core/docs/workbench/master-catchup-plan-2026-06-23.md

Workbench/UI Master Catch-up Plan

Date: 2026-06-23 Status: Master phased plan for Workbench/UI catch-up Scope: Workbench UI/UX, backend read models, proposal surfaces, eval/governance surfaces, demo readiness

0. North Star

CORE Workbench is the local proof cockpit for CORE. It must show what happened, what evidence supports it, what authority allowed or refused it, whether it can replay, what mutated, and what remains proposal-only.

The Workbench is not:

• a generic chatbot shell;
• a dashboard over invented metrics;
• a mutation console;
• an animation layer pretending to be evidence;
• a shortcut around ADR, handler, replay, or governance boundaries.

The target demo grammar is:

prompt / artifact / eval input
-> deterministic trace
-> construction/proposal evidence
-> contract/refusal authority
-> replay/sealing
-> audit/governance
-> demo narrative

Every visible claim must be backed by a backend read model, committed artifact, or existing allowlisted execution path.

1. Current baseline

The route registry in workbench-ui/src/app/routes.ts is the source of truth. Current route count: 16.

Section	Route	Path	Catch-up posture
Converse	Chat	/chat	usable; demo polish only
Cognition	Trace	/trace	needs Construction / ProblemFrame tab
Cognition	Contemplation	/contemplation	usable; proposal boundary copy should be checked
Determinism	Tour	/tour	needs sponsor-grade guided proof scripts
Determinism	Replay	/replay	usable; should cross-link from demo/trace
Determinism	Demos	/demos	needs proof-theater orchestration
Evidence	Proposals	/proposals	needs universal ProposalArtifact visual language
Evidence	Runs	/runs	usable; identity-continuity demo polish
Evidence	Lived Life	/lived-life	usable when persisted artifact exists; honesty copy must remain fail-closed
Evidence	Vault	/vault	usable; read-only exact-CGA recall story
Evidence	Audit	/audit	needs governance event expansion
Discipline	Evals	/evals	needs generalization audit and report-pin distinction
Discipline	Calibration	/calibration	usable; wrong/practice distinction must remain clear
Substrate	Packs	/packs	usable; cross-link CORE-Logos
Substrate	CORE-Logos	/logos	read-only viewer built; Studio explicitly deferred
Settings	Settings	/settings	usable; CLI-only runtime config boundary

2. Architecture pivots Workbench must absorb

2.1 Proposal-first construction

The kernel now follows the authority gradient:

surface/process cue
-> ConstructionProposal(status="proposed")
-> exact mention/entity/quantity bindings
-> ContractAssessment
-> diagnostic runnable/refused

Workbench must show that proposals are hypotheses and contracts are the runnable or refused authority. Diagnostic families must be visibly tagged:

diagnostic_only=True
serving_allowed=False

2.2 Quantity-entity foundational seam

binding.quantity_entity and quantity_entity_binding_candidate.v1 are now foundational to later rate, partition, comparison, and state-change work. The UI must render quantity-to-entity grounding as exact local evidence, not generic NLP entity extraction and not serving truth.

2.3 Residual-gated practice spine

The emerging evidence chain is:

ContractResidual
-> SearchGateDecision
-> ComputeBudgetDecision
-> GeometricSearchRun
-> CandidateOperatorResult
-> CandidateAttemptRunBinding
-> ReplayAdapterResult | ReplayAdapterRefusal
-> SealedPracticeTrace

This is diagnostic, inert evidence. It is not answer production, not serving authority, not pack/policy/identity mutation, and not proof by itself.

2.4 Generalization audit governance

Generalization benchmarks are audit/test-only instruments. No raw sealed items may be exposed in UI artifacts, diffs, source files, or logs. Benchmark failures are diagnosis signals, not direct patch targets.

The UI must distinguish:

• committed report pins;
• ephemeral local outputs;
• governed rebaseline candidates;
• unratified artifacts.

2.5 Universal ProposalArtifact substrate

Proposal cannot remain math-specific or page-specific. Workbench should converge on one proposal visual grammar:

ProposalArtifact
  subject
  state
  capability_level
  source
  proposed_change
  reasoning_trace
  evidence_pointers
  validation
  replay_evidence
  safety_report
  affected_artifacts
  handler_route
  suggested_cli
  audit_refs
  ui_disclosure

Capability levels:

Level	Meaning	UI may do
inspect_only	artifact can be inspected only	read/copy/navigate
proposal_only	draft or preview may exist	validate/export/copy, no apply
ratification_enabled	admitted handler exists	ratify/reject/defer through handler only

No Ratify affordance may render unless capability_level == ratification_enabled and an admitted handler route exists.

3. Phased execution plan

Phase 0 — Truth baseline and docs reconciliation

Deliverables:

• refresh workbench-ui/README.md route inventory;
• update docs/workbench/UI-UX-GUIDE.md with post-Wave-M pivots;
• add this master plan;
• add implementation briefs for the first code-bearing phases.

Acceptance:

cd workbench-ui
pnpm test
pnpm build

Phase 1 — Trace Construction read model

Add read-only backend endpoint:

GET /trace/<turn_id>/construction

Target schemas:

ConstructionEvidence
ConstructionProposalView
SourceSpanView
RoleObligationView
MentionView
MentionBindingView
BoundRelationView
ContractAssessmentView
ConstructionFamilyView

Rules:

• read-only;
• no candidate generation;
• no replay execution;
• no mutation;
• no serving authority;
• exact spans only;
• missing evidence returns missing_evidence.

