paperlint 2.0.0

package/scripts/check.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * `npm run check` — ONE command you run on yourself before pushing.
+ *
+ * ── WHY IT EXISTS, AND IT IS A MEASURED FAILURE, NOT A TIDINESS IDEA ───────────────────────
+ * On 2026-09-19 a change to `paper/research-question` was pushed that broke the test suite.
+ * The gates were run afterwards — `lint`, `check:readme`, `check:globs`, `check:content-only`,
+ * and the rule's own mutation battery, all green — but `npm test` and `test:install` were not,
+ * because there were eleven separate scripts and no way to run them except from memory. Five
+ * callers across two files had been left behind by the change, and the suite said so; nobody
+ * asked it.
+ *
+ * A prose reminder would not have helped. The same class is on record from vigiles: three
+ * agents were handed a list of five gate commands, all three reported "gates 5/5 green", and
+ * not one ran the harness tests — they were not on the list.
+ *
+ * 🔴 SO THE LOAD-BEARING PART HERE IS NOT THE LIST OF GATES — IT IS THE TAIL. This script
+ * prints which CI jobs it does NOT reproduce, and why. A check that is silent about its own
+ * boundary reads as complete, which is the same class as a counter that counts what it ignores.
+ *
+ * ── WHAT KEEPS THE LIST FROM GOING STALE ───────────────────────────────────────────────────
+ * `check.harness.mjs` sits beside it and pulls the job names OUT OF THE WORKFLOW ITSELF,
+ * requiring every one to be either covered here or named in `NOT_COVERED` with a reason. Add a
+ * job to CI and the harness goes red the same day — the list cannot quietly fall behind.
+ *
+ * ── WHY IT DOES NOT REPLACE THE CI JOBS ────────────────────────────────────────────────────
+ * The jobs solve a different problem: a different environment (TeX Live exists only in
+ * `build-e2e`, and macOS only in its second matrix cell) and a named culprit per bond. One command cannot do that and should
+ * not try. This is about a human being able to check themselves BEFORE the push.
+ *
+ * ── NO `--fast` FLAG, ON PURPOSE ───────────────────────────────────────────────────────────
+ * A subset flag re-creates the exact failure above: the cheap half gets run and reported as
+ * "the gates". The slow steps instead SKIP LOUDLY when their prerequisite is genuinely absent
+ * (no TeX, no network), and the tail names every skip. "I ran check" then means one thing.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Every local gate, in the order a human wants them: cheapest and most likely to fail first,
+ * so a typo does not cost eight minutes. `job` names the CI job this step reproduces, and the
+ * harness checks those names against the real workflow.
+ *
+ * Each gate says how it runs in one of two ways:
+ *   - `script` — an npm script that people also run by hand (`build`, `lint`, `fmt:check`, `test`);
+ *   - `run` — the command itself, for checks that have no npm script of their own. Keeping these
+ *     out of package.json keeps its script list short; this file is the one place they are listed.
+ * Programs installed by npm (`vigiles`, `eslint`) are found because `node_modules/.bin` is put
+ * first on PATH below, the same way `npm run` does it.
+ */
+const locked = (...cmd) => ["node", "scripts/exclusive.mjs", ...cmd];
+
+export const GATES = [
+  {
+    name: "the package compiles",
+    job: "gates",
+    script: "build",
+    // First because everything below imports from `dist/`. A stale build makes every later
+    // failure a lie about its own cause.
+  },
+  {
+    name: "rules and scripts lint",
+    job: "gates",
+    script: "lint",
+  },
+  {
+    name: "skills lint, and the vigiles marks in README.md and CLAUDE.md",
+    job: "gates",
+    run: locked("vigiles", "lint", ".", "README.md"),
+    // README.md is passed to `vigiles lint` by name: it is not an instruction file, so vigiles
+    // would not open it on its own. The marks tie the `paperlint init` and `paperlint new` sections to the
+    // functions that implement them, and the lint fails when either function is renamed.
+  },
+  {
+    name: "formatting",
+    job: "gates",
+    script: "fmt:check",
+    // Prettier defaults, the same config as vigiles. What it must not touch — compiled
+    // SKILL.md, fixture data, raw runs — is listed in `.prettierignore` with the reason.
+  },
+  {
+    name: "every declared rule is enabled for a file on disk",
+    job: "gates",
+    run: locked("node", "scripts/rules-see-files.mjs"),
+  },
+  {
+    name: "rules read content, not the filesystem",
+    job: null,
+    // 🔴 Deliberately not in CI, and this is the one asymmetry worth stating rather than
+    // hiding: the check is about a property of the rules' source, which cannot change between
+    // a developer's tree and the runner's. Running it twice buys nothing; NOT running it
+    // locally buys a defect that reaches review.
+    reason:
+      "source-only property — identical in every environment, so CI adds nothing",
+    run: locked("node", "scripts/rules-are-content-only.mjs"),
+  },
+  {
+    name: "every test — vitest over *.test.ts, then the vigiles harnesses (npm test)",
+    job: "gates",
+    script: "test",
+  },
+  {
+    // vitest transpiles without type-checking, so the tests' types are checked here.
+    name: "the tests type-check",
+    job: "gates",
+    run: ["tsc", "-p", "tsconfig.test.json"],
+  },
+  {
+    name: "mutation batteries are frozen — none new, none grown (#52)",
+    job: "gates",
+    run: locked("node", "scripts/mutation-batteries-frozen.mjs"),
+  },
+  {
+    name: "legacy layer exemptions are frozen — none new, none grown (#76)",
+    job: "gates",
+    run: locked("node", "scripts/layer-legacy-frozen.mjs"),
+  },
+  {
+    name: "mutation batteries — every guard is killed by its own assertion",
+    job: "gates",
+    run: locked("node", "scripts/run-mutations.mjs"),
+  },
+  {
+    name: "install e2e — pack, install under npm and pnpm, run the binary",
+    job: "gates",
+    run: locked("node", "test/e2e/install.mjs"),
+  },
+  {
+    name: "build e2e — a real pdflatex, and the PDF's fonts are measured",
+    job: "build-e2e",
+    run: locked("node", "test/e2e/build.mjs"),
+  },
+  {
+    name: "banal e2e — the real banal on pdf.js-written XML gives banal-on-pdftohtml's numbers",
+    job: "build-e2e",
+    run: locked("node", "test/e2e/banal.mjs"),
+  },
+  {
+    name: "toolchain e2e — real TeX Live into $RPP_TEXLIVE_DIR, then a build with only it on PATH",
+    job: "build-e2e",
+    run: locked("node", "test/e2e/toolchain.mjs"),
+  },
+];
+
+/** The command line a gate runs, as an argument list. */
+export function commandOf(gate) {
+  return gate.script ? ["npm", "run", "-s", gate.script] : gate.run;
+}
+
+/**
+ * CI jobs this command does NOT reproduce. Each needs a reason a reader can check, because an
+ * unexplained gap is indistinguishable from an oversight — which is what the harness enforces.
+ */
+export const NOT_COVERED = {
+  // build-e2e's macOS cell is the one part of a covered job no local command can stand in for:
+  // it exists because issue #9 appeared on macOS alone (/var is a symlink to /private/var).
+  merge:
+    "dependabot-automerge.yml merges the bot's own pull requests once CI is green. It checks " +
+    "nothing itself; there is no local equivalent because it acts on GitHub, not on the tree.",
+  release:
+    "release.yml publishes to npm and tags a GitHub release; running it locally would publish. " +
+    "What can break it silently, the release notes, is rendered by scripts/release-config.test.ts in npm test.",
+  validate:
+    "pr-title.yml checks the pull request's TITLE (the squash commit semantic-release reads), " +
+    "which exists only on GitHub, not in the tree.",
+};
+
+/**
+ * Exit 77 means "declared skip" — the same code vigiles' runner uses (`SKIP_EXIT_CODE`), and the
+ * one lib/mutation-driver.mjs already recognizes. The e2e steps exit 77 when a tool they need is
+ * absent and --strict is off. Anything else nonzero is a failure.
+ *
+ * 🔴 A SKIP IS A THIRD OUTCOME. Until the Codex review on #45 the e2e steps exited 0 on a skip,
+ * this loop counted that as a pass, and `skipped` below was declared and never filled: a machine
+ * without pnpm or TeX printed "all gates passed" for runs that never happened.
+ */
+export const SKIP_EXIT = 77;
+export function outcome(status) {
+  if (status === 0) return "pass";
+  if (status === SKIP_EXIT) return "skip";
+  return "fail";
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const BIN_FIRST_PATH = [join(ROOT, "node_modules", ".bin"), process.env.PATH]
+    .filter(Boolean)
+    .join(delimiter);
+  const failed = [];
+  const skipped = [];
+
+  for (const g of GATES) {
+    process.stdout.write(`── ${g.name}\n`);
+    const [cmd, ...args] = commandOf(g);
+    const r = spawnSync(cmd, args, {
+      cwd: ROOT,
+      stdio: "inherit",
+      encoding: "utf8",
+      env: { ...process.env, PATH: BIN_FIRST_PATH },
+    });
+    // 🔴 The exit code is read from the command itself, never from a pipe. `cmd | tail && …`
+    // reports the FILTER's status, which is almost always zero — that is how a red harness
+    // shipped on 2026-09-16.
+    const o = outcome(r.status);
+    if (o === "pass") continue;
+    const shown = commandOf(g).join(" ");
+    if (o === "skip") skipped.push(`${g.name}  (${shown} → ${SKIP_EXIT})`);
+    else failed.push(`${g.name}  (${shown} → ${r.status})`);
+  }
+
+  console.log("");
+  if (failed.length) {
+    console.error("🔴 gates failed:");
+    for (const f of failed) console.error(`   ${f}`);
+  } else {
+    const passed = GATES.length - skipped.length;
+    console.log(
+      `✓ ${passed} gate(s) passed${skipped.length ? `, ${skipped.length} SKIPPED — not run, not passed` : ""}`,
+    );
+  }
+  if (skipped.length) for (const s of skipped) console.log(`⏳ skipped: ${s}`);
+
+  // THE TAIL. Not decoration — the reason this file exists rather than a list in a doc.
+  console.log("\nWhat this command does NOT cover:");
+  for (const [job, why] of Object.entries(NOT_COVERED)) {
+    console.log(`  CI job «${job}» — ${why}`);
+  }
+  const localOnly = GATES.filter((g) => g.job === null);
+  for (const g of localOnly) {
+    console.log(`  (and «${g.name}» runs ONLY here — ${g.reason})`);
+  }
+
+  process.exit(failed.length ? 1 : 0);
+}
+
+export { ROOT, existsSync, join };

