any-doctor 0.0.1 → 0.0.2

package/CONTEXT.md

@@ -67,6 +67,17 @@ repo-scoped file access, structural search, and a finding emitter.
 Confinement enforces it: outside ctx there is nothing — no imports, no
 writes, no subprocesses, no network.
 
+`ctx.files.list()` and `ctx.search` exclude test paths by default
+(test-named code files — `*.test.*`/`*.spec.*` with a code extension —
+and `test/`, `tests/`, `__tests__/` directories): tests mimic production
+shapes without being production reads. The one law (`isTestPath`) and
+the one derivation (`includeTestsFor`) live in contract.ts; every read
+capability applies them. A Doctor run opts back in with
+`--include-tests`; `ctx.files.read()` is never filtered — an explicit
+path is a deliberate choice. Verify always sees everything its fixtures
+seed: the sandbox is the doctor's own world, and a seed named
+`*.test.ts` is deliberate test data.
+
 ## Engine
 
 The structural-search backend a DoctorCtx uses to answer ctx.search.
@@ -76,6 +87,23 @@ program runs unchanged on any engine. One module owns the invocation
 (src/engine.ts); the search host sits on it, and the sdk asks the host —
 there is exactly one path, with no unconfined fallback.
 
+## Score
+
+The share of scanned files with no findings, weighted by each affected
+file's worst severity (error 1, warning 0.5, info 0.1). One sentence,
+locally computed: "491/628 files clean" is a 78. Zero findings is 100 by
+anchor; an empty scan is also 100. The denominator is the target's file
+count as the doctors scanned it (default extensions); findings naming
+files outside that count can push the raw value negative, so the result
+is floored into 0–100 — and floored, never rounded, so any finding costs
+at least one point. Findings duplicated across doctors at the same
+file:line are deduplicated before scoring — the first-sorted copy wins
+(groups sort by the first finding carrying an explicit severity
+override, else the doctor's declared default; equal-severity groups
+fall back to input order) and a hidden duplicate's severity does not
+contribute. The score summarizes health — the findings are the work;
+the two are reported together, never conflated.
+
 ## Meta
 
 A doctor program's declared data: id, description, default severity,
@@ -116,13 +144,17 @@ discovery reads it directly, with no separate index or cache.
 ## Scope
 
 Where a doctor program lives: repo-local (`./doctors/`, committed with
-the consuming repo) or user-global (`~/.any-doctor/doctors/`, available
-in every repo). Repo-local wins slug collisions. Scanning a target repo
+the consuming repo), user-global (`~/.any-doctor/doctors/`, available
+in every repo), or bundled (the first-party pack inside the package,
+read-only — a starting point, not a dependency). Repo-local wins slug
+collisions, then user-global, then bundled. Scanning a target repo
 never writes to any scope.
 
 ## Skill
 
 The instructions any-doctor provides so an agent can create a doctor that
-fits the contract. Planted as `AGENTS.md` in a scope directory and also
-served verbatim by `generate`. Any Doctor equips agents with the skill;
+fits the contract. Planted as `AGENTS.md` behind a one-line provenance
+marker; `generate` refreshes a copy it planted (the marker is the
+boundary) and never touches a copy without one. The generation prompt
+embeds the skill verbatim. Any Doctor equips agents with the skill;
 it never launches, deploys, or speaks for an agent.

package/README.md

