@pmelab/gtd 57.0.0 → 58.0.0

package/dist/workflows.mjs

@@ -17636,7 +17636,6 @@ const defaults = {
 	standardMinP: "0.8",
 	refactorFlagPattern: "\\bGTD_FLAG_\\w+",
 	seamAllow: [...testFileGlobs, ".gtd/**"].join(", "),
-	flagMode: "true",
 	naiveTest: "false",
 	flag_risk_tier: "0",
 	qualityReviews: "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge, criteria-coverage",
@@ -18070,6 +18069,18 @@ in its docs or agent instructions (\`AGENTS.md\`, \`CLAUDE.md\`). When
 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
 
@@ -18109,7 +18120,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 --
@@ -18179,11 +18190,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\`
 `;
 const clearCriteriaQuestion = {
@@ -18242,6 +18254,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 : ""}`;
 const builderSystem = () => `${builderPersona}
 
@@ -18921,21 +18934,22 @@ const afterRefactorLine = (rebuild) => `- A reviewed refactor has just landed an
   though never a release flag. Build only what is still missing, held to every
   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, tier, amend) => !flagMode ? "- Add no release flag — this project ships without release flags" : tier === "low" ? "- Add no release flag — this change is low risk tier" : 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`;
-const implementBuildingPrompt = (reference, tier, amend, afterRefactor, flagMode = true, rebuild = {}) => `${stateFileRules}
+const flagLine = (flag, amend) => 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, as the requirements ask,
+  following the repository's flag conventions`;
+const implementBuildingPrompt = (reference, amend, afterRefactor, flag = { kind: "none" }, rebuild = {}) => `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
 ${impactHints}
 ${criteriaBinding(true)}
 ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${amend === true ? `- The change already exists in the tree from an earlier lap; amend it to meet
   the re-derived requirements instead of rewriting it
-` : flagMode ? `- Implement them properly, fitting the codebase's seams and conventions
+` : 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
   restructure, abstract or refactor around the change
 `}${reference === void 0 || amend === true ? "" : `- Reference only: \`git show ${reference}\` shows an earlier naive attempt.
   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
@@ -18954,7 +18968,7 @@ An edit together with an approval counts as steer. Only
 \`.gtd/REQUIREMENTS.md\` is meant to change here: any other edit lands on the
 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). */
 const seamSteerMessage = (retry, judged = true) => isFault(retry) ? `The naive pass failed three times and the retries are spent. The last
 attempt's tests (\`git show ${retry.hash}\`) fall short:
 ${retry.fault}
@@ -38602,19 +38616,12 @@ const ShippedOptions = Struct({
 	testCommand: setting,
 	plannerModel: setting,
 	coderModel: setting,
-	flagMode: optionalWith(Boolean$, { exact: true }),
 	naiveTest: optionalWith(Boolean$, { exact: true })
 });
 const over = (base, options) => ({
 	...base,
 	...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. */
-const flagModeOn = () => {
-	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. */
 const naiveTestOn = () => {
 	const value = vars.naiveTest ?? defaults.naiveTest;
@@ -39032,6 +39039,43 @@ const HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
 /** A list item, its checkbox dropped: its text. */
 const ITEM = /^ ?(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.*)$/;
 //#endregion
+//#region src/workflows/feature/release-flag.ts
+const NAME = /^existing:\s*`?([A-Za-z_][\w.-]*)`?$/i;
+const isFlagHeading = (h) => 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) => {
+	const lines = markFenced(text);
+	const at = lines.findIndex((l) => !l.fenced && isFlagHeading(HEADING.exec(l.line)));
+	if (at === -1) return void 0;
+	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. */
+const releaseFlagOf = (text) => {
+	const line = requestLine(text);
+	if (line === void 0 || /^none$/i.test(line)) return { kind: "none" };
+	if (/^new$/i.test(line)) return { kind: "new" };
+	const name = NAME.exec(line)?.[1];
+	return name === void 0 ? { unreadable: line } : {
+		kind: "existing",
+		name
+	};
+};
+/** Refuse `file` when its `## Release Flag` section is neither `none`, `new` nor `existing: <NAME>`. */
+const requireReleaseFlag = (file) => {
+	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. */
+const requestedFlag = () => {
+	requireReleaseFlag(REQUIREMENTS);
+	return releaseFlagOf(read(".gtd/REQUIREMENTS.md") ?? "");
+};
+/** Whether the change goes behind a release flag: only then does the seam judge rule. */
+const flagged = () => requestedFlag().kind !== "none";
+//#endregion
 //#region src/workflows/feature/criteria.ts
 /** Below this the judge's `yes` is not trusted: a wrong skip builds against criteria nobody can check. */
 const CLEAR_MIN_P = .8;
@@ -39123,14 +39167,15 @@ const requireCriteria = (file) => {
 	refuse(`gtd land: acceptance-criteria: ${file} has ${criteria.length === 0 ? `no "## Acceptance Criteria" list` : unnamed.length > 0 ? `${unnamed.length} criterion without an ID:\n${unnamed.map((c) => `  - ${c.text}`).join("\n")}` : `duplicate IDs: ${[...new Set(twice)].join(", ")}`} — list every criterion under "## Acceptance Criteria" as "- AC-<n>: <checkable criterion>", each ID unique and never reused`);
 };
 const isImpactHeading = (h) => h !== null && h[1].length === 2 && /^impact$/i.test(h[2].trim());
+const isImpactTurnHeading = (h) => h !== null && h[1].length === 2 && /^(impact|release flag)$/i.test(h[2].trim());
 /** Whether `text` has an unfenced, level-2 `## Impact` heading. */
 const hasImpact = (text) => markFenced(text).some((l) => !l.fenced && isImpactHeading(HEADING.exec(l.line)));
-/** `text` without its `## Impact` section, whitespace collapsed. */
+/** `text` without its `## Impact` and `## Release Flag` sections, whitespace collapsed. */
 const withoutImpact = (text) => {
 	let inImpact = false;
 	return markFenced(text).filter((l) => {
 		const h = l.fenced ? null : HEADING.exec(l.line);
-		if (h !== null && h[1].length <= 2) inImpact = isImpactHeading(h);
+		if (h !== null && h[1].length <= 2) inImpact = isImpactTurnHeading(h);
 		return !inImpact;
 	}).map((l) => l.line).join(" ").replace(/\s+/g, " ").trim();
 };
@@ -39147,12 +39192,12 @@ const requireImpact = (file) => {
 	if (hasImpact(text)) return;
 	refuse(`gtd land: impact: ${file} has no "## Impact" section — explore the codebase and add "## Impact" naming the units, public surfaces and surprises this change touches`);
 };
-/** Refuse a turn that changed `file` beyond its `## Impact` section. */
+/** Refuse a turn that changed `file` beyond its `## Impact` and `## Release Flag` sections. */
 const requireImpactOnly = (file) => {
 	const change = changes().get(file);
 	if (change === void 0) return;
 	if (withoutImpact(change.before ?? "") === withoutImpact(change.after ?? "")) return;
-	refuse(`gtd land: impact-only: this turn may only add "## Impact" to ${file} — restore everything else`);
+	refuse(`gtd land: impact-only: this turn may only add "## Impact" (and "## Release Flag") to ${file} — restore everything else`);
 };
 const idNumber = (id) => Number(id.slice(3));
 /** Why `listed` renumbers or reuses an earlier ID; `undefined` when it does neither. */
@@ -39199,6 +39244,7 @@ const impact = async () => {
 	requireCriteriaFrozen(REQUIREMENTS);
 	requireImpact(REQUIREMENTS);
 	requireImpactOnly(REQUIREMENTS);
+	requireReleaseFlag(REQUIREMENTS);
 };
 /**
 * The skip path: when the sketch stated clear, checkable criteria, write them
@@ -39302,6 +39348,7 @@ const design = (base, guard) => scope("design", async () => {
 		requireReplies(REQUIREMENTS);
 		requireCriteria(REQUIREMENTS);
 		requireImpact(REQUIREMENTS);
+		requireReleaseFlag(REQUIREMENTS);
 		guard?.();
 	} while (await noteGate(REQUIREMENTS, answerProductQuestions));
 });
@@ -40088,7 +40135,7 @@ const applied = async (tip) => {
 	return !wrote(".gtd/FEEDBACK.md") && codeChanges().length > 0;
 };
 const build = async (options) => {
-	await agentWithSkills("building", implementBuildingPrompt(options.reference, options.tier, options.amend, options.afterRefactor, flagModeOn(), options.rebuild), {
+	await agentWithSkills("building", implementBuildingPrompt(options.reference, options.amend, options.afterRefactor, requestedFlag(), options.rebuild), {
 		label: "Implementing",
 		model: coder(),
 		system: builderSystem(),
@@ -40115,7 +40162,7 @@ const implementing = (options) => scope("implement", async () => {
 /** Resolves `true` when the human steered (edited), `false` on a clean overrule. */
 const steer = async (retry) => {
 	await human("steer", {
-		message: seamSteerMessage(retry, flagModeOn()),
+		message: seamSteerMessage(retry, flagged()),
 		label: "Steer or overrule the naive pass",
 		file: REQUIREMENTS,
 		acceptClean: true
@@ -40194,7 +40241,7 @@ const tried = async (tip) => {
 	const before = head$1();
 	await run("applying", applyScript(tip.hash, FEEDBACK, naiveApplyFailure(tip.hash), [".gtd"]), { label: "Applying the naive pass to try it" });
 	await human("try", {
-		message: naiveTryMessage(flagModeOn()),
+		message: naiveTryMessage(flagged()),
 		label: "Try the naive pass",
 		file: NAIVE_TEST,
 		acceptClean: true
@@ -40228,7 +40275,7 @@ const decide = () => scope("seam", async () => {
 				continue;
 			}
 		}
-		const outcome = verdict ?? (flagModeOn() ? await ruled(tip, vetting.again) : {
+		const outcome = verdict ?? (flagged() ? await ruled(tip, vetting.again) : {
 			reference: tip.hash,
 			tip
 		});
@@ -40297,7 +40344,7 @@ const unwind = () => {
 	return run("unwind", revertScript(commit, FEEDBACK, unwindFailure(commit)), { label: "Unwinding your input" });
 };
 /**
-* A naive pass (judged only with `flagMode` on), then implement and the
+* A naive pass (judged only when a release flag is asked for), then implement and the
 * quality lap, then the review; design must have run since `firstBase`.
 */
 const buildFeature = async (firstBase) => {
@@ -40389,7 +40436,6 @@ const ordinaryStart = async () => {
 		file: ".gtd/TODO.md"
 	});
 	refusePendingHandOff();
-	flagModeOn();
 	naiveTestOn();
 	const stated = statedCriteria(changes(), head$1());
 	await unwind();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "57.0.0",
+  "version": "58.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/workflows/feature/acceptance-criteria.feature

@@ -39,6 +39,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -67,6 +71,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - `greeting` reads "Hello, world".
@@ -82,6 +90,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -98,6 +110,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -131,6 +147,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hi".
@@ -150,6 +170,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         """
         # Requirements
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -178,6 +202,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hi".
@@ -226,6 +254,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".

package/src/workflows/feature/criteria-coverage.feature

@@ -8,7 +8,6 @@ Feature: the criteria-coverage lens checks the change's tests against its criter
   Background:
     Given the shipped workflows, as gtd install scaffolds them
     And an environment variable "GTD_QUALITYREVIEWS" set to "criteria-coverage"
-    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/criteria.ts

@@ -13,6 +13,7 @@ import {
 import { HEADING, ITEM, markFenced } from "../shared/fences.js"
 import { planner, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
+import { requireReleaseFlag } from "./release-flag.js"
 
 export interface Criterion {
   readonly id: string
@@ -137,16 +138,20 @@ export const requireCriteria = (file: string): void => {
 const isImpactHeading = (h: RegExpExecArray | null): boolean =>
   h !== null && h[1]!.length === 2 && /^impact$/i.test(h[2]!.trim())
 
+// The skip path's impact turn may write both: a sketch can ask for a flag.
+const isImpactTurnHeading = (h: RegExpExecArray | null): boolean =>
+  h !== null && h[1]!.length === 2 && /^(impact|release flag)$/i.test(h[2]!.trim())
+
 /** Whether `text` has an unfenced, level-2 `## Impact` heading. */
 export const hasImpact = (text: string): boolean =>
   markFenced(text).some((l) => !l.fenced && isImpactHeading(HEADING.exec(l.line)))
 
-/** `text` without its `## Impact` section, whitespace collapsed. */
+/** `text` without its `## Impact` and `## Release Flag` sections, whitespace collapsed. */
 const withoutImpact = (text: string): string => {
   let inImpact = false
   const kept = markFenced(text).filter((l) => {
     const h = l.fenced ? null : HEADING.exec(l.line)
-    if (h !== null && h[1]!.length <= 2) inImpact = isImpactHeading(h)
+    if (h !== null && h[1]!.length <= 2) inImpact = isImpactTurnHeading(h)
     return !inImpact
   })
   return kept
@@ -172,13 +177,13 @@ export const requireImpact = (file: string): void => {
   )
 }
 
-/** Refuse a turn that changed `file` beyond its `## Impact` section. */
+/** Refuse a turn that changed `file` beyond its `## Impact` and `## Release Flag` sections. */
 export const requireImpactOnly = (file: string): void => {
   const change = changes().get(file)
   if (change === undefined) return
   if (withoutImpact(change.before ?? "") === withoutImpact(change.after ?? "")) return
   refuse(
-    `gtd land: impact-only: this turn may only add "## Impact" to ${file} — restore everything else`,
+    `gtd land: impact-only: this turn may only add "## Impact" (and "## Release Flag") to ${file} — restore everything else`,
   )
 }
 
@@ -240,6 +245,7 @@ const impact = async (): Promise<void> => {
   requireCriteriaFrozen(REQUIREMENTS)
   requireImpact(REQUIREMENTS)
   requireImpactOnly(REQUIREMENTS)
+  requireReleaseFlag(REQUIREMENTS)
 }
 
 /**

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

@@ -41,6 +41,10 @@ Feature: a trivial change takes the same few beats at either risk tier
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

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

@@ -302,38 +302,9 @@ describe("an in-flight process from before the architecture path was removed", (
   })
 })
 
-describe("flagMode", () => {
-  const config = (workflow: string): string =>
-    [
-      'import { feature } from "@pmelab/gtd/workflows/feature"',
-      'export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"',
-      `export default ${workflow}`,
-      "",
-    ].join("\n")
-
-  const designed = async (workflow: string, env: Record<string, string> = {}) => {
-    const repo = testRepo({ workflow, env: { GTD_QUALITYREVIEWS: "", ...env } })
-    repo.write("src/calc.ts", CALC)
-    repo.commit("feat: add calculator")
-    repo.write("TODO.md", "# Add subtract\n")
-    return repo.drive({
-      unwind: () => undefined,
-      "start-gate.check": () => undefined,
-      "design.triage": (_, r) =>
-        r.write(
-          ".gtd/REQUIREMENTS.md",
-          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
-        ),
-      "design.gate.answer": () => undefined,
-    })
-  }
-
-  it("set on explicitly, runs the naive pass like the default", async () => {
-    expect((await designed(config("feature({ flagMode: true })"))).state).toBe("seam.naive")
-  })
-
-  it("off through GTD_FLAGMODE=false, lands the naive pass with no seam judge", async () => {
-    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_FLAGMODE: "false" } })
+describe("release flag", () => {
+  it("with no Release Flag section, lands the naive pass with no seam judge", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD })
     repo.write("src/calc.ts", CALC)
     repo.commit("feat: add calculator")
     repo.write("TODO.md", "# Add subtract\n")
@@ -357,13 +328,6 @@ describe("flagMode", () => {
     expect(repo.read("src/calc.ts")).toBe(`${CALC}// naive\n`)
     expect(repo.subjects().some((subject) => subject.includes("seam.judge"))).toBe(false)
   })
-
-  it("refuses a value other than true or false before the process starts", async () => {
-    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_FLAGMODE: "off" } })
-    repo.write("TODO.md", "# Add subtract\n")
-    await expect(repo.drive({})).rejects.toThrow('flagMode must be "true" or "false", got "off"')
-    expect(repo.subjects()).toEqual(["chore: initial commit"])
-  })
 })
 
 // pins the public re-exports from the feature entry point

package/src/workflows/feature/feature.ts

@@ -9,7 +9,7 @@ import {
   start,
 } from "../../flows/index.js"
 import { gate } from "../shared/health.js"
-import { flagModeOn, naiveTestOn, shipped } from "../shared/options.js"
+import { naiveTestOn, shipped } from "../shared/options.js"
 import { FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
 import { refusePendingHandOff } from "../shared/tail.js"
 import * as t from "../shared/text.js"
@@ -29,7 +29,7 @@ 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
 // green-baseline gate → design → a naive pass, tried by a person with
-// `naiveTest` on and judged with `flagMode` on: it
+// `naiveTest` on and judged when the requirements ask for a release flag: it
 // lands as the implementation, or (refactoring first when the judge asks) is
 // built fresh from → the health loop → the triaged quality lap and its finding gate → a
 // reviewer's walkthrough of the whole change for the human, which signs off
@@ -46,7 +46,7 @@ export const unwind = (): Promise<void> => {
 export { reUnwind }
 
 /**
- * A naive pass (judged only with `flagMode` on), then implement and the
+ * A naive pass (judged only when a release flag is asked for), then implement and the
  * quality lap, then the review; design must have run since `firstBase`.
  */
 export const buildFeature = async (firstBase: string): Promise<void> => {
@@ -139,7 +139,6 @@ export const ordinaryStart = async (): Promise<void> => {
   await human("idle", { message: t.idleMessage(), label: "Idle", file: ".gtd/TODO.md" })
   refusePendingHandOff()
   // Read right after idle, so a bad value refuses the landing that would pin it.
-  flagModeOn()
   naiveTestOn()
   const stated = statedCriteria(changes(), head())
   await unwind()

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

@@ -11,7 +11,6 @@ Feature: each quality lens runs on its own model hint
       import { feature } from "@pmelab/gtd/workflows/feature"
       export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
       export default feature({
-        flagMode: false,
         qualityReviews: "correctness, conventions, test-audit=opus",
       })
       """

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

@@ -12,7 +12,6 @@ Feature: the quality lap's findings are triaged, then decided at the finding gat
   Background:
     Given the shipped workflows, as gtd install scaffolds them
     And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
-    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/naive-acceptance.feature

@@ -31,6 +31,10 @@ Feature: a naive pass ends only when its tests reach no file it added and the su
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(5, 3)` returns 2.

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

@@ -4,19 +4,20 @@ 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, or straight to the implementation with `flagMode` off. Notes in
+  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 flagMode off
+  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({ flagMode: false, naiveTest: true })
+        export default feature({ naiveTest: true })
         """
       And an environment variable "GTD_QUALITYREVIEWS" set to ""
       And a file "src/calc.ts" with:
@@ -177,7 +178,7 @@ Feature: a person tries the naive pass by hand before anything builds on it
         gtd(check): seam.applying → seam.try
         """
 
-  Rule: with flagMode on
+  Rule: with a release flag asked for
 
     Background:
       Given a gtd config with:
@@ -208,7 +209,11 @@ Feature: a person tries the naive pass by hand before anything builds on it
 
         - the calculator module
 
-        ## Acceptance Criteria
+        ## Release Flag
+
+      new
+
+      ## Acceptance Criteria
 
         - AC-1: subtract(a, b) returns a - b.
         """
@@ -226,7 +231,7 @@ Feature: a person tries the naive pass by hand before anything builds on it
       And step "seam.applying" runs its script
       And step "seam.restoring" runs its script
 
-    Scenario: with flagMode on the person tries the pass before the seam judge rules
+    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"

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

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

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

@@ -39,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.