any-doctor 0.0.9 → 0.1.1

package/CONTEXT.md

@@ -360,8 +360,11 @@ and applicability rules.
   digest, indentation-relative column, and innermost enclosing function span —
   computed per comparison from one post-scan read, never persisted.
 - **Observation:** evidence that a finding was detected in a particular scan.
-- **Decision:** a reasoned accepted/not-applicable disposition with local or project
-  scope; it changes review state, not the raw observation.
+- **Decision** *(landed locally, D31)*: a reasoned accepted/not-applicable
+  disposition with a required reason, stored in the local decisions file,
+  reversible, attached to a Finding identity — it changes review state
+  (the active list), never the raw observation, and never the gate.
+  Project scope (Git-shared) is M3.
 - **Continuing** *(landed in the diff path)*: a head occurrence matched to a
   compatible base occurrence by identity — movement is not addition. Matches
   resting on content alone are flagged contextFallback; identical copies
@@ -369,5 +372,6 @@ and applicability rules.
 - **No longer detected** *(landed in the diff path)*: absence established by
   compatible, completed coverage.
 - **Claimed fix:** a recorded explanation of remediation, separate from rescan evidence.
-- **Reassessment:** a decision requires review because identity or applicability is
-  changed, conflicting, or uncertain.
+- **Reassessment** *(landed locally)*: a decision requires review because
+  its evidence changed — the finding resurfaces with a warning; the
+  decision is never silently carried.

package/bin/cli.js

@@ -4,15 +4,19 @@ import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { DOCTOR_FILE_RE } from "./contract.js";
 import { renderJson, renderReport, renderVerifyResult, reportDiffOf, unsafeSkipLine } from "./report.js";
+import { readKeyFor, resolveFinding } from "./contract.js";
 import { runCohort } from "./cohort.js";
 import { countsOfSeverities, gateVerdict, isFailOn } from "./gate.js";
-import { captureHeadScan, runDiff } from "./diff.js";
+import { runDiff } from "./diff.js";
 import { digestTextFile, doctorDigests } from "./identity.js";
+import { decisionsPath, loadDecisions, recordDecision, reverseDecision, decodeDecisionKey, encodeDecisionKey } from "./finding-state.js";
+import { reviewOf } from "./review.js";
+import { captureScan } from "./scan-capture.js";
 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";
@@ -42,6 +46,19 @@ function skillText() {
         return null;
     }
 }
+// The agent usage doc — the machine-facing interface, printable on demand
+// (`any-doctor help agents`) so npx-only users need no installation to
+// discover it. Shipped in the package; always in sync with the version
+// that printed it.
+function agentUsageText() {
+    const p = fileURLToPath(new URL("../skill/agent-usage.md", import.meta.url));
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
 function useColor() {
     return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
 }
@@ -55,6 +72,71 @@ class ExitCode extends Error {
         this.code = code;
     }
 }
