docs(workbench): reconcile Wave M plans into b3.5; scrap duplicate Phase A docs

The docs/proposal-artifact-substrate-v1 work (#727) — wave-m-consolidation-b3.5,
core-logos-studio-plan, proposal-artifact-substrate-v1 — is the authoritative
consolidation and supersedes the parallel 'Phase A' I'd just drafted. Reconciling
to one source of truth:

- FOLD IN the one genuine gap b3.5 missed (a design review caught it): the
  Calibration centerpiece undersells — the reader reads the sub-N_MIN committed
  practice report.json, so on live data no class shows licensed, while the
  earned state (additive 95/5/100, PROPOSE-licensed) sits in the disagreeing
  ratification_queue.json. Added as a diagnosis addendum + a Deliverable-2
  acceptance criterion (make the committed practice artifacts coherent; show
  ≥1 earned class). Data-side fix, not a re-derivation.
- FOLD IN the grouped-navigation idea: a  field on the route registry
  (Deliverable 1) + the organism's-loop grouping (Converse/Cognition/Evidence/
  Determinism/Discipline/Substrate/Settings), with the correction that
  'core-logos' is the language/manifold Studio surface, not the cognition cluster.
- REDIRECT wave-M-worthiness.md's consolidation section to point at b3.5 instead
  of defining a parallel Phase A.
- SCRAP duplicates: wave-M-phaseA-briefs (duplicated b3.5) and
  workbench-ui-ux-guide-brief (superseded by b3.5 Deliverable 4).
This commit is contained in:
Shay 2026-06-13 04:18:44 -07:00
parent 2bc1274dec
commit 7adae77de8
4 changed files with 30 additions and 296 deletions

View file

