paperlint 12.0.0 → 13.0.0

package/dist/versions.js

@@ -0,0 +1,164 @@
+/**
+ * A PAPER'S FROZEN VERSIONS, read from the disk: the folder `versions/`, its lock, and the draft
+ * measured against the frozen source it left (`src/domain/versions.ts` holds the convention and every
+ * decision; this file reads and writes through the ports).
+ *
+ *   readVersions    the cycles, the lock and the files of `versions/`, as the rules and the table read them
+ *   draftDrift      paper.tex, assembled as the build read it, against the frozen source of the attempt
+ *   versionLines    the version → state table (`paperlint versions`, `paperlint submission show`)
+ *   freezePlan      before a `submission --save` sends: what it will freeze, or why it cannot
+ *   freezeSent      after the portal took it: the PDF sent and its source, written and locked
+ */
+import { join } from "node:path";
+import { callerPath } from "./caller-path.js";
+import { venueCycleOf } from "./domain/cycle.js";
+import { sha256Hex } from "./domain/sha256.js";
+import { messageOf } from "./domain/text.js";
+import { err, ok } from "./domain/result.js";
+import { driftBase, frozenKey, lineDrift, lockText, LOCK_FILE, parseLock, versionRows, versionTable, VERSIONS_DIR, } from "./domain/versions.js";
+import { readCycles } from "./cycle-rules.js";
+import { readPaper, decoded } from "./tex-paper.js";
+import { MAIN } from "./build.js";
+import { paperRecord } from "./paper-record.js";
+/** The paper's `versions/` folder. */
+export const versionsDir = (paperDir) => join(paperDir, VERSIONS_DIR);
+/** A frozen file's path, by its key. */
+export const frozenPath = (paperDir, key) => join(paperDir, VERSIONS_DIR, key);
+/** Whether a frozen file is on disk, by its key. */
+export const hasFrozen = (paperDir, files) => (key) => files.isFile(callerPath(frozenPath(paperDir, key)));
+/** A frozen file's text, by its key; null when it is not there. */
+export const frozenText = (paperDir, key, files) => decoded(files.readBytes(callerPath(frozenPath(paperDir, key))));
+/** The size and digest of a frozen file on disk, by its key: zero bytes of nothing when it is gone. */
+export const factsOfFrozen = (paperDir, files) => (key) => {
+    const b = files.readBytes(callerPath(frozenPath(paperDir, key))) ??
+        new Uint8Array();
+    return { bytes: b.length, sha256: sha256Hex(b) };
+};
+/** `versions/lock.json`: null when there is none; else parsed, or why it does not parse. */
+export function readLock(paperDir, files) {
+    const b = files.readBytes(callerPath(join(versionsDir(paperDir), LOCK_FILE)));
+    if (b === null)
+        return null;
+    try {
+        return parseLock(JSON.parse(new TextDecoder().decode(b)));
+    }
+    catch (e) {
+        return err(`not JSON: ${messageOf(e)}`);
+    }
+}
+/** The entries of a folder, each a file or a folder, by name. */
+export const entriesIn = (dir, deps) => [...deps.listDir(callerPath(dir))].sort().map((name) => ({
+    name,
+    kind: deps.files.isFile(callerPath(join(dir, name))) ? "file" : "dir",
+}));
+/** The paper's cycles, when it keeps them and they read; null for the flat form or a broken record. */
+export function cyclesIn(paperDir, files) {
+    const r = readCycles(paperDir, { files });
+    return r.ok ? r.value : null;
+}
+/** paper.tex, assembled as the last build read it (its includes spliced in); null without one. */
+export function draftText(paperDir, deps) {
+    const main = join(paperDir, MAIN);
+    const src = decoded(deps.files.readBytes(callerPath(main)));
+    return src === null ? null : readPaper(main, src, deps).text;
+}
+/** The draft against the frozen source of the paper's attempt: none, nothing frozen, the same, or drifted. */
+export function draftDrift(paperDir, cycles, draft, files) {
+    const base = driftBase(cycles.current, hasFrozen(paperDir, files));
+    if (base === null)
+        return { kind: "none" };
+    const frozen = frozenText(paperDir, base.key, files);
+    if (frozen === null)
+        return { kind: "no-base", key: base.key };
+    const drift = lineDrift(frozen, draft);
+    return drift.added === 0 && drift.removed === 0
+        ? { kind: "same", key: base.key }
+        : { kind: "drift", key: base.key, drift };
+}
+/**
+ * The version → state table of the paper in `paperDir`: each attempt's frozen files and what they
+ * are, then the draft. Or why there is none: the paper keeps no `cycles`.
+ */
+export function versionLines(paperDir, deps) {
+    const cycles = cyclesIn(paperDir, deps.files);
+    if (cycles === null)
+        return err('the paper keeps no "cycles" in paperlint.json (or they do not read — `paperlint lint` says why): versions are kept per attempt, versions/<cycle>/<stage>.pdf');
+    const lock = readLock(paperDir, deps.files);
+    const draft = draftText(paperDir, deps);
+    return ok(versionTable(versionRows({
+        cycles: cycles.list,
+        has: hasFrozen(paperDir, deps.files),
+        lock: lock?.ok === true ? lock.value : {},
+        draft: draft === null
+            ? { kind: "none" }
+            : draftDrift(paperDir, cycles, draft, deps.files),
+    })));
+}
+const refusal = (why, cycle) => `refused: ${why}, and the two could not be frozen together in versions/${cycle}/ — rebuild (\`paperlint build\`), run the dry run again, then --save; nothing was sent`;
+/** Why the source on disk cannot be frozen as the PDF's; null when the build's record says it can. */
+function sourceProblem(paperDir, deps) {
+    const record = paperRecord(paperDir, deps);
+    if (record.kind === "none")
+        return err("no record of the build (_build/sources.json), so which source the PDF was built from is not known");
+    if (record.kind === "stale")
+        return err(`${record.changed.map((x) => x.path).join(", ")} changed since the build, so the PDF is not what the source builds now`);
+    const source = draftText(paperDir, deps);
+    return source === null
+        ? err(`no ${MAIN} to freeze beside the PDF`)
+        : ok(source);
+}
+/**
+ * Before a `--save` sends: what it will freeze — the open cycle's `submitted`, or the accepted one's
+ * `camera-ready` — and the source to freeze beside the PDF. Refused when the build's record does not
+ * say the source on disk is the one the PDF was built from: a PDF frozen with another source is a
+ * pair that lies.
+ */
+export function freezePlan(paperDir, cycles, deps) {
+    const c = cycles === null ? null : venueCycleOf(cycles.current);
+    if (cycles === null || c === null)
+        return ok({ kind: "flat" });
+    const source = sourceProblem(paperDir, deps);
+    return source.ok
+        ? ok({
+            kind: "freeze",
+            cycle: c.id,
+            stage: cycles.current.kind === "accepted" ? "camera-ready" : "submitted",
+            source: source.value,
+        })
+        : err(refusal(source.error, c.id));
+}
+const lockEntry = (bytes, frozen) => ({
+    kind: "file",
+    bytes: bytes.length,
+    sha256: sha256Hex(bytes),
+    frozen,
+});
+/** The lock with the two frozen files recorded, written; or why the lock on disk does not read. */
+function lockSent(s, entries, deps) {
+    const lock = readLock(s.paperDir, deps.files) ?? ok({});
+    if (!lock.ok)
+        return lock;
+    deps.files.writeAtomic(callerPath(join(versionsDir(s.paperDir), LOCK_FILE)), new TextEncoder().encode(lockText({ ...lock.value, ...entries })));
+    return ok(null);
+}
+/**
+ * After the portal took the PDF: the PDF and its source written to `versions/<cycle>/<stage>.*`,
+ * replacing an earlier upload's, and recorded in the lock. The line to print; an error line when the
+ * lock does not read (the files are frozen, the lock left as it is).
+ */
+export function freezeSent(s, deps) {
+    const { cycle, stage } = s.plan;
+    const source = new TextEncoder().encode(s.plan.source);
+    const pdfKey = frozenKey(cycle, stage, "pdf");
+    const texKey = frozenKey(cycle, stage, "tex");
+    deps.files.writeAtomic(callerPath(frozenPath(s.paperDir, pdfKey)), s.pdf);
+    deps.files.writeAtomic(callerPath(frozenPath(s.paperDir, texKey)), source);
+    const frozen = deps.now();
+    const locked = lockSent(s, { [pdfKey]: lockEntry(s.pdf, frozen), [texKey]: lockEntry(source, frozen) }, deps);
+    return locked.ok
+        ? ok(`frozen        versions/${pdfKey} (${String(s.pdf.length)} bytes) and ${stage}.tex (${String(source.length)} bytes), recorded in versions/lock.json`)
+        : err(`versions/lock.json does not read (${locked.error}): versions/${pdfKey} and ${stage}.tex are frozen, not recorded — \`npx paperlint versions lock ${s.shownPaper}\` records them`);
+}
+/** What a send in the flat form says instead of a freeze. */
+export const NOT_FROZEN = 'not frozen    the paper keeps no "cycles" in paperlint.json: versions are frozen per attempt, in versions/<cycle>/ (docs/configuration.md, "The paper\'s cycles")';
+//# sourceMappingURL=versions.js.map

