paperlint 10.3.0 → 10.4.1

package/eslint.config.mjs

@@ -212,27 +212,33 @@ export const IO_MODULES = [
   "readline/promises",
 ].flatMap((m) => [m, `node:${m}`]);
 
-/** What the inside may import from outside the repository: types, pure path arithmetic, hashing. */
-export const INSIDE_EXTERNALS = [
-  "ts-essentials",
-  "path",
-  "node:path",
-  "crypto",
-  "node:crypto",
-];
-/** What the flat app files may import besides: Node's pure helpers, measured on the first v7 run. */
-export const APP_EXTERNALS = [
-  ...INSIDE_EXTERNALS,
-  "util",
-  "node:util",
-  "url",
-  "node:url",
-  "module",
-  "node:module",
-];
+/**
+ * The npm packages that exist because of ONE external program or format, from `dependencies` in
+ * package.json: only that tool's adapter (or `src/cli.ts`, the root) imports them; the domain, a
+ * port and the app take a port. A package that exists because of one external tool goes here in the
+ * same PR that adds its adapter. A pure utility library (remeda, zod, ts-essentials) needs nothing:
+ * the inside may import every package and Node built-in that is not listed here and is not an effect
+ * (`IO_MODULES`).
+ */
+export const TOOL_PACKAGES = [
+  "@eslint/markdown", // ESLint's Markdown language
+  "@eslint/plugin-kit",
+  "@retorquere/bibtex-parser", // BibTeX
+  "@unified-latex/unified-latex-types", // LaTeX
+  "@unified-latex/unified-latex-util-parse",
+  "@unified-latex/unified-latex-util-visit",
+  "ajv", // JSON Schema
+  "eslint",
+  "js-yaml", // YAML
+  "markdown-it", // Markdown
+  "mp4box", // MP4
+  "srt-parser-2", // SRT subtitles
+  "typescript", // the compiler API
+  "unpdf", // PDF
+  "vigiles", // the agent harness
+].flatMap((m) => [m, `${m}/**`]);
 
 const ORIGINS = ["external", "core"];
-const modules = (source) => ({ to: { module: { origin: ORIGINS, source } } });
 const elements = (...types) => ({ element: { types: { anyOf: types } } });
 const APP = { file: { categories: "app" } };
 const ROOT = { file: { categories: "root" } };
