@pmelab/gtd 27.1.0 → 27.3.0

package/dist/workflows.mjs

@@ -250,9 +250,9 @@ const check = async (name, command, options) => {
 	}), { label });
 	return !wrote(report);
 };
-const isCode$1 = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
+const isCode$2 = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
 /** The last step's changes outside `.gtd/`. */
-const codeChanges = () => changes().filter((c) => isCode$1(c.path));
+const codeChanges = () => changes().filter((c) => isCode$2(c.path));
 /** Refuse a turn whose only change deletes `file` — unless it says it found nothing to do. */
 const requireProgress = (file) => {
 	const change = changes().get(file);
@@ -17235,6 +17235,26 @@ ${fixFeedbackPrompt}
   then legitimately report itself already satisfied later
 - Leave everything uncommitted and finish your turn — do not commit
 `;
+const refactorRules = (strays, pattern) => `- Behaviour-neutral: the suite's outcome must not change
+- Change only these paths, nothing else — a test file only when it is
+  one of them:
+${strays.map((path) => `  - \`${path}\``).join("\n")}
+- Introduce no new flag read and add no second read of an existing one:
+  every match of \`${pattern}\` may move, never increase in number`;
+const refactorBuildingPrompt = (pkg, strays, pattern, reference) => `${stateFileRules}
+- The package to implement is \`${pkg}\`; never delete it
+${refactorRules(strays, pattern)}
+${reference === void 0 ? "" : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
+  earlier attempt at this change. Read it for ideas; never apply,
+  cherry-pick or check it out — write a fresh refactor
+`}- Leave everything uncommitted and finish your turn — do not commit
+`;
+const refactorFixPrompt = (strays, pattern) => `${stateFileRules}
+${fixFeedbackPrompt}
+${refactorRules(strays, pattern)}
+- Never do another package's work, even when it would green the suite
+- Leave everything uncommitted and finish your turn — do not commit
+`;
 const healthJudgeMessage = () => `The check is still red, and this isn't the first round —
 \`.gtd/FEEDBACK.md\` holds this round's output, and the previous round's
 is in history. Run \`gtd judge answer\` and pipe a
@@ -17805,12 +17825,22 @@ const escalationSteps = {
 	stop: escalate,
 	exhausted: escalationExhausted
 };
+const guarded = (turn, guard) => async (...a) => {
+	await turn(...a);
+	guard?.();
+};
+const guardedSteps = (guard, describeGuard) => ({
+	limit: escalationSteps.limit,
+	describe: guarded(guarded(escalationSteps.describe, guard), describeGuard),
+	stop: guarded(escalationSteps.stop, guard),
+	exhausted: guarded(escalationSteps.exhausted, guard)
+});
 /**
 * Hand a red suite that repeated attempts could not fix to a person: an
 * agent writes `.gtd/ESCALATION.md`, a human narrows it. From the third round
 * on, the human is told the budget is spent instead.
 */
-const escalation = (count) => escalation$1(count, escalationSteps);
+const escalation = (count, guard) => escalation$1(count, guardedSteps(guard));
 /** "Is this red round the same failure as the last one?" — asked of two reports, or of nothing when one is empty. */
 const retryQuestion = (comparable) => comparable ? {
 	id: "verdict",
@@ -17846,21 +17876,25 @@ const runSuite = (options) => check("health.check", env.testCommand ?? "", {
 * first once `FIX_CAP` fixes are spent, or a judge calls the failure
 * identical to the previous round's.
 */
-const healthy = (fix, options = {}) => healthy$1(fix, {
+const healthy = (fix, options = {}) => healthy$1(guarded(fix, options.guard), {
 	check: () => runSuite(options),
 	report: FEEDBACK,
 	fixCap: 3,
 	fixesSoFar: options.fixesSoFar ?? 0,
 	sameFailure,
 	escalations: options.escalations ?? { rounds: 0 },
-	escalation: escalationSteps
+	escalation: guardedSteps(options.guard, options.describeGuard)
 });
-/** Hold the process at `<name>.blocked` until the suite is green. */
-const gate = (name, message) => gate$1(name, () => baseline("check"), () => human("blocked", {
+/**
+* Hold the process at `<name>.blocked` until the suite is green. `guard` runs
+* after each `blocked` landing only — never after a check, whose refusal would
+* re-run the same script forever.
+*/
+const gate = (name, message, guard) => gate$1(name, () => baseline("check"), guarded(() => human("blocked", {
 	message,
 	label: "Baseline is red",
 	file: FEEDBACK
-}));
+}), guard));
 //#endregion
 //#region node_modules/effect/dist/esm/Function.js
 /**
@@ -37184,6 +37218,7 @@ const defaults = {
 	judgeIdenticalMinP: "0.7",
 	reviewNoteActionable: "0.7",
 	reviewSeverityMinP: "0.7",
+	refactorFlagPattern: "\\bGTD_FLAG_\\w+",
 	qualityReviews: "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge"
 };
 /** Environment settings. */
@@ -37201,6 +37236,7 @@ const ShippedOptions = Struct({
 	judgeIdenticalMinP: setting,
 	reviewNoteActionable: setting,
 	reviewSeverityMinP: setting,
+	refactorFlagPattern: setting,
 	qualityReviews: setting,
 	testCommand: setting,
 	plannerModel: setting,
@@ -37221,6 +37257,27 @@ const shipped = (flow, doors, base) => defineWorkflow(standardSchemaV1(ShippedOp
 	doors,
 	base
 }));
+const FlagOptions = Struct({
+	...ShippedOptions.fields,
+	flagRegistry: setting
+});
+const flagShipped = (flow) => defineWorkflow(standardSchemaV1(FlagOptions, {
+	onExcessProperty: "error",
+	errors: "all"
+}), (options) => {
+	const flagDefaults = {
+		...defaults,
+		flag: "",
+		flagRegistry: "src/flags/index.ts"
+	};
+	return {
+		flow,
+		defaults: over(flagDefaults, options),
+		envDefaults: over(envDefaults, options),
+		doors: {},
+		base: void 0
+	};
+});
 //#endregion
 //#region src/workflows/shared/tail.ts
 /** The reviewer's own `.gtd/REVIEW.md`, kept beside the human's notes so `fix` can tell them apart. */
@@ -37230,13 +37287,13 @@ const REVIEW_ORIG = ".gtd/REVIEW.orig.md";
 * finding to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
 * has any.
 */
-const qualityLap = () => qualityLap$1(lensesOf(vars.qualityReviews ?? ""), reviewQuality, QUALITY);
+const qualityLap = (guard) => qualityLap$1(lensesOf(vars.qualityReviews ?? ""), guarded(reviewQuality, guard), QUALITY);
 /** Resolves `true` once `.gtd/QUALITY.md` is resolved, `false` when the fix cap escalated instead. */
-const fixQualityFindings = (escalations) => fixFindings({
-	fix: fixQuality,
+const fixQualityFindings = (escalations, guard) => fixFindings({
+	fix: guarded(fixQuality, guard),
 	findings: QUALITY,
 	cap: 3,
-	escalate: () => escalation(escalations)
+	escalate: () => escalation(escalations, guard)
 });
 /** `.gtd/REVIEW.md` removed at the end of a round at commit `round`. */
 const closeReview = (round) => run("review.closing", removeScript([REVIEW, REVIEW_ORIG]), {
@@ -37252,19 +37309,26 @@ const refusePendingHandOff = () => {
 * `finish` — the human review, as the calling workflow runs it. `green`: the
 * caller just left the full suite green (the package loop), so no run opens it.
 */
-const tail = (fixFirst, finish, green = false) => scope("build", async () => {
+const tail = (fixFirst, finish, green = false, guard) => scope("build", async () => {
 	const escalations = { rounds: 0 };
 	const fix = fixCheck;
 	const repair = async () => {
-		await fix();
+		await guarded(fix, guard)();
 		await healthy(fix, {
 			fixesSoFar: 1,
-			escalations
+			escalations,
+			guard
 		});
 	};
 	if (fixFirst) await repair();
-	else if (!green) await healthy(fix, { escalations });
-	if (await qualityLap() === "findings") if (await fixQualityFindings(escalations)) await healthy(fix, { escalations });
+	else if (!green) await healthy(fix, {
+		escalations,
+		guard
+	});
+	if (await qualityLap(guard) === "findings") if (await fixQualityFindings(escalations, guard)) await healthy(fix, {
+		escalations,
+		guard
+	});
 	else await repair();
 	return finish(escalations);
 });
@@ -37273,11 +37337,14 @@ const tail = (fixFirst, finish, green = false) => scope("build", async () => {
 * `.gtd/REVIEW.md`; a note leaves it, with the reviewer's own version as
 * `REVIEW_ORIG`, for the next `fix` to read — never a re-plan.
 */
-const handOffReview = (base, escalations) => reviewToHandOff(base, {
+const handOffReview = (base, escalations, guard) => reviewToHandOff(base, {
 	file: REVIEW,
-	reviewing,
-	fixRisks,
-	keepGreen: () => healthy(fixCheck, { escalations }),
+	reviewing: guarded(reviewing, guard),
+	fixRisks: guarded(fixRisks, guard),
+	keepGreen: () => healthy(fixCheck, {
+		escalations,
+		guard
+	}),
 	awaitReview: (b) => awaitReview(b, handOffAwaitReviewMessage(b)),
 	reviewMissing,
 	close: closeReview,
@@ -37287,7 +37354,7 @@ const handOffReview = (base, escalations) => reviewToHandOff(base, {
 	deleted: "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix."
 });
 /** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
-const handOffTail = (fixFirst, base) => tail(fixFirst, (escalations) => handOffReview(base, escalations));
+const handOffTail = (fixFirst, base, guard) => tail(fixFirst, (escalations) => handOffReview(base, escalations, guard), false, guard);
 //#endregion
 //#region src/workflows/feature/steps.ts
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
@@ -37569,7 +37636,7 @@ const triage$1 = (severities) => async (notes) => {
 		return [n.id, severity.tier === "could" ? "defer" : "edit"];
 	}));
 };
-const isCode = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
+const isCode$1 = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
 /**
 * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
 * reviews and signs off or comments, and each note is judged: edits go to
@@ -37582,7 +37649,7 @@ const review$1 = (base, escalations = { rounds: 0 }) => {
 	return review$2(base, {
 		file: REVIEW,
 		feedback: REQUIREMENTS,
-		isCode,
+		isCode: isCode$1,
 		reviewing: (b, carry) => {
 			deferred = [];
 			return reviewing(b, carry);
@@ -37711,6 +37778,9 @@ const skills = (vars) => ({
 	"build.review.fix.nits": ["incremental-implementation", "code-simplification"],
 	"build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
 	notes: ["incremental-implementation", "code-simplification"],
+	refactor: ["ponytail"],
+	"refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
+	"refactor.health": ["ponytail", "debugging-and-error-recovery"],
 	...lensScopes("build.quality", lensesOf(vars.qualityReviews ?? ""), (lens) => builtInLenses[lens]?.skills ?? [lens])
 });
 //#endregion
@@ -37734,6 +37804,119 @@ const steering = {
 	[REVIEW]: "review"
 };
 //#endregion
+//#region src/workflows/feature/refactor.ts
+const REFACTOR_PACKAGE = ".gtd/REFACTOR.md";
+const isCode = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
+const requireWithin = (allowed) => {
+	const outside = changes().map((c) => c.path).filter((path) => isCode(path) && !allowed.includes(path));
+	if (outside.length === 0) return;
+	refuse(`gtd land: refactor-scope: the refactor may change only its stray paths — revert these:\n${outside.map((path) => `  - ${path}`).join("\n")}`);
+};
+const flagExpression = (pattern) => {
+	if (pattern.trim() === "") throw new Error("gtd: refactorFlagPattern must not be blank");
+	let expression;
+	try {
+		expression = new RegExp(pattern, "g");
+	} catch (error) {
+		throw new Error(`gtd: refactorFlagPattern is not a valid regular expression: ${String(error)}`);
+	}
+	if (expression.test("")) throw new Error("gtd: refactorFlagPattern must not match the empty string");
+	return expression;
+};
+const countFlags = (text, expression, into) => {
+	let zeroLength = false;
+	for (const [name] of text.matchAll(expression)) if (name === "") zeroLength = true;
+	else into.set(name, (into.get(name) ?? 0) + 1);
+	return zeroLength;
+};
+const listPaths = (paths) => paths.map((path) => `  - ${path}`).join("\n");
+const requireNoNewFlags = (pattern, since) => {
+	const expression = flagExpression(pattern);
+	const before = /* @__PURE__ */ new Map();
+	const after = /* @__PURE__ */ new Map();
+	const unreadable = [];
+	const zeroLength = [];
+	for (const { path, status, before: was, after: now } of changesSince(since)) {
+		if (!isCode(path)) continue;
+		const oldSide = status === "added" ? "" : was;
+		const newSide = status === "deleted" ? "" : now;
+		if (oldSide === void 0 || newSide === void 0) {
+			unreadable.push(path);
+			continue;
+		}
+		countFlags(oldSide, expression, before);
+		if (countFlags(newSide, expression, after)) zeroLength.push(path);
+	}
+	if (unreadable.length > 0) refuse(`gtd land: refactor-flags: cannot compare flag reads in:\n${listPaths(unreadable)}`);
+	if (zeroLength.length > 0) refuse(`gtd land: refactor-flags: refactorFlagPattern (${pattern}) produced a zero-length match in:\n${listPaths(zeroLength)}`);
+	const raised = [...after].filter(([name, count]) => count > (before.get(name) ?? 0));
+	if (raised.length === 0) return;
+	refuse(`gtd land: refactor-flags: the refactor may not introduce or add reads of a flag (${pattern}):\n${raised.map(([name, count]) => `  - ${name}: ${before.get(name) ?? 0} → ${count}`).join("\n")}`);
+};
+const packageLines = (strays, pattern, reference) => [
+	"# Behaviour-neutral refactor",
+	"",
+	"## Scope (read-only)",
+	"",
+	...strays.map((path) => `- \`${path}\``),
+	"",
+	"This list is fixed when the package is derived: editing it here widens or narrows nothing.",
+	"",
+	"## Rules",
+	"",
+	"- The suite's outcome must not change",
+	"- Change only the paths above; a test file only when it is one of them",
+	`- Introduce no flag read and add no second read of an existing one (\`${pattern}\`)`,
+	"",
+	"## Reference",
+	"",
+	reference === void 0 ? "None." : `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+	""
+];
+const deriveScript = (lines) => `mkdir -p .gtd
+printf '%s\\n' ${lines.map(quote).join(" ")} > ${quote(REFACTOR_PACKAGE)}
+`;
+const refactorFirst = async (shape, options = {}) => {
+	if (shape.choice !== "refactor-first" || shape.unreadable.length > 0) return false;
+	const pattern = vars.refactorFlagPattern ?? defaults.refactorFlagPattern;
+	const expression = flagExpression(pattern);
+	const { strays } = shape;
+	const zeroLength = strays.filter((path) => countFlags(read(path) ?? "", expression, /* @__PURE__ */ new Map()));
+	if (zeroLength.length > 0) throw new Error(`gtd: refactorFlagPattern (${pattern}) produces a zero-length match in:\n${listPaths(zeroLength)}`);
+	const reference = options.reference?.trim() ? options.reference : void 0;
+	return scope({
+		name: "refactor",
+		access: { write: [...strays, ".gtd/**"] }
+	}, async () => {
+		await run("deriving", deriveScript(packageLines(strays, pattern, reference)), {
+			label: "Deriving the refactor package",
+			file: REFACTOR_PACKAGE
+		});
+		const from = head$1();
+		const guard = () => {
+			requireWithin(strays);
+			requireNoNewFlags(pattern, from);
+		};
+		await agentWithSkills("building", refactorBuildingPrompt(REFACTOR_PACKAGE, strays, pattern, reference), {
+			label: "Refactoring",
+			model: coder(),
+			system: builderSystem()
+		});
+		guard();
+		await healthy(async () => {
+			await agentWithSkills("fix.suite.fixing", refactorFixPrompt(strays, pattern), {
+				label: "Fixing the check",
+				file: FEEDBACK,
+				model: coder(),
+				system: builderSystem()
+			});
+			guard();
+		}, { describeGuard: guard });
+		await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" });
+		return true;
+	});
+};
+//#endregion
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality
@@ -37789,6 +37972,160 @@ const fixFlow = async () => {
 };
 const fix = shipped(fixFlow, { fix: {} });
 //#endregion
+//#region src/workflows/shared/registry.ts
+const FILL = "
";
+const commentLength = (rest) => {
+	const end = rest.startsWith("//") ? rest.indexOf("\n") : rest.indexOf("*/") + 2;
+	return end <= 0 ? rest.length : end;
+};
+const stringEnd = (text, i, quote) => {
+	let j = i + 1;
+	while (j < text.length && text[j] !== quote) j += text[j] === "\\" ? 2 : 1;
+	return Math.min(j, text.length);
+};
+const mask = (text) => {
+	let out = "";
+	let i = 0;
+	while (i < text.length) {
+		const c = text[i];
+		const rest = text.slice(i);
+		if (rest.startsWith("//") || rest.startsWith("/*")) {
+			const len = commentLength(rest);
+			out += FILL.repeat(len);
+			i += len;
+		} else if (c === "\"" || c === "'" || c === "`") {
+			const j = stringEnd(text, i, c);
+			out += c + FILL.repeat(j - i - 1) + (j < text.length ? c : "");
+			i = j + 1;
+		} else {
+			out += c;
+			i += 1;
+		}
+	}
+	return out;
+};
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const entrySpan = (text, name) => {
+	const quoted = escapeRegExp(name);
+	const re = new RegExp(`\\bname\\s*:\\s*(["'\`])${quoted}\\1`, "g");
+	const masked = mask(text);
+	for (const hit of text.matchAll(re)) {
+		if (masked[hit.index] === FILL) continue;
+		const start = masked.lastIndexOf("{", hit.index);
+		const close = masked.indexOf("}", hit.index);
+		return start < 0 || close < 0 ? void 0 : {
+			start,
+			end: close + 1
+		};
+	}
+};
+const DEFAULT_ON = /\bdefaultOn\s*:\s*(true|false)\s*,?/;
+const defaultOnHit = (body) => DEFAULT_ON.exec(mask(body));
+const defaultOnValue = (body) => defaultOnHit(body)?.[1];
+const KIND = /\bkind\s*:\s*["'`]/;
+const registryEntry = (text, name) => {
+	const span = entrySpan(text, name);
+	if (span === void 0) return void 0;
+	const body = text.slice(span.start, span.end);
+	const hit = KIND.exec(mask(body));
+	return {
+		kind: (hit === null ? null : /^(\w+)["'`]/.exec(body.slice(hit.index + hit[0].length)))?.[1] ?? "",
+		defaultOn: defaultOnValue(body) === "true"
+	};
+};
+const canonical = (body) => {
+	const hit = defaultOnHit(body);
+	const kept = hit === null ? body : body.slice(0, hit.index) + body.slice(hit.index + hit[0].length);
+	const masked = mask(kept);
+	return kept.split("").filter((c, i) => masked[i] === FILL || !(/\s/.test(c) || c === "," && /^\s*}/.test(masked.slice(i + 1)))).join("");
+};
+/**
+* [] when `after` differs from `before` only by the named entry's `defaultOn`
+* going absent/false → true (whitespace and trailing commas inside that entry
+* ignored, so oxfmt re-wrapping it passes); else one line per fault.
+*/
+const flipProblems = (before, after, name) => {
+	const was = entrySpan(before, name);
+	const now = entrySpan(after, name);
+	if (was === void 0) return [`no entry "${name}" before the turn`];
+	if (now === void 0) return [`entry "${name}" is gone`];
+	const faults = [];
+	if (before.slice(0, was.start) !== after.slice(0, now.start)) faults.push("text before the entry changed");
+	if (before.slice(was.end) !== after.slice(now.end)) faults.push("text after the entry changed");
+	const oldBody = before.slice(was.start, was.end);
+	const newBody = after.slice(now.start, now.end);
+	if (canonical(oldBody) !== canonical(newBody)) faults.push(`entry "${name}" changed beyond defaultOn`);
+	if (defaultOnValue(newBody) !== "true") faults.push(`"${name}" is not set to defaultOn: true`);
+	return faults;
+};
+/** `path:line` for every `GTD_FLAG_<NAME>` in shipped sources; re-states scripts/lint-flags.ts' rule by hand. */
+const flagReferences = (files, name) => {
+	const pattern = new RegExp(`\\bGTD_FLAG_${escapeRegExp(name.toUpperCase())}\\b`);
+	return files.filter(({ path }) => !/\.(test|fixture|stories)\.tsx?$/.test(path)).flatMap(({ path, text }) => text.split("\n").flatMap((line, i) => pattern.test(line) ? [`${path}:${i + 1}`] : []));
+};
+const requireFlag = (workflow, registryPath, name, defaultOn) => {
+	if (name === "") return refuse(`gtd: ${workflow} needs --var flag=<name>`);
+	const entry = registryEntry(read(registryPath) ?? "", name);
+	if (entry === void 0) return refuse(`gtd: ${workflow}: no flag "${name}" in ${registryPath}`);
+	if (entry.kind !== "release") return refuse(`gtd: ${workflow}: flag "${name}" is ${entry.kind}, not release`);
+	if (entry.defaultOn !== defaultOn) return refuse(defaultOn ? `gtd: ${workflow}: flag "${name}" is not default-on — roll it out first` : `gtd: ${workflow}: flag "${name}" is already default-on`);
+};
+//#endregion
+//#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.";
+const rolloutFlow = async () => {
+	const registry = vars.flagRegistry ?? "";
+	const name = vars.flag ?? "";
+	requireFlag("rollout", registry, name, false);
+	const base = head$1();
+	const before = read(registry) ?? "";
+	const guard = () => {
+		const strays = changesSince(base).paths.filter((path) => path !== registry && path !== ".gtd/FEEDBACK.md");
+		if (strays.length > 0) refuse(`gtd land: rollout-only: ${strays.join(", ")} changed — rollout may only set defaultOn: true on "${name}" in ${registry}`);
+		const problems = flipProblems(before, read(registry) ?? "", name);
+		if (problems.length > 0) refuse(`gtd land: rollout-only: other edits in ${registry}: ${problems.join("; ")}`);
+	};
+	await scope("rollout", async () => {
+		await agent("flipping", flippingPrompt(name, registry), {
+			label: `Rolling out ${name}`,
+			model: coder()
+		});
+		guard();
+		await gate("suite", suiteBlockedMessage(), guard);
+	});
+};
+const rollout = flagShipped(rolloutFlow);
+//#endregion
+//#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 () => {
+	const registry = vars.flagRegistry ?? "";
+	const name = vars.flag ?? "";
+	refusePendingHandOff();
+	requireFlag("cleanup", registry, name, true);
+	let scanned = false;
+	const guard = () => {
+		const turn = scanned ? changes() : void 0;
+		if ((turn === void 0 || turn.some((c) => c.path === registry)) && registryEntry(read(registry) ?? "", name) !== void 0) refuse(`gtd land: cleanup: ${registry} still declares flag "${name}"`);
+		const hits = flagReferences((turn === void 0 ? [...glob("src/**/*.ts"), ...glob("src/**/*.tsx")] : turn.filter((c) => c.status !== "deleted").map((c) => c.path).filter((path) => path.startsWith("src/") && /\.tsx?$/.test(path))).map((path) => ({
+			path,
+			text: read(path) ?? ""
+		})), name);
+		if (hits.length > 0) refuse(`gtd land: cleanup: ${hits.join(", ")} still names GTD_FLAG_${name.toUpperCase()}`);
+	};
+	await scope("cleanup", async () => {
+		await agent("removing", removingPrompt(name, registry), {
+			label: `Removing ${name}`,
+			model: coder()
+		});
+		guard();
+		scanned = true;
+	});
+	await handOffTail(false, start(), guard);
+};
+const cleanup = flagShipped(cleanupFlow);
+//#endregion
 //#region src/workflows/index.ts
 var workflows_default = feature;
 /**
@@ -37797,4 +38134,4 @@ var workflows_default = feature;
 */
 const doors = {};
 //#endregion
-export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, QUALITY, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, awaitReview, base, baseline, build, buildTail, builtInLenses, closeReview, coder, collecting, declaredTests, decompose, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, envDefaults, escalate, escalation, escalationExhausted, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, fixSuite, gate, handOffReview, handOffTail, healthy, lensesOf, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, planner, qualityLap, reUnwind, requireDeclaredTests, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewing, skills, steering, summary, tail, threads, triage, unwind };
+export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, REFACTOR_PACKAGE, REQUIREMENTS, REVIEW, REVIEW_ORIG, ShippedOptions, access, afterTail, agentWithSkills, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, awaitReview, base, baseline, build, buildTail, builtInLenses, cleanup, cleanupFlow, closeReview, coder, collecting, declaredTests, decompose, workflows_default as default, defaults, deferNotes, describeEscalation, design, doors, envDefaults, escalate, escalation, escalationExhausted, feature, fix, fixCheck, fixFlow, fixNits, fixQuality, fixQualityFindings, fixReviewNotes, fixRisks, fixSuite, gate, guarded, handOffReview, handOffTail, healthy, lensesOf, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, planner, qualityLap, reUnwind, refactorFirst, requireDeclaredTests, requireNoNewFlags, requireWithin, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewing, rollout, rolloutFlow, skills, steering, summary, tail, threads, triage, unwind };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "27.1.0",
+  "version": "27.3.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -52,6 +52,16 @@
       "source": "./src/workflows/index.ts",
       "default": "./dist/workflows.mjs"
     },
