Learning #13 — a forward-looking claim has to be computed, not re-read

[rmsharp]

Revised 2026-08-01 — the original version of this PR made a claim that is false, and this
revision corrects it. It argued that the motivating prediction was "true when written and false
when used" and titled itself "a handoff's predictions decay." Re-deriving the case from git
rather than from the receipt's own account shows the prediction was never true, and the commits
the original blamed for invalidating it landed hours before it was written. The row now states the
stronger and checkable lesson. Details under "What was wrong" below.

What this is

One row appended to the starter-kit/SESSION_RUNNER.md Learnings table (was 1–12; appended,
never renumbered — rows 1–12 are byte-unchanged, and the diff on that file is a single added line),
plus one CHANGELOG.md ledger entry. No other file is touched.

A forward-looking claim cannot be checked by re-reading a file — it has to be computed.

Docs-only: no principle, phase, gate, workstream or failure mode changes, and the FM count stays
27.

Why the existing rows don't cover it

Existing row	What it covers	Its prescribed repair
Learning #6, FM #11	claims written from memory	go re-read the file that confirms it
Learnings #7, #10, #12	cross-references that go stale in the corpus	grep the corpus / encode an assertion

Every one of those repairs assumes there is a file to check. A prediction describes a state that
does not exist yet, so no file confirms it — the remedy the existing rows prescribe cannot reach it.
That is the gap, and it is a structural one rather than another instance of staleness.

The motivating case, reproducible from this repository

The S3 receipt's next_steps tells the next session what to expect from the v3.6 sync merge:

expect one CHANGELOG union conflict, resolve newest-on-top

The merge met seven conflicting files. The tempting reading is that the prediction decayed. It
did not — it was never derived. Two commands, both runnable in a clone of this repository:

$ git log --oneline -S 'expect one CHANGELOG union conflict' -- HANDOFFS.md
bec4095 feat(dashboard): Layer 8 — a framework filename is not proof of a framework

$ git show --stat --format='' bec4095
 CHANGELOG.md                         |  12 +--
 CLAUDE.md                            |   2 +-
 HANDOFFS.md                          |  11 ++-
 README.md                            |   6 +-
 starter-kit/methodology_dashboard.py |  95 ++++++++++++++++++-----
 tools/methodology_dashboard.py       |  95 ++++++++++++++++++-----
 tools/test_methodology_dashboard.py  | 146 +++++++++++++++++++++++++++++++++--
 7 files changed, 311 insertions(+), 56 deletions(-)

The sentence predicting one conflicting file entered the tree in a commit that itself changed
seven — and those seven are the seven the merge later collided in. Every fact needed to get the
prediction right was already in the author's own working tree at the moment it was typed.

What was wrong in the first version of this PR

The original claimed the prediction was invalidated by "Layer 8 and the pre-PR review fixes …
committed to the branch after the point the fork had been ported from it." Three problems:

1. The chronology is backwards. eeb827f (pre-PR review) is 07-26 18:13 and 7a7e9a2 is
   07-26 17:05; the prediction was written in bec4095 at 07-27 00:07. Both alleged invalidators
   were already in the tree.
2. It blames the commit that contains it. The prediction lives inside Layer 8 (bec4095).
3. There was no moment when it was true. Measured against the fork's main, the conflict count
   over the branch's life ran 1 → 5 → 5 → 7, and at the only point it was 1, that one file was
   HANDOFFS.md — not CHANGELOG.md.

The original also misquoted the receipt as expect one CHANGELOG.md union conflict; the text says
CHANGELOG, so grepping the quoted string returned nothing. And it reasoned from a fork-only session
receipt (S17), a fork-only campaign vocabulary (Layer 8), and a ported from commit that this
repository has no way to locate. All of that is gone — the argument now rests on the two commands
above.

Honest limit: the seven-conflict outcome was measured against the contributing fork's main
(ae6050d), which is not an ancestor of main here, so it is corroboration rather than something
you can re-run. The two commands above do not depend on it.

