Umbrella: V2 architecture refactor — shell primitives, composition root, state reactivity, transport adapter

Read docs/ADR-0004-ui-shell.md and the phase-specific issue, especially #592 for the remaining guardrail work. Start at build/check-boundaries.mjs and review the full validation gates: npm test, tsc --noEmit, and npm run check:arch. Done means the phase contract is met in one PR and the full gate set remains green.

docs/ADR-0004-ui-shell.md decided, on 2026-08-03, to reject the Preact migration (#578, moot) and instead invest in a small set of shared vanilla shell primitives, since the measured evidence showed the Preact treatment costing +330 lines (+26% over a fair vanilla control) and +7.7 KB gzip with no simplification win. That decision opened four refactor issues (#586, #587, #588, #589) plus a separate transport-layer proposal (#585) that this umbrella sequences alongside two more issues surfaced by the same 2026-08-03 review (#590, #591) and a lock-in issue (#592) into one ordered execution plan for the /ship skill: one PR per phase, one session per phase, with a human merge gate between every phase.

Phases

• Phase 1 — #586: SurfaceLifecycle primitive + docked right-inspector slot. Collapses six copy-pasted overlay lifecycles into one, and gives .main-row a real inspectorHost slot — unblocks #488 (foldable right inspector), which is built explicitly on top of this issue's skeleton.
• Phase 2 — #587: side-panel registry, so adding a left-nav panel is a one-file change instead of touching the shell in five-plus places. Unblocks #487 (left navigation); salvages the proven nav-sections.ts registry design from feat/nav-section-registry-487p2 (PR #573) rather than re-deriving it.
• Phase 3 — #591 (fail-closed decoders): small, independent, low-risk — a good early win that doesn't depend on or block anything else in this sequence.
• Phase 4 — #588: decompose the composition root (src/ui/app.ts, createApp spans ~3,000 lines) along four seams, plus a fifth extraction replacing the as App cast with typed staged construction.
• Phase 5 — #589: extract the dashboard tile gesture controller and a pure repaint plan out of renderDashboard's one 46-nested-function closure.
• Phase 6 — #590 (reactive workspace aggregate): retire dashboardTreeRevision by making the committed workspace aggregate itself reactive. Sequenced after #588 so this touches a smaller composition-root surface once the workspace-persistence extraction (workspace-session.ts) has already moved out of app.ts.
• Phase 7 — #585 (ADR-0005): @clickhouse/client-web transport spike. Independent of the shell track — has its own validation gates (precision, streaming, auth/epoch, cancellation, bundle) and may conclude "Rejected"; that outcome still completes the phase, it just means the repository keeps the current separated custom transport from Phase 1 of that issue's own delivery plan.
• Phase 8 — #592 (guardrail lock-in): extend build/check-boundaries.mjs to mechanically forbid the six-copies-of-an-overlay problem from regrowing. Runs last because it locks in what phases 1–2 established.

Ground rules

• Each phase is exactly one PR.
• A phase's own issue body (Goal/Context/Tests/Acceptance criteria) is the contract for that PR — this umbrella does not restate or override it.
• Every phase must leave main green under the full gate set: npm test and tsc --noEmit and npm run check:arch (check-boundaries.mjs). Note: this repo's npm test alone does not run pretest in every invocation context, so npm test passing by itself is not sufficient evidence — run the full gate explicitly.
• No phase starts before the previous phase has merged.
• #487 and #488 are feature work, not refactor work, and are deliberately not part of this umbrella — they follow on the primitives this umbrella delivers (#586 for #488, #587 for #487) once those primitives exist.

Related

• ADR-0004 (docs/ADR-0004-ui-shell.md)
• #582 — V2 roadmap (this umbrella sequences the roadmap's refactor track)
• #487 — left navigation (follow-on feature work, not in this umbrella)
• #488 — right inspector (follow-on feature work, not in this umbrella)
• #570 — CLOSED (Not Planned); same defect family as #591 but not resumed by it