+// ---- remembered decisions (M2) ------------------------------------------
+//
+// Local decisions suppress findings from the ACTIVE list (report display,
+// dashboard tree) when the identity key matches exactly; gates and exit
+// codes stay on the RAW findings — a private decision never changes CI
+// (that is M3's project scope). Evidence-changed findings resurface with
+// a reassessment warning; a corrupt decisions file fails the run loudly
+// rather than silently ignoring the user's records.
+// The JSON adapter over the view: per-readKey rows carry the printable
+// key (decision only where applied); the decisions block renders only
+// when it has content — renderJson decides from this payload.
+function jsonReviewOf(view) {
+    const annotations = new Map();
+    for (const [readKey, row] of view.rows) {
+        annotations.set(readKey, {
+            ...(row.key !== undefined ? { decisionKey: row.key } : {}),
+            ...(row.decision !== undefined ? { decision: row.decision } : {}),
+            ...(row.stale === true ? { stale: true } : {}),
+        });
+    }
+    return {
+        annotations,
+        reassessing: view.reassessing,
+        ambiguous: view.ambiguous.map((a) => ({ checkKey: a.checkKey, file: a.file, occurrences: a.occurrences })),
+        dormant: view.dormant,
+    };
+}
+// The command layer's adapter: one ReviewView, surfaces read it. The
+// derivation lives in review.ts — one derivation, N adapters.
+function computeReview(targetDir, capture, provenance, load = loadDecisions) {
+    const loaded = load(targetDir);
+    if (!loaded.ok)
+        return loaded;
+    return { ok: true, review: reviewOf(capture, loaded.decisions, encodeDecisionKey, provenance) };
+}
+// The scan's doctor provenance: program digests from the spec (the same
+// pre-scan digest discipline the diff uses) — the command layer alone
+// holds program paths.
+function scanProvenanceOf(spec, groups) {
+    var _a;
+    const digests = doctorDigests(spec.doctors, digestTextFile);
+    const programDigests = new Map(digests.map((d) => [d.doctorId, d.digest]));
+    const revisions = new Map();
+    for (const g of groups) {
+        for (const check of (_a = g.meta.checks) !== null && _a !== void 0 ? _a : []) {
+            if (check.revision !== undefined)
+                revisions.set(`${g.meta.id}/${check.id}`, check.revision);
+        }
+    }
+    return { revisions, programDigests };
+}
+// The display outcome: decided findings removed, everything else the raw
+// truth. The report and dashboard render this; the gate renders raw.
+function outcomeWithoutDecided(outcome, suppressedReadKeys) {
+    if (suppressedReadKeys.size === 0)
+        return outcome;
+    const groups = outcome.groups.map((g) => ({
+        ...g,
+        findings: g.findings.filter((f) => {
+            const j = resolveFinding(g.meta, f);
+            return !suppressedReadKeys.has(readKeyFor(j.checkKey, f.file, f.line, f.column));
+        }),
+    }));
+    return { ...outcome, groups };
+}
 // Verify's crossing of the Runner seam: a failure there is a failure of
 // the whole command, so it renders and aborts. (Run mode crosses the
 // seam through the Cohort, whose crashes ride the RunOutcome as data.)
