@pmelab/gtd 29.3.0 → 30.0.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -74,8 +74,8 @@ autonomously run the process for you. Ask your agent if you have any questions.
   misreading it — see
   [History format](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#history-format).
 - **Files, not chat.** Conversation lives in files like `REQUIREMENTS.md` or
-  `ARCHITECTURE.md`. Request changes by editing them, approve by leaving the
-  tree clean — all in your own editor. There is no chat UI that could flicker.
+  `REVIEW.md`. Request changes by editing them, approve by leaving the tree
+  clean — all in your own editor. There is no chat UI that could flicker.
 - **Harness agnostic.** gtd emits prompts to stdout (or JSON). Claude Code, a
   bash loop, a CI job, or you reading it out loud to your sentient cat — the
   workflow doesn't care who executes it.
@@ -341,24 +341,26 @@ 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; a closed pull request whose branch was
-deleted from origin is left behind and a new one opens; 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; to tear a stack down from its worktree, delete the top branch with
+`Closes #N` on its top pull request; a later process on an already-stacked
+branch, such as review fixes, lands one commit per slice on the top pull request
+and keeps the stack; a closed pull request whose branch was deleted from origin
+is left behind and a new one opens; 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; to tear a
+stack down from its worktree, delete the top branch with
 `git push origin --delete`, since `gh pr close --delete-branch` cannot). 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 can hand the build 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
@@ -409,36 +411,26 @@ noted in steps 3 and 4 below.
 1. **You sketch.** Change anything, or write the idea into `.gtd/TODO.md`. Rough
    is fine; it is treated as a sketch, not as work.
 2. **You answer questions and discuss.** Planning works out what the thing
