@pmelab/gtd 15.8.0 → 15.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "15.8.0",
+  "version": "15.10.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/workflows/prose.ts

@@ -65,10 +65,11 @@ judgement call: the grouping is already decided.`
 
 export const reviewerPersona = `You are the independent reviewing mind in gtd's build pipeline —
 deliberately separate from whoever wrote the code, with no attachment
-to it. Two turns: write a structured review document grouping a diff
-into chunks; later, classify a round of the human's feedback as
-actionable or just approving, never fixing anything yourself. You judge
-and classify; you never build.`
+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.
+Beyond that you never fix or build anything yourself.`
 
 export const specReviewerPersona = `You are the adversarial spec-conformance checker in gtd's build
 pipeline, checking one freshly-built package against its spec. Verify

package/src/workflows/review.test.ts

@@ -0,0 +1,247 @@
+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 { fixtureContext } from "./text.fixture.js"
+
+afterEach(() => installContext(undefined))
+
+const REVIEW = ".gtd/REVIEW.md"
+const REQUIREMENTS = ".gtd/REQUIREMENTS.md"
+
+class Stop extends Error {}
+
+const doc = (notes: readonly string[]): string =>
+  [
+    "# Review: abc1234",
+    "",
+    "<!-- base: 0000000000000000000000000000000000000000 -->",
+    "",
+    "## calc",
+    ...notes.flatMap((note, i) => [`- [ ] ./src/calc.ts#${i + 1}-${i + 1}`, note]),
+    "",
+  ].join("\n")
+
+const BEFORE = doc(["add", "sub", "mul"])
+
+interface Drive {
+  readonly notes: readonly string[]
+  readonly answers?: Readonly<Record<string, JudgeAnswer>>
+  readonly truncated?: readonly string[]
+  readonly vars?: Readonly<Record<string, string>>
+  /** The REVIEW.md the human leaves; defaults to `notes` laid over the baseline. */
+  readonly after?: string
+}
+
+interface Run {
+  readonly log: string[]
+  readonly prompts: Map<string, string>
+  readonly result: ReviewOutcome | "stopped"
+  readonly judged: readonly string[]
+}
+
+/** Run `review` against a scripted context; a second pass at the gate or a fresh review stops the run. */
+const drive = async (d: Drive): Promise<Run> => {
+  const log: string[] = []
+  const prompts = new Map<string, string>()
+  const judged: string[] = []
+  const files = new Map<string, string>([[REVIEW, d.after ?? doc(d.notes)]])
+  let steps = 0
+  let nitsFixed = false
+  let awaits = 0
+  let reviews = 0
+  const effects: Record<string, () => void> = {
+    "review.reviewing": () => {
+      if (++reviews > 1) throw new Stop()
+    },
+    "review.await-review": () => {
+      if (++awaits > 1) throw new Stop()
+    },
+    "review.closing": () => void files.delete(REVIEW),
+    "review.collecting": () => void files.set(REQUIREMENTS, "## Concern"),
+    "review.fix-nits": () => {
+      nitsFixed = true
+    },
+  }
+  const context = fixtureContext(
+    { vars: d.vars ?? {} },
+    {
+      step: (request: StepRequest) => {
+        steps++
+        if (request.kind === "restart") return Promise.resolve()
+        log.push(request.name)
+        if (request.kind === "agent") prompts.set(request.name, request.prompt)
+        effects[request.name]?.()
+        if (request.kind !== "judge") return Promise.resolve()
+        judged.push(...request.questions.map((q) => q.id))
+        return Promise.resolve({ answers: d.answers ?? {}, truncated: d.truncated ?? [] })
+      },
+      refuse: (message: string): never => {
+        throw new Error(message)
+      },
+      pushScope: () => undefined,
+      popScope: () => undefined,
+      read: (path) => files.get(path),
+      changesSince: (): readonly Change[] => [
+        { path: REVIEW, status: "modified", before: BEFORE, after: files.get(REVIEW) },
+        ...(nitsFixed
+          ? [{ path: "src/calc.ts", status: "modified" as const, before: "a", after: "b" }]
+          : []),
+      ],
+      head: () => `c${steps}`,
+      start: () => "c0",
+    },
+  )
+  installContext(context)
+  let result: ReviewOutcome | "stopped"
+  try {
+    result = await review("base")
+  } catch (error) {
+    if (!(error instanceof Stop)) throw error
+    result = "stopped"
+  }
+  return { log, prompts, result, judged }
+}
+
+const verdict = (answer: string, p = 0.9): JudgeAnswer => ({ answer, p })
+
+describe("review verdict routing", () => {
+  const notes = ["add — typo", "sub", "mul"]
+
+  it("judges one note per added note, as one judge rest", async () => {
+    const run = await drive({ notes: ["add — a", "sub — b", "mul"] })
+    expect(run.judged).toEqual(["note-1", "note-2"])
+    expect(run.log.filter((n) => n === "review.triage")).toHaveLength(1)
+  })
+
+  it("an unanswered note counts as edit", async () => {
+    const run = await drive({ notes: ["add — typo", "sub", "mul"], answers: {} })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.closing",
+      "review.collecting",
+    ])
+    expect(run.result).toMatchObject({ verdict: "feedback" })
+  })
+
+  it("a cut note counts as edit despite a confident praise", async () => {
+    const run = await drive({
+      notes,
+      answers: { "note-1": verdict("praise", 0.99) },
+      truncated: ["note-1"],
+    })
+    expect(run.log).toContain("review.collecting")
+  })
+
+  it("a verdict below the reviewNoteActionable floor counts as edit", async () => {
+    const run = await drive({ notes, answers: { "note-1": verdict("praise", 0.5) } })
+    expect(run.log).toContain("review.collecting")
+  })
+
+  it("a blank floor makes every note an edit", async () => {
+    const run = await drive({
+      notes,
+      answers: { "note-1": verdict("praise", 1) },
+      vars: { reviewNoteActionable: "" },
+    })
+    expect(run.log).toContain("review.collecting")
+  })
+
+  it("only praise closes and signs off with no agent turn", async () => {
+    const run = await drive({ notes, answers: { "note-1": verdict("praise") } })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.closing",
+    ])
+    expect(run.result).toEqual({ verdict: "signoff" })
+  })
+
+  it("questions only are answered, then the gate again, never closed", async () => {
+    const run = await drive({
+      notes: ["add — why?", "sub — and here?", "mul"],
+      answers: { "note-1": verdict("question"), "note-2": verdict("question") },
+    })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.answer-review-questions",
+      "review.await-review",
+    ])
+    expect(run.prompts.get("review.answer-review-questions")).toContain("note-2")
+    expect(run.result).toBe("stopped")
+  })
+
+  it("nits without edits are fixed, kept green, closed, then re-reviewed with the answers carried", async () => {
+    const run = await drive({
+      notes: ["add — why?", "sub — typo", "mul"],
+      answers: { "note-1": verdict("question"), "note-2": verdict("nit") },
+    })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.answer-review-questions",
+      "review.fix-nits",
+      "health.check",
+      "review.closing",
+      "review.reviewing",
+    ])
+    expect(run.prompts.get("review.fix-nits")).not.toContain("why?")
+    expect(run.prompts.get("review.reviewing")).toContain("Carry-over: commit `c4`")
+    expect(run.result).toBe("stopped")
+  })
+
+  it("nits alone carry nothing over", async () => {
+    const run = await drive({
+      notes: ["add — typo", "sub", "mul"],
+      answers: { "note-1": verdict("nit") },
+    })
+    expect(run.prompts.get("review.reviewing")).not.toContain("Carry-over")
+  })
+
+  it("edits run after questions and nits, and the capture names only the edits and the answering commit", async () => {
+    const run = await drive({
+      notes: ["add — rename it", "sub — why?", "mul — typo"],
+      answers: { "note-2": verdict("question"), "note-3": verdict("nit") },
+    })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.answer-review-questions",
+      "review.fix-nits",
+      "health.check",
+      "review.closing",
+      "review.collecting",
+    ])
+    const capture = run.prompts.get("review.collecting") ?? ""
+    expect(capture).toContain("note-1")
+    expect(capture).toContain("rename it")
+    expect(capture).not.toContain("note-2 —")
+    expect(capture).not.toContain("note-3 —")
+    expect(capture).toContain("commit c4 answered")
+  })
+
+  it("a noted round with no extractable note collects as one edit, without judging", async () => {
+    const run = await drive({ notes: [], after: BEFORE + "\nSome stray prose.\n" })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.closing",
+      "review.collecting",
+    ])
+    expect(run.prompts.get("review.collecting")).toContain("The human's notes are in")
+  })
+
+  it("never counts a nit fix as a hand-edit", async () => {
+    const run = await drive({
+      notes: ["add — rename it", "sub — typo", "mul"],
+      answers: { "note-2": verdict("nit") },
+    })
+    expect(run.result).toMatchObject({ verdict: "feedback", edited: [] })
+  })
+})

