Story Done

The closing gate of the per-story loop. Reads the story, audits each acceptance criterion against the actual implementation, ensures evidence is in place, prompts a code review if one is missing, then transitions Status to Complete and points the user at the next ready story.

Phase 1: Resolve the Story

If a path is supplied, use it. Otherwise consult production/session-state/active.md for an active story, or glob production/epics/**/*.md and ask the user which one.

Stop and warn if the story file does not exist.

Phase 2: Read Story + Implementation Files

Pull these from the story:

• Story ID, Title, Layer, Type
• TR-ID and Governing ADR
• Acceptance Criteria (every checkbox)
• Implementation Notes
• Test Evidence path
• Out of Scope list
• Status (must be In Progress or In Review; if already Complete, ask the user whether to re-verify)

Glob the most recent edits to src/ to find files modified for this story. Cross-reference with the session state file. Read each modified file.

If a Test Evidence path is specified, read the test file. If absent for a Logic or Integration story, this is a hard blocker (see Phase 5).

Phase 3: Verify Each Acceptance Criterion

Walk every AC checkbox in order. For each:

Mark each AC one of: VERIFIED, DEFERRED (Visual/Feel awaiting user confirmation), MISSING EVIDENCE, or FAILED.

Phase 4: Check for Deviations

• Out of Scope check: list every modified file. Flag any file outside the Out of Scope boundary as a Deviation. Ask the user to confirm whether it was intentional.
• ADR check: re-read the governing ADR's Implementation Guidelines. Spot any obvious divergence in the diff and surface it.
• Manifest check: confirm the story's Manifest Version stamp still matches the manifest header date.

Phase 5: Code Review Gate

Look for evidence of /code-review having run on the changed files. Look in the session state file, conversation transcript, or any cached review artifact.

If no review is recorded, use AskUserQuestion:

• [A] Run /code-review now and resume /story-done after
• [B] Skip the review — accept the risk (NOT recommended)
• [C] Cancel — I'll come back later

If [A], run /code-review against the modified files and incorporate the verdict into Phase 6.

Phase 6: Build the Verdict

Compose:

## Story Closing Review: [Story Title] ([Story ID])

### AC Verification
- [x] [AC1 text] — VERIFIED — covered by [test or evidence]
- [x] [AC2 text] — VERIFIED — implemented in [file:function]
- [ ] [AC3 text] — DEFERRED — awaiting Visual/Feel sign-off
- [ ] [AC4 text] — MISSING EVIDENCE — [what's missing]

### Deviations
[None | list with rationale and user confirmation]

### Code Review
[Reference + verdict, or "Not run".]

### Test Evidence
[Path | "Not required for Type: [type]"]

### Verdict: [COMPLETE | NEEDS FIXES | BLOCKED]

Verdict rules:

• COMPLETE — every AC is VERIFIED or has user-approved DEFERRED status, no MISSING EVIDENCE, code review APPROVED (or APPROVED WITH SUGGESTIONS), no unresolved out-of-scope changes.
• NEEDS FIXES — one or more ACs FAILED or have MISSING EVIDENCE that the user wants to resolve.
• BLOCKED — fundamental gap (no test for Logic story, ADR violation, scope blowout the user has not acknowledged).

Phase 7: Update Story Status

If verdict is COMPLETE, ask the user:

"May I update [story path] Status to Complete and stamp the Closed date?"

On approval, edit the story file:

• Set Status: Complete
• Add Closed: [today's date]

• Append a closing note section if there were Deviations:

  ## Closing Notes
  - [Deviation summary]
  - Code review verdict: [verdict]
  - Test evidence: [path]

Append to production/session-state/active.md:

## Story Closed — [date]
- [story path] -> Complete
- ACs verified: [N/M]
- Code review: [verdict]
- Next: [next ready story slug]

If verdict is NEEDS FIXES or BLOCKED, leave the story Status untouched and write a ## Open Issues section into the story file (with user approval) listing what remains.

Phase 8: Surface the Next Story

Read the active sprint file (production/sprints/[current-sprint].md or the parent epic). Find the next story whose Status is Ready and whose Dependencies are all Complete.

Render:

Next ready story: [title] ([path])
- Type: [type]
- Estimated effort: [estimate from story file]
- Run /story-readiness [path] to validate, then /dev-story [path] to start.

If no Ready story exists in the sprint, suggest /sprint-status to inspect sprint state, or /create-stories [next-epic] if the epic is still open.

Quality Gates / PASS-FAIL

• COMPLETE — story passes every gate; Status flipped, session state updated, next story surfaced.
• NEEDS FIXES — at least one AC unverified; story stays open; specific remaining work is documented.
• BLOCKED — fundamental gap; story stays open; user is told exactly which skill to run next.

Examples

Example 1 — A formula change story (Logic): Reads tests, confirms the unit test file exists and tests the AC's boundary values, runs /code-review, both pass. Updates Status to Complete. Surfaces the next Ready story.

Example 2 — A new onboarding screen (UI): No automated test required. Asks the user to walk through the flow on a device, requires a screenshot in production/qa/evidence/. The user confirms two of three ACs and reports a small layout regression on the third. Verdict: NEEDS FIXES. Story stays open with an Open Issues note.