Doctor

The doctor does not call a model and does not judge whether your architecture is good. It checks things with a definite answer: required files, required sections, evidence behind a completion claim, references to decisions and code, and a few signals of memory going stale. Same input, same report, every run. That is what lets it sit in a pre-commit hook and in CI without anyone second-guessing it.

Running it

$ persist doctor          # human-readable report
$ persist doctor --json   # machine-readable, schemaVersion persist.doctor.v1

The report lists findings grouped by severity, then the checks that could not run and why, then the result. This is a repository right after init, one ADR, and one module:

$ persist doctor
Doctor Report

WARNING
- Security model authentication and authorization section is still an unfilled template. (docs/20-security/SECURITY_MODEL.md)
- Product purpose is still an unfilled template. (docs/00-product/PRODUCT.md)
- Product users section is still an unfilled template. (docs/00-product/PRODUCT.md)
- Module memory purpose is still an unfilled template. (docs/30-modules/billing/MODULE.md)
- Module memory owns section is still an unfilled template. (docs/30-modules/billing/MODULE.md)
- Conventions canonical-primitives section is still an unfilled template. (docs/60-engineering/CONVENTIONS.md)

INFO
- Persist OS config validates. (.persist/config.json)
- 1 feature folders detected.
- 1 module folders detected.
- 2 ADRs detected.

Result: WARNINGS

Exit codes

• 0 Healthy No errors and no warnings. Result: PASSED.
• 1 Warnings only Something to look at. Result: WARNINGS.
• 2 Errors Memory is broken or a claim lacks evidence. Result: FAILED.

Info findings never change the exit code. Exit 1 is still non-zero, and a CI step fails on any non-zero exit — but the generated pre-commit hook reads the exit code and only fails on errors, so a warning is visible without blocking the commit. This is a recorded commit attempt right after persist feature create, before any template was filled:

$ git commit -m "Plan the checkout feature"
Doctor Report

WARNING
- Security model authentication and authorization section is still an unfilled template. (docs/20-security/SECURITY_MODEL.md)
- Product purpose is still an unfilled template. (docs/00-product/PRODUCT.md)
- Product users section is still an unfilled template. (docs/00-product/PRODUCT.md)
- Conventions canonical-primitives section is still an unfilled template. (docs/60-engineering/CONVENTIONS.md)

INFO
- Persist OS config validates. (.persist/config.json)
- 1 feature folders detected.
- 0 module folders detected.
- 0 ADRs detected.

Result: WARNINGS
[main 305fdb2] Plan the checkout feature
 2 files changed, 50 insertions(+)
[exit 0]
$ git log --oneline
305fdb2 Plan the checkout feature
8c93abe Add repository memory

Every check

Checks run in this order. The first two run always; the rest need a valid .persist/config.json, because they depend on the configured paths.

The fence loop

A staged change to source with no recorded reason and no ADR reference is a fence crossing. Brand-new files never count — a new file has no existing logic to misunderstand — so creating a migration is quiet while editing an old one still asks why. Generated and cache folders are out of scope too. Doctor names the rewritten lines with their hunk context, so the question is answerable as asked, and warns rather than blocks. A change that only adds lines still warns, naming its insertion points. When nothing is staged, for example because a commit was made with the hooks off, doctor checks the commits the branch hasn't pushed yet, so the question still comes up. Trimmed to the finding:

$ persist doctor
Doctor Report

WARNING
- Change rewrites existing code in src/billing.js with no recorded reason: line 2 (in `export function writeOrder(order) {`). Ask the person who knows: was that behaviour deliberate? If yes: persist fence add src/billing.js --why "<reason>" --by <name>. If no: persist fence add src/billing.js --no-constraint --by <name>. (src/billing.js)
…
Result: WARNINGS

The answer comes from a person, because the constraint lives in someone’s memory rather than in the code. persist fence add writes it in the exact shape doctor and the SessionStart hook read, and refuses a path that does not exist:

$ persist fence add src/billing.js --why "Writes four collections in one transaction so the ledger and the audit trail cannot diverge." --by Priya
Persist OS fence add complete.
Fenced: src/billing.js
Created:
- docs/60-engineering/FENCES.md

From then on, a change to that path hands the reason back instead of asking again:

$ persist doctor
Doctor Report

INFO
…
- Change touches a recorded fence: Writes four collections in one transaction so the ledger and the audit trail cannot diverge. (see docs/60-engineering/FENCES.md). Confirm the reason still holds before changing the logic. (src/billing.js)
…
Result: PASSED

