Unified Workspace Intelligence Runner

Use one command when you want the latest answer to these questions:

• What projects and relationships exist now?
• What changed, and what may be affected?
• Is the workspace healthy and ready?
• What should developers, CI, IDEs, and AI tools read?

Run it from a Workspai workspace root or any project with a validated workspace binding:

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

generic is the vendor-neutral context surface. Replace it with codex, claude, cursor, or orca for agent-specific context. The agent-sync stage also publishes shared grounding for GitHub Copilot, VS Code, and AGENTS.md consumers.

Workspai runs the required steps in a fixed order and saves one final report. The technical contract writes that report atomically to .workspai/reports/workspace-intelligence-run-last-run.json with schema workspace-intelligence-run.v1. JSON stdout returns the same report payload. Consumers should read the persisted report when they need durable evidence and use the process exit code for the immediate automation verdict.

Execution envelope and canonical chain

The runner separates prerequisite operations from the versioned intelligence chain. sync and baseline handling are reported in preflight; they are not additional chain stages.

Execution order

sync
  -> model
  -> baseline resolution
  -> diff
  -> impact
  -> doctor-evidence
  -> contract-evidence
  -> analyze-evidence
  -> readiness-evidence
  -> verify
  -> context
  -> agent-sync
  -> explain

The report always contains exactly two ordered preflight entries:

ID	Execution point	Successful result	Purpose
sync	Before model	synchronized	Reconcile workspace inventory and contract inputs.
baseline	After model, before diff	created or reused	Ensure Diff has an explicit structural baseline.

The report always contains exactly these 11 ordered stages:

Order	Stage	Contract role
1	model	Build and persist the current workspace model.
2	diff	Compare the current model with the selected baseline.
3	impact	Calculate affected projects and transitive consequence.
4	doctor-evidence	Refresh workspace and project health evidence.
5	contract-evidence	Verify the workspace contract.
6	analyze-evidence	Refresh structural and operational analysis.
7	readiness-evidence	Refresh pre-verify release-readiness evidence.
8	verify	Produce the definitive evidence-backed gate.
9	context	Build agent context from the same current evidence.
10	agent-sync	Project canonical context into agent and IDE surfaces.
11	explain	Explain the resulting release posture and blockers.

The machine-readable authority is workspace-intelligence-chain.v1.json. Commands, websites, IDEs, CI jobs, and agent instructions must not define a different order or insert sync or snapshot-baseline into stages.

Baseline semantics

On the first run, the runner creates .workspai/reports/workspace-model-snapshot.json and reports:

{
  "id": "baseline",
  "status": "passed",
  "result": "created"
}

On later runs, it reuses the existing snapshot and reports result: "reused". baselineCreated is true only when that run created the baseline.

The runner does not silently replace an existing baseline immediately before Diff. Doing so would erase the change boundary and incorrectly report no changes. Refresh or replace a baseline only through the explicit workspace snapshot workflow after the intended structural state has been accepted.

Status and exit semantics

Report status	Exit code	Meaning
passed	0	Every operation executed and no gate blocked the run.
failed	1	A required operation threw or could not complete. Downstream stages are recorded as skipped.
blocked	2	Execution completed, but one or more evidence or verification gates rejected readiness.

The canonical mapping is passed → 0, failed → 1, and blocked → 2.

A blocked evidence stage does not stop the chain. Context, grounding, and Explain must still be refreshed so humans and agents receive the current blocker evidence. A hard failed stage stops execution work and every downstream canonical stage is recorded with status: "skipped", exitCode: 0, and durationMs: 0.

Stage invariants:

• passed requires exitCode: 0;
• blocked requires a non-zero stage exit code;
• failed requires exitCode: 1;
• skipped requires exitCode: 0 and durationMs: 0;
• report status and exit code are derived from all preflight and stage results;
• every stage artifact list must exactly match the runtime registry.

--strict promotes warning-grade readiness states such as Analyze needs-attention and Readiness warn into blocked stage verdicts. It does not turn evidence blockers into execution failures: the aggregate exit remains 2, not 1.

