@pmelab/gtd 38.2.0 → 40.0.0

package/src/cli/Metrics.ts

@@ -45,6 +45,8 @@ export interface Metrics {
     }
   }
   readonly findings: { readonly total: number; readonly byLens: Readonly<Record<string, number>> }
+  /** Keyed by the re-check's full step name, from its subject: the mark's value is scope-relative. */
+  readonly flaky: { readonly total: number; readonly byStep: Readonly<Record<string, number>> }
 }
 
 type Phase = keyof Metrics["cost"]["byPhase"]
@@ -87,6 +89,7 @@ interface Tally {
   readonly byPhase: Record<Phase, number>
   readonly doubleWork: { naive: number; rebuild: number }
   readonly byLens: Record<string, number>
+  readonly flaky: Record<string, number>
 }
 
 const emptyTally = (): Tally => ({
@@ -96,6 +99,7 @@ const emptyTally = (): Tally => ({
   byPhase: { naive: 0, refactor: 0, implement: 0, other: 0 },
   doubleWork: { naive: 0, rebuild: 0 },
   byLens: record(),
+  flaky: record(),
 })
 
 const sum = (record: Readonly<Record<string, number>>): number =>
@@ -116,6 +120,7 @@ const finish = (t: Tally): Metrics => ({
     },
   },
   findings: { total: sum(t.byLens), byLens: t.byLens },
+  flaky: { total: sum(t.flaky), byStep: t.flaky },
 })
 
 /** The open slice: its naive cost so far, and whether its implement turns rebuild it. */
@@ -186,6 +191,7 @@ export const processMetrics = (commits: readonly MetricCommit[]): Metrics => {
       add(t.continuations, at.replace(CONTINUE, "$1"), 1)
     const lens = LENS.exec(at)?.[1]
     if (lens !== undefined && commit.findings > 0) add(t.byLens, lens, commit.findings)
+    if (message.marks.some((m) => m.name === "flaky")) add(t.flaky, at, 1)
     tallyDecision(t, open, at, subject.to)
   }
   return finish(t)
@@ -202,6 +208,7 @@ export const totalMetrics = (all: readonly Metrics[]): Metrics & { readonly proc
     t.doubleWork.naive += m.cost.doubleWork.naive
     t.doubleWork.rebuild += m.cost.doubleWork.rebuild
     for (const [k, v] of Object.entries(m.findings.byLens)) add(t.byLens, k, v)
+    for (const [k, v] of Object.entries(m.flaky.byStep)) add(t.flaky, k, v)
   }
   return { processes: all.length, ...finish(t) }
 }
@@ -257,6 +264,7 @@ const line = (label: string, m: Metrics): string => {
     `${continued} continuations${continued > 0 ? ` (${listed(m.continuations)})` : ""}`,
     `cost ${cost.total} (${listed(cost.byPhase)}; by model ${listed(cost.byModel) || "-"}), double work ${cost.doubleWork.total}`,
     `${m.findings.total} findings${m.findings.total > 0 ? ` (${listed(m.findings.byLens)})` : ""}`,
+    `${m.flaky.total} flaky${m.flaky.total > 0 ? ` (${listed(m.flaky.byStep)})` : ""}`,
   ].join("; ")
 }
 

package/src/workflow-kit/health.ts

@@ -44,16 +44,24 @@ export interface Health {
   /** Shared with other callers in the same run of red checks. */
   readonly escalations: EscalationCount
   readonly escalation: EscalationSteps
+  /** Runs the suite once more before a person is asked; `true` ends the loop as if `check` had passed. */
+  readonly recheck?: () => Promise<boolean>
 }
 
 // check() stamps the report with the commit it ran at, so equal failures differ there.
 const STAMP = /\n<!-- gtd check [0-9a-f]+ -->\n?$/
 const stripStamp = (text: string): string => text.replace(STAMP, "\n")
 
