paperlint 9.0.1 → 10.0.0

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);

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

@@ -0,0 +1,114 @@
+/**
+ * `repro/allowed-files-only` (`src/repro-layout-rule.ts`) on paper folders held in memory, run the way
+ * ESLint runs it: `create`, then `root`. Both halves: each misplaced entry at the top of `repro/` is
+ * reported once, on the first line of `PIPELINE-STATUS.md`; the layout, a paper with no `repro/`, and
+ * any file but the scorecard are not.
+ */
+import { describe, expect, it } from "vitest";
+import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
+import { reproMessage, SCRIPT_CURE } from "./domain/repro-layout.ts";
+import {
+  REPRO_LAYOUT_RULE_LEVELS,
+  reproLayoutRules,
+} from "./repro-layout-rule.ts";
+
+const DIR = "/work/papers/p";
+const SCAFFOLD = {
+  [`${DIR}/PIPELINE-STATUS.md`]: "# status\n",
+  [`${DIR}/paper.tex`]: "\\documentclass{article}\n",
+};
+
+interface Reported {
+  readonly messageId: string;
+  readonly message: string;
+  readonly line: number;
+}
+
+/** The rule over the folder `tree` describes, reached through `file` (default the scorecard). */
+function lint(
+  tree: Readonly<Record<string, string>>,
+  file = `${DIR}/PIPELINE-STATUS.md`,
+): Reported[] {
+  const files = memoryFiles(tree);
+  const rule = reproLayoutRules({ files, listDir: memoryListDir(files) })[
+    "allowed-files-only"
+  ];
+  const out: Reported[] = [];
+  const visitor = rule.create({
+    filename: file,
+    sourceCode: { getLocFromIndex: () => ({ line: 1, column: 0 }) },
+    report: (d) => {
+      const template = rule.meta.messages[d.messageId] ?? "";
+      const message = Object.entries(d.data).reduce(
+        (m, [k, v]) => m.split(`{{${k}}}`).join(String(v)),
+        template,
+      );
+      out.push({ messageId: d.messageId, message, line: d.loc.start.line });
+    },
+  });
+  visitor.root?.();
+  return out;
+}
+
+describe("repro/allowed-files-only — reports", () => {
+  it("a loose script, once, on the first line, with the one text", () => {
+    expect(lint({ ...SCAFFOLD, [`${DIR}/repro/run.py`]: "x" })).toEqual([
+      {
+        messageId: "misplaced",
+        message: reproMessage({
+          path: "repro/run.py",
+          problem: "stray",
+          cure: SCRIPT_CURE,
+        }),
+        line: 1,
+      },
+    ]);
+  });
+
+  it("an undated folder and a study without a README.md, each once, in name order", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/repro/spike/x.py`]: "x",
+        [`${DIR}/repro/ablation-2026-10-12/run.py`]: "x",
+      }).map((r) => r.message.split(" ", 1).join("")),
+    ).toEqual(["`repro/ablation-2026-10-12/`", "`repro/spike/`"]);
+  });
+});
+
+describe("repro/allowed-files-only — silent", () => {
+  it("on the layout, whatever tools/, data/ and the studies hold", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/repro/README.md`]: "x",
+        [`${DIR}/repro/.gitignore`]: "x",
+        [`${DIR}/repro/tools/paper_numbers.py`]: "x",
+        [`${DIR}/repro/data/numbers.tsv`]: "x",
+        [`${DIR}/repro/data/references-cache.json`]: "{}",
+        [`${DIR}/repro/ablation-2026-10-12/README.md`]: "x",
+        [`${DIR}/repro/ablation-2026-10-12/loose.py`]: "x",
+        [`${DIR}/repro/human-labels-2026-10/README.md`]: "x",
+        [`${DIR}/repro/__pycache__/x.pyc`]: "x",
+      }),
+    ).toEqual([]);
+  });
+
+  it("on a paper with no repro/", () => {
+    expect(lint(SCAFFOLD)).toEqual([]);
+  });
+
+  it("on any file but PIPELINE-STATUS.md", () => {
+    expect(
+      lint({ ...SCAFFOLD, [`${DIR}/repro/run.py`]: "x" }, `${DIR}/paper.tex`),
+    ).toEqual([]);
+  });
+});
+
+describe("repro/allowed-files-only — level", () => {
+  it("is an error from the start", () => {
+    expect(REPRO_LAYOUT_RULE_LEVELS).toEqual({
+      "repro/allowed-files-only": "error",
+    });
+  });
+});

package/src/repro-layout-rule.ts

