paperlint 10.3.0 → 10.4.0

package/src/domain/decide-first.ts

@@ -0,0 +1,243 @@
+/**
+ * DECIDE FIRST — the default mode of a measurement study (src/domain/study-mode.ts): the author's
+ * decisions on the inputs are committed before any output exists, and git's history is the proof of
+ * order. `repro/outputs-before-decision` judges it here, from facts git gave (src/adapters/git/):
+ *
+ *   - each output in the tree or ever committed while the decision file was never committed;
+ *   - each output whose FIRST commit is not a strict descendant of the decision file's FIRST commit —
+ *     earlier, on a line of history the decision is not on, or in the very same commit (which says
+ *     nothing about which came first);
+ *   - a decision file the outputs match (it would be "produced" by the run it gates);
+ *   - a decision file committed and since deleted: it is not in HEAD, so there is no decision;
+ *   - a history that cannot be read: no git, or a shallow clone, whose every file starts at the clone.
+ *
+ * Outputs that were committed and later deleted count: an output that existed before the decision is
+ * evidence after it is gone. Pure.
+ */
+import { README } from "./repro-layout.ts";
+import {
+  decisionAsOutput,
+  inStudy,
+  isOutput,
+  type DecideFirst,
+} from "./study-mode.ts";
+
+/** What a decision path names on disk when it is no file git can vouch for. */
+export type NotAFile = "directory" | "symbolic link";
+
+/** A commit, and its committer date (ISO 8601 with its offset). */
+export interface CommitAt {
+  readonly commit: string;
+  readonly date: string;
+}
+
+/** Where a file's first commit stands against the decision's first commit. */
+export type Order =
+  /** A strict descendant: the file entered history after the decision. */
+  | "after"
+  /** The same commit: nothing in history says which came first. */
+  | "same"
+  /** Not a descendant: earlier, or on a line of history the decision is not on — or no decision. */
+  | "not-after";
+
+/** The first commit of a file under the study's folder, and its order against the decision. */
+export interface FirstCommit extends CommitAt {
+  /** Relative to the study's folder. */
+  readonly path: string;
+  readonly order: Order;
+}
+
+/**
+ * What git's history says of a decide-first study: when its decision file entered history, and when
+ * every file ever committed under the study's folder did — or, when the decision names a directory,
+ * that history was not asked (git answers for a directory with the commits of anything under it).
+ */
+export type OrderFacts =
+  | { readonly kind: "not-a-file"; readonly what: NotAFile }
+  | { readonly kind: "unknown"; readonly why: string }
+  /** A shallow clone: every file's first commit is the clone's first, so no order can be read. */
+  | { readonly kind: "shallow" }
+  | {
+      readonly kind: "read";
+      /** null: the decision file was never committed. */
+      readonly decision: CommitAt | null;
+      /** The decision was committed, then deleted: it is not in HEAD. */
+      readonly decisionDeleted: boolean;
+      readonly files: readonly FirstCommit[];
+    };
+
+/** What the judge reads of one decide-first study. */
+export interface DecideFirstStudy {
+  readonly id: string;
+  readonly folder: string;
+  /** The plan's path in the folder. */
+  readonly plan: string;
+  readonly mode: DecideFirst;
+  /** Every file under the study's folder now, relative to it. */
+  readonly tree: readonly string[];
+  readonly facts: OrderFacts;
+}
+
+/** One defect `repro/outputs-before-decision` reports. */
+export type OrderFinding =
+  | {
+      readonly problem: "decision-is-output";
+      readonly id: string;
+      readonly file: string;
+      readonly glob: string;
+    }
+  | {
+      readonly problem: "decision-deleted";
+      readonly id: string;
+      readonly file: string;
+    }
+  | {
+      readonly problem: "decision-not-file";
+      readonly id: string;
+      readonly file: string;
+      readonly what: NotAFile;
+    }
+  | {
+      readonly problem: "no-history";
+      readonly id: string;
+      readonly why: string;
+    }
+  | { readonly problem: "shallow"; readonly id: string }
+  | {
+      readonly problem: "undecided-output";
+      readonly id: string;
+      readonly folder: string;
+      readonly path: string;
+      readonly decision: string;
+    }
+  | {
+      readonly problem: "output-before-decision";
+      readonly id: string;
+      readonly folder: string;
+      readonly path: string;
+      readonly output: CommitAt;
+      readonly decision: CommitAt;
+      readonly same: boolean;
+    };
+
+/** Whether `path` (relative to the study's folder) is an output and none of the study's own files. */
+const outputOf =
+  (s: DecideFirstStudy) =>
+  (path: string): boolean =>
+    ![README, s.plan, inStudy(s.folder, s.mode.decision.file)].includes(path) &&
+    isOutput(s.mode.outputs, path);
+
+/** The files of a read history that are outputs of the study, oldest first commit first. */
+export const outputCommits = (
+  s: DecideFirstStudy,
+  files: readonly FirstCommit[],
+): readonly FirstCommit[] => files.filter((f) => outputOf(s)(f.path));
+
+/** The findings of a history that was read. */
+const ordered = (
+  s: DecideFirstStudy,
+  decision: CommitAt | null,
+  files: readonly FirstCommit[],
+): readonly OrderFinding[] => {
+  const isOut = outputOf(s);
+  const at = { id: s.id, folder: s.folder };
+  if (decision === null)
+    // The tree's outputs, then those only history holds: deleting an output does not erase it.
+    return [...new Set([...s.tree, ...files.map((f) => f.path)])]
+      .filter(isOut)
+      .map((path) => ({
+        problem: "undecided-output",
+        ...at,
+        path,
+        decision: s.mode.decision.file,
+      }));
+  return files
+    .filter((f) => isOut(f.path) && f.order !== "after")
+    .map((f) => ({
+      problem: "output-before-decision",
+      ...at,
+      path: f.path,
+      output: { commit: f.commit, date: f.date },
+      decision,
+      same: f.order === "same",
+    }));
+};
+
+/** Every defect of a decide-first study, in a fixed order: the plan's, then the history's. */
+export const judgeOrder = (s: DecideFirstStudy): readonly OrderFinding[] => {
+  const glob = decisionAsOutput(s.folder, s.mode);
+  const clash: readonly OrderFinding[] =
+    glob === null
+      ? []
+      : [
+          {
+            problem: "decision-is-output",
+            id: s.id,
+            file: s.mode.decision.file,
+            glob,
+          },
+        ];
+  return [...clash, ...historyFindings(s)];
+};
+
+/** The findings of a decide-first study's history, whatever git could say of it. */
+const historyFindings = (s: DecideFirstStudy): readonly OrderFinding[] => {
+  const file = s.mode.decision.file;
+  switch (s.facts.kind) {
+    case "not-a-file":
+      return [
+        { problem: "decision-not-file", id: s.id, file, what: s.facts.what },
+      ];
+    case "unknown":
+      return [{ problem: "no-history", id: s.id, why: s.facts.why }];
+    case "shallow":
+      return [{ problem: "shallow", id: s.id }];
+    case "read":
+      // A decision deleted since is no decision: the order is not judged against it.
+      return s.facts.decisionDeleted
+        ? [{ problem: "decision-deleted", id: s.id, file }]
+        : ordered(s, s.facts.decision, s.facts.files);
+  }
+};
+
+const RULE = "repro/outputs-before-decision";
+
+/** Each finding by its problem. */
+type FindingOf = {
+  readonly [F in OrderFinding as F["problem"]]: F;
+};
+
+/** Why git's history says nothing of a decision that is not a file. */
+const NOT_A_FILE: Readonly<Record<NotAFile, string>> = {
+  directory:
+    "git answers for a directory with the commits of anything under it",
+  "symbolic link": "git records the link, not the file it points to",
+};
+
+const short = (c: CommitAt): string => `${c.commit.slice(0, 12)} (${c.date})`;
+
+const HEADS: {
+  readonly [P in keyof FindingOf]: (f: FindingOf[P]) => string;
+} = {
+  "decision-is-output": (f) =>
+    `The decision of \`${f.id}\`, \`${f.file}\`, is matched by its output \`${f.glob}\`: the decision would be one of the files its own run produces. What to do: keep the decision out of the outputs — a file the globs do not match, or one elsewhere in the paper — and set \`mode.decision.file\`.`,
+  "decision-deleted": (f) =>
+    `The decision of \`${f.id}\`, \`${f.file}\`, was committed and then deleted: it is not in HEAD, so the study has no decision its outputs could follow. What to do: restore the decision file as it was decided and commit it — never write a new one after the outputs; if the decision no longer holds, declare the study \`exploratory\` with the reason.`,
+  "decision-not-file": (f) =>
+    `The decision of \`${f.id}\`, \`${f.file}\`, is a ${f.what}, not a file: ${NOT_A_FILE[f.what]}, so no order can be read from it. What to do: name the decision file itself in \`mode.decision.file\`.`,
+  "no-history": (f) =>
+    `\`${f.id}\` is decided before its run, and git's history is the proof of that order, but git could not answer: ${f.why}. What to do: lint the paper inside its git repository, with git installed.`,
+  shallow: (f) =>
+    `\`${f.id}\` is decided before its run, and this clone is shallow: every file's first commit is the clone's first, so the order of decision and outputs cannot be read. What to do: fetch the whole history (\`git fetch --unshallow\`; in GitHub Actions, \`actions/checkout\` with \`fetch-depth: 0\`).`,
+  "undecided-output": (f) =>
+    `\`repro/${f.folder}/${f.path}\` is an output of \`${f.id}\` — in the tree, or in its history — and the study is decided before its run, but its decision \`${f.decision}\` was never committed. What to do: write and commit the decision, check it with \`npx paperlint studies gate <paper-dir> ${f.id}\`, then run the study again; if the output was made before any decision, declare the study \`exploratory\` with the reason. Deleting the output does not undo it: history keeps it.`,
+  "output-before-decision": (f) =>
+    `\`repro/${f.folder}/${f.path}\`, an output of \`${f.id}\`, entered history in ${short(f.output)}, ${f.same ? "the very commit" : "not after the commit"} that first recorded its decision, ${short(f.decision)}. The study is declared decided before its run, and its history does not show that order. What to do: if the decision really came first, nothing in this history can prove it — declare the study \`exploratory\` with the reason, or run it again after the decision; never rewrite the history to make it pass.`,
+};
+
+const headOf = <P extends keyof FindingOf>(p: P, f: FindingOf[P]): string =>
+  HEADS[p](f);
+
+/** The one text a finding is reported with: what is wrong, what to do, and the rule's page. */
+export const orderMessage = (f: OrderFinding): string =>
+  `${headOf(f.problem, f)}\nRule ${RULE}: https://github.com/zernie/paperlint/blob/main/docs/rules/${RULE}.md`;

