@pmelab/gtd 27.2.0 → 27.4.0

package/src/edge/Edge.ts

@@ -4,6 +4,7 @@ import {
   GitService,
   Host,
   Workspace,
+  type AuthorIdent,
   type GitOperations,
   type HostOps,
   type WorkspaceOps,
@@ -29,7 +30,9 @@ import {
 } from "../workflow/index.js"
 import {
   formatFault,
+  formatStepId,
   formatSubject,
+  isRecordableApproval,
   parseCommitMessage,
   replay,
   treeFromRecord,
@@ -41,7 +44,14 @@ import {
 } from "../replay/index.js"
 import type { ScopeAccess } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
-import { judgeJson, UNATTRIBUTED_MODEL, type ModelCost, type StepAccess } from "../wire/index.js"
+import {
+  judgeJson,
+  UNATTRIBUTED_MODEL,
+  type ApprovalEntry,
+  type ModelCost,
+  type StepAccess,
+} from "../wire/index.js"
+
 import { GTD_VERSION } from "../install/index.js"
 import { keptRef, processHistoryRef } from "../platform/index.js"
 import { isAbsolute, relative, resolve, sep } from "node:path"
@@ -141,6 +151,8 @@ export interface ProcessRun {
   readonly trace: readonly TraceEntry[]
   readonly costEntries: readonly CostEntry[]
   readonly judgeVerdicts: readonly JudgeVerdictEntry[]
+  /** Oldest first. */
+  readonly approvals: readonly ApprovalEntry[]
   /** The process settings recorded in the process's first commit (empty for a process started before pinning existed). */
   readonly pinnedVars: Record<string, string>
   /** Absent for a process started before recording existed. */
@@ -228,6 +240,21 @@ const pinnedConfigOf = (history: History): ProcessRun["pinnedConfig"] => {
   return undefined
 }
 
+const approvalEntryOf = (
+  hash: string,
+  message: ReturnType<typeof parseCommitMessage>,
+): readonly ApprovalEntry[] =>
+  message.approved === undefined
+    ? []
+    : [
+        {
+          step: formatStepId(message.approved.step),
+          name: message.approved.name,
+          email: message.approved.email,
+          commit: hash,
+        },
+      ]
+
 const buildRun = (
   history: History,
   location: EpisodeLocation,
@@ -247,6 +274,7 @@ const buildRun = (
     trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i]!)),
     costEntries: parsed.flatMap(costEntriesOf),
     judgeVerdicts: parsed.flatMap((m) => m.judge),
+    approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i]!)),
     pinnedVars: { ...first?.vars },
     pinnedConfig: pinnedConfigOf(history.slice(Math.max(location.baseIndex, 0))),
     headTurn: headTurnOf(head),
@@ -729,7 +757,8 @@ const messageDef = (
   ...common,
   kind: "message",
   content: request.options.message ?? request.options.label ?? step.name,
-  ...optional("acceptClean", request.options.acceptClean),
+  ...optional("acceptClean", request.options.approve === true || request.options.acceptClean),
+  ...optional("approve", request.options.approve),
 })
 
 const stepDefOf = (step: ReachedStep): StepDef => {
@@ -933,6 +962,17 @@ const setupFor = (
     return { resolved, def, vars, env, setup }
   })
 