Report contract

The durable report contains:

{
  "schemaVersion": "workspace-intelligence-run.v1",
  "chainSchemaVersion": "workspai-workspace-intelligence-chain-v1",
  "generatedAt": "2026-07-18T00:00:00.000Z",
  "workspacePath": "/absolute/machine-local/path",
  "baselineCreated": false,
  "preflight": [],
  "status": "blocked",
  "exitCode": 2,
  "stages": [],
  "artifactPath": ".workspai/reports/workspace-intelligence-run-last-run.json"
}

The abbreviated arrays above illustrate the envelope only; conforming reports must contain exactly two preflight entries and 11 stages. The complete JSON Schema is workspace-intelligence-run.v1.json. Structural schema validation is necessary but not sufficient. Workspai also enforces stage order, registered artifacts, baseline coherence, failure propagation, and aggregate verdict semantics before writing the report.

workspacePath and some underlying evidence can contain machine-local absolute paths. Do not treat the run report as a portable workspace identity contract or publish it without applying the relevant redaction policy.

CI consumption

The simplest hard gate is:

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

Both exit 1 and exit 2 fail a normal CI step. If artifacts must be uploaded after a blocked run, allow the runner step to continue, upload with if: always(), then fail the job from the recorded step outcome. See examples/ci-agent-grounding.yml.

Automation must distinguish:

• exit 1: repair execution, environment, permissions, corruption, or another hard runtime failure;
• exit 2: inspect Analyze, Readiness, Verify, and Explain evidence and resolve the reported blockers;
• exit 0: consume the newly refreshed artifacts.

Do not parse terminal prose. Read status, exitCode, preflight, stages, and their registered artifacts from the JSON report.

When Verify publishes resolutionHints, an evidence-backed step includes its exact sourceCommand and sourceArtifact. Consumers should run that producer command instead of substituting a generic Analyze refresh, then re-run Verify.

Verified engineering goals

The intelligence runner answers what is true now. A verified goal adds the durable definition of what must become true, so a person or agent can resume work without changing the success criteria between attempts.

# Prepare the whole workspace for release.
npx workspai workspace goal plan release-readiness --json

# Remove blocking dependency vulnerabilities from one registered project.
npx workspai workspace goal plan dependency-security --scope project:api --json

# Raise one project's measured coverage to at least 75%.
npx workspai workspace goal plan test-coverage --scope project:web --target 75 --json

# Re-measure the goal against current source and evidence.
npx workspai workspace goal verify <goal-id> --json

Planning writes an immutable goal definition and its current status under .workspai/goals/<goal-id>/. Verification also refreshes the canonical latest verdict at .workspai/reports/verified-goal-last-run.json. Consumers must read the JSON verdict; they must not infer success from an agent message or a source edit alone.

The three shipped goal kinds have explicit completion rules:

Goal kind	Completion boundary
release-readiness	Readiness passes and Workspace Verify reports ready.
dependency-security	A fresh audit reports zero blocking vulnerabilities and required checks pass.
test-coverage	Runtime-owned coverage reaches the selected percentage and required checks pass.

Goals are workspace-scoped by default. Use --scope project:<registered-name> when the requested outcome belongs to one project. Dependency goals preserve a hash baseline for recognized manifests and lockfiles across supported ecosystems. Breaking or force-based changes remain forbidden unless the goal explicitly records --allow-breaking or --allow-force; changing a manifest alone never satisfies the goal.

--no-run only reads current goal evidence. --reuse-intelligence may reuse a just-completed canonical run, but it does not waive goal-specific measurement. The goal schemas are verified-goal.v1.json and verified-goal-status.v1.json.

Relationship to other commands

workspace intelligence run is the canonical Workspace Intelligence chain. pipeline is a broader governance/release orchestrator and autopilot release is a separate release surface. Neither command may replace, reorder, extend, or silently partially execute the canonical intelligence chain.

Individual commands such as workspace model, workspace diff, and workspace verify remain useful for inspection and targeted renewal. A partial manual sequence must not be documented or treated as an equivalent replacement for the unified runner.