paperlint 8.0.0 → 9.0.1

package/skills/plan-paper-timeline/plan-paper-timeline.effects.harness.mjs

@@ -1,51 +1,23 @@
 /**
- * plan-paper-timeline — the EFFECTS tier. What the run can actually reach, not what
- * SKILL.md says it reaches.
+ * plan-paper-timeline — the EFFECTS tier. What the run actually does, not what
+ * SKILL.md says it does.
  *
  * SIBLING, NOT REPLACEMENT. `plan-paper-timeline.harness.mjs` next door is static
  * (`checkSkill()`): frontmatter, wiring, script paths, verdict vocabulary. It is untouched.
  * This file runs the REAL `claude` CLI against a SCRIPTED MOCK MODEL (`runHarnessTest`),
- * so it costs $0 and no API key — and observes the one thing static analysis structurally
- * cannot: whether the tools this skill DECLARES EXIST WHERE IT RUNS.
+ * so it costs $0 and no API key.
  *
- * ── WHY THIS SKILL FOR THIS CHANNEL ──────────────────────────────────────────────
- * It is the only skill in the corpus whose core step is an MCP call. §3 says, literally,
- * «Use `mcp__Google_Calendar__create_event` … 🔴 Read the zone, do not assume it». Four of its ten
- * declared entries are MCP calendar tools. A declaration naming a tool that is not there is
- * invisible to every static check in this repo and to `vigiles audit`, which scores this
- * corpus Structure 100.
+ * Run A: the skill activates, its body reaches the model, and a declared, granted tool
+ * (`Read`) works. Run B: §3's prescribed `create_event` call, parsed out of SKILL.md,
+ * replayed against a strict calendar double.
  *
- * ── SAFETY: WHY THIS CANNOT TOUCH A REAL CALENDAR ───────────────────────────
- * Measured before this file was written, not assumed. The probe below is `list_events`,
- * which is READ-ONLY; `create_event`/`update_event` are NEVER called here, on purpose,
- * even though the surface turns out to be absent. The run also happens in a `mkdtemp`
- * work dir the runner deletes. If a future CLI ever exposes the calendar headlessly, the
- * read-only probe starts PASSING and this test FAILS loudly — which is the point of
- * pinning it, and is a far better way to learn it than a created event.
- *
- * ── WHAT THIS PINS (a characterization test, deliberately) ───────────────────────
- * Under `claude -p` at `CHARACTERIZED_CLI` (`lib/agent-cli-version.mjs`, 2.1.227) the whole
- * `mcp__*` surface is ABSENT, and so is `ToolSearch`.
- *
- * 🔴 THAT NUMBER IS A VALUE, NOT PROSE, and it was prose until issue #7. The probe below used
- * to run with `stdio: "ignore"`, so the version the CLI printed was never read — this tier
- * characterized whatever the runner installed that day while this paragraph kept saying 2.1.227.
- * Measured: 2.1.273 on the reporter's machine and on this one, forty-six patch releases of drift
- * that nothing in a green log could show. The version is now OBSERVED, reported in the summary
- * below, and named in every failure message — so a red says which version it characterized.
- * That means:
- *   1. §3 of this skill is UNEXECUTABLE in any headless / CI context. It is an
- *      interactive-session-only step. Nothing in the file says so.
- *   2. 🔴 THE RECORDED `ToolSearch` FINDING DOES NOT REPRODUCE HERE, AND THE CORRECTION
- *      MATTERS. `.claude/lib/skill-effects-results/README.md` (2026-08-10, $0.82)
- *      recorded "the model called ToolSearch … it isn't in allowed-tools," with the caveat
- *      that it might be an artifact of the headless environment. It is the opposite:
- *      headless has NO ToolSearch to call. Adding `ToolSearch` to `allowed-tools` would
- *      therefore fix nothing here. The reachability of these four tools is a property of
- *      the ENVIRONMENT, not of the declaration.
- *
- * If either fact changes, this file fails and says which one — that is its whole job.
- * It is not asserting that absence is good.
+ * ── WHY RUN A NO LONGER PROBES THE CALENDAR ─────────────────────────────────────
+ * It used to call `mcp__Google_Calendar__list_events` and `ToolSearch` and pin "No such
+ * tool available" as a finding about headless runs. It was a finding about the FIXTURE:
+ * the run happens in an empty `mkdtemp` with no MCP server configured, so the calendar
+ * tool is missing by construction, whatever the CLI can do. vigiles 38 refuses a
+ * scripted call to a tool the CLI does not have, for exactly this reason. Run B is
+ * where the calendar step is tested, with the surface supplied.
  *
  * Cost: $0 (scripted mock model, no API key). Wall clock ~30-60s for one CLI spawn.
  */
