core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/sessions/workbench-proposal-first-alignment-scope-2026-06-20.md

14 KiB
Raw Permalink Blame History

Workbench/UI Alignment Scope Note: Proposal-First Construction & Governance

Status: Approved & Registered Scope Note
Date: 2026-06-20
Author: Gemini 3.5 Flash (docs-only Workbench scope auditor)
Governing Doctrine: ADR-0223, ADR-0224, and the PR #841-#849 reconciliation baseline

1. Current Workbench Baseline

The CORE Workbench is established as a local operator/auditor surface, not a mutation console. Every visual claim displayed on the UI must trace to a backend read model, committed artifact, or allowlisted execution path.

1.1 Route Registry & Shortcuts

The single source of truth for all routes is workbench-ui/src/app/routes.ts. There are currently 16 registered routes grouped into 7 wayfinding sections:

Section Route Path Shortcut Purpose
Converse Chat /chat ⌘1 Execute a normal CORE turn and journal evidence.
Cognition Trace /trace ⌘2 Inspect turn surfaces, grounding, stage rail, propagation, and trace hashes.
Cognition Contemplation /contemplation Palette Inspect persisted contemplation process traces.
Determinism Tour /tour Palette Guided determinism tour over the real demos with honesty cards.
Determinism Replay /replay ⌘3 Re-run a turn in a sealed fresh runtime and compare envelopes.
Determinism Demos /demos Palette Run registered determinism demos.
Evidence Proposals /proposals ⌘4 Review the teaching proposal queue and HITL ratification.
Evidence Runs /runs ⌘6 Browse recorded session runs, identity continuity, and checkpoint gaps.
Evidence Lived Life /lived-life Palette Watch always-on heartbeat loop closure (versor_condition < 1e-6) evidence.
Evidence Vault /vault ⌘8 Inspect persisted vault entries with exact CGA recall evidence.
Evidence Audit /audit ⌘9 Read deterministic audit events (digests, mutation boundary flags).
Discipline Evals /evals ⌘5 Run/read allowlisted eval lanes and wrong=0 ledgers.
Discipline Calibration /calibration Palette See gold-tether arena practice classes and license verdicts.
Substrate Packs /packs ⌘7 Browse language/identity pack manifests, checksums, and metadata.
Substrate CORE-Logos /logos Palette Inspect CORE-Logos pack overview, lexicon, glosses, morphology, alignment, and safety.
Settings Settings /settings ⌘0 Manage local UI preferences; engine config remains CLI-only.

1.2 EvidenceSubject Grammar

The RightInspector and Evidence Chain Rail render details dynamically based on a canonical EvidenceSubject structure:

  • turn -> /trace/<turnId>
  • proposal -> /proposals/<proposalId>
  • eval_result -> /evals/<laneId>
  • artifact -> /replay/<artifactId>
  • run -> /runs/<sessionId>
  • pack -> /packs/<packId>
  • vault_entry -> /vault?inspect=vault:<entryIndex>
  • audit_event -> /audit?inspect=audit:<eventId>
  • calibration_class -> /calibration?inspect=calibration:<className>

1.3 Baseline Absences from UI-UX-GUIDE

  • Leeway Evidence: Full B4 leeway annotations are not admitted; only B4a nullable LeewayEvidence read models are exposed.
  • CORE-Logos Studio: Only the read-only /logos viewer is supported. No patch-forge, draft-state editing, or pack-mutation UI is authorized.
  • Universal Proposal Envelope: Designed conceptually, but the UI lacks a unified artifact display template.

2. Architecture Pivots Since Latest Workbench Guide

Several critical back-end pivots have landed since the last UI-UX Guide update (Wave M B3.5). The UI must align with these boundaries:

2.1 The Proposal-First Construction Seam (ADR-0223 / ADR-0224)

The back-end math and quantitative reasoning pipelines have transitioned to a strict one-way authority gradient:

surface/process cue
→ ConstructionProposal(status="proposed")
→ exact mention/entity/quantity bindings
→ ContractAssessment
→ diagnostic runnable/refused
  • Closeness Proposes: Surface text matching or process-frame triggers authorize the creation of a ConstructionProposal(status="proposed"). This proposal is a pure hypothesis and is created before role binding or validation.
  • Bindings Ground: Spans from the text are bound to roles (e.g. base_quantity, scale, state_entity).
  • Contracts Determine: The organ-specific ContractAssessment evaluates these bindings and decides if the contract is runnable or refused (with typed blocker codes).
  • Diagnostic Posture: All proposal-first families (such as proportional_change.decrease_to_fraction and partition.percent_partition) enforce diagnostic_only=True and serving_allowed=False. The UI must never display these constructions as runnable in serving or active in response generation.

