# 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.
