paperlint 10.3.0 → 10.4.0

package/skills/draft-paper/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the numbers exist and it's time to WRITE the paper — "dr
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:c8d25c21dc01a742 compiled from skills/draft-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:a68aebea0917e4a6 compiled from skills/draft-paper/SKILL.md.spec.ts -->
 
 # draft-paper — prose that survives review and gets cited
 
@@ -33,9 +33,17 @@ number in the body stays in the body**.
    study, and — for security — the explicit threat model (attacker goals/capabilities/knowledge). A
    fuzzy threat model is the fastest reject at a security venue.
 4. **Method** — the reusable core. How the measurement/benchmark is *constructed* so someone else can
-   run it on a different target. This is the part that gets cited; give it the most care.
+   run it on a different target. This is the part that gets cited; give it the most care. **It states
+   each study's mode from the index, never from memory:** run `npx paperlint studies index <paper-dir>`, then read
+   each reported study's `mode`, `decision` and `first output` columns in `repro/README.md` and
+   write one sentence per study — decided before its run, with the decision's commit and date (and
+   its first output's, which came after); an exploratory study named exploratory, with its reason.
+   A study whose `decision` reads `not committed` was not decided before its run: say so.
 5. **Results** — the numbers from `build-benchmark`, each tied to a claim. Report ranges/CIs, not
