@pmelab/gtd 27.3.0 → 27.5.0

package/src/edge/Edge.test.ts

@@ -22,7 +22,7 @@ import { GTD_VERSION } from "../install/index.js"
 import { keptRef, processHistoryRef } from "../platform/index.js"
 import { GitService, Workspace, type GitOperations, type WorkspaceOps } from "../platform/index.js"
 import { formatCommitMessage, type CommitSpec } from "../replay/index.js"
-import { contentHash } from "../workflow/index.js"
+import { contentHash, StartFlags } from "../workflow/index.js"
 import {
   fakeGitOperations,
   InMemRepo,
@@ -151,6 +151,7 @@ describe("currentRun", () => {
       trace: [],
       costEntries: [],
       judgeVerdicts: [],
+      approvals: [],
       pinnedVars: {},
       headTurn: undefined,
       closingHash: undefined,
@@ -780,6 +781,50 @@ export const defaults = { deployTarget: "npm test", reviewer: "nobody" }
   })
 })
 
+describe("StartFlags", () => {
+  const FLAGGED = `import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+}
+
+export const side = async () => {
+  await agent("working", "w")
+}
+
+export const defaults = { flag_naive_pass: "0", other: "x" }
+`
+  const withFlags = <A>(
+    eff: Effect.Effect<A, Error, RestRequirements>,
+    repo: InMemRepo,
+    flags: Record<string, string>,
+  ): Promise<A> =>
+    Effect.runPromise(
+      eff.pipe(Effect.provideService(StartFlags, flags), Effect.provide(testLayers(repo, {}))),
+    )
+
+  it("a starting process takes the declared flag from StartFlags, never an undeclared one", async () => {
+    const rest = await withFlags(currentRest, repoWith(FLAGGED), {
+      flag_naive_pass: "1",
+      flag_other: "1",
+    })
+    expect(rest.vars).toEqual({ flag_naive_pass: "1", other: "x" })
+  })
+
+  it("a running process missing the pin resolves the declared default, never the live flag", async () => {
+    const repo = repoWith(FLAGGED.replace('flag_naive_pass: "0", ', ""))
+    await enter(repo, "side")
+    // a process started before the flag existed: its opening commit lacks the pin
+    repo.writeFile("gtd.config.ts", FLAGGED)
+    const rest = await withFlags(currentRest, repo, { flag_naive_pass: "1" })
+    expect(rest.vars.flag_naive_pass).toBe("0")
+  })
+
+  it("with no StartFlags provided, resolves the declared default", async () => {
+    expect((await provide(currentRest, repoWith(FLAGGED))).vars.flag_naive_pass).toBe("0")
+  })
+})
+
 describe("environment settings", () => {
   const ENVV = `import { agent, human } from "@pmelab/gtd/flows"
 
@@ -1306,6 +1351,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 +1436,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,
@@ -15,6 +16,8 @@ import {
   contentHash,
   multilineSetting,
   resolveVars,
+  resolveStartVars,
+  StartFlags,
   resolveScopeAccess,
   resolveScopeSkills,
   type ConfigFingerprint,
@@ -29,7 +32,9 @@ import {
 } from "../workflow/index.js"
 import {
   formatFault,
+  formatStepId,
   formatSubject,
+  isRecordableApproval,
   parseCommitMessage,
   replay,
   treeFromRecord,
@@ -41,7 +46,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 +153,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 +242,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 +276,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),
@@ -534,9 +564,11 @@ const settingsFor = (
   pinnedVars: Readonly<Record<string, string>>,
   hostEnv: Readonly<Record<string, string | undefined>>,
   startOverrides: Readonly<Record<string, string>> = {},
+  /** The live flags a STARTING process pins; a running one passes `{}` and replays its pins. */
+  startFlags: Readonly<Record<string, string>>,
 ): { readonly vars: Record<string, string>; readonly env: Record<string, string> } => ({
   vars: {
-    ...resolveVars(workflow.vars, startOverrides, hostEnv),
+    ...resolveStartVars(workflow.vars, startFlags, startOverrides, hostEnv),
     ...pinnedVars,
   },
   env: resolveVars(workflow.env, {}, hostEnv),
@@ -729,7 +761,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 => {
@@ -883,7 +916,14 @@ const setupFor = (
   Effect.gen(function* () {
     const resolved = yield* workflowOf(config, run)
     const def = resolved.def
-    const { vars, env } = settingsFor(resolved, run.pinnedVars, host.env, startOverrides)
+    const startFlags = run.trace.length === 0 ? yield* StartFlags : {}
+    const { vars, env } = settingsFor(
+      resolved,
+      run.pinnedVars,
+      host.env,
+      startOverrides,
+      startFlags,
+    )
     const skills = yield* resolveScopeSkills(def, vars)
     const access = yield* resolveScopeAccess(def, skills, vars)
     const budget = yield* Effect.try({
@@ -933,6 +973,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 +1025,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,
           }))
@@ -1027,7 +1078,7 @@ export const startRefusal = (
 > =>
   Effect.gen(function* () {
     const host = yield* Host
-    const { vars, env } = settingsFor(resolved, {}, host.env, startVars)
+    const { vars, env } = settingsFor(resolved, {}, host.env, startVars, yield* StartFlags)
     const skills = yield* resolveScopeSkills(resolved.def, vars)
     const access = yield* resolveScopeAccess(resolved.def, skills, vars)
     const workspace = rest.setup.workspace
@@ -1107,6 +1158,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 +1259,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 +1287,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 +1305,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 +1328,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 +1344,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,
@@ -1289,7 +1380,7 @@ export const summaryFor = (
         .map((entry) => ({ hash: entry.hash, state: entry.state })),
       processCost: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
       processCostByModel: costByModel(run.costEntries),
-      ...settingsFor(resolved, run.pinnedVars, host.env),
+      ...settingsFor(resolved, run.pinnedVars, host.env, {}, {}),
     })
   })
 
@@ -1300,6 +1391,7 @@ export interface HistoryStep {
   readonly from: StateName | undefined
   readonly to: StateName
   readonly verdicts: readonly JudgeVerdict[]
+  readonly approval?: ApprovalEntry
 }
 
 export interface HistoryTrail {
@@ -1371,6 +1463,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/flags/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { FLAGS, resolveFlags, type FlagDeclaration, type Flags } from "./index.js"
+import { FLAGS, flagSettings, resolveFlags, type FlagDeclaration, type Flags } from "./index.js"
 
 const registry = [
   { name: "alpha", owner: "pmelab", expiry: "2020-01-01", kind: "release" },
@@ -92,4 +92,17 @@ describe("FLAGS", () => {
     })
     expect(new Set(names).size).toBe(names.length)
   })
+
+  it("leaves naive_pass off by default", () => {
+    expect(resolveFlags({}).naive_pass).toBe(false)
+  })
+})
+
+describe("flagSettings", () => {
+  it('maps every flag to "1" or "0" under flag_<name>', () => {
+    expect(flagSettings({ alpha: true, new_review: false })).toEqual({
+      flag_alpha: "1",
+      flag_new_review: "0",
+    })
+  })
 })