I1: replace the dispatcher's bespoke repairs with a manifest, gated against the canonical field text

[bdelanghe]

Closes #91. Implements I1 of docs/session-capability-invariants.md, which moves from Partial to Enforced.

The gate, not the refactor

ensureMcpRegistered (#84) and syncStopHook (#88) are now entries in one MANIFEST the dispatcher drives with a single loop. That half fixes no live bug.

The half that pays: parseSteps in gen-bootstrap-pin.mjs — which already parsed the canonical setup-script block for PIN and the SUM_* lines, verified before designing around it — now also enumerates that field's steps, and .claude/bootstrap-steps.test.mjs asserts each maps to a manifest entry or an IRREDUCIBLE declaration with a reason. A step added to the field with no fallback now fails CI instead of going unnoticed until it breaks in production, which is how #85 happened.

The parse finds exactly the four steps I1 names:

step	covered by
settings.json heredoc	IRREDUCIBLE — writes the pointer that invokes the dispatcher; a fallback would run before itself
CLAUDE_SESSION_ROOT= prefix	IRREDUCIBLE — being wrong about the session root is the state it corrects
node register-mcp.mjs	MANIFEST — predicate over JSON, repair by merging into ~/.claude.json
cp stop-hook-git-check.sh	MANIFEST — byte compare, repair by copying

What was preserved deliberately

• The asymmetry. The comparison is per-entry. The Stop hook compares bytes because its failure was a wrong file (3262 stock against 5458), so a presence check reports health on a broken hook; MCP compares a predicate over JSON because ~/.claude.json holds much more than any repo declares. Forcing one comparison on both reinstates a failure that has already happened here.
• The comments. This file's value is disproportionately in its scar tissue — homedir() being right for the settings dir and wrong for the session root, the stock hook crying wolf after every squash merge, "absent" being a real case because the bootstrap verifies each fetched file independently. Those moved onto the entries they explain rather than being deleted; they are why the two entries differ.
• Irreducible is declared, not inferred from absence. An omission and a decision both present as silence, and the test requires a reason, not a bare flag.
• The parse refuses what it cannot classify. An unknown verb throws rather than dropping out of the enumeration — a step silently missing from the gate is the exact invisibility this removes.
• The idiom. bootstrap-steps.test.mjs asserts on parseSteps rather than reimplementing it, the same reason bootstrap-pin.test.mjs asserts on its generator.

Verification

• All existing suites pass unchanged (109 pass across .claude/, up from 99).
• The negative test, which is the honest one: adding a cp step to the canonical text with no manifest entry takes the suite to 98 pass / 1 fail, naming the artifact and quoting the offending line. Two mutants of the loop (needsRepair ignoring repairable: false; repairing unconditionally) are both caught.
• Ran end to end against a fake two-repo session root: replaced a stock Stop hook byte-for-byte, registered an empty MCP config, and emitted the drift context block only when registration could not be repaired — a repaired session still pays nothing in context.

One precision on the issue's wording: node --test .claude/ does not resolve a dot-prefixed directory on Node 22 (Cannot find module), so the suite form is node --test '.claude/*.test.mjs'. CI enumerates the files individually and now includes the new one.

Note on the pin

session-start-dispatch.mjs is a fetched file, so FRESHNESS is red on this branch by construction — PIN cannot name a merge commit that does not exist. It is reported as a diagnostic on pull_request and org-defaults.yml opens the bump PR on merge, so the pin is deliberately not hand-bumped here. INTEGRITY is green.

---

Generated by Claude Code