@pmelab/gtd 30.0.0 → 31.0.0

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

@@ -0,0 +1,165 @@
+@inmem
+Feature: flag mode off builds a feature with no release flag, seam judge or refactor
+
+  `flagMode` is a factory option of the shipped workflows, on by default. Off,
+  the project ships without feature flags: no seam judge and no refactor run,
+  and the naive implementation goes straight through the health loop and the
+  quality lap.
+
+  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({ flagMode: false })
+      """
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    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: the change behaves as described.
+      """
+    And step "design.gate.answer" changes nothing
+
+  Scenario: flag mode off skips the seam judge and the refactor, and asks for no flag
+    When the process is driven
+    Then the process rests at "implement.building"
+    And the resting step's content contains "the quickest way that works"
+    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 "new release flag"
+    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
+    When the process is driven
+    Then the process rests at "build.review.reviewing"
+    And "src/calc.ts" contains "subtract"
+    And the commit subjects end with:
+      """
+      chore: initial commit
+      feat: add calculator
+      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 → 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
+      """
+
+  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/index.ts

@@ -1,6 +1,7 @@
 import { feature } from "./feature.js"
 
 export * from "./steps.js"
+export * from "./criteria.js"
 export * from "./planning.js"
 export * from "./refactor.js"
 export * from "./seam.js"

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

@@ -34,6 +34,10 @@ Feature: a naive pass the judge rules land goes straight to implement with no se
       ### Typo
 
       - greeting reads "Hello, world".
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
     And step "seam.naive" writes "src/greeting.ts" with:

package/src/workflows/feature/planning.ts

@@ -8,6 +8,7 @@ import {
   scope,
 } from "../../flows/index.js"
 import { REQUIREMENTS } from "../shared/steps.js"
+import { requireCriteria } from "./criteria.js"
 import { answerProductQuestions, triage } from "./steps.js"
 
 /**
@@ -31,5 +32,6 @@ export const design = (base: string): Promise<void> =>
       await triage(base)
       requireProgress(REQUIREMENTS)
       requireReplies(REQUIREMENTS)
+      requireCriteria(REQUIREMENTS)
     } while (await noteGate(REQUIREMENTS, answerProductQuestions))
   })

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

@@ -35,6 +35,10 @@ Feature: a refactor that carried the whole feature still gets a feature review
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
 

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

@@ -34,6 +34,10 @@ Feature: a refactor-first judgment walks one fixed path to idle
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
 

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

@@ -46,6 +46,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
     And step "seam.naive" writes "src/calc.ts" with:
@@ -126,6 +130,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
     And step "seam.naive" writes "src/calc.ts" with:
@@ -205,6 +213,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         ### Subtract
 
         - `subtract(a, b)` returns `a - b`.
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       And step "seam.naive" writes "src/calc.ts" with:
@@ -449,6 +461,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         # Requirements
 
         - multiply, designed
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "implement.building" writes "src/calc.ts" with:
         """
@@ -1404,6 +1420,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         ### Subtract
 
         - `subtract(a, b)` returns `a - b`.
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       And step "seam.naive" writes "src/calc.ts" with:
@@ -1582,6 +1602,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         ### Subtract
 
         - `subtract(a, b)` returns `a - b`.
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       And judge step "seam.judge" answers:

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

@@ -49,6 +49,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Risk Tier
 
         low — trivial copy change
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       When the process is driven
@@ -64,6 +68,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Risk Tier
 
         high — touches payments
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       When the process is driven
@@ -80,6 +88,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Concerns
 
         ### Subtract
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       When the process is driven
@@ -105,6 +117,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - error rate on /subtract stays flat
         - p95 latency
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       When the process is driven
@@ -125,6 +141,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Risk Tier
 
         low — trivial copy change
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "seam.naive" writes "src/calc.ts" with:
         """
@@ -157,6 +177,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Concerns
 
         ### Subtract
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       When the process is driven
@@ -199,6 +223,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Production Signals
 
         - error rate stays flat
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       When the process is driven
@@ -220,6 +248,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
         ## Risk Tier
 
         low — trivial
+
+        ## Acceptance Criteria
+
+        - AC-1: the change behaves as described.
         """
       And step "design.gate.answer" changes nothing
       And step "seam.naive" writes "src/calc.ts" with:

package/src/workflows/feature/seam-rejection.feature

@@ -33,6 +33,10 @@ Feature: rejected naive passes walk one fixed path through the steer gate to idl
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
 
@@ -77,6 +81,10 @@ Feature: rejected naive passes walk one fixed path through the steer gate to idl
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`, in the calculator module.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "seam.naive" from now on changes nothing
     And step "seam.naive" writes "src/calc.ts" with:

package/src/workflows/feature/seam.feature

@@ -43,6 +43,10 @@ Feature: the naive pass and seam judge decide how a feature is built
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     And step "design.gate.answer" changes nothing
 
@@ -184,6 +188,10 @@ Feature: the naive pass and seam judge decide how a feature is built
       ### Subtract
 
       - `subtract(a, b)` returns `a - b`, in a new module.
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     When gtd lands
     Then the process rests at "seam.naive"

package/src/workflows/feature/seam.ts

@@ -16,7 +16,9 @@ import { healthy } from "../shared/health.js"
 import { coder, FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
+import { requireCriteria, requireCriteriaFrozen } from "./criteria.js"
 import { refactorStrays, reviewedRefactor } from "./refactor.js"
+import { flagModeOn } from "../shared/options.js"
 import type { RiskTier } from "./tier.js"
 
 /** Naive-pass retries after a `reject`; the next `reject` rests at `seam.steer`. */
