@pmelab/gtd 27.3.0 → 27.4.0

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

package/src/replay/Replay.ts

@@ -236,7 +236,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
   agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
-  human: new Set([...STEERING_OPTIONS, "message", "acceptClean"]),
+  human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
 }
@@ -249,6 +249,14 @@ const unknownOptions = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": unknown key(s) ${unknown.join(", ")} in ${step.kind}() options`
 }
 
+const approveConflict = (step: ReachedStep): string | undefined => {
+  const request = step.request
+  if (request.kind !== "human" || request.options.approve !== true) return undefined
+  const keys = (["mode", "file"] as const).filter((key) => request.options[key] !== undefined)
+  if (keys.length === 0) return undefined
+  return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`
+}
+
 export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
@@ -485,10 +493,20 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`,
       }
     }
-    const error = unknownOptions(step) ?? checkIdentity(step)
+    const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
+  const missingApproval = (step: ReachedStep, commit: ParsedCommit, expected: string) => {
+    if (step.request.kind !== "human" || step.request.options.approve !== true) return undefined
+    const approved = commit.parsed.approved
+    if (approved !== undefined && formatStepId(approved.step) === expected) return undefined
+    return {
+      kind: "divergence" as const,
+      message: `gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it — ${DIVERGED}`,
+    }
+  }
+
   const consumeCommit = (step: ReachedStep, commit: ParsedCommit): unknown => {
     const recorded = commit.parsed.step
     const expected = formatStepId(step.id)
@@ -500,6 +518,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}" — ${DIVERGED}`,
       })
     }
+    const unapproved = missingApproval(step, commit, expected)
+    if (unapproved !== undefined) return finish(unapproved)
     cursor++
     advance(commit)
     if (commit.parsed.kept !== undefined) {

package/src/replay/Trailers.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest"
-import { formatCommitMessage, parseCommitMessage, parseSubject } from "./Trailers.js"
+import {
+  formatCommitMessage,
+  isRecordableApproval,
+  parseCommitMessage,
+  parseSubject,
+} from "./Trailers.js"
 
 describe("the commit-message codec", () => {
   it("round-trips a step commit's subject and trailers", () => {
@@ -173,3 +178,107 @@ describe("Gtd-Kept", () => {
     expect(parsed.format).toBe(1)
   })
 })
+
+describe("Gtd-Approved", () => {
+  const approved = {
+    step: { name: "seam", occurrence: 2 },
+    name: "Ada Lovelace",
+    email: "ada@x.io",
+  }
+  const line = (value: string) => `gtd(human): a → b\n\nGtd-Approved: ${value}`
+
+  it("is written as one JSON line between Gtd-Judge and Gtd-Branch and round-trips", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "next",
+      from: "seam",
+      step: { name: "seam", occurrence: 2 },
+      judge: [{ id: "v", answer: "yes", p: 1 }],
+      branch: "feat",
+      approved,
+    })
+    const lines = message.split("\n")
+    const at = lines.indexOf(
+      'Gtd-Approved: {"step":"seam#2","name":"Ada Lovelace","email":"ada@x.io"}',
+    )
+    expect(at).toBeGreaterThan(-1)
+    expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
+    expect(lines[at + 1]).toBe("Gtd-Branch: feat")
+    expect(parseCommitMessage(message).approved).toEqual(approved)
+  })
+
+  it.each([
+    ["a plain step", "seam"],
+    ["a step with a space and hash", "phase#1 review"],
+    ["a step with angle brackets", "a <b> c"],
+    ["a scoped step", "pkg.seam"],
+    ["a quote/backslash approver name", "seam", 'Ada "A" \\ L'],
+  ])("round-trips %s", (_label, stepName, approver = "Ada") => {
+    const a = { step: { name: stepName, occurrence: 3 }, name: approver, email: "a@x.io" }
+    expect(
+      parseCommitMessage(formatCommitMessage({ actor: "human", to: "b", approved: a })).approved,
+    ).toEqual(a)
+  })
+
+  it("reads undefined for the old shape, non-objects and bad fields", () => {
+    for (const value of [
+      "seam#1 Ada <a@x.io>",
+      "",
+      "[]",
+      '"x"',
+      "null",
+      '{"step":"seam#1","name":"Ada"}',
+      '{"step":"seam#1","name":"Ada","email":1}',
+      '{"step":"seam","name":"Ada","email":"a@x.io"}',
+      '{"step":"seam#0","name":"Ada","email":"a@x.io"}',
+    ]) {
+      expect(parseCommitMessage(line(value)).approved).toBe(undefined)
+    }
+  })
+
+  it("reads undefined for a control character in any field", () => {
+    for (const json of [
+      '{"step":"se\\u001bam#1","name":"Ada","email":"a@x.io"}',
+      '{"step":"seam#1","name":"Ada\\u0007","email":"a@x.io"}',
+      '{"step":"seam#1","name":"Ada","email":"a\\u0085@x.io"}',
+    ]) {
+      expect(parseCommitMessage(line(json)).approved).toBe(undefined)
+    }
+  })
+
+  it("reads undefined when absent", () => {
+    expect(parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" })).approved).toBe(
+      undefined,
+    )
+  })
+})
+
+describe("isRecordableApproval", () => {
+  const of = (name: string, email: string, occurrence = 1) => ({
+    step: { name: "gate", occurrence },
+    name,
+    email,
+  })
+
+  it("accepts ordinary, quoted, backslashed and angle-bracketed identities", () => {
+    for (const name of ["Ada", 'A "B"', "A\\B", "A <B>"]) {
+      expect(isRecordableApproval(of(name, "a@x.io"))).toBe(true)
+    }
+    expect(isRecordableApproval(of("Ada", "a<b>@x.io"))).toBe(true)
+  })
+
+  it("refuses a C1 control character in name or email", () => {
+    expect(isRecordableApproval(of("Ada\u0085", "a@x.io"))).toBe(false)
+    expect(isRecordableApproval(of("Ada", "a\u0085@x.io"))).toBe(false)
+  })
+
+  it("refuses a JS line terminator that would split the trailer on read", () => {
+    const name = "x\u2028Gtd-Branch: forged\u2028"
+    expect(isRecordableApproval(of(name, "a@x.io"))).toBe(false)
+    expect(isRecordableApproval(of("Ada", "a\u2029@x.io"))).toBe(false)
+  })
+
+  it("refuses an occurrence that does not read back", () => {
+    expect(isRecordableApproval(of("Ada", "a@x.io", 0))).toBe(false)
+  })
+})

