@geonosis/doctor 1.2.0 → 1.3.0

package/README.md

@@ -13,6 +13,11 @@ npx geonosis-doctor
 Run it **after every bump** and **in CI**. It exits 1 when any line is a FAIL or an UNJUDGED — a
 question it could not ask is not a pass — and 2 when the run could not be made at all.
 
+**A directory that is not a project is a 2, not a pass.** With no `package.json` and no
+`.oxlintrc.json` anywhere under the root there is nothing here to examine, and every line it would
+print is about a gate that is not there. It used to answer `doctor PASS` at exit 0 off six SKIPs and
+three vacuous OKs — from the tool whose thesis is that a SKIP is not a pass.
+
 ```
 geonosis-doctor [--root <dir>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
 ```
@@ -50,6 +55,26 @@ npm and pnpm alike.
 A declared range this check cannot read is a **FAIL**, not a pass. A version it cannot judge is a
 refusal.
 
+## The options a rule actually runs under
+
+Every reader here that consumes a rule's configuration reads `overrides[]` as well as `rules`, and
+resolves them the way oxlint does — **measured**, not assumed, against oxlint 1.80:
+
+- an override entry naming a rule again **replaces** its options for the files its `files` globs
+  claim; nothing is deep-merged into the base;
+- when several overrides claim one file, the **last** of them wins outright;
+- a rule an override names and the base block never mentions is **enabled**, on those files.
+
+Reading `rules` alone is one config with two answers. dielime registers its Medusa providers from
+three files — a base `medusa-config.ts` and two carrier registries — and declares that exactly
+where oxlint reads it, in overrides naming the carrier directories. The rule resolved it; `drift`
+read the base object and reported two working carriers as directories the registry "never names";
+`exercised` would have called a rule enabled only in an override "not enabled here" and skipped it.
+
+The glob subset understood is `**` across segments, `*` and `?` within one, and `{a,b}`; a pattern
+with no separator matches a basename anywhere. Like `pathMatching` in the rule plugin, it is a
+subset that says so rather than a dependency that would have to be right about everything.
+
 ### `exercised` — enabled ≠ exercised
 
 A rule at `"error"` over a tree with no violation of it, and a rule at `"error"` that can never
@@ -111,10 +136,14 @@ probe derives its path from the option, never from a fixed corpus location, and
 `lib/probe.ts`'s `pathMatching` builds one back out of the regex and then tests it against that
 regex, refusing with a sentence rather than placing a file the rule will never look at.
 
-One rule cannot be probed by a single file and says so: `no-unregistered-plugin-dir` reports a
-directory its registry does not name and reads that registry off disk, so the probe fires only when
-the configured registry is also in the tree. Widening it until it fired would be the rule claiming
-evidence it does not have, which is the defect the rule itself is about.
+A probe declares FILES, not a file. `no-unregistered-plugin-dir` reports a directory its registry
+does not name and reads that registry off disk, returning silently when it is not there — so one
+file could never exercise it, and dielime, enforcing it at error over four registries, read as a
+permanent FAIL for a gate that was working. Its probe now declares the directory AND the registry,
+and every file a probe declares is mounted into the copy. A probe declaring only `{ path, source }`
+is the one-file case of the same thing and is read unchanged, which matters: this reads probes off
+the plugin build the consumer has INSTALLED, and every build published before this shape existed
+answers in the bare form.
 
 #### The corpus a shipped one cannot be
 
@@ -172,6 +201,10 @@ naming bun. It used to be warned with vitest's sentence — eight lines of it in
 report, each blaming a runner the check had not read, which is how a reader learns to skim the
 section and miss the vitest lines beside them that are true.
 
+A workspace whose test script runs a runner over **zero test files** is a SKIP, not a warning:
+dielime's `packages/eslint-config` runs `vitest run` and has no test file under it, so there is no
+result for an exit code to be wrong about. The message says what was counted.
+
 The message names the runner it read. What it does not do is see through a wrapper: a script that
 runs `bun ./scripts/vitest-strict.ts` reads as neither, and that consumer's wrapper is in fact the
 exemplary fix — it spawns vitest with `--reporter=json`, reads the report, and fails on a missing
@@ -185,10 +218,39 @@ The other four ask whether a gate measures what it names. This one asks whether
 |---|---|---|
 | `.github/workflows/*.yml` | FAIL | a job or step switched off by a condition that can never be true. One consumer carried 90 tests, a pgvector container and an E2E suite and ran none of it, the disablement documented as "TEMPORARY" in a comment. It is "never downgrade a rule", one level up |
 | test files | FAIL | a `*.test.*` file with no `test` script in any workspace from it up to the root. A monorepo that runs one vitest over the whole tree has no orphan in it, and this says so |
+| script paths | FAIL | a `scripts` entry that hands `bun`, `node` or `tsx` a file that is not on disk. during.day's `bun run fast` began `bun scripts/check-plugin-version.ts && …` and the script had been deleted: the 2.5 s gate had failed at its first command for as long as nobody looked. Only a word with a file extension is asked about, so `bun test`, `bun run lint` and `node --version` are not paths |
+| generated files | FAIL | a file carrying `geonosis:gated-by: <gate>` that nothing here runs the gate for — checked against every manifest script, every ratchet counter command and every workflow, because what matters is that SOMETHING runs it. A file that names its **writer** and no gate at all fails on that alone: during.day's AGENTS.md is a 1,117-line byte-copy of its own law, written by `geonosis sync`, and nothing ever ran `sync --check` — the doctor stood beside it warning about the shorter original |
+| `NODE_OPTIONS` | WARN | a manifest script preloading through `NODE_OPTIONS` beside a ratchet counter whose command shells to `pnpm`. The nested pnpm inherits the option: dielime's ts5 shim sent it looking for a `.pnpmfile.mjs` that is not there, the counter died, the ratchet refused correctly, and nothing in the message was near the cause. Both halves must be present, and the line names the script and the counter |
+| workspace bins | FAIL | a script calling a bin THIS repo's own workspaces declare, with no `node_modules/.bin/<name>` at the root. pnpm links a workspace bin only for the packages that depend on it: dielime's `@dielime/gate-tools` had to become an explicit root devDependency before the gate scripts could find it, and naming that took a debugging session. External commands are not judged — that would be a guess |
 | plugin directories | FAIL | a manifest directory under the roots `no-unregistered-plugin-dir` names that the registry never mentions. SKIP when the rule is not configured — the roots are the repo's, read from the rule it already wrote, never a list invented here |
