#479 feat(doctor): critical "Hook command" check catches dangling hook entries

[Anonymous]

Originally created by: fu351

Why

Follow-up to [#477] (ADR 0086). Hook entries are the bare doberman hook …, so when the package is removed — or its bin dir is not on the host's PATH — Claude Code / Codex fail the hook and carry on unmediated. Nothing surfaced that state; doberman doctor reported "Host hooks: installed" and looked green.

What

• New Hook command check in doberman doctor (src/doberman/cli/doctor.py), listed right after Host hooks:
• [ ok ] — doberman resolves on PATH; the detail prints the resolved path (a second, stale install earlier on PATH becomes visible here).
• [FAIL] (critical, exit 1) — hooks are installed in any writable Claude/Codex scope but doberman does not resolve. The detail names both fixes: put the install's bin dir on PATH (or pipx install doberman-core), or strip the dangling entries with doberman uninstall-hooks (--global for user-wide ones).
• [warn] (non-critical) — nothing installed and no doberman on PATH.
• Resolution uses this process's PATH, which can differ from the host's; the detail says so.
• Diagnosis only. doctor keeps its read-only contract — it never edits settings. Stripping stays with the existing, gated uninstall-hooks / uninstall commands.
• Docs: docs/CLI.md (critical-check list for --json), docs/RECOVERY.md + README pip-uninstall notes, CHANGELOG Unreleased.

Tests

tests/unit/test_cli_doctor.py: resolvable → OK with the path; installed + unresolvable → critical FAIL, exit 1, message names uninstall-hooks; unresolvable without hooks → WARN, non-critical; --json lists Hook command under critical_failures. An autouse fixture pins shutil.which("doberman") so the healthy fixture never depends on the test runner's PATH. Read-only invariant test unchanged and still passing.

Not covered here: the case where the package is already gone — doctor cannot run without a binary; the docs keep saying "reinstall first".

🤖 Generated with Claude Code

https://claude.ai/code/session_01T7XD6aDzEdRfMz7H2XJ8L3

[Anonymous]

Ticket changed by: fu351

• status: open --> closed