paperlint 10.3.0 → 10.4.0

package/src/domain/study-mode.ts

@@ -0,0 +1,78 @@
+/**
+ * A STUDY'S MODE — how its outcomes are kept from the decisions about its inputs. A measurement study
+ * declares exactly one (docs/design/study-modes.md):
+ *
+ *   decide_before_run   the default: the author's decisions on the inputs (exclusions, veto, the
+ *                       sample's approval) are committed BEFORE any output exists. No key, no extra
+ *                       tool: git's history is the proof of order, and
+ *                       `repro/outputs-before-decision` re-checks it on every lint.
+ *   exploratory         no gate: the study is exploratory and is reported as such, with its reason.
+ *
+ * "None" and "two at once" cannot be written: the plan holds one `mode`, a union on its `kind`, and a
+ * measurement study's plan is not ready without it (the parser, `src/adapters/study-registry/`).
+ *
+ * Paths: `outputs` are globs relative to the study's folder (the study's results live there); the
+ * decision's `file` is relative to the PAPER's folder, so a decision may live beside the study or
+ * anywhere in the paper (`research/decisions.md`). Pure.
+ */
+import { posix } from "node:path";
+import { REPRO_DIR } from "./repro-layout.ts";
+import type { StudyKind } from "./study-registry.ts";
+
+/** A decision recorded in a file: where, and what it decides. */
+export interface Decision {
+  /** Relative to the paper's folder. */
+  readonly file: string;
+  readonly note: string;
+}
+
+/** Decide first: the decision on the inputs is committed before any output exists. */
+export interface DecideFirst {
+  readonly kind: "decide_before_run";
+  /** Globs relative to the study's folder: the files the run produces. */
+  readonly outputs: readonly string[];
+  readonly decision: Decision;
+}
+
+/** Exploratory: no gate, and reported as exploratory. */
+export interface Exploratory {
+  readonly kind: "exploratory";
+  readonly reason: string;
+}
+
+export type StudyMode = DecideFirst | Exploratory;
+
+/**
+ * The kinds of study whose plan must declare a mode: the ones that measure. A spike, a tool, a data
+ * set, an artifact or a salvage may omit it.
+ */
+export const MODE_REQUIRED: readonly StudyKind[] = ["measurement"];
+
+/** Whether a study of `kind` must declare its mode. */
+export const needsMode = (kind: StudyKind): boolean =>
+  MODE_REQUIRED.includes(kind);
+
+/** `paperPath` relative to the study folder `folder`, when it lies inside it; else null. */
+export const inStudy = (folder: string, paperPath: string): string | null => {
+  const prefix = `${REPRO_DIR}/${folder}/`;
+  const n = posix.normalize(paperPath);
+  return n.startsWith(prefix) ? n.slice(prefix.length) : null;
+};
+
+/** Whether the file at `path` (relative to the study's folder) is one of `outputs`. */
+export const isOutput = (outputs: readonly string[], path: string): boolean =>
+  outputs.some((g) => posix.matchesGlob(path, g));
+
+/**
+ * The output glob that matches the study's own decision file, when the file lies in the study's
+ * folder: the decision would be "produced" by the run it gates.
+ */
+export const decisionAsOutput = (
+  folder: string,
+  m: DecideFirst,
+): string | null => {
+  const rel = inStudy(folder, m.decision.file);
+  return rel === null
+    ? null
+    : (m.outputs.find((g) => posix.matchesGlob(rel, g)) ?? null);
+};

package/src/domain/study-registry.test.ts

@@ -25,8 +25,12 @@ import {
   type Study,
   type StudyInput,
   type StudyRegistry,
+  type IndexInput,
 } from "./study-registry.ts";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const study = (over: Partial<Study> = {}): Study => ({
   id: "P1-S01",
   folder: "P1-S01-baseline",
@@ -56,7 +60,7 @@ const input = (
 ): StudyInput => ({
   folders: r.studies.map((s) => s.folder),
   registry: read(r),
-  readme: withIndex("# Reproduction index\n", r),
+  readme: withIndex("# Reproduction index\n", r, NO_FACTS),
   existingResults: new Set(),
   plans: new Map(),
   ...over,
@@ -310,16 +314,16 @@ describe("judgeStudies — the index", () => {
 
   it("a table prettier padded by display width, with wide characters, is in sync", async () => {
     const wide = reg(study({ title: "測定 A" }));
-    const readme = await format(withIndex("# index\n", wide), {
+    const readme = await format(withIndex("# index\n", wide, NO_FACTS), {
       parser: "markdown",
     });
-    expect(readme).not.toBe(withIndex("# index\n", wide));
+    expect(readme).not.toBe(withIndex("# index\n", wide, NO_FACTS));
     expect(judgeStudies(input(wide, { readme }))).toEqual([]);
   });
 
   it("a title with a backslash before a pipe stays one cell through prettier", async () => {
     const bs = reg(study({ title: "foo\\|bar" }));
-    const readme = await format(withIndex("# index\n", bs), {
+    const readme = await format(withIndex("# index\n", bs, NO_FACTS), {
       parser: "markdown",
     });
     expect(judgeStudies(input(bs, { readme }))).toEqual([]);
@@ -328,22 +332,25 @@ describe("judgeStudies — the index", () => {
 
   it("a title carrying the end marker's text: in sync, and regenerating changes nothing", () => {
     const m = reg(study({ title: `x ${INDEX_END} y` }));
-    const readme = withIndex("# index\n", m);
+    const readme = withIndex("# index\n", m, NO_FACTS);
     expect(judgeStudies(input(m, { readme }))).toEqual([]);
-    expect(withIndex(readme, m)).toBe(readme);
+    expect(withIndex(readme, m, NO_FACTS)).toBe(readme);
   });
 
   it("prose that mentions the begin marker is kept, and the real block is the one judged", () => {
     const r1 = reg(study());
     const prose = `# index\n\nThe table between \`${INDEX_BEGIN}\` and its end marker is generated.\n`;
-    const readme = withIndex(prose, r1);
+    const readme = withIndex(prose, r1, NO_FACTS);
     expect(judgeStudies(input(r1, { readme }))).toEqual([]);
-    expect(withIndex(readme, r1)).toBe(readme);
+    expect(withIndex(readme, r1, NO_FACTS)).toBe(readme);
     expect(readme.startsWith(prose.trimEnd())).toBe(true);
   });
 
   it("a block that differs from the registry by one character", () => {
-    const readme = withIndex("# index\n", r).replace("designing", "running");
+    const readme = withIndex("# index\n", r, NO_FACTS).replace(
+      "designing",
+      "running",
+    );
     expect(judgeStudies(input(r, { readme }))).toEqual([
       { problem: "stale-index", why: "differs" },
     ]);
@@ -363,12 +370,12 @@ describe("the index", () => {
         in_paper: "yes",
       }),
     );
-    expect(studyIndex(r)).toBe(
+    expect(studyIndex(r, NO_FACTS)).toBe(
       [
-        "| id     | title               | status    | result   | in paper | folder                               |",
-        "| ------ | ------------------- | --------- | -------- | -------- | ------------------------------------ |",
-        "| P1-S01 | Baseline pass rate  | designing | —        | no       | [P1-S01-baseline/](P1-S01-baseline/) |",
-        "| P1-S02 | Pipes \\| and breaks | done      | 41 of 60 | yes      | [P1-S02-a-b/](P1-S02-a-b/)           |",
+        "| id     | title               | status    | result   | in paper | mode | decision | first output | folder                               |",
+        "| ------ | ------------------- | --------- | -------- | -------- | ---- | -------- | ------------ | ------------------------------------ |",
+        "| P1-S01 | Baseline pass rate  | designing | —        | no       | —    | —        | —            | [P1-S01-baseline/](P1-S01-baseline/) |",
+        "| P1-S02 | Pipes \\| and breaks | done      | 41 of 60 | yes      | —    | —        | —            | [P1-S02-a-b/](P1-S02-a-b/)           |",
       ].join("\n"),
     );
   });
@@ -390,30 +397,30 @@ describe("the index", () => {
         }),
       ].slice(0, n),
     );
-    const md = withIndex("# Reproduction index\n\nSome text.\n", r);
+    const md = withIndex("# Reproduction index\n\nSome text.\n", r, NO_FACTS);
     expect(await format(md, { parser: "markdown" })).toBe(md);
   });
 });
 
 describe("the index of an empty registry, and its markers", () => {
   it("of an empty registry is the header alone", () => {
-    expect(studyIndex(reg())).toBe(
+    expect(studyIndex(reg(), NO_FACTS)).toBe(
       [
-        "| id  | title | status | result | in paper | folder |",
-        "| --- | ----- | ------ | ------ | -------- | ------ |",
+        "| id  | title | status | result | in paper | mode | decision | first output | folder |",
+        "| --- | ----- | ------ | ------ | -------- | ---- | -------- | ------------ | ------ |",
       ].join("\n"),
     );
   });
 
   it("sits between the two markers, a blank line on each side", () => {
-    expect(indexBlock(reg())).toBe(
-      `${INDEX_BEGIN}\n\n${studyIndex(reg())}\n\n${INDEX_END}`,
+    expect(indexBlock(reg(), NO_FACTS)).toBe(
+      `${INDEX_BEGIN}\n\n${studyIndex(reg(), NO_FACTS)}\n\n${INDEX_END}`,
     );
   });
 
   it("is read back from a README as the text between the markers, or null", () => {
-    expect(embeddedIndex(`# x\n\n${indexBlock(reg())}\n`)).toBe(
-      `\n\n${studyIndex(reg())}\n\n`,
+    expect(embeddedIndex(`# x\n\n${indexBlock(reg(), NO_FACTS)}\n`)).toBe(
+      `\n\n${studyIndex(reg(), NO_FACTS)}\n\n`,
     );
     expect(embeddedIndex("# x\n")).toBeNull();
     expect(embeddedIndex(`${INDEX_END}\n${INDEX_BEGIN}\n`)).toBeNull();
@@ -424,27 +431,27 @@ describe("withIndex", () => {
   const r = reg(study());
 
   it("replaces the block in place and keeps the rest", () => {
-    const before = `# Index\n\nintro\n\n${indexBlock(reg())}\n\ntail\n`;
-    expect(withIndex(before, r)).toBe(
-      `# Index\n\nintro\n\n${indexBlock(r)}\n\ntail\n`,
+    const before = `# Index\n\nintro\n\n${indexBlock(reg(), NO_FACTS)}\n\ntail\n`;
+    expect(withIndex(before, r, NO_FACTS)).toBe(
+      `# Index\n\nintro\n\n${indexBlock(r, NO_FACTS)}\n\ntail\n`,
     );
   });
 
   it("appends the block to a README without markers", () => {
-    expect(withIndex("# Index\n\nintro", r)).toBe(
-      `# Index\n\nintro\n\n${indexBlock(r)}\n`,
+    expect(withIndex("# Index\n\nintro", r, NO_FACTS)).toBe(
+      `# Index\n\nintro\n\n${indexBlock(r, NO_FACTS)}\n`,
     );
   });
 
   it("writes a README when there is none", () => {
-    expect(withIndex(null, r)).toBe(
-      `# Reproduction index\n\n${indexBlock(r)}\n`,
+    expect(withIndex(null, r, NO_FACTS)).toBe(
+      `# Reproduction index\n\n${indexBlock(r, NO_FACTS)}\n`,
     );
   });
 
   it("is a fixed point: a second run changes nothing", () => {
-    const once = withIndex("# Index\n", r);
-    expect(withIndex(once, r)).toBe(once);
+    const once = withIndex("# Index\n", r, NO_FACTS);
+    expect(withIndex(once, r, NO_FACTS)).toBe(once);
   });
 });
 

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 };
@@ -172,6 +182,11 @@ export interface StudyPlan {
   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;
 }
 
 /**
@@ -200,6 +215,7 @@ export const PLAN_FIELDS = [
   "primary_outcome",
   "author_check",
   "extra",
+  "mode",
 ] as const;
 
 /** A plan with empty required texts: the author has not approved it. */
@@ -211,6 +227,11 @@ export const PLAN_TEXT_FIELDS = [
   "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];
 
@@ -230,16 +251,34 @@ export type ParsedPlan =
 /** 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: 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" }`.
+ * 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 = (): DraftPlan => ({
+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. */
@@ -425,20 +464,40 @@ 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) ? [`${s.folder}/${s.plan}`] : [],
+    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. */
@@ -695,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" };
 }
@@ -718,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))
@@ -739,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;
 
@@ -764,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");
 }
 
@@ -786,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")
@@ -796,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
@@ -832,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. */
@@ -923,7 +1062,7 @@ const HEADS: { readonly [P in Problem]: (f: FindingOf[P]) => string } = {
       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\`.`;
+        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\`.`;
     }

package/src/new-paper.test.ts

@@ -42,9 +42,13 @@ import {
   registryText,
   withIndex,
   type StudyRegistry,
+  type IndexInput,
 } from "./domain/study-registry.ts";
 import { statSync } from "node:fs";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const dirs: string[] = [];
 afterEach(() => {
   for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
@@ -813,7 +817,7 @@ describe("paperlint lint — a scaffolded paper has no layout finding", () => {
       "talk/.gitkeep": "",
       "sections/.gitkeep": "",
       "repro/studies.json": registryText(SOME_STUDY),
-      "repro/README.md": withIndex(REPRO_INDEX_STUB, SOME_STUDY),
+      "repro/README.md": withIndex(REPRO_INDEX_STUB, SOME_STUDY, NO_FACTS),
       "repro/P1-S01-some-study/README.md": "# s\n",
       "repro/P1-S01-some-study/.gitkeep": "",
     });