paperlint 7.1.0 → 7.2.0

package/docs/configuration.md

@@ -1,3 +1,5 @@
+| `deadlines` | one entry per deadline, `{ "what", "observed", "override" }` — see [Deadlines](#deadlines) below |
+
 # Configuration reference
 
 paperlint reads one file name at two levels, `paperlint.json`, with one schema. Both files are
@@ -96,16 +98,17 @@ The same keys as the root file, minus the project-only ones (`papersDir`, `struc
 skills' keys), which are refused here by name, plus `talk` and `submission`, which only a paper has. **It merges over the root file:** its `extends`,
 `kind` and `pdf` win; one it does not set comes from the root.
 
-| key          | what it is                                                                                                                                                                                                             |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `extends`    | the venue preset the built PDF is judged against: `paperlint:<name>` (shipped) or `./path` / `../path` (your own, relative to this file) — [`rules.md`](rules.md#checks-against-the-venue)                             |
-| `kind`       | the kind of paper (`short`, `research`, …) whose page limit applies                                                                                                                                                    |
-| `pdf`        | where the built PDF is, relative to the paper, when it is not `paper.pdf`                                                                                                                                              |
-| `identity`   | what identifies the authors — names, handles, emails, affiliations, your own project names. A blind venue's PDF must say none of it ([`anonymity/identity`](rules/anonymity/identity.md)). Joined with the root's list |
-| `talk`       | how this paper is presented, `{ "mode": "remote-video" }` plus optional `dir`, `files`, `one_slide` — the `talk/*` rules judge its finished files ([`talk.md`](talk.md)). Only here: the root file refuses it          |
-| `submission` | which submission on the venue's portal is this paper's, `{ "id": 7 }` — read by [`paperlint submission`](submission.md), with the preset's `portal`. Only here: the root file refuses it                               |
-| `rules`      | rule overrides for this paper alone — `{ "<rule>": "<severity>" }`, or blocks with globs relative to the paper                                                                                                         |
-| `$comment`   | a note for humans; ignored                                                                                                                                                                                             |
+| key          | what it is                                                                                                                                                                                                                                                            |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `extends`    | the venue preset the built PDF is judged against: `paperlint:<name>` (shipped) or `./path` / `../path` (your own, relative to this file) — [`rules.md`](rules.md#checks-against-the-venue)                                                                            |
+| `kind`       | the kind of paper (`short`, `research`, …) whose page limit applies                                                                                                                                                                                                   |
+| `pdf`        | where the built PDF is, relative to the paper, when it is not `paper.pdf`                                                                                                                                                                                             |
+| `identity`   | what identifies the authors — names, handles, emails, affiliations, your own project names. A blind venue's PDF must say none of it ([`anonymity/identity`](rules/anonymity/identity.md)). Joined with the root's list                                                |
+| `talk`       | how this paper is presented, `{ "mode": "remote-video" }` plus optional `dir`, `files`, `one_slide` — the `talk/*` rules judge its finished files ([`talk.md`](talk.md)). Only here: the root file refuses it                                                         |
+| `submission` | which submission on the venue's portal is this paper's, `{ "id": 7 }` — read by [`paperlint submission`](submission.md), with the preset's `portal`. Only here: the root file refuses it                                                                              |
+| `cycles`     | the paper's attempts at venues, one entry per attempt, oldest first — see [The paper's cycles](#the-papers-cycles) below. With it, `extends`, `kind` and `submission` are the current attempt's and may not be written beside it. Only here: the root file refuses it |
+| `rules`      | rule overrides for this paper alone — `{ "<rule>": "<severity>" }`, or blocks with globs relative to the paper                                                                                                                                                        |
+| `$comment`   | a note for humans; ignored                                                                                                                                                                                                                                            |
 
 `paperlint new` writes this file from the template (`templates/paper/paperlint.json`, or your
 `<papers>/.template/paperlint.json` if you keep one). With `--venue` it writes the venue into it:
@@ -132,7 +135,8 @@ npx paperlint new my-paper --venue ./venues/my-workshop.jsonc     # "extends": "
 Without a venue the file has `"extends": null` and a `$comment` saying what goes there. Until
 `extends` names a preset (here or in the root file), `paperlint lint` gives that paper one warning,
 `pdf/measured`: "this paper names no venue preset yet … set "extends" in
-papers/my-paper/paperlint.json".
+papers/my-paper/paperlint.json". A paper keeping `cycles` is told instead to set the venue in its
+current cycle — `extends` beside `cycles` is refused.
 
 **Any other key is an error**, in either file, named in the message: `paperlint.json: unknown key
 "papersdir"`. A misspelt key would otherwise read as "not set", and the setting you meant would
@@ -144,6 +148,130 @@ the root `paperlint.json`'s `rules` → the paper's own `rules`. So a venue can
 project can change that for every paper, and one paper can still change it for itself. Only rules
 paperlint ships may be named, at every level.
 
+## The paper's cycles
+
+A paper goes to a venue, is rejected, and goes to the next one. `cycles` records each attempt as
+one entry, oldest first; `extends`, `kind` and `submission` are then **derived** from the current
+attempt — the one open cycle, or the accepted last one — and writing any of them beside `cycles`
+is refused as a second source for one fact.
+
+```jsonc
+{
+  "pdf": "build/paper.pdf",
+  "cycles": [
+    {
+      "id": "alpha-2026", // what a stage's `cycle:` names
+      "venue": { "kind": "preset", "extends": "paperlint:acm-sigconf" },
+      "kind": "short",
+      "opened": "2026-07-01", // the day this attempt was decided
+      "deadlines": [
+        {
+          "what": "submission",
+          "observed": [
+            {
+              "at": "2026-08-06 AoE",
+              "source": "call",
+              "url": "https://alpha.example/cfp",
+              "read": "2026-07-01",
+            },
+          ],
+        },
+      ],
+      "outcome": {
+        "kind": "rejected",
+        "date": "2026-09-08",
+        "desk": false,
+        "evidence": "reviews/alpha-decision.md",
+      },
+    },
+    {
+      "id": "beta-2027",
+      "venue": { "kind": "preset", "extends": "paperlint:ieee-conference" },
+      "opened": "2026-09-09",
+      "phase": "porting", // the source is still in alpha's template
+      "deadlines": [
+        {
+          "what": "submission",
+          "observed": [
+            {
+              "at": "2026-10-20T04:00:00Z",
+              "source": "portal",
+              "url": "https://beta.example/deadlines",
+              "read": "2026-09-09",
+            },
+            {
+              "at": "2026-10-23 AoE",
+              "source": "call",
+              "url": "https://beta.example/cfp",
+              "read": "2026-09-09",
+            },
+          ],
+          "override": {
+            "at": "2026-10-27T04:00:00Z",
+            "reason": "the chairs extended the deadline by mail",
+            "evidence": "mail/extension.eml",
+          },
+        },
+      ],
+      "submission": { "id": 7 },
+    },
+  ],
+}
+```
+
+| field        | what it is                                                                                                                                                                                                                                                                                                                       |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`         | unique in the list; a scorecard stage names it as `cycle: <id>` ([`cycle/stage`](rules/cycle/stage.md))                                                                                                                                                                                                                          |
+| `venue`      | `{ "kind": "preset", "extends": "paperlint:<name>" \| "./path" }` — resolved as `extends` is; or `{ "kind": "named", "name", "url" }` for a venue with no preset yet. A named venue has no format rules                                                                                                                          |
+| `kind`       | a key of the preset's `format.kinds`; omit when the venue has one kind                                                                                                                                                                                                                                                           |
+| `opened`     | `YYYY-MM-DD`, the day this attempt was decided — the boundary a consumer judges the scorecard's rows against                                                                                                                                                                                                                     |
+| `phase`      | `"porting"` while the source is still in the previous venue's template: every `pdf/*`, `format/*`, `anonymity/*` and `tex/*` venue rule is silent for the paper, and [`cycle/port-done`](rules/cycle/port-done.md) fires once the class line is the venue's. Default `"prepared"`                                                |
+| `deadlines`  | a list of `{ "what", "at", "source", "url" }`: `what` is `registration`, `submission`, `resubmission`, `notification` or `camera-ready`; `at` an instant with its zone (`2026-10-20T04:00:00Z`) or a call's `"YYYY-MM-DD AoE"`; `source` is `"portal"` or `"call"` — where it was read ([`cycle/record`](rules/cycle/record.md)) |
+| `submission` | which submission on the venue's portal is this paper's, `{ "id": 7 }` — what the flat `submission` key is                                                                                                                                                                                                                        |
+| `outcome`    | `{ "kind": "open" }` (the default), or `accepted` \| `rejected` \| `withdrawn` with `date` and `evidence`, a file in the paper folder ([`cycle/evidence`](rules/cycle/evidence.md)); `rejected` may add `"desk": true`                                                                                                           |
+
+**One open cycle at most, and it is the last entry.** Two open cycles is dual submission or a
+decision nobody recorded; `paperlint lint` refuses the file with one line naming both ids. A paper
+whose last cycle is rejected or withdrawn and has no open one is between venues: `extends` derives
+to null and the venue rules say nothing. An accepted last cycle keeps the paper at that venue —
+camera-ready and talk are judged against it, and the venue's blindness no longer applies.
+
+Papers without `cycles` read exactly as before.
+
+### Deadlines
+
+A deadline records **what each page said**, and optionally **a human decision that overrides it**:
+
+| field      | what it is                                                                                                                                                                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `what`     | `registration` — the abstract registration, a call's "abstract" date · `submission` — the full paper, a call's "paper" date, HotCRP's "submissions must be completed by" · `resubmission` — updates to a completed submission · `notification` · `camera-ready`                                         |
+| `observed` | the readings: `{ "at", "source", "url", "read" }` — `at` an instant with its zone (`2026-10-20T04:00:00Z`) or a call's `"YYYY-MM-DD AoE"` (paperlint converts it to the end of that day at UTC−12); `source` `"portal"` or `"call"`; `url` the page; `read` the day it was read. One reading per source |
+| `override` | `{ "at", "reason", "evidence" }` — an instant that binds instead, why, and a file in the paper folder it rests on (the chairs' mail). [`cycle/evidence`](rules/cycle/evidence.md) requires the file                                                                                                     |
+
+**Which instant is in force:** the `override` when there is one; otherwise the **earliest** reading.
+The portal and the call often disagree — at MSR 2027 the portal's "submissions must be completed by"
+is 04:00 UTC on the call's _abstract_ day, four days before the call's _paper_ day — and both are kept:
+the earlier one is the safe one, and recording both is not an error. The kinds map a call's words
+honestly: the call's "abstract" is `registration`, its "paper" is `submission`; the portal's earlier
+`submission` then binds. A deadline moved by the chairs' mail is an `override` with the mail as its
+evidence, never a reading with a made-up source. Any key the record does not know — in a deadline, a
+reading, an override, an outcome, a venue — is an error, so an override typed under another name
+cannot look recorded and not be in force.
+
+**Where the readings come from.** A shipped venue preset whose venue takes submissions on HotCRP
+carries the portal's readings itself, as `deadlines` (`presets/msr.jsonc`). A cycle whose venue is that
+preset **derives** them: write only what the call says and any override; a portal reading the preset
+already carries is reported by [`cycle/record`](rules/cycle/record.md) as a second copy. A scheduled
+workflow in paperlint's repository re-reads every such portal once a day and, when a value changed,
+opens a pull request that releases a patch — **so new dates reach your papers through your normal
+dependency update** (Dependabot or Renovate bumping `paperlint`); there is nothing to run. A venue
+without a preset (`"venue": { "kind": "named", … }`) has no one reading it for you: type its
+deadlines from its call, `"source": "call"`, and re-read the call yourself.
+
+**`paperlint lint` never reads the clock.** It checks the record — instants with zones, each source's
+deadlines in order, the evidence on disk — and gives the same answer tomorrow for the same files.
+How many days are left is a status view's or a calendar's question, not a gate's.
+
 ## Records in frontmatter, checked by shipped JSON Schemas
 
 Two kinds of file under a paper keep a record in their YAML frontmatter, and paperlint validates

package/docs/rules/cycle/evidence.md

@@ -0,0 +1,87 @@
+# cycle/evidence
+
+**Level:** error · **Reads:** the paper's `paperlint.json` (`cycles`) and the paper folder ·
+**Reported on:** the first line of the paper's `PIPELINE-STATUS.md`
+
+## What it catches
+
+A closed cycle — `outcome.kind` is `accepted`, `rejected` or `withdrawn` — names an `evidence`
+file that is not in the paper folder: the decision mail, the reviews, or the note that records the
+withdrawal was never saved, or the path is wrong.
+
+The same for a deadline's `override`: the instant a human decided binds instead of what the pages
+said rests on its `evidence` — the chairs' mail that extended the deadline, a saved page — and that
+file must be in the paper folder.
+
+## Why
+
+The outcome of an attempt is a claim about what a venue decided, and the record is read by people
+and programs that were not there when the mail arrived: a status command, a scorecard check, the
+next attempt's prior-work delta. A decision whose evidence is not in the folder is a claim with
+nothing behind it, and the day it is doubted there is nowhere to look. The record therefore refuses
+an outcome without `evidence` at all, and this rule requires the file to exist.
+
+## Examples
+
+Failing — `paperlint.json`:
+
+```json
+{
+  "cycles": [
+    {
+      "id": "first-2026",
+      "venue": { "kind": "preset", "extends": "paperlint:acm-sigconf" },
+      "opened": "2026-07-01",
+      "outcome": {
+        "kind": "rejected",
+        "date": "2026-09-08",
+        "evidence": "reviews/decision.md"
+      }
+    }
+  ]
+}
+```
+
+with no `reviews/decision.md` in the paper folder:
+
+```text
+papers/my-paper/PIPELINE-STATUS.md
+  1:1  error  cycle «first-2026» is rejected (2026-09-08) with evidence `reviews/decision.md`, which is
+              not in the paper folder — save the decision mail, the reviews or the note that records
+              the decision there, or correct the path  cycle/evidence
+```
+
+An override whose evidence was never saved:
+
+```text
+  1:1  error  cycle «msr-2027»: the override of the "submission" deadline (2026-10-27T04:00:00Z)
+              rests on `mail/extension.eml`, which is not in the paper folder — save the mail or the
+              page that grants it there, or correct the path  cycle/evidence
+```
+
+Passing:
+
+- the same record with `reviews/decision.md` present;
+- an open cycle (`"outcome": { "kind": "open" }`, or no `outcome`): nothing has been decided;
+- a paper whose `paperlint.json` has no `cycles`.
+
+## Options / preset fields
+
+No rule options. `evidence` is a path relative to the paper folder; it may name any file — the
+saved mail, a markdown note with the reviews, a PDF.
+
+## What it does not check
+
+- What the file says. A rejection recorded as `accepted` with the rejection mail as evidence passes
+  here; the person who records the outcome reads the mail. Likewise an override's mail is not read
+  for its date.
+- The `date`. It must be a day (`YYYY-MM-DD`), nothing more.
+- Whether a `desk` rejection is marked as such (`"desk": true`); it changes what work follows, not
+  whether the record is consistent.
+
+## How to fix
+
+Save the decision in the paper folder — the mail as it arrived, the reviews as the portal shows
+them, or a dated note that records a withdrawal and why — and name that file in `evidence`. If the
+file exists under another name, correct the path. For an override, save the mail or page that moved
+the deadline and name it in the override's `evidence`.

package/docs/rules/cycle/port-done.md

@@ -0,0 +1,75 @@
+# cycle/port-done
+
+**Level:** error · **Reads:** `paper.tex` → the paper's `paperlint.json` (`cycles`) → the venue
+preset's `template` · **Reported on:** `paper.tex`
+
+## What it catches
+
+The current cycle declares `"phase": "porting"` — the source is still in the previous venue's
+template, so the venue's format rules are silent — and the paper's `\documentclass` is already the
+one the venue's preset requires. The port is done and the declaration is stale.
+
+## Why
+
+`"phase": "porting"` is a record of open work, not a softer severity: the day a new venue is chosen
+the source is still in the old venue's template, and a page count under the wrong template says
+nothing about the new limit. While the phase is declared, every `pdf/*`, `format/*`, `anonymity/*`
+and `tex/*` venue rule stays silent for that paper. A declaration that silences rules must not be
+able to stay on after its reason is gone: once the class line is the venue's, this rule fires, and
+the only way to be quiet again is to drop the phase — which turns the format rules back on.
+
+## Examples
+
+Failing — `paperlint.json`:
+
+```json
+{
+  "cycles": [
+    {
+      "id": "blind-2027",
+      "venue": { "kind": "preset", "extends": "./blindconf.jsonc" },
+      "opened": "2026-09-09",
+      "phase": "porting"
+    }
+  ]
+}
+```
+
+where the preset's `template` is `\documentclass[conference,compsoc]{IEEEtran}`, and `paper.tex`
+begins with that very line:
+
+```text
+papers/my-paper/paper.tex
+  1:1  error  the \documentclass is already `\documentclass[conference,compsoc]{IEEEtran}`, which
+              BlindConf requires, and the cycle «blind-2027» still declares "phase": "porting" — the
+              port is done: remove the phase, so the venue's format rules judge this paper again
+              cycle/port-done
+```
+
+Passing:
+
+- the same paper with the phase removed (or `"phase": "prepared"`);
+- a cycle still porting whose `paper.tex` still has the old venue's class line — the port is open
+  work, as declared;
+- a preset that names no `template`: there is nothing to compare, as for `tex/template`;
+- a paper whose `paperlint.json` has no `cycles`.
+
+## Options / preset fields
+
+No rule options. It reads the preset's `template`, the field [`tex/template`](../tex/template.md)
+reads, and compares the way that rule does.
+
+## What it does not check
+
+- Whether the port is complete beyond the class line — the page limit, the fonts, the sections. Those
+  are the format rules' to judge, and they judge again the moment the phase is dropped.
+- A cycle declared `porting` whose class line is still the old one: that is the state the phase
+  describes.
+- A `porting` cycle that has already sent a PDF — [`cycle/stage`](stage.md) reports that on the
+  scorecard.
+
+## How to fix
+
+Remove `"phase": "porting"` from the current cycle in `paperlint.json`, then run `paperlint lint`
+and `paperlint build`: the venue's format rules judge the paper again, and what they report is the
+rest of the port.

package/docs/rules/cycle/record.md

@@ -0,0 +1,152 @@
+# cycle/record
+
+**Level:** error · **Reads:** the paper's `paperlint.json` (`cycles`) and the venue presets it names ·
+**Reported on:** the first line of the paper's `PIPELINE-STATUS.md`
+
+## What it catches
+
+The paper's `cycles` — its attempts at venues, one entry each, oldest first — do not describe one
+consistent history:
+
+- **one source's deadlines are out of order.** The order a venue's deadlines keep is
+
+  ```text
+  registration ≤ submission ≤ resubmission < notification < camera-ready
+  ```
+
+  and it is checked within each source: the portal's readings among themselves, the call's among
+  themselves, the overrides among themselves. A call's abstract day after its own paper day is a
+  date typed wrong or an AoE day miscounted.
+
+- **a portal reading the venue's preset already carries.** A cycle whose venue is a preset derives
+  the portal's readings from it (`presets/msr.jsonc` carries MSR's); the same reading typed into the
+  paper is a second copy, and it goes stale the day paperlint updates the preset.
+
+The structural problems of the record — a bare date where an instant is needed, two open cycles, an
+open cycle that is not the last, two cycles with one id, one deadline in two entries, two readings
+from one source, an override without its reason or evidence, an unknown key anywhere in the record
+— are refused earlier, by `paperlint lint` itself before any rule runs, with one line naming the
+file, the place and the problem, and exit code 2, the same way an unknown key in `paperlint.json` is
+refused. This rule judges what the record parses with.
+
+## Why
+
+A deadline is the one fact in the record whose error costs the attempt. The record keeps what each
+page said — the portal, which refuses the upload, and the call, which only announces — with where and
+when it was read, and the **earlier** reading binds unless a human override says otherwise. That the
+portal and the call disagree is expected and is not a finding: at MSR 2027 the portal's "submissions
+must be completed by" falls at 04:00 UTC on the call's _abstract_ day, four days before the call's
+_paper_ day, and keeping both is how the earlier one is seen. What is a finding is a source that
+contradicts itself, and a fact recorded in two places.
+
+## Examples
+
+Failing — `paperlint.json`, the call's own dates inverted:
+
+```json
+{
+  "cycles": [
+    {
+      "id": "conf-2027",
+      "venue": { "kind": "preset", "extends": "paperlint:acm-sigconf" },
+      "opened": "2026-09-09",
+      "deadlines": [
+        {
+          "what": "registration",
+          "observed": [
+            {
+              "at": "2026-10-25 AoE",
+              "source": "call",
+              "url": "https://conf.example/cfp",
+              "read": "2026-09-09"
+            }
+          ]
+        },
+        {
+          "what": "submission",
+          "observed": [
+            {
+              "at": "2026-10-23 AoE",
+              "source": "call",
+              "url": "https://conf.example/cfp",
+              "read": "2026-09-09"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+```text
+papers/my-paper/PIPELINE-STATUS.md
+  1:1  error  paperlint.json, cycle «conf-2027»: the call's "registration" (2026-10-26T11:59:59Z) is
+              after its "submission" (2026-10-24T11:59:59Z) — a date typed wrong, or an AoE day
+              miscounted (write a call's date as "YYYY-MM-DD AoE" and paperlint converts it)
+              cycle/record
+```
+
+Failing — a cycle at `paperlint:msr` that copies the portal's reading the preset carries:
+
+```text
+  1:1  error  paperlint.json, cycle «msr-2027»: the "submission" deadline records a portal reading,
+              and the preset paperlint:msr carries the portal's reading of it (2026-10-20T04:00:00Z,
+              read 2026-10-05) — a second copy drifts when paperlint updates the preset: delete this
+              one (the call's reading and an override stay)  cycle/record
+```
+
+Passing:
+
+- the first record with the registration on `2026-10-20 AoE`;
+- a cycle at `paperlint:msr` recording the call's abstract day as `registration` (`2026-10-20 AoE`)
+  and its paper day as `submission` (`2026-10-23 AoE`): the preset's portal `submission`
+  (`2026-10-20T04:00:00Z`) is earlier than both, binds, and is not a contradiction;
+- a cycle with no `deadlines` at all;
+- a paper whose `paperlint.json` has no `cycles` (the flat form, `"extends": "paperlint:…"`).
+
+## Options / preset fields
+
+No rule options. One deadline entry:
+
+```jsonc
+{
+  "what": "submission", // registration (the call's abstract) · submission (the full paper) · resubmission · notification · camera-ready
+  "observed": [
+    {
+      "at": "2026-10-23 AoE", // or an instant with its zone: 2026-10-20T04:00:00Z
+      "source": "call", // or "portal"
+      "url": "https://conf.example/cfp",
+      "read": "2026-10-05", // the day the page was read
+    },
+  ],
+  // optional; wins over every reading
+  "override": {
+    "at": "2026-10-27T04:00:00Z",
+    "reason": "the chairs extended the deadline by mail",
+    "evidence": "mail/extension.eml",
+  },
+}
+```
+
+The preset field is `deadlines` in a venue preset: a list of readings `{ "what", "at", "source",
+"url", "read" }`, `at` in UTC. Shipped presets carry their portal's readings and are refreshed by a
+scheduled workflow in paperlint's repository; your own preset may carry readings the same way.
+
+## What it does not check
+
+- Whether a reading is still what the page says. The rule has no network and no clock; a shipped
+  preset's readings are re-read daily in paperlint's repository and reach you as a patch release.
+  A venue without a preset (`"kind": "named"`) is re-read by you.
+- Whether a deadline has passed, or how long is left.
+- A disagreement between sources — that is what the record holds; the earlier reading binds.
+- Whether an override's evidence exists — that is [`cycle/evidence`](evidence.md).
+- Whether the scorecard's stages name these cycles — that is [`cycle/stage`](stage.md).
+
+## How to fix
+
+Correct the date. For a deadline read from a call for papers, write it as the call prints it,
+`"YYYY-MM-DD AoE"`, and let paperlint do the arithmetic; for one read from a portal, write the instant
+the portal shows with its zone. Delete a portal reading the venue's preset already carries. A
+deadline the chairs moved by mail is an `override`, with the mail saved in the paper folder as its
+`evidence`.

package/docs/rules/cycle/stage.md

@@ -0,0 +1,85 @@
+# cycle/stage
+
+**Level:** error · **Reads:** the paper's `PIPELINE-STATUS.md` frontmatter (`stages`) and its
+`paperlint.json` (`cycles`) · **Reported on:** the frontmatter of `PIPELINE-STATUS.md`
+
+## What it catches
+
+With `cycles` declared in the paper's `paperlint.json`, a `stages` entry in the scorecard's
+frontmatter must say which attempt it belongs to, `cycle: <id>`, and that attempt must exist. Three
+things can be wrong:
+
+- a stage names no `cycle`;
+- a stage names a `cycle` no declared cycle has as its `id`;
+- a `submitted` or `camera-ready` stage belongs to a cycle whose `phase` is still `porting` — a PDF
+  was sent to the venue while the record says the source is still in the previous venue's template.
+
+Without `cycles` (the flat form) the rule is silent and `venue:` stays what it was.
+
+## Why
+
+A paper's attempts are recorded once, in `paperlint.json`; the scorecard's stages are the evidence
+— which PDF, how many bytes, when. A stage that names its cycle says which attempt the evidence
+belongs to, and the venue's name is then spelled once, in the preset, instead of as a free string
+retyped per stage (`REALM @ EMNLP 2026`, `AISec 2026 @ ACM CCS`, …). A stage whose cycle does not
+exist is evidence of nothing.
+
+The `porting` case is the other half of a declaration: `"phase": "porting"` silences the venue's
+format rules because the source is, by declaration, not yet in the venue's template. A PDF sent
+from such a cycle contradicts that declaration — either the port is done and the phase is stale, or
+the stage is wrong.
+
+## Examples
+
+Failing — `paperlint.json` declares one cycle, `open-2027`, and `PIPELINE-STATUS.md` has
+
+```yaml
+---
+stages:
+  - stage: submitted
+    date: 2026-07-22
+    pdf: versions/a.pdf
+    bytes: 1
+---
+```
+
+```text
+papers/my-paper/PIPELINE-STATUS.md
+  1:1  error  the «submitted» stage (2026-07-22) names no `cycle` — this paper declares `cycles` in
+              paperlint.json, so each stage says which attempt it belongs to: `cycle: <id>`, one of
+              open-2027  cycle/stage
+```
+
+Passing:
+
+```yaml
+---
+stages:
+  - stage: submitted
+    cycle: open-2027
+    date: 2026-07-22
+    pdf: versions/a.pdf
+    bytes: 1
+---
+```
+
+Also passing: a paper without `cycles`, whatever its stages say.
+
+## Options / preset fields
+
+No rule options.
+
+## What it does not check
+
+- The PDF, its bytes, or the frozen source — [`paper/stages`](../../rules.md) and `paper/source`
+  do.
+- Whether a stage's `date` falls inside its cycle (after `opened`, before the outcome's `date`).
+- Whether a cycle without any `submitted` stage was in fact submitted; that is the portal's record
+  (`paperlint submission`), not the scorecard's.
+- The rest of the cycle record — [`cycle/record`](record.md) does.
+
+## How to fix
+
+Add `cycle: <id>` to each stage, with the id of the cycle the PDF was sent in. For a stage whose
+cycle is still `porting`: if the port is done, remove `"phase": "porting"` from the cycle
+([`cycle/port-done`](port-done.md) says when); if no PDF was sent, remove the stage.