paperlint 7.2.0 → 9.0.0

package/skills/tighten-paper/SKILL.md.spec.ts

@@ -40,31 +40,12 @@ counter, is not this skill; it is the damage this skill exists to undo.
 If you are invoked while the author is still adding material, say so and decline the pass. The right
 answer is "not yet", not a smaller cut.
 
-## 🏗 START WITH THE MECHANICAL LEG — run \`structure.mjs\` (added 2026-08-05)
+## 🏗 START WITH THE SHAPE — weigh every section before judging it
 
-\`\`\`
-node .claude/skills/tighten-paper/structure.mjs <paper.md>              # whole paper
-node .claude/skills/tighten-paper/structure.mjs <paper.md> --section=3  # one section
-\`\`\`
-
-🔴 **THE SCRIPT NO LONGER FINDS ANYTHING — it is an INVENTORY (2026-08-26).** All sixteen of its
-checks moved into ESLint rules (\`eslint-rules/paper-structure.mjs\`). The findings you used to read
-here now come from:
-
-\`\`\`
-npx eslint --no-config-lookup --config eslint.config.mjs <paper.md>
-\`\`\`
-
-⚠️ Do NOT pass \`--flags-only\`. It is kept only because two harnesses assert on its silence, and it
-prints nothing and exits 0 whatever the paper looks like. Measured 26.08 on \`the reference paper\`:
-\`--flags-only\` printed 0 lines while ESLint on the same bytes reported **6 structural findings**
-(subsection-size ×2 · section-lead · free-section-size ×2 · block-ungraded). A mode that cannot
-speak is not a check, and reading its silence as "clean" is the defect this pipeline is named for.
-
-What the inventory prints, and why it stays a script: the outline **in order** — every heading, its
-own words, its total with subsections, its share of the body, and the \`carries:\`/\`score:\`/\`verdict:\`
-note the section wrote about itself, printed beside its weight. That comparison is the whole point
-and a linter cannot make it: a finding has nowhere to put a table.
+Write the outline out **in order**: every heading, its own words before its first subsection, its
+total with subsections, its share of the body — and beside each, the \`carries:\`/\`score:\`/\`verdict:\`
+note the section wrote about itself. That comparison, a section's weight printed next to what it
+claims about itself, is the whole point.
 
 🔴 **Why this exists, and why word counts alone mislead.** Asked whether a paper short-changed its
 contribution, per-section word counts said no — the contribution had 38% more words than related
@@ -73,7 +54,7 @@ owned **0, 28 and 38** words before their first subsection. Nothing in the toolc
 question, because every metric was per-sentence or per-document and none was per-section. The author's
 word for the result was a "salad" — a jumbled mix — and he was right while the numbers said fine.
 
-**What the script does NOT decide, and you must:** the ORDER, the NAMES, and whether a section earns
+**What the count does NOT decide, and you must:** the ORDER, the NAMES, and whether a section earns
 its place. Those are judgement, and pretending otherwise would be the failure this whole pipeline
 exists to prevent.
 
@@ -194,18 +175,24 @@ called it "fat for no reason" after a pass that cut almost nothing and left it 1
 
 A verdict that lives in a chat log is gone by the next session, and the next session then re-derives
 it or ignores it. **Every section and subsection gets a one-line verdict comment immediately above its
-heading**, in the paper source, stamped with the date and the skill that produced it:
-
-\`\`\`
-<!-- TIGHTEN 2026-08-06 · score 8/10 · verdict: KEEP · 190w
-     carries: tools get close but none resolves a NAMED rule against a committed config
-     because: it is the only place the tool-ecosystem gap is closed; a reviewer who skips it
-              asks "hasn't this been done" and gets no answer -->
-<!-- TIGHTEN 2026-08-06 · score 5/10 · verdict: SHORTEN -89w · 210w
-     carries: why a linter for the rules file cannot work
-     because: the point lands in two sentences; the rest re-establishes what §2 already did -->
-<!-- TIGHTEN 2026-08-06 · score 2/10 · verdict: MOVE→artifact · 45w
-     carries: nothing the reader must hold to judge the contribution -->
+heading**, in \`paper.tex\`, as LaTeX \`%\` comments, stamped with the date and the skill that
+produced it:
+
+\`\`\`latex
+% TIGHTEN 2026-08-06 · score 8/10 · verdict: KEEP · 190w
+%   carries: tools get close but none resolves a NAMED rule against a committed config
+%   because: it is the only place the tool-ecosystem gap is closed; a reviewer who skips it
+%            asks "hasn't this been done" and gets no answer
+\\section{Related tools}
+
+% TIGHTEN 2026-08-06 · score 5/10 · verdict: SHORTEN -89w · 210w
+%   carries: why a linter for the rules file cannot work
+%   because: the point lands in two sentences; the rest re-establishes what §2 already did
+\\subsection{Why not a linter}
+
+% TIGHTEN 2026-08-06 · score 2/10 · verdict: MOVE→artifact · 45w
+%   carries: nothing the reader must hold to judge the contribution
+\\subsection{Implementation notes}
 \`\`\`
 
 🔴 **Before assigning any \`MOVE→\` verdict, read \`paper-pipeline/references/body-vs-appendix.md\`.**
@@ -230,7 +217,7 @@ written and **not one ever concluded "cut me"**. Author, 2026-08-06, reading the
 value on every page and compared nothing.
 
 The pairing is the mechanism: **a low score beside a KEEP verdict is a visible contradiction**, and
-\`structure.mjs\` reports it. Prose cannot contradict itself; a number can.
+the outline above puts the two side by side. Prose cannot contradict itself; a number can.
 
 **Calibration, so the scale does not drift to "everything is an 8":**
 - **9–10** — remove it and a reviewer cannot assess the contribution. The claim, its evidence, its price.
@@ -285,10 +272,10 @@ Rules for these comments:
   unpriced prose accumulates, because nothing there costs a page.
 - **Stale beats absent, but not by much.** A comment whose date precedes the last substantive edit to
   its section is stale; re-grade it rather than trusting it.
-- **A verdict nobody executed is a note, not a decision.** \`structure.mjs\` reports blocks still
-  carrying a non-KEEP verdict — a paper full of unexecuted CUTs is worse than one never graded,
+- **A verdict nobody executed is a note, not a decision.** List the blocks still carrying a
+  non-KEEP verdict — a paper full of unexecuted CUTs is worse than one never graded,
   because it reads as decided.
-- They are working notes: stripped before typesetting, like every other \`<!-- -->\` block.
+- They are working notes: a \`%\` comment never reaches the PDF.
 - The chat summary still gets written — but it is the *derivative*, and the paper is the record.
 
 ## 🧱 Enforce subsections — a section without them is a wall

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());
 
@@ -50,15 +56,6 @@ test("checkAuthors sorts every kind of entry into its bucket", async () => {
     entry("nomatch", "Ada Lovelace", "Nobody Has This"),
     entry("onlycorr", "Ada Lovelace", "Only On CoRR"),
     entry("down", "Ada Lovelace", "Service Down"),
-    {
-      type: "mdref",
-      key: "sw",
-      unparsed: true,
-      author: "",
-      title: "",
-      booktitle: "",
-      journal: "",
-    },
   ];
   const answers = {
     "Same Paper": [hit("Same Paper.", ["Ada Lovelace", "Alan Turing"])],
@@ -101,10 +98,6 @@ test("checkAuthors sorts every kind of entry into its bucket", async () => {
         },
       ],
       skipped: [
-        {
-          key: "sw",
-          why: "no author/title — a reference to software or a dataset, DBLP does not apply",
-        },
         {
           key: "etal",
           why: "author list ends in `and others` — completeness not checkable",
@@ -228,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 three
- * bibliography sources it reads (.bib, a .tex's filecontents or its sibling refs.bib, a markdown
- * reference list), 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,22 +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",
-  "md/paper.md":
-    "# P\n\n## References\n\n1. A. Lovelace. *All Good.* Proc. X, 2024.\n2. some-npm-package, https://npm.example\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[]) => {
@@ -75,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,
@@ -93,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, .tex or paper.md 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: "",
@@ -133,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: [],
@@ -152,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,
@@ -162,15 +206,15 @@ test("a .tex with no filecontents reads the refs.bib beside it — PASS, exit 0"
   });
 });
 
-test("a markdown reference list: a software entry is not applicable, not dropped", () => {
-  const r = run(join(root, "md"));
+test("an `and others` entry is printed as not applicable, not dropped", () => {
+  const r = run(join(root, "etal"));
   assert.deepEqual(r, {
     status: 0,
     stderr: "",
     stdout:
-      "== bib-authors: <root>/md/paper.md ==\n" +
-      "  · n/a ref2 — no author/title — a reference to software or a dataset, DBLP does not apply\n\n" +
-      "-- 1 entries · 0 difference(s) · 1 not applicable · 0 NOT CHECKED\nPASS: no author-list disagreement.\n",
+      "== bib-authors: <root>/etal/refs.bib ==\n" +
+      "  · n/a etal — author list ends in `and others` — completeness not checkable\n\n" +
+      "-- 2 entries · 0 difference(s) · 1 not applicable · 0 NOT CHECKED\nPASS: no author-list disagreement.\n",
   });
 });
 
@@ -186,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;