@pmelab/gtd 27.2.0 → 27.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "27.2.0",
+  "version": "27.4.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -581,7 +581,7 @@ kept before it squashes.
 
 ```sh
 gtd history list                 # one line per kept process
-gtd history show <ref>           # replay its steps and judge verdicts
+gtd history show <ref>           # replay its steps, judge verdicts and approvals
 gtd history fetch | sh           # pull every kept ref from origin
 ```
 
@@ -601,6 +601,19 @@ of on the branch (see [Kept tips](docs/configuration.md#kept-tips)). Those refs
 are not process history: `gtd history` does not list them, and the
 `refs/gtd/history/*` refspecs above neither push nor fetch them.
 
+A workflow can rest at an approval gate (`human(name, { approve: true })`; the
+`seamGate` helper does this after a `refactor-first` diff-shape judgment). Only
+a clean `gtd land` approves it, and the commit records who in a
+`Gtd-Approved: {"step":"<step>#<n>","name":"<name>","email":"<email>"}` trailer;
+a landing with any edit is refused (as is a script run after the tree changed —
+revert and land again), and `gtd abandon` is the only other way out. `approve`
+cannot be combined with `mode` or `file` (refused when replay reaches the step).
+Git hooks do not run on the approval commit; `commit.gpgSign` still applies, so
+a failing signer refuses the approval. `gtd next --json` lists the process's
+approvals as `approvals` (`[]` when none), and `gtd history show` prints each as
+`approved <step>#<n> by <name> <<email>>`. See
+[Step options](docs/configuration.md#step-options).
+
 ## Entrypoints
 
 gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and

package/dist/chunks/{reserved-B2QaImnN.mjs → reserved-BPdVZkgv.mjs}

@@ -591,6 +591,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
@@ -1161,9 +1181,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)
 });
