paperlint 10.2.0 → 10.4.0

package/src/domain/study-registry.ts

@@ -10,12 +10,22 @@
  * ── JSON, NEVER MARKDOWN ─────────────────────────────────────────────────────────
  * The registry is data: its text is parsed once, where it enters, against the schema in
  * `src/adapters/study-registry/` (`StudyRegistryCodec`). The index in `repro/README.md` is OUTPUT: it is
- * generated from the registry and compared as a string, between two fixed markers. Nothing parses it.
+ * generated from the registry, the plans' modes and git's history (src/domain/index-columns.ts), and
+ * compared cell by cell between two fixed markers, the two columns read from git left out. Nothing
+ * else parses it.
  *
  * Pure: the caller lists `repro/`, reads the registry and the README, and says which result files exist.
  */
 import { isAbsolute, posix, win32 } from "node:path";
 import { STUDIES_FILE, STUDY_SLUG } from "./repro-layout.ts";
+import { needsMode, type StudyMode } from "./study-mode.ts";
+import {
+  decisionCell,
+  firstOutputCell,
+  modeCell,
+  type IndexFacts,
+  type IndexHistory,
+} from "./index-columns.ts";
 
 /** The registry, at the top of the paper's `repro/`; the layout allows it there. */
 export { STUDIES_FILE };
@@ -61,6 +71,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 +136,155 @@ 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 outcomes are kept from the decisions on the inputs: decided before the run, or
+   * exploratory (src/domain/study-mode.ts). A measurement study's plan is not ready without it.
+   */
+  readonly mode?: StudyMode | 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",
+  "mode",
+] 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",
+  "mode",
+  "mode.outputs",
+  "mode.decision.file",
+  "mode.decision.note",
+  "mode.reason",
+] 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 decision file `paperlint studies new` names for a study in `folder`, relative to the paper. */
+export const decisionPath = (folder: string): string =>
+  `repro/${folder}/${DECISION_FILE}`;
+
+/** The decision file's name, beside the plan. */
+export const DECISION_FILE = "decision.md";
+
+/**
+ * The plan `paperlint studies new` writes for a study of `kind` in `folder`: 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" }`. A study that must declare its mode gets the default one,
+ * decided before the run, its decision file named and its outputs and note to fill.
+ */
+export const planTemplate = (kind: StudyKind, folder: string): DraftPlan => ({
+  question: "",
+  population: { source: "", draw: { kind: "all", method: "" } },
+  arms: [],
+  primary_outcome: "",
+  author_check: null,
+  ...(needsMode(kind)
+    ? {
+        mode: {
+          kind: "decide_before_run",
+          outputs: [],
+          decision: { file: decisionPath(folder), note: "" },
+        },
+      }
+    : {}),
+});
+
+/** 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 +305,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 +359,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);
@@ -191,13 +464,42 @@ export const titleWords = (title: string): number =>
  * Whether `path` stays inside the folder it is relative to. A backslash or a Windows absolute path
  * is refused outright: `posix.normalize` does not resolve `..\\`, while the host's `join` may.
  */