@@ -71,6 +73,7 @@ export function implement(
         options.tier,
         options.amend,
         options.afterRefactor,
+        flagModeOn(),
       ),
       {
         label: "Implementing",
@@ -79,13 +82,16 @@ export function implement(
         ...(options.afterRefactor === true ? { allowEmpty: true } : {}),
       },
     )
-    await healthy(() =>
-      t.agentWithSkills("fix.suite.fixing", t.implementFixPrompt(), {
-        label: "Fixing the check",
-        file: FEEDBACK,
-        model: coder(),
-        system: t.builderSystem(),
-      }),
+    requireCriteriaFrozen(REQUIREMENTS)
+    await healthy(
+      () =>
+        t.agentWithSkills("fix.suite.fixing", t.implementFixPrompt(), {
+          label: "Fixing the check",
+          file: FEEDBACK,
+          model: coder(),
+          system: t.builderSystem(),
+        }),
+      { guard: () => requireCriteriaFrozen(REQUIREMENTS), guardRests: false },
     )
     await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" })
   })
@@ -122,6 +128,7 @@ const decide = (): Promise<Decision> =>
       })
       // Any edit steers, with a fresh budget and no stale rejection; clean overrules.
       if (changes().length === 0) return { reference: tip.hash }
+      requireCriteria(REQUIREMENTS)
       rejection = undefined
       retries = 0
     }

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

@@ -33,6 +33,10 @@ Feature: a process keeps the risk tier setting it started with when GTD_FLAG_RIS
       ## Risk Tier
 
       low — a new pure function
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
 
   Scenario: a process started with the flag off records no tier after the flag turns on

package/src/workflows/index.ts

@@ -21,6 +21,7 @@ export {
 } from "./shared/tail.js"
 export { lensesOf } from "../workflow-kit/index.js"
 export * from "./feature/steps.js"
+export * from "./feature/criteria.js"
 export * from "./feature/planning.js"
 export * from "./feature/refactor.js"
 export * from "./feature/seam.js"

package/src/workflows/shared/options.test.ts

@@ -30,6 +30,18 @@ describe("the shipped workflow factories", () => {
     })
   })
 
+  it("default flagMode on and lay a boolean factory option over it as a string", () => {
+    expect(defaults.flagMode).toBe("true")
+    expect(configure(feature({ flagMode: false }))).toMatchObject({
+      ok: true,
+      build: { defaults: { flagMode: "false" } },
+    })
+    expect(configure(review({ flagMode: true }))).toMatchObject({
+      ok: true,
+      build: { defaults: { flagMode: "true" } },
+    })
+  })
+
   it("declare flag_risk_tier off by default; it is no factory option", () => {
     expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_risk_tier")
   })

package/src/workflows/shared/options.ts

@@ -5,6 +5,8 @@ import {
   type WorkflowBase,
   type WorkflowDoors,
   type WorkflowFactory,
+  refuse,
+  vars,
 } from "../../flows/index.js"
 import { defaultFlagRegistry, defaults, envDefaults } from "./vars.js"
 
@@ -23,18 +25,31 @@ export const ShippedOptions = Schema.Struct({
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,
+  flagMode: Schema.optionalWith(Schema.Boolean, { exact: true }),
 })
 
 export type ShippedOptions = Schema.Schema.Encoded<typeof ShippedOptions>
 
 const over = (
   base: Readonly<Record<string, string>>,
-  options: Readonly<Record<string, string>>,
+  options: Readonly<Record<string, string | boolean>>,
 ): Record<string, string> => ({
   ...base,
-  ...Object.fromEntries(Object.entries(options).filter(([name]) => Object.hasOwn(base, name))),
+  ...Object.fromEntries(
+    Object.entries(options)
+      .filter(([name]) => Object.hasOwn(base, name))
+      .map(([name, value]) => [name, String(value)]),
+  ),
 })
 
+/** The `flagMode` setting, pinned at process start. Anything but true/false fails rather than guess a side. */
+export const flagModeOn = (): boolean => {
+  const value = vars.flagMode ?? defaults.flagMode!
+  if (value !== "true" && value !== "false")
+    refuse(`gtd: flagMode must be "true" or "false", got ${JSON.stringify(value)}`)
+  return value === "true"
+}
+
 /** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
 export const shipped = (
   flow: Flow,

package/src/workflows/shared/text.test.ts

@@ -990,6 +990,22 @@ describe("the seam phase's texts", () => {
     expect(prompt).toContain("Implement them properly")
   })
 
+  it("flag mode off asks for the naive version and no release flag, whatever the tier or lap", () => {
+    for (const [tier, amend] of [
+      ["high", false],
+      ["low", false],
+      ["high", true],
+    ] as const) {
+      const prompt = renderText(() => implementBuildingPrompt(undefined, tier, amend, false, false))
+      expect(prompt).toContain("Add no release flag — this project ships without release flags")
+      expect(prompt).not.toContain("new release flag")
+      expect(prompt).not.toContain("low risk tier")
+    }
+    expect(
+      renderText(() => implementBuildingPrompt(undefined, "high", false, false, false)),
+    ).toContain("the quickest way that works")
+  })
+
   it("keeps a fix turn to the feedback file's rules", () => {
     expect(renderText(() => implementFixPrompt())).toContain(".gtd/FEEDBACK.md")
   })