paperlint 3.1.1 → 3.1.3

package/docs/prior-art/citation-checkers.md

@@ -0,0 +1,174 @@
+# Verifying a bibliography against reality — is this solved?
+
+**Question this file answers:** could `paperlint`'s "does every `.bib` entry name a real work, with the
+right authors" check depend on an existing, maintained package instead of shelling out to Crossref /
+Semantic Scholar / arXiv / DBLP itself?
+
+**Verdict: no dependable dependency exists, but two API-level facts we were not using would cut our
+own runtime by roughly 5–8×.** Depend on nothing; keep the in-repo checker; add Semantic Scholar's
+`/paper/batch`, OpenAlex's `|`-joined `filter=doi:`, and the Crossref polite pool's raised concurrency.
+Everything found in the "verify existence + author list against a real record" niche is either (a) a
+research prototype released alongside one paper, (b) a solo weekend project pushed in the last few
+months with single-digit-to-low-hundred commits and no PyPI/npm listing, or (c) a Zotero/LaTeX tool
+that solves an adjacent problem (parsing, key generation, unused-entry detection) and does not touch
+external databases at all. None ship a bulk/batch mode faster than calling the same three-to-five
+free APIs ourselves would already be, and every one of them is Python — none is an npm package, so
+"depend on it" would mean shelling out to a Python subprocess from a Node 22 tool. That includes
+`rebiber` itself: this file corrects our earlier read of it (below) — the maintained line is GitHub
+1.4, not the 2021 PyPI 1.1.3 our toolchain currently installs — but even 1.4 doesn't clear the bar,
+because its bundled venue data is ML/NLP/CV/IR only.
+
+---
+
+## Comparison table
+
+Checked 2026-09-27, via GitHub READMEs/WebFetch summaries unless marked otherwise. Star/commit counts
+and "last activity" are as reported by the fetch, not independently re-verified against the live repo
+— treat anything below as **[B]** (read a secondary description) rather than **[A]** (read the
+primary source myself), except where a direct quote is given.
+
+| tool                                                                | verifies                                                                                                                                                                                                                                                           | online/offline                                                                                                                              | install                                                                                                                                                       | license                           | maintenance signal                                                                                                                                     | batch/bulk                                                                                                                                                                               | verdict                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **rebiber 1.4** (yuchenlin, GitHub HEAD — **not** the PyPI package) | rewrites entry to DBLP/ACL-anthology record (existence + authors + venue, by _replacing_ the entry); `--dry-run --report` now previews without rewriting, `-s True` keeps short venue names, `--live-lookup` falls back to a live DBLP search on a local-data miss | offline-first against a bundled, **monthly-refreshed** local DBLP/anthology snapshot; only `--live-lookup` goes to the network              | **GitHub only, and its own README says so**: _"Install from GitHub only. We do not publish or support PyPI (`pip install rebiber` is a 2021 1.1.3 release)."_ | not stated in the fetched excerpt | active — 1.4 migrates to `bibtexparser 2`, raises the Python floor to 3.10                                                                             | one bib file per run; the local-snapshot design makes that run fast regardless                                                                                                           | **narrower than it looks, not simply rejected** — see the callout right below the table                                                                                                                                                                    |
+| **hallucite** (se-uhd)                                              | title + authors primarily, DOI/venue/year via 5 DBs (offline DBLP mirror first, then CrossRef/DOI/arXiv/OpenAlex/S2); LLM only for human-in-the-loop triage of what's left unresolved                                                                              | **offline-first**: local DBLP mirror built from Dagstuhl monthly snapshot (~3.8 GB, ~5 min build), only escalates to the network for misses | `mise install` + `mise run fetch-dblp-dump` + `mise run build-dblp`; ships as a Claude Code / Codex CLI plugin, not a pip/npm package                         | not stated in README              | 83 commits, active CI, no version tag seen                                                                                                             | offline pass over the whole PDF's refs is effectively bulk (SQLite lookups); network fallback is per-entry                                                                               | closest in spirit to our DBLP pass — the offline-mirror idea is real and reusable _as an idea_, but it's a Python-only agent-skill bundle, not an importable package, and license is unstated                                                              |
+| **clibib** (from arXiv:2604.03159)                                  | deterministic **identifier resolution** — given a DOI/arXiv-id/ISBN/PMID it returns exactly one record via the Zotero Translation Server (falls back to CrossRef on an empty `/search`); title match via token-Jaccard ≥0.3                                        | online                                                                                                                                      | PyPI, MIT, "≈230 lines of Python, 2 runtime deps (`requests`, `python-dotenv`)"                                                                               | MIT                               | released alongside a Sept-2026 arXiv paper; no independent release history yet                                                                         | not documented as batched — one identifier per call                                                                                                                                      | narrower than what we need: it fixes/retrieves a record given a _known-good_ id, not "does this claimed entry match a real one" — a retrieval tool, not a verifier                                                                                         |
+| **bibverify** (Hylouis233)                                          | DOI/PMID/PMCID/arXiv + title/authors/year/venue/pages across **9 providers** (Crossref, OpenAlex, S2, PubMed, Europe PMC, CORE, DBLP, arXiv, bioRxiv)                                                                                                              | online, with an **expiring SQLite cache of successful responses only** (TTL 168h default)                                                   | `pip`, `uv tool install`, Docker; npm wrapper (`npx @hylouis233/bibverify`) "planned v0.4.0", not shipped                                                     | MIT                               | v0.3.0, 51 commits, 100 stars, CI across OS/Python matrix — the most conventionally "maintained"-looking of the group                                  | shared connection pool + retry/backoff/`Retry-After`, `delay_between_requests` (default 0.5s); README's own benchmark is explicitly disclaimed as "not a complete scientific evaluation" | the best-engineered of the bunch, but pre-1.0, single-maintainer, npm channel not live yet                                                                                                                                                                 |
+| **citeproof** (xiehuanyi)                                           | existence + author/year/venue/DOI/arXiv-id match across Crossref, DBLP, S2, OpenAlex, arXiv; verdicts `verified / metadata_mismatch / inconclusive / likely_hallucinated`                                                                                          | online only                                                                                                                                 | `pip install git+…`, not on PyPI                                                                                                                              | MIT                               | **4 commits visible** — early/inactive                                                                                                                 | `--workers` flag (default 3); README benchmarks 1 worker ≈47s vs 3 workers ≈4s for its test set, and warns raising workers past API throughput does nothing                              | too new/thin to trust; but its own worker benchmark independently confirms our finding that concurrency, not CPU, is the lever                                                                                                                             |
+| **reference-validator** (bet-lab)                                   | DOI vs Crossref, arXiv detection, "dual validation" flagging local-vs-API conflicts; also touches DBLP/PubMed/Zenodo/DataCite/OpenAlex                                                                                                                             | online                                                                                                                                      | `uv tool install git+…`                                                                                                                                       | Apache-2.0                        | 60 commits, no date surfaced                                                                                                                           | `--workers` (default 10), `--delay` (default 1.0s)                                                                                                                                       | same shape as the others: solo project, git-only install                                                                                                                                                                                                   |
+| **Bibtex-Verifier** (Ritesh778 / merfanian forks)                   | Crossref + OpenAlex + Semantic Scholar; web-app framing ("catch errors & hallucinated references")                                                                                                                                                                 | online                                                                                                                                      | web app / local Flask-style app, not a library                                                                                                                | not confirmed                     | multiple parallel forks (Ritesh778, merfanian, Slowist-Lee) — a sign of "everyone reinvents this small thing," not of one canonical maintained project | not documented                                                                                                                                                                           | a UI tool for a human pasting one `.bib`, wrong shape for a CI dependency                                                                                                                                                                                  |
+| **VeriBib** (Ferry-Li)                                              | cross-references against **Google Scholar** to catch fabrications                                                                                                                                                                                                  | online, scrapes Google Scholar                                                                                                              | GitHub only                                                                                                                                                   | not confirmed                     | not confirmed                                                                                                                                          | not documented                                                                                                                                                                           | Google Scholar has no public API and scraping it is a ban-prone, unstable foundation — worse than what we have                                                                                                                                             |
+| **Better BibTeX** (Zotero plugin)                                   | _nothing external_ — it generates stable citation keys and exports formats from a Zotero library the user already curated                                                                                                                                          | offline (operates on your own library)                                                                                                      | Zotero plugin                                                                                                                                                 | AGPL-3.0                          | mature, years of releases, widely used                                                                                                                 | n/a                                                                                                                                                                                      | **not a verifier at all** — it assumes your Zotero entry is already correct and just keeps the citation key stable across edits. Wrong tool for this problem, included because it's the obvious "isn't this solved by reference-manager software" question |
+| **checkcites** (CTAN/LuaTeX)                                        | unused/undefined references between `.bib` and `.aux`/`.bcf` — a **local consistency** check, no external database at all                                                                                                                                          | offline                                                                                                                                     | TeX Live (bundled)                                                                                                                                            | mature CTAN package               | stable, part of TeX Live                                                                                                                               | n/a                                                                                                                                                                                      | answers a different question ("did I cite everything I defined"), not "is this a real paper"                                                                                                                                                               |
+| **GPTZero / Paperpile "citation checker"**                          | existence + hallucination flagging, marketed at authors/reviewers after the NeurIPS-2025 incident (GPTZero found 53/4,841 accepted papers with fabricated cites)                                                                                                   | online, hosted SaaS                                                                                                                         | web upload only, no API/CLI for automation                                                                                                                    | proprietary                       | commercial product, actively marketed                                                                                                                  | unknown, not exposed for programmatic bulk use                                                                                                                                           | not integrable into a CLI linter at all — no API surface to call from Node                                                                                                                                                                                 |
+
+### 🔴 Correction to our own prior verdict on rebiber — and a live bug it exposes
+
+Our original rejection of rebiber (setuptools-broken install, DBLP-snapshot miss, forced rewrite to
+long booktitles) was measured against **PyPI `rebiber` 1.1.3, released 2021-09-08**. That is not the
+tool's current state, and — checked while writing this file — **it is not even the artifact rebiber's
+own maintainer wants installed.** Its README says outright:
+
+> Install from GitHub only. We do not publish or support PyPI (`pip install rebiber` is a 2021 1.1.3
+> release).
+
+`paperlint`'s toolchain currently pins `rebiber>=1.1.3` and installs it **from PyPI** — meaning it is
+running exactly the release the upstream maintainer disowns, five point-releases and a bibtexparser
+major-version migration behind. Filed as **paperlint#114**.
+
+GitHub HEAD (1.4) fixes two of our three original complaints in principle: `--dry-run --report` can
+preview matches without rewriting the entry (no forced long booktitle unless asked for), and
+`-s True` keeps short venue abbreviations; `--live-lookup` adds a live-DBLP fallback for the
+local-snapshot-miss case that burned us before. It does **not** fix the shape of the underlying
+problem for us: its bundled venue data is **ML/NLP/CV/IR only** — no CCS, USENIX Security, S&P/Oakland,
+ICSE, or FSE — so any reference to a security or software-engineering venue falls straight through to
+`--live-lookup` (a live, unbatched DBLP query, the exact bottleneck this file is about) or is left
+unmatched. **Verdict on rebiber specifically: worth re-pointing our toolchain at GitHub 1.4 instead of
+the disowned PyPI 1.1.3 regardless (that's a straight bug-fix, tracked in #114), but not worth adopting
+as the existence/author checker itself** — its offline-snapshot idea is sound (same shape as
+hallucite's, below), its venue coverage is not ours, and it still rewrites rather than reports unless
+`--dry-run` is remembered on every invocation.
+
+## What "solved" would require, and why nothing here clears the bar
+
+A dependency worth taking has to be (1) **on a registry** (npm ideally, or a PyPI package with a clean
+wheel — not `pip install git+…`), (2) **maintained** past a single paper's release, (3) **licensed**
+clearly, and (4) **faster or no slower** than calling the free APIs directly. Every project above fails
+at least one of these:
+
+- **rebiber, citeproof, clibib, reference-validator, bibverify's Python line** — git-only or PyPI-only
+  install, none published to npm. A Node 22 linter would be shelling out to a Python venv it has to
+  provision itself — the same failure class that sank `rebiber` (its `bibtexparser` wheel breaking on
+  modern `setuptools`), just relocated to a different Python package.
+- **hallucite** is the one idea genuinely worth stealing rather than depending on: an **offline DBLP
+  mirror**, rebuilt monthly from the Dagstuhl CC0 dump (`dblp.xml.gz`, updated on every DBLP rebuild —
+  <https://dblp.org/faq/1474679.html>), turns "one DBLP query per reference, rate-limited" into "one
+  3.8 GB SQLite build, then instant local lookups." That is a real fix for the exact bottleneck named
+  in our own script's docstring ("DBLP rate limits at >1 req/s"). It is not something to `npm install`;
+  it is a pattern (`fetch dump → build local index → query locally → escalate misses`) our own script
+  could adopt without taking hallucite as a dependency.
+- **Everything web-UI-shaped** (Bibtex-Verifier forks, GPTZero, Paperpile) has no CLI/API a build step
+  can call.
+- **Better BibTeX and checkcites** are not verifiers against reality at all — they were checked because
+  "doesn't Zotero/LaTeX already solve this" is the natural next question, and the honest answer is no:
+  BBT trusts whatever is already in your Zotero library, and checkcites only compares your `.bib`
+  against your own `.tex`, never against an external database.
+- **No maintained project publishes a batch/bulk verification API of its own.** The closest thing —
+  citeproof's and reference-validator's `--workers` flags — is just client-side concurrency against the
+  _same_ public APIs we already call, with no batching at the HTTP level. Their own numbers (citeproof:
+  1 worker ≈47s → 3 workers ≈4s on its test set, extra workers "no faster") independently confirm what
+  our own 3.5–7 min runtime already suggests: **the bottleneck is round trips, not our per-request
+  logic**, which points straight at the API-level fixes below rather than at swapping tools.
+
+## API-level speedups we are not using, ranked by expected gain
+
+1. **Semantic Scholar `/graph/v1/paper/batch`** — up to **500 mixed identifiers (DOI/arXiv/PMID/…) in
+   one POST**, replacing up to 500 of our per-entry calls with one round trip
+   (<https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/operation/post_graph_get_papers>).
+   For a 27-reference file this alone turns Semantic Scholar's contribution from ~27 sequential
+   requests into 1. **Highest expected gain of the three**, because it removes an entire per-entry
+   network round-trip rather than just widening its allowed rate.
+
+2. **DBLP: switch from live per-entry queries to an offline mirror**, the hallucite pattern above.
+   DBLP's live API has no published numeric rate limit — the FAQ only asks callers to "tone down"
+   scripts and offers a self-hosted SPARQL/dump route for anyone needing volume
+   (<https://dblp.org/faq/Am+I+allowed+to+crawl+the+dblp+website.html>) — which is exactly the
+   unpredictability our docstring already blames for the 3.5–7 min runtime ("DBLP rate limits at >1
+   req/s, timeouts, retries"). A monthly dump (`https://dblp.org/xml/release/`, or the Dagstuhl-hosted
+   snapshot) turns every DBLP author-sequence comparison into a local SQLite lookup. **Second-highest
+   gain** because it's specifically the part our own docstring names as the slow one, but it costs a
+   ~3.8 GB local artifact and a monthly refresh job — a real added complexity, not free.
+
+3. **OpenAlex: `filter=doi:<doi1>|<doi2>|…`**, joining **up to 50–100 DOIs per call** with `|` (OR)
+   inside one `filter=` parameter (confirmed by OpenAlex's own blog post,
+   <https://blog.openalex.org/fetch-multiple-dois-in-one-openalex-api-request/>, and its help docs).
+   For a paper with ~27 references this collapses OpenAlex's entire contribution into 1 request instead
+   of up to 27. Ranked third only because our current script does not query OpenAlex at all today per
+   the task description (Crossref + S2 + arXiv + DBLP) — so this is a net-new win, not a replacement of
+   an existing slow path, and adding a fourth provider is itself a small scope increase to weigh.
+
+4. **Crossref: send `mailto=` for the polite pool, and prefer `/works/{doi}` (single-record) over
+   `/works?query=` (list) lookups.** Crossref's Dec-2025 rate-limit revision documents the public pool
+   at 5 req/s (single-record) / 1 req/s (list) with concurrency 1, versus the polite pool at **10 req/s
+   / 3 req/s with concurrency 3** (<https://www.crossref.org/blog/announcing-changes-to-rest-api-rate-limits/>).
+   Our script already sends `mailto` (see its docstring: "THE ADDRESS IS THE CONSUMER'S, NOT OURS"), so
+   this is confirmation the polite pool is already in effect, not a new lever — but the single-record
+   vs. list distinction is: a citation with a known DOI should hit `/works/{doi}` (5–10 req/s) rather
+   than the title-search `/works?query.bibliographic=` (1–3 req/s) fallback path, and it's worth
+   auditing which of our 27 references fall through to the slower list endpoint today.
+
+Combined, (1)+(3) should remove most of the _count_ of round trips for entries that carry a DOI or
+arXiv id (the common case), and (2) removes the specific bottleneck our own docstring names for
+authors-vs-venue checks. None of these require a new dependency — they are call-shape changes to the
+same four APIs the script already knows how to speak to (plus adding OpenAlex, which it does not
+currently query).
+
+---
+
+## Status
+
+Written 2026-09-27 from WebSearch/WebFetch passes over GitHub READMEs, arXiv:2604.03159, and the
+Crossref/OpenAlex/Semantic Scholar/DBLP official docs — no tool below was cloned and run locally, so
+every non-quoted maintenance/star claim is **[B]**, and the "closest to solved" claim (hallucite) rests
+on its README's self-description, not an independent audit of its DBLP-mirror code.
+
+Sources:
+[rebiber](https://github.com/yuchenlin/rebiber) ·
+[rebiber README (raw, checked for the 1.4 / PyPI-disowned correction)](https://raw.githubusercontent.com/yuchenlin/rebiber/main/README.md) ·
+[hallucite](https://github.com/se-uhd/hallucite) ·
+[BibTeX Citation Hallucinations in Scientific Publishing Agents (arXiv:2604.03159)](https://arxiv.org/abs/2604.03159) ·
+[bibverify](https://github.com/Hylouis233/bibverify) ·
+[citeproof](https://github.com/xiehuanyi/citeproof) ·
+[reference-validator](https://github.com/bet-lab/reference-validator) ·
+[Bibtex-Verifier](https://github.com/merfanian/Bibtex-Verifier) ·
+[VeriBib](https://github.com/Ferry-Li/VeriBib) ·
+[Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/) ·
+[checkcites (CTAN)](https://ctan.org/tex-archive/support/checkcites) ·
+[Paperpile — a new tool to fight hallucinations in preprints](https://paperpile.com/blog/citation-checker-hallucinations/) ·
+[Semantic Scholar Graph API — batch endpoint](https://api.semanticscholar.org/api-docs/graph) ·
+[OpenAlex blog — fetch multiple DOIs in one request](https://blog.openalex.org/fetch-multiple-dois-in-one-openalex-api-request/) ·
+[OpenAlex — Filter docs](https://help.openalex.org/api/filtering/) ·
+[Crossref — Announcing changes to REST API rate limits](https://www.crossref.org/blog/announcing-changes-to-rest-api-rate-limits/) ·
+[Crossref — Access and authentication (polite pool)](https://www.crossref.org/documentation/retrieve-metadata/rest-api/access-and-authentication/) ·
+[DBLP — How can I download the whole dblp dataset?](https://dblp.org/faq/1474679.html) ·
+[DBLP — Am I allowed to crawl the dblp website?](https://dblp.org/faq/Am+I+allowed+to+crawl+the+dblp+website.html) ·
+[Crossref — Public data files and snapshots](https://www.crossref.org/documentation/retrieve-metadata/bulk-downloads/)

package/docs/references.md

@@ -0,0 +1,126 @@
+# The reference check
+
+`paperlint build` checks every entry of a paper's bibliography against the services that know
+about published work, after the PDF is built. `paperlint lint` then reports what the check found,
+offline. This page explains how the check works, the file it keeps in your paper's folder, and
+what happens in CI and without a network.
+
+## What is checked, and where
+
+For each entry in the bibliography (the `filecontents` block inside `paper.tex`, else `refs.bib`):
+
+| question                                                                                                 | asked of                                    |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| does the cited work exist, and does its title match?                                                     | Crossref, OpenAlex, Semantic Scholar, arXiv |
+| does a DOI that no registry knows really not exist?                                                      | doi.org, the DOI authority                  |
+| for an entry that claims a published venue, are the authors the published version's, not the preprint's? | DBLP                                        |
+
+CVE identifiers are not checked by `build`: a bibliography has no CVE field, so none is extracted.
+The verify-citations script checks a `cve` against NVD when it is given citations as JSON (see the
+skill), and that is the only place NVD is asked.
+
+A work that is simply not found is `unresolvable`, never a failure: plenty of real work is not
+indexed. Only a positive disproof fails an entry, for example a DOI that resolves to a different
+paper, or one the DOI authority says does not exist.
+
+The verdicts land in `<paper>/_build/references.json`. `paperlint lint` reads that file and reports:
+
+| rule                 | when                                                              |
+| -------------------- | ----------------------------------------------------------------- |
+| `paper/cite-exists`  | an entry's identifier provably does not resolve to the work cited |
+| `paper/author-list`  | an entry's authors are the preprint's under a published venue     |
+| `paper/refs-fresh`   | the bibliography changed since the build checked it — build again |
+| `paper/refs-checked` | no build has checked the references, or the last one could not    |
+
+The step never fails the build. Without a network the PDF is still built and lint warns that the
+references were not checked.
+
+## `repro/references-cache.json` — commit it
+
+Asking five services about every entry is slow. DBLP asks clients to pause between requests, and a
+slow service is retried. Before this cache existed, a 27-reference paper spent 217 seconds on the
+check, on every build, and a 51-reference paper did not finish inside a 12-minute CI job
+([#107](https://github.com/zernie/paperlint/issues/107)).
+
+So the build keeps every answer it receives in `<paper>/repro/references-cache.json`, and the next
+build asks only what that file cannot answer:
+
+- An unchanged bibliography whose answers are under 30 days old asks nothing and makes no network request at all, not even the check
+  for whether the services can be reached.
+- Adding or editing an entry asks only about that entry. Answers are stored per identifier (DOI,
+  arXiv id, or title), so changing an entry's DOI or title is what makes it be asked again.
+- A request that failed is not an answer and is not stored, so the next build asks it again.
+- "Does not exist" from doi.org is not stored either. A DOI cited before the authority has
+  registered it would otherwise stay "does not exist" in the file forever; it is asked again on each
+  build until the authority confirms it.
+
+## When a service refuses
+
+Free services rate-limit. From a CI runner or a shared network, Semantic Scholar answers `429`,
+DBLP answers an HTML page where JSON was asked, a registry stops answering. The check handles this
+within one build:
+
+- **A service that refuses stops being asked for the rest of the build.** The first request to
+  each service goes alone; once a service refuses (a `429` or `5xx`, HTML instead of JSON, a
+  timeout, no connection), no new request goes to it until the next build, and no retries or pauses
+  are spent on it. A service that refuses from the start costs one request. One that starts refusing
+  later costs at most the requests already in flight at that moment — six, the number of entries
+  checked at once.
+- **The entries it would have answered say so.** An entry no registry confirmed carries
+  `not asked: <service>: <reason>` in its reason. An entry whose authors DBLP could not check is
+  `authors: unchecked`, which `paper/refs-checked` reports and lint never treats as a pass.
+- **Once one registry confirms a work, the others are not asked.** A confirmation settles the
+  verdict, so the remaining registries (and doi.org) could only cost requests.
+- **DBLP's pace** — it asks clients to pause between queries — is kept between queries DBLP
+  actually answered, and not after a cached answer or once DBLP has refused.
+
+Measured 2026-09-27 from a sandboxed runner where Semantic Scholar, OpenAlex and Crossref answered
+`429` and DBLP answered HTML: a 30-reference paper built in 5.6 s cold and 5.4 s warm (the check
+used to take 475 s and 450 s). Its entries were recorded, with the refusals named, and each later
+build fills in more of the cache as the services let it.
+
+**Commit this file.** It sits in `repro/`, beside the paper's other reproduction files, and not in
+`_build/`, which is build output. Committed, it makes CI and every other clone start warm: a CI job
+that builds an unchanged paper spends no time on the check.
+
+It holds what the services answered, each answer with the day it was fetched, and never a verdict.
+The verdicts are worked out again from those answers on every build, so an improvement to the
+checker reaches every paper at once, instead of being frozen behind a stored "passed".
+
+### Refreshing it
+
+An answer is used for 30 days after the date in its `fetched` field; after that the next build asks
+again and re-dates it. This is what lets a work that a service had not indexed yet ("no record")
+be found once it is. An answer that could not be refreshed because the service refused stays, and is
+asked again on the next build. To ask sooner:
+
+- **one entry**: delete its lines from the file (the keys name the service and the identifier, and
+  DBLP answers carry the title they were asked for);
+- **everything**: delete the file.
+
+The next build asks again and writes the new answers.
+
+### A file that does not read
+
+The build refuses a cache file it cannot read (bad JSON, another schema version, a field of the
+wrong type) and says which part is wrong. It does not overwrite the file, and does not run the
+check over half a cache: the references are recorded as not checked, and lint says so. Fix the
+file, or delete it.
+
+## CI
+
+| the paper has                     | a CI build                                                         |
+| --------------------------------- | ------------------------------------------------------------------ |
+| a committed, up-to-date cache     | asks nothing, needs no network for the check                       |
+| a cache missing a few new entries | asks about those entries only                                      |
+| no cache committed                | asks about every entry, every run: commit the file after one build |
+
+A CI run writes new answers into its own checkout, which is thrown away. Build locally and commit
+the file to keep the answers.
+
+## Running a checker by hand
+
+The two checkers are scripts in the `verify-citations` skill and can be run on their own to read
+one verdict in full: `verify-cites.mjs` (existence and title) and `bib-authors.mjs` (authors). Run
+from the command line, `verify-cites.mjs` keeps its own cache in `~/.cache/paperlint/cite-cache.json`
+(`VERIFY_CITES_CACHE` overrides); it never reads or writes the paper's committed cache.

package/docs/testing.md

@@ -0,0 +1,118 @@
+# Testing
+
+The one map of the kinds of test in this repository: what each answers, where it lives, what it
+may touch, and how to run it. The rules that apply to every kind are at the end.
+
+## Which kind do I need?
+
+| you are testing                                                                               | kind            |
+| --------------------------------------------------------------------------------------------- | --------------- |
+| a pure function: a parser, a decision, a formatter                                            | **unit**        |
+| a use case or an adapter that reaches the disk, a process, the network or the clock           | **integration** |
+| what an agent sees or does: a hook's decision, a skill's contract                             | **harness**     |
+| the package as someone else gets it: the tarball installed elsewhere, a real TeX build, a PDF | **e2e**         |
+
+When in doubt between unit and integration: if the function takes a port (`Files`,
+`CheckReferences`, `RunProcess`, …) or calls `fetch`, it is integration.
+
+## Unit — vitest, pure functions
+
+- **Answers:** does this function return the right value for this input?
+- **Lives:** beside the module, `<module>.test.ts` for a `.ts` module, `<module>.test.mjs` for a
+  `.mjs` one (TypeScript has no types to check a JS module against, and `allowJs` was measured to
+  break a dozen existing `@ts-expect-error` imports).
+- **May touch:** nothing. No disk, no network, no process, no clock.
+- **Example:** `src/domain/lookup-cache.test.ts` — the reference cache's parse, serialize and key
+  functions, each refusal compared as a whole value.
+
+## Integration — vitest, with fakes through the ports
+
+- **Answers:** does this use case or adapter do the right thing with the world it talks to?
+- **Lives:** beside the module, named like a unit test.
+- **May touch:** a temp directory (`useTempDir` and `writeTree` in `test/support.mjs`), a child
+  process of this repository's own scripts (`runNode`). Never the real network.
+- **How fakes get in:** through the seams the code already has.
+  - a port the use case takes: `memoryFiles` and `scriptedProcess` in `src/adapters/memory/`, a
+    `CheckReferences` function, a `MeasureGeometry`;
+  - `fetch`, stubbed with `vi.stubGlobal` and routed by URL, which also records every request made;
+  - a clock or a pause, passed in (`referencesChecker({ today })`) or run under `vi.useFakeTimers`.
+- **Example:** `src/adapters/references/index.test.ts` — the reference checker over a fake
+  `fetch`: a cold run stores every answer, a warm run makes no request at all (the recorded list of
+  requests is empty), an edited entry asks only for itself.
+
+## Harness — vigiles, the agent-facing surface only
+
+- **Answers:** what does an agent see or cause? A hook's allow or deny on a given input, what a
+  skill's contract promises.
+- **Lives:** `<surface>.harness.mjs` beside what it tests; it imports `runHook`, `runHarnessTest`
+  or `runEval` from vigiles. Harnesses written before this rule that import none of the three are
+  frozen in `scripts/harness-api.frozen.json`, which only shrinks (`scripts/harness-api.test.ts`,
+  #77). A new test of anything else is a unit or integration test.
+- **Asserts through** `lib/check.mjs`: `const check = createChecker();` then
+  `check(label, cond, detail)`. A failure prints the label and the detail, every call is counted.
+  Do not define a local `check`.
+- **Example:** `hooks/hooks.harness.mjs`.
+- **Skills are tested through vigiles**, not a bespoke runner: a home-grown runner here once printed
+  byte-identical "clean" verdicts for three skills that had never loaded.
+
+## End-to-end — `test/e2e/*.mjs`
+
+- **Answers:** does the package work once it is somewhere else? The tarball installed into another
+  tree, a real `pdflatex` build, the PDF's fonts measured.
+- **May touch:** everything a user's machine has, except the network: a citation service is a
+  counting fake `fetch` even here (`test/e2e/build.mjs`).
+- **What each run proves, and when a change owes one:** [`e2e.md`](e2e.md).
+
+## Running
+
+```bash
+npx vitest run <file or folder>   # unit and integration tests
+npx vigiles test <file>           # one harness
+npm test                          # everything: vitest, then every harness
+npm run coverage                  # the same under c8, failing below the thresholds in .c8rc.json
+npm run test:e2e                  # the end-to-end runs
+npm run check                     # every gate CI runs, and the list of what it does not reproduce
+```
+
+While editing, run the tests you touched, `npx tsc --noEmit`, `npx eslint <files>` and
+`npm run fmt:check`. **Before every push, run `npm run check` and read its exit code** — the
+coverage gate cannot be judged from one file.
+
+⚠️ **Not `vigiles test .`**, and never drop `--min=1` from `npm test`. Measured 2026-09-11:
+
+| form                   | what happens                                                                | exit  |
+| ---------------------- | --------------------------------------------------------------------------- | ----- |
+| `vigiles test .`       | `.` is read as a FILE — `ERR_UNSUPPORTED_DIR_IMPORT`, uncaught, runner dies | **0** |
+| `vigiles test`         | `No **/*.harness.{mjs,cjs,js,mts,cts,ts} files found.`                      | **0** |
+| `vigiles test --min=1` | names the empty match and fails                                             | **1** |
+
+`--min=1` is the only thing between "every test passed" and "no test ran". vitest exits 1 when no
+file matches, and it transpiles without type-checking, so `npm run check` runs
+`tsc -p tsconfig.test.json` as its own gate.
+
+## Rules for every kind
+
+1. **Red first.** Run a new test on the code before the change and watch it fail at its own
+   assertion. A test that has only ever been green is indistinguishable from one that cannot fail.
+   Never add a file that patches source to prove a test can fail.
+2. **Assert the whole value** — `assert.deepEqual`, `expect(x).toEqual(…)` on the entire result,
+   not a substring or one field. A substring passes on output that is wrong everywhere else. The
+   exception is prose whose wording is not the subject; say so in a comment.
+3. **Test what the code does, never what its source says.** A test that reads a source file (a
+   `.mjs`, a `SKILL.md`, a README, a config) and asserts it contains some text restates the file:
+   rewording turns it red while a real regression stays green. Assert a return value, a run's output
+   and exit code, what landed on disk, the requests made. Text is the subject only when it is the
+   output — a message the program prints, a file it generates.
+4. **No test touches the real network.** A service is a fake `fetch` or a fake port. A test that
+   passes only while Crossref or DBLP answers is not a test of this package.
+5. **Coverage is 100% on lines, statements, functions and branches**, enforced by `npm run coverage`
+   in `npm run check` and CI. c8 reads `NODE_V8_COVERAGE`, so a CLI a test spawns is measured too,
+   unless the test hands the child a fresh `env` without it. vitest runs in the `threads` pool with
+   native `import` (`vitest.config.ts` says why), and the run preloads `test/coverage-src.mjs`, which
+   answers every import of `dist/*.js` with `src/*.ts`, so no module is measured twice.
+6. **No `c8 ignore`, and no guard deleted to reach 100%.** An effect a test cannot reach — a race, a
+   permission root is never denied, a broken install, a 270 MB download — is made injectable and the
+   test passes a fake. A precondition about an argument becomes the signature. A guard whose input can
+   really occur stays, with the test that reaches it. `scripts/coverage-config.test.ts` fails on any
+   coverage-ignore comment and pins `.c8rc.json`'s `exclude` list.
+7. **Say what an assertion guards** in a comment directly above it (`// Guards: …`).

package/docs/toolchain.md

@@ -141,12 +141,14 @@ bash node_modules/paperlint/skills/render-paper/ensure-checkers.sh
 
 ```
    ✅ aclpubcheck
-   ✅ rebiber
+   ✅ rebiber 1.4.0
    ✅ jinja2
    ✅ textidote (/opt/textidote/textidote.jar)
 ✅ all checkers are installed AND run
 ```
 
-It checks that the tools RUN, not that pip exited zero — `aclpubcheck --help` prints usage and
-exits zero on an interpreter where its own dependencies do not import, so "installed" and "works"
-are separate questions here.
+It checks that the tools RUN, not that pip exited zero: aclpubcheck's checker module is imported
+(which pulls in numpy and pandas) and its `python3 -m aclpubcheck` entry point must answer, and
+rebiber must convert a known arXiv entry to its official record. Both come from their GitHub
+sources pinned to a commit — each project's own instruction, and why is recorded in
+`checkers-requirements.txt`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/skills/paper-pipeline/references/artifact-checklist.md

@@ -77,17 +77,17 @@ unreleased. Absence and unfindability fail the same way for a reader.
 
 ## Running `aclpubcheck` locally
 
-The official ACL format checker. `pip install aclpubcheck` fails in some sandboxes (`bibtexparser`
-will not build a wheel). Working recipe:
+The official ACL format checker. Install it, pinned to its GitHub source with rebiber beside it,
+with the package's one command, which then proves it runs:
 
 ```bash
-git clone --depth 1 https://github.com/acl-org/aclpubcheck.git
-pip install pdfplumber PyPDF2 termcolor numpy pylatexenc pybtex unidecode
-mkdir -p stub/rebiber   # rebiber is used ONLY by the optional author-name check
-printf 'def construct_bib_db(*a, **k): return {}\n' > stub/rebiber/__init__.py
-PYTHONPATH=stub python3 -m aclpubcheck --paper_type long <pdf>
+bash node_modules/paperlint/skills/render-paper/ensure-checkers.sh
+python3 -m aclpubcheck --paper_type long <pdf>
 ```
 
+(The recipe that stood here cloned the repository and stubbed rebiber out, because the PyPI release
+did not install. The pinned commit installs, and `ensure-checkers.sh` records why.)
+
 🔴 **Run it on a build WITHOUT line numbers.** Against a `[review]`-mode PDF it reports one margin
 error per line number — about 2,000 of them, all spurious, because it is written for camera-ready
 files. A checker whose output is 100% false positives gets muted the same day.

package/skills/render-paper/checkers-requirements.txt

@@ -8,25 +8,26 @@
 
 jinja2>=3.0                  # {{macro}} substitution in paper_numbers.py
 
-# 🔴 THIS PIN IS LOAD-BEARING, not cosmetic. aclpubcheck pulls in bibtexparser; the 2.x branch is
-# beta (2.0.0b9) with a different API, and the 1.4.x branch's sdist does not build under
-# setuptools 68+. 1.3.0 has a prebuilt WHEEL (bibtexparser-1.3.0-py3-none-any.whl), so `<2`
-# resolves to it and there's nothing to build. Verified 2026-09-04 in a clean venv: install exits
-# 0, `python -m aclpubcheck.formatchecker --help` runs.
-bibtexparser<2
+# bibtexparser is pulled in by rebiber (below), not by aclpubcheck: aclpubcheck's own code never
+# imports it. rebiber 1.4 moved to bibtexparser 2 (`bibtexparser>=2,<3` in its pyproject), and
+# 2.0.1 is a stable release with a prebuilt wheel. The old pin `bibtexparser<2` existed only
+# for rebiber 1.1.3; it would now make the file unsatisfiable, so it is gone.
 
-# 🔴 aclpubcheck IS INSTALLED SEPARATELY, WITH `--no-deps`, AND IT IS DELIBERATELY NOT LISTED HERE.
-# Measured 2026-09-17: it declares `tsv>=1.2,<2.0`, which has NO PREBUILT WHEEL AT ALL
-# (`pip download --only-binary :all: tsv` → "from versions: none"), and its source does not build
+# 🔴 aclpubcheck IS INSTALLED SEPARATELY, WITH `--no-deps`, BY ensure-checkers.sh, AND IT IS
+# DELIBERATELY NOT LISTED HERE (a requirements file cannot say `--no-deps` for one line).
+# It comes from its GitHub source pinned to a commit, not from PyPI: upstream says to install "from
+# the GitHub repository (DIFFERENT from `pypi`)", and PyPI's 0.2.0 is a snapshot of 2022-10-10. The
+# pin is 237bee3 of 2026-09-11, whose own setup.py pins rebiber to the SAME commit as below —
+# measured 2026-09-27: both resolve together, `pip check` names no rebiber conflict.
+# Why `--no-deps`: it still declares `tsv`, which has NO PREBUILT WHEEL AT ALL
+# (`pip download --only-binary :all: tsv` → "from versions: none"), and whose source does not build
 # under a modern setuptools:
 #     AttributeError: install_layout. Did you mean: 'install_platlib'?
-# That one line alone made installing the WHOLE file fail, and that's why the paper went a month
+# That one line alone once made installing the WHOLE file fail, and that's why a paper went a month
 # without an official format check.
-# Verified, not assumed: `tsv` is imported NOWHERE in aclpubcheck's source (grep for
-# `import tsv|from tsv` — 0 hits), and without it
-# `python3 -m aclpubcheck.formatchecker --help` prints usage and exits zero.
-# So what follows is aclpubcheck's OWN dependencies, taken verbatim from the package's metadata,
-# minus tsv. A list, rather than `aclpubcheck` on one line, so the next unrepresentable dependency
+# Verified, not assumed, on the pinned commit: `tsv` is imported NOWHERE in aclpubcheck's source,
+# and neither is `setuptools`, which it also declares.
+# So what follows is aclpubcheck's OWN dependencies, from its setup.py, minus tsv and setuptools. A list, rather than `aclpubcheck` on one line, so the next unrepresentable dependency
 # reads as a missing line rather than an unverified assumption.
 # 🔴 THE UPPER BOUNDS ARE REMOVED, AND THAT IS A MEASUREMENT, NOT CARELESSNESS. The first edition
 # of this list copied aclpubcheck's bounds verbatim — and turned red on CI, where Python is newer:
@@ -48,8 +49,18 @@ pylatexenc>=2.10
 termcolor>=2.0.1
 tqdm>=4.64.1
 
-rebiber>=1.1.3               # an aclpubcheck dependency AND our own tool
+# 🔴 rebiber FROM ITS GITHUB SOURCE, PINNED TO A COMMIT — NOT FROM PyPI. The upstream README says
+# so itself: "Install from GitHub only. We do not publish or support PyPI (`pip install rebiber` is
+# a 2021 1.1.3 release)." The `rebiber>=1.1.3` that stood here installed exactly that 2021 release
+# (#114). The pin is 1.4.0, commit b917e36 of 2026-09-08 ("Support bibtexparser 2 parsing and
+# writing APIs"); upstream has no 1.4 tag, so a commit is the only fixed name.
+# Measured 2026-09-27 in a clean Python 3.11 venv, under this file's `--only-binary :all:`: installs
+# in 36 s (pip builds it from source with hatchling, the one allowed build), `rebiber -v` runs,
+# and a `--dry-run` over a three-entry .bib leaves the file untouched. It carries 409 MB of venue
+# data. aclpubcheck declares `rebiber>=1.1.3,<2`, which 1.4.0 satisfies.
+rebiber @ git+https://github.com/yuchenlin/rebiber@b917e36ec94084a84025eb06781b5aac96d1cedd
 
-# ⚠️ Call ONLY as `python3 -m aclpubcheck.formatchecker`. The package has no __main__.py, and the
-# form `python3 -m aclpubcheck` fails with "cannot be directly executed" — that's exactly how this
-# step once lived its whole life without ever running.
+# Since the pinned commit the package has a `__main__.py`, so `python3 -m aclpubcheck <pdf>` runs
+# the format checker (measured 2026-09-27 on its example PDF: 10 errors, 0 warnings, exit 0). The
+# PyPI 0.2.0 that stood here had none, and `python3 -m aclpubcheck` failed with "cannot be directly
+# executed"; `python3 -m aclpubcheck.formatchecker` works on both.

package/skills/render-paper/ensure-checkers.sh

@@ -27,8 +27,10 @@ echo "== python dependencies =="
 # bibtexparser looked like the guilty one.
 pip install -q --only-binary :all: -r "$HERE/checkers-requirements.txt"
 # The checker itself — WITHOUT its dependencies: they are listed in requirements.txt by name, minus
-# the unbuildable `tsv`, which it does not import. The reason is in the header of requirements.txt.
-pip install -q --no-deps aclpubcheck
+# the unbuildable `tsv`, which it does not import. From its GitHub source at a fixed commit, not
+# PyPI — both reasons are in the header of requirements.txt.
+ACLPUBCHECK="aclpubcheck @ git+https://github.com/acl-org/aclpubcheck@237bee3a554f2d2fcda69cd0cf1edf4168e3d339"
+pip install -q --no-deps "$ACLPUBCHECK"
 
 echo "== TeXtidote (a jar, not a pip package) =="
 if [ -f "$JAR" ]; then
@@ -55,10 +57,24 @@ fail=0
 # "numpy.dtype size changed"). That is, the acceptance check that stood here let through exactly
 # the failure it was written for. `import aclpubcheck.formatchecker` pulls in numpy and pandas on
 # lines 15 and 20 of the checker itself and therefore fails honestly.
+# And the entry point, which the PyPI release did not have: `python3 -m aclpubcheck` must answer.
 python3 -c "import aclpubcheck.formatchecker" >/dev/null 2>&1 \
+  && python3 -m aclpubcheck --help >/dev/null 2>&1 \
   && echo "   ✅ aclpubcheck" || { echo "   ❌ aclpubcheck is installed, but does not run"; fail=1; }
-python3 -c "import rebiber" >/dev/null 2>&1 \
-  && echo "   ✅ rebiber" || { echo "   ❌ rebiber does not import"; fail=1; }
+# 🔴 RUN IT, NOT IMPORT IT. rebiber is used as a command, and an import proves neither the entry
+# point, nor that it loads its bundled venue data, nor that it parses a .bib (bibtexparser 2 since
+# 1.4). So it is given the arXiv entry of a paper its data knows (NeurIPS 2017) with --dry-run
+# (nothing is written) and must report that entry CONVERTED to the official record — measured
+# 2026-09-27 on the pinned commit: `converted (official): 1`, no network.
+reb_tmp="$(mktemp -d)"
+printf '@article{vaswani2017attention,\n  title = {Attention Is All You Need},\n  author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, Lukasz and Polosukhin, Illia},\n  journal = {arXiv preprint arXiv:1706.03762},\n  year = {2017}\n}\n' > "$reb_tmp/in.bib"
+reb_out="$(rebiber -i "$reb_tmp/in.bib" --dry-run 2>&1 || true)"
+if grep -q "converted (official): 1" <<<"$reb_out"; then
+  echo "   ✅ rebiber $(rebiber -v 2>/dev/null)"
+else
+  echo "   ❌ rebiber does not convert a known entry"; fail=1
+fi
+rm -rf "$reb_tmp"
 python3 -c "import jinja2" >/dev/null 2>&1 \
   && echo "   ✅ jinja2" || { echo "   ❌ jinja2 does not import"; fail=1; }
 java -jar "$JAR" --version >/dev/null 2>&1 \