@pmelab/gtd 57.0.0 → 58.1.0

package/dist/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
-import { Ct as envDefaults, Ft as flagReferences, Lt as registryEntry, Rt as requireFlag, S as coder, St as defaults, i as skills, n as summary, o as flagShipped, r as access, t as steering } from "../chunks/reserved-X2RkNHin.mjs";
-import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-S04KEewi.mjs";
+import { It as registryEntry, Lt as requireFlag, Pt as flagReferences, St as envDefaults, a as flagShipped, i as skills, n as summary, r as access, t as steering, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
+import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-Bd7L940p.mjs";
 //#region src/workflows/cleanup/cleanup.ts
 const removingPrompt = (name, registry) => `Clean up the release flag "${name}", which is default-on: delete its entry in ${registry}, and remove every \`GTD_FLAG_${name.toUpperCase()}\` check from the shipped sources. Keep the flag-on path; delete code only the off path reached, including tests that pin the off path.`;
 const cleanupFlow = async () => {

package/dist/workflows/feature.mjs

@@ -1,8 +1,8 @@
 import { agent, answered, applyScript, changes, changesSince, check, codeChanges, env, hasThreadFor, head, human, judge, judgeDiffShape, kept, mark, matches, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars, wrote } from "../flows.mjs";
 import { lensEntriesOf } from "../workflow-kit.mjs";
-import { $ as naiveTryMessage, B as designImpactPrompt, C as collecting, Ct as envDefaults, F as builderSystem, H as designTriagePrompt, I as clearCriteriaMessage, J as idleMessage, L as clearCriteriaQuestion, M as agentWithSkills, N as buildReviewCollectingPrompt, O as planner, Q as naivePassPrompt, R as criterionLine, S as coder, St as defaults, T as fixNits, V as designSystem, X as implementFixPrompt, Y as implementBuildingPrompt, Z as naiveApplyFailure, _ as REFACTOR_NOTE, _t as startGateBlockedMessage, a as flagModeOn, at as refactorDroppedRefusal, b as answerReviewQuestions, c as shipped, ct as refactorRules, f as healthy, g as REFACTOR, gt as seamSteerMessage, ht as seamByHandMessage, i as skills, it as refactorBuildingPrompt, m as NAIVE_TEST, mt as reviewerSystem, n as summary, ot as refactorFixPrompt, p as FEEDBACK, r as access, s as naiveTestOn, st as refactorNotePrompt, t as steering, tt as normaliseCriteriaScript, u as gate, v as REQUIREMENTS, vt as unwindFailedMessage, wt as testFileGlobs, yt as unwindFailure, z as designGateAnswerMessage } from "../chunks/reserved-X2RkNHin.mjs";
-import { a as refusePendingHandOff } from "../chunks/tail-S04KEewi.mjs";
-import { n as isCode$1, r as reUnwind, t as buildTail } from "../chunks/review-v7sh5GF4.mjs";
+import { B as designSystem, Ct as testFileGlobs, D as planner, F as clearCriteriaMessage, I as clearCriteriaQuestion, J as implementBuildingPrompt, L as criterionLine, M as buildReviewCollectingPrompt, P as builderSystem, Q as naiveTryMessage, R as designGateAnswerMessage, S as collecting, St as envDefaults, V as designTriagePrompt, X as naiveApplyFailure, Y as implementFixPrompt, Z as naivePassPrompt, _ as REQUIREMENTS, _t as unwindFailedMessage, at as refactorFixPrompt, d as healthy, et as normaliseCriteriaScript, f as FEEDBACK, g as REFACTOR_NOTE, gt as startGateBlockedMessage, h as REFACTOR, ht as seamSteerMessage, i as skills, it as refactorDroppedRefusal, j as agentWithSkills, l as gate, mt as seamByHandMessage, n as summary, o as naiveTestOn, ot as refactorNotePrompt, p as NAIVE_TEST, pt as reviewerSystem, q as idleMessage, r as access, rt as refactorBuildingPrompt, s as shipped, st as refactorRules, t as steering, vt as unwindFailure, w as fixNits, x as coder, xt as defaults, y as answerReviewQuestions, z as designImpactPrompt } from "../chunks/reserved-lMYCaapY.mjs";
+import { a as refusePendingHandOff } from "../chunks/tail-Bd7L940p.mjs";
+import { n as isCode$1, r as reUnwind, t as buildTail } from "../chunks/review-Bfaror38.mjs";
 import { posix } from "node:path";
 //#region src/workflows/shared/fences.ts
 const markFenced = (text) => {
@@ -23,6 +23,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;
@@ -114,14 +151,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();
 };
@@ -138,12 +176,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. */
@@ -190,6 +228,7 @@ const impact = async () => {
 	requireCriteriaFrozen(REQUIREMENTS);
 	requireImpact(REQUIREMENTS);
 	requireImpactOnly(REQUIREMENTS);
+	requireReleaseFlag(REQUIREMENTS);
 };
 /**
 * The skip path: when the sketch stated clear, checkable criteria, write them
@@ -293,6 +332,7 @@ const design = (base, guard) => scope("design", async () => {
 		requireReplies(REQUIREMENTS);
 		requireCriteria(REQUIREMENTS);
 		requireImpact(REQUIREMENTS);
+		requireReleaseFlag(REQUIREMENTS);
 		guard?.();
 	} while (await noteGate(REQUIREMENTS, answerProductQuestions));
 });
@@ -658,7 +698,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(),
@@ -685,7 +725,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
@@ -764,7 +804,7 @@ const tried = async (tip) => {
 	const before = head();
 	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
@@ -798,7 +838,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
 		});
@@ -867,7 +907,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) => {
@@ -959,7 +999,6 @@ const ordinaryStart = async () => {
 		file: ".gtd/TODO.md"
 	});
 	refusePendingHandOff();
-	flagModeOn();
 	naiveTestOn();
 	const stated = statedCriteria(changes(), head());
 	await unwind();

package/dist/workflows/fix.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { b as reviewNotes, x as reviewRisks } from "../chunks/steering-CCNvngSH.mjs";
-import { Ct as envDefaults, G as finisherSystem, K as fixReviewNotesPrompt, M as agentWithSkills, S as coder, St as defaults, c as shipped, i as skills, l as baseline, n as summary, r as access, t as steering, y as REVIEW } from "../chunks/reserved-X2RkNHin.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-S04KEewi.mjs";
+import { G as fixReviewNotesPrompt, St as envDefaults, W as finisherSystem, c as baseline, i as skills, j as agentWithSkills, n as summary, r as access, s as shipped, t as steering, v as REVIEW, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-Bd7L940p.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, start } from "../flows.mjs";
-import { Ct as envDefaults, G as finisherSystem, M as agentWithSkills, S as coder, St as defaults, c as shipped, dt as reviewFeedbackFixPrompt, ft as reviewGateBlockedMessage, i as skills, n as summary, r as access, t as steering, u as gate, v as REQUIREMENTS } from "../chunks/reserved-X2RkNHin.mjs";
-import { a as refusePendingHandOff } from "../chunks/tail-S04KEewi.mjs";
-import { r as reUnwind, t as buildTail } from "../chunks/review-v7sh5GF4.mjs";
+import { St as envDefaults, W as finisherSystem, _ as REQUIREMENTS, dt as reviewGateBlockedMessage, i as skills, j as agentWithSkills, l as gate, n as summary, r as access, s as shipped, t as steering, ut as reviewFeedbackFixPrompt, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
+import { a as refusePendingHandOff } from "../chunks/tail-Bd7L940p.mjs";
+import { r as reUnwind, t as buildTail } from "../chunks/review-Bfaror38.mjs";
 //#region src/workflows/review/review.ts
 const fixFeedback = async () => {
 	await agentWithSkills("feedback.fixing", reviewFeedbackFixPrompt(), {

package/dist/workflows/rollout.mjs

@@ -1,5 +1,5 @@
 import { agent, changesSince, glob, head, mark, read, refuse, removeScript, run, scope, vars } from "../flows.mjs";
-import { Ct as envDefaults, It as flipProblems, Pt as flagMentions, Rt as requireFlag, S as coder, St as defaults, i as skills, n as summary, o as flagShipped, p as FEEDBACK, r as access, t as steering, u as gate } from "../chunks/reserved-X2RkNHin.mjs";
+import { Ft as flipProblems, Lt as requireFlag, Nt as flagMentions, St as envDefaults, a as flagShipped, f as FEEDBACK, i as skills, l as gate, n as summary, r as access, t as steering, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
 //#region src/workflows/rollout/rollout.ts
 const flippingPrompt = (name, registry) => `Roll out the release flag "${name}": in ${registry}, set \`defaultOn: true\` on its entry. Change nothing else — no other entry, no other field, no other file, no comments.`;
 const suiteBlockedMessage = () => "The suite is red after the rollout. Fix it by hand — a rollout may only touch the flag's registry entry — then land.";

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.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -66,6 +66,11 @@
       "types": "./src/testkit/index.ts",
       "source": "./src/testkit/index.ts",
       "default": "./dist/testkit.mjs"
+    },
+    "./testkit/gherkin": {
+      "types": "./src/gherkin/index.ts",
+      "source": "./src/gherkin/index.ts",
+      "default": "./dist/testkit/gherkin.mjs"
     }
   },
   "files": [
@@ -76,6 +81,8 @@
     "src/wire/",
     "src/steering/",
     "src/testkit/",
+    "src/twins/",
+    "src/gherkin/",
     "src/cli/",
     "src/edge/",
     "src/emit/",

package/src/cli/Cli.test.ts

@@ -25,7 +25,7 @@ import {
 import { EXIT_CODES, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
 import { Host } from "../platform/index.js"
 import { type CommandRequirements } from "./Cli.js"
-import { InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
 import { CONFIG_SCAFFOLD } from "../install/index.js"
 
 const FLAG_NAMES = [

package/src/cli/History.test.ts

@@ -1,6 +1,6 @@
 import { Effect, Exit } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
 import { runCli } from "./index.js"
 import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
 

package/src/cli/Metrics.test.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
 import { runCli } from "./index.js"
 import { processMetrics, readProcessMetrics, totalMetrics, type MetricCommit } from "./Metrics.js"
 

package/src/cli/Program.test.ts

@@ -18,7 +18,7 @@ vi.mock("node:os", async (importOriginal) => ({
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
 import { needsOf, runCommand, SelectorUsageError } from "./Program.js"
-import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
 import {
   commitAll,
   DID_NOT_RUN_COMMENT,

package/src/cli/Strays.test.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
 import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_STRAYS_FOUND } from "../wire/index.js"
-import { InMemRepo, makeCapturingCliIo } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo } from "../twins/index.js"
 import { runCli } from "./index.js"
 
 const seed = (): InMemRepo => {

package/src/edge/Edge.test.ts

@@ -31,7 +31,7 @@ import {
   makeCapturingCliIo,
   makeInMemoryWorkspaceOps,
   testLayers,
-} from "../testkit/index.js"
+} from "../twins/index.js"
 
 type Env = Readonly<Record<string, string | undefined>>
 type Files = Readonly<Record<string, string>>

package/src/emit/Emit.ts

@@ -110,7 +110,7 @@ export const emitScripts = (
   optional: assembleScript(optional),
 })
 
-/** Exported so `src/testkit/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
+/** Exported so `src/twins/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
 export const DID_NOT_RUN_COMMENT =
   "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn"
 

package/src/emit/GitScript.ts

@@ -130,7 +130,7 @@ export const fetchHistoryRefs = (remote: string): string =>
 // No test asserts the two stay byte-identical; a drift between them is a
 // review-time risk this boundary accepts.
 
-/** Marks an emitted block as print-only — mirrors `OutcomeScript.ts`'s `OUTCOME_MARKER` verbatim, so `src/testkit/EmittedScriptRecognizer.ts` recognizes either path's output identically. */
+/** Marks an emitted block as print-only — mirrors `OutcomeScript.ts`'s `OUTCOME_MARKER` verbatim, so `src/twins/EmittedScriptRecognizer.ts` recognizes either path's output identically. */
 const OUTCOME_MARKER = "# gtd: outcome (print-only)"
 
 const printfLine = (fmt: string, args: readonly string[]): string =>

package/src/emit/OutcomeScript.ts

@@ -19,7 +19,7 @@ const printfLine = (fmt: string, args: readonly string[]): string =>
 
 /**
  * Marks an emitted block as print-only. Load-bearing beyond documentation:
- * `src/testkit/EmittedScriptRecognizer.ts` recognizes an outcome block by
+ * `src/twins/EmittedScriptRecognizer.ts` recognizes an outcome block by
  * this line, and a bare `printf` would be ambiguous with a workflow
  * `script:` command that happens to start the same way.
  */