@pmelab/gtd 23.2.0 → 24.1.0

package/src/workflows/feature/review.ts

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

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

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

package/src/workflows/feature/steps.ts

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

package/src/workflows/fix/fix.feature

@@ -0,0 +1,80 @@
+Feature: fix fixes the notes review hands it
+
+  `review` and `fix` meet only in `.gtd/REVIEW.md`: a review the human leaves
+  a note in ends with the reviewer's copy kept beside it, and `gtd door fix`
+  picks both up.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    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"
+
+  Scenario: a note left in review is fixed, and both review files are removed
+    Given step "review-gate.check" changes nothing
+    And step "build.health.check" changes nothing
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function
+      """
+    When gtd opens door "review" with "HEAD~1"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function — rename it to sum
+      """
+    And step "build.review.handing-off" runs its script
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    And ".gtd/REVIEW.orig.md" contains "new add function"
+
+    Given step "notes.fixing" writes "src/calc.ts" with:
+      """
+      export const sum = (a: number, b: number) => a + b
+      """
+    And step "notes.closing" runs its script
+    When gtd opens door "fix"
+    Then the resting step's content contains "rename it to sum"
+    # The fix goes to its own review, which the same scripted reviewer writes
+    # afresh — the handed-off review itself is gone, as the reviewer's copy shows.
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And the commit subjects end with:
+      """
+      gtd(human): notes.fixing
+      gtd(agent): notes.fixing → notes.closing
+      gtd(check): notes.closing → build.health.check
+      gtd(check): build.health.check → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.await-review
+      """
+    And ".gtd/REVIEW.orig.md" does not exist
+    And ".gtd/REVIEW.md" contains "new add function"
+    And "src/calc.ts" contains "sum"
+
+  Scenario: a reviewer's copy with no review is refused
+    Given a file ".gtd/REVIEW.orig.md" with:
+      """
+      # Review: abc1234
+      """
+    And the working tree is committed as "chore: stray copy"
+    Then opening door "fix" is refused with "has no .gtd/REVIEW.md"

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

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest"
+import { runsItsScript, testRepo } from "../../testkit/index.js"
+import { CONFIG_SCAFFOLD } from "../../install/index.js"
+import { reviewDoc } from "../shared/config.fixture.js"
+
+const REVIEW = ".gtd/REVIEW.md"
+const ORIG = ".gtd/REVIEW.orig.md"
+const CALC = "export const add = (a: number, b: number) => a + b\n"
+
+describe("the fix workflow", () => {
+  it("with no handed-off review, repairs a red baseline and hands it to review", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+    await repo.start("fix")
+    const rest = await repo.drive({
+      "fix-precheck": (_, r) => r.write(".gtd/FEEDBACK.md", "1 test failing\n"),
+      "build.fix": (beat, r) => {
+        expect(beat.content).toContain(".gtd/FEEDBACK.md")
+        r.remove(".gtd/FEEDBACK.md")
+        r.write("src/repair.ts", "export const repaired = true\n")
+      },
+      "build.health.check": () => undefined,
+    })
+    expect(rest).toMatchObject({ state: "build.review.reviewing", actor: "agent" })
+    expect(repo.subjects().slice(1)).toEqual([
+      "gtd(human): fix-precheck",
+      "gtd(check): fix-precheck → build.fix",
+      "gtd(agent): build.fix → build.health.check",
+      "gtd(check): build.health.check → build.review.reviewing",
+    ])
+  })
+
+  it("with a green baseline, has nothing to fix", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+    await repo.start("fix")
+    const rest = await repo.drive({ "fix-precheck": () => undefined })
+    expect(rest.state).toBe("idle")
+    expect(repo.subjects().at(-1)).toBe("gtd(check): fix-precheck → idle")
+  })
+
+  it("fixes a handed-off review's notes and risks in one turn, removes both review files, then checks health", async () => {
+    const repo = testRepo({
+      workflow: CONFIG_SCAFFOLD,
+      env: { GTD_QUALITYREVIEWS: "" },
+      files: {
+        "src/calc.ts": CALC,
+        [REVIEW]: reviewDoc("add — rename it to sum", "Risk: drops the carry"),
+        [ORIG]: reviewDoc("add", "Risk: drops the carry"),
+      },
+    })
+    await repo.door("fix")
+    const rest = await repo.drive({
+      "notes.fixing": (beat, r) => {
+        expect(beat.content).toContain("rename it to sum")
+        expect(beat.content).toContain("Risk: drops the carry")
+        r.write("src/calc.ts", CALC.replace("add", "sum"))
+      },
+      "notes.closing": runsItsScript,
+    })
+    expect(rest.state).toBe("build.health.check")
+    expect(repo.subjects().slice(1)).toEqual([
+      "gtd(human): notes.fixing",
+      "gtd(agent): notes.fixing → notes.closing",
+      "gtd(check): notes.closing → build.health.check",
+    ])
+    expect(repo.read("src/calc.ts")).toContain("sum")
+    expect(repo.read(REVIEW)).toBeUndefined()
+    expect(repo.read(ORIG)).toBeUndefined()
+  })
+
+  it("refuses a review with no reviewer's copy, so no note is deleted unread", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, files: { [REVIEW]: reviewDoc("add") } })
+    await expect(repo.door("fix")).rejects.toThrow(/not handed off/)
+  })
+})

package/src/workflows/fix/fix.ts

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

package/src/workflows/fix/index.ts

@@ -0,0 +1,6 @@
+import { fix } from "./fix.js"
+
+export { fix, fixFlow, fixReviewNotes } from "./fix.js"
+export * from "../shared/reserved.js"
+
+export default fix

package/src/workflows/index.ts

@@ -1,4 +1,38 @@
 // The `@pmelab/gtd/workflows` entry, built on its own: core never imports it,
 // a repository's `gtd.config.ts` does.
-export * from "./bundled.js"
-export { default } from "./bundled.js"
+import type { Doors } from "../flows/index.js"
+import { feature } from "./feature/feature.js"
+
+export { threads, type ThreadInfo } from "../flows/index.js"
+export * from "./shared/reserved.js"
+export { ShippedOptions } from "./shared/options.js"
+export { agentWithSkills } from "./shared/text.js"
+export * from "./shared/steps.js"
+export * from "./shared/health.js"
+export * from "./shared/scenarios.js"
+export {
+  closeReview,
+  fixQualityFindings,
+  handOffReview,
+  handOffTail,
+  qualityLap,
+  REVIEW_ORIG,
+  tail,
+  type TailPlan,
+} from "./shared/tail.js"
+export { lensesOf } from "../workflow-kit/index.js"
+export * from "./feature/steps.js"
+export * from "./feature/planning.js"
+export * from "./feature/packages.js"
+export { buildTail, type ReviewOutcome } from "./feature/review.js"
+export * from "./feature/feature.js"
+export { base, review, reviewFlow } from "./review/review.js"
+export { fix, fixFlow, fixReviewNotes } from "./fix/fix.js"
+
+export default feature
+
+/**
+ * @deprecated Empty: each shipped workflow builds its own doors, so a config
+ * gets `fix` and `review [base]` by exporting `fix` and `review`.
+ */
+export const doors: Doors = {}

package/src/workflows/review/index.ts

@@ -0,0 +1,6 @@
+import { review } from "./review.js"
+
+export { review, reviewFlow } from "./review.js"
+export * from "../shared/reserved.js"
+
+export default review

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

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest"
+import { runsItsScript, testRepo, type TestRepo } from "../../testkit/index.js"
+import { CONFIG_SCAFFOLD } from "../../install/index.js"
+import { reviewDoc } from "../shared/config.fixture.js"
+import { base } from "./review.js"
+
+const REVIEW = ".gtd/REVIEW.md"
+const ORIG = ".gtd/REVIEW.orig.md"
+
+/** A repository with one commit to review, the review run until the human holds `.gtd/REVIEW.md`. */
+const reviewed = async (): Promise<TestRepo> => {
+  const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+  repo.write("src/calc.ts", "export const add = (a: number, b: number) => a + b\n")
+  repo.commit("feat: add calculator")
+  await repo.door("review", "HEAD~1")
+  const rest = await repo.drive({
+    "review-gate.check": () => undefined,
+    "build.health.check": () => undefined,
+    "build.review.reviewing": (beat, r) => {
+      expect(beat.file).toBe(REVIEW)
+      r.write(REVIEW, reviewDoc("new add function"))
+    },
+  })
+  expect(rest).toMatchObject({ state: "build.review.await-review", actor: "human" })
+  return repo
+}
+
+describe("the review workflow", () => {
+  it("checks, reviews and hands the review to the human", async () => {
+    const repo = await reviewed()
+    expect(repo.subjects().slice(2)).toEqual([
+      "gtd(human): review-gate.check",
+      "gtd(check): review-gate.check → build.health.check",
+      "gtd(check): build.health.check → build.review.reviewing",
+      "gtd(agent): build.review.reviewing → build.review.await-review",
+    ])
+  })
+
+  it("closes a review the human signs off", async () => {
+    const repo = await reviewed()
+    repo.write(REVIEW, reviewDoc("new add function").replace("- [ ]", "- [x]"))
+    await repo.land()
+    const rest = await repo.drive({ "build.review.closing": runsItsScript })
+    expect(rest.state).toBe("idle")
+    expect(repo.subjects().slice(-2)).toEqual([
+      "gtd(human): build.review.await-review → build.review.closing",
+      "gtd(check): build.review.closing → idle",
+    ])
+    expect(repo.read(REVIEW)).toBeUndefined()
+  })
+
+  it("never lands a review the review format rejects", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+    repo.write("src/calc.ts", "export const add = (a: number, b: number) => a + b\n")
+    repo.commit("feat: add calculator")
+    await repo.door("review", "HEAD~1")
+    await expect(
+      repo.drive({
+        "review-gate.check": () => undefined,
+        "build.health.check": () => undefined,
+        "build.review.reviewing": (_, r) => r.write(REVIEW, "not a review\n"),
+      }),
+    ).rejects.toThrow(/validating \.gtd\/REVIEW\.md/)
+    expect(repo.subjects().at(-1)).toBe("gtd(check): build.health.check → build.review.reviewing")
+  })
+
+  it("ends with the review and the reviewer's copy kept when the human leaves a note", async () => {
+    const repo = await reviewed()
+    repo.write(REVIEW, reviewDoc("new add function — rename it to sum"))
+    await repo.land()
+    const rest = await repo.drive({
+      "build.review.handing-off": runsItsScript,
+    })
+    expect(rest.state).toBe("idle")
+    expect(repo.subjects().slice(-2)).toEqual([
+      "gtd(human): build.review.await-review → build.review.handing-off",
+      "gtd(check): build.review.handing-off → idle",
+    ])
+    expect(repo.read(REVIEW)).toContain("rename it to sum")
+    expect(repo.read(ORIG)).toBe(reviewDoc("new add function"))
+  })
+
+  it("refuses a pending hand-off before requesting any step, the gate's check included", async () => {
+    const repo = testRepo({
+      workflow: CONFIG_SCAFFOLD,
+      files: { [REVIEW]: reviewDoc("note"), [ORIG]: reviewDoc("orig") },
+    })
+    await expect(repo.door("review")).rejects.toThrow(".gtd/REVIEW.orig.md is a pending hand-off")
+    expect(repo.subjects()).toEqual(["chore: initial commit"])
+  })
+})
+
+describe("the deprecated shipped base", () => {
+  it("answers for a workflow named review only, mapping reviewBase", () => {
+    expect(base("review", {})).toBe("")
+    expect(base("review", { reviewBase: "v1" })).toBe("v1")
+    expect(base("audit", { reviewBase: "v1" })).toBeUndefined()
+  })
+})