paperlint 2.0.0

package/scripts/rules-are-content-only.harness.mjs

@@ -0,0 +1,113 @@
+/**
+ * Colocated test for `scripts/rules-are-content-only.mjs` — a rule may not ask git.
+ * Run: `npx vigiles test scripts/rules-are-content-only.harness.mjs`
+ *
+ * 🔴 BOTH HALVES. Like its sibling, this guard's success state is silence, so silence alone is
+ * no evidence it works:
+ *   I.   QUIET on this repository's real `eslint-rules/`, and the count is asserted non-zero —
+ *        a guard that scanned nothing is also quiet, and that is the reading to rule out first.
+ *   II.  FIRES on each form the defect takes: static `import`, `require()`, dynamic `import()`,
+ *        and the `node:` prefix — the prefix matters because a set membership test that lists
+ *        only the bare specifier passes a file that writes the modern spelling.
+ *   III. QUIET on sources that merely TALK about the banned module — a comment and a string
+ *        literal. This is the half a grep cannot have, and the reason the check parses.
+ */
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const { rulesAreContentOnly, processImports } = await import(
+  join(HERE, "rules-are-content-only.mjs")
+);
+
+let n = 0;
+const check = (label, ok) => {
+  n++;
+  assert.equal(ok, true, label);
+};
+
+// ── I. quiet on the real corpus, and it actually looked ───────────────────────
+{
+  const { checked, findings } = rulesAreContentOnly({ cwd: join(HERE, "..") });
+  check(
+    `scanned something (${checked.length} rule sources)`,
+    checked.length > 0,
+  );
+  check(
+    `quiet on the real corpus (${findings.length} findings)`,
+    findings.length === 0,
+  );
+  check(
+    "mutation files are not scanned as rules",
+    !checked.some((f) => f.endsWith(".mutations.mjs")),
+  );
+}
+
+// ── II. fires on every form the defect has taken ────────────────────────────
+for (const [label, src] of [
+  [
+    "execFileSync with a git argv",
+    `import { execFileSync } from "node:child_process";
+     execFileSync("git", ["cat-file", "-e", sha]);`,
+  ],
+  [
+    "a namespaced call",
+    `import cp from "node:child_process";
+     cp.spawnSync("git", ["rev-parse", ref]);`,
+  ],
+  [
+    "execSync with a git shell line",
+    `import { execSync } from "child_process";
+     execSync("git log --oneline -1");`,
+  ],
+  ["exec, async form", `exec("git rev-list --all", cb);`],
+]) {
+  check(`FIRES on ${label}`, processImports(src).length === 1);
+}
+
+// ── III. the FALSE POSITIVE that forced the narrowing, asserted so it cannot return ──
+// 🔴 `paper-texcount.mjs` in the consumer shells out to `texcount` to count words in a .tex.
+// The first version of this check keyed on importing `child_process` at all, so it claimed that
+// rule on its first run — a false positive on an `error` gate, which is worse than a miss
+// because the gate that cannot be cleared gets switched off rather than fixed.
+for (const [label, src] of [
+  [
+    "a rule spawning texcount",
+    `import { execFileSync } from "node:child_process";
+     execFileSync("texcount", ["-brief", file]);`,
+  ],
+  [
+    "a rule spawning pdflatex",
+    `import { spawnSync } from "node:child_process";
+     spawnSync("pdflatex", [tex]);`,
+  ],
+  [
+    "importing child_process without running git",
+    `import { execFileSync } from "node:child_process";
+     export default {};`,
+  ],
+]) {
+  check(`quiet on ${label}`, processImports(src).length === 0);
+}
+
+// ── IV. quiet on sources that only MENTION it — what a grep cannot do ───────
+for (const [label, src] of [
+  [
+    "a comment naming git",
+    `// never reach for git cat-file here\nexport default {};`,
+  ],
+  ["a string literal", `export const why = "git cat-file is banned in rules";`],
+  [
+    "a reported message",
+    `export default { meta: { messages: { m: "run git cat-file? no" } } };`,
+  ],
+  [
+    "a program merely NAMED git-something",
+    `execFileSync("git-lfs-helper", []);`,
+  ],
+]) {
+  check(`quiet on ${label}`, processImports(src).length === 0);
+}
+
+console.log(`rules-are-content-only.harness: ${n} assertions passed`);

