@pmelab/gtd 24.2.0 → 24.4.0

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

package/src/cli/Output.ts

@@ -0,0 +1,68 @@
+import { Effect } from "effect"
+import { CommandRunner, GitService, Host, Narrator, Workspace } from "../platform/index.js"
+import { selectPath } from "../wire/index.js"
+import { ConfigDiscovery, ConfigService } from "../workflow/index.js"
+import type { ToolCommands } from "./ToolCommands.js"
+
+/**
+ * A command-level failure that should exit like a CLI usage error (2), not a
+ * generic runtime failure (1): an unknown `--json=<path>` selector, or a
+ * `gtd judge answer` verdict that fails to decode — malformed JSON on stdin,
+ * or one naming a question id the pending judgment never asked. Both are
+ * caller-input errors per `docs/cli.md`'s exit-code table, not a refusal
+ * about the resolved rest's own state.
+ */
+export class SelectorUsageError extends Error {}
+
+/** The `--json=<path>` select branch, shared by the emitting commands so none drift on the unknown-selector message. `absent` writes nothing and lets the caller's success path continue. */
+export const writeSelection = (
+  out: ArtifactOut,
+  fields: unknown,
+  path: string,
+): Effect.Effect<void, Error> =>
+  Effect.gen(function* () {
+    const selection = selectPath(fields, path)
+    if (selection.kind === "value") {
+      out.write(`${selection.text}\n`)
+    } else if (selection.kind === "unknown") {
+      return yield* Effect.fail(
+        new SelectorUsageError(
+          `gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``,
+        ),
+      )
+    }
+  })
+
+/**
+ * `--json`'s three shapes: absent, bare (the whole document), or `--json=<path>`
+ * (one reduced value). See `src/wire/Select.ts` for how `select` is later resolved.
+ */
+export type JsonMode =
+  | { readonly kind: "off" }
+  | { readonly kind: "document" }
+  | { readonly kind: "select"; readonly path: string }
+
+/**
+ * The all-or-nothing stdout buffer every `run*Command` handler writes
+ * through instead of `io.stdout` directly. `flush()` is called exactly once,
+ * by `runCli`, after the command's Effect succeeds; on any failure `flush()`
+ * is never reached, so the buffer is simply discarded and nothing reaches
+ * `io.stdout`. `ui` is the one handler that calls `flush()` itself,
+ * ahead of blocking on `Effect.never` — since it blocks forever, `runCli`'s
+ * own flush-on-success would otherwise never fire and its output would never
+ * reach stdout.
+ */
+export interface ArtifactOut {
+  readonly write: (chunk: string) => void
+  readonly flush: () => void
+}
+
+export type CommandRequirements =
+  | GitService
+  | ConfigService
+  | ConfigDiscovery
+  | Workspace
+  | Host
+  | Narrator
+  | CommandRunner
+  | ToolCommands

package/src/cli/Program.test.ts

@@ -17,7 +17,7 @@ vi.mock("node:os", async (importOriginal) => ({
 
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
-import { formatFinding, needsOf, runCommand, SelectorUsageError } from "./Program.js"
+import { needsOf, runCommand, SelectorUsageError } from "./Program.js"
 import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../testkit/index.js"
 import {
   commitAll,
@@ -28,6 +28,7 @@ import {
 } from "../emit/index.js"
 import { HISTORY_REF } from "../platform/index.js"
 import { CONFIG_SCAFFOLD } from "../install/index.js"
+import { contentHash } from "../workflow/index.js"
 
 const run = async (
   repo: InMemRepo,
@@ -102,7 +103,7 @@ export const defaults = { greeting: "hello" }
     expect(exitCode).toBe(0)
     expect(stdout).toContain(
       commitAll(
-        "gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Format: 1",
+        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Config: ${contentHash(WORKFLOW)} gtd.config.ts\nGtd-Format: 1`,
       ),
     )
     expect(repo.commitHistory()).toHaveLength(before)
@@ -958,12 +959,6 @@ describe("gtd check <mode> <file>", () => {
     )
   })
 
-  it("a line-carrying finding with no range prints '<file>:<line>: <message>' — the flat-shape fallback no built-in format reaches", async () => {
-    expect(formatFinding("FAKE.md", { message: "positioned but rangeless", line: 4 })).toBe(
-      "FAKE.md:5: positioned but rangeless",
-    )
-  })
-
   it("an absent file exits 0 with no output", async () => {
     const repo = bareRepo()
     const { stdout, exitCode } = await run(repo, "check", "qa", ".gtd/TODO.md")
@@ -1697,6 +1692,9 @@ describe("runCommand — refuses in a repository with no commits", () => {
     judge: { kind: "judge" },
     judgeAnswer: { kind: "judgeAnswer" },
     judgeRun: { kind: "judgeRun", provider: "fixed" },
+    historyList: { kind: "historyList" },
+    historyShow: { kind: "historyShow", ref: "x" },
+    historyFetch: { kind: "historyFetch", remote: "origin" },
   }
 
   const stateKinds = (Object.keys(commandFor) as Command["kind"][]).filter(
@@ -1706,7 +1704,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   const NO_COMMITS_MESSAGE =
     "gtd requires a repository with at least one commit — make an initial commit, then run gtd again"
 
-  it("derives exactly the thirteen non-standalone kinds — a canary for the table-driven cases below", () => {
+  it("derives exactly the sixteen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
       [
         "abandon",
@@ -1722,6 +1720,9 @@ describe("runCommand — refuses in a repository with no commits", () => {
         "ui",
         "judge",
         "judgeAnswer",
+        "historyList",
+        "historyShow",
+        "historyFetch",
       ].sort(),
     )
   })