# 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.
When mutation is admitted, it must pass through an explicit corridor rather than
appearing as an ambient UI capability.

## Work queue

| Work item | Title | Scope | Mutation allowed? |
|---|---|---|---|
| W-026 | Read-only API contract | endpoint schemas + stdlib local server surface only | 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, admitted math ratification corridor | Math ratification only |
| 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 unadmitted
mutation paths.

Deliverables:

- `workbench/api.py`
- `workbench/schemas.py`
- `workbench/readers.py`
- `workbench/server.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 /artifacts/{artifact_id}`
- `GET /proposals`
- `GET /proposals/{proposal_id}`
- `GET /evals`
- `GET /evals/{lane}`
- `POST /evals/run`

Strict rules:

- W-026 is API-only. No frontend, auth, visual intro, trace drawer, chat UI,
  live chat endpoint, or replay theater.
- Use the Python standard-library HTTP server for W-026. Defer FastAPI or any
  other web framework unless a later ADR admits the dependency.
- No proposal accept/reject endpoints unless a later ADR admits the specific
  corridor and its preconditions.
- No synthetic trace/replay evidence. Routes for later phases must return
  `unsupported` or `not_found` until a real evidence path exists.

### Phase 2 — Frontend shell

Goal: create a minimal, elegant workbench UI shell.

Proposed layout:

```text
+--------------------------------------------------------------+
| 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.

## Mutation doctrine

The Workbench mutation rule is not "no mutation ever." It is: no mutation
without an admitted corridor, explicit preconditions, auditable telemetry, and
replay evidence.

An admitted corridor must satisfy all four requirements:

1. **ADR-governed path.** The path is named and bounded by an accepted ADR or
   follow-on work item. Chat turns use the existing runtime checkpoint path
   governed by ADR-0146/0150. Math ratification is the first proposal corridor,
   governed by the ADR-0172 math proposal path.
2. **Visible preconditions.** The UI shows what must be true before action is
   enabled. The math corridor requires pending state, replay equivalence, and an
   admitted handler before ratification is available.
3. **Auditable telemetry.** Every action emits an operator event with enough
   information to reconstruct what happened.
4. **Replay evidence before action.** The operator sees replay-equivalence
   status and provenance before committing a change.

Everything outside an admitted corridor remains forbidden. In particular,
corpus mutation, pack mutation, arbitrary file writes, arbitrary workflow
dispatch, hidden background workers, and unreviewed proposal mutation remain
out of bounds for v1.

### 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:

- unadmitted accept/reject buttons
- workflow dispatch
- direct corpus mutation
- pack mutation
- arbitrary file writes

### 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 in W-026.
- 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.
- Unadmitted mutation endpoints are forbidden in v1.
- Proposal reads must derive state from `ProposalLog.current_state()`, not by
  treating append-only JSONL events as proposal rows.

## 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-unadmitted-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 and see whether any admitted corridor applies,
6. inspect a trace/replay artifact,
7. perform a basic chat turn,
8. verify no unadmitted mutation path exists.

## Explicit deferrals

- multi-user collaboration
- cloud deployment
- mobile UI
- auth, unless a separate ADR admits it after the local read-only boundary is
  proven
- unadmitted proposal accept/reject buttons
- workflow dispatch
- corpus or pack mutation
- arbitrary file writes
- packaged desktop app
- public marketing site
- arbitrary plugin/tool execution

## Prototype branch rejection criteria

Do not continue from a prototype branch that:

- mixes W-026 with W-027/W-028 frontend or trace/chat work
- adds auth before the local read-only API boundary is accepted
- adds FastAPI, uvicorn, pydantic, or another web framework without ADR review
- claims replay equivalence by comparing an artifact digest to itself
- returns placeholder trace data as a successful trace response
- parses proposal log events as if they were proposal records
