paperlint 9.0.1 → 10.0.0

package/docs/ci.md

@@ -0,0 +1,60 @@
+# Run it in CI
+
+Two jobs, one choice: how much of the paper CI judges.
+
+| job                        | time                          | checks                                     |
+| -------------------------- | ----------------------------- | ------------------------------------------ |
+| build, then lint           | ~3 min first run, then cached | everything                                 |
+| lint only (`init` adds it) | seconds                       | the source; not pages, fonts or references |
+
+`paperlint lint` exits non-zero on any error; warnings only print, unless you pass
+`--max-warnings <n>`.
+
+## Build, then lint
+
+Lint judges pages, fonts and references from what build measured, so the full job builds first.
+The cache keeps TeX Live between runs:
+
+```yaml
+name: papers
+on: [push, pull_request]
+jobs:
+  papers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/paperlint/texlive
+          key: texlive-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - run: npx paperlint toolchain
+      - run: npx paperlint build --all
+      - run: npx paperlint lint
+```
+
+Commit `repro/data/references-cache.json` of each paper: with it, a build asks the citation
+services only about new or edited entries, so an unchanged bibliography usually builds without
+the network ([`references.md`](references.md)).
+
+## Lint only
+
+Each paper then gets one warning that it was not built. Call the action from the installed package,
+after `npm ci`: the action and the CLI it runs are then one revision, pinned by your lockfile.
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-node@v4
+    with:
+      node-version: 22
+  - run: npm ci
+  - uses: ./node_modules/paperlint
+```
+
+With no `paths` it lints the `papersDir` of your `paperlint.json`; pass `paths:` only to lint less.
+
+This is the workflow `paperlint init` offers to write ([`install.md`](install.md)).

package/docs/configuration.md

@@ -13,6 +13,8 @@ papers/
     paper.tex
     PIPELINE-STATUS.md
     paperlint.json           THIS PAPER: its venue preset, its kind, its own rules — `paperlint new` writes it
+    reviews/ research/ figures/ versions/ submission/ repro/
+                             the paper's layout — `paperlint new` makes them (an empty one holds a `.gitkeep`)
 venues/usenix-sec.jsonc      (optional, your own) a VENUE PRESET: format, page limits, TeX packages, rules
 ```
 

package/docs/e2e.md

@@ -54,8 +54,8 @@ depend on each other — and drives the installed binary:
   publishes, once each — and says they need `npm install` in a fresh clone; a second `init`
   leaves that file byte-identical
 - `paperlint lint` passes the staged corpus
