@pmelab/gtd 24.3.0 → 25.0.0

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

@@ -5,7 +5,8 @@ import {
   type JudgeAnswer,
   type StepRequest,
 } from "../../flows/index.js"
-import { review, type ReviewOutcome } from "./review.js"
+import { review, severityOf, type ReviewOutcome } from "./review.js"
+import type { ReviewNote } from "../../steering/index.js"
 import * as bundled from "../index.js"
 import { fixtureContext } from "../shared/text.fixture.js"
 
@@ -38,6 +39,8 @@ interface Drive {
   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)[]
+  /** Let the run pass the second gate, stopping at the first range read after it. */
+  readonly passSecondGate?: boolean
 }
 
 interface Run {
@@ -45,6 +48,11 @@ interface Run {
   readonly prompts: Map<string, string>
   readonly result: ReviewOutcome | "stopped"
   readonly judged: readonly string[]
+  /** `acceptClean` of each `review.await-review` gate, in order. */
+  readonly gates: readonly boolean[]
+  readonly gateMessages: readonly string[]
+  /** Every `changesSince` argument, in order. */
+  readonly since: readonly string[]
 }
 
 /** Run `review` against a scripted context; a second pass at the gate or a fresh review stops the run. */
@@ -52,6 +60,9 @@ const drive = async (d: Drive): Promise<Run> => {
   const log: string[] = []
   const prompts = new Map<string, string>()
   const judged: string[] = []
+  const gates: boolean[] = []
+  const gateMessages: string[] = []
+  const since: string[] = []
   const files = new Map<string, string>([[REVIEW, d.after ?? doc(d.notes)]])
   let steps = 0
   let nitsFixed = false
@@ -65,7 +76,7 @@ const drive = async (d: Drive): Promise<Run> => {
       if (written !== undefined) files.set(REVIEW, written)
     },
     "review.await-review": () => {
-      if (++awaits > 1) throw new Stop()
+      if (++awaits > (d.passSecondGate ? 2 : 1)) throw new Stop()
     },
     "review.closing": () => void files.delete(REVIEW),
     "review.collecting": () => void files.set(REQUIREMENTS, "## Concern"),
@@ -73,6 +84,14 @@ const drive = async (d: Drive): Promise<Run> => {
       nitsFixed = true
     },
   }
+  const record = (request: StepRequest): void => {
+    if (request.kind === "human" && request.name === "review.await-review") {
+      gates.push(request.options.acceptClean === true)
+      gateMessages.push(request.options.message ?? "")
+    }
+    if (request.kind === "agent") prompts.set(request.name, request.prompt)
+    if (request.kind === "judge") judged.push(...request.questions.map((q) => q.id))
+  }
   const context = fixtureContext(
     { vars: d.vars ?? {} },
     {
@@ -80,10 +99,9 @@ const drive = async (d: Drive): Promise<Run> => {
         steps++
         if (request.kind === "restart") return Promise.resolve()
         log.push(request.name)
-        if (request.kind === "agent") prompts.set(request.name, request.prompt)
+        record(request)
         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 => {
@@ -92,12 +110,16 @@ const drive = async (d: Drive): Promise<Run> => {
       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" }]
-          : []),
-      ],
+      changesSince: (from: string): readonly Change[] => {
+        since.push(from)
+        if (d.passSecondGate && awaits === 2) throw new Stop()
+        return [
+          { 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",
     },
@@ -110,7 +132,7 @@ const drive = async (d: Drive): Promise<Run> => {
     if (!(error instanceof Stop)) throw error
     result = "stopped"
   }
-  return { log, prompts, result, judged }
+  return { log, prompts, result, judged, gates, gateMessages, since }
 }
 
 const verdict = (answer: string, p = 0.9): JudgeAnswer => ({ answer, p })
@@ -179,7 +201,18 @@ describe("review verdict routing", () => {
 
   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.judged).toEqual([
+      "note-1",
+      "note-1.security",
+      "note-1.reversibility",
+      "note-1.blastRadius",
+      "note-1.newConcept",
+      "note-2",
+      "note-2.security",
+      "note-2.reversibility",
+      "note-2.blastRadius",
+      "note-2.newConcept",
+    ])
     expect(run.log.filter((n) => n === "review.triage")).toHaveLength(1)
   })
 
@@ -337,49 +370,195 @@ describe("the default quality lenses", () => {
   })
 })
 
-describe("scenario wording in review's fix turns", () => {
-  const frozen = { at: "h1", texts: { "e2e/a.feature": "Given a" } }
-  const risky = doc(["Risk: drops the carry", "sub"])
+describe("severityOf", () => {
+  const note = (forced = false): ReviewNote => ({
+    id: "n",
+    kind: "pointer",
+    anchor: "a",
+    before: "",
+    text: "t",
+    forced,
+  })
+  const ans = (o: Partial<Record<string, string>> = {}, p = 0.9) => {
+    const base: Record<string, string> = {
+      security: "no",
+      reversibility: "two-way",
+      blastRadius: "local",
+      newConcept: "no",
+      ...o,
+    }
+    return Object.fromEntries(Object.entries(base).map(([k, v]) => [`n.${k}`, { answer: v, p }]))
+  }
+  const j = (answers: ReturnType<typeof ans>, truncated: string[] = []) => ({ answers, truncated })
+
+  it("security or one-way is critical and names each answer", () => {
+    expect(severityOf(note(), j(ans({ security: "yes" })), 0.7)).toMatchObject({
+      tier: "critical",
+      reason: "critical: security",
+    })
+    expect(
+      severityOf(note(), j(ans({ security: "yes", reversibility: "one-way" })), 0.7),
+    ).toMatchObject({ tier: "critical", reason: "critical: security, one-way door", rank: 0 })
+  })
+
+  it("contract or new concept is should; neither is could", () => {
+    expect(severityOf(note(), j(ans({ blastRadius: "contract" })), 0.7).tier).toBe("should")
+    expect(severityOf(note(), j(ans({ newConcept: "yes" })), 0.7)).toMatchObject({
+      tier: "should",
+      reason: "should: new concept",
+      rank: 1,
+    })
+    expect(severityOf(note(), j(ans()), 0.7)).toMatchObject({ tier: "could", rank: 2 })
+  })
+
+  it("unsure is critical: unanswered, unrecognised, cut, low p, blank floor", () => {
+    const a = ans()
+    delete (a as Record<string, unknown>)["n.security"]
+    for (const x of [
+      severityOf(note(), j(a), 0.7),
+      severityOf(note(), j(ans({ security: "unsure" })), 0.7),
+      severityOf(note(), j(ans(), ["n"]), 0.7),
+      severityOf(note(), j(ans({}, 0.5)), 0.7),
+      severityOf(note(), j(ans()), Infinity),
+    ])
+      expect(x).toMatchObject({ tier: "critical", reason: "critical: judge unsure" })
+  })
+
+  it("forced is critical regardless of answers", () => {
+    expect(severityOf(note(true), j({}), 0.7)).toMatchObject({
+      tier: "critical",
+      reason: "critical: forced by `!`",
+    })
+  })
+})
+
+describe("severity routing", () => {
+  const sev = (id: string, a: Record<string, string>): Record<string, JudgeAnswer> =>
+    Object.fromEntries(Object.entries(a).map(([k, v]) => [`${id}.${k}`, verdict(v)]))
+  const could = {
+    security: "no",
+    reversibility: "two-way",
+    blastRadius: "local",
+    newConcept: "no",
+  }
+
+  it("a forced note is asked nothing, not even the verdict, and is a critical edit", async () => {
+    const run = await drive({ notes: ["! rename it — now", "sub"] })
+    expect(run.judged.filter((id) => id.startsWith("note-1"))).toEqual([])
+    expect(run.log).toContain("review.collecting")
+    expect(run.prompts.get("review.collecting")).toContain("(critical: forced by `!`)")
+  })
+
+  it("a confident could edit defers and, alone, returns to the review gate", async () => {
+    const run = await drive({
+      notes: ["add — quote", "sub", "mul"],
+      answers: { "note-1": verdict("edit"), ...sev("note-1", could) },
+    })
+    expect(run.log).toEqual([
+      "review.reviewing",
+      "review.await-review",
+      "review.triage",
+      "review.defer",
+      "review.await-review",
+    ])
+  })
+
+  it("severity answers on a nit leave it a nit", async () => {
+    const run = await drive({
+      notes: ["add — typo", "sub", "mul"],
+      answers: { "note-1": verdict("nit"), ...sev("note-1", { reversibility: "one-way" }) },
+    })
+    expect(run.log).toContain("review.fix.nits.fixing")
+    expect(run.log).not.toContain("review.collecting")
+  })
+
+  it("edits are captured critical before should, doors first, each labelled", async () => {
+    const run = await drive({
+      notes: ["add — plain", "sub — concept", "mul — door"],
+      answers: {
+        "note-1": verdict("edit"),
+        ...sev("note-1", { ...could, security: "yes" }),
+        ...sev("note-2", { ...could, newConcept: "yes" }),
+        ...sev("note-3", { ...could, reversibility: "one-way" }),
+      },
+    })
+    const capture = run.prompts.get("review.collecting") ?? ""
+    const at = (id: string): number => capture.indexOf(`- ${id} —`)
+    expect(at("note-3")).toBeLessThan(at("note-1"))
+    expect(at("note-1")).toBeLessThan(at("note-2"))
+    expect(capture).toContain("(critical: one-way door)")
+    expect(capture).toContain("(should: new concept)")
+    expect(capture).toContain("(critical: security)")
+  })
+
+  it("a round of only forced notes judges nothing and tiers each critical", async () => {
+    const run = await drive({ notes: ["! rename it", "! drop it", "mul"] })
+    expect(run.log).not.toContain("review.triage")
+    expect(run.judged).toEqual([])
+    expect(run.prompts.get("review.collecting")).toContain("(critical: forced by `!`)")
+    expect(run.prompts.get("review.collecting")).not.toContain("! rename")
+  })
+
+  it("a note opening with != is not forced and keeps its text", async () => {
+    const run = await drive({ notes: ["!= should be ===", "sub"] })
+    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([false, 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("a later gate does not accept 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([false, false])
+  })
+
+  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.reviewing",
+      "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 green-keeping fix after a risk fix that rewrites a scenario stops at review.scenario-wording", async () => {
-    const log: string[] = []
-    let red = false
-    let drifted = false
-    installContext(
-      fixtureContext(
-        {},
-        {
-          step: (request: StepRequest) => {
-            if (request.kind === "restart") return Promise.resolve()
-            log.push(request.name)
-            if (request.name === "health.check") red = !red && !drifted
-            if (request.name === "fix") drifted = true
-            if (request.name === "scenario-wording") throw new Stop()
-            return Promise.resolve()
-          },
-          pushScope: () => undefined,
-          popScope: () => undefined,
-          read: (path) =>
-            path === REVIEW
-              ? risky
-              : path === "e2e/a.feature"
-                ? drifted
-                  ? "Given b"
-                  : "Given a"
-                : undefined,
-          changes: (): readonly Change[] =>
-            red
-              ? [{ path: ".gtd/FEEDBACK.md", status: "added", before: undefined, after: "red" }]
-              : [],
-          matches: (path, pattern) => path === pattern,
-          head: () => "h2",
-          start: () => "h0",
-        },
-      ),
-    )
-    await review("base", undefined, frozen).catch((e: unknown) => {
-      if (!(e instanceof Stop)) throw e
+  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(log.slice(-2)).toEqual(["fix", "scenario-wording"])
+    expect(run.log).toContain("review.collecting")
+    expect(run.log).not.toContain("review.defer")
   })
 })

package/src/workflows/feature/review.ts

@@ -1,8 +1,15 @@
-import { answered, judge, numeric, vars, type JudgeQuestion } from "../../flows/index.js"
+import {
+  answered,
+  head,
+  judge,
+  numeric,
+  vars,
+  type JudgeQuestion,
+  type Judgment,
+} 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,
@@ -14,8 +21,7 @@ import {
 } 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"
+import { answerReviewQuestions, collecting, deferNotes, fixNits } from "./steps.js"
 
 export type { ReviewOutcome } from "../../workflow-kit/index.js"
 
@@ -30,33 +36,124 @@ const verdictQuestion = (note: ReviewNote): JudgeQuestion => ({
     "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.",
 })
 
+type Tier = "critical" | "should" | "could"
+
+const SEVERITY_ANSWERS: Readonly<Record<string, readonly string[]>> = {
+  security: ["yes", "no"],
+  reversibility: ["one-way", "two-way"],
+  blastRadius: ["local", "module", "contract"],
+  newConcept: ["yes", "no"],
+}
+
+interface Severity {
+  readonly tier: Tier
+  readonly reason: string
+  /** Capture order: 0 one-way door, 1 new concept, 2 everything else. */
+  readonly rank: 0 | 1 | 2
+}
+
 /**
- * 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.
+ * Deferring is the risky direction: anything unanswered, unrecognised, cut or
+ * below `minP` is `critical`, never `could`.
  */
-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]
-    }),
-  )
+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
+  const rank = (): 0 | 1 | 2 =>
+    a("reversibility") === "one-way" ? 0 : a("newConcept") === "yes" ? 1 : 2
+  if (note.forced) return { tier: "critical", reason: "critical: forced by `!`", rank: 2 }
+  const unsure =
+    judgment.truncated.includes(note.id) ||
+    Object.entries(SEVERITY_ANSWERS).some(
+      ([q, allowed]) => !allowed.includes(a(q) ?? "") || !((ans(q)?.p ?? NaN) >= minP),
+    )
+  if (unsure) return { tier: "critical", reason: "critical: judge unsure", rank: 2 }
+  const critical = [
+    ...(a("security") === "yes" ? ["security"] : []),
+    ...(a("reversibility") === "one-way" ? ["one-way door"] : []),
+  ]
+  if (critical.length > 0)
+    return { tier: "critical", reason: `critical: ${critical.join(", ")}`, rank: rank() }
+  const should = [
+    ...(a("blastRadius") === "contract" ? ["contract"] : []),
+    ...(a("newConcept") === "yes" ? ["new concept"] : []),
+  ]
+  if (should.length > 0)
+    return { tier: "should", reason: `should: ${should.join(", ")}`, rank: rank() }
+  return { tier: "could", reason: "could", rank: 2 }
 }
 
+const severityQuestions = (note: ReviewNote): JudgeQuestion[] => [
+  {
+    id: `${note.id}.security`,
+    primitive: "noul",
+    instructions: `Does the change the human asks for in note "${note.id}" (on "${note.anchor}") touch security — authentication, authorisation, secrets, untrusted input or data exposure?`,
+    criteria: "yes: it changes or could weaken a security property. no: it does not.",
+  },
+  {
+    id: `${note.id}.reversibility`,
+    primitive: "choice",
+    instructions: `Once the change in note "${note.id}" ships, can it be undone without breaking anyone who already depends on it?`,
+    criteria:
+      "one-way: a published API, file format, persisted data, protocol or other contract that cannot be taken back. two-way: can be reverted freely.",
+  },
+  {
+    id: `${note.id}.blastRadius`,
+    primitive: "choice",
+    instructions: `How far does the change in note "${note.id}" reach?`,
+    criteria:
+      "local: one function or file. module: a whole module or several files. contract: a public interface other code or users depend on.",
+  },
+  {
+    id: `${note.id}.newConcept`,
+    primitive: "noul",
+    instructions: `Does the change in note "${note.id}" introduce a concept new to this codebase — a new abstraction, entity or term? Judge from the evidence, never a glossary; reusing or extending an existing concept is not new.`,
+    criteria: "yes: a genuinely new concept. no: reuses or extends an existing one.",
+  },
+]
+
+/**
+ * One judge rest: a verdict per unforced note (a forced note is asked
+ * 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`.
+ */
+const triage =
+  (severities: Map<string, Severity>) =>
+  async (notes: readonly ReviewNote[]): Promise<ReadonlyMap<string, kit.Verdict>> => {
+    const asked = notes.filter((n) => !n.forced)
+    const judgment: Judgment =
+      asked.length === 0
+        ? { answers: {}, truncated: [] }
+        : await judge("review.triage", {
+            questions: asked.flatMap((n) => [verdictQuestion(n), ...severityQuestions(n)]),
+            evidence: Object.fromEntries(
+              asked.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 { answers, truncated } = judgment
+    const minP = numeric(vars.reviewNoteActionable, Infinity)
+    const severityMinP = numeric(vars.reviewSeverityMinP, Infinity)
+    severities.clear()
+    return new Map(
+      notes.map((n): [string, kit.Verdict] => {
+        const verdict = n.forced
+          ? 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"]
+      }),
+    )
+  }
+
 const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
 
 /**
@@ -68,26 +165,66 @@ const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".
 export const review = (
   base: string,
   escalations: EscalationCount = { rounds: 0 },
-  frozen?: FrozenScenarios,
-): Promise<kit.ReviewOutcome> =>
-  kit.review(base, {
+): Promise<kit.ReviewOutcome> => {
+  const severities = new Map<string, Severity>()
+  // Armed by a defer-only round and spent at the very next gate; a fresh
+  // review (`reviewing`) disarms it, so a later gate never accepts a clean land.
+  let deferred: readonly t.NoteInput[] = []
+  return kit.review(base, {
     file: REVIEW,
     feedback: REQUIREMENTS,
     isCode,
-    reviewing,
-    fixRisks: (risks) => guarded(frozen, () => fixRisks(risks), "review")(),
-    keepGreen: () => healthy(guarded(frozen, fixCheck, "review"), { escalations }),
-    awaitReview,
+    reviewing: (b, carry) => {
+      deferred = []
+      return reviewing(b, carry)
+    },
+    fixRisks,
+    keepGreen: () => healthy(fixCheck, { escalations }),
+    awaitReview: (b) => {
+      const notes = deferred
+      deferred = []
+      return notes.length > 0
+        ? awaitReview(b, t.buildReviewAwaitAfterDeferMessage(b, notes), true)
+        : awaitReview(b)
+    },
     reviewMissing,
     collecting,
-    triage,
+    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())
+    },
     answerQuestions: answerReviewQuestions,
-    fixNits: (notes) => guarded(frozen, () => fixNits(notes), "review")(),
+    fixNits,
     close: closeReview,
     captures: {
       edits: t.reviewEditsCapture,
       notes: t.reviewNotesCapture,
-      editNotes: t.reviewEditNotesCapture,
+      editNotes: (round, edits, answeredAt) =>
+        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, s }) => ({
+              id: n.id,
+              anchor: n.anchor,
+              text: n.forced ? n.text.replace(/^!\s*/, "") : n.text,
+              ...(s === undefined ? {} : { label: s.reason }),
+            })),
+          answeredAt,
+        ),
     },
     refusals: {
       deleted:
@@ -96,11 +233,11 @@ 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",
     },
   })