The honest answer is sometimes that nothing in the file is deliberate — and that is recorded too. persist fence add src/billing.js --no-constraint --by Priya writes a No constraint entry naming who confirmed it, and the file stays quiet from then on. A later --why for the same path replaces the standing line and keeps the history; --no-constraint over a recorded reason is refused. Cleared files are not injected into sessions — they answer nothing an agent needs before editing.

The file starts empty and grows only through fence add; nothing generates it. Rename or delete a fenced file and doctor names the entry that now points at nothing.

Not evaluated is not a pass

When a check has nothing to look at or cannot run, the report says so instead of silently passing. In a fresh repository with no ADRs, features, or modules, standards and content are listed as not evaluated with the reason. The config-dependent checks are all not evaluated when the config is missing or invalid. staleness and fence are not evaluated outside a git repository (staleness also in a shallow clone), and fence also when nothing is staged and the branch has no upstream; hooks-active outside git and in CI; hook-drift is not evaluated when a hook file is missing; retired-skills when the skills directories do not exist; duplicate-titles when the ADR directory does not exist. Each one carries a reason, in both the text report and the JSON.

$ persist doctor
Doctor Report

INFO
- Persist OS config validates. (.persist/config.json)
- 0 feature folders detected.
- 0 module folders detected.
- 0 ADRs detected.

NOT EVALUATED
- standards: no feature folders or ADRs exist, so there are no completion claims or decisions to check
- content: no feature folders, module folders, or ADRs exist, so there is no memory content to check
- fence: nothing is staged and the branch has no upstream, so there is no change to check — the pre-commit hook checks each commit as it is made
- governing-adrs: no accepted ADR lists the paths it governs (an Applies To section), so no change can be matched to a decision

Result: PASSED

The same fresh memory in a folder that is not a git repository: every check that reads git says so.

$ persist doctor
Doctor Report

INFO
- Persist OS config validates. (.persist/config.json)
- 0 feature folders detected.
- 0 module folders detected.
- 0 ADRs detected.

NOT EVALUATED
- standards: no feature folders or ADRs exist, so there are no completion claims or decisions to check
- content: no feature folders, module folders, or ADRs exist, so there is no memory content to check
- staleness: not a git repository, so commit history is unavailable
- ignored-files: not a git repository, so ignore rules cannot be evaluated
- hooks-active: not a git repository, so there is no clone to switch the hooks on in
- fence: not inside a git work tree, so the staged set is unknown
- governing-adrs: no accepted ADR lists the paths it governs (an Applies To section), so no change can be matched to a decision

Result: PASSED

The JSON report

--json is for CI artifacts, hooks, and agent handoffs. The schema is versioned so tooling can depend on it. Abridged from a real run:

{
  "schemaVersion": "persist.doctor.v1",
  "status": "warnings",
  "exitCode": 1,
  "summary": {
    "errors": 0,
    "warnings": 6,
    "info": 4
  },
  "findings": [
    {
      "severity": "info",
      "check": "config",
      "message": "Persist OS config validates.",
      "path": ".persist/config.json"
    },
    {
      "severity": "warning",
      "check": "content-product",
      "message": "Product purpose is still an unfilled template.",
      "path": "docs/00-product/PRODUCT.md"
    }
  ],
  "checks": [
    { "id": "config", "status": "evaluated" },
    { "id": "staleness", "status": "not-evaluated", "reason": "…" }
  ]
}

findings[].check is a fine-grained rule id such as content-product or standards-adr-consequences; checks[].id is the check module from the table above. They are different namespaces on purpose.

Where it runs

Pre-commit hook

.persist/hooks/pre-commit runs persist doctor first, then your preCommitGates. Init switches it on when you agree; other clones run git config core.hooksPath .persist/hooks once.

CI

.github/workflows/persist.yml runs npx --yes persist-os@latest doctor on pull requests and pushes to main, with full history so the staleness check can run.

The completion loop

The generated agent rules end every piece of work with persist doctor. For a human the same loop is pnpm test:run && pnpm typecheck && persist doctor.

What it will not catch

Contradictions in meaning. An accepted ADR that says one thing while the code does another passes every structural check. That judgment stays with the people and agents doing the work, because the moment the gate needs a model to decide whether two documents agree, it stops being something you can trust blindly.