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

```text
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:

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