diff --git a/docs/workbench/acceptance-gates.md b/docs/workbench/acceptance-gates.md index d5ba2c6b..5884ac08 100644 --- a/docs/workbench/acceptance-gates.md +++ b/docs/workbench/acceptance-gates.md @@ -15,7 +15,7 @@ The planning branch is acceptable when it includes: - data-shape contract - UI component map - explicit non-goals -- explicit mutation boundaries +- explicit mutation boundaries and admitted-corridor requirements - work queue for W-026 through W-031 ## W-026 — Read-only API gates @@ -29,7 +29,7 @@ Required: - path traversal tests for artifact readers - proposal event-log read-model tests using `ProposalLog.current_state()` - unknown trace ids return `404`, not placeholder success payloads -- no proposal accept/reject route +- no proposal accept/reject route outside an admitted corridor - no corpus mutation route - no pack mutation route - no workflow dispatch route @@ -64,7 +64,7 @@ Required: - top runtime bar - empty states for all modules - API client shape aligned to `data-shapes-v1.md` -- no mutation buttons +- no mutation buttons outside an admitted corridor - no fake/mock runtime as permanent architecture Acceptance command candidates: @@ -103,13 +103,18 @@ Required: - display replay evidence - display proposed chain - display suggested CLI copy command +- mutation only through admitted corridors: + ADR-governed path, visible preconditions, auditable telemetry, and replay + evidence before action Forbidden: -- accept button -- reject button +- unadmitted accept/reject button - workflow dispatch -- direct proposal mutation +- direct proposal mutation outside an admitted corridor +- corpus mutation +- pack mutation +- arbitrary file writes ## W-030 — Eval Center gates @@ -150,17 +155,18 @@ The v1 workbench is releasable when an operator can: 1. start the local API, 2. open the UI, 3. see runtime status, -4. inspect a proposal without mutating it, +4. inspect a proposal and see whether an admitted corridor applies, 5. run/view contemplation-quality, 6. inspect trace/replay metadata, 7. perform a basic chat turn, -8. verify from UI copy and docs that no hidden ratification/mutation path exists. +8. verify from UI copy and docs that no unadmitted ratification/mutation path exists. ## Red flags Any of these should block merge: -- UI can accept/reject proposals in v1 +- UI can accept/reject proposals without an admitted corridor, visible + preconditions, auditable telemetry, and replay evidence - API exposes arbitrary path reads - API invokes shell from user input - frontend hardcodes fake eval/proposal data as product path diff --git a/docs/workbench/implementation-plan.md b/docs/workbench/implementation-plan.md index 44ebd3da..4e92dba9 100644 --- a/docs/workbench/implementation-plan.md +++ b/docs/workbench/implementation-plan.md @@ -1,8 +1,10 @@ # 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 +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 @@ -11,7 +13,7 @@ boundaries while making the system legible to operators, engineers, and auditors | 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 | No | +| 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 | @@ -32,7 +34,8 @@ No code beyond docs. ### Phase 1 — Read-only API skeleton -Goal: expose a narrow local workbench API without introducing new mutation paths. +Goal: expose a narrow local workbench API without introducing unadmitted +mutation paths. Deliverables: @@ -61,7 +64,8 @@ Strict rules: 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. +- 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. @@ -113,6 +117,31 @@ 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. @@ -128,10 +157,11 @@ Deliverables: Forbidden in v1: -- accept button -- reject button +- unadmitted accept/reject buttons - workflow dispatch - direct corpus mutation +- pack mutation +- arbitrary file writes ### Phase 5 — Eval Center @@ -170,7 +200,7 @@ Deliverables: - 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. +- 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. @@ -191,7 +221,7 @@ Each implementation PR must include: - 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 +- no-unadmitted-mutation regression checks for read-only routes ## Release criteria for v1 @@ -201,10 +231,10 @@ The v1 workbench is accepted when an operator can: 2. open the UI, 3. inspect runtime status, 4. run or view contemplation-quality, -5. inspect a proposal without accepting it, +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 hidden mutation path exists. +8. verify no unadmitted mutation path exists. ## Explicit deferrals @@ -213,8 +243,10 @@ The v1 workbench is accepted when an operator can: - mobile UI - auth, unless a separate ADR admits it after the local read-only boundary is proven -- proposal accept/reject buttons +- unadmitted proposal accept/reject buttons - workflow dispatch +- corpus or pack mutation +- arbitrary file writes - packaged desktop app - public marketing site - arbitrary plugin/tool execution diff --git a/docs/workbench/wave-1-evidence-spine.md b/docs/workbench/wave-1-evidence-spine.md index 5c5645c5..227744da 100644 --- a/docs/workbench/wave-1-evidence-spine.md +++ b/docs/workbench/wave-1-evidence-spine.md @@ -251,10 +251,10 @@ envelope. ### 1F. Mutation Doctrine Reconciliation -- [ ] Update `docs/workbench/implementation-plan.md` mutation section to match +- [x] Update `docs/workbench/implementation-plan.md` mutation section to match reality -- [ ] Update `docs/workbench/acceptance-gates.md` to reflect admitted corridors -- [ ] Document the honest rule: +- [x] Update `docs/workbench/acceptance-gates.md` to reflect admitted corridors +- [x] Document the honest rule: **The mutation rule is not "no buttons ever." It is:** @@ -270,10 +270,10 @@ envelope. proposals. This is the template for future mutation surfaces, not an exception to a "no mutation" rule. -- [ ] Record what already exists: `ratify_math_proposal`, `reject`, `defer` +- [x] Record what already exists: `ratify_math_proposal`, `reject`, `defer` in `workbench/api.py` lines 112+; `RatificationCommandPanel.tsx` with precondition gates -- [ ] No new mutation endpoints in Wave 1 beyond what exists +- [x] No new mutation endpoints in Wave 1 beyond what exists ---