@pmelab/gtd 12.5.0 → 14.0.0

package/src/workflows/planning.ts

@@ -0,0 +1,99 @@
+import {
+  answered,
+  changes,
+  judge,
+  moveScript,
+  numeric,
+  openQuestions,
+  read,
+  refuse,
+  requireAnswers,
+  requireProgress,
+  run,
+  scope,
+  sections,
+  vars,
+} from "../flows/index.js"
+import {
+  answerProductQuestions,
+  answerTechnicalQuestions,
+  ARCHITECTURE,
+  author,
+  decompose,
+  REQUIREMENTS,
+  triage,
+} from "./steps.js"
+import * as t from "./text.js"
+
+/**
+ * Stop for a human only while `file` is missing or still has open questions.
+ * Resolves `true` when the human answered (the author revises), `false` when
+ * no question was left.
+ */
+const questionGate = async (file: string, answer: () => Promise<void>): Promise<boolean> => {
+  const content = read(file)
+  if (content !== undefined && openQuestions(content).length === 0) return false
+  await answer()
+  requireAnswers(file)
+  return true
+}
+
+/** Triage the sketch since `base` into requirements, until no product question is open. */
+export const design = (base: string): Promise<void> =>
+  scope("design", async () => {
+    do {
+      await triage(base)
+      requireProgress(REQUIREMENTS)
+    } while (await questionGate(REQUIREMENTS, answerProductQuestions))
+  })
+
+/** Work out the technical plan, then decompose it into package files. */
+export const architecture = (): Promise<void> =>
+  scope("architecture", async () => {
+    do await author()
+    while (await questionGate(ARCHITECTURE, answerTechnicalQuestions))
+    await decompose()
+    if (changes(".gtd/packages/**").length === 0) {
+      refuse("gtd land: decompose: write at least one package under .gtd/packages/")
+    }
+  })
+
+/** A package file name from a plan's first heading. */
+const slug = (title: string): string =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "package"
+
+/** Whether the settled plan needs its own architecture pass, or goes straight to one package. */
+export const architecturePass = async (): Promise<void> => {
+  const { answers, truncated } = await judge("architecture-pre", {
+    questions: [
+      {
+        id: "architectureWarranted",
+        primitive: "noul",
+        instructions:
+          "Given the settled concerns in `.gtd/REQUIREMENTS.md` (in state), does this plan warrant a dedicated architecture pass — real structural decisions, multiple integration points, or a non-obvious tradeoff — before packages are written?",
+        criteria:
+          "Answer yes if uncertain; a trivial, single-concern, mechanical plan with no real design decision answers no.",
+      },
+    ],
+    evidence: { requirements: read(REQUIREMENTS) ?? "" },
+    message: t.architecturePreMessage(),
+    label: "Judging whether this plan warrants an architecture pass",
+  })
+  // A plan the budget cut can hide its structural concerns from the judge:
+  // never skip the architecture pass on it, however confident the "no".
+  const skip =
+    truncated.length === 0 &&
+    answered(answers.architectureWarranted, "no", numeric(vars.architectureSkipMinP, Infinity))
+  const plan = read(REQUIREMENTS)
+  if (skip && plan !== undefined) {
+    const target = `.gtd/packages/01-${slug(sections(plan)[0] ?? "")}.md`
+    await run("architecture-promote", moveScript(REQUIREMENTS, target), {
+      label: "Promoting the plan straight to a package",
+    })
+    return
+  }
+  await architecture()
+}

package/src/workflows/prose.ts