package/src/workflows/review.ts

@@ -13,17 +13,18 @@ import {
   requireThreadsClosed,
   run,
   scope,
-  sectionBodies,
   vars,
   type Change,
   type JudgeQuestion,
 } from "../flows/index.js"
-import { stripCodeThreads } from "../steering/index.js"
+import { reviewNotes, stripCodeThreads, type ReviewNote } from "../steering/index.js"
 import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
 import {
+  answerReviewQuestions,
   awaitReview,
   collecting,
   fix,
+  fixNits,
   fixQuality,
   QUALITY,
   REQUIREMENTS,
@@ -70,36 +71,43 @@ export type ReviewOutcome =
       readonly edited: readonly Change[]
     }
 
-/** One noul per `## ` chunk of `.gtd/REVIEW.md`: is its note actionable? */
-const triageQuestions = (chunks: readonly string[]): JudgeQuestion[] =>
-  chunks.map((title, i) => ({
-    id: `chunk-${i + 1}`,
-    primitive: "noul",
-    instructions: `Is the note under review chunk "${title}" (in .gtd/REVIEW.md) actionable — anything beyond an approving remark with no code edit?`,
-    criteria:
-      "A concrete request, a question, a code comment, or a hand-edit under this chunk answers yes. No note, or a purely approving remark, answers no.",
-  }))
-
-/** A note-only round: judge whether any chunk of `review` asks for something. */
-const actionable = async (review: string): Promise<boolean> => {
-  const found = sectionBodies(review)
-  const chunks = found.map((section) => section.title)
-  const evidence = Object.fromEntries(found.map(({ body }, i) => [`chunk-${i + 1}`, body]))
+type Verdict = "edit" | "question" | "nit" | "praise"
+
+const VERDICTS: readonly 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, Verdict>> => {
   const { answers, truncated } = await judge("review.triage", {
-    questions: triageQuestions(chunks),
-    evidence,
+    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 feedback actionability",
+    label: "Judging each note",
   })
-  // Dismissing a note is the risky direction, so only a confident "no" on
-  // uncut evidence dismisses a chunk; a blank floor dismisses nothing.
   const minP = numeric(vars.reviewNoteActionable, Infinity)
-  return (
-    chunks.length === 0 ||
-    chunks.some((_, i) => {
-      const id = `chunk-${i + 1}`
-      return truncated.includes(id) || !answered(answers[id], "no", minP)
-    })
+  return new Map(
+    notes.map((n): [string, 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]
+    }),
   )
 }
 
@@ -140,8 +148,8 @@ const notedSince = (commit: string): boolean =>
  * commit of the last `review.collecting` turn, `"missing"` when the round
  * left no review, or `undefined` when no such turn ran.
  */
-const converse = async (base: string): Promise<string | undefined> => {
-  let collectedAt: string | undefined
+const converse = async (base: string, collectedBefore?: string): Promise<string | undefined> => {
+  let collectedAt = collectedBefore
   for (;;) {
     await awaitReview(base)
     if (changes(REVIEW).some((c) => c.status === "deleted")) {
@@ -180,41 +188,111 @@ const settledAfter = (collectedAt: string | undefined): { folded: boolean; settl
     !notedSince(collectedAt),
 })
 
+/** What `finish` hands back to `review`: an outcome, or another lap at the gate. */
+type Finish =
+  | ReviewOutcome
+  | { readonly next: "await"; readonly reviewed: string }
+  | { readonly next: "rereview"; readonly carry: string | undefined }
+
+/** What a round's routing needs from `finish`: its closing step and the ways it ends. */
+interface Round {
+  readonly round: string
+  readonly escalations: EscalationCount
+  readonly close: () => Promise<void>
+  readonly outcome: (verdict: "signoff" | "feedback") => ReviewOutcome
+  readonly unfolded: () => Promise<Finish>
+}
+
+/** Judge every note, then run each verdict's route: answers, then nit fixes, then the edits' lap. */
+const routeNotes = async (notes: readonly ReviewNote[], r: Round): Promise<Finish> => {
+  const verdicts = await triage(notes)
+  const of = (v: Verdict): ReviewNote[] => notes.filter((n) => verdicts.get(n.id) === v)
+  const [edits, questions, nits] = [of("edit"), of("question"), of("nit")]
+  if (edits.length + questions.length + nits.length === 0) return r.unfolded()
+
+  let answeredAt: string | undefined
+  if (questions.length > 0) {
+    await answerReviewQuestions(questions)
+    answeredAt = head()
+  }
+  if (nits.length > 0) {
+    await fixNits(nits)
+    await healthy(fix, { escalations: r.escalations })
+  }
+  if (edits.length > 0) {
+    await r.close()
+    return r.outcome(await collect(t.reviewEditNotesCapture(r.round, edits, answeredAt)))
+  }
+  if (nits.length > 0) {
+    await r.close()
+    return { next: "rereview", carry: answeredAt }
+  }
+  return { next: "await", reviewed: answeredAt! }
+}
+
 const finish = async (
   reviewed: string,
   collectedAt: string | undefined,
-): Promise<ReviewOutcome> => {
+  escalations: EscalationCount,
+): Promise<Finish> => {
+  // Everything the human did is read before any agent turn runs, so a nit fix
+  // is never counted as a hand-edit.
   const round = head()
   const since = changesSince(reviewed)
   const edited = since.filter(isCodeEdit)
+  const baselineText = since.get(REVIEW)?.before ?? ""
   const record = read(REVIEW) ?? ""
   const { folded, settled } = afterCollect(collectedAt)
   // The review gate clears every tick before its commit, so a changed
   // REVIEW.md is a note, never a tick.
   const noted = since.some((c) => c.path === REVIEW)
+  const close = (): Promise<void> =>
+    run("review.closing", removeScript([REVIEW]), { label: "Closing the review", base: round })
   const outcome = (verdict: "signoff" | "feedback"): ReviewOutcome =>
     verdict === "signoff" ? { verdict } : { verdict, base: round, restoreFrom: reviewed, edited }
-  await run("review.closing", removeScript([REVIEW]), {
-    label: "Closing the review",
-    base: round,
-  })
-  if (settled) return outcome(folded ? "feedback" : "signoff")
-  if (edited.length > 0) return outcome(await collect(t.reviewEditsCapture(round)))
-  if (!noted || !(await actionable(record))) return outcome(folded ? "feedback" : "signoff")
-  return outcome(await collect(t.reviewNotesCapture(round)))
+  const unfolded = async (): Promise<Finish> => {
+    await close()
+    return outcome(folded ? "feedback" : "signoff")
+  }
+
+  const collectWith = async (capture: string): Promise<Finish> => {
+    await close()
+    return outcome(await collect(capture))
+  }
+  if (settled || (edited.length === 0 && !noted)) return unfolded()
+  if (edited.length > 0) return collectWith(t.reviewEditsCapture(round))
+  const notes = reviewNotes(baselineText, record)
+  if (notes.length === 0) return collectWith(t.reviewNotesCapture(round))
+  return routeNotes(notes, { round, escalations, close, outcome, unfolded })
 }
 
 /**
  * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
- * reviews and signs off or comments, and a comment is classified into
- * requirements for another lap.
+ * 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 = async (base: string): Promise<ReviewOutcome> => {
+export const review = async (
+  base: string,
+  escalations: EscalationCount = { rounds: 0 },
+): Promise<ReviewOutcome> => {
+  let carry: string | undefined
   for (;;) {
-    await reviewing(base)
-    const reviewed = head()
-    const collectedAt = await converse(base)
-    if (collectedAt !== "missing") return finish(reviewed, collectedAt)
+    await reviewing(base, carry)
+    carry = undefined
+    let reviewed = head()
+    let collectedAt: string | undefined
+    for (;;) {
+      collectedAt = await converse(base, collectedAt)
+      if (collectedAt === "missing") break
+      const result = await finish(reviewed, collectedAt, escalations)
+      if (!("next" in result)) return result
+      if (result.next === "rereview") {
+        carry = result.carry
+        break
+      }
+      reviewed = result.reviewed
+    }
   }
 }
 
@@ -233,7 +311,7 @@ export const buildTail = (fixFirst: boolean, base: string): Promise<ReviewOutcom
       }
       const lap = lapped ? "clean" : await qualityLap()
       lapped = true
-      if (lap === "clean") return review(base)
+      if (lap === "clean") return review(base, escalations)
       if (await fixQualityFindings(escalations)) await healthy(fix, { escalations })
       else redFirst = true
     }

package/src/workflows/steps.test.ts

@@ -104,4 +104,43 @@ describe("the bundled workflow's steps declare skills", () => {
     expect(request.options.skills).toEqual([])
     expect(request.prompt).not.toContain("Load whatever's listed here")
   })
+
+  it("answerReviewQuestions answers inline in .gtd/REVIEW.md as the reviewer, with reviewSkills", async () => {
+    const request = await capture(() =>
+      steps.answerReviewQuestions([{ id: "note-1", anchor: "calc ./a.ts#1-1", text: "why?" }]),
+    )
+    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",
+      skills: ["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" },
+      ]),
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.fix-nits")
+    expect(request.options.skills).toEqual(["incremental-implementation", "code-simplification"])
+    expect(request.prompt).toContain("typo")
+    expect(request.prompt).toContain("semicolon")
+    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"))
+    if (bare.kind !== "agent" || carried.kind !== "agent") throw new Error("unreachable")
+    expect(bare.prompt).not.toContain("Carry-over")
+    expect(carried.prompt).toContain("Carry-over: commit `abc1234`")
+  })
 })

package/src/workflows/steps.ts

@@ -158,15 +158,47 @@ export const fixQuality = (): Promise<void> =>
     allowEmpty: true,
   })
 
-/** Write `.gtd/REVIEW.md` over everything since `base`. */
-export const reviewing = (base: string): Promise<void> =>
-  t.agentWithSkills("review.reviewing", vars.reviewSkills, t.buildReviewReviewingPrompt(base), {
-    label: "Reviewing",
+/** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
+export const reviewing = (base: string, carry?: string): Promise<void> =>
+  t.agentWithSkills(
+    "review.reviewing",
+    vars.reviewSkills,
+    t.buildReviewReviewingPrompt(base, carry),
+    {
+      label: "Reviewing",
+      file: REVIEW,
+      mode: "review",
+      model: planner(),
+      system: t.reviewerSystem(),
+      base,
+    },
+  )
+
+/** Answer every `question` note inline in `.gtd/REVIEW.md`. */
+export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills(
+    "review.answer-review-questions",
+    vars.reviewSkills,
+    t.buildReviewAnswerQuestionsPrompt(notes),
+    {
+      label: "Answering your questions",
+      file: REVIEW,
+      mode: "review",
+      model: planner(),
+      system: t.reviewerSystem(),
+    },
+  )
+
+/**
+ * Fix every `nit` note in one turn. Its name puts it in the `build.review`
+ * conversation, which has one identity — so it runs as the reviewer, not the coder.
+ */
+export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills("review.fix-nits", vars.reviewFixSkills, t.buildReviewFixNitsPrompt(notes), {
+    label: "Fixing your nits",
     file: REVIEW,
-    mode: "review",
     model: planner(),
     system: t.reviewerSystem(),
-    base,
   })
 
 export const awaitReview = (base: string): Promise<void> =>