paperlint 10.3.0 → 10.4.0

package/src/outputs-before-decision-rule.test.ts

@@ -0,0 +1,206 @@
+/**
+ * `repro/outputs-before-decision` (`src/outputs-before-decision-rule.ts`) over a REAL git repository
+ * in a scratch directory, the files read from disk and the history from git: silent on a study whose
+ * outputs entered history after its decision, loud on each output that did not, on an output while
+ * the decision is uncommitted; and only on `PIPELINE-STATUS.md`.
+ */
+import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { expect, it } from "vitest";
+import { gitHistory } from "./adapters/git/index.ts";
+import {
+  nodeFiles,
+  nodeListDir,
+  nodeListEntries,
+  spawnProcess,
+} from "./adapters/node/index.ts";
+import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
+import type { StudyMode } from "./domain/study-mode.ts";
+import { planText, registryText } from "./domain/study-registry.ts";
+import { outputsBeforeDecisionRules } from "./outputs-before-decision-rule.ts";
+import { commit, initRepo } from "../test/git-repo.ts";
+import { useTempDir } from "../test/support.ts";
+import { ROW, planOf } from "../test/study-tree.ts";
+
+const root = useTempDir("outputs-before-decision-");
+const DECIDED: StudyMode = {
+  kind: "decide_before_run",
+  outputs: ["out/**", "RESULTS.md"],
+  decision: { file: "repro/P1-S01-outcome/decision.md", note: "exclusions" },
+};
+const S = "p/repro/P1-S01-outcome";
+const PAPER = {
+  "p/PIPELINE-STATUS.md": "# status\n",
+  "p/repro/studies.json": registryText({ prefix: "P1", studies: [ROW] }),
+  [`${S}/README.md`]: "# outcome\n",
+  [`${S}/plan.json`]: planText(planOf(DECIDED)),
+};
+const T = (h: number): string =>
+  `2026-10-16T${String(h).padStart(2, "0")}:00:00+05:00`;
+
+/** The rule's message ids over the paper in `repo`, reached through `file`. */
+const lint = (repo: string, file = "p/PIPELINE-STATUS.md"): string[] => {
+  const rule = outputsBeforeDecisionRules({
+    files: nodeFiles,
+    listDir: nodeListDir,
+    entries: nodeListEntries,
+    codec: studyRegistryCodec,
+    git: gitHistory(spawnProcess(), { PATH: String(process.env.PATH) }),
+  })["outputs-before-decision"];
+  const ids: string[] = [];
+  rule
+    .create({
+      filename: join(repo, file),
+      sourceCode: { getLocFromIndex: () => ({ line: 1, column: 0 }) },
+      report: (d) => ids.push(d.messageId),
+    })
+    .root?.();
+  return ids;
+};
+
+it("silent when the decision was committed first and the outputs after it", () => {
+  const repo = join(root, "clean");
+  initRepo(repo);
+  commit(repo, PAPER, T(9));
+  commit(repo, { [`${S}/decision.md`]: "exclude run 7\n" }, T(10));
+  commit(
+    repo,
+    { [`${S}/RESULTS.md`]: "41 of 60\n", [`${S}/out/a.csv`]: "1\n" },
+    T(11),
+  );
+  // Guards: the correct history — and the rule speaks only on PIPELINE-STATUS.md.
+  expect([lint(repo), lint(repo, "p/paper.tex")]).toEqual([[], []]);
+});
+
+it("loud on each output committed with or before the decision, and on outputs with no decision", () => {
+  const repo = join(root, "early");
+  initRepo(repo);
+  commit(repo, { ...PAPER, [`${S}/out/early.csv`]: "1\n" }, T(9));
+  commit(
+    repo,
+    { [`${S}/decision.md`]: "d\n", [`${S}/RESULTS.md`]: "x\n" },
+    T(10),
+  );
+  // Guards: one finding per output — the earlier one and the one in the decision's own commit.
+  expect(lint(repo)).toEqual([
+    "output-before-decision",
+    "output-before-decision",
+  ]);
+  const none = join(root, "undecided");
+  initRepo(none);
+  commit(none, PAPER, T(9));
+  commit(none, { [`${S}/RESULTS.md`]: "x\n" }, T(10));
+  // Guards: an output while the decision has never been committed.
+  expect(lint(none)).toEqual(["undecided-output"]);
+});
+
+it("never reads through a row whose folder leads outside repro/: no study, so no question to git", () => {
+  const repo = join(root, "escaping");
+  initRepo(repo);
+  // The row names `../outside`; a plan and an output sit there, outside `repro/`.
+  commit(
+    repo,
+    {
+      ...PAPER,
+      "p/repro/studies.json": registryText({
+        prefix: "P1",
+        studies: [{ ...ROW, folder: "../outside" }],
+      }),
+      "p/outside/plan.json": planText(planOf(DECIDED)),
+      "p/outside/RESULTS.md": "41 of 60\n",
+    },
+    T(9),
+  );
+  // Guards: an output outside the paper's `repro/` is no study's; `repro/study-registered` names the row.
+  expect(lint(repo)).toEqual([]);
+});
+
+it("loud on an output committed and then deleted while the decision was never committed", () => {
+  const repo = join(root, "deleted");
+  initRepo(repo);
+  commit(repo, { ...PAPER, [`${S}/RESULTS.md`]: "41 of 60\n" }, T(9));
+  commit(repo, { [`${S}/RESULTS.md`]: null }, T(10));
+  // Guards: the tree is clean now, and history still shows a result that came before any decision.
+  expect(lint(repo)).toEqual(["undecided-output"]);
+});
+
+it("loud on a decision that names a directory: git's answer for it is no decision's commit", () => {
+  const repo = join(root, "directory");
+  initRepo(repo);
+  const dir = "repro/P1-S01-outcome/decisions";
+  commit(
+    repo,
+    {
+      ...PAPER,
+      [`${S}/plan.json`]: planText(
+        planOf({ ...DECIDED, decision: { file: dir, note: "n" } }),
+      ),
+      [`p/${dir}/a.md`]: "exclude run 7\n",
+    },
+    T(9),
+  );
+  commit(repo, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(10));
+  // Guards: the order is never read from a directory's history — the plan is reported instead.
+  expect(lint(repo)).toEqual(["decision-not-file"]);
+});
+
+it("lists a symlink in the study's folder as a file, never following it: a loop or a link outside", () => {
+  const repo = join(root, "links");
+  initRepo(repo);
+  mkdirSync(join(repo, "outside"), { recursive: true });
+  writeFileSync(join(repo, "outside", "RESULTS.md"), "not this study's\n");
+  commit(repo, PAPER, T(9));
+  commit(repo, { [`${S}/decision.md`]: "exclude run 7\n" }, T(10));
+  symlinkSync(".", join(repo, S, "loop"));
+  symlinkSync(join(repo, "outside"), join(repo, S, "ext"));
+  commit(repo, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(11));
+  // Guards: a link to its own folder would recurse forever, and one outside would bring a foreign
+  // `RESULTS.md` into the study; both are entries git itself stores as links.
+  expect(lint(repo)).toEqual([]);
+});
+
+it("loud on a decision deleted after its outputs: a decision that no longer stands decides nothing", () => {
+  const repo = join(root, "decision-deleted");
+  initRepo(repo);
+  commit(repo, PAPER, T(9));
+  commit(repo, { [`${S}/decision.md`]: "exclude run 7\n" }, T(10));
+  commit(repo, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(11));
+  commit(repo, { [`${S}/decision.md`]: null }, T(12));
+  // Guards: the order was right once; with the decision gone from HEAD the study is reported.
+  expect(lint(repo)).toEqual(["decision-deleted"]);
+});
+
+it("loud on a decision that is a symbolic link: git records the link, not the decision", () => {
+  const repo = join(root, "decision-link");
+  initRepo(repo);
+  mkdirSync(join(repo, "p"), { recursive: true });
+  writeFileSync(join(repo, "p/elsewhere.md"), "exclude run 7\n");
+  mkdirSync(join(repo, S), { recursive: true });
+  symlinkSync("../../elsewhere.md", join(repo, S, "decision.md"));
+  commit(repo, PAPER, T(9));
+  commit(repo, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(10));
+  // Guards: a link committed first proves nothing of what it pointed to when the run started.
+  expect(lint(repo)).toEqual(["decision-not-file"]);
+});
+
+it("never reads through a study folder that is a symbolic link", () => {
+  const repo = join(root, "folder-link");
+  initRepo(repo);
+  const elsewhere = "p/elsewhere";
+  commit(
+    repo,
+    {
+      ...Object.fromEntries(
+        Object.entries(PAPER).filter(([k]) => !k.startsWith(S)),
+      ),
+      [`${elsewhere}/README.md`]: "# outcome\n",
+      [`${elsewhere}/plan.json`]: planText(planOf(DECIDED)),
+      [`${elsewhere}/RESULTS.md`]: "41 of 60\n",
+    },
+    T(9),
+  );
+  symlinkSync("../elsewhere", join(repo, S));
+  commit(repo, {}, T(10));
+  // Guards: the outputs behind the link are not this paper's study; nothing is read through it.
+  expect(lint(repo)).toEqual([]);
+});

