Finding what is stale in a checkout before you pay for a full test run

What question it answers

"What is structurally inconsistent or stale in this project, before I edit it or pay for a full verification run?" An agent arriving at an unfamiliar checkout has one expensive way to find out whether the repository is coherent, and most of what goes wrong before you touch anything is not a failing test at all.

The command sits in a five-question ladder where each rung has a different cost and a different meaning: `app inspect` asks what is composed, `project doctor` asks what is inconsistent or stale in the source, `package test` asks whether one package satisfies the contract, `solution check` asks whether a plan still fits, and `npm run verify` asks whether everything actually works. Only the last one runs tests, and it is roughly a thousand times slower.

What it does

`npm run crm -- project doctor --json` emits `projectDoctorContract: 1` across seven categories — composition, packages, modules, plans, skills, docs, hygiene — with per-check `status`, `authority`, `subject`, `evidence`, `reason` and `remediation`, plus a compact `problems[]` view carrying every failure and nothing else.

Every check names the authority it speaks for, and `AUTHORITIES` is a closed list that `check()` throws on, so a future check cannot be added without naming who refuses it. There is deliberately no `doctor` authority: composition problems come verbatim from the inspector, module-state drift from `readModuleState` (the same ADR-019 authority the module factory evolves from), plan staleness from `bindSolutionPlan`, the package private-import rule from the same function `crm package validate` uses, hygiene from `git ls-files`.

Run here on 2026-08-09 it printed `"ok": true`, status `passed`, project kind `framework-repository`, composition `valid`, 136 documents scanned, three Solution Plans discovered, one candidate package located, and counts of 9 passed, 0 warning, 0 failed, 4 not applicable. The four not-applicable rows are the interesting ones: `packages.source-boundary — NO_PACKAGES_COMPOSED`, `modules.migration-history — NO_MODULE_STATE_FILES`, and two Solution Plans marked `PLAN_NOT_DECLARED_CURRENT — it no longer binds to this composition, which for an undeclared plan is a fact rather than a fault`.

That last verdict is a design decision with a name. Staleness is graded only for a plan the project declares in `package.json` under `agentCrm.solutionPlans`: a declared `required` plan that no longer binds fails, a declared `current` one warns, an undeclared one is not applicable and still carries its evidence. Two of this repository's three checked-in plans are historical design examples, and warning about them on every run is exactly the fatigue that teaches a reader to skim past the warnings that matter.

It refuses to invent rules, and the ExecPlan records both refusals in detail. No fuzzy comparison of generated source against a re-render, because the re-render differs for a dozen innocent reasons and a check that cries wolf is one people silence. No anchor parsing in documentation links, because heading-to-slug is a guess. Documentation links are read as prose with fenced blocks and inline code blanked first — a guide that shows a Markdown link inside a fence is documenting syntax, not linking anywhere.

What it refuses to claim

Twelve codes, printed in the report and in the human view under the heading "What this does not prove". Verbatim: `DOMAIN_CORRECTNESS_NOT_PROVEN` (nothing here executes an action, evaluates a policy or drives a state transition — a project can be perfectly consistent and compute the wrong number), `NOT_A_SUBSTITUTE_FOR_VERIFY` (no test is run; a green doctor means the source is self-consistent, not that the software works), `DATABASE_NOT_INSPECTED`, `PROVIDER_HEALTH_UNKNOWN`, `SECRETS_NOT_INSPECTED` (the hygiene check asks git which paths are tracked; it never opens them), `PRODUCTION_READINESS_NOT_ASSESSED`, `PACKAGE_CONFORMANCE_NOT_RUN` (packages are checked for the source-boundary rule only), `DISCOVERY_IS_BY_CONVENTION` (something kept elsewhere is not seen, and its absence from this report is not a statement that it is fine), `UNCOMPOSED_PACKAGES_NOT_CLASSIFIED`, `PLAN_CURRENCY_IS_DECLARED`, `GENERATED_SOURCE_DRIFT_LIMITED` and `NO_MUTATION` (this command changes nothing; every finding carries the existing command that would fix it, and there is no `--fix`).

`UNCOMPOSED_PACKAGES_NOT_CLASSIFIED` is the one with a scar behind it. Package discovery took three attempts, and two of them produced false failures — first by treating every directory under `packages/` with a `src/index.js` as a package and reporting eight boundary violations in a repository that has none, then by string-matching `definePackage(` and grading a package that did not exist while missing one whose import was aliased. The version that holds parses no package source at all: the inspector says which packages exist, the composition file's own import specifiers say where they are, and a directory the composition does not reference is not classified at all. Telling kernel code from an unreferenced domain package would mean executing it, and guessing is what produced the false failure twice.

A warning never fails the run. A stale Solution Plan and a one-sided Skill mirror are information owned by somebody else, and a doctor that failed the build for them is a doctor people stop running.

What it costs to run

Measured here on 2026-08-09: about 0.38 s wall clock for `--json`, exit code 0, nothing written. The ExecPlan's own measurements put it at ~155 ms against ~122 ms for the single inspection it performs and ~156,000 ms for `npm run verify` — roughly 1.3× the load it reuses, and about a thousandth of the cost of the run it is not a substitute for. The stated budget follows from those measurements rather than from an invented target: under a second on a project this size, and within roughly 1.5× the inspection it already performs.

It loads the composition exactly once and reuses it for the composition checks, every plan binding and the `inspectionFingerprint`; a test asserts the loader is called precisely once. That load gets a 10-second bound rather than the inspector's default 60, because a command whose entire proposition is that it costs 150 ms must not silently cost a minute — and a timeout is reported as a timeout, naming the command that waits longer.

Exit codes: `0` no failures, `1` inconsistencies, `2` not a readable project. Nothing in the document carries an absolute path, a stack frame, a source body, a secret or a timestamp.

Where it fits

Before you edit. It is the cheap rung of the ladder — the one you can afford to run on arrival, after a merge, or between edits, which is a different tool from the one you run before a merge.

It is deliberately not the runtime `crm doctor` that already exists: that one boots the application, opens the database and reports runtime counts, and cannot run on a project that does not boot. This one reads source, opens nothing, and works precisely when the application will not start — which is when a diagnostic is worth having.