# ROADMAP_AUDIT.md — Analysis-Only Audit of Parked v2.8.0 (Round 2) + v2.9.0 (Round 3) > **FILED UNDER 2.8.0 — PRODUCED-BY, NOT MEASURED-VERSION.** This document *measures* an earlier codebase > (see its baseline stamp below), but it was *produced* as part of the audit/planning phase that became the > 2.8.0 overhaul. Planning artifacts are filed by the release whose work produced them, never by the version > they discuss. The version in the title or baseline is the code it examined, not the folder it belongs in. > (A 2.5.0 and 2.6.0 folder do exist, holding feature designs for features that shipped in those releases. There > is no 2.7.0 folder because no artifact has been identified as produced during 2.7.0.) > **ANALYSIS ONLY. Nothing implemented, committed, or pushed. No parked plan modified.** > Grounded on `dev` @ `027be1b` (v2.7.0, cache `robco-terminal-v2.7.0-r5`, 1557 tests / 130 suites). > Sources: the ~24 gitignored `planning/` docs (MASTER_PLAN, CAPABILITY_SLATE, AI_SLATE, DETERMINISTIC_FEATURES, > CLOUD/PERFORMANCE/ACCESSIBILITY/TEST_STRENGTH/CONTENT/CODE_QUALITY/GAME_AGNOSTICISM/GAME_THEMING/TOKEN_USAGE audits, > FEATURE_REMAKES, RECREATION_IDEAS, WASTELAND_UPLINK_SPEC, PARALLELIZATION_PLAN, DEPLOY_STAGING_PLAN, > MAINREVERT_COMPAT_PLAN) + direct reads of `state.js`, `cloud.js`, `api.js`, `ui-*.js`, `sw.js`, `ARCHITECTURE.md`. > This document strengthens the two parked design plans; it does not replace them. Awaits owner review + explicit approval. --- ## 0. The single most important finding — RE-BASELINE FIRST **Every upstream design doc that feeds these two parked steps was written against v2.6.0 (`bc8c2eb`, 1078 tests / 89 suites). The repo is now v2.7.0 (1557 tests / 130 suites). A large fraction of what those docs call "BUILD-NOW" is already shipped and Suite-guarded.** Before ANY of Round 2/3 is scheduled, each source doc must be re-validated against HEAD, because acting on their stale "queue" would re-plan finished work. Confirmed already-shipped (so NOT part of the parked remainder): - **All 6 Phase-N native calculators** — VATS, TRADE, THREAT, CONSULT, BIO-SCAN, LOOT (Suites 105–110). - **All 9 Phase-F device capabilities** — Wake Lock, Haptic, Web Share, Badge, Pip-Boy Radio (synth), Cold-Start/Degraded Boot, Overseer's Log, High-Lumen Optics, TERMLINK console (Suites 115–123). - **Per-game theming foundation GT-1/GT-2/GT-3** — the `THEMES` table + `GAME_DEFS[ctx].theme` + per-game default optics + identity strings (Suites 124/127/130). - **The game-agnostic seam** — Protocol 38 + Suite 89 + the `GAME_FILES` boot manifest; the A9 refactor (GA-1…GA-4, GA-6, GA-7, GA-10) is done. **FO4 is now a near data-only drop-in.** - **loadUI dirty-diff** — `_renderSig`/`_isDirty()`/`_clearRenderCache()` + the `renderWorldMap` tab-guard (Suite 91) already resolved most of PERFORMANCE_AUDIT's headline S-P1/B-P1. - **a11y baseline** — `:focus-visible`, `prefers-reduced-motion` (0.01ms), `#chatDisplay aria-live`, `#sysModal` focus-trap (Suites 60/92/94). **Therefore the genuine parked remainder is the UNBUILT residue only.** The rest of this audit treats the two steps at that residue level. --- ## Objective 1 — Full audit of both steps ### 1A. PARKED STEP 2 (v2.8.0) — what it actually still is After re-baselining, Step 2's real content collapses to five clusters: 1. **The genuinely-generative AI residue** (from AI_SLATE, minus the 3 cores B3 already pulled to native): INTERCEPT (AI-augment), RADIO banter, AUDIO-LOG/TTS narration, SCAN AREA, COMPANION MEMORY, OVERSEER directive, HACK-FAIL taunt (AI variant), SHARE-TARGET→vision parse, optional TRADE/BIO-SCAN banter. **Precondition: App Check.** 2. **The SPEC-FIRST device capabilities that were NOT pulled into 2.7.0**: CRT-tilt/gyro parallax, RobCo hacking minigame, `share_target` receiver, TTS audio-log, ambient-light optic calibration. 3. **The client-side infra bundle**: Web Workers offload, SW background-sync queue, full localStorage→IndexedDB migration, cloud-save conflict resolution + version history, full backup export/import, list virtualization, a11y deep pass, unified settings/profile hub, migration test harness, diegetic onboarding, diagnostics export, the `autoImportState` VM test (TS-GAP-7). 4. **Remote Transmissions** (Firestore-driven owner-push broadcast/content-drop). 5. **Deferred theming GT-4 (per-game accent CSS) + GT-5 (game-styled save layout)** and the R2-k/l/m polish (UX clarity, new-game-readiness audit, per-game EXPERIENCE). ### 1B. PARKED STEP 3 (v2.9.0) — what it actually still is Eight owner-selected gameplay systems (Radio tuner, VATS turn-based resolver, Build Planner/Respec, World-Map overhaul, Faction Consequence Engine, Quest Tracker overhaul, Crafting/Workbench stations, Companion/Squad management) + the kept slate (R3-11 per-game SVG map, R3-12 karma/rep timeline with native cause-logging, R3-14 loadout manager, R3-15 aid manager, R3-17 combat log, R3-18 perk planner, R3-19 dialogue helper) + the two FEATURE_REMAKES front-ends (VATS "Targeting Silhouette", Inventory "Manifest & Loadout"). **Most of these EXTEND existing minimal implementations** — `renderSquad()`, `renderQuests()`, `renderCraft()`/`doCraft()`, the shipped native VATS/THREAT/LOOT, and the fog-of-war map all already exist in basic form. That is a strength (extend-before-create, Protocol 22), but it means Step 3 is mostly *overhaul*, not greenfield — and overhaul carries Protocol 25 (don't break muscle memory) risk. --- ## Objective 2 — Incomplete / vague / redundant / poorly-scoped / missing ### 2A. Redundancies (duplicate designs for one slot) - **⚠ WORLD-MAP REWORK EXISTS THREE TIMES.** FEATURE_REMAKES "Phosphor Cartography" (inline-SVG vector nodes) vs RECREATION_IDEAS Idea 3 "Recon Grid" (CSS-grid `<button>` cells + radar sweep) vs the roadmap's own R3-5 exploration overhaul + R3-11 per-game SVG map. **Same data** (`gridRow`/`gridCol`), **same fog-of-war** (`recordLocationVisit`/`markLocationVisited`), **same zoom** (`_mapActiveZone`). These are competing implementations, not additive work. → **Enhancement #1.** - **UPLINK vs Radio vs Map-encounters vs INTERCEPT are already-consolidated but the roadmap still lists them apart.** WASTELAND_UPLINK_SPEC folds RECREATION Idea 4 + AI-H INTERCEPT + Pip-Boy Radio tuner (R3 #2) + World-Map encounter rolls (R3 #5) + Day/Night + Hardcore-as-boundary into **one engine with shared primitives** (world-clock, seeded-roll, one data bank). The parked steps still enumerate Radio (#2) and Map (#5) as standalone — they should reference the unified engine. → **Enhancements #2, #9.** - **CONSULT (WU-N4, shipped) already absorbed B1-09 TERMLINK's command-palette intent**; any "TERMLINK console" residue must not re-fork `NATIVE_COMMAND_ROUTER`. - **TTS/Audio-Log appears twice** (B1-13 device layer + AI-B narration layer) — one surface, two docs. - **Manifest & Loadout ≈ R3-14 loadout manager ≈ #9 crafting build-on** — the FEATURE_REMAKES inventory remake IS the loadout manager; don't build both. ### 2B. Vague / under-specified - **Remote Transmissions has NO design doc at all.** CLOUD_AUDIT never proposes a broadcast/content-drop mechanism. The parked bullet is a one-liner ("Firestore-driven, read-only public + App Check, $0 Spark, owner pushes holotapes"). Data model, security rules, cache/offline behavior, and the render surface are all undefined. This is the single most under-specified Step-2 item. → **Enhancement #2.** - **The IndexedDB bundle says "migrate EVERYTHING with bulletproof zero-loss"** but gives no migration strategy (dual-read shadow? one-shot? rollback?). This is the highest-risk infra item and the thinnest spec. → **Enhancement #7.** - **Web Workers / background-sync / conflict-resolution are named but undesigned** — PERFORMANCE_AUDIT explicitly solved its perf problems with the (now-shipped) dirty-diff instead of workers, so "Web Workers offload" has no identified workload. Needs a concrete "what runs in the worker" before it earns a slot. - **R2-m per-game EXPERIENCE (all 10 sub-items)** is a wish-list, not a spec; several sub-items (per-game map, faction framing) are already partially done or belong to other units (map → R3-11). - **VATS "turn-based combat resolver" (#3)** overlaps the already-shipped native VATS calculator — the parked text doesn't clearly delineate "new turn-based resolver" from "extend the shipped WU-N1 calc." → **Enhancement #9.** ### 2C. Missing (gaps neither step names) - **Per-vendor stock does not exist and is not proposed** anywhere (VENDORS.CSV is metadata-only). TRADE, faction vendor lock/unlock (#6), and any Build Planner "buy this" flow are all realism-limited without it. → **Enhancement #14.** - **FNV DLC quest lines are entirely absent** (all 4 lines, ~35–40 quests; the `dlc` schema already exists). Quest Tracker overhaul (#8) on incomplete data ships a half-empty tracker. → **Enhancement #14.** - **`autoImportState` has no behavioral test** (TS-GAP-7) — the AI write path that every AI-residue feature depends on is validated only by source-string presence. → **Enhancement #5.** - **No merge-time integration gate** exists (see Objective 7) — an operational gap that Round 2/3's larger, more-parallel work will expose. --- ## Objective 3 — Where to expand for immersion / usefulness / maintainability / future-proofing Covered concretely in **Proposed Enhancements** (#1–#15). Headlines: unify the map (immersion + maintainability), make the ambient engine the substrate that Radio/Map/Remote-Transmissions/INTERCEPT all plug into (immersion + architecture), decompose the two monoliths that block FO4 and new AI directives (`getSystemDirective`, `window.onload`), and make every gameplay system natively editable (owner's recurring pain point). --- ## Objective 4 — Additional systems that fit WITHOUT bloat Only systems that ride existing seams (no new framework, offline-safe, game-agnostic) qualify. The three worth adding are folded into the enhancements: the **unified Combat Encounter flow** (#9, reuses shipped natives + the seeded-roll engine), **Build-code sharing** (#10, reuses WU-F3 Web Share), and the **SETUP hub** merging onboarding + settings (#15, reuses `sysModal`). Everything else in the parked steps is already enough surface area — the audit explicitly recommends *consolidation over addition* (see Objective 10 for what to push OUT). --- ## Objective 5 — Consolidation opportunities BETWEEN 2.8.0 and 2.9.0 (duplicate work) This is where the biggest savings are. | # | Duplicate / overlap spanning both steps | Consolidation | |---|---|---| | C1 | **Seeded-roll engine**: Step-2 WASTELAND UPLINK ambient engine needs a deterministic PRNG + `rollTable`; Step-3 World-Map overhaul (#5) needs "encounter rolls"; Step-3 LOOT drop-table needs seeded random. | Build the **one** seeded-roll engine in the UPLINK substrate (U0) in v2.8.0; Map encounters + LOOT consume it in v2.9.0. (Already the UPLINK spec's §2.4 design.) | | C2 | **Radio tuner**: listed as Step-3 #2 gameplay AND as the UPLINK spec's "PULL surface" (Step-2 engine). | One feature. The tuner is the pull-side of the v2.8.0 ambient bank; don't build a separate v2.9.0 radio. | | C3 | **Remote Transmissions (Step-2) vs the UPLINK broadcast channel (Step-2/3)** | Make Remote Transmissions the **online content-drop layer feeding the same offline bank** — exactly parallel to how INTERCEPT is the AI-augment layer. One push channel, three sources (static / AI / owner-push). → **Enhancement #2.** | | C4 | **Day/Night cycle** appears in UPLINK (Step 2) and implicitly in the World-Map/Survival items (Step 3). | One world-clock substrate (UPLINK U0/U2) owns it; every consumer reads it. | | C5 | **VATS**: Step-3 "turn-based resolver #3" + FEATURE_REMAKES "Targeting Silhouette" + the shipped native WU-N1. | One VATS: the shipped deterministic core, wrapped by the Silhouette UI, extended with AP-across-turns. → **Enhancement #9.** | | C6 | **Loadout**: Step-3 R3-14 loadout manager + FEATURE_REMAKES "Manifest & Loadout" + #9 crafting build-on + R3-15 aid manager. | One inventory-panel overhaul that is simultaneously the loadout + aid manager. → **Enhancement #8.** | | C7 | **Native input paths**: R3-12 (rep cause-log), R3-17 (combat log) both re-state "native entry, no AI." | Codify once as a protocol; every Step-3 system inherits it. → **Enhancement #6.** | | C8 | **App Check**: Step-2 precondition for AI-residue AND for Remote Transmissions AND for COMPANION MEMORY. | Do it **once**, first, as an explicit unit. → **Enhancement #3.** | **Net:** roughly a third of the two steps' nominal line items collapse into shared substrates. The dominant theme is *"one engine, many consumers."* --- ## Objective 6 — Fit with RobCo philosophy + Fallout immersion + long-term scalability Every parked item was checked against the hard constraints (vanilla no-build global-scope JS, no unapproved `APP_VERSION` bump, popup-only auth, free/BYO-key, game-agnostic Protocol 38, offline-safe, the full gate). Findings: - **Compliant as-scoped:** the UPLINK engine (offline, writes-nothing-durable, `GAME_DEFS[ctx].ambient` data seam), the theming GT-4/GT-5, the device SPEC-FIRST capabilities, list virtualization, the SETUP hub. - **Needs a kill-switch + fallback (Protocol 32/33)** the moment they touch network: every AI-residue feature, Remote Transmissions, COMPANION MEMORY, background-sync. - **Auth-safety (Protocol 30/31):** none of the parked items should touch auth; verify no AI-residue feature adds a redirect path or an unconditional `signInAnonymously`. - **The one philosophy tension:** the **MEGA "Streaming Two-Phase Narrator"** (FEATURE_REMAKES) changes the AI contract (Protocol 14) and adds a persisted state field (Protocol 4) — high-value UX but the least "vanilla/offline-safe" idea in the corpus. → flag to a later version (Objective 10). - **Scalability:** the GAME_DEFS seam means FNV/FO3/FO4 all ride data. The two things that DON'T yet scale are the `getSystemDirective()` monolith and the read-tracker duplication (Objective 8). --- ## Objective 7 — Dependency correctness + reordering to reduce risk ### 7A. Correct dependencies (verified) - Phase-N natives + Phase-F caps + theming GT-1/2/3 are **done** — Step 3's overhauls correctly build on them. - UPLINK build order **U0 (clock+roll+no-write guard) → U1 (push) → U2 (day/night+weather) → U3 (radio) → U4 (map encounters) → U5 (INTERCEPT AI)** is sound and substrate-first. - Main-revert compatibility is **SAFE**: v2.6.0 IS the Phase-6 release; 2.7.0 added **zero** new state fields; `state.js` defaults + `migrateState` are byte-identical v2.6.0→dev. dev→main promotes already-verified work. ### 7B. Recommended reordering (risk-reduction) 1. **App Check FIRST** (Enhancement #3) — it gates the entire `[DATA]` AI tier + Remote Transmissions + COMPANION. Verify/finish before any networked residue. 2. **The two decompositions BEFORE the features that pile onto them** — `getSystemDirective()` (Enh #4) before any new AI directive/FO4; `window.onload` (Enh #11) before Boot-MOTD / ambient-init / more toggles. 3. **The AI-safety test foundation BEFORE AI-residue** — TS-GAP-7 VM test + numeric-clamp decision (Enh #5) before shipping features that write AI output to state. 4. **The data lane EARLY and in parallel** — VENDOR_STOCK + DLC quests (Enh #14) on the clean `reg_*/db_*` lane (the *only* genuinely parallelizable lane) can run during the v2.8.0 window and unblocks Step-3 TRADE/faction/quest realism. 5. **UPLINK U0/U1 substrate in v2.8.0** so Step-3 Map encounters + LOOT reuse the seeded-roll engine instead of re-inventing it. 6. **World-map unification decision BEFORE any map code** (Enh #1) — pick one design so 5+ existing suites aren't churned twice. --- ## Objective 8 — Technical debt preventable now Grounded in CODE_QUALITY_AUDIT cross-checked against HEAD (several items shipped; these remain OPEN): - **`getSystemDirective()` — 190-line monolithic template string, no section seams (QA-STRUCT-1).** The single biggest FO4 blocker and it blocks every new AI-residue directive. Ties directly to the **GA-5 residual** (`ctx === 'FO3' ? '…' : ''` tracker-directive ternaries — the one remaining Protocol-38 two-game hardcode). → **Enhancement #4.** - **`window.onload` — ~540-line boot block (QA-CONS-2).** Every new field/panel/toggle grows it; it is the most regression-prone block, and Step 2's Boot-MOTD/ambient-init/wake-lock-restore all land here. → **Enhancement #11.** - **`renderSkillBooks`/`renderMagazines` ~90% duplication (QA-DUP-1, WU-B8 still open).** Every new read-tracker (FO4 comics/holotapes) is another ~130-line copy-paste — a direct Step-3 scaling tax. Extract `_renderReadTracker(opts)`. - **LIVE doc-debt (QA-DOC-1):** CLAUDE.md + ARCHITECTURE.md still reference a **nonexistent `js/registry.js`** (actual files: `reg_nv.js`/`reg_fo3.js`/`registry-core.js`) in load-order + Protocols 3/6. Any new-game/Protocol-4 work follows a wrong path. ARCHITECTURE.md also has 50+ stale `ui.js` monolith refs (QA-DOC-2). Cheap to fix, high leverage. - **`alert()` at 30+ sites (QA-CONS-10):** blocks the main thread, breaks the diegetic voice, unstyleable. Round-3's confirm-gated mutations (TRADE/craft/loadout) will add more unless a diegetic modal helper is standardized (reuse `_openSysModal`). - **No per-suite parity check (H1-7b):** the gate compares only TOTAL test counts across the two runners — the two could drift +3/−3 per suite and still pass. Round 2/3 adds ~hundreds of tests across both runners; tighten now. → **Enhancement #15.** - **App Check stale placeholder comment** (cloud.js:31–35 says "replace placeholder" while line 36 holds a real reCAPTCHA-format key and the guard would initialize it). → **Enhancement #3.** --- ## Objective 9 — Architectural improvements that make later versions easier - **Decompose the two monoliths** (Enh #4, #11) — turns "edit a 190/540-line block and pray" into testable, per-section units; makes FO4 a data-add. - **One ambient substrate with a data-only per-game seam** (`GAME_DEFS[ctx].ambient`) that Radio/Map/Remote-Transmissions/INTERCEPT all consume (Enh #2, #9) — new content = data, not code. - **A behavioral-test tier** (VM sandbox for `autoImportState`, browser `test.html` for no-persist/data-safety invariants — Enh #5, #15) — the gate is currently strong on format/presence and *blind to behavioral correctness on data-safety paths*; both TS-GAP-7 and the UPLINK §7 guards push this direction. - **A native-input protocol** (Enh #6) — bakes the owner's "every feature must have a native path, no AI for data entry" rule into the process so it isn't re-litigated per feature. - **A merge-time full-gate discipline** (Enh #15) — the repo has no integration gate; recompute cache-rev + test-count at each single-branch merge, full gate after each, per Protocol 12/8. --- ## Objective 10 — Items to MOVE to a later release (don't belong in 2.8.0/2.9.0) - **MEGA "Streaming Two-Phase Narrator"** (FEATURE_REMAKES) → **later.** Changes the AI contract (Protocol 14) + adds a persisted context field (Protocol 4) + depends on unverified provider streaming. Highest risk, least offline-safe. Park until the AI-residue tier is stable and App Check is confirmed. - **COMPANION MEMORY (AI-K)** → **late in v2.8.0 at the earliest, or later.** The only new *persistent operator-linked Firestore* system; needs a schema + eviction policy + PRIVACY.md update + App Check. The AI_SLATE itself flags it "heaviest, recommend last." - **Web Workers offload** → **later / drop until justified.** No identified workload survives the shipped dirty-diff; a capability without a problem. - **FO4 as a game** → **Round 4 (data-only), as already planned.** Only the *theme* is Round-3 data; a full third game is out of scope for both steps. - **DLC-area map zones / Sierra Madre-Zion-Big MT-Divide** (CONTENT NV-REG-4) → **later.** Needs a zone-grid extension beyond the Mojave 6×6 — a design decision, not a data add. - **Hardcore/Survival (R3 #7, already deferred-standalone)** → **keep deferred.** It's the mutating sibling that must live *outside* the writes-nothing ambient engine; build it after the substrate is proven. --- ## Cross-cutting risk flags (for owner attention) 1. **App Check ambiguity is load-bearing.** The docs assume it's disabled; the code suggests it now initializes (real-format key + the guard only skips on the literal `REPLACE_WITH_RECAPTCHA_SITE_KEY`). Verify in the Firebase console + confirm `firestore.rules` enforcement before treating the AI-residue precondition as either "blocked" or "done." A wrong assumption here mis-orders all of Step 2. 2. **Overhaul ≠ greenfield (Protocol 25).** Step 3 mostly rewrites working screens (map, inventory, quests, squad). Each overhaul must preserve the existing workflow as a fallback/zoom view and pass the existing suites (74/114/126/68/79 for the map alone). 3. **Serial reality.** ~0% of the backlog is strictly parallelizable; everything funnels through both test runners + count + docs + `sw.js`, and `api.js`'s router region is a three-way-merge hazard. The only clean parallel lane is `reg_*/db_*` data. Plan for serial integration with a human-owned, full-gate-after-each-merge discipline. 4. **Docs are stale at the source.** Re-baseline every audit doc's counts/suite numbers against 1557/130 before quoting them in a build spec. --- # Proposed Enhancements *Exactly 15 high-value additions/improvements. Each is a natural extension of the existing roadmap, grounded in real files + the parked plans. No filler. Complexity is Low / Medium / High. "Belongs in" is a recommendation for owner review, not a commitment.* ### 1. Unify the World-Map rework into ONE canonical unit - **Why:** The map overhaul is designed three times (FEATURE_REMAKES "Phosphor Cartography", RECREATION Idea 3 "Recon Grid", roadmap R3-5 + R3-11). Building more than one is pure duplicate work and doubles the churn on 5+ existing map suites. - **Benefits:** UX/immersion — one polished radar-swept, tap-to-travel, fog-of-war map instead of three half-designs. Maintainability — one render path, one set of guards. Architecture — R3-11's per-game SVG (Mojave vs Capital Wasteland) is the superset; adopt it and retire the others. - **Complexity:** Medium (High if per-game SVG art is bespoke). - **Belongs in:** v2.9.0. - **Dependencies:** shipped fog-of-war helpers (`recordLocationVisit`/`markLocationVisited`/`_mapActiveZone`); coordinate-data guards (Suites 74/114/126/68/79); reduced-motion (Suite 94); the seeded-roll engine (#2) if it consumes encounter rolls. ### 2. Make "Remote Transmissions" the ONLINE content-drop layer of the WASTELAND UPLINK engine - **Why:** Remote Transmissions has no design doc, and the UPLINK spec already defines an offline broadcast channel with a static bank + an optional AI-augment (INTERCEPT). An owner-pushed Firestore content-drop is the *third source* on the exact same push channel — not a parallel system. - **Benefits:** Immersion — owner can drop holotapes/bulletins that appear in the living-world feed without a redeploy. Architecture — one push channel, three sources (static / AI-INTERCEPT / owner-push); the offline bank is the fail-safe fallback (Protocol 33) when Firestore is unreachable. Maintainability — reuses the UPLINK data-bank shape and render path. - **Complexity:** Medium–High (Firestore read path + security rules + kill-switch; the engine already exists). - **Belongs in:** v2.8.0 (offline UPLINK substrate) → the content-drop layer rides App Check. - **Dependencies:** UPLINK U0/U1 substrate; **App Check (#3)**; a new `remoteTransmissions` kill-switch flag + graceful offline fallback (Protocol 32/33); read-only public Firestore rule. ### 3. Promote App Check to an explicit, verified precondition unit + clean the stale placeholder - **Why:** App Check gates the entire `[DATA]` AI tier, Remote Transmissions, and COMPANION MEMORY. The code (cloud.js:36) holds a real-format reCAPTCHA v3 key while the comment (31–35) still says "replace placeholder" and the guard only skips on the literal sentinel — so it may already initialize. This ambiguity mis-orders all of Step 2. - **Benefits:** Architecture — turns a fuzzy precondition into a verified gate. Maintainability — removes a stale, misleading comment. De-risk — if App Check is already live, a large chunk of Step 2 is unblocked immediately. - **Complexity:** Low–Medium (mostly verification + `firestore.rules` enforcement + a kill-switch; the SDK wiring exists). - **Belongs in:** v2.8.0 (first). - **Dependencies:** Firebase console confirmation; `firestore.rules`; a config flag. ### 4. Decompose `getSystemDirective()` into per-section/per-game builders + retire the GA-5 ternaries - **Why:** It's a 190-line monolithic template string (QA-STRUCT-1) — the single biggest FO4 blocker, and it blocks every new AI-residue directive (INTERCEPT/OVERSEER/SCAN all inject text here). It still contains the one remaining Protocol-38 two-game hardcode (GA-5 `ctx === 'FO3' ? '…' : ''`). - **Benefits:** Maintainability — testable `_directiveSection_*()` helpers. Architecture — a third game injects directive text via `GAME_DEFS[ctx].ai`, not string surgery. Future-proof — closes the last agnosticism residual. - **Complexity:** Medium (Protocol 14 AI-contract test mandatory in the same commit). - **Belongs in:** v2.8.0 (before any new AI directive or FO4). - **Dependencies:** Protocol 14 round-trip test; Suite 89 agnosticism guard. ### 5. Ship the `autoImportState` VM-sandbox behavioral test (TS-GAP-7) + decide numeric clamping (TS-COV-1) - **Why:** `autoImportState` is the AI→state write path every AI-residue feature depends on, and it is validated only by source-string presence — a deleted field-write can still pass. The gate is blind to behavioral correctness on this path. - **Benefits:** Architecture — establishes the behavioral-test tier (VM sandbox) the whole AI-residue tier needs for confidence. Maintainability — catches silent AI-contract regressions before they corrupt saves. Safety — settles whether out-of-range numerics (`lvl:999`, `s:-5`) are clamped in `autoImportState` or the save layer. - **Complexity:** Medium (building a VM harness for api.js + its deps is non-trivial; no scaffold exists yet — that's why it's SPEC-FIRST). - **Belongs in:** v2.8.0 (foundation, before AI-residue). - **Dependencies:** mock Gemini/Firestore/Auth (reuse the Suite 2b/12/51 sandbox pattern); both runners at parity. ### 6. Codify a "native input path required" protocol for every gameplay data system - **Why:** The owner's recurring pain point (explicit in R3-12 and R3-17): every native feature must have a native, no-AI way to enter/edit its data. Today rep and location changes lean on the AI. Making it a protocol stops it being re-litigated per feature. - **Benefits:** UX — the user always controls their own campaign data offline. Immersion — diegetic native controls, not "ask the terminal." Maintainability — one rule inherited by combat log, rep cause-log, quest objectives, loadout, aid manager. Architecture — reinforces Protocol 24 (AI never sole source of truth). - **Complexity:** Low (a protocol + a checklist; each feature implements its own control). - **Belongs in:** v2.9.0 (cross-cutting; codify at the start of the gameplay round). - **Dependencies:** none (process/protocol). ### 7. Sequence the IndexedDB migration as a standalone, test-first unit with a dual-read shadow + rollback - **Why:** "Migrate EVERYTHING (robco_v8 + slots + backups + settings) with bulletproof zero-loss" is the highest-risk infra item and the thinnest spec. Bundling it with the rest of the client-infra bundle courts a save-loss incident. - **Benefits:** Architecture — IndexedDB unlocks larger saves, background-sync, and conflict history. Safety — a dual-read (read IDB, fall back to localStorage) shadow period + checksum/version + explicit rollback makes it reversible. Maintainability — isolates the riskiest change to one auditable unit. - **Complexity:** High. - **Belongs in:** v2.8.0 (standalone; NOT bundled). - **Dependencies:** the migration test harness (R2-h); TS-GAP-7-style behavioral round-trip tests; `migrateState` invariants; must preserve the beforeunload-flush guard (Suite 95). ### 8. Fold list virtualization into the "Manifest & Loadout" inventory remake - **Why:** `renderInventory` is the only unbounded list (grows with playtime); virtualization is a real perf gap that PERFORMANCE_AUDIT never proposed. FEATURE_REMAKES already rebuilds this exact panel — do both in one pass. - **Benefits:** Performance — bounded render cost on long campaigns. UX — the remake's sort/search/inspect-drawer/loadout-header become the loadout + aid manager in one screen (consolidates R3-14 + R3-15 + #9). Maintainability — one inventory overhaul instead of three. - **Complexity:** Medium. - **Belongs in:** v2.9.0. - **Dependencies:** shipped dirty-diff (Suite 91); `lookupItemInDb`/`updateMath` carry-weight; keep `state.inventory` schema unchanged (Protocol 25); Suites 40/61/75. ### 9. Unify VATS resolver + THREAT + combat log + LOOT into one "Combat Encounter" flow - **Why:** Step 3 lists a "turn-based VATS resolver (#3)", THREAT (shipped), combat log (R3-17), and LOOT (shipped) as separate items — but they are one loop: assess threat → queue VATS shots across AP/turns → log the kill → loot the drop. FEATURE_REMAKES's "Targeting Silhouette" is the front-end for it. - **Benefits:** Immersion — a coherent combat loop instead of four disjoint panels. Architecture — reuses the shipped native VATS/THREAT/LOOT + the UPLINK seeded-roll engine for drops/hit rolls. Maintainability — one encounter surface, one set of coefficients (`GAME_DEFS[ctx].vats`). - **Complexity:** Medium–High. - **Belongs in:** v2.9.0. - **Dependencies:** shipped WU-N1/N3/N6 + GA-7/GA-10; the seeded-roll engine (#2); native combat-log input (#6); `BESTIARY.CSV`. ### 10. Build-code sharing for the Vault-Tec Build Planner via Web Share reuse - **Why:** The Build Planner (#4) produces a SPECIAL+skills+perks build; encoding it as a shareable string that re-imports is a small, high-delight addition that reuses the shipped WU-F3 "Eject Holotape" (Web Share) plumbing. - **Benefits:** UX — export/import/share a build; compare-and-respec across saves. Immersion — "transmit build code" fits the terminal fantasy. Maintainability — reuses the existing share + clipboard fallback chain (no new I/O). - **Complexity:** Low–Medium. - **Belongs in:** v2.9.0. - **Dependencies:** the Build Planner (#4 of the parked set); shipped WU-F3 Web Share; a versioned build-code format (guard against silent breakage). ### 11. Decompose the ~540-line `window.onload` boot block before adding more boot features - **Why:** QA-CONS-2 — it's the most regression-prone block, and Step 2 piles Boot-MOTD, ambient-engine init, wake-lock restore, and radio restore directly onto it. - **Benefits:** Maintainability — split into `_hydrateStateFromStorage` / `_restoreMuteToggles` / `_wirePanelPersistence` / `_wireKeyboardShortcuts` / `_startSessionTimers`. Architecture — each new boot feature attaches to a named seam, not a monolith. Safety — shrinks the highest boot-regression surface before the ambient engine (which self-boots after `loadUI`) lands. - **Complexity:** Medium (touches every boot path — Protocol 8 plan-audit required). - **Belongs in:** v2.8.0 (before Boot-MOTD / ambient init). - **Dependencies:** boot-smoke + render-check; Suite 56 load-order guards. ### 12. Deliver the per-game EXPERIENCE (R2-m) as a GAME_DEFS data-extension guarded by a Suite-89-style check - **Why:** R2-m ("all 10" per-game experiences) is a wish-list at risk of scattering new two-game hardcodes across feature code. The GAME_DEFS seam already carries theme/boot/save identity; extend it (`GAME_DEFS[ctx].ambient`, per-game terminology/voice/faction-framing) as *data*, and guard that no new literal creeps in. - **Benefits:** Immersion — FO3 vs FNV feel distinct (boot flavor, radio bank, terminology, faction framing). Future-proof — FO4 experience = a new GAME_DEFS block, zero feature-code change. Architecture — a Suite-89-style guard fails the build if a new `=== 'FO3'` literal appears. - **Complexity:** Medium. - **Belongs in:** v2.8.0. - **Dependencies:** `getSystemDirective` decomposition (#4) for per-game AI voice; the `GAME_DEFS[ctx].ambient` seam (#2); Protocol 38 / Suite 89. ### 13. Playthrough Type + Complete RNG UX clarity (R2-k) reusing the WU-E2 template banner - **Why:** R2-k flags that the Playthrough Type selector needs per-option explanations; the WU-E2 owner-override kept a reusable "feature notice" banner template that is currently idle — a perfect fit. - **Benefits:** UX — new users understand Minmaxed/Completionist/Casual/Speedrun and what Complete RNG does before committing. Maintainability — reuses an existing template (Protocol 22) instead of new markup. Onboarding — reduces the "what does this do?" support surface. - **Complexity:** Low. - **Belongs in:** v2.8.0. - **Dependencies:** the WU-E2 reusable banner template (shipped, Suite 112); Campaign Config panel; game-agnostic copy (Protocol 38). ### 14. Per-vendor VENDOR_STOCK dataset + FNV DLC quest lines as the parallel data lane - **Why:** Per-vendor stock doesn't exist (VENDORS.CSV is metadata-only) and the FNV DLC quest lines are entirely absent (the `dlc` schema already exists). These are the content foundations under Step-3 TRADE realism, faction vendor lock/unlock (#6 gameplay), the Build Planner economy, and the Quest Tracker overhaul (#8 gameplay). They also live on the *only* genuinely parallelizable lane (`reg_*/db_*`). - **Benefits:** Usefulness — TRADE and quests become real instead of "full DB as stock" and half-empty. Architecture — data-only, game-agnostic, zero collision with UI/api/cloud. Scheduling — can run concurrently during the v2.8.0 window, unblocking v2.9.0. - **Complexity:** Medium (fallout.wiki sourcing per Protocol 3; large additive data). - **Belongs in:** v2.9.0 content (start the data lane in the v2.8.0 window). - **Dependencies:** fallout.wiki (Protocol 3); Suites 78/82 count-sync; no APP_VERSION bump. ### 15. Enforce per-suite parity + a behavioral-test/merge-time gate discipline - **Why:** The gate compares only the TOTAL test count across the two runners (H1-7b) — they can drift per-suite and still pass. Round 2/3 adds hundreds of tests across both runners, and there is **no merge-time integration gate** at all. Both are latent operational risks that Round 2/3's scale will expose. - **Benefits:** Safety — per-suite parity closes a real gate hole; the behavioral tier (#5) catches data-safety regressions source-scans miss. Maintainability — a documented "recompute cache-rev + count, full gate after each single-branch merge" rule (Protocol 12/8) prevents N-way-merge breakage in the hot `api.js` router. - **Complexity:** Low–Medium. - **Belongs in:** v2.8.0 (infra/process, before the high-volume test additions). - **Dependencies:** the VM/behavioral harness (#5); the parity check in `scripts/gate.js`; Protocol 15/2a. --- ## Appendix — Enhancement distribution (at a glance) | # | Enhancement | Complexity | Version | Primary type | |---|---|---|---|---| | 1 | Unify World-Map rework | Medium | v2.9.0 | Consolidation | | 2 | Remote Transmissions = UPLINK online layer | Med–High | v2.8.0 | Consolidation / architecture | | 3 | App Check as verified precondition | Low–Med | v2.8.0 | Precondition / tech-debt | | 4 | Decompose getSystemDirective + kill GA-5 | Medium | v2.8.0 | Architecture / tech-debt | | 5 | autoImportState VM behavioral test | Medium | v2.8.0 | Test-infra / safety | | 6 | Native-input-path protocol | Low | v2.9.0 | Process | | 7 | IndexedDB migration as standalone unit | High | v2.8.0 | Infra / safety | | 8 | Virtualization in Manifest & Loadout | Medium | v2.9.0 | Consolidation / perf | | 9 | Unified Combat Encounter flow | Med–High | v2.9.0 | Consolidation / immersion | | 10 | Build-code sharing via Web Share | Low–Med | v2.9.0 | Additive (fits) | | 11 | Decompose window.onload | Medium | v2.8.0 | Architecture / tech-debt | | 12 | Per-game EXPERIENCE via GAME_DEFS data | Medium | v2.8.0 | Future-proof | | 13 | Playthrough/RNG UX clarity | Low | v2.8.0 | UX / onboarding | | 14 | VENDOR_STOCK + DLC quests data lane | Medium | v2.9.0 (start 2.8.0) | Content / unblocker | | 15 | Per-suite parity + merge-gate discipline | Low–Med | v2.8.0 | Gate / process | **Balance:** 9 land in v2.8.0 (foundations, preconditions, decompositions, safety), 6 in v2.9.0 (gameplay consolidations + content), one content lane spans both. Five are consolidations of existing duplicate work; four are architecture/tech-debt; three sharpen vague items; three are additive-but-fitting. --- *END — analysis only. Nothing was implemented, committed, or pushed. Parked steps untouched. Awaiting owner review + explicit approval before anything folds into the roadmap.*