@pmelab/gtd 27.9.0 → 28.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "27.9.0",
+  "version": "28.1.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

@@ -327,23 +327,25 @@ Then, in any repository:
 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
+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 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
@@ -362,8 +364,9 @@ state name to choose. The four commands: **`gtd-build`** drives beats until the
 process rests; **`gtd-edit`** opens the steering file the process is waiting on
 right now — falling back to `.gtd/TODO.md` when the resting state declares none;
 **`gtd-door <name> [args...]`** starts a process through a door (`gtd-door fix`,
-`gtd-door review [base]`) and drives it. The `.gtd/TODO.md` fallback is also how
-you begin: on a clean repository the edit command opens the empty
+`gtd-door review [base]`, `gtd-door rollout <flag>`, `gtd-door cleanup <flag>`
+where the config exports them) and drives it. The `.gtd/TODO.md` fallback is
+also how you begin: on a clean repository the edit command opens the empty
 `.gtd/TODO.md`, and whatever you write there is the first sketch the whole
 process gets planned from. As a final step, if it finds an LSP-capable editor,
 the briefing also offers to wire up live diagnostics and review actions in it —
@@ -580,11 +583,25 @@ gate.
 
 ### Rolling out and cleaning up release flags
 
-Two more bundled workflows retire a release flag:
-`gtd --workflow rollout --var flag=<name>` turns it default-on,
-`gtd --workflow cleanup --var flag=<name>` removes it afterwards. See
+Two more bundled workflows retire a release flag. They are opt-in: the
+`gtd.config.ts` that `gtd install` writes does not export them, so add `rollout`
+from `@pmelab/gtd/workflows/rollout` and `cleanup` from
+`@pmelab/gtd/workflows/cleanup` to its exports first. `gtd door rollout <flag>`
+turns it default-on, `gtd door cleanup <flag>` removes it afterwards
+(`/gtd rollout <flag>` and `/gtd cleanup <flag>` in Claude Code;
+`gtd --workflow rollout --var flag=<name>` works too). See
 [Feature flags](docs/configuration.md#rolling-out-and-cleaning-up-a-release-flag).
 
+Rollout makes "on under `GTD_FLAG_<NAME>=1`" prose wrong until cleanup, so once
+the suite passes it lists every line outside the registry that names the flag
+(as `path:line`, the first 50, then a `git grep` command over tracked files for
+the rest) and edits none of them, leaving no file behind. The squash carries the
+list only through the closing message `gtd summary` writes; the `Gtd-Mark:`
+trailers survive only in the process history ref `refs/gtd/history/<entry>`,
+recovered with `gtd history fetch | sh` and read with
+`git log --format=%B <ref>`. An empty list says so in one line. Fix the prose by
+hand or leave it for cleanup.
+
 The delivery model these workflows implement: [Delivery model](SDLC.md).
 
 ## Checking a range for stray files
@@ -604,8 +621,11 @@ or `.gitmodules` `ignore` say. Works in any git repository, no process needed.
 
 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` changes nothing about this: the turns are already
-kept before it squashes.
+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
+squash 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 `gtd history fetch | sh`, then `gtd history show <ref>`.
 
 ```sh
 gtd history list                 # one line per kept process
@@ -614,7 +634,9 @@ gtd history fetch | sh           # pull every kept ref from origin
 ```
 
 `gtd history fetch` only prints a fetch script; pipe it into `sh` to run it.
-Refs are not pushed or fetched by default. To share them:
+Beyond that one ship push, 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:
 
 ```sh
 git push origin 'refs/gtd/history/*'
@@ -622,7 +644,9 @@ 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.
+`+`, 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
+(`git update-ref -d <ref>`) and fetches again.
 
 A step declared with `keep: true` files its turn under `refs/gtd/kept/` instead
 of on the branch (see [Kept tips](docs/configuration.md#kept-tips)). Those refs
@@ -670,7 +694,9 @@ listed in the
 `gtd slices` lists the spans a flow's `slice()` calls mark. It refuses (exit 1)
 when HEAD neither closes nor sits inside a process, or when today's config
 disagrees with history about the process; a version mismatch only warns on
-stderr.
+stderr. `gtd summary --slice <name>` prints the closing-message prompt for one
+of those slices — its own range, human commits and cost — and inherits those
+refusals; an unknown name is refused with every valid slice listed.
 
 ## License
 

package/claude/hooks/doors.ts

@@ -32,3 +32,15 @@ export async function enter(io: ShipIo, name: string, args: string[]): Promise<S
   if (started.code !== 0) return fail(`The door script failed.\n${started.err.trim()}`)
   return { ok: true, text: `Started ${name}.` }
 }
+
+// A door is entered only when the words fit its args; anything else is requirements.
+export function doorFor(
+  listed: readonly Door[],
+  verb: string,
+  args: readonly string[],
+): Door | undefined {
+  const door = listed.find((d) => d.name === verb)
+  if (!door) return undefined
+  const required = door.args.filter((a) => !a.optional).length
+  return args.length >= required && args.length <= door.args.length ? door : undefined
+}

package/claude/hooks/register.tsx

@@ -7,7 +7,7 @@ import type { AccessDef } from "./access"
 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 { doorFor, doors, enter } from "./doors"
 import { subagentModel } from "./models"
 import { pastedCommand } from "./paste"
 import { personaSpec, resumable } from "./persona"
@@ -824,9 +824,7 @@ async function command($: $, arg: string): Promise<string | undefined> {
     case "":
       return resume($)
     default:
-      return (await doors(shipIo($))).some((d) => d.name === verb)
-        ? enterNow($, verb, rest)
-        : begin($, arg)
+      return doorFor(await doors(shipIo($)), verb, rest) ? enterNow($, verb, rest) : begin($, arg)
   }
 }
 

package/claude/hooks/ship.ts

@@ -53,7 +53,7 @@ export function costTrailers(log: string) {
 // `gtd summary` is the only place gtd names the process's start parent.
 // `gtd base` is the review anchor and would squash only part of the process.
 const summaryRange = (summary: string) =>
-  /git log ([0-9a-f]{7,40})\.\.([0-9a-f]{7,40})/.exec(summary)?.slice(1, 3)
+  /git log ([0-9a-f]{7,64})\.\.([0-9a-f]{7,64})/.exec(summary)?.slice(1, 3)
 
 const COMMIT_FORMAT = `
 --- MESSAGE FORMAT (overrides any formatting the instructions above imply) ---
@@ -102,6 +102,18 @@ Nothing else. No file-by-file list, no per-commit narration, no implementation
 detail the diff already shows, no test-plan boilerplate, no sign-off, no footer
 trailers. Short headings and lists are fine. Under 250 words.`
 
+// 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 the
+// ship, not pass as an answer.
+const attempt = async (io: ShipIo, 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 ship(io: ShipIo, isDry: boolean): Promise<Shipped> {
   const git = async (...args: string[]) => (await io.run(["git", ...args])).out.trim()
   const ok = async (...args: string[]) => (await io.run(["git", ...args])).code === 0
@@ -125,7 +137,7 @@ export async function ship(io: ShipIo, isDry: boolean): Promise<Shipped> {
 
   const squashed = await squash(io, git, ok, branch, isDry)
   if (!squashed.ok) return squashed
-  if (isDry) return preview(io, git, branch, baseRef, squashed.text)
+  if (isDry) return preview(io, git, branch, baseRef, squashed.text, squashed.history)
   return pullRequest(io, git, ok, branch, baseBranch, baseRef)
 }
 
@@ -154,7 +166,7 @@ async function squash(
   ok: Ok,
   branch: string,
   isDry: boolean,
-): Promise<Shipped> {
+): Promise<Shipped & { history?: string }> {
   const summary = await io.run(["gtd", "summary"])
   if (summary.code !== 0) {
     io.log(`No gtd process at HEAD, so nothing is squashed; ${branch} is described as it stands.`)
@@ -172,24 +184,62 @@ async function squash(
   const { base, tip, count } = range
 
   // gtd churns its own steering files every process, so `.gtd/` alone is no change.
-  if (await ok("diff", "--quiet", base, "HEAD", "--", ":(exclude).gtd/")) {
-    if (isDry)
-      return { ok: true, text: `No file changes outside .gtd/: would drop ${count} commit(s).` }
-    if (!(await ok("reset", "--hard", base))) return fail("git reset failed; nothing changed.")
-    io.log(
-      `No file changes outside .gtd/: dropped ${count} commit(s). Undo with git reset --hard ORIG_HEAD.`,
-    )
-    return { ok: true, text: "" }
-  }
+  if (await ok("diff", "--quiet", base, "HEAD", "--", ":(exclude).gtd/"))
+    return dropProcess(io, ok, base, count, isDry)
 
   io.log(`Squashing ${count} commit(s) since ${short(base)}…`)
   const trailers = costTrailers(await git("log", "--format=%B%n", `${base}..${tip}`))
+  const history = await historyRef(io, tip)
+  if (history) trailers.push(`Gtd-History: ${history}`)
   const reply = await io.complete(summary.out + "\n" + COMMIT_FORMAT)
   const message = reply && cleanReply(reply)
   if (!message) return fail("The commit-message turn produced nothing.")
   const full = trailers.length ? `${message}\n\n${trailers.join("\n")}` : message
-  if (isDry) return { ok: true, text: full }
+  if (isDry) return { ok: true, text: full, history }
+
+  return commitSquash(io, git, ok, base, full, history)
+}
 
+async function dropProcess(
+  io: ShipIo,
+  ok: Ok,
+  base: string,
+  count: number,
+  isDry: boolean,
+): Promise<Shipped> {
+  if (isDry)
+    return { ok: true, text: `No file changes outside .gtd/: would drop ${count} commit(s).` }
+  if (!(await ok("reset", "--hard", base))) return fail("git reset failed; nothing changed.")
+  io.log(
+    `No file changes outside .gtd/: dropped ${count} commit(s). Undo with git reset --hard ORIG_HEAD.`,
+  )
+  return { ok: true, text: "" }
+}
+
+async function commitSquash(
+  io: ShipIo,
+  git: Git,
+  ok: Ok,
+  base: string,
+  full: string,
+  history: string | undefined,
+): Promise<Shipped> {
+  // Before the squash: a failure leaves the branch as it was, so a retry finds the process.
+  if (history) {
+    // Forced so a retry after the tip changed lands. The ref is keyed by the entry
+    // commit, which every clone of the process shares: a second clone shipping the
+    // same entry replaces origin's copy.
+    io.log(`Pushing ${history} to origin: the process's step commits become fetchable there.`)
+    const pushed = await attempt(io, ["git", "push", "origin", `+${history}:${history}`])
+    if (pushed.killed)
+      return fail(
+        `git push of ${history} did not finish; nothing was squashed. Retry.\n${pushed.err}`.trimEnd(),
+      )
+    if (pushed.code !== 0)
+      return fail(
+        `git push of ${history} failed; nothing was squashed or pushed.\n${pushed.err}`.trimEnd(),
+      )
+  }
   if (!(await ok("reset", "--soft", base))) return fail("git reset failed; nothing changed.")
   const commit = await io.run(["git", "commit", "--cleanup=strip", "-F", "-"], full + "\n")
   if (commit.code !== 0) {
@@ -203,7 +253,39 @@ async function squash(
   return { ok: true, text: "" }
 }
 
-async function preview(io: ShipIo, git: Git, branch: string, baseRef: string, message: string) {
+async function historyRef(io: ShipIo, tip: string) {
+  const list = await io.run(["gtd", "history", "list", "--json"])
+  let entries: { ref?: string; entry?: string; tip?: string }[] = []
+  try {
+    entries = JSON.parse(list.out)
+  } catch {
+    // unreadable list reads as no entry
+  }
+  // The ref becomes a refspec: push it only when it is exactly the full-sha
+  // name of its entry (40 hex, or 64 under SHA-256).
+  const found = Array.isArray(entries)
+    ? entries.find(
+        (e) =>
+          e.tip === tip &&
+          /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(e.entry ?? "") &&
+          e.ref === `refs/gtd/history/${e.entry}`,
+      )
+    : undefined
+  if (!found) {
+    io.log("No gtd history ref keeps this process: shipping without a Gtd-History trailer.")
+    return undefined
+  }
+  return found.ref
+}
+
+async function preview(
+  io: ShipIo,
+  git: Git,
+  branch: string,
+  baseRef: string,
+  message: string,
+  history?: string,
+) {
   const mergeBase = await git("merge-base", baseRef, "HEAD")
   const existing = await io.run(["gh", "pr", "view", "--json", "url"])
   const pr =
@@ -212,7 +294,11 @@ async function preview(io: ShipIo, git: Git, branch: string, baseRef: string, me
       : `would open a pull request for ${branch} into ${baseRef} (${await git("rev-list", "--count", `${mergeBase}..HEAD`)} commit(s) before the squash)`
   return {
     ok: true,
-    text: [message && `Commit message:\n\n${message}`, `Pull request: ${pr}.`]
+    text: [
+      message && `Commit message:\n\n${message}`,
+      history && `History: would push ${history} to origin.`,
+      `Pull request: ${pr}.`,
+    ]
       .filter(Boolean)
       .join("\n\n"),
   }
@@ -256,14 +342,23 @@ async function pullRequest(
 // the push failed, or nothing.
 export async function pushBranch(io: ShipIo, branch: string) {
   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 (!(await ok("rev-parse", "--verify", "--quiet", `origin/${branch}`))) {
     io.log(`Pushing ${branch} to origin…`)
-    if (!(await ok("push", "--set-upstream", "origin", branch))) return "git push failed."
-  } else if (!(await ok("merge-base", "--is-ancestor", "HEAD", `origin/${branch}`))) {
+    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…`)
-    if (!(await ok("push", "--force-with-lease", "origin", branch))) {
-      return `git push failed: origin/${branch} moved. Fetch and reconcile first.`
-    }
+    return push(
+      ["--force-with-lease", "origin", branch],
+      `git push failed: origin/${branch} moved. Fetch and reconcile first.`,
+    )
   }
   return undefined
 }