@@ -1215,7 +1235,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
@@ -1236,6 +1256,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. */
@@ -1253,6 +1274,7 @@ const ShippedOptions = Struct({
 	judgeIdenticalMinP: setting,
 	reviewNoteActionable: setting,
 	reviewSeverityMinP: setting,
+	refactorFlagPattern: setting,
 	qualityReviews: setting,
 	testCommand: setting,
 	plannerModel: setting,
@@ -1314,6 +1336,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
@@ -1337,4 +1362,4 @@ const steering = {
 	[REVIEW]: "review"
 };
 //#endregion
-export { reviewerSystem as $, architectureAuthorPrompt as A, designGateAnswerMessage as B, fixRisks as C, reviewing as D, reviewQuality as E, buildReviewCollectingPrompt as F, handOffAwaitReviewMessage as G, designTriagePrompt as H, buildReviewFixNitsPrompt as I, packagesItemFixSuitePrompt as J, idleMessage as K, buildReviewTriageMessage as L, architectureGateAnswerMessage as M, buildReviewAnswerQuestionsPrompt as N, agentWithSkills as O, buildReviewAwaitAfterDeferMessage as P, reviewNotesCapture as Q, builderSystem as R, fixQuality as S, reviewMissing as T, finisherSystem as U, designSystem as V, fixReviewNotesPrompt as W, reviewEditsCapture as X, reviewEditNotesCapture as Y, reviewGateBlockedMessage as Z, REQUIREMENTS as _, flagShipped as a, coder as b, envDefaults as c, gate as d, startGateBlockedMessage as et, guarded as f, QUALITY as g, FEEDBACK as h, skills as i, architectureDecomposePrompt as j, architectSystem as k, baseline as l, ARCHITECTURE as m, summary as n, unwindFailure as nt, shipped as o, healthy as p, packagesItemBuildingPrompt as q, access as r, defaults as s, steering as t, unwindFailedMessage as tt, escalation as u, REVIEW as v, planner as w, fixCheck as x, awaitReview as y, deferNotesScript as z };
+export { reviewGateBlockedMessage as $, architectureAuthorPrompt as A, designGateAnswerMessage as B, fixRisks as C, reviewing as D, reviewQuality as E, buildReviewCollectingPrompt as F, handOffAwaitReviewMessage as G, designTriagePrompt as H, buildReviewFixNitsPrompt as I, packagesItemFixSuitePrompt as J, idleMessage as K, buildReviewTriageMessage as L, architectureGateAnswerMessage as M, buildReviewAnswerQuestionsPrompt as N, agentWithSkills as O, buildReviewAwaitAfterDeferMessage as P, reviewEditsCapture as Q, builderSystem as R, fixQuality as S, reviewMissing as T, finisherSystem as U, designSystem as V, fixReviewNotesPrompt as W, refactorFixPrompt as X, refactorBuildingPrompt as Y, reviewEditNotesCapture as Z, REQUIREMENTS as _, flagShipped as a, coder as b, envDefaults as c, gate as d, reviewNotesCapture as et, guarded as f, QUALITY as g, FEEDBACK as h, skills as i, unwindFailure as it, architectureDecomposePrompt as j, architectSystem as k, baseline as l, ARCHITECTURE as m, summary as n, startGateBlockedMessage as nt, shipped as o, healthy as p, packagesItemBuildingPrompt as q, access as r, unwindFailedMessage as rt, defaults as s, steering as t, reviewerSystem as tt, escalation as u, REVIEW as v, planner as w, fixCheck as x, awaitReview as y, deferNotesScript as z };

package/dist/chunks/{tail-BnhIxCYv.mjs → tail-iLAMoigl.mjs}

@@ -1,6 +1,6 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../flows.mjs";
 import { fixFindings, lensesOf, qualityLap as qualityLap$1, reviewToHandOff } from "../workflow-kit.mjs";
-import { C as fixRisks, D as reviewing, E as reviewQuality, G as handOffAwaitReviewMessage, S as fixQuality, T as reviewMissing, f as guarded, g as QUALITY, p as healthy, u as escalation, v as REVIEW, x as fixCheck, y as awaitReview } from "./reserved-B2QaImnN.mjs";
+import { C as fixRisks, D as reviewing, E as reviewQuality, G as handOffAwaitReviewMessage, S as fixQuality, T as reviewMissing, f as guarded, g as QUALITY, p as healthy, u as escalation, v as REVIEW, x as fixCheck, y as awaitReview } from "./reserved-BPdVZkgv.mjs";
 //#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. */
 const REVIEW_ORIG = ".gtd/REVIEW.orig.md";

package/dist/chunks/{wire-BY1S-obW.mjs → wire-C12dahrH.mjs}

@@ -110,7 +110,7 @@ const demandOf = (input) => {
 * instead of failing loudly.
 */
 const statusOf = (input) => {
-	const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel } = input;
+	const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel, approvals } = input;
 	return {
 		idle,
 		initial,
@@ -128,7 +128,8 @@ const statusOf = (input) => {
 		next,
 		cost,
 		costByModel,
-		judge: rendered.judge
+		judge: rendered.judge,
+		approvals
 	};
 };
 //#endregion
@@ -168,7 +169,7 @@ const dispatchFieldsOf = (demand) => {
 	}
 };
 /**
-* Flatten a `Demand` plus its `BeatStatus` into the single 24-key document
+* Flatten a `Demand` plus its `BeatStatus` into the single 25-key document
 * `gtd next --json` emits — the ONLY place the two are joined. `cost`/
 * `costByModel` are omitted together, exactly when no cost was recorded
 * (`cost <= 0`).
@@ -200,7 +201,8 @@ const beatDocument = (demand, status) => {
 		costByModel: hasCost ? status.costByModel : void 0,
 		judge: status.judge,
 		skills,
-		access
+		access,
+		approvals: status.approvals
 	};
 };
 const renderBeatJson = (document) => JSON.stringify(document) + "\n";

package/dist/flows.mjs

@@ -400,6 +400,28 @@ const judgeDiffShape = async (name, options) => {
 		judgment
 	};
 };
+const displayPath = (path) => /[\x00-\x1f\x7f-\x9f]/.test(path) ? JSON.stringify(path) : path;
+const seamReport = (shape) => {
+	const unreadable = new Set(shape.unreadable);
+	return [
+		"Seam report: the judge found the diff's shape needs a refactor first. These paths stray outside the allowlist:",
+		"",
+		...shape.strays.map((path) => `- ${displayPath(path)}${unreadable.has(path) ? " (unreadable — not judged)" : ""}`),
+		"",
+		"Landing a clean tree with `gtd land` approves this diff exactly as judged; edits are refused. To stop instead, run `gtd abandon`."
+	].join("\n");
+};
+/**
+* Rest at an approval gate `name` showing the seam report — only when
+* `shape.choice` is `refactor-first`. `land` and `reject` reach no step.
+*/
+const seamGate = async (name, shape) => {
+	if (shape.choice !== "refactor-first") return;
+	await human(name, {
+		message: seamReport(shape),
+		approve: true
+	});
+};
 //#endregion
 //#region src/flows/factory.ts
 const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory");
@@ -607,6 +629,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	revertScript: () => revertScript,
 	run: () => run,
 	scope: () => scope,
+	seamGate: () => seamGate,
 	sectionBodies: () => sectionBodies,
 	sections: () => sections,
 	showScript: () => showScript,
@@ -617,4 +640,4 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	wrote: () => wrote
 });
 //#endregion
