docs(workbench): consolidate review + IA reorg into Wave M Phase A (re-sequenced before C)

Boils the design review and the information-architecture decision into one
integration. Phase B's heart (calibration/serving discipline) is done;
Phase A (Structure & Polish) now runs BEFORE resuming Phase C because two of
its items are structural prerequisites the Cognition cluster lands into.

Key synthesis: the command-palette drift bug and the grouped-nav idea are
the SAME fix — navigation derives from one registry that also encodes
structure. Standing IA constraint: one workbench, one address space, one
Chain Rail; grouping is a wayfinding skin, never an architectural fork; no
separate workbenches (the single evidence model is the thesis); 'levels' are
depth-within-a-surface, not top-level categories.

Phase A brief pack (wave-M-phaseA-briefs):
- A1: navigation registry (one source of truth) + grouped nav by the
  organism's loop (Converse/Cognition=core-logos/Evidence/Determinism/
  Discipline/Substrate/Settings) + palette fix (Demos+Calibration are
  currently unreachable via ⌘K; the ⌘1-0 map is stale)
- A2: Calibration earned-state — the centerpiece undersells (reads the
  sub-N_MIN report.json; the earned license lives in the disagreeing
  ratification_queue). Primary fix: regenerate coherent practice artifacts;
  fallback: reader surfaces both with provenance
- A3: Doctrine station ('how this UI can't lie') — elevate contracts/checks
  into a first-class surface; trails, larger

Parked: B4 (needs engine-side license stamping; no re-derivation),
Calibration EvidenceSubject kind.
This commit is contained in:
Shay 2026-06-13 04:09:45 -07:00
parent eeba99e8af
commit 2bc1274dec
2 changed files with 212 additions and 4 deletions

View file

@ -0,0 +1,128 @@
# 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

@ -172,8 +172,88 @@ 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.
## Execution order
## Consolidated re-sequencing (amended 2026-06-13, after Phase B heart landed)
**B → C → D**, with **A in parallel**. The worthiness gap is widest at B; the
tour (D) lands hardest once B and C exist to show off. Phase B brief pack is
authored first (this commit); subsequent phase packs follow as each lands.
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.
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.
### 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.