paperlint 10.3.0 → 10.4.0

package/src/studies.test.ts

@@ -5,7 +5,11 @@
  * state).
  */
 import { describe, expect, it } from "vitest";
-import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
+import {
+  memoryFiles,
+  memoryListDir,
+  memoryListEntries,
+} from "./adapters/memory/index.ts";
 import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
 import {
   indexBlock,
@@ -16,9 +20,13 @@ import {
   withIndex,
   type Study,
   type StudyRegistry,
+  type IndexInput,
 } from "./domain/study-registry.ts";
 import { runStudies, type StudiesArgs } from "./studies.ts";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const CWD = "/work";
 const DIR = "/work/papers/example";
 const REPRO = `${DIR}/repro`;
@@ -68,9 +76,24 @@ function studies(
     {
       files,
       listDir: memoryListDir(files),
+      entries: memoryListEntries(files),
       codec: studyRegistryCodec,
       cwd,
       today: "2026-10-15",
+      git: {
+        committed: () => {
+          throw new Error(
+            "new and index never ask whether a file is committed",
+          );
+        },
+        // A history with no decision and no output committed yet.
+        order: () => ({
+          kind: "read",
+          decision: null,
+          decisionDeleted: false,
+          files: [],
+        }),
+      },
       log: (l) => log.push(l),
       err: (l) => err.push(l),
     },
@@ -110,10 +133,11 @@ describe("studies new", () => {
     expect(after).toEqual({
       ...before,
       [`${REPRO}/P1-S02-ablation-of-the-guard/README.md`]: studyReadme(added),
-      [`${REPRO}/P1-S02-ablation-of-the-guard/plan.json`]:
-        planText(planTemplate()),
+      [`${REPRO}/P1-S02-ablation-of-the-guard/plan.json`]: planText(
+        planTemplate("spike", "x"),
+      ),
       [`${REPRO}/studies.json`]: registryText(r),
-      [`${REPRO}/README.md`]: `# Reproduction index\n\nIntro.\n\n${indexBlock(r)}\n`,
+      [`${REPRO}/README.md`]: `# Reproduction index\n\nIntro.\n\n${indexBlock(r, NO_FACTS)}\n`,
     });
     expect(log).toEqual([
       "created papers/example/repro/P1-S02-ablation-of-the-guard/README.md",
@@ -221,7 +245,7 @@ describe("studies index", () => {
   it("regenerates the block in place", () => {
     const tree = paper({
       [`${REPRO}/studies.json`]: registryText(r),
-      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(P1())}\n\nTail.\n`,
+      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(P1(), NO_FACTS)}\n\nTail.\n`,
     });
     const { code, log, err, after } = studies(
       { sub: "index", paperDir: "papers/example" },
@@ -234,14 +258,14 @@ describe("studies index", () => {
     });
     expect(after).toEqual({
       ...tree,
-      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(r)}\n\nTail.\n`,
+      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(r, NO_FACTS)}\n\nTail.\n`,
     });
   });
 
   it("says so and writes nothing when the index is in sync", () => {
     const tree = paper({
       [`${REPRO}/studies.json`]: registryText(r),
-      [`${REPRO}/README.md`]: withIndex("# I\n", r),
+      [`${REPRO}/README.md`]: withIndex("# I\n", r, NO_FACTS),
     });
     const out = studies({ sub: "index" }, tree);
     expect([out.code, out.log, out.after]).toEqual([
@@ -266,7 +290,7 @@ describe("studies index", () => {
 describe("studies index — a table a formatter padded", () => {
   it("leaves an index in sync as it is, whatever its padding", () => {
     const r = P1(study({ title: "測定 A" }));
-    const generated = withIndex("# I\n", r);
+    const generated = withIndex("# I\n", r, NO_FACTS);
     const padded = generated.replace("測定 A", "測定 A  ");
     expect(padded).not.toBe(generated);
     const tree = paper({
@@ -315,7 +339,7 @@ describe("studies — run from inside the paper folder", () => {
   it("names the folder `.`", () => {
     const tree = paper({
       [`${REPRO}/studies.json`]: registryText(P1()),
-      [`${REPRO}/README.md`]: withIndex("# I\n", P1()),
+      [`${REPRO}/README.md`]: withIndex("# I\n", P1(), NO_FACTS),
     });
     const out = studies({ sub: "index", paperDir: "." }, tree, DIR);
     expect([out.code, out.log]).toEqual([
@@ -330,12 +354,12 @@ describe("studies — the command line", () => {
     [
       "no subcommand",
       { sub: undefined },
-      'studies needs a subcommand: new or index — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir>',
+      'studies needs a subcommand: new, index or gate — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir> · npx paperlint studies gate <paper-dir> <id>',
     ],
     [
       "an unknown subcommand",
       { sub: "add" },
-      'unknown subcommand `studies add`: new or index — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir>',
+      'unknown subcommand `studies add`: new, index or gate — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir> · npx paperlint studies gate <paper-dir> <id>',
     ],
     [
       "new with no paper folder",

package/src/studies.ts

@@ -1,6 +1,8 @@
 /**
  * `paperlint studies new|index <paper-dir>` — the two commands that write a paper's study registry,
- * `repro/studies.json`, and its index in `repro/README.md` (docs/design/study-registry.md).
+ * `repro/studies.json`, and its index in `repro/README.md` (docs/design/study-registry.md) — and
+ * `studies gate <paper-dir> <id>` (src/study-gate.ts), over the studies' modes
+ * (docs/design/study-modes.md).
  *
  *   new <paper-dir> "<title>" [--kind <kind>]
  *            the next id; `repro/<id>-<slug>/README.md` with the id and title in its frontmatter, and
@@ -23,7 +25,7 @@ import {
   STUDIES_FILE,
   STUDY_KINDS,
   addStudy,
-  indexInSync,
+  indexCurrent,
   isStudyKind,
   planTemplate,
   planText,
@@ -36,8 +38,12 @@ import {
 } from "./domain/study-registry.ts";
 import type { Files } from "./ports/files.ts";
 import type { StudyRegistryCodec } from "./ports/study-registry-codec.ts";
+import type { ListEntries } from "./ports/list-entries.ts";
 import type { ListDir } from "./ports/talk-media.ts";
-import { registryOf } from "./study-registry-rule.ts";
+import { readableFolders, registryOf } from "./study-registry-rule.ts";
+import { runGate } from "./study-gate.ts";
+import { indexInputOf } from "./study-index-input.ts";
+import type { GitHistory, GitOrder } from "./ports/git-history.ts";
 
 /** What one `studies` run was asked, after the command line. */
 export interface StudiesArgs {
@@ -52,8 +58,10 @@ export interface StudiesArgs {
 }
 
 export interface StudiesDeps {
+  readonly git: GitHistory & GitOrder;
   readonly files: Files;
   readonly listDir: ListDir;
+  readonly entries: ListEntries;
   readonly codec: StudyRegistryCodec;
   readonly cwd: string;
   /** Today, `YYYY-MM-DD`: the root reads the clock. */
@@ -65,7 +73,8 @@ export interface StudiesDeps {
 const NEW_USAGE =
   'npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]';
 const INDEX_USAGE = "npx paperlint studies index <paper-dir>";
-const SUBS = `new or index — ${NEW_USAGE} · ${INDEX_USAGE}`;
+const GATE_USAGE = "npx paperlint studies gate <paper-dir> <id>";
+const SUBS = `new, index or gate — ${[NEW_USAGE, INDEX_USAGE, GATE_USAGE].join(" · ")}`;
 
 const STATUS_FILE = "PIPELINE-STATUS.md";
 
@@ -93,10 +102,26 @@ function registryIn(p: Paper, deps: StudiesDeps): StudyRegistry | Refusal {
     case "unreadable":
       return refuse(1, `${file} is not a study registry: ${r.why}`);
     case "read":
-      return r.registry;
+      return escaping(p, r.registry, deps) ?? r.registry;
   }
 }
 
+/** The refusal when a row names a folder that is not one inside `repro/`; null when none does. */
+function escaping(
+  p: Paper,
+  r: StudyRegistry,
+  deps: StudiesDeps,
+): Refusal | null {
+  const readable = readableFolders(p.dir, deps);
+  const s = r.studies.find((row) => !readable(row.folder));
+  return s === undefined
+    ? null
+    : refuse(
+        1,
+        `${s.id} in ${p.shown}/${REPRO_DIR}/${STUDIES_FILE} names the folder \`${s.folder}\`, which is not one folder inside ${REPRO_DIR}/: nothing is read or written through it. Give the row its own folder's name, then run this again.`,
+      );
+}
+
 const isRefusal = (v: unknown): v is Refusal =>
   typeof v === "object" && v !== null && "code" in v && "line" in v;
 
@@ -115,12 +140,13 @@ const studiesCount = (r: StudyRegistry): string =>
  * Write the index of `r` into the README; whether it wrote. A block already in sync is left as it
  * is, so the padding a formatter gave the table is never undone.
  */
-function writeIndex(dir: string, r: StudyRegistry, files: Files): boolean {
-  const before = readmeOf(dir, files);
-  if (indexInSync(before, r)) return false;
-  files.writeAtomic(
+function writeIndex(dir: string, r: StudyRegistry, deps: StudiesDeps): boolean {
+  const before = readmeOf(dir, deps.files);
+  const at = indexInputOf(dir, { kind: "read", registry: r }, deps);
+  if (indexCurrent(before, r, at)) return false;
+  deps.files.writeAtomic(
     callerPath(join(dir, REPRO_DIR, README)),
-    text(withIndex(before, r)),
+    text(withIndex(before, r, at)),
   );
   return true;
 }
@@ -155,7 +181,7 @@ function runIndex(
   if (blocked !== null) return blocked;
   const readme = `${p.shown}/${REPRO_DIR}/${README}`;
   return [
-    writeIndex(p.dir, r, deps.files)
+    writeIndex(p.dir, r, deps)
       ? `wrote the index of ${studiesCount(r)} in ${readme}`
       : `the index in ${readme} is in sync with ${studiesCount(r)}`,
   ];
@@ -186,18 +212,19 @@ function newArgs(
 function writeStudy(
   p: Paper,
   added: { readonly registry: StudyRegistry; readonly study: Study },
-  files: Files,
+  deps: StudiesDeps,
 ): readonly string[] {
   const { study, registry } = added;
+  const { files } = deps;
   const at = (...names: readonly string[]): AbsolutePath =>
     callerPath(join(p.dir, REPRO_DIR, ...names));
   files.writeAtomic(at(study.folder, README), text(studyReadme(study)));
   files.writeAtomic(
     at(study.folder, PLAN_FILE),
-    text(planText(planTemplate())),
+    text(planText(planTemplate(study.kind, study.folder))),
   );
   files.writeAtomic(at(STUDIES_FILE), text(registryText(registry)));
-  writeIndex(p.dir, registry, files);
+  writeIndex(p.dir, registry, deps);
   const repro = `${p.shown}/${REPRO_DIR}`;
   return [
     `created ${repro}/${study.folder}/${README}`,
@@ -228,35 +255,69 @@ function runNew(
         1,
         `${p.shown}/${REPRO_DIR}/${folder}/ already exists; it is never overwritten. Register it by hand, or remove it and run this again.`,
       )
-    : writeStudy(p, added, deps.files);
+    : writeStudy(p, added, deps);
 }
 
 /** The paper folder the command line names, or the refusal. */
-function paperOf(a: StudiesArgs, deps: StudiesDeps): Refusal | Paper {
+function paperOf(a: StudiesArgs, deps: StudiesDeps): Refusal | Chosen {
   if (a.sub === undefined)
     return refuse(2, `studies needs a subcommand: ${SUBS}`);
-  if (a.sub !== "new" && a.sub !== "index")
+  const sub = COMMANDS.get(a.sub);
+  if (sub === undefined)
     return refuse(2, `unknown subcommand \`studies ${a.sub}\`: ${SUBS}`);
   if (a.paperDir === undefined)
-    return refuse(
-      2,
-      `studies ${a.sub} needs the paper's folder: ${a.sub === "new" ? NEW_USAGE : INDEX_USAGE}`,
-    );
+    return refuse(2, `studies ${a.sub} needs the paper's folder: ${sub.usage}`);
   const dir = resolve(deps.cwd, a.paperDir);
   const shown = relative(deps.cwd, dir) || ".";
   return deps.files.isFile(callerPath(join(dir, STATUS_FILE)))
-    ? { dir, shown }
+    ? { dir, shown, run: sub.run }
     : refuse(2, `${shown} is not a paper folder: it has no ${STATUS_FILE}`);
 }
 
+/** `gate`: the study's id, one argument, then the gate. */
+const gateRun = (
+  p: Paper,
+  a: StudiesArgs,
+  deps: StudiesDeps,
+): Refusal | readonly string[] => {
+  if (a.title === undefined)
+    return refuse(2, `studies gate needs the study's id: ${GATE_USAGE}`);
+  const [surplus] = a.extra;
+  if (surplus !== undefined)
+    return refuse(
+      2,
+      `studies gate takes the paper's folder and one id — \`${surplus}\` is one argument too many`,
+    );
+  const out = runGate(p.dir, p.shown, a.title, deps);
+  return out.ok ? out.lines : out.refusal;
+};
+
+/** A run of a subcommand over a paper folder. */
+type Run = (
+  p: Paper,
+  a: StudiesArgs,
+  d: StudiesDeps,
+) => Refusal | readonly string[];
+
+/** The paper folder, and the run the subcommand chose. */
+interface Chosen extends Paper {
+  readonly run: Run;
+}
+
+/** Each subcommand: its usage line and its run. */
+const COMMANDS: ReadonlyMap<
+  string,
+  { readonly usage: string; readonly run: Run }
+> = new Map([
+  ["new", { usage: NEW_USAGE, run: runNew }],
+  ["index", { usage: INDEX_USAGE, run: runIndex }],
+  ["gate", { usage: GATE_USAGE, run: gateRun }],
+]);
+
 /** The run: 0 done, 1 refused by the paper's state, 2 refused by the command line. */
 export function runStudies(a: StudiesArgs, deps: StudiesDeps): number {
   const p = paperOf(a, deps);
-  const out = isRefusal(p)
-    ? p
-    : a.sub === "new"
-      ? runNew(p, a, deps)
-      : runIndex(p, a, deps);
+  const out = isRefusal(p) ? p : p.run(p, a, deps);
   if (isRefusal(out)) {
     deps.err(out.line);
     return out.code;

package/src/study-gate.test.ts

@@ -0,0 +1,316 @@
+/**
+ * `paperlint studies gate <paper-dir> <id>` (`src/study-gate.ts`) on papers held in memory, git a
+ * stand-in: 0 once the decision is committed as it stands, 1 with the reason otherwise — and 0 for a
+ * study whose run waits on nothing, saying why.
+ */
+import { expect, it } from "vitest";
+import type { StudyMode } from "./domain/study-mode.ts";
+import {
+  DATE,
+  DECIDED,
+  DIR,
+  ROW,
+  SHA,
+  planOf,
+  studies,
+  tree,
+} from "../test/study-tree.ts";
+const DECISION = `${DIR}/repro/P1-S01-outcome/decision.md`;
+const decided = (mode: StudyMode = DECIDED) => tree({}, planOf(mode));
+
+it("open once the decision is committed as it stands: exit 0 with its commit and date", () => {
+  const r = studies(
+    "gate",
+    decided(),
+    {},
+    {
+      git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } },
+    },
+  );
+  // Guards: the line a runner's log keeps, and the exit code `gate && run` reads.
+  expect([r.code, r.log, r.err]).toEqual([
+    0,
+    [
+      `P1-S01: the decision repro/P1-S01-outcome/decision.md is committed in ${SHA} (${DATE}); the run may start.`,
+    ],
+    [],
+  ]);
+});
+
+it("closed while the decision is uncommitted, changed since its commit, or unknown to git", () => {
+  const gate = (state: Parameters<typeof studies>[3]) =>
+    studies("gate", decided(), {}, state);
+  // Guards: each reason the run must wait is said, exit 1.
+  expect(
+    [
+      gate({}),
+      gate({ git: { [DECISION]: { kind: "changed", commit: SHA } } }),
+      gate({
+        git: { [DECISION]: { kind: "unknown", why: "git is not installed" } },
+      }),
+    ].map((r) => [r.code, r.err]),
+  ).toEqual([
+    [
+      1,
+      [
+        "P1-S01: the decision repro/P1-S01-outcome/decision.md is not committed; the run waits for it. Write the decision there, commit it, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        `P1-S01: the decision repro/P1-S01-outcome/decision.md has changed since its last commit, ${SHA}; the run waits for the decision as committed. Commit it, then run this again.`,
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: git could not say whether the decision repro/P1-S01-outcome/decision.md is committed: git is not installed.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a plan that names no decision file, or one its own outputs match", () => {
+  // Guards: a gate on nothing, or on a file the run itself produces, is no gate.
+  expect([
+    studies("gate", decided({ ...DECIDED, decision: { file: " ", note: "n" } }))
+      .err,
+    studies("gate", decided({ ...DECIDED, outputs: ["*.md"] })).err,
+  ]).toEqual([
+    [
+      "P1-S01: its plan.json is a draft — `mode.decision.file` is empty; the run waits for a ready plan. Fill it in, then run this again.",
+    ],
+    [
+      "P1-S01: its decision repro/P1-S01-outcome/decision.md is matched by its output `*.md`; a decision cannot be what its own run produces.",
+    ],
+  ]);
+});
+
+it("an exploratory study's run waits on nothing: exit 0, saying so", () => {
+  // Guards: the runner may call gate on every study; the answer names the mode.
+  expect(
+    studies("gate", decided({ kind: "exploratory", reason: "a first look" })),
+  ).toMatchObject({
+    code: 0,
+    log: [
+      "P1-S01 is exploratory (a first look): it has no gate, and its results are reported as exploratory.",
+    ],
+  });
+});
+
+it("refuses a study that declares no mode, and one whose row names a folder outside repro/", () => {
+  // Guards: a measurement with no mode is not gated by default — it is refused until it says how;
+  // and a row naming `../x` is never read through, so no file outside the paper decides the gate.
+  expect(
+    [
+      studies("gate", tree({}, planOf(undefined))),
+      studies(
+        "gate",
+        tree(
+          {
+            [`${DIR}/x/plan.json`]: JSON.stringify(planOf(DECIDED)),
+          },
+          planOf(DECIDED),
+          { ...ROW, folder: "../x" },
+        ),
+      ),
+    ].map((r) => [r.code, r.err]),
+  ).toEqual([
+    [
+      1,
+      [
+        "P1-S01 declares no mode in papers/example: no row of papers/example/repro/studies.json with this id names a plan.json that parses with `mode`. Lint the paper (`npx paperlint lint`) to see why.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its row names the folder `../x`, which is not one folder inside papers/example/repro/; nothing is read through it. Give the row its own folder's name.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a command line without the study's id, or with an argument too many", () => {
+  // Guards: exit 2 is the command line's, never the paper's state.
+  expect(
+    [
+      studies("gate", decided(), { title: undefined }),
+      studies("gate", decided(), { extra: ["P1-S02"] }),
+    ].map((r) => [r.code, r.err]),
+  ).toEqual([
+    [
+      2,
+      [
+        "studies gate needs the study's id: npx paperlint studies gate <paper-dir> <id>",
+      ],
+    ],
+    [
+      2,
+      [
+        "studies gate takes the paper's folder and one id — `P1-S02` is one argument too many",
+      ],
+    ],
+  ]);
+});
+
+it("a plan it cannot read through declares no mode: no registry, a plan outside its folder, a NUL, not JSON", () => {
+  const noMode = (t: Readonly<Record<string, string>>) =>
+    studies("gate", t).err[0]?.split(":")[0];
+  const withoutRegistry = Object.fromEntries(
+    Object.entries(decided()).filter(([k]) => !k.endsWith("studies.json")),
+  );
+  // Guards: each is refused as declaring no mode — none is read past, none opens the gate.
+  expect([
+    noMode(withoutRegistry),
+    noMode(tree({}, planOf(DECIDED), { ...ROW, plan: "../plan.json" })),
+    noMode(tree({}, planOf(DECIDED), { ...ROW, plan: "a\0b.json" })),
+    noMode({ ...decided(), [`${DIR}/repro/P1-S01-outcome/plan.json`]: "{" }),
+  ]).toEqual(Array(4).fill("P1-S01 declares no mode in papers/example"));
+});
+
+it("refuses a decision that names a directory, whatever git says of it", () => {
+  const dir = "repro/P1-S01-outcome/decisions";
+  const r = studies(
+    "gate",
+    tree(
+      { [`${DIR}/${dir}/a.md`]: "exclude run 7\n" },
+      planOf({ ...DECIDED, decision: { file: dir, note: "n" } }),
+    ),
+    {},
+    {
+      git: {
+        [`${DIR}/${dir}`]: { kind: "committed", commit: SHA, date: DATE },
+      },
+    },
+  );
+  // Guards: git answers for a directory with the last commit under it — never a decision as committed.
+  expect([r.code, r.err]).toEqual([
+    1,
+    [
+      `P1-S01: its decision ${dir} is a directory, not a file; the run cannot be gated on it. Name the decision file in \`mode.decision.file\`.`,
+    ],
+  ]);
+});
+
+it("closed when the decision was committed and then deleted: it is not in HEAD", () => {
+  const r = studies(
+    "gate",
+    decided(),
+    {},
+    { git: { [DECISION]: { kind: "deleted", commit: SHA } } },
+  );
+  // Guards: a decision deleted in a later commit leaves a clean tree, and still gates nothing.
+  expect([r.code, r.err]).toEqual([
+    1,
+    [
+      `P1-S01: the decision repro/P1-S01-outcome/decision.md is not in HEAD: it was deleted in ${SHA}; the run waits for a decision that stands. Restore it, commit it, then run this again.`,
+    ],
+  ]);
+});
+
+it("refuses a plan that is still a draft: a mode is no decision until its plan is ready", () => {
+  const r = studies(
+    "gate",
+    decided({ ...DECIDED, outputs: [] }),
+    {},
+    { git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } } },
+  );
+  const blankReason = studies(
+    "gate",
+    decided({ kind: "exploratory", reason: " " }),
+  );
+  const twoEmpty = studies(
+    "gate",
+    decided({
+      ...DECIDED,
+      outputs: [],
+      decision: { ...DECIDED.decision, note: "" },
+    }),
+  );
+  // Guards: a draft names no outputs to keep from the decision, and an exploratory plan with no
+  // reason is no declaration; the gate opens on a ready plan only, whatever its mode.
+  expect([
+    [r.code, r.err],
+    [blankReason.code, blankReason.err],
+    [twoEmpty.code, twoEmpty.err],
+  ]).toEqual([
+    [
+      1,
+      [
+        "P1-S01: its plan.json is a draft — `mode.outputs` is empty; the run waits for a ready plan. Fill it in, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its plan.json is a draft — `mode.reason` is empty; the run waits for a ready plan. Fill it in, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its plan.json is a draft — `mode.outputs`, `mode.decision.note` are empty; the run waits for a ready plan. Fill it in, then run this again.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a decision or a study folder that is a symbolic link", () => {
+  const committed = {
+    [DECISION]: { kind: "committed", commit: SHA, date: DATE },
+  } as const;
+  const decisionLink = studies(
+    "gate",
+    { ...decided(), [DECISION]: "exclude run 7\n" },
+    {},
+    { git: committed, links: [DECISION] },
+  );
+  const folderLink = studies(
+    "gate",
+    decided(),
+    {},
+    { git: committed, links: [`${DIR}/repro/P1-S01-outcome`] },
+  );
+  // Guards: git records a link, not the file it points to; a linked folder leads out of `repro/`.
+  expect([
+    [decisionLink.code, decisionLink.err],
+    [folderLink.code, folderLink.err],
+  ]).toEqual([
+    [
+      1,
+      [
+        "P1-S01: its decision repro/P1-S01-outcome/decision.md is a symbolic link, not a file; the run cannot be gated on it. Name the decision file in `mode.decision.file`.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its row names the folder `P1-S01-outcome`, which is not one folder inside papers/example/repro/; nothing is read through it. Give the row its own folder's name.",
+      ],
+    ],
+  ]);
+});
+
+it("never reads a plan through a backslash: `..\\x\\plan.json` is outside the folder on Windows", () => {
+  const plan = "..\\x\\plan.json";
+  const r = studies(
+    "gate",
+    tree(
+      {
+        [`${DIR}/repro/P1-S01-outcome/${plan}`]: JSON.stringify(
+          planOf(DECIDED),
+        ),
+      },
+      planOf(DECIDED),
+      { ...ROW, plan },
+    ),
+    {},
+    { git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } } },
+  );
+  // Guards: the containment test is the registry rule's own `isInside`, the same on every platform.
+  expect(r.err[0]?.split(":")[0]).toBe(
+    "P1-S01 declares no mode in papers/example",
+  );
+});