From 7adae77de83b339ccc9676eb6ee73e96d02062b1 Mon Sep 17 00:00:00 2001 From: Shay Date: Sat, 13 Jun 2026 04:18:44 -0700 Subject: [PATCH] docs(workbench): reconcile Wave M plans into b3.5; scrap duplicate Phase A docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- .../wave-M-phaseA-briefs-2026-06-13.md | 128 ------------------ .../workbench-ui-ux-guide-brief-2026-06-13.md | 86 ------------ docs/workbench/wave-M-worthiness.md | 96 ++----------- docs/workbench/wave-m-consolidation-b3.5.md | 16 +++ 4 files changed, 30 insertions(+), 296 deletions(-) delete mode 100644 docs/handoff/wave-M-phaseA-briefs-2026-06-13.md delete mode 100644 docs/handoff/workbench-ui-ux-guide-brief-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 deleted file mode 100644 index f2735534..00000000 --- a/docs/handoff/wave-M-phaseA-briefs-2026-06-13.md +++ /dev/null @@ -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 `⌘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/handoff/workbench-ui-ux-guide-brief-2026-06-13.md b/docs/handoff/workbench-ui-ux-guide-brief-2026-06-13.md deleted file mode 100644 index d05d347a..00000000 --- a/docs/handoff/workbench-ui-ux-guide-brief-2026-06-13.md +++ /dev/null @@ -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; `
` 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. diff --git a/docs/workbench/wave-M-worthiness.md b/docs/workbench/wave-M-worthiness.md index d1a738d7..7f4f44b1 100644 --- a/docs/workbench/wave-M-worthiness.md +++ b/docs/workbench/wave-M-worthiness.md @@ -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 `⌘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. +**Order:** B3.5 (consolidation) → resume Phase C (cognition legibility) → +D (tour) → E (continuous). B4 stays parked behind B3.5-c's feasibility gate. diff --git a/docs/workbench/wave-m-consolidation-b3.5.md b/docs/workbench/wave-m-consolidation-b3.5.md index 3458dd30..979bd06a 100644 --- a/docs/workbench/wave-m-consolidation-b3.5.md +++ b/docs/workbench/wave-m-consolidation-b3.5.md @@ -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. ---