+    "./workflows/rollout": {
+      "types": "./src/workflows/rollout/index.ts",
+      "source": "./src/workflows/rollout/index.ts",
+      "default": "./dist/workflows/rollout.mjs"
+    },
+    "./workflows/cleanup": {
+      "types": "./src/workflows/cleanup/index.ts",
+      "source": "./src/workflows/cleanup/index.ts",
+      "default": "./dist/workflows/cleanup.mjs"
+    },
     "./testkit": {
       "types": "./src/testkit/index.ts",
       "source": "./src/testkit/index.ts",

package/src/flags/index.test.ts

@@ -55,6 +55,34 @@ describe("resolveFlags", () => {
   })
 })
 
+describe("resolveFlags defaultOn", () => {
+  const on = [
+    { name: "beta", owner: "pmelab", expiry: "2099-01-01", kind: "release", defaultOn: true },
+  ] as const satisfies readonly FlagDeclaration[]
+
+  it.each([undefined, ""])("reads unset or empty (%j) as on", (value) => {
+    expect(resolveFlags({ GTD_FLAG_BETA: value }, on).beta).toBe(true)
+  })
+
+  it.each(["0", "false", "FALSE"])("%s still forces a default-on flag off", (value) => {
+    expect(resolveFlags({ GTD_FLAG_BETA: value }, on).beta).toBe(false)
+  })
+
+  it.each(["1", "true"])("%s forces a default-on flag on", (value) => {
+    expect(resolveFlags({ GTD_FLAG_BETA: value }, on).beta).toBe(true)
+  })
+
+  it("still throws for a garbled value", () => {
+    expect(() => resolveFlags({ GTD_FLAG_BETA: "ture" }, on)).toThrow(
+      /^GTD_FLAG_BETA must be 1, 0, true or false$/,
+    )
+  })
+
+  it("reads an entry without defaultOn as off when unset", () => {
+    expect(resolveFlags({}, [...on, ...registry]).alpha).toBe(false)
+  })
+})
+
 describe("FLAGS", () => {
   it("declares settable, unique variable names", () => {
     // Vacuous while FLAGS is empty; guards the first declared flag.

package/src/flags/index.ts

@@ -9,6 +9,8 @@ export interface FlagDeclaration {
   /** ISO `YYYY-MM-DD`; never enforced at runtime. */
   readonly expiry: string
   readonly kind: FlagKind
+  /** Unset or empty resolves on; `0`/`false` is still the kill switch. */
+  readonly defaultOn?: boolean
 }
 
 export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
@@ -18,17 +20,20 @@ export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
   readonly [N in R[number]["name"]]: boolean
 }
 
-const BOOL: Record<string, boolean> = { "": false, "0": false, false: false, "1": true, true: true }
+const BOOL: Record<string, boolean> = { "0": false, false: false, "1": true, true: true }
 
 export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof FLAGS>(
   env: Readonly<Record<string, string | undefined>>,
   registry: R = FLAGS as unknown as R,
 ): Flags<R> => {
   const out: Record<string, boolean> = {}
-  for (const { name } of registry) {
+  for (const { name, defaultOn } of registry) {
     const variable = `GTD_FLAG_${name.toUpperCase()}`
-    const raw = env[variable] ?? ""
-    const key = raw.toLowerCase()
+    const key = (env[variable] ?? "").toLowerCase()
+    if (key === "") {
+      out[name] = defaultOn ?? false
+      continue
+    }
     if (!Object.hasOwn(BOOL, key)) {
       throw new Error(`${variable} must be 1, 0, true or false`)
     }

package/src/testkit/EmittedScriptRecognizer.ts

@@ -667,6 +667,26 @@ const recognizeDeferNotes = (repo: InMemRepo, block: string): BlockOutcome | und
   return { kind: "applied" }
 }
 
+/** `mkdir -p <dir>` then `printf '%s\n' <quoted lines> > <path>`: a flow's one-file write. Re-rendered from what was extracted, so any other shape stays unrecognized. */
+const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
+  const [mkdir, printf, ...rest] = block.split("\n")
+  if (
+    rest.length > 0 ||
+    !mkdir?.startsWith("mkdir -p ") ||
+    !printf?.startsWith("printf '%s\\n' ")
+  ) {
+    return undefined
+  }
+  const tokens = extractQuotedTokens(printf.slice("printf '%s\\n' ".length))
+  const path = tokens.pop()
+  if (path === undefined || !path.includes("/")) return undefined
+  const dir = path.slice(0, path.lastIndexOf("/"))
+  const rendered = `mkdir -p ${dir}\nprintf '%s\\n' ${tokens.map(shellQuote).join(" ")} > ${shellQuote(path)}`
+  if (rendered !== block) return undefined
+  repo.writeFile(path, `${tokens.join("\n")}\n`)
+  return { kind: "applied" }
+}
+
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (
   repo: InMemRepo,
@@ -679,6 +699,7 @@ const recognizersFor = (
   (block) => recognizeBinaryGuard(commands, block),
   (block) => recognizeGitBuilders(repo, block),
   (block) => recognizeDeferNotes(repo, block),
+  (block) => recognizeWriteLines(repo, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
   (block) => recognizePresentationSubshell(repo, commands, block),
   (block) => recognizeModeContradictionSkipNotice(block),