@pmelab/gtd 43.0.0 → 44.0.0

package/src/workflows/feature/feature.ts

@@ -26,7 +26,7 @@ import {
   type StatedCriteria,
 } from "./criteria.js"
 import { design } from "./planning.js"
-import { buildTail, isCode, reUnwind, review, type ReviewOutcome } from "./review.js"
+import { buildTail, humanReview, isCode, reUnwind, type ReviewOutcome } from "../shared/review.js"
 import { implement, implementing, seamBuild } from "./seam.js"
 import { sliceCap, sliceCriteria, slicing } from "./slicing.js"
 import { recordRisk, riskTierOn, type RiskTier } from "./tier.js"
@@ -153,7 +153,7 @@ const settleQuality = async (): Promise<void> => {
 
 /** The triaged quality lap, then the human review since `base`. */
 const reviewedTail = (base: string, lensBase: string): Promise<ReviewOutcome> =>
-  tail((escalations, report) => review(base, escalations, { report }), {
+  tail((escalations, report) => humanReview(base, escalations, { report }), {
     green: true,
     lensBase,
     triage: true,

package/src/workflows/feature/index.ts

@@ -11,7 +11,7 @@ export {
   type BuildTailOptions,
   type FeedbackTarget,
   type ReviewOutcome,
-} from "./review.js"
+} from "../shared/review.js"
 export type { ReviewRange } from "../shared/text.js"
 export * from "./feature.js"
 export * from "../shared/reserved.js"

package/src/workflows/feature/refactor.ts

@@ -20,7 +20,7 @@ import { healthy, type Guard } from "../shared/health.js"
 import { coder, FEEDBACK, HANDOFF, REFACTOR } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults, testFileGlobs } from "../shared/vars.js"
-import { buildTail, reUnwind, type FeedbackTarget } from "./review.js"
+import { buildTail, reUnwind, type FeedbackTarget } from "../shared/review.js"
 import { refactorCollecting } from "./steps.js"
 
 export const REFACTOR_PACKAGE = REFACTOR

package/src/workflows/feature/seam.ts

@@ -45,7 +45,7 @@ import {
   refactorStrays,
   reviewedRefactor,
 } from "./refactor.js"
-import { isCode } from "./review.js"
+import { isCode } from "../shared/review.js"
 import { flagModeOn } from "../shared/options.js"
 import type { RiskTier } from "./tier.js"
 

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

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs"
 import { describe, expect, it } from "vitest"
-import { installContext, type ScopeOptions, type StepRequest } from "../../flows/index.js"
-import { captureStep, fixtureContext } from "../shared/text.fixture.js"
+import type { StepRequest } from "../../flows/index.js"
+import { captureStep } from "../shared/text.fixture.js"
 import * as steps from "./steps.js"
 
 const capture = (
@@ -49,68 +49,6 @@ describe("the feature workflow's own steps declare skills — a step's rendered
     expect(closed).toContain("already closed")
     expect(closed).not.toContain("exactly one `- A:` reply")
   })
-
-  it("answerReviewQuestions answers inline in .gtd/REVIEW.md as the reviewer, with its bundled skills", async () => {
-    const request = await capture(
-      () =>
-        steps.answerReviewQuestions([{ id: "note-1", anchor: "calc ./a.ts#1-1", text: "why?" }]),
-      "build",
-    )
-    if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.name).toBe("review.answer-review-questions")
-    expect(request.options).toMatchObject({
-      file: ".gtd/REVIEW.md",
-      mode: "review",
-    })
-    expect(request.prompt).toContain("code-review-and-quality")
-    expect(request.prompt).toContain("note-1 — calc ./a.ts#1-1")
-    expect(request.prompt).toContain("`A: ` line")
-    expect(request.prompt).toContain("gtd check review .gtd/REVIEW.md")
-  })
-
-  it("fixNits fixes every nit in one turn and leaves .gtd/REVIEW.md alone", async () => {
-    const request = await capture(
-      () =>
-        steps.fixNits([
-          { id: "note-1", anchor: "calc ./a.ts#1-1", text: "typo" },
-          { id: "note-2", anchor: "calc ./a.ts#2-2", text: "semicolon" },
-        ]),
-      "build",
-    )
-    if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.name).toBe("review.fix.nits.fixing")
-    expect(request.prompt).toContain("incremental-implementation, code-simplification")
-    expect(request.prompt).toContain("typo")
-    expect(request.prompt).toContain("semicolon")
-    expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
-  })
-
-  it("fixNits with access runs in a review.fix.nits scope, the step named fixing inside it", async () => {
-    const scopes: ScopeOptions[] = []
-    const steps_: StepRequest[] = []
-    const access = { write: ["src/a.ts", ".gtd/**"] }
-    installContext(
-      fixtureContext(
-        { scope: "refactor.build" },
-        {
-          step: (request) => {
-            steps_.push(request)
-            return Promise.resolve()
-          },
-          pushScope: (s) => void scopes.push(s),
-          popScope: () => undefined,
-          changesSince: () => [],
-        },
-      ),
-    )
-    try {
-      await steps.fixNits([], access)
-    } finally {
-      installContext(undefined)
-    }
-    expect(scopes).toEqual([{ name: "review.fix.nits", access }])
-    expect(steps_.map((r) => ("name" in r ? r.name : ""))).toEqual(["fixing"])
-  })
 })
 
 describe("the feature workflow's planning steps run on the planner model", () => {

package/src/workflows/feature/steps.ts

@@ -1,8 +1,11 @@
-import { human, scope, type ScopeAccess } from "../../flows/index.js"
+import { human } from "../../flows/index.js"
 import type { CollectRound } from "../../workflow-kit/index.js"
 import * as t from "../shared/text.js"
 import { riskTierOn } from "./tier.js"
-import { planner, REFACTOR, REQUIREMENTS, REVIEW } from "../shared/steps.js"
+import { planner, REFACTOR, REQUIREMENTS } from "../shared/steps.js"
+
+// Kept on the published feature entry.
+export { answerReviewQuestions, collecting, fixNits } from "../shared/steps.js"
 
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 export const triage = (base: string): Promise<void> =>
@@ -23,45 +26,6 @@ export const answerProductQuestions = (): Promise<void> =>
     acceptClean: true,
   })
 
-/** Answer every `question` note inline in `.gtd/REVIEW.md`. */
-export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<void> =>
-  t.agentWithSkills("review.answer-review-questions", t.buildReviewAnswerQuestionsPrompt(notes), {
-    label: "Answering your questions",
-    file: REVIEW,
-    mode: "review",
-    model: planner(),
-    system: t.reviewerSystem(),
-  })
-
-/** Fix every `nit` note in one turn. */
-export const fixNits = (
-  notes: readonly t.NoteInput[],
-  access?: ScopeAccess,
-  rules?: string,
-): Promise<void> => {
-  const fixing = (name: string): Promise<void> =>
-    t.agentWithSkills(name, t.buildReviewFixNitsPrompt(notes, rules), {
-      label: "Fixing your nits",
-      file: REVIEW,
-      model: planner(),
-      system: t.reviewerSystem(),
-    })
-  return access === undefined
-    ? fixing("review.fix.nits.fixing")
-    : scope({ name: "review.fix.nits", access }, () => fixing("fixing"))
-}
-
-/** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
-export const collecting = (capture: string, round?: CollectRound): Promise<void> =>
-  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture, undefined, round), {
-    label: "Collecting your feedback",
-    file: REQUIREMENTS,
-    mode: "qa",
-    model: planner(),
-    system: t.reviewerSystem(),
-    allowEmpty: true,
-  })
-
 /** Turn the refactor review round `capture` describes into `.gtd/REFACTOR.md`, or change nothing. */
 export const refactorCollecting = (
   capture: string,

package/src/workflows/fix/fix.feature

@@ -1,8 +1,7 @@
-Feature: fix fixes the notes review hands it
+Feature: fix fixes the notes a hand-off leaves 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.
+  A hand-off is `.gtd/REVIEW.md` with the human's notes beside the reviewer's
+  own `.gtd/REVIEW.orig.md`; `gtd door fix` picks both up.
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
@@ -13,10 +12,8 @@ Feature: fix fixes the notes review hands it
       """
     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:
+  Scenario: a handed-off note is fixed, and both review files are removed
+    Given a file ".gtd/REVIEW.orig.md" with:
       """
       # Review: abc1234
 
@@ -27,11 +24,7 @@ Feature: fix fixes the notes review hands it
       - [ ] ./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:
+    And a file ".gtd/REVIEW.md" with:
       """
       # Review: abc1234
 
@@ -42,21 +35,27 @@ Feature: fix fixes the notes review hands it
       - [ ] ./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"
+    And the working tree is committed as "chore: hand off a review"
+    And step "build.health.check" changes nothing
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
 
-    Given step "notes.fixing" writes "src/calc.ts" with:
+      - [ ] ./src/calc.ts#1-1
+        new add function
+      """
+    And 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.
+    # The fix goes to its own review, which the scripted reviewer writes afresh.
     When the process is driven
     Then the process rests at "build.review.await-review"
     And the commit subjects end with:

package/src/workflows/index.ts

@@ -32,7 +32,7 @@ export {
   type BuildTailOptions,
   type FeedbackTarget,
   type ReviewOutcome,
-} from "./feature/review.js"
+} from "./shared/review.js"
 export * from "./feature/feature.js"
 export { base, review, reviewFlow } from "./review/review.js"
 export { fix, fixFlow, fixReviewNotes } from "./fix/fix.js"

package/src/workflows/review/review-door.feature

@@ -0,0 +1,149 @@
+@inmem
+Feature: the review door fixes its notes in the same process
+
+  `gtd door review` runs the feature's review over everything since its base:
+  the triaged quality lap writes `.gtd/REVIEW.md`, the human answers each note,
+  and what they ask for is fixed in place under the health loop before the
+  review comes back. A sign-off ends the process; nothing is left for `fix`.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    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 step "review-gate.check" changes nothing
+    And step "build.health.check" changes nothing
+    And step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## add has no test
+
+      Add a test for add.
+      """
+    And step "build.quality.sorting" runs its script
+    And judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"design","p":0.9}]
+      """
+    And step "build.review.composing" runs its script
+    And step "build.review.closing" runs its script
+
+  Scenario: the review is composed from the lap's notes, with answer boxes
+    When gtd opens door "review" with "HEAD~1"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And the commit subjects end with:
+      """
+      gtd(human): review-gate.check
+      gtd(check): review-gate.check → 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
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## add has no test
+
+      Add a test for add.
+
+      Tick exactly one:
+
+      - [ ] fix as suggested
+      - [ ] won't fix
+      - [ ] _your answer_
+      """
+
+  Scenario: a won't-fix signs off, and no review is left for fix
+    When gtd opens door "review" with "HEAD~1"
+    And the process is driven
+    And the text "- [ ] won't fix" in ".gtd/REVIEW.md" is replaced with "- [x] won't fix"
+    And gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    And ".gtd/REVIEW.md" does not exist
+    And ".gtd/REVIEW.orig.md" does not exist
+
+  Scenario: a note ticked fix as suggested is fixed in place, then reviewed again
+    Given step "build.review.fix.nits.fixing" writes "src/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      """
+    When gtd opens door "review" with "HEAD~1"
+    And the process is driven
+    And the text "- [ ] fix as suggested" in ".gtd/REVIEW.md" is replaced with "- [x] fix as suggested"
+    And gtd lands
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And the commit subjects end with:
+      """
+      gtd(human): build.review.await-review → build.review.fix.nits.fixing
+      gtd(agent): build.review.fix.nits.fixing → build.health.check
+      gtd(check): build.health.check → build.review.closing
+      gtd(check): build.review.closing → build.review.composing
+      gtd(check): build.review.composing → build.review.await-review
+      """
+    And ".gtd/REVIEW.md" contains "## Fixed from your notes"
+    And "src/calc.test.ts" contains "adds"
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    And ".gtd/REVIEW.md" does not exist
+    And ".gtd/REVIEW.orig.md" does not exist
+
+  Scenario: an own answer asking for a change is fixed in place, then reviewed again
+    Given judge step "build.review.triage" answers:
+      """
+      [{"id":"answer-1","answer":"edit","p":0.9}]
+      """
+    And step "build.review.collecting" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Test add with negatives
+
+      add(-1, -2) returns -3.
+      """
+    And step "feedback.fixing" is prompted with ".gtd/REQUIREMENTS.md"
+    And step "feedback.fixing" writes "src/calc.test.ts" with:
+      """
+      it("adds negatives", () => {})
+      """
+    And step "re-unwind" runs its script
+    And step "feedback.closing" runs its script
+    When gtd opens door "review" with "HEAD~1"
+    And the process is driven
+    And the text "- [ ] _your answer_" in ".gtd/REVIEW.md" is replaced with "- [x] test negatives too"
+    And gtd lands
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    And the commit subjects end with:
+      """
+      gtd(human): build.review.await-review → build.review.triage
+      gtd(judge): build.review.triage → build.review.closing
+      gtd(check): build.review.closing → build.review.collecting
+      gtd(agent): build.review.collecting → re-unwind
+      gtd(check): re-unwind → feedback.fixing
+      gtd(agent): feedback.fixing → feedback.closing
+      gtd(check): feedback.closing → build.health.check
+      gtd(check): build.health.check → 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
+      """
+    And ".gtd/REQUIREMENTS.md" does not exist
+    And "src/calc.test.ts" contains "adds negatives"
+    And ".gtd/REVIEW.md" does not contain "test negatives too"
+
+  Scenario: a leftover requirements file is refused before any step
+    Given a file ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+      """
+    And the working tree is committed as "chore: leftover requirements"
+    Then opening door "review" is refused with ".gtd/REQUIREMENTS.md is left over"

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { runsItsScript, testRepo, type TestRepo } from "../../testkit/index.js"
+import { testRepo } from "../../testkit/index.js"
 import { CONFIG_SCAFFOLD } from "../../install/index.js"
 import { reviewDoc } from "../shared/config.fixture.js"
 import { base } from "./review.js"
