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:
parent
eeba99e8af
commit
2bc1274dec
2 changed files with 212 additions and 4 deletions
128
docs/handoff/wave-M-phaseA-briefs-2026-06-13.md
Normal file
128
docs/handoff/wave-M-phaseA-briefs-2026-06-13.md
Normal 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 `⌘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).
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue