@pmelab/gtd 27.5.0 → 27.7.0

package/src/workflows/cleanup/cleanup.feature

@@ -36,35 +36,6 @@ Feature: cleanup removes a default-on release flag and keeps its flag-on path
       """
     And the working tree is committed as "feat: registry"
 
-  Scenario: removing the entry and the off path lands, then reaches the review gate
-    Given step "cleanup.removing" writes "src/flags/index.ts" with:
-      """
-      export const FLAGS = [
-        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
-        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
-      ] as const
-      """
-    And step "cleanup.removing" writes "src/calc.ts" with:
-      """
-      export const on = true
-      """
-    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#1-1
-        flag removed
-      """
-    When gtd starts workflow "cleanup" with "--var flag=live"
-    And the process is driven
-    Then the process rests at "build.review.await-review"
-    And "src/flags/index.ts" does not contain "live"
-
   Scenario: a turn leaving the registry entry is refused
     Given step "cleanup.removing" writes "src/calc.ts" with:
       """

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

@@ -0,0 +1,114 @@
+@inmem
+Feature: a trivial change takes the same few beats at either risk tier, flag-free at low
+
+  With GTD_FLAG_NAIVE_PASS and GTD_FLAG_RISK_TIER on, a one-line copy fix goes
+  from idle through the naive pass, the seam judge's land, implement and human
+  review back to idle. Low tier walks exactly the steps high does; only the
+  implementation prompt and the summary differ.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "1"
+    And a file "src/greeting.ts" with:
+      """
+      export const greeting = "Helo, world"
+      """
+    And the working tree is committed as "feat: add greeting"
+    And a file "TODO.md" with:
+      """
+      # Fix the typo
+
+      greeting says "Helo"; make it "Hello".
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.gate.answer" changes nothing
+    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 Outline: a one-line fix runs idle to idle with the same beats at either tier
+    Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Risk Tier
+
+      <tier> — one-line copy fix
+      """
+    When the process is driven
+    Then the process rests at "seam.naive"
+    And the last commit subject is "gtd(human): design.gate.answer → seam.naive"
+
+    Given step "seam.naive" writes "src/greeting.ts" with:
+      """
+      export const greeting = "Hello, world"
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"land","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "implement.building"
+    And the resting step's content contains "<demand>"
+    And the resting step's content does not contain "<absent>"
+
+    Given step "implement.building" writes "src/greeting.ts" with:
+      """
+      export const greeting = "Hello, world!"
+      """
+    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:
+      """
+      gtd(human): idle → unwind
+      gtd(check): unwind → start-gate.check
+      gtd(check): start-gate.check → design.triage
+      gtd(agent): design.triage → design.gate.answer
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → implement.building
+      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
+      """
+    And the output of gtd "summary" <summary> "needs a human reviewer"
+
+    Examples:
+      | tier | demand                                             | absent              | summary          |
+      | low  | Add no release flag                                | new release flag    | does not contain |
+      | high | Put the new behaviour behind a new release flag    | Add no release flag | contains         |

package/src/workflows/feature/feature.ts

@@ -18,6 +18,7 @@ import { packages } from "./packages.js"
 import { architecture, design } from "./planning.js"
 import { buildTail, type ReviewOutcome } from "./review.js"
 import { seamBuild } from "./seam.js"
