paperlint 10.2.0 → 10.4.0

package/skills/camera-ready/SKILL.md

@@ -4,7 +4,7 @@ description: On acceptance, turn the anonymized-for-review paper into the de-ano
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch]
 ---
 
-<!-- vigiles:sha256:1c9ad89e55c3e89a compiled from skills/camera-ready/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:66444fd7ce0e56a0 compiled from skills/camera-ready/SKILL.md.spec.ts -->
 
 # camera-ready — de-anonymize an accepted paper into the final proceedings version
 
@@ -73,6 +73,11 @@ The review artifact was an OSF anonymized view-only link. The camera-ready needs
   or `\doi{}`.
 - Keep the artifact **self-checking** (it still recomputes every headline number and exits non-zero on
   drift) — de-anonymizing it doesn't excuse it from reproducing the paper.
+- **Ship each study's evidence of its mode**: its `plan.json`, 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. The public repo keeps the **whole git history** — the order of
+  decision and outputs is read from it (`repro/outputs-before-decision`), and a squashed or shallow
+  copy loses it.
 
 ## 3. Responsible disclosure (security papers — BEFORE public release)
 For the AISec "Safety Theater" paper the studied hooks are named-but-anonymized, and disclosure to the

package/skills/camera-ready/SKILL.md.spec.ts

@@ -88,6 +88,11 @@ The review artifact was an OSF anonymized view-only link. The camera-ready needs
   or \`\\doi{}\`.
 - Keep the artifact **self-checking** (it still recomputes every headline number and exits non-zero on
   drift) — de-anonymizing it doesn't excuse it from reproducing the paper.
+- **Ship each study's evidence of its mode**: its \`plan.json\`, 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. The public repo keeps the **whole git history** — the order of
+  decision and outputs is read from it (\`repro/outputs-before-decision\`), and a squashed or shallow
+  copy loses it.
 
 ## 3. Responsible disclosure (security papers — BEFORE public release)
 For the AISec "Safety Theater" paper the studied hooks are named-but-anonymized, and disclosure to the

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/run-agent-grid/SKILL.md

@@ -4,7 +4,7 @@ description: "Run a paid or counted agent experiment grid end to end — units
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:522a747e8eb6ead4 compiled from skills/run-agent-grid/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:451354b8f781c409 compiled from skills/run-agent-grid/SKILL.md.spec.ts -->
 
 # run-agent-grid — running a counted agent grid without spoiling it
 
@@ -25,10 +25,15 @@ and a driver loop that calls the guard: [`references/registry-and-ledger.md`](re
 
 **The grid's study folder.** A grid is one study of the paper. Its folder is made by
 `npx paperlint studies new <paper-dir> "<title>" --kind measurement` — the next id in
-`repro/studies.json`, the folder `repro/<id>-<slug>/` — and `grid.json`, the runs and the ledger live
-in it. When the grid ends, its row is updated (`status`, `result`, `result_file`, `in_paper`) and
-`npx paperlint studies index <paper-dir>` regenerates the index; `repro/study-registered` fails the
-lint until both are done.
+`repro/studies.json`, the folder `repro/<id>-<slug>/` with the study's `plan.json` — and `grid.json`,
+the runs and the ledger live in it. The plan says what the grid measures, the population and its
+draw (`{ "kind": "seeded", "method", "seed" }`), the `arms` (each name once) and the `primary_outcome`, and is filled before the first counted
+run; the author's approval of the drawn units goes into both `grid.json`'s `approval` (the guard reads
+it) and the plan's `author_check` (the lint reads it). A grid that is one study of a larger
+measurement names it in its row's `measurement`. When the grid ends, its row is updated (`status`,
+`result`, `result_file`, `in_paper`) and `npx paperlint studies index <paper-dir>` regenerates the
+index; `repro/study-registered` fails the lint until both are done, and on a running grid whose plan
+is empty.
 
 ## The order — each gate is passed before the next phase starts
 

package/skills/run-agent-grid/SKILL.md.spec.ts

@@ -26,10 +26,15 @@ and a driver loop that calls the guard: [\`references/registry-and-ledger.md\`](
 
 **The grid's study folder.** A grid is one study of the paper. Its folder is made by
 \`npx paperlint studies new <paper-dir> "<title>" --kind measurement\` — the next id in
-\`repro/studies.json\`, the folder \`repro/<id>-<slug>/\` — and \`grid.json\`, the runs and the ledger live
-in it. When the grid ends, its row is updated (\`status\`, \`result\`, \`result_file\`, \`in_paper\`) and
-\`npx paperlint studies index <paper-dir>\` regenerates the index; \`repro/study-registered\` fails the
-lint until both are done.
+\`repro/studies.json\`, the folder \`repro/<id>-<slug>/\` with the study's \`plan.json\` — and \`grid.json\`,
+the runs and the ledger live in it. The plan says what the grid measures, the population and its
+draw (\`{ "kind": "seeded", "method", "seed" }\`), the \`arms\` (each name once) and the \`primary_outcome\`, and is filled before the first counted
+run; the author's approval of the drawn units goes into both \`grid.json\`'s \`approval\` (the guard reads
+it) and the plan's \`author_check\` (the lint reads it). A grid that is one study of a larger
+measurement names it in its row's \`measurement\`. When the grid ends, its row is updated (\`status\`,
+\`result\`, \`result_file\`, \`in_paper\`) and \`npx paperlint studies index <paper-dir>\` regenerates the
+index; \`repro/study-registered\` fails the lint until both are done, and on a running grid whose plan
+is empty.
 
 ## The order — each gate is passed before the next phase starts
 

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" }],
+    },
+  ]);
+});