@@ -69,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) {
@@ -224,20 +308,25 @@ 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;
 }
 async function cmdRun(args) {
-    var _a;
+    var _a, _b, _c;
     const parsed = parseArgs(args);
     if (parsed.global) {
         fail("--global is a generate-only flag");
@@ -266,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
@@ -285,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,
@@ -317,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
@@ -347,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.
@@ -363,7 +473,7 @@ async function cmdRun(args) {
     let diff;
     if (parsed.base !== undefined && outcome.crashed.length === 0) {
         try {
-            const head = captureHeadScan(spec.targetDir, summary.groups, (_a = outcome.analysisAvailable) !== null && _a !== void 0 ? _a : false, headDigests);
+            const head = captureScan(spec.targetDir, summary.groups, (_a = outcome.analysisAvailable) !== null && _a !== void 0 ? _a : false, headDigests);
             diff = await runDiff(spec, parsed.base, head);
         }
         catch (e) {
@@ -371,22 +481,56 @@ async function cmdRun(args) {
             return 1;
         }
     }
-    // The Gate: advisory findings by default (--fail-on none), crashes
-    // and skips always fail, diff mode judges only what the change
-    // ADDED.
-    const gate = gateVerdict(parsed.failOn, diff !== undefined ? countsOfSeverities(diff.added.map(a => a.severity)) : summary.severityCounts, diff !== undefined ? "diff" : "full");
     // Report-vs-dashboard policy: --all is the batch/report mode; JSON is
     // a machine surface and never opens a TUI; otherwise a real terminal
     // with room and no headless override gets the tree.
     const interactive = wantsTui(parsed);
+    // Remembered decisions: computed when state exists (headless) or when
+    // the dashboard may record one (it needs the identity keys either way).
+    // A corrupt file fails the run loudly — never ignored, never reset.
+    let review;
+    // JSON is the agent surface: findings carry decisionKey from the very
+    // first run, so agents decide without a resolving scan.
+    if (fs.existsSync(decisionsPath(parsed.targetDir)) || interactive || parsed.format === "json") {
+        const capture = captureScan(parsed.targetDir, summary.groups, (_b = outcome.analysisAvailable) !== null && _b !== void 0 ? _b : false, []);
+        const provenance = scanProvenanceOf(spec, summary.groups);
+        const r = computeReview(parsed.targetDir, capture, provenance);
+        if (!r.ok) {
+            fail(r.error);
+            return 1;
+        }
+        review = r.review;
+    }
+    // The Gate: advisory findings by default (--fail-on none), crashes
+    // and skips always fail, diff mode judges only what the change
+    // ADDED.
+    const gate = gateVerdict(parsed.failOn, diff !== undefined ? countsOfSeverities(diff.added.map(a => a.severity)) : summary.severityCounts, diff !== undefined ? "diff" : "full");
     // The machine surface: exactly one JSON object on stdout, diagnostics
     // on stderr, the gate verdict data not prose.
+    // Surfaces carry decision info only when there is any — an emptied
+    // store (last decision reversed) leaves no machinery behind.
+    const reviewActive = review !== undefined
+        && (review.accepted + review.notApplicable > 0
+            || review.reassessing.length > 0
+            || review.ambiguous.length > 0);
     if (parsed.format === "json") {
-        console.log(renderJson(outcome, summary, gate, diff));
+        console.log(renderJson(outcome, summary, gate, diff, review !== undefined ? jsonReviewOf(review) : undefined));
         return exitAfterSurface(outcome, gate);
     }
     if (!interactive) {
-        console.log(renderReport(outcome, useColor(), diff !== undefined ? reportDiffOf(diff) : undefined));
+        // Agents and pipes get one pointer to the machine surface — stderr,
+        // so JSON purity and report pipes are untouched. The TTY check keeps
+        // terminal humans (whose stdout IS a tty) free of it.
+        if (parsed.format === "report" && !process.stdout.isTTY) {
+            warn(dim("any-doctor: non-interactive output — agents: run with --format json (findings carry decisionKey); the full workflow: any-doctor help agents"));
+        }
+        // The report renders the ACTIVE list: decided findings are hidden,
+        // with the reviewed line keeping the hiding honest. The gate above
+        // still judged the raw findings — local decisions never change CI.
+        console.log(renderReport(outcomeWithoutDecided(outcome, (_c = review === null || review === void 0 ? void 0 : review.suppressedReadKeys) !== null && _c !== void 0 ? _c : new Set()), useColor(), diff !== undefined ? reportDiffOf(diff) : undefined, reviewActive && review !== undefined
+            ? { accepted: review.accepted, notApplicable: review.notApplicable,
+                reassessing: review.reassessing, ambiguous: review.ambiguous }
+            : undefined));
         return exitAfterSurface(outcome, gate);
     }
     const invoker = process.argv[1] ? `node "${fs.realpathSync(process.argv[1])}"` : "any-doctor";
@@ -394,7 +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);
-    await runDashboard({ outcome, invoker, useColor: useColor() });
+    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) {
@@ -554,6 +707,294 @@ async function cmdGenerate(args) {
     console.log(dim('  node "' + cliJs + '" verify "' + doctorAbs + '"'));
     return 0;
 }
+function parseDecideArgs(args) {
+    const out = { actor: "cli", targetDir: path.resolve("."), all: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const v = args[i + 1];
+        if (a === "--key" || a === "--file" || a === "--check" || a === "--reason" || a === "--actor") {
+            if (v === undefined || v.startsWith("--"))
+                return { error: `${a} needs a value` };
+            if (a === "--key")
+                out.key = v;
+            else if (a === "--file")
+                out.file = v;
+            else if (a === "--check")
+                out.check = v;
+            else if (a === "--reason")
+                out.reason = v;
+            else
+                out.actor = v;
+            i += 1;
+        }
+        else if (a === "--line") {
+            if (v === undefined || !/^\d+$/.test(v))
+                return { error: "--line needs a numeric value" };
+            out.line = Number(v);
+            i += 1;
+        }
+        else if (a === "--accepted")
+            out.disposition = "accepted";
+        else if (a === "--not-applicable")
+            out.disposition = "not-applicable";
+        else if (a === "--all")
+            out.all = true;
+        else if (out.doctorPath === undefined && (DOCTOR_FILE_RE.test(a) || isBareDoctorSlug(a)))
+            out.doctorPath = a;
+        else if (out.targetDir === path.resolve("."))
+            out.targetDir = path.resolve(a);
+        else
+            return { error: `unexpected argument: ${a}` };
+    }
+    if (out.disposition === undefined)
+        return { error: "choose --accepted or --not-applicable" };
+    if (out.reason === undefined || out.reason.trim() === "")
+        return { error: "--reason is required — a decision without a reason is a suppression" };
+    if (out.key === undefined && (out.file === undefined || out.line === undefined)) {
+        return { error: "pass --key <decisionKey from a scan's JSON>, or --file and --line to resolve against a fresh scan" };
+    }
+    return out;
+}
+async function cmdDecide(args) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const parsed = parseDecideArgs(args);
+    if ("error" in parsed) {
+        fail("any-doctor decide: " + parsed.error);
+        return 1;
+    }
+    let key = parsed.key;
+    let scanProvenanceAtDecide;
+    if (key !== undefined) {
+        // Keys cross shells as base64url (raw keys contain NUL separators
+        // that cannot traverse argv). A non-decodable value only matches if
+        // some record literally holds it — otherwise refuse loudly.
+        const decoded = decodeDecisionKey(key);
+        if (decoded === null) {
+            const raw = loadDecisions(parsed.targetDir);
+            const exact = raw.ok && raw.decisions.some((d) => d.key === key);
+            if (!exact) {
+                fail("any-doctor decide: --key expects the base64url decisionKey a scan's JSON or 'any-doctor decisions' prints");
+                return 1;
+            }
+        }
+        else {
+            key = decoded;
+        }
+    }
+    if (scanProvenanceAtDecide === undefined && parsed.key !== undefined && key !== undefined) {
+        // --key decisions still record what runs NOW: the decision names a
+        // checkKey, whose doctor is discoverable by id — digest its current
+        // program so a later changed doctor resurfaces this decision (the
+        // agent flow's version of the resolving scan's provenance).
+        const doctorId = (_a = key.split("\u0000")[0]) === null || _a === void 0 ? void 0 : _a.split("/")[0];
+        // An explicit doctor path wins (the caller knows what ran); else
+        // discover by the id the checkKey names.
+        const slug = parsed.doctorPath !== undefined
+            ? path.resolve(process.cwd(), parsed.doctorPath)
+            : doctorId !== undefined ? resolveDoctorPath(doctorId, process.cwd()) : null;
+        if (slug !== null) {
+            const bytes = digestTextFile(slug);
+            // 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 = "";
+    if (key === undefined) {
+        // Resolve by scanning: the decision must attach to the evidence a
+        // finding has NOW, so --file/--line re-runs the doctors first.
+        const badTarget = unusableTargetReason(parsed.targetDir);
+        if (badTarget !== null) {
+            fail(badTarget);
+            return 1;
+        }
+        let doctors;
+        if (parsed.doctorPath) {
+            const sel = await selectDoctor(parsed.doctorPath, { cwd: process.cwd(), useColor: useColor(), env: processTtyEnv() });
+            const selection = selectionOutcome(sel);
+            if ("exit" in selection)
+                return selection.exit;
+            doctors = [{ id: path.basename(selection.doctorPath, ".mjs"), programPath: selection.doctorPath }];
+        }
+        else {
+            const cohort = await gatherDoctors();
+            warnBrokenDoctors(cohort.broken);
+            if (cohortUnusable(cohort))
+                return 1;
+            let valid = cohort.valid;
+            if (!parsed.all && valid.length > 1) {
+                fail("multiple doctors discovered — pass a doctor path (or --all) so the resolving scan matches what you ran");
+                return 1;
+            }
+            doctors = valid.map((d) => ({ id: d.meta.id, programPath: d.path }));
+        }
+        const spec = { doctors, targetDir: parsed.targetDir, includeTests: false, skippedUnsafe: [] };
+        const ran = await runCohort(spec);
+        if (ran.crashed.length > 0) {
+            for (const c of ran.crashed)
+                fail(c.detail);
+            fail("any-doctor decide: the resolving scan crashed — a decision attaches to evidence, and there is none");
+            return 1;
+        }
+        const groups = deriveSummary(ran).groups;
+        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
+            .map((e) => { var _a; return ({ e, key: (_a = view.rawKeyByReadKey.get(readKeyFor(e.checkKey, e.f.file, e.f.line, e.f.column))) !== null && _a !== void 0 ? _a : "", row: view.rows.get(readKeyFor(e.checkKey, e.f.file, e.f.line, e.f.column)) }); })
+            .filter((c2) => { var _a; return ((_a = c2.row) === null || _a === void 0 ? void 0 : _a.stale) !== true; })
+            .filter(({ e }) => e.f.file === parsed.file && e.f.line === parsed.line
+            && (parsed.check === undefined || e.checkKey === parsed.check || e.f.rule === parsed.check || e.checkKey.endsWith("/" + parsed.check)));
+        if (candidates.length === 0) {
+            fail(`no current finding at ${parsed.file}:${parsed.line}${parsed.check !== undefined ? " for " + parsed.check : ""} — findings move; run a scan and use its decisionKey`);
+            return 1;
+        }
+        const distinct = new Set(candidates.map((c) => c.e.checkKey));
+        if (distinct.size > 1) {
+            fail(`multiple findings at ${parsed.file}:${parsed.line} — pass --check: ${[...distinct].join(", ")}`);
+            return 1;
+        }
+        key = candidates[0].key;
+        checkKey = candidates[0].e.checkKey;
+        const rev = scanProv.revisions.get(checkKey);
+        const doctorId = checkKey.split("/")[0];
+        scanProvenanceAtDecide = {
+            ...(rev !== undefined ? { revision: rev } : { programDigest: scanProv.programDigests.get(doctorId) }),
+        };
+    }
+    // With --key, checkKey and file come from the DECODED key itself (its
+    // first two NUL-separated fields); line is display-only and unknown
+    // here (0). Splitting the encoded argv form would store the whole
+    // blob as checkKey and the decision would sit dormant forever
+    // (loop-4's catch).
+    const [keyCheck, keyFile] = key.split("\u0000");
+    const stateExistedBefore = fs.existsSync(decisionsPath(parsed.targetDir));
+    const recorded = recordDecision(parsed.targetDir, {
+        key: key,
+        checkKey: checkKey !== "" ? checkKey : keyCheck,
+        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,
+        // Scan-resolved decisions record what ran (revision-or-digest);
+        // --key decisions carry no provenance the command can see — later
+        // scans treat absence as incompatible until re-decided (visible).
+        ...(scanProvenanceAtDecide !== undefined ? { provenance: scanProvenanceAtDecide } : {}),
+    });
+    if (!recorded.ok) {
+        fail(recorded.error);
+        return 1;
+    }
+    ok(`decision recorded (${parsed.disposition}): ${truncReason(parsed.reason)} — hidden from the active list on the next scan; any-doctor decisions --reverse <key> to undo`);
+    if (!stateExistedBefore) {
+        // The one-time adoption nudge: the highest-trust channel for agents
+        // is the repo's own AGENTS.md — we never write it; we point at the
+        // paste source.
+        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 0;
+}
+function truncReason(s) {
+    return s.length <= 60 ? s : s.slice(0, 59) + "…";
+}
+async function cmdDecisions(args) {
+    let targetDir = path.resolve(".");
+    let reverse;
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json")
+            json = true;
+        else if (a === "--reverse") {
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith("--")) {
+                fail("--reverse needs a decision key (any-doctor decisions lists them)");
+                return 1;
+            }
+            reverse = v;
+            i += 1;
+        }
+        else if (a.startsWith("--")) {
+            fail(`any-doctor decisions: unknown flag ${a} (known: --json, --reverse <key>)`);
+            return 1;
+        }
+        else
+            targetDir = path.resolve(a);
+    }
+    const loaded = loadDecisions(targetDir);
+    if (!loaded.ok) {
+        fail(loaded.error);
+        return 1;
+    }
+    if (reverse !== undefined) {
+        const r = reverseByKey(targetDir, reverse);
+        if (!r.ok) {
+            fail(r.error);
+            return 1;
+        }
+        ok("decision reversed — the finding returns to the active list on the next scan");
+        return 0;
+    }
+    if (json) {
+        // Machine surface: JSON in EVERY state (empty included — prose here
+        // broke parsers), keys shell-safe (base64url, matching decisionKey —
+        // raw keys hold NULs argv cannot carry).
+        console.log(JSON.stringify({
+            schema: 1,
+            decisions: loaded.decisions.map((d) => ({ ...d, key: encodeDecisionKey(d.key) })),
+        }, null, 2));
+        return 0;
+    }
+    if (loaded.decisions.length === 0) {
+        console.log(dim("no decisions recorded — they are created from the dashboard (a/x) or any-doctor decide"));
+        return 0;
+    }
+    // Bounded output: a wall of decisions is a denial of service on the
+    // reader; --json is the unbounded export path.
+    const LIST_CAP = 500;
+    for (const d of loaded.decisions.slice(0, LIST_CAP)) {
+        console.log(`${d.disposition === "accepted" ? "✓ accepted" : "⊘ not-applicable"}  ${d.checkKey}  ${d.file}:${d.line}`);
+        console.log(dim(`  reason: ${d.reason}`));
+        console.log(dim(`  actor: ${d.actor} · updated ${d.updatedAt} · key: ${encodeDecisionKey(d.key)}`));
+    }
+    if (loaded.decisions.length > LIST_CAP) {
+        console.log(dim(`… and ${loaded.decisions.length - LIST_CAP} more — any-doctor decisions --json`));
+    }
+    return 0;
+}
+// Reverse by exact key or a unique prefix (full identity keys are long).
+function reverseByKey(targetDir, key) {
+    const loaded = loadDecisions(targetDir);
+    if (!loaded.ok)
+        return loaded;
+    // The printed keys are base64url-encoded (raw keys hold NULs argv
+    // cannot carry); match encoded-prefix-unique, encoded-exact, or raw.
+    const candidates = [];
+    const decoded = decodeDecisionKey(key);
+    if (decoded !== null)
+        candidates.push(decoded);
+    candidates.push(key);
+    for (const candidate of candidates) {
+        const exact = loaded.decisions.find((d) => d.key === candidate);
+        if (exact !== undefined)
+            return reverseDecision(targetDir, exact.key);
+    }
+    for (const candidate of candidates) {
+        const prefixed = loaded.decisions.filter((d) => encodeDecisionKey(d.key).startsWith(candidate) || d.key.startsWith(candidate));
+        if (prefixed.length === 1)
+            return reverseDecision(targetDir, prefixed[0].key);
+        if (prefixed.length > 1)
+            return { ok: false, error: `key prefix is ambiguous (${prefixed.length} decisions) — use more characters` };
+    }
+    return { ok: false, error: "no decision matches that key — any-doctor decisions lists them (copy the printed key)" };
+}
 const STOP_WORDS = new Set(["a", "an", "the", "find", "flag", "all", "that", "which", "is", "are", "in", "on", "of", "to", "and", "or", "not"]);
 function slugify(intent) {
     const words = intent.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").trim().split(/\s+/);
@@ -566,9 +1007,13 @@ function usage() {
     console.log('  generate "<intent>" [--global]      print the exact prompt for your agent to build a doctor');
     console.log("  run [--all] [--include-tests] [doctor.(m)js] [dir]   scan; no argument = every doctor in one review tree");
     console.log("  verify [--all] [doctor.(m)js]     fixture gate (no doctor: fuzzy picker; --all: every doctor)");
+    console.log("  decide (--key K | --file F --line N [--check C]) (--accepted|--not-applicable) --reason R");
+    console.log("                                    record a decision on a finding (resolves by scanning unless --key)");
+    console.log("  decisions [dir] [--json] [--reverse K]   list remembered decisions; reverse one");
     console.log("");
     console.log(dim("doctors live in ./doctors/ (repo), ~/.any-doctor/doctors/ (global), and the bundled pack (lowest priority)."));
     console.log(dim("generation delegates to your installed agent — run and verify never touch a model."));
+    console.log(dim("agents: 'any-doctor help agents' prints the machine interface (JSON scan, decide, decisions)."));
 }
 export async function main(argv = process.argv.slice(2)) {
     const major = Number(process.versions.node.split(".")[0]);
@@ -579,6 +1024,15 @@ export async function main(argv = process.argv.slice(2)) {
     const cmd = argv[0];
     const rest = argv.slice(1);
     if (cmd === "help" || cmd === "--help") {
+        if (rest[0] === "agents") {
+            const doc = agentUsageText();
+            if (doc === null) {
+                fail("agent usage doc not found (skill/agent-usage.md missing).");
+                return 1;
+            }
+            console.log(doc.trimEnd());
+            return 0;
+        }
         usage();
         return 0;
     }
@@ -594,6 +1048,10 @@ export async function main(argv = process.argv.slice(2)) {
             return await cmdRun(rest);
         if (cmd === "verify")
             return await cmdVerify(rest);
+        if (cmd === "decide")
+            return await cmdDecide(rest);
+        if (cmd === "decisions")
+            return await cmdDecisions(rest);
     }
     catch (e) {
         if (e instanceof ExitCode)

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>;