-export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, judgeDiffShape, kept, matches, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, sectionBodies, sections, showScript, skillsFor, start, flows_exports as t, threads, vars, wrote };
+export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, judgeDiffShape, kept, matches, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, seamGate, sectionBodies, sections, showScript, skillsFor, start, flows_exports as t, threads, vars, wrote };

package/dist/gtd.bundle.mjs

@@ -20269,6 +20269,13 @@ const makeGitImpl = (executor, root) => {
 		hasCommits: () => exec("git", "rev-parse", "--verify", "HEAD").pipe(map$4(() => true), catchAll(() => succeed$3(false))),
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
 		diffPaths: (base, tip) => exec("git", "diff", "--name-only", "-z", "--no-renames", "--no-relative", "--ignore-submodules=none", "--end-of-options", base, tip, "--").pipe(map$4(splitNul)),
+		authorIdent: () => exec("git", "var", "GIT_AUTHOR_IDENT").pipe(map$4((out) => {
+			const match = /^(.*?) <([^<>]*)> \d+ [+-]\d{4}$/.exec(out.trim());
+			return match === null || match[1] === "" || match[2] === "" ? none$4() : some({
+				name: match[1],
+				email: match[2]
+			});
+		}), catchAll(() => succeed$3(none$4()))),
 		changedPaths: (base) => gen(function* () {
 			const ref = base ?? "HEAD";
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchAll(() => succeed$3("")));
@@ -20286,6 +20293,7 @@ const makeGitImpl = (executor, root) => {
 			}
 			return all;
 		}),
+		stagedPaths: () => exec("git", "diff", "--cached", "--name-status", "--no-renames", "-z", "HEAD").pipe(catchAll(() => succeed$3("")), map$4((out) => parseNameStatus(splitNul(out)))),
 		resolveRef: (ref) => exec("git", "rev-parse", "--verify", "--end-of-options", ref).pipe(map$4((s) => s.trim()), flatMap$4((hash) => resolvedRefOrCorrupted(ref, hash))),
 		readRefOption: (ref) => exec("git", "rev-parse", "--verify", "--quiet", ref).pipe(map$4((s) => some(s.trim())), catchAll(() => succeed$3(none$4()))),
 		isAncestor: (a, b) => run$4(root, "git", "merge-base", "--is-ancestor", a, b).pipe(provide$1(succeed$2(CommandExecutor, executor)), map$4(() => true), catchAll(() => succeed$3(false))),
