paperlint 10.2.0 → 10.3.0

package/src/domain/study-registry.ts

@@ -61,6 +61,55 @@ export const INDEX_END = "<!-- studies:end -->";
 /** The README written when `repro/` has none. */
 const INDEX_HEADING = "# Reproduction index";
 
+/** What a measurement is to the paper: the claim it carries, or what that claim is compared with. */
+export const MEASUREMENT_ROLES = ["headline", "baseline"] as const;
+export type MeasurementRole = (typeof MEASUREMENT_ROLES)[number];
+
+/**
+ * The statuses of a study that has run: its plan was due before the first run. A `designing` study
+ * has not run yet, and a `dropped` one never will.
+ */
+export const RAN_STATUSES: readonly StudyStatus[] = [
+  "running",
+  "done",
+  "stopped",
+  "superseded",
+];
+
+/** A requirement of the author's on the paper's measurements, in their words. */
+export interface Requirement {
+  readonly id: string;
+  /** The author's words, verbatim. */
+  readonly text: string;
+  readonly date: string;
+  /** Where they said it: a chat, a message, a review comment. */
+  readonly source: string;
+}
+
+/** Someone's approval, in their words: of a measurement, or of a study's drawn units. */
+export interface Approval {
+  readonly by: string;
+  readonly date: string;
+  readonly quote: string;
+  readonly source?: string | undefined;
+}
+
+/**
+ * One measurement: what the paper measures, made of one or more studies (a pilot, the main run, a
+ * replication) whose rows name it in `measurement`. A measurement may carry more fields.
+ */
+export interface Measurement {
+  readonly id: string;
+  readonly title: string;
+  /** The research question it answers. */
+  readonly rq?: string | undefined;
+  readonly role: MeasurementRole;
+  readonly approval?: Approval | undefined;
+  /** The ids of the requirements it must meet. */
+  readonly requirements?: readonly string[] | undefined;
+  readonly [extra: string]: unknown;
+}
+
 /**
  * One study. The named fields are the registry's; a row may carry more (a paper merges its own
  * measurement metadata into it), and they are kept as they are.
@@ -77,14 +126,126 @@ export interface Study {
   readonly result_file?: string | undefined;
   readonly superseded_by?: string | undefined;
   readonly in_paper: InPaper;
+  /** The id of the measurement the study belongs to. */
+  readonly measurement?: string | undefined;
+  /** The study's plan: a path inside its folder, `plan.json`. */
+  readonly plan?: string | undefined;
   readonly [extra: string]: unknown;
 }
 
 export interface StudyRegistry {
   readonly prefix: string;
+  /** The paper's author: the one person whose approval makes a measurement the headline. */
+  readonly author?: string | undefined;
+  readonly requirements?: readonly Requirement[] | undefined;
+  /** When present, every row's `measurement` names one of them. */
+  readonly measurements?: readonly Measurement[] | undefined;
   readonly studies: readonly Study[];
 }
 
