doctor

name: doctor description: Validate consumer install state — read-only audit of pipeline.config, gh auth, GitHub labels, plugin registration, residual subtree artifacts, and base branch. --fix labels seeds the canonical pipeline labels idempotently; --fix config reconciles new PIPELINE_* knobs into the host pipeline.config (append-only, never overwriting host values). Usage: /pipeline:doctor [--fix labels | --fix config] disable-model-invocation: false allowed-tools: Bash, Read

Boot

At session start, before running any of the steps below, source the project's pipeline.config so the PIPELINE_* variables are available for the rest of this skill:

source "$(pwd)/pipeline.config" 2>/dev/null || source ./pipeline.config
# Self-resolve CLAUDE_PLUGIN_ROOT in case the env var is unset in the Bash subshell.
# Anchor via the plugin cache glob (var-independent — no chicken-and-egg dependence on
# CLAUDE_PLUGIN_ROOT to FIND the resolver). _cpr_dir is the dir prefix; literal source line.
_cpr_dir="${CLAUDE_PLUGIN_ROOT:+${CLAUDE_PLUGIN_ROOT}/}"
_cpr_dir="${_cpr_dir:-$(ls -d ${HOME}/.claude/plugins/cache/claude-pipeline-local/pipeline/*/ 2>/dev/null | sort -V | tail -1)}"
_cpr_dir="${_cpr_dir:-$(ls -d ${HOME}/.claude/plugins/cache/claude-pipeline/pipeline/*/ 2>/dev/null | sort -V | tail -1)}"
source "${_cpr_dir}scripts/_resolve-plugin-root.sh" 2>/dev/null || true

Doctor

gh auth → plugin install → pipeline.config → labels → settings wiring → allow-list → CLAUDE.md residual → base branch

Run the doctor script with the user-supplied flags (forward $@ verbatim so both /pipeline:doctor and /pipeline:doctor --fix labels work):

bash "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh" "$@"

Report the full stdout (CHECK lines + summary table) to the user. If the exit code was non-zero, finish with "One or more checks failed — see the summary above." If zero, finish with "All checks passed."

Checks

State table — each row names a check, the trigger that fires it, the worst-case severity, and the remediation. Complex checks have their own sub-section below with the full state machine.

The shared scripts/_advisory-text.sh helper is the single source of truth for capability-impact annotation copy surfaced by settings_residual — also sourced by migrate-from-subtree.sh so the wording matches.

claude_plugin_root check

Validates CLAUDE_PLUGIN_ROOT resolves to a real plugin install. Captures a pre-resolve env snapshot to distinguish four states:

consumer_drift check

Per-file drift classification on top of skill_files_residual's duplicate presence. Delegates to scripts/diff-consumer-files.sh (stateless, also reused by migrate-from-subtree.sh); assigns one of six buckets:

B-vs-C tie-break. If both heuristics fire, C wins — preserves consumer functionality when uncertain.

Check verdict.