@@ -7,79 +7,7 @@ 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,

package/src/workflows/review/review.ts

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

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

@@ -9,7 +9,7 @@ import {
 } from "../../flows/index.js"
 import {
   buildTail,
-  review,
+  humanReview,
   reUnwind,
   severityOf,
   type BuildTailOptions,
@@ -17,8 +17,7 @@ import {
 } from "./review.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as bundled from "../index.js"
-import type * as featureEntry from "./index.js"
-import { fixtureContext } from "../shared/text.fixture.js"
+import { fixtureContext } from "./text.fixture.js"
 import { toRequest } from "../../judges/index.js"
 
 afterEach(() => installContext(undefined))
@@ -155,7 +154,7 @@ const drive = async (d: Drive): Promise<Run> => {
   installContext(context)
   let result: ReviewOutcome | "stopped"
   try {
-    result = await review("base", undefined, {
+    result = await humanReview("base", undefined, {
       ...d.options,
       ...(d.guarded ? { guard: () => void log.push("guard") } : {}),
     })
@@ -975,11 +974,8 @@ describe("BuildTailOptions.lensBase", () => {
   })
 })
 
-// pins the public re-exports from the feature entry point and the published workflows entry
+// pins the public re-exports from the published workflows entry
 export type _PublicBuildTailOptions = [
-  featureEntry.BuildTailOptions,
-  featureEntry.FeedbackTarget,
-  featureEntry.ReviewRange,
   bundled.BuildTailOptions,
   bundled.FeedbackTarget,
   bundled.ReviewRange,

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

@@ -16,20 +16,22 @@ import {
 } from "../../flows/index.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
-import { guarded, healthy, type EscalationCount } from "../shared/health.js"
-import { NO_FINDINGS, type LensReport } from "../shared/lenses.js"
+import { guarded, healthy, type EscalationCount } from "./health.js"
+import { NO_FINDINGS, type LensReport } from "./lenses.js"
 import {
+  answerReviewQuestions,
   awaitReview,
+  collecting,
   fixCheck,
+  fixNits,
   fixRisks,
   QUALITY,
   REQUIREMENTS,
   REVIEW,
   reviewMissing,
-} from "../shared/steps.js"
-import { closeReview, isOptionalObject, tail, type TailOptions } from "../shared/tail.js"
-import * as t from "../shared/text.js"
-import { answerReviewQuestions, collecting, fixNits } from "./steps.js"
+} from "./steps.js"
+import { closeReview, isOptionalObject, tail, type TailOptions } from "./tail.js"
+import * as t from "./text.js"
 
 export type { ReviewOutcome } from "../../workflow-kit/index.js"
 
@@ -200,10 +202,11 @@ const composing = (
  * 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
  * may comment. A fix joins the nit batch, a won't-fix is dropped, and an own
- * answer or comment is judged: edits go to another planning lap, questions
- * are answered in place, nits fixed in one batch, praise dropped.
+ * answer or comment is judged: edits end the review as `feedback` for the
+ * caller to build, questions are answered in place, nits fixed in one batch,
+ * praise dropped.
  */
-export const review = (
+export const humanReview = (
   base: string,
   escalations: EscalationCount = { rounds: 0 },
   options: Omit<BuildTailOptions, "fixFirst" | "green"> = {},
@@ -316,7 +319,7 @@ export function buildTail(
     )
   }
   const [base, form] = options
-  return tail((escalations, report) => review(base, escalations, { ...form, report }), {
+  return tail((escalations, report) => humanReview(base, escalations, { ...form, report }), {
     ...form,
     triage: true,
   })