paperlint 10.1.1 → 10.3.0

package/docs/design/study-registry.md

@@ -0,0 +1,246 @@
+# The study registry — design
+
+A paper's `repro/` holds one folder per study. Named `<slug>-YYYY-MM-DD`, they sort by date and say
+nothing else: a real paper reached 79 study folders, and nobody could tell which one a number in the
+paper came from, which ones had ended, or which were current. This note fixes the shape of the
+registry that gives every study a stable number and a plain name, the lint rule that holds it, and the
+two commands that write it.
+
+## What is decided
+
+1. **One registry, `repro/studies.json`, JSON with a schema.** Never markdown: a table in a README is
+   what people edit by hand and what a parser has to guess at. The schema (zod, in
+   `src/adapters/study-registry/`) is checked where the file is read; nothing after that re-validates.
+
+   ```json
+   {
+     "prefix": "P1",
+     "studies": [
+       {
+         "id": "P1-S01",
+         "folder": "P1-S01-baseline-pass-rate",
+         "title": "Baseline pass rate",
+         "question": "How often does the unmodified agent pass the task?",
+         "kind": "measurement",
+         "status": "done",
+         "date": "2026-10-15",
+         "result": "41 of 60 runs pass",
+         "result_file": "results.tsv",
+         "in_paper": "yes"
+       }
+     ]
+   }
+   ```
+
+   | field           | values                                                                    |
+   | --------------- | ------------------------------------------------------------------------- |
+   | `prefix`        | the paper's prefix: a capital letter, then capitals or digits (`P1`)      |
+   | `id`            | `<prefix>-S<two or more digits>`, unique                                  |
+   | `folder`        | `<id>-<slug>`: the study's folder at the top of `repro/`                  |
+   | `title`         | a plain name, at most 8 words                                             |
+   | `question`      | one sentence: what the study asks                                         |
+   | `kind`          | `measurement`, `spike`, `tooling`, `data`, `artifact`, `salvage`          |
+   | `status`        | `designing`, `running`, `done`, `stopped`, `superseded`, `dropped`        |
+   | `date`          | `YYYY-MM-DD`, the day it was registered                                   |
+   | `result`        | optional; one line. Required when `done`                                  |
+   | `result_file`   | optional; a path inside the folder. Required, and must exist, when `done` |
+   | `superseded_by` | optional; an id in the registry. Required when `superseded`               |
+   | `in_paper`      | `yes`, `no`, `registry` (listed only in the registry, not in the text)    |
+
+   | `measurement` | optional; the id of the measurement the study belongs to (6) |
+   | `plan` | optional; the study's plan, a path inside its folder: `plan.json` (7) |
+
+   **A row may carry more fields**, and they are kept: a paper merges its own metadata into the rows
+   (`frame`, `method`, `outcome`, …). The top level is closed — `prefix`, `studies`, and the optional
+   `author`, `requirements` and `measurements` (6) — so a misspelt key is an error, not an ignored
+   key.
+
+2. **The rule `repro/study-registered`, an error,** reported on the first line of
+   `PIPELINE-STATUS.md` like `repro/allowed-files-only`, once per finding:
+
+   - every folder at the top of `repro/` that is not `tools/`, `data/` or a byproduct the layout
+     ignores (`__pycache__/`, `node_modules/`, …) has exactly one row, and every row's folder exists;
+   - the folder is `<id>-<slug>`, the id is `<prefix>-S<digits>`, ids are unique;
+   - `done` has a `result` and an existing `result_file`; `superseded` names an existing id in
+     `superseded_by`; a title has at most 8 words;
+   - **the index is in sync:** the block of `repro/README.md` between the two markers below equals the
+     text generated from `studies.json`. The comparison is of strings. The markdown is output only and
+     is never parsed.
+
+     ```
+     <!-- studies:begin — generated from studies.json by `paperlint studies index`; do not edit -->
+     <!-- studies:end -->
+     ```
+
+   - a paper with study folders and no `repro/studies.json` gets one finding naming the file.
+   - a `studies.json` that is not JSON, or not of the schema, gets one finding with the reasons.
+
+3. **Two commands**, in `src/studies.ts`, wired in `src/cli.ts`:
+
+   - `paperlint studies new <paper-dir> "<title>" [--kind measurement]` takes the next id, creates
+     `repro/<id>-<slug>/README.md` (frontmatter `id:` and `title:`) and the plan's template,
+     `plan.json` (7), appends the row with `status: designing`, `in_paper: no`, today's date and
+     `plan: "plan.json"`, and regenerates the index block. It refuses a
+     title over 8 words, a title with no letter or digit to make a slug from, an unknown kind, a folder
+     that already exists, and a paper with no `studies.json` (the prefix is the author's choice, so the
+     refusal names the file to write and does not guess one).
+   - `paperlint studies index <paper-dir>` regenerates the index block: a table with the columns id ·
+     title · status · result · in paper · folder. With no markers in `repro/README.md` the block is
+     appended; with no `repro/README.md` the file is written.
+
+4. **The layout accepts `<id>-<slug>` beside `<slug>-YYYY-MM-DD`.** `repro/allowed-files-only` keeps
+   accepting the dated form, so a paper that turns the registry off is not broken by this change; it
+   also allows `studies.json` at the top of `repro/`. A folder in the dated form is still reported by
+   `repro/study-registered` as unregistered — that is the point of the registry — and the paper decides
+   whether to register it or turn the rule off.
+
+5. **Skills.** `build-benchmark`, `run-agent-grid` and `build-label-page` create a study only with
+   `paperlint studies new`, and update its row (status, result, result file, in paper) when it ends,
+   then run `paperlint studies index`.
+
+6. **Measurements above studies, and the author's requirements.** One measurement (a census, a
+   benchmark) spans several study folders: a pilot, the main run, a replication. Before this, a paper
+   put the measurement's fields on the row of its first study under prefixed names
+   (`measurement_title`, `measurement_status`) and the other rows carried `measurement: <id>`, which
+   nothing checked; the author's verbatim requirements went to a separate file nothing read. Now:
+
+   ```json
+   {
+     "prefix": "P1",
+     "author": "A. Author",
+     "requirements": [
+       {
+         "id": "R1",
+         "text": "Every sample is a random draw from all rules found.",
+         "date": "2026-10-10",
+         "source": "chat"
+       }
+     ],
+     "measurements": [
+       {
+         "id": "M1",
+         "title": "Rule census",
+         "rq": "RQ1",
+         "role": "headline",
+         "approval": {
+           "by": "A. Author",
+           "date": "2026-10-12",
+           "quote": "This is the one."
+         },
+         "requirements": ["R1"]
+       }
+     ],
+     "studies": [
+       { "id": "P1-S01", "measurement": "M1", "plan": "plan.json", "…": "…" }
+     ]
+   }
+   ```
+
+   `role` is `headline` (the paper's claim rests on it) or `baseline`. A measurement keeps extra
+   fields like a row; a requirement and an approval are exactly their fields. The rule reports, each
+   finding its own message id: a row naming an undeclared measurement (`unknown-measurement`), a
+   measurement no row names (`empty-measurement`), a measurement naming an undeclared requirement
+   (`unknown-requirement`), and a headline without `approval`, or approved by anyone but `author`
+   when the registry names one (`headline-approval`). These cross-references are the rule's, not the
+   parser's: one dangling id must not fail the whole parse and hide every other finding. **These checks run only when the registry has
+   `measurements`**: a registry written before them, whose rows already carry `measurement` as a field
+   of their own, stays valid.
+
+7. **The study's plan, `plan.json`.** Each study folder held a hand-written `prereg.json`, its
+   fields differing study to study, read only by the experimental `study/declare-sample`. The name
+   misled — it is not an outside pre-registration — so the plan is `plan.json`, written as a
+   template by `paperlint studies new` beside the README, and named in the row's `plan`:
+
+   ```json
+   {
+     "question": "",
+     "population": {
+       "source": "",
+       "draw": { "kind": "all", "method": "" }
+     },
+     "arms": [],
+     "primary_outcome": "",
+     "author_check": null
+   }
+   ```
+
+   The template's draw is of all the population (`"kind": "all"`, a census); a sampled study changes
+   it to `{ "kind": "seeded", "method": "random", "seed": 7 }`. `arms` is empty for a census;
+   `author_check` becomes `{ "by", "date", "quote" }` once the author has seen the drawn units.
+   **Parse, don't validate:**
+
+   - **Closed at every level.** A misspelt key is an error; the paper's own keys (hypotheses,
+     models, budget) go in the one optional key `extra`, an object of anything.
+   - **One spelling of "none".** `author_check` is required, and `null` is "not yet"; an absent key
+     is an error, never a second way to say the same.
+   - **No contradictory state.** Each of these is a parse error, not a later finding:
+     - an `author_check` on a draft — the author approved a plan whose texts are empty;
+     - a draw that is not one of two kinds: `seeded`, whose `seed` is required and not null, or
+       `all` (a census), which has no seed;
+     - two arms of one name;
+     - a key of `extra` that is a field of the plan, which would say one thing twice.
+
+     The population's size is not stored: it is counted from the source, and a stored copy could
+     only contradict it. Nothing downstream read it.
+
+   - **Complete or not is a type.** The parser returns a plan `ready` (every required text filled)
+     or a `draft` with the list of its empty texts, or why it is no plan. The rule never looks at a
+     text again: a study that has run on a `draft` is `bad-plan`, with the parser's list.
+   - **The schemas are the domain's types.** The domain's types are written by hand (the domain
+     imports no zod); the adapter holds a compile-time proof that each schema's output — registry,
+     study, measurement, requirement, approval, author check, plan, ready-or-draft — and its domain type are the
+     same type both ways, so a field added to one alone stops the build.
+
+   The schemas live beside the registry's, in `src/adapters/study-registry/`. The rule reports a
+   `plan` outside the folder, missing, or not of the schema, and — once the study has run (`running`,
+   `done`, `stopped`, `superseded`) — a draft (`bad-plan`); a study of a headline measurement
+   that has run with no `author_check` in its plan, no plan, or a check by anyone but `author`
+   (`author-check`). A `designing` study's template is clean, so `studies new` never leaves the lint
+   red.
+
+   **Compatibility.** A row may name `prereg.json` as its plan: it is parsed by a loose schema of
+   its own — keys of its own accepted at every level, those at the top kept in `extra`, a seed makes
+   the draw `seeded`, none (or `null`) makes it `all`; a size is not read; an absent check is
+   `null` — and judged as the plan, the same contradictions refused; a second rule, `repro/study-plan-name`, warns that it moves to `plan.json` — a warning cannot
+   come from an error rule, since ESLint sets the level per rule. A `prereg.json` no row names is not
+   read, so no existing paper turns red.
+
+## Where each part lives
+
+| part                                   | file                                | layer   |
+| -------------------------------------- | ----------------------------------- | ------- |
+| the types, the judge, the index, ids   | `src/domain/study-registry.ts`      | domain  |
+| the plan's type and template           | `src/domain/study-registry.ts`      | domain  |
+| the schemas (zod) of registry and plan | `src/adapters/study-registry/`      | adapter |
+| what the app asks of a parser          | `src/ports/study-registry-codec.ts` | port    |
+| both rules: list, read, report         | `src/study-registry-rule.ts`        | app     |
+| the two commands                       | `src/studies.ts`                    | app     |
+| wiring, the clock for today's date     | `src/cli.ts`                        | root    |
+
+The judge is pure: it takes the folder names, the parsed registry (or why it is absent or unreadable),
+the README's text, which result files exist, and each named plan parsed, and returns findings. The rule and the commands are
+the only places that touch the disk, through the `Files` and `ListDir` ports.
+
+## Generated index, and prettier
+
+The index is a table whose columns are padded to their widest cell, the way prettier writes a
+markdown table, so formatting `repro/README.md` with prettier does not make the block stale. A `|` in
+a cell is escaped and a line break becomes a space.
+
+## Rejected, by the author on 2026-10-15
+
+- Commands that change a study's status: the row is edited in `studies.json`, the rule checks it.
+- Detecting automatically whether a study is cited in the paper: `in_paper` is declared.
+- An adopt or migration command for existing folders: there are no other users; the folders are
+  renamed by hand once.
+- A PreToolUse hook for the registry: the lint is the guarantee, and the layout hook already refuses
+  a loose entry.
+
+## What it does not check
+
+- Whether the `question` is one sentence, or the `result` one line, beyond their being strings.
+- What a study's `README.md` says, or whether its frontmatter matches the row.
+- Files inside a study folder other than `result_file` and the `plan` its row names.
+- `study/declare-sample` still reads only `prereg.json`, and asks for different fields
+  (`strata`, `screens`, `coverage`, and an `author_check` of `who`, `when`, `units_seen`,
+  `units_drawn`, `verdict`); merging the two shapes is its own decision.

