@pmelab/gtd 27.3.0 → 27.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "27.3.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/{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"
 		]
 	},
 	{