paperlint 10.3.0 → 10.4.1

package/src/adapters/memory/index.ts

@@ -6,6 +6,7 @@ import { absolutePath } from "../../domain/paths.ts";
 import type { Download } from "../../ports/download.ts";
 import type { Files } from "../../ports/files.ts";
 import type { ListDir } from "../../ports/talk-media.ts";
+import type { ListEntries } from "../../ports/list-entries.ts";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
 import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
 import { err, ok } from "../../domain/result.ts";
@@ -72,6 +73,18 @@ export const memoryListDir =
     ),
   ];
 
+/**
+ * `ListEntries` over `memoryFiles`: each name directly under a directory, a file when it is one, else a
+ * directory. Memory holds no links: the walk's refusal to follow one is the node adapter's to show.
+ */
+export const memoryListEntries =
+  (files: MemoryFiles): ListEntries =>
+  (dir) =>
+    memoryListDir(files)(dir).map((name) => ({
+      name,
+      kind: files.isFile(absolutePath(`${dir}/${name}`)) ? "file" : "dir",
+    }));
+
 export interface MemoryWorkspace extends Workspace {
   /** Every file written into a scratch directory, in order. */
   readonly written: {

package/src/adapters/node/index.ts

@@ -35,3 +35,4 @@ export { nodeFiles } from "./files.io.ts";
 export { spawnProcess, type SpawnSync } from "./process.io.ts";
 export { hostDirs } from "./host.io.ts";
 export { nodeListDir } from "./list-dir.io.ts";
+export { nodeListEntries } from "./list-entries.io.ts";

package/src/adapters/node/list-entries.io.ts

@@ -0,0 +1,27 @@
+/** `ListEntries` over `node:fs`: `readdir` with its file types, which `lstat` each entry, never following a link. */
+import { readdirSync, type Dirent } from "node:fs";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import { codeOf } from "../../domain/text.ts";
+import type { DirEntry, ListEntries } from "../../ports/list-entries.ts";
+
+/** What a directory entry is, its link never followed. */
+const kindOf = (d: Readonly<Dirent>): DirEntry["kind"] => {
+  if (d.isSymbolicLink()) return "symlink";
+  if (d.isDirectory()) return "dir";
+  return d.isFile() ? "file" : "other";
+};
+
+export const nodeListEntries: ListEntries = (
+  dir: AbsolutePath,
+): readonly DirEntry[] => {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).map((d) => ({
+      name: d.name,
+      kind: kindOf(d),
+    }));
+  } catch (e) {
+    const code = codeOf(e);
+    if (code === "ENOENT" || code === "ENOTDIR") return [];
+    throw e;
+  }
+};

package/src/adapters/node/list-entries.test.ts