package/scripts/check.mutations.mjs

@@ -0,0 +1,110 @@
+/**
+ * Battery for `npm run check` — and the thing under test is NOT "does it run every gate".
+ * That part is visible: you watch it happen. What is invisible, and therefore what this kills,
+ * is whether the harness beside it can still tell when the gate list has fallen behind CI.
+ *
+ * 🔴 The failure mode this whole file exists against, measured 2026-09-19: a list of gates kept
+ * by hand becomes a fossil the day after it is written. `check.harness.mjs` is the mechanism that
+ * stops that — it reads job names out of the workflow rather than trusting a copy — and its
+ * success state is silence. "It passed" and "it cannot fail" look identical from outside.
+ *
+ * Each case removes ONE property and names the assertion that must notice.
+ */
+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 CHECK = join(HERE, "check.mjs");
+const HARNESS = join(HERE, "check.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "a CI job stops being accounted for — the tail goes quiet about its own boundary",
+        harness: HARNESS,
+        // No job name here: the harness reads every workflow in directory order, so which job
+        // fails first depends on file names, not on what this mutation proves.
+        expect:
+          "is either reproduced by a gate or named in NOT_COVERED with a reason",
+        disables:
+          "the reason this command is not just a shell alias. Emptying NOT_COVERED removes the " +
+          "one sentence that tells a reader what the green does NOT mean — and a check silent " +
+          "about its boundary reads as complete, which is the counter-that-counts-what-it-ignores " +
+          "class this repository keeps re-finding",
+        edits: [
+          [
+            CHECK,
+            "export const NOT_COVERED = {",
+            "export const NOT_COVERED = { }; const _unused = {",
+          ],
+        ],
+      },
+      {
+        name: "a gate names a CI job that does not exist — coverage on paper, none in fact",
+        harness: HARNESS,
+        expect: "names a job that really exists in a workflow",
+        disables:
+          "the link between the list and the workflow. A dead job name is WORSE than a missing " +
+          "one: it reads as coverage and delivers nothing, and nothing else in the repository " +
+          "would ever contradict it",
+        // 🔴 The anchor is a gate whose job is ALSO claimed by other gates (`gates`), and that
+        // is not incidental. Renaming a solely-claimed job — `build-e2e` — kills the FIRST
+        // assertion instead, because that job becomes uncovered before anyone asks whether the
+        // new name exists. Measured: the driver reported "RED but a DIFFERENT case". Two
+        // assertions overlapping is fine; a battery that cannot tell them apart is not.
+        edits: [
+          [
+            CHECK,
+            'job: "gates",\n    run: locked("vigiles", "lint"',
+            'job: "gates-renamed-in-ci",\n    run: locked("vigiles", "lint"',
+          ],
+        ],
+      },
+      {
+        name: "a gate points at an npm script nobody can run",
+        harness: HARNESS,
+        expect: "maps to a script that exists",
+        disables:
+          "the guarantee that every listed gate is runnable. A renamed script fails at the exact " +
+          "moment someone is trusting the list — which is the worst possible moment to find out",
+        edits: [[CHECK, 'script: "fmt:check"', 'script: "fmt:check-renamed"']],
+      },
+      {
+        name: "a gate runs a file that is not on disk",
+        harness: HARNESS,
+        expect: "runs files that exist",
+        disables:
+          "the same guarantee for gates that name their command directly instead of an npm " +
+          "script. A moved or renamed file would only show up when someone runs the whole list",
+        edits: [
+          [
+            CHECK,
+            '"scripts/rules-are-content-only.mjs"',
+            '"scripts/rules-are-content-only-renamed.mjs"',
+          ],
+        ],
+      },
+      {
+        name: "a gate drops out of CI silently, with no reason given",
+        harness: HARNESS,
+        expect: "carries a reason",
+        disables:
+          "the cost of removing something from CI. Without this, `job: null` is the quiet way to " +
+          "take a check out of the pipeline: the local run still shows it green and nothing says " +
+          "it stopped being enforced anywhere else",
+        edits: [
+          [
+            CHECK,
+            'reason:\n      "source-only property',
+            'reasonRemoved:\n      "source-only property',
+          ],
+        ],
+      },
+    ],
+  }),
+);