Phase 2 — Trace Construction tab

Add Trace tab:

Pipeline | Construction | Field | Bundle | Surfaces | Grounding | Verdicts | Metadata | Raw

Components:

ConstructionTab
SourceTextWithSpans
ConstructionProposalCard
RoleObligationTable
MentionBindingTable
ContractAssessmentPanel
ConstructionAuthorityBanner

Required copy/badges:

Proposal != Runnable
Contract Determines
Diagnostic Only
Serving Disallowed
Exact Span Required

Phase 3 — Residual-gated practice visibility

Expose read-only practice/candidate/sealed-trace projections. Prefer adding the surface under Trace/Evals/Audit before creating a new route.

Cards:

Residual Card
Search Gate Card
Compute Budget Card
Candidate Operator Card
Run Binding Card
Replay Adapter Card
Sealed Practice Trace Card

Every card must say whether mutation happened. In the current spine, the answer should be no.

Phase 4 — Universal ProposalArtifact UI frame

Build shared proposal review components and adapt existing math/cognition proposals into them before adding new proposal domains.

Components:

ProposalArtifactFrame
ProposalCapabilityBadge
ProposalSubjectHeader
ProposalEvidencePointerList
ProposalReasoningTraceViewer
ProposalValidationReport
ProposalSafetyReport
ProposalHandlerDisclosure
ProposalAuditRefs

Phase 5 — Generalization audit governance in Evals

Add read-only endpoints:

GET /generalization/manifests
GET /generalization/cache
GET /generalization/reports
GET /generalization/reports/<dataset>/<split>

Add /evals internal tabs:

Lanes
Generalization Audits
Report Pins

Required banner:

Audit-only. No raw sealed items are exposed here. Benchmark failures are diagnosis signals, not direct mutation targets.

Phase 6 — Audit governance expansion

Expand audit sources for:

generalization_manifest
generalization_report
report_rebaseline
startup_guard
construction_evidence
candidate_operator
practice_trace
sealed_practice_trace
proposal_artifact
logos_pack_safety

Cards must answer:

What happened?
Was mutation possible?
Was mutation performed?
What digest proves it?
What route inspects it?
What command reproduces it?

Phase 7 — Demo Theater proof tour

Upgrade /tour and /demos into guided proof narratives over the real routes.

Flagship demo paths:

1. Deterministic turn evidence: Chat -> Trace -> Field -> Bundle -> Replay.
2. Proposal-first construction: Trace -> Construction -> Contract blockers.
3. Residual-gated practice: Evals/Trace -> Candidate -> Replay -> Sealed trace -> Audit.
4. Generalization audit governance: Evals -> Generalization -> Report Pins -> Audit.

Every demo step must include:

Claim
What this proves
What this does not prove
Evidence route
Artifact/digest
Reproducer
Failure mode

Phase 8 — CORE-Logos read-only excellence

Polish the existing /logos viewer without adding Studio semantics.

Allowed:

• overview cards;
• safety verdict explanation;
• alignment graph/table polish;
• known gaps card;
• holonomy case viewer;
• manifest digest prominence;
• Packs <-> CORE-Logos cross-links.

Forbidden until later ADR/ProposalArtifact substrate:

• pack editing;
• patch forge;
• holonomy handler UI;
• draft mutation UI;
• Studio route.

Phase 9 — Visual and capture hardening

Run a demo-readiness pass over density, layout, keyboard flow, empty/error/loading contracts, copy buttons, truncation, and partner screenshots.

Capture targets:

/chat
/trace/<turn_id>
/trace/<turn_id> Construction tab
/replay/<turn_id>
/proposals
/evals Generalization Audits
/audit Governance filters
/logos
/tour
/demos

4. Master PR ladder

PR	Title	Scope
1	docs(workbench): reconcile catch-up baseline	README/UI guide/master plan
2	feat(workbench): expose construction evidence read model	schemas + /trace/:id/construction
3	feat(workbench-ui): add Trace construction tab	frontend tab/components/tests
4	feat(workbench): expose practice evidence read models	candidate/practice/sealed trace readers
5	feat(workbench-ui): render residual practice evidence	Trace/Evals/Audit cards
6	feat(workbench-ui): add proposal artifact frame	shared proposal visual substrate
7	feat(workbench): expose generalization audit summaries	manifest/cache/report readers
8	feat(workbench-ui): add generalization audit view	Evals tabs/cards/tests
9	feat(workbench): expand audit governance sources	audit source/schema readers
10	feat(workbench-ui): upgrade audit governance surface	filters/cards/cross-links
11	feat(workbench-ui): upgrade demo theater proof tour	demo scripts/evidence links
12	polish(workbench-ui): demo readiness hardening	visual/copy/accessibility/capture
13	docs(demos): add partner demo package	scripts/reproducers/screenshots

5. Critical success criteria

Workbench is caught up when:

1. every major backend capability has a truthful read surface;
2. Trace shows construction/proposal-first evidence;
3. Evals show generalization audit governance without raw data leakage;
4. Audit shows mutation and governance boundaries clearly;
5. Proposal review uses one visual language across domains;
6. Demo Theater can tell the whole CORE story without manual explanation;
7. CORE-Logos is beautiful but still read-only;
8. no UI route implies authority the backend has not admitted;
9. every claim has evidence or explicitly says it does not;
10. a sponsor can understand why CORE is not another chatbot wrapper.

6. Operating rule

Make the truth visible.
Do not beautify absence into evidence.
Do not promote hypothesis into authority.
Do not let UI convenience outrun governance.