paperlint 3.1.3 → 4.0.0

package/skills/tighten-paper/SKILL.md

@@ -1,24 +1,13 @@
 ---
 name: tighten-paper
 description: "Use when a paper \"feels long / bloated / overly complex / hard to read / doesn't deliver its point / the middle drags\" — or after review rounds deposited hedge-mass. The developmental / editorial pass on a DRAFTED paper: what a real human editor thinks reading it cover to cover — the ONE point, does every section earn its place, can it be SKIMMED, is it too long for its contribution, which sections are TMI that belong in the artifact/appendix, does the conclusion pay off the intro's promise. Produces a structural verdict + a concrete cut / fold / merge / reorder plan — NOT sentence fixes. Its verdict is a required INPUT to pc-panel-review and a hard gate in harden-paper. NOT sentence craft or a writing grade (grade-paper-writing), NOT jargon stalls (the persona stall pass), NOT scientific defects (pc-panel-review / paper-adversarial-review). Run it BEFORE those on a bloated draft — no point polishing sentences in a section that should be cut."
-allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Bash(node .claude/skills/paper-pipeline/scripts/announce.mjs:*), Bash(node .claude/skills/paper-pipeline/scripts/ledger.mjs:*)]
+allowed-tools: [Read, Write, Edit, Grep, Glob, Agent]
 ---
 
-<!-- vigiles:sha256:79a018d2fd2bf3e7 compiled from skills/tighten-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:fd00cde33ea4b81c compiled from skills/tighten-paper/SKILL.md.spec.ts -->
 
 # tighten-paper — the developmental edit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-```
-node .claude/skills/paper-pipeline/scripts/announce.mjs tighten-paper <paper-dir>
-```
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Sentence-level passes make a wall of text into readable text. They do **not** tell you the wall shouldn't be there
 at all. This pass is the editor who reads the whole paper once and asks: *is this the right paper, at the right
 length, delivering the right point?* Its deliverable is a **cut/fold/merge/reorder plan and a length verdict**, not
@@ -321,32 +310,6 @@ Produce:
 - **The middle-sag diagnosis** and the fix (consolidate these findings, lead each with its point).
 - **Skim-test failures** (headings/lead-sentences that don't carry the argument).
 
-## Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-```
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record tighten-paper <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record tighten-paper <paper-dir> ABSTAINED <reason> "<one line>"
-```
-
-**FINDING** is the normal row — `<count>` is the number of CUT / FOLD / MERGE / REORDER actions in
-the plan and `<report-path>` is the plan itself. Add `--blocking` when the paper is over its limit
-and the plan cannot get it under.
-**ABSTAINED** — `no-witness`: a cover-to-cover read produced no action at all, which on a real draft
-should be rare. `blocked`: the declined pass of the section above — content is still being added, so
-there was nothing to read whole.
-
-🔴 **This is the check with the documented history of never saying no**: a tightening pass once
-returned KEEP on 80 of 81 sections and still counted as run. It is also one of the three failures
-that deleted `PASS` — the word made "I read it all and nothing moved" indistinguishable from "I did
-not really read it". `status.mjs` reports a check that has never recorded a finding, on the
-mutation-testing principle that a test which kills no mutant is not a test. So an `ABSTAINED
-no-witness` here owes a note saying what was read and why nothing moved.
-
-The mechanical half of this skill files separately, under `tighten-paper/structure` — one check, one
-row. Do not record a `structure.mjs` result here.
-
 ## Compose
 Run this FIRST on a draft that "feels bloated" — before grade-paper-writing / the stall pass / pc-panel, because
 polishing sentences in a section that should be folded to the artifact is wasted work. After the plan is applied,

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

@@ -10,30 +10,10 @@ export default experimental_skill({
   name: "tighten-paper",
   description:
     "Use when a paper \"feels long / bloated / overly complex / hard to read / doesn't deliver its point / the middle drags\" — or after review rounds deposited hedge-mass. The developmental / editorial pass on a DRAFTED paper: what a real human editor thinks reading it cover to cover — the ONE point, does every section earn its place, can it be SKIMMED, is it too long for its contribution, which sections are TMI that belong in the artifact/appendix, does the conclusion pay off the intro's promise. Produces a structural verdict + a concrete cut / fold / merge / reorder plan — NOT sentence fixes. Its verdict is a required INPUT to pc-panel-review and a hard gate in harden-paper. NOT sentence craft or a writing grade (grade-paper-writing), NOT jargon stalls (the persona stall pass), NOT scientific defects (pc-panel-review / paper-adversarial-review). Run it BEFORE those on a bloated draft — no point polishing sentences in a section that should be cut.",
-  tools: [
-    "Read",
-    "Write",
-    "Edit",
-    "Grep",
-    "Glob",
-    "Agent",
-    "Bash(node .claude/skills/paper-pipeline/scripts/announce.mjs:*)",
-    "Bash(node .claude/skills/paper-pipeline/scripts/ledger.mjs:*)",
-  ],
+  tools: ["Read", "Write", "Edit", "Grep", "Glob", "Agent"],
   body: `
 # tighten-paper — the developmental edit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/announce.mjs tighten-paper <paper-dir>