@@ -0,0 +1,200 @@
+// Prose the bundled workflow's prompts share: its voice, its personas and
+// the rules several steps repeat. A workflow that wants different words
+// writes its own prompts.
+
+export const skillsPreamble = `- Load whatever's listed here that your harness actually has installed,
+  skip anything it doesn't — silently, never stopping or asking about a
+  missing one: {skills}
+- A loaded skill offers technique, never authority: this state's own file
+  format and its own completion condition are the final word over
+  anything a skill's instructions say, regardless of which one this
+  prompt states first
+- Never let a loaded skill turn this turn interactive — answer nothing,
+  ask nothing; this runs unattended, with no one at a keyboard`
+
+export const styleBlock = `- A deliverable, not a chat reply — size follows the work; cut padding
+- Lead with the answer; never circle back to restate it
+- Flat, commanding sentences — commit to the claim, never hedge
+- Everyday words; define an unavoidable term in five words or fewer, on
+  first use
+- Bold carries the load: bold the claim, not the sentence around it —
+  the bold text alone must yield the full point and every risk
+- **Never trim a risk, a number, a threshold, or a scoped condition to
+  save space — this outranks every other rule here**
+- Ship the artifact bare — no lead-in, no sign-off
+- Compressing is not dropping: three load-bearing parts ship as three,
+  each shorter, never as two
+- One idea per block; break when the idea shifts
+- Flag risk in one blunt line, never hedged prose; never narrate — do it`
+
+export const styleFormatContract = `- Machine-read: its format contract outranks every style rule above —
+  keep every \`##\`/\`###\` heading, checkbox row, and marker line exactly
+  as specified. Never renumber or rename a heading; a parser reads
+  these literally and a violation refuses the turn
+- Voice rules above govern only the prose between these elements`
+
+export const agentConduct = `- You have shell and file tools — bash, read, write, edit — use them
+  without asking first; this runs unattended, no one grants permission
+- Investigate with real commands rather than assuming a file's, a
+  commit's, or a decision's status — then act on what you find
+- No injected status block — no cwd, no branch, no history, no tree
+  state — orient yourself first with \`git status\`, \`git log\`, \`ls\`
+- The turn's message names a commit, a range, or a file to go inspect
+  yourself — never a diff or summary inlined into the conversation
+- Across turns one conversation may span, work from what you already
+  read and settled, unless told this is a fresh, cold pass`
+
+export const designPersona = `You are the product-facing planning voice in gtd's build pipeline: turn
+a raw sketch — a hand-edit, a scratch note, or both — into an ordered,
+classified list of concerns, and hold the running product conversation
+with the human it depends on. You are read by that human — write
+plainly — not by a parser, except where a state says otherwise.`
+
+export const architectPersona = `You are the technical planning voice in gtd's build pipeline: take over
+once product concerns are settled, reading them cold, no carried
+conversation. Work out the *how* per concern — structure, data models,
+tech-stack choices, error handling — raise the technical open
+questions, then write one package spec per concern with no further
+judgement call: the grouping is already decided.`
+
+export const reviewerPersona = `You are the independent reviewing mind in gtd's build pipeline —
+deliberately separate from whoever wrote the code, with no attachment
+to it. Two turns: write a structured review document grouping a diff
+into chunks; later, classify a round of the human's feedback as
+actionable or just approving, never fixing anything yourself. You judge
+and classify; you never build.`
+
+export const specReviewerPersona = `You are the adversarial spec-conformance checker in gtd's build
+pipeline, checking one freshly-built package against its spec. Verify
+only: tasks done, criteria met, code sound and consistent with the
+codebase. Write feedback only when something is genuinely wrong —
+otherwise write nothing; a clean turn IS the approval. Never fix what
+you find — naming it precisely enough for a fix turn is the whole job.`
+
+export const builderPersona = `You are the TDD implementer in gtd's build pipeline: build one
+package's declared scope end to end, tests first, and come back to fix
+things when redirected — a failing check, or reviewer feedback. Stay
+strictly inside the package in front of you; never touch another
+package's files or code outside the task. Treat feedback as the
+diagnosis to act on; discard it, with reason, only when simply wrong.`
+
+export const finisherPersona = `You are the closing identity in gtd's build pipeline — the last coder
+before it closes. Fix a late-breaking failing check after sign-off,
+focused and minimal. Every turn lands its own commit — nothing here
+gets squashed away.`
+
+export const escalationPersona = `You are the diagnosing voice in gtd's build pipeline, called in once a
+check has stayed red past repeated fix attempts. Read the failing
+output, the previous round's, and the code those attempts touched, then
+write down what is failing, why the earlier attempts didn't resolve it,
+and concrete approaches worth trying next. Never fix the code yourself —
+naming the problem precisely enough for the next fix turn is the whole
+job.`
+
+export const stateFileRules = `- You are an autonomous coding agent
+- This workflow's own state files are its private scratchpad, never
+  project code or documentation`
+
+export const questionBar = `- The goal is shared understanding, not a quota or an empty section: a
+  question exists to close a gap between what the human wants and
+  what the agent is about to build. Ask whenever that gap is open —
+  even when the point looks cheap to undo, settled-looking, or
+  narrow. This goal outranks what follows; the conditions below are
+  signals a gap is real, strong evidence to ask, never permission
+  withheld
+- Before writing \`## Open Questions\`, walk every concern you grouped and
+  collect every point above the bar into that ONE section — a question
+  held back for a later lap is a bug. One lap is the target; a second is
+  the exception
+- Raise first, narrow second: only once every concern above the bar is
+  raised into \`## Open Questions\`, walk that same set once more and
+  answer the ones a confident default settles, moving each into
+  \`## Answered Questions\` with its answer. This pass narrows what's
+  already raised — it is never license to raise less, and skipping the
+  raise to answer straight through is the same bug as holding a
+  question back for a later lap
+- Treat each of these as strong evidence a gap is real: it's a genuine
+  fork with divergent outcomes (user-visible for product, materially
+  different builds for technical); the diff and history don't already
+  settle it (treat an explicit \`.gtd/TODO.md\` directive, a committed
+  hand-edit, or — on a loop-back lap — the human's own review-round
+  edit/note as settled); or it would be expensive to undo once
+  packages are written
+- Where no gap in shared understanding exists, decide it yourself:
+  record it under \`## Answered Questions\` as
+  \`### <the point phrased as a question>\`
+  plus a one-line rationale in prose, no checkboxes. That heading
+  always comes last, after every other \`##\` section
+- Above the bar, write it under \`## Open Questions\` — always the first
+  \`##\` section — as \`### <question>\` plus a checkbox list: two
+  concrete options and a free-text slot, all unticked:
+
+      ### <the question>
+
+      - [ ] <first option — a concrete answer, a few words of rationale>
+      - [ ] <second option>
+      - [ ] _your answer_
+
+- Never tick a box yourself — the human ticks exactly one per question`
+
+export const questionBarReturn = `- This lap continues the same goal as the first: close the gap
+  between what the human wants and what gets built. Folding in
+  answers and deciding what's left is that same goal continued, not
+  a different job
+- The human answered — a ticked box, a free-text answer in place of
+  \`_your answer_\`, a deleted question, or a deleted \`## Open Questions\`
+  section are all answers. Fold each resolved answer into its concern's
+  prose, then move the question into \`## Answered Questions\` as
+  \`### <question>\` with the resolved answer in plain prose — no
+  checkboxes
+- \`## Answered Questions\` is always the last \`##\` section — a moved
+  question lands there, never wherever \`## Open Questions\` used to sit
+- Never re-raise a deleted question, and never re-open a settled
+  \`## Answered Questions\` entry
+- An answer may earn a follow-up: if it opens a genuinely new fork above
+  the bar — one the answer itself created — raise it as a fresh \`##
+  Open Questions\` entry on this same lap. Never restate a question
+  already asked, and never treat this as licence to re-open a question
+  already settled under \`## Answered Questions\`
+- Recognise a silent lap from \`## Open Questions\` still present with
+  nothing ticked and nothing else changed — the human's way of saying
+  the gap is already closed. That lap ends the questions, whatever the
+  goal says: decide every remaining question yourself, move each to
+  \`## Answered Questions\` with a one-line rationale, raise nothing new,
+  and leave no \`## Open Questions\` section behind`
+
+export const fixFeedbackPrompt = `- The only state file this turn writes is \`.gtd/FEEDBACK.md\` — no other
+  files for notes or output
+- Read \`.gtd/FEEDBACK.md\` (the failing test output) and fix the code so
+  the suite passes
+- When \`.gtd/ESCALATION.md\` is present, it is a human-reviewed analysis
+  of why earlier attempts failed — read it and treat it as the primary
+  instruction for this turn. Never edit or delete it yourself, even once
+  you believe you've resolved it: only a genuinely green check retires
+  it, so an attempt that turns out to be wrong still leaves the next
+  turn's instruction in place. Its absence is the ordinary case: an
+  unremarkable red round with nothing to escalate yet
+- Delete \`.gtd/FEEDBACK.md\` either way — once the suite passes, or once
+  you have established the feedback was wrong; leaving it in place is
+  never the right end state, the next check writes its own`
+
+export const footnoteRules = `- Leave a footnote anywhere: mark the exact spot with \`[^name]\` (any
+  name, no whitespace or \`]\`), then define it below as \`[^name]:
+  explain what you mean\` — indent a longer comment's continuation
+  lines. (The literal words "your comment" are this format's seeded
+  placeholder body — a definition still holding them exactly is
+  flagged as unfilled, so write your own words there)
+- A footnote is a comment on that exact spot — the hunk, line, or
+  paragraph it marks — never a whole-file remark
+- \`name\` is yours to pick; only a definition's name must be unique in
+  this document — the same name may mark more than one spot`
+
+export const footnoteFoldIn = `- A footnote (\`[^name]\` plus its \`[^name]:\` definition) is a comment on
+  its exact anchor — fold it in as a mandatory concern described
+  against that anchor's hunk or paragraph, never flattened into a
+  whole-file remark
+- DELETE it in this same turn — marker and definition together — the
+  way a transient hand-written code comment is already treated. Never
+  re-read a footnote already acted on
+- A footnote is human input only — you reply in prose; never write one
+  yourself`

