@pmelab/gtd 48.0.0 → 49.0.0

package/src/workflows/feature/reviewer-walkthrough.feature

@@ -0,0 +1,229 @@
+@inmem
+Feature: a reviewer walks the human through the feature's code
+
+  The feature's final review is written by a reviewer turn
+  (`build.review.reviewing`): chunks grouped by concern, each pointing at its
+  code, so the phone shows it. Every finding the quality laps left gets a chunk
+  of its own, headed exactly as the prompt gives it, holding the pointers to the
+  code it cites; gtd then adds the finding's text and the answer boxes
+  (`build.review.carrying`). A chunk pointing at no code, or a finding left out,
+  is refused.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And an environment variable "GTD_FLAGMODE" set to "false"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract
+
+      subtract(a, b) returns the difference.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.naive" writes "src/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      """
+    And step "seam.check" changes nothing
+    And step "implement.applying" runs its script
+    And step "implement.health.check" changes nothing
+    And step "implement.closing" runs its script
+    And judge step "implement.coverage" answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9}]
+      """
+    And step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## AC-1 ignores floating point
+
+      Should subtract round? The criterion does not say.
+      """
+    And judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"design","p":0.9}]
+      """
+    And step "build.quality.sorting" runs its script
+    And step "build.quality.closing" runs its script
+    And step "build.review.carrying" runs its script
+
+  Scenario: the finding gets its text and answer boxes under the reviewer's pointers
+    Given step "build.review.reviewing" is prompted with "- `## AC-1 ignores floating point`:"
+    And step "build.review.reviewing" is prompted with "> Should subtract round? The criterion does not say."
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      The new export.
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+      """
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## Subtract
+
+      The new export.
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## AC-1 ignores floating point
+
+      Should subtract round? The criterion does not say.
+
+      In the code:
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+
+      Tick exactly one:
+
+      - [ ] fix as suggested
+      - [ ] won't fix
+      - [ ] _your answer_
+      """
+    And no commit body contains "build.review.composing"
+    And the commit subjects end with:
+      """
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
+      """
+
+  Scenario: a chunk pointing at no code is refused
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      The new export, with no pointer.
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+      """
+    Then driving the process is refused with "Subtract — points at no code"
+
+  Scenario: a finding the reviewer left out is refused
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+      """
+    Then driving the process is refused with "AC-1 ignores floating point — no chunk of its own"
+
+  Scenario: a risk the reviewer marks is fixed before the human sees the review
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      - [ ] ./src/calc.ts#2-2 — Risk: overflows on large numbers
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+      """
+    And step "build.review.fix.risks.fixing" changes nothing
+    And step "build.health.check" changes nothing
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And the commit subjects end with:
+      """
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.fix.risks.fixing
+      gtd(agent): build.review.fix.risks.fixing → build.health.check
+      gtd(check): build.health.check → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
+      """
+
+  Scenario: a standard conflict the reviewer writes itself is refused
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Standard conflict 0123abcd
+
+      - [ ] ./src/calc.ts#2-2 — copied over
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+      """
+    Then driving the process is refused with "Standard conflict 0123abcd — gtd writes conflicts"
+
+  Scenario: two chunks with one title are refused
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+      """
+    Then driving the process is refused with "AC-1 ignores floating point — a second chunk with this title"
+
+  Scenario: a risk marked in a finding's chunk is refused, never fixed
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — Risk: no rounding
+      """
+    Then driving the process is refused with "no `Risk:` in a quality finding's chunk"

package/src/workflows/feature/seam-rejection.feature

@@ -100,7 +100,7 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
     And step "implement.applying" runs its script
     When gtd lands
     And the process is driven
-    Then the process rests at "build.review.composing"
+    Then the process rests at "build.review.reviewing"
     And the commit subjects end with:
       """
       gtd(human): idle → unwind
@@ -124,7 +124,7 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.composing
+      gtd(check): implement.closing → build.review.reviewing
       """
     And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_risk_tier=0"
     And the commit "gtd(agent): seam.naive → seam.check" has a body containing "Gtd-Kept:"

package/src/workflows/feature/seam.feature

