doctor runs everything or nothing: no --only, no --category, and a partial run would have no way to admit it was partial

[MongLong0214]

doctor runs all of its checks or none of them. There is no --only for the check a user is debugging, no --category for the subsystem a CI job cares about — and, more dangerous once they exist, no way for a partial report to admit it is partial. ADR-0032 rejected profiles precisely because "a profile that omits checks reproduces the #458 shape — the screen that lied by not looking"; explicit filters are the replacement, and they are only safe if a filtered report can never pass for the repository's health.

Why this exists

• PRD §2.5 (filters over registry data), §5.5 (selection and partial honesty), §8.5 ("No partial run presented as full"), §7 (the 2 exit for a bad selection).
• index --rebuild reports unqualified success on a mirror it could not read, and cli.md says it always can #400 / init reports ready on an unfetched mirror without saying so — the first screen a user meets #402 are the category this guards: an unqualified answer over a subset is the first-screen lie, one flag away.

Scope

• register (src/commands/doctor.ts shim → command action): --only <ids> (comma-separated registry ids) and --category <name>; both filter the registry before the run (PRD §2.5) — unselected checks are not executed, not merely hidden.
• An unknown id or category is a usage error: exit 2, nothing runs, no report on stdout (PRD §2.5; SPEC §10: 2 means could not run, and commander's existing usage-error path already owns it).
• The envelope gains selection: string[] — present iff the run was filtered, carrying the values the user passed (PRD §5's example: --category capture → ["capture"]); omitted on a full run, never null or [].
• status and headline derive from the selected checks only, and the headline is prefixed N of M checks run where M is the full registry size (PRD §5.5).
• --help documents exit codes 0, 1, 2 (PRD §7.3; SPEC §10 requires every command to document its codes). The current help line names only 0 and 1.

Acceptance criteria

• doctor --only cli-runtime --json: one check row, selection present, headline prefixed 1 of 13 checks run (PRD §11 "partial honesty").
• doctor --category capture --json: exactly commit-msg-hook, hook-runtime, pending-backlog; selection: ["capture"].
• Unknown --only id and unknown --category each: exit 2, a usage error on stderr, no JSON on stdout, zero checks executed (PRD §11 "exit codes", last column).
• Full run: no selection key in the JSON.
• A fixture where an unselected check would fail: a filtered run over a healthy category reports status for the selection only and exits 0 — and its headline carries the N of M prefix, so it cannot read as the repository's health.
• --help names 0, 1, and 2.
• Unselected checks demonstrably do not run (asserted via the injected context — no spawn from an unselected check).

Tests that must exist

case	what it catches
a partial run always carries selection and the N of M prefix	PRD §8.5 violated — a filtered report publishable as full health, the #458 shape rebuilt behind a flag. This is the fails-if-wrong case
unknown --only id exits 2 and runs nothing	two SPEC §10 violations at once: 2 acquiring a finding-like meaning, and a doctor that runs twelve checks and then errors — the partial work a usage error must not leave behind
full run omits selection	selection: [] or selection: null on the default path — the omitted-never-null contract
a failing unselected check does not affect a filtered run's status or exit	derivation leaking beyond the selection — §5.5's "its status speaks only for the selected checks" read backwards would hide the prefix instead
--category capture selects exactly the three capture checks	the filter drifting from the registry's category data — hand-maintained lists are the thing the registry replaced

Open questions the PRD leaves — flagged, not decided here

1. A selection that splits a declared dependency. --only commit-msg-hook excludes hook-runtime, which the check's behaviour (its outcome: detail) and blockedBy both consume. Auto-include the dependency? Run it unreported? Let the dependent report without it (which its current contract cannot)? PRD §2.5/§5.5 are silent. Needs a PRD amendment before this ticket merges; the acceptance tests above deliberately use dependency-free selections.
2. Combining --only with --category (reject, intersect, union) is unspecified. Flag in the PR; rejecting the combination is the smallest surface until the PRD says otherwise.

Depends on

• doctor --json is an unversioned struct dump: no schema, no version, and the state between healthy and broken has no name #469 (the selection field and headline live in the envelope), doctor's text report has no first line that matters: a user reads thirteen rows to find the one thing to fix #470 (the text prefix renders through the new header), runDoctor is a hand-written array of ad-hoc functions: one throwing check kills the whole command, and nothing is timed #463 (the registry the filters select over).

Out of scope

• --profile / per-surface check sets (PRD non-goal, with a named reopening condition), persisting a selection, any new category.

Traceability: PRD §2.5, §5.5, §7, §8.5, §11; ADR-0032 §8.4 and the profiles rejection; SPEC §10.

[MongLong0214]

Partially resolved by the amendment merged in #460.

selection is now specified in the report envelope ("selection": ["capture"], omitted on a full run), and the partial-honesty rule is tied to it.

Still unspecified, and worth deciding in this ticket rather than assuming: what --only commit-msg-hook does when hook-runtime is excluded by the same filter. Registry order is now frozen and dependencies are declared, so the two defensible answers are visible — pull the dependency in silently, or run the dependent and let it report a blocked skip. The second is more consistent with §3's annotate-never-suppress rule, but the PRD does not say so.

Combining --only with --category is likewise open.