paperlint 9.0.1 → 10.0.0

package/skills/study-accepted-papers/references/mechanisms.md

@@ -0,0 +1,181 @@
+# Mechanisms of a strong accept — the generic list (M1–M10)
+
+What separates a venue's award winners from its ordinary accepted papers, written so it can be checked
+against any draft. The ids are the rows of the scorecard section in the paper's `PIPELINE-STATUS.md`;
+the skill scores a draft against them in mode C and checks the wording in mode D.
+
+**Where the list comes from, and how far it reaches.** One run of this skill on one software-engineering
+venue (zernie/paperlint#207): every award winner the venue listed for seven years against the ordinary
+papers of the same years, then twelve papers read in full, with two award / no-award pairs on the same
+question. It is a list of **hypotheses to re-test on your venue**, not a law. Each entry says what
+supports it and what it is not. The examples below are award papers, named by title; what is said about
+each comes from reading its full text.
+
+**What did NOT separate the winners** (the same run, issue #207): form. Body words, figures, tables,
+title shape, "first / gap / doubt" phrasing and statistics markers: 13 features, none significant after
+correction, on 21 winners against 112 ordinary papers. Releasing an artifact did not separate them
+either, because most ordinary papers release one too. Do not rebuild a paper's form to match the
+winners. In that run, an apparent "winners have many figures" pattern came from one year of five papers
+and did not hold across seven.
+
+The two published sources on how reviewers in software engineering judge papers point the same way.
+The ICSE 2018 PC report found best-paper nominees furthest above accepted papers on significance and
+soundness, not on presentation. Ernst et al. (EMSE 2021) found negative reviews come from "a mismatch
+between the method and the claims" and "overly grandiose claims". Both are quoted in
+[`base-rates.md`](base-rates.md).
+
+---
+
+| id      | mechanism                                       | the check                                                                                                            |
+| ------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **M1**  | a non-model oracle under the headline           | what decides the headline number: execution, a developer's action, or people reading, with their agreement reported? |
+| **M2**  | the claim is aimed at a belief stated on record | which sentence, by whom, does the result confirm or refute, quoted and cited?                                        |
+| **M3**  | the construct is the claim                      | does what the oracle decides equal what the claim sentence asserts?                                                  |
+| **M4**  | the denominator in the claim sentence, no drift | does every claim sentence carry its scope, and does the abstract say no more than the body?                          |
+| **M5**  | a negative or "X alone" claim shape             | is the claim a counter-example to a stated universal, or "X alone is not Y"?                                         |
+| **M6**  | the generalised-over factor is a column         | if the claim names a class (models, tools, languages), is that class a manipulated column with every cell printed?   |
+| **M7**  | the phenomenon measured directly                | is the thing the claim is about an outcome of its own, not inferred from a downstream proxy?                         |
+| **M8**  | a reusable thing the field pays for once        | which benchmark, method, labelled set or actionable number will a reader reuse?                                      |
+| **M9**  | relevance to every reviewer on the PC           | would a reviewer outside the topic care, e.g. because it is about how the venue does its own science?                |
+| **M10** | where the paper's own result loses              | is the case where the method or tool fails reported as prominently as where it wins?                                 |
+
+---
+
+## M1 — a non-model oracle under the headline
+
+**What it is.** The number in the title or abstract is decided by something other than a model's
+judgement: running the code, what developers actually did, or people reading, with how much they agreed.
+
+**Supports it.** In the run, no winner rested its headline on model-only labels. Award examples:
+_Does Functional Package Management Enable Reproducible Builds at Scale? Yes._ (MSR 2025) rebuilds
+packages and compares the result bit for bit; _A Large-scale Study about Quality and Reproducibility of
+Jupyter Notebooks_ (MSR 2019) re-executes the notebooks; _Can LLMs Replace Manual Annotation of
+Software Engineering Artifacts?_ (MSR 2025) keeps human annotations as the reference the models are
+measured against.
+
+**What it is not.** Not sufficient: in the run's pairs, papers with a human anchor still lost on M3 and
+M4. Not "report κ": winners with and without an agreement statistic were indistinguishable. The point is
+what decides the headline, not the statistic beside it.
+
+## M2 — the claim is aimed at a belief stated on record
+
+**What it is.** The introduction quotes a position the field has written down (a claim in a cited
+paper, a practice the venue's own papers follow, a widely read critique) and the result confirms or
+refutes it.
+
+**Supports it.** All the award papers read in full did this; the non-award papers read mostly did not.
+The reproducible-builds paper answers a doubt that a cited interview study put on record.
+
+**What it is not.** Not "no study has done X": a gap is not a belief. Doubt words ("first", "gap",
+"little is known") did not separate winners in the corpus count. What separates is a named position
+with a source.
+
+## M3 — the construct is the claim
+
+**What it is.** What the oracle measures is exactly what the claim sentence asserts, so a reviewer
+cannot ask "but is that what you mean?".
+
+**Supports it.** Bitwise equality _is_ reproducibility (the reproducible-builds paper); re-execution
+_is_ reproducibility (the notebooks paper). _Clarity Is Not Assumed_ (ASE 2026) defines its construct
+formally before measuring it, so a change in the outcome can mean only one thing. In the run's
+award / no-award pair on one question, this was the deciding difference, not the number of raters.
+
+**What it is not.** Not the same as having an oracle (M1): a valid oracle on a nearby construct still
+fails here.
+
+## M4 — the denominator in the claim sentence, no drift
+
+**What it is.** Each claim sentence carries its scope ("in the 1,000 repositories that…", "for the
+evaluated models"), and the abstract and introduction claim no more than the body shows.
+
+**Supports it.** The reproducible-builds abstract scopes its main sentence to one package manager. _The
+Hidden Cost of Readability_ (ICSE 2026) has a title that asserts only what its oracle measured. In the
+run's pairs, the non-award paper lost where its introduction or abstract said more than its own tables.
+
+**What it is not.** Not hedging. A bold title wins when the fragile half of the claim lives, scoped, in
+the body; the defect is drift between the levels, not confidence.
+
+## M5 — a negative or "X alone" claim shape
+
+**What it is.** Refute a stated universal with one large counter-example, or show that one factor alone
+does not produce the outcome everyone assumes it does.
+
+**Supports it.** The reproducible-builds paper refutes "reproducible builds do not scale" and, with
+equal weight, the opposite myth about its own tool.
+
+**What it is not.** A universal positive ("every X is Y") has the opposite logic: no single census can
+carry it, so it either narrows or needs many independent settings.
+
+## M6 — the generalised-over factor is a column
+
+**What it is.** When the claim names a class (language models, tools, languages, ecosystems), the paper
+varies that factor alone inside one design, prints every cell, and names the member that deviates.
+
+**Supports it.** _The Hidden Cost of Readability_ runs ten models in one design and names the outliers.
+_Understanding Software Engineering Agents: A Study of Thought-Action-Result Trajectories_ (ASE 2025)
+names in its threats that comparing distinct models complicates a fair comparison, and scopes its
+claims accordingly.
+
+**What it is not.** Not necessary for an award: most winners in the run were observational. It is
+necessary to use the class noun without bounding it to the members measured.
+
+## M7 — the phenomenon measured directly
+
+**What it is.** The thing the claim is about is an outcome of its own (for example, disagreement between
+readings measured as a rate), beside the downstream outcome (for example, correctness) that it affects.
+
+**Supports it.** _Clarity Is Not Assumed_ measures conflict between a model's outputs directly, beside
+correctness. In the run, that was what separated it from a no-award paper on the same question, which
+measured correctness alone.
+
+**What it is not.** Only applies when the claim is about the phenomenon itself; a claim about an effect
+is carried by M3 and M5.
+
+## M8 — a reusable thing the field pays for once
+
+**What it is.** A named benchmark, a method another team can apply, a labelled set, or an actionable
+number a practitioner can use.
+
+**Supports it.** The ambiguity benchmark of _Clarity Is Not Assumed_; the trajectory analysis method of
+the agents paper; the decision procedure of the annotation paper.
+
+**What it is not.** A released artifact alone is an admission ticket, not a differentiator: most
+ordinary accepted papers release one. The differentiator is that a reader reuses it.
+
+## M9 — relevance to every reviewer on the PC
+
+**What it is.** A result that matters to reviewers outside the paper's topic, most often because it is
+about how the venue's community does its own research (its datasets, its labelling practice, its
+reproducibility).
+
+**Supports it.** In the run, meta-research was over-represented among winners; examples are the
+annotation paper and _Escaping the Time Pit_ (MSR 2021). This was a post-hoc observation by one coder.
+Treat it as the weakest entry.
+
+**What it is not.** Not a form. It is a topic choice, so it is a mode A or B decision, rarely a mode C
+fix.
+
+## M10 — where the paper's own result loses
+
+**What it is.** The cases where the paper's method, tool or hypothesis fails are reported in the same
+place and with the same prominence as where it wins.
+
+**Supports it.** The reproducible-builds paper names a "false myth" about its own tool; the annotation
+paper reports the tasks where models failed beside the ones where they succeeded.
+
+**What it is not.** Not a threats section. This is what keeps M2 and M5 from reading as advocacy.
+
+---
+
+## Using the list
+
+- **Mode A (idea) and B (design):** M1, M2, M3, M6 and M7 are design decisions. Write each as a
+  requirement for the study before anything runs: what the oracle is, which stated belief is targeted,
+  which factor is a column.
+- **Mode C (draft):** score every row of the scorecard section in `PIPELINE-STATUS.md`. Each row gets a
+  status (pass / partial / fail), evidence as `file:line` in the paper source, an owner, and a plan or an
+  explicit "accept ceiling" with the reason.
+- **Mode D (final):** M4 and M2, sentence by sentence, in the abstract and the introduction.
+- **Re-test the list on your venue.** Add a mechanism your venue's winners share, with its evidence, in
+  the venue corpus (`<papers-root>/venues/<venue>/`). Mark one that does not hold there. The ids M1–M10
+  stay stable so scorecards stay comparable.

package/skills/verify-citations/SKILL.md

@@ -4,7 +4,7 @@ description: Verify every citation is a real work with correct metadata, and tha
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent]
 ---
 
-<!-- vigiles:sha256:fdb023ed7c613e1b compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:47a4b53679a716dd compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
@@ -134,7 +134,7 @@ built and records the verdicts, with the SHA-256 of the bibliography it checked,
 changed since, and `paper/refs-checked` warns when nothing was recorded or the build had no network. The
 step never fails the build.
 
-What the services ANSWERED is kept in `<paper>/repro/references-cache.json` — **commit it**. A build asks
+What the services ANSWERED is kept in `<paper>/repro/data/references-cache.json` — **commit it**. A build asks
 only the questions that file cannot answer (a new or edited entry, or an answer older than 30 days), so an
 unchanged bibliography builds with no network at all, in CI too, until its answers age out. It holds responses, never verdicts: the verdicts are derived again on
 every build. A service that refuses (429, HTML instead of JSON, a timeout) is not asked again for the rest of the

package/skills/verify-citations/SKILL.md.spec.ts

@@ -150,7 +150,7 @@ built and records the verdicts, with the SHA-256 of the bibliography it checked,
 changed since, and \`paper/refs-checked\` warns when nothing was recorded or the build had no network. The
 step never fails the build.
 
-What the services ANSWERED is kept in \`<paper>/repro/references-cache.json\` — **commit it**. A build asks
+What the services ANSWERED is kept in \`<paper>/repro/data/references-cache.json\` — **commit it**. A build asks
 only the questions that file cannot answer (a new or edited entry, or an answer older than 30 days), so an
 unchanged bibliography builds with no network at all, in CI too, until its answers age out. It holds responses, never verdicts: the verdicts are derived again on
 every build. A service that refuses (429, HTML instead of JSON, a timeout) is not asked again for the rest of the

package/src/build.ts

@@ -615,7 +615,7 @@ export const measureStep: BuildStep = {
  * `_build/references.json` for the offline lint rules (`reference-rules.ts`). OPTIONAL and NEVER
  * FAILING: without network the PDF is still built, and the record says `not-checked`.
  *
- * What the services answered is read from and added to `<paper>/repro/references-cache.json`
+ * What the services answered is read from and added to `<paper>/repro/data/references-cache.json`
  * (`references.ts`, `domain/lookup-cache.ts`), committed with the paper, so only a new or edited
  * entry is asked, and an unchanged bibliography is checked with no network at all (#107).
  */

package/src/cli.harness.mjs

@@ -1233,6 +1233,48 @@ check(
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// `paperlint hook paper-folder-layout` the way Claude Code runs it: the payload on stdin, the answer
+// on stdout, through the real bin. The in-process tests inject both streams; this is the one place
+// the defaults are read and written for real.
+{
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-hook-")));
+  try {
+    const paper = join(root, "papers", "p");
+    mkdirSync(paper, { recursive: true });
+    writeFileSync(join(paper, "PIPELINE-STATUS.md"), "# S\n");
+    const hook = (file) =>
+      spawnSync(
+        process.execPath,
+        [
+          join(HERE, "..", "bin", "paperlint.mjs"),
+          "hook",
+          "paper-folder-layout",
+        ],
+        {
+          cwd: root,
+          encoding: "utf8",
+          input: JSON.stringify({ tool_input: { file_path: file } }),
+        },
+      );
+    const stray = hook(join(paper, "PLAN.md"));
+    check(
+      "the layout hook refuses a new stray PLAN.md on stdout as a PreToolUse deny, exit 0",
+      stray.status === 0 &&
+        /^\{"hookSpecificOutput":\{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"`PLAN\.md` is at the root/.test(
+          stray.stdout,
+        ),
+    );
+    const outside = hook(join(root, "notes.md"));
+    check(
+      "and says nothing about a file outside every paper folder",
+      outside.status === 0 && outside.stdout === "",
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
 console.log(
   `✓ ${String(check.count)} assertions passed — paperlint lint, one command instead of hand-rolled config`,
 );

package/src/cli.test.ts

@@ -9,7 +9,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { createServer } from "node:http";
 import { dirname, join } from "node:path";
-import { test } from "vitest";
+import { test, vi } from "vitest";
 import {
   runNode,
   useTempDir,
@@ -200,6 +200,70 @@ test("runHook: a runtime with no cli.js beside it, and a hook killed by a signal
   );
 });
 
+test("runHook paper-folder-layout: in-process, on the real disk — a refusal on stdout for a new stray file, nothing for an allowed one, a complaint and exit 0 on a broken payload", () => {
+  const dir = join(root, "layout-hook");
+  writeTree(dir, {
+    "papers/p/PIPELINE-STATUS.md": "# status\n",
+    "papers/p/paper.tex": "x",
+    "papers/p/NOTES.md": "x",
+  });
+  const hook = (payload: string) => {
+    const out: string[] = [];
+    const err: string[] = [];
+    const code = runHook("paper-folder-layout", {
+      stdin: () => payload,
+      out: (t) => out.push(t),
+      err: (m: string) => err.push(m),
+      run: () => {
+        throw new Error("an in-process hook spawns nothing");
+      },
+    });
+    return { code, out, err };
+  };
+  const write = (file: string) =>
+    JSON.stringify({ tool_input: { file_path: join(dir, file) } });
+  const stray = hook(write("papers/p/PLAN.md"));
+  assert.equal(stray.code, 0);
+  assert.match(
+    stray.out.join(""),
+    /^\{"hookSpecificOutput":\{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"`PLAN\.md` is at the root of a paper folder/,
+  );
+  assert.deepEqual(hook(write("papers/p/NOTES.md")), {
+    code: 0,
+    out: [],
+    err: [],
+  });
+  const broken = hook("{ not json");
+  assert.equal(broken.code, 0);
+  assert.match(
+    broken.err.join(""),
+    /^paperlint: the paper-folder-layout hook did not run: /,
+  );
+});
+
+test("runHook paper-folder-layout: by default its output goes to stdout, where Claude Code reads it", () => {
+  const dir = join(root, "layout-hook-stdout");
+  writeTree(dir, { "papers/p/PIPELINE-STATUS.md": "# status\n" });
+  const write = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation(() => true);
+  try {
+    const code = runHook("paper-folder-layout", {
+      stdin: () =>
+        JSON.stringify({
+          tool_input: { file_path: join(dir, "papers/p/PLAN.md") },
+        }),
+    });
+    assert.equal(code, 0);
+    assert.match(
+      String(write.mock.calls[0]?.[0]),
+      /^\{"hookSpecificOutput":\{"hookEventName":"PreToolUse","permissionDecision":"deny"/,
+    );
+  } finally {
+    write.mockRestore();
+  }
+});
+
 test("chooseVenue: a preset by path (inside and outside the paper), by prefixed name, and a broken one", async () => {
   const dir = join(root, "venues");
   writeTree(dir, {
@@ -447,14 +511,34 @@ test("silentOptionalRules: a rule no block names for any paper is silent — a g
   );
 });
 
+test("silentOptionalRules: a rule that runs on the paper's PIPELINE-STATUS.md is reached through it", async () => {
+  const eslint = {
+    calculateConfigForFile: (f: string) =>
+      Promise.resolve(
+        f.endsWith("PIPELINE-STATUS.md")
+          ? { rules: { "study/declare-sample": [2] } }
+          : { rules: {} },
+      ),
+  };
+  const sampleOn = {
+    rules: [
+      { basePath: ".", rules: { "study/declare-sample": "error" as const } },
+    ],
+  };
+  assert.deepEqual(
+    await silentOptionalRules(eslint, ["p/paper.tex"], sampleOn),
+    [],
+  );
+});
+
 test("init with no path sets up the current directory, and its first paper is paper.tex", async () => {
   const dir = writeTree(join(root, "init-here"), { "package.json": "{}" });
   const r = await cli(["init", "--yes", "--no-hooks", "--paper", "first"], dir);
-  assert.deepEqual(
-    readdirSync(join(dir, "papers", "first")).sort(),
-    ["PIPELINE-STATUS.md", "paper.tex", "paperlint.json"],
-    r.out + r.err,
-  );
+  const made = readdirSync(join(dir, "papers", "first"));
+  // The three files, then the layout's folders (src/new-paper.test.ts holds the exact tree).
+  for (const f of ["PIPELINE-STATUS.md", "paper.tex", "paperlint.json"])
+    assert.ok(made.includes(f), `${f} is missing:\n${r.out + r.err}`);
+  assert.equal(made.includes("main.tex"), false);
 });
 
 test("init and doctor with a declaration that names no directory: nothing to compare", async () => {

package/src/cli.ts

@@ -138,7 +138,12 @@ import {
   init,
   processInteractivity,
 } from "./init.ts";
-import { newPaper, reportNewPaper, type VenueSetting } from "./new-paper.ts";
+import {
+  newPaper,
+  reportNewPaper,
+  STATUS_FILE,
+  type VenueSetting,
+} from "./new-paper.ts";
 // The one source for the consumer's config key lives in lib/ (the ESLint rules and the skill scripts
 // import it too). It is imported compiled, from dist/, the one path that resolves the same from src/
 // and from dist/ — see CONTRIBUTING.md.
@@ -164,12 +169,22 @@ export { init };
 export { nextSteps } from "./init.ts";
 
 import paperStages from "#eslint-rules/paper-stages";
+import preregCoverage from "#eslint-rules/prereg-coverage";
 import cycleStage from "#eslint-rules/cycle-stage";
 import { CYCLE_RULE_LEVELS, cycleRules } from "./cycle-rules.ts";
 import {
   FOLDER_VENUE_RULE_LEVELS,
   folderVenueRules,
 } from "./folder-venue-rule.ts";
+import {
+  FOLDER_LAYOUT_RULE_LEVELS,
+  folderLayoutRules,
+} from "./folder-layout-rule.ts";
+import { folderLayoutHook } from "./folder-layout-hook.ts";
+import {
+  REPRO_LAYOUT_RULE_LEVELS,
+  reproLayoutRules,
+} from "./repro-layout-rule.ts";
 import typography from "#eslint-rules/paper-typography";
 import texBuild from "#eslint-rules/tex-build";
 import reviewFrontmatter from "#eslint-rules/review-frontmatter";
@@ -177,6 +192,7 @@ import siblingFrontmatter from "#eslint-rules/sibling-frontmatter";
 import pdfRules from "#eslint-rules/pdf-last-page-balance";
 import { messageOf } from "./domain/text.ts";
 import { isRecord } from "./domain/record.ts";
+import { ESCAPE_HATCH } from "./domain/paper-layout.ts";
 
 /** The shipped venue presets, read from the package's venues directory — the one list. */
 const SHIPPED_VENUES = (): string[] => shippedPresets(presetsDir());
@@ -348,6 +364,9 @@ const FRAGMENT_RULES = {
   "heading-case": REGISTER_AND_CASE_RULES["heading-case"],
 };
 
+/** What the two layout rules read with: the disk and its directory listings. */
+const LAYOUT_RULE_DEPS = { files: nodeFiles, listDir: nodeListDir };
+
 /** What the talk rules read with: the disk, the shipped presets, and the three media readers. */
 const TALK_RULE_DEPS = {
   files: nodeFiles,
@@ -380,7 +399,9 @@ export function buildConfig(
     // its files carry every marker a paper does. Flat config does NOT ignore dot-directories by
     // default (only `node_modules/` and `.git/`), so without this block `paperlint lint` would lint the
     // template as a paper — and a richer template with placeholder stages would fail the run.
-    { ignores: ["**/.template/"] },
+    // The same for a paper's `extra/`: the layout promises it is never judged, and an archived
+    // snapshot there carries a paper's markers too, so its folder read as a paper root with strays.
+    { ignores: ["**/.template/", `**/${ESCAPE_HATCH}/`] },
     // The `pdf` plugin is registered for EVERY file. A consumer's block (`rules`, appended below)
     // may name its rules for a glob that also matches markdown files; with the plugin defined only
     // beside `paper.tex`, ESLint would refuse those files with "could not find plugin". Every rule
@@ -409,8 +430,12 @@ export function buildConfig(
           rules: {
             ...paperStages.rules,
             ...folderVenueRules({ files: nodeFiles, venuesDir: presetsDir() }),
+            ...folderLayoutRules(LAYOUT_RULE_DEPS),
           },
         },
+        repro: { rules: reproLayoutRules(LAYOUT_RULE_DEPS) },
+        // Registered, on for no paper: `"study/declare-sample": "error"` in paperlint.json turns it on.
+        study: { rules: preregCoverage.rules },
         cycle: { rules: CYCLE_STATUS_RULES },
       },
       ...md,
@@ -418,6 +443,8 @@ export function buildConfig(
         "paper/stages": "error",
         "paper/source": "error",
         ...FOLDER_VENUE_RULE_LEVELS,
+        ...FOLDER_LAYOUT_RULE_LEVELS,
+        ...REPRO_LAYOUT_RULE_LEVELS,
         ...CYCLE_RULE_LEVELS,
       },
     },
@@ -647,7 +674,7 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * 🔴 AN OPTIONAL RULE THAT IS ON AND REACHES NO PAPER IS A GREEN ZERO. A `files` glob that matches
  * nothing — a typo, a path relative to the wrong directory — leaves the rule never invoked, and a
  * rule that never runs reports exactly like a rule that passed. So for every optional rule the
- * consumer turned on, some `paper.tex` must actually have it enabled; the ones none has are
+ * consumer turned on, some paper's `paper.tex` or `PIPELINE-STATUS.md` must actually have it enabled; the ones none has are
  * returned, for the caller to refuse.
  *
  * `files` is every `paper.tex` the guard may count: the ones this run linted AND every paper of the
@@ -673,9 +700,16 @@ export async function silentOptionalRules(
     ),
   );
   const reached = new Set<string>();
-  for (const f of new Set(files.filter((p) => basename(p) === MAIN))) {
+  // A paper's rules reach it through two files: `paper.tex` and the `PIPELINE-STATUS.md` beside it,
+  // where the rules about the paper folder itself run.
+  const probes = [
+    ...new Set(files.filter((p) => basename(p) === MAIN)),
+  ].flatMap((f) => [f, join(dirname(f), STATUS_FILE)]);
+  for (const probe of probes) {
     // Undefined for a file outside ESLint's cwd or scope: it reaches nothing.
-    const cfg = ComputedConfig.parse(await eslint.calculateConfigForFile(f));
+    const cfg = ComputedConfig.parse(
+      await eslint.calculateConfigForFile(probe),
+    );
     // Reached is "some block names the rule for this paper", on OR off: a paper that turns off what
     // its venue preset turned on is the documented way out, and reads the same as a glob that missed
     // only if "off" is counted as "not there" — which refused every such paper.
@@ -1084,6 +1118,35 @@ export function toPaths(papers: unknown): string[] {
   return [];
 }
 
+/** What an in-process hook is handed: the payload, and where its output and complaints go. */
+interface HookIo {
+  readonly err: typeof console.error;
+  readonly stdin: () => string;
+  readonly out: (text: string) => void;
+}
+
+/**
+ * Hooks that run inside this process instead of as a vigiles program, each because it must call the
+ * package's own code (`src/folder-layout-hook.ts` says why for its one). Advisory: whatever goes
+ * wrong, the tool call has already happened, so it says so on stderr and exits 0.
+ */
+const IN_PROCESS_HOOKS: Readonly<Record<string, (io: HookIo) => number>> = {
+  "paper-folder-layout": ({ err, stdin, out }) => {
+    try {
+      const said = folderLayoutHook(JSON.parse(stdin()), {
+        files: nodeFiles,
+        listDir: nodeListDir,
+      });
+      if (said !== null) out(`${JSON.stringify(said)}\n`);
+    } catch (e) {
+      err(
+        `paperlint: the paper-folder-layout hook did not run: ${messageOf(e)}`,
+      );
+    }
+    return 0;
+  },
+};
+
 /**
  * `paperlint hook <name>` — run an editor hook. It exists for ONE thing: so that the wiring does not
  * address the runtime from the project root.
@@ -1125,6 +1188,10 @@ export function runHook(
     // the very file the package itself declares as its `bin`.
     resolve = (spec: string): string =>
       createRequire(import.meta.url).resolve(spec),
+    stdin = (): string => readFileSync(0, "utf8"),
+    out = (text: string): void => {
+      process.stdout.write(text);
+    },
   }: {
     err?: typeof console.error;
     /** Runs the hook with the terminal's streams: `spawnSync` is one, and only its status is read. */
@@ -1134,12 +1201,18 @@ export function runHook(
       options: { readonly stdio: "inherit" },
     ) => { readonly status: number | null };
     resolve?: (spec: string) => string;
+    /** The hook's payload, as Claude Code sends it on stdin. */
+    stdin?: () => string;
+    /** Where an in-process hook's output goes: stdout, which Claude Code reads. */
+    out?: (text: string) => void;
   } = {},
 ): number {
   if (!name) {
     err(`\`hook\` needs a name, e.g. \`paperlint hook paper-edit-guard\``);
     return 2;
   }
