core/docs/handoff/wave-M-phaseB-calibration-briefs-2026-06-13.md

Wave M · Phase B — Calibration / Serving-Discipline Brief Pack

Date: 2026-06-13 Plan: docs/workbench/wave-M-worthiness.md § Phase B. Goal: make the calibrated-learning / serving-discipline loop visible — the gold-tether arena, the reliability gate, "the engine earns the right to guess." This is the widest worthiness gap.

Dependency DAG

B1 (backend readers) ──┬──→ B2 (Calibration route) ──→ B4 (leeway wiring)
                       └──→ B3 (wrong=0 global frame)

B1 gates everything — it merges first. B2/B3 are parallel-safe after B1 (disjoint files except the usual train: App.tsx / types/api.ts / routeConformance / NOT_YET_MIRRORED → strictly sequential merges, union rebase). B4 last (touches Proposals + Replay rails).

Standing constraints (all briefs)

• Worktree off fresh origin/main; green-local (pnpm build && pnpm test, plus the Python lane for B1) before push; STOP after checks green; Shay merges.
• NEVER re-implement engine math. Import and call core.reliability_gate (conservative_floor, license_for, Ceilings, Action); never reproduce the Wilson floor or θ logic in the workbench.
• Read-only. No new mutation endpoints; no execution. The reader reads committed artifacts + computes derived numbers via the engine's own functions. A calibration view never changes a license.
• Token-only styling (hexScan); schema mirrored + snapshot regenerated + drift gate; enum coverage if a new badge enum is added; conformance rows (ADR-0162 §6); no invented data — absent calibration evidence renders honest absence.

---

Brief B1 — Calibration readers + endpoints (Python only; GATING)

Worktree + gates

cd /Users/kaizenpro/Projects/core
git fetch origin
git worktree add ../core-wb-m-b1 origin/main -b feat/wb-m-calibration-readers
cd ../core-wb-m-b1
ls core/reliability_gate/ledger.py || echo "STOP: reliability_gate missing"

Read first (do not wander)

• core/reliability_gate/ledger.py — ClassTally(class_name, correct, wrong, refused, t2_verified, t2_agrees_gold); derived committed (=correct+wrong), attempted, reliability() (=conservative_floor), coverage().
• core/reliability_gate/{floor,gate,ceilings,propose}.py — conservative_floor(successes, committed) (Wilson, N_MIN=10, 0.0 below); license_for(tally, ceilings, action) -> LicenseDecision(licensed, measured, required); Action.PROPOSE (θ=0.85) / Action.SERVE (θ=0.99); Ceilings.required(class_name, action).
• workbench/readers.py (list_/read_ + _page + _is_allowed patterns), workbench/api.py (route wiring), workbench/schemas.py + the two snapshot generators (scripts/dump-schemas.py, scripts/dump-enums.py).
• evals/gsm8k_math/train_sample/v1/report.json + train_sample_coverage_report.json — the persisted calibration evidence.

