paperlint 7.2.0 → 9.0.0

package/lib/skill-eval-fixture.ts

@@ -10,54 +10,61 @@
  * and the zero was an artifact of the empty directory, not a fact about the skill.
  *
  * Extracted from `paper-pipeline/pipeline-firing.eval.mjs`, which had it right
- * from the start, so the two runners cannot drift apart on what the model sees.
+ * from the start; the `paper-pipeline/*.eval.mjs` experiments carry the same
+ * block, byte for byte.
  *
  * ⚠️ AND THE PRICE, so this file is not a one-sided story (measured 2026-08-12).
  * With a fixture present the model OPENS THE PAPER and looks around, so the number
  * stops being "did the DESCRIPTION fire" and becomes "did the model go investigate
  * and then fire". A different quantity, and a costlier one: ~590k → ~780k tokens
- * per skill (+190k) and 67s → 84s, while this whole fixture is 1,537 characters
- * ≈ 384 tokens. The growth is reading, not input size (`cache` 470k → 652k).
+ * per skill (+190k) and 67s → 84s, while the fixture measured then was 1,537
+ * characters ≈ 384 tokens. The growth is reading, not input size (`cache`
+ * 470k → 652k).
  * Cite the trigger numbers with that caveat attached — it is written out in
  * `vigiles/repro/skill-trigger-2026-08-11/README.md` under "How to read".
  */
 export const FIXTURE = {
-  "paper/paper.md": [
-    "# Prose Isn't Policy: Measuring Whether Agent-Config Rules Are Enforceable",
+  "paper/paper.tex": [
+    "\\documentclass{article}",
+    "\\title{Prose Isn't Policy: Measuring Whether Agent-Config Rules Are Enforceable}",
+    "\\begin{document}",
+    "\\maketitle",
     "",
-    "## Abstract",
+    "\\begin{abstract}",
     "Agent configuration files state rules in prose and assume the model obeys them. We compile a",
-    "corpus of real rules and measure what fraction can be mechanically enforced. We find that 84%",
+    "corpus of real rules and measure what fraction can be mechanically enforced. We find that 84\\%",
     "of rules in our corpus are enforceable, and that LLM-authored checkers for the remainder leak",
-    "silently in 84-96% of adversarial cases \\cite{greshake2023}.",
+    "silently in 84--96\\% of adversarial cases~\\cite{greshake2023}.",
+    "\\end{abstract}",
     "",
-    "## 1 Introduction",
+    "\\section{Introduction}",
     "Every agent harness ships a natural-language rulebook. Nothing checks it. This is the same",
-    "mistake as a code comment that claims an invariant no test enforces \\cite{thompson1984}.",
+    "mistake as a code comment that claims an invariant no test enforces~\\cite{thompson1984}.",
     "",
-    "## 2 Method",
+    "\\section{Method}",
     "We gather rules from public repositories, classify each by enforceability, and build a",
     "two-stage adversarial gate that validates a synthesized rule against a blind gold set.",
     "",
-    "## 3 Results",
-    "See Table 1. The headline number is 84%.",
+    "\\section{Results}",
+    "See Table~1. The headline number is 84\\%.",
     "",
-    "## 4 Discussion",
+    "\\section{Discussion}",
     "The result generalizes beyond our corpus in the sense that the mechanism is not corpus-specific,",
     "though of course the specific percentages are, and it is important to note in this context that",
     "the framing itself may be what carries, rather than the measurement.",
     "",
-    "## 5 Threats to Validity",
+    "\\section{Threats to Validity}",
     "Our corpus is drawn from public repositories and may not represent private configurations.",
     "",
-    "## 6 Related Work",
+    "\\section{Related Work}",
     "TODO",
     "",
-    "## 7 Conclusion",
+    "\\section{Conclusion}",
     "Prose is not policy.",
+    "\\end{document}",
   ].join("\n"),
   "paper/repro/README.md":
-    "# Reproduction artifact\n\n`python3 paper_numbers.py` recomputes every bolded figure in paper.md.\n",
+    "# Reproduction artifact\n\n`python3 paper_numbers.py` recomputes every bolded figure in paper.tex.\n",
   "paper/PIPELINE-STATUS.md":
     "# Pipeline status\n\n| gate | state |\n|---|---|\n| numbers | pass |\n| structure | not run |\n| citations | not run |\n",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "7.2.0",
+  "version": "9.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",
@@ -20,6 +20,7 @@
   "dependencies": {
     "@eslint/markdown": "^8.0.3",
     "@eslint/plugin-kit": "^0.7.2",
+    "@retorquere/bibtex-parser": "^10.0.1",
     "@unified-latex/unified-latex-types": "^1.8.4",
     "@unified-latex/unified-latex-util-parse": "^1.8.4",
     "@unified-latex/unified-latex-util-visit": "^1.8.4",
@@ -37,7 +38,6 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@retorquere/bibtex-parser": "^10.0.1",
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/release-notes-generator": "14.1.1",
     "@types/js-yaml": "^4.0.9",
@@ -56,14 +56,6 @@
     "typescript-eslint": "^8.70.1",
     "vitest": "^4.1.11"
   },
-  "peerDependencies": {
-    "@retorquere/bibtex-parser": "^10.0.1"
-  },
-  "peerDependenciesMeta": {
-    "@retorquere/bibtex-parser": {
-      "optional": true
-    }
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zernie/paperlint.git"
@@ -114,8 +106,6 @@
     "eslint.config.mjs",
     "fixtures",
     "!fixtures/accepted-papers",
-    "!fixtures/real-markdown-paper",
-    "fixtures/real-markdown-paper/baseline.*",
     "hooks",
     "lib",
     "presets",

package/presets/realm.jsonc

@@ -72,7 +72,7 @@
     //
     // A gate on banal's number would give 13 against a limit of 8 and would redden on a paper that
     // is within the limit. For an `error`-level rule that is the worst outcome. The limit stays
-    // owned by the counter inside `build-submission.sh`: it reads the markdown source and therefore
+    // owned by the counter inside `build-submission.sh`: it reads the paper's source and therefore
     // KNOWS where the body ends, which the PDF does not.
     //
     // The numbers below are DATA for that counter and for humans, not an input to the rule. Source:

package/scripts/check.test.ts

@@ -6,7 +6,7 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { test } from "vitest";
+import { test, vi } from "vitest";
 import {
   GATES,
   NOT_COVERED,
@@ -122,6 +122,28 @@ test("🔴 runGates: a vitest gate that exits 0 but leaves no report is a FAILUR
   );
 });
 
+test("🔴 every gate runs with CI=true, as CI runs it — a local check is the CI check", () => {
+  // Libraries change behaviour under CI=true (typescript-eslint infers a single run and parses from
+  // disk): a gate run without it passed locally and failed in CI on 2026-10-07.
+  // Whatever the caller's shell says: on CI it is already "true", so the test sets it otherwise.
+  vi.stubEnv("CI", "false");
+  const seen: (string | undefined)[] = [];
+  runGates({
+    gates: [
+      { name: "a", job: "gates", run: ["true"] },
+      { name: "b", job: "gates", script: "build" },
+    ],
+    spawn: (_cmd, _args, options) => {
+      seen.push(options.env["CI"]);
+      return { status: 0 };
+    },
+    write: () => {},
+    ...capture().io,
+  });
+  vi.unstubAllEnvs();
+  assert.deepEqual(seen, ["true", "true"]);
+});
+
 test("run as a program with every gate passing: the plain verdict, exit 0", () => {
   // spawnSync is replaced before check.ts loads, so the real file runs end to end — every gate
   // "passes" in microseconds instead of the eleven real ones running.

package/scripts/check.ts

@@ -30,8 +30,10 @@
  *
  * ── NO `--fast` FLAG, ON PURPOSE ───────────────────────────────────────────────────────────
  * A subset flag re-creates the exact failure above: the cheap half gets run and reported as
- * "the gates". The slow steps instead SKIP LOUDLY when their prerequisite is genuinely absent
- * (no TeX, no network), and the tail names every skip. "I ran check" then means one thing.
+ * "the gates". Every gate runs with CI=true, as in CI, so a local check is the CI check: the e2e
+ * steps are strict (`test/e2e/need.ts`) — a missing prerequisite (no TeX) FAILS with what to
+ * install, as it does in CI — and a test that still skips is named in the tail, never counted as a
+ * pass. "I ran check" then means one thing.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync } from "node:fs";
@@ -293,7 +295,9 @@ function runEach(
       cwd: ROOT,
       stdio: "inherit",
       encoding: "utf8",
-      env: { ...process.env, PATH: BIN_FIRST_PATH },
+      // CI=true, as CI runs every gate: libraries read it (typescript-eslint infers a single run and
+      // parses from disk), so without it a local check is not the CI check (2026-10-07).
+      env: { ...process.env, CI: "true", PATH: BIN_FIRST_PATH },
     });
     // 🔴 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

package/scripts/coverage-config.test.ts

@@ -21,7 +21,7 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { globSync, readFileSync } from "node:fs";
-import { dirname, join, matchesGlob, resolve } from "node:path";
+import { basename, dirname, join, matchesGlob, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import ts from "typescript";
@@ -146,16 +146,23 @@ test("every typeOnly exclusion has no runtime code", () => {
 });
 
 test("every evalOnly exclusion is imported only by an eval or another evalOnly module", () => {
-  const evalOnly = new Set(expand(CONFIG.evalOnly).map((f) => join(ROOT, f)));
+  const only = expand(CONFIG.evalOnly);
+  const evalOnly = new Set(only.map((f) => join(ROOT, f)));
+  // Any import of one names it — `./x.mjs`, `#lib/x` — so a source whose text holds none of their
+  // base names imports none of them, and only the others are parsed.
+  const names = only.map((f) => basename(f).replace(/\.[^.]+$/, ""));
   const sources = globSync("**/*.{mjs,ts}", {
     cwd: ROOT,
     exclude: (p) => p === "node_modules" || p === "dist" || p === "coverage",
   });
   const importers = sources.flatMap((f) => {
     const abs = join(ROOT, f);
-    return importedPaths(abs, readFileSync(abs, "utf8"))
-      .filter((target) => evalOnly.has(target))
-      .map(() => f);
+    const text = readFileSync(abs, "utf8");
+    return names.some((n) => text.includes(n))
+      ? importedPaths(abs, text)
+          .filter((target) => evalOnly.has(target))
+          .map(() => f)
+      : [];
   });
   const outsiders = importers.filter(
     (f) => !f.endsWith(".eval.mjs") && !evalOnly.has(join(ROOT, f)),
@@ -258,11 +265,13 @@ test("no measured source carries a coverage-ignore comment", () => {
   // The scan covers exactly what c8 measures: the same set, derived from the tracked files.
   assert.deepEqual(files, trackedSources().filter(isMeasured));
   assert.ok(files.length > 0);
-  const offenders = files.filter((f) =>
-    comments(f, readFileSync(join(ROOT, f), "utf8")).some((c) =>
-      IGNORE.test(c),
-    ),
-  );
+  // An ignore comment's text matches IGNORE, so a source whose text does not holds none, and only
+  // the others have their comments read off the tree.
+  const offenders = files
+    .map((f) => [f, readFileSync(join(ROOT, f), "utf8")] as const)
+    .filter(([, text]) => IGNORE.test(text))
+    .filter(([f, text]) => comments(f, text).some((c) => IGNORE.test(c)))
+    .map(([f]) => f);
   assert.deepEqual(offenders, []);
 });
 

package/scripts/harness-api.frozen.json

@@ -10,7 +10,6 @@
     "eslint-rules/pdf-last-page-balance.harness.mjs",
     "eslint-rules/temp-root-realpath.harness.mjs",
     "eslint-rules/tex-build.harness.mjs",
-    "fixtures/real-markdown-paper/real-markdown-paper.harness.ts",
     "lib/agent-cli-version.harness.mjs",
     "lib/paper-config.harness.mjs",
     "lib/skill-trigger-cases.harness.mjs",
@@ -30,13 +29,9 @@
     "skills/osf-artifact-upload/osf-artifact-upload.harness.ts",
     "skills/paper-adversarial-review/paper-adversarial-review.harness.mjs",
     "skills/paper-pipeline/paper-pipeline.harness.mjs",
-    "skills/paper-pipeline/scripts/artifact-coverage.harness.mjs",
     "skills/paper-pipeline/scripts/consumer.harness.mjs",
     "skills/paper-pipeline/scripts/extract-ref-facts.harness.mjs",
     "skills/paper-pipeline/scripts/generated-code.harness.mjs",
-    "skills/paper-pipeline/scripts/population-map.harness.mjs",
-    "skills/paper-pipeline/scripts/provenance.harness.mjs",
-    "skills/paper-pipeline/scripts/round-diff.harness.ts",
     "skills/paper-status/paper-status.harness.mjs",
     "skills/pc-panel-review/pc-panel-review.harness.mjs",
     "skills/plan-paper-timeline/plan-paper-timeline.harness.mjs",

package/scripts/layer-legacy-frozen.test.ts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { test } from "vitest";
 import {
   checkFrozen,
+  filesToLint,
   FROZEN_FILE,
   judge,
   main,
@@ -164,8 +165,9 @@ test("main: problems are listed and fail; a clean count passes", async () => {
   );
 });
 
-// Lints the whole of src/ with the real config: ~3 s alone, 5.6 s measured under c8 with the
-// suite running in parallel — past vitest's 5 s default, so the budget is stated here.
+// Loads the real config (about 2.5 s) and lints the src/ files that carry a directive (21 of 223),
+// measured 2026-10-07: 5.5 s alone, 10–11 s under c8 — past vitest's 5 s default, so the budget is
+// stated here. Linting all of src/ took 22–23 s under c8 and timed out with the suite in parallel.
 test(
   "checkFrozen on this repository: nothing new, nothing grown — and on a tree with no src/, ESLint refuses loudly",
   {
@@ -186,6 +188,43 @@ test(
   },
 );
 
+test("filesToLint: every src/ file whose text carries an eslint-disable directive, in any form — and no other", () => {
+  const root = useTempDir("layer-frozen-files-");
+  writeTree(root, {
+    "src/line.ts": "export const a = 1; // eslint-disable-line no-console\n",
+    "src/next.ts":
+      "// eslint-disable-next-line no-console\nexport const b = 1;\n",
+    "src/block.ts": "/* eslint-disable no-console */\nexport const c = 1;\n",
+    "src/deep/inner.ts":
+      "// eslint-disable-next-line x -- why\nexport const d = 1;\n",
+    "src/plain.ts": "export const e = 1;\n",
+    "lib/outside.ts": "// eslint-disable-next-line no-console\n",
+  });
+  assert.deepEqual(filesToLint(root), [
+    "src/block.ts",
+    "src/deep/inner.ts",
+    "src/line.ts",
+    "src/next.ts",
+  ]);
+});
+
+test("checkFrozen with the real ESLint on a tree: a new legacy directive in a file the list does not name still fails", async () => {
+  const root = useTempDir("layer-frozen-real-");
+  writeTree(root, {
+    [FROZEN_FILE]: JSON.stringify({ files: {} }),
+    "eslint.config.mjs":
+      'export default [{ files: ["src/**/*.ts"], rules: { "no-restricted-globals": ["error", "process"] } }];\n',
+    "src/plain.ts": "export const quiet = 1;\n",
+    "src/new.ts": `// eslint-disable-next-line no-restricted-globals -- ${IO}\nexport const env = process;\n`,
+  });
+  const r = await checkFrozen(root);
+  assert.deepEqual(r.counts, { "src/new.ts": { "no-restricted-globals": 1 } });
+  assert.match(
+    r.problems.join("\n"),
+    /^src\/new\.ts: a new legacy layer exemption/,
+  );
+});
+
 test("checkFrozen: a lint that returns no result reports that nothing was counted", async () => {
   const root = useTempDir("layer-frozen-empty-");
   writeTree(root, {

package/scripts/layer-legacy-frozen.ts

@@ -32,10 +32,15 @@
  * counted by construction — and a range directive (`/* eslint-disable … *\/` around a multi-line
  * import) counts exactly what it silences.
  *
+ * ESLint lints only the files that can carry one (`filesToLint`): a suppressed finding comes from a
+ * directive, and every directive's text holds `eslint-disable` (`-line`, `-next-line`, the block
+ * form). The bulk-suppressions file is not applied here. So the narrowing drops only files that
+ * cannot add to the count — 21 of 223 today — and the count still comes from ESLint's report.
+ *
  * Run: `node scripts/layer-legacy-frozen.ts` (also part of `npm run check`)
  */
 import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ESLint } from "eslint";
@@ -195,11 +200,35 @@ function layerLint(cwd: string): ESLint {
   });
 }
 
+/**
+ * The `src/**\/*.ts` files of `root` whose text holds `eslint-disable` — every file that can carry a
+ * suppressed finding — relative to `root`, POSIX separators, sorted.
+ */
+export function filesToLint(root: string): string[] {
+  const src = join(root, "src");
+  const all = readdirSync(src, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".ts"))
+    .map((e) => join(e.parentPath, e.name));
+  return all
+    .filter((f) => readFileSync(f, "utf8").includes("eslint-disable"))
+    .map((f) => relative(root, f).split(sep).join("/"))
+    .sort();
+}
+
+/**
+ * The files ESLint lints: those that can carry a suppression, or — when there are none, or no
+ * `src/` — the whole glob, so ESLint itself refuses a tree with no source.
+ */
+const lintTargets = (root: string): string[] => {
+  const narrowed = existsSync(join(root, "src")) ? filesToLint(root) : [];
+  return narrowed.length > 0 ? narrowed : ["src/**/*.ts"];
+};
+
 /** Lint `src/` with the repository's configuration and run the whole check. */
 export async function checkFrozen(
   root: string = ROOT,
   {
-    lint = (cwd: string) => layerLint(cwd).lintFiles(["src/**/*.ts"]),
+    lint = (cwd: string) => layerLint(cwd).lintFiles(lintTargets(cwd)),
   }: { lint?: (cwd: string) => Promise<readonly Suppressed[]> } = {},
 ): Promise<FrozenCheck> {
   const data = FrozenFile.parse(

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

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [Bash, Read, Agent]
 ---
 
-<!-- vigiles:sha256:293f0627e6873774 compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c3a1f2644781eb6f compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
 
 # cold-read-diff — the reader who cannot fake understanding
 
@@ -55,7 +55,7 @@ one, and its confusion is the finding.
 
 ## How to run it
 
-1. **Take the diff.** `git diff -U0 -- <paper.md>` since the last commit, or the `new_string` of the
+1. **Take the diff.** `git diff -U0 -- <paper.tex>` since the last commit, or the `new_string` of the
    edits just applied. Prose only — skip comments, tables, bibliography.
 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
@@ -105,7 +105,7 @@ Two more things the same run proved:
 - **Expand build-time macros first.** The reader saw seven raw `{{placeholders}}` and correctly
   reported that every headline number was missing. That is a true statement about the extract and a
   false one about the paper.
-- **Strip working comments.** He graded `<!-- JUSTIFY … -->` notes as prose because he could not tell
+- **Strip working comments.** He graded `% JUSTIFY …` comment notes as prose because he could not tell
   them apart — and said so, which is itself a finding about the extract.
 
 **So:** take the changed lines, then widen each to its enclosing paragraph, expand macros, drop

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

@@ -60,7 +60,7 @@ one, and its confusion is the finding.
 
 ## How to run it
 
-1. **Take the diff.** \`git diff -U0 -- <paper.md>\` since the last commit, or the \`new_string\` of the
+1. **Take the diff.** \`git diff -U0 -- <paper.tex>\` since the last commit, or the \`new_string\` of the
    edits just applied. Prose only — skip comments, tables, bibliography.
 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
@@ -110,7 +110,7 @@ Two more things the same run proved:
 - **Expand build-time macros first.** The reader saw seven raw \`{{placeholders}}\` and correctly
   reported that every headline number was missing. That is a true statement about the extract and a
   false one about the paper.
-- **Strip working comments.** He graded \`<!-- JUSTIFY … -->\` notes as prose because he could not tell
+- **Strip working comments.** He graded \`% JUSTIFY …\` comment notes as prose because he could not tell
   them apart — and said so, which is itself a finding about the extract.
 
 **So:** take the changed lines, then widen each to its enclosing paragraph, expand macros, drop

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

@@ -4,7 +4,7 @@ description: Use when asking "does this paper read well?" / "is the writing any
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:03d0377baf71967f compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:21c8899648c9b223 compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
 
 # grade-paper-writing — grade how the paper READS, then fix it sentence by sentence
 
@@ -53,7 +53,7 @@ derived from that gap.
 ### 🔴 Read the BUILT PDF, not the source
 
 **The stall pass reads the typeset pages.** The source is for locating the fix afterwards, never for
-judging the read. This was previously written as "read the `.tex`/`.md`, **or** run `render-paper`",
+judging the read. This was previously written as "read the `.tex`, **or** run `render-paper`",
 and that *or* is why the pass kept missing what the author saw immediately: he reads the PDF.
 
 Things that exist only in the render, every one of which produces a real stall:
@@ -153,7 +153,7 @@ is what happened.
 
 ## How to run it
 
-1. **Read the actual draft** (the `.tex`/`.md`, or run `render-paper` to read the built pages as a reader
+1. **Read the actual draft** (the `.tex`, or run `render-paper` to read the built pages as a reader
    would). Grade the writing as written — never from a summary.
 2. **Run the cold-read stall pass FIRST — the full specification is below, under "The stall pass".**
    It was previously a pointer to a reference section that did not exist, which is why the pass drifted
@@ -215,10 +215,18 @@ is what happened.
 5. **Flag the two prose traps by name:** (a) Attention-style dense contribution-less prose used where the
    audience does NOT already care; (b) hedge-stacking ("may possibly in some cases potentially") — replace
    each pile with one precise scope sentence.
-6. 🔴 **Run `prose-lint.mjs` and treat every FLAG as a finding, not as context.** It is wired into
-   `paper-lint` on paper edits, so its output arrives whether or not this skill was invoked — but 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.
+6. 🔴 **Run `prose-lint.mjs` on the paper and treat every FLAG as a finding, not as context:**
+
+   ```
+   node ${CLAUDE_SKILL_DIR}/prose-lint.mjs <paper-dir>/paper.tex             # the report
+   node ${CLAUDE_SKILL_DIR}/prose-lint.mjs --headings <paper-dir>/paper.tex  # the headings as a set
+   ```
+
+   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
+   `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.
    Two entries in `THRESHOLDS` exist because this skill previously ran five times without either
    firing: the `"not X, but Y"` density had **no threshold at all** and printed as a neutral line
    while standing at 50.8 per 10,000 words against an LLM baseline of 7.8, and the lexicon missed
@@ -227,21 +235,6 @@ is what happened.
    A number printed without a threshold is prose; that is this project's own thesis, and the linter
    was violating it.
 
-6a. 🔴 **`prose-lint.mjs` IS NO LONGER ALONE — seven of its twelve gating metrics moved
-   on 2026-08-26 into ESLint rules, and running only it shows you five twelfths.** A second
-   run is mandatory; without it, step 6 is incomplete:
-
-   ```
-   npx eslint "papers/*/paper.md" "papers/*/draft.md"
-   ```
-
-   From there come: `paper/citation-density` · `paper/unexplained-jargon` ·
-   `paper/multi-claim-sentence` · `paper/conceits` · `paper/hedge-density` ·
-   `paper/discourse-subject` · `paper/undefined-coinage` (file — `eslint-rules/paper-craft.mjs`).
-   Gain from the move — `file:line:col` on each finding: the old report printed the sentence head,
-   and you had to find it in the article by eye. Everything step 6b says about
-   meaning regression applies to them just the same: this is diagnosis, not objective.
-
 6b. 🔴 **A lint fix that costs meaning is a REGRESSION, and no linter can see it.** The metrics above
    are diagnostics, never objectives. Optimising one directly is how a sentence gets worse while the
    number gets better — and the number is exactly what makes it feel like progress.

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

@@ -59,7 +59,7 @@ derived from that gap.
 ### 🔴 Read the BUILT PDF, not the source
 
 **The stall pass reads the typeset pages.** The source is for locating the fix afterwards, never for
-judging the read. This was previously written as "read the \`.tex\`/\`.md\`, **or** run \`render-paper\`",
+judging the read. This was previously written as "read the \`.tex\`, **or** run \`render-paper\`",
 and that *or* is why the pass kept missing what the author saw immediately: he reads the PDF.
 
 Things that exist only in the render, every one of which produces a real stall:
@@ -159,7 +159,7 @@ is what happened.
 
 ## How to run it
 
-1. **Read the actual draft** (the \`.tex\`/\`.md\`, or run \`render-paper\` to read the built pages as a reader
+1. **Read the actual draft** (the \`.tex\`, or run \`render-paper\` to read the built pages as a reader
    would). Grade the writing as written — never from a summary.
 2. **Run the cold-read stall pass FIRST — the full specification is below, under "The stall pass".**
    It was previously a pointer to a reference section that did not exist, which is why the pass drifted
@@ -221,10 +221,18 @@ is what happened.
 5. **Flag the two prose traps by name:** (a) Attention-style dense contribution-less prose used where the
    audience does NOT already care; (b) hedge-stacking ("may possibly in some cases potentially") — replace
    each pile with one precise scope sentence.
-6. 🔴 **Run \`prose-lint.mjs\` and treat every FLAG as a finding, not as context.** It is wired into
-   \`paper-lint\` on paper edits, so its output arrives whether or not this skill was invoked — but 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.
+6. 🔴 **Run \`prose-lint.mjs\` on the paper and treat every FLAG as a finding, not as context:**
+
+   \`\`\`
+   node \${CLAUDE_SKILL_DIR}/prose-lint.mjs <paper-dir>/paper.tex             # the report
+   node \${CLAUDE_SKILL_DIR}/prose-lint.mjs --headings <paper-dir>/paper.tex  # the headings as a set
+   \`\`\`
+
+   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
+   \`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.
    Two entries in \`THRESHOLDS\` exist because this skill previously ran five times without either
    firing: the \`"not X, but Y"\` density had **no threshold at all** and printed as a neutral line
    while standing at 50.8 per 10,000 words against an LLM baseline of 7.8, and the lexicon missed
@@ -233,21 +241,6 @@ is what happened.
    A number printed without a threshold is prose; that is this project's own thesis, and the linter
    was violating it.
 
-6a. 🔴 **\`prose-lint.mjs\` IS NO LONGER ALONE — seven of its twelve gating metrics moved
-   on 2026-08-26 into ESLint rules, and running only it shows you five twelfths.** A second
-   run is mandatory; without it, step 6 is incomplete:
-
-   \`\`\`
-   npx eslint "papers/*/paper.md" "papers/*/draft.md"
-   \`\`\`
-
-   From there come: \`paper/citation-density\` · \`paper/unexplained-jargon\` ·
-   \`paper/multi-claim-sentence\` · \`paper/conceits\` · \`paper/hedge-density\` ·
-   \`paper/discourse-subject\` · \`paper/undefined-coinage\` (file — \`eslint-rules/paper-craft.mjs\`).
-   Gain from the move — \`file:line:col\` on each finding: the old report printed the sentence head,
-   and you had to find it in the article by eye. Everything step 6b says about
-   meaning regression applies to them just the same: this is diagnosis, not objective.
-
 6b. 🔴 **A lint fix that costs meaning is a REGRESSION, and no linter can see it.** The metrics above
    are diagnostics, never objectives. Optimising one directly is how a sentence gets worse while the
    number gets better — and the number is exactly what makes it feel like progress.