@pmelab/gtd 23.1.0 → 24.0.0

package/src/workflows/feature/feature.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext, type StepRequest } from "../../flows/index.js"
+import { fixtureContext } from "../shared/text.fixture.js"
+import { ordinaryStart } from "./feature.js"
+
+afterEach(() => installContext(undefined))
+
+const FILES: Readonly<Record<string, string>> = {
+  ".gtd/REVIEW.md": "# Review: abc1234\n",
+  ".gtd/REVIEW.orig.md": "# Review: abc1234\n",
+}
+
+describe("an ordinary feature start", () => {
+  it("refuses a pending hand-off right after idle, before unwinding", async () => {
+    const steps: StepRequest[] = []
+    installContext(
+      fixtureContext(
+        {},
+        {
+          step: (request: StepRequest) => {
+            steps.push(request)
+            return Promise.resolve()
+          },
+          refuse: (message: string): never => {
+            throw new Error(message)
+          },
+          pushScope: () => undefined,
+          popScope: () => undefined,
+          read: (path) => FILES[path],
+          head: () => "c1",
+          start: () => "c0",
+        },
+      ),
+    )
+    await expect(ordinaryStart()).rejects.toThrow(".gtd/REVIEW.orig.md is a pending hand-off")
+    expect(steps.map((s) => ("name" in s ? s.name : s.kind))).toEqual(["idle"])
+  })
+})

package/src/workflows/{bundled.ts → feature/feature.ts}

@@ -7,43 +7,22 @@ import {
   revertScript,
   run,
   start,
-  type Doors,
-  type WorkflowBase,
-  type Summary,
-} from "../flows/index.js"
-import { baseline, gate } from "./health.js"
+} from "../../flows/index.js"
+import { gate } from "../shared/health.js"
+import { shipped } from "../shared/options.js"
+import type { FrozenScenarios } from "../shared/scenarios.js"
+import { FEEDBACK, REVIEW } from "../shared/steps.js"
+import { refusePendingHandOff } from "../shared/tail.js"
+import * as t from "../shared/text.js"
 import { packages } from "./packages.js"
 import { architecture, design } from "./planning.js"
-import type { FrozenScenarios } from "./scenarios.js"
 import { buildTail, type ReviewOutcome } from "./review.js"
-import { ARCHITECTURE, FEEDBACK, REQUIREMENTS, REVIEW } from "./steps.js"
-import { shipped } from "./options.js"
-import * as t from "./text.js"
 
-// gtd's bundled workflows. Any change to the tree starts a process:
-// `idle` → `unwind` reverts the sketch (its intent survives in history) → a
+// The ordinary start. Any change to the tree starts a process: `idle` →
+// `unwind` reverts the sketch (its intent survives in history) → a
 // green-baseline gate → design, architecture and one package per concern →
 // the quality lap → human review, which signs off (the episode ends back at
