paperlint 9.0.0 → 10.0.0

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: "" }],
+  ),
+];

package/src/folder-layout-hook.test.ts

@@ -0,0 +1,214 @@
+/**
+ * The `paper-folder-layout` hook (`src/folder-layout-hook.ts`): a PreToolUse payload in, Claude Code's
+ * refusal out. Both halves: it denies creating a new entry the layout does not allow — at a paper
+ * folder's root or at the top of its `repro/`, and a study folder whose first file is not its
+ * README.md — with the rule's own text; it allows every existing file, every new file inside an
+ * existing entry, every allowed new entry, and anything outside a paper folder.
+ */
+import { describe, expect, it } from "vitest";
+import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
+import {
+  folderLayoutHook,
+  paperFolderOf,
+  writtenPath,
+} from "./folder-layout-hook.ts";
+import { folderLayoutRules } from "./folder-layout-rule.ts";
+import { reproLayoutRules } from "./repro-layout-rule.ts";
+
+const DIR = "/work/papers/p";
+const PAPER = {
+  [`${DIR}/PIPELINE-STATUS.md`]: "# status\n",
+  [`${DIR}/paper.tex`]: "\\documentclass{article}\n",
+  [`${DIR}/paperlint.json`]: "{}\n",
+};
+
+/** A Write of `file`, which does not exist unless `tree` holds it, into the paper. */
+const writing = (
+  file: string,
+  tree: Record<string, string> = {},
+  tool = "Write",
+) => {
+  const files = memoryFiles({ ...PAPER, ...tree });
+  return folderLayoutHook(
+    {
+      hook_event_name: "PreToolUse",
+      tool_name: tool,
+      tool_input: { file_path: file },
+      cwd: "/work",
+    },
+    { files, listDir: memoryListDir(files) },
+  );
+};
+
+/** The reason a refusal gives, or null when the write is allowed. */
+const reason = (
+  file: string,
+  tree: Record<string, string> = {},
+  tool = "Write",
+): string | null =>
+  writing(file, tree, tool)?.hookSpecificOutput.permissionDecisionReason ??
+  null;
+
+/** What both rules report once `tree` is on disk, as message text. */
+function ruleSays(tree: Record<string, string>): string[] {
+  const files = memoryFiles({ ...PAPER, ...tree });
+  const deps = { files, listDir: memoryListDir(files) };
+  const out: string[] = [];
+  const report = (d: { readonly data: Record<string, unknown> }) =>
+    out.push(String(d.data["text"]));
+  const at = { getLocFromIndex: () => ({ line: 1, column: 0 }) };
+  const filename = `${DIR}/PIPELINE-STATUS.md`;
+  folderLayoutRules(deps)
+    ["allowed-files-only"].create({ filename, sourceCode: at, report })
+    .root?.();
+  reproLayoutRules(deps)
+    ["allowed-files-only"].create({ filename, sourceCode: at, report })
+    .root?.();
+  return out;
+}
+
+describe("paper-folder-layout hook — denies a new stray entry", () => {
+  it("a new PLAN.md at the root: a PreToolUse deny, the rule's text exactly", () => {
+    const out = writing(`${DIR}/PLAN.md`);
+    expect(out).toEqual({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: ruleSays({ [`${DIR}/PLAN.md`]: "x" })[0],
+      },
+    });
+    expect(out?.hookSpecificOutput.permissionDecisionReason).toMatch(
+      /^`PLAN\.md` is at the root of a paper folder.*\n<paper>\/\n/su,
+    );
+  });
+
+  it("a file that would create a root folder the layout does not allow, naming the folder", () => {
+    expect(reason(`${DIR}/archive/2026/old.pdf`)).toBe(
+      ruleSays({ [`${DIR}/archive/2026/old.pdf`]: "x" })[0],
+    );
+  });
+
+  it("a loose script at the top of repro/, and an undated folder there", () => {
+    expect(reason(`${DIR}/repro/run.py`)).toBe(
+      ruleSays({ [`${DIR}/repro/run.py`]: "x" })[0],
+    );
+    expect(reason(`${DIR}/repro/run.py`)).toMatch(
+      /Where it goes: repro\/tools\//,
+    );
+    expect(
+      reason(`${DIR}/repro/baseline/run.py`, {
+        [`${DIR}/repro/README.md`]: "x",
+      }),
+    ).toMatch(/^`repro\/baseline\/` is loose at the top/);
+  });
+
+  it("a new study folder whose first file is not its README.md", () => {
+    expect(reason(`${DIR}/repro/ablation-2026-10-12/run.py`)).toMatch(
+      /^`repro\/ablation-2026-10-12\/` is a study folder without a README\.md/,
+    );
+  });
+
+  it("through an Edit and a MultiEdit too, and a path relative to the session's cwd", () => {
+    expect(reason(`${DIR}/NOTES-2.md`, {}, "Edit")).not.toBeNull();
+    expect(reason(`${DIR}/NOTES-2.md`, {}, "MultiEdit")).not.toBeNull();
+    const files = memoryFiles(PAPER);
+    expect(
+      folderLayoutHook(
+        { tool_input: { file_path: "papers/p/x.py" }, cwd: "/work" },
+        { files, listDir: memoryListDir(files) },
+      ),
+    ).not.toBeNull();
+  });
+});
+
+describe("paper-folder-layout hook — allows", () => {
+  it("🔴 any file that already exists, even one out of place: editing is never blocked", () => {
+    expect(reason(`${DIR}/PLAN.md`, { [`${DIR}/PLAN.md`]: "x" })).toBeNull();
+    expect(
+      reason(`${DIR}/repro/run.py`, { [`${DIR}/repro/run.py`]: "x" }),
+    ).toBeNull();
+  });
+
+  it("a new file inside an entry that already exists, even a stray one — the rule reports the entry", () => {
+    expect(
+      reason(`${DIR}/archive/new.pdf`, { [`${DIR}/archive/old.pdf`]: "x" }),
+    ).toBeNull();
+    expect(
+      reason(`${DIR}/repro/baseline/new.py`, {
+        [`${DIR}/repro/baseline/old.py`]: "x",
+      }),
+    ).toBeNull();
+  });
+
+  it("a new allowed entry: at the root, in an allowed folder, and in repro/'s layout", () => {
+    expect(reason(`${DIR}/NOTES.md`)).toBeNull();
+    expect(reason(`${DIR}/reviews/2026-10-12-x.md`)).toBeNull();
+    expect(reason(`${DIR}/extra/anything.bin`)).toBeNull();
+    expect(reason(`${DIR}/repro/README.md`)).toBeNull();
+    expect(reason(`${DIR}/repro/tools/paper_numbers.py`)).toBeNull();
+    expect(reason(`${DIR}/repro/data/numbers.tsv`)).toBeNull();
+  });
+
+  it("a new study folder started with its README.md, then any file in it", () => {
+    expect(reason(`${DIR}/repro/ablation-2026-10-12/README.md`)).toBeNull();
+    expect(
+      reason(`${DIR}/repro/ablation-2026-10-12/run.py`, {
+        [`${DIR}/repro/ablation-2026-10-12/README.md`]: "x",
+      }),
+    ).toBeNull();
+  });
+
+  it("🔴 anything under extra/, an archived paper with its own PIPELINE-STATUS.md included: lint never reads it", () => {
+    const snapshot = { [`${DIR}/extra/old/PIPELINE-STATUS.md`]: "# old\n" };
+    expect(reason(`${DIR}/extra/old/notes.txt`, snapshot)).toBeNull();
+    expect(
+      paperFolderOf(
+        `${DIR}/extra/old/notes.txt`,
+        memoryFiles({ ...PAPER, ...snapshot }),
+      ),
+    ).toBeNull();
+  });
+
+  it("a file outside every paper folder", () => {
+    expect(reason("/work/README.md")).toBeNull();
+    expect(reason("/work/papers/notes.md")).toBeNull();
+    expect(reason("/elsewhere/PLAN.md")).toBeNull();
+  });
+
+  it("a payload with no path it can read", () => {
+    const files = memoryFiles(PAPER);
+    const deps = { files, listDir: memoryListDir(files) };
+    expect(folderLayoutHook({}, deps)).toBeNull();
+    expect(folderLayoutHook({ tool_input: { file_path: 7 } }, deps)).toBeNull();
+    expect(folderLayoutHook(null, deps)).toBeNull();
+  });
+});
+
+describe("the cheap first step: the nearest folder holding PIPELINE-STATUS.md", () => {
+  const files = memoryFiles(PAPER);
+
+  it("is the paper folder for a file at its root or anywhere below", () => {
+    expect(paperFolderOf(`${DIR}/x.md`, files)).toBe(DIR);
+    expect(paperFolderOf(`${DIR}/a/b/c.md`, files)).toBe(DIR);
+  });
+
+  it("is null outside a paper folder, up to the file system's root", () => {
+    expect(paperFolderOf("/work/papers/x.md", files)).toBeNull();
+    expect(paperFolderOf("/x.md", files)).toBeNull();
+  });
+
+  it("reads the path from file_path, or notebook_path, made absolute against cwd", () => {
+    expect(writtenPath({ tool_input: { file_path: "/a/b.md" } })).toBe(
+      "/a/b.md",
+    );
+    expect(
+      writtenPath({ tool_input: { notebook_path: "n.ipynb" }, cwd: "/w" }),
+    ).toBe("/w/n.ipynb");
+    expect(writtenPath({ tool_input: {} })).toBeNull();
+    // A relative path needs an absolute cwd to mean anything: never the process's own.
+    expect(writtenPath({ tool_input: { file_path: "a.md" } })).toBeNull();
+    expect(
+      writtenPath({ tool_input: { file_path: "a.md" }, cwd: "w" }),
+    ).toBeNull();
+  });
+});