paperlint 4.1.0 → 5.0.0

package/eslint-rules/paper-context.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The paper a linted file belongs to, as `paperlint lint` hands it in ESLint's settings, and the
+ * reading of the paper's other files.
+ */
+import { mkdtempSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  PAPERLINT_SETTINGS,
+  otherTexts,
+  paperOf,
+  textOnDisk,
+} from "./paper-context.ts";
+
+describe("paperOf", () => {
+  it("the paper under settings.paperlint.paper", () => {
+    const paper = { main: "/p/paper.tex", files: ["/p/paper.tex", "/p/a.tex"] };
+    expect(paperOf({ [PAPERLINT_SETTINGS]: { paper } })).toEqual(paper);
+  });
+
+  it("none when lint handed none, or handed something else", () => {
+    expect(paperOf({})).toBe(null);
+    expect(paperOf({ [PAPERLINT_SETTINGS]: { paper: { main: 1 } } })).toBe(
+      null,
+    );
+  });
+});
+
+describe("otherTexts", () => {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-ctx-")));
+  writeFileSync(join(dir, "a.tex"), "A");
+  writeFileSync(join(dir, "b.tex"), "B");
+  const paper = {
+    main: join(dir, "a.tex"),
+    files: [join(dir, "a.tex"), join(dir, "b.tex"), join(dir, "gone.tex")],
+  };
+
+  it("every file of the paper but the linted one; a file that cannot be read holds no text", () => {
+    expect(otherTexts(paper, join(dir, "a.tex"))).toEqual(["B", ""]);
+    expect(textOnDisk(join(dir, "gone.tex"))).toBe("");
+  });
+
+  it("none without a paper", () => {
+    expect(otherTexts(null, join(dir, "a.tex"))).toEqual([]);
+  });
+});

package/eslint-rules/paper-context.ts

@@ -0,0 +1,57 @@
+/**
+ * THE PAPER A LINTED FILE BELONGS TO — handed to the rules by `paperlint lint` in ESLint's `settings`.
+ *
+ * ESLint lints one file at a time. A paper whose body is in `sections/*.tex` is several files, and
+ * two questions are about the paper, not the file: which reference form (`Fig.` or `Figure`) the
+ * paper uses most, and whether the build `paper.tex` declares is a review build. The CLI knows the
+ * files (it resolves the includes the way the build does, `bodyFiles` in src/tex-paper.ts) and puts
+ * them under `settings.paperlint.paper`
+ * for `paper.tex` and for every file it includes. A rule reads the other files from disk.
+ *
+ * No setting — a file linted outside `paperlint lint`, or a markdown paper — means a paper of one
+ * file: every rule decides on the file it was handed, as it did before.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+
+/** The key under ESLint's `settings`; the paper is at `settings[PAPERLINT_SETTINGS].paper`. */
+export const PAPERLINT_SETTINGS = "paperlint";
+
+const PaperSetting = z.object({
+  /** The absolute path of the paper's `paper.tex`. */
+  main: z.string(),
+  /** Absolute paths: `paper.tex`, then every file of its body, each once. */
+  files: z.array(z.string()).readonly(),
+});
+
+/** The paper a file belongs to: its main file and all of its files. */
+export type PaperOfFile = Readonly<z.infer<typeof PaperSetting>>;
+
+const Settings = z.looseObject({ paper: PaperSetting });
+
+/** The paper the linted file belongs to, or null when lint handed none. */
+export function paperOf(
+  settings: Readonly<Record<string, unknown>>,
+): PaperOfFile | null {
+  const r = Settings.safeParse(settings[PAPERLINT_SETTINGS]);
+  return r.success ? r.data.paper : null;
+}
+
+/**
+ * The text of a file on disk; empty when it cannot be read — a file gone since `paperlint lint`
+ * named it holds no text for any rule.
+ */
+export function textOnDisk(path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** The texts of the paper's files other than `filename`, read from disk; none without a paper. */
+export const otherTexts = (
+  paper: PaperOfFile | null,
+  filename: string,
+): readonly string[] =>
+  (paper?.files ?? []).filter((f) => f !== filename).map(textOnDisk);

package/eslint-rules/paper-typography.test.mjs

@@ -16,7 +16,10 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { texLanguage } from "./latex-language.ts";
-import typography, { texVisibleRuns } from "./paper-typography.ts";
+import typography, {
+  crefDefinitionRanges,
+  texVisibleRuns,
+} from "./paper-typography.ts";
 import bib from "./bib-reachable-entry.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -118,6 +121,50 @@ describe("paper/section-word", () => {
     expect(ids(await lint(src), "paper/section-word")).toEqual([]);
   });
 
