@pmelab/gtd 16.0.0 → 17.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "gtd",
+  "version": "17.2.0",
+  "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
+  "author": {
+    "name": "Philipp Melab"
+  },
+  "types": "./claude/types/index.d.ts"
+}

package/README.md

@@ -21,7 +21,9 @@ npm install -g @pmelab/gtd
 
 Or run without installing (prefix every `gtd` below with `npx`) — see
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md)
-for the settings most projects tune.
+for the settings most projects tune. A process setting's value is committed to
+Git history; keep secrets in an environment setting (see
+[Settings](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#settings)).
 
 Also install all three skill sources the bundled workflow names in its prompts —
 none is optional. See
@@ -276,6 +278,34 @@ this with your environment. See
 [Driving the loop](https://github.com/pmelab/gtd/blob/main/docs/driver.md) for
 the full protocol.
 
+### Or drive it from inside Claude Code
+
+The gtd mod runs the same loop inside an interactive Claude Code session
+(2.1.287 or later), without `claude -p`. The plugin is the npm package itself,
+so it brings its own gtd; it needs only `node` and `npm` on your `PATH`:
+
+```sh
+claude plugin marketplace add pmelab/gtd
+claude plugin install gtd@gtd
+```
+
+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.
+`/gtd fix` and `/gtd review [base]` take the two side 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
+[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
 
 But lets be honest, who reads documentation these days. Paste this into your
@@ -359,8 +389,11 @@ noted in steps 2, 3, and 4 below.
    users only; model `haiku`, `--model <name>` overrides) and reuses its login.
    With no `--provider`, `gtd judge run` picks jev when `TYPESAFE_API_KEY` is
    set and non-empty and no `--model` is given, else llm — never falling back
-   across them; `--model` with `--provider fixed`/`jev` is refused. jev and llm
-   exit 1 with nothing on stdout when they cannot answer every question):
+   across them; a `.gtdrc` `judge: { provider, model }` key and the
+   `GTD_JUDGE_PROVIDER` / `GTD_JUDGE_MODEL` environment variables choose the
+   judge without editing the driver (flags win over both); `--model` with
+   `--provider fixed`/`jev` is refused. jev and llm exit 1 with nothing on
+   stdout when they cannot answer every question):
    - Every red round after the first: was the failure identical, new, or
      progress?
    - Before spending a review turn on a package: does the code already satisfy
@@ -376,14 +409,16 @@ noted in steps 2, 3, and 4 below.
    floors and skip a gate unattended.**
 
    Once the last package is built, the whole change goes through a qualitative
-   review lap before you see anything: one configured skill per turn, each
-   looking at the change from its own angle (a security checklist, a
-   simplification pass) and fixing what it finds once, with no re-review after
-   the fix. The per-package review above only judges that package against its
-   own spec; this lap is where code quality is looked at, and every round pays
-   for it. It never replaces step 4 — your review stays the final gate, and
-   nothing here skips it. The `gtd --entry fix-precheck` side door (below)
-   repairs a red baseline through this same lap.
+   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
+   them once, with no re-review after the fix. A clean turn means approval only
+   when that lens found nothing at all. The per-package review above only judges
+   that package against its own spec; this lap is where code quality is looked
+   at, and every round pays for it. It never replaces step 4 — your review stays
+   the final gate, and nothing here skips it. The `gtd --entry fix-precheck`
+   side door (below) repairs a red baseline through this same lap.
 
    A red suite that keeps failing past a few fix attempts escalates instead of
    retrying forever: an agent turn reads the failing output and writes
@@ -395,20 +430,25 @@ noted in steps 2, 3, and 4 below.
    attempt anywhere new.
 
 4. **You review.** You get a review document listing what changed and what to
-   look at. 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. A hand-edit
-   to code always plans a lap. Only a confident non-`edit` verdict skips the
-   replan — a note whose evidence was cut, or that got no verdict, counts as
-   `edit`. The same `gtd judge answer` / conservative-default shape as step 3's
-   own judged points.
+   look at. Before you see it, an automatic risk-fix pass
+   (`build.review.fix-risks`) runs. Any risk the reviewer names (a note opening
+   with `Risk:`) is fixed first, the suite kept green, and the review rewritten
+   — once per review round, so a risk the rewrite still names reaches 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. A hand-edit to code
+   always plans a lap. Only a confident non-`edit` verdict skips the replan — a
+   note whose evidence was cut, or that got no verdict, counts as `edit`. The
+   same `gtd judge answer` / conservative-default shape as step 3's own judged
+   points.
 
 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

package/bin/gtd

@@ -0,0 +1,3 @@
+#!/bin/sh
+# The gtd this plugin ships, on the Bash tool's PATH while the plugin is enabled.
+exec node "$(dirname "$0")/../dist/gtd.bundle.mjs" "$@"

package/claude/hooks/drive.ts

@@ -0,0 +1,169 @@
+import type { Stop } from "../types"
+
+// The subset of `gtd next --json` this driver reads. Absent optional fields
+// are simply missing; booleans may arrive as strings.
+export type Beat = {
+  kind: string
+  idle?: boolean | string
+  state?: string
+  label?: string
+  file?: string
+  content?: string
+  log?: string
+  memory?: string
+  model?: string
+  system?: string
+  validate?: string
+  judge?: unknown
+  changes?: { status: string; path: string }[]
+  session?: { id?: string; resume?: boolean | string }
+}
+
+export type Landing = {
+  script: string
+  settled?: boolean | string
+  idle?: boolean | string
+  subject?: string
+}
+
+export type Turn = {
+  memory: string
+  resume: boolean
+  prompt: string
+  label?: string
+  model?: string
+  system?: string
+}
+
+export type TurnEnd = { ok: true } | { ok: false; why: string }
+
+export type Io = {
+  next(): Promise<Beat>
+  plain(): Promise<string>
+  land(verdict?: string): Promise<Landing>
+  sh(script: string, log?: string): Promise<number>
+  check(script: string): Promise<{ ok: boolean; out: string }>
+  judge(): Promise<string | undefined>
+  turn(t: Turn): Promise<TurnEnd>
+  resume(memory: string, text: string): Promise<TurnEnd>
+  progress(beat: number, b: Beat): void
+  stopped(): boolean
+}
+
+const MAX_FIXES = 3
+
+export const isTrue = (v: unknown) => v === true || v === "true"
+
+// What acting on one beat came to: stop the run, or land the beat (with the
+// verdict when a judge gate was answered).
+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) } })
+
+// 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> {
+  // 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
+  for (let beat = 1; ; beat++) {
+    if (io.stopped()) return { kind: "stopped", text: "stopped on request" }
+    const b = await io.next()
+    io.progress(beat, b)
+    // The opening beat lands even at idle: a re-run there is the human's
+    // 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)
+    if (acted.stop) return acted.stop
+    judged = acted.verdict ? b.state : undefined
+    const landed = await land(io, b, acted.verdict)
+    if (landed) return landed
+  }
+}
+
+async function act(
+  io: Io,
+  b: Beat,
+  beat: number,
+  judged: string | undefined,
+  landTurn: string | undefined,
+): Promise<Acted> {
+  switch (b.kind) {
+    case "stalled":
+      return { stop: { kind: "stalled", text: b.content ?? "", ...where(b) } }
+    case "message":
+      return 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)
+    default:
+      return failed(b, `unknown beat kind '${b.kind}'`)
+  }
+}
+
+async function message(io: Io, b: Beat, beat: number, judged: string | undefined): Promise<Acted> {
+  const verdict = b.judge && judged !== b.state ? await io.judge() : undefined
+  if (verdict || beat === 1) return { verdict }
+  // Any later beat is a gate this run produced and the human has not read yet.
+  const stop: Stop = { kind: "gate", text: b.content ?? "", ...where(b) }
+  if (b.judge) stop.isJudge = true
+  if (b.file) stop.file = b.file
+  return { stop }
+}
+
+async function agent(io: Io, b: Beat, landTurn: string | undefined): Promise<Acted> {
+  const memory = b.memory ?? b.session?.id ?? b.state ?? "root"
+  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,
+        })
+  if (!t.ok) return failed(b, t.why)
+  return b.validate ? validated(io, b, b.validate, memory) : {}
+}
+
+// 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> {
+  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)
+    if (!f.ok) return failed(b, f.why)
+  }
+}
+
+async function land(io: Io, b: Beat, verdict: string | undefined): Promise<Stop | undefined> {
+  const l = await io.land(verdict)
+  const code = await io.sh(l.script, b.log)
+  if (code !== 0) return { kind: "error", text: `landing script exited ${code}`, ...where(b) }
+  if (!isTrue(l.settled)) return undefined
+  const text = isTrue(l.idle) ? await io.plain() : l.subject || "settled"
+  return { kind: "done", text, ...where(b) }
+}
+
+// What a reload that cut the loop off does next. Only a turn the agent
+// finished lands; any other end runs it again. A script cut off may have run
+// partly, and running it again is not safe to assume, so a person decides.
+export type Reloaded = "wait" | "land" | "rerun" | "halt"
+
+export function afterReload(cut: { isScripting?: boolean; agentStatus?: string }): Reloaded {
+  if (cut.isScripting) return "halt"
+  if (cut.agentStatus === "running") return "wait"
+  return cut.agentStatus === "completed" ? "land" : "rerun"
+}

