@pmelab/gtd 26.0.0 → 27.0.0

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-import { C as EXIT_SIGTERM, D as WIRE_SCHEMA, E as UNATTRIBUTED_MODEL, O as renderFormat, S as EXIT_SIGINT, T as ACCESS_REFUSAL, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_USAGE_ERROR, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-DA7q2ikx.mjs";
-export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, resolveSession, selectPath, stallDiagnosis, statusOf };
+import { C as EXIT_SIGTERM, D as UNATTRIBUTED_MODEL, E as ACCESS_REFUSAL, O as WIRE_SCHEMA, S as EXIT_SIGINT, T as EXIT_USAGE_ERROR, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_STRAYS_FOUND, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-BY1S-obW.mjs";
+export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, resolveSession, selectPath, stallDiagnosis, statusOf };

package/dist/workflows/feature.mjs

@@ -1,6 +1,6 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, numeric, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars } from "../flows.mjs";
 import { review as review$1 } from "../workflow-kit.mjs";
-import { $ as unwindFailedMessage, A as architectureDecomposePrompt, B as designSystem, C as fixRisks, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as packagesItemBuildingPrompt, I as buildReviewTriageMessage, J as reviewEditsCapture, K as packagesItemFixSuitePrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as startGateBlockedMessage, R as deferNotesScript, S as fixCheck, T as reviewMissing, V as designTriagePrompt, W as idleMessage, X as reviewNotesCapture, Z as reviewerSystem, _ as FEEDBACK, b as awaitReview, c as refusePendingHandOff, d as defaults, et as unwindFailure, f as envDefaults, g as ARCHITECTURE, h as healthy, i as skills, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as tail, m as gate, n as summary, o as closeReview, q as reviewEditNotesCapture, r as access, t as steering, u as shipped, v as REQUIREMENTS, w as planner, x as coder, y as REVIEW, z as designGateAnswerMessage } from "../chunks/reserved-6pAgFGgB.mjs";
+import { $ as unwindFailedMessage, A as architectureDecomposePrompt, B as designSystem, C as fixRisks, D as agentWithSkills, E as reviewing, F as buildReviewFixNitsPrompt, G as packagesItemBuildingPrompt, I as buildReviewTriageMessage, J as reviewEditsCapture, K as packagesItemFixSuitePrompt, L as builderSystem, M as buildReviewAnswerQuestionsPrompt, N as buildReviewAwaitAfterDeferMessage, O as architectSystem, P as buildReviewCollectingPrompt, Q as startGateBlockedMessage, R as deferNotesScript, S as fixCheck, T as reviewMissing, V as designTriagePrompt, W as idleMessage, X as reviewNotesCapture, Z as reviewerSystem, _ as FEEDBACK, b as awaitReview, c as refusePendingHandOff, d as defaults, et as unwindFailure, f as envDefaults, g as ARCHITECTURE, h as healthy, i as skills, j as architectureGateAnswerMessage, k as architectureAuthorPrompt, l as tail, m as gate, n as summary, o as closeReview, q as reviewEditNotesCapture, r as access, t as steering, u as shipped, v as REQUIREMENTS, w as planner, x as coder, y as REVIEW, z as designGateAnswerMessage } from "../chunks/reserved-BL9krPao.mjs";
 //#region src/workflows/feature/steps.ts
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 const triage = (base) => agentWithSkills("triage", designTriagePrompt(base), {

package/dist/workflows/fix.mjs

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
-import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, a as REVIEW_ORIG, d as defaults, f as envDefaults, i as skills, n as summary, p as baseline, r as access, s as handOffTail, t as steering, u as shipped, x as coder, y as REVIEW } from "../chunks/reserved-6pAgFGgB.mjs";
+import { D as agentWithSkills, H as finisherSystem, U as fixReviewNotesPrompt, a as REVIEW_ORIG, d as defaults, f as envDefaults, i as skills, n as summary, p as baseline, r as access, s as handOffTail, t as steering, u as shipped, x as coder, y as REVIEW } from "../chunks/reserved-BL9krPao.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,5 +1,5 @@
 import { start } from "../flows.mjs";
-import { Y as reviewGateBlockedMessage, c as refusePendingHandOff, d as defaults, f as envDefaults, i as skills, m as gate, n as summary, r as access, s as handOffTail, t as steering, u as shipped } from "../chunks/reserved-6pAgFGgB.mjs";
+import { Y as reviewGateBlockedMessage, c as refusePendingHandOff, d as defaults, f as envDefaults, i as skills, m as gate, n as summary, r as access, s as handOffTail, t as steering, u as shipped } from "../chunks/reserved-BL9krPao.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "26.0.0",
+  "version": "27.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -106,7 +106,7 @@
     "postbuild": "node scripts/assert-no-test-doubles.mjs",
     "watch": "tsdown --watch",
     "bench:replay": "node scripts/bench-replay.mjs",
-    "test": "turbo run format:check typecheck lint lint:sh lint:boundaries test:unit test:workflows test:e2e:inmem test:e2e:live test:web analyze",
+    "test": "jiti scripts/test-states.main.ts",
     "test:unit": "vitest run --project unit",
     "test:workflows": "vitest run --project workflows",
     "test:watch": "vitest",

package/src/cli/Cli.test.ts

@@ -981,9 +981,60 @@ describe("parseArgv — gtd history", () => {
   })
 })
 