@@ -0,0 +1,121 @@
+/**
+ * `repro/allowed-files-only` — the top of a paper's `repro/` holds an index, the shared `tools/` and
+ * `data/`, and one dated folder per study, each with a `README.md`.
+ *
+ * What may stand there, and why, is `src/domain/repro-layout.ts` and docs/rules/repro/allowed-files-only.md.
+ * This file lists the folder and reports.
+ *
+ * ── WHY A RULE OF ITS OWN, NOT MORE OF `paper/allowed-files-only` ─────────────────────
+ * Each entry is judged by exactly one rule: `paper/allowed-files-only` judges the paper folder's root,
+ * where `repro/` is allowed, and this rule judges what is inside `repro/`. Neither reports an entry
+ * the other does, so a stray entry gets one message. A rule of its own also has its own page and its
+ * own switch: a paper whose `repro/` predates the layout can turn this one off and keep its root
+ * judged.
+ *
+ * ── WHICH FILE IT REPORTS ON ─────────────────────────────────────────────────────
+ * `PIPELINE-STATUS.md`, first line, like `paper/allowed-files-only`: every paper has it, and `repro/` may
+ * have no file ESLint lints at all.
+ */
+import { basename, dirname, join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  README,
+  REPRO_DIR,
+  judgeRepro,
+  reproMessage,
+  type ReproEntry,
+} from "./domain/repro-layout.ts";
+import type {
+  FolderRuleContext,
+  FolderRuleModule,
+} from "./folder-venue-rule.ts";
+import type { FolderLayoutDeps } from "./folder-layout-rule.ts";
+import type { Files } from "./ports/files.ts";
+import type { LayoutEntry } from "./domain/paper-layout.ts";
+import { rulePageUrl } from "./venue-rules.ts";
+
+const STATUS_FILE = "PIPELINE-STATUS.md";
+
+/** `entries` of `<dir>/repro/`, each folder with whether it holds a README.md. */
+const withReadme = (
+  dir: string,
+  entries: readonly LayoutEntry[],
+  files: Files,
+): readonly ReproEntry[] =>
+  entries.map((e) => ({
+    ...e,
+    hasReadme:
+      e.kind === "dir" &&
+      files.isFile(callerPath(join(dir, REPRO_DIR, e.name, README))),
+  }));
+
+/**
+ * The text of each finding among `entries` at the top of the paper folder `dir`'s `repro/` — THE one
+ * function behind both the rule and the `paper-folder-layout` hook, so the two cannot disagree.
+ */
+export const reproTexts = (
+  dir: string,
+  entries: readonly LayoutEntry[],
+  files: Files,
+): readonly string[] =>
+  judgeRepro(withReadme(dir, entries, files)).map(reproMessage);
+
+/** The entries at the top of `<dir>/repro/`, each a file or a folder; none without a `repro/`. */
+export const reproEntriesOf = (
+  dir: string,
+  deps: FolderLayoutDeps,
+): readonly LayoutEntry[] =>
+  [...deps.listDir(callerPath(join(dir, REPRO_DIR)))].sort().map((name) => ({
+    name,
+    kind: deps.files.isFile(callerPath(join(dir, REPRO_DIR, name)))
+      ? "file"
+      : "dir",
+  }));
+
+const META: FolderRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "the top of a paper's repro/ holds README.md, .gitignore, tools/, data/ and one <slug>-YYYY-MM-DD folder per study, each with a README.md",
+    url: rulePageUrl("repro/allowed-files-only"),
+  },
+  schema: [],
+  messages: {
+    // The whole text is `reproMessage` (src/domain/repro-layout.ts), the one the hook sends too.
+    misplaced: "{{text}}",
+  },
+};
+
+/** The rule, reading the folder through `deps`. */
+export function reproLayoutRules(
+  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);
+            reproTexts(dir, reproEntriesOf(dir, deps), deps.files).forEach(
+              (text) => {
+                context.report({
+                  loc: { start: at, end: at },
+                  messageId: "misplaced",
+                  data: { text },
+                });
+              },
+            );
+          },
+        };
+      },
+    },
+  };
+}
+
+/** The level it is on at in paperlint's own config, for every paper's `PIPELINE-STATUS.md`. */
+export const REPRO_LAYOUT_RULE_LEVELS: Readonly<
+  Record<"repro/allowed-files-only", "error">
+> = { "repro/allowed-files-only": "error" };

package/src/rule-cases.test.ts

@@ -39,6 +39,14 @@ const paper = (
   ...extra,
 });
 
