paperlint 10.3.0 → 10.4.1

package/skills/grade-paper-writing/prose-lint.test.ts

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "vitest";
-import { cpSync } from "node:fs";
+import { cpSync, readFileSync } from "node:fs";
 import { layRecord, recordedTree } from "../../test/recorded-fixture.ts";
 import { runNode, useTempDir, writeTree } from "../../test/support.ts";
 
@@ -62,6 +62,16 @@ const TREE = {
   "commented/paper.tex": tex(
     `Prose here.\n% \\caption{Commented ${LONG_CAPTION_SENTENCE}.}\n\\begin{verbatim}\n\\caption{Quoted ${LONG_CAPTION_SENTENCE}.}\n\\end{verbatim}\n\\begin{figure}\\caption{Real ${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
   ),
+  // The caption command with an optional argument, and with a space before its brace.
+  "optarg/paper.tex": tex(
+    `Prose here. \\begin{figure}\\caption[Short]{${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
+  ),
+  "spaced/paper.tex": tex(
+    `Prose here. \\begin{figure}\\caption {${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
+  ),
+  "negated/paper.tex": tex(
+    "It is not fast. It is not small. It is not red. Nothing here is plain.",
+  ),
   "ends-on-marks/paper.tex": tex(
     "The method holds on every input~\\cite{knuth}. The proof is given in full (Section~\\ref{proof}). The result is new.",
   ),
@@ -83,6 +93,9 @@ const READ: Readonly<Record<string, readonly string[]>> = {
   inline: ["paper.tex", "sec/results.tex"],
   commented: ["paper.tex"],
   "ends-on-marks": ["paper.tex"],
+  negated: ["paper.tex"],
+  optarg: ["paper.tex"],
+  spaced: ["paper.tex"],
   empty: ["paper.tex"],
 };
 writeTree(
@@ -182,6 +195,23 @@ test("--flags-only: an over-long caption flags and exits 1", () => {
   expect(r.stderr).toMatchSnapshot();
 });
 
+test("--flags-only: a metric over its threshold (not a caption) is a finding too, and the report flags the same line", () => {
+  const file = join(root, "negated", "paper.tex");
+  const only = runNode(SCRIPT, ["--flags-only", file]);
+  const report = runNode(SCRIPT, [file]);
+  // Guards: the mode promised "print nothing on a clean paper, any output means a finding" and
+  // looked only at captions; the metrics the report FLAGs are findings of the same kind.
+  assert.deepEqual(
+    { status: only.status, stdout: only.stdout },
+    { status: 1, stdout: "" },
+  );
+  expect(only.stderr).toMatchSnapshot();
+  assert.match(
+    report.stdout,
+    /^FLAG sentences whose main claim is a negation: 75%$/m,
+  );
+});
+
 test("--flags-only: a paper with no figures directory is clean, exit 0 and silent", () => {
   assert.deepEqual(
     runNode(SCRIPT, ["--flags-only", join(root, "clean", "paper.tex")]),
@@ -248,17 +278,13 @@ test("🔴 --flags-only reads the captions of the paper.tex and of the files it
       stdout: r.stdout,
       flagged: r.stderr
         .split("\n")
-        .filter((l) => l.startsWith("   "))
+        .filter((l) => l.startsWith("      > "))
         .map((l) => l.split(":")[0]),
     },
     {
       status: 1,
       stdout: "",
-      flagged: [
-        "   paper.tex",
-        "   sec/results.tex",
-        "   run prose-lint.mjs on the file without --flags-only for the sentences",
-      ],
+      flagged: ["      > paper.tex", "      > sec/results.tex"],
     },
   );
 });
@@ -274,8 +300,14 @@ test("--flags-only on a rendered page reads the captions in figures/*.tex beside
     join(root, "rendered", "page.txt"),
   ]);
   assert.deepEqual(
-    { status: r.status, first: r.stderr.split("\n")[1]?.split(":")[0] },
-    { status: 1, first: "   figures/f.tex" },
+    {
+      status: r.status,
+      first: r.stderr
+        .split("\n")
+        .find((l) => l.startsWith("      > "))
+        ?.split(":")[0],
+    },
+    { status: 1, first: "      > figures/f.tex" },
   );
   // …and a page with no figures/ beside it has no caption to flag.
   assert.deepEqual(runNode(SCRIPT, ["--flags-only", join(root, "page.txt")]), {
@@ -296,9 +328,86 @@ test("🔴 a caption commented out or quoted in verbatim is not measured; a real
       status: r.status,
       findings: r.stderr
         .split("\n")
-        .filter((l) => l.startsWith("   paper.tex:"))
+        .filter((l) => l.startsWith("      > paper.tex:"))
         .map((l) => /— "(\w+)/.exec(l)?.[1]),
     },
     { status: 1, findings: ["Real"] },
   );
 });
+
+/** The `prose-lint.mjs` invocations SKILL.md documents (Step 6), their arguments with `<paper-dir>` filled in. */
+const documentedInvocations = (paperDir: string): readonly string[][] =>
+  readFileSync(join(dirname(SCRIPT), "SKILL.md"), "utf8")
+    .split("\n")
+    .flatMap((line) => {
+      const m =
+        /node \$\{CLAUDE_SKILL_DIR\}\/prose-lint\.mjs ([^#]+?)\s*(#|$)/.exec(
+          line,
+        );
+      return m?.[1] === undefined
+        ? []
+        : [m[1].replaceAll("<paper-dir>", paperDir).split(/\s+/)];
+    });
+
+test("🔴 the invocation SKILL.md documents reports an over-long caption, with no flag the skill does not name", () => {
+  const documented = documentedInvocations(join(root, "p"));
+  // Guards: the report is the documented way to run the checks (Step 6), and captions were
+  // measured only under an undocumented flag — an over-long caption produced no finding.
+  const report = documented.find((a) => !a.includes("--headings"));
+  assert.ok(report !== undefined, "SKILL.md documents a report invocation");
+  const r = runNode(SCRIPT, report);
+  assert.deepEqual(
+    {
+      status: r.status,
+      flagged: r.stdout
+        .split("\n")
+        .filter(
+          (l) => l.startsWith("FLAG figure captions") || l.includes("caption"),
+        ),
+    },
+    {
+      status: 0,
+      flagged: [
+        "FLAG figure captions over the limit: 2",
+        '       > figures/fig1.tex: caption sentence of 46 words (warn >40) — "Big. word0 word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 wor…"',
+        "       > figures/fig1.tex: caption is 106 words (warn >100) — a caption this long is a section under a picture",
+      ],
+    },
+  );
+});
+
+test("the report says a paper whose captions are within the limits is clean on that line", () => {
+  const r = runNode(SCRIPT, [join(root, "clean", "paper.tex")]);
+  // Guards: the line is printed on a clean paper too, so its absence is never read as a pass.
+  assert.match(r.stdout, /^ok {3}figure captions over the limit: 0$/m);
+});
+
+test("🔴 a caption with an optional argument, or a space before its brace, is measured", () => {
+  const found = (dir: string) => {
+    const r = runNode(SCRIPT, [join(root, dir, "paper.tex")]);
+    return [
+      r.status,
+      /^FLAG figure captions over the limit: (\d+)$/m.exec(r.stdout)?.[1],
+    ];
+  };
+  // Guards: the scan matched `\caption{` only, so `\caption[Short]{…}` and `\caption {…}` were never
+  // read and the report printed "ok ... 0" for a long caption.
+  expect([found("optarg"), found("spaced")]).toEqual([
+    [0, "1"],
+    [0, "1"],
+  ]);
+});
+
+test("🔴 the caption of the package's own p1 fixture, which has an optional argument, is reported", () => {
+  const p1 = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "fixtures",
+    "paper-sources",
+    "p1",
+    "paper.tex",
+  );
+  const r = runNode(SCRIPT, ["--flags-only", p1]);
+  assert.match(r.stderr, /— "Optional-arg caption this sentence/);
+});

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/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- vigiles:sha256:f51051aae2ef09f8 compiled from src/CLAUDE.md.spec.ts -->
+<!-- vigiles:sha256:599c83e36edde981 compiled from src/CLAUDE.md.spec.ts -->
 
 # CLAUDE.md
 
@@ -21,12 +21,15 @@ test — a parser for banal's JSON is pure and is still banal's.
 
 | element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
 | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `domain`  | `src/domain/`          | values and decisions in the paper's vocabulary                                                                                                                     | `domain`; `ts-essentials`, `node:path`, `node:crypto`                                                                   |
-| `port`    | `src/ports/`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | `domain`, `port`; the same three externals                                                                              |
-| `app`     | `src/*.ts`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | `domain`, `port`, `app`, the package's `.mjs`; Node's `util`/`url`/`module`                                             |
+| `domain`  | `src/domain/`          | values and decisions in the paper's vocabulary                                                                                                                     | `domain`; any package or Node built-in that is no tool package (`TOOL_PACKAGES`) and no effect |
+| `port`    | `src/ports/`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | `domain`, `port`; the same as the domain                                                                                   |
+| `app`     | `src/*.ts`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | `domain`, `port`, `app`, the package's `.mjs`; the same externals as the domain                                             |
 | `adapter` | `src/adapters/<tool>/` | everything that knows `<tool>` exists, pure parsers included; used through its `index.ts`                                                                          | `domain`, `port`, its own folder, its tool's packages, the package's `.mjs`. **Never** `app`, **never** another adapter |
 | `root`    | `src/cli.ts`           | reads `process.*`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
 
+A package that exists because of one external tool goes in `TOOL_PACKAGES` (`eslint.config.mjs`), in the same PR that
+adds its adapter; a pure utility library (`remeda`, `zod`, `ts-essentials`) needs nothing, and effects are axis B's.
+
 Folders are ELEMENTS of `eslint-plugin-boundaries`, single files are CATEGORIES (`root`, `app`,
 `test`, `io`): v7 matches element patterns as folders. Everyone — tests included — reaches an
 adapter through its `index.ts`; the files inside one adapter import each other freely.

package/src/CLAUDE.md.spec.ts

@@ -18,12 +18,15 @@ test — a parser for banal's JSON is pure and is still banal's.
 
 | element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
 | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; \`ts-essentials\`, \`node:path\`, \`node:crypto\`                                                                   |
-| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same three externals                                                                              |
-| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; Node's \`util\`/\`url\`/\`module\`                                             |
+| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; any package or Node built-in that is no tool package (\`TOOL_PACKAGES\`) and no effect |
+| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same as the domain                                                                                   |
+| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; the same externals as the domain                                             |
 | \`adapter\` | \`src/adapters/<tool>/\` | everything that knows \`<tool>\` exists, pure parsers included; used through its \`index.ts\`                                                                          | \`domain\`, \`port\`, its own folder, its tool's packages, the package's \`.mjs\`. **Never** \`app\`, **never** another adapter |
 | \`root\`    | \`src/cli.ts\`           | reads \`process.*\`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
 
+A package that exists because of one external tool goes in \`TOOL_PACKAGES\` (\`eslint.config.mjs\`), in the same PR that
+adds its adapter; a pure utility library (\`remeda\`, \`zod\`, \`ts-essentials\`) needs nothing, and effects are axis B's.
+
 Folders are ELEMENTS of \`eslint-plugin-boundaries\`, single files are CATEGORIES (\`root\`, \`app\`,
 \`test\`, \`io\`): v7 matches element patterns as folders. Everyone — tests included — reaches an
 adapter through its \`index.ts\`; the files inside one adapter import each other freely.

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