paperlint 9.0.0 → 10.0.0

package/src/folder-layout-hook.ts

@@ -0,0 +1,141 @@
+/**
+ * The `paper-folder-layout` hook — `paper/allowed-files-only` and `repro/allowed-files-only` BEFORE a file is
+ * created, not at the next lint. PreToolUse on `Edit|Write|MultiEdit` (`plugin/hooks/hooks.json`):
+ * when the file about to be written does not exist yet and would add an entry the layout does not
+ * allow — at a paper folder's root, or at the top of its `repro/` — the call is denied, and the
+ * reason is the rule's own message: where the entry goes, and the layout drawn. The agent writes it
+ * where it belongs instead, in the same turn.
+ *
+ * ── WHAT IT NEVER BLOCKS ─────────────────────────────────────────────────────────
+ * - A file that already exists. Editing is never refused, wherever the file is: a paper whose
+ *   folder predates the layout keeps working, and the rule reports what is out of place.
+ * - A new file inside an entry that already exists, even one the layout does not allow: the entry is
+ *   not new, and the rule reports it once, by name. Only a NEW entry is refused.
+ * - Anything outside a paper folder (no `PIPELINE-STATUS.md` above it).
+ * A new study folder in `repro/` is created with its `README.md` first: any other first file in it
+ * is refused with `repro/allowed-files-only`'s "without a README.md" message.
+ *
+ * ── WHAT IT CANNOT SEE ───────────────────────────────────────────────────────────
+ * A shell command (`mv`, `cp`, a script writing files) is not an Edit or a Write, and this hook never
+ * sees it. The guarantee is the lint: both rules fail `paperlint lint`, in CI, whatever wrote the
+ * entry. The hook only saves the round trip. It does not read the paper's `rules` either: a paper
+ * that switched a layout rule off is still refused a new stray entry.
+ *
+ * ── ONE FUNCTION PER RULE, NOT TWO LISTS ─────────────────────────────────────────
+ * The texts are `strayTexts` (`src/folder-layout-rule.ts`) and `reproTexts`
+ * (`src/repro-layout-rule.ts`), the functions the rules report with.
+ *
+ * ── WHY IT IS NOT A VIGILES PROGRAM LIKE ITS NEIGHBOURS (measured 2026-10-12, vigiles 38) ──────
+ * A shipped `.hook.mjs` may import nothing but `vigiles/hook` (`checkHookImports`), so it cannot call
+ * this package's function; its only way to a tool is `run()`, whose output reaches stderr and never
+ * the hook's answer (`paper-status-gates.hook.mjs` measured that); and a `provide()` command runs
+ * before the reaction without the event, so it cannot know which file is written. Each of the three
+ * would mean a second copy of the layout. So `paperlint hook paper-folder-layout` runs this module
+ * in-process (`runHook`, src/cli.ts), behind the same wiring command as the other hooks, which is
+ * what `paperlint init` merges and `paperlint doctor` reads.
+ *
+ * ── THE CHEAP FIRST STEP ─────────────────────────────────────────────────────────
+ * Before reading any settings or listing any folder, the hook looks for the nearest folder above the
+ * file that holds `PIPELINE-STATUS.md` — the file every paper has and the rules are reported on — with
+ * one `isFile` per ancestor and nothing else: no git, no lint. No such folder: no output.
+ */
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import { ESCAPE_HATCH } from "./domain/paper-layout.ts";
+import { README, REPRO_DIR, isStudyName } from "./domain/repro-layout.ts";
+import { fieldOf } from "./domain/record.ts";
+import { strayTexts, type FolderLayoutDeps } from "./folder-layout-rule.ts";
+import type { Files } from "./ports/files.ts";
+import { reproTexts } from "./repro-layout-rule.ts";
+
+/** The file every paper folder has, and the rules are reported on. */
+const STATUS_FILE = "PIPELINE-STATUS.md";
+
+/** What Claude Code reads from a PreToolUse hook's stdout to refuse the call, with the reason. */
+export interface HookOutput {
+  readonly hookSpecificOutput: {
+    readonly hookEventName: "PreToolUse";
+    readonly permissionDecision: "deny";
+    readonly permissionDecisionReason: string;
+  };
+}
+
+/** The target file's absolute path from the payload; null when there is none to read. */
+export function writtenPath(payload: unknown): string | null {
+  const input = fieldOf(payload, "tool_input");
+  const raw = fieldOf(input, "file_path") ?? fieldOf(input, "notebook_path");
+  if (typeof raw !== "string" || raw === "") return null;
+  if (isAbsolute(raw)) return resolve(raw);
+  const cwd = fieldOf(payload, "cwd");
+  return typeof cwd === "string" && isAbsolute(cwd) ? resolve(cwd, raw) : null;
+}
+
+/**
+ * The nearest folder above `file` holding `PIPELINE-STATUS.md`, up to the root; null when none, and
+ * null for anything under a folder named `extra/`, which lint never reads: an archived paper kept
+ * there carries its own status file and is not a paper to hold to the layout.
+ */
+export function paperFolderOf(file: string, files: Files): string | null {
+  // The same reach as lint's `**/extra/` ignore: a folder named extra/ anywhere above the file.
+  if (dirname(file).split(sep).includes(ESCAPE_HATCH)) return null;
+  const up = (dir: string): string | null => {
+    if (files.isFile(callerPath(join(dir, STATUS_FILE)))) return dir;
+    const parent = dirname(dir);
+    return parent === dir ? null : up(parent);
+  };
+  return up(dirname(file));
+}
+
+/** The entry `segments` would add under `dir`, as the layout judges it; null when it exists. */
+const newEntry = (
+  dir: string,
+  [name = "", ...below]: readonly string[],
+  deps: FolderLayoutDeps,
+): { readonly name: string; readonly kind: "file" | "dir" } | null =>
+  deps.listDir(callerPath(dir)).includes(name)
+    ? null
+    : { name, kind: below.length > 0 ? "dir" : "file" };
+
+/** Why creating `segments` (relative to the paper folder `dir`) breaks the layout; null when not. */
+function refusal(
+  dir: string,
+  segments: readonly string[],
+  deps: FolderLayoutDeps,
+): string | null {
+  const atRoot = newEntry(dir, segments, deps);
+  const [rootText] =
+    atRoot === null ? [] : strayTexts(dir, [atRoot], deps.files);
+  if (rootText !== undefined) return rootText;
+  const [top, ...inRepro] = segments;
+  if (top !== REPRO_DIR || inRepro.length === 0) return null;
+  const entry = newEntry(join(dir, REPRO_DIR), inRepro, deps);
+  // A new study folder starts with its README.md: that write is what makes it complete.
+  if (
+    entry === null ||
+    (isStudyName(entry.name) && inRepro.slice(1).join("/") === README)
+  )
+    return null;
+  const [text] = reproTexts(dir, [entry], deps.files);
+  return text ?? null;
+}
+
+/** The hook: the payload of an Edit or a Write in, Claude Code's refusal out, or null to allow. */
+export function folderLayoutHook(
+  payload: unknown,
+  deps: FolderLayoutDeps,
+): HookOutput | null {
+  const file = writtenPath(payload);
+  const dir = file === null ? null : paperFolderOf(file, deps.files);
+  if (file === null || dir === null || deps.files.isFile(callerPath(file)))
+    return null;
+  const reason = refusal(dir, relative(dir, file).split(/[\\/]/), deps);
+  return reason === null
+    ? null
+    : {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: reason,
+        },
+      };
+}

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