-// `idle`) or sends a full re-plan lap. `feature` is that ordinary start;
-// `gtd --workflow fix` and `gtd --workflow review --var reviewBase=<commitish>`
-// enter the same build tail further in. Each of the three is a factory over
-// the settings in `./vars.ts`; its flow is exported too, for composing.
-//
-// Every part is exported for other workflows to compose; see the modules
-// re-exported below.
-
-export { threads, type ThreadInfo } from "../flows/index.js"
-export { defaults, envDefaults } from "./vars.js"
-export { ShippedOptions } from "./options.js"
-export { skills } from "./skills.js"
-export { access } from "./access.js"
-export { agentWithSkills } from "./text.js"
-export * from "./steps.js"
-export * from "./health.js"
-export * from "./planning.js"
-export * from "./packages.js"
-export * from "./scenarios.js"
-export * from "./review.js"
+// `idle`) or sends a full re-plan lap.
 
 /** Revert the sketch that started the process out of the working tree; its intent survives in history. */
 export const unwind = (): Promise<void> => {
@@ -97,6 +76,7 @@ export const afterTail = async (outcome: ReviewOutcome): Promise<void> => {
 /** An ordinary start: wait at `idle`, unwind the sketch, check the baseline, then plan and build. */
 export const ordinaryStart = async (): Promise<void> => {
   await human("idle", { message: t.idleMessage(), label: "Idle", file: ".gtd/TODO.md" })
+  refusePendingHandOff()
   await unwind()
   if (changes(FEEDBACK).some((c) => c.status !== "deleted")) {
     await human("unwind-failed", {
@@ -109,36 +89,4 @@ export const ordinaryStart = async (): Promise<void> => {
   await planAndBuild(start())
 }
 
-/** Repair a red baseline through the build tail, as its own reviewed commit. */
-export const fixFlow = async (): Promise<void> => {
-  if (await baseline("fix-precheck")) return
-  return afterTail(await buildTail(true, start()))
-}
-
-/** Pure review of everything since `reviewBase`. */
-export const reviewFlow = async (): Promise<void> => {
-  await gate("review-gate", t.reviewGateBlockedMessage())
-  return afterTail(await buildTail(false, start()))
-}
-
 export const feature = shipped(ordinaryStart)
-export const fix = shipped(fixFlow)
-export const review = shipped(reviewFlow)
-
-export default feature
-
-export const summary: Summary = t.summaryPrompt
-
-export const steering = { [REQUIREMENTS]: "qa", [ARCHITECTURE]: "qa", [REVIEW]: "review" }
-
-export const base: WorkflowBase = (workflow, vars) =>
-  workflow === "review" ? (vars.reviewBase ?? "") : undefined
-
-export const doors: Doors = {
-  fix: { workflow: "fix" },
-  review: {
-    workflow: "review",
-    args: [{ name: "base", optional: true }],
-    vars: ({ base }) => (base === undefined ? {} : { reviewBase: base }),
-  },
-}

package/src/workflows/{packages.test.ts → feature/packages.test.ts}

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it } from "vitest"
-import { installContext, type Change, type StepRequest } from "../flows/index.js"
+import { installContext, type Change, type StepRequest } from "../../flows/index.js"
 import { declaredTests, packages, SCENARIO_PACKAGE } from "./packages.js"
-import { fixtureContext } from "./text.fixture.js"
+import { fixtureContext } from "../shared/text.fixture.js"
 
 afterEach(() => installContext(undefined))
 

package/src/workflows/{packages.ts → feature/packages.ts}

@@ -8,9 +8,9 @@ import {
   removeScript,
   run,
   scope,
-} from "../flows/index.js"
-import { healthy } from "./health.js"
-import { freezeScenarios, guarded, type FrozenScenarios } from "./scenarios.js"
+} from "../../flows/index.js"
+import { healthy } from "../shared/health.js"
+import { freezeScenarios, guarded, type FrozenScenarios } from "../shared/scenarios.js"
 import { build, fixSuite } from "./steps.js"
 
 /** Package 0: the e2e scenarios, written red. */

package/src/workflows/{planning.ts → feature/planning.ts}

@@ -7,14 +7,13 @@ import {
   requireThreadsClosed,
   requireProgress,
   scope,
-} from "../flows/index.js"
+} from "../../flows/index.js"
+import { ARCHITECTURE, REQUIREMENTS } from "../shared/steps.js"
 import {
   answerProductQuestions,
   answerTechnicalQuestions,
-  ARCHITECTURE,
   author,
   decompose,
-  REQUIREMENTS,
   triage,
 } from "./steps.js"
 

package/src/workflows/{review.test.ts → feature/review.test.ts}

@@ -1,8 +1,13 @@
 import { afterEach, describe, expect, it } from "vitest"
-import { installContext, type Change, type JudgeAnswer, type StepRequest } from "../flows/index.js"
-import { fixQualityFindings, review, type ReviewOutcome } from "./review.js"
-import * as bundled from "./index.js"
-import { fixtureContext } from "./text.fixture.js"
+import {
+  installContext,
+  type Change,
+  type JudgeAnswer,
+  type StepRequest,
+} from "../../flows/index.js"
+import { review, type ReviewOutcome } from "./review.js"
+import * as bundled from "../index.js"
+import { fixtureContext } from "../shared/text.fixture.js"
 
 afterEach(() => installContext(undefined))
 
@@ -378,43 +383,3 @@ describe("scenario wording in review's fix turns", () => {
     expect(log.slice(-2)).toEqual(["fix", "scenario-wording"])
   })
 })
-
-describe("the quality fix loop", () => {
-  it("a fix that resolves QUALITY.md and rewrites a scenario ends after the wording gate", async () => {
-    const QUALITY = ".gtd/QUALITY.md"
-    const log: string[] = []
-    const files = new Map([
-      [QUALITY, "- finding"],
-      ["e2e/a.feature", "Given a"],
-    ])
-    let last: readonly Change[] = []
-    installContext(
-      fixtureContext(
-        {},
-        {
-          step: (request: StepRequest) => {
-            if (request.kind === "restart") return Promise.resolve()
-            log.push(request.name)
-            last = []
-            if (request.name === "fix.quality.fixing") {
-              files.delete(QUALITY)
-              files.set("e2e/a.feature", "Given b")
-              last = [{ path: QUALITY, status: "deleted", before: "- finding", after: undefined }]
-            }
-            return Promise.resolve()
-          },
-          pushScope: () => undefined,
-          popScope: () => undefined,
-          read: (path) => files.get(path),
-          changes: () => last,
-          matches: (path, pattern) => path === pattern,
-          head: () => "h2",
-          start: () => "h0",
-        },
-      ),
-    )
-    const frozen = { at: "h1", texts: { "e2e/a.feature": "Given a" } }
-    expect(await fixQualityFindings({ rounds: 0 }, frozen)).toBe(true)
-    expect(log).toEqual(["fix.quality.fixing", "scenario-wording"])
-  })
-})

package/src/workflows/feature/review.ts

@@ -0,0 +1,106 @@
+import { answered, judge, numeric, vars, type JudgeQuestion } from "../../flows/index.js"
+import type { ReviewNote } from "../../steering/index.js"
+import * as kit from "../../workflow-kit/index.js"
+import { healthy, type EscalationCount } from "../shared/health.js"
+import { guarded, type FrozenScenarios } from "../shared/scenarios.js"
+import {
+  awaitReview,
+  fixCheck,
+  fixRisks,
+  REQUIREMENTS,
+  REVIEW,
+  reviewing,
+  reviewMissing,
+} from "../shared/steps.js"
+import { closeReview, tail } from "../shared/tail.js"
+import * as t from "../shared/text.js"
+import type { BuiltPlan } from "./packages.js"
+import { answerReviewQuestions, collecting, fixNits } from "./steps.js"
+
+export type { ReviewOutcome } from "../../workflow-kit/index.js"
+
+const VERDICTS: readonly kit.Verdict[] = ["edit", "question", "nit", "praise"]
+
+/** One four-way choice per note the human added to `.gtd/REVIEW.md`. */
+const verdictQuestion = (note: ReviewNote): JudgeQuestion => ({
+  id: note.id,
+  primitive: "choice",
+  instructions: `Classify the human's note on review item "${note.anchor}" (in .gtd/REVIEW.md). Its evidence holds the anchor, the reviewer's text and the human's text.`,
+  criteria:
+    "edit: a request to change behaviour, design or scope — anything needing a plan, or any note you are unsure about. question: asks something and wants an answer, with no change requested. nit: a small, local, unambiguous fix (naming, typo, formatting, comment wording) needing no re-plan. praise: an approving remark with nothing to do.",
+})
+
+/**
+ * One judge rest, one verdict per note. Dismissing a note is the risky
+ * direction, so only a confident non-`edit` verdict on uncut evidence counts;
+ * a cut, unanswered or below-floor note is an `edit`, and a blank floor makes
+ * every note one.
+ */
+const triage = async (notes: readonly ReviewNote[]): Promise<ReadonlyMap<string, kit.Verdict>> => {
+  const { answers, truncated } = await judge("review.triage", {
+    questions: notes.map(verdictQuestion),
+    evidence: Object.fromEntries(
+      notes.map((n) => [
+        n.id,
+        `Anchor: ${n.anchor}\nReviewer's text: ${n.before}\nHuman's text: ${n.text}`,
+      ]),
+    ),
+    message: t.buildReviewTriageMessage(),
+    label: "Judging each note",
+  })
+  const minP = numeric(vars.reviewNoteActionable, Infinity)
+  return new Map(
+    notes.map((n): [string, kit.Verdict] => {
+      const verdict = VERDICTS.find((v) => v !== "edit" && answered(answers[n.id], v, minP))
+      return [n.id, truncated.includes(n.id) || verdict === undefined ? "edit" : verdict]
+    }),
+  )
+}
+
+const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
+
+/**
+ * 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
+ * another planning lap, questions are answered in place, nits fixed in one
+ * batch, praise dropped.
+ */
+export const review = (
+  base: string,
+  escalations: EscalationCount = { rounds: 0 },
+  frozen?: FrozenScenarios,
+): Promise<kit.ReviewOutcome> =>
+  kit.review(base, {
+    file: REVIEW,
+    feedback: REQUIREMENTS,
+    isCode,
+    reviewing,
+    fixRisks: (risks) => guarded(frozen, () => fixRisks(risks), "review")(),
+    keepGreen: () => healthy(guarded(frozen, fixCheck, "review"), { escalations }),
+    awaitReview,
+    reviewMissing,
+    collecting,
+    triage,
+    answerQuestions: answerReviewQuestions,
+    fixNits: (notes) => guarded(frozen, () => fixNits(notes), "review")(),
+    close: closeReview,
+    captures: {
+      edits: t.reviewEditsCapture,
+      notes: t.reviewNotesCapture,
+      editNotes: t.reviewEditNotesCapture,
+    },
+    refusals: {
+      deleted:
+        "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note (or edit code) to request changes.",
+      unmatched:
+        "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing",
+    },
+  })
+
+/** The build tail: fix (when entered red), keep green, the quality lap, then human review since `base`. */
+export const buildTail = (
+  fixFirst: boolean,
+  base: string,
+  built?: BuiltPlan,
+): Promise<kit.ReviewOutcome> =>
+  tail(fixFirst, (escalations, frozen) => review(base, escalations, frozen), built)

package/src/workflows/feature/steps.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest"
+import type { StepRequest } from "../../flows/index.js"
+import { captureStep } from "../shared/text.fixture.js"
+import * as steps from "./steps.js"
+
+const capture = (
+  fn: () => Promise<void>,
+  scope: string,
+  skills?: Readonly<Record<string, readonly string[]>>,
+): Promise<StepRequest> => captureStep(fn, { scope, ...(skills !== undefined ? { skills } : {}) })
+
+const agentPrompt = (request: StepRequest): string => {
+  if (request.kind !== "agent") throw new Error(`expected an agent step, got ${request.kind}`)
+  return request.prompt
+}
+
+describe("the feature workflow's own steps declare skills — a step's rendered prompt carries its bundled skills.ts preamble", () => {
+  it("triage carries design.triage's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.triage("base"), "design"))
+    expect(prompt).toContain("spec-driven-development, planning-and-task-breakdown")
+  })
+
+  it("author carries architecture.author's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.author(), "architecture"))
+    expect(prompt).toContain("api-and-interface-design, documentation-and-adrs, ponytail")
+  })
+
+  it("decompose carries architecture.decompose's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.decompose(), "architecture"))
+    expect(prompt).toContain("incremental-implementation, planning-and-task-breakdown")
+  })
+
+  it("build carries packages.item.building's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.build("pkg"), "packages.item"))
+    expect(prompt).toContain("test-driven-development, incremental-implementation")
+  })
+
+  it("fixSuite carries packages.item.fix.suite's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.fixSuite(), "packages.item"))
+    expect(prompt).toContain("debugging-and-error-recovery")
+  })
+
+  it("collecting carries build.review.collecting's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.collecting("capture"), "build"))
+    expect(prompt).toContain("code-review-and-quality")
+  })
+
+  it("answerReviewQuestions answers inline in .gtd/REVIEW.md as the reviewer, with its bundled skills", async () => {
+    const request = await capture(
+      () =>
+        steps.answerReviewQuestions([{ id: "note-1", anchor: "calc ./a.ts#1-1", text: "why?" }]),
+      "build",
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.answer-review-questions")
+    expect(request.options).toMatchObject({
+      file: ".gtd/REVIEW.md",
+      mode: "review",
+    })
+    expect(request.prompt).toContain("code-review-and-quality")
+    expect(request.prompt).toContain("note-1 — calc ./a.ts#1-1")
+    expect(request.prompt).toContain("`A: ` line")
+    expect(request.prompt).toContain("gtd check review .gtd/REVIEW.md")
+  })
+
+  it("fixNits fixes every nit in one turn and leaves .gtd/REVIEW.md alone", async () => {
+    const request = await capture(
+      () =>
+        steps.fixNits([
+          { id: "note-1", anchor: "calc ./a.ts#1-1", text: "typo" },
+          { id: "note-2", anchor: "calc ./a.ts#2-2", text: "semicolon" },
+        ]),
+      "build",
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.fix.nits.fixing")
+    expect(request.prompt).toContain("incremental-implementation, code-simplification")
+    expect(request.prompt).toContain("typo")
+    expect(request.prompt).toContain("semicolon")
+    expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
+  })
+})

