@pmelab/gtd 64.2.0 → 65.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "64.2.0",
+  "version": "65.0.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -362,24 +362,19 @@ questions one at a time, answers your own questions about the plan or the diff,
 records what you decide in the steering file the way the step asks, and moves
 the process on only when you say so; a review you leave untouched signs off.
 While a step runs you can keep asking; requests for changes wait for the next
-rest. When the process finishes, Claude offers to squash it and open its pull
-request (or run `/gtd ship`: one commit under one pull request, see the
-[driver doc](docs/driver.md)); a process started for an issue ships with
-`Closes #N` on its pull request; a closed pull request whose branch was deleted
-from origin is left behind and a new one opens. A process can change hands at
-any gate: ask Claude to hand it off (or run `/gtd throw @dev`) and it opens a
-draft pull request assigned to them, and `/gtd catch <pr>` picks it up exactly
-where it waits, so whoever wrote the requirements can hand the build to someone
-else. `/gtd pr` brings a pull request's unresolved review threads into the
-review: each becomes a note in `.gtd/REVIEW.md` ticked "fix as suggested"
-(untick it for "won't fix" plus a reason, or your own answer), the review door
-fixes them in place, and each thread then gets a reply naming the fixing commit
-(or your reason) and is resolved. Ship, hand-off and throw answer at once and
-run in the background, with progress on the status line; they report by waking
-Claude, a toast, a transcript line and a push notification, and a failed push or
-`gh` call reports as a failure. While a ship or hand-off runs or is queued,
-`/gtd catch`, the doors, `/gtd <requirements>` and bare `/gtd` wait for its
-report. See
+rest. A process can change hands at any gate: ask Claude to hand it off (or run
+`/gtd throw @dev`) and it opens a draft pull request assigned to them, and
+`/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
+requirements can hand the build to someone else. `/gtd pr` brings a pull
+request's unresolved review threads into the review: each becomes a note in
+`.gtd/REVIEW.md` ticked "fix as suggested" (untick it for "won't fix" plus a
+reason, or your own answer), the review door fixes them in place, and each
+thread then gets a reply naming the fixing commit (or your reason) and is
+resolved. Hand-off and throw answer at once and run in the background, with
+progress on the status line; they report by waking Claude, a toast, a transcript
+line and a push notification, and a failed push or `gh` call reports as a
+failure. While a hand-off runs or is queued, `/gtd catch`, the doors,
+`/gtd <requirements>` and bare `/gtd` wait for its report. See
 [Inside Claude Code](https://github.com/pmelab/gtd/blob/main/docs/driver.md#inside-claude-code-the-gtd-mod).
 
 ### Then let an agent build your own
@@ -450,7 +445,8 @@ to answer, reopening it edits your last entry instead. Tap an already-answered
 question to leave a note on it; the agent may overturn the answer. A `findings`
 file lists its findings, each with a fix checkbox and, once ticked, an optional
 line of guidance; Done stays disabled while the file holds anything its gate
-would refuse. See
+would refuse. Done saves and leaves the server running; it exits once the
+worktree moves on to another step. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md)
 for its `ui:` settings.
 
@@ -498,15 +494,29 @@ or `.gitmodules` `ignore` say. Works in any git repository, no process needed.
 
 ## Process history
 
+Every process runs on the branch `gtd/<b>`, never on your branch `<b>`: starting
+creates it (or reuses one whose commits are on `<b>` or in a kept history ref;
+any other `gtd/<b>` is refused). A finished process switches HEAD back to `<b>`,
+and gtd moves `<b>` only when the workflow calls `ship()`, which squashes the
+process onto `<b>` as one commit (see
+[Shipping](docs/configuration.md#shipping)); what it committed after its last
+ship stays on `gtd/<b>`. `gtd abandon` switches back to `<b>` with the unshipped
+work uncommitted and deletes `gtd/<b>`; `gtd restore` recreates it. The closing
+commit records `Gtd-Branch: <b>`.
+
 When a process finishes, the landing that closes it also keeps the whole run
 behind a ref, `refs/gtd/history/<entry>`, so a squash or a deleted branch
-doesn't lose it. `/gtd ship` pushes this process's own ref to origin alongside
-the branch (never the others) and writes a `Gtd-History: <ref>` trailer on the
-squashed commit. The push is forced, so it replaces origin's copy of that one
-ref. If that push fails, the ship fails and nothing is squashed. Recover the
-full trail with `s=$(gtd history fetch --json=script) && sh -c "$s"`, then
+doesn't lose it. A `ship()` step writes the ref too, and names it in a
+`Gtd-History: <ref>` trailer on the commit it puts on `<b>`. Recover the full
+trail with `s=$(gtd history fetch --json=script) && sh -c "$s"`, then
 `gtd history show <ref>`.
 
+`gtd abandon` keeps `refs/gtd/history/<entry>` at the abandoned tip too; history
+lists and counts it like a finished one. Set `historyRemote` in the `config`
+export to a remote name and every finish, ship and abandon force-pushes its ref
+there; a failed push exits non-zero after the commit landed and prints the
+retry.
+
 ```sh
 gtd history list                 # one line per kept process
 gtd history show <ref>           # replay its steps, judge verdicts and approvals
