@geonosis/ratchet 1.3.0 → 2.0.0

package/README.md

@@ -363,11 +363,12 @@ Every counter takes its `command` from the config, so the toolchain stays the re
 | `testFailures` | the runner's own failure summary — or, with `report: "vitest-json"`, `numFailedTests` out of the JSON report the command wrote; throws when nothing is readable, when the report is absent, and when the report failed with nothing failing | `command`, `report`, `reportPath` |
 | `unformattedFiles` | paths `--list-different` names that exist on disk | `command` |
 | `cloneCount` | jscpd's `Found N clones` | `command` |
-| `knipIssues` | the totals under knip's unused-* headings | `command`, `headings` |
+| `knipIssues` | the total under EVERY heading knip's compact reporter emits — the shape `<Title> (N)`, not a list of titles, so a heading the kit has not heard of is debt rather than a silent zero. `headings` narrows it, and every printed heading the narrowing leaves out must be named under `excusedHeadings` with a reason or the run refuses | `command`, `headings`, `excusedHeadings` |
 | `boundaryIssues` | `N issues found` from a boundary scan | `command` |
 | `archViolations` | lines matching a marker your own architecture scan prints, refusing a non-zero exit that printed none of them — a scan that could not run is not a clean scan | `command`, `match` |
 | `sumOfCounts` | the total of one capture group across a per-file census (`grep -rc`) | `command`, `match` |
 | `lawLineCount` | the lines of the law file — a ceiling that can only come down | `path` |
+| `probelessRules` | the rules an oxlint config ENABLES that the plugin it loads declares no `probe()` for. Those are the ones `geonosis-doctor`'s `exercised` can only answer UNJUDGED about, which #137 makes a WARN naming the kit as owner — and a WARN the kit carries across releases is a downgraded rule by another name. The plugin is imported from the tree it is pointed at, and one that cannot be loaded is a refusal, never a zero | `config`, `plugin` |
 | `runtimeCodeShipped` | 0 when a change shipped runtime code, 1 when it shipped none | `command`, `patterns` |
 | `disabledCiJobs` | lines of `if: false` across the workflow files — a job switched off to get a release through, still off. A condition that merely mentions `false` is not one. No workflows directory at all reads 0 | `dir` |
 | `bundleBytes` | one integer out of whatever your sizing command printed, separators and all; with `match`, the group that pattern names rather than the last integer, refusing when it matches nothing. **Tolerates.** | `command`, `match`, `tolerance` |
@@ -375,6 +376,7 @@ Every counter takes its `command` from the config, so the toolchain stays the re
 | `testsWithoutRunner` | workspaces holding `*.test.*`, `*.spec.*` or `__tests__/` with no `test` script — the suites nobody runs, which read exactly like suites that pass | `script` |
 | `packagesWithoutTypecheck` | workspaces with no `typecheck` script | `script` |
 | `walkFindings` | the defects in the report `geonosis-walk` wrote, over every page; with `classes`, only those classes, refusing a class the walk does not have. A missing or unparsable report is a refusal — the walk writes none when it could not run | `report`, `classes` |
+| `orphanTodos` | debt markers outside the plan graph: one naming no plan, and one naming a plan that is not in the plans directory. Leading zeroes are a spelling, so `(021)` finds `21-…md`. Fixtures, dependencies and build output are not read | `markers`, `plans`, `roots` |
 
 ### `tolerance`, and the two counters that accept one
 

package/dist/{chunk-HBM6F3GO.js → chunk-H4PLCM5J.js}

@@ -1,13 +1,76 @@
+// src/core/envelope.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var ENVELOPES_DIR = ".geonosis/envelopes";
+var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
+var UnbalancedEnvelope = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnbalancedEnvelope";
+  }
+};
+var isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+var unbalancedMessage = (envelope, next) => `${envelope.tool}: considered ${envelope.considered} but accounts for ${envelope.read + envelope.refused.length + envelope.excused.length} \u2014 ${envelope.read} read + ${envelope.refused.length} refused + ${envelope.excused.length} excused. A run that has lost count of its own inputs cannot say what it measured, so no verdict was rendered and no envelope was written. Next: ${next}`;
+var writeEnvelope = ({
+  envelope,
+  next,
+  root
+}) => {
+  if (envelope.tool.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `an envelope with no tool name cannot be filed or reported against. Next: ${next}`
+    );
+  }
+  if (envelope.version.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: an envelope that cannot name the build that wrote it dates nothing, and a stale one reads exactly like a fresh one. Next: ${next}`
+    );
+  }
+  if (!isCount(envelope.considered) || !isCount(envelope.read)) {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: considered ${envelope.considered} and read ${envelope.read} \u2014 a census is a whole number of things, and arithmetic over anything else balances by accident. Next: ${next}`
+    );
+  }
+  if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
+    throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
+  }
+  const at = envelopePath(root, envelope.tool);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
+`);
+  return at;
+};
+var UNKNOWN = "unknown";
+var versionIn = (dir) => {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var versionOf = (moduleUrl) => {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (; ; ) {
+    const found = versionIn(dir);
+    if (found !== void 0) return found;
+    const up = dirname(dir);
+    if (up === dir) return UNKNOWN;
+    dir = up;
+  }
+};
+
 // src/core/lock.ts
 import { randomUUID } from "crypto";
-import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { linkSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "fs";
 import { homedir } from "os";
-import { dirname, join } from "path";
-var heavyLockPath = () => process.env.GEONOSIS_HEAVY_LOCK ?? join(homedir(), ".cache", "geonosis", "heavy.lock");
+import { dirname as dirname2, join as join2 } from "path";
+var heavyLockPath = () => process.env.GEONOSIS_HEAVY_LOCK ?? join2(homedir(), ".cache", "geonosis", "heavy.lock");
 var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
 var holderOf = (path) => {
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
     return typeof parsed.pid === "number" ? {
       cwd: parsed.cwd ?? "somewhere",
       pid: parsed.pid,
@@ -31,7 +94,7 @@ var heldFor = (holder) => {
   return `${Math.round((Date.now() - since) / 1e3)}s`;
 };
 var write = (path) => {
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync2(dirname2(path), { recursive: true });
   const mine = {
     cwd: process.cwd(),
     pid: process.pid,
@@ -39,7 +102,7 @@ var write = (path) => {
   };
   const staging = `${path}.${process.pid}.${randomUUID()}`;
   try {
-    writeFileSync(staging, JSON.stringify(mine));
+    writeFileSync2(staging, JSON.stringify(mine));
     linkSync(staging, path);
     return true;
   } catch (error) {
@@ -89,7 +152,7 @@ var acquireExclusive = async ({
 };
 
 // src/core/config.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { existsSync, readFileSync as readFileSync3 } from "fs";
 import { resolve } from "path";
 var CONFIG_FILE = "geonosis.ratchet.json";
 var keyOf = (entry) => entry.key ?? entry.counter;
@@ -98,7 +161,7 @@ var loadConfig = (cwd) => {
   if (!existsSync(path)) {
     throw new Error(`no ${CONFIG_FILE} in ${cwd} \u2014 the ratchet has nothing to count`);
   }
-  const parsed = JSON.parse(readFileSync2(path, "utf8"));
+  const parsed = JSON.parse(readFileSync3(path, "utf8"));
   if (!Array.isArray(parsed.counters)) {
     throw new Error(`${CONFIG_FILE} has no "counters" array`);
   }
@@ -126,7 +189,7 @@ var loadConfig = (cwd) => {
 };
 var resolveBaseline = (cwd) => {
   try {
-    const parsed = JSON.parse(readFileSync2(resolve(cwd, CONFIG_FILE), "utf8"));
+    const parsed = JSON.parse(readFileSync3(resolve(cwd, CONFIG_FILE), "utf8"));
     return typeof parsed.baseline === "string" ? parsed.baseline : "gate-baseline.json";
   } catch {
     return "gate-baseline.json";
@@ -172,13 +235,13 @@ ${output.trim()}`
 };
 
 // src/core/prove.ts
