# Health Batch — Scoping & Build Order **What this is.** The deferred 2.8.5 "code + test health" batch (QUEUE.md items **1c** + **2**) turned into a concrete, ranked, ready-to-build unit list. Analysis only — no code changed, nothing committed. **Snapshot:** branch `dev`, clean at `1564aec`, 2026-07-15. > **PROGRESS (2026-07-15):** ✅ **U1** (offline-first behavioral test + commit boot-smoke) shipped `4aec149`, audited. ✅ **U6** (protocol consolidation, pulled forward) shipped `09c1e73`, audited — ~1,074 tokens saved, lossless. ⏸ **DEFERRED TO LAST — the protocol-reference-integrity guard** (a Suite-220 check that every `Protocol N` reference resolves; surfaced by the U6 audit as a discipline-only gap). **Owner directive (2026-07-15): run it as the FINAL health step, after ALL other passes settle** — protocol structure and test counts are still in flux (more merges expected), so building it now means rebuilding it against a moving target. Do NOT pick it up until the batch is otherwise complete. **What this is NOT.** Not a re-run of the big reviews already done (architecture, deep-systems, gate, reframing). Those conclusions are settled and are the input here, not the subject. This pass measures the current state with real numbers and turns the batch into units you can pick up one at a time. --- ## 1. The baseline nobody had — measured, not guessed Every number below was grepped from the repo today. This is the missing baseline. ### The headline: the gate checks that the source LOOKS right, not that the app WORKS The single canonical test runner (`tests/robco-diagnostics.js`) holds **234 suites / ~3,272 tests**. I classified every suite by how it actually checks things: | How the suite checks | Suites | Share | | --- | --- | --- | | **Pure static** — reads the source as text, greps it with string/regex matches. Never runs the code. | **175** | **75%** | | **Behavioral (in-process)** — actually executes app code in a sandbox and checks the result. | 59 | 25% | | **Behavioral (browser)** — opens a real browser. | **0 of 234** | **0%** | - Weighted by individual assertions it's a touch better but the same story: of ~2,756 assert-calls, at most ~1,005 (**36%**) live in a suite that runs *any* code — and even those suites mix static greps in, so the true "executes code" share is lower. - The runner does **4,706** `.includes()`/regex `.test()` calls against source text. That is the dominant mechanism by a wide margin. - **Not one of the 234 in-runner suites opens a browser.** Every browser-level check lives in 5 separate `.mjs` files. **This independently confirms the gate review's "65–75% static" finding.** It's 75% by suite. The raw test count measures how *greppable* the source is, not that the app *works* — which is exactly how a whole panel (MANIFEST) once rendered completely invisible under a fully green gate. ### The commit gate opens zero browsers — the browser checks are push-only The gate is split at the commit/push line (`scripts/gate.js`): - **Commit (`gate:fast`, ~12.7s per the QUEUE):** lint, format, boot-chain preflight, the Node runner. **Steps 5–9 (every browser check) are skipped.** - **Push / CI (`gate` full):** adds the browser checks — boot-smoke, render-check (which runs `render-integrity`'s 12-config matrix), a11y baseline-diff, `test.html` runtime audit, save-survival. So at the moment you commit, **nothing has opened a browser.** The render-integrity guard — the "make green mean the user can see it" pattern that caught the dock fix — exists and works, but it only fires at **push**, not commit. Between committing and pushing, green means "the source greps clean," nothing more. ### Per-session load cost (what every work session pays on open) - `CLAUDE.md` (the rules doc, loaded every session): **95 KB ≈ 24k tokens.** - `MEMORY.md` index: ~1 KB (negligible). - `library/TEST_CATALOG.md`: 220 KB (~55k tokens) — **not** loaded per session; it's a pointer target read on demand. Good — that's the token split working. - **Protocol inventory:** 46 numbered protocols + 9 UI protocols = **55 protocol sections**, 2 marked retired. Net-positive over time (many added — data-provenance guards, etc. — only Protocol 15 truly retired). The rules doc is the one fixed cost paid on *every* session. ### Cheap perf / bundle / a11y baselines - **Boot JS payload (served, excludes lazy Tesseract):** ~**1.52 MB** across 30 files, unminified. - **CSS:** ~516 KB across 13 files. **index.html:** 245 KB. **Rough uncompressed boot weight: ~2.3 MB** (Pages CDN applies brotli over the wire, but there is **no minification** step in the pipeline). - **Biggest single served file: `js/dev/test-console.js` at 204 KB** — the Diagnostic Shell. It ships to **every production user** even though prod users can never unlock it. That's ~13% of the boot JS that no prod user can use. Clear bundle-size target. - **Vendored Tesseract OCR: ~7 MB** — correctly lazy-loaded (never at boot). Leave it. - **Accessibility baseline (`tests/a11y-baseline.json`) = 40 accepted violations** the gate currently tolerates: **30 `label`** (form inputs missing labels), 4 `select-name`, 3 `label-title-only`, 2 `color-contrast`, 1 `scrollable-region-focusable`. A concrete number to burn down. --- ## 2. The batch, broken into concrete units Each unit: what it is · what "done" looks like · rough size · dependencies · leverage against "green must mean it works." ### Tier 1 — Makes green actually mean "it works" (highest leverage) **U1 — Offline-first behavioral test + a fast commit-gate boot smoke.** ⭐ *Build first — full detail in §4.* Prove, in a real browser, that the app **boots and stays usable with the network cut** — not "the source looks offline-safe." Add a lightweight boot smoke that can run at the **commit** boundary so commit-green means "it boots," closing the biggest gap in §1. *Done:* a headless test cuts the network, loads the app, asserts it reaches READY and a core screen renders + a native tool works offline; a fast boot check runs pre-commit. *Size: M. Deps: none (harness exists).* **U2 — Assertion-strength + dedup + test-strength audit (the measurement that steers U3).** Read the 175 static suites and rank them: which assert something real, which are tautological/existence-only greps, which duplicate each other. Produce a coverage-preserving dedup list and a "convert-me" hit-list. *Done:* a ranked ledger — weak asserts, redundant suites (with proof they're redundant), and the top static suites worth making behavioral. *Size: M. Deps: none. Feeds U3.* **U3 — Convert the highest-value static suites to behavioral (phased).** The structural fix for the 75%. Take U2's hit-list and rebuild the highest-value static greps as in-process/browser behavioral checks, coverage-preserving. Phased — never a big-bang rewrite. *Done:* the top-ranked static suites now execute code and assert results; suite count holds or the delta is explained. *Size: L (multi-pass). Deps: U1 harness + U2 hit-list.* **U4 — CI failure-evidence packaging.** When the push/CI gate goes red, capture screenshots + logs + artifacts so the failure is diagnosable without a re-run. Named home in QUEUE 1c. *Done:* a red browser-check run uploads a screenshot + console/network log + the failing assertion as CI artifacts. *Size: S. Deps: none (nice after U1 adds browser coverage).* **U5 — Gate profiling + flaky-test hardening.** Nobody has a per-step wall-time breakdown of the gate. Produce one, then harden any flaky browser check (shared-Chromium races, timing waits). *Done:* a per-step timing table + any flaky check made deterministic. *Size: S. Deps: none.* ### Tier 2 — Per-session cost (owner-facing efficiency) **U6 — Session-load-cost pass: protocol-consolidation + token-usage audit (merged).** The rules doc is ~24k tokens on every session. Losslessly restructure and de-duplicate it — merge overlapping protocol prose, collapse repeated examples — **without dropping any enforced rule.** Fold in the expanded token-usage audit (they're the same measurement). *See recommendation, §5 — candidate to pull forward.* *Done:* rules doc materially smaller in tokens, every enforced rule still present and still gate-guarded, a before/after token count recorded. *Size: M. Deps: none (pure docs).* ### Tier 3 — Measured user-facing improvements (QUEUE item 2) **U7 — Bundle-size + caching audit + measured cuts.** Headline: stop shipping the 204 KB dev-only Diagnostic Shell to prod users (lazy-load or prod-strip it), add a minification step, verify Pages caching/compression headers. *Done:* measured before/after boot-payload drop; dev console no longer in the prod boot path; caching verified. *Size: M. Deps: none (U5's profiling helps target).* **U8 — Performance audit + measured improvements.** Real mobile load/runtime perf: list virtualization for long inventories, lazy panel render, render-cost cuts. Measured, not guessed. *Done:* before/after numbers on a phone-class profile for the named hotspots. *Size: M–L. Deps: overlaps U7 on payload.* **U9 — Accessibility baseline burn-down.** Drive the 40 accepted violations down — the 30 missing `label`s are the bulk and are mechanical. Beyond-baseline pass (keyboard nav, landmarks) as a stretch. *Done:* baseline count materially lower (target the 30 labels first); `a11y-baseline.json` shrinks and the gate holds the new, lower bar. *Size: M. Deps: none.* ### Tier 4 — Hygiene (real, lower leverage) **U10 — Leftover offline-network sweep (measurement only).** Sweep for any external-network dependency in the install/boot/offline/local-save path. ⚠ The permanent **CDN chokepoint guard** is explicitly owned by 2.9.0's trust-boundary audit — do **not** rebuild it here; this unit is just the measurement that feeds it. *Done:* a finite list of every external fetch on the critical path, each classified core-vs-optional. *Size: S. Deps: none.* **U11 — Dependency / security hygiene.** `npm audit`, dependency freshness, sanity-check the vendored Tesseract. *Done: clean audit or a recorded triage. Size: S. Deps: none.* **U12 — Residual code-quality sweep.** The big readability refactor already shipped (strand a). This is only the leftover: dead-code, naming stragglers, small smells the restructure didn't reach. *Done: a short cleanup pass, no behavior change. Size: S. Deps: none. Lowest leverage — the headline code-quality work is already done.* --- ## 3. Ranked build order Highest-leverage-first, ranked against "green must mean the user can see it": 1. **U1** — Offline-first behavioral test + fast commit-gate boot smoke ⭐ 2. **U2** — Assertion-strength + dedup audit (steers U3) 3. **U6** — Session-load-cost / protocol-consolidation *(pull forward — pure docs, zero code risk, paid every session; see §5)* 4. **U3** — Convert top static suites → behavioral (phased) 5. **U4** — CI failure-evidence packaging 6. **U5** — Gate profiling + flaky hardening 7. **U7** — Bundle-size cuts (strip the 204 KB dev console from prod) 8. **U9** — Accessibility baseline burn-down 9. **U8** — Performance audit + measured cuts 10. **U10** — Offline-network sweep (measurement; guard is 2.9.0) 11. **U11** — Dependency / security hygiene 12. **U12** — Residual code-quality sweep U6 is slotted at #3 because it's pure-docs and independent — it can run in parallel with U1/U2 without touching the same files. --- ## 4. The single top unit to start now — U1 **U1 — Offline-first behavioral test + a fast commit-gate boot smoke.** **Why it's #1.** It hits the exact gap the whole batch exists to close: today, commit-green means "source greps clean" and 0/234 suites open a browser. Two named test-health homes (the real offline-first test + making green mean it-works) collapse into this one unit. It's self-contained, needs no other unit first, and is independently shippable. **Two pieces:** 1. **Real offline-first behavioral test** (new `.mjs`, push-gate). In a headless browser: load the app, then **cut the network** (block all requests / `context.setOffline(true)`), reload, and assert the app **reaches READY, renders a core screen, and a native tool actually works** (e.g. run a THREAT or LOOT calc, or a stat edit — all designed to work with no AI/network). This proves the offline-first promise behaviorally, replacing today's "the source looks offline-safe" static checks. 2. **Fast commit-gate boot smoke.** A minimal single-page-load headless check cheap enough (~3–5s) to run inside `gate:fast` at the **commit** boundary, so commit-green finally means "it boots and paints," not just "it greps clean." Keep it deliberately tiny — one load, assert READY + no console errors + the first board is visible — so it doesn't blow the ~12.7s fast-gate budget. **Acceptance criteria (Protocol 26):** - Offline test: passes on a good build; **fails loudly** if the app can't boot or a native tool breaks offline (verify by temporarily breaking one, red-then-green). - Commit smoke: runs in `gate:fast`, adds only a few seconds, catches a deliberately-broken boot. - New tests counted + synced everywhere (Protocol 2a); regression discipline (Protocol 13/42) — anything the new tests surface gets fixed in the same commit. - Reuse the existing shared-Chromium harness (`browser-server.mjs`) — don't cold-launch a second browser (Protocol 22). **Watch-outs:** keep the commit smoke genuinely fast or it'll get disabled; make "offline" a true network cut, not a mocked flag; don't duplicate boot-smoke.mjs — extend the harness. --- ## 5. Protocol-consolidation — recommendation **Recommendation: PULL IT FORWARD as its own early unit (U6, build-order #3), but scope it strictly as *lossless* restructuring.** **Why pull it forward.** It's the only item in the batch that reduces a cost paid on **every single session** — the ~24k-token rules doc loads whether or not the work needs it. It's **pure docs: zero code risk, no test-harness dependency**, so it can run in parallel with U1/U2 without collision. Every session before it lands overpays; every session after benefits. That's a compounding return the test-health units don't have. **The hard constraint that makes it safe.** The protocol count is **net-positive on purpose** — the protocols encode real bugs and hard-won rules (the data-provenance guards, the auth clobber fixes, the UTF-8 incident). Consolidation must **never** be deletion. The rule is: **merge and de-duplicate the prose, collapse repeated examples, tighten wording — but every enforced rule stays present and every gate-guarded protocol stays gate-guarded.** If the token count drops, it must be because the *same rules are said once instead of three times*, never because a rule left the building. Suite 220's doc-reference integrity guard already protects against silently dropping a referenced protocol — lean on it. **What it should NOT do.** It should not re-litigate any protocol's substance, retire rules, or "simplify" by loosening enforcement. It's a compression pass on the words, not a policy change. **Bottom line:** yes — unbundle it from the test-health strand and run it early as a lossless doc-compression unit, because it pays back on every session and can't collide with the code work. --- ## Summary (the four asks) - **Static-vs-behavioral (the headline):** **175 of 234 test suites (75%) are pure static source-text greps that never run the code; 0 of 234 open a browser.** The commit gate opens zero browsers at all — every browser check is push-only. Green currently means "the source greps clean," not "the user can see it." This independently confirms the gate review's 65–75% figure. - **Ranked units (one line each):** 1. **U1** Offline-first behavioral test + fast commit-gate boot smoke ⭐ 2. **U2** Assertion-strength + dedup audit (steers U3) 3. **U6** Session-load-cost / protocol-consolidation (pull forward, pure docs) 4. **U3** Convert top static suites → behavioral (phased) 5. **U4** CI failure-evidence packaging 6. **U5** Gate profiling + flaky-test hardening 7. **U7** Bundle-size cuts (strip 204 KB dev console from prod) 8. **U9** Accessibility baseline burn-down (40 accepted violations → down) 9. **U8** Performance audit + measured cuts 10. **U10** Offline-network sweep (measurement; guard is 2.9.0) 11. **U11** Dependency / security hygiene 12. **U12** Residual code-quality sweep - **Build first:** **U1 — the offline-first behavioral test + a fast commit-gate boot smoke.** It closes the exact gap the batch exists for (make green mean it boots and paints, in a real browser, offline), it's self-contained, and it needs nothing else first. Full spec in §4. - **Protocol-consolidation:** **Pull it forward** as its own early doc-only unit — it's the one item that cuts a cost paid every session (~24k tokens) and carries zero code risk — **but constrain it to lossless restructuring:** merge and de-duplicate prose, never drop an enforced or gate-guarded rule.