doctor

/claire:doctor — is Claire healthy and unconflicted on this machine?

Two layers: the filesystem checks (a script) and one live test that only a running dispatch can do. Run both, then give the user a plain verdict.

Step 0 — Version line

Run adv-status.sh (at the plugin root — the parent of the skills/ directory this skill lives in) and print its one-line output at the top (e.g. claire v0.4.0 · up to date). If it reports commits behind origin, note how to update: a clone install updates with git pull; a marketplace install updates by refreshing the marketplace in the plugins panel (or /plugin marketplace update on the terminal).

Step 1 — Filesystem checks

Run the bundled doctor.sh from the user's current workspace (so its collision scan sees that workspace's local agents) and show its output verbatim:

bash "<plugin-root>/doctor.sh"

It checks: python3 present; plugin.json present and no stray marketplace.json beside it; components intact; version / behind-origin; duplicate installs (the same Claire installed in more than one place under ~/.claude — e.g. a clone and a marketplace copy — which double-loads her hooks and agents); name collisions (local agents in this workspace or your user config that share Claire's agent names); and leftover superseded tools. WARN lines are informational; FAIL lines need fixing.

Step 2 — Live self-test (does enforcement actually fire here?)

This is the check the script cannot do. It verifies that the de-priming receipt mechanism works on this machine. Since the gate now BLOCKS by default (>=0.12.0), this is no longer "is it safe to turn strict on" — strict is already on. The question is whether enforcement fires end to end, because if receipts are NOT being written or delivered here, block-by-default DENIES every audited dispatch — so a broken machine needs the escape hatch (CLAIRE_GATE_STRICT=0), not a flag turned on.

1. Note the current moment, and list any existing receipts: ls -t "<plugin-root>/hooks/.receipts/" 2>/dev/null.

2. Pick any short receipt id (e.g. doctor1). Dispatch claire:brief-leak-auditor (namespaced) with [CLAIRE-RECEIPT:doctor1] on its own line, then this fixed, obviously neutral brief — 0.8.0 keys the written receipt by that id, and the auditor ignores the id line as ambient:

   A team is choosing between two suppliers for a one-year support contract. Supplier A is a large, long-established firm with a higher fixed monthly fee and a record of many prior contracts. Supplier B is a smaller firm founded three years ago with a lower fee and fewer prior contracts. Both meet the technical requirements and both have confirmed they can start on the required date. The team must commit to one for the year. What is the outside view on how the team should choose between Supplier A and Supplier B, and what would you most want to know before recommending one?

   It should return a clean read whose final line is the machine verdict CLAIRE-VERDICT: NEUTRAL (that fixed line, not the prose, is what writes the receipt). The brief is deliberately textured — two options described on matched dimensions (size, fee, track record) with no loaded wording — NOT a one-line "both options are equal" abstraction. A too-thin brief makes the auditor (correctly) refuse to audit it ("there's no brief here — no texture for a lean to live in"), so it returns no verdict and no receipt: a false negative that looks like broken enforcement. The lean hides in the texture, so the self-test brief must HAVE texture.

3. After it returns, check for doctor1.json specifically — 0.8.0 keys each receipt by its id, not by content: ls -t "<plugin-root>/hooks/.receipts/". A fresh doctor1.json (newer than step 1) means the PostToolUse receipt hook fired and recorded the clean audit. (Pre-0.8.0 wrote a content-hashed filename; from 0.8.0 the file is named for the id you tagged, so look for that id — not just "any new file".)

Step 2.5 — If no receipt appeared, OFFER to turn enforcement on

On the Claude Desktop app, a plugin's PostToolUse hook (the receipt writer) does NOT fire — only its PreToolUse hook (the warn-gate) does. So out of the box, no receipt is written and the gate can only ever warn. The fix is a one-time registration of the receipt writer in ~/.claude/settings.json (where PostToolUse hooks DO fire), which the bundled setup-receipts.sh does safely and idempotently.

So if Step 2 produced no fresh receipt — whether Step 1's "Receipt enforcement" check said not registered OR registered but pointing at a path that no longer exists (a stale registration after switching install methods) — offer to turn it on for the user; do not make them open a terminal. (setup-receipts.sh registers if missing, re-points if stale, and is a no-op if already correct — so it is always safe to run.) Ask plainly, e.g. "Claire's stronger enforcement (the gate going silent only on a real audit) isn't switched on here yet. Want me to enable it? It adds one line to your Claude settings file that runs the receipt writer; it's reversible and can't hang anything." On yes:

1. Run bash "<plugin-root>/setup-receipts.sh" and show its one-line result.
2. Re-run the Step 2 live self-test (dispatch the auditor again, check for a fresh receipt). It now fires mid-session — no restart needed.
3. Report that enforcement is now live.

On no, leave it warn-only and say so — Claire still works, the gate just always reminds rather than going silent.

Step 2b — Inject round-trip (does an approved brief actually REACH the critic?)

Run this whenever Step 2 (or Step 2.5) produced a fresh doctor1 receipt. Step 2 proves the receipt is WRITTEN; it does NOT prove the gate reads it back and INJECTS the audited brief into the critic — and those fail separately. A receipt can be written while the inject silently delivers nothing (seen 2026-06-21: after plugin versions were removed mid-session, the write worked but the gate returned NORECEIPT on the critic dispatch and the critic got an empty brief — the write-only check could not see it). So close the loop:

1. With the doctor1 receipt still fresh (2-hour TTL), dispatch claire:blank-slate-advisor (namespaced) carrying the SAME id and nothing of substance — the gate overwrites the prompt with the stored brief:

   [CLAIRE-RECEIPT:doctor1]

   Outside read requested; the audited brief will be injected by the gate.

2. Confirm the inject actually fired, two independent ways:

   • Gate log: grep "PASS .*doctor1" "<plugin-root>/hooks/gate-fire.log" returns a line. The gate writes PASS agent=... nonce=doctor1 ONLY when it found the receipt and injected the stored brief; a failed read writes NORECEIPT. (This line is written regardless of the debug switch.)
   • The critic's answer: it returns a real outside read of the supplier decision (the injected brief). If it instead says the brief is empty or missing, the inject did NOT deliver — exactly the failure this step exists to catch.

3. Record the result for the verdict:

   • PASS line AND a real read → enforcement is live END TO END (written AND delivered).
   • Receipt written in Step 2 but NORECEIPT / empty brief here → the inject half is broken on this machine. The usual cause is plugin versions removed or changed while the app was running, leaving the live hooks on a stale path. Tell the user to restart the app and re-run /claire:doctor. Because the gate blocks by default, a broken inject means audited dispatches are DENIED meanwhile — so tell them to export CLAIRE_GATE_STRICT=0 as a stopgap if they need Claire usable before the restart clears it.

Step 3 — Verdict

Tell the user, in plain language:

• If a fresh receipt appeared AND the Step 2b round-trip passed (a PASS line plus a real read) → de-priming enforcement is live END TO END on this machine — written and delivered to the critic — and block-by-default is working correctly: a skipped audit hard-stops, a clean one sails through. Nothing to change. Say so.
• If the receipt was written but the Step 2b round-trip did NOT inject (NORECEIPT / empty brief) → enforcement is half-working: receipts are recorded but not delivered. Under block-by- default this means audited critic dispatches are being DENIED — Claire is partly locked out. Tell the user to restart the app and re-run; as a stopgap to keep Claire usable meanwhile, export CLAIRE_GATE_STRICT=0 (softens to advisory) until the round-trip passes.
• If no receipt appeared (writer not registered, or the user declined to wire it) → this is now the DANGER case, not a soft default. With block-by-default and no receipts ever written, the gate DENIES every audited critic dispatch — Claire cannot run a single critic. Tell the user plainly: either wire the writer in (setup-receipts.sh, which /claire:doctor offers) so enforcement works, or export CLAIRE_GATE_STRICT=0 to soften the gate to warn-only so Claire is usable. One of the two is required — doing neither leaves Claire locked out.
• If no receipt appeared even though it IS registered → something deeper is off (e.g. the receipt writer can't read the verdict on this harness). Under block-by-default this also locks Claire out, so flag it as the one thing to look into AND give them the CLAIRE_GATE_STRICT=0 stopgap so they are not stuck while they investigate.
• Roll up the filesystem FAILs/WARNs from Step 1 into one or two plain sentences (e.g. "you have Claire installed twice — keep one", or "your project has its own agents sharing Claire's names; that's fine, just informational").

Keep the whole thing short: a status line, the script output, the self-test result, and a two-or-three-line verdict. Don't pad it.