+}
 
-/** The build tail: fix (when entered red), keep green, the quality lap, then human review since `base`. */
+/** The build tail: fix (when entered red), keep green unless `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)
+  green = false,
+): Promise<kit.ReviewOutcome> => tail(fixFirst, (escalations) => review(base, escalations), green)

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

@@ -79,4 +79,16 @@ describe("the feature workflow's own steps declare skills — a step's rendered
     expect(request.prompt).toContain("semicolon")
     expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
   })
+
+  it("deferNotes rests at build.review.defer as a script writing .gtd/TODO.md", async () => {
+    const request = await capture(
+      () =>
+        steps.deferNotes([{ id: "note-1", anchor: "a", text: "x", label: "could" }], "abcdef123"),
+      "build",
+    )
+    if (request.kind !== "run") throw new Error("unreachable")
+    expect(request.name).toBe("review.defer")
+    expect(request.body).toContain("## Deferred review notes (abcdef1)")
+    expect(request.options).toMatchObject({ file: ".gtd/TODO.md" })
+  })
 })

package/src/workflows/feature/steps.ts

@@ -1,4 +1,4 @@
-import { human } from "../../flows/index.js"
+import { human, run } from "../../flows/index.js"
 import * as t from "../shared/text.js"
 import { ARCHITECTURE, coder, FEEDBACK, planner, REQUIREMENTS, REVIEW } from "../shared/steps.js"
 
@@ -90,3 +90,10 @@ export const collecting = (capture: string): Promise<void> =>
     system: t.reviewerSystem(),
     allowEmpty: true,
   })
+
+/** `build.review.defer`: append `notes` to `.gtd/TODO.md` as one section; the step's landing is the commit. */
+export const deferNotes = (notes: readonly t.NoteInput[], round: string): Promise<void> =>
+  run("review.defer", t.deferNotesScript(notes, round), {
+    label: "Deferring could-notes to TODO.md",
+    file: ".gtd/TODO.md",
+  })