@pmelab/gtd 60.1.0 → 61.0.0

package/src/edge/Edge.ts

@@ -37,18 +37,23 @@ import {
   isRecordableApproval,
   parseCommitMessage,
   replay,
+  type CommitMessage,
   scopeRunStart,
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
+  type PinChange,
+  PIN_STATES,
   type ReachedStep,
   type ReplayOutcome,
   type TreeView,
 } from "../replay/index.js"
 import type { Mark, ScopeAccess, SummaryContext } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
+import { pinScript, unpinScript } from "../emit/index.js"
 import {
   judgeJson,
+  PIN_PATH,
   UNATTRIBUTED_MODEL,
   type ApprovalEntry,
   type ModelCost,
@@ -87,6 +92,16 @@ interface EpisodeLocation {
   readonly processStart: number
 }
 
+const isOpening = ({ parsed, step }: CommitMessage): boolean =>
+  parsed !== undefined &&
+  step === undefined &&
+  parsed.from === undefined &&
+  parsed.actor === "human"
+
+// A pin commit's subject may name the first step; it bounds nothing.
+const boundsEpisode = (def: WorkflowDefinition, { parsed, pin }: CommitMessage): boolean =>
+  pin !== "add" && (parsed === undefined || !ACTORS.has(parsed.actor) || parsed.to === def.initial)
+
 /**
  * Where the episode HEAD belongs to begins, read off subjects alone. Walking
  * back from HEAD: a bare `gtd(human): <step>` commit with no `Gtd-Step` is what
@@ -99,13 +114,7 @@ interface EpisodeLocation {
 const locateEpisode = (def: WorkflowDefinition, history: History): EpisodeLocation => {
   for (let i = history.length - 1; i >= 0; i--) {
     const message = parseCommitMessage(history[i]!.message)
-    const subject = message.parsed
-    const opening =
-      subject !== undefined &&
-      message.step === undefined &&
-      subject.from === undefined &&
-      subject.actor === "human"
-    if (opening) {
+    if (isOpening(message)) {
       return {
         workflow: message.workflow,
         legacyOpening: message.workflow === undefined,
@@ -113,7 +122,7 @@ const locateEpisode = (def: WorkflowDefinition, history: History): EpisodeLocati
         processStart: i,
       }
     }
-    if (subject === undefined || !ACTORS.has(subject.actor) || subject.to === def.initial) {
+    if (boundsEpisode(def, message)) {
       return { workflow: undefined, legacyOpening: false, baseIndex: i, processStart: i + 1 }
     }
   }
@@ -156,6 +165,8 @@ export interface ProcessRun {
   readonly trace: readonly TraceEntry[]
   readonly costEntries: readonly CostEntry[]
   readonly judgeVerdicts: readonly JudgeVerdictEntry[]
+  /** Whether a pin commit has landed in this process. */
+  readonly pinCommitted: boolean
   /** Every process commit's `Gtd-Mark`s, oldest first. */
   readonly marks: readonly Mark[]
   /** Oldest first. */
@@ -186,7 +197,8 @@ const headTurnOf = (head: History[number] | undefined): ProcessRun["headTurn"] =
   if (head === undefined) return undefined
   const message = parseCommitMessage(head.message)
   const subject = message.parsed
-  if (subject === undefined || !ACTORS.has(subject.actor)) return undefined
+  if (subject === undefined || !ACTORS.has(subject.actor) || message.pin !== undefined)
+    return undefined
   return {
     state: subject.to,
     actor: subject.actor,
@@ -267,8 +279,11 @@ const buildRun = (
   location: EpisodeLocation,
   closingHash: string | undefined,
 ): ProcessRun => {
-  const processCommits = history.slice(location.processStart)
-  const parsed = processCommits.map((c) => parseCommitMessage(c.message))
+  const allProcessCommits = history.slice(location.processStart)
+  const allParsed = allProcessCommits.map((c) => parseCommitMessage(c.message))
+  // A pin commit is no turn; the unpin commit stays, as the one that closes the process.
+  const processCommits = allProcessCommits.filter((_, i) => allParsed[i]!.pin !== "add")
+  const parsed = allParsed.filter((m) => m.pin !== "add")
   const first = parsed[0]
   const startParentHash = hashAt(history, location.processStart - 1) ?? EMPTY_TREE
   const head = history[history.length - 1]
@@ -281,6 +296,7 @@ const buildRun = (
     trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i]!)),
     costEntries: parsed.flatMap((m, i) => costEntriesOf(processCommits[i]!.hash, m)),
     judgeVerdicts: parsed.flatMap((m) => m.judge),
+    pinCommitted: allParsed.some((m) => m.pin === "add"),
     marks: parsed.flatMap((m) => m.marks),
     approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i]!)),
     pinnedVars: { ...first?.vars },