+// Only an approval gate counts an index-only edit (one staged, then reverted
+// in the worktree): its approval must cover exactly the judged diff. Every
+// other rest keeps the worktree's view, so a net-zero turn stays an attempt.
+const pendingChanges = (git: GitOperations, withIndex: boolean) =>
+  Effect.gen(function* () {
+    const worktree = yield* git.changedPaths()
+    if (!withIndex) return worktree
+    const seen = new Set(worktree.map((e) => e.path))
+    return [...worktree, ...(yield* git.stagedPaths()).filter((e) => !seen.has(e.path))]
+  })
+
 /** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
 export const restAt = (
   ref: string | undefined,
@@ -974,7 +1014,7 @@ export const restAt = (
     }
     const changes =
       ref === undefined
-        ? (yield* git.changedPaths()).map((e) => ({
+        ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({
             status: normalizeStatus(e.status),
             path: e.path,
           }))
@@ -1107,6 +1147,32 @@ export const restIsIdle = (rest: Rest): boolean =>
 
 const isHumanReviewGate = (def: StepDef): boolean => def.actor === "human" && def.mode === "review"
 
+// An approval covers exactly the judged diff, so any edit refuses it; the
+// approver is read only at such a rest, and must be a name a trailer can carry.
+const approvalRefusal = (rest: Rest, approver: Option.Option<AuthorIdent>): Landing | undefined => {
+  if (rest.stepDef.approve !== true) return undefined
+  const id = rest.step.id
+  if (rest.changes.length > 0) {
+    return {
+      kind: "refusal",
+      message: `gtd land: approval-gate: ${formatStepId(id)} approves exactly the judged diff — revert your edits and run \`gtd land\` on a clean tree to approve, or run \`gtd abandon\``,
+    }
+  }
+  if (Option.isNone(approver)) {
+    return {
+      kind: "refusal",
+      message: `gtd land: approval-gate: ${formatStepId(id)} records who approved it, but git has no author identity — set user.name and user.email`,
+    }
+  }
+  if (!isRecordableApproval({ step: id, ...approver.value })) {
+    return {
+      kind: "refusal",
+      message: `gtd land: approval-gate: ${formatStepId(id)} cannot record ${approver.value.name} <${approver.value.email}> as approver — it would not read back unchanged from its Gtd-Approved trailer (a control character, for example)`,
+    }
+  }
+  return undefined
+}
+
 /** The landing a clean tree decides before any replay, if it decides one. */
 const cleanLanding = (rest: Rest): Landing | undefined => {
   if (rest.changes.length > 0) return undefined
@@ -1182,7 +1248,15 @@ const keptTurn = (rest: Rest) =>
     ? { keepTurn: keptRef(rest.run.startHash, rest.state) }
     : {}
 
-const landingTo = (rest: Rest, to: StateName, branch: Option.Option<string>): Landing => {
+const approvedTrailer = (rest: Rest, approver: Option.Option<AuthorIdent>) =>
+  Option.isSome(approver) ? { approved: { step: rest.step.id, ...approver.value } } : {}
+
+const landingTo = (
+  rest: Rest,
+  to: StateName,
+  branch: Option.Option<string>,
+  approver: Option.Option<AuthorIdent>,
+): Landing => {
   if (isSettledNoop(rest, to)) return { kind: "noop", settled: true }
   // The landing that leaves the flow's first step starts the process: it
   // pins the process settings every later invocation reads back.
@@ -1202,6 +1276,7 @@ const landingTo = (rest: Rest, to: StateName, branch: Option.Option<string>): La
       from: rest.state,
       to,
       step: rest.step.id,
+      ...approvedTrailer(rest, approver),
       ...(starts ? { vars: rest.vars, config: rest.config } : {}),
       ...(finishes ? closingTrailers(branch) : {}),
     },
@@ -1219,8 +1294,11 @@ const decideLanding = (
   rest: Rest,
   verdicts: readonly JudgeVerdict[] | undefined,
   branch: Option.Option<string>,
+  approver: Option.Option<AuthorIdent>,
 ): Effect.Effect<Landing, Error> =>
   Effect.gen(function* () {
+    const unapproved = approvalRefusal(rest, approver)
+    if (unapproved !== undefined) return unapproved
     const early = cleanLanding(rest)
     if (early !== undefined) return early
     if (rest.stepDef.kind === "prompt" && rest.stepDef.access?.write != null) {
@@ -1239,12 +1317,12 @@ const decideLanding = (
     )
     const to = yield* landingTarget(outcome, rest)
     if (typeof to !== "string") return to
-    return landingTo(rest, to, branch)
+    return landingTo(rest, to, branch, approver)
   })
 
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
 export const previewLanding = (rest: Rest): Effect.Effect<StateName | undefined> =>
-  decideLanding(rest, undefined, Option.none()).pipe(
+  decideLanding(rest, undefined, Option.none(), Option.none()).pipe(
     Effect.map((landing) => (landing.kind === "commit" ? landing.to : undefined)),
     Effect.catchAll(() => Effect.succeed(undefined)),
   )
@@ -1255,8 +1333,10 @@ export const snapshotFromRest = (
   verdicts?: readonly JudgeVerdict[],
 ): Effect.Effect<RepoSnapshot, Error, Workspace | GitService> =>
   Effect.gen(function* () {
-    const branch = yield* (yield* GitService).currentBranch()
-    const landing = yield* decideLanding(rest, verdicts, branch)
+    const git = yield* GitService
+    const branch = yield* git.currentBranch()
+    const approver = rest.stepDef.approve === true ? yield* git.authorIdent() : Option.none()
+    const landing = yield* decideLanding(rest, verdicts, branch, approver)
     return {
       stepDef: rest.stepDef,
       state: rest.state,
@@ -1300,6 +1380,7 @@ export interface HistoryStep {
   readonly from: StateName | undefined
   readonly to: StateName
   readonly verdicts: readonly JudgeVerdict[]
+  readonly approval?: ApprovalEntry
 }
 
 export interface HistoryTrail {
@@ -1371,6 +1452,7 @@ const historySteps = (run: ProcessRun): readonly HistoryStep[] => {
       from: message.parsed?.from,
       to: entry.state,
       verdicts: message.judge,
+      ...optional("approval", approvalEntryOf(entry.hash, message)[0]),
     }
   })
 }

package/src/emit/GitScript.test.ts

@@ -7,6 +7,7 @@ import fc from "fast-check"
 import {
   commitAll,
   commitAsIs,
+  commitClean,
   deleteRef,
   discardPending,
   fetchHistoryRefs,
@@ -70,6 +71,7 @@ const runWithFakeGit = (script: string, binDir: string): { status: number | null
 const allBuilders: ReadonlyArray<[string, string]> = [
   ["commitAll", commitAll("gtd(agent): working")],
   ["commitAsIs", commitAsIs("gtd(agent): working")],
+  ["commitClean", commitClean("gtd(human): gate → again")],
   ["softResetTo", softResetTo("HEAD~1")],
   ["mixedResetTo", mixedResetTo("HEAD~1")],
   ["hardResetTo", hardResetTo("HEAD~1")],
@@ -104,6 +106,40 @@ describe("commitAsIs", () => {
   })
 })
 
+describe("commitClean", () => {
+  const logGit = (body: string): { binDir: string; log: string } => {
+    const dir = mkdtempSync(join(tmpdir(), "gtd-log-git-"))
+    const log = join(dir, "log")
+    const gitPath = join(dir, "git")
+    writeFileSync(gitPath, `#!/bin/sh\necho "$*" >> '${log}'\n${body}\n`)
+    chmodSync(gitPath, 0o755)
+    return { binDir: dir, log }
+  }
+  const readLog = (log: string): string[] =>
+    execFileSync("cat", [log], { encoding: "utf8" }).trim().split("\n")
+  const cases = `case "$1" in
+  rev-parse) echo head0 ;;
+  status) ;;
+  config) echo \${GTD_CFG:-false} ;;
+  commit-tree) echo commit0 ;;
+esac`
+
+  it("a dirty tree exits 1 before any commit", () => {
+    const { binDir, counterFile } = withFakeGit(`echo head0`, `echo " M a.txt"`)
+    const result = runWithFakeGit(commitClean("msg"), binDir)
+    expect(result.status).toBe(1)
+    expect(execFileSync("cat", [counterFile], { encoding: "utf8" }).trim()).toBe("2")
+  })
+
+  it("a refused update-ref (HEAD moved) exits 1; the write is guarded by the pinned HEAD", () => {
+    const { binDir, log } = logGit(`${cases}\nif [ "$1" = update-ref ]; then exit 1; fi`)
+    const result = runWithFakeGit(commitClean("msg"), binDir)
+    expect(result.status).toBe(1)
+    const lines = readLog(log)
+    expect(lines[lines.length - 1]).toBe("update-ref -m commit: msg HEAD commit0 head0")
+  })
+})
+
 describe("commitAllowEmpty retry discrimination (via commitAsIs)", () => {
   it("retries without hooks on the hook's own empty-git-commit rejection", () => {
     const { binDir, counterFile } = withFakeGit(
@@ -304,7 +340,7 @@ describe("keepTurn", () => {
         `  write-tree) echo tree0 ;;`,
         `  commit-tree) echo commit0 ;;`,
         `  config) echo false ;;`,
-        `  update-ref) [ "$2" = HEAD ] && exit 1; exit 0 ;;`,
+        `  update-ref) [ "$4" = HEAD ] && exit 1; exit 0 ;;`,
         `  *) exit 0 ;;`,
         `esac`,
       ].join("\n"),
@@ -313,7 +349,7 @@ describe("keepTurn", () => {
     const result = runWithFakeGit(`set -eu\n${block}`, binDir)
     expect(result.status).toBe(1)
     const calls = readFileSync(log, "utf8").trim().split("\n")
-    expect(calls).toContain("update-ref HEAD commit0 head0")
+    expect(calls).toContain("update-ref -m commit: gtd(agent): done HEAD commit0 head0")
     const resetAt = calls.indexOf("reset -q")
     expect(resetAt).toBeGreaterThan(-1)
     expect(calls.slice(resetAt + 1)).toEqual([
@@ -335,7 +371,7 @@ describe("keepTurn", () => {
         `  write-tree) echo tree0 ;;`,
         `  commit-tree) echo commit0 ;;`,
         `  config) echo false ;;`,
-        `  update-ref) [ "$2" = HEAD ] && exit 1; exit 0 ;;`,
+        `  update-ref) [ "$4" = HEAD ] && exit 1; exit 0 ;;`,
         `  reset) exit 1 ;;`,
         `  *) exit 0 ;;`,
         `esac`,

package/src/emit/GitScript.ts

@@ -24,10 +24,32 @@ const commitAllowEmpty = (message: string): string => {
   ].join("\n")
 }
 
+export const CHANGED_SINCE_LAND =
+  "gtd: the working tree changed since `gtd land` — revert the edits and run `gtd land` again to approve"
+
 /** `git add -A || exit 1` (an `&&` left side would not abort under `set -e`) then `commitAllowEmpty`. */
 export const commitAll = (message: string): string =>
   `git add -A || exit 1\n${commitAllowEmpty(message)}`
 
+/**
+ * An approval records exactly the judged tree: HEAD is pinned before the
+ * clean check and the commit is built over its tree with `commit-tree`, so no
+ * hook runs and none can add to it. A HEAD that moved fails the guarded
+ * `update-ref`. `commit-tree` ignores `commit.gpgSign`, so it is read here.
+ */
+export const commitClean = (message: string): string =>
+  [
+    `gtd_head=$(git rev-parse --verify HEAD) || exit 1`,
+    `if [ -n "$(git status --porcelain --untracked-files=all --ignore-submodules=none)" ]; then`,
+    `  printf '%s\\n' ${shellQuote(CHANGED_SINCE_LAND)} >&2`,
+    `  exit 1`,
+    `fi`,
+    `gtd_sign_cfg=$(git config --type=bool --default=false commit.gpgSign) || exit 1`,
+    `if [ "$gtd_sign_cfg" = true ]; then gtd_sign=-S; else gtd_sign=--no-gpg-sign; fi`,
+    `gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m ${shellQuote(message)}) || exit 1`,
+    `git update-ref -m ${shellQuote(`commit: ${message}`)} HEAD "$gtd_tip" "$gtd_head" || exit 1`,
+  ].join("\n")
+
 /** No current caller — see `Git.ts`'s `GitWriterOperations.commitAsIs` for why it's kept anyway. */
 export const commitAsIs = (message: string): string => commitAllowEmpty(message)
 
@@ -70,7 +92,7 @@ export const keepTurn = (refPrefix: string, message: string): string => {
     `gtd_kept=$(git commit-tree "$gtd_tree" -p "$gtd_head" -m ${shellQuote(message)}) || exit 1`,
     `git update-ref ${keptRef} "$gtd_kept" || exit 1`,
     `gtd_marker=$(printf '%s\\nGtd-Kept: %s' ${shellQuote(message)} "$gtd_kept")`,
-    `if ! gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m "$gtd_marker") || ! git update-ref HEAD "$gtd_tip" "$gtd_head"; then`,
+    `if ! gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m "$gtd_marker") || ! git update-ref -m ${shellQuote(`commit: ${message}`)} HEAD "$gtd_tip" "$gtd_head"; then`,
     `  git reset -q && git update-ref -d ${keptRef}`,
     `  exit 1`,
     `fi`,
@@ -129,6 +151,8 @@ const renderGitWrite = (write: GitWrite): string => {
   switch (write.kind) {
     case "commitAll":
       return commitAll(write.message)
+    case "commitClean":
+      return commitClean(write.message)
     case "updateRef":
       return updateRef(write.ref, write.target)
     case "keepTurn":

package/src/emit/index.ts

@@ -15,6 +15,8 @@ export {
   shellQuote,
   commitAll,
   commitAsIs,
+  commitClean,
+  CHANGED_SINCE_LAND,
   softResetTo,
   mixedResetTo,
   hardResetTo,

package/src/flows/helpers.ts

@@ -2,6 +2,7 @@ import {
   changes,
   codeThreads,
   head,
+  human,
   judge,
   matches,
   openQuestions,
@@ -250,3 +251,30 @@ export const judgeDiffShape = async (
       : "refactor-first"
   return { choice, strays, unreadable: [], judgment }
 }
+
+const displayPath = (path: string): string =>
+  // eslint-disable-next-line no-control-regex -- the control range IS the point
+  /[\x00-\x1f\x7f-\x9f]/.test(path) ? JSON.stringify(path) : path
+
+const seamReport = (shape: DiffShapeResult): string => {
+  const unreadable = new Set(shape.unreadable)
+  const strays = shape.strays.map(
+    (path) => `- ${displayPath(path)}${unreadable.has(path) ? " (unreadable — not judged)" : ""}`,
+  )
+  return [
+    "Seam report: the judge found the diff's shape needs a refactor first. These paths stray outside the allowlist:",
+    "",
+    ...strays,
+    "",
+    "Landing a clean tree with `gtd land` approves this diff exactly as judged; edits are refused. To stop instead, run `gtd abandon`.",
+  ].join("\n")
+}
+
+/**
+ * Rest at an approval gate `name` showing the seam report — only when
+ * `shape.choice` is `refactor-first`. `land` and `reject` reach no step.
+ */
+export const seamGate = async (name: string, shape: DiffShapeResult): Promise<void> => {
+  if (shape.choice !== "refactor-first") return
+  await human(name, { message: seamReport(shape), approve: true })
+}

package/src/flows/runtime.ts

@@ -39,6 +39,13 @@ export interface HumanOptions extends SteeringOptions {
    * Without this a clean landing is a no-op: the gate waits for a change.
    */
   readonly acceptClean?: boolean | undefined
+  /**
+   * A sign-off gate: only a clean landing completes it, and that commit
+   * carries `Gtd-Approved: {"step":"<step>#<n>","name":"<name>","email":"<email>"}`.
+   * A dirty landing is refused. Implies `acceptClean`. Cannot be combined with
+   * `mode` or `file`: an approval records exactly the judged tree.
+   */
+  readonly approve?: boolean | undefined
 }
 
 export interface RunOptions extends SteeringOptions {}

package/src/install/Install.ts

@@ -246,7 +246,8 @@ skills, \`skills\` (an array of the skill names, already trimmed and split —
 (\`{read, write}\`, each an array of globs or \`null\` for unrestricted). When set: \`model\`, \`memory\`,
 \`label\`, \`file\`, \`mode\`, \`edges\`, \`judge\` (the pending judgment's rendered
 document). When a cost has been recorded (a prior \`gtd land --cost=<n>\`):
-\`cost\`, \`costByModel\`.
+\`cost\`, \`costByModel\`. Always \`approvals\` (an array of
+\`{step, name, email, commit}\`, \`[]\` when none).
 
 \`gtd land\` fields, in fixed order: \`schema\`, \`script\` (the POSIX sh to run), \`settled\`
 (true for a no-op at a \`script\` rest — stop immediately, nothing more to

package/src/platform/Git.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { NodeContext } from "@effect/platform-node"
-import { Cause, Effect, Exit } from "effect"
+import { Cause, Effect, Exit, Option } from "effect"
 import { describe, expect, it } from "vitest"
 import { GitService, InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
 import { Host } from "./index.js"
@@ -140,3 +140,27 @@ describe("diffPaths [Live]", () => {
     }
   })
 })
+
+describe("authorIdent [Live]", () => {
+  it("is none when git has no author identity", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-ident-")))
+    try {
+      const git = (...args: string[]) =>
+        execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: "pipe" })
+      git("init")
+      git("config", "user.useConfigOnly", "true")
+      git("config", "user.name", "")
+      git("config", "user.email", "")
+      const ident = await Effect.runPromise(
+        Effect.flatMap(GitService, (g) => g.authorIdent()).pipe(
+          Effect.provide(GitService.Live),
+          Effect.provide(Host.layer({ root, home: root, env: {} })),
+          Effect.provide(NodeContext.layer),
+        ),
+      )
+      expect(Option.isNone(ident)).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})

package/src/platform/Git.ts

@@ -94,6 +94,15 @@ export interface GitReaderOperations {
   readonly changedPaths: (
     base?: string,
   ) => Effect.Effect<ReadonlyArray<{ readonly path: string; readonly status: string }>, Error>
+  /**
+   * The index vs `HEAD`, as `{path, status}` pairs — what a commit would carry
+   * that `changedPaths` misses when the worktree reverted a staged edit. Empty
+   * before the first commit.
+   */
+  readonly stagedPaths: () => Effect.Effect<
+    ReadonlyArray<{ readonly path: string; readonly status: string }>,
+    Error
+  >
   /**
    * Paths whose content differs between the trees of `base` and `tip`: added,
    * modified and deleted alike; a rename reports both paths (no rename
@@ -103,8 +112,12 @@ export interface GitReaderOperations {
    * working tree. Fails when either side does not resolve.
    */
   readonly diffPaths: (base: string, tip: string) => Effect.Effect<ReadonlyArray<string>, Error>
+  /** `git var GIT_AUTHOR_IDENT`'s name and email; `None` when git has no identity. */
+  readonly authorIdent: () => Effect.Effect<Option.Option<AuthorIdent>, Error>
 }
 
+export type AuthorIdent = { readonly name: string; readonly email: string }
+
 export interface GitWriterOperations {
   /**
    * `git add -A` then commit. `--allow-empty` is load-bearing: the machine
@@ -406,6 +419,17 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
         "--",
       ).pipe(Effect.map(splitNul)),
 
+    authorIdent: () =>
+      exec("git", "var", "GIT_AUTHOR_IDENT").pipe(
+        Effect.map((out) => {
+          const match = /^(.*?) <([^<>]*)> \d+ [+-]\d{4}$/.exec(out.trim())
+          return match === null || match[1] === "" || match[2] === ""
+            ? Option.none()
+            : Option.some({ name: match[1]!, email: match[2]! })
+        }),
+        Effect.catchAll(() => Effect.succeed(Option.none())),
+      ),
+
     changedPaths: (base?: string) =>
       Effect.gen(function* () {
         const ref = base ?? "HEAD"
@@ -443,6 +467,12 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
         return all
       }),
 
+    stagedPaths: () =>
+      exec("git", "diff", "--cached", "--name-status", "--no-renames", "-z", "HEAD").pipe(
+        Effect.catchAll(() => Effect.succeed("")),
+        Effect.map((out) => parseNameStatus(splitNul(out))),
+      ),
+
     resolveRef: (ref: string) =>
       exec("git", "rev-parse", "--verify", "--end-of-options", ref).pipe(
         Effect.map((s) => s.trim()),

package/src/platform/index.ts

@@ -15,6 +15,7 @@ export {
   type GitOperations,
   type GitReaderOperations,
   type GitWriterOperations,
+  type AuthorIdent,
 } from "./Git.js"
 export { Narrator, GtdError, GtdUsageError, renderFailure } from "./Commentary.js"
 export { CommandRunner } from "./CommandRunner.js"

package/src/replay/Format.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { formatFault } from "./Format.js"
+import { formatCommitMessage, formatFault, parseCommitMessage } from "./index.js"
 
 describe("the history format", () => {
   it("accepts a history entirely in the current format", () => {
@@ -18,3 +18,18 @@ describe("the history format", () => {
     )
   })
 })
+
+describe("Gtd-Approved and the history format", () => {
+  it("leaves Gtd-Format at 1 on a message carrying it", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "b",
+      approved: { step: { name: "seam", occurrence: 1 }, name: "Test", email: "test@test.com" },
+    })
+    expect(message).toContain(
+      'Gtd-Approved: {"step":"seam#1","name":"Test","email":"test@test.com"}',
+    )
+    expect(message).toContain("Gtd-Format: 1")
+    expect(parseCommitMessage(message).format).toBe(1)
+  })
+})

package/src/replay/Replay.test.ts

@@ -1076,3 +1076,94 @@ describe("replay: access resolution", () => {
     expect(outcome.kind === "failed" && outcome.message).toContain('scope "a"')
   })
 })
+
+describe("human({ approve })", () => {
+  const gate: Flow = async () => {
+    await human("gate", { approve: true })
+    await human("after")
+  }
+  const sign = (step: string, occurrence: number) => ({
+    step: { name: step, occurrence },
+    name: "Test",
+    email: "test@test.com",
+  })
+  const approval = (approved?: ReturnType<typeof sign>): string =>
+    formatCommitMessage({
+      actor: "human",
+      from: "gate",
+      to: "after",
+      step: { name: "gate", occurrence: 1 },
+      ...(approved !== undefined ? { approved } : {}),
+    })
+
+  it("is accepted: no unknown-option failure, the gate is the rest", async () => {
+    const outcome = await replayOf(gate, new History())
+    expect(outcome.kind).toBe("rest")
+    if (outcome.kind === "rest") expect(outcome.rest.name).toBe("gate")
+  })
+
+  it("consumes a commit carrying a matching Gtd-Approved and continues past the gate", async () => {
+    const h = new History().raw(approval(sign("gate", 1)))
+    const outcome = await replayOf(gate, h)
+    expect(outcome.kind).toBe("rest")
+    if (outcome.kind === "rest") expect(outcome.rest.name).toBe("after")
+  })
+
+  it("diverges on a commit without Gtd-Approved", async () => {
+    const outcome = await replayOf(gate, new History().raw(approval()))
+    expect(outcome).toEqual({
+      kind: "divergence",
+      message: `gtd: commit ${hashOf(1).slice(0, 7)} completes approval gate "gate#1" but records no Gtd-Approved for it — the workflow changed under this process; run \`gtd abandon\` to start over`,
+    })
+  })
+
+  it("diverges on a Gtd-Approved naming another step, or another occurrence", async () => {
+    for (const other of [sign("elsewhere", 1), sign("gate", 2)]) {
+      const outcome = await replayOf(gate, new History().raw(approval(other)))
+      expect(outcome.kind).toBe("divergence")
+      expect(outcome.kind === "divergence" && outcome.message).toContain(
+        'completes approval gate "gate#1" but records no Gtd-Approved for it',
+      )
+    }
+  })
+
+  describe("refuses mode and file", () => {
+    const tail =
+      "in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing"
+    const outcomeOf = async (options: Record<string, unknown>) =>
+      replayOf(async () => {
+        await human("gate", options as never)
+      }, new History())
+
+    it.each([
+      [{ approve: true, mode: "review" }, "mode"],
+      [{ approve: true, file: ".gtd/REVIEW.md" }, "file"],
+      [{ approve: true, mode: "review", file: ".gtd/REVIEW.md" }, "mode, file"],
+    ])("fails on %j naming %s", async (options, keys) => {
+      expect(await outcomeOf(options)).toEqual({
+        kind: "failed",
+        message: `gtd: step "gate": approve cannot be combined with ${keys} ${tail}`,
+      })
+    })
+
+    it("replays approve with label or base, and approve: false with mode", async () => {
+      for (const options of [
+        { approve: true, label: "x" },
+        { approve: true, base: "start" },
+        { approve: false, mode: "review" },
+        { approve: true, mode: undefined },
+      ]) {
+        expect((await outcomeOf(options)).kind).toBe("rest")
+      }
+    })
+  })
+
+  it("does not demand Gtd-Approved at a plain human step", async () => {
+    const h = new History().land("human", "plain", 1, "after")
+    const outcome = await replayOf(async () => {
+      await human("plain")
+      await human("after")
+    }, h)
+    expect(outcome.kind).toBe("rest")
+  })
+})