# Protocol Consolidation Plan — Health-batch Unit U6 **What this is.** A LOSSLESS restructuring plan for `CLAUDE.md` — the rules doc that loads on **every** session (~24k tokens). The goal is to make the *same* rules cost fewer tokens, never to remove a rule. Analysis only: **no edits to `CLAUDE.md` or any source, no commit.** This is the doc the owner reviews *before* anything touches the governing rules file. **Snapshot:** branch `dev`, clean at `4aec149`, 2026-07-15. Opus authored (Protocol 8 stage 1). **The one hard constraint.** Every protocol was born from a real bug. **No enforced or gate-guarded rule may be dropped, and no bug-origin lesson may be lost.** Suite 220 already fails the build if a referenced protocol/file/global vanishes — this plan respects that guard, it does not fight it. Consolidation = saying a rule *once* instead of three times, compressing narration that restates rather than teaches, and pointing to the guard where the guard already *is* the enforcement. If a token drops, it is because the words got tighter, never because a rule left the building. --- ## 1. Measured baseline (grepped today, not guessed) | Metric | Value | | --- | --- | | `CLAUDE.md` size | **95,477 bytes** · **777 lines** · **13,053 words** | | Estimated tokens | **≈ 23,900** (÷4 chars/token — matches the plan's "~24k") | | Numbered protocols | 46 (1 retired: Protocol 15) | | UI protocols | 9 (UI-1..UI-10, UI-8 not yet adopted) | | Total protocol sections | **55** | **Composition (rough):** the doc is genuinely dense — it is *not* 20% fat. It is protocol prose (~70%), tables (~15%: the Pointer Index, 2a sync table, Prohibited Patterns, Protocol 2/2a doc tables), and build-history narration woven into protocol bodies (~15%: "why we added this," incident references, worked examples, "(2.8.5 U-A4 split)" tags). The realistic savings live in the narration and the restatement, not in the rules. **The ten biggest sections (bytes):** | Bytes | Section | Consolidation angle | | --- | --- | --- | | 7,357 | Reference Pointer Index | Navigation aid — mostly keep; small dedup | | 6,888 | Architecture Quick Reference | **Load-order narration — biggest single win** | | 5,604 | Protocol 2a — Test Count Sync | Changelog/hotfix model restates itself | | 4,852 | Protocol 8 — Dispatch Multi-Model | Prose-heavy rationale | | 3,887 | Protocol 46 — Code Map currency | Guard-enforced; CI-vs-local explanation compressible | | 3,811 | Prohibited Patterns | 4 rows restate Protocols 16/30/31/39 | | 3,534 | Protocol 45 — Doc Reference Integrity | Guard-enforced; sibling of 46 | | 3,529 | Protocol 38 — Game-Agnostic Code | Keep (dense rules + sanctioned-exception list) | | 3,500 | Protocol UI-10 — Overseer Presence | Keep (recent, all distinct rules) | | 2,803 | Protocol 43 — Dev-Branch Workflow | Re-lists every protocol by number — compressible | --- ## 2. What must NOT be touched (guardrails for the eventual edit) Stated up front so the edit pass can't drift: 1. **The repeated test count `3276 tests / 232 suites` is deliberate, gate-adjacent duplication.** Protocol 2a *requires* it in the gate code block, gate note, Protocol 4 checklist, Protocol 5 checklist, and the Architecture Quick Reference one-liner. **Do not dedup any of these five.** They exist to be caught by the `Select-String` drift scan. 2. **The `<!-- LOAD-ORDER-GUARD:BEGIN … END -->` filename list + order** is machine-checked by Suite 220 (Protocol 45 check 3) against `index.html`. The **filenames and their order stay exactly as-is.** Only the *prose description* attached to each line is in scope. 3. **Every `window.*` global name, `js/…` file path, and `library/<file>` pointer** named in the doc is checked by Suite 220 (checks 1, 2, 4). Compression must not remove or rename any of these tokens. 4. **Every bug-origin lesson stays.** The r6 bug, the 5c-ii clobber, the UTF-8 double-encode incident, the `getRedirectResult`-null mobile regression, the beforeunload-flush footgun — the *lesson* (what broke and why the rule exists) is load-bearing and stays. Only redundant *restatement* of it, or a bare commit hash, is a compression candidate. 5. **No protocol number is reused or renumbered.** Merges keep all original numbers as sub-parts (e.g. "Protocol 32/33/35 — Remote Kill-Switch, parts a/b/c") so every existing `→ Protocol N` cross-reference and Suite 220 lookup still resolves. --- ## 3. SAFE — purely mechanical (no owner judgment needed) These are verbatim/near-verbatim restatement removed by stating the rule once and pointing to it. No rule changes, no nuance at risk. ### S1 — Collapse the cache-bump restatement in the gate block → point to Protocol 1 **Where:** Pre-Commit Gate section, the two bullets "Bump `CACHE_NAME` when served files change" + "Cache-bump guard runs at commit time" (lines ~60–64). **Now:** both bullets fully re-explain the served/precached set (`index.html, sw.js, manifest.json, icons, css/, js/`), the strict-monotonic rule, and the "non-served commits bypass" behavior — which Protocol 1 then states again in full immediately below. **After:** one bullet — *"Bump `CACHE_NAME` when a staged file is in the served/precached set — full rule + the automated guard in **Protocol 1**."* The powershell-comment pointers already say "(Protocol 1)"; keep those. **Saved:** ~550 bytes (~140 tok). **Lossless:** the full rule + guard behavior lives verbatim in Protocol 1; nothing is lost, it is said once. ### S2 — Dedup Protocol 1's own internal double-statement **Where:** Protocol 1 body + its "Automated guard" paragraph. **Now:** the intro paragraph and the "Automated guard" paragraph each independently enumerate the served set AND the monotonic-increase rule AND the "non-served commits skip" behavior. **After:** state the served set once, the guard behavior once. Keep the Format block and the "Why" untouched. **Saved:** ~350 bytes (~90 tok). **Lossless:** same rule, stated once within the section. ### S3 — Prohibited Patterns: shorten the 4 rows whose "Why" is copied from a protocol **Where:** the `skipWaiting`, `linkWithRedirect`, `signInAnonymously`, and PowerShell-non-ASCII rows (lines 719, 727–729). **Now:** each "Why" cell is a near-verbatim paragraph copy of Protocol 16/30/31/39 and *already ends with "(Protocol N)"*. **After:** keep the "Never Do" cell and a one-line why + the existing "→ Protocol N" pointer. Example — `linkWithRedirect` row why becomes: *"GitHub Pages can't host the redirect handler; mobile blocks the iframe fallback → sign-in silently fails. Full mechanism: **Protocol 30**."* **Keep untouched:** the rows with no protocol home (`innerHTML +=`, untrusted `innerHTML`, `localStorage` in audio hot paths, recursive key transform, inventory drops, auto-push) — those are the table's *only* copy of the rule. **Saved:** ~700 bytes (~175 tok). **Lossless:** the full mechanism lives in the named protocol; the table keeps the scannable prohibition + pointer. ### S4 — Protocol 2a: dedup the changelog-model restatement **Where:** the "Changelog versioning model" paragraph and the "Hotfix model" bullet list. **Now:** both independently explain that per-push test-count/cache updates go on `[Unreleased]` and never on a released entry, "the one sanctioned exception is a hotfix." **After:** state the Unreleased-vs-released rule once; the Hotfix bullets reference it rather than re-explaining it. **Saved:** ~300 bytes (~75 tok). **Lossless:** every distinct rule (pre-release / hotfix / new-version) preserved; the shared premise stated once. ### S5 — Reference Pointer Index: trim the 3-class intro restatement **Where:** the "3-class library maintenance model" + "Doc-maintenance rule" prose under the table. **Now:** the LIVE-class definition and "a stale LIVE doc is worse than no doc" appear in both the 3-class list and the doc-maintenance rule below it. **After:** state the "stale is worse than none" principle once; the per-doc rules reference it. **Saved:** ~250 bytes (~60 tok). **Lossless:** the table, the class assignments, and every per-doc obligation stay; one repeated sentence removed. **Safe-mechanical subtotal: ~2,150 bytes ≈ ~540 tokens across 5 changes.** Modest, zero-risk, and a clean first commit that can land without a sign-off round-trip. --- ## 4. NEEDS OWNER SIGN-OFF — judgment calls Each preserves the rule but touches something the owner may want kept inline (reference value, tone, or a bug-origin narration). Ranked by savings. ### J1 — Compress the Architecture Quick Reference load-order narration ⭐ BIGGEST WIN **Where:** "Script load order" — 31 numbered items, each with a full-sentence description of what the file does + a "(2.8.5 U-A4 split)" build tag. **The case for it:** this narration is (a) **self-admittedly drifted** — the doc's own Pointer Index says *"CLAUDE.md's own 'Architecture Quick Reference' narration has drifted in places (it self-flags this)"*; (b) **duplicated by `library/CODE_MAP.md`**, the canonical derived-from-source "where does X live" doc; and (c) **not guarded** — Suite 220 only checks the filenames + order, never the prose. A drift-prone, duplicated, unguarded 6.9 KB block is the textbook compression target. **After:** keep the guarded filename + order + a 3–6 word label per line (e.g. `js/ui/ui-render-inventory.js → CARGO MANIFEST & AMMO renderers`). Drop the full sentences and the "(unit split)" build tags. One pointer line at the top: *"Full per-file detail → `library/CODE_MAP.md` (derived from source, Protocol 46)."* **Saved:** ~3,200 bytes (~800 tok). **JUDGMENT:** the owner may value the inline at-a-glance reference even knowing it drifts. **Lossless-safe** because the load-order *contract* (what Suite 220 enforces) is untouched and the deep detail already lives, more accurately, in CODE_MAP.md. The only thing lost is a second, staler copy. ### J2 — Merge Protocols 32 + 33 + 35 into one "Remote Kill-Switch" protocol **Where:** 32 (ships with flag + fallback), 33 (read is fail-safe), 35 (auto-flip on regression). **After:** one section "Protocol 32/33/35 — Remote Kill-Switch" with three labelled parts **(a)** every networked feature ships a flag + graceful fallback, **(b)** the boot read is fail-safe (default features-enabled, never black-screen), **(c)** auto-flip off on detected post-deploy regression, restore-first. Shared "why a kill switch" framing stated once. **Saved:** ~500 bytes (~125 tok) + real cognitive win (one mental model, not three lookups). **JUDGMENT — low nuance risk:** all three rules are preserved verbatim as sub-parts; numbers retained so cross-refs resolve. Flag: confirm no external doc references "Protocol 33" as a standalone heading (Suite 220 checks references *from* the docs, so keeping the number string in the heading is sufficient). ### J3 — Group Protocols 29 + 30 + 31 under an "Authentication Hard Rules" heading **Where:** 29 (real-device mobile verify), 30 (popup-only, redirect banned), 31 (guarded anon sign-in). **After:** one "Authentication" super-heading with three sub-rules kept intact. The shared "GitHub Pages can't host the redirect handler / storage partitioning" premise (currently in both Protocol 30 and the Prohibited Patterns table) stated once and pointed to. **Saved:** ~400 bytes (~100 tok). **JUDGMENT:** each rule and its bug-origin (`getRedirectResult`-null, the 5c-ii clobber) stays verbatim. Pure grouping + one shared-premise dedup. Low risk. ### J4 — Compress the guard-explanation prose in Protocols 45 + 46 **Where:** both "enforcement arm" protocols carry multi-paragraph explanations of the gitignored-`library/` problem, why `MANIFEST.txt` is the committed exception, and exactly what tests 220.7/220.8 do differently on CI vs locally. **After:** keep (1) the **rule** — docs' code references must resolve; keep CODE_MAP + Pointer Index + MANIFEST current, manifest-entry-before-pointer; and (2) the **one-line why** — an honor-system doc drifted once (the `pushToCloud`/`pullFromCloud` incident), so the class gets a Suite 220 guard. Compress the CI-vs-local mechanics of 220.7/220.8 to a two-line summary + "see Suite 220 tests 220.7/220.8." The guard *is* the enforcement; the doc only needs to say the rule and that the guard exists. **Saved:** ~1,500 bytes (~375 tok). **JUDGMENT — owner-sensitive:** this is subtle, deliberately-written reasoning about a genuinely non-obvious CI edge case ("a naive existsSync check looked CI-safe but fails on a clean checkout"). Compressing it risks a future session re-deriving the trap. **Recommend:** compress but keep the one-sentence trap-warning verbatim ("`fs.existsSync('library/CODE_MAP.md')` would either fail every CI run or never run at all — the latter is worse than no guard"). That sentence is the load-bearing lesson. ### J5 — Protocol 40: compress the "when you must update test.html" list **Where:** the bulleted enumeration of when `test.html` must change. **After:** the enumeration largely restates Protocol 4 (new state field) and the import-contract surface. Compress to: *"Update `test.html` in the same commit whenever the import/sync contract, a state field, the boot chain, or a runtime-contract suite changes (the `test.html` analogue of Protocol 4)."* Keep the `Suites: N` marker rule, the game-agnostic requirement, and the Suite 96 / `test-html-check.mjs` enforcement note verbatim. **Saved:** ~500 bytes (~125 tok). **JUDGMENT:** the specific triggers are useful; compressing leans on Protocol 4 being read alongside. Low-moderate risk. ### J6 — Protocol 43: stop re-listing every protocol by number **Where:** the "Same bar on both branches" section enumerates ~10 protocols by number ("Protocol 1 applies… Protocol 2/2a applies… 38, 39, 41, 42, 36b… 13, 14, 19, 20…"). **After:** *"Every protocol in this document applies identically on `dev` — the full pre-commit/pre-push gate, cache bumps, doc sync, and every named rule. `dev` is held to `main`'s exact bar."* The exhaustive number list adds no rule; the principle is "all of them." **Saved:** ~450 bytes (~110 tok). **JUDGMENT:** the enumeration arguably signals emphasis. Removing it loses nothing normative (it literally means "all"), but the owner may want the emphasis. Low risk. ### J7 — Trim bare incident hashes / worked examples (keep every lesson) **Where:** scattered — Protocol 39's commit hashes (`48feb96`/`c108beb`), Protocol 42's WU-A5 precedent paragraph, Protocol 44's worked seven-event example, Protocol 8's plan-audit restatement. **After:** keep the *lesson* in full; trim the bare commit-hash citations and shorten the longest worked examples to one line. Example — Protocol 42 keeps "a harness step hit the beforeunload-flush clobber; investigation showed every shipped path is guarded, so it was harness-only but locked with Suite 95.8/95.9" and drops the surrounding restatement. **Saved:** ~600 bytes (~150 tok). **JUDGMENT — most owner-sensitive; recommend LAST or SKIP.** The owner "cares deeply — every protocol was born from a real bug." A commit hash is arguably prunable, but this is exactly the material he values. **Recommend:** present as optional; default to keeping unless he explicitly green-lights. **Judgment-call subtotal: ~7,150 bytes ≈ ~1,790 tokens across 7 changes** (or ~1,640 tokens if J7 is skipped). --- ## 5. Merges considered and REJECTED (nuance-loss risk too high) Stated so the owner sees they were evaluated, not missed: - **Protocol 13 + 42** (regression-test-required + fix-flaws-found-in-testing) — related but distinct scopes (shipped bug vs. flaw surfaced during dev), and 42 carries the "harness-only" classification nuance. **Keep separate**, cross-reference only. - **Protocol 26 + 27 + Protocol 8 plan-audit** (definition-of-done / reproduce-before-fixing / plan-audit) — overlapping philosophy but three distinct enforceable gates. Merging would blur which check is which. **Keep separate.** - **Protocol 22 + 23** (extend-before-creating / architectural-boundaries) — adjacent but 23 encodes the specific layering contract; folding it into 22 would bury the load-order boundary. **Keep separate.** - **The Reference Pointer Index table itself** — this is the navigation aid that makes the whole token-split strategy work (it's why `TEST_CATALOG.md`'s 55k tokens *aren't* loaded per session). **Do not compress the table**; it earns its bytes many times over. --- ## 6. Verification the eventual edit must pass (non-negotiable) When this plan is later implemented (a *separate*, owner-approved edit pass — not this doc): 1. **Full gate green** — `npm run gate` (lint, format, the 3276-test Node runner, and the push-boundary browser checks) must pass unchanged. A docs-only edit touches no served file, so **no `CACHE_NAME` bump** and no test-count change. 2. **Suite 220 green specifically** — every `window.*`, `js/…` path, `library/<file>` pointer, and the LOAD-ORDER-GUARD list must still resolve. J1 is the one change that goes near the guarded region; the filename list + order stay byte-identical, only prose labels change. 3. **No enforced rule dropped** — a reviewer diffs the before/after and confirms every numbered protocol heading still exists, every gate-guarded rule is still stated, and every bug-origin lesson is still present (compressed, never deleted). 4. **Record the before/after token count** in the commit (Protocol 26 definition-of-done): before ≈ 23,900 tokens; after = measured. --- ## 7. Bottom line - **Estimated total saving:** **~2,300 tokens (~10%)** if every change is accepted (~2,150 if J7 is skipped). Broken down: **~540 tokens safe-mechanical**, **~1,790 tokens judgment-call**. Honest framing — the doc is dense, not bloated; there is no 20% of pure fat to cut, and pretending otherwise would mean cutting rules, which the constraint forbids. - **Change counts:** **5 safe-mechanical** (land these first, no sign-off needed) vs. **7 judgment-call** (need owner sign-off; J7 recommended optional/skip). - **The single biggest win:** **J1 — compressing the Architecture Quick Reference load-order narration (~800 tokens, a third of the whole saving).** It's the safest big cut because that prose is self-flagged as drifted, is duplicated by `library/CODE_MAP.md`, and is *not* what Suite 220 guards — so the enforced contract is untouched and only a staler second copy goes away. - **Nothing enforced is dropped. Every bug-origin lesson stays. Suite 220 and the full gate stay green.**