package/dist/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":"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"}

package/docs/configuration.md

@@ -164,7 +164,7 @@ is refused as a second source for one fact.
   "pdf": "build/paper.pdf",
   "cycles": [
     {
-      "id": "alpha-2026", // what a stage's `cycle:` names
+      "id": "alpha-2026", // the name of its folder in versions/
       "venue": { "kind": "preset", "extends": "paperlint:acm-sigconf" },
       "kind": "short",
       "opened": "2026-07-01", // the day this attempt was decided
@@ -225,7 +225,7 @@ is refused as a second source for one fact.
 
 | field        | what it is                                                                                                                                                                                                                                                                                                                       |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`         | unique in the list; a scorecard stage names it as `cycle: <id>` ([`cycle/stage`](rules/cycle/stage.md))                                                                                                                                                                                                                          |
+| `id`         | unique in the list; the name of the attempt's folder in `versions/` ([`versions/layout`](rules/versions/layout.md)), so one folder name: lowercase letters, digits and hyphens, starting with a letter or a digit (`msr-2027`). Anything else (`conf/2026`, `..`, `Conf-2026`) is refused when the record is read                |
 | `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                                                                                                                                                                                                                     |
@@ -242,6 +242,80 @@ camera-ready and talk are judged against it, and the venue's blindness no longer
 
 Papers without `cycles` read exactly as before.
 
+### The frozen versions: one folder per attempt
+
+A paper that keeps `cycles` freezes each version it sends in `versions/<cycle id>/`, one file per
+stage. No date is typed into a name: when a file was frozen is in `versions/lock.json`, which
+paperlint writes.
+
+```text
+versions/
+├── alpha-2026/                ← rejected: historical
+│   ├── submitted.pdf
+│   └── submitted.tex
+├── beta-2027/                 ← open: CURRENT, under review
+│   ├── submitted.pdf
+│   └── submitted.tex
+└── lock.json                  ← generated: bytes, sha256 and when each file was frozen
+```
+
+Each version's state follows from its cycle's `outcome`, never typed: a `submitted` version of the
+open cycle is under review; anything in a rejected or withdrawn cycle's folder is historical; an
+accepted cycle's `submitted` is the camera-ready's base, and its `camera-ready` is final. When a
+decision arrives you change one value, the cycle's `outcome`, and every state follows.
+`npx paperlint versions` prints the table, and `paperlint submission show` prints it after the
+portal's copy:
+
+```text
+  beta-2027   submitted  CURRENT (under review at paperlint:ieee-conference)  186504 B  frozen 2026-10-23 16:58 UTC
+  alpha-2026  submitted  historical (rejected)                                305412 B  frozen 2026-07-22
+  paper.tex   draft      target not chosen                                    differs from beta-2027/submitted.tex: 18 lines added, 18 removed
+```
+
+`paperlint submission new --save` and `submission update --save` freeze what they send: the exact
+PDF, and the source the build read — a paper split into `sections/` is frozen whole, its includes
+spliced in — as `versions/<cycle>/submitted.{pdf,tex}`, or `camera-ready.{pdf,tex}` once the cycle is
+accepted, and record both in the lock. A later save in the same cycle replaces them: the last upload
+is the one under review. A save whose sources changed since the build is refused before anything is
+sent, because the PDF and the source on disk would no longer be a pair. A file you put there yourself
+(an arXiv copy, an upload made on the portal by hand) is recorded with `npx paperlint versions lock`.
+
+**Between venues.** Freeze at the send — `--save` does it. Keep editing `paper.tex`: it is always the
+draft, the only file you edit, and [`cycle/draft-drift`](rules/cycle/draft-drift.md) says how far it
+has moved from what the reviewers read, so a reply to them quotes the frozen file. Open the next
+cycle only once the current one has an outcome (one open cycle at most). If the venue accepts, the
+camera-ready starts from the frozen `submitted.tex`, not from the drifted draft; once the camera-ready
+is sent and frozen, [`cycle/camera-ready-source`](rules/cycle/camera-ready-source.md) checks that it
+kept at least half of the accepted source's lines. A cycle that has a submission and nothing frozen is
+[`cycle/submitted-frozen`](rules/cycle/submitted-frozen.md).
+
+**From the `stages:` list.** A paper that recorded its frozen versions as a `stages:` list in
+`PIPELINE-STATUS.md`, with dated files in `versions/`, moves to the folders with one command:
+
+```console
+$ npx paperlint versions migrate papers/my-paper
+moved         versions/2026-07-22-submitted.pdf → versions/alpha-2026/submitted.pdf
+moved         versions/2026-07-22-submitted.tex → versions/alpha-2026/submitted.tex
+recorded      versions/lock.json, 2 entries
+removed       the stages: list from PIPELINE-STATUS.md — the folders and the lock are the record now
+```
+
+Each entry's `cycle:` names its folder, its `bytes:` and `sourceBytes:` are checked against the
+files once more, its `date:` becomes the day the lock records, and `sourceLost: true` becomes a lock
+entry that records the loss. An entry without a `cycle:`, a file that is no longer the one declared,
+or a dated file no entry names stops the whole migration before anything moves, with what to do;
+so does a destination that is already there, such as a version `submission update --save` froze
+while the list was still in place. A source two stages were built from (a `submitted` and an `arxiv`
+sharing one `.tex`) is copied to each. Paths in the list are read in one spelling (`./versions/a.tex` is `versions/a.tex`), and one
+outside the paper folder (`../a.tex`) is refused. Before anything moves, the whole plan is replayed on
+the paths it touches: a plan that could stop half-way is refused with nothing moved.
+Any other loose file at the top of `versions/` (a withdrawn `STALE` copy, a note on the old
+convention) moves to `extra/versions/`, since [`versions/layout`](rules/versions/layout.md) allows
+nothing there beside `lock.json`. The YAML comments inside the list leave with it: read them first,
+since a provenance note kept there (which commit a source came from, whether a PDF is the portal's
+bytes or a rebuild) belongs in the cycle's evidence or the scorecard's prose. A paper without
+`cycles` keeps its `stages:` list: `paper/stages` and `paper/source` still read it.
+
 ### Deadlines
 
 A deadline records **what each page said**, and optionally **a human decision that overrides it**:

package/docs/layout.md

@@ -27,8 +27,8 @@ flowchart TB
   end
   S4["<b>4 · draft</b><br/>draft-paper · argument-arc · tighten-paper<br/>writes: paper.tex, sections/, figures/<br/>checked by: the tex/* rules<br/>hook paper-edit-guard: no shell writes"]
   S5["<b>5 · review</b><br/>grade-paper-writing · verify-citations<br/>pc-panel-review · harden-paper<br/>study-accepted-papers, mode C or D<br/>writes: reviews/, the scorecard<br/>in PIPELINE-STATUS.md<br/>checked by: review/frontmatter"]
-  S6["<b>6 · submit</b><br/>paperlint build · submit-paper<br/>writes: paper.pdf, _build/,<br/>versions/, submission/<br/>checked by: format/page-limit, pdf/*,<br/>anonymity/identity, paper/stages"]
-  S7["<b>7 · camera-ready</b><br/>camera-ready<br/>writes: versions/, talk/<br/>checked by: paper/stages, talk/*"]
+  S6["<b>6 · submit</b><br/>paperlint build · submit-paper<br/>writes: paper.pdf, _build/,<br/>versions/, submission/<br/>checked by: format/page-limit, pdf/*,<br/>anonymity/identity, versions/layout"]
+  S7["<b>7 · camera-ready</b><br/>camera-ready<br/>writes: versions/, talk/<br/>checked by: versions/layout, talk/*"]
   S8["<b>8 · extend</b><br/>extend-paper<br/>writes: a new paper folder"]
   N --> S1 --> S2 --> D
   Y --> S4 --> S5 --> S6 --> S7 --> S8
@@ -64,7 +64,7 @@ creates one.
     ├── paper.pdf                      ← the built PDF
     ├── *.tex *.bib *.cls *.sty *.bst  ← what TeX and bibtex look up beside paper.tex
     ├── _build/                        ← the facts `paperlint build` writes
-    ├── versions/                      ← each stage's frozen PDF and source
+    ├── versions/                      ← each stage's frozen PDF and source — per attempt, versions/<cycle>/, with lock.json
     ├── reviews/                       ← dated reviews and pass reports
     ├── siblings/                      ← the cards of competing papers
     ├── research/                      ← dated research and decision records
@@ -102,7 +102,7 @@ Both are explained in [`venues.md`](venues.md).
 | ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `<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))                                                                                |
+| `PIPELINE-STATUS.md`                 | every stage      | `paperlint new`, then `paper-pipeline`, `paper-status`; `study-accepted-papers` (the scorecard)                                                                                                  | `paper/stages`, `paper/source`, [`cycle/submitted-frozen`](rules/cycle/submitted-frozen.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))                                                                |
@@ -119,7 +119,7 @@ Both are explained in [`venues.md`](venues.md).
 | `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`                                                                                                                                           |
+| `versions/`                          | 6, then 7        | you, at submission and at camera-ready (`submit-paper` says how): the frozen PDF and source of each stage                                                                                        | [`versions/layout`](rules/versions/layout.md) with `cycles`; `paper/stages`, `paper/source` without                                                                      |
 | `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                                                                                                                                                            |

package/docs/rules/cycle/camera-ready-source.md

@@ -0,0 +1,62 @@
+# cycle/camera-ready-source
+
+**Level:** error · **Reads:** `paperlint.json` (`cycles`), `versions/<accepted cycle>/submitted.tex` and
+`camera-ready.tex` · **Reported on:** the first line of `paper.tex`
+
+## What it catches
+
+The last cycle is `accepted`, its camera-ready is frozen (`versions/<cycle>/camera-ready.tex`, written
+by `npx paperlint submission update <paper> --save`), and that frozen source keeps less than half of the
+lines of what was accepted, the cycle's frozen `submitted.tex`. The message names both files and the
+count.
+
+Until the camera-ready is frozen the rule is silent: while it is being edited, `paper.tex` differs from
+what was accepted by design, since the reviewers' changes go in.
+
+## Why
+
+The camera-ready is what the venue accepted plus the changes its reviewers asked for. Between the upload
+and the decision `paper.tex` usually moved on (see [`cycle/draft-drift`](draft-drift.md)). Built from
+that drifted draft, the camera-ready would send the venue a paper its reviewers never read.
+
+A camera-ready differs from what was accepted, so any difference cannot be the test. The rule counts
+the accepted source's lines the camera-ready keeps unchanged, with the same line diff as
+`cycle/draft-drift`: one that keeps at least half started from the accepted source; one that keeps less
+was built from something else.
+
+## Examples
+
+Failing: cycle `open-2027` is accepted, and its frozen camera-ready was built from a draft that moved
+on:
+
+```text
+papers/my-paper/paper.tex
+  1:1  error  cycle «open-2027» is accepted, and its frozen camera-ready,
+              `versions/open-2027/camera-ready.tex`, keeps 3 of the 13 lines of what was accepted,
+              `versions/open-2027/submitted.tex` — under half, so it was not built from the accepted
+              source. …  cycle/camera-ready-source
+```
+
+Passing:
+
+- an accepted cycle whose camera-ready is not frozen yet, however far `paper.tex` has moved;
+- a frozen camera-ready that is the accepted source plus the requested changes.
+
+## Options / preset fields
+
+No rule options.
+
+## What it does not check
+
+- Whether the changes are the ones the reviewers asked for. Half of the lines kept says the
+  camera-ready started from the accepted source, not that every change in it was requested.
+- `paper.tex` after the camera-ready is frozen. What the venue holds is fixed; the draft is free to head
+  for the next paper.
+- A camera-ready PDF frozen without its source: there is nothing to compare, and
+  [`versions/layout`](../versions/layout.md) names the missing source.
+
+## How to fix
+
+Copy `versions/<cycle>/submitted.tex` over `paper.tex`, make the changes the reviewers asked for, build,
+and send again with `npx paperlint submission update <paper> --save`. That replaces the frozen
+`camera-ready.{pdf,tex}`.

package/docs/rules/cycle/draft-drift.md

@@ -0,0 +1,47 @@
+# cycle/draft-drift
+
+**Level:** warn · **Reads:** `paper.tex` (with the files the last build spliced in), `paperlint.json`
+(`cycles`), `versions/<open cycle>/submitted.tex` · **Reported on:** the first line of `paper.tex`
+
+## What it catches
+
+The last cycle is open, its `submitted.tex` is frozen, and `paper.tex` differs from it. The message
+says by how much: the lines added and removed, as a line diff counts them.
+
+## Why
+
+`paper.tex` is always the draft; the frozen `submitted.tex` is what the venue's reviewers read. Between
+the upload and the decision the draft keeps moving — towards the next venue, or answering what the
+reviewers are likely to ask — and that is expected. What is not expected is to forget it: a reply to a
+reviewer that quotes line numbers, or a rebuttal that quotes a sentence, has to quote the frozen file.
+The warning keeps the distance visible. ESLint has no info level, so it is a warning: it prints and
+does not fail the run.
+
+## Examples
+
+Reported — the open cycle `open-2027` froze `submitted.tex`, and `paper.tex` changed since:
+
+```text
+papers/my-paper/paper.tex
+  1:1  warning  paper.tex has moved on from `versions/open-2027/submitted.tex`, the version under
+                review at paperlint:acm-sigconf: 18 lines added, 18 removed — expected while the draft
+                heads for its next venue; …  cycle/draft-drift
+```
+
+Silent: `paper.tex` as frozen; no open cycle; or no frozen `submitted.tex` yet.
+
+## Options / preset fields
+
+No rule options. A paper that does not want the reminder turns it off in its `paperlint.json`:
+`"rules": { "cycle/draft-drift": "off" }`.
+
+## What it does not check
+
+- Which of the changes matter: a changed number and a reflowed paragraph count the same.
+- A paper split into several files is compared as the last build assembled it; when the build's record
+  is out of date (`paper/sources-fresh` says so), only `paper.tex` itself is compared.
+
+## How to fix
+
+Nothing to fix while the draft heads elsewhere. To answer the reviewers of the open cycle, quote
+`versions/<cycle>/submitted.tex`.

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

@@ -65,8 +65,8 @@ reads, and compares the way that rule does.
   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.
+- A `porting` cycle that has already sent a PDF — [`versions/layout`](../versions/layout.md) reports
+  a `submitted` or `camera-ready` PDF frozen in its folder.
 
 ## How to fix
 

package/docs/rules/cycle/record.md

@@ -144,7 +144,8 @@ scheduled workflow in paperlint's repository; your own preset may carry readings
 - 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).
+- Whether `versions/` holds a folder per cycle and nothing else — that is
+  [`versions/layout`](../versions/layout.md).
 
 ## How to fix
 

package/docs/rules/cycle/submitted-frozen.md

@@ -0,0 +1,65 @@
+# cycle/submitted-frozen
+
+**Level:** error · **Reads:** the paper's `paperlint.json` (`cycles`) and its `versions/` folder ·
+**Reported on:** the first line of `PIPELINE-STATUS.md`
+
+## What it catches
+
+A cycle with `"submission": { "id": … }` — a PDF went to the venue's portal — and no
+`versions/<cycle>/submitted.pdf`.
+
+## Why
+
+What the reviewers read is the one version an author has to be able to show again: a reviewer's
+page and line numbers point into it, and a camera-ready starts from its source. Before this rule a
+paper could record a submission on an open cycle, keep no frozen copy, and `paperlint lint` said
+nothing; the only record of the text under review was a branch commit, which squash merges and
+`git gc` destroy.
+
+Since this rule, `paperlint submission new --save` and `submission update --save` freeze the exact
+PDF they send, with the source it was built from, so the rule fires only for an upload made another
+way (by hand on the portal, or before paperlint froze on send).
+
+## Examples
+
+Failing — `paperlint.json` has
+
+```json
+{
+  "cycles": [
+    {
+      "id": "open-2027",
+      "venue": { "kind": "preset", "extends": "paperlint:acm-sigconf" },
+      "opened": "2026-09-09",
+      "submission": { "id": 7 }
+    }
+  ]
+}
+```
+
+and `versions/open-2027/` is empty:
+
+```text
+papers/my-paper/PIPELINE-STATUS.md
+  1:1  error  cycle «open-2027» has submission 7 on the portal, and `versions/open-2027/submitted.pdf`
+              is not there: what the reviewers read is not frozen. …  cycle/submitted-frozen
+```
+
+Passing: the same cycle with `versions/open-2027/submitted.pdf` on disk; or a cycle with no
+`submission` yet (still preparing).
+
+## Options / preset fields
+
+No rule options.
+
+## What it does not check
+
+- The source beside the PDF, the lock, the folder's names — [`versions/layout`](../versions/layout.md) does.
+- That the frozen PDF is the one the portal holds: `paperlint submission show` compares sha256s.
+
+## How to fix
+
+Send with `npx paperlint submission update <paper> --save`: it freezes what it sends. For an upload
+made before, put the PDF the portal holds at `versions/<cycle>/submitted.pdf` (`submission show`
+prints its size and sha256 to check against), the source it was built from as `submitted.tex`, and
+run `npx paperlint versions lock <paper>`.

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

@@ -29,7 +29,7 @@ it: [the map](../../layout.md).
 ├── paper.pdf                      ← the built PDF
 ├── *.tex *.bib *.cls *.sty *.bst  ← what TeX and bibtex look up beside paper.tex
 ├── _build/                        ← the facts `paperlint build` writes
-├── versions/                      ← each stage's frozen PDF and source
+├── versions/                      ← each stage's frozen PDF and source — per attempt, versions/<cycle>/, with lock.json
 ├── reviews/                       ← dated reviews and pass reports
 ├── siblings/                      ← the cards of competing papers
 ├── research/                      ← dated research and decision records

package/docs/rules/versions/layout.md

@@ -0,0 +1,88 @@
+# versions/layout
+
+**Level:** error · **Reads:** the paper's `versions/` folder, `versions/lock.json` and `paperlint.json`
+(`cycles`) · **Reported on:** the first line of `PIPELINE-STATUS.md`
+
+## What it catches
+
+A paper that keeps `cycles` freezes each version it sends in one folder per attempt:
+
+```text
+versions/
+├── alpha-2026/          ← a cycle id in paperlint.json
+│   ├── submitted.pdf
+│   └── submitted.tex
+├── beta-2027/
+│   ├── submitted.pdf
+│   ├── submitted.tex
+│   └── camera-ready.pdf ← only after the attempt is accepted
+└── lock.json            ← written by paperlint: bytes, sha256, when each file was frozen
+```
+
+The rule reports:
+
+- an entry of `versions/` that is neither `lock.json` nor a folder: a dated file from the layout
+  before folders per attempt (`2026-07-22-submitted.pdf`) is named with the command that moves it;
+- a folder that names no cycle in `paperlint.json`;
+- a file in a cycle's folder that is not `<stage>.pdf` or `<stage>.tex`, the stage one of
+  `submitted`, `camera-ready`, `arxiv`;
+- a frozen PDF without its source beside it, unless the lock records the source as lost;
+- a `submitted` or `camera-ready` PDF in a cycle whose `phase` is still `porting`;
+- frozen files and no lock, a lock that does not read, a frozen file the lock does not record, a file
+  whose bytes or digest are not the ones the lock recorded, and a lock entry whose file is gone.
+
+Names and folders starting with `.` (`.gitkeep`) are not judged. A paper without `cycles` is not
+judged either: its `stages:` list in `PIPELINE-STATUS.md` is still its record, checked by
+`paper/stages` and `paper/source`.
+
+## Why
+
+The folder and the file name are the record: which attempt a file belongs to, and at which stage it
+was frozen. What state it is in follows from the attempt's `outcome` in `paperlint.json` — under
+review while the cycle is open, historical once it is rejected or withdrawn, the camera-ready's base
+once accepted. A name outside the convention is a version whose state nobody can read off.
+
+A frozen file is never supposed to change. The lock records its bytes and digest when paperlint froze
+it, so a file that was replaced afterwards — the PDF a reviewer's page numbers point into, the source
+their line numbers point into — is caught instead of trusted. The lock is generated, never typed:
+`paperlint submission new|update --save` writes it when it freezes what it sent, and
+`paperlint versions lock` records a file put there by hand.
+
+## Examples
+
+Failing — `paperlint.json` declares the cycle `open-2027`, and `versions/` still holds a file of the
+old layout:
+
+```text
+papers/my-paper/PIPELINE-STATUS.md
+  1:1  error  `versions/2026-07-22-submitted.pdf` is not part of the layout — a frozen version in the
+              layout before folders per attempt: `npx paperlint versions migrate <paper>` moves it
+              into versions/<cycle>/  versions/layout
+```
+
+Passing: `versions/open-2027/submitted.pdf` and `submitted.tex`, both recorded in `versions/lock.json`
+as they stand.
+
+## Options / preset fields
+
+No rule options.
+
+## What it does not check
+
+- That a cycle with a submission froze anything at all — [`cycle/submitted-frozen`](../cycle/submitted-frozen.md) does.
+- That the frozen source builds the frozen PDF: the lock records what was frozen together, and
+  `submission --save` freezes the source only when the build's record says it is the one the PDF was
+  built from.
+- A lost source: the lock records it (`"sourceLost": true`) and `paperlint versions` shows it; there is
+  nothing left to fix, so it is not reported.
+
+## How to fix
+
+- A dated file: `npx paperlint versions migrate <paper>` moves every one named in `stages:` into its
+  cycle's folder, writes the lock and drops the list.
+- A folder or file outside the convention: rename it to the cycle id or the stage, or move it to
+  `extra/`.
+- A file put there by hand, or one replaced on purpose: `npx paperlint versions lock <paper>`.
+- A file replaced by accident, or deleted: restore it from git.
+- A PDF sent from a cycle still `porting`: the port is done — drop the phase
+  ([`cycle/port-done`](../cycle/port-done.md) says when).