@pmelab/gtd 45.1.0 → 46.0.0

package/.claude-plugin/plugin.json

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

@@ -371,11 +371,15 @@ the top branch with `git push origin --delete`, since
 ask Claude to hand it off (or run `/gtd throw @dev`) and it opens a draft pull
 request assigned to them, and `/gtd catch <pr>` picks it up exactly where it
 waits, so whoever wrote the requirements can hand the build to someone else.
-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
+`/gtd pr` brings a pull request's unresolved review threads into the review:
+each becomes a note in `.gtd/REVIEW.md` ticked "fix as suggested" (untick it for
+"won't fix" plus a reason, or your own answer), the review door fixes them in
+place, and each thread then gets a reply naming the fixing commit (or your
+reason) and is resolved. Ship, hand-off and throw answer at once and run in the
+background, with progress on the status line; they report by waking Claude, a
+toast, a transcript line and a push notification, and a failed push or `gh` call
+reports as a failure. While a ship or hand-off runs or is queued, `/gtd catch`,
+the doors, `/gtd <requirements>` and bare `/gtd` wait for its report. See
 [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
@@ -737,21 +741,6 @@ hand or leave it for cleanup.
 
 The delivery model these workflows implement: [Delivery model](SDLC.md).
 
-### Reviving skipped tests
-
-The opt-in `tests` workflow revisits tests nobody runs. Export `tests` from
-`@pmelab/gtd/workflows/tests` and run `gtd door tests` (or
-`gtd --workflow tests`). On a green baseline an agent sweeps the whole
-repository — every skipped test plus the `test-audit` skill's findings — into
-`.gtd/TESTS.md`, one section per test file. Each file is then rewritten in its
-own turn until nothing in it is skipped and the suite is green. A test the agent
-calls obsolete stays skipped and is proposed for deletion: the review in
-`.gtd/REVIEW.md` gives each proposal `delete it`, `keep it skipped` or
-`_your answer_`, and refuses sign-off until each holds one tick. An agent turn
-that deletes a test file is refused. Skip detection is a factory option with
-JavaScript/TypeScript and cucumber defaults; see
-[Reviving skipped tests](docs/configuration.md#reviving-skipped-tests).
-
 ## Checking a range for stray files
 
 ```sh
@@ -890,15 +879,15 @@ approvals as `approvals` (`[]` when none), and `gtd history show` prints each as
 gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and
 [SemVer promise](https://github.com/pmelab/gtd/blob/main/COMPATIBILITY.md).
 
-| Import                                                                                                                                                                                        | What it is                                                                                                                                                                                             |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@pmelab/gtd/flows`                                                                                                                                                                           | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope` and `slice` (named spans of a process), workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                |
-| `@pmelab/gtd/wire`                                                                                                                                                                            | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                                           |
-| `@pmelab/gtd/steering`                                                                                                                                                                        | The steering-file formats (`qa`, `review`) and the review-note readers.                                                                                                                                |
-| `@pmelab/gtd/workflow-kit`                                                                                                                                                                    | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails.                                                                                  |
-| `@pmelab/gtd/workflows`                                                                                                                                                                       | Every shipped workflow and all its parts in one module; also resolvable as `@pmelab/gtd/workflow`.                                                                                                     |
-| `@pmelab/gtd/workflows/feature`, `@pmelab/gtd/workflows/review`, `@pmelab/gtd/workflows/fix`, `@pmelab/gtd/workflows/rollout`, `@pmelab/gtd/workflows/cleanup`, `@pmelab/gtd/workflows/tests` | One shipped workflow each: its factory as the default export, its parts, and the reserved exports (`defaults`, `envDefaults`, `summary`, `steering`, `skills`, `access`). `gtd install` imports these. |
-| `@pmelab/gtd/testkit`                                                                                                                                                                         | Runs any workflow against the real engine, in an in-memory or a real repository. Needs `vitest` and `quickpickle`, optional peer dependencies.                                                         |
+| Import                                                                                                                                                         | What it is                                                                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@pmelab/gtd/flows`                                                                                                                                            | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope` and `slice` (named spans of a process), workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                |
+| `@pmelab/gtd/wire`                                                                                                                                             | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                                           |
+| `@pmelab/gtd/steering`                                                                                                                                         | The steering-file formats (`qa`, `review`) and the review-note readers.                                                                                                                                |
+| `@pmelab/gtd/workflow-kit`                                                                                                                                     | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails.                                                                                  |
+| `@pmelab/gtd/workflows`                                                                                                                                        | Every shipped workflow and all its parts in one module; also resolvable as `@pmelab/gtd/workflow`.                                                                                                     |
+| `@pmelab/gtd/workflows/feature`, `@pmelab/gtd/workflows/review`, `@pmelab/gtd/workflows/fix`, `@pmelab/gtd/workflows/rollout`, `@pmelab/gtd/workflows/cleanup` | One shipped workflow each: its factory as the default export, its parts, and the reserved exports (`defaults`, `envDefaults`, `summary`, `steering`, `skills`, `access`). `gtd install` imports these. |
+| `@pmelab/gtd/testkit`                                                                                                                                          | Runs any workflow against the real engine, in an in-memory or a real repository. Needs `vitest` and `quickpickle`, optional peer dependencies.                                                         |
 
 Types come from the TypeScript sources the package ships. Configs never need an
 install for any of these but `./testkit`: gtd resolves a `gtd.config.ts`'s

package/claude/hooks/pr.ts

@@ -0,0 +1,342 @@
+// `/gtd pr`: a pull request's unresolved review threads become notes in the
+// review gate's file, and once the review door has acted on them each thread
+// gets a reply and is resolved. gtd itself never talks to GitHub: the mod
+// reads and writes the threads, and gtd only sees the notes.
+
+import type { PrFeedback, PrThread } from "../types"
+import { pushBranch } from "./ship"
+import type { ShipIo, Shipped } from "./ship"
+
+export const REVIEW_FILE = ".gtd/REVIEW.md"
+
+export type Pr = {
+  host: string
+  owner: string
+  name: string
+  number: number
+  url: string
+  branch: string
+}
+export type Thread = PrThread
+export type Choice = "fix" | "wontfix" | "answer"
+export type Answer = { thread: string; title: string; choice: Choice; text: string }
+
+const PR_URL = /^https?:\/\/([^/]+)\/([^/]+)\/([^/]+)\/pull\/(\d+)/
+// The thread's node id, tagged on the note's heading.
+const TAG = /\(thread ([A-Za-z0-9_=-]+)\)\s*$/
+const LEAD = "Tick exactly one:"
+const PLACEHOLDER = "_your answer_"
+
+const fail = (text: string): Shipped => ({ ok: false, text })
+
+export async function currentPr(io: ShipIo): Promise<Pr | string> {
+  const branch = (await io.run(["git", "rev-parse", "--abbrev-ref", "HEAD"])).out.trim()
+  const v = await io.run(["gh", "pr", "view", "--json", "number,url"])
+  if (v.code !== 0) return `gh pr view failed: ${v.err.trim()}`
+  try {
+    const { url } = JSON.parse(v.out) as { url: string }
+    const m = PR_URL.exec(url)
+    if (!m) return `gh pr view returned an unexpected url: ${url}`
+    return { host: m[1]!, owner: m[2]!, name: m[3]!, number: Number(m[4]), url, branch }
+  } catch {
+    return "gh pr view returned something unreadable."
+  }
+}
+
+const THREADS = `query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100) {
+        nodes {
+          id
+          isResolved
+          path
+          line
+          originalLine
+          comments(first: 50) { nodes { author { login } body url } }
+        }
+      }
+    }
+  }
+}`
+
+type ThreadNode = {
+  id: string
+  isResolved: boolean
+  path: string | null
+  line: number | null
+  originalLine: number | null
+  comments: { nodes: { author: { login: string } | null; body: string; url: string }[] }
+}
+
+export async function unresolvedThreads(io: ShipIo, pr: Pr): Promise<Thread[] | string> {
+  const r = await io.run([
+    "gh",
+    "api",
+    "graphql",
+    "--hostname",
+    pr.host,
+    "-f",
+    `query=${THREADS}`,
+    "-f",
+    `owner=${pr.owner}`,
+    "-f",
+    `name=${pr.name}`,
+    "-F",
+    `number=${pr.number}`,
+  ])
+  if (r.code !== 0) return `Reading the review threads failed: ${r.err.trim()}`
+  let nodes: ThreadNode[]
+  try {
+    nodes = JSON.parse(r.out).data.repository.pullRequest.reviewThreads.nodes as ThreadNode[]
+  } catch {
+    return "gh api returned something unreadable for the review threads."
+  }
+  return nodes
+    .filter((t) => !t.isResolved)
+    .map((t) => ({
+      id: t.id,
+      ...(t.path ? { path: t.path } : {}),
+      ...((t.line ?? t.originalLine) ? { line: (t.line ?? t.originalLine)! } : {}),
+      comments: t.comments.nodes.map((c) => ({
+        author: c.author?.login ?? "ghost",
+        body: c.body,
+        url: c.url,
+      })),
+    }))
+}
+
+// Code spans pass as they are; elsewhere only an entity hides a footnote
+// marker or a comment from gtd's raw-text checks.
+const escaped = (line: string) =>
+  line
+    .replace(/^((?:\s*>)*\s*(?:[-*+]|\d+[.)])\s+)\[([ xX])\]/, "$1\\[$2\\]")
+    .split(/(`+[^`]*`+)/)
+    .map((part, i) =>
+      i % 2 === 1 ? part : part.replace(/\[\^/g, "&#91;^").replace(/<!--/g, "&lt;!--"),
+    )
+    .join("")
+
+// The fence open after `line`, given the one open before it. A closing fence
+// carries no info string.
+const fenceAfter = (open: string | undefined, line: string) => {
+  const m = /^(?:\s*>)*\s*(`{3,}|~{3,})(.*)$/.exec(line)
+  if (!m) return open
+  const f = m[1]!
+  if (open === undefined) return f
+  return f[0] === open[0] && f.length >= open.length && !m[2]!.trim() ? undefined : open
+}
+
+// A comment is quoted, and anything that would parse as part of the review's
+// own structure — a task box, a footnote — is escaped. Code in a fence parses
+// as code, so a suggestion is kept verbatim.
+const quoted = (body: string) => {
+  let fence: string | undefined
+  return body
+    .trim()
+    .split(/\r?\n/)
+    .map((l) => {
+      const wasCode = fence !== undefined
+      fence = fenceAfter(fence, l)
+      return wasCode || fence !== undefined ? l : escaped(l)
+    })
+    .map((l) => (l ? `> ${l}` : ">"))
+    .join("\n")
+}
+
+const heading = (t: Thread) =>
+  `## ${t.path ? `${t.path}${t.line ? `:${t.line}` : ""}` : "Pull request review"} (thread ${t.id})`
+
+export function threadNote(t: Thread) {
+  const said = t.comments.map((c) => `**@${c.author}** ([comment](${c.url})):\n\n${quoted(c.body)}`)
+  return [
+    heading(t),
+    ...said,
+    "From the pull request. To decline it, tick won't fix and write your reason after it on that line.",
+    LEAD,
+    "- [x] fix as suggested\n- [ ] won't fix\n- [ ] _your answer_",
+  ].join("\n\n")
+}
+
+// The review with every thread it does not already hold appended, pre-ticked.
+export function withThreads(review: string, threads: readonly Thread[]) {
+  const held = new Set(chunks(review).flatMap((c) => (c.thread ? [c.thread] : [])))
+  const added = threads.filter((t) => !held.has(t.id)).map(threadNote)
+  return added.length === 0 ? review : `${review.trimEnd()}\n\n${added.join("\n\n")}\n`
+}
+
+type Chunk = { title: string; thread?: string; lines: string[] }
+
+// Every imported line is quoted, so a `## ` line is always a chunk's heading.
+function chunks(review: string): Chunk[] {
+  return review
+    .split(/^## /m)
+    .slice(1)
+    .map((part) => {
+      const [first = "", ...lines] = part.split(/\r?\n/)
+      const title = first.trim()
+      const thread = TAG.exec(title)?.[1]
+      return { title, ...(thread ? { thread } : {}), lines }
+    })
+}
+
+// An unindented line right below an item continues it, as markdown reads it.
+const continues = (line: string, afterBlank: boolean) => !afterBlank || /^\s+\S/.test(line)
+
+// The three answer boxes after the lead line, a wrapped item's continuation joined on.
+function boxes(lines: readonly string[]) {
+  const at = lines.findIndex((l) => l.trim() === LEAD)
+  if (at === -1) return undefined
+  const items: { checked: boolean; text: string }[] = []
+  let blank = false
+  for (const line of lines.slice(at + 1)) {
+    const m = /^[-*+] \[([ xX])\]\s*(.*)$/.exec(line)
+    const isText = line.trim() !== ""
+    if (m) items.push({ checked: m[1] !== " ", text: m[2]!.trim() })
+    else if (items.length > 0 && isText && continues(line, blank))
+      items.at(-1)!.text = `${items.at(-1)!.text} ${line.trim()}`.trim()
+    else if (items.length > 0 && isText) break
+    blank = !isText
+  }
+  return items
+}
+
+const reasonOf = (text: string) => text.replace(/^won['’]t fix\b[\s:,;.—–-]*/i, "").trim()
+
+export function answers(review: string): Answer[] {
+  return chunks(review).flatMap((c) => {
+    const b = c.thread ? boxes(c.lines) : undefined
+    if (!c.thread || b?.length !== 3) return []
+    const ticked = b.flatMap((o, i) => (o.checked ? [i] : []))
+    if (ticked.length !== 1) return []
+    const i = ticked[0]!
+    const choice = (["fix", "wontfix", "answer"] as const)[i]!
+    const own = b[2]!.text.toLowerCase() === PLACEHOLDER ? "" : b[2]!.text
+    const text = choice === "wontfix" ? reasonOf(b[1]!.text) : choice === "answer" ? own : ""
+    return [{ thread: c.thread, title: c.title, choice, text }]
+  })
+}
+
+// Thread notes declined without the reason their reply needs.
+export function missingReasons(review: string) {
+  return answers(review)
+    .filter((a) => a.choice === "wontfix" && a.text === "")
+    .map((a) => `${REVIEW_FILE}: "${a.title}": write the reason after "won't fix" on that line.`)
+}
+
+// The first commit since `since` whose review answers any of `ids`: the gate
+// that decided them. Undefined while none has landed.
+export async function decided(io: ShipIo, since: string, ids: readonly string[]) {
+  // A reset or rebase since the import leaves nothing to find the gate in.
+  if ((await io.run(["git", "merge-base", "--is-ancestor", since, "HEAD"])).code !== 0)
+    return "gone"
+  const log = await io.run([
+    "git",
+    "log",
+    "--reverse",
+    "--first-parent",
+    "--format=%H",
+    `${since}..HEAD`,
+  ])
+  if (log.code !== 0) return "gone"
+  for (const commit of log.out.split("\n").filter(Boolean)) {
+    const shown = await io.run(["git", "show", `${commit}:${REVIEW_FILE}`])
+    if (shown.code !== 0) continue
+    const got = answers(shown.out).filter((a) => ids.includes(a.thread))
+    if (got.length > 0) return { gate: commit, answers: got }
+  }
+  return undefined
+}
+
+export type PrRest = { isReviewGate: boolean; isDone: boolean; branch: string }
+
+// What a rest does with `/gtd pr`'s threads. Threads of another branch's pull
+// request never reach this one's review; a process that ends before any review
+// gate drops them.
+export function prAction(pr: PrFeedback | undefined, at: PrRest) {
+  if (!pr) return "none"
+  if (at.branch !== pr.branch) return "forget"
+  if (pr.importedAt === undefined) return at.isReviewGate ? "import" : at.isDone ? "forget" : "none"
+  return at.isReviewGate || at.isDone ? "reply" : "none"
+}
+
+// The fixes the gate asked for are the first turn after it, so its first code
+// commit is the fix; later ones belong to other notes or rounds.
+export function replyText(a: Answer, fix: string | undefined) {
+  if (a.choice === "wontfix") return a.text ? `Won't fix: ${a.text}` : "Won't fix."
+  if (a.choice === "answer") return a.text
+  return fix ? `Fixed in ${fix}.` : "Fixed as suggested; the fix changed no code."
+}
+
+const REPLY = `mutation($thread: ID!, $body: String!) {
+  addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $thread, body: $body }) { comment { id } }
+}`
+const RESOLVE = `mutation($thread: ID!) {
+  resolveReviewThread(input: { threadId: $thread }) { thread { isResolved } }
+}`
+
+// Pushes the branch so the commits a reply names exist on GitHub, then replies
+// to each answered thread and resolves it. The code commits after `gate` are
+// the fixes; a thread that fails is named and left open.
+export async function reply(
+  io: ShipIo,
+  host: string,
+  gate: string,
+  decidedAnswers: readonly Answer[],
+): Promise<Shipped & { isPushed: boolean }> {
+  const branch = (await io.run(["git", "rev-parse", "--abbrev-ref", "HEAD"])).out.trim()
+  const pushed = await pushBranch(io, branch)
+  if (pushed) return { ...fail(pushed), isPushed: false }
+  const log = await io.run([
+    "git",
+    "log",
+    "--reverse",
+    "--first-parent",
+    "--format=%H",
+    `${gate}..HEAD`,
+    "--",
+    ".",
+    ":(exclude).gtd",
+  ])
+  const fix = log.out.split("\n").find(Boolean)
+  const failed: string[] = []
+  for (const a of decidedAnswers) {
+    const sent = await io.run([
+      "gh",
+      "api",
+      "graphql",
+      "--hostname",
+      host,
+      "-f",
+      `query=${REPLY}`,
+      "-f",
+      `thread=${a.thread}`,
+      "-f",
+      `body=${replyText(a, fix)}`,
+    ])
+    const resolved =
+      sent.code === 0 &&
+      (
+        await io.run([
+          "gh",
+          "api",
+          "graphql",
+          "--hostname",
+          host,
+          "-f",
+          `query=${RESOLVE}`,
+          "-f",
+          `thread=${a.thread}`,
+        ])
+      ).code === 0
+    if (!resolved) failed.push(a.title)
+  }
+  const done = decidedAnswers.length - failed.length
+  const text = `Replied to and resolved ${done} review thread(s).`
+  return failed.length === 0
+    ? { ok: true, text, isPushed: true }
+    : {
+        ...fail(`${text}\nThese failed and stay open:\n${failed.map((t) => `- ${t}`).join("\n")}`),
+        isPushed: true,
+      }
+}

package/claude/hooks/register.tsx

@@ -10,6 +10,15 @@ import type { Io, Opening, Turn, TurnEnd } from "./drive"
 import { doorFor, doors, enter } from "./doors"
 import { subagentModel } from "./models"
 import { pastedCommand } from "./paste"
+import {
+  currentPr,
+  decided,
+  missingReasons,
+  reply,
+  REVIEW_FILE,
+  unresolvedThreads,
+  withThreads,
+} from "./pr"
 import { personaSpec, resumable } from "./persona"
 import { JUDGE_SYSTEM, judgePrompt, judgeQuestions, judgeRunEnv, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
@@ -277,8 +286,8 @@ async function start($: $, opening: Opening = {}) {
   moveOn($)
   stopRequested = false
   await findRoot($)
-  // Requests not yet handed to a rest outlive a restart.
-  await update($, run, (r) => ({ isRunning: true, beat: 0, notes: r.notes }))
+  // Requests not yet handed to a rest, and review threads not yet replied to, outlive a restart.
+  await update($, run, (r) => ({ isRunning: true, beat: 0, notes: r.notes, pr: r.pr }))
   void drive(io($), opening)
     .catch((err: unknown): Stop => ({ kind: "error", text: String(err) }))
     .then(async (stop) => {
@@ -290,6 +299,8 @@ async function start($: $, opening: Opening = {}) {
       const rest = restId(at.head, stop.state)
       await update($, run, (r) => ({ ...r, isRunning: false, stop, rest, isRepeat }))
       $.ui.status(undefined)
+      // Before the wake, so nothing the model starts there races the push.
+      await prRest($, stop)
       $.ui.toast(headline(stop))
       await push($, stop)
       await wake($)
@@ -502,6 +513,125 @@ async function enterNow($: $, door: string, args: string[]) {
   return entered.text
 }
 
+const isReviewGate = (stop: Stop | undefined) =>
+  stop?.kind === "gate" &&
+  !stop.isJudge &&
+  stop.file === REVIEW_FILE &&
+  /(^|\.)review\.await-review$/.test(stop.state ?? "")
+
+// The pull request's unresolved threads go into the review gate's file: now,
+// when gtd waits there, or through the review door at its first gate.
+async function prNow($: $) {
+  const r = await read($, run)
+  if (r.isRunning) return "Stop the loop first: /gtd stop."
+  if (r.pending) return "A continue is already waiting for this turn to end."
+  if (r.pr?.importedAt !== undefined) return retryReplies($, r.stop)
+  if (r.pr && !isReviewGate(r.stop)) {
+    return "Review threads from an earlier /gtd pr wait for the review's first review gate."
+  }
+  const io = shipIo($)
+  const pr = await currentPr(io)
+  if (typeof pr === "string") return pr
+  const threads = await unresolvedThreads(io, pr)
+  if (typeof threads === "string") return threads
+  if (threads.length === 0) return `${pr.url} has no unresolved review threads.`
+  await update($, run, (x) => ({ ...x, pr: { threads, host: pr.host, branch: pr.branch } }))
+  if (isReviewGate(r.stop)) {
+    await importThreads($)
+    return `Added ${threads.length} review thread(s) of ${pr.url} to ${REVIEW_FILE}, ticked fix as suggested.`
+  }
+  const entered = await enter(io, "review", [])
+  if (!entered.ok) {
+    await update($, run, (x) => ({ ...x, pr: undefined }))
+    return `${entered.text}\nRun /gtd pr at a review gate, or once nothing is underway.`
+  }
+  await start($)
+  return `Started a review of ${pr.url}; its ${threads.length} review thread(s) join the review.`
+}
+
+// Replies whose push failed are retried here, at a rest that sends them.
+async function retryReplies($: $, stop: Stop | undefined) {
+  // prRest, not a bare reply: threads of another branch must be dropped, never answered.
+  if (stop) {
+    await prRest($, stop)
+    if ((await read($, run)).pr === undefined) return "Done with the earlier review threads."
+  }
+  return "Review threads from an earlier /gtd pr still wait for their replies, sent at the next review gate or when the process ends; /gtd pr retries them there."
+}
+
+async function importThreads($: $) {
+  const pr = (await read($, run)).pr
+  if (!pr || pr.importedAt !== undefined) return
+  const path = `${root}/${REVIEW_FILE}`
+  const review = (await $.fs.exists(path)) ? await $.fs.read(path) : ""
+  await $.fs.write(path, withThreads(review, pr.threads))
+  const importedAt = await head($)
+  await update($, run, (x) => ({ ...x, pr: { ...pr, importedAt } }))
+}
+
+const forgetPr = ($: $) => update($, run, (x) => ({ ...x, pr: undefined }))
+
+// A failing import or reply is reported, never allowed to swallow the rest.
+async function guardedPr($: $, work: () => Promise<unknown>) {
+  try {
+    await work()
+  } catch (err) {
+    $.ui.log(`gtd pr: ${String(err)}`)
+    $.ui.toast("gtd pr: handling the review threads failed")
+  }
+}
+
+async function prRest($: $, stop: Stop) {
+  const pr = (await read($, run)).pr
+  if (!pr) return
+  const branch = (
+    await $.process.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], { cwd: root })
+  ).stdout.trim()
+  const action = prAction(pr, {
+    isReviewGate: isReviewGate(stop),
+    isDone: stop.kind === "done",
+    branch,
+  })
+  if (action === "forget") await forgetPr($)
+  if (action === "import") await guardedPr($, () => importThreads($))
+  if (action === "reply") await guardedPr($, () => replyThreads($, stop))
+}
+
+// Once a gate answered the imported threads and the process rests at a review
+// gate again or is done, each thread is replied to and resolved. Only a failed
+// push keeps them for the next rest.
+async function replyThreads($: $, stop: Stop) {
+  const pr = (await read($, run)).pr
+  if (!pr?.importedAt) return
+  const io = shipIo($)
+  const found = await decided(
+    io,
+    pr.importedAt,
+    pr.threads.map((t) => t.id),
+  )
+  if (found === "gone") {
+    $.ui.log("gtd pr: the history moved since the review threads were added; they get no replies.")
+    await forgetPr($)
+    return
+  }
+  if (!found) {
+    if (stop.kind === "done") await forgetPr($)
+    return
+  }
+  // Nothing has acted on the answers yet, unless the process already ended.
+  if (stop.kind !== "done" && found.gate === (await head($))) return
+  $.ui.status("replying to the review threads…")
+  let replied
+  try {
+    replied = await reply(io, pr.host, found.gate, found.answers)
+  } finally {
+    $.ui.status(undefined)
+  }
+  for (const line of replied.text.split("\n")) $.ui.log(line)
+  $.ui.toast(replied.text.split("\n")[0]!)
+  if (replied.isPushed) await forgetPr($)
+}
+
 // Picks the process up where it was thrown: a rest that waits on a person is
 // shown to the catcher first, never landed unseen.
 async function catchNow($: $, ref: string) {
@@ -743,8 +873,15 @@ async function proceed(
   return undefined
 }
 
-// The rest's own `gtd validate` script, run.
+// The rest's own `gtd validate` script, run; a declined review thread needs
+// the reason its reply carries.
 async function validateRest($: $) {
+  const r = await read($, run)
+  if (r.pr?.importedAt !== undefined && isReviewGate(r.stop)) {
+    const path = `${root}/${REVIEW_FILE}`
+    const missing = (await $.fs.exists(path)) ? missingReasons(await $.fs.read(path)) : []
+    if (missing.length > 0) return { ok: false, out: missing.join("\n") }
+  }
   const script = await gtd($, ["validate"])
   if (script.trim().startsWith("nothing to validate")) return { ok: true, out: "" }
   const v = await $.process.run(["sh", "-c", script], { cwd: root, timeoutMs: TEN_MINUTES })
@@ -872,10 +1009,16 @@ async function command($: $, arg: string): Promise<string | undefined> {
     case "":
       return resume($)
     default:
-      return doorFor(await doors(shipIo($)), verb, rest) ? enterNow($, verb, rest) : begin($, arg)
+      return routed($, verb, rest, arg)
   }
 }
 
+// A door wins over the bare `pr` verb; anything else is requirements.
+async function routed($: $, verb: string, rest: string[], arg: string) {
+  if (doorFor(await doors(shipIo($)), verb, rest)) return enterNow($, verb, rest)
+  return verb === "pr" && rest.length === 0 ? prNow($) : begin($, arg)
+}
+
 async function resume($: $) {
   const b = await docs($).next()
   if (isTrue(b.idle)) {
@@ -1020,7 +1163,7 @@ export const register: Register = (on) => {
       name: "gtd",
       description: "Drive gtd until it rests on you; pass requirements to start a new process",
       argumentHint:
-        "[requirements | <door> [args] | stop | status | ui | ship [-n] | throw [@user] | catch <pr|branch>]",
+        "[requirements | <door> [args] | stop | status | ui | ship [-n] | pr | throw [@user] | catch <pr|branch>]",
       immediate: true,
     })
     return next(e)

package/claude/types/index.d.ts

@@ -10,6 +10,20 @@ export type Stop = {
   mode?: string
 }
 
+export type PrThread = {
+  id: string
+  path?: string
+  line?: number
+  comments: { author: string; body: string; url: string }[]
+}
+
+export type PrFeedback = {
+  threads: PrThread[]
+  host: string
+  branch: string
+  importedAt?: string
+}
+
 export type Run = {
   isRunning: boolean
   beat: number
@@ -33,6 +47,10 @@ export type Run = {
   inflight?: { agentId: string; memory: string }
   // a script (beat or landing) is running, so a reload must not run it again
   isScripting?: boolean
+  // `/gtd pr`'s review threads, for the pull request of `branch`;
+  // `importedAt` is HEAD when they were written into the review gate's file,
+  // and the replies wait on a gate after it
+  pr?: PrFeedback
 }
 
 declare module "claude-code" {