2.2 Quantity-Entity Upcoming Seam

The authorized foundational slice binding.quantity_entity introduces local quantity-to-entity grounding:

  • Quantities are bound to entities (MentionBinding(binding_type="quantity_entity")) and optionally to units (MentionBinding(binding_type="quantity_unit")).
  • Spans must match the source text exactly.
  • The UI must render these relations as diagnostic grounding facts in the frame, rather than generic entity extractions or semantic ontology mappings.

2.3 Governed Report Rebaseline Discipline (#847 / #848)

  • Ephemeral live runner outputs (e.g., train accuracy shifts from 6/44/0 to 30/20/0 after a capability change) must not be committed casually within capability PRs.
  • The committed report.json is a sealed, governed artifact.
  • Any modification to report.json must occur in a dedicated rebaseline PR, explicitly authorized by a governance/rebaseline role, to preserve the sacred wrong_ids == [] invariant.

2.4 Fresh-Base Agent Startup Guard (#849)

  • scripts/agent_startup.sh enforces workspace hygiene before any agent edits.
  • It prevents stale worktrees from causing conflict-prone PRs by validating HEAD alignment with origin/main (or requiring explicit ancestral alignment override via CODEX_ALLOW_NON_MAIN_BASE=1 for PR-resumption).

3. UI Gaps

The current Workbench UI contains several conceptual and routing gaps relative to the backend pivots:

  1. Proposals Route Collision: The /proposals route reads primarily like a Human-In-The-Loop (HITL) teaching/memory proposal queue. It needs to distinguish:
    • Teaching Proposals: Persisted corrections in the teaching loop awaiting review.
    • Construction Proposals: Ephemeral/diagnostic structural hypotheses extracted from a turn's ProblemFrame (with status="proposed", "partial", "closed", or "refused").
    • Contract Assessments: The runnable/refused evaluations that prove or refuse a construction proposal.
  2. Trace Route Deficit: The /trace detail view lacks visual support for ProblemFrame constructions. It needs a dedicated Construction or ProblemFrame panel displaying the entire pipeline: proposals → evidence spans → mention bindings → contract assessments → dispatch status/blockers.
  3. Evals Route Ambiguity: The /evals view shows live runs and wrong counts but does not differentiate:
    • Committed/ratified report pins (stable in git).
    • Ephemeral live runner outputs (which may show capability lifts not yet committed to report pins).
    • Unratified artifact mutations and historical rebaseline events.
  4. Audit Route Gaps: The /audit log should display artifact and rebaseline governance events (e.g., when a report pin is ratified, or when an unauthorized file modification is blocked) as distinct, flagged events.
  5. Read-Only Enforcements: The CORE-Logos and Packs routes must remain read-only; no "Studio" or "mutation" affordances can be simulated.
  6. Registry / Command Palette Parity: The command palette must not advertise route shortcuts or commands for un-shipped pages. No route registry paths or command counts may change until the underlying page and read models are implemented.
  7. Evidence Chain Rail Grammar: If the backend exposes them, the Evidence Chain Rail needs address mappings for construction proposals and assessments (e.g., /proposals/construction:<familyId> or /trace/<turnId>?inspect=assessment:<organName>).

4. Recommended UI Update Sequence

To address these gaps safely, future UI PRs should follow a sequential, decoupled path:

graph TD
    A["PR A: Docs-Only UI Guide Update"] --> B["PR B: Construction Read Models"]
    B --> C["PR C: Trace ProblemFrame Panel"]
    C --> D["PR D: Proposals Route Tab Split"]
    D --> E["PR E: Evals Rebaseline Provenance Card"]
    E --> F["PR F: Audit Governance Event Logger"]
    F --> G["PR G: (Optional) Dedicated Construction Route"]

A. Docs-Only Workbench Doctrine Update

  • Scope: Align docs/workbench/UI-UX-GUIDE.md with proposal-first semantics, clarifying that proposals are hypotheses and contracts are the runnable authority.
  • Constraint: No code changes.

B. Read-Model Inventory for Construction Proposals and Assessments

  • Scope: Add backend API read-model endpoints to expose ProblemFrame.proposals and assess_contracts() results for a given turn ID.
  • Constraint: Read-only endpoints; no execution paths.

C. Trace ProblemFrame/Construction Read-Only Panel

  • Scope: Add a sub-tab in /trace to visualize the grounded mentions, bindings, and active construction proposals for the selected turn. Highlight exact text spans on hover and display contract refusal blocker codes clearly.

D. Proposals Route Tab Split / Filter Split

  • Scope: Introduce clear UI tabs or filters in /proposals to separate "Teaching & Memory Proposals" (which require HITL operator ratification) from "Diagnostic Construction Proposals" (which are immutable, turn-scoped hypotheses).

E. Evals Rebaseline Provenance Card

  • Scope: Add a metadata card to /evals that displays the current committed report pin status vs. live output, referencing the controlling rebaseline session document and ratification PR hash.

F. Audit Route Artifact-Governance Reader

  • Scope: Integrate governance events (such as rebaselines, startup guard outcomes, and reconciliation audits) into the /audit stream.

G. Dedicated Construction Route (Only under Evidence Pressure)

  • Scope: If diagnostic families grow beyond the capacity of the Trace panel, introduce a dedicated /constructions route showing global catalog families, role obligations, and test-suite adequacy.
  • Constraint: Do not add this route early; route counts and shortcuts must remain locked at 16 until evidence demands it.

5. Non-Goals

The following patterns violate CORE architecture and are explicitly forbidden from future UI work:

  • No Mutation UI: The UI must never allow editing, adding, or deleting files, packs, or database records.
  • No Applying Proposals: The UI cannot provide button triggers to apply or run a construction proposal.
  • No Generic Entity Extraction: Do not build arbitrary NLP extraction views or taggers. Only display the exact bindings generated by the backend ProblemFrame.
  • No Serving Admission Controls: The UI must not provide toggle switches to promote diagnostic families to serving or modify the serving_allowed state.
  • No Hidden Normalization: The UI must display raw, un-repaired values. It must never normalize floating-point values or massage versor_condition readouts.
  • No CORE-Logos Studio: The /logos route is a viewer; no interactive "Studio" features (pack editing, patch-forge creation) may be implemented.

6. Acceptance Criteria for Future UI Work

Every future UI contribution must satisfy:

  1. Evidence-Driven Only: The UI must only render committed, backend-provided JSON payloads. No mock data or UI-synthesized states.
  2. Honest Empty States: If a turn has no construction proposals, show "No construction proposals in this frame" rather than implying the pipeline failed.
  3. Exact Span Mapping: Spans shown in the UI must map exactly to character offsets in the raw problem text.
  4. Diagnostic Integrity: Visual elements for diagnostic-only families must carry clear "Diagnostic Only / Serving Disallowed" tags.
  5. Honest Evals: If wrong_ids is non-empty, the count of wrong answers must be highlighted in red; do not hide errors behind generic success badges.
  6. Registry Conformance: Any new route must be registered in WORKBENCH_ROUTES and satisfy route conformance (loading, error, and empty state handles).

7. Recommended Next Implementation Briefs

For the next sessions, the following PR briefs are recommended:

Brief 1: Align UI Guide with Proposal-First Doctrine

PR Title: docs(workbench): align UI guide with proposal-first construction doctrine

Task:
- Update docs/workbench/UI-UX-GUIDE.md to document the proposal-first construction seam.
- Define the separate roles of ConstructionProposal (status="proposed", diagnostic) and ContractAssessment (runnable authority).
- Document the governance rules for evals rebaselines and the startup guard.

Constraints:
- No changes to workbench-ui/*, generate/*, or tests/*.
- Docs-only alignment pass.

Brief 2: Read ProblemFrame Construction Evidence in Trace

PR Title: feat(workbench): read ProblemFrame construction evidence in Trace

Task:
- Expose initial_frame.proposals and ContractAssessment results in the turn read model API.
- In the Trace route UI, add a "Construction" tab next to the "Pipeline" and "Field" tabs.
- Render a list of active construction proposals, their role obligations, and their ContractAssessment status (runnable vs refused blocker codes).
- Highlight the corresponding SourceSpans in the problem text when a role or proposal is hovered.

Constraints:
- UI must remain read-only.
- Expose diagnostic_only=True and serving_allowed=False flags.
- Do not add new routes or change the route registry in routes.ts.
- Ensure the route count remains 16.