package/scripts/eslint-report-guard.mjs

@@ -0,0 +1,82 @@
+/**
+ * THE GREEN-ZERO GUARD over an ESLint JSON report.
+ *
+ * 🔴 WHY THIS EXISTS. `eslint` prints findings and exits 0 when there are none — and "no findings"
+ * is byte-identical to "not one rule was handed a single file". A rule whose glob matched nothing is
+ * never invoked, and a rule that is never invoked physically cannot report that. A CI job built on
+ * the exit code alone therefore passes loudest exactly when it measured nothing.
+ *
+ * WHAT IT DOES AND DOES NOT CLAIM. It answers one question that needs no knowledge of the caller's
+ * config: *was anything linted at all*. It does NOT audit per-rule coverage — a run can lint a
+ * thousand files while one rule still sees none. That is `scripts/rules-see-files.mjs`, which reads this
+ * package's own config and cannot read yours.
+ *
+ * 🔴 IT LIVES IN A FILE, NOT INSIDE `action.yml`. An inline `node -e` blob in a composite step is
+ * unreachable from a test: the only way to exercise it is to run the whole action on a runner. This
+ * file is called by the action and by `action.harness.mjs` with the same arguments, so the harness
+ * proves the BEHAVIOUR rather than the presence of a string in YAML.
+ *
+ * Usage: node scripts/eslint-report-guard.mjs <report.json> <eslint-rc> [paths] [config]
+ * Exit:  1 when nothing was measured (unparsable report, or zero files linted)
+ *        otherwise ESLint's own return code, passed through untouched
+ */
+import { readFileSync } from "node:fs";
+
+/** @returns {{ code: number, lines: string[] }} — never throws, so the caller decides how to exit. */
+export function guard(
+  reportPath,
+  eslintRc,
+  { paths = ".", config = "eslint.config.mjs" } = {},
+) {
+  const lines = [];
+  let res;
+  try {
+    res = JSON.parse(readFileSync(reportPath, "utf8"));
+  } catch {
+    lines.push(
+      `::error::ESLint wrote no parsable report to ${reportPath} (rc=${eslintRc}). Nothing was measured.`,
+    );
+    return { code: 1, lines };
+  }
+  if (!Array.isArray(res)) {
+    lines.push(
+      `::error::The report at ${reportPath} is not an ESLint result array. Nothing was measured.`,
+    );
+    return { code: 1, lines };
+  }
+  // THE GUARD. Not "were there findings" — "was anything linted at all".
+  if (res.length === 0) {
+    lines.push(
+      "::error::ESLint linted ZERO files. In the exit code this is indistinguishable from a clean " +
+        `run, and it means the paths or the config matched nothing. paths=${paths} config=${config}`,
+    );
+    return { code: 1, lines };
+  }
+  const msgs = res.flatMap((f) => f.messages ?? []);
+  const errors = msgs.filter((m) => m.severity === 2);
+  for (const f of res)
+    for (const m of f.messages ?? [])
+      lines.push(
+        `${m.severity === 2 ? "error" : "warning"} ${f.filePath}:${m.line}:${m.column}  ` +
+          `${m.ruleId ?? "(no rule)"}  ${m.message}`,
+      );
+  lines.push(
+    `\nlinted ${res.length} file(s) · ${msgs.length} finding(s) · ${errors.length} error(s) · ` +
+      `${msgs.length - errors.length} warning(s)`,
+  );
+  return { code: eslintRc, lines };
+}
+
+// Guarded by realpath, not by `import.meta.url === \`file://${process.argv[1]}\``: through a symlink
+// `import.meta.url` is the REALPATH while `argv[1]` is the link, so that idiom compares false and the
+// CLI silently does nothing. Consumers reach this package through a symlinked tree.
+if (
+  process.argv[1] &&
+  (await import("node:fs")).realpathSync(process.argv[1]) ===
+    (await import("node:url")).fileURLToPath(import.meta.url)
+) {
+  const [report, rc, paths, config] = process.argv.slice(2);
+  const { code, lines } = guard(report, Number(rc), { paths, config });
+  for (const l of lines) console.log(l);
+  process.exit(code);
+}

