@pmelab/gtd 38.2.0 → 40.0.0

package/src/workflows/shared/health.ts

@@ -4,8 +4,10 @@ import {
   env,
   human,
   judge,
+  mark,
   numeric,
   vars,
+  type CheckOptions,
   type JudgeQuestion,
 } from "../../flows/index.js"
 import * as kit from "../../workflow-kit/index.js"
@@ -19,6 +21,24 @@ export const FIX_CAP = 3
 export const baseline = (name: string, label = "Checking the baseline"): Promise<boolean> =>
   check(name, env.testCommand ?? "", { report: FEEDBACK, label })
 
+/**
+ * Re-run a red check as step `name` before a person sees it. Green records
+ * `Gtd-Mark: flaky=<red>` on the re-check's landing and resolves `true`.
+ */
+export const recheck = async (
+  name: string,
+  red: string,
+  options: Pick<CheckOptions, "sweepOnGreen"> = {},
+): Promise<boolean> => {
+  const green = await check(name, env.testCommand ?? "", {
+    ...options,
+    report: FEEDBACK,
+    label: "Re-running checks",
+  })
+  if (green) mark("flaky", red)
+  return green
+}
+
 export type { EscalationCount } from "../../workflow-kit/index.js"
 
 const escalationSteps = (rules?: string): kit.EscalationSteps => ({
@@ -117,18 +137,24 @@ export interface HealthOptions {
   readonly rules?: string | undefined
 }
 
+// Swept only on green: an unresolved analysis survives every retry.
+const healthSweep = (options: HealthOptions): string[] => [
+  ESCALATION,
+  ...(options.sweepOnGreen ?? []),
+]
+
 const runSuite = (options: HealthOptions): Promise<boolean> =>
   check("health.check", env.testCommand ?? "", {
     report: FEEDBACK,
     label: "Running checks",
-    // Swept only on green: an unresolved analysis survives every retry.
-    sweepOnGreen: [ESCALATION, ...(options.sweepOnGreen ?? [])],
+    sweepOnGreen: healthSweep(options),
   })
 
 /**
  * Loop until the suite is green: check, and on red run `fix` — escalating
  * first once `FIX_CAP` fixes are spent, or a judge calls the failure
- * identical to the previous round's.
+ * identical to the previous round's. An escalation re-runs the suite once
+ * first; a green re-run ends the loop.
  */
 export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}): Promise<void> =>
   kit.healthy(guarded(fix, options.guard), {
@@ -138,6 +164,8 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
     fixesSoFar: options.fixesSoFar ?? 0,
     sameFailure,
     escalations: options.escalations ?? { rounds: 0 },
+    recheck: () =>
+      recheck("health.recheck", "health.check", { sweepOnGreen: healthSweep(options) }),
     escalation: guardedSteps(
       options.guard,
       options.describeGuard,
@@ -147,13 +175,14 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
   })
 
 /**
- * Hold the process at `<name>.blocked` until the suite is green. `guard` runs
+ * Hold the process at `<name>.blocked` until the suite is green, re-running a
+ * red check once as `<name>.recheck` before resting. `guard` runs
  * after each `blocked` landing only — never after a check, whose refusal would
  * re-run the same script forever.
  */
 export const gate = (name: string, message: string, guard?: Guard): Promise<void> =>
   kit.gate(
     name,
-    () => baseline("check"),
+    async () => (await baseline("check")) || recheck("recheck", `${name}.check`),
     guarded(() => human("blocked", { message, label: "Baseline is red", file: FEEDBACK }), guard),
   )

package/src/workflows/shared/recheck.feature

@@ -0,0 +1,60 @@
+@inmem
+Feature: a red check is re-run once before it reaches a person
+
+  Before the fix loop escalates, `healthy` re-runs the suite as
+  `health.recheck`. Green there ends the loop as if the check had passed, and
+  the re-check's landing records `Gtd-Mark: flaky=health.check`. Red again
+  escalates as before.
+
+  Background:
+    Given a gtd config with:
+      """
+      import { healthy } from "@pmelab/gtd/workflows"
+      import { agent, human } from "@pmelab/gtd/flows"
+
+      export const held = async () => {
+        await agent("first", "go")
+        await healthy(() => agent("fix", "go"))
+        await human("done")
+      }
+      export default held
+      """
+    And step "first" writes "src/a.ts" with:
+      """
+      export const a = 1
+      """
+    And step "health.check" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    And step "fix" deletes ".gtd/FEEDBACK.md"
+    And judge step "health.judge" answers:
+      """
+      [{"id":"verdict","answer":"progress","p":0.9}]
+      """
+
+  Scenario: a re-check that passes ends the loop without a person, recorded as flaky
+    Given step "health.recheck" deletes ".gtd/FEEDBACK.md"
+    When gtd starts workflow "held"
+    And the process is driven
+    Then the process rests at "done"
+    And the commit subjects end with:
+      """
+      gtd(agent): fix → health.check
+      gtd(check): health.check → health.judge
+      gtd(judge): health.judge → health.recheck
+      gtd(check): health.recheck → done
+      """
+    And the last commit body contains "Gtd-Mark: flaky=health.check"
+    And ".gtd/FEEDBACK.md" does not exist
+
+  Scenario: a re-check that stays red escalates, with nothing recorded as flaky
+    Given step "health.recheck" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test still failing
+      """
+    When gtd starts workflow "held"
+    And the process is driven
+    Then the process rests at "health.describe"
+    And the last commit subject is "gtd(check): health.recheck → health.describe"
+    And no commit body contains "Gtd-Mark: flaky="

package/src/workflows/shared/text.ts

@@ -92,14 +92,14 @@ What each change does next (then run \`gtd land\`):
 
 export const qualityUnresolvedMessage = (): string =>
   `The quality lap's fix turns hit their cap and \`.gtd/QUALITY.md\` still
-holds findings. Nothing reviews the change after this, so the process
-will not end with them open.
+holds findings. Nothing after this fixes them, so the process will not
+go on with them open.
 
 Fix what matters by hand, then delete or empty \`.gtd/QUALITY.md\` —
 dropping a finding is your call to make.
 
 What each change does next (then run \`gtd land\`):
-- **Delete or empty \`.gtd/QUALITY.md\`** — the suite runs on your edits, then the process ends (**idle**).
+- **Delete or empty \`.gtd/QUALITY.md\`** — the suite runs on your edits, then the next slice is built, or after the last one you review the change (**build.review.reviewing**).
 - **Anything else** — rests here again.
 `
 
@@ -144,8 +144,10 @@ reword a criterion in place, append a new one with the next unused
 number, delete a dropped one — never renumber, never reuse an ID. When
 the file holds no list (a review loop-back rewrites it), recover the
 last settled one from history (\`git log -p -- .gtd/REQUIREMENTS.md\`)
-and carry its IDs over. Landing is refused while a criterion has no ID or
-two share one.
+and carry its IDs over: after a review a built criterion keeps its ID,
+reworded in place when the review changes its behaviour, and new
+behaviour gets a new ID. Landing is refused while a criterion has no ID
+or two share one.
 `
 
 const riskTierBlock = `

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

@@ -1,121 +0,0 @@
-@inmem
-Feature: human review is the review door's, never the feature workflow's
-
-  A feature process ends once its last slice lands: the quality lap is its
-  last look at the change, and no human review rest follows it. Human review
-  runs only when someone opens the `review` door.
-
-  Background:
-    Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_QUALITYREVIEWS" set to ""
-    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 "seam.naive" writes "src/calc.test.ts" with:
-      """
-      it("[AC-1] subtracts", () => {})
-      """
-    And step "seam.naive" 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 "seam.check" changes nothing
-    And step "implement.applying" runs its script
-    And step "implement.health.check" changes nothing
-    And step "implement.closing" runs its script
-    And judge step "implement.coverage" answers:
-      """
-      [{"id":"AC-1","answer":"yes","p":0.9}]
-      """
-
-  Scenario: a feature process ends at idle with no review rest
-    When the process is driven
-    Then the process rests at "idle"
-    And "src/calc.ts" contains "subtract"
-    And ".gtd/REVIEW.md" does not exist
-    And the commit subjects end with:
-      """
-      gtd(human): design.gate.answer → seam.naive
-      gtd(agent): seam.naive → seam.check
-      gtd(check): seam.check → implement.applying
-      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
-      """
-
-  Scenario: the review door still runs human review over the finished feature
-    When the process is driven
-    Then the process rests at "idle"
-
-    Given step "review-gate.check" changes nothing
-    And step "build.health.check" changes nothing
-    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## calc
-
-      - [ ] ./src/calc.ts#2-2
-        new subtract function
-      """
-    When gtd opens door "review" with "HEAD~11"
-    And the process is driven
-    Then the process rests at "build.review.await-review"
-    And the resting step's content contains the hash of the commit "feat: add calculator"
-
-    Given a file ".gtd/REVIEW.md" with:
-      """
-      # Review: abc1234
-
-      <!-- base: 0000000 -->
-
-      ## calc
-
-      - [x] ./src/calc.ts#2-2
-        new subtract function
-      """
-    And step "build.review.closing" runs its script
-    When gtd lands
-    And the process is driven
-    Then the process rests at "idle"
-    And ".gtd/REVIEW.md" does not exist
-    And the commit subjects end with:
-      """
-      gtd(check): implement.closing → idle
-      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
-      gtd(human): build.review.await-review → build.review.closing
-      gtd(check): build.review.closing → idle
-      """