@@ -337,14 +343,20 @@ export const layerBoundaries = (root) => ({
             allow: { to: elements("js-module") },
           },
           // ── libraries and built-ins (the plugin calls Node built-ins origin "core") ──
+          // Everyone may import any package and built-in …
           {
-            from: elements("domain", "port"),
-            allow: modules(INSIDE_EXTERNALS),
+            from: [elements("domain", "port", "adapter"), APP, ROOT],
+            allow: { to: { module: { origin: ORIGINS } } },
           },
-          { from: APP, allow: modules(APP_EXTERNALS) },
+          // … but the inside — not an adapter, not the root — not a package that exists because of
+          // one external tool (TOOL_PACKAGES). Effects are axis B's, below.
           {
-            from: [elements("adapter"), ROOT],
-            allow: { to: { module: { origin: ORIGINS } } },
+            from: [elements("domain", "port"), APP],
+            disallow: {
+              to: { module: { origin: "external", source: TOOL_PACKAGES } },
+            },
+            message:
+              "{{ dependency.source }} exists because of one external tool or format: only that tool's adapter (src/adapters/<tool>/) and src/cli.ts import it; this file takes a port (src/CLAUDE.md, layers). A new package of that kind is listed in TOOL_PACKAGES in the PR that adds its adapter.",
           },
           // Tests may import anything, fakes included …
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "10.3.0",
+  "version": "10.4.1",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -11,6 +11,7 @@
     "test:e2e": "vitest run --project 'e2e-*'",
     "test:e2e:install": "vitest run --project e2e-install",
     "test:e2e:tex": "vitest run --project e2e-tex",
+    "test:e2e:studies": "vitest run --project e2e-studies",
     "coverage": "NODE_OPTIONS=\"--import=./test/coverage-src.ts $NODE_OPTIONS\" c8 --check-coverage npm test --",
     "lint": "eslint .",
     "check": "node scripts/check.ts",

package/scripts/check.ts

@@ -173,6 +173,12 @@ export const GATES: readonly Gate[] = [
     script: "test:e2e:install",
     vitest: true,
   },
+  {
+    name: "studies e2e — a study decided before its run, in a real git repository",
+    job: "gates",
+    script: "test:e2e:studies",
+    vitest: true,
+  },
   {
     name: "TeX e2e — real TeX Live: paperlint toolchain, a real pdflatex build of every fixture, the real banal",
     job: "build-e2e",

package/skills/camera-ready/SKILL.md

@@ -4,7 +4,7 @@ description: On acceptance, turn the anonymized-for-review paper into the de-ano
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch]
 ---
 
-<!-- vigiles:sha256:1c9ad89e55c3e89a compiled from skills/camera-ready/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:66444fd7ce0e56a0 compiled from skills/camera-ready/SKILL.md.spec.ts -->
 
 # camera-ready — de-anonymize an accepted paper into the final proceedings version
 
@@ -73,6 +73,11 @@ The review artifact was an OSF anonymized view-only link. The camera-ready needs
   or `\doi{}`.
 - Keep the artifact **self-checking** (it still recomputes every headline number and exits non-zero on
   drift) — de-anonymizing it doesn't excuse it from reproducing the paper.
+- **Ship each study's evidence of its mode**: its `plan.json`, its decision file, and
+  `repro/README.md` with the index regenerated (`npx paperlint studies index <paper-dir>`) — each study's mode,
+  decision commit and first output. The public repo keeps the **whole git history** — the order of
+  decision and outputs is read from it (`repro/outputs-before-decision`), and a squashed or shallow
+  copy loses it.
 
 ## 3. Responsible disclosure (security papers — BEFORE public release)
 For the AISec "Safety Theater" paper the studied hooks are named-but-anonymized, and disclosure to the

package/skills/camera-ready/SKILL.md.spec.ts

@@ -88,6 +88,11 @@ The review artifact was an OSF anonymized view-only link. The camera-ready needs
   or \`\\doi{}\`.
 - Keep the artifact **self-checking** (it still recomputes every headline number and exits non-zero on
   drift) — de-anonymizing it doesn't excuse it from reproducing the paper.
+- **Ship each study's evidence of its mode**: its \`plan.json\`, its decision file, and
+  \`repro/README.md\` with the index regenerated (\`npx paperlint studies index <paper-dir>\`) — each study's mode,
+  decision commit and first output. The public repo keeps the **whole git history** — the order of
+  decision and outputs is read from it (\`repro/outputs-before-decision\`), and a squashed or shallow
+  copy loses it.
 
 ## 3. Responsible disclosure (security papers — BEFORE public release)
 For the AISec "Safety Theater" paper the studied hooks are named-but-anonymized, and disclosure to the

package/skills/draft-paper/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the numbers exist and it's time to WRITE the paper — "dr
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:c8d25c21dc01a742 compiled from skills/draft-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:a68aebea0917e4a6 compiled from skills/draft-paper/SKILL.md.spec.ts -->
 
 # draft-paper — prose that survives review and gets cited
 
@@ -33,9 +33,17 @@ number in the body stays in the body**.
    study, and — for security — the explicit threat model (attacker goals/capabilities/knowledge). A
    fuzzy threat model is the fastest reject at a security venue.
 4. **Method** — the reusable core. How the measurement/benchmark is *constructed* so someone else can
-   run it on a different target. This is the part that gets cited; give it the most care.
+   run it on a different target. This is the part that gets cited; give it the most care. **It states
+   each study's mode from the index, never from memory:** run `npx paperlint studies index <paper-dir>`, then read
+   each reported study's `mode`, `decision` and `first output` columns in `repro/README.md` and
+   write one sentence per study — decided before its run, with the decision's commit and date (and
+   its first output's, which came after); an exploratory study named exploratory, with its reason.
+   A study whose `decision` reads `not committed` was not decided before its run: say so.
 5. **Results** — the numbers from `build-benchmark`, each tied to a claim. Report ranges/CIs, not
-   rounded maxes. One figure or table carries the paper — make it legible standalone.
+   rounded maxes. One figure or table carries the paper — make it legible standalone. A number from
+   an exploratory study says "exploratory" where it is reported; "pre-registered" or "decided before"
+   only for a study the index shows as `decide_before_run` with its decision committed before its
+   first output.
 6. **Threats to validity** — construct / internal / external, honestly (see below). This section is a
    trust signal, not a confession.
 7. **Related work** — position against the *nearest* neighbor explicitly ("X measures A; we measure B

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

@@ -39,9 +39,17 @@ number in the body stays in the body**.
    study, and — for security — the explicit threat model (attacker goals/capabilities/knowledge). A
    fuzzy threat model is the fastest reject at a security venue.
 4. **Method** — the reusable core. How the measurement/benchmark is *constructed* so someone else can
-   run it on a different target. This is the part that gets cited; give it the most care.
+   run it on a different target. This is the part that gets cited; give it the most care. **It states
+   each study's mode from the index, never from memory:** run \`npx paperlint studies index <paper-dir>\`, then read
+   each reported study's \`mode\`, \`decision\` and \`first output\` columns in \`repro/README.md\` and
+   write one sentence per study — decided before its run, with the decision's commit and date (and
+   its first output's, which came after); an exploratory study named exploratory, with its reason.
+   A study whose \`decision\` reads \`not committed\` was not decided before its run: say so.
 5. **Results** — the numbers from \`build-benchmark\`, each tied to a claim. Report ranges/CIs, not
-   rounded maxes. One figure or table carries the paper — make it legible standalone.
+   rounded maxes. One figure or table carries the paper — make it legible standalone. A number from
+   an exploratory study says "exploratory" where it is reported; "pre-registered" or "decided before"
+   only for a study the index shows as \`decide_before_run\` with its decision committed before its
+   first output.
 6. **Threats to validity** — construct / internal / external, honestly (see below). This section is a
    trust signal, not a confession.
 7. **Related work** — position against the *nearest* neighbor explicitly ("X measures A; we measure B

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

@@ -4,7 +4,7 @@ description: Grade how a paper reads and fix it sentence by sentence. Use when a
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:1897016b69f3f9b8 compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:2b7193c739a374e6 compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
 
 # grade-paper-writing — grade how the paper READS, then fix it sentence by sentence
 
@@ -223,7 +223,9 @@ is what happened.
    ```
 
    It measures the prose a reader sees — the files the last build read spliced in, no preamble,
-   comments, floats or inline `.bib` — so its rates are the paper's, not the source file's. Run
+   comments, floats or inline `.bib` — so its rates are the paper's, not the source file's — and, on
+   its own line, the figure captions that float outside that prose, flagging a caption sentence over
+   40 words or a caption over 100. Run
    `npx paperlint build` first: with no current build record it reads `paper.tex` alone and says so. The skill is what must ACT on it.
    Its thresholds are sourced; a FLAG means the text sits above a published human or machine
    baseline, which is a defect with a number attached, not an opinion.

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

@@ -229,7 +229,9 @@ is what happened.
    \`\`\`
 
    It measures the prose a reader sees — the files the last build read spliced in, no preamble,
-   comments, floats or inline \`.bib\` — so its rates are the paper's, not the source file's. Run
+   comments, floats or inline \`.bib\` — so its rates are the paper's, not the source file's — and, on
+   its own line, the figure captions that float outside that prose, flagging a caption sentence over
+   40 words or a caption over 100. Run
    \`npx paperlint build\` first: with no current build record it reads \`paper.tex\` alone and says so. The skill is what must ACT on it.
    Its thresholds are sourced; a FLAG means the text sits above a published human or machine
    baseline, which is a defect with a number attached, not an opinion.

package/skills/grade-paper-writing/__snapshots__/prose-lint.test.ts.snap

@@ -1,10 +1,19 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`--flags-only: a metric over its threshold (not a caption) is a finding too, and the report flags the same line 1`] = `
+"✍️  prose-lint — paper.tex — 1 finding(s):
+   sentences whose main claim is a negation: 75%
+   run prose-lint.mjs on the file without --flags-only for every metric
+"
+`;
+
 exports[`--flags-only: an over-long caption flags and exits 1 1`] = `
 "✍️  prose-lint — paper.tex — 2 finding(s):
-   figures/fig1.tex: caption sentence of 46 words (warn >40) — "Big. word0 word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 wor…"
-   figures/fig1.tex: caption is 106 words (warn >100) — a caption this long is a section under a picture
-   run prose-lint.mjs on the file without --flags-only for the sentences
+   all metadiscourse/1000w  363.6   (Hyland RA baseline 64.9, warn >90)
+   figure captions over the limit: 2
+      > figures/fig1.tex: caption sentence of 46 words (warn >40) — "Big. word0 word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 wor…"
+      > figures/fig1.tex: caption is 106 words (warn >100) — a caption this long is a section under a picture
+   run prose-lint.mjs on the file without --flags-only for every metric
 "
 `;
 
@@ -37,6 +46,7 @@ ok   all metadiscourse/1000w  0   (Hyland RA baseline 64.9, warn >90)
 ok   "rather than"/instead-of/10,000w  0   (warn >25; not epanorthosis, no published baseline)
 ok   sentences ending on a cross-ref/citation/hedge (wasted stress position): 0
 ok   sentences whose main claim is a negation: 0%
+ok   figure captions over the limit: 0
      topic positions (whose story is this?): "a rendered page." | "it was hyphenated across a" | "next page text here."
 
 (thresholds and their sources are in THRESHOLDS at the top of this file)
@@ -64,6 +74,9 @@ FLAG sentences ending on a cross-ref/citation/hedge (wasted stress position): 12
        > …], and that results from a handful of runs need honest statistics [1].
        > …g code [1], and models that memorize answers instead of reasoning [1].
 ok   sentences whose main claim is a negation: 37%
+FLAG figure captions over the limit: 2
+       > paper.tex: caption sentence of 52 words (warn >40) — "Two things make it different from how efficiency tools are usually measured: the tool is installed the way a u…"
+       > paper.tex: caption sentence of 44 words (warn >40) — "The advertised 65% is an output-token reduction; because output is only math of the dollar cost, even a perfec…"
      topic positions (whose story is this?): "a fast-growing ecosystem of plugins," | "the most popular single artifact---a" | "we show that such claims," | "efficiency tools are validated on" | "we introduce a reproducible, cost-aware," | "across 140 runs on two" | "output falls far short of" | "the ceiling is also structural:" | "we argue that trustworthy evaluation" | "ai coding agents and their" | "built on the reasoning-and-acting loops" | "assistants of this kind are" | "an unverified performance claim about" | "while the community has invested" | "we focus on the most" | "the flagship example is a" | "naming the commits matters more" | "two separate claims are bundled" | "the first is that the" | "that one has already been" | "the second claim is the" | "nobody had measured it." | "it fails for a reason" | "this paper is about the" | "rq: when a token-efficiency tool" | "the first half is measured," | "our contribution is not that" | "we identify why the headline" | "we build a cost-aware, correctness-gated" | "we measure two widely used" | "output falls far short of" | "the dollar bill does not" | "the broader point is about" | "a modern agent bills tokens" | "a multi-turn agentic session [1]" | "reading the upstream benchmark code" | "the reported number measures something" | "the fix is to measure" | "the compression literature these tools" | "the harness --- the ecosystem" | "we implement the evaluation as" | "figure 1 shows the whole" | "each tool is delivered as" | "a skill that ships as" | "this step is load-bearing: a" | "we use seven self-contained coding" | "the suite deliberately skews short" | "each task is run with" | "the runs date from july" | "the two tools are the" | "for every run we record" | "on a subscription the \`\`bill''" | "we report dollars---the weighting most" | "each task carries a deterministic" | "these are lightweight structural checks" | "a trial where the skill" | "for each task we report" | "we call an effect significant" | "we also note which effects" | "for the bill we report" | "averages taken over a few" | "this protocol is sized to" | "two things are still required" | "the flagship skill (claim 65%)" | "we sign bill changes so" | "for the flagship, the bill" | "either way the answer is" | "the second tool (claim 63%)" | "it is also not significant." | "its one per-task cell that" | "the intervals are wide: at" | "but they exclude anything near" | "whatever room remains is capped" | "correctness." | "both arms passed the correctness" | "a sharper signal hides in" | "this is a short-session effect" | "this is not a quirk" | "both shares below are measured," | "pooled across all tasks and" | "if output is a fraction" | "even a perfect 65% output" | "the advertised 63--75% and the" | "the flagship's other feature trims" | "output is a small fraction" | "we measure cost: latency and" | "we do not claim \`\`these" | "nor do we dispute the" | "our point is that they" | "we label each by its" | "we run five trials per" | "that is itself part of" | "across tasks the flagship's output" | "the honest quantity is therefore" | "our design refutes the advertised" | "what caps those is the" | "a formal equivalence test (tost---a" | "the harness is not toothless," | "at that scale we read" | "we test one model, and" | "anthropic's tiers all share a" | "the ceiling scales linearly with" | "even if output were priced" | "our tasks top out around" | "this cuts in our favor." | "a longer session re-reads a" | "that pushes the ceiling lower," | "one might object that terser" | "but that downstream saving is" | "so it adds a few" | "the compounded ceiling is --," | "the overhead runs the other" | "an always-loaded tool prompt adds" | "that fixed cost amortizes over" | "the durable long-session prediction is" | "an empirical long-session demonstration is" | "every run in the main" | "the harness decides how many" | "a wordier model would raise" | "the ceiling of section 1" | "a pilot on claude haiku" | "nearly double, and still about" | "both runs ship in the" | "a second harness is reachable" | "the flagship now ships wrappers" | "measuring a second harness therefore" | "wrapper list and the rejected" | "we do not study multi-agent" | "we test two tools, and" | "the harness can a/b any" | "the bias runs in our" | "our per-run bill uses the" | "a user can also invalidate" | "(the first two rewrite the" | "that is, they push cost" | "they lower the ceiling and" | "so our clean-caching tasks, if" | "the correctness gate is a" | "so \`\`zero regressions'' bounds gross" | "a stronger gate that runs" | "still, a gate that never" | "without it, a harness would" | "the efficiency-claim failure is a" | "a community norm of cost-aware," | "execution-based, correctness-gated benchmarks such as" | "we keep their correctness-first discipline" | "several lines of work push" | "we take the same stance---price" | "closest to us, [1] argue" | "we turn that lens on" | "a long line of work" | "capability benchmarks show the same" | "we aim the same critique" | "the industry a/b test cited" | "what we add over such" | "the efficiency-tool market runs on" | "these tools trim what the" | "we measured two of the" | "the numbers are not fabricated;" | "the output you are shown" | "trimming the model's replies to" | "we release the measurements with" | "before you install the next" | "the complete harness of section" | "the measurements are released per" | "individual trial rows are not"
 
 (thresholds and their sources are in THRESHOLDS at the top of this file)

package/skills/grade-paper-writing/prose-lint.mjs

@@ -17,17 +17,18 @@
  *
  * A `.txt` is the text of the rendered PDF — the page a reviewer actually reads.
  *
- * The figure captions are measured too (`--flags-only`): every `\caption{}` in `paper.tex` and the
+ * The figure captions are measured too, in the report: every `\caption{}` in `paper.tex` and the
  * files it includes, or, beside a rendered page, in `figures/*.tex`.
  *
- * Advisory: it prints findings; `--flags-only` exits with code 1 if anything was found.
+ * Advisory: the report prints every check and exits 0. `--flags-only` prints the checks the report
+ * marks FLAG, each with the lines under it, and nothing on a clean paper; it exits 1 when there is
+ * one — the form for a hook.
  */
 import { paperProse } from "#src/paper-prose";
 import { paperRecord } from "#src/paper-record";
-import { latexReader } from "#src/adapters/latex/index";
+import { captionsOf, latexReader, parseLatex } from "#src/adapters/latex/index";
 import { nodeFiles } from "#src/adapters/node/index";
 import { sourcesCodec } from "#src/adapters/sources-record/index";
-import { texToMdast } from "#eslint-rules/latex-language";
 
 const THRESHOLDS = {
   metadiscourseTotalPer1000: {
@@ -363,77 +364,116 @@ function figureFiles(pagePath, fs, path) {
 }
 
 /**
- * Every `\caption{…}` of `sources` (`{ file, text }`) a reader sees, measured. The LaTeX
- * language's projection blanks what never typesets — verbatim and code, macro definitions, the
- * preamble — and keeps a caption's argument; it keeps comments too, as `html` nodes of its tree,
- * for the rules that read notes. So a caption is skipped when its argument is blank in the
- * projection or it starts inside a comment: a quoted or commented-out `\caption` is not one.
+ * Every `\caption` of `sources` (`{ file, text }`) a reader sees, measured. The captions come from the
+ * parsed source (`captionsOf`, src/adapters/latex/captions.ts): its optional argument, star and spacing
+ * are the parser's, and a caption that is commented out, in verbatim or in a macro's definition is not one.
  */
 function captions(sources) {
-  const out = [];
-  for (const { file: f, text: s } of sources) {
-    const { root, text: seen } = texToMdast(s);
-    const comments = root.children
-      .filter((n) => n.type === "html")
-      .map((n) => [n.position.start.offset, n.position.end.offset]);
-    for (const m of s.matchAll(/\\caption\{/g)) {
-      let i = m.index + m[0].length,
-        depth = 1,
-        j = i;
-      while (j < s.length && depth) {
-        if (s[j] === "{") depth++;
-        else if (s[j] === "}") depth--;
-        j++;
-      }
-      if (
-        !/\S/.test(seen.slice(i, j - 1)) ||
-        comments.some(([a, b]) => m.index >= a && m.index < b)
-      )
-        continue;
-      const text = s
-        .slice(i, j - 1)
-        .replace(/\\[a-zA-Z]+\s*/g, " ")
-        .replace(/[{}]/g, " ")
-        .replace(/---/g, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-      if (!text) continue;
-      // A non-empty caption splits into at least one sentence.
-      const sents = splitSentences(text);
-      out.push({
-        file: f,
-        words: words(text),
+  return sources.flatMap(({ file, text }) =>
+    captionsOf(parseLatex(text)).map((raw) => {
+      // A dash with no spaces round it joins two words in the count, as it never did here.
+      const caption = raw.replace(/---/g, " ");
+      const sents = splitSentences(caption);
+      return {
+        file,
+        words: words(caption),
         longest: Math.max(...sents.map(words)),
         longestSentence: sents.slice().sort((a, b) => words(b) - words(a))[0],
-      });
-    }
-  }
-  return out;
+      };
+    }),
+  );
+}
+
+/**
+ * The findings on the captions of the file `f`: one line per caption sentence or caption over its
+ * limit. A paper's captions are in its own files — paper.tex and what it includes, wherever a figure
+ * is set; a rendered page has the `.tex` of `figures/` beside it. The report and `--flags-only` both
+ * read them from here.
+ */
+function captionFindings(f, tex, fs, path) {
+  return captions(tex ? tex.files : figureFiles(f, fs, path)).flatMap((c) =>
+    CAPTION_LIMITS.filter(over(c)).map(say(c)),
+  );
+}
+
+/**
+ * The two limits a caption is held to: the `THRESHOLDS` key, what of a caption it is measured on, and
+ * how a finding reads. A caption is over a limit when its measure exceeds the threshold's `warn`.
+ */
+const CAPTION_LIMITS = [
+  {
+    key: "captionSentenceWords",
+    measure: (c) => c.longest,
+    say: (c, warn) =>
+      `${c.file}: caption sentence of ${c.longest} words (warn >${warn}) — "${c.longestSentence.slice(0, 110)}…"`,
+  },
+  {
+    key: "captionWords",
+    measure: (c) => c.words,
+    say: (c, warn) =>
+      `${c.file}: caption is ${c.words} words (warn >${warn}) — a caption this long is a section under a picture`,
+  },
+];
+const over = (c) => (limit) => limit.measure(c) > THRESHOLDS[limit.key].warn;
+const say = (c) => (limit) => limit.say(c, THRESHOLDS[limit.key].warn);
+
+/**
+ * Every line of the report as data, in the order it is printed: `ok` is true (passed), false (a
+ * finding, marked `FLAG`) or null (a figure, no check), `under` the lines that name the offenders.
+ * The report prints all of it; `--flags-only` prints the findings: one list, two renderings.
+ */
+function checks(r, captionLines) {
+  const T = THRESHOLDS;
+  return [
+    {
+      ok: r.metadiscoursePer1000 <= T.metadiscourseTotalPer1000.warn,
+      text: `all metadiscourse/1000w  ${r.metadiscoursePer1000}   (Hyland RA baseline 64.9, warn >${T.metadiscourseTotalPer1000.warn})`,
+      under: [],
+    },
+    {
+      ok: null,
+      text: `nominalisations/1000w    ${r.nominalisationsPer1000}`,
+      under: [],
+    },
+    {
+      ok: r.contrastivePer10k <= T.contrastivePer10k.warn,
+      text: `"rather than"/instead-of/10,000w  ${r.contrastivePer10k}   (warn >${T.contrastivePer10k.warn}; not epanorthosis, no published baseline)`,
+      under: [],
+    },
+    {
+      ok: r.wastedStress.length === 0,
+      text: `sentences ending on a cross-ref/citation/hedge (wasted stress position): ${r.wastedStress.length}`,
+      under: r.wastedStress.map((s) => `…${s.slice(-70)}`),
+    },
+    {
+      ok: r.negatedSentencePct <= T.negatedMainClausePct.warn,
+      text: `sentences whose main claim is a negation: ${r.negatedSentencePct}%`,
+      under: [],
+    },
+    {
+      ok: captionLines.length === 0,
+      text: `figure captions over the limit: ${captionLines.length}`,
+      under: captionLines,
+    },
+    {
+      ok: null,
+      text: `topic positions (whose story is this?): ${r.topics.map((t) => `"${t}"`).join(" | ")}`,
+      under: [],
+    },
+  ];
 }
 
-function report(name, r) {
-  const flag = (ok) => (ok ? "ok  " : "FLAG");
+const MARK = { true: "ok  ", false: "FLAG", null: "    " };
+
+function report(name, r, rows) {
   console.log(`\n=== ${name} — ${r.words} words, ${r.sentences} sentences ===`);
   console.log(
     `sentence lengths ${JSON.stringify(r.sentenceLens)}  mean ${r.meanLen}  sd ${r.sdLen}  CV ${r.cv}`,
   );
-  console.log(
-    `${flag(r.metadiscoursePer1000 <= THRESHOLDS.metadiscourseTotalPer1000.warn)} all metadiscourse/1000w  ${r.metadiscoursePer1000}   (Hyland RA baseline 64.9, warn >${THRESHOLDS.metadiscourseTotalPer1000.warn})`,
-  );
-  console.log(`     nominalisations/1000w    ${r.nominalisationsPer1000}`);
-  console.log(
-    `${flag(r.contrastivePer10k <= THRESHOLDS.contrastivePer10k.warn)} "rather than"/instead-of/10,000w  ${r.contrastivePer10k}   (warn >${THRESHOLDS.contrastivePer10k.warn}; not epanorthosis, no published baseline)`,
-  );
-  console.log(
-    `${flag(r.wastedStress.length === 0)} sentences ending on a cross-ref/citation/hedge (wasted stress position): ${r.wastedStress.length}`,
-  );
-  r.wastedStress.forEach((s) => console.log(`       > …${s.slice(-70)}`));
-  console.log(
-    `${flag(r.negatedSentencePct <= THRESHOLDS.negatedMainClausePct.warn)} sentences whose main claim is a negation: ${r.negatedSentencePct}%`,
-  );
-  console.log(
-    `     topic positions (whose story is this?): ${r.topics.map((t) => `"${t}"`).join(" | ")}`,
-  );
+  rows.forEach(({ ok, text, under }) => {
+    console.log(`${MARK[ok]} ${text}`);
+    under.forEach((l) => console.log(`       > ${l}`));
+  });
 }
 
 const args = process.argv.slice(2);
@@ -474,14 +514,14 @@ function pdfTextOnly(t) {
     .replace(/\f/g, "\n\n");
 }
 
-// 🔴 `--flags-only` and a NON-ZERO EXIT, added 2026-08-05, are what let anything downstream act.
-// Until today this file printed a wall of numbers and always exited 0, and it was wired to no hook
-// at all — it ran only if a human or a skill remembered it existed. Its epanorthosis metric sat at
-// 50.8 per 10,000 words (the LLM baseline is 7.8) through five consecutive writing passes and never
-// once flagged, because it had no threshold. The corpus owner found the tic by eye in a single reading and
-// asked why the tooling had not. It had not because it was measuring, and measuring is not checking
-// — which is, word for word, this paper's own thesis running loose inside its own toolchain.
-const flagsOnly = args.includes("--flags-only");
+// `--flags-only` prints the findings of the report (every line it marks FLAG, with the lines under
+// it) and nothing on a clean paper, and exits 1 when there is one: the form for a hook. The report
+// prints all of `checks` and exits 0.
+const mode = args.includes("--flags-only")
+  ? "flags"
+  : args.includes("--headings")
+    ? "headings"
+    : "report";
 let flagged = 0;
 for (const f of args.filter((a) => !a.startsWith("--"))) {
   const raw = fs.readFileSync(f, "utf8");
@@ -509,33 +549,25 @@ for (const f of args.filter((a) => !a.startsWith("--"))) {
     process.exit(2);
   }
   const r = analyse(text, sentences);
-  if (flagsOnly) {
-    const lines = [];
-    // A paper's captions are in its own files — paper.tex and what it includes, wherever a figure
-    // is set; a rendered page has the `.tex` of `figures/` beside it.
-    for (const c of captions(tex ? tex.files : figureFiles(f, fs, path))) {
-      if (c.longest > THRESHOLDS.captionSentenceWords.warn)
-        lines.push(
-          `   ${c.file}: caption sentence of ${c.longest} words (warn >${THRESHOLDS.captionSentenceWords.warn}) — "${c.longestSentence.slice(0, 110)}…"`,
-        );
-      if (c.words > THRESHOLDS.captionWords.warn)
-        lines.push(
-          `   ${c.file}: caption is ${c.words} words (warn >${THRESHOLDS.captionWords.warn}) — a caption this long is a section under a picture`,
-        );
-    }
-    if (lines.length) {
-      flagged += lines.length;
+  const rows = () => checks(r, captionFindings(f, tex, fs, path));
+  if (mode === "flags") {
+    const found = rows().filter((row) => row.ok === false);
+    if (found.length) {
+      flagged += found.length;
       // The header STATES the count, so a caller need not count output lines — header and footer
       // are not findings.
       console.error(
-        `✍️  prose-lint — ${f.split("/").pop()} — ${lines.length} finding(s):`,
+        `✍️  prose-lint — ${f.split("/").pop()} — ${found.length} finding(s):`,
       );
-      lines.forEach((l) => console.error(l));
+      found.forEach(({ text, under }) => {
+        console.error(`   ${text}`);
+        under.forEach((l) => console.error(`      > ${l}`));
+      });
       console.error(
-        "   run prose-lint.mjs on the file without --flags-only for the sentences",
+        "   run prose-lint.mjs on the file without --flags-only for every metric",
       );
     }
-  } else if (args.includes("--headings")) {
+  } else if (mode === "headings") {
     // The whole-document question, printed as one list. Not a gate: "does this heading name a
     // concrete noun" is judgement and pretending otherwise would be the exact failure this file
     // exists to stop. What was missing is cheaper and was the real cause — nobody had ever seen the
@@ -558,10 +590,10 @@ for (const f of args.filter((a) => !a.startsWith("--"))) {
       'a linter, a configuration, a repository, a rule — not "answers", "kinds", "moves".',
     );
   } else {
-    report(f.split("/").pop(), r);
+    report(f.split("/").pop(), r, rows());
   }
 }
-if (!flagsOnly)
+if (mode !== "flags")
   console.log(
     "\n(thresholds and their sources are in THRESHOLDS at the top of this file)",
   );