@pmelab/gtd 60.1.0 → 61.0.0

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

package/src/testkit/TestRepo.test.ts

@@ -61,10 +61,12 @@ describe("testRepo", () => {
     expect(repo.subjects()).toEqual([
       "chore: initial commit",
       "gtd(agent): plan → build",
+      "gtd(check): pin → build",
       "gtd(agent): build → check",
       "gtd(check): check → sign-off",
     ])
     expect(repo.read("src/add.ts")).toContain("a + b")
+    expect(repo.read(".gtd/process.gtdpin")).toBeDefined()
   })
 
   it("runs a workflow given as gtd.config.ts source", async () => {
@@ -550,7 +552,8 @@ describe("testRepo", () => {
         trailers: { Refs: ["#1", "#2"] },
       })
       await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
-      expect(repo.commits().at(-1)!.trailers["Gtd-Step"]).toEqual(["plan#1"])
+      expect(repo.commits().at(-2)!.trailers["Gtd-Step"]).toEqual(["plan#1"])
+      expect(repo.commits().at(-1)!.trailers["Gtd-Pin"]).toEqual(["add"])
     })
 
     const greeter = {

package/src/testkit/TestRepo.ts

@@ -353,13 +353,15 @@ const expectedVerdict = (doc: BeatDocument): string => {
 
 const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(", ")
 
-/** Who acts at `doc`: its scripted actor, or a check's own script under `checks: "run"`. A stall has none. */
+/** Who acts at `doc`: its scripted actor, or its own script at a pin beat or a check under `checks: "run"`. A stall has none. */
 const actorAt = (
   doc: BeatDocument,
   actors: Actors,
   checks: DriveOptions["checks"],
 ): { readonly scripted: boolean; readonly actor: ScriptedActor | undefined } => {
   if (doc.kind === "stalled") return { scripted: false, actor: undefined }
+  // A drive is a driver: pinning is its own business, not a step to script.
+  if (doc.pin !== undefined) return { scripted: false, actor: runsItsScript }
   if (Object.hasOwn(actors, doc.state)) return { scripted: true, actor: actors[doc.state] }
   const runs = checks === "run" && doc.actor === "check"
   return { scripted: false, actor: runs ? runsItsScript : undefined }

package/src/twins/EmittedScriptRecognizer.ts

@@ -7,6 +7,7 @@ import {
   commitAll,
   commitAsIs,
   commitClean,
+  commitPath,
   deleteRef,
   discardPending,
   hardResetTo,
@@ -24,6 +25,8 @@ import {
   contradictionMessage,
   modeContradictionSkipNotice,
   OUTCOME_MARKER,
+  pinScript,
+  unpinScript,
 } from "../emit/index.js"
 import {
   BUILT_IN_MODE_NAMES,
@@ -32,7 +35,7 @@ import {
   type SteeringFormat,
 } from "../steering/internal.js"
 import { refNameFault } from "../replay/index.js"
-import { renderFormat } from "../wire/index.js"
+import { PIN_PATH, renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
 import type { CommandTable } from "./Layers.js"
@@ -174,6 +177,17 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
 
   if (block.startsWith("git add -A || exit 1\ngtd_sign_cfg=")) return recognizeKeepTurn(repo, block)
 
+  if (block.startsWith("git add -A -- ")) {
+    const [path, message] = extractQuotedTokens(block)
+    if (path === undefined || message === undefined || commitPath(path, message) !== block) {
+      return undefined
+    }
+    const failure = repo.commitPath(path, message)
+    return failure === undefined
+      ? { kind: "applied" }
+      : { kind: "failed", error: failure, status: 1 }
+  }
+
   if (block.startsWith("git add -A || exit 1\n")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAll(message) === block) {
@@ -255,6 +269,22 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   return undefined
 }
 
+/** What the in-memory `gtd bundle` prints: a pin header, and no engine behind it. */
+const IN_MEMORY_PIN = "gtdpin 1 gtd in-memory\n"
+
+/** A pin or unpin beat's script. */
+const recognizePinScripts = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
+  if (block === pinScript(PIN_PATH)) {
+    repo.writeFile(PIN_PATH, IN_MEMORY_PIN)
+    return { kind: "applied" }
+  }
+  if (block === unpinScript(PIN_PATH)) {
+    if (repo.readFile(PIN_PATH) !== undefined) repo.deleteFile(PIN_PATH)
+    return { kind: "applied" }
+  }
+  return undefined
+}
+
 /** The REAL `fileExistsGuard` block, re-derived from the extracted path and string-compared. The one recognizer that can report `{ kind: "stopped" }`: a real `exit 0` there ends the script successfully. */
 const recognizeFileExistsGuard = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   const [file] = extractQuotedTokens(block)
@@ -694,6 +724,7 @@ const recognizersFor = (
   (block) => recognizeBinaryGuard(commands, block),
   (block) => (git ? recognizeGitBuilders(repo, block) : undefined),
   (block) => recognizeWriteLines(repo, block),
+  (block) => recognizePinScripts(repo, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
   (block) => recognizePresentationSubshell(repo, commands, block, git),
   (block) => recognizeModeContradictionSkipNotice(block),

package/src/twins/GitTiers.ts

@@ -21,6 +21,8 @@ import { Effect, Exit, Option } from "effect"
 import { Narrator, GitService, Host, type GitOperations, NodeServices } from "../platform/index.js"
 import {
   commitAll,
+  commitPath,
+  unpinScript,
   commitAsIs,
   commitClean,
   softResetTo,
@@ -1356,6 +1358,27 @@ export const runGitScriptContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("commitPath", () => {
+    it("commits the one path; every other pending change stays pending", () => {
+      t.seed.writeFile(".gtd/process.gtdpin", "pin")
+      t.seed.writeFile("other.ts", "export const y = 1")
+      run(t, commitPath(".gtd/process.gtdpin", "gtd(check): pin → building"))
+      expect(t.observe.headSubject()).toBe("gtd(check): pin → building")
+      expect(t.observe.headTouchedPaths()).toEqual([".gtd/process.gtdpin"])
+      expect(t.observe.statusPorcelain()).toContain("other.ts")
+      expect(t.observe.statusPorcelain()).not.toContain("process.gtdpin")
+    })
+
+    it("commits the path's deletion", () => {
+      t.seed.commit("feat: pinned", { ".gtd/process.gtdpin": "pin" })
+      run(t, unpinScript(".gtd/process.gtdpin"))
+      run(t, commitPath(".gtd/process.gtdpin", "gtd(check): unpin → idle"))
+      expect(t.observe.headTouchedPaths()).toEqual([".gtd/process.gtdpin"])
+      expect(t.observe.existsPath(".gtd/process.gtdpin")).toBe(false)
+      expect(t.observe.statusPorcelain().trim()).toBe("")
+    })
+  })
+
   describe("commitClean", () => {
     it("on a clean tree commits an empty commit with the message", () => {
       const headBefore = t.observe.resolveRef("HEAD")

package/src/twins/InMemRepo.ts

@@ -474,6 +474,20 @@ export class InMemRepo {
     this.resetHard()
   }
 
+  /** Twin of `GitScript.commitPath`: commits `path` as the worktree has it, every other staged change left staged. */
+  commitPath(path: string, message: string): string | undefined {
+    if (!this.worktree.has(path) && !this.headTree().has(path) && !this.index.has(path)) {
+      return `error: pathspec '${path}' did not match any file(s) known to git`
+    }
+    const staged = new Map(this.index)
+    this.index = new Map(this.headTree())
+    this.stage(path)
+    const failure = this.commitAsIs(message)
+    this.index = staged
+    this.stage(path)
+    return failure
+  }
+
   commitAllWithPrefix(prefix: string): string | undefined {
     this.index = new Map(this.worktree)
     return this.commitAsIs(prefix)