@pmelab/gtd 29.2.1 → 29.2.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "29.2.1",
+  "version": "29.2.3",
   "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,35 +324,38 @@ 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. 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`, `/gtd review [base]`,
-`/gtd rollout <flag>` and `/gtd cleanup <flag>` (where the config exports them)
-take the doors described below; text whose word count does not fit a door's args
-(bare `/gtd rollout` included) starts a process from that text as requirements.
-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 and open its pull
-request(s) (or run `/gtd ship`; `GTD_SHIP_MODE` picks one stacked pull request
-per slice or one commit per slice, see the [driver doc](docs/driver.md));
-re-running `/gtd ship` after a lower stacked pull request merged restacks the
-rest (it refuses, with nothing changed, when that pull request merged anywhere
-but the default branch (unless into a lower slice branch before that one merged
-into it), a slice branch is checked out in another worktree, an unrelated local
-branch sits inside the rebased commits, or a slice's change is already upstream;
-a failed rebase is rolled back). 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
+That starts a process from your requirements and drives it until it needs you.
+The requirements go to the top of `.gtd/TODO.md`; deferred review notes already
+there stay. 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 add
+the requirements to the top of `.gtd/TODO.md` and run `/gtd`. `/gtd fix`,
+`/gtd review [base]`, `/gtd rollout <flag>` and `/gtd cleanup <flag>` (where the
+config exports them) take the doors described below; text whose word count does
+not fit a door's args (bare `/gtd rollout` included) starts a process from that
+text as requirements. 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
+and open its pull request(s) (or run `/gtd ship`; `GTD_SHIP_MODE` picks one
+stacked pull request per slice or one commit per slice, see the
+[driver doc](docs/driver.md)); a process started for an issue ships with
+`Closes #N` on its top pull request; re-running `/gtd ship` after a lower
+stacked pull request merged restacks the rest (it refuses, with nothing changed,
+when that pull request merged anywhere but the default branch (unless into a
+lower slice branch before that one merged into it), a slice branch is checked
+out in another worktree, an unrelated local branch sits inside the rebased
+commits, or a slice's change is already upstream; a failed rebase is rolled
+back). 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

package/claude/hooks/drive.ts

@@ -44,7 +44,8 @@ export type Turn = {
   access?: AccessDef
 }
 
