docs(rules): three measured lessons folded into existing bullets, paid for without narrowing one (#193)

[ZacxDev]

What this is

clawgate #193 plus three lessons measured 2026-08-14. The task card bundled them deliberately, and it was right to: all three landed inside paragraphs the consolidation had just rewritten.

The consolidation half of #193 was already done — PR #458 turned the five worktree bullets into three (recipe / "a worktree isolates a working DIRECTORY only" + REPO·SESSION·ENVIRONMENT sub-bullets / base-clone re-sync). No further worktree consolidation was available without losing scope, so this PR does not attempt one. What it does is the part that was actually left: fit three new rules into the budget without a ceiling bump, which the card called for in its own words — "the answer to the next real rule is consolidation, not another bump."

MAX_BYTES and MIN_HEADROOM_BYTES are unchanged.

Size, as printed by the test

before: 33,264 B
after:  34,268 B   headroom 932 (min 900)   slack above the floor: 32 B

The honest reading: the file is at capacity. 32 B is not a working margin. The next real rule needs either a genuine consolidation or an argued bump — the module comment already predicted this and is now correct twice over.

Where each lesson went, and why

Placement was chosen by where the reader already is when the hazard fires, not by which cluster the lesson came from. Two of the three are verification lessons, not worktree ones, and they went to the verification section.

lesson	placement	why there
cp -a of a worktree gives zero git isolation	4th sub-bullet under "a worktree isolates a working DIRECTORY only"	It is that rule in a new shape. The frame, the "list is not closed" clause and the silent-failure framing are all reused — cost was 394 B, its own text only.
A guard on prose is walkable by rewording	extends "A guard can be SPELLED rather than STRUCTURAL"	Same question ("can it pass while the hazard exists in a different shape?"), new artifact type. When the thing under test is a sentence, the existing remedy ("assert the STATE — id plus attribute, a role") has no referent, so the reader is left with no move. The new one: pin the whole normalised string.
A fixture whose value equals the constant it tests	extends "pick fixtures whose fields are pairwise distinct" in the mutation bullet	Same collision, different pair — fixture vs constant, not field vs field. The existing clause is strictly narrower: a fixture with pairwise-distinct fields can still have one equal to the constant under test.

The last two reuse the → archive: anchor already on their bullet, so neither added a tag. Only the new sub-bullet needed one (worktree-copy-git).

Full evidence for all three is in RULES-ARCHIVE.md (no ceiling, not auto-loaded): the .git-is-a-FILE mechanism and the commit that landed on a real branch; the three prose walks with the exact strings that walked them; the three fixture-equals-constant instances including the one introduced inside the commit that fixed the previous one.

Paying the 202 B — without narrowing anything

The three additions overshot the budget by 202 B. What was reclaimed, and the test applied to each (can the shortened rule pass while the hazard exists in a shape the original covered?):

• The stash section stated "for ANY reason" three times — the heading, a 🔴 clause, and a trailing "regardless of why". The third was dropped; the heading and the 🔴 clause (The prohibition is NOT scoped to rebases, and applies for ANY reason, plus "a narrower earlier wording is exactly how it failed") are kept verbatim. The consequence clause ("a concurrent agent or session can pop your stash") was moved, not deleted. This is the one rule whose narrowing is the documented origin incident, so it got the strictest check.
• The pkill bullet's incident numbers (~15 PIDs, 0 files collected and exit 144) moved to sibling-agent-kill — which already held them verbatim and was already tagged on that bullet. The hazard shape survives in the core: a box-wide pattern destroys a sibling's run, and the result reads exactly like a code defect.
• Two sentences of narrative trimmed from the new additions themselves.

🔴 What was deliberately NOT touched: the clause saying /proc/<pid>/cwd cannot separate two agents that both sit in the base clone. PR #447 trimmed exactly that and re-opened the original incident. It is now named in the test module's comment so the next person shaving that bullet knows which sentence is load-bearing.

Verification

Gate — nix build .#checks.x86_64-linux.pytests -L --no-link, read by content:

PASS  scripts/tests  (collected=4119 passed=4119 skipped=0 floor=3970)
TOTAL collected=9919  passed=9918  skipped=1  failed=0  (floor: 9311)
RESULT: PASS (exit=0)

scripts/tests (which holds test_rules_size.py) is confirmed collected, so the target ran rather than being silently absent. No panic: test timed out.

Negative controls — all 5 test functions, 7 controls, each red with its own message, all green again after restore:

control	fires	message
ceiling forced below size	under_hard_ceiling	OVER BY: 1 bytes
headroom floor above free space	keeps_working_headroom	RECLAIM / free: 952 (minimum required: 953)
RULES_MD → missing path	rules_md_exists	not found -- the size gate below would be vacuous
ARCHIVE_MD → missing path	archive_exists_and_has_anchors	RULES.md's eviction target is gone
archive present but anchorless	archive_exists_and_has_anchors	has no ## <anchor> sections
playbook stops deriving its list	archive_exists_and_has_anchors	the eviction playbook omits existing archive anchors [...]
bogus → archive: tag injected	every_archive_pointer_resolves	points at archive anchors that do not exist: ['no-such-anchor']

The last one doubles as the positive control for the pointer test: it can observe a dangling anchor, so its green on the real file means something.

Anchors resolve both directions — 0 dangling refs; 0 archive sections unreferenced (excluding retired-*); 0 TOC drift; 0 duplicate refs.

Cold read — the check no test performs

Each changed bullet was re-read as someone who will never open the archive:

• cp -a sub-bullet — mechanism (.git is a FILE), consequence (commit lands on the REAL branch), trigger (the SESSION surface tells you to make such copies), and fix (rm -f <copy>/.git) are all present. Reads correctly against the frame.
• prose-guard — three walk mechanisms still named (static prose satisfying a computed-slot check; rewording; synonym). Remedy and its cost both stated, so a reader does not reject the fix.
• fixture-equals-constant — imperative plus a mechanical control that needs no imagining of the mutant.
• stash — every scope-bearing clause verbatim; only the third utterance of one qualifier gone.
• pkill — the docs(rules): two multi-agent lessons that never landed, recovered from a merged branch #447 clause intact; only incident numbers moved.

🔴 This caught the one real regression. run a SINGLE agent in-place — never two file-modifying ones had been shortened to never two, which reads as forbidding a second read-only agent that the previous sentence explicitly permits. 20 B restored. No test would have caught it, and it is the reason the cold read is a required step rather than a nicety.

Not done

Not merged, not deployed. home-manager switch / ship.sh still required for this to reach either host.