@@ -21231,7 +21239,8 @@ skills, \`skills\` (an array of the skill names, already trimmed and split —
 (\`{read, write}\`, each an array of globs or \`null\` for unrestricted). When set: \`model\`, \`memory\`,
 \`label\`, \`file\`, \`mode\`, \`edges\`, \`judge\` (the pending judgment's rendered
 document). When a cost has been recorded (a prior \`gtd land --cost=<n>\`):
-\`cost\`, \`costByModel\`.
+\`cost\`, \`costByModel\`. Always \`approvals\` (an array of
+\`{step, name, email, commit}\`, \`[]\` when none).
 
 \`gtd land\` fields, in fixed order: \`schema\`, \`script\` (the POSIX sh to run), \`settled\`
 (true for a no-op at a \`script\` rest — stop immediately, nothing more to
@@ -22013,6 +22022,28 @@ const judgeDiffShape = async (name, options) => {
 		judgment
 	};
 };
+const displayPath = (path) => /[\x00-\x1f\x7f-\x9f]/.test(path) ? JSON.stringify(path) : path;
+const seamReport = (shape) => {
+	const unreadable = new Set(shape.unreadable);
+	return [
+		"Seam report: the judge found the diff's shape needs a refactor first. These paths stray outside the allowlist:",
+		"",
+		...shape.strays.map((path) => `- ${displayPath(path)}${unreadable.has(path) ? " (unreadable — not judged)" : ""}`),
+		"",
+		"Landing a clean tree with `gtd land` approves this diff exactly as judged; edits are refused. To stop instead, run `gtd abandon`."
+	].join("\n");
+};
+/**
+* Rest at an approval gate `name` showing the seam report — only when
+* `shape.choice` is `refactor-first`. `land` and `reject` reach no step.
+*/
+const seamGate = async (name, shape) => {
+	if (shape.choice !== "refactor-first") return;
+	await human(name, {
+		message: seamReport(shape),
+		approve: true
+	});
+};
 //#endregion
 //#region src/flows/factory.ts
 const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory");
@@ -22220,6 +22251,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	revertScript: () => revertScript,
 	run: () => run$3,
 	scope: () => scope,
+	seamGate: () => seamGate,
 	sectionBodies: () => sectionBodies,
 	sections: () => sections,
 	showScript: () => showScript,
@@ -37282,7 +37314,7 @@ var init_Demand = __esmMin((() => {
 var statusOf;
 var init_BeatStatus = __esmMin((() => {
 	statusOf = (input) => {
-		const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel } = input;
+		const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel, approvals } = input;
 		return {
 			idle,
 			initial,
@@ -37300,7 +37332,8 @@ var init_BeatStatus = __esmMin((() => {
 			next,
 			cost,
 			costByModel,
-			judge: rendered.judge
+			judge: rendered.judge,
+			approvals
 		};
 	};
 }));
@@ -37360,7 +37393,8 @@ var init_BeatDocument = __esmMin((() => {
 			costByModel: hasCost ? status.costByModel : void 0,
 			judge: status.judge,
 			skills,
-			access
+			access,
+			approvals: status.approvals
 		};
 	};
 	renderBeatJson = (document) => JSON.stringify(document) + "\n";
@@ -37689,12 +37723,38 @@ const TRAILER_RE = /^(Gtd-[A-Za-z-]+):[ \t]*(.*?)[ \t]*$/gm;
 const COST_RE = /^([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+))?$/;
 const VAR_RE = /^([^=\s]+)=(.*)$/;
 const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/;
-const CONTROL_CHARACTER$1 = /[\x00-\x1f\x7f-\x9f]/;
+const CONTROL_CHARACTER$1 = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/;
 const encodePath = (path) => path.trim() !== path || path.startsWith("\"") || CONTROL_CHARACTER$1.test(path) ? JSON.stringify(path) : path;
 const decodePath = (raw) => {
 	const path = raw.startsWith("\"") ? parseJson$1(raw) : raw;
 	return typeof path === "string" && path !== "" && !CONTROL_CHARACTER$1.test(path) ? path : void 0;
 };
+const decodeApproval = (raw) => {
+	const parsed = parseJson$1(raw);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	const { step, name, email } = parsed;
+	if (typeof step !== "string" || typeof name !== "string" || typeof email !== "string") return void 0;
+	if ([
+		step,
+		name,
+		email
+	].some((field) => CONTROL_CHARACTER$1.test(field))) return void 0;
+	const id = parseStepId(step);
+	return id === void 0 ? void 0 : {
+		step: id,
+		name,
+		email
+	};
+};
+const encodeApproval = ({ step, name, email }) => JSON.stringify({
+	step: formatStepId(step),
+	name,
+	email
+});
+const isRecordableApproval = (approval) => {
+	const back = decodeApproval(encodeApproval(approval));
+	return back !== void 0 && encodeApproval(back) === encodeApproval(approval);
+};
 const FORMAT_RE = /^[1-9][0-9]*$/;
 const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const TRAILER_READERS = {
@@ -37729,6 +37789,9 @@ const TRAILER_READERS = {
 	"Gtd-Kept": (value, into) => {
 		if (HASH_RE.test(value)) into.kept ??= value;
 	},
+	"Gtd-Approved": (value, into) => {
+		into.approved ??= decodeApproval(value);
+	},
 	"Gtd-Format": (value, into) => {
 		if (FORMAT_RE.test(value)) into.format ??= Number(value);
 	},
@@ -37750,6 +37813,7 @@ const parseCommitMessage = (message) => {
 		branch: void 0,
 		version: void 0,
 		kept: void 0,
+		approved: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -37775,6 +37839,7 @@ const formatCommitMessage = (spec) => {
 	for (const [path, hash] of sortedEntries(spec.config)) lines.push(`Gtd-Config: ${hash} ${encodePath(path)}`);
 	if (spec.cost !== void 0) lines.push(`Gtd-Cost: ${spec.cost.cost}${spec.cost.model !== void 0 ? ` ${spec.cost.model}` : ""}`);
 	for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`);