-\`\`\`
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Sentence-level passes make a wall of text into readable text. They do **not** tell you the wall shouldn't be there
 at all. This pass is the editor who reads the whole paper once and asks: *is this the right paper, at the right
 length, delivering the right point?* Its deliverable is a **cut/fold/merge/reorder plan and a length verdict**, not
@@ -336,32 +316,6 @@ Produce:
 - **The middle-sag diagnosis** and the fix (consolidate these findings, lead each with its point).
 - **Skim-test failures** (headings/lead-sentences that don't carry the argument).
 
-## Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record tighten-paper <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record tighten-paper <paper-dir> ABSTAINED <reason> "<one line>"
-\`\`\`
-
-**FINDING** is the normal row — \`<count>\` is the number of CUT / FOLD / MERGE / REORDER actions in
-the plan and \`<report-path>\` is the plan itself. Add \`--blocking\` when the paper is over its limit
-and the plan cannot get it under.
-**ABSTAINED** — \`no-witness\`: a cover-to-cover read produced no action at all, which on a real draft
-should be rare. \`blocked\`: the declined pass of the section above — content is still being added, so
-there was nothing to read whole.
-
-🔴 **This is the check with the documented history of never saying no**: a tightening pass once
-returned KEEP on 80 of 81 sections and still counted as run. It is also one of the three failures
-that deleted \`PASS\` — the word made "I read it all and nothing moved" indistinguishable from "I did
-not really read it". \`status.mjs\` reports a check that has never recorded a finding, on the
-mutation-testing principle that a test which kills no mutant is not a test. So an \`ABSTAINED
-no-witness\` here owes a note saying what was read and why nothing moved.
-
-The mechanical half of this skill files separately, under \`tighten-paper/structure\` — one check, one
-row. Do not record a \`structure.mjs\` result here.
-
 ## Compose
 Run this FIRST on a draft that "feels bloated" — before grade-paper-writing / the stall pass / pc-panel, because
 polishing sentences in a section that should be folded to the artifact is wasted work. After the plan is applied,

package/skills/tighten-paper/structure.mjs

@@ -22,7 +22,7 @@
  *
  * ── 2026-08-26, EVENING: BOTH NAMED CONSUMERS ARE CLOSED, AND A THIRD ONE TURNED UP ────────
  *
- * The paragraph above named two callers and said that until they are converted, the ledger writes
+ * The paragraph above named two callers and said that until they are converted, they read
  * "no findings" BY SILENCE. That was true and measured: on `the reference paper/paper.md`
  * `--flags-only` printed 0 lines, while the same bytes through ESLint give **6 findings**
  * (`subsection-size` ×2 · `section-lead` · `free-section-size` ×2 · `block-ungraded`).
@@ -31,11 +31,6 @@
  *       stood next to it, running the same rules over the same glob; a measurement showed a
  *       byte-identical list of files. The full justification is in the comment where the removed
  *       step used to be.
- *   `run-mechanical.mjs`, the `tighten-paper/structure` line → CONVERTED to ESLint
- *       (`read: 'eslint'`, filtered by the rules from `eslint-rules/paper-structure.mjs`). Not
- *       deleted: ESLint writes nothing into the ledger, and the ledger is the only place where the
- *       fact "somebody looked at this paper's structure on these bytes" is stored with a hash of the
- *       input.
  *
  * 🔴 A THIRD CALLER THE BANNER DID NOT KNOW ABOUT: `.githooks/pre-commit`. It printed nothing and
  * swallowed the exit code through `|| true`. The lesson is exactly the one already recorded in
@@ -97,7 +92,7 @@ import {
   stripFences,
   requireMarkdown,
   stripFrontmatter,
-} from "../../lib/markdown.mjs";
+} from "#lib/markdown";
 
 // Markup is parsed with a PARSER (`CLAUDE.md`, 2026-08-11). We fail rather than degrade: without a
 // parser not one section would be found in the paper, `--flags-only` would return 0 findings and
@@ -294,11 +289,9 @@ const freeTotal = freeSections.reduce((a, r) => a + r.words, 0);
 // edit, and there is nothing to settle the question of which one is right.
 
 if (flagsOnly) {
-  // Silence and exit code 0 — ALWAYS. Deliberately not one line on stdout/stderr:
-  // `run-mechanical.mjs` reads this mode as `read: 'flags'`, that is, "non-empty output = a
-  // finding", and a pointer saying "the checks have moved" would turn into a permanent false finding
-  // in the ledger. The limitation of this mode is named in the banner at the top; it is cured by
-  // converting both callers to `npx eslint`, not here.
+  // Silence and exit code 0 — ALWAYS. Deliberately not one line on stdout/stderr: a caller that
+  // reads "non-empty output = a finding" would turn a pointer saying "the checks have moved" into a
+  // permanent false finding. The limitation of this mode is named in the banner at the top.
   process.exit(0);
 }
 

package/skills/tighten-paper/{structure.test.mjs → structure.test.ts}

@@ -6,11 +6,12 @@ import assert from "node:assert/strict";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../../test/support.mjs";
+import { runNode, useTempDir, writeTree } from "../../test/support.ts";
 
 const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "structure.mjs");
 const root = useTempDir("structure-");
-const words = (n) => Array.from({ length: n }, (_, i) => `w${i}`).join(" ");
+const words = (n: number) =>
+  Array.from({ length: n }, (_, i) => `w${String(i)}`).join(" ");
 
 writeTree(root, {
   // Every row shape: a sub-section before any section, carries notes with a score and a verdict,
@@ -69,7 +70,7 @@ ${words(30)}
   "body-only.md": `## 1 Intro\n${words(8)}\n\n## 2 Rest\n${words(4)}\n\n## 3 Empty\n`,
 });
 