-| the law | WARN | its measured length against `geonosis.json` → `law.maxLines` (200 by default). dielime is 382, during.day 1,104 |
-| `.claude/settings.json` | WARN | nothing installs the kit's plugin, so the gates run and the method does not (D-041) |
-| `geonosis.json` blocks | WARN | a block whose package is not installed — nothing reads it — or an installed package with no block, running on defaults nobody chose |
+| `publicHoistPattern` | FAIL / SKIP | a pattern in `pnpm-workspace.yaml` with no root `node_modules` link for a workspace package it matches. pnpm dropped one during an **unrelated** `add`, then answered "Already up to date" to every install afterwards over a clean `git status` — the tree was fixed only by deleting `.modules.yaml` and `.pnpm-workspace-state-v1.json`, which the line carries verbatim. Only workspace packages are judged, because one exists on disk by construction and a missing link for it cannot be "the install never ran"; the root package is never asked about, since no package manager puts a repo's root inside its own `node_modules`. A pattern matching no workspace package is SKIP, never a pass |
+| the law | WARN / SKIP | its measured length against `geonosis.json` → `law.maxLines`. **SKIP when the repo declares no ceiling** — during.day read "1,104 lines against a ceiling of 200" for a number it never chose, which is unactionable in both directions. The length is still printed, because that is the number a repo declares against |
+| `.claude/settings.json` | WARN | nothing under `enabledPlugins` enables the kit's plugin, so the gates run and the method does not (D-041). The **user-scope** `~/.claude/settings.json` is read too and acknowledged as "installed elsewhere — not this repo's to declare": both source repos got this WARN while the plugin was installed machine-wide. The key is read, never the word `geonosis` appearing somewhere in the file |
+| `geonosis.json` blocks | WARN | a block whose package **no manifest declares** — nothing reads it, and a stale `node_modules` copy is named as what a previous install left behind; a block whose package is declared and does not resolve — run the install; or a **declared** package with no block, running on defaults nobody chose |
+
+The two directions do not read the same source. Whether a repo still *chose* a package is a question
+for the **manifests**: a `release` block whose package had been removed from every manifest, with a
+stale `node_modules` directory still present, resolved perfectly and the check said nothing (#78).
+Whether a tool will actually load is the forward question, and that one is resolution's.
+
+The "installed with no block" direction is scoped to **direct** dependencies. `@geonosis/review` and
+`@geonosis/testbed` arrive transitively through `@geonosis/cli`, and asking a consumer to configure
+a package they never installed is noise — which is how a reader learns to skip the section (#61). A
+transitive presence gets an OK line naming where it came from, and no demand.
+
+#### A geonosis bin a git hook cannot start
+
+Every committed hook — `lefthook.yml`, `.husky/*`, `.githooks/*` — is read, and a line running a
+geonosis bin through `pnpm`, `npx`, `bunx` or `yarn` is a **FAIL** naming the direct call that
+replaces it.
+
+A git hook's PATH is not the shell's: no nvm shim, no corepack shim, nothing a version manager put
+there. dielime's first hooked commit was "refused" on 2026-08-30 and the ledger never ran — `pnpm`
+was not found, and the sentence its author read was a version manager's failure wearing a gate's
+refusal costume. That is the worst shape a gate has, because it is indistinguishable from the gate
+working. `node_modules/.bin/<bin>` is linked by every package manager and needs nothing on PATH.
+
+A hook file naming no geonosis bin is a **SKIP** with the sentence, never a vacuous OK.
 
 ### `observability` — a sink nobody can reach
 

package/dist/{chunk-ZJCUTDQW.js → chunk-7BRGHYQR.js}

@@ -23,19 +23,28 @@ var walk = (dir, onFile) => {
   }
 };
 var parse = (path) => JSON.parse(readFileSync(path, "utf8"));
+var stringsOf = (value) => Array.isArray(value) ? value.filter((one) => typeof one === "string") : [];
+var rulesOf = (value) => typeof value === "object" && value !== null ? value : {};
+var overridesOf = (value) => Array.isArray(value) ? value.filter((one) => typeof one === "object" && one !== null).map((one) => ({ files: stringsOf(one.files), rules: rulesOf(one.rules) })) : [];
 var readConfig = (path, root) => {
   const dir = join(path, "..");
   const relative = relativePath(root, path);
   try {
     const config = parse(path);
-    const jsPlugins = Array.isArray(config.jsPlugins) ? config.jsPlugins.filter((one) => typeof one === "string") : [];
-    const rules = typeof config.rules === "object" && config.rules !== null ? config.rules : {};
-    return { dir, jsPlugins, path, relative, rules };
+    return {
+      dir,
+      jsPlugins: stringsOf(config.jsPlugins),
+      overrides: overridesOf(config.overrides),
+      path,
+      relative,
+      rules: rulesOf(config.rules)
+    };
   } catch (error) {
     return {
       dir,
       error: `could not read it: ${error.message}`,
       jsPlugins: [],
+      overrides: [],
       path,
       relative,
       rules: {}
@@ -63,6 +72,14 @@ var discoverWorkspaces = (root) => {
   });
   return found.toSorted((a, b) => a.relative.localeCompare(b.relative));
 };
+var TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+var testFilesUnder = (dir) => {
+  const found = [];
+  walk(dir, (path, name) => {
+    if (TEST_FILE.test(name)) found.push(path);
+  });
+  return found;
+};
 var readRatchet = (root) => {
   const path = join(root, RATCHET_FILE);
   try {
@@ -324,7 +341,28 @@ import { existsSync as existsSync2, readFileSync as readFileSync3, realpathSync
 import { createRequire } from "module";
 import { dirname, join as join3 } from "path";
 import { pathToFileURL } from "url";
-var resolveFrom = (dir, specifier) => createRequire(join3(dir, "noop.js")).resolve(specifier);
+var packageNameOf = (specifier) => {
+  const parts2 = specifier.split("/");
+  return specifier.startsWith("@") ? parts2.slice(0, 2).join("/") : parts2[0] ?? specifier;
+};
+var resolveFrom = (dir, specifier) => {
+  if (specifier.startsWith(".") || specifier.startsWith("/")) {
+    return createRequire(join3(dir, "noop.js")).resolve(specifier);
+  }
+  const name = packageNameOf(specifier);
+  let at = dir;
+  for (; ; ) {
+    if (existsSync2(join3(at, "node_modules", name, "package.json"))) {
+      return createRequire(join3(at, "noop.js")).resolve(specifier);
+    }
+    const parent = dirname(at);
+    if (parent === at) break;
+    at = parent;
+  }
+  throw new DoctorError(
+    `${specifier} does not resolve from ${dir} \u2014 no node_modules on the way up carries ${name}`
+  );
+};
 var packageDirOf = (entry, name) => {
   let dir = dirname(entry);
   for (; ; ) {
@@ -353,13 +391,17 @@ var pluginVersionOf = async (entry) => {
   }
   return version;
 };
+var filesOf = (answer) => Array.isArray(answer.files) ? answer.files : [answer];
 var probesOf = async (entry, plugin) => {
   const loaded = await import(pathToFileURL(entry).href);
   return Object.fromEntries(
-    Object.entries(loaded.default?.rules ?? {}).filter(([, rule]) => typeof rule?.probe === "function").map(([name, rule]) => [
-      `${plugin}/${name}`,
-      rule.probe
-    ])
+    Object.entries(loaded.default?.rules ?? {}).filter(([, rule]) => typeof rule?.probe === "function").map(([name, rule]) => {
+      const declared = rule.probe;
+      return [
+        `${plugin}/${name}`,
+        (options) => filesOf(declared(options))
+      ];
+    })
   );
 };
 var corpusOfPlugin = (from, specifier) => join3(packageDirOf(resolveFrom(from, specifier), specifier), "corpus");
@@ -373,15 +415,80 @@ var real = (path) => {
 var relativeToRoot = (root, path) => relativePath(real(root), real(path));
 
 // src/drift.ts
-import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
+import { closeSync, existsSync as existsSync3, openSync, readdirSync as readdirSync2, readFileSync as readFileSync4, readSync } from "fs";
+import { homedir } from "os";
 import { join as join4, sep as sep2 } from "path";
+
+// src/overrides.ts
+var SPECIAL = /* @__PURE__ */ new Set(["$", "(", ")", "+", ".", "/", "@", "\\", "^", "|"]);
+var globToRegExp = (glob) => {
+  let source = "";
+  for (let at = 0; at < glob.length; at += 1) {
+    const character = glob[at] ?? "";
+    if (character === "*") {
+      if (glob[at + 1] === "*") {
+        if (glob[at + 2] === "/") {
+          source += "(?:[^/]*/)*";
+          at += 2;
+        } else {
+          source += ".*";
+          at += 1;
+        }
+      } else {
+        source += "[^/]*";
+      }
+      continue;
+    }
+    if (character === "?") {
+      source += "[^/]";
+      continue;
+    }
+    if (character === "{") {
+      source += "(?:";
+      continue;
+    }
+    if (character === "}") {
+      source += ")";
+      continue;
+    }
+    if (character === ",") {
+      source += "|";
+      continue;
+    }
+    source += SPECIAL.has(character) ? `\\${character}` : character;
+  }
+  return new RegExp(`^${source}$`);
+};
+var matchesGlob = (glob, path) => {
+  const here = globToRegExp(glob);
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  return here.test(path) || !glob.includes("/") && here.test(name);
+};
+var layersOf = (config, rule) => {
+  const layers = [];
+  if (rule in config.rules) layers.push({ files: [], level: config.rules[rule] });
+  for (const override of config.overrides ?? []) {
+    if (rule in override.rules) layers.push({ files: override.files, level: override.rules[rule] });
+  }
+  return layers;
+};
+var governing = (layers, path) => {
+  let found;
+  for (const layer of layers) {
+    if (layer.files.length === 0 || layer.files.some((glob) => matchesGlob(glob, path))) {
+      found = layer;
+    }
+  }
+  return found;
+};
+
+// src/drift.ts
 var WORKFLOWS = ".github/workflows";
 var SETTINGS = ".claude/settings.json";
 var GEONOSIS = "geonosis.json";
 var LAW = "CLAUDE.md";
 var CEILING = 200;
 var SWITCHED_OFF = /^\s*if:\s*(?:\$\{\{\s*)?false\b/m;
-var TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
 var finding3 = (subject, verdict, message) => ({
   check: "drift",
   message,
@@ -427,7 +534,7 @@ var holds = (parent, child) => child === parent || child.startsWith(`${parent}${
 var ownersOf = (path, workspaces) => workspaces.filter((one) => holds(one.dir, path)).toSorted((a, b) => b.dir.length - a.dir.length);
 var orphanTests = (root, workspaces) => {
   const orphaned = /* @__PURE__ */ new Map();
-  for (const path of filesUnder(root, (name) => TEST_FILE.test(name))) {
+  for (const path of testFilesUnder(root)) {
     const owners = ownersOf(path, workspaces);
     if (owners.some((one) => typeof one.manifest.scripts?.test === "string")) continue;
     const owner = owners[0];
@@ -446,6 +553,170 @@ var orphanTests = (root, workspaces) => {
     )
   );
 };
+var RUNS_A_FILE = /* @__PURE__ */ new Set(["bun", "node", "tsx"]);
+var BETWEEN_COMMANDS = /(?:&&|\|\||[;|&()])/;
+var NAMES_A_FILE = /\.[cm]?[jt]sx?$/;
+var SHELL_WOULD_REWRITE = /[$*?{}]/;
+var pathRunBy = (segment) => {
+  const words = segment.trim().split(/\s+/).filter((word) => word !== "");
+  for (const [index, word] of words.entries()) {
+    if (!RUNS_A_FILE.has(word)) continue;
+    const argument = words.slice(index + 1).find((one) => !one.startsWith("-"));
+    if (argument === void 0 || SHELL_WOULD_REWRITE.test(argument)) continue;
+    if (NAMES_A_FILE.test(argument)) return argument;
+  }
+  return void 0;
+};
+var pathsRunByScript = (script) => script.split(BETWEEN_COMMANDS).map(pathRunBy).filter((one) => one !== void 0);
+var scriptPaths = (workspaces) => {
+  const missing = workspaces.flatMap(
+    (one) => Object.entries(one.manifest.scripts ?? {}).flatMap(
+      ([name, script]) => pathsRunByScript(script).filter((path) => !existsSync3(join4(one.dir, path))).map((path) => ({ name, path, workspace: one }))
+    )
+  );
+  if (missing.length === 0) {
+    return [
+      finding3("script paths", "OK", "every file a script hands to bun, node or tsx is on disk")
+    ];
+  }
+  return missing.map(
+    ({ name, path, workspace }) => finding3(
+      workspace.relative === "" ? "package.json" : `${workspace.relative}/package.json`,
+      "FAIL",
+      `the "${name}" script runs ${path} and there is no such file \u2014 this script fails at that command, and every gate that calls it has been running nothing since the file went`
+    )
+  );
+};
+var workspaceBins = (workspaces) => {
+  const found = /* @__PURE__ */ new Map();
+  for (const one of workspaces) {
+    const declared = one.manifest.bin;
+    if (typeof declared === "string") {
+      const name = one.manifest.name;
+      if (name !== void 0) found.set(name.replace(/^@[^/]+\//, ""), one);
+      continue;
+    }
+    for (const name of Object.keys(declared ?? {})) found.set(name, one);
+  }
+  return found;
+};
+var linkedBins = (root, workspaces) => {
+  const bins = workspaceBins(workspaces);
+  if (bins.size === 0) {
+    return [finding3("workspace bins", "SKIP", "no workspace here declares a bin")];
+  }
+  const missing = workspaces.flatMap(
+    (one) => Object.entries(one.manifest.scripts ?? {}).flatMap(
+      ([script, body]) => [...new Set(body.split(/[\s;|&()]+/).filter((word) => bins.has(word)))].filter((name) => !existsSync3(join4(root, "node_modules/.bin", name))).map((name) => ({ name, script, workspace: one }))
+    )
+  );
+  if (missing.length === 0) {
+    return [
+      finding3(
+        "workspace bins",
+        "OK",
+        "every workspace bin a script names is linked under the root"
+      )
+    ];
+  }
+  return missing.map(
+    ({ name, script, workspace }) => finding3(
+      name,
+      "FAIL",
+      `the "${script}" script in ${workspace.relative === "" ? "package.json" : `${workspace.relative}/package.json`} calls it, ${bins.get(name)?.manifest.name ?? "a workspace"} declares it, and node_modules/.bin/${name} is not there \u2014 add that package as a dependency of the one whose script calls it, so the package manager links the bin`
+    )
+  );
+};
+var SHELLS_TO_PNPM = /(?:^|[\s;&|(])pnpm(?:\s|$)/;
+var NODE_OPTIONS = /(?:^|[\s;&|(])NODE_OPTIONS=/;
+var preloadAroundPnpm = (root, workspaces) => {
+  const counters = (readRatchet(root)?.counters ?? []).filter(
+    (entry) => typeof entry.command === "string" && SHELLS_TO_PNPM.test(entry.command)
+  );
+  if (counters.length === 0) return [];
+  const scripts = workspaces.flatMap(
+    (one) => Object.entries(one.manifest.scripts ?? {}).filter(([, body]) => NODE_OPTIONS.test(body)).map(([name]) => one.relative === "" ? name : `${one.relative}:${name}`)
+  );
+  if (scripts.length === 0) return [];
+  const named2 = counters.map((entry) => typeof entry.key === "string" ? entry.key : String(entry.counter)).join(", ");
+  const some = scripts.slice(0, 3).join(", ");
+  const rest = scripts.length > 3 ? ` and ${scripts.length - 3} more` : "";
+  return [
+    finding3(
+      "NODE_OPTIONS",
+      "WARN",
+      `${scripts.length} script(s) preload something through NODE_OPTIONS (${some}${rest}), and the "${named2}" counter(s) shell out to pnpm \u2014 a nested pnpm INHERITS the option and dies on it (a preloaded resolver patch sends it looking for a .pnpmfile.mjs that is not there). Run the ratchet outside those scripts, or unset NODE_OPTIONS for the nested call: env -u NODE_OPTIONS pnpm \u2026`
+    )
+  ];
+};
+var GATED_BY = /geonosis:gated-by:\s*(.+?)\s*(?:-->|\*\/|$)/m;
+var GENERATED_BY = /Generated by\s+`([^`]+)`/m;
+var CAN_CARRY_A_MARKER = /\.(?:mdc?|markdown|ya?ml|toml|[cm]?[jt]sx?|json[c5]?|txt|sh|mjs|cjs)$/i;
+var HEAD_BYTES = 4096;
+var markerIn = (path) => {
+  let handle;
+  try {
+    handle = openSync(path, "r");
+  } catch {
+    return void 0;
+  }
+  try {
+    const buffer = Buffer.alloc(HEAD_BYTES);
+    const read = readSync(handle, buffer, 0, HEAD_BYTES, 0);
+    const head = buffer.toString("utf8", 0, read);
+    const gate = GATED_BY.exec(head)?.[1];
+    if (gate !== void 0) return { gate };
+    const writer = GENERATED_BY.exec(head)?.[1];
+    return writer === void 0 ? void 0 : { writer };
+  } catch {
+    return void 0;
+  } finally {
+    closeSync(handle);
+  }
+};
+var everythingRun = (root, workspaces) => {
+  const scripts = workspaces.flatMap((one) => Object.values(one.manifest.scripts ?? {}));
+  const counters = (readRatchet(root)?.counters ?? []).map((entry) => String(entry.command ?? ""));
+  const workflows = filesUnder(
+    join4(root, WORKFLOWS),
+    (name) => name.endsWith(".yml") || name.endsWith(".yaml")
+  ).map((path) => {
+    try {
+      return readFileSync4(path, "utf8");
+    } catch {
+      return "";
+    }
+  });
+  return [...scripts, ...counters, ...workflows].join("\n");
+};
+var generatedFiles = (root, workspaces) => {
+  const marked = filesUnder(root, (name) => CAN_CARRY_A_MARKER.test(name)).map((path) => ({ marker: markerIn(path), path })).filter((one) => one.marker !== void 0);
+  if (marked.length === 0) {
+    return [
+      finding3(
+        "generated files",
+        "SKIP",
+        "nothing here says it was generated, so there is no write half here to look for a read half of"
+      )
+    ];
+  }
+  const run = everythingRun(root, workspaces);
+  return marked.map(({ marker, path }) => {
+    const at = relativePath(root, path);
+    if (!("gate" in marker)) {
+      return finding3(
+        at,
+        "FAIL",
+        `generated by \`${marker.writer}\` and it names no gate that reads it back. A written file no check reads is the write half of an instrument with no read half: it can drift from its source for ever and every gate stays green. Re-run \`${marker.writer}\` on a version that writes the \`geonosis:gated-by:\` marker, and run the gate it names`
+      );
+    }
+    return run.includes(marker.gate) ? finding3(at, "OK", `generated, and \`${marker.gate}\` reads it back`) : finding3(
+      at,
+      "FAIL",
+      `generated, and nothing here runs \`${marker.gate}\` \u2014 the gate it names. A written file no check reads is the write half of an instrument with no read half: it can drift from its source for ever and every gate stays green. Add \`${marker.gate}\` to a script, a counter or a workflow`
+    );
+  });
+};
 var readGeonosis = (root) => {
   const path = join4(root, GEONOSIS);
   if (!existsSync3(path)) return void 0;
@@ -458,13 +729,22 @@ var readGeonosis = (root) => {
 var law = (root, config) => {
   const declared = config?.law ?? {};
   const file = typeof declared.file === "string" ? declared.file : LAW;
-  const ceiling = typeof declared.maxLines === "number" ? declared.maxLines : CEILING;
   const path = join4(root, file);
   if (!existsSync3(path)) {
     return [finding3(file, "SKIP", "there is no law file here to measure")];
   }
   const source = readFileSync4(path, "utf8");
   const lines = source.split("\n").length - (source.endsWith("\n") ? 1 : 0);
+  if (typeof declared.maxLines !== "number") {
+    return [
+      finding3(
+        file,
+        "SKIP",
+        `${lines} lines, and no ceiling to measure them against \u2014 set law.maxLines in geonosis.json to have this asked (${CEILING} is what both source repos converged on)`
+      )
+    ];
+  }
+  const ceiling = declared.maxLines;
   return [
     lines > ceiling ? finding3(
       file,
@@ -473,20 +753,40 @@ var law = (root, config) => {
     ) : finding3(file, "OK", `${lines} lines, under the ceiling of ${ceiling}`)
   ];
 };
-var hooks = (root) => {
+var KIT_PLUGIN = "geonosis";
+var enablesKit = (path) => {
+  if (!existsSync3(path)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    const enabled = parsed.enabledPlugins;
+    if (typeof enabled !== "object" || enabled === null) return false;
+    return Object.entries(enabled).some(
+      ([id, on]) => on !== false && id.split("@")[0] === KIT_PLUGIN
+    );
+  } catch {
+    return false;
+  }
+};
+var hooks = (root, userSettings) => {
   const path = join4(root, SETTINGS);
-  if (!existsSync3(path)) {
+  if (enablesKit(path)) {
+    return [finding3(SETTINGS, "OK", `\`enabledPlugins\` here enables the kit\u2019s plugin`)];
+  }
+  if (enablesKit(userSettings)) {
     return [
       finding3(
         SETTINGS,
-        "WARN",
-        "nothing here installs the kit\u2019s plugin, so none of the hooks, agents or skills reach this repo \u2014 the gates run, the method does not"
+        "OK",
+        `installed elsewhere \u2014 not this repo\u2019s to declare: \`enabledPlugins\` in ${userSettings} enables it for every repo on this machine`
       )
     ];
   }
-  const source = readFileSync4(path, "utf8");
   return [
-    source.includes("geonosis") ? finding3(SETTINGS, "OK", "it installs the kit\u2019s plugin") : finding3(SETTINGS, "WARN", "it names no geonosis plugin or marketplace")
+    finding3(
+      SETTINGS,
+      "WARN",
+      `nothing enables the kit\u2019s plugin, so none of the hooks, agents or skills reach this repo \u2014 the gates run, the method does not. What satisfies this: a "geonosis@<marketplace>" entry under \`enabledPlugins\` in ${SETTINGS} here, or the same in the user-scope ${userSettings}`
+    )
   ];
 };
 var READERS = {
@@ -504,7 +804,17 @@ var resolves = (root, name) => {
     return false;
   }
 };
-var blocks = (root, config, readers) => {
+var declaredAnywhere = (workspaces) => new Set(
+  workspaces.flatMap(
+    (one) => [
+      one.manifest.dependencies,
+      one.manifest.devDependencies,
+      one.manifest.optionalDependencies,
+      one.manifest.peerDependencies
+    ].flatMap((field) => Object.keys(field ?? {}))
+  )
+);
+var blocks = (root, config, readers, workspaces) => {
   if (config === void 0) {
     return [
       finding3(
@@ -514,19 +824,30 @@ var blocks = (root, config, readers) => {
       )
     ];
   }
+  const declaredPackages = declaredAnywhere(workspaces);
   return Object.entries(readers).flatMap(([block, name]) => {
     const declared = config[block] !== void 0;
+    const chosen = declaredPackages.has(name);
     const installed = resolves(root, name);
+    if (declared && !chosen) {
+      return [
+        finding3(
+          name,
+          "WARN",
+          `geonosis.json has a "${block}" block and no manifest here declares ${name} \u2014 nothing reads it${installed ? ", and the copy still under node_modules is what a stale install left behind" : ""}`
+        )
+      ];
+    }
     if (declared && !installed) {
       return [
         finding3(
           name,
           "WARN",
-          `geonosis.json has a "${block}" block and ${name} is not installed here \u2014 nothing reads it`
+          `geonosis.json has a "${block}" block, a manifest declares ${name}, and it does not resolve here \u2014 run the install`
         )
       ];
     }
-    if (!declared && installed) {
+    if (!declared && chosen && installed) {
       return [
         finding3(
           name,
@@ -535,29 +856,54 @@ var blocks = (root, config, readers) => {
         )
       ];
     }
+    if (!declared && installed) {
+      return [
+        finding3(
+          name,
+          "OK",
+          `${name} is here but no manifest declares it \u2014 a transitive dependency this repo did not choose, so it wants no "${block}" block`
+        )
+      ];
+    }
     return declared ? [finding3(name, "OK", `a "${block}" block, and ${name} to read it`)] : [];
   });
 };
-var pluginDirsConfigured = (root) => {
+var PLUGIN_DIR_RULE = "biological-architecture/no-unregistered-plugin-dir";
+var registryList = (value) => {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((one) => typeof one === "string")) return value;
+  return void 0;
+};
+var pluginDirsOf = (level) => {
+  const options = Array.isArray(level) ? level[1] : void 0;
+  const registry = registryList(options?.registry);
+  if (options?.roots === void 0 || registry === void 0) return void 0;
+  return { manifests: options.manifests ?? ["index.ts"], registry, roots: options.roots };
+};
+var pluginDirLayers = (root) => {
   const path = join4(root, ".oxlintrc.json");
-  if (!existsSync3(path)) return void 0;
-  try {
-    const parsed = JSON.parse(readFileSync4(path, "utf8"));
-    const rule = parsed.rules?.["biological-architecture/no-unregistered-plugin-dir"];
-    const options = Array.isArray(rule) ? rule[1] : void 0;
-    if (options?.roots === void 0 || typeof options.registry !== "string") return void 0;
-    return {
-      manifests: options.manifests ?? ["index.ts"],
-      registry: options.registry,
-      roots: options.roots
-    };
-  } catch {
-    return void 0;
+  if (!existsSync3(path)) return [];
+  const layers = [];
+  for (const layer of layersOf(readConfig(path, root), PLUGIN_DIR_RULE)) {
+    const dirs = pluginDirsOf(layer.level);
+    if (dirs !== void 0) layers.push({ dirs, files: layer.files });
   }
+  return layers;
+};
+var layerOver = (layers, root, relative) => {
+  const at = join4(root, relative);
+  const inside = readdirSync2(at, { withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => `${relative}/${entry.name}`);
+  const paths = inside.length === 0 ? [relative] : inside;
+  const wrapped = layers.map((layer) => ({ files: layer.files, level: layer.dirs }));
+  for (const path of paths) {
+    const found = governing(wrapped, path);
+    if (found !== void 0) return found.level;
+  }
+  return void 0;
 };
 var pluginDirs = (root) => {
-  const configured = pluginDirsConfigured(root);
-  if (configured === void 0) {
+  const layers = pluginDirLayers(root);
+  if (layers.length === 0) {
     return [
       finding3(
         "plugin directories",
@@ -566,50 +912,180 @@ var pluginDirs = (root) => {
       )
     ];
   }
-  const registryPath = join4(root, configured.registry);
-  if (!existsSync3(registryPath)) {
-    return [finding3(configured.registry, "FAIL", "the registry the rule names is not there")];
+  const missing = [...new Set(layers.flatMap((layer) => layer.dirs.registry))].filter(
+    (registry) => !existsSync3(join4(root, registry))
+  );
+  if (missing.length > 0) {
+    return missing.map(
+      (registry) => finding3(registry, "FAIL", "the registry the rule names is not there")
+    );
   }
-  const registry = readFileSync4(registryPath, "utf8");
-  const unreachable = [];
-  for (const rootDir of configured.roots) {
+  const source = /* @__PURE__ */ new Map();
+  const unreachable = /* @__PURE__ */ new Map();
+  for (const rootDir of new Set(layers.flatMap((layer) => layer.dirs.roots))) {
     const at = join4(root, rootDir);
     if (!existsSync3(at)) continue;
     for (const entry of readdirSync2(at, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
-      const hasManifest = configured.manifests.some(
-        (name) => existsSync3(join4(at, entry.name, name))
+      const relative = `${rootDir}/${entry.name}`;
+      const governs = layerOver(layers, root, relative);
+      if (governs === void 0) continue;
+      const key = governs.registry.join(", ");
+      const registry = source.get(key) ?? governs.registry.map((half) => readFileSync4(join4(root, half), "utf8")).join("\n");
+      source.set(key, registry);
+      const hasManifest = governs.manifests.some((name) => existsSync3(join4(at, entry.name, name)));
+      if (!hasManifest || registry.includes(entry.name)) continue;
+      unreachable.set(key, [...unreachable.get(key) ?? [], relative]);
+    }
+  }
+  return [...source.keys()].toSorted().map((registry) => {
+    const named2 = unreachable.get(registry) ?? [];
+    return named2.length === 0 ? finding3(registry, "OK", "every directory under the declared roots is named by it") : finding3(
+      registry,
+      "FAIL",
+      `${named2.length} directory(ies) it never names: ${named2.join(", ")}`
+    );
+  });
+};
+var WORKSPACE_YAML = "pnpm-workspace.yaml";
+var HOIST_KEY = "publicHoistPattern";
+var HOIST_REPAIR = "rm -rf node_modules/.modules.yaml node_modules/.pnpm-workspace-state-v1.json && pnpm install";
+var hoistPatterns = (root) => {
+  const path = join4(root, WORKSPACE_YAML);
+  if (!existsSync3(path)) return void 0;
+  const lines = readFileSync4(path, "utf8").split("\n");
+  const at = lines.findIndex((line) => new RegExp(`^${HOIST_KEY}\\s*:`).test(line));
+  if (at < 0) return void 0;
+  const patterns = [];
+  for (const line of lines.slice(at + 1)) {
+    if (/^\s*(?:#.*)?$/.test(line)) continue;
+    const item = /^\s+-\s*(.+?)\s*$/.exec(line);
+    if (item?.[1] === void 0) break;
+    patterns.push(item[1].replace(/^['"]|['"]$/g, ""));
+  }
+  return patterns;
+};
+var matching = (pattern) => new RegExp(`^${pattern.replaceAll(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*")}$`);
+var publicHoists = (root, workspaces) => {
+  const patterns = hoistPatterns(root);
+  if (patterns === void 0) {
+    return [
+      finding3(
+        WORKSPACE_YAML,
+        "SKIP",
+        `no ${HOIST_KEY} is declared here, so nothing claims a package should be linked at the root`
+      )
+    ];
+  }
+  const named2 = workspaces.flatMap(
+    (one) => one.dir === root || one.manifest.name === void 0 ? [] : [one.manifest.name]
+  );
+  return patterns.map((pattern) => {
+    const shape = matching(pattern);
+    const hoisted = named2.filter((name) => shape.test(name));
+    if (hoisted.length === 0) {
+      return finding3(
+        pattern,
+        "SKIP",
+        `this ${HOIST_KEY} matches no workspace package here, so what it should have linked at the root is a question this cannot answer`
+      );
+    }
+    const pruned = hoisted.filter((name) => !existsSync3(join4(root, "node_modules", name)));
+    if (pruned.length === 0) {
+      return finding3(
+        pattern,
+        "OK",
+        `every workspace package this ${HOIST_KEY} matches is linked at the root`
       );
-      if (hasManifest && !registry.includes(entry.name)) {
-        unreachable.push(`${rootDir}/${entry.name}`);
+    }
+    return finding3(
+      pattern,
+      "FAIL",
+      `the ${HOIST_KEY} \`${pattern}\` has no root link for ${pruned.map((name) => `node_modules/${name}`).join(", ")} \u2014 pnpm prunes one during an unrelated add and then answers "Already up to date" over a clean git status forever. Repair: ${HOIST_REPAIR}`
+    );
+  });
+};
+var HOOK_FILES = ["lefthook.yml", "lefthook.yaml", ".lefthook.yml", ".lefthook.yaml"];
+var HOOK_DIRS = [".husky", ".githooks"];
+var VERSION_MANAGED = /(?:^|[\s;&|(])(?<runner>pnpm|npx|bunx|yarn)\b(?:\s+(?:exec|run|dlx|x))?\s+(?<bin>geonosis(?:-[a-z-]+)?)\b/;
+var NAMES_A_BIN = /(?:^|[\s;&|(/])geonosis(?:-[a-z-]+)?\b/;
+var hookLines = (root) => {
+  const found = [];
+  const read = (path) => {
+    const at = relativePath(root, path);
+    for (const line of readFileSync4(path, "utf8").split("\n")) {
+      if (line.trim() !== "") found.push({ at, line });
+    }
+  };
+  for (const name of HOOK_FILES) {
+    const path = join4(root, name);
+    if (existsSync3(path)) read(path);
+  }
+  for (const name of HOOK_DIRS) {
+    const dir = join4(root, name);
+    if (!existsSync3(dir)) continue;
+    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+      if (entry.isFile() && !entry.name.startsWith("_") && !entry.name.startsWith(".")) {
+        read(join4(dir, entry.name));
       }
     }
   }
-  return [
-    unreachable.length === 0 ? finding3(
-      configured.registry,
-      "OK",
-      "every directory under the declared roots is named by it"
-    ) : finding3(
-      configured.registry,
-      "FAIL",
-      `${unreachable.length} directory(ies) it never names: ${unreachable.join(", ")}`
-    )
-  ];
+  return found;
+};
+var gitHooks = (root) => {
+  const lines = hookLines(root);
+  if (lines.length === 0) {
+    return [finding3("git hooks", "SKIP", "no lefthook, husky or .githooks file here to read")];
+  }
+  const files = [...new Set(lines.map((one) => one.at))].toSorted();
+  return files.flatMap((at) => {
+    const here = lines.filter((one) => one.at === at);
+    const named2 = here.filter((one) => NAMES_A_BIN.test(one.line));
+    if (named2.length === 0) {
+      return [finding3(at, "SKIP", "it names no geonosis bin, so there is nothing here to start")];
+    }
+    const wrong = named2.flatMap((one) => {
+      const found = VERSION_MANAGED.exec(one.line)?.groups;
+      return found === void 0 ? [] : [{ bin: found["bin"] ?? "", runner: found["runner"] ?? "" }];
+    });
+    if (wrong.length === 0) {
+      return [
+        finding3(
+          at,
+          "OK",
+          `${named2.length} geonosis bin(s) here, every one called directly rather than through a runner`
+        )
+      ];
+    }
+    return wrong.map(
+      ({ bin, runner }) => finding3(
+        at,
+        "FAIL",
+        `it runs ${bin} through ${runner} \u2014 a git hook's PATH is not the shell's and carries no version-manager shim, so ${runner} fails to START and what the author reads is its message, not this gate's. Call it directly: node_modules/.bin/${bin}`
+      )
+    );
+  });
 };
 var checkDrift = ({
   readers = READERS,
   root,
+  userSettings = join4(homedir(), SETTINGS),
   workspaces
 }) => {
   const config = readGeonosis(root);
   return [
     ...ci(root),
     ...orphanTests(root, workspaces),
+    ...scriptPaths(workspaces),
+    ...linkedBins(root, workspaces),
+    ...preloadAroundPnpm(root, workspaces),
+    ...generatedFiles(root, workspaces),
     ...pluginDirs(root),
+    ...publicHoists(root, workspaces),
+    ...gitHooks(root),
     ...law(root, config),
-    ...hooks(root),
-    ...blocks(root, config, readers)
+    ...hooks(root, userSettings),
+    ...blocks(root, config, readers, workspaces)
   ];
 };
 
@@ -672,7 +1148,38 @@ var ownReach = ({
   };
 };
 var optionsOf = (level) => Array.isArray(level) ? level.slice(1) : [];
-var under = (config, rule) => `${rule} under ${JSON.stringify(optionsOf(config.rules[rule]))}`;
+var optionSetsOf = (config, rule) => {
+  const seen = /* @__PURE__ */ new Set();
+  const sets = [];
+  for (const layer of layersOf(config, rule)) {
+    const options = [...optionsOf(layer.level)];
+    const key = JSON.stringify(options);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    sets.push(options);
+  }
+  return sets;
+};
+var enablingLayersOf = (config, rule) => {
+  const seen = /* @__PURE__ */ new Set();
+  const layers = [];
+  for (const layer of layersOf(config, rule)) {
+    if (OFF.has(severityOf(layer.level))) continue;
+    const options = [...optionsOf(layer.level)];
+    const key = JSON.stringify([layer.files, options]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    layers.push({ files: layer.files, options });
+  }
+  return layers;
+};
+var under = (config, rule) => `${rule} under ${optionSetsOf(config, rule).map((options) => JSON.stringify(options)).join(" / ")}`;
+var enabledHere = (config, plugin) => [
+  .../* @__PURE__ */ new Set([
+    ...enabledRulesOf(config.rules, plugin),
+    ...config.overrides.flatMap((one) => enabledRulesOf(one.rules, plugin))
+  ])
+].toSorted();
 var throughProbes = ({
   config,
   corpus,
@@ -681,6 +1188,7 @@ var throughProbes = ({
   silent
 }) => {
   const refused = /* @__PURE__ */ new Map();
+  const placed = /* @__PURE__ */ new Set();
   const dir = mkdtempSync(join5(tmpdir(), "geonosis-doctor-probe-"));
   const here = join5(dir, "corpus");
   try {
@@ -689,10 +1197,29 @@ var throughProbes = ({
       const write = probes[rule];
       if (write === void 0) continue;
       try {
-        const probe = write(optionsOf(config.rules[rule]));
-        const at = join5(here, probe.path);
-        mkdirSync(dirname2(at), { recursive: true });
-        writeFileSync(at, probe.source);
+        const layers = enablingLayersOf(config, rule);
+        const unclaimed = [];
+        let anyPlaced = false;
+        for (const layer of layers) {
+          const files = write(layer.options);
+          if (files.length === 0) throw new Error("its probe declares no file at all");
+          const claims = layer.files.length === 0 || files.some((file) => layer.files.some((glob) => matchesGlob(glob, file.path)));
+          if (!claims) {
+            unclaimed.push(
+              `its probe lands at ${files[0]?.path ?? ""}, which the entry enabling it claims none of: ${layer.files.join(", ")}`
+            );
+            continue;
+          }
+          for (const file of files) {
+            const at = join5(here, file.path);
+            if (placed.has(at)) continue;
+            placed.add(at);
+            mkdirSync(dirname2(at), { recursive: true });
+            writeFileSync(at, file.source);
+          }
+          anyPlaced = true;
+        }
+        if (!anyPlaced) throw new Error(unclaimed.join(" \xB7 "));
       } catch (error) {
         refused.set(rule, String(error.message));
       }
@@ -735,7 +1262,7 @@ var checkExercised = async ({
   } catch (error) {
     return said("SKIP", refusal(error));
   }
-  const enabled = enabledRulesOf(config.rules, manifest.plugin);
+  const enabled = enabledHere(config, manifest.plugin);
   if (enabled.length === 0) return said("SKIP", `no ${manifest.plugin} rule is enabled here`);
   let reach;
   try {
@@ -796,7 +1323,7 @@ var checkExercised = async ({
   }
   const unplaceable = [
     ...unprobed.map(
-      (rule) => `${rule} declares no probe, so ${optionsOf(config.rules[rule]).length === 0 ? "its scope" : JSON.stringify(optionsOf(config.rules[rule]))} does not reach the corpus`
+      (rule) => `${rule} declares no probe, so ${optionSetsOf(config, rule).every((options) => options.length === 0) ? "its scope" : under(config, rule)} does not reach the corpus`
     ),
     ...inert.map((rule) => `${rule}: ${probed.refused.get(rule) ?? ""}`)
   ];
@@ -1199,6 +1726,12 @@ var checkRunner = ({
         `"${script}" runs neither vitest nor bun test \u2014 this check has nothing to say about it`
       );
     }
+    if (testFilesUnder(workspace.dir).length === 0) {
+      return said(
+        "SKIP",
+        `"${script}" runs a test runner and there is no test file under this workspace \u2014 nothing here for its exit code to be wrong about`
+      );
+    }
     if (WRITES_A_REPORT.test(script)) {
       return said("OK", "the script asks the runner for its own JSON report, not for a status code");
     }
@@ -1283,6 +1816,11 @@ var runDoctor = async ({
 }) => {
   const configs = discoverConfigs(root);
   const workspaces = discoverWorkspaces(root);
+  if (workspaces.length === 0 && configs.length === 0) {
+    throw new DoctorError(
+      `nothing here to examine \u2014 no package.json and no ${CONFIG_FILE} anywhere under ${root}. Every line this would print is about a gate that is not here, and a page of SKIPs is not a pass.`
+    );
+  }
   const asked = (check) => only === void 0 || only.includes(check);
   const runs = [
     ["loaded", () => checkLoaded({ configs, root, workspaces })],

package/dist/doctor-cli.js

@@ -3,58 +3,65 @@ import {
   formatDoctor,
   formatJson,
   runDoctor
-} from "./chunk-ZJCUTDQW.js";
+} from "./chunk-7BRGHYQR.js";
 
 // src/doctor-cli.ts
 import { resolve } from "path";
-var USAGE = `geonosis-doctor [--root <dir>] [--only <check,\u2026>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
-
-Five questions a version bump is not finished until something has asked. The first four are ways
-enforcement has reported green while measuring nothing; the fifth asks whether it is still there.
-
-  loaded      The plugin oxlint would LOAD from each config's directory, against the version that
+var ABOUT = {
+  baseline: `The ratchet's numbers at HEAD against another ref. A ratchet lowers its own baseline
+              when a number shrinks, so nothing inside one checkout can see a branch raise one back
+              up. OFF unless asked for: it is the only check that runs git, and this tool is run
+              over repos other people are working in.`,
+  deployed: `What the pipeline REPORTED deploying, in .geonosis/deployed.json, against what the
+              tree declares in the wrangler configs geonosis.json names and release.secrets.
+              "versions upload" applies no triggers, so a cron edited in a config is silently
+              ignored in production for ever with a green pipeline; a secret can be put outside the
+              gate entirely. SKIPs with the sentence when the file is absent \u2014 its absence is not a
+              pass \u2014 and reads the file rather than importing @geonosis/release.`,
+  drift: `The gates that were set up and are no longer running: a CI job switched off by a
+              condition that can never be true, a test file under a workspace with no test script, a
+              script handing bun/node/tsx a file that is not on disk, a workspace bin nothing links,
+              an integration directory the registry never names, a geonosis bin a git hook calls
+              through pnpm/npx/bunx and therefore cannot start, a law over the ceiling its own
+              geonosis.json declared, nothing enabling the plugin in either scope, and a
+              geonosis.json block no manifest declares a package for (or the reverse).`,
+  exercised: `Every rule a config enables, against the corpus the loaded plugin ships. A rule at
+              "error" that can never fire is indistinguishable from a clean tree.`,
+  loaded: `The plugin oxlint would LOAD from each config's directory, against the version that
               config's workspace DECLARES. oxlint resolves a jsPlugins specifier from the CONFIG
               FILE's directory, so a nested copy left behind by a per-workspace install runs while
               every manifest and the lockfile say otherwise \u2014 one consumer measured a whole bug
               report against 0.3.0 on a repo pinned to 0.4.0. Every copy is found by RESOLUTION,
-              never by find: on pnpm the store keeps every version ever installed.
-
-  exercised   Every rule a config enables, against the corpus the loaded plugin ships. A rule at
-              "error" that can never fire is indistinguishable from a clean tree.
-
-  baseline    The ratchet's numbers at HEAD against another ref. A ratchet lowers its own baseline
-              when a number shrinks, so nothing inside one checkout can see a branch raise one back
-              up. OFF unless asked for: it is the only check that runs git, and this tool is run
-              over repos other people are working in.
-
-  runner      Workspaces whose test script's exit code is the only verdict. A pool exited 0 over
-              suites it had just reported as failing, for weeks, in a consumer.
-
-  observability
-              The exporter named by the "observability" block in geonosis.json: is a sink
+              never by find: on pnpm the store keeps every version ever installed.`,
+  observability: `The exporter named by the "observability" block in geonosis.json: is a sink
               configured, is its endpoint reachable (a HEAD with a short timeout), and did an event
               arrive inside maxAgeSeconds \u2014 read from the lastEventFile the sink writes, never from
               this tool importing the library it is checking. A deploy job reported success having
               deployed nothing and a /health answered ok over a dead database on the same
-              afternoon; both left a green build and a silent project.
-  drift       The gates that were set up and are no longer running: a CI job switched off by a
-              condition that can never be true, a test file under a workspace with no test script,
-              an integration directory the registry never names, a law over the ceiling its own
-              geonosis.json set, no .claude/settings.json installing the plugin, and a
-              geonosis.json block whose package is not installed (or the reverse).
+              afternoon; both left a green build and a silent project.`,
+  runner: `Workspaces whose test script's exit code is the only verdict. A pool exited 0 over
+              suites it had just reported as failing, for weeks, in a consumer. A script with no
+              test file under it is a SKIP \u2014 there is no result for an exit code to be wrong about.`
+};
+var USAGE = `geonosis-doctor [--root <dir>] [--only <check,\u2026>] [--json] [--strict] [--baseline-against [<ref>]] [--oxlint <path>]
 
-  deployed    What the pipeline REPORTED deploying, in .geonosis/deployed.json, against what the
-              tree declares in the wrangler configs geonosis.json names and release.secrets.
-              "versions upload" applies no triggers, so a cron edited in a config is silently
-              ignored in production for ever with a green pipeline; a secret can be put outside the
-              gate entirely. SKIPs with the sentence when the file is absent \u2014 its absence is not a
-              pass \u2014 and reads the file rather than importing @geonosis/release.
+${CHECKS.length} questions a version bump is not finished until something has asked. Most are ways
+enforcement has reported green while measuring nothing; drift asks whether the gate is still there
+at all, and the last two ask whether what was reported is what happened.
+
+With no arguments it runs every one of them over the working directory. A tree holding no
+package.json and no .oxlintrc.json is REFUSED with exit 2 \u2014 there is nothing there to examine, and a
+page of SKIPs is not a pass.
+
+${CHECKS.map((check) => `  ${check.padEnd(11)} ${ABOUT[check]}`).join("\n\n")}
 
 exercised reads the corpus the loaded plugin ships, and \u2014 when geonosis.json names one under
 doctor.corpus \u2014 the corpus THIS repo ships for its own options. Three rules cannot be answered any
 other way: layer-walls fires on a repo's own layer names, no-brand-names on its brand, and
 plugin-route-namespaced on its package root, while the shipped corpus says acme and layers/core.
 
+  --print-config-shape   every file this reads, and the keys it reads out of each
+
 Exits 1 when any line is a FAIL or an UNJUDGED \u2014 a question this could not ask is not a pass \u2014 and
 2 when the run could not be made at all. --strict promotes every WARN to a FAIL. --json prints the
 whole report for a CI step to read.`;
@@ -100,10 +107,43 @@ var parseDoctorArgs = (argv, cwd) => {
     strict
   };
 };
+var CONFIG_SHAPE = `geonosis-doctor reads geonosis.json, geonosis.ratchet.json, .oxlintrc.json,
+pnpm-workspace.yaml and .claude/settings.json
+
+geonosis.json \u2192 "law"
+  file            string?    the law file to measure (default "CLAUDE.md")
+  maxLines        number?    the ceiling. Undeclared means UNJUDGED, never a default it fires on
+geonosis.json \u2192 "observability"
+  sink            string     where this repo sends its errors
+  endpoint        string     the URL that must be reachable
+  lastEventFile   string     the file the sink writes on arrival
+  probe           string?    a command that answers instead of lastEventFile
+  maxAgeSeconds   number     how old the last event may be
+geonosis.json \u2192 "release"
+  wrangler        string[]   the wrangler configs a deployment carries
+  wranglerEnv     string?    the named environment block to read
+  secrets         string[]   the secret names it carries
+.oxlintrc.json
+  jsPlugins       string[]   the plugin specifiers oxlint would load
+  rules           object     the base rules, and the options each was given
+  overrides       object[]   files + rules; an entry REPLACES a rule's options for the files it
+                             claims, last match winning \u2014 the same resolution oxlint does
+geonosis.ratchet.json
+  the ratchet's own \u2014 run \`geonosis-ratchet --print-config-shape\`
+pnpm-workspace.yaml
+  publicHoistPattern  string[]   the packages this repo claims are linked at the root, read as
+                                 text; a "*" is the only wildcard and it spans "/"
+.claude/settings.json
+  enabledPlugins  object     what installs the kit's plugin in THIS repo`;
 var main = async () => {
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h")) {
     process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
+  if (argv.includes("--print-config-shape")) {
+    process.stdout.write(`${CONFIG_SHAPE}
 `);
     return 0;
   }

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+type Overrides = {
+    files: readonly string[];
+    rules: Record<string, unknown>;
+}[];
+
 /**
  * The questions a bump is not finished until something has asked, in the order a run asks them.
  * The first four are ways enforcement has reported green while measuring nothing; `drift` asks
@@ -29,6 +34,7 @@ declare class DoctorError extends Error {
     constructor(message: string);
 }
 type Manifest = {
+    bin?: Record<string, string> | string;
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
     name?: string;
@@ -47,6 +53,8 @@ type DiscoveredConfig = {
     /** Why this config could not be read. A config nobody can parse is a finding, never a skip. */
     error?: string;
     jsPlugins: string[];
+    /** Layers that REPLACE a rule's options for the files they claim — never merged into the base. */
+    overrides: Overrides;
     path: string;
     relative: string;
     rules: Record<string, unknown>;
@@ -138,7 +146,7 @@ declare const READERS: Record<string, string>;
  * block nothing reads. The other four checks ask whether a gate measures what it names; this one
  * asks whether it is still there at all.
  */
-declare const checkDrift: ({ readers, root, workspaces, }: {
+declare const checkDrift: ({ readers, root, userSettings, workspaces, }: {
     /**
      * Which package reads which block. It is a parameter so a test can name one that can NEVER be
      * installed: a fixture that turns on whether some real package happens to be present on the base
@@ -147,6 +155,11 @@ declare const checkDrift: ({ readers, root, workspaces, }: {
      */
     readers?: Record<string, string>;
     root: string;
+    /**
+     * The machine-wide settings, a parameter so a test never asks about the home directory it happens
+     * to run in — the same reason `readers` is one.
+     */
+    userSettings?: string;
     workspaces: Workspace[];
 }) => Finding[];
 
@@ -244,15 +257,6 @@ declare const repoCorpusOf: (root: string) => string | undefined;
 declare const formatDoctor: ({ counts, findings, ok, root }: DoctorReport) => string;
 declare const formatJson: (report: DoctorReport) => string;
 
-/**
- * What oxlint would load, asked the only way that answers on every package manager.
- *
- * oxlint resolves a `jsPlugins` specifier from the CONFIG FILE's directory, not the working
- * directory, so the question is asked from a directory and never from the process's cwd. And it is
- * asked of the RESOLVER: counting copies with `find` is a bun/npm check only — on pnpm the entries
- * under `node_modules/@scope/` are symlinks into `.pnpm/`, which keeps every version ever
- * installed, so the same count answers 7 on a correct tree and 0 with the store excluded.
- */
 declare const resolveFrom: (dir: string, specifier: string) => string;
 /** The package a resolved entry point belongs to: up until a manifest claims the name. */
 declare const packageDirOf: (entry: string, name: string) => string;

package/dist/index.js

@@ -34,7 +34,7 @@ import {
   resolveFrom,
   runDoctor,
   satisfies
-} from "./chunk-ZJCUTDQW.js";
+} from "./chunk-7BRGHYQR.js";
 export {
   CHECKS,
   CONFIG_FILE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/doctor",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "types": "./dist/index.d.ts",
   "description": "The adoption doctor — declared ≠ loaded, enabled ≠ exercised, a baseline that grew, a runner whose exit code is the only verdict.",
   "keywords": [
@@ -35,7 +35,7 @@
     "dist"
   ],
   "dependencies": {
-    "@geonosis/lint-parity": "1.2.0"
+    "@geonosis/lint-parity": "1.3.0"
   },
   "peerDependencies": {
     "oxlint": ">=1.77"