--- name: parked-token-usage-audit description: "The durable rulings from the token-usage / readability / code-organization / test-health audit program — the readability north star, the comment philosophy, the coverage-preserving-consolidation guardrail, and the 3-class library maintenance model" metadata: node_type: project originSessionId: parked-token-usage-audit --- *Correction 2026-07-20: this file was a parked brief with a timing lock and a scope list. The timing window has passed and parts of the work have run — schedule, version pins, test counts, protocol numbers and "what has landed" have been stripped. Current roadmap state lives in `QUEUE.md`; what shipped lives in `CHANGELOG.md` + git log; architecture in `library/CODE_MAP.md`. What remains below is the reasoning and the owner's rulings, which do not expire.* ## The goal, in the owner's words Cut token usage across the whole workflow — orchestration plus the delegated build sessions — **without** weakening any of the owner's hard rules: the gate's guarantees, notify-on-everything, the self-improving guards, free/BYO-key, game-agnostic. **Savings come from efficiency, never from dropping safety or transparency.** Owner also asked for depth, twice: the first pass was too shallow, and he wanted it re-run **"EXPANDED AS MUCH AS POSSIBLE — go in depth this time."** Separately: *"why you rushing yourself? I told you take your time with the token audit."* ## ⭐ THE STRUCTURAL INSIGHT (owner-surfaced) — the thing the first pass missed The always-loaded instruction file is paid for by **every** session regardless of relevance, and much of its bulk is **reference history, not load-bearing rules**. Owner asked whether moving it to a referenced library and pointing the AI at it would save tokens — **yes**. **The split:** keep the load-bearing rules inline (needed every session); move exhaustive reference/history into a library read **on demand**. Wins: smaller always-loaded context every session, and cheaper doc-sync because reference changes stop editing a giant inline block. Tradeoff: read-on-demand costs tokens only *when* a session needs the detail — a net win for rarely-needed history, while inline stays right for actual rules. **⭐ AUTOMATIC POINTERS (owner directive — load-bearing for the whole model):** *"ensure anything the Claude AIs will need to look at in the code library, they automatically get pointed at; protocol/rule or not."* The on-demand split only WORKS if sessions can FIND the material. So: a SMALL always-loaded **pointer index** (topic → library path) plus per-area pointers (per-file header comments, a "start here" entry point). Make it a rule: whenever code or a library doc moves, update the pointer index in the same commit, gate-guarded where feasible so a stale pointer fails the build. **A session must never have to guess where the relevant reference lives.** **RENAME (owner):** "Prompt Library" → just **"Library"** — it became more than prompts (reference content, appendices, framings, briefs). ## ⭐ READABILITY — THE NORTH STAR Owner: **"take someone who has never seen the code, they look at it, and are able to just understand it cleanly."** That sentence is the guiding goal of all code-organization work — a newcomer opens the codebase and understands it with minimal ramp. What serves it, in rough order of leverage: 1. **A "START HERE" onboarding narrative** — guided tour of the mental model + data flow + "where does X live" + a recommended READING ORDER. The single biggest newcomer lever. 2. **Documented DATA SHAPES** — one canonical reference of the state object, the AI schema, a game-definition entry, the save envelope. In a stateful app this is a newcomer's #1 need. 3. **A GLOSSARY** of domain and internal terms, so the vocabulary decodes. 4. **A per-file HEADER STANDARD** — purpose, responsibilities, what it exposes, load-order slot, entry points, dependencies. 5. **Documented NAMING CONVENTIONS** written down once, so names are guessable. 6. **Small, intention-revealing FUNCTIONS** — the top level should read like prose; replace clever one-liners with clear equivalents; rename cryptic vars. (The GOOD kind of rename — clarity, not flavor.) 7. **DATA-FLOW / LIFECYCLE maps** — boot, save/load, AI request lifecycle, the event bus, the render pipeline. 8. **Magic numbers/strings → NAMED CONSTANTS** with a why-comment. 9. **Consistent COMMENT MARKERS** (`// WHY:`, `// GOTCHA:`, `// TODO:`) so comments are scannable. 10. **AUTOMATED enforcement** — lint rules for depth, function length, complexity, consistent return, naming, plus a soft max-file-size guideline, so clarity is gate-enforced and can't rot. 11. **"HOW WE DO X" recipes** — surface the existing protocols as newcomer-facing guides. Plus: split oversized modules by responsibility, section dividers, a dead-code sweep, a code map, dedupe of parallel helpers, a CSS audit, consistent function ordering. **Every change stays behavior-identical and gate-green.** **⚠️ HARD CONSTRAINT on any split:** the app loads plain global-scope scripts in a **fixed order**. Any split must preserve load order and global availability, and re-sync every place that names a file — the file manifest, the service-worker asset list, the script tags, the packing config, the boot-order guards. The refactor is only "done" when every rule or doc that names a file/function/path has been corrected in the SAME commit. ## ⭐ COMMENT PHILOSOPHY — my professional pushback, which the owner accepted The owner initially asked to "comment everything." My counter, adopted: **document the WHY, not the WHAT** — intent, gotchas, rationale, edge cases, non-obvious decisions. Do NOT comment every line or obvious code: line-by-line narration goes stale, bloats context (cutting directly against the token goal), and hides the signal. **Self-documenting names plus targeted WHY-comments beat wall-to-wall narration.** ## ⛔ REJECTED — code immersion / diegetic identifier naming Owner 2026-07-08: **"scrap that entirely."** The idea of naming code identifiers diegetically is DROPPED. **Readability wins over flavor in the source.** Do not re-propose it. The energy went into readability instead. ## TEST HEALTH — strength AND efficiency, with a hard guardrail Pair the gap-finding audit ([[parked-test-strength-audit]]) with a consolidation audit into ONE "test health" pass: strength (add what's missing) + efficiency (cut redundancy). **⚠️ HARD GUARDRAIL: this is COVERAGE-PRESERVING CONSOLIDATION, NOT count-cutting for its own sake.** The escape-ratchet rule means every escaped bug ADDED a test — so removing a test risks removing a real regression guard. **ONLY remove:** exact duplicates, tests superseded by a stronger test on the same path, and dead tests for removed features. **ONLY combine** where the merged test has IDENTICAL coverage. **NEVER reduce real coverage to lower a number.** Analysis-only first — propose each removal with its coverage-equivalence argument; the owner approves each. Rest of the pass: - **Assertion-strength / anti-vacuous audit** — find tests that would pass even if the feature broke (e.g. "it renders" with no result check, over-mocked tests that never touch real code). Different question from coverage: *do the existing tests actually catch regressions?* - **Static → behavioral balance** — tests that grep the source for a literal are brittle and can be vacuous (a string existing ≠ it working). Convert where appropriate, while keeping the deliberately load-bearing source-invariant guards. - **★ REFACTOR-RESILIENCE PREP** — find tests that reference exact function names or line-fragile literals that a rename or file-split would BREAK, and harden or flag them. **Do test-health BEFORE/WITH the refactor, not after — the two are COUPLED.** - **Flaky-test hardening** — there have been real harness flakes (stdin-pipe corruption, cross-suite async ordering). Find the flake sources. - **Gate-speed profiling** — find the slowest tests so the gate stays fast as it grows. - **Test-file readability** — the runners are large; the code-org standards apply to them too. ## ⭐ LIBRARY MAINTENANCE MODEL — 3 CLASSES (owner-agreed 2026-07-11) **Design this in from the START, or every library doc becomes a maintained doc and the library becomes a second codebase that rots.** 1. **LIVE — maintained + gate-guarded.** Docs that DESCRIBE THE CODE: the brain dump, the code map, the data-shape reference, the glossary, the "START HERE" doc, the queue, the pointer index. If these drift they don't just go stale — they make the next session **confidently wrong**, which is worse than having no doc at all. These are what the doc-reference-integrity guard exists to protect. 2. **⭐ GENERATED — never hand-maintained (the big win).** A hand-written, hand-synced catalog is *precisely why* doc-sync is tedious and why counts and descriptions keep drifting. It should be **generated from the source itself**, so it is correct by construction and the sync burden disappears. **General rule: if a doc can be generated from the source, generate it — that beats guarding it.** Audit the whole library for anything else derivable (load order, flag lists, tool registries). 3. **ARCHIVE — frozen, never updated.** Every audit doc, plan, slate, mockup and design snapshot. These are POINT-IN-TIME records and updating them destroys their value. Stamp each with a date and a "snapshot as of X — not current truth" header so no session mistakes one for the live picture, then leave them alone permanently. Plus a 4th, outside the library: the **PORTABLE BRIEF** for external models is GENERATED ON DEMAND from the brain dump and **never stored** — it cannot go stale because it is always new. Net: the real maintenance burden collapses to a small LIVE set, most of it gate-checkable. Everything else is auto-generated or deliberately frozen. ## ⚠️ SCOPE CAUTION This program kept growing by accretion into a super-phase. **Prioritize and sequence within it** — readability, test-health and the library split are the spine; performance, accessibility and asset-size are high-value; the rest slot by ROI. **Do not do everything at max depth in one blind pass — synthesize and order first.** Related: [[parked-code-quality-audit]], [[parked-test-strength-audit]], [[parked-performance-audit]], [[parked-accessibility-audit]], [[session-management-rule]], [[opus-plan-sonnet-implement-workflow]], [[always-acknowledge-actions]], [[prompt-library-campaign-framings]].