@pmelab/gtd 57.0.0 → 58.0.0

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

@@ -45,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

@@ -51,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.
@@ -149,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.
@@ -246,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.
@@ -1193,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.
@@ -1318,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:",
+    })
+  })
+})

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

@@ -0,0 +1,46 @@
+import { read, refuse } from "../../flows/index.js"
+import { HEADING, markFenced } from "../shared/fences.js"
+import { REQUIREMENTS } from "../shared/steps.js"
+import type { ReleaseFlag } from "../shared/text.js"
+
+const NAME = /^existing:\s*`?([A-Za-z_][\w.-]*)`?$/i
+
+const isFlagHeading = (h: RegExpExecArray | null): boolean =>
+  h !== null && h[1]!.length === 2 && /^release flag$/i.test(h[2]!.trim())
+
+/** The first line under `## Release Flag`, `undefined` without the section. */
+const requestLine = (text: string): string | undefined => {
+  const lines = markFenced(text)
+  const at = lines.findIndex((l) => !l.fenced && isFlagHeading(HEADING.exec(l.line)))
+  if (at === -1) return undefined
+  const body = lines.slice(at + 1)
+  const end = body.findIndex((l) => !l.fenced && HEADING.test(l.line))
+  return (end === -1 ? body : body.slice(0, end)).find((l) => l.line.trim() !== "")?.line.trim()
+}
+
+/** What `text` asks for, or why it cannot be read. No section asks for no flag. */
+export const releaseFlagOf = (text: string): ReleaseFlag | { readonly unreadable: string } => {
+  const line = requestLine(text)
+  if (line === undefined || /^none$/i.test(line)) return { kind: "none" }
+  if (/^new$/i.test(line)) return { kind: "new" }
+  const name = NAME.exec(line)?.[1]
+  return name === undefined ? { unreadable: line } : { kind: "existing", name }
+}
+
+/** Refuse `file` when its `## Release Flag` section is neither `none`, `new` nor `existing: <NAME>`. */
+export const requireReleaseFlag = (file: string): void => {
+  const request = releaseFlagOf(read(file) ?? "")
+  if (!("unreadable" in request)) return
+  refuse(
+    `gtd land: release-flag: ${file}'s "## Release Flag" reads ${JSON.stringify(request.unreadable)} — its first line must be \`new\`, \`existing: <NAME>\` or \`none\`, or leave the section out for no flag`,
+  )
+}
+
+/** What `.gtd/REQUIREMENTS.md` asks for now; a person's unreadable edit is refused. */
+export const requestedFlag = (): ReleaseFlag => {
+  requireReleaseFlag(REQUIREMENTS)
+  return releaseFlagOf(read(REQUIREMENTS) ?? "") as ReleaseFlag
+}
+
+/** Whether the change goes behind a release flag: only then does the seam judge rule. */
+export const flagged = (): boolean => requestedFlag().kind !== "none"

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

@@ -11,7 +11,6 @@ Feature: a feature process ends at the human review
   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

package/src/workflows/feature/reviewer-walkthrough.feature

@@ -11,7 +11,6 @@ Feature: a reviewer walks the human through the feature's code
   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

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

@@ -54,6 +54,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -77,6 +81,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -101,6 +109,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -134,6 +146,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -162,6 +178,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -211,6 +231,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -261,6 +285,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -290,6 +318,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.

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

@@ -38,6 +38,10 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.
@@ -83,6 +87,10 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/seam.feature

@@ -48,6 +48,10 @@ Feature: the naive pass and seam judge decide how a feature is built
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.
@@ -241,6 +245,10 @@ Feature: the naive pass and seam judge decide how a feature is built
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/seam.test.ts

@@ -234,18 +234,24 @@ interface Seamed {
   readonly outcome: SeamOutcome | Error
 }
 