+  const inProcess = IN_PROCESS_HOOKS[name];
+  if (inProcess !== undefined) return inProcess({ err, stdin, out });
   const program = fileURLToPath(
     new URL(`../hooks/${name}.hook.mjs`, import.meta.url),
   );

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

@@ -0,0 +1,32 @@
+/**
+ * `renderTree` (`src/domain/layout-tree.ts`): the drawing every layout message and rule page shows.
+ * Branches drawn as `tree` draws them, nested entries indented under a continuing or a closed branch,
+ * every note in one column.
+ */
+import { describe, expect, it } from "vitest";
+import { leaf, renderTree } from "./layout-tree.ts";
+
+describe("renderTree", () => {
+  it("draws nested entries under open and closed branches, notes in one column", () => {
+    expect(
+      renderTree("root/", [
+        { name: "a/", note: "first", children: [leaf("x", "inner")] },
+        leaf("bb", "middle"),
+        { name: "c/", note: "last", children: [leaf("y", "under last")] },
+      ]),
+    ).toBe(
+      [
+        "root/",
+        "├── a/     ← first",
+        "│   └── x  ← inner",
+        "├── bb     ← middle",
+        "└── c/     ← last",
+        "    └── y  ← under last",
+      ].join("\n"),
+    );
+  });
+
+  it("an empty layout is its root alone", () => {
+    expect(renderTree("root/", [])).toBe("root/");
+  });
+});