package/docs/layout.md

@@ -15,14 +15,14 @@ flowchart TB
   S1["<b>1 · idea</b><br/>research-ideate · map-prior-work<br/>analyze-sibling-paper<br/>writes: siblings/<br/>checked by: sibling/frontmatter"]
   S2["<b>2 · venue</b><br/>find-venue · plan-paper-timeline<br/>study-accepted-papers, mode A or B<br/>writes: paperlint.json, a report in reviews/<br/>checked by: review/frontmatter"]
   V[("<b>#lt;papers-root#gt;/venues/#lt;venue#gt;/</b><br/>beside the papers, not in one:<br/>the venue's accepted papers,<br/>shared by every paper aimed at it<br/>checked by: nothing")]
-  subgraph S3["3 · study: repro/#lt;slug#gt;-YYYY-MM-DD/"]
+  subgraph S3["3 · study: repro/#lt;id#gt;-#lt;slug#gt;/"]
     direction TB
-    D["<b>design</b> · build-benchmark<br/>writes: the study's README.md<br/>checked by: repro/allowed-files-only"]
-    P["<b>pre-register</b> · build-benchmark<br/>writes: prereg.json, before the draw<br/>checked by: study/declare-sample (experimental, off)"]
-    A["<b>author check</b> · you see the drawn units<br/>writes: author_check in prereg.json<br/>checked by: study/declare-sample (experimental, off)"]
+    D["<b>design</b> · build-benchmark<br/>paperlint studies new<br/>writes: the study's folder, README.md,<br/>its row in repro/studies.json<br/>checked by: repro/allowed-files-only,<br/>repro/study-registered"]
+    P["<b>plan</b> · build-benchmark<br/>fills: plan.json, before the draw<br/>checked by: repro/study-registered,<br/>once the study runs"]
+    A["<b>author check</b> · you see the drawn units<br/>writes: author_check in plan.json<br/>checked by: repro/study-registered,<br/>for a headline measurement"]
     R["<b>run</b> · your scripts<br/>writes: the study folder,<br/>repro/tools/, repro/data/<br/>checked by: repro/allowed-files-only"]
     L["<b>labels</b> · build-label-page<br/>a phone page; the answers go<br/>into the study's data/"]