-export type TurnEnd = { ok: true } | { ok: false; why: string }
+// `isLost`: the scope's subagent no longer takes messages.
+export type TurnEnd = { ok: true } | { ok: false; why: string; isLost?: true }
 
 export type Io = {
   next(): Promise<Beat>
@@ -138,39 +139,53 @@ async function message(io: Io, b: Beat, beat: number, judged: string | undefined
 }
 
 async function agent(io: Io, b: Beat, landTurn: string | undefined): Promise<Acted> {
-  const memory = memoryOf(b)
-  const t =
-    landTurn === memory
-      ? ({ ok: true } as const)
-      : await io.turn({
-          memory,
-          resume: isTrue(b.session?.resume),
-          prompt: b.content ?? "",
-          label: b.label,
-          model: b.model || undefined,
-          system: b.system || undefined,
-          skills: b.skills ?? [],
-          scope: memory.split("#")[0]!,
-          access: b.access,
-        })
+  const turn = turnOf(b)
+  const t = landTurn === turn.memory ? ({ ok: true } as const) : await io.turn(turn)
   if (!t.ok) return failed(b, t.why)
-  return b.validate ? validated(io, b, b.validate, memory) : {}
+  return b.validate ? validated(io, b, b.validate) : {}
 }
 
 // The step's own validator; its findings go back to the same conversation.
-async function validated(io: Io, b: Beat, validate: string, memory: string): Promise<Acted> {
+async function validated(io: Io, b: Beat, validate: string): Promise<Acted> {
   for (let fixes = 0; ; fixes++) {
     const v = await io.check(validate)
     if (v.ok) return {}
     if (fixes >= MAX_FIXES)
       return failed(b, `validation still failing after ${fixes} fixes\n${v.out}`)
-    const f = await io.resume(memory, v.out)
+    const f = await followUp(io, b, v.out)
     if (!f.ok) return failed(b, f.why)
   }
 }
 
+// A conversation whose subagent is gone starts over with the step's prompt
+// and the follow-up, rather than failing a step a fresh subagent can finish.
+async function followUp(io: Io, b: Beat, text: string): Promise<TurnEnd> {
+  const turn = turnOf(b)
+  const r = await io.resume(turn.memory, text)
+  if (r.ok || !r.isLost) return r
+  return io.turn({ ...turn, resume: false, prompt: `${turn.prompt}\n\n${LOST}\n\n${text}` })
+}
+
+const LOST =
+  "An earlier subagent working on this step was lost; what it did is in the working tree. Continue from there with this:"
+
 const memoryOf = (b: Beat) => b.memory ?? b.session?.id ?? b.state ?? "root"
 
+function turnOf(b: Beat): Turn {
+  const memory = memoryOf(b)
+  return {
+    memory,
+    resume: isTrue(b.session?.resume),
+    prompt: b.content ?? "",
+    label: b.label,
+    model: b.model || undefined,
+    system: b.system || undefined,
+    skills: b.skills ?? [],
+    scope: memory.split("#")[0]!,
+    access: b.access,
+  }
+}
+
 // A prompt beat whose turn wrote outside its access gets one recovery turn
 // with the refusal text; a second refusal is an error, not another loop.
 async function land(
@@ -201,11 +216,10 @@ async function recover(
   verdict: string | undefined,
   text: string,
 ): Promise<Stop | undefined> {
-  const memory = memoryOf(b)
-  const r = await io.resume(memory, text)
+  const r = await followUp(io, b, text)
   if (!r.ok) return { kind: "error", text: r.why, ...where(b) }
   if (b.validate) {
-    const v = await validated(io, b, b.validate, memory)
+    const v = await validated(io, b, b.validate)
     if (v.stop) return v.stop
   }
   return land(io, b, verdict, false)

package/claude/hooks/paste.ts

@@ -10,7 +10,7 @@ export function pastedCommand(text: string): Pasted | undefined {
   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.",
+      lost: "The pasted requirements did not arrive whole. Add them to the top of .gtd/TODO.md and run /gtd.",
     }
   }
   return { arg }

package/claude/hooks/register.tsx

@@ -17,6 +17,7 @@ import { catchFrom, throwTo } from "./handoff"
 import { jobs } from "./jobs"
 import { documents, readDocument } from "./schema"
 import { READ_ONLY_GIT, ship } from "./ship"
+import { withRequirements } from "./sketch"
 import type { Shipped, ShipIo } from "./ship"
 import { collectAnswer } from "./delegate"
 import { decideCommand, decideContinue, decideJob, restId, TOOLS } from "./tools"
@@ -27,6 +28,7 @@ import {
   jobHeadline,
   jobPushText,
   pushText,
+  lostLine,
   restartLine,
   RELOAD_CUT_SCRIPT,
   runningLine,
@@ -114,6 +116,26 @@ async function send($: $, agentId: string, text: string) {
   return undefined
 }
 
+// A subagent that no longer takes messages can leave its task listed with a
+// frozen timer: stop it, and forget it as the scope's conversation. It must
+// not stay `inflight` either, or a reload would land a turn it never ran.
+async function forget($: $, memory: string, agentId: string) {
+  $.ui.log(lostLine(memory.split("#")[0]!))
+  accesses.delete(agentId)
+  await update($, scopes, (s) => {
+    const rest = { ...s }
+    if (rest[memory]?.agentId === agentId) delete rest[memory]
+    return rest
+  })
+  await update($, run, (r) => (r.inflight?.agentId === agentId ? { ...r, inflight: undefined } : r))
+  try {
+    await $.tool.call({ tool: "TaskStop", task_id: agentId })
+  } catch {
+    // already gone from the task list
+  }
+  ended.delete(agentId)
+}
+
 async function settle($: $, end: TurnEnd) {
   await update($, run, (r) => ({ ...r, inflight: undefined }))
   return end
@@ -175,6 +197,7 @@ function io($: $): Io {
         await update($, run, (r) => ({ ...r, inflight: { agentId: known, memory: t.memory } }))
         const ended = await end
         if (ended) return settle($, ended)
+        await forget($, t.memory, known)
       }
       // No live conversation for this scope (fresh scope, or this session never
       // held it): start one, as the sh driver falls back to `--session-id`.
@@ -189,7 +212,7 @@ function io($: $): Io {
         cwd: root,
       })
       const id = spawned.agentId
-      if (!id) return { ok: false, why: spawned.deny ?? "subagent spawn refused" }
+      if (!id) return settle($, { ok: false, why: spawned.deny ?? "subagent spawn refused" })
       ours.add(id)
       setAccess(id, t.access)
       await update($, agents, (list) => [...list, id].slice(-200))
@@ -200,7 +223,10 @@ function io($: $): Io {
     resume: async (memory, text) => {
       const id = (await read($, scopes))[memory]?.agentId
       const end = id ? await send($, id, text) : undefined
-      return end ?? { ok: false, why: `no live subagent for ${memory}` }
+      if (end) return end
+      if (id) await forget($, memory, id)
+      else $.ui.log(lostLine(memory.split("#")[0]!))
+      return { ok: false, isLost: true, why: `no live subagent for ${memory}` }
     },
     progress: (beat, b) => {
       // The band is not drawn everywhere (Remote Control, the mobile app):
@@ -306,7 +332,8 @@ async function begin($: $, requirements: string) {
   const file = b.file ?? ".gtd/TODO.md"
   const path = `${root}/${file}`
   await $.process.run(["mkdir", "-p", path.slice(0, path.lastIndexOf("/"))])
-  await $.fs.write(path, requirements + "\n")
+  const existing = (await $.fs.exists(path)) ? await $.fs.read(path) : ""
+  await $.fs.write(path, withRequirements(existing, requirements))
   await start($)
   return `Started a new gtd process from ${file}.`
 }

package/claude/hooks/ship.ts

@@ -116,16 +116,30 @@ in a terminal. Plain prose is the right answer too when there is no shape to
 draw; then keep it to a paragraph, wrapped at 72 columns.
 
 No markdown headings, no code fences, no bullet list of changed files, no
-sign-off, and no footer trailers except one: when the instructions above
+sign-off, and no footer trailers except two: when the instructions above
 say the change is breaking, end with a literal 'BREAKING CHANGE: <what
 breaks>' footer after a blank line. The release tooling reads only that
-footer, so a breaking change without it is never released as one.
+footer, so a breaking change without it is never released as one. And when
+the instructions above ask for a 'Closes #N' footer, end with it too — the
+pull request is linked to its issue only through that line.
 
 NOTHING REVIEWS THIS BEFORE IT IS COMMITTED — no editor opens on it. What you
 print is the commit message verbatim.
 
 Print the message and nothing else — no code fences, no preamble.`
 
+// `gtd summary --slice` asks only the process's last slice to close its issue;
+// a group that absorbed that slice is the last commit all the same.
+const ABSORBED = `
+--- THIS IS THE PROCESS'S LAST COMMIT ---
+
+The slices after this one changed nothing outside .gtd/ and fold into it. If
+the process was started for an issue — its entry commit or
+.gtd/REQUIREMENTS.md names one as #N, owner/repo#N or an issue URL — end the
+message with a literal 'Closes #N' footer per issue. Name only an issue the
+work resolves, never one it merely mentions.
+`
+
 const DESCRIPTION = `The description is a STANDING statement, not a changelog. It covers exactly three
 things, and a reviewer reads it once:
 
@@ -247,7 +261,8 @@ function withWarning(r: Shipped, warning?: string): Shipped {
 type Git = (...args: string[]) => Promise<string>
 type Ok = (...args: string[]) => Promise<boolean>
 
-type Group = { name: string; base: string; tip: string }
+// `absorbed`: the group took in a trailing .gtd/-only slice, so it closes the process.
+type Group = { name: string; base: string; tip: string; absorbed?: boolean }
 
 // Slices that changed a file outside .gtd/ each land a commit; one that did not
 // folds into the next landed slice, or the previous when it is last.
@@ -263,7 +278,8 @@ async function landed(ok: Ok, slices: Slice[]) {
     groups.push({ name: s.name, base: carry ?? s.base, tip: s.tip })
     carry = undefined
   }
-  if (carry && groups.length) groups.at(-1)!.tip = slices.at(-1)!.tip
+  if (carry && groups.length)
+    Object.assign(groups.at(-1)!, { tip: slices.at(-1)!.tip, absorbed: true })
   return groups
 }
 
@@ -304,7 +320,9 @@ async function commitMessages(io: ShipIo, git: Git, groups: Group[], tip: string
       return fail(
         `gtd summary --slice=${g.name} failed; nothing changed.\n${summary.err}`.trimEnd(),
       )
-    const reply = await io.complete(summary.out + "\n" + COMMIT_FORMAT)
+    const reply = await io.complete(
+      summary.out + "\n" + (g.absorbed ? ABSORBED : "") + COMMIT_FORMAT,
+    )
     const message = reply && cleanReply(reply)
     if (!message) return fail("The commit-message turn produced nothing.")
     parts.push({ message, trailers })
@@ -1500,7 +1518,14 @@ async function shipLink(
   const pushed = await pushLink(io, git, l, i < links.length - 1)
   if (pushed) return { step: "push", why: pushed }
   const lowerRef = lower?.branch ?? baseRef
-  const ctx: Ctx = { to: l.commit, from: lower?.commit ?? mergeBase, below, stacked: true }
+  const ctx: Ctx = {
+    to: l.commit,
+    from: lower?.commit ?? mergeBase,
+    below,
+    stacked: true,
+    lower: i < links.length - 1,
+    floor: mergeBase,
+  }
   const done = await sliceStep(io, git, ok, l, view, base, lowerRef, ctx)
   if ("step" in done) return done
   if (done.number === undefined && i < links.length - 1)
@@ -1861,7 +1886,49 @@ const TITLE = /^(feat|fix|refactor|perf|docs|test|build|ci|chore)(\([\w./-]+\))?
 export const THROWN = "<!-- gtd:thrown -->"
 
 // unstacked: this run took the PR off a stack, so nothing new is still a success.
-type Ctx = { from: string; to: string; stacked?: boolean; below?: number; unstacked?: boolean }
+// lower: a stacked slice below the top, whose PR merges first and must close nothing.
+type Ctx = {
+  from: string
+  to: string
+  stacked?: boolean
+  below?: number
+  unstacked?: boolean
+  lower?: boolean
+  // The stack's floor: the top PR closes what every slice's commits close.
+  floor?: string
+}
+
+// [ \t], never \s: a reference on the next line is not what the keyword closes.
+const KEYWORD = String.raw`(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?[ \t]+`
+const URL = String.raw`https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/issues\/(\d+)`
+const REF = String.raw`(?:(?:[\w.-]+\/[\w.-]+)?#\d+|${URL})`
+const NEXT = String.raw`(?:[ \t]*,[ \t]*|[ \t]+and[ \t]+)(?:${KEYWORD})?`
+// A whole line of closing references, bulleted or not: `Closes #1.`,
+// `- Fixes #1, #2`, `Resolves o/r#3 and fixes <issue URL>`.
+const CLOSING = new RegExp(
+  String.raw`^[ \t]*(?:[-*][ \t]+)?${KEYWORD}${REF}(?:${NEXT}${REF})*[ \t]*\.?[ \t]*$`,
+  "gim",
+)
+const REFS = new RegExp(REF, "g")
+
+const closed = (text: string) => {
+  const refs = new Map<string, string>()
+  for (const [line] of text.matchAll(CLOSING))
+    for (const [whole, repo, n] of line.matchAll(REFS)) {
+      const ref = repo ? `${repo}#${n}` : whole
+      if (!refs.has(ref.toLowerCase())) refs.set(ref.toLowerCase(), ref)
+    }
+  return refs
+}
+
+// The description prompt forbids footers, so the issues the commits close are
+// carried over here: a PR body without the keyword never links its issue.
+export function withCloses(body: string, log: string) {
+  const has = closed(body)
+  const add = [...closed(log)].filter(([key]) => !has.has(key)).map(([, ref]) => ref)
+  if (!add.length) return body
+  return [body.trimEnd(), add.map((ref) => `Closes ${ref}`).join("\n")].filter(Boolean).join("\n\n")
+}
 
 async function createPr(
   io: ShipIo,
@@ -1869,7 +1936,7 @@ async function createPr(
   branch: string,
   baseBranch: string,
   baseRef: string,
-  { from: mergeBase, to, stacked, below }: Ctx,
+  { from: mergeBase, to, stacked, below, lower, floor }: Ctx,
   thrown?: { number: number; url: string },
 ): Promise<Shipped & { number?: number }> {
   const count = await git("rev-list", "--count", `${mergeBase}..${to}`)
@@ -1878,6 +1945,13 @@ async function createPr(
       ? `#${thrown.number} was thrown as a draft: describing ${count} commit(s) properly…`
       : `No pull request for ${branch} yet: describing ${count} commit(s)…`,
   )
+  const log = await git(
+    "log",
+    "--no-merges",
+    "--reverse",
+    "--format=%H%n%B%n---",
+    `${mergeBase}..${to}`,
+  )
   const prompt = `Write the title and description for a pull request, from the commits below.
 
 Format, exactly:
@@ -1903,7 +1977,7 @@ Print the title and description and nothing else — no preamble, and no code
 fence wrapped around the whole reply.
 
 --- COMMITS ON ${branch} (against ${baseRef}), oldest first ---
-${await git("log", "--no-merges", "--reverse", "--format=%H%n%B%n---", `${mergeBase}..${to}`)}
+${log}
 
 --- DIFF STAT ---
 ${await git("diff", "--stat", `${mergeBase}..${to}`)}`
@@ -1915,7 +1989,8 @@ ${await git("diff", "--stat", `${mergeBase}..${to}`)}`
   // a reply shaped like the title it was asked for.
   if (!TITLE.test(title))
     return fail(`The pull-request turn returned no usable title: ${title.slice(0, 120)}`)
-  const written = rest.join("\n").replace(/^\s*\n/, "")
+  const text = rest.join("\n").replace(/^\s*\n/, "")
+  const written = lower ? text : withCloses(text, floor ? await closingLog(git, floor, to) : log)
   const body = stacked ? stackLine(written, below) : written
   const head = await git("rev-parse", to)
   if (thrown) {
@@ -1974,39 +2049,63 @@ async function sinceHead(git: Git, ok: Ok, branch: string, mergeBase: string, to
   return isSynced ? synced : mergeBase
 }
 
-async function updatePr(
+const closingLog = (git: Git, from: string, to: string) =>
+  git("log", "--no-merges", "--format=%B%n---", `${from}..${to}`)
+
+type Existing = { number: number; body?: string; url: string }
+
+// The standing description re-derived: the stack line, and the issues the
+// branch closes, re-applied on every refresh but only written when changed.
+async function refresher(
   io: ShipIo,
   git: Git,
-  ok: Ok,
-  branch: string,
-  { from: mergeBase, to, stacked, below, unstacked }: Ctx,
-  existing: { number: number; body?: string; url: string },
-): Promise<Shipped & { number?: number }> {
-  const restack = (body: string) => (stacked ? stackLine(body, below) : body)
+  { from: mergeBase, to, stacked, below, lower, floor }: Ctx,
+  existing: Existing,
+) {
+  // The whole branch, not just what is new: a PR shipped before its commits
+  // closed anything, or whose edit failed after the sync head moved, still gains them.
+  const log = lower ? "" : await closingLog(git, floor ?? mergeBase, to)
+  const restack = (raw: string) => {
+    const body = withCloses(raw, log)
+    return stacked ? stackLine(body, below) : body
+  }
   const edit = async (body: string) =>
     io.run(["gh", "pr", "edit", String(existing.number), "--body-file", "-"], body)
-  // The stack line is re-applied on every refresh, but only written when it changed.
-  const restacked = async (pr: { body?: string }, text: string) => {
-    const fixed = restack(pr.body ?? "")
-    if (fixed === (pr.body ?? "")) return { ok: true, text, number: existing.number }
+  const was = existing.body ?? ""
+  const restacked = async (text: string) => {
+    const fixed = restack(was)
+    if (fixed === was) return { ok: true, text, number: existing.number }
     const edited = await edit(fixed)
     if (edited.code !== 0)
       return {
         ...fail(
-          `gh pr edit failed; the stack line of ${existing.url} is unchanged.\n${edited.err}`,
+          `gh pr edit failed; the description of ${existing.url} is unchanged.\n${edited.err}`,
         ),
         number: existing.number,
       }
     return { ok: true, text, number: existing.number }
   }
+  return { restack, edit, restacked, stale: restack(was) !== was }
+}
+
+async function updatePr(
+  io: ShipIo,
+  git: Git,
+  ok: Ok,
+  branch: string,
+  ctx: Ctx,
+  existing: Existing,
+): Promise<Shipped & { number?: number }> {
+  const { from: mergeBase, to, stacked, unstacked } = ctx
+  const { restack, edit, restacked, stale } = await refresher(io, git, ctx, existing)
   // Only what landed since the last run. A stored head a squash left behind
   // falls back to the whole branch, the only honest range left.
   const since = await sinceHead(git, ok, branch, mergeBase, to)
   // ^mergeBase keeps a synced head from before a main merge from re-weighing
   // the commits that merge brought in.
   const count = Number(await git("rev-list", "--count", `${since}..${to}`, `^${mergeBase}`))
-  if (!count && (stacked || unstacked))
-    return restacked(existing, `Nothing new since the last ship: ${existing.url}`)
+  if (!count && (stacked || unstacked || stale))
+    return restacked(`Nothing new since the last ship: ${existing.url}`)
   if (!count) return fail(`No commits since the last ship: ${existing.url}`)
   io.log(`#${existing.number}: weighing ${count} commit(s) against the standing description…`)
 
@@ -2051,7 +2150,6 @@ ${await git("diff", "--stat", `${mergeBase}..${to}`)}`
   if (/^\s*NO-UPDATE\s*$/.test(out)) {
     await io.run(["git", "config", "--local", `branch.${branch}.prSyncHead`, sha])
     return restacked(
-      existing,
       `Nothing at that level changed; the description of ${existing.url} is left alone.`,
     )
   }

package/claude/hooks/sketch.ts

@@ -0,0 +1,6 @@
+// New requirements go above what the steering file already holds, untouched:
+// a deferred review note the start diff alters reads as the human's edit.
+export function withRequirements(existing: string, requirements: string): string {
+  const head = `${requirements.trimEnd()}\n`
+  return existing.trim() ? `${head}\n${existing}` : head
+}

package/claude/hooks/wording.ts

@@ -50,6 +50,8 @@ export const beatLine = (beat: number, b: Beat) => `▸ ${step(b)} · step ${bea
 export const restartLine = (scope: string) =>
   `${scope}: skills or system changed — started a fresh subagent`
 
+export const lostLine = (scope: string) => `${scope}: subagent lost`
+
 // What a push to a phone says when gtd stops: the step, and where to act on it.
 export function pushText(stop: Stop, repo: string, url?: string) {
   const at = `${repo}: ${headline(stop).replace(/^\S+ /, "")}`

package/dist/chunks/{reserved-BzeofpoC.mjs → reserved-BduvUQxQ.mjs}

@@ -770,9 +770,13 @@ ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `;
 const refactorRules = (strays, pattern) => `- Behaviour-neutral: the suite's outcome must not change
-- Change only these paths, nothing else, and never a test file even
-  when it is one of them:
+- Change only these paths, nothing else:
 ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
+- An existing test file only where a changed call shape reaches it:
+  update its call sites, inside an assertion too;
+  never add or delete a test file,
+  never add, remove or alter a test or an assertion, and never
+  change what an assertion checks, an expected value or a snapshot
 - Introduce no new flag read and add no second read of an existing one:
   every match of \`${pattern}\` may move, never increase in number`;
 const withRules = (rules) => rules === void 0 ? "" : `${rules}\n`;
@@ -782,8 +786,13 @@ ${feedback ? `- The package carries a \`## Review feedback\` section: a human's
   last refactor. Act on it, within the rules below
 ` : ""}${refactorRules(strays, pattern)}
 ${reference === void 0 ? "" : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
-  earlier attempt at this change. Read it for ideas; never apply,
-  cherry-pick or check it out — write a fresh refactor
+  earlier attempt at this change, and \`git show --stat ${reference}\`
+  lists every file it touched, the test call sites included.
+  Read it; never apply, cherry-pick or check it out
+- Its changes to these paths' existing code are the seam: write that
+  restructuring afresh here, minus the feature's own behaviour. A
+  refactor that touches none of it is wrong, however clean — never
+  swap in an unrelated tidy-up
 `}- Leave everything uncommitted and finish your turn — do not commit
 `;
 const refactorFixPrompt = (strays, pattern) => `${stateFileRules}
@@ -1099,11 +1108,11 @@ const closedFold = (round, target) => round === "edits" ? `- Fold every hand-edi
 /** `refactor` retargets the prompt at `.gtd/REFACTOR.md` and fences it to the strays. A concern outside the fence is not folded; if nothing at all is written the landing is refused, but a partly buildable round drops the rest silently. */
 const buildReviewCollectingPrompt = (capture, refactor) => {
 	const target = refactor ? ".gtd/REFACTOR.md" : ".gtd/REQUIREMENTS.md";
-	const fence = refactor ? `- The next refactor may change only these paths, and never a test file
-  or a flag read:
+	const fence = refactor ? `- The next refactor may change only these paths, plus an existing test
+  file's call sites, and never a flag read:
 ${refactor.strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
-  A concern needing any other path, a test file, a new or added flag
-  read, or a change in behaviour (that belongs to the feature, not this
+  A concern needing any other path, a new or changed test or assertion,
+  a new or added flag read, or a change in behaviour (that belongs to the feature, not this
   refactor) cannot be built: do not fold it
 ` : "";
 	const actionable = refactor ? `The round is actionable if the human left a note on
@@ -1207,7 +1216,7 @@ ${removed.map(({ path, lines }) => lines.map((a) => `    ${path} — ${a.scenari
 const lapRange = {
 	first: "it covers everything since the base.",
 	feedback: "it starts at the previous review's boundary, so it covers only what is new since the previous review.",
-	refactor: "it covers the whole refactor since it started, on every round."
+	refactor: "it covers the whole refactor since it started, on every round. A refactor may update an existing test's call sites only: give any test-file hunk its own chunk, and say so if it changes a test, an assertion or an expected value."
 };
 const buildReviewReviewingPrompt = (base, lap, carry, removed = []) => `${styleBlock}
 
@@ -1324,7 +1333,12 @@ ${slice === void 0 ? `- Write the closing message for the process HEAD closes or
   the exact escape or rewrite a committed config needs. A \`!\` on the
   type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
   own commit-analyzer has missed that marker before, cutting no release
-  until a follow-up commit carried the literal footer instead
+  until a follow-up commit carried the literal footer instead${slice === void 0 || slice.index === slice.count ? `
+- If the process was started for an issue — its entry commit or
+  \`.gtd/REQUIREMENTS.md\` names one as \`#N\`, \`owner/repo#N\` or an issue
+  URL — end the message with a literal \`Closes #N\` footer per issue
+  (\`Closes owner/repo#N\` for another repository). Name only an issue the
+  work resolves, never one it merely mentions` : ""}
 
 ${slice !== void 0 && slice.index > 1 ? `The process's entry commit is \`${it.entryCommit}\` — outside this slice's range, context
 that states the motivation. ` : `The process's entry commit is \`${it.entryCommit}\`. `}${human}Inspect the range: \`git log ${it.processBase}..${it.processTip}\`

package/dist/chunks/{tail-eS_ZSImR.mjs → tail-pgq1Fbbv.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 { E as reviewing, S as fixRisks, T as reviewQuality, W as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, c as escalation, d as healthy, m as QUALITY, u as guarded, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-BzeofpoC.mjs";
+import { E as reviewing, S as fixRisks, T as reviewQuality, W as handOffAwaitReviewMessage, _ as REVIEW, b as fixCheck, c as escalation, d as healthy, m as QUALITY, u as guarded, v as awaitReview, w as reviewMissing, x as fixQuality } from "./reserved-BduvUQxQ.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 { _t as registryEntry, a as flagShipped, dt as defaults, ft as envDefaults, ht as flagReferences, i as skills, n as summary, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-BzeofpoC.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-eS_ZSImR.mjs";
+import { _t as registryEntry, a as flagShipped, dt as defaults, ft as envDefaults, ht as flagReferences, i as skills, n as summary, r as access, t as steering, vt as requireFlag, y as coder } from "../chunks/reserved-BduvUQxQ.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-pgq1Fbbv.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.`;
 const cleanupFlow = async () => {