+/** `true` when the re-check passed, else the red re-check's report — the one the escalation describes. */
+const recheckReport = async (health: Health): Promise<true | string | undefined> => {
+  if (health.recheck === undefined) return undefined
+  return (await health.recheck()) || stripStamp(read(health.report) ?? "")
+}
+
 /**
  * Loop until the suite is green: check, and on red run `fix` — escalating
  * first once `fixCap` fixes are spent, or `sameFailure` calls the failure
- * identical to the previous round's.
+ * identical to the previous round's, unless `recheck` passes.
  */
 export const healthy = async (fix: () => Promise<void>, health: Health): Promise<void> => {
   let fixes = health.fixesSoFar ?? 0
@@ -67,6 +75,12 @@ export const healthy = async (fix: () => Promise<void>, health: Health): Promise
     const stuck = previous !== undefined && (await health.sameFailure(previous, current))
     previous = current
     if (stuck || fixes >= health.fixCap) {
+      const rechecked = await recheckReport(health)
+      if (rechecked === true) {
+        health.escalations.rounds = 0
+        return
+      }
+      previous = rechecked ?? previous
       await escalation(health.escalations, health.escalation)
       fixes = 0
     }

package/src/workflows/cleanup/cleanup.test.ts

@@ -160,6 +160,7 @@ describe("the cleanup guard over every later agent turn", () => {
         "build.health.check": (_, r) => {
           if (!stopped) r.write(FEEDBACK, `failing ${runs++}\n`)
         },
+        "build.health.recheck": (_, r) => r.write(FEEDBACK, `failing ${runs++}\n`),
         "build.health.describe": () => undefined,
         "build.health.judge": () => '[{"id":"verdict","answer":"progress","p":0.9}]',
         "build.fix": (_, r) => r.write("src/other.ts", `export const n = ${runs}\n`),
@@ -176,6 +177,7 @@ describe("the cleanup guard over every later agent turn", () => {
     await expect(
       driven(guarded("", NO_ACCESS), {
         "build.health.check": (_, r) => r.write(FEEDBACK, `failing ${runs++}\n`),
+        "build.health.recheck": (_, r) => r.write(FEEDBACK, `failing ${runs++}\n`),
         "build.health.judge": () => '[{"id":"verdict","answer":"progress","p":0.9}]',
         "build.fix": (_, r) => r.write("src/other.ts", `export const n = ${runs}\n`),
         "build.health.describe": (_, r) => r.write("src/b.ts", NAMED),

package/src/workflows/feature/coverage.feature

@@ -55,19 +55,19 @@ Feature: a feature is done only when every acceptance criterion has a passing te
     And the output of gtd "judge" contains "add is unchanged."
     And the output of gtd "judge" contains "[AC-1] subtracts"
 
-  Scenario: every ID covered ends the feature and marks the IDs it covers
+  Scenario: every ID covered moves on to the review and marks the IDs it covers
     Given judge step "implement.coverage" answers:
       """
       [{"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 "idle"
+    Then the process rests at "build.review.reviewing"
     And the commit subjects end with:
       """
       gtd(check): implement.applying → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → idle
+      gtd(check): implement.closing → build.review.reviewing
       """
     And the commit "gtd(judge): implement.coverage → implement.closing" has a body containing "Gtd-Mark: covers=AC-1"
     And the commit "gtd(judge): implement.coverage → implement.closing" has a body containing "Gtd-Mark: covers=AC-2"
@@ -132,7 +132,7 @@ Feature: a feature is done only when every acceptance criterion has a passing te
       """
     Then driving the process is refused with "criteria-frozen"
 
-  Scenario: overruling at the gate ends the feature, recording the uncovered IDs
+  Scenario: overruling at the gate moves on to the review, recording the uncovered IDs
     Given judge step "implement.coverage" answers:
       """
       [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-2","answer":"no","p":0.9}]
@@ -144,7 +144,7 @@ Feature: a feature is done only when every acceptance criterion has a passing te
       """
     And step "implement.uncovered" changes nothing
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And the commit "gtd(human): implement.uncovered → implement.closing" has a body containing "Gtd-Mark: covers=AC-1"
     And the commit "gtd(human): implement.uncovered → implement.closing" has a body containing "Gtd-Mark: uncovered=AC-2"
 

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import type { Change } from "../../flows/index.js"
-import { criteriaOf, criterionIds, statedCriteria } from "./criteria.js"
+import { criteriaOf, criterionIds, statedCriteria, unstableIds } from "./criteria.js"
 
 const added = (path: string, after: string): Change => ({
   path,
@@ -120,3 +120,22 @@ describe("criterionIds", () => {
     expect(criterionIds(requirements, { except: ["AC-1", "AC-3"] })).toEqual(["AC-2", "AC-4"])
   })
 })
+
+describe("unstableIds", () => {
+  const ids = { closed: ["AC-1", "AC-3"], used: ["AC-1", "AC-2", "AC-3"] }
+
+  it("accepts built IDs kept or dropped and new ones numbered above all handed out", () => {
+    expect(unstableIds(["AC-3", "AC-4", "AC-7"], ids)).toBeUndefined()
+    expect(unstableIds([], ids)).toBeUndefined()
+  })
+
+  it("names a new ID that reuses a number handed out before, even a narrowed-away one", () => {
+    expect(unstableIds(["AC-1", "AC-2", "AC-3"], ids)).toMatch(
+      /^numbers AC-2 at or below AC-3, .* from AC-4$/,
+    )
+  })
+
+  it("names every reused ID", () => {
+    expect(unstableIds(["AC-0", "AC-2"], ids)).toMatch(/^numbers AC-0, AC-2 at or below AC-3/)
+  })
+})

package/src/workflows/feature/criteria.ts

@@ -151,6 +151,30 @@ export const requireCriteria = (file: string): void => {
   )
 }
 
+/** The IDs a review's feedback lap must respect. */
+export interface StableIds {
+  /** Listed when the build closed: each may stay, reworded or not, or go. */
+  readonly closed: readonly string[]
+  /** Every ID handed out so far: any other is numbered above all of them. */
+  readonly used: readonly string[]
+}
+
+const idNumber = (id: string): number => Number(id.slice("AC-".length))
+
+/** Why `listed` renumbers or reuses an earlier ID; `undefined` when it does neither. */
+export const unstableIds = (listed: readonly string[], ids: StableIds): string | undefined => {
+  const top = Math.max(0, ...ids.used.map(idNumber))
+  const reused = listed.filter((id) => !ids.closed.includes(id) && idNumber(id) <= top)
+  if (reused.length === 0) return undefined
+  return `numbers ${reused.join(", ")} at or below AC-${top}, an ID already handed out — keep a built criterion's ID (reword it in place when the review changes it), and number new ones from AC-${top + 1}`
+}
+
+/** Refuse criteria in `file` that renumber or reuse an earlier ID. */
+export const requireStableIds = (file: string, ids: StableIds): void => {
+  const why = unstableIds(criterionIds(read(file) ?? ""), ids)
+  if (why !== undefined) refuse(`gtd land: criteria-ids: ${file} ${why}`)
+}
+
 /** Refuse a turn that changed the acceptance criteria in `file`: after the design gate only another design lap may. */
 export const requireCriteriaFrozen = (file: string): void => {
   const change = changes().get(file)

package/src/workflows/feature/fast-path.feature

@@ -3,7 +3,7 @@ Feature: a trivial change takes the same few beats at either risk tier
 
   With GTD_FLAG_RISK_TIER on, a one-line copy fix goes
   from idle through the naive pass, the seam judge's land, the applied pass and
-  the quality lap back to idle. Low tier walks exactly the steps high does; only
+  the quality lap to the review gate. Low tier walks exactly the steps high does; only
   the summary differs.
 
   Background:
@@ -32,7 +32,7 @@ Feature: a trivial change takes the same few beats at either risk tier
       """
     And step "build.quality.correctness.reviewing" changes nothing
 
-  Scenario Outline: a one-line fix runs idle to idle with the same beats at either tier
+  Scenario Outline: a one-line fix runs from idle to the review gate with the same beats at either tier
     Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
       """
       # Requirements
@@ -64,7 +64,7 @@ Feature: a trivial change takes the same few beats at either risk tier
       """
     And step "implement.applying" runs its script
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And "src/greeting.ts" contains "Hello, world"
     And the commit subjects end with:
       """
@@ -80,7 +80,7 @@ Feature: a trivial change takes the same few beats at either risk tier
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → idle
+      gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
       """
     And the output of gtd "summary" <summary> "needs a human reviewer"
 

package/src/workflows/feature/feature.ts

@@ -9,13 +9,16 @@ import {
   slice,
   start,
 } from "../../flows/index.js"
-import { gate, healthy } from "../shared/health.js"
+import { gate, healthy, type EscalationCount } from "../shared/health.js"
 import { flagModeOn, shipped } from "../shared/options.js"
 import { FEEDBACK, fixCheck, QUALITY, REQUIREMENTS } from "../shared/steps.js"
 import { refusePendingHandOff, tail } from "../shared/tail.js"
 import * as t from "../shared/text.js"
 import {
+  criterionIds,
   requireCriteriaFrozen,
+  requireStableIds,
+  type StableIds,
   skipDesign,
   sliceIds,
   statedCriteria,
@@ -23,8 +26,8 @@ import {
   type StatedCriteria,
 } from "./criteria.js"
 import { design } from "./planning.js"
-import { buildTail, isCode, reUnwind, type ReviewOutcome } from "./review.js"
-import { closeOut, implement, seamBuild } from "./seam.js"
+import { buildTail, isCode, reUnwind, review, type ReviewOutcome } from "./review.js"
+import { implement, implementing, seamBuild } from "./seam.js"
 import { sliceCap, sliceCriteria, slicing } from "./slicing.js"
 import { recordRisk, riskTierOn, type RiskTier } from "./tier.js"
 
@@ -33,7 +36,9 @@ import { recordRisk, riskTierOn, type RiskTier } from "./tier.js"
 // green-baseline gate → design → per slice of the criteria, a naive pass,
 // judged with `flagMode` on: it lands as the implementation, or (refactoring
 // first when the judge asks) is built fresh from → the health loop → the
-// quality lap, and the episode ends back at `idle`. Human review is the `review` door's.
+// quality lap → after the last slice, human review of the whole change, which
+// signs off (the episode ends back at `idle`) or sends a design → implement
+// lap.
 
 /** Revert the sketch that started the process out of the working tree; its intent survives in history. */
 export const unwind = (): Promise<void> => {
@@ -52,40 +57,54 @@ export { reUnwind }
 export const buildFeature = async (firstBase: string): Promise<void> => {
   const tier = riskTierOn() ? recordRisk() : undefined
   const slices = await slicing()
+  // Every ID handed out, gathered before a later narrowing can drop one: none is ever reused.
+  const handedOut = new Set(listedIds())
   // A single slice keeps the unnumbered names and builds against every criterion.
   const one = slices.length === 1
+  // A steer may delete every criterion of a later slice: there is nothing to build there.
+  const built = (i: number): boolean => sliceIds(sliceCriteria(slices, i))?.length !== 0
   for (const i of slices.keys()) {
-    const more = i < slices.length - 1
-    const criteria = sliceCriteria(slices, i)
-    // A steer may have deleted every criterion of a later slice: nothing to build.
-    if (sliceIds(criteria)?.length === 0) {
-      if (!more) await closeOut()
-      continue
-    }
+    if (!built(i)) continue
     const n = one ? "" : `-${i + 1}`
     await buildSlice(i === 0 ? firstBase : head(), {
       tier,
-      criteria,
+      criteria: sliceCriteria(slices, i),
       refactor: `refactor${n}`,
       feature: `feature${n}`,
-      more,
+      // A steer or a narrowing may empty every later slice.
+      more: () => slices.some((_, j) => j > i && built(j)),
+      // Every slice but the one is built unreviewed, so the review covers them all.
+      reviewBase: one ? undefined : firstBase,
+      handedOut,
     })
   }
 }
 
+const listedIds = (): readonly string[] => criterionIds(read(REQUIREMENTS) ?? "")
+
+const gather = (handedOut: Set<string>): readonly string[] => {
+  for (const id of listedIds()) handedOut.add(id)
+  return [...handedOut]
+}
+
 interface SliceBuild {
   readonly tier: RiskTier | undefined
   readonly criteria: CriteriaSlice | undefined
   readonly refactor: string
   readonly feature: string
-  readonly more: boolean
+  readonly more: () => boolean
+  /** Absent: the slice's own base. */
+  readonly reviewBase?: string | undefined
+  /** Every criterion ID handed out so far; the slice adds those a steer adds. */
+  readonly handedOut: Set<string>
 }
 
-/** A naive pass (judged only with `flagMode` on), then implement and the quality lap. */
+/** A naive pass (judged only with `flagMode` on), then implement and the quality lap; after the last slice, the review. */
 const buildSlice = async (sliceBase: string, build: SliceBuild): Promise<void> => {
   const seam = await seamBuild(sliceBase, { criteria: build.criteria, refactor: build.refactor })
+  const used = gather(build.handedOut)
   await slice(build.feature, async () => {
-    await implement({
+    const closed = await implementing({
       reference: seam.reference,
       tier: build.tier,
       afterRefactor: seam.refactored,
@@ -95,6 +114,8 @@ const buildSlice = async (sliceBase: string, build: SliceBuild): Promise<void> =
       base: build.criteria === undefined ? undefined : sliceBase,
       more: build.more,
     })
+    // Closing kept the criteria exactly when there is more to build, so this reads as it did.
+    const more = build.more()
     // A feature slice with no code beyond the carried-over tests: the refactor carried the
     // feature, so the lap covers the whole slice.
     const carried = seam.rebuild?.acceptance?.tests ?? []
@@ -103,14 +124,19 @@ const buildSlice = async (sliceBase: string, build: SliceBuild): Promise<void> =
       !changesSince(seam.base).some((c) => isCode(c.path) && !carried.includes(c.path))
         ? sliceBase
         : seam.base
-    // The criteria stay in the tree for the next slice; no quality fix may move them.
-    const guard = build.more ? () => requireCriteriaFrozen(REQUIREMENTS) : undefined
-    await tail(settleQuality, { green: true, lensBase: base, guard, guardRests: false })
+    if (more) {
+      // The criteria stay in the tree for the next slice; no quality fix may move them.
+      const guard = () => requireCriteriaFrozen(REQUIREMENTS)
+      await tail(settleQuality, { green: true, lensBase: base, guard, guardRests: false })
+      return
+    }
+    const reviewBase = build.reviewBase ?? base
+    await featureFeedback(await reviewedTail(reviewBase, base), base, { closed, used })
   })
 }
 
-// The lap is feature's last look: findings the fix cap left must not end the process, nor reach
-// the next one's lap, which appends to the file. Empty counts as resolved, as the lap reads it.
+// The lap's findings the fix cap left must not reach the review, nor the next process's lap,
+// which appends to the file. Empty counts as resolved, as the lap reads it.
 const settleQuality = async (): Promise<void> => {
   let rested = false
   while ((read(QUALITY) ?? "").length > 0) {
@@ -121,10 +147,44 @@ const settleQuality = async (): Promise<void> => {
       file: QUALITY,
     })
   }
-  // The person may have fixed code by hand there; nothing else checks it before idle.
+  // The person may have fixed code by hand there; nothing else checks it before the review.
   if (rested) await healthy(() => fixCheck())
 }
 
+/** The quality lap, then the human review since `base`. */
+const reviewedTail = (base: string, lensBase: string, lap?: "feedback"): Promise<ReviewOutcome> =>
+  tail(
+    async (escalations: EscalationCount) => {
+      await settleQuality()
+      return review(base, escalations, { lap })
+    },
+    { green: true, lensBase },
+  )
+
+// seam.naive / seam.judge never run on a feedback lap: its design → implement is built unjudged
+// and unrefactored, held to every criterion's coverage since the process start.
+const featureFeedback = async (
+  first: ReviewOutcome,
+  lensBase: string,
+  ids: StableIds,
+): Promise<void> => {
+  let outcome = first
+  let closed = ids.closed
+  const handedOut = new Set([...ids.used, ...ids.closed])
+  while (outcome.verdict === "feedback") {
+    await reUnwind(outcome)
+    const lap = { closed, used: [...handedOut] }
+    // Gathered every round, so an ID one round adds and the next drops is never reused.
+    await design(outcome.base, () => {
+      requireStableIds(REQUIREMENTS, lap)
+      gather(handedOut)
+    })
+    const tier = riskTierOn() ? recordRisk() : undefined
+    closed = await implementing({ tier, amend: true })
+    outcome = await reviewedTail(outcome.base, lensBase, "feedback")
+  }
+}
+
 /** Design — skipped when the sketch's own criteria are judged clear — then `buildFeature`. */
 export const planAndBuild = async (firstBase: string, stated?: StatedCriteria): Promise<void> => {
   // GTD_FLAG_RISK_TIER: the tier is proposed at triage and set at the design gate, so no skip.

package/src/workflows/feature/flag-mode.feature

@@ -67,7 +67,7 @@ Feature: flag mode off lands the naive pass with no release flag, seam judge or
       """
     And step "build.quality.correctness.reviewing" changes nothing
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "subtract"
     And "src/calc.test.ts" contains "[AC-1] subtracts"
     And the commit subjects end with:
@@ -85,5 +85,5 @@ Feature: flag mode off lands the naive pass with no release flag, seam judge or
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → idle
+      gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
       """

package/src/workflows/feature/one-step-land.feature

@@ -5,7 +5,7 @@ Feature: a naive pass the judge rules land is itself the implementation
   With GTD_FLAG_RISK_TIER off, a naive pass that
   edits an existing source file is judged land: the process skips the approval
   gate and any refactor, applies the kept pass as it is — no build turn — and
-  runs the health loop and quality back to idle, with no review. The flag is pinned here so the per-flag test runs never
+  runs the health loop and quality lap to the feature review. The flag is pinned here so the per-flag test runs never
   move it off this path.
 
   Background:
@@ -62,9 +62,9 @@ Feature: a naive pass the judge rules land is itself the implementation
       """
     And step "build.quality.correctness.reviewing" changes nothing
 
-  Scenario: a land judgment applies the naive pass and runs idle to idle with no rebuild
+  Scenario: a land judgment applies the naive pass and runs from idle to the review gate with no rebuild
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And "src/greeting.ts" contains "Hello, world"
     And "src/acceptance.test.ts" contains "[AC-1] holds"
     And the commit subjects end with:
@@ -81,7 +81,7 @@ Feature: a naive pass the judge rules land is itself the implementation
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → idle
+      gtd(agent): build.quality.correctness.reviewing → 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/planning.ts

@@ -25,13 +25,14 @@ const noteGate = async (file: string, answer: () => Promise<void>): Promise<bool
   return true
 }
 
-/** Triage the sketch since `base` into requirements, until no product question is open. */
-export const design = (base: string): Promise<void> =>
+/** Triage the sketch since `base` into requirements, until no product question is open; `guard` holds every round's criteria. */
+export const design = (base: string, guard?: () => void): Promise<void> =>
   scope("design", async () => {
     do {
       await triage(base)
       requireProgress(REQUIREMENTS)
       requireReplies(REQUIREMENTS)
       requireCriteria(REQUIREMENTS)
+      guard?.()
     } while (await noteGate(REQUIREMENTS, answerProductQuestions))
   })

package/src/workflows/feature/quality-unresolved.feature

@@ -1,9 +1,9 @@
 @inmem
-Feature: quality findings left unresolved hold a feature process short of idle
+Feature: quality findings left unresolved hold a feature process short of its review
 
-  The quality lap is the last look `feature` takes. When the fix cap leaves
-  `.gtd/QUALITY.md` behind, the process rests for a person instead of ending
-  with findings nobody acted on.
+  When the quality lap's fix cap leaves `.gtd/QUALITY.md` behind, the process
+  rests for a person instead of handing findings nobody acted on to the
+  human review.
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
@@ -97,10 +97,10 @@ Feature: quality findings left unresolved hold a feature process short of idle
     And step "build.health.check" changes nothing
     When gtd lands
     And the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And the commit subjects end with:
       """
       gtd(check): build.health.check → build.quality-unresolved
       gtd(human): build.quality-unresolved → build.health.check
-      gtd(check): build.health.check → idle
+      gtd(check): build.health.check → build.review.reviewing
       """

package/src/workflows/feature/refactor-absorbs.feature

@@ -42,7 +42,7 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       """
     And step "design.gate.answer" changes nothing
 
-  Scenario: a tests-only implement turn after a refactor that did it all reaches the quality lap and idle
+  Scenario: a tests-only implement turn after a refactor that did it all reaches the quality lap and the review
     Given step "seam.check" changes nothing
     And step "seam.naive" writes "src/acceptance.test.ts" with:
       """
@@ -113,7 +113,7 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
 
     Given step "build.quality.correctness.reviewing" changes nothing
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "subtract"
     And the commit subjects end with:
       """
@@ -123,7 +123,7 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → idle
+      gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
       """
     And the output lines of gtd "slices" start with:
       """

package/src/workflows/feature/refactor-first.feature

@@ -1,10 +1,10 @@
 # One SDLC path per file, so a changed path reds exactly one fixture — do not merge.
 @inmem
-Feature: a refactor-first judgment walks one fixed path to idle
+Feature: a refactor-first judgment walks one fixed path to the review gate
 
   With GTD_FLAG_RISK_TIER off, a naive pass touching
   an existing non-allowlisted file is ruled refactor-first, is refactored and
-  that refactor reviewed, and only then implemented, with no feature review. The flags are
+  that refactor reviewed, and only then implemented and brought to the feature review. The flags are
   pinned so the per-flag test runs never move it off its path.
 
   Background:
@@ -41,7 +41,7 @@ Feature: a refactor-first judgment walks one fixed path to idle
       """
     And step "design.gate.answer" changes nothing
 
-  Scenario: a refactor-first judgment runs refactor, its review, implement and review to idle
+  Scenario: a refactor-first judgment runs refactor, its review, implement and the quality lap to the feature review
     Given step "seam.check" changes nothing
     And step "seam.naive" writes "src/acceptance.test.ts" with:
       """
@@ -121,7 +121,7 @@ Feature: a refactor-first judgment walks one fixed path to idle
       [{"id":"AC-1","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "op(a, b, 1)"
     And "src/calc.ts" contains "subtract"
     And the commit subjects end with:
@@ -145,7 +145,7 @@ Feature: a refactor-first judgment walks one fixed path to idle
       gtd(agent): implement.building → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → idle
+      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/refactor-rebuild.feature

@@ -242,7 +242,7 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
       [{"id":"AC-1","answer":"yes","p":0.9}]
       """
     When the process is driven
-    Then the process rests at "idle"
+    Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "op(a, b, -1)"
     And "src/acceptance.test.ts" contains "[AC-1]"
     And ".gtd/REFACTOR-NOTE.md" does not exist
@@ -260,7 +260,7 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
       gtd(agent): implement.building → implement.health.check
       gtd(check): implement.health.check → implement.coverage
       gtd(judge): implement.coverage → implement.closing
-      gtd(check): implement.closing → idle
+      gtd(check): implement.closing → build.review.reviewing
       """
     And the output lines of gtd "slices" start with:
       """