package/scripts/rules-are-content-only.mjs

@@ -0,0 +1,138 @@
+/**
+ * A RULE MAY NOT ASK GIT.
+ *
+ * 🔴 The defect it exists for, measured 2026-09-16. `paper/source` bound a paper's stage to a
+ * commit sha and verified it with `git cat-file -e`. Of four shas recorded in the consumer's
+ * front matter, ONE still resolved ninety minutes later: a squash-merge had orphaned the branch
+ * commits and `gc` collected them. A recorded sha is a pointer to a pointer, and both hops are
+ * removed by ROUTINE maintenance — squash, rebase, gc, force-push, filter-repo. Nobody is at
+ * fault, so nobody is on the hook to fix it; the rule simply turns red and gets switched off.
+ *
+ * ── THE STRONGER LEG, AND THE REASON THIS IS A FLOOR CHECK ──────────────────
+ * `actions/checkout` defaults to `fetch-depth: 1` — exactly one commit. Measured in the
+ * consumer the same day: six checkouts, not one override. So a git-reading rule does not
+ * resolve even a LIVE sha under CI, which is the one place it has to hold. Locally it stays
+ * green, so the failure is one-directional and in the flattering direction.
+ *
+ * ── WHAT IT CHECKS, AND WHY NOT A GREP ──────────────────────────────────────
+ * A `child_process` spawner called with `git` as the program, read from the AST. Parsed, not
+ * grepped, so the words `git cat-file` in this very comment are not a finding — a text guard
+ * would have to exempt itself, which is the failure mode that makes text guards unmaintainable.
+ *
+ * ⚠️ THE BOUND, stated so the check is not mistaken for more than it is. Two things pass: a
+ * rule that opens `.git/` with `fs` (indistinguishable at this level from reading a data file),
+ * and a rule that assembles the program name at runtime. Both accepted deliberately — see the
+ * note on `SPAWNERS` for the false positive that forced the predicate this narrow.
+ *
+ * Run: `node scripts/rules-are-content-only.mjs`  (exit 1 and a named rule on a finding)
+ * Tested by: `scripts/rules-are-content-only.harness.mjs` — quiet on the real corpus, firing on
+ * a planted rule.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "espree";
+import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
+
+/**
+ * 🔴 THE PREDICATE IS "RUNS GIT", NOT "SPAWNS A PROCESS", and the narrowing was forced by a
+ * FALSE POSITIVE on the consumer's corpus the hour this check shipped: `paper-texcount.mjs`
+ * shells out to `texcount` to count words in a .tex, which is a measuring tool, not history.
+ * A false positive on an `error` gate is worse than a miss — the gate that cannot be cleared
+ * gets switched off, and this one would have been switched off on its first run.
+ *
+ * ⚠️ THE COST OF NARROWING, stated rather than hidden: a rule that builds the program name at
+ * runtime (`const g = "gi" + "t"`) passes. That is accepted. The defect has taken exactly one
+ * form — a literal `git` handed to a `child_process` function — and a check that also caught
+ * the contrived form would have to claim every spawn, which is the false positive above.
+ */
+const SPAWNERS = new Set([
+  "exec",
+  "execSync",
+  "execFile",
+  "execFileSync",
+  "spawn",
+  "spawnSync",
+  "fork",
+]);
+
+/** `"git"` as the program, or `"git …"` as the head of a shell line handed to `exec`. */
+const isGit = (v) =>
+  typeof v === "string" && (v === "git" || v.startsWith("git "));
+
+/** Rule sources only: a mutation file plants defects on purpose, a harness asserts about them. */
+const isRuleSource = (f) =>
+  f.endsWith(".mjs") &&
+  !f.endsWith(".mutations.mjs") &&
+  !f.endsWith(".harness.mjs");
+
+/** @param {string} src @returns {string[]} the git invocations this source makes */
+export function processImports(src) {
+  const ast = parse(src, {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    range: false,
+  });
+  const found = [];
+  const walk = (n) => {
+    if (n === null || typeof n !== "object") return;
+    if (Array.isArray(n)) return n.forEach(walk);
+    // Both spellings of the callee: `execFileSync(…)` after a named import, and
+    // `cp.execFileSync(…)` after a namespace import. Listed, not described — the node types a
+    // check walks are the only honest statement of its coverage.
+    if (n.type === "CallExpression") {
+      const name =
+        n.callee?.type === "MemberExpression"
+          ? n.callee.property?.name
+          : n.callee?.name;
+      if (SPAWNERS.has(String(name)) && isGit(n.arguments?.[0]?.value))
+        found.push(String(n.arguments[0].value));
+    }
+    for (const k of Object.keys(n)) if (k !== "parent") walk(n[k]);
+  };
+  walk(ast);
+  return found;
+}
+
+/** @param {{cwd: string}} options */
+export function rulesAreContentOnly({ cwd }) {
+  const dir = join(cwd, "eslint-rules");
+  const checked = [];
+  const findings = [];
+  for (const f of readdirSync(dir).filter(isRuleSource)) {
+    const hits = processImports(readFileSync(join(dir, f), "utf8"));
+    // 🔴 The counter increments WITH the verdict, not before it: a `checked` that keeps
+    // counting while the verdict stops being reached is the failure recorded in the consumer's
+    // rules as "a counter that counts what it ignores".
+    checked.push(f);
+    for (const h of hits) findings.push({ file: f, specifier: h });
+  }
+  return { checked, findings };
+}
+
+if (isMain(import.meta.url)) {
+  // 🔴 `process.cwd()`, NOT the package root. A consumer installs this package and runs the
+  // script from its own repository, where the rules that matter are ITS `eslint-rules/` — the
+  // package's own are already checked by the package's own gate. Anchored to the package root
+  // the consumer's gate would re-check the same eight files and report a confident zero about
+  // rules it never opened: a counter that counts what it ignores.
+  const cwd = process.cwd();
+  const { checked, findings } = rulesAreContentOnly({ cwd });
+  if (checked.length === 0) {
+    console.error(
+      `${join(cwd, "eslint-rules")}: no rule sources. Either this is not a repository with ` +
+        `ESLint rules, or the directory moved — a silent zero here would read as a clean run.`,
+    );
+    process.exit(1);
+  }
+  for (const { file, specifier } of findings) {
+    console.error(
+      `${file}: imports \`${specifier}\`. A rule may not ask git: history is rewritten by ` +
+        `routine maintenance and CI clones one commit deep, so the fact does not survive where ` +
+        `the rule has to hold. Put the fact on disk and check it by bytes.`,
+    );
+  }
+  console.log(
+    `rules-are-content-only: ${checked.length} rule sources under ${cwd}, ${findings.length} findings`,
+  );
+  process.exit(findings.length === 0 ? 0 : 1);
+}

