kami
53d8108189
Vikunja #167/#168/#169. #167 PlanGrounder (infrastructure/workflow): build-prereq + touches-scope existence grounding, emits PlanGroundingEvaluatedEvent. Deterministic fold over recorded workspace/plan events (invariants #8/#9). #168 positive-pattern mining (SessionOrchestratorPlanPatterns): mine SuccessfulPlanShape from cross-session log — a locked plan whose own workflow later completed — and inject the closest-resembling plan shape as L0/SYSTEM advisory context for the planning stage. Keyword-Jaccard resemblance, no LLM/embedder, replays identically. Advisory only (#3). #169 stage-prompt audit + CORREX_STAGE_GUIDANCE ON/OFF toggle in SessionOrchestratorExecution. RunCommand gains --intent to seed a freestyle session over REST. Also: workspace verification events + concept-compiler wiring. ./gradlew check green.
108 lines
6.0 KiB
Markdown
108 lines
6.0 KiB
Markdown
# 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.
|