package/claude/hooks/entry.ts

@@ -0,0 +1,34 @@
+// The workflow's side doors: `fix` repairs a red baseline as its own reviewed
+// commit, `review` reviews everything since a base, straight to the review
+// tail. `gtd --entry` prints the script that starts the process; running it
+// is the driver's job, as with every git write gtd plans.
+
+import type { ShipIo, Shipped } from "./ship"
+
+const fail = (text: string): Shipped => ({ ok: false, text })
+
+export async function enter(io: ShipIo, door: "fix" | "review", base?: string): Promise<Shipped> {
+  const args = door === "fix" ? ["--entry", "fix-precheck"] : await reviewArgs(io, base)
+  if (typeof args === "string") return fail(args)
+  const planned = await io.run(["gtd", ...args])
+  if (planned.code !== 0)
+    return fail(planned.err.trim() || `gtd ${args.join(" ")} exited ${planned.code}`)
+  const started = await io.run(["sh", "-c", planned.out])
+  if (started.code !== 0) return fail(`The entry script failed.\n${started.err.trim()}`)
+  return {
+    ok: true,
+    text: door === "fix" ? "Started a fix." : `Started a review since ${args.at(-1)?.slice(-7)}.`,
+  }
+}
+
+// Reviews the branch since it left `base`, the default branch unless named.
+async function reviewArgs(io: ShipIo, base: string | undefined) {
+  const git = async (...a: string[]) => (await io.run(["git", ...a])).out.trim()
+  const from =
+    base || (await git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")) || "main"
+  const mergeBase = await git("merge-base", from, "HEAD")
+  if (!mergeBase) return `There is no common ancestor of ${from} and HEAD to review from.`
+  if (mergeBase === (await git("rev-parse", "HEAD")))
+    return `Nothing to review: HEAD has no commits beyond ${from}.`
+  return ["--entry", "review-gate.check", "--var", `reviewBase=${mergeBase}`]
+}

package/claude/hooks/handoff.ts

@@ -0,0 +1,174 @@
+// Multiplayer gtd: a process is entirely git, so handing it to someone else is
+// pushing the branch and telling them. `throw` opens (or refreshes) a draft
+// pull request for the hand-off; `catch` checks it out wherever it was thrown.
+
+import { pushBranch, THROWN } from "./ship"
+import type { ShipIo, Shipped } from "./ship"
+
+export type Rest = { state?: string; label?: string; content?: string; isIdle: boolean }
+
+const fail = (text: string): Shipped => ({ ok: false, text })
+
+type Pr = {
+  number: number
+  url: string
+  state?: string
+  body?: string
+  assignees?: { login: string }[]
+}
+
+export async function throwTo(
+  io: ShipIo,
+  rest: Rest,
+  target: string | undefined,
+  now: string,
+): Promise<Shipped> {
+  if (rest.isIdle) return fail("Nothing is in progress, so there is nothing to throw.")
+  // Only landed state travels: an edit still in the tree is half an answer.
+  if ((await io.run(["git", "status", "--porcelain"])).out.trim()) {
+    return fail("The working tree has edits. Proceed to land them, or stash them, then throw.")
+  }
+  const on = await throwBranch(io, now)
+  if (typeof on === "string") return fail(on)
+  const behind = await remoteAhead(io, on.branch)
+  if (behind) return fail(behind)
+  const pushed = await pushBranch(io, on.branch)
+  if (pushed) return fail(pushed)
+  const at = rest.label ? `${rest.state} (${rest.label})` : (rest.state ?? "a gate")
+  const pr = await draft(io, on.branch, on.base, rest, at)
+  if (typeof pr === "string") return fail(pr)
+  const handle = target?.replace(/^@/, "")
+  if (handle) {
+    const assigned = await assign(io, pr, handle)
+    if (assigned) return fail(assigned)
+  }
+  const to = handle ? `to @${handle}` : "to anyone"
+  await io.run(
+    ["gh", "pr", "comment", String(pr.number), "--body-file", "-"],
+    `Thrown ${to} at **${at}**. Catch it with \`/gtd catch ${on.branch}\`.\n`,
+  )
+  return { ok: true, text: `Thrown ${to}: ${pr.url}` }
+}
+
+// The catcher checks out what origin holds, so a throw describing local HEAD
+// must not leave origin elsewhere: fetch first, a stale tracking ref can hide
+// a teammate's commits or a rewind. Returns why the throw refuses, or nothing.
+async function remoteAhead(io: ShipIo, branch: string) {
+  const ok = async (...args: string[]) => (await io.run(["git", ...args])).code === 0
+  if (!(await ok("fetch", "--prune", "origin"))) return "git fetch failed."
+  if (!(await ok("rev-parse", "--verify", "--quiet", `origin/${branch}`))) return undefined
+  if (await ok("merge-base", "--is-ancestor", `origin/${branch}`, "HEAD")) return undefined
+  return `origin/${branch} has commits HEAD lacks. Pull or catch them first, then throw.`
+}
+
+// The branch to throw, moving the process off the default branch onto a new
+// one when it sits there; a string is why that failed.
+async function throwBranch(io: ShipIo, now: string) {
+  const git = async (...args: string[]) => (await io.run(["git", ...args])).out.trim()
+  const branch = await git("rev-parse", "--abbrev-ref", "HEAD")
+  if (!branch || branch === "HEAD") return "Detached HEAD: there is no branch to throw."
+  const head = await git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+  const base = head.replace(/^origin\//, "") || "main"
+  if (branch !== base) return { branch, base }
+  const fresh = `gtd/${now.replace(/[-:]/g, "").replace("T", "-").slice(0, 13)}`
+  const switched = await io.run(["git", "switch", "-c", fresh])
+  if (switched.code !== 0) return `Could not create ${fresh}.\n${switched.err}`
+  io.log(`Moved the process onto a new branch, ${fresh}.`)
+  return { branch: fresh, base }
+}
+
+const throwBody = (branch: string, at: string, content = "") => `${THROWN}
+This gtd process was thrown at **${at}** and waits for whoever catches it.
+
+Catch it in Claude Code with the gtd mod:
+
+\`\`\`
+/gtd catch ${branch}
+\`\`\`
+
+or without it: \`gh pr checkout ${branch} && gtd next\`.
+
+<details><summary>What the process is waiting for</summary>
+
+${content.slice(0, 6000)}
+
+</details>
+`
+
+// Opens the hand-off's draft, or refreshes a thrown one; a string is why that
+// failed.
+async function draft(
+  io: ShipIo,
+  branch: string,
+  base: string,
+  rest: Rest,
+  at: string,
+): Promise<Pr | string> {
+  const body = throwBody(branch, at, rest.content)
+  const view = await io.run([
+    "gh",
+    "pr",
+    "view",
+    branch,
+    "--json",
+    "number,url,state,body,assignees",
+  ])
+  if (view.code !== 0) {
+    const title = `wip: ${branch} — ${rest.label ?? rest.state}`
+    const created = await io.run(
+      [
+        "gh",
+        "pr",
+        "create",
+        "--draft",
+        "--head",
+        branch,
+        "--base",
+        base,
+        "--title",
+        title,
+        "--body-file",
+        "-",
+      ],
+      body,
+    )
+    if (created.code !== 0) return `gh pr create failed; nothing was opened.\n${created.err}`
+    const url = created.out.trim()
+    return { number: Number(url.split("/").pop()), url }
+  }
+  const pr = JSON.parse(view.out) as Pr
+  if (pr.state !== "OPEN") return `The pull request for ${branch} is ${pr.state}, not open.`
+  // A pull request someone opened for review keeps its own description and
+  // stays ready: only ship marks a draft ready again, and only a thrown one.
+  if (pr.body?.includes(THROWN)) {
+    await io.run(["gh", "pr", "edit", String(pr.number), "--body-file", "-"], body)
+    await io.run(["gh", "pr", "ready", String(pr.number), "--undo"])
+  }
+  return pr
+}
+
+async function assign(io: ShipIo, pr: Pr, handle: string) {
+  const stale = (pr.assignees ?? []).map((a) => a.login).filter((login) => login !== handle)
+  const args = ["gh", "pr", "edit", String(pr.number), "--add-assignee", handle]
+  for (const login of stale) args.push("--remove-assignee", login)
+  const assigned = await io.run(args)
+  return assigned.code === 0
+    ? undefined
+    : `Thrown to ${pr.url}, but assigning @${handle} failed.\n${assigned.err}`
+}
+
+export async function catchFrom(io: ShipIo, ref: string): Promise<Shipped> {
+  if ((await io.run(["git", "status", "--porcelain"])).out.trim()) {
+    return fail("The working tree has edits. Commit or stash them before catching.")
+  }
+  const checkout = await io.run(["gh", "pr", "checkout", ref])
+  if (checkout.code !== 0) return fail(`Could not check out ${ref}.\n${checkout.err}`)
+  const view = await io.run(["gh", "pr", "view", ref, "--json", "number,url"])
+  if (view.code === 0) {
+    const pr = JSON.parse(view.out) as { number: number; url: string }
+    await io.run(["gh", "pr", "edit", String(pr.number), "--add-assignee", "@me"])
+    await io.run(["gh", "pr", "comment", String(pr.number), "--body", "Caught."])
+    return { ok: true, text: `Caught ${pr.url}` }
+  }
+  return { ok: true, text: `Checked out ${ref}.` }
+}

package/claude/hooks/judge.ts

@@ -0,0 +1,99 @@
+// gtd's `llm` judge provider, answered by a subagent instead of `claude -p`.
+// A port of src/judges/providers/llm.ts (which needs Node, which a mod has
+// not): claude/hooks/judge.test.ts pins the prompt to gtd's own, so the two
+// cannot drift apart unnoticed.
+
+type Question = {
+  id: string
+  primitive: string
+  instructions: string
+  criteria: string
+}
+
+export type Judgment = { state?: Record<string, string>; questions: Question[] }
+
+type Verdict = { id: string; answer: string | number; p: number }
+
+export const JUDGE_SYSTEM =
+  "You are a strict, impartial judge. Answer each question from the supplied evidence alone.\n" +
+  "Reply only with the structured answer; never use tools or ask questions."
+
+const LABEL = /(?:^|\. )([A-Za-z][A-Za-z0-9_-]*): /g
+
+const splitLabels = (criteria: string): [string, string][] => {
+  const hits = [...criteria.matchAll(LABEL)]
+  return hits.map((m, i) => {
+    const start = m.index + m[0].length
+    const end = hits[i + 1]?.index ?? criteria.length
+    return [m[1] as string, criteria.slice(start, end).replace(/^ /, "")]
+  })
+}
+
+// A string is why the question cannot be put to a model.
+const levelsOf = (q: Question): [string, string][] | string => {
+  if (q.primitive === "noul") return []
+  if (q.primitive !== "choice" && q.primitive !== "score") {
+    return `question "${q.id}": unknown primitive "${q.primitive}"`
+  }
+  const levels = splitLabels(q.criteria)
+  return levels.length < 2
+    ? `question "${q.id}": ${q.primitive} criteria need at least 2 labelled ${q.primitive === "choice" ? "options" : "levels"}`
+    : levels
+}
+
+const optionsOf = (q: Question, levels: [string, string][]): (string | number)[] =>
+  q.primitive === "noul"
+    ? ["yes", "no"]
+    : q.primitive === "choice"
+      ? levels.map(([label]) => label)
+      : levels.map((_, i) => i + 1)
+
+const describe = (q: Question, levels: [string, string][]) => {
+  const head = `<question id="${q.id}">\n${q.instructions}\n`
+  if (q.primitive === "noul")
+    return `${head}Criteria: ${q.criteria}\nAnswer "yes" or "no".\n</question>`
+  const body =
+    q.primitive === "choice"
+      ? levels.map(([label, text]) => `- ${label}: ${text}`).join("\n")
+      : levels.map(([, text], i) => `${i + 1}. ${text}`).join("\n")
+  const ask =
+    q.primitive === "choice"
+      ? "Answer with exactly one label."
+      : "Answer with the number of one level."
+  return `${head}${body}\n${ask}\n</question>`
+}
+
+// The prompt gtd's llm provider sends; throws for criteria it cannot ask about.
+export function judgePrompt(j: Judgment): string {
+  const parts = [
+    "Answer every question below from the evidence alone. For each, give your answer and p, your confidence between 0 and 1 that the given answer is correct.",
+  ]
+  for (const [key, body] of Object.entries(j.state ?? {}))
+    parts.push(`<evidence key="${key}">\n${body}\n</evidence>`)
+  for (const q of j.questions) {
+    const levels = levelsOf(q)
+    if (typeof levels === "string") throw new Error(levels)
+    parts.push(describe(q, levels))
+  }
+  return parts.join("\n\n")
+}
+
+// The reply `{ <id>: { answer, p } }` as gtd's verdict array, every question
+// answered with one of its own options; a string is why it is not usable.
+export function toVerdicts(j: Judgment, reply: unknown): Verdict[] | string {
+  if (typeof reply !== "object" || reply === null) return "the reply is not an object"
+  const out: Verdict[] = []
+  for (const q of j.questions) {
+    const raw = (reply as Record<string, unknown>)[q.id] as
+      | { answer?: unknown; p?: unknown }
+      | undefined
+    const levels = levelsOf(q)
+    if (typeof levels === "string") return levels
+    if (!raw || typeof raw.p !== "number" || raw.p < 0 || raw.p > 1)
+      return `"${q.id}" has no p in [0, 1]`
+    if (!optionsOf(q, levels).includes(raw.answer as string | number))
+      return `"${q.id}" answer is not one of its options`
+    out.push({ id: q.id, answer: raw.answer as string | number, p: raw.p })
+  }
+  return out
+}

package/claude/hooks/models.ts

@@ -0,0 +1,19 @@
+// A workflow names models by role (`smart`, `base`), as hints a driver
+// resolves; the bash driver does it with GTD_PLANNERMODEL / GTD_CODERMODEL.
+// A subagent takes only Claude Code's own aliases, so anything else becomes
+// undefined: the session's own model.
+
+const ALIASES = ["sonnet", "opus", "haiku", "fable"] as const
+type Alias = (typeof ALIASES)[number]
+
+export type Roles = { smart?: string; base?: string }
+
+const asAlias = (name: string): Alias | undefined =>
+  ALIASES.find((a) => name === a || name.startsWith(`claude-${a}`))
+
+export function subagentModel(hint: string | undefined, roles: Roles): Alias | undefined {
+  if (!hint) return undefined
+  const resolved =
+    hint === "smart" ? (roles.smart ?? "opus") : hint === "base" ? (roles.base ?? "sonnet") : hint
+  return asAlias(resolved)
+}