docs(vrs): add thin Doctor contract

docs/vrs/02-doctor/requirements.md

@@ -0,0 +1,30 @@
+# Doctor requirements
+
+Doctor checks one catalog from one host. It follows the root
+[vision](../vision.md). It refines [R03](../requirements.md#L46-L47),
+[R04](../requirements.md#L51-L54), and [R08](../requirements.md#L92-L95).
+It does not define fleet health.
+
+## Requirements
+
+- **DOCTOR-R01 Diagnostic subject:** One run checks one selected catalog and one
+  selected host. The result does not claim that a remote host is available.
+- **DOCTOR-R02 Gate result:** A healthy result returns zero. Any diagnosed
+  problem returns non-zero. Each problem names the affected declaration, task,
+  runtime, catalog, or supervision subject.
+- **DOCTOR-R03 Read-only diagnosis:** A run must not change catalog, presence,
+  or runtime state. It must not reconcile, launch, stop, reap, repair, or
+  materialize work.
+- **DOCTOR-R04 Bounded non-interactive operation:** Doctor and its external
+  probes must not read the caller's standard input. A probe must stop within a
+  fixed time. A timed-out probe is a failed check, not a hung caller.
+- **DOCTOR-R05 Active local health:** Doctor checks each active declaration on
+  the selected host. It checks that declared work is alive and that presence is
+  maintained. It does not check remote availability.
+- **DOCTOR-R06 Retired absence:** A retired declaration is healthy only when all
+  declared task records are absent. A live or dead record is unhealthy. A
+  retired declaration does not require presence or active-declaration checks.
+
+The [Retirement health invariant](../../../INVARIANTS.md#L20) and its tests prove
+the retirement rule. The [specification](spec.md) owns the mechanism, check
+groups, and known gaps.

docs/vrs/02-doctor/spec.md

@@ -0,0 +1,60 @@
+# Doctor specification
+
+This document maps the [Doctor requirements](requirements.md) to the current
+CLI, implementation, and tests. It does not define check order, private
+filenames, exact report text, or fallback behavior.
+
+## Scope and inputs
+
+The [`doctor` CLI](../../../src/main.rs#L240-L252) selects a catalog and a host.
+Shared catalog rules resolve the catalog. The caller can select a host, or st2
+can detect the local host. The `--require-supervisor` flag requires a resident
+`st2 up` process. Without this flag, manual and one-shot operation are valid.
+The report names the resolved catalog and host.
+
+## Checks
+
+[`doctor_cmd`](../../../src/main.rs#L988-L1130) is the implementation authority.
+It performs these check groups:
+
+- **Environment:** The required runtime tools are available
+  ([source](../../../src/main.rs#L997-L1003)).
+- **Supervision:** The host mode matches the caller's request
+  ([source](../../../src/main.rs#L1005-L1028); [tests](../../../tests/doctor.rs#L40-L92)).
+- **Catalog:** The selected catalog has no discovery errors
+  ([source](../../../src/main.rs#L1030-L1040)).
+- **Runtime:** Runtime state is readable, and each active local task is alive
+  ([Doctor source](../../../src/main.rs#L1041-L1102); [unified runtime view](../../../src/run.rs#L687-L700)).
+  The PTY probe has a fixed deadline and closed standard input
+  ([probe source](../../../src/run.rs#L443-L458); [tests](../../../tests/doctor.rs#L95-L194)).
+- **Presence:** Each active local declaration has maintained presence
+  ([source](../../../src/main.rs#L1103-L1121)).
+- **Retirement:** Every task record for a retired local declaration is absent
+  ([source](../../../src/main.rs#L1068-L1089); [tests](../../../tests/doctor.rs#L196-L302)).
+
+## Output contract
+
+Doctor writes a human-readable report for the resolved catalog and host. Each
+failure has a subject label and available detail. Doctor returns zero only when
+it diagnoses no problem. The formatter and result are in
+[`report_check`](../../../src/main.rs#L1165-L1175) and
+[`doctor_cmd`](../../../src/main.rs#L1124-L1129). The
+[clean-path test](../../../tests/native_only.rs#L243-L369) proves that the CLI
+does not need a predecessor transport.
+
+## Open questions
+
+These are implementation gaps or unsettled product choices, not requirements:
+
+- **Malformed presence:** Unreadable or invalid fresh presence becomes
+  `offline`. Should Doctor report corruption separately?
+  ([source](../../../src/status.rs#L70-L95))
+- **Exec enumeration bound:** Exec record enumeration is synchronous file-system
+  work. It is outside the PTY deadline. What deadline should cover the full
+  diagnosis? ([source](../../../src/exec_backend.rs#L190-L217))
+- **Tool dependency:** Doctor requires `pty` when a host has only exec tasks.
+  Should the declared tasks select the required tools?
+  ([source](../../../src/main.rs#L997-L1003))
+- **Machine output:** Doctor has no stable machine-readable report. Should it
+  provide structured findings in addition to the exit status?
+  ([CLI surface](../../../src/main.rs#L240-L252))