package/src/workflows/feature/steps.ts

@@ -0,0 +1,92 @@
+import { human } from "../../flows/index.js"
+import * as t from "../shared/text.js"
+import { ARCHITECTURE, coder, FEEDBACK, planner, REQUIREMENTS, REVIEW } from "../shared/steps.js"
+
+/** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
+export const triage = (base: string): Promise<void> =>
+  t.agentWithSkills("triage", t.designTriagePrompt(base), {
+    label: "Triaging the change",
+    file: REQUIREMENTS,
+    mode: "qa",
+    model: planner(),
+    system: t.designSystem(),
+  })
+
+export const author = (): Promise<void> =>
+  t.agentWithSkills("author", t.architectureAuthorPrompt(), {
+    label: "Refining the technical plan",
+    file: ARCHITECTURE,
+    mode: "qa",
+    model: planner(),
+    system: t.architectSystem(),
+  })
+
+export const decompose = (): Promise<void> =>
+  t.agentWithSkills("decompose.decomposing", 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,
+  })
+
+export const build = (pkg: string): Promise<void> =>
+  t.agentWithSkills("building", t.packagesItemBuildingPrompt(pkg), {
+    label: "Building",
+    model: coder(),
+    system: t.builderSystem(),
+  })
+
+export const fixSuite = (): Promise<void> =>
+  t.agentWithSkills("fix.suite.fixing", t.packagesItemFixSuitePrompt(), {
+    label: "Fixing the check",
+    file: FEEDBACK,
+    model: coder(),
+    system: t.builderSystem(),
+  })
+
+/** Answer every `question` note inline in `.gtd/REVIEW.md`. */
+export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills("review.answer-review-questions", t.buildReviewAnswerQuestionsPrompt(notes), {
+    label: "Answering your questions",
+    file: REVIEW,
+    mode: "review",
+    model: planner(),
+    system: t.reviewerSystem(),
+  })
+
+/** Fix every `nit` note in one turn. */
+export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills("review.fix.nits.fixing", t.buildReviewFixNitsPrompt(notes), {
+    label: "Fixing your nits",
+    file: REVIEW,
+    model: planner(),
+    system: t.reviewerSystem(),
+  })
+
+/** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
+export const collecting = (capture: string): Promise<void> =>
+  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture), {
+    label: "Collecting your feedback",
+    file: REQUIREMENTS,
+    mode: "qa",
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })

package/src/workflows/fix/fix.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext, type StepRequest } from "../../flows/index.js"
+import { fixtureContext } from "../shared/text.fixture.js"
+import { fixFlow } from "./fix.js"
+
+afterEach(() => installContext(undefined))
+
+const REVIEW = ".gtd/REVIEW.md"
+const ORIG = ".gtd/REVIEW.orig.md"
+
+const reviewDoc = (...notes: string[]): string =>
+  [
+    "# Review: abc1234",
+    "",
+    "<!-- base: 0000000 -->",
+    "",
+    "## calc",
+    ...notes.flatMap((note, i) => [`- [ ] ./src/calc.ts#${i + 1}`, note]),
+    "",
+  ].join("\n")
+
+class Stop extends Error {}
+
+/** Run `fix` over `files` until its third step; returns the steps it asked for. */
+const drive = async (files: Readonly<Record<string, string>>): Promise<StepRequest[]> => {
+  const steps: StepRequest[] = []
+  installContext(
+    fixtureContext(
+      {},
+      {
+        step: (request: StepRequest) => {
+          steps.push(request)
+          if (steps.length >= 3) throw new Stop()
+          return Promise.resolve()
+        },
+        refuse: (message: string): never => {
+          throw new Error(message)
+        },
+        pushScope: () => undefined,
+        popScope: () => undefined,
+        // Closing removes both review files, as the real tree would show.
+        read: (path) =>
+          steps.some((s) => "name" in s && s.name === "closing") ? undefined : files[path],
+        head: () => "c1",
+        start: () => "c0",
+      },
+    ),
+  )
+  await fixFlow().catch((e: unknown) => {
+    if (!(e instanceof Stop)) throw e
+  })
+  return steps
+}
+
+describe("the fix workflow", () => {
+  it("with no handed-off review, repairs a red baseline from fix-precheck", async () => {
+    const [first] = await drive({})
+    expect(first).toMatchObject({ kind: "run", name: "fix-precheck" })
+  })
+
+  it("fixes a handed-off review's notes and risks in one turn, then removes both review files", async () => {
+    const steps = await drive({
+      [REVIEW]: reviewDoc("add — rename it to sum", "Risk: drops the carry"),
+      [ORIG]: reviewDoc("add", "Risk: drops the carry"),
+    })
+    const [fixing, closing] = steps
+    if (fixing?.kind !== "agent" || closing?.kind !== "run") throw new Error("unexpected steps")
+    expect(fixing.name).toBe("fixing")
+    expect(fixing.prompt).toContain("rename it to sum")
+    expect(fixing.prompt).toContain("Risk: drops the carry")
+    expect(closing.name).toBe("closing")
+    expect(closing.body).toContain(REVIEW)
+    expect(closing.body).toContain(ORIG)
+  })
+
+  it("after the notes, checks health before the suite is trusted", async () => {
+    const steps = await drive({ [REVIEW]: reviewDoc("add"), [ORIG]: reviewDoc("add") })
+    expect(steps.map((s) => [s.kind, "name" in s ? s.name : undefined])).toEqual([
+      ["agent", "fixing"],
+      ["run", "closing"],
+      ["run", "health.check"],
+    ])
+  })
+
+  it("refuses a reviewer's copy left with no review", async () => {
+    await expect(drive({ [ORIG]: reviewDoc("add") })).rejects.toThrow(/has no \.gtd\/REVIEW\.md/)
+  })
+
+  it("refuses a review with no reviewer's copy, so no note is deleted unread", async () => {
+    await expect(drive({ [REVIEW]: reviewDoc("Risk: drops the carry") })).rejects.toThrow(
+      /not handed off/,
+    )
+  })
+})

