paperlint 9.0.0 → 10.0.0

package/src/new-paper.harness.mjs

@@ -9,6 +9,8 @@
  *     and a placeholder stage would be a red `paper/stages` on the very first run;
  *   - the scorecard carries the `**Readiness verdict:**` line the status hook surfaces on every
  *     paper edit — without it the hook reports that the paper cannot say whether it is ready;
+ *   - a new folder also holds the layout (folders with a `.gitkeep`, `repro/README.md`), and lint
+ *     still reports no finding on it: the rules that read those folders do not see the placeholders;
  *   - it never overwrites, and on an existing folder adds only what is missing;
  *   - the project's `<papers>/.template/` wins over the package, file by file.
  *
@@ -82,6 +84,11 @@ try {
       `\`${dot}\` is refused — discovery skips dot-directories, so it would never be linted`,
       /starting with a dot/.test(nameProblem(dot, []) ?? ""),
     );
+  for (const reserved of ["venues", "extra"])
+    check(
+      `\`${reserved}\` is refused — the papers directory's own folder, which no paper may take`,
+      /reserved/.test(nameProblem(reserved, []) ?? ""),
+    );
   check(
     "a refused name creates nothing",
     newPaper(work, "Bad", { venues: [] }).ok === false &&
@@ -119,6 +126,20 @@ try {
       /2 problems \(0 errors, 2 warnings\)/.test(l.text),
   );
 
+  check(
+    "🔴 the layout is there: the five folders every paper uses, `repro/` with an index, tools/ and data/ — and none of the optional ones",
+    ["reviews", "research", "figures", "versions", "submission"].every((d) =>
+      existsSync(join(papers, "demo", d, ".gitkeep")),
+    ) &&
+      existsSync(join(papers, "demo", "repro", "README.md")) &&
+      existsSync(join(papers, "demo", "repro", "tools", ".gitkeep")) &&
+      existsSync(join(papers, "demo", "repro", "data", ".gitkeep")) &&
+      !existsSync(join(papers, "demo", "repro", ".gitkeep")) &&
+      ["siblings", "sections", "talk", "extra", "_build"].every(
+        (d) => !existsSync(join(papers, "demo", d)),
+      ),
+  );
+
   // What the status hook reads on every paper edit: the verdict line.
   check(
     "the scorecard carries the `**Readiness verdict:**` line the status hook surfaces",
@@ -135,7 +156,8 @@ try {
     again.ok &&
       !again.fresh &&
       read(papers, "demo", STATUS_FILE) === "mine\n" &&
-      again.files.every((f) => f.status === "kept"),
+      again.files.every((f) => f.status === "kept") &&
+      again.layout.length === 0,
   );
   writeFileSync(join(papers, "afile"), "x");
   check(

package/src/new-paper.test.ts

@@ -16,13 +16,28 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { existsSync } from "node:fs";
-import { newPaper, OVERRIDE_DIR, reportNewPaper } from "./new-paper.ts";
+import {
+  newPaper,
+  OVERRIDE_DIR,
+  PACKAGE_TEMPLATES,
+  reportNewPaper,
+} from "./new-paper.ts";
 import { parsePaperSettings } from "./paper-settings.ts";
 import { chooseVenue, run } from "./cli.ts";
 import { shippedPresets } from "./presets.ts";
 import { presetsDir } from "./package-dirs.ts";
 import { lintReport } from "../test/lint-report.ts";
 import { z } from "zod";
+import { judgeLayout } from "./domain/paper-layout.ts";
+import {
+  GITKEEP,
+  NOT_SCAFFOLDED,
+  SCAFFOLD_DIRS,
+  SCAFFOLD_FILES,
+} from "./domain/scaffold-layout.ts";
+import { ROOT_DIRS } from "./domain/paper-layout.ts";
+import { judgeRepro, REPRO_DIR } from "./domain/repro-layout.ts";
+import { statSync } from "node:fs";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -395,11 +410,13 @@ describe("paperlint new --allow-venue-name", () => {
     const r = await newIn(["--allow-venue-name"], {}, "realm-of-agents");
     expect(r.code).toBe(0);
     expect(r.out).not.toMatch(/venue really belongs|names a venue/);
-    expect(readdirSync(r.dir).sort()).toEqual([
-      "PIPELINE-STATUS.md",
-      "paper.tex",
-      "paperlint.json",
-    ]);
+    expect(readdirSync(r.dir)).toEqual(
+      expect.arrayContaining([
+        "PIPELINE-STATUS.md",
+        "paper.tex",
+        "paperlint.json",
+      ]),
+    );
   });
 
   it.each<{
@@ -519,3 +536,279 @@ describe("a project's own template", () => {
     ).toBeGreaterThan(0);
   });
 });
+
+describe("the PIPELINE-STATUS template — only stage tables are headed `id`", () => {
+  // A consumer's stage-table parser reads every table whose first column is `id` as stage rows, and a
+  // row under a heading that names no stage section is an error there: a fix-list table headed `id`
+  // gave a real paper two such errors (2026-10-12). Every other table starts with `#` or a word.
+  const SECTIONS = ["SETUP", "LOOP", "CONTINUOUS", "GATES", "AFTER"];
+  const text = readFileSync(
+    join(PACKAGE_TEMPLATES, "PIPELINE-STATUS.md"),
+    "utf8",
+  );
+  const idTablesUnder = text
+    .split("\n")
+    .reduce<{ heading: string; found: readonly string[] }>(
+      (acc, line) =>
+        line.startsWith("#")
+          ? { ...acc, heading: line.replace(/^#+\s*/, "") }
+          : /^\|\s*id\s*\|/.test(line)
+            ? { ...acc, found: [...acc.found, acc.heading] }
+            : acc,
+      { heading: "", found: [] },
+    ).found;
+
+  it("has stage tables at all", () => {
+    expect(idTablesUnder.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it("puts each one under a stage section's heading", () => {
+    expect(
+      idTablesUnder.filter((h) => !SECTIONS.includes(h.split(/\s/)[0] ?? "")),
+    ).toEqual([]);
+  });
+});
+
+/** Every file under `dir`, as a path from it, sorted. */
+const filesUnder = (dir: string, at = ""): string[] =>
+  readdirSync(join(dir, at), { withFileTypes: true })
+    .flatMap((e) =>
+      e.isDirectory() ? filesUnder(dir, `${at}${e.name}/`) : [`${at}${e.name}`],
+    )
+    .sort();
+
+describe("paperlint new — the layout is scaffolded", () => {
+  const EXPECTED = [
+    "PIPELINE-STATUS.md",
+    "figures/.gitkeep",
+    "paper.tex",
+    "paperlint.json",
+    "repro/README.md",
+    "repro/data/.gitkeep",
+    "repro/tools/.gitkeep",
+    "research/.gitkeep",
+    "reviews/.gitkeep",
+    "submission/.gitkeep",
+    "versions/.gitkeep",
+  ];
+
+  it("a new paper has exactly the expected tree", () => {
+    const papers = join(tmp(), "papers");
+    const r = newPaper(papers, "demo", { venues: [] });
+    expect(r.ok && r.layout).toEqual(SCAFFOLD_FILES.map((f) => f.path));
+    expect(filesUnder(join(papers, "demo"))).toEqual(EXPECTED);
+  });
+
+  it("derives from the layout constants: every root folder is scaffolded or excused, and an excuse names a folder the layout has", () => {
+    const excused = NOT_SCAFFOLDED.map((n) => n.name);
+    expect([...SCAFFOLD_DIRS, ...excused].sort()).toEqual(
+      [...ROOT_DIRS].sort(),
+    );
+    expect(excused.filter((n) => !ROOT_DIRS.includes(n))).toEqual([]);
+    expect(NOT_SCAFFOLDED.filter((n) => n.why.length < 20)).toEqual([]);
+    // The optional folders are decided, not forgotten: these four are not made.
+    expect(excused).toEqual(
+      expect.arrayContaining(["siblings", "sections", "talk", "extra"]),
+    );
+  });
+
+  it(".gitkeep stands in an empty folder only, and no folder is empty but for it", () => {
+    const papers = join(tmp(), "papers");
+    newPaper(papers, "demo", { venues: [] });
+    const dir = join(papers, "demo");
+    const folders = new Set(
+      filesUnder(dir)
+        .filter((p) => p.includes("/"))
+        .map((p) => p.slice(0, p.lastIndexOf("/"))),
+    );
+    for (const f of folders) {
+      const names = readdirSync(join(dir, f)).filter((n) =>
+        statSync(join(dir, f, n)).isFile(),
+      );
+      const subdirs = readdirSync(join(dir, f)).length - names.length;
+      // A folder holds a .gitkeep alone, or real entries and no .gitkeep.
+      expect(
+        names.includes(GITKEEP) ? names.length === 1 && subdirs === 0 : true,
+        f,
+      ).toBe(true);
+    }
+    // repro/ holds its index and folders, so it has no placeholder of its own.
+    expect(existsSync(join(dir, REPRO_DIR, GITKEEP))).toBe(false);
+    expect(existsSync(join(dir, GITKEEP))).toBe(false);
+  });
+});
+
+describe("paperlint new — what the scaffold writes fits the layout", () => {
+  it("the folders it makes are the layout's: nothing it writes is a stray, at the root or in repro/", () => {
+    const papers = join(tmp(), "papers");
+    newPaper(papers, "demo", { venues: [] });
+    const dir = join(papers, "demo");
+    const entries = (d: string) =>
+      readdirSync(d, { withFileTypes: true }).map((e) => ({
+        name: e.name,
+        kind: e.isDirectory() ? ("dir" as const) : ("file" as const),
+      }));
+    expect(judgeLayout(entries(dir), { roots: [] })).toEqual([]);
+    expect(
+      judgeRepro(
+        entries(join(dir, REPRO_DIR)).map((e) => ({
+          ...e,
+          hasReadme: false,
+        })),
+      ),
+    ).toEqual([]);
+  });
+
+  it("repro/README.md is a stub index: one line saying one line per study", () => {
+    const papers = join(tmp(), "papers");
+    newPaper(papers, "demo", { venues: [] });
+    expect(
+      readFileSync(join(papers, "demo", "repro", "README.md"), "utf8"),
+    ).toMatch(/One line per study/);
+  });
+
+  it("the report names the folders in one line", () => {
+    const papers = join(tmp(), "papers");
+    const lines = reportNewPaper(
+      newPaper(papers, "demo", { venues: [] }),
+      (p) => p,
+    );
+    expect(lines.filter((l) => l.includes(GITKEEP))).toEqual([
+      "      + versions/ reviews/ research/ repro/ repro/tools/ repro/data/ figures/ submission/  (the paper's layout; an empty folder holds a .gitkeep, so git keeps it)",
+    ]);
+  });
+});
+
+describe("paperlint new — the scaffold on a folder that is not new", () => {
+  it("a second run changes nothing: all kept, no layout, same tree", () => {
+    const papers = join(tmp(), "papers");
+    newPaper(papers, "demo", { venues: [] });
+    const before = filesUnder(join(papers, "demo"));
+    const again = newPaper(papers, "demo", { venues: [] });
+    expect(again.ok && again.layout).toEqual([]);
+    expect(again.ok && again.files.every((f) => f.status === "kept")).toBe(
+      true,
+    );
+    expect(filesUnder(join(papers, "demo"))).toEqual(before);
+  });
+
+  it("a folder that holds something gets only its missing three files, no layout", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, "old"), { recursive: true });
+    writeFileSync(join(papers, "old", "paper.tex"), "mine\n");
+    const r = newPaper(papers, "old", { venues: [] });
+    expect(r.ok && r.layout).toEqual([]);
+    expect(filesUnder(join(papers, "old"))).toEqual([
+      "PIPELINE-STATUS.md",
+      "paper.tex",
+      "paperlint.json",
+    ]);
+    expect(readFileSync(join(papers, "old", "paper.tex"), "utf8")).toBe(
+      "mine\n",
+    );
+  });
+
+  it("an empty folder made by hand is new: it gets the layout", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, "made"), { recursive: true });
+    const r = newPaper(papers, "made", { venues: [] });
+    expect(r.ok && !r.fresh).toBe(true);
+    expect(filesUnder(join(papers, "made"))).toContain("reviews/.gitkeep");
+  });
+
+  it("🔴 a folder the author emptied of its placeholder is not given it back, and a file in one stays", () => {
+    const papers = join(tmp(), "papers");
+    newPaper(papers, "demo", { venues: [] });
+    const dir = join(papers, "demo");
+    rmSync(join(dir, "reviews", GITKEEP));
+    writeFileSync(join(dir, "reviews", "2026-10-13-pass.md"), "x\n");
+    rmSync(join(dir, "figures"), { recursive: true });
+    newPaper(papers, "demo", { venues: [] });
+    expect(readdirSync(join(dir, "reviews"))).toEqual(["2026-10-13-pass.md"]);
+    expect(existsSync(join(dir, "figures"))).toBe(false);
+  });
+
+  it("an existing repro/README.md is never overwritten", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, "p", "repro"), { recursive: true });
+    writeFileSync(join(papers, "p", "repro", "README.md"), "mine\n");
+    newPaper(papers, "p", { venues: [] });
+    expect(readFileSync(join(papers, "p", "repro", "README.md"), "utf8")).toBe(
+      "mine\n",
+    );
+  });
+});
+
+/** A consumer project with one scaffolded paper and `added` files in it, linted: the rule ids found. */
+async function lintScaffold(added: Record<string, string> = {}) {
+  const root = tmp();
+  writeFileSync(
+    join(root, "package.json"),
+    JSON.stringify({ name: "c", private: true }),
+  );
+  newPaper(join(root, "papers"), "demo", { venues: [] });
+  for (const [p, text] of Object.entries(added)) {
+    mkdirSync(join(root, "papers", "demo", p, ".."), { recursive: true });
+    writeFileSync(join(root, "papers", "demo", p), text);
+  }
+  const out: string[] = [];
+  const code = await run(["lint", "--json"], {
+    cwd: root,
+    log: (s: string) => out.push(s),
+    err: () => {},
+  });
+  return {
+    code,
+    ids: lintReport(out.join("\n")).flatMap((r) =>
+      r.messages.map((m) => m.ruleId),
+    ),
+  };
+}
+
+describe("paperlint lint — a scaffolded paper has no layout finding", () => {
+  const LAYOUT_RULES = [
+    "paper/allowed-files-only",
+    "repro/allowed-files-only",
+    "review/frontmatter",
+    "sibling/frontmatter",
+    "paper/stages",
+    "study/declare-sample",
+  ];
+
+  it("none of the rules that read the layout's folders reports it; only the not-built warnings remain", async () => {
+    const { code, ids } = await lintScaffold();
+    expect(ids.filter((id) => LAYOUT_RULES.includes(id ?? ""))).toEqual([]);
+    expect(ids).toEqual(["pdf/measured", "paper/sources-fresh"]);
+    expect(code).toBe(0);
+  });
+
+  it("🔴 a .gitkeep beside real entries, in any folder the rules read, is not reported either", async () => {
+    const { ids } = await lintScaffold({
+      "siblings/.gitkeep": "",
+      "talk/.gitkeep": "",
+      "sections/.gitkeep": "",
+      "repro/some-study-2026-10-13/README.md": "# s\n",
+      "repro/some-study-2026-10-13/.gitkeep": "",
+    });
+    expect(ids.filter((id) => LAYOUT_RULES.includes(id ?? ""))).toEqual([]);
+  });
+});
+
+describe("paperlint lint — extra/ is never read", () => {
+  // An archived snapshot of an older paper carries every marker a paper does. Under extra/ it is
+  // spillover the layout promises never to judge; anywhere else its folder reads as a paper root.
+  const SNAPSHOT = (dir: string) => ({
+    [`${dir}/PIPELINE-STATUS.md`]: "# Pipeline status\n",
+    [`${dir}/notes.txt`]: "x\n",
+  });
+
+  it("🔴 an archived paper under extra/ is never linted, by any rule", async () => {
+    const { ids } = await lintScaffold(SNAPSHOT("extra/old-2025"));
+    expect(ids).toEqual(["pdf/measured", "paper/sources-fresh"]);
+  });
+
+  it("the same snapshot outside extra/ is reported, so the test above can fail", async () => {
+    const { ids } = await lintScaffold(SNAPSHOT("research/old-2025"));
+    expect(ids).toContain("paper/allowed-files-only");
+  });
+});