-   rounded maxes. One figure or table carries the paper — make it legible standalone.
+   rounded maxes. One figure or table carries the paper — make it legible standalone. A number from
+   an exploratory study says "exploratory" where it is reported; "pre-registered" or "decided before"
+   only for a study the index shows as `decide_before_run` with its decision committed before its
+   first output.
 6. **Threats to validity** — construct / internal / external, honestly (see below). This section is a
    trust signal, not a confession.
 7. **Related work** — position against the *nearest* neighbor explicitly ("X measures A; we measure B

package/skills/draft-paper/SKILL.md.spec.ts

@@ -39,9 +39,17 @@ number in the body stays in the body**.
    study, and — for security — the explicit threat model (attacker goals/capabilities/knowledge). A
    fuzzy threat model is the fastest reject at a security venue.
 4. **Method** — the reusable core. How the measurement/benchmark is *constructed* so someone else can
-   run it on a different target. This is the part that gets cited; give it the most care.
+   run it on a different target. This is the part that gets cited; give it the most care. **It states
+   each study's mode from the index, never from memory:** run \`npx paperlint studies index <paper-dir>\`, then read
+   each reported study's \`mode\`, \`decision\` and \`first output\` columns in \`repro/README.md\` and
+   write one sentence per study — decided before its run, with the decision's commit and date (and
+   its first output's, which came after); an exploratory study named exploratory, with its reason.
+   A study whose \`decision\` reads \`not committed\` was not decided before its run: say so.
 5. **Results** — the numbers from \`build-benchmark\`, each tied to a claim. Report ranges/CIs, not
-   rounded maxes. One figure or table carries the paper — make it legible standalone.
+   rounded maxes. One figure or table carries the paper — make it legible standalone. A number from
+   an exploratory study says "exploratory" where it is reported; "pre-registered" or "decided before"
+   only for a study the index shows as \`decide_before_run\` with its decision committed before its
+   first output.
 6. **Threats to validity** — construct / internal / external, honestly (see below). This section is a
    trust signal, not a confession.
 7. **Related work** — position against the *nearest* neighbor explicitly ("X measures A; we measure B

package/skills/harden-paper/SKILL.md

@@ -4,7 +4,7 @@ description: Use when asking "is this paper actually ready to submit?" / "what's
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:35f1ec023504e0ce compiled from skills/harden-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:85001dd768358bb5 compiled from skills/harden-paper/SKILL.md.spec.ts -->
 
 # harden-paper — the multi-axis pre-submit gate
 
@@ -61,8 +61,18 @@ middle sags" — wasting the polish on possibly-cut sections.
      there with no pointer reaching it, the body is overclaiming and "it's in the appendix" is not
      a defence — reviewers are not required to read appendices, and ARR says so in as many words.
      Rule and the sorting test: `paper-pipeline/references/body-vs-appendix.md`.
+   - 🔴 **A confirmatory claim on a study that was not confirmatory.** Every claim the paper presents
+     as tested — a prediction, a hypothesis confirmed, a headline effect — must rest on a study whose
+     `mode` is `decide_before_run` and whose `decision` commit precedes its `first output`, read
+     from the index in `repro/README.md` after `npx paperlint studies index <paper-dir>` (the plans and git, not
+     the prose). A confirmatory claim on an exploratory study, on one whose decision reads `not
+     committed`, or on one whose first output is not after its decision, is a **soundness** finding,
+     not a wording one: re-label the result exploratory, or rest the claim on a study decided first.
+     Flag every "pre-registered", "preregistered", "registered in advance" or "decided before" the
+     table does not support, and check the Methods sentence names each study's mode as the table does.
    Mechanical leg: `tex/claim-provenance` (axis 7) reports every sentence that states a number and
-   does not say whose it is.
+   does not say whose it is; `repro/outputs-before-decision` every output that entered history
+   before its decision.
 
 3. **Novelty vs the nearest neighbor** — the scoop check. Search for the paper that *already did your
    thing* (`verify-citations` covers metadata; here, actively hunt the closest empirical/method twin).

package/skills/harden-paper/SKILL.md.spec.ts

@@ -78,8 +78,18 @@ middle sags" — wasting the polish on possibly-cut sections.
      there with no pointer reaching it, the body is overclaiming and "it's in the appendix" is not
      a defence — reviewers are not required to read appendices, and ARR says so in as many words.
      Rule and the sorting test: \`paper-pipeline/references/body-vs-appendix.md\`.
+   - 🔴 **A confirmatory claim on a study that was not confirmatory.** Every claim the paper presents
+     as tested — a prediction, a hypothesis confirmed, a headline effect — must rest on a study whose
+     \`mode\` is \`decide_before_run\` and whose \`decision\` commit precedes its \`first output\`, read
+     from the index in \`repro/README.md\` after \`npx paperlint studies index <paper-dir>\` (the plans and git, not
+     the prose). A confirmatory claim on an exploratory study, on one whose decision reads \`not
+     committed\`, or on one whose first output is not after its decision, is a **soundness** finding,
+     not a wording one: re-label the result exploratory, or rest the claim on a study decided first.
+     Flag every "pre-registered", "preregistered", "registered in advance" or "decided before" the
+     table does not support, and check the Methods sentence names each study's mode as the table does.
    Mechanical leg: \`tex/claim-provenance\` (axis 7) reports every sentence that states a number and
-   does not say whose it is.
+   does not say whose it is; \`repro/outputs-before-decision\` every output that entered history
+   before its decision.
 
 3. **Novelty vs the nearest neighbor** — the scoop check. Search for the paper that *already did your
    thing* (\`verify-citations\` covers metadata; here, actively hunt the closest empirical/method twin).

package/skills/osf-artifact-upload/SKILL.md

@@ -4,7 +4,7 @@ description: Upload or replace a paper's reproduction artifact file on an OSF pr
 allowed-tools: [Read, Write, Grep, Glob, Bash]
 ---
 
-<!-- vigiles:sha256:334c907233abc97c compiled from skills/osf-artifact-upload/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:953fdd419dbc789c compiled from skills/osf-artifact-upload/SKILL.md.spec.ts -->
 
 # osf-artifact-upload — push/replace a file on an OSF project via API
 
@@ -45,6 +45,12 @@ curl -g -s --retry 3 --cacert $CA -H "$AUTH" -X PUT --data-binary @"$ZIP" "${UP}
 Verification that actually holds: **OSF-stored md5 == `md5sum $ZIP`**. The upload response also returns the
 md5; matching it to the local file is proof even when the download-back call flakes.
 
+## What the artifact ships about each study
+Before zipping, the artifact carries, for every study the paper reports: its `plan.json` (its mode)
+and its decision file; and `repro/README.md` with the index regenerated (`npx paperlint studies index <paper-dir>`)
+— each study's mode, decision commit and first output — with the command that re-checks the order
+(`npx paperlint lint` on a full clone). A zip without them asks a reviewer to take the modes on trust.
+
 ## After
 - Confirm the paper's Availability `\url{}` still points at the same node (it does — same guid).
 - Tell the user to **revoke the token** (osf.io/settings/tokens → Delete).

package/skills/osf-artifact-upload/SKILL.md.spec.ts

@@ -51,6 +51,12 @@ curl -g -s --retry 3 --cacert $CA -H "$AUTH" -X PUT --data-binary @"$ZIP" "\${UP
 Verification that actually holds: **OSF-stored md5 == \`md5sum $ZIP\`**. The upload response also returns the
 md5; matching it to the local file is proof even when the download-back call flakes.
 
+## What the artifact ships about each study
+Before zipping, the artifact carries, for every study the paper reports: its \`plan.json\` (its mode)
+and its decision file; and \`repro/README.md\` with the index regenerated (\`npx paperlint studies index <paper-dir>\`)
+— each study's mode, decision commit and first output — with the command that re-checks the order
+(\`npx paperlint lint\` on a full clone). A zip without them asks a reviewer to take the modes on trust.
+
 ## After
 - Confirm the paper's Availability \`\\url{}\` still points at the same node (it does — same guid).
 - Tell the user to **revoke the token** (osf.io/settings/tokens → Delete).

package/skills/pc-panel-review/SKILL.md

@@ -4,7 +4,7 @@ description: Use when asking "what would the program committee decide?" / "simul
 allowed-tools: [Read, Write, Grep, Glob, Bash, WebSearch, WebFetch, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:7e5fb04d1cfa0548 compiled from skills/pc-panel-review/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:d92a744ec1cc1b05 compiled from skills/pc-panel-review/SKILL.md.spec.ts -->
 
 # pc-panel-review — model the whole PC, not one reviewer
 
@@ -61,11 +61,18 @@ prose-only read can.
      and calls the paper a blog post — the one reviewer a panel of careful full readers never
      predicts. Give it the three sections as text and the venue's name, nothing else.
    - **Methods/stats skeptic** — sample size, construct validity, multiple comparisons, overclaims,
-     whether the CIs support the claims.
+     whether the CIs support the claims, and **whether every confirmatory claim rests on a study
+     decided before its run**. Run `npx paperlint studies index <paper-dir>` and give this reviewer the index in
+     `repro/README.md` (each study's `mode`, `decision` and `first output`) beside the paper: a
+     claim of a tested prediction on an exploratory study, on one whose decision reads `not
+     committed`, or on one whose first output is not after its decision is a soundness finding, and
+     so is a "pre-registered" or "decided before" the table does not support; the reviewer names it.
    - **Domain practitioner** — relevance to the CFP, novelty vs the nearest prior work, does the
      finding change behavior, generalizability, fairness/tone toward anyone named.
    - **Artifact / reproducibility reviewer (MANDATORY if an artifact is attached)** — *actually
-     `cd` into the artifact and run it*; verify every headline number reproduces; read the code for
+     `cd` into the artifact and run it*; verify every headline number reproduces; re-run the order
+     check the paper's decided-before claims rest on (`npx paperlint lint` on a full clone); read the
+     code for
      circularity (echoing stored fields vs recomputing); grep all files (incl. data + compiled
      caches) for anonymization leaks; scope the badge (Available / Functional / Reproduced).
    - **Security/ethics reviewer** (security venues) — threat model soundness, responsible disclosure,

package/skills/pc-panel-review/SKILL.md.spec.ts

@@ -77,11 +77,18 @@ prose-only read can.
      and calls the paper a blog post — the one reviewer a panel of careful full readers never
      predicts. Give it the three sections as text and the venue's name, nothing else.
    - **Methods/stats skeptic** — sample size, construct validity, multiple comparisons, overclaims,
-     whether the CIs support the claims.
+     whether the CIs support the claims, and **whether every confirmatory claim rests on a study
+     decided before its run**. Run \`npx paperlint studies index <paper-dir>\` and give this reviewer the index in
+     \`repro/README.md\` (each study's \`mode\`, \`decision\` and \`first output\`) beside the paper: a
+     claim of a tested prediction on an exploratory study, on one whose decision reads \`not
+     committed\`, or on one whose first output is not after its decision is a soundness finding, and
+     so is a "pre-registered" or "decided before" the table does not support; the reviewer names it.
    - **Domain practitioner** — relevance to the CFP, novelty vs the nearest prior work, does the
      finding change behavior, generalizability, fairness/tone toward anyone named.
    - **Artifact / reproducibility reviewer (MANDATORY if an artifact is attached)** — *actually
-     \`cd\` into the artifact and run it*; verify every headline number reproduces; read the code for
+     \`cd\` into the artifact and run it*; verify every headline number reproduces; re-run the order
+     check the paper's decided-before claims rest on (\`npx paperlint lint\` on a full clone); read the
+     code for
      circularity (echoing stored fields vs recomputing); grep all files (incl. data + compiled
      caches) for anonymization leaks; scope the badge (Available / Functional / Reproduced).
    - **Security/ethics reviewer** (security venues) — threat model soundness, responsible disclosure,

package/skills/tighten-paper/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when a paper \"feels long / bloated / overly complex / hard to
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent]
 ---
 
-<!-- vigiles:sha256:c57d6da372b28acf compiled from skills/tighten-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:ccf39ff26a2146e9 compiled from skills/tighten-paper/SKILL.md.spec.ts -->
 
 # tighten-paper — the developmental edit
 
@@ -149,6 +149,10 @@ called it "fat for no reason" after a pass that cut almost nothing and left it 1
   measurement paper's fat HIDES as explanation of real numbers, which is exactly why "it's all numbers" lets it
   survive a lazy pass (GateBench 2026-07-25: a pass cut only 5% hiding behind this; the author correctly pushed
   back that whole sections were over-explained, not just number-dense).
+- **The study-mode sentence is never cut for length.** The Methods sentence that says a study was
+  decided before its run (with its decision's commit and date, from the index in `repro/README.md`)
+  or is exploratory — and the word "exploratory" beside an exploratory number — is the claim's
+  warrant, not its explanation: cut around it, never it.
 - **"Fold to the artifact" is the PRIMARY length lever for a measurement/benchmark paper — not a last resort.**
   FIRST verify the artifact exists and recomputes the numbers (it usually does for these papers). Then per-case
   breakdowns, secondary analyses, exhaustive robustness sub-results, ablation walkthroughs, and every "we also

package/skills/tighten-paper/SKILL.md.spec.ts

@@ -155,6 +155,10 @@ called it "fat for no reason" after a pass that cut almost nothing and left it 1
   measurement paper's fat HIDES as explanation of real numbers, which is exactly why "it's all numbers" lets it
   survive a lazy pass (GateBench 2026-07-25: a pass cut only 5% hiding behind this; the author correctly pushed
   back that whole sections were over-explained, not just number-dense).
+- **The study-mode sentence is never cut for length.** The Methods sentence that says a study was
+  decided before its run (with its decision's commit and date, from the index in \`repro/README.md\`)
+  or is exploratory — and the word "exploratory" beside an exploratory number — is the claim's
+  warrant, not its explanation: cut around it, never it.
 - **"Fold to the artifact" is the PRIMARY length lever for a measurement/benchmark paper — not a last resort.**
   FIRST verify the artifact exists and recomputes the numbers (it usually does for these papers). Then per-case
   breakdowns, secondary analyses, exhaustive robustness sub-results, ablation walkthroughs, and every "we also

package/src/adapters/git/history.test.ts

@@ -0,0 +1,121 @@
+/**
+ * The git ports over a REAL repository in a scratch directory: the committed state of a decision,
+ * and the order of every output's first commit against the decision's — after, the same commit, or
+ * not after — a deleted output included, and a shallow clone named as such.
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { expect, it } from "vitest";
+import { absolutePath } from "../../domain/paths.ts";
+import { spawnProcess } from "../node/index.ts";
+import { commit, git, initRepo } from "../../../test/git-repo.ts";
+import { useTempDir } from "../../../test/support.ts";
+import { gitHistory } from "./index.ts";
+
+const root = useTempDir("git-history-");
+const ports = gitHistory(spawnProcess(), { PATH: String(process.env.PATH) });
+const T1 = "2026-10-16T10:00:00+05:00";
+const T2 = "2026-10-16T11:00:00+05:00";
+const T3 = "2026-10-16T12:00:00+05:00";
+
+it("a decision committed, then changed, then never committed: three states", () => {
+  const repo = join(root, "committed");
+  initRepo(repo);
+  const sha = commit(repo, { "p/decision.md": "exclusions: none\n" }, T1);
+  const paper = absolutePath(join(repo, "p"));
+  const file = absolutePath(join(repo, "p/decision.md"));
+  // Guards: the commit and its date as git records them.
+  expect(ports.committed(paper, file)).toEqual({
+    kind: "committed",
+    commit: sha,
+    date: T1,
+  });
+  writeFileSync(file, "exclusions: run 7\n");
+  // Guards: an edit after the commit is not the recorded decision.
+  expect(ports.committed(paper, file)).toEqual({
+    kind: "changed",
+    commit: sha,
+  });
+  writeFileSync(join(repo, "p/new.md"), "x\n");
+  expect(ports.committed(paper, absolutePath(join(repo, "p/new.md")))).toEqual({
+    kind: "not-committed",
+  });
+});
+
+it("outputs after the decision, in its commit, before it, and deleted since: each with its order", () => {
+  const repo = join(root, "order");
+  initRepo(repo);
+  const early = commit(repo, { "p/repro/S/early.csv": "1\n" }, T1);
+  const decided = commit(
+    repo,
+    { "p/repro/S/decision.md": "d\n", "p/repro/S/same.csv": "2\n" },
+    T2,
+  );
+  const later = commit(
+    repo,
+    { "p/repro/S/later.csv": "3\n", "p/repro/S/early.csv": null },
+    T3,
+  );
+  // Guards: the order is read from ancestry; a deleted early output is still evidence.
+  expect(
+    ports.order(
+      absolutePath(join(repo, "p/repro/S")),
+      absolutePath(join(repo, "p/repro/S/decision.md")),
+    ),
+  ).toEqual({
+    kind: "read",
+    decision: { commit: decided, date: T2 },
+    decisionDeleted: false,
+    files: [
+      { path: "early.csv", commit: early, date: T1, order: "not-after" },
+      { path: "decision.md", commit: decided, date: T2, order: "same" },
+      { path: "same.csv", commit: decided, date: T2, order: "same" },
+      { path: "later.csv", commit: later, date: T3, order: "after" },
+    ],
+  });
+});
+
+it("a shallow clone is named, not judged", () => {
+  const repo = join(root, "deep");
+  initRepo(repo);
+  commit(repo, { "p/repro/S/decision.md": "d\n" }, T1);
+  commit(repo, { "p/repro/S/out.csv": "1\n" }, T2);
+  const shallow = join(root, "shallow");
+  git(root, ["clone", "-q", "--depth", "1", `file://${repo}`, shallow]);
+  // Guards: a CI checkout of depth 1 says so instead of reading every file as born in one commit.
+  expect(
+    ports.order(
+      absolutePath(join(shallow, "p/repro/S")),
+      absolutePath(join(shallow, "p/repro/S/decision.md")),
+    ),
+  ).toEqual({ kind: "shallow" });
+});
+
+it("outside any repository, git's own refusal is the reason", () => {
+  const r = ports.order(absolutePath("/"), absolutePath("/decision.md"));
+  // Guards: no repository is "unknown", never an empty history.
+  expect(r.kind).toBe("unknown");
+});
+
+it("a decision committed and deleted in a later commit is not in HEAD: never `committed`", () => {
+  const repo = join(root, "deleted");
+  initRepo(repo);
+  const sha = commit(repo, { "p/repro/S/decision.md": "d\n" }, T1);
+  const gone = commit(repo, { "p/repro/S/decision.md": null }, T2);
+  const paper = absolutePath(join(repo, "p"));
+  const file = absolutePath(join(repo, "p/repro/S/decision.md"));
+  // Guards: `git log -1` names the deletion and the tree is clean, yet there is no decision to gate on;
+  // the order still reads the decision's first commit, and says it is gone.
+  expect([
+    ports.committed(paper, file),
+    ports.order(absolutePath(join(repo, "p/repro/S")), file),
+  ]).toEqual([
+    { kind: "deleted", commit: gone },
+    {
+      kind: "read",
+      decision: { commit: sha, date: T1 },
+      decisionDeleted: true,
+      files: [{ path: "decision.md", commit: sha, date: T1, order: "same" }],
+    },
+  ]);
+});