+/** The file `paperlint studies new` writes a study's plan to, beside its README.md. */
+export const PLAN_FILE = "plan.json";
+
+/** The plan's name before it was a plan: still read as one, and reported by `repro/study-plan-name`. */
+export const LEGACY_PLAN_FILE = "prereg.json";
+
+/** The author's check of a study's drawn units, before the runs. */
+export type AuthorCheck = Omit<Approval, "source">;
+
+/**
+ * A study's plan, fixed before its runs: what it measures, on what population and how it is drawn,
+ * its arms, its primary outcome, and the author's check of the drawn units. Closed: a key the paper
+ * needs of its own goes in `extra`, so a misspelt key is an error, not a key nobody reads. "Not
+ * known" and "not yet" have one spelling each: null.
+ */
+export interface StudyPlan {
+  readonly question: string;
+  readonly population: {
+    /** Where the units come from: the census, crawl or registry, with its date. */
+    readonly source: string;
+    readonly draw: Draw;
+  };
+  /** The conditions compared, each name once; none for a census. */
+  readonly arms: readonly { readonly name: string }[];
+  readonly primary_outcome: string;
+  /** null: the author has not checked the drawn units yet. Only a ready plan carries one. */
+  readonly author_check: AuthorCheck | null;
+  /** The paper's own keys: hypotheses, models, budget … Kept, never read; none is a plan field. */
+  readonly extra?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * How the sample is drawn from the population: a seeded draw, whose seed is part of it, or all of
+ * the population (a census), which has none. The size of the population is not stored: it is
+ * counted from the source, and a stored copy would only contradict it.
+ */
+export type Draw =
+  | {
+      readonly kind: "seeded";
+      /** `random`, `stratified` … */
+      readonly method: string;
+      readonly seed: string | number;
+    }
+  | {
+      readonly kind: "all";
+      /** `census` … */
+      readonly method: string;
+    };
+
+/** The top-level fields of a plan: none of them may be a key of `extra`. */
+export const PLAN_FIELDS = [
+  "question",
+  "population",
+  "arms",
+  "primary_outcome",
+  "author_check",
+  "extra",
+] as const;
+
+/** A plan with empty required texts: the author has not approved it. */
+export type DraftPlan = StudyPlan & { readonly author_check: null };
+
+/** The texts a plan must fill before the study runs, in the order they are named. */
+export const PLAN_TEXT_FIELDS = [
+  "question",
+  "population.source",
+  "population.draw.method",
+  "primary_outcome",
+] as const;
+export type PlanTextField = (typeof PLAN_TEXT_FIELDS)[number];
+
+/**
+ * A plan's text, parsed: ready (every required text filled), a draft (its empty texts named, and
+ * no check of the author's: only a complete plan is approved), or the reasons it is not a plan. Whether a plan is complete is decided here, once, by the parser.
+ */
+export type ParsedPlan =
+  | { readonly kind: "ready"; readonly plan: StudyPlan }
+  | {
+      readonly kind: "draft";
+      readonly plan: DraftPlan;
+      readonly empty: readonly PlanTextField[];
+    }
+  | { readonly kind: "unreadable"; readonly why: string };
+
+/** What a study's folder holds of the plan its row names: absent, or what its text parsed to. */
+export type PlanState = { readonly kind: "absent" } | ParsedPlan;
+
+/**
+ * The plan `paperlint studies new` writes: every field present, its value to fill. Its draw is of
+ * all the population (a census); a sampled study changes it to `{ "kind": "seeded", "method", "seed" }`.
+ */
+export const planTemplate = (): DraftPlan => ({
+  question: "",
+  population: { source: "", draw: { kind: "all", method: "" } },
+  arms: [],
+  primary_outcome: "",
+  author_check: null,
+});
+
+/** A plan's text as `paperlint studies new` writes it: JSON, two-space indented, a final newline. */
+export const planText = (p: StudyPlan): string =>
+  `${JSON.stringify(p, null, 2)}\n`;
+
 /** A registry's text, parsed: the registry, or the one reason it is not one. */
 export type ParsedRegistry =
   | { readonly ok: true; readonly registry: StudyRegistry }
@@ -105,6 +266,8 @@ export interface StudyInput {
   readonly readme: string | null;
   /** Each `<folder>/<result_file>` of the registry that is a file. */
   readonly existingResults: ReadonlySet<string>;
+  /** The plan each row names, by `<folder>/<plan>`; one not listed is absent. */
+  readonly plans: ReadonlyMap<string, PlanState>;
 }
 
 /** One defect of the registry, of a row, or of the index. */
@@ -157,8 +320,79 @@ export type StudyFinding =
   | {
       readonly problem: "stale-index";
       readonly why: "no-readme" | "no-markers" | "differs";
+    }
+  | {
+      readonly problem: "unknown-measurement";
+      readonly id: string;
+      readonly measurement: string;
+    }
+  | { readonly problem: "empty-measurement"; readonly measurement: string }
+  | {
+      readonly problem: "unknown-requirement";
+      readonly measurement: string;
+      readonly requirement: string;
+    }
+  | {
+      readonly problem: "headline-approval";
+      readonly measurement: string;
+      readonly why: "missing";
+      readonly author: string | null;
+    }
+  | {
+      readonly problem: "headline-approval";
+      readonly measurement: string;
+      readonly why: "not-author";
+      readonly by: string;
+      readonly author: string;
+    }
+  | {
+      readonly problem: "bad-plan";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "missing" | "outside";
+    }
+  | {
+      readonly problem: "bad-plan";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "unreadable";
+      readonly reasons: string;
+    }
+  | {
+      readonly problem: "bad-plan";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "unfilled";
+      readonly fields: readonly PlanTextField[];
+      readonly status: StudyStatus;
+    }
+  | {
+      readonly problem: "author-check";
+      readonly id: string;
+      readonly measurement: string;
+      readonly status: StudyStatus;
+      readonly why: "no-plan" | "missing";
+    }
+  | {
+      readonly problem: "author-check";
+      readonly id: string;
+      readonly measurement: string;
+      readonly status: StudyStatus;
+      readonly why: "not-author";
+      readonly by: string;
+      readonly author: string;
+    }
+  | {
+      readonly problem: "legacy-plan";
+      readonly id: string;
+      readonly path: string;
     };
 
+/** The findings `repro/study-plan-name` reports, a warning; every other is `repro/study-registered`'s. */
+export const PLAN_NAME_PROBLEMS: readonly StudyFinding["problem"][] = [
+  "legacy-plan",
+];
+
 /** The number of an id of `prefix` (`P1-S07` → 7); null for an id of another shape. */
 function idNumber(prefix: string, id: string): number | null {
   const m = new RegExp(`^${prefix}-S(\\d{2,})$`, "u").exec(id);
@@ -198,6 +432,15 @@ const isInside = (path: string): boolean => {
   return n !== ".." && !n.startsWith("../");
 };
 
+/**
+ * The `<folder>/<plan>` of each row whose plan lies inside its folder: the files the judge needs read
+ * (`StudyInput.plans`). A plan outside its folder is reported without being read.
+ */
+export const planKeys = (r: StudyRegistry): readonly string[] =>
+  r.studies.flatMap((s) =>
+    s.plan !== undefined && isInside(s.plan) ? [`${s.folder}/${s.plan}`] : [],
+  );
+
 /** One row of a registry, with what the judge read beside it. */
 interface Row {
   readonly r: StudyRegistry;
@@ -283,6 +526,102 @@ const noSuccessor: RowCheck = ({ r, s }) => {
     : null;
 };
 
+/** A row's `measurement`, when the registry declares its measurements, names one of them. */
+const unknownMeasurement: RowCheck = ({ r, s }) =>
+  r.measurements === undefined ||
+  s.measurement === undefined ||
+  r.measurements.some((m) => m.id === s.measurement)
+    ? null
+    : { problem: "unknown-measurement", id: s.id, measurement: s.measurement };
+
+/** The state of the plan the row names (absent when outside its folder); null when it names none. */
+const planOf = ({ s, input }: Row): PlanState | null => {
+  if (s.plan === undefined) return null;
+  return isInside(s.plan)
+    ? (input.plans.get(`${s.folder}/${s.plan}`) ?? { kind: "absent" })
+    : { kind: "absent" };
+};
+
+const hasRun = (s: Study): boolean => RAN_STATUSES.includes(s.status);
+
+/** The finding for the plan `path` of `s`, in the state its folder holds it; null when it stands. */
+const planFinding = (
+  s: Study,
+  path: string,
+  state: PlanState,
+): StudyFinding | null => {
+  const at = { problem: "bad-plan", id: s.id, path } as const;
+  switch (state.kind) {
+    case "absent":
+      return { ...at, why: "missing" };
+    case "unreadable":
+      return { ...at, why: "unreadable", reasons: state.why };
+    case "draft":
+      return hasRun(s)
+        ? { ...at, why: "unfilled", fields: state.empty, status: s.status }
+        : null;
+    case "ready":
+      return null;
+  }
+};
+
+/** The plan a row names is a file inside its folder, of the schema, and ready once the study has run. */
+const badPlan: RowCheck = ({ s, input }) => {
+  const path = s.plan;
+  if (path === undefined) return null;
+  if (!isInside(path))
+    return { problem: "bad-plan", id: s.id, path, why: "outside" };
+  return planFinding(
+    s,
+    path,
+    input.plans.get(`${s.folder}/${path}`) ?? { kind: "absent" },
+  );
+};
+
+/** A plan under its old name: read, and named for renaming. */
+const legacyPlan: RowCheck = ({ s }) =>
+  s.plan !== undefined && posix.basename(s.plan) === LEGACY_PLAN_FILE
+    ? { problem: "legacy-plan", id: s.id, path: s.plan }
+    : null;
+
+/**
+ * A study of a headline measurement that has run carries the author's check of its drawn units in
+ * its plan, by the registry's author when it names one. A plan that cannot be read is `badPlan`'s.
+ */
+const authorCheck: RowCheck = (row) => {
+  const { r, s } = row;
+  const m = r.measurements?.find((o) => o.id === s.measurement);
+  if (m?.role !== "headline" || !hasRun(s)) return null;
+  const at = {
+    problem: "author-check",
+    id: s.id,
+    measurement: m.id,
+    status: s.status,
+  } as const;
+  const state = planOf(row);
+  if (state === null) return { ...at, why: "no-plan" };
+  const wrong =
+    state.kind === "ready" || state.kind === "draft"
+      ? checkProblem(r, state.plan)
+      : null;
+  return wrong === null ? null : { ...at, ...wrong };
+};
+
+/** What a read plan's author check lacks: it is not there, or it is not the registry's author's. */
+const checkProblem = (
+  r: StudyRegistry,
+  plan: StudyPlan,
+):
+  | { readonly why: "missing" }
+  | { readonly why: "not-author"; readonly by: string; readonly author: string }
+  | null => {
+  const check = plan.author_check;
+  if (check === null) return { why: "missing" };
+  return r.author === undefined || check.by === r.author
+    ? null
+    : { why: "not-author", by: check.by, author: r.author };
+};
+
 /** The checks of a row, in the order their findings are reported. */
 const ROW_CHECKS: readonly RowCheck[] = [
   badId,
@@ -294,8 +633,58 @@ const ROW_CHECKS: readonly RowCheck[] = [
   noResult,
   resultFile,
   noSuccessor,
+  unknownMeasurement,
+  badPlan,
+  legacyPlan,
+  authorCheck,
 ];
 
+/** A headline measurement's approval: missing, or not the registry's author's; null when it stands. */
+const headlineApproval = (
+  r: StudyRegistry,
+  m: Measurement,
+): StudyFinding | null => {
+  if (m.role !== "headline") return null;
+  const author = r.author ?? null;
+  if (m.approval === undefined)
+    return {
+      problem: "headline-approval",
+      measurement: m.id,
+      why: "missing",
+      author,
+    };
+  return author === null || m.approval.by === author
+    ? null
+    : {
+        problem: "headline-approval",
+        measurement: m.id,
+        why: "not-author",
+        by: m.approval.by,
+        author,
+      };
+};
+
+/** What is wrong with one measurement: no study, a requirement not held, a headline not approved. */
+const judgeMeasurement = (
+  r: StudyRegistry,
+  m: Measurement,
+): readonly StudyFinding[] => {
+  const approval = headlineApproval(r, m);
+  return [
+    ...(r.studies.some((s) => s.measurement === m.id)
+      ? []
+      : [{ problem: "empty-measurement", measurement: m.id } as const]),
+    ...(m.requirements ?? [])
+      .filter((id) => !(r.requirements ?? []).some((q) => q.id === id))
+      .map((requirement): StudyFinding => ({
+        problem: "unknown-requirement",
+        measurement: m.id,
+        requirement,
+      })),
+    ...(approval === null ? [] : [approval]),
+  ];
+};
+
 /** What is wrong with a row, in a fixed order. */
 const judgeRow = (row: Row): readonly StudyFinding[] =>
   ROW_CHECKS.map((check) => check(row)).filter(
@@ -339,6 +728,7 @@ export function judgeStudies(input: StudyInput): readonly StudyFinding[] {
         next,
       })),
     ...r.studies.flatMap((s, i) => judgeRow({ r, s, i, input })),
+    ...(r.measurements ?? []).flatMap((m) => judgeMeasurement(r, m)),
     ...(index === null ? [] : [index]),
   ];
 }
@@ -466,6 +856,14 @@ const RENAME =
 
 const tick = (s: string): string => `\`${s}\``;
 
+/** `a`, `b` and `c`: names in backticks, the last joined by "and". */
+const listed = (names: readonly string[]): string => {
+  const t = names.map(tick);
+  return [t.slice(0, -1).join(", "), ...t.slice(-1)]
+    .filter((part) => part !== "")
+    .join(" and ");
+};
+
 /** Each finding by its problem: the map the messages are looked up in. */
 type FindingOf = {
   readonly [F in StudyFinding as F["problem"]]: F;
@@ -506,15 +904,58 @@ const HEADS: { readonly [P in Problem]: (f: FindingOf[P]) => string } = {
   "no-successor": (f) =>
     `${REGISTRY}: ${tick(f.id)} is \`superseded\` ${f.superseded_by === null ? "without `superseded_by`" : `by ${tick(f.superseded_by)}, which is no study in the registry`}. What to do: name the id of the study that replaced it.`,
   "stale-index": (f) => `${STALE_HEAD[f.why]} ${RUN_INDEX}`,
+  "unknown-measurement": (f) =>
+    `${REGISTRY}: the row ${tick(f.id)} names the measurement ${tick(f.measurement)}, which is not in \`measurements\`. What to do: add the measurement to \`measurements\`, or correct the row's \`measurement\`.`,
+  "empty-measurement": (f) =>
+    `${REGISTRY}: no row names the measurement ${tick(f.measurement)}, and a measurement is made of studies. What to do: set \`"measurement": "${f.measurement}"\` on the rows of its studies, or remove the measurement.`,
+  "unknown-requirement": (f) =>
+    `${REGISTRY}: the measurement ${tick(f.measurement)} must meet the requirement ${tick(f.requirement)}, which is not in \`requirements\`. What to do: add the requirement — the author's words verbatim in \`text\`, with its \`date\` and \`source\` — or correct the measurement's \`requirements\`.`,
+  "headline-approval": (f) =>
+    f.why === "missing"
+      ? `${REGISTRY}: the measurement ${tick(f.measurement)} is a \`headline\` one and has no \`approval\`. What to do: record ${f.author === null ? "the author's approval" : `the approval of ${f.author}, the registry's \`author\``} — \`by\`, \`date\`, and their words in \`quote\` — or make it a \`baseline\`.`
+      : `${REGISTRY}: the measurement ${tick(f.measurement)} is a \`headline\` one, and its \`approval\` is by ${f.by}, not by the registry's \`author\`, ${f.author}. What to do: only the author approves a headline measurement; record their own approval.`,
+  "bad-plan": (f) => {
+    const of = `the \`plan\` of ${tick(f.id)}, ${tick(f.path)},`;
+    const plan = `The plan of ${tick(f.id)}, ${tick(f.path)} in its folder,`;
+    switch (f.why) {
+      case "missing":
+        return `${REGISTRY}: ${of} is not a file in its folder. What to do: write the plan there (its fields are on the rule's page), or correct the row's \`plan\`.`;
+      case "outside":
+        return `${REGISTRY}: ${of} is outside its folder. What to do: keep the plan in the study's folder, as \`${PLAN_FILE}\`, and name it relative to the folder.`;
+      case "unreadable":
+        return `${plan} is not a study plan: ${f.reasons}. What to do: give it the fields on the rule's page — \`question\`, \`population\`, \`arms\`, \`primary_outcome\`.`;
+      case "unfilled":
+        return `${plan} leaves ${listed(f.fields)} empty, and the study is ${tick(f.status)}: a plan is written before the runs. What to do: fill them in, or set the study back to \`designing\`.`;
+    }
+  },
+  "author-check": (f) => {
+    const head = `${tick(f.id)} is ${tick(f.status)} in the headline measurement ${tick(f.measurement)}, and`;
+    switch (f.why) {
+      case "no-plan":
+        return `${head} its row names no plan to hold the author's check of the drawn units. What to do: write its plan (\`${PLAN_FILE}\` in its folder, named in the row's \`plan\`) with \`author_check\` — \`by\`, \`date\`, and the author's words in \`quote\`.`;
+      case "missing":
+        return `${head} its plan has no \`author_check\`. What to do: show the author the drawn units, then record their answer in the plan's \`author_check\` — \`by\`, \`date\`, and their words in \`quote\`.`;
+      case "not-author":
+        return `${head} the \`author_check\` in its plan is by ${f.by}, not by the registry's \`author\`, ${f.author}. What to do: only the author approves the drawn units of a headline measurement; record their own answer.`;
+    }
+  },
+  "legacy-plan": (f) =>
+    `The plan of ${tick(f.id)} is ${tick(f.path)}, its old name; it is read as the plan. What to do: rename it to \`${PLAN_FILE}\` in the study's folder (\`git mv\`) and set the row's \`plan\` to \`${PLAN_FILE}\`.`,
 };
 
 /** The head of finding `f` of problem `p`: the lookup, typed by the problem. */
 const headOf = <P extends Problem>(p: P, f: FindingOf[P]): string =>
   HEADS[p](f);
 
+/** The rule that reports finding `f`. */
+const ruleOf = (f: StudyFinding): string =>
+  PLAN_NAME_PROBLEMS.includes(f.problem)
+    ? "repro/study-plan-name"
+    : "repro/study-registered";
+
 /** The one text a finding is reported with: what is wrong, what to do, and the rule's page. */
 export const studyMessage = (f: StudyFinding): string =>
-  `${headOf(f.problem, f)}\nRule repro/study-registered: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/study-registered.md`;
+  `${headOf(f.problem, f)}\nRule ${ruleOf(f)}: https://github.com/zernie/paperlint/blob/main/docs/rules/${ruleOf(f)}.md`;
 
 // ── a new study ───────────────────────────────────────────────────────────────────
 
@@ -541,20 +982,20 @@ function titleProblem(title: string): string | null {
     : null;
 }
 
-/**
- * `r` with a new study appended: the next id, the folder `<id>-<slug>`, `status: designing`,
- * `in_paper: no` and an empty question; or why the title cannot make one.
- */
-export function addStudy(
-  r: StudyRegistry,
-  n: NewStudy,
-):
+/** A registry with a study added, and the study; or why it could not be. */
+export type Added =
   | {
       readonly ok: true;
       readonly registry: StudyRegistry;
       readonly study: Study;
     }
-  | { readonly ok: false; readonly why: string } {
+  | { readonly ok: false; readonly why: string };
+
+/**
+ * `r` with a new study appended: the next id, the folder `<id>-<slug>`, `status: designing`,
+ * `in_paper: no`, an empty question and its plan, `plan.json`; or why the title cannot make one.
+ */
+export function addStudy(r: StudyRegistry, n: NewStudy): Added {
   const title = n.title.trim().replace(/\s+/gu, " ");
   const why = titleProblem(title);
   if (why !== null) return { ok: false, why };
@@ -568,6 +1009,7 @@ export function addStudy(
     status: "designing",
     date: n.date,
     in_paper: "no",
+    plan: PLAN_FILE,
   };
   return {
     ok: true,
@@ -589,6 +1031,10 @@ export const studyReadme = (s: Study): string =>
     `Its row in \`../${STUDIES_FILE}\` holds its status. When the study ends, set \`status\`, \`result\`,`,
     "`result_file` and `in_paper` there, then run `npx paperlint studies index <paper-dir>`.",
     "",
+    `Its plan is \`${PLAN_FILE}\`: what it measures, the population and the draw, the arms and the primary`,
+    "outcome, filled in before the first run; the author's check of the drawn units goes in its",
+    "`author_check`.",
+    "",
     "## Question",
     "",
     "## How to run",

package/src/new-paper.test.ts

@@ -793,6 +793,7 @@ describe("paperlint lint — a scaffolded paper has no layout finding", () => {
     "paper/allowed-files-only",
     "repro/allowed-files-only",
     "repro/study-registered",
+    "repro/study-plan-name",
     "review/frontmatter",
     "sibling/frontmatter",
     "paper/stages",

package/src/ports/study-registry-codec.ts

@@ -1,11 +1,15 @@
 /**
- * How a `repro/studies.json` becomes a value: its text parsed once, where it enters, against the schema
+ * How a `repro/studies.json`, and a study's `plan.json`, become values: its text parsed once, where it enters, against the schema
  * of `StudyRegistry` (`src/domain/study-registry.ts`). The one implementation is
  * `src/adapters/study-registry/` (zod); `src/cli.ts` wires it.
  */
-import type { ParsedRegistry } from "../domain/study-registry.ts";
+import type { ParsedPlan, ParsedRegistry } from "../domain/study-registry.ts";
 
 export interface StudyRegistryCodec {
   /** A `studies.json`'s text: the registry, or the one reason it is not one of this schema. */
   readonly parse: (text: string) => ParsedRegistry;
+  /** A study's `plan.json` text, strict: ready, a draft naming its empty texts, or why it is no plan. */
+  readonly parsePlan: (text: string) => ParsedPlan;
+  /** A plan still named `prereg.json`, loose: the same three outcomes. */
+  readonly parseLegacyPlan: (text: string) => ParsedPlan;
 }

package/src/rule-cases.test.ts

@@ -18,6 +18,8 @@ import { z } from "zod";
 import { run, rulePlugins } from "./cli.ts";
 import { sha256Hex } from "./domain/sha256.ts";
 import {
+  planTemplate,
+  planText,
   registryText,
   withIndex,
   type StudyRegistry,
@@ -66,6 +68,20 @@ const REGISTERED_STUDY: Readonly<Record<string, string>> = {
   [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
 };
 
+/** The registered study with its plan named `name`, the plan's text beside its README. */
+const STUDY_WITH_PLAN = (name: string): Readonly<Record<string, string>> => {
+  const r: StudyRegistry = {
+    ...REGISTRY,
+    studies: REGISTRY.studies.map((s) => ({ ...s, plan: name })),
+  };
+  return {
+    [`${P}/repro/studies.json`]: registryText(r),
+    [`${P}/repro/README.md`]: withIndex("# repro\n", r),
+    [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
+    [`${P}/repro/P1-S01-ablation/${name}`]: planText(planTemplate()),
+  };
+};
+
 /** `study/declare-sample` is off by default; a paper turns it on in its `paperlint.json`. */
 const DECLARE_SAMPLE_ON: Readonly<Record<string, string>> = {
   [`${P}/paperlint.json`]: JSON.stringify({
@@ -771,6 +787,17 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     // Every folder registered, and the index the registry generates.
     silent: paper(tex("x"), REGISTERED_STUDY),
   },
+  // A study's plan still named prereg.json: read as its plan, and a warning to rename it.
+  "repro/study-plan-name": {
+    reports: {
+      tree: paper(tex("x"), STUDY_WITH_PLAN("prereg.json")),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 1,
+      line: 1,
+    },
+    // The same plan as plan.json.
+    silent: paper(tex("x"), STUDY_WITH_PLAN("plan.json")),
+  },
   // A study's prereg.json that declares none of population, strata, screens, coverage, author_check.
   // Off by default: the paper turns it on, as both trees do.
   "study/declare-sample": {

package/src/studies-cli.test.ts

@@ -83,7 +83,7 @@ describe("paperlint studies index — through the CLI", () => {
     writeTree(repro, {
       "studies.json": readFileSync(file, "utf8").replace(
         '"designing"',
-        '"running"',
+        '"dropped"',
       ),
     });
     expect(await registryFindings(dir)).toEqual([
@@ -96,7 +96,7 @@ describe("paperlint studies index — through the CLI", () => {
       [],
     ]);
     expect(readFileSync(join(repro, "README.md"), "utf8")).toContain(
-      "| P1-S01 | Baseline pass rate | running |",
+      "| P1-S01 | Baseline pass rate | dropped |",
     );
     expect(await registryFindings(dir)).toEqual([]);
   });