@pmelab/gtd 57.0.0 → 58.1.0

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!

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

@@ -912,45 +912,53 @@ describe("the seam phase's texts", () => {
     expect(prompt).not.toContain("rejected")
   })
 
-  it("cites the reference as reading material only and asks for a new release flag", () => {
+  it("cites the reference as reading material only", () => {
     const prompt = renderText(() => implementBuildingPrompt("abc123"))
     expect(prompt).toContain("git show abc123")
     expect(prompt).toContain("never apply")
-    expect(prompt).toContain("release flag")
-  })
-
-  it("high and undefined tiers carry the flag bullet; low says to add none", () => {
-    const base = renderText(() => implementBuildingPrompt("abc123"))
-    expect(renderText(() => implementBuildingPrompt("abc123", "high"))).toBe(base)
-    expect(base).toContain("new release flag")
-    const low = renderText(() => implementBuildingPrompt("abc123", "low"))
-    expect(low).toContain("Add no release flag — this change is low risk tier")
-    expect(low).not.toContain("new release flag")
-    expect(low).toContain("git show abc123")
   })
 
   it("drops the git show line when there is no reference", () => {
-    const prompt = renderText(() => implementBuildingPrompt(undefined, "low"))
+    const prompt = renderText(() => implementBuildingPrompt(undefined))
     expect(prompt).not.toContain("git show")
     expect(prompt).not.toContain("Reference only")
-    expect(prompt).toContain("Add no release flag")
-    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")
+  it("asks for no flag and the naive version when the requirements ask for none, on any lap", () => {
+    for (const amend of [false, true]) {
+      const prompt = renderText(() => implementBuildingPrompt(undefined, amend))
+      expect(prompt).toContain("Add no release flag — the requirements ask for none")
       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")
+    expect(renderText(() => implementBuildingPrompt(undefined))).toContain(
+      "the quickest way that works",
+    )
+  })
+
+  it("asks for a new flag, kept on a later lap, when the requirements ask for one", () => {
+    const first = renderText(() => implementBuildingPrompt("abc123", false, false, { kind: "new" }))
+    expect(first).toContain("behind a new release flag, as the requirements ask")
+    expect(first).toContain("Implement them properly")
+    const amend = renderText(() => implementBuildingPrompt(undefined, true, false, { kind: "new" }))
+    expect(amend).toContain("Keep the release flag the earlier lap added")
+  })
+
+  it("names the existing flag the requirements ask for, and asks for no new one", () => {
+    const prompt = renderText(() =>
+      implementBuildingPrompt(undefined, false, false, { kind: "existing", name: "GTD_FLAG_BETA" }),
+    )
+    expect(prompt).toContain("behind the existing flag `GTD_FLAG_BETA`")
+    expect(prompt).toContain("add no new flag")
+    expect(prompt).toContain("Implement them properly")
+  })
+
+  it("explains the Release Flag section at triage, at the impact turn and at the design gate", () => {
+    for (const prompt of [() => designTriagePrompt("base"), () => designImpactPrompt()]) {
+      const text = renderText(prompt)
+      expect(text).toContain("`## Release Flag`")
+      expect(text).toContain("Never add one on your own judgement")
+    }
+    expect(renderText(() => designGateAnswerMessage())).toContain("**Ask for a release flag**")
   })
 
   it("keeps a fix turn to the feedback file's rules", () => {
@@ -992,7 +1000,7 @@ describe("the seam phase's texts", () => {
     expect(message).not.toContain("outside the expected set")
   })
 
-  it("promises no judge on an overrule with flagMode off", () => {
+  it("promises no judge on an overrule when no release flag is asked for", () => {
     for (const retry of [{ red: "abc123" }, { fault: "acceptance-internals: x", hash: "abc123" }]) {
       const message = renderText(() => seamSteerMessage(retry, false))
       expect(message).not.toContain("seam judge")

package/src/workflows/shared/text.ts

@@ -348,6 +348,19 @@ none is declared, fall back to directories and packages. Landing is
 refused while the section is missing.
 `
 
+const releaseFlagBlock = `
+## Release flag
+
+Only when the sketch asks outright for the change to ship behind a
+feature or release flag, \`.gtd/REQUIREMENTS.md\` carries a
+\`## Release Flag\` section whose first line is \`new\` (a new
+flag) or \`existing: <NAME>\` (behind a flag that already exists,
+named as the sketch names it). Never add one on your own judgement:
+without the section the change ships unflagged. A later lap keeps the
+section exactly as the last settled file had it, unless the human
+changed it. Landing is refused while its first line is anything else.
+`
+
 const riskTierBlock = `
 ## Risk tier and production signals
 
@@ -389,7 +402,7 @@ ${footnoteFoldIn}${codeThreadReplies()}
   or both
 - Whichever lap this is, leave \`.gtd/REQUIREMENTS.md\`
   uncommitted and finish once it reflects this lap's own work
-${acceptanceCriteriaBlock}${impactBlock}
+${acceptanceCriteriaBlock}${impactBlock}${releaseFlagBlock}
 Every lap re-explores and leaves \`## Impact\` present. On a return
 lap or review loop-back the human may have edited \`## Impact\` (or
 footnoted it): read that edit from history (\`git log -1 -p --
@@ -461,11 +474,12 @@ ${stateFileRules}
 - The only state file this turn touches is \`.gtd/REQUIREMENTS.md\`
   — no other files for notes or output
 - \`.gtd/REQUIREMENTS.md\` already holds the settled acceptance
-  criteria. Add a \`## Impact\` section and change nothing else — a
-  turn that touches anything outside it is refused
+  criteria. Add a \`## Impact\` section — and a \`## Release Flag\`
+  section when the sketch asks for one — and change nothing else: a
+  turn that touches anything outside them is refused
 - No human reviews this before the build: put any surprise in the
   Impact prose, never as a question
-${impactBlock}
+${impactBlock}${releaseFlagBlock}
 - Leave \`.gtd/REQUIREMENTS.md\` uncommitted and finish once it holds \`## Impact\`
 `
 
@@ -543,6 +557,7 @@ What each change does next (then run \`gtd land\`):
 - **Accept as-is** — change nothing and re-run; the plan stands as written. Refused while a thread is open.
 - **Revise answers** — tick exactly one option per open question (replace \`_your answer_\` for your own) to send it back for the agent to fold your answers in, or delete a question to skip it.
 - **Discuss** — start or continue a thread (\`- H:\`); the agent replies and this gate stops again.
+- **Ask for a release flag** — add \`## Release Flag\` with \`new\` or \`existing: <NAME>\` as its first line, or delete the section to ship unflagged.
 ${riskTier ? RISK_TIER_GATE_LINE : ""}`
 
 export const builderSystem = (): string =>
@@ -1532,26 +1547,28 @@ const afterRefactorLine = (rebuild: Rebuild): string =>
   rule below; if nothing is, ${carries(rebuild) ? "carry over the acceptance tests below and change nothing else" : "change nothing and finish your turn"}
 `
 
-const flagLine = (
-  flagMode: boolean,
-  tier: "low" | "high" | undefined,
-  amend: boolean | undefined,
-): string =>
-  !flagMode
-    ? "- Add no release flag — this project ships without release flags"
-    : tier === "low"
-      ? "- Add no release flag — this change is low risk tier"
+/** What \`## Release Flag\` in \`.gtd/REQUIREMENTS.md\` asks for; no section is \`none\`. */
+export type ReleaseFlag =
+  | { readonly kind: "none" }
+  | { readonly kind: "new" }
+  | { readonly kind: "existing"; readonly name: string }
+
+const flagLine = (flag: ReleaseFlag, amend: boolean | undefined): string =>
+  flag.kind === "none"
+    ? "- Add no release flag — the requirements ask for none"
+    : flag.kind === "existing"
+      ? `- Put the new behaviour behind the existing flag \`${flag.name}\`, as the
+  requirements ask — add no new flag`
       : amend === true
         ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag"
-        : `- Put the new behaviour behind a new release flag, following the
-  repository's flag conventions`
+        : `- Put the new behaviour behind a new release flag, as the requirements ask,
+  following the repository's flag conventions`
 
 export const implementBuildingPrompt = (
   reference: string | undefined,
-  tier?: "low" | "high",
   amend?: boolean,
   afterRefactor?: boolean,
-  flagMode = true,
+  flag: ReleaseFlag = { kind: "none" },
   rebuild: Rebuild = {},
 ): string =>
   `${stateFileRules}
@@ -1563,7 +1580,7 @@ ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
       ? `- The change already exists in the tree from an earlier lap; amend it to meet
   the re-derived requirements instead of rewriting it
 `
-      : flagMode
+      : flag.kind !== "none"
         ? `- Implement them properly, fitting the codebase's seams and conventions
 `
         : `- Implement them the quickest way that works — the naive version. Do not
@@ -1576,7 +1593,7 @@ ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
   Read it for ideas; never apply, cherry-pick or check it out — write
   the change fresh${carries(rebuild) ? ", its acceptance tests excepted (below)" : ""}
 `
-  }${rebuildLines(rebuild)}${flagLine(flagMode, tier, amend)}
+  }${rebuildLines(rebuild)}${flagLine(flag, amend)}
 - Write the tests first, then the code that makes them pass
 ${behaviourTests}
 - Leave \`.gtd/REQUIREMENTS.md\` in place and everything uncommitted, then
@@ -1599,7 +1616,7 @@ An edit together with an approval counts as steer. Only
 branch unjudged.
 `
 
-/** `judged`: whether an overruled pass still meets the seam judge (`flagMode` on). */
+/** `judged`: whether an overruled pass still meets the seam judge (a release flag asked for). */
 export const seamSteerMessage = (retry: NaiveRetry, judged = true): string =>
   isFault(retry)
     ? `The naive pass failed three times and the retries are spent. The last

package/src/workflows/shared/vars.ts

@@ -28,7 +28,6 @@ export const defaults: Readonly<Record<string, string>> = {
   standardMinP: "0.8",
   refactorFlagPattern: "\\bGTD_FLAG_\\w+",
   seamAllow: [...testFileGlobs, ".gtd/**"].join(", "),
-  flagMode: "true",
   // A person tries every green naive pass at `seam.try` before anything builds on it.
   naiveTest: "false",
   // GTD_FLAG_RISK_TIER, recorded at process start; only "1" is on.

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

@@ -1,88 +0,0 @@
-@inmem
-Feature: flag mode off lands the naive pass 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 pass itself lands, 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`.
-
-      ## Impact
-
-      - the greeting module
-
-      ## Acceptance Criteria
-
-      - AC-1: the change behaves as described.
-      """
-    And step "design.gate.answer" changes nothing
-
-  Scenario: flag mode off lands the naive pass unjudged, and asks for no flag
-    When the process is driven
-    Then the process rests at "seam.naive"
-    And the resting step's content contains "the quickest way that works"
-    And the resting step's content does not contain "release flag"
-    Given 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 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 "src/calc.test.ts" contains "[AC-1] subtracts"
-    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 → 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.quality.correctness.reviewing
-      gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
-      """