@pmelab/gtd 56.0.0 → 58.0.0

package/src/workflows/feature/naive-test.feature

@@ -0,0 +1,263 @@
+@inmem
+Feature: a person tries the naive pass by hand before anything builds on it
+
+  `naiveTest` is a factory option of the shipped workflows, off by default. On,
+  every green naive pass is applied to the working tree and the process rests
+  at `seam.try`. A clean landing signs it off and the process goes on — to the
+  seam judge when the requirements ask for a release flag, else straight to the
+  implementation. Notes in
+  `.gtd/NAIVE-TEST.md`, a code edit or a requirements edit send it back: the
+  pass and the person's code edits leave the tree again, and the next naive
+  pass gets the notes and the edits. Every lap ends at the gate again.
+
+  Rule: with no release flag asked for
+
+    Background:
+      Given a gtd config with:
+        """
+        import { feature } from "@pmelab/gtd/workflows/feature"
+        export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
+        export default feature({ naiveTest: true })
+        """
+      And an environment variable "GTD_QUALITYREVIEWS" set to ""
+      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
+
+        ## Impact
+
+        - the calculator module
+
+        ## 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 "seam.applying" runs its script
+      And step "seam.restoring" runs its script
+
+    Scenario: a green naive pass rests at seam.try, applied to the working tree
+      When the process is driven
+      Then the process rests at "seam.try"
+      And the resting step's content contains "try it by hand"
+      And the resting step's content contains "`.gtd/NAIVE-TEST.md`"
+      And "src/calc.ts" contains "export const subtract"
+      And the commit subjects end with:
+        """
+        gtd(agent): seam.naive → seam.check
+        gtd(check): seam.check → seam.applying
+        gtd(check): seam.applying → seam.try
+        """
+
+    Scenario: a clean landing signs the pass off, takes it out and lands it as the implementation
+      When the process is driven
+      Then the process rests at "seam.try"
+      When gtd lands
+      And step "implement.applying" runs its script
+      And step "implement.health.check" changes nothing
+      And step "implement.closing" runs its script
+      And the process is driven
+      Then the process rests at "build.review.reviewing"
+      And "src/calc.ts" contains "export const subtract"
+      And the commit subjects end with:
+        """
+        gtd(check): seam.applying → seam.try
+        gtd(human): seam.try → seam.restoring
+        gtd(check): seam.restoring → implement.applying
+        gtd(check): implement.applying → implement.health.check
+        gtd(check): implement.health.check → implement.closing
+        gtd(check): implement.closing → build.review.reviewing
+        """
+
+    Scenario: notes and a code edit send the pass back, out of the tree, to a naive pass that reads both
+      Given step "seam.naive", when prompted with "> subtract(5, 3) printed 8, not 2.", writes "notes-read.txt" with:
+        """
+        read
+        """
+      And step "seam.naive", when prompted with "-- . ':(exclude).gtd'", writes "edits-read.txt" with:
+        """
+        read
+        """
+      When the process is driven
+      Then the process rests at "seam.try"
+      Given a file ".gtd/NAIVE-TEST.md" with:
+        """
+        subtract(5, 3) printed 8, not 2.
+        """
+      And a file "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        export const subtract = (a: number, b: number) => a - b
+        """
+      And a file "src/hint.ts" with:
+        """
+        export const hint = "subtract, not add"
+        """
+      When gtd lands
+      And the process is driven
+      Then the process rests at "seam.try"
+      And "src/hint.ts" does not exist
+      And "notes-read.txt" contains "read"
+      And "edits-read.txt" contains "read"
+      And ".gtd/NAIVE-TEST.md" does not exist
+      And the commit subjects end with:
+        """
+        gtd(check): seam.applying → seam.try
+        gtd(human): seam.try → seam.restoring
+        gtd(check): seam.restoring → seam.naive
+        gtd(agent): seam.naive → seam.check
+        gtd(check): seam.check → seam.applying
+        gtd(check): seam.applying → seam.try
+        """
+
+    Scenario: notes alone send the pass back with no edits to read
+      Given step "seam.naive", when prompted with "They edited the code", writes "edits-read.txt" with:
+        """
+        read
+        """
+      When the process is driven
+      Then the process rests at "seam.try"
+      Given a file ".gtd/NAIVE-TEST.md" with:
+        """
+        subtract adds.
+        """
+      When gtd lands
+      And the process is driven
+      Then the process rests at "seam.try"
+      And "edits-read.txt" does not exist
+
+    Scenario: a requirements edit at seam.try stays, and sends the pass back
+      When the process is driven
+      Then the process rests at "seam.try"
+      Given a file ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the calculator module
+
+        ## Acceptance Criteria
+
+        - AC-1: subtract(a, b) returns a - b.
+        - AC-2: subtract(a, b) rejects NaN.
+        """
+      When gtd lands
+      And the process is driven
+      Then the process rests at "seam.try"
+      And ".gtd/REQUIREMENTS.md" contains "AC-2: subtract(a, b) rejects NaN."
+      And the commit subjects end with:
+        """
+        gtd(human): seam.try → seam.restoring
+        gtd(check): seam.restoring → seam.naive
+        gtd(agent): seam.naive → seam.check
+        gtd(check): seam.check → seam.applying
+        gtd(check): seam.applying → seam.try
+        """
+
+  Rule: with a release flag asked for
+
+    Background:
+      Given a gtd config with:
+        """
+        import { feature } from "@pmelab/gtd/workflows/feature"
+        export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
+        export default feature({ naiveTest: true })
+        """
+      And an environment variable "GTD_QUALITYREVIEWS" set to ""
+      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
+
+        ## Impact
+
+        - the calculator module
+
+        ## Release Flag
+
+      new
+
+      ## 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 "seam.applying" runs its script
+      And step "seam.restoring" runs its script
+
+    Scenario: the person tries the pass before the seam judge rules
+      When the process is driven
+      Then the process rests at "seam.try"
+      And the resting step's content contains "the seam judge rules on its shape"
+      When gtd lands
+      And the process is driven
+      Then the process rests at "seam.judge"
+
+  Rule: with a naiveTest that is neither true nor false
+
+    Background:
+      Given an environment variable "GTD_NAIVETEST" set to "maybe"
+      And a gtd config with:
+        """
+        import { feature } from "@pmelab/gtd/workflows/feature"
+        export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
+        export default feature()
+        """
+      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
+        """
+
+    Scenario: the landing that would pin it is refused
+      Then driving the process is refused with "naiveTest must be"

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

@@ -10,7 +10,6 @@ Feature: a naive pass the judge rules land is itself the implementation
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
     And a file "src/greeting.ts" with:
@@ -40,6 +39,10 @@ Feature: a naive pass the judge rules land is itself the implementation
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/planning.ts

@@ -9,6 +9,7 @@ import {
 } from "../../flows/index.js"
 import { REQUIREMENTS } from "../shared/steps.js"
 import { requireCriteria, requireImpact } from "./criteria.js"
+import { requireReleaseFlag } from "./release-flag.js"
 import { answerProductQuestions, triage } from "./steps.js"
 
 /**
@@ -34,6 +35,7 @@ export const design = (base: string, guard?: () => void): Promise<void> =>
       requireReplies(REQUIREMENTS)
       requireCriteria(REQUIREMENTS)
       requireImpact(REQUIREMENTS)
+      requireReleaseFlag(REQUIREMENTS)
       guard?.()
     } while (await noteGate(REQUIREMENTS, answerProductQuestions))
   })

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

@@ -10,7 +10,6 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     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"
@@ -41,6 +40,10 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

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

@@ -9,7 +9,6 @@ Feature: a refactor-first judgment walks one fixed path to the review gate
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to ""
     And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
@@ -40,6 +39,10 @@ Feature: a refactor-first judgment walks one fixed path to the review gate
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/refactor-lens-models.feature

@@ -33,6 +33,10 @@ Feature: the refactor review's lenses take their model hints from refactorQualit
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

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

@@ -11,7 +11,6 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to ""
     And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
@@ -46,6 +45,10 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: subtract returns the difference.

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

@@ -9,7 +9,6 @@ Feature: the refactor is reviewed on its own before the feature is implemented
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to ""
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
 
@@ -52,6 +51,10 @@ Feature: the refactor is reviewed on its own before the feature is implemented
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.
@@ -150,6 +153,10 @@ Feature: the refactor is reviewed on its own before the feature is implemented
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.
@@ -247,6 +254,10 @@ Feature: the refactor is reviewed on its own before the feature is implemented
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -1194,6 +1205,10 @@ Feature: the refactor is reviewed on its own before the feature is implemented
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -1319,6 +1334,10 @@ Feature: the refactor is reviewed on its own before the feature is implemented
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.

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

@@ -0,0 +1,167 @@
+@inmem
+Feature: a release flag only when the requirements ask for one
+
+  A change ships unflagged unless `.gtd/REQUIREMENTS.md` carries a
+  `## Release Flag` section — written by triage, or by the skip path's impact
+  turn, only when the sketch asks for a flag, and editable at the design gate.
+  Its first line is `new` (a new release flag) or `existing: <NAME>` (behind a
+  flag that already exists). Without it no seam judge or refactor runs and the
+  naive pass lands as the implementation; with it the seam judge rules on the
+  pass.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    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 step "unwind" changes nothing
+    And step "start-gate.check" 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
+
+  Rule: the design path
+
+    Background:
+      Given a file "TODO.md" with:
+        """
+        # Add subtract
+
+        subtract(a, b) returns the difference.
+        """
+      And step "design.gate.answer" changes nothing
+
+    Scenario: with no Release Flag section the naive pass lands unjudged, and no flag is asked for
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the calculator module
+
+        ## Acceptance Criteria
+
+        - AC-1: subtract(a, b) returns a - b.
+        """
+      And step "implement.applying" runs its script
+      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.reviewing"
+      And "src/calc.ts" contains "subtract"
+      And no commit body contains "seam.judge"
+      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.closing
+        gtd(check): implement.closing → build.review.reviewing
+        """
+
+    Scenario: a new release flag asked for sends the naive pass to the seam judge
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the calculator module
+
+        ## Release Flag
+
+        new
+
+        ## Acceptance Criteria
+
+        - AC-1: subtract(a, b) returns a - b.
+        """
+      When the process is driven
+      Then the process rests at "seam.judge"
+
+    Scenario: an existing flag asked for sends the naive pass to the seam judge too
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the calculator module
+
+        ## Release Flag
+
+        existing: GTD_FLAG_BETA
+
+        ## Acceptance Criteria
+
+        - AC-1: subtract(a, b) returns a - b.
+        """
+      When the process is driven
+      Then the process rests at "seam.judge"
+
+    Scenario: a Release Flag section that asks for neither is refused
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the calculator module
+
+        ## Release Flag
+
+        maybe later
+
+        ## Acceptance Criteria
+
+        - AC-1: subtract(a, b) returns a - b.
+        """
+      Then driving the process is refused with "release-flag"
+
+  Rule: the skip path
+
+    Background:
+      Given a file "TODO.md" with:
+        """
+        # Add subtract
+
+        Ship it behind the existing GTD_FLAG_BETA flag.
+
+        ## Acceptance criteria
+
+        - subtract(a, b) returns a - b.
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+
+    Scenario: the impact turn records the flag the sketch asks for, and the seam judge rules
+      Given step "design.impact" appends to ".gtd/REQUIREMENTS.md":
+        """
+
+        ## Impact
+
+        - the calculator module
+
+        ## Release Flag
+
+        existing: GTD_FLAG_BETA
+        """
+      When the process is driven
+      Then the process rests at "seam.judge"
+      And ".gtd/REQUIREMENTS.md" contains "existing: GTD_FLAG_BETA"

package/src/workflows/feature/release-flag.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest"
+import { releaseFlagOf } from "./release-flag.js"
+
+const requirements = (section: string): string =>
+  `# Requirements\n\n## Impact\n\n- a module\n\n${section}## Acceptance Criteria\n\n- AC-1: a\n`
+
+describe("releaseFlagOf", () => {
+  it("asks for no flag without the section, or with none", () => {
+    expect(releaseFlagOf(requirements(""))).toEqual({ kind: "none" })
+    expect(releaseFlagOf(requirements("## Release Flag\n\nnone\n\n"))).toEqual({ kind: "none" })
+  })
+
+  it("reads new and an existing flag's name, backticked or not", () => {
+    expect(releaseFlagOf(requirements("## Release Flag\n\nnew\n\n"))).toEqual({ kind: "new" })
+    for (const line of [
+      "existing: GTD_FLAG_BETA",
+      "existing: `GTD_FLAG_BETA`",
+      "Existing:GTD_FLAG_BETA",
+    ])
+      expect(releaseFlagOf(requirements(`## Release Flag\n\n${line}\n\n`))).toEqual({
+        kind: "existing",
+        name: "GTD_FLAG_BETA",
+      })
+  })
+
+  it("reads only the first line under the heading, and only a level-2 heading", () => {
+    expect(
+      releaseFlagOf(requirements("## Release Flag\n\nnew\n\nbecause the sketch says so\n\n")),
+    ).toEqual({
+      kind: "new",
+    })
+    expect(releaseFlagOf(requirements("### Release Flag\n\nnew\n\n"))).toEqual({ kind: "none" })
+  })
+
+  it("ignores a fenced heading", () => {
+    expect(releaseFlagOf(requirements("```\n## Release Flag\n\nnew\n```\n\n"))).toEqual({
+      kind: "none",
+    })
+  })
+
+  it("names the line it cannot read", () => {
+    expect(releaseFlagOf(requirements("## Release Flag\n\nmaybe later\n\n"))).toEqual({
+      unreadable: "maybe later",
+    })
+    expect(releaseFlagOf(requirements("## Release Flag\n\nexisting:\n\n"))).toEqual({
+      unreadable: "existing:",
+    })
+  })
+})