-    Y["<b>analysis</b> · build-benchmark<br/>writes: the numbers, NOTES.md"]
+    Y["<b>analysis</b> · build-benchmark<br/>writes: the numbers, NOTES.md,<br/>the study's row: status, result<br/>then paperlint studies index<br/>checked by: repro/study-registered"]
     D --> P --> A --> R --> L --> Y
   end
   S4["<b>4 · draft</b><br/>draft-paper · argument-arc · tighten-paper<br/>writes: paper.tex, sections/, figures/<br/>checked by: the tex/* rules<br/>hook paper-edit-guard: no shell writes"]
@@ -69,11 +69,12 @@ creates one.
     ├── siblings/                      ← the cards of competing papers
     ├── research/                      ← dated research and decision records
     ├── repro/                         ← the reproduction artifact
-    │   ├── README.md                  ← the index: one line per study
+    │   ├── README.md                  ← the index: one line per study, generated from studies.json
+    │   ├── studies.json               ← the study registry: id, title, status and result of each study
     │   ├── .gitignore                 ← keeps the scripts' byproducts out of git
     │   ├── tools/                     ← scripts used across the paper (numbers, figures, anonymity check, harnesses)
     │   ├── data/                      ← shared data (tables, caches)
-    │   └── <slug>-YYYY-MM-DD/         ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)
+    │   └── <id>-<slug>/               ← one folder per study or spike, named by its row in studies.json (P1-S03-baseline)
     │       └── README.md              ← required: what it asks, how to run it, what it found
     ├── figures/                       ← graphics and their sources
     ├── sections/                      ← the body, when it is split
