core/docs/workbench/implementation-plan.md

CORE Workbench v1 — Implementation Plan

This plan intentionally starts with planning and read-only observability before any mutating workflow. The purpose is to preserve CORE's existing ADR trust boundaries while making the system legible to operators, engineers, and auditors.

Work queue

Work item	Title	Scope	Mutation allowed?
W-026	Read-only API contract	endpoint schemas + local server surface	No
W-027	Frontend shell	navigation, layout, design tokens, empty states	No
W-028	Chat + trace drawer	basic chat, turn metadata, trace drawer	Runtime turn only
W-029	Proposal queue	proposal-log read model, detail view, CLI-copy affordance	No
W-030	Eval center	lane discovery, run/read evals, result viewer	Eval result writes only if CLI already supports it
W-031	Replay theater	artifact selection, digest compare, replay status UI	No

Phase sequencing

Phase 0 — Planning package

Deliverables:

• ADR-0160
• Product/UX blueprint
• Implementation plan
• API contract
• data-shape contract
• acceptance gates

No code beyond docs.

Phase 1 — Read-only API skeleton

Goal: expose a narrow local workbench API without introducing new mutation paths.

Deliverables:

• workbench/api.py
• workbench/schemas.py
• workbench/readers.py
• route tests with temp fixtures
• CLI command: core workbench api --host 127.0.0.1 --port 8765

Initial endpoints:

• GET /health
• GET /runtime/status
• GET /artifacts
• GET /proposals
• GET /evals
• GET /evals/{lane}

Strict rule: no proposal accept/reject endpoints.

Phase 2 — Frontend shell

Goal: create a minimal, elegant workbench UI shell.

Proposed layout:

+--------------------------------------------------------------+
| CORE Workbench        runtime status      replay status      |
+----------------------+---------------------------------------+
| Chat                 | Main Panel                            |
| Replay               |                                       |
| Proposals            |                                       |
| Evals                |                                       |
| Artifacts            |                                       |
| Runtime              |                                       |
+----------------------+---------------------------------------+

Deliverables:

• workbench/ui/ or apps/workbench/ depending repo convention
• React/Vite/TypeScript shell
• read-only API client
• navigation
• empty states
• no mocks as long-lived architecture; fixtures only in tests/story views

Phase 3 — Chat + Trace Drawer

Goal: prove a small chat surface can expose trace metadata without becoming a chatbot clone.

Deliverables:

• prompt box
• response surface
• trust badges
• expandable trace drawer
• grounding/provenance summary
• telemetry line link when available

Mutation boundary:

A live chat turn may use the existing runtime path. The workbench must label any runtime checkpointing clearly and must not add hidden persistence beyond runtime behavior already governed by ADR-0146/0150.

Phase 4 — Proposal Queue

Goal: make proposal lifecycle visible.

Deliverables:

• pending/accepted/rejected state filters
• proposal detail panel
• replay-equivalence evidence
• source provenance
• proposed chain display
• copyable local CLI command for review

Forbidden in v1:

• accept button
• reject button
• workflow dispatch
• direct corpus mutation

Phase 5 — Eval Center

Goal: turn deterministic evals into a UI surface.

Deliverables:

• lane list
• run lane action for read-only lanes
• result JSON viewer
• metric cards
• case failures
• contemplation-quality detail view

Mutation boundary:

If --save equivalent behavior is exposed, it must be explicit and documented; otherwise first pass should run and display without writing.

Phase 6 — Replay Theater

Goal: make deterministic replay obvious.

Deliverables:

• artifact selector
• original vs replay comparison
• trace hash / digest comparison
• divergence panel
• pass/fail badge

API design constraints

• All schemas must be explicit dataclasses or pydantic models.
• No raw arbitrary filesystem reads from user-provided paths.
• Artifact readers must be rooted under known repo directories.
• Every response should contain enough metadata to audit source path, digest, and timestamp when available.
• Mutation endpoints are forbidden in v1.

Frontend constraints

• TypeScript strict mode.
• API client generated or manually typed from schema contract.
• No global mutable singleton for runtime state.
• No decorative animation as status.
• Color only communicates operational meaning.
• JSON viewers must preserve stable key ordering when possible.

Test expectations

Each implementation PR must include:

• route-level tests for API endpoints
• schema serialization tests
• permission/path traversal tests for artifact readers
• frontend smoke/build check once UI exists
• no-mutation regression checks for read-only routes

Release criteria for v1

The v1 workbench is accepted when an operator can:

1. start the local workbench server,
2. open the UI,
3. inspect runtime status,
4. run or view contemplation-quality,
5. inspect a proposal without accepting it,
6. inspect a trace/replay artifact,
7. perform a basic chat turn,
8. verify no hidden mutation path exists.

Explicit deferrals

• auth
• multi-user collaboration
• cloud deployment
• mobile UI
• proposal accept/reject buttons
• workflow dispatch
• packaged desktop app
• public marketing site
• arbitrary plugin/tool execution