@pmelab/gtd 60.0.0 → 61.0.0

package/src/cli/Program.test.ts

@@ -18,7 +18,13 @@ 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 { needsOf, runCommand, SelectorUsageError, type CommandRequirements } from "./Program.js"
-import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
+import {
+  InMemRepo,
+  makeCapturingCliIo,
+  testLayers,
+  applyEmittedScript,
+  takePinBeat,
+} from "../twins/index.js"
 import {
   commitAll,
   DID_NOT_RUN_COMMENT,
@@ -39,13 +45,14 @@ const run = async (
   return result()
 }
 
-/** Lands via `gtd land --json` and applies the emitted script, as a driver would. */
+/** Lands via `gtd land --json` and applies the emitted script, then takes the pin or unpin beat it leads to, as a driver would. */
 const landAndApply = async (
   repo: InMemRepo,
 ): Promise<{ readonly exitCode: number; readonly script: string }> => {
   const { stdout, exitCode } = await run(repo, "land", "--json")
   const script = exitCode === 0 ? (JSON.parse(stdout) as { readonly script: string }).script : ""
   if (exitCode === 0) expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
+  if (exitCode === 0) await takePinBeat(repo)
   return { exitCode, script }
 }
 
@@ -104,7 +111,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-Config: ${contentHash(WORKFLOW)} gtd.config.ts\nGtd-Format: 1`,
+        `gtd(human): working\n\nGtd-Workflow: hotfix\nGtd-Var: greeting=hello\nGtd-Config: ${contentHash(WORKFLOW)} gtd.config.ts\nGtd-Format: 2`,
       ),
     )
     expect(repo.commitHistory()).toHaveLength(before)
@@ -190,6 +197,9 @@ export const hotfix = workflow(
     const { stdout } = await run(repo, "start", "hotfix")
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
     expect(repo.lastCommitSubject()).toBe("gtd(human): working")
+    const pin = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
+    expect(pin).toMatchObject({ kind: "script", state: "pin", actor: "check", pin: "add" })
+    expect(await takePinBeat(repo, "add")).toBe(true)
     const next = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
     expect(next.kind).toBe("prompt")
     expect(next.state).toBe("working")
@@ -496,6 +506,7 @@ export const resume = workflow(work)
     const repo = seed(WORKFLOW)
     const { stdout: entry } = await run(repo, "start", "resume")
     expect(applyEmittedScript(repo, new Map(), entry).ok).toBe(true)
+    await takePinBeat(repo, "add")
     const { stdout, exitCode } = await run(repo, "next", "--json")
     expect(exitCode).toBe(0)
     expect(JSON.parse(stdout).kind).toBe("prompt")
@@ -775,20 +786,20 @@ describe("gtd next — refuses when history diverges from what replay reaches",
     expect(repo.commitHistory()).toHaveLength(before)
 
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
-    expect(repo.commitHistory()).toHaveLength(before - 2)
+    expect(repo.commitHistory()).toHaveLength(before - 3)
   })
 })
 
 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 2, but this gtd reads format 1"
+  const FOREIGN = "is written in history format 3, but this gtd reads formats 1 to 2"
 
   /** 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: 2")
+    repo.seedCommit("gtd(agent): elsewhere → review\n\nGtd-Step: elsewhere#1\nGtd-Format: 3")
     return repo
   }
 
@@ -813,7 +824,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: 2")
+    repo.seedCommit("gtd2[human] idle -> working\n\nGtd-Format: 3")
     for (const command of ["next", "abandon"]) {
       const { exitCode, stderr } = await run(repo, command)
       expect(exitCode).toBe(1)
@@ -824,7 +835,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: 2")
+    repo.seedCommit("feat: x\n\nGtd-Format: 3")
     expect((await run(repo, "next")).exitCode).toBe(0)
   })
 
@@ -832,7 +843,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: 2")
+    repo.seedCommit("gtd(human): idle → working\n\nGtd-Step: idle#1\nGtd-Format: 3")
     repo.updateRef(HISTORY_REF, repo.resolveRef("HEAD")!)
     repo.hardResetTo(base)
     const { exitCode, stderr } = await run(repo, "restore")
@@ -1390,10 +1401,10 @@ export default async () => {
     expect(await nextOf(repo)).toEqual({ target: "accepted" })
   })
 
-  it("a turn that finishes the flow targets the initial step", async () => {
+  it("a turn that finishes a pinned flow targets the unpin", async () => {
     const repo = await atWorking()
     repo.writeFile("REVIEW.md", "an updated review\n")
-    expect(await nextOf(repo)).toMatchObject({ target: "idle" })
+    expect(await nextOf(repo)).toMatchObject({ target: "unpin" })
   })
 
   it("plain gtd next shows the same preview as a `Next:` line", async () => {
@@ -1476,7 +1487,7 @@ export default async () => {
     expect((JSON.parse(stdout) as { readonly script: string }).script).toContain("git commit")
   })
 
-  it("a clean run that finishes the flow lands an ordinary commit re-entering the initial step", async () => {
+  it("a clean run that finishes a pinned flow lands an ordinary commit at the unpin", async () => {
     const repo = await atChecking(REENTRY_WORKFLOW)
     const { stdout, exitCode } = await run(repo, "land", "--json")
     expect(exitCode).toBe(0)
@@ -1485,7 +1496,7 @@ export default async () => {
     expect(script).not.toContain("git reset --mixed")
     expect(script).not.toContain("nothing to retain")
     expect(applyEmittedScript(repo, new Map(), script).ok).toBe(true)
-    expect(repo.lastCommitSubject()).toBe("gtd(check): checking → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): checking → unpin")
   })
 
   it("the same rest with a pending change lands an ordinary commit too", async () => {
@@ -1523,7 +1534,7 @@ export default async () => {
     expect(parsed.script).toContain("nothing to do")
   })
 
-  it("gtd land --json a decision that re-enters the initial step reports settled:false, idle:true, state:idle", async () => {
+  it("gtd land --json a decision that ends a pinned flow reports settled:false, idle:false, state:unpin", async () => {
     const repo = await atChecking(REENTRY_WORKFLOW)
     const { stdout, exitCode } = await run(repo, "land", "--json")
     expect(exitCode).toBe(0)
@@ -1533,8 +1544,8 @@ export default async () => {
       readonly state: string
     }
     expect(parsed.settled).toBe(false)
-    expect(parsed.idle).toBe(true)
-    expect(parsed.state).toBe("idle")
+    expect(parsed.idle).toBe(false)
+    expect(parsed.state).toBe("unpin")
   })
 
   it("gtd land --json an ordinary commit reports settled:false", async () => {
@@ -1683,7 +1694,7 @@ export default async () => {
     const { exitCode, script } = await landAndApply(repo)
     expect(exitCode).toBe(0)
     expect(script).not.toContain("fmt-notes")
-    expect(repo.lastCommitSubject()).toBe("gtd(agent): drafting → idle")
+    expect(repo.lastCommitSubject("HEAD~1")).toBe("gtd(agent): drafting → unpin")
   })
 
   it("`gtd next --json`'s `validate` field carries the mode's format command", async () => {
@@ -1712,6 +1723,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
     check: { kind: "check", mode: "qa", file: ".gtd/TODO.md" },
     uncheck: { kind: "uncheck", file: ".gtd/REVIEW.md" },
     guide: { kind: "guide" },
+    bundle: { kind: "bundle" },
     summary: { kind: "summary" },
     base: { kind: "base" },
     judge: { kind: "judge" },
@@ -1732,11 +1744,12 @@ describe("runCommand — refuses in a repository with no commits", () => {
   const NO_COMMITS_MESSAGE =
     "gtd: the repository has no commits yet — make an initial commit, then run gtd again"
 
-  it("derives exactly the sixteen non-standalone kinds — a canary for the table-driven cases below", () => {
+  it("derives exactly the seventeen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
       [
         "abandon",
         "base",
+        "bundle",
         "start",
         "land",
         "next",
@@ -1761,7 +1774,10 @@ describe("runCommand — refuses in a repository with no commits", () => {
       const repo = new InMemRepo()
       const before = repo.commitHistory().length
       const written: string[] = []
-      const out = { write: (chunk: string) => written.push(chunk), flush: () => {} }
+      const out = {
+        write: (chunk: string | Uint8Array) => written.push(String(chunk)),
+        flush: () => {},
+      }
 
       const exit = await Effect.runPromiseExit(
         runCommand(commandFor[kind], { kind: "off" }, out).pipe(Effect.provide(testLayers(repo))),
@@ -1780,7 +1796,10 @@ describe("runCommand — refuses in a repository with no commits", () => {
   it("a repository with a commit passes the guard and dispatches normally", async () => {
     const repo = seedIdle()
     const written: string[] = []
-    const out = { write: (chunk: string) => written.push(chunk), flush: () => {} }
+    const out = {
+      write: (chunk: string | Uint8Array) => written.push(String(chunk)),
+      flush: () => {},
+    }
 
     const exit = await Effect.runPromiseExit(
       runCommand({ kind: "next" }, { kind: "off" }, out).pipe(Effect.provide(testLayers(repo))),
@@ -1859,7 +1878,7 @@ export default workflow(
   it("writes the rendered summary, with a trailing newline, counting the human turns after the entry commit", async () => {
     const repo = await reviewed()
     const history = repo.commitHistory()
-    const entryHash = history[history.length - 3]!.hash
+    const entryHash = history[history.length - 4]!.hash
     const tipHash = history[history.length - 1]!.hash
 
     const { exitCode, stdout } = await run(repo, "summary")
@@ -1953,7 +1972,7 @@ export default async () => {
   it("refuses once the process has closed and HEAD rests at the initial step again", async () => {
     const repo = await atDeciding()
     await landTurn(repo)
-    expect(repo.lastCommitSubject()).toBe("gtd(human): deciding → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
 
     const { exitCode, stdout, stderr } = await run(repo, "base")
     expect(exitCode).toBe(1)
@@ -2090,7 +2109,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
     )
     expect(Exit.isFailure(exit)).toBe(true)
     if (Exit.isFailure(exit)) {
-      const failure = Cause.failureOption(exit.cause)
+      const failure = Cause.findErrorOption(exit.cause)
       expect(failure._tag).toBe("Some")
       if (failure._tag === "Some") {
         expect(failure.value).toBeInstanceOf(SelectorUsageError)
@@ -2297,8 +2316,8 @@ export default workflow(
 describe("runCommand — the repository-root guard's messages", () => {
   const guarded = async (
     override: (
-      git: Context.Tag.Service<GitService>,
-      host: Context.Tag.Service<Host>,
+      git: Context.Service.Shape<typeof GitService>,
+      host: Context.Service.Shape<typeof Host>,
     ) => Effect.Effect<unknown, Error, CommandRequirements>,
   ): Promise<string> => {
     const exit = await Effect.runPromiseExit(

package/src/cli/Program.ts

@@ -1,5 +1,6 @@
 import { Effect, Option, Schema } from "effect"
 import {
+  GtdError,
   GtdUsageError,
   Narrator,
   GitService,
@@ -15,6 +16,8 @@ import {
 import {
   WORKFLOW_MODULE,
   ConfigDiscovery,
+  EngineCore,
+  pin,
   refuseLegacyRc,
   ConfigService,
   formatDiagnostic,
@@ -44,6 +47,7 @@ import {
   type StatusChange,
   selectPath,
   EXIT_OK,
+  PIN_PATH,
 } from "../wire/index.js"
 import {
   currentRest,
@@ -77,6 +81,7 @@ import {
   deleteRef,
   hardResetTo,
   mixedResetTo,
+  unpinScript,
   ScriptSurface,
   updateRef,
   type RunnableScript,
@@ -88,7 +93,7 @@ import {
   abandonNoopOutcome,
   restoredOutcome,
 } from "../emit/index.js"
-import { renderBriefing, WORKFLOWS_REPO } from "../install/index.js"
+import { GTD_VERSION, renderBriefing, WORKFLOWS_REPO } from "../install/index.js"
 import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
 import {
   normalizeScriptNewline,
@@ -119,7 +124,7 @@ import { runHistoryMetricsCommand } from "./Metrics.js"
  * SAME type structurally off `currentRest`'s own success type rather than
  * importing the name.
  */
-type Rest = Effect.Effect.Success<typeof currentRest>
+type Rest = Effect.Success<typeof currentRest>
 
 export type Command =
   | { readonly kind: "lsp" }
@@ -161,6 +166,7 @@ export type Command =
     }
   | { readonly kind: "uncheck"; readonly file: string }
   | { readonly kind: "guide" }
+  | { readonly kind: "bundle" }
   | { readonly kind: "summary" }
   | { readonly kind: "base" }
   | { readonly kind: "judge" }
@@ -219,15 +225,34 @@ const runGuideCommand = (
     const briefing = renderBriefing()
     out.write(briefing.endsWith("\n") ? briefing : briefing + "\n")
     const host = yield* Host
-    const topLevel = yield* Effect.either((yield* GitService).topLevel())
-    if (topLevel._tag === "Left") return
-    if ((yield* host.realPath(topLevel.right)) !== (yield* host.realPath(host.root))) return
+    const topLevel = yield* Effect.result((yield* GitService).topLevel())
+    if (topLevel._tag === "Failure") return
+    if ((yield* host.realPath(topLevel.success)) !== (yield* host.realPath(host.root))) return
     if ((yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)) !== undefined) return
     yield* (yield* Narrator).warn(
       `gtd guide: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`,
     )
   })
 
+/** Loads the workflow first, so a pin is never made of one gtd would refuse. */
+const runBundleCommand = (
+  out: ArtifactOut,
+): Effect.Effect<
+  void,
+  Error,
+  ConfigService | ConfigDiscovery | EngineCore | Host | Narrator | Workspace
+> =>
+  Effect.gen(function* () {
+    yield* (yield* ConfigService).load
+    const host = yield* Host
+    const module = yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)
+    // Inside a pin, load read the pinned workflow, not a config on disk.
+    if (module === undefined) {
+      return yield* Effect.fail(new GtdError(`gtd bundle: no ${WORKFLOW_MODULE} here or above`))
+    }
+    out.write(yield* pin(module, host.root, GTD_VERSION))
+  })
+
 /**
  * `planLanding`'s result — a preview of what `gtd land` would do, plus the
  * combined `script` the driver runs to do it. `script` is
@@ -457,7 +482,7 @@ const runJudgeRunCommand = (
   })
 
 /** A verdict's own `answer` shape covers every `judge:` primitive (`noul` → boolean, `choice` → string, `score` → number) without gtd itself interpreting which one applies — that's a driver/judge-model concern, not this decode's. */
-const VerdictAnswer = Schema.Union(Schema.String, Schema.Number, Schema.Boolean)
+const VerdictAnswer = Schema.Union([Schema.String, Schema.Number, Schema.Boolean])
 
 /**
  * One `gtd judge answer` verdict entry per pending question, `{ id, answer,
@@ -470,14 +495,14 @@ const VerdictAnswer = Schema.Union(Schema.String, Schema.Number, Schema.Boolean)
 const verdictSchemaFor = (ids: readonly string[]) =>
   Schema.Array(
     Schema.Struct({
-      id: ids.length > 0 ? Schema.Literal(...(ids as [string, ...string[]])) : Schema.Never,
+      id: ids.length > 0 ? Schema.Literals(ids) : Schema.Never,
       answer: VerdictAnswer,
       // Bounded [0, 1] — every OTHER bound in the routes: matching path fails
       // CLOSED (a non-finite rendered minP/maxP never matches); an
       // unvalidated p wouldn't: a driver bug or a miscalibrated model
       // sending p > 1 would clear every minP a workflow declares,
       // unconditionally forcing the judged route on a live gate.
-      p: Schema.Number.pipe(Schema.between(0, 1)),
+      p: Schema.Number.check(Schema.isBetween({ minimum: 0, maximum: 1 })),
     }),
   )
 
@@ -509,7 +534,7 @@ const runJudgeAnswerCommand = (
       try: () => JSON.parse(raw) as unknown,
       catch: () => new SelectorUsageError("gtd judge answer: stdin is not valid JSON"),
     })
-    const verdict = yield* Schema.decodeUnknown(verdictSchemaFor(ids))(parsed).pipe(
+    const verdict = yield* Schema.decodeUnknownEffect(verdictSchemaFor(ids))(parsed).pipe(
       Effect.mapError(
         (e) =>
           new SelectorUsageError(
@@ -776,6 +801,7 @@ const runAbandonCommand = (
     const steps: EmitStep[] = [
       { kind: "gitWrite", command: updateRef(HISTORY_REF, tip) },
       { kind: "gitWrite", command: mixedResetTo(run.startParentHash) },
+      { kind: "gitWrite", command: unpinScript(PIN_PATH) },
       { kind: "outcome", command: abandonedOutcome(restState, run.startParentHash, initial) },
     ]
     const required = emitScripts(steps).required
@@ -1037,7 +1063,7 @@ const runCodeThreadsCheckCommand = (): Effect.Effect<void, Error, CommandRequire
     const workspace = yield* Workspace
     const changed = yield* git.changedPaths(rest.run.diffBase)
     const lines = changed
-      .filter((c) => c.status !== "D")
+      .filter((c) => c.status !== "D" && c.path !== PIN_PATH)
       .flatMap(({ path }) => {
         const { threads, findings } = parseCodeThreads(path, workspace.atPath(path) ?? "")
         return [
@@ -1137,7 +1163,7 @@ const gatherBeatDocument = (
       kind === "prompt" ? resolveSession(rendered.memory, rendered.memoryResumed) : undefined
     const resolvedValidate =
       kind === "prompt"
-        ? yield* resolveValidateScript(rest).pipe(Effect.catchAll(() => Effect.succeed(undefined)))
+        ? yield* resolveValidateScript(rest).pipe(Effect.catch(() => Effect.succeed(undefined)))
         : undefined
     const validate =
       resolvedValidate !== undefined && resolvedValidate.script.length > 0
@@ -1332,6 +1358,8 @@ const dispatchVoidCommand = (
       return runUncheckCommand(command.file)
     case "guide":
       return runGuideCommand(out)
+    case "bundle":
+      return runBundleCommand(out)
     case "summary":
       return runSummaryCommand(out)
     case "base":

package/src/cli/Strays.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { GitService, GtdError, Narrator, type GitOperations } from "../platform/index.js"
 import { strayPaths } from "../step/index.js"
-import { EXIT_OK, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import { EXIT_OK, EXIT_STRAYS_FOUND, PIN_PATH } from "../wire/index.js"
 import {
   SelectorUsageError,
   writeSelection,
@@ -31,7 +31,8 @@ export const runStraysCommand = (
     const narrator = yield* Narrator
     const base = yield* resolveSide(git, command.base)
     const tip = yield* resolveSide(git, command.tip)
-    const touched = yield* git.diffPaths(base, tip)
+    // The pin is the engine's, never a turn's, so it is never a stray either.
+    const touched = (yield* git.diffPaths(base, tip)).filter((path) => path !== PIN_PATH)
     const strays = strayPaths(touched, command.globs)
     const total = touched.length
 

package/src/cli/ToolCommands.ts

@@ -29,7 +29,7 @@ interface JudgeRequest {
  * The subcommands backed by a driver or tool. Core may not import those
  * units, so the composition root provides them here.
  */
-export class ToolCommands extends Context.Tag("ToolCommands")<
+export class ToolCommands extends Context.Service<
   ToolCommands,
   {
     readonly ui: (
@@ -39,4 +39,4 @@ export class ToolCommands extends Context.Tag("ToolCommands")<
     readonly lsp: (gtd: SelfGtd) => Effect.Effect<void, Error>
     readonly judge: (request: JudgeRequest) => Promise<string>
   }
->() {}
+>()("ToolCommands") {}