docs(planning): parallel-sessions plan — fan-out to many agents, one closer per tree

[KJ5HST]

Planning-session deliverable — nothing implemented

docs/planning/parallel-sessions-plan.md (S24, 2026-09-16). Trigger: "Do the recent changes allow for fanning out with multiple agents now? Prior to that, fanning out was very messy." The Orient answer was safe but not clean — the ratchet binds every actor's output; nothing yet coordinates two actors writing at once. This plan is the coordination half.

The finding — one closer per tree. Every coordination artifact the methodology has is serial (one ACTIVE TASK, one S<N>, two prepend-only ledgers at one anchor, a hook that forces every commit onto one of them, a reconcile step that walks one line). The operator's own records show both failure shapes precisely: six verify-agents mutating one tree fabricated a defect (adopter S163); two sequences prepending at one anchor conflicted in both ledgers (this repo, S21). They also show what worked: agents return content, one integrator writes and commits (adopter S13). The plan generalizes that into two shapes — A: one session, many hands (workers are layers, the lead closes) and B: many sessions, many closers (one per branch, records merge without conflict).

What it proposes (§4, D1–D15; §6, six phases, one per session):

• .gitattributes merge=union for the four append-only files, as a SEED, plus a canonical bin/check-ledger (the CHANGELOG.md twin of check-handoff) and a two-branch merge test, RED-first
• a ## Parallel Actors section in the flight manual: the four slice gates + three more (one closer; disjoint write scopes; serial integration, one unit per checkpoint) — the runner gets a pointer, paid by reduction (35 tokens of headroom)
• "one writer per tree" as a SAFEGUARDS hard rule; recommended FM Resolve #16: generalize CONTEXT_TEMPLATE 'auto-memory' to agent-level memory #29 "Shared-tree mutation"
• sequence-tagged session ids (S24-<seq>; bare S<N> stays the trunk's); a merge is one action with one receipt — closes the "11 reconciled receipts" ruling by rule
• --source=github reads the manifest at the same ref as the content, so Test 9 is green on every branch correctly; worktree-aware --calibrate
• an alternatives table (changelog fragments considered and deferred, with the cost stated) and six honest ceilings (§7)

Sequencing (D12): v3.8 first; this plan as v3.9. Phase 1 is independent and could land earlier.

Twelve decisions for the operator are in §8 — each with a recommendation; answering them (here, as a comment) is this plan's Phase 0.

Evidence discipline: every methodology citation is file:line at main @ 6b29d3d, re-run before commit (§9). Adopter evidence is cited by session number; the project is deliberately unnamed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GBY4miFUdnMfCD634WDq9U

[rmsharp]

Thanks for writing this up. I read the twelve items in §8 as your decisions to make, so this is a
collaborator's review, not a set of answers. In short: one change to how the ledgers merge, short notes
on seven items, and agreement with the rest.

1. The one change: leave HANDOFFS.md out of merge=union

The plan gives git's built-in union merge driver to four append-only files (§4, "The append-only
files merge by union"). I'd keep it for CHANGELOG.md and the two .jsonl histories, and leave
HANDOFFS.md without it. Its conflicts are then small and marked, and the plan's own fallback covers
them: resolve by hand, then run check-handoff --all.

What goes wrong. Say two branches each add a receipt to the top of HANDOFFS.md. A union merge does
not keep two receipts. It produces one block that starts with two session: lines, then the fields the
two receipts had in common, then both receipts' other fields one after the other. The merge reports
success. bin/check-handoff --all fails on the result, but only if someone runs it, and GitHub's merge
button runs no checker.

Why. When both sides insert text at the same place, git first sets aside the lines the two insertions
have in common, and only then does union stack the lines that differ. Every receipt opens with the same
```handoff line and closes with the same ``` line, so both receipts land inside one pair of
fences. CHANGELOG.md entries each start with their own ### heading, so they stay whole; the only loss
is the blank line between them.

How I checked. I replayed your two most recent sessions as if both had started from 64f23bf: one
side adds the receipt and ledger entry from 64f23bf..6b29d3d, the other those from 6b29d3d..219fb9d.
I merged each file with and without the attribute, on git 2.50.1, using only this repository's history
and the Python standard library:
https://github.com/rmsharp/methodology/blob/c3a096bdc8b4eeb4be4539e4ac458c652a26bc03/docs/planning/pr83-union-repro.py

What is merged	Without union	With union
CHANGELOG.md: the two real ledger entries	marked conflict	both entries kept, ours above theirs; one blank line lost
HANDOFFS.md: the two real receipts	marked conflict	one block with two session: lines; merge reports success
HANDOFFS.md: two made-up receipts that share nothing but their fence lines	not run	still one block
HANDOFFS.md (made-up receipts): one branch archives old receipts, as methodology_trim.py does, and adds its own; the other adds one	marked conflict	an archived receipt is back in the live file, and the two new ones are fused

What this changes in the plan.

• Phase 1's merge test expects the merge to succeed with check-handoff --all green. It will fail,
  even with minimal receipts, because the fence lines alone are enough (third row).
• The rejected alternative. The alternatives table turns down per-session receipt files because
  "union covers both files at once". That no longer holds, so it is the option to revisit if receipt
  conflicts turn out to be frequent.
• "Every legitimate concurrent edit is an insertion" stops being true once the distributed
  methodology_trim.py archives old records (last row). I ran that case on HANDOFFS.md only; a
  CHANGELOG.md trim against a new entry is untested.
• The proposed bin/check-ledger should accept a ### heading directly under the previous entry,
  since union drops the blank line between them. Not tested: whether methodology_trim.py accepts
  that, and the two .jsonl files, where one record per line should make union safe.

2. Smaller notes, by §8 item

• Item 2, "one writer per tree" as a SAFEGUARDS.md hard rule. Agree. Sizing note: if my open
  PR Put the CHANGELOG.md rules in one synced home: the seed becomes a pointer, and the rules stop contradicting each other #84 lands first, SAFEGUARDS.md has 17 tokens of headroom rather than 71, so the new row would be
  paid for almost entirely by cutting other text, as the plan already allows.
• Item 4, session identity. Agree with S<N>-<seq>. But "bare S<N> is reserved for the trunk
  sequence (main)" reads as if there were one trunk. A fork's main is a trunk too: mine has used
  bare S<N> for over 200 sessions, and starter-kit/HANDOFFS.md already says a fork and its upstream
  keep separate numbering. Suggested wording: each repository's main uses bare S<N>; S<N>-<seq>
  is for other branches in the same repository.
• Item 5, a merge is one action with one receipt. Agree, and dropping the 11 reconciled receipts is
  right: they are my commits from PR Merge the read-set budgets series (#76–#79): the Phase 0 mandatory read fits in one read again #80, each already recorded in my fork's ledger. One addition: after
  a merge, check that each merged PR has a ledger entry. Phase 0 only looks at commits made since the
  ledger last changed, so a merged commit with no entry drops out of view once any later commit edits the
  ledger. That happened to 56997af from PR Ship the ledger trimmer, with tests that run outside this fork (read-set budgets, 2 of 4) #77.
• Item 7, reading the manifest at the same ref as the content. Agree. One limit to record: Test 9 in
  bin/tests.sh makes about 29 GitHub API calls per run. When I ran two suites at once, both failed
  Test 9 on GitHub's secondary rate limit, while gh api rate_limit showed 5000 of 5000 remaining.
  Phase 5 runs sessions concurrently, so it should run suites one at a time or expect this.
• Item 10, a new failure mode. Agree on adding failure mode Resolve #16: generalize CONTEXT_TEMPLATE 'auto-memory' to agent-level memory #29, "Shared-tree mutation". I've seen
  the tendency twice more: a review agent that wrote into the distributed template
  starter-kit/CHANGELOG.md in the shared tree, and the two concurrent suites above, which shared no
  tree, only GitHub's rate limit. So the wording could say shared state, for example: concurrent
  actors that edit, build, test or call a rate-limited service against shared state read each other's
  side effects as defects. The name is yours.
• Item 11, the dashboard advisory. The plan makes no recommendation. Mine is to wait until after
  Phase 5: a permanent low-priority advisory on every project with one session sequence would be a report
  nothing acts on.
• Item 12, the scope guard. Agree with the boundary, but it says the plan does not touch the 9
  principles or the 6 phases, and the plan adds a paragraph to Principle 9 and a clause to step 4 of the
  flight manual's Phase 1. More accurate: adds none, removes none, renumbers none; amends Principle 9 by
  one paragraph and Phase 1 step 4 by one clause.

On items 1, 3, 6 and 9 I agree as recommended; for item 3, the merge above confirms union puts ours
above theirs. Item 8, releasing v3.8 first, is your call.

[KJ5HST]

The §8 decisions are answered: docs/planning/parallel-sessions-plan.md §8A, commit 5bab033. Claude wrote them in session S27 at the maintainer's direction. They take your review into account, and §9A has the measurements.

• Your main change is adopted. HANDOFFS.md stays out of merge=union. Reproduced: with the default conflict style, and with zdiff3, two prepended receipts merge into one block with two session: lines, and the merge exits 0. Only a per-clone merge.conflictStyle=diff3 keeps them whole, and that can't ship. Conflicts are resolved with git merge-file --union --diff3 on the three index stages, then check-handoff --all.
• Your untested case is measured. On CHANGELOG.md, the real trimmer (--cut 1 and --cut 3) against a prepended entry merges clean: nothing archived returns, one blank line is lost, and the trimmer accepts the result.
• Adopted as you worded them:
  • item 4: each repository's main uses bare S<N>;
  • item 5: the merged-PR ledger check. PR Ship the ledger trimmer, with tests that run outside this fork (read-set budgets, 2 of 4) #77's 56997af really had no entry here; it's now backfilled;
  • item 10: FM Resolve #16: generalize CONTEXT_TEMPLATE 'auto-memory' to agent-level memory #29, named "Shared-state interference" to cover your two cases;
  • item 11: deferred until after Phase 5;
  • item 12: the scope wording.
• Item 7 needs you. bin/sync --source=github: an update route that can recognize a file as merely behind, and a refusal that names its own cause #87 clones main but still iterates the local manifest, so Test 9 still fails by construction on a branch that adds a distributed file. The adopted fix is to iterate the clone's bin/_manifest.py. That changes the premise of your Test 28, so I'd like your view before Phase 3 changes it.
• The plan now targets v4.1, since v3.8 and v4.0 have shipped.