@@ -114,37 +86,19 @@ const r = await runHarnessTest({
   transcript: true,
   timeoutMs: 180_000,
   prompt: "plan the AISec timeline",
-  // The SESSION grant. Deliberately WIDER than the skill's declaration for `Read`, and
-  // deliberately missing `Bash` — that asymmetry is what turns the two probes below into
-  // a control and a measurement inside ONE permission configuration.
-  allowedTools: ["Read", "Write", "Skill", "ToolSearch", ...declaredMcp],
+  // The SESSION grant: the tools the script below calls, and no others.
+  allowedTools: ["Read", "Skill"],
   files: { "cfp.md": "AISec 2026 — submission 24 Jul AoE\n" },
   model: [
     { tool: "Skill", input: { skill: "plan-paper-timeline" } },
-    // CONTROL: a tool that is present and permitted. If this failed, every "absent"
-    // verdict below would be a broken run, not a finding.
+    // CONTROL: a tool that is present and permitted.
     { tool: "Read", input: { file_path: "cfp.md" } },
-    // READ-ONLY calendar probe. Never create_event / update_event — see header.
-    {
-      tool: "mcp__Google_Calendar__list_events",
-      input: { calendarId: "primary" },
-    },
-    // The tool the 2026-08-10 sweep said was missing from the declaration.
-    {
-      tool: "ToolSearch",
-      input: {
-        query: "select:mcp__Google_Calendar__create_event",
-        max_results: 1,
-      },
-    },
     { text: "done" },
   ],
 });
 
 try {
   const call = (name) => r.toolCalls.find((c) => c.name === name);
-  const absent = (c) =>
-    c !== undefined && c.isError && /No such tool available/.test(c.resultText);
 
   // ── 1. The run actually happened and the skill actually loaded ──────────────────
   // Asserted FIRST and separately from everything below. A confident "nothing was
@@ -172,48 +126,14 @@ try {
     throw new Error(
       `POSITIVE CONTROL FAILED: Read — a tool this skill declares and the session grants — ` +
         `did not succeed (${ctrl ? ctrl.resultText.slice(0, 160) : "never called"}). ` +
-        `Until this passes, no "tool absent" result below can be believed.`,
-    );
-
-  // ── 2. The pinned environment fact: the declared MCP surface is not there ───────
-  const cal = call("mcp__Google_Calendar__list_events");
-  if (!absent(cal))
-    throw new Error(
-      `THE ENVIRONMENT CHANGED — and this is good news that must be read, not silenced. ` +
-        `Observed \`claude\` ${cli.version} (characterized against ${cli.characterized}). ` +
-        `\`mcp__Google_Calendar__list_events\` is now REACHABLE from \`claude -p\` ` +
-        `(result: ${cal ? cal.resultText.slice(0, 200) : "no call recorded"}). ` +
-        `Consequences: (a) §3 of this skill is now executable headlessly, so it can finally be ` +
-        `tested for real instead of characterized; (b) 🔴 every future run of this tier can now ` +
-        `WRITE A REAL CALENDAR — re-check the safety argument in this file's header BEFORE ` +
-        `adding a create_event probe; (c) update this assertion deliberately, do not delete it.`,
-    );
-
-  const ts = call("ToolSearch");
-  if (!absent(ts))
-    throw new Error(
-      `\`ToolSearch\` is now available under \`claude -p\` ${cli.version} ` +
-        `(characterized against ${cli.characterized}) (result: ` +
-        `${ts ? ts.resultText.slice(0, 200) : "no call recorded"}). The 2026-08-10 sweep recorded ` +
-        `"ToolSearch missing from allowed-tools" as a finding about THIS SKILL; measured on ` +
-        `2026-08-11 it was a fact about the ENVIRONMENT (headless had no ToolSearch at all). ` +
-        `If it exists now, that finding becomes actionable again: add it to allowed-tools.`,
+        `The skill loaded but the run cannot use the tools it declares.`,
     );
 
-  // ── 3. What that means, stated once, where a reader will see it ────────────────
+  // ── 2. The version goes in the REPORT, not only into failures ──────────────────
   console.log(
     `✓ plan-paper-timeline [effects]: skill activated and its body reached the model; ` +
       `Read (declared+granted) works — the run is live.\n` +
-      // 🔴 The version goes in the REPORT, not only into failures. A characterization test that
-      // silently still holds is indistinguishable from one nobody re-checked, so the run says
-      // which version it held against — and says it whether or not the numbers agree.
-      `  CLI: ${cli.note}\n` +
-      `  PINNED: ${String(declaredMcp.length)} of its 10 declared entries are MCP calendar tools, ` +
-      `and the whole mcp__* surface is ABSENT under \`claude -p\`; \`ToolSearch\` is absent too.\n` +
-      `  → §3 ("Create the calendar events") is an INTERACTIVE-SESSION-ONLY step. Nothing in ` +
-      `SKILL.md says so, and no static check can see it.\n` +
-      `  → Corrects the 2026-08-10 sweep: the ToolSearch gap was environmental, not a defect ` +
-      `in this declaration.`,
+      `  CLI: ${cli.note}`,
   );
 } finally {
   r.cleanup();
@@ -222,9 +142,8 @@ try {
 // ════════════════════════════════════════════════════════════════════════════════
 // RUN B — §3 EXECUTED, not characterized
 //
-// Run A above pins that the calendar surface is absent from a headless session, which
-// is true and worth knowing and also means the skill's CENTRAL STEP has never been
-// checked by anything. Run B supplies the surface with a stand-in
+// A headless run in an empty work dir has no calendar surface, so without a stand-in
+// the skill's CENTRAL STEP is checked by nothing. Run B supplies the surface with a stand-in
 // (`fixtures/fake-google-calendar.ts`) carrying the REAL API's required-field sets,
 // so the step becomes executable for the first time.
 //

package/skills/verify-citations/SKILL.md

@@ -4,7 +4,7 @@ description: Verify every citation is a real work with correct metadata, and tha
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent]
 ---
 
-<!-- vigiles:sha256:faf8d55c8ddb82ed compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:fdb023ed7c613e1b compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
@@ -165,10 +165,13 @@ heavier than a typo, and it is exactly the class §"any regalia about third part
 
 **How to run.**
 ```
-node scripts/bib-authors.mjs <paper-dir>          # or a .bib, or a .tex with a filecontents block
+node scripts/bib-authors.mjs <paper-dir>          # the databases bibtex opened in the last build; or a .bib, or a .tex
 node scripts/bib-authors.mjs <paper-dir> --json
 ```
-Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error.
+Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error. A paper
+directory or a `.tex` is read through the build's record (`_build/sources.json`): a paper that was never built,
+or changed since, is refused (exit 2) and told to run `npx paperlint build` first — the databases are TeX's answer,
+not a reading of the source. A `.bib` named is read as itself.
 
 **Source is DBLP, and that choice is the evidence.** DBLP indexes the proceedings record and the CoRR record
 **separately**, so a single query returns both lists side by side — the cleanest proof available that the
@@ -244,7 +247,7 @@ It used to be one script, `verify-refs.mjs`; the measurement half stayed a scrip
 became twelve ESLint rules over the facts it writes.
 
 ```
-# 1. measure: parse the bibliography, ask CrossRef/arXiv, write _build/refs.facts.json
+# 1. measure: parse the bibliography bibtex opened (build the paper first), ask CrossRef/arXiv, write _build/refs.facts.json
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir>
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir> --offline  # cached responses only
 

package/skills/verify-citations/SKILL.md.spec.ts

@@ -181,10 +181,13 @@ heavier than a typo, and it is exactly the class §"any regalia about third part
 
 **How to run.**
 \`\`\`
-node scripts/bib-authors.mjs <paper-dir>          # or a .bib, or a .tex with a filecontents block
+node scripts/bib-authors.mjs <paper-dir>          # the databases bibtex opened in the last build; or a .bib, or a .tex
 node scripts/bib-authors.mjs <paper-dir> --json
 \`\`\`
-Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error.
+Exits **1** on any author-set or author-order disagreement, **0** when clean, **2** on usage/IO error. A paper
+directory or a \`.tex\` is read through the build's record (\`_build/sources.json\`): a paper that was never built,
+or changed since, is refused (exit 2) and told to run \`npx paperlint build\` first — the databases are TeX's answer,
+not a reading of the source. A \`.bib\` named is read as itself.
 
 **Source is DBLP, and that choice is the evidence.** DBLP indexes the proceedings record and the CoRR record
 **separately**, so a single query returns both lists side by side — the cleanest proof available that the
@@ -260,7 +263,7 @@ It used to be one script, \`verify-refs.mjs\`; the measurement half stayed a scr
 became twelve ESLint rules over the facts it writes.
 
 \`\`\`
-# 1. measure: parse the bibliography, ask CrossRef/arXiv, write _build/refs.facts.json
+# 1. measure: parse the bibliography bibtex opened (build the paper first), ask CrossRef/arXiv, write _build/refs.facts.json
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir>
 node .claude/skills/paper-pipeline/scripts/extract-ref-facts.mjs <paper-dir> --offline  # cached responses only
 

package/skills/verify-citations/scripts/bib-authors.check.test.mjs

@@ -13,9 +13,15 @@ import {
   checkAuthors,
   claimsPublished,
   dblpHits,
-  parseBib,
+  authorEntries,
   surnames,
 } from "./bib-authors.mjs";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { absolutePath } from "#src/domain/paths";
+
+/** This check's entries of a BibTeX text, read by the one bibtex reader. */
+const entriesIn = (bib) =>
+  authorEntries(bibReader.readFile(absolutePath("/p/refs.bib"), bib).entries);
 
 afterEach(() => vi.unstubAllGlobals());
 
@@ -215,35 +221,27 @@ test("dblpHits: no hits is an empty list; 429 is retryable; other errors are not
   );
 });
 
-test("parseBib reads quoted and bare field values, and a field that is absent", () => {
+test("authorEntries: names written family first (`and others` kept), a quoted value, a field that is absent", () => {
   assert.deepEqual(
-    parseBib(
-      '@article{k, author = "Ada Lovelace", title = {T}, journal = J, }',
+    entriesIn(
+      '@article{k, author = "Ada Lovelace and van der Berg, Jan and others", title = {The {BERT} Model}, journal = {J}}\n@misc{untitled, author = {Hopper, Grace}}',
     ),
     [
       {
         type: "article",
         key: "k",
-        author: "Ada Lovelace",
-        title: "T",
+        author: "Lovelace, Ada and van der Berg, Jan and others",
+        title: "The BERT Model",
         booktitle: "",
         journal: "J",
       },
-    ],
-  );
-});
-
-test("parseBib: braces nested inside a value, and a bare last value with no comma after it", () => {
-  assert.deepEqual(
-    parseBib("@article{k, title = {The {BERT} Model}, journal = J}"),
-    [
       {
-        type: "article",
-        key: "k",
-        author: "",
-        title: "The {BERT} Model",
+        type: "misc",
+        key: "untitled",
+        author: "Hopper, Grace",
+        title: "",
         booktitle: "",
-        journal: "J",
+        journal: "",
       },
     ],
   );

package/skills/verify-citations/scripts/bib-authors.cli.test.ts

@@ -1,7 +1,7 @@
 /**
- * bib-authors.mjs as a process: which file it picks from a paper directory, the bibliography
- * sources it reads (.bib, a .tex's filecontents or its sibling refs.bib), the file it refuses, and
- * the report and exit code for each outcome. DBLP is a preload that answers
+ * bib-authors.mjs as a process: the bibliography it reads (a .bib named, or what the last build's
+ * bibtex opened for a paper directory or a .tex — `_build/sources.json`, through `bibliographyAt`), the
+ * targets it refuses, and the report and exit code for each outcome. DBLP is a preload that answers
  * by title from a table (the documented `result.hits.hit[].info` shape) — no network.
  */
 import assert from "node:assert/strict";
@@ -15,6 +15,13 @@ import {
   useTempDir,
   writeTree,
 } from "../../../test/support.ts";
+import {
+  plantedOnDisk,
+  recordOnDisk,
+  type Shape,
+} from "../../../test/recorded-fixture.ts";
+import { absolutePath } from "#src/domain/paths";
+import { bibliographyUnreadWhy } from "#src/paper-sources";
 
 const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "bib-authors.mjs");
 const root = useTempDir("bib-authors-cli-");
@@ -32,6 +39,10 @@ const bib = (
 ) =>
   `@inproceedings{${key}, author = {${author}}, title = {${title}}, ${venue}}\n`;
 
+/** A .tex that declares the database `name`, with `preamble` before its document. */
+const declaring = (name: string, preamble = "") =>
+  `\\documentclass{article}\n${preamble}\\begin{document}x\\bibliography{${name}}\\end{document}\n`;
+
 writeTree(root, {
   // The retry backoff (1.5 s, then 3 s) and the 900 ms courtesy pause are real sleeps in the
   // script. Under CPU load they made "DBLP down" take 11.7 s once and time out. The preload
@@ -46,24 +57,53 @@ writeTree(root, {
     "  const hit = (answers[q] ?? []).map((authors) => ({ info: { title: q, venue: 'X', year: '2024',\n" +
     "    type: 'Conference and Workshop Papers', authors: { author: authors.map((text) => ({ text })) } } }));\n" +
     "  return new Response(JSON.stringify({ result: { hits: { hit } } }), { status: 200 });\n};\n",
+  "findings/paper.tex": declaring("paper"),
   "findings/paper.bib":
     bib("dropped", "Ada Lovelace and Grace Hopper", "Dropped Author") +
     bib("order", "Alan Turing and Ada Lovelace", "Swapped Order"),
   "findings/other.bib": bib("never", "X", "Never Read"),
   "twotex/b.tex": "\\documentclass{article}\n",
-  "twotex/a.tex":
-    "\\begin{filecontents*}{refs.bib}\n" +
-    bib("pre", "Ada Lovelace", "A Preprint", "journal = {arXiv preprint}") +
-    "\\end{filecontents*}\n",
-  "sibling/paper.tex": "\\documentclass{article}\n",
+  "twotex/paper.tex": declaring(
+    "refs",
+    "\\begin{filecontents*}[overwrite]{refs.bib}\n" +
+      bib("pre", "Ada Lovelace", "A Preprint", "journal = {arXiv preprint}") +
+      "\\end{filecontents*}\n",
+  ),
+  // What TeX wrote from that block: the file bibtex opened.
+  "twotex/refs.bib": bib(
+    "pre",
+    "Ada Lovelace",
+    "A Preprint",
+    "journal = {arXiv preprint}",
+  ),
+  "sibling/paper.tex": declaring("refs"),
   "sibling/refs.bib": bib("good", "Ada Lovelace", "All Good"),
-  "nobib/paper.tex": "\\documentclass{article}\n",
+  "etal/paper.tex": declaring("refs"),
   "etal/notes.txt": "not a bibliography\n",
   "etal/refs.bib":
     bib("good", "Ada Lovelace", "All Good") +
     bib("etal", "Ada Lovelace and others", "Truncated"),
+  "down/paper.tex": declaring("refs"),
   "down/refs.bib": bib("down", "Ada Lovelace", "Service Down"),
-  "empty/.keep": "",
+});
+
+/** The record of a paper whose bibliography is `db`, a file the author keeps. */
+const keeps = (db: string): Shape => ({
+  inputs: [
+    ["paper.tex", "body"],
+    [db, "preamble"],
+  ],
+  databases: [db],
+});
+recordOnDisk(join(root, "findings"), keeps("paper.bib"));
+recordOnDisk(join(root, "sibling"), keeps("refs.bib"));
+recordOnDisk(join(root, "etal"), keeps("refs.bib"));
+recordOnDisk(join(root, "down"), keeps("refs.bib"));
+// A block TeX wrote into refs.bib: the file is no input, the block is.
+recordOnDisk(join(root, "twotex"), {
+  inputs: [["paper.tex", "body"]],
+  written: ["refs.bib"],
+  databases: ["refs.bib"],
 });
 
 const run = (...args: string[]) => {
@@ -77,14 +117,16 @@ const run = (...args: string[]) => {
   };
 };
 
-test("refusals: no argument, no such path, a directory with nothing to read, a .tex with no bibliography", () => {
+test("refusals: no argument; a path with no bibliography to read, in bibliographyAt's words", () => {
+  // The path → bibliography vocabulary is tested once, beside bibliographyAt (src/paper-sources.ts).
+  // Here: that the command speaks it, and exits 2.
+  const notes = join(root, "etal", "notes.txt");
   assert.deepEqual(
-    [
-      run(),
-      run(join(root, "nope")),
-      run(join(root, "empty")),
-      run(join(root, "nobib", "paper.tex")),
-    ].map(({ status, stdout, stderr }) => ({ status, stdout, stderr })),
+    [run(), run(notes)].map(({ status, stdout, stderr }) => ({
+      status,
+      stdout,
+      stderr,
+    })),
     [
       {
         status: 2,
@@ -95,24 +137,13 @@ test("refusals: no argument, no such path, a directory with nothing to read, a .
       {
         status: 2,
         stdout: "",
-        stderr: "bib-authors: no such path: <root>/nope\n",
-      },
-      {
-        status: 2,
-        stdout: "",
-        stderr: "bib-authors: no .bib or .tex in <root>/empty\n",
-      },
-      {
-        status: 2,
-        stdout: "",
-        stderr:
-          "bib-authors: no bibliography found in <root>/nobib/paper.tex (no filecontents block, no refs.bib beside it)\n",
+        stderr: `bib-authors: ${bibliographyUnreadWhy({ kind: "not-bib-or-tex", path: absolutePath(notes) }).replaceAll(root, "<root>")}\n`,
       },
     ],
   );
 });
 
-test("a paper directory: the canonical paper.bib is read, and each difference is printed — FAIL, exit 1", () => {
+test("a paper directory: the paper.bib its \\bibliography{paper} declares is read, and each difference is printed — FAIL, exit 1", () => {
   assert.deepEqual(run(join(root, "findings")), {
     status: 1,
     stderr: "",
@@ -135,16 +166,16 @@ test("a paper directory: the canonical paper.bib is read, and each difference is
   });
 });
 
-test("two .tex files and no paper.tex: the first by name, said out loud; its filecontents is read", () => {
-  const r = run(join(root, "twotex"), "--json");
+test("a .tex named is its folder's paper: the database bibtex opened is read from the block that wrote it", () => {
+  const r = run(join(root, "twotex", "paper.tex"), "--json");
   assert.deepEqual(
     { status: r.status, stderr: r.stderr, report: parseJson(r.stdout) },
     {
       status: 0,
-      stderr:
-        "⚠️ <root>/twotex holds several .tex files and no canonical paper.tex: a.tex, b.tex — took a.tex. If that is the wrong one, name the file explicitly.\n",
+      stderr: "",
       report: {
-        file: "<root>/twotex/a.tex",
+        file: "<root>/twotex/paper.tex",
+        files: ["<root>/twotex/paper.tex"],
         entries: 1,
         findings: [],
         skipped: [],
@@ -154,7 +185,18 @@ test("two .tex files and no paper.tex: the first by name, said out loud; its fil
   );
 });
 
-test("a .tex with no filecontents reads the refs.bib beside it — PASS, exit 0", () => {
+test("a .bib named is read as itself", () => {
+  const r = run(join(root, "findings", "paper.bib"), "--json");
+  const report: unknown = parseJson(r.stdout);
+  assert.deepEqual(
+    report !== null && typeof report === "object" && "files" in report
+      ? report.files
+      : report,
+    ["<root>/findings/paper.bib"],
+  );
+});
+
+test("a .tex that declares refs and has no block reads refs.bib — PASS, exit 0", () => {
   const r = run(join(root, "sibling", "paper.tex"));
   assert.deepEqual(r, {
     status: 0,
@@ -164,16 +206,6 @@ test("a .tex with no filecontents reads the refs.bib beside it — PASS, exit 0"
   });
 });
 
-test("a file that is neither a .bib nor a .tex is refused — not swapped for the refs.bib beside it", () => {
-  const r = run(join(root, "etal", "notes.txt"));
-  assert.deepEqual(r, {
-    status: 2,
-    stdout: "",
-    stderr:
-      "bib-authors: <root>/etal/notes.txt is not a .bib or a .tex — give the paper's .bib or paper.tex\n",
-  });
-});
-
 test("an `and others` entry is printed as not applicable, not dropped", () => {
   const r = run(join(root, "etal"));
   assert.deepEqual(r, {
@@ -198,3 +230,54 @@ test("DBLP down: NOT CHECKED, PARTIAL, exit 2 — never a pass", () => {
       "PARTIAL: no disagreement among the entries reached, but 1 could not be checked — this is NOT a pass.\n",
   });
 });
+
+// The planted papers of fixtures/paper-sources, laid out as a build leaves them: the file read is the
+// one bibtex opened (tex-truth.json), or the block that wrote it.
+test.each([
+  ["v1-stale", "refs.bib"],
+  ["v2-overwrite", "paper.tex"],
+  ["v3-declared", "paper.bib"],
+  ["v4-commented", "refs.bib"],
+])("%s: reads %s", (paper, file) => {
+  const dir = join(root, "planted", paper);
+  plantedOnDisk(dir, paper);
+  const r = runNode(SCRIPT, [dir, "--json"], {
+    nodeArgs: ["--import", join(root, "dblp.mjs")],
+  });
+  const report: unknown = parseJson(r.stdout);
+  assert.deepEqual(
+    report !== null && typeof report === "object" && "files" in report
+      ? report.files
+      : report,
+    [join(dir, file)],
+  );
+});
+
+test("🔴 a paper that was not built is refused — run `npx paperlint build` first — and so is one changed since", () => {
+  const unbuilt = join(root, "unbuilt");
+  writeTree(unbuilt, {
+    "paper.tex": declaring("refs"),
+    "refs.bib": bib("good", "Ada Lovelace", "All Good"),
+  });
+  assert.deepEqual(
+    [run(unbuilt), run(join(unbuilt, "paper.tex"))].map(
+      ({ status, stdout, stderr }) => ({ status, stdout, stderr }),
+    ),
+    Array.from({ length: 2 }, () => ({
+      status: 2,
+      stdout: "",
+      stderr:
+        "bib-authors: <root>/unbuilt has not been built — run `npx paperlint build` first, which records the databases bibtex reads\n",
+    })),
+  );
+  recordOnDisk(unbuilt, keeps("refs.bib"));
+  writeTree(unbuilt, {
+    "refs.bib": bib("good", "Ada Lovelace", "All Good Edited"),
+  });
+  assert.deepEqual(run(unbuilt), {
+    status: 2,
+    stdout: "",
+    stderr:
+      "bib-authors: <root>/unbuilt changed since the last build (refs.bib edited) — run `npx paperlint build` first\n",
+  });
+});

package/skills/verify-citations/scripts/bib-authors.d.mts

@@ -1,7 +1,7 @@
 // Types for bib-authors.mjs, for the exports `src/` imports — the same arrangement as
 // `verify-cites.d.mts` beside it. Only what `src/` imports is declared.
 
-/** One entry as `parseBib` returns it; a field the entry lacks is "". */
+/** One entry as `authorEntries` returns it; a field the entry lacks is "". */
 export interface BibEntry {
   readonly type: string;
   readonly key: string;
@@ -11,7 +11,27 @@ export interface BibEntry {
   readonly journal: string;
 }
 
-export declare function parseBib(text: string): BibEntry[];
+/** A name of a name list, in its parts (`BibName`). */
+export interface ReadName {
+  readonly lastName?: string;
+  readonly firstName?: string;
+  readonly prefix?: string;
+  readonly suffix?: string;
+  readonly name?: string;
+}
+
+/** An entry as the bibtex reader reads it (src/domain/paper-sources.ts), as far as this check uses it. */
+export interface ReadEntry {
+  readonly type: string;
+  readonly key: string;
+  readonly fields: Readonly<Record<string, string>>;
+  readonly names: Readonly<Record<string, readonly ReadName[]>>;
+}
+
+/** The entries this check reads, from the bibtex reader's. */
+export declare function authorEntries(
+  entries: readonly ReadEntry[],
+): BibEntry[];
 
 /** True when the author list ends in `and others` — there is nothing complete to compare. */
 export declare const truncated: (authorField: string) => boolean;