bootstrap-pin: generate the pin, stop failing PRs that cannot fix it, and terminate

[bdelanghe]

Follow-up to #77, which went red on FRESHNESS and could not do anything about it. Branches from main, not from #77 — the two are independent, but the merge order matters (see the note on #77: this one first, then #77 goes green with no change to its diff).

Three commits, and the second and third are both cases of the first being wrong in a way only running it would show.

1. Generate the pin, and stop failing PRs that cannot fix it

PIN and the SUM_* digests are one atomic pair. SUM_* is content-addressed and knowable on a branch; PIN is a commit, and cannot name a merge commit before that commit exists. So every PR touching a fetched file is red on FRESHNESS with no honest fix — recording the new digests early just moves the red to INTEGRITY. #75 hit it, #77 hit it again, and an expected-red teaches people to ignore red. Worse: org-defaults.yml also runs on push to main, so main went red the moment such a PR merged and stayed red until a human hand-typed a follow-up.

• gen-bootstrap-pin.mjs generates the pin and digests, and backs the gate's --check. register-mcp: register each repo's MCP servers at user scope #71 and bootstrap: verify fetched scripts before executing, and bump the pin #72 were both a human hand-copying 64 hex characters; the gate that caught them decided "correct" in code separate from the code that produces correct, which is the same bug one level up.
• FRESHNESS is asserted on push and reported (t.diagnostic) on pull_request. INTEGRITY stays hard everywhere.
• A pin job regenerates on push to main and opens the bump PR itself, on a fixed branch so consecutive pushes update one PR rather than queueing PRs that pin superseded commits. Not auto-merged: the org requires a review on the default branch, and a generator that writes the trust anchor is the last place to drop that.

2. It did not terminate

That commit claims the loop terminates "because the bump only edits .claude/README.md, which is not in the fetch set, so it cannot invalidate the pin it just wrote." Running the loop showed that is true and not sufficient:

round	event	before	after
1	a fetched file changes on main	bump PR opened	bump PR opened
2	that bump PR merges	bump PR opened	silent
3	anything at all pushes to main	bump PR opened	silent

The README-is-not-fetched argument establishes that the content stays consistent across a bump. It says nothing about the commit id — and the commit id is what the rewrite keyed on. next === source was the only guard, and after a bump lands next always differs, because PIN names the new commit rather than the one before it. An automation that opens a PR on every push to the default branch is worse than the expected-red it was written to remove.

So the decision moves off commit identity and onto content. planBump writes only when the pin is wrong — INTEGRITY broken, or STALE against this tree. A pin that trails HEAD but still serves byte-identical files is correct, and correct is a no-op.

3. The pin job made the workflow unparseable, and CI showed green

The job in commit 1 never ran. Neither did schema, the job that runs every test in this repo. Its gh pr create --body "..." put prose at column 0 inside a run: | block scalar; a non-empty line at column 0 ends the scalar, and the --- rule then starts a new YAML document:

.github/workflows/org-defaults.yml, line 74, column 1
could not find expected ':'

The first push of this PR showed seven checks, every one green, with the test suite never executed. GitHub does not report an unparseable workflow as a failing check — it records a run named by the file's raw path, and the jobs inside simply do not happen. A break that removes your gates does not look like a break; it looks like success with fewer lines.

• The bump PR body moves to .github/bootstrap-pin-bump.md, passed with --body-file. Prose wants blank lines, a --- rule and a leading _, none of which survive inline in a block scalar — and keeping it in a file makes the body reviewable as prose, which is what it is.
• workflows.test.mjs asserts, across all twelve workflows, that nothing but a top-level key or a comment starts at column 0. Not a YAML parser: node has none built in, this repo's tests take no dependencies, and the one structural property that broke is exactly checkable.

It runs from schema, i.e. from inside org-defaults.yml, so it fully covers the other eleven and covers this one only before a push. The other half is that schema is a required check — one that never reports blocks the merge, which is what catches this file being already broken on a branch. Neither half is sufficient alone; that is written into the test's header rather than left to be rediscovered.

Verification

• 71/71 across org-defaults, workflows, session-start-dispatch, register-mcp, gen-bootstrap-pin, bootstrap-pin.
• gen-bootstrap-pin.test.mjs walks the four rounds above against a fixture world, including the commit a merged bump lands as — a new id serving identical bytes, the case the old guard could not see. Deleting the gate fails that test and only that test; checked by deleting it, not assumed.
• End to end on a scratch branch, both directions: with the generator as it stood in commit 1, round 2 writes and opens a second bump; with commit 2 it reports already serves this content and opens nothing, while --check still calls the tree correct.
• workflows.test.mjs checked against the real break: restoring the previous org-defaults.yml fails it and names line 74.

Note on branch naming

The session's designated branch is claude/ci-chain-verification-r8bpoh, which already carries #77. This is a separate change off main, so it is on its own branch rather than stacked into that PR — say the word if you would rather have them together.