@ -1,128 +0,0 @@
# Wave M · Phase A — Structure & Polish Brief Pack
Date: 2026-06-13
Plan: `docs/workbench/wave-M-worthiness.md` § Consolidated re-sequencing.
Runs **before** resuming Phase C — A1/A2 are structural prerequisites the
Cognition cluster lands into.
## Standing constraints
- Worktree off fresh `origin/main`; green-local (`pnpm build && pnpm test`,
Python lane where touched) before push; **STOP after checks green; Shay
merges.** Token-only (hexScan); schema/enum/conformance gates; no new
mutation endpoints; no invented data.
- **One workbench, one address space, one Chain Rail.** Grouping is a
wayfinding skin, never an architectural fork. Do not split into separate
apps; do not break the Evidence Address or cross-route co-addressability.
## Order
A1 ∥ A2 (disjoint files) → A3 trails (larger). Each is its own PR.
---
## Brief A1 — Navigation registry (one source of truth) + grouped nav + palette fix
Kills a live bug **and** delivers the grouped IA in one move: today
`LeftNav.NAV_ITEMS` and `CommandPalette.NAV_COMMANDS` + `NAV_PATHS` are two
hardcoded lists that have drifted — **Demos and Calibration are reachable
from the nav but not via `⌘K`**, and the `⌘10` map is stale. The fix is the
registry-driven move (same principle that made KeyboardHelp honest).
### Read first
- `src/app/LeftNav.tsx` (`NAV_ITEMS`), `src/design/components/primitives/CommandPalette.tsx`
(`NAV_COMMANDS`, `NAV_PATHS`), `src/app/Shell.test.tsx` (the nav assertion),
`src/app/shortcutRegistry.ts` (the registry pattern).
### Deliverables
1. `src/app/routes.ts` (new): the single source of truth —
`export const WORKBENCH_ROUTES: RouteSpec[]` where
`RouteSpec = { id: string; label: string; path: string; section: Section;
shortcut?: string }` and
`Section = "Converse" | "Cognition" | "Evidence" | "Determinism" |
"Discipline" | "Substrate" | "Settings"`. Group the current routes:
Chat→Converse; Trace/Runs/Audit/Vault→Evidence; Replay/Demos→Determinism;
Evals/Calibration/Proposals→Discipline; Packs→Substrate; Settings→Settings.
The **Cognition** section is declared now (empty) so Phase C slots in.
Keep `shortcut` only on the routes that warrant a `⌘` (don't force 12 into
`⌘10`) — primary picks get `⌘1…⌘9`; the rest are palette-only.
2. `LeftNav` renders `WORKBENCH_ROUTES` **grouped by section** (section
label + its items, in `Section` order); empty sections render nothing.
3. `CommandPalette` derives its navigate commands and the path map from
`WORKBENCH_ROUTES` — delete `NAV_COMMANDS`/`NAV_PATHS`. Demos + Calibration
become reachable; shortcuts come from the registry.
4. `Shell.test` nav assertion updated to the grouped structure; add a test
that **every** `WORKBENCH_ROUTES` path is reachable from the palette (so
drift is caught by a test, not a human).
5. Constraint: routing, the Evidence Address, and the Chain Rail are
untouched — this is nav presentation only.
### Verify: `pnpm build && pnpm test`
---
## Brief A2 — Calibration earned-state (the centerpiece must show its thesis)
On committed data the Calibration route shows three classes all "not yet
licensed", empty bars — it never shows a class crossing θ. The reader reads
`evals/gsm8k_math/practice/v1/report.json` `per_class`, whose committed copy
is a sub-`N_MIN` baseline (`additive` committed=0), while the *earned* state
(`additive` committed=100, measured 0.861, PROPOSE-licensed) lives in the
separately-committed `ratification_queue.json` — and the two disagree
(correct 3 vs 95, committed in different commits).
### Primary fix (preferred — coherent data, reader unchanged)
Regenerate the committed practice artifacts from **one coherent run** via the
sealed practice runner (`evals/gsm8k_math/practice/v1/runner.py` —
`build_report` / `write_report`, and the ratification-queue generation) so
`report.json` `per_class` and `ratification_queue.json` agree, and the
unchanged reader surfaces the earned class. **Trust boundary:** sealed
practice, deterministic regen, reviewed; practice regime may carry wrong>0
(attempt-and-eliminate) — that is NOT the serving wrong=0; do not conflate or
weaken either. Verify post-regen: the two artifacts agree, and
`read_calibration_classes()` shows ≥1 licensed class.
### Fallback (workbench-only, if regen is out of scope)
Extend the B1 reader to surface **both** artifacts with provenance: the
`per_class` ledger AND an "earned licenses" set parsed from
`ratification_queue.json` `proposals` (class_name, committed, measured,
required, action), each labeled by its source so the two are never silently
merged. The route gains an "Earned licenses" panel. Honest, but messier than
coherent data — prefer the primary.
### Verify
`PYTHONPATH=$PWD .venv/bin/python -m pytest tests/test_workbench_calibration.py -q`
plus, for the primary, a check that the two committed artifacts agree.
---
## Brief A3 — Doctrine station ("how this UI can't lie") — trails; larger
A read-only surface that elevates the "contracts/checks" instinct into a
first-class station: list the doctrine gates and the load-bearing invariants,
each with *what it proves* and a pointer to its executable check. Every other
AI UI asks for trust; this shows the proofs.
### Deliverables (sketch — full brief authored when A1/A2 land)
- New route under the **Cognition/meta** section: a static-but-real catalog of
the gates — hexScan (token-only), schemaDrift (TS mirrors the engine schema,
both snapshots), enumCoverage, route conformance (ADR-0162 §6), golden-file
layout (DAG) — and the invariants — `wrong=0`, `versor_condition < 1e-6`
each row: name · what it proves · the file/command that executes it · doc
(ADR) reference.
- Data is read from a small committed manifest of gates (so the station can't
drift from reality silently — the manifest itself is conformance-checked
against the test files it names). No invented "all green" badges: a gate is
listed because its check exists, not because we assert it passes.
- Read-only; no execution from the UI.
### Verify: `pnpm build && pnpm test`
---
## After this pack
Resume **Phase C** (Cognition / core-logos cluster: pipeline visualizer,
field substrate, identity, contemplation) into the grouped structure A1
created. B4 stays parked (engine-side license stamping). Then D (tour),
E (continuous).

View file