+	if (spec.approved !== void 0) lines.push(`Gtd-Approved: ${encodeApproval(spec.approved)}`);
 	if (spec.branch !== void 0) lines.push(`Gtd-Branch: ${spec.branch}`);
 	if (spec.version !== void 0) lines.push(`Gtd-Version: ${spec.version}`);
 	lines.push(`Gtd-Format: 1`);
@@ -37870,7 +37935,8 @@ const KNOWN_OPTIONS = {
 	human: /* @__PURE__ */ new Set([
 		...STEERING_OPTIONS,
 		"message",
-		"acceptClean"
+		"acceptClean",
+		"approve"
 	]),
 	run: new Set(STEERING_OPTIONS),
 	judge: /* @__PURE__ */ new Set([...STEERING_OPTIONS, "message"])
@@ -37880,6 +37946,13 @@ const unknownOptions = (step) => {
 	if (unknown.length === 0) return void 0;
 	return `gtd: step "${step.name}": unknown key(s) ${unknown.join(", ")} in ${step.kind}() options`;
 };
+const approveConflict = (step) => {
+	const request = step.request;
+	if (request.kind !== "human" || request.options.approve !== true) return void 0;
+	const keys = ["mode", "file"].filter((key) => request.options[key] !== void 0);
+	if (keys.length === 0) return void 0;
+	return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`;
+};
 const replay = async (input) => {
 	const commits = input.episode.commits.map((c) => ({
 		...c,
@@ -38039,12 +38112,21 @@ const replay = async (input) => {
 			kind: "divergence",
 			message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`
 		};
-		const error = unknownOptions(step) ?? checkIdentity(step);
+		const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step);
 		return error === void 0 ? void 0 : {
 			kind: "failed",
 			message: error
 		};
 	};
+	const missingApproval = (step, commit, expected) => {
+		if (step.request.kind !== "human" || step.request.options.approve !== true) return void 0;
+		const approved = commit.parsed.approved;
+		if (approved !== void 0 && formatStepId(approved.step) === expected) return void 0;
+		return {
+			kind: "divergence",
+			message: `gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it — ${DIVERGED}`
+		};
+	};
 	const consumeCommit = (step, commit) => {
 		const recorded = commit.parsed.step;
 		const expected = formatStepId(step.id);
@@ -38055,6 +38137,8 @@ const replay = async (input) => {
 				message: `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}" — ${DIVERGED}`
 			});
 		}
