@pmelab/gtd 27.7.0 → 27.7.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -324,18 +324,26 @@ Then, in any repository:
 /gtd Add a --json flag to the export command
 ```
 
-That starts a process from your requirements and drives it until it needs you.
-`/gtd fix` and `/gtd review [base]` take the two doors described below. At every
-human rest Claude itself takes over: it walks you through the open 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. 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 into one commit and open its pull request (or run `/gtd ship`). 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 architecture to someone else. See
+That starts a process from your requirements and drives it until it needs you. A
+long, multi-line requirements paste still starts a process; if Claude Code never
+expanded the paste, gtd says it could not read it, and you write the
+requirements to `.gtd/TODO.md` and run `/gtd`. `/gtd fix` and
+`/gtd review [base]` take the two doors described below. At every human rest
+Claude itself takes over: it walks you through the open 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 into one commit and open its pull request
+(or run `/gtd ship`). 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 architecture to someone else. 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
 [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
@@ -577,6 +585,8 @@ Two more bundled workflows retire a release flag:
 `gtd --workflow cleanup --var flag=<name>` removes it afterwards. See
 [Feature flags](docs/configuration.md#rolling-out-and-cleaning-up-a-release-flag).
 
+The delivery model these workflows implement: [Delivery model](SDLC.md).
+
 ## Checking a range for stray files
 
 ```sh

package/claude/hooks/assist.ts

@@ -5,7 +5,9 @@
 
 import type { Stop } from "../types"
 import { RELOAD_CUT_SCRIPT } from "./wording"