@ -1,86 +0,0 @@
# Brief — CORE Workbench UI/UX Guide (indexed, teach-everything doc)
Date: 2026-06-13
**Dispatch target: Sonnet (or any mid-tier model)** — this is a documentation
task over already-shipped code, not architecture. No code changes.
## Goal
Produce a single comprehensive, **indexed** guide that explains, defines,
guides, and *teaches* the entire Workbench UI/UX — so an external evaluator
(Anthropic, xAI) or a new operator can understand every surface and *why* it
works the way it does, and a returning contributor can navigate by the index.
Deliverable: `docs/workbench/UI-UX-GUIDE.md` (one file, top-anchored table of
contents linking to every section). Markdown only — no standalone HTML, no
sidecar assets (CLAUDE.md § Documentation Discipline). Mermaid fenced blocks
are allowed where a flow genuinely helps; `<details>` for long tables.
## Audience & voice
Two readers: an impressed-but-skeptical evaluator, and a new operator. Voice:
humble + precise, ADR-0160's pillars (audit-native, calm/infinite-depth,
replay-before-persuasion). **Never oversell** — every capability claim must
match what the code actually does; prefer "shows / refuses / replays" over
"understands / knows". If a surface is read-only, say so.
## Required sections (this is the index)
1. **What the Workbench is** — the thesis ("determinism made felt, not
animated cognition"), the three pillars, and the evidence model (one
evidence manifold per route).
2. **Run it** — point to `scripts/workbench` (doctor/setup/up), ports, the
pure-Python guarantee. Mirror the README; don't duplicate the launcher's
internals.
3. **The evidence model** — Evidence Address (URL = subject, the `?inspect=`
param, `Cmd+Shift+C` copy), the Evidence Chain Rail (intent → subject →
provenance → admissibility → replay → authority → action; lit/hollow/dim),
the EvidenceSubject kinds.
4. **The eleven routes** — one subsection each: Chat, Trace, Replay (the
Moment), Demos (Demo Theater), Proposals (+ HITL ratification), Evals
(+ wrong=0 ledger), Runs, Packs, Vault (fail-closed), Audit, Settings.
For each: *purpose · what evidence it projects · how to use it · key
interactions · its three states (loading/error/empty)*.
5. **The design system & primitives** — tokens (semantic color roles, no
palette literals), and each primitive: Panel, TabBar, SplitPane,
VirtualizedList, SearchInput, TreeView, DAG viewer, Timeline, DigestBadge,
Timestamp, MetadataTable, StableJsonViewer, the state components, badges.
6. **Keyboard & command** — the full keyboard map (Cmd+K palette, Cmd+I
inspector, Cmd+1..0 nav, Cmd+Shift+C, j/k list nav, `/` search, Enter,
Esc, `?` help) and the registry-driven help contract.
7. **Why the UI can't lie** — the doctrine gates as a feature: hexScan
(token-only), schemaDrift (TS mirrors the engine schema), enumCoverage,
route conformance, golden-file layouts. Explain that these *prove* the
honesty, they aren't decoration.
8. **Determinism & replay** — the Replay Moment in depth (sealed single-turn,
`trace_integrity`, the honesty card), and what replay does/doesn't prove.
9. **Glossary** — trace hash, versor, epistemic state, grounding source,
wrong=0, gold-tether, θ, evidence subject, etc.
## Read first (ground every claim in the real code)
- `docs/workbench/``core-workbench-v1-blueprint.md`, `design-system.md`,
`ui-component-map.md`, `api-contract-v1.md`, `acceptance-gates.md`,
`wave-R-mastery-revamp.md`, `wave-M-worthiness.md`, `README.md`.
- `workbench-ui/src/app/` — read each route component for accurate behavior
(don't infer); `evidenceAddress.ts`, `evidenceContext.tsx`,
`EvidenceChainRail.tsx`, `shortcutRegistry.ts`, `KeyboardHelp.tsx`.
- `workbench-ui/src/design/` — tokens, components, `doctrine/` gates.
- `README.md` § CORE Workbench (the launcher).
- ADR-0160, ADR-0162 (the UI doctrine + acceptance gates).
## Constraints
- **Accuracy over completeness** — if unsure what a control does, read the
component; never guess. A wrong instruction is worse than an omission.
- Cross-link every section to the source file(s) so it stays maintainable.
- Keep it one navigable file with a working top-of-doc index; if it grows
past ~800 lines, split by section into `docs/workbench/guide/` with an
index page — but prefer one file.
- Add a one-line pointer from `docs/workbench/README.md` to the guide.
## Verification
- Every route/primitive named in the guide exists in the code (grep-check).
- The keyboard map matches `shortcutRegistry` / `KeyboardHelp`.
- No standalone HTML; `git diff --check` clean.

View file

@ -172,88 +172,20 @@ Detailed brief pack: `docs/handoff/wave-M-phaseB-calibration-briefs-2026-06-13.m
- No timelines — phases/priorities/scope-sizes; sequencing is the dependency
DAG, not a clock.
## Consolidated re-sequencing (amended 2026-06-13, after Phase B heart landed)
Phase B's heart is **done** — B1 (#724 readers), B2 (#725 Calibration route),
B3 (#726 wrong=0 frame) make the serving-discipline loop visible. A design
review of that work + an information-architecture decision now fold into a
single **Phase A (Structure & Polish) that runs BEFORE we resume Phase C**
because two of them are structural prerequisites the Cognition cluster (C)
should land *into*, not extend a flat list past.
## Consolidation & re-sequencing — see B3.5
The governing insight: **the command-palette drift bug and the
grouped-navigation idea are the same fix.** Navigation must derive from one
registry that also encodes structure; build that once.
Phase B's heart is done (B1 #724 / B2 #725 / B3 #726). The consolidation that
must happen before Phase C — route-registry unification (kills the
command-palette drift), calibration becoming evidence-native, the B4
feasibility gate, the UI/UX guide, and the Phase-A residue ledger — is
governed by **`wave-m-consolidation-b3.5.md`** (deliverables B3.5-a … e). That
doc is authoritative for the consolidation slice; this plan's Phase A items
fold into B3.5-e (the residue ledger). The grouped-navigation idea and the
Calibration earned-state fix are folded into B3.5 (D1 `section` field; D2
acceptance). Related parallel tracks: `core-logos-studio-plan.md` (the
language/manifold Substrate surface) and `proposal-artifact-substrate-v1.md`
(the universal proposal envelope).
### Standing IA constraint (binds everything below)
**One workbench, one address space, one Chain Rail.** Grouping is a wayfinding
skin, never an architectural fork. A calibration class and the trace it
relates to stay co-addressable. We do **not** split into separate workbenches
— the single evidence model is the thesis. "Levels" are expressed as *depth
within a surface* (calm default / infinite depth), not as top-level
categories.
### Phase A — Structure & Polish (NEXT; runs before resuming C)
- **A1 — Navigation registry (one source of truth) + grouped nav + palette
fix.** Today `LeftNav.NAV_ITEMS` and `CommandPalette.NAV_COMMANDS`/`NAV_PATHS`
are two hardcoded lists that have **already drifted** — Demos (#723) and
Calibration (#725) are in the nav but unreachable via `⌘K`, and the `⌘10`
map is stale. Replace both with one `routes` registry `{ id, label, path,
section, shortcut? }`; LeftNav renders it **grouped by section**;
CommandPalette derives its nav commands and the `⌘` map from it (drift
becomes structurally impossible — the same registry-driven move that made
KeyboardHelp honest). Sections follow the organism's loop:
**Converse · Cognition (core-logos) · Evidence · Determinism · Discipline ·
Substrate · Settings.** Current routes group as: Chat→Converse;
Trace/Runs/Audit/Vault→Evidence; Replay/Demos→Determinism;
Evals/Calibration/Proposals→Discipline; Packs→Substrate; Settings→Settings.
The **Cognition** group is created now (empty or near-empty) so Phase C's
surfaces slot into a home rather than a flat tail.
- **A2 — Calibration earned-state (the centerpiece must show its thesis).**
On committed data the Calibration route shows three classes all "not yet
licensed" with empty bars — it never shows a class crossing θ, because the
reader reads `practice/v1/report.json` `per_class`, whose committed copy is
a sub-`N_MIN` baseline, while the *earned* state (`additive` committed=100,
measured 0.86, **PROPOSE-licensed**) lives in the separately-committed
`ratification_queue.json` — and the two artifacts disagree (correct:3 vs 95,
different commits). **Primary fix:** regenerate the committed practice
artifacts from one coherent run via the sealed practice runner so
`report.json` per_class and the queue agree and the reader (unchanged) shows
the earned class — deterministic regen, reviewed, no metric weakening.
**Fallback** if regen is out of scope: the reader honestly surfaces *both*
artifacts with provenance (the per_class ledger AND an "earned licenses"
panel from the queue), each labeled by source. Either way the disagreement
is resolved and the route shows its moment.
- **A3 — Doctrine station ("how this UI can't lie").** Elevate the
"contracts/checks" instinct into a *surface*, not a folder: a read-only
station that lists the doctrine gates (hexScan, schemaDrift across both
snapshots, enumCoverage, route conformance, golden-file layout) and the
load-bearing invariants (`wrong=0`, `versor_condition < 1e-6`), each with
*what it proves* and a pointer to its executable check. Every other AI UI
asks for trust; this one shows the proofs. Larger scope than A1/A2 — may
trail into/after C, but it is the single most novel "worthy of the model"
surface and belongs in the Cognition/meta neighborhood.
- Remaining Phase-A polish (density pref wiring, DAG's other two consumers,
accessibility pass, tabular-nums/balance sweep) continues as before,
parallel-safe.
Brief pack: `docs/handoff/wave-M-phaseA-briefs-2026-06-13.md`.
### Parked / deferred
- **B4 (per-turn leeway attribution)** is **blocked**: a served turn carries
no calibration-class/license/θ. It needs an **engine-side** change to stamp
ReachLevel/class/θ onto served results (its own ADR) — then B4 is a trivial
display. Do not re-derive in the workbench (theater).
- **Calibration EvidenceSubject kind** (the route uses local selection today)
— a conscious deferral, not an accident; revisit if a calibration class
needs to thread the Chain Rail.
### Order
**A (A1 → A2 in parallel; A3 trails) → resume C (Cognition / core-logos
cluster) → D (tour) → E (continuous).** A1+A2 land before C so the Cognition
surfaces arrive into a grouped structure that already shows discipline
honestly.
**Order:** B3.5 (consolidation) → resume Phase C (cognition legibility) →
D (tour) → E (continuous). B4 stays parked behind B3.5-c's feasibility gate.

View file

@ -43,6 +43,8 @@ Calibration classes and serving metrics are visible, and wrong=0 is now a felt g
That means calibration is still partly a page-local experience, not fully part of the Evidence Chain Rail.
**Addendum (review, 2026-06-13): the centerpiece currently undersells its own thesis.** The reader reads `evals/gsm8k_math/practice/v1/report.json` `per_class`, whose committed copy is a sub-`N_MIN` baseline (`additive` committed=0) — so on live data the route shows three classes, all "not yet licensed", with empty reliability bars. It never shows a class *crossing θ*, which is the entire point. Meanwhile the *earned* state (`additive` committed=100, measured 0.861, **PROPOSE-licensed**) lives in the separately-committed `ratification_queue.json`, and the two artifacts disagree (correct 3 vs 95, committed in different commits). An evaluator opening Calibration today sees the discipline's scaffolding but not its moment. The fix is data-side, not a re-derivation: make the committed practice artifacts coherent (regenerate from one deterministic practice run via the runner) so `report.json` `per_class` shows ≥1 earned class and matches the queue; the reader stays unchanged. Sealed-practice may carry wrong>0 (attempt-and-eliminate) — that is *not* the serving wrong=0; do not conflate. Folds into Deliverable 2.
### 3. B4 is conceptually right but data-shape risky
B4 wants the Replay/Proposals evidence rails to explain why approximation/leeway was granted: class, license, theta, disclosure, and relation to HITL ratification.
@ -94,6 +96,7 @@ id
path
label
description
section # wayfinding group; see note below
left_nav_visible
command_palette_visible
landing_route_allowed
@ -101,6 +104,15 @@ keyboard_shortcut
route_conformance_required
```
**Grouped navigation (review, 2026-06-13).** As the route count grows past a
flat list, LeftNav should render grouped by `section`, by the organism's loop
rather than by abstraction level: `Converse · Cognition · Evidence ·
Determinism · Discipline · Substrate · Settings`. This is a wayfinding skin
only — one workbench, one address space, one Chain Rail; never a split into
separate apps. (Note: "core-logos" is the *language/manifold* Studio surface
per `core-logos-studio-plan.md` — the Substrate neighborhood — not the
cognition cluster.)
### Critical rule
If there are more routes than single-digit keyboard shortcuts, the UI must say so honestly.
@ -174,6 +186,10 @@ Show only fields carried by the backend read model:
- RightInspector handles the subject without falling to raw unknown.
- Evidence Chain Rail names calibration as serving-discipline evidence, not runtime truth.
- Missing data renders as missing/unknown, not as green.
- The committed practice artifacts are coherent (`report.json` `per_class`
agrees with `ratification_queue.json`) and the route shows ≥1 earned
(licensed) class — the centerpiece demonstrates "earns the right to guess",
not only the un-earned floor.
---