Mission Spec

Own requirement discussion and the draft -> approved spec transition. Do not implement the work and do not write a separate implementation plan.

Declare: 使用 mission-spec skill，讨论并生成可批准的 canonical spec。

Workflow

1. Read the request and the relevant repository context.
2. If lite-arch-recall is installed, run it only before a genuine architecture-bearing decision (hard-to-reverse system boundary, data ownership, protocol, persistence, or cross-module control-flow choice) against applicable docs/adr/ records. Ordinary model/module iteration, hyperparameter changes, experiment setup, bug fixes, and CSV bookkeeping do not trigger ADR recall.
3. Ask one question at a time only while a material goal, constraint, scope boundary, or acceptance condition remains unresolved.
4. Present alternatives only when real alternatives exist. Recommend one and state concrete tradeoffs.
5. Once the design is determined, write a draft to docs/specs/<YYYY-MM-DD>-<topic>.md. Register its task pointer using the lifecycle command below so preparation survives compaction.
6. Run python scripts/validate_spec.py <spec> --allow-uncommitted-approved and fix every error.
7. Use explicit approval of the exact draft, or an existing explicit user delegation that covers this task and its decisions. For delegated approval, record the user's source reference and scope, set approval_mode: delegated and approval_source, and continue without asking again. Do not infer delegation from positive discussion or permission for another task.
8. After approval, set status: approved and add the current RFC 3339 approved_at timestamp with timezone. Do not change the approved body in the same edit.
9. For a genuine architecture-bearing decision, run installed lite-arch and print its required three-line decision block before creating, amending, superseding, or skipping an ADR. Do not create ADRs for ordinary scientific iterations or routine implementation choices.
10. Commit the approved spec and any draft ADR created by the optional gate before execution. Then run validate_spec.py without the allow flag to prove the approved file is committed and unchanged from HEAD.
11. Route the committed spec to mission-approved-doc, unless the user explicitly chooses ordinary direct implementation. When presenting the completed artifacts to the user, always print the raw CSV file path and the mission issues/<stem>/<stem>.csv command in an isolated code block (never as a markdown hyperlink like [任务 CSV](...)) so the user can easily copy and paste it into an execution session.

Canonical format

Use exactly one scalar frontmatter block:

---
mission: spec
status: draft
created: YYYY-MM-DD
---

After approval:

---
mission: spec
status: approved
created: YYYY-MM-DD
approved_at: YYYY-MM-DDTHH:MM:SS+08:00
---

Required sections:

• Goal
• Scope
• Design
• Acceptance Criteria

Add Non-goals, Alternatives, Compatibility, Security, Rollout, or Rollback only when they carry real information.

The validator accepts unique scalar fields mission, status, created, approved_at, plus optional approval_mode and approval_source. Existing four-field specs remain valid. approval_mode is explicit (default) or delegated; delegated approval requires a nonempty source reference and a description of its scope in the body. Nested values, arrays, aliases, tags, duplicate keys, invalid dates and extra frontmatter blocks remain invalid.

Approval integrity

• Explicit approval applies to the exact draft the user saw. Delegation applies only within the user's stated task and scope.
• A later content change needs renewed approval. If existing delegation covers that change, revalidate and record the new approved_at under the same source; otherwise return to draft and request approval for the concrete changed content.
• A later session may trust an approved spec only when validate_spec.py confirms that it exists in HEAD and the working copy is unchanged.
• Never infer approval from positive discussion, implementation permission for another artifact, or a previous version of the document.

Recoverable task pointer

After creating the draft, run from the project root:

python .agents/harness/workflow/mission_state.py register --task-id <SpecID> --spec docs/specs/<file>.md --source-ref <user-source-ref>

When the user changes task boundaries, add --replaces <old-task-id> --reason <reason> to register the new pointer and retire the old task in one write. Do not use replacement for intentionally parallel tasks. issues/.missions.json records task identity and lifecycle, not CSV row progress or scientific outcomes. This local control file is Git-ignored so code branch changes cannot restore an old active pointer. Keep it with the current workspace when transferring an interrupted task.

Writing boundary

Run humanizer-zh on prose before presenting or committing the spec. Do not let it rewrite frontmatter, code identifiers, paths, commands, dates, or machine-checked fields.

mission-spec produces and approves the spec. mission-approved-doc maps an approved spec into execution artifacts. mission-csv-execute owns execution state. Keep those responsibilities separate.