@pmelab/gtd 62.1.0 → 63.0.0

package/dist/testkit/gherkin.mjs

@@ -1,4 +1,4 @@
-import { n as runsItsScript, r as testRepo } from "../chunks/testkit-CPzWnl3P.mjs";
+import { n as runsItsScript, r as testRepo } from "../chunks/testkit-DwypA7cH.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { After, AfterAll, Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";

package/dist/testkit.mjs

@@ -1,3 +1,3 @@
 import { H as installContext } from "./chunks/flows-DENt0uWV.mjs";
-import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-CPzWnl3P.mjs";
+import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-DwypA7cH.mjs";
 export { inTurn, installContext, runsItsScript, testRepo, verdict, verdictWhen, whenPrompted };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "62.1.0",
+  "version": "63.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/cli/Cli.ts

@@ -455,7 +455,7 @@ With no <name>, list every workflow and door it can start. An unknown <name>, th
     arity: "none",
     group: "Start and stop",
     summary: "Pin the process to the live gtd and workflow",
-    details: `Switch the process underway to the live engine and workflow, the way out when the workflow needs a fix mid-process: the printed script runs the pin beat again, writing \`gtd bundle\`'s output to .gtd/process.gtdpin and committing that file alone. Always runs on the gtd on PATH, never on the pin. Refuses when no process is underway, when the next beat is a pin or unpin beat already, or when the live workflow does not replay the process.
+    details: `Switch the process underway to the live engine and workflow, the way out when the workflow needs a fix mid-process: the printed script runs the pin beat again, writing \`gtd bundle\`'s output to .gtd/process.gtdpin and committing that file alone. Always runs on the gtd on PATH, never on the pin. When the live workflow no longer replays the process, the commit continues from the divergence: a Gtd-Anchor trailer names the last commit it replays, the later commits stay as files only, and the process rests at the step the live workflow reached there. Refuses when no process is underway, when the next beat is a pin or unpin beat already, when an unpinned process diverges, or when the live workflow would continue at the default workflow's first step.
 
   s=$(gtd repin --json=script) && sh -c "$s"`,
   },

package/src/cli/Program.test.ts