• B.bug row → fail (active bug — stale local overrides correct plugin behavior).
• A / B / C / E row whose basename is in LOAD_BEARING_HOOKS → fail (#295). The array in scripts/doctor.sh (currently enforce-base-branch.py, enforce-path-c-delegation.py, block_deletions.py) names hooks the pipeline depends on for defense-in-depth; stale local copies silently defeat the guardrail. Detail line: <n> load-bearing hook(s) drifted (<csv>) — defense-in-depth at risk.
• Other A / B / C / E row → warn (drift exists but not breaking).
• Only D / F rows (or no rows) → pass.

Textual-diff-only; no behavioral comparison. --fix drift is out of scope.

preservation_refs check

Answers "why is each duplicate still here, and should the consumer delete it?" Per consumer .claude/{scripts,hooks}/ file with a plugin-shipped collision, delegates to scripts/scan-preservation-refs.sh (also used by migrate-from-subtree.sh --keep-referenced); emits one per-file block with references + verdict (KEEP/DELETE) + advisory text.

Reference-source buckets (six total; copy from scripts/_advisory-text.sh::advisory_for_ref_source):

Verdict rule. DELETE when every reference is in {self-only, falls-away} OR no references found. KEEP when at least one reference is in {active-wiring, fork, consumer-skill-ref, doc-ref}.

Status mapping. pass when zero files or every verdict is DELETE; warn when any KEEP. Never fail — the only fail-grade signal in this domain is consumer_drift::B.bug. No --fix preservation-refs mode; doctor stays read-only.

Cache + plugin-skill match. scan-preservation-refs.sh calls diff-consumer-files.sh once at start and caches the per-path bucket. The falls-away vs consumer-skill-ref distinction requires ${CLAUDE_PLUGIN_ROOT}/skills/<n>/ to exist (basename match). When CLAUDE_PLUGIN_ROOT is unresolved, every SKILL.md ref defaults to consumer-skill-ref — conservatively correct, but under-reports safe-to-delete cases.

Mutating actions

--fix labels

/pipeline:doctor --fix labels seeds the 10 canonical pipeline labels on $PIPELINE_REPO via gh label create --force, which is an idempotent upsert — safe to re-run. The four configurable label rows (excluded, later, human, brainstorm) honor PIPELINE_LABELS_* overrides from pipeline.config.

--fix config

/pipeline:doctor --fix config reconciles the host pipeline.config against pipeline.config.example (#1038). It is a KEY-LEVEL MERGE, append-only: every PIPELINE_* key present (uncommented) in pipeline.config.example but ABSENT from the host pipeline.config is appended at the example default value. It NEVER overwrites an existing host value (PIPELINE_REPO and per-operator paths are sacred), preserves host comments/ordering/non-PIPELINE_ lines (it only appends), and skips commented #PIPELINE_* example lines (those are documentation defaults single-sourced at the read site via ${VAR:-default}, not required live keys). Keys with no safe default (empty, owner/repo, /path/..., the PIPELINE_MOCK_WEB_EVAL_* family) are surfaced as "added — needs your value" so you can fill them in rather than silently running empty. It accepts optional vOLD vNEW positional args (--fix config vX vY) so the change report can name the version delta — the doctor-on-update detector passes the diffed plugin versions through this way. The report lists the version delta, a labels line (pointing at the companion --fix labels seed), the envvars added (key=default), and the envvars still needing a value.

Defaults-in-code / config = overrides-only (#1052). The reconcile follows a defaults-in-code model, mirroring Claude Code itself: Claude Code writes nothing to settings.json on install or upgrade — defaults live in the binary and apply whenever a key is absent. The same here: a PIPELINE_* knob with a read-site ${VAR:-default} (or colon-less ${VAR-default}) is COMMENTED in pipeline.config.example — it is a documentation default that the read site owns, NOT a required live key — so the reconcile SKIPS it and the host stays clean. Seeding such a knob at its current default would PIN that value: when a future plugin version flips the default, a host carrying the explicit seeded line silently keeps the OLD value, while a non-overriding host follows the new read-site default. Seeding therefore defeats central default evolution — the exact property the defaults-in-code model preserves. Only no-safe-default required keys (PIPELINE_REPO, per-operator paths, the PIPELINE_MOCK_WEB_EVAL_* family) stay uncommented = seeded. The golden guard tests/test-doctor-golden-seed-set.sh is the forcing function: it pins the seeded key set against the real example, so any newly-added uncommented-defaulted knob turns the test red and forces the author to comment it (or consciously extend the golden list).

--fix residual

Interactive remediation for the three residual checks (claude_md_residual, settings_residual, skill_files_residual); y/N prompt per finding. DOCTOR_FIX_NONINTERACTIVE=1 auto-skips (everything defaults to No) — useful for CI smoke runs.

• settings_residual patching is delegated to migrate-from-subtree.sh --patch settings (in-place jq rewrite with .bak backup; ISO-timestamp collision suffix). Honors --dry-run, --assume-yes, --assume-no.
• claude_md_residual only surfaces the report from migration-cleanup-claudemd.sh; doctor does NOT edit CLAUDE.md directly — it's user-authored prose.
• skill_files_residual lists each duplicate as a y/N prompt; consumer-required .template-rendered paths are excluded from the prompts.
• Consumer-required paths rendered from plugin scripts/*.template / hooks/*.template are never proposed for deletion (load-bearing). The .template-branch becomes obsolete once #215 lands.

--fix stdin-guards

Remediates the stdin_read_timeout_guards check (#917): patches consumer .claude/hooks/ files whose stdin reads lack a timeout guard so a never-closing stdin can no longer wedge the session. y/N prompt per file. Strategy split by file type:

• Plugin-shipped Python duplicate (basename also exists under ${CLAUDE_PLUGIN_ROOT}/hooks/) → re-sync: copies the now-guarded plugin file over the drifted consumer copy. This is the existing drift-remediation idiom and avoids fragile in-place AST surgery.
• Consumer-authored bash hook → in-place $(cat) → $(timeout 5 cat || true) rewrite, with a .bak backup (same .bak convention as --fix residual).
• Consumer-authored Python hook (no plugin counterpart) is surfaced for manual review only — doctor does not attempt an in-place AST edit.

Unlike --fix residual (which auto-skips under DOCTOR_FIX_NONINTERACTIVE=1), --fix stdin-guards honors DOCTOR_FIX_NONINTERACTIVE=1 as auto-yes (applies the patch) so CI/tests can exercise the remediation path without a TTY.