@pmelab/gtd 16.0.0 → 17.2.0

package/hooks/hooks.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "16.0.0",
+  "version": "17.2.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/schema.json

@@ -5,7 +5,7 @@
   "properties": {
     "vars": {
       "type": "object",
-      "description": "Flat name -> scalar map merged into the workflow's vars. Scalars are coerced to strings.",
+      "description": "Flat name -> scalar map merged into the workflow's process settings (defaults), pinned for the whole process at its start. Scalars are coerced to strings.",
       "additionalProperties": {
         "type": [
           "string",
@@ -14,6 +14,38 @@
         ]
       }
     },
+    "env": {
+      "type": "object",
+      "description": "Flat name -> scalar map merged into the workflow's environment settings (envDefaults) — values that change how a step runs on this machine, like the test command or a model hint. Read fresh on every gtd call, never pinned to a process. GTD_<NAME> environment variables override these entries. Scalars are coerced to strings.",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean"
+        ]
+      }
+    },
+    "judge": {
+      "type": "object",
+      "required": [],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": [
+            "fixed",
+            "jev",
+            "llm"
+          ],
+          "description": "Judge provider `gtd judge run` uses when no --provider flag and no GTD_JUDGE_PROVIDER is set. Absent means auto: jev when TYPESAFE_API_KEY is set, otherwise llm."
+        },
+        "model": {
+          "type": "string",
+          "description": "Model for provider llm, used when no --model flag and no GTD_JUDGE_MODEL is set. Pairing it with another provider is an error."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Which judge `gtd judge run` uses, when no flag or GTD_JUDGE_* variable says."
+    },
     "modes": {
       "type": "object",
       "description": "Steering-file modes a workflow step's mode: may name. Each entry declares at least one of format/validate: shell commands gtd runs via bash with $GTD_FILE set to the steering file's path. format rewrites the file in place; validate exits 0 when valid, non-zero with findings on stdout/stderr otherwise. The halves layer independently, so naming a built-in mode (qa/review) and declaring only format: adds formatting while keeping gtd's own validation. gtd ships no formatter — bring your own (prettier, dprint, a script).",

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/flows/runtime.ts

@@ -136,6 +136,7 @@ export interface FlowContext {
   readonly threads: (text: string) => readonly ThreadInfo[]
   readonly codeThreads: () => readonly CodeThreadInfo[]
   readonly vars: Readonly<Record<string, string>>
+  readonly env: Readonly<Record<string, string>>
   readonly head: () => string
   readonly start: () => string
   /**
@@ -256,19 +257,31 @@ export const start = (): string => ctx().start()
 export const skillsFor = (localName: string, ownSkills?: readonly string[]): readonly string[] =>
   ctx().skillsFor(localName, ownSkills)
 
-/** The merged workflow variables. */
-export const vars: Readonly<Record<string, string>> = new Proxy(
-  {},
-  {
-    get: (_target, key) => (typeof key === "string" ? ctx().vars[key] : undefined),
-    has: (_target, key) => typeof key === "string" && key in ctx().vars,
-    ownKeys: () => Object.keys(ctx().vars),
-    getOwnPropertyDescriptor: (_target, key) =>
-      typeof key === "string" && key in ctx().vars
-        ? { enumerable: true, configurable: true, value: ctx().vars[key] }
-        : undefined,
-  },
-)
+const settingsProxy = (
+  read: () => Readonly<Record<string, string>>,
+): Readonly<Record<string, string>> =>
+  new Proxy(
+    {},
+    {
+      get: (_target, key) => (typeof key === "string" ? read()[key] : undefined),
+      has: (_target, key) => typeof key === "string" && key in read(),
+      ownKeys: () => Object.keys(read()),
+      getOwnPropertyDescriptor: (_target, key) =>
+        typeof key === "string" && key in read()
+          ? { enumerable: true, configurable: true, value: read()[key] }
+          : undefined,
+    },
+  )
+
+/** The process settings: pinned at process start, so flow code may branch on them. */
+export const vars: Readonly<Record<string, string>> = settingsProxy(() => ctx().vars)
+
+/**
+ * The environment settings: resolved live on every invocation. Flow code must
+ * read them only where they cannot change the next step (step options, script
+ * bodies) — replay cannot enforce this.
+ */
+export const env: Readonly<Record<string, string>> = settingsProxy(() => ctx().env)
 
 // ── Text utilities ──────────────────────────────────────────────────────────
 
@@ -343,6 +356,7 @@ export interface SummaryContext {
   readonly processCost: number
   readonly processCostByModel: readonly { readonly model: string; readonly cost: number }[]
   readonly vars: Readonly<Record<string, string>>
+  readonly env: Readonly<Record<string, string>>
 }
 
 /** `gtd summary`'s prompt — a workflow module's optional `summary` export. */

package/src/workflows/health.ts

@@ -1,6 +1,7 @@
 import {
   answered,
   check,
+  env,
   human,
   judge,
   numeric,
@@ -17,7 +18,7 @@ export const FIX_CAP = 3
 
 /** Run the suite as step `name`; resolves `true` when it passed. A failure is in `.gtd/FEEDBACK.md`. */
 export const baseline = (name: string, label = "Checking the baseline"): Promise<boolean> =>
-  check(name, vars.testCommand ?? "", { report: FEEDBACK, label })
+  check(name, env.testCommand ?? "", { report: FEEDBACK, label })
 
 /** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
 export interface EscalationCount {
@@ -95,7 +96,7 @@ export const healthy = async (
   let fixes = options.fixesSoFar ?? 0
   let previous: string | undefined
   for (;;) {
-    const green = await check("health.check", vars.testCommand ?? "", {
+    const green = await check("health.check", env.testCommand ?? "", {
       report: FEEDBACK,
       label: "Running checks",
       // Swept only on green: an unresolved analysis survives every retry.

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

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"],
 }