package/scripts/rules-are-content-only.mutations.mjs

@@ -0,0 +1,81 @@
+/**
+ * Battery for the "rule does not touch git" gate, `scripts/rules-are-content-only.mjs`.
+ *
+ * 🔴 This battery needs to be sharper than the rule. Its success state is an EMPTY LIST, which is
+ * exactly the state it teaches not to trust. A check seen only silent is indistinguishable from
+ * one that never looks.
+ *
+ * BOTH DIRECTIONS, and they must die on DIFFERENT assertions:
+ *   - `undercatch` — stops finding anything. The "quiet on clean" half stays green;
+ *     the "fires" half must fail.
+ *   - `overcatch` — calls any spawner a finding. The "fires" half stays green
+ *     (it still sees `git`), the "quiet on clean" half must fail. MEASURED: it breaks on
+ *     LIVE CORPUS (6 findings in the package's own rules) before a planted fixture with
+ *     `texcount` — and that is stronger, not weaker: real data.
+ * A battery where both mutations die on one assertion proves ONE half exists.
+ *
+ * ⚠️ The second mutation reproduces a REAL false positive: the first version of the check
+ * was keyed on the `child_process` import and in the first hour called `paper-texcount.mjs`
+ * a finding in the consumer — it calls `texcount` to count words. On an `error` gate this is
+ * worse than a miss: a gate you cannot pass gets turned off. The mutation holds this line.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "../lib/mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const GUARD = join(HERE, "rules-are-content-only.mjs");
+const HARNESS = join(HERE, "rules-are-content-only.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "undercatch — check stops finding",
+        harness: HARNESS,
+        expect: "FIRES on execFileSync with a git argv",
+        disables:
+          "the verdict itself: the check becomes that very confident green zero it was written " +
+          "to spot — it scans, counts files and renders no judgment",
+        edits: [
+          [
+            GUARD,
+            "if (SPAWNERS.has(String(name)) && isGit(n.arguments?.[0]?.value))",
+            "if (false && SPAWNERS.has(String(name)) && isGit(n.arguments?.[0]?.value))",
+          ],
+        ],
+      },
+      {
+        name: "overcatch — any spawner call becomes a finding",
+        harness: HARNESS,
+        // Fails on LIVE CORPUS, not on the texcount fixture, and this is measured: under this mutation
+        // the package's own rules yield 6 findings, meaning the "quiet on clean" half breaks
+        // before we reach the planted case. Live signal is stronger than fixture — it is real data — so
+        // it is named, not the one I expected to see.
+        expect: "quiet on the real corpus",
+        disables:
+          "the boundary of the predicate 'calls git' vs 'spawns a process' — the one that was " +
+          "set after the texcount false positive in the consumer",
+        edits: [
+          [
+            GUARD,
+            "if (SPAWNERS.has(String(name)) && isGit(n.arguments?.[0]?.value))",
+            "if (SPAWNERS.has(String(name)))",
+          ],
+        ],
+      },
+      {
+        name: "guard for empty scan stops failing",
+        harness: HARNESS,
+        expect: "scanned something",
+        disables:
+          "the answer to 'did you even look': zero found sources become silent success again, " +
+          "indistinguishable from a clean run",
+        edits: [[GUARD, 'f.endsWith(".mjs") &&', "false &&"]],
+      },
+    ],
+  }),
+);

package/scripts/rules-see-files.harness.mjs

@@ -0,0 +1,115 @@
+/**
+ * Colocated test for `scripts/rules-see-files.mjs` — the guard against a green zero.
+ * Run: `npx vigiles test scripts/rules-see-files.harness.mjs`
+ *
+ * 🔴 BOTH HALVES, and for this guard the order matters more than usual. Its success state is
+ * silence, and silence is exactly the state it was built to distrust: a guard that has only
+ * ever been seen quiet is indistinguishable from a guard that is dead. So:
+ *   I.  QUIET on this repository — every rule declared in `eslint.config.mjs` is enabled for at
+ *       least one file that exists.
+ *   II. FIRES on a planted empty glob — a throwaway project whose config declares a rule over a
+ *       glob nothing matches. The rule is syntactically fine, the config is valid, ESLint exits
+ *       0 with zero findings, and the guard is the only thing that says anything.
+ *   III. The fixture in II has a CONTROL rule that does see a file, so "fires" means "named the
+ *        blind one", not "complained about everything".
+ */
+import assert from "node:assert/strict";
+import { ESLint } from "eslint";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+const { rulesSeeFiles } = await import(join(HERE, "rules-see-files.mjs"));
+
+const TMP = realpathSync(mkdtempSync(join(tmpdir(), "rules-see-files-")));
+process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
+
+// ═════════════════════════════════════════════════════════════════════════════
+// I. QUIET ON THIS REPOSITORY
+// ═════════════════════════════════════════════════════════════════════════════
+{
+  const { rules, blind, linted } = await rulesSeeFiles({ cwd: ROOT });
+  assert.deepEqual(
+    blind,
+    [],
+    "a rule declared in eslint.config.mjs was enabled for zero files on disk — it is never " +
+      "invoked, and its zero findings mean nothing",
+  );
+  assert.ok(
+    rules.length > 0,
+    "no rules were found in eslint.config.mjs — the guard has no subject",
+  );
+  assert.ok(
+    linted > 0,
+    "ESLint linted no files at all — the guard cannot distinguish anything",
+  );
+  // Not just "not blind": the count has to be the fixtures it should be seeing. A rule that saw
+  // one file when four exist is a narrower defect of the same family.
+  const tex = rules.find((r) => r.rule === "tex/future-promise");
+  assert.ok(tex, "`tex/future-promise` is no longer declared");
+  assert.ok(
+    tex.files >= 4,
+    `\`tex/future-promise\` was enabled for ${tex.files} file(s); the four fixtures alone should ` +
+      "exceed that, so its glob is narrower than the test data it is supposed to cover",
+  );
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// II + III. FIRES ON A PLANTED EMPTY GLOB, AND NAMES THE RIGHT RULE
+// ═════════════════════════════════════════════════════════════════════════════
+{
+  const project = join(TMP, "planted");
+  mkdirSync(project, { recursive: true });
+  writeFileSync(join(project, "probe.js"), "export const x = 1;\n");
+  writeFileSync(
+    join(project, "eslint.config.mjs"),
+    [
+      "const noop = { meta: { schema: [] }, create: () => ({}) };",
+      "export default [",
+      "  {",
+      '    files: ["**/*.js"],',
+      "    plugins: { probe: { rules: { alive: noop, dead: noop } } },",
+      '    rules: { "probe/alive": "warn" },',
+      "  },",
+      "  {",
+      // Nothing in this project has that extension. The block is valid, the rule is valid,
+      // and it will never be called.
+      '    files: ["**/*.nosuchextension"],',
+      "    plugins: { probe: { rules: { alive: noop, dead: noop } } },",
+      '    rules: { "probe/dead": "warn" },',
+      "  },",
+      "];",
+      "",
+    ].join("\n"),
+  );
+
+  // First: confirm the thing the guard exists to distrust. ESLint itself is perfectly happy.
+  const results = await new ESLint({ cwd: project }).lintFiles(["."]);
+  assert.deepEqual(
+    results.flatMap((r) => r.messages),
+    [],
+    "the planted project produced findings — it is supposed to be the silent, green, and wrong case",
+  );
+
+  const { blind, rules } = await rulesSeeFiles({ cwd: project });
+  assert.deepEqual(
+    blind,
+    ["probe/dead"],
+    "the guard did not name the rule declared over an empty glob",
+  );
+  assert.equal(
+    rules.find((r) => r.rule === "probe/alive").files,
+    1,
+    "the control rule was not credited with the file it does see — the guard reports blindness " +
+      "for everything rather than for the blind one",
+  );
+}

package/scripts/rules-see-files.mjs

@@ -0,0 +1,99 @@
+/**
+ * THE GUARD AGAINST A GREEN ZERO.
+ *
+ * 🔴 The defect it exists for, measured 2026-09-10 on the source corpus: a lint rule whose glob
+ * matches NO file is never invoked. The run exits 0 with no findings — byte-identical to the
+ * run of a rule that examined everything and passed. In that corpus a fresh clone produced
+ * RC=0 and 652 findings, and NINETEEN rules had seen no file at all. Nothing in the output said
+ * so, because there is nothing for a rule to say when it is not called.
+ *
+ * ── WHY THIS CANNOT LIVE INSIDE A RULE ──────────────────────────────────────
+ * A rule cannot report that it was not invoked; not being invoked is precisely the state in
+ * which it has no opportunity to report anything. The check therefore has to stand OUTSIDE the
+ * rules, look at the config and at the files on disk, and answer a question no individual rule
+ * can ask: "was anything actually handed to you?"
+ *
+ * ── WHAT IT CHECKS, AND WHY THAT AND NOT "THE GLOB IS NON-EMPTY" ────────────
+ * Per RULE, not per glob. The unit that goes silent is a rule, and a rule can be enabled in one
+ * block whose glob is empty while a completely different block is busy — a non-empty glob
+ * somewhere in the config is not evidence about the rule you care about. So: collect every rule
+ * declared at a severity other than `off`, lint the repository, and for each linted file ask
+ * ESLint what the effective config is. A rule enabled for zero linted files is BLIND.
+ *
+ * Run: `node scripts/rules-see-files.mjs`  (exit 1 and a named rule when something is blind)
+ * Tested by: `scripts/rules-see-files.harness.mjs` — both halves, quiet here and firing on a
+ * planted empty glob.
+ */
+import { ESLint } from "eslint";
+import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
+
+/** ESLint accepts severities as strings and as numbers; `off` and `0` are the same thing. */
+const isOff = (v) => {
+  const s = Array.isArray(v) ? v[0] : v;
+  return s === "off" || s === 0;
+};
+
+/**
+ * @param {{cwd: string}} options
+ * @returns {Promise<{rules: {rule: string, files: number}[], linted: number, blind: string[]}>}
+ */
+export async function rulesSeeFiles({ cwd }) {
+  const configPath = new URL(
+    "eslint.config.mjs",
+    `file://${cwd.endsWith("/") ? cwd : cwd + "/"}`,
+  );
+  const config = (await import(configPath.href)).default;
+
+  const declared = new Set();
+  for (const block of config)
+    for (const [id, severity] of Object.entries(block.rules ?? {}))
+      if (!isOff(severity)) declared.add(id);
+
+  const eslint = new ESLint({ cwd });
+  // `errorOnUnmatchedPattern: false` is NOT set on purpose. A repository where `.` matches
+  // nothing at all is a different failure, and it should be loud in its own words rather than
+  // arrive here disguised as "every rule is blind".
+  const results = await eslint.lintFiles(["."]);
+
+  const seen = new Map([...declared].map((id) => [id, 0]));
+  for (const result of results) {
+    const effective = await eslint.calculateConfigForFile(result.filePath);
+    for (const id of declared)
+      if (effective.rules?.[id] && !isOff(effective.rules[id]))
+        seen.set(id, seen.get(id) + 1);
+  }
+
+  const rules = [...seen]
+    .map(([rule, files]) => ({ rule, files }))
+    .sort((a, b) => a.rule.localeCompare(b.rule));
+  return {
+    rules,
+    linted: results.length,
+    blind: rules.filter((r) => r.files === 0).map((r) => r.rule),
+  };
+}
+
+// CLI entry. Guarded so the harness can import the function without running the process exit.
+// 🔴 `isMain`, NOT `import.meta.url === `file://${process.argv[1]}``. Node resolves the entry
+// point to its REAL path for `import.meta.url` but leaves `process.argv[1]` as typed, so through
+// a symlink the two are not equal and the CLI silently does not run — the process exits 0 having
+// done nothing. The consumer reaches these scripts through exactly such a symlink. Observed 14.09
+// on run 34784079821: `extract-pdf-facts.mjs --strict` returned RC=0 and created no facts file.
+if (isMain(import.meta.url)) {
+  const { rules, linted, blind } = await rulesSeeFiles({ cwd: process.cwd() });
+  for (const { rule, files } of rules)
+    console.log(`${String(files).padStart(4)}  ${rule}`);
+  console.log(`\n${rules.length} rule(s) declared, ${linted} file(s) linted.`);
+  if (blind.length) {
+    console.log(
+      `\n✗ ${blind.length} rule(s) saw NO file and were never invoked:\n` +
+        blind.map((r) => `    ${r}`).join("\n") +
+        "\n\n  A rule that is never invoked reports exactly what a rule that passed reports.\n" +
+        "  Fix the glob it is declared on, or delete the declaration — do not leave it green.",
+    );
+    process.exit(1);
+  }
+  console.log(
+    "✓ every declared rule was enabled for at least one file on disk.",
+  );
+}

package/scripts/rules-see-files.mutations.mjs

@@ -0,0 +1,131 @@
+/**
+ * Mutation battery for the guard against a green zero, `scripts/rules-see-files.mjs`.
+ * Run: `node scripts/rules-see-files.mutations.mjs` (not `vigiles test` — not a harness).
+ *
+ * 🔴 WHY THIS GUARD NEEDS A MUTATION BATTERY MORE THAN ANYTHING ELSE HERE. Its success state
+ * is an empty list, which is the exact state it was built to distrust. A guard that has only
+ * been observed quiet is indistinguishable from a guard that does nothing — that is the whole
+ * premise of the thing being guarded, applied to the guard itself.
+ *
+ * BOTH DIRECTIONS, one mutation each, and they must die on DIFFERENT assertions:
+ *   - `under-report` makes the guard incapable of ever calling a rule blind. The quiet half of
+ *     its harness stays green; the FIRING half must go red.
+ *   - `over-report` makes it call everything blind. The firing half stays green (it still names
+ *     `probe/dead`, among others); the QUIET half must go red.
+ * A battery in which both mutations died on the same assertion would prove only that one of the
+ * two halves exists.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const GUARD = "scripts/rules-see-files.mjs";
+const HARNESS = "scripts/rules-see-files.harness.mjs";
+
+// Coverage mode — see `scripts/run-mutations.mjs` guard 2.
+if (process.env.MUTATIONS_REPORT_COVERAGE) {
+  console.log(`MUTATION-COVERS\t${HARNESS}`);
+  process.exit(0);
+}
+
+const PRISTINE = readFileSync(GUARD, "utf8");
+
+const M = [
+  [
+    "under-report",
+    "never call a rule blind — the guard becomes the silent green it exists to catch",
+    "blind: rules.filter((r) => r.files === 0).map((r) => r.rule)",
+    "blind: [] /* MUT */",
+  ],
+  [
+    "over-report",
+    "call every rule blind — the guard becomes noise, and noise gets switched off within a day",
+    "      if (effective.rules?.[id] && !isOff(effective.rules[id]))\n        seen.set(id, seen.get(id) + 1);",
+    "      if (false)\n        seen.set(id, seen.get(id) + 1); /* MUT */",
+  ],
+];
+
+const runHarness = () => {
+  try {
+    execFileSync("npx", ["vigiles", "test", HARNESS], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { failed: false, out: "" };
+  } catch (e) {
+    return { failed: true, out: (e.stdout ?? "") + (e.stderr ?? "") };
+  }
+};
+
+{
+  const base = runHarness();
+  if (base.failed) {
+    console.log(
+      "❌ THE HARNESS IS RED BEFORE ANY MUTATION — the battery cannot tell a killed mutation " +
+        "from that:\n" +
+        base.out.slice(-1500),
+    );
+    process.exit(1);
+  }
+}
+
+let ok = 0;
+let bad = 0;
+const rows = [];
+for (const [label, what, from, to] of M) {
+  const hits = PRISTINE.split(from).length - 1;
+  if (hits !== 1) {
+    console.log(
+      `❌ ${label}: TARGET ${hits === 0 ? "NOT FOUND" : `NOT UNIQUE (${hits})`} — ${from.slice(0, 70)}`,
+    );
+    bad++;
+    continue;
+  }
+  writeFileSync(GUARD, PRISTINE.replace(from, to));
+  const on = readFileSync(GUARD, "utf8");
+  if (!on.includes(to) || on.includes(from)) {
+    console.log(
+      `❌ ${label}: THE MUTATION DID NOT LAND (checked by re-reading the file)`,
+    );
+    bad++;
+    writeFileSync(GUARD, PRISTINE);
+    continue;
+  }
+  const { failed, out } = runHarness();
+  writeFileSync(GUARD, PRISTINE);
+  if (readFileSync(GUARD, "utf8") !== PRISTINE) {
+    console.log(`❌ ${label}: THE ROLLBACK FAILED`);
+    bad++;
+    continue;
+  }
+  const at = (out.match(/rules-see-files\.harness\.mjs:(\d+)/) ?? [])[1];
+  const msg = (out.match(/AssertionError[^:]*: ([^\n]+)/) ?? [])[1] ?? "";
+  if (failed) {
+    ok++;
+    rows.push([
+      label,
+      what,
+      ((at ? `harness:${at} · ` : "") + msg).trim().slice(0, 130),
+    ]);
+  } else {
+    console.log(
+      `🔴 ${label}: THE HARNESS IS GREEN UNDER THE MUTATION — a finding about the TEST, not a conclusion about the guard`,
+    );
+    bad++;
+  }
+}
+console.log("\n| direction | mutation | what the harness died on |");
+console.log("|---|---|---|");
+for (const [a, b, c] of rows)
+  console.log(`| \`${a}\` | ${b} | ${c.replace(/\|/g, "\\|")} |`);
+// The two must die on DIFFERENT lines, or only one half of the guard is actually tested.
+const lines = rows.map(
+  ([, , where]) => (where.match(/harness:(\d+)/) ?? [])[1],
+);
+if (rows.length === 2 && lines[0] && lines[0] === lines[1]) {
+  console.log(
+    "\n🔴 BOTH mutations died on the SAME assertion — only one half of the guard is tested",
+  );
+  bad++;
+}
+console.log(`\n${ok} mutation(s) killed, ${bad} problem(s)`);
+process.exit(bad ? 1 : 0);