-import { TOOL } from "./tools"
+import type { Shipped } from "./ship"
+import { JOB_NAME, TOOL } from "./tools"
+import type { JobName } from "./tools"
 
 export type Asked = {
   id: string
@@ -35,7 +37,13 @@ export function wakes(stop: Stop, branch: string | undefined): boolean {
 
 const step = (s: Stop) => s.label ?? s.state ?? "the current step"
 
-const fence = (text: string) => `~~~~text\n${text.trim()}\n~~~~`
+// The text can come from commit messages anyone on the branch wrote: the fence
+// is longer than any run of ~ inside it, so the text cannot close it early.
+const fence = (text: string) => {
+  const body = text.trim()
+  const bar = "~".repeat(Math.max(4, ...[...body.matchAll(/~+/g)].map((m) => m[0].length + 1)))
+  return `${bar}text\n${body}\n${bar}`
+}
 
 const RULES = `Ground rules:
 - gtd decides what happens next. Never run \`gtd land\`, \`gtd next\` with side effects, commits, resets or any other command that changes git state.
@@ -133,3 +141,28 @@ export function wakePrompt(w: Wake): string {
   const extras = `Only when the person asks: ${TOOL.handoff} hands the process to someone else, ${TOOL.browser} opens gtd's browser view of this step.`
   return [...body, ...notes, RULES, extras].join("\n\n")
 }
+
+// The wake after a background ship or hand-off ended: the model only relays it.
+export function jobPrompt(job: JobName, outcome: Shipped): string {
+  const name = JOB_NAME[job]
+  if (outcome.ok) {
+    return [
+      `The ${name} the person asked for finished. gtd's report:`,
+      fence(outcome.text),
+      "Relay the result to the person in a line or two, with any link in it. Do nothing else.",
+    ].join("\n\n")
+  }
+  const lines = [
+    `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")
+}

package/claude/hooks/delegate.ts

@@ -0,0 +1,22 @@
+export type AnswerIo = {
+  ended: Promise<{ ok: boolean }>
+  deadline: Promise<unknown>
+  read(): Promise<string>
+  remove(): Promise<unknown>
+}
+
+export async function collectAnswer(io: AnswerIo): Promise<string | undefined> {
+  const ended = await Promise.race([io.ended, io.deadline.then(() => undefined)])
+  if (!ended) {
+    // The agent may still write the file: remove it only once its turn ends.
+    void io.ended.then(io.remove).catch(() => undefined)
+    return undefined
+  }
+  try {
+    return ended.ok ? await io.read() : undefined
+  } catch {
+    return undefined
+  } finally {
+    await io.remove()
+  }
+}

package/claude/hooks/handoff.ts

@@ -43,11 +43,17 @@ export async function throwTo(
     if (assigned) return fail(assigned)
   }
   const to = handle ? `to @${handle}` : "to anyone"
-  await io.run(
+  const commented = await io.run(
     ["gh", "pr", "comment", String(pr.number), "--body-file", "-"],
     `Thrown ${to} at **${at}**. Catch it with \`/gtd catch ${on.branch}\`.\n`,
   )
-  return { ok: true, text: `Thrown ${to}: ${pr.url}` }
+  // The hand-off already happened: failing here would keep the run open locally
+  // while the pull request is someone else's.
+  const warning =
+    commented.code === 0
+      ? ""
+      : `\nWarning: gh pr comment failed; no catch hint was posted.\n${commented.err}`
+  return { ok: true, text: `Thrown ${to}: ${pr.url}${warning}` }
 }
 
 // The catcher checks out what origin holds, so a throw describing local HEAD
@@ -141,8 +147,11 @@ async function draft(
   // 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.
   if (pr.body?.includes(THROWN)) {
-    await io.run(["gh", "pr", "edit", String(pr.number), "--body-file", "-"], body)
-    await io.run(["gh", "pr", "ready", String(pr.number), "--undo"])
+    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}`
+    const undone = await io.run(["gh", "pr", "ready", String(pr.number), "--undo"])
+    if (undone.code !== 0)
+      return `gh pr ready --undo failed; ${pr.url} is not a draft again.\n${undone.err}`
   }
   return pr
 }

package/claude/hooks/jobs.ts

@@ -0,0 +1,67 @@
+// 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 slot while the work still ran would let a second push overwrite the first.
+
+import type { Shipped } from "./ship"
+import type { JobName } from "./tools"
+import { JOB_NAME } from "./tools"
+
+export type Jobs = {
+  // Claims the slot now; `work` starts at once or, `isInTurn`, at the next
+  // `flush`. `done` runs when it ends, either way, and owns the job's effect
+  // and report. Answers at once: the started text, or a refusal when a job is
+  // running or queued.
+  start(
+    job: JobName,
+    work: () => Promise<Shipped>,
+    isInTurn: boolean,
+    done: (outcome: Shipped) => Promise<void>,
+  ): string
+  flush(): void
+  busy(): JobName | undefined
+}
+
+export function jobs(): Jobs {
+  let current:
+    | {
+        job: JobName
+        work: () => Promise<Shipped>
+        done: (outcome: Shipped) => Promise<void>
+        isRunning: boolean
+      }
+    | undefined
+
+  const launch = () => {
+    const slot = current
+    if (!slot || slot.isRunning) return
+    slot.isRunning = true
+    void (async () => {
+      let outcome: Shipped
+      try {
+        outcome = await slot.work()
+      } catch (err) {
+        outcome = { ok: false, text: err instanceof Error ? err.message : String(err) }
+      } finally {
+        current = undefined
+      }
+      try {
+        await slot.done(outcome)
+      } catch {
+        // a failed report must not become an unhandled rejection
+      }
+    })()
+  }
+
+  return {
+    start(job, work, isInTurn, done) {
+      if (current) {
+        return `A ${JOB_NAME[current.job]} is already being prepared; wait for its report.`
+      }
+      current = { job, work, done, isRunning: false }
+      if (!isInTurn) launch()
+      return `The ${JOB_NAME[job]} has started in the background; its outcome is reported here when it ends.`
+    },
+    flush: launch,
+    busy: () => current?.job,
+  }
+}

package/claude/hooks/paste.ts

@@ -0,0 +1,17 @@
+export type Pasted = { arg: string } | { lost: string }
+
+const PLACEHOLDER = /\[Pasted text #\d+[^\]]*\]/
+
+// The mod cannot recover an unexpanded paste: Claude Code's paste cache is keyed
+// by a hash it does not expose.
+export function pastedCommand(text: string): Pasted | undefined {
+  const m = /^\/gtd\s+([\s\S]*)$/.exec(text)
+  const arg = m?.[1]?.trim()
+  if (!arg) return undefined
+  if (PLACEHOLDER.test(arg)) {
+    return {
+      lost: "The pasted requirements did not arrive whole. Write them to .gtd/TODO.md and run /gtd.",
+    }
+  }
+  return { arg }
+}

package/claude/hooks/register.tsx

@@ -4,22 +4,28 @@ import type { EngineInterface, Register } from "claude-code"
 import type { Run, Stop } from "../types"
 import { accessDenial, mainDenial } from "./access"
 import type { AccessDef } from "./access"
-import { wakePrompt, wakes } from "./assist"
+import { jobPrompt, wakePrompt, wakes } from "./assist"
 import { afterReload, drive, isTrue } from "./drive"
 import type { Io, Opening, Turn, TurnEnd } from "./drive"
 import { doors, enter } from "./doors"
 import { subagentModel } from "./models"
+import { pastedCommand } from "./paste"
 import { personaSpec, resumable } from "./persona"
 import { JUDGE_SYSTEM, judgePrompt, judgeQuestions, judgeRunEnv, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
 import { catchFrom, throwTo } from "./handoff"
+import { jobs } from "./jobs"
 import { documents, readDocument } from "./schema"
 import { READ_ONLY_GIT, ship } from "./ship"
-import type { ShipIo } from "./ship"
-import { decideContinue, restId, TOOLS } from "./tools"
+import type { Shipped, ShipIo } from "./ship"
+import { collectAnswer } from "./delegate"
+import { decideCommand, decideContinue, decideJob, restId, TOOLS } from "./tools"
+import type { JobName } from "./tools"
 import {
   beatLine,
   headline,
+  jobHeadline,
+  jobPushText,
   pushText,
   restartLine,
   RELOAD_CUT_SCRIPT,
@@ -52,7 +58,6 @@ let stepStartedAt = Date.now()
 // Set before the first await of `start`, so two Continue presses arriving
 // together cannot both pass the isRunning check and start two drivers.
 let isDriving = false
-let isShipping = false
 // bumped by every stop, so a queued continue that was mid-check sees it
 let stopCount = 0
 // subagents answering into a file: what each may touch (see tool.call)
@@ -219,7 +224,7 @@ async function head($: $) {
 }
 
 async function start($: $, opening: Opening = {}) {
-  if (isDriving) return
+  if (isDriving || background.busy()) return
   isDriving = true
   closeUi()
   moveOn($)
@@ -371,45 +376,75 @@ async function browse($: $) {
 
 // A gate is news even when nobody watches the terminal: a push reaches the
 // phone over Remote Control, and the engine drops it while the person is here.
+const repoName = () => root.split("/").pop() ?? "gtd"
+
 async function push($: $, stop: Stop, url?: string) {
-  const repo = root.split("/").pop() ?? "gtd"
+  await notify($, pushText(stop, repoName(), url))
+}
+
+async function notify($: $, message: string) {
   try {
-    await $.tool.call({
-      tool: "PushNotification",
-      message: pushText(stop, repo, url),
-      status: "proactive",
-    })
+    await $.tool.call({ tool: "PushNotification", message, status: "proactive" })
   } catch {
     // no push channel: the dialog and the band still say it
   }
 }
 
-async function throwNow($: $, target: string | undefined) {
-  if ((await read($, run)).isRunning) return "Stop the loop first: /gtd stop."
-  closeUi()
-  moveOn($)
-  const b = await docs($).next()
-  $.ui.status("handing off…")
-  const rest = {
-    state: b.state,
-    label: b.label,
-    content: b.content,
-    isIdle: isTrue(b.idle),
-  }
-  const thrown = await throwTo(shipIo($), rest, target, new Date().toISOString()).catch(
-    (err: unknown) => ({ ok: false, text: String(err) }),
+const background = jobs()
+
+// A job asked from the model's tool call waits for that turn to end; one asked
+// from the command starts right after, off the hook, so the command answers in
+// budget. Either way the slot is claimed now, with the job's own effect.
+function startJob(
+  $: $,
+  job: JobName,
+  isInTurn: boolean,
+  work: () => Promise<Shipped>,
+  then?: (outcome: Shipped) => Promise<void>,
+) {
+  const answer = background.start(job, work, true, async (outcome) => {
+    if (then) await then(outcome)
+    $.ui.status(undefined)
+    for (const line of outcome.text.split("\n")) $.ui.log(line)
+    $.ui.toast(jobHeadline(job, outcome))
+    await notify($, jobPushText(job, outcome, repoName()))
+    const text = jobPrompt(job, outcome)
+    $.clock.after(0, () => void $.prompt.submit({ text }))
+  })
+  if (!isInTurn) $.clock.after(0, () => background.flush())
+  return answer
+}
+
+async function throwNow($: $, target: string | undefined, isInTurn: boolean) {
+  const refused = decideJob(await read($, run), "handoff")
+  if (refused) return refused
+  return startJob(
+    $,
+    "handoff",
+    isInTurn,
+    async () => {
+      closeUi()
+      moveOn($)
+      const b = await docs($).next()
+      $.ui.status("handing off…")
+      const rest = {
+        state: b.state,
+        label: b.label,
+        content: b.content,
+        isIdle: isTrue(b.idle),
+      }
+      return throwTo(shipIo($), rest, target, new Date().toISOString())
+    },
+    async (thrown) => {
+      if (!thrown.ok) return
+      await update($, run, (r) => ({
+        ...r,
+        url: undefined,
+        uiNote: undefined,
+        stop: { kind: "stopped" as const, text: thrown.text },
+      }))
+    },
   )
-  $.ui.status(undefined)
-  for (const line of thrown.text.split("\n")) $.ui.log(line)
-  if (thrown.ok) {
-    await update($, run, (r) => ({
-      ...r,
-      url: undefined,
-      uiNote: undefined,
-      stop: { kind: "stopped" as const, text: thrown.text },
-    }))
-  }
-  return thrown.text
 }
 
 async function enterNow($: $, door: string, args: string[]) {
@@ -499,15 +534,14 @@ async function delegate($: $, who: Delegate, prompt: string, model: string, deli
   if (!id) return undefined
   ours.add(id)
   delegates.set(id, { file, mayRun: who.mayRun })
-  const ended = await turnEnd(id)
-  delegates.delete(id)
-  try {
-    return ended.ok ? await $.fs.read(file) : undefined
-  } catch {
-    return undefined
-  } finally {
-    await $.process.run(["rm", "-f", file])
-  }
+  // A timed-out agent may still be running: it keeps its tool limits until its
+  // turn ends, where turn.complete drops them.
+  return collectAnswer({
+    ended: turnEnd(id),
+    deadline: $.clock.sleep(TEN_MINUTES),
+    read: () => $.fs.read(file),
+    remove: () => $.process.run(["rm", "-f", file]),
+  })
 }
 
 async function writer($: $, prompt: string) {
@@ -544,25 +578,28 @@ function shipIo($: $): ShipIo {
     complete: (prompt) => writer($, prompt),
     log: (line) => {
       for (const l of line.split("\n")) $.ui.log(l)
+      if (background.busy()) $.ui.status(line.split("\n")[0]!)
     },
     today: () => new Date().toISOString().slice(0, 10),
   }
 }
 
-async function shipNow($: $, isDry: boolean) {
-  if (isShipping) return "A pull request is already being prepared."
-  isShipping = true
-  await dismiss($)
-  $.ui.status(isDry ? "previewing the pull request…" : "opening the pull request…")
-  const shipped = await ship(shipIo($), isDry).catch((err: unknown) => ({
-    ok: false,
-    text: String(err),
-  }))
-  isShipping = false
-  $.ui.status(undefined)
-  for (const line of shipped.text.split("\n")) $.ui.log(line)
-  $.ui.toast(shipped.ok ? "pull request ready" : "opening the pull request failed")
-  return shipped.text
+async function shipNow($: $, isDry: boolean, isInTurn: boolean) {
+  const refused = decideJob(await read($, run), "ship")
+  if (refused) return refused
+  return startJob(
+    $,
+    "ship",
+    isInTurn,
+    async () => {
+      $.ui.status(isDry ? "previewing the pull request…" : "opening the pull request…")
+      return ship(shipIo($), isDry)
+    },
+    async (shipped) => {
+      // a failed ship leaves the run as it was; a dry run changes nothing
+      if (shipped.ok && !isDry) await dismiss($)
+    },
+  )
 }
 
 // Turns a missing CLI or a wrong directory into an instruction, not a stack trace.
@@ -641,6 +678,7 @@ async function proceed(
   const go = await decideContinue(r, rest, verdicts, {
     current: () => currentRest($, r.stop?.state),
     validate: () => validateRest($),
+    busy: background.busy(),
     judgment: async () => {
       const doc = await gtd($, ["judge", "--json"]).catch(() => undefined)
       return doc === undefined ? undefined : readDocument<Judgment>("judge --json", doc)
@@ -765,6 +803,8 @@ async function stopNow($: $) {
 // `/gtd [verb] …`; anything that is not a verb is a new process's requirements.
 async function command($: $, arg: string): Promise<string | undefined> {
   if (arg === "stop") return stopNow($)
+  const busy = decideCommand(arg, background.busy())
+  if (busy) return busy
   const problem = await preflight($)
   if (problem) return problem
   const [verb = "", ...rest] = arg.split(/\s+/)
@@ -772,7 +812,7 @@ async function command($: $, arg: string): Promise<string | undefined> {
     case "status":
       return gtd($, ["next"])
     case "throw":
-      return throwNow($, rest[0])
+      return throwNow($, rest[0], false)
     case "ui":
       return browse($)
     case "catch":
@@ -780,7 +820,7 @@ async function command($: $, arg: string): Promise<string | undefined> {
         ? catchNow($, rest[0])
         : "Name the pull request or branch: /gtd catch <number|branch>."
     case "ship":
-      return shipNow($, rest[0] === "-n" || rest[0] === "--dry-run")
+      return shipNow($, rest[0] === "-n" || rest[0] === "--dry-run", false)
     case "":
       return resume($)
     default:
@@ -912,10 +952,14 @@ export const register: Register = (on) => {
   }).catch(($, e, next) => ({ text: next.error.message }))
 
   on("turn.complete", ($, e, next) => {
-    if (!e.agentId) void launchPending($)
+    if (!e.agentId) {
+      background.flush()
+      void launchPending($)
+    }
     if (e.agentId && ours.has(e.agentId)) {
       const end: TurnEnd =
         e.reason === "answer" ? { ok: true } : { ok: false, why: `agent turn ended: ${e.reason}` }
+      delegates.delete(e.agentId)
       const resolve = waiting.get(e.agentId)
       waiting.delete(e.agentId)
       if (resolve) resolve(end)
@@ -943,7 +987,24 @@ export const register: Register = (on) => {
   // A subagent's hand-back arrives as a prompt to the main session, whose model
   // would then act on it. gtd reads the turn's result from git instead.
   on("prompt.submit", async ($, e, next) => {
-    if (!e.origin || e.origin.kind === "composer" || e.origin.kind === "bridge") return next(e)
+    if (!e.origin || e.origin.kind === "composer" || e.origin.kind === "bridge") {
+      const pasted = pastedCommand(e.text)
+      if (!pasted) return next(e)
+      // Off the hook: preflight may install gtd's runtime and outlast its budget.
+      const say = (text: string) => {
+        for (const line of text.split("\n")) $.ui.log(line)
+        $.ui.toast(text.split("\n")[0]!)
+      }
+      if ("lost" in pasted) say(pasted.lost)
+      else {
+        $.clock.after(0, () => {
+          void command($, pasted.arg)
+            .then((text) => text && say(text))
+            .catch((err) => say(err instanceof Error ? err.message : String(err)))
+        })
+      }
+      return { drop: "gtd took the command" }
+    }
     if ([...ours].some((id) => e.text.includes(`from="${id}"`))) {
       return { drop: DROPPED }
     }
@@ -957,10 +1018,10 @@ export const register: Register = (on) => {
     answer(await note($, String(e.text ?? "")), true),
   )
   on("tool.call", { tool: "mcp__gtd__handoff" }, async ($, e) =>
-    answer(await throwNow($, typeof e.to === "string" && e.to ? e.to : undefined), true),
+    answer(await throwNow($, typeof e.to === "string" && e.to ? e.to : undefined, true), true),
   )
   on("tool.call", { tool: "mcp__gtd__ship" }, async ($, e) =>
-    answer(await shipNow($, e.dryRun === true), true),
+    answer(await shipNow($, e.dryRun === true, true), true),
   )
   on("tool.call", { tool: "mcp__gtd__browser" }, async ($) => answer(await browse($), true))
 

package/claude/hooks/ship.ts

@@ -334,13 +334,18 @@ ${await git("diff", "--stat", `${mergeBase}..HEAD`)}`
   const head = await git("rev-parse", "HEAD")
   if (thrown) {
     const n = String(thrown.number)
+    // Ready first: a failure here leaves the THROWN marker, so a retry comes back.
+    const ready = await io.run(["gh", "pr", "ready", n])
+    if (ready.code !== 0)
+      return fail(`gh pr ready failed; ${thrown.url} is unchanged.\n${ready.err}`)
     const edited = await io.run(
       ["gh", "pr", "edit", n, "--title", title, "--body-file", "-"],
       body + "\n",
     )
     if (edited.code !== 0)
-      return fail(`gh pr edit failed; the pull request is unchanged.\n${edited.err}`)
-    await io.run(["gh", "pr", "ready", n])
+      return fail(
+        `gh pr edit failed; ${thrown.url} is marked ready but keeps its thrown title and description.\n${edited.err}`,
+      )
     await io.run(["git", "config", "--local", `branch.${branch}.prSyncHead`, head])
     return { ok: true, text: `Rewrote ${thrown.url} and marked it ready for review.` }
   }

package/claude/hooks/tools.ts

@@ -71,6 +71,37 @@ export type ContinueIo = {
   // the rest's own `gtd validate` script, run; ok when there is nothing to check
   validate(): Promise<{ ok: boolean; out: string }>
   judgment(): Promise<Judgment | undefined>
+  // a ship or hand-off running or queued: it writes the tree the driver would
+  busy?: JobName
+}
+
+export type JobName = "ship" | "handoff"
+
+export const JOB_NAME: Record<JobName, string> = { ship: "ship", handoff: "hand-off" }
+
+const busyText = (job: JobName) => `A ${JOB_NAME[job]} is still running: wait for its report.`
+
+// Only these leave the tree alone (ship and throw refuse for themselves); any
+// other verb, unknown ones included, may switch branch or write .gtd/. `stop`
+// is not here: `command` takes the bare word itself, and `stop <words>` is a
+// requirement. `ui` is not: its page writes steering files.
+const WHILE_BUSY = new Set(["status", "throw", "ship"])
+
+export function decideCommand(arg: string, busy: JobName | undefined): string | undefined {
+  if (!busy) return undefined
+  const verb = arg.trim().split(/\s+/)[0] ?? ""
+  return WHILE_BUSY.has(verb) ? undefined : busyText(busy)
+}
+
+// Pure: a refused job leaves the run, and so `continue`, as it was.
+export function decideJob(run: Run, job: JobName): string | undefined {
+  if (run.isRunning) return "gtd is running a step: wait for it to rest."
+  if (run.pending) return "A continue is already waiting for this turn to end."
+  const kind = run.stop?.kind
+  if (job === "ship" && (kind === "gate" || kind === "stalled" || kind === "error")) {
+    return "gtd still waits on the person at this step: answer it with continue first."
+  }
+  return undefined
 }
 
 // What `continue` may do from here. `rest` undefined is the band's Continue,
@@ -82,6 +113,7 @@ export async function decideContinue(
   io: ContinueIo,
 ): Promise<Proceed> {
   if (run.isRunning) return { refuse: "gtd is already running a step." }
+  if (io.busy) return { refuse: busyText(io.busy) }
   const stop = run.stop
   if (!stop) return { refuse: "Nothing is waiting: gtd has no rest open. /gtd drives it." }
   if (stop.kind === "done") {

package/claude/hooks/wording.ts

@@ -2,6 +2,9 @@
 
 import type { Stop } from "../types"
 import type { Beat } from "./drive"
+import type { Shipped } from "./ship"
+import { JOB_NAME } from "./tools"
+import type { JobName } from "./tools"
 
 const step = (s: { label?: string; state?: string }) => s.label ?? s.state ?? "the next step"
 
@@ -53,3 +56,11 @@ export function pushText(stop: Stop, repo: string, url?: string) {
   if (stop.kind !== "gate") return at
   return url ? `${at}. Open: ${url}` : at
 }
+
+const capitalised = (s: string) => s[0]!.toUpperCase() + s.slice(1)
+
+export const jobHeadline = (job: JobName, outcome: Shipped) =>
+  `${outcome.ok ? "✔" : "✘"} ${capitalised(JOB_NAME[job])} ${outcome.ok ? "finished" : "failed"}`
+
+export const jobPushText = (job: JobName, outcome: Shipped, repo: string) =>
+  `${repo}: ${JOB_NAME[job]} ${outcome.ok ? "finished" : "failed"}. ${outcome.text}`.trim()

package/dist/chunks/{reserved-Df8GeSHw.mjs → reserved-UdSuHDUJ.mjs}

@@ -1234,13 +1234,13 @@ const fixRisks = (notes) => agentWithSkills("review.fix.risks.fixing", buildRevi
 	system: reviewerSystem(),
 	allowEmpty: true
 });
-const awaitReview = (base, message = buildReviewAwaitReviewMessage(base), acceptClean = false) => human("review.await-review", {
+const awaitReview = (base, message = buildReviewAwaitReviewMessage(base)) => human("review.await-review", {
 	message,
 	label: "Awaiting your review",
 	file: REVIEW,
 	mode: "review",
 	base,
-	...acceptClean ? { acceptClean } : {}
+	acceptClean: true
 });
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */
 const reviewMissing = (round) => human("review.review-missing", {

package/dist/chunks/{tail-DmIfEAI4.mjs → tail-fj60rQ3y.mjs}

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../flows.mjs";
 import { fixFindings, lensesOf, qualityLap as qualityLap$1, reviewToHandOff } from "../workflow-kit.mjs";
-import { C as fixRisks, D as reviewing, E as reviewQuality, G as handOffAwaitReviewMessage, S as fixQuality, T as reviewMissing, f as guarded, g as QUALITY, p as healthy, u as escalation, v as REVIEW, x as fixCheck, y as awaitReview } from "./reserved-Df8GeSHw.mjs";
+import { C as fixRisks, D as reviewing, E as reviewQuality, G as handOffAwaitReviewMessage, S as fixQuality, T as reviewMissing, f as guarded, g as QUALITY, p as healthy, u as escalation, v as REVIEW, x as fixCheck, y as awaitReview } from "./reserved-UdSuHDUJ.mjs";
 //#region src/workflows/shared/tail.ts
 /** The reviewer's own `.gtd/REVIEW.md`, kept beside the human's notes so `fix` can tell them apart. */
 const REVIEW_ORIG = ".gtd/REVIEW.orig.md";

package/dist/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
-import { a as flagShipped, b as coder, c as envDefaults, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-Df8GeSHw.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-DmIfEAI4.mjs";
+import { a as flagShipped, b as coder, c as envDefaults, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-UdSuHDUJ.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-fj60rQ3y.mjs";
 import { i as requireFlag, r as registryEntry, t as flagReferences } from "../chunks/registry-CP3YuV9j.mjs";
 //#region src/workflows/cleanup/cleanup.ts
 const removingPrompt = (name, registry) => `Clean up the release flag "${name}", which is default-on: delete its entry in ${registry}, and remove every \`GTD_FLAG_${name.toUpperCase()}\` check from the shipped sources. Keep the flag-on path; delete code only the off path reached, including tests that pin the off path.`;

package/dist/workflows/feature.mjs

@@ -1,7 +1,7 @@
 import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, judgeDiffShape, kept, mark, numeric, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, seamGate, start, vars } from "../flows.mjs";
 import { review as review$1 } from "../workflow-kit.mjs";
-import { $ as refactorFixPrompt, A as architectureAuthorPrompt, B as designGateAnswerMessage, C as fixRisks, D as reviewing, F as buildReviewCollectingPrompt, H as designTriagePrompt, I as buildReviewFixNitsPrompt, J as implementFixPrompt, K as idleMessage, L as buildReviewTriageMessage, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewAwaitAfterDeferMessage, Q as refactorBuildingPrompt, R as builderSystem, T as reviewMissing, V as designSystem, X as packagesItemBuildingPrompt, Y as naivePassPrompt, Z as packagesItemFixSuitePrompt, _ as REQUIREMENTS, at as seamByHandMessage, b as coder, c as envDefaults, ct as unwindFailedMessage, d as gate, et as reviewEditNotesCapture, h as FEEDBACK, i as skills, it as reviewerSystem, j as architectureDecomposePrompt, k as architectSystem, lt as unwindFailure, m as ARCHITECTURE, n as summary, o as shipped, ot as seamSteerMessage, p as healthy, q as implementBuildingPrompt, r as access, rt as reviewNotesCapture, s as defaults, st as startGateBlockedMessage, t as steering, tt as reviewEditsCapture, v as REVIEW, w as planner, x as fixCheck, y as awaitReview, z as deferNotesScript } from "../chunks/reserved-Df8GeSHw.mjs";
-import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-DmIfEAI4.mjs";
+import { $ as refactorFixPrompt, A as architectureAuthorPrompt, B as designGateAnswerMessage, C as fixRisks, D as reviewing, F as buildReviewCollectingPrompt, H as designTriagePrompt, I as buildReviewFixNitsPrompt, J as implementFixPrompt, K as idleMessage, L as buildReviewTriageMessage, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewAwaitAfterDeferMessage, Q as refactorBuildingPrompt, R as builderSystem, T as reviewMissing, V as designSystem, X as packagesItemBuildingPrompt, Y as naivePassPrompt, Z as packagesItemFixSuitePrompt, _ as REQUIREMENTS, at as seamByHandMessage, b as coder, c as envDefaults, ct as unwindFailedMessage, d as gate, et as reviewEditNotesCapture, h as FEEDBACK, i as skills, it as reviewerSystem, j as architectureDecomposePrompt, k as architectSystem, lt as unwindFailure, m as ARCHITECTURE, n as summary, o as shipped, ot as seamSteerMessage, p as healthy, q as implementBuildingPrompt, r as access, rt as reviewNotesCapture, s as defaults, st as startGateBlockedMessage, t as steering, tt as reviewEditsCapture, v as REVIEW, w as planner, x as fixCheck, y as awaitReview, z as deferNotesScript } from "../chunks/reserved-UdSuHDUJ.mjs";
+import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-fj60rQ3y.mjs";
 //#region src/workflows/feature/tier.ts
 /** GTD_FLAG_NAIVE_PASS, GTD_FLAG_RISK_TIER: both pinned at process start, so a mid-process flip never moves a process. */
 const riskTierOn = () => vars.flag_naive_pass === "1" && vars.flag_risk_tier === "1";
@@ -355,7 +355,7 @@ const review = (base, escalations = { rounds: 0 }) => {
 		awaitReview: (b) => {
 			const notes = deferred;
 			deferred = [];
-			return notes.length > 0 ? awaitReview(b, buildReviewAwaitAfterDeferMessage(b, notes), true) : awaitReview(b);
+			return notes.length > 0 ? awaitReview(b, buildReviewAwaitAfterDeferMessage(b, notes)) : awaitReview(b);
 		},
 		reviewMissing,
 		collecting,

package/dist/workflows/fix.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
-import { O as agentWithSkills, U as finisherSystem, W as fixReviewNotesPrompt, b as coder, c as envDefaults, i as skills, l as baseline, n as summary, o as shipped, r as access, s as defaults, t as steering, v as REVIEW } from "../chunks/reserved-Df8GeSHw.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-DmIfEAI4.mjs";
+import { O as agentWithSkills, U as finisherSystem, W as fixReviewNotesPrompt, b as coder, c as envDefaults, i as skills, l as baseline, n as summary, o as shipped, r as access, s as defaults, t as steering, v as REVIEW } from "../chunks/reserved-UdSuHDUJ.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-fj60rQ3y.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,6 +1,6 @@
 import { start } from "../flows.mjs";
-import { c as envDefaults, d as gate, i as skills, n as summary, nt as reviewGateBlockedMessage, o as shipped, r as access, s as defaults, t as steering } from "../chunks/reserved-Df8GeSHw.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-DmIfEAI4.mjs";
+import { c as envDefaults, d as gate, i as skills, n as summary, nt as reviewGateBlockedMessage, o as shipped, r as access, s as defaults, t as steering } from "../chunks/reserved-UdSuHDUJ.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-fj60rQ3y.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/dist/workflows/rollout.mjs

@@ -1,5 +1,5 @@
 import { agent, changesSince, head, read, refuse, scope, vars } from "../flows.mjs";
-import { a as flagShipped, b as coder, c as envDefaults, d as gate, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-Df8GeSHw.mjs";
+import { a as flagShipped, b as coder, c as envDefaults, d as gate, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-UdSuHDUJ.mjs";
 import { i as requireFlag, n as flipProblems } from "../chunks/registry-CP3YuV9j.mjs";
 //#region src/workflows/rollout/rollout.ts
 const flippingPrompt = (name, registry) => `Roll out the release flag "${name}": in ${registry}, set \`defaultOn: true\` on its entry. Change nothing else — no other entry, no other field, no other file, no comments.`;

package/dist/workflows.mjs

@@ -17995,13 +17995,13 @@ const fixRisks = (notes) => agentWithSkills("review.fix.risks.fixing", buildRevi
 	system: reviewerSystem(),
 	allowEmpty: true
 });
-const awaitReview = (base, message = buildReviewAwaitReviewMessage(base), acceptClean = false) => human("review.await-review", {
+const awaitReview = (base, message = buildReviewAwaitReviewMessage(base)) => human("review.await-review", {
 	message,
 	label: "Awaiting your review",
 	file: REVIEW,
 	mode: "review",
 	base,
-	...acceptClean ? { acceptClean } : {}
+	acceptClean: true
 });
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */
 const reviewMissing = (round) => human("review.review-missing", {
@@ -37911,7 +37911,7 @@ const review$1 = (base, escalations = { rounds: 0 }) => {
 		awaitReview: (b) => {
 			const notes = deferred;
 			deferred = [];
-			return notes.length > 0 ? awaitReview(b, buildReviewAwaitAfterDeferMessage(b, notes), true) : awaitReview(b);
+			return notes.length > 0 ? awaitReview(b, buildReviewAwaitAfterDeferMessage(b, notes)) : awaitReview(b);
 		},
 		reviewMissing,
 		collecting,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "27.7.0",
+  "version": "27.7.1",
   "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/workflows/feature/review.test.ts

@@ -509,13 +509,19 @@ describe("severity routing", () => {
       notes: ["add — quote", "sub", "mul"],
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
     })
-    expect(run.gates).toEqual([false, true])
+    expect(run.gates).toEqual([true, true])
     expect(run.gateMessages[1]).toContain("NOT acted on")
     expect(run.gateMessages[1]).toContain("note-1")
     expect(run.gateMessages[0]).not.toContain("NOT acted on")
   })
 
-  it("a later gate does not accept a clean land after a deferral round with a nit", async () => {
+  it("the first round's gate accepts a clean land", async () => {
+    const run = await drive({ notes: ["add", "sub", "mul"] })
+    expect(run.gates.length).toBeGreaterThan(0)
+    expect(run.gates.every((g) => g)).toBe(true)
+  })
+
+  it("a later gate still accepts a clean land after a deferral round with a nit", async () => {
     const run = await drive({
       notes: ["add — quote", "sub — typo", "mul"],
       answers: {
@@ -527,7 +533,7 @@ describe("severity routing", () => {
     })
     expect(run.log).toContain("review.defer")
     expect(run.log.at(-1)).toBe("review.await-review")
-    expect(run.gates).toEqual([false, false])
+    expect(run.gates).toEqual([true, true])
   })
 
   it("a question and a could note in one round: the gate's base is the answering commit", async () => {

package/src/workflows/feature/review.ts

@@ -167,8 +167,8 @@ export const review = (
   escalations: EscalationCount = { rounds: 0 },
 ): Promise<kit.ReviewOutcome> => {
   const severities = new Map<string, Severity>()
-  // Armed by a defer-only round and spent at the very next gate; a fresh
-  // review (`reviewing`) disarms it, so a later gate never accepts a clean land.
+  // Armed by a defer-only round to pick the next gate's message; a fresh
+  // review (`reviewing`) disarms it.
   let deferred: readonly t.NoteInput[] = []
   return kit.review(base, {
     file: REVIEW,
@@ -184,7 +184,7 @@ export const review = (
       const notes = deferred
       deferred = []
       return notes.length > 0
-        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes), true)
+        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes))
         : awaitReview(b)
     },
     reviewMissing,

package/src/workflows/shared/steps.ts

@@ -117,7 +117,6 @@ export const fixRisks = (notes: readonly t.NoteInput[]): Promise<void> =>
 export const awaitReview = (
   base: string,
   message = t.buildReviewAwaitReviewMessage(base),
-  acceptClean = false,
 ): Promise<void> =>
   human("review.await-review", {
     message,
@@ -125,7 +124,7 @@ export const awaitReview = (
     file: REVIEW,
     mode: "review",
     base,
-    ...(acceptClean ? { acceptClean } : {}),
+    acceptClean: true,
   })
 
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */

package/src/workflows/shared/tail.test.ts

@@ -38,8 +38,18 @@ const handOff = async (
   } = {},
 ) => {
   const log: string[] = []
+  const gates: boolean[] = []
   const scripts = new Map<string, string>()
   const files = new Map<string, string>()
+  const onReviewing = () => {
+    if (log.filter((n) => n === "review.reviewing").length > 1) throw new Error("re-review")
+    if (after !== "unwritten") files.set(REVIEW, reviewDoc("new add function"))
+  }
+  const onGate = (request: StepRequest) => {
+    if (request.kind === "human") gates.push(request.options.acceptClean === true)
+    if (after === "deleted") files.delete(REVIEW)
+    else if (after !== "unwritten") files.set(REVIEW, after)
+  }
   installContext(
     fixtureContext(
       { codeThreads: extra.codeThreads ?? [] },
@@ -48,14 +58,8 @@ const handOff = async (
           if (request.kind === "restart") return Promise.resolve()
           log.push(request.name)
           if (request.kind === "run") scripts.set(request.name, request.body)
-          if (request.name === "review.reviewing") {
-            if (log.filter((n) => n === "review.reviewing").length > 1) throw new Error("re-review")
-            if (after !== "unwritten") files.set(REVIEW, reviewDoc("new add function"))
-          }
-          if (request.name === "review.await-review") {
-            if (after === "deleted") files.delete(REVIEW)
-            else if (after !== "unwritten") files.set(REVIEW, after)
-          }
+          if (request.name === "review.reviewing") onReviewing()
+          if (request.name === "review.await-review") onGate(request)
           return Promise.resolve()
         },
         refuse: (message: string): never => {
@@ -96,7 +100,7 @@ const handOff = async (
     () => undefined,
     (e: unknown) => (e as Error).message,
   )
-  return { log, scripts, refusal }
+  return { log, scripts, refusal, gates }
 }
 
 describe("the hand-off review", () => {
@@ -105,6 +109,11 @@ describe("the hand-off review", () => {
     expect(run.log).toEqual(["review.reviewing", "review.await-review", "review.closing"])
   })
 
+  it("the review gate accepts a clean landing", async () => {
+    const run = await handOff(reviewDoc("new add function"))
+    expect(run.gates).toEqual([true])
+  })
+
   it("a note ends the round with the review kept and the reviewer's version copied beside it", async () => {
     const run = await handOff(reviewDoc("new add function — rename it to sum"))
     expect(run.log).toEqual(["review.reviewing", "review.await-review", "review.handing-off"])