Cross-reference sweep (Learnings #7/#10)

Changing the size of a numbered set is exactly the trigger those rows describe.

• git grep -nE 'table (was|is|now) ?1[–-][0-9]+' returns two live sites outside this PR's own
  entry — the v3.4 narration in CHANGELOG.md and the matching v3.4 bullet in CLAUDE.md
  §Versioning. Both are dated release narration, which this repo leaves verbatim by design
  (the v2.7.1 precedent).
• The Learnings table caption states no size.
• Nothing else required updating.

Verification

• bin/tests.sh — 84 passed, 0 failed
• bin/check-links — OK, 82 relative links across 21 distributed markdown files
• Learnings table parses as contiguous rows 1–13, every row 4-column, one physical line each
• Rows 1–12 byte-unchanged (starter-kit/SESSION_RUNNER.md diff is 1 insertion(+), no deletions)
• grep -inE "Opus|Sonnet|Haiku|Fable" starter-kit/SESSION_RUNNER.md — empty (brand-neutrality)

Notes

starter-kit/SESSION_RUNNER.md is bin/_manifest.py-distributed, so adopters receive this row via
bin/sync. It is written to stand alone in a single-repo installation: the Learning column names no
fork, no upstream, and no session ID, and the one command it prescribes
(git merge-tree --write-tree --name-only) is non-mutating and works in any repository.

Two things I'd defer to you:

1. A version event. My read is no — this is one distributed row, and every prior Learnings
   row (v2.3 content release: 6 upstream candidates from rad-con SESSION_RUNNER audit (review requested) #7–Proposal: render-dependency completeness discipline (silent font-fallback case) #12) rode an existing release rather than getting its own. Happy to pre-write the
   README.md §What's New and CLAUDE.md §Versioning sites if you'd rather it ship as one.
2. Whether this repo's HANDOFFS.md is owed a receipt for these commits. Its ledger currently
   holds S1–S3, and Phase 0 reconcile will flag the gap at the next Orient. I left it alone rather
   than invent a session number in your ledger; say the word and I'll add it.

Separately, and not folded in here (FM #17 — one deliverable): the sweep turned up five dangling
Learning #N citations already live in distributed files — starter-kit/RECOMMENDED_SKILLS.md:90,
:94, :95 and workstreams/DEVELOPMENT_WORKSTREAM.md:23, :56 cite Learnings #28/#30/#34,
which have no referent anywhere in the corpus. DEVELOPMENT_WORKSTREAM.md:23 points the reader at
"Learning #30 (in ITERATIVE_METHODOLOGY.md §Knowledge Accumulation)", and that section contains
no numbered learnings at all. Reproduce with:

grep -rnoE "Learning[s]? #[0-9]+" starter-kit/ workstreams/ | awk -F'#' '$2+0 > 13'

Happy to open that as a separate issue or PR — it's the same defect class as what this PR corrects.

🤖 Generated with Claude Code

[KJ5HST]

Reviewed this against origin/main, and ran the checks at the PR head rather than reading them off the body — bin/tests.sh 84/84, bin/check-links OK (82 links / 21 files), unit suite 197/197, bin/check-handoff OK. Table parses 1–13, every row 4-column, zero lines removed from base, fast-forward on main. The corpus sweep holds too: I re-ran it and found no live count-claim about the Learnings table anywhere. And the motivating case verifies from both ends — the upstream S3 receipt does say "expect one CHANGELOG union conflict," and the fork's S17 receipt records seven with the same cause. Good catch, and a real gap the existing rows don't cover.

Approving. Four things came up. None blocking, all optional:

1. The writer-side half doesn't reach the checklist that governs writers. The row asks writers to name the state a prediction depends on — but that lives only in the Learnings table. Phase 3D's Minimum Handoff Requirements has no prediction guidance at all. That's your own Learning #8 pointed back at this change: a session following the condensed checklist never sees the instruction. The reader-side half is fine where it is.

2. No upstream receipt. I take the point about not double-counting S17. But upstream's Phase 0 reconcile is repo-local — after merge, b5eb613 and the merge commit sit past the HANDOFFS.md frontier (7817989) with no receipt, so the next session here is instructed to write a status: reconciled block. #62 went the other way (9e93588 opened an upstream S3 claim while also having a fork record). So it's not receipt vs. none — it's complete from the session that did the work vs. reconciled reconstructed later by one that didn't. Related and not yours to fix here: bin/check-handoff validates the newest receipt's structure, not receipt coverage of commits, so it stays green on a repo whose newest commits have none.

3. README §What's New. Every Learning from #7 through #12 got its own "New Learning #N" bullet (lines 283/293/301/313/368). #13 gets none unless there's a version event — so the public restatement would sit one row behind the shipped table. That's the version-event question you handed me: a v3.6.1 dot release gives it a home; otherwise the next release absorbs it.

4. Size (advisory). +1,605 bytes for one row. Rows 1–6 average ~510 characters; #12 is 2,400 and #13 is 1,604. The row re-narrates the case the CHANGELOG entry already carries in full. Not asking you to trim it — just flagging the trend on a file adopters are expected to actually read. BL-9 territory.

Your call on all of it: address any of these on this branch and I'll merge after, or say the word and I'll merge as-is and we pick them up separately. I'd lean toward the second — 1 and 3 read cleaner as a small follow-on than as edits to a 30-line PR.

---

Footnote, unrelated to this PR. While orienting I noticed there's no ### … [ad hoc] Released v3.6 entry in CHANGELOG.md — v3.5, v3.4, v3.3, v3.0.1 and v3.0 each have one, but v3.6 has only the pre-merge campaign entry dated 07-26. The tag and Release went out on 07-27 as a non-commit action, which is both the class the ledger header calls out by name ("release, tag/branch op, PR open…") and the class Phase 0 reconcile can't catch, since it diffs commits. Nothing blocking — just easier to add now than to reconstruct later, and it could ride along here if you end up touching the ledger anyway.

[rmsharp]

Heads-up: I've force-pushed this branch and rewritten the title and description. The original version of this PR was wrong, not just unclear.

Mark tried to read it cold and reported it as unintelligible — that it "assumes knowledge from a source outside itself." That was right, and chasing it turned up something worse than opacity.

The PR's load-bearing claim was that the motivating prediction was "true when written and false when used, and the session that wrote it is the session that invalidated it." One command in this repository refutes it:

$ git log --oneline -S 'expect one CHANGELOG union conflict' -- HANDOFFS.md
bec4095 feat(dashboard): Layer 8 — a framework filename is not proof of a framework

$ git show --stat --format='' bec4095 | tail -1
 7 files changed, 311 insertions(+), 56 deletions(-)

The sentence predicting one conflicting file was written into a commit that itself changed seven — the same seven the merge later collided in. It didn't decay; it was never derived. The two commits the original blamed for invalidating it (eeb827f 07-26 18:13, 7a7e9a2 07-26 17:05) both landed hours before it was written at 07-27 00:07, and it was written inside "Layer 8" — the very commit it blamed.

Measured against the fork's main, the conflict count over the branch's life ran 1 → 5 → 5 → 7, and at the only point it was 1, that file was HANDOFFS.md, not CHANGELOG.md. There was no moment at which the prediction held.

What changed:

• Thesis. "Predictions decay" → a forward-looking claim cannot be checked by re-reading a file; it has to be computed. That's the sharper gap: Learning Post-v2.2: audit rad-con SESSION_RUNNER.md for content worth upstreaming #6 / FM feat: protocols as first-class methodology layer (v2.4) #11 both prescribe "go re-read the file," and a prediction has no file. Retitled to match.
• Every unreachable referent is gone. The old text reasoned from a fork-only session receipt (S17 — this repo's HANDOFFS.md holds only S1–S3), fork-only campaign vocabulary (Layer 8), and a ported from commit with no way to locate it here. The argument now rests on two commands you can run.
• Fixed a misquote. It quoted the receipt as expect one CHANGELOG.md union conflict; the text says CHANGELOG, so grepping the quoted string returned nothing — which removed the one rescue move available to a confused reader.
• The countermeasure is now executable: git merge-tree --write-tree --name-only, which computes conflicting paths without touching a working tree.
• The row is written to stand alone in an adopter's single repo — no fork, no upstream, no session ID in the Learning column.

I squashed to one commit rather than stacking a correction on top, so a commit message asserting the refuted premise doesn't land in this repo's history on merge. Content is otherwise identical to what I'd verified: bin/tests.sh 84/84, bin/check-links OK, table contiguous 1–13, rows 1–12 byte-unchanged.

Worth saying plainly: I think this makes the PR stronger. A proposed Learning about claims that were never verified, which then caught and corrected its own unverified claim, is about the best evidence for the Learning that could exist. It also means the row is now grounded in a case I actually re-derived rather than one I took the receipt's word for.

Two open questions for you at the bottom of the description (version event, and whether this repo's HANDOFFS.md is owed a receipt), plus one separate finding I deliberately did not fold in: five dangling Learning #28/#30/#34 citations already live in distributed files. Happy to take that as its own issue.

[rmsharp]

Thanks — and apologies for the ordering: my rewrite comment above landed after your approval, so you reviewed a version that no longer exists. Short summary of what moved and where I've landed on your four.

On the one line I want to flag specifically. You wrote that the case "verifies from both ends — the upstream S3 receipt does say 'expect one CHANGELOG union conflict,' and the fork's S17 receipt records seven with the same cause." Both halves of that are true, and it's the second one that turned out to be the problem: the S17 receipt's account of the cause is what I'd taken on trust, and it's wrong. The prediction wasn't invalidated by later commits — it was written inside bec4095, a commit that had already changed all seven files, and the two commits the old text blamed landed hours before it. So the row was teaching "predictions decay" from a case that isn't decay at all. That's not a knock on the review; it's that the only way to catch it was to re-derive the cause from git instead of from the receipt, which is now precisely what the row tells you to do. Detail in my previous comment.

1 — writer-side half doesn't reach Phase 3D. Agreed, and it's the sharpest of the four. The rewritten row still puts the writer-side duty ("derive it or label it a guess") only in the Learnings table, so a session following the condensed checklist never sees it. Taking your lean: follow-on, not this branch.

2 — upstream receipt. You've convinced me, and your framing is better than the one I had. I was thinking receipt-vs-none; the real choice is complete from the session that did the work vs reconciled reconstructed by one that didn't, and #62 already set the precedent by opening an upstream S3 claim alongside a fork record. Your call whether you'd rather I add it here or take it with the follow-on — I didn't want to invent a session number in your ledger unasked. Noted too that bin/check-handoff validates the newest receipt's structure rather than coverage of commits, so it stays green on exactly the gap that would open here.

3 — README §What's New. Agreed, and tied to the version-event question. My read is still no standalone event for one row, which means the public restatement sits one row behind until the next release absorbs it. If you'd rather it not lag, a v3.6.1 gives it a home and I'll pre-write both sites.

4 — size. Addressed, and thank you for flagging it — my first rewrite made it worse (1,604 → 1,986 bytes) before I measured it against your note. The row is now 1,562 bytes, 42 smaller than the version you reviewed, and every column is inside the rows 1–12 envelope (Learning 929 ≤ 1,834 · Source 169 ≤ 236 · When 449 ≤ 467). I cut the row's re-narration of the case and left the full account in the CHANGELOG entry — keeping just enough in the Source column that it still stands alone for an adopter, who receives the row but not this ledger.

Footnote — the missing Released v3.6 entry. You're right, and I verified it: v3.5, v3.4, v3.3, v3.0.1 and v3.0 each have one; v3.6 has only the 07-26 campaign entry. I'm adding it to the fork's ledger as its own commit rather than riding it along here, so this PR stays one deliverable — upstream's copy is yours to add whenever, and happy to open it as a one-line PR if that's easier.

So: lean two, as you suggested. Merge when you're happy with the corrected version and I'll pick up 1 and 3 (and 2, if you want it there) as a follow-on.

One more thing found by the sweep and deliberately kept out of this PR — five dangling Learning #28/#30/#34 citations already live in starter-kit/RECOMMENDED_SKILLS.md and workstreams/DEVELOPMENT_WORKSTREAM.md, against a table that ends at #12. Same defect class as what this PR corrects. Say the word and it becomes an issue.

[rmsharp]

Correcting one thing in my previous comment — I said I'd add the Released v3.6 entry to the fork's ledger as its own commit. That was wrong, and I only caught it when I went to do it.

The fork already has one: CHANGELOG.md:198, ### 2026-07-27 · [ad hoc] v3.6 shipped — PR #62 merged, tagged, released, and the fork resynced. My check had grepped for the literal Released v3 heading form, which that entry doesn't use — so I confirmed a gap that wasn't there and missed that the gap is upstream's, which is of course exactly where you were looking.

To be precise about what's actually true: upstream CHANGELOG.md has Released v3.5 / v3.4 / v3.3 / v3.0.1 / v3.0, and for v3.6 only the 07-26 campaign entry. So your footnote stands as written — it just needs fixing in your ledger, not mine.

Leaving it to you rather than riding it along, to keep this PR at one deliverable. Happy to open it as a one-line PR if that's easier than writing it yourself.

(Third self-correction in a PR about unverified claims. The row is earning its keep.)