# R2 — Rules Restructure: what changed, where everything went, what R3 should consider **Snapshot 2026-07-20.** Deliverable for roadmap item R2. ARCHIVE-class once R3 runs. **Scope discipline held: nothing was deleted.** Every protocol that existed before this unit still exists, at its own number, in exactly one place. The R3 candidate list at the bottom is a *proposal for the owner to review* — none of it was acted on. --- ## 1. The new shape The rulebook is two layers instead of one 101KB file every session read end to end. | Layer | File(s) | Read when | | ----- | ------- | --------- | | **Universal contract** | `CLAUDE.md` (~34KB) | Every session, always | | **Subsystem notes** | `rules/*.md` (10 files) | Only when that surface is touched | `CLAUDE.md` now holds, in this order: how the rulebook works · the **retrieval map** · the Reference Pointer Index · the gate block · the universal contract (11 protocols) · session & orchestration (8 protocols) · the retired protocols · the Prohibited Patterns table · a short architecture pointer block. **What made the contract cut.** The reviewer's candidate list was assessed against the real document rather than adopted wholesale: | Reviewer's candidate | Verdict | | -------------------- | ------- | | Fallout data from fallout.wiki | **Kept** — Protocol 3, whole (it is two lines and its second half, "ARCHITECTURE.md is canonical", is universal too) | | Reproduce or trace before fixing | **Kept** — Protocol 27 | | Extend before creating a parallel system | **Kept** — Protocol 22 | | Restore production before diagnosing | **Kept** — Protocol 16 | | Auth changes need real-device testing | **Moved to `rules/auth-and-cloud.md`.** Rejected for the contract: the rule is inseparable from its mechanism (the Firebase redirect-handler / storage-partitioning explanation), which is long and useless to a session not touching auth. The retrieval map is the salience mechanism here, not the contract. | | Cross-subsystem / high-risk changes get an independent diff audit | **Kept** — this is Protocol 8 stage 3, in Session & Orchestration | | Code wins over documentation | **Kept, and made explicit** — it existed only as an aside under the pointer index; it is now a numbered bullet of Protocol 3 | **Added to the contract beyond the reviewer's list**, because they apply to every commit and need judgement: Protocol 26 (definition of done), 23 (architectural boundaries), 13 (regression test required), 42 (fix flaws found during testing), 36 (gate parity + escape-ratchet), 49 (the retirement rule), 43 (branch model), 2 (docs in the same commit). **Session & orchestration** (8, 9, 12, 18, 19, 28, 41, 48) stayed in `CLAUDE.md` for a specific reason: no file path triggers them. A note nothing routes to is a rule nobody retrieves — the exact failure this unit exists to fix. --- ## 2. The file → notes mapping | Touching | Note | | -------- | ---- | | `js/core/state.js`, `js/core/idb.js`, `js/core/runtime.js`, `js/services/api-import.js`, any new `state` field | `rules/state-and-save.md` | | `sw.js`, `index.html`, `manifest.json`, icons, `css/`, `js/`, `.github/workflows/`, any live-site push | `rules/deploy-and-cache.md` | | `js/services/cloud.js`, `js/ui/ui-account.js`, `firestore.rules`, any sign-in flow, any new network/IO feature | `rules/auth-and-cloud.md` | | `index.html`, `css/`, `js/ui/`, any user-visible change | `rules/ui-and-mobile.md` | | `js/ui/ui-audio.js`, the `AudioSettings` cache, the Audio Systems panel | `rules/audio.md` | | `js/data/`, `GAME_DEFS`, the `GAME_FILES` manifest, any per-game branch | `rules/game-data.md` | | `js/services/api*.js`, the Tri-Node schema | `rules/ai-contract.md` | | Boot-order changes, any file split/add/move/delete, `repomix.config.json`, non-ASCII files | `rules/file-layout.md` | | `tests/`, `scripts/`, `js/dev/test-console.js`, new events/flags, safeguards | `rules/testing-and-gates.md` | | `CHANGELOG.md`, `README.md`, `ARCHITECTURE.md`, `CLAUDE.md`, `rules/`, `library/`, `planning/` | `rules/docs-and-library.md` | --- ## 3. Where every protocol landed (the survival ledger) Nothing vanished. **Bold = moved out of `CLAUDE.md`.** | # | Protocol | Home | | - | -------- | ---- | | 1 | Service Worker Cache Bump | **`rules/deploy-and-cache.md`** | | 2 | Documentation Updates (+ changelog placement model) | `CLAUDE.md` — contract | | 2a | Test Count Sync — RETIRED | `CLAUDE.md` — retired, in place | | 3 | Source of Truth (+ new "code beats docs" clause) | `CLAUDE.md` — contract | | 4 | Adding a New State Field | **`rules/state-and-save.md`** | | 5 | Adding a New UI Panel | **`rules/ui-and-mobile.md`** | | 6 | Registry Autocomplete Input | **`rules/ui-and-mobile.md`** | | 7 | Adding a New Audio Source | **`rules/audio.md`** | | 8 | Dispatch Multi-Model Workflow | `CLAUDE.md` — session | | 9 | Dispatch Reporting | `CLAUDE.md` — session | | 10 | UI Verification | **`rules/ui-and-mobile.md`** | | 11 | Deploy Verification | **`rules/deploy-and-cache.md`** | | 12 | No Concurrent Pushes | `CLAUDE.md` — session | | 13 | Regression Test Required | `CLAUDE.md` — contract | | 14 | AI Contract Safety | **`rules/ai-contract.md`** | | 15 | Test-Runner Parity — RETIRED | `CLAUDE.md` — retired, in place | | 16 | Hotfix / Rollback | `CLAUDE.md` — contract | | 17 | Mobile Baseline | **`rules/ui-and-mobile.md`** | | 18 | Memory Maintenance | `CLAUDE.md` — session | | 19 | Batch Before Push | `CLAUDE.md` — session | | 20 | Static Source-Invariant Guards | **`rules/testing-and-gates.md`** | | 21 | Plain-English Changelog | **`rules/docs-and-library.md`** | | 22 | Extend Before Creating | `CLAUDE.md` — contract | | 23 | Architectural Boundaries | `CLAUDE.md` — contract | | 24 | AI Determinism | **`rules/ai-contract.md`** | | 25 | UX Stability | **`rules/ui-and-mobile.md`** | | 26 | Definition of Done | `CLAUDE.md` — contract | | 27 | Reproduce Before Fixing | `CLAUDE.md` — contract | | 28 | Usage Efficiency | `CLAUDE.md` — session | | 29/30/31 | Authentication Hard Rules | **`rules/auth-and-cloud.md`** | | 32/33/35 | Remote Kill-Switch | **`rules/auth-and-cloud.md`** | | 34 | Cloud Writes Additive (+ cloud-sync determination) | **`rules/auth-and-cloud.md`** | | 36 | Gate Parity & Escape-Ratchet | `CLAUDE.md` — contract | | 37 | Keep repomix.config.json Current | **`rules/file-layout.md`** | | 38 | Game-Agnostic Feature Code | **`rules/game-data.md`** | | 39 | UTF-8 Source Integrity | **`rules/file-layout.md`** | | 40 | Keep `tests/test.html` In Sync | **`rules/testing-and-gates.md`** | | 41 | End-of-Task Cleanup Sweep | `CLAUDE.md` — session | | 42 | Fix Flaws Found During Testing | `CLAUDE.md` — contract | | 43 | Dev-Branch Workflow | `CLAUDE.md` — contract | | 44 | Diagnostic Shell Trigger | **`rules/testing-and-gates.md`** | | 45 | Documentation Reference Integrity | **`rules/docs-and-library.md`** | | 46 | Keep Code Map + Pointer Index Current | **`rules/docs-and-library.md`** | | 47 | *(reserved — catalog generator)* | referenced in both, unassigned | | 48 | Back Up the Local-Only Artifacts | `CLAUDE.md` — session | | 49 | The Retirement Rule | `CLAUDE.md` — contract | | UI-1…UI-7, UI-9, UI-10 | all UI protocols | **`rules/ui-and-mobile.md`** | | — | Prohibited Patterns table | `CLAUDE.md` (whole) + restated per note | | — | Script load order + LOAD-ORDER-GUARD markers | **`rules/file-layout.md`** | | — | 3-class library model + doc-maintenance rule | **`rules/docs-and-library.md`** | | — | Reference Pointer Index | `CLAUDE.md` (kept, trimmed) | --- ## 4. Enforcement moved with the content (same commit) Per Protocol 49 — relocating rule text without relocating its guard would have silently halved Suite 220's coverage while still reporting green. - `readRulebook()` / `ruleNoteFiles()` / `rulebookFiles()` helpers added to the runner. Every "is rule X codified?" assertion (96.8, 154.18, 155.16, 208.27, 212.15) now reads the whole rulebook, not just `CLAUDE.md`. - **220.1 / 220.2** scan the notes too; 220.2's path regex gained the `rules/` prefix and `.md`. - **220.3** reads the load-order block from `rules/file-layout.md` (markers moved verbatim). - **220.9** parses the defined-protocol set from every rulebook file, and records which file defines each id. - **220.13 (new)** — every protocol number is defined by a heading in exactly **one** rulebook file. This is the restructure's core safety property: a rule copy-pasted into a second note would start drifting immediately. - **220.14 (new)** — `CLAUDE.md` reaches every note on disk and names none that is missing. A note nothing routes to is a rule nobody retrieves. - All three new/moved guards were **red-tested**: duplicating a heading, naming a phantom note, and corrupting the load-order list each fail the build as intended. - `repomix.config.json` gained `rules/**` to its private-agent-file ignore list (Protocol 37). --- ## 5. R3 CANDIDATES — proposed cuts, NOT applied The owner reviews this list before R3 runs. Ordered strongest case first. Each entry states what would be lost, because a retirement that hides its cost is the failure Protocol 49 names. **C1 — Protocol 12 (No Concurrent Pushes).** One sentence restating a git fact any session already knows, that no mechanism enforces and no incident is on file for. *Lost:* nothing mechanical; the coordination intent is already implied by Protocol 19 (batch before push). *Counter-argument:* it is nearly free to keep. **C2 — Protocol 18 (Memory Maintenance).** Generic "keep memories current, don't store transient state" guidance that duplicates the harness's own memory instructions verbatim. It teaches nothing project-specific. *Lost:* nothing — the same rule arrives with the agent. **C3 — Protocol 5 and Protocol 6 (adding a UI panel / an autocomplete input).** Step-by-step checklists that go stale every time the render layer is split, and the render layer has now been split three times (U-A1, U-A2, U-A4). Both still say "`render*()` in `ui-render.js`" when the render pipeline is nine files. *Lost:* real onboarding value — but the accurate version of this information is `library/CODE_MAP.md`, which is derived from source and cannot rot the same way. **Recommendation: replace with a pointer, do not simply delete.** **C4 — Protocol 37 (keep repomix.config.json current).** Guards one config file's `include` list. Nothing has ever broken because of it, and a stale repomix config is self-announcing (the pack is visibly missing files). *Lost:* a small early-warning; the failure is cheap and obvious. **C5 — Protocol 9's third paragraph (mobile formatting of Dispatch reports).** Duplicates the second paragraph's intent at greater length. *Lost:* nothing; merge into one paragraph. **C6 — Protocol 8's "Why" paragraph.** ~120 words justifying a workflow the same section already specifies procedurally. The rationale is worth one sentence, not a paragraph. *Lost:* the explanation of why Fable is named explicitly — worth preserving in compressed form. **C7 — The "Pending protocol amendments" paragraph in Protocol 38.** A status ledger of which Design Overhaul amendments have landed, embedded inside a rule about game-agnostic code. It is roadmap state, not a rule, and it belongs in `QUEUE.md` or the build plan. *Lost:* nothing — relocate rather than delete. **C8 — Protocol 45's "Ratchet intent" and "Scope decision" paragraphs.** Excellent reasoning, but it is design rationale for a guard that already exists and is already tested. *Lost:* the argument for staying narrow, which a future session might re-litigate. **Weakest candidate on this list — flagged for completeness, recommend keeping.** **Explicitly NOT candidates (keep-cases under Protocol 49):** the architecture-conformance baseline (its risk stays live until 3.0 ES modules make layering structural — this is the canonical keep-case); Protocols 29/30/31 (real-device auth; a real production regression is on file); Protocol 39 (UTF-8 integrity; a real corruption incident is on file with a commit hash); Protocol 34 (cloud write safety; the failure is unrecoverable data loss); Protocol 1 (cache bump; failure is silent and user-visible). **Suggested R3 shape:** take C1, C2, C5, C6, C7 (pure weight, nothing lost), convert C3 to pointers, and leave C4 and C8 alone. That is one reversible commit, which is what R3 asks for.