package/src/new-paper.ts

@@ -12,20 +12,34 @@
  *   - the name is validated, because it becomes a path and, through the hooks, a shell argument.
  *
  * The only substitution is `{{name}}` → the folder name. Nothing else in a template is touched.
+ *
+ * Beside the three files, a NEW paper folder gets the layout the rules enforce (`SCAFFOLD_FILES`,
+ * src/domain/scaffold-layout.ts): its folders, each with a `.gitkeep` or a first file, so the layout
+ * is visible from the first commit. That is for a folder that is absent or empty. On a folder that
+ * holds anything, `new` adds only the missing three files, as before: a paper that already has its
+ * own shape is not given folders it did not choose, and one whose author deleted an empty folder
+ * does not get it back.
  */
 /* eslint-disable boundaries/dependencies -- legacy I/O, moves behind a port in #76 */
 import {
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 /* eslint-enable boundaries/dependencies */
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_FILE } from "#lib/paper-config";
 import { isRecord } from "./domain/record.ts";
+import { ESCAPE_HATCH, VENUES_DIR } from "./domain/paper-layout.ts";
+import {
+  GITKEEP,
+  SCAFFOLD_FILES,
+  type ScaffoldFile,
+} from "./domain/scaffold-layout.ts";
 import {
   venuesNamedBy,
   withoutVenues,
@@ -51,10 +65,14 @@ export const SOURCE_FILE = "paper.tex";
 /** The flag that lets `paperlint new` create a folder whose name names a venue. */
 export const ALLOW_VENUE_NAME = "--allow-venue-name";
 
+/** Names the papers directory's layout already gives a meaning to (src/domain/paper-layout.ts). */
+const RESERVED_NAMES: readonly string[] = [VENUES_DIR, ESCAPE_HATCH];
+
 /**
  * Why a name is refused, or null. `[a-z0-9._-]+` is the charset; a LEADING dot is refused on top
  * of it, because discovery skips dot-directories — a paper named `.x` would be created and then
- * never linted, which is worse than a refusal.
+ * never linted, which is worse than a refusal. `venues` and `extra` are refused for the same reason:
+ * the first is the venues' corpus beside the papers, the second is never linted.
  *
  * A name that names a venue — one of `venues`' names as whole words (`aisec-2026`) — is refused
  * too, the paper's own venue included: a paper that is rejected goes to another venue and keeps its
@@ -71,6 +89,8 @@ export function nameProblem(
     return `\`${name}\` — a paper name may hold only a-z, 0-9, dot, underscore and hyphen (it becomes a path and a shell argument)`;
   if (name.startsWith("."))
     return `\`${name}\` — a name starting with a dot is skipped by paper discovery, so it would never be linted`;
+  if (RESERVED_NAMES.includes(name))
+    return `\`${name}\` — reserved: \`${VENUES_DIR}/\` beside the papers holds the venues' corpora, and lint never reads a folder named \`${ESCAPE_HATCH}/\`, so a paper by either name would be taken for something else or never linted`;
   const named = venuesNamedBy(name, venues);
   if (named.length === 0) return null;
   const which = named.map((n) => `"${n.name}"`).join(", ");
@@ -96,6 +116,8 @@ export type NewPaperResult =
       /** The folder did not exist before this run. */
       readonly fresh: boolean;
       readonly files: readonly FileOutcome[];
+      /** The layout files written into a folder that was absent or empty, relative to it; none otherwise. */
+      readonly layout: readonly string[];
     }
   | { readonly ok: false; readonly reason: string };
 
