The prose update route can wipe an adopter's ledgers: give the instruction the three rules that stop it

[rmsharp]

The defect

starter-kit/BOOTSTRAP.md §Without bin/sync is one sentence:

Tell your agent: "Update methodology using https://github.com/KJ5HST/methodology". It will fetch the latest
starter-kit files and overlay them.

It names no exception, and six of the files it tells the agent to overlay are seeds: CHANGELOG.md,
HANDOFFS.md, SESSION_NOTES.md, ROADMAP.md, .context-budget.json and .quality-gates.json. An agent that
follows the sentence literally replaces the adopter's action ledger and every close-out receipt with empty
templates.

bin/sync has never had this defect. bin/_manifest.py classes those six as seeds and installs them once, and
bin/sync refuses to overwrite them by construction. The gap is only in the prose route — which is the route
this very section tells people to use, and for an adopter with no sibling checkout it is the only route there
is. The fix is delivered by the instruction that is broken: following it to get the corrected text overwrites the
ledgers first.

An acceptance test across six adopter projects rated this critical and measured the exposure. Three of them were
inspected directly and held identical text; their CHANGELOG.md / HANDOFFS.md pairs were 42 KB / 70 KB,
150 KB / 112 KB and 474 KB / 1.1 MB. The protection had reached none of the six.

What this changes

One section of one file. The instruction stays exactly as it is; three numbered rules follow it.

1. Overlay the tracked files; never overwrite the adopter-owned ones. A two-row table splitting the
distribution, with the consequence of getting it wrong in the sentence beneath it rather than left implicit. The
rows are derived from bin/_manifest.py's DISTRIBUTION list, not written from memory.

2. Reconcile the adopter-owned files by hand, because nothing else will. Never overwriting them means a
project moving up from an earlier version keeps its ledgers in their old format — new behaviour, missing
structure. This rule points at the Updating an existing project from an earlier methodology version paragraph
in §Setup with bin/sync rather than restating the migration, so the two cannot drift apart and this section
needs no edit when that paragraph changes.

3. Verify afterwards, don't assume. bin/status and the five verdicts it prints, with the one that means
rule 2 is still owed called out.

Why it is prose and not a mechanism

Because the failure is a prose instruction being followed correctly. There is no code path to guard: the agent
never runs bin/sync, so no refusal in bin/sync can reach it. The only thing standing between the instruction
and an overwritten ledger is what the instruction says, which is what this changes.

Verification

Measured on the branch, and again on the merged trees:

• bash bin/tests.sh — 139 passed, 0 failed, unchanged from the base commit; 163/0 merged with Put the CHANGELOG.md rules in one synced home: the seed becomes a pointer, and the rules stop contradicting each other #84;
  188/0 merged with bin/sync --source=github: an update route that can recognize a file as merely behind, and a refusal that names its own cause #87, where the raised floor of 188 is met exactly.
• bin/check-links — OK, 107 relative links across 23 distributed markdown files.
• python3 starter-kit/context_budget.py --precommit — exit 0.
• python3 starter-kit/quality_ratchet.py --run — 10/10 pass, 0 fail, 0 unmeasured,
  results 6542e640a956 · manifest 97a7aab85b9a on the branch; 10/10 on both merged trees.

No gate moves: the change is prose in one file and adds no tests.

Deliberately not in this pull request

• The --source=github note. The fork's version of this section closes with a paragraph about that route.
  It describes behaviour bin/sync --source=github: an update route that can recognize a file as merely behind, and a refusal that names its own cause #87 changes, so it belongs with that work, not here.
• The stale file lists in §Setup with bin/sync. Noted above; a separate, larger edit.
• Any change to bin/sync, bin/status or the manifest. They already behave correctly; only the prose did not.

🤖 Generated with Claude Code