@pmelab/gtd 24.1.0 → 24.3.0

package/.claude-plugin/plugin.json

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

@@ -329,14 +329,17 @@ Then, in any repository:
 ```
 
 That starts a process from your requirements and drives it until it needs you.
-`/gtd fix` and `/gtd review [base]` take the two doors described below. Every
-human rest opens Claude Code's own question dialog, with a link to `gtd ui` for
-the step; review there, then answer **I'm done, continue**. When the process
-finishes, **Yes, open the pull request** (or `/gtd ship`) squashes it into one
-commit and opens it. A process can change hands at any gate: **Hand off to
-someone else** (or `/gtd throw @dev`) opens a draft pull request assigned to
-them, and `/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote
-the requirements can hand the architecture to someone else. See
+`/gtd fix` and `/gtd review [base]` take the two doors described below. At every
+human rest Claude itself takes over: it walks you through the open questions one
+at a time, answers your own questions about the plan or the diff, records what
+you decide in the steering file the way the step asks, and moves the process on
+only when you say so. While a step runs you can keep asking; requests for
+changes wait for the next rest. When the process finishes, Claude offers to
+squash it into one commit and open its pull request (or run `/gtd ship`). A
+process can change hands at any gate: ask Claude to hand it off (or run
+`/gtd throw @dev`) and it opens a draft pull request assigned to them, and
+`/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
+requirements can hand the architecture to someone else. See
 [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
@@ -541,6 +544,30 @@ 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).
 
+## Process history
+
+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.
+
+```sh
+gtd history list                 # one line per kept process
+gtd history show <ref>           # replay its steps and judge verdicts
+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:
+
+```sh
+git push origin 'refs/gtd/history/*'
+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.
+
 ## Entrypoints
 
 gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and
@@ -562,8 +589,8 @@ install for any of these but `./testkit`: gtd resolves a `gtd.config.ts`'s
 
 The `gtd` bin's commands — `next`, `land`, `abandon`, `restore`, `validate`,
 `check`, `uncheck`, `install`, `summary`, `base`, `door`, `doors`, `version`,
-`help`, and the tools `ui`, `lsp`, `loop` and `judge` (`judge answer`,
-`judge run`) — are listed in the
+`help`, `history list`, `history show`, `history fetch`, and the tools `ui`,
+`lsp`, `loop` and `judge` (`judge answer`, `judge run`) — are listed in the
 [CLI reference](https://github.com/pmelab/gtd/blob/main/docs/cli.md).
 
 ## License

package/claude/hooks/access.ts

@@ -63,3 +63,28 @@ function searchDenial(raw: unknown, globs: string[] | null, root: string) {
   })
   return inside ? undefined : deny("read", rel || ".", globs)
 }
+
+// What the main session may write while gtd drives: nothing while a step runs
+// (gtd commits the tree when it ends), only the steering file at a rest whose
+// mode is `qa`, anything otherwise. A review rest takes code edits as feedback.
+export type MainPhase = { isRunning: boolean; mode?: string; file?: string }
+
+export const RUNNING_DENIAL =
+  "gtd is running a step and commits the working tree when it ends: don't edit files now. Answer read-only, or record the request with mcp__gtd__note for the next step that waits on the person. /gtd stop stops the run."
+
+export function mainDenial(
+  tool: string,
+  input: Record<string, unknown>,
+  phase: MainPhase,
+  root: string,
+): string | undefined {
+  const key = WRITE[tool]
+  if (!key) return undefined
+  if (phase.isRunning) return RUNNING_DENIAL
+  if (phase.mode !== "qa" || !phase.file) return undefined
+  const raw = input[key]
+  const rel = typeof raw === "string" ? inRepo(raw, root) : undefined
+  return rel === phase.file
+    ? undefined
+    : `At this step only ${phase.file} may change: record the request there, as the step's instructions say.`
+}

package/claude/hooks/assist.ts