+describe("parseArgv — gtd strays", () => {
+  const strays = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", "strays", ...args])
+
+  it("splits the range at '..' and carries the globs", () => {
+    const plan = strays("main..feature", "src/**", "*.md")
+    expect(plan).toMatchObject({
+      kind: "command",
+      command: { kind: "strays", base: "main", tip: "feature", globs: ["src/**", "*.md"] },
+    })
+  })
+
+  it("an empty side becomes HEAD; no globs is an empty list", () => {
+    expect(strays("main..")).toMatchObject({
+      command: { base: "main", tip: "HEAD", globs: [] },
+    })
+    expect(strays("..main")).toMatchObject({ command: { base: "HEAD", tip: "main" } })
+    expect(strays("..")).toMatchObject({ command: { base: "HEAD", tip: "HEAD" } })
+  })
+
+  it("a missing range, a range without '..', a '...' range and a second '..' are usage errors", () => {
+    for (const args of [[], ["main"], ["main...feature"], ["a..b..c"]]) {
+      expect(strays(...args).kind).toBe("usage")
+    }
+    const plan = strays("main")
+    if (plan.kind === "usage") expect(plan.message).toContain("<base>..<tip>")
+  })
+
+  it("--json is in scope: bare and selected", () => {
+    expect(strays("a..b", "--json")).toMatchObject({ kind: "command", json: { kind: "document" } })
+    expect(strays("a..b", "--json=0")).toMatchObject({
+      kind: "command",
+      json: { kind: "select", path: "0" },
+    })
+  })
+
+  it("--json's scope error and help name strays", () => {
+    const plan = parseArgv(["node", "gtd.js", "lsp", "--json"])
+    if (plan.kind === "usage") expect(plan.message).toContain("`gtd strays`")
+    expect(renderHelp()).toContain("strays <range> [glob...]")
+    expect(renderHelp()).toContain("gtd strays only")
+  })
+})
+
 describe("standaloneKinds / needsOf", () => {
   it("pins the standalone kinds", () => {
-    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "loop", "judgeRun"])
+    expect(standaloneKinds()).toEqual([
+      "lsp",
+      "check",
+      "uncheck",
+      "install",
+      "loop",
+      "judgeRun",
+      "strays",
+    ])
   })
 
   it("needsOf matches none/fs for the standalone kinds and state for everything else", () => {
@@ -993,6 +1044,7 @@ describe("standaloneKinds / needsOf", () => {
     expect(needsOf("install")).toBe("none")
     expect(needsOf("loop")).toBe("none")
     expect(needsOf("judgeRun")).toBe("none")
+    expect(needsOf("strays")).toBe("none")
     for (const kind of [
       "land",
       "start",
@@ -1231,7 +1283,7 @@ describe("runCli — exit codes", () => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("gtd: init")
+    repo.seedCommit("gtd: init")
     const { io, captured } = capturingIo(() => testLayers(repo))
     await Effect.runPromise(runCli(["node", "gtd.js", "next", "--json=does.not.exist"], io))
     const { stdout, stderr, exitCode } = captured()
@@ -1316,7 +1368,7 @@ describe("runCli — stdout stays byte-empty on every failing surface", () => {
     // produce zero calls, not merely an empty joined string.
     const repo = new InMemRepo()
     repo.writeFile("README.md", "x\n")
-    repo.commitAllWithPrefix("chore: init gtd workflow")
+    repo.seedCommit("chore: init gtd workflow")
     repo.writeFile(".gtd/TODO.md", "## Open Questions\n\n###\n\nno question text.\n")
     const stdoutCalls: string[] = []
     const io: CliIo = {
@@ -1396,7 +1448,7 @@ describe("runCli — flush normalizes the artifact's trailing newline", () => {
     const repo = new InMemRepo()
     repo.writeFile(".gitignore", "node_modules\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("chore: initial commit")
+    repo.seedCommit("chore: initial commit")
     const { io, captured } = capturingIo(() => testLayers(repo))
     await Effect.runPromise(runCli(["node", "gtd.js", "land"], io))
     const { stdout } = captured()

package/src/cli/Cli.ts

@@ -29,7 +29,7 @@ import {
   type JsonMode,
 } from "./Program.js"
 import type { ToolCommands } from "./ToolCommands.js"
-import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
 
 export type { Command, CommandRequirements } from "./Program.js"
 export { needsOf, standaloneKinds } from "./Program.js"
@@ -96,15 +96,16 @@ const FLAGS: readonly FlagRow[] = [
       kind === "judgeAnswer" ||
       kind === "doors" ||
       kind === "historyList" ||
-      kind === "historyShow",
+      kind === "historyShow" ||
+      kind === "strays",
     decode: ([raw]) => Either.right(raw ?? ""),
     scopeError:
-      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show` — " +
+      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show`/`gtd strays` — " +
       "every other command prints plain text; see `gtd install` for the driver protocol briefing",
     valueHint: "<path>",
     help: [
       "(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd history",
-      "list/gtd history show only) output structured JSON. Bare --json prints the whole document;",
+      "list/gtd history show/gtd strays only) output structured JSON. Bare --json prints the whole document;",
       "--json=<path> (a dotted key path into that document, e.g.",
       "kind, content, session.id) prints just that value: a",
       "scalar raw and unquoted, a boolean as true/false, a list",
@@ -667,6 +668,25 @@ const COMMAND_ROWS: readonly CommandRow[] = [
       "every question, with nothing on stdout",
     ],
   },
+  {
+    token: "strays",
+    kind: "strays",
+    arity: { name: "range", variadic: "glob" },
+    details: [
+      "List the files <range> (<base>..<tip>, an empty side is HEAD)",
+      "touched in its committed net diff that match none of the",
+      "globs. Anchored at the repo root: * stays within one path",
+      "segment, ** crosses them, everything else is literal — quote",
+      "globs in the shell. stdout: a sorted JSON array, [] when",
+      "clean; stderr: a summary, plus one stray: line per path with",
+      "--verbose. --json=<n> picks one entry, nothing past the end;",
+      "a symlink is a path like any other, never followed; a",
+      "submodule counts as its path, whatever diff.ignoreSubmodules",
+      "or .gitmodules ignore say. Runs in any git repository, no",
+      "process needed. Exits 10 when",
+      "strays were found, 1 on an unknown revision, 2 on a bad range",
+    ],
+  },
   {
     token: "history list",
     kind: "historyList",
@@ -1228,6 +1248,28 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     }
   }
 
+  if (kind === "strays") {
+    const [range, ...globs] = restPositionals as [string, ...string[]]
+    const at = range.indexOf("..")
+    if (at < 0 || range.includes("...") || range.indexOf("..", at + 1) >= 0) {
+      return usagePlan(
+        `gtd strays: <range> must be <base>..<tip> (an empty side is HEAD) — got '${range}'`,
+        jsonSeen,
+      )
+    }
+    return {
+      kind: "command",
+      command: {
+        kind: "strays",
+        base: range.slice(0, at) || "HEAD",
+        tip: range.slice(at + 2) || "HEAD",
+        globs,
+      },
+      json,
+      verbose,
+    }
+  }
+
   if (kind === "uncheck") {
     return {
       kind: "command",
@@ -1419,9 +1461,9 @@ export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void,
     // where the whole buffered artifact is known-complete and safe to hand
     // to stdout (a failure discards the buffer instead — see
     // `bufferedArtifactOut`).
-    Effect.map(() => {
+    Effect.map((code) => {
       out.flush()
-      io.exit(EXIT_OK)
+      io.exit(code)
     }),
     Effect.provide(io.layers(plan.verbose)),
     Effect.sandbox,

package/src/cli/History.test.ts

@@ -36,7 +36,7 @@ const finishedProcess = async (repo: InMemRepo, file: string) => {
 const repoWithConfig = (): InMemRepo => {
   const repo = new InMemRepo()
   repo.writeFile("gtd.config.ts", CONFIG)
-  repo.commitAllWithPrefix("chore: add workflow")
+  repo.seedCommit("chore: add workflow")
   return repo
 }
 
@@ -90,7 +90,7 @@ describe("historyEntries", () => {
     const repo = repoWithConfig()
     const { entry: hash } = await finishedProcess(repo, "a.txt")
     repo.writeFile("x.txt", "x\n")
-    repo.commitAllWithPrefix("chore: bare tip")
+    repo.seedCommit("chore: bare tip")
     repo.updateRef(`refs/gtd/history/${hash}`, "HEAD")
     expect((await entries(repo))[0]?.branch).toBeNull()
   })

package/src/cli/Output.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 import { CommandRunner, GitService, Host, Narrator, Workspace } from "../platform/index.js"
-import { selectPath } from "../wire/index.js"
+import { selectPath, type EXIT_OK, type EXIT_STRAYS_FOUND } from "../wire/index.js"
 import { ConfigDiscovery, ConfigService } from "../workflow/index.js"
 import type { ToolCommands } from "./ToolCommands.js"
 
@@ -66,3 +66,5 @@ export type CommandRequirements =
   | Narrator
   | CommandRunner
   | ToolCommands
+
+export type SuccessExit = typeof EXIT_OK | typeof EXIT_STRAYS_FOUND

package/src/cli/Program.test.ts

@@ -60,7 +60,7 @@ const seed = (source: string, extra: Record<string, string> = {}): InMemRepo =>
   const repo = new InMemRepo()
   repo.writeFile("gtd.config.ts", source)
   for (const [path, content] of Object.entries(extra)) repo.writeFile(path, content)
-  repo.commitAllWithPrefix("chore: add custom workflow")
+  repo.seedCommit("chore: add custom workflow")
   return repo
 }
 
@@ -69,7 +69,7 @@ const seedBundled = (): InMemRepo => {
   const repo = new InMemRepo()
   repo.writeFile("README.md", "# test project\n")
   repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-  repo.commitAllWithPrefix("chore: init")
+  repo.seedCommit("chore: init")
   return repo
 }
 
@@ -199,7 +199,7 @@ describe("gtd --workflow <name> — the shipped workflows", () => {
     const repo = seedBundled()
     const base = repo.commitHistory().at(-1)!.hash
     repo.writeFile("scratch.txt", "more work\n")
-    repo.commitAllWithPrefix("chore: more work")
+    repo.seedCommit("chore: more work")
     const before = repo.commitHistory().length
     const { stdout, exitCode } = await run(
       repo,
@@ -288,7 +288,7 @@ describe("gtd next --json — log path emission", () => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("gtd: init")
+    repo.seedCommit("gtd: init")
     return repo
   }
 
@@ -703,7 +703,7 @@ describe("gtd next — refuses when history diverges from what replay reaches",
   const diverged = async (): Promise<InMemRepo> => {
     const repo = await atWorking()
     repo.writeFile("WORK.md", "done\n")
-    repo.commitAllWithPrefix("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1")
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1")
     return repo
   }
 
@@ -752,9 +752,7 @@ describe("a history written in a format this gtd does not read", () => {
     const repo = seed(IDLE_THEN_WORKING)
     await landTurn(repo, { "NOTE.md": "a note\n" })
     repo.writeFile("WORK.md", "done\n")
-    repo.commitAllWithPrefix(
-      "gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 2",
-    )
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 2")
     return repo
   }
 
@@ -779,7 +777,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("refuses even when a foreign subject hides the commit from the episode", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.commitAllWithPrefix("gtd2[human] idle -> working\n\nGtd-Format: 2")
+    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 2")
     for (const command of ["next", "abandon"]) {
       const { exitCode, stderr } = await run(repo, command)
       expect(exitCode).toBe(1)
@@ -790,7 +788,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("a commit gtd never wrote is not read for a format, even quoting the trailer", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.commitAllWithPrefix("feat: x\n\nGtd-Format: 2")
+    repo.seedCommit("feat: x\n\nGtd-Format: 2")
     expect((await run(repo, "next")).exitCode).toBe(0)
   })
 
@@ -798,7 +796,7 @@ describe("a history written in a format this gtd does not read", () => {
     const repo = seed(IDLE_THEN_WORKING)
     const base = repo.resolveRef("HEAD")!
     repo.writeFile("NOTE.md", "a note\n")
-    repo.commitAllWithPrefix("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 2")
+    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 2")
     repo.updateRef(HISTORY_REF, repo.resolveRef("HEAD")!)
     repo.hardResetTo(base)
     const { exitCode, stderr } = await run(repo, "restore")
@@ -1695,6 +1693,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
     historyList: { kind: "historyList" },
     historyShow: { kind: "historyShow", ref: "x" },
     historyFetch: { kind: "historyFetch", remote: "origin" },
+    strays: { kind: "strays", base: "HEAD", tip: "HEAD", globs: [] },
   }
 
   const stateKinds = (Object.keys(commandFor) as Command["kind"][]).filter(
@@ -1949,7 +1948,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-    repo.commitAllWithPrefix("gtd: init")
+    repo.seedCommit("gtd: init")
     return repo
   }
 

package/src/cli/Program.ts

@@ -42,6 +42,7 @@ import {
   type NextMatch,
   type StatusChange,
   selectPath,
+  EXIT_OK,
 } from "../wire/index.js"
 import {
   currentRest,
@@ -94,13 +95,16 @@ import {
   type ArtifactOut,
   type CommandRequirements,
   type JsonMode,
+  type SuccessExit,
 } from "./Output.js"
 export {
   SelectorUsageError,
   type ArtifactOut,
   type CommandRequirements,
   type JsonMode,
+  type SuccessExit,
 } from "./Output.js"
+import { runStraysCommand } from "./Strays.js"
 import { runHistoryFetchCommand, runHistoryListCommand, runHistoryShowCommand } from "./History.js"
 
 /**
@@ -161,6 +165,13 @@ export type Command =
   | { readonly kind: "historyList" }
   | { readonly kind: "historyShow"; readonly ref: string }
   | { readonly kind: "historyFetch"; readonly remote: string }
+  | {
+      readonly kind: "strays"
+      /** Each side of `<base>..<tip>`; an empty side is `HEAD`, as git reads it. */
+      readonly base: string
+      readonly tip: string
+      readonly globs: readonly string[]
+    }
   | {
       readonly kind: "judgeRun"
       readonly provider?: "fixed" | "jev" | "llm"
@@ -1149,6 +1160,7 @@ export const needsOf = (kind: Command["kind"]): Needs => {
     case "install":
     case "loop":
     case "judgeRun":
+    case "strays":
       return "none"
     case "check":
     case "uncheck":
@@ -1166,18 +1178,27 @@ export const standaloneKinds = (): readonly Command["kind"][] => [
   "install",
   "loop",
   "judgeRun",
+  "strays",
 ]
 
 /**
  * Dispatches to the named `run*Command` handler for every `Command.kind` —
  * the counterpart of `Cli.ts`'s `parseArgv`, which has already validated
- * every field a handler receives. A command choosing its own exit code is
- * unrepresentable: every branch returns `Effect<void>`, and `Cli.ts`'s
- * `runCli` supplies `EXIT_OK` once, after this Effect succeeds.
+ * every field a handler receives. Only `strays` chooses its exit code; every
+ * other branch returns `Effect<void>` and resolves to `EXIT_OK`.
  */
+const dispatchCommand = (
+  command: Command,
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<SuccessExit, Error, CommandRequirements> => {
+  if (command.kind === "strays") return runStraysCommand(command, json, out)
+  return Effect.as(dispatchVoidCommand(command, json, out), EXIT_OK)
+}
+
 // fallow-ignore-next-line complexity
 const dispatchVoidCommand = (
-  command: Command,
+  command: Exclude<Command, { kind: "strays" }>,
   json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> => {
@@ -1255,8 +1276,8 @@ export const runCommand = (
   command: Command,
   json: JsonMode,
   out: ArtifactOut,
-): Effect.Effect<void, Error, CommandRequirements> => {
-  const dispatch = dispatchVoidCommand(command, json, out)
+): Effect.Effect<SuccessExit, Error, CommandRequirements> => {
+  const dispatch = dispatchCommand(command, json, out)
   if (needsOf(command.kind) !== "state") return dispatch
   return Effect.gen(function* () {
     const git = yield* GitService
@@ -1278,6 +1299,6 @@ export const runCommand = (
     for (const warning of config.warnings) {
       yield* narrator.warn(`gtd: warning: ${formatDiagnostic(warning)}`)
     }
-    yield* dispatch
+    return yield* dispatch
   })
 }

package/src/cli/Strays.test.ts

@@ -0,0 +1,88 @@
+import { Effect } from "effect"
+import { describe, expect, it } from "vitest"
+import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import { InMemRepo, makeCapturingCliIo } from "../testkit/index.js"
+import { runCli } from "./index.js"
+
+const seed = (): InMemRepo => {
+  const repo = new InMemRepo()
+  repo.writeFile("README.md", "x\n")
+  repo.commitAllWithPrefix("base")
+  repo.updateRef("base", "HEAD")
+  repo.writeFile("src/a.ts", "a\n")
+  repo.writeFile("notes/b.md", "b\n")
+  repo.writeFile("notes/c.md", "c\n")
+  repo.commitAllWithPrefix("work")
+  return repo
+}
+
+const strays = async (repo: InMemRepo, ...args: string[]) => {
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", "strays", ...args], io))
+  return result()
+}
+
+describe("gtd strays — stderr commentary", () => {
+  it("quiet: only the N of M summary", async () => {
+    const { stderr, exitCode } = await strays(seed(), "base..HEAD", "src/**")
+    expect(stderr).toBe("gtd strays: 2 of 3 touched files outside the allowlist\n")
+    expect(exitCode).toBe(EXIT_STRAYS_FOUND)
+  })
+
+  it("--verbose: one stray: line per path, then the summary", async () => {
+    const { stderr } = await strays(seed(), "base..HEAD", "src/**", "--verbose")
+    expect(stderr).toBe(
+      'stray: "notes/b.md"\nstray: "notes/c.md"\ngtd strays: 2 of 3 touched files outside the allowlist\n',
+    )
+  })
+
+  it("a path with a line break and an escape reaches stderr JSON-quoted", async () => {
+    const repo = seed()
+    repo.writeFile("x\n\x1b[2J", "x\n")
+    repo.commitAllWithPrefix("odd")
+    const { stderr } = await strays(repo, "base..HEAD", "src/**", "--verbose")
+    expect(stderr).toContain('stray: "x\\n\\u001b[2J"\n')
+    expect(stderr).not.toContain("\x1b")
+  })
+
+  it("clean run: the single all-inside line", async () => {
+    const { stderr, exitCode } = await strays(seed(), "base..HEAD", "src/**", "notes/*")
+    expect(stderr).toBe("gtd strays: no strays — 3 touched files, all inside the allowlist\n")
+    expect(exitCode).toBe(EXIT_OK)
+  })
+})
+
+describe("gtd strays --json=<index>", () => {
+  it("--json=0 prints the first stray, exit 10", async () => {
+    const { stdout, exitCode } = await strays(seed(), "base..HEAD", "src/**", "--json=0")
+    expect(stdout).toBe("notes/b.md\n")
+    expect(exitCode).toBe(EXIT_STRAYS_FOUND)
+  })
+
+  it("--json=0 on a clean range prints nothing, exit 0", async () => {
+    const { stdout, exitCode } = await strays(seed(), "base..HEAD", "src/**", "notes/*", "--json=0")
+    expect(stdout).toBe("")
+    expect(exitCode).toBe(EXIT_OK)
+  })
+
+  it("an index past the end prints nothing and keeps exit 10", async () => {
+    const { stdout, exitCode } = await strays(seed(), "base..HEAD", "src/**", "--json=5")
+    expect(stdout).toBe("")
+    expect(exitCode).toBe(EXIT_STRAYS_FOUND)
+  })
+})
+
+describe("gtd strays — unknown revisions", () => {
+  it.each([
+    ["nope..HEAD", "nope"],
+    ["HEAD..nope", "nope"],
+    ["HEAD..--output=x", "--output=x"],
+  ])("%s: exit 1, empty stdout, no file written", async (range, side) => {
+    const repo = seed()
+    const { stdout, stderr, exitCode } = await strays(repo, range)
+    expect(stdout).toBe("")
+    expect(stderr).toContain(`unknown revision '${side}'`)
+    expect(exitCode).toBe(EXIT_RUNTIME_ERROR)
+    expect(repo.readFile("x")).toBeUndefined()
+  })
+})

package/src/cli/Strays.ts

@@ -0,0 +1,56 @@
+import { Effect } from "effect"
+import { GitService, GtdError, Narrator, type GitOperations } from "../platform/index.js"
+import { strayPaths } from "../step/index.js"
+import { EXIT_OK, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import {
+  SelectorUsageError,
+  writeSelection,
+  type ArtifactOut,
+  type JsonMode,
+  type SuccessExit,
+} from "./Output.js"
+
+// `^{commit}` peels to a commit: a tree or blob would make `git diff` print paths not anchored at the repo root.
+const resolveSide = (git: GitOperations, side: string): Effect.Effect<string, Error> =>
+  git
+    .resolveRef(`${side}^{commit}`)
+    .pipe(Effect.mapError(() => new GtdError(`gtd strays: unknown revision '${side}'`)))
+
+/** stdout carries the array alone; the summary is ungated stderr so a quiet run still explains its exit code, the per-path lines are narration. */
+export const runStraysCommand = (
+  command: {
+    readonly base: string
+    readonly tip: string
+    readonly globs: readonly string[]
+  },
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<SuccessExit, Error, GitService | Narrator> =>
+  Effect.gen(function* () {
+    const git = yield* GitService
+    const narrator = yield* Narrator
+    const base = yield* resolveSide(git, command.base)
+    const tip = yield* resolveSide(git, command.tip)
+    const touched = yield* git.diffPaths(base, tip)
+    const strays = strayPaths(touched, command.globs)
+    const total = touched.length
+
+    if (json.kind === "select") {
+      // An index past the end is absent here, not a usage error: it must not mask the exit 0/10 verdict.
+      yield* writeSelection(out, strays, json.path).pipe(
+        Effect.catchIf(
+          (error) => error instanceof SelectorUsageError && /^\d+$/.test(json.path),
+          () => Effect.void,
+        ),
+      )
+    } else out.write(`${JSON.stringify(strays)}\n`)
+
+    // JSON-quoted: a path is author-controlled and must not carry terminal escapes.
+    for (const path of strays) yield* narrator.narrate(`stray: ${JSON.stringify(path)}`)
+    yield* narrator.warn(
+      strays.length === 0
+        ? `gtd strays: no strays — ${total} touched files, all inside the allowlist`
+        : `gtd strays: ${strays.length} of ${total} touched files outside the allowlist`,
+    )
+    return strays.length === 0 ? EXIT_OK : EXIT_STRAYS_FOUND
+  })