paperlint 4.0.0 → 4.2.0

package/scripts/check.ts

@@ -34,9 +34,11 @@
  * (no TeX, no network), and the tail names every skip. "I ran check" then means one thing.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { z } from "zod";
 import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -72,11 +74,17 @@ type GateCommand =
       readonly script: string;
       readonly run?: undefined;
       readonly inCi?: RunInCi;
+      /**
+       * The script is a vitest run, so its JSON report says how many tests were SKIPPED: a run
+       * whose exit is 0 and whose report counts a skip is a skip, not a pass.
+       */
+      readonly vitest?: true;
     }
   | {
       readonly run: readonly [string, ...string[]];
       readonly script?: undefined;
       readonly inCi?: undefined;
+      readonly vitest?: undefined;
     };
 
 /**
@@ -160,22 +168,14 @@ export const GATES: readonly Gate[] = [
   {
     name: "install e2e — pack, install under npm and pnpm, run the binary",
     job: "gates",
-    run: ["node", "test/e2e/install.ts"],
+    script: "test:e2e:install",
+    vitest: true,
   },
   {
-    name: "build e2e — a real pdflatex, and the PDF's fonts are measured",
+    name: "TeX e2e — real TeX Live: paperlint toolchain, a real pdflatex build of every fixture, the real banal",
     job: "build-e2e",
-    run: ["node", "test/e2e/build.ts"],
-  },
-  {
-    name: "banal e2e — the real banal on pdf.js-written XML gives banal-on-pdftohtml's numbers",
-    job: "build-e2e",
-    run: ["node", "test/e2e/banal.ts"],
-  },
-  {
-    name: "toolchain e2e — real TeX Live into $PAPERLINT_TEXLIVE_DIR, then a build with only it on PATH",
-    job: "build-e2e",
-    run: ["node", "test/e2e/toolchain.ts"],
+    script: "test:e2e:tex",
+    vitest: true,
   },
 ];
 
@@ -205,18 +205,41 @@ export const NOT_COVERED: Readonly<Record<string, string>> = {
 };
 
 /**
- * Exit 77 means "declared skip" — the same code vigiles' runner uses (`SKIP_EXIT_CODE`). The e2e steps exit 77 when a tool they need is
- * absent and --strict is off. Anything else nonzero is a failure.
+ * vitest's JSON report, as far as the verdict reads it: skipped (`pending`) and `todo` tests.
  *
- * 🔴 A SKIP IS A THIRD OUTCOME. Until the Codex review on #45 the e2e steps exited 0 on a skip,
- * this loop counted that as a pass, and `skipped` below was declared and never filled: a machine
- * without pnpm or TeX printed "all gates passed" for runs that never happened.
+ * 🔴 A SKIP IS A THIRD OUTCOME. Until the Codex review on #45 the e2e runs exited 0 on a skip and
+ * this loop counted that as a pass: a machine without pnpm or TeX printed "all gates passed" for
+ * runs that never happened. The count comes from the runner's own report, not from an exit code
+ * the tests would have to agree on.
  */
