The Workspace Intelligence Loop Is a Decision Contract

“Analyze the workspace” sounds like one operation. It is actually a sequence of different decisions.

If those decisions are merged, reordered, or skipped without evidence, a tool can produce a confident answer from the wrong state. Workspai therefore exposes one canonical chain:

The chain is not a progress animation. It is a runtime contract.

Why order matters

Impact without a current model can describe an old workspace.

Readiness without current doctor and contract evidence can approve a broken toolchain or invalid boundary.

Agent context generated before verification can faithfully package a false claim.

Explanation without the stage record can turn an incomplete run into a polished story.

The order protects downstream decisions from upstream ambiguity.

Preflight is not a hidden stage

Workspai records two deterministic prerequisites outside the canonical stage array:

Sync      before Model
Baseline  after Model, before Diff

Sync reconciles workspace inventory and contract inputs. Baseline resolution ensures Diff has an explicit structural comparison point. Both appear in the run report's preflight array; neither increases the canonical stage count.

Graph queries, watch mode, evaluation, MCP, pipeline, and release autopilot are also valuable surfaces. They remain auxiliary rather than silently redefining the eleven-stage contract.

Run the chain

From the workspace root:

npx workspai workspace intelligence run \
  --for-agent generic \
  --strict \
  --json

The durable summary is written to:

.workspai/reports/workspace-intelligence-run-last-run.json

Each stage records its outcome, duration, message, and contract-owned artifact list.

Blocked is not failed

The runner can complete with a healthy decision, complete with evidence that still blocks the decision, or be unable to finish a required operation.

That distinction matters more than a process number. A blocker is useful evidence: the inspection worked and found a reason not to call the workspace ready. Context, Agent Sync, and Explain still refresh so people and agents receive that reason.

An execution problem is different. It means Workspai could not finish the inspection, so downstream decisions are not presented as current.

How an agent should use the loop

An autonomous repair agent should not walk the stages mechanically and hope the blocker disappears. It should:

1. locate the blocking decision and its producer evidence;
2. trace the proof back to source;
3. change source or configuration when a real defect exists;
4. identify the earliest evidence boundary invalidated by that change;
5. rerun the unified chain so downstream evidence regenerates in contract order;
6. stop at verified completion or a genuine external boundary.

Refreshing reports without changing the cause is not repair. Repeating model calls against identical source and evidence is not progress.

The contract supplies the stage order, evidence ownership, and completion semantics. The model still uses its tools and reasoning to find the correct source-level fix.

The reverse path matters

The forward chain produces a decision. Repair moves backward from that decision to its source:

When readiness reports a dependency vulnerability, editing the readiness JSON would only alter a generated symptom. The agent needs to identify the affected project and dependency evidence, make an allowed source or lockfile change, and then regenerate the invalidated decisions.

This pattern generalizes beyond dependency findings. It applies to stale contracts, missing metadata, API drift, runtime policy failures, and future blocker types for which no custom repair tool exists.

One loop, several consumers

The same contract is consumed by:

• the CLI;
• CI workflows;
• Workspai for VS Code;
• MCP clients;
• generated agent packs;
• future SDKs and independent packages.

A narrow UI may show only the active stage and its neighboring stages. An MCP client may query one current decision. Those are projections.

The stage IDs, order, preflight semantics, artifacts, and skip behavior still come from the same machine-readable contract. Otherwise the interface becomes a second architecture.

That is the difference between displaying a workflow and implementing one.

The practical command surface is documented in the CLI reference. The proof and freshness rules behind the loop are explained in Evidence.