@pmelab/gtd 33.0.0 → 34.0.0

package/src/workflows/feature/feature.ts

@@ -3,15 +3,16 @@ import {
   changesSince,
   head,
   human,
+  read,
   revertScript,
   run,
   slice,
   start,
 } from "../../flows/index.js"
-import { gate } from "../shared/health.js"
+import { gate, healthy } from "../shared/health.js"
 import { flagModeOn, shipped } from "../shared/options.js"
-import { FEEDBACK } from "../shared/steps.js"
-import { refusePendingHandOff } from "../shared/tail.js"
+import { FEEDBACK, fixCheck, QUALITY } from "../shared/steps.js"
+import { refusePendingHandOff, tail } from "../shared/tail.js"
 import * as t from "../shared/text.js"
 import { skipDesign, statedCriteria, type StatedCriteria } from "./criteria.js"
 import { design } from "./planning.js"
@@ -22,9 +23,8 @@ import { recordRisk, riskTierOn } from "./tier.js"
 // The ordinary start. Any change to the tree starts a process: `idle` →
 // `unwind` reverts the sketch (its intent survives in history) → a
 // green-baseline gate → design → a judged naive pass (refactoring first when
-// the judge asks; with `flagMode` off, neither) → implement → the quality lap
-// → human review, which signs off (the episode ends back at `idle`) or sends a
-// design → implement lap.
+// the judge asks; with `flagMode` off, neither) → implement → the quality lap,
+// and the episode ends back at `idle`. Human review is the `review` door's.
 
 /** Revert the sketch that started the process out of the working tree; its intent survives in history. */
 export const unwind = (): Promise<void> => {
@@ -36,9 +36,7 @@ export const unwind = (): Promise<void> => {
 
 export { reUnwind }
 
-// seam.naive / seam.judge run once: a feedback lap is design → implement on every verdict, so a
-// seam a re-plan turns up is built unjudged and unrefactored.
-/** A judged naive pass (none with `flagMode` off), then implement and review until a review round signs off; design must have run since `firstBase`. */
+/** A judged naive pass (none with `flagMode` off), then implement and the quality lap; design must have run since `firstBase`. */
 export const buildFeature = async (firstBase: string): Promise<void> => {
   const tier = riskTierOn() ? recordRisk() : undefined
   const seam: Omit<SeamOutcome, "reference"> & { reference?: string } = flagModeOn()
@@ -46,15 +44,31 @@ export const buildFeature = async (firstBase: string): Promise<void> => {
     : { base: firstBase }
   await slice("feature", async () => {
     await implement({ reference: seam.reference, tier, afterRefactor: seam.refactored })
-    // An empty feature slice: the refactor carried the feature, so review the whole change.
+    // An empty feature slice: the refactor carried the feature, so the lap covers the whole change.
     const base =
       seam.refactored === true && !changesSince(seam.base).some((c) => isCode(c.path))
         ? firstBase
         : seam.base
-    await featureFeedback(await buildTail(base, { green: true, lensBase: base }), base)
+    await tail(settleQuality, { green: true, lensBase: base })
   })
 }
 
+// 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.
+const settleQuality = async (): Promise<void> => {
+  let rested = false
+  while ((read(QUALITY) ?? "").length > 0) {
+    rested = true
+    await human("quality-unresolved", {
+      message: t.qualityUnresolvedMessage(),
+      label: "Quality findings left unresolved",
+      file: QUALITY,
+    })
+  }
+  // The person may have fixed code by hand there; nothing else checks it before idle.
+  if (rested) await healthy(() => fixCheck())
+}
+
 /** 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.
@@ -62,20 +76,19 @@ export const planAndBuild = async (firstBase: string, stated?: StatedCriteria):
   await buildFeature(firstBase)
 }
 
-const featureFeedback = async (first: ReviewOutcome, lensBase?: string): Promise<void> => {
+// seam.naive / seam.judge never run here: a re-plan's seam is built unjudged and unrefactored.
+/** After a tail that skipped planning: stop on sign-off, re-plan on feedback. Opens no slice: slices cannot nest. */
+export const afterTail = async (first: ReviewOutcome): Promise<void> => {
   let outcome = first
   while (outcome.verdict === "feedback") {
     await reUnwind(outcome)
     await design(outcome.base)
     const tier = riskTierOn() ? recordRisk() : undefined
     await implement({ tier, amend: true })
-    outcome = await buildTail(outcome.base, { green: true, lap: "feedback", lensBase })
+    outcome = await buildTail(outcome.base, { green: true, lap: "feedback" })
   }
 }
 
-/** After a tail that skipped planning: stop on sign-off, re-plan on feedback. Opens no slice: slices cannot nest. */
-export const afterTail = (outcome: ReviewOutcome): Promise<void> => featureFeedback(outcome)
-
 /** An ordinary start: wait at `idle`, unwind the sketch, check the baseline, then plan and build. */
 export const ordinaryStart = async (): Promise<void> => {
   await human("idle", { message: t.idleMessage(), label: "Idle", file: ".gtd/TODO.md" })

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

@@ -58,7 +58,7 @@ Feature: flag mode off builds a feature with no release flag, seam judge or refa
     And step "implement.closing" runs its script
     And step "build.quality.correctness.reviewing" changes nothing
     When the process is driven
-    Then the process rests at "build.review.reviewing"
+    Then the process rests at "idle"
     And "src/calc.ts" contains "subtract"
     And the commit subjects end with:
       """
@@ -72,94 +72,5 @@ Feature: flag mode off builds a feature with no release flag, seam judge or refa
       gtd(agent): implement.building → implement.health.check
       gtd(check): implement.health.check → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
+      gtd(agent): build.quality.correctness.reviewing → idle
       """
-
-  Scenario: flag mode off asks for no flag on a feedback lap either
-    Given step "implement.building" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      export const subtract = (a: number, b: number) => a - b
-      """
-    And step "implement.health.check" changes nothing
-    And step "implement.closing" runs its script
-    And step "build.quality.correctness.reviewing" changes nothing
-    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## calc
-
-      - [ ] ./src/calc.ts#2-2
-        new subtract function
-      """
-    When 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#2-2
-        new subtract function[^why]
-
-      [^why]:
-          - H: also export multiply
-      """
-    And step "build.review.collecting" writes ".gtd/REQUIREMENTS.md" with:
-      """
-      # Requirements
-
-      ## Concerns
-
-      ### Multiply
-
-      - Export `multiply()`.
-
-      ## Acceptance Criteria
-
-      - AC-1: the change behaves as described.
-      """
-    And step "build.review.collecting" writes ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## calc
-
-      - [ ] ./src/calc.ts#2-2
-        new subtract function[^why]
-
-      [^why]:
-          - H: also export multiply
-          - A: noted in the requirements.
-      """
-    When gtd lands
-    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#2-2
-        new subtract function
-      """
-    And step "build.review.closing" runs its script
-    And step "re-unwind" runs its script
-    And step "implement.building" is no longer scripted
-    When gtd lands
-    And the process is driven
-    Then the process rests at "implement.building"
-    And the resting step's content contains "Add no release flag — this project ships without release flags"
-    And the resting step's content does not contain "release flag the earlier lap added"
-    And no commit body contains "Gtd-Kept:"

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

@@ -4,8 +4,8 @@ Feature: a naive pass the judge rules land goes straight to implement with no se
 
   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, and runs implement, quality and
-  review back to idle. The flag is pinned here so the per-flag test runs never
+  gate and any refactor, and runs implement and quality
+  back to idle, with no review. The flag is pinned here so the per-flag test runs never
   move it off this path.
 
   Background:
@@ -60,35 +60,9 @@ Feature: a naive pass the judge rules land goes straight to implement with no se
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
     And step "build.quality.correctness.reviewing" changes nothing
-    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## greeting
-
-      - [ ] ./src/greeting.ts#1-1
-        typo fixed
-      """
-    And step "build.review.closing" runs its script
 
   Scenario: a land judgment runs idle to idle with no seam gate or refactor
     When the process is driven
-    Then the process rests at "build.review.await-review"
-    Given a file ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## greeting
-
-      - [x] ./src/greeting.ts#1-1
-        typo fixed
-      """
-    When gtd lands
-    And the process is driven
     Then the process rests at "idle"
     And "src/greeting.ts" contains "Hello, world!"
     And the commit subjects end with:
@@ -104,10 +78,7 @@ Feature: a naive pass the judge rules land goes straight to implement with no se
       gtd(agent): implement.building → implement.health.check
       gtd(check): implement.health.check → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
-      gtd(agent): build.review.reviewing → build.review.await-review
-      gtd(human): build.review.await-review → build.review.closing
-      gtd(check): build.review.closing → idle
+      gtd(agent): build.quality.correctness.reviewing → idle
       """
     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/quality-unresolved.feature

@@ -0,0 +1,96 @@
+@inmem
+Feature: quality findings left unresolved hold a feature process short of idle
+
+  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.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And an environment variable "GTD_FLAGMODE" set to "false"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract
+
+      subtract(a, b) returns the difference.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Concerns
+
+      ### Subtract
+
+      - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "implement.building" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      """
+    And step "implement.health.check" changes nothing
+    And step "implement.closing" runs its script
+
+  Scenario: findings the fix cap left unresolved rest at build.quality-unresolved
+    Given step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      - subtract has no test
+      """
+    And step "build.fix.quality.fixing" from now on changes nothing
+    And step "build.health.describe" writes ".gtd/ESCALATION.md" with:
+      """
+      # Escalation
+
+      The fix turn changed nothing.
+      """
+    When the process is driven
+    Then the process rests at "build.health.stop"
+    Given step "build.fix" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      // checked
+      """
+    And step "build.health.check" changes nothing
+    When gtd lands
+    And the process is driven
+    Then the process rests at "build.quality-unresolved"
+    And ".gtd/QUALITY.md" contains "subtract has no test"
+
+    When gtd lands
+    And the process is driven
+    Then the process rests at "build.quality-unresolved"
+
+    Given a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      // checked by hand
+      """
+    And the file ".gtd/QUALITY.md" is deleted
+    And step "build.health.check" changes nothing
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    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
+      """

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

@@ -1,16 +1,16 @@
 # One SDLC path per file, so a changed path reds exactly one fixture — do not merge.
 @inmem
-Feature: a refactor that carried the whole feature still gets a feature review
+Feature: a refactor that carried the whole feature still gets a quality lap over all of it
 
   With GTD_FLAG_RISK_TIER off, a refactor-first
   refactor can land everything the requirements ask for. The feature slice's
   implement turn then has nothing to author: its empty turn completes the
-  step, and with no code changed since the refactor the feature review covers
-  the whole change, refactor included.
+  step, and with no code changed since the refactor the feature slice's
+  quality lap covers the whole change, refactor included.
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
     And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
     And a file "src/calc.ts" with:
@@ -42,7 +42,7 @@ Feature: a refactor that carried the whole feature still gets a feature review
       """
     And step "design.gate.answer" changes nothing
 
-  Scenario: an empty implement turn after a refactor that did it all reaches review and idle
+  Scenario: an empty implement turn after a refactor that did it all reaches the quality lap and idle
     Given step "seam.check" changes nothing
     And step "seam.naive" writes "src/acceptance.test.ts" with:
       """
@@ -94,25 +94,14 @@ Feature: a refactor that carried the whole feature still gets a feature review
     And step "implement.building" changes nothing
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
-    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## calc
-
-      - [ ] ./src/calc.ts#1-2
-        subtract next to add
-      """
     When gtd lands
     And the process is driven
-    Then the process rests at "build.review.await-review"
+    Then the process rests at "build.quality.correctness.reviewing"
+    And the resting step's content contains the hash of the commit "feat: add calculator"
     And ".gtd/REQUIREMENTS.md" does not exist
 
-    Given step "build.review.closing" runs its script
-    When gtd lands
-    And the process is driven
+    Given step "build.quality.correctness.reviewing" changes nothing
+    When the process is driven
     Then the process rests at "idle"
     And "src/calc.ts" contains "subtract"
     And the commit subjects end with:
@@ -121,10 +110,8 @@ Feature: a refactor that carried the whole feature still gets a feature review
       gtd(check): refactor.build.review.closing → implement.building
       gtd(agent): implement.building → implement.health.check
       gtd(check): implement.health.check → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
-      gtd(agent): build.review.reviewing → build.review.await-review
-      gtd(human): build.review.await-review → build.review.closing
-      gtd(check): build.review.closing → idle
+      gtd(check): implement.closing → build.quality.correctness.reviewing
+      gtd(agent): build.quality.correctness.reviewing → idle
       """
     And the output lines of gtd "slices" start with:
       """

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

@@ -4,7 +4,7 @@ Feature: a refactor-first judgment walks one fixed path to idle
 
   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. The flags are
+  that refactor reviewed, and only then implemented, with no feature review. The flags are
   pinned so the per-flag test runs never move it off its path.
 
   Background:
@@ -95,18 +95,6 @@ Feature: a refactor-first judgment walks one fixed path to idle
       - [x] ./src/calc.ts#1-2
         add built on the shared op
       """
-    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## calc
-
-      - [ ] ./src/calc.ts#1-3
-        subtract built on the shared op
-      """
-    And step "build.review.closing" runs its script
     When gtd lands
     And the process is driven
     Then the process rests at "implement.building"
@@ -121,21 +109,6 @@ Feature: a refactor-first judgment walks one fixed path to idle
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
     When 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
-
-      - [x] ./src/calc.ts#1-3
-        subtract built on the shared op
-      """
-    When gtd lands
-    And the process is driven
     Then the process rests at "idle"
     And "src/calc.ts" contains "op(a, b, 1)"
     And "src/calc.ts" contains "subtract"
@@ -158,10 +131,7 @@ Feature: a refactor-first judgment walks one fixed path to idle
       gtd(check): refactor.build.review.closing → implement.building
       gtd(agent): implement.building → implement.health.check
       gtd(check): implement.health.check → implement.closing
-      gtd(check): implement.closing → build.review.reviewing
-      gtd(agent): build.review.reviewing → build.review.await-review
-      gtd(human): build.review.await-review → build.review.closing
-      gtd(check): build.review.closing → idle
+      gtd(check): implement.closing → idle
       """
     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:"