package/src/workflows/fix/fix.ts

@@ -0,0 +1,52 @@
+import { read, refuse, removeScript, run, scope, start } from "../../flows/index.js"
+import { reviewNotes, reviewRisks } from "../../steering/index.js"
+import { baseline } from "../shared/health.js"
+import { shipped } from "../shared/options.js"
+import { coder, REVIEW } from "../shared/steps.js"
+import { handOffTail, REVIEW_ORIG } from "../shared/tail.js"
+import * as t from "../shared/text.js"
+
+/**
+ * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every
+ * risk its reviewer marked, in one turn; the review files go once it is done.
+ */
+export const fixReviewNotes = (): Promise<void> =>
+  scope("notes", async () => {
+    const record = read(REVIEW) ?? ""
+    const orig = read(REVIEW_ORIG)
+    // Without the reviewer's copy no note can be told from the review's own text,
+    // and closing would delete notes never read — also keeps a stray review out.
+    if (orig === undefined) {
+      return refuse(
+        `gtd: ${REVIEW} has no ${REVIEW_ORIG}, so it was not handed off by a review — remove it, or restore ${REVIEW_ORIG}.`,
+      )
+    }
+    const notes = reviewNotes(orig, record)
+    await t.agentWithSkills("fixing", t.fixReviewNotesPrompt(notes, reviewRisks(record)), {
+      label: "Fixing your review notes",
+      file: REVIEW,
+      model: coder(),
+      system: t.finisherSystem(),
+      // Praise and questions are answered without an edit; the hand-off review that follows catches an unaddressed note.
+      allowEmpty: true,
+    })
+    await run("closing", removeScript([REVIEW, REVIEW_ORIG]), { label: "Closing the review" })
+  })
+
+/**
+ * Fix what a review handed on, else repair a red baseline — then the
+ * hand-off review of the result. A note there is handed to the next `fix`.
+ */
+export const fixFlow = async (): Promise<void> => {
+  if (read(REVIEW) !== undefined) {
+    await fixReviewNotes()
+    return handOffTail(false, start())
+  }
+  if (read(REVIEW_ORIG) !== undefined) {
+    return refuse(`gtd: ${REVIEW_ORIG} has no ${REVIEW} — remove it, or restore ${REVIEW}.`)
+  }
+  if (await baseline("fix-precheck")) return
+  await handOffTail(true, start())
+}
+
+export const fix = shipped(fixFlow, { fix: {} })