package/src/replay/Trailers.ts

@@ -60,6 +60,12 @@ export interface CostEntry {
   readonly model: string | undefined
 }
 
+export interface Approval {
+  readonly step: StepId
+  readonly name: string
+  readonly email: string
+}
+
 export interface CommitMessage {
   readonly subject: string
   readonly parsed: ParsedSubject | undefined
@@ -77,6 +83,8 @@ export interface CommitMessage {
   readonly version: string | undefined
   /** The off-branch tip a keep step set aside; a non-hash value is skipped. */
   readonly kept: string | undefined
+  /** `Gtd-Approved`; a malformed or control-character value is skipped. */
+  readonly approved: Approval | undefined
   readonly format: number
 }
 
@@ -106,7 +114,7 @@ const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/
 // JSON string. A control character is refused on read: history written by
 // someone else must never put escape sequences on a terminal.
 // eslint-disable-next-line no-control-regex -- the control range IS the point
-const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/
 const encodePath = (path: string): string =>
   path.trim() !== path || path.startsWith('"') || CONTROL_CHARACTER.test(path)
     ? JSON.stringify(path)
@@ -115,6 +123,24 @@ const decodePath = (raw: string): string | undefined => {
   const path = raw.startsWith('"') ? parseJson(raw) : raw
   return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
 }
+const decodeApproval = (raw: string): Approval | undefined => {
+  const parsed = parseJson(raw)
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
+  const { step, name, email } = parsed as Record<string, unknown>
+  if (typeof step !== "string" || typeof name !== "string" || typeof email !== "string")
+    return undefined
+  if ([step, name, email].some((field) => CONTROL_CHARACTER.test(field))) return undefined
+  const id = parseStepId(step)
+  return id === undefined ? undefined : { step: id, name, email }
+}
+const encodeApproval = ({ step, name, email }: Approval): string =>
+  JSON.stringify({ step: formatStepId(step), name, email })
+// The land-time refusal relies on this: an approval that would not read back
+// unchanged must never be written.
+export const isRecordableApproval = (approval: Approval): boolean => {
+  const back = decodeApproval(encodeApproval(approval))
+  return back !== undefined && encodeApproval(back) === encodeApproval(approval)
+}
 const FORMAT_RE = /^[1-9][0-9]*$/
 const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
 
@@ -125,6 +151,7 @@ interface Trailers {
   branch: string | undefined
   version: string | undefined
   kept: string | undefined
+  approved: Approval | undefined
   readonly judge: JudgeVerdict[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
@@ -164,6 +191,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Kept": (value, into) => {
     if (HASH_RE.test(value)) into.kept ??= value
   },
+  "Gtd-Approved": (value, into) => {
+    into.approved ??= decodeApproval(value)
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -183,6 +213,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     branch: undefined,
     version: undefined,
     kept: undefined,
+    approved: undefined,
     judge: [],
     vars: {},
     config: {},
@@ -208,6 +239,8 @@ export interface CommitSpec {
   readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
+  /** Written after `Gtd-Judge`, before `Gtd-Branch`. */
+  readonly approved?: Approval
   readonly branch?: string
   readonly version?: string
 }
@@ -230,6 +263,9 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     )
   }
   for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  if (spec.approved !== undefined) {
+    lines.push(`Gtd-Approved: ${encodeApproval(spec.approved)}`)
+  }
   if (spec.branch !== undefined) lines.push(`Gtd-Branch: ${spec.branch}`)
   if (spec.version !== undefined) lines.push(`Gtd-Version: ${spec.version}`)
   lines.push(`Gtd-Format: ${HISTORY_FORMAT}`)

package/src/replay/index.ts

@@ -2,7 +2,9 @@ export { replay, type EpisodeCommit, type ReachedStep, type ReplayOutcome } from
 export { treeFromRecord, type TreeView } from "./Tree.js"
 export {
   formatCommitMessage,
+  formatStepId,
   formatSubject,
+  isRecordableApproval,
   parseCommitMessage,
   type CommitSpec,
   type JudgeVerdict,

package/src/replay/seamGate.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest"
+import { human, seamGate, type DiffShape, type DiffShapeResult, type Flow } from "../flows/index.js"
+import { replay, treeFromRecord } from "./index.js"
+
+// Lives in replay, which drives a flow to its rest (flows tests may not import replay).
+const shape = (
+  choice: DiffShape,
+  strays: string[] = [],
+  unreadable: string[] = [],
+): DiffShapeResult => ({ choice, strays, unreadable, judgment: undefined })
+
+const restOf = async (result: DiffShapeResult) => {
+  const flow: Flow = async () => {
+    await seamGate("seam", result)
+    await human("next")
+  }
+  const outcome = await replay({
+    flow,
+    episode: { base: { hash: "0".repeat(40), tree: treeFromRecord({}) }, commits: [] },
+    vars: {},
+    env: {},
+    start: "0".repeat(40),
+    budgetBytes: 1024,
+  })
+  if (outcome.kind !== "rest") throw new Error(`expected a rest, got ${outcome.kind}`)
+  return outcome.rest
+}
+
+describe("seamGate", () => {
+  for (const choice of ["land", "reject"] as const) {
+    it(`reaches no step on ${choice}: the flow's next step is the rest`, async () => {
+      const rest = await restOf(shape(choice, ["a.ts"]))
+      expect(rest.name).toBe("next")
+    })
+  }
+
+  it("rests at an approve human step named after the caller on refactor-first", async () => {
+    const rest = await restOf(shape("refactor-first", ["a.ts"]))
+    expect(rest.name).toBe("seam")
+    expect(rest.request).toMatchObject({ kind: "human", options: { approve: true } })
+  })
+
+  it("lists every stray in order, marks only the unreadable, names gtd land and gtd abandon", async () => {
+    const rest = await restOf(shape("refactor-first", ["a.ts", "b/c.ts", "z.bin"], ["b/c.ts"]))
+    if (rest.request.kind !== "human") throw new Error("expected a human step")
+    const message = rest.request.options.message ?? ""
+    const lines = message.split("\n")
+    const strays = lines.filter((line) => line.startsWith("- "))
+    expect(strays).toEqual(["- a.ts", "- b/c.ts (unreadable — not judged)", "- z.bin"])
+    expect(message).toMatch(/`gtd land`[^\n]*approve/)
+    expect(message).toContain("`gtd abandon`")
+  })
+
+  it("quotes a stray path with a control character", async () => {
+    const rest = await restOf(shape("refactor-first", ["a\nb", "c\u001b[2K"]))
+    if (rest.request.kind !== "human") throw new Error("expected a human step")
+    const strays = (rest.request.options.message ?? "")
+      .split("\n")
+      .filter((line) => line.startsWith("- "))
+    expect(strays).toEqual(['- "a\\nb"', '- "c\\u001b[2K"'])
+  })
+})

package/src/step/LandStep.ts

@@ -8,6 +8,7 @@ import type { StateName } from "../workflow/index.js"
  */
 export type GitWrite =
   | { readonly kind: "commitAll"; readonly message: string }
+  | { readonly kind: "commitClean"; readonly message: string }
   | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
   | { readonly kind: "keepTurn"; readonly ref: string; readonly message: string }
 

package/src/step/planStep.test.ts

@@ -131,6 +131,38 @@ describe("planStep — keepHistory", () => {
   })
 })
 
