paperlint 9.0.1 → 10.1.0

package/src/folder-layout-rule.ts

@@ -0,0 +1,151 @@
+/**
+ * `paper/allowed-files-only` — the root of a paper folder holds only paperlint's own files and folders.
+ *
+ * What may stand there, and why each entry, is `src/domain/paper-layout.ts` (the one list) and
+ * docs/rules/paper/allowed-files-only.md. This file reads the folder and the paper's settings, and reports.
+ *
+ * ── WHY A RULE THAT LISTS A DIRECTORY ───────────────────────────────────────────
+ * A structure linter over file NAMES (ls-lint, ESLint's `project-structure`) judges the files handed
+ * to it, and ESLint is handed only the files paperlint lints: a stray `.pdf`, `.py` or `.md` is never
+ * one of them, so a rule fired per file cannot see it. Listing the folder is one `readdir`; a rule is
+ * plain JS and may do it (root CLAUDE.md, "Measure before calling it impossible").
+ *
+ * ── WHICH FILE IT REPORTS ON ─────────────────────────────────────────────────────
+ * The folder is not a file ESLint lints; `PIPELINE-STATUS.md` is, in every paper (`paperlint lint`
+ * requires it, `paperlint new` writes it). Each stray entry is one finding on its first line, the
+ * place `paper/folder-venue-leftover` reports for the same reason.
+ *
+ * ── WHAT THE SETTINGS ADD ────────────────────────────────────────────────────────
+ * `pdf`, `talk.dir`, and a preset file of the paper's own (`extends`, or any cycle's) may name an
+ * entry at the root; each such entry is allowed while the settings name it. Settings that do not parse
+ * add nothing: `paperlint lint` refuses them before ESLint runs, and `pdf/profile` names the problem.
+ */
+import { basename, dirname, join, posix, relative, resolve } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  judgeLayout,
+  strayMessage,
+  type LayoutEntry,
+} from "./domain/paper-layout.ts";
+import type {
+  FolderRuleContext,
+  FolderRuleModule,
+} from "./folder-venue-rule.ts";
+import { readPaperSettings, type PaperSettings } from "./paper-settings.ts";
+import type { Files } from "./ports/files.ts";
+import type { ListDir } from "./ports/talk-media.ts";
+import { rulePageUrl } from "./venue-rules.ts";
+
+const STATUS_FILE = "PIPELINE-STATUS.md";
+
+/** What the rule reads with: the disk, and the names in a directory. */
+export interface FolderLayoutDeps {
+  readonly files: Files;
+  readonly listDir: ListDir;
+}
+
+/** The first segment of `p`, relative to the paper folder `dir`; null when it is not inside it. */
+function rootOf(dir: string, p: string): string | null {
+  const first = relative(dir, resolve(dir, p)).split(/[\\/]/, 1).join("");
+  return first === "" || first === ".." ? null : first;
+}
+
+/** A preset spec that names a file (`./venue.jsonc`), not a shipped preset (`paperlint:aidc`). */
+const isPresetFile = (spec: string): boolean =>
+  spec.startsWith("./") || spec.startsWith("../");
+
+/** Every path the settings name relative to the paper: the PDF, the talk folder, its preset files. */
+const pathsOf = (s: PaperSettings): readonly string[] => [
+  ...(s.pdf === null ? [] : [s.pdf]),
+  ...(s.talk === null ? [] : [s.talk.dir]),
+  ...[
+    s.extends,
+    ...(s.cycles?.list ?? []).map((c) =>
+      c.venue.kind === "preset" ? c.venue.extends : null,
+    ),
+  ].filter((spec): spec is string => spec !== null && isPresetFile(spec)),
+];
+
+/** What the paper's settings name at the root of `dir`, each once; none without readable settings. */
+export function declaredRoots(dir: string, files: Files): readonly string[] {
+  const read = readPaperSettings(files, dir);
+  if (!read.ok || read.value === null) return [];
+  return [
+    ...new Set(
+      pathsOf(read.value)
+        .map((p) => rootOf(dir, posix.normalize(p)))
+        .filter((r): r is string => r !== null),
+    ),
+  ];
+}
+
+/** The folder's root entries, each a file or a folder. */
+const entriesOf = (
+  dir: string,
+  deps: FolderLayoutDeps,
+): readonly LayoutEntry[] =>
+  [...deps.listDir(callerPath(dir))].sort().map((name) => ({
+    name,
+    kind: deps.files.isFile(callerPath(join(dir, name))) ? "file" : "dir",
+  }));
+
+/**
+ * The text of each stray entry among `entries` of the paper folder `dir` — THE one function behind
+ * both the rule and the `paper-folder-layout` hook (`src/folder-layout-hook.ts`), so the two cannot
+ * disagree about what is allowed or what to say.
+ */
+export const strayTexts = (
+  dir: string,
+  entries: readonly LayoutEntry[],
+  files: Files,
+): readonly string[] =>
+  judgeLayout(entries, { roots: declaredRoots(dir, files) }).map(strayMessage);
+
+const META: FolderRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "the paper folder's root holds only paperlint's own files and folders; anything else goes into the folder for its kind, or extra/",
+    url: rulePageUrl("paper/allowed-files-only"),
+  },
+  schema: [],
+  messages: {
+    // The whole text is `strayMessage` (src/domain/paper-layout.ts), the one the hook that fires on
+    // writing such an entry sends too.
+    stray: "{{text}}",
+  },
+};
+
+/** The rule, reading the folder and the paper's settings through `deps`. */
+export function folderLayoutRules(
+  deps: FolderLayoutDeps,
+): Readonly<Record<"allowed-files-only", FolderRuleModule>> {
+  return {
+    "allowed-files-only": {
+      meta: META,
+      create(context: FolderRuleContext) {
+        if (basename(context.filename) !== STATUS_FILE) return {};
+        return {
+          root() {
+            const dir = dirname(context.filename);
+            const at = context.sourceCode.getLocFromIndex(0);
+            strayTexts(dir, entriesOf(dir, deps), deps.files).forEach(
+              (text) => {
+                context.report({
+                  loc: { start: at, end: at },
+                  messageId: "stray",
+                  data: { text },
+                });
+              },
+            );
+          },
+        };
+      },
+    },
+  };
+}
+
+/** The level it is on at in paperlint's own config, for every paper's `PIPELINE-STATUS.md`. */
+export const FOLDER_LAYOUT_RULE_LEVELS: Readonly<
+  Record<"paper/allowed-files-only", "error">
+> = { "paper/allowed-files-only": "error" };