package/src/domain/index-columns.test.ts

@@ -0,0 +1,216 @@
+/**
+ * The index's mode columns (`src/domain/index-columns.ts`) and the table that carries them
+ * (`studyIndex`, `indexInSync`, `indexCurrent` in `src/domain/study-registry.ts`): the mode from the
+ * plan, the decision's and the first output's commits from git's history, and the two git columns
+ * left out of what the lint compares.
+ */
+import { describe, expect, it } from "vitest";
+import type { DecideFirstStudy } from "./decide-first.ts";
+import { decisionCell, indexHistory } from "./index-columns.ts";
+import type { DecideFirst } from "./study-mode.ts";
+import {
+  indexCurrent,
+  indexInSync,
+  studyIndex,
+  withIndex,
+  type IndexInput,
+  type PlanState,
+  type Study,
+  type StudyPlan,
+  type StudyRegistry,
+} from "./study-registry.ts";
+
+const D = { commit: "d".repeat(40), date: "2026-10-14T09:12:00+05:00" };
+const A = { commit: "a".repeat(40), date: "2026-10-16T11:00:00+05:00" };
+
+const DECIDED: DecideFirst = {
+  kind: "decide_before_run",
+  outputs: ["RESULTS.md"],
+  decision: { file: "repro/P1-S01-hint/decision.md", note: "exclusions" },
+};
+
+const plan = (mode: StudyPlan["mode"]): PlanState => ({
+  kind: "ready",
+  plan: {
+    question: "q?",
+    population: { source: "s", draw: { kind: "all", method: "census" } },
+    arms: [],
+    primary_outcome: "o",
+    author_check: null,
+    mode,
+  },
+});
+
+const row = (n: number, over: Partial<Study> = {}): Study => ({
+  id: `P1-S0${String(n)}`,
+  folder: `P1-S0${String(n)}-s`,
+  title: `S${String(n)}`,
+  question: "q?",
+  kind: "measurement",
+  status: "running",
+  date: "2026-10-15",
+  in_paper: "no",
+  plan: "plan.json",
+  ...over,
+});
+
+/** Nine studies, one per state a mode cell can be in. */
+const NINE: StudyRegistry = {
+  prefix: "P1",
+  studies: [
+    row(1, { folder: "P1-S01-hint" }),
+    row(2),
+    row(3),
+    row(4),
+    row(5),
+    row(6, { kind: "spike", plan: undefined }),
+    row(7, { plan: "../plan.json" }),
+    row(8),
+    row(9),
+  ],
+};
+/** Their plans and histories. */
+const NINE_AT: IndexInput = {
+  plans: new Map<string, PlanState>([
+    ["P1-S01-hint/plan.json", plan(DECIDED)],
+    ["P1-S02-s/plan.json", plan(DECIDED)],
+    ["P1-S03-s/plan.json", plan({ kind: "exploratory", reason: "a | look" })],
+    ["P1-S04-s/plan.json", plan(DECIDED)],
+    ["P1-S05-s/plan.json", plan(DECIDED)],
+    ["P1-S08-s/plan.json", { kind: "unreadable", why: "not JSON" }],
+    ["P1-S09-s/plan.json", plan(undefined)],
+  ]),
+  history: new Map([
+    [
+      "P1-S01",
+      { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
+    ],
+    [
+      "P1-S02",
+      {
+        kind: "read",
+        decision: null,
+        decisionDeleted: false,
+        firstOutput: null,
+      },
+    ],
+    ["P1-S04", { kind: "unread", why: "shallow clone" }],
+  ]),
+};
+
+describe("the mode columns of the index", () => {
+  it("say each study's mode and, for one decided before its run, its two commits", () => {
+    // Guards: the sample row a reader and the review skills read — decided before the run, the
+    // decision's first commit and date, the first output's — and every other state its own words.
+    expect(studyIndex(NINE, NINE_AT).split("\n").slice(2)).toEqual([
+      "| P1-S01 | S1    | running | —      | no       | decide_before_run      | dddddddddddd 2026-10-14 | aaaaaaaaaaaa 2026-10-16 | [P1-S01-hint/](P1-S01-hint/) |",
+      "| P1-S02 | S2    | running | —      | no       | decide_before_run      | not committed           | none                    | [P1-S02-s/](P1-S02-s/)       |",
+      "| P1-S03 | S3    | running | —      | no       | exploratory: a \\| look | —                       | —                       | [P1-S03-s/](P1-S03-s/)       |",
+      "| P1-S04 | S4    | running | —      | no       | decide_before_run      | unknown (shallow clone) | unknown (shallow clone) | [P1-S04-s/](P1-S04-s/)       |",
+      "| P1-S05 | S5    | running | —      | no       | decide_before_run      | not read                | not read                | [P1-S05-s/](P1-S05-s/)       |",
+      "| P1-S06 | S6    | running | —      | no       | —                      | —                       | —                       | [P1-S06-s/](P1-S06-s/)       |",
+      "| P1-S07 | S7    | running | —      | no       | —                      | —                       | —                       | [P1-S07-s/](P1-S07-s/)       |",
+      "| P1-S08 | S8    | running | —      | no       | —                      | —                       | —                       | [P1-S08-s/](P1-S08-s/)       |",
+      "| P1-S09 | S9    | running | —      | no       | —                      | —                       | —                       | [P1-S09-s/](P1-S09-s/)       |",
+    ]);
+  });
+
+  it("the lint compares the mode, never the two commits; `studies index` rewrites on either", () => {
+    const r: StudyRegistry = { prefix: "P1", studies: [row(1)] };
+    const plans = new Map([["P1-S01-s/plan.json", plan(DECIDED)]]);
+    const was: IndexInput = { plans, history: new Map() };
+    const readme = withIndex("# index\n", r, was);
+    const committed: IndexInput = {
+      plans,
+      history: new Map([
+        [
+          "P1-S01",
+          {
+            kind: "read",
+            decision: D,
+            decisionDeleted: false,
+            firstOutput: null,
+          },
+        ],
+      ]),
+    };
+    const explored: IndexInput = {
+      plans: new Map([
+        ["P1-S01-s/plan.json", plan({ kind: "exploratory", reason: "r" })],
+      ]),
+      history: new Map(),
+    };
+    // Guards: a squash merge renames the commits, so the lint cannot hold them; the command can.
+    expect([
+      indexInSync(readme, r, committed),
+      indexCurrent(readme, r, committed),
+      indexInSync(readme, r, explored),
+      indexCurrent(readme, r, was),
+      indexCurrent(null, r, was),
+    ]).toEqual([true, false, false, true, false]);
+  });
+});
+
+it("a decision committed and since deleted shows its commit, and that it is gone", () => {
+  // Guards: the Methods sentence must not cite a decision that no longer stands.
+  expect(
+    decisionCell({
+      mode: DECIDED,
+      history: {
+        kind: "read",
+        decision: D,
+        decisionDeleted: true,
+        firstOutput: null,
+      },
+    }),
+  ).toBe("dddddddddddd 2026-10-14, deleted since");
+});
+
+describe("indexHistory", () => {
+  const study = (facts: DecideFirstStudy["facts"]): DecideFirstStudy => ({
+    id: "P1-S01",
+    folder: "P1-S01-hint",
+    plan: "plan.json",
+    mode: DECIDED,
+    tree: [],
+    facts,
+  });
+
+  it("is the decision's first commit and the oldest output's, or what kept git from saying", () => {
+    expect([
+      indexHistory(study({ kind: "unknown", why: "not a repository" })),
+      indexHistory(study({ kind: "shallow" })),
+      indexHistory(study({ kind: "not-a-file", what: "directory" })),
+      indexHistory(
+        study({
+          kind: "read",
+          decision: D,
+          decisionDeleted: false,
+          files: [
+            { path: "decision.md", ...D, order: "same" },
+            { path: "RESULTS.md", ...A, order: "after" },
+          ],
+        }),
+      ),
+      indexHistory(
+        study({
+          kind: "read",
+          decision: null,
+          decisionDeleted: false,
+          files: [],
+        }),
+      ),
+    ]).toEqual([
+      { kind: "unread", why: "git could not answer" },
+      { kind: "unread", why: "shallow clone" },
+      { kind: "unread", why: "the decision is a directory" },
+      { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
+      {
+        kind: "read",
+        decision: null,
+        decisionDeleted: false,
+        firstOutput: null,
+      },
+    ]);
+  });
+});

package/src/domain/index-columns.ts

@@ -0,0 +1,105 @@
+/**
+ * THE MODE COLUMNS OF THE INDEX — three columns of `repro/README.md`'s study index beyond the row:
+ * the study's mode, as its plan declares it, and for a study decided before its run the commit that
+ * first recorded its decision and the commit that first recorded an output (docs/design/study-modes.md).
+ *
+ * The mode comes from the plan, which is in the tree, so `repro/study-registered` compares it. The
+ * two commits come from git's history as `paperlint studies index` read it when it ran: a squash merge
+ * or a rebase gives the same files new commits, and a shallow CI clone has none to read, so the lint
+ * never compares those two columns. `repro/outputs-before-decision` judges the order itself. Pure.
+ */
+import {
+  outputCommits,
+  type CommitAt,
+  type DecideFirstStudy,
+} from "./decide-first.ts";
+import type { StudyMode } from "./study-mode.ts";
+
+/** What git's history says of a decide-first study's decision and outputs. */
+export type IndexHistory =
+  /** No order could be read: why, in a few words (`shallow clone`). */
+  | { readonly kind: "unread"; readonly why: string }
+  | {
+      readonly kind: "read";
+      /** The decision file's first commit; null: never committed. */
+      readonly decision: CommitAt | null;
+      /** The decision was committed, then deleted: it is not in HEAD. */
+      readonly decisionDeleted: boolean;
+      /** The first commit of the oldest output; null: no output was ever committed. */
+      readonly firstOutput: CommitAt | null;
+    };
+
+/** What the index shows of a study beyond its row. */
+export interface IndexFacts {
+  /** The mode its plan declares; null when its plan declares none, or there is no plan to read. */
+  readonly mode: StudyMode | null;
+  /** For a decide-first study, its history; null when it was not asked (the lint does not ask). */
+  readonly history: IndexHistory | null;
+}
+
+/** The cell of a column that does not apply to a study. */
+export const NOT_APPLICABLE = "—";
+
+/** A commit as a cell: its first twelve characters, and its date. */
+const commitCell = (c: CommitAt): string =>
+  `${c.commit.slice(0, 12)} ${c.date.slice(0, 10)}`;
+
+/** The mode cell: `decide_before_run`, `exploratory: <reason>`, or `—`. */
+export const modeCell = (f: IndexFacts): string => {
+  if (f.mode === null) return NOT_APPLICABLE;
+  return f.mode.kind === "exploratory"
+    ? `exploratory: ${f.mode.reason}`
+    : f.mode.kind;
+};
+
+/** A history cell of a decide-first study: the text `pick` makes of it, `absent` when it makes none. */
+const historyCell =
+  (
+    pick: (h: IndexHistory & { readonly kind: "read" }) => string | null,
+    absent: string,
+  ) =>
+  (f: IndexFacts): string => {
+    if (f.mode?.kind !== "decide_before_run") return NOT_APPLICABLE;
+    if (f.history === null) return "not read";
+    if (f.history.kind === "unread") return `unknown (${f.history.why})`;
+    return pick(f.history) ?? absent;
+  };
+
+/** The decision cell: its first commit and date (`, deleted since` when it is not in HEAD), or `not committed`. */
+export const decisionCell = historyCell(
+  (h) =>
+    h.decision === null
+      ? null
+      : `${commitCell(h.decision)}${h.decisionDeleted ? ", deleted since" : ""}`,
+  "not committed",
+);
+
+/** The first-output cell: the commit and date of the first output, or `none`. */
+export const firstOutputCell = historyCell(
+  (h) => (h.firstOutput === null ? null : commitCell(h.firstOutput)),
+  "none",
+);
+
+/** The history the index shows of a decide-first study, from the facts git gave. */
+export const indexHistory = (s: DecideFirstStudy): IndexHistory => {
+  switch (s.facts.kind) {
+    case "not-a-file":
+      return { kind: "unread", why: `the decision is a ${s.facts.what}` };
+    case "unknown":
+      return { kind: "unread", why: "git could not answer" };
+    case "shallow":
+      return { kind: "unread", why: "shallow clone" };
+    case "read": {
+      const [first] = outputCommits(s, s.facts.files);
+      return {
+        kind: "read",
+        decision: s.facts.decision,
+        decisionDeleted: s.facts.decisionDeleted,
+        firstOutput:
+          first === undefined
+            ? null
+            : { commit: first.commit, date: first.date },
+      };
+    }
+  }
+};

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

@@ -21,8 +21,12 @@ import {
   type StudyInput,
   type StudyPlan,
   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-census",
@@ -105,7 +109,7 @@ const input = (
 ): StudyInput => ({
   folders: r.studies.map((s) => s.folder),
   registry: { kind: "read", registry: r },
-  readme: withIndex("# Reproduction index\n", r),
+  readme: withIndex("# Reproduction index\n", r, NO_FACTS),
   existingResults: new Set(),
   plans: new Map(
     r.studies.flatMap((s) =>
@@ -158,7 +162,7 @@ describe("measurements and plans — silent", () => {
       ],
     });
     const plans = new Map([
-      [`P1-S01-census/${PLAN_FILE}`, draft(planTemplate())],
+      [`P1-S01-census/${PLAN_FILE}`, draft(planTemplate("spike", "x"))],
     ]);
     expect(findings(r, { plans })).toEqual([]);
   });
@@ -325,7 +329,7 @@ describe("plans — filled once the study has run, and named plan.json", () => {
       measurements: [],
     });
     const plans = new Map([
-      [`P1-S01-census/${PLAN_FILE}`, draft(planTemplate())],
+      [`P1-S01-census/${PLAN_FILE}`, draft(planTemplate("spike", "x"))],
     ]);
     expect(findings(r, { plans })).toEqual([
       { problem: "no-result", id: "P1-S01", missing: ["result_file"] },
@@ -460,7 +464,7 @@ describe("planKeys", () => {
 
 describe("planTemplate and planText", () => {
   it("every field present, its value to fill, and author_check null", () => {
-    expect(planTemplate()).toEqual({
+    expect(planTemplate("spike", "x")).toEqual({
       question: "",
       population: { source: "", draw: { kind: "all", method: "" } },
       arms: [],
@@ -532,7 +536,7 @@ const MESSAGES = [
       why: "unreadable",
       reasons: "question: required",
     },
-    "The plan of `P1-S01`, `plan.json` in its folder, is not a study plan: question: required. What to do: give it the fields on the rule's page — `question`, `population`, `arms`, `primary_outcome`.",
+    "The plan of `P1-S01`, `plan.json` in its folder, is not a study plan: question: required. What to do: give it the fields on the rule's page — `question`, `population`, `arms`, `primary_outcome`, and for a measurement its `mode`.",
   ],
   [
     {

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

@@ -0,0 +1,55 @@
+/**
+ * A study's mode (`src/domain/study-mode.ts`): which kinds must declare one, where a decision lies
+ * relative to the study, and when a decision would be one of the study's own outputs.
+ */
+import { expect, it } from "vitest";
+import {
+  decisionAsOutput,
+  inStudy,
+  needsMode,
+  type DecideFirst,
+} from "./study-mode.ts";
+
+const DECIDED: DecideFirst = {
+  kind: "decide_before_run",
+  outputs: ["**/*.md"],
+  decision: { file: "repro/S1-x/decision.md", note: "n" },
+};
+
+it("only a measurement must declare its mode", () => {
+  // Guards: a spike and the other kinds may omit it.
+  expect(
+    (
+      [
+        "measurement",
+        "spike",
+        "tooling",
+        "data",
+        "artifact",
+        "salvage",
+      ] as const
+    ).map(needsMode),
+  ).toEqual([true, false, false, false, false, false]);
+});
+
+it("a paper-relative path inside the study's folder, normalised; outside it, none", () => {
+  // Guards: `./` and `x/../` spellings land where they point; another folder is not this study's.
+  expect([
+    inStudy("S1-x", "repro/S1-x/a/b.md"),
+    inStudy("S1-x", "./repro/S1-x/z/../c.md"),
+    inStudy("S1-x", "repro/S1-xy/c.md"),
+    inStudy("S1-x", "research/d.md"),
+  ]).toEqual(["a/b.md", "c.md", null, null]);
+});
+
+it("the output glob that would swallow the decision; none when it lies elsewhere or no glob matches", () => {
+  // Guards: a decision in the folder that an output matches is named by the glob; one elsewhere is not.
+  expect([
+    decisionAsOutput("S1-x", DECIDED),
+    decisionAsOutput("S1-x", { ...DECIDED, outputs: ["out/**"] }),
+    decisionAsOutput("S1-x", {
+      ...DECIDED,
+      decision: { file: "research/d.md", note: "n" },
+    }),
+  ]).toEqual(["**/*.md", null, null]);
+});