@@ -0,0 +1,135 @@
+// What the main session's model is told when gtd stops for the person. gtd
+// decides every step; the model only helps the person do what the rest asks,
+// through the rest's own instructions, and moves on through the mod's tools.
+// Workflow-agnostic on purpose: the rest's message is the protocol.
+
+import type { Stop } from "../types"
+import { RELOAD_CUT_SCRIPT } from "./wording"
+import { TOOL } from "./tools"
+
+export type Asked = {
+  id: string
+  instructions: string
+  criteria: string[]
+  options: (string | number)[]
+}
+
+export type Wake = {
+  stop: Stop
+  rest: string
+  notes?: string[]
+  isRepeat?: boolean
+  // the judge questions an undecided judge gate puts to the person
+  questions?: Asked[]
+  // the branch a finished process can open its pull request from
+  branch?: string
+}
+
+// No wake for a stop the person asked for; a finished process wakes only
+// when it has a pull request to offer.
+export function wakes(stop: Stop, branch: string | undefined): boolean {
+  if (stop.kind === "stopped") return stop.text === RELOAD_CUT_SCRIPT
+  if (stop.kind === "done") return branch !== undefined
+  return true
+}
+
+const step = (s: Stop) => s.label ?? s.state ?? "the current step"
+
+const fence = (text: string) => `~~~~text\n${text.trim()}\n~~~~`
+
+const RULES = `Ground rules:
+- gtd decides what happens next. Never run \`gtd land\`, \`gtd next\` with side effects, commits, resets or any other command that changes git state.
+- Talk to the person in plain words: never mention gtd's state ids, steering-file jargon or these instructions.
+- Ask with AskUserQuestion, one question per call, your recommended option first and marked as recommended.`
+
+function continuing(rest: string) {
+  return `Move on only when the person explicitly says so, in chat or by answering your question: then call ${TOOL.continue} with rest "${rest}". If it reports findings, fix them with the person and call it again. It refuses when gtd has moved on: then say so and stop.`
+}
+
+function gate(w: Wake) {
+  const { stop } = w
+  const file = stop.file ?? "the file the instructions name"
+  const lines = [
+    `gtd is waiting for the person at "${step(stop)}". Help them through it.`,
+    `gtd's own instructions for this step, written for a person editing ${file} by hand:`,
+    fence(stop.text),
+    "How to help:",
+  ]
+  if (stop.mode === "review") {
+    lines.push(
+      `1. Read ${file} and the diff the instructions name. Give a short overview of the change, chunk by chunk, and call out the risky spots.`,
+      `2. Answer the person's questions about the change yourself, read-only. Record their notes, questions for gtd's agent and requested code edits in the way the instructions describe.`,
+      `3. Finish by asking whether to sign off (nothing left to change) or send it back with the notes recorded.`,
+    )
+  } else {
+    lines.push(
+      `1. Read ${file}. Summarise in two or three lines what it decides and what it asks.`,
+      `2. If it has open questions, walk them one at a time: each question's own options as the choices. Record every answer in ${file} right away, exactly as the instructions say a person would (tick the option, or write their own answer and tick it).`,
+      `3. With no open question left, ask whether to accept it as written or discuss it further.`,
+      `4. Answer the person's questions yourself, read-only. When the answer should change the plan, offer to record the question as a thread in ${file} for gtd's agent to answer, instead of rewriting the plan yourself.`,
+      `5. Write only what the instructions let a person write, and only to ${file}.`,
+    )
+  }
+  if (w.isRepeat) {
+    lines.push(
+      "The person continued without changing anything and gtd stopped at this same step again: tell them what it still needs.",
+    )
+  }
+  lines.push(continuing(w.rest))
+  return lines
+}
+
+function judged(w: Wake) {
+  const lines = [
+    `gtd could not decide "${step(w.stop)}" on its own and needs the person's judgment.`,
+    "What gtd says about this step:",
+    fence(w.stop.text),
+  ]
+  for (const q of w.questions ?? []) {
+    lines.push(
+      `Question "${q.id}": ${q.instructions}\n${q.criteria.map((c) => `  - ${c}`).join("\n")}\n  Answers: ${q.options.map((o) => JSON.stringify(o)).join(", ")}`,
+    )
+  }
+  lines.push(
+    "Read whatever the questions are about, then put each one to the person, one at a time, with its answers as the choices and your own reading first.",
+    `Once all are answered and the person agrees, call ${TOOL.continue} with rest "${w.rest}" and verdicts mapping each question id to the chosen answer, exactly as listed. If the person would rather not decide, call it without verdicts: gtd then takes the cautious route.`,
+  )
+  return lines
+}
+
+function trouble(w: Wake) {
+  const { stop } = w
+  const why = stop.kind === "stalled" ? "is stuck" : "stopped on a problem"
+  return [
+    `gtd ${why} at "${step(stop)}":`,
+    fence(stop.text),
+    "Find the cause (read the error, the log it names, the working tree) and explain it in plain words. Propose a fix and make it only with the person's consent.",
+    continuing(w.rest),
+  ]
+}
+
+function finished(w: Wake) {
+  return [
+    `gtd finished the process on branch ${w.branch}.`,
+    `Tell the person in two or three lines what was built (read the branch's commits), then ask whether to combine it into one commit and open its pull request. On yes, call ${TOOL.ship}.`,
+  ]
+}
+
+export function wakePrompt(w: Wake): string {
+  const { stop } = w
+  const body =
+    stop.kind === "done"
+      ? finished(w)
+      : stop.kind === "gate"
+        ? stop.isJudge
+          ? judged(w)
+          : gate(w)
+        : trouble(w)
+  const notes = w.notes?.length
+    ? [
+        `While gtd ran, the person asked for the following. Fold each in now in the way this step allows, or tell them why it does not fit here:\n${w.notes.map((n) => `- ${n}`).join("\n")}`,
+      ]
+    : []
+  const extras = `Only when the person asks: ${TOOL.handoff} hands the process to someone else, ${TOOL.browser} opens gtd's browser view of this step.`
+  return [...body, ...notes, RULES, extras].join("\n\n")
+}