@@ -195,7 +217,19 @@ export interface NewPaperOptions {
   readonly venues: readonly NamedVenue[];
 }
 
-// Documented in README.md#getting-started — update it when this changes.
+/** The layout files `dir` is given: all of them when it holds nothing (absent, or made by hand and still empty), else none. */
+const layoutFor = (dir: string, fresh: boolean): readonly ScaffoldFile[] =>
+  fresh || readdirSync(dir).length === 0 ? SCAFFOLD_FILES : [];
+
+/** Writes the layout files under `dir`; `wx` fails rather than overwrite, as for the three files. */
+const writeLayout = (dir: string, layout: readonly ScaffoldFile[]): void => {
+  layout.forEach(({ path, text }) => {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text, { encoding: "utf8", flag: "wx" });
+  });
+};
+
+// Documented in README.md#-getting-started — update it when this changes.
 export function newPaper(
   papersRoot: string,
   name: string,
@@ -225,6 +259,7 @@ export function newPaper(
     if (!planned.ok) return planned;
     toWrite.push(planned.value);
   }
+  const scaffold = layoutFor(dir, fresh);
   // Read every template before writing any file, so a missing one leaves no half-made folder.
   mkdirSync(dir, { recursive: true });
   for (const { file, text, from } of toWrite) {
@@ -232,9 +267,15 @@ export function newPaper(
     writeFileSync(join(dir, file), text, { encoding: "utf8", flag: "wx" });
     files.push({ file, status: "created", from });
   }
-  return { ok: true, dir, fresh, files };
+  writeLayout(dir, scaffold);
+  return { ok: true, dir, fresh, files, layout: scaffold.map((f) => f.path) };
 }
 
+/** The folders the layout files sit in, each once, in order: `reviews/`, `repro/tools/`, … */
+const layoutFolders = (paths: readonly string[]): readonly string[] => [
+  ...new Set(paths.map((p) => `${dirname(p)}/`)),
+];
+
 /** The report lines, shared by `paperlint new` and the first-paper offer in `paperlint init`. */
 export function reportNewPaper(
   result: NewPaperResult,
@@ -250,5 +291,10 @@ export function reportNewPaper(
         ? `      + ${f.file}  (from the ${f.from === "project" ? `project's ${OVERRIDE_DIR}/` : "package"} template)`
         : `      = ${f.file}  (kept — never overwritten)`,
     );
-  return out;
+  return result.layout.length === 0
+    ? out
+    : [
+        ...out,
+        `      + ${layoutFolders(result.layout).join(" ")}  (the paper's layout; an empty folder holds a ${GITKEEP}, so git keeps it)`,
+      ];
 }

package/src/paper-files.test.ts

@@ -75,12 +75,15 @@ async function lint(
 const linted = (stdout: string): string[] =>
   lintReport(stdout).map((r) => r.filePath);
 
-/** Vendored code under a paper: a syntax error, an unknown rule in a directive, plain CommonJS. */
+/**
+ * Vendored code under a paper: a syntax error, an unknown rule in a directive, plain CommonJS — in
+ * `repro/tools/`, where `repro/allowed-files-only` puts a paper's scripts.
+ */
 const VENDORED = {
-  "papers/a/repro/x.js": "return 1;\n",
-  "papers/a/repro/y.mjs":
+  "papers/a/repro/tools/x.js": "return 1;\n",
+  "papers/a/repro/tools/y.mjs":
     "// eslint-disable-next-line import/no-nodejs-modules\nimport fs from 'node:fs';\n",
-  "papers/a/repro/lib/z.cjs": "module.exports = 1;\n",
+  "papers/a/repro/tools/lib/z.cjs": "module.exports = 1;\n",
 };
 
 describe("paperlint lint — lints only the files paperlint owns", () => {
@@ -125,10 +128,10 @@ describe("paperlint lint — lints only the files paperlint owns", () => {
 
   it("a file named on the command line that paperlint does not lint is refused by name", async () => {
     const root = project(VENDORED);
-    const r = await lint(root, ["papers/a/repro/x.js"]);
+    const r = await lint(root, ["papers/a/repro/tools/x.js"]);
     expect(r.code).toBe(2);
     expect(r.err).toMatch(
-      /papers\/a\/repro\/x\.js is not a file paperlint lints/,
+      /papers\/a\/repro\/tools\/x\.js is not a file paperlint lints/,
     );
     expect(r.err).toMatch(/PIPELINE-STATUS\.md/);
   });

package/src/references.test.ts

@@ -303,13 +303,13 @@ const cacheText = (files: Files): string | null => {
   return b === null ? null : new TextDecoder().decode(b);
 };
 
-describe("the lookup cache — <paper>/repro/references-cache.json", () => {
+describe("the lookup cache — <paper>/repro/data/references-cache.json", () => {
   it("a build that fetched writes the cache; the next build is handed it and writes nothing", async () => {
     const f = fetching("crossref:doi:10.1/x");
     const { files, out } = await build(ordinary(), f.check);
     expect(out).toEqual({
       ok: true,
-      note: "references: 1 checked, 0 failing → _build/references.json; 1 new answer → repro/references-cache.json",
+      note: "references: 1 checked, 0 failing → _build/references.json; 1 new answer → repro/data/references-cache.json",
     });
     const written = cacheText(files);
     expect(written).toBe(
@@ -350,7 +350,7 @@ describe("the lookup cache — counting", () => {
     const { out } = await build(ordinary(), two);
     expect(out).toEqual({
       ok: true,
-      note: "references: 1 checked, 0 failing → _build/references.json; 2 new answers → repro/references-cache.json",
+      note: "references: 1 checked, 0 failing → _build/references.json; 2 new answers → repro/data/references-cache.json",
     });
   });
 
@@ -381,7 +381,7 @@ describe("the lookup cache — counting", () => {
     expect({ again, file: cacheText(files) }).toEqual({
       again: {
         ok: true,
-        note: "references: 1 checked, 0 failing → _build/references.json; 1 new answer → repro/references-cache.json",
+        note: "references: 1 checked, 0 failing → _build/references.json; 1 new answer → repro/data/references-cache.json",
       },
       file: serializeLookupCache({
         citations: new Map([["a", ANSWER]]),
@@ -402,7 +402,7 @@ describe("the lookup cache — refusing", () => {
     });
     expect(out).toEqual({
       ok: true,
-      note: "references NOT checked — repro/references-cache.json cannot be read (schema 7: this paperlint reads schema 1) — fix it, or delete it to ask every question again; lint will say so",
+      note: "references NOT checked — repro/data/references-cache.json cannot be read (schema 7: this paperlint reads schema 1) — fix it, or delete it to ask every question again; lint will say so",
     });
     expect(f.seen).toEqual([]);
     expect(cacheText(files)).toBe('{"schema": 7}');

package/src/references.ts

@@ -19,7 +19,7 @@
  * stale when it changes (`pdf_sha256`); these are about the databases and are stale when THEY
  * change (`bib.sha256`). One staleness key per file, the way `pdf/fresh` already works.
  *
- * 🔴 WHAT THE CHECKERS ANSWERED IS KEPT, COMMITTED, IN `<paper>/repro/references-cache.json`
+ * 🔴 WHAT THE CHECKERS ANSWERED IS KEPT, COMMITTED, IN `<paper>/repro/data/references-cache.json`
  * (`domain/lookup-cache.ts`). Loaded before the check and saved after it — only when something new
  * was fetched, a refreshed answer included — so a build asks each question at most once every
  * MAX_AGE_DAYS, not once per build (#107: 217 s for 27 references, every build). The verdicts above are NOT cached: they are derived from the cached
@@ -77,7 +77,7 @@ export const REFERENCES_SCHEMA = 3;
 export const REFERENCES_FILE = "references.json";
 
 /** The lookup cache's place in a paper: committed, beside the paper's other reproduction files. */
-export const LOOKUP_CACHE_FILE = "repro/references-cache.json";
+export const LOOKUP_CACHE_FILE = "repro/data/references-cache.json";
 
 export const lookupCachePath = (paperDir: string): string =>
   join(paperDir, LOOKUP_CACHE_FILE);