@@ -110,7 +110,7 @@ export const hotfix = workflow(
     expect(exitCode).toBe(0)
     expect(stdout).toContain(
       commitAll(
-        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Format: 2`,
+        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Format: 3`,
       ),
     )
     expect(repo.commitHistory()).toHaveLength(before)
@@ -791,14 +791,14 @@ describe("gtd next — refuses when history diverges from what replay reaches",
 
 describe("a history written in a format this gtd does not read", () => {
   // The exact wording is pinned in Format.test.ts; this is the part that proves the format gate fired.
-  const FOREIGN = "is written in history format 3, but this gtd reads formats 1 to 2"
+  const FOREIGN = "is written in history format 4, but this gtd reads formats 1 to 3"
 
   /** A step commit that would also diverge, so only the format gate can explain the refusal. */
   const foreignStep = async (): Promise<InMemRepo> => {
     const repo = seed(IDLE_THEN_WORKING)
     await landTurn(repo, { "NOTE.md": "a note\n" })
     repo.writeFile("WORK.md", "done\n")
-    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 3")
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 4")
     return repo
   }
 
@@ -823,7 +823,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("refuses even when a foreign subject hides the commit from the episode", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 3")
+    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 4")
     for (const command of ["next", "abandon"]) {
       const { exitCode, stderr } = await run(repo, command)
       expect(exitCode).toBe(1)
@@ -834,7 +834,7 @@ describe("a history written in a format this gtd does not read", () => {
   it("a commit gtd never wrote is not read for a format, even quoting the trailer", async () => {
     const repo = seed(IDLE_THEN_WORKING)
     repo.writeFile("NOTE.md", "a note\n")
-    repo.seedCommit("feat: x\n\nGtd-Format: 3")
+    repo.seedCommit("feat: x\n\nGtd-Format: 4")
     expect((await run(repo, "next")).exitCode).toBe(0)
   })
 
@@ -842,7 +842,7 @@ describe("a history written in a format this gtd does not read", () => {
     const repo = seed(IDLE_THEN_WORKING)
     const base = repo.resolveRef("HEAD")!
     repo.writeFile("NOTE.md", "a note\n")
-    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 3")
+    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 4")
     repo.updateRef(HISTORY_REF, repo.resolveRef("HEAD")!)
     repo.hardResetTo(base)
     const { exitCode, stderr } = await run(repo, "restore")

package/src/cli/Program.ts

@@ -51,6 +51,7 @@ import {
 } from "../wire/index.js"
 import {
   currentRest,
+  repinAnchor,
   startRefusal,
   currentRun,
   renderRest,
@@ -867,36 +868,45 @@ const runRestoreCommand = (
     yield* writeScript(json, out, combinedScript(required, ""))
   })
 
+/** The step an ordinary repin rests at — the one the process rests at now. */
+const repinTarget = Effect.gen(function* () {
+  const rest = yield* currentRest
+  const refusal =
+    rest.pin === "add"
+      ? "the next beat pins the process already — run it (`gtd next --json=content`), then land"
+      : rest.pin === "remove"
+        ? "the flow has ended — its unpin beat is next, so there is nothing to repin"
+        : noProcessUnderway(rest)
+          ? "no gtd process is underway — nothing to repin"
+          : undefined
+  if (refusal !== undefined) return yield* Effect.fail(new Error(`gtd repin: ${refusal}`))
+  return rest.step.name
+})
+
 /**
- * `gtd repin`: the pin beat's script and landing, on demand. It runs live,
- * so reading the rest first refuses a live workflow that cannot replay the
- * process before any pin is written.
+ * `gtd repin`: the pin beat's script and landing, on demand. It runs live: a
+ * pinned process the live workflow no longer replays is anchored where it
+ * diverged, and any other failure to read the rest refuses before any pin is
+ * written.
  */
 const runRepinCommand = (
   json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
-    const rest = yield* currentRest
-    const refusal =
-      rest.pin === "add"
-        ? "the next beat pins the process already — run it (`gtd next --json=content`), then land"
-        : rest.pin === "remove"
-          ? "the flow has ended — its unpin beat is next, so there is nothing to repin"
-          : noProcessUnderway(rest)
-            ? "no gtd process is underway — nothing to repin"
-            : undefined
-    if (refusal !== undefined) return yield* Effect.fail(new Error(`gtd repin: ${refusal}`))
+    const anchor = yield* repinAnchor
+    const to = anchor?.to ?? (yield* repinTarget)
     const message = formatCommitMessage({
       actor: "check",
       from: PIN_STATES.add,
-      to: rest.step.name,
+      to,
       pin: "add",
+      ...(anchor !== undefined ? { anchor: anchor.at } : {}),
     })
     const steps: EmitStep[] = [
       { kind: "gitWrite", command: repinScript(PIN_PATH) },
       { kind: "gitWrite", command: commitPath(PIN_PATH, message) },
-      { kind: "outcome", command: transitionOutcome(PIN_STATES.add, rest.step.name) },
+      { kind: "outcome", command: transitionOutcome(PIN_STATES.add, to) },
     ]
     yield* writeScript(json, out, combinedScript(emitScripts(steps).required, ""))
   })

package/src/edge/Edge.test.ts

@@ -217,7 +217,7 @@ describe("currentRun", () => {
     const before = headOf(repo)
     const opening = await enter(repo, "side")
     expect(repo.lastCommitMessage(opening)).toBe(
-      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Format: 2`,
+      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Format: 3`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -250,7 +250,7 @@ export const again = workflow(async () => {
     const before = headOf(repo)
     const opening = await enter(repo, "again")
     expect(repo.lastCommitMessage(opening)).toBe(
-      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 2`,
+      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 3`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -403,7 +403,7 @@ export const again = workflow(async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
       await land(repo)
-      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 2")
+      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 3")
       const run = await provide(currentRun, repo)
       expect(run.headTurn).toEqual({ state: "building", actor: "agent", empty: true, step: false })
     })

package/src/edge/Edge.ts

@@ -36,7 +36,9 @@ import {
   parseCommitMessage,
   replay,
   type CommitMessage,
+  formatCommitMessage,
   scopeRunStart,
+  setAsideBy,
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
@@ -259,6 +261,18 @@ const approvalEntryOf = (
         },
       ]
 
+// What an anchor set aside answers no step: it records no mark, approval or
+// verdict. An anchor naming no commit is replay's to refuse.
+const setAsideIn = (history: History, location: EpisodeLocation): ReadonlySet<string> => {
+  const anchored = setAsideBy(
+    hashAt(history, location.baseIndex) ?? EMPTY_TREE,
+    history
+      .slice(location.baseIndex + 1)
+      .map((c) => ({ hash: c.hash, parsed: parseCommitMessage(c.message) })),
+  )
+  return "setAside" in anchored ? anchored.setAside : new Set()
+}
+
 const buildRun = (
   history: History,
   location: EpisodeLocation,
@@ -269,6 +283,9 @@ const buildRun = (
   // 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 setAside = setAsideIn(history, location)
+  const answering = parsed.filter((_, i) => !setAside.has(processCommits[i]!.hash))
+  const answeringCommits = processCommits.filter((c) => !setAside.has(c.hash))
   const first = parsed[0]
   const startParentHash = hashAt(history, location.processStart - 1) ?? EMPTY_TREE
   const head = history[history.length - 1]
@@ -280,10 +297,10 @@ const buildRun = (
     diffBase: first?.reviewBase ?? startParentHash,
     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),
+    judgeVerdicts: answering.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]!)),
+    marks: answering.flatMap((m) => m.marks),
+    approvals: answeringCommits.flatMap((c, i) => approvalEntryOf(c.hash, answering[i]!)),
     pinnedVars: { ...first?.vars },
     headTurn: headTurnOf(head),
     closingHash,
@@ -1012,6 +1029,54 @@ export const restAt = (
 
 export const currentRest: Effect.Effect<Rest, Error, RestRequirements> = restAt(undefined)
 
+/**
+ * Where `gtd repin` anchors a pinned process the live workflow no longer
+ * replays: the commit replay last stood on, and the step the live workflow
+ * reaches from there on HEAD's tree — the unpin when the flow ends instead.
+ * `undefined` when there is nothing to anchor: no divergence, or no pin.
+ */
+export const repinAnchor: Effect.Effect<
+  { readonly at: string; readonly to: string } | undefined,
+  Error,
+  RestRequirements
+> = Effect.gen(function* () {
+  const git = yield* GitService
+  const config = yield* (yield* ConfigService).load
+  const workspace = yield* Workspace
+  const run = yield* computeProcessRun(git, config.workflow)
+  const { def, setup } = yield* setupFor(config, run, workspace, yield* Host)
+  const diverged = yield* Effect.promise(() => replayFor(setup))
+  if (diverged.kind !== "divergence" || !headHasPin(workspace, run)) return undefined
+  // A trial anchor naming the reserved pin state diverges at whatever step the
+  // flow reaches once it stands on HEAD's tree.
+  const trial: EpisodeCommit = {
+    hash: "",
+    message: formatCommitMessage({
+      actor: "check",
+      from: PIN_STATES.add,
+      to: PIN_STATES.add,
+      pin: "add",
+      anchor: diverged.at,
+    }),
+    tree: setup.episode.at(-1)?.tree ?? setup.base.tree,
+  }
+  const outcome = yield* Effect.promise(() =>
+    replayFor({ ...setup, episode: [...setup.episode, trial] }),
+  )
+  if (outcome.kind !== "divergence") {
+    return yield* Effect.fail(replayError(outcome) ?? new Error("gtd repin: replay found no step"))
+  }
+  const to = outcome.reached ?? PIN_STATES.remove
+  if (run.workflow === undefined && to === def.initial) {
+    return yield* Effect.fail(
+      new Error(
+        `gtd repin: the live workflow continues this process at "${to}", the default workflow's first step, where a finished process waits — run \`gtd abandon\` to start over`,
+      ),
+    )
+  }
+  return { at: diverged.at, to }
+})
+
 /** 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 }

package/src/edge/index.ts

@@ -3,6 +3,7 @@ export {
   summaryRun,
   restAt,
   currentRest,
+  repinAnchor,
   startRefusal,
   reviewBaseFor,
   type RenderedRest,

package/src/replay/Format.test.ts

@@ -3,11 +3,12 @@ import { formatCommitMessage, formatFault, parseCommitMessage } from "./index.js
 
 describe("the history format", () => {
   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: 3 }])).toBeUndefined()
     expect(
       formatFault([
         { hash: "a".repeat(40), format: 1 },
         { hash: "b".repeat(40), format: 2 },
+        { hash: "c".repeat(40), format: 3 },
       ]),
     ).toBeUndefined()
     expect(formatFault([])).toBeUndefined()
@@ -16,11 +17,11 @@ describe("the history format", () => {
   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: 3 },
-      { hash: "c".repeat(40), format: 4 },
+      { hash: "b".repeat(40), format: 4 },
+      { hash: "c".repeat(40), format: 5 },
     ])
     expect(fault).toBe(
-      "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",
+      "gtd: commit bbbbbbb is written in history format 4, but this gtd reads formats 1 to 3 — run a gtd release that reads format 4 to continue this process",
     )
   })
 })
@@ -35,8 +36,8 @@ 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: 2")
-    expect(parseCommitMessage(message).format).toBe(2)
+    expect(message).toContain("Gtd-Format: 3")
+    expect(parseCommitMessage(message).format).toBe(3)
   })
 })
 
@@ -50,7 +51,7 @@ describe("Gtd-Pin", () => {
       branch: "main",
     })
     expect(message).toBe(
-      "gtd(check): unpin → idle\n\nGtd-Pin: remove\nGtd-Branch: main\nGtd-Format: 2",
+      "gtd(check): unpin → idle\n\nGtd-Pin: remove\nGtd-Branch: main\nGtd-Format: 3",
     )
     expect(parseCommitMessage(message).pin).toBe("remove")
     expect(parseCommitMessage("gtd(check): pin → a\n\nGtd-Pin: add").pin).toBe("add")
@@ -60,3 +61,21 @@ describe("Gtd-Pin", () => {
     expect(parseCommitMessage("gtd(check): pin → a\n\nGtd-Pin: frozen").pin).toBeUndefined()
   })
 })
+
+describe("Gtd-Anchor", () => {
+  it("round-trips after Gtd-Pin, and reads a non-hash value as no anchor", () => {
+    const anchor = "a".repeat(40)
+    const message = formatCommitMessage({
+      actor: "check",
+      from: "pin",
+      to: "b",
+      pin: "add",
+      anchor,
+    })
+    expect(message).toBe(
+      `gtd(check): pin → b\n\nGtd-Pin: add\nGtd-Anchor: ${anchor}\nGtd-Format: 3`,
+    )
+    expect(parseCommitMessage(message).anchor).toBe(anchor)
+    expect(parseCommitMessage("gtd(check): pin → b\n\nGtd-Anchor: HEAD~2").anchor).toBeUndefined()
+  })
+})

package/src/replay/Format.ts

@@ -1,7 +1,8 @@
 // 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. Format 2 adds pin commits, which format 1 would replay as turns.
-export const HISTORY_FORMAT = 2
+// untouched. Format 2 adds pin commits, which format 1 would replay as turns;
+// format 3 adds the anchor, whose set-aside commits format 2 would replay.
+export const HISTORY_FORMAT = 3
 const OLDEST_READABLE_FORMAT = 1
 
 const short = (hash: string): string => hash.slice(0, 7)

package/src/replay/Replay.test.ts

@@ -1154,6 +1154,8 @@ describe("human({ approve })", () => {
     expect(outcome).toEqual({
       kind: "divergence",
       message: `gtd: commit ${hashOf(1).slice(0, 7)} completes approval gate "gate#1" but records no Gtd-Approved for it — the workflow changed under this process; run \`gtd abandon\` to start over`,
+      at: hashOf(0),
+      reached: "gate",
     })
   })
 
@@ -1271,3 +1273,88 @@ describe("pin commits", () => {
     expect((await replayOf(flow, h)).kind).toBe("ended")
   })
 })
+
+describe("replay: a repin's anchor", () => {
+  const anchorTo = (to: string, at: number): string =>
+    formatCommitMessage({ actor: "check", from: "pin", to, pin: "add", anchor: hashOf(at) })
+
+  // The old flow went idle → build → old; this one goes idle → build → check.
+  const anchoredHistory = (): History =>
+    new History()
+      .land("human", "idle", 1, "build", { "a.txt": "a" })
+      .land("agent", "build", 1, "old", { "b.txt": "b" })
+      .raw(anchorTo("build", 1))
+
+  it("records where replay diverged and the step it reached there", async () => {
+    const h = new History().land("human", "idle", 1, "fix", { "TODO.md": "go" })
+    const outcome = await replayOf(fixLoop, h)
+    expect(outcome).toMatchObject({ kind: "divergence", at: hashOf(1), reached: "check" })
+  })
+
+  it("rests at the anchored step, redone on the anchor's tree", async () => {
+    let afterBuild: readonly string[] = []
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("build", "p")
+      afterBuild = changes().map((c) => c.path)
+      await agent("check", "p")
+    }
+    expect(restName(await replayOf(flow, anchoredHistory()))).toBe("build#1")
+    const outcome = await replayOf(flow, anchoredHistory(), { pending: { "c.txt": "c" } })
+    expect(restName(outcome)).toBe("check#1")
+    expect(afterBuild).toEqual(["c.txt"])
+  })
+
+  it("fails changesSince() on a commit it set aside", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      changesSince(hashOf(2))
+      await agent("build", "p")
+    }
+    const outcome = await replayOf(flow, anchoredHistory())
+    expect(outcome.kind === "failed" && outcome.message).toContain("a repin set 0000000 aside")
+  })
+
+  it("diverges again when the flow reaches another step than the anchor names", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("make", "p")
+    }
+    expect(await replayOf(flow, anchoredHistory())).toMatchObject({
+      kind: "divergence",
+      at: hashOf(3),
+      reached: "make",
+    })
+  })
+
+  it("lets the flow code leading to the step read HEAD's tree", async () => {
+    const flow: Flow = async () => {
+      await human("idle")
+      await agent("build", `seen: ${read("b.txt") ?? "nothing"}`)
+    }
+    const outcome = await replayOf(flow, anchoredHistory())
+    expect(outcome.kind === "rest" && outcome.rest.request).toMatchObject({ prompt: "seen: b" })
+  })
+
+  it("diverges when the flow ends where it names a step", async () => {
+    const outcome = await replayOf(async () => void (await human("idle")), anchoredHistory())
+    expect(outcome).toMatchObject({ kind: "divergence", at: hashOf(3), reached: undefined })
+  })
+
+  it("closes the process when it names the unpin and the flow ends", async () => {
+    const h = new History()
+      .land("human", "idle", 1, "build", { "a.txt": "a" })
+      .land("agent", "build", 1, "old")
+      .raw(anchorTo("unpin", 1))
+    const outcome = await replayOf(async () => void (await human("idle")), h)
+    expect(outcome.kind).toBe("ended")
+  })
+
+  it("fails when it names no commit replay reads", async () => {
+    const h = anchoredHistory().raw(anchorTo("build", 2))
+    const outcome = await replayOf(async () => void (await human("idle")), h)
+    expect(outcome.kind === "failed" && outcome.message).toContain(
+      "which is no commit replay reads",
+    )
+  })
+})