@pmelab/gtd 27.3.0 → 27.4.0

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-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";
+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-C12dahrH.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "27.3.0",
+  "version": "27.4.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/cli/Cli.ts

@@ -705,11 +705,11 @@ const COMMAND_ROWS: readonly CommandRow[] = [
     arity: { name: "ref" },
     details: [
       "Replay one kept process under today's config and print its",
-      "steps and judge verdicts. <ref> is a full ref, an entry hash",
-      "(or unique prefix) or a branch name. Refuses (exit 1) when a",
-      "config file differs from its content at the ref's tip. A",
-      "version mismatch only warns on stderr. --json prints the",
-      "trail as one document; writes nothing",
+      "steps, judge verdicts and approvals. <ref> is a full ref, an",
+      "entry hash (or unique prefix) or a branch name. Refuses",
+      "(exit 1) when a config file differs from its content at the",
+      "ref's tip. A version mismatch only warns on stderr. --json",
+      "prints the trail as one document; writes nothing",
     ],
   },
   {

package/src/cli/History.ts

@@ -128,6 +128,11 @@ export const runHistoryShowCommand = (
     for (const step of trail.steps) {
       lines.push(`${seven(step.hash)} ${step.subject}`)
       for (const v of step.verdicts) lines.push(`  judge ${v.id} = ${v.answer} (p=${v.p})`)
+      if (step.approval !== undefined) {
+        lines.push(
+          `  approved ${step.approval.step} by ${step.approval.name} <${step.approval.email}>`,
+        )
+      }
     }
     lines.push(`ended (${trail.ended})`)
     out.write(`${lines.join("\n")}\n`)

package/src/cli/Program.ts

@@ -1080,6 +1080,7 @@ const gatherBeatDocument = (
       next: yield* computeNextMatch(rest),
       cost: rest.cost.total,
       costByModel: rest.cost.byModel,
+      approvals: rest.run.approvals,
     })
     return beatDocument(demand, status)
   })

package/src/edge/Edge.test.ts

@@ -151,6 +151,7 @@ describe("currentRun", () => {
       trace: [],
       costEntries: [],
       judgeVerdicts: [],
+      approvals: [],
       pinnedVars: {},
       headTurn: undefined,
       closingHash: undefined,
@@ -1306,6 +1307,28 @@ export default async () => {
     expect(trail.steps.filter((s) => s.verdicts.length > 0)).toHaveLength(1)
   })
 
+  it("sets approval on the approval step only", async () => {
+    const repo = repoWith(`import { human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await human("gate", { message: "seam report", approve: true })
+  await human("after")
+}
+`)
+    await land(repo, { "src/a.ts": "a\n" })
+    const approval = await land(repo)
+    const tip = await land(repo, { "src/b.ts": "b\n" })
+    const trail = await provide(historyTrail(tip), repo)
+    expect(trail.steps.find((s) => s.hash === approval)?.approval).toEqual({
+      step: "gate#1",
+      name: "Test",
+      email: "test@test.com",
+      commit: approval,
+    })
+    expect(trail.steps.filter((s) => s.approval !== undefined)).toHaveLength(1)
+  })
+
   it("records the version and warns about none while they match", async () => {
     const { repo, tip } = await finished()
     const trail = await provide(historyTrail(tip), repo)
@@ -1369,3 +1392,140 @@ export default async () => {
     expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")
   })
 })
