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 status, exit code, duration, message, and its contract-owned artifact list.

Blocked is not failed

The aggregate runtime contract distinguishes three outcomes:

A blocked evidence stage does not terminate the chain. Context, Agent Sync, and Explain still refresh so humans and agents receive the current blocker.

A hard failed stage behaves differently. Every downstream stage is recorded as skipped with zero exit code and duration instead of disappearing from the report.

Strict mode can promote warning-grade readiness states to blocked verdicts. It does not rewrite an evidence blocker as an execution failure.

How an agent should use the loop

An autonomous repair agent should not call the eleven commands 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. rerun the earliest invalidated stage;
5. allow downstream evidence to regenerate 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.