@pmelab/gtd 39.0.0 → 41.0.0

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:
       """

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

@@ -4,7 +4,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
   After a refactor-first judgment the refactor is built, quality-lapped and
   reviewed in its own slice. Review edits re-run the refactor, never the design;
   the feature slice that follows is quality-lapped from the refactor's
-  sign-off, with no feature review. The flags are pinned so the per-flag test runs never move it off
+  sign-off, then reviewed. The flags are pinned so the per-flag test runs never move it off
   its path.
 
   Background:
@@ -428,7 +428,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       Then the process rests at "refactor.build.review.await-review"
       When gtd lands
       And the process is driven
-      Then the process rests at "idle"
+      Then the process rests at "build.review.reviewing"
 
     Scenario: a question answered at the refactor review reaches the re-derived package as ### Answered Questions
       When the process is driven
@@ -727,7 +727,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       When gtd lands
       And the process is driven
-      Then the process rests at "idle"
+      Then the process rests at "build.review.reviewing"
       And "src/calc.ts" contains "subtract"
 
     Scenario: a praise-only one-shot footnote signs off and the feature slice follows
@@ -769,7 +769,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       When gtd lands
       And the process is driven
-      Then the process rests at "idle"
+      Then the process rests at "build.review.reviewing"
       And "src/calc.ts" contains "subtract"
 
     Scenario: a one-shot footnote judged edit that collecting leaves out refuses naming its anchor
@@ -1084,7 +1084,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       When gtd lands
       And the process is driven
-      Then the process rests at "idle"
+      Then the process rests at "build.review.reviewing"
       And "src/calc.ts" contains "subtract"
 
     Scenario: a praise-only refactor review still signs off and the feature slice follows
@@ -1119,7 +1119,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       When gtd lands
       And the process is driven
-      Then the process rests at "idle"
+      Then the process rests at "build.review.reviewing"
       And "src/calc.ts" contains "subtract"
 
     Scenario: a nit fix in the refactor slice that changes a non-stray is refused, though a glob stray widens the write access
@@ -1309,11 +1309,11 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       And the resting step's content contains the hash of the commit "gtd(check): refactor.build.review.closing → implement.building"
       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 the commit subjects end with:
         """
         gtd(check): implement.closing → build.quality.correctness.reviewing
-        gtd(agent): build.quality.correctness.reviewing → idle
+        gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
         """
 
   Rule: a refactor package never carries a test file, and demoted headings stop at ######