@@ -22,13 +22,20 @@ any-doctor run doctors/fetch-without-abort-signal.mjs path/to/repo   # scan + sc
 ```
 
 `generate` plants the skill as `AGENTS.md` in the scope dir (agents load it
-natively) and copies the generation prompt — paste it into your own agent
+natively — a planted copy refreshes on the next generate; a copy with your
+own edits is never touched) and copies the generation prompt — paste it into your own agent
 session, any agent, GUI or CLI. When it has written the doctor + fixtures,
 `verify` gates it: missing expected findings fail recall, unexpected ones
 fail precision. `run` and `verify` never touch a model or an agent — pipe
 the output (or set `ANY_DOCTOR_HEADLESS=1`) for stable CI output. Requires
 Node ≥ 18.
 
+`run` excludes test files from scanning by default (test-named code files
+and `test/`, `tests/`, `__tests__/` directories — for `ctx.files.list` and
+`ctx.search` alike) — mocks and fixture data mimic production shapes
+without being production reads. Pass `--include-tests` to scan them;
+`verify` always scans everything its fixtures seed.
+
 A doctor program is `<name>.mjs` (exports `meta` + `doctor(ctx)`) next to
 its fixture module `<name>.fixtures.mjs` (seeds + expected findings).
 See [CONTEXT.md](CONTEXT.md) for the vocabulary and
@@ -41,7 +48,7 @@ per-check fixtures and the interactive check tree in `run`.
 | Doc | What it holds |
 |---|---|
 | [CONTEXT.md](CONTEXT.md) | Domain glossary — canonical terms |
-| [docs/decisions.md](docs/decisions.md) | Decision log (D1–D16). Read first; don't relitigate |
+| [docs/decisions.md](docs/decisions.md) | Decision log (D1–D19). Read first; don't relitigate |
 | [docs/vision.md](docs/vision.md) | Product idea and the lifecycle novelty |
 | [docs/features.md](docs/features.md) | Doctor discovery & registry spec + status |
 | [docs/research.md](docs/research.md) | Landscape, React Doctor teardown |

package/bin/cli.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
+export declare function plantSkill(scopeDir: string, skill: string): "planted" | "refreshed" | "left-user-copy";
 export declare function main(argv?: string[]): Promise<number>;

package/bin/cli.js

@@ -3,7 +3,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { DOCTOR_FILE_RE } from "./contract.js";
-import { renderReport, renderVerifyResult, unsafeSkipLine } from "./report.js";
+import { cohortFileCount, renderReport, renderVerifyResult, unsafeSkipLine } from "./report.js";
 import { copyToClipboard } from "./clipboard.js";
 import { runDashboard } from "./dashboard.js";
 import { brokenDoctors, discoverDoctors, globalDoctorsDir, unsafeSlugs } from "./discover.js";
@@ -97,7 +97,7 @@ function selectionOutcome(sel) {
     }
 }
 function parseArgs(args) {
-    const out = { targetDir: path.resolve("."), all: false, global: false };
+    const out = { targetDir: path.resolve("."), all: false, global: false, includeTests: false };
     let targetDirSet = false;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -105,6 +105,8 @@ function parseArgs(args) {
             out.all = true;
         else if (a === "--global")
             out.global = true;
+        else if (a === "--include-tests")
+            out.includeTests = true;
         else if (out.doctorPath === undefined && DOCTOR_FILE_RE.test(a))
             out.doctorPath = a;
         else if (!targetDirSet) {
@@ -125,10 +127,10 @@ async function gatherDoctors() {
         broken: brokenDoctors(all),
     };
 }
-async function scanOnce(doctorAbs, targetDir) {
-    const result = await runOrReport(runDoctor({ programPath: doctorAbs, targetDir }));
+async function scanOnce(options) {
+    const result = await runOrReport(runDoctor(options));
     return {
-        group: { programName: path.basename(doctorAbs), meta: result.meta, findings: result.findings },
+        group: { programName: path.basename(options.programPath), meta: result.meta, findings: result.findings },
         fileCount: result.fileCount,
     };
 }
@@ -167,7 +169,7 @@ async function cmdRun(args) {
         if ("exit" in selection)
             return selection.exit;
         const runStarted = Date.now();
-        const scan = await scanOnce(selection.doctorPath, parsed.targetDir);
+        const scan = await scanOnce({ programPath: selection.doctorPath, targetDir: parsed.targetDir, includeTests: parsed.includeTests });
         outcome = {
             groups: [scan.group],
             crashed: [],
@@ -189,11 +191,11 @@ async function cmdRun(args) {
         const groups = [];
         const crashed = [];
         const doctorPaths = new Map();
-        let fileCount = 0;
+        const fileCounts = [];
         for (const d of discovered) {
             try {
-                const scan = await scanOnce(d.path, parsed.targetDir);
-                fileCount = Math.max(fileCount, scan.fileCount);
+                const scan = await scanOnce({ programPath: d.path, targetDir: parsed.targetDir, includeTests: parsed.includeTests });
+                fileCounts.push(scan.fileCount);
                 doctorPaths.set(d.meta.id, d.path);
                 groups.push(scan.group);
             }
@@ -208,7 +210,7 @@ async function cmdRun(args) {
             crashed,
             skippedUnsafe,
             doctorPaths,
-            fileCount,
+            fileCount: cohortFileCount(fileCounts),
             durationMs: Date.now() - runStarted,
             targetDir: parsed.targetDir,
         };
@@ -243,6 +245,9 @@ async function cmdVerify(args) {
         fail("--global is a generate-only flag");
         return 1;
     }
+    if (parsed.includeTests) {
+        warn("--include-tests applies to run only — verify always scans everything its fixtures seed");
+    }
     if (parsed.all) {
         const cohort = await gatherDoctors();
         warnBrokenDoctors(cohort.broken);
@@ -301,6 +306,21 @@ async function cmdVerify(args) {
     console.log(dim(`${result.results.length - failures}/${result.results.length} fixtures passed for ${result.meta.id}`));
     return failures > 0 ? 1 : 0;
 }
+// The planted copy of the skill once went three decisions stale
+// (doctors/AGENTS.md still taught "builtins allowed" after Confinement
+// refused every import), so planting refreshes: a copy any-doctor planted
+// carries the provenance marker and is overwritten on generate; a copy
+// without it is the user's and is never touched.
+const PLANT_MARKER = "<!-- any-doctor skill plant -->\n";
+export function plantSkill(scopeDir, skill) {
+    const agentsPath = path.join(scopeDir, "AGENTS.md");
+    const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : null;
+    if (existing === null || existing.startsWith(PLANT_MARKER)) {
+        fs.writeFileSync(agentsPath, PLANT_MARKER + skill);
+        return existing === null ? "planted" : "refreshed";
+    }
+    return "left-user-copy";
+}
 async function cmdGenerate(args) {
     let intent;
     let global = false;
@@ -324,9 +344,9 @@ async function cmdGenerate(args) {
         ? (fs.mkdirSync(globalDoctorsDir(), { recursive: true }), globalDoctorsDir())
         : path.resolve("doctors");
     fs.mkdirSync(scopeDir, { recursive: true });
-    const agentsPath = path.join(scopeDir, "AGENTS.md");
-    if (!fs.existsSync(agentsPath)) {
-        fs.writeFileSync(agentsPath, skill);
+    const planted = plantSkill(scopeDir, skill);
+    if (planted === "left-user-copy") {
+        warn("AGENTS.md exists with edits of your own — left untouched (delete it to re-plant)");
     }
     const cliJs = fileURLToPath(new URL("cli.js", import.meta.url));
     const doctorAbs = path.join(scopeDir, slug + ".mjs");
@@ -372,10 +392,10 @@ function usage() {
     console.log(BOLD + "any-doctor" + RESET + dim(" — your agent writes the analyzer, fixtures prove it, CI reruns it forever"));
     console.log("");
     console.log('  generate "<intent>" [--global]      print the exact prompt for your agent to build a doctor');
-    console.log("  run [--all] [doctor.(m)js] [dir]   scan; no argument = every doctor in one review tree");
+    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("");
-    console.log(dim("doctors live in ./doctors/ (repo) and ~/.any-doctor/doctors/ (global)."));
+    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."));
 }
 export async function main(argv = process.argv.slice(2)) {
@@ -386,10 +406,15 @@ export async function main(argv = process.argv.slice(2)) {
     }
     const cmd = argv[0];
     const rest = argv.slice(1);
-    if (!cmd || cmd === "help" || cmd === "--help") {
+    if (cmd === "help" || cmd === "--help") {
         usage();
         return 0;
     }
+    // D15: bare `npx any-doctor` is the cold start — every discovered
+    // doctor (bundled included), straight into the report/tree, no usage
+    // wall. `help` remains the explicit usage door.
+    if (!cmd)
+        return await cmdRun(rest);
     try {
         if (cmd === "generate")
             return await cmdGenerate(rest);

package/bin/contract.d.ts

@@ -62,6 +62,7 @@ export declare const SEARCH_RESULT = "###ANY_DOCTOR_SEARCH_RESULT###";
 export type Mode = {
     kind: "run";
     root: string;
+    includeTests?: boolean;
 } | {
     kind: "verify";
     fixtures: string;
@@ -112,6 +113,8 @@ export type Frame = RunResult | VerifyRunResult | MetaResult;
 export declare const DOCTOR_FILE_RE: RegExp;
 export declare const FIXTURES_FILE_RE: RegExp;
 export declare function fixturesPathFor(programPath: string): string;
+export declare function isTestPath(relativePath: string): boolean;
+export declare function includeTestsFor(mode: Mode): boolean;
 export declare function runCommandFor(doctorPath: string, root: string, invoker?: string): string;
 export declare function compareFindings(expected: {
     file: string;

package/bin/contract.js

@@ -7,7 +7,9 @@ export const SEARCH_REQUEST = "###ANY_DOCTOR_SEARCH###";
 export const SEARCH_RESULT = "###ANY_DOCTOR_SEARCH_RESULT###";
 export function modeArgs(mode, programPath) {
     switch (mode.kind) {
-        case "run": return [programPath, mode.root];
+        case "run": return mode.includeTests === true
+            ? [programPath, mode.root, "--include-tests"]
+            : [programPath, mode.root];
         case "verify": return [programPath, "--verify", mode.fixtures];
         case "meta": return [programPath, "--meta"];
     }
@@ -20,8 +22,8 @@ export function decodeLoaderArgs(argv) {
         return { program, mode: { kind: "verify", fixtures: third } };
     if (second === "--meta" && third === undefined)
         return { program, mode: { kind: "meta" } };
-    if (second !== undefined && !second.startsWith("-") && third === undefined) {
-        return { program, mode: { kind: "run", root: second } };
+    if (second !== undefined && !second.startsWith("-") && (third === undefined || third === "--include-tests")) {
+        return { program, mode: { kind: "run", root: second, ...(third === "--include-tests" ? { includeTests: true } : {}) } };
     }
     return null;
 }
@@ -36,6 +38,26 @@ export const FIXTURES_FILE_RE = /\.fixtures\.(m|c)?js$/;
 export function fixturesPathFor(programPath) {
     return programPath.replace(DOCTOR_FILE_RE, "") + ".fixtures.mjs";
 }
+// D18's one law, in the conventions' home: test files and test directories
+// are not production reads. Every read capability applies this predicate —
+// the sdk walk prunes by it, the search host filters matches by it. Test
+// FILES are test-named code files (.test./.spec. with a code extension);
+// test DIRECTORIES are test/tests/__tests__ anywhere in the path.
+const TEST_FILE_RE = /(?:\.test|\.spec)\.[cm]?[jt]sx?$/i;
+const TEST_DIR_NAMES = new Set(["test", "tests", "__tests__"]);
+export function isTestPath(relativePath) {
+    if (TEST_FILE_RE.test(relativePath))
+        return true;
+    return relativePath.split(/[\\/]+/).some((seg) => TEST_DIR_NAMES.has(seg));
+}
+// One derivation, one home: a run scans test files only when --include-tests
+// asks; a verify always sees everything its fixtures seed (D18) — the
+// sandbox is the doctor's own world.
+export function includeTestsFor(mode) {
+    if (mode.kind === "verify")
+        return true;
+    return mode.kind === "run" && mode.includeTests === true;
+}
 // The re-run command embedded in copied prompts. invoker defaults to
 // the installed binary name; callers running via node or npx pass their own.
 export function runCommandFor(doctorPath, root, invoker = "any-doctor") {

package/bin/dashboard.d.ts

@@ -1,4 +1,5 @@
 import { Finding, JoinedFinding, ReportGroup, Severity } from "./contract.js";
+import { ScoreResult } from "./score.js";
 import { TtyStdin, TtyStdout } from "./tty.js";
 import { RunOutcome } from "./report.js";
 export declare function highlightCode(line: string, useColor: boolean): string;
@@ -88,7 +89,7 @@ export interface DashboardFrameState {
     readKeys: Set<string>;
     readSource: FrameSource;
     expanded?: ReadonlySet<string>;
-    fileCount: number;
+    score: ScoreResult;
     durationMs: number;
     useColor: boolean;
     notice?: string;

package/bin/dashboard.js

@@ -2,12 +2,12 @@ import * as fs from "fs";
 import * as path from "path";
 import { copyToClipboard } from "./clipboard.js";
 import { resolveFinding, runCommandFor } from "./contract.js";
-import { scoreFromSeverities } from "./score.js";
+import { computeScore, scoreHeaderLines } from "./score.js";
 import { processTtyEnv } from "./tty.js";
 import * as tty from "./tty.js";
 import { runTty, truncateVisible, visibleWidth } from "./tty.js";
 import { BOLD, colorizer, DIM, GLYPH, gradeColor, GREEN, ORANGE, RESET, SEVERITY_COLOR, YELLOW } from "./palette.js";
-import { unsafeSkipLine } from "./report.js";
+import { dedupeGroups, unsafeSkipLine } from "./report.js";
 const SPLIT_MIN_COLS = 100;
 const TOKEN_RE = /(\/\/.*$)|('(?:[^'\\]|\\.)*'|"(?:[^'\\]|\\.)*"|`(?:[^`\\]|\\.)*`)|\b(const|let|var|function|return|if|else|for|while|await|async|try|catch|finally|import|export|from|new|class|extends|throw|typeof|instanceof|in|of|do|switch|case|break|continue|default|yield)\b|\b(\d+(?:\.\d+)?)\b/g;
 export function highlightCode(line, useColor) {
@@ -402,22 +402,22 @@ function itemRowText(it, isSelected, readKeys, c, showCheckId = true) {
     return `${isSelected ? c("›", BOLD) : " "}${glyph} ${c(it.site.file + ":" + it.site.line, wrap)}${suffix}`;
 }
 export function dashboardFrame(state) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f;
     const { tree, selectedRow, readKeys, useColor, cols, rows } = state;
     const c = colorizer(useColor);
     const findings = tree.flatMap(d => d.checks.flatMap(g => g.items));
     const layout = resolveDashboardLayout(cols, rows, findings.length);
-    const { score, grade } = scoreFromSeverities(findings.map(it => it.severity));
+    const header = scoreHeaderLines(state.score);
     const barWidth = Math.min(46, Math.max(16, cols - 60));
-    const header = [
-        c(`Score: ${score} / 100 — ${grade}`, BOLD + gradeColor(score)),
-        c(scoreBar(score, barWidth), gradeColor(score)),
-        c(`${findings.length} finding${findings.length === 1 ? "" : "s"} · ${state.fileCount} files · ${state.durationMs}ms`, DIM),
+    const headerLines = [
+        c(header.scoreLine, BOLD + gradeColor(state.score.score)),
+        c(scoreBar(state.score.score, barWidth), gradeColor(state.score.score)),
+        c(`${findings.length} finding${findings.length === 1 ? "" : "s"} · ${(_a = header.cleanLine) !== null && _a !== void 0 ? _a : state.score.filesTotal + " files"} · ${state.durationMs}ms`, DIM),
     ];
     if (state.skippedUnsafe !== undefined && state.skippedUnsafe.length > 0) {
-        header.push(c(`\u26a0 ${unsafeSkipLine(state.skippedUnsafe)}`, YELLOW));
+        headerLines.push(c(`\u26a0 ${unsafeSkipLine(state.skippedUnsafe)}`, YELLOW));
     }
-    header.push("");
+    headerLines.push("");
     const rowsData = buildListRows(tree, useColor, selectedRow, readKeys, state.expanded);
     const viewport = Math.max(1, Math.min(layout.listHeight, layout.bodyRows));
     let firstVisible = Math.max(0, Math.min(selectedRow - viewport + 1, Math.max(0, rowsData.length - viewport)));
@@ -437,11 +437,11 @@ export function dashboardFrame(state) {
         detail.push(c(`${sel.site.file}:${sel.site.line}`, BOLD));
         detail.push(c(`${cap(sel.category)} · ${sel.severity}`, DIM));
         detail.push("");
-        const impact = (_a = sel.impact) !== null && _a !== void 0 ? _a : sel.description;
+        const impact = (_b = sel.impact) !== null && _b !== void 0 ? _b : sel.description;
         for (const l of wordWrap(impact, layout.detailWidth - 2))
             detail.push(c(l, SEVERITY_COLOR[sel.severity]));
         detail.push("");
-        proseSection(detail, "Why", (_b = sel.why) !== null && _b !== void 0 ? _b : "Not documented for this check.", layout.detailWidth - 2, c);
+        proseSection(detail, "Why", (_c = sel.why) !== null && _c !== void 0 ? _c : "Not documented for this check.", layout.detailWidth - 2, c);
         detail.push("");
         detail.push(c("Code", DIM));
         for (const l of codeFrameLines(state.readSource(sel.site.file), sel.site.line, layout.detailWidth - 2, useColor))
@@ -490,7 +490,7 @@ export function dashboardFrame(state) {
     const body = [];
     if (layout.mode === "split") {
         for (let i = 0; i < layout.bodyRows; i++) {
-            body.push(padVisible(truncateVisible((_c = listLines[i]) !== null && _c !== void 0 ? _c : "", layout.listWidth), layout.listWidth) + "  " + ((_d = detail[i]) !== null && _d !== void 0 ? _d : ""));
+            body.push(padVisible(truncateVisible((_d = listLines[i]) !== null && _d !== void 0 ? _d : "", layout.listWidth), layout.listWidth) + "  " + ((_e = detail[i]) !== null && _e !== void 0 ? _e : ""));
         }
     }
     else {
@@ -501,7 +501,7 @@ export function dashboardFrame(state) {
             ...detail,
         ];
         for (let i = 0; i < layout.bodyRows; i++)
-            body.push((_e = stacked[i]) !== null && _e !== void 0 ? _e : "");
+            body.push((_f = stacked[i]) !== null && _f !== void 0 ? _f : "");
     }
     // Fixed-shape footer: the notice line is always present (blank when idle)
     // so showing or clearing a notice never changes the frame height.
@@ -509,7 +509,7 @@ export function dashboardFrame(state) {
         state.notice ? c("✔ " + state.notice, GREEN) : "",
         c("↑↓ move · →← expand · enter copy finding · c copy group · q quit", DIM),
     ];
-    return [...header, "", ...body, "", ...footer].join("\n");
+    return [...headerLines, "", ...body, "", ...footer].join("\n");
 }
 function cap(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
@@ -553,9 +553,12 @@ export async function runDashboardOn(env, input, deps = {}) {
     if (!tty.canRunTui(env))
         return;
     const useColor = input.useColor;
-    // The tree is computed once from immutable items; everything downstream
-    // — rows, prompts, expansion, detail — reads this frozen shape.
-    const tree = buildTree(buildItems(input.outcome.groups));
+    // One RunOutcome, one story on every surface: the tree AND the score
+    // consume the same deduplicated groups the report renders — counts and
+    // score can never disagree between surfaces.
+    const { groups: deduped } = dedupeGroups(input.outcome.groups);
+    const tree = buildTree(buildItems(deduped));
+    const score = computeScore(deduped, input.outcome.fileCount);
     const expanded = initialExpanded(tree);
     const readKeys = new Set();
     let notice;
@@ -604,7 +607,7 @@ export async function runDashboardOn(env, input, deps = {}) {
                 readKeys,
                 readSource,
                 expanded,
-                fileCount: input.outcome.fileCount,
+                score,
                 durationMs: input.outcome.durationMs,
                 useColor,
                 notice,

package/bin/discover.d.ts

@@ -1,6 +1,6 @@
 import { DoctorMeta } from "./contract.js";
 import { RunnerError } from "./runner.js";
-export type Scope = "repo" | "global";
+export type Scope = "repo" | "global" | "bundled";
 export interface DiscoveredDoctor {
     slug: string;
     scope: Scope;
@@ -15,10 +15,13 @@ export interface BrokenDoctor {
 export declare function unsafeSlugs(discovered: DiscoveredDoctor[]): string[];
 export declare function brokenDoctors(discovered: DiscoveredDoctor[]): BrokenDoctor[];
 export declare function globalDoctorsDir(): string;
+export declare function bundledDoctorsDir(): string;
 export declare function findRepoDoctorsDir(cwd: string): string | null;
 export declare function discoverDoctors(cwd: string, opts?: {
     globalDir?: string;
+    bundledDir?: string;
 }): Promise<DiscoveredDoctor[]>;
 export declare function resolveDoctorPath(arg: string, cwd: string, opts?: {
     globalDir?: string;
+    bundledDir?: string;
 }): string | null;

package/bin/discover.js

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { fileURLToPath } from "url";
 import { DOCTOR_FILE_RE, FIXTURES_FILE_RE } from "./contract.js";
 import { metaDoctor } from "./runner.js";
 // The gate's partition over discovery — owned by the data so every surface
@@ -18,6 +19,12 @@ export function brokenDoctors(discovered) {
 export function globalDoctorsDir() {
     return path.join(os.homedir(), ".any-doctor", "doctors");
 }
+// The bundled pack: the package's own doctors/, a sibling of bin/ wherever
+// the package lives (repo dev, node_modules, or the npx cache). Read-only
+// and lowest priority (D15) — repo-local and user-global win collisions.
+export function bundledDoctorsDir() {
+    return path.join(path.resolve(fileURLToPath(new URL("..", import.meta.url))), "doctors");
+}
 export function findRepoDoctorsDir(cwd) {
     let dir = path.resolve(cwd);
     for (;;) {
@@ -31,14 +38,22 @@ export function findRepoDoctorsDir(cwd) {
     }
 }
 export async function discoverDoctors(cwd, opts) {
-    var _a;
+    var _a, _b;
     const repoDir = findRepoDoctorsDir(cwd);
     const scopes = [
         ...(repoDir ? [{ scope: "repo", dir: repoDir }] : []),
         { scope: "global", dir: (_a = opts === null || opts === void 0 ? void 0 : opts.globalDir) !== null && _a !== void 0 ? _a : globalDoctorsDir() },
+        { scope: "bundled", dir: (_b = opts === null || opts === void 0 ? void 0 : opts.bundledDir) !== null && _b !== void 0 ? _b : bundledDoctorsDir() },
     ];
     const bySlug = new Map();
+    const seenDirs = [];
     for (const { scope, dir } of scopes) {
+        // Running inside this repo, the bundled dir IS the repo dir — scan it
+        // once, as the repo scope.
+        const resolved = path.resolve(dir);
+        if (seenDirs.includes(resolved))
+            continue;
+        seenDirs.push(resolved);
         if (!fs.existsSync(dir))
             continue;
         const files = fs.readdirSync(dir)
@@ -60,10 +75,11 @@ export async function discoverDoctors(cwd, opts) {
     return [...bySlug.values()];
 }
 // Explicit paths (absolute, or containing separators) resolve directly.
-// Bare filenames are slugs: scopes win - repo-local first - so a stray
-// slug.mjs in the working directory cannot shadow an installed doctor.
+// Bare filenames are slugs: scopes win — repo-local first, then global,
+// then bundled — so a stray slug.mjs in the working directory cannot
+// shadow an installed doctor.
 export function resolveDoctorPath(arg, cwd, opts) {
-    var _a;
+    var _a, _b;
     const bare = path.basename(arg) === arg && !path.isAbsolute(arg);
     if (!bare) {
         const direct = path.resolve(cwd, arg);
@@ -73,7 +89,11 @@ export function resolveDoctorPath(arg, cwd, opts) {
     if (bare) {
         const base = path.basename(arg);
         const repoDir = findRepoDoctorsDir(cwd);
-        const scopes = [repoDir, (_a = opts === null || opts === void 0 ? void 0 : opts.globalDir) !== null && _a !== void 0 ? _a : globalDoctorsDir()].filter((d) => Boolean(d));
+        const scopes = [
+            repoDir,
+            (_a = opts === null || opts === void 0 ? void 0 : opts.globalDir) !== null && _a !== void 0 ? _a : globalDoctorsDir(),
+            (_b = opts === null || opts === void 0 ? void 0 : opts.bundledDir) !== null && _b !== void 0 ? _b : bundledDoctorsDir(),
+        ].filter((d) => Boolean(d));
         for (const dir of scopes) {
             const candidate = path.join(dir, base);
             if (fs.existsSync(candidate))

package/bin/doctor-loader.mjs

@@ -30,7 +30,7 @@ export function confineProcess() {
         // No loader hooks on this runtime — the other confinement layers still apply.
     }
 }
-const USAGE = "usage: doctor-loader.mjs <program.(m)js> <root> | <program.(m)js> --verify <fixtures.(m)js> | <program.(m)js> --meta";
+const USAGE = "usage: doctor-loader.mjs <program.(m)js> <root> [--include-tests] | <program.(m)js> --verify <fixtures.(m)js> | <program.(m)js> --meta";
 const SEVERITIES = new Set(["error", "warning", "info"]);
 function validateMeta(mod) {
     const m = mod.meta;
@@ -48,9 +48,9 @@ function validateMeta(mod) {
         process.exit(3);
     }
 }
-function runOnce(root, mod) {
+function runOnce(root, mod, opts) {
     const started = Date.now();
-    const { ctx, getFindings } = buildCtx(root);
+    const { ctx, getFindings } = buildCtx(root, opts);
     const fileCount = ctx.files.list().length;
     const result = mod.doctor(ctx);
     if (!result || typeof result.then !== "function") {
@@ -101,7 +101,7 @@ async function main() {
             }) + "\n");
         }
         else if (mode.kind === "run") {
-            const result = await runOnce(mode.root, mod);
+            const result = await runOnce(mode.root, mod, { includeTests: contract.includeTestsFor(mode) });
             process.stdout.write("\n" + contract.RESULT_SENTINEL + JSON.stringify(result) + "\n");
         }
         else {
@@ -118,7 +118,10 @@ async function main() {
                     for (const [rel, content] of Object.entries(fixture.seed)) {
                         materializeSeed(tmp, rel, content);
                     }
-                    const result = await runOnce(tmp, mod);
+                    // Verify always lists everything (includeTestsFor): the sandbox is
+                    // the doctor's own world — a seed named *.test.ts is deliberate
+                    // test data (effect-doctor's sleep-in-test depends on it).
+                    const result = await runOnce(tmp, mod, { includeTests: contract.includeTestsFor(mode) });
                     const diff = contract.compareFindings(fixture.expected, result.findings);
                     results.push({ name: fixture.name, ok: diff.missing.length === 0 && diff.unexpected.length === 0, ...diff });
                 }

package/bin/report.d.ts

@@ -8,6 +8,7 @@ export interface RunOutcome {
     durationMs: number;
     targetDir: string;
 }
+export declare function cohortFileCount(counts: number[]): number;
 export declare function unsafeSkipLine(names: string[]): string;
 export declare function unsafeRefusalLine(name: string, capabilities: readonly string[]): string;
 export declare function dedupeGroups(groups: ReportGroup[]): {