package/src/outputs-before-decision-rule.ts

@@ -0,0 +1,124 @@
+/**
+ * `repro/outputs-before-decision` — a study decided before its run shows that order in git's
+ * history: every output entered history after the decision file did, and no output exists while the
+ * decision is uncommitted. What is judged, and why, is `src/domain/decide-first.ts` and
+ * docs/rules/repro/outputs-before-decision.md; this file finds the decide-first studies, lists their
+ * folders, asks git through the `GitOrder` port, and reports.
+ *
+ * ── WHY A RULE MAY ASK GIT HERE ────────────────────────────────────────────────
+ * `eslint-rules/` may not run git (eslint.config.mjs, `GIT_IN_A_RULE`): a pinned sha is deleted by a
+ * squash or a gc, and a shallow CI checkout has none. This rule pins no sha. It asks the history the
+ * checkout has for an ORDER, which a squash merge keeps when the decision was merged before the run
+ * (the decide-first workflow), and it reports a shallow clone by name instead of judging it.
+ *
+ * Reported on `PIPELINE-STATUS.md`, first line, like the other `repro/` rules.
+ */
+import { basename, dirname, join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  filesUnder,
+  modeStudies,
+  onDisk,
+  type StudyDeps,
+} from "./study-modes.ts";
+import {
+  judgeOrder,
+  orderMessage,
+  type DecideFirstStudy,
+  type OrderFinding,
+} from "./domain/decide-first.ts";
+import { REPRO_DIR } from "./domain/repro-layout.ts";
+import type {
+  FolderRuleContext,
+  FolderRuleModule,
+} from "./folder-venue-rule.ts";
+import type { GitOrder } from "./ports/git-history.ts";
+import { rulePageUrl } from "./venue-rules.ts";
+
+const STATUS_FILE = "PIPELINE-STATUS.md";
+
+/** What the rule reads with: the registry's, and git's order. */
+export interface OrderDeps extends StudyDeps {
+  readonly git: GitOrder;
+}
+
+/** Every decide-first study of the paper folder `paper`, with its tree and its history's order. */
+export const decideFirstStudies = (
+  paper: string,
+  deps: OrderDeps,
+): readonly DecideFirstStudy[] =>
+  modeStudies(paper, deps).flatMap(({ row, plan, mode, empty }) => {
+    // Only a ready plan decides: a draft may name no outputs, or an empty decision file.
+    if (mode.kind !== "decide_before_run" || empty.length > 0) return [];
+    const folder = join(paper, REPRO_DIR, row.folder);
+    const decision = join(paper, mode.decision.file);
+    const on = onDisk(decision, deps);
+    return [
+      {
+        id: row.id,
+        folder: row.folder,
+        plan,
+        mode,
+        tree: filesUnder(folder, deps),
+        facts:
+          on === "directory" || on === "symbolic link"
+            ? { kind: "not-a-file", what: on }
+            : deps.git.order(callerPath(folder), callerPath(decision)),
+      },
+    ];
+  });
+
+const PROBLEMS: readonly OrderFinding["problem"][] = [
+  "decision-is-output",
+  "decision-deleted",
+  "decision-not-file",
+  "no-history",
+  "shallow",
+  "undecided-output",
+  "output-before-decision",
+];
+
+const NAME = "repro/outputs-before-decision";
+
+/** On `PIPELINE-STATUS.md`, every finding of every decide-first study of its paper, at its first line. */
+const reportOn = (context: FolderRuleContext, deps: OrderDeps) => {
+  if (basename(context.filename) !== STATUS_FILE) return {};
+  return {
+    root() {
+      const at = context.sourceCode.getLocFromIndex(0);
+      decideFirstStudies(dirname(context.filename), deps)
+        .flatMap(judgeOrder)
+        .forEach((f) => {
+          context.report({
+            loc: { start: at, end: at },
+            messageId: f.problem,
+            data: { text: orderMessage(f) },
+          });
+        });
+    },
+  };
+};
+
+/** The rule, reading the folder and git through `deps`. */
+export const outputsBeforeDecisionRules = (
+  deps: OrderDeps,
+): Readonly<Record<"outputs-before-decision", FolderRuleModule>> => ({
+  "outputs-before-decision": {
+    meta: {
+      type: "suggestion",
+      docs: {
+        description:
+          "a study decided before its run shows it in git's history: every output entered history after its decision file, and none exists while the decision is uncommitted",
+        url: rulePageUrl(NAME),
+      },
+      schema: [],
+      messages: Object.fromEntries(PROBLEMS.map((p) => [p, "{{text}}"])),
+    },
+    create: (context) => reportOn(context, deps),
+  },
+});
+
+/** Its level in paperlint's own config: an error. */
+export const ORDER_RULE_LEVELS: Readonly<{
+  "repro/outputs-before-decision": "error";
+}> = { "repro/outputs-before-decision": "error" };