+		const unapproved = missingApproval(step, commit, expected);
+		if (unapproved !== void 0) return finish(unapproved);
 		cursor++;
 		advance(commit);
 		if (commit.parsed.kept !== void 0) if (commit.kept === void 0) keptTips.delete(step.name);
@@ -39169,6 +39253,9 @@ const planStep = (snapshot, opts = {}) => {
 					kind: "keepTurn",
 					ref: landing.keepTurn,
 					message
+				} : landing.spec.approved !== void 0 ? {
+					kind: "commitClean",
+					message
 				} : {
 					kind: "commitAll",
 					message
@@ -39376,6 +39463,12 @@ const pinnedConfigOf = (history) => {
 		};
 	}
 };
+const approvalEntryOf = (hash, message) => message.approved === void 0 ? [] : [{
+	step: formatStepId(message.approved.step),
+	name: message.approved.name,
+	email: message.approved.email,
+	commit: hash
+}];
 const buildRun = (history, location, closingHash) => {
 	const processCommits = history.slice(location.processStart);
 	const parsed = processCommits.map((c) => parseCommitMessage(c.message));
@@ -39391,6 +39484,7 @@ const buildRun = (history, location, closingHash) => {
 		trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i])),
 		costEntries: parsed.flatMap(costEntriesOf),
 		judgeVerdicts: parsed.flatMap((m) => m.judge),
+		approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i])),
 		pinnedVars: { ...first?.vars },
 		pinnedConfig: pinnedConfigOf(history.slice(Math.max(location.baseIndex, 0))),
 		headTurn: headTurnOf(head),
@@ -39676,7 +39770,8 @@ const messageDef = (common, request, step) => ({
 	...common,
 	kind: "message",
 	content: request.options.message ?? request.options.label ?? step.name,
-	...optional$1("acceptClean", request.options.acceptClean)
+	...optional$1("acceptClean", request.options.approve === true || request.options.acceptClean),
+	...optional$1("approve", request.options.approve)
 });
 const stepDefOf = (step) => {
 	const request = step.request;
@@ -39805,6 +39900,12 @@ const setupFor = (config, run, workspace, host, startOverrides = {}) => gen(func
 		}
 	};
 });
+const pendingChanges = (git, withIndex) => gen(function* () {
+	const worktree = yield* git.changedPaths();
+	if (!withIndex) return worktree;
+	const seen = new Set(worktree.map((e) => e.path));
+	return [...worktree, ...(yield* git.stagedPaths()).filter((e) => !seen.has(e.path))];
+});
 /** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
 const restAt = (ref, startOverrides = {}) => gen(function* () {
 	const git = yield* GitService;
@@ -39820,7 +39921,7 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 	yield* (yield* Narrator).narrate(`rest resolved: ${step.name} (awaits ${step.actor})`);
 	const stepDef = stepDefOf(step);
 	if (stepDef.mode !== void 0 && def.modes[stepDef.mode] === void 0) return yield* fail$7(/* @__PURE__ */ new Error(`gtd config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`));