-- `paperlint new demo` scaffolds a paper from the templates that shipped in the tarball, its own lint is
-  clean, and `paperlint lint` stays clean with it in the corpus
+- `paperlint new demo` scaffolds a paper from the templates that shipped in the tarball (and the
+  layout's folders), its own lint is clean, and `paperlint lint` stays clean with it in the corpus
 - `hooks.json` arrived and parses, and every hook command named in it resolves to a file
 - every skill arrived, and every script path named inside a skill resolves **in the consumer**
 

package/docs/install.md

@@ -50,9 +50,9 @@ question (Ctrl+D) also takes the default.
 | what                                                                 | where                   | when                                                                                                                                                                              |
 | -------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `{ "papersDir": … }` naming your papers directory                    | `paperlint.json`        | only when it is not the default `papers`                                                                                                                                          |
-| the three hook commands, merged in beside your own entries           | `.claude/settings.json` | by default. A human at a terminal is asked [Y/n]; an agent, CI or `--yes` gets YES; `--no-hooks` skips. Hand-wired under another spelling: nothing written, so nothing runs twice |
+| the four hook commands, merged in beside your own entries            | `.claude/settings.json` | by default. A human at a terminal is asked [Y/n]; an agent, CI or `--yes` gets YES; `--no-hooks` skips. Hand-wired under another spelling: nothing written, so nothing runs twice |
 | a GitHub Actions workflow: `npm ci`, then `./node_modules/paperlint` | `.github/workflows/`    | only if you say yes; it asks once, and only when a human is at a terminal (stdin and stdout, no `CI`, no `--yes`)                                                                 |
-| a first paper, via `paperlint new`                                   | `<papers>/<name>/`      | only when the papers directory holds none: asked of a human at a terminal, otherwise only with `--paper <name>`                                                                   |
+| a first paper, via `paperlint new`, with its layout's folders        | `<papers>/<name>/`      | only when the papers directory holds none: asked of a human at a terminal, otherwise only with `--paper <name>`                                                                   |
 | one relative symlink per shipped skill, into the installed package   | `.claude/skills/<name>` | always — except where that name is already taken (a directory, a file, a link elsewhere): that entry is left as it is and named in the report                                     |
 
 It installs no software you did not say yes to, and touches nothing else. Commit `.claude/settings.json` so every clone
@@ -61,9 +61,11 @@ gets the hooks; the hook commands run files inside `node_modules`, so a fresh cl
 
 ## Why it is shaped this way
 
-**One file, at the project root.** A hook cannot import code or walk up a tree looking for a
-config; it can only read a path it can spell, and `$CLAUDE_PROJECT_DIR/paperlint.json` is one. The
-same file is read by the CLI, the three hooks, `eslint-rules/papers.mjs`,
+**One file, at the project root.** A vigiles hook cannot import code or walk up a tree looking for
+a config; it can only read a path it can spell, and `$CLAUDE_PROJECT_DIR/paperlint.json` is one.
+(`paper-folder-layout` is not a vigiles hook: it runs inside the CLI, because it must call the
+function its rule reports with.) The same file is read by the CLI, the three vigiles hooks,
+`eslint-rules/papers.mjs`,
 `lib/skill-trigger-cases.mjs` and `skills/paper-pipeline/scripts/consumer.mjs`. It is optional:
 absent, every reader takes the same defaults.
 
@@ -147,17 +149,19 @@ are probably smaller now; re-measure before quoting them.
 | of which `typescript` (via `vigiles`)  |      23 MB |
 | of which `vigiles` itself              |       6 MB |
 
-Neither `paperlint lint` nor any of the three hooks loads `@ast-grep` or `typescript` (traced);
-`vigiles` itself is loaded.
+Neither `paperlint lint` nor any of the four hooks loads `@ast-grep` or `typescript` (traced;
+`paper-folder-layout` on 2026-10-12: 223 CommonJS modules, none from either); `vigiles` itself is
+loaded.
 
 ## Troubleshooting
 
-| symptom                                                      | cause and fix                                                                                                                                                                          |
-| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init`: skills "nothing linked", or hooks that fail to start | the package is not installed in this project (`npx` ran a temporary copy). Run `npm i -D paperlint`, then `npx paperlint init` again                                                   |
-| `paperlint lint`: `no papers in papers/`                     | there is no paper where `papersDir` points. Create one with `npx paperlint new <name>`, or set `"papersDir"` in `paperlint.json`                                                       |
-| hooks fail with `Cannot find module` in a fresh clone        | the hook commands run files in `node_modules`: run `npm install`                                                                                                                       |
-| `paperlint: not built`                                       | installed from git with `--ignore-scripts`, or a clone before building: run `npm run build` in the package                                                                             |
-| a skill does not show up in Claude Code                      | its name was already taken in `.claude/skills/`. `init` names it and leaves it alone; rename or remove yours and run `npx paperlint init` again                                        |
-| **every** shell command is blocked in Claude Code            | `paper-edit-guard` cannot parse the root `paperlint.json` (merge-conflict markers, a typo), and refuses rather than guess. Fix it with a normal file edit — file edits are not blocked |
-| anything else                                                | `npx paperlint doctor` — it checks the setup and exits non-zero on anything miswired                                                                                                   |
+| symptom                                                                                                                       | cause and fix                                                                                                                                                                                            |
+| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`: skills "nothing linked", or hooks that fail to start                                                                  | the package is not installed in this project (`npx` ran a temporary copy). Run `npm i -D paperlint`, then `npx paperlint init` again                                                                     |
+| `paperlint lint`: `no papers in papers/`                                                                                      | there is no paper where `papersDir` points. Create one with `npx paperlint new <name>`, or set `"papersDir"` in `paperlint.json`                                                                         |
+| hooks fail with `Cannot find module` in a fresh clone                                                                         | the hook commands run files in `node_modules`: run `npm install`                                                                                                                                         |
+| `paperlint: not built`                                                                                                        | installed from git with `--ignore-scripts`, or a clone before building: run `npm run build` in the package                                                                                               |
+| a skill does not show up in Claude Code                                                                                       | its name was already taken in `.claude/skills/`. `init` names it and leaves it alone; rename or remove yours and run `npx paperlint init` again                                                          |
+| **every** shell command is blocked in Claude Code                                                                             | `paper-edit-guard` cannot parse the root `paperlint.json` (merge-conflict markers, a typo), and refuses rather than guess. Fix it with a normal file edit — file edits are not blocked                   |
+| a Write of a new file is denied: "… is at the root of a paper folder" or "… is loose at the top of the paper's repro/ folder" | `paper-folder-layout` refuses to create an entry the paper layout does not allow; the reason says where it goes. Write it there. Existing files are never refused, and the hook does not see shell moves |
+| anything else                                                                                                                 | `npx paperlint doctor` — it checks the setup and exits non-zero on anything miswired                                                                                                                     |

package/docs/layout.md

@@ -0,0 +1,154 @@
+# Where things live, and what checks them when
+
+A paper moves through eight stages ([the flow](#the-flow)). Each stage writes into one
+place, and a check guards that place. This page is the map: the places, who writes each one, and the
+moment each check runs. The skills, stage by stage: [`skills.md`](skills.md).
+
+## The flow
+
+Each box names the stage's skills, what it writes, and what checks it. Stage 3 is drawn from the
+inside: a study's pre-registration and its human labels are made there.
+
+```mermaid
+flowchart TB
+  N["<b>paperlint new</b><br/>creates the paper folder<br/>checked from here on:<br/>every lint · paper/allowed-files-only<br/>every new file · hook paper-folder-layout"]
+  S1["<b>1 · idea</b><br/>research-ideate · map-prior-work<br/>analyze-sibling-paper<br/>writes: siblings/<br/>checked by: sibling/frontmatter"]
+  S2["<b>2 · venue</b><br/>find-venue · plan-paper-timeline<br/>study-accepted-papers, mode A or B<br/>writes: paperlint.json, a report in reviews/<br/>checked by: review/frontmatter"]
+  V[("<b>#lt;papers-root#gt;/venues/#lt;venue#gt;/</b><br/>beside the papers, not in one:<br/>the venue's accepted papers,<br/>shared by every paper aimed at it<br/>checked by: nothing")]
+  subgraph S3["3 · study: repro/#lt;slug#gt;-YYYY-MM-DD/"]
+    direction TB
+    D["<b>design</b> · build-benchmark<br/>writes: the study's README.md<br/>checked by: repro/allowed-files-only"]
+    P["<b>pre-register</b> · build-benchmark<br/>writes: prereg.json, before the draw<br/>checked by: study/declare-sample (experimental, off)"]
+    A["<b>author check</b> · you see the drawn units<br/>writes: author_check in prereg.json<br/>checked by: study/declare-sample (experimental, off)"]
+    R["<b>run</b> · your scripts<br/>writes: the study folder,<br/>repro/tools/, repro/data/<br/>checked by: repro/allowed-files-only"]
+    L["<b>labels</b> · build-label-page<br/>a phone page; the answers go<br/>into the study's data/"]
+    Y["<b>analysis</b> · build-benchmark<br/>writes: the numbers, NOTES.md"]
+    D --> P --> A --> R --> L --> Y
+  end
+  S4["<b>4 · draft</b><br/>draft-paper · argument-arc · tighten-paper<br/>writes: paper.tex, sections/, figures/<br/>checked by: the tex/* rules<br/>hook paper-edit-guard: no shell writes"]
+  S5["<b>5 · review</b><br/>grade-paper-writing · verify-citations<br/>pc-panel-review · harden-paper<br/>study-accepted-papers, mode C or D<br/>writes: reviews/, the scorecard<br/>in PIPELINE-STATUS.md<br/>checked by: review/frontmatter"]
+  S6["<b>6 · submit</b><br/>paperlint build · submit-paper<br/>writes: paper.pdf, _build/,<br/>versions/, submission/<br/>checked by: format/page-limit, pdf/*,<br/>anonymity/identity, paper/stages"]
+  S7["<b>7 · camera-ready</b><br/>camera-ready<br/>writes: versions/, talk/<br/>checked by: paper/stages, talk/*"]
+  S8["<b>8 · extend</b><br/>extend-paper<br/>writes: a new paper folder"]
+  N --> S1 --> S2 --> D
+  Y --> S4 --> S5 --> S6 --> S7 --> S8
+  S2 -. fills .-> V
+  V -. read again .-> S5
+```
+
+The cylinder is a venue's corpus of accepted papers: it lives beside the papers, not inside one
+([`venues.md`](venues.md)).
+
+## The map
+
+The papers directory is `papersDir` in the project's `paperlint.json` (default `papers/`). A folder
+in it is a paper when it holds `PIPELINE-STATUS.md`, `paper.tex` or `paperlint.json`; `paperlint new`
+creates one.
+
+<!-- layout:begin — drawn from src/domain/paper-layout.ts (PAPERS_LAYOUT_TREE); src/layout-docs.test.ts fails when this block differs -->
+
+```text
+<papers-root>/
+├── venues/                            ← outside every paper folder: one folder per venue
+│   └── <venue>/                       ← that venue's accepted papers, shared by every paper aimed at it
+└── <paper>/                           ← one folder per paper, named after the work; its root holds only what is below
+    ├── PIPELINE-STATUS.md             ← the paper's one live-state file: stages, plan, scorecard
+    ├── paper.tex                      ← the source; `paperlint build` compiles it
+    ├── paperlint.json                 ← the paper's settings
+    ├── README.md                      ← what the paper is
+    ├── CLAUDE.md                      ← the paper's agent rules
+    ├── CLAIMS.md                      ← the claims ledger
+    ├── NOTES.md                       ← each number in the paper → the data it comes from
+    ├── SUBMIT-CHECKLIST.md            ← the venue's format and submission mechanics
+    ├── .gitignore                     ← keeps the build's byproducts out of git
+    ├── paper.pdf                      ← the built PDF
+    ├── *.tex *.bib *.cls *.sty *.bst  ← what TeX and bibtex look up beside paper.tex
+    ├── _build/                        ← the facts `paperlint build` writes
+    ├── versions/                      ← each stage's frozen PDF and source
+    ├── reviews/                       ← dated reviews and pass reports
+    ├── siblings/                      ← the cards of competing papers
+    ├── research/                      ← dated research and decision records
+    ├── repro/                         ← the reproduction artifact
+    │   ├── README.md                  ← the index: one line per study
+    │   ├── .gitignore                 ← keeps the scripts' byproducts out of git
+    │   ├── tools/                     ← scripts used across the paper (numbers, figures, anonymity check, harnesses)
+    │   ├── data/                      ← shared data (tables, caches)
+    │   └── <slug>-YYYY-MM-DD/         ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)
+    │       └── README.md              ← required: what it asks, how to run it, what it found
+    ├── figures/                       ← graphics and their sources
+    ├── sections/                      ← the body, when it is split
+    ├── talk/                          ← the talk's files
+    ├── submission/                    ← forms, portal records, mail with the venue, the anonymized upload
+    └── extra/                         ← anything; never judged
+```
+
+<!-- layout:end -->
+
+Two places with similar names are not in this drawing:
+
+- `venues/` at the **project root** holds your own venue presets and their cards
+  (`venues/<name>.jsonc`, `venues/<name>.md`), for a venue paperlint does not ship.
+- `<papers-root>/venues/<venue>/` (drawn above) holds a venue's **accepted papers**.
+
+Both are explained in [`venues.md`](venues.md).
+
+## Each place: who writes it, and what checks it
+
+"Stage" is the stage of [the pipeline](#the-flow) that writes the place first.
+"Checked by" is the rule `paperlint lint` runs over it; "nothing" means no rule reads its content.
+
+| place                                 | stage            | written by                                                                                                                                                                                       | checked by                                                                                                                           |
+| ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `<papers-root>/venues/<venue>/`       | 2 venue          | `study-accepted-papers`, its first run for that venue (mode A, usually)                                                                                                                          | nothing ([why](venues.md#what-checks-it))                                                                                            |
+| the paper folder's root               | before 1         | `paperlint new`: the three files, and an empty `.gitkeep` folder for `reviews/`, `research/`, `figures/`, `versions/`, `submission/`, `repro/tools/`, `repro/data/` (`repro/` gets a stub index) | [`paper/allowed-files-only`](rules/paper/allowed-files-only.md); the hook `paper-folder-layout` refuses a new stray entry            |
+| `PIPELINE-STATUS.md`                  | every stage      | `paperlint new`, then `paper-pipeline`, `paper-status`; `study-accepted-papers` (the scorecard)                                                                                                  | `paper/stages`, `paper/source`, [`cycle/stage`](rules/cycle/stage.md) ([rules](rules.md))                                            |
+| `paperlint.json`                      | before 1, then 2 | `paperlint new`; `find-venue` names the venue                                                                                                                                                    | `paperlint lint` refuses an unknown key; [`cycle/record`](rules/cycle/record.md)                                                     |
+| `siblings/`                           | 1 idea           | `map-prior-work`, `analyze-sibling-paper`                                                                                                                                                        | `sibling/frontmatter` ([records](configuration.md#records-in-frontmatter-checked-by-shipped-json-schemas))                           |
+| `reviews/`                            | 2, then 4–5      | `study-accepted-papers` (its report), `grade-paper-writing`, `cold-read-diff`, the review skills                                                                                                 | `review/frontmatter` ([records](configuration.md#records-in-frontmatter-checked-by-shipped-json-schemas))                            |
+| `research/`                           | any              | you and the skills: dated research and decision records                                                                                                                                          | nothing                                                                                                                              |
+| `repro/`, its top                     | 3 study          | `build-benchmark`, your scripts                                                                                                                                                                  | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md); the hook `paper-folder-layout` refuses a new loose entry            |
+| `repro/<slug>-YYYY-MM-DD/`            | 3 study          | `build-benchmark` (the design, in its `README.md`)                                                                                                                                               | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md): the dated name, and a `README.md` in it                             |
+| `repro/<slug>-YYYY-MM-DD/prereg.json` | 3 study          | `build-benchmark`, before the sample is drawn; you add the author's check                                                                                                                        | [`study/declare-sample`](rules/study/declare-sample.md)                                                                              |
+| `repro/<slug>-YYYY-MM-DD/data/`       | 3 study          | `build-label-page` exports the labels here                                                                                                                                                       | nothing                                                                                                                              |
+| `repro/tools/`, `repro/data/`         | 3 study          | your scripts; `paperlint build` keeps `repro/data/references-cache.json`                                                                                                                         | nothing inside them                                                                                                                  |
+| `NOTES.md`                            | 3, then 4        | you: each number → the data it comes from; `build-label-page` adds a line per label file                                                                                                         | nothing                                                                                                                              |
+| `paper.tex`, `sections/`, `*.bib`     | 4 draft          | `draft-paper`, `argument-arc`, `tighten-paper`                                                                                                                                                   | the `tex/*`, `paper/*` and `bib/*` rules ([rules](rules.md)); the hook `paper-edit-guard` refuses a shell write                      |
+| `CLAIMS.md`, `figures/`               | 4 draft          | you                                                                                                                                                                                              | nothing                                                                                                                              |
+| `paper.pdf`, `_build/`                | 6 submit         | `paperlint build`                                                                                                                                                                                | `pdf/*`, [`format/page-limit`](rules/format/page-limit.md), [`anonymity/identity`](rules/anonymity/identity.md), the reference rules |
+| `versions/`                           | 6, then 7        | you, at submission and at camera-ready (`submit-paper` says how): the frozen PDF and source of each stage                                                                                        | `paper/stages`, `paper/source`                                                                                                       |
+| `submission/`, `SUBMIT-CHECKLIST.md`  | 6 submit         | you, while `submit-paper` and `submission-portal` do the submitting: forms, portal records, mail with the venue                                                                                  | [`cycle/evidence`](rules/cycle/evidence.md), for the files a closed cycle names                                                      |
+| `talk/`                               | 7 camera-ready   | you                                                                                                                                                                                              | the `talk/*` rules ([talk](talk.md))                                                                                                 |
+| `extra/`                              | any              | you                                                                                                                                                                                              | nothing, ever                                                                                                                        |
+
+## What runs when
+
+A check runs at one of four moments:
+
+- **Before a write** — a Claude Code hook. It sees an agent's Edit or Write, not a shell `mv` or a
+  script, so it saves a round trip and guarantees nothing.
+- **On lint** — `paperlint lint`, when you run it. Every rule runs, whatever wrote the files. This is
+  the guarantee. No hook runs it for you.
+- **In CI** — the same lint, on every push, if the project has the workflow `paperlint init` offers.
+  The lint-only job skips what needs a build (pages, fonts, references).
+- **On demand** — a skill, when you ask for what it does. A skill stops nothing; it writes.
+
+| what                                                                                        | kind  | when it runs                                                | what it stops                                                                                                                  |
+| ------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `paper-folder-layout`                                                                       | hook  | before an agent creates a file (Edit, Write)                | a new entry the layout does not allow, at a paper's root or the top of its `repro/`; never an existing file                    |
+| `paper-edit-guard`                                                                          | hook  | before an agent's shell command                             | a shell command that writes or moves a paper's source, which would skip the hooks that run after an edit                       |
+| `paper-skills-nudge`                                                                        | hook  | after an agent edits a paper's source                       | nothing: it shows the agent the pre-submit checklist                                                                           |
+| `paper-status-gates`                                                                        | hook  | after an agent edits a paper's source                       | nothing: it prints the paper's readiness and its unrun gates, for a person reading the transcript                              |
+| [`paper/allowed-files-only`](rules/paper/allowed-files-only.md)                             | rule  | every `paperlint lint`, and CI                              | a stray file or folder at a paper's root (error)                                                                               |
+| [`repro/allowed-files-only`](rules/repro/allowed-files-only.md)                             | rule  | every `paperlint lint`, and CI                              | a loose entry at the top of `repro/`, an undated study folder, a study folder without `README.md` (error)                      |
+| [`study/declare-sample`](rules/study/declare-sample.md)                                     | rule  | every `paperlint lint`, and CI, once a paper turns it on    | a study's `prereg.json` without its population, strata, screens, coverage or the author's check (experimental, off by default) |
+| [`paper/folder-venue-leftover`](rules/paper/folder-venue-leftover.md)                       | rule  | every `paperlint lint`, and CI                              | nothing: it warns when the folder is named after another venue                                                                 |
+| `review/frontmatter`, `sibling/frontmatter`                                                 | rule  | every `paperlint lint`, and CI                              | a review whose findings break the schema (error); a sibling card that does not say how much was read (warning)                 |
+| `paper/stages`, `paper/source`                                                              | rule  | every `paperlint lint`, and CI                              | a stage whose frozen PDF or source is missing or changed (error)                                                               |
+| the rules on the source (`tex/*`, `paper/*`, `bib/*`)                                       | rule  | every `paperlint lint`, and CI                              | what each one's [row](rules.md) says                                                                                           |
+| the rules on what `paperlint build` measured (`pdf/*`, `format/page-limit`, the references) | rule  | every `paperlint lint` after a build; CI's full job         | a PDF over the page limit, in the wrong font or format, or with a bad reference                                                |
+| `study-accepted-papers`                                                                     | skill | when you ask; stage 2 (modes A, B) and stage 5 (modes C, D) | nothing: it fills the venue's corpus, and writes the strong-accept scorecard in `PIPELINE-STATUS.md`                           |
+| `build-benchmark`                                                                           | skill | when you ask; stage 3                                       | nothing: it writes the study's design and its `prereg.json`                                                                    |
+| `build-label-page`                                                                          | skill | when you ask; stage 3                                       | nothing: it builds the labelling page, and exports the answers into the study's `data/`                                        |
+
+The hooks are wired by `paperlint init` ([`install.md`](install.md)). A rule's level and options:
+[`rules.md`](rules.md).

package/docs/optional-rules.md

@@ -8,10 +8,11 @@ rules apply to that paper. The root `paperlint.json` can turn it on for every pa
 with a block ([`configuration.md`](configuration.md#the-rules-key-turning-rules-on-and-off)); a
 paper's own file still has the last word for that paper.
 
-| rule                                            | what it checks                                                                              | who needs it                                                                                                                                                                            |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pdf/last-page-balance`                         | the two columns of the last page end at about the same height                               | two-column papers whose publisher asks for it — see below                                                                                                                               |
-| [`tex/heading-case`](rules/tex/heading-case.md) | the words of the paper's title and of each heading are in the capitalization the venue asks | papers whose venue names a case style paperlint builds; only the AgenticDev preset turns it on (`chicago-headline` for the title and every heading) — [page](rules/tex/heading-case.md) |
+| rule                                                    | what it checks                                                                                                             | who needs it                                                                                                                                                                            |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pdf/last-page-balance`                                 | the two columns of the last page end at about the same height                                                              | two-column papers whose publisher asks for it — see below                                                                                                                               |
+| [`tex/heading-case`](rules/tex/heading-case.md)         | the words of the paper's title and of each heading are in the capitalization the venue asks                                | papers whose venue names a case style paperlint builds; only the AgenticDev preset turns it on (`chicago-headline` for the title and every heading) — [page](rules/tex/heading-case.md) |
+| [`study/declare-sample`](rules/study/declare-sample.md) | experimental: a study's `prereg.json` declares its population, screens, coverage and the author's check of the drawn units | papers with a sampled study; no preset turns it on — [page](rules/study/declare-sample.md)                                                                                              |
 
 ## `pdf/last-page-balance`
 

package/docs/references.md

@@ -61,18 +61,21 @@ is stale and `paper/sources-fresh` says so: build again to write it. A database
 the paper directory, on its search path (`BIBINPUTS`), is not read: the step says which and
 `paper/refs-checked` warns.
 
-## `repro/references-cache.json` — commit it
+## `repro/data/references-cache.json` — commit it
 
 Asking five services about every entry is slow. DBLP asks clients to pause between requests, and a
 slow service is retried. Before this cache existed, a 27-reference paper spent 217 seconds on the
 check, on every build, and a 51-reference paper did not finish inside a 12-minute CI job
 ([#107](https://github.com/zernie/paperlint/issues/107)).
 
-So the build keeps every answer it receives in `<paper>/repro/references-cache.json`, and the next
+So the build keeps every answer it receives in `<paper>/repro/data/references-cache.json`, and the next
 build asks only what that file cannot answer:
 
 - An unchanged bibliography whose answers are under 30 days old asks nothing and makes no network request at all, not even the check
   for whether the services can be reached.
+- A cache at the old place, `repro/references-cache.json`, is not read: `repro/allowed-files-only` reports
+  it with the command that moves it (`git mv repro/references-cache.json repro/data/`). Until it is
+  moved, the build asks every question again.
 - Adding or editing an entry asks only about that entry. Answers are stored per identifier (DOI,
   arXiv id, or title), so changing an entry's DOI or title is what makes it be asked again.
 - A request that failed is not an answer and is not stored, so the next build asks it again.

package/docs/rules/paper/allowed-files-only.md

@@ -0,0 +1,192 @@
+# paper/allowed-files-only
+
+**Level:** error · **Reads:** the paper folder's root (a directory listing), its `paperlint.json` ·
+**Reported on:** the first line of the paper's `PIPELINE-STATUS.md`, once per stray entry
+
+## What it catches
+
+A file or folder at the root of a paper folder that is not part of paperlint's layout. The root
+holds a small, known set; every kind of material has one folder; anything else goes into `extra/`,
+which is never judged.
+
+It runs on every `paperlint lint` and in CI, from the moment `paperlint new` creates the folder; a
+hook refuses a new stray entry before it is written. Which stage writes each place, and what checks
+it: [the map](../../layout.md).
+
+<!-- layout:begin — drawn from src/domain/paper-layout.ts (PAPER_LAYOUT_TREE); src/layout-docs.test.ts fails when this block differs -->
+
+```text
+<paper>/
+├── PIPELINE-STATUS.md             ← the paper's one live-state file: stages, plan, scorecard
+├── paper.tex                      ← the source; `paperlint build` compiles it
+├── paperlint.json                 ← the paper's settings
+├── README.md                      ← what the paper is
+├── CLAUDE.md                      ← the paper's agent rules
+├── CLAIMS.md                      ← the claims ledger
+├── NOTES.md                       ← each number in the paper → the data it comes from
+├── SUBMIT-CHECKLIST.md            ← the venue's format and submission mechanics
+├── .gitignore                     ← keeps the build's byproducts out of git
+├── paper.pdf                      ← the built PDF
+├── *.tex *.bib *.cls *.sty *.bst  ← what TeX and bibtex look up beside paper.tex
+├── _build/                        ← the facts `paperlint build` writes
+├── versions/                      ← each stage's frozen PDF and source
+├── reviews/                       ← dated reviews and pass reports
+├── siblings/                      ← the cards of competing papers
+├── research/                      ← dated research and decision records
+├── repro/                         ← the reproduction artifact
+│   ├── README.md                  ← the index: one line per study
+│   ├── .gitignore                 ← keeps the scripts' byproducts out of git
+│   ├── tools/                     ← scripts used across the paper (numbers, figures, anonymity check, harnesses)
+│   ├── data/                      ← shared data (tables, caches)
+│   └── <slug>-YYYY-MM-DD/         ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)
+│       └── README.md              ← required: what it asks, how to run it, what it found
+├── figures/                       ← graphics and their sources
+├── sections/                      ← the body, when it is split
+├── talk/                          ← the talk's files
+├── submission/                    ← forms, portal records, mail with the venue, the anonymized upload
+└── extra/                         ← anything; never judged
+```
+
+<!-- layout:end -->
+
+`paperlint new` makes the folders a paper uses from its first day: `versions/`, `reviews/`, `research/`,
+`repro/` (with its index, `tools/` and `data/`), `figures/` and `submission/`, each empty one with a
+`.gitkeep` so the layout is in the first commit. It leaves out `siblings/` (made with the first
+competitor's card), `sections/` (when the body is split), `talk/` (when the paper declares a talk),
+`extra/` (never judged) and `_build/` (the build's). No rule reports a `.gitkeep` inside these folders.
+
+`extra/` is never judged by any rule, not only this one: `paperlint lint` does not read a folder named
+`extra/`, wherever it is. An archived snapshot of an older paper kept there, with its own
+`PIPELINE-STATUS.md`, is not taken for a second paper.
+
+Never reported: the byproducts a TeX run leaves beside `paper.tex` (`paper.aux`, `.log`, `.out`,
+`.toc`, `.lof`, `.lot`, `.lol`, `.loa`, `.fls`, `.xdv`, `.dvi`, `.synctex.gz`; bibtex's `.bbl`, `.blg`;
+makeindex's `.idx`, `.ind`, `.ilg`; glossaries' `.glo`, `.gls`, `.glg`, `.acn`, `.acr`, `.alg`, `.ist`,
+`.nlo`, `.nls`; biber's `.bcf`, `.run.xml`; beamer's `.nav`, `.snm`, `.vrb`; latexmk's `.fdb_latexmk`;
+the list follows latexmk's clean lists; only under the job name `paper`), the `.aux` that
+`\include{chapter}` writes beside a root `chapter.tex`, and the operating system's `.DS_Store` and
+`Thumbs.db`.
+
+A venue's corpus of accepted papers is not in the paper folder at all: it is shared by every paper
+that targets the venue, in `<papers-root>/venues/<venue>/` ([what it holds](../../venues.md)).
+
+The paper's settings can move three entries, and what they name at the root is allowed while they
+name it: `pdf` (the built PDF under another path), `talk.dir` (another talk folder), and a preset
+file of the paper's own (`extends`, or the `extends` of any of its `cycles`).
+
+## Why
+
+A paper folder collects files the way a desk does: a plan, mails, three drafts of the PDF, an old
+attempt's checklist, a corpus. After a few months nobody can say which file is current, where the
+evidence for a decision is, or where a new thing goes, and an agent asked to continue the work reads
+the wrong one. A fixed root is what build tools settled on long ago (Cargo, Maven): a known set, one
+folder per kind of material, and one place for the rest.
+
+A structure linter over file names cannot do this from inside ESLint: ESLint is handed only the files
+paperlint lints, so a stray `.pdf`, `.py` or `.md` is never one of them. The rule lists the folder
+itself.
+
+## Examples
+
+Failing: a plan beside the paper.
+
+```text
+papers/agent-rule-drift/PIPELINE-STATUS.md
+  1:1  error  `PLAN.md` is at the root of a paper folder (the folder holding PIPELINE-STATUS.md),
+              and that root holds only paperlint's layout. Where it goes: a section of
+              PIPELINE-STATUS.md — the paper's one live-state file holds its stages, its plan
+              ("Plan / now") and its scorecard; move what is still live there and delete the file.
+The layout (extra/ takes anything and is never judged; the build's paper.* byproducts are never reported):
+<paper>/
+├── PIPELINE-STATUS.md             ← the paper's one live-state file: stages, plan, scorecard
+…
+└── extra/                         ← anything; never judged
+Rule paper/allowed-files-only: https://github.com/zernie/paperlint/blob/main/docs/rules/paper/allowed-files-only.md  paper/allowed-files-only
+```
+
+Each message names the entry and where it goes, and draws the whole layout above, so it reads on its own. A
+name met in real paper folders has one destination:
+
+| entry                      | where it goes                                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `PLAN.md`, `plans/`        | a section of `PIPELINE-STATUS.md` ("Plan / now")                                                           |
+| `DECISION-LOG.md`          | `research/`                                                                                                |
+| `EMAILS.md`                | `submission/`                                                                                              |
+| `data/`                    | `repro/data/`                                                                                              |
+| `artifact/`                | `repro/` (scripts in `repro/tools/`, data in `repro/data/`); the anonymized upload copy in `submission/`   |
+| `archive/`                 | `versions/` for frozen PDFs, `submission/` for an earlier attempt's forms and mails, `extra/` for the rest |
+| `venue-corpus/`, `venues/` | `<papers-root>/venues/<venue>/`, outside the paper folder                                                  |
+
+Any other name gets the choice by what it is: a record or research → `research/`; about submitting
+→ `submission/`; the paper's live state → a section of `PIPELINE-STATUS.md`; reproduction → `repro/`;
+a frozen PDF of a stage → `versions/`; unclear → `extra/`.
+
+Passing: the folder `paperlint new` writes (`PIPELINE-STATUS.md`, `paper.tex`, `paperlint.json`),
+and any folder holding only the entries above.
+
+## Options / preset fields
+
+No rule options. The paper's `pdf`, `talk.dir` and own preset files add what they name (above).
+
+## What it does not check
+
+- What is inside the allowed folders. `reviews/`, `siblings/` and `repro/` have their own rules
+  ([`repro/allowed-files-only`](../repro/allowed-files-only.md) for `repro/`); the rest are free.
+- Whether a `.tex` at the root is included by anything: a fragment the body no longer `\input`s
+  passes. Old versions of the source belong in `versions/`.
+- A folder without `PIPELINE-STATUS.md`: it is not a paper to paperlint.
+
+## The hook: a new stray entry is refused before it is written
+
+`paperlint init` also wires the hook `paper-folder-layout` (PreToolUse on `Edit|Write|MultiEdit`,
+`plugin/hooks/hooks.json`). When an agent is about to create a file that would add an entry the
+layout does not allow — at a paper folder's root, or at the top of its `repro/`
+([`repro/allowed-files-only`](../repro/allowed-files-only.md)) — the hook denies the call, and the reason it gives is the
+rule's own message: where the entry goes, and the layout drawn. The agent writes the file where it
+belongs instead, in the same turn. The text comes from the functions the rules report with
+(`strayTexts`, `reproTexts`); there is no second list.
+
+What it never refuses:
+
+- **a file that already exists** — editing is never blocked, wherever the file is, so 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 a stray one: the entry is not new, and the
+  rule names it once;
+- anything outside a paper folder.
+
+A new study folder in `repro/` is started with its `README.md`; any other first file in it is
+refused with `repro/allowed-files-only`'s "without a README.md" message.
+
+🔴 **What it cannot see: the shell.** `mv`, `cp`, `git mv`, or a script that writes files are not an
+Edit or a Write, so the hook never sees them. The guarantee is the lint: both rules fail `paperlint
+lint`, and 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
+(an existing one is never refused).
+
+Its first step is cheap: it looks for the nearest folder above the target file that holds
+`PIPELINE-STATUS.md`, one file check per ancestor, and allows the call when there is none — no git,
+no settings, no lint before that. Measured on 2026-10-12: that step takes about 19 µs. The process
+around it is what every `paperlint hook` costs, the CLI's import: about 650 ms per write on the
+measuring machine, with or without a paper folder (`paper-skills-nudge`, a vigiles hook, measured 730
+to 850 ms on the same machine). The hook fails open: a payload it cannot read is reported on stderr
+and the call goes ahead.
+
+A project whose papers all live under one folder can skip the process for every other write by
+giving the hook's entry in its own `.claude/settings.json` an `if`, Claude Code's permission-rule
+filter, for example `"if": "Write(**/papers/**)"`. paperlint does not write one: where papers live is
+a project's choice, and a filter that misses a papers folder would make the hook silently dead there.
+
+## How to fix
+
+Move the entry where its message says, and update whatever names its path:
+
+```sh
+git mv papers/agent-rule-drift/EMAILS.md papers/agent-rule-drift/submission/EMAILS.md
+```
+
+To keep something as it is, move it under `extra/`. To switch the rule off for one paper, set it in
+that paper's `paperlint.json`:
+
+```json
+{ "rules": { "paper/allowed-files-only": "off" } }
+```