@@ -0,0 +1,61 @@
+/**
+ * `nodeListEntries`: a directory's entries with their kinds, a symbolic link reported as one and never
+ * followed; none for a missing directory or a file; other errors thrown.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { absolutePath } from "../../domain/paths.ts";
+import { useTempDir } from "../../../test/support.ts";
+import { nodeListEntries } from "./list-entries.io.ts";
+
+const root = useTempDir("paperlint-list-entries-");
+
+const sorted = (dir: string) =>
+  [...nodeListEntries(absolutePath(dir))].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+
+describe("nodeListEntries", () => {
+  it("names each entry's kind, a link to a directory as a link", () => {
+    const d = join(root, "study");
+    mkdirSync(join(d, "out"), { recursive: true });
+    writeFileSync(join(d, "a.md"), "");
+    symlinkSync(".", join(d, "loop"));
+    expect(sorted(d)).toEqual([
+      { name: "a.md", kind: "file" },
+      { name: "loop", kind: "symlink" },
+      { name: "out", kind: "dir" },
+    ]);
+  });
+
+  // A FIFO needs `mkfifo`, which Windows does not have; the reason is said, not hidden.
+  it.skipIf(process.platform === "win32")(
+    "names a FIFO as neither a file nor a directory: other",
+    () => {
+      const d = join(root, "fifo");
+      mkdirSync(d, { recursive: true });
+      const made = spawnSync("mkfifo", [join(d, "pipe")]);
+      expect(made.status).toBe(0);
+      writeFileSync(join(d, "a.md"), "");
+      // Guards: it was reported as a file, so a reader would open it and block.
+      expect(sorted(d)).toEqual([
+        { name: "a.md", kind: "file" },
+        { name: "pipe", kind: "other" },
+      ]);
+    },
+  );
+
+  it("is empty for a directory that does not exist, and for a file", () => {
+    writeFileSync(join(root, "f"), "");
+    expect([
+      nodeListEntries(absolutePath(join(root, "none"))),
+      nodeListEntries(absolutePath(join(root, "f"))),
+    ]).toEqual([[], []]);
+  });
+
+  it("throws any other error", () => {
+    expect(() => nodeListEntries(absolutePath(`${root}/a\0b`))).toThrow();
+  });
+});

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

@@ -240,7 +240,7 @@ const planWith = (over: Readonly<Record<string, unknown>>): string =>
 
 describe("parsing a study's plan: ready or draft", () => {
   it("a filled plan is ready, its `extra` kept as it is", () => {
-    expect(parsePlan(JSON.stringify(PLAN))).toEqual({
+    expect(parsePlan(JSON.stringify(PLAN), "spike")).toEqual({
       kind: "ready",
       plan: PLAN,
     });
@@ -255,17 +255,20 @@ describe("parsing a study's plan: ready or draft", () => {
       },
       arms: [],
     };
-    expect(parsePlan(JSON.stringify(census))).toEqual({
+    expect(parsePlan(JSON.stringify(census), "spike")).toEqual({
       kind: "ready",
       plan: census,
     });
   });
 
   it("the template studies new writes is a draft of a census, naming every empty text", () => {
-    expect(planTemplate().population.draw).toEqual({ kind: "all", method: "" });
-    expect(parsePlan(planText(planTemplate()))).toEqual({
+    expect(planTemplate("spike", "x").population.draw).toEqual({
+      kind: "all",
+      method: "",
+    });
+    expect(parsePlan(planText(planTemplate("spike", "x")), "spike")).toEqual({
       kind: "draft",
-      plan: planTemplate(),
+      plan: planTemplate("spike", "x"),
       empty: [
         "question",
         "population.source",
@@ -277,7 +280,7 @@ describe("parsing a study's plan: ready or draft", () => {
 
   it("a text of white space only is empty", () => {
     const plan = { ...PLAN, primary_outcome: "  ", author_check: null };
-    expect(parsePlan(JSON.stringify(plan))).toEqual({
+    expect(parsePlan(JSON.stringify(plan), "spike")).toEqual({
       kind: "draft",
       plan,
       empty: ["primary_outcome"],
@@ -330,7 +333,7 @@ describe("parsing a study's plan: no contradictory state", () => {
       "population.draw.kind: Invalid discriminator value. Expected 'seeded' | 'all'",
     ],
   ])("refuses %s", (_why, t, why) => {
-    expect(parsePlan(t)).toEqual({ kind: "unreadable", why });
+    expect(parsePlan(t, "spike")).toEqual({ kind: "unreadable", why });
   });
 });
 
@@ -352,7 +355,7 @@ describe("parsing a study's plan: no name or fact said twice", () => {
       'population: Unrecognized key: "size"',
     ],
   ])("refuses %s", (_why, t, why) => {
-    expect(parsePlan(t)).toEqual({ kind: "unreadable", why });
+    expect(parsePlan(t, "spike")).toEqual({ kind: "unreadable", why });
   });
 });
 
@@ -395,7 +398,7 @@ describe("parsing a study's plan: strict at every level", () => {
       'arms.0: Unrecognized key: "model"',
     ],
   ])("refuses %s", (_why, t, why) => {
-    expect(parsePlan(t)).toEqual({ kind: "unreadable", why });
+    expect(parsePlan(t, "spike")).toEqual({ kind: "unreadable", why });
   });
 });
 

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

@@ -12,8 +12,13 @@
  * Its texts may be empty — the template's are — and the parser says which: a plan comes out ready or
  * a draft naming its empty texts, so nothing downstream looks at a text again. A plan still named
  * `prereg.json` has a loose schema of its own.
+ *
+ * A plan's `mode` (docs/design/study-modes.md) is parsed here too, strictly, a union on its `kind`:
+ * one mode at most, a glob that leaves the study's folder or a decision outside the paper refused,
+ * and a measurement's plan ready only with a mode.
  */
 import { z } from "zod";
