paperlint 10.2.0 → 10.3.0

package/skills/build-benchmark/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:93d83b56c6c1baea compiled from skills/build-benchmark/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:ed855c5f3aa34b10 compiled from skills/build-benchmark/SKILL.md.spec.ts -->
 
 # build-benchmark — the study + the artifact reviewers can run
 
@@ -44,10 +44,19 @@ Every study gets its folder, its id and its row from one command, never from a f
 npx paperlint studies new <paper-dir> "<plain title, at most 8 words>" --kind measurement
 ```
 
-It takes the next id in `repro/studies.json`, creates `repro/<id>-<slug>/README.md`, appends the row
-(`status: designing`) and regenerates the index in `repro/README.md`. The kinds: `measurement`,
-`spike`, `tooling`, `data`, `artifact`, `salvage`. Write the study's one-sentence `question` into its
-row at once.
+It takes the next id in `repro/studies.json`, creates `repro/<id>-<slug>/README.md` and the study's
+plan, `plan.json`, appends the row (`status: designing`, `plan: "plan.json"`) and regenerates the index
+in `repro/README.md`. The kinds: `measurement`, `spike`, `tooling`, `data`, `artifact`, `salvage`.
+Write the study's one-sentence `question` into its row at once. Never write a plan by hand under
+another name: the template's fields are the ones `repro/study-registered` reads.
+
+**A measurement that spans studies** (a pilot, the main run, a replication) is declared once, in
+`measurements` at the top of `repro/studies.json` — `id`, `title`, `rq`, `role` (`headline` or
+`baseline`) — and each of its studies' rows names it in `measurement`. The author's requirements on
+the measurements go, verbatim, into `requirements` (`id`, `text`, `date`, `source`), and each
+measurement lists the ones it must meet; never in a separate note. A `headline` measurement carries
+the author's `approval` (`by` the registry's `author`, `date`, their words in `quote`), written
+from the author's own message, never by the agent that designed the study.
 
 As the study moves, edit its row in `repro/studies.json`: `running` when the first counted run starts;
 when it ends, `done` with `result` (one line) and `result_file` (the file inside the folder the result
@@ -73,13 +82,16 @@ Write the design as the answer to "what would make the critiqued pitfall impossi
 **Declare the population, the screens and the coverage before freezing the sample.** Each screen
 between the population and the sample (fits one excerpt, one classifier lane, a model-picked item)
 changes what the sample can say, not only its size; screens that are reasonable one by one can leave a
-sample nobody meets in practice. So, before the draw is frozen, the study's `prereg.json` says what
-the claim is about, what each screen removed per stratum and what share the sample can represent; then
-show the author the drawn **units** (the rules or cases, not the items made from them) and ask: *is
-this what you meet in practice?* The fields are the experimental rule
-`study/declare-sample` (`docs/rules/study/declare-sample.md`), off by default: do this step either way,
-and turn the check on with `"rules": { "study/declare-sample": "error" }` in the paper's `paperlint.json`
-for `paperlint lint` to fail until they are there.
+sample nobody meets in practice. So, before the draw is frozen, fill the study's `plan.json`: the
+`question`, the `population` (its `source`, and the `draw`: `{ "kind": "all", "method" }` for a census,
+or `{ "kind": "seeded", "method", "seed" }` for a sample),
+the `arms` (`[]` for a census) and the `primary_outcome`; what each screen removed per stratum and
+what share the sample can represent go into the same file, under `extra` (the plan is closed: any
+other unknown key is an error). Then show the
+author the drawn **units** (the rules or cases, not the items made from them), ask *is this what you
+meet in practice?*, and record the answer in the plan's `author_check` (`by`, `date`, their words in
+`quote`). Once the study is `running`, `repro/study-registered` fails the lint on an empty plan field,
+and, for a study of a `headline` measurement, on a plan without the author's check.
 
 ## 2. Honest statistics — the part reviewers attack first
 

package/skills/build-benchmark/SKILL.md.spec.ts

@@ -50,10 +50,19 @@ Every study gets its folder, its id and its row from one command, never from a f
 npx paperlint studies new <paper-dir> "<plain title, at most 8 words>" --kind measurement
 \`\`\`
 
-It takes the next id in \`repro/studies.json\`, creates \`repro/<id>-<slug>/README.md\`, appends the row
-(\`status: designing\`) and regenerates the index in \`repro/README.md\`. The kinds: \`measurement\`,
-\`spike\`, \`tooling\`, \`data\`, \`artifact\`, \`salvage\`. Write the study's one-sentence \`question\` into its
-row at once.
+It takes the next id in \`repro/studies.json\`, creates \`repro/<id>-<slug>/README.md\` and the study's
+plan, \`plan.json\`, appends the row (\`status: designing\`, \`plan: "plan.json"\`) and regenerates the index
+in \`repro/README.md\`. The kinds: \`measurement\`, \`spike\`, \`tooling\`, \`data\`, \`artifact\`, \`salvage\`.
+Write the study's one-sentence \`question\` into its row at once. Never write a plan by hand under
+another name: the template's fields are the ones \`repro/study-registered\` reads.
+
+**A measurement that spans studies** (a pilot, the main run, a replication) is declared once, in
+\`measurements\` at the top of \`repro/studies.json\` — \`id\`, \`title\`, \`rq\`, \`role\` (\`headline\` or
+\`baseline\`) — and each of its studies' rows names it in \`measurement\`. The author's requirements on
+the measurements go, verbatim, into \`requirements\` (\`id\`, \`text\`, \`date\`, \`source\`), and each
+measurement lists the ones it must meet; never in a separate note. A \`headline\` measurement carries
+the author's \`approval\` (\`by\` the registry's \`author\`, \`date\`, their words in \`quote\`), written
+from the author's own message, never by the agent that designed the study.
 
 As the study moves, edit its row in \`repro/studies.json\`: \`running\` when the first counted run starts;
 when it ends, \`done\` with \`result\` (one line) and \`result_file\` (the file inside the folder the result
@@ -79,13 +88,16 @@ Write the design as the answer to "what would make the critiqued pitfall impossi
 **Declare the population, the screens and the coverage before freezing the sample.** Each screen
 between the population and the sample (fits one excerpt, one classifier lane, a model-picked item)
 changes what the sample can say, not only its size; screens that are reasonable one by one can leave a
-sample nobody meets in practice. So, before the draw is frozen, the study's \`prereg.json\` says what
-the claim is about, what each screen removed per stratum and what share the sample can represent; then
-show the author the drawn **units** (the rules or cases, not the items made from them) and ask: *is
-this what you meet in practice?* The fields are the experimental rule
-\`study/declare-sample\` (\`docs/rules/study/declare-sample.md\`), off by default: do this step either way,
-and turn the check on with \`"rules": { "study/declare-sample": "error" }\` in the paper's \`paperlint.json\`
-for \`paperlint lint\` to fail until they are there.
+sample nobody meets in practice. So, before the draw is frozen, fill the study's \`plan.json\`: the
+\`question\`, the \`population\` (its \`source\`, and the \`draw\`: \`{ "kind": "all", "method" }\` for a census,
+or \`{ "kind": "seeded", "method", "seed" }\` for a sample),
+the \`arms\` (\`[]\` for a census) and the \`primary_outcome\`; what each screen removed per stratum and
+what share the sample can represent go into the same file, under \`extra\` (the plan is closed: any
+other unknown key is an error). Then show the
+author the drawn **units** (the rules or cases, not the items made from them), ask *is this what you
+meet in practice?*, and record the answer in the plan's \`author_check\` (\`by\`, \`date\`, their words in
+\`quote\`). Once the study is \`running\`, \`repro/study-registered\` fails the lint on an empty plan field,
+and, for a study of a \`headline\` measurement, on a plan without the author's check.
 
 ## 2. Honest statistics — the part reviewers attack first
 

package/skills/build-label-page/SKILL.md

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:7a537e71585bd321 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:dd742c1fcb34cfd6 compiled from skills/build-label-page/SKILL.md.spec.ts -->
 
 # build-label-page — a page the person labels on a phone, and the labels back in the repo
 
@@ -49,15 +49,17 @@ The full text, each with its reason and its check, is
    fit the time they have on a phone? Who is the labeller: a page with a store opens only for people
    with access to the artifact, so the labeller is the owner or has been shared as a Contributor.
    If the study design is not written yet, `build-benchmark` comes first.
-   If the items come from a drawn sample, the study's `prereg.json` declares the population, the
-   screens and the coverage before the sample is frozen (the experimental rule `study/declare-sample` checks it, off by default), and the
-   author has been shown the drawn **units** (the rules or cases, not the items) with "is this what
-   you meet in practice?". The labelling page is not that check: items made from easy units each look
-   fine on their own.
+   If the items come from a drawn sample, the study's `plan.json` (written by
+   `paperlint studies new`) declares the population and its draw before the sample is frozen, and its
+   `author_check` records that the author has been shown the drawn **units** (the rules or cases, not
+   the items) with "is this what you meet in practice?". The labelling page is not that check: items
+   made from easy units each look fine on their own.
 2. **Copy the generator into the study and write the items.** The study folder is
    `<paper-dir>/repro/<id>-<slug>/`, made by `npx paperlint studies new <paper-dir> "Gold labels"
    --kind data` when the labelling is a study of its own (`P1-S04-gold-labels`): the command writes
-   its `README.md` and its row in `repro/studies.json`, and `repro/study-registered` checks both. When
+   its `README.md`, its `plan.json` and its row in `repro/studies.json`, and `repro/study-registered`
+   checks them; fill the plan (what is labelled, the items' source, `arms: []`, the primary outcome)
+   before the first label. When
    the labels are in, update the row (`status`, `result`, `result_file`) and run
    `npx paperlint studies index <paper-dir>`. Where this sits in stage 3, and what checks each place:
    `docs/layout.md` in the paperlint package.

package/skills/build-label-page/SKILL.md.spec.ts

@@ -59,15 +59,17 @@ The full text, each with its reason and its check, is
    fit the time they have on a phone? Who is the labeller: a page with a store opens only for people
    with access to the artifact, so the labeller is the owner or has been shared as a Contributor.
    If the study design is not written yet, \`build-benchmark\` comes first.
-   If the items come from a drawn sample, the study's \`prereg.json\` declares the population, the
-   screens and the coverage before the sample is frozen (the experimental rule \`study/declare-sample\` checks it, off by default), and the
-   author has been shown the drawn **units** (the rules or cases, not the items) with "is this what
-   you meet in practice?". The labelling page is not that check: items made from easy units each look
-   fine on their own.
+   If the items come from a drawn sample, the study's \`plan.json\` (written by
+   \`paperlint studies new\`) declares the population and its draw before the sample is frozen, and its
+   \`author_check\` records that the author has been shown the drawn **units** (the rules or cases, not
+   the items) with "is this what you meet in practice?". The labelling page is not that check: items
+   made from easy units each look fine on their own.
 2. **Copy the generator into the study and write the items.** The study folder is
    \`<paper-dir>/repro/<id>-<slug>/\`, made by \`npx paperlint studies new <paper-dir> "Gold labels"
    --kind data\` when the labelling is a study of its own (\`P1-S04-gold-labels\`): the command writes
-   its \`README.md\` and its row in \`repro/studies.json\`, and \`repro/study-registered\` checks both. When
+   its \`README.md\`, its \`plan.json\` and its row in \`repro/studies.json\`, and \`repro/study-registered\`
+   checks them; fill the plan (what is labelled, the items' source, \`arms: []\`, the primary outcome)
+   before the first label. When
    the labels are in, update the row (\`status\`, \`result\`, \`result_file\`) and run
    \`npx paperlint studies index <paper-dir>\`. Where this sits in stage 3, and what checks each place:
    \`docs/layout.md\` in the paperlint package.

package/skills/run-agent-grid/SKILL.md

@@ -4,7 +4,7 @@ description: "Run a paid or counted agent experiment grid end to end — units
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:522a747e8eb6ead4 compiled from skills/run-agent-grid/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:451354b8f781c409 compiled from skills/run-agent-grid/SKILL.md.spec.ts -->
 
 # run-agent-grid — running a counted agent grid without spoiling it
 
@@ -25,10 +25,15 @@ and a driver loop that calls the guard: [`references/registry-and-ledger.md`](re
 
 **The grid's study folder.** A grid is one study of the paper. Its folder is made by
 `npx paperlint studies new <paper-dir> "<title>" --kind measurement` — the next id in
-`repro/studies.json`, the folder `repro/<id>-<slug>/` — and `grid.json`, the runs and the ledger live
-in it. When the grid ends, its row is updated (`status`, `result`, `result_file`, `in_paper`) and
-`npx paperlint studies index <paper-dir>` regenerates the index; `repro/study-registered` fails the
-lint until both are done.
+`repro/studies.json`, the folder `repro/<id>-<slug>/` with the study's `plan.json` — and `grid.json`,
+the runs and the ledger live in it. The plan says what the grid measures, the population and its
+draw (`{ "kind": "seeded", "method", "seed" }`), the `arms` (each name once) and the `primary_outcome`, and is filled before the first counted
+run; the author's approval of the drawn units goes into both `grid.json`'s `approval` (the guard reads
+it) and the plan's `author_check` (the lint reads it). A grid that is one study of a larger
+measurement names it in its row's `measurement`. When the grid ends, its row is updated (`status`,
+`result`, `result_file`, `in_paper`) and `npx paperlint studies index <paper-dir>` regenerates the
+index; `repro/study-registered` fails the lint until both are done, and on a running grid whose plan
+is empty.
 
 ## The order — each gate is passed before the next phase starts
 

package/skills/run-agent-grid/SKILL.md.spec.ts

@@ -26,10 +26,15 @@ and a driver loop that calls the guard: [\`references/registry-and-ledger.md\`](
 
 **The grid's study folder.** A grid is one study of the paper. Its folder is made by
 \`npx paperlint studies new <paper-dir> "<title>" --kind measurement\` — the next id in
-\`repro/studies.json\`, the folder \`repro/<id>-<slug>/\` — and \`grid.json\`, the runs and the ledger live
-in it. When the grid ends, its row is updated (\`status\`, \`result\`, \`result_file\`, \`in_paper\`) and
-\`npx paperlint studies index <paper-dir>\` regenerates the index; \`repro/study-registered\` fails the
-lint until both are done.
+\`repro/studies.json\`, the folder \`repro/<id>-<slug>/\` with the study's \`plan.json\` — and \`grid.json\`,
+the runs and the ledger live in it. The plan says what the grid measures, the population and its
+draw (\`{ "kind": "seeded", "method", "seed" }\`), the \`arms\` (each name once) and the \`primary_outcome\`, and is filled before the first counted
+run; the author's approval of the drawn units goes into both \`grid.json\`'s \`approval\` (the guard reads
+it) and the plan's \`author_check\` (the lint reads it). A grid that is one study of a larger
+measurement names it in its row's \`measurement\`. When the grid ends, its row is updated (\`status\`,
+\`result\`, \`result_file\`, \`in_paper\`) and \`npx paperlint studies index <paper-dir>\` regenerates the
+index; \`repro/study-registered\` fails the lint until both are done, and on a running grid whose plan
+is empty.
 
 ## The order — each gate is passed before the next phase starts
 

package/src/adapters/study-registry/index.test.ts

@@ -4,6 +4,8 @@
  */
 import { describe, expect, it } from "vitest";
 import {
+  planTemplate,
+  planText,
   registryText,
   type StudyRegistry,
 } from "../../domain/study-registry.ts";
@@ -142,3 +144,341 @@ describe("refusing a row that is not a study", () => {
     });
   });
 });
+
+/** A registry with every key above the studies. */
+const FULL = {
+  prefix: "P1",
+  author: "A. Author",
+  requirements: [
+    {
+      id: "R1",
+      text: "Every sample is a random draw from all rules found.",
+      date: "2026-10-10",
+      source: "chat",
+    },
+  ],
+  measurements: [
+    {
+      id: "M1",
+      title: "Rule census",
+      rq: "RQ1",
+      role: "headline",
+      approval: {
+        by: "A. Author",
+        date: "2026-10-12",
+        quote: "This is the one.",
+        source: "review comment",
+      },
+      requirements: ["R1"],
+      frame: "all rules found",
+    },
+    { id: "M2", title: "Baseline", role: "baseline" },
+  ],
+  studies: [{ ...ROW, measurement: "M1", plan: "plan.json" }],
+};
+
+describe("the keys above the studies: author, requirements, measurements", () => {
+  it("a registry with all of them parses to itself, a measurement's extra fields kept", () => {
+    expect(parse(text(FULL))).toEqual({ ok: true, registry: FULL });
+  });
+});
+
+describe("refusing what is not a measurement, a requirement or a plan path", () => {
+  it.each([
+    [
+      "a role that is neither",
+      { ...FULL, measurements: [{ id: "M1", title: "x", role: "main" }] },
+      'measurements.0.role: Invalid option: expected one of "headline"|"baseline"',
+    ],
+    [
+      "an approval without the author's words",
+      {
+        ...FULL,
+        measurements: [
+          {
+            id: "M1",
+            title: "x",
+            role: "headline",
+            approval: { by: "A", date: "2026-10-12" },
+          },
+        ],
+      },
+      "measurements.0.approval.quote: Invalid input: expected string, received undefined",
+    ],
+    [
+      "a requirement with a key of its own",
+      { ...FULL, requirements: [{ ...FULL.requirements[0], note: "x" }] },
+      'requirements.0: Unrecognized key: "note"',
+    ],
+    [
+      "a row's plan that is not a path",
+      { ...FULL, studies: [{ ...ROW, plan: true }] },
+      "studies.0.plan: Invalid input: expected string, received boolean",
+    ],
+  ])("refuses %s", (_why, v, why) => {
+    expect(parse(text(v))).toEqual({ ok: false, why });
+  });
+});
+
+/** A filled plan of a seeded draw, with keys of the paper's own in `extra`. */
+const parsePlan = studyRegistryCodec.parsePlan;
+const PLAN = {
+  question: "How many rules can a linter check?",
+  population: {
+    source: "the crawl of 2026-10-01",
+    draw: { kind: "seeded", method: "random", seed: 7 },
+  },
+  arms: [{ name: "with the linter" }, { name: "without" }],
+  primary_outcome: "the share of rules checked",
+  author_check: { by: "A. Author", date: "2026-10-14", quote: "Go." },
+  extra: { hypotheses: ["H1"], draw_script: "tools/draw.py" },
+};
+
+/** `PLAN` with `over` merged in, as the text of a file. */
+const planWith = (over: Readonly<Record<string, unknown>>): string =>
+  JSON.stringify({ ...PLAN, ...over });
+
+describe("parsing a study's plan: ready or draft", () => {
+  it("a filled plan is ready, its `extra` kept as it is", () => {
+    expect(parsePlan(JSON.stringify(PLAN))).toEqual({
+      kind: "ready",
+      plan: PLAN,
+    });
+  });
+
+  it("a census draws all: no seed", () => {
+    const census = {
+      ...PLAN,
+      population: {
+        source: "every rule found",
+        draw: { kind: "all", method: "census" },
+      },
+      arms: [],
+    };
+    expect(parsePlan(JSON.stringify(census))).toEqual({
+      kind: "ready",
+      plan: census,
+    });
+  });
+
+  it("the template studies new writes is a draft of a census, naming every empty text", () => {
+    expect(planTemplate().population.draw).toEqual({ kind: "all", method: "" });
+    expect(parsePlan(planText(planTemplate()))).toEqual({
+      kind: "draft",
+      plan: planTemplate(),
+      empty: [
+        "question",
+        "population.source",
+        "population.draw.method",
+        "primary_outcome",
+      ],
+    });
+  });
+
+  it("a text of white space only is empty", () => {
+    const plan = { ...PLAN, primary_outcome: "  ", author_check: null };
+    expect(parsePlan(JSON.stringify(plan))).toEqual({
+      kind: "draft",
+      plan,
+      empty: ["primary_outcome"],
+    });
+  });
+});
+
+describe("parsing a study's plan: no contradictory state", () => {
+  it.each([
+    [
+      "an author_check on a draft: the author approved a plan with empty texts",
+      planWith({ question: "", primary_outcome: " " }),
+      "author_check: is set, and the plan leaves `question`, `primary_outcome` empty — the author approves a complete plan: fill them, or set author_check to null",
+    ],
+    [
+      "a seeded draw without its seed",
+      planWith({
+        population: {
+          source: "x",
+          draw: { kind: "seeded", method: "random" },
+        },
+      }),
+      "population.draw.seed: Invalid input",
+    ],
+    [
+      "a seeded draw whose seed is null",
+      planWith({
+        population: {
+          source: "x",
+          draw: { kind: "seeded", method: "random", seed: null },
+        },
+      }),
+      "population.draw.seed: Invalid input",
+    ],
+    [
+      "a draw of all that carries a seed",
+      planWith({
+        population: {
+          source: "x",
+          draw: { kind: "all", method: "census", seed: 7 },
+        },
+      }),
+      'population.draw: Unrecognized key: "seed"',
+    ],
+    [
+      "a draw of no known kind",
+      planWith({
+        population: { source: "x", draw: { method: "census" } },
+      }),
+      "population.draw.kind: Invalid discriminator value. Expected 'seeded' | 'all'",
+    ],
+  ])("refuses %s", (_why, t, why) => {
+    expect(parsePlan(t)).toEqual({ kind: "unreadable", why });
+  });
+});
+
+describe("parsing a study's plan: no name or fact said twice", () => {
+  it.each([
+    [
+      "two arms of one name",
+      planWith({ arms: [{ name: "a" }, { name: "b" }, { name: "a" }] }),
+      "arms: more than one arm is named «a» — an arm's name is unique",
+    ],
+    [
+      "a key in `extra` that is a field of the plan",
+      planWith({ extra: { hypotheses: ["H1"], question: "x" } }),
+      "extra.question: is a field of the plan itself — set it there, not in extra",
+    ],
+    [
+      "a population size: it is derived, never stored",
+      planWith({ population: { ...PLAN.population, size: 4210 } }),
+      'population: Unrecognized key: "size"',
+    ],
+  ])("refuses %s", (_why, t, why) => {
+    expect(parsePlan(t)).toEqual({ kind: "unreadable", why });
+  });
+});
+
+describe("parsing a study's plan: strict at every level", () => {
+  it.each([
+    ["text that is not JSON", "{", "not JSON"],
+    [
+      "a misspelt key at the top",
+      planWith({ primary_outcom: "x" }),
+      '(top): Unrecognized key: "primary_outcom"',
+    ],
+    [
+      "a misspelt key in the draw",
+      planWith({
+        population: {
+          ...PLAN.population,
+          draw: { kind: "seeded", method: "random", seed: 7, sed: 7 },
+        },
+      }),
+      'population.draw: Unrecognized key: "sed"',
+    ],
+    [
+      "a key of the paper's own outside `extra`",
+      planWith({ hypotheses: ["H1"] }),
+      '(top): Unrecognized key: "hypotheses"',
+    ],
+    [
+      "no author_check: null is the one way to say none yet",
+      planWith({ author_check: undefined }),
+      "author_check: Invalid input: expected object, received undefined",
+    ],
+    [
+      "an author_check with an empty quote",
+      planWith({ author_check: { ...PLAN.author_check, quote: "" } }),
+      "author_check.quote: Too small: expected string to have >=1 characters",
+    ],
+    [
+      "an arm with a key besides its name",
+      planWith({ arms: [{ name: "a", model: "m" }] }),
+      'arms.0: Unrecognized key: "model"',
+    ],
+  ])("refuses %s", (_why, t, why) => {
+    expect(parsePlan(t)).toEqual({ kind: "unreadable", why });
+  });
+});
+
+/** A plan under its old name, written by hand: keys of its own, a size, no seed, no check. */
+const parseLegacyPlan = studyRegistryCodec.parseLegacyPlan;
+const OLD = {
+  question: "How many rules can a linter check?",
+  population: {
+    source: "the crawl of 2026-10-01",
+    about: "rules in instruction files",
+    size: 4210,
+    draw: { method: "random", script: "tools/draw.py" },
+  },
+  arms: [{ name: "with the linter", model: "m" }],
+  primary_outcome: "",
+  hypotheses: ["H1"],
+  strata: { by: "type" },
+};
+
+describe("parsing a plan under its old name, prereg.json: loose", () => {
+  it("keys of its own accepted, the top-level ones kept in `extra`; size dropped; no seed and no check: a draw of all, null", () => {
+    expect(parseLegacyPlan(JSON.stringify(OLD))).toEqual({
+      kind: "draft",
+      plan: {
+        question: "How many rules can a linter check?",
+        population: {
+          source: "the crawl of 2026-10-01",
+          draw: { kind: "all", method: "random" },
+        },
+        arms: [{ name: "with the linter" }],
+        primary_outcome: "",
+        author_check: null,
+        extra: { hypotheses: ["H1"], strata: { by: "type" } },
+      },
+      empty: ["primary_outcome"],
+    });
+  });
+});
+
+describe("parsing a plan under its old name, prereg.json: its draw", () => {
+  it("a seed, and a check: a seeded draw, the check kept", () => {
+    const old = {
+      ...OLD,
+      population: {
+        source: "s",
+        draw: { method: "random", seed: "a1" },
+      },
+      primary_outcome: "share",
+      author_check: { by: "A. Author", date: "2026-10-14", quote: "Go." },
+    };
+    expect(parseLegacyPlan(JSON.stringify(old))).toMatchObject({
+      kind: "ready",
+      plan: {
+        population: {
+          source: "s",
+          draw: { kind: "seeded", method: "random", seed: "a1" },
+        },
+        author_check: { by: "A. Author", date: "2026-10-14", quote: "Go." },
+      },
+    });
+  });
+
+  it("a seed of null is a draw of all", () => {
+    const old = {
+      ...OLD,
+      population: { source: "s", draw: { method: "census", seed: null } },
+    };
+    expect(parseLegacyPlan(JSON.stringify(old))).toMatchObject({
+      plan: { population: { draw: { kind: "all", method: "census" } } },
+    });
+  });
+
+  it("still needs the plan's own fields", () => {
+    expect(parseLegacyPlan(JSON.stringify({ hypotheses: ["H1"] }))).toEqual({
+      kind: "unreadable",
+      why: "question: Invalid input: expected string, received undefined; population: Invalid input: expected object, received undefined; arms: Invalid input: expected array, received undefined; primary_outcome: Invalid input: expected string, received undefined",
+    });
+  });
+
+  it("text that is not JSON", () => {
+    expect(parseLegacyPlan("{")).toEqual({
+      kind: "unreadable",
+      why: "not JSON",
+    });
+  });
+});