+
+describe("landing at an approve rest", () => {
+  const GATED = `import { human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await human("gate", { message: "seam report", approve: true })
+  await human("after")
+}
+`
+
+  const atGate = async (): Promise<InMemRepo> => {
+    const repo = repoWith(GATED)
+    await land(repo, { "src/a.ts": "a\n" })
+    return repo
+  }
+
+  const snapshotAt = async (repo: InMemRepo, git?: GitOperations) => {
+    const rest = await provide(currentRest, repo)
+    const effect = snapshotFromRest(rest)
+    return git === undefined ? await provide(effect, repo) : await provideWithGit(effect, git, repo)
+  }
+
+  it("rests at a message step carrying approve", async () => {
+    const rest = await provide(currentRest, await atGate())
+    expect(rest.state).toBe("gate")
+    expect(rest.stepDef).toMatchObject({ kind: "message", content: "seam report", approve: true })
+  })
+
+  it("refuses a dirty tree and commits nothing", async () => {
+    const repo = await atGate()
+    const head = headOf(repo)
+    repo.writeFile("src/edited.ts", "edit\n")
+    const { landing } = await snapshotAt(repo)
+    expect(landing).toEqual({
+      kind: "refusal",
+      message:
+        "gtd land: approval-gate: gate#1 approves exactly the judged diff — revert your edits and run `gtd land` on a clean tree to approve, or run `gtd abandon`",
+    })
+    expect(headOf(repo)).toBe(head)
+  })
+
+  const stageThenRevert = (repo: InMemRepo): void => {
+    repo.writeFile("src/a.ts", "edited\n")
+    repo.stageAll()
+    repo.writeFile("src/a.ts", "a\n")
+  }
+
+  it("refuses an edit staged and then reverted in the worktree", async () => {
+    const repo = await atGate()
+    stageThenRevert(repo)
+    expect((await snapshotAt(repo)).landing).toMatchObject({
+      kind: "refusal",
+      message: expect.stringContaining("approves exactly the judged diff"),
+    })
+  })
+
+  it("counts no index-only edit at a rest that approves nothing", async () => {
+    const repo = await atGate()
+    await land(repo)
+    stageThenRevert(repo)
+    const rest = await provide(currentRest, repo)
+    expect(rest.state).toBe("after")
+    expect(rest.changes).toEqual([])
+    expect((await snapshotAt(repo)).landing).toEqual({ kind: "noop", settled: false })
+  })
+
+  it("refuses a clean tree when git has no author identity", async () => {
+    const repo = await atGate()
+    const git = { ...fakeGitOperations(repo), authorIdent: () => Effect.succeed(Option.none()) }
+    const { landing } = await snapshotAt(repo, git)
+    expect(landing).toEqual({
+      kind: "refusal",
+      message:
+        "gtd land: approval-gate: gate#1 records who approved it, but git has no author identity — set user.name and user.email",
+    })
+  })
+
+  it("refuses an identity a trailer cannot carry", async () => {
+    const repo = await atGate()
+    const git = {
+      ...fakeGitOperations(repo),
+      authorIdent: () => Effect.succeed(Option.some({ name: "Ada\u001b[31m", email: "a@x.io" })),
+    }
+    expect((await snapshotAt(repo, git)).landing).toEqual({
+      kind: "refusal",
+      message:
+        "gtd land: approval-gate: gate#1 cannot record Ada\u001b[31m <a@x.io> as approver — it would not read back unchanged from its Gtd-Approved trailer (a control character, for example)",
+    })
+  })
+
+  it("approve implies acceptClean even when acceptClean is false", async () => {
+    const repo = repoWith(GATED.replace("approve: true", "approve: true, acceptClean: false"))
+    await land(repo, { "src/a.ts": "a\n" })
+    expect((await snapshotAt(repo)).landing.kind).toBe("commit")
+  })
+
+  it("lands a clean tree as a commit carrying the approver", async () => {
+    const repo = await atGate()
+    const { landing } = await snapshotAt(repo)
+    if (landing.kind !== "commit") throw new Error(`expected commit, got ${landing.kind}`)
+    expect(landing.to).toBe("after")
+    expect(landing.spec.approved).toEqual({
+      step: { name: "gate", occurrence: 1 },
+      name: "Test",
+      email: "test@test.com",
+    })
+  })
+
+  it("reads the author identity only at an approve rest", async () => {
+    const repo = repoWith(GATED)
+    repo.writeFile("src/a.ts", "a\n")
+    const git = {
+      ...fakeGitOperations(repo),
+      authorIdent: () => Effect.die(new Error("authorIdent read at a plain rest")),
+    }
+    expect((await snapshotAt(repo, git)).landing.kind).toBe("commit")
+  })
+
+  it("collects each approval of the current process, oldest first", async () => {
+    const repo = await atGate()
+    expect((await provide(currentRun, repo)).approvals).toEqual([])
+    const approval = await land(repo)
+    expect((await provide(currentRun, repo)).approvals).toEqual([
+      { step: "gate#1", name: "Test", email: "test@test.com", commit: approval },
+    ])
+  })
+
+  it("resumes past the approval commit without asking again", async () => {
+    const repo = await atGate()
+    await land(repo)
+    expect(repo.lastCommitMessage()).toContain(
+      'Gtd-Approved: {"step":"gate#1","name":"Test","email":"test@test.com"}',
+    )
+    expect((await provide(currentRest, repo)).state).toBe("after")
+  })
+})

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