docs(vrs): specify the doctor subsystem from the code and its tests

[schickling-assistant]

Why

doctor is the only way to ask whether a catalog is healthy on a host, and it
gates real operational decisions — yet it had no VRS coverage at all. Grepping
doctor across docs/vrs/ returned nothing. Its contract lived only in the
subcommand, tests/doctor.rs, the doctor part of tests/native_only.rs, and a
single INVARIANTS.md row for retirement health. That makes it easy to change
doctor's definition of "healthy" without noticing the definition moved.

What

Adds docs/vrs/02-doctor/, the first subsystem node under docs/vrs/:

• requirements.md — the durable guarantees. What counts as healthy and
  unhealthy for tooling, supervision, catalog structure, task liveness,
  presence, and retirement; the exit contract; and what doctor must never do
  (write, repair, hang, or touch its caller's stdin).
• spec.md — the mechanism. Catalog and host resolution, the ordered check
  sequence with what each check inspects and when it fails, the per-declaration
  split between retired and live declarations, the output shape, an evidence
  table mapping each guarantee to its proof, and the open questions.

Docs only. No code, and no change to docs/vrs/vision.md, docs/vrs/requirements.md,
docs/vrs/spec.md, or INVARIANTS.md.

The 02- prefix leaves 01- free for a subsystem node already in flight.

How

Everything was derived from the implementation and the tests, not from intent:

• Behaviour comes from reading doctor_cmd in src/main.rs end to end, plus
  the modules it calls — presence reading and the derived-unknown rule, the
  per-(catalog, host) pid lock, catalog discovery, and the bounded
  non-interactive session probe with its union of both task backends.
• Each guarantee that a test pins is listed in an evidence table in spec.md
  with the qualified test name. Retirement health cites the same three tests
  INVARIANTS.md already names.
• Guarantees that hold by construction but that no test isolates are stated as
  such in a sentence directly under the evidence table, rather than being
  presented as proven.

What was deliberately left out

Anything not established by the code or a test is recorded as an open question
in spec.md instead of being written into the contract:

• DOCTOR-DQ1 — the read-only guarantee is established by inspecting the
  doctor path, not by a check. No test asserts the catalog and runtime-state
  directories are unchanged after a run, the way materialization proves its
  tracked-target guarantee.
• DOCTOR-DQ2 — discovery warnings, notably a path-vs-content disagreement
  about identity or host, are surfaced by validate and ignored by doctor.
  Whether that is correct scope or a gap is unsettled.
• DOCTOR-DQ3 — pty is checked unconditionally and is the only tool
  checked, even though a host running only terminal-free tasks does not need it.
  No test covers a missing tool.
• DOCTOR-DQ4 — retirement looks for residue; a live declaration only checks
  that its declared tasks are alive. A session belonging to no declaration on
  this host is invisible.
• DOCTOR-DQ5 — there is no machine-readable report, so the exit status is
  the entire machine contract.

Rationale

Requirements and spec are split so the two questions have separate homes: what
must hold for doctor to be correct, versus how it currently establishes that.
The check sequence, output strings, and probe bound are mechanism and live only
in spec.md; the guarantees they serve live in requirements.md and would
survive a rewrite of the mechanism.

IDs are namespaced (DOCTOR-R01, DOCTOR-A01, …) so a subsystem node never
collides with the root documents' bare R01-style IDs.

axe vrs check --profile strict docs/vrs reports zero diagnostics, and
nix flake check passes locally.

For the owner

Two things this PR deliberately does not do, both of which are yours to decide.

A root requirement may be missing. The root VRS never names doctor. R04 assigns host-local health observation, diagnosis, bounded recovery, and escalation to the root agent, and describes the st2 loop as the deterministic half. Doctor is a third thing: a deterministic, on-demand health check that needs no running supervisor. DOCTOR-R02's "manual/--once mode is healthy" arm only makes sense against a root-level requirement that host health is inspectable on demand — and no such requirement exists today. This node references R03/R04/R08 by ID and writes nothing into the root files, since docs/vrs/spec.md requires explicit approval to change them.

Presence semantics stay with R08. Doctor reads presence, so there was a standing temptation to specify the states and the staleness window that produces the derived unknown here. It does not: this node only decides which readings count as healthy. Moving presence detail into the doctor node would give R08 and this file two owners for one contract.

Posted on behalf of @schickling

field	value
agent_name	cl2-cedar
agent_session_id	e5217740-eef6-48eb-a794-3e5e11939e4d
agent_tool	Claude Code
agent_tool_version	2.1.220
agent_runtime	Claude Code 2.1.220
agent_model	claude-opus-5
runtime_profile	/nix/store/i8y8b542cyqi385ywcjw5fvsq24f75v4-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/i81qxhzlrzcxrrdwpp6i8hagka2gby8y-agent-skills-corpus/share/agent-skills/manifest.json
worktree	dotfiles/schickling/2026-07-20-cos-misc
machine	dev3
tooling_profile	dotfiles@unknown-dirty

[schickling]

@codex

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c21ced9be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[myobie]

Closing per stable-main hygiene disposition: documentation scope is preserved on main history; no merge required.