@pmelab/gtd 25.0.0 → 26.1.0

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
         ? [
             {

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -5,6 +5,7 @@ import {
   deleteRef,
   discardPending,
   hardResetTo,
+  keepTurn,
   mixedResetTo,
   softResetTo,
   updateRef,
@@ -40,7 +41,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     twin.writeFile("a.txt", "1")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAll("gtd(agent): building"))
-    twin.commitAllWithPrefix("gtd(agent): building")
+    twin.seedCommit("gtd(agent): building")
 
     expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
@@ -84,15 +85,15 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("softResetTo: moves HEAD only, leaving index and worktree untouched", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
     repo.writeFile("b.txt", "2")
-    repo.commitAllWithPrefix("chore: second")
+    repo.seedCommit("chore: second")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("b.txt", "2")
-    twin.commitAllWithPrefix("chore: second")
+    twin.seedCommit("chore: second")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, softResetTo(first))
     twin.softResetTo(first)
@@ -105,15 +106,15 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("mixedResetTo: moves HEAD and index, leaving the worktree untouched", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
     repo.writeFile("b.txt", "2")
-    repo.commitAllWithPrefix("chore: second")
+    repo.seedCommit("chore: second")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("b.txt", "2")
-    twin.commitAllWithPrefix("chore: second")
+    twin.seedCommit("chore: second")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, mixedResetTo(first))
     twin.mixedResetTo(first)
@@ -125,15 +126,15 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("hardResetTo: moves HEAD, index, AND worktree", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
     repo.writeFile("b.txt", "2")
-    repo.commitAllWithPrefix("chore: second")
+    repo.seedCommit("chore: second")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("b.txt", "2")
-    twin.commitAllWithPrefix("chore: second")
+    twin.seedCommit("chore: second")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, hardResetTo(first))
     twin.hardResetTo(first)
@@ -146,12 +147,12 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("discardPending: drops every pending change, tracked or untracked", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.writeFile("a.txt", "changed")
     repo.writeFile("untracked.txt", "new")
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("a.txt", "changed")
     twin.writeFile("untracked.txt", "new")
 
@@ -167,11 +168,11 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("updateRef: points a repo-local ref at a commit hash", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const hash = repo.resolveRef("HEAD")!
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
 
     const result = applyEmittedScript(repo, NO_COMMANDS, updateRef("refs/gtd/base", hash))
     twin.updateRef("refs/gtd/base", hash)
@@ -184,11 +185,11 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
   it("deleteRef: removes a repo-local ref (idempotently)", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.updateRef("refs/gtd/base", repo.resolveRef("HEAD")!)
     const twin = new InMemRepo()
     twin.writeFile("a.txt", "1")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.updateRef("refs/gtd/base", twin.resolveRef("HEAD")!)
 
     const result = applyEmittedScript(repo, NO_COMMANDS, deleteRef("refs/gtd/base"))
@@ -405,7 +406,7 @@ describe("applyEmittedScript — a tripped precondition stops the script", () =>
   it("fails at the precondition and never applies a subsequent recognizable block", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const actualHead = repo.resolveRef("HEAD")!
     const wrongHash = "0".repeat(40)
     expect(wrongHash).not.toBe(actualHead)
@@ -426,7 +427,7 @@ describe("applyEmittedScript — a tripped precondition stops the script", () =>
   it("a satisfied precondition is a no-op and lets the rest of the script run", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const actualHead = repo.resolveRef("HEAD")!
 
     const script = [preconditionHeadEquals(actualHead), commitAll("gtd(agent): lands")].join("\n\n")
@@ -442,7 +443,7 @@ describe("applyEmittedScript — a realistic assembled multi-block script", () =
   it("parses set -eu and a satisfied precondition alongside real builder blocks", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     const first = repo.resolveRef("HEAD")!
 
     const script = [
@@ -464,11 +465,11 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
   it("an assembled commitAll applies exactly like commitAllWithPrefix", () => {
     const repo = new InMemRepo()
     repo.writeFile("base.txt", "0")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.writeFile("a.txt", "1")
     const twin = new InMemRepo()
     twin.writeFile("base.txt", "0")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("a.txt", "1")
 
     const steps: readonly EmitStep[] = [
@@ -476,7 +477,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
     ]
     const { required } = emitScripts(steps)
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
-    twin.commitAllWithPrefix("gtd(agent): building")
+    twin.seedCommit("gtd(agent): building")
 
     expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
@@ -485,7 +486,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
   it("a squash's four gitWrite steps (retain, soft-reset, commit-as-is, discard) apply in order", () => {
     const repo = new InMemRepo()
     repo.writeFile("a.txt", "1")
-    repo.commitAllWithPrefix("gtd(agent): building")
+    repo.seedCommit("gtd(agent): building")
     const tip = repo.resolveRef("HEAD")!
     // Untracked, never staged — the index still matches the tip's own tree
     // exactly, mirroring the real flow where nothing `git add`s between the
@@ -537,11 +538,11 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
   it("a realistic assembled script — commitAll's gitWrite plus a trailing outcome step — applies exactly like commitAllWithPrefix, the outcome step contributing nothing", () => {
     const repo = new InMemRepo()
     repo.writeFile("base.txt", "0")
-    repo.commitAllWithPrefix("chore: first")
+    repo.seedCommit("chore: first")
     repo.writeFile("a.txt", "1")
     const twin = new InMemRepo()
     twin.writeFile("base.txt", "0")
-    twin.commitAllWithPrefix("chore: first")
+    twin.seedCommit("chore: first")
     twin.writeFile("a.txt", "1")
 
     const steps: readonly EmitStep[] = [
@@ -550,7 +551,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
     ]
     const { required } = emitScripts(steps)
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
-    twin.commitAllWithPrefix("gtd(agent): building")
+    twin.seedCommit("gtd(agent): building")
 
     expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
@@ -636,3 +637,30 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
     expect(result.error).toContain("totally-unrecognized-required-command")
   })
 })
+
+describe("applyEmittedScript — keepTurn", () => {
+  const MESSAGE = "gtd(agent): a → b\n\nGtd-Step: a#1\nGtd-Format: 1"
+  const REF = "refs/gtd/kept/entry/a"
+
+  const seeded = (): InMemRepo => {
+    const repo = new InMemRepo()
+    repo.writeFile("base.txt", "0")
+    repo.seedCommit("chore: first")
+    repo.writeFile("turn.txt", "1")
+    return repo
+  }
+
+  it("fails loudly on a near-miss and applies nothing", () => {
+    const repo = seeded()
+    const before = snapshot(repo)
+    const nearMiss = keepTurn(REF, MESSAGE).replace(
+      "git reset --hard HEAD",
+      "git reset --soft HEAD",
+    )
+    const result = applyEmittedScript(repo, NO_COMMANDS, nearMiss)
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain("unrecognized script block")
+    expect(snapshot(repo)).toEqual(before)
+    expect(repo.resolveRef(REF)).toBeNull()
+  })
+})

package/src/testkit/EmittedScriptRecognizer.ts

@@ -9,6 +9,7 @@ import {
   deleteRef,
   discardPending,
   hardResetTo,
+  keepTurn,
   mixedResetTo,
   shellQuote,
   softResetTo,
@@ -30,6 +31,7 @@ import {
   steeringFormatFor,
   type SteeringFormat,
 } from "../steering/index.js"
+import { refNameFault } from "../replay/index.js"
 import { renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
@@ -140,6 +142,20 @@ const conditionStatement = (block: string): string => {
   return end === -1 ? block.slice(start) : block.slice(start, end)
 }
 
+/** `keepTurn`: an invalid ref name fails before anything moves, as `git update-ref` does. */
+const recognizeKeepTurn = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
+  const [message, refDir] = extractQuotedTokens(block)
+  const ref = refDir?.slice(0, -1)
+  if (message === undefined || ref === undefined || keepTurn(ref, message) !== block) {
+    return undefined
+  }
+  if (refNameFault(ref) !== undefined) {
+    return { kind: "failed", error: `fatal: invalid ref format: ${ref}`, status: 128 }
+  }
+  const failure = repo.keepTurn(ref, message)
+  return failure === undefined ? { kind: "applied" } : { kind: "failed", error: failure, status: 1 }
+}
+
 // fallow-ignore-next-line complexity
 const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   if (block === discardPending()) {
@@ -156,11 +172,15 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   // quoted argument.
   const conditionLine = conditionStatement(block)
 
+  if (block.startsWith("git add -A || exit 1\ngtd_sign_cfg=")) return recognizeKeepTurn(repo, block)
+
   if (block.startsWith("git add -A || exit 1\n")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAll(message) === block) {
-      repo.commitAllWithPrefix(message)
-      return { kind: "applied" }
+      const failure = repo.commitAllWithPrefix(message)
+      return failure === undefined
+        ? { kind: "applied" }
+        : { kind: "failed", error: failure, status: 1 }
     }
     return undefined
   }
@@ -168,8 +188,10 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   if (block.startsWith("if ! out=$(git commit --allow-empty -m ")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAsIs(message) === block) {
-      repo.commitAsIs(message)
-      return { kind: "applied" }
+      const failure = repo.commitAsIs(message)
+      return failure === undefined
+        ? { kind: "applied" }
+        : { kind: "failed", error: failure, status: 1 }
     }
     return undefined
   }