Phase checkpoints and a Decisions ledger for plan specs

Context

The story behind this plan — what prompted the work and why it matters now.

Implementation plans that exceed roughly ten steps consume more context than one session can hold. The repo already reaches this conclusion: guidelines/right-sizing.md line 35 tells the author that a plan needing more than ten steps "is probably two plans — split it". It then offers no mechanism to split with. A grep of the whole plugin for parent, child, and subplan concepts returns nothing.

Two capabilities are missing, and only one of them is about parallelism. The workflow prompt already fans out across subagents, which helps when slices are independent — migrations, renames, per-file sweeps. Context exhaustion bites hardest on long sequential plans, where step seven depends on decisions made in step two, and there fan-out does nothing. The fix for that shape is checkpointing.

Most of the machinery already exists. build/SKILL.md line 152 resumes from the first unmarked step, so implement-some-steps, clear the context, re-run already works by accident. What is missing is a declared safe stopping point and a record of decisions already settled. The ## Completion Report section is a gap ledger, not a decision ledger, so a resumed session re-derives — or contradicts — choices the first session made.

The format is bidirectional, and that is the main cost driver. buildDigest is documented as the exact inverse of parseSpecMarkdown, and extractSections derives a spec back out of rendered HTML for legacy HTML-only plans. A new grouping level therefore has to be carried at four sites — parse, render, extract-from-DOM, re-emit — with test-build-plan-html.mjs and test-extract-plan-spec.mjs guarding fidelity. Anything carried at fewer than four sites is a silent data loss rather than a missing feature.

One hazard is already latent. parseSpecMarkdown splits the Steps chunk with split(/\n(?=\d+\.\s)/) and folds each piece to a single line with inline(), so a ### Phase: heading placed between steps two and three is appended to step two's Verify: text with no parse error at all. Phases are actively unsafe to author until step 1 of this plan lands, which is also why this plan does not use phase headings itself.

Alternatives weighed. A phases: frontmatter key holding step ranges (phases: 1-3 Setup, 4-6 Build) would cost almost nothing — the frontmatter parser already keeps arbitrary keys and the digest round trip could not break — but inserting a step silently shifts every later range, so the grouping rots in exactly the situation it is meant to survive. Headings are self-maintaining and were chosen for that reason. Full parent and child plan files were also considered and deliberately deferred: they additionally solve authoring size, but they force a position on progress rollup, gallery nesting, and archiving before phases have been used even once. Phase boundaries are designed here to be extractable into child files later.

The remaining decisions, recorded here as well as in this plan's own ## Decisions section because the renderer skips that section until step 5 lands and the gallery, the extractor, and plan reviewers all read the rendered HTML. A phase name renders as an <h3> inside a data-phase wrapper, so phases join the document outline for screen-reader navigation while the attribute carries extraction. Phases group the same flat step numbering, so adding them to an in-progress plan keeps every existing [x] marker valid and build still resumes at the first unmarked step rather than at a phase start. The boundary offers to compact the session rather than only stopping, and build prints the /compact command rather than running it, since compaction is a user-typed CLI built-in and not a callable tool — safe mid-plan only because durable state lives in the spec rather than the conversation. finalize-plan is in scope because build/SKILL.md line 303 requires the two skills' completion rules to stay consistent. The checkpoint contract in both skills is guarded by a prose grep in the style of test-exitplanmode-guard.sh, which catches deletion of the contract rather than proving runtime behaviour.

The renderer has two homes, and that shaped the step order. tests/plugins/test-build-plan-html.mjs line 837 asserts the three files under kit/plugins/plan-agent/scripts/ are byte-identical to their repo-root counterparts under scripts/, so every renderer edit lands at the root and is re-copied into the bundle before any test runs. The extractor is not mirrored at all — extract-plan-spec.mjs ships only at the repo root.

workflow: never is set deliberately. Four of the twelve steps — 1, 2, 3, and 5 — are ordered edits to a single file, scripts/lib/plan-spec.mjs, so subagents fanning out would conflict on it. The renderer's own heuristic counts files and directories and would otherwise license fan-out this plan cannot use.