# PARALLELIZATION_PLAN.md — RobCo U.O.S. Stage D (Worktree Execution Strategy) — B3-rerun > **PLAN-ONLY. Re-run over the B3-revised master plan (42 units, incl. Phase N).** Untracked. Implements nothing, changes no code, commits nothing, creates no worktrees-with-changes, performs no merges/rebases. Worktree commands below are **RECOMMENDATIONS** for the owner, not actions taken here. > Baseline: `origin/main` @ `bc8c2eb` — v2.6.0, cache `robco-terminal-v2.6.0-r1`, 1078 tests / 89 suites. > Input: `MASTER_PLAN.md` (Stage C · B3-revised) — **42** dependency-ordered work-units with exact file-touch lists, now including **Phase N — Native Deterministic Features** (WU-N1 VATS, N2 TRADE, N3 THREAT, N4 CONSULT, N5 BIO-SCAN, N6 LOOT) + WU-D4 data gaps + the shrunken Phase G. **Present and read** (no STOP). --- ## 0. METHOD (mechanical — unchanged) Two units are **PARALLELIZABLE** only if BOTH hold: 1. **Literal disjointness** — exact file-touch sets have an empty intersection, AND 2. **No denylist contact** — neither touches a SHARED-FILES DENYLIST singleton. **SHARED-FILES DENYLIST** (touching any ⇒ must serialize): `sw.js` (the single `CACHE_NAME` line — Protocol 1 monotonic guard), `tests/check-persistence.js` **and** `.ps1` (both runners + the hardcoded count, Protocol 2a/15), `index.html`, `css/terminal.css`, `js/state.js`, `js/api.js`, and the doc set (`CHANGELOG.md` `README.md` `ARCHITECTURE.md` `RULES.md` `CLAUDE.md`). Dependency order from MASTER_PLAN is also binding. **What the B3 rerun changes:** +6 Phase-N units, +1 WU-D4, +2 optional Phase-G enrichment layers. The decisive new fact: **5 of the 6 Phase-N units (N2–N6) edit `js/api.js`** (drop `[TRADE]`/`[THREAT]`/`[LOOT]` AI macros + add the `[CONSULT]`/`[BIO-SCAN]` native-router entries) — a denylist file — and **all 6 edit `index.html` + `css` + `tests×2` + `sw.js`**. So Phase N lands almost entirely on the serial backbone; it does **not** add a parallel lane. --- ## 1. PER-UNIT FILE SETS + DENYLIST CONTACT (refreshed, 42 units) Legend: ● = denylist file · ○ = private (non-denylist) file. Phase-N rows are new. | Unit | Dep | Private (non-denylist) files | Denylist contact | |---|---|---|---| | WU-A2 | — | `ui-render.js` | ● index ● tests×2 ● RULES ● CLAUDE ● sw | | WU-A1 | A2 | `ui-render.js` | ● css ● tests×2 ● sw ● docs | | WU-A3 | A1,A2 | `ui-core.js`, `ui-render.js` | ● tests×2 ● sw ● docs | | WU-B1 | — | — | ● **api.js** ● tests×2 ● sw ● docs | | WU-B2 | — | `ui-core.js`, `cloud.js` | ● tests×2 ● sw ● docs | | WU-B3 | — | — | ● **api.js** ● tests×2 ● sw ● docs | | WU-B4 | — | `cloud.js` | ● tests×2 ● sw ● docs | | WU-B5 | B4 | — | ● tests×2 ● RULES ● CLAUDE | | WU-B6 | — | — | ● tests×2 ● docs | | WU-B7 | — | `ui-audio.js`, `ui-core.js`, `api.js`, `ui-account.js`, `ui-render.js` | ● **api.js** ● tests×2 ● sw ● docs | | WU-B8 | A1 | `ui-render.js` | ● tests×2 ● sw ● docs | | WU-B9 | — | `cloud.js` | ● **state.js** ● tests×2 ● sw ● docs | | WU-C1 | — | — | ● css ● tests×2 ● sw ● docs | | WU-C2 | — | — | ● css ● tests×2 ● sw ● docs | | WU-C3 | A2 | `ui-core.js` | ● index ● css ● tests×2 ● sw ● docs | | WU-C4 | — | `ui-core.js` | ● index ● tests×2 ● sw ● docs | | WU-C5 | A1 | `ui-render.js` | ● tests×2 ● sw ● docs | | WU-C6 | — | — | ● index ● tests×2 ● sw ● docs | | WU-C7 | A1,A2 | `tests/render-check.mjs` | ● css ● index ● tests×2 ● sw ● docs | | WU-D1 | — | `reg_fo3.js` | ● tests×2 ● sw ● docs | | WU-D2 | — | `db_fo3.js`, `db_nv.js`, `reg_nv.js`, `reg_fo3.js` | ● tests×2 ● sw ● docs | | **WU-D4** | — | `db_nv.js`, `db_fo3.js`, `reg_*.js` | ● tests×2 ● sw ● docs | | WU-E1 | — | `ui-*.js` (broad sweep) | ● index ● tests×2 ● sw ● docs | | WU-E2 | — | `ui-core.js` | ● index ● css ● tests×2 ● sw ● docs | | WU-F1..F9 | A+C | new `js/*` module each (+ thin hook) | ● index ● css ● tests×2 ● sw ● docs | | **WU-N1 VATS** | A1/A2, D4a | `ui-core.js` (`showVATSOverlay`) | ● index ● css ● tests×2 ● sw ● docs | | **WU-N2 TRADE** | A1/A2, D4b | `ui-render.js` | ● **api.js** ● index ● css ● tests×2 ● sw ● docs | | **WU-N3 THREAT** | A1/A2, D4c | `ui-render.js`/`ui-core.js` | ● **api.js** ● index ● css ● tests×2 ● sw ● docs | | **WU-N4 CONSULT** | A1/A2 | `ui-render.js` | ● **api.js** ● index ● tests×2 ● sw ● docs | | **WU-N5 BIO-SCAN** | A1/A2 | `ui-render.js`/`ui-core.js` | ● **api.js** ● index ● css ● tests×2 ● sw ● docs | | **WU-N6 LOOT** | A1/A2 | `ui-render.js` | ● **api.js** ● index ● css ● tests×2 ● sw ● docs | | WU-VER | ALL | `manifest.json` | ● **state.js** ● **sw** ● index ● CHANGELOG ● ARCHITECTURE ● README ● RULES ● CLAUDE | | WU-D3 | — | *(deferred)* | — | | WU-G0 + residue + WU-G-TRADEBANTER/BIOPHRASE | B,G0,N2/N5 | `firestore.rules`, config, new js | ● tests×2 ● docs (+ index/css/api/sw per unit) — *deferred* | --- ## 2. DISJOINTNESS MATRIX (strict rule) — STILL ~ZERO, now reinforced by Phase N The strict rule is unchanged and the B3 additions only harden it: > **Under the strict rule, provably-parallelizable unit pairs = ZERO.** Every buildable unit (now ~38) touches `tests/check-persistence.{js,ps1}` + the doc set; all but B5/B6 also touch `sw.js`. Those are denylist singletons. No pair is literally disjoint AND denylist-free. Phase N makes the two heaviest contended files even hotter: | Singleton | Units touching it (Δ from B3) | |---|---| | `tests×2` | **every buildable unit** (~38) | | docs set | **every buildable unit** (~38) | | `sw.js` | every unit except B5, B6 (~36) | | `index.html` | A2, C3, C4, C6, C7, E1, E2, F1–F9, **N1–N6**, VER (~23) | | `css/terminal.css` | A1, C1, C2, C3, C7, E2, F1–F9, **N1,N2,N3,N5,N6** (~21) | | `js/api.js` | B1, B3, B7, **N2, N3, N4, N5, N6** (3 → **8**) | | `js/state.js` | B9, VER | **`js/api.js` more than doubled in contention** (3→8 units) — the macro-routing + `NATIVE_COMMAND_ROUTER` edits in N2–N6 land in the same file as B1/B3/B7. That cluster is now the second-tightest serial chokepoint after the tests/docs/sw triad. **Honest headline: 0% of the 42-unit backlog is strictly parallelizable** — the same conclusion as the first run, now with a larger denylist heat-map. --- ## 3. PRIVATE-FILE CONTENTION (pragmatic layer) — Phase N joins the backbone Looking past the denylist at *private* source files (the part a second worktree could develop concurrently if denylist edits are deferred to integration): | Private file | Units contending (Δ from B3) | |---|---| | `js/ui-render.js` | A2, A1, A3, B7, B8, C5, E1, **N2, N3, N4, N5, N6** — **even heavier** | | `js/ui-core.js` | A3, B2, B7, C3, C4, E2, E1, **N1, (N3/N5 alt)** — **heavier** | | `js/api.js` | B1, B3, B7, **N2, N3, N4, N5, N6** *(also denylist)* — tight serial cluster | | `js/cloud.js` | B2, B4, B9 | | `reg_fo3 / reg_nv / db_fo3 / db_nv` | D1, D2, **D4** | | new per-feature module | each F-unit owns its own → mutually disjoint | **Clusters with a code body provably disjoint from the foundation spine:** - **DATA cluster (D1 + D2 + D4):** touches only `reg_*/db_*`. **Zero overlap** with any UI/api/cloud/state source. WU-D4 (B3 coefficients/gaps) *joins this existing cluster* — it shares `db_*`/`reg_*` with D2, so it serializes **within** the stream but adds **no new collision** with the rest of the backlog. The DATA stream remains the one clean parallel lane, now 3 units. - **CAPABILITY modules (F1–F9):** each a self-contained new `js/` module → mutually disjoint code bodies; shell wiring deferred to integration. **Phase N has NO disjoint code body.** N1 contends on `ui-core.js` (with A3/B2/B7/C3/C4/E2); N2–N6 contend on `ui-render.js` (with A1/A2/A3/B7/B8/C5/E1) **and** on `js/api.js` (with B1/B3/B7). **All six Phase-N natives are serial-backbone units** — they cannot be developed in concurrent worktrees without colliding on `ui-render.js`/`ui-core.js`/`api.js` at the private level, on top of the universal denylist. This matches the master-plan re-hand-off note exactly. --- ## 4. WHAT IS GENUINELY PARALLELIZABLE (Phase N included) > **Model unchanged:** parallel *development* of disjoint code bodies in separate worktrees is possible, but every shared-singleton edit (cache bump, both test-runner counts, doc finalization) and EVERY merge is serial and human-owned. You parallelize the *typing*, never the *integration*. | Workstream | Units | Disjoint from spine? | Run mode | |---|---|---|---| | **WS-SPINE** (foundation + most of B/C/E + **all of Phase N**) | A2→A1→A3, B-series, C-series, E-series, **N1–N6** | n/a — IS the spine | strictly serial | | **WS-DATA** | D1 → D2 → **D4** | ✅ registry/db only | **parallel worktree** alongside WS-SPINE | | **WS-CAP** (per feature) | F1…F9, one branch each | ✅ if self-contained module | **parallel prototyping**, serial integration | **Phase N is firmly in WS-SPINE.** Its tight internal ordering: N2–N6 all edit `js/api.js`, so they serialize among themselves AND after the Phase-B api.js units (B1→B3→B7) to avoid line-drift in the macro-router/`NATIVE_COMMAND_ROUTER` region. N1 (VATS, `ui-core.js` only) is the lone Phase-N unit not touching api.js, but still collides on `index.html`/`css`/`ui-core.js`. **Fraction (B3-rerun):** of ~38 buildable units, only the **3 DATA units (D1/D2/D4)** form a clean concurrent lane, plus the **9 capability prototypes** *if* each is an isolated module. So ~12/38 can have code bodies typed off the critical path — but **all 38 integrate serially**, and **all 6 Phase-N natives are on the serial spine**. **Strictly parallel-and-mergeable in isolation: ~0.** The relative parallel fraction *shrank* vs the first run (6 new serial-backbone units added, only 1 new unit — D4 — joined a parallel lane, and it merely thickened an existing stream). --- ## 5. RECOMMENDED WORKTREE LAYOUT (for the owner — do NOT run in this plan-only stage) Still only two concurrent worktree types are worth standing up — Phase N adds nothing here because it is all serial: ```bash # Main checkout stays on the serial spine (A → B → C → E → N → VER): # C:/Dev/!GEM/Website version (branch: main, or wf/spine) # Worktree 1 — DATA workstream (registry/DB corrections + B3 coefficients), concurrent with spine: git worktree add ../GEM-data -b wf/data-corrections origin/main # owns: js/reg_fo3.js, js/reg_nv.js, js/db_fo3.js, js/db_nv.js # work: WU-D1 → WU-D2 → WU-D4 (serialize within stream; D4 feeds N1/N2/N3 coefficients) # Worktree(s) — CAPABILITY prototypes (only if each is a self-contained module): git worktree add ../GEM-cap-radio -b wf/cap-f5-radio origin/main # WU-F5 git worktree add ../GEM-cap-wake -b wf/cap-f1-wakelock origin/main # WU-F1 # ...one short-lived branch per F-unit, each owning ONLY its new js/ module ``` Note: **do NOT stand up Phase-N worktrees.** N1–N6 share `ui-render.js`/`ui-core.js`/`api.js` with the spine and each other — they must land sequentially on the spine. Branch convention `wf/<stream>-<unit>-<slug>`; remove worktrees after merge; never leave stale worktrees holding denylist files open. **Sequencing tie-in:** WU-D4 lives in `wf/data-corrections` but **feeds** N1 (ranged), N2 (barter), N3 (ammo-burn). The owner should land the DATA branch (incl. D4) **before** the dependent Phase-N coefficient work on the spine — or build the Phase-N exact-math cores first (melee VATS, barter shape, TTK) which don't block on D4, and refine the coefficient-gated parts after D4 merges. --- ## 6. RECOMMENDED SERIAL ORDER (everything not in a parallel worktree) Each line = one commit through the full gate, one `-rN` cache bump (+1), one count-sync (both runners), one doc update: ``` SPINE (strict order): 1. WU-A2 (Suite 88; data-sub-id; UI-1..5) ── first 2. WU-A1 (.tracker-toggle; GATE-UI-3) ── needs A2 3. WU-A3 (loadUI fan-out) ── needs A1/A2 4. WU-B8 (shared render helper) ── needs A1 5. WU-C5 (ARIA labels on buttons) ── needs A1 6. WU-C7 (mobile layout) ── needs A1/A2 7. WU-C3 (tab ARIA + contrast) ── needs A2 SECURITY/CORRECTNESS (serialize through denylist; api.js units in order): WU-B1 → WU-B3 → WU-B7 (all touch api.js — sequence to avoid drift) WU-B2 (ui-core.js + cloud.js) WU-B4 → WU-B5 (cloud sanitize → round-trip test) WU-B6 (test/doc-only) WU-B9 (state.js accessor) A11Y/CSS (css/index denylist — serialize): WU-C1 WU-C2 WU-C4 WU-C6 VOICE/TEMPLATES: WU-E1 WU-E2 PHASE N — NATIVE DETERMINISTIC (serial spine; all touch index/css/tests/sw, N2–N6 also api.js): WU-N1 (VATS — ui-core.js; melee/AP-strike core now, ranged after WU-D4a) WU-N4 (CONSULT — native router entry; lightest api.js touch) WU-N3 (THREAT — bestiary+TTK; ammo-burn after WU-D4c) WU-N5 (BIO-SCAN — advisory + router entry) WU-N2 (TRADE — barter UI + additive/confirm-gated; after WU-D4b) WU-N6 (LOOT — additive add/value) # N2–N6 serialize on api.js macro-router region; order within is flexible # but must follow B1/B3/B7 (Phase-B api.js edits) to avoid line-drift. INTEGRATE PARALLEL WORKSTREAMS (human merge, §7): merge wf/data-corrections (WU-D1, WU-D2, WU-D4) # land before/with the D4-gated Phase-N refinements merge each wf/cap-* (WU-F1..F9) one at a time, full gate per merge CLOSE-OUT (last): WU-VER (APP_VERSION → 2.7.0; final cache rev r1; doc + count consolidation; owner-confirmed) DEFERRED (not this chain): WU-D3, WU-G0 + Phase-G generative residue + WU-G-TRADEBANTER/BIOPHRASE (App-Check-gated; the natives do NOT wait on these), TS-GAP-7 VM sandbox. ``` Ordering notes from MASTER_PLAN: A-spine rigid (A2→A1→A3); B1/B3/B7 + N2–N6 all touch `api.js` → one serial chain through that file; B4→B5 hard dep; C3/C5/C7 rebase on A2/A1; Phase N rebases on A1/A2 and (for coefficient parts) on WU-D4. WU-VER always last. --- ## 7. MERGING IS HUMAN-OWNED — NO INTEGRATION GATE EXISTS TODAY (load-bearing — unchanged) **This is the headline constraint. Read it before standing up any worktree:** - **There is NO merge-time integration gate in this repo today.** The gate runs at commit (`gate:fast`) and push (`gate` full) **per branch**. Nothing automatically re-runs the full gate at the moment two branches combine. - **Two individually-green branches can still break in the N-way merge.** Both bump `CACHE_NAME` to the same `-rN`; both edit the hardcoded test count; both add a Suite — and the textual merge can produce a file that compiles but has a wrong count, a duplicate suite, a non-monotonic cache rev, or a silently dropped guard. None of that is caught by the per-branch gates that already passed. **B3 raises the stakes:** with `js/api.js` now touched by 8 units (B1/B3/B7 + N2–N6), the macro-router region is a prime three-way-merge hazard. - **Therefore integration MUST be:** (1) **human** — the owner performs every merge by hand, resolving the denylist singletons (cache rev → next monotonic `-rN`; test count → recomputed total synced across BOTH runners + all doc locations per Protocol 2a; docs → consolidated; api.js router region → reconciled by hand); and (2) **gated at merge** — after each merge, run the **full** gate (`npm run gate`, incl. Playwright boot-smoke + render-check) on the merged tree **before** the next branch is merged in. One merge, one full-gate run, repeat. - **Merging is NEVER automated.** No auto-merge, no merge bot, no CI auto-integration. The owner owns every merge, sequenced (Protocol 12 — no concurrent pushes), one change landing at a time (Protocol 8 audit gate). - **Cache rev + count are recomputed at merge, not carried from branches.** A branch's `-rN` and count are provisional; the real values are assigned by the owner at integration time in monotonic, gap-free order. --- ## 8. SUMMARY FOR THE OWNER (B3-rerun) - **Strictly parallelizable: still ~0% of the backlog** — now 42 units. Every buildable unit funnels through `tests/check-persistence.{js,ps1}` + the hardcoded count + the doc set (and almost all through `sw.js`). Phase N reinforces this and **doubles `js/api.js` contention (3 → 8 units)**. - **Phase N is entirely serial backbone.** All 6 natives (VATS/TRADE/THREAT/CONSULT/BIO-SCAN/LOOT) share `ui-render.js`/`ui-core.js`/`api.js` with the spine and each other — none are parallel-developable. They join the serial spine ahead of WU-VER and after the Phase-B api.js edits. - **The only parallel lanes are unchanged in shape:** **WS-DATA** (now D1+D2+**D4**, registry/db only — D4 thickens the stream but adds no new collision) and **WS-CAP** (F1–F9 isolated-module prototypes). ~12/38 buildable units can have code typed off the critical path; **all 38 integrate serially.** The *relative* parallel fraction shrank vs the first run (6 serial-backbone units added; only D4 joined a parallel lane). - **Recommended worktrees:** one `wf/data-corrections` (D1→D2→D4) concurrent with the spine; short-lived `wf/cap-*` per capability module. **No Phase-N worktrees** — they are serial. Land DATA (incl. D4) before the D4-gated Phase-N coefficient refinements, or build the exact-math cores first. - **Headline (unchanged, load-bearing):** **merging stays 100% human-owned.** There is no merge-time integration gate, so two green branches can still break when combined — and the now-hot `api.js` router region makes that more likely. The owner resolves cache rev + test count + docs + the api.js router by hand and runs the full gate after every single merge, one branch at a time. **Never automate the merge.** --- *PARALLELIZATION_PLAN.md — Stage D (B3-rerun), plan-only. No code changed, nothing committed, no worktrees created, no merges performed. FINAL stage of the parked chain — Phase Z stays parked until the owner says go.*