feat(checkpoint-iterate): add last-mile iteration session with attempt ledger

[desek]

Adds checkpoint-iterate, a skill for the last mile: the iteration that happens after an implementation lands and before it is actually right. Net diff against main is 14 files, +1506/-10.

The problem

A Change Request describes an implementation before it exists, so in a complex codebase what gets delivered is approximately right rather than exactly right. Closing that gap is an interactive loop — the user names what to try, the agent changes the code and reports evidence, the user decides whether it survives.

That loop currently leaves almost no trace, and it loses the wrong half. A checkpoint commit records what was kept; the approaches tried and abandoned before it leave nothing behind, anywhere. Those discards are the higher-value observations — knowing an approach does not work here saves the next implementer an afternoon. The existing distillation workflow reads commit history, so it can only ever learn from successes.

What this adds

A session, opened by explicit user invocation against an already-implemented CR, that maintains a ledger at docs/cr/CR-XXXX-iterate.md.

Roles are fixed. The user names what to try and renders the verdict. The agent makes the change, runs the checks, reports the evidence, writes the ledger entry, and commits — it is the party present at every attempt and already writing to the repository, so the recording is a side effect of work it was doing anyway. The user is never asked to keep a notebook alongside the work. The agent records the verdict verbatim and never infers one, and must report evidence before asking for it.

Dispositions are a closed set — kept, discarded, partially-kept — with the partial case required to state which portion survived and which was reverted. Discarded entries are never deleted; retaining them is the entire point.

Entries are written when an attempt starts, not when it finishes. An entry is open until judged, then settled. This is what makes an interrupted session recoverable: a fresh agent can distinguish an attempt that was abandoned from one that was never judged, rather than folding unjudged work into the next attempt.

Commit convention

Session commits reuse the checkpoint type with a scoped identifier, rather than introducing a parallel one:

Subject	Produced by
checkpoint(CR-XXXX):	Core agentic implementation workflow
checkpoint(CR-XXXX-iterate):	An iteration session

Reusing the type keeps session work visible to context recovery — correct, since iteration work is exactly what a later session needs. The -iterate suffix does the separating, so either view is one query away.

Surviving context loss and running in parallel

Re-hydration is one user action — the same invocation that opened the session. The ledger is on disk and is the sole durable state, so the agent reconstructs everything itself: reads the CR and every settled entry, reads the checkpoint commits, reconciles uncommitted changes against any open entry, and settles it before starting new work. It must not re-propose an approach a discarded entry already eliminated without saying so.

Concurrent sessions require separate Git worktrees. The hazard is not the ledgers, which are distinct files — it is that the existing checkpoint workflow stages with git add -A, so two sessions sharing a working tree would each sweep the other's in-flight changes into their own commits, misattributing work and corrupting both ledgers. Worktree isolation is the primary defence; scoped staging bounds the damage if it is ignored; and the ledger records the tree it was opened in, so a cross-tree resume is detected rather than proceeding silently.

Also

WORKFLOW.md gains an optional iteration stage between finalize and push, with both Mermaid diagrams updated. The skill is registered as a releasable component and listed in the README.

Testing

bats -r tests/ — 59/59 passing, up from 25. Thirty-four new tests: 22 covering the skill's structure, registration, and its load-bearing workflow behaviours, 12 covering the ledger template.

Validation traced all 42 functional requirements, 7 non-functional requirements, and 26 acceptance criteria to the implementation with file:line evidence: FAIL=0, PARTIAL=0, GAP=0. Report included at docs/cr/CR-0015-validation-report.md.

Review notes

Two things worth surfacing rather than leaving to be discovered:

The closing step depends on a workflow this repo does not ship. Distillation hands the ledger to /checkpoint-distill, which exists as an installed skill but is not part of this repository. The skill documents it as an external prerequisite. A consumer installing checkpoint-iterate on its own gets a skill whose final step needs something they may not have — worth deciding whether to ship it from here.

A presentational tension the validator recorded rather than smoothed over. The happy-path loop in SKILL.md lists the ledger write as step 5, after the verdict, while the open-at-start rule lives verbatim in the bundled template. The requirement is genuinely satisfied, but the two read against each other. Noted in the report's Gaps section as optional cleanup.

Refs #24