@pmelab/gtd 27.3.0 → 27.5.0

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))),
@@ -20962,13 +20970,23 @@ const restorability = (git, headHash, tipHash) => gen(function* () {
 });
 //#endregion
 //#region src/flags/index.ts
-const FLAGS$1 = [];
+const FLAGS$1 = [{
+	name: "naive_pass",
+	owner: "pmelab",
+	expiry: "2027-01-15",
+	kind: "release"
+}];
 const BOOL = {
 	"0": false,
 	false: false,
 	"1": true,
 	true: true
 };
+/** A `flag_<name>` setting's value as the pinned `"1"`/`"0"`, or undefined when garbled. */
+const flagSettingValue = (raw) => {
+	const key = raw.toLowerCase();
+	return Object.hasOwn(BOOL, key) ? BOOL[key] ? "1" : "0" : void 0;
+};
 const resolveFlags = (env, registry = FLAGS$1) => {
 	const out = {};
 	for (const { name, defaultOn } of registry) {
@@ -20983,6 +21001,7 @@ const resolveFlags = (env, registry = FLAGS$1) => {
 	}
 	return out;
 };
+const flagSettings = (flags) => Object.fromEntries(Object.entries(flags).map(([name, on]) => [`flag_${name}`, on ? "1" : "0"]));
 //#endregion
 //#region src/install/Version.ts
 const _require = createRequire(import.meta.url);
@@ -21231,7 +21250,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
@@ -21967,7 +21987,8 @@ const strayContent = (strays) => strays.map((c) => [
 */
 const judgeDiffShape = async (name, options) => {
 	const { changes: all, allow } = options;
-	const isStray = (c) => !allow.some((pattern) => matches(c.path, pattern));
+	const exempt = options.exempt ?? [];
+	const isStray = (c) => !exempt.includes(c.path) && !allow.some((pattern) => matches(c.path, pattern));
 	const strayChanges = all.filter(isStray).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).map(({ path, status, before, after }) => ({
 		path,
 		status,
@@ -22013,6 +22034,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");
@@ -22191,6 +22234,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	configure: () => configure$1,
 	defineConfig: () => defineConfig,
 	defineWorkflow: () => defineWorkflow,
+	displayPath: () => displayPath,
 	env: () => env,
 	glob: () => glob,
 	hasThreadFor: () => hasThreadFor,
@@ -22220,6 +22264,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	revertScript: () => revertScript,
 	run: () => run$3,
 	scope: () => scope,
+	seamGate: () => seamGate,
 	sectionBodies: () => sectionBodies,
 	sections: () => sections,
 	showScript: () => showScript,
@@ -37282,7 +37327,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 +37345,8 @@ var init_BeatStatus = __esmMin((() => {
 			next,
 			cost,
 			costByModel,
-			judge: rendered.judge
+			judge: rendered.judge,
+			approvals
 		};
 	};
 }));
@@ -37360,7 +37406,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 +37736,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 +37802,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 +37826,7 @@ const parseCommitMessage = (message) => {
 		branch: void 0,
 		version: void 0,
 		kept: void 0,
+		approved: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -37775,6 +37852,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 +37948,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 +37959,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 +38125,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 +38150,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);
@@ -38284,7 +38381,10 @@ const compileConfig = (value, origin) => {
 };
 //#endregion
 //#region src/workflow/vars.ts
+init_esm();
 const PREFIX = "GTD_";
+/** The live release flags as `flag_<name>` settings, provided by the CLI; absent means no flags. */
+var StartFlags = class extends Reference()("StartFlags", { defaultValue: () => ({}) }) {};
 /**
 * One kind of setting, later wins: the workflow's own defaults, `--var`
 * overrides (process settings only; environment settings pass `{}`), then
@@ -38304,6 +38404,18 @@ const resolveVars = (workflowVars, entryVars, env) => {
 	}
 	return merged;
 };
+/**
+* `resolveVars` for a process being STARTED: `flags` land between the workflow
+* defaults and `--var`, for already-declared names only. A running process never
+* calls this — it replays its pinned record.
+*/
+const resolveStartVars = (workflowVars, flags, entryVars, env) => {
+	const declared = Object.fromEntries(Object.entries(flags).filter(([name]) => Object.hasOwn(workflowVars, name)));
+	return resolveVars({
+		...workflowVars,
+		...declared
+	}, entryVars, env);
+};
 /** The first process setting whose value spans lines — a `Gtd-Var:` trailer cannot carry it. */
 const multilineSetting = (vars) => Object.keys(vars).sort().find((name) => /[\r\n]/.test(vars[name]));
 const SETTING_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -39169,6 +39281,9 @@ const planStep = (snapshot, opts = {}) => {
 					kind: "keepTurn",
 					ref: landing.keepTurn,
 					message
+				} : landing.spec.approved !== void 0 ? {
+					kind: "commitClean",
+					message
 				} : {
 					kind: "commitAll",
 					message
@@ -39234,7 +39349,7 @@ const planStart = (current, actor, start) => gen(function* () {
 	const overrideRefusal = yield* checkOverrides(commandLabel, varOverrides, Object.keys(workflow.vars), Object.keys(workflow.env));
 	if (overrideRefusal !== void 0) return overrideRefusal;
 	const baseOf = workflow.def.base;
-	const vars = resolveVars(workflow.vars, varOverrides, (yield* Host).env);
+	const vars = resolveStartVars(workflow.vars, yield* StartFlags, varOverrides, (yield* Host).env);
 	const multiline = multilineSetting(vars);
 	if (multiline !== void 0) return refusal(`${commandLabel}: process setting "${multiline}" spans several lines — a process setting is pinned in a commit trailer and must be a single line`);
 	const template = yield* try_({
@@ -39376,6 +39491,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 +39512,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),
@@ -39579,9 +39701,9 @@ const pendingTree = (workspace, entries, rewrite) => {
 * are always live. `startOverrides` are `--var` values, passed only while a
 * process is being started.
 */
-const settingsFor = (workflow, pinnedVars, hostEnv, startOverrides = {}) => ({
+const settingsFor = (workflow, pinnedVars, hostEnv, startOverrides = {}, startFlags) => ({
 	vars: {
-		...resolveVars(workflow.vars, startOverrides, hostEnv),
+		...resolveStartVars(workflow.vars, startFlags, startOverrides, hostEnv),
 		...pinnedVars
 	},
 	env: resolveVars(workflow.env, {}, hostEnv)
@@ -39676,7 +39798,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;
@@ -39754,7 +39877,8 @@ const costByModel = (entries) => {
 const setupFor = (config, run, workspace, host, startOverrides = {}) => gen(function* () {
 	const resolved = yield* workflowOf(config, run);
 	const def = resolved.def;
-	const { vars, env } = settingsFor(resolved, run.pinnedVars, host.env, startOverrides);
+	const startFlags = run.trace.length === 0 ? yield* StartFlags : {};
+	const { vars, env } = settingsFor(resolved, run.pinnedVars, host.env, startOverrides, startFlags);
 	const skills = yield* resolveScopeSkills(def, vars);
 	const access = yield* resolveScopeAccess(def, skills, vars);
 	const budget = yield* try_({
@@ -39805,6 +39929,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 +39950,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
 	})) : [];
@@ -39858,7 +39988,7 @@ const currentRest = restAt(void 0);
 */
 const startRefusal = (rest, resolved, startVars) => gen(function* () {
 	const host = yield* Host;
-	const { vars, env } = settingsFor(resolved, {}, host.env, startVars);
+	const { vars, env } = settingsFor(resolved, {}, host.env, startVars, yield* StartFlags);
 	const skills = yield* resolveScopeSkills(resolved.def, vars);
 	const access = yield* resolveScopeAccess(resolved.def, skills, vars);
 	const workspace = rest.setup.workspace;
@@ -39906,6 +40036,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 +40109,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 +40131,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 +40147,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 +40165,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,
@@ -40044,7 +40202,7 @@ const summaryFor = (run) => gen(function* () {
 		})),
 		processCost: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
 		processCostByModel: costByModel(run.costEntries),
-		...settingsFor(resolved, run.pinnedVars, host.env)
+		...settingsFor(resolved, run.pinnedVars, host.env, {}, {})
 	});
 });
 /** Repository-relative paths of the config files today's config and the process's own record name; one outside the repository cannot be read at a ref, so it is left out. */
@@ -40070,7 +40228,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 +40287,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 +40332,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 +40370,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 +40854,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 +41394,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
 	}));
 });
 /**
@@ -41500,6 +41680,12 @@ const FLAGS = [
 				if (/[\r\n]/.test(value)) return left(`gtd: --var ${name} must be a single-line value`);
 				if (seen.has(name)) return left(`gtd: --var ${name} specified more than once`);
 				seen.add(name);
+				if (name.startsWith("flag_")) {
+					const pinned = flagSettingValue(value);
+					if (pinned === void 0) return left(`gtd: --var ${name} must be 1, 0, true or false`);
+					vars[name] = pinned;
+					continue;
+				}
 				vars[name] = value;
 			}
 			return right(vars);
@@ -41906,11 +42092,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"
 		]
 	},
 	{
@@ -42337,7 +42523,7 @@ const runCli = (argv, io) => {
 	return flatMap$4(Host, ({ env }) => try_({
 		try: () => resolveFlags(env, io.flags),
 		catch: (e) => new GtdError(e.message)
-	})).pipe(flatMap$4(() => runCommand(plan.command, plan.json, out)), map$4((code) => {
+	})).pipe(flatMap$4((flags) => runCommand(plan.command, plan.json, out).pipe(provideService(StartFlags, flagSettings(flags)))), map$4((code) => {
 		out.flush();
 		io.exit(code);
 	}), provide$1(io.layers(plan.verbose)), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json.kind !== "off")(cause)));