@@ -0,0 +1,235 @@
+/**
+ * `paper/allowed-files-only` (`src/folder-layout-rule.ts`) on paper folders held in memory, run the way
+ * ESLint runs it: `create`, then `root`. Both halves: a stray file or folder at the paper's root is
+ * reported once each, on the first line of `PIPELINE-STATUS.md`; the scaffold, and what the paper's
+ * settings name at its root, are not.
+ */
+import { describe, expect, it } from "vitest";
+import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
+import { KNOWN_CURES, strayMessage } from "./domain/paper-layout.ts";
+import {
+  FOLDER_LAYOUT_RULE_LEVELS,
+  declaredRoots,
+  folderLayoutRules,
+} from "./folder-layout-rule.ts";
+
+const DIR = "/work/papers/p";
+const SCAFFOLD = {
+  [`${DIR}/PIPELINE-STATUS.md`]: "# status\n",
+  [`${DIR}/paper.tex`]: "\\documentclass{article}\n",
+  [`${DIR}/paperlint.json`]: "{}\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 = folderLayoutRules({
+    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("paper/allowed-files-only — reports", () => {
+  it("a stray file at the root, once, on the first line, with the one stray text", () => {
+    expect(lint({ ...SCAFFOLD, [`${DIR}/PLAN.md`]: "x" })).toEqual([
+      {
+        messageId: "stray",
+        message: strayMessage({
+          name: "PLAN.md",
+          kind: "file",
+          cure: KNOWN_CURES[0]?.cure ?? "",
+        }),
+        line: 1,
+      },
+    ]);
+  });
+
+  it("a stray folder, by its name with a slash, whatever it holds", () => {
+    expect(
+      lint({ ...SCAFFOLD, [`${DIR}/archive/old/x.pdf`]: "x" }).map(
+        (r) => r.message,
+      ),
+    ).toEqual([
+      expect.stringMatching(
+        /^`archive\/` is at the root of a paper folder.* Where it goes: versions\/ for frozen PDFs/,
+      ),
+    ]);
+  });
+
+  it("every stray entry, each once", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/a.pdf`]: "x",
+        [`${DIR}/data/x.json`]: "x",
+        [`${DIR}/run.py`]: "x",
+      }).length,
+    ).toBe(3);
+  });
+
+  it("a folder the settings name is allowed only while they name it", () => {
+    expect(
+      lint({ ...SCAFFOLD, [`${DIR}/video/talk.mp4`]: "x" }).map((r) =>
+        r.message.slice(0, 9),
+      ),
+    ).toEqual(["`video/` "]);
+  });
+});
+
+describe("paper/allowed-files-only — silent", () => {
+  it("on the scaffold `paperlint new` writes", () => {
+    expect(lint(SCAFFOLD)).toEqual([]);
+  });
+
+  it("on the allowed folders, whatever they hold, and on extra/", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/reviews/2026-10-12-x.md`]: "x",
+        [`${DIR}/repro/run.py`]: "x",
+        [`${DIR}/extra/anything/at/all.bin`]: "x",
+        [`${DIR}/_build/paper.facts.json`]: "{}",
+        [`${DIR}/paper.aux`]: "x",
+        [`${DIR}/refs.bib`]: "x",
+      }),
+    ).toEqual([]);
+  });
+
+  it("on what the settings name at the root: the PDF, the talk folder, the paper's own preset", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/paperlint.json`]: JSON.stringify({
+          extends: "./venue.jsonc",
+          pdf: "out/main.pdf",
+          talk: { mode: "remote-video", dir: "video" },
+        }),
+        [`${DIR}/venue.jsonc`]: "{}",
+        [`${DIR}/out/main.pdf`]: "x",
+        [`${DIR}/video/talk.mp4`]: "x",
+      }),
+    ).toEqual([]);
+  });
+
+  it("on any file but PIPELINE-STATUS.md: the folder is judged once per paper", () => {
+    expect(
+      lint({ ...SCAFFOLD, [`${DIR}/PLAN.md`]: "x" }, `${DIR}/paper.tex`),
+    ).toEqual([]);
+  });
+});
+
+describe("declaredRoots — what a paper's settings name at its root", () => {
+  const roots = (settings: object, tree: Record<string, string> = {}) =>
+    declaredRoots(
+      DIR,
+      memoryFiles({
+        [`${DIR}/paperlint.json`]: JSON.stringify(settings),
+        ...tree,
+      }),
+    );
+
+  it("the first segment of each path inside the folder", () => {
+    expect(
+      roots({
+        pdf: "build/out/paper.pdf",
+        talk: { mode: "remote-video", dir: "media/talk" },
+      }),
+    ).toEqual(["build", "media"]);
+  });
+
+  it("every cycle's own preset file, and none outside the folder or shipped", () => {
+    expect(
+      roots({
+        cycles: [
+          {
+            id: "a",
+            venue: { kind: "preset", extends: "./a.jsonc" },
+            opened: "2026-01-01",
+            deadlines: [],
+            outcome: {
+              kind: "rejected",
+              date: "2026-02-01",
+              evidence: "submission/a.eml",
+              desk: false,
+            },
+          },
+          {
+            id: "c",
+            venue: { kind: "named", name: "C", url: "https://c.example" },
+            opened: "2026-03-01",
+            deadlines: [],
+            outcome: {
+              kind: "withdrawn",
+              date: "2026-03-02",
+              evidence: "submission/c.eml",
+            },
+          },
+          {
+            id: "b",
+            venue: { kind: "preset", extends: "../shared/b.jsonc" },
+            opened: "2026-03-01",
+            deadlines: [],
+            outcome: { kind: "open" },
+          },
+        ],
+      }),
+    ).toEqual(["a.jsonc"]);
+  });
+});
+
+describe("declaredRoots — nothing to add", () => {
+  const roots = (settings: object) =>
+    declaredRoots(
+      DIR,
+      memoryFiles({ [`${DIR}/paperlint.json`]: JSON.stringify(settings) }),
+    );
+
+  it("nothing when the settings do not parse, or there are none", () => {
+    expect(roots({ venu: "x" })).toEqual([]);
+    expect(declaredRoots(DIR, memoryFiles({}))).toEqual([]);
+  });
+
+  it("an absolute path inside the folder counts; the folder itself, or a path outside it, does not", () => {
+    expect(
+      roots({
+        pdf: `${DIR}/out/paper.pdf`,
+        talk: { mode: "remote-video", dir: "." },
+      }),
+    ).toEqual(["out"]);
+    expect(roots({ pdf: "/elsewhere/paper.pdf" })).toEqual([]);
+  });
+
+  it("a shipped preset names no file", () => {
+    expect(roots({ extends: "paperlint:aidc" })).toEqual([]);
+  });
+});
+
+it("is on at error in paperlint's own config", () => {
+  expect(FOLDER_LAYOUT_RULE_LEVELS).toEqual({
+    "paper/allowed-files-only": "error",
+  });
+});

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