sdlc-finish

name	sdlc-finish
description	End-of-work discipline for project repos: hostile validation of the diff before declaring work done, and handoff (settle the tree, update state.md, append the journal) before ending a session with changes. Triggered by the claim, not the diff — use before any done/ship verdict, even for small edits.

sdlc-finish — validate, then hand off

Two objectives. The first earns the word "done"; the second makes the project resumable by a session that remembers nothing of this one.

Objective 1 — Validate before saying "done"

You wrote the change, which makes you its least suspicious reader. The objective is to switch sides: re-read the work as a reviewer who assumes it is broken, and let the evidence — not the memory of writing it — carry the claim. Scale the depth to the blast radius of the claim, not the size of the diff: a done or ship verdict is inherited unchecked by everything downstream, so a one-line edit under that verdict still earns the full hostile read. Validation is done when:

• You have re-read the full diff cold — run bash ../sdlc-core/scripts/diff-inventory.sh for the complete inventory (status, diffs, untracked, stashes), then read the changes themselves, not a paraphrase from memory. Read looking for the bug, the scope creep, the file you forgot you touched — and for comments the code didn't earn (narration, prescriptive scaffolding, change markers; STANDARD §3): the inventory lists every added comment line, and each one you keep must state a why the code can't.
• Every success criterion has evidence — a command you ran this session, output quoted, not paraphrased. "Tests pass" without the run in front of you is a claim, not evidence. Compare against the baseline you took at orientation: a suite that was already failing proves nothing about your change.
• The must-NOT-change list is confirmed, the same way — by running, not by inspection.
• The verification baseline ran this session — the Verification path commands in state.md, re-run now and re-stamped with today's date; the strict state check refuses a stale stamp. If a command genuinely cannot run here, mark it not re-run (today's date) and say so in the report — a disclosed gap is honest; an implied pass on an unrun suite is the false-SHIP failure this library exists to stop.
• The evidence report (format: STANDARD §7) states what was verified at which rung of the ladder, and — honestly — what was not.

If a criterion can't be checked with what exists, say so explicitly rather than substituting a weaker check that can.

Objective 2 — Hand off before stopping

The next session starts with zero memory of this conversation. Handoff is done when:

• The tree is settled — committed, or deliberately left dirty with the reason stated in state.md. No silent half-states.
• A pull request is self-contained — when work ships through a PR, its implementation, verification evidence, state.md, and journal.md settle on the same pull request before final CI and merge. If the handoff changes while the PR is open, update that branch and rerun its required checks. Never open a follow-up AI-SDLC-only pull request merely to close or repair the original handoff. Record post-merge readback in the final report; only a newly discovered substantive defect starts new work.
• .ai-sdlc/state.md is the current truth — goals, decisions, next steps, and known landmines as they stand now, not as they stood when the session started. Format: ../sdlc-core/references/STATE-SPEC.md. Stamp updated: with today's date every time, even for a small change — a stale date understates how current the file is. When a Next step depends on something outside this repo (a PR, a deploy, another agent's work), name that dependency explicitly so the next session re-verifies it instead of trusting a claim that may have moved on.
• Next is settled — use the Xit profile from STATE-SPEC.md; summarize terminal [x]/[~] items in the journal and remove them, leaving only unresolved work. A task becomes [x] only after its #verify proof ran.
• The journal has an entry — what changed, why, and what a future session should distrust, in a few terse bullets, not a narrative.
• bash ../sdlc-core/scripts/check-state.sh --strict exits 0.

End the final response with the STANDARD §7 evidence report, keeping each field at the start of its line: What changed:, What was verified:, and Remaining risk:. The Stop hook recognizes that exact three-field contract and runs the strict state check before allowing the session to end.

The acid test: a stranger given only state.md and the repo reaches the same understanding you have right now. If they'd have to rediscover something the hard way, it isn't written down yet.

Pointers

• ../sdlc-core/references/STANDARD.md — verification ladder §4, evidence report format §7
• ../sdlc-core/references/STATE-SPEC.md — state.md / journal format
• ../sdlc-core/scripts/ — diff-inventory.sh, check-state.sh, compact-journal.sh