@pmelab/gtd 60.0.0 → 61.0.0

package/src/replay/Format.test.ts

@@ -2,25 +2,31 @@ import { describe, expect, it } from "vitest"
 import { formatCommitMessage, formatFault, parseCommitMessage } from "./index.js"
 
 describe("the history format", () => {
-  it("accepts a history entirely in the current format", () => {
-    expect(formatFault([{ hash: "a".repeat(40), format: 1 }])).toBeUndefined()
+  it("accepts a history in the current format and in the one before it", () => {
+    expect(formatFault([{ hash: "a".repeat(40), format: 2 }])).toBeUndefined()
+    expect(
+      formatFault([
+        { hash: "a".repeat(40), format: 1 },
+        { hash: "b".repeat(40), format: 2 },
+      ]),
+    ).toBeUndefined()
     expect(formatFault([])).toBeUndefined()
   })
 
   it("names the first foreign commit, the found and readable formats, and what to do", () => {
     const fault = formatFault([
       { hash: "a".repeat(40), format: 1 },
-      { hash: "b".repeat(40), format: 2 },
-      { hash: "c".repeat(40), format: 3 },
+      { hash: "b".repeat(40), format: 3 },
+      { hash: "c".repeat(40), format: 4 },
     ])
     expect(fault).toBe(
-      "gtd: commit bbbbbbb is written in history format 2, but this gtd reads format 1 — run a gtd release that reads format 2 to continue this process",
+      "gtd: commit bbbbbbb is written in history format 3, but this gtd reads formats 1 to 2 — run a gtd release that reads format 3 to continue this process",
     )
   })
 })
 
 describe("Gtd-Approved and the history format", () => {
-  it("leaves Gtd-Format at 1 on a message carrying it", () => {
+  it("writes the current format on a message carrying it", () => {
     const message = formatCommitMessage({
       actor: "human",
       to: "b",
@@ -29,7 +35,28 @@ describe("Gtd-Approved and the history format", () => {
     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)
+    expect(message).toContain("Gtd-Format: 2")
+    expect(parseCommitMessage(message).format).toBe(2)
+  })
+})
+
+describe("Gtd-Pin", () => {
+  it("round-trips add and remove, after Gtd-Mark and before Gtd-Branch", () => {
+    const message = formatCommitMessage({
+      actor: "check",
+      from: "unpin",
+      to: "idle",
+      pin: "remove",
+      branch: "main",
+    })
+    expect(message).toBe(
+      "gtd(check): unpin → idle\n\nGtd-Pin: remove\nGtd-Branch: main\nGtd-Format: 2",
+    )
+    expect(parseCommitMessage(message).pin).toBe("remove")
+    expect(parseCommitMessage("gtd(check): pin → a\n\nGtd-Pin: add").pin).toBe("add")
+  })
+
+  it("reads an unknown value as no pin", () => {
+    expect(parseCommitMessage("gtd(check): pin → a\n\nGtd-Pin: frozen").pin).toBeUndefined()
   })
 })

package/src/replay/Format.ts

@@ -1,14 +1,17 @@
 // Bump only when what replay reads back out of git changes incompatibly — the
 // package version must not stand in for it, since most majors leave history
-// untouched. A bump that keeps reading the previous format widens the check below.
-export const HISTORY_FORMAT = 1
+// untouched. Format 2 adds pin commits, which format 1 would replay as turns.
+export const HISTORY_FORMAT = 2
+const OLDEST_READABLE_FORMAT = 1
 
 const short = (hash: string): string => hash.slice(0, 7)
 
 export const formatFault = (
   commits: readonly { readonly hash: string; readonly format: number }[],
 ): string | undefined => {
-  const foreign = commits.find((c) => c.format !== HISTORY_FORMAT)
+  const foreign = commits.find(
+    (c) => c.format < OLDEST_READABLE_FORMAT || c.format > HISTORY_FORMAT,
+  )
   if (foreign === undefined) return undefined
-  return `gtd: commit ${short(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads format ${HISTORY_FORMAT} — run a gtd release that reads format ${foreign.format} to continue this process`
+  return `gtd: commit ${short(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads formats ${OLDEST_READABLE_FORMAT} to ${HISTORY_FORMAT} — run a gtd release that reads format ${foreign.format} to continue this process`
 }

package/src/replay/Replay.test.ts

@@ -6,6 +6,7 @@ import {
   changes,
   changesSince,
   codeThreads,
+  head,
   human,
   judge,
   kept,
@@ -1217,3 +1218,56 @@ describe("human({ approve })", () => {
     expect(outcome.kind).toBe("rest")
   })
 })
+
+describe("pin commits", () => {
+  const PIN = ".gtd/process.gtdpin"
+  const pinned = () =>
+    new History()
+      .land("human", "idle", 1, "build", { "NOTE.md": "n" })
+      .raw("gtd(check): pin → build\n\nGtd-Pin: add", { [PIN]: "gtdpin 1 gtd 1\n" })
+
+  it("are never a turn: the next step answers from the commit after the pin", async () => {
+    const flow = async () => {
+      await human("idle")
+      await agent("build", "b")
+      await agent("check", "c")
+    }
+    const h = pinned().land("agent", "build", 1, "check", { "a.ts": "a" })
+    expect(restName(await replayOf(flow, h))).toBe("check#1")
+  })
+
+  it("hide the pin from every tree flow code reads, so a turn's changes leave it out", async () => {
+    let seen: { readonly changed: readonly string[]; readonly pin: string | undefined } | undefined
+    const flow = async () => {
+      await human("idle")
+      await agent("build", "b")
+      seen = { changed: changes().map((c) => c.path), pin: read(PIN) }
+      await agent("check", "c")
+    }
+    const h = pinned().land("agent", "build", 1, "check", { "a.ts": "a" })
+    await replayOf(flow, h)
+    expect(seen).toEqual({ changed: ["a.ts"], pin: undefined })
+  })
+
+  it("are never what head() names: a flow reverting the start reverts the turn", async () => {
+    let named: string | undefined
+    const flow = async () => {
+      await human("idle")
+      named = head()
+      await agent("build", "b")
+    }
+    await replayOf(flow, pinned())
+    expect(named).toBe(hashOf(1))
+  })
+
+  it("trailing an ended flow are no divergence", async () => {
+    const flow = async () => {
+      await human("idle")
+      await agent("build", "b")
+    }
+    const h = pinned()
+      .land("agent", "build", 1, "unpin", { "a.ts": "a" })
+      .raw("gtd(check): unpin → idle\n\nGtd-Pin: remove", { [PIN]: null })
+    expect((await replayOf(flow, h)).kind).toBe("ended")
+  })
+})

package/src/replay/Replay.ts

@@ -20,17 +20,20 @@ import {
   threads,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
-import { globMatches } from "../wire/index.js"
+import { globMatches, PIN_PATH } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
-import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
+import { diffTrees, isEmptyDiff, withoutPath, type TreeView } from "./Tree.js"
 import {
   formatStepId,
   parseCommitMessage,
   type CommitMessage,
   type JudgeVerdict,
   type StepId,
+  PIN_STATES,
 } from "./Trailers.js"
 
+const UNPIN_STATE = PIN_STATES.remove
+
 export interface EpisodeCommit {
   readonly hash: string
   readonly message: string
@@ -297,7 +300,29 @@ const modeWithoutFile = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": mode requires file in ${step.kind}() options — name the steering file the mode checks`
 }
 
-export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
+// The pin is the engine's, not the process's: flow code never sees it, so a
+// pin commit is an empty diff replay can step over.
+const withoutPin = (input: ReplayInput): ReplayInput => {
+  const hide = (tree: TreeView): TreeView => withoutPath(tree, PIN_PATH)
+  return {
+    ...input,
+    episode: {
+      base: { ...input.episode.base, tree: hide(input.episode.base.tree) },
+      commits: input.episode.commits.map((c) => ({
+        ...c,
+        tree: hide(c.tree),
+        ...(c.kept !== undefined ? { kept: { ...c.kept, tree: hide(c.kept.tree) } } : {}),
+      })),
+    },
+    ...(input.startTree !== undefined ? { startTree: hide(input.startTree) } : {}),
+    ...(input.pending !== undefined
+      ? { pending: { ...input.pending, tree: hide(input.pending.tree) } }
+      : {}),
+  }
+}
+
+export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
+  const input = withoutPin(raw)
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
     parsed: parseCommitMessage(c.message),
@@ -317,6 +342,11 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   let cursor = 0
   let pendingUsed = false
   let position: Position = input.episode.base
+  // Never stands on a pin commit: `head()` names the turn, so a flow
+  // reverting it reverts the turn, not the pin.
+  const skipPins = (): void => {
+    while (cursor < commits.length && commits[cursor]!.parsed.pin !== undefined) cursor++
+  }
   let previousPosition: Position = input.episode.base
   let expectedNext: { readonly name: string; readonly hash: string } | undefined
   const occurrences = new Map<string, number>()
@@ -560,20 +590,25 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     if (unapproved !== undefined) return finish(unapproved)
     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,
-        })
-    }
+    skipPins()
+    noteKept(step, commit)
     const to = commit.parsed.parsed?.to
-    if (to !== undefined) expectedNext = { name: to, hash: commit.hash }
+    // A turn that ends a pinned process names the unpin, which is no step.
+    if (to !== undefined && to !== UNPIN_STATE) expectedNext = { name: to, hash: commit.hash }
     return replyFor(step.request, commit.parsed.judge)
   }
 
+  const noteKept = (step: ReachedStep, commit: ParsedCommit): void => {
+    if (commit.parsed.kept === undefined) return
+    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 landPending = (step: ReachedStep, pending: NonNullable<typeof input.pending>): unknown => {
     pendingUsed = true
     landed = step
@@ -587,7 +622,10 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   }
 
   const answer = (step: ReachedStep): unknown => {
-    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) cursor++
+    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) {
+      cursor++
+      skipPins()
+    }
     const commit = commits[cursor]
     if (commit !== undefined) return consumeCommit(step, commit)
     if (input.pending === undefined || pendingUsed) {
@@ -604,6 +642,9 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
 
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
+    if (Object.values(PIN_STATES).includes(scoped(request.name))) {
+      return `gtd: step "${scoped(request.name)}": the name is reserved for the pin and unpin beats — rename the step`
+    }
     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)`
     }
@@ -636,13 +677,15 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     return blocker === undefined ? answer(step) : finish(blocker)
   }
 
-  const endOfFlow = (via: "return" | "restart"): ReplayOutcome =>
-    cursor < commits.length
+  const endOfFlow = (via: "return" | "restart"): ReplayOutcome => {
+    skipPins()
+    return cursor < commits.length
       ? {
           kind: "divergence",
           message: `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode — ${DIVERGED}`,
         }
       : { kind: "ended", via, trace, landed, marks }
+  }
 
   const changesSince = (hash: string): readonly Change[] => {
     const tree = treeAt(hash)
@@ -714,13 +757,14 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     // At the rest, trailing attempts sit above the last step commit: the head a
     // prompt names is the commit the process actually stands on.
     head: () => {
-      const rest = commits.slice(cursor)
+      const rest = commits.slice(cursor).filter((c) => c.parsed.pin === undefined)
       return rest.length > 0 && rest.every((c) => c.parsed.step === undefined)
         ? rest[rest.length - 1]!.hash
         : position.hash
     },
   }
 
+  skipPins()
   installContext(context)
   try {
     // A pre-upgrade flow destructuring `{ entry }` reads `undefined` (an

package/src/replay/Trailers.test.ts

@@ -46,7 +46,7 @@ describe("the commit-message codec", () => {
       reviewBase: "abc",
     })
     expect(message).toBe(
-      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 1",
+      "gtd(human): fix-precheck\n\nGtd-Workflow: fix\nGtd-Review-Base: abc\nGtd-Format: 2",
     )
     expect(parseCommitMessage(message).workflow).toBe("fix")
     expect(parseCommitMessage("gtd(human): fix-precheck").workflow).toBeUndefined()
@@ -56,7 +56,7 @@ describe("the commit-message codec", () => {
     const one = formatCommitMessage({ actor: "human", to: "x", vars: { b: "2", a: "1", c: "" } })
     const two = formatCommitMessage({ actor: "human", to: "x", vars: { c: "", a: "1", b: "2" } })
     expect(one).toBe(two)
-    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 1")
+    expect(one).toBe("gtd(human): x\n\nGtd-Var: a=1\nGtd-Var: b=2\nGtd-Var: c=\nGtd-Format: 2")
     expect(parseCommitMessage(one).vars).toEqual({ a: "1", b: "2", c: "" })
   })
 
@@ -68,7 +68,7 @@ describe("the commit-message codec", () => {
       config: { "lib/my flow.ts": "0123456789abcdef", "gtd.config.ts": "deadbeefdeadbeef" },
     })
     expect(message).toBe(
-      "gtd(human): x\n\nGtd-Var: a=1\nGtd-Config: deadbeefdeadbeef gtd.config.ts\nGtd-Config: 0123456789abcdef lib/my flow.ts\nGtd-Format: 1",
+      "gtd(human): x\n\nGtd-Var: a=1\nGtd-Config: deadbeefdeadbeef gtd.config.ts\nGtd-Config: 0123456789abcdef lib/my flow.ts\nGtd-Format: 2",
     )
     expect(parseCommitMessage(message).config).toEqual({
       "gtd.config.ts": "deadbeefdeadbeef",
@@ -118,8 +118,8 @@ describe("the commit-message codec", () => {
   it("reads a Gtd-Version carrying control bytes as unknown, and keeps spaces and parens", () => {
     const withVersion = (value: string) =>
       formatCommitMessage({ actor: "a", to: "b" }).replace(
-        "Gtd-Format: 1",
-        `Gtd-Version: ${value}\nGtd-Format: 1`,
+        "Gtd-Format: 2",
+        `Gtd-Version: ${value}\nGtd-Format: 2`,
       )
     expect(parseCommitMessage(withVersion("1.0\u001b]0;x\u0007")).version).toBeUndefined()
     expect(parseCommitMessage(withVersion("1.0\u009b")).version).toBeUndefined()
@@ -135,15 +135,15 @@ describe("the commit-message codec", () => {
     expect(parsed.version).toBeUndefined()
   })
 
-  it("keeps Gtd-Format at 1 when branch and version are written", () => {
+  it("writes the current Gtd-Format when branch and version are written", () => {
     const message = formatCommitMessage({ actor: "a", to: "b", branch: "m", version: "1" })
-    expect(message.endsWith("Gtd-Format: 1")).toBe(true)
+    expect(message.endsWith("Gtd-Format: 2")).toBe(true)
   })
 
   it("writes Gtd-Format last on every message, even one with no other trailer", () => {
     const message = formatCommitMessage({ actor: "agent", to: "building" })
-    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 1")
-    expect(parseCommitMessage(message).format).toBe(1)
+    expect(message).toBe("gtd(agent): building\n\nGtd-Format: 2")
+    expect(parseCommitMessage(message).format).toBe(2)
   })
 
   it("reads a message without Gtd-Format as format 1, and an explicit one as written", () => {
@@ -183,10 +183,10 @@ describe("Gtd-Kept", () => {
     expect(parseCommitMessage(`gtd(agent): a → b\n\nGtd-Kept: ${hash}0`).kept).toBeUndefined()
   })
 
-  it("reads undefined when absent, and leaves Gtd-Format at 1", () => {
+  it("reads undefined when absent, and leaves Gtd-Format at the current format", () => {
     const parsed = parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" }))
     expect(parsed.kept).toBeUndefined()
-    expect(parsed.format).toBe(1)
+    expect(parsed.format).toBe(2)
   })
 })
 
@@ -326,7 +326,7 @@ describe("Gtd-Mark", () => {
     const at = lines.findIndex((l) => l.startsWith("Gtd-Mark:"))
     expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
     expect(lines[at + 1]).toMatch(/^Gtd-Approved:/)
-    expect(lines).toContain("Gtd-Format: 1")
+    expect(lines).toContain("Gtd-Format: 2")
   })
 
   it("writes nothing without marks", () => {

package/src/replay/Trailers.ts

@@ -4,6 +4,7 @@
 // command unusable.
 
 import type { Mark } from "../flows/index.js"
+import type { PinMark } from "../wire/index.js"
 import { HISTORY_FORMAT } from "./Format.js"
 
 const TRANSITION_SEP = " → "
@@ -67,6 +68,11 @@ export interface Approval {
   readonly email: string
 }
 
+export type PinChange = PinMark
+
+/** What a pin and an unpin beat rest at, and their commits name — neither is a step of the workflow. */
+export const PIN_STATES: Readonly<Record<PinChange, string>> = { add: "pin", remove: "unpin" }
+
 export interface CommitMessage {
   readonly subject: string
   readonly parsed: ParsedSubject | undefined
@@ -88,6 +94,8 @@ export interface CommitMessage {
   readonly kept: string | undefined
   /** `Gtd-Approved`; a malformed or control-character value is skipped. */
   readonly approved: Approval | undefined
+  /** `Gtd-Pin`: a commit that adds or removes the pin — never a turn. */
+  readonly pin: PinChange | undefined
   readonly format: number
 }
 
@@ -156,6 +164,7 @@ interface Trailers {
   version: string | undefined
   kept: string | undefined
   approved: Approval | undefined
+  pin: PinChange | undefined
   readonly judge: JudgeVerdict[]
   readonly marks: Mark[]
   readonly vars: Record<string, string>
@@ -206,6 +215,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Approved": (value, into) => {
     into.approved ??= decodeApproval(value)
   },
+  "Gtd-Pin": (value, into) => {
+    if (value === "add" || value === "remove") into.pin ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -226,6 +238,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     version: undefined,
     kept: undefined,
     approved: undefined,
+    pin: undefined,
     judge: [],
     marks: [],
     vars: {},
@@ -256,6 +269,7 @@ export interface CommitSpec {
   readonly marks?: readonly Mark[]
   /** Written after `Gtd-Mark`, before `Gtd-Branch`. */
   readonly approved?: Approval
+  readonly pin?: PinChange
   readonly branch?: string
   readonly version?: string
 }
@@ -264,27 +278,28 @@ const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string,
   Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
 
 /** Trailer order is fixed so the same spec always yields the same bytes. */
+const trailer = (name: string, value: string | undefined): readonly string[] =>
+  value === undefined ? [] : [`Gtd-${name}: ${value}`]
+
+const costValue = (cost: CommitSpec["cost"]): string | undefined =>
+  cost === undefined ? undefined : `${cost.cost}${cost.model !== undefined ? ` ${cost.model}` : ""}`
+
 export const formatCommitMessage = (spec: CommitSpec): string => {
-  const lines: string[] = []
-  if (spec.step !== undefined) lines.push(`Gtd-Step: ${formatStepId(spec.step)}`)
-  if (spec.workflow !== undefined) lines.push(`Gtd-Workflow: ${spec.workflow}`)
-  if (spec.reviewBase !== undefined) lines.push(`Gtd-Review-Base: ${spec.reviewBase}`)
-  for (const [name, value] of sortedEntries(spec.vars)) lines.push(`Gtd-Var: ${name}=${value}`)
-  for (const [path, hash] of sortedEntries(spec.config))
-    lines.push(`Gtd-Config: ${hash} ${encodePath(path)}`)
-  if (spec.cost !== undefined) {
-    lines.push(
-      `Gtd-Cost: ${spec.cost.cost}${spec.cost.model !== undefined ? ` ${spec.cost.model}` : ""}`,
-    )
-  }
-  for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
-  for (const m of spec.marks ?? []) lines.push(`Gtd-Mark: ${m.name}=${m.value}`)
-  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}`)
+  const lines = [
+    ...trailer("Step", spec.step && formatStepId(spec.step)),
+    ...trailer("Workflow", spec.workflow),
+    ...trailer("Review-Base", spec.reviewBase),
+    ...sortedEntries(spec.vars).map(([name, value]) => `Gtd-Var: ${name}=${value}`),
+    ...sortedEntries(spec.config).map(([path, hash]) => `Gtd-Config: ${hash} ${encodePath(path)}`),
+    ...trailer("Cost", costValue(spec.cost)),
+    ...(spec.judge ?? []).map((verdict) => `Gtd-Judge: ${JSON.stringify(verdict)}`),
+    ...(spec.marks ?? []).map((m) => `Gtd-Mark: ${m.name}=${m.value}`),
+    ...trailer("Approved", spec.approved && encodeApproval(spec.approved)),
+    ...trailer("Pin", spec.pin),
+    ...trailer("Branch", spec.branch),
+    ...trailer("Version", spec.version),
+    `Gtd-Format: ${HISTORY_FORMAT}`,
+  ]
   const subject = formatSubject(spec.actor, spec.to, spec.from)
   return `${subject}\n\n${lines.join("\n")}`
 }

package/src/replay/Tree.ts

@@ -43,3 +43,14 @@ export const diffTrees = (before: TreeView, after: TreeView): TreeDiff => {
 
 export const isEmptyDiff = (diff: TreeDiff): boolean =>
   diff.added.length === 0 && diff.modified.length === 0 && diff.deleted.length === 0
+
+export const withoutPath = (tree: TreeView, hidden: string): TreeView => {
+  let paths: readonly string[] | undefined
+  return {
+    paths: () => (paths ??= tree.paths().filter((path) => path !== hidden)),
+    read: (path) => (path === hidden ? undefined : tree.read(path)),
+    ...(tree.id !== undefined
+      ? { id: (path: string) => (path === hidden ? undefined : tree.id!(path)) }
+      : {}),
+  }
+}

package/src/replay/index.ts

@@ -12,8 +12,11 @@ export {
   formatSubject,
   isRecordableApproval,
   parseCommitMessage,
+  type CommitMessage,
   type CommitSpec,
   type JudgeVerdict,
+  type PinChange,
+  PIN_STATES,
 } from "./Trailers.js"
 export { accessShapeFault } from "./Access.js"
 export { formatFault } from "./Format.js"

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: "commitPath"; readonly path: string; 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/RepoSnapshot.ts

@@ -19,6 +19,8 @@ export type Landing =
       readonly keepHistory?: string
       /** The kept ref this landing's turn goes to; the branch gets a marker commit instead. */
       readonly keepTurn?: string
+      /** The one path this landing commits; every other pending change stays pending. */
+      readonly only?: string
     }
 
 /**

package/src/step/planStart.test.ts

@@ -177,7 +177,7 @@ describe("planStart", () => {
         kind: "gitWrite",
         write: {
           kind: "commitAll",
-          message: "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=\nGtd-Format: 1",
+          message: "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=\nGtd-Format: 2",
         },
       },
       { kind: "outcome", outcome: { kind: "commit", subject: "gtd(human): work" } },
@@ -196,7 +196,7 @@ describe("planStart", () => {
     if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
       throw new Error("expected a gitWrite step")
     expect(write.write.message).toBe(
-      "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 1",
+      "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 2",
     )
     const outcome = plan.steps.find((s) => s.kind === "outcome")
     expect(outcome).toEqual({

package/src/step/planStart.ts

@@ -158,11 +158,11 @@ const resolveBase = (
     const git = yield* GitService
     const rendered = value.trim()
     const target = rendered === "" ? yield* git.defaultBranch() : rendered
-    const resolvedBase = yield* Effect.either(git.resolveRef(target))
-    if (resolvedBase._tag === "Left") {
+    const resolvedBase = yield* Effect.result(git.resolveRef(target))
+    if (resolvedBase._tag === "Failure") {
       return refusal(`${commandLabel}: "${target}" does not resolve to a commit`)
     }
-    const mergeBase = yield* git.mergeBase(resolvedBase.right, "HEAD")
+    const mergeBase = yield* git.mergeBase(resolvedBase.success, "HEAD")
     if (Option.isNone(mergeBase)) {
       return refusal(`${commandLabel}: "${target}" shares no common ancestor with HEAD`)
     }

package/src/step/planStep.test.ts

@@ -39,7 +39,7 @@ describe("planStep — commit", () => {
     expect(outcome.steps).toEqual([
       {
         kind: "gitWrite",
-        write: { kind: "commitAll", message: "gtd(agent): await-answers\n\nGtd-Format: 1" },
+        write: { kind: "commitAll", message: "gtd(agent): await-answers\n\nGtd-Format: 2" },
       },
       { kind: "outcome", outcome: { kind: "commit", subject: "gtd(agent): await-answers" } },
     ])
@@ -59,7 +59,7 @@ describe("planStep — commit", () => {
       kind: "gitWrite",
       write: {
         kind: "commitAll",
-        message: "gtd(human): building → done\n\nGtd-Step: building#1\nGtd-Format: 1",
+        message: "gtd(human): building → done\n\nGtd-Step: building#1\nGtd-Format: 2",
       },
     })
     expect(outcome.steps.at(-1)).toEqual({
@@ -99,7 +99,7 @@ describe("planStep — commit", () => {
     expect(trailers[1]).toBe("Gtd-Cost: 1.5 m")
     expect(trailers[2]).toBe('Gtd-Judge: {"id":"q1","answer":true,"p":0.9}')
     expect(trailers[3]).toBe('Gtd-Judge: {"id":"q2","answer":"x","p":0.4}')
-    expect(trailers[4]).toBe("Gtd-Format: 1")
+    expect(trailers[4]).toBe("Gtd-Format: 2")
     expect(trailers).toHaveLength(5)
   })
 })
@@ -182,7 +182,7 @@ describe("planStep — keepTurn", () => {
       write: {
         kind: "keepTurn",
         ref: kept,
-        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 1",
+        message: "gtd(agent): building → checking\n\nGtd-Step: building#1\nGtd-Format: 2",
       },
     })
   })

package/src/step/planStep.ts

@@ -1,7 +1,7 @@
 import { formatCommitMessage, type JudgeVerdict } from "../replay/index.js"
 import type { StateName } from "../workflow/index.js"
-import type { LandStep } from "./LandStep.js"
-import type { RepoSnapshot } from "./RepoSnapshot.js"
+import type { GitWrite, LandStep } from "./LandStep.js"
+import type { Landing, RepoSnapshot } from "./RepoSnapshot.js"
 
 export type { JudgeVerdict }
 
@@ -35,6 +35,13 @@ const uncheckStep = (snapshot: RepoSnapshot): readonly LandStep[] =>
     ? [{ kind: "uncheck", file: snapshot.file }]
     : []
 
+const gitWriteOf = (landing: Extract<Landing, { kind: "commit" }>, message: string): GitWrite => {
+  if (landing.only !== undefined) return { kind: "commitPath", path: landing.only, message }
+  if (landing.keepTurn !== undefined) return { kind: "keepTurn", ref: landing.keepTurn, message }
+  if (landing.spec.approved !== undefined) return { kind: "commitClean", message }
+  return { kind: "commitAll", message }
+}
+
 export const planStep = (
   snapshot: RepoSnapshot,
   opts: {
@@ -84,12 +91,7 @@ export const planStep = (
       ...uncheckStep(snapshot),
       {
         kind: "gitWrite",
-        write:
-          landing.keepTurn !== undefined
-            ? { kind: "keepTurn", ref: landing.keepTurn, message }
-            : landing.spec.approved !== undefined
-              ? { kind: "commitClean", message }
-              : { kind: "commitAll", message },
+        write: gitWriteOf(landing, message),
       },
       ...(landing.keepHistory !== undefined
         ? [