case-progress

case-progress - Case progress and status management (case-handling progress ledger)

Status: v0.1.0 skeleton. For the design source of truth, see the consuming project SuitAgent docs/case-dashboard与数据真值方案.md(v1.5, decisions #045/#046).

Responsibilities

Function	Form
Status writes	scripts/case_store.py CLI: show / list / add-task / set-status / add-deadline / set-stage / set-fields / validate / migrate / render (audit / report deferred to M6)
View rendering	render <短码>: generates 案件视图.md + 案件视图.html(00 directory, one-page derived view, do not edit by hand);each write automatically refreshes existing view files— stays fresh without hooks
Session contract	references/contract.md: Agent session starts show loads state + reads narrative documents via context pointers; on finish, writes back through the CLI,manual yaml editing prohibited
List write pitfall (set-fields)	set-fields oflists are whole replacement rather than append: passing {"任务": [新增一条]} will wipe out all original entries in that list. Schema validation (each line requires source) cannot catch "failing to pass the remaining entries"—if a new entry happens to carry a valid source, validation passes directly and the data has already been cleared.Before appending one entry you must first show/read out the full list, and pass the original entries + the new entry together; after writing, immediately recheck the entry count and key ids, and restore from backup if abnormal
Project management	/progress commands: natural-language-driven task/deadline/stage operations; explicit operations are routed directly to this CLI; complex semantics are transferred to the "workflow wrap-up status synchronization" process below
Data contract	references/schema.md: case.yaml v4.0 field dictionary—the sole authoritative version, other skills only reference it and do not copy it
Monitoring reconciliation	M6 (long-term): audit subcommand + hooks attachment points (PostToolUse bookkeeping / Stop·SubagentStop closing / SessionStart early warning)

Development red lines

1. Path resolution must not use __file__.resolve()(symlink installation will penetrate back into this repository): for the project root, use upward discovery from cwd (find an ancestor containing a case directory starting with 6 digits) or --root / SUITAGENT_ROOT specification.
2. Single write implementation: all writes to case.yaml must go through this engine—schema validation → line-level source protection (never overwrite source: user lines; "closed case" is only manually marked, never automatically inferred) → flock → temporary file + os.replace atomic replacement.
3. Schema sole authority: the field dictionary is maintained only in this skill; consumers such as case-dashboard reference the version number and do not copy the content.
4. Runtime data must never enter the skill directory(this repository is public): case.yaml,.audit.jsonl , etc. all go into the consuming project's case directory.
5. Invocation method: Other skills (such as the case-dashboard server) call this CLI via subprocess; cross-skill Python import is prohibited.
6. Counting the number of entries in a yaml list must slice by top-level key: in case.yaml, besides 案件时间线 there are also 法定期限、开庭与听证、工时记录 and multiple other date lists; counting across lists with grep -c "^- 日期: " yields a number unrelated to the target list (once "no data lost" was misjudged as "40+ entries lost", and it was then used to cover up 7 genuinely lost entries). Use case_store.py show <短码> or slice from the top-level key to the next non-indented line. Before writing, cp case.yaml /tmp/case.yaml.bak to keep a backup, allowing one-click rollback.

Directory structure

scripts/      case_store.py（CLI + 库 + audit）—— M2 实现
references/   schema.md（v4.0 字段字典）、contract.md（会话契约）—— M3a 起充实

Workflow wrap-up status sync (executed directly by the main Agent, skill-to-skill collaboration, no subagent dispatch)

For the consuming project's composite workflows (seven scenarios such as defendant response, evidence cross-examination, etc.), after the Reporter, or when the user says "sync case progress / update the case based on new documents",the main Agent executes directly according to the following process：

1. Load state：show <案件短码>
2. Inventory outputs: list the new files in the 02–11 directories involved in this workflow; read the key files (judgment/ summons/ new documents) to extract event elements
3. Mapping judgment: output → semantic change (new task / task completed / new deadline / stage advancement / timeline event)
4. CLI write-back: add-task / set-status / add-deadline / set-stage (AI identity, without --actor user)
5. Work-hour recording (mandatory)：log-work <短码> <时长|auto|?> <本次工作摘要> [--task] [--file 产出文书] [--type]——Every piece of work completed with AI collaboration (document drafting/ research/ analysis/ organizing) is recorded as it is completed: content and associated documents/ tasks are carried automatically.Three states of duration: the user's explicitly stated actual value takes priority (e.g., "spent an afternoon" → 4h); if not specified, pass auto——take the reference default by work type (2h for court appearance as the floor)(reference defaults: document·research 1h, verification·communication·organizing 0.5h, court appearance 2h as the practical floor; the type can be inferred from the content—AI generation is fast but the real cost of lawyer verification/ revision is included, and can be adjusted up or down according to the actual situation);? is used only when the user explicitly does not want an estimate
6. Validation and reporting：validate after passing, output the change list and items to be confirmed

Execution discipline: never manually modify yaml; deadlines must include the start date and legal basis, and uncertain ones are listed as items to be confirmed rather than fabricated; manual override protection (source=user rows are only flagged, not rewritten; closed cases are never set; locked stages are not rewritten); output a brief Markdown change list, and produce no files.

Relationship with the surrounding ecosystem (case lifecycle relay)

• new-case: creates the case directory and the initial case.yaml (v4.0 template), the data production upstream of this skill
• case-dashboard: view layer, read and written through this CLI, only consumes and does not write separately
• Main Agent (skill-to-skill collaboration): the status sync at workflow wrap-up is executed directly by the main Agent according to the above process,without relying on a subagent(architectural decision: skill collaboration is primary; the consuming project may later phase out subagent dispatch entirely)
• DataRules.md(consuming project .claude/rules/): the rules layer of the session contract, pointing to this skill

Roadmap

M2 write engine → M3a v4.0 data model → M3b lightweight write-back entry → M4 legacy migration → M6 hooks monitoring (long-term). See TASKS.md and the consuming project plan for details.