package/src/hooks-settings.harness.ts

@@ -1,5 +1,5 @@
 /**
- * Both halves for `hooks-settings.ts` — the three hooks written into `.claude/settings.json`.
+ * Both halves for `hooks-settings.ts` — the four hooks written into `.claude/settings.json`.
  *
  * The merge under test is vigiles' REAL one (`vigiles/claude-code`), not a stand-in: the claims
  * that matter — a user's hook in the same matcher survives, a second run is byte-identical — are
@@ -65,9 +65,9 @@ check(
 // ── the one source: plugin/hooks/hooks.json ─────────────────────────────────────────────
 const wiring = shippedWiring();
 check(
-  "the hook names are DERIVED from hooks.json — three, in its order",
+  "the hook names are DERIVED from hooks.json — four, in its order",
   wiring.names.join() ===
-    "paper-edit-guard,paper-skills-nudge,paper-status-gates",
+    "paper-edit-guard,paper-folder-layout,paper-skills-nudge,paper-status-gates",
 );
 // ── settings written by hand: shapes Claude Code would ignore are skipped, not crashed on ──
 check(
@@ -194,7 +194,7 @@ try {
     const r = wireHooks(dir, merge, wiring);
     const s = settingsIn(dir);
     check(
-      "no settings file → it is created with the three hooks",
+      "no settings file → it is created with the four hooks",
       r.status === "written" &&
         wiredCounts(s, wiring.names).every(
           (c) => c.ours === 1 && c.other === 0,
@@ -283,7 +283,8 @@ try {
     check(
       "and names the hooks that are not wired in ANY form",
       r.status === "foreign" &&
-        r.missing.join() === "paper-skills-nudge,paper-status-gates",
+        r.missing.join() ===
+          "paper-folder-layout,paper-skills-nudge,paper-status-gates",
     );
     // The control: without the check, vigiles' merge WOULD add a second copy. This is the
     // reason the check exists, measured rather than asserted.
@@ -319,13 +320,13 @@ try {
   const wiredOnce = merge({}, wiring.compiled, MANAGED_BY);
   check(
     "wired once each → ✓ wired, with the fresh-clone consequence",
-    /✓ wired — paper-edit-guard, paper-skills-nudge, paper-status-gates, once each/.test(
+    /✓ wired — paper-edit-guard, paper-folder-layout, paper-skills-nudge, paper-status-gates, once each/.test(
       doc(wiredOnce),
     ) && /cannot run until `npm install`/.test(doc(wiredOnce)),
   );
   check(
     "nothing wired → ⚠ not wired, with the remedy",
-    /⚠ not wired — none of the 3 hooks/.test(doc({})),
+    /⚠ not wired — none of the 4 hooks/.test(doc({})),
   );
   const twice = PreToolUseSettings.parse(structuredClone(wiredOnce));
   twice.hooks.PreToolUse[0]?.hooks.push({
@@ -353,7 +354,7 @@ try {
   });
   check(
     "🔴 partly wired BY HAND → the remedy is NOT `npx paperlint init`, which would refuse to write",
-    /partly wired — missing: paper-skills-nudge, paper-status-gates/.test(
+    /partly wired — missing: paper-folder-layout, paper-skills-nudge, paper-status-gates/.test(
       handPartial,
     ) && /writes nothing then/.test(handPartial),
   );

package/src/init.ts

@@ -691,7 +691,7 @@ function papersLines(decl: DeclarationResult, why: string): string[] {
   ];
 }
 
-// Documented in README.md#install-and-set-up — update it when this changes.
+// Documented in README.md#-getting-started and docs/install.md — update them when this changes.
 export async function init(
   dir: string,
   opts: InitOptions = {},

package/src/layout-docs.test.ts

@@ -0,0 +1,52 @@
+/**
+ * The pages draw the layout the code enforces. Each page embeds the drawing between
+ * `<!-- layout:begin … -->` and `<!-- layout:end -->`, and that block must equal the render of the
+ * constants that decide what is allowed (`PAPER_LAYOUT_TREE`, `REPRO_LAYOUT_TREE`, and
+ * `PAPERS_LAYOUT_TREE`, which draws the paper folder beside the venues' corpora) — so a page cannot
+ * show an entry the rule reports, or miss one it allows. Both halves: the committed pages match, and
+ * a page with one entry changed or with no block at all does not.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import {
+  PAPER_LAYOUT_TREE,
+  PAPERS_LAYOUT_TREE,
+} from "./domain/paper-layout.ts";
+import { REPRO_LAYOUT_TREE } from "./domain/repro-layout.ts";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const PAGES: readonly (readonly [string, string])[] = [
+  ["docs/rules/paper/allowed-files-only.md", PAPER_LAYOUT_TREE],
+  ["docs/rules/repro/allowed-files-only.md", REPRO_LAYOUT_TREE],
+  ["docs/layout.md", PAPERS_LAYOUT_TREE],
+];
+
+/** The drawing a page embeds, as its fenced block holds it; null when the page has no block. */
+function embedded(page: string): string | null {
+  const m =
+    /<!-- layout:begin[^\n]*-->\n\n```text\n([\s\S]*?)\n```\n\n<!-- layout:end -->/u.exec(
+      page,
+    );
+  return m === null ? null : (m[1] ?? null);
+}
+
+describe("the pages draw the layout the code enforces", () => {
+  it.each(PAGES)("%s embeds the current render", (path, tree) => {
+    expect(
+      embedded(readFileSync(join(ROOT, path), "utf8")),
+      `${path}: paste this between its layout markers:\n\n${tree}\n`,
+    ).toBe(tree);
+  });
+
+  it("a page whose drawing lost an entry differs from the render", () => {
+    const page = `<!-- layout:begin x -->\n\n\`\`\`text\n${PAPER_LAYOUT_TREE.replace(/\n[^\n]*extra\/[^\n]*/u, "")}\n\`\`\`\n\n<!-- layout:end -->\n`;
+    expect(embedded(page)).not.toBe(PAPER_LAYOUT_TREE);
+  });
+
+  it("a page with no block has no drawing", () => {
+    expect(embedded("# a page\n")).toBeNull();
+  });
+});

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