paperlint 10.3.0 → 10.4.1

package/dist/study-run.d.ts

@@ -0,0 +1,19 @@
+/** What a `paperlint studies` command on one study comes to: the lines it prints, or its refusal. */
+/** A refusal: the exit code, and the line that explains it. */
+export interface StudyRefusal {
+    readonly code: 1 | 2;
+    readonly line: string;
+}
+/** What a run came to: the lines it printed, or the refusal. */
+export type StudyRun = {
+    readonly ok: true;
+    readonly lines: readonly string[];
+} | {
+    readonly ok: false;
+    readonly refusal: StudyRefusal;
+};
+/** A refusal for the paper's state: exit 1. */
+export declare const refusal: (line: string) => StudyRefusal;
+/** The run that is `r`. */
+export declare const refused: (r: StudyRefusal) => StudyRun;
+//# sourceMappingURL=study-run.d.ts.map

package/dist/study-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"study-run.d.ts","sourceRoot":"","sources":["../src/study-run.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3D,+CAA+C;AAC/C,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,YAAmC,CAAC;AAE3E,2BAA2B;AAC3B,eAAO,MAAM,OAAO,GAAI,GAAG,YAAY,KAAG,QAGxC,CAAC"}

package/dist/study-run.js

@@ -0,0 +1,9 @@
+/** What a `paperlint studies` command on one study comes to: the lines it prints, or its refusal. */
+/** A refusal for the paper's state: exit 1. */
+export const refusal = (line) => ({ code: 1, line });
+/** The run that is `r`. */
+export const refused = (r) => ({
+    ok: false,
+    refusal: r,
+});
+//# sourceMappingURL=study-run.js.map

package/dist/study-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"study-run.js","sourceRoot":"","sources":["../src/study-run.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAarG,+CAA+C;AAC/C,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAE3E,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAe,EAAY,EAAE,CAAC,CAAC;IACrD,EAAE,EAAE,KAAK;IACT,OAAO,EAAE,CAAC;CACX,CAAC,CAAC"}

package/docs/design/study-modes.md

