# Wave R — Mastery Revamp: Determinism Made Felt Status: approved plan Date: 2026-06-12 Refines: `wave-1-evidence-spine.md` — keeps its spine and Wave-1 deliverables (all shipped: PRs #702, #703, #704, #706); supersedes its Wave 2 / Wave 3 sequencing with the upgraded specs below. Reviewed by: Claude Fable 5 (full re-audit of ADR-0160, ADR-0162, the shipped `origin/main` code, and the Wave 1 plan), approved by Shay. Execution-shape review (external, via Shay, 2026-06-12): R0 confirmed as a strict PR train, never one PR; honesty fix made unconditional in R0a; route conformance test front-loaded R1 → R0a; `Kbd` front-loaded R1 → R0d; KeyboardHelp made registry-driven in R0d; merge order pinned R0a-first. Declined with reasons: full serialization of echelon-1 dispatch (file surfaces verified disjoint; parallel dispatch retained with serial merge), and folding the Playwright lane into R0a (ADR-0162 acceptance 5–7 needs a dedicated, parallel-safe brief). ## Why a revamp before Wave 2 Wave 1 shipped the correct architecture — the evidence spine is real, tested, and on main. But a fresh audit of the shipped code against the doctrine found six gaps that compound if Wave 2 routes are built on top of them: 1. **The UI advertises capabilities that don't exist.** `KeyboardHelp.tsx` documents `j/k` list navigation and the Wave 1 keyboard map says it shipped — no list in the app implements it. `SearchInput`'s `/` binding is mounted nowhere. An audit-native product whose help overlay makes false claims is violating its own first pillar. 2. **No evidence addresses.** Every route is a flat path (zero URL params in `App.tsx`). A selected turn, proposal, or eval result cannot be linked, bookmarked, or cited. For a product whose identity is "evidence you can hand to someone," the URL is the most important audit artifact — and it does not exist. 3. **Doctrine lives in prose, not tests.** ADR-0162 acceptance criteria 5–7 require Playwright (reduced-motion collapse, palette-from-every-route, offline preview). No Playwright exists. The empty/error/loading contract has no conformance test. Per CLAUDE.md's schema-defined proof obligations: a claim without a test that can meaningfully fail is decoration. 4. **The deferred substrate is exactly what compounds.** Inspector resize, per-route `setSubject` call sites, palette action-commands, shared list navigation — all deferred "until a route needs them." Six Wave-2 routes need all of them simultaneously. Deferring means rework ×6. 5. **Wave 2/3 were spec'd as CRUD.** "List with badges + detail panel" six times. Nothing visualizes the structures that make CORE distinct: proposition chains, proof-carrying promotion DAGs, entailment traces, the wrong=0 ledger. 6. **No frontend CI lane exists at all.** `smoke.yml` and `full-pytest.yml` are Python-only. Frontend PRs merge with zero frontend CI verification, and the local full `pnpm test` hangs on worker teardown (live timer handles; diagnosed 2026-06-12). ## The design thesis The blueprint asks for "Linear's calm + Raycast's speed + Instruments' precision." That is the floor. The ceiling — what no other AI product can copy honestly — is: > **Every other AI UI animates fake cognition. This one makes real > determinism *felt*.** Mastery is not more motion or more chrome (the ADR-0162 no-go list stands unchanged). Mastery is a small set of **signature interactions** that are only possible *because* the engine is deterministic: | Signature interaction | What it is | Pillar it embodies | |---|---|---| | **The Evidence Address** | Every evidence subject (turn / proposal / artifact / eval result) has a canonical URL; inspector state serializes into it; `Cmd+Shift+C` copies it anywhere | Audit-native — a claim becomes a pasteable link | | **The Evidence Chain Rail** | The spine's seven stages (intent → subject → provenance → admissibility → replay → authority → action) as a persistent compact rail in the inspector, each stage lit with its actual status | Calm default, infinite depth — structure, zero theater | | **The Replay Moment** | Select any turn → Replay → side-by-side original/replay → two trace hashes resolve **equal**, leaf diff confirms zero divergence | Replay before persuasion — the honest wow | | **Deterministic structure rendering** | Proposal chains / PCCP proof-promotion DAGs / entailment traces as layered SVG DAGs with deterministic layout (same input → same pixels) | All three — interactive where masterful, static where honest | | **The wrong=0 ledger surface** | Evals render the correct/refused/wrong triplet as the canonical visualization; refusals first-class; failures-first ordering | Audit-native — the engine's epistemic honesty, visible | Deterministic layout is doctrine, not preference: force-directed layouts are seeded-random, so the same evidence would render differently across sessions — a literal replay violation. Layered longest-path layout with lexicographic tie-breaking renders identically forever and is screenshot-diffable. --- ## Wave R0 — Substrate hardening Blocks everything. Four briefs; R0a ∥ R0b ∥ R0c can run in parallel, R0d lands after R0c. **Brief 5 (Trace route) dispatch HOLDS until R0 lands** — Trace is the first consumer of this substrate and building it twice is waste. ### R0a — Test-runner hardening + frontend CI lane - [ ] `vite.config.ts` test config gains `testTimeout`, `hookTimeout`, `teardownTimeout` caps so a hung worker fails fast instead of hanging to a CI wall - [ ] Timer hygiene audit: every `setInterval`/`setTimeout` in `workbench-ui/src/` has a cleanup path; component tests that mount timer-scheduling components (`Timestamp`, copy-feedback buttons) use fake timers - [ ] Full multi-file `pnpm test` completes and **exits** locally - [ ] New `.github/workflows/workbench-ui.yml`: path-filtered to `workbench-ui/**` **and the workflow file itself** (it validates its own changes), runs `pnpm install --frozen-lockfile && pnpm build && pnpm test`, `timeout-minutes: 15` - [ ] Remove the `j/k`, `/`, and `Enter — Open selected item` rows from `KeyboardHelp.tsx` **unconditionally** — the overlay must not advertise shortcuts that do not exist. R0d restores them when they become real (and makes the overlay registry-driven so this class of dishonesty is structurally impossible) - [ ] Minimal route conformance test (front-loaded from R1 on execution-shape review): parametrized over the implemented routes (Chat, Proposals, Evals, Replay), asserts empty / error / loading each render with next-action / reproducer / specific-label content (ADR-0162 §6). Minimal means existing routes only — the harness is the contract every later route must pass; fix what fails, no expected-fail lists ### R0b — Playwright smoke lane (pays ADR-0162 acceptance debt 5/6/7) - [ ] `@playwright/test` devDependency + `playwright.config.ts` with `webServer` (vite preview build) - [ ] e2e spec 1: `⌘K` opens the palette from every route; palette navigates to every route (acceptance criterion 6) - [ ] e2e spec 2: `prefers-reduced-motion: reduce` collapses tokenized motion to instant (acceptance criterion 5) - [ ] e2e spec 3: `/preview` renders every primitive with network access blocked (acceptance criterion 7 — offline-safe, per operator circumstances) - [ ] `pnpm test:e2e` script; CI job added to `workbench-ui.yml` (separate job so vitest results are not hostage to browser install) ### R0c — Evidence addresses (URL = subject) - [ ] `workbench-ui/src/app/evidenceAddress.ts`: `subjectToUrl(subject)` / `urlToSubject(params, search)` codec, round-trip property tested for every `EvidenceSubject` kind - [ ] Route params in `App.tsx`: `/trace/:turnId?`, `/proposals/:proposalId?`, `/evals/:laneId?`, `/replay/:artifactId?` (placeholders keep flat paths until their R2 route lands; the codec already speaks their grammar) - [ ] `?inspect=` query param carries the inspector subject + open state; `EvidenceProvider` syncs with the URL (deep link restores inspector) - [ ] Existing routes (Proposals, Evals, Replay) read their param on load to restore selection and write it on selection change - [ ] `Cmd+Shift+C` global shortcut + palette command "Copy evidence link" (registered but inert until R0d's action-command plumbing; ships the shortcut, R0d ships the palette verb) - [ ] Tests: codec round-trip; deep-link restores Proposals selection; inspector state survives a simulated reload ### R0d — Interaction substrate (lands after R0c) - [ ] `useListNavigation` hook: `j/k` + arrows + `Home`/`End` + `Enter` + input-focus guard; roving-tabindex or `aria-activedescendant` pattern - [ ] `VirtualizedList` primitive over `@tanstack/react-virtual`, composing `useListNavigation`; deterministic keys - [ ] `Panel` primitive: header / toolbar-slot / body chrome so routes stop hand-rolling borders - [ ] Inspector resize: wire the existing `SplitPane` into `Shell.tsx` for the inspector column; width persisted (storage access guarded, per the `af8d4f75` precedent) - [ ] Palette action commands: `commandRegistry` gains an action kind; per-route `register()` call sites (the deferred Wave-1 item); first verbs: "Copy evidence link", "Toggle inspector", "Run eval lane …" (registered by the Evals route; executes the existing read-only `POST /evals/run` — an ADR-0160-allowed lane, not a mutation) - [ ] Wire `useListNavigation` + `SearchInput` into the Proposals list and Replay artifact list now (at least two real consumers; `/` becomes real where a `SearchInput` is mounted) - [ ] `Kbd` primitive (front-loaded from R1 — KeyboardHelp and palette shortcut hints consume it) - [ ] `KeyboardHelp.tsx` becomes **registry-driven**: the overlay renders from the shortcut/command registry instead of a hand-maintained list, so advertising an unimplemented shortcut is structurally impossible. The rows R0a removed return here as real, registry-backed entries --- ## Wave R1 — Design mastery pass (one PR, after R0) - [ ] Typography precision: `tabular-nums` for every metric cell (`MetadataTable` values, eval metrics, turn costs); type-scale audit; `text-wrap: balance` on headings - [ ] Selection-state unification: selected row vs focused row are visually distinct and consistent across routes (tokens, not per-route CSS) - [ ] Hash display standard: one rule (12-char truncation + copy + mono) everywhere; consolidate `CopyableHash` (chat) with `DigestBadge` (cleanup-as-you-find: remove the duplicate) - [ ] `EvidenceChainRail` component in `RightInspector`: seven stages, each lit (evidence present) / dim (not applicable) / hollow (not recorded). Statuses derive only from fields the subject actually carries — a stage with no data renders "not recorded", never a guess - [ ] Empty-state glyphs: small static deterministic monochrome SVGs - [ ] `Panel` adoption in Proposals + Evals (Chat/Replay opportunistic) - [ ] **Doctrine-as-tests** (route conformance moved to R0a; the rest here): - [ ] Raw-hex scan test: no hex/rgb literals in `src/**` outside `tokens.css` - [ ] Schema-drift gate: `scripts/dump-schemas.py` (read-only AST walk of `workbench/schemas.py`, same pattern as `dump-enums.py`) → snapshot → vitest asserts `types/api.ts` field coverage --- ## Wave R2 — Projections (parallel briefs, written after R0/R1 land) Every route is the same triad — **list (virtualized, `j/k`) → detail (tabs) → inspector (chain rail)** — with evidence addresses and a conformance test. Briefs get authored against the landed substrate; the specs below are the commitments. ### Trace (Brief 5, upgraded — first dispatch of R2) Everything in the existing Brief 5, plus: URL param selection via R0c codec, `useListNavigation` + `VirtualizedList` for the timeline, `Panel` chrome, versor-condition strip (see journal note below), and the conformance test. ### Runs / Audit / Packs / Vault / Settings - **Runs** — `GET /runs`, `GET /runs/{session_id}`; session list with checkpoint badges; every turn cross-links to `/trace/:turnId`. - **Audit** — `GET /audit/events`; vertical event timeline (new `Timeline` primitive); mutation-boundary events visually weighted above routine events. - **Packs** — `GET /packs`, `GET /packs/{pack_id}`; new `TreeView` primitive; manifest checksum displayed with `DigestBadge` (verify affordance). - **Vault** — `GET /vault/summary`, `GET /vault/entries`; epistemic-state badges; exact-recall provenance (`cga_inner` evidence shown, never an approximate score — runtime recall is exact by doctrine). - **Settings** — localStorage prefs + read-only runtime config display; no engine mutation (CLI-only, stated in the UI). **Journal addition (additive, append-only-safe):** an optional `versor_condition` field on journal entries — **investigate first**: it ships only if `ChatTurnResult`/runtime already exposes the value for the turn. The workbench layer must never compute field algebra itself. Older entries render "not recorded". --- ## Wave R3 — Theater (the wow, honest) - **The Replay Moment** — implement the `/replay/{id}` backend (currently 501): re-run a journaled turn deterministically, return original + replay envelopes; frontend hero flow renders hash-to-hash equality and a leaf diff with `≠` glyphs. Read-only; replay does not checkpoint. - **Deterministic DAG viewer** — one component, hand-rolled layered layout (longest-path layering, lexicographic tie-break, ~150 lines, golden-file layout tests, no graph dependency). Pan/zoom/click-node-→-inspector. Consumers: proposal chains, PCCP proof-promotion (8 scenarios from `demos/proof_carrying_promotion`), entailment traces. - **Demo Theater route** — `GET /demos`, `POST /demos/{id}/run`; scenario results with evidence-class badges and "what this proves / what this does not prove" honesty cards; proposer-was-wrong scenarios visually highlighted. - **wrong=0 ledger view** — Evals renders the correct/refused/wrong triplet as the primary visualization; refusal reasons inspectable; failures-first. --- ## Dependency DAG ``` R0a ─┐ R0b ─┼─(R0c)──→ R0d ──→ R1 ──→ R2 (Trace ∥ Runs ∥ Audit ∥ Packs ∥ Vault ∥ Settings) ──→ R3 R0c ─┘ ``` R0a / R0b / R0c are parallel-safe to **dispatch** (disjoint files; trivial `package.json` merge between R0b and R0d is sequenced away). **Merge order is a strict train: R0a merges first** — it is the smallest PR, carries the honesty fix, and lands the CI lane that then verifies R0b and R0c; R0b/R0c merge next in either order; R0d follows R0c (shares `evidenceContext`/`Shell`). R1 is one PR after all of R0. R2 routes are mutually independent. R3 follows the R2 routes it draws data from — no theater work starts before R0/R1 are merged and tested. ## Keyboard map after R0 | Shortcut | Action | Status | |---|---|---| | `Cmd+K` | Command palette | shipped (Wave 1) | | `Cmd+I` | Toggle inspector | shipped (Wave 1) | | `Cmd+1`..`Cmd+0` | Navigate routes | shipped (Wave 1) | | `Cmd+Shift+C` | Copy evidence link | R0c | | `j/k` / arrows | List navigation | R0d (real, via `useListNavigation`) | | `/` | Focus search | R0d (real where `SearchInput` is mounted) | | `Enter` | Open selection | R0d | | `Esc` | Close overlay / clear selection | shipped + R0d | | `?` | Keyboard help | shipped (Wave 1; overlay lists only real shortcuts) | ## Explicit exclusions (unchanged from ADR-0160/0162 + Wave 1) - No multi-user auth, cloud, SaaS, mobile - No animated cognition theater, glassmorphism, neon, decorative motion - No force-directed / nondeterministic graph layout — ever - No corpus/pack mutation from the UI; mutation only through admitted corridors (ADR-0172 pattern) - No framework churn: React 18 + Vite + stdlib-HTTP backend stay - New dependencies limited to: `@playwright/test` (dev), `@tanstack/react-virtual` (runtime, ~3 kB) ## Risks and standing decisions - **DAG layout**: hand-rolled over `dagre`/`elkjs` — determinism is doctrine, graphs are small (<50 nodes), and the layout is a pure function with golden-file tests. - **`versor_condition` in the journal**: investigate-first; never computed in the workbench layer. - **Vitest hang**: if R0a's timer hygiene doesn't fully resolve teardown, the timeout caps still convert "hangs 30 min" into "fails in seconds" — the CI lane is safe either way. - **Pipeline merge model**: the AssetOverflow pipeline auto-merges agent branches; the reliable gate is pre-push verification. Every brief carries its own verification commands for this reason. ## Brief pack Dispatch briefs for R0a–R0d and R1 live in `docs/handoff/wave-R-mastery-briefs-2026-06-12.md`. R2/R3 briefs are authored after R0/R1 land, against the real substrate.