paperlint 3.0.0 → 3.1.1

package/skills/paper-pipeline/scripts/pipeline-edges.mjs

@@ -124,11 +124,11 @@ export const UNEXPRESSED = [
   ],
   [
     "draft ← study",
-    'draft-paper/SKILL.md: "**FAIL** — it declined to draft because a required input was missing: no numbers from build-benchmark"',
+    'draft-paper/SKILL.md: "**FINDING** — it declined to draft because a required input was missing: no numbers from `build-benchmark`"',
   ],
   [
     "priorwork ← idea",
-    'paper-pipeline/SKILL.md SETUP: map-prior-work runs "right after `research-ideate` says go"',
+    'map-prior-work/SKILL.md, the `priorwork` row: "SETUP, right after `research-ideate` says go"',
   ],
 ];
 

package/skills/paper-pipeline/scripts/pipeline-edges.test.mjs

@@ -0,0 +1,73 @@
+/**
+ * pipeline-edges.mjs admits each edge on a SENTENCE from a skill's own SKILL.md, quoted in the
+ * table so the judgement stays auditable. A quote is only evidence while the skill still says it,
+ * so every quote is looked up in the SKILL.md it names. A skill reworded since — or a quote that
+ * was never verbatim — fails here, naming the edge.
+ *
+ * Matching tolerates what quoting legitimately changes: runs of whitespace, `**` emphasis, and an
+ * elision `…`, which splits a quote into fragments that must each appear. The values are prose,
+ * so reading them with a pattern is reading prose, not parsing a format.
+ */
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { CANONICAL_INPUTS, NOT_EDGES, UNEXPRESSED } from "./pipeline-edges.mjs";
+
+const SKILLS = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const norm = (s) => s.replace(/\*\*/g, "").replace(/\s+/g, " ");
+
+/** [edge, skill, quote] for every `<skill>/SKILL.md…: "<quote>"` in the three tables. */
+function quotes() {
+  const cells = [
+    ...Object.entries(CANONICAL_INPUTS).flatMap(([row, { requires }]) =>
+      Object.entries(requires).map(([input, why]) => [
+        `${row} ← ${input}`,
+        why,
+      ]),
+    ),
+    ...UNEXPRESSED,
+    ...NOT_EDGES,
+  ];
+  return cells.flatMap(([edge, why]) =>
+    quotesIn(why).map(([skill, quote]) => [edge, skill, quote]),
+  );
+}
+
+/** [skill, quote] for every `<skill>/SKILL.md…: "<quote>"` in one cell. */
+function quotesIn(why) {
+  return [...why.matchAll(/([a-z-]+)\/SKILL\.md[^"]*"((?:[^"\\]|\\.)*)"/g)].map(
+    (m) => [m[1], m[2]],
+  );
+}
+
+// Guards: the pattern below is not vacuous — a cell that names a SKILL.md yields its quote.
+test("every cell that names a SKILL.md yields a quote to check", () => {
+  const cells = [
+    ...Object.values(CANONICAL_INPUTS).flatMap((v) =>
+      Object.values(v.requires),
+    ),
+    ...UNEXPRESSED.map(([, why]) => why),
+    ...NOT_EDGES.map(([, why]) => why),
+  ];
+  const unparsed = cells.filter(
+    (why) => why.includes("/SKILL.md") && quotesIn(why).length === 0,
+  );
+  assert.deepEqual(unparsed, []);
+});
+
+test("every quoted sentence is still in the SKILL.md it is attributed to", () => {
+  const stale = quotes().flatMap(([edge, skill, quote]) => {
+    const file = join(SKILLS, skill, "SKILL.md");
+    if (!existsSync(file))
+      return [{ edge, skill, missing: "the skill itself" }];
+    const text = norm(readFileSync(file, "utf8"));
+    return norm(quote)
+      .split("…")
+      .map((f) => f.trim())
+      .filter((f) => f.length > 0 && !text.includes(f))
+      .map((missing) => ({ edge, skill, missing }));
+  });
+  assert.deepEqual(stale, []);
+});

package/skills/paper-pipeline/scripts/population-map.harness.mjs

@@ -8,29 +8,10 @@
  * THE REGISTRY ITSELF (`repro/populations.tsv`), both have no address in the paper, and so cannot be expressed by ESLint,
  * which reports only to the linted file.
  *
- * WHY THIS FILE AND NOT MORE CASES IN THE SELF-TEST. `population-map.selftest.mjs` is thorough —
- * 7 planted cases, both directions. Nothing here duplicates it. Two things were wrong with it
- * anyway:
- *
- *   1. IT IS INVISIBLE TO THE MEASUREMENT. `vigiles audit` scores this repo `Tested: 0`, and the
- *      metric counts `*.harness.mjs` / `*.eval.mjs`. Verified 2026-08-07: bare `npx vigiles test`
- *      reports no harness files found — its glob does not descend into dot-dirs AND the self-test
- *      does not carry a name the collector looks for. Given an explicit path it runs
- *      fine, which is the trap: it is green, correct, and uncounted, so the repo reads
- *      as having no test for its own registry hygiene.
- *
- *   2. IT ONLY EXERCISES `findings()`. Everything between the command line and that function —
- *      finding paper.md, finding repro/populations.tsv, `--flags-only` staying silent on a clean
- *      paper — is what the CI step and `run-mechanical.mjs` actually invoke, and none of it was
- *      under test. This repository's three dead hooks all had correct logic; what was broken was
- *      the wiring around it.
- *
- * 🔴 THE SELF-TEST IS RUN AS A SUBPROCESS, NEVER IMPORTED. It ends in `process.exit(fail ? 1 : 0)`.
- * Import it and a PASSING self-test terminates this process at that line — every assertion below it
- * never runs, and `vigiles test` reports ✓ because nothing threw. That is trap #1 from
- * hooks.harness.mjs wearing a different hat, and it would have been undetectable from the output.
- *
- * Every fixture is a throwaway in a temp dir; nothing here reads or writes a real paper.
+ * The findings themselves are planted in `population-map.test.mjs` (vitest; until #52 a
+ * self-test script this harness spawned). This file keeps what only the command shows: finding
+ * paper.md and repro/populations.tsv, and `--flags-only` staying silent on a clean paper — the
+ * wiring the CI step and `run-mechanical.mjs` actually invoke.
  */
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
@@ -49,7 +30,6 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 
 const ROOT = consumerRoot();
 const SCRIPT = join(HERE, "population-map.mjs");
-const SELFTEST = join(HERE, "population-map.selftest.mjs");
 const tmp = realpathSync(mkdtempSync(join(tmpdir(), "popmap-harness-")));
 
 /** Run a node script; never throws on a non-zero exit. */
@@ -87,29 +67,6 @@ const REG = [
   "census\t134\tdisjoint\tbroad\ta separate sample",
 ].join("\n");
 
-// ── 1. the self-test still kills every mutant it claims to ─────────────────────────────
-// Owning it from a *.harness.mjs is the whole point: the metric now counts it, and a regression in
-// the self-test itself fails this file rather than passing unnoticed in a step nobody reads.
-{
-  const r = run([SELFTEST]);
-  assert.equal(r.code, 0, "population-map.selftest.mjs failed:\n" + r.out);
-  const m = r.out.match(/(\d+) passed, (\d+) failed/);
-  assert.ok(
-    m,
-    "the self-test printed no result line — it may have exited before running:\n" +
-      r.out,
-  );
-  // A self-test that runs ZERO cases also prints "0 failed" and exits 0. That shape is exactly how
-  // this repo's earlier harness reported ✓ on `assert.equal(1, 2)`, so the count is asserted too.
-  // Threshold lowered 13 → 7 along with the move of two findings to ESLint. The assertion on COUNT is kept:
-  // a self-test that ran zero cases also prints «0 failed» and exits zero.
-  assert.ok(
-    Number(m[1]) >= 7,
-    `the self-test ran only ${m[1]} case(s) — cases have gone missing`,
-  );
-  assert.equal(Number(m[2]), 0, "the self-test reported failures:\n" + r.out);
-}
-
 // ── 2. the CLI finds the paper and the registry, and fires on a stale registry row ─────
 // 🔴 FIXTURE REWRITTEN 2026-08-26. Before that it planted an UNLINKED POPULATION, and that
 // finding moved to `paper/population-untied` — meaning the old «dirty» input became clean, and

package/skills/paper-pipeline/scripts/population-map.mjs

@@ -94,7 +94,7 @@ export function parseRegistry(tsv) {
     if (!line.trim() || line.startsWith("#")) continue;
     const [id, print, relation, relatedTo, gloss] = line
       .split("\t")
-      .map((c) => (c ?? "").trim());
+      .map((c) => c.trim()); // split yields strings; a missing column is `undefined` in the destructuring
     if (!id || id === "id") continue;
     rows.push({ id, print, relation, relatedTo, gloss });
   }
@@ -108,6 +108,12 @@ export function findings(md, tsv) {
   const out = [];
 
   for (const row of reg) {
+    // A row with no printed quantity has nothing to look for in the body. It used to reach
+    // `printed(undefined)` and crash the checker; it is a defect of the TSV, reported as one.
+    if (!row.print) {
+      out.push({ kind: "incomplete", row });
+      continue;
+    }
     const appears = printed(row.print).test(body);
     if (!appears) {
       // A registry row for a quantity the body no longer prints. Same discipline as the
@@ -124,7 +130,7 @@ export function findings(md, tsv) {
   return out;
 }
 
-/* Importable above this line; the CLI only runs when this file is the entry point, so the selftest
+/* Importable above this line; the CLI only runs when this file is the entry point, so the tests
  * can exercise findings() without the argv handling firing. */
 if (!isMain(import.meta.url)) {
   // imported — nothing to do
@@ -175,6 +181,10 @@ function main() {
       console.log(
         `  🔴 ${f.row.id} says it relates to "${f.row.relatedTo}", which is not a row in populations.tsv`,
       );
+    } else {
+      console.log(
+        `  🔴 ${f.row.id} has no printed quantity — the row cannot be checked against the body`,
+      );
     }
   }
   process.exit(0);

package/skills/paper-pipeline/scripts/population-map.test.mjs

@@ -0,0 +1,154 @@
+/**
+ * population-map.mjs — the registry's own findings (`stale`, `badref`), planted in both directions,
+ * and the command around them. Until #52 the seven cases below were `population-map.selftest.mjs`,
+ * a script the harness spawned and whose "N passed" line it parsed; they are vitest cases now.
+ *
+ * 🔴 ONE CASE WAS DELETED BEFORE THE MOVE, NOT MOVED, and that is worth remembering: it ran a
+ * HAND-COPIED COPY of the checker's regex over a string. A change to the real `printed()` cannot
+ * touch such a test by construction. The property is pinned by behaviour instead (case 6).
+ */
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+import { bodyOf, findings } from "./population-map.mjs";
+
+const SCRIPT = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "population-map.mjs",
+);
+const doc = (bodyLines) =>
+  `## Abstract\n\n${bodyLines}\n\n## References\n\n[1] x.\n`;
+const kinds = (md, reg) =>
+  findings(md, reg).map((f) => `${f.kind}:${f.row.print}`);
+const REG = [
+  "id\tprinted\trelation\trelated_to\tgloss",
+  "broad\t1,921\troot\t\tthe corpus",
+  "sub\t1,836\tsubset\tbroad\tthose it could read",
+].join("\n");
+const HEAD = "id\tprinted\trelation\trelated_to\tgloss\n";
+
+// 1. The direction that matters more: a checker firing on a paper that already obeys gets muted.
+test("a registry that matches the body is silent", () => {
+  assert.deepEqual(
+    kinds(
+      doc(
+        "The resolver ran over all 1,921 repositories, and read 1,836 of them.",
+      ),
+      REG,
+    ),
+    [],
+  );
+});
+
+// 2. A row for a quantity the paper no longer prints is a claim nobody can check.
+test("a stale registry row fires", () => {
+  assert.deepEqual(
+    kinds(doc("The resolver ran over all 1,921 repositories."), REG),
+    ["stale:1,836"],
+  );
+});
+
+// 3. `retired` is what keeps a set declared after it was cut from the paper.
+test("a retired row does not fire", () => {
+  assert.deepEqual(
+    kinds(
+      doc("The resolver ran over all 1,921 repositories, and read 1,836."),
+      `${REG}\ngold\t7,310\tretired\t\ta public gold set`,
+    ),
+    [],
+  );
+});
+
+// 4. A relation pointing at an id that is not a row — a defect of the TSV alone.
+test("a dangling related_to fires", () => {
+  assert.deepEqual(
+    kinds(
+      doc("We read 1,836 repositories."),
+      `${HEAD}sub\t1,836\tsubset\tnosuch\tx`,
+    ),
+    ["badref:1,836"],
+  );
+});
+
+// 5. A row whose number is absent is `stale`, never also `badref`.
+test("a row that is absent is stale, not badref", () => {
+  assert.deepEqual(
+    kinds(doc("Nothing numeric here."), `${HEAD}sub\t1,836\tsubset\tnosuch\tx`),
+    ["stale:1,836"],
+  );
+});
+
+// 6. `printed()` boundaries through behaviour: 189 is not printed inside 1,189.
+test('189 is not "printed" inside 1,189', () => {
+  assert.deepEqual(
+    kinds(
+      doc("A follow-up read covered 1,189 records, of all 1,921."),
+      `${HEAD}broad\t1,921\troot\t\tthe corpus\nspread\t189\tsubset\tbroad\tenumerable`,
+    ),
+    ["stale:189"],
+  );
+});
+
+// 7. The body stops at the bibliography; with no Abstract it starts at the top, with no
+//    References it runs to the end.
+test("bodyOf: from Abstract to References, or the whole text when either is missing", () => {
+  assert.deepEqual(
+    [
+      bodyOf(doc("nothing here")).includes("[1] x."),
+      bodyOf("pre\n\n## References\n\n[1] x.\n"),
+      bodyOf("## Abstract\n\nall of it\n"),
+    ],
+    [false, "pre\n\n", "## Abstract\n\nall of it\n"],
+  );
+});
+
+test("a registry row with no printed quantity is reported, not a crash", () => {
+  assert.deepEqual(
+    findings(doc("x"), `${HEAD}short\n`).map((f) => [f.kind, f.row.id]),
+    [["incomplete", "short"]],
+  );
+});
+
+// ── the command ─────────────────────────────────────────────────────────────────────────
+const root = useTempDir("population-map-");
+const paper = (name, body, tsv) =>
+  writeTree(join(root, name), {
+    "paper.md": doc(body),
+    ...(tsv === undefined ? {} : { "repro/populations.tsv": tsv }),
+  });
+
+test("the command: usage, a paper without markdown, a clean registry, and every finding kind", () => {
+  assert.deepEqual(runNode(SCRIPT, []), {
+    status: 0,
+    stdout: "",
+    stderr: "usage: node population-map.mjs <paper-dir> [--flags-only]\n",
+  });
+  const tex = writeTree(join(root, "tex"), { "paper.tex": "x" });
+  assert.match(
+    runNode(SCRIPT, [tex]).stderr,
+    /population map SKIPPED for .* — no paper\.md\/draft\.md — this checker reads markdown only/,
+  );
+  const clean = paper(
+    "clean",
+    "All 1,921 of them.",
+    `${HEAD}broad\t1,921\troot\t\tx`,
+  );
+  assert.equal(
+    runNode(SCRIPT, [clean]).stdout,
+    "population map: the registry matches the body — no stale rows, no dangling related_to.\n",
+  );
+  assert.equal(runNode(SCRIPT, [clean, "--flags-only"]).stdout, "");
+  const bad = paper(
+    "bad",
+    "We read 1,836.",
+    `${HEAD}sub\t1,836\tsubset\tnosuch\tx\nold\t7,310\tsubset\tsub\tx\nshort\n`,
+  );
+  assert.deepEqual(runNode(SCRIPT, [bad]).stdout.split("\n").slice(1), [
+    '  🔴 sub says it relates to "nosuch", which is not a row in populations.tsv',
+    "  ·  7,310 (old) is declared and the body no longer prints it — drop the row or mark it retired",
+    "  🔴 short has no printed quantity — the row cannot be checked against the body",
+    "",
+  ]);
+});

package/skills/paper-pipeline/scripts/provenance.harness.mjs

@@ -234,6 +234,32 @@ const NOTES = [
   assert.match(out, /clean/, "clean run did not print a verdict:\n" + out);
 }
 
+// ── 6. a registry with no ratchet file: every registered quantity sourced, nothing still raw ──
+{
+  const d = paper("no-ratchet", {
+    body: "Nothing bolded here.",
+    notes: NOTES,
+    numbers: "# id\tvalue\n a\t1\n",
+  });
+  const { out } = kinds(d);
+  assert.match(
+    out,
+    /1 quantities are sourced and guarded, 0 are still raw/,
+    "no numbers-grandfathered.txt must count as zero still raw:\n" + out,
+  );
+}
+
+// ── 7. no argument: the directory it is run from ──────────────────────────────────────────
+{
+  const d = paper("from-cwd", { body: "Nothing bolded here.", notes: NOTES });
+  const out = execFileSync("node", [SCRIPT], { cwd: d, encoding: "utf8" });
+  assert.match(
+    out,
+    /clean/,
+    "run with no argument must judge its cwd:\n" + out,
+  );
+}
+
 rmSync(tmp, { recursive: true, force: true });
 console.log(
   "✓ check-provenance: no-numbers-gate fires, coverage is measured, both guards are pinned, clean run speaks",

package/skills/paper-pipeline/scripts/round-diff.harness.mjs

@@ -14,8 +14,7 @@
  * on the mutation-testing principle that a test which kills no mutant is not a test. On the live
  * paper this check reports one finding (`no-round-ledger` — there are no rounds on file yet), so the
  * live corpus cannot distinguish "the other twelve checks work" from "the other twelve checks are
- * dead code". Its evidence of life is here, and its evidence that THIS FILE has teeth is
- * `round-diff.mutations.mjs`.
+ * dead code". Its evidence of life is here: every case below was seen failing before it passed.
  *
  * 🔴 ASSERTIONS RUN AT MODULE TOP LEVEL. `vigiles test` imports the file and treats "did not throw"
  * as a pass; an earlier harness in this directory exported a `tests` object, nothing ran, and the

package/skills/paper-pipeline/scripts/round-diff.mjs

@@ -65,7 +65,7 @@
  */
 import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { join, resolve, relative } from "node:path";
+import { basename, join, resolve, relative } from "node:path";
 import { stripFrontmatter, frontmatterBlock } from "../../../lib/markdown.mjs";
 import { isMain } from "./consumer.mjs";
 
@@ -274,7 +274,7 @@ const unquote = (s) => s.replace(/^["']|["']$/g, "");
  * The first version fell through to the substring rule for numeric entries too, so `touches: ["2"]`
  * matched "Section 12", "2026", and every heading containing the character 2 — a one-character
  * declaration authorising most of the paper, with `overbroad-scope` silent because the LIST was
- * short. Found on 2026-08-10 by mutation, not by reading: disabling the nesting rule changed no
+ * short. Measured on 2026-08-10, not read off the code: disabling the nesting rule changed no
  * verdict, because the substring fallback was quietly doing its job for it.
  */
 export function covers(entry, heading) {
@@ -318,6 +318,8 @@ export function check(dir, { since } = {}) {
   const at = (rev) => {
     if (!repo) return { ok: false, err: "not a git repository" };
     const r = git(repo, "show", `${rev}:${rel}`);
+    // A git that fails without a word on stderr (killed, or a wrapper that swallows it) still
+    // leaves the reader the revision and path it could not read.
     return r.ok
       ? { ok: true, src: r.out }
       : { ok: false, err: r.err || `git show ${rev}:${rel} failed` };
@@ -342,6 +344,10 @@ export function check(dir, { since } = {}) {
     manifests.push(man);
   }
   manifests.sort((a, b) => Number(a.round ?? 0) - Number(b.round ?? 0));
+  // A manifest names its round in `round:`; one that does not is named by its file — printing
+  // `round undefined` would point the reader at nothing.
+  const label = (m) =>
+    m.round === undefined ? relOf(dir, m.path) : `round ${m.round}`;
   const open = manifests.filter((m) => !m.closed);
 
   if (!since && manifests.length === 0) {
@@ -353,7 +359,7 @@ export function check(dir, { since } = {}) {
   if (open.length > 1) {
     add(
       "two-open-rounds",
-      `${open.length} manifests have no \`closed:\` (${open.map((m) => `round ${m.round}`).join(", ")}) — with two open rounds every budget below is checked against the wrong base.`,
+      `${open.length} manifests have no \`closed:\` (${open.map((m) => label(m)).join(", ")}) — with two open rounds every budget below is checked against the wrong base.`,
     );
   }
   if (!since && manifests.length > 0 && open.length === 0) {
@@ -410,13 +416,13 @@ export function check(dir, { since } = {}) {
       if (cum > total) {
         add(
           "ratchet-cumulative",
-          `across ${manifests.length} rounds the body grew ${sign(cum)} words against ${sign(total)} of declared budget (${c0.bodyWords} → ${nowC.bodyWords}, from round ${first.round}'s base \`${first.base}\`). Every individual round may have been inside its own budget; this is the drift they compound into.`,
+          `across ${manifests.length} rounds the body grew ${sign(cum)} words against ${sign(total)} of declared budget (${c0.bodyWords} → ${nowC.bodyWords}, from ${label(first)}'s base \`${first.base}\`). Every individual round may have been inside its own budget; this is the drift they compound into.`,
         );
       }
     } else {
       add(
         "unresolvable-base",
-        `round ${first.round}'s base \`${first.base}\` does not resolve (${g0.err}), so cumulative drift across ${manifests.length} rounds is UNMEASURED — not zero.`,
+        `${label(first)}'s base \`${first.base}\` does not resolve (${g0.err}), so cumulative drift across ${manifests.length} rounds is UNMEASURED — not zero.`,
       );
     }
   }
@@ -522,7 +528,8 @@ export function check(dir, { since } = {}) {
 const num = (v, d) =>
   v === undefined || v === null || v === "" || isNaN(Number(v)) ? d : Number(v);
 const sign = (n) => (n > 0 ? `+${n}` : String(n));
-const relOf = (dir, p) => relative(resolve(dir, ".."), p) || p;
+/** `p`, which lies inside the paper directory `dir`, named from the paper's own name down. */
+const relOf = (dir, p) => join(basename(dir), relative(dir, p));
 
 // ── CLI ──────────────────────────────────────────────────────────────────────────────────────
 

package/skills/paper-pipeline/scripts/round-diff.test.mjs

@@ -0,0 +1,159 @@
+/**
+ * round-diff.mjs beyond its harness: the manifest reader's edge lines, `*` coverage, the census of
+ * an empty text, and — in real git repositories — manifests without a round number, a first base
+ * that does not resolve, a removed section that is declared, more than eight new numbers, and the
+ * command with no git on PATH, no paper.md, and no directory argument.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+import { census, check, covers, parseManifest } from "./round-diff.mjs";
+
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "round-diff.mjs");
+const root = useTempDir("round-diff-");
+let n = 0;
+
+/** A git repo whose HEAD holds `base` as paper.md; the working tree then holds `now`. */
+function repo(base, now = base, rounds = {}) {
+  const dir = join(root, `r${String(n++)}`, "paper");
+  writeTree(dir, { "paper.md": base });
+  const g = (...a) => spawnSync("git", a, { cwd: dir, encoding: "utf8" });
+  g("init", "-q");
+  g(
+    "-c",
+    "user.name=t",
+    "-c",
+    "user.email=t@t",
+    "commit",
+    "-qm",
+    "base",
+    "--allow-empty",
+  );
+  g("add", "paper.md");
+  g("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "paper");
+  const head = g("rev-parse", "HEAD").stdout.trim();
+  writeTree(dir, {
+    "paper.md": now,
+    ...Object.fromEntries(
+      Object.entries(rounds).map(([f, body]) => [
+        `rounds/${f}`,
+        body.replaceAll("HEAD_SHA", head),
+      ]),
+    ),
+  });
+  return dir;
+}
+const kinds = (r) => r.findings.map((f) => f.kind);
+
+test("manifest: no frontmatter, comments and blanks, a list item before any key, lists both ways", () => {
+  assert.deepEqual(parseManifest("no frontmatter", "m.md"), {
+    error: "no frontmatter block",
+    path: "m.md",
+  });
+  assert.deepEqual(
+    parseManifest(
+      [
+        "---",
+        "- stray item",
+        "# a comment",
+        "",
+        "base: abc # the base",
+        "touches:",
+        "  - 1",
+        "  - Intro",
+        "allows: [new-number, 'new-citation']",
+        "not a key line",
+        "notes:",
+        "---",
+        "",
+      ].join("\n"),
+      "m.md",
+    ),
+    {
+      path: "m.md",
+      touches: ["1", "Intro"],
+      allows: ["new-number", "new-citation"],
+      base: "abc",
+      notes: [],
+    },
+  );
+});
+
+test("`*` covers every heading; an empty text has no hedge density", () => {
+  assert.equal(covers("*", "7. Anything"), true);
+  assert.equal(census("").hedgeDensity, 0);
+});
+
+const P = (...secs) => secs.map(([h, t]) => `## ${h}\n\n${t}\n`).join("\n");
+// Untouched sections, so a round that touches one or two is not an over-broad scope.
+const REST = ["3. Three", "4. Four", "5. Five", "6. Six"].map((h) => [
+  h,
+  "Same.",
+]);
+const round = (r, base, touches, extra = "") =>
+  `---\n${r === null ? "" : `round: ${r}\n`}base: ${base}\ntouches: [${touches}]\nbudget: 1000\n${extra}---\n`;
+
+test("a manifest without a round number is named by its file, not as `round undefined`; its unresolvable base is named", () => {
+  const text = P(["1. Intro", "Words here."], ...REST);
+  const dir = repo(text, text, {
+    "a.md": round(null, "deadbeef", "1", "closed: true\n"),
+    "b.md": round(null, "HEAD_SHA", "1"),
+  });
+  const r = check(dir);
+  assert.deepEqual(kinds(r), ["unresolvable-base"]);
+  assert.match(
+    r.findings[0].msg,
+    /^paper\/rounds\/a\.md's base `deadbeef` does not resolve/,
+  );
+});
+
+test("a removed section the round declares is not a finding; more than eight new numbers are elided", () => {
+  const base = P(["1. Intro", "Words."], ["2. Gone", "Old words."], ...REST);
+  const now = P(["1. Intro", "Words 1 2 3 4 5 6 7 8 9 10."], ...REST);
+  const dir = repo(base, now, { "a.md": round(1, "HEAD_SHA", "1, 2") });
+  const r = check(dir);
+  assert.deepEqual(kinds(r), ["unauthorised-number"]);
+  assert.match(
+    r.findings[0].msg,
+    /^10 numeric literal\(s\) new to the body this round \(1, 2, 3, 4, 5, 6, 7, 8, …\)/,
+  );
+});
+
+test("the command: no paper.md is a note; no git on PATH is 'not a git repository'; no argument is the cwd", () => {
+  const empty = writeTree(join(root, "empty"), { "x.txt": "" });
+  const none = runNode(SCRIPT, [], { cwd: empty });
+  assert.equal(none.status, 0);
+  assert.match(none.stdout, new RegExp(`^ {3}no paper\\.md in ${empty}$`, "m"));
+  const dir = writeTree(join(root, "nogit"), { "paper.md": P(["1. A", "x"]) });
+  const r = runNode(SCRIPT, [dir, "--json", "--since=HEAD"], {
+    env: { PATH: dirname(process.execPath) },
+  });
+  assert.deepEqual(JSON.parse(r.stdout), [
+    {
+      kind: "unresolvable-base",
+      msg: "cannot read paper.md at `HEAD`: not a git repository. A round whose base does not resolve is a round with no gate, and it must not read as a clean run.",
+    },
+  ]);
+});
+
+test("a git that fails without a word still names the revision it could not read", () => {
+  // A stand-in `git` first on PATH: it knows the repository root, and `show` exits 1 silently.
+  const bin = writeTree(join(root, "quiet-git-bin"), {
+    git: '#!/bin/sh\ncase "$1" in rev-parse) pwd ;; show) exit 1 ;; *) exit 0 ;; esac\n',
+  });
+  chmodSync(join(bin, "git"), 0o755);
+  const dir = writeTree(join(root, "quiet"), { "paper.md": P(["1. A", "x"]) });
+  const r = runNode(SCRIPT, [dir, "--json", "--since=abc"], {
+    env: { PATH: `${bin}:${dirname(process.execPath)}` },
+  });
+  assert.deepEqual(JSON.parse(r.stdout), [
+    {
+      kind: "unresolvable-base",
+      msg: "cannot read paper.md at `abc`: git show abc:paper.md failed. A round whose base does not resolve is a round with no gate, and it must not read as a clean run.",
+    },
+  ]);
+});