paperlint 9.0.1 → 10.0.0

package/src/domain/repro-layout.test.ts

@@ -0,0 +1,222 @@
+/**
+ * The layout of a paper's `repro/` (`src/domain/repro-layout.ts`), judged on its top entries alone.
+ * Both halves: the layout itself, the byproducts and dated study folders with a README.md are clean;
+ * every other entry is reported once, with where it goes by kind, and a study folder without its
+ * README.md is reported once.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  DATA_CURE,
+  FILE_CURE_BY_KIND,
+  MOVED_FILES,
+  NOTE_CURE,
+  SCRIPT_CURE,
+  isStudyName,
+  judgeRepro,
+  reproMessage,
+  suggestedStudyName,
+  type ReproEntry,
+} from "./repro-layout.ts";
+
+const file = (name: string): ReproEntry => ({
+  name,
+  kind: "file",
+  hasReadme: false,
+});
+const dir = (name: string, hasReadme = true): ReproEntry => ({
+  name,
+  kind: "dir",
+  hasReadme,
+});
+
+describe("isStudyName", () => {
+  it.each([
+    "context-reading-2026-10",
+    "human-labels-2026-10",
+    "ablation-2026-10-12",
+    "a1-b2-2026-01-31",
+    "leap-2024-02-29",
+    "leap-2000-02-29",
+    "april-2026-04-30",
+  ])("%s is a study's name", (name) => {
+    expect(isStudyName(name)).toBe(true);
+  });
+
+  it.each([
+    ["no date", "ablation"],
+    ["no slug", "2026-10-12"],
+    ["a capital", "Ablation-2026-10-12"],
+    ["an underscore", "human_labels-2026-10"],
+    ["a doubled hyphen", "a--b-2026-10"],
+    ["month 13", "x-2026-13"],
+    ["month 00", "x-2026-00-01"],
+    ["day 00", "x-2026-10-00"],
+    ["31 April", "x-2026-04-31"],
+    ["29 February of a common year", "x-2025-02-29"],
+    ["29 February 1900", "x-1900-02-29"],
+    ["32 October", "x-2026-10-32"],
+    ["a two-digit year", "x-26-10-12"],
+  ])("not with %s: %s", (_why, name) => {
+    expect(isStudyName(name)).toBe(false);
+  });
+});
+
+describe("suggestedStudyName", () => {
+  it("a name that is a study's once lowercased and hyphenated, as it is", () => {
+    expect(suggestedStudyName("Human_Labels_2026_10")).toBe(
+      "human-labels-2026-10",
+    );
+  });
+
+  it("a name with no date: its slug, and the date to fill in", () => {
+    expect(suggestedStudyName("Old Baseline")).toBe("old-baseline-YYYY-MM-DD");
+  });
+
+  it("a name with a date that is not one: the slug without it", () => {
+    expect(suggestedStudyName("results-2026-13-01")).toBe("results-YYYY-MM-DD");
+  });
+
+  it("a name with no slug at all: a placeholder for one", () => {
+    expect(suggestedStudyName("2026-10")).toBe("<slug>-YYYY-MM-DD");
+    expect(suggestedStudyName("__")).toBe("<slug>-YYYY-MM-DD");
+  });
+});
+
+describe("judgeRepro — silent", () => {
+  it("on the layout: the index, .gitignore, tools/, data/ and dated studies with a README.md", () => {
+    expect(
+      judgeRepro([
+        file("README.md"),
+        file(".gitignore"),
+        dir("tools", false),
+        dir("data", false),
+        dir("ablation-2026-10-12"),
+        dir("human-labels-2026-10"),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("on what interpreters, package managers and the system leave, file or folder", () => {
+    expect(
+      judgeRepro([
+        dir("__pycache__", false),
+        dir(".pytest_cache", false),
+        dir(".mypy_cache", false),
+        dir(".ruff_cache", false),
+        dir(".ipynb_checkpoints", false),
+        dir("node_modules", false),
+        dir(".venv", false),
+        file(".DS_Store"),
+        file("Thumbs.db"),
+      ]),
+    ).toEqual([]);
+  });
+});
+
+describe("judgeRepro — reports, one finding per entry", () => {
+  it("a loose file, by kind: script, tool manifest, data, note, anything else", () => {
+    expect(
+      judgeRepro([
+        file("paper_numbers.py"),
+        file("check-anon.sh"),
+        file("harness.MJS"),
+        file("requirements.txt"),
+        file("Makefile"),
+        file("numbers.tsv"),
+        file("runs.jsonl"),
+        file("notes.md"),
+        file("figure.pdf"),
+        file("LICENSE"),
+      ]).map((f) => [f.path, f.problem, f.cure]),
+    ).toEqual([
+      ["repro/paper_numbers.py", "stray", SCRIPT_CURE],
+      ["repro/check-anon.sh", "stray", SCRIPT_CURE],
+      ["repro/harness.MJS", "stray", SCRIPT_CURE],
+      ["repro/requirements.txt", "stray", SCRIPT_CURE],
+      ["repro/Makefile", "stray", SCRIPT_CURE],
+      ["repro/numbers.tsv", "stray", DATA_CURE],
+      ["repro/runs.jsonl", "stray", DATA_CURE],
+      ["repro/notes.md", "stray", NOTE_CURE],
+      ["repro/figure.pdf", "stray", FILE_CURE_BY_KIND],
+      ["repro/LICENSE", "stray", FILE_CURE_BY_KIND],
+    ]);
+  });
+
+  it("a file paperlint once kept at the top: where it is read now, with the command", () => {
+    expect(
+      judgeRepro(MOVED_FILES.map((m) => file(m.name))).map((f) => f.cure),
+    ).toEqual(MOVED_FILES.map((m) => m.cure));
+    expect(MOVED_FILES[0]?.cure).toContain(
+      "git mv repro/references-cache.json repro/data/",
+    );
+  });
+});
+
+describe("judgeRepro — reports a folder, one finding each", () => {
+  it("an undated folder: rename it as a study, with its first commit's date as the default", () => {
+    expect(judgeRepro([dir("Old_Baseline")])).toEqual([
+      {
+        path: "repro/Old_Baseline/",
+        problem: "stray",
+        cure: "rename it to `old-baseline-YYYY-MM-DD`, one folder per study or spike, named for what it is and the date it began — the date of its first commit is a fine default (`git log --reverse --format=%as -- repro/Old_Baseline | head -1`, run in the paper folder) — and give it a README.md; if it holds scripts or data shared across the paper instead, move them into repro/tools/ or repro/data/",
+      },
+    ]);
+  });
+
+  it("a study folder without its README.md", () => {
+    expect(judgeRepro([dir("ablation-2026-10-12", false)])).toEqual([
+      {
+        path: "repro/ablation-2026-10-12/",
+        problem: "no-readme",
+        cure: "add repro/ablation-2026-10-12/README.md — what the study asks, how to run it, what it found — and a line for it in repro/README.md",
+      },
+    ]);
+  });
+
+  it("a name allowed for a folder, as a file, and the other way round", () => {
+    expect(
+      judgeRepro([
+        file("tools"),
+        file("ablation-2026-10-12"),
+        dir("README.md"),
+      ]).map((f) => f.path),
+    ).toEqual(["repro/tools", "repro/ablation-2026-10-12", "repro/README.md/"]);
+  });
+});
+
+describe("reproMessage — stands alone", () => {
+  it("a stray entry: what it is, where it goes, what repro/ holds, the rule's page", () => {
+    expect(
+      reproMessage({
+        path: "repro/run.py",
+        problem: "stray",
+        cure: SCRIPT_CURE,
+      }),
+    ).toBe(
+      [
+        `\`repro/run.py\` is loose at the top of the paper's repro/ folder, which holds only an index, the shared tools and data, and one dated folder per study. Where it goes: ${SCRIPT_CURE}.`,
+        "What repro/ holds (what interpreters and package managers leave there, like __pycache__/ and node_modules/, is never reported):",
+        "repro/",
+        "├── README.md           ← the index: one line per study",
+        "├── .gitignore          ← keeps the scripts' byproducts out of git",
+        "├── tools/              ← scripts used across the paper (numbers, figures, anonymity check, harnesses)",
+        "├── data/               ← shared data (tables, caches)",
+        "└── <slug>-YYYY-MM-DD/  ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)",
+        "    └── README.md       ← required: what it asks, how to run it, what it found",
+        "Rule repro/allowed-files-only: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/allowed-files-only.md",
+      ].join("\n"),
+    );
+  });
+
+  it("a study without its README.md: what to add", () => {
+    expect(
+      reproMessage({
+        path: "repro/x-2026-10/",
+        problem: "no-readme",
+        cure: "add it",
+      }),
+    ).toMatch(
+      /^`repro\/x-2026-10\/` is a study folder without a README\.md, and every study in repro\/ has one\. What to do: add it\.\nWhat repro\/ holds/,
+    );
+  });
+});

package/src/domain/repro-layout.ts

@@ -0,0 +1,311 @@
+/**
+ * THE LAYOUT OF A PAPER'S `repro/` — what may stand at its top, and nothing else.
+ *
+ * `repro/` is where a paper's evidence lives, and it fills up the way a desk does: one real paper had
+ * 120 entries at its top, about 70 study folders (some with no date) and about 50 loose scripts, data
+ * files and notes. Nobody could say which script produces which number, which study is current, or
+ * where a new run goes. The layout gives each kind of material one place:
+ *
+ *   repro/
+ *   ├── README.md              the index: one line per study
+ *   ├── <slug>-YYYY-MM-DD/     one folder per study or spike, with a README.md inside
+ *   ├── tools/                 scripts used across the paper (numbers, figures, anonymity check, harnesses)
+ *   └── data/                  shared data (tables, caches)
+ *
+ * plus `.gitignore`. A loose note belongs in its study's folder or in the paper's `research/`.
+ *
+ * ── THE DATE IN A STUDY'S NAME ────────────────────────────────────────────────────
+ * `<slug>-YYYY-MM-DD` is the day the study began. `<slug>-YYYY-MM` is accepted too: a study that ran
+ * over weeks (labelling, a reading of a corpus) has a month as its honest date, and both forms sort
+ * by time. The date must be a real one (no month 13, no 30 February). The slug is lowercase letters
+ * and digits in words joined by single hyphens.
+ *
+ * ── NEVER REPORTED ───────────────────────────────────────────────────────────────
+ * What interpreters, package managers and the operating system leave in any folder they run in
+ * (`__pycache__/`, `node_modules/`, `.DS_Store`, …): the scripts' byproducts, not the author's.
+ *
+ * Pure: the caller lists the folder and says which study folders hold a `README.md`.
+ */
+import { extname } from "node:path";
+import { leaf, renderTree, type TreeNode } from "./layout-tree.ts";
+
+/** The folder this layout governs, at the paper folder's root. */
+export const REPRO_DIR = "repro";
+
+/** The index at the top of `repro/`, and the file every study folder holds. */
+export const README = "README.md";
+
+/** The files `repro/` may hold at its top, by exact name. */
+export const REPRO_FILE_NOTES: readonly {
+  readonly name: string;
+  readonly note: string;
+}[] = [
+  { name: README, note: "the index: one line per study" },
+  { name: ".gitignore", note: "keeps the scripts' byproducts out of git" },
+];
+export const REPRO_FILES: readonly string[] = REPRO_FILE_NOTES.map(
+  (f) => f.name,
+);
+
+/** The shared folders `repro/` may hold besides its study folders. */
+export const TOOLS_DIR = "tools";
+export const DATA_DIR = "data";
+export const REPRO_DIR_NOTES: readonly {
+  readonly name: string;
+  readonly note: string;
+}[] = [
+  {
+    name: TOOLS_DIR,
+    note: "scripts used across the paper (numbers, figures, anonymity check, harnesses)",
+  },
+  { name: DATA_DIR, note: "shared data (tables, caches)" },
+];
+export const REPRO_DIRS: readonly string[] = REPRO_DIR_NOTES.map((d) => d.name);
+
+/** The study folder as the layout draws it: the name pattern, and the README.md it must hold. */
+const STUDY_NODE: TreeNode = {
+  name: "<slug>-YYYY-MM-DD/",
+  note: "one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)",
+  children: [
+    leaf(README, "required: what it asks, how to run it, what it found"),
+  ],
+};
+
+/** The layout of `repro/`, entry by entry. */
+export const REPRO_NODES: readonly TreeNode[] = [
+  ...REPRO_FILE_NOTES.map((f) => leaf(f.name, f.note)),
+  ...REPRO_DIR_NOTES.map((d) => leaf(`${d.name}/`, d.note)),
+  STUDY_NODE,
+];
+
+/** The drawing of `repro/`'s layout: the rule's message, the hook's refusal, the rule's page. */
+export const REPRO_LAYOUT_TREE: string = renderTree(
+  `${REPRO_DIR}/`,
+  REPRO_NODES,
+);
+
+/**
+ * What interpreters, package managers, test runners and the operating system write into the folder
+ * they run in. Never reported, whether a file or a folder.
+ */
+export const REPRO_BYPRODUCTS: readonly string[] = [
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+  ".ipynb_checkpoints",
+  "node_modules",
+  ".venv",
+  ".DS_Store",
+  "Thumbs.db",
+];
+
+/** A study's name: a slug, then the year, the month, and optionally the day it began. */
+const STUDY_NAME = /^([a-z0-9]+(?:-[a-z0-9]+)*)-(\d{4})-(\d{2})(?:-(\d{2}))?$/u;
+
+const isLeapYear = (y: number): boolean =>
+  (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+
+/** The days in month `m` (1–12) of year `y`. */
+const daysIn = (y: number, m: number): number =>
+  m === 2 ? (isLeapYear(y) ? 29 : 28) : [4, 6, 9, 11].includes(m) ? 30 : 31;
+
+/** Whether `name` is a study folder's: `<slug>-YYYY-MM-DD` or `<slug>-YYYY-MM`, a real date. */
+export function isStudyName(name: string): boolean {
+  const m = STUDY_NAME.exec(name);
+  if (m === null) return false;
+  const year = Number(m[2]);
+  const month = Number(m[3]);
+  const day = m[4] === undefined ? 1 : Number(m[4]);
+  return month >= 1 && month <= 12 && day >= 1 && day <= daysIn(year, month);
+}
+
+/**
+ * The study name to suggest for a folder named `name`: its name as a slug, with the date to fill in.
+ * A name that becomes a study name once lowercased and hyphenated is suggested as it is.
+ */
+export function suggestedStudyName(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  if (isStudyName(slug)) return slug;
+  const base = slug.replace(/(?:^|-)\d{4}(?:-\d{1,2}){0,2}$/u, "");
+  return `${base === "" ? "<slug>" : base}-YYYY-MM-DD`;
+}
+
+/** The extensions of a script: what a study or the paper's build runs. */
+export const SCRIPT_EXTENSIONS: readonly string[] = [
+  ".py",
+  ".ipynb",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".mts",
+  ".cts",
+  ".r",
+  ".jl",
+  ".rb",
+  ".pl",
+  ".awk",
+  ".sql",
+];
+
+/** Names without a script's extension that still say how the tools run. */
+export const TOOL_FILES: readonly string[] = [
+  "Makefile",
+  "Dockerfile",
+  "requirements.txt",
+  "pyproject.toml",
+  "uv.lock",
+  "package.json",
+  "package-lock.json",
+];
+
+/** The extensions of data: tables, records, caches, archives, raw output. */
+export const DATA_EXTENSIONS: readonly string[] = [
+  ".tsv",
+  ".csv",
+  ".json",
+  ".jsonl",
+  ".ndjson",
+  ".yaml",
+  ".yml",
+  ".xml",
+  ".txt",
+  ".log",
+  ".parquet",
+  ".sqlite",
+  ".db",
+  ".xlsx",
+  ".npy",
+  ".npz",
+  ".pkl",
+  ".gz",
+  ".zip",
+  ".tar",
+];
+
+/** The extensions of a note. */
+export const NOTE_EXTENSIONS: readonly string[] = [".md", ".markdown"];
+
+/** Where a script goes. */
+export const SCRIPT_CURE =
+  "repro/tools/ — the scripts used across the paper (numbers, figures, the anonymity check, harnesses); a script only one study runs goes in that study's folder instead";
+
+/** Where data goes. */
+export const DATA_CURE =
+  "repro/data/ — the data shared across the paper (tables, caches); what one study's run produced goes in that study's folder instead";
+
+/** Where a note goes. */
+export const NOTE_CURE =
+  "the dated folder of the study it is about (repro/<slug>-YYYY-MM-DD/), or the paper's research/ when it is research or a decision rather than the record of a run";
+
+/** Where a file of any other kind goes. */
+export const FILE_CURE_BY_KIND =
+  "decide by what it is — a script → repro/tools/; data → repro/data/; a note → the dated folder of its study, or the paper's research/; what one study produced → that study's folder";
+
+/** The files paperlint itself once kept at the top of `repro/`, each with where it is read now. */
+export const MOVED_FILES: readonly {
+  readonly name: string;
+  readonly cure: string;
+}[] = [
+  {
+    name: "references-cache.json",
+    cure: "repro/data/references-cache.json, where `paperlint build` reads and writes the citation services' answers (`git mv repro/references-cache.json repro/data/`); until it is moved, the next build asks every service again",
+  },
+  {
+    name: "refs-cache.json",
+    cure: "repro/data/refs-cache.json, where the paper-pipeline's extract-ref-facts script keeps its raw answers (`git mv repro/refs-cache.json repro/data/`)",
+  },
+  {
+    name: "generated-code-grandfathered.txt",
+    cure: "repro/tools/generated-code-grandfathered.txt, where the paper-pipeline's generated-code check reads it (`git mv repro/generated-code-grandfathered.txt repro/tools/`)",
+  },
+];
+
+/** Where a stray file goes: a file paperlint moved, else by the kind its name says. */
+function fileCure(name: string): string {
+  const moved = MOVED_FILES.find((f) => f.name === name);
+  if (moved !== undefined) return moved.cure;
+  const ext = extname(name).toLowerCase();
+  if (TOOL_FILES.includes(name) || SCRIPT_EXTENSIONS.includes(ext))
+    return SCRIPT_CURE;
+  if (DATA_EXTENSIONS.includes(ext)) return DATA_CURE;
+  if (NOTE_EXTENSIONS.includes(ext)) return NOTE_CURE;
+  return FILE_CURE_BY_KIND;
+}
+
+/** Where a folder with no study name goes: renamed as a study, or emptied into the shared folders. */
+const folderCure = (name: string): string =>
+  `rename it to \`${suggestedStudyName(name)}\`, one folder per study or spike, named for what it is and the date it began — the date of its first commit is a fine default (\`git log --reverse --format=%as -- repro/${name} | head -1\`, run in the paper folder) — and give it a README.md; if it holds scripts or data shared across the paper instead, move them into repro/tools/ or repro/data/`;
+
+/** An entry at the top of `repro/`: a file or a folder, and for a folder whether it holds a README.md. */
+export interface ReproEntry {
+  readonly name: string;
+  readonly kind: "file" | "dir";
+  readonly hasReadme: boolean;
+}
+
+/** What is wrong with an entry at the top of `repro/`. */
+export interface ReproFinding {
+  /** The entry's path from the paper folder; a folder's ends in a slash. */
+  readonly path: string;
+  /** `stray`: not part of the layout. `no-readme`: a study folder without its README.md. */
+  readonly problem: "stray" | "no-readme";
+  /** Where it goes, or what to add. */
+  readonly cure: string;
+}
+
+const isAllowed = (e: ReproEntry): boolean =>
+  REPRO_BYPRODUCTS.includes(e.name) ||
+  (e.kind === "file"
+    ? REPRO_FILES.includes(e.name)
+    : REPRO_DIRS.includes(e.name) || isStudyName(e.name));
+
+/** The one finding for `e`, or null when it is in its place. */
+function judgeEntry(e: ReproEntry): ReproFinding | null {
+  const path = `${REPRO_DIR}/${e.name}${e.kind === "dir" ? "/" : ""}`;
+  if (!isAllowed(e))
+    return {
+      path,
+      problem: "stray",
+      cure: e.kind === "dir" ? folderCure(e.name) : fileCure(e.name),
+    };
+  if (e.kind === "dir" && isStudyName(e.name) && !e.hasReadme)
+    return {
+      path,
+      problem: "no-readme",
+      cure: `add ${path}${README} — what the study asks, how to run it, what it found — and a line for it in repro/${README}`,
+    };
+  return null;
+}
+
+/** The entries at the top of `repro/` that are out of place, at most one finding each, in order. Pure. */
+export function judgeRepro(
+  entries: readonly ReproEntry[],
+): readonly ReproFinding[] {
+  return entries.map(judgeEntry).filter((f): f is ReproFinding => f !== null);
+}
+
+/**
+ * The one text a finding is reported with, by the rule `repro/allowed-files-only` and by the hook that fires
+ * when such an entry is written. It stands alone: what is wrong, where the entry goes, and what
+ * `repro/` holds, for a reader who knows nothing of paperlint.
+ */
+export function reproMessage(f: ReproFinding): string {
+  const head =
+    f.problem === "stray"
+      ? `\`${f.path}\` is loose at the top of the paper's repro/ folder, which holds only an index, the shared tools and data, and one dated folder per study. Where it goes: ${f.cure}.`
+      : `\`${f.path}\` is a study folder without a ${README}, and every study in repro/ has one. What to do: ${f.cure}.`;
+  return [
+    head,
+    "What repro/ holds (what interpreters and package managers leave there, like __pycache__/ and node_modules/, is never reported):",
+    REPRO_LAYOUT_TREE,
+    `Rule repro/allowed-files-only: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/allowed-files-only.md`,
+  ].join("\n");
+}

package/src/domain/scaffold-layout.ts

@@ -0,0 +1,104 @@
+/**
+ * WHAT `paperlint new` PUTS IN A NEW PAPER FOLDER BESIDE ITS THREE FILES — the layout, visible from the
+ * first commit.
+ *
+ * The rules `paper/allowed-files-only` and `repro/allowed-files-only` say where every kind of material goes. A
+ * paper that starts with three files shows none of it, and the first reviewer's report, the first
+ * figure and the first script each land loose at the root. So a new folder already holds the places.
+ *
+ * ── ONE SOURCE OF TRUTH ──────────────────────────────────────────────────────────
+ * Nothing here lists a folder by hand. The folders are `ROOT_DIR_NOTES` (paper-layout.ts) minus the
+ * ones named in `NOT_SCAFFOLDED`, each with its reason; `repro/` gets its own shared folders from
+ * `REPRO_DIR_NOTES`. A folder added to the layout is scaffolded unless someone writes down why not,
+ * and a test fails on an excluded name the layout no longer has.
+ *
+ * ── `.gitkeep` ───────────────────────────────────────────────────────────────────
+ * Git keeps files, not folders: an empty folder is not in the first commit, which is the point of
+ * scaffolding. A folder that holds nothing else gets a `.gitkeep`; a folder that holds a real file
+ * (`repro/` with its README.md) gets none. `.gitkeep` is the convention, not a paperlint file, and no
+ * rule reads it: `paper/stages` looks for `*.pdf` in `versions/`, the review and sibling rules lint
+ * `*.md`, `repro/allowed-files-only` judges the top of `repro/` only, and neither `tools/` nor `data/` is
+ * listed by any rule.
+ *
+ * Pure: a list of paths and texts, written by `new-paper.ts`.
+ */
+import { ROOT_DIR_NOTES } from "./paper-layout.ts";
+import {
+  DATA_DIR,
+  README,
+  REPRO_DIR,
+  REPRO_DIR_NOTES,
+  TOOLS_DIR,
+} from "./repro-layout.ts";
+
+/** The placeholder git needs to keep an otherwise empty folder. */
+export const GITKEEP = ".gitkeep";
+
+/**
+ * The folders of the layout that `paperlint new` does not create, each with why. A folder here is
+ * allowed at the root all the same; it appears when the work needs it.
+ */
+export const NOT_SCAFFOLDED: readonly {
+  readonly name: string;
+  readonly why: string;
+}[] = [
+  {
+    name: "_build",
+    why: "`paperlint build` writes it, and an empty one would claim a build that never ran",
+  },
+  {
+    name: "siblings",
+    why: "a card is written when a close competitor turns up (skill analyze-sibling-paper, which also writes the folder's README.md index); a paper may have none, and an empty folder reads as an unfinished analysis",
+  },
+  {
+    name: "sections",
+    why: "the body is split only when it outgrows `paper.tex`; the stub is one file, and an empty `sections/` suggests the split is expected",
+  },
+  {
+    name: "talk",
+    why: "only a paper that declares a talk (`talk` in paperlint.json) has one, and its folder is the declared `talk.dir`, which need not be `talk/`",
+  },
+  {
+    name: "extra",
+    why: "the escape hatch for material nothing else takes; it is never judged, so it has no place in a layout meant to be filled by kind",
+  },
+];
+
+/** The folders at the paper's root that a new paper holds from the first commit, in layout order. */
+export const SCAFFOLD_DIRS: readonly string[] = ROOT_DIR_NOTES.map(
+  (d) => d.name,
+).filter((name) => !NOT_SCAFFOLDED.some((n) => n.name === name));
+
+/**
+ * The stub index of `repro/`: it makes the folder non-empty (no `.gitkeep`) and says what the rule
+ * asks of it. A line per study is added when the first study is.
+ */
+export const REPRO_INDEX_STUB = `# Reproduction index
+
+One line per study: \`<slug>-YYYY-MM-DD/\` — what it asks and what it found. Scripts used across the
+paper go in \`${TOOLS_DIR}/\`, shared data in \`${DATA_DIR}/\`.
+`;
+
+/** A file `paperlint new` writes into a new paper folder, with its path from that folder. */
+export interface ScaffoldFile {
+  readonly path: string;
+  readonly text: string;
+}
+
+/**
+ * Every file of the layout scaffold, relative to the paper folder, in a fixed order: a `.gitkeep` in
+ * each empty folder, and `repro/README.md` where `repro/` would otherwise hold only folders.
+ */
+export const SCAFFOLD_FILES: readonly ScaffoldFile[] = [
+  ...SCAFFOLD_DIRS.flatMap((dir): readonly ScaffoldFile[] =>
+    dir === REPRO_DIR
+      ? [
+          { path: `${REPRO_DIR}/${README}`, text: REPRO_INDEX_STUB },
+          ...REPRO_DIR_NOTES.map((d) => ({
+            path: `${REPRO_DIR}/${d.name}/${GITKEEP}`,
+            text: "",
+          })),
+        ]
+      : [{ path: `${dir}/${GITKEEP}`, text: "" }],
+  ),
+];