+describe("planStep — approval landing", () => {
+  const approved = { step: { name: "gate", occurrence: 1 }, name: "Ada", email: "ada@x.io" }
+
+  it("commits with commitClean when the landing records an approval", () => {
+    const base = commitTo("gate", "again")
+    const s = snapshot({
+      state: "gate",
+      stepDef: {},
+      landing: { ...base, spec: { ...base.spec, approved } },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "commitClean" } })
+  })
+
+  it("a finishing approval still points the history ref after the commitClean write", () => {
+    const base = commitTo("gate", "idle")
+    const s = snapshot({
+      state: "gate",
+      stepDef: {},
+      landing: { ...base, spec: { ...base.spec, approved }, keepHistory: "refs/gtd/history/abc" },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps.map((x) => (x.kind === "gitWrite" ? x.write.kind : x.kind))).toEqual([
+      "commitClean",
+      "updateRef",
+      "outcome",
+    ])
+  })
+})
+
 describe("planStep — keepTurn", () => {
   const kept = "refs/gtd/kept/abc/building"
 

package/src/step/planStep.ts

@@ -87,7 +87,9 @@ export const planStep = (
         write:
           landing.keepTurn !== undefined
             ? { kind: "keepTurn", ref: landing.keepTurn, message }
-            : { kind: "commitAll", message },
+            : landing.spec.approved !== undefined
+              ? { kind: "commitClean", message }
+              : { kind: "commitAll", message },
       },
       ...(landing.keepHistory !== undefined
         ? [

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest"
 import {
   commitAll,
   commitAsIs,
+  commitClean,
   deleteRef,
   discardPending,
   hardResetTo,
@@ -664,3 +665,29 @@ describe("applyEmittedScript — keepTurn", () => {
     expect(repo.resolveRef(REF)).toBeNull()
   })
 })
+
+describe("applyEmittedScript — commitClean", () => {
+  const MESSAGE = 'gtd(human): gate → again\n\nGtd-Approved: {"step":"gate#1"}'
+
+  it("applies the rendered block as an empty commit over HEAD", () => {
+    const repo = new InMemRepo()
+    repo.writeFile("base.txt", "0")
+    repo.seedCommit("chore: first")
+    const result = applyEmittedScript(repo, NO_COMMANDS, commitClean(MESSAGE))
+    expect(result).toMatchObject({ ok: true })
+    expect(repo.lastCommitMessage()).toBe(MESSAGE)
+    expect(repo.statusPorcelain()).toBe("")
+  })
+
+  it("fails loudly on a one-character near-miss and applies nothing", () => {
+    const repo = new InMemRepo()
+    repo.writeFile("base.txt", "0")
+    repo.seedCommit("chore: first")
+    const before = snapshot(repo)
+    const nearMiss = commitClean(MESSAGE).replace("update-ref -m", "update-ref -n")
+    const result = applyEmittedScript(repo, NO_COMMANDS, nearMiss)
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain("unrecognized script block")
+    expect(snapshot(repo)).toEqual(before)
+  })
+})