package/src/domain/layout-tree.ts

@@ -0,0 +1,47 @@
+/**
+ * A layout drawn as a tree — the one picture of what a paper folder may hold.
+ *
+ * The rules' messages, the hook's refusal and the rules' pages all show the same drawing, rendered by
+ * `renderTree` from the constants that decide what is allowed (`paper-layout.ts`, `repro-layout.ts`).
+ * The pages embed it between markers and a test compares them with this render, so a page cannot
+ * describe a layout the code does not enforce.
+ */
+
+/** One entry of a layout: its name (a folder's ends in a slash), what it is for, what it holds. */
+export interface TreeNode {
+  readonly name: string;
+  readonly note: string;
+  readonly children: readonly TreeNode[];
+}
+
+/** An entry with nothing drawn under it. */
+export const leaf = (name: string, note: string): TreeNode => ({
+  name,
+  note,
+  children: [],
+});
+
+interface Row {
+  readonly left: string;
+  readonly note: string;
+}
+
+/** Each entry's line, depth first, with the branch drawing in front of its name. */
+const rowsOf = (nodes: readonly TreeNode[], indent: string): readonly Row[] =>
+  nodes.flatMap((n, i) => {
+    const last = i === nodes.length - 1;
+    return [
+      { left: `${indent}${last ? "└── " : "├── "}${n.name}`, note: n.note },
+      ...rowsOf(n.children, `${indent}${last ? "    " : "│   "}`),
+    ];
+  });
+
+/** `nodes` under `root`, one line each, every note in one column after `←`. Pure. */
+export function renderTree(root: string, nodes: readonly TreeNode[]): string {
+  const rows = rowsOf(nodes, "");
+  const width = Math.max(0, ...rows.map((r) => r.left.length));
+  return [
+    root,
+    ...rows.map((r) => `${r.left.padEnd(width)}  ← ${r.note}`),
+  ].join("\n");
+}

package/src/domain/lookup-cache.ts

@@ -1,5 +1,5 @@
 /**
- * THE LOOKUP CACHE — `<paper>/repro/references-cache.json`: what the citation services ANSWERED,
+ * THE LOOKUP CACHE — `<paper>/repro/data/references-cache.json`: what the citation services ANSWERED,
  * kept so that a build asks each question at most once every MAX_AGE_DAYS, not once per build (#107).
  *
  *   { "schema": 1,
@@ -15,7 +15,7 @@
  * responses on every build, by the current version of the checkers. A cached verdict would freeze
  * whatever the checker believed the day it ran — a bug fixed in the comparison would never reach a
  * paper whose entries are cached. A cached response is evidence: it cannot be made up, only
- * refetched. The precedent is `extract-ref-facts.mjs`'s `repro/refs-cache.json` ("the cache is
+ * refetched. The precedent is `extract-ref-facts.mjs`'s `repro/data/refs-cache.json` ("the cache is
  * evidence, not a second declaration").
  *
  * 🔴 COMMITTED, so CI and every other clone start warm: a build whose entries are all here makes no