+  it("🔴 a cleveref name definition is not prose: silent, and --fix leaves it as written", async () => {
+    const src =
+      "\\documentclass{article}\n\\usepackage{cleveref}\n\\crefname{section}{§}{§§}\n\\Crefname{section}{§}{§§}\n" +
+      "\\begin{document}\nText.\n\\end{document}\n";
+    expect(ids(await lint(src), "paper/section-word")).toEqual([]);
+    expect(await fixed(src)).toBe(src);
+  });
+
+  it("a definition's range: its attached arguments, or the groups after a macro the parser did not sign", () => {
+    const signed = "\\crefname{section}{}{§§}";
+    expect(crefDefinitionRanges(signed)).toEqual([[0, signed.length]]);
+    const at = (s, e) => ({ start: { offset: s }, end: { offset: e } });
+    const tree = (macro, after) => ({ content: [macro, ...after] });
+    expect(
+      crefDefinitionRanges("", {
+        parse: () =>
+          tree({ type: "macro", content: "Crefname", position: at(0, 9) }, [
+            { type: "group", content: [], position: at(9, 14) },
+            { type: "string", content: "x", position: at(14, 15) },
+          ]),
+      }),
+    ).toEqual([[0, 14]]);
+    // A node with no position has no range; an argument with no content ends nothing.
+    expect(
+      crefDefinitionRanges("", {
+        parse: () =>
+          tree(
+            {
+              type: "macro",
+              content: "crefname",
+              args: [{ type: "argument" }],
+            },
+            [],
+          ),
+      }),
+    ).toEqual([]);
+  });
+
+  it("…while a § in prose next to such a definition is still reported", async () => {
+    const src =
+      "\\documentclass{article}\n\\crefname{section}{§}{§§}\n\\begin{document}\nSee §5.\n\\end{document}\n";
+    expect(ids(await lint(src), "paper/section-word")).toHaveLength(1);
+  });
+
   it("markdown: `§5` → `Section 5`, code untouched", async () => {
     const src = "See §5 and `§3` here.\n";
     expect(ids(await lint(src, "paper.md"), "paper/section-word")).toHaveLength(

package/eslint-rules/paper-typography.ts

@@ -61,8 +61,15 @@
  */
 import assert from "node:assert/strict";
 import { getParser } from "@unified-latex/unified-latex-util-parse";
+import { takeWhile } from "remeda";
 import type { Nodes } from "mdast";
-import type { TexArg, TexNode, TexRoot } from "./latex-language.ts";
+import {
+  texToMdast,
+  type TexArg,
+  type TexNode,
+  type TexRoot,
+} from "./latex-language.ts";
+import { otherTexts, paperOf } from "./paper-context.ts";
 import type {
   RuleContext,
   RuleFixer,
@@ -101,16 +108,27 @@ export function bibRange(text: string): BibRange | null {
   return { start: m.index, end: m.index + whole.length, bodyStart, body };
 }
 
+/** A node of a file's projection, as far as its place goes: mdast's, or the `.tex` language's. */
+interface ProjectedNode {
+  readonly type: string;
+  readonly position?:
+    | {
+        readonly start: { readonly offset?: number | undefined };
+        readonly end: { readonly offset?: number | undefined };
+      }
+    | undefined;
+}
+
 /**
  * The ranges a markup rule must not read: LaTeX comments (the language gives them as `html`
  * nodes, with positions) and the inline bibliography.
  */
 function skippedRanges(
-  sourceCode: RuleSourceCode,
+  nodes: readonly ProjectedNode[],
   raw: string,
 ): [number, number][] {
   const out: [number, number][] = [];
-  for (const n of sourceCode.ast?.children ?? [])
+  for (const n of nodes)
     if (n.type === "html" && n.position) {
       // An offset-less point compares as NaN: inside no range, as `undefined` always did.
       const {
@@ -121,17 +139,97 @@ function skippedRanges(
     }
   const bib = bibRange(raw);
   if (bib) out.push([bib.start, bib.end]);
-  return out;
+  return [...out, ...crefDefinitionRanges(raw)];
+}
+
+/**
+ * cleveref's name and format definitions (`\crefname{section}{§}{§§}`): the label a reference
+ * prints is set there, not written as prose, so a sign in them is not a sign in the text.
+ */
+const CREF_DEFINITIONS: ReadonlySet<string> = new Set([
+  "crefname",
+  "Crefname",
+  "crefformat",
+  "Crefformat",
+  "crefrangeformat",
+  "Crefrangeformat",
+  "crefmultiformat",
+  "Crefmultiformat",
+  "crefrangemultiformat",
+  "Crefrangemultiformat",
+]);
+
+const isGroup = (n: TexNode): boolean => n.type === "group";
+
+/**
+ * A macro's range with its arguments: the ones the parser attached (cleveref's are signed) or the
+ * `{…}` groups standing right after it when it was given none — from the first to the last offset
+ * any of them carries. An argument's closing brace is one character past its last node.
+ */
+function withArguments(
+  m: TexNode & { readonly type: "macro" },
+  after: readonly TexNode[],
+): readonly [number, number][] {
+  const offsets = [
+    m.position?.start.offset,
+    m.position?.end.offset,
+    ...(m.args ?? []).map((a) => {
+      const last = a.content?.at(-1)?.position?.end.offset;
+      return last === undefined ? undefined : last + 1;
+    }),
+    takeWhile(after, isGroup).at(-1)?.position?.end.offset,
+  ].filter((o): o is number => o !== undefined);
+  return offsets.length === 0
+    ? []
+    : [[Math.min(...offsets), Math.max(...offsets)]];
+}
+
+/**
+ * The ranges of the cleveref definitions in the preamble and in the document body. `parse` is
+ * unified-latex's; a test hands in a tree with the fields the walk tolerates being absent.
+ */
+export function crefDefinitionRanges(
+  raw: string,
+  {
+    parse = (s: string): TexRoot => getParser().parse(s),
+  }: { readonly parse?: (s: string) => TexRoot } = {},
+): readonly [number, number][] {
+  const root = parse(raw);
+  const doc = root.content.find(
+    (n): n is Extract<TexNode, { type: "environment" | "mathenv" }> =>
+      n.type === "environment" && n.env === "document",
+  );
+  const lists: readonly (readonly TexNode[])[] = [
+    root.content,
+    doc?.content ?? [],
+  ];
+  return lists.flatMap((list) =>
+    list.flatMap((n, i) =>
+      n.type === "macro" && CREF_DEFINITIONS.has(n.content)
+        ? withArguments(n, list.slice(i + 1))
+        : [],
+    ),
+  );
 }
 const inside = (ranges: readonly [number, number][], i: number) =>
   ranges.some(([s, e]) => i >= s && i < e);
 
-/** Every match of `re` in `raw` outside the skipped ranges. */
-function markupMatches(sourceCode: TexSourceCode, re: RegExp) {
-  const raw = sourceCode.raw;
-  const skip = skippedRanges(sourceCode, raw);
+/** Every match of `re` in `raw` outside the ranges skipped in it (`nodes`: its projection's). */
+const markupMatchesIn = (
+  raw: string,
+  nodes: readonly ProjectedNode[],
+  re: RegExp,
+): readonly RegExpExecArray[] => {
+  const skip = skippedRanges(nodes, raw);
   return [...raw.matchAll(re)].filter((m) => !inside(skip, m.index));
-}
+};
+
+/** Every match of `re` in the linted file outside the skipped ranges. */
+const markupMatches = (
+  sourceCode: TexSourceCode,
+  re: RegExp,
+): readonly RegExpExecArray[] =>
+  markupMatchesIn(sourceCode.raw, sourceCode.ast?.children ?? [], re);
 
 const isTex = (sourceCode: RuleSourceCode): sourceCode is TexSourceCode =>
   typeof sourceCode.raw === "string";
@@ -439,25 +537,42 @@ function leadingZero(context: RuleContext) {
 
 const FIG_REF = /\b(Fig\.|Figure)(?=~?\\(?:ref|autoref)\b)/g;
 
+/** The reference forms another file of the paper writes, read the way the linted file is. */
+const figureFormsIn = (raw: string): readonly (string | undefined)[] =>
+  markupMatchesIn(raw, texToMdast(raw).root.children, FIG_REF).map(
+    ([, form]) => form,
+  );
+
+/**
+ * The minority form is rewritten to the majority one; on a tie, to the full word. The majority is
+ * the PAPER's: a body split into `sections/*.tex` is one document to its reader, so the other files
+ * `paperlint lint` names for this one (`paperOf`) are counted too, and only this file is reported.
+ */
 function figureRefStyle(context: RuleContext) {
   const sc = context.sourceCode;
   if (!isTex(sc)) return;
-  const all = markupMatches(sc, FIG_REF);
-  const short = all.filter((m) => m[1] === "Fig.");
-  const long = all.filter((m) => m[1] === "Figure");
-  if (!short.length || !long.length) return;
-  // The minority form is rewritten to the majority one; on a tie, to the full word.
-  const [minority, word] =
-    short.length > long.length ? [long, "Fig."] : [short, "Figure"];
-  for (const m of minority) {
-    const [, form = ""] = m;
-    const range: [number, number] = [m.index, m.index + form.length];
-    at(context, range[0], range[1], {
-      messageId: "mixed",
-      data: { form, word, n: String(all.length - minority.length) },
-      fix: (f) => f.replaceTextRange(range, word),
+  const own = markupMatches(sc, FIG_REF);
+  const forms: readonly (string | undefined)[] = [
+    ...own.map(([, form]) => form),
+    ...otherTexts(paperOf(context.settings), context.filename).flatMap(
+      figureFormsIn,
+    ),
+  ];
+  const short = forms.filter((f) => f === "Fig.").length;
+  const long = forms.filter((f) => f === "Figure").length;
+  if (short === 0 || long === 0) return;
+  const [minority, word, n] =
+    short > long ? ["Figure", "Fig.", short] : ["Fig.", "Figure", long];
+  own
+    .filter(([, form]) => form === minority)
+    .forEach((m) => {
+      const range = [m.index, m.index + minority.length] as const;
+      at(context, range[0], range[1], {
+        messageId: "mixed",
+        data: { form: minority, word, n: String(n) },
+        fix: (f) => f.replaceTextRange(range, word),
+      });
     });
-  }
 }
 
 const rule = (

package/eslint-rules/tex-build.ts

@@ -51,6 +51,7 @@
  */
 import { readFileSync } from "node:fs";
 import type { RuleContext } from "./rule-context.ts";
+import { paperOf, textOnDisk } from "./paper-context.ts";
 
 /**
  * A copy rather than an import, for the same reason the prose lexicons are copies: a rule may
@@ -169,7 +170,13 @@ const futurePromise = {
         } catch {
           return;
         }
-        if (REVIEW_MODE_RE.test(text)) return;
+        // The build mode is the PAPER's: an included file declares none, `paper.tex` does.
+        const main = paperOf(context.settings)?.main;
+        const declares =
+          main === undefined || main === context.filename
+            ? text
+            : textOnDisk(main);
+        if (REVIEW_MODE_RE.test(declares)) return;
         // Comments are blanked by CUTTING THE TAIL of the line, exactly as the previous
         // implementation did. Columns do not shift: a match is only possible to the LEFT of
         // `%`, and the left part of the line stays in place character for character. An

package/eslint.config.mjs

@@ -428,6 +428,7 @@ const TYPESCRIPT_ONLY = [
   "test/*.{js,mjs,cjs}",
   "test/e2e/**/*.{js,mjs,cjs}",
   "test/fixtures/layers/src/**/*.{js,mjs,cjs}",
+  "fixtures/accepted-papers/**/*.{js,mjs,cjs}",
   "fixtures/real-markdown-paper/**/*.{js,mjs,cjs}",
   "skills/paper-pipeline/scripts/fixtures/**/*.{js,mjs,cjs}",
   "skills/plan-paper-timeline/fixtures/**/*.{js,mjs,cjs}",

package/fixtures/real-markdown-paper/baseline.json

@@ -7,7 +7,7 @@
     "this file names the rule. That is not expressible on an eleven-line stub, where every line was",
     "written by someone who already knew which rule would read it.",
     "",
-    "Recorded 2026-09-19, re-recorded 2026-09-26 for 3.0.0. Three of the four rules are about the",
+    "Recorded 2026-09-19, re-recorded 2026-09-26 for 3.0.0. Two of the three rules are about the",
     "scorecard being deliberately thin (no pdf, no frozen source) rather than about the prose.",
     "paper/leading-zero reports each of the 18 p-values of paperlint#44 where it is (one finding per",
     "occurrence since 3.0.0; before, paper/typography reported them as one count). They are real",
@@ -17,7 +17,6 @@
   "findings": {
     "paper/stages": 2,
     "paper/source": 1,
-    "paper/research-question": 1,
     "paper/leading-zero": 18
   }
 }

package/fixtures/real-markdown-paper/baseline.ts

@@ -1,8 +1,9 @@
 /**
- * ONE reader of `baseline.json`, shared by the two runs that compare against it: the harness
- * beside this file (the repository's own `bin/paperlint.mjs`) and `test/e2e/install/install.e2e.ts` (the binary
- * a consumer actually got). Two copies of "growth fails, a drop never does" would drift the first
- * time one of them is tightened, and the two runs would then disagree about the same article.
+ * ONE reader of `baseline.json`, shared by every run that compares against one: the harness beside
+ * this file (the repository's own `bin/paperlint.mjs`), `test/e2e/install/install.e2e.ts` (the
+ * binary a consumer actually got), and `fixtures/accepted-papers/accepted-papers.test.ts` (one
+ * baseline per accepted paper). Two copies of "growth fails, a drop never does" would drift the
+ * first time one of them is tightened, and the runs would then disagree about the same rules.
  */
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -21,10 +22,10 @@ const LintOutput = z.array(
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
-/** The recorded counts, `{ruleId: n}`. */
-export function recordedFindings(): Counts {
+/** The counts recorded in `dir`'s `baseline.json` (this article's by default), `{ruleId: n}`. */
+export function recordedFindings(dir: string = HERE): Counts {
   return Baseline.parse(
-    JSON.parse(readFileSync(join(HERE, "baseline.json"), "utf8")),
+    JSON.parse(readFileSync(join(dir, "baseline.json"), "utf8")),
   ).findings;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -110,6 +110,7 @@
     "eslint-rules",
     "eslint.config.mjs",
     "fixtures",
+    "!fixtures/accepted-papers",
     "!fixtures/real-markdown-paper",
     "fixtures/real-markdown-paper/baseline.*",
     "hooks",

package/scripts/check.ts

@@ -3,9 +3,9 @@
  * `npm run check` — ONE command you run on yourself before pushing.
  *
  * ── WHY IT EXISTS, AND IT IS A MEASURED FAILURE, NOT A TIDINESS IDEA ───────────────────────
- * On 2026-09-19 a change to `paper/research-question` was pushed that broke the test suite.
+ * On 2026-09-19 a change to a lint rule was pushed that broke the test suite.
  * The gates were run afterwards — `lint`, `check:readme`, `check:globs`, `check:content-only`,
- * and the rule's own (since-removed) mutation battery, all green — but `npm test` and `test:install` were not,
+ * and the rule's own mutation battery, all green — but `npm test` and `test:install` were not,
  * because there were eleven separate scripts and no way to run them except from memory. Five
  * callers across two files had been left behind by the change, and the suite said so; nobody
  * asked it.

package/scripts/eslint-report-guard.mjs

@@ -17,6 +17,7 @@
  * proves the BEHAVIOUR rather than the presence of a string in YAML.
  *
  * Usage: node scripts/eslint-report-guard.mjs <report.json> <eslint-rc> [paths] [config]
+ * An empty or absent `paths` means the CLI was given none and linted the papersDir of the config.
  * Exit:  1 when nothing was measured (unparsable report, or zero files linted)
  *        otherwise ESLint's own return code, passed through untouched
  */
@@ -26,8 +27,10 @@ import { readFileSync } from "node:fs";
 export function guard(
   reportPath,
   eslintRc,
-  { paths = ".", config = "paperlint.json" } = {},
+  { paths = "", config = "paperlint.json" } = {},
 ) {
+  const scope =
+    paths.trim() === "" ? "(none: the papersDir of paperlint.json)" : paths;
   const lines = [];
   let res;
   try {
@@ -48,7 +51,7 @@ export function guard(
   if (res.length === 0) {
     lines.push(
       "::error::ESLint linted ZERO files. In the exit code this is indistinguishable from a clean " +
-        `run, and it means the paths or the config matched nothing. paths=${paths} config=${config}`,
+        `run, and it means the paths or the config matched nothing. paths=${scope} config=${config}`,
     );
     return { code: 1, lines };
   }

package/scripts/harness-api.frozen.json

@@ -5,7 +5,6 @@
     "action.harness.mjs",
     "eslint-rules/install-path-literals.harness.mjs",
     "eslint-rules/latex-language.harness.mjs",
-    "eslint-rules/paper-research-question.harness.mjs",
     "eslint-rules/paper-stages.harness.mjs",
     "eslint-rules/papers.harness.mjs",
     "eslint-rules/pdf-last-page-balance.harness.mjs",

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