core/docs/handoff/WORKBENCH-UI-WAVE-SCOPING.md

Workbench UI — Wave Scoping Brief

Status: Scoping (no code in this brief; names the wave shape and the prerequisite ADRs/decisions before any implementation moves) Date: 2026-05-27 Author: Shay Parent doctrine: ADR-0160, ADR-0162 Related: ADR-0161 (proposal-review trust boundary), ADR-0167 (teaching-corridor), ADR-0168 / 0168.1 (FrameClaim handler), ADR-0169 / 0169.1 (CompositionClaim doctrine), ADR-0172 (math contemplation corridor)

---

Goal

Stand up the workbench frontend so the math teaching corridor is operable by a single operator at human-realistic throughput. The current bottleneck is not capability — Tier 1 + Tier 1.5 shipped FrameClaim and (pending) CompositionClaim handlers — it is operator ergonomics. Every audit refusal we cannot ratify quickly is a learning event the engine never gets.

This brief does not commit code. It names:

1. what doctrine has already settled,
2. what the current operator pain points are,
3. what needs a fresh decision (ADR or scoping note) before any implementation,
4. the proposed wave shape (sequence + dependency DAG),
5. the guardrails the wave must not violate,
6. the acceptance criteria for the wave overall.

---

What doctrine has already settled

The frontend has substantial pre-existing doctrine. The scoping brief must respect, not relitigate, the following.

ADR-0160 — Workbench v1

• Frontend stack pinned: React + Vite + TypeScript, TanStack Query, Zustand/Jotai, Tailwind + shadcn primitives, Monaco where structured JSON inspection is necessary.
• No Electron. No heavy design system. No plugin marketplace.
• Local-first, deterministic backend. Backend already exists at workbench/ (stdlib HTTP server, routes for chat/proposals/ math-proposals/ratify/evals/replay/trace).
• Trust boundary v1 = read-only by default. Accepting proposals, rejecting proposals as durable state, and pack/corpus mutation were explicitly forbidden in v1.

ADR-0162 — Design System

• Token namespace, typography, color semantics all bound to ratified enums (EpistemicState, NormativeClearance, ReviewState, grounding source). No invented color states.
• Keyboard contract. Workbench is keyboard-first.
• Layout shell committed.
• Component map v1 must-ship (15 components): WorkbenchShell, TopBar, LeftNav, StatusFooter, CommandPalette, ChatTurnList, ChatTurnCard, ResponseEvidenceStrip, TraceDrawer, four state badges, ReplayTheater, ReplayComparisonPanel, ReplayDiffViewer, ProposalQueue, ProposalCard, ProposalDetailPanel, RatificationCommandPanel, EvalCenter, EvalLaneList, EvalFailureViewer, StableJsonViewer, StableJsonDiffViewer, ArtifactLink.
• No-go list: no chat-clone bubbles, no "AI thinking" affordances, no glassmorphism, no purple-neon-cyberpunk, no graph-builder canvas, no dashboard splash metrics, no color-only state encoding.
• Implementation plan — Branch 1 (pre-W-027) names a single PR scope: workbench-ui/ directory at repo root with pinned deps and the tokens CSS. No app routes yet.

These two ADRs already constitute the design phase. The wave is implementation, not re-design.

---

Current state — backend ready, frontend zero

• workbench/api.py exposes the routes ADR-0160 anticipates: /health, /runtime/status, /artifacts, /proposals, /math-proposals, /math-proposals/{id}/ratify, /evals, /evals/run, /chat/turn, /trace/..., /replay/....
• workbench/server.py is a stdlib ThreadingHTTPServer. No remote network dependency for cognition.
• workbench/schemas.py defines ProposalSummary, ProposalDetail, MathProposalSummary, MathProposalDetail, MathRatifyResult, EvalLaneSummary, EvalRunResult, ReplayComparison, ReplayDivergence — the JSON contract the UI will consume.
• MathProposalDetail already carries suggested_ratify_cli and handler_name, which means the dispatch corridor is already end-to-end on the server side.

What does not exist yet:

• workbench-ui/ directory (ADR-0162 Branch 1 deliverable — not landed).
• Any HTML/CSS/JS asset.
• Any client-side state management.
• Any keyboard binding implementation.

So the wave starts from zero on the client and from a complete contract on the server.

