@pmelab/gtd 24.1.0 → 24.3.0

package/dist/workflows/feature.mjs

@@ -1,6 +1,6 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, numeric, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars } from "../flows.mjs";
 import { freezeScenarios, review as review$1 } from "../workflow-kit.mjs";
-import { $ as unwindFailure, A as architectureAuthorPrompt, B as designTriagePrompt, C as fixCheck, D as reviewing, E as reviewMissing, F as buildReviewFixNitsPrompt, G as packagesItemFixSuitePrompt, I as buildReviewTriageMessage, K as reviewEditNotesCapture, L as builderSystem, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewCollectingPrompt, Q as unwindFailedMessage, R as designGateAnswerMessage, S as coder, T as planner, U as idleMessage, W as packagesItemBuildingPrompt, X as reviewerSystem, Y as reviewNotesCapture, Z as startGateBlockedMessage, _ as ARCHITECTURE, b as REVIEW, c as refusePendingHandOff, d as shipped, f as defaults, g as healthy, h as gate, i as skills, j as architectureDecomposePrompt, k as architectSystem, l as tail, n as summary, o as closeReview, p as envDefaults, q as reviewEditsCapture, r as access, t as steering, u as guarded, v as FEEDBACK, w as fixRisks, x as awaitReview, y as REQUIREMENTS, z as designSystem } from "../chunks/reserved-ejn-LVYO.mjs";
+import { $ as unwindFailure, A as architectureAuthorPrompt, B as designTriagePrompt, C as fixCheck, D as reviewing, E as reviewMissing, F as buildReviewFixNitsPrompt, G as packagesItemFixSuitePrompt, I as buildReviewTriageMessage, K as reviewEditNotesCapture, L as builderSystem, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewCollectingPrompt, Q as unwindFailedMessage, R as designGateAnswerMessage, S as coder, T as planner, U as idleMessage, W as packagesItemBuildingPrompt, X as reviewerSystem, Y as reviewNotesCapture, Z as startGateBlockedMessage, _ as ARCHITECTURE, b as REVIEW, c as refusePendingHandOff, d as shipped, f as defaults, g as healthy, h as gate, i as skills, j as architectureDecomposePrompt, k as architectSystem, l as tail, n as summary, o as closeReview, p as envDefaults, q as reviewEditsCapture, r as access, t as steering, u as guarded, v as FEEDBACK, w as fixRisks, x as awaitReview, y as REQUIREMENTS, z as designSystem } from "../chunks/reserved-DJwU5C4z.mjs";
 //#region src/workflows/feature/steps.ts
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 const triage = (base) => agentWithSkills("triage", designTriagePrompt(base), {

package/dist/workflows/fix.mjs

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-D-PvRC5W.mjs";
-import { H as fixReviewNotesPrompt, O as agentWithSkills, S as coder, V as finisherSystem, a as REVIEW_ORIG, b as REVIEW, d as shipped, f as defaults, i as skills, m as baseline, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-ejn-LVYO.mjs";
+import { H as fixReviewNotesPrompt, O as agentWithSkills, S as coder, V as finisherSystem, a as REVIEW_ORIG, b as REVIEW, d as shipped, f as defaults, i as skills, m as baseline, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-DJwU5C4z.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,5 +1,5 @@
 import { start } from "../flows.mjs";
-import { J as reviewGateBlockedMessage, c as refusePendingHandOff, d as shipped, f as defaults, h as gate, i as skills, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-ejn-LVYO.mjs";
+import { J as reviewGateBlockedMessage, c as refusePendingHandOff, d as shipped, f as defaults, h as gate, i as skills, n as summary, p as envDefaults, r as access, s as handOffTail, t as steering } from "../chunks/reserved-DJwU5C4z.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "24.1.0",
+  "version": "24.3.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.test.ts

@@ -926,6 +926,60 @@ describe("parseArgv — doors", () => {
   })
 })
 
+describe("parseArgv — gtd history", () => {
+  const parse = (...args: string[]) => parseArgv(["node", "gtd.js", ...args])
+  const usage = (plan: CliPlan): string => (plan.kind === "usage" ? plan.message : "")
+
+  it("history list / show <ref> / fetch parse to their commands", () => {
+    expect(parse("history", "list")).toMatchObject({
+      kind: "command",
+      command: { kind: "historyList" },
+    })
+    expect(parse("history", "show", "feat/x")).toMatchObject({
+      kind: "command",
+      command: { kind: "historyShow", ref: "feat/x" },
+    })
+    expect(parse("history", "fetch")).toMatchObject({
+      kind: "command",
+      command: { kind: "historyFetch", remote: "origin" },
+    })
+    expect(parse("history", "fetch", "upstream")).toMatchObject({
+      command: { kind: "historyFetch", remote: "upstream" },
+    })
+  })
+
+  it("bare history and an unknown subcommand are usage errors naming list, show, fetch", () => {
+    for (const args of [["history"], ["history", "nope"]]) {
+      const message = usage(parse(...args))
+      expect(message).toContain("list")
+      expect(message).toContain("show")
+      expect(message).toContain("fetch")
+    }
+  })
+
+  it("show without a ref, and extra arguments, are usage errors", () => {
+    expect(usage(parse("history", "show"))).toContain("missing ref")
+    expect(usage(parse("history", "show", "a", "b"))).toContain("too many arguments")
+    expect(usage(parse("history", "list", "x"))).toContain("too many arguments")
+    expect(usage(parse("history", "fetch", "a", "b"))).toContain("too many arguments")
+  })
+
+  it("--json is accepted for list and show, rejected for fetch", () => {
+    expect(parse("history", "list", "--json")).toMatchObject({ json: { kind: "document" } })
+    expect(parse("history", "show", "x", "--json=ended")).toMatchObject({
+      json: { kind: "select", path: "ended" },
+    })
+    expect(parse("history", "fetch", "--json").kind).toBe("usage")
+  })
+
+  it("help lists the three history rows", () => {
+    const help = renderHelp()
+    expect(help).toMatch(/^ {2}history list\b/m)
+    expect(help).toContain("history show <ref>")
+    expect(help).toContain("history fetch [remote]")
+  })
+})
+
 describe("standaloneKinds / needsOf", () => {
   it("pins the standalone kinds", () => {
     expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "loop", "judgeRun"])
@@ -950,6 +1004,9 @@ describe("standaloneKinds / needsOf", () => {
       "judgeAnswer",
       "door",
       "doors",
+      "historyList",
+      "historyShow",
+      "historyFetch",
     ] as const) {
       expect(needsOf(kind)).toBe("state")
     }

package/src/cli/Cli.ts

@@ -92,15 +92,17 @@ const FLAGS: readonly FlagRow[] = [
       kind === "land" ||
       kind === "judge" ||
       kind === "judgeAnswer" ||
-      kind === "doors",
+      kind === "doors" ||
+      kind === "historyList" ||
+      kind === "historyShow",
     decode: ([raw]) => Either.right(raw ?? ""),
     scopeError:
-      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors` — " +
+      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show` — " +
       "every other command prints plain text; see `gtd install` for the driver protocol briefing",
     valueHint: "<path>",
     help: [
-      "(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors only) output",
-      "structured JSON. Bare --json prints the whole document;",
+      "(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd history",
+      "list/gtd history show only) output structured JSON. Bare --json prints the whole document;",
       "--json=<path> (a dotted key path into that document, e.g.",
       "kind, content, session.id) prints just that value: a",
       "scalar raw and unquoted, a boolean as true/false, a list",
@@ -366,6 +368,8 @@ type Arity =
   | { readonly names: readonly [string, string] }
   // One required leading positional, then any number the command itself judges.
   | { readonly name: string; readonly variadic: string }
+  // At most one trailing positional.
+  | { readonly name: string; readonly optional: true }
 
 interface CommandRow {
   readonly token: string
@@ -661,6 +665,41 @@ const COMMAND_ROWS: readonly CommandRow[] = [
       "every question, with nothing on stdout",
     ],
   },
+  {
+    token: "history list",
+    kind: "historyList",
+    arity: "none",
+    details: [
+      "List the finished processes kept behind refs/gtd/history/*,",
+      "newest first: entry, branch, tip, date and subject per line.",
+      "--json prints one array of { ref, entry, branch, tip, date,",
+      "subject }. Writes nothing and never replays; with no refs it",
+      "hints at `gtd history fetch | sh` and still exits 0",
+    ],
+  },
+  {
+    token: "history show",
+    kind: "historyShow",
+    arity: { name: "ref" },
+    details: [
+      "Replay one kept process under today's config and print its",
+      "steps and judge verdicts. <ref> is a full ref, an entry hash",
+      "(or unique prefix) or a branch name. Refuses (exit 1) when a",
+      "config file differs from its content at the ref's tip. A",
+      "version mismatch only warns on stderr. --json prints the",
+      "trail as one document; writes nothing",
+    ],
+  },
+  {
+    token: "history fetch",
+    kind: "historyFetch",
+    arity: { name: "remote", optional: true },
+    details: [
+      "Print a script that fetches every refs/gtd/history/* from",
+      "<remote> (default origin) and reports how many arrived — run",
+      "it with `gtd history fetch | sh`. Never runs git itself",
+    ],
+  },
 ]
 
 const commandByToken = (token: string): CommandRow | undefined =>
@@ -708,7 +747,9 @@ export const renderHelp = (): string => {
           ? `${row.token} <${row.arity.names[0]}> <${row.arity.names[1]}>`
           : "variadic" in row.arity
             ? `${row.token} <${row.arity.name}> [${row.arity.variadic}...]`
-            : `${row.token} <${row.arity.name}>`
+            : "optional" in row.arity
+              ? `${row.token} [${row.arity.name}]`
+              : `${row.token} <${row.arity.name}>`
     return renderBlock(header, row.details)
   })
   const commands = [
@@ -883,6 +924,11 @@ const arityError = (cmd: string, rest: readonly string[], arity: Arity): string
       : undefined
   }
   if ("names" in arity) return pairArityError(cmd, rest, arity.names)
+  if ("optional" in arity) {
+    return rest.length > 1
+      ? `gtd ${cmd}: too many arguments — expected at most one ${arity.name}, got: ${rest.join(", ")}`
+      : undefined
+  }
   if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`
   if (!("variadic" in arity) && rest.length > 1) {
     return `gtd ${cmd}: too many arguments — expected one ${arity.name}, got: ${rest.join(", ")}`
@@ -950,7 +996,18 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   if (first === "version") return { kind: "output", stdout: `${GTD_VERSION}\n` }
   if (first === "help") return { kind: "output", stdout: renderHelp() }
 
-  const row = first === undefined ? undefined : commandByToken(first)
+  const isHistory = first === "history"
+  const row =
+    first === undefined
+      ? undefined
+      : commandByToken(isHistory ? `history ${positionals[1] ?? ""}` : first)
+
+  if (isHistory && row === undefined) {
+    return usagePlan(
+      "gtd history: expected a subcommand — list, show <ref> or fetch [remote]",
+      jsonSeen,
+    )
+  }
 
   // `gtd judge answer` — the CLI's one two-level verb. The NORMAL path is
   // "answer" arriving as `positionals[1]`, a second token after "judge" —
@@ -1005,7 +1062,9 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   // From here, `kind` is a genuine `Command["kind"]`. `judgeAnswer` consumes
   // TWO leading positionals ("judge" and "answer"), everything else one.
   const restPositionals =
-    first === undefined ? positionals : positionals.slice(judgeAnswer || judgeRun ? 2 : 1)
+    first === undefined
+      ? positionals
+      : positionals.slice(judgeAnswer || judgeRun || isHistory ? 2 : 1)
 
   if (kind === "start" && first === undefined) {
     if (restPositionals.length > 0) {
@@ -1019,7 +1078,9 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     // `first === undefined`, which the `if` branch above already handled.
     const bareCheck =
       kind === "check" && restPositionals.length === 0 && present.has("--open-threads")
-    const arityMsg = bareCheck ? undefined : arityError(first!, restPositionals, row!.arity)
+    const arityMsg = bareCheck
+      ? undefined
+      : arityError(isHistory ? row!.token : first!, restPositionals, row!.arity)
     if (arityMsg !== undefined) return usagePlan(arityMsg, jsonSeen)
   }
 
@@ -1147,6 +1208,24 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     }
   }
 
+  if (kind === "historyShow") {
+    return {
+      kind: "command",
+      command: { kind: "historyShow", ref: restPositionals[0]! },
+      json,
+      verbose,
+    }
+  }
+
+  if (kind === "historyFetch") {
+    return {
+      kind: "command",
+      command: { kind: "historyFetch", remote: restPositionals[0] ?? "origin" },
+      json,
+      verbose,
+    }
+  }
+
   if (kind === "uncheck") {
     return {
       kind: "command",
@@ -1170,7 +1249,8 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
       | "summary"
       | "base"
       | "judge"
-      | "judgeAnswer",
+      | "judgeAnswer"
+      | "historyList",
   }
   return { kind: "command", command, json, verbose }
 }

package/src/cli/History.test.ts

@@ -0,0 +1,225 @@
+import { Effect, Exit } from "effect"
+import { describe, expect, it } from "vitest"
+import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { runCli } from "./index.js"
+import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
+
+const CONFIG = `import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await agent("building", "build-prompt")
+}
+`
+
+const land = async (repo: InMemRepo, files: Record<string, string>): Promise<string> => {
+  for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", "land", "--json"], io))
+  const { stdout, exitCode, stderr } = result()
+  if (exitCode !== 0) throw new Error(`land exited ${exitCode}: ${stderr}`)
+  const outcome = applyEmittedScript(
+    repo,
+    new Map(),
+    (JSON.parse(stdout) as { script: string }).script,
+  )
+  if (!outcome.ok) throw new Error(outcome.error)
+  return repo.resolveRef("HEAD")!
+}
+
+const finishedProcess = async (repo: InMemRepo, file: string) => {
+  const entry = await land(repo, { [file]: `${file}\n` })
+  const tip = await land(repo, { [`${file}.out`]: "out\n" })
+  return { entry, tip }
+}
+
+const repoWithConfig = (): InMemRepo => {
+  const repo = new InMemRepo()
+  repo.writeFile("gtd.config.ts", CONFIG)
+  repo.commitAllWithPrefix("chore: add workflow")
+  return repo
+}
+
+const entries = (repo: InMemRepo): Promise<readonly HistoryEntry[]> =>
+  Effect.runPromise(historyEntries.pipe(Effect.provide(testLayers(repo, {}))))
+
+const entry = (over: Partial<HistoryEntry> & { entry: string }): HistoryEntry => ({
+  ref: `refs/gtd/history/${over.entry}`,
+  branch: null,
+  tip: "t".repeat(40),
+  date: "1",
+  subject: "s",
+  ...over,
+})
+
+const resolve = (
+  arg: string,
+  list: readonly HistoryEntry[],
+): Promise<Exit.Exit<HistoryEntry, Error>> => Effect.runPromiseExit(resolveHistoryRef(arg, list))
+
+const failureText = (exit: Exit.Exit<unknown, Error>): string =>
+  Exit.isFailure(exit) ? String(exit.cause) : ""
+
+describe("historyEntries", () => {
+  it("is empty without refs", async () => {
+    expect(await entries(repoWithConfig())).toEqual([])
+  })
+
+  it("lists finished processes newest tip first, with branch and entry subject", async () => {
+    const repo = repoWithConfig()
+    const first = await finishedProcess(repo, "a.txt")
+    const second = await finishedProcess(repo, "b.txt")
+    const list = await entries(repo)
+    expect(list.map((e) => e.entry)).toEqual([second.entry, first.entry])
+    expect(list[0]).toMatchObject({
+      ref: `refs/gtd/history/${second.entry}`,
+      branch: repo.branchName(),
+      tip: second.tip,
+      subject: "gtd(human): idle → building",
+    })
+  })
+
+  it("skips a ref whose name suffix is not an entry hash", async () => {
+    const repo = repoWithConfig()
+    const { entry: hash } = await finishedProcess(repo, "a.txt")
+    repo.updateRef("refs/gtd/history/--output=x", "HEAD")
+    expect((await entries(repo)).map((e) => e.entry)).toEqual([hash])
+  })
+
+  it("has a null branch when the tip records none", async () => {
+    const repo = repoWithConfig()
+    const { entry: hash } = await finishedProcess(repo, "a.txt")
+    repo.writeFile("x.txt", "x\n")
+    repo.commitAllWithPrefix("chore: bare tip")
+    repo.updateRef(`refs/gtd/history/${hash}`, "HEAD")
+    expect((await entries(repo))[0]?.branch).toBeNull()
+  })
+})
+
+describe("resolveHistoryRef", () => {
+  const a = entry({ entry: "abc1230000", branch: "feat/x", date: "1" })
+  const b = entry({ entry: "abc9990000", branch: "feat/x", date: "2" })
+  const c = entry({ entry: "def4560000", branch: "other", date: "3" })
+  const list = [c, b, a]
+
+  it("accepts the full ref", async () => {
+    expect(await resolve(a.ref, list)).toEqual(Exit.succeed(a))
+  })
+
+  it("accepts the entry hash or a unique hex prefix", async () => {
+    expect(await resolve("abc1230000", list)).toEqual(Exit.succeed(a))
+    expect(await resolve("def", list)).toEqual(Exit.succeed(c))
+  })
+
+  it("refuses an ambiguous prefix, listing every match", async () => {
+    const exit = await resolve("abc", list)
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(failureText(exit)).toContain(a.entry)
+    expect(failureText(exit)).toContain(b.entry)
+    expect(failureText(exit)).not.toContain(c.entry)
+  })
+
+  it("resolves a branch name to its newest ref by tip date", async () => {
+    expect(await resolve("feat/x", list)).toEqual(Exit.succeed(b))
+  })
+
+  it("resolves a hex-looking branch name matching no entry as a branch", async () => {
+    const dead = entry({ entry: "1111110000", branch: "beef", date: "9" })
+    expect(await resolve("beef", [dead, ...list])).toEqual(Exit.succeed(dead))
+  })
+
+  it("fails when nothing matches", async () => {
+    const exit = await resolve("nope", list)
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(failureText(exit)).toContain("nope")
+  })
+})
+
+const gtd = async (repo: InMemRepo, ...args: string[]) => {
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", ...args], io))
+  return result()
+}
+
+describe("gtd history list", () => {
+  it("prints the fetch hint and exits 0 without refs", async () => {
+    const out = await gtd(repoWithConfig(), "history", "list")
+    expect(out.exitCode).toBe(0)
+    expect(out.stdout).toBe("no history refs; run gtd history fetch | sh to pull them\n")
+  })
+
+  it("prints [] under --json without refs", async () => {
+    const out = await gtd(repoWithConfig(), "history", "list", "--json")
+    expect(out.exitCode).toBe(0)
+    expect(JSON.parse(out.stdout)).toEqual([])
+  })
+
+  it("prints one text line per ref and a full-hash JSON array", async () => {
+    const repo = repoWithConfig()
+    const { entry: hash, tip } = await finishedProcess(repo, "a.txt")
+    const text = await gtd(repo, "history", "list")
+    const line = text.stdout.trimEnd().split("\n")
+    expect(line).toHaveLength(1)
+    expect(
+      line[0]!.startsWith(`${hash.slice(0, 7)} ${repo.branchName()} ${tip.slice(0, 7)} `),
+    ).toBe(true)
+    expect(line[0]!.endsWith(" gtd(human): idle → building")).toBe(true)
+    const json = await gtd(repo, "history", "list", "--json")
+    expect(JSON.parse(json.stdout)).toEqual([
+      expect.objectContaining({
+        ref: `refs/gtd/history/${hash}`,
+        entry: hash,
+        branch: repo.branchName(),
+        tip,
+        subject: "gtd(human): idle → building",
+      }),
+    ])
+    expect((await gtd(repo, "history", "list", "--json=0.entry")).stdout).toBe(`${hash}\n`)
+  })
+})
+
+describe("gtd history show", () => {
+  it("prints header, steps and the ending", async () => {
+    const repo = repoWithConfig()
+    const { entry: hash, tip } = await finishedProcess(repo, "a.txt")
+    const out = await gtd(repo, "history", "show", hash.slice(0, 7))
+    expect(out.exitCode).toBe(0)
+    const lines = out.stdout.trimEnd().split("\n")
+    expect(lines[0]).toBe(
+      `refs/gtd/history/${hash} (branch ${repo.branchName()}, tip ${tip.slice(0, 7)})`,
+    )
+    expect(out.stdout).toContain("gtd(human): idle → building")
+    expect(lines[lines.length - 1]).toBe("ended (return)")
+  })
+
+  it("--json carries the trail and the entry fields", async () => {
+    const repo = repoWithConfig()
+    const { entry: hash, tip } = await finishedProcess(repo, "a.txt")
+    const out = await gtd(repo, "history", "show", hash, "--json")
+    const doc = JSON.parse(out.stdout)
+    expect(doc).toMatchObject({ entry: hash, tip, ended: "return", branch: repo.branchName() })
+    expect(doc.steps.length).toBeGreaterThan(0)
+    expect(doc.version).toHaveProperty("running")
+  })
+
+  it("exits 1 for an unknown ref", async () => {
+    const out = await gtd(repoWithConfig(), "history", "show", "nope")
+    expect(out.exitCode).toBe(1)
+    expect(out.stdout).toBe("")
+  })
+})
+
+describe("gtd history fetch", () => {
+  it("prints a script fetching from origin and writes no git", async () => {
+    const repo = repoWithConfig()
+    const out = await gtd(repo, "history", "fetch")
+    expect(out.exitCode).toBe(0)
+    expect(out.stdout).toContain("git fetch 'origin' 'refs/gtd/history/*:refs/gtd/history/*'")
+    expect(repo.resolveRef("refs/gtd/history/x")).toBeNull()
+  })
+
+  it("takes the remote as an argument", async () => {
+    const out = await gtd(repoWithConfig(), "history", "fetch", "upstream")
+    expect(out.stdout).toContain("git fetch 'upstream'")
+  })
+})

package/src/cli/History.ts

@@ -0,0 +1,143 @@
+import { Effect } from "effect"
+import { historyTrail } from "../edge/index.js"
+import { combinedScript, fetchHistoryRefs } from "../emit/index.js"
+import { GitService, Narrator, PROCESS_HISTORY_PREFIX } from "../platform/index.js"
+import { parseCommitMessage } from "../replay/index.js"
+import {
+  writeSelection,
+  type ArtifactOut,
+  type CommandRequirements,
+  type JsonMode,
+} from "./Output.js"
+
+export interface HistoryEntry {
+  readonly ref: string
+  readonly entry: string
+  /** From the tip's `Gtd-Branch`; null when the finishing commit recorded none. */
+  readonly branch: string | null
+  readonly tip: string
+  readonly date: string
+  readonly subject: string
+}
+
+/** Newest tip first. */
+export const historyEntries: Effect.Effect<readonly HistoryEntry[], Error, GitService> = Effect.gen(
+  function* () {
+    const git = yield* GitService
+    // A fetched ref name is attacker-controlled: only hash suffixes are entries.
+    const refs = (yield* git.listRefs(PROCESS_HISTORY_PREFIX)).filter(({ ref }) =>
+      ENTRY_HASH.test(ref.slice(PROCESS_HISTORY_PREFIX.length)),
+    )
+    return yield* Effect.forEach(refs, ({ ref, hash, date }) =>
+      Effect.gen(function* () {
+        const entry = ref.slice(PROCESS_HISTORY_PREFIX.length)
+        const message = parseCommitMessage(yield* git.lastCommitMessage(hash))
+        return {
+          ref,
+          entry,
+          branch: message.branch ?? null,
+          tip: hash,
+          date,
+          subject: yield* git.lastCommitSubject(entry),
+        }
+      }),
+    )
+  },
+)
+
+const ENTRY_HASH = /^[0-9a-f]{40}([0-9a-f]{24})?$/
+
+const HEX = /^[0-9a-f]+$/i
+
+/**
+ * Lookup order: full ref; then entry hash or hex prefix (unique → it, several
+ * → fail listing them); then branch name (newest tip first, as `entries` is
+ * ordered). A hex-looking name that matches no entry still resolves as a
+ * branch. No match → fail.
+ */
+export const resolveHistoryRef = (
+  arg: string,
+  entries: readonly HistoryEntry[],
+): Effect.Effect<HistoryEntry, Error> => {
+  const byRef = entries.find((e) => e.ref === arg)
+  if (byRef !== undefined) return Effect.succeed(byRef)
+  if (HEX.test(arg)) {
+    const lower = arg.toLowerCase()
+    const matches = entries.filter((e) => e.entry.toLowerCase().startsWith(lower))
+    if (matches.length === 1) return Effect.succeed(matches[0]!)
+    if (matches.length > 1) {
+      return Effect.fail(
+        new Error(
+          `gtd history: "${arg}" is ambiguous — it matches:\n${matches.map((e) => `  ${e.entry} ${e.branch ?? "-"}`).join("\n")}`,
+        ),
+      )
+    }
+  }
+  const byBranch = entries.find((e) => e.branch === arg)
+  if (byBranch !== undefined) return Effect.succeed(byBranch)
+  return Effect.fail(new Error(`gtd history: no history ref matches "${arg}"`))
+}
+
+const seven = (hash: string): string => hash.slice(0, 7)
+
+/** Writes `document` per `json` (bare → whole, `=path` → one value); returns false for `off`. */
+const writeJson = (
+  json: JsonMode,
+  out: ArtifactOut,
+  document: unknown,
+): Effect.Effect<boolean, Error> =>
+  Effect.gen(function* () {
+    if (json.kind === "off") return false
+    if (json.kind === "document") out.write(`${JSON.stringify(document)}\n`)
+    else yield* writeSelection(out, document, json.path)
+    return true
+  })
+
+export const runHistoryListCommand = (
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
+  Effect.gen(function* () {
+    const entries = yield* historyEntries
+    if (yield* writeJson(json, out, entries)) return
+    if (entries.length === 0) {
+      out.write("no history refs; run gtd history fetch | sh to pull them\n")
+      return
+    }
+    out.write(
+      entries
+        .map((e) => `${seven(e.entry)} ${e.branch ?? "-"} ${seven(e.tip)} ${e.date} ${e.subject}\n`)
+        .join(""),
+    )
+  })
+
+export const runHistoryShowCommand = (
+  ref: string,
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
+  Effect.gen(function* () {
+    const entry = yield* resolveHistoryRef(ref, yield* historyEntries)
+    const trail = yield* historyTrail(entry.tip)
+    const document = { ref: entry.ref, entry: entry.entry, branch: entry.branch, ...trail }
+    if (yield* writeJson(json, out, document)) return
+    if (trail.versionWarning !== undefined) {
+      yield* (yield* Narrator).warn(trail.versionWarning)
+    }
+    const lines = [`${entry.ref} (branch ${entry.branch ?? "-"}, tip ${seven(entry.tip)})`]
+    for (const step of trail.steps) {
+      lines.push(`${seven(step.hash)} ${step.subject}`)
+      for (const v of step.verdicts) lines.push(`  judge ${v.id} = ${v.answer} (p=${v.p})`)
+    }
+    lines.push(`ended (${trail.ended})`)
+    out.write(`${lines.join("\n")}\n`)
+  })
+
+/** Prints the script and never runs git: gtd's promise that it only decides and prints. */
+export const runHistoryFetchCommand = (
+  remote: string,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
+  Effect.sync(() => {
+    out.write(`${combinedScript(fetchHistoryRefs(remote), "")}\n`)
+  })