paperlint 4.2.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.ts

@@ -63,7 +63,13 @@ 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,
@@ -102,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 {
@@ -197,12 +214,22 @@ export function crefDefinitionRanges(
 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";
@@ -510,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "4.2.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",

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/paper-pipeline/references/pipeline-status-template.md

@@ -11,7 +11,7 @@ the verdict line's wording and the `☐`/`☑` marks as they are, or the hook go
 
 ## The front matter
 
-Above the sections, the file carries YAML. Two fields are read by rules:
+Above the sections, the file carries YAML. The rules read its `stages` field:
 
 ```yaml
 ---
@@ -22,20 +22,9 @@ stages:
     bytes: 305412
     source: versions/2026-07-22-submitted.tex
     sourceBytes: 57210
-researchQuestion: "Does pruning the state space reduce review cost?"
 ---
 ```
 
-`researchQuestion` is **your sentence, written once** — not a label the checker hunts for in the
-prose. `paper/research-question` then asks two things it can actually answer: is it written down,
-and does the paper contain it (whitespace collapsed). Leave the field out and a shipped paper gets
-an advisory finding, which is the right outcome for a position paper with no question: the absence
-becomes a decision on the record rather than an omission.
-
-⚠️ Write the sentence the way it appears in the paper. If the paper breaks it across lines that is
-fine — only whitespace is normalised — but LaTeX markup inside the sentence (`\emph{cost}`) will not
-match, and the finding will quote exactly what it looked for.
-
 ## The row ids, and what each one runs
 
 The `id` cell is the **join key** — the same string appears in this template, in every paper's
@@ -116,10 +105,7 @@ existed. Neither is expressible now. Keep new ids lowercase, one word, and say w
 The template itself is a FILE, not this page: `templates/paper/PIPELINE-STATUS.md` at the package
 root (beside `templates/paper/paper.tex` and `paper.md`). `paperlint new <name>` copies it with the paper's
 name filled in, and a project that keeps its own richer scorecard puts one at
-`<papers>/.template/PIPELINE-STATUS.md`, which `paperlint new` prefers. It used to live in a fenced block
-here, which meant a command would have had to parse markdown to extract it, and a human had to copy
-it by hand. The copy carries `researchQuestion` (empty) and no `stages` — a new paper has shipped
-nothing.
+`<papers>/.template/PIPELINE-STATUS.md`, which `paperlint new` prefers. The copy carries no `stages` — a new paper has shipped nothing.
 
 ---
 

package/src/adapters/latex/includes.ts

@@ -55,10 +55,18 @@ export const includesOf = (t: ParsedTex): readonly Include[] =>
 const isDocument = (n: Node): n is Readonly<Ast.Environment> =>
   n.type === "environment" && n.env === "document";
 
-/** The span of the `document` environment's body, or null when the source has none. */
+/**
+ * The span of the `document` environment's body, or null when the source has none. A macro's own
+ * position ends at its name, so its place is taken with its arguments: a body ending in
+ * `\input{sections/a}` ends at the closing brace.
+ */
 export const documentBodyOf = (t: ParsedTex): Span | null =>
   (t.root.content.find(isDocument)?.content ?? [])
-    .flatMap((n) => inPlace(placeOf(n), (span) => [span]))
+    .flatMap((n) =>
+      inPlace(n.type === "macro" ? macroPlace(n) : placeOf(n), (span) => [
+        span,
+      ]),
+    )
     .reduce<Span | null>(
       (body, span) =>
         body === null ? span : { start: body.start, end: span.end },

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

@@ -526,6 +526,14 @@ describe("documentBodyOf — the body of a source that is a document of its own"
     expect(latexReader.documentBody(src)).toEqual(body);
   });
 
+  it("a body ending in a macro ends after that macro's arguments, not after its name", () => {
+    const src = "\\begin{document}\nText.\n\\input{sections/a}\\end{document}";
+    const body = documentBodyOf(parseLatex(src));
+    expect(body && src.slice(body.start, body.end)).toBe(
+      "Text.\n\\input{sections/a}",
+    );
+  });
+
   it("none without a document environment, or with an empty one", () => {
     expect(documentBodyOf(parseLatex("just text"))).toBe(null);
     expect(documentBodyOf(parseLatex("\\begin{document}\\end{document}"))).toBe(

package/src/build.harness.mjs

@@ -264,8 +264,10 @@ try {
     tex.calls.every((c) => c.cwd === clean),
   );
   check(
-    "🔴 pdflatex got paperlint's venues directory on TEXINPUTS, trailing separator kept",
-    tex.calls.every((c) => c.texinputs === `${venues}${delimiter}`),
+    "🔴 pdflatex got the paper's directory, then paperlint's venues directory, on TEXINPUTS, trailing separator kept",
+    tex.calls.every(
+      (c) => c.texinputs === `.${delimiter}${venues}${delimiter}`,
+    ),
   );
 
   // ── the measure step: facts for the lint rules ────────────────────────────────────────

package/src/build.test.ts

@@ -6,7 +6,8 @@
  */
 import assert from "node:assert/strict";
 import { existsSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { delimiter, join } from "node:path";
+import { texInputsDir } from "./package-dirs.ts";
 import { test } from "vitest";
 import { present, useTempDir, writeTree } from "../test/support.ts";
 import {
@@ -344,6 +345,22 @@ test("paths: a paper that IS the working directory is named by its full path", a
   assert.equal(existsSync(join(dir, "paper.pdf")), false);
 });
 
+test("🔴 pdflatex looks for an \\input in the paper's directory, then paperlint's inputs, then the system tree", async () => {
+  const dir = paper();
+  const f: Fake = {};
+  const inner = fakeRun(f);
+  const seen: (string | undefined)[] = [];
+  await build(dir, f, {
+    run: (bin, args, opts) => {
+      if (bin === "pdflatex") seen.push(opts.env?.["TEXINPUTS"]);
+      return inner(bin, args, opts);
+    },
+  });
+  // The same search path the lint rules read includes through (`texSearchPath`).
+  // A pass runs in the paper's directory, where `.` is that directory.
+  assert.equal(seen[0], [".", texInputsDir(), ""].join(delimiter));
+});
+
 test("facts that cannot be read fail the build at `facts`", async () => {
   const { line } = await build(
     paper({ "paper.tex": TEX, "paperlint.json": "{ nope" }),

package/src/build.ts

@@ -44,7 +44,7 @@ import { createHash } from "node:crypto";
 import { delimiter, join, relative } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { getParser } from "@unified-latex/unified-latex-util-parse";
-import { texInputsDir } from "./package-dirs.ts";
+import { texInputsDir, texSearchPath } from "./package-dirs.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
 import {
   declaredVenue,
@@ -268,11 +268,15 @@ export const inputsStep: BuildStep = {
   required: false,
   applies: () => ({
     yes: true,
-    why: `TEXINPUTS += ${texInputsDir()}`,
+    why: `TEXINPUTS += the paper's directory, then ${texInputsDir()}`,
   }),
+  // The same search path the lint rules read includes through: one answer to which file is meant.
+  // A pass runs IN the paper's directory, so that directory is `.` here. TeX names a file it finds
+  // through an absolute entry by that absolute path: with the directory itself on TEXINPUTS, the
+  // `broken` build fixture's log said `/tmp/…/paper.tex:6:` instead of `./paper.tex:6:` (measured).
   run: (ctx) => ({
     ok: true,
-    env: withTexInputs(ctx.env, [texInputsDir()]),
+    env: withTexInputs(ctx.env, texSearchPath(".")),
   }),
 };
 

package/src/cli.harness.mjs

@@ -132,8 +132,8 @@ check(
     Array.isArray(cfg) && ruleBlocks(cfg).length === 4,
   );
   check(
-    "with a LaTeX language a fifth block is added",
-    ruleBlocks(buildConfig({}, {})).length === 5,
+    "with a LaTeX language two blocks are added: paper.tex, and the files it includes",
+    ruleBlocks(buildConfig({}, {})).length === 6,
   );
   check(
     "🔴 the project's paper TEMPLATE directory is ignored — flat config does not skip dot-directories",
@@ -181,7 +181,7 @@ check(
     writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
     writeFileSync(
       join(paper, "PIPELINE-STATUS.md"),
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
     );
     writeFileSync(
       join(root, "package.json"),
@@ -441,32 +441,14 @@ check(
         !existsSync(join(dir, WORKFLOW_PATH)),
       );
       check(
-        "and the CI step is still printed — it just gets pasted in by hand",
-        /uses: zernie\/paperlint@/.test(out.text()) &&
-          /paths: writing/.test(out.text()),
-      );
-    }
-    {
-      // Guards: the printed step carries the tag of the running release, not a placeholder.
-      const dir = project("ci-printed-pin", { papers: ["writing"] });
-      const out = say();
-      await init(dir, {
-        log: out.log,
-        err: out.log,
-        interactive: false,
-        run: haveAll,
-        version: "1.2.3",
-      });
-      check(
-        "🔴 a released version — the printed step is pinned to its tag, no <commit-sha>",
-        /uses: zernie\/paperlint@v1\.2\.3\b/.test(out.text()) &&
-          !/<commit-sha>/.test(out.text()),
+        "and the CI steps are still printed — they just get pasted in by hand",
+        out.text().includes("- uses: ./node_modules/paperlint"),
       );
     }
     {
       const dir = project("ci-yes", { papers: ["writing"] });
       const asked = [];
-      const wf = await offerWorkflow(dir, "writing", {
+      const wf = await offerWorkflow(dir, {
         interactive: true,
         ask: async (q) => {
           asked.push(q);
@@ -477,16 +459,22 @@ check(
         "saying yes WRITES the workflow",
         wf === "written" && existsSync(join(dir, WORKFLOW_PATH)),
       );
+      const steps =
+        yamlLoad(readFileSync(join(dir, WORKFLOW_PATH), "utf8"))?.jobs?.papers
+          ?.steps ?? [];
       check(
-        "and the workflow carries THE directory that was actually discussed",
-        /paths: writing/.test(readFileSync(join(dir, WORKFLOW_PATH), "utf8")),
+        "🔴 the workflow runs the action from the installed package — one revision, set by the lockfile",
+        steps.some((st) => st.uses === "./node_modules/paperlint") &&
+          !steps.some((st) =>
+            String(st.uses ?? "").startsWith("zernie/paperlint"),
+          ),
       );
       check(
-        "without a known release the action keeps the obvious placeholder, never a guessed tag",
-        /@<commit-sha>/.test(readFileSync(join(dir, WORKFLOW_PATH), "utf8")),
+        "and it repeats no papers directory — the action reads papersDir from paperlint.json",
+        steps.every((st) => st.with?.paths === undefined),
       );
       check("the question is asked exactly once", asked.length === 1);
-      const again = await offerWorkflow(dir, "writing", {
+      const again = await offerWorkflow(dir, {
         interactive: true,
         ask: async () => "y",
       });
@@ -495,29 +483,9 @@ check(
         again === "kept",
       );
     }
-    {
-      const dir = project("ci-pinned", { papers: ["writing"] });
-      const wf = await offerWorkflow(dir, "writing", {
-        interactive: true,
-        ask: async () => "y",
-        version: "1.2.3",
-      });
-      const yaml = existsSync(join(dir, WORKFLOW_PATH))
-        ? readFileSync(join(dir, WORKFLOW_PATH), "utf8")
-        : "";
-      const uses = (yamlLoad(yaml)?.jobs?.papers?.steps ?? []).map(
-        (s) => s.uses,
-      );
-      check(
-        "🔴 a released version — the written workflow is pinned to its tag, no <commit-sha> left",
-        wf === "written" &&
-          uses.includes("zernie/paperlint@v1.2.3") &&
-          !yaml.includes("<commit-sha>"),
-      );
-    }
     {
       const dir = project("ci-no", { papers: ["writing"] });
-      const no = await offerWorkflow(dir, "writing", {
+      const no = await offerWorkflow(dir, {
         interactive: true,
         ask: async () => "",
       });
@@ -532,7 +500,7 @@ check(
       // 🔴 THE `.catch` HERE IS LOAD-BEARING, NOT CAUTION. A leaked exception is a PROPERTY that
       // gets asserted; without it, the harness crashes instead of failing a named assertion,
       // i.e. the real defect would look like a hole in the test rather than a caught one.
-      const aborted = await offerWorkflow(dir, "writing", {
+      const aborted = await offerWorkflow(dir, {
         interactive: true,
         ask: async () => {
           throw new Error("Aborted with Ctrl+D");
@@ -733,7 +701,7 @@ check(
       "x".repeat(100),
     );
     const status = (bytes) =>
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
     writeFileSync(join(paper, "versions", "s.tex"), "abcd");
     writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
 
@@ -822,7 +790,7 @@ check(
     );
     writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
     const status = (bytes) =>
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
     writeFileSync(join(paper, "PIPELINE-STATUS.md"), status(100));
 
     // findProjectRoot — kept separate from the run so the failure is distinguishable
@@ -934,7 +902,7 @@ check(
     );
     writeFileSync(
       join(paper, "PIPELINE-STATUS.md"),
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
     );
     writeFileSync(
       join(root, "paperlint.json"),