@@ -320,6 +336,8 @@ const subjectIsBoundary = (def: WorkflowDefinition, subject: string): boolean =>
   const parsed = parseCommitMessage(subject).parsed
   if (parsed === undefined || !ACTORS.has(parsed.actor)) return true
   if (parsed.actor === "human" && parsed.from === undefined) return false
+  // A pin commit's subject can name the first step; it bounds nothing.
+  if (parsed.actor === "check" && parsed.from === PIN_STATES.add) return false
   return parsed.to === def.initial
 }
 
@@ -849,6 +867,10 @@ interface ResolvedRest {
  * before any mutation.
  */
 interface Rest extends ResolvedRest {
+  /** Set at a pin or unpin beat; `step` is then the step the flow reached around it. */
+  readonly pin: PinChange | undefined
+  /** Whether HEAD's tree carries the pin. */
+  readonly pinned: boolean
   readonly step: ReachedStep
   readonly trace: readonly ReachedStep[]
   readonly run: ProcessRun
@@ -985,13 +1007,15 @@ export const restAt = (
     // staying true; passing a pending tree here would make it serve a stale
     // steering file on every cache hit.
     const outcome = yield* Effect.promise(() => replayFor(setup))
-    const error = replayError(outcome)
-    if (error !== undefined || outcome.kind !== "rest") {
-      return yield* Effect.fail(error ?? new Error("gtd: replay found no rest"))
+    const pinned = headHasPin(workspace, run)
+    const pin = pinBeatAt(outcome, run, def, pinned)
+    const resting = restingOn(outcome, pin)
+    if (resting === undefined) {
+      return yield* Effect.fail(replayError(outcome) ?? new Error("gtd: replay found no rest"))
     }
-    const step = outcome.rest
-    yield* (yield* Narrator).narrate(`rest resolved: ${step.name} (awaits ${step.actor})`)
-    const stepDef = stepDefOf(step)
+    const { reached, step } = resting
+    const { stepDef, state, memory } = restFacts(pin, step, reached.trace, run)
+    yield* (yield* Narrator).narrate(`rest resolved: ${state} (awaits ${stepDef.actor})`)
     if (stepDef.mode !== undefined && def.modes[stepDef.mode] === undefined) {
       return yield* Effect.fail(
         new Error(
@@ -1006,7 +1030,6 @@ export const restAt = (
             path: e.path,
           }))
         : []
-    const memory = memoryOf(outcome.trace, run)
     const configNow = config.fingerprint
     // Only the current rest warns, so a command must read it once — a second
     // read warns twice. An earlier ref (restore's tip) would warn about a
@@ -1015,11 +1038,13 @@ export const restAt = (
     return {
       def,
       workflowName: resolved.name,
-      state: step.name,
+      state,
       stepDef,
-      actor: step.actor,
+      actor: stepDef.actor,
+      pin,
+      pinned,
       step,
-      trace: outcome.trace,
+      trace: reached.trace,
       run,
       vars,
       env,
@@ -1035,6 +1060,66 @@ export const restAt = (
 
 export const currentRest: Effect.Effect<Rest, Error, RestRequirements> = restAt(undefined)
 
+/** The step the process rests at and the trace that reached it — at an unpin, the flow's last step. */
+const restingOn = (outcome: ReplayOutcome, pin: PinChange | undefined) => {
+  if (outcome.kind === "rest") return { reached: outcome, step: outcome.rest }
+  if (outcome.kind !== "ended" || pin !== "remove") return undefined
+  const step = outcome.trace.at(-1)
+  return step === undefined ? undefined : { reached: outcome, step }
+}
+
+/** A pin or unpin beat has its own script, no step's, and no agent memory. */
+const restFacts = (
+  pin: PinChange | undefined,
+  step: ReachedStep,
+  trace: readonly ReachedStep[],
+  run: ProcessRun,
+) =>
+  pin === undefined
+    ? { stepDef: stepDefOf(step), state: step.name, memory: memoryOf(trace, run) }
+    : {
+        stepDef: pinStepDef(pin),
+        state: PIN_STATES[pin],
+        memory: { key: undefined, resumed: false },
+      }
+
+const headHasPin = (workspace: WorkspaceOps, run: ProcessRun): boolean => {
+  const head = run.episode.commits.at(-1)?.hash ?? run.episode.base
+  return head !== undefined && workspace.treeSync(head).has(PIN_PATH)
+}
+
+const underwayAt = (run: ProcessRun, step: ReachedStep, def: WorkflowDefinition): boolean =>
+  run.workflow !== undefined || step.name !== def.initial || step.id.occurrence !== 1
+
+/**
+ * A started process pins first — again, should a turn have deleted the pin;
+ * a pinned flow that ended unpins before the closing commit.
+ */
+const pinBeatAt = (
+  outcome: ReplayOutcome,
+  run: ProcessRun,
+  def: WorkflowDefinition,
+  pinned: boolean,
+): PinChange | undefined => {
+  if (flowEnded(outcome, run, def)) return pinned || run.pinCommitted ? "remove" : undefined
+  if (outcome.kind !== "rest" || pinned) return undefined
+  return underwayAt(run, outcome.rest, def) ? "add" : undefined
+}
+
+// A default-workflow process back at the first step has ended, as a returned flow has.
+const flowEnded = (outcome: ReplayOutcome, run: ProcessRun, def: WorkflowDefinition): boolean =>
+  outcome.kind === "ended" ||
+  (outcome.kind === "rest" &&
+    run.workflow === undefined &&
+    outcome.rest.name === def.initial &&
+    underwayAt(run, outcome.rest, def))
+
+const pinStepDef = (pin: PinChange): StepDef => ({
+  actor: "check",
+  kind: "script",
+  content: pin === "add" ? pinScript(PIN_PATH) : unpinScript(PIN_PATH),
+})
+
 type EndedOutcome = Extract<ReplayOutcome, { kind: "ended" }>
 type UnendedOutcome = Exclude<ReplayOutcome, { kind: "ended" }>
 
@@ -1094,6 +1179,7 @@ export interface RenderedRest extends RestHints {
   readonly content: string
   readonly memory?: string
   readonly memoryResumed: boolean
+  readonly pin?: PinChange
 }
 
 export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
@@ -1105,6 +1191,7 @@ export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
     ...rest.hints,
     ...(rest.memory !== undefined ? { memory: rest.memory } : {}),
     memoryResumed: rest.memoryResumed,
+    ...(rest.pin !== undefined ? { pin: rest.pin } : {}),
   })
 
 /**
@@ -1122,9 +1209,7 @@ export const stalledAt = (rest: Rest): boolean =>
 
 /** No process is underway: the default workflow's first step, first visit — a dirty tree there is a turn not yet landed, not a process. */
 export const noProcessUnderway = (rest: Rest): boolean =>
-  rest.run.workflow === undefined &&
-  rest.state === rest.def.initial &&
-  rest.step.id.occurrence === 1
+  rest.pin === undefined && !underwayAt(rest.run, rest.step, rest.def)
 
 /** `idle` means exactly one thing: no process underway, clean tree. */
 export const restIsIdle = (rest: Rest): boolean =>
@@ -1254,15 +1339,15 @@ const landingTo = (
   if (refused !== undefined) return refused
   // Landing on the first step while a process is underway ends it (flow
   // return and `restart()` alike); the script then points the history ref at
-  // that very commit.
-  const finishes = underway && to === rest.def.initial
+  // that very commit. A pinned process ends one beat later, at the unpin.
+  const { finishes, landsAt } = endingOf(rest, to, underway)
   return {
     kind: "commit",
-    to,
+    to: landsAt,
     spec: {
       actor: rest.actor,
       from: rest.state,
-      to,
+      to: landsAt,
       step: rest.step.id,
       ...(marks.length > 0 && { marks }),
       ...approvedTrailer(rest, approver),
@@ -1274,6 +1359,53 @@ const landingTo = (
   }
 }
 
+const endingOf = (rest: Rest, to: StateName, underway: boolean) => {
+  const ends = underway && to === rest.def.initial
+  return { finishes: ends && !rest.pinned, landsAt: ends && rest.pinned ? PIN_STATES.remove : to }
+}
+
+/** A pin or unpin commit carries the pin alone; the unpin commit closes the process. */
+const pinLanding = (rest: Rest, pin: PinChange, branch: Option.Option<string>): Landing => {
+  const change = rest.changes.find((c) => c.path === PIN_PATH)?.status
+  return pin === "add" ? pinCommit(rest, change) : unpinCommit(rest, change, branch)
+}
+
+const pinCommit = (rest: Rest, change: string | undefined): Landing => {
+  if (change === undefined || change === "D") return pinRefusal("add")
+  const to = rest.step.name
+  return {
+    kind: "commit",
+    to,
+    spec: { actor: rest.actor, from: rest.state, to, pin: "add" },
+    only: PIN_PATH,
+  }
+}
+
+const unpinCommit = (
+  rest: Rest,
+  change: string | undefined,
+  branch: Option.Option<string>,
+): Landing => {
+  if (change !== "D" && rest.pinned) return pinRefusal("remove")
+  const to = rest.def.initial
+  return {
+    kind: "commit",
+    to,
+    spec: { actor: rest.actor, from: rest.state, to, pin: "remove", ...closingTrailers(branch) },
+    keepHistory: processHistoryRef(rest.run.startHash),
+    // A turn already deleted the pin: the closing commit has no path of its own.
+    ...(rest.pinned ? { only: PIN_PATH } : {}),
+  }
+}
+
+const pinRefusal = (pin: PinChange): Landing => ({
+  kind: "refusal",
+  message:
+    pin === "add"
+      ? `gtd land: ${PIN_PATH} is missing — run the pin beat's script (\`gtd next --json=content\`); if its \`gtd bundle\` fails, fix what it reports, or run \`gtd abandon\``
+      : `gtd land: ${PIN_PATH} is still there — run the unpin beat's script (\`gtd next --json=content\`), then land`,
+})
+
 const startTrailers = (rest: Rest, starts: boolean) =>
   starts ? { vars: rest.vars, config: rest.config } : {}
 
@@ -1292,6 +1424,7 @@ const decideLanding = (
   approver: Option.Option<AuthorIdent>,
 ): Effect.Effect<Landing, Error> =>
   Effect.gen(function* () {
+    if (rest.pin !== undefined) return pinLanding(rest, rest.pin, branch)
     const unapproved = approvalRefusal(rest, approver)
     if (unapproved !== undefined) return unapproved
     const early = cleanLanding(rest)

package/src/emit/GitScript.ts

@@ -12,12 +12,13 @@ export const pathspec = (paths: ReadonlyArray<string>): string => paths.map(shel
  * output rather than the exit code, so a genuinely rejected commit (a lint
  * error, a commit-msg hook) still fails.
  */
-const commitAllowEmpty = (message: string): string => {
+const commitAllowEmpty = (message: string, only?: string): string => {
   const m = shellQuote(message)
+  const paths = only === undefined ? "" : ` -- ${shellQuote(only)}`
   return [
-    `if ! out=$(git commit --allow-empty -m ${m} 2>&1); then`,
+    `if ! out=$(git commit --allow-empty -m ${m}${paths} 2>&1); then`,
     `  case "$out" in`,
-    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} || exit 1 ;;`,
+    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m}${paths} || exit 1 ;;`,
     `    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
     `  esac`,
     `fi`,
@@ -31,6 +32,21 @@ export const CHANGED_SINCE_LAND =
 export const commitAll = (message: string): string =>
   `git add -A || exit 1\n${commitAllowEmpty(message)}`
 
+/** Commits `path` alone, as the worktree has it; every other pending change stays pending. */
+export const commitPath = (path: string, message: string): string =>
+  `git add -A -- ${shellQuote(path)} || exit 1\n${commitAllowEmpty(message, path)}`
+
+/** A pin beat's script. A failed `gtd bundle` leaves no half-written pin behind. */
+export const pinScript = (path: string): string => {
+  const p = shellQuote(path)
+  const slash = path.lastIndexOf("/")
+  const mkdir = slash === -1 ? "" : `mkdir -p ${shellQuote(path.slice(0, slash))}\n`
+  return `${mkdir}gtd bundle >${p} || { rm -f -- ${p}; exit 1; }`
+}
+
+/** An unpin beat's script, and `gtd abandon`'s removal of the pin. */
+export const unpinScript = (path: string): string => `rm -f -- ${shellQuote(path)}`
+
 /**
  * An approval records exactly the judged tree: HEAD is pinned before the
  * clean check and the commit is built over its tree with `commit-tree`, so no
@@ -151,6 +167,8 @@ const renderGitWrite = (write: GitWrite): string => {
   switch (write.kind) {
     case "commitAll":
       return commitAll(write.message)
+    case "commitPath":
+      return commitPath(write.path, write.message)
     case "commitClean":
       return commitClean(write.message)
     case "updateRef":

package/src/emit/index.ts

@@ -16,6 +16,9 @@ export {
   commitAll,
   commitAsIs,
   commitClean,
+  commitPath,
+  pinScript,
+  unpinScript,
   CHANGED_SINCE_LAND,
   softResetTo,
   mixedResetTo,

package/src/gherkin/messages.test.ts

@@ -45,6 +45,7 @@ describe("restDescription", () => {
         "  last commits:",
         "    chore: initial commit",
         "    gtd(agent): plan → sign-off",
+        "    gtd(check): pin → sign-off",
         '  actors never used: "repair" (scenario), "ready" (Background)',
       ].join("\n"),
     )

package/src/gherkin/module-config.feature

@@ -20,5 +20,6 @@ Feature: a scenario runs a workflow module from disk
     And the commit subjects end with:
       """
       gtd(agent): plan → sign-off
+      gtd(check): pin → sign-off
       """
 

package/src/gherkin/more-steps.feature

@@ -23,6 +23,7 @@ Feature: steps for checks, stalls, beat fields, commit bodies and the environmen
 
   Scenario: the resting step's fields are read by name
     When gtd starts workflow "tested"
+    And the process is driven
     Then the process rests at "build.plan"
     And the resting step's model is "smart"
     And the resting step's idle is "false"

package/src/gherkin/testkit.feature

@@ -43,6 +43,7 @@ Feature: testkit drives any workflow against the real engine
     And the commit subjects end with:
       """
       gtd(human): plan
+      gtd(check): pin → plan
       gtd(agent): plan → check
       gtd(check): check → ready
       gtd(judge): ready → ship
@@ -106,7 +107,7 @@ Feature: testkit drives any workflow against the real engine
     When gtd starts workflow "tiny"
     And the process is driven
     Then the process rests at "plan"
-    And the last commit subject is "gtd(human): plan"
+    And the last commit subject is "gtd(check): pin → plan"
 
   Scenario: a prompt asserted beside a script is checked at every visit, before the step acts
     Given step "check" is prompted with "npm test"

package/src/install/Install.ts

@@ -240,7 +240,13 @@ The \`kind\` field (\`--json=kind\`) selects what to do:
   Land it immediately, no display needed.
 - \`script\` — run \`--json=content\` with \`sh -c\`, appending its output to
   \`--json=log\`, and ignore its exit code — the outcome lives in the tree,
-  not in the exit code.
+  not in the exit code. Two script beats carry a \`pin\` mark: the **pin
+  beat** right after a process starts (\`pin: "add"\`, its script writes
+  \`gtd bundle\`'s output to \`.gtd/process.gtdpin\`) and the **unpin beat**
+  once the flow has ended (\`pin: "remove"\`, its script deletes that file).
+  Both run unattended, like any script beat. A driver may write or delete the
+  file its own way instead of running the script; either way it then lands,
+  and the unpin's landing is the commit that closes the process.
 - \`prompt\` — send plain \`gtd next\`'s own output to your agent CLI over
   stdin (it's the bare content at this kind, so no separate \`--json=content\`
   read is needed), using the accompanying \`session.id\`/\`session.resume\`/
@@ -284,7 +290,8 @@ skills, \`skills\` (an array of the skill names, already trimmed and split —
 \`label\`, \`file\`, \`mode\`, \`edges\`, \`judge\` (the pending judgment's rendered
 document). When a cost has been recorded (a prior \`gtd land --cost=<n>\`):
 \`cost\`, \`costByModel\`. Always \`approvals\` (an array of
-\`{step, name, email, commit}\`, \`[]\` when none).
+\`{step, name, email, commit}\`, \`[]\` when none). Only at a pin or unpin
+beat: \`pin\` (\`"add"\` or \`"remove"\`).
 
 \`gtd land\` fields, in fixed order: \`schema\`, \`script\` (the POSIX sh to run), \`settled\`
 (true for a no-op at a \`script\` rest — stop immediately, nothing more to

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")
+  })
+})