paperlint 2.1.0 → 3.0.0

package/skills/grade-paper-writing/SKILL.md

@@ -4,7 +4,7 @@ description: Use when asking "does this paper read well?" / "is the writing any
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill, Bash(node .claude/skills/paper-pipeline/scripts/announce.mjs:*), Bash(node .claude/skills/paper-pipeline/scripts/ledger.mjs:*)]
 ---
 
-<!-- vigiles:sha256:374531c7f64e998e compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c0907d5c98e2c831 compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
 
 # grade-paper-writing — grade how the paper READS, then fix it sentence by sentence
 
@@ -255,6 +255,25 @@ is what happened.
    `PIPELINE-STATUS.md` (Wc row). Same rule as `pc-panel-review`'s ledger and `analyze-sibling-paper`'s
    `siblings/` — review artifacts live colocated and ride with the paper to camera-ready/extension.
 
+## The report's frontmatter — the findings, as records
+
+The report opens with YAML frontmatter that lists what it found, one record per finding.
+`paperlint lint` validates it (`review/frontmatter`): an **open** finding must name the
+pipeline `cause` that let it through — fix that, and the text edit falls out of running the
+fixed tool.
+
+```yaml
+---
+findings:
+  - id: 1
+    status: open            # open | fixed | wontfix
+    cause: missing-skill    # skill-defect | missing-skill | hook | rule — required when open
+    title: "§3 opens on a term the reader has not met"
+  - id: 2
+    status: fixed
+---
+```
+
 ## Record the verdict
 
 🔴 LAST step, once the deliverable exists:

package/skills/grade-paper-writing/SKILL.md.spec.ts

