@pmelab/gtd 17.0.0 → 17.3.0

package/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["../claude/hooks/register.tsx"] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "17.0.0",
+  "version": "17.3.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -16,7 +16,14 @@
     "src/workflows/",
     "README.md",
     "LICENSE",
-    "schema.json"
+    "schema.json",
+    ".claude-plugin/plugin.json",
+    "hooks/",
+    "bin/",
+    "claude/hooks/",
+    "claude/types/",
+    "!claude/**/*.test.ts",
+    "skills/"
   ],
   "publishConfig": {
     "access": "public",

package/skills/authoring/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: authoring
+description: >-
+  Write or edit a gtd workflow (the repository's `gtd.config.ts`). Use when the
+  user asks to create a custom gtd workflow, customize or change their
+  workflow's shape, add/remove/rename a step, add a gate/phase/review step,
+  change what an agent is prompted to do, adjust fix caps, models, or steering
+  files, or otherwise change the flow gtd runs.
+---
+
+# Authoring a gtd workflow
+
+A gtd workflow is **plain async TypeScript**: a `gtd.config.ts` at the
+repository root default-exports the **flow**, one async function that awaits
+**steps** built from `@pmelab/gtd/flows`; optional `defaults` (process
+settings), `envDefaults` (environment settings), `summary`, `base` and
+`steering` (steering file → mode, for the LSP) exports sit beside it, and any
+other export is a helper gtd ignores. Every step is a commit; gtd finds where a
+process rests by **replaying** the flow over the episode's commits, so the git
+history IS the state and nothing is stored anywhere else.
+
+Your job is to produce or edit that module so it loads cleanly and does what the
+user wants. Driving a workflow once it exists is a separate concern — that is
+what a driver does.
+
+**Trust:** gtd evaluates `gtd.config.ts` on every command that resolves workflow
+state (`gtd next` and `gtd lsp` included). It is code the user's repository
+runs; write it with the same care as a build script.
+
+## Golden rule: start from the bundled default, edit incrementally
+
+Do **not** write a workflow from a blank page unless the user wants something
+tiny. gtd ships one known-good workflow and runs it when no `gtd.config.ts` is
+found, and publishes it as `@pmelab/gtd/workflow`: its default export is that
+flow, and every phase and single step it is built from is a named export. Start
+by importing what you keep and writing only what changes:
+
+```ts
+import { start } from "@pmelab/gtd/flows"
+import bundled, { afterTail, buildTail } from "@pmelab/gtd/workflow"
+
+export {
+  defaults,
+  envDefaults,
+  summary,
+  base,
+  steering,
+} from "@pmelab/gtd/workflow"
+
+export default async ({ entry }) =>
+  entry === "hotfix"
+    ? afterTail(await buildTail(true, start()))
+    : bundled({ entry })
+```
+
+To change a phase itself, read its source in the npm package
+(`node_modules/@pmelab/gtd/src/workflows/`, or under `$(npm root -g)` for a
+global install) and write your own version in `gtd.config.ts`, reusing its
+single steps.
+
+There is no `extends`/merge: the innermost `gtd.config.ts` walking up from the
+current directory is the whole workflow. If one already exists, read it and edit
+it in place.
+
+Prefer the bundled workflow's own parts over re-implementing them — `healthy`,
+`escalation`, `gate`, `design`, `architecturePass`, `packages`, `specReview`,
+`qualityLap`, `review`, `buildTail`, and single steps like `triage` or `fix`.
+Their full step names are versioned API.
+
+Make one small change, **verify it loads** (see "Verify"), then make the next. A
+workflow that fails to load breaks every gtd command in the repository.
+
+## The step API
+
+| Call                         | Actor   | Rest content | Resolves to                            |
+| ---------------------------- | ------- | ------------ | -------------------------------------- |
+| `agent(name, prompt, opts?)` | `agent` | `prompt`     | `void`, once an agent turn landed      |
+| `human(name, opts?)`         | `human` | `message`    | `void`, once a person landed           |
+| `run(name, body, opts?)`     | `check` | `script`     | `void`, once the run's tree landed     |
+| `judge(name, spec)`          | `judge` | `message`    | `{ answers, truncated }`               |
+| `restart()`                  | —       | —            | never: ends the episode from any depth |
+
+- `run` body: a POSIX `sh` string the driver runs verbatim. Decide in flow code,
+  then render the script from those values — `check(name, command, …)` and the
+  exported `checkScript`, `revertScript`, `restoreScript`, `removeScript`,
+  `moveScript` and `quote` do that for the common cases. **A run's outcome is
+  what it leaves in the tree** — read it back with `changes()` and `read()`.
+- `judge` takes `{ questions, evidence, message?, label? }`. Questions are
+  `{ id, primitive: "noul" | "choice" | "score", instructions, criteria }`;
+  `evidence` is an object of strings, the `judgeBudgetBytes` var split evenly
+  across its keys. It resolves to `answers` — one `{ answer, p }` per question
+  id (a `noul` reads back as `"yes"`/`"no"`), `undefined` when the verdict left
+  it out — and `truncated`, the evidence keys the budget cut. Compare answers
+  with plain `if`s; landing with no verdict leaves every answer `undefined`, so
+  make `undefined` take the conservative branch.
+- A person or a driver sees a rest as one of the five content kinds `capture` (a
+  dirty tree at a human step), `message`, `script`, `prompt`, `stalled`. Every
+  step you add must fit one of them; there is no sixth.
+
+Options (all optional): `label`, `file` (a `.gtd/` path), `mode` (needs `file`;
+`qa`, `review`, or a `.gtdrc` `modes:` name), `message` (human/judge), `model`,
+`system` (agent), `allowEmpty` (agent), `acceptClean` (human), `base` (the
+commit the step reviews since — what `gtd base` prints).
+
+Helpers — pure reads of the commit replay stands on (the tree the last step
+left, never the live working tree): `read(path)`, `glob(pattern)`,
+`changes(glob?)` (what the last step changed: `{ path, status, before, after }`
+per path, `status` one of `"added"`/`"modified"`/`"deleted"`, plus `paths` and
+`get(path)`), `sections(text)` (`## ` headings), `openQuestions(text)` (a `qa`
+document's unanswered questions), `vars` (process settings, pinned at process
+start — safe to branch on), `env` (environment settings, read live — only for
+prompt text, step options and `run()` bodies, never a branch), `head()` (the
+commit the flow stands on) and `start()` (the process's diff base). State a flow
+needs across steps — a counter, the previous report, a review round's base —
+lives in local variables; replay rebuilds them.
+
+Composition: `scope(name, fn)` prefixes step names (`build.fix`) and sets their
+**memory scope** (one scope = one agent conversation = one model/system — mixing
+them inside a scope fails the process); `scope({ name?, model, system }, fn)`
+also sets defaults for agent steps inside. `refuse(message)` refuses the pending
+landing — call it right after the step whose turn you reject.
+`@pmelab/gtd/flows` exports `requireProgress(file)`, `requireAnswers(file)` and
+`requireRevert(edited, base)`, three such checks ready-made.
+
+## Names, commits and history
+
+- The step name is the `<to>` in `gtd(<actor>): <from> → <to>`, and every
+  landing carries `Gtd-Step: <name>#<n>`. It is also the memory scope key (up to
+  the last dot). Rename a step and every process resting on it diverges.
+- An episode ends when the flow returns or calls `restart()`; the next starts at
+  the flow's first step on an ordinary start — that step is where a finished
+  process waits (the bundled one is `human("idle", …)`).
+- `gtd --entry <name>` starts a process with the flow's `{ entry }` argument set
+  to `<name>` (`undefined` on an ordinary start). Branch on it, and `refuse()`
+  names you don't accept; a flow that never reads `entry` accepts none. An
+  `export const base = (entry, vars) => commitish | undefined` fixes an entered
+  process's diff base. `--var <name>=<value>` only pins process settings: names
+  the workflow's `defaults` or `.gtdrc` `vars:` declare — never an environment
+  setting.
+
+## Landing rules you are designing for
+
+- **Agent turn changed something** → the step completes.
+- **Agent turn changed nothing** → an **attempt**: an empty commit, the process
+  stays; the next dispatch is a **stall**. Pass `allowEmpty: true` when "nothing
+  to change" is a legitimate result (a reviewer approving by writing nothing).
+- **Human landing changed nothing** → a no-op, the gate keeps waiting — unless
+  `acceptClean: true`, which makes "change nothing" mean "accept as-is".
+- **Run landed a clean tree** → the step completes; if replay comes straight
+  back to the same step, the landing is **settled** (the driver stops).
+- **Nothing the flow branches on explains the turn** → call `refuse(message)`:
+  nothing lands, `gtd land` exits 1.
+
+Branch on what the step left, not on who acted:
+
+```ts
+await run(
+  "check",
+  `${env.testCommand} > .gtd/FEEDBACK.md 2>&1 && rm -f .gtd/FEEDBACK.md`,
+)
+if (read(".gtd/FEEDBACK.md") !== undefined) {
+  await agent("fix", "Fix what .gtd/FEEDBACK.md reports, then delete it.", {
+    file: ".gtd/FEEDBACK.md",
+  })
+}
+```
+
+Keep `.gtd/` clean across processes: a steering file should be deleted by the
+step that consumes it. A workflow that accumulates files in `.gtd/` is almost
+certainly a bug.
+
+## Rules for flow code
+
+Flow code is replayed on every command, so it must reach the same steps every
+time it sees the same history. `run()` bodies and module top-level code are
+exempt. gtd does not read the source ahead of time: breaking a rule shows up
+when replay runs, as an error or, for nondeterminism, as a divergence later.
+
+- No IO or nondeterminism in flow code — no clock, randomness, environment,
+  network or filesystem. Read the tree through the helpers; do IO inside a
+  `run()` body.
+- Await only a step, `scope()`, or a function that steps. Anything else fails
+  with `the flow awaited something that is not a step`.
+- One call site per step name — wrap a reused helper in two different
+  `scope()`s.
+- No `try`/`catch` around a step: `restart()` and refusals travel as exceptions.
+- Only the options a step accepts; an unknown key fails naming the step.
+- The default export is a flow that reaches a step on an ordinary start — the
+  same step whatever the repository's files hold; every `mode` must exist.
+
+## Verify (after every change)
+
+1. **`gtd next`** — loads the workflow (printing every load error at once) and
+   shows the resolved rest: step, actor, label, file. It never mutates, so run
+   it as often as you like.
+2. **A scratch repository** with at least one commit — make the change a step
+   expects, run `gtd land --json=script | sh`, then `gtd next` to see where it
+   went. A flow is code, so walking it is the only way to see its branches.
+
+`gtd validate` is NOT for this — it validates a **steering file**, not the
+workflow.
+
+## Worked example: add an approval gate before building
+
+In the bundled default, `planAndBuild` runs the design phase, the architecture
+pass (which writes `.gtd/packages/`), then builds the packages. Add a human
+sign-off between the two:
+
+```ts
+const planAndBuild = async (): Promise<void> => {
+  for (;;) {
+    await design()
+    await architecturePass()
+    await human("approve-plan", {
+      message:
+        "The packages under .gtd/packages/ are ready. Edit them to adjust the plan, or change nothing — then run `gtd land` to start building.",
+      label: "Approve the plan",
+      acceptClean: true,
+    })
+    await packages()
+    if ((await buildTail(false)) === "signoff") return
+    await reUnwind()
+  }
+}
+```
+
+`acceptClean: true` is what makes an untouched landing approve; without it the
+gate would wait for an edit. `approve-plan` sits in the `root` scope and is a
+new, unique name. Verify: `gtd next` loads without errors, and in a scratch
+repository a landing at `architecture.decompose` (or `architecture-promote`) now
+leads to `approve-plan`, and an untouched landing there to
+`packages.item.building`.
+
+## No migration
+
+A process's commits only make sense to the workflow that made them. If the
+workflow changes under an in-flight process so its history no longer replays to
+the steps its commits name, gtd refuses with a divergence error telling you to
+run `gtd abandon`. Tell the user to finish or `gtd abandon` any in-flight
+process before switching to the edited workflow.
+
+## Notes
+
+- This skill is versioned in the gtd repository, not auto-installed. When gtd is
+  upgraded, re-copy it from the new version's `skills/authoring/SKILL.md`.
+- Where this file and the code disagree, the code wins: the step API's own doc
+  comments in `@pmelab/gtd/flows`, and the bundled workflow under
+  `src/workflows/`.

package/src/workflows/prose.ts

@@ -68,7 +68,8 @@ deliberately separate from whoever wrote the code, with no attachment
 to it. Write a structured review document grouping a diff into
 chunks; classify a round of the human's feedback as actionable or
 just approving; answer the human's questions inline in the review;
-and, when asked, fix the small nits the human flagged in one batch.
+and, when asked, fix the small nits the human flagged and the risks
+you marked yourself, each in one batch.
 Beyond that you never fix or build anything yourself.`
 
 export const specReviewerPersona = `You are the adversarial spec-conformance checker in gtd's build
@@ -179,13 +180,20 @@ export const questionBarReturn = `- This lap continues the same goal as the firs
   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
+- Never re-raise a deleted question. A settled \`## Answered Questions\`
+  entry stays settled, except one carrying a human footnote on its
+  \`### \` heading: that is the only entry that may change. Fold the note
+  in, then either rewrite the recorded answer in place (still under
+  \`## Answered Questions\`) or, when the note leaves the point genuinely
+  open, move it back to \`## Open Questions\` as a fresh fork with
+  options and the \`_your answer_\` slot. A note that only asks a
+  question follows the footnote rule: one \`- A:\` reply, answer unchanged
 - 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\`
+  already settled under \`## Answered Questions\` that carries no
+  footnote on its heading
 - 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

package/src/workflows/review.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it } from "vitest"
 import { installContext, type Change, type JudgeAnswer, type StepRequest } from "../flows/index.js"
 import { review, type ReviewOutcome } from "./review.js"
+import { unified } from "./index.js"
 import { fixtureContext } from "./text.fixture.js"
 
 afterEach(() => installContext(undefined))
@@ -30,6 +31,8 @@ interface Drive {
   readonly vars?: Readonly<Record<string, string>>
   /** The REVIEW.md the human leaves; defaults to `notes` laid over the baseline. */
   readonly after?: string
+  /** The REVIEW.md each `review.reviewing` turn writes, in order; also raises the review-turn stop to one past the last. */
+  readonly reviewDocs?: readonly (string | undefined)[]
 }
 
 interface Run {
@@ -51,7 +54,10 @@ const drive = async (d: Drive): Promise<Run> => {
   let reviews = 0
   const effects: Record<string, () => void> = {
     "review.reviewing": () => {
-      if (++reviews > 1) throw new Stop()
+      const docs = d.reviewDocs
+      if (++reviews > (docs?.length ?? 0) + (docs === undefined ? 1 : 0)) throw new Stop()
+      const written = docs?.[reviews - 1]
+      if (written !== undefined) files.set(REVIEW, written)
     },
     "review.await-review": () => {
       if (++awaits > 1) throw new Stop()
@@ -104,6 +110,65 @@ const drive = async (d: Drive): Promise<Run> => {
 
 const verdict = (answer: string, p = 0.9): JudgeAnswer => ({ answer, p })
 
+describe("the risk-fix pass", () => {
+  const risky = doc(["Risk: drops the carry", "sub"])
+  const clean = doc(["add — fine", "sub"])
+
+  it("a marked risk is fixed, kept green, re-reviewed, then rests at the gate", async () => {
+    const run = await drive({ notes: [], reviewDocs: [risky, clean] })
+    expect(run.log.slice(0, 5)).toEqual([
+      "review.reviewing",
+      "review.fix-risks",
+      "health.check",
+      "review.reviewing",
+      "review.await-review",
+    ])
+    expect(run.prompts.get("review.fix-risks")).toContain("risk-1")
+    expect(run.prompts.get("review.fix-risks")).toContain("Risk: drops the carry")
+    expect(run.prompts.get("review.fix-risks")).toContain("Leave `.gtd/REVIEW.md` untouched")
+  })
+
+  it("a risk the re-review still marks goes to the gate with no second fix", async () => {
+    const run = await drive({ notes: [], reviewDocs: [risky, risky] })
+    expect(run.log.filter((n) => n === "review.fix-risks")).toHaveLength(1)
+    expect(run.log.slice(0, 5)).toEqual([
+      "review.reviewing",
+      "review.fix-risks",
+      "health.check",
+      "review.reviewing",
+      "review.await-review",
+    ])
+  })
+
+  it("no marker means no fix-risks step", async () => {
+    const run = await drive({ notes: [], reviewDocs: [clean] })
+    expect(run.log).not.toContain("review.fix-risks")
+    expect(run.log[0]).toBe("review.reviewing")
+    expect(run.log[1]).toBe("review.await-review")
+  })
+
+  it("a nit re-review round gets its own single pass", async () => {
+    const run = await drive({
+      notes: ["add — typo", "sub", "mul"],
+      answers: { "note-1": verdict("nit") },
+      reviewDocs: [undefined, risky, clean],
+    })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.fix-nits",
+      "health.check",
+      "review.closing",
+      "review.reviewing",
+      "review.fix-risks",
+      "health.check",
+      "review.reviewing",
+      "review.await-review",
+    ])
+  })
+})
+
 describe("review verdict routing", () => {
   const notes = ["add — typo", "sub", "mul"]
 
@@ -245,3 +310,24 @@ describe("review verdict routing", () => {
     expect(run.result).toMatchObject({ verdict: "feedback", edited: [] })
   })
 })
+
+describe("the default quality lenses", () => {
+  it("are the six lenses in the settled order", () => {
+    expect(unified.defaults.qualityReviews!.split(",").map((l) => l.trim())).toEqual([
+      "correctness",
+      "owasp-security",
+      "ponytail-review",
+      "test-audit",
+      "conventions",
+      "spec-challenge",
+    ])
+  })
+
+  it("expose builtInLenses through the public workflow module", () => {
+    expect(Object.keys(unified.builtInLenses).sort()).toEqual([
+      "conventions",
+      "correctness",
+      "spec-challenge",
+    ])
+  })
+})

package/src/workflows/review.ts

@@ -17,7 +17,7 @@ import {
   type Change,
   type JudgeQuestion,
 } from "../flows/index.js"
-import { reviewNotes, stripCodeThreads, type ReviewNote } from "../steering/index.js"
+import { reviewNotes, reviewRisks, stripCodeThreads, type ReviewNote } from "../steering/index.js"
 import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
 import {
   answerReviewQuestions,
@@ -26,6 +26,7 @@ import {
   fix,
   fixNits,
   fixQuality,
+  fixRisks,
   QUALITY,
   REQUIREMENTS,
   REVIEW,
@@ -43,8 +44,8 @@ export const qualityLenses = (): readonly string[] =>
     .filter((lens) => lens.length > 0)
 
 /**
- * One review turn per lens over the whole change, each appending what it
- * finds blocking to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
+ * One review turn per lens over the whole change, each appending every
+ * finding to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
  * has any.
  */
 export const qualityLap = async (): Promise<"clean" | "findings"> => {
@@ -270,6 +271,20 @@ const finish = async (
   return routeNotes(notes, { round, escalations, close, outcome, unfolded })
 }
 
+/** Write the review; if it marks risks, fix them, keep green, and write it again — once, so the re-review's own risks reach the human unfixed. */
+const reviewOnce = async (
+  base: string,
+  carry: string | undefined,
+  escalations: EscalationCount,
+): Promise<void> => {
+  await reviewing(base, carry)
+  const risks = reviewRisks(read(REVIEW) ?? "")
+  if (risks.length === 0) return
+  await fixRisks(risks)
+  await healthy(fix, { escalations })
+  await reviewing(base, carry)
+}
+
 /**
  * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
  * reviews and signs off or comments, and each note is judged: edits go to
@@ -282,7 +297,7 @@ export const review = async (
 ): Promise<ReviewOutcome> => {
   let carry: string | undefined
   for (;;) {
-    await reviewing(base, carry)
+    await reviewOnce(base, carry, escalations)
     carry = undefined
     let reviewed = head()
     let collectedAt: string | undefined

package/src/workflows/skills.test.ts

@@ -26,7 +26,7 @@ import { skills } from "./skills.js"
 //   - build.review.answer-review-questions, build.review.fix-nits — NOT yet
 //     e2e-grounded; only steps.test.ts's preamble checks, which use local names
 describe("the bundled workflow's skills map", () => {
-  it("declares exactly the sixteen bundled agent steps, by full name", () => {
+  it("declares exactly the seventeen bundled agent steps, by full name", () => {
     expect(Object.keys(skills).sort()).toEqual(
       [
         "design.triage",
@@ -44,6 +44,7 @@ describe("the bundled workflow's skills map", () => {
         "build.review.reviewing",
         "build.review.answer-review-questions",
         "build.review.fix-nits",
+        "build.review.fix-risks",
         "build.review.collecting",
       ].sort(),
     )

package/src/workflows/skills.ts

@@ -33,5 +33,6 @@ export const skills: Readonly<Record<string, readonly string[]>> = {
   "build.review.reviewing": ["code-review-and-quality"],
   "build.review.answer-review-questions": ["code-review-and-quality"],
   "build.review.fix-nits": ["incremental-implementation", "code-simplification"],
+  "build.review.fix-risks": ["debugging-and-error-recovery", "incremental-implementation"],
   "build.review.collecting": ["code-review-and-quality"],
 }

package/src/workflows/steps.test.ts

@@ -91,6 +91,46 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(prompt).toContain("owasp-security")
   })
 
+  it("correctness loads code-review-and-quality and carries all four trace points", async () => {
+    const request = await capture(() => steps.reviewQuality("correctness"))
+    expect(agentSkillsOption(request)).toEqual(["code-review-and-quality"])
+    const body = JSON.stringify(request)
+    for (const point of [
+      "partial-failure",
+      "format, not just its presence",
+      "parallel write paths",
+      "contract test",
+    ])
+      expect(body).toContain(point)
+  })
+
+  it.each(["conventions", "spec-challenge"])(
+    "%s sends no skills and carries its brief",
+    async (lens) => {
+      const request = await capture(() => steps.reviewQuality(lens))
+      expect(agentSkillsOption(request)).toEqual([])
+      expect(JSON.stringify(request)).toContain(
+        steps.builtInLenses[lens]!.brief.split("\n")[0]!.slice(0, 40),
+      )
+    },
+  )
+
+  it("an unknown lens loads itself as a skill, with no brief", async () => {
+    const request = await capture(() => steps.reviewQuality("my-lens"))
+    expect(agentSkillsOption(request)).toEqual(["my-lens"])
+    expect(JSON.stringify(request)).not.toContain("This lens's brief")
+  })
+
+  it("a configured build.quality.reviewing entry replaces a built-in lens's skills; the brief stays", async () => {
+    const prompt = agentPrompt(
+      await capture(() => steps.reviewQuality("conventions"), {
+        "quality.reviewing": ["my-org-checklist"],
+      }),
+    )
+    expect(prompt).toContain("my-org-checklist")
+    expect(prompt).toContain("AGENTS.md")
+  })
+
   it("fixQuality carries build.fix-quality's bundled skills", async () => {
     const prompt = agentPrompt(await capture(() => steps.fixQuality()))
     expect(prompt).toContain("incremental-implementation, code-simplification")
@@ -143,6 +183,19 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
   })
 
+  it("fixRisks fixes every risk, tolerates an empty turn, and leaves .gtd/REVIEW.md alone", async () => {
+    const request = await capture(() =>
+      steps.fixRisks([{ id: "risk-1", anchor: "calc ./a.ts#1-1", text: "Risk: drops it" }]),
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.fix-risks")
+    expect(request.options).toMatchObject({ allowEmpty: true })
+    expect(request.prompt).toContain("debugging-and-error-recovery, incremental-implementation")
+    expect(request.prompt).toContain("risk-1 — calc ./a.ts#1-1")
+    expect(request.prompt).toContain("Risk: drops it")
+    expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
+  })
+
   it("reviewing names the carry-over commit only when given one", async () => {
     const bare = await capture(() => steps.reviewing("base"))
     const carried = await capture(() => steps.reviewing("base", "abc1234"))

package/src/workflows/steps.ts

@@ -134,6 +134,18 @@ export const escalationExhausted = (): Promise<void> =>
 
 // ── Quality and review ──────────────────────────────────────────────────────
 
+export interface BuiltInLens {
+  readonly skills: readonly string[]
+  readonly brief: string
+}
+
+/** Lenses the workflow defines itself, not bundled skills: `skills/` is not in the npm package, and a missing lens skill burns a turn silently. */
+export const builtInLenses: Readonly<Record<string, BuiltInLens>> = {
+  correctness: { skills: ["code-review-and-quality"], brief: t.correctnessBrief },
+  conventions: { skills: [], brief: t.conventionsBrief },
+  "spec-challenge": { skills: [], brief: t.specChallengeBrief },
+}
+
 /**
  * One quality review, through the skill `lens`. `lens` rides as this turn's
  * own `skills` option — a `.gtdrc` `build.quality.reviewing` entry still
@@ -141,14 +153,18 @@ export const escalationExhausted = (): Promise<void> =>
  * but absent one the lens itself is what the turn loads by default.
  */
 export const reviewQuality = (lens: string): Promise<void> =>
-  t.agentWithSkills("quality.reviewing", t.buildQualityReviewingPrompt(lens), {
-    label: "Reviewing (one quality lens)",
-    file: QUALITY,
-    model: planner(),
-    system: t.reviewerSystem(),
-    allowEmpty: true,
-    skills: [lens],
-  })
+  t.agentWithSkills(
+    "quality.reviewing",
+    t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief),
+    {
+      label: "Reviewing (one quality lens)",
+      file: QUALITY,
+      model: planner(),
+      system: t.reviewerSystem(),
+      allowEmpty: true,
+      skills: builtInLenses[lens]?.skills ?? [lens],
+    },
+  )
 
 export const fixQuality = (): Promise<void> =>
   t.agentWithSkills("fix-quality", t.buildFixQualityPrompt(), {
@@ -192,6 +208,16 @@ export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
     system: t.reviewerSystem(),
   })
 
+/** Fix the `Risk:`-marked notes the reviewer named. Shares the `build.review` conversation like `fixNits`; an empty turn means the risk was judged false. */
+export const fixRisks = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills("review.fix-risks", t.buildReviewFixRisksPrompt(notes), {
+    label: "Fixing the reviewer's risks",
+    file: REVIEW,
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })
+
 export const awaitReview = (base: string): Promise<void> =>
   human("review.await-review", {
     message: t.buildReviewAwaitReviewMessage(base),