@pmelab/gtd 26.0.0 → 26.1.0

package/src/platform/RetainedHistory.ts

@@ -9,6 +9,9 @@ export const PROCESS_HISTORY_PREFIX = "refs/gtd/history/"
 
 export const processHistoryRef = (hash: string): string => `${PROCESS_HISTORY_PREFIX}${hash}`
 
+/** Directory of a step's turns set aside by `keep: true`, each at `<this>/<kept hash>`; own namespace, so history list/show/fetch never see it. */
+export const keptRef = (entry: string, step: string): string => `refs/gtd/kept/${entry}/${step}`
+
 export const readRetainedHistory = (
   git: GitOperations,
 ): Effect.Effect<Option.Option<string>, Error> => git.readRefOption(HISTORY_REF)

package/src/platform/Workspace.test.ts

@@ -83,7 +83,7 @@ const makeInMemTier = (): WorkspaceTier => {
     writeWorking: (path, content) => repo.writeFile(path, content),
     commit: (path, content) => {
       repo.writeFile(path, content)
-      repo.commitAllWithPrefix(`commit ${path}`)
+      repo.seedCommit(`commit ${path}`)
     },
     provide: (eff) =>
       Effect.runPromise(eff.pipe(Effect.provide(Layer.succeed(Workspace, workspaceOps)))),

package/src/platform/index.ts

@@ -21,6 +21,7 @@ export { CommandRunner } from "./CommandRunner.js"
 export { loopLogPath } from "./WorktreeState.js"
 export {
   HISTORY_REF,
+  keptRef,
   processHistoryRef,
   PROCESS_HISTORY_PREFIX,
   readRetainedHistory,

package/src/replay/RefName.test.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process"
+import { describe, expect, it } from "vitest"
+import { refNameFault } from "./RefName.js"
+
+// The predicate's owner: it must agree with git, or an invalid keep name only fails at landing.
+describe("refNameFault", () => {
+  it.each([
+    "a",
+    "a.b",
+    "build.naive",
+    "-a",
+    "ünï",
+    "a@b",
+    "a/b",
+    "a.",
+    "a//b",
+    "/a",
+    "a/",
+    "@",
+    "a@{b",
+    "a..b",
+    "a b",
+    "a~b",
+    "a^b",
+    "a:b",
+    "a?b",
+    "a*b",
+    "a[b",
+    "a\\b",
+    "a\tb",
+    ".a",
+    "a.lock",
+    "a/.b",
+    "a.lock/b",
+    "",
+  ])("agrees with git check-ref-format for %j", (name) => {
+    const git = spawnSync("git", ["check-ref-format", `refs/gtd/kept/e/${name}`])
+    expect(refNameFault(name) === undefined).toBe(git.status === 0)
+  })
+})

package/src/replay/RefName.ts

@@ -0,0 +1,19 @@
+// A kept ref is `refs/gtd/kept/<entry>/<step>`: the step's full name must survive `git check-ref-format`.
+
+// eslint-disable-next-line no-control-regex -- the control range IS the point
+const FORBIDDEN = /[\u0000- \u007f~^:?*[\\]/
+
+/** Why `name` cannot be (part of) a git ref name, or `undefined` when it can. */
+export const refNameFault = (name: string): string | undefined => {
+  if (name === "") return "it is empty"
+  if (FORBIDDEN.test(name)) return "it contains a space, control character or one of ~^:?*[\\"
+  if (name.includes("..")) return 'it contains ".."'
+  if (name.includes("@{")) return 'it contains "@{"'
+  if (name.endsWith(".")) return 'it ends with "."'
+  for (const part of name.split("/")) {
+    if (part === "") return 'it has an empty "/" component'
+    if (part.startsWith(".")) return 'a component starts with "."'
+    if (part.endsWith(".lock")) return 'a component ends with ".lock"'
+  }
+  return undefined
+}

package/src/replay/Replay.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest"
+import { beforeEach, describe, expect, it } from "vitest"
 import fc from "fast-check"
 import {
   FLOWS_PROTOCOL,
@@ -8,6 +8,7 @@ import {
   codeThreads,
   human,
   judge,
+  kept,
   read,
   refuse,
   restart,
@@ -32,6 +33,7 @@ interface Commit {
   readonly hash: string
   readonly message: string
   readonly tree: TreeView
+  readonly kept?: { readonly hash: string; readonly tree: TreeView }
 }
 
 const hashOf = (n: number): string => n.toString(16).padStart(40, "0")
@@ -64,12 +66,19 @@ class History {
     return this
   }
 
-  raw(message: string, edit: Record<string, string | null> = {}): this {
+  raw(
+    message: string,
+    edit: Record<string, string | null> = {},
+    keptTip?: { hash: string; files: Record<string, string> },
+  ): this {
     this.apply(edit)
     this.commits.push({
       hash: hashOf(this.counter++),
       message,
       tree: treeFromRecord({ ...this.files }),
+      ...(keptTip !== undefined
+        ? { kept: { hash: keptTip.hash, tree: treeFromRecord(keptTip.files) } }
+        : {}),
     })
     return this
   }
@@ -600,6 +609,188 @@ describe("replay", () => {
   })
 })
 
+describe("replay: keep", () => {
+  let seen: { read?: string | undefined; changes?: number }
+  beforeEach(() => {
+    seen = {}
+  })
+  const keepFlow =
+    (name = "naive"): Flow =>
+    async () => {
+      await human("idle")
+      await agent(name, "p", { keep: true })
+      seen.read = read("naive.txt")
+      seen.changes = changes().length
+      await human("after")
+    }
+
+  it("accepts keep as an agent option", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(keepFlow(), h)
+    expect(outcome.kind).toBe("rest")
+    expect(restName(outcome)).toBe("naive#1")
+  })
+
+  it("a pending turn completes the keep step but replay stays on the pre-turn tree", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(keepFlow(), h, { pending: { "naive.txt": "naive\n" } })
+    expect(restName(outcome)).toBe("after#1")
+    expect(outcome.kind === "rest" && outcome.landed?.name).toBe("naive")
+    expect(seen.read).toBeUndefined()
+    expect(seen.changes).toBe(0)
+  })
+
+  it("a marker commit answers its step and the next step is reached", async () => {
+    const marker = formatCommitMessage({
+      actor: "agent",
+      from: "naive",
+      to: "after",
+      step: { name: "naive", occurrence: 1 },
+    })
+    const h = new History()
+      .land("human", "idle", 1, "naive", {})
+      .raw(`${marker}\nGtd-Kept: ${hashOf(77)}`)
+    const outcome = await replayOf(keepFlow(), h)
+    expect(restName(outcome)).toBe("after#1")
+    expect(seen.read).toBeUndefined()
+    expect(seen.changes).toBe(0)
+  })
+
+  it("rejects keep together with allowEmpty", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("naive", "p", { keep: true, allowEmpty: true })
+    }
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(flow, h)
+    expect(outcome.kind === "failed" && outcome.message).toContain("allowEmpty")
+  })
+
+  it.each(["a b", "a..b", "a~b", "a.lock", "a:b", "a/b"])(
+    "fails naming the step when %j is not a valid ref component",
+    async (name) => {
+      const h = new History().land("human", "idle", 1, name, {})
+      const outcome = await replayOf(keepFlow(name), h)
+      expect(outcome.kind).toBe("failed")
+      expect(outcome.kind === "failed" && outcome.message).toContain(`step "${name}"`)
+    },
+  )
+
+  it("does not check the name of a step that does not keep", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("a b", "p")
+    }
+    const h = new History().land("human", "idle", 1, "a b", {})
+    expect(restName(await replayOf(flow, h))).toBe("a b#1")
+  })
+})
+
+describe("replay: kept()", () => {
+  const markerFor = (name: string, to: string, occurrence = 1, tip = hashOf(77)): string =>
+    `${formatCommitMessage({
+      actor: "agent",
+      from: name,
+      to,
+      step: { name, occurrence },
+    })}\nGtd-Kept: ${tip}`
+
+  type Tip = ReturnType<typeof kept>
+  let seen: { before?: Tip; after?: Tip }
+  beforeEach(() => {
+    seen = {}
+  })
+  const flow =
+    (name = "naive"): Flow =>
+    async () => {
+      await human("idle")
+      seen.before = kept(name)
+      await agent("naive", "p", { keep: true })
+      seen.after = kept(name)
+      await human("after")
+    }
+
+  it("returns the newest consumed marker's hash and its diff against the marker's tree", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "naive", { "base.txt": "b\n" })
+      .raw(
+        markerFor("naive", "after"),
+        {},
+        { hash: hashOf(77), files: { "base.txt": "b\n", "naive.ts": "export const n = 1\n" } },
+      )
+    const outcome = await replayOf(flow(), h)
+    expect(restName(outcome)).toBe("after#1")
+    expect(seen.after?.hash).toBe(hashOf(77))
+    expect(seen.after?.changes.map((c) => [c.path, c.status, c.after])).toEqual([
+      ["naive.ts", "added", "export const n = 1\n"],
+    ])
+  })
+
+  it("the newest of two passes wins", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "naive", {})
+      .raw(markerFor("naive", "naive", 1, hashOf(70)), {}, { hash: hashOf(70), files: { a: "1" } })
+      .raw(markerFor("naive", "after", 2, hashOf(71)), {}, { hash: hashOf(71), files: { a: "2" } })
+    const twice: Flow = async () => {
+      await human("idle")
+      await agent("naive", "p", { keep: true })
+      await agent("naive", "p", { keep: true })
+      seen.after = kept("naive")
+      await human("after")
+    }
+    await replayOf(twice, h)
+    expect(seen.after?.hash).toBe(hashOf(71))
+    expect(seen.after?.changes.get("a")?.after).toBe("2")
+  })
+
+  it("is undefined for a step that never kept", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {}).land("agent", "naive", 1, "after")
+    expect(restName(await replayOf(flow(), h))).toBe("after#1")
+    expect(seen.after).toBeUndefined()
+  })
+
+  it("is undefined when the marker's kept object is gone", async () => {
+    const h = new History().land("human", "idle", 1, "naive", {}).raw(markerFor("naive", "after"))
+    expect(restName(await replayOf(flow(), h))).toBe("after#1")
+    expect(seen.after).toBeUndefined()
+  })
+
+  it("resolves the name through scope() like agent()", async () => {
+    const scoped: Flow = async () => {
+      await human("idle")
+      await scope("build", async () => {
+        await agent("naive", "p", { keep: true })
+        seen.after = kept("naive")
+      })
+      seen.before = kept("naive")
+      await human("after")
+    }
+    const h = new History()
+      .land("human", "idle", 1, "build.naive", {})
+      .raw(markerFor("build.naive", "after"), {}, { hash: hashOf(77), files: { "x.ts": "x" } })
+    await replayOf(scoped, h)
+    expect(seen.after?.hash).toBe(hashOf(77))
+    expect(seen.before).toBeUndefined()
+  })
+
+  it('shows the pending tip with hash "" during the landing decision', async () => {
+    const h = new History().land("human", "idle", 1, "naive", {})
+    const outcome = await replayOf(flow(), h, { pending: { "naive.ts": "n\n" } })
+    expect(restName(outcome)).toBe("after#1")
+    expect(seen.after?.hash).toBe("")
+    expect(seen.after?.changes.map((c) => [c.path, c.status])).toEqual([["naive.ts", "added"]])
+  })
+
+  it("does not show a marker the flow has not consumed yet", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "naive", {})
+      .raw(markerFor("naive", "after"), {}, { hash: hashOf(77), files: { "x.ts": "x" } })
+    await replayOf(flow(), h)
+    expect(seen.before).toBeUndefined()
+    expect(seen.after?.hash).toBe(hashOf(77))
+  })
+})
+
 describe("replay: skills resolution", () => {
   interface Tiers {
     skills?: Record<string, readonly string[]>

package/src/replay/Replay.ts

@@ -21,6 +21,7 @@ import {
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
+import { refNameFault } from "./RefName.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
 import {
   formatStepId,
@@ -34,6 +35,8 @@ export interface EpisodeCommit {
   readonly hash: string
   readonly message: string
   readonly tree: TreeView
+  /** Present when the commit carries Gtd-Kept and that object still exists. */
+  readonly kept?: { readonly hash: string; readonly tree: TreeView }
 }
 
 /**
@@ -232,7 +235,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // The option keys each step accepts. A gtd.config.ts is evaluated without a
 // 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"]),
+  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
@@ -275,6 +278,11 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const scopeCallIds: number[] = []
   let scopeCallCount = 0
   const trace: ReachedStep[] = []
+  // Newest consumed keep per scoped step name; `before` is the tree the kept turn diverged from.
+  const keptTips = new Map<
+    string,
+    { readonly hash: string; readonly before: TreeView; readonly after: TreeView }
+  >()
   let landed: ReachedStep | undefined
   let outcome: ReplayOutcome | undefined
   let signal: (() => void) | undefined
@@ -494,11 +502,32 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     }
     cursor++
     advance(commit)
+    if (commit.parsed.kept !== undefined) {
+      if (commit.kept === undefined) keptTips.delete(step.name)
+      else
+        keptTips.set(step.name, {
+          hash: commit.kept.hash,
+          before: commit.tree,
+          after: commit.kept.tree,
+        })
+    }
     const to = commit.parsed.parsed?.to
     if (to !== undefined) expectedNext = { name: to, hash: commit.hash }
     return replyFor(step.request, commit.parsed.judge)
   }
 
+  const landPending = (step: ReachedStep, pending: NonNullable<typeof input.pending>): unknown => {
+    pendingUsed = true
+    landed = step
+    // A kept turn is set aside: replay stays on the pre-turn tree, as it will once the marker lands.
+    const keeping = step.request.kind === "agent" && step.request.options.keep === true
+    if (keeping) {
+      keptTips.set(step.name, { hash: "", before: position.tree, after: pending.tree })
+    }
+    advance({ hash: "", tree: keeping ? position.tree : pending.tree })
+    return replyFor(step.request, pending.verdicts ?? [])
+  }
+
   const answer = (step: ReachedStep): unknown => {
     while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) cursor++
     const commit = commits[cursor]
@@ -506,10 +535,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     if (input.pending === undefined || pendingUsed) {
       return finish({ kind: "rest", rest: step, trace, landed })
     }
-    pendingUsed = true
-    landed = step
-    advance({ hash: "", tree: input.pending.tree })
-    return replyFor(step.request, input.pending.verdicts ?? [])
+    return landPending(step, input.pending)
   }
 
   // gtd.config.ts is loaded without a type check.
@@ -517,7 +543,20 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     if (request.kind === "run" && typeof request.body !== "string") {
       return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`
     }
-    return request.kind === "agent" ? scopeAccessFault() : undefined
+    if (request.kind !== "agent") return undefined
+    const name = scoped(request.name)
+    if (request.options.keep === true) {
+      // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
+      if (request.options.allowEmpty === true) {
+        return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`
+      }
+      // "/" would let one step's ref directory collide with another step's ref (git refuses `a` and `a/b` together).
+      const refFault = name.includes("/") ? 'it contains "/"' : refNameFault(name)
+      if (refFault !== undefined) {
+        return `gtd: step "${name}": keep: true files the turn under a git ref named after the step, but ${refFault}`
+      }
+    }
+    return scopeAccessFault()
   }
 
   const handleStep = async (request: StepRequest): Promise<unknown> => {
@@ -611,6 +650,12 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
               .map((f) => f.message),
           }))
         }),
+    kept: (name) => {
+      const tip = keptTips.get(scoped(name))
+      return tip === undefined
+        ? undefined
+        : { hash: tip.hash, changes: changesBetween(tip.before, tip.after) }
+    },
     vars: input.vars,
     env: input.env,
     start: () => input.start,

package/src/replay/Trailers.test.ts

@@ -147,3 +147,29 @@ describe("the commit-message codec", () => {
     expect(parseSubject("gtd(agent): fix")).toEqual({ actor: "agent", to: "fix" })
   })
 })
+
+describe("Gtd-Kept", () => {
+  const hash = "0123456789abcdef0123456789abcdef01234567"
+
+  it("parses a 40-hex hash", () => {
+    expect(parseCommitMessage(`gtd(agent): a → b\n\nGtd-Step: a#1\nGtd-Kept: ${hash}`).kept).toBe(
+      hash,
+    )
+  })
+
+  it("parses a 64-hex (sha256) hash", () => {
+    const sha256 = hash.repeat(2).slice(0, 64)
+    expect(parseCommitMessage(`gtd(agent): a → b\n\nGtd-Kept: ${sha256}`).kept).toBe(sha256)
+  })
+
+  it("skips a non-hash value", () => {
+    expect(parseCommitMessage("gtd(agent): a → b\n\nGtd-Kept: not-a-hash").kept).toBeUndefined()
+    expect(parseCommitMessage(`gtd(agent): a → b\n\nGtd-Kept: ${hash}0`).kept).toBeUndefined()
+  })
+
+  it("reads undefined when absent, and leaves Gtd-Format at 1", () => {
+    const parsed = parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" }))
+    expect(parsed.kept).toBeUndefined()
+    expect(parsed.format).toBe(1)
+  })
+})

package/src/replay/Trailers.ts

@@ -75,6 +75,8 @@ export interface CommitMessage {
   /** Written only on a process's finishing landing. */
   readonly branch: string | undefined
   readonly version: string | undefined
+  /** The off-branch tip a keep step set aside; a non-hash value is skipped. */
+  readonly kept: string | undefined
   readonly format: number
 }
 
@@ -114,6 +116,7 @@ const decodePath = (raw: string): string | undefined => {
   return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
 }
 const FORMAT_RE = /^[1-9][0-9]*$/
+const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
 
 interface Trailers {
   step: StepId | undefined
@@ -121,6 +124,7 @@ interface Trailers {
   reviewBase: string | undefined
   branch: string | undefined
   version: string | undefined
+  kept: string | undefined
   readonly judge: JudgeVerdict[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
@@ -157,6 +161,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Version": (value, into) => {
     if (value !== "") into.version ??= value
   },
+  "Gtd-Kept": (value, into) => {
+    if (HASH_RE.test(value)) into.kept ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -175,6 +182,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     reviewBase: undefined,
     branch: undefined,
     version: undefined,
+    kept: undefined,
     judge: [],
     vars: {},
     config: {},

package/src/replay/index.ts

@@ -9,3 +9,4 @@ export {
 } from "./Trailers.js"
 export { accessShapeFault, foldAccess } from "./Access.js"
 export { formatFault } from "./Format.js"
+export { refNameFault } from "./RefName.js"

package/src/step/LandStep.ts

@@ -9,6 +9,7 @@ import type { StateName } from "../workflow/index.js"
 export type GitWrite =
   | { readonly kind: "commitAll"; readonly message: string }
   | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
+  | { readonly kind: "keepTurn"; readonly ref: string; readonly message: string }
 
 /** A landed step's trailing report, rendered by `GitScript.ts` into a `printf` line. */
 export type Outcome =

package/src/step/RepoSnapshot.ts

@@ -17,6 +17,8 @@ export type Landing =
       readonly spec: CommitSpec
       /** The full history ref a finishing landing points at its own commit. */
       readonly keepHistory?: string
+      /** The kept ref this landing's turn goes to; the branch gets a marker commit instead. */
+      readonly keepTurn?: string
     }
 
 /**

package/src/step/planStart.test.ts

@@ -27,7 +27,7 @@ export const base = (workflow, vars) => (workflow === "reviewcheck" ? (vars.base
 const repoAt = (): InMemRepo => {
   const repo = new InMemRepo()
   repo.writeFile("gtd.config.ts", WORKFLOW)
-  repo.commitAllWithPrefix("chore: add custom workflow")
+  repo.seedCommit("chore: add custom workflow")
   return repo
 }
 
@@ -104,7 +104,7 @@ describe("planStart", () => {
       const fork = repo.resolveRef("HEAD")!
       repo.updateRef("main", fork)
       repo.writeFile("a.txt", "a")
-      repo.commitAllWithPrefix("feat: ahead of main")
+      repo.seedCommit("feat: ahead of main")
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: {} })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
       const write = plan.steps.find((s) => s.kind === "gitWrite")
@@ -117,11 +117,11 @@ describe("planStart", () => {
       const repo = repoAt()
       const fork = repo.resolveRef("HEAD")!
       repo.writeFile("other.txt", "o")
-      repo.commitAllWithPrefix("feat: other branch")
+      repo.seedCommit("feat: other branch")
       repo.updateRef("other", repo.resolveRef("HEAD")!)
       repo.hardResetTo(fork)
       repo.writeFile("mine.txt", "m")
-      repo.commitAllWithPrefix("feat: my branch")
+      repo.seedCommit("feat: my branch")
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: { base: "other" } })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
       const write = plan.steps.find((s) => s.kind === "gitWrite")
@@ -143,7 +143,7 @@ describe("planStart", () => {
       repo.updateRef("old-root", repo.resolveRef("HEAD")!)
       repo.mixedResetTo("4b825dc642cb6eb9a060e54bf8d69288fbee4904")
       repo.writeFile("gtd.config.ts", WORKFLOW)
-      repo.commitAllWithPrefix("chore: a second root")
+      repo.seedCommit("chore: a second root")
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: { base: "old-root" } })
       expect(plan).toEqual({
         kind: "refusal",

package/src/step/planStep.test.ts

@@ -130,3 +130,56 @@ describe("planStep — keepHistory", () => {
     ).toBe(false)
   })
 })
+
+describe("planStep — keepTurn", () => {
+  const kept = "refs/gtd/kept/abc/building"
+
+  it("emits keepTurn in place of commitAll, carrying the step's own commit message", () => {
+    const s = snapshot({
+      state: "building",
+      stepDef: { actor: "agent", kind: "prompt" },
+      actor: "agent",
+      changes: [{ status: "A", path: "naive.txt" }],
+      landing: { ...commitTo("building", "checking", "agent"), keepTurn: kept },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps.map((step) => step.kind)).toEqual(["gitWrite", "outcome"])
+    expect(outcome.steps[0]).toEqual({
+      kind: "gitWrite",
+      write: {
+        kind: "keepTurn",
+        ref: kept,
+        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 1",
+      },
+    })
+  })
+
+  it("a finishing keep landing points the history ref after the marker", () => {
+    const s = snapshot({
+      state: "building",
+      stepDef: { actor: "agent", kind: "prompt" },
+      actor: "agent",
+      landing: {
+        ...commitTo("building", "idle", "agent"),
+        keepTurn: kept,
+        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((step) => step.kind)).toEqual(["gitWrite", "gitWrite", "outcome"])
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "keepTurn" } })
+    expect(outcome.steps[1]).toEqual({
+      kind: "gitWrite",
+      write: { kind: "updateRef", ref: "refs/gtd/history/abc", target: "HEAD" },
+    })
+  })
+
+  it("without keepTurn the landing stays a commitAll", () => {
+    const s = snapshot({ state: "building", stepDef: {}, landing: commitTo("building", "done") })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "commitAll" } })
+  })
+})

package/src/step/planStep.ts

@@ -82,7 +82,13 @@ export const planStep = (
     subject,
     steps: [
       ...uncheckStep(snapshot),
-      { kind: "gitWrite", write: { kind: "commitAll", message } },
+      {
+        kind: "gitWrite",
+        write:
+          landing.keepTurn !== undefined
+            ? { kind: "keepTurn", ref: landing.keepTurn, message }
+            : { kind: "commitAll", message },
+      },
       ...(landing.keepHistory !== undefined
         ? [
             {