Investigate first (decides the reader's source)

Is the live ClassTally ledger persisted anywhere at rest? Grep for a written ledger jsonl/json. If not (likely), the reader reconstructs per-class ClassTally from the committed report.json per-class outcomes, then applies the real conservative_floor + license_for. Document which source you used in the reader docstring + the PR.

Deliverables

1. workbench/calibration.py (new): pure functions that load the committed report artifact(s), build ClassTally per class, and produce per-class rows via the real engine functions — no math re-implemented here.
2. Schemas (workbench/schemas.py): CalibrationClass (class_name, correct, wrong, refused, committed, attempted, reliability_floor, coverage, propose_licensed, propose_required, serve_licensed, serve_required) and ServingMetrics (lane, correct, refused, wrong, source_path, source_digest). Mirror in types/api.ts; regenerate both snapshots; the drift gate must pass.
3. Endpoints (workbench/api.py): GET /calibration/classes → {items: CalibrationClass[]}; GET /serving/metrics → {items: ServingMetrics[]} (read train_sample + holdout_dev committed reports; never run a lane). Path-validate any id; reads only inside allowed eval roots.
4. Trust boundary stated in the PR: read-only over committed artifacts + engine-owned derivation; no execution, no mutation.

Verification

cd ../core-wb-m-b1
.venv/bin/python -m pytest tests/ -k "workbench_calibration or workbench_schemas or workbench_api" -q
.venv/bin/python scripts/dump-schemas.py | diff - workbench-ui/schema-snapshot.json

Add tests/test_workbench_calibration.py: a class that cleared SERVE shows serve_licensed=true; a class below N_MIN shows reliability_floor=0.0 and propose_licensed=false; the reader's numbers equal a direct conservative_floor/license_for call (proves no re-implementation).

---

Brief B2 — Calibration / Gold-Tether route (frontend; after B1)

Gates

git worktree add ../core-wb-m-b2 origin/main -b feat/wb-m-calibration-route
grep -q "CalibrationClass" workbench-ui/src/types/api.ts || echo "STOP: B1 not merged"

Deliverables

• TS mirrors already landed in B1; add useCalibrationClasses / useServingMetrics query hooks.
• app/calibration/CalibrationRoute.tsx — per class: a coverage-vs-Wilson bar (reliability_floor vs the cleared θ), correct/refused/wrong counts (wrong load-bearing), and a plain verdict pill: "earned SERVE", "earned PROPOSE", or "not yet licensed". Failures-first ordering (lowest reliability / un-licensed at top). VirtualizedList + useListNavigation + SearchInput; Panel/TabBar detail (Counts / License math / Raw).
• The "License math" tab shows the honest derivation: committed N, Wilson floor, θ required, measured ≥ required → licensed — read from B1, not computed in the UI.
• Nav entry; Calibration row in routeConformance (loading "Loading calibration...", empty "No calibration evidence yet." + the practice-lane CLI, error). Selection publishes an evidence subject (new calibration_class kind, inspect-param) — or, if that's too much for one PR, local selection
  • flag the subject-kind as a follow-up.
• Tests: failures-first ordering, the un-licensed/below-N_MIN class renders "not yet licensed", the wrong count renders, j/k spine.

Verify: cd workbench-ui && pnpm build && pnpm test

---

Brief B3 — wrong=0 as a felt global presence (frontend; parallel with B2)

Gates

git worktree add ../core-wb-m-b3 origin/main -b feat/wb-m-wrong-zero-frame
grep -q "ServingMetrics" workbench-ui/src/types/api.ts || echo "STOP: B1 not merged"

Deliverables

• A small always-present invariant element in the Shell chrome (header strip): live N correct · N refused · 0 wrong, the zero rendered hard (verified token) — sourced from /serving/metrics, never invented; when unavailable, render an honest "metrics unavailable", never a fake zero.
• It links to the Calibration route (B2) and the Evals wrong=0 ledger.
• Doctrine line: the strip states an invariant, it does not claim correctness it can't read — if the committed report shows wrong>0 it shows wrong>0 in the contradicted token (the strip must be able to show a non-zero wrong honestly; it is a mirror, not a slogan).
• Tests: renders the triplet from a stubbed metrics fetch; renders a non-zero wrong honestly (no hard-coded zero); honest absence on fetch error.

Verify: cd workbench-ui && pnpm build && pnpm test

---

Brief B4 — The leeway story (frontend; after B1 + B2)

Gates

git worktree add ../core-wb-m-b4 origin/main -b feat/wb-m-leeway-wiring
grep -q "CalibrationClass" workbench-ui/src/types/api.ts || echo "STOP: B1 not merged"

Deliverables

• In the Replay / Proposals evidence rails, when a turn or proposal carries an approximate/served result, surface why latitude was granted: the class, its license (PROPOSE/SERVE), the θ it cleared, and the [approximate] disclosure — joining the existing HITL ratification to the calibration that grants it. Read from B1; link to the Calibration route.
• No new mutation; purely a read-only cross-link/annotation.
• Tests: a served-with-leeway fixture renders its class + θ + license; a fully-verified turn renders no leeway annotation (absence is honest).

Verify: cd workbench-ui && pnpm build && pnpm test

---

After this pack

Phase C brief pack (cognitive-pipeline visualizer, contemplation-as-process, field substrate, identity continuity) is authored once Phase B lands — C1/C3 are also backend-reader-first and Python-gated.