fix(docs): name the population behind every write-share figure, and gate it - #377
Open
wshallwshall wants to merge 6 commits into
Open
fix(docs): name the population behind every write-share figure, and gate it#377wshallwshall wants to merge 6 commits into
wshallwshall wants to merge 6 commits into
Conversation
…d every copy now says so
The table at docs/WORKTREE-GATE.md:26-30 is this repo's authoritative record of the 30-day
write-collision measurement: 166 sessions ran with their cwd in the shared primary, 6,075 of THEIR
Edit/Write calls (44%) landed in that primary's tree, and 4,010 (29%) landed in a sibling worktree by
absolute path. Both data rows open with "Their", so the two percentages are shares of ONE denominator
-- roughly 13,800 calls -- and roughly 27% of that population landed outside the repository entirely.
Fourteen other sites stated a share of writes without naming that population. A bare "29% of writes"
does not read as ambiguous: the reader supplies the wider denominator and is never corrected. Four of
the fourteen are the ones that matter most -- the gate's own docstring, this suite's own
test_worktree_gate.py, and prune-merged.ps1 twice, once in a string printed to an operator at the
moment they are authorising a destructive worktree deletion.
TWO SITES ASSERTED A WRONG POPULATION RATHER THAN OMITTING ONE. scripts/hooks/worktree_gate.ps1:23 and
tests/test_worktree_gate.py:5 both said "29% of THIS REPO'S Edit/Write calls". That is not vague, it is
false, and it is the sentence that justified the target-path design. Both were invisible to the regex
that found the other twelve, because its noise allowlist held only "the" and "all" -- the blind spot is
recorded in the new gate's docstring so the next reader does not have to rediscover it.
THE FALSE ATTRIBUTION IS RETIRED. docs/SESSION-DRIFT-CONTROLS.md:640 named the gate's docstring as the
source of the whole cluster. That is false for the 44% and the 166: `git log -S '44%'` and
`git log -S '166'` over scripts/hooks/worktree_gate.ps1 each return ZERO commits across all history, so
the docstring never carried either and only ever carried the 29%. The table is the only artifact
holding both numerators, which is the only context in which their shared denominator had to be made
explicit -- and the false attribution is what made the loose reading look authoritative. Corrected in
place with a dated CORRECTION block rather than struck, because the figures stand; only the
denominator and the source were wrong. "Cited, not re-measured" still holds and is kept: the
DENOMINATOR is known, the COUNTS are what nobody can re-derive. Stating those together as one blanket
hedge is weaker than the truth and invites relaxing the scope on the grounds that it was hedged anyway.
THE ARCHIVE IS CORRECTED, NOT REWRITTEN. docs/archive/backlog/BACKLOG-CLOSED.md:6709 QUOTES what
occupancy.ps1 disclosed. Rewording the script would have turned that quotation into a misquote, so the
sentence stands and a dated CORRECTION blockquote follows it, modelled on the #1099 correction already
in that file. It also fixes the paraphrase in the same sentence: "false about one write in three" is
true only of primary-seated writes. No ledger number was allocated -- a prose correction has no fix and
no closing condition, so it is not an item, and CLAUDE.md forbids filing something that would sit open
describing something true. The deviation from #1099's numbered form is deliberate and stated in the
block itself.
ONE SITE WAS DELIBERATELY NOT TOUCHED. docs/WORKTREES.md:695 already reads "166 sessions ran with their
cwd in the shared primary, and 44% of all their file writes landed in the primary's tree". It was the
only correctly scoped statement in the repo, and a mechanical sweep would have damaged it invisibly.
It is now the new gate's positive control.
THE GATE. tests/test_write_share_denominator.py, added to the DOC_GUARDS list in ci.yml in this same
commit so a docs-only pull request still runs it. It bans the loose form rather than requiring one
spelling, because the scope can be carried by an attribution after the figure, a lead-in before it, or
a possessive, and pinning one wording would go red on a harmless rewrite. Three properties are
load-bearing and each is documented next to the knob it constrains: it matches WHOLE-FILE text because
two live sites wrapped between "of" and its noun; it rejects a repo-naming possessive outright; and its
window is 200 characters and looks both ways, because both orders occur here and a window wide enough
to reach WORKTREE-GATE.md's own table from 794 characters below would let any file containing that
table say anything. An archived quotation is discharged only by a CORRECTION block that itself names
the population.
PROVED IT CAN FAIL. Mutating each of the 13 sites the gate can see, one at a time, with both windows
blanked: caught 13 of 13, no blind spot. An earlier mutation that blanked only the FORWARD context
reported 5 misses -- that was the instrument, not the gate, and it is why the check blanks both.
Stated limits, in the source: the noun list is an allowlist, so "44% of edits" or a spelled-out
percentage passes, and no percentage-keyed scan can ever see a paraphrase like "one write in three".
Verification: 192 passed, 1 skipped over the doc guards and both edited test modules. The skip is
test_gate_installed_parity, which declares itself -- the installed gate is SUPPOSED to differ while
worktree_gate.ps1 has uncommitted changes; re-run after this commit. Backlog banners unchanged: 513
items parsed by scripts/docs/backlog_status_check.py, 203 open, before and after. ruff check and
ruff format clean over 1109 files; all three edited PowerShell scripts parse. mypy reports the same 21
pre-existing errors as HEAD, in files this commit does not touch -- they are the worktree venv's
missing optional extras, not a regression.
The sibling repo claude-multisession shipped this correction first; this is the source repo catching
up, and the source was the less accurate of the two until now.
AMENDED. Two defects found by an adversarial pass over the first version of this commit, both in the
new gate rather than in the prose:
* THE PATTERN WAS STILL BLIND, to the same class it was written for. Its modifier run was an allowlist
of determiners, and ONE ADJECTIVE defeated it: "~29% of this repo's REAL Edit/Write calls" -- the
exact wording that stood in tests/test_worktree_gate.py until this commit -- did not match at all, so
the single wrongest sentence in the repository was the one sentence the guard could not see. The run
is now open and capped at three tokens, with `durable`, `body` and `bytes` barred so the store-
transaction family ("63% of the hub's durable writes", a different subject) and "77% of the body
bytes this message writes" (a verb) stay out, plus a lookbehind so the benchmark corpus's "49.44%"
is not read as a bare "44%". Four false-positive controls pin those. The gate now sees 14 sites,
all scoped, and mutating each with both windows blanked is caught 14 of 14.
* $GateVersion WAS NOT BUMPED, and the variable's own comment at :60-67 records that exact omission
happening once before: rules were added without a bump, so `-Status` printed the same version on
both sides directly above a *** STALE *** verdict. This commit changes the file's bytes, so the
label moves to 2026.08.13.1. Nothing enforces the bump -- test_install_gate_wiring only checks the
format -- which is why it is worth doing by hand rather than assuming a gate will catch it.
The installed gate on the developing machine is now STALE against this commit, which
tests/test_gate_installed_parity.py reports rather than hides. It skipped while the source was
uncommitted and reds from here until a human runs install-gate.ps1 from a PLAIN terminal; the
installer refuses under $env:CLAUDECODE by design. CI is unaffected: no gate is installed there and
the module skips.
wshallwshall
enabled auto-merge (squash)
August 13, 2026 16:41
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The source-repo half of the denominator correction. Single commit, based on
df1059f5.Fourteen sites stated a share of writes without naming the population -- including the gate's own
docstring, its test suite, and a string
prune-merged.ps1prints to an operator at the moment theyauthorise a destructive deletion. Also retires a false source attribution and adds
tests/test_write_share_denominator.py, wired intoDOC_GUARDS.claude-multisessionshipped its half first; MessageFoundry is where the measurement actually livesand was the less accurate of the two until now.
Two things to know before merging
1.
test_gate_installed_paritywill RED on this machine from this commit until a human runspwsh -NoProfile -File scripts\worktree\install-gate.ps1from a plain terminal. That is correctbehaviour, not a regression: the commit changes
worktree_gate.ps1's bytes, so the installed copy isgenuinely stale. Parity was intact before the commit (installed and repo@df1059f5 hash
identically -- checked). CI is unaffected; no gate is installed there and the module skips.
Do NOT install from the worktree to make it green. That would put an unmerged version on a
machine-global path governing every session on this box -- the stale-checkout downgrade hazard the
parity module documents.
$GateVersionis bumped to2026.08.13.1so-Statuscannot print matchinglabels above a STALE verdict.
2. This PR is
code=true(it touches .ps1/.py/.yml), so the full matrix runs on all three legs.Do not let it be split into a docs-only PR:
test_worktree_gate.pyandtest_script_root_anchoring.pyare not inDOC_GUARDSand would then not run at all -- and they aretwo of the edited sites.
Verification
Full suite 12,258 passed / 856 skipped / 0 failed (37 min); baseline 12,259/855, the one moved test
being the parity skip above. 325 targeted tests green after the last two edits.
ruffclean over 1109files, all PowerShell parses, ledger gate and leak guard passed.
mypy: same 21 pre-existing errors asHEAD, in files this commit does not touch.
The authoring session's own gate was blind to the class it was written for, and they fixed it: the
modifier run was an allowlist of determiners, and one adjective defeated it -- "29% of this repo's
REAL Edit/Write calls", the exact wording in the gate's own test suite, did not match at all. An
allowlist decides in advance which words a defect may contain, which nobody can know. Now an open
capped run with three bars and four false-positive controls; mutating all 14 sites is caught 14 of 14.