+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
@@ -56,9 +57,10 @@ export const planAndBuild = async (firstBase: string): Promise<void> => {
   let base = firstBase
   for (;;) {
     await design(base)
+    const tier = riskTierOn() ? recordRisk() : undefined
     // GTD_FLAG_NAIVE_PASS: the record is pinned at the process start, so a mid-process flip never moves a process.
     if (vars.flag_naive_pass === "1") {
-      await seamBuild()
+      await seamBuild(tier)
     } else {
       await architecture()
       await packages()

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

@@ -0,0 +1,108 @@
+# One SDLC path per file, so a changed path reds exactly one fixture — do not merge.
+@inmem
+Feature: a naive pass the judge rules land goes straight to implement with no seam gate
+
+  With GTD_FLAG_NAIVE_PASS on and GTD_FLAG_RISK_TIER off, a naive pass that
+  edits an existing source file is judged land: the process skips the approval
+  gate, any refactor and any architecture, and runs implement, quality and
+  review back to idle. The flags are pinned here so the per-flag test runs never
+  move it off this path.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    And a file "src/greeting.ts" with:
+      """
+      export const greeting = "Helo, world"
+      """
+    And the working tree is committed as "feat: add greeting"
+    And a file "TODO.md" with:
+      """
+      # Fix the typo
+
+      greeting says "Helo"; make it "Hello".
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Concerns
+
+      ### Typo
+
+      - greeting reads "Hello, world".
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.naive" writes "src/greeting.ts" with:
+      """
+      export const greeting = "Hello, world"
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"land","p":0.9}]
+      """
+    And step "implement.building" writes "src/greeting.ts" with:
+      """
+      export const greeting = "Hello, world!"
+      """
+    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, refactor or architecture
+    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:
+      """
+      gtd(human): idle → unwind
+      gtd(check): unwind → start-gate.check
+      gtd(check): start-gate.check → design.triage
+      gtd(agent): design.triage → design.gate.answer
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → implement.building
+      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
+      """
+    And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_naive_pass=1"
+    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.judge" has a body containing "Gtd-Kept:"
+    And the commit "gtd(judge): seam.judge → implement.building" has a body containing "\"answer\":\"land\""
+    And no commit body contains "Gtd-Approved:"
+    And no commit body contains "Gtd-Workflow:"

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

@@ -0,0 +1,137 @@
+# 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
+
+  With GTD_FLAG_NAIVE_PASS on and GTD_FLAG_RISK_TIER off, a naive pass touching
+  an existing non-allowlisted file is ruled refactor-first, rests at the
+  approval gate, and is refactored before it is implemented. The flags are
+  pinned so the per-flag test runs never move it off its path.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    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`.
+      """
+    And step "design.gate.answer" changes nothing
+
+  Scenario: a refactor-first judgment runs approval, refactor, implement and review to idle
+    Given 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 judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "refactor.deriving" runs its script
+    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 the process is driven
+    Then the process rests at "seam.approve"
+    And the resting step's content contains "src/calc.ts"
+
+    When gtd lands
+    And the process is driven
+    Then the process rests at "refactor.building"
+    And ".gtd/REFACTOR.md" contains "calc.ts`"
+
+    Given step "refactor.building" writes "src/calc.ts" with:
+      """
+      export const op = (a: number, b: number, sign: number) => a + sign * b
+      export const add = (a: number, b: number) => op(a, b, 1)
+      """
+    And step "refactor.health.check" changes nothing
+    And step "refactor.closing" runs its script
+    When the process is driven
+    Then the process rests at "implement.building"
+    And ".gtd/REFACTOR.md" does not exist
+    And "src/calc.ts" contains "op(a, b, 1)"
+
+    Given step "implement.building" writes "src/calc.ts" with:
+      """
+      export const op = (a: number, b: number, sign: number) => a + sign * b
+      export const add = (a: number, b: number) => op(a, b, 1)
+      export const subtract = (a: number, b: number) => op(a, b, -1)
+      """
+    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"
+    And the commit subjects end with:
+      """
+      gtd(human): idle → unwind
+      gtd(check): unwind → start-gate.check
+      gtd(check): start-gate.check → design.triage
+      gtd(agent): design.triage → design.gate.answer
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → seam.approve
+      gtd(human): seam.approve → refactor.deriving
+      gtd(check): refactor.deriving → refactor.building
+      gtd(agent): refactor.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.closing
+      gtd(check): refactor.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
+      """
+    And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_naive_pass=1"
+    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.judge" has a body containing "Gtd-Kept:"
+    And the commit "gtd(judge): seam.judge → seam.approve" has a body containing "\"answer\":\"refactor-first\""
+    And the commit "gtd(human): seam.approve → refactor.deriving" has a body containing "Gtd-Approved: {\"step\":\"seam.approve#1\",\"name\":\"Test\",\"email\":\"test@test.com\"}"
+    And no commit body contains "Gtd-Workflow:"

package/src/workflows/feature/risk-tier.feature

@@ -0,0 +1,238 @@
+@inmem
+Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_TIER
+
+  With GTD_FLAG_NAIVE_PASS and GTD_FLAG_RISK_TIER both on, design.triage asks
+  for a risk tier and production signals, and the design gate's exit lands them
+  as Gtd-Mark trailers: one `risk-tier=<low|high>`, one `production-signal`
+  per signal. A missing or unreadable tier is high. With the flag off, nothing
+  is asked and no commit carries a Gtd-Mark.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
+
+  Rule: with GTD_FLAG_RISK_TIER on
+
+    Background:
+      Given an environment variable "GTD_FLAG_RISK_TIER" set to "1"
+      And a file "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        """
+      And a file "src/calc.test.ts" with:
+        """
+        import { expect, it } from "vitest"
+        it("adds", () => expect(1 + 1).toBe(2))
+        """
+      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
+
+    Scenario: with both flags on the triage prompt asks for the tier and the signals
+      When the process is driven
+      Then the process rests at "design.triage"
+      And the resting step's content contains "## Risk Tier"
+      And the resting step's content contains "## Production Signals"
+      And the resting step's content contains "unsure means `high`"
+
+    Scenario: a low tier marks risk-tier=low on the design-exit commit
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial copy change
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit subject is "gtd(human): design.gate.answer → seam.naive"
+      And the last commit body contains "Gtd-Mark: risk-tier=low"
+
+    Scenario: a high tier marks the design-exit commit
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        high — touches payments
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit subject is "gtd(human): design.gate.answer → seam.naive"
+      And the last commit body contains "Gtd-Mark: risk-tier=high"
+
+    Scenario Outline: a missing section or an unknown word counts as high
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        <tier section>
+        ## Concerns
+
+        ### Subtract
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit body contains "Gtd-Mark: risk-tier=high"
+
+      Examples:
+        | tier section                  |
+        |                               |
+        | ## Risk Tier\n\nmedium — hmm |
+        | ```\n## Risk Tier\n\nlow\n```\n |
+
+    Scenario Outline: signals written at triage land as marks for either tier
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        <tier> — reason
+
+        ## Production Signals
+
+        - error rate on /subtract stays flat
+        - p95 latency
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit body contains "Gtd-Mark: production-signal=error rate on /subtract stays flat"
+      And the last commit body contains "Gtd-Mark: production-signal=p95 latency"
+
+      Examples:
+        | tier |
+        | low  |
+        | high |
+
+    Scenario: the tier comes from the requirements the final design gate lap accepted
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial copy change
+        """
+      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 judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "design.gate.answer"
+      Given a file ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        high — touches payments
+        """
+      And step "design.triage" from now on changes nothing
+      And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        high — touches payments
+
+        ## Concerns
+
+        ### Subtract
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "implement.building"
+      And the resting step's content contains "Put the new behaviour behind a new release flag"
+      And the resting step's content does not contain "Add no release flag"
+
+  Rule: with GTD_FLAG_RISK_TIER off
+
+    Background:
+      Given an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+      And a file "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        """
+      And a file "src/calc.test.ts" with:
+        """
+        import { expect, it } from "vitest"
+        it("adds", () => expect(1 + 1).toBe(2))
+        """
+      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
+
+    Scenario: the flag-off twin asks for no tier and marks no commit
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial
+
+        ## Production Signals
+
+        - error rate stays flat
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And no commit body contains "Gtd-Mark"
+
+    Scenario: the flag-off twin's triage prompt has no tier section
+      When the process is driven
+      Then the process rests at "design.triage"
+      And the resting step's content does not contain "## Risk Tier"
+      And the resting step's content does not contain "## Production Signals"
+
+
+    Scenario: the flag-off twin keeps today's flag demand
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial
+        """
+      And step "design.gate.answer" changes nothing
+      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 judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "implement.building"
+      And the resting step's content contains "Put the new behaviour behind a new release flag"
+      And the resting step's content does not contain "Add no release flag"