package/scripts/exclusive.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * MUTUAL EXCLUSION FOR RUNS THAT TOUCH THE SAME FILES.
+ *
+ * ── WHY ──────────────────────────────────────────────────────────────────────────────────────
+ * The mutation batteries (`scripts/run-mutations.mjs`) edit the sources IN PLACE — a deliberate strategy, explained in the header of
+ * `lib/mutation-driver.mjs`: nine cases rewrite the real file, and copying the whole repository
+ * per mutation would mean minutes instead of seconds.
+ *
+ * The strategy has one cost: while the battery runs, ANY parallel `npm test` reads a file in its
+ * mutilated state and fails — with a message about an assertion, not about a mutation. The
+ * failure is FALSE, NON-DETERMINISTIC (it depends on which second you caught) and reads as "the
+ * tests are flaky", i.e. it leads in exactly the direction where there is nothing to fix. This
+ * has already cost an investigation: two runs in a row gave DIFFERENT error messages, and the
+ * conclusion "I broke round-diff" was wrong.
+ *
+ * ── WHY A LOCK AND NOT AN INSTRUCTION "DON'T RUN THEM AT THE SAME TIME" ───────────────────────
+ * The instruction already existed — as prose, in the consumer's CLAUDE.md. Prose does not
+ * execute, so it is not checked and does not apply to anyone who has not read it: the person in
+ * the other terminal, the agent, the editor with tests on save. A lock refuses LOUDLY and names
+ * the reason at the moment it matters.
+ *
+ * ── HOW ─────────────────────────────────────────────────────────────────────────────────────
+ * `mkdirSync` is atomic: either we created the directory or it already existed — there is no
+ * race, unlike "check existsSync, then write". Inside it lie the holder's pid and command; if the
+ * process with that pid is dead, the lock is taken over with an explicit message, otherwise an
+ * interrupted run would block the repository forever, and the first cure would be "delete the
+ * lock by hand", i.e. switching the mechanism off.
+ *
+ * The lock is released in `finally` AND on signals — for exactly the same reason the mutation
+ * driver restores the sources on SIGINT/SIGTERM.
+ */
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const LOCK = join(ROOT, ".vigiles", "exclusive.lock");
+const INFO = join(LOCK, "holder.json");
+
+const argv = process.argv.slice(2);
+if (argv.length === 0) {
+  console.error("usage: node scripts/exclusive.mjs <command> [args…]");
+  process.exit(2);
+}
+
+// The PARENT is created recursively; only the lock itself must be a non-recursive mkdir, because
+// that is the atomic step. Nothing else guarantees `.vigiles/` exists: once
+// `.vigiles/coverage.json` stopped being tracked, a fresh checkout has no such directory, and the
+// lock's mkdir failed with ENOENT before any gate ran (CI on e389916).
+mkdirSync(dirname(LOCK), { recursive: true });
+
+/** Is the process alive. `kill(pid, 0)` sends nothing — it only checks existence and rights. */
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM"; // exists but belongs to someone else — counted as alive
+  }
+}
+
+function readHolder() {
+  try {
+    return JSON.parse(readFileSync(INFO, "utf8"));
+  } catch {
+    return null; // the lock exists, its description is unreadable — resolved below as "dead"
+  }
+}
+
+function acquire() {
+  try {
+    mkdirSync(LOCK, { recursive: false });
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+    const holder = readHolder();
+    if (holder && alive(holder.pid)) {
+      console.error(
+        `🔴 refused: this repository is busy with a run that EDITS FILES IN PLACE.\n` +
+          `   held by: pid ${holder.pid}, "${holder.cmd}", since ${holder.at}\n` +
+          `   A parallel run would produce FALSE failures — a test would read the source in its\n` +
+          `   mutilated state and complain about an assertion, not a mutation. Wait for it to finish.`,
+      );
+      process.exit(3);
+    }
+    console.error(
+      `⚠️  the lock was left behind by a run that no longer exists` +
+        (holder
+          ? ` (pid ${holder.pid}, "${holder.cmd}")`
+          : " (description unreadable)") +
+        ` — taking it over.`,
+    );
+    rmSync(LOCK, { recursive: true, force: true });
+    mkdirSync(LOCK, { recursive: false });
+  }
+  writeFileSync(
+    INFO,
+    JSON.stringify(
+      { pid: process.pid, cmd: argv.join(" "), at: new Date().toISOString() },
+      null,
+      2,
+    ),
+  );
+}
+
+const release = () => {
+  if (existsSync(LOCK)) rmSync(LOCK, { recursive: true, force: true });
+};
+
+acquire();
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    release();
+    process.exit(sig === "SIGINT" ? 130 : 143);
+  });
+}
+
+// 🔴 `process.on("exit")`, NOT `finally`, AND THIS IS NOT STYLE. The first edition released the
+// lock in `finally` — and it STAYED ON DISK: `process.exit()` terminates the process immediately,
+// the stack is not unwound, `finally` does not run. Caught by a run (the lock outlived a
+// successful launch), not by reading. The cost of the defect would have been exactly the inverse
+// of the intent: every run would leave the repository "busy", and the first cure would be "delete
+// the lock by hand", i.e. switching the mechanism off.
+process.on("exit", release);
+
+const r = spawnSync(argv[0], argv.slice(1), { stdio: "inherit", shell: false });
+if (r.error) {
+  console.error(`🔴 failed to launch "${argv.join(" ")}": ${r.error.message}`);
+  process.exit(127);
+}
+process.exit(r.status ?? 1);