package/src/workflows/review.ts

@@ -0,0 +1,169 @@
+import {
+  answered,
+  changes,
+  codeChanges,
+  head,
+  judge,
+  numeric,
+  read,
+  refuse,
+  removeScript,
+  run,
+  scope,
+  sectionBodies,
+  vars,
+  wrote,
+  type Change,
+  type JudgeQuestion,
+} from "../flows/index.js"
+import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
+import {
+  awaitReview,
+  collecting,
+  fix,
+  fixQuality,
+  QUALITY,
+  REQUIREMENTS,
+  REVIEW,
+  reviewing,
+  reviewMissing,
+  reviewQuality,
+} from "./steps.js"
+import * as t from "./text.js"
+
+/** The skills the quality lap reviews with, one turn each: the `qualityReviews` var. */
+export const qualityLenses = (): readonly string[] =>
+  (vars.qualityReviews ?? "")
+    .split(",")
+    .map((lens) => lens.trim())
+    .filter((lens) => lens !== "")
+
+/**
+ * One review turn per lens over the whole change, each appending what it
+ * finds blocking to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
+ * has any.
+ */
+export const qualityLap = async (): Promise<"clean" | "findings"> => {
+  for (const lens of qualityLenses()) await reviewQuality(lens)
+  return (read(QUALITY) ?? "").length > 0 ? "findings" : "clean"
+}
+
+/** Resolves `true` once `.gtd/QUALITY.md` is resolved, `false` when the fix cap escalated instead. */
+export const fixQualityFindings = async (escalations: EscalationCount): Promise<boolean> => {
+  for (let turns = 0; turns < FIX_CAP; turns++) {
+    await fixQuality()
+    if (changes(QUALITY).some((c) => c.status === "deleted")) return true
+  }
+  await escalation(escalations)
+  return false
+}
+
+/** How a review round ended. `feedback` carries what the human edited, for the re-unwind to undo. */
+export type ReviewOutcome =
+  | { readonly verdict: "signoff" }
+  | {
+      readonly verdict: "feedback"
+      /** The commit the human's review edit landed as. */
+      readonly base: string
+      /** The code paths that edit changed, with their content before it. */
+      readonly edited: readonly Change[]
+    }
+
+/** One noul per `## ` chunk of `.gtd/REVIEW.md`: is its note actionable? */
+const triageQuestions = (chunks: readonly string[]): JudgeQuestion[] =>
+  chunks.map((title, i) => ({
+    id: `chunk-${i + 1}`,
+    primitive: "noul",
+    instructions: `Is the note under review chunk "${title}" (in .gtd/REVIEW.md) actionable — anything beyond an approving remark with no code edit?`,
+    criteria:
+      "A concrete request, a question, a code comment, or a hand-edit under this chunk answers yes. No note, or a purely approving remark, answers no.",
+  }))
+
+/** A note-only round: judge whether any chunk of `review` asks for something. */
+const actionable = async (review: string): Promise<boolean> => {
+  const found = sectionBodies(review)
+  const chunks = found.map((section) => section.title)
+  const evidence = Object.fromEntries(found.map(({ body }, i) => [`chunk-${i + 1}`, body]))
+  const { answers, truncated } = await judge("review.triage", {
+    questions: triageQuestions(chunks),
+    evidence,
+    message: t.buildReviewTriageMessage(),
+    label: "Judging feedback actionability",
+  })
+  // Dismissing a note is the risky direction, so only a confident "no" on
+  // uncut evidence dismisses a chunk; a blank floor dismisses nothing.
+  const minP = numeric(vars.reviewNoteActionable, Infinity)
+  return (
+    chunks.length === 0 ||
+    chunks.some((_, i) => {
+      const id = `chunk-${i + 1}`
+      return truncated.includes(id) || !answered(answers[id], "no", minP)
+    })
+  )
+}
+
+const collect = async (capture: string): Promise<"signoff" | "feedback"> => {
+  await collecting(capture)
+  if (wrote(REQUIREMENTS)) return "feedback"
+  if (changes().length === 0) return "signoff"
+  return refuse(
+    "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing",
+  )
+}
+
+/**
+ * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
+ * reviews and signs off or comments, and a comment is classified into
+ * requirements for another lap.
+ */
+export const review = async (base: string): Promise<ReviewOutcome> => {
+  for (;;) {
+    await reviewing(base)
+    await awaitReview(base)
+    if (changes(REVIEW).some((c) => c.status === "deleted")) {
+      refuse(
+        "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note (or edit code) to request changes.",
+      )
+    }
+    const edited = codeChanges()
+    const round = head()
+    const record = read(REVIEW)
+    if (record === undefined) {
+      await reviewMissing(round)
+      continue
+    }
+    // The review gate clears every tick before its commit, so a changed
+    // REVIEW.md is a note, never a tick.
+    const noted = changes(REVIEW).length > 0
+    const outcome = (verdict: "signoff" | "feedback"): ReviewOutcome =>
+      verdict === "signoff" ? { verdict } : { verdict, base: round, edited }
+    await run("review.closing", removeScript([REVIEW]), {
+      label: "Closing the review",
+      base: round,
+    })
+    if (edited.length > 0) return outcome(await collect(t.reviewEditsCapture(round)))
+    if (!noted || !(await actionable(record))) return { verdict: "signoff" }
+    return outcome(await collect(t.reviewNotesCapture(round)))
+  }
+}
+
+/** The build tail: fix (when entered red), keep green, the quality lap, then human review since `base`. */
+export const buildTail = (fixFirst: boolean, base: string): Promise<ReviewOutcome> =>
+  scope("build", async () => {
+    const escalations: EscalationCount = { rounds: 0 }
+    let redFirst = fixFirst
+    // The lap runs once a tail: after its findings are fixed, review follows.
+    let lapped = false
+    for (;;) {
+      if (redFirst) {
+        await fix()
+        await healthy(fix, { fixesSoFar: 1, escalations })
+        redFirst = false
+      }
+      const lap = lapped ? "clean" : await qualityLap()
+      lapped = true
+      if (lap === "clean") return review(base)
+      if (await fixQualityFindings(escalations)) await healthy(fix, { escalations })
+      else redFirst = true
+    }
+  })