package/src/adapters/git/index.test.ts

@@ -0,0 +1,268 @@
+/**
+ * The git ports over a scripted `RunProcess`: the commands they run and each answer git can give —
+ * including each way git can fail to give one. The same ports over a real repository are in
+ * `history.test.ts` beside this file.
+ */
+import { expect, it } from "vitest";
+import { exitedWith, scriptedProcess } from "../memory/index.ts";
+import { absolutePath } from "../../domain/paths.ts";
+import type { Command, ProcessExit } from "../../ports/process.ts";
+import { firstCommitsOf, gitHistory } from "./index.ts";
+
+const PAPER = absolutePath("/repo/papers/p");
+const FILE = absolutePath("/repo/papers/p/repro/S/decision.md");
+const STUDY = absolutePath("/repo/papers/p/repro/S");
+const D = "d".repeat(40);
+const A = "a".repeat(40);
+const B = "b".repeat(40);
+const DATE = "2026-10-16T15:23:00+05:00";
+
+/** HEAD's tree holds the decision, unless a test says otherwise. */
+const IN_HEAD = exitedWith("repro/S/decision.md\n");
+
+/**
+ * The ports over git answering by its subcommand (`args[2]`, after `-c core.quotepath=false`); the
+ * decision in HEAD's tree unless `ls-tree` is answered.
+ */
+const over = (answers: Readonly<Record<string, ProcessExit>>) => {
+  const all: Readonly<Record<string, ProcessExit>> = {
+    "ls-tree": IN_HEAD,
+    ...answers,
+  };
+  const run = scriptedProcess(
+    (c: Command) => all[String(c.args[2])] ?? exitedWith(""),
+  );
+  return { git: gitHistory(run, { PATH: "/usr/bin" }), calls: run.calls };
+};
+
+it("committed: the last commit and its date when the file is as committed — asked from the paper", () => {
+  const { git, calls } = over({ log: exitedWith(`${D}\t${DATE}\n`) });
+  // Guards: the answer, and that git runs in the paper's folder with the file's absolute path.
+  expect(git.committed(PAPER, FILE)).toEqual({
+    kind: "committed",
+    commit: D,
+    date: DATE,
+  });
+  expect(calls.map((c) => [c.args, c.cwd])).toEqual([
+    [
+      [
+        "-c",
+        "core.quotepath=false",
+        "log",
+        "-1",
+        "--format=%H%x09%cI",
+        "--",
+        FILE,
+      ],
+      PAPER,
+    ],
+    [
+      [
+        "-c",
+        "core.quotepath=false",
+        "ls-tree",
+        "--name-only",
+        "HEAD",
+        "--",
+        FILE,
+      ],
+      PAPER,
+    ],
+    [
+      ["-c", "core.quotepath=false", "status", "--porcelain=v1", "--", FILE],
+      PAPER,
+    ],
+  ]);
+});
+
+it("committed: a decision whose last commit deleted it is not in HEAD — deleted, never committed", () => {
+  // Guards: `log -1` names the deleting commit and the status is clean; only HEAD's tree tells.
+  expect([
+    over({
+      log: exitedWith(`${D}\t${DATE}\n`),
+      "ls-tree": exitedWith(""),
+    }).git.committed(PAPER, FILE),
+    over({
+      log: exitedWith(`${D}\t${DATE}\n`),
+      "ls-tree": { kind: "spawn-failed", message: "EIO" },
+    }).git.committed(PAPER, FILE),
+  ]).toEqual([
+    { kind: "deleted", commit: D },
+    { kind: "unknown", why: "EIO" },
+  ]);
+});
+
+it("committed: changed since its commit, never committed, or git unable to say at either step", () => {
+  // Guards: an edited decision is not the recorded one; a file only on disk records nothing.
+  expect([
+    over({
+      log: exitedWith(`${D}\t${DATE}\n`),
+      status: exitedWith(" M decision.md\n"),
+    }).git.committed(PAPER, FILE),
+    over({ log: exitedWith("") }).git.committed(PAPER, FILE),
+    over({ log: { kind: "not-found", file: "git" } }).git.committed(
+      PAPER,
+      FILE,
+    ),
+    over({
+      log: exitedWith(`${D}\t${DATE}\n`),
+      status: { kind: "spawn-failed", message: "EACCES" },
+    }).git.committed(PAPER, FILE),
+  ]).toEqual([
+    { kind: "changed", commit: D },
+    { kind: "not-committed" },
+    { kind: "unknown", why: "git is not installed" },
+    { kind: "unknown", why: "EACCES" },
+  ]);
+});
+
+it("every way git can fail is a reason, never an answer", () => {
+  const ask = (x: ProcessExit) =>
+    over({ "rev-parse": x }).git.order(STUDY, FILE);
+  // Guards: no git, no repository, a hang, a kill — each named, none read as "no commits".
+  expect([
+    ask(exitedWith("", 128)),
+    ask({
+      kind: "exited",
+      status: 128,
+      stdout: "",
+      stderr: "fatal: not a git repository\n",
+    }),
+    ask({ kind: "timed-out", afterMs: 1, stdout: "", stderr: "" }),
+    ask({ kind: "signalled", signal: "SIGTERM", stdout: "", stderr: "" }),
+  ]).toEqual([
+    { kind: "unknown", why: "git exited 128" },
+    { kind: "unknown", why: "fatal: not a git repository" },
+    { kind: "unknown", why: "git did not finish (timed-out)" },
+    { kind: "unknown", why: "git did not finish (signalled)" },
+  ]);
+});
+
+it("order: a shallow clone is said, not judged", () => {
+  // Guards: in a shallow clone every file starts at the clone — no order can be read.
+  expect(
+    over({ "rev-parse": exitedWith("true\n") }).git.order(STUDY, FILE),
+  ).toEqual({ kind: "shallow" });
+});
+
+it("order: each file's first commit against the decision's — after, the same, not after", () => {
+  const log = `\x01${D}\t${DATE}\nx.csv\n\x01${A}\t${DATE}\na.csv\nx.csv\n\x01${B}\t${DATE}\nb.csv\n`;
+  // Guards: the decision's own commit is `same`; the others are ordered by ancestry.
+  const result = gitHistory(
+    scriptedProcess((c) => {
+      const sub = String(c.args[2]);
+      if (sub === "rev-parse") return exitedWith("false\n");
+      if (sub === "ls-tree") return IN_HEAD;
+      if (sub === "log" && c.args.includes("--reverse")) return exitedWith(log);
+      if (sub === "log") return exitedWith(`${A}\t${DATE}\n${D}\t${DATE}\n`);
+      return exitedWith("", String(c.args[5]) === A ? 0 : 1);
+    }),
+    {},
+  ).order(STUDY, FILE);
+  expect(result).toEqual({
+    kind: "read",
+    decision: { commit: D, date: DATE },
+    decisionDeleted: false,
+    files: [
+      { path: "x.csv", commit: D, date: DATE, order: "same" },
+      { path: "a.csv", commit: A, date: DATE, order: "after" },
+      { path: "b.csv", commit: B, date: DATE, order: "not-after" },
+    ],
+  });
+});
+
+it("order: no decision commit makes every file not-after; a failed ancestry question is a reason", () => {
+  const log = `\x01${A}\t${DATE}\na.csv\n`;
+  const answer = (mergeBase: ProcessExit, decisionLog: string) =>
+    gitHistory(
+      scriptedProcess((c) => {
+        const sub = String(c.args[2]);
+        if (sub === "rev-parse") return exitedWith("false\n");
+        if (sub === "ls-tree") return IN_HEAD;
+        if (sub === "log" && c.args.includes("--reverse"))
+          return exitedWith(log);
+        if (sub === "log") return exitedWith(decisionLog);
+        return mergeBase;
+      }),
+      {},
+    ).order(STUDY, FILE);
+  // Guards: an uncommitted decision orders nothing; git failing mid-way is not "not after".
+  expect(answer(exitedWith(""), "")).toEqual({
+    kind: "read",
+    decision: null,
+    decisionDeleted: false,
+    files: [{ path: "a.csv", commit: A, date: DATE, order: "not-after" }],
+  });
+  expect(
+    answer(
+      {
+        kind: "exited",
+        status: 128,
+        stdout: "",
+        stderr: "fatal: bad object\n",
+      },
+      `${D}\t${DATE}\n`,
+    ),
+  ).toEqual({ kind: "unknown", why: "fatal: bad object" });
+});
+
+it("order: git failing on the decision's log or the folder's log is a reason", () => {
+  const fail = {
+    kind: "exited",
+    status: 128,
+    stdout: "",
+    stderr: "fatal: x\n",
+  } as const;
+  const answer = (decision: ProcessExit, folder: ProcessExit) =>
+    gitHistory(
+      scriptedProcess((c) => {
+        const sub = String(c.args[2]);
+        if (sub === "rev-parse") return exitedWith("false\n");
+        return c.args.includes("--reverse") ? folder : decision;
+      }),
+      {},
+    ).order(STUDY, FILE);
+  // Guards: each step's failure surfaces.
+  expect([answer(fail, exitedWith("")), answer(exitedWith(""), fail)]).toEqual([
+    { kind: "unknown", why: "fatal: x" },
+    { kind: "unknown", why: "fatal: x" },
+  ]);
+});
+
+it("order: a decision not in HEAD is said deleted; git failing on HEAD's tree is a reason", () => {
+  const answer = (lsTree: ProcessExit) =>
+    gitHistory(
+      scriptedProcess((c) => {
+        const sub = String(c.args[2]);
+        if (sub === "rev-parse") return exitedWith("false\n");
+        if (sub === "ls-tree") return lsTree;
+        if (c.args.includes("--reverse"))
+          return exitedWith(`\x01${D}\t${DATE}\ndecision.md\n`);
+        return exitedWith(`${D}\t${DATE}\n`);
+      }),
+      {},
+    ).order(STUDY, FILE);
+  // Guards: the decision's first commit is still read, and its absence from HEAD is carried with it.
+  expect([
+    answer(exitedWith("")),
+    answer({ kind: "spawn-failed", message: "EIO" }),
+  ]).toEqual([
+    {
+      kind: "read",
+      decision: { commit: D, date: DATE },
+      decisionDeleted: true,
+      files: [{ path: "decision.md", commit: D, date: DATE, order: "same" }],
+    },
+    { kind: "unknown", why: "EIO" },
+  ]);
+});
+
+it("firstCommitsOf keeps each path's first commit and skips blank lines", () => {
+  // Guards: the reverse log is read oldest first; a later commit of a path does not move it.
+  expect([
+    ...firstCommitsOf(`\x01${A}\t${DATE}\na\n\n\x01${B}\t${DATE}\na\nb\n`),
+  ]).toEqual([
+    ["a", { commit: A, date: DATE }],
+    ["b", { commit: B, date: DATE }],
+  ]);
+});