@pmelab/gtd 27.2.0 → 27.4.0

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-import { C as EXIT_SIGTERM, D as UNATTRIBUTED_MODEL, E as ACCESS_REFUSAL, O as WIRE_SCHEMA, S as EXIT_SIGINT, T as EXIT_USAGE_ERROR, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_STRAYS_FOUND, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-BY1S-obW.mjs";
+import { C as EXIT_SIGTERM, D as UNATTRIBUTED_MODEL, E as ACCESS_REFUSAL, O as WIRE_SCHEMA, S as EXIT_SIGINT, T as EXIT_USAGE_ERROR, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_STRAYS_FOUND, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-C12dahrH.mjs";
 export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, resolveSession, selectPath, stallDiagnosis, statusOf };

package/dist/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
-import { a as flagShipped, b as coder, c as envDefaults, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-B2QaImnN.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-BnhIxCYv.mjs";
+import { a as flagShipped, b as coder, c as envDefaults, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-BPdVZkgv.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-iLAMoigl.mjs";
 import { i as requireFlag, r as registryEntry, t as flagReferences } from "../chunks/registry-CP3YuV9j.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.`;

package/dist/workflows/feature.mjs

@@ -1,7 +1,7 @@
-import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, numeric, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars } from "../flows.mjs";
+import { answered, changes, changesSince, glob, hasThreadFor, head, human, judge, numeric, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars } from "../flows.mjs";
 import { review as review$1 } from "../workflow-kit.mjs";
-import { $ as reviewerSystem, A as architectureAuthorPrompt, B as designGateAnswerMessage, C as fixRisks, D as reviewing, F as buildReviewCollectingPrompt, H as designTriagePrompt, I as buildReviewFixNitsPrompt, J as packagesItemFixSuitePrompt, K as idleMessage, L as buildReviewTriageMessage, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewAwaitAfterDeferMessage, Q as reviewNotesCapture, R as builderSystem, T as reviewMissing, V as designSystem, X as reviewEditsCapture, Y as reviewEditNotesCapture, _ as REQUIREMENTS, b as coder, c as envDefaults, d as gate, et as startGateBlockedMessage, h as FEEDBACK, i as skills, j as architectureDecomposePrompt, k as architectSystem, m as ARCHITECTURE, n as summary, nt as unwindFailure, o as shipped, p as healthy, q as packagesItemBuildingPrompt, r as access, s as defaults, t as steering, tt as unwindFailedMessage, v as REVIEW, w as planner, x as fixCheck, y as awaitReview, z as deferNotesScript } from "../chunks/reserved-B2QaImnN.mjs";
-import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-BnhIxCYv.mjs";
+import { A as architectureAuthorPrompt, B as designGateAnswerMessage, C as fixRisks, D as reviewing, F as buildReviewCollectingPrompt, H as designTriagePrompt, I as buildReviewFixNitsPrompt, J as packagesItemFixSuitePrompt, K as idleMessage, L as buildReviewTriageMessage, M as architectureGateAnswerMessage, N as buildReviewAnswerQuestionsPrompt, O as agentWithSkills, P as buildReviewAwaitAfterDeferMessage, Q as reviewEditsCapture, R as builderSystem, T as reviewMissing, V as designSystem, X as refactorFixPrompt, Y as refactorBuildingPrompt, Z as reviewEditNotesCapture, _ as REQUIREMENTS, b as coder, c as envDefaults, d as gate, et as reviewNotesCapture, h as FEEDBACK, i as skills, it as unwindFailure, j as architectureDecomposePrompt, k as architectSystem, m as ARCHITECTURE, n as summary, nt as startGateBlockedMessage, o as shipped, p as healthy, q as packagesItemBuildingPrompt, r as access, rt as unwindFailedMessage, s as defaults, t as steering, tt as reviewerSystem, v as REVIEW, w as planner, x as fixCheck, y as awaitReview, z as deferNotesScript } from "../chunks/reserved-BPdVZkgv.mjs";
+import { a as tail, i as refusePendingHandOff, n as closeReview } from "../chunks/tail-iLAMoigl.mjs";
 //#region src/workflows/feature/steps.ts
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 const triage = (base) => agentWithSkills("triage", designTriagePrompt(base), {
@@ -282,7 +282,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
@@ -295,7 +295,7 @@ const review = (base, escalations = { rounds: 0 }) => {
 	return review$1(base, {
 		file: REVIEW,
 		feedback: REQUIREMENTS,
-		isCode,
+		isCode: isCode$1,
 		reviewing: (b, carry) => {
 			deferred = [];
 			return reviewing(b, carry);
@@ -405,7 +405,120 @@ const ordinaryStart = async () => {
 };
 const feature = shipped(ordinaryStart);
 //#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();
+		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/feature/index.ts
 var feature_default = feature;
 //#endregion
-export { access, afterTail, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, build, buildTail, collecting, declaredTests, decompose, feature_default as default, defaults, deferNotes, design, envDefaults, feature, fixNits, fixSuite, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, reUnwind, requireDeclaredTests, skills, steering, summary, triage, unwind };
+export { REFACTOR_PACKAGE, access, afterTail, answerProductQuestions, answerReviewQuestions, answerTechnicalQuestions, architecture, author, build, buildTail, collecting, declaredTests, decompose, feature_default as default, defaults, deferNotes, design, envDefaults, feature, fixNits, fixSuite, nextPackage, ordinaryStart, packageItem, packages, planAndBuild, reUnwind, refactorFirst, requireDeclaredTests, requireNoNewFlags, requireWithin, skills, steering, summary, triage, unwind };

package/dist/workflows/fix.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { d as reviewNotes, f as reviewRisks } from "../chunks/steering-DVILanVf.mjs";
-import { O as agentWithSkills, U as finisherSystem, W as fixReviewNotesPrompt, b as coder, c as envDefaults, i as skills, l as baseline, n as summary, o as shipped, r as access, s as defaults, t as steering, v as REVIEW } from "../chunks/reserved-B2QaImnN.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-BnhIxCYv.mjs";
+import { O as agentWithSkills, U as finisherSystem, W as fixReviewNotesPrompt, b as coder, c as envDefaults, i as skills, l as baseline, n as summary, o as shipped, r as access, s as defaults, t as steering, v as REVIEW } from "../chunks/reserved-BPdVZkgv.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-iLAMoigl.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,6 +1,6 @@
 import { start } from "../flows.mjs";
-import { Z as reviewGateBlockedMessage, c as envDefaults, d as gate, i as skills, n as summary, o as shipped, r as access, s as defaults, t as steering } from "../chunks/reserved-B2QaImnN.mjs";
-import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-BnhIxCYv.mjs";
+import { $ as reviewGateBlockedMessage, c as envDefaults, d as gate, i as skills, n as summary, o as shipped, r as access, s as defaults, t as steering } from "../chunks/reserved-BPdVZkgv.mjs";
+import { i as refusePendingHandOff, r as handOffTail } from "../chunks/tail-iLAMoigl.mjs";
 //#region src/workflows/review/review.ts
 /**
 * Pure review of everything since `reviewBase`: a green gate, the quality

package/dist/workflows/rollout.mjs

@@ -1,5 +1,5 @@
 import { agent, changesSince, head, read, refuse, scope, vars } from "../flows.mjs";
-import { a as flagShipped, b as coder, c as envDefaults, d as gate, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-B2QaImnN.mjs";
+import { a as flagShipped, b as coder, c as envDefaults, d as gate, i as skills, n as summary, r as access, s as defaults, t as steering } from "../chunks/reserved-BPdVZkgv.mjs";
 import { i as requireFlag, n as flipProblems } from "../chunks/registry-CP3YuV9j.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.`;

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
@@ -17809,9 +17829,9 @@ const guarded = (turn, guard) => async (...a) => {
 	await turn(...a);
 	guard?.();
 };
-const guardedSteps = (guard) => ({
+const guardedSteps = (guard, describeGuard) => ({
 	limit: escalationSteps.limit,
-	describe: guarded(escalationSteps.describe, guard),
+	describe: guarded(guarded(escalationSteps.describe, guard), describeGuard),
 	stop: guarded(escalationSteps.stop, guard),
 	exhausted: guarded(escalationSteps.exhausted, guard)
 });
@@ -17863,7 +17883,7 @@ const healthy = (fix, options = {}) => healthy$1(guarded(fix, options.guard), {
 	fixesSoFar: options.fixesSoFar ?? 0,
 	sameFailure,
 	escalations: options.escalations ?? { rounds: 0 },
-	escalation: guardedSteps(options.guard)
+	escalation: guardedSteps(options.guard, options.describeGuard)
 });
 /**
 * Hold the process at `<name>.blocked` until the suite is green. `guard` runs
@@ -37198,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. */
@@ -37215,6 +37236,7 @@ const ShippedOptions = Struct({
 	judgeIdenticalMinP: setting,
 	reviewNoteActionable: setting,
 	reviewSeverityMinP: setting,
+	refactorFlagPattern: setting,
 	qualityReviews: setting,
 	testCommand: setting,
 	plannerModel: setting,
@@ -37614,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
@@ -37627,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);
@@ -37756,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
@@ -37779,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
@@ -37996,4 +38134,4 @@ var workflows_default = feature;
 */
 const doors = {};
 //#endregion
-export { ARCHITECTURE, ESCALATION, FEEDBACK, FIX_CAP, FlagOptions, QUALITY, 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, requireDeclaredTests, retryQuestion, review, reviewFlow, reviewMissing, reviewQuality, reviewing, rollout, rolloutFlow, 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.2.0",
+  "version": "27.4.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/cli/Cli.ts

@@ -705,11 +705,11 @@ const COMMAND_ROWS: readonly CommandRow[] = [
     arity: { name: "ref" },
     details: [
       "Replay one kept process under today's config and print its",
-      "steps and judge verdicts. <ref> is a full ref, an entry hash",
-      "(or unique prefix) or a branch name. Refuses (exit 1) when a",
-      "config file differs from its content at the ref's tip. A",
-      "version mismatch only warns on stderr. --json prints the",
-      "trail as one document; writes nothing",
+      "steps, judge verdicts and approvals. <ref> is a full ref, an",
+      "entry hash (or unique prefix) or a branch name. Refuses",
+      "(exit 1) when a config file differs from its content at the",
+      "ref's tip. A version mismatch only warns on stderr. --json",
+      "prints the trail as one document; writes nothing",
     ],
   },
   {

package/src/cli/History.ts

@@ -128,6 +128,11 @@ export const runHistoryShowCommand = (
     for (const step of trail.steps) {
       lines.push(`${seven(step.hash)} ${step.subject}`)
       for (const v of step.verdicts) lines.push(`  judge ${v.id} = ${v.answer} (p=${v.p})`)
+      if (step.approval !== undefined) {
+        lines.push(
+          `  approved ${step.approval.step} by ${step.approval.name} <${step.approval.email}>`,
+        )
+      }
     }
     lines.push(`ended (${trail.ended})`)
     out.write(`${lines.join("\n")}\n`)

package/src/cli/Program.ts

@@ -1080,6 +1080,7 @@ const gatherBeatDocument = (
       next: yield* computeNextMatch(rest),
       cost: rest.cost.total,
       costByModel: rest.cost.byModel,
+      approvals: rest.run.approvals,
     })
     return beatDocument(demand, status)
   })

package/src/edge/Edge.test.ts

@@ -151,6 +151,7 @@ describe("currentRun", () => {
       trace: [],
       costEntries: [],
       judgeVerdicts: [],
+      approvals: [],
       pinnedVars: {},
       headTurn: undefined,
       closingHash: undefined,
@@ -1306,6 +1307,28 @@ export default async () => {
     expect(trail.steps.filter((s) => s.verdicts.length > 0)).toHaveLength(1)
   })
 
+  it("sets approval on the approval step only", async () => {
+    const repo = repoWith(`import { human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await human("gate", { message: "seam report", approve: true })
+  await human("after")
+}
+`)
+    await land(repo, { "src/a.ts": "a\n" })
+    const approval = await land(repo)
+    const tip = await land(repo, { "src/b.ts": "b\n" })
+    const trail = await provide(historyTrail(tip), repo)
+    expect(trail.steps.find((s) => s.hash === approval)?.approval).toEqual({
+      step: "gate#1",
+      name: "Test",
+      email: "test@test.com",
+      commit: approval,
+    })
+    expect(trail.steps.filter((s) => s.approval !== undefined)).toHaveLength(1)
+  })
+
   it("records the version and warns about none while they match", async () => {
     const { repo, tip } = await finished()
     const trail = await provide(historyTrail(tip), repo)
@@ -1369,3 +1392,140 @@ export default async () => {
     expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")
   })
 })
+
+describe("landing at an approve rest", () => {
+  const GATED = `import { human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await human("gate", { message: "seam report", approve: true })
+  await human("after")
+}
+`
+
+  const atGate = async (): Promise<InMemRepo> => {
+    const repo = repoWith(GATED)
+    await land(repo, { "src/a.ts": "a\n" })
+    return repo
+  }
+
+  const snapshotAt = async (repo: InMemRepo, git?: GitOperations) => {
+    const rest = await provide(currentRest, repo)
+    const effect = snapshotFromRest(rest)
+    return git === undefined ? await provide(effect, repo) : await provideWithGit(effect, git, repo)
+  }
+
+  it("rests at a message step carrying approve", async () => {
+    const rest = await provide(currentRest, await atGate())
+    expect(rest.state).toBe("gate")
+    expect(rest.stepDef).toMatchObject({ kind: "message", content: "seam report", approve: true })
+  })
+
+  it("refuses a dirty tree and commits nothing", async () => {
+    const repo = await atGate()
+    const head = headOf(repo)
+    repo.writeFile("src/edited.ts", "edit\n")
+    const { landing } = await snapshotAt(repo)
+    expect(landing).toEqual({
+      kind: "refusal",
+      message:
+        "gtd land: approval-gate: gate#1 approves exactly the judged diff — revert your edits and run `gtd land` on a clean tree to approve, or run `gtd abandon`",
+    })
+    expect(headOf(repo)).toBe(head)
+  })
+
+  const stageThenRevert = (repo: InMemRepo): void => {
+    repo.writeFile("src/a.ts", "edited\n")
+    repo.stageAll()
+    repo.writeFile("src/a.ts", "a\n")
+  }
+
+  it("refuses an edit staged and then reverted in the worktree", async () => {
+    const repo = await atGate()
+    stageThenRevert(repo)
+    expect((await snapshotAt(repo)).landing).toMatchObject({
+      kind: "refusal",
+      message: expect.stringContaining("approves exactly the judged diff"),
+    })
+  })
+
+  it("counts no index-only edit at a rest that approves nothing", async () => {
+    const repo = await atGate()
+    await land(repo)
+    stageThenRevert(repo)
+    const rest = await provide(currentRest, repo)
+    expect(rest.state).toBe("after")
+    expect(rest.changes).toEqual([])
+    expect((await snapshotAt(repo)).landing).toEqual({ kind: "noop", settled: false })
+  })
+
+  it("refuses a clean tree when git has no author identity", async () => {
+    const repo = await atGate()
+    const git = { ...fakeGitOperations(repo), authorIdent: () => Effect.succeed(Option.none()) }
+    const { landing } = await snapshotAt(repo, git)
+    expect(landing).toEqual({
+      kind: "refusal",
+      message:
+        "gtd land: approval-gate: gate#1 records who approved it, but git has no author identity — set user.name and user.email",
+    })
+  })
+
+  it("refuses an identity a trailer cannot carry", async () => {
+    const repo = await atGate()
+    const git = {
+      ...fakeGitOperations(repo),
+      authorIdent: () => Effect.succeed(Option.some({ name: "Ada\u001b[31m", email: "a@x.io" })),
+    }
+    expect((await snapshotAt(repo, git)).landing).toEqual({
+      kind: "refusal",
+      message:
+        "gtd land: approval-gate: gate#1 cannot record Ada\u001b[31m <a@x.io> as approver — it would not read back unchanged from its Gtd-Approved trailer (a control character, for example)",
+    })
+  })
+
+  it("approve implies acceptClean even when acceptClean is false", async () => {
+    const repo = repoWith(GATED.replace("approve: true", "approve: true, acceptClean: false"))
+    await land(repo, { "src/a.ts": "a\n" })
+    expect((await snapshotAt(repo)).landing.kind).toBe("commit")
+  })
+
+  it("lands a clean tree as a commit carrying the approver", async () => {
+    const repo = await atGate()
+    const { landing } = await snapshotAt(repo)
+    if (landing.kind !== "commit") throw new Error(`expected commit, got ${landing.kind}`)
+    expect(landing.to).toBe("after")
+    expect(landing.spec.approved).toEqual({
+      step: { name: "gate", occurrence: 1 },
+      name: "Test",
+      email: "test@test.com",
+    })
+  })
+
+  it("reads the author identity only at an approve rest", async () => {
+    const repo = repoWith(GATED)
+    repo.writeFile("src/a.ts", "a\n")
+    const git = {
+      ...fakeGitOperations(repo),
+      authorIdent: () => Effect.die(new Error("authorIdent read at a plain rest")),
+    }
+    expect((await snapshotAt(repo, git)).landing.kind).toBe("commit")
+  })
+
+  it("collects each approval of the current process, oldest first", async () => {
+    const repo = await atGate()
+    expect((await provide(currentRun, repo)).approvals).toEqual([])
+    const approval = await land(repo)
+    expect((await provide(currentRun, repo)).approvals).toEqual([
+      { step: "gate#1", name: "Test", email: "test@test.com", commit: approval },
+    ])
+  })
+
+  it("resumes past the approval commit without asking again", async () => {
+    const repo = await atGate()
+    await land(repo)
+    expect(repo.lastCommitMessage()).toContain(
+      'Gtd-Approved: {"step":"gate#1","name":"Test","email":"test@test.com"}',
+    )
+    expect((await provide(currentRest, repo)).state).toBe("after")
+  })
+})