I1: replace the dispatcher's bespoke repair functions with a manifest, and gate it against the canonical field text

[bdelanghe]

Implements I1 of docs/session-capability-invariants.md — every step of the canonical bootstrap has a fallback, or is declared irreducible. Currently graded Partial: two of four steps self-heal.

The problem

ensureMcpRegistered (#84) and syncStopHook (#88) are two bespoke implementations of one idea, written a few hours apart. A third would be a third. Worse, nothing relates the setup-script field's contents to the dispatcher's coverage — that mapping exists only as prose in .claude/README.md, so a step added to the field without a fallback is invisible until it goes missing in production, which is how #85 happened.

Shape

One manifest the dispatcher interprets. Per entry: artifact, canonical source, install target, comparison (bytes or predicate), repair action, failure wording. The dispatcher becomes a loop; mcpDriftContext generalises to "entries that could not be repaired".

The two existing repairs are deliberately not symmetric today, and the manifest has to keep both:

• MCP: compare declared-vs-registered JSON, repair by merging into ~/.claude.json.
• Stop hook: compare bytes, repair by copying. Bytes matter — the failure was a wrong file (3262 stock vs 5458), so a presence check reports health.

The gate is the point

gen-bootstrap-pin.mjs already parses the canonical setup-script text in .claude/README.md to extract PIN and the SUM_* lines. Extend that parse to enumerate the field's steps and assert each maps to a manifest entry or an explicit irreducible: declaration with a reason.

Then adding a line to the field without a fallback fails a test — which is the gap this whole thread is about.

Follow the existing idiom: bootstrap-pin.test.mjs asserts on the generator rather than reimplementing its logic, specifically so the two cannot drift. The manifest gate should do the same.

Done when

• The dispatcher contains no per-artifact repair code, only the manifest and the loop.
• Both existing repairs still pass their current tests, unchanged in behaviour.
• A step added to the canonical text with no manifest entry fails node --test .claude/.
• The two irreducible steps (settings.json write, CLAUDE_SESSION_ROOT prefix) are declared as such with reasons, not merely absent.

Note

This is a refactor plus a gate; it fixes no live bug. Its value is that the next #85 is caught by CI instead of by reading /tmp/env-manager.log.

[bdelanghe]

Notes for whoever picks this up

Premise re-verified 2026-08-03 against main (.claude/session-start-dispatch.mjs, blob 869bb1e): both bespoke repairs are still there, called back-to-back at the top of main() — ensureMcpRegistered() and syncStopHook(). Nothing has moved on this since it was filed.

The gate is the deliverable, not the refactor

The manifest alone fixes no live bug. What has value is that a step added to the canonical setup-script text in .claude/README.md with no fallback starts failing node --test .claude/ instead of going unnoticed until it breaks in production — which is how #85 happened. If you find yourself shipping the loop without the gate, you've built the half that doesn't pay.

Four things to preserve or check

1. The two repairs are deliberately asymmetric and the manifest must keep both. MCP: compare declared-vs-registered JSON, repair by merging into ~/.claude.json. Stop hook: compare bytes (source.equals(installed)), repair by copying. Bytes matter — the failure was a wrong file (3262 stock vs 5458), so a presence check reports health on a broken hook.

2. Verify the gen-bootstrap-pin.mjs claim before designing around it. The issue body says it already parses the canonical text for PIN and the SUM_* lines, and proposes extending that parse to enumerate the field's steps. That is the issue author's claim, not something confirmed in this pass.

3. Follow the existing idiom. bootstrap-pin.test.mjs asserts on the generator rather than reimplementing its logic, specifically so the two cannot drift. The manifest gate should do the same.

4. The two irreducible steps must be declared, not merely absent. The settings.json write and the CLAUDE_SESSION_ROOT prefix need an explicit irreducible: with a reason. Otherwise absence-as-omission and absence-as-decision stay indistinguishable, which is the whole gap.

The main risk

This file's value is disproportionately in its comments. They encode failures that actually happened — homedir() resolving to /root while repos are in /home/user, with the dispatcher exiting 0 on "nothing to do"; the stock Stop hook crying wolf after every squash merge; the "absent" case being real rather than a bug because the bootstrap verifies each fetched file independently. A naive collapse into a data table moves the repair logic into the manifest and leaves that reasoning homeless. Route those comments to their manifest entries — don't delete them. The file is trustworthy because it explains its own scar tissue.

Two notes on working it

Attach bounded-systems/.github as the session's project directory, or at minimum attach it — the dispatcher only fires for real in a multi-repo session, which is awkward to exercise from inside one. And since this is a refactor plus a gate, the honest test is a negative one: add a line to the canonical text with no manifest entry and confirm the suite goes red.

Don't chase front-desk-scheduler#96

It merged 2026-07-31 and its guidance is live in that repo's CLAUDE.md. It's related only by contrast: #96 declined to build a staleness checker for needs: because nothing records where a window exists, so there was nothing to gate against. #91 is the case where the thing to gate against does exist and is already machine-parsed — which is why leaving it unbuilt is a different kind of gap than accepting author-maintenance on needs:.

---

Generated by Claude Code