@pmelab/gtd 26.0.0 → 27.0.0

package/src/testkit/GitTiers.ts

@@ -30,6 +30,7 @@ import {
   updateRef,
   fetchHistoryRefs,
   deleteRef,
+  shellQuote,
 } from "../emit/index.js"
 import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
 import { InMemRepo } from "./InMemRepo.js"
@@ -38,8 +39,6 @@ import { gitTestLayer, type ScriptedCommand } from "./Layers.js"
 export interface GitTierCapabilities {
   /** Assert file BYTES on disk, not just index/HEAD state (`hardResetTo`) — only the Live tier has a real working-tree file to read back. */
   readonly onDiskContent: boolean
-  /** Install a real `.git/hooks/pre-commit` and prove the `--no-verify` retry — only the Live tier has a hooks directory. */
-  readonly commitHooks: boolean
   /** `git worktree add` — sibling linked worktrees sharing one `.git`; the fake models a single worktree only. */
   readonly linkedWorktrees: boolean
   /** A cwd→home directory chain for config discovery — both tiers walk it through `Workspace`/`Host` now, so this is `true` for either. */
@@ -48,6 +47,26 @@ export interface GitTierCapabilities {
   readonly remotes: boolean
 }
 
+// Quoted heredoc: `$`, `$(…)` and backticks in `output` reach stderr verbatim.
+const writeRejectingHook = (hooksDir: string, output: string): void => {
+  mkdirSync(hooksDir, { recursive: true })
+  writeFileSync(
+    join(hooksDir, "pre-commit"),
+    `#!/bin/sh\ncat >&2 <<'GTD_HOOK_EOF'\n${output}\nGTD_HOOK_EOF\nexit 1\n`,
+    { mode: 0o755 },
+  )
+}
+
+// `printf '%s'` keeps `content` byte-exact.
+const writeStagingHook = (hooksDir: string, path: string, content: string): void => {
+  mkdirSync(hooksDir, { recursive: true })
+  writeFileSync(
+    join(hooksDir, "pre-commit"),
+    `#!/bin/sh\nprintf '%s' ${shellQuote(content)} > ${shellQuote(path)} && git add ${shellQuote(path)}\nexit 0\n`,
+    { mode: 0o755 },
+  )
+}
+
 export interface GitTierSeed {
   readonly commit: (message: string, files?: Record<string, string>) => void
   readonly writeFile: (path: string, content: string) => void
@@ -56,6 +75,12 @@ export interface GitTierSeed {
   readonly stageAll: () => void
   readonly updateRef: (ref: string, hash: string) => void
   readonly mixedReset: (ref: string) => void
+  /** Every hooked commit fails printing `output`; `--no-verify` skips it. */
+  readonly rejectingHook: (output: string) => void
+  /** Every hooked commit first writes `content` to `path` and stages it; `--no-verify` and `commit-tree` skip it. */
+  readonly stagingHook: (path: string, content: string) => void
+  /** Every commit `git commit` signs, or `git commit-tree -S` writes, fails; plain `git commit-tree` is unaffected. */
+  readonly failingSigner: () => void
 }
 
 export interface GitTierObserve {
@@ -157,7 +182,6 @@ const makeLiveTier = (initialCommit = true): GitTier => {
     root,
     capabilities: {
       onDiskContent: true,
-      commitHooks: true,
       linkedWorktrees: true,
       directoryChainConfig: true,
       remotes: true,
@@ -193,6 +217,22 @@ const makeLiveTier = (initialCommit = true): GitTier => {
       stageAll: () => gitExec("add", "-A"),
       updateRef: (ref, hash) => gitExec("update-ref", ref, hash),
       mixedReset: (ref) => gitExec("reset", "--mixed", ref),
+      rejectingHook: (output) => {
+        const hooks = join(root, ".git/hooks")
+        gitExec("config", "core.hooksPath", hooks)
+        writeRejectingHook(hooks, output)
+      },
+      stagingHook: (path, content) => {
+        const hooks = join(root, ".git/hooks")
+        gitExec("config", "core.hooksPath", hooks)
+        writeStagingHook(hooks, path, content)
+      },
+      failingSigner: () => {
+        gitExec("config", "commit.gpgsign", "true")
+        // A global `gpg.format ssh` would otherwise sign and the case pass vacuously.
+        gitExec("config", "gpg.format", "openpgp")
+        gitExec("config", "gpg.program", "false")
+      },
     },
     observe: {
       resolveRef: (ref) => gitExec("rev-parse", ref),
@@ -258,7 +298,7 @@ const makeInMemTier = (initialCommit = true): GitTier => {
   const repo = new InMemRepo()
   if (initialCommit) {
     repo.writeFile("readme.txt", "hello")
-    repo.commitAllWithPrefix("init: first commit")
+    repo.seedCommit("init: first commit")
   }
   const gitLayer = gitTestLayer(repo, IN_MEM_ROOT)
 
@@ -275,7 +315,6 @@ const makeInMemTier = (initialCommit = true): GitTier => {
     root: IN_MEM_ROOT,
     capabilities: {
       onDiskContent: false,
-      commitHooks: false,
       linkedWorktrees: false,
       directoryChainConfig: true,
       remotes: false,
@@ -286,17 +325,26 @@ const makeInMemTier = (initialCommit = true): GitTier => {
     seed: {
       commit: (message, files = { "file.txt": message }) => {
         for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
-        repo.commitAllWithPrefix(message)
+        repo.seedCommit(message)
       },
       writeFile: (path, content) => repo.writeFile(path, content),
       deleteFile: (path) => repo.deleteFile(path),
       commitDeletion: (path, message) => {
         repo.deleteFile(path)
-        repo.commitAllWithPrefix(message)
+        repo.seedCommit(message)
       },
       stageAll: () => repo.stageAll(),
       updateRef: (ref, hash) => repo.updateRef(ref, hash),
       mixedReset: (ref) => repo.mixedResetTo(ref),
+      rejectingHook: (output) => {
+        repo.hookRejection = output
+      },
+      stagingHook: (path, content) => {
+        repo.hookStages = { path, content }
+      },
+      failingSigner: () => {
+        repo.signingFails = true
+      },
     },
     observe: {
       resolveRef: (ref) => {
@@ -361,6 +409,7 @@ export const CONTRACT_COVERED_OPERATIONS: ReadonlySet<keyof GitOperations> = new
   "subjectHistory",
   "readFileAtRef",
   "changedPaths",
+  "diffPaths",
   "commitAllWithPrefix",
   "softResetTo",
   "commitAsIs",
@@ -386,7 +435,7 @@ const PATHOLOGICAL_PATHS: ReadonlyArray<{ label: string; path: string }> = [
 ]
 
 /**
- * Exercise all 21 `GitOperations` methods identically against `makeTier()` —
+ * Exercise every `GitOperations` methods identically against `makeTier()` —
  * called once per tier by `src/platform/Git.test.ts`. A capability-gated group
  * (`t.capabilities.X`) is skipped, not faked, on a tier that can't support it.
  */
@@ -432,6 +481,7 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
         g.readFileAtRef("HEAD", "second.txt"),
         g.changedPaths(),
         g.changedPaths("HEAD~1"),
+        g.diffPaths("HEAD~1", "HEAD"),
       ]),
     )
     expect(await t.observe.snapshot()).toBe(before)
@@ -727,23 +777,6 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
       const history = await runGit(t, (g) => g.commitHistory())
       expect(history[history.length - 1]?.message).toBe("gtd: grilled")
     })
-
-    it.skipIf(!capabilities.commitHooks)(
-      "retries with --no-verify when a hook blocks the empty commit",
-      async () => {
-        const hookPath = join(t.root, ".git/hooks/pre-commit")
-        writeFileSync(
-          hookPath,
-          `#!/bin/sh\necho "lint-staged prevented an empty git commit." >&2\nexit 1\n`,
-        )
-        execSync(`chmod +x "${hookPath}"`)
-        const headBefore = t.observe.resolveRef("HEAD")
-        await runGit(t, (g) => g.commitAllWithPrefix("gtd: grilled"))
-        expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
-        const history = await runGit(t, (g) => g.commitHistory())
-        expect(history[history.length - 1]?.message).toBe("gtd: grilled")
-      },
-    )
   })
 
   describe("commitAsIs", () => {
@@ -768,6 +801,35 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe.each([
+    ["commitAllWithPrefix", (g: GitOperations) => g.commitAllWithPrefix("gtd: building")],
+    ["commitAsIs", (g: GitOperations) => g.commitAsIs("gtd: building")],
+  ] as const)("%s seeded commit failures", (_name, commit) => {
+    it("retries with --no-verify when a hook blocks the empty commit", async () => {
+      t.seed.rejectingHook("lint-staged prevented an empty git commit.")
+      const headBefore = t.observe.resolveRef("HEAD")
+      await runGit(t, commit)
+      expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
+      const history = await runGit(t, (g) => g.commitHistory())
+      expect(history[history.length - 1]?.message).toBe("gtd: building")
+    })
+
+    it("fails on a hook rejection that is not the empty-commit one, leaving HEAD unchanged", async () => {
+      t.seed.rejectingHook("lint error")
+      const headBefore = t.observe.resolveRef("HEAD")
+      expect(Exit.isFailure(await runGitExit(t, commit))).toBe(true)
+      expect(t.observe.resolveRef("HEAD")).toBe(headBefore)
+    })
+
+    it("fails both attempts when the signer cannot write, leaving HEAD unchanged", async () => {
+      t.seed.rejectingHook("rejected: empty git commit")
+      t.seed.failingSigner()
+      const headBefore = t.observe.resolveRef("HEAD")
+      expect(Exit.isFailure(await runGitExit(t, commit))).toBe(true)
+      expect(t.observe.resolveRef("HEAD")).toBe(headBefore)
+    })
+  })
+
   describe("softResetTo", () => {
     it("moves HEAD back but keeps worktree changes from second commit", async () => {
       const firstHash = t.observe.resolveRef("HEAD")
@@ -824,6 +886,25 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
       expect(resolved._tag).toBe("None")
     })
 
+    it("readRefOption of <hash>^{commit} is Some for an existing commit", async () => {
+      const head = t.observe.resolveRef("HEAD")
+      const resolved = await runGit(t, (g) => g.readRefOption(`${head}^{commit}`))
+      expect(resolved._tag).toBe("Some")
+      if (resolved._tag === "Some") expect(resolved.value).toBe(head)
+    })
+
+    it("readRefOption of <hash>^{commit} is None for a 40-hex hash with no object", async () => {
+      const missing = "0123456789abcdef0123456789abcdef01234567"
+      const resolved = await runGit(t, (g) => g.readRefOption(`${missing}^{commit}`))
+      expect(resolved._tag).toBe("None")
+    })
+
+    it("readRefOption of a bare 40-hex hash with no object is Some", async () => {
+      const missing = "0123456789abcdef0123456789abcdef01234567"
+      const resolved = await runGit(t, (g) => g.readRefOption(missing))
+      expect(resolved._tag).toBe("Some")
+    })
+
     it("deleteRef removes a ref idempotently (deleting twice is a no-op)", async () => {
       const head = t.observe.resolveRef("HEAD")
       await runGit(t, (g) => g.updateRef("refs/gtd/marker", head))
@@ -909,6 +990,70 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("diffPaths", () => {
+    const sorted = (paths: ReadonlyArray<string>) => [...paths].sort()
+
+    it("reports added, modified and deleted paths between two commits", async () => {
+      t.seed.commit("chore: seed", { "mod.txt": "one", "del.txt": "bye" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.writeFile("mod.txt", "two")
+      t.seed.stageAll()
+      t.seed.commitDeletion("del.txt", "chore: delete")
+      t.seed.commit("feat: add", { "add.txt": "new", "mod.txt": "two" })
+      const tip = t.observe.resolveRef("HEAD")
+      const paths = await runGit(t, (g) => g.diffPaths(base, tip))
+      expect(sorted(paths)).toEqual(["add.txt", "del.txt", "mod.txt"])
+    })
+
+    it("reports both paths of a rename", async () => {
+      t.seed.commit("chore: seed", { "old.txt": "same content unique-marker\n" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.deleteFile("old.txt")
+      t.seed.commit("refactor: rename", { "new.txt": "same content unique-marker\n" })
+      const tip = t.observe.resolveRef("HEAD")
+      expect(sorted(await runGit(t, (g) => g.diffPaths(base, tip)))).toEqual(["new.txt", "old.txt"])
+    })
+
+    it("omits a file changed then restored between the endpoints", async () => {
+      t.seed.commit("chore: seed", { "flip.txt": "one" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.commit("chore: change", { "flip.txt": "two" })
+      t.seed.commit("chore: restore", { "flip.txt": "one" })
+      const tip = t.observe.resolveRef("HEAD")
+      expect(await runGit(t, (g) => g.diffPaths(base, tip))).toEqual([])
+    })
+
+    it("never reports staged, unstaged or untracked changes", async () => {
+      t.seed.commit("chore: seed", { "a.txt": "a", "b.txt": "b" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.writeFile("a.txt", "staged")
+      t.seed.stageAll()
+      t.seed.writeFile("b.txt", "unstaged")
+      t.seed.writeFile("untracked.txt", "u")
+      expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([])
+    })
+
+    it("is [] for diffPaths(x, x)", async () => {
+      const head = t.observe.resolveRef("HEAD")
+      expect(await runGit(t, (g) => g.diffPaths(head, head))).toEqual([])
+    })
+
+    for (const { label, path } of PATHOLOGICAL_PATHS) {
+      it(`reports a path containing ${label}, verbatim`, async () => {
+        const base = t.observe.resolveRef("HEAD")
+        t.seed.commit("feat: pathological", { [path]: "content" })
+        expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([path])
+      })
+    }
+
+    it("fails when either side does not resolve", async () => {
+      const bad = await runGitExit(t, (g) => g.diffPaths("totally-invalid-ref-xyz", "HEAD"))
+      expect(Exit.isFailure(bad)).toBe(true)
+      const badTip = await runGitExit(t, (g) => g.diffPaths("HEAD", "totally-invalid-ref-xyz"))
+      expect(Exit.isFailure(badTip)).toBe(true)
+    })
+  })
+
   describe("changedPaths", () => {
     it("unions a tracked modification, a tracked deletion, and an untracked addition, deduplicated by path", async () => {
       t.seed.commit("chore: seed", { "modme.txt": "orig", "delme.txt": "bye" })

package/src/testkit/InMemRepo.ts

@@ -111,6 +111,7 @@ export class InMemRepo {
 
   // fallow-ignore-next-line complexity
   resolveRef(ref: string): string | null {
+    if (ref.endsWith("^{commit}")) return this.resolveRef(ref.slice(0, -"^{commit}".length))
     if (/^[0-9a-f]{40}$/.test(ref)) {
       return this.commits.has(ref) ? ref : null
     }
@@ -269,6 +270,13 @@ export class InMemRepo {
     return diffTrees(baseTree, worktreeTree)
   }
 
+  diffPaths(base: string, tip: string): string[] {
+    for (const ref of [base, tip]) {
+      if (this.resolveRef(ref) === null) throw new Error(`Invalid ref: ${ref}`)
+    }
+    return diffTrees(this.treeAt(base), this.treeAt(tip)).map((e) => e.path)
+  }
+
   /** The worktree content of `path`, or `undefined` when absent. A LIVE read — never a snapshot. */
   readFile(path: string): string | undefined {
     return this.worktree.get(path)
@@ -335,8 +343,13 @@ export class InMemRepo {
     this.index = new Map(this.worktree)
   }
 
-  /** Commit whatever is currently staged (the index) verbatim, with no implicit staging first — mirrors `git commit --allow-empty -m <message>` after a soft reset. */
-  commitAsIs(message: string): void {
+  /** Seeded failure modes (see `GitTierSeed`): a pre-commit hook printing this and exiting 1, and a signer that cannot write. */
+  hookRejection: string | undefined = undefined
+  signingFails = false
+  /** Seeded: a pre-commit hook writing and staging this file. */
+  hookStages: { readonly path: string; readonly content: string } | undefined = undefined
+
+  private writeCommit(message: string): void {
     const tree = new Map(this.index)
     const parent = this.head
     const hash = makeHash(message, parent, tree)
@@ -346,24 +359,63 @@ export class InMemRepo {
     this.branches.set(this.currentBranch, hash)
   }
 
-  /** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
-  discardPending(): void {
-    this.index = new Map(this.worktree)
-    this.resetHard()
+  /**
+   * Twin of the emitted `git commit --allow-empty` if/case retry: a hook
+   * rejection printing "empty git commit" retries without hooks, any other
+   * rejection fails; a failing signer fails either attempt. Commits whatever is
+   * staged verbatim, like `git commit` after a soft reset.
+   */
+  commitAsIs(message: string): string | undefined {
+    if (this.hookRejection !== undefined && !this.hookRejection.includes("empty git commit")) {
+      return this.hookRejection
+    }
+    if (this.signingFails) return "error: gpg failed to sign the data"
+    if (this.hookStages !== undefined) {
+      this.worktree.set(this.hookStages.path, this.hookStages.content)
+      this.index.set(this.hookStages.path, this.hookStages.content)
+    }
+    this.writeCommit(message)
+    return undefined
   }
 
-  commitAllWithPrefix(prefix: string): void {
+  /** Setup commit: stages everything, and throws if a failure is seeded, as the Live tier's hooks and signer would. */
+  seedCommit(message: string): void {
+    if (this.hookRejection !== undefined || this.hookStages !== undefined || this.signingFails) {
+      throw new Error("seedCommit after a seeded commit failure")
+    }
     this.index = new Map(this.worktree)
+    this.writeCommit(message)
+  }
 
+  /** Twin of `GitScript.keepTurn`: no hook runs; `signingFails` fails the marker. */
+  keepTurn(refPrefix: string, message: string): string | undefined {
+    this.stageAll()
     const tree = new Map(this.index)
-    const message = prefix
     const parent = this.head
     const hash = makeHash(message, parent, tree)
+    this.commits.set(hash, { hash, message, files: new Map(tree), parent, seq: this.nextSeq++ })
+    const ref = `${refPrefix}/${hash}`
+    this.refs.set(ref, hash)
+    this.index = new Map(this.headTree())
+    if (this.signingFails) {
+      this.refs.delete(ref)
+      return "error: gpg failed to sign the data"
+    }
+    this.writeCommit(`${message}\nGtd-Kept: ${hash}`)
+    this.index = new Map(tree)
+    this.resetHard()
+    return undefined
+  }
 
-    const commit: Commit = { hash, message, files: new Map(tree), parent, seq: this.nextSeq++ }
-    this.commits.set(hash, commit)
-    this.head = hash
-    this.branches.set(this.currentBranch, hash)
+  /** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
+  discardPending(): void {
+    this.index = new Map(this.worktree)
+    this.resetHard()
+  }
+
+  commitAllWithPrefix(prefix: string): string | undefined {
+    this.index = new Map(this.worktree)
+    return this.commitAsIs(prefix)
   }
 
   // Git's empty-tree object SHA: used as squash base when there's no parent commit.

package/src/testkit/Layers.test.ts

@@ -2,7 +2,8 @@ import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
 import { ConfigDiscovery, LEGACY_RC_FILES, walkUp } from "../workflow/index.js"
 import { InMemRepo } from "./index.js"
-import { testLayers } from "./Layers.js"
+import { ambientFlagEnv, testLayers } from "./Layers.js"
+import { Host } from "../platform/index.js"
 
 // The in-memory `ConfigDiscovery` counterpart walks the SAME root→home chain
 // and looks for the SAME `LEGACY_RC_FILES` as `ConfigDiscovery.Live` — both
@@ -56,3 +57,35 @@ describe("the in-memory ConfigDiscovery counterpart", () => {
     expect(found).toEqual([`${HOME}/${LEGACY_RC_FILES[1]}`])
   })
 })
+
+describe("ambient GTD_FLAG_* reaches the in-memory Host", () => {
+  const hostEnv = (ambient: Record<string, string>, env?: Record<string, string>) => {
+    const before = { ...process.env }
+    Object.assign(process.env, ambient)
+    return Effect.runPromise(
+      Effect.map(Host, (h) => h.env).pipe(
+        Effect.provide(testLayers(new InMemRepo(), env ? { env } : {})),
+        Effect.ensuring(
+          Effect.sync(() => {
+            for (const k of Object.keys(ambient)) {
+              if (before[k] === undefined) delete process.env[k]
+              else process.env[k] = before[k]
+            }
+          }),
+        ),
+      ),
+    )
+  }
+
+  it("carries the ambient flag, and explicit env wins", async () => {
+    expect((await hostEnv({ GTD_FLAG_ALPHA: "1" }))["GTD_FLAG_ALPHA"]).toBe("1")
+    const env = await hostEnv({ GTD_FLAG_ALPHA: "1" }, { GTD_FLAG_ALPHA: "0" })
+    expect(env["GTD_FLAG_ALPHA"]).toBe("0")
+  })
+
+  it("picks only GTD_FLAG_* keys", () => {
+    expect(ambientFlagEnv({ GTD_FLAG_X: "1", PATH: "/bin", GTD_FLAG_U: undefined })).toEqual({
+      GTD_FLAG_X: "1",
+    })
+  })
+})

package/src/testkit/Layers.ts

@@ -216,6 +216,21 @@ const missingToolCommands: ToolCommands["Type"] = {
 export const gitTestLayer = (repo: InMemRepo, root = "/repo"): Layer.Layer<GitService> =>
   Layer.succeed(GitService, fakeGitOperations(repo, root))
 
+/**
+ * The one sanctioned leak of the real `process.env` into the in-memory `Host`:
+ * the runner's `GTD_FLAG_*` state, so a flag-on `npm test` state exercises the
+ * flag in memory as it does live. A test asserting one flag side sets the flag
+ * itself; explicit env wins.
+ */
+export const ambientFlagEnv = (
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(env).filter(
+      (e): e is [string, string] => e[0].startsWith("GTD_FLAG_") && e[1] !== undefined,
+    ),
+  )
+
 /** Every layer `makeProgram` needs — `CommandRequirements`'s return type here IS the guarantee: a new port added there fails this function's typecheck instead of silently under-providing. */
 export function testLayers(
   repo: InMemRepo,
@@ -231,7 +246,12 @@ export function testLayers(
     // symlinks against): both sides of `assertRunningFromRepoRoot`'s
     // comparison collapse to `root` when given anything, exactly like the
     // fake's `root` "resolving" to itself before this port existed.
-    Host.layer({ root, home, env: opts.env ?? {}, realPath: () => Effect.succeed(root) }),
+    Host.layer({
+      root,
+      home,
+      env: { ...ambientFlagEnv(), ...opts.env },
+      realPath: () => Effect.succeed(root),
+    }),
     ConfigService.Live,
     makeInMemoryConfigDiscovery(repo, root),
     Narrator.layer(opts.narrate ?? (() => {}), opts.verbose ?? true),

package/src/testkit/TestRepo.ts

@@ -19,7 +19,7 @@ export interface TestRepoOptions {
   readonly workflow: WorkflowModule
   /** Committed alongside the config, before any process starts. */
   readonly files?: Readonly<Record<string, string>>
-  /** The environment gtd sees; the real `process.env` is never read. */
+  /** The environment gtd sees; the real `process.env` is never read, except ambient `GTD_FLAG_*` (explicit env wins). */
   readonly env?: Readonly<Record<string, string>>
 }
 
@@ -169,7 +169,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     typeof workflow === "string" ? workflow : moduleSource(id, workflow),
   )
   for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content)
-  repo.commitAllWithPrefix("chore: initial commit")
+  repo.seedCommit("chore: initial commit")
 
   // The module is registered only while gtd runs, so nothing outlives the
   // call that loads it and no test can reach another's module.
@@ -245,7 +245,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     read: (path) => repo.readFile(path),
     write: (path, content) => repo.writeFile(path, content),
     remove: (path) => repo.deleteFile(path),
-    commit: (message) => repo.commitAllWithPrefix(message),
+    commit: (message) => repo.seedCommit(message),
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
     runScript: (script) => {
       const flow = applyFlowScript(repo, new Map(), script)

package/src/wire/ExitCodes.test.ts

@@ -5,16 +5,24 @@ import {
   EXIT_RUNTIME_ERROR,
   EXIT_SIGINT,
   EXIT_SIGTERM,
+  EXIT_STRAYS_FOUND,
   EXIT_USAGE_ERROR,
 } from "./index.js"
 
 describe("EXIT_CODES", () => {
-  it("is frozen at exactly {0, 1, 2, 130, 143} — a new code breaks every driver", () => {
-    expect(EXIT_CODES).toEqual(new Set([0, 1, 2, 130, 143]))
+  it("is frozen at exactly {0, 1, 2, 10, 130, 143} — a new code breaks every driver", () => {
+    expect(EXIT_CODES).toEqual(new Set([0, 1, 2, 10, 130, 143]))
   })
 
   it("each named constant is a member of the set", () => {
-    for (const code of [EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR, EXIT_SIGINT, EXIT_SIGTERM]) {
+    for (const code of [
+      EXIT_OK,
+      EXIT_RUNTIME_ERROR,
+      EXIT_USAGE_ERROR,
+      EXIT_STRAYS_FOUND,
+      EXIT_SIGINT,
+      EXIT_SIGTERM,
+    ]) {
       expect(EXIT_CODES.has(code)).toBe(true)
     }
   })

package/src/wire/ExitCodes.ts

@@ -3,6 +3,8 @@ export const EXIT_OK = 0
 export const EXIT_RUNTIME_ERROR = 1
 /** gtd was invoked wrong — an unknown option/command, bad arity, a scope violation, a decode failure. */
 export const EXIT_USAGE_ERROR = 2
+/** `gtd strays` found touched paths outside the allowlist — that command's only, and it carries no other meaning. */
+export const EXIT_STRAYS_FOUND = 10
 export const EXIT_SIGINT = 130
 export const EXIT_SIGTERM = 143
 
@@ -11,6 +13,7 @@ export const EXIT_CODES: ReadonlySet<number> = new Set([
   EXIT_OK,
   EXIT_RUNTIME_ERROR,
   EXIT_USAGE_ERROR,
+  EXIT_STRAYS_FOUND,
   EXIT_SIGINT,
   EXIT_SIGTERM,
 ])

package/src/wire/Glob.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+import { globMatches } from "./Glob.js"
+
+describe("globMatches", () => {
+  it("`*` stays within one segment; `**` crosses segments, zero included", () => {
+    expect(globMatches("a.md", "*.md")).toBe(true)
+    expect(globMatches("docs/a.md", "*.md")).toBe(false)
+    expect(globMatches("src/x/y/a.ts", "src/**")).toBe(true)
+    expect(globMatches("a.ts", "**/a.ts")).toBe(true)
+    expect(globMatches("x/a.ts", "**/a.ts")).toBe(true)
+  })
+
+  it("dotfiles match `*` and `**` like any other path", () => {
+    expect(globMatches(".env", "*")).toBe(true)
+    expect(globMatches("dir/.hidden", "dir/*")).toBe(true)
+    expect(globMatches(".github/ci.yml", "**")).toBe(true)
+    expect(globMatches(".github/ci.yml", "*")).toBe(false)
+  })
+
+  it("matches case-sensitively", () => {
+    expect(globMatches("README.md", "readme.md")).toBe(false)
+  })
+
+  it("`?` and `[` are literal", () => {
+    expect(globMatches("a?.txt", "a?.txt")).toBe(true)
+    expect(globMatches("ab.txt", "a?.txt")).toBe(false)
+    expect(globMatches("[a].txt", "[a].txt")).toBe(true)
+    expect(globMatches("a.txt", "[a].txt")).toBe(false)
+  })
+
+  it("`**` crosses a path containing a line break", () => {
+    expect(globMatches("weird\nname.txt", "**")).toBe(true)
+    expect(globMatches("d/a\nb", "d/**")).toBe(true)
+  })
+})

package/src/wire/Glob.ts

@@ -23,7 +23,7 @@ const compile = (glob: string): RegExp => {
       i += 2
     }
   }
-  return new RegExp(`${pattern}$`)
+  return new RegExp(`${pattern}$`, "s")
 }
 
 export const globMatches = (path: string, glob: string): boolean => compile(glob).test(path)

package/src/workflow/Workflow.ts

@@ -39,6 +39,7 @@ export interface StepDef {
   readonly answerGate?: boolean
   readonly requireRevert?: boolean
   readonly allowEmpty?: boolean
+  readonly keep?: boolean
   readonly acceptClean?: boolean
   readonly skills?: readonly string[]
   readonly access?: StepAccess

package/src/workflow/discovery.test.ts

@@ -83,7 +83,7 @@ const inMemory = (): Tier => ({
   load: (files) => {
     const repo = new InMemRepo()
     for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
-    repo.commitAllWithPrefix("chore: init")
+    repo.seedCommit("chore: init")
     return loadWith(testLayers(repo))
   },
   dispose: () => {},

package/src/workflows/shared/text.fixture.ts

@@ -77,6 +77,7 @@ export const fixtureContext = (
   glob: () => [],
   changes: () => [],
   changesSince: unavailable,
+  kept: () => undefined,
   matches: () => false,
   sections: () => [],
   sectionBodies: () => [],