-export const SKIP_EXIT: number = 77;
-export function outcome(status: number | null): Outcome {
-  if (status === 0) return "pass";
-  if (status === SKIP_EXIT) return "skip";
-  return "fail";
+const VitestReport = z.looseObject({
+  numPendingTests: z.number().int().nonnegative(),
+  numTodoTests: z.number().int().nonnegative(),
+});
+
+/** How many tests a vitest JSON report says were not run, or null when it is not one. */
+export function skippedIn(report: string | null): number | null {
+  if (report === null) return null;
+  try {
+    const r = VitestReport.safeParse(JSON.parse(report));
+    return r.success ? r.data.numPendingTests + r.data.numTodoTests : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A gate's outcome from its exit status and, for a vitest gate, the skip count its report gave
+ * (`null`: the report is missing or unreadable, which cannot be read as a pass).
+ */
+export function outcome(
+  status: number | null,
+  vitest?: { readonly skipped: number | null },
+): Outcome {
+  if (status !== 0) return "fail";
+  if (vitest === undefined) return "pass";
+  if (vitest.skipped === null) return "fail";
+  return vitest.skipped > 0 ? "skip" : "pass";
 }
 
 /** The gates that did not pass, each as the line the verdict prints, split by outcome. */
@@ -225,11 +248,29 @@ interface NotPassed {
   skipped: string[];
 }
 
+/** A report file's text, read once and removed; null when the run wrote none. */
+export type ReadReport = (file: string) => string | null;
+const readReport: ReadReport = (file) => {
+  if (!existsSync(file)) return null;
+  const text = readFileSync(file, "utf8");
+  rmSync(file, { force: true });
+  return text;
+};
+
+/** The arguments that make a vitest gate write its JSON report to `file`, beside the usual output. */
+export const reportArgs = (file: string): string[] => [
+  "--",
+  "--reporter=default",
+  "--reporter=json",
+  `--outputFile.json=${file}`,
+];
+
 /** Run each gate in order; `write` announces it before it starts. */
 function runEach(
   gates: readonly Gate[],
   spawn: Spawn,
   write: (text: string) => unknown,
+  reportOf: ReadReport,
 ): NotPassed {
   const BIN_FIRST_PATH = [join(ROOT, "node_modules", ".bin"), process.env.PATH]
     .filter(Boolean)
@@ -237,10 +278,14 @@ function runEach(
   const failed: string[] = [];
   const skipped: string[] = [];
 
-  for (const g of gates) {
+  for (const [i, g] of gates.entries()) {
     write(`── ${g.name}\n`);
     const [cmd, ...args] = commandOf(g);
-    const r = spawn(cmd, args, {
+    const file = join(
+      tmpdir(),
+      `paperlint-check-${String(process.pid)}-${String(i)}.json`,
+    );
+    const r = spawn(cmd, g.vitest ? [...args, ...reportArgs(file)] : args, {
       cwd: ROOT,
       stdio: "inherit",
       encoding: "utf8",
@@ -249,12 +294,18 @@ function runEach(
     // 🔴 The exit code is read from the command itself, never from a pipe. `cmd | tail && …`
     // reports the FILTER's status, which is almost always zero — that is how a red harness
     // shipped on 2026-09-16.
-    const o = outcome(r.status);
+    const skips = g.vitest ? { skipped: skippedIn(reportOf(file)) } : undefined;
+    const o = outcome(r.status, skips);
     if (o === "pass") continue;
     const shown = commandOf(g).join(" ");
     if (o === "skip")
-      skipped.push(`${g.name}  (${shown} → ${String(SKIP_EXIT)})`);
-    else failed.push(`${g.name}  (${shown} → ${String(r.status)})`);
+      skipped.push(
+        `${g.name}  (${shown} → ${String(skips?.skipped)} test(s) skipped)`,
+      );
+    else
+      failed.push(
+        `${g.name}  (${shown} → ${r.status === 0 ? "exit 0, but no vitest JSON report to read skips from" : String(r.status)})`,
+      );
   }
   return { failed, skipped };
 }
@@ -299,14 +350,16 @@ export function runGates({
   log = console.log,
   err = console.error,
   write = (s: string) => process.stdout.write(s),
+  reportOf = readReport,
 }: {
   gates?: readonly Gate[];
   spawn?: Spawn;
   log?: (line: string) => void;
   err?: (line: string) => void;
   write?: (text: string) => unknown;
+  reportOf?: ReadReport;
 } = {}): number {
-  const notPassed = runEach(gates, spawn, write);
+  const notPassed = runEach(gates, spawn, write, reportOf);
   report(gates, notPassed, { log, err });
   return notPassed.failed.length ? 1 : 0;
 }

package/scripts/test.test.ts

@@ -24,7 +24,7 @@ test("a failing vitest does not skip the harnesses, and is named as the failure"
     1,
   );
   assert.deepEqual(calls, [
-    ["vitest", "run"],
+    ["vitest", "run", "--project", "unit"],
     ["vigiles", "test", "--min=1", "--no-skip"],
   ]);
   assert.deepEqual(said, [

package/scripts/test.ts

@@ -46,7 +46,7 @@ export function withSources(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
 }
 
 export const SUITES: readonly Suite[] = [
-  { name: "vitest", command: ["vitest", "run"] },
+  { name: "vitest", command: ["vitest", "run", "--project", "unit"] },
   { name: "harnesses", command: ["vigiles", "test", "--min=1"] },
 ];
 

package/skills/cold-read-diff/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: cold-read-diff
-description: Send just-changed paper prose to a reader with NO context and ask what each sentence claims — the only check that catches a sentence which is short, true, jargon-free and still meaningless to anyone who does not already know the idea. Run after every prose edit to a paper, before calling the edit done, and before reporting a section as fixed. Scoped to the diff, so it is cheap enough to run every time. Not a writing grade (grade-paper-writing), not a structural pass (tighten-paper), not a defect review.
+description: Send just-changed paper prose to two readers with NO context — an engineer who asks what each sentence claims, and a skimming workshop reviewer who asks whose result it states and whether it reads like a paper — the only check that catches a sentence which is short, true, jargon-free and still meaningless to anyone who does not already know the idea. Run after every prose edit to a paper, before calling the edit done, and before reporting a section as fixed. Scoped to the diff, so it is cheap enough to run every time. Not a writing grade (grade-paper-writing), not a structural pass (tighten-paper), not a defect review.
 context: fork
 allowed-tools: [Bash, Read, Agent]
 ---
 
-<!-- vigiles:sha256:e45391841e689aa9 compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:293f0627e6873774 compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
 
 # cold-read-diff — the reader who cannot fake understanding
 
@@ -57,21 +57,41 @@ one, and its confusion is the finding.
 
 1. **Take the diff.** `git diff -U0 -- <paper.md>` since the last commit, or the `new_string` of the
    edits just applied. Prose only — skip comments, tables, bibliography.
-2. **Spawn ONE agent with no repository context.** Give it the changed paragraphs **as text in the
-   prompt**, not as a file path. A path is an invitation to read the neighbours, and reading the
-   neighbours is how the check fails silently. `sonnet` is the right model: competent, cheap,
-   and not the one that wrote the sentence.
-3. **Ask exactly two questions per sentence:**
+2. **Spawn TWO agents with no repository context, one per persona, in parallel.** Give each the
+   changed paragraphs **as text in the prompt**, not as a file path. A path is an invitation to read
+   the neighbours, and reading the neighbours is how the check fails silently. `sonnet` is the right
+   model: competent, cheap, and not the one that wrote the sentence.
+
+   | persona | who | what only it can report |
+   |---|---|---|
+   | **the engineer** | a strong practitioner outside academia, reading closely | a sentence that parses only for a reader who already holds the idea |
+   | **the workshop reviewer** | a PC member at the target venue with 40 minutes for the whole paper, skimming the abstract, the introduction and the conclusion, Confidence 3 | a sentence whose result has no owner, a relation between claims left to infer, a sentence that does not read like a paper at this venue |
+
+   The engineer cannot see the second column: a sentence with no stated owner reads to him as
+   confident, and he does not know the venue's register. Both run, every time; neither replaces the
+   other. The reviewer is told the venue's name and nothing else. When the diff touches none of the
+   abstract, the introduction and the conclusion, the reviewer still reads it — as the paragraph a
+   skimming reviewer lands on.
+3. **Ask the engineer exactly two questions per sentence:**
    - *What does this sentence claim? Restate it in your own words.* If restating requires guessing,
      the answer is `CANNOT PARSE` plus what stopped them — an undefined term, a pronoun with no
      referent, a number with no denominator, two clauses that do not connect.
    - *Would a reader who stops here understand it?* Yes / No / Only-if-they-know-X.
+
+   **Ask the reviewer two different ones:**
+   - *Whose result does this sentence state — the authors' measurement, a cited work, or a property
+     of the world?* If it cannot tell, the answer is `WHOSE?` with the sentence quoted.
+   - *Does this read like a paper at this venue?* If not, `REGISTER` with the sentence quoted and
+     what a paper there would write instead — an aphorism, a fragment, a colloquial turn, or two
+     claims side by side with the relation between them unstated.
 4. **Ask for the dangerous class explicitly:** *which sentences sound clever but say less than they
    appear to?* Those read fine and carry nothing, and they are the ones a knowing reader waves
    through.
 5. **Apply the fixes — as rewrites of the whole thought, never as excisions.** See the rule below.
-6. **Re-run on the fix.** An edit is not done until the same kind of reader parses the replacement.
-   One confirming round; do not loop past it.
+6. **Re-run on the fix, with both personas.** An edit is not done until the engineer parses the
+   replacement AND the reviewer finds its owner and its register. A fix for the engineer that goes
+   colloquial is a new `REGISTER` finding, and the reverse holds too. One confirming round; do not
+   loop past it.
 
 ## 🔴 Hand the reader WHOLE PARAGRAPHS, never `+` lines
 
@@ -115,7 +135,8 @@ findings:
 
 - 🔴 **No context in the prompt. Ever.** Not the title, not the abstract, not "this is a paper about
   agent rules files". Every sentence of background handed to the reader is a sentence of confusion
-  they will no longer report.
+  they will no longer report. The one exception is the venue's name, given to the reviewer persona:
+  judging register without knowing the venue is guessing.
 - 🔴 **A fix that removes the flagged construction and keeps the compression is not a fix.** Proven
   twice in one hour: *"not through any defect in how we write it, but because that is what English
   is"* → *"that is what English is for"* (tic gone, meaning inverted into nonsense); *"the agent

package/skills/cold-read-diff/SKILL.md.spec.ts

@@ -8,7 +8,7 @@ import { experimental_skill } from "vigiles/spec";
 export default experimental_skill({
   name: "cold-read-diff",
   description:
-    "Send just-changed paper prose to a reader with NO context and ask what each sentence claims — the only check that catches a sentence which is short, true, jargon-free and still meaningless to anyone who does not already know the idea. Run after every prose edit to a paper, before calling the edit done, and before reporting a section as fixed. Scoped to the diff, so it is cheap enough to run every time. Not a writing grade (grade-paper-writing), not a structural pass (tighten-paper), not a defect review.",
+    "Send just-changed paper prose to two readers with NO context — an engineer who asks what each sentence claims, and a skimming workshop reviewer who asks whose result it states and whether it reads like a paper — the only check that catches a sentence which is short, true, jargon-free and still meaningless to anyone who does not already know the idea. Run after every prose edit to a paper, before calling the edit done, and before reporting a section as fixed. Scoped to the diff, so it is cheap enough to run every time. Not a writing grade (grade-paper-writing), not a structural pass (tighten-paper), not a defect review.",
   context: "fork",
   tools: ["Bash", "Read", "Agent"],
   body: `
@@ -62,21 +62,41 @@ one, and its confusion is the finding.
 
 1. **Take the diff.** \`git diff -U0 -- <paper.md>\` since the last commit, or the \`new_string\` of the
    edits just applied. Prose only — skip comments, tables, bibliography.
-2. **Spawn ONE agent with no repository context.** Give it the changed paragraphs **as text in the
-   prompt**, not as a file path. A path is an invitation to read the neighbours, and reading the
-   neighbours is how the check fails silently. \`sonnet\` is the right model: competent, cheap,
-   and not the one that wrote the sentence.
-3. **Ask exactly two questions per sentence:**
+2. **Spawn TWO agents with no repository context, one per persona, in parallel.** Give each the
+   changed paragraphs **as text in the prompt**, not as a file path. A path is an invitation to read
+   the neighbours, and reading the neighbours is how the check fails silently. \`sonnet\` is the right
+   model: competent, cheap, and not the one that wrote the sentence.
+
+   | persona | who | what only it can report |
+   |---|---|---|
+   | **the engineer** | a strong practitioner outside academia, reading closely | a sentence that parses only for a reader who already holds the idea |
+   | **the workshop reviewer** | a PC member at the target venue with 40 minutes for the whole paper, skimming the abstract, the introduction and the conclusion, Confidence 3 | a sentence whose result has no owner, a relation between claims left to infer, a sentence that does not read like a paper at this venue |
+
+   The engineer cannot see the second column: a sentence with no stated owner reads to him as
+   confident, and he does not know the venue's register. Both run, every time; neither replaces the
+   other. The reviewer is told the venue's name and nothing else. When the diff touches none of the
+   abstract, the introduction and the conclusion, the reviewer still reads it — as the paragraph a
+   skimming reviewer lands on.
+3. **Ask the engineer exactly two questions per sentence:**
    - *What does this sentence claim? Restate it in your own words.* If restating requires guessing,
      the answer is \`CANNOT PARSE\` plus what stopped them — an undefined term, a pronoun with no
      referent, a number with no denominator, two clauses that do not connect.
    - *Would a reader who stops here understand it?* Yes / No / Only-if-they-know-X.
+
+   **Ask the reviewer two different ones:**
+   - *Whose result does this sentence state — the authors' measurement, a cited work, or a property
+     of the world?* If it cannot tell, the answer is \`WHOSE?\` with the sentence quoted.
+   - *Does this read like a paper at this venue?* If not, \`REGISTER\` with the sentence quoted and
+     what a paper there would write instead — an aphorism, a fragment, a colloquial turn, or two
+     claims side by side with the relation between them unstated.
 4. **Ask for the dangerous class explicitly:** *which sentences sound clever but say less than they
    appear to?* Those read fine and carry nothing, and they are the ones a knowing reader waves
    through.
 5. **Apply the fixes — as rewrites of the whole thought, never as excisions.** See the rule below.
-6. **Re-run on the fix.** An edit is not done until the same kind of reader parses the replacement.
-   One confirming round; do not loop past it.
+6. **Re-run on the fix, with both personas.** An edit is not done until the engineer parses the
+   replacement AND the reviewer finds its owner and its register. A fix for the engineer that goes
+   colloquial is a new \`REGISTER\` finding, and the reverse holds too. One confirming round; do not
+   loop past it.
 
 ## 🔴 Hand the reader WHOLE PARAGRAPHS, never \`+\` lines
 
@@ -120,7 +140,8 @@ findings:
 
 - 🔴 **No context in the prompt. Ever.** Not the title, not the abstract, not "this is a paper about
   agent rules files". Every sentence of background handed to the reader is a sentence of confusion
-  they will no longer report.
+  they will no longer report. The one exception is the venue's name, given to the reviewer persona:
+  judging register without knowing the venue is guessing.
 - 🔴 **A fix that removes the flagged construction and keeps the compression is not a fix.** Proven
   twice in one hour: *"not through any defect in how we write it, but because that is what English
   is"* → *"that is what English is for"* (tic gone, meaning inverted into nonsense); *"the agent

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:46bb85bfaa45e595 compiled from skills/draft-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c8d25c21dc01a742 compiled from skills/draft-paper/SKILL.md.spec.ts -->
 
 # draft-paper — prose that survives review and gets cited
 
@@ -78,7 +78,7 @@ grade.
 
 ## Run the prose through the PAPER suite's QA (do not skip — and do not use the blog skills)
 Before any review pass, run the draft through the paper-side prose QA — it catches what a self-read won't:
-- **`grade-paper-writing`** — the 9-dim rubric + the PERSONA cold-read stall pass (a committed
+- **`grade-paper-writing`** — the 10-dim rubric + the PERSONA cold-read stall pass (a committed
   non-academic persona, per-section — the localized "wait, what does that even mean?" axis authors are
   blind to). Its avoid-list grep also strips the AI-writing tropes (hedge-stacking, "it's worth
   noting", limp connectives, fake balance) that make a draft read unserious to a human PC.

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

@@ -84,7 +84,7 @@ grade.
 
 ## Run the prose through the PAPER suite's QA (do not skip — and do not use the blog skills)
 Before any review pass, run the draft through the paper-side prose QA — it catches what a self-read won't:
-- **\`grade-paper-writing\`** — the 9-dim rubric + the PERSONA cold-read stall pass (a committed
+- **\`grade-paper-writing\`** — the 10-dim rubric + the PERSONA cold-read stall pass (a committed
   non-academic persona, per-section — the localized "wait, what does that even mean?" axis authors are
   blind to). Its avoid-list grep also strips the AI-writing tropes (hedge-stacking, "it's worth
   noting", limp connectives, fake balance) that make a draft read unserious to a human PC.