+import { README } from "../../domain/repro-layout.ts";
 import {
   IN_PAPER,
   MEASUREMENT_ROLES,
@@ -29,9 +34,16 @@ import {
   type ParsedRegistry,
   type Requirement,
   type Study,
+  type PlanTextField,
+  type StudyKind,
   type StudyPlan,
   type StudyRegistry,
 } from "../../domain/study-registry.ts";
+import {
+  needsMode,
+  type Decision,
+  type StudyMode,
+} from "../../domain/study-mode.ts";
 import type { StudyRegistryCodec } from "../../ports/study-registry-codec.ts";
 
 const study = z.looseObject({
@@ -128,6 +140,66 @@ const extra = z.record(z.string(), z.unknown()).superRefine((e, ctx) => {
     });
 });
 
+/** Every value of `values` once: a repeat is an error naming it. */
+const once =
+  (what: string) =>
+  (values: readonly string[], ctx: Readonly<z.core.$RefinementCtx>): void => {
+    repeated(values).forEach((v) => {
+      ctx.addIssue({
+        code: "custom",
+        message: `${what} «${v}» is listed more than once`,
+      });
+    });
+  };
+
+/** Whether `p` is a relative path that stays where it starts: no backslash, not absolute, no `..`. */
+const staysInside = (p: string): boolean =>
+  !p.includes("\\") && !p.startsWith("/") && !p.split("/").includes("..");
+
+/** An output glob, relative to the study's folder: inside it, and never the study's README. */
+const inFolder = z
+  .string()
+  .min(1)
+  .refine(
+    (p) => staysInside(p) && p !== README,
+    `is not a path inside the study's folder, or names its ${README}`,
+  );
+
+/**
+ * Whether `p` names a file by one or more names joined by `/`, none empty, `.` or `..`: never the
+ * paper's folder itself (`.`) nor a path ending in `/`. Whether a name is a directory on disk is the
+ * gate's and the order rule's to see.
+ */
+const namesAFile = (p: string): boolean =>
+  p.split("/").every((n) => n !== "" && n !== "." && n !== "..");
+
+/**
+ * A decision file, relative to the PAPER's folder: inside it, and a file's path. Empty in a draft (the
+ * parser names it).
+ */
+const inPaper = z
+  .string()
+  .refine(staysInside, "is not a path inside the paper's folder")
+  .refine(
+    (p) => p === "" || !staysInside(p) || namesAFile(p),
+    "is not a path to a file inside the paper's folder: one or more names joined by /, none empty, . or ..",
+  );
+
+const decisionShape = z.strictObject({ file: inPaper, note: z.string() });
+
+/** The output globs: each once; none yet in a draft. */
+const outputs = z.array(inFolder).superRefine(once("the output"));
+
+/** How the outcomes are kept from the decisions: exactly one mode, by its `kind`. */
+const mode = z.discriminatedUnion("kind", [
+  z.strictObject({
+    kind: z.literal("decide_before_run"),
+    outputs,
+    decision: decisionShape,
+  }),
+  z.strictObject({ kind: z.literal("exploratory"), reason: z.string() }),
+]);
+
 /** A plan's shape: closed at every level; the paper's own keys go in `extra`. Null is the one "none". */
 const planShape = z.strictObject({
   question: z.string(),
@@ -136,6 +208,7 @@ const planShape = z.strictObject({
   primary_outcome: z.string(),
   author_check: authorCheck.nullable(),
   extra: extra.optional(),
+  mode: mode.optional(),
 });
 
 /**
@@ -196,6 +269,28 @@ const readyTexts = z.object({
   primary_outcome: filled,
 });
 
+/** Whether `t` says something. */
+const says = (t: string): boolean => /\S/u.test(t);
+
+/**
+ * The mode's texts that are still empty, by their field: the mode itself when a study of `kind` must
+ * declare one and the plan does not, a decide-first mode's outputs and decision, an exploratory reason.
+ */
+const modeEmpties = (
+  p: StudyPlan,
+  kind: StudyKind,
+): readonly PlanTextField[] => {
+  const m = p.mode;
+  if (m === undefined) return needsMode(kind) ? ["mode"] : [];
+  if (m.kind === "exploratory") return says(m.reason) ? [] : ["mode.reason"];
+  return PLAN_TEXT_FIELDS.filter(
+    (f) =>
+      (f === "mode.outputs" && m.outputs.length === 0) ||
+      (f === "mode.decision.file" && !says(m.decision.file)) ||
+      (f === "mode.decision.note" && !says(m.decision.note)),
+  );
+};
+
 /** A plan that parsed: ready, or a draft. */
 type ReadyOrDraft = Exclude<ParsedPlan, { readonly kind: "unreadable" }>;
 
@@ -203,29 +298,37 @@ type ReadyOrDraft = Exclude<ParsedPlan, { readonly kind: "unreadable" }>;
  * A parsed plan, ready when every required text is filled, else a draft naming the empty ones. A
  * draft that carries the author's check is no plan: the author approved one with empty texts.
  */
-const readyOrDraft = (
-  p: StudyPlan,
-  ctx: Readonly<z.core.$RefinementCtx>,
-): ReadyOrDraft => {
-  const checked = readyTexts.safeParse(p);
-  if (checked.success) return { kind: "ready", plan: p };
-  const paths = checked.error.issues.map((i) => i.path.join("."));
-  const empty = PLAN_TEXT_FIELDS.filter((f) => paths.includes(f));
-  if (p.author_check === null)
-    return { kind: "draft", plan: { ...p, author_check: null }, empty };
-  ctx.addIssue({
-    code: "custom",
-    path: ["author_check"],
-    message: `is set, and the plan leaves ${empty.map((f) => `\`${f}\``).join(", ")} empty — the author approves a complete plan: fill them, or set author_check to null`,
-  });
-  return z.NEVER;
-};
+const readyOrDraft =
+  (kind: StudyKind) =>
+  (p: StudyPlan, ctx: Readonly<z.core.$RefinementCtx>): ReadyOrDraft => {
+    const checked = readyTexts.safeParse(p);
+    const paths = checked.success
+      ? []
+      : checked.error.issues.map((i) => i.path.join("."));
+    const empty = [
+      ...PLAN_TEXT_FIELDS.filter((f) => paths.includes(f)),
+      ...modeEmpties(p, kind),
+    ];
+    if (empty.length === 0) return { kind: "ready", plan: p };
+    if (p.author_check === null)
+      return { kind: "draft", plan: { ...p, author_check: null }, empty };
+    ctx.addIssue({
+      code: "custom",
+      path: ["author_check"],
+      message: `is set, and the plan leaves ${empty.map((f) => `\`${f}\``).join(", ")} empty — the author approves a complete plan: fill them, or set author_check to null`,
+    });
+    return z.NEVER;
+  };
 
-/** A `plan.json`: strict, then ready or draft. */
-const plan = planShape.transform(readyOrDraft);
+/** A `plan.json` of a study of `kind`: strict, then ready or draft — a measurement's ready only with its mode. */
+const planFor = (kind: StudyKind) => planShape.transform(readyOrDraft(kind));
 
-/** A `prereg.json`: loose, mapped onto the plan, then ready or draft. */
-const legacyPlan = legacyAsPlan.transform(readyOrDraft);
+/**
+ * A `prereg.json`: loose, mapped onto the plan, then ready or draft. Written before modes existed, it
+ * is never asked for one; `repro/study-plan-name` already asks to move it to `plan.json`, where the
+ * strict parser does.
+ */
+const legacyPlan = legacyAsPlan.transform(readyOrDraft("spike"));
 
 // ── the schemas ARE the domain's types ─────────────────────────────────────────
 // Each schema's output and its hand-written domain type are the same type, both ways, once both are
@@ -261,8 +364,10 @@ export type SchemasAreTheDomain = [
   Same<z.output<typeof authorCheck>, AuthorCheck>,
   Same<z.output<typeof planShape>, StudyPlan>,
   Same<z.output<typeof legacyAsPlan>, StudyPlan>,
-  Same<z.output<typeof plan>, ReadyOrDraft>,
+  Same<z.output<ReturnType<typeof planFor>>, ReadyOrDraft>,
   Same<z.output<typeof legacyPlan>, ReadyOrDraft>,
+  Same<z.output<typeof mode>, StudyMode>,
+  Same<z.output<typeof decisionShape>, Decision>,
 ] extends true[]
   ? true
   : never;
@@ -315,8 +420,9 @@ const planParser =
       : { kind: "unreadable", why: reasons(parsed.error.issues) };
   };
 
-/** A `plan.json`: strict. */
-export const parseStudyPlan = planParser(plan);
+/** A `plan.json` of a study of `kind`: strict. */
+export const parseStudyPlan = (text: string, kind: StudyKind): ParsedPlan =>
+  planParser(planFor(kind))(text);
 
 /** A plan still named `prereg.json`: loose, read only when a row names it. */
 export const parseLegacyPlan = planParser(legacyPlan);

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

@@ -0,0 +1,162 @@
+/**
+ * The schema of a study's mode (`mode` in its plan). Both halves: what `studies new` writes parses back
+ * to itself; a measurement's plan is ready only with exactly one mode; every contradiction is refused
+ * with its reason.
+ */
+import { expect, it } from "vitest";
+import type { StudyMode } from "../../domain/study-mode.ts";
+import {
+  planTemplate,
+  planText,
+  type StudyKind,
+  type StudyPlan,
+} from "../../domain/study-registry.ts";
+import { studyRegistryCodec } from "./index.ts";
+
+const DECIDED: StudyMode = {
+  kind: "decide_before_run",
+  outputs: ["data/outcome/**", "RESULTS.md"],
+  decision: {
+    file: "repro/P1-S01-x/decision.md",
+    note: "exclusions and the sample approved",
+  },
+};
+const EXPLORATORY: StudyMode = {
+  kind: "exploratory",
+  reason: "a first look at the logs, to find the question",
+};
+
+const PLAN: StudyPlan = {
+  question: "Does the hint help?",
+  population: {
+    source: "tasks, 2026-10-01",
+    draw: { kind: "all", method: "census" },
+  },
+  arms: [{ name: "hint" }, { name: "none" }],
+  primary_outcome: "pass rate",
+  author_check: null,
+  mode: DECIDED,
+};
+
+const parse = (text: string, kind: StudyKind = "measurement") =>
+  studyRegistryCodec.parsePlan(text, kind);
+const withMode = (mode: unknown): string => JSON.stringify({ ...PLAN, mode });
+const why = (text: string): string => {
+  const r = parse(text);
+  return r.kind === "unreadable" ? r.why : r.kind;
+};
+const empty = (text: string, kind: StudyKind = "measurement") => {
+  const r = parse(text, kind);
+  return r.kind === "draft" ? r.empty : r.kind;
+};
+
+it("each mode parses to itself, ready", () => {
+  // Guards: the three modes round-trip through the text planText writes.
+  expect(
+    [DECIDED, EXPLORATORY].map((mode) => parse(planText({ ...PLAN, mode }))),
+  ).toEqual(
+    [DECIDED, EXPLORATORY].map((mode) => ({
+      kind: "ready",
+      plan: { ...PLAN, mode },
+    })),
+  );
+});
+
+it("a measurement's plan without a mode is a draft naming `mode`; a spike's is ready", () => {
+  const none: StudyPlan = { ...PLAN, mode: undefined };
+  // Guards: "none" is not a ready state for a measurement — and a spike may omit it.
+  expect(empty(planText(none))).toEqual(["mode"]);
+  expect(empty(planText(none), "spike")).toBe("ready");
+});
+
+it("the template of a measurement is a draft decided before its run, its decision file named", () => {
+  const t = planTemplate("measurement", "P1-S02-x");
+  // Guards: `studies new` scaffolds the default mode; what is left to fill is named.
+  expect(t.mode).toEqual({
+    kind: "decide_before_run",
+    outputs: [],
+    decision: { file: "repro/P1-S02-x/decision.md", note: "" },
+  });
+  expect(empty(planText(t))).toEqual([
+    "question",
+    "population.source",
+    "population.draw.method",
+    "primary_outcome",
+    "mode.outputs",
+    "mode.decision.note",
+  ]);
+  expect(planTemplate("spike", "P1-S03-y").mode).toBeUndefined();
+});
+
+it("each mode's empty texts are named: the decision's, an exploratory reason", () => {
+  // Guards: a mode left half-written is a draft, so a study that has run on it is reported.
+  expect(
+    empty(
+      withMode({ ...DECIDED, outputs: [], decision: { file: " ", note: "" } }),
+    ),
+  ).toEqual(["mode.outputs", "mode.decision.file", "mode.decision.note"]);
+  expect(empty(withMode({ ...EXPLORATORY, reason: "" }))).toEqual([
+    "mode.reason",
+  ]);
+});
+
+it("two modes at once, or a mode that is neither, cannot be written", () => {
+  // Guards: exactly one — a second mode's key is an unknown key, an unknown kind is refused.
+  expect(why(withMode({ ...DECIDED, reason: "r" }))).toBe(
+    'mode: Unrecognized key: "reason"',
+  );
+  expect(why(withMode({ kind: "preregistered" }))).toBe(
+    "mode.kind: Invalid discriminator value. Expected 'decide_before_run' | 'exploratory'",
+  );
+  expect(why(withMode({ kind: "blind" }))).toBe(
+    "mode.kind: Invalid discriminator value. Expected 'decide_before_run' | 'exploratory'",
+  );
+});
+
+it("refuses an output outside the folder or naming the study's README, and a decision outside the paper", () => {
+  const outside =
+    "is not a path inside the study's folder, or names its README.md";
+  // Guards: a glob cannot reach past the study's folder; a decision cannot leave the paper.
+  expect(
+    ["../x", "/abs", "a\\b", "README.md"].map((o) =>
+      why(withMode({ ...DECIDED, outputs: [o] })),
+    ),
+  ).toEqual(Array.from({ length: 4 }, () => `mode.outputs.0: ${outside}`));
+  expect(why(withMode({ ...DECIDED, outputs: ["a", "a"] }))).toBe(
+    "mode.outputs: the output «a» is listed more than once",
+  );
+  expect(
+    ["../d.md", "/d.md", "a\\d.md"].map((file) =>
+      why(withMode({ ...DECIDED, decision: { file, note: "n" } })),
+    ),
+  ).toEqual(
+    Array.from(
+      { length: 3 },
+      () => "mode.decision.file: is not a path inside the paper's folder",
+    ),
+  );
+});
+
+it("refuses a decision path that names the paper's folder or a directory, and keeps an empty one a draft", () => {
+  const notFile =
+    "mode.decision.file: is not a path to a file inside the paper's folder: one or more names joined by /, none empty, . or ..";
+  // Guards: a decision of `.` would make the gate ask git about the whole paper, and the order rule
+  // read the paper's first commit as the decision; such a path cannot be written down.
+  expect(
+    [".", "./", "repro/", "a//d.md", "a/./d.md", "./d.md"].map((file) =>
+      why(withMode({ ...DECIDED, decision: { file, note: "n" } })),
+    ),
+  ).toEqual(Array(6).fill(notFile));
+  expect(
+    empty(withMode({ ...DECIDED, decision: { file: "", note: "n" } })),
+  ).toEqual(["mode.decision.file"]);
+});
+
+it("mode is a field of the plan, so extra cannot carry it", () => {
+  // Guards: one place says how a study is gated.
+  expect(
+    why(JSON.stringify({ ...PLAN, mode: undefined, extra: { mode: {} } })),
+  ).toBe(
+    "extra.mode: is a field of the plan itself — set it there, not in extra",
+  );
+});

package/src/cli.ts

@@ -190,6 +190,12 @@ import {
   studyRegistryRules,
 } from "./study-registry-rule.ts";
 import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
+import { nodeListEntries, spawnProcess } from "./adapters/node/index.ts";
+import { gitHistory } from "./adapters/git/index.ts";
+import {
+  ORDER_RULE_LEVELS,
+  outputsBeforeDecisionRules,
+} from "./outputs-before-decision-rule.ts";
 import { runStudies } from "./studies.ts";
 import typography from "#eslint-rules/paper-typography";
 import texBuild from "#eslint-rules/tex-build";
@@ -243,6 +249,11 @@ const USAGE = `paperlint — machine-checkable gates for a paper kept in git
                                       index in repro/README.md regenerated
   npx paperlint studies index <paper-dir>
                                       regenerate the index in repro/README.md from repro/studies.json
+  npx paperlint studies gate <paper-dir> <id>
+                                      may the study's run start? For a study decided before its run
+                                      (the default mode), exit 0 only once its decision file is
+                                      committed as it stands, printing the commit and date; else exit
+                                      1 saying why. A runner calls it first: gate … && ./run.sh
   npx paperlint hook <name>           run an editor hook (.claude/settings.json calls this)
   npx paperlint --help
 
@@ -267,7 +278,10 @@ studies:
   --kind <kind>       new: measurement (the default), spike, tooling, data, artifact or salvage.
                       A study's status, result and in_paper are edited in repro/studies.json, its
                       plan in its plan.json; the rule repro/study-registered checks them
-                      (docs/rules/repro/study-registered.md)
+                      (docs/rules/repro/study-registered.md). A measurement's plan declares its
+                      mode: decide_before_run (written by new) or exploratory;
+                      repro/outputs-before-decision checks the order in git
+                      (docs/design/study-modes.md)
 
 submission:
   The venue preset declares the portal — "portal": { "kind": "hotcrp", "url": "<site>" } — and the
@@ -383,20 +397,43 @@ const FRAGMENT_RULES = {
   "heading-case": REGISTER_AND_CASE_RULES["heading-case"],
 };
 
+/** `names` of this process's environment, and nothing else of it. */
+const envOf =
+  (names: readonly string[]) =>
+  (env: Readonly<NodeJS.ProcessEnv>): Readonly<Record<string, string>> =>
+    Object.fromEntries(
+      Object.entries(env).filter(
+        (e): e is [string, string] =>
+          names.includes(e[0]) && e[1] !== undefined,
+      ),
+    );
+
+/** The environment git runs in: PATH, and HOME for its configuration. */
+const gitEnv = envOf(["PATH", "HOME"]);
+
+/** git's history, as the decide-first rule and the gate read it. */
+const GIT = gitHistory(spawnProcess(), gitEnv(process.env));
+
 /** What the two layout rules read with: the disk and its directory listings. */
 const LAYOUT_RULE_DEPS = { files: nodeFiles, listDir: nodeListDir };
 
 /** What `repro/study-registered` and `paperlint studies` read with: the layout's, and the registry's parser. */
-const STUDY_RULE_DEPS = { ...LAYOUT_RULE_DEPS, codec: studyRegistryCodec };
+const STUDY_RULE_DEPS = {
+  ...LAYOUT_RULE_DEPS,
+  entries: nodeListEntries,
+  codec: studyRegistryCodec,
+};
 
 /** The `repro` plugin's rules, on every `PIPELINE-STATUS.md`: the layout of `repro/`, and its study registry. */
 const REPRO_RULES = {
   ...reproLayoutRules(LAYOUT_RULE_DEPS),
   ...studyRegistryRules(STUDY_RULE_DEPS),
+  ...outputsBeforeDecisionRules({ ...STUDY_RULE_DEPS, git: GIT }),
 };
 const REPRO_RULE_LEVELS = {
   ...REPRO_LAYOUT_RULE_LEVELS,
   ...STUDY_REGISTRY_RULE_LEVELS,
+  ...ORDER_RULE_LEVELS,
 };
 
 /** Today in this machine's time zone, `YYYY-MM-DD`: the date `paperlint studies new` registers a study on. */
@@ -1675,7 +1712,14 @@ const SIMPLE: Readonly<
         extra: a.paths.slice(3),
         kind: a.kind,
       },
-      { ...STUDY_RULE_DEPS, cwd, today: today(), log, err },
+      {
+        ...STUDY_RULE_DEPS,
+        git: GIT,
+        cwd,
+        today: today(),
+        log,
+        err,
+      },
     ),
   submission: (a, { log, err, cwd }) =>
     runSubmission(