-const run = (...args) => {
+const run = (...args: string[]) => {
   const r = runNode(
     SCRIPT,
     args.map((a) => (a.startsWith("--") ? a : join(root, a))),

package/skills/verify-citations/SKILL.md

@@ -4,21 +4,10 @@ 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:3a7e10662d0084c4 compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:fe3634eb63db5c0d compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-```
-node .claude/skills/paper-pipeline/scripts/announce.mjs verify-citations <paper-dir>
-```
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Reviewers reject on a single fabricated or wrong citation — it reads as either sloppiness or a
 hallucinated bibliography, and either one is fatal. And they reject on "this was already done by ___" if
 your delta over the nearest prior work isn't spelled out. This skill closes both holes before submit.
@@ -30,8 +19,7 @@ bibliography changes, including the edit you make on the last day. Scorecard row
 `<paper-dir>/PIPELINE-STATUS.md`; see the CONTINUOUS section of `paper-pipeline`.
 
 - **A pass dated before the current text is STALE, and stale reads as green.** The date in the `cites`
-  row is compared against the paper's own mtime, and `../paper-pipeline/scripts/pipeline-check.mjs` reports the
-  mismatch — because a `☑` from three days and forty edits ago is worse than a `☐`: it looks closed.
+  row is compared against the paper's own mtime — because a `☑` from three days and forty edits ago is worse than a `☐`: it looks closed.
 - **"We checked last cycle" does not count.** Say it plainly, because it is the exact sentence that
   ships a fabricated cite: a review round adds text, added text adds citations, and the run that
   cleared the bibliography never saw them.
@@ -294,30 +282,6 @@ therefore being checked for the first time.
 fails CI if any line or branch of them goes unexercised. Run `npx vitest run src/references.test.ts`
 after any edit to the rules.
 
-## 6. Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-```
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> ABSTAINED <reason> "<one line>"
-```
-
-**FINDING** — `<count>` is the number of cites still `% VERIFY` or `unresolvable`; `<report-path>`
-lists them. Add `--blocking` for a cite an authoritative source disproves, or a missing delta
-sentence; either is a submit blocker.
-**ABSTAINED** — `no-witness`: every cite resolved with correct metadata and the delta sentence is in
-the prose. `crashed`: the registries were unreachable, so nothing was verified — which is emphatically
-not the same as everything checking out, and under the old vocabulary both came back `PASS`.
-
-🔴 **There is no PASS.** `no-witness` here means every cite the paper makes was looked up and none
-of them came back wrong. It does not mean the bibliography is complete: this check cannot see a work
-that should have been cited and is not. That gap belongs to `map-prior-work`, and no row here covers it.
-
-Because this check is CONTINUOUS, it writes a row per run and never a final one. That is the point:
-the ledger compares the row against the paper's current bytes, so a pass that predates the last three
-`\cite` additions reports as STALE-PAPER instead of reading as green.
-
 ## Rules
 - **Re-run on every `\cite` added or moved.** A `cites` row older than the paper's text is a stale pass,
   not a green one — "we checked last cycle" is not a verification.

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

@@ -24,17 +24,6 @@ export default experimental_skill({
   body: `
 # verify-citations — every cite real, the delta explicit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/announce.mjs verify-citations <paper-dir>
-\`\`\`
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Reviewers reject on a single fabricated or wrong citation — it reads as either sloppiness or a
 hallucinated bibliography, and either one is fatal. And they reject on "this was already done by ___" if
 your delta over the nearest prior work isn't spelled out. This skill closes both holes before submit.
@@ -46,8 +35,7 @@ bibliography changes, including the edit you make on the last day. Scorecard row
 \`<paper-dir>/PIPELINE-STATUS.md\`; see the CONTINUOUS section of \`paper-pipeline\`.
 
 - **A pass dated before the current text is STALE, and stale reads as green.** The date in the \`cites\`
-  row is compared against the paper's own mtime, and \`../paper-pipeline/scripts/pipeline-check.mjs\` reports the
-  mismatch — because a \`☑\` from three days and forty edits ago is worse than a \`☐\`: it looks closed.
+  row is compared against the paper's own mtime — because a \`☑\` from three days and forty edits ago is worse than a \`☐\`: it looks closed.
 - **"We checked last cycle" does not count.** Say it plainly, because it is the exact sentence that
   ships a fabricated cite: a review round adds text, added text adds citations, and the run that
   cleared the bibliography never saw them.
@@ -310,30 +298,6 @@ therefore being checked for the first time.
 fails CI if any line or branch of them goes unexercised. Run \`npx vitest run src/references.test.ts\`
 after any edit to the rules.
 
-## 6. Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> ABSTAINED <reason> "<one line>"
-\`\`\`
-
-**FINDING** — \`<count>\` is the number of cites still \`% VERIFY\` or \`unresolvable\`; \`<report-path>\`
-lists them. Add \`--blocking\` for a cite an authoritative source disproves, or a missing delta
-sentence; either is a submit blocker.
-**ABSTAINED** — \`no-witness\`: every cite resolved with correct metadata and the delta sentence is in
-the prose. \`crashed\`: the registries were unreachable, so nothing was verified — which is emphatically
-not the same as everything checking out, and under the old vocabulary both came back \`PASS\`.
-
-🔴 **There is no PASS.** \`no-witness\` here means every cite the paper makes was looked up and none
-of them came back wrong. It does not mean the bibliography is complete: this check cannot see a work
-that should have been cited and is not. That gap belongs to \`map-prior-work\`, and no row here covers it.
-
-Because this check is CONTINUOUS, it writes a row per run and never a final one. That is the point:
-the ledger compares the row against the paper's current bytes, so a pass that predates the last three
-\`\\cite\` additions reports as STALE-PAPER instead of reading as green.
-
 ## Rules
 - **Re-run on every \`\\cite\` added or moved.** A \`cites\` row older than the paper's text is a stale pass,
   not a green one — "we checked last cycle" is not a verification.

package/skills/verify-citations/scripts/{bib-authors.cli.test.mjs → bib-authors.cli.test.ts}

@@ -9,7 +9,12 @@ import { join } from "node:path";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+import {
+  parseJson,
+  runNode,
+  useTempDir,
+  writeTree,
+} from "../../../test/support.ts";
 
 const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "bib-authors.mjs");
 const root = useTempDir("bib-authors-cli-");
@@ -19,7 +24,12 @@ const DBLP_ANSWERS = {
   "Swapped Order": [["Ada Lovelace", "Alan Turing"]],
   "All Good": [["Ada Lovelace"]],
 };
-const bib = (key, author, title, venue = "booktitle = {Proc. X}") =>
+const bib = (
+  key: string,
+  author: string,
+  title: string,
+  venue = "booktitle = {Proc. X}",
+) =>
   `@inproceedings{${key}, author = {${author}}, title = {${title}}, ${venue}}\n`;
 
 writeTree(root, {
@@ -54,7 +64,7 @@ writeTree(root, {
   "empty/.keep": "",
 });
 
-const run = (...args) => {
+const run = (...args: string[]) => {
   const r = runNode(SCRIPT, args, {
     nodeArgs: ["--import", join(root, "dblp.mjs")],
   });
@@ -126,7 +136,7 @@ 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");
   assert.deepEqual(
-    { status: r.status, stderr: r.stderr, report: JSON.parse(r.stdout) },
+    { status: r.status, stderr: r.stderr, report: parseJson(r.stdout) },
     {
       status: 0,
       stderr:

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

@@ -0,0 +1,63 @@
+// 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 "". */
+export interface BibEntry {
+  readonly type: string;
+  readonly key: string;
+  readonly author: string;
+  readonly title: string;
+  readonly booktitle: string;
+  readonly journal: string;
+}
+
+export declare function parseBib(text: string): BibEntry[];
+
+/** True when the author list ends in `and others` — there is nothing complete to compare. */
+export declare const truncated: (authorField: string) => boolean;
+
+/** True when the entry names a venue that is not a preprint server. */
+export declare function claimsPublished(
+  entry: Pick<BibEntry, "booktitle" | "journal">,
+): boolean;
+
+/** One DBLP search hit, as `dblpHits` normalises it. */
+export interface DblpHit {
+  readonly venue: string;
+  readonly year: string;
+  readonly type: string;
+  readonly title: string;
+  readonly authors: readonly string[];
+}
+
+/** DBLP's hits for a title; throws on a failed request (with `retryable` for a 429). */
+export declare function dblpHits(title: string): Promise<DblpHit[]>;
+
+export interface AuthorFinding {
+  readonly key: string;
+  readonly venue: string;
+  readonly missing: readonly string[];
+  readonly extra: readonly string[];
+  readonly orderDiffers: boolean;
+}
+
+export interface KeyWhy {
+  readonly key: string;
+  readonly why: string;
+}
+
+/** The buckets of one comparison; an entry in none of them was a preprint entry. */
+export interface AuthorBuckets {
+  readonly findings: readonly AuthorFinding[];
+  readonly skipped: readonly KeyWhy[];
+  readonly unchecked: readonly KeyWhy[];
+  readonly matched: readonly string[];
+}
+
+export declare function checkAuthors(
+  parsed: readonly BibEntry[],
+  options?: {
+    readonly lookup?: (title: string) => Promise<readonly DblpHit[]>;
+    readonly pause?: (ms: number) => Promise<void> | void;
+  },
+): Promise<AuthorBuckets>;

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

@@ -45,10 +45,7 @@
  */
 import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join, extname } from "node:path";
-import {
-  headings as mdHeadings,
-  requireMarkdown,
-} from "../../../lib/markdown.mjs";
+import { headings as mdHeadings, requireMarkdown } from "#lib/markdown";
 import { isMain } from "../../paper-pipeline/scripts/consumer.mjs";
 
 const DBLP = "https://dblp.org/search/publ/api";

package/skills/verify-citations/scripts/{verify-cites.cli.test.mjs → verify-cites.cli.test.ts}

@@ -9,7 +9,23 @@ import { readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+import { z } from "zod";
+import {
+  runNode,
+  useTempDir,
+  writeTree,
+  type ScriptResult,
+} from "../../../test/support.ts";
+
+/** The verdicts `verify-cites --json`… prints: one per citation, with the fields these tests read. */
+const Verdicts = z.array(
+  z.looseObject({
+    id: z.unknown().optional(),
+    verdict: z.unknown().optional(),
+    flags: z.array(z.unknown()).nullish(),
+  }),
+);
+const Cache = z.record(z.string(), z.unknown());
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const root = useTempDir("verify-cites-cli-");
@@ -48,12 +64,17 @@ writeTree(root, {
     "  return new Response(null, { status: 404 });\n};\n",
   "consumer/paperlint.json": JSON.stringify({ contactEmail: "me@example.org" }),
 });
-const offline = (args, opts = {}) =>
-  runNode(SCRIPT, [...args, "--offline"], { env, ...opts });
-const parsed = (r) => ({ ...r, stdout: JSON.parse(r.stdout) });
-const SUMMARY_PASS = (n, t, u, flagged) =>
-  `\nverify-cites: ${n} citation(s) — ${t} true, 0 false (fabrication), ${u} unresolvable` +
-  (flagged ? `, ${flagged} with hygiene flag(s)` : "") +
+const offline = (
+  args: readonly string[],
+  opts: { input?: string } = {},
+): ScriptResult => runNode(SCRIPT, [...args, "--offline"], { env, ...opts });
+const parsed = (r: ScriptResult) => ({
+  ...r,
+  stdout: Verdicts.parse(JSON.parse(r.stdout)),
+});
+const SUMMARY_PASS = (n: number, t: number, u: number, flagged: number) =>
+  `\nverify-cites: ${String(n)} citation(s) — ${String(t)} true, 0 false (fabrication), ${String(u)} unresolvable` +
+  (flagged ? `, ${String(flagged)} with hygiene flag(s)` : "") +
   "\nPASS — no fabrication (unresolvable is advisory)\n";
 
 test("-h is --help", () => {
@@ -118,9 +139,11 @@ test("online, a DOI the authority does not know is FALSE: FAIL, exit 1, and the
   assert.deepEqual(
     {
       status: r.status,
-      verdicts: JSON.parse(r.stdout).map((x) => x.verdict),
+      verdicts: Verdicts.parse(JSON.parse(r.stdout)).map((x) => x.verdict),
       tail: r.stderr.trim().split("\n").pop(),
-      cached: Object.keys(JSON.parse(readFileSync(CACHE, "utf8"))).sort(),
+      cached: Object.keys(
+        Cache.parse(JSON.parse(readFileSync(CACHE, "utf8"))),
+      ).sort(),
     },
     {
       status: 1,

package/skills/verify-citations/scripts/verify-cites.d.mts

@@ -0,0 +1,58 @@
+// Types for verify-cites.mjs, for the exports `src/` imports — the same arrangement as
+// `skills/paper-pipeline/scripts/consumer.d.mts`. Without this file TypeScript sees an untyped
+// module, and every import needed a `@ts-expect-error` plus a cast at each call.
+//
+// Only what `src/` imports is declared. The `.mjs` is not typechecked, so a declaration nobody
+// compiles against would drift without anyone noticing.
+
+/** One entry as `parseBib` returns it: the BibTeX key as `id`, plus the fields it recognised. */
+export interface Citation {
+  readonly id: string;
+  readonly [field: string]: unknown;
+}
+
+/** Every entry of a BibTeX text, `@comment`/`@string`/`@preamble` skipped. */
+export declare function parseBib(text: string): Citation[];
+
+/** The title reduced to what identifies it: case, braces and punctuation removed. */
+export declare function titleIdentity(title: string): string;
+
+/** Answers the resolvers gave, keyed by request — shared between citations and runs. */
+export type ResponseCache = Record<string, unknown>;
+
+/** Would verifying `citation` make a request, given `cache`? Answers from the cache only. */
+export declare function wouldAsk(
+  citation: Citation,
+  cache: ResponseCache,
+): Promise<boolean>;
+
+/** One run's memory of which service refused: a refusing service is not asked again. */
+export interface Breaker {
+  call<T>(
+    service: string,
+    attempt: () => Promise<
+      { ok: true; value: T } | { ok: false; reason: string }
+    >,
+  ): Promise<{ ok: true; value: T } | { ok: false; reason: string }>;
+}
+
+export declare function createBreaker(): Breaker;
+
+/** The verdict on one citation. */
+export interface CiteVerdict {
+  readonly id: string;
+  readonly verdict: "true" | "false" | "unresolvable";
+  readonly reason?: string;
+  /** "<service>: <reason>" for each question a refusing service did not answer. */
+  readonly refused?: readonly string[];
+}
+
+/** Verify ONE citation live, answering from `cache` first and writing new answers into it. */
+export declare function verifyCitationLive(
+  citation: Citation,
+  options?: {
+    readonly cache?: ResponseCache;
+    readonly offline?: boolean;
+    readonly breaker?: Breaker;
+  },
+): Promise<CiteVerdict>;

package/src/CLAUDE.md

@@ -35,7 +35,7 @@ through the `io` file category in `boundaries/dependencies`; the `process` and `
 carries `// eslint-disable-next-line <rule> -- legacy <I/O|layer>, moves behind a port in #76`.
 Unused directives are errors (`reportUnusedDisableDirectives`), so a fixed site must drop its
 comment; the per-file counts are frozen in `scripts/layer-legacy.frozen.json` and checked by
-`scripts/layer-legacy-frozen.mjs` (`npm run check`, CI), which counts ESLint's own
+`scripts/layer-legacy-frozen.ts` (`npm run check`, CI), which counts ESLint's own
 `suppressedMessages` and fails when a file's count grows, a file not in the list carries one, or
 anything under `src/domain/`, `src/ports/` or `src/adapters/` does. A NEW module that needs the
 world is a new `*.io.ts` in the adapter of the program it talks to — never a new directive.

package/src/adapters/banal/failure.ts

@@ -59,9 +59,8 @@ function missing(m: BanalMissing): string {
 
 type Kind = BanalFailure["kind"];
 /** One sentence-writer per variant. A mapped type over `kind`, so a new variant without one is a compile error. */
-type Describers = {
-  readonly [K in Kind]: (f: Extract<BanalFailure, { kind: K }>) => Lines;
-};
+type FailureOf = { readonly [K in Kind]: Extract<BanalFailure, { kind: K }> };
+type Describers = { readonly [K in Kind]: (f: FailureOf[K]) => Lines };
 
 const orNone = (s: string): string => s || "no output";
 
@@ -101,15 +100,15 @@ const DESCRIBE: Describers = {
 };
 
 /**
- * What to tell a person. Most failures are one line; a sha256 mismatch shows both hashes.
- *
- * The one assertion below narrows the table's entry for `f.kind` to a function of `f`: the mapped
- * type already pairs each kind with its own variant, and TypeScript cannot correlate the index with
- * the argument on its own.
+ * The describer for `kind`, applied to its own variant. Generic over the kind, so the table's entry
+ * and the argument are correlated through `FailureOf[K]` and need no assertion (TypeScript#47109).
  */
+const describeKind = <K extends Kind>(kind: K, f: FailureOf[K]): Lines =>
+  DESCRIBE[kind](f);
+
+/** What to tell a person. Most failures are one line; a sha256 mismatch shows both hashes. */
 export function describe(f: BanalFailure): Lines {
-  const write = DESCRIBE[f.kind] as (f: BanalFailure) => Lines;
-  return write(f);
+  return describeKind(f.kind, f);
 }
 
 /** `describe` as one line, for a caller that has a single line to fill. */

package/src/adapters/banal/index.test.ts

@@ -2,12 +2,12 @@
  * `adapters/banal/index.ts` — banal as the two ports the app sees. What `run.test.ts` checks in
  * banal's own terms is checked here as the domain receives it: a `Geometry` whose provenance names
  * banal and the rule that found it, a reason that is one line of text, a `Ready` that says what was
- * verified. In-memory ports throughout; the real banal is `test/e2e/banal.mjs`.
+ * verified. In-memory ports throughout; the real banal is `test/e2e/banal.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
 import { whyNoGeometry } from "../../domain/geometry.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { ProcessExit } from "../../ports/process.ts";
 import { sha256Hex } from "../../domain/sha256.ts";
 import {
@@ -21,7 +21,7 @@ import type { Ready } from "../../ports/tool-installer.ts";
 import { banalInstaller, banalMeasurer, parseBanalSettings } from "./index.ts";
 
 const dirs = { home: "/h", tmp: "/t", cwd: "/r" };
-const project = "/r" as AbsolutePath;
+const project = absolutePath("/r");
 const MEASURED =
   '{"papersize":[792,612],"columns":2,"bodyfontsize":9,"pages":[{},{"type":"bib","reffontsize":7}]}';
 
@@ -44,15 +44,12 @@ test("with $BANAL: banal gets the .xml and a quoted $PDFTOHTML, and the geometry
   const { m, run } = measurer({ BANAL: "/own/banal" });
   const g = m.measure([]);
   assert.equal(g.kind, "measured");
-  assert.deepEqual(g.kind === "measured" && g.by, {
+  assert.deepEqual(g.by, {
     tool: "banal",
     path: "/own/banal",
     how: "$BANAL",
   });
-  assert.deepEqual(
-    g.kind === "measured" && [g.geometry.columns, g.geometry.bodyPages],
-    [2, 1],
-  );
+  assert.deepEqual([g.geometry.columns, g.geometry.bodyPages], [2, 1]);
   const c = run.calls[0];
   // Guards: the poppler-free path — banal is handed paperlint's XML, never the PDF.
   assert.match(c?.args.at(-1) ?? "", /\.xml$/);