stage-spec

Stage Spec (stage spec authoring/backfilling)

Positioning

Upgrade the design document's stage plan into amachine-verifiable stage contract(spec-kit mode): one per stage docs/design/stage-specs/S{N}.md, for stage-gate to execute item by item. A spec is astage contract (DoD/grid/boundaries), not a task breakdown—task breakdown is left to writing-plans。

When to use

• Before a stage starts: "write S{N} spec", "backfill stage spec", "S2 finalize"
• After design §6 (phased implementation plan) changes—the specs of affected stages must be synced

Inputs

• Design document:docs/design/intent-confirmation-domain-design.md(§6 stage rows + related §3/§4 behavior specs + §8 contracts)
• Template:docs/design/stage-specs/README.md(template + maintenance rules)
• Existing assets:docs/decisions/(stage decision ADRs—spec cites numbers),docs/tests/coverage-matrix.md(from S2)

Template (five sections—no additions or deletions)

# Stage S{N} Spec（{阶段名}）

> 来源：docs/design/intent-confirmation-domain-design.md §6；开工日期：YYYY-MM-DD

## DoD（机器可验证断言——stage-gate 逐条执行）

## TDD 网格（本阶段新增功能——spec-first + test-first）

## 产出物

## 边界（不做——防蔓延）

DoD assertion writing rules (acceptance core)

1. Each item can be directly executed by stage-gate—either a complete command (npx vitest run, dual tsc, playwright), or a verifiable behavior assertion + the test file path that carries it (tests/unit/xxx.test.ts contract case list).
2. No prose-style "done"—"complete XX refactor" is not acceptable; "XX produces <output> for <input> (contract cases: a/b/c)" is.
3. Command references are not copied—DoD directly references existing gate commands, does not copy gate output (prevent dual sources).
4. Counts give lower bounds—new case assertions write "≥N items" and point back to the TDD grid; L3 regression writes the expected total (e.g. 31/31).
5. Status-type assertions are explicit—audit status (all open items from the previous stage fixed/recorded), coverage matrix (first version produced/updated), decision log sync, push + CI green—listed item by item, not merged into one sentence "wrap-up complete".
6. Nested sub-assertions item by item—multiple verification points under behavior acceptance are split into sub- - [ ], executed item by item by stage-gate.

TDD grid (spec-first + test-first)

| Feature | Spec assertion (write first—source §4/§3.3) | Failing test (red) | Implementation (green) | Refactor |

• One row per feature newly added in this stage; spec assertions mark the source subsection (§4/§3.3/§8.x);
• Failing tests givespecific test file names + contract case type list; the refactor column writes the semantic comparison/deduplication against the old implementation.

Deliverables

• File/module/test list—checkable, serving as the anchor points for DoD assertions.
• Synced with the actions slot of the project handoff storage (.handoff/): after the spec is finalized, have that stage rowpoint to this spec's path （docs/design/stage-specs/S{N}.md), reference only, do not copy (prevent dual sources); if that row does not yet exist, register it first then point. The write entry and command form use the write-slot table of project-handoff as thesingle authoritative surface— this document only defines the contract that "the stage row must point to the spec", and does not copy its parameter surface (that copy will rot first).

Boundaries (do not do—prevent sprawl)

• One per line, explicit exclusions (e.g., "XX belongs to S{N+1}"); boundaries come from design §6 or stage rulings (ruling → ADR → spec reference).

Acceptance

• Each DoD item can be directly executed by stage-gate (command or test file path, no prose-style statements)
• No unverifiable statements like "complete XX"; count assertions have lower bounds/expected values
• All five sections present; source/start date in the header; TDD grid covers all new functionality
• Synced with the .handoff/ actions slot (that stage's row carries the spec path; for the write entry point see the project-handoff write-slot table delegated in the "Deliverables" section)

Boundaries (division of labor)

Adjacent skills	Division of labor
writing-plans	stage-spec = stage contract (DoD/grid/boundaries, executed by stage-gate); writing-plans = general task decomposition (bite-size steps + code + verification). Finalize the spec first, then decompose tasks into plans as needed
stage-gate	The spec's consumer—once the spec is written it is executed by the gate; DoD that fails executability = spec rework
decision-log	Stage rulings (e.g., DoD changes) → ADR; the spec references the ADR number without copying its content
project-handoff	Handoff storage'stool side：.handoff/ structure and write-command parameter surface are entirely defined by it; the steps in this document only register references as required by the contract; if it changes shape, this document is not updated in return

Completion criteria

• docs/design/stage-specs/S{N}.md Created/updated (all five sections present)
• Every DoD assertion is executable (command or test path), no prose-style "complete"
• TDD grid comes first—spec assertions are marked with sources, failing tests are given with file names and case lists
• .handoff/ actions slot synced (references spec)
• DoD changes (if any) recorded by ADR

Anti-patterns

• Writing prose assertions like "complete XX"—the gate cannot execute them
• Copying gate output/test output into the spec (dual source)
• DoD disconnected from the TDD grid (grid functionality has no corresponding DoD assertion)
• Missing boundaries section—no one claims the scope-creep risk
• After the spec is finalized, not writing back to .handoff/(the next session does not know the contract exists)