From 2bc1274dec3516f2c382587092915ab668b5cf2a Mon Sep 17 00:00:00 2001 From: Shay Date: Sat, 13 Jun 2026 04:09:45 -0700 Subject: [PATCH] docs(workbench): consolidate review + IA reorg into Wave M Phase A (re-sequenced before C) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../wave-M-phaseA-briefs-2026-06-13.md | 128 ++++++++++++++++++ docs/workbench/wave-M-worthiness.md | 88 +++++++++++- 2 files changed, 212 insertions(+), 4 deletions(-) create mode 100644 docs/handoff/wave-M-phaseA-briefs-2026-06-13.md diff --git a/docs/handoff/wave-M-phaseA-briefs-2026-06-13.md b/docs/handoff/wave-M-phaseA-briefs-2026-06-13.md new file mode 100644 index 00000000..f2735534 --- /dev/null +++ b/docs/handoff/wave-M-phaseA-briefs-2026-06-13.md @@ -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 `⌘1–0` 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 + `⌘1–0`) — 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). diff --git a/docs/workbench/wave-M-worthiness.md b/docs/workbench/wave-M-worthiness.md index f0eebb15..d1a738d7 100644 --- a/docs/workbench/wave-M-worthiness.md +++ b/docs/workbench/wave-M-worthiness.md @@ -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 `⌘1–0` + 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.