paperlint 10.2.0 → 10.4.0

package/docs/rules.md

@@ -3,58 +3,60 @@
 The README lists what each check catches in one line. This page says exactly which file each one
 reads and when it fails. Errors fail `paperlint lint`; warnings print and do not.
 
-| Rule                                                                  | Level                                                    | Reads                                                                             | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| --------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `paper/stages`                                                        | error                                                    | `PIPELINE-STATUS.md`                                                              | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `paper/source`                                                        | error                                                    | `PIPELINE-STATUS.md`                                                              | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| [`study/declare-sample`](rules/study/declare-sample.md)               | experimental; off unless a paper turns it on (`"error"`) | each study's `repro/<study>/prereg.json`                                          | a study's pre-registration does not declare its `population` (what the claim is about, source, size), the `strata` and what each of its `screens` removed per stratum value, its `coverage` (share 0–1 or null with a reason, and the strata it cannot reach), or the `author_check` of the drawn units (a doubtful verdict needs a recorded `decision`); reported on `PIPELINE-STATUS.md`, once per problem — [page](rules/study/declare-sample.md)                                                                                                   |
-| [`cycle/record`](rules/cycle/record.md)                               | error                                                    | `paperlint.json` (`cycles`)                                                       | the paper's attempts at venues (`cycles`, one entry per attempt) hold one source's deadlines out of order (registration ≤ submission ≤ resubmission < notification < camera-ready), or copy a portal reading the venue's preset carries; reported on `PIPELINE-STATUS.md`. A record that does not parse — a bare date, two open cycles, an unknown key — is refused by `paperlint lint` itself before any rule runs, exit 2 — [page](rules/cycle/record.md)                                                                                            |
-| [`cycle/evidence`](rules/cycle/evidence.md)                           | error                                                    | `paperlint.json` (`cycles`) → the paper folder                                    | a closed cycle (`accepted`, `rejected`, `withdrawn`) or a deadline's `override` names an `evidence` file — the decision mail, the reviews, the withdrawal note, the chairs' mail — that is not in the paper folder; reported on `PIPELINE-STATUS.md` — [page](rules/cycle/evidence.md)                                                                                                                                                                                                                                                                 |
-| [`cycle/stage`](rules/cycle/stage.md)                                 | error                                                    | `PIPELINE-STATUS.md` → `paperlint.json` (`cycles`)                                | with `cycles` declared, a stage names no `cycle: <id>`, names one no cycle has, or a `submitted`/`camera-ready` stage belongs to a cycle whose `phase` is still `porting` — [page](rules/cycle/stage.md)                                                                                                                                                                                                                                                                                                                                               |
-| [`cycle/port-done`](rules/cycle/port-done.md)                         | error                                                    | `paper.tex` → `paperlint.json` (`cycles`) → the preset's `template`               | the current cycle still declares `"phase": "porting"` (which silences the venue's format rules) while the `\documentclass` is already the venue's template: the port is done, drop the phase — [page](rules/cycle/port-done.md)                                                                                                                                                                                                                                                                                                                        |
-| [`paper/folder-venue-leftover`](rules/paper/folder-venue-leftover.md) | warn                                                     | the folder name → `paperlint.json`                                                | the paper's folder is named after another shipped venue than the one it extends (`papers/aisec-2026/` for a paper now set for AIDC); reported on `PIPELINE-STATUS.md` — [page](rules/paper/folder-venue-leftover.md)                                                                                                                                                                                                                                                                                                                                   |
-| [`paper/allowed-files-only`](rules/paper/allowed-files-only.md)       | error                                                    | the paper folder's root listing → `paperlint.json`                                | a file or folder at the paper's root is not part of the layout (`PLAN.md`, `archive/`, a stray PDF); reported on `PIPELINE-STATUS.md`, once per entry, with where it goes; `extra/` takes anything — [page](rules/paper/allowed-files-only.md)                                                                                                                                                                                                                                                                                                         |
-| [`repro/allowed-files-only`](rules/repro/allowed-files-only.md)       | error                                                    | the listing of the paper's `repro/`                                               | an entry at the top of `repro/` is not `README.md`, `studies.json`, `.gitignore`, `tools/`, `data/` or a study folder named `<id>-<slug>` (or, in a paper without the registry, `<slug>-YYYY-MM-DD`), or a study folder has no `README.md`; reported on `PIPELINE-STATUS.md`, once per entry, with where it goes by kind (a script → `repro/tools/`, data → `repro/data/`, a note → its study or `research/`) — [page](rules/repro/allowed-files-only.md)                                                                                              |
-| [`repro/study-registered`](rules/repro/study-registered.md)           | error                                                    | the listing of the paper's `repro/`, `repro/studies.json`, `repro/README.md`      | a study folder with no row in `repro/studies.json`, a row whose folder is missing or not `<id>-<slug>`, a bad or repeated id, a title over 8 words, `done` without a result and an existing result file, `superseded` without an existing successor, or the index in `repro/README.md` out of sync with the registry; `paperlint studies new` and `paperlint studies index` write both — [page](rules/repro/study-registered.md)                                                                                                                       |
-| [`paper/sources-fresh`](rules/paper/sources-fresh.md)                 | warn                                                     | `paper.tex` → `_build/sources.json`                                               | the paper has not been built (no record of the files TeX read), or a file changed since the last build (its SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                                                                                                                                                                                               |
-| `paper/author-list`                                                   | error                                                    | `paper.tex` → `_build/references.json`, `_build/sources.json`                     | an entry's authors are not those of the version it cites — typically the arXiv preprint's list under a published venue. Checked online by `paperlint build` (DBLP), reported on the entry's own line (or at the top of `paper.tex`, naming the entry's file); silent without a current build record                                                                                                                                                                                                                                                    |
-| `paper/section-word`                                                  | warn                                                     | `paper.tex` and its body files                                                    | `§` or `\S\ref` instead of the word Section. **Fixable:** `--fix` writes `Section~\ref{…}` / `Section 5`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `paper/leading-zero`                                                  | warn                                                     | `paper.tex` and its body files                                                    | a decimal below 1 without its leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz. A number right after `¶` or `§` (`¶¶.42`) is a paragraph designator and is not reported; in a paragraph that cites numbers that way, another bare decimal is reported without a fix, with the zero as a suggestion. **Fixable**                                                                                          |
-| `paper/figure-ref-style`                                              | warn                                                     | `paper.tex` and its body files                                                    | `Fig.~\ref` and `Figure~\ref` mixed in one document; each minority occurrence is reported. **Fixable:** `--fix` writes the majority form                                                                                                                                                                                                                                                                                                                                                                                                               |
-| [`bib/reachable-entry`](rules/bib/reachable-entry.md)                 | warn                                                     | `paper.tex` → `_build/sources.json`: the databases the last build's bibtex opened | an entry has no doi, url or arXiv id — a reader has nothing to follow. Reported on the entry in the `filecontents` block of `paper.tex` that wrote its `.bib`, or at the top of `paper.tex` with the entry's file and line first; silent until a build records the paper; no fix, the link has to be looked up — [page](rules/bib/reachable-entry.md)                                                                                                                                                                                                  |
-| `paper/cite-exists`                                                   | error                                                    | `paper.tex` → `_build/references.json`                                            | an entry's doi or arXiv id resolves to nothing, or to a different work. Checked online by `paperlint build`; a work that was merely not found is not a finding                                                                                                                                                                                                                                                                                                                                                                                         |
-| `paper/refs-fresh`                                                    | error                                                    | `paper.tex` → `_build/references.json`                                            | the databases bibtex opened changed since the build checked them (their SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `paper/refs-checked`                                                  | warn                                                     | `paper.tex` → `_build/references.json`                                            | a build recorded the paper's databases and none has checked their references, or the last build could not (no network), or its bibtex typeset a key paperlint's reader did not read (an entry behind `%`, inside `@comment{…}`), or bibtex found a database outside the paper directory (`BIBINPUTS`) — so the two rules above did not run on it. Silent without a record of the build (`paper/sources-fresh` speaks)                                                                                                                                  |
-| `tex/future-promise`                                                  | warn                                                     | `paper.tex` and its body files                                                    | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `tex/acm-frontmatter-override`                                        | error                                                    | `paper.tex`                                                                       | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| [`tex/template`](rules/tex/template.md)                               | error                                                    | `paper.tex` → `paperlint.json`                                                    | the `\documentclass` is not the preset's `template` class, or lacks an option it names — [page](rules/tex/template.md)                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| [`tex/required-section`](rules/tex/required-section.md)               | error                                                    | `paper.tex` → `paperlint.json`                                                    | a section the preset requires (AIDC: «LLM Usage Statement», last) is missing or not where it must be — [page](rules/tex/required-section.md)                                                                                                                                                                                                                                                                                                                                                                                                           |
-| [`tex/heading-case`](rules/tex/heading-case.md)                       | optional; the AgenticDev preset sets `error`             | `paper.tex` and the files it includes                                             | a word in the paper's `\title` or in a `\section`, `\subsection`, `\subsubsection`, `\paragraph` or `\subparagraph` title is not in the style its scope asks: `{ "title", "headings", "levels"? }`, each `chicago-headline` (Conference Publishing's quote of the Chicago Manual of Style), `sentence` (first word only) or `any`. Words that are a preposition in one title and a particle in another (`up`, `on`, `in`) are not read mid-title. **Fixable:** `--fix` — [page](rules/tex/heading-case.md)                                             |
-| [`format/layout-override`](rules/format/layout-override.md)           | error                                                    | `paper.tex` → `paperlint.json`                                                    | the source changes the page layout the venue's template sets for the whole document — `geometry`, a layout `\setlength`, `\linespread`, `\baselinestretch` — [page](rules/format/layout-override.md)                                                                                                                                                                                                                                                                                                                                                   |
-| [`anonymity/identity`](rules/anonymity/identity.md)                   | error                                                    | `paper.tex` → `_build/paper.facts.json`                                           | a double-blind venue (`"blind": true`) and no `identity` declared, or a declared name, handle, email or project in the PDF's text, metadata or link targets — [page](rules/anonymity/identity.md)                                                                                                                                                                                                                                                                                                                                                      |
-| [`tex/venue-leftover`](rules/tex/venue-leftover.md)                   | warn                                                     | `paper.tex` → `paperlint.json`                                                    | the text names another shipped venue than the one the paper extends («Submission to VenueA 2026» in a paper now set for VenueB) — [page](rules/tex/venue-leftover.md)                                                                                                                                                                                                                                                                                                                                                                                  |
-| [`tex/claim-provenance`](rules/tex/claim-provenance.md)               | warn                                                     | `paper.tex`                                                                       | a sentence of the body states a number and does not say whose it is — no citation or link, no _we_/_our_, no `\ref` or "Table 2", no sample ("n = 134", "48 runs") — [page](rules/tex/claim-provenance.md)                                                                                                                                                                                                                                                                                                                                             |
-| [`tex/register`](rules/tex/register.md)                               | warn                                                     | `paper.tex` and the files it includes                                             | the body runs to a post's register: more than 0.8 sentences per 1000 words open with _And_, _So_, _But_, _Nor_, _Or_ or _Yet_ — the limit is an option — [page](rules/tex/register.md)                                                                                                                                                                                                                                                                                                                                                                 |
-| [`tex/contrast-frames`](rules/tex/contrast-frames.md)                 | warn                                                     | `paper.tex` and the files it includes → `paperlint.json`                          | contrast frames (_X, not Y_, _not X but Y_, _rather than_, _instead of_, _as opposed to_) per 10,000 words fall outside the band the venue preset's anchors set (AIDC: 0–10.4, from five accepted ACSAC papers); above it, each frame is reported too — [page](rules/tex/contrast-frames.md)                                                                                                                                                                                                                                                           |
-| [`tex/claim-emphasis`](rules/tex/claim-emphasis.md)                   | warn                                                     | `paper.tex` and the files it includes → `paperlint.json`                          | claims set in bold inside a sentence (six words or more, or holding a number; not a term, not a label opening a paragraph) per 10,000 words fall outside the preset's band (AIDC: 0–17.8); above it, each is reported too — [page](rules/tex/claim-emphasis.md)                                                                                                                                                                                                                                                                                        |
-| [`tex/relation-markers`](rules/tex/relation-markers.md)               | warn                                                     | `paper.tex` and the files it includes → `paperlint.json`                          | words that name how a sentence relates to the one before (_because_, _therefore_, _however_, _for example_ …) per 10,000 words fall outside the preset's band (AIDC: 25.4–135.0) — the floor that catches relations left to infer — [page](rules/tex/relation-markers.md)                                                                                                                                                                                                                                                                              |
-| `review/frontmatter`                                                  | error                                                    | `reviews/*.md`                                                                    | the review's frontmatter fails paperlint's JSON Schema — a `findings` record without `id`/`status`, an unknown field, or an **open** finding with no `cause` (`skill-defect` · `missing-skill` · `hook` · `rule`). A review with no `findings` key is not checked for findings                                                                                                                                                                                                                                                                         |
-| `sibling/frontmatter`                                                 | warn                                                     | `siblings/*.md` (not `README.md`)                                                 | a sibling card's frontmatter has no `read:` saying how much of the competing paper was read (`full` · `abstract` · `none`)                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `pdf/fresh`                                                           | error                                                    | `paper.tex` → `_build/paper.facts.json`                                           | the paper names a venue and the facts cannot be judged: not JSON, a schema other than 3, or they describe a PDF that is gone or differs from the one on disk (its SHA-256)                                                                                                                                                                                                                                                                                                                                                                             |
-| `pdf/profile`                                                         | error                                                    | `paper.tex` → `paperlint.json`                                                    | `paperlint.json` is not JSON or has an unknown key, its `extends` does not resolve (not found, a cycle, a chain longer than four, a preset that fails the schema, an npm name), it names no `kind` while the preset has kinds, or names a kind the preset does not have                                                                                                                                                                                                                                                                                |
-| `pdf/fonts`                                                           | error                                                    | `paper.tex` → `_build/paper.facts.json`                                           | a font the pages draw is Type 3 or not embedded, or no font starts with the family the venue preset names for body text (`fonts_text`) or headings (`fonts_title`)                                                                                                                                                                                                                                                                                                                                                                                     |
-| `pdf/geometry`                                                        | error                                                    | `paper.tex` → `_build/paper.facts.json`                                           | the page width or height is more than `dimTol` (default 0.05 in) off the preset's, or the column count differs                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| [`format/page-limit`](rules/format/page-limit.md)                     | error                                                    | `paper.tex` → `_build/paper.facts.json`                                           | body or reference pages exceed the limits of the paper's kind. With `body_ends_at: "references"` (AIDC) the body ends at the references or the appendix, whichever comes first — found by hyperref's anchors, then the heading line — and the page it ends on counts when body text stands above the heading; with `appendix_in_body` too (MSR) the appendix is body wherever it sits and the reference pages are the ones holding only references; an end it cannot find, or signals that disagree, are reported — [page](rules/format/page-limit.md) |
-| [`pdf/body-size`](rules/pdf/body-size.md)                             | error                                                    | `paper.tex` → `_build/paper.facts.json`                                           | the body font size is more than `body_pt_tol` off the preset's, or the reference font size is outside the preset's range widened by `body_pt_tol`. banal reads 0.3 pt above the size the glyphs are set in; checked on five built accepted papers (none reported) and three variants one size off (each reported) — [page](rules/pdf/body-size.md)                                                                                                                                                                                                     |
-| `pdf/measured`                                                        | warn                                                     | `paper.tex` → `_build/paper.facts.json`                                           | the paper's `paperlint.json` names no venue preset yet; or it names one and there are no facts (it was not built), or the facts carry no page geometry (banal was not found) — so the checks above did not run                                                                                                                                                                                                                                                                                                                                         |
-| [`talk/profile`](rules/talk/profile.md)                               | error                                                    | `paper.tex` → `paperlint.json`                                                    | the paper declares `talk` and names no preset, the preset has no `talk` block, the mode is not one the venue allows, or the venue sets no talk slot for the paper's kind — [page](rules/talk/profile.md)                                                                                                                                                                                                                                                                                                                                               |
-| [`talk/required-files`](rules/talk/required-files.md)                 | error                                                    | `paper.tex` → `paperlint.json`, the talk folder                                   | a file the venue requires for the paper's talk mode (video, one-slide, captions…) is not in the talk folder — [page](rules/talk/required-files.md)                                                                                                                                                                                                                                                                                                                                                                                                     |
-| [`talk/undeclared`](rules/talk/undeclared.md)                         | warn                                                     | `paper.tex` → the paper's `talk/` folder                                          | an `.mp4` sits in `talk/` and the paper declares no `talk`, so nothing checks it — [page](rules/talk/undeclared.md)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| [`talk/duration`](rules/talk/duration.md)                             | error                                                    | `paper.tex` → the talk video                                                      | the video runs longer than the slot's `talk_s_max`, or its audio track is more than 1 s off the video's length — [page](rules/talk/duration.md)                                                                                                                                                                                                                                                                                                                                                                                                        |
-| [`talk/duration-floor`](rules/talk/duration-floor.md)                 | warn                                                     | `paper.tex` → the talk video                                                      | the video runs shorter than the slot's `talk_s_min` — [page](rules/talk/duration-floor.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| [`talk/video-format`](rules/talk/video-format.md)                     | error                                                    | `paper.tex` → the talk video                                                      | the video is not ISO media, is QuickTime where the venue asks for MP4, is under `min_height_px`, or over `max_bytes` — [page](rules/talk/video-format.md)                                                                                                                                                                                                                                                                                                                                                                                              |
-| [`talk/one-slide-size`](rules/talk/one-slide-size.md)                 | error                                                    | `paper.tex` → the one-slide PNG                                                   | the one-slide image is not the size the paper or the preset states, or not a PNG — [page](rules/talk/one-slide-size.md)                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| [`talk/captions-cover`](rules/talk/captions-cover.md)                 | warn                                                     | `paper.tex` → the captions and the video                                          | the captions start late, end early or leave a long gap (uncalibrated thresholds) — [page](rules/talk/captions-cover.md)                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Rule                                                                      | Level                                                    | Reads                                                                                                  | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper/stages`                                                            | error                                                    | `PIPELINE-STATUS.md`                                                                                   | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `paper/source`                                                            | error                                                    | `PIPELINE-STATUS.md`                                                                                   | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`study/declare-sample`](rules/study/declare-sample.md)                   | experimental; off unless a paper turns it on (`"error"`) | each study's `repro/<study>/prereg.json`                                                               | a study's pre-registration does not declare its `population` (what the claim is about, source, size), the `strata` and what each of its `screens` removed per stratum value, its `coverage` (share 0–1 or null with a reason, and the strata it cannot reach), or the `author_check` of the drawn units (a doubtful verdict needs a recorded `decision`); reported on `PIPELINE-STATUS.md`, once per problem — [page](rules/study/declare-sample.md)                                                                                                                                                                                                                                                                                              |
+| [`cycle/record`](rules/cycle/record.md)                                   | error                                                    | `paperlint.json` (`cycles`)                                                                            | the paper's attempts at venues (`cycles`, one entry per attempt) hold one source's deadlines out of order (registration ≤ submission ≤ resubmission < notification < camera-ready), or copy a portal reading the venue's preset carries; reported on `PIPELINE-STATUS.md`. A record that does not parse — a bare date, two open cycles, an unknown key — is refused by `paperlint lint` itself before any rule runs, exit 2 — [page](rules/cycle/record.md)                                                                                                                                                                                                                                                                                       |
+| [`cycle/evidence`](rules/cycle/evidence.md)                               | error                                                    | `paperlint.json` (`cycles`) → the paper folder                                                         | a closed cycle (`accepted`, `rejected`, `withdrawn`) or a deadline's `override` names an `evidence` file — the decision mail, the reviews, the withdrawal note, the chairs' mail — that is not in the paper folder; reported on `PIPELINE-STATUS.md` — [page](rules/cycle/evidence.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [`cycle/stage`](rules/cycle/stage.md)                                     | error                                                    | `PIPELINE-STATUS.md` → `paperlint.json` (`cycles`)                                                     | with `cycles` declared, a stage names no `cycle: <id>`, names one no cycle has, or a `submitted`/`camera-ready` stage belongs to a cycle whose `phase` is still `porting` — [page](rules/cycle/stage.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [`cycle/port-done`](rules/cycle/port-done.md)                             | error                                                    | `paper.tex` → `paperlint.json` (`cycles`) → the preset's `template`                                    | the current cycle still declares `"phase": "porting"` (which silences the venue's format rules) while the `\documentclass` is already the venue's template: the port is done, drop the phase — [page](rules/cycle/port-done.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`paper/folder-venue-leftover`](rules/paper/folder-venue-leftover.md)     | warn                                                     | the folder name → `paperlint.json`                                                                     | the paper's folder is named after another shipped venue than the one it extends (`papers/aisec-2026/` for a paper now set for AIDC); reported on `PIPELINE-STATUS.md` — [page](rules/paper/folder-venue-leftover.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [`paper/allowed-files-only`](rules/paper/allowed-files-only.md)           | error                                                    | the paper folder's root listing → `paperlint.json`                                                     | a file or folder at the paper's root is not part of the layout (`PLAN.md`, `archive/`, a stray PDF); reported on `PIPELINE-STATUS.md`, once per entry, with where it goes; `extra/` takes anything — [page](rules/paper/allowed-files-only.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`repro/allowed-files-only`](rules/repro/allowed-files-only.md)           | error                                                    | the listing of the paper's `repro/`                                                                    | an entry at the top of `repro/` is not `README.md`, `studies.json`, `.gitignore`, `tools/`, `data/` or a study folder named `<id>-<slug>` (or, in a paper without the registry, `<slug>-YYYY-MM-DD`), or a study folder has no `README.md`; reported on `PIPELINE-STATUS.md`, once per entry, with where it goes by kind (a script → `repro/tools/`, data → `repro/data/`, a note → its study or `research/`) — [page](rules/repro/allowed-files-only.md)                                                                                                                                                                                                                                                                                         |
+| [`repro/study-registered`](rules/repro/study-registered.md)               | error                                                    | the listing of the paper's `repro/`, `repro/studies.json`, `repro/README.md`, each study's `plan.json` | a study folder with no row in `repro/studies.json`, a row whose folder is missing or not `<id>-<slug>`, a bad or repeated id, a title over 8 words, `done` without a result and an existing result file, `superseded` without an existing successor, a row naming a measurement the registry does not declare, a measurement with no study or an unknown requirement, a headline measurement not approved by the author, a plan that is missing, malformed or — once the study runs — unfilled, a headline study that has run without the author's check in its plan, or the index in `repro/README.md` out of sync with the registry; `paperlint studies new` and `paperlint studies index` write both — [page](rules/repro/study-registered.md) |
+| [`repro/study-plan-name`](rules/repro/study-plan-name.md)                 | warn                                                     | `repro/studies.json`                                                                                   | a study's plan still named `prereg.json`, its old name: read as the plan, and to be renamed `plan.json` — [page](rules/repro/study-plan-name.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| [`repro/outputs-before-decision`](rules/repro/outputs-before-decision.md) | error                                                    | `repro/studies.json`, each decide-first study's `plan.json` and folder, git's history                  | an output of a study decided before its run whose first commit does not descend from its decision's first commit, an output while the decision is uncommitted, a decision its outputs match, a shallow or unreadable history; `paperlint studies gate` opens the run only once the decision is committed — [page](rules/repro/outputs-before-decision.md)                                                                                                                                                                                                                                                                                                                                                                                         |
+| [`paper/sources-fresh`](rules/paper/sources-fresh.md)                     | warn                                                     | `paper.tex` → `_build/sources.json`                                                                    | the paper has not been built (no record of the files TeX read), or a file changed since the last build (its SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `paper/author-list`                                                       | error                                                    | `paper.tex` → `_build/references.json`, `_build/sources.json`                                          | an entry's authors are not those of the version it cites — typically the arXiv preprint's list under a published venue. Checked online by `paperlint build` (DBLP), reported on the entry's own line (or at the top of `paper.tex`, naming the entry's file); silent without a current build record                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `paper/section-word`                                                      | warn                                                     | `paper.tex` and its body files                                                                         | `§` or `\S\ref` instead of the word Section. **Fixable:** `--fix` writes `Section~\ref{…}` / `Section 5`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `paper/leading-zero`                                                      | warn                                                     | `paper.tex` and its body files                                                                         | a decimal below 1 without its leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz. A number right after `¶` or `§` (`¶¶.42`) is a paragraph designator and is not reported; in a paragraph that cites numbers that way, another bare decimal is reported without a fix, with the zero as a suggestion. **Fixable**                                                                                                                                                                                                                                                                                     |
+| `paper/figure-ref-style`                                                  | warn                                                     | `paper.tex` and its body files                                                                         | `Fig.~\ref` and `Figure~\ref` mixed in one document; each minority occurrence is reported. **Fixable:** `--fix` writes the majority form                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [`bib/reachable-entry`](rules/bib/reachable-entry.md)                     | warn                                                     | `paper.tex` → `_build/sources.json`: the databases the last build's bibtex opened                      | an entry has no doi, url or arXiv id — a reader has nothing to follow. Reported on the entry in the `filecontents` block of `paper.tex` that wrote its `.bib`, or at the top of `paper.tex` with the entry's file and line first; silent until a build records the paper; no fix, the link has to be looked up — [page](rules/bib/reachable-entry.md)                                                                                                                                                                                                                                                                                                                                                                                             |
+| `paper/cite-exists`                                                       | error                                                    | `paper.tex` → `_build/references.json`                                                                 | an entry's doi or arXiv id resolves to nothing, or to a different work. Checked online by `paperlint build`; a work that was merely not found is not a finding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `paper/refs-fresh`                                                        | error                                                    | `paper.tex` → `_build/references.json`                                                                 | the databases bibtex opened changed since the build checked them (their SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `paper/refs-checked`                                                      | warn                                                     | `paper.tex` → `_build/references.json`                                                                 | a build recorded the paper's databases and none has checked their references, or the last build could not (no network), or its bibtex typeset a key paperlint's reader did not read (an entry behind `%`, inside `@comment{…}`), or bibtex found a database outside the paper directory (`BIBINPUTS`) — so the two rules above did not run on it. Silent without a record of the build (`paper/sources-fresh` speaks)                                                                                                                                                                                                                                                                                                                             |
+| `tex/future-promise`                                                      | warn                                                     | `paper.tex` and its body files                                                                         | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `tex/acm-frontmatter-override`                                            | error                                                    | `paper.tex`                                                                                            | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`tex/template`](rules/tex/template.md)                                   | error                                                    | `paper.tex` → `paperlint.json`                                                                         | the `\documentclass` is not the preset's `template` class, or lacks an option it names — [page](rules/tex/template.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [`tex/required-section`](rules/tex/required-section.md)                   | error                                                    | `paper.tex` → `paperlint.json`                                                                         | a section the preset requires (AIDC: «LLM Usage Statement», last) is missing or not where it must be — [page](rules/tex/required-section.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`tex/heading-case`](rules/tex/heading-case.md)                           | optional; the AgenticDev preset sets `error`             | `paper.tex` and the files it includes                                                                  | a word in the paper's `\title` or in a `\section`, `\subsection`, `\subsubsection`, `\paragraph` or `\subparagraph` title is not in the style its scope asks: `{ "title", "headings", "levels"? }`, each `chicago-headline` (Conference Publishing's quote of the Chicago Manual of Style), `sentence` (first word only) or `any`. Words that are a preposition in one title and a particle in another (`up`, `on`, `in`) are not read mid-title. **Fixable:** `--fix` — [page](rules/tex/heading-case.md)                                                                                                                                                                                                                                        |
+| [`format/layout-override`](rules/format/layout-override.md)               | error                                                    | `paper.tex` → `paperlint.json`                                                                         | the source changes the page layout the venue's template sets for the whole document — `geometry`, a layout `\setlength`, `\linespread`, `\baselinestretch` — [page](rules/format/layout-override.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [`anonymity/identity`](rules/anonymity/identity.md)                       | error                                                    | `paper.tex` → `_build/paper.facts.json`                                                                | a double-blind venue (`"blind": true`) and no `identity` declared, or a declared name, handle, email or project in the PDF's text, metadata or link targets — [page](rules/anonymity/identity.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`tex/venue-leftover`](rules/tex/venue-leftover.md)                       | warn                                                     | `paper.tex` → `paperlint.json`                                                                         | the text names another shipped venue than the one the paper extends («Submission to VenueA 2026» in a paper now set for VenueB) — [page](rules/tex/venue-leftover.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [`tex/claim-provenance`](rules/tex/claim-provenance.md)                   | warn                                                     | `paper.tex`                                                                                            | a sentence of the body states a number and does not say whose it is — no citation or link, no _we_/_our_, no `\ref` or "Table 2", no sample ("n = 134", "48 runs") — [page](rules/tex/claim-provenance.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`tex/register`](rules/tex/register.md)                                   | warn                                                     | `paper.tex` and the files it includes                                                                  | the body runs to a post's register: more than 0.8 sentences per 1000 words open with _And_, _So_, _But_, _Nor_, _Or_ or _Yet_ — the limit is an option — [page](rules/tex/register.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [`tex/contrast-frames`](rules/tex/contrast-frames.md)                     | warn                                                     | `paper.tex` and the files it includes → `paperlint.json`                                               | contrast frames (_X, not Y_, _not X but Y_, _rather than_, _instead of_, _as opposed to_) per 10,000 words fall outside the band the venue preset's anchors set (AIDC: 0–10.4, from five accepted ACSAC papers); above it, each frame is reported too — [page](rules/tex/contrast-frames.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`tex/claim-emphasis`](rules/tex/claim-emphasis.md)                       | warn                                                     | `paper.tex` and the files it includes → `paperlint.json`                                               | claims set in bold inside a sentence (six words or more, or holding a number; not a term, not a label opening a paragraph) per 10,000 words fall outside the preset's band (AIDC: 0–17.8); above it, each is reported too — [page](rules/tex/claim-emphasis.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`tex/relation-markers`](rules/tex/relation-markers.md)                   | warn                                                     | `paper.tex` and the files it includes → `paperlint.json`                                               | words that name how a sentence relates to the one before (_because_, _therefore_, _however_, _for example_ …) per 10,000 words fall outside the preset's band (AIDC: 25.4–135.0) — the floor that catches relations left to infer — [page](rules/tex/relation-markers.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `review/frontmatter`                                                      | error                                                    | `reviews/*.md`                                                                                         | the review's frontmatter fails paperlint's JSON Schema — a `findings` record without `id`/`status`, an unknown field, or an **open** finding with no `cause` (`skill-defect` · `missing-skill` · `hook` · `rule`). A review with no `findings` key is not checked for findings                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `sibling/frontmatter`                                                     | warn                                                     | `siblings/*.md` (not `README.md`)                                                                      | a sibling card's frontmatter has no `read:` saying how much of the competing paper was read (`full` · `abstract` · `none`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `pdf/fresh`                                                               | error                                                    | `paper.tex` → `_build/paper.facts.json`                                                                | the paper names a venue and the facts cannot be judged: not JSON, a schema other than 3, or they describe a PDF that is gone or differs from the one on disk (its SHA-256)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `pdf/profile`                                                             | error                                                    | `paper.tex` → `paperlint.json`                                                                         | `paperlint.json` is not JSON or has an unknown key, its `extends` does not resolve (not found, a cycle, a chain longer than four, a preset that fails the schema, an npm name), it names no `kind` while the preset has kinds, or names a kind the preset does not have                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `pdf/fonts`                                                               | error                                                    | `paper.tex` → `_build/paper.facts.json`                                                                | a font the pages draw is Type 3 or not embedded, or no font starts with the family the venue preset names for body text (`fonts_text`) or headings (`fonts_title`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `pdf/geometry`                                                            | error                                                    | `paper.tex` → `_build/paper.facts.json`                                                                | the page width or height is more than `dimTol` (default 0.05 in) off the preset's, or the column count differs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`format/page-limit`](rules/format/page-limit.md)                         | error                                                    | `paper.tex` → `_build/paper.facts.json`                                                                | body or reference pages exceed the limits of the paper's kind. With `body_ends_at: "references"` (AIDC) the body ends at the references or the appendix, whichever comes first — found by hyperref's anchors, then the heading line — and the page it ends on counts when body text stands above the heading; with `appendix_in_body` too (MSR) the appendix is body wherever it sits and the reference pages are the ones holding only references; an end it cannot find, or signals that disagree, are reported — [page](rules/format/page-limit.md)                                                                                                                                                                                            |
+| [`pdf/body-size`](rules/pdf/body-size.md)                                 | error                                                    | `paper.tex` → `_build/paper.facts.json`                                                                | the body font size is more than `body_pt_tol` off the preset's, or the reference font size is outside the preset's range widened by `body_pt_tol`. banal reads 0.3 pt above the size the glyphs are set in; checked on five built accepted papers (none reported) and three variants one size off (each reported) — [page](rules/pdf/body-size.md)                                                                                                                                                                                                                                                                                                                                                                                                |
+| `pdf/measured`                                                            | warn                                                     | `paper.tex` → `_build/paper.facts.json`                                                                | the paper's `paperlint.json` names no venue preset yet; or it names one and there are no facts (it was not built), or the facts carry no page geometry (banal was not found) — so the checks above did not run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`talk/profile`](rules/talk/profile.md)                                   | error                                                    | `paper.tex` → `paperlint.json`                                                                         | the paper declares `talk` and names no preset, the preset has no `talk` block, the mode is not one the venue allows, or the venue sets no talk slot for the paper's kind — [page](rules/talk/profile.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [`talk/required-files`](rules/talk/required-files.md)                     | error                                                    | `paper.tex` → `paperlint.json`, the talk folder                                                        | a file the venue requires for the paper's talk mode (video, one-slide, captions…) is not in the talk folder — [page](rules/talk/required-files.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`talk/undeclared`](rules/talk/undeclared.md)                             | warn                                                     | `paper.tex` → the paper's `talk/` folder                                                               | an `.mp4` sits in `talk/` and the paper declares no `talk`, so nothing checks it — [page](rules/talk/undeclared.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| [`talk/duration`](rules/talk/duration.md)                                 | error                                                    | `paper.tex` → the talk video                                                                           | the video runs longer than the slot's `talk_s_max`, or its audio track is more than 1 s off the video's length — [page](rules/talk/duration.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`talk/duration-floor`](rules/talk/duration-floor.md)                     | warn                                                     | `paper.tex` → the talk video                                                                           | the video runs shorter than the slot's `talk_s_min` — [page](rules/talk/duration-floor.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`talk/video-format`](rules/talk/video-format.md)                         | error                                                    | `paper.tex` → the talk video                                                                           | the video is not ISO media, is QuickTime where the venue asks for MP4, is under `min_height_px`, or over `max_bytes` — [page](rules/talk/video-format.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| [`talk/one-slide-size`](rules/talk/one-slide-size.md)                     | error                                                    | `paper.tex` → the one-slide PNG                                                                        | the one-slide image is not the size the paper or the preset states, or not a PNG — [page](rules/talk/one-slide-size.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| [`talk/captions-cover`](rules/talk/captions-cover.md)                     | warn                                                     | `paper.tex` → the captions and the video                                                               | the captions start late, end early or leave a long gap (uncalibrated thresholds) — [page](rules/talk/captions-cover.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 **Body files** are the files of the paper's directory that TeX read after `\begin{document}` in the
 last build, as `paperlint build` recorded them in `_build/sources.json` — not a preamble file, not a

package/docs/testing.md

@@ -100,6 +100,7 @@ npm run coverage                  # the same under c8, failing below the thresho
 npm run test:e2e                  # every end-to-end run
 npm run test:e2e:install          # the package packed and installed under npm and pnpm
 npm run test:e2e:tex              # real TeX Live: toolchain, builds of every fixture, banal
+npm run test:e2e:studies          # real git: the gate, the order rule, the index's commits
 npm run check                     # every gate CI runs, and the list of what it does not reproduce
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "10.2.0",
+  "version": "10.4.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -11,6 +11,7 @@
     "test:e2e": "vitest run --project 'e2e-*'",
     "test:e2e:install": "vitest run --project e2e-install",
     "test:e2e:tex": "vitest run --project e2e-tex",
+    "test:e2e:studies": "vitest run --project e2e-studies",
     "coverage": "NODE_OPTIONS=\"--import=./test/coverage-src.ts $NODE_OPTIONS\" c8 --check-coverage npm test --",
     "lint": "eslint .",
     "check": "node scripts/check.ts",

package/scripts/check.ts

@@ -173,6 +173,12 @@ export const GATES: readonly Gate[] = [
     script: "test:e2e:install",
     vitest: true,
   },
+  {
+    name: "studies e2e — a study decided before its run, in a real git repository",
+    job: "gates",
+    script: "test:e2e:studies",
+    vitest: true,
+  },
   {
     name: "TeX e2e — real TeX Live: paperlint toolchain, a real pdflatex build of every fixture, the real banal",
     job: "build-e2e",

package/skills/build-benchmark/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:93d83b56c6c1baea compiled from skills/build-benchmark/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:ed855c5f3aa34b10 compiled from skills/build-benchmark/SKILL.md.spec.ts -->
 
 # build-benchmark — the study + the artifact reviewers can run
 
@@ -44,10 +44,19 @@ Every study gets its folder, its id and its row from one command, never from a f
 npx paperlint studies new <paper-dir> "<plain title, at most 8 words>" --kind measurement
 ```
 
-It takes the next id in `repro/studies.json`, creates `repro/<id>-<slug>/README.md`, appends the row
-(`status: designing`) and regenerates the index in `repro/README.md`. The kinds: `measurement`,
-`spike`, `tooling`, `data`, `artifact`, `salvage`. Write the study's one-sentence `question` into its
-row at once.
+It takes the next id in `repro/studies.json`, creates `repro/<id>-<slug>/README.md` and the study's
+plan, `plan.json`, appends the row (`status: designing`, `plan: "plan.json"`) and regenerates the index
+in `repro/README.md`. The kinds: `measurement`, `spike`, `tooling`, `data`, `artifact`, `salvage`.
+Write the study's one-sentence `question` into its row at once. Never write a plan by hand under
+another name: the template's fields are the ones `repro/study-registered` reads.
+
+**A measurement that spans studies** (a pilot, the main run, a replication) is declared once, in
+`measurements` at the top of `repro/studies.json` — `id`, `title`, `rq`, `role` (`headline` or
+`baseline`) — and each of its studies' rows names it in `measurement`. The author's requirements on
+the measurements go, verbatim, into `requirements` (`id`, `text`, `date`, `source`), and each
+measurement lists the ones it must meet; never in a separate note. A `headline` measurement carries
+the author's `approval` (`by` the registry's `author`, `date`, their words in `quote`), written
+from the author's own message, never by the agent that designed the study.
 
 As the study moves, edit its row in `repro/studies.json`: `running` when the first counted run starts;
 when it ends, `done` with `result` (one line) and `result_file` (the file inside the folder the result
@@ -73,13 +82,16 @@ Write the design as the answer to "what would make the critiqued pitfall impossi
 **Declare the population, the screens and the coverage before freezing the sample.** Each screen
 between the population and the sample (fits one excerpt, one classifier lane, a model-picked item)
 changes what the sample can say, not only its size; screens that are reasonable one by one can leave a
-sample nobody meets in practice. So, before the draw is frozen, the study's `prereg.json` says what
-the claim is about, what each screen removed per stratum and what share the sample can represent; then
-show the author the drawn **units** (the rules or cases, not the items made from them) and ask: *is
-this what you meet in practice?* The fields are the experimental rule
-`study/declare-sample` (`docs/rules/study/declare-sample.md`), off by default: do this step either way,
-and turn the check on with `"rules": { "study/declare-sample": "error" }` in the paper's `paperlint.json`
-for `paperlint lint` to fail until they are there.
+sample nobody meets in practice. So, before the draw is frozen, fill the study's `plan.json`: the
+`question`, the `population` (its `source`, and the `draw`: `{ "kind": "all", "method" }` for a census,
+or `{ "kind": "seeded", "method", "seed" }` for a sample),
+the `arms` (`[]` for a census) and the `primary_outcome`; what each screen removed per stratum and
+what share the sample can represent go into the same file, under `extra` (the plan is closed: any
+other unknown key is an error). Then show the
+author the drawn **units** (the rules or cases, not the items made from them), ask *is this what you
+meet in practice?*, and record the answer in the plan's `author_check` (`by`, `date`, their words in
+`quote`). Once the study is `running`, `repro/study-registered` fails the lint on an empty plan field,
+and, for a study of a `headline` measurement, on a plan without the author's check.
 
 ## 2. Honest statistics — the part reviewers attack first
 

package/skills/build-benchmark/SKILL.md.spec.ts

@@ -50,10 +50,19 @@ Every study gets its folder, its id and its row from one command, never from a f
 npx paperlint studies new <paper-dir> "<plain title, at most 8 words>" --kind measurement
 \`\`\`
 
-It takes the next id in \`repro/studies.json\`, creates \`repro/<id>-<slug>/README.md\`, appends the row
-(\`status: designing\`) and regenerates the index in \`repro/README.md\`. The kinds: \`measurement\`,
-\`spike\`, \`tooling\`, \`data\`, \`artifact\`, \`salvage\`. Write the study's one-sentence \`question\` into its
-row at once.
+It takes the next id in \`repro/studies.json\`, creates \`repro/<id>-<slug>/README.md\` and the study's
+plan, \`plan.json\`, appends the row (\`status: designing\`, \`plan: "plan.json"\`) and regenerates the index
+in \`repro/README.md\`. The kinds: \`measurement\`, \`spike\`, \`tooling\`, \`data\`, \`artifact\`, \`salvage\`.
+Write the study's one-sentence \`question\` into its row at once. Never write a plan by hand under
+another name: the template's fields are the ones \`repro/study-registered\` reads.
+
+**A measurement that spans studies** (a pilot, the main run, a replication) is declared once, in
+\`measurements\` at the top of \`repro/studies.json\` — \`id\`, \`title\`, \`rq\`, \`role\` (\`headline\` or
+\`baseline\`) — and each of its studies' rows names it in \`measurement\`. The author's requirements on
+the measurements go, verbatim, into \`requirements\` (\`id\`, \`text\`, \`date\`, \`source\`), and each
+measurement lists the ones it must meet; never in a separate note. A \`headline\` measurement carries
+the author's \`approval\` (\`by\` the registry's \`author\`, \`date\`, their words in \`quote\`), written
+from the author's own message, never by the agent that designed the study.
 
 As the study moves, edit its row in \`repro/studies.json\`: \`running\` when the first counted run starts;
 when it ends, \`done\` with \`result\` (one line) and \`result_file\` (the file inside the folder the result
@@ -79,13 +88,16 @@ Write the design as the answer to "what would make the critiqued pitfall impossi
 **Declare the population, the screens and the coverage before freezing the sample.** Each screen
 between the population and the sample (fits one excerpt, one classifier lane, a model-picked item)
 changes what the sample can say, not only its size; screens that are reasonable one by one can leave a
-sample nobody meets in practice. So, before the draw is frozen, the study's \`prereg.json\` says what
-the claim is about, what each screen removed per stratum and what share the sample can represent; then
-show the author the drawn **units** (the rules or cases, not the items made from them) and ask: *is
-this what you meet in practice?* The fields are the experimental rule
-\`study/declare-sample\` (\`docs/rules/study/declare-sample.md\`), off by default: do this step either way,
-and turn the check on with \`"rules": { "study/declare-sample": "error" }\` in the paper's \`paperlint.json\`
-for \`paperlint lint\` to fail until they are there.
+sample nobody meets in practice. So, before the draw is frozen, fill the study's \`plan.json\`: the
+\`question\`, the \`population\` (its \`source\`, and the \`draw\`: \`{ "kind": "all", "method" }\` for a census,
+or \`{ "kind": "seeded", "method", "seed" }\` for a sample),
+the \`arms\` (\`[]\` for a census) and the \`primary_outcome\`; what each screen removed per stratum and
+what share the sample can represent go into the same file, under \`extra\` (the plan is closed: any
+other unknown key is an error). Then show the
+author the drawn **units** (the rules or cases, not the items made from them), ask *is this what you
+meet in practice?*, and record the answer in the plan's \`author_check\` (\`by\`, \`date\`, their words in
+\`quote\`). Once the study is \`running\`, \`repro/study-registered\` fails the lint on an empty plan field,
+and, for a study of a \`headline\` measurement, on a plan without the author's check.
 
 ## 2. Honest statistics — the part reviewers attack first
 

package/skills/build-label-page/SKILL.md

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:7a537e71585bd321 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:dd742c1fcb34cfd6 compiled from skills/build-label-page/SKILL.md.spec.ts -->
 
 # build-label-page — a page the person labels on a phone, and the labels back in the repo
 
@@ -49,15 +49,17 @@ The full text, each with its reason and its check, is
    fit the time they have on a phone? Who is the labeller: a page with a store opens only for people
    with access to the artifact, so the labeller is the owner or has been shared as a Contributor.
    If the study design is not written yet, `build-benchmark` comes first.
-   If the items come from a drawn sample, the study's `prereg.json` declares the population, the
-   screens and the coverage before the sample is frozen (the experimental rule `study/declare-sample` checks it, off by default), and the
-   author has been shown the drawn **units** (the rules or cases, not the items) with "is this what
-   you meet in practice?". The labelling page is not that check: items made from easy units each look
-   fine on their own.
+   If the items come from a drawn sample, the study's `plan.json` (written by
+   `paperlint studies new`) declares the population and its draw before the sample is frozen, and its
+   `author_check` records that the author has been shown the drawn **units** (the rules or cases, not
+   the items) with "is this what you meet in practice?". The labelling page is not that check: items
+   made from easy units each look fine on their own.
 2. **Copy the generator into the study and write the items.** The study folder is
    `<paper-dir>/repro/<id>-<slug>/`, made by `npx paperlint studies new <paper-dir> "Gold labels"
    --kind data` when the labelling is a study of its own (`P1-S04-gold-labels`): the command writes
-   its `README.md` and its row in `repro/studies.json`, and `repro/study-registered` checks both. When
+   its `README.md`, its `plan.json` and its row in `repro/studies.json`, and `repro/study-registered`
+   checks them; fill the plan (what is labelled, the items' source, `arms: []`, the primary outcome)
+   before the first label. When
    the labels are in, update the row (`status`, `result`, `result_file`) and run
    `npx paperlint studies index <paper-dir>`. Where this sits in stage 3, and what checks each place:
    `docs/layout.md` in the paperlint package.

package/skills/build-label-page/SKILL.md.spec.ts

@@ -59,15 +59,17 @@ The full text, each with its reason and its check, is
    fit the time they have on a phone? Who is the labeller: a page with a store opens only for people
    with access to the artifact, so the labeller is the owner or has been shared as a Contributor.
    If the study design is not written yet, \`build-benchmark\` comes first.
-   If the items come from a drawn sample, the study's \`prereg.json\` declares the population, the
-   screens and the coverage before the sample is frozen (the experimental rule \`study/declare-sample\` checks it, off by default), and the
-   author has been shown the drawn **units** (the rules or cases, not the items) with "is this what
-   you meet in practice?". The labelling page is not that check: items made from easy units each look
-   fine on their own.
+   If the items come from a drawn sample, the study's \`plan.json\` (written by
+   \`paperlint studies new\`) declares the population and its draw before the sample is frozen, and its
+   \`author_check\` records that the author has been shown the drawn **units** (the rules or cases, not
+   the items) with "is this what you meet in practice?". The labelling page is not that check: items
+   made from easy units each look fine on their own.
 2. **Copy the generator into the study and write the items.** The study folder is
    \`<paper-dir>/repro/<id>-<slug>/\`, made by \`npx paperlint studies new <paper-dir> "Gold labels"
    --kind data\` when the labelling is a study of its own (\`P1-S04-gold-labels\`): the command writes
-   its \`README.md\` and its row in \`repro/studies.json\`, and \`repro/study-registered\` checks both. When
+   its \`README.md\`, its \`plan.json\` and its row in \`repro/studies.json\`, and \`repro/study-registered\`
+   checks them; fill the plan (what is labelled, the items' source, \`arms: []\`, the primary outcome)
+   before the first label. When
    the labels are in, update the row (\`status\`, \`result\`, \`result_file\`) and run
    \`npx paperlint studies index <paper-dir>\`. Where this sits in stage 3, and what checks each place:
    \`docs/layout.md\` in the paperlint package.