package/src/ports/git-history.ts

@@ -0,0 +1,44 @@
+/**
+ * What git says of a study's files — shaped by what the decide-first gate needs: whether a decision
+ * file is committed as it stands, and in which commit (`studies gate`); and whether
+ * each output entered history after the decision (`repro/outputs-before-decision`). The one
+ * implementation is `src/adapters/git/`; `src/cli.ts` wires it.
+ */
+import type { OrderFacts } from "../domain/decide-first.ts";
+import type { AbsolutePath } from "../domain/paths.ts";
+
+export type {
+  CommitAt,
+  FirstCommit,
+  Order,
+  OrderFacts,
+} from "../domain/decide-first.ts";
+
+export type Committed =
+  /** No commit has the file: untracked, ignored, only staged, or absent. */
+  | { readonly kind: "not-committed" }
+  /** Committed, and changed since (edited, staged, deleted): the commit is not what is on disk. */
+  | { readonly kind: "changed"; readonly commit: string }
+  /** Committed, then deleted in a later commit: it is not in HEAD, so there is nothing to gate on. */
+  | { readonly kind: "deleted"; readonly commit: string }
+  /** Committed as it stands: the last commit that touched it, and that commit's date. */
+  | {
+      readonly kind: "committed";
+      readonly commit: string;
+      readonly date: string;
+    }
+  /** git could not answer: not installed, not a repository. */
+  | { readonly kind: "unknown"; readonly why: string };
+
+export interface GitHistory {
+  /** `file` (absolute, in the repository that holds `paper`), asked from the paper's folder. */
+  readonly committed: (paper: AbsolutePath, file: AbsolutePath) => Committed;
+}
+
+export interface GitOrder {
+  /** The order of `decision`'s first commit against every file's under `studyDir` (a folder that exists). */
+  readonly order: (
+    studyDir: AbsolutePath,
+    decision: AbsolutePath,
+  ) => OrderFacts;
+}

