Workspace Doctor

Doctor is the diagnostic layer of Workspace Intelligence. It checks each project in its real workspace context, then explains what passed, what needs attention, and what can be repaired safely.

For one project:

npx workspai doctor project --json

For the whole workspace:

npx workspai doctor --json

For a compact automation payload or a forced live scan:

npx workspai doctor workspace --json=summary
npx workspai doctor workspace --fresh --json=summary

Human-readable output is useful in a terminal. JSON output is the durable interface for CI, the VS Code extension, and AI agents.

A versioned diagnosis, not a health score

In 0.56, Doctor publishes a canonical diagnosis with stable finding identities, causal groups, confidence, proof bindings, repair disposition, unknowns, and contradictions. Its completeness boundary spans six diagnostic domains: structure, dependencies, lifecycle, quality, configuration, and delivery.

This separation matters to consumers. A finding is the observed problem; a causal group explains related findings; a capability says whether Workspai can act; a receipt records what was actually attempted. A summary projection is bounded for agents and CI, but does not replace the complete diagnosis artifact.

The machine-readable Doctor family has distinct responsibilities:

The full workspace result is persisted at .workspai/reports/doctor-last-run.json; the compact receipt is written to .workspai/reports/doctor-receipt-last-run.json. Capability and validation artifacts use .workspai/reports/doctor-capabilities.json and .workspai/reports/doctor-validation-last-run.json. Consumers should validate the declared schema instead of identifying a payload only by its filename.

Inspect the runtime and framework capability registry or validate its governed corpus:

npx workspai doctor capabilities --json
npx workspai doctor capabilities --runtime rust --json
npx workspai doctor capabilities --framework nextjs --json
npx workspai doctor capabilities --validate --write --json

--fresh bypasses Doctor's project scan cache. Use it when a consumer needs live evidence rather than a compatible persisted scan.

Capability coverage is fail-closed. An adapter can report full, partial, or unsupported behavior per diagnostic domain; discovering a runtime or framework does not imply that every probe or repair is available on every platform.

Evidence and repair posture

Doctor records the evidence behind each finding. Depending on the runtime, that can include dependency security, tests, formatting, environment configuration, containers, deployment surfaces, migrations, health probes, lockfiles, and native quality tools.

Every repair capability is classified before execution:

• safe — deterministic and low risk;
• guarded — requires review or approval;
• breaking — may change compatibility and is never silently applied;
• manual — Workspai can explain the gap but cannot make the decision for you.

Missing tools, unsupported adapters, unmet preconditions, policy limits, and source-level ambiguity are explicit decision causes. They are not silently converted into model execution or reported as successful repair.

Doctor's diagnosis is consumed by Readiness, Verify, remediation planning, and the Repair Engine. Those consumers should use stable finding identities and causal groups instead of re-parsing human-readable Doctor lines into a second diagnosis.

Graph-aware diagnosis

Doctor can use the current workspace graph to explain affected projects and related surfaces. The graph does not invent a diagnosis: source proofs and runtime checks remain the evidence. Missing or partial extraction stays visible as an unknown instead of being reported as success.

From finding to repair

A blocker is not closed because a manifest changed. Dependency repairs, for example, must reconcile the manifest, lockfile, and installed tree, then run focused audit, tests, build, the intelligence loop, and final verification.

See Verified AI Repair for that full transaction.