@@ -585,7 +595,7 @@ gtd history judges --jsonl > judges.jsonl
 ```
 
 `gtd history fetch` only prints a fetch script; pipe it into `sh` to run it.
-Beyond that one ship push, refs are not pushed or fetched by default. The ref
+Without `historyRemote`, refs are not pushed or fetched by default. The ref
 holds every step commit, including steering files and code a later step removed,
 so anyone who can fetch the remote can read it. To share the rest:
 
@@ -596,7 +606,7 @@ git config --add remote.origin.fetch 'refs/gtd/history/*:refs/gtd/history/*'
 
 The second line makes every plain `git fetch` include them. It has no leading
 `+`, so a conflicting local ref fails instead of being overwritten: after a
-forced `/gtd ship` push, a clone holding the old tip deletes its local ref
+forced `historyRemote` push, a clone holding the old tip deletes its local ref
 (`git update-ref -d <ref>`) and fetches again.
 
 A step declared with `keep: true` files its turn under `refs/gtd/kept/` instead

package/claude/hooks/assist.ts

@@ -5,7 +5,7 @@
 
 import type { Stop } from "../types"
 import { RELOAD_CUT_SCRIPT } from "./wording"
-import type { Shipped } from "./ship"
+import type { Done } from "./git"
 import { JOB_NAME, TOOL } from "./tools"
 import type { JobName } from "./tools"
 
@@ -23,16 +23,12 @@ export type Wake = {
   isRepeat?: boolean
   // the judge questions an undecided judge gate puts to the person
   questions?: Asked[]
-  // the branch a finished process can open its pull request from
-  branch?: string
 }
 
-// No wake for a stop the person asked for; a finished process wakes only
-// when it has a pull request to offer.
-export function wakes(stop: Stop, branch: string | undefined): boolean {
+// No wake for a finished process or a stop the person asked for.
+export function wakes(stop: Stop): boolean {
   if (stop.kind === "stopped") return stop.text === RELOAD_CUT_SCRIPT
-  if (stop.kind === "done") return branch !== undefined
-  return true
+  return stop.kind !== "done"
 }
 
 const step = (s: Stop) => s.label ?? s.state ?? "the current step"
@@ -116,23 +112,9 @@ function trouble(w: Wake) {
   ]
 }
 
-function finished(w: Wake) {
-  return [
-    `gtd finished the process on branch ${w.branch}.`,
-    `Tell the person in two or three lines what was built (read the branch's commits), then ask whether to squash it and open its pull request(s). On yes, call ${TOOL.ship}.`,
-  ]
-}
-
 export function wakePrompt(w: Wake): string {
   const { stop } = w
-  const body =
-    stop.kind === "done"
-      ? finished(w)
-      : stop.kind === "gate"
-        ? stop.isJudge
-          ? judged(w)
-          : gate(w)
-        : trouble(w)
+  const body = stop.kind === "gate" ? (stop.isJudge ? judged(w) : gate(w)) : trouble(w)
   const notes = w.notes?.length
     ? [
         `While gtd ran, the person asked for the following. Fold each in now in the way this step allows, or tell them why it does not fit here:\n${w.notes.map((n) => `- ${n}`).join("\n")}`,
@@ -142,9 +124,9 @@ export function wakePrompt(w: Wake): string {
   return [...body, ...notes, RULES, extras].join("\n\n")
 }
 
-// The wake after a background ship or hand-off ended. It must not forbid further work:
+// The wake after a background hand-off ended. It must not forbid further work:
 // an agent with standing instructions (a review loop, a CI watch) would go idle.
-export function jobPrompt(job: JobName, outcome: Shipped): string {
+export function jobPrompt(job: JobName, outcome: Done): string {
   const name = JOB_NAME[job]
   if (outcome.ok) {
     return [
@@ -153,17 +135,9 @@ export function jobPrompt(job: JobName, outcome: Shipped): string {
       "Relay the result to the person in a line or two, with any link in it; then continue with any work the person already asked for.",
     ].join("\n\n")
   }
-  const lines = [
+  return [
     `The ${name} the person asked for failed. gtd reports the failed step:`,
     fence(outcome.text),
-  ]
-  if (job === "ship") {
-    lines.push(
-      `If the commits were already squashed, they stay squashed: running /gtd ship again pushes the already-squashed branch.`,
-    )
-  }
-  lines.push(
     "Tell the person what failed in plain words and what to try. Do not retry it yourself.",
-  )
-  return lines.join("\n\n")
+  ].join("\n\n")
 }

package/claude/hooks/doors.ts

@@ -2,7 +2,7 @@
 // prints the script that starts one; running it is the driver's job, as with
 // every git write gtd plans. The mod hardcodes no door: it asks gtd.
 
-import type { ShipIo, Shipped } from "./ship"
+import type { GitIo, Done } from "./git"
 
 export type Door = {
   name: string
@@ -10,12 +10,12 @@ export type Door = {
   args: { name: string; optional: boolean }[]
 }
 
-const fail = (text: string): Shipped => ({ ok: false, text })
+const fail = (text: string): Done => ({ ok: false, text })
 
 type Startable = { kind: "workflow"; name: string } | ({ kind: "door" } & Door)
 
 // Every door the repository offers; none when gtd cannot say.
-export async function doors(io: ShipIo): Promise<Door[]> {
+export async function doors(io: GitIo): Promise<Door[]> {
   const listed = await io.run(["gtd", "start", "--json"])
   if (listed.code !== 0) return []
   try {
@@ -27,7 +27,7 @@ export async function doors(io: ShipIo): Promise<Door[]> {
   }
 }
 
-export async function enter(io: ShipIo, name: string, args: string[]): Promise<Shipped> {
+export async function enter(io: GitIo, name: string, args: string[]): Promise<Done> {
   const argv = ["gtd", "start", name, ...args]
   const planned = await io.run(argv)
   if (planned.code !== 0)

package/claude/hooks/git.ts

@@ -0,0 +1,56 @@
+export type Ran = { code: number; out: string; err: string }
+
+export type GitIo = {
+  // argv runs in the repository root; stdin is the child's whole input
+  run(argv: string[], stdin?: string): Promise<Ran>
+  log(line: string): void
+}
+
+export type Done = { ok: boolean; text: string }
+
+// A rejection becomes `killed`, so the caller can tell a timeout from a refused
+// push. Relies on the host's process runner rejecting at its timeout; a spawn
+// failure lands here too. Only pushes: any other crashed read must abort, not
+// pass as an answer.
+const attempt = async (io: GitIo, argv: string[]): Promise<Ran & { killed: boolean }> => {
+  try {
+    return { ...(await io.run(argv)), killed: false }
+  } catch (err) {
+    return { code: 1, out: "", err: err instanceof Error ? err.message : String(err), killed: true }
+  }
+}
+
+export async function defaultBranch(git: (...args: string[]) => Promise<string>) {
+  const head = await git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+  return head.replace(/^origin\//, "") || "main"
+}
+
+// A pull request describes what the remote branch holds. A rewritten branch
+// needs --force-with-lease on an existing origin/<branch>. `fresh`: origin
+// lacks the branch, so any tracking ref is stale. Returns why the push failed,
+// or nothing.
+export async function pushBranch(io: GitIo, branch: string, fresh = false) {
+  const ok = async (...args: string[]) => (await io.run(["git", ...args])).code === 0
+  const push = async (args: string[], failure: string) => {
+    const r = await attempt(io, ["git", "push", ...args])
+    if (r.killed)
+      return `git push of ${branch} did not finish; nothing was lost. Retry without fetching.\n${r.err}`.trimEnd()
+    if (r.code !== 0) return `${failure}\n${r.err}`.trimEnd()
+    return undefined
+  }
+  if (fresh || !(await ok("rev-parse", "--verify", "--quiet", `origin/${branch}`))) {
+    io.log(`Pushing ${branch} to origin…`)
+    return push(["--set-upstream", "origin", branch], "git push failed.")
+  }
+  if (!(await ok("merge-base", "--is-ancestor", "HEAD", `origin/${branch}`))) {
+    io.log(`Pushing ${branch} to origin…`)
+    return push(
+      ["--force-with-lease", "origin", branch],
+      `git push failed: origin/${branch} moved. Fetch and reconcile first.`,
+    )
+  }
+  return undefined
+}
+
+// Marks a draft pull request `/gtd throw` opened for a hand-off.
+export const THROWN = "<!-- gtd:thrown -->"

package/claude/hooks/handoff.ts

@@ -2,12 +2,12 @@
 // pushing the branch and telling them. `throw` opens (or refreshes) a draft
 // pull request for the hand-off; `catch` checks it out wherever it was thrown.
 
-import { defaultBranch, pushBranch, THROWN } from "./ship"
-import type { ShipIo, Shipped } from "./ship"
+import { defaultBranch, pushBranch, THROWN } from "./git"
+import type { GitIo, Done } from "./git"
 
 export type Rest = { state?: string; label?: string; content?: string; isIdle: boolean }
 
-const fail = (text: string): Shipped => ({ ok: false, text })
+const fail = (text: string): Done => ({ ok: false, text })
 
 type Pr = {
   number: number
@@ -18,11 +18,11 @@ type Pr = {
 }
 
 export async function throwTo(
-  io: ShipIo,
+  io: GitIo,
   rest: Rest,
   target: string | undefined,
   now: string,
-): Promise<Shipped> {
+): Promise<Done> {
   if (rest.isIdle) return fail("Nothing is in progress, so there is nothing to throw.")
   // Only landed state travels: an edit still in the tree is half an answer.
   if ((await io.run(["git", "status", "--porcelain"])).out.trim()) {
@@ -59,7 +59,7 @@ export async function throwTo(
 // The catcher checks out what origin holds, so a throw describing local HEAD
 // must not leave origin elsewhere: fetch first, a stale tracking ref can hide
 // a teammate's commits or a rewind. Returns why the throw refuses, or nothing.
-async function remoteAhead(io: ShipIo, branch: string) {
+async function remoteAhead(io: GitIo, branch: string) {
   const ok = async (...args: string[]) => (await io.run(["git", ...args])).code === 0
   if (!(await ok("fetch", "--prune", "origin"))) return "git fetch failed."
   if (!(await ok("rev-parse", "--verify", "--quiet", `origin/${branch}`))) return undefined
@@ -69,7 +69,7 @@ async function remoteAhead(io: ShipIo, branch: string) {
 
 // The branch to throw, moving the process off the default branch onto a new
 // one when it sits there; a string is why that failed.
-async function throwBranch(io: ShipIo, now: string) {
+async function throwBranch(io: GitIo, now: string) {
   const git = async (...args: string[]) => (await io.run(["git", ...args])).out.trim()
   const branch = await git("rev-parse", "--abbrev-ref", "HEAD")
   if (!branch || branch === "HEAD") return "Detached HEAD: there is no branch to throw."
@@ -103,7 +103,7 @@ ${content.slice(0, 6000)}
 // Opens the hand-off's draft, or refreshes a thrown one; a string is why that
 // failed.
 async function draft(
-  io: ShipIo,
+  io: GitIo,
   branch: string,
   base: string,
   rest: Rest,
@@ -144,7 +144,7 @@ async function draft(
   const pr = JSON.parse(view.out) as Pr
   if (pr.state !== "OPEN") return `The pull request for ${branch} is ${pr.state}, not open.`
   // A pull request someone opened for review keeps its own description and
-  // stays ready: only ship marks a draft ready again, and only a thrown one.
+  // stays ready: only a thrown one is rewritten and made a draft again.
   if (pr.body?.includes(THROWN)) {
     const edited = await io.run(["gh", "pr", "edit", String(pr.number), "--body-file", "-"], body)
     if (edited.code !== 0) return `gh pr edit failed; the pull request is unchanged.\n${edited.err}`
@@ -155,7 +155,7 @@ async function draft(
   return pr
 }
 
-async function assign(io: ShipIo, pr: Pr, handle: string) {
+async function assign(io: GitIo, pr: Pr, handle: string) {
   const stale = (pr.assignees ?? []).map((a) => a.login).filter((login) => login !== handle)
   const args = ["gh", "pr", "edit", String(pr.number), "--add-assignee", handle]
   for (const login of stale) args.push("--remove-assignee", login)
@@ -165,7 +165,7 @@ async function assign(io: ShipIo, pr: Pr, handle: string) {
     : `Thrown to ${pr.url}, but assigning @${handle} failed.\n${assigned.err}`
 }
 
-export async function catchFrom(io: ShipIo, ref: string): Promise<Shipped> {
+export async function catchFrom(io: GitIo, ref: string): Promise<Done> {
   if ((await io.run(["git", "status", "--porcelain"])).out.trim()) {
     return fail("The working tree has edits. Commit or stash them before catching.")
   }

package/claude/hooks/jobs.ts

@@ -1,8 +1,8 @@
-// The one background slot ship and hand-off share: both push the branch, so
-// two at once would race. No global deadline on purpose: a deadline that freed
+// The one background slot for a hand-off: it pushes the branch, so two at
+// once would race. No global deadline on purpose: a deadline that freed
 // the slot while the work still ran would let a second push overwrite the first.
 
-import type { Shipped } from "./ship"
+import type { Done } from "./git"
 import type { JobName } from "./tools"
 import { JOB_NAME } from "./tools"
 
@@ -13,9 +13,9 @@ export type Jobs = {
   // running or queued.
   start(
     job: JobName,
-    work: () => Promise<Shipped>,
+    work: () => Promise<Done>,
     isInTurn: boolean,
-    done: (outcome: Shipped) => Promise<void>,
+    done: (outcome: Done) => Promise<void>,
   ): string
   flush(): void
   busy(): JobName | undefined
@@ -25,8 +25,8 @@ export function jobs(): Jobs {
   let current:
     | {
         job: JobName
-        work: () => Promise<Shipped>
-        done: (outcome: Shipped) => Promise<void>
+        work: () => Promise<Done>
+        done: (outcome: Done) => Promise<void>
         isRunning: boolean
       }
     | undefined
@@ -36,7 +36,7 @@ export function jobs(): Jobs {
     if (!slot || slot.isRunning) return
     slot.isRunning = true
     void (async () => {
-      let outcome: Shipped
+      let outcome: Done
       try {
         outcome = await slot.work()
       } catch (err) {

package/claude/hooks/pr.ts

@@ -4,8 +4,8 @@
 // reads and writes the threads, and gtd only sees the notes.
 
 import type { PrFeedback, PrThread } from "../types"
-import { pushBranch } from "./ship"
-import type { ShipIo, Shipped } from "./ship"
+import { pushBranch } from "./git"
+import type { GitIo, Done } from "./git"
 
 export const REVIEW_FILE = ".gtd/REVIEW.md"
 
@@ -27,9 +27,9 @@ const TAG = /\(thread ([A-Za-z0-9_=-]+)\)\s*$/
 const LEAD = "Tick exactly one:"
 const PLACEHOLDER = "_your answer_"
 
-const fail = (text: string): Shipped => ({ ok: false, text })
+const fail = (text: string): Done => ({ ok: false, text })
 
-export async function currentPr(io: ShipIo): Promise<Pr | string> {
+export async function currentPr(io: GitIo): Promise<Pr | string> {
   const branch = (await io.run(["git", "rev-parse", "--abbrev-ref", "HEAD"])).out.trim()
   const v = await io.run(["gh", "pr", "view", "--json", "number,url"])
   if (v.code !== 0) return `gh pr view failed: ${v.err.trim()}`
@@ -69,7 +69,7 @@ type ThreadNode = {
   comments: { nodes: { author: { login: string } | null; body: string; url: string }[] }
 }
 
-export async function unresolvedThreads(io: ShipIo, pr: Pr): Promise<Thread[] | string> {
+export async function unresolvedThreads(io: GitIo, pr: Pr): Promise<Thread[] | string> {
   const r = await io.run([
     "gh",
     "api",
@@ -226,7 +226,7 @@ export function missingReasons(review: string) {
 
 // The first commit since `since` whose review answers any of `ids`: the gate
 // that decided them. Undefined while none has landed.
-export async function decided(io: ShipIo, since: string, ids: readonly string[]) {
+export async function decided(io: GitIo, since: string, ids: readonly string[]) {
   // A reset or rebase since the import leaves nothing to find the gate in.
   if ((await io.run(["git", "merge-base", "--is-ancestor", since, "HEAD"])).code !== 0)
     return "gone"
@@ -279,11 +279,11 @@ const RESOLVE = `mutation($thread: ID!) {
 // to each answered thread and resolves it. The code commits after `gate` are
 // the fixes; a thread that fails is named and left open.
 export async function reply(
-  io: ShipIo,
+  io: GitIo,
   host: string,
   gate: string,
   decidedAnswers: readonly Answer[],
-): Promise<Shipped & { isPushed: boolean }> {
+): Promise<Done & { isPushed: boolean }> {
   const branch = (await io.run(["git", "rev-parse", "--abbrev-ref", "HEAD"])).out.trim()
   const pushed = await pushBranch(io, branch)
   if (pushed) return { ...fail(pushed), isPushed: false }