@pmelab/gtd 27.2.0 → 27.4.0

package/dist/testkit.mjs

@@ -1,5 +1,5 @@
 import { checkScript, configProblems, configure, installContext, isFactoryWorkflow, moveScript, protocolMismatch, removeScript, restoreScript, revertScript, showScript, t as flows_exports } from "./flows.mjs";
-import { E as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./chunks/wire-BY1S-obW.mjs";
+import { E as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./chunks/wire-C12dahrH.mjs";
 import { C as headingSections, S as headingSectionBodies, a as unansweredQuestions, b as parseThreadsWithFindings, n as openThreads, r as steeringFormatFor, s as parseCodeThreads, t as BUILT_IN_MODE_NAMES, w as formatFinding } from "./chunks/steering-DVILanVf.mjs";
 import { $ as logWarning, $i as format, $n as map$5, $r as make$19, $t as provide$1, A as catchIf, Ai as get$5, An as scopeMake, Ar as flatMap$3, At as suspend$5, B as flatMap$4, Bi as isNone, Bn as get$3, Br as sync$1, Bt as unsafeMakeLatch, C as all$1, Ci as toArray, Cn as isInterrupted, Cr as exitFail, Ct as sandbox, D as async, Di as GenericTag, Dn as squash, Dr as exitZipRight, Dt as scopedWith$1, E as asVoid$1, Ei as unsafeHead, En as reduceWithContext, Er as exitVoid, Et as scoped$4, F as ensuring$2, Fi as splitAt, Fn as join$3, Fr as map$3, Ft as tryMap, G as forkIn, Gi as some, Gn as TypeId$10, Gr as whenEffect, Gt as zipLeft, H as fnUntraced, Hi as map$8, Hn as modify$1, Hr as uninterruptible, Ht as when, I as exit, Ii as filter$1, In as sequential, Ir as onInterrupt, It as tryPromise, J as ignore, Ji as match$2, Jn as all, Jr as DeferredTypeId$1, Jt as spaced$1, K as forkScoped, Ki as isLeft, Kn as Class, Kr as withFiberRuntime, Kt as zipRight$3, L as fail$5, Li as flatMap$5, Ln as bind, Lr as scopeClose, Lt as try_, M as die$2, Mi as omit, Mn as _await$2, Mr as interruptAsFiber, Mt as tap, N as dieMessage, Ni as empty$5, Nn as inheritAll$1, Nr as interruptFiber, Nt as tapErrorCause, O as catchAll$1, Oi as Tag, On as ensuring$3, Or as fiberId, Ot as serviceOption, P as either, Pi as fromIterable, Pn as interruptAllAs$1, Pr as interruptible$1, Pt as timeout, Q as isEffect, Qi as NodeInspectSymbol, Qn as isFailure, Qr as ids, Qt as mergeAll$2, R as failCause$4, Ri as fromNullable, Rn as bindTo, Rr as succeed$4, Rt as uninterruptible$1, S as addFinalizer$1, Si as takeRight, Sn as isDieType, Sr as exitAs, St as runtime, T as as, Ti as unsafeGet, Tn as map$6, Tr as exitSucceed, Tt as scopeWith, U as forEach$2, Ui as match$4, Un as set$1, Ur as uninterruptibleMask$1, Ut as withFiberRuntime$1, V as flatten$4, Vi as isSome, Vn as make$16, Vr as tap$1, Vt as unsafeMakeSemaphore$1, W as forkDaemon, Wi as none, Wn as update$1, Wr as void_$2, Wt as zip$1, X as interruptible, Xi as pipeArguments, Xn as fail$4, Xr as combine, Xt as tagged, Y as interrupt$4, Yi as right, Yn as die, Yr as empty$6, Yt as TaggedError$1, Z as intoDeferred, Zi as BaseProto, Zn as failCause$3, Zr as combineAll, Zt as fromEffect$5, _ as decodeSync, _i as of, _n as fail$3, _r as deferredIsDone, _t as raceWith, a as Literal, aa as constUndefined, ai as size$2, an as updateContext$1, ar as zipRight$2, at as matchCause, b as acquireRelease, bi as reverse, bn as interrupt$3, br as deferredUnsafeDone, bt as runPromise, c as String$, ca as identity, ci as append$1, cn as Scope, cr as asyncInterrupt, ct as negate, d as Union, di as empty$4, dn as close, dr as deferredAwait, dt as orElse, ea as toJSON, ei as none$1, en as provideMerge$1, er as mapBoth, et as makeSemaphore, f as between, fi as filter, fn as extend, fr as deferredComplete, ft as orElseSucceed, gi as map$7, gn as die$1, gr as deferredInterruptWith, gt as race, hi as isEmpty$2, hn as NoSuchElementException, hr as deferredInterrupt, ht as provideService, i as Defect, ia as constTrue, ii as has, in as unsafeRunPromiseExit, ir as zip$2, it as match$5, j as catchTag, ji as getOption, jn as scopeTag, jr as interrupt$2, jt as sync$2, k as catchAllCause, ki as add, kn as forEachConcurrentDiscard, kr as fiberRefLocally, kt as succeed$6, l as Struct, la as pipe, li as appendAll, ln as addFinalizer, lr as catchAll, lt as onError, m as optional$1, mi as isChunk, mn as make$18, mr as deferredFailCause, mt as provide$2, n as Boolean$, na as hasProperty, ni as make$17, nn as succeed$3, nr as succeed$5, nt as mapBoth$1, o as Never, oa as constVoid, oi as decode, on as forkIn$1, or as as$1, ot as matchCauseEffect, p as decodeUnknown, pi as fromIterable$1, pn as fork, pr as deferredFail, pt as promise, q as gen, qi as left, qn as spanTag, qr as zipRight$1, qt as zipWith, r as Cause, ra as constFalse, ri as set$2, rn as unsafeFork, rr as void_$3, rt as mapError, s as Number$, sa as dual, si as isFinite, sn as unsafeMakeSemaphore, sr as asVoid, st as matchEffect, t as Array$, ta as equals, ti as get$4, tn as scoped$3, tr as match$3, tt as map$4, u as TaggedError, ui as drop, un as addFinalizerExit, ur as currentContext$1, ut as orDie, v as encodeSync, vi as prepend, vn as failureOrCause, vr as deferredMake, vt as repeat, w as annotateLogs, wi as unsafeFromArray, wn as isInterruptedOnly, wr as exitFailCause, wt as scope, x as acquireUseRelease$2, xi as take$2, xn as interruptors, xr as deferredUnsafeMake, xt as runPromiseExit$1, y as _void, yi as reduce, yn as flipCauseOption, yr as deferredSucceed, yt as retry, z as fiberIdWith, zi as getOrElse, zn as sleep, zr as suspend$4, zt as uninterruptibleMask } from "./chunks/Schema-CyImoHTj.mjs";
 import { createRequire } from "node:module";
@@ -5402,6 +5402,13 @@ const makeGitImpl = (executor, root) => {
 		hasCommits: () => exec("git", "rev-parse", "--verify", "HEAD").pipe(map$4(() => true), catchAll$1(() => succeed$6(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() : some({
+				name: match[1],
+				email: match[2]
+			});
+		}), catchAll$1(() => succeed$6(none()))),
 		changedPaths: (base) => gen(function* () {
 			const ref = base ?? "HEAD";
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchAll$1(() => succeed$6("")));
@@ -5419,6 +5426,7 @@ const makeGitImpl = (executor, root) => {
 			}
 			return all;
 		}),
+		stagedPaths: () => exec("git", "diff", "--cached", "--name-status", "--no-renames", "-z", "HEAD").pipe(catchAll$1(() => succeed$6("")), 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$1(() => succeed$6(none()))),
 		isAncestor: (a, b) => run$1(root, "git", "merge-base", "--is-ancestor", a, b).pipe(provide$2(succeed$1(CommandExecutor, executor)), map$4(() => true), catchAll$1(() => succeed$6(false))),
@@ -6358,7 +6366,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
@@ -6879,12 +6888,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(raw) : raw;
 	return typeof path === "string" && path !== "" && !CONTROL_CHARACTER$1.test(path) ? path : void 0;
 };
+const decodeApproval = (raw) => {
+	const parsed = parseJson(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 = {
@@ -6919,6 +6954,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);
 	},
@@ -6940,6 +6978,7 @@ const parseCommitMessage = (message) => {
 		branch: void 0,
 		version: void 0,
 		kept: void 0,
+		approved: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -6965,6 +7004,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`);
@@ -7060,7 +7100,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"])
@@ -7070,6 +7111,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,
@@ -7229,12 +7277,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);
@@ -7245,6 +7302,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);
@@ -8355,6 +8414,9 @@ const planStep = (snapshot, opts = {}) => {
 					kind: "keepTurn",
 					ref: landing.keepTurn,
 					message
+				} : landing.spec.approved !== void 0 ? {
+					kind: "commitClean",
+					message
 				} : {
 					kind: "commitAll",
 					message
@@ -8556,6 +8618,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));
@@ -8571,6 +8639,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),
@@ -8856,7 +8925,8 @@ const messageDef = (common, request, step) => ({
 	...common,
 	kind: "message",
 	content: request.options.message ?? request.options.label ?? step.name,
-	...optional("acceptClean", request.options.acceptClean)
+	...optional("acceptClean", request.options.approve === true || request.options.acceptClean),
+	...optional("approve", request.options.approve)
 });
 const stepDefOf = (step) => {
 	const request = step.request;
@@ -8985,6 +9055,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;
@@ -9000,7 +9076,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$5(/* @__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
 	})) : [];
@@ -9086,6 +9162,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;
@@ -9140,7 +9235,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
@@ -9158,6 +9257,7 @@ const landingTo = (rest, to, branch) => {
 			from: rest.state,
 			to,
 			step: rest.step.id,
+			...approvedTrailer(rest, approver),
 			...starts ? {
 				vars: rest.vars,
 				config: rest.config
@@ -9173,7 +9273,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) {
@@ -9189,14 +9291,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()).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll$1(() => succeed$6(void 0)));
+const previewLanding = (rest) => decideLanding(rest, void 0, none(), none()).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll$1(() => succeed$6(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();
+	const landing = yield* decideLanding(rest, verdicts, branch, approver);
 	return {
 		stepDef: rest.stepDef,
 		state: rest.state,
@@ -9250,7 +9354,8 @@ const historySteps = (run) => {
 			actor: entry.actor,
 			from: message.parsed?.from,
 			to: entry.state,
-			verdicts: message.judge
+			verdicts: message.judge,
+			...optional("approval", approvalEntryOf(entry.hash, message)[0])
 		};
 	});
 };
@@ -9308,8 +9413,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(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(message)}) || exit 1`,
+	`git update-ref -m ${shellQuote(`commit: ${message}`)} HEAD "$gtd_tip" "$gtd_head" || exit 1`
+].join("\n");
 /** No current caller — see `Git.ts`'s `GitWriterOperations.commitAsIs` for why it's kept anyway. */
 const commitAsIs = (message) => commitAllowEmpty(message);
 /** No current caller — see `Git.ts`'s `GitWriterOperations.softResetTo` for why it's kept anyway. */
@@ -9347,7 +9470,7 @@ const keepTurn = (refPrefix, message) => {
 		`gtd_kept=$(git commit-tree "$gtd_tree" -p "$gtd_head" -m ${shellQuote(message)}) || exit 1`,
 		`git update-ref ${keptRef} "$gtd_kept" || exit 1`,
 		`gtd_marker=$(printf '%s\\nGtd-Kept: %s' ${shellQuote(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(`commit: ${message}`)} HEAD "$gtd_tip" "$gtd_head"; then`,
 		`  git reset -q && git update-ref -d ${keptRef}`,
 		`  exit 1`,
 		`fi`,
@@ -9385,6 +9508,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);
 	}
@@ -9858,6 +9982,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`);
@@ -10391,7 +10516,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
 	}));
 });
 /**
@@ -11080,11 +11206,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"
 		]
 	},
 	{
@@ -11697,6 +11823,10 @@ var InMemRepo = class InMemRepo {
 	changedPathsWorktree(base) {
 		return diffTrees(this.treeAt(base), new Map(this.worktree));
 	}
+	/** The index vs HEAD — the port's `stagedPaths`. */
+	stagedPaths() {
+		return diffTrees(this.treeAt(void 0), this.index);
+	}
 	diffPaths(base, tip) {
 		for (const ref of [base, tip]) if (this.resolveRef(ref) === null) throw new Error(`Invalid ref: ${ref}`);
 		return diffTrees(this.treeAt(base), this.treeAt(tip)).map((e) => e.path);
@@ -11756,6 +11886,7 @@ var InMemRepo = class InMemRepo {
 	/** Seeded failure modes (see `GitTierSeed`): a pre-commit hook printing this and exiting 1, and a signer that cannot write. */
 	hookRejection = void 0;
 	signingFails = false;
+	signingEnabled = false;
 	/** Seeded: a pre-commit hook writing and staging this file. */
 	hookStages = void 0;
 	writeCommit(message) {
@@ -11767,7 +11898,8 @@ var InMemRepo = class InMemRepo {
 			message,
 			files: new Map(tree),
 			parent,
-			seq: this.nextSeq++
+			seq: this.nextSeq++,
+			signed: this.signingEnabled
 		};
 		this.commits.set(hash, commit);
 		this.head = hash;
@@ -11788,6 +11920,16 @@ var InMemRepo = class InMemRepo {
 		}
 		this.writeCommit(message);
 	}
+	/** Twin of `GitScript.commitClean`: no hook runs, HEAD's tree is recorded; `undefined` on success, else the stderr text. */
+	commitClean(message) {
+		if (this.head === null) return "fatal: Needed a single revision";
+		if (this.statusPorcelain().trim() !== "") return CHANGED_SINCE_LAND;
+		if (this.signingFails) return "error: gpg failed to sign the data";
+		this.writeCommit(message);
+	}
+	headSigned() {
+		return this.headCommit()?.signed === true;
+	}
 	/** Setup commit: stages everything, and throws if a failure is seeded, as the Live tier's hooks and signer would. */
 	seedCommit(message) {
 		if (this.hookRejection !== void 0 || this.hookStages !== void 0 || this.signingFails) throw new Error("seedCommit after a seeded commit failure");
@@ -11805,7 +11947,8 @@ var InMemRepo = class InMemRepo {
 			message,
 			files: new Map(tree),
 			parent,
-			seq: this.nextSeq++
+			seq: this.nextSeq++,
+			signed: false
 		});
 		const ref = `${refPrefix}/${hash}`;
 		this.refs.set(ref, hash);
@@ -12000,7 +12143,12 @@ const makeGitReaderOps = (repo, root) => ({
 	commitHistory: (base, head) => succeed$6(repo.commitHistory(base, head)),
 	subjectHistory: (pageSize, skip, head) => succeed$6(repo.subjectHistory(pageSize, skip, head)),
 	changedPaths: (base) => succeed$6(repo.changedPathsWorktree(base)),
-	diffPaths: (base, tip) => tryCatch(() => repo.diffPaths(base, tip))
+	stagedPaths: () => succeed$6(repo.stagedPaths()),
+	diffPaths: (base, tip) => tryCatch(() => repo.diffPaths(base, tip)),
+	authorIdent: () => succeed$6(some({
+		name: "Test",
+		email: "test@test.com"
+	}))
 });
 const failOn = (output) => {
 	if (output !== void 0) throw new Error(output);
@@ -12557,6 +12705,18 @@ const recognizeGitBuilders = (repo, block) => {
 		}
 		return;
 	}
+	if (block.startsWith("gtd_head=$(git rev-parse --verify HEAD) || exit 1\nif [ -n ")) {
+		const [message] = extractQuotedTokens(block.slice(block.indexOf("\"$gtd_head\" -m ")));
+		if (message !== void 0 && commitClean(message) === block) {
+			const failure = repo.commitClean(message);
+			return failure === void 0 ? { kind: "applied" } : {
+				kind: "failed",
+				error: failure,
+				status: 1
+			};
+		}
+		return;
+	}
 	if (block.startsWith("if ! out=$(git commit --allow-empty -m ")) {
 		const [message] = extractQuotedTokens(conditionLine);
 		if (message !== void 0 && commitAsIs(message) === block) {
@@ -12961,6 +13121,17 @@ const recognizeDeferNotes = (repo, block) => {
 	repo.writeFile(".gtd/TODO.md", `${old}${sep}${lines.join("\n")}\n`);
 	return { kind: "applied" };
 };
+/** `mkdir -p <dir>` then `printf '%s\n' <quoted lines> > <path>`: a flow's one-file write. Re-rendered from what was extracted, so any other shape stays unrecognized. */
+const recognizeWriteLines = (repo, block) => {
+	const [mkdir, printf, ...rest] = block.split("\n");
+	if (rest.length > 0 || !mkdir?.startsWith("mkdir -p ") || !printf?.startsWith("printf '%s\\n' ")) return;
+	const tokens = extractQuotedTokens(printf.slice(14));
+	const path = tokens.pop();
+	if (path === void 0 || !path.includes("/")) return void 0;
+	if (`mkdir -p ${path.slice(0, path.lastIndexOf("/"))}\nprintf '%s\\n' ${tokens.map(shellQuote).join(" ")} > ${shellQuote(path)}` !== block) return void 0;
+	repo.writeFile(path, `${tokens.join("\n")}\n`);
+	return { kind: "applied" };
+};
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (repo, commands) => [
 	(block) => recognizeSetFlags(block),
@@ -12970,6 +13141,7 @@ const recognizersFor = (repo, commands) => [
 	(block) => recognizeBinaryGuard(commands, block),
 	(block) => recognizeGitBuilders(repo, block),
 	(block) => recognizeDeferNotes(repo, block),
+	(block) => recognizeWriteLines(repo, block),
 	(block) => recognizeFailurePromptWrapper(repo, commands, block),
 	(block) => recognizePresentationSubshell(repo, commands, block),
 	(block) => recognizeModeContradictionSkipNotice(block),
@@ -13309,6 +13481,13 @@ const makeLiveTier = (initialCommit = true) => {
 				gitExec("config", "commit.gpgsign", "true");
 				gitExec("config", "gpg.format", "openpgp");
 				gitExec("config", "gpg.program", "false");
+			},
+			workingSigner: () => {
+				const signer = join(root, ".git/gtd-test-signer.sh");
+				writeFileSync(signer, `#!/bin/sh\ncat >/dev/null\nprintf '%s\\n' '-----BEGIN PGP SIGNATURE-----' '' 'ZHVtbXk=' '-----END PGP SIGNATURE-----'\nprintf '\\n[GNUPG:] SIG_CREATED ' >&2\n`, { mode: 493 });
+				gitExec("config", "commit.gpgsign", "true");
+				gitExec("config", "gpg.format", "openpgp");
+				gitExec("config", "gpg.program", signer);
 			}
 		},
 		observe: {
@@ -13338,7 +13517,8 @@ const makeLiveTier = (initialCommit = true) => {
 				});
 			},
 			headSubject: () => gitExec("log", "-1", "--pretty=%s"),