---

Operator pain points (evidence)

Sourced from the 2026-05-27 end-to-end demo and the CompositionClaim brief pack:

1. HITL burden is high. Architecturally clean rejection of handler-mismatched proposals still costs the operator a full round-trip (read row → reason about category → reject → move on). At 47 audit rows × multiple proposal categories, this is the gating cost on the compounding loop.
2. No keyboard corridor for ratification. Operator currently constructs the suggested CLI by reading MathProposalDetail.suggested_ratify_cli from JSON output and pasting into a shell — a four-step context-switch per row.
3. Evidence is text-block JSON. MathReaderRefusalEvidence ships the audit-row context but reading it from raw JSON requires the operator to mentally render the source sentence, the bound slots, and the missing-operator pair.
4. Reasoning traces are flat. MathProposalDetail.reasoning_trace_steps carries the step-by-step decomposer hypothesis, but with no visualization the operator cannot quickly see where the chain would diverge from a correct admission.
5. Replay equivalence is a string field. replay_equivalence_hash is a meaningful invariant but currently surfaces as opaque hex — the operator has no eyes-on confirmation that a proposal genuinely replays.
6. No "stuck queue" diagnosis. The queue of pending proposals does not currently visualize why an item is pending (replay passed but operator hasn't reviewed? replay didn't run? evidence incomplete?). All three states render identically.

These are not capability problems. They are throughput problems with a deterministic fix.

---

What needs a fresh decision

Two doctrine updates are prerequisites. Both should land before any frontend code so the wave doesn't burn cycles on a moving target.

D1 — Trust-boundary ratchet (new ADR)

Problem. ADR-0160 v1 explicitly forbids "accepting proposals" in the UI. That was correct when no ratification handlers existed server-side. Tier 1.5 changed the world:

• teaching/math_lexical_ratification.py::apply_lexical_claim (W2-D, merged)
• teaching/math_frame_ratification.py::apply_frame_claim (PR #389, merged)
• teaching/math_composition_ratification.py::apply_composition_claim (PR-β, pending)

Each handler is replay-gated, hazard-pinned (case 0050), partition- tested, idempotent, and append-only on a reviewed JSONL artifact. The original ADR-0160 prohibition was a safety stance against mutation paths that did not yet have proper gates. Those gates now exist.

Decision needed. Either:

• (a) A new ADR (working title: ADR-0173 — Workbench Ratification Trust Boundary) that explicitly admits operator ratification through the workbench, scoped to the three existing handlers and gated by their existing replay/hazard/partition pins; or
• (b) A scoping note that re-affirms ADR-0160 v1 read-only and defers ratification UI to a v2.

Recommendation: (a). Otherwise the wave reduces to "render proposals you cannot act on," which does not retire the operator- burden pain point at all.

Acceptance: ADR-0173 must enumerate exactly which handlers are admitted, which are not, what mutation paths are still forbidden (corpus, packs, engine_state outside checkpoint path, frame/lexical registry edits outside the handler), and how the UI surfaces the proposal-review trust boundary visually (e.g. RatificationCommandPanel must distinguish "replay passed, you may ratify" from "replay didn't run, ratify is disabled").

D2 — Component-set ratification (sub-decision in D1 or its own scoping note)

ADR-0162's "v1 must-ship" component list pre-dates the ratification handlers. Specifically, RatificationCommandPanel was named as must-ship but its semantics were not pinned because no handler existed. With handlers live, we need to fix:

• which proposal kinds the panel can drive (LexicalClaim, FrameClaim, CompositionClaim — and the deferred SUB_TYPE_FOR_OPERATOR entries remain disabled with a clear "no handler yet" affordance);
• whether the panel executes the suggested CLI in-process via the existing apply_*_claim() handlers, or merely renders the CLI for the operator to copy/run (the brief recommends in-process execution under D1's trust boundary, because copy/paste-to-shell is itself an operator-burden axis);
• the keyboard binding contract (e.g. j/k to navigate proposals, r to ratify the focused proposal, x to reject, ? for help — must be pinned in D1 or a sibling note before implementation so every panel shares one mental model).

Recommendation: fold D2 into D1 as a single ADR.

---

Proposed wave shape

Five waves, ordered. Each wave is one PR or one tight stack, not a sprawling branch.

W0 (docs):    Trust-boundary ratchet ADR + component-set update
                │
                ▼
W1 (UI base): workbench-ui/ scaffold per ADR-0162 Branch 1
              (Vite, TS, Tailwind, shadcn primitives, tokens CSS,
               shell, command palette, status footer — no routes yet)
                │
                ▼
W2 (read):    ProposalQueue + ProposalCard + ProposalDetailPanel
              (math + cognition proposals, read-only;
               StableJsonViewer for evidence/replay payloads;
               EpistemicState / ReviewState / TraceHash badges)
                │
                ▼
W3 (act):     RatificationCommandPanel + handler dispatch
              (keyboard corridor: j/k navigate, r ratify, x reject;
               in-process apply_*_claim() execution via API;
               replay-state visualization;
               post-ratify auto-advance to next pending)
                │
                ▼
W4 (verify):  TraceDrawer + ReplayTheater + ReplayComparisonPanel +
              ReplayDiffViewer + EvalCenter + EvalLaneList +
              EvalFailureViewer
              (the audit/replay surfaces that close the loop;
               StableJsonDiffViewer for replay divergences)

Why this order

• W0 is unblock-everything. Code written against a stale trust boundary either gets thrown out (if doctrine tightens) or builds in a constraint that the rest of the wave can't honor (if doctrine loosens unevenly).
• W1 is the substrate. ADR-0162 already named it; ship it once, every later wave assumes it.
• W2 is the minimum legible workbench. If we ship W0-W2 only, the operator can already inspect every pending proposal at human speed — a real throughput improvement even without ratification UI.
• W3 is the throughput multiplier. The keyboard ratification corridor is the entire reason this wave exists. It must land before W4 because trace/replay surfaces are audit tools, not throughput tools — and we're throughput-bound, not audit-bound.
• W4 closes the loop. Once an operator has ratified a proposal, TraceDrawer + ReplayTheater + EvalCenter let them verify the effect immediately rather than dropping back to the CLI.

What ships in each wave

Wave	One-line description	Approximate PR count	Approximate test surface
W0	Trust-boundary ratchet ADR + (sub-decision) component-set update	1 docs PR	0 (docs only)
W1	workbench-ui/ scaffold + tokens + shell + palette + status footer	1 frontend PR	smoke (build green, tokens snapshot, shell renders)
W2	ProposalQueue + ProposalCard + ProposalDetailPanel + StableJsonViewer + badges	1 PR (math) + 1 PR (cognition) OR 1 bundled	component tests + 1 e2e against backend fixtures
W3	RatificationCommandPanel + keyboard corridor + handler dispatch	1 PR per handler OR 1 bundled PR (LexicalClaim + FrameClaim + CompositionClaim)	one e2e per handler ratifying a fixture proposal → checking the JSONL artifact change
W4	TraceDrawer + ReplayTheater + ReplayDiff + EvalCenter	2 PRs (replay surfaces + eval surfaces)	one e2e per surface

This is the shape, not the exact PR boundaries — operators running W2/W3/W4 should bundle per the project's existing "batch-during-research" pattern when CI cycle time argues for it.

---

Guardrails (must hold across every wave)

Each is non-negotiable. A PR that violates one is reworked, not waived.

1. CLAUDE.md docs discipline. No standalone HTML artifacts as substrate (CSS regen ordering / SVG element ordering break determinism). The workbench is allowed to render HTML because it is a read-only view of deterministic JSONL artifacts, not a substitute for them.
2. ADR-0162 no-go list. Reread every PR. No chat-clone bubbles, no "AI thinking" theater, no glassmorphism, no dashboard splash pages, no graph-builder canvas, no auto-dismiss toast for audit events, no color-only state encoding.
3. Determinism preserved. Every UI state derived from a deterministic backend payload. No client-side randomness that affects rendered content. (Loading skeletons are fine; "shuffle proposal queue" is not.)
4. Trust boundary respected. W2 ships read-only. W3 ships ratification only for handlers admitted by D1's ADR. Pack / corpus / engine_state mutation paths remain forbidden through the UI.
5. wrong == 0 invariant unchanged. No UI wave touches the server-side handlers' hazard pins. Every UI PR runs the affected server suites green (core test --suite teaching -q, core test --suite runtime -q).
6. Case 0050 protected. UI must not introduce a fast-path that bypasses the handler's pre-conditions. Ratifying through the UI must call the same apply_*_claim() function as the CLI, carrying the same evidence, raising the same exceptions.
7. Keyboard-first. No mouse-only interactions for any v1 must- ship component. (Mouse is supported; mouse-only is not.)
8. Accessibility. No icon-only buttons without accessible labels; no color-only state encoding (badges carry text + shape, not color alone). Pinned in ADR-0162 §"The no-go list" — restated here because it's the easiest guardrail to drift on.
9. No remote network dependencies for cognition. Workbench backend stays local-first. UI may fetch from http://127.0.0.1:<port> only. No CDN-loaded fonts/icons in v1; bundle locally.
10. No engine_state writes outside the existing checkpoint path (ADR-0146/0150).

---

Anti-regression invariants

Inherited from the broader teaching corridor — listed so every wave PR can self-check.

• wrong == 0 on core eval gsm8k_math preserved.
• ADR-0166 — no new eval lanes introduced by UI work.
• ADR-0057 replay-equivalence — inherited unchanged.
• ADR-0167 partition — cognition and math proposal surfaces remain partitioned in the UI as on the server.
• Case 0050 hazard pin holds across every W3 ratification path.
• engine_state/* never committed.
• Pinned-lane SHAs should not require updates due to UI work; if one moves, the UI PR is doing something it shouldn't.

---

Open questions (resolve in W0)

1. In-process ratification vs out-of-process dispatch. D1 recommends in-process via the existing API, but if there's a reason to keep the UI strictly read-only and dispatch ratification through the CLI (e.g. an audit-trail concern), W0 must name it.
2. Single-operator only vs multi-operator-aware. The current handler architecture is single-operator (no proposal locking, no review-state contention). W0 should affirm or deny that v1 stays single-operator.
3. Telemetry path. The backend chat/telemetry.py JSONL sink exists. W0 should pin whether the UI emits its own operator- action events (e.g. "operator-ratify", "operator-reject", "operator-defer") into the same sink, or into a separate workbench-events log.
4. Font / icon bundling. ADR-0162 pins typography but doesn't commit on whether to bundle Inter / a system stack. W0 should resolve so W1 doesn't introduce a runtime fetch.
5. Build artifact location. Does workbench-ui/dist/ get committed, gitignored, or served from a CI step? W0 should commit. (Recommendation: gitignored; built locally; CI verifies the build is green but does not commit the artifact.)

---

Acceptance criteria (whole wave)

The wave is "done" when:

• A new operator can run core workbench serve (existing CLI) and open the UI in a local browser.
• Pending audit refusals from audit_brief_11.json appear as a navigable queue.
• An operator can ratify a LexicalClaim, FrameClaim, or CompositionClaim proposal via keyboard in under 10 seconds per row for a row whose evidence they understand.
• The ratification produces the same JSONL artifact change as invoking the corresponding apply_*_claim() from the CLI — byte-equal where possible, semantic-equal otherwise.
• core test --suite teaching -q, core test --suite runtime -q, and core eval gsm8k_math remain green throughout.
• Case 0050 remains refused after end-to-end UI ratification of any pending proposal.
• The five operator pain points listed above are individually retired (each can be pointed at one shipped component).

---

Memory pointers

• feedback-batch-during-research — bundling rule for the W2/W3/W4 PRs when CI cycle time argues for it
• feedback-no-self-dispatch-of-subagents — Shay dispatches
• feedback-production-line-pattern — wave brief pack pattern
• feedback-parallel-agent-worktrees — fresh worktree per brief
• feedback-wrong-zero-hazard-case-0050 — W3 mandatory pin
• feedback-address-critiques-dont-waive — guardrail violations are reworked, not waived
• milestone-adr-0172-tier1-2026-05-27 — context for why throughput, not capability, is the bottleneck
• adr-0167-audit-as-evidence-wave — parent corridor

---

Next step

If approved, W0 docs PR is the immediate output: ADR-0173 (working title: Workbench Ratification Trust Boundary) authored against the five operator pain points above, the existing handlers as scope, and the keyboard contract as pinned semantics. Once W0 lands, W1 (the ADR-0162 Branch 1 scaffold) can dispatch.