correx/docs/specs/2026-07-15-closed-loop-workspace.md

Closed-loop workspace

Decision

Treat workspace truth as a recorded control-plane fact, not a terminal-stage hope. A plan may run only after its declared assumptions are grounded; every code-producing stage must leave a recorded verified increment before another implementation stage proceeds. Artifact-schema validation remains useful, but it is not evidence that the workspace compiles, builds, or satisfies its declared preconditions.

Known-good workspace invariant

After a stage that writes code/configuration, the orchestrator records one verification observation for the workspace state produced by that stage. The next implementation stage may rely only on a passing observation whose workspace state key is the current recorded state key.

• A passing observation is the authoritative known-good baseline.
• A failed or unavailable observation is a local stage failure: retry the owner, route a recovery ticket, or ask for clarification; do not continue the normal plan edge.
• A docs-only stage and a stage with no declared writes do not manufacture a compiler/build claim.
• Replay reads the recorded observation and result. It never reruns a command or rescans the live workspace.

The existing StaticAnalysisCompletedEvent records command output. The implementation should add a small workspace-verification result event (or extend that event deliberately) that binds: session, stage, state key, declared write paths, selected command/expectation, result, and the observation sequence. That binding prevents a later dirty workspace from being mistaken for the state that was verified.

Seam 1: plan grounding before lock

Plan compilation remains deterministic. Grounding is a distinct phase after structural compilation and before ExecutionPlanLockedEvent, because it needs recorded workspace facts.

Inputs, all from the current session's recorded observations:

Check	Evidence	Outcome
Declared writes/touches	workspace root and path policy; plan manifest	reject unsafe/out-of-scope paths before lock
Referenced existing paths	repo-map/workspace-state index	report an absent or ambiguous reference to the architect
Referenced symbols	grounding-grade symbol index, not L3 similarity	report unresolved symbols with candidate paths
Build prerequisites	project profile commands plus detected manifest/config files	require an explicit bootstrap stage, clarification, or verified prerequisite
Stage ordering	writes, prerequisites, and verification requirements	reject a stage that depends on an unverified prior increment

The repo map is an input catalog, not proof: its L3 embeddings are deliberately excluded from this phase. The grounding index must expose exact paths and best-effort symbols from an observation recorded at plan time. If the index cannot prove an assumption, the outcome is unknown, never present.

The phase emits a PlanGroundingEvaluated observation containing the plan identity, workspace state key, findings, and verdict (pass, return_to_architect, or clarification_required). A non-pass verdict prevents the plan lock; the architect receives compact findings and produces a new plan. That makes a doomed scaffold fail at stage 0 rather than after downstream files accumulate.

Seam 2: verified increments in the orchestrator

For a stage with declared writes, the stage-success path is:

write/tool evidence → contract/static checks → selected build/test command
  → WorkspaceVerificationObserved(pass, stateKey) → transition to next implementation stage

On a failed command, missing prerequisite, or state-key mismatch:

WorkspaceVerificationObserved(fail/unavailable, evidence)
  → retry feedback to owner → no-progress recovery arbiter → terminal failure only after escalation

The selected command is deterministic from the stage's buildExpectation, the bound project profile, and the recorded prerequisite classification. The model cannot choose a shell command as the truth test. setup may run only when configured by the operator and is recorded separately; its success is not itself a green verification result.

The next-stage context receives a compact verified baseline entry: state key, verified command, and changed paths. It must not receive a claim that a skipped/deferred compiler assertion passed. If the stage's workspace changed after verification, the baseline is invalid and the next stage must re-observe/verify before treating it as known-good.

Early precondition signals

REFERENCE_EXISTS and similar intent-plane blocks are observations, not disposable ReAct errors. Repeated blocks for one build-critical path become a workspace_precondition failure with the path and attempts recorded. The recovery owner either creates the necessary bootstrap/configuration, or routes to clarification when the authoritative intent cannot decide whether that path should exist. This is an early warning; the per-stage verification remains the final truth check.

Increment sequence

1. #162 — per-write verification: compiler assertions render as deferred/skipped and write-declaring stages run their configured deterministic gate.
2. #163 — consume repeated hard blockers: promote repeated build-critical missing paths into recovery-eligible precondition failures.
3. Grounding index and phase: record an exact path/symbol/prerequisite snapshot, evaluate the compiled plan against it, and prevent a non-grounded plan from locking.
4. Verification invariant: bind command results to workspace state keys; inject the recorded verified baseline into subsequent implementation stages.
5. #165 — no-progress recovery: preserve intent-holder escalation for an increment that still cannot become verified.

Non-goals

• Do not use semantic L3 retrieval as a plan-grounding oracle.
• Do not silently synthesize ecosystem-specific manifests from a failed command.
• Do not rerun commands, inspect the filesystem, or reconstruct verification during replay.
• Do not make a terminal verifier the first build truth check for a multi-stage implementation run.