paperlint 3.1.0 → 3.1.1

package/eslint-rules/temp-root-realpath.harness.mjs

@@ -146,6 +146,55 @@ const cases = [];
   );
 }
 
+// ── 5b. `realpathSync.native(…)` resolves too — as a bare import and through a namespace. A
+//       `.native(…)` on anything else is NOT a resolve: another object, a computed member, a call
+//       result, a bare `native` function. Each of those still gets its finding.
+{
+  const root = 'mkdtempSync(join(tmpdir(), "probe-"))';
+  const silent = await on(
+    `${HEAD}import * as fs from "node:fs";\n` +
+      `const a = realpathSync.native(${root});\nconst b = fs.realpathSync.native(${root});\n`,
+  );
+  assert.deepEqual(
+    silent,
+    [],
+    `realpathSync.native must exempt the root; got: ${JSON.stringify(silent)}`,
+  );
+  for (const wrap of [
+    "keep",
+    "other.native",
+    "fs[name].native",
+    "pick().native",
+    "native",
+  ]) {
+    const m = await on(`${HEAD}const r = ${wrap}(${root});\n`);
+    assert.equal(
+      m.length,
+      1,
+      `${wrap}(…) does not resolve the path — one finding expected, got ${JSON.stringify(m)}`,
+    );
+  }
+  cases.push(
+    "realpathSync.native / fs.realpathSync.native exempt; keep, other.native, fs[name].native, pick().native, native do not",
+  );
+}
+
+// ── 5c. The walk over the arguments survives the shapes that are not plain nodes: an array hole
+//       (null) and a regex literal's `regex` object (no `type`). Neither is a `tmpdir()` call.
+{
+  const m = await on(
+    `${HEAD}const a = mkdtempSync([, /tmp/g]);\nconst b = mkdtempSync([, /x/, tmpdir()]);\n`,
+  );
+  assert.deepEqual(
+    m.map((x) => x.line),
+    [5],
+    `only the second call names tmpdir(); got: ${JSON.stringify(m)}`,
+  );
+  cases.push(
+    "an array hole and a regex literal in the arguments are walked, not mistaken",
+  );
+}
+
 // ── 6. 🔴 THE CORPUS ITSELF IS CLEAN. The "silent" half on a made-up string says nothing
 //      about the repository: the rule could also be silent because it was never handed a
 //      single file (the recorded class — `scripts/rules-see-files.mjs`). So this check runs

package/eslint-rules/tex-build.mjs