-	const changes = ref === void 0 ? (yield* git.changedPaths()).map((e) => ({
+	const changes = ref === void 0 ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({
 		status: normalizeStatus(e.status),
 		path: e.path
 	})) : [];
@@ -39906,6 +40007,25 @@ const noProcessUnderway = (rest) => rest.run.workflow === void 0 && rest.state =
 /** `idle` means exactly one thing: no process underway, clean tree. */
 const restIsIdle = (rest) => noProcessUnderway(rest) && rest.changes.length === 0;
 const isHumanReviewGate = (def) => def.actor === "human" && def.mode === "review";
+const approvalRefusal = (rest, approver) => {
+	if (rest.stepDef.approve !== true) return void 0;
+	const id = rest.step.id;
+	if (rest.changes.length > 0) return {
+		kind: "refusal",
+		message: `gtd land: approval-gate: ${formatStepId(id)} approves exactly the judged diff — revert your edits and run \`gtd land\` on a clean tree to approve, or run \`gtd abandon\``
+	};
+	if (isNone(approver)) return {
+		kind: "refusal",
+		message: `gtd land: approval-gate: ${formatStepId(id)} records who approved it, but git has no author identity — set user.name and user.email`
+	};
+	if (!isRecordableApproval({
+		step: id,
+		...approver.value
+	})) return {
+		kind: "refusal",
+		message: `gtd land: approval-gate: ${formatStepId(id)} cannot record ${approver.value.name} <${approver.value.email}> as approver — it would not read back unchanged from its Gtd-Approved trailer (a control character, for example)`
+	};
+};
 /** The landing a clean tree decides before any replay, if it decides one. */
 const cleanLanding = (rest) => {
 	if (rest.changes.length > 0) return void 0;
@@ -39960,7 +40080,11 @@ const closingTrailers = (branch) => ({
 });
 const isSettledNoop = (rest, to) => rest.changes.length === 0 && rest.stepDef.kind === "script" && to === rest.state;
 const keptTurn = (rest) => rest.stepDef.keep === true && rest.changes.length > 0 ? { keepTurn: keptRef(rest.run.startHash, rest.state) } : {};
-const landingTo = (rest, to, branch) => {
+const approvedTrailer = (rest, approver) => isSome(approver) ? { approved: {
+	step: rest.step.id,
+	...approver.value
+} } : {};
+const landingTo = (rest, to, branch, approver) => {
 	if (isSettledNoop(rest, to)) return {
 		kind: "noop",
 		settled: true
@@ -39978,6 +40102,7 @@ const landingTo = (rest, to, branch) => {
 			from: rest.state,
 			to,
 			step: rest.step.id,
+			...approvedTrailer(rest, approver),
 			...starts ? {
 				vars: rest.vars,
 				config: rest.config
@@ -39993,7 +40118,9 @@ const landingTo = (rest, to, branch) => {
 * replay with the working tree as the pending turn. The target step is
 * computed by replaying, never matched.
 */
-const decideLanding = (rest, verdicts, branch) => gen(function* () {
+const decideLanding = (rest, verdicts, branch, approver) => gen(function* () {
+	const unapproved = approvalRefusal(rest, approver);
+	if (unapproved !== void 0) return unapproved;
 	const early = cleanLanding(rest);
 	if (early !== void 0) return early;
 	if (rest.stepDef.kind === "prompt" && rest.stepDef.access?.write != null) {
@@ -40009,14 +40136,16 @@ const decideLanding = (rest, verdicts, branch) => gen(function* () {
 	}));
 	const to = yield* landingTarget(outcome, rest);
 	if (typeof to !== "string") return to;
-	return landingTo(rest, to, branch);
+	return landingTo(rest, to, branch, approver);
 });
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
-const previewLanding = (rest) => decideLanding(rest, void 0, none$4()).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll(() => succeed$3(void 0)));
+const previewLanding = (rest) => decideLanding(rest, void 0, none$4(), none$4()).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll(() => succeed$3(void 0)));
 /** Every fact the pure landing planner needs, read once: the rest, its steering file, and the landing decision. */
 const snapshotFromRest = (rest, verdicts) => gen(function* () {
-	const branch = yield* (yield* GitService).currentBranch();
-	const landing = yield* decideLanding(rest, verdicts, branch);
+	const git = yield* GitService;
+	const branch = yield* git.currentBranch();
+	const approver = rest.stepDef.approve === true ? yield* git.authorIdent() : none$4();
+	const landing = yield* decideLanding(rest, verdicts, branch, approver);
 	return {
 		stepDef: rest.stepDef,
 		state: rest.state,
@@ -40070,7 +40199,8 @@ const historySteps = (run) => {
 			actor: entry.actor,
 			from: message.parsed?.from,
 			to: entry.state,
-			verdicts: message.judge
+			verdicts: message.judge,
+			...optional$1("approval", approvalEntryOf(entry.hash, message)[0])
 		};
 	});
 };
@@ -40128,8 +40258,26 @@ const commitAllowEmpty = (message) => {
 		`fi`
 	].join("\n");
 };
+const CHANGED_SINCE_LAND = "gtd: the working tree changed since `gtd land` — revert the edits and run `gtd land` again to approve";
 /** `git add -A || exit 1` (an `&&` left side would not abort under `set -e`) then `commitAllowEmpty`. */
 const commitAll = (message) => `git add -A || exit 1\n${commitAllowEmpty(message)}`;
+/**
+* An approval records exactly the judged tree: HEAD is pinned before the
+* clean check and the commit is built over its tree with `commit-tree`, so no
+* hook runs and none can add to it. A HEAD that moved fails the guarded
+* `update-ref`. `commit-tree` ignores `commit.gpgSign`, so it is read here.
+*/
+const commitClean = (message) => [
+	`gtd_head=$(git rev-parse --verify HEAD) || exit 1`,
+	`if [ -n "$(git status --porcelain --untracked-files=all --ignore-submodules=none)" ]; then`,
+	`  printf '%s\\n' ${shellQuote$1(CHANGED_SINCE_LAND)} >&2`,
+	`  exit 1`,
+	`fi`,
+	`gtd_sign_cfg=$(git config --type=bool --default=false commit.gpgSign) || exit 1`,
+	`if [ "$gtd_sign_cfg" = true ]; then gtd_sign=-S; else gtd_sign=--no-gpg-sign; fi`,
+	`gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m ${shellQuote$1(message)}) || exit 1`,
+	`git update-ref -m ${shellQuote$1(`commit: ${message}`)} HEAD "$gtd_tip" "$gtd_head" || exit 1`
+].join("\n");
 const mixedResetTo = (ref) => `git reset --mixed ${shellQuote$1(ref)}`;
 const hardResetTo = (ref) => `git reset --hard ${shellQuote$1(ref)}`;
 /**
@@ -40155,7 +40303,7 @@ const keepTurn = (refPrefix, message) => {
 		`gtd_kept=$(git commit-tree "$gtd_tree" -p "$gtd_head" -m ${shellQuote$1(message)}) || exit 1`,
 		`git update-ref ${keptRef} "$gtd_kept" || exit 1`,
 		`gtd_marker=$(printf '%s\\nGtd-Kept: %s' ${shellQuote$1(message)} "$gtd_kept")`,
-		`if ! gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m "$gtd_marker") || ! git update-ref HEAD "$gtd_tip" "$gtd_head"; then`,
+		`if ! gtd_tip=$(git commit-tree "$gtd_sign" "$gtd_head^{tree}" -p "$gtd_head" -m "$gtd_marker") || ! git update-ref -m ${shellQuote$1(`commit: ${message}`)} HEAD "$gtd_tip" "$gtd_head"; then`,
 		`  git reset -q && git update-ref -d ${keptRef}`,
 		`  exit 1`,
 		`fi`,
@@ -40193,6 +40341,7 @@ const renderOutcome = (outcome) => {
 const renderGitWrite = (write) => {
 	switch (write.kind) {
 		case "commitAll": return commitAll(write.message);
+		case "commitClean": return commitClean(write.message);
 		case "updateRef": return updateRef(write.ref, write.target);
 		case "keepTurn": return keepTurn(write.ref, write.message);
 	}
@@ -40676,6 +40825,7 @@ const runHistoryShowCommand = (ref, json, out) => gen(function* () {
 	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 !== void 0) lines.push(`  approved ${step.approval.step} by ${step.approval.name} <${step.approval.email}>`);
 	}
 	lines.push(`ended (${trail.ended})`);
 	out.write(`${lines.join("\n")}\n`);
@@ -41215,7 +41365,8 @@ const gatherBeatDocument = (rest, rendered) => gen(function* () {
 		changes: computeStatusChanges(rest.changes),
 		next: yield* computeNextMatch(rest),
 		cost: rest.cost.total,
-		costByModel: rest.cost.byModel
+		costByModel: rest.cost.byModel,
+		approvals: rest.run.approvals
 	}));
 });
 /**
@@ -41906,11 +42057,11 @@ const COMMAND_ROWS = [
 		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"
 		]
 	},
 	{