package/src/ports/list-entries.ts

@@ -0,0 +1,18 @@
+/**
+ * A directory's entries with what each one is, read without following a symbolic link — so a walk
+ * that descends only into `dir` entries can neither loop on a link to an ancestor nor wander into a
+ * tree outside through one. The walker of a study's folder (`src/study-modes.ts`) reads with it.
+ */
+import type { AbsolutePath } from "../domain/paths.ts";
+
+/**
+ * One entry of a directory: a directory, a symbolic link (not followed), or a file — anything else on
+ * disk (a socket, a FIFO) reads as a file: a name, never descended into.
+ */
+export interface DirEntry {
+  readonly name: string;
+  readonly kind: "file" | "dir" | "symlink";
+}
+
+/** The entries of `dir`; none when it does not exist or is not a directory. */
+export type ListEntries = (dir: AbsolutePath) => readonly DirEntry[];

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

@@ -3,13 +3,20 @@
  * of `StudyRegistry` (`src/domain/study-registry.ts`). The one implementation is
  * `src/adapters/study-registry/` (zod); `src/cli.ts` wires it.
  */
-import type { ParsedPlan, ParsedRegistry } from "../domain/study-registry.ts";
+import type {
+  ParsedPlan,
+  ParsedRegistry,
+  StudyKind,
+} from "../domain/study-registry.ts";
 
 export interface StudyRegistryCodec {
   /** A `studies.json`'s text: the registry, or the one reason it is not one of this schema. */
   readonly parse: (text: string) => ParsedRegistry;
-  /** A study's `plan.json` text, strict: ready, a draft naming its empty texts, or why it is no plan. */
-  readonly parsePlan: (text: string) => ParsedPlan;
+  /**
+   * A study's `plan.json` text, strict: ready, a draft naming its empty texts, or why it is no plan. A
+   * study of a `kind` that must declare its mode (a measurement) is ready only with one.
+   */
+  readonly parsePlan: (text: string, kind: StudyKind) => ParsedPlan;
   /** A plan still named `prereg.json`, loose: the same three outcomes. */
   readonly parseLegacyPlan: (text: string) => ParsedPlan;
 }