-			headTouchedPaths: () => gitExec("show", "--name-only", "--pretty=format:", "HEAD").split("\n").filter((line) => line.length > 0)
+			headTouchedPaths: () => gitExec("show", "--name-only", "--pretty=format:", "HEAD").split("\n").filter((line) => line.length > 0),
+			headSigned: () => gitExec("cat-file", "commit", "HEAD").includes("\ngpgsig ")
 		},
 		runScript: (script) => {
 			const result = spawnSync("sh", ["-c", `exec 2>&1\n${script}`], {
@@ -13417,6 +13597,9 @@ const makeInMemTier = (initialCommit = true) => {
 			},
 			failingSigner: () => {
 				repo.signingFails = true;
+			},
+			workingSigner: () => {
+				repo.signingEnabled = true;
 			}
 		},
 		observe: {
@@ -13437,7 +13620,8 @@ const makeInMemTier = (initialCommit = true) => {
 			headSubject: () => repo.lastCommitSubject() ?? "",
 			headTouchedPaths: () => {
 				return [.../* @__PURE__ */ new Set([...repo.pathsAtRef("HEAD~1"), ...repo.pathsAtRef("HEAD")])].filter((p) => repo.fileAtRef("HEAD~1", p) !== repo.fileAtRef("HEAD", p)).sort();
-			}
+			},
+			headSigned: () => repo.headSigned()
 		},
 		runScript: (script, commands = /* @__PURE__ */ new Map()) => {
 			const { ok, status, output, error } = applyEmittedScript(repo, commands, script);
@@ -13514,7 +13698,9 @@ const runGitServiceContract = (makeTier) => {
 			g.readFileAtRef("HEAD", "second.txt"),
 			g.changedPaths(),
 			g.changedPaths("HEAD~1"),
-			g.diffPaths("HEAD~1", "HEAD")
+			g.stagedPaths(),
+			g.diffPaths("HEAD~1", "HEAD"),
+			g.authorIdent()
 		]));
 		expect(await t.observe.snapshot()).toBe(before);
 		await runGit(t, (g) => g.updateRef("refs/gtd/marker", t.observe.resolveRef("HEAD")));
@@ -14002,6 +14188,13 @@ const runGitServiceContract = (makeTier) => {
 		it("returns [] on a clean tree", async () => {
 			expect(await runGit(t, (g) => g.changedPaths())).toEqual([]);
 		});
+		it("ignores an edit staged and then reverted in the worktree", async () => {
+			t.seed.commit("chore: seed", { "a.txt": "1" });
+			t.seed.writeFile("a.txt", "2");
+			t.seed.stageAll();
+			t.seed.writeFile("a.txt", "1");
+			expect(await runGit(t, (g) => g.changedPaths())).toEqual([]);
+		});
 		for (const { label, path } of PATHOLOGICAL_PATHS) it(`reports an untracked path containing ${label}, verbatim`, async () => {
 			t.seed.writeFile(path, "content");
 			expect(await runGit(t, (g) => g.changedPaths())).toEqual([{
@@ -14086,6 +14279,45 @@ const runGitServiceContract = (makeTier) => {
 			});
 		});
 	});
+	describe("stagedPaths", () => {
+		it("returns [] when the index matches HEAD, whatever the worktree holds", async () => {
+			t.seed.commit("chore: seed", { "a.txt": "1" });
+			t.seed.writeFile("a.txt", "2");
+			t.seed.writeFile("u.txt", "u");
+			expect(await runGit(t, (g) => g.stagedPaths())).toEqual([]);
+		});
+		it("reports an edit staged and then reverted in the worktree", async () => {
+			t.seed.commit("chore: seed", { "a.txt": "1" });
+			t.seed.writeFile("a.txt", "2");
+			t.seed.stageAll();
+			t.seed.writeFile("a.txt", "1");
+			expect(await runGit(t, (g) => g.stagedPaths())).toEqual([{
+				path: "a.txt",
+				status: "M"
+			}]);
+		});
+		it("reports staged additions and deletions", async () => {
+			t.seed.commit("chore: seed", { "gone.txt": "g" });
+			t.seed.deleteFile("gone.txt");
+			t.seed.writeFile("new.txt", "n");
+			t.seed.stageAll();
+			expect([...await runGit(t, (g) => g.stagedPaths())].sort((a, b) => a.path.localeCompare(b.path))).toEqual([{
+				path: "gone.txt",
+				status: "D"
+			}, {
+				path: "new.txt",
+				status: "A"
+			}]);
+		});
+	});
+	describe("authorIdent", () => {
+		it("is the configured name and email", async () => {
+			expect(await runGit(t, (g) => g.authorIdent())).toEqual(some({
+				name: "Test",
+				email: "test@test.com"
+			}));
+		});
+	});
 	describe("topLevel", () => {
 		it("resolves to this tier's own root", async () => {
 			expect(await runGit(t, (g) => g.topLevel())).toBe(t.root);
@@ -14180,6 +14412,74 @@ const runGitScriptContract = (makeTier) => {
 			expect(t.observe.headSubject()).toBe("gtd: grilled");
 		});
 	});
+	describe("commitClean", () => {
+		it("on a clean tree commits an empty commit with the message", () => {
+			const headBefore = t.observe.resolveRef("HEAD");
+			run(t, commitClean("gtd(human): gate → again"));
+			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
+			expect(t.observe.headSubject()).toBe("gtd(human): gate → again");
+			expect(t.observe.headTouchedPaths()).toEqual([]);
+		});
+		it("a staging hook never runs: nothing touched, nothing staged, file absent", () => {
+			const headBefore = t.observe.resolveRef("HEAD");
+			t.seed.stagingHook("hooked.txt", "hooked");
+			run(t, commitClean("gtd(human): gate → again"));
+			expect(t.observe.headTouchedPaths()).toEqual([]);
+			expect(t.observe.resolveRef("HEAD^")).toBe(headBefore);
+			expect(t.observe.statusPorcelain().trim()).toBe("");
+			expect(t.observe.existsPath("hooked.txt")).toBe(false);
+		});
+		it("a rejecting hook is never consulted", () => {
+			t.seed.rejectingHook("rejected");
+			run(t, commitClean("gtd(human): gate → again"));
+			expect(t.observe.headSubject()).toBe("gtd(human): gate → again");
+		});
+		it("a working signer signs the approval", () => {
+			t.seed.workingSigner();
+			run(t, commitClean("gtd(human): gate → again"));
+			expect(t.observe.headSigned()).toBe(true);
+		});
+		it("no signing config: the approval does not try to sign", () => {
+			run(t, commitClean("gtd(human): gate → again"));
+			expect(t.observe.headSigned()).toBe(false);
+		});
+		it("a failing signer fails the approval: HEAD and status unchanged", () => {
+			t.seed.failingSigner();
+			const headBefore = t.observe.resolveRef("HEAD");
+			const result = t.runScript(commitClean("gtd(human): gate → again"));
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(1);
+			expect(result.output).toContain("failed to sign");
+			expect(t.observe.resolveRef("HEAD")).toBe(headBefore);
+			expect(t.observe.statusPorcelain().trim()).toBe("");
+		});
+		const refused = (name, dirty, pending) => {
+			it(`${name}: fails, HEAD unchanged, edit still pending`, () => {
+				dirty();
+				const headBefore = t.observe.resolveRef("HEAD");
+				const result = t.runScript(commitClean("gtd(human): gate → again"));
+				expect(result.ok).toBe(false);
+				expect(result.output).toContain("changed since `gtd land`");
+				expect(t.observe.resolveRef("HEAD")).toBe(headBefore);
+				expect(t.observe.statusPorcelain()).toContain(pending);
+			});
+		};
+		refused("a modified tracked file", () => {
+			t.seed.commit("feat: base", { "a.txt": "1" });
+			t.seed.writeFile("a.txt", "2");
+		}, "a.txt");
+		refused("a staged change", () => {
+			t.seed.writeFile("s.txt", "s");
+			t.seed.stageAll();
+		}, "s.txt");
+		refused("an untracked file", () => t.seed.writeFile("u.txt", "u"), "u.txt");
+		refused("an edit staged then reverted in the worktree", () => {
+			t.seed.commit("feat: base", { "a.txt": "1" });
+			t.seed.writeFile("a.txt", "2");
+			t.seed.stageAll();
+			t.seed.writeFile("a.txt", "1");
+		}, "a.txt");
+	});
 	describe("commitAsIs", () => {
 		it("does NOT stage — a worktree write after staging is excluded (the squash mechanic)", () => {
 			t.seed.writeFile("a.txt", "a");