@@ -271,6 +271,25 @@ is what happened.
    \`PIPELINE-STATUS.md\` (Wc row). Same rule as \`pc-panel-review\`'s ledger and \`analyze-sibling-paper\`'s
    \`siblings/\` — review artifacts live colocated and ride with the paper to camera-ready/extension.
 
+## The report's frontmatter — the findings, as records
+
+The report opens with YAML frontmatter that lists what it found, one record per finding.
+\`paperlint lint\` validates it (\`review/frontmatter\`): an **open** finding must name the
+pipeline \`cause\` that let it through — fix that, and the text edit falls out of running the
+fixed tool.
+
+\`\`\`yaml
+---
+findings:
+  - id: 1
+    status: open            # open | fixed | wontfix
+    cause: missing-skill    # skill-defect | missing-skill | hook | rule — required when open
+    title: "§3 opens on a term the reader has not met"
+  - id: 2
+    status: fixed
+---
+\`\`\`
+
 ## Record the verdict
 
 🔴 LAST step, once the deliverable exists:

package/skills/paper-pipeline/scripts/consumer.d.mts

@@ -29,5 +29,4 @@ export declare function installedSkills(dir: string): string[];
 export declare function packageVenuesDir(): string;
 export declare const SHIPPED_SKILLS_DIR: string;
 export declare const PACKAGE_NAME: "paperlint";
-export declare const LEGACY_PACKAGE_NAME: "research-paper-pipeline";
 export declare const BIN_FILE: "bin/paperlint.mjs";

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

@@ -32,7 +32,6 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import {
-  CONFIG_KEY,
   DEFAULT_SCRIPTS_ROOT,
   consumerRoot,
   consumerSkillsDir,
@@ -87,15 +86,12 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const TMP = realpathSync(mkdtempSync(join(tmpdir(), "consumer-harness-")));
 process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
 
-/** A throwaway consumer repository with the given `paperlint` block (or none). */
+/** A throwaway consumer repository with the given root `paperlint.json` settings (or none). */
 function fakeConsumer(block) {
   const root = mkdtempSync(join(TMP, "repo-"));
-  writeFileSync(
-    join(root, "package.json"),
-    JSON.stringify(
-      block === undefined ? { name: "x" } : { name: "x", [CONFIG_KEY]: block },
-    ),
-  );
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "x" }));
+  if (block !== undefined)
+    writeFileSync(join(root, "paperlint.json"), JSON.stringify(block));
   return root;
 }
 /** A directory that looks like an installed copy of this package. */
@@ -188,7 +184,7 @@ function installedDir(root) {
   );
   assert.match(
     err.message,
-    /package\.json/,
+    /paperlint\.json/,
     "the refusal must name the file the key goes in",
   );
 }
@@ -409,12 +405,12 @@ assert.equal(
   );
   assert.match(
     missing.message,
-    /package\.json/,
+    /paperlint\.json/,
     "the refusal must name the file the key goes in",
   );
 
   // And the default's version of that message must say the default was used — otherwise someone
-  // who declared nothing goes looking in package.json for a line that is not there.
+  // who declared nothing goes looking in paperlint.json for a line that is not there.
   assert.throws(
     () => scriptsRoot({ env: {}, cwd: fakeConsumer(undefined) }),
     /Nothing was declared/,
@@ -462,7 +458,7 @@ assert.equal(
   assert.equal(s.ledger, "a/b/ledger.mjs");
 
   // EXACTLY ONE slash, whatever the consumer typed. `scriptsRoot()` returns the declaration
-  // verbatim, so a trailing slash in package.json arrives here intact; `${root}/` would then give
+  // verbatim, so a trailing slash in paperlint.json arrives here intact; `${root}/` would then give
   // `a/b//`, which matches nothing — the silent direction again.
   const typedSlash = pipelineScripts("a/b/");
   assert.equal(

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

@@ -56,7 +56,7 @@
  * ── THE LEDGER, THREE RUNGS ─────────────────────────────────────────────────
  *   1. `PIPELINE_LEDGER` in the environment — always wins. This is what test harnesses set to
  *      keep fixture rows out of real history, so it must outrank a declaration on disk.
- *   2. `"paperlint": { "ledger": "…" }` in the CONSUMER's `package.json`, read
+ *   2. `{ "ledger": "…" }` in the CONSUMER's root `paperlint.json`, read
  *      from `process.cwd()`, resolved relative to it.
  *   3. `runs.jsonl` beside this file — ONLY when this file is not inside `node_modules`, i.e.
  *      when the package is being developed in its own checkout. Inside `node_modules` with
@@ -75,7 +75,6 @@
  */
 import {
   existsSync,
-  readFileSync,
   readdirSync,
   readlinkSync,
   realpathSync,
@@ -86,7 +85,11 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 // Re-exported, not re-declared — see the note in `lib/paper-config.mjs`. This file is not a hook
 // and never needed its own copy.
-import { CONFIG_KEY, settingsOf } from "../../../lib/paper-config.mjs";
+import {
+  CONFIG_FILE,
+  CONFIG_KEY,
+  settingsOf,
+} from "../../../lib/paper-config.mjs";
 export { CONFIG_KEY, settingsOf };
 
 /**
@@ -144,13 +147,6 @@ export function packageVenuesDir() {
  */
 export const PACKAGE_NAME = "paperlint";
 
-/**
- * The name the package was published under before 2.0.0. Only for recognising what an older
- * install left behind (hook commands, skill links, the config key) so `init` can replace it and
- * `doctor` can name it.
- */
-export const LEGACY_PACKAGE_NAME = "research-paper-pipeline";
-
 /**
  * The package's one executable, relative to the package root — what `bin` in package.json names
  * and what every hook command runs. Named like the package; `consumer.harness.mjs` checks it
@@ -245,16 +241,6 @@ function readlinkOr(entry) {
   }
 }
 
-/** The consumer's parsed `package.json`, or `null` when there is none or it does not parse. */
-export function consumerPkg(opts) {
-  const file = join(consumerRoot(opts), "package.json");
-  try {
-    return JSON.parse(readFileSync(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
 /**
  * True when `dir` lies inside a `node_modules` directory.
  *
@@ -282,7 +268,7 @@ export function ledgerPath(
 
   // Rung 2 — the consumer's declaration.
   const root = consumerRoot({ env, cwd });
-  const declared = settingsOf(consumerPkg({ env, cwd }))?.ledger;
+  const declared = settingsOf(consumerRoot({ env, cwd }))?.ledger;
   // 🔴 `declared === undefined`, NOT `declared ?? default` — the same distinction `papersRoot()`
   // makes and for the same reason: `"ledger": null` is a keystroke, not an absence, and reading
   // it as "nothing was declared" would silently pick a different file than the one asked for.
@@ -299,8 +285,8 @@ export function ledgerPath(
     throw new Error(
       `${CONFIG_KEY}: no ledger location is declared, and the default (a file beside this ` +
         `module) is inside node_modules, which \`npm ci\` deletes.\n` +
-        `Declare where the ledger lives, in ${join(root, "package.json")}:\n` +
-        `  "${CONFIG_KEY}": { "ledger": "docs/pipeline-runs.jsonl" }\n` +
+        `Declare where the ledger lives, in ${join(root, CONFIG_FILE)}:\n` +
+        `  { "ledger": "docs/pipeline-runs.jsonl" }\n` +
         `or set PIPELINE_LEDGER for a single run.\n` +
         `This is thrown rather than defaulted on purpose: appending to a path under ` +
         `node_modules succeeds, so the rows would look recorded right up until the next ` +
@@ -321,7 +307,7 @@ export function ledgerPathExisting(hereDir, opts) {
   if (!existsSync(p))
     throw new Error(
       `${CONFIG_KEY}: the ledger "${p}" does not exist. Create it (an empty file is a valid ` +
-        `empty ledger) or fix the "ledger" declaration in package.json.`,
+        `empty ledger) or fix the "ledger" declaration in ${CONFIG_FILE}.`,
     );
   return p;
 }
@@ -374,7 +360,7 @@ export const DEFAULT_SCRIPTS_ROOT = ".claude/skills/paper-pipeline/scripts";
  */
 export function scriptsRoot({ env = process.env, cwd = process.cwd() } = {}) {
   const root = consumerRoot({ env, cwd });
-  const declared = settingsOf(consumerPkg({ env, cwd }))?.scripts;
+  const declared = settingsOf(consumerRoot({ env, cwd }))?.scripts;
   // 🔴 `declared === undefined`, NOT `declared ?? DEFAULT` — the same distinction `papersRoot()`
   // and `ledgerPath()` make, for the same reason: `"scripts": null` is a keystroke, not an
   // absence, and silently substituting the default for it hides a typo behind a working run.
@@ -393,8 +379,8 @@ export function scriptsRoot({ env = process.env, cwd = process.cwd() } = {}) {
         `instruction would point at a directory the repository does not track.\n` +
         `Keep a symlink where the prose already looks —\n` +
         `  ${join(root, DEFAULT_SCRIPTS_ROOT)} -> node_modules/${CONFIG_KEY}/skills/paper-pipeline/scripts\n` +
-        `— or declare the real, repository-relative location in ${join(root, "package.json")}:\n` +
-        `  "${CONFIG_KEY}": { "scripts": "path/to/pipeline/scripts" }\n` +
+        `— or declare the real, repository-relative location in ${join(root, CONFIG_FILE)}:\n` +
+        `  { "scripts": "path/to/pipeline/scripts" }\n` +
         `(If nothing was declared, the root itself is under node_modules: run the command from ` +
         `the consumer repository, or export CLAUDE_PROJECT_DIR.)`,
     );
@@ -403,9 +389,9 @@ export function scriptsRoot({ env = process.env, cwd = process.cwd() } = {}) {
       `${CONFIG_KEY}: the pipeline scripts path "${rel}" does not exist under ${root}.\n` +
         (declared === undefined
           ? `Nothing was declared, so the default "${DEFAULT_SCRIPTS_ROOT}" was used. Create the ` +
-            `symlink there, or declare the real location in package.json:\n` +
-            `  "${CONFIG_KEY}": { "scripts": "path/to/pipeline/scripts" }`
-          : `It is declared in package.json under "${CONFIG_KEY}" as ` +
+            `symlink there, or declare the real location in ${CONFIG_FILE}:\n` +
+            `  { "scripts": "path/to/pipeline/scripts" }`
+          : `It is declared in ${CONFIG_FILE} as ` +
             `"scripts": ${JSON.stringify(declared)}. Fix it there, or create the directory.`) +
         `\nThis is thrown rather than ignored on purpose: this value is a PREFIX that callers ` +
         `filter prose with, so a wrong one matches no instruction at all and every check built ` +
@@ -453,7 +439,7 @@ export function consumerTimezone({
   env = process.env,
   cwd = process.cwd(),
 } = {}) {
-  const declared = settingsOf(consumerPkg({ env, cwd }))?.timezone;
+  const declared = settingsOf(consumerRoot({ env, cwd }))?.timezone;
   // 🔴 `declared === undefined`, NOT `declared ?? DEFAULT` — the same distinction every carrier
   // above makes: `"timezone": null` is a keystroke, not an absence.
   const tz = declared === undefined ? DEFAULT_TIMEZONE : declared;
@@ -467,7 +453,7 @@ export function consumerTimezone({
     throw new RangeError(
       `${CONFIG_KEY}: "timezone" is ${JSON.stringify(tz)}, which is not an IANA time zone this ` +
         `runtime knows (e.g. "Europe/Berlin", "America/New_York", "UTC").\n` +
-        `Fix it in package.json under "${CONFIG_KEY}".\n` +
+        `Fix it in ${CONFIG_FILE}.\n` +
         `This throws rather than falling back to ${DEFAULT_TIMEZONE} on purpose: a silent fallback ` +
         `would put every deadline anchor at the wrong hour while looking like it worked.`,
     );
@@ -505,7 +491,7 @@ export function consumerContactEmail({
   env = process.env,
   cwd = process.cwd(),
 } = {}) {
-  const declared = settingsOf(consumerPkg({ env, cwd }))?.contactEmail;
+  const declared = settingsOf(consumerRoot({ env, cwd }))?.contactEmail;
   if (declared === undefined || declared === null) return null;
   if (typeof declared !== "string" || !declared.includes("@"))
     throw new TypeError(

package/skills/paper-pipeline/scripts/extract-ref-facts.harness.mjs

@@ -21,7 +21,11 @@
  * as success, so an exported test object would report ✓ without running anything.
  */
 import assert from "node:assert/strict";
-import { PAPERS_DIR_FIELD } from "../../../lib/paper-config.mjs";
+import {
+  DEFAULT_PAPERS_ROOT,
+  PAPERS_DIR_FIELD,
+  settingsOf,
+} from "../../../lib/paper-config.mjs";
 import {
   existsSync,
   mkdirSync,
@@ -57,9 +61,7 @@ const X = await import(join(HERE, "extract-ref-facts.mjs"));
 // A directory on disk answers the same question without knowing any name in advance.
 const PAPERS_ROOT = join(
   ROOT,
-  JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"))["paperlint"]?.[
-    PAPERS_DIR_FIELD
-  ] ?? "papers",
+  settingsOf(ROOT)?.[PAPERS_DIR_FIELD] ?? DEFAULT_PAPERS_ROOT,
 );
 const REAL_PAPERS = existsSync(PAPERS_ROOT)
   ? readdirSync(PAPERS_ROOT, { withFileTypes: true })

package/skills/paper-pipeline/scripts/run-mechanical.mjs

@@ -33,13 +33,7 @@
 
 import { record, ABSTENTIONS } from "./ledger.mjs";
 import { execFileSync } from "node:child_process";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { isMain, settingsOf } from "./consumer.mjs";
@@ -83,10 +77,7 @@ const ROOT = consumerRoot();
 // simply do not run: `needs()` below checks the directory on disk, so the absence reads as
 // ABSTAINED `input-missing`, not as a crash and not as a clean run.
 const CITE_CHECKS =
-  process.env.PIPELINE_CITE_CHECKS ||
-  settingsOf(JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")))
-    ?.citeChecks ||
-  null;
+  process.env.PIPELINE_CITE_CHECKS || settingsOf(ROOT)?.citeChecks || null;
 // The citation-checker directory exists and is declared. It sits in the `needs()` of every row
 // that calls it: without that a wrong or undeclared path would fail with a python stack trace, and
 // in `flags` mode a stack trace is counted line by line and goes into the ledger as a FINDING whose

package/skills/plan-paper-timeline/SKILL.md

@@ -4,7 +4,7 @@ description: Turn a venue's CFP dates into a scheduled, buffered plan on the Goo
 allowed-tools: [Read, Write, Grep, Glob, mcp__Google_Calendar__list_events, mcp__Google_Calendar__search_events, mcp__Google_Calendar__create_event, mcp__Google_Calendar__update_event, Bash(node .claude/skills/paper-pipeline/scripts/announce.mjs:*), Bash(node .claude/skills/paper-pipeline/scripts/ledger.mjs:*)]
 ---
 
-<!-- vigiles:sha256:9009b62e211cf421 compiled from skills/plan-paper-timeline/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:faf0c175f1a0c5e5 compiled from skills/plan-paper-timeline/SKILL.md.spec.ts -->
 
 # plan-paper-timeline — CFP dates → a buffered, filing-aware schedule
 
@@ -96,7 +96,7 @@ Use `mcp__Google_Calendar__create_event` for three anchors per paper. 🔴 **Rea
 assume it** — it is the `timezone` carrier, and it is the author's, not the pipeline's:
 
 ```
-node -p "((p) => p.paperlint ?? p['research-paper-pipeline'])(require('./package.json'))?.timezone ?? 'UTC'"
+node -p "(() => { try { return require('./paperlint.json')?.timezone } catch {} })() ?? 'UTC'"
 ```
 
 The example below shows the default, `UTC`; substitute whatever that command prints.

package/skills/plan-paper-timeline/SKILL.md.spec.ts

@@ -113,7 +113,7 @@ Use \`mcp__Google_Calendar__create_event\` for three anchors per paper. 🔴 **R
 assume it** — it is the \`timezone\` carrier, and it is the author's, not the pipeline's:
 
 \`\`\`
-node -p "((p) => p.paperlint ?? p['research-paper-pipeline'])(require('./package.json'))?.timezone ?? 'UTC'"
+node -p "(() => { try { return require('./paperlint.json')?.timezone } catch {} })() ?? 'UTC'"
 \`\`\`
 
 The example below shows the default, \`UTC\`; substitute whatever that command prints.

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

@@ -383,7 +383,7 @@ try {
     //
     // 🔴 THIS USED TO COMPARE AGAINST ONE HARD-CODED ZONE — the first consumer's. That is exactly
     // the thing a package may not know: the same CFP date is a different wall-clock hour for every
-    // author, so the zone is the `timezone` CARRIER, read from the consumer's package.json. What
+    // author, so the zone is the `timezone` CARRIER, read from the project's paperlint.json. What
     // the PRESCRIPTION in §3 must show is therefore not anybody's real zone but the documented
     // DEFAULT, next to the instruction telling the model to substitute the declared one.
     //

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

@@ -53,8 +53,8 @@ process.exit(
         edits: [
           [
             SKILL,
-            "(require('./package.json'))?.timezone ?? 'UTC'",
-            "(require('./package.json'))?.papersDir ?? 'papers'",
+            "require('./paperlint.json')?.timezone } catch {} })() ?? 'UTC'",
+            "require('./paperlint.json')?.papersDir } catch {} })() ?? 'papers'",
           ],
         ],
         harness: HARNESS,

package/skills/render-paper/check-render.sh

@@ -348,9 +348,8 @@ fi
 # and it does it WIDER: the block here skipped review mode, the rule judges the artifact always. Two
 # sources of truth about one fact drift apart — so the duplicate was deleted, not kept "just in case".
 #
-# 🔴 The condition under which this becomes a loss: the rule looks at papers that declared their venue
-# in `venue.json`. Should a paper appear with a build but without `venue.json`, nobody will check its
-# fonts. Today there are none (all three real papers are declared).
+# 🔴 The condition under which this becomes a loss: the rule looks at papers whose `paperlint.json`
+# names a venue preset. A paper with a build but no preset gets its fonts checked by nobody.
 
 # --- chktex, if installed: LaTeX-source typography the log cannot see ---
 # Adopted 2026-08-24 instead of writing our own. Measured first: out of the box it produced 28

package/skills/render-paper/render-paper.harness.mjs

@@ -36,8 +36,8 @@ import { dirname, join } from "node:path";
 import { checkSkill } from "../../lib/skill-checks.mjs";
 import { papersRoot } from "../../eslint-rules/papers.mjs";
 import {
-  consumerPkg,
   consumerRoot,
+  settingsOf,
 } from "../paper-pipeline/scripts/consumer.mjs";
 
 await checkSkill("render-paper");
@@ -308,7 +308,7 @@ await checkSkill("render-paper");
   // and say so out loud.
   const root = (() => {
     try {
-      return papersRoot(consumerPkg(), consumerRoot());
+      return papersRoot(settingsOf(consumerRoot()), consumerRoot());
     } catch {
       return null;
     }

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:f35db5aec55b4691 compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:2bb9f6f1233094cf compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
@@ -136,6 +136,15 @@ any `false` (fabrication)** — `unresolvable` alone is advisory and does NOT fa
 narrowed-false philosophy. API responses are cached to `scripts/.cite-cache.json` (gitignored) so re-runs are
 cheap and deterministic.
 
+## 5a. Both checks run on every `paperlint build`
+
+`npx paperlint build` runs `verify-cites` and `bib-authors` over the paper's bibliography after the PDF is
+built and records the verdicts, with the SHA-256 of the bibliography it checked, in
+`<paper>/_build/references.json`. `paperlint lint` reads that record offline: `paper/cite-exists` and
+`paper/author-list` report a failing entry on its own line, `paper/refs-fresh` says when the bibliography
+changed since, and `paper/refs-checked` warns when nothing was recorded or the build had no network. The
+step never fails the build. Run the scripts by hand (below) to read a single verdict in full.
+
 ## 5b. The author-list gate — `scripts/bib-authors.mjs`
 
 `verify-cites.mjs` answers *"does this citation exist, and does the id point at it?"*. There is a second

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

@@ -152,6 +152,15 @@ any \`false\` (fabrication)** — \`unresolvable\` alone is advisory and does NO
 narrowed-false philosophy. API responses are cached to \`scripts/.cite-cache.json\` (gitignored) so re-runs are
 cheap and deterministic.
 
+## 5a. Both checks run on every \`paperlint build\`
+
+\`npx paperlint build\` runs \`verify-cites\` and \`bib-authors\` over the paper's bibliography after the PDF is
+built and records the verdicts, with the SHA-256 of the bibliography it checked, in
+\`<paper>/_build/references.json\`. \`paperlint lint\` reads that record offline: \`paper/cite-exists\` and
+\`paper/author-list\` report a failing entry on its own line, \`paper/refs-fresh\` says when the bibliography
+changed since, and \`paper/refs-checked\` warns when nothing was recorded or the build had no network. The
+step never fails the build. Run the scripts by hand (below) to read a single verdict in full.
+
 ## 5b. The author-list gate — \`scripts/bib-authors.mjs\`
 
 \`verify-cites.mjs\` answers *"does this citation exist, and does the id point at it?"*. There is a second

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

@@ -192,7 +192,7 @@ function bibTextFrom(target) {
  * Only three fields are needed (type, key, author, title, booktitle/journal), and a full
  * BibTeX grammar would be a second thing to maintain. Brace-depth counting is enough and
  * is exercised by the colocated test. */
-function parseBib(text) {
+export function parseBib(text) {
   const out = [];
   const re = /@(\w+)\s*\{\s*([^,\s]+)\s*,/g;
   let m;
@@ -289,7 +289,7 @@ export function claimsPublished(e) {
 
 /* ---------- DBLP ---------- */
 
-async function dblpHits(title) {
+export async function dblpHits(title) {
   const url = `${DBLP}/?q=${encodeURIComponent(title)}&format=json&h=6`;
   // Per-request timeout: a check that hangs is indistinguishable from a check that is dead,
   // and this one runs 25+ requests. Measured 2026-08-24: a single unbounded query stalled the
@@ -335,23 +335,31 @@ export function compare(ourSurnames, theirSurnames) {
   return { missing, extra, orderDiffers };
 }
 
-function die(msg) {
-  console.error(`bib-authors: ${msg}`);
-  process.exit(2);
-}
-
-async function main() {
-  const args = process.argv.slice(2).filter((a) => a !== "--json");
-  const asJson = process.argv.includes("--json");
-  if (!args[0])
-    die("usage: bib-authors.mjs <paper-dir|file.bib|file.tex> [--json]");
-
-  const { text, file, markdown } = bibTextFrom(args[0]);
-  const parsed = markdown ? parseMarkdownRefs(text) : parseBib(text);
-  const entries = parsed.filter((e) => e.title && e.author);
+/**
+ * The comparison over parsed entries, the network behind `lookup` (DBLP by default). Returns the
+ * buckets main() prints and `paperlint build` records: `findings` (the author list differs from
+ * the published version's), `matched` (compared, equal), `skipped` (not applicable), `unchecked`
+ * (the lookup FAILED — never a pass). An entry in none of them was a preprint entry, which may
+ * carry preprint metadata.
+ *
+ * @param lookup  title → DBLP-shaped hits; throws on a failed request (`retryable` for a 429)
+ * @param pause   ms → a promise; DBLP asks for gentle clients. A test passes `() => {}`.
+ */
+export async function checkAuthors(
+  parsed,
+  {
+    lookup = dblpHits,
+    pause = (ms) =>
+      new Promise((r) => {
+        setTimeout(r, ms);
+      }),
+  } = {},
+) {
   const findings = [];
   const skipped = []; // legitimately not applicable
   const unchecked = []; // we FAILED to check — must never be reported as a pass
+  const matched = []; // compared against the published record, and equal
+  const entries = parsed.filter((e) => e.title && e.author);
 
   for (const e of parsed.filter((x) => x.unparsed)) {
     skipped.push({
@@ -377,7 +385,7 @@ async function main() {
     let hits = null;
     for (let attempt = 0; attempt < 3 && hits === null; attempt++) {
       try {
-        hits = await dblpHits(e.title.replace(/[{}]/g, ""));
+        hits = await lookup(e.title.replace(/[{}]/g, ""));
       } catch (err) {
         const last = attempt === 2;
         if (last)
@@ -385,10 +393,7 @@ async function main() {
             key: e.key,
             why: `DBLP lookup failed: ${err.message}`,
           });
-        else
-          await new Promise((r) => {
-            setTimeout(r, 1500 * (attempt + 1));
-          });
+        else await pause(1500 * (attempt + 1));
       }
     }
     if (hits === null) continue;
@@ -408,7 +413,9 @@ async function main() {
     const ours = surnames(e.author);
     const theirs = surnames(rec.authors.join(" and "));
     const d = compare(ours, theirs);
-    if (d.missing.length || d.extra.length || d.orderDiffers) {
+    if (!(d.missing.length || d.extra.length || d.orderDiffers))
+      matched.push(e.key);
+    else {
       findings.push({
         key: e.key,
         venue: `${rec.venue} ${rec.year}`.trim(),
@@ -417,12 +424,27 @@ async function main() {
         ...d,
       });
     }
-    // A braced body rather than a concise arrow — see `no-promise-executor-return` (2026-08-28).
-    await new Promise((r) => {
-      setTimeout(r, 900);
-    }); // DBLP asks for gentle clients; 350 ms drew 429s
+    await pause(900); // DBLP asks for gentle clients; 350 ms drew 429s
   }
 
+  return { findings, skipped, unchecked, matched };
+}
+
+function die(msg) {
+  console.error(`bib-authors: ${msg}`);
+  process.exit(2);
+}
+
+async function main() {
+  const args = process.argv.slice(2).filter((a) => a !== "--json");
+  const asJson = process.argv.includes("--json");
+  if (!args[0])
+    die("usage: bib-authors.mjs <paper-dir|file.bib|file.tex> [--json]");
+
+  const { text, file, markdown } = bibTextFrom(args[0]);
+  const parsed = markdown ? parseMarkdownRefs(text) : parseBib(text);
+  const entries = parsed.filter((e) => e.title && e.author);
+  const { findings, skipped, unchecked } = await checkAuthors(parsed);
   if (asJson) {
     console.log(
       JSON.stringify(