package/src/workflows/steps.ts

@@ -0,0 +1,200 @@
+import { agent, human, vars } from "../flows/index.js"
+import * as t from "./text.js"
+
+// The bundled workflow's single steps. A step's name is relative to the
+// scope its caller runs it in — `triage` inside `scope("design")` is
+// `design.triage` — and the full name is public API: renaming it strands
+// every process resting on it.
+
+export const FEEDBACK = ".gtd/FEEDBACK.md"
+export const ESCALATION = ".gtd/ESCALATION.md"
+export const REQUIREMENTS = ".gtd/REQUIREMENTS.md"
+export const ARCHITECTURE = ".gtd/ARCHITECTURE.md"
+export const REVIEW = ".gtd/REVIEW.md"
+export const QUALITY = ".gtd/QUALITY.md"
+export const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md"
+
+const planner = (): string => vars.plannerModel ?? ""
+const coder = (): string => vars.coderModel ?? ""
+
+// ── Planning ────────────────────────────────────────────────────────────────
+
+/** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
+export const triage = (base: string): Promise<void> =>
+  agent("triage", t.withSkills(vars.triageSkills, t.designTriagePrompt(base)), {
+    label: "Triaging the change",
+    file: REQUIREMENTS,
+    mode: "qa",
+    model: planner(),
+    system: t.designSystem(),
+  })
+
+export const author = (): Promise<void> =>
+  agent("author", t.withSkills(vars.architectureSkills, t.architectureAuthorPrompt()), {
+    label: "Refining the technical plan",
+    file: ARCHITECTURE,
+    mode: "qa",
+    model: planner(),
+    system: t.architectSystem(),
+  })
+
+export const decompose = (): Promise<void> =>
+  agent("decompose", t.withSkills(vars.decomposeSkills, t.architectureDecomposePrompt()), {
+    label: "Decomposing into packages",
+    model: planner(),
+    system: t.architectSystem(),
+  })
+
+export const answerProductQuestions = (): Promise<void> =>
+  human("gate.answer", {
+    message: t.designGateAnswerMessage(),
+    label: "Awaiting your product answers",
+    file: REQUIREMENTS,
+    mode: "qa",
+    acceptClean: true,
+  })
+
+export const answerTechnicalQuestions = (): Promise<void> =>
+  human("gate.answer", {
+    message: t.architectureGateAnswerMessage(),
+    label: "Awaiting your technical answers",
+    file: ARCHITECTURE,
+    mode: "qa",
+    acceptClean: true,
+  })
+
+// ── Packages ────────────────────────────────────────────────────────────────
+
+export const build = (pkg: string): Promise<void> =>
+  agent("building", t.withSkills(vars.buildSkills, t.packagesItemBuildingPrompt(pkg)), {
+    label: "Building",
+    model: coder(),
+    system: t.builderSystem(),
+  })
+
+export const fixSuite = (): Promise<void> =>
+  agent("fix-suite", t.withSkills(vars.fixSkills, t.packagesItemFixSuitePrompt()), {
+    label: "Fixing the check",
+    file: FEEDBACK,
+    model: coder(),
+    system: t.builderSystem(),
+  })
+
+export const fixSpec = (pkg: string): Promise<void> =>
+  agent("fix-spec", t.withSkills(vars.reviewFixSkills, t.packagesItemFixSpecPrompt(pkg)), {
+    label: "Fixing review feedback",
+    file: SPEC_FEEDBACK,
+    model: coder(),
+    system: t.builderSystem(),
+  })
+
+/** Review `pkg` against its spec, focused on the `failing` sections the pre-judge could not clear. */
+export const reviewPackage = (pkg: string, failing: readonly string[] = []): Promise<void> =>
+  agent(
+    "spec.review",
+    t.withSkills(vars.specReviewSkills, t.packagesItemSpecReviewPrompt(pkg, failing)),
+    {
+      label: "Reviewing the package",
+      model: planner(),
+      system: t.specReviewerSystem(),
+      allowEmpty: true,
+    },
+  )
+
+// ── Keeping the suite green ─────────────────────────────────────────────────
+
+export const fix = (): Promise<void> =>
+  agent("fix", t.withSkills(vars.fixSkills, t.buildFixPrompt()), {
+    label: "Fixing the check",
+    file: FEEDBACK,
+    model: coder(),
+    system: t.finisherSystem(),
+  })
+
+export const describeEscalation = (): Promise<void> =>
+  agent("health.describe", t.withSkills(vars.escalateSkills, t.healthDescribePrompt()), {
+    label: "Describing the escalation",
+    file: FEEDBACK,
+    model: coder(),
+    system: t.escalationSystem(),
+    allowEmpty: true,
+  })
+
+export const escalate = (): Promise<void> =>
+  human("health.stop", {
+    message: t.healthStopMessage(),
+    label: "Escalating to a human",
+    file: ESCALATION,
+    acceptClean: true,
+  })
+
+export const escalationExhausted = (): Promise<void> =>
+  human("health.exhausted", {
+    message: t.healthExhaustedMessage(),
+    label: "Escalation exhausted",
+    file: ESCALATION,
+    acceptClean: true,
+  })
+
+// ── Quality and review ──────────────────────────────────────────────────────
+
+/** One quality review, through the skill `lens`. */
+export const reviewQuality = (lens: string): Promise<void> =>
+  agent("quality.reviewing", t.withSkills(lens, t.buildQualityReviewingPrompt(lens)), {
+    label: "Reviewing (one quality lens)",
+    file: QUALITY,
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })
+
+export const fixQuality = (): Promise<void> =>
+  agent("fix-quality", t.withSkills(vars.reviewFixSkills, t.buildFixQualityPrompt()), {
+    label: "Fixing quality findings",
+    file: QUALITY,
+    model: coder(),
+    system: t.finisherSystem(),
+    allowEmpty: true,
+  })
+
+/** Write `.gtd/REVIEW.md` over everything since `base`. */
+export const reviewing = (base: string): Promise<void> =>
+  agent("review.reviewing", t.withSkills(vars.reviewSkills, t.buildReviewReviewingPrompt(base)), {
+    label: "Reviewing",
+    file: REVIEW,
+    mode: "review",
+    model: planner(),
+    system: t.reviewerSystem(),
+    base,
+  })
+
+export const awaitReview = (base: string): Promise<void> =>
+  human("review.await-review", {
+    message: t.buildReviewAwaitReviewMessage(base),
+    label: "Awaiting your review",
+    file: REVIEW,
+    mode: "review",
+    base,
+  })
+
+/** The round at commit `round` left no `.gtd/REVIEW.md`. */
+export const reviewMissing = (round: string): Promise<void> =>
+  human("review.review-missing", {
+    message: t.buildReviewReviewMissingMessage(round),
+    label: "Nothing to review",
+  })
+
+/** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
+export const collecting = (capture: string): Promise<void> =>
+  agent(
+    "review.collecting",
+    t.withSkills(vars.reviewSkills, t.buildReviewCollectingPrompt(capture)),
+    {
+      label: "Collecting your feedback",
+      file: REQUIREMENTS,
+      mode: "qa",
+      model: planner(),
+      system: t.reviewerSystem(),
+      allowEmpty: true,
+    },
+  )