package/scripts/harness-api.frozen.json

@@ -0,0 +1,76 @@
+{
+  "issue": "https://github.com/zernie/research-paper-pipeline/issues/77",
+  "why": "A *.harness.* file tests the agent surface and imports runHook, runHarnessTest or runEval from vigiles. Plain unit tests are *.test.ts, run by vitest. These are the harness files that existed on main on 2026-09-25 and import none of the three. The list only shrinks: rename a file to *.test.ts (issue #77), or make it a real harness, then delete its entry. Checked by scripts/harness-api.test.ts, part of npm test.",
+  "harnesses": [
+    "action.harness.mjs",
+    "eslint-rules/doc-fields.harness.mjs",
+    "eslint-rules/install-path-literals.harness.mjs",
+    "eslint-rules/latex-language.harness.mjs",
+    "eslint-rules/paper-research-question.harness.mjs",
+    "eslint-rules/paper-stages.harness.mjs",
+    "eslint-rules/paper-typography.harness.mjs",
+    "eslint-rules/papers.harness.mjs",
+    "eslint-rules/pdf-last-page-balance.harness.mjs",
+    "eslint-rules/review-findings-cause.harness.mjs",
+    "eslint-rules/temp-root-realpath.harness.mjs",
+    "eslint-rules/tex-build.harness.mjs",
+    "fixtures/real-markdown-paper/real-markdown-paper.harness.mjs",
+    "lib/agent-cli-version.harness.mjs",
+    "lib/mutation-driver.harness.mjs",
+    "lib/paper-config.harness.mjs",
+    "lib/skill-trigger-cases.harness.mjs",
+    "scripts/check.harness.mjs",
+    "scripts/mutation-batteries-frozen.harness.mjs",
+    "scripts/rules-are-content-only.harness.mjs",
+    "scripts/rules-see-files.harness.mjs",
+    "skills/analyze-sibling-paper/analyze-sibling-paper.harness.mjs",
+    "skills/argument-arc/argument-arc.harness.mjs",
+    "skills/build-benchmark/build-benchmark.harness.mjs",
+    "skills/camera-ready/camera-ready.harness.mjs",
+    "skills/cold-read-diff/cold-read-diff.harness.mjs",
+    "skills/draft-paper/draft-paper.harness.mjs",
+    "skills/extend-paper/extend-paper.harness.mjs",
+    "skills/find-venue/find-venue.harness.mjs",
+    "skills/grade-paper-writing/grade-paper-writing.harness.mjs",
+    "skills/harden-paper/harden-paper.harness.mjs",
+    "skills/map-prior-work/map-prior-work.harness.mjs",
+    "skills/osf-artifact-upload/osf-artifact-upload.harness.mjs",
+    "skills/paper-adversarial-review/paper-adversarial-review.harness.mjs",
+    "skills/paper-pipeline/paper-pipeline.harness.mjs",
+    "skills/paper-pipeline/scripts/artifact-coverage.harness.mjs",
+    "skills/paper-pipeline/scripts/consumer.harness.mjs",
+    "skills/paper-pipeline/scripts/extract-ref-facts.harness.mjs",
+    "skills/paper-pipeline/scripts/generated-code.harness.mjs",
+    "skills/paper-pipeline/scripts/pipeline-check.harness.mjs",
+    "skills/paper-pipeline/scripts/population-map.harness.mjs",
+    "skills/paper-pipeline/scripts/provenance.harness.mjs",
+    "skills/paper-pipeline/scripts/round-diff.harness.mjs",
+    "skills/paper-status/paper-status.harness.mjs",
+    "skills/pc-panel-review/pc-panel-review.harness.mjs",
+    "skills/plan-paper-timeline/plan-paper-timeline.harness.mjs",
+    "skills/render-paper/extract-pdf-facts.harness.mjs",
+    "skills/render-paper/render-paper.harness.mjs",
+    "skills/research-ideate/research-ideate.harness.mjs",
+    "skills/study-accepted-papers/study-accepted-papers.harness.mjs",
+    "skills/submit-paper/submit-paper.harness.mjs",
+    "skills/sweep-design-space/sweep-design-space.harness.mjs",
+    "skills/tighten-paper/tighten-paper.harness.mjs",
+    "skills/verify-citations/verify-citations.harness.mjs",
+    "src/build-engine.harness.mjs",
+    "src/build.harness.mjs",
+    "src/cli.harness.mjs",
+    "src/doctor.harness.mjs",
+    "src/engine.harness.mjs",
+    "src/hooks-settings.harness.mjs",
+    "src/latex-log.harness.mjs",
+    "src/latex-loop.harness.mjs",
+    "src/link-skills.harness.mjs",
+    "src/new-paper.harness.mjs",
+    "src/pdf-facts.harness.mjs",
+    "src/pdf-geometry.harness.mjs",
+    "src/rules-config.harness.mjs",
+    "src/structure.harness.mjs",
+    "src/tex-requirements.harness.mjs",
+    "src/toolchain.harness.mjs"
+  ]
+}