@@ -152,7 +152,7 @@ Feature: the naive pass and seam judge decide how a feature is built
       [{"id":"AC-1","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "build.review.composing"
+    Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "subtract"
     And the commit subjects end with:
       """
@@ -160,7 +160,7 @@ Feature: the naive pass and seam judge decide how a feature is built
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.composing
+      gtd(check): implement.closing → build.review.reviewing
       """
     And ".gtd/REQUIREMENTS.md" does not exist
 

package/src/workflows/feature/slice-findings.feature

@@ -70,7 +70,7 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
     And step "build.quality.sorting" runs its script
     And step "build.quality.closing" runs its script
     And step "build.health.check" changes nothing
-    And step "build.review.composing" runs its script
+    And step "build.review.carrying" runs its script
 
   Scenario: a finding questioning a criterion reaches the final review, never the fixer
     Given step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
@@ -85,6 +85,25 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       """
       [{"id":"Q1","answer":"design","p":0.9}]
       """
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract and multiply
+
+      - [ ] ./src/sub.test.ts#1-1 — subtract
+      - [ ] ./src/mul.test.ts#1-1 — multiply
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/sub.test.ts#1-1 — where it applies
+
+      ## AC-1 ignores floating point (2)
+
+      - [ ] ./src/sub.test.ts#1-1 — where it applies
+      """
     When the process is driven
     Then the process rests at "build.review.await-review"
     And no commit body contains "build.fix.quality.fixing"
@@ -117,8 +136,9 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       gtd(check): implement.closing → build.quality.correctness.reviewing
       gtd(agent): build.quality.correctness.reviewing → build.quality.triage
       gtd(judge): build.quality.triage → build.quality.sorting
-      gtd(check): build.quality.sorting → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
+      gtd(check): build.quality.sorting → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
       """
 
   Scenario: a mechanical finding the fix cap leaves in an early slice is carried, never escalated
@@ -135,6 +155,25 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       [{"id":"Q1","answer":"mechanical","p":0.9}]
       """
     And step "build.fix.quality.fixing" changes nothing
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract and multiply
+
+      - [ ] ./src/sub.test.ts#1-1 — subtract
+      - [ ] ./src/mul.test.ts#1-1 — multiply
+
+      ## subtract has no negative test
+
+      - [ ] ./src/sub.test.ts#1-1 — where it applies
+
+      ## subtract has no negative test (2)
+
+      - [ ] ./src/sub.test.ts#1-1 — where it applies
+      """
     When the process is driven
     Then the process rests at "build.review.await-review"
     And no commit body contains "build.health.describe"
@@ -168,8 +207,9 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       gtd(agent): build.fix.quality.fixing
       gtd(agent): build.fix.quality.fixing → build.health.check
       gtd(check): build.health.check → build.quality.closing
-      gtd(check): build.quality.closing → build.review.composing
-      gtd(check): build.review.composing → build.review.await-review
+      gtd(check): build.quality.closing → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
       """
 
   Scenario: the final review lists every slice's fixes with their commits
@@ -190,6 +230,17 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       it("subtracts a larger number", () => {})
       """
     And step "build.fix.quality.fixing" deletes ".gtd/QUALITY.md"
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract and multiply
+
+      - [ ] ./src/sub.test.ts#1-1 — subtract
+      - [ ] ./src/mul.test.ts#1-1 — multiply
+      """
     When the process is driven
     Then the process rests at "build.review.await-review"
     And ".gtd/REVIEW.md" contains ", slice 1, lens correctness)"

package/src/workflows/feature/slicing.feature

@@ -51,7 +51,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-2","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "build.review.composing"
+    Then the process rests at "build.review.reviewing"
     And the commit subjects end with:
       """
       gtd(human): design.gate.answer → seam.naive
@@ -60,7 +60,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.composing
+      gtd(check): implement.closing → build.review.reviewing
       """
     And the output lines of gtd "slices" start with:
       """
@@ -112,7 +112,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       [{"id":"AC-2","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "build.review.composing"
+    Then the process rests at "build.review.reviewing"
     And the commit subjects end with:
       """
       gtd(agent): design.triage → design.gate.answer
@@ -129,7 +129,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.composing
+      gtd(check): implement.closing → build.review.reviewing
       """
     And the output lines of gtd "slices" start with:
       """
@@ -268,7 +268,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       """
     When gtd lands
     And the process is driven
-    Then the process rests at "build.review.composing"
+    Then the process rests at "build.review.reviewing"
     And the commit subjects end with:
       """
       gtd(human): seam.steer → seam.naive
@@ -277,7 +277,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → build.review.composing
+      gtd(check): implement.closing → build.review.reviewing
       """
     And ".gtd/REQUIREMENTS.md" does not exist
     And ".gtd/SLICES.md" does not exist

package/src/workflows/feature/standards.feature

@@ -67,7 +67,31 @@ Feature: the review learns standards from the human's answers
       Calculators read better as classes.
       """
     And step "build.quality.sorting" runs its script
-    And step "build.review.composing" runs its script
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+      """
+    And step "build.review.reviewing", when prompted with "- `## subtract has no class`", writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## subtract has no class
+
+      - [ ] ./src/calc.ts#2-2 — a plain function
+      """
+    And step "build.review.carrying" runs its script
     And judge step "build.quality.triage" answers:
       """
       [{"id":"Q1","answer":"design","p":0.9}]

package/src/workflows/shared/review.ts

@@ -5,6 +5,7 @@ import {
   judge,
   numeric,
   read,
+  refuse,
   requireRevert,
   restoreScript,
   run,
@@ -15,7 +16,7 @@ import {
   type Judgment,
   type ScopeAccess,
 } from "../../flows/index.js"
-import type { ReviewNote } from "../../steering/index.js"
+import { reviewChunks, reviewRisks, type ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
 import { guarded, healthy, type EscalationCount } from "./health.js"
 import { NO_FINDINGS, type LensReport } from "./lenses.js"
@@ -28,10 +29,11 @@ import {
   fixRisks,
   REQUIREMENTS,
   REVIEW,
+  reviewing,
   reviewMissing,
 } from "./steps.js"
 import { learnStandards, settlesStandard, standardsAddedSince, standardsPending } from "./learn.js"
-import { parseStandards, STANDARDS } from "./standards.js"
+import { isConflictTitle, parseStandards, STANDARDS } from "./standards.js"
 import { closeReview, isOptionalObject, tail, type TailOptions } from "./tail.js"
 import * as t from "./text.js"
 
@@ -170,6 +172,21 @@ const triage =
 
 export const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
 
+const composedOf = (
+  base: string,
+  report: LensReport,
+  nitFix: string | undefined,
+  answered: ReadonlySet<string>,
+): t.ComposedReview => ({
+  ...report,
+  nitFix,
+  answered,
+  standards: {
+    added: standardsAddedSince(base),
+    undecided: parseStandards(read(STANDARDS) ?? "").undecided,
+  },
+})
+
 /**
  * gtd writes `.gtd/REVIEW.md` from the quality lap's `report` — no reviewer
  * turn. A re-review
@@ -189,20 +206,81 @@ const composing = (
       ? writeScript(
           REVIEW,
           t.composedReview(base, {
-            ...report,
+            ...composedOf(base, report, nitFix, answered),
             weakened: kit.removedAssertions(changesSince(base)),
-            nitFix,
-            answered,
-            standards: {
-              added: standardsAddedSince(base),
-              undecided: parseStandards(read(STANDARDS) ?? "").undecided,
-            },
           }),
         )
       : showScript(carry, REVIEW, REVIEW),
     { label: "Composing the review", file: REVIEW, base },
   )
 
+/**
+ * Refuses a review with a chunk pointing at no code, or a lap note without a
+ * chunk of its own. A range with no code change has nothing to point at, so
+ * there only a note's chunk needs a pointer.
+ */
+const requirePointers = (
+  review: string,
+  notes: readonly { title: string }[],
+  codeChanged: boolean,
+): void => {
+  const chunks = reviewChunks(review)
+  const titles = new Set(chunks.map((c) => c.title))
+  const noted = new Set(notes.map((n) => n.title))
+  const problems = [
+    ...chunks
+      .filter((c) => c.pointers === 0 && (codeChanged || noted.has(c.title)))
+      .map((c) => `  - ${REVIEW}:${c.line + 1}: ${c.title} — points at no code`),
+    ...chunks
+      .filter((c) => isConflictTitle(c.title))
+      .map((c) => `  - ${REVIEW}:${c.line + 1}: ${c.title} — gtd writes conflicts; leave it out`),
+    ...notes.filter((n) => !titles.has(n.title)).map((n) => `  - ${n.title} — no chunk of its own`),
+    // Notes and answers are matched to their chunk by title.
+    ...chunks
+      .filter((c, i) => chunks.findIndex((d) => d.title === c.title) !== i)
+      .map((c) => `  - ${REVIEW}:${c.line + 1}: ${c.title} — a second chunk with this title`),
+    // A risk is fixed before the human sees it; a note is the human's to decide.
+    ...reviewRisks(review)
+      .filter((r) => [...noted].some((title) => r.anchor.startsWith(`${title} ./`)))
+      .map((r) => `  - ${r.anchor} — no \`Risk:\` in a quality finding's chunk`),
+  ]
+  if (problems.length === 0) return
+  refuse(
+    `gtd land: review-pointers: ${problems.length} problem(s) in ${REVIEW} — every chunk needs a pointer to its code, and every quality finding its own chunk, headed exactly as the prompt gave it:\n${problems.join("\n")}`,
+  )
+}
+
+/**
+ * A reviewer walks the human through everything since `base`, every chunk
+ * pointing at its code and each of the lap's notes a chunk of its own; gtd
+ * then adds each note's text and answer boxes, and the summary chunks.
+ */
+const walkthrough = async (
+  base: string,
+  report: t.ComposedReview,
+  lap: t.ReviewRange,
+  carry: string | undefined,
+): Promise<void> => {
+  const notes = t.titledNotes(report)
+  await reviewing(base, carry, lap, t.walkthroughBlock(notes, report.nitFix))
+  const review = read(REVIEW)
+  // A review the reviewer did not write is the round's own refusal or rest.
+  if (review === undefined) return
+  requirePointers(
+    review,
+    notes,
+    changesSince(base).some((c) => isCode(c.path)),
+  )
+  const full = t.withWalkthrough(review, report)
+  if (full !== review) {
+    await run("review.carrying", writeScript(REVIEW, full), {
+      label: "Adding the quality lap's findings",
+      file: REVIEW,
+      base,
+    })
+  }
+}
+
 /**
  * The quality lap's notes reach a human over everything since `base`, who
  * answers each one — fix as suggested, won't fix, or their own answer — and
@@ -234,12 +312,27 @@ export const humanReview = (
     isCode,
     reviewing: (b, carry) => {
       const fixedAt = nitFix
-      nitFix = undefined
-      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt, answered)
+      const report = options.report ?? NO_FINDINGS
+      return options.walkthrough === true
+        ? guarded(
+            () =>
+              walkthrough(
+                b,
+                composedOf(b, report, fixedAt, answered),
+                options.lap ?? "first",
+                carry,
+              ),
+            guard,
+          )()
+        : composing(b, report, carry, fixedAt, answered)
     },
     fixRisks: guarded((notes) => fixRisks(notes, fixAccess, rules), guard),
     keepGreen: () => healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules }),
-    awaitReview,
+    // Kept until the human sees a review, so a re-review after a risk fix still names it.
+    awaitReview: (b) => {
+      nitFix = undefined
+      return awaitReview(b)
+    },
     reviewMissing,
     collecting: feedback.collecting,
     triage: triage(severities),
@@ -297,8 +390,10 @@ export interface BuildTailOptions extends TailOptions {
   readonly feedback?: FeedbackTarget | undefined
   /** Write access for the nit and risk fix turns; absent: the bundled `access` export decides. */
   readonly fixAccess?: ScopeAccess | undefined
-  /** @deprecated No reviewer turn reads it since the review is composed. */
+  /** Which round a `walkthrough` reviewer writes; absent: `first`. */
   readonly lap?: t.ReviewRange | undefined
+  /** A reviewer turn writes the review as a walkthrough of the code, the lap's notes among its chunks; absent: gtd composes it from the notes alone. */
+  readonly walkthrough?: boolean | undefined
   /** What the triaged quality lap left for the review; absent: nothing. */
   readonly report?: LensReport | undefined
 }

package/src/workflows/shared/steps.ts

@@ -94,15 +94,16 @@ export const fixQuality = (rules?: string): Promise<void> =>
     allowEmpty: true,
   })
 
-/** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
+/** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given; `extra` joins the prompt. */
 export const reviewing = (
   base: string,
   carry?: string,
   lap: t.ReviewRange = "first",
+  extra = "",
 ): Promise<void> =>
   t.agentWithSkills(
     "review.reviewing",
-    t.buildReviewReviewingPrompt(base, lap, carry, removedAssertions(changesSince(base))),
+    t.buildReviewReviewingPrompt(base, lap, carry, removedAssertions(changesSince(base)), extra),
     {
       label: "Reviewing",
       file: REVIEW,