any-doctor 0.1.0 → 0.1.2

package/README.md

@@ -32,7 +32,7 @@ each with impact, why, fix, and the honest blind spots. `enter` copies a
 fix prompt for your agent.
 
 ```bash
-npx any-doctor@latest run slop-doctor   # one doctor, straight to the report
+npx any-doctor@latest run slop   # one doctor, straight to the report
 ```
 
 Non-terminals and CI never see a prompt — output is stable and pipeable
@@ -42,11 +42,11 @@ Non-terminals and CI never see a prompt — output is stable and pipeable
 
 | Doctor | Discipline | Checks |
 |---|---|---:|
-| **slop-doctor** | The recurring failures of LLM-written code: identical helpers copied across modules, dead exports, unread bindings, hostname-sniffed environments, careless substring matching, collapsed boolean states | 8 |
-| **convex-doctor** | Convex discipline: indexed reads, bounded collects, validated args, awaited writes, honest runtime boundaries | 15 |
-| **effect-v4-doctor** | Effect v4 discipline — the mechanical rules of the [kitlangton Effect skill](https://www.ui-skills.com/skills/kitlangton/effect), enforced | 10 |
-| **openrouter-doctor** | OpenRouter discipline: stream errors surfaced, keep-alives skipped, cancellations that stop billing | 5 |
-| **async-doctor** | Async and concurrency: dropped promise results, uncleared timers, fetch hygiene | 3 |
+| **slop** | The recurring failures of LLM-written code: identical helpers copied across modules, dead exports, unread bindings, hostname-sniffed environments, careless substring matching, collapsed boolean states | 8 |
+| **convex** | Convex discipline: indexed reads, bounded collects, validated args, awaited writes, honest runtime boundaries | 15 |
+| **effect-v4-kitlangton** | Effect v4 discipline — the mechanical rules of the [kitlangton Effect skill](https://www.ui-skills.com/skills/kitlangton/effect), enforced | 10 |
+| **openrouter** | OpenRouter discipline: stream errors surfaced, keep-alives skipped, cancellations that stop billing | 5 |
+| **async** | Async and concurrency: dropped promise results, uncleared timers, fetch hygiene | 3 |
 
 Checks ship positive and innocent-lookalike fixtures. `verify` compares an
 exact multiset of rule/file/line and optional column, then runs shared innocent

package/bin/analysis-host.js

@@ -9,7 +9,7 @@ const modelCache = new Map();
 const callsCache = new Map();
 const spansCache = new Map();
 // Test seam: the model cache is keyed by mtime+size for the process
-// lifetime; tests bust it between cases. Invisible to slop-doctor's
+// lifetime; tests bust it between cases. Invisible to slop's
 // default run (test-file consumers are the documented narrowing).
 export function clearAnalysisCache() {
     modelCache.clear();

package/bin/certify.js

@@ -161,7 +161,7 @@ export async function certify(mod, fixtures) {
             }
             // Verify always lists everything (includeTestsFor): the sandbox is
             // the doctor's own world — a seed named *.test.ts is deliberate
-            // test data (effect-v4-doctor's sleep-in-test depends on it).
+            // test data (effect-v4-kitlangton's sleep-in-test depends on it).
             const result = await inSandbox(fixture.seed, (tmp) => runOnce(tmp, mod, { includeTests: true }));
             const diff = contract.compareFindings(fixture.expected, result.findings);
             const row = { name: fixture.name, ok: diff.missing.length === 0 && diff.unexpected.length === 0, ...diff };

package/bin/cli.js

@@ -16,7 +16,7 @@ import { deriveSummary } from "./summary.js";
 import { copyToClipboard } from "./clipboard.js";
 import { runDashboard } from "./dashboard.js";
 import { brokenDoctors, discoverDoctors, globalDoctorsDir, resolveDoctorPath, unsafeSlugs, scopeLabel } from "./discover.js";
-import { causeSummaryLine, describeRunnerError, isRunnerError, verifyDoctor } from "./runner.js";
+import { causeSummaryLine, describeRunnerError, isRunnerError, metaDoctor, verifyDoctor } from "./runner.js";
 import { scanDoctorFile, capabilitySummary } from "./capabilities.js";
 import { selectDoctor } from "./select.js";
 import { pickItemsOn } from "./picker.js";
@@ -151,8 +151,10 @@ async function runOrReport(work) {
     }
 }
 function warnBrokenDoctors(skipped) {
+    // stderr, always: a console.log here put the warning INSIDE --format
+    // json stdout, corrupting the machine surface (agent-review probe).
     for (const b of skipped) {
-        console.log(YELLOW + "\u26a0 skipping broken doctor " + b.slug + RESET + dim(" — " + causeSummaryLine(b.cause)));
+        warn("\u26a0 skipping broken doctor " + b.slug + dim(" — " + causeSummaryLine(b.cause)));
     }
 }
 function selectionOutcome(sel) {
@@ -306,14 +308,19 @@ function wantsTui(parsed) {
 // partial), the gate's bar judges findings, skips fail quietly. Each
 // surface calls this where its timing wants the lines printed.
 function exitAfterSurface(outcome, gate) {
-    var _a;
+    var _a, _b, _c, _d;
     if (outcome.crashed.length > 0) {
         for (const c of outcome.crashed)
             fail(`doctor crashed (results above are partial): ${c.id}`);
         return 1;
     }
+    if (((_b = (_a = outcome.broken) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0) {
+        for (const b of (_c = outcome.broken) !== null && _c !== void 0 ? _c : [])
+            fail(`broken doctor (not scanned): ${b.id}`);
+        return 1;
+    }
     if (gate.fails) {
-        fail((_a = gate.reason) !== null && _a !== void 0 ? _a : "gate failed");
+        fail((_d = gate.reason) !== null && _d !== void 0 ? _d : "gate failed");
         return 1;
     }
     return outcome.skippedUnsafe.length > 0 ? 1 : 0;
@@ -348,6 +355,7 @@ async function cmdRun(args) {
     // Cohort, which owns everything from first spawn to last settle.
     let doctors;
     let skippedUnsafe;
+    let broken = [];
     // The live line is mode-based, not count-based: an explicit path is a
     // scan of one (label + elapsed, no counts, no settle notes); picker
     // and --all are cohort runs (counts + per-settle notes) even when the
@@ -367,14 +375,27 @@ async function cmdRun(args) {
         // report use.
         doctors = [{ id: path.basename(selection.doctorPath, ".mjs"), programPath: selection.doctorPath }];
         skippedUnsafe = [];
+        broken = sel.kind === "doctor" ? sel.skipped : [];
     }
     else {
         const cohort = await gatherDoctors();
         warnBrokenDoctors(cohort.broken);
-        if (cohortUnusable(cohort))
+        if (cohortUnusable(cohort)) {
+            // Structured failure even here: the JSON surface still gets its
+            // object with the broken array (agent-review probe: stdout was
+            // empty when every doctor was broken).
+            if (parsed.format === "json") {
+                const failed = {
+                    groups: [], crashed: [], broken: cohort.broken.map(b => ({ id: b.slug, detail: causeSummaryLine(b.cause) })),
+                    skippedUnsafe: cohort.skippedUnsafe, doctorPaths: new Map(), fileCount: 0, durationMs: 0, targetDir: parsed.targetDir,
+                };
+                console.log(renderJson(failed, deriveSummary(failed), gateVerdict(parsed.failOn, { error: 0, warning: 0, info: 0 }, "full")));
+            }
             return 1;
+        }
         let valid = cohort.valid;
         skippedUnsafe = cohort.skippedUnsafe;
+        broken = cohort.broken;
         // The cold start is opt-in: the selector opens with nothing
         // pre-selected, space selects, a selects every filtered row, and
         // Enter runs the selection — narrowing to one doctor is one space,
@@ -399,7 +420,7 @@ async function cmdRun(args) {
     // rejects the batch must not leave a hidden cursor behind. Settle
     // notes name doctors by the spec's ids — one naming rule, shared with
     // the crash report.
-    const spec = { doctors, targetDir: parsed.targetDir, includeTests: parsed.includeTests, skippedUnsafe };
+    const spec = { doctors, targetDir: parsed.targetDir, includeTests: parsed.includeTests, skippedUnsafe, broken };
     const idOf = new Map(doctors.map(d => [d.programPath, d.id]));
     // JSON mode paints nothing on stdout — not even the live line. The
     // picker and dashboard get the same refusal from wantsTui; the
@@ -429,6 +450,13 @@ async function cmdRun(args) {
     finally {
         spin === null || spin === void 0 ? void 0 : spin.stop();
     }
+    // Broken doctors fail ALWAYS, like crashes: a doctor whose program
+    // cannot even be read is an infrastructure failure, and a local broken
+    // file shadowing a bundled doctor must never read as that doctor
+    // scanning clean (the agent-review probe: exit 0, score 100).
+    for (const b of broken) {
+        warn("\u26a0 broken doctor " + b.slug + " — " + causeSummaryLine(b.cause));
+    }
     // Crash detail prints before any surface: "details above" in the
     // report's every-crashed line stays true, and the dashboard's own
     // rendering (findings and skips, not crashes) stays clean.
@@ -510,12 +538,16 @@ async function cmdRun(args) {
     // renders findings and skips, not crashes — and the dashboard ignores
     // diff mode: it is the review experience, not the gate.
     const code = exitAfterSurface(outcome, gate);
+    const stateExistedBeforeDashboard = fs.existsSync(decisionsPath(parsed.targetDir));
     await runDashboard({
         outcome,
         invoker,
         useColor: useColor(),
         ...(review !== undefined ? { view: review } : {}),
     });
+    if (!stateExistedBeforeDashboard && fs.existsSync(decisionsPath(parsed.targetDir))) {
+        console.log(dim("tip: add the agent workflow to this repo's AGENTS.md so your agents use decisions — 'any-doctor help agents' prints ready-to-paste markdown"));
+    }
     return code;
 }
 async function cmdVerify(args) {
@@ -724,7 +756,7 @@ function parseDecideArgs(args) {
     return out;
 }
 async function cmdDecide(args) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     const parsed = parseDecideArgs(args);
     if ("error" in parsed) {
         fail("any-doctor decide: " + parsed.error);
@@ -762,7 +794,15 @@ async function cmdDecide(args) {
             : doctorId !== undefined ? resolveDoctorPath(doctorId, process.cwd()) : null;
         if (slug !== null) {
             const bytes = digestTextFile(slug);
-            scanProvenanceAtDecide = { programDigest: doctorDigests([{ id: doctorId !== null && doctorId !== void 0 ? doctorId : "x", programPath: slug }], () => bytes)[0].digest };
+            // Prefer the check's declared semantic revision (the churn escape):
+            // a --key decision must survive cosmetic doctor edits exactly like
+            // a scan-resolved one — digest-only recording churned (smoke catch).
+            const metaRead = await metaDoctor({ programPath: slug });
+            const checkId = (_b = key.split("\u0000")[0]) === null || _b === void 0 ? void 0 : _b.split("/")[1];
+            const declared = (_e = (_d = (_c = metaRead.meta) === null || _c === void 0 ? void 0 : _c.checks) === null || _d === void 0 ? void 0 : _d.find(ch => ch.id === checkId)) === null || _e === void 0 ? void 0 : _e.revision;
+            scanProvenanceAtDecide = declared !== undefined
+                ? { revision: declared }
+                : { programDigest: doctorDigests([{ id: doctorId !== null && doctorId !== void 0 ? doctorId : "x", programPath: slug }], () => bytes)[0].digest };
         }
     }
     let checkKey = "";
@@ -803,7 +843,7 @@ async function cmdDecide(args) {
             return 1;
         }
         const groups = deriveSummary(ran).groups;
-        const capture = captureScan(parsed.targetDir, groups, (_b = ran.analysisAvailable) !== null && _b !== void 0 ? _b : false, []);
+        const capture = captureScan(parsed.targetDir, groups, (_f = ran.analysisAvailable) !== null && _f !== void 0 ? _f : false, []);
         const scanProv = scanProvenanceOf(spec, deriveSummary(ran).groups);
         const view = reviewOf(capture, [], encodeDecisionKey, scanProv);
         const candidates = capture.entries
@@ -838,8 +878,8 @@ async function cmdDecide(args) {
     const recorded = recordDecision(parsed.targetDir, {
         key: key,
         checkKey: checkKey !== "" ? checkKey : keyCheck,
-        file: (_d = (_c = parsed.file) !== null && _c !== void 0 ? _c : keyFile) !== null && _d !== void 0 ? _d : "",
-        line: (_e = parsed.line) !== null && _e !== void 0 ? _e : 0,
+        file: (_h = (_g = parsed.file) !== null && _g !== void 0 ? _g : keyFile) !== null && _h !== void 0 ? _h : "",
+        line: (_j = parsed.line) !== null && _j !== void 0 ? _j : 0,
         disposition: parsed.disposition,
         reason: parsed.reason,
         actor: parsed.actor,

package/bin/cohort.d.ts

@@ -9,6 +9,7 @@ export interface CohortSpec {
     targetDir: string;
     includeTests: boolean;
     skippedUnsafe?: readonly string[];
+    broken?: readonly import("./discover.js").BrokenDoctor[];
 }
 export type DoctorExecutor = typeof runDoctorCohort;
 export declare function runCohort(spec: CohortSpec, onProgress?: (p: CohortProgress) => void, exec?: DoctorExecutor): Promise<RunOutcome>;

package/bin/cohort.js

@@ -2,7 +2,7 @@ import * as path from "path";
 import { cohortFileCount } from "./contract.js";
 import { describeRunnerError, runDoctorCohort } from "./runner.js";
 export async function runCohort(spec, onProgress, exec = runDoctorCohort) {
-    var _a;
+    var _a, _b;
     const runStarted = Date.now();
     // The executor preserves options order; the fold pairs runs with
     // their doctor by index.
@@ -31,6 +31,10 @@ export async function runCohort(spec, onProgress, exec = runDoctorCohort) {
     return {
         groups,
         crashed,
+        broken: ((_b = spec.broken) !== null && _b !== void 0 ? _b : []).map(b => ({
+            id: b.slug,
+            detail: b.cause !== undefined ? describeRunnerError(b.cause) : `broken doctor ${b.slug}`,
+        })),
         skippedUnsafe: spec.skippedUnsafe ? [...spec.skippedUnsafe] : [],
         doctorPaths,
         fileCount: cohortFileCount(fileCounts),

package/bin/contract.d.ts

@@ -50,6 +50,7 @@ export interface CrashedDoctor {
 export interface RunOutcome {
     groups: ReportGroup[];
     crashed: CrashedDoctor[];
+    broken?: CrashedDoctor[];
     skippedUnsafe: string[];
     doctorPaths: ReadonlyMap<string, string>;
     fileCount: number;

package/bin/engine.js

@@ -90,7 +90,7 @@ export function resolveAstGrepBinary() {
     return cachedBinary;
 }
 // One batched query over a real repo emits tens of megabytes of JSON (the
-// async-doctor pilot's ten patterns produce 24MB over a 979-file repo) —
+// async pilot's ten patterns produce 24MB over a 979-file repo) —
 // spawnSync's 1MB default truncates that mid-array, and the crash reads as
 // an ast-grep bug instead of a buffer bug. The ceiling exists so a runaway
 // pattern (matching near-every node of a monorepo) fails loudly here

package/bin/mask.js

@@ -5,7 +5,7 @@
 //
 // Regex literals must be masked because they may contain quote
 // characters: an unmasked /["']/ opens a phantom string that swallows
-// every line after it (found by slop-doctor flagging imports whose
+// every line after it (found by slop flagging imports whose
 // type-position uses had been masked out of existence).
 //
 // Two host-side consumers share it: ctx.files.readMasked (the sdk — what

package/bin/report.js

@@ -164,14 +164,19 @@ export function renderReport(input, useColor, diff, review) {
     return lines.join("\n").replace(/\n+$/, "");
 }
 export function renderJson(input, summary, gate, diff, review) {
-    var _a;
+    var _a, _b;
     return JSON.stringify({
         schema: 1,
         tool: "any-doctor",
         target: input.targetDir,
         fileCount: input.fileCount,
         durationMs: input.durationMs,
-        score: summary.score,
+        // An invalidated grade is withheld in JSON exactly as in prose: a
+        // partial (crashed/broken) or empty scan emits null score/grade —
+        // never a vacuous 100/Excellent the flag then contradicts.
+        score: summary.score.partialScan === true || summary.score.emptyScan === true
+            ? { ...summary.score, score: null, grade: null }
+            : summary.score,
         counts: { ...summary.severityCounts, total: summary.total, hiddenDuplicates: summary.hidden },
         analysisAvailable: (_a = input.analysisAvailable) !== null && _a !== void 0 ? _a : false,
         emptyScan: summary.emptyScan,
@@ -181,6 +186,9 @@ export function renderJson(input, summary, gate, diff, review) {
                 ...(b.ruleId !== null ? { rule: b.ruleId } : {}),
                 heading: b.heading,
                 severity: b.severity,
+                ...(b.impact !== undefined ? { impact: b.impact } : {}),
+                ...(b.why !== undefined ? { why: b.why } : {}),
+                ...(b.fix !== undefined ? { fix: b.fix } : {}),
                 findings: b.findings.map(f => {
                     var _a;
                     const readKey = readKeyFor(`${gc.group.meta.id}/${(_a = b.ruleId) !== null && _a !== void 0 ? _a : gc.group.meta.id}`, f.file, f.line, f.column);
@@ -199,6 +207,9 @@ export function renderJson(input, summary, gate, diff, review) {
             ...(gc.group.meta.blindSpots !== undefined && gc.group.meta.blindSpots.length > 0 ? { blindSpots: gc.group.meta.blindSpots } : {}),
         })),
         crashed: input.crashed.map(cr => ({ id: cr.id, detail: cr.detail })),
+        // Discovery failures — an unreadable program is infrastructure, not
+        // a finding; it fails the run always and says so here.
+        broken: ((_b = input.broken) !== null && _b !== void 0 ? _b : []).map(b => ({ id: b.id, detail: b.detail })),
         skippedUnsafe: input.skippedUnsafe,
         gate: {
             failOn: gate.failOn,

package/bin/score.d.ts

@@ -4,6 +4,7 @@ export interface ScoreResult {
     grade: string;
     filesClean: number;
     filesTotal: number;
+    emptyScan: boolean;
     partialScan?: boolean;
 }
 export declare function findingSeverity(g: ReportGroup, f: Finding): Severity;

package/bin/score.js

@@ -39,7 +39,7 @@ export function scoreFromFileHealth(perFile, filesTotal) {
     const score = filesTotal <= 0
         ? 100
         : Math.max(0, Math.min(100, Math.floor(100 * (1 - burden / filesTotal))));
-    return { score, grade: gradeFor(score), filesClean: Math.max(0, filesTotal - worst.size), filesTotal };
+    return { score, grade: gradeFor(score), filesClean: Math.max(0, filesTotal - worst.size), filesTotal, emptyScan: filesTotal <= 0 };
 }
 export function computeScore(groups, filesTotal) {
     return scoreFromFileHealth(groups.flatMap(g => g.findings.map(f => ({ file: f.file, severity: findingSeverity(g, f) }))), filesTotal);
@@ -64,7 +64,7 @@ export function scoreHeaderLines(s) {
         return { scoreLine: "Score: n/a — no files scanned", cleanLine: null, emptyScan: true, partialScan: false };
     }
     if (s.partialScan === true) {
-        return { scoreLine: "Score: n/a — partial scan (a doctor crashed; results above are incomplete)", cleanLine: null, emptyScan: false, partialScan: true };
+        return { scoreLine: "Score: n/a — partial scan (a doctor failed — crashed or broken; results above are incomplete)", cleanLine: null, emptyScan: false, partialScan: true };
     }
     return {
         scoreLine: `Score: ${s.score} / 100 — ${s.grade}`,

package/bin/summary.d.ts

@@ -4,6 +4,9 @@ export interface CheckBucket {
     ruleId: string | null;
     heading: string;
     severity: Severity;
+    impact?: string;
+    why?: string;
+    fix?: string;
     findings: Finding[];
 }
 export interface GroupChecks {

package/bin/summary.js

@@ -54,14 +54,14 @@ function dedupeGroups(groups) {
     return { groups: out, hidden };
 }
 export function deriveSummary(outcome) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const { groups, hidden } = dedupeGroups(outcome.groups);
     const total = groups.reduce((n, g) => n + g.findings.length, 0);
     const score = computeScore(groups, outcome.fileCount);
     // A crashed doctor contributes no findings, so the raw score reads its
     // silence as cleanliness — the derivation is where crashes are known,
     // and where the partial flag is set for every surface to honor.
-    if (((_b = (_a = outcome.crashed) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0)
+    if (((_b = (_a = outcome.crashed) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0 || ((_d = (_c = outcome.broken) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0) > 0)
         score.partialScan = true;
     const header = scoreHeaderLines(score);
     const severityCounts = { error: 0, warning: 0, info: 0 };
@@ -92,6 +92,9 @@ function expandChecks(g) {
                 ruleId: (_a = f.rule) !== null && _a !== void 0 ? _a : null,
                 heading: j.description,
                 severity: j.declaredSeverity,
+                ...(j.impact !== undefined ? { impact: j.impact } : {}),
+                ...(j.why !== undefined ? { why: j.why } : {}),
+                ...(j.fix !== undefined ? { fix: j.fix } : {}),
                 findings: [],
             });
         }

package/docs/plans/finding-lifecycle/design.md

@@ -88,6 +88,45 @@ changed doctor can support an explicit detector comparison, not a code-fix claim
 Expired detailed history must be identified as unavailable, not reconstructed as
 complete from summary counters.
 
+## Doctor identity across authors and renames (planned, M3)
+
+Decisions crossing trust boundaries — committed project records shared
+through Git — need doctor identity that is unique across authors and
+stable across display renames. Two mechanisms, both visible, both
+authored; no hidden self-asserted IDs:
+
+- **Namespace/id.** A doctor's full key is `namespace/id` when it
+  declares a `namespace` (kebab-case author or origin), bare `id`
+  otherwise. Bundled doctors stay bare forever — the curated first-party
+  pack — so the 0.1.2 rename never churns again; third-party doctors
+  MUST declare a namespace, making `alice/convex` and `bob/convex`
+  distinct by construction while keys stay human-readable (surfaces may
+  show the friendly id; machine surfaces carry the full key). A copy
+  that keeps the same namespace/id is honestly the same doctor; a fork
+  that changes meaning diverges through provenance (revision/digest).
+  Self-generated UUIDs are ruled out: they travel with file copies,
+  producing invisible collisions — worse than name collisions because
+  nobody can read the key. The doctor identity key never drops its
+  namespace component: matching decisions on code evidence alone would
+  let one doctor's decision suppress another doctor's finding at the
+  same location — the cross-doctor suppression the identity layer
+  exists to prevent.
+- **`supersedes` for renames.** Renaming is a semantic event only the
+  doctor's owner can assert: `supersedes: "convex-doctor"` (old full
+  key). On load, the state layer migrates decisions from superseded
+  keys to the new ones, gated on provenance continuity — revision or
+  program digest must still match; a rename combined with a meaning
+  change resurfaces decisions for reassessment rather than silently
+  carrying. This is the explicit, authored version of "identity
+  survives renames": no invisible magic, and the migration is visible
+  in state.
+
+Both land with M3 (they are load-bearing only once decisions are
+committed and shared); the doctor contract and the authoring skill
+teach the declaration from day one so authored doctors arrive
+namespaced. The 0.1.1→0.1.2 bundled rename churns once, deliberately,
+while exposure is near zero; `supersedes` is not retrofitted for it.
+
 ## Team convergence
 
 For the same source, compatible doctors/engines, configuration, and committed

package/doctors/{async-doctor.mjs → async.mjs}

@@ -1,5 +1,5 @@
 export const meta = {
-  id: "async-doctor",
+  id: "async",
   description: "Async and concurrency discipline: fetch hygiene, promise handling, timer cleanup.",
   severity: "warning",
   category: "async",
@@ -16,6 +16,7 @@ export const meta = {
       id: "fetch-calls-without-abortsignal",
       description: "Fetch call does not provide an AbortSignal.",
       severity: "warning",
+      revision: 1,
       impact: "Requests cannot be cancelled: navigating away, unmounting, or superseding leaves fetches running to completion.",
       why: "A fetch without a signal has no path to cancellation, so component-driven requests outlive the components that issued them.",
       fix: "Pass an AbortController's signal via the request options and abort it on cleanup or supersede.",
@@ -26,6 +27,7 @@ export const meta = {
       id: "unawaited-async-map",
       description: ".map(async ...) result is never awaited — the promises are dropped.",
       severity: "warning",
+      revision: 1,
       needs: ["bindings"],
       impact: "The async work starts but nothing waits for it: errors vanish silently and the results are lost mid-flight.",
       why: "Array.map returns a new array of promises. Without Promise.all or an await on the result, the async callbacks run fire-and-forget.",
@@ -38,6 +40,7 @@ export const meta = {
       id: "uncleared-settimeout-in-effect",
       description: "setTimeout inside useEffect is not cleared with clearTimeout.",
       severity: "warning",
+      revision: 1,
       impact: "The callback fires after the component is gone: state updates on unmounted components, work the user cancelled, and hard-to-trace bugs.",
       why: "Every timer started inside an effect must be cleared in that effect's cleanup; an uncleared setTimeout outlives the render that created it.",
       fix: "Assign the timer and return a cleanup that calls clearTimeout with the same identifier.",

package/doctors/{convex-doctor.mjs → convex.mjs}

@@ -1,5 +1,5 @@
 export const meta = {
-  id: "convex-doctor",
+  id: "convex",
   description: "Convex discipline: indexed reads, bounded collects, query clocks, discarded promises, validated args, awaited writes, honest runtime boundaries.",
   severity: "warning",
   category: "convex",
@@ -26,6 +26,7 @@ export const meta = {
       needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
       description: "A database filter without an index may scan many documents to find matching results.",
       severity: "warning",
+      revision: 1,
       impact: "Without an index restriction, finding matching results may read many table documents. Cost grows with the scanned candidate set, even when few results are returned.",
       why: ".filter() runs after documents are read - it cannot reduce reads. Only an index range (.withIndex with q.eq/q.gt/...) restricts how many documents the query touches.",
       fix: "Define an index covering the filtered fields in schema.ts and use .withIndex(\"by_field\", q => q.eq(\"field\", value)) instead of .filter().",
@@ -37,6 +38,7 @@ export const meta = {
       needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
       description: "An index without a range feeds an unbounded consumer.",
       severity: "warning",
+      revision: 1,
       impact: "The index does not restrict the candidate set. An unbounded collect can grow with the table; filters may read many candidates before returning a few results.",
       why: "Choosing index order does not narrow its range. This check reports unbounded consumers; filtered bounded-result consumers remain index review candidates.",
       fix: "Pass a range expression: .withIndex(\"by_x\", q => q.eq(\"x\", value)) - or bound the chain with .take(n) when recent-items ordering is the intent.",
@@ -46,7 +48,8 @@ export const meta = {
     {
       id: "query-clock-reactivity",
       description: "Date.now() in a query can produce stale time-dependent results and reduce cache reuse.",
-      severity: "warning", needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
+      severity: "warning",
+      revision: 1, needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
       claim: "A global Date.now() call directly inside an import-resolved Convex query handler.",
       lookalikes: ["mutation expiry timestamps", "action clocks", "shadowed Date", "nested or unresolved helper functions"],
       impact: "Time passing does not itself rerun a subscribed query; time-dependent results may become stale and cache reuse can suffer.",
@@ -56,7 +59,8 @@ export const meta = {
     {
       id: "transaction-clock-duration",
       description: "Subtracting two Date.now() readings in one transaction produces zero elapsed time.",
-      severity: "warning", needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
+      severity: "warning",
+      revision: 1, needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
       claim: "A subtraction of two global Date.now() calls, or immutable direct aliases, in the same inline query/mutation handler.",
       lookalikes: ["historical timestamps or expiry cutoffs", "action duration measurement", "random branching", "reassigned timestamps"],
       impact: "The transaction clock is fixed at function start, so this calculation cannot measure work duration.",
@@ -68,6 +72,7 @@ export const meta = {
       needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
       description: ".collect() on a query chain with no take, no paginate, and no index range bounding it.",
       severity: "warning",
+      revision: 1,
       impact: "Unbounded reads grow with the table and eventually hit Convex's per-transaction document read limit - the query works at demo scale and fails in production.",
       why: "Convex has no query planner: reads follow the chain exactly as written. The scaling guide is explicit that every .collect() must be provably small or index-narrowed (stack.convex.dev/queries-that-scale).",
       fix: 'Bound the chain - .take(50) for recent-items UIs, .paginate(args.paginationOpts) for incremental loading - or narrow it with .withIndex("by_field", q => q.eq(...)).',
@@ -81,6 +86,7 @@ export const meta = {
       lookalikes: ["multi-field indexes serving both bounds"],
       description: "An indexed chain that also filters - a multi-field index candidate whether the index is range-narrowed or the results are bounded.",
       severity: "warning",
+      revision: 1,
       impact: "The index range still reads every document the filter then discards; when the discarded slice is large, the query pays for it on every call.",
       why: "When one index field plus a filter still reads too much, Convex's guidance is to promote to a multi-field index so both conditions become range bounds instead of post-read filters.",
       fix: '.index("by_teamId_status", ["teamId", "status"]) and query it with both .eq() bounds instead of filtering.',
@@ -90,6 +96,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "A presence field (lastSeen/heartbeat-shaped) patched onto a document.",
       severity: "warning",
+      revision: 1,
       impact: "Convex re-runs every subscribed query that read the document. A 10-second heartbeat on a widely-read user document invalidates those queries continuously - including queries that never touch the field.",
       why: "Frequently-updated fields on widely-referenced documents cause fan-out invalidation; the scaling guide's fix is document segmentation, not smarter queries.",
       fix: 'Split presence into its own table (heartbeats) and patch that; patch the parent document only on meaningful transitions (online to offline).',
@@ -101,6 +108,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "A query/mutation/action defined without argument validators.",
       severity: "warning",
+      revision: 1,
       impact: "Args arrive unvalidated and untyped: any payload the client sends is accepted at runtime, and the handler's args parameter is any instead of the inferred literal type - typos surface later as undefined fields instead of immediately as validation errors.",
       why: "Validators are the contract: Convex checks every call against args at runtime and generates the handler's TypeScript types from the same definition. A function without args gets neither the check nor the types.",
       fix: "Declare the shape: export const create = mutation({ args: { body: v.string() }, handler: ... }) - an explicit args: {} for no-arg functions keeps the contract visible.",
@@ -112,6 +120,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "A server-side run call referencing the public api namespace - a review candidate; namespace alone does not establish an authorization flaw.",
       severity: "info",
+      revision: 1,
       impact: "Everything reachable through api is callable by any client that can reach the deployment. A server-only workflow invoked via api is an exposed surface that clients can call directly, with any arguments the validators accept.",
       why: "internal.* is the server-to-server namespace: the same functions, unreachable from clients. A run* call that names api.* is either exposing a function by mistake or announcing it should be internal.",
       fix: "Define the target as internalQuery/internalMutation/internalAction and reference it as internal.module.function in the run* call.",
@@ -123,6 +132,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "A write, scheduler, or mutation/action call inside a query.",
       severity: "warning",
+      revision: 1,
       impact: "Queries are read-only transactions - the write methods do not exist on a query's context, so the function fails on its first real call rather than at deploy time. ctx.runQuery IS allowed (same read snapshot); only mutations, actions, and scheduling are forbidden.",
       why: "A query body runs inside a deterministic read transaction: its context carries db reads, auth and storage, runQuery, nothing else. Writes and scheduling belong in a mutation.",
       fix: "Move the write into a mutation the client or an action invokes; if the read and the write must be atomic, the whole operation is a mutation that reads first.",
@@ -134,6 +144,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "ctx.db used inside an action.",
       severity: "warning",
+      revision: 1,
       impact: "Actions have no db on their context - the call throws at runtime, usually on the first request that reaches that path.",
       why: "Actions run outside the transaction: their context offers runQuery/runMutation/runAction, scheduler, storage and auth. Database access goes through a function the action invokes.",
       fix: "Replace ctx.db.<x> with await ctx.runQuery(...) for reads or await ctx.runMutation(...) for writes.",
@@ -143,7 +154,8 @@ export const meta = {
     {
       id: "unawaited-convex-call",
       description: "A known Promise-returning Convex context call is discarded as a standalone expression.",
-      severity: "warning", needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
+      severity: "warning",
+      revision: 1, needs: ["calls"], onUnknown: "skip", reportingUnit: "occurrence",
       claim: "A direct discarded call to a context method of an import-resolved handler's context parameter - db or storage, reads included, scheduler and run* functions too - resolved by binding identity.",
       lookalikes: ["returned callbacks", "arguments to helpers", "stored promises", "query builders", "shadowed context bindings"],
       impact: "Discarding the promise can lose errors or leave work unfinished when the function returns.",
@@ -155,6 +167,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: 'A query or mutation defined in a "use node" file.',
       severity: "warning",
+      revision: 1,
       impact: "Deploy fails: queries and mutations must run in Convex's deterministic runtime, which is what makes their transaction guarantees replayable.",
       why: '"use node" opts the file into the Node runtime, which only actions can use. Queries and mutations must be deterministic so re-execution produces identical results.',
       fix: "Split the file: keep the query/mutation in the default runtime and move the Node-dependent work into an action it schedules.",
@@ -166,6 +179,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "A run call awaited inside a for/while loop - a batching review candidate; deliberate retry loops (OCC with backoff) share this shape.",
       severity: "info",
+      revision: 1,
       impact: "N iterations become N separate transactions, each with its own round trip and commit - a 1000-item backfill is 1000 sequential transactions, and the caller's timeout budget pays for all of them.",
       why: "Each run* call is a complete transaction of its own. A loop of awaited runs is the slowest possible batch; the batching guidance is to do the work inside one mutation instead.",
       fix: "Pass the ids to a mutation that loops internally over ctx.db writes - one transaction - or chunk the loop into bounded batches of run* calls.",
@@ -177,6 +191,7 @@ export const meta = {
       reportingUnit: "occurrence",
       description: "ctx.db.patch/replace called with a spread - a review candidate; presence alone does not prove client-controlled fields.",
       severity: "info",
+      revision: 1,
       impact: "Every field the client included gets written: the validators constrain the mutation's args, but the spread forwards them all, so fields the mutation never named (ownership, role, timestamps) become client-writable.",
       why: "patch merges whatever object it is given. Spreading args into it delegates field selection to the caller - the opposite of what a validated mutation is for.",
       fix: "Name the fields: ctx.db.patch(args.id, { title: args.title }) - build the patch object server-side from explicitly validated values.",

package/doctors/{effect-v4-doctor.mjs → effect-v4-kitlangton.mjs}

@@ -1,5 +1,5 @@
 export const meta = {
-  id: "effect-v4-doctor",
+  id: "effect-v4-kitlangton",
   description: "Effect v4 discipline: typed errors over hand-rolled tags, Config over direct env reads, named Effect.fn, deterministic generators, validated boundaries, no casts that silence the type system. The mechanical rules of the kitlangton Effect skill, enforced.",
   severity: "warning",
   category: "effect",
@@ -23,6 +23,7 @@ export const meta = {
       id: "type-silencing-cast",
       description: "`as any`, a double cast, or a non-null assertion used in Effect code.",
       severity: "warning",
+      revision: 1,
       impact: "The cast disables exactly the guarantee Effect's types exist to give - that every failure is typed and every value's context is known. The next reader inherits an unsound spot that neither the compiler nor the runtime will ever flag.",
       why: "Effect's type system is the discipline: errors are values, contexts are tracked. The Effect skill's first Do Not names this directly - no `as any`, no non-null assertions, no unchecked casts to silence typing problems.",
       fix: "Answer the type instead: narrow with Schema decoding at the boundary, model the absence (Option/nullable field) instead of asserting it away, or scope one `Effect.castTo`-style escape with a comment if it is truly unavoidable.",
@@ -33,6 +34,7 @@ export const meta = {
       id: "schema-class-as-default",
       description: "Schema.Class / Schema.TaggedClass used for application data modeling.",
       severity: "warning",
+      revision: 1,
       impact: "Class-based schemas pull inheritance and identity semantics into what is usually a plain record, and they accrete: one class schema becomes the base of a hierarchy the codebase never needed.",
       why: "The Effect skill's model is records as `Schema.Struct(...)` plus a same-name interface, with tagged variants reserved for boundary-crossing unions - Schema.Class and Schema.TaggedClass are explicitly not the default modeling pattern.",
       fix: "Model the record with Schema.Struct({...}) and an interface of the same name; reach for Schema.TaggedStruct/TaggedUnion only at boundaries that need discriminants.",
@@ -43,6 +45,7 @@ export const meta = {
       id: "handrolled-tagged-error",
       description: "A _tag error class hand-rolled (extends Error with a _tag, or Data.TaggedError) instead of Schema.TaggedErrorClass.",
       severity: "warning",
+      revision: 1,
       impact: "Hand-rolled error classes drift from the schema ecosystem: no decoder at boundaries, no derived interface, and each one re-implements tagging slightly differently - exhaustiveness checking gets weaker the more exist.",
       why: "The skill's rule: expected typed failures are `Schema.TaggedErrorClass`; do not hand-roll `_tag` error classes when it fits.",
       fix: "Declare the failure with Schema.TaggedErrorClass<Name>()(\"Name\", { field: Schema.String }) - it carries the tag, the payload schema, and the interface in one definition.",
@@ -53,6 +56,7 @@ export const meta = {
       id: "cause-level-recovery",
       description: "Effect.catchCause / catchAllCause / sandbox used where typed-error recovery is the default.",
       severity: "info",
+      revision: 1,
       impact: "Cause-level recovery sees defects (failures the code was not prepared for) as recoverable, which quietly swallows programming errors into fallback paths instead of letting them surface.",
       why: "The skill's ordering: typed-error recovery first; cause-level recovery only when the boundary truthfully wants defects too. This check records every cause-level use at info severity because the legitimate cases exist.",
       fix: "Recover on the typed tag (catchTag / catchAll over the error union); reserve cause-level handling for boundaries that genuinely observe defects (logging, supervision).",
@@ -63,6 +67,7 @@ export const meta = {
       id: "direct-process-env-read",
       description: "process.env read directly inside Effect application code.",
       severity: "warning",
+      revision: 1,
       impact: "Env reads scattered through logic cannot be overridden in tests, differ between layers, and hide configuration from the ConfigProvider - the app's settings become untestable ambient state.",
       why: "The skill's core default: runtime configuration is read through `Config` recipes in layers, not direct process.env access in application logic.",
       fix: "Declare Config.schema/redacted/string for the variable, read it with yield* inside the owning layer, and swap ConfigProvider layers in tests.",
@@ -73,6 +78,7 @@ export const meta = {
       id: "unnamed-effect-fn",
       description: "Effect.fn defined without a span/tracing name.",
       severity: "warning",
+      revision: 1,
       impact: "Unnamed Effect.fn functions show up in traces and stack frames as anonymous noise - the observability the API exists to provide is silently discarded.",
       why: "The skill: public service methods and non-trivial internal methods are defined with `Effect.fn(\"Domain.operation\")` - the name is the point; Effect.fnUntraced is the explicit opt-out, not the default.",
       fix: "Pass the dotted name first: Effect.fn(\"User.load\")((userId) => ...) - or use Effect.fnUntraced deliberately when span metadata is intentionally unnecessary.",
@@ -83,6 +89,7 @@ export const meta = {
       id: "date-now-in-gen",
       description: "Date.now() called inside an Effect.gen body.",
       severity: "warning",
+      revision: 1,
       impact: "The generator reads wall-clock time directly, so the workflow is untestable with TestClock and non-reproducible across runs - time-sensitive branches flip depending on when the code executes.",
       why: "Effect generators run against the runtime's Clock service precisely so time can be controlled (TestClock in tests); Date.now() steps around that contract. The ecosystem's rule: read time through Clock, or pass it in.",
       fix: "yield* Clock.currentTimeMillisNow() (TestClock controls it in tests), or accept the timestamp as a parameter from the caller.",
@@ -93,6 +100,7 @@ export const meta = {
       id: "zod-single-record",
       description: "z.record called with a single argument.",
       severity: "warning",
+      revision: 1,
       impact: "The single-argument form leaves the record's keys unconstrained - a schema that validates values but accepts any key shape, which is exactly the drift the boundary was meant to stop.",
       why: "z.record's single-argument call is the legacy loose form; the explicit form names both halves of the contract (z.record(keySchema, valueSchema)) and keeps key validation honest. In Effect apps, boundary validation is the discipline - Schema or zod, either way both halves are named.",
       fix: "Name both halves: z.record(z.string(), valueType) - or migrate the boundary to Effect Schema (Schema.Struct plus decoding at the edge).",
@@ -103,6 +111,7 @@ export const meta = {
       id: "sleep-in-test",
       description: "Effect.sleep used inside a test file.",
       severity: "warning",
+      revision: 1,
       impact: "Real sleeps make tests slow and flaky: they encode a guess about timing instead of a synchronization fact, so they pass until the machine is busy - then fail spuriously.",
       why: "The skill's testing rule: no arbitrary Effect.sleep in tests when a deterministic primitive is available - TestClock controls time, and Deferred/Queue/Latch/Ref synchronize for real.",
       fix: "Advance time with TestClock, or synchronize on a Deferred/Latch the code under test completes; sleep only when pacing itself is the behavior under test.",
@@ -113,6 +122,7 @@ export const meta = {
       id: "blind-layer-merge",
       description: "Layer.mergeAll / provideMerge used as a make-it-compile composition tool.",
       severity: "info",
+      revision: 1,
       impact: "Merging everything blurs which layer provides which dependency; requirement errors surface as far-away runtime resolution failures instead of close-to-the-code build errors.",
       why: "The skill names these as blind make-it-compile tools: composition should express the dependency structure, not flatten it. Recorded at info severity because legitimate merges exist.",
       fix: "Express the wiring: build layers from their dependencies (Layer.provide / composition at the layer that needs them) so the graph is readable in code.",
@@ -302,7 +312,7 @@ function checkSchemaClass(ctx, file, lines) {
 
 // Two shapes: the Data.TaggedError class-builder (any usage), and any class
 // declaring its own _tag member - the body is brace-tracked from the class
-// line the same way convex-doctor tracks function bodies.
+// line the same way convex tracks function bodies.
 function checkTaggedError(ctx, file, lines) {
   for (let i = 0; i < lines.length; i++) {
     if (/\bData\.TaggedError\b/.test(lines[i])) {

package/doctors/{openrouter-doctor.mjs → openrouter.mjs}

@@ -1,5 +1,5 @@
 export const meta = {
-  id: "openrouter-doctor",
+  id: "openrouter",
   description: "OpenRouter discipline: stream errors surfaced, keep-alives skipped, cancellations that stop billing.",
   severity: "warning",
   category: "openrouter",
@@ -15,6 +15,7 @@ export const meta = {
       id: "midstream-error-ignored",
       description: "A streamed OpenRouter response is consumed without ever checking for mid-stream errors",
       severity: "warning",
+      revision: 1,
       impact: "After headers commit, OpenRouter keeps the status at 200 and delivers failures as SSE events — the docs note the error chunk 'can be the first and only event'. A loop that only reads delta.content records a silent empty reply as success.",
       why: "OpenRouter's stream protocol puts errors inside the 200-OK body: a top-level error field on the chunk, with choices[0].finish_reason === \"error\". Neither the HTTP status nor the types say anything is wrong.",
       fix: "Check each chunk: `if (chunk.error ?? parsed.choices?.[0]?.finish_reason === \"error\") throw new Error(chunk.error?.message)` before reading delta.content.",
@@ -25,6 +26,7 @@ export const meta = {
       id: "sse-comment-parse-crash",
       description: "A hand-rolled SSE reader will feed OpenRouter's keep-alive comments to JSON.parse",
       severity: "warning",
+      revision: 1,
       impact: "OpenRouter sends `: OPENROUTER PROCESSING` comment lines while routing; the docs warn hand parsers must skip them. A loop that JSON.parses every data-bearing line crashes mid-generation.",
       why: "SSE keep-alive comments start with `:` and are legal on any stream, but OpenRouter sends them as a matter of course during provider routing — a naive `split(\"\\n\")` + JSON.parse loop meets one on the first slow request.",
       fix: "Skip comment lines before parsing: `if (line.startsWith(\":\")) continue;` — or use an SDK stream helper that handles SSE framing.",
@@ -35,6 +37,7 @@ export const meta = {
       id: "missing-abort-signal",
       description: "An OpenRouter request is sent without an AbortSignal, so cancellation keeps billing",
       severity: "warning",
+      revision: 1,
       impact: "For non-streaming requests and several providers (Bedrock, Groq, Google, Mistral, Replicate, …) the docs are explicit: aborting without a signal means 'the model will continue processing and you will be billed for the complete response'.",
       why: "Cancellation stops processing and billing only when the connection is actually aborted. No signal, no abort — the user who navigates away still pays for the full completion.",
       fix: "Thread an AbortController through: `fetch(url, { ..., signal: controller.signal })`, and abort it on cancellation, navigation, or timeout.",
@@ -45,6 +48,7 @@ export const meta = {
       id: "retry-after-ignored",
       description: "A retry loop around an OpenRouter call never reads the Retry-After header",
       severity: "warning",
+      revision: 1,
       impact: "429 and 503 responses carry Retry-After, and raw fetch gets no SDK backoff — immediate retries thundering-herd into the same limit and can exhaust the daily caps on :free variants (20 RPM / 50–1000 RPD).",
       why: "The official SDKs honor Retry-After automatically; hand-rolled catch-and-retry loops don't. The header is the only backoff signal a raw fetch client receives.",
       fix: "Read the header and wait: `const wait = Number(res.headers.get(\"retry-after\") ?? 1); await sleep(wait * 1000);` before retrying.",
@@ -55,6 +59,7 @@ export const meta = {
       id: "hardcoded-dated-model-slug",
       description: "A dated model slug is hardcoded where a maintained alias would survive provider removals",
       severity: "info",
+      revision: 1,
       impact: "Model availability is separate from API versioning — the docs state models are added and removed by providers independently, and a removed slug starts returning 404s with zero code changes around it.",
       why: "OpenRouter maintains ~family-latest aliases and per-slug routing variants (:nitro, :floor, :free). A versioned slug is sometimes a deliberate reproducibility pin — this is advice to pin consciously, not a defect.",
       fix: "Prefer `~author/family-latest` aliases or read slugs from config; if the pin is deliberate, keep it and note why.",

package/doctors/{slop-doctor.mjs → slop.mjs}

@@ -1,5 +1,5 @@
 export const meta = {
-  id: "slop-doctor",
+  id: "slop",
   description: "LLM slop discipline: duplicated helpers, dead exports and unread bindings, hostname-sniffed environments, careless text matching, collapsed boolean states. Born from 1,368 Bugbot findings across 182 reviewed PRs.",
   severity: "warning",
   category: "slop",
@@ -19,6 +19,7 @@ export const meta = {
       id: "identical-helper-body-in-two-modules",
       description: "A function body identical (literals included) to one in another module - a consolidation suggestion, not a proven defect.",
       severity: "info",
+      revision: 1,
       impact: "Two copies of one contract drift independently: the next edit fixes one and silently leaves the other behind. In the corpus this came from, reviewers raised it 16 times across 14 PRs and every finding was actioned - but duplication alone establishes maintenance risk, not a bug.",
       why: "Generated code copies what worked instead of importing it. The bodies are identical including literal values, which is what makes later divergence invisible - but intentional copies exist, so this is a review suggestion.",
       fix: "Consolidate into one shared module and import it on both sides - or, if the domains must stay separate, make the separation explicit in the name and a comment saying why they differ.",
@@ -31,6 +32,7 @@ export const meta = {
       id: "environment-guessed-from-hostname-substring",
       description: "Environment routing decided by a hostname substring with a fixed fallback.",
       severity: "info",
+      revision: 1,
       impact: "Every deployment host the substring does not anticipate falls through to the fallback environment - production traffic silently using local/dev settings, or vice versa. The corpus caught this 8 times across 2 PRs.",
       why: "Guessing environment from `host.includes(\"staging\")` encodes a naming convention as a behavior switch; opaque custom domains and renamed deployments break the guess with no error anywhere.",
       fix: "Read the environment from configuration (an explicit env var or build-time constant) and treat unknown values as errors, with the hostname heuristic at most a last-resort default.",
@@ -41,6 +43,7 @@ export const meta = {
       id: "boolean-collapsed-into-three-state",
       description: "A nullish-defaulted boolean collapsed into a two-way ternary that feeds a three-state domain.",
       severity: "info",
+      revision: 1,
       impact: "false from 'not detected' and false from 'explicitly refused' become the same state - downstream logic treats unknown as negative, 8 findings across 4 PRs in the corpus.",
       why: "`x ?? detect()` yields boolean | undefined, but `x === true ? A : B` maps both false and undefined to B. The three-state union was written knowing the difference; the collapse forgets it.",
       fix: "Branch on the actual three states: `typeof x === \"boolean\" ? (x ? A : B) : C` - or model the source as an explicit tri-state from the start.",
@@ -51,6 +54,7 @@ export const meta = {
       id: "prefix-overlapping-substring-match",
       description: "An OR-chain of substring tests whose literals overlap by prefix.",
       severity: "warning",
+      revision: 1,
       impact: "`includes(\"referral\") || includes(\"refer\")` also matches 'reference', 'referee', 'preferred' - the classifier accepts unrelated words and the stem list grows by accretion. 5 findings across 5 PRs.",
       why: "The shorter stem subsumes the longer one entirely and both subsume words nobody meant. Substring matching has no word boundary, so every added stem widens the net silently.",
       fix: "Match whole tokens: split the text and compare exact membership, or use a word-bounded regex (\\breferral\\b) - one explicit list, no accidental vocabulary.",
@@ -61,6 +65,7 @@ export const meta = {
       id: "export-without-any-consumer",
       description: "A named export with no consumer found - a deletion candidate, pending the blind spots below.",
       severity: "info",
+      revision: 1,
       impact: "Likely dead public surface: code that looks load-bearing, is maintained, reviewed, and shipped - but no consumer was found. The corpus caught this 5 times across 4 PRs.",
       why: "Generated code over-exports ('might be useful'), and nothing in the toolchain reports an export with zero consumers. Dynamic consumers are detected heuristically - see blind spots - so this is a candidate, not a verdict.",
       fix: "Verify against the blind spots, then delete it - or consume it. If it is a genuine public API entry point, say so in a comment and exempt it deliberately.",
@@ -73,6 +78,7 @@ export const meta = {
       id: "named-import-without-reference",
       description: "A named import with zero references (value, JSX, and type positions all resolve) and no textual trace.",
       severity: "warning",
+      revision: 1,
       impact: "Dead dependency surface: the import suggests usage the module does not have, and removing the last real import from a module can change its initialization order. 5 findings across 3 PRs.",
       why: "Imports accumulate during generation and refactoring; TypeScript only reports these with noUnusedLocals enabled, which most repos never turn on. The identity engine resolves JSX and type-position references, and a whole-word occurrence guard backstops what no resolver sees - a finding means BOTH layers found nothing.",
       fix: "Remove the specifier (keep the import statement if other specifiers remain or the module has side effects).",
@@ -85,6 +91,7 @@ export const meta = {
       id: "unread-local-binding",
       description: "A non-exported local binding that is never read anywhere in its file.",
       severity: "info",
+      revision: 1,
       impact: "Computation whose result nobody uses - constants, derived values, whole call results assigned and forgotten. The corpus found these as rate-limit constants and computed guards left behind by refactors.",
       why: "Bindings created for a plan the code abandoned. Side-effecting initializers are deliberately exempt (the call may matter even when the value does not).",
       fix: "Delete the binding; if its initializer has side effects, keep the expression and drop the assignment.",
@@ -97,6 +104,7 @@ export const meta = {
       id: "unanchored-abbreviation-regex",
       description: "A short case-insensitive regex tested against text without word boundaries.",
       severity: "info",
+      revision: 1,
       impact: "/ai/i matches 'said', 'wait', 'chair' - an abbreviation filter that accepts common words wholesale. 4 findings across 4 PRs.",
       why: "Short stems need boundaries; without them the regex is a substring test wearing a regex costume, and case-insensitivity widens it further.",
       fix: "Anchor it: /\\bai\\b/i - or match against whole tokens after splitting.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "any-doctor",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Your agent writes the analyzer, fixtures prove it, CI reruns it forever.",
   "license": "MIT",
   "bin": {

package/skill/agent-usage.md

@@ -11,15 +11,28 @@ npx any-doctor@latest run --all <dir> --format json
 ```
 
 One JSON object on stdout (diagnostics on stderr — ignore stderr unless
-the exit code is nonzero). Every finding carries:
-
-- `file`, `line`, `column`, `severity`, `message`
-- `decisionKey` — the finding's stable identity; use it to record decisions
-- `decision` — present only when a decision already applies to it
-
-Exit codes: crashes and skipped doctors fail ALWAYS. `--fail-on
-error|warning|info` sets a bar over RAW findings — recorded decisions
-never flip a gate, so dismissing findings cannot fake a clean run.
+the exit code is nonzero). Structure: `groups` → `checks` → `findings`.
+Replace `<dir>` with the SAME target directory in every command — state
+and decisions live per directory, and omitting it targets your current
+working directory.
+
+Each check carries `heading`, `severity`, and the explanation fields
+`impact`, `why`, `fix` (present when the doctor declared them) — read
+these to investigate. Each finding carries:
+
+- `file`, `line` — always; `column`, `severity`, `message` — optional
+- `decisionKey` — the finding's stable identity; use it to record
+  decisions. ABSENT when `staleEvidence` is true (the source could not
+  be read): such findings are not decidable this run — report them, and
+  note that decisions never attach to unreadable evidence
+- `decision` — present only when a decision already applies (decided
+  findings stay in this raw list, annotated; the human report hides them)
+
+Exit codes: crashes, broken doctors (unreadable programs), and skipped
+doctors fail ALWAYS, and appear in the JSON as `crashed`, `broken`, and
+`skippedUnsafe`. `--fail-on error|warning|info` sets a bar over RAW
+findings — recorded decisions never flip a gate, so dismissing findings
+cannot fake a clean run.
 
 ## The workflow
 
@@ -41,10 +54,13 @@ decide.
 ## Recording decisions
 
 ```bash
-npx any-doctor@latest decide --key <decisionKey> --accepted --reason "<why>"
-npx any-doctor@latest decide --key <decisionKey> --not-applicable --reason "<why>"
+npx any-doctor@latest decide --key <decisionKey> --accepted --reason "<why>" <dir>
+npx any-doctor@latest decide --key <decisionKey> --not-applicable --reason "<why>" <dir>
 ```
 
+(With `--file`/`--line` resolution instead of `--key`, pass the doctor
+path too: `decide --file <f> --line <n> --accepted --reason "…" <doctor> <dir>`.)
+
 - `--accepted`: the concern is real but the code is intentional.
 - `--not-applicable`: the check's interpretation is wrong for this code.
 - `--reason` is required and must be specific enough for a human to
@@ -60,6 +76,9 @@ npx any-doctor@latest decisions <dir> --json     # inspect state
 npx any-doctor@latest decisions <dir> --reverse <key>
 ```
 
+State lives in `<dir>/.any-doctor/decisions.local.json` — the directory
+you scanned, not the one you run from.
+
 ## Diff against a base
 
 ```bash