-import { existsSync as existsSync2, mkdtempSync, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync2, mkdtempSync, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
 import { tmpdir } from "os";
-import { delimiter, dirname as dirname3, join as join2, resolve as resolve3 } from "path";
+import { delimiter, dirname as dirname4, join as join3, resolve as resolve3 } from "path";
 
 // src/core/exclusive.ts
 import { spawn } from "child_process";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname3, resolve as resolve2 } from "path";
 var MARK = /^exclusive-hold (start|end) (\d+)$/gm;
 var KEY = "exclusive";
 var spanOf = (output) => {
@@ -193,7 +256,7 @@ var hold = (cli, holdMs, lockPath) => new Promise((done) => {
     process.execPath,
     [cli, "--exclusive", "--exclusive-timeout", "60", "--hold", String(holdMs)],
     {
-      cwd: dirname2(resolve2(cli)),
+      cwd: dirname3(resolve2(cli)),
       env: { ...process.env, GEONOSIS_HEAVY_LOCK: lockPath },
       stdio: ["ignore", "pipe", "pipe"]
     }
@@ -245,9 +308,9 @@ var toolPath = (cwd) => {
   const dirs = [];
   let dir = resolve3(cwd);
   for (; ; ) {
-    const bin = join2(dir, "node_modules", ".bin");
+    const bin = join3(dir, "node_modules", ".bin");
     if (existsSync2(bin)) dirs.push(bin);
-    const parent = dirname3(dir);
+    const parent = dirname4(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -255,7 +318,7 @@ var toolPath = (cwd) => {
 };
 var NO_PROBE = "no probe \u2014 a counter nobody has seen read a planted finding has not been shown to measure";
 var oneProofOf = async (counter, key, path, probe) => {
-  const dir = mkdtempSync(join2(tmpdir(), "geonosis-prove-"));
+  const dir = mkdtempSync(join3(tmpdir(), "geonosis-prove-"));
   try {
     probe.input(dir);
     const command = probe.command?.(dir);
@@ -322,11 +385,43 @@ var runProve = async ({
     if (taken.some((one) => one.verdict !== "proven" && one.verdict !== "skipped")) {
       return { proofs, proven: false };
     }
+    const customized = (counter.readingParams ?? []).filter((one) => entry[one] !== void 0);
+    if (customized.length > 0) {
+      const declared = entry.probe;
+      const named = customized.map((one) => `${one} ${JSON.stringify(entry[one])}`).join(", ");
+      if (declared === void 0 || typeof declared.sample !== "string" || typeof declared.expect !== "number") {
+        proofs.push({
+          counter: counter.id,
+          key,
+          reason: `the configured ${named} is not exercised by this counter's shipped probe \u2014 declare probe: { sample, expect } beside it, a sample this reading must count`,
+          verdict: "unproven"
+        });
+        return { proofs, proven: false };
+      }
+      const sample = declared.sample;
+      const entryProbe = {
+        command: () => "cat sample.txt",
+        expect: declared.expect,
+        input: (dir) => writeFileSync3(join3(dir, "sample.txt"), sample),
+        name: "configured reading",
+        params: Object.fromEntries(customized.map((one) => [one, entry[one]]))
+      };
+      const proof = await oneProofOf(counter, key, path, entryProbe);
+      const said = proof.verdict === "cannot-fail" ? {
+        counter: counter.id,
+        expected: declared.expect,
+        key,
+        reading: 0,
+        verdict: "misread"
+      } : proof;
+      proofs.push(said);
+      if (said.verdict !== "proven") return { proofs, proven: false };
+    }
   }
   if (exclusiveVia !== void 0) {
-    const dir = mkdtempSync(join2(tmpdir(), "geonosis-lock-"));
+    const dir = mkdtempSync(join3(tmpdir(), "geonosis-lock-"));
     try {
-      const proof = await proveExclusive({ cli: exclusiveVia, lockPath: join2(dir, "heavy.lock") });
+      const proof = await proveExclusive({ cli: exclusiveVia, lockPath: join3(dir, "heavy.lock") });
       proofs.push(proof);
       if (proof.verdict !== "serialised") return { proofs, proven: false };
     } finally {
@@ -337,20 +432,23 @@ var runProve = async ({
 };
 
 // src/core/ratchet.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
 import { resolve as resolve4 } from "path";
 var EVIDENCE_LINES = 10;
 var recorded = (counter, params, run) => {
   let output = "";
+  let lastCommand;
   const trimmed = (lines) => lines.map((line) => line.trimEnd()).filter((line) => line !== "").slice(-EVIDENCE_LINES);
   return {
     cited: () => {
       const counted = counter.evidence === void 0 ? [] : counter.evidence({ output, params });
       return trimmed(counted.length > 0 ? counted : output.split("\n"));
     },
+    lastCommand: () => lastCommand,
     run: (command) => {
       const result = run(command);
       output = result.output;
+      lastCommand = command;
       return result;
     }
   };
@@ -386,9 +484,10 @@ var runRatchet = async ({
   if (!existsSync3(baselinePath)) {
     throw new Error(`no ${config.baseline} in ${cwd} \u2014 nothing to ratchet against`);
   }
-  const baseline = JSON.parse(readFileSync3(baselinePath, "utf8"));
+  const baseline = JSON.parse(readFileSync4(baselinePath, "utf8"));
   const byId = new Map(counters.map((one) => [one.id, one]));
   const measurements = [];
+  const refusals = [];
   for (const entry of config.counters) {
     const counter = byId.get(entry.counter);
     if (counter === void 0) {
@@ -409,7 +508,17 @@ var runRatchet = async ({
     }
     const tolerance = toleranceOf(entry, key, counter);
     const recorder = recorded(counter, entry, runCommand(cwd, entry.counter));
-    const now = await counter.run({ cwd, key, params: entry, run: recorder.run });
+    let now;
+    try {
+      now = await counter.run({ cwd, key, params: entry, run: recorder.run });
+    } catch (error) {
+      const ran = recorder.lastCommand();
+      refusals.push({
+        key,
+        reason: `${error.message}${ran === void 0 ? "" : `. Next: run \`${ran}\` in ${cwd} and read what it prints`}`
+      });
+      continue;
+    }
     const verdict = verdictOf(now, limit, tolerance);
     measurements.push({
       baseline: limit,
@@ -421,16 +530,16 @@ var runRatchet = async ({
   }
   const grew = measurements.some((one) => one.verdict === "grew");
   const shrank = measurements.some((one) => one.verdict === "shrank");
-  if (shrank && !grew) {
+  if (shrank && !grew && refusals.length === 0) {
     const next = { ...baseline };
     for (const one of measurements) {
       if (one.verdict === "shrank") next[one.key] = one.now;
     }
-    writeFileSync2(baselinePath, `${JSON.stringify(next, null, 2)}
+    writeFileSync4(baselinePath, `${JSON.stringify(next, null, 2)}
 `);
-    return { measurements, rewritten: true };
+    return { considered: config.counters.length, measurements, refusals, rewritten: true };
   }
-  return { measurements, rewritten: false };
+  return { considered: config.counters.length, measurements, refusals, rewritten: false };
 };
 
 // src/counters/params.ts
@@ -449,12 +558,12 @@ var countMatches = (text, pattern) => text.match(new RegExp(pattern.source, `${p
 var escapeForRegex = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 // src/counters/plant.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname4, join as join3 } from "path";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname5, join as join4 } from "path";
 var plant = (dir, relative, contents) => {
-  const path = join3(dir, relative);
-  mkdirSync2(dirname4(path), { recursive: true });
-  writeFileSync3(path, contents);
+  const path = join4(dir, relative);
+  mkdirSync3(dirname5(path), { recursive: true });
+  writeFileSync5(path, contents);
 };
 var captured = (sample) => ({
   command: () => "cat sample.txt",
@@ -539,8 +648,8 @@ var bundleBytes = {
 };
 
 // src/counters/ci.ts
-import { readdirSync, readFileSync as readFileSync4 } from "fs";
-import { join as join4, resolve as resolve5 } from "path";
+import { readdirSync, readFileSync as readFileSync5 } from "fs";
+import { join as join5, resolve as resolve5 } from "path";
 var DISABLED = /\bif:[ \t]*false\b/;
 var WORKFLOW = /\.ya?ml$/;
 var disabledCiJobs = {
@@ -558,7 +667,7 @@ var disabledCiJobs = {
     const dir = resolve5(cwd, relative);
     let files;
     try {
-      files = readdirSync(dir, { withFileTypes: true }).filter((entry) => WORKFLOW.test(entry.name)).map((entry) => join4(dir, entry.name));
+      files = readdirSync(dir, { withFileTypes: true }).filter((entry) => WORKFLOW.test(entry.name)).map((entry) => join5(dir, entry.name));
     } catch {
       return 0;
     }
@@ -566,7 +675,7 @@ var disabledCiJobs = {
     for (const file of files) {
       let contents;
       try {
-        contents = readFileSync4(file, "utf8");
+        contents = readFileSync5(file, "utf8");
       } catch (error) {
         throw new CounterError(
           "disabledCiJobs",
@@ -589,29 +698,49 @@ var cloneCount = {
     const output = run(command).output;
     const found = output.match(CLONES)?.[1];
     if (found === void 0) {
+      const said = output.trim();
       throw new CounterError(
         "cloneCount",
-        `no "Found N clones" line:
-${output.trim().slice(-500)}`
+        said === "" ? 'the command printed nothing at all, so there is no "Found N clones" line to read and no output to show \u2014 it is not installed, or it never ran' : `no "Found N clones" line in what it printed:
+${said.slice(-500)}`
       );
     }
     return Number(found);
   }
 };
-var DEFAULT_HEADINGS = [
-  "Unused files",
-  "Unused dependencies",
-  "Unused devDependencies",
-  "Unused exports",
-  "Unused exported types"
-];
+var HEADING = /^([A-Z][A-Za-z ]+?) \((\d+)\)\s*$/gm;
+var headingsIn = (output) => {
+  const found = /* @__PURE__ */ new Map();
+  for (const [, heading = "", count = "0"] of output.matchAll(HEADING)) {
+    found.set(heading, Number(count));
+  }
+  return found;
+};
+var excusesIn = (params) => {
+  const declared = params["excusedHeadings"];
+  return new Set(
+    typeof declared === "object" && declared !== null && !Array.isArray(declared) ? Object.keys(declared) : []
+  );
+};
 var knipIssues = {
   id: "knipIssues",
   probe: { ...captured("Unused files (1)\nsrc/gone.ts\n"), expect: 1 },
+  readingParams: ["headings"],
   run: async ({ params, run }) => {
     const command = stringParam("knipIssues", params, "command", "npx knip --reporter compact");
-    const output = run(command).output;
-    return stringsParam(params, "headings", DEFAULT_HEADINGS).map((heading) => Number(output.match(new RegExp(`${heading} \\((\\d+)\\)`))?.[1] ?? 0)).reduce((sum, count) => sum + count, 0);
+    const printed = headingsIn(run(command).output);
+    const counted = stringsParam(params, "headings", [...printed.keys()]);
+    const excused = excusesIn(params);
+    const dropped = [...printed.entries()].filter(
+      ([heading, count]) => count > 0 && !counted.includes(heading) && !excused.has(heading)
+    );
+    if (dropped.length > 0) {
+      throw new CounterError(
+        "knipIssues",
+        `knip printed ${dropped.map(([heading, count]) => `${heading} (${count})`).join(", ")} and the configured "headings" counts ${counted.join(", ")} \u2014 three ways out: add each to "headings", name it under "excusedHeadings" with the reason this repo does not hold it, or remove "headings" altogether and count every heading knip prints`
+      );
+    }
+    return counted.reduce((sum, heading) => sum + (printed.get(heading) ?? 0), 0);
   }
 };
 var ISSUES = /(\d+) issues? found/;
@@ -646,7 +775,7 @@ var unformattedFiles = {
 };
 
 // src/counters/gate-report.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
 import { resolve as resolve7 } from "path";
 var DEFAULT_REPORT = ".geonosis/gate-report.json";
 var fastTierMs = {
@@ -680,7 +809,7 @@ var fastTierMs = {
     }
     let report;
     try {
-      report = JSON.parse(readFileSync5(path, "utf8"));
+      report = JSON.parse(readFileSync6(path, "utf8"));
     } catch (error) {
       throw new CounterError(
         "fastTierMs",
@@ -702,7 +831,7 @@ var fastTierMs = {
 };
 
 // src/counters/law.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
 import { resolve as resolve8 } from "path";
 var lawLineCount = {
   id: "lawLineCount",
@@ -715,12 +844,12 @@ var lawLineCount = {
     const relative = stringParam("lawLineCount", params, "path", "CLAUDE.md");
     const path = resolve8(cwd, relative);
     if (!existsSync6(path)) throw new CounterError("lawLineCount", `no law file at ${relative}`);
-    return readFileSync6(path, "utf8").replace(/\n$/, "").split("\n").length;
+    return readFileSync7(path, "utf8").replace(/\n$/, "").split("\n").length;
   }
 };
 
 // src/counters/oxlint.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync8, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "fs";
 import { resolve as resolve9 } from "path";
 var DEFAULT_COMMAND = "npx oxlint --format=unix --config .oxlintrc.json .";
 var PROBE_COMMAND = "oxlint --format=unix --config .oxlintrc.json .";
@@ -887,11 +1016,11 @@ var oxlintRule = {
     const source = resolve9(cwd, config);
     if (!existsSync7(source)) throw new CounterError("oxlintRule", `no config at ${config}`);
     const strictName = `.oxlintrc.ratchet-${key}.json`;
-    const strict = readFileSync7(source, "utf8").replace(
+    const strict = readFileSync8(source, "utf8").replace(
       new RegExp(`("[^"]*${escapeForRegex(rule)}"\\s*:\\s*\\[?\\s*)"(warn|off)"`),
       '$1"error"'
     );
-    writeFileSync4(resolve9(cwd, strictName), strict);
+    writeFileSync6(resolve9(cwd, strictName), strict);
     try {
       return countRule(run(command.replace("{config}", strictName)), rule, expect);
     } finally {
@@ -900,6 +1029,100 @@ var oxlintRule = {
   }
 };
 
+// src/counters/probes.ts
+import { existsSync as existsSync8, readFileSync as readFileSync9 } from "fs";
+import { createRequire } from "module";
+import { join as join6, resolve as resolve10 } from "path";
+import { pathToFileURL } from "url";
+var ID = "probelessRules";
+var OFF = /* @__PURE__ */ new Set([0, "0", "allow", "off", false]);
+var severityOf2 = (level) => Array.isArray(level) ? level[0] : level;
+var enabledIn = (config, namespace) => {
+  const on = /* @__PURE__ */ new Set();
+  for (const block of [
+    config.rules ?? {},
+    ...(config.overrides ?? []).map((one) => one.rules ?? {})
+  ]) {
+    for (const [id, level] of Object.entries(block)) {
+      if (id.startsWith(`${namespace}/`) && !OFF.has(severityOf2(level))) {
+        on.add(id.slice(namespace.length + 1));
+      }
+    }
+  }
+  return [...on].toSorted();
+};
+var probedBy = async (cwd, plugin) => {
+  let entry;
+  try {
+    entry = createRequire(join6(cwd, "noop.js")).resolve(plugin);
+  } catch (error) {
+    throw new CounterError(
+      ID,
+      `could not resolve ${plugin} from ${cwd} \u2014 ${String(error.message).split("\n")[0]}. A plugin nobody can load says nothing about which rules ship a probe, and it is not zero of them`
+    );
+  }
+  let loaded;
+  try {
+    loaded = await import(pathToFileURL(entry).href);
+  } catch (error) {
+    throw new CounterError(ID, `could not import ${entry} \u2014 ${error.message}`);
+  }
+  const namespace = loaded.default?.meta?.name;
+  if (typeof namespace !== "string" || namespace === "") {
+    throw new CounterError(
+      ID,
+      `${plugin} declares no meta.name, so nothing says which rule ids in the config are its own`
+    );
+  }
+  return {
+    namespace,
+    probed: new Set(
+      Object.entries(loaded.default?.rules ?? {}).filter(([, rule]) => typeof rule?.probe === "function").map(([name]) => name)
+    )
+  };
+};
+var PLUGIN = "@geonosis/oxlint-plugin-biological-architecture";
+var probelessRules = {
+  id: ID,
+  probe: {
+    expect: 1,
+    input: (dir) => {
+      plant(
+        dir,
+        ".oxlintrc.json",
+        JSON.stringify({
+          jsPlugins: ["probe-plugin"],
+          rules: { "x/probed": "error", "x/bare": "error" }
+        })
+      );
+      plant(
+        dir,
+        "node_modules/probe-plugin/package.json",
+        '{"name":"probe-plugin","main":"index.js"}'
+      );
+      plant(
+        dir,
+        "node_modules/probe-plugin/index.js",
+        "export default { meta: { name: 'x' }, rules: { probed: { probe: () => [], create: () => ({}) }, bare: { create: () => ({}) } } }\n"
+      );
+    },
+    params: { plugin: "probe-plugin" }
+  },
+  run: async ({ cwd, params }) => {
+    const relative = stringParam(ID, params, "config", ".oxlintrc.json");
+    const path = resolve10(cwd, relative);
+    if (!existsSync8(path)) throw new CounterError(ID, `no oxlint config at ${relative}`);
+    let config;
+    try {
+      config = JSON.parse(readFileSync9(path, "utf8"));
+    } catch (error) {
+      throw new CounterError(ID, `${relative} does not parse: ${error.message}`);
+    }
+    const { namespace, probed } = await probedBy(cwd, stringParam(ID, params, "plugin", PLUGIN));
+    return enabledIn(config, namespace).filter((rule) => !probed.has(rule)).length;
+  }
+};
+
 // src/counters/runtime-code.ts
 var DEFAULT_PATTERNS = ["^(apps|packages)/[^/]+/src/"];
 var NOT_RUNTIME = /(\.test\.|\.spec\.|__tests__\/|__fixtures__\/|\.d\.ts$)/;
@@ -925,15 +1148,15 @@ var runtimeCodeShipped = {
 
 // src/counters/scripts.ts
 import { readdirSync as readdirSync3 } from "fs";
-import { join as join6 } from "path";
+import { join as join8 } from "path";
 
 // src/counters/workspace.ts
-import { existsSync as existsSync8, readdirSync as readdirSync2, readFileSync as readFileSync8 } from "fs";
-import { join as join5, resolve as resolve10 } from "path";
+import { existsSync as existsSync9, readdirSync as readdirSync2, readFileSync as readFileSync10 } from "fs";
+import { join as join7, resolve as resolve11 } from "path";
 var SKIP = /^(node_modules|\.)/;
 var childDirs = (dir) => {
   try {
-    return readdirSync2(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !SKIP.test(entry.name)).map((entry) => join5(dir, entry.name));
+    return readdirSync2(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !SKIP.test(entry.name)).map((entry) => join7(dir, entry.name));
   } catch {
     return [];
   }
@@ -943,14 +1166,14 @@ var expand = (root, pattern) => {
   const segments = pattern.split("/").filter((one) => one !== "" && one !== ".");
   let dirs = [root];
   for (const segment of segments) {
-    dirs = segment === "*" ? dirs.flatMap((dir) => childDirs(dir)) : segment === "**" ? dirs.flatMap((dir) => descendants(dir, 3)) : dirs.map((dir) => join5(dir, segment)).filter((dir) => existsSync8(dir));
+    dirs = segment === "*" ? dirs.flatMap((dir) => childDirs(dir)) : segment === "**" ? dirs.flatMap((dir) => descendants(dir, 3)) : dirs.map((dir) => join7(dir, segment)).filter((dir) => existsSync9(dir));
   }
   return dirs;
 };
 var QUOTED = /^['"]|['"]$/g;
 var cleaned = (value) => value.replace(/#.*$/, "").trim().replaceAll(QUOTED, "");
 var pnpmPatterns = (path) => {
-  const lines = readFileSync8(path, "utf8").split("\n");
+  const lines = readFileSync10(path, "utf8").split("\n");
   const at = lines.findIndex((line) => line.startsWith("packages:"));
   if (at === -1) return [];
   const inline = lines[at]?.slice("packages:".length).trim() ?? "";
@@ -969,31 +1192,31 @@ var pnpmPatterns = (path) => {
   return patterns;
 };
 var npmPatterns = (path) => {
-  const parsed = JSON.parse(readFileSync8(path, "utf8"));
+  const parsed = JSON.parse(readFileSync10(path, "utf8"));
   const declared = Array.isArray(parsed.workspaces) ? parsed.workspaces : parsed.workspaces?.packages ?? [];
   return declared.filter((one) => typeof one === "string");
 };
 var nameOf = (dir) => {
-  const manifest = join5(dir, "package.json");
-  if (!existsSync8(manifest)) return void 0;
+  const manifest = join7(dir, "package.json");
+  if (!existsSync9(manifest)) return void 0;
   try {
-    const { name } = JSON.parse(readFileSync8(manifest, "utf8"));
+    const { name } = JSON.parse(readFileSync10(manifest, "utf8"));
     return typeof name === "string" && name !== "" ? name : void 0;
   } catch {
     return void 0;
   }
 };
 var workspaceDirs = (cwd) => {
-  const root = resolve10(cwd);
-  const pnpm = join5(root, "pnpm-workspace.yaml");
-  const manifest = join5(root, "package.json");
-  const patterns = existsSync8(pnpm) ? pnpmPatterns(pnpm) : existsSync8(manifest) ? npmPatterns(manifest) : [];
-  const dirs = patterns.filter((pattern) => !pattern.startsWith("!")).flatMap((pattern) => expand(root, pattern)).filter((dir) => existsSync8(join5(dir, "package.json")));
+  const root = resolve11(cwd);
+  const pnpm = join7(root, "pnpm-workspace.yaml");
+  const manifest = join7(root, "package.json");
+  const patterns = existsSync9(pnpm) ? pnpmPatterns(pnpm) : existsSync9(manifest) ? npmPatterns(manifest) : [];
+  const dirs = patterns.filter((pattern) => !pattern.startsWith("!")).flatMap((pattern) => expand(root, pattern)).filter((dir) => existsSync9(join7(dir, "package.json")));
   return [...new Set(dirs)];
 };
 var manifestOf = (dir) => {
   try {
-    const parsed = JSON.parse(readFileSync8(join5(dir, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync10(join7(dir, "package.json"), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : void 0;
   } catch {
     return void 0;
@@ -1023,7 +1246,7 @@ var holdsTests = (dir, depth = 6) => {
     if (entry.isDirectory()) {
       if (entry.name === TEST_DIR) return true;
       if (SKIP2.test(entry.name) || depth === 0) continue;
-      if (holdsTests(join6(dir, entry.name), depth - 1)) return true;
+      if (holdsTests(join8(dir, entry.name), depth - 1)) return true;
       continue;
     }
     if (TEST_FILE.test(entry.name)) return true;
@@ -1064,16 +1287,26 @@ var packagesWithoutTypecheck = {
 var sumOfCounts = {
   id: "sumOfCounts",
   probe: { ...captured("src/a.ts:1\nsrc/b.ts:0\n"), expect: 1 },
+  readingParams: ["match"],
   run: async ({ params, run }) => {
     const command = stringParam("sumOfCounts", params, "command");
-    const match = new RegExp(stringParam("sumOfCounts", params, "match", ":(\\d+)$"), "gm");
-    return [...run(command).output.matchAll(match)].map(([, digits]) => Number(digits ?? 0)).filter((count) => Number.isFinite(count)).reduce((sum, count) => sum + count, 0);
+    const pattern = stringParam("sumOfCounts", params, "match", ":(\\d+)$");
+    const match = new RegExp(pattern, "gm");
+    const output = run(command).output;
+    const found = [...output.matchAll(match)];
+    if (found.length === 0 && output.trim() !== "") {
+      throw new CounterError(
+        "sumOfCounts",
+        `its match ${pattern} read nothing from ${output.trim().split("\n").length} line(s) of output (first: ${JSON.stringify(output.trim().split("\n")[0])}) \u2014 a match that cannot read the tool is not a zero`
+      );
+    }
+    return found.map(([, digits]) => Number(digits ?? 0)).filter((count) => Number.isFinite(count)).reduce((sum, count) => sum + count, 0);
   }
 };
 
 // src/counters/suppressions.ts
-import { readdirSync as readdirSync4, readFileSync as readFileSync9 } from "fs";
-import { join as join7, resolve as resolve11 } from "path";
+import { readdirSync as readdirSync4, readFileSync as readFileSync11 } from "fs";
+import { join as join9, resolve as resolve12 } from "path";
 var CODE_FILE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|vue|svelte|astro)$/;
 var SKIP3 = /^(?:node_modules|dist|coverage|\.[^.]|__fixtures__)/;
 var SUPPRESSION = /(?:eslint|oxlint|biome)-(?:disable|ignore)(?:-next-line|-line)?|@ts-expect-error|@ts-ignore/g;
@@ -1088,12 +1321,12 @@ var countIn = (dir, depth = 12) => {
   for (const entry of entries) {
     if (SKIP3.test(entry.name)) continue;
     if (entry.isDirectory()) {
-      if (depth > 0) found += countIn(join7(dir, entry.name), depth - 1);
+      if (depth > 0) found += countIn(join9(dir, entry.name), depth - 1);
       continue;
     }
     if (!CODE_FILE.test(entry.name)) continue;
     try {
-      found += readFileSync9(join7(dir, entry.name), "utf8").match(SUPPRESSION)?.length ?? 0;
+      found += readFileSync11(join9(dir, entry.name), "utf8").match(SUPPRESSION)?.length ?? 0;
     } catch {
     }
   }
@@ -1107,14 +1340,14 @@ var suppressionCount = {
   },
   run: async ({ cwd, params }) => {
     const roots = stringsParam(params, "roots", ["."]);
-    return roots.reduce((sum, root) => sum + countIn(resolve11(cwd, root)), 0);
+    return roots.reduce((sum, root) => sum + countIn(resolve12(cwd, root)), 0);
   }
 };
 
 // src/counters/tests.ts
-import { existsSync as existsSync9, mkdtempSync as mkdtempSync2, readFileSync as readFileSync10, rmSync as rmSync4 } from "fs";
+import { existsSync as existsSync10, mkdtempSync as mkdtempSync2, readFileSync as readFileSync12, rmSync as rmSync4 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join8, resolve as resolve12 } from "path";
+import { join as join10, resolve as resolve13 } from "path";
 var COUNTER = "testFailures";
 var VITEST_LINE = /^\s*Tests {2,}(.+?)\s*$/;
 var VITEST_TOTAL = /\(\d+\)$/;
@@ -1146,7 +1379,7 @@ ${output.trim().slice(-500)}`
   );
 };
 var fromReport = (path) => {
-  if (!existsSync9(path)) {
+  if (!existsSync10(path)) {
     throw new CounterError(
       COUNTER,
       `the runner wrote no report at ${path} \u2014 a crash before the reporter is not a pass`
@@ -1154,7 +1387,7 @@ var fromReport = (path) => {
   }
   let report;
   try {
-    report = JSON.parse(readFileSync10(path, "utf8"));
+    report = JSON.parse(readFileSync12(path, "utf8"));
   } catch (error) {
     throw new CounterError(
       COUNTER,
@@ -1178,14 +1411,14 @@ var fromReport = (path) => {
 };
 var reportPathFor = (cwd, params, command) => {
   const named = params.reportPath;
-  if (typeof named === "string" && named !== "") return { own: false, path: resolve12(cwd, named) };
+  if (typeof named === "string" && named !== "") return { own: false, path: resolve13(cwd, named) };
   if (!command.includes(PLACEHOLDER)) {
     throw new CounterError(
       COUNTER,
       `report: "${VITEST_JSON}" needs somewhere to put the report \u2014 write ${PLACEHOLDER} into the command (--outputFile=${PLACEHOLDER}) or give the entry a "reportPath"`
     );
   }
-  return { own: true, path: join8(mkdtempSync2(join8(tmpdir2(), "geonosis-report-")), "report.json") };
+  return { own: true, path: join10(mkdtempSync2(join10(tmpdir2(), "geonosis-report-")), "report.json") };
 };
 var testFailures = {
   id: COUNTER,
@@ -1234,11 +1467,77 @@ var testFailures = {
       run(command.replaceAll(PLACEHOLDER, path));
       return fromReport(path);
     } finally {
-      if (own) rmSync4(join8(path, ".."), { force: true, recursive: true });
+      if (own) rmSync4(join10(path, ".."), { force: true, recursive: true });
     }
   }
 };
 
+// src/counters/todos.ts
+import { existsSync as existsSync11, readdirSync as readdirSync5, readFileSync as readFileSync13 } from "fs";
+import { join as join11, resolve as resolve14 } from "path";
+var CODE_FILE2 = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|vue|svelte|astro)$/;
+var SKIP4 = /^(?:node_modules|dist|coverage|\.[^.]|__fixtures__)/;
+var PLAN_FILE = /^(\d{3,})-[a-z\d][a-z\d.-]*\.md$/;
+var plansIn = (dir) => {
+  if (!existsSync11(dir)) return /* @__PURE__ */ new Set();
+  const found = /* @__PURE__ */ new Set();
+  for (const name of readdirSync5(dir)) {
+    const number = PLAN_FILE.exec(name)?.[1];
+    if (number !== void 0) found.add(String(Number(number)));
+  }
+  return found;
+};
+var countIn2 = (dir, marker, plans, depth = 12) => {
+  let entries;
+  try {
+    entries = readdirSync5(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let found = 0;
+  for (const entry of entries) {
+    if (SKIP4.test(entry.name)) continue;
+    if (entry.isDirectory()) {
+      if (depth > 0) found += countIn2(join11(dir, entry.name), marker, plans, depth - 1);
+      continue;
+    }
+    if (!CODE_FILE2.test(entry.name)) continue;
+    let text = "";
+    try {
+      text = readFileSync13(join11(dir, entry.name), "utf8");
+    } catch {
+      continue;
+    }
+    for (const match of text.matchAll(marker)) {
+      const cited = match[1];
+      if (cited === void 0 || !plans.has(String(Number(cited)))) found += 1;
+    }
+  }
+  return found;
+};
+var orphanTodos = {
+  id: "orphanTodos",
+  probe: {
+    expect: 2,
+    input: (dir) => plant(
+      dir,
+      "src/planted.ts",
+      "// TODO: no plan named at all\n// TODO(099): a plan nobody wrote\nexport const a = 1\n"
+    )
+  },
+  readingParams: ["markers"],
+  run: async ({ cwd, params }) => {
+    const markers = stringsParam(params, "markers", ["TODO", "FIXME"]);
+    const plans = plansIn(resolve14(cwd, stringParam("orphanTodos", params, "plans", "plans")));
+    const marker = new RegExp(
+      `\\b(?:${markers.map(escapeForRegex).join("|")})\\b(?:\\((\\d+)\\))?`,
+      "g"
+    );
+    const roots = stringsParam(params, "roots", ["."]);
+    return roots.reduce((sum, root) => sum + countIn2(resolve14(cwd, root), marker, plans), 0);
+  }
+};
+
 // src/counters/typecheck.ts
 var UNRESOLVED = /error TS(?:2305|2307): ([^\n]*)/g;
 var SPECIFIER = /'([^']+)'/g;
@@ -1274,8 +1573,8 @@ var typecheckErrors = {
 };
 
 // src/counters/walk.ts
-import { existsSync as existsSync10, readFileSync as readFileSync11 } from "fs";
-import { resolve as resolve13 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
+import { resolve as resolve15 } from "path";
 var DEFAULT_REPORT2 = ".geonosis/walk-report.json";
 var CLASSES = /* @__PURE__ */ new Set([
   "buy-box-above-fold",
@@ -1319,8 +1618,8 @@ var walkFindings = {
   },
   run: async ({ cwd, params }) => {
     const relative = stringParam("walkFindings", params, "report", DEFAULT_REPORT2);
-    const path = resolve13(cwd, relative);
-    if (!existsSync10(path)) {
+    const path = resolve15(cwd, relative);
+    if (!existsSync12(path)) {
       throw new CounterError(
         "walkFindings",
         `no walk report at ${relative} \u2014 run \`geonosis-walk\` before measuring it`
@@ -1328,7 +1627,7 @@ var walkFindings = {
     }
     let report;
     try {
-      report = JSON.parse(readFileSync11(path, "utf8"));
+      report = JSON.parse(readFileSync14(path, "utf8"));
     } catch (error) {
       throw new CounterError(
         "walkFindings",
@@ -1362,7 +1661,9 @@ var COUNTERS = [
   oxlintErrors,
   oxlintRule,
   oxlintWarnings,
+  orphanTodos,
   packagesWithoutTypecheck,
+  probelessRules,
   runtimeCodeShipped,
   sumOfCounts,
   testFailures,
@@ -1383,7 +1684,7 @@ var counterById = (id) => {
 
 // src/report.ts
 var WIDTH = 28;
-var formatReport = ({ measurements, rewritten }) => {
+var formatReport = ({ measurements, refusals, rewritten }) => {
   const lines = measurements.map((one) => {
     if (one.verdict === "skipped") {
       return `  SKIP ${one.key}: not measured by --tier ${one.tier}`;
@@ -1396,8 +1697,14 @@ var formatReport = ({ measurements, rewritten }) => {
     if (one.verdict === "shrank") return `${head}  <-- improved -${one.baseline - one.now}`;
     return head;
   });
+  lines.push(...refusals.map((one) => `  CANNOT MEASURE ${one.key}: ${one.reason}`));
   const grew = measurements.filter((one) => one.verdict === "grew");
-  if (grew.length > 0) {
+  if (refusals.length > 0) {
+    lines.push(
+      "",
+      `ratchet FAIL \u2014 ${refusals.length} counter(s) could not be measured, and a gate that cannot measure has not passed. The baseline was left exactly as it was. Next: run each counter's own command by hand \u2014 ${refusals.map((one) => one.key).join(", ")} \u2014 and fix what it prints.`
+    );
+  } else if (grew.length > 0) {
     lines.push(
       "",
       "ratchet FAIL \u2014 debt grew. Fix it, or say in the commit message why the baseline goes up."
@@ -1419,6 +1726,7 @@ var formatProve = ({ proofs, proven }) => {
     }
     if (one.verdict === "cannot-measure") return `  CANNOT MEASURE ${one.key}: ${one.reason}`;
     if (one.verdict === "cannot-fail") return `  CANNOT FAIL ${one.key}: read 0`;
+    if (one.verdict === "unproven") return `  UNPROVEN ${one.key}: ${one.reason}`;
     if (one.verdict === "misread") {
       return `  MISREAD ${one.key}: read ${one.reading} where its probe planted ${one.expected}`;
     }
@@ -1433,6 +1741,11 @@ var formatProve = ({ proofs, proven }) => {
 };
 
 export {
+  ENVELOPES_DIR,
+  envelopePath,
+  UnbalancedEnvelope,
+  writeEnvelope,
+  versionOf,
   heavyLockPath,
   acquireExclusive,
   CONFIG_FILE,

package/dist/cli.js

@@ -4,8 +4,10 @@ import {
   formatProve,
   formatReport,
   runProve,
-  runRatchet
-} from "./chunk-HBM6F3GO.js";
+  runRatchet,
+  versionOf,
+  writeEnvelope
+} from "./chunk-H4PLCM5J.js";
 
 // src/cli.ts
 import process from "process";
@@ -100,6 +102,19 @@ var holdTheLock = async (ms) => {
 `);
   return 0;
 };
+var ENVELOPE_NEXT = "geonosis-ratchet --print-config-shape, then count the entries in geonosis.ratchet.json \u2014 a run that measured fewer counters than the config named is a bug in this tool, not in the tree it measured";
+var envelopeOf = (result, durationMs) => ({
+  considered: result.considered,
+  durationMs,
+  excused: result.measurements.flatMap(
+    (one) => one.verdict === "skipped" ? [{ path: one.key, reason: `not measured by --tier ${one.tier}` }] : []
+  ),
+  findings: result.measurements.filter((one) => one.verdict === "grew"),
+  read: result.measurements.filter((one) => one.verdict !== "skipped").length,
+  refused: result.refusals.map((one) => ({ path: one.key, reason: one.reason })),
+  tool: "ratchet",
+  version: versionOf(import.meta.url)
+});
 var measure = async () => {
   if (holdMs !== void 0) return holdTheLock(holdMs);
   if (proving) {
@@ -112,8 +127,17 @@ var measure = async () => {
     process.stdout.write(formatProve(proof));
     return proof.proven ? 0 : 2;
   }
+  const startedAt = Date.now();
   const result = await runRatchet({ counters: COUNTERS, cwd, tier });
   process.stdout.write(formatReport(result));
+  const at = writeEnvelope({
+    envelope: envelopeOf(result, Date.now() - startedAt),
+    next: ENVELOPE_NEXT,
+    root: cwd
+  });
+  process.stdout.write(`envelope: ${at}
+`);
+  if (result.refusals.length > 0) return 2;
   return result.measurements.some((one) => one.verdict === "grew") ? 1 : 0;
 };
 try {

package/dist/index.d.ts

@@ -76,6 +76,14 @@ type Counter = {
      * nobody configured says nothing about the mode they did.
      */
     probe?: CounterProbe | CounterProbe[];
+    /**
+     * The params that change WHAT this counter reads (a `match`), as opposed to where it looks.
+     * #140: a configured reading the probe never exercises can be wrong in a way the probe cannot
+     * see — during.day's mis-escaped match read 0, was certified PROVEN, and the false win was
+     * banked into the baseline. A config customizing one of these must declare `probe: { sample,
+     * expect }` beside it, or the prove line says UNPROVEN.
+     */
+    readingParams?: string[];
     run: (context: CounterContext) => Promise<number>;
 };
 /** One line of `geonosis.ratchet.json`'s `counters` array. */
@@ -134,6 +142,11 @@ type Proof = {
     key: string;
     reason: string;
     verdict: 'cannot-measure';
+} | {
+    counter: string;
+    key: string;
+    reason: string;
+    verdict: 'unproven';
 }
 /**
  * Not a counter: `--exclusive` itself, measured by running two of it. A lock is a claim about the
@@ -157,8 +170,24 @@ type ProveResult = {
     /** False as soon as one counter could not be shown to read its own planted finding. */
     proven: boolean;
 };
+/** A counter whose tool could not be read. Never a number, and never a silent zero. */
+type Refusal = {
+    key: string;
+    reason: string;
+};
 type RatchetResult = {
+    /**
+     * How many counters the config named. The denominator: `considered === measurements.length +
+     * refusals.length`, and a run whose two do not add up has lost one somewhere between the config
+     * and the report.
+     */
+    considered: number;
     measurements: Measurement[];
+    /**
+     * Every counter that blew up, not just the first. The throw that used to leave the run at the
+     * first failure also left every counter behind it unrun and unreported.
+     */
+    refusals: Refusal[];
     /** True when the baseline file was rewritten because something shrank. */
     rewritten: boolean;
 };
@@ -178,6 +207,80 @@ declare const loadConfig: (cwd: string) => RatchetConfig;
  */
 declare const resolveBaseline: (cwd: string) => string;
 
+/**
+ * The report envelope: what a tool CONSIDERED, against what it actually read.
+ *
+ * Four denominator bugs landed in one day — a migrations run that reported on three of four files,
+ * a plan check that printed `PASS — 0 plan(s)` over a directory of twenty-one, a parity run over a
+ * tree the second config ignored, a chains validator that walked a list it had already filtered.
+ * Every one of them was GREEN, and every one of them was green because the tool published the
+ * numerator and nobody published the denominator.
+ *
+ * So every gate writes this, and the law is arithmetic:
+ *
+ *     considered === read + refused.length + excused.length
+ *
+ * checked HERE, at write time. A tool whose own accounting does not add up has not measured what it
+ * says it measured, so it renders no verdict at all: the write throws, the file is not created, and
+ * the bin exits 2. That is deliberately harsher than a failing gate — a wrong verdict is worse than
+ * no verdict, and a tool that has lost count of its own inputs cannot tell which it is.
+ *
+ * `refused` and `excused` are both "considered and NOT read". They differ in whose fault it is:
+ * refused is the tool unable to read the thing (an unparseable migration, a counter whose command
+ * blew up), excused is the thing legitimately exempt (a contract-migration marker the gate believed,
+ * a step the run never reached, a plan written before the contract). Both carry a reason, because a
+ * bucket without reasons is just a smaller silence.
+ */
+type EnvelopeEntry = {
+    /** What was not read — a file, a counter key, a step id. Whatever the tool names its inputs by. */
+    path: string;
+    /** Why it was not read, in a sentence a reader can act on. */
+    reason: string;
+};
+type ReportEnvelope = {
+    /** Everything this run took as its input. The denominator. */
+    considered: number;
+    durationMs: number;
+    excused: EnvelopeEntry[];
+    /** Whatever the tool found. Shape is the tool's own; nothing here reads into it. */
+    findings: unknown[];
+    /** How many of `considered` the run actually read. The numerator. */
+    read: number;
+    refused: EnvelopeEntry[];
+    /** The name the envelope is filed under, and the name a refusal is reported against. */
+    tool: string;
+    /** The build that wrote it. An envelope that cannot name its build dates nothing. */
+    version: string;
+};
+/** Where every tool writes, and the one directory the doctor's envelope check reads. */
+declare const ENVELOPES_DIR = ".geonosis/envelopes";
+declare const envelopePath: (root: string, tool: string) => string;
+/** A run whose accounting does not add up. Never a verdict — the refusal to render one. */
+declare class UnbalancedEnvelope extends Error {
+    constructor(message: string);
+}
+/**
+ * Writes the envelope, or refuses. Returns the path written so a caller can print it.
+ *
+ * The check is before the write and not after it, because a file on disk is a verdict: the doctor
+ * would read a half-true envelope and report on numbers nobody stands behind.
+ */
+declare const writeEnvelope: ({ envelope, next, root, }: {
+    envelope: ReportEnvelope;
+    /** The command a reader should run to see the accounting for themselves. */
+    next: string;
+    root: string;
+}) => string;
+/**
+ * The version of the package a module belongs to, found by walking up to the nearest manifest.
+ *
+ * Called with `import.meta.url`, it answers the same in `src/` under vitest and in the bundled
+ * `dist/` a bin loads — which is the whole point, because the envelope a consumer's CI writes is
+ * written by the build, and a version baked in at compile time would be the version of whoever
+ * bundled it.
+ */
+declare const versionOf: (moduleUrl: string) => string;
+
 declare const COUNTERS: Counter[];
 declare const counterById: (id: string) => Counter;
 
@@ -251,7 +354,7 @@ declare const runRatchet: ({ counters, cwd, tier, }: {
  * the tier left out says so by name — printing a number for it would be the stale OK this exists
  * to prevent.
  */
-declare const formatReport: ({ measurements, rewritten }: RatchetResult) => string;
+declare const formatReport: ({ measurements, refusals, rewritten }: RatchetResult) => string;
 declare const formatProve: ({ proofs, proven }: ProveResult) => string;
 
 /**
@@ -270,4 +373,4 @@ declare const formatProve: ({ proofs, proven }: ProveResult) => string;
  */
 declare const runCommand: (cwd: string, counterId: string, env?: NodeJS.ProcessEnv) => (command: string) => CommandResult;
 
-export { CONFIG_FILE, COUNTERS, type CommandResult, type Counter, type CounterConfig, type CounterContext, CounterError, type CounterProbe, type Holder, type Measurement, type Proof, type ProveResult, type RatchetConfig, type RatchetResult, type Verdict, acquireExclusive, counterById, formatProve, formatReport, heavyLockPath, keyOf, loadConfig, resolveBaseline, runCommand, runProve, runRatchet };
+export { CONFIG_FILE, COUNTERS, type CommandResult, type Counter, type CounterConfig, type CounterContext, CounterError, type CounterProbe, ENVELOPES_DIR, type EnvelopeEntry, type Holder, type Measurement, type Proof, type ProveResult, type RatchetConfig, type RatchetResult, type Refusal, type ReportEnvelope, UnbalancedEnvelope, type Verdict, acquireExclusive, counterById, envelopePath, formatProve, formatReport, heavyLockPath, keyOf, loadConfig, resolveBaseline, runCommand, runProve, runRatchet, versionOf, writeEnvelope };

package/dist/index.js

@@ -2,8 +2,11 @@ import {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  ENVELOPES_DIR,
+  UnbalancedEnvelope,
   acquireExclusive,
   counterById,
+  envelopePath,
   formatProve,
   formatReport,
   heavyLockPath,
@@ -12,14 +15,19 @@ import {
   resolveBaseline,
   runCommand,
   runProve,
-  runRatchet
-} from "./chunk-HBM6F3GO.js";
+  runRatchet,
+  versionOf,
+  writeEnvelope
+} from "./chunk-H4PLCM5J.js";
 export {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  ENVELOPES_DIR,
+  UnbalancedEnvelope,
   acquireExclusive,
   counterById,
+  envelopePath,
   formatProve,
   formatReport,
   heavyLockPath,
@@ -28,5 +36,7 @@ export {
   resolveBaseline,
   runCommand,
   runProve,
-  runRatchet
+  runRatchet,
+  versionOf,
+  writeEnvelope
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/ratchet",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "types": "./dist/index.d.ts",
   "description": "Debt as a number that may only shrink — one ratchet, pluggable counters.",
   "keywords": [