+/** `study/declare-sample` is off by default; a paper turns it on in its `paperlint.json`. */
+const DECLARE_SAMPLE_ON: Readonly<Record<string, string>> = {
+  [`${P}/paperlint.json`]: JSON.stringify({
+    extends: null,
+    rules: { "study/declare-sample": "error" },
+  }),
+};
+
 // ── the venues: presets of the tree's own, never the shipped ones ──────────────────────────────
 //
 // A case judges a RULE, so every number it is sized against is written here, beside the facts and
@@ -693,6 +701,78 @@ const CASES: Readonly<Record<string, RuleCases>> = {
       ...onBlindConf("papers/blindconf-2026"),
     },
   },
+  // A plan beside the paper: the root holds only paperlint's own files and folders.
+  "paper/allowed-files-only": {
+    reports: {
+      tree: paper(tex("x"), { [`${P}/PLAN.md`]: "# plan\n" }),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same material where the layout puts it.
+    silent: paper(tex("x"), {
+      [`${P}/research/plan.md`]: "# plan\n",
+      [`${P}/extra/PLAN.md`]: "# plan\n",
+    }),
+  },
+  // A loose script at the top of repro/: it belongs in repro/tools/.
+  "repro/allowed-files-only": {
+    reports: {
+      tree: paper(tex("x"), { [`${P}/repro/run.py`]: "print(1)\n" }),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same script where the layout puts it, and a dated study with its README.md.
+    silent: paper(tex("x"), {
+      [`${P}/repro/README.md`]: "# repro\n",
+      [`${P}/repro/tools/run.py`]: "print(1)\n",
+      [`${P}/repro/ablation-2026-10-12/README.md`]: "# ablation\n",
+    }),
+  },
+  // A study's prereg.json that declares none of population, strata, screens, coverage, author_check.
+  // Off by default: the paper turns it on, as both trees do.
+  "study/declare-sample": {
+    reports: {
+      tree: paper(tex("x"), {
+        ...DECLARE_SAMPLE_ON,
+        [`${P}/repro/README.md`]: "# repro\n",
+        [`${P}/repro/draw-2026-10-12/README.md`]: "# draw\n",
+        [`${P}/repro/draw-2026-10-12/prereg.json`]: JSON.stringify({
+          hypotheses: ["H1"],
+        }),
+      }),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same study, declaring them.
+    silent: paper(tex("x"), {
+      ...DECLARE_SAMPLE_ON,
+      [`${P}/repro/README.md`]: "# repro\n",
+      [`${P}/repro/draw-2026-10-12/README.md`]: "# draw\n",
+      [`${P}/repro/draw-2026-10-12/prereg.json`]: JSON.stringify({
+        hypotheses: ["H1"],
+        population: {
+          about: "rules in instruction files",
+          source: "a census, 2026-07-28",
+          size: 4210,
+        },
+        strata: { by: "rule type", values: ["crisp", "vague"] },
+        screens: [
+          { name: "fits one excerpt", removed: { crisp: 10, vague: 300 } },
+        ],
+        coverage: { share: 0.3, unreachable: ["vague"] },
+        author_check: {
+          who: "first author",
+          when: "2026-10-12",
+          units_seen: 12,
+          units_drawn: 12,
+          verdict: "representative",
+        },
+      }),
+    }),
+  },
   // EMNLP, a shipped venue's name (REALM's conference), in a BlindConf paper's text.
   "tex/venue-leftover": {
     reports: {
@@ -944,6 +1024,24 @@ describe("every registered rule has cases, and every case names a registered rul
   });
 });
 
+describe("study/declare-sample is off by default", () => {
+  it("is silent on an empty prereg.json until the paper turns it on", async () => {
+    const study = {
+      [`${P}/repro/README.md`]: "# repro\n",
+      [`${P}/repro/draw-2026-10-12/README.md`]: "# draw\n",
+      [`${P}/repro/draw-2026-10-12/prereg.json`]: "{}",
+    };
+    const ids = async (tree: Record<string, string>) =>
+      (await lintTree(tree)).map((m) => m.ruleId);
+    expect(await ids(paper(tex("x"), study))).not.toContain(
+      "study/declare-sample",
+    );
+    expect(
+      await ids(paper(tex("x"), { ...study, ...DECLARE_SAMPLE_ON })),
+    ).toContain("study/declare-sample");
+  });
+});
+
 /**
  * A case lints its tree through the whole CLI: a body long enough for a rate to be judged (2 000
  * words and more) takes seconds under coverage, on a machine running every suite at once.

package/templates/paper/PIPELINE-STATUS.md

@@ -13,7 +13,41 @@ Updated: <ISO>
 **Readiness verdict:** <one line — submit-ready? if not, the WORST failing gate first. Any failing
 gate caps "ready"; an accept probability alone is not a verdict.>
 
-**Gates at a glance (worst first — mark any failing gate ✗):** readability(persona stalls) <density/verdict> · structure(tighten-paper) <verdict> · claims-honest(claims) <clean?> · defects(panel) <accept-prob/decision> · writing <NN/60> · content(venue bar) <run?/levers>
+**Gates at a glance (worst first — mark any failing gate ✗):** readability(persona stalls) <density/verdict> · structure(tighten-paper) <verdict> · claims-honest(claims) <clean?> · defects(panel) <accept-prob/decision> · writing <NN/60> · content(strong-accept scorecard) <run?/mode>
+
+## Plan / now
+
+The paper's live plan: this file is the paper's one live-state file, so the plan lives here, not in a
+`PLAN.md` beside it (`paper/allowed-files-only` reports one). Rewrite this section as the plan changes; a
+decision's history goes to `research/` as a dated record.
+
+- **Now (<ISO date>):** <what is being worked on, and the next step>
+- **Decisions in force:** <the decision — who made it, ISO date, link to the record>
+- **Schedule:** <ISO date — milestone, in the author's own zone>
+
+## Strong-accept scorecard (M1–M10)
+
+Filled by `study-accepted-papers`: mode C scores every row, mode D checks M2 and M4 again. What each
+mechanism is, and what it is not, is that skill's `references/mechanisms.md`. The verdicts live only
+here; the dated report in `reviews/` keeps the reasoning and points here.
+
+Status: `pass` · `partial` · `fail` · `—` (not scored). A `fail` names an owner and either a plan or
+`accept ceiling: <why>`.
+
+| #   | mechanism                                       | status | evidence (file:line) | owner | plan or accept ceiling |
+| --- | ----------------------------------------------- | ------ | -------------------- | ----- | ---------------------- |
+| M1  | a non-model oracle under the headline           | —      | —                    | —     | —                      |
+| M2  | the claim is aimed at a belief stated on record | —      | —                    | —     | —                      |
+| M3  | the construct is the claim                      | —      | —                    | —     | —                      |
+| M4  | the denominator in the claim sentence, no drift | —      | —                    | —     | —                      |
+| M5  | a negative or "X alone" claim shape             | —      | —                    | —     | —                      |
+| M6  | the generalised-over factor is a column         | —      | —                    | —     | —                      |
+| M7  | the phenomenon measured directly                | —      | —                    | —     | —                      |
+| M8  | a reusable thing the field pays for once        | —      | —                    | —     | —                      |
+| M9  | relevance to every reviewer on the PC           | —      | —                    | —     | —                      |
+| M10 | where the paper's own result loses              | —      | —                    | —     | —                      |
+
+## Stages
 
 ### SETUP
 
@@ -22,18 +56,18 @@ gate caps "ready"; an accept probability alone is not a verdict.>
 | idea       | Validate idea                     | research-ideate       | ☐      | —    | —                                                                                                 | —         |
 | priorwork  | Map competitors                   | map-prior-work        | ☐      | —    | —                                                                                                 | siblings/ |
 | venue      | Pick venue                        | find-venue            | ☐      | —    | —                                                                                                 | —         |
-| venuebar   | Venue bar / levers                | study-accepted-papers | ☐      | —    | —                                                                                                 | —         |
+| venuebar   | What the venue rewards            | study-accepted-papers | ☐      | —    | —                                                                                                 | —         |
 | **access** | 🔴 **Can you physically submit?** | plan-paper-timeline   | ☐      | —    | account · profile ACTIVE since <ISO> · portal reachable · form fields known · artifact host known | —         |
 | schedule   | Schedule + calendar               | plan-paper-timeline   | ☐      | —    | —                                                                                                 | —         |
 | **frame**  | **Claim stated before the runs**  | argument-arc (frame)  | ☐      | —    | one paragraph: what will this paper claim?                                                        | —         |
 
 ### LOOP
 
-| id    | Work             | Skill           | Status | Date | Result | Open |
-| ----- | ---------------- | --------------- | ------ | ---- | ------ | ---- |
-| study | Study + artifact | build-benchmark | ☐      | —    | —      | —    |
-| draft | Draft            | draft-paper     | ☐      | —    | —      | —    |
-| arc   | Argument arc     | argument-arc    | ☐      | —    | —      | —    |
+| id    | Work             | Skill           | Status | Date | Result | Open   |
+| ----- | ---------------- | --------------- | ------ | ---- | ------ | ------ |
+| study | Study + artifact | build-benchmark | ☐      | —    | —      | repro/ |
+| draft | Draft            | draft-paper     | ☐      | —    | —      | —      |
+| arc   | Argument arc     | argument-arc    | ☐      | —    | —      | —      |
 
 ### CONTINUOUS