+const FLAGGED = "# Requirements\n\n## Release Flag\n\nnew\n"
+
 /** Runs `seamBuild` against a scripted context: the judge answers `answer`, every review signs off. */
 const driveSeam = async (
   answer: string,
   stray: Change = change("src/a.ts", "modified"),
   vars: Record<string, string> = {},
   reds = 0,
+  requirements = FLAGGED,
 ): Promise<Seamed> => {
   let red = false
   let redsLeft = reds
   const names: string[] = []
   const stack: string[] = []
-  const files = new Map<string, string>([["src/a.ts", "a"]])
+  const files = new Map<string, string>([
+    ["src/a.ts", "a"],
+    [".gtd/REQUIREMENTS.md", requirements],
+  ])
   let current = "c0"
   const effects: Record<string, () => void> = {
     note: () => void files.set(NOTE, "Seam: a shared op"),
@@ -302,8 +308,8 @@ describe("seamBuild", () => {
     expect(h.names).toEqual(["seam.naive", "seam.check", "seam.judge"])
   })
 
-  it("with flagMode off resolves a vetted pass to land with no judge", async () => {
-    const h = await driveSeam("reject", undefined, { flagMode: "false" })
+  it("with no release flag asked for resolves a vetted pass to land with no judge", async () => {
+    const h = await driveSeam("reject", undefined, {}, 0, "# Requirements\n")
     expect(h.outcome).toEqual({ reference: "abc", base: "c-base", land: true })
     expect(h.names).toEqual(["seam.naive", "seam.check"])
   })
@@ -393,6 +399,7 @@ describe("seamBuild", () => {
 
 describe("implement", () => {
   let lastOptions: Extract<StepRequest, { kind: "agent" }>["options"] | undefined
+  let requirements = FLAGGED
   const building = async (
     reference: string | undefined,
     tier?: "low" | "high",
@@ -414,6 +421,7 @@ describe("implement", () => {
           pushScope: () => undefined,
           popScope: () => undefined,
           changesSince: () => [],
+          read: (path: string) => (path === ".gtd/REQUIREMENTS.md" ? requirements : undefined),
         },
       ),
     )
@@ -506,9 +514,14 @@ describe("implement", () => {
     expect(prompt).toContain("otherwise put")
   })
 
-  it("amend on tier low says to add no release flag", async () => {
-    const prompt = await building(undefined, "low", true)
-    expect(prompt).toContain("Add no release flag")
-    expect(prompt).toContain("amend")
+  it("asks for no release flag when the requirements ask for none, whatever the tier", async () => {
+    requirements = "# Requirements\n"
+    try {
+      const prompt = await building(undefined, "high", true)
+      expect(prompt).toContain("Add no release flag")
+      expect(prompt).toContain("amend")
+    } finally {
+      requirements = FLAGGED
+    }
   })
 })

package/src/workflows/feature/seam.ts

@@ -37,7 +37,8 @@ import {
   reviewedRefactor,
 } from "./refactor.js"
 import { isCode } from "../shared/review.js"
-import { flagModeOn, naiveTestOn } from "../shared/options.js"
+import { naiveTestOn } from "../shared/options.js"
+import { flagged, requestedFlag } from "./release-flag.js"
 import type { RiskTier } from "./tier.js"
 
 /** Naive-pass retries after a `reject` or a red suite; the next one rests at `seam.steer`. */
@@ -187,10 +188,9 @@ const build = async (options: ImplementOptions): Promise<void> => {
     "building",
     t.implementBuildingPrompt(
       options.reference,
-      options.tier,
       options.amend,
       options.afterRefactor,
-      flagModeOn(),
+      requestedFlag(),
       options.rebuild,
     ),
     {
@@ -237,14 +237,14 @@ export const implementing = (options: ImplementOptions): Promise<readonly string
 interface Decision {
   readonly reference: string
   readonly tip: KeptTip
-  /** Absent on `land` (or with `flagMode` off, unjudged): the pass itself is the implementation. */
+  /** Absent on `land` (or unjudged, with no release flag asked for): the pass itself is the implementation. */
   readonly shape?: DiffShapeResult
 }
 
 /** Resolves `true` when the human steered (edited), `false` on a clean overrule. */
 const steer = async (retry: t.NaiveRetry): Promise<boolean> => {
   await human("steer", {
-    message: t.seamSteerMessage(retry, flagModeOn()),
+    message: t.seamSteerMessage(retry, flagged()),
     label: "Steer or overrule the naive pass",
     file: REQUIREMENTS,
     acceptClean: true,
@@ -328,7 +328,7 @@ const tried = async (tip: KeptTip): Promise<t.NaiveTested | undefined> => {
     label: "Applying the naive pass to try it",
   })
   await human("try", {
-    message: t.naiveTryMessage(flagModeOn()),
+    message: t.naiveTryMessage(flagged()),
     label: "Try the naive pass",
     file: NAIVE_TEST,
     acceptClean: true,
@@ -359,7 +359,7 @@ const decide = (): Promise<Decision> =>
         }
       }
       const outcome =
-        verdict ?? (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })
+        verdict ?? (flagged() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })
       if (!("kind" in outcome)) return outcome
       retry = outcome.kind === "retry" ? outcome.retry : undefined
     }

package/src/workflows/feature/standards.feature

@@ -12,7 +12,6 @@ Feature: the review learns standards from the human's answers
   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

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

@@ -30,16 +30,9 @@ 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("refuse the removed flagMode option", () => {
+    expect(defaults.flagMode).toBeUndefined()
+    expect(configure(feature({ flagMode: false } as never))).toMatchObject({ ok: false })
   })
 
   it("declare flag_risk_tier off by default; it is no factory option", () => {

package/src/workflows/shared/options.ts

@@ -27,7 +27,6 @@ export const ShippedOptions = Schema.Struct({
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,
-  flagMode: Schema.optionalWith(Schema.Boolean, { exact: true }),
   naiveTest: Schema.optionalWith(Schema.Boolean, { exact: true }),
 })
 
@@ -45,14 +44,6 @@ const over = (
   ),
 })
 
-/** 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"
-}
-
 /** The `naiveTest` setting, pinned at process start. Anything but true/false fails rather than guess. */
 export const naiveTestOn = (): boolean => {
   const value = vars.naiveTest ?? defaults.naiveTest!