-   should do first, then how it should be built, and hands you a file at either
-   point — every process stops there, even with no open question. Answer open
-   questions in your editor, in the file, and start the loop again; a round that
-   only leaves notes needs no tick. Start a footnote with `- H: <question>` to
-   ask something: the agent replies with `- A: <reply>` and the process stops at
-   the same gate again. Close a thread by replying with a conclusion or deleting
-   it. While a thread's last entry is the agent's, moving on is refused. Leave
-   the file untouched and start the loop to accept the plan as-is, unanswered
-   questions and all. Every plan gets the technical pass: its document has four
-   sections, in order — `## Interfaces`, `## Call Stacks`, `## E2E Scenarios`,
-   `## Unit Tests` — behind a leading `## Open Questions` when there are any.
-   `## E2E Scenarios` is never empty: it names each user-visible behaviour in
-   plain words (the builder writes the scenario itself), or, when nothing
-   user-visible changes, the line `No e2e change.` with a one-line reason.
-
-3. **You wait.** The work is split into vertical slices and built one at a time,
-   each one starting from the unit and e2e tests it declares (a build turn
-   missing one is refused; a test the package only relies on is marked
-   `(unchanged)`; it must exist before the turn, and the build turn must not
-   create, edit or delete it — a wrong marker is fixed upstream, in the plan,
-   and a process stuck on one is ended with `gtd abandon`; and a package whose
-   work lies outside the repository, such as filing issues, closes on recorded
-   evidence), checked against the full suite (`testCommand`) and fixed until it
-   passes before moving on — so keep that suite fast; gtd has no lighter one.
-   Scenario wording is not frozen: you sign the scenarios off once, in the
-   review's `## Scenarios` chunk, where any assertion an existing scenario lost
-   is marked `Weakened:`. After the last package the quality lap runs. Two
-   points along the process are judged rather than always asking you outright —
-   each stops and hands you a verdict to make (`gtd judge answer`, or land with
-   a clean tree to accept the conservative default, which never skips work;
+   should do and hands you `.gtd/REQUIREMENTS.md` — every process stops there,
+   even with no open question. Answer open questions in your editor, in the
+   file, and start the loop again; a round that only leaves notes needs no tick.
+   Start a footnote with `- H: <question>` to ask something: the agent replies
+   with `- A: <reply>` and the process stops at the same gate again. Close a
+   thread by replying with a conclusion or deleting it. While a thread's last
+   entry is the agent's, moving on is refused. Leave the file untouched and
+   start the loop to accept the plan as-is, unanswered questions and all.
+
+3. **You wait.** The agent first implements the requirements the quickest way
+   that works — the naive pass — and a judge reads where it changed code (see
+   [the naive pass](#the-naive-pass) below). Then the change is built
+   test-first, checked against the full suite (`testCommand`) and fixed until it
+   passes — so keep that suite fast; gtd has no lighter one. Scenario wording is
+   not frozen: you sign the scenarios off once, in the review's `## Scenarios`
+   chunk, where any assertion an existing scenario lost is marked `Weakened:`.
+   After the build the quality lap runs. Three points along the process are
+   judged rather than always asking you outright — each stops and hands you a
+   verdict to make (`gtd judge answer`, or land with a clean tree to accept the
+   conservative default, which never skips work;
    `gtd judge run --provider fixed --answers <path>` — or the
    `GTD_JUDGE_ANSWERS` env var, inline JSON — answers one from a file, piped
    between `gtd judge --json` and `gtd judge answer`;
@@ -453,6 +445,8 @@ noted in steps 3 and 4 below.
    choose the judge without editing the driver (flags win over both, in that
    order); `--model` with `--provider fixed`/`jev` is refused. jev and llm exit
    1 with nothing on stdout when they cannot answer every question):
+   - After the naive pass: does it land as is, need its seam refactored first,
+     or get rejected and retried?
    - Every red round after the first: was the failure identical, new, or
      progress?
    - After you review: is each of your notes an edit, a question, a nit or
@@ -467,8 +461,8 @@ noted in steps 3 and 4 below.
    measured probability, so a confidently wrong verdict can clear the 0.7 floor
    and skip a gate unattended.**
 
-   Once the last package is built, the whole change goes through a qualitative
-   review lap before you see anything: six lenses, one turn each, in order —
+   Once the change is built, the whole change goes through a qualitative review
+   lap before you see anything: six lenses, one turn each, in order —
    `correctness`, `owasp-security`, `ponytail-review`, `test-audit`,
    `conventions`, `spec-challenge`. Each traces the change from its own angle
    and records every finding, blocking or not; one fix turn then fixes ALL of
@@ -495,14 +489,14 @@ noted in steps 3 and 4 below.
    you unfixed; risk: a fix lands with no check that the risk was real. Tick the
    boxes to approve, or write what is wrong. Approving ends the process;
    feedback is judged note by note, each as `edit`, `question`, `nit` or
-   `praise`. An `edit` sends the process back to step 2 for a fresh plan — it
-   never patches over a design you rejected. A `question` is answered inline
-   under your note and the process stops at the review again — no new plan. A
-   `nit` is fixed in one batch, the suite must go green (a red one gets fix
-   turns first), then a fresh review of the change stops at the review again.
-   `praise` is dropped; a round of only praise signs off. When a round mixes
-   them, questions are answered and nits fixed first, then the edits are planned
-   — risk: the planning lap may redo nit fixes it touches.
+   `praise`. An `edit` sends the process back to step 2 for re-derived
+   requirements, and the implementation is amended to meet them. A `question` is
+   answered inline under your note and the process stops at the review again —
+   no new plan. A `nit` is fixed in one batch, the suite must go green (a red
+   one gets fix turns first), then a fresh review of the change stops at the
+   review again. `praise` is dropped; a round of only praise signs off. When a
+   round mixes them, questions are answered and nits fixed first, then the edits
+   are planned — risk: the planning lap may redo nit fixes it touches.
 
    Each `edit` note also gets a severity tier from four judge questions
    (security, reversibility, blast radius, new concept). `critical` and `should`
@@ -521,8 +515,8 @@ noted in steps 3 and 4 below.
 
 You never talk to it. Every exchange is a file in `.gtd/` that you edit in your
 own editor, and every answer you give is a commit. Your test suite is the gate
-throughout: a red baseline stops the process before it starts, and a red package
-is fixed before the next one begins.
+throughout: a red baseline stops the process before it starts, and a red build
+is fixed before review.
 
 Prefer a phone or another device over your editor? `gtd ui` opens the file whose
 turn it is as a small web app, over Tailscale — including a step that names no
@@ -582,11 +576,12 @@ unknown key. `gtd.config.ts` is the only repository config: gtd 23 removed the
 home directory — fails every command until you delete it. See
 [Migrating from `.gtdrc`](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#migrating-from-gtdrc).
 
-**Naive pass (flag `GTD_FLAG_NAIVE_PASS=1`, off by default).** Instead of an
-architecture and package files, the agent first implements the requirements
-directly. A judge checks whether it changed anything outside the expected set
-(tests, steering files; see `seamAllow`). Incidental changes land; a needed seam
-change is refactored first, in its own slice with its own quality lap
+#### The naive pass
+
+After design the agent first implements the requirements directly. A judge
+checks whether it changed anything outside the expected set (tests, steering
+files; see `seamAllow`). Incidental changes land; a needed seam change is
+refactored first, in its own slice with its own quality lap
 (`refactorQualityReviews`) and review, before the feature is implemented and
 reviewed; a wrong approach is retried twice, then rests for you to steer or
 overrule it. `gtd slices` lists the `refactor` and `feature` slices. A refactor
@@ -600,14 +595,13 @@ out is `gtd abandon`. A process from 27.5.0 or later whose judge ruled
 that slice. Details in
 [the naive-pass path](docs/configuration.md#the-naive-pass-path).
 
-**Risk tier (flag `GTD_FLAG_RISK_TIER=1`, off by default, needs
-`GTD_FLAG_NAIVE_PASS=1`).** Triage proposes a risk tier, `low` or `high`, and
-the production signals to watch after merge. Edit the first word under
-`## Risk Tier` at the design gate to change it; a missing or unreadable tier
-means `high`. Each lap lands a `Gtd-Mark: risk-tier=<low|high>` trailer and a
-`Gtd-Mark: production-signal=…` trailer per signal; `gtd summary` reads the last
-lap's only. Its "needs a human reviewer" line for `high` is advisory, not a
-gate.
+**Risk tier (flag `GTD_FLAG_RISK_TIER=1`, off by default).** Triage proposes a
+risk tier, `low` or `high`, and the production signals to watch after merge.
+Edit the first word under `## Risk Tier` at the design gate to change it; a
+missing or unreadable tier means `high`. Each lap lands a
+`Gtd-Mark: risk-tier=<low|high>` trailer and a `Gtd-Mark: production-signal=…`
+trailer per signal; `gtd summary` reads the last lap's only. Its "needs a human
+reviewer" line for `high` is advisory, not a gate.
 
 A `gtd.config.ts` call to `buildTail` or `tail` that fits neither call form is
 rejected; `tail`'s positional form is deprecated for `tail(finish, options?)`.

package/claude/hooks/ship.ts

@@ -495,8 +495,7 @@ async function squash(
   if (!msgs.ok) return msgs
   const { fulls, history } = msgs
   const warn = () => (mode === "commits" && many ? rebaseWarning(io) : undefined)
-  if (resume?.links)
-    return squashOntoStack(io, git, ok, groups[0]!, fulls[0]!, history, resume, isDry, tip)
+  if (resume?.links) return squashOntoStack(io, git, ok, groups, fulls, history, resume, isDry, tip)
   if (isDry)
     return dryRun(
       groups,
@@ -552,18 +551,21 @@ async function stackReads(
   mode: ShipMode,
 ): Promise<Resumed | string | undefined> {
   if (mode !== "stack") return undefined
-  if (groups.length > 1) return await stackPrecheck(io, git, ok, branch, baseBranch, groups)
+  if (groups.length > 1)
+    return await stackPrecheck(io, git, ok, branch, baseBranch, groups, base, isDry)
   return resumable(io, git, ok, branch, baseBranch, isDry, base)
 }
 
-// One slice on a recorded stack: its commit becomes the new top of the stack, and
-// the record, including the recorded top the missing-branch fallbacks read, stays.
+// A process on a recorded stack — a re-ship, or a follow-up such as review fixes —
+// lands its slice commits on the top branch, so they join the top pull request.
+// The record, including the recorded top the missing-branch fallbacks and the
+// restack read, stays.
 async function squashOntoStack(
   io: ShipIo,
   git: Git,
   ok: Ok,
-  group: Group,
-  full: string,
+  groups: Group[],
+  fulls: string[],
   history: string | undefined,
   resume: Resumed,
   isDry: boolean,
@@ -572,16 +574,16 @@ async function squashOntoStack(
   const links = resume.links!
   const top = links.length - 1
   if (isDry) {
-    const messages = links.map((_, i) => (i === top ? full : ""))
-    return {
-      ...dryRun([group], [full], history, undefined, links),
-      messages,
-      restack: resume.restack,
-    }
+    // the follow-up's slice names are not stack slices: no [name] headers
+    const messages = links.map((_, i) => (i === top ? fulls.join("\n\n") : ""))
+    return { ok: true as const, text: "", history, stack: links, messages, restack: resume.restack }
   }
   const pushed = await pushHistory(io, history)
   if (pushed) return fail(pushed)
-  const one = await commitSquash(io, git, ok, group.base, full)
+  const one =
+    groups.length === 1
+      ? await commitSquash(io, git, ok, groups[0]!.base, fulls[0]!)
+      : await commitChain(io, git, ok, groups, fulls)
   if (!one.ok) return one
   const failed = await resume.revive?.()
   if (failed) return fail(failed)
@@ -709,24 +711,30 @@ async function takenSlice(git: Git, ok: Ok, branch: string, groups: Group[], dea
   return undefined
 }
 
-async function recordedRefusal(
+// A live record takes the process onto its top branch; a dead one (no links)
+// leaves the way open for a fresh stack.
+async function liveRecord(
   io: ShipIo,
   git: Git,
   ok: Ok,
   branch: string,
   baseBranch: string,
   recorded: string[],
-): Promise<string | undefined> {
-  // The staleness test a resume uses: a dead record is not a live stack.
+  base: string,
+  isDry: boolean,
+): Promise<Resumed | string> {
+  // The staleness test a resume uses, without the restack's origin and worktree
+  // reads: a dead record is not a live stack, and its dropped-record line is
+  // silenced since a fresh stack replaces it.
   const quiet = { ...io, log: () => {} }
   const found = await resumable(quiet, git, ok, branch, baseBranch, true, "HEAD", false)
   // resumable refuses (a missing branch, a closed slice PR) before it tests the
   // chain; only a record that still chains to HEAD may refuse a fresh stack.
-  if (typeof found === "string")
-    return (await chainsToHead(git, ok, branch, recorded)) ? found : undefined
-  if (!found.forget)
-    return `${branch} already has a recorded stack (${recorded.join(", ")}); nothing changed. Ship with GTD_SHIP_MODE=commits, or run git config --local --unset branch.${branch}.gtdStack and git config --local --unset branch.${branch}.gtdStackTop, delete or rename the ${branch}-<slice> branches, then ship again.`
-  return undefined
+  if (typeof found === "string") return (await chainsToHead(git, ok, branch, recorded)) ? found : {}
+  // `forget` with links is a live stack a restack ends, not a dead record.
+  if (!found.links) return {}
+  // Live: any refusal of the full resume (origin, worktrees) stands.
+  return resumable(io, git, ok, branch, baseBranch, isDry, base)
 }
 
 async function chainsToHead(git: Git, ok: Ok, branch: string, recorded: string[]) {
@@ -760,11 +768,14 @@ async function stackPrecheck(
   branch: string,
   baseBranch: string,
   groups: Group[],
-): Promise<string | undefined> {
+  base: string,
+  isDry: boolean,
+): Promise<Resumed | string | undefined> {
   const recorded = names(await git("config", "--local", "--get", STACK_KEY(branch)))
   if (recorded.length) {
-    const refused = await recordedRefusal(io, git, ok, branch, baseBranch, recorded)
-    if (refused) return refused
+    const live = await liveRecord(io, git, ok, branch, baseBranch, recorded, base, isDry)
+    // Without links the squash builds a fresh stack, so the collision checks still run.
+    if (typeof live === "string" || live?.links) return live
   }
   const retired = names(await git("config", "--local", "--get", RETIRED_KEY(branch)))
   const taken = await takenSlice(git, ok, branch, groups, [...recorded, ...retired])