@@ -0,0 +1,265 @@
+# Study modes: decide first, or exploratory — design
+
+## Why
+
+A study's outcomes are computed by an automated runner in the same workspace where the people
+deciding its inputs work: which runs count, which units are excluded, whether a veto applies, whether
+the drawn sample is approved. If those decisions can be made — or changed — after an outcome has been
+seen, the decision can follow the result, and nothing in the repository says which came first.
+
+What is needed:
+
+1. every measurement says how its outcomes are kept from the decisions on its inputs, and none can
+   say nothing;
+2. the default needs no key and no outside service: the decision is recorded first, the run starts
+   after, and anyone with the repository can re-check the order;
+3. a study that cannot work that way is declared exploratory, with its reason, and reported as such;
+4. the paper's Methods and its reviewers read each study's mode, decision commit and first output
+   from one generated place, not from prose someone keeps in sync by hand.
+
+## What is decided
+
+### 1. One mode per measurement, in its plan
+
+A study's `plan.json` holds one `mode`, a union on its `kind` (`src/domain/study-mode.ts`):
+
+```json
+{ "mode": { "kind": "decide_before_run",
+            "outputs": ["out/**", "RESULTS.md"],
+            "decision": { "file": "repro/P1-S03-x/decision.md", "note": "exclusions and veto" } } }
+
+{ "mode": { "kind": "exploratory", "reason": "a first look at the logs, to find the question" } }
+```
+
+- **Exactly one, by construction.** The modes are one discriminated union, each variant closed: a
+  second mode's key in the same object is an unknown key, and an unknown `kind` is refused. This is
+  the parser's (`src/adapters/study-registry/`), not a later check.
+- **None is not ready.** The parser is told the study's `kind` (from its row). A `measurement`'s plan
+  without a mode is a **draft** naming `mode` among its empty texts, like an empty `question`: legal
+  while the study is `designing`, reported by `repro/study-registered` (`bad-plan`, `unfilled`) once
+  it runs, and a parse error when the author's check is already on it (the author approved an
+  incomplete plan). A spike, a tool, a data set, an artifact or a salvage may omit it.
+- **The default is written for you.** `paperlint studies new` writes a measurement's plan with
+  `decide_before_run`, its decision file named (`repro/<folder>/decision.md`), its outputs and note
+  left to fill — a draft until they are. The decision file itself is NOT created: an empty
+  placeholder that got committed would open the gate on nothing.
+- **Paths.** `outputs` are globs relative to the study's folder, inside it, never the study's
+  `README.md`. A decision `file` is relative to the **paper's** folder, so it may live beside the
+  study or anywhere in the paper (`research/decisions.md`); it may not leave the paper, and it is a
+  file's path — names joined by `/`, none empty, `.` or `..` — so `.` (the paper itself) or a path
+  ending in `/` cannot be written. A name that is a directory on disk is the gate's to refuse and the
+  rule's to report (`decision-not-file`): git answers for a directory with the commits of anything
+  under it. Whether a
+  decision inside the study's folder is matched by an output glob needs the folder, which the plan
+  does not hold: the rule reports it (`decision-is-output`) and the gate refuses it.
+- **Empty texts of a mode** — no outputs yet, an empty decision file or note, an empty reason — are a
+  draft's empty texts, named field by field (`mode.outputs`, `mode.decision.file`, …).
+
+### 2. `paperlint studies gate <paper-dir> <id>`
+
+Exit 0 only if the decision file exists and is committed as it stands (git's last commit for it, and
+nothing changed since), printing the commit and its date; exit 1 saying why otherwise (not
+committed, changed since its commit, committed and since deleted — not in HEAD, though `git log -1`
+names the deleting commit and the tree is clean — git unable to answer, no decision file named, a
+decision that is a directory, a decision its own outputs match). A runner calls it first:
+
+```sh
+npx paperlint studies gate papers/my-paper P1-S03 && ./run.sh
+```
+
+For an exploratory study it exits 0 and says it has no gate. A study that declares no mode, whose
+plan is still a draft, or whose id two rows of the registry share (the gate answers for exactly one
+study), is refused.
+
+### 3. `repro/outputs-before-decision` — the proof of order a reviewer can re-run
+
+An error, reported on `PIPELINE-STATUS.md`. For each decide-first study: every output whose first
+commit is not a strict descendant of the decision file's first commit (earlier, on another line of
+history, or in the same commit) is a finding; deleted outputs count. An output in the tree or in history while the
+decision was never committed is a finding, and so is a decision committed and since deleted
+(`decision-deleted`): it is not in HEAD, so no order is judged against it. A shallow clone, and a
+history git cannot read, are
+findings that say so — never a pass. The study's folder is walked without following a symbolic link
+(`ListEntries`, `src/ports/list-entries.ts`): a link is one entry, as git stores it, so a link to the
+folder itself cannot loop the walk and one outside brings no foreign file into the study.
+
+**Why a lint rule may ask git here.** Rules in `eslint-rules/` may not run git
+(`eslint.config.mjs`, `GIT_IN_A_RULE`): a pinned sha is deleted by a squash or a gc, and a shallow CI
+checkout has none. This rule pins no sha; it asks the history the checkout has for an order. A squash
+merge keeps that order when the decision was merged before the run — which is the decide-first
+workflow — and a shallow checkout is named by the rule (`fetch-depth: 0`).
+
+### 4. The index carries each study's mode
+
+`repro/README.md`'s study index (`paperlint studies index`, docs/design/study-registry.md) has three
+columns for this (`src/domain/index-columns.ts`):
+
+| column         | cell                                                                                                                         |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `mode`         | `decide_before_run`, `exploratory: <reason>`, or `—` for a study whose plan has none                                         |
+| `decision`     | the decision file's first commit (12 characters) and its date (`, deleted since` when it is not in HEAD), or `not committed` |
+| `first output` | the first commit of the oldest output and its date, or `none`                                                                |
+
+A sample row:
+
+```markdown
+| id     | title   | status | result   | in paper | mode              | decision                | first output            | folder                             |
+| ------ | ------- | ------ | -------- | -------- | ----------------- | ----------------------- | ----------------------- | ---------------------------------- |
+| P1-S01 | Outcome | done   | 41 of 60 | yes      | decide_before_run | 3f2a9c1d7e40 2026-10-14 | 8b51e0aa42c9 2026-10-15 | [P1-S01-outcome/](P1-S01-outcome/) |
+```
+
+- **The mode is compared, the commits are not.** The mode comes from the plan, which is in the tree,
+  so `repro/study-registered` reports an index whose mode column is not the plan's. The two commits
+  are what git's history said when `studies index` last ran: a squash merge or a rebase gives the
+  same files new commits, and a shallow CI clone has none to read, so the lint never compares those
+  two columns — comparing them would turn every squash merge red. `studies index` rewrites the README
+  whenever any column moved, and in a shallow clone writes `unknown (shallow clone)`. The order
+  itself is `repro/outputs-before-decision`'s to judge, not the table's.
+- **The skills read the table.** `draft-paper` writes the Methods sentence from it (decided before
+  the run, the decision's commit and date; exploratory studies labelled with their reason);
+  `harden-paper` and `pc-panel-review` check that every confirmatory claim rests on a
+  `decide_before_run` study whose decision commit precedes its first output, and flag a
+  "pre-registered" or "decided before" claim the table does not support; `tighten-paper` keeps that
+  sentence; `osf-artifact-upload` and `camera-ready` ship each plan, its decision file and the index,
+  with the whole history. Each regenerates the index first, so the commits are this checkout's.
+
+### 5. Reads stay inside the paper
+
+**What these checks guard against.** paperlint's checks guard against accidents and honest
+mistakes — a run started before the decision was committed, a decision edited or deleted afterwards,
+a path typed wrong — not against an author who controls the repository's history and sets out to
+forge it. The path rules below exist to keep every read inside the paper, so a mistyped row cannot
+make a command or a rule read, judge or write files that belong to nothing in it.
+
+Every command and rule that reads a study's folder — `studies gate`, `studies index` and `new`,
+`repro/outputs-before-decision`, and `repro/study-registered`'s reads of plans and result files —
+goes through one reader, `studyFolder` (`src/study-folder.ts`), built once per run from the paper's
+folder over `ListEntries`, which does not follow links. It decides first whether a row's folder may
+be entered at all (`refusal`): its `folder` is one folder directly inside `repro/` (`isFolderName`:
+not empty, not `.` or `..`, no separator or NUL) and not a symbolic link. Such a row is never read
+through: `studies index` and `new` refuse the registry, the gate refuses the study, the order rule
+treats it as no study, and `repro/study-registered` reads its plan and results as missing.
+
+A plan's path is held inside its folder by the registry rule's own `isInside`, the same on every
+platform (a backslash is refused outright). The reader walks the path one component at a time, and a
+plan or a result file whose path passes through a symbolic link — the file itself, or a directory
+above it — is never read. The gate refuses it naming the link, the order rule treats the study as
+declaring no mode, and `repro/study-registered` reports it (`bad-plan`, `result-file`) with the link.
+
+The decision file is held inside the paper by the schema (`staysInside`) and is judged by the same
+walk (`decisionEntry`, `entryAt`): every component of its path must be a real directory and the last
+a regular file. A directory or a symbolic link as the file itself is refused by the gate and reported
+by the rule (`decision-not-file`); a symbolic link above the file is refused naming that link
+(`decision-linked`).
+
+The plan reads, the result-file existence checks and the decision's path check take a `StudyFolder`
+and not `Files`, so a read that follows a link is not what those readers are handed. A study's
+outputs are listed through it too (`StudyFolder.list`).
+
+Only a **ready** plan's mode decides anything: the gate refuses a draft, naming its empty fields, and
+the order rule judges no draft — a draft may name no outputs, or an empty decision file.
+
+### 6. Legacy plans
+
+A plan still named `prereg.json` is parsed by its loose legacy schema, which never asks for a mode,
+and `repro/study-plan-name` keeps warning that it moves to `plan.json` — where the strict parser asks
+for one. So an old paper keeps linting as before until it renames the file. A `plan.json` written by
+the release before modes existed, for a measurement, reads as a draft whose empty text is `mode`:
+silent while the study is `designing`, reported once it runs, and an unreadable plan when the
+author's check is already on it (the message names `mode`). Adding one line — usually the
+decide-first mode — is the migration. An index generated before the mode columns existed is out of
+sync until `paperlint studies index` regenerates it.
+
+### 7. Why: confirmatory vs exploratory, and venues that review the plan first
+
+Read for this note (2026-10-16):
+
+- Nosek, Ebersole, DeHaven, Mellor, "The preregistration revolution", _PNAS_ 115(11):2600–2606,
+  2018 (metadata and abstract from Crossref, doi:10.1073/pnas.1708274114). The abstract, verbatim:
+
+  > Progress in science relies in part on generating hypotheses with existing observations and
+  > testing hypotheses with new observations. This distinction between postdiction and prediction
+  > is appreciated conceptually but is not respected in practice. Mistaking generation of
+  > postdictions with testing of predictions reduces the credibility of research findings. […] An
+  > effective solution is to define the research questions and analysis plan before observing the
+  > research outcomes—a process called preregistration. Preregistration distinguishes analyses and
+  > outcomes that result from predictions from those that result from postdictions.
+
+  This is the distinction the modes encode: decided first is prediction; exploratory is postdiction,
+  legitimate when it is labelled.
+
+- The MSR (Mining Software Repositories) Registered Reports track, 2020 edition
+  (https://2020.msrconf.org/track/msr-2020-Registered-Reports; the 2021, 2025 and 2026 editions have a
+  track page at the same address, the 2019 site has none there). Quoted from the 2020 page:
+
+  > Methods and proposed analyses are pre-registered and reviewed prior to research being conducted.
+
+  > (MSR 2020) Phase 1: Introduction, Methods (including proposed analyses), and Pilot Data (where
+  > applicable).
+
+  > (EMSE) Phase 2: full study, after data collection and analysis.
+
+  > Additional exploratory analyses in Phase 2 may be conducted, if they are justified.
+
+  > Any deviation from the protocol must be justified and logged in detail to ensure replicability.
+
+  A venue of this field already reviews the plan before the data, and accepts exploratory analyses
+  beside it only when they are justified. The modes, the order rule and the index give a paper the
+  same evidence in its own repository: what was fixed before the run, with its commit, and what was
+  exploratory, with its reason.
+
+## Alternatives considered
+
+- **Encrypting the outputs until the decision (age, to a key the author holds): rejected.** It needs
+  an external binary that `paperlint toolchain` does not install, and a key whose custody has no good
+  home: a session in the cloud has nowhere private to keep the identity, and a key in a CI secret is
+  readable by any workflow that can be edited. Decide first already proves the order from git with no
+  key at all, so encryption would add a dependency and a secret to guard to buy what the history
+  shows. Blind analysis in physics (Klein & Roodman, _Annu. Rev. Nucl. Part. Sci._ 55, 2005) and
+  MacCoun & Perlmutter, "Hide results to seek the truth" (_Nature_ 526, 2015) — both cited from
+  memory, not re-read for this note — are where the idea comes from; what is kept is that the
+  decision is fixed and recorded before the outcome is seen.
+- **Paragraph links (`% study: <id>` comments in `paper.tex`) checked by lint rules: rejected.** Such
+  rules check only the paragraphs that carry a convention authors do not write, so an unlinked
+  overclaim passes silently. The review skills check the Methods sentence and every confirmatory
+  claim against the index instead, which covers the whole text.
+- **A separate `studies methods` command printing the modes and commits: rejected.** The same facts
+  are three columns of the `studies index` table the registry already generates; a second command
+  would be a second rendering of one set of facts.
+- **Comparing the decision and first-output columns in the lint: rejected.** A squash merge renames
+  the commits, so the index would go stale on every merge, and a shallow CI clone cannot read them;
+  the order rule judges the history directly instead (§4).
+- **An outside pre-registration (OSF, AsPredicted) as the record: not required.** A timestamped
+  record before the outcome is what they give; here the repository's history is that record,
+  re-checkable by anyone who clones it. A paper may still register outside and cite it.
+
+## Where each part lives
+
+| part                                                         | file                                  | layer   |
+| ------------------------------------------------------------ | ------------------------------------- | ------- |
+| the modes, what is an output, which decision a mode waits on | `src/domain/study-mode.ts`            | domain  |
+| the order judge and its messages                             | `src/domain/decide-first.ts`          | domain  |
+| the index's mode columns and the history they show           | `src/domain/index-columns.ts`         | domain  |
+| the index, which columns the lint compares, `isFolderName`   | `src/domain/study-registry.ts`        | domain  |
+| the schema of `mode`; readiness by kind                      | `src/adapters/study-registry/`        | adapter |
+| git: committed state, first commits, ancestry, shallow       | `src/adapters/git/`                   | adapter |
+| what the app asks of git                                     | `src/ports/git-history.ts`            | port    |
+| a directory's entries, links not followed                    | `src/ports/list-entries.ts`           | port    |
+| the studies with a mode, and how a decision's path stands    | `src/study-modes.ts`                  | app     |
+| what the study readers need of a study's folder              | `src/ports/study-folder.ts`           | port    |
+| what the study readers are handed                            | `src/ports/study-deps.ts`             | port    |
+| the one reader of a study's folder, links not followed       | `src/study-folder.ts`                 | app     |
+| the order rule                                               | `src/outputs-before-decision-rule.ts` | app     |
+| the plans and histories `studies index` and `new` write from | `src/study-index-input.ts`            | app     |
+| `gate`; `new` and `index`                                    | `src/study-gate.ts`, `src/studies.ts` | app     |
+| wiring: git with PATH and HOME, the clock                    | `src/cli.ts`                          | root    |
+
+## What it does not check
+
+- What a decision says. The gate is that it is committed, not its content.
+- A decision amended after the outputs: `repro/outputs-before-decision` orders FIRST commits; later
+  edits of the decision are in its history but not reported.
+- That nobody ran a decide-first study before its decision and kept the outputs out of git. The rule
+  keeps early outputs out of the repository's history, not out of a person's hands.
+- Files outside the study's folder as outputs: outputs are relative to it by construction.
+- Whether the paper's text matches the index: that is the review skills' job, not a lint rule's.

package/docs/design/study-registry.md

@@ -205,6 +205,12 @@ two commands that write it.
    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.
 
+8. **A study's mode.** A measurement's plan declares how its outcomes are kept from the decisions
+   on its inputs: `decide_before_run` (the default `studies new` writes) or `exploratory` with its
+   reason. `paperlint studies gate` and the rule `repro/outputs-before-decision` hold it, and the
+   index carries it in three columns: the mode, the decision's first commit and date, and the first
+   output's commit. Its own note: [`study-modes.md`](study-modes.md).
+
 ## Where each part lives
 
 | part                                   | file                                | layer   |

package/docs/e2e.md

@@ -8,10 +8,14 @@ or CI:
 | -------------------------- | ------------- | -------------------------------------------- | --------------------------- |
 | `npm run test:e2e:install` | `e2e-install` | npm and pnpm, and the network for `npm pack` | `test/e2e/install/*.e2e.ts` |
 | `npm run test:e2e:tex`     | `e2e-tex`     | TeX Live from `paperlint toolchain`, banal   | `test/e2e/tex/*.e2e.ts`     |
-| `npm run test:e2e`         | both          |                                              |                             |
-
-Both areas are part of `npm run check`, so nobody has to remember to call them. CI runs each in the
-job that has its environment: `test:e2e:install` in `gates`, `test:e2e:tex` in `build-e2e`.
+| `npm run test:e2e:studies` | `e2e-studies` | git                                          | `test/e2e/studies/*.e2e.ts` |
+| `npm run test:e2e`         | all three     |                                              |                             |
+
+All three areas are part of `npm run check`, so nobody has to remember to call them. CI runs each in
+the job that has its environment: `test:e2e:install` and `test:e2e:studies` in `gates`, `test:e2e:tex`
+in `build-e2e`. The studies run drives a study decided before its run through the real binary in a
+real git repository: the gate, the order the lint reads, a shallow clone named, and the two commits
+`studies index` writes into the index.
 
 This page says what they prove, what they deliberately do not, and when a change owes a new one.
 

package/docs/layout.md

@@ -112,6 +112,7 @@ Both are explained in [`venues.md`](venues.md).
 | `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>/decision.md`      | 3 study          | you: the decisions on the inputs of a study decided before its run, committed before the run (`paperlint studies gate`); the plan names it, and it may live elsewhere in the paper               | [`repro/outputs-before-decision`](rules/repro/outputs-before-decision.md)                                                                                                |
 | `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                                                                                                                                                                  |
@@ -135,25 +136,27 @@ 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/`, 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/`                                                                   |
+| 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`                                                                                        |
+| [`repro/outputs-before-decision`](rules/repro/outputs-before-decision.md)                   | rule    | every `paperlint lint`, and CI (with the whole history)     | an output of a study decided before its run that git shows was not made after the decision                                                                |
+| `paperlint studies gate`                                                                    | command | before a decide-first study's run                           | the run, until the decision is committed                                                                                                                  |
+| [`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/repro/outputs-before-decision.md

@@ -0,0 +1,122 @@
+# repro/outputs-before-decision
+
+**Level:** error · **Reads:** `repro/studies.json`, each study's `plan.json`, the files under a
+decide-first study's folder, and git's history of them · **Reported on:** the first line of the
+paper's `PIPELINE-STATUS.md`, once per finding
+
+## What it catches
+
+A study decided before its run — its plan's `mode` is `decide_before_run`, the default
+`paperlint studies new` writes for a measurement — whose history does not show that order:
+
+```json
+{
+  "mode": {
+    "kind": "decide_before_run",
+    "outputs": ["out/**", "RESULTS.md"],
+    "decision": {
+      "file": "repro/P1-S01-outcome/decision.md",
+      "note": "exclusions, veto, and the sample approved"
+    }
+  }
+}
+```
+
+- **`output-before-decision`** — an output (a file the `outputs` globs match, under the study's
+  folder) whose FIRST commit is not a strict descendant of the decision file's FIRST commit: earlier,
+  on a line of history the decision is not on, or in the very same commit, which says nothing about
+  which came first. An output committed and later deleted still counts.
+- **`undecided-output`** — an output in the tree, or one ever committed and since deleted, while the
+  decision file has never been committed.
+- **`decision-is-output`** — the decision file lies in the study's folder and an output glob matches
+  it: the decision would be a file its own run produces.
+- **`decision-deleted`** — the decision file was committed and later deleted: it is not in HEAD, so
+  the study has no decision its outputs could follow, and the order is not judged against it.
+- **`decision-not-file`** — the decision path names a directory or a symbolic link: git answers for
+  a directory with the commits of anything under it, and records a link rather than the file it
+  points to, so no order is read from either. (A path that names the paper's folder
+  itself, `.`, or ends in `/` is refused when the plan is parsed.)
+- **`decision-linked`** — the decision path passes through a symbolic link above the file: git
+  records the link, not the files behind it, so no order is read from it, and the finding names the
+  link.
+- **`shallow`** — the clone is shallow, so every file's first commit is the clone's: no order can be
+  read, and the rule says so instead of judging.
+- **`no-history`** — git could not answer (not installed, not a repository).
+
+The study's own files — `plan.json`, `README.md` and the decision file — are never outputs. A symbolic
+link in the study's folder is one entry, as git stores it, and is never followed: a link to the folder
+itself cannot loop the walk, and one to a tree outside brings none of its files into the study.
+
+## Why
+
+A measurement's inputs — which runs count, which units are excluded, whether the sample is approved
+— must be decided before anyone has seen an outcome; otherwise the decision can follow the result.
+"Decide first, then compute" needs no key and no encryption: the decision is committed, the run
+starts only after (`paperlint studies gate` exits 0 only then), and git's history is the proof of
+order. This rule re-reads that proof on every lint, so a reviewer who clones the repository can run
+the same check and get the same answer. The design is
+[`docs/design/study-modes.md`](../../design/study-modes.md).
+
+**It asks git for an order, never pins a sha**, which is why it can live as a lint rule (rules in
+`eslint-rules/` may not run git: a pinned sha is deleted by a squash or a gc). A squash merge keeps
+the order when the decision was merged before the run — the decide-first workflow — and a shallow
+checkout is named, not read as a violation.
+
+## Examples
+
+Failing:
+
+```text
+papers/example/PIPELINE-STATUS.md
+  1:1  error  `repro/P1-S01-outcome/RESULTS.md`, an output of `P1-S01`, entered history in
+              4f2a9c0e1b7d (2026-10-16T10:00:00+05:00), the very commit that first recorded its
+              decision, 4f2a9c0e1b7d (2026-10-16T10:00:00+05:00). The study is declared decided
+              before its run, and its history does not show that order. What to do: if the decision
+              really came first, nothing in this history can prove it — declare the study
+              `exploratory` with the reason, or run it again after the decision; never rewrite the
+              history to make it pass.
+Rule repro/outputs-before-decision: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/outputs-before-decision.md  repro/outputs-before-decision
+```
+
+Passing: `decision.md` committed in one commit; `RESULTS.md` and `out/` committed in a later commit
+that descends from it. An `exploratory` study is not this rule's.
+
+## Options / preset fields
+
+No rule options. The study declares its mode in its plan.
+
+## What it does not check
+
+- What the decision says. The gate is that it is committed, not its content.
+- **A decision amended after the outputs**: the order is between FIRST commits. A later edit of the
+  decision file is visible in its history (`git log -- <file>`) but not reported.
+- That nobody ran the study before the decision and kept the outputs out of git. History records
+  what was committed; a run on a machine that never committed it leaves no trace.
+- A study whose row names a folder that is not one inside `repro/` (`../x`), or a folder that is a
+  symbolic link: nothing is read through it, so it is no study here;
+  [`repro/study-registered`](study-registered.md) reports the row or reads its plan as missing.
+- A study whose plan is still a draft: only a ready plan's mode decides anything, and
+  [`repro/study-registered`](study-registered.md) reports an unfilled plan once the study runs.
+- Commit dates. They are shown in the message, but the order is ancestry, which a rebase can
+  rewrite only by making a new history that a reviewer comparing against the published one sees.
+
+## How to fix
+
+Commit the decision first, then let the run start:
+
+```sh
+git add papers/example/repro/P1-S01-outcome/decision.md && git commit -m "P1-S01: decision"
+npx paperlint studies gate papers/example P1-S01 && ./run.sh
+```
+
+In CI, check out the whole history: `actions/checkout` with `fetch-depth: 0`. A study whose outputs
+were made before its decision cannot be repaired by editing history; declare it exploratory:
+
+```json
+{
+  "mode": {
+    "kind": "exploratory",
+    "reason": "outputs existed before the exclusions were fixed"
+  }
+}
+```