@@ -97,28 +98,30 @@ Both are explained in [`venues.md`](venues.md).
 "Stage" is the stage of [the pipeline](#the-flow) that writes the place first.
 "Checked by" is the rule `paperlint lint` runs over it; "nothing" means no rule reads its content.
 
-| place                                 | stage            | written by                                                                                                                                                                                       | checked by                                                                                                                           |
-| ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `<papers-root>/venues/<venue>/`       | 2 venue          | `study-accepted-papers`, its first run for that venue (mode A, usually)                                                                                                                          | nothing ([why](venues.md#what-checks-it))                                                                                            |
-| the paper folder's root               | before 1         | `paperlint new`: the three files, and an empty `.gitkeep` folder for `reviews/`, `research/`, `figures/`, `versions/`, `submission/`, `repro/tools/`, `repro/data/` (`repro/` gets a stub index) | [`paper/allowed-files-only`](rules/paper/allowed-files-only.md); the hook `paper-folder-layout` refuses a new stray entry            |
-| `PIPELINE-STATUS.md`                  | every stage      | `paperlint new`, then `paper-pipeline`, `paper-status`; `study-accepted-papers` (the scorecard)                                                                                                  | `paper/stages`, `paper/source`, [`cycle/stage`](rules/cycle/stage.md) ([rules](rules.md))                                            |
-| `paperlint.json`                      | before 1, then 2 | `paperlint new`; `find-venue` names the venue                                                                                                                                                    | `paperlint lint` refuses an unknown key; [`cycle/record`](rules/cycle/record.md)                                                     |
-| `siblings/`                           | 1 idea           | `map-prior-work`, `analyze-sibling-paper`                                                                                                                                                        | `sibling/frontmatter` ([records](configuration.md#records-in-frontmatter-checked-by-shipped-json-schemas))                           |
-| `reviews/`                            | 2, then 4–5      | `study-accepted-papers` (its report), `grade-paper-writing`, `cold-read-diff`, the review skills                                                                                                 | `review/frontmatter` ([records](configuration.md#records-in-frontmatter-checked-by-shipped-json-schemas))                            |
-| `research/`                           | any              | you and the skills: dated research and decision records                                                                                                                                          | nothing                                                                                                                              |
-| `repro/`, its top                     | 3 study          | `build-benchmark`, your scripts                                                                                                                                                                  | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md); the hook `paper-folder-layout` refuses a new loose entry            |
-| `repro/<slug>-YYYY-MM-DD/`            | 3 study          | `build-benchmark` (the design, in its `README.md`)                                                                                                                                               | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md): the dated name, and a `README.md` in it                             |
-| `repro/<slug>-YYYY-MM-DD/prereg.json` | 3 study          | `build-benchmark`, before the sample is drawn; you add the author's check                                                                                                                        | [`study/declare-sample`](rules/study/declare-sample.md)                                                                              |
-| `repro/<slug>-YYYY-MM-DD/data/`       | 3 study          | `build-label-page` exports the labels here                                                                                                                                                       | nothing                                                                                                                              |
-| `repro/tools/`, `repro/data/`         | 3 study          | your scripts; `paperlint build` keeps `repro/data/references-cache.json`                                                                                                                         | nothing inside them                                                                                                                  |
-| `NOTES.md`                            | 3, then 4        | you: each number → the data it comes from; `build-label-page` adds a line per label file                                                                                                         | nothing                                                                                                                              |
-| `paper.tex`, `sections/`, `*.bib`     | 4 draft          | `draft-paper`, `argument-arc`, `tighten-paper`                                                                                                                                                   | the `tex/*`, `paper/*` and `bib/*` rules ([rules](rules.md)); the hook `paper-edit-guard` refuses a shell write                      |
-| `CLAIMS.md`, `figures/`               | 4 draft          | you                                                                                                                                                                                              | nothing                                                                                                                              |
-| `paper.pdf`, `_build/`                | 6 submit         | `paperlint build`                                                                                                                                                                                | `pdf/*`, [`format/page-limit`](rules/format/page-limit.md), [`anonymity/identity`](rules/anonymity/identity.md), the reference rules |
-| `versions/`                           | 6, then 7        | you, at submission and at camera-ready (`submit-paper` says how): the frozen PDF and source of each stage                                                                                        | `paper/stages`, `paper/source`                                                                                                       |
-| `submission/`, `SUBMIT-CHECKLIST.md`  | 6 submit         | you, while `submit-paper` and `submission-portal` do the submitting: forms, portal records, mail with the venue                                                                                  | [`cycle/evidence`](rules/cycle/evidence.md), for the files a closed cycle names                                                      |
-| `talk/`                               | 7 camera-ready   | you                                                                                                                                                                                              | the `talk/*` rules ([talk](talk.md))                                                                                                 |
-| `extra/`                              | any              | you                                                                                                                                                                                              | nothing, ever                                                                                                                        |
+| place                                | stage            | written by                                                                                                                                                                                       | checked by                                                                                                                                                               |
+| ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `<papers-root>/venues/<venue>/`      | 2 venue          | `study-accepted-papers`, its first run for that venue (mode A, usually)                                                                                                                          | nothing ([why](venues.md#what-checks-it))                                                                                                                                |
+| the paper folder's root              | before 1         | `paperlint new`: the three files, and an empty `.gitkeep` folder for `reviews/`, `research/`, `figures/`, `versions/`, `submission/`, `repro/tools/`, `repro/data/` (`repro/` gets a stub index) | [`paper/allowed-files-only`](rules/paper/allowed-files-only.md); the hook `paper-folder-layout` refuses a new stray entry                                                |
+| `PIPELINE-STATUS.md`                 | every stage      | `paperlint new`, then `paper-pipeline`, `paper-status`; `study-accepted-papers` (the scorecard)                                                                                                  | `paper/stages`, `paper/source`, [`cycle/stage`](rules/cycle/stage.md) ([rules](rules.md))                                                                                |
+| `paperlint.json`                     | before 1, then 2 | `paperlint new`; `find-venue` names the venue                                                                                                                                                    | `paperlint lint` refuses an unknown key; [`cycle/record`](rules/cycle/record.md)                                                                                         |
+| `siblings/`                          | 1 idea           | `map-prior-work`, `analyze-sibling-paper`                                                                                                                                                        | `sibling/frontmatter` ([records](configuration.md#records-in-frontmatter-checked-by-shipped-json-schemas))                                                               |
+| `reviews/`                           | 2, then 4–5      | `study-accepted-papers` (its report), `grade-paper-writing`, `cold-read-diff`, the review skills                                                                                                 | `review/frontmatter` ([records](configuration.md#records-in-frontmatter-checked-by-shipped-json-schemas))                                                                |
+| `research/`                          | any              | you and the skills: dated research and decision records                                                                                                                                          | nothing                                                                                                                                                                  |
+| `repro/`, its top                    | 3 study          | `build-benchmark`, your scripts                                                                                                                                                                  | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md); the hook `paper-folder-layout` refuses a new loose entry                                                |
+| `repro/studies.json`                 | 3 study          | `paperlint studies new` appends a row; you edit a row when its study ends; `paperlint studies index` regenerates the index in `repro/README.md`                                                  | [`repro/study-registered`](rules/repro/study-registered.md): a row per study folder, its fields, the index in sync                                                       |
+| `repro/<id>-<slug>/`                 | 3 study          | `paperlint studies new` (the folder and its `README.md`), then `build-benchmark` (the design, in its `README.md`)                                                                                | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md): the name, and a `README.md` in it; [`repro/study-registered`](rules/repro/study-registered.md): its row |
+| `repro/<id>-<slug>/plan.json`        | 3 study          | `paperlint studies new` writes the template; `build-benchmark` fills it before the sample is drawn; you add the author's check                                                                   | [`repro/study-registered`](rules/repro/study-registered.md): its fields, filled once the study runs, and `author_check` in a headline measurement                        |
+| `repro/<id>-<slug>/prereg.json`      | 3 study          | the plan's old name, still read when the row names it                                                                                                                                            | [`repro/study-plan-name`](rules/repro/study-plan-name.md) (warning); [`study/declare-sample`](rules/study/declare-sample.md), off by default                             |
+| `repro/<id>-<slug>/data/`            | 3 study          | `build-label-page` exports the labels here                                                                                                                                                       | nothing                                                                                                                                                                  |
+| `repro/tools/`, `repro/data/`        | 3 study          | your scripts; `paperlint build` keeps `repro/data/references-cache.json`                                                                                                                         | nothing inside them                                                                                                                                                      |
+| `NOTES.md`                           | 3, then 4        | you: each number → the data it comes from; `build-label-page` adds a line per label file                                                                                                         | nothing                                                                                                                                                                  |
+| `paper.tex`, `sections/`, `*.bib`    | 4 draft          | `draft-paper`, `argument-arc`, `tighten-paper`                                                                                                                                                   | the `tex/*`, `paper/*` and `bib/*` rules ([rules](rules.md)); the hook `paper-edit-guard` refuses a shell write                                                          |
+| `CLAIMS.md`, `figures/`              | 4 draft          | you                                                                                                                                                                                              | nothing                                                                                                                                                                  |
+| `paper.pdf`, `_build/`               | 6 submit         | `paperlint build`                                                                                                                                                                                | `pdf/*`, [`format/page-limit`](rules/format/page-limit.md), [`anonymity/identity`](rules/anonymity/identity.md), the reference rules                                     |
+| `versions/`                          | 6, then 7        | you, at submission and at camera-ready (`submit-paper` says how): the frozen PDF and source of each stage                                                                                        | `paper/stages`, `paper/source`                                                                                                                                           |
+| `submission/`, `SUBMIT-CHECKLIST.md` | 6 submit         | you, while `submit-paper` and `submission-portal` do the submitting: forms, portal records, mail with the venue                                                                                  | [`cycle/evidence`](rules/cycle/evidence.md), for the files a closed cycle names                                                                                          |
+| `talk/`                              | 7 camera-ready   | you                                                                                                                                                                                              | the `talk/*` rules ([talk](talk.md))                                                                                                                                     |
+| `extra/`                             | any              | you                                                                                                                                                                                              | nothing, ever                                                                                                                                                            |
 
 ## What runs when
 
@@ -132,23 +135,25 @@ A check runs at one of four moments:
   The lint-only job skips what needs a build (pages, fonts, references).
 - **On demand** — a skill, when you ask for what it does. A skill stops nothing; it writes.
 
-| what                                                                                        | kind  | when it runs                                                | what it stops                                                                                                                  |
-| ------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `paper-folder-layout`                                                                       | hook  | before an agent creates a file (Edit, Write)                | a new entry the layout does not allow, at a paper's root or the top of its `repro/`; never an existing file                    |
-| `paper-edit-guard`                                                                          | hook  | before an agent's shell command                             | a shell command that writes or moves a paper's source, which would skip the hooks that run after an edit                       |
-| `paper-skills-nudge`                                                                        | hook  | after an agent edits a paper's source                       | nothing: it shows the agent the pre-submit checklist                                                                           |
-| `paper-status-gates`                                                                        | hook  | after an agent edits a paper's source                       | nothing: it prints the paper's readiness and its unrun gates, for a person reading the transcript                              |
-| [`paper/allowed-files-only`](rules/paper/allowed-files-only.md)                             | rule  | every `paperlint lint`, and CI                              | a stray file or folder at a paper's root (error)                                                                               |
-| [`repro/allowed-files-only`](rules/repro/allowed-files-only.md)                             | rule  | every `paperlint lint`, and CI                              | a loose entry at the top of `repro/`, an undated study folder, a study folder without `README.md` (error)                      |
-| [`study/declare-sample`](rules/study/declare-sample.md)                                     | rule  | every `paperlint lint`, and CI, once a paper turns it on    | a study's `prereg.json` without its population, strata, screens, coverage or the author's check (experimental, off by default) |
-| [`paper/folder-venue-leftover`](rules/paper/folder-venue-leftover.md)                       | rule  | every `paperlint lint`, and CI                              | nothing: it warns when the folder is named after another venue                                                                 |
-| `review/frontmatter`, `sibling/frontmatter`                                                 | rule  | every `paperlint lint`, and CI                              | a review whose findings break the schema (error); a sibling card that does not say how much was read (warning)                 |
-| `paper/stages`, `paper/source`                                                              | rule  | every `paperlint lint`, and CI                              | a stage whose frozen PDF or source is missing or changed (error)                                                               |
-| the rules on the source (`tex/*`, `paper/*`, `bib/*`)                                       | rule  | every `paperlint lint`, and CI                              | what each one's [row](rules.md) says                                                                                           |
-| the rules on what `paperlint build` measured (`pdf/*`, `format/page-limit`, the references) | rule  | every `paperlint lint` after a build; CI's full job         | a PDF over the page limit, in the wrong font or format, or with a bad reference                                                |
-| `study-accepted-papers`                                                                     | skill | when you ask; stage 2 (modes A, B) and stage 5 (modes C, D) | nothing: it fills the venue's corpus, and writes the strong-accept scorecard in `PIPELINE-STATUS.md`                           |
-| `build-benchmark`                                                                           | skill | when you ask; stage 3                                       | nothing: it writes the study's design and its `prereg.json`                                                                    |
-| `build-label-page`                                                                          | skill | when you ask; stage 3                                       | nothing: it builds the labelling page, and exports the answers into the study's `data/`                                        |
+| what                                                                                        | kind  | when it runs                                                | what it stops                                                                                                                                             |
+| ------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper-folder-layout`                                                                       | hook  | before an agent creates a file (Edit, Write)                | a new entry the layout does not allow, at a paper's root or the top of its `repro/`; never an existing file                                               |
+| `paper-edit-guard`                                                                          | hook  | before an agent's shell command                             | a shell command that writes or moves a paper's source, which would skip the hooks that run after an edit                                                  |
+| `paper-skills-nudge`                                                                        | hook  | after an agent edits a paper's source                       | nothing: it shows the agent the pre-submit checklist                                                                                                      |
+| `paper-status-gates`                                                                        | hook  | after an agent edits a paper's source                       | nothing: it prints the paper's readiness and its unrun gates, for a person reading the transcript                                                         |
+| [`paper/allowed-files-only`](rules/paper/allowed-files-only.md)                             | rule  | every `paperlint lint`, and CI                              | a stray file or folder at a paper's root (error)                                                                                                          |
+| [`repro/allowed-files-only`](rules/repro/allowed-files-only.md)                             | rule  | every `paperlint lint`, and CI                              | a loose entry at the top of `repro/`, a folder that is not a study's, a study folder without `README.md` (error)                                          |
+| [`repro/study-registered`](rules/repro/study-registered.md)                                 | rule  | every `paperlint lint`, and CI                              | a study folder without its row in `repro/studies.json`, a row that does not match, a measurement or plan that does not hold, an index out of sync (error) |
+| [`repro/study-plan-name`](rules/repro/study-plan-name.md)                                   | rule  | every `paperlint lint`, and CI                              | nothing: it warns when a study's plan is still named `prereg.json`                                                                                        |
+| [`study/declare-sample`](rules/study/declare-sample.md)                                     | rule  | every `paperlint lint`, and CI, once a paper turns it on    | a study's `prereg.json` without its population, strata, screens, coverage or the author's check (experimental, off by default)                            |
+| [`paper/folder-venue-leftover`](rules/paper/folder-venue-leftover.md)                       | rule  | every `paperlint lint`, and CI                              | nothing: it warns when the folder is named after another venue                                                                                            |
+| `review/frontmatter`, `sibling/frontmatter`                                                 | rule  | every `paperlint lint`, and CI                              | a review whose findings break the schema (error); a sibling card that does not say how much was read (warning)                                            |
+| `paper/stages`, `paper/source`                                                              | rule  | every `paperlint lint`, and CI                              | a stage whose frozen PDF or source is missing or changed (error)                                                                                          |
+| the rules on the source (`tex/*`, `paper/*`, `bib/*`)                                       | rule  | every `paperlint lint`, and CI                              | what each one's [row](rules.md) says                                                                                                                      |
+| the rules on what `paperlint build` measured (`pdf/*`, `format/page-limit`, the references) | rule  | every `paperlint lint` after a build; CI's full job         | a PDF over the page limit, in the wrong font or format, or with a bad reference                                                                           |
+| `study-accepted-papers`                                                                     | skill | when you ask; stage 2 (modes A, B) and stage 5 (modes C, D) | nothing: it fills the venue's corpus, and writes the strong-accept scorecard in `PIPELINE-STATUS.md`                                                      |
+| `build-benchmark`                                                                           | skill | when you ask; stage 3                                       | nothing: it registers the study with `paperlint studies new`, writes its design, fills its `plan.json`, and updates its row when it ends                  |
+| `build-label-page`                                                                          | skill | when you ask; stage 3                                       | nothing: it builds the labelling page, and exports the answers into the study's `data/`                                                                   |
 
 The hooks are wired by `paperlint init` ([`install.md`](install.md)). A rule's level and options:
 [`rules.md`](rules.md).

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

@@ -34,11 +34,12 @@ it: [the map](../../layout.md).
 ├── siblings/                      ← the cards of competing papers
 ├── research/                      ← dated research and decision records
 ├── repro/                         ← the reproduction artifact
-│   ├── README.md                  ← the index: one line per study
+│   ├── README.md                  ← the index: one line per study, generated from studies.json
+│   ├── studies.json               ← the study registry: id, title, status and result of each study
 │   ├── .gitignore                 ← keeps the scripts' byproducts out of git
 │   ├── tools/                     ← scripts used across the paper (numbers, figures, anonymity check, harnesses)
 │   ├── data/                      ← shared data (tables, caches)
-│   └── <slug>-YYYY-MM-DD/         ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)
+│   └── <id>-<slug>/               ← one folder per study or spike, named by its row in studies.json (P1-S03-baseline)
 │       └── README.md              ← required: what it asks, how to run it, what it found
 ├── figures/                       ← graphics and their sources
 ├── sections/                      ← the body, when it is split

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

@@ -7,8 +7,8 @@ per misplaced entry
 ## What it catches
 
 An entry at the top of a paper's `repro/` that is not part of its layout, and a study folder there
-without a `README.md`. `repro/` holds an index, the tools and data the whole paper shares, and one
-dated folder per study. Stage 3 of the pipeline, the study, writes here; the rule runs on every
+without a `README.md`. `repro/` holds an index, the study registry, the tools and data the whole
+paper shares, and one folder per study. Stage 3 of the pipeline, the study, writes here; the rule runs on every
 `paperlint lint` and in CI, and a hook refuses a new loose entry before it is written. The whole map:
 [`layout.md`](../../layout.md).
 
@@ -16,12 +16,13 @@ dated folder per study. Stage 3 of the pipeline, the study, writes here; the rul
 
 ```text
 repro/
-├── README.md           ← the index: one line per study
-├── .gitignore          ← keeps the scripts' byproducts out of git
-├── tools/              ← scripts used across the paper (numbers, figures, anonymity check, harnesses)
-├── data/               ← shared data (tables, caches)
-└── <slug>-YYYY-MM-DD/  ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)
-    └── README.md       ← required: what it asks, how to run it, what it found
+├── README.md      ← the index: one line per study, generated from studies.json
+├── studies.json   ← the study registry: id, title, status and result of each study
+├── .gitignore     ← keeps the scripts' byproducts out of git
+├── tools/         ← scripts used across the paper (numbers, figures, anonymity check, harnesses)
+├── data/          ← shared data (tables, caches)
+└── <id>-<slug>/   ← one folder per study or spike, named by its row in studies.json (P1-S03-baseline)
+    └── README.md  ← required: what it asks, how to run it, what it found
 ```
 
 <!-- layout:end -->
@@ -33,10 +34,16 @@ above, and it already holds the index.
 A loose note belongs in the folder of the study it is about, or in the paper's `research/` when it is
 research or a decision rather than the record of a run.
 
-**The date in a study's name** is the day the study began: `ablation-2026-10-12`. A month is
-accepted too, `human-labels-2026-10`: a study that ran over weeks (labelling, reading a corpus) has a
-month as its honest date, and both forms sort by time. The date must be a real one — no month 13, no
-30 February. The slug is lowercase letters and digits, words joined by single hyphens.
+**A study's name** is `<id>-<slug>`: the id of its row in `repro/studies.json` — the paper's prefix,
+`-S`, two or more digits — then a slug, lowercase letters and digits in words joined by single
+hyphens: `P1-S03-baseline`. `npx paperlint studies new` makes the folder, its `README.md` and its row.
+This rule accepts the shape; whether the row exists, and matches, is
+[`repro/study-registered`](study-registered.md).
+
+**The dated form, `<slug>-YYYY-MM-DD`**, is accepted too, so a paper that keeps its dated folders and
+turns `repro/study-registered` off is not broken: `ablation-2026-10-12`, the day the study began. A
+month is accepted as well, `human-labels-2026-10`, for a study that ran over weeks. The date must be a
+real one — no month 13, no 30 February.
 
 Never reported: what interpreters, package managers, test runners and the operating system leave in
 the folder they run in — `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`,
@@ -55,14 +62,15 @@ or where a new run goes. Each kind of material now has one place, and each study
 Failing: a script loose at the top.
 
 ```text
-papers/agent-rule-drift/PIPELINE-STATUS.md
+papers/example/PIPELINE-STATUS.md
   1:1  error  `repro/paper_numbers.py` is loose at the top of the paper's repro/ folder, which holds
-              only an index, the shared tools and data, and one dated folder per study. Where it
-              goes: repro/tools/ — the scripts used across the paper (numbers, figures, the anonymity
-              check, harnesses); a script only one study runs goes in that study's folder instead.
+              only an index, the study registry, the shared tools and data, and one folder per study.
+              Where it goes: repro/tools/ — the scripts used across the paper (numbers, figures, the
+              anonymity check, harnesses); a script only one study runs goes in that study's folder
+              instead.
 What repro/ holds (what interpreters and package managers leave there, like __pycache__/ and node_modules/, is never reported):
 repro/
-├── README.md           ← the index: one line per study
+├── README.md      ← the index: one line per study, generated from studies.json
 …
 Rule repro/allowed-files-only: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/allowed-files-only.md  repro/allowed-files-only
 ```
@@ -70,14 +78,14 @@ Rule repro/allowed-files-only: https://github.com/zernie/paperlint/blob/main/doc
 Each message names the entry and where it goes, and draws the layout above, so it reads on its own. Where
 an entry goes depends on what it is:
 
-| entry                                                                                                                          | where it goes                                                                                         |
-| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| a script (`.py`, `.ipynb`, `.sh`, `.js`, `.mjs`, `.ts`, `.r`, `.jl`, `.sql` …), `Makefile`, `requirements.txt`, `package.json` | `repro/tools/`, or the folder of the one study that runs it                                           |
-| data (`.tsv`, `.csv`, `.json`, `.jsonl`, `.yaml`, `.txt`, `.log`, `.parquet`, `.zip` …)                                        | `repro/data/`, or the folder of the one study that produced it                                        |
-| a note (`.md`)                                                                                                                 | the dated folder of the study it is about, or the paper's `research/`                                 |
-| a folder whose name is not `<slug>-YYYY-MM-DD`                                                                                 | rename it to `<slug>-YYYY-MM-DD` and give it a `README.md`; its first commit's date is a fine default |
-| a study folder without `README.md`                                                                                             | add one: what the study asks, how to run it, what it found; and a line in `repro/README.md`           |
-| anything else                                                                                                                  | by what it is, as above                                                                               |
+| entry                                                                                                                          | where it goes                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a script (`.py`, `.ipynb`, `.sh`, `.js`, `.mjs`, `.ts`, `.r`, `.jl`, `.sql` …), `Makefile`, `requirements.txt`, `package.json` | `repro/tools/`, or the folder of the one study that runs it                                                                                                          |
+| data (`.tsv`, `.csv`, `.json`, `.jsonl`, `.yaml`, `.txt`, `.log`, `.parquet`, `.zip` …)                                        | `repro/data/`, or the folder of the one study that produced it                                                                                                       |
+| a note (`.md`)                                                                                                                 | the folder of the study it is about, or the paper's `research/`                                                                                                      |
+| a folder whose name is neither `<id>-<slug>` nor `<slug>-YYYY-MM-DD`                                                           | rename it to `<id>-<slug>` with its row in `repro/studies.json` and a `README.md`; with `repro/study-registered` off, `<slug>-YYYY-MM-DD`, dated by its first commit |
+| a study folder without `README.md`                                                                                             | add one: what the study asks, how to run it, what it found; and the study's row in `repro/studies.json`                                                              |
+| anything else                                                                                                                  | by what it is, as above                                                                                                                                              |
 
 Three files paperlint itself once kept at the top of `repro/` are named with their new place and the
 command that moves them: `references-cache.json` → `repro/data/` (read by `paperlint build`),
@@ -98,7 +106,8 @@ No rule options.
 ## What it does not check
 
 - What is inside `tools/`, `data/` and the study folders.
-- Whether `repro/README.md` exists, or has a line for every study.
+- Whether every study folder has its row in `repro/studies.json`, and whether `repro/README.md`'s index
+  is in sync: that is [`repro/study-registered`](study-registered.md).
 - What a study's `README.md` says.
 - `repro/` itself: whether the paper has one is `paper/allowed-files-only`'s concern, and that rule never
   looks inside it. Each entry is judged by exactly one of the two rules.
@@ -106,18 +115,19 @@ No rule options.
 ## The hook
 
 The hook `paper-folder-layout` refuses, before it is written, a new file that would add an entry
-this rule reports — a loose file at the top of `repro/`, an undated folder, or a study folder whose
+this rule reports — a loose file at the top of `repro/`, a folder that is not a study's, or a study folder whose
 first file is not its `README.md` — with this rule's message as the reason. It never refuses a file
 that already exists, and it cannot see a shell `mv` or `cp`: the lint is the guarantee. What it does
 and does not do is on [`paper/allowed-files-only`'s page](../paper/allowed-files-only.md#the-hook-a-new-stray-entry-is-refused-before-it-is-written).
 
 ## How to fix
 
-Move or rename the entry where its message says, and update whatever names its path:
+Move or rename the entry where its message says, and update whatever names its path; a renamed study
+folder gets its row in `repro/studies.json` in the same commit:
 
 ```sh
-git mv papers/agent-rule-drift/repro/paper_numbers.py papers/agent-rule-drift/repro/tools/
-git mv papers/agent-rule-drift/repro/baseline papers/agent-rule-drift/repro/baseline-2026-08-05
+git mv papers/example/repro/paper_numbers.py papers/example/repro/tools/
+git mv papers/example/repro/baseline papers/example/repro/P1-S04-baseline
 ```
 
 To switch the rule off for one paper — say, one whose `repro/` predates the layout — set it in that