paperlint 12.1.0 → 13.0.0

package/docs/rules.md

@@ -5,13 +5,16 @@ reads and when it fails. Errors fail `paperlint lint`; warnings print and do not
 
 | Rule                                                                      | Level                                                    | Reads                                                                                                  | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | ------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `paper/stages`                                                            | error                                                    | `PIPELINE-STATUS.md`                                                                                   | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `paper/source`                                                            | error                                                    | `PIPELINE-STATUS.md`                                                                                   | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `paper/stages`                                                            | error                                                    | `PIPELINE-STATUS.md`                                                                                   | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares. In a paper that keeps `cycles`, the `stages:` list is retired: one finding names `paperlint versions migrate`, and [`versions/layout`](rules/versions/layout.md) judges `versions/`                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `paper/source`                                                            | error                                                    | `PIPELINE-STATUS.md`                                                                                   | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it). Silent in a paper that keeps `cycles`: there [`versions/layout`](rules/versions/layout.md) holds each PDF to its source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | [`study/declare-sample`](rules/study/declare-sample.md)                   | experimental; off unless a paper turns it on (`"error"`) | each study's `repro/<study>/prereg.json`                                                               | a study's pre-registration does not declare its `population` (what the claim is about, source, size), the `strata` and what each of its `screens` removed per stratum value, its `coverage` (share 0–1 or null with a reason, and the strata it cannot reach), or the `author_check` of the drawn units (a doubtful verdict needs a recorded `decision`); reported on `PIPELINE-STATUS.md`, once per problem — [page](rules/study/declare-sample.md)                                                                                                                                                                                                                                                                                              |
 | [`cycle/record`](rules/cycle/record.md)                                   | error                                                    | `paperlint.json` (`cycles`)                                                                            | the paper's attempts at venues (`cycles`, one entry per attempt) hold one source's deadlines out of order (registration ≤ submission ≤ resubmission < notification < camera-ready), or copy a portal reading the venue's preset carries; reported on `PIPELINE-STATUS.md`. A record that does not parse — a bare date, two open cycles, an unknown key — is refused by `paperlint lint` itself before any rule runs, exit 2 — [page](rules/cycle/record.md)                                                                                                                                                                                                                                                                                       |
 | [`cycle/evidence`](rules/cycle/evidence.md)                               | error                                                    | `paperlint.json` (`cycles`) → the paper folder                                                         | a closed cycle (`accepted`, `rejected`, `withdrawn`) or a deadline's `override` names an `evidence` file — the decision mail, the reviews, the withdrawal note, the chairs' mail — that is not in the paper folder; reported on `PIPELINE-STATUS.md` — [page](rules/cycle/evidence.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| [`cycle/stage`](rules/cycle/stage.md)                                     | error                                                    | `PIPELINE-STATUS.md` → `paperlint.json` (`cycles`)                                                     | with `cycles` declared, a stage names no `cycle: <id>`, names one no cycle has, or a `submitted`/`camera-ready` stage belongs to a cycle whose `phase` is still `porting` — [page](rules/cycle/stage.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [`cycle/port-done`](rules/cycle/port-done.md)                             | error                                                    | `paper.tex` → `paperlint.json` (`cycles`) → the preset's `template`                                    | the current cycle still declares `"phase": "porting"` (which silences the venue's format rules) while the `\documentclass` is already the venue's template: the port is done, drop the phase — [page](rules/cycle/port-done.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`cycle/submitted-frozen`](rules/cycle/submitted-frozen.md)               | error                                                    | `paperlint.json` (`cycles`) → `versions/`                                                              | a cycle has `"submission": { "id" }` — a PDF went to the portal — and no `versions/<cycle>/submitted.pdf`; `submission new                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | update --save`freeze what they send, so this fires for an upload made another way; reported on`PIPELINE-STATUS.md` — [page](rules/cycle/submitted-frozen.md) |
+| [`cycle/draft-drift`](rules/cycle/draft-drift.md)                         | warn                                                     | `paper.tex` → `paperlint.json` (`cycles`) → `versions/<cycle>/submitted.tex`                           | the last cycle is open and `paper.tex` (as the last build assembled it) differs from the source frozen when its PDF was sent; says how many lines were added and removed — [page](rules/cycle/draft-drift.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`cycle/camera-ready-source`](rules/cycle/camera-ready-source.md)         | error                                                    | `paper.tex` → `paperlint.json` (`cycles`) → `versions/<cycle>/`                                        | the last cycle is accepted, its camera-ready is frozen, and the frozen `camera-ready.tex` keeps less than half of the lines of the frozen `submitted.tex`, so it was not built from what was accepted; silent until the camera-ready is frozen — [page](rules/cycle/camera-ready-source.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| [`versions/layout`](rules/versions/layout.md)                             | error                                                    | `versions/`, `versions/lock.json` → `paperlint.json` (`cycles`)                                        | with `cycles` declared: an entry of `versions/` that is not `lock.json` or a folder named by a cycle id, a file in a cycle's folder that is not `<stage>.pdf`/`.tex` (`submitted`, `camera-ready`, `arxiv`), a PDF without its source (unless the lock records it lost), a PDF sent from a cycle still `porting`, or a frozen file that does not match `versions/lock.json`; reported on `PIPELINE-STATUS.md` — [page](rules/versions/layout.md)                                                                                                                                                                                                                                                                                                  |
 | [`paper/folder-venue-leftover`](rules/paper/folder-venue-leftover.md)     | warn                                                     | the folder name → `paperlint.json`                                                                     | the paper's folder is named after another shipped venue than the one it extends (`papers/aisec-2026/` for a paper now set for AIDC); reported on `PIPELINE-STATUS.md` — [page](rules/paper/folder-venue-leftover.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | [`paper/allowed-files-only`](rules/paper/allowed-files-only.md)           | error                                                    | the paper folder's root listing → `paperlint.json`                                                     | a file or folder at the paper's root is not part of the layout (`PLAN.md`, `archive/`, a stray PDF); reported on `PIPELINE-STATUS.md`, once per entry, with where it goes; `extra/` takes anything — [page](rules/paper/allowed-files-only.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | [`repro/allowed-files-only`](rules/repro/allowed-files-only.md)           | error                                                    | the listing of the paper's `repro/`                                                                    | an entry at the top of `repro/` is not `README.md`, `studies.json`, `.gitignore`, `tools/`, `data/` or a study folder named `<id>-<slug>` (or, in a paper without the registry, `<slug>-YYYY-MM-DD`), or a study folder has no `README.md`; reported on `PIPELINE-STATUS.md`, once per entry, with where it goes by kind (a script → `repro/tools/`, data → `repro/data/`, a note → its study or `research/`) — [page](rules/repro/allowed-files-only.md)                                                                                                                                                                                                                                                                                         |
@@ -279,13 +282,24 @@ The paper body is `paper.tex`, and it gets three rules of its own: `paper/typogr
 run on it but judge the files beside it. The scorecard and the review notes are Markdown files, and
 the other five rules read those.
 
-## The scorecard's `bytes:` and `sourceBytes:`
+## Frozen versions: `versions/<cycle>/` and its lock
+
+**A paper that keeps `cycles`** freezes what it sends without a manual step:
+`paperlint submission new --save` and `submission update --save` write the exact PDF they sent and the
+source it was built from into `versions/<cycle>/submitted.{pdf,tex}` (`camera-ready.*` once the cycle
+is accepted), and record their bytes, sha256 and the time in `versions/lock.json`, a file paperlint
+writes and nobody edits. [`versions/layout`](rules/versions/layout.md) then fails if a frozen file no
+longer matches the lock, and `npx paperlint versions` prints each version's state. A file you freeze
+yourself is recorded with `npx paperlint versions lock`. The layout, the states and the move from the
+`stages:` list (`npx paperlint versions migrate`) are in
+[configuration](configuration.md#the-frozen-versions-one-folder-per-attempt).
+
+### Without `cycles`: the scorecard's `bytes:` and `sourceBytes:`
 
 **When you submit,** copy the PDF and `paper.tex` you sent into the paper's `versions/` folder and
 record the stage in the front matter of `PIPELINE-STATUS.md` (the paper's scorecard). From then on
 `paper/stages` fails if that PDF goes missing or changes size, and `paper/source` if its source was
-not kept. Today you record it by hand; a command for it is planned
-([#100](https://github.com/zernie/paperlint/issues/100)). A stage looks like this:
+not kept. A stage looks like this:
 
 ```yaml
 ---
@@ -301,8 +315,8 @@ stages:
 ```
 
 A stage name may use `a-z`, `0-9`, `.`, `_` and `-`. You write `bytes:` and `sourceBytes:` yourself
-(`wc -c < versions/2026-07-22-submitted.pdf`), or the agent does, once, when the stage is recorded;
-no command in this package generates them. They are not a checksum to maintain: a
-frozen PDF is never supposed to change, so `bytes:` disagreeing with the file means the file was
-replaced after it was declared, and that is exactly the finding. If you really did re-freeze a
-stage, update the number in the same commit.
+(`wc -c < versions/2026-07-22-submitted.pdf`), or the agent does, once, when the stage is recorded.
+They are not a checksum to maintain: a frozen PDF is never supposed to change, so `bytes:`
+disagreeing with the file means the file was replaced after it was declared, and that is exactly the
+finding. If you really did re-freeze a stage, update the number in the same commit. Recording the
+paper's attempts as `cycles` moves all of this to the folders and the generated lock.

package/docs/submission.md

@@ -88,6 +88,22 @@ against the venue's call for papers.
 The safe order: `new`, `new --save` once; then `show`, `update`, `update --save`, and `show` again
 until it says `match yes`. Every `--save` comes after the author has read the dry run and said yes.
 
+## What a save freezes
+
+In a paper that keeps `cycles`, a `new --save` or `update --save` the portal took freezes what it
+sent: the exact PDF, and the source the build read (a paper split into several files, assembled), as
+`versions/<cycle>/submitted.{pdf,tex}` — `camera-ready.{pdf,tex}` once the cycle is accepted — and
+records both in `versions/lock.json`. It prints one line:
+
+```
+frozen        versions/beta-2027/submitted.pdf (186504 bytes) and submitted.tex (57210 bytes), recorded in versions/lock.json
+```
+
+A later save in the same cycle replaces them: the last upload is the one under review. `show` ends
+with the table of the paper's versions and their states, as `paperlint versions` prints it. A paper
+without `cycles` is sent as before, and the save says `not frozen`. The layout and the states:
+[configuration](configuration.md#the-frozen-versions-one-folder-per-attempt).
+
 ## The check before sending
 
 A person confirms every send. To help them decide, `new` and `update` first run the venue rules of
@@ -107,9 +123,11 @@ With no findings it prints one line, `venue rules at their default options: no e
 run at paperlint's default levels and options: a `rules` override in your `paperlint.json` or
 preset is applied by `paperlint lint`, not here.
 
-The command refuses one thing by itself: `--save` when no build facts describe this PDF (none, or
-of other bytes) exits 2 and sends nothing. Rebuild (`paperlint build`) and run the dry run again.
-Everything else, including over the limit, is the person's call.
+The command refuses two things by itself, each with exit 2 and nothing sent: `--save` when no build
+facts describe this PDF (none, or of other bytes), and — in a paper that keeps `cycles` — `--save`
+when the sources changed since the build, because the PDF and the source on disk would no longer be a
+pair to freeze. Rebuild (`paperlint build`) and run the dry run again. Everything else, including over
+the limit, is the person's call.
 
 **The `submission-confirm` hook** (installed by `paperlint init`) stops any `submission new|update`
 with `--save` or `--submit` until the person has said yes to that exact PDF in that exact folder. The flow:

package/eslint-rules/paper-stages.test.mjs

@@ -139,3 +139,65 @@ test("a frontmatter node without a value (another markdown language) reads as em
     stages.rules[rule].create(context).yaml({ type: "yaml" });
   assert.deepEqual(reports, []);
 });
+
+const CYCLES = { "paperlint.json": JSON.stringify({ cycles: [] }) };
+const RETIRED = (paper) =>
+  `\`stages\` is retired for a paper that keeps \`cycles\` in paperlint.json: its frozen versions are versions/<cycle>/<stage>.{pdf,tex}, recorded in versions/lock.json — \`npx paperlint versions migrate ${paper}\` moves the files there and takes the list out`;
+
+test("under `cycles`: a `stages` list is one finding naming the migration, and dated files owe it nothing", () => {
+  const files = {
+    ...CYCLES,
+    "versions/2026-08-02-submitted.pdf": "x",
+  };
+  assert.deepEqual(
+    lint(
+      "retired",
+      "stages:\n  - stage: submitted\n    date: 2026-08-02\n    pdf: versions/2026-08-02-submitted.pdf\n    bytes: 9",
+      { files },
+    ),
+    [RETIRED("retired")],
+  );
+  assert.deepEqual(
+    lint("retired-src", "stages:\n  - stage: submitted\n    date: 2026-08-02", {
+      rule: "source",
+      files,
+    }),
+    [],
+  );
+});
+
+test("under `cycles`: no list, an empty one, or no frontmatter is silent; YAML that does not parse is still named", () => {
+  assert.deepEqual(lint("retired-none", "title: x", { files: CYCLES }), []);
+  assert.deepEqual(lint("retired-empty", "stages: []", { files: CYCLES }), []);
+  const [msg] = lint("retired-yaml", "stages: [", { files: CYCLES });
+  assert.match(msg, /^the frontmatter does not parse as YAML: /);
+  // A paperlint.json that does not parse keeps the flat form's checks: `paperlint lint` refuses it before any rule runs.
+  assert.deepEqual(
+    lint("retired-broken", "stages:", {
+      files: { "paperlint.json": "{" },
+    }),
+    [
+      "`stages` must be a LIST of entries, not empty — a paper can reach the same stage twice",
+    ],
+  );
+});
+
+test("under `cycles`: a frontmatter node without a value reads as empty YAML", () => {
+  const dir = writeTree(join(root, "retired-valueless"), CYCLES);
+  const reports = [];
+  const context = {
+    filename: join(dir, "PIPELINE-STATUS.md"),
+    cwd: dir,
+    report: (r) => reports.push(r),
+  };
+  stages.rules.stages.create(context).yaml({ type: "yaml" });
+  assert.deepEqual(reports, []);
+  // Linted from the paper itself, the command names it as `.`.
+  stages.rules.stages
+    .create(context)
+    .yaml({ type: "yaml", value: "stages:\n  - stage: submitted" });
+  assert.deepEqual(
+    reports.map((r) => r.data),
+    [{ paper: "." }],
+  );
+});

package/eslint-rules/paper-stages.ts

@@ -46,8 +46,8 @@
  * keyed by stage name holds one. The `versions/<date>-<stage>.pdf` convention already holds
  * many, and the field must not be weaker than the filenames it describes.
  */
-import { existsSync, statSync, readdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { existsSync, readFileSync, statSync, readdirSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
 import assert from "node:assert/strict";
 import { load } from "js-yaml";
 import { z } from "zod";
@@ -68,6 +68,58 @@ const StageRecord = z
     sourceLost: z.unknown().optional(),
   })
   .catch({});
+/** What these rules read of the paper's settings: whether it keeps `cycles` at all. */
+const Settings = z
+  .looseObject({ cycles: z.array(z.unknown()).optional() })
+  .catch({});
+
+/**
+ * Whether the paper keeps `cycles` in its paperlint.json. Its frozen versions are then
+ * `versions/<cycle>/<stage>.{pdf,tex}` recorded in `versions/lock.json`, judged by `versions/layout`,
+ * and the `stages:` list is retired: `paperlint versions migrate` turns it into folders.
+ */
+function keepsCycles(dir: string): boolean {
+  try {
+    const raw: unknown = JSON.parse(
+      readFileSync(join(dir, "paperlint.json"), "utf8"),
+    );
+    return Settings.parse(raw).cycles !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/** Under `cycles`: a non-empty `stages:` list is one finding, naming the command that retires it. */
+function retired(context: RuleContext, dir: string) {
+  return {
+    yaml(node: { readonly value?: string }) {
+      const parsed = (() => {
+        try {
+          return { ok: true as const, data: load(node.value ?? "") };
+        } catch (e) {
+          assert.ok(e instanceof Error);
+          return { ok: false as const, reason: e.message };
+        }
+      })();
+      if (!parsed.ok) {
+        context.report({
+          node,
+          messageId: "badYaml",
+          data: { reason: parsed.reason },
+        });
+        return;
+      }
+      const raw = Frontmatter.parse(parsed.data).stages;
+      if (raw === undefined || (Array.isArray(raw) && raw.length === 0)) return;
+      context.report({
+        node,
+        messageId: "retired",
+        data: { paper: relative(context.cwd, dir) || "." },
+      });
+    },
+  };
+}
+
 const REQUIRED = ["date", "pdf", "bytes"] satisfies readonly (
   "date" | "pdf" | "bytes"
 )[];
@@ -126,6 +178,12 @@ function frozenPdfs(
   return out;
 }
 
+/** The frozen PDFs in `versions/` that no declared stage of the same day names. */
+const undeclared = (dir: string, records: readonly Declared[]) =>
+  frozenPdfs(join(dir, "versions")).filter(
+    (f) => !records.some((r) => r.stage === f.stage && r.date === f.date),
+  );
+
 export default {
   rules: {
     stages: {
@@ -150,12 +208,14 @@ export default {
             "«{{stage}}» ({{date}}): {{want}} bytes declared, {{got}} on disk — this is NOT that file",
           fileNotDeclared:
             "`versions/{{file}}` is frozen, but no «{{stage}}» stage on {{date}} is declared in `stages` — the artefact ran ahead of the declaration",
+          retired:
+            "`stages` is retired for a paper that keeps `cycles` in paperlint.json: its frozen versions are versions/<cycle>/<stage>.{pdf,tex}, recorded in versions/lock.json — `npx paperlint versions migrate {{paper}}` moves the files there and takes the list out",
         },
       },
       create(context: RuleContext) {
         const dir = dirname(context.filename);
+        if (keepsCycles(dir)) return retired(context, dir);
         let declared: Declared[] | null = null; // null = there was no frontmatter at all
-
         return {
           yaml(node: { readonly value?: string }) {
             let data: unknown;
@@ -252,16 +312,13 @@ export default {
           // 🔴 On `root:exit` rather than inside `yaml`, because the case worth catching is
           // precisely the one with NO frontmatter at all — where the `yaml` visitor never runs.
           "root:exit"(node: object) {
-            const records = declared ?? [];
-            for (const f of frozenPdfs(join(dir, "versions"))) {
-              if (records.some((r) => r.stage === f.stage && r.date === f.date))
-                continue;
+            undeclared(dir, declared ?? []).forEach((f) => {
               context.report({
                 node,
                 messageId: "fileNotDeclared",
                 data: { file: f.name, stage: f.stage, date: f.date },
               });
-            }
+            });
           },
         };
       },
@@ -319,6 +376,8 @@ export default {
       },
       create(context: RuleContext) {
         const dir = dirname(context.filename);
+        // Under `cycles` the lock records each frozen source, and `versions/layout` checks it.
+        if (keepsCycles(dir)) return {};
         return {
           yaml(node: { readonly value?: string }) {
             let data: unknown;

package/eslint-rules/prereg-coverage.test.ts

@@ -399,6 +399,7 @@ describe("the rule, on the status file of a paper", () => {
     rule
       .create({
         filename: join(dir, file),
+        cwd: dir,
         options: [],
         settings: {},
         sourceCode: {

package/eslint-rules/rule-context.ts

@@ -55,6 +55,8 @@ export interface RuleReport {
 
 export interface RuleContext {
   readonly filename: string;
+  /** The directory ESLint runs from: what a command a message names is relative to. */
+  readonly cwd: string;
   readonly options: readonly unknown[];
   readonly settings: Readonly<Record<string, unknown>>;
   readonly sourceCode: RuleSourceCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "12.1.0",
+  "version": "13.0.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "@unified-latex/unified-latex-util-replace": "^1.8.4",
     "@unified-latex/unified-latex-util-visit": "^1.8.4",
     "ajv": "^6.12.6",
+    "diff": "^8.0.4",
     "eslint": "^10.9.1",
     "js-yaml": "^4.1.0",
     "markdown-it": "^14.3.0",

package/skills/paper-pipeline/references/pipeline-status-template.md

@@ -11,7 +11,10 @@ the verdict line's wording and the `☐`/`☑` marks as they are, or the hook go
 
 ## The front matter
 
-Above the sections, the file carries YAML. The rules read its `stages` field:
+Above the sections, the file carries YAML. In a paper WITHOUT `cycles` in its `paperlint.json`, the
+rules read its `stages` field (a paper with `cycles` keeps no such list: its frozen versions are the
+folders `versions/<cycle>/` and the generated `versions/lock.json`, and `paperlint versions migrate`
+moves an old list there):
 
 ```yaml
 ---

package/skills/submit-paper/SKILL.md

@@ -4,7 +4,7 @@ description: End-to-end playbook for submitting a peer-reviewed paper to a doubl
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill]
 ---
 
-<!-- vigiles:sha256:81d5777962c2864a compiled from skills/submit-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:567bfff9583abdf1 compiled from skills/submit-paper/SKILL.md.spec.ts -->
 
 # submit-paper — get a reviewed paper from "done" to "ready for review"
 
@@ -137,20 +137,28 @@ Many workshop HotCRPs have **no supplementary-upload field** — check first; if
 
 ## 7. Freeze the version you actually uploaded
 
-🔴 **The moment the portal accepts the file, download it back and commit it.** The rendered PDF is the
-only artifact git cannot reconstruct — it was built outside the repo and lived on the portal.
+🔴 **What the reviewers read is the one version git cannot rebuild for you later** — it was built
+outside the repo and lives on the portal. Freeze it at the send.
+
+In a paper that keeps `cycles` in `paperlint.json`, the send freezes it:
+`paperlint submission update <paper> --save` (and `new --save`) writes the exact PDF it sent and the
+source the build read into
 
 ```
-<paper-dir>/versions/<ISO-date>-submitted.pdf
+<paper-dir>/versions/<cycle id>/submitted.pdf
+<paper-dir>/versions/<cycle id>/submitted.tex
 ```
 
-and in `PIPELINE-STATUS.md`, on the Submit row, the source that produced it: the literal word
-**`commit <hash>`**. Stages are `submitted` / `camera-ready` / `arxiv`; each one you *declare* in
-PIPELINE-STATUS needs its own frozen file.
+and records their bytes and sha256 in `versions/lock.json` (generated; never edit it). After an
+acceptance the same command freezes `camera-ready.{pdf,tex}`. An upload made on the portal by hand:
+put that PDF and its source there under those names and run `npx paperlint versions lock <paper>`.
+`npx paperlint versions` prints which version is under review and how far `paper.tex` has moved.
 
-**This is enforced, not advised** — `checkFrozenVersions()` in `.claude/hooks/paper-lint.mjs` reads the
-declared stages and reports a paper that declared one without freezing it. The convention itself is
-documented per-paper in `versions/README.md`.
+**This is enforced, not advised** — `cycle/submitted-frozen` fails a cycle that has a submission and
+no frozen `submitted.pdf`, and `versions/layout` fails a frozen file that no longer matches the lock.
+A paper without `cycles` records each stage in `PIPELINE-STATUS.md`'s `stages:` list instead,
+checked by `paper/stages` and `paper/source`; `npx paperlint versions migrate` moves it to the
+folders once it keeps `cycles`.
 
 **Why it is a step and not hygiene:** `agenticdev-2026` kept a folder for exactly this for a month and
 the file inside was the wrong build (340 952 B vs the real 352 357 B). It surfaced only when a reviewer

package/skills/submit-paper/SKILL.md.spec.ts

@@ -153,20 +153,28 @@ Many workshop HotCRPs have **no supplementary-upload field** — check first; if
 
 ## 7. Freeze the version you actually uploaded
 
-🔴 **The moment the portal accepts the file, download it back and commit it.** The rendered PDF is the
-only artifact git cannot reconstruct — it was built outside the repo and lived on the portal.
+🔴 **What the reviewers read is the one version git cannot rebuild for you later** — it was built
+outside the repo and lives on the portal. Freeze it at the send.
+
+In a paper that keeps \`cycles\` in \`paperlint.json\`, the send freezes it:
+\`paperlint submission update <paper> --save\` (and \`new --save\`) writes the exact PDF it sent and the
+source the build read into
 
 \`\`\`
-<paper-dir>/versions/<ISO-date>-submitted.pdf
+<paper-dir>/versions/<cycle id>/submitted.pdf
+<paper-dir>/versions/<cycle id>/submitted.tex
 \`\`\`
 
-and in \`PIPELINE-STATUS.md\`, on the Submit row, the source that produced it: the literal word
-**\`commit <hash>\`**. Stages are \`submitted\` / \`camera-ready\` / \`arxiv\`; each one you *declare* in
-PIPELINE-STATUS needs its own frozen file.
+and records their bytes and sha256 in \`versions/lock.json\` (generated; never edit it). After an
+acceptance the same command freezes \`camera-ready.{pdf,tex}\`. An upload made on the portal by hand:
+put that PDF and its source there under those names and run \`npx paperlint versions lock <paper>\`.
+\`npx paperlint versions\` prints which version is under review and how far \`paper.tex\` has moved.
 
-**This is enforced, not advised** — \`checkFrozenVersions()\` in \`.claude/hooks/paper-lint.mjs\` reads the
-declared stages and reports a paper that declared one without freezing it. The convention itself is
-documented per-paper in \`versions/README.md\`.
+**This is enforced, not advised** — \`cycle/submitted-frozen\` fails a cycle that has a submission and
+no frozen \`submitted.pdf\`, and \`versions/layout\` fails a frozen file that no longer matches the lock.
+A paper without \`cycles\` records each stage in \`PIPELINE-STATUS.md\`'s \`stages:\` list instead,
+checked by \`paper/stages\` and \`paper/source\`; \`npx paperlint versions migrate\` moves it to the
+folders once it keeps \`cycles\`.
 
 **Why it is a step and not hygiene:** \`agenticdev-2026\` kept a folder for exactly this for a month and
 the file inside was the wrong build (340 952 B vs the real 352 357 B). It surfaced only when a reviewer

package/skills/submit-paper/references/publishers/acm.md

@@ -81,9 +81,11 @@ need to wait for them or make them up.
 
 ## The frozen version
 
-Camera-ready is a separate **stage** in the sense of `versions/` (see `checkFrozenVersions()` in
-`paper-lint.mjs`): the uploaded PDF is stored as `versions/<date>-camera-ready.pdf`, and the commit
-of its source is recorded in `PIPELINE-STATUS.md` as `commit <hash>`.
+Camera-ready is a separate **stage** in `versions/`: once the cycle's `outcome` is `accepted`,
+`paperlint submission update <paper> --save` freezes the PDF it sends and its source as
+`versions/<cycle>/camera-ready.{pdf,tex}` and records them in `versions/lock.json`. A camera-ready
+uploaded through the publisher's own system (not the review portal) goes there by hand, followed by
+`npx paperlint versions lock <paper>`.
 
 **Why this isn't a formality:** the arXiv posting and the extension paper get diffed against
 camera-ready later, and reviewer references to line numbers only resolve against the exact render

package/src/adapters/memory/index.test.ts

@@ -6,9 +6,31 @@ import {
   fixedDownload,
   memoryFiles,
   memoryListEntries,
+  memoryCopyFile,
+  memoryMoveFile,
   memoryWorkspace,
 } from "./index.ts";
 
+test("memoryMoveFile: the bytes move to the new path; a path holding nothing throws", () => {
+  const files = memoryFiles({ "/p/a.pdf": "x" });
+  const move = memoryMoveFile(files);
+  move(absolutePath("/p/a.pdf"), absolutePath("/p/v/b.pdf"));
+  assert.deepEqual([...files.map.keys()], ["/p/v/b.pdf"]);
+  assert.throws(() => {
+    move(absolutePath("/p/a.pdf"), absolutePath("/p/c.pdf"));
+  }, /ENOENT/);
+});
+
+test("memoryCopyFile: the bytes under the new path too; a path holding nothing throws", () => {
+  const files = memoryFiles({ "/p/a.tex": "x" });
+  const copy = memoryCopyFile(files);
+  copy(absolutePath("/p/a.tex"), absolutePath("/p/v/b.tex"));
+  assert.deepEqual([...files.map.keys()], ["/p/a.tex", "/p/v/b.tex"]);
+  assert.throws(() => {
+    copy(absolutePath("/p/none"), absolutePath("/p/c.tex"));
+  }, /ENOENT/);
+});
+
 test("memoryWorkspace: a `within` that throws is recorded as `threw`, and the error goes on", () => {
   const ws = memoryWorkspace();
   assert.throws(

package/src/adapters/memory/index.ts

@@ -7,6 +7,7 @@ import type { Download } from "../../ports/download.ts";
 import type { Files } from "../../ports/files.ts";
 import type { ListDir } from "../../ports/talk-media.ts";
 import type { ListEntries } from "../../ports/list-entries.ts";
+import type { CopyFile, MoveFile } from "../../ports/move-file.ts";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
 import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
 import { err, ok } from "../../domain/result.ts";
@@ -73,6 +74,26 @@ export const memoryListDir =
     ),
   ];
 
+/** `MoveFile` over `memoryFiles`: the bytes under the new path, none under the old; nothing there throws. */
+/** `CopyFile` over `memoryFiles`: the bytes under the new path too; nothing there throws. */
+export const memoryCopyFile =
+  (files: MemoryFiles): CopyFile =>
+  (from, to) => {
+    const b = files.map.get(from);
+    if (b === undefined) throw new Error(`ENOENT: no file to copy at ${from}`);
+    files.writeAtomic(to, b);
+  };
+
+export const memoryMoveFile =
+  (files: MemoryFiles): MoveFile =>
+  (from, to) => {
+    const b = files.map.get(from);
+    if (b === undefined) throw new Error(`ENOENT: no file to move at ${from}`);
+    files.writeAtomic(to, b);
+    // eslint-disable-next-line functional/immutable-data -- a test double's disk is the mutable map memoryFiles keeps
+    files.map.delete(from);
+  };
+
 /**
  * `ListEntries` over `memoryFiles`: each name directly under a directory, a file when it is one, else a
  * directory. Memory holds no links: the walk's refusal to follow one is the node adapter's to show.

package/src/adapters/node/index.ts

@@ -36,3 +36,4 @@ export { spawnProcess, type SpawnSync } from "./process.io.ts";
 export { hostDirs } from "./host.io.ts";
 export { nodeListDir } from "./list-dir.io.ts";
 export { nodeListEntries } from "./list-entries.io.ts";
+export { nodeCopyFile, nodeMoveFile } from "./move-file.io.ts";

package/src/adapters/node/move-file.io.ts

@@ -0,0 +1,21 @@
+/** `MoveFile` and `CopyFile` over `node:fs`: a rename or a copy, the directory made first. */
+import { copyFileSync, mkdirSync, renameSync } from "node:fs";
+import { dirname } from "node:path";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { CopyFile, MoveFile } from "../../ports/move-file.ts";
+
+export const nodeMoveFile: MoveFile = (
+  from: AbsolutePath,
+  to: AbsolutePath,
+): void => {
+  mkdirSync(dirname(to), { recursive: true });
+  renameSync(from, to);
+};
+
+export const nodeCopyFile: CopyFile = (
+  from: AbsolutePath,
+  to: AbsolutePath,
+): void => {
+  mkdirSync(dirname(to), { recursive: true });
+  copyFileSync(from, to);
+};

package/src/adapters/node/move-file.test.ts

@@ -0,0 +1,51 @@
+/** `nodeMoveFile`: the file arrives with its bytes, into a folder made for it, and is gone from where it was. */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { absolutePath } from "../../domain/paths.ts";
+import { useTempDir } from "../../../test/support.ts";
+import { nodeCopyFile, nodeMoveFile } from "./move-file.io.ts";
+
+const root = useTempDir("paperlint-move-file-");
+
+describe("nodeMoveFile", () => {
+  it("moves a file into a folder that does not exist yet", () => {
+    writeFileSync(join(root, "a.pdf"), "bytes");
+    nodeMoveFile(
+      absolutePath(join(root, "a.pdf")),
+      absolutePath(join(root, "x", "y", "b.pdf")),
+    );
+    expect(existsSync(join(root, "a.pdf"))).toBe(false);
+    expect(readFileSync(join(root, "x", "y", "b.pdf"), "utf8")).toBe("bytes");
+  });
+
+  it("throws when there is nothing to move", () => {
+    expect(() => {
+      nodeMoveFile(
+        absolutePath(join(root, "none")),
+        absolutePath(join(root, "z")),
+      );
+    }).toThrow();
+  });
+});
+
+describe("nodeCopyFile", () => {
+  it("copies a file into a folder that does not exist yet, and leaves it where it was", () => {
+    writeFileSync(join(root, "s.tex"), "source");
+    nodeCopyFile(
+      absolutePath(join(root, "s.tex")),
+      absolutePath(join(root, "c", "d", "s.tex")),
+    );
+    expect(readFileSync(join(root, "s.tex"), "utf8")).toBe("source");
+    expect(readFileSync(join(root, "c", "d", "s.tex"), "utf8")).toBe("source");
+  });
+
+  it("throws when there is nothing to copy", () => {
+    expect(() => {
+      nodeCopyFile(
+        absolutePath(join(root, "none")),
+        absolutePath(join(root, "w")),
+      );
+    }).toThrow();
+  });
+});