package/src/rule-cases.test.ts

@@ -17,16 +17,22 @@ import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { run, rulePlugins } from "./cli.ts";
 import { sha256Hex } from "./domain/sha256.ts";
+import type { StudyMode } from "./domain/study-mode.ts";
 import {
   planTemplate,
   planText,
   registryText,
   withIndex,
+  type StudyPlan,
   type StudyRegistry,
+  type IndexInput,
 } from "./domain/study-registry.ts";
 import { recordText } from "../test/recorded-fixture.ts";
 import { useTempDir, venuePreset, writeTree } from "../test/support.ts";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const fixture = (p: string): string =>
   readFileSync(join(ROOT, "fixtures", p), "utf8");
@@ -64,7 +70,7 @@ const REGISTRY: StudyRegistry = {
 };
 const REGISTERED_STUDY: Readonly<Record<string, string>> = {
   [`${P}/repro/studies.json`]: registryText(REGISTRY),
-  [`${P}/repro/README.md`]: withIndex("# repro\n", REGISTRY),
+  [`${P}/repro/README.md`]: withIndex("# repro\n", REGISTRY, NO_FACTS),
   [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
 };
 
@@ -76,9 +82,47 @@ const STUDY_WITH_PLAN = (name: string): Readonly<Record<string, string>> => {
   };
   return {
     [`${P}/repro/studies.json`]: registryText(r),
-    [`${P}/repro/README.md`]: withIndex("# repro\n", r),
+    [`${P}/repro/README.md`]: withIndex("# repro\n", r, NO_FACTS),
     [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
-    [`${P}/repro/P1-S01-ablation/${name}`]: planText(planTemplate()),
+    [`${P}/repro/P1-S01-ablation/${name}`]: planText(
+      planTemplate("spike", "P1-S01-ablation"),
+    ),
+  };
+};
+
+/** The registered study as a measurement in `mode`, its plan ready, `files` beside it. */
+const STUDY_IN_MODE = (
+  mode: StudyMode,
+  files: Readonly<Record<string, string>> = {},
+): Readonly<Record<string, string>> => {
+  const r: StudyRegistry = {
+    ...REGISTRY,
+    studies: REGISTRY.studies.map((s) => ({ ...s, plan: "plan.json" })),
+  };
+  const plan: StudyPlan = {
+    question: "Which step does the work?",
+    population: { source: "tasks", draw: { kind: "all", method: "census" } },
+    arms: [],
+    primary_outcome: "pass rate",
+    author_check: null,
+    mode,
+  };
+  // The index carries the plan's mode, as the lint reads it; no history is asked.
+  const facts: IndexInput = {
+    plans: new Map([["P1-S01-ablation/plan.json", { kind: "ready", plan }]]),
+    history: new Map(),
+  };
+  return {
+    [`${P}/repro/studies.json`]: registryText(r),
+    [`${P}/repro/README.md`]: withIndex("# repro\n", r, facts),
+    [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
+    [`${P}/repro/P1-S01-ablation/plan.json`]: planText(plan),
+    ...Object.fromEntries(
+      Object.entries(files).map(([k, v]) => [
+        `${P}/repro/P1-S01-ablation/${k}`,
+        v,
+      ]),
+    ),
   };
 };
 
@@ -787,6 +831,37 @@ const CASES: Readonly<Record<string, RuleCases>> = {
     // Every folder registered, and the index the registry generates.
     silent: paper(tex("x"), REGISTERED_STUDY),
   },
+  // A study decided before its run, linted where git has no history of it: said, never a pass. The
+  // order itself is judged on real repositories in src/outputs-before-decision-rule.test.ts.
+  "repro/outputs-before-decision": {
+    reports: {
+      tree: paper(
+        tex("x"),
+        STUDY_IN_MODE(
+          {
+            kind: "decide_before_run",
+            outputs: ["RESULTS.md"],
+            decision: {
+              file: "repro/P1-S01-ablation/decision.md",
+              note: "exclusions",
+            },
+          },
+          { "RESULTS.md": "41 of 60\n" },
+        ),
+      ),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same study declared exploratory: no gate, nothing to order.
+    silent: paper(
+      tex("x"),
+      STUDY_IN_MODE(
+        { kind: "exploratory", reason: "a first look" },
+        { "RESULTS.md": "41 of 60\n" },
+      ),
+    ),
+  },
   // A study's plan still named prereg.json: read as its plan, and a warning to rename it.
   "repro/study-plan-name": {
     reports: {

package/src/studies-index-modes.test.ts

@@ -0,0 +1,129 @@
+/**
+ * `paperlint studies index` and `studies new` (`src/studies.ts`) writing the index's mode columns from
+ * the plans and git's history (a stand-in), and refusing a registry whose row names a folder outside
+ * `repro/` before reading or writing through it.
+ */
+import { expect, it } from "vitest";
+import {
+  DECIDED,
+  DIR,
+  ROW,
+  planOf,
+  studies,
+  tree,
+} from "../test/study-tree.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 README = `${DIR}/repro/README.md`;
+
+/** The row of P1-S01 in the README `studies index` wrote, its cells trimmed. */
+const rowOf = (after: Readonly<Record<string, string>>): string[] =>
+  (after[README] ?? "")
+    .split("\n")
+    .filter((l) => l.startsWith("| P1-S01"))
+    .flatMap((l) => l.split("|").map((c) => c.trim()))
+    .filter((c) => c !== "");
+
+it("writes the decision's first commit and the first output's, read from git", () => {
+  const r = studies(
+    "index",
+    tree({ [`${DIR}/repro/P1-S01-outcome/RESULTS.md`]: "41 of 60\n" }),
+    { title: undefined },
+    {
+      order: {
+        kind: "read",
+        decision: D,
+        decisionDeleted: false,
+        files: [
+          { path: "decision.md", ...D, order: "same" },
+          { path: "RESULTS.md", ...A, order: "after" },
+        ],
+      },
+    },
+  );
+  // Guards: the cells the review skills read the Methods sentence's facts from.
+  expect([r.code, r.log, rowOf(r.after)]).toEqual([
+    0,
+    ["wrote the index of 1 study in papers/example/repro/README.md"],
+    [
+      "P1-S01",
+      "Outcome",
+      "running",
+      "—",
+      "no",
+      "decide_before_run",
+      "dddddddddddd 2026-10-14",
+      "aaaaaaaaaaaa 2026-10-16",
+      "[P1-S01-outcome/](P1-S01-outcome/)",
+    ],
+  ]);
+});
+
+it("rewrites the index when only git's columns moved, and leaves it when nothing did", () => {
+  const before = studies("index", tree(), { title: undefined }).after;
+  const order = {
+    kind: "read",
+    decision: D,
+    decisionDeleted: false,
+    files: [],
+  } as const;
+  const moved = studies("index", before, { title: undefined }, { order });
+  const again = studies("index", moved.after, { title: undefined }, { order });
+  // Guards: the lint ignores those two columns, so the command is what keeps them current.
+  expect([rowOf(before)[6], moved.log, again.log]).toEqual([
+    "unknown (git could not answer)",
+    ["wrote the index of 1 study in papers/example/repro/README.md"],
+    ["the index in papers/example/repro/README.md is in sync with 1 study"],
+  ]);
+});
+
+it("an exploratory study's mode carries its reason, and no commit", () => {
+  const r = studies(
+    "index",
+    tree({}, planOf({ kind: "exploratory", reason: "a first look" })),
+    { title: undefined },
+  );
+  expect(rowOf(r.after).slice(5, 8)).toEqual([
+    "exploratory: a first look",
+    "—",
+    "—",
+  ]);
+});
+
+it("refuses a registry whose row names a folder outside repro/, for index and for new", () => {
+  const escaping = tree(
+    { [`${DIR}/x/plan.json`]: JSON.stringify(planOf(DECIDED)) },
+    planOf(DECIDED),
+    { ...ROW, folder: "../x" },
+  );
+  const line =
+    "P1-S01 in papers/example/repro/studies.json names the folder `../x`, which is not one folder inside repro/: nothing is read or written through it. Give the row its own folder's name, then run this again.";
+  const index = studies("index", escaping, { title: undefined });
+  const added = studies("new", escaping, { title: "Second" });
+  // Guards: nothing is written — no README, no new folder — when a row could lead outside the paper.
+  expect([
+    [index.code, index.err, README in index.after],
+    [added.code, added.err, Object.keys(added.after).length],
+  ]).toEqual([
+    [1, [line], false],
+    [1, [line], Object.keys(escaping).length],
+  ]);
+});
+
+it("refuses a registry whose study folder is a symbolic link, for index", () => {
+  const r = studies(
+    "index",
+    tree(),
+    { title: undefined },
+    { links: [`${DIR}/repro/P1-S01-outcome`] },
+  );
+  // Guards: a linked folder leads the reads out of `repro/`, like a row naming `../x`.
+  expect([r.code, r.err, README in r.after]).toEqual([
+    1,
+    [
+      "P1-S01 in papers/example/repro/studies.json names the folder `P1-S01-outcome`, which is not one folder inside repro/: nothing is read or written through it. Give the row its own folder's name, then run this again.",
+    ],
+    false,
+  ]);
+});