paperlint 10.4.0 → 10.4.1

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)",
   );

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

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "vitest";
-import { cpSync } from "node:fs";
+import { cpSync, readFileSync } from "node:fs";
 import { layRecord, recordedTree } from "../../test/recorded-fixture.ts";
 import { runNode, useTempDir, writeTree } from "../../test/support.ts";
 
@@ -62,6 +62,16 @@ const TREE = {
   "commented/paper.tex": tex(
     `Prose here.\n% \\caption{Commented ${LONG_CAPTION_SENTENCE}.}\n\\begin{verbatim}\n\\caption{Quoted ${LONG_CAPTION_SENTENCE}.}\n\\end{verbatim}\n\\begin{figure}\\caption{Real ${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
   ),
+  // The caption command with an optional argument, and with a space before its brace.
+  "optarg/paper.tex": tex(
+    `Prose here. \\begin{figure}\\caption[Short]{${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
+  ),
+  "spaced/paper.tex": tex(
+    `Prose here. \\begin{figure}\\caption {${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
+  ),
+  "negated/paper.tex": tex(
+    "It is not fast. It is not small. It is not red. Nothing here is plain.",
+  ),
   "ends-on-marks/paper.tex": tex(
     "The method holds on every input~\\cite{knuth}. The proof is given in full (Section~\\ref{proof}). The result is new.",
   ),
@@ -83,6 +93,9 @@ const READ: Readonly<Record<string, readonly string[]>> = {
   inline: ["paper.tex", "sec/results.tex"],
   commented: ["paper.tex"],
   "ends-on-marks": ["paper.tex"],
+  negated: ["paper.tex"],
+  optarg: ["paper.tex"],
+  spaced: ["paper.tex"],
   empty: ["paper.tex"],
 };
 writeTree(
@@ -182,6 +195,23 @@ test("--flags-only: an over-long caption flags and exits 1", () => {
   expect(r.stderr).toMatchSnapshot();
 });
 
+test("--flags-only: a metric over its threshold (not a caption) is a finding too, and the report flags the same line", () => {
+  const file = join(root, "negated", "paper.tex");
+  const only = runNode(SCRIPT, ["--flags-only", file]);
+  const report = runNode(SCRIPT, [file]);
+  // Guards: the mode promised "print nothing on a clean paper, any output means a finding" and
+  // looked only at captions; the metrics the report FLAGs are findings of the same kind.
+  assert.deepEqual(
+    { status: only.status, stdout: only.stdout },
+    { status: 1, stdout: "" },
+  );
+  expect(only.stderr).toMatchSnapshot();
+  assert.match(
+    report.stdout,
+    /^FLAG sentences whose main claim is a negation: 75%$/m,
+  );
+});
+
 test("--flags-only: a paper with no figures directory is clean, exit 0 and silent", () => {
   assert.deepEqual(
     runNode(SCRIPT, ["--flags-only", join(root, "clean", "paper.tex")]),
@@ -248,17 +278,13 @@ test("🔴 --flags-only reads the captions of the paper.tex and of the files it
       stdout: r.stdout,
       flagged: r.stderr
         .split("\n")
-        .filter((l) => l.startsWith("   "))
+        .filter((l) => l.startsWith("      > "))
         .map((l) => l.split(":")[0]),
     },
     {
       status: 1,
       stdout: "",
-      flagged: [
-        "   paper.tex",
-        "   sec/results.tex",
-        "   run prose-lint.mjs on the file without --flags-only for the sentences",
-      ],
+      flagged: ["      > paper.tex", "      > sec/results.tex"],
     },
   );
 });
@@ -274,8 +300,14 @@ test("--flags-only on a rendered page reads the captions in figures/*.tex beside
     join(root, "rendered", "page.txt"),
   ]);
   assert.deepEqual(
-    { status: r.status, first: r.stderr.split("\n")[1]?.split(":")[0] },
-    { status: 1, first: "   figures/f.tex" },
+    {
+      status: r.status,
+      first: r.stderr
+        .split("\n")
+        .find((l) => l.startsWith("      > "))
+        ?.split(":")[0],
+    },
+    { status: 1, first: "      > figures/f.tex" },
   );
   // …and a page with no figures/ beside it has no caption to flag.
   assert.deepEqual(runNode(SCRIPT, ["--flags-only", join(root, "page.txt")]), {
@@ -296,9 +328,86 @@ test("🔴 a caption commented out or quoted in verbatim is not measured; a real
       status: r.status,
       findings: r.stderr
         .split("\n")
-        .filter((l) => l.startsWith("   paper.tex:"))
+        .filter((l) => l.startsWith("      > paper.tex:"))
         .map((l) => /— "(\w+)/.exec(l)?.[1]),
     },
     { status: 1, findings: ["Real"] },
   );
 });
+
+/** The `prose-lint.mjs` invocations SKILL.md documents (Step 6), their arguments with `<paper-dir>` filled in. */
+const documentedInvocations = (paperDir: string): readonly string[][] =>
+  readFileSync(join(dirname(SCRIPT), "SKILL.md"), "utf8")
+    .split("\n")
+    .flatMap((line) => {
+      const m =
+        /node \$\{CLAUDE_SKILL_DIR\}\/prose-lint\.mjs ([^#]+?)\s*(#|$)/.exec(
+          line,
+        );
+      return m?.[1] === undefined
+        ? []
+        : [m[1].replaceAll("<paper-dir>", paperDir).split(/\s+/)];
+    });
+
+test("🔴 the invocation SKILL.md documents reports an over-long caption, with no flag the skill does not name", () => {
+  const documented = documentedInvocations(join(root, "p"));
+  // Guards: the report is the documented way to run the checks (Step 6), and captions were
+  // measured only under an undocumented flag — an over-long caption produced no finding.
+  const report = documented.find((a) => !a.includes("--headings"));
+  assert.ok(report !== undefined, "SKILL.md documents a report invocation");
+  const r = runNode(SCRIPT, report);
+  assert.deepEqual(
+    {
+      status: r.status,
+      flagged: r.stdout
+        .split("\n")
+        .filter(
+          (l) => l.startsWith("FLAG figure captions") || l.includes("caption"),
+        ),
+    },
+    {
+      status: 0,
+      flagged: [
+        "FLAG 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",
+      ],
+    },
+  );
+});
+
+test("the report says a paper whose captions are within the limits is clean on that line", () => {
+  const r = runNode(SCRIPT, [join(root, "clean", "paper.tex")]);
+  // Guards: the line is printed on a clean paper too, so its absence is never read as a pass.
+  assert.match(r.stdout, /^ok {3}figure captions over the limit: 0$/m);
+});
+
+test("🔴 a caption with an optional argument, or a space before its brace, is measured", () => {
+  const found = (dir: string) => {
+    const r = runNode(SCRIPT, [join(root, dir, "paper.tex")]);
+    return [
+      r.status,
+      /^FLAG figure captions over the limit: (\d+)$/m.exec(r.stdout)?.[1],
+    ];
+  };
+  // Guards: the scan matched `\caption{` only, so `\caption[Short]{…}` and `\caption {…}` were never
+  // read and the report printed "ok ... 0" for a long caption.
+  expect([found("optarg"), found("spaced")]).toEqual([
+    [0, "1"],
+    [0, "1"],
+  ]);
+});
+
+test("🔴 the caption of the package's own p1 fixture, which has an optional argument, is reported", () => {
+  const p1 = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "fixtures",
+    "paper-sources",
+    "p1",
+    "paper.tex",
+  );
+  const r = runNode(SCRIPT, ["--flags-only", p1]);
+  assert.match(r.stderr, /— "Optional-arg caption this sentence/);
+});

package/src/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- vigiles:sha256:f51051aae2ef09f8 compiled from src/CLAUDE.md.spec.ts -->
+<!-- vigiles:sha256:599c83e36edde981 compiled from src/CLAUDE.md.spec.ts -->
 
 # CLAUDE.md
 
@@ -21,12 +21,15 @@ test — a parser for banal's JSON is pure and is still banal's.
 
 | element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
 | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `domain`  | `src/domain/`          | values and decisions in the paper's vocabulary                                                                                                                     | `domain`; `ts-essentials`, `node:path`, `node:crypto`                                                                   |
-| `port`    | `src/ports/`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | `domain`, `port`; the same three externals                                                                              |
-| `app`     | `src/*.ts`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | `domain`, `port`, `app`, the package's `.mjs`; Node's `util`/`url`/`module`                                             |
+| `domain`  | `src/domain/`          | values and decisions in the paper's vocabulary                                                                                                                     | `domain`; any package or Node built-in that is no tool package (`TOOL_PACKAGES`) and no effect |
+| `port`    | `src/ports/`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | `domain`, `port`; the same as the domain                                                                                   |
+| `app`     | `src/*.ts`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | `domain`, `port`, `app`, the package's `.mjs`; the same externals as the domain                                             |
 | `adapter` | `src/adapters/<tool>/` | everything that knows `<tool>` exists, pure parsers included; used through its `index.ts`                                                                          | `domain`, `port`, its own folder, its tool's packages, the package's `.mjs`. **Never** `app`, **never** another adapter |
 | `root`    | `src/cli.ts`           | reads `process.*`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
 
+A package that exists because of one external tool goes in `TOOL_PACKAGES` (`eslint.config.mjs`), in the same PR that
+adds its adapter; a pure utility library (`remeda`, `zod`, `ts-essentials`) needs nothing, and effects are axis B's.
+
 Folders are ELEMENTS of `eslint-plugin-boundaries`, single files are CATEGORIES (`root`, `app`,
 `test`, `io`): v7 matches element patterns as folders. Everyone — tests included — reaches an
 adapter through its `index.ts`; the files inside one adapter import each other freely.

package/src/CLAUDE.md.spec.ts

@@ -18,12 +18,15 @@ test — a parser for banal's JSON is pure and is still banal's.
 
 | element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
 | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; \`ts-essentials\`, \`node:path\`, \`node:crypto\`                                                                   |
-| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same three externals                                                                              |
-| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; Node's \`util\`/\`url\`/\`module\`                                             |
+| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; any package or Node built-in that is no tool package (\`TOOL_PACKAGES\`) and no effect |
+| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same as the domain                                                                                   |
+| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; the same externals as the domain                                             |
 | \`adapter\` | \`src/adapters/<tool>/\` | everything that knows \`<tool>\` exists, pure parsers included; used through its \`index.ts\`                                                                          | \`domain\`, \`port\`, its own folder, its tool's packages, the package's \`.mjs\`. **Never** \`app\`, **never** another adapter |
 | \`root\`    | \`src/cli.ts\`           | reads \`process.*\`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
 
+A package that exists because of one external tool goes in \`TOOL_PACKAGES\` (\`eslint.config.mjs\`), in the same PR that
+adds its adapter; a pure utility library (\`remeda\`, \`zod\`, \`ts-essentials\`) needs nothing, and effects are axis B's.
+
 Folders are ELEMENTS of \`eslint-plugin-boundaries\`, single files are CATEGORIES (\`root\`, \`app\`,
 \`test\`, \`io\`): v7 matches element patterns as folders. Everyone — tests included — reaches an
 adapter through its \`index.ts\`; the files inside one adapter import each other freely.

package/src/adapters/latex/captions.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The captions of a LaTeX source (`captionsOf`) on real parses: the mandatory argument of `\caption`,
+ * whatever optional argument, star or space precedes it, and none that a reader of the PDF never sees.
+ */
+import { describe, expect, it } from "vitest";
+import { captionsOf, parseLatex } from "./index.ts";
+
+const captions = (src: string): readonly string[] =>
+  captionsOf(parseLatex(src));
+
+describe("captionsOf", () => {
+  it("the text of a caption: formatting kept as words, whitespace collapsed", () => {
+    expect(
+      captions(
+        "\\begin{figure}\\caption{\\textbf{Big.}  Some   words.}\\end{figure}",
+      ),
+    ).toEqual(["Big. Some words."]);
+  });
+
+  it("with an optional argument, a star, or a space before the brace", () => {
+    // Guards: a scan for `\caption{` read none of these.
+    expect(
+      captions(
+        "\\caption[Short]{With option.} \\caption*{Starred.} \\caption {Spaced.}\n\\caption\n  {Next line.}",
+      ),
+    ).toEqual(["With option.", "Starred.", "Spaced.", "Next line."]);
+  });
+
+  it("in order, in the files' text as given; a caption with no words is left out", () => {
+    expect(
+      captions(
+        "\\caption{One.}\\caption{}\\caption{\\centering}\\caption{Two.}",
+      ),
+    ).toEqual(["One.", "Two."]);
+  });
+
+  it("not one that is commented out, in verbatim, or in a macro's definition", () => {
+    const src = [
+      "% \\caption{Commented.}",
+      "\\begin{verbatim}\\caption{Quoted.}\\end{verbatim}",
+      "\\newcommand{\\fig}{\\caption{Defined.}}",
+      "\\caption{Real.}",
+    ].join("\n");
+    expect(captions(src)).toEqual(["Real."]);
+  });
+});
+
+describe("captionsOf — what a reader sees", () => {
+  it("a formula counts as one word and an escaped character is itself", () => {
+    // Guards: dropping them made a caption of 54 words one of 40 and let it pass.
+    expect(
+      captions(
+        "\\caption{Cut by 65\\% of $20\\%$ and Welch $p$; \\textbf{bold} \\& more.}",
+      ),
+    ).toEqual(["Cut by 65% of math and Welch math; bold & more."]);
+  });
+});