@@ -156,10 +156,10 @@ const futurePromise = {
     return {
       root() {
         // 🔴 ONE GUARD, NOT THREE. The first draft had `if (!file || !existsSync(file))`
-        // BEFORE the read — and a mutation run on 2026-09-07 showed that removing that line is
-        // caught by NOTHING: the `try/catch` around the read covers exactly the same cases (no
-        // path, a `<text>` run through stdin, no permission). Two guards doing one job is a
-        // guard no mutation can kill, i.e. a dead assertion dressed as robustness.
+        // BEFORE the read — removing that line on 2026-09-07 showed it is caught by NOTHING:
+        // the `try/catch` around the read covers exactly the same cases (no path, a `<text>` run
+        // through stdin, no permission). Two guards doing one job is a guard the harness can
+        // never fail on, i.e. a dead assertion dressed as robustness.
         // What is left is the read inside `try`: stay quiet rather than judge content we never
         // saw.
         let text;
@@ -264,7 +264,7 @@ const acmFrontmatterOverride = {
       root() {
         // Same single guard as the sibling rule, and for the same measured reason: a separate
         // `existsSync` before the read is covered by this `catch` in every case it could
-        // fire, i.e. it is an assertion no mutation can kill.
+        // fire, i.e. it is an assertion the harness can never fail on.
         let text;
         try {
           text = readFileSync(context.filename, "utf8");
@@ -289,14 +289,14 @@ const acmFrontmatterOverride = {
           for (const { re, removes } of FRONTMATTER_OVERRIDES) {
             // 🔴 NO `re.lastIndex = 0` HERE, AND THAT IS A MEASUREMENT. These regexes are
             // module-level and `/g`, so they carry `lastIndex` across files, and the obvious
-            // defensive line is to reset it. A mutation run on 2026-09-11 removed that line
-            // and the harness stayed GREEN — because the loop below always drains the regex,
-            // and a `/g` `exec` that returns `null` resets `lastIndex` to 0 by itself. The
-            // reset was a guard no mutation could kill, i.e. the same dead assertion dressed
-            // as robustness that the sibling rule's single-`try` comment describes. What
-            // keeps the property honest instead is an ASSERTION, not a line of code: the
-            // harness lints the same input twice in one process and requires the two runs to
-            // agree. Add a `break` to this loop and that assertion is what will fail.
+            // defensive line is to reset it. Removing that line on 2026-09-11 left the harness
+            // GREEN — because the loop below always drains the regex, and a `/g` `exec` that
+            // returns `null` resets `lastIndex` to 0 by itself. The reset was a guard the
+            // harness could never fail on, i.e. the same dead assertion dressed as robustness
+            // that the sibling rule's single-`try` comment describes. What keeps the property
+            // honest instead is an ASSERTION, not a line of code: the harness lints the same
+            // input twice in one process and requires the two runs to agree. Add a `break` to
+            // this loop and that assertion is what will fail.
             let m;
             while ((m = re.exec(line)) !== null) {
               const column = m.index + 1;

package/eslint.config.mjs

@@ -138,6 +138,9 @@ export const layerBoundaries = (root) => ({
         partialMatch: false,
         capture: ["kind"],
       },
+      // test/support.mjs — shared helpers for tests. Only the `test` category may import it: the
+      // policies below allow tests any element, and allow no other file this one.
+      { type: "test-support", pattern: "test", partialMatch: false },
     ],
     "boundaries/files": [
       // `exclusive`: the root also matches the app pattern below, and is only the root.
@@ -369,8 +372,9 @@ export default [
    * 🔴 THIS BLOCK COVERS THE PACKAGE ITSELF, and before 2026-09-15 it was not here: the config held only
    * one block for `.tex` (I don't quote the glob inside this comment: the sequence
    * "star-slash" would close the comment itself — which is where I tripped), and a file with no block gets simply IGNORED by ESLint 9.
-   * Meaning: 133 own `.mjs` — mutation engine, three hooks, scripts for 24 skills — went unchecked,
-   * with green `npm run lint`. A tool that checks others' papers and not itself.
+   * Meaning: 133 own `.mjs` — a since-removed mutation-testing engine, three hooks, scripts for
+   * 24 skills — went unchecked, with green `npm run lint`. A tool that checks others' papers and
+   * not itself.
    *
    * Measurement on the first run: 15 files with dead imports (`resolve`, `pathToFileURL`) and
    * orphaned constants — remnants of a move from `mine`, where those names were needed. All

package/hooks/hooks.harness.mjs

@@ -21,9 +21,7 @@
  * `.ts` source would be: a twin can drift from its build, and there is no twin here to drift.
  *
  * Run: `npx vigiles test hooks/hooks.harness.mjs`
- * Killed by: `hooks/hooks.mutations.mjs`
  */
-import assert from "node:assert/strict";
 import { runHook } from "vigiles";
 import { checkHookImports } from "vigiles/hook";
 import {
@@ -40,6 +38,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PAPERS_DIR_FIELD } from "../lib/paper-config.mjs";
+import { createChecker } from "../lib/check.mjs";
 
 const HOOKS = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HOOKS, "..");
@@ -51,11 +50,7 @@ const SHIPPED = readdirSync(HOOKS)
   .filter((f) => f.endsWith(".hook.mjs"))
   .sort();
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 /**
  * A throwaway consumer repository: a root `paperlint.json` holding the given settings (none when
@@ -492,7 +487,7 @@ try {
       // 🔴 AND SILENT ON THE DEFAULT ROOT TOO — this is the half that catches `??`. With
       // `declared ?? DEFAULT` an explicit `null` is read as «nothing was declared», the prefix
       // becomes `papers/`, and the nudge starts firing about a tree the consumer never named.
-      // Without this case that mutation survives, because the assertion above passes either way.
+      // Without this case that defect survives, because the assertion above passes either way.
       const d = at(
         broken,
         "paper-skills-nudge",
@@ -629,8 +624,8 @@ try {
     );
     // 🔴 THE NASTY NAME NEEDS A REAL DIRECTORY BEHIND IT, or the assertion cannot fail. First
     // draft just passed `a;b` and checked for silence — but a name that names nothing is silent
-    // anyway, for want of a status file, so the mutation that DELETES the name check survived
-    // green. The fixture now contains a paper literally called `a;b` with a status file in it:
+    // anyway, for want of a status file, so deleting the name check would leave this harness
+    // green regardless. The fixture now contains a paper literally called `a;b` with a status file in it:
     // with the check, silence; without it, the verdict comes out. Measured 2026-09-12.
     mkdirSync(join(dir, "docs/papers/a;b"), { recursive: true });
     writeFileSync(
@@ -648,7 +643,7 @@ try {
     );
   }
 
-  console.log(`hooks.harness: ${n} assertions passed`);
+  console.log(`hooks.harness: ${check.count} assertions passed`);
 } finally {
   for (const d of tmps) rmSync(d, { recursive: true, force: true });
 }

package/hooks/paper-edit-guard.hook.mjs

@@ -355,8 +355,8 @@ const MUTATORS = [
  * `runs()` now sees through `env`, `env -C`, `command`, `nice`, `xargs`, `sudo`, `time`, a
  * repeated space and a quoted head — every form tried. So the crutch defended nothing, which is
  * not a judgement but a measurement: removing it left all 78 harness assertions GREEN, and no
- * command form could be found that it alone catches. A line no mutation can kill is a line
- * documenting a defence that does not exist, so it was deleted rather than kept for comfort.
+ * command form could be found that it alone catches. A line the harness can never fail on is a
+ * line documenting a defence that does not exist, so it was deleted rather than kept for comfort.
  *
  * ⚠️ WHAT THIS DOES NOT FIX: rows 3 and 4 above. A wrapper that moves the working directory is
  * still invisible, because `touches`/`namesPaperSource` compare against a repo-root prefix and

package/hooks/paper-edit-guard.test.mjs

@@ -0,0 +1,61 @@
+/**
+ * paper-edit-guard's Bash scan on the shapes the hooks harness does not carry: a `>` inside quotes
+ * or escaped (not a redirection), a target spelled with backslashes (read through them), a target
+ * ended by a delimiter, and a mutator that moves a paper source AWAY — a write `writesTo` does not
+ * see, which the `touches` fallback catches. Each case runs the hook the way a consumer's settings
+ * run it: `vigiles hook-runtime run-program`, from a throwaway project.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import {
+  hookConsumer,
+  onBash,
+  runShippedHook,
+} from "../test/hook-consumer.mjs";
+import { useTempDir } from "../test/support.mjs";
+
+const dir = hookConsumer(useTempDir("paper-edit-guard-"), {
+  "papers/alpha/PIPELINE-STATUS.md": "# S\n",
+});
+/** `>` built rather than typed: a literal one here would be a redirection to the guard's own scan. */
+const GT = String.fromCharCode(62);
+const P = "papers/alpha/paper.md";
+
+/** The guard's exit code for one Bash command: 2 denies, 0 lets it through. */
+const guard = (command) =>
+  runShippedHook("paper-edit-guard", onBash(command), dir).exitCode;
+
+test("a `>` inside quotes, after an escaped quote, or escaped itself is not a redirection", () => {
+  assert.deepEqual(
+    [
+      guard(`echo "a ${GT} ${P}"`),
+      guard(`echo "a \\" ${GT} b"`),
+      guard(`echo a\\${GT} ${P}`),
+    ],
+    [0, 0, 0],
+  );
+});
+
+test("a redirection target is read through backslashes, quoted or not, and ends at a delimiter", () => {
+  assert.deepEqual(
+    [
+      guard(`echo x ${GT} "papers/alpha/pa\\per.md"`),
+      guard(`echo x ${GT} papers/alpha/pa\\per.md`),
+      guard(`echo x ${GT}${P}; true`),
+    ],
+    [2, 2, 2],
+  );
+});
+
+test("moving a paper source away is a write to it: denied", () => {
+  assert.equal(guard(`mv ${P} /tmp/elsewhere.md`), 2);
+});
+
+test("a command cut off right after a backslash still names its target, quoted or not", () => {
+  // The backslash escapes nothing — there is no next character — and the target read so far
+  // is still a paper source.
+  assert.deepEqual(
+    [guard(`echo x ${GT} ${P}\\`), guard(`echo x ${GT} "${P}\\`)],
+    [2, 2],
+  );
+});

package/hooks/paper-skills-nudge.hook.mjs

@@ -71,8 +71,8 @@ const READ_CONFIG = `f="\${CLAUDE_PROJECT_DIR:-.}/${CONFIG_FILE}"; if [ -e "$f"
  * `e.path.under()`, and vigiles normalises the prefix itself (`normalizePrefix` →
  * `trimTrailingSeparators`), so `"docs/papers/"` and `"docs/papers"` are the same prefix to it.
  * A normalise here would be a line no test could kill, which is a line that documents a
- * defence that does not exist. Checked 2026-09-12 by mutation: removing it left the harness
- * green, which is the finding that produced this paragraph.
+ * defence that does not exist. Confirmed 2026-09-12: removing it left the harness green, which
+ * is the finding that produced this paragraph.
  *
  * ⚠️ A NUDGE FALLS SILENT WHERE THE GATE REFUSES, and the asymmetry is the decision, not an
  * inconsistency. `paper-edit-guard` denies on an unreadable declaration because a gate that

package/hooks/paper-skills-nudge.test.mjs

@@ -0,0 +1,38 @@
+/**
+ * paper-skills-nudge on the two declarations the hooks harness does not carry: none at all (the
+ * default `papers/` root applies) and one that does not parse (silence — a nudge never blocks).
+ */
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { test } from "vitest";
+import {
+  hookConsumer,
+  onEdit,
+  runShippedHook,
+} from "../test/hook-consumer.mjs";
+import { useTempDir } from "../test/support.mjs";
+
+const root = useTempDir("paper-skills-nudge-");
+
+test("no paperlint.json: an edit to papers/<p>/paper.md gets the checklist", () => {
+  const dir = hookConsumer(join(root, "default"));
+  const r = runShippedHook(
+    "paper-skills-nudge",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.equal(r.exitCode, 0);
+  assert.notEqual(r.stdout, "");
+});
+
+test("a paperlint.json that does not parse: silent, exit 0", () => {
+  const dir = hookConsumer(join(root, "broken"), {
+    "paperlint.json": "{ nope",
+  });
+  const r = runShippedHook(
+    "paper-skills-nudge",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.deepEqual([r.exitCode, r.stdout, r.stderr], [0, "", ""]);
+});

package/hooks/paper-status-gates.test.mjs

@@ -0,0 +1,42 @@
+/**
+ * paper-status-gates on the two declarations the hooks harness does not carry: none at all (the
+ * default `papers/` root applies) and one that does not parse (silence — this hook never blocks).
+ */
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { test } from "vitest";
+import {
+  hookConsumer,
+  onEdit,
+  runShippedHook,
+} from "../test/hook-consumer.mjs";
+import { useTempDir } from "../test/support.mjs";
+
+const root = useTempDir("paper-status-gates-");
+const STATUS = "**Readiness verdict:** ✅ fixture verdict line\n";
+
+test("no paperlint.json: an edit under papers/ runs the gates for that paper", () => {
+  const dir = hookConsumer(join(root, "default"), {
+    "papers/alpha/PIPELINE-STATUS.md": STATUS,
+  });
+  const r = runShippedHook(
+    "paper-status-gates",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.equal(r.exitCode, 0);
+  assert.match(r.stderr, /fixture verdict line/);
+});
+
+test("a paperlint.json that does not parse: silent, exit 0", () => {
+  const dir = hookConsumer(join(root, "broken"), {
+    "paperlint.json": "{ nope",
+    "papers/alpha/PIPELINE-STATUS.md": STATUS,
+  });
+  const r = runShippedHook(
+    "paper-status-gates",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.deepEqual([r.exitCode, r.stdout, r.stderr], [0, "", ""]);
+});

package/lib/agent-cli-version.harness.mjs

@@ -107,6 +107,13 @@ const cases = [];
   cases.push(
     'exit 0 + empty stdout (the `stdio: "ignore"` shape) → throws, does not report a blank',
   );
+  // …and what the program DID say, on stderr, is carried into the refusal: it is the only clue.
+  const chatty = spawner({ status: 0, stdout: "", stderr: "  warming up\n" });
+  assert.throws(
+    () => observeAgentCli({ spawnSync: chatty }),
+    /\(got "", stderr "warming up"\)/,
+  );
+  cases.push("…and the stderr it printed instead is quoted in the refusal");
 }
 
 // ── 5. THE CALL SHAPE, asserted directly. Case 4 catches a discarding probe only because the

package/lib/check.d.mts

@@ -0,0 +1,17 @@
+// Types for lib/check.mjs — the shared harness assertion helper (see the module).
+
+/** A failure detail: text, any value (rendered with `util.inspect`), or a thunk producing one. */
+export type Detail = unknown;
+
+export declare function renderDetail(detail: Detail): string;
+export declare function failureMessage(label: string, detail: Detail): string;
+
+export interface Check {
+  (label: string, cond: unknown, detail?: Detail): void;
+  /** How many times this checker has been called. */
+  readonly count: number;
+}
+
+export declare function createChecker(options?: {
+  log?: (line: string) => void;
+}): Check;

package/lib/check.mjs

@@ -0,0 +1,50 @@
+/**
+ * The one assertion helper every `*.harness.mjs` uses.
+ *
+ * Until #52 each harness defined its own `check()`, and the copies had drifted: some printed a
+ * detail on failure and some dropped it, some joined it with " — " and some with a newline, and two
+ * passed the LABEL to vigiles' `recordCheck(n)`, which adds its argument to a number — so the
+ * recorded count became a string. One helper removes the drift instead of documenting it.
+ *
+ * What it guarantees:
+ *   - a failure names the label AND the detail, on stderr and in the thrown assertion — the detail
+ *     is what makes a red run diagnosable without re-running it;
+ *   - `detail` may be a function, so an expensive rendering is paid only on failure;
+ *   - every call is counted (`check.count`) and reported to the vigiles runner (`recordCheck`), so
+ *     a harness's summary line and the runner's check count come from the same place.
+ */
+import assert from "node:assert/strict";
+import { inspect } from "node:util";
+import { recordCheck } from "vigiles";
+
+/** A failure detail as text: strings verbatim, other values through `util.inspect`, a thunk called. */
+export function renderDetail(detail) {
+  const value = typeof detail === "function" ? detail() : detail;
+  if (value === undefined || value === null || value === "") return "";
+  return typeof value === "string" ? value : inspect(value, { depth: 6 });
+}
+
+/** The label, then the detail: on the same line when it is one line, below it when it is many. */
+export function failureMessage(label, detail) {
+  const shown = renderDetail(detail);
+  if (!shown) return label;
+  return shown.includes("\n") ? `${label}\n${shown}` : `${label} — ${shown}`;
+}
+
+/**
+ * A fresh `check(label, cond, detail?)`. `check.count` is how many times it has been called.
+ * `log` is where a failure is printed — stderr unless this module's own test injects one.
+ */
+export function createChecker({ log = console.error } = {}) {
+  let count = 0;
+  const check = (label, cond, detail) => {
+    count++;
+    recordCheck();
+    if (cond) return;
+    const message = failureMessage(label, detail);
+    log(`✗ ${message}`);
+    assert.fail(message);
+  };
+  Object.defineProperty(check, "count", { get: () => count });
+  return check;
+}

package/lib/check.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { createChecker, failureMessage, renderDetail } from "./check.mjs";
+
+test("renderDetail: a string verbatim, nothing for empty, a value inspected, a thunk called", () => {
+  assert.deepEqual(
+    [
+      renderDetail("as is"),
+      renderDetail(""),
+      renderDetail(undefined),
+      renderDetail(null),
+      renderDetail({ a: [1, 2] }),
+      renderDetail(() => "lazy"),
+      renderDetail(() => undefined),
+    ],
+    ["as is", "", "", "", "{ a: [ 1, 2 ] }", "lazy", ""],
+  );
+});
+
+test("failureMessage: label alone, label — detail, or label on its own line above a multi-line detail", () => {
+  assert.deepEqual(
+    [
+      failureMessage("L", undefined),
+      failureMessage("L", "d"),
+      failureMessage("L", "one\ntwo"),
+    ],
+    ["L", "L — d", "L\none\ntwo"],
+  );
+});
+
+test("createChecker: counts every call, stays silent on a pass", () => {
+  const printed: string[] = [];
+  const check = createChecker({ log: (s) => printed.push(s) });
+  check("a", true);
+  check("b", 1 === 1, "unused detail");
+  assert.deepEqual({ count: check.count, printed }, { count: 2, printed: [] });
+});
+
+test("createChecker: a failure throws AND prints the label with its detail, and is counted", () => {
+  const printed: string[] = [];
+  const check = createChecker({ log: (s) => printed.push(s) });
+  // Guards: the detail reaches the reader — the drift this helper replaced dropped it.
+  assert.throws(() => check("the label", false, { got: 3 }), {
+    name: "AssertionError",
+    message: "the label — { got: 3 }",
+  });
+  assert.deepEqual(
+    { count: check.count, printed },
+    { count: 1, printed: ["✗ the label — { got: 3 }"] },
+  );
+});
+
+test("createChecker: a detail thunk is only evaluated on failure", () => {
+  let calls = 0;
+  const check = createChecker({ log: () => {} });
+  check("pass", true, () => {
+    calls++;
+    return "x";
+  });
+  assert.throws(() =>
+    check("fail", false, () => {
+      calls++;
+      return "x";
+    }),
+  );
+  assert.equal(calls, 1);
+});

package/lib/markdown.mjs

@@ -49,6 +49,9 @@ try {
  */
 export const MD_AVAILABLE = () => md !== null;
 
+/** markdown-it's block tokens for `text`, or null when it did not resolve. A test passes its own. */
+const defaultParse = () => (md === null ? null : (text) => md.parse(text, {}));
+
 /**
  * The frontmatter is BLANKED with spaces, not cut out: the offsets must stay the
  * same, because the checks cut the document by offset. Blanking is necessary — inside
@@ -118,15 +121,17 @@ function lineStarts(text) {
  * under without a blank line would become a level-2 heading per CommonMark. The former
  * regexps knew only ATX, so this preserves the contract rather than narrowing it.
  */
-export function headings(text) {
-  if (md === null) return [];
-  const toks = md.parse(blankFrontmatter(text), {});
+export function headings(text, { parse = defaultParse() } = {}) {
+  if (parse === null) return [];
+  const toks = parse(blankFrontmatter(text));
   const starts = lineStarts(text);
   const out = [];
   for (let i = 0; i < toks.length; i++) {
     const t = toks[i];
     if (t.type !== "heading_open" || !t.map) continue;
     if (!t.markup || !t.markup.startsWith("#")) continue; // setext — see the caveat above
+    // markdown-it follows `heading_open` with its `inline` token and maps blocks to lines of the
+    // parsed text; the fallbacks are for a token stream that does not (another parser version).
     const inline = toks[i + 1];
     out.push({
       depth: Number(t.tag.slice(1)),
@@ -138,64 +143,6 @@ export function headings(text) {
   return out;
 }
 
-/** Offsets of the `---` thematic breaks (in this knowledge base — a prose separator). */
-export function thematicBreaks(text) {
-  if (md === null) return [];
-  const starts = lineStarts(text);
-  return md
-    .parse(blankFrontmatter(text), {})
-    .filter((t) => t.type === "hr" && t.map)
-    .map((t) => starts[t.map[0]] ?? 0);
-}
-
-/**
- * A section's body: from the line AFTER the heading matching `match`, up to the next
- * heading of THE SAME OR A LOWER level. `{ heading, body }` or `null`.
- *
- * `match` — a regex over the heading text OR a predicate over `{depth,text,line,offset}`.
- *
- * Level-or-lower, not "exactly `##`": a `###` subsection inside the section does not
- * end it — that is exactly how the former expressions with the `(?=\n## )` lookahead
- * behaved. A regex cannot know this distinction in principle: it has no notion of level.
- *
- * `depth` — the CEILING on the level of the heading itself. Without it an `### Abstract`
- * quoted in an appendix becomes the abstract — and the abstract is judged with a
- * threshold of ZERO.
- *
- * `stopAtRule` additionally cuts the section off at the first `---`. That is NOT markdown
- * structure but a paper convention, and it is preserved deliberately: the conclusion has
- * a `---` before the appendices, and without that boundary a section with no following
- * `##` would reach to the end of the file.
- *
- * 🔴 A MERGED VERSION. On 2026-08-11 this function appeared SIMULTANEOUSLY in two places:
- * here (for `kb-lint`) and in `paper-lint.mjs` (richer — with the level ceiling, the
- * heading in the result and `stopAtRule`). Both were written within one hour by two
- * parallel passes, neither saw the other. Merged into the rich version: the weak one was
- * a subset, and keeping both would have meant diverging in behaviour at the very next edit.
- */
-export function sectionBody(
-  text,
-  match,
-  { depth = 6, stopAtRule = false } = {},
-) {
-  const test = typeof match === "function" ? match : (h) => match.test(h.text);
-  const hs = headings(text);
-  const i = hs.findIndex((h) => h.depth <= depth && test(h));
-  if (i === -1) return null;
-  const h = hs[i];
-  const next = hs.slice(i + 1).find((n) => n.depth <= h.depth);
-  let end = next ? next.offset : text.length;
-  if (stopAtRule) {
-    const hr = thematicBreaks(text).find((o) => o > h.offset && o < end);
-    if (hr !== undefined) end = hr;
-  }
-  // The body starts on the line AFTER the heading: the heading itself is not part of the
-  // section, just as the former expressions' group did not capture it.
-  const nl = text.indexOf("\n", h.offset);
-  const start = nl === -1 || nl + 1 > end ? end : nl + 1;
-  return { heading: h, body: text.slice(start, end) };
-}
-
 /**
  * Slicing the document into chunks "a heading + everything up to the next heading FROM
  * THE SAME RANGE of levels". → `[{ heading, raw, body }]`.
@@ -302,15 +249,15 @@ export function stripFences(text, { blank = false } = {}) {
  * indistinguishable from "the paper has no sections". A confident zero has already been
  * read as a finding four times in this repo; here it is inexpressible.
  */
-export function requireMarkdown() {
+export function requireMarkdown({ from = import.meta.url } = {}) {
   if (MD_AVAILABLE()) return;
-  // 🔴 THE CURE DEPENDS ON THE DELIVERY CHANNEL, AND NAMING THE WRONG ONE WASTES THE ERROR.
-  // Measured 2026-09-19: `npm pack` strips `package-lock.json` unconditionally, and a plugin copy
-  // gets `npm ci` only when a lockfile is present in the fetched root — so a plugin installed from
-  // npm has NO `node_modules`, with no log entry anywhere. Telling that user to run `npm i at the
-  // repo root` points at a repository they do not have. The channel is readable from this file's
-  // own location, so the message can name it instead of guessing.
-  const fromPluginCache = import.meta.url.includes("/.claude/plugins/");
+  // 🔴 THE CURE DEPENDS ON WHERE THIS COPY RUNS FROM. Measured 2026-09-19: a Claude Code plugin
+  // copy is installed without dependencies (`npm pack` strips `package-lock.json`, and the plugin
+  // cache runs `npm ci` only with a lockfile). The plugin channel was removed in #82, but a copy
+  // installed before then still runs from there, and "npm i at the repo root" would point its user
+  // at a repository they do not have. The location is readable from this file's own URL (`from`,
+  // a parameter only so a test can name a plugin-cache location without copying the file there).
+  const fromPluginCache = from.includes("/.claude/plugins/");
   console.error(
     "markdown-it does not resolve — this script parses markup with a parser and without it " +
       "would produce a confident zero instead of an error.\n" +