@pmelab/gtd 42.0.0 → 44.0.0

package/src/workflows/review/review.ts

@@ -1,18 +1,46 @@
-import { start, type WorkflowBase } from "../../flows/index.js"
+import { read, refuse, removeScript, run, start, type WorkflowBase } from "../../flows/index.js"
+import { buildTail, reUnwind } from "../shared/review.js"
 import { gate } from "../shared/health.js"
 import { shipped } from "../shared/options.js"
-import { handOffTail, refusePendingHandOff } from "../shared/tail.js"
+import { coder, REQUIREMENTS } from "../shared/steps.js"
+import { refusePendingHandOff } from "../shared/tail.js"
 import * as t from "../shared/text.js"
 
+/** Build the concerns a review round collected into `.gtd/REQUIREMENTS.md`, then remove it. */
+const fixFeedback = async (): Promise<void> => {
+  await t.agentWithSkills("feedback.fixing", t.reviewFeedbackFixPrompt(), {
+    label: "Fixing your review feedback",
+    file: REQUIREMENTS,
+    model: coder(),
+    system: t.finisherSystem(),
+    // An earlier nit fix may already have built the concern.
+    allowEmpty: true,
+  })
+  await run("feedback.closing", removeScript([REQUIREMENTS]), { label: "Closing the feedback" })
+}
+
 /**
- * Pure review of everything since `reviewBase`: a green gate, the quality
- * lap, then the human review. A note ends the process with `.gtd/REVIEW.md`
- * left for `fix`; it never re-plans.
+ * The feature's review of everything since `reviewBase` — a green gate, the
+ * triaged quality lap, then the human review — with no design phase: a
+ * review that asks for changes is fixed in place and reviewed again, until
+ * sign-off.
  */
 export const reviewFlow = async (): Promise<void> => {
   refusePendingHandOff()
+  // A review's feedback is whatever sits in this file, so a leftover one would be built, then deleted.
+  if (read(REQUIREMENTS) !== undefined) {
+    refuse(`gtd: ${REQUIREMENTS} is left over — finish or remove it before a review.`)
+  }
   await gate("review-gate", t.reviewGateBlockedMessage())
-  await handOffTail(false, start())
+  const base = start()
+  // The gate just proved the tree green.
+  let outcome = await buildTail(base, { green: true })
+  while (outcome.verdict === "feedback") {
+    await reUnwind(outcome)
+    await fixFeedback()
+    // The human reviews the whole change again; the lenses only what the fix changed.
+    outcome = await buildTail(base, { lensBase: outcome.base })
+  }
 }
 
 export const review = shipped(

package/src/workflows/shared/__fixtures__/feature-collecting-prompt.txt

@@ -45,11 +45,12 @@ You are judging and classifying a round of review feedback.
 - This turn writes `.gtd/REQUIREMENTS.md` (the folded concerns) and
   replies inside `.gtd/REVIEW.md` (thread replies only; the file stays
   in the tree) — you classify, you do not build
-- Fold every concluded thread, ticked answer and hand-edit — and each
-  `edit` note the capture lists, no other note — into
-  `.gtd/REQUIREMENTS.md` and delete the folded threads from
-  `.gtd/REVIEW.md`; append one `- A:` reply to each thread
-  whose last entry is a `- H:` question
+- Fold every concluded thread and hand-edit — and each `edit` note
+  the capture lists, no other note — into `.gtd/REQUIREMENTS.md` and
+  delete the folded threads from `.gtd/REVIEW.md`; append one `- A:`
+  reply to each thread whose last entry is a `- H:` question
+- Never fold a note's ticked answer box the capture does not list: gtd
+  routes those itself
 - When the capture names an answering commit, carry each answered
   question into `.gtd/REQUIREMENTS.md`'s `## Answered Questions` as
   `### <the note>` plus its answer — the lap replaces `.gtd/REVIEW.md`

package/src/workflows/shared/access.test.ts

@@ -11,7 +11,6 @@ describe("the bundled workflow's access export", () => {
     expect(bundled).toEqual({
       design: { write: [] },
       "build.review": { write: [".gtd/REVIEW.md"] },
-      "build.review.defer": { write: [".gtd/TODO.md"] },
       "build.review.fix.nits": {},
       "build.review.fix.risks": {},
       "build.quality.correctness": { write: [] },
@@ -21,7 +20,6 @@ describe("the bundled workflow's access export", () => {
       "build.quality.conventions": { write: [] },
       "build.quality.spec-challenge": { write: [] },
       "refactor.build.review": { write: [".gtd/REVIEW.md"] },
-      "refactor.build.review.defer": { write: [".gtd/TODO.md"] },
       "refactor.build.quality.correctness": { write: [] },
       "refactor.build.quality.ponytail-review": { write: [] },
       "refactor.build.quality.conventions": { write: [] },
@@ -32,7 +30,6 @@ describe("the bundled workflow's access export", () => {
     expect(bundled).not.toHaveProperty(["refactor.build.review.fix.nits"])
     expect(bundled).not.toHaveProperty(["refactor.build.review.fix.risks"])
     expect(bundled["refactor.build.review"]).toEqual({ write: [".gtd/REVIEW.md"] })
-    expect(bundled["refactor.build.review.defer"]).toEqual({ write: [".gtd/TODO.md"] })
   })
 
   it("keys one lens scope per qualityReviews entry", () => {
@@ -54,17 +51,11 @@ describe("the bundled workflow's access export", () => {
       "refactor.build.quality.correctness",
       "refactor.build.quality.my-lens",
       "refactor.build.review",
-      "refactor.build.review.defer",
     ])
   })
 
-  it("keys only turn or script scopes", () => {
-    // `build.review.defer` is a script scope: no turn, so no skills entry.
-    const known = [
-      ...Object.keys(workflow.skills(defaults)),
-      "build.review.defer",
-      "refactor.build.review.defer",
-    ]
+  it("keys only turn scopes", () => {
+    const known = Object.keys(workflow.skills(defaults))
     for (const key of Object.keys(bundled)) expect(known).toContain(key)
   })
 })

package/src/workflows/shared/access.ts

@@ -13,12 +13,10 @@ export const access = (
 ): Readonly<Record<string, ScopeAccess>> => ({
   design: { write: [] },
   "build.review": { write: [".gtd/REVIEW.md"] },
-  "build.review.defer": { write: [".gtd/TODO.md"] },
   // `{}` reopens what `build.review` restricted: the fixes edit code.
   "build.review.fix.nits": {},
   "build.review.fix.risks": {},
   "refactor.build.review": { write: [".gtd/REVIEW.md"] },
-  "refactor.build.review.defer": { write: [".gtd/TODO.md"] },
   ...lensScopes("build.quality", lensesOf(vars.qualityReviews ?? ""), () => ({ write: [] })),
   ...lensScopes("refactor.build.quality", lensesOf(vars.refactorQualityReviews ?? ""), () => ({
     write: [],

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

@@ -9,7 +9,7 @@ import {
 } from "../../flows/index.js"
 import {
   buildTail,
-  review,
+  humanReview,
   reUnwind,
   severityOf,
   type BuildTailOptions,
@@ -17,8 +17,7 @@ import {
 } from "./review.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as bundled from "../index.js"
-import type * as featureEntry from "./index.js"
-import { fixtureContext } from "../shared/text.fixture.js"
+import { fixtureContext } from "./text.fixture.js"
 import { toRequest } from "../../judges/index.js"
 
 afterEach(() => installContext(undefined))
@@ -155,7 +154,7 @@ const drive = async (d: Drive): Promise<Run> => {
   installContext(context)
   let result: ReviewOutcome | "stopped"
   try {
-    result = await review("base", undefined, {
+    result = await humanReview("base", undefined, {
       ...d.options,
       ...(d.guarded ? { guard: () => void log.push("guard") } : {}),
     })
@@ -675,7 +674,7 @@ describe("severity routing", () => {
     expect(run.prompts.get("review.collecting")).toContain("(critical: forced by `!`)")
   })
 
-  it("a confident could edit defers and, alone, returns to the review gate", async () => {
+  it("a confident could edit is still re-planned, labelled could", async () => {
     const run = await drive({
       notes: ["add — quote", "sub", "mul"],
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
@@ -684,9 +683,10 @@ describe("severity routing", () => {
       "review.composing",
       "review.await-review",
       "review.triage",
-      "review.defer",
-      "review.await-review",
+      "review.closing",
+      "review.collecting",
     ])
+    expect(run.prompts.get("review.collecting")).toContain("(could)")
   })
 
   it("severity answers on a nit leave it a nit", async () => {
@@ -730,68 +730,19 @@ describe("severity routing", () => {
     expect(run.judged).toContain("note-1.security")
   })
 
-  it("the gate after a deferral accepts a clean land and lists the deferred notes", async () => {
-    const run = await drive({
-      notes: ["add — quote", "sub", "mul"],
-      answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
-    })
-    expect(run.gates).toEqual([true, true])
-    expect(run.gateMessages[1]).toContain("NOT acted on")
-    expect(run.gateMessages[1]).toContain("note-1")
-    expect(run.gateMessages[0]).not.toContain("NOT acted on")
-  })
-
   it("the first round's gate accepts a clean land", async () => {
     const run = await drive({ notes: ["add", "sub", "mul"] })
     expect(run.gates.length).toBeGreaterThan(0)
     expect(run.gates.every((g) => g)).toBe(true)
   })
 
-  it("a later gate still accepts a clean land after a deferral round with a nit", async () => {
-    const run = await drive({
-      notes: ["add — quote", "sub — typo", "mul"],
-      answers: {
-        "note-1": verdict("edit"),
-        ...sev("note-1", could),
-        "note-2": verdict("nit"),
-      },
-      reviewDocs: [undefined, doc(["add", "sub"])],
-    })
-    expect(run.log).toContain("review.defer")
-    expect(run.log.at(-1)).toBe("review.await-review")
-    expect(run.gates).toEqual([true, true])
-  })
-
-  it("a question and a could note in one round: the gate's base is the answering commit", async () => {
-    const run = await drive({
-      notes: ["add — why?", "sub — quote", "mul"],
-      answers: {
-        "note-1": verdict("question"),
-        "note-2": verdict("edit"),
-        ...sev("note-2", could),
-      },
-      passSecondGate: true,
-    })
-    expect(run.log).toEqual([
-      "review.composing",
-      "review.await-review",
-      "review.triage",
-      "review.answer-review-questions",
-      "review.defer",
-      "review.await-review",
-    ])
-    // c4 is the answering commit, not the defer commit (c5) or the round (c2)
-    expect(run.since.at(-1)).toBe("c4")
-  })
-
   it("a blank reviewSeverityMinP makes every confident could critical", async () => {
     const run = await drive({
       notes: ["add — quote", "sub", "mul"],
       answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
       vars: { reviewSeverityMinP: "" },
     })
-    expect(run.log).toContain("review.collecting")
-    expect(run.log).not.toContain("review.defer")
+    expect(run.prompts.get("review.collecting")).toContain("(critical: judge unsure)")
   })
 })
 
@@ -1023,11 +974,8 @@ describe("BuildTailOptions.lensBase", () => {
   })
 })
 
-// pins the public re-exports from the feature entry point and the published workflows entry
+// pins the public re-exports from the published workflows entry
 export type _PublicBuildTailOptions = [
-  featureEntry.BuildTailOptions,
-  featureEntry.FeedbackTarget,
-  featureEntry.ReviewRange,
   bundled.BuildTailOptions,
   bundled.FeedbackTarget,
   bundled.ReviewRange,

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

@@ -16,20 +16,22 @@ import {
 } from "../../flows/index.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
-import { guarded, healthy, type EscalationCount } from "../shared/health.js"
-import { NO_FINDINGS, type LensReport } from "../shared/lenses.js"
+import { guarded, healthy, type EscalationCount } from "./health.js"
+import { NO_FINDINGS, type LensReport } from "./lenses.js"
 import {
+  answerReviewQuestions,
   awaitReview,
+  collecting,
   fixCheck,
+  fixNits,
   fixRisks,
   QUALITY,
   REQUIREMENTS,
   REVIEW,
   reviewMissing,
-} from "../shared/steps.js"
-import { closeReview, isOptionalObject, tail, type TailOptions } from "../shared/tail.js"
-import * as t from "../shared/text.js"
-import { answerReviewQuestions, collecting, deferNotes, fixNits } from "./steps.js"
+} from "./steps.js"
+import { closeReview, isOptionalObject, tail, type TailOptions } from "./tail.js"
+import * as t from "./text.js"
 
 export type { ReviewOutcome } from "../../workflow-kit/index.js"
 
@@ -46,6 +48,12 @@ const verdictQuestion = (note: ReviewNote): JudgeQuestion => ({
 
 type Tier = "critical" | "should" | "could"
 
+const TIER_ORDER: Readonly<Record<Tier, number>> = { critical: 0, should: 1, could: 2 }
+
+/** Capture order: critical, should, could; within a tier one-way doors, then new concepts. */
+const captureKey = (s: Severity | undefined): number =>
+  s === undefined ? 2 : TIER_ORDER[s.tier] * 3 + s.rank
+
 const SEVERITY_ANSWERS: Readonly<Record<string, readonly string[]>> = {
   security: ["yes", "no"],
   reversibility: ["one-way", "two-way"],
@@ -60,10 +68,7 @@ interface Severity {
   readonly rank: 0 | 1 | 2
 }
 
-/**
- * Deferring is the risky direction: anything unanswered, unrecognised, cut or
- * below `minP` is `critical`, never `could`.
- */
+/** Anything unanswered, unrecognised, cut or below `minP` is `critical`, never `could`. */
 export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number): Severity => {
   const ans = (q: string) => judgment.answers[`${note.id}.${q}`]
   const a = (q: string): string | undefined => ans(q)?.answer
@@ -125,7 +130,7 @@ const severityQuestions = (note: ReviewNote): JudgeQuestion[] => [
  * nothing) plus four severity answers. 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`. Severity answers on a
- * non-`edit` note are ignored. A confident `could` edit becomes `defer`.
+ * non-`edit` note are ignored; on an `edit` they order the collecting turn.
  */
 const triage =
   (severities: Map<string, Severity>) =>
@@ -155,9 +160,8 @@ const triage =
           ? undefined
           : VERDICTS.find((v) => v !== "edit" && answered(answers[n.id], v, minP))
         if (verdict !== undefined && !truncated.includes(n.id)) return [n.id, verdict]
-        const severity = severityOf(n, judgment, severityMinP)
-        severities.set(n.id, severity)
-        return [n.id, severity.tier === "could" ? "defer" : "edit"]
+        severities.set(n.id, severityOf(n, judgment, severityMinP))
+        return [n.id, "edit"]
       }),
     )
   }
@@ -167,13 +171,15 @@ export const isCode = (path: string): boolean => path !== ".gtd" && !path.starts
 /**
  * gtd writes `.gtd/REVIEW.md` from the quality lap's `report` — no reviewer
  * turn — and removes what the fixer left in `.gtd/QUALITY.md`. A re-review
- * after fixed nits restores the doc as committed at `carry`, answers kept.
+ * after fixed nits restores the doc as committed at `carry`, answers kept;
+ * a fresh one leaves out the notes the human already answered.
  */
 const composing = (
   base: string,
   report: LensReport,
   carry?: string,
   nitFix?: string,
+  answered: ReadonlySet<string> = new Set(),
 ): Promise<void> =>
   run(
     "review.composing",
@@ -184,6 +190,7 @@ const composing = (
             ...report,
             weakened: kit.removedAssertions(changesSince(base)),
             nitFix,
+            answered,
           }),
           [QUALITY],
         )
@@ -193,11 +200,13 @@ const composing = (
 
 /**
  * The quality lap's notes reach a human over everything since `base`, who
- * 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,
+ * answers each one — fix as suggested, won't fix, or their own answer — and
+ * may comment. A fix joins the nit batch, a won't-fix is dropped, and an own
+ * answer or comment is judged: edits end the review as `feedback` for the
+ * caller to build, questions are answered in place, nits fixed in one batch,
  * praise dropped.
  */
-export const review = (
+export const humanReview = (
   base: string,
   escalations: EscalationCount = { rounds: 0 },
   options: Omit<BuildTailOptions, "fixFirst" | "green"> = {},
@@ -210,42 +219,26 @@ export const review = (
       "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing",
   }
   const severities = new Map<string, Severity>()
-  // Armed by a defer-only round to pick the next gate's message; a fresh
-  // review (`reviewing`) disarms it.
-  let deferred: readonly t.NoteInput[] = []
   // Set by a nit fix, so the fresh review that follows names its commit.
   let nitFix: string | undefined
+  // Every note the human answered in this review, left out of a fresh one.
+  const answered = new Set<string>()
   return kit.review(base, {
     file: REVIEW,
     feedback: feedback.file,
     isCode,
     reviewing: (b, carry) => {
-      deferred = []
       const fixedAt = nitFix
       nitFix = undefined
-      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt)
+      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt, answered)
     },
     fixRisks: guarded((notes) => fixRisks(notes, fixAccess, rules), guard),
     keepGreen: () => healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules }),
-    awaitReview: (b) => {
-      const notes = deferred
-      deferred = []
-      return notes.length > 0
-        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes))
-        : awaitReview(b)
-    },
+    awaitReview: (b) => awaitReview(b),
     reviewMissing,
     collecting: feedback.collecting,
     triage: triage(severities),
-    defer: (notes) => {
-      deferred = notes.map((n) => ({
-        id: n.id,
-        anchor: n.anchor,
-        text: n.text,
-        label: severities.get(n.id)!.reason,
-      }))
-      return deferNotes(deferred, head())
-    },
+    decided: (decisions) => decisions.forEach((d) => answered.add(d.anchor)),
     answerQuestions: answerReviewQuestions,
     fixNits: async (notes) => {
       await guarded((n: typeof notes) => fixNits(n, fixAccess, rules), guard)(notes)
@@ -259,14 +252,13 @@ export const review = (
         t.reviewEditNotesCapture(
           round,
           edits
-            .map((n, i) => ({ n, i, s: severities.get(n.id) }))
-            // critical before should, then one-way doors, then new concepts
-            .sort(
-              (x, y) =>
-                Number(x.s?.tier === "should") - Number(y.s?.tier === "should") ||
-                (x.s?.rank ?? 2) - (y.s?.rank ?? 2) ||
-                x.i - y.i,
-            )
+            .map((n, i) => ({
+              n,
+              i,
+              s: severities.get(n.id),
+              key: captureKey(severities.get(n.id)),
+            }))
+            .sort((x, y) => x.key - y.key || x.i - y.i)
             .map(({ n, s }) => ({
               id: n.id,
               anchor: n.anchor,
@@ -327,7 +319,7 @@ export function buildTail(
     )
   }
   const [base, form] = options
-  return tail((escalations, report) => review(base, escalations, { ...form, report }), {
+  return tail((escalations, report) => humanReview(base, escalations, { ...form, report }), {
     ...form,
     triage: true,
   })

package/src/workflows/shared/skills.test.ts

@@ -21,6 +21,7 @@ describe("the bundled workflow's skills export", () => {
         "build.review.fix.nits",
         "build.review.fix.risks",
         "notes",
+        "feedback",
         "refactor",
         "refactor.fix.suite",
         "refactor.health",
@@ -71,6 +72,7 @@ describe("the bundled workflow's skills export", () => {
       "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
       "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
       notes: ["incremental-implementation", "code-simplification"],
+      feedback: ["test-driven-development", "incremental-implementation"],
       refactor: ["ponytail"],
       "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
       "refactor.health": ["ponytail", "debugging-and-error-recovery"],

package/src/workflows/shared/skills.ts

@@ -22,6 +22,8 @@ export const skills = (
     design: ["spec-driven-development", "planning-and-task-breakdown"],
     // `fix`'s turn over the notes a review handed on.
     notes: ["incremental-implementation", "code-simplification"],
+    // `review`'s turn building what a review round collected.
+    feedback: ["test-driven-development", "incremental-implementation"],
     // The refactor's own turns load `ponytail`; `refactor.build.*` carry the `build.*` lists.
     ...build,
     ...Object.fromEntries(Object.entries(build).map(([name, list]) => [`refactor.${name}`, list])),

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
-import type { StepRequest } from "../../flows/index.js"
-import { captureStep } from "./text.fixture.js"
+import { installContext, type ScopeOptions, type StepRequest } from "../../flows/index.js"
+import { captureStep, fixtureContext } from "./text.fixture.js"
 import * as steps from "./steps.js"
 
 const capture = (
@@ -151,4 +151,66 @@ describe("the bundled workflow's model hints", () => {
     expect(await modelOf(() => steps.fixQuality())).toBe("base")
     expect(await modelOf(() => steps.fixCheck(), { env: { coderModel: "sonnet" } })).toBe("sonnet")
   })
+
+  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")
+  })
+
+  it("fixNits with access runs in a review.fix.nits scope, the step named fixing inside it", async () => {
+    const scopes: ScopeOptions[] = []
+    const steps_: StepRequest[] = []
+    const access = { write: ["src/a.ts", ".gtd/**"] }
+    installContext(
+      fixtureContext(
+        { scope: "refactor.build" },
+        {
+          step: (request) => {
+            steps_.push(request)
+            return Promise.resolve()
+          },
+          pushScope: (s) => void scopes.push(s),
+          popScope: () => undefined,
+          changesSince: () => [],
+        },
+      ),
+    )
+    try {
+      await steps.fixNits([], access)
+    } finally {
+      installContext(undefined)
+    }
+    expect(scopes).toEqual([{ name: "review.fix.nits", access }])
+    expect(steps_.map((r) => ("name" in r ? r.name : ""))).toEqual(["fixing"])
+  })
 })

package/src/workflows/shared/steps.ts

@@ -1,5 +1,5 @@
 import { changesSince, env, human, scope, type ScopeAccess } from "../../flows/index.js"
-import { removedAssertions } from "../../workflow-kit/index.js"
+import { removedAssertions, type CollectRound } from "../../workflow-kit/index.js"
 import * as t from "./text.js"
 
 // The bundled workflow's single steps. A step's name is relative to the
@@ -145,6 +145,45 @@ export const awaitReview = (
     acceptClean: true,
   })
 
+/** 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[],
+  access?: ScopeAccess,
+  rules?: string,
+): Promise<void> => {
+  const fixing = (name: string): Promise<void> =>
+    t.agentWithSkills(name, t.buildReviewFixNitsPrompt(notes, rules), {
+      label: "Fixing your nits",
+      file: REVIEW,
+      model: planner(),
+      system: t.reviewerSystem(),
+    })
+  return access === undefined
+    ? fixing("review.fix.nits.fixing")
+    : scope({ name: "review.fix.nits", access }, () => fixing("fixing"))
+}
+
+/** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
+export const collecting = (capture: string, round?: CollectRound): Promise<void> =>
+  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture, undefined, round), {
+    label: "Collecting your feedback",
+    file: REQUIREMENTS,
+    mode: "qa",
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })
+
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */
 export const reviewMissing = (round: string): Promise<void> =>
   human("review.review-missing", {

package/src/workflows/shared/tail.ts

@@ -190,7 +190,7 @@ const runTail = <T>(finish: Finish<T>, options: TailOptions): Promise<T> =>
   })
 
 /**
- * The review and fix workflows' human review since `base`: a sign-off closes
+ * The fix workflow's human review since `base`: a sign-off closes
  * `.gtd/REVIEW.md`; a note leaves it, with the reviewer's own version as
  * `REVIEW_ORIG`, for the next `fix` to read — never a re-plan.
  */
@@ -220,6 +220,6 @@ export const handOffReview = (
       "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix.",
   })
 
-/** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
+/** The tail the fix workflow runs: ends at the hand-off review since `base`. */
 export const handOffTail = (fixFirst: boolean, base: string, guard?: Guard): Promise<void> =>
   tail((escalations) => handOffReview(base, escalations, guard), { fixFirst, guard })