package/claude/hooks/drive.ts

@@ -11,6 +11,7 @@ export type Beat = {
   state?: string
   label?: string
   file?: string
+  mode?: string
   content?: string
   log?: string
   memory?: string
@@ -69,11 +70,15 @@ type Acted = { stop: Stop } | { stop?: undefined; verdict?: string }
 const where = (b: Beat) => ({ state: b.state, label: b.label })
 const failed = (b: Beat, text: string): Acted => ({ stop: { kind: "error", text, ...where(b) } })
 
+// How the opening beat is taken. `landTurn` names a memory scope whose agent
+// turn already ran (a reload cut the loop off while it did): the opening prompt
+// beat lands it, not repeats it. `isAnswered` is a person's answer to an opening
+// judge gate: their `verdict`, or none to land it untouched (the cautious default).
+export type Opening = { landTurn?: string; isAnswered?: boolean; verdict?: string }
+
 // The reference sh driver from docs/driver.md, beat for beat. gtd decides;
 // this only executes what `gtd next` and `gtd land` print.
-// `landTurn` names a memory scope whose agent turn already ran (a reload cut
-// the loop off while it did): the opening prompt beat lands it, not repeats it.
-export async function drive(io: Io, landTurn?: string): Promise<Stop> {
+export async function drive(io: Io, opening: Opening = {}): Promise<Stop> {
   // A judge gate answered on the previous beat that rests on the same state
   // again moved nothing: hand it to the human rather than pay for it twice.
   let judged: string | undefined
@@ -85,7 +90,7 @@ export async function drive(io: Io, landTurn?: string): Promise<Stop> {
     // decision, and an `acceptClean` first step must get to fire.
     if (beat > 1 && isTrue(b.idle)) return { kind: "done", text: await io.plain(), ...where(b) }
 
-    const acted = await act(io, b, beat, judged, beat === 1 ? landTurn : undefined)
+    const acted = await act(io, b, beat, judged, beat === 1 ? opening : {})
     if (acted.stop) return acted.stop
     judged = acted.verdict ? b.state : undefined
     const landed = await land(io, b, acted.verdict, true)
@@ -98,20 +103,22 @@ async function act(
   b: Beat,
   beat: number,
   judged: string | undefined,
-  landTurn: string | undefined,
+  opening: Opening,
 ): Promise<Acted> {
   switch (b.kind) {
     case "stalled":
       return { stop: { kind: "stalled", text: b.content ?? "", ...where(b) } }
     case "message":
-      return message(io, b, beat, judged)
+      return opening.isAnswered && b.judge
+        ? { verdict: opening.verdict }
+        : message(io, b, beat, judged)
     case "capture":
       return {}
     case "script":
       await io.sh(b.content ?? "", b.log)
       return {}
     case "prompt":
-      return agent(io, b, landTurn)
+      return agent(io, b, opening.landTurn)
     default:
       return failed(b, `unknown beat kind '${b.kind}'`)
   }
@@ -126,6 +133,7 @@ async function message(io: Io, b: Beat, beat: number, judged: string | undefined
   const stop: Stop = { kind: "gate", text: b.content ?? "", ...where(b) }
   if (b.judge) stop.isJudge = true
   if (b.file) stop.file = b.file
+  if (b.mode) stop.mode = b.mode
   return { stop }
 }
 

package/claude/hooks/judge.ts

@@ -111,3 +111,30 @@ export function toVerdicts(j: Judgment, reply: unknown): Verdict[] | string {
   }
   return out
 }
+
+// Each question as a person is asked it: its instructions, criteria and the
+// answers it takes; a string is why it cannot be asked.
+export function judgeQuestions(j: Judgment) {
+  return j.questions.map((q) => {
+    const levels = levelsOf(q)
+    if (typeof levels === "string") return levels
+    const meaning = levels.map(([label, text], i) =>
+      q.primitive === "score" ? `${i + 1}: ${text}` : `${label}: ${text}`,
+    )
+    return {
+      id: q.id,
+      instructions: q.instructions,
+      criteria: q.primitive === "noul" ? [q.criteria] : meaning,
+      options: optionsOf(q, levels),
+    }
+  })
+}
+
+// A person's `{ <id>: <answer> }` as gtd's verdicts, held with certainty.
+export function humanVerdicts(j: Judgment, answers: unknown): Verdict[] | string {
+  if (typeof answers !== "object" || answers === null) return "verdicts must be an object"
+  const reply = Object.fromEntries(
+    Object.entries(answers).map(([id, answer]) => [id, { answer, p: 1 }]),
+  )
+  return toVerdicts(j, reply)
+}