-const isInside = (path: string): boolean => {
+export const isInside = (path: string): boolean => {
   if (path.includes("\\") || isAbsolute(path) || win32.isAbsolute(path))
     return false;
   const n = posix.normalize(path);
   return n !== ".." && !n.startsWith("../");
 };
 
+/**
+ * Whether `folder` names one folder directly inside `repro/`: not empty, not `.` or `..`, and no
+ * separator or NUL. Every command and rule that reads a study's folder reads only such a one: a row
+ * naming `../x` would have them read and write outside the paper.
+ */
+export const isFolderName = (folder: string): boolean =>
+  folder !== "." && folder !== ".." && /^[^/\\\0]+$/u.test(folder);
+
+/**
+ * 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[] =>
+  planRefs(r).map((p) => p.key);
+
+/** Each plan `planKeys` names, with the kind of the study whose row names it: what its parser needs. */
+export const planRefs = (
+  r: StudyRegistry,
+): readonly {
+  readonly key: string;
+  readonly folder: string;
+  readonly kind: StudyKind;
+}[] =>
+  r.studies.flatMap((s) =>
+    s.plan !== undefined && isInside(s.plan) && isFolderName(s.folder)
+      ? [{ key: `${s.folder}/${s.plan}`, folder: s.folder, kind: s.kind }]
+      : [],
+  );
+
 /** One row of a registry, with what the judge read beside it. */
 interface Row {
   readonly r: StudyRegistry;
@@ -283,6 +585,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 +692,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(
@@ -306,11 +754,12 @@ const judgeRow = (row: Row): readonly StudyFinding[] =>
 function judgeIndex(
   r: StudyRegistry,
   readme: string | null,
+  plans: ReadonlyMap<string, PlanState>,
 ): StudyFinding | null {
   if (readme === null) return { problem: "stale-index", why: "no-readme" };
   const block = embeddedIndex(readme);
   if (block === null) return { problem: "stale-index", why: "no-markers" };
-  return indexInSync(readme, r)
+  return indexInSync(readme, r, { plans, history: new Map() })
     ? null
     : { problem: "stale-index", why: "differs" };
 }
@@ -329,7 +778,7 @@ export function judgeStudies(input: StudyInput): readonly StudyFinding[] {
     return [{ problem: "unreadable", why: state.why }];
   const r = state.registry;
   const next = nextStudyId(r);
-  const index = judgeIndex(r, input.readme);
+  const index = judgeIndex(r, input.readme, input.plans);
   return [
     ...input.folders
       .filter((f) => !r.studies.some((s) => s.folder === f))
@@ -339,6 +788,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]),
   ];
 }
@@ -349,19 +799,65 @@ export function judgeStudies(input: StudyInput): readonly StudyFinding[] {
 const cell = (s: string): string =>
   s.replace(/\r?\n/gu, " ").replace(/\\/gu, "\\\\").replace(/\|/gu, "\\|");
 
-/** The columns of the index: each one's header, and its cell for a study. */
+/**
+ * What the index is generated from beyond the registry: the plans by `<folder>/<plan>` (as
+ * `StudyInput.plans`), and the history of each decide-first study by id. A study with no history
+ * listed shows `not read` — the lint, which never compares those columns, asks none.
+ */
+export interface IndexInput {
+  readonly plans: ReadonlyMap<string, PlanState>;
+  readonly history: ReadonlyMap<string, IndexHistory>;
+}
+
+/** The mode the plan of `s` declares; null when it names none, or the plan is absent or unreadable. */
+const declaredMode = (
+  s: Study,
+  plans: ReadonlyMap<string, PlanState>,
+): StudyMode | null => {
+  const state =
+    s.plan !== undefined && isInside(s.plan)
+      ? plans.get(`${s.folder}/${s.plan}`)
+      : undefined;
+  return state === undefined ||
+    state.kind === "absent" ||
+    state.kind === "unreadable"
+    ? null
+    : (state.plan.mode ?? null);
+};
+
+/** What the index shows of `s` beyond its row. */
+const factsOf = (s: Study, at: IndexInput): IndexFacts => ({
+  mode: declaredMode(s, at.plans),
+  history: at.history.get(s.id) ?? null,
+});
+
+/**
+ * The columns of the index: each one's header, its cell for a study, and whether git's history is
+ * where the cell comes from — those two are never compared (src/domain/index-columns.ts).
+ */
 const COLUMNS: readonly {
   readonly head: string;
-  readonly of: (s: Study) => string;
+  readonly of: (s: Study, f: IndexFacts) => string;
+  readonly fromGit: boolean;
 }[] = [
-  { head: "id", of: (s) => s.id },
-  { head: "title", of: (s) => cell(s.title) },
-  { head: "status", of: (s) => s.status },
-  { head: "result", of: (s) => cell(s.result ?? "—") },
-  { head: "in paper", of: (s) => s.in_paper },
-  { head: "folder", of: (s) => `[${s.folder}/](${s.folder}/)` },
+  { head: "id", of: (s) => s.id, fromGit: false },
+  { head: "title", of: (s) => cell(s.title), fromGit: false },
+  { head: "status", of: (s) => s.status, fromGit: false },
+  { head: "result", of: (s) => cell(s.result ?? "—"), fromGit: false },
+  { head: "in paper", of: (s) => s.in_paper, fromGit: false },
+  { head: "mode", of: (_, f) => cell(modeCell(f)), fromGit: false },
+  { head: "decision", of: (_, f) => decisionCell(f), fromGit: true },
+  { head: "first output", of: (_, f) => firstOutputCell(f), fromGit: true },
+  {
+    head: "folder",
+    of: (s) => `[${s.folder}/](${s.folder}/)`,
+    fromGit: false,
+  },
 ];
 
+/** The positions of the columns read from git: left out when an index is compared. */
+const FROM_GIT = COLUMNS.flatMap((c, i) => (c.fromGit ? [i] : []));
+
 /** The width a cell takes: its code points. */
 const widthOf = (s: string): number => Array.from(s).length;
 
@@ -374,20 +870,23 @@ const padded = (t: string, width: number): string =>
  * widest cell (at least 3), the way prettier writes a table — so formatting the README leaves it as
  * it is.
  */
-export function studyIndex(r: StudyRegistry): string {
+export function studyIndex(r: StudyRegistry, at: IndexInput): string {
+  const studies = r.studies.map((s) => ({ s, f: factsOf(s, at) }));
   const sized = COLUMNS.map((c) => ({
     ...c,
     width: Math.max(
       3,
       widthOf(c.head),
-      ...r.studies.map((s) => widthOf(c.of(s))),
+      ...studies.map(({ s, f }) => widthOf(c.of(s, f))),
     ),
   }));
   const line = (cells: readonly string[]): string => `| ${cells.join(" | ")} |`;
   return [
     line(sized.map((c) => padded(c.head, c.width))),
     line(sized.map((c) => "-".repeat(c.width))),
-    ...r.studies.map((s) => line(sized.map((c) => padded(c.of(s), c.width)))),
+    ...studies.map(({ s, f }) =>
+      line(sized.map((c) => padded(c.of(s, f), c.width))),
+    ),
   ].join("\n");
 }
 
@@ -396,7 +895,7 @@ export function studyIndex(r: StudyRegistry): string {
  * `---`. The index is judged on this, because the padding belongs to the formatter: prettier sizes a
  * column by display width, so a wide character pads differently from a code-point count.
  */
-const cellsOf = (table: string): string =>
+const cellsOf = (table: string, skip: readonly number[]): string =>
   table
     .trim()
     .split("\n")
@@ -406,19 +905,44 @@ const cellsOf = (table: string): string =>
         .replace(/^\||\|$/gu, "")
         .split(/(?<!\\)\|/u)
         .map((c) => c.trim().replace(/^:?-{3,}:?$/u, "---"))
+        .filter((_, i) => !skip.includes(i))
         .join("|"),
     )
     .join("\n");
 
-/** Whether `readme` holds the index of `r`, whatever padding a formatter gave its table. */
-export function indexInSync(readme: string | null, r: StudyRegistry): boolean {
+/** Whether `readme` holds the index of `r` in every column but those at `skip`, whatever its padding. */
+const sameCells = (
+  readme: string | null,
+  index: string,
+  skip: readonly number[],
+): boolean => {
   const block = readme === null ? null : embeddedIndex(readme);
-  return block !== null && cellsOf(block) === cellsOf(studyIndex(r));
-}
+  return block !== null && cellsOf(block, skip) === cellsOf(index, skip);
+};
+
+/**
+ * Whether `readme` holds the index of `r`, whatever padding a formatter gave its table and whatever
+ * its two columns read from git say: what `repro/study-registered` checks.
+ */
+export const indexInSync = (
+  readme: string | null,
+  r: StudyRegistry,
+  at: IndexInput,
+): boolean => sameCells(readme, studyIndex(r, at), FROM_GIT);
+
+/**
+ * Whether `readme` holds the index of `r` in every column, whatever its padding: when it does,
+ * `studies index` leaves the README as it is, so the padding a formatter gave the table stays.
+ */
+export const indexCurrent = (
+  readme: string | null,
+  r: StudyRegistry,
+  at: IndexInput,
+): boolean => sameCells(readme, studyIndex(r, at), []);
 
 /** The index between its markers, a blank line on each side. */
-export const indexBlock = (r: StudyRegistry): string =>
-  `${INDEX_BEGIN}\n\n${studyIndex(r)}\n\n${INDEX_END}`;
+export const indexBlock = (r: StudyRegistry, at: IndexInput): string =>
+  `${INDEX_BEGIN}\n\n${studyIndex(r, at)}\n\n${INDEX_END}`;
 
 /**
  * Where `marker` stands alone on a line of `text`, at or after `from`; -1 when it does not. A marker
@@ -442,13 +966,18 @@ export function embeddedIndex(readme: string): string | null {
  * `readme` with its index regenerated from `r`: the block replaced in place, appended when the README
  * has none, a README of its own when there is none.
  */
-export function withIndex(readme: string | null, r: StudyRegistry): string {
-  if (readme === null) return `${INDEX_HEADING}\n\n${indexBlock(r)}\n`;
+export function withIndex(
+  readme: string | null,
+  r: StudyRegistry,
+  at: IndexInput,
+): string {
+  const fresh = indexBlock(r, at);
+  if (readme === null) return `${INDEX_HEADING}\n\n${fresh}\n`;
   const block = embeddedIndex(readme);
-  if (block === null) return `${readme.trimEnd()}\n\n${indexBlock(r)}\n`;
+  if (block === null) return `${readme.trimEnd()}\n\n${fresh}\n`;
   const begin = markerAt(readme, INDEX_BEGIN);
   const after = begin + INDEX_BEGIN.length + block.length + INDEX_END.length;
-  return `${readme.slice(0, begin)}${indexBlock(r)}${readme.slice(after)}`;
+  return `${readme.slice(0, begin)}${fresh}${readme.slice(after)}`;
 }
 
 /** The registry's text as `paperlint studies new` writes it: JSON, two-space indented, a final newline. */
@@ -466,6 +995,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 +1043,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\`, and for a measurement its \`mode\`.`;
+      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 +1121,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 +1148,7 @@ export function addStudy(
     status: "designing",
     date: n.date,
     in_paper: "no",
+    plan: PLAN_FILE,
   };
   return {
     ok: true,
@@ -589,6 +1170,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",