paperlint 9.0.0 → 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/CLAUDE.md

@@ -1,9 +1,15 @@
-# CLAUDE.md — `src/`
+<!-- vigiles:sha256:f51051aae2ef09f8 compiled from src/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## `src/`
 
 The package's TypeScript: the CLI, the build, the toolchain installer, and the measuring that feeds
 the facts file. Loaded when working under `src/`; the repository-wide rules are in the root
 `CLAUDE.md`.
 
+## The two layer axes
+
 **`src/` is hexagonal on two axes, and the linter enforces both** (`eslint.config.mjs`; fixtures in
 `test/fixtures/layers/`, run by `test/eslint-layers.test.ts`; issue #76).
 
@@ -49,3 +55,19 @@ against `process.cwd()`, so lint started from any other directory classifies not
 `checkAllOrigins: true`: without it no `module:` policy is evaluated, so axis B and the library bans
 report nothing — dropping it turns the fixtures `src/domain/reads-disk.ts` and
 `src/adapters/one/disk.ts` clean (measured).
+
+## Readers and commands
+
+`@retorquere/bibtex-parser` is the one `.bib` reader, behind `src/ports/bib-reader.ts`.
+Rejected on 2026-09-27, so not proposed again: a separate `paperlint refs` command; the slowness it
+would have moved was a cache thrown away after every build (`docs/references.md`).
+
+## Rules
+
+### Layers
+
+**Enforced by:** `eslint/boundaries/dependencies`
+
+### Effect Globals
+
+**Enforced by:** `eslint/no-restricted-globals`

package/src/CLAUDE.md.spec.ts

@@ -0,0 +1,72 @@
+// Compiled to src/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+import { enforce, file, instructionFile, prose } from "vigiles/spec";
+
+export default instructionFile({
+  sections: {
+    "`src/`": prose`The package's TypeScript: the CLI, the build, the toolchain installer, and the measuring that feeds
+the facts file. Loaded when working under \`src/\`; the repository-wide rules are in the root
+\`CLAUDE.md\`.`,
+
+    "The two layer axes": prose`**\`src/\` is hexagonal on two axes, and the linter enforces both** (\`eslint.config.mjs\`; fixtures in
+\`test/fixtures/layers/\`, run by ${file("test/eslint-layers.test.ts")}; issue #76).
+
+**Axis A — knowledge. Core means the DOMAIN, not "no I/O".** A file belongs to an adapter when it
+exists because of one external program or format: _if banal / pdf.js / TeX Live / ESLint / Claude
+Code disappeared tomorrow, which files would change? Those are its adapter, wherever they sit
+today._ The domain is what would not change if every one of them were swapped. Purity is not the
+test — a parser for banal's JSON is pure and is still banal's.
+
+| element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
+| --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; \`ts-essentials\`, \`node:path\`, \`node:crypto\`                                                                   |
+| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same three externals                                                                              |
+| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; Node's \`util\`/\`url\`/\`module\`                                             |
+| \`adapter\` | \`src/adapters/<tool>/\` | everything that knows \`<tool>\` exists, pure parsers included; used through its \`index.ts\`                                                                          | \`domain\`, \`port\`, its own folder, its tool's packages, the package's \`.mjs\`. **Never** \`app\`, **never** another adapter |
+| \`root\`    | \`src/cli.ts\`           | reads \`process.*\`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
+
+Folders are ELEMENTS of \`eslint-plugin-boundaries\`, single files are CATEGORIES (\`root\`, \`app\`,
+\`test\`, \`io\`): v7 matches element patterns as folders. Everyone — tests included — reaches an
+adapter through its \`index.ts\`; the files inside one adapter import each other freely.
+
+**Axis B — purity.** An effect (disk, process, network, env, clock, TTY) may be written only in
+\`src/adapters/<tool>/<x>.io.ts\` and \`src/cli.ts\`. Every other file, adapters' parsers included,
+takes a port. Test: _can a call here fail for a reason not in its arguments?_ Imports are checked
+through the \`io\` file category in \`boundaries/dependencies\`; the \`process\` and \`fetch\` globals by
+\`no-restricted-globals\`.
+
+**The legacy app files are held by a ratchet, not exempted.** A site that still breaks either axis
+carries \`// eslint-disable-next-line <rule> -- legacy <I/O|layer>, moves behind a port in #76\`.
+Unused directives are errors (\`reportUnusedDisableDirectives\`), so a fixed site must drop its
+comment; the per-file counts are frozen in \`scripts/layer-legacy.frozen.json\` and checked by
+${file("scripts/layer-legacy-frozen.ts")} (\`npm run check\`, CI), which counts ESLint's own
+\`suppressedMessages\` and fails when a file's count grows, a file not in the list carries one, or
+anything under \`src/domain/\`, \`src/ports/\` or \`src/adapters/\` does. A NEW module that needs the
+world is a new \`*.io.ts\` in the adapter of the program it talks to — never a new directive.
+
+Parse at the boundary, into types that cannot hold an invalid state (a banal path that exists only
+after its sha256 and probe passed; a \`Ready\` only an installer mints; an outcome as a discriminated
+union, not a string); the inside never re-validates.
+
+⚠️ **Two settings are load-bearing.** \`boundaries/root-path\`: without it the plugin matches paths
+against \`process.cwd()\`, so lint started from any other directory classifies nothing and passes.
+\`checkAllOrigins: true\`: without it no \`module:\` policy is evaluated, so axis B and the library bans
+report nothing — dropping it turns the fixtures \`src/domain/reads-disk.ts\` and
+\`src/adapters/one/disk.ts\` clean (measured).`,
+
+    "Readers and commands": prose`\`@retorquere/bibtex-parser\` is the one \`.bib\` reader, behind ${file("src/ports/bib-reader.ts")}.
+Rejected on 2026-09-27, so not proposed again: a separate \`paperlint refs\` command; the slowness it
+would have moved was a cache thrown away after every build (${file("docs/references.md")}).`,
+  },
+  rules: {
+    layers: enforce(
+      "eslint/boundaries/dependencies",
+      "Both axes: what a layer may import, and where an effect may be written.",
+      { render: "id" },
+    ),
+    "effect-globals": enforce(
+      "eslint/no-restricted-globals",
+      "The process and fetch globals only where an effect may be written.",
+      { render: "id" },
+    ),
+  },
+});

package/src/build.ts

@@ -34,7 +34,7 @@
  * The decision of the LaTeX loop is `latex-loop.ts`, reading the log is `latex-log.ts`; both are
  * pure. This file is the shell: it runs processes through the injected `run` (the existing port —
  * `spawnSync` by default) and reads the files a pass left behind. Where paperlint's own files live is
- * answered by `package-dirs.ts`, the one module allowed to know it (rule 10).
+ * answered by `package-dirs.ts`, the one module allowed to know it (root CLAUDE.md).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
@@ -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 () => {