@pmelab/gtd 25.0.0 → 26.1.0

package/dist/testkit.mjs

@@ -6071,6 +6071,8 @@ const HISTORY_REF = "refs/worktree/gtd/history";
 /** One ref per finished process, kept past the branch's deletion; distinct from the per-worktree `HISTORY_REF`. */
 const PROCESS_HISTORY_PREFIX = "refs/gtd/history/";
 const processHistoryRef = (hash) => `${PROCESS_HISTORY_PREFIX}${hash}`;
+/** Directory of a step's turns set aside by `keep: true`, each at `<this>/<kept hash>`; own namespace, so history list/show/fetch never see it. */
+const keptRef = (entry, step) => `refs/gtd/kept/${entry}/${step}`;
 const readRetainedHistory = (git) => git.readRefOption(HISTORY_REF);
 /**
 * Whether resetting to `tipHash` is safe: HEAD must be an ancestor of
@@ -6085,6 +6087,26 @@ const restorability = (git, headHash, tipHash) => gen(function* () {
 	};
 });
 //#endregion
+//#region src/flags/index.ts
+const FLAGS$1 = [];
+const BOOL = {
+	"": false,
+	"0": false,
+	false: false,
+	"1": true,
+	true: true
+};
+const resolveFlags = (env, registry = FLAGS$1) => {
+	const out = {};
+	for (const { name } of registry) {
+		const variable = `GTD_FLAG_${name.toUpperCase()}`;
+		const key = (env[variable] ?? "").toLowerCase();
+		if (!Object.hasOwn(BOOL, key)) throw new Error(`${variable} must be 1, 0, true or false`);
+		out[name] = BOOL[key];
+	}
+	return out;
+};
+//#endregion
 //#region src/install/Version.ts
 const _require = createRequire(import.meta.url);
 const findPackageJson = (fromUrl) => {
@@ -6750,6 +6772,22 @@ const accessShapeFault = (value) => {
 const sameGlobs = (a, b) => a === void 0 || b === void 0 ? a === b : a.length === b.length && a.every((g, i) => g === b[i]);
 const sameAccess = (a, b) => sameGlobs(a?.read, b?.read) && sameGlobs(a?.write, b?.write);
 //#endregion
+//#region src/replay/RefName.ts
+const FORBIDDEN = /[\u0000- \u007f~^:?*[\\]/;
+/** Why `name` cannot be (part of) a git ref name, or `undefined` when it can. */
+const refNameFault = (name) => {
+	if (name === "") return "it is empty";
+	if (FORBIDDEN.test(name)) return "it contains a space, control character or one of ~^:?*[\\";
+	if (name.includes("..")) return "it contains \"..\"";
+	if (name.includes("@{")) return "it contains \"@{\"";
+	if (name.endsWith(".")) return "it ends with \".\"";
+	for (const part of name.split("/")) {
+		if (part === "") return "it has an empty \"/\" component";
+		if (part.startsWith(".")) return "a component starts with \".\"";
+		if (part.endsWith(".lock")) return "a component ends with \".lock\"";
+	}
+};
+//#endregion
 //#region src/replay/Tree.ts
 const treeFromRecord = (files) => ({
 	paths: () => Object.keys(files).sort(),
@@ -6844,6 +6882,7 @@ const decodePath = (raw) => {
 	return typeof path === "string" && path !== "" && !CONTROL_CHARACTER$1.test(path) ? path : void 0;
 };
 const FORMAT_RE = /^[1-9][0-9]*$/;
+const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const TRAILER_READERS = {
 	"Gtd-Step": (value, into) => {
 		into.step ??= parseStepId(value);
@@ -6873,6 +6912,9 @@ const TRAILER_READERS = {
 	"Gtd-Version": (value, into) => {
 		if (value !== "") into.version ??= value;
 	},
+	"Gtd-Kept": (value, into) => {
+		if (HASH_RE.test(value)) into.kept ??= value;
+	},
 	"Gtd-Format": (value, into) => {
 		if (FORMAT_RE.test(value)) into.format ??= Number(value);
 	},
@@ -6893,6 +6935,7 @@ const parseCommitMessage = (message) => {
 		reviewBase: void 0,
 		branch: void 0,
 		version: void 0,
+		kept: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -7007,7 +7050,8 @@ const KNOWN_OPTIONS = {
 		...STEERING_OPTIONS,
 		"model",
 		"system",
-		"allowEmpty"
+		"allowEmpty",
+		"keep"
 	]),
 	human: /* @__PURE__ */ new Set([
 		...STEERING_OPTIONS,
@@ -7039,6 +7083,7 @@ const replay = async (input) => {
 	const scopeCallIds = [];
 	let scopeCallCount = 0;
 	const trace = [];
+	const keptTips = /* @__PURE__ */ new Map();
 	let landed;
 	let outcome;
 	let signal;
@@ -7198,6 +7243,12 @@ const replay = async (input) => {
 		}
 		cursor++;
 		advance(commit);
+		if (commit.parsed.kept !== void 0) if (commit.kept === void 0) keptTips.delete(step.name);
+		else keptTips.set(step.name, {
+			hash: commit.kept.hash,
+			before: commit.tree,
+			after: commit.kept.tree
+		});
 		const to = commit.parsed.parsed?.to;
 		if (to !== void 0) expectedNext = {
 			name: to,
@@ -7205,6 +7256,21 @@ const replay = async (input) => {
 		};
 		return replyFor(step.request, commit.parsed.judge);
 	};
+	const landPending = (step, pending) => {
+		pendingUsed = true;
+		landed = step;
+		const keeping = step.request.kind === "agent" && step.request.options.keep === true;
+		if (keeping) keptTips.set(step.name, {
+			hash: "",
+			before: position.tree,
+			after: pending.tree
+		});
+		advance({
+			hash: "",
+			tree: keeping ? position.tree : pending.tree
+		});
+		return replyFor(step.request, pending.verdicts ?? []);
+	};
 	const answer = (step) => {
 		while (cursor < commits.length && isAttemptAt(commits[cursor], step.name)) cursor++;
 		const commit = commits[cursor];
@@ -7215,17 +7281,18 @@ const replay = async (input) => {
 			trace,
 			landed
 		});
-		pendingUsed = true;
-		landed = step;
-		advance({
-			hash: "",
-			tree: input.pending.tree
-		});
-		return replyFor(step.request, input.pending.verdicts ?? []);
+		return landPending(step, input.pending);
 	};
 	const requestFault = (request) => {
 		if (request.kind === "run" && typeof request.body !== "string") return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`;
-		return request.kind === "agent" ? scopeAccessFault() : void 0;
+		if (request.kind !== "agent") return void 0;
+		const name = scoped(request.name);
+		if (request.options.keep === true) {
+			if (request.options.allowEmpty === true) return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`;
+			const refFault = name.includes("/") ? "it contains \"/\"" : refNameFault(name);
+			if (refFault !== void 0) return `gtd: step "${name}": keep: true files the turn under a git ref named after the step, but ${refFault}`;
+		}
+		return scopeAccessFault();
 	};
 	const handleStep = async (request) => {
 		if (outcome !== void 0) throw new Stop();
@@ -7308,6 +7375,13 @@ const replay = async (input) => {
 				faults: findings.filter((f) => f.message.startsWith(`Code thread at ${c.path}:${t.line + 1}: `)).map((f) => f.message)
 			}));
 		}),
+		kept: (name) => {
+			const tip = keptTips.get(scoped(name));
+			return tip === void 0 ? void 0 : {
+				hash: tip.hash,
+				changes: changesBetween(tip.before, tip.after)
+			};
+		},
 		vars: input.vars,
 		env: input.env,
 		start: () => input.start,
@@ -7408,7 +7482,9 @@ const resolveVars = (workflowVars, entryVars, env) => {
 		...entryVars
 	};
 	for (const name of Object.keys(merged)) {
-		const value = env[PREFIX + name.toUpperCase()];
+		const key = PREFIX + name.toUpperCase();
+		if (key.startsWith("GTD_FLAG_")) continue;
+		const value = env[key];
 		if (value !== void 0) merged[name] = value;
 	}
 	return merged;
@@ -8271,7 +8347,11 @@ const planStep = (snapshot, opts = {}) => {
 			...uncheckStep(snapshot),
 			{
 				kind: "gitWrite",
-				write: {
+				write: landing.keepTurn !== void 0 ? {
+					kind: "keepTurn",
+					ref: landing.keepTurn,
+					message
+				} : {
 					kind: "commitAll",
 					message
 				}
@@ -8746,6 +8826,7 @@ const promptDef = (common, request, skills, access) => ({
 	...optional("model", request.options.model),
 	...optional("system", request.options.system),
 	...optional("allowEmpty", request.options.allowEmpty),
+	...optional("keep", request.options.keep),
 	...optional("skills", skills),
 	...optional("access", access)
 });
@@ -8860,11 +8941,21 @@ const setupFor = (config, run, workspace, host, startOverrides = {}) => gen(func
 		hash: run.episode.base,
 		tree: commitTree(workspace, run.episode.base)
 	};
-	const episode = run.episode.commits.map((c) => ({
-		hash: c.hash,
-		message: c.message,
-		tree: commitTree(workspace, c.hash)
-	}));
+	const git = yield* GitService;
+	const episode = [];
+	for (const c of run.episode.commits) {
+		const tip = parseCommitMessage(c.message).kept;
+		const exists = tip !== void 0 && isSome(yield* git.readRefOption(`${tip}^{commit}`));
+		episode.push({
+			hash: c.hash,
+			message: c.message,
+			tree: commitTree(workspace, c.hash),
+			...exists ? { kept: {
+				hash: tip,
+				tree: commitTree(workspace, tip)
+			} } : {}
+		});
+	}
 	let pendingMemo;
 	return {
 		resolved,
@@ -9040,6 +9131,7 @@ const closingTrailers = (branch) => ({
 	...isSome(branch) ? { branch: branch.value } : {}
 });
 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) => {
 	if (isSettledNoop(rest, to)) return {
 		kind: "noop",
@@ -9064,7 +9156,8 @@ const landingTo = (rest, to, branch) => {
 			} : {},
 			...finishes ? closingTrailers(branch) : {}
 		},
-		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {}
+		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {},
+		...keptTurn(rest)
 	};
 };
 /**
@@ -9201,7 +9294,7 @@ const commitAllowEmpty = (message) => {
 	return [
 		`if ! out=$(git commit --allow-empty -m ${m} 2>&1); then`,
 		`  case "$out" in`,
-		`    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} ;;`,
+		`    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} || exit 1 ;;`,
 		`    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
 		`  esac`,
 		`fi`
@@ -9223,6 +9316,36 @@ const hardResetTo = (ref) => `git reset --hard ${shellQuote(ref)}`;
 * `GitWriterOperations.discardPending` for why it's kept anyway.
 */
 const discardPending = () => `git add -A && git reset --hard HEAD`;
+/**
+* POSIX sh (runs under dash). The marker is a `commit-tree` over HEAD's own
+* tree, so no hook runs on it and its tree is the pre-turn tree by
+* construction; `commit-tree` ignores `commit.gpgSign`, hence the explicit
+* `-S`, read (and failing closed) before any object or ref is written; the
+* index is already staged by then, so an early exit leaves the turn staged.
+* The kept ref is deleted only after `reset -q` succeeds: it is then the
+* turn's only handle.
+* The branch moves before the final hard reset, so if that reset fails the
+* marker has landed and the turn is still in the working tree (kept ref
+* present); every other failure leaves the branch untouched.
+*/
+const keepTurn = (refPrefix, message) => {
+	const keptRef = `${shellQuote(`${refPrefix}/`)}"$gtd_kept"`;
+	return [
+		`git add -A || exit 1`,
+		`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_head=$(git rev-parse --verify HEAD) || exit 1`,
+		`gtd_tree=$(git write-tree) || exit 1`,
+		`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`,
+		`  git reset -q && git update-ref -d ${keptRef}`,
+		`  exit 1`,
+		`fi`,
+		`git reset --hard HEAD`
+	].join("\n");
+};
 const updateRef = (ref, hash) => `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`;
 /** `git update-ref -d <ref>` — idempotent: deleting a missing ref is already a no-op in real git. */
 const deleteRef = (ref) => `git update-ref -d ${shellQuote(ref)}`;
@@ -9255,6 +9378,7 @@ const renderGitWrite = (write) => {
 	switch (write.kind) {
 		case "commitAll": return commitAll(write.message);
 		case "updateRef": return updateRef(write.ref, write.target);
+		case "keepTurn": return keepTurn(write.ref, write.message);
 	}
 };
 /**
@@ -11303,7 +11427,10 @@ const runCli = (argv, io) => {
 		io.exit(2);
 	});
 	const out = bufferedArtifactOut(io);
-	return runCommand$1(plan.command, plan.json, out).pipe(map$4(() => {
+	return flatMap$4(Host, ({ env }) => try_({
+		try: () => resolveFlags(env, io.flags),
+		catch: (e) => new GtdError(e.message)
+	})).pipe(flatMap$4(() => runCommand$1(plan.command, plan.json, out)), map$4(() => {
 		out.flush();
 		io.exit(0);
 	}), provide$2(io.layers(plan.verbose)), sandbox, catchAll$1((cause) => isInterruptedOnly(cause) ? failCause$4(cause) : report(io, plan.json.kind !== "off")(cause)));
@@ -11381,6 +11508,7 @@ var InMemRepo = class InMemRepo {
 		return this.head !== null;
 	}
 	resolveRef(ref) {
+		if (ref.endsWith("^{commit}")) return this.resolveRef(ref.slice(0, -9));
 		if (/^[0-9a-f]{40}$/.test(ref)) return this.commits.has(ref) ? ref : null;
 		const tildeMatch = /^(HEAD|[0-9a-f]{40})(~(\d+)|\^)?$/.exec(ref);
 		if (tildeMatch) {
@@ -11553,8 +11681,12 @@ var InMemRepo = class InMemRepo {
 	stageAll() {
 		this.index = new Map(this.worktree);
 	}
-	/** Commit whatever is currently staged (the index) verbatim, with no implicit staging first — mirrors `git commit --allow-empty -m <message>` after a soft reset. */
-	commitAsIs(message) {
+	/** 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;
+	/** Seeded: a pre-commit hook writing and staging this file. */
+	hookStages = void 0;
+	writeCommit(message) {
 		const tree = new Map(this.index);
 		const parent = this.head;
 		const hash = makeHash(message, parent, tree);
@@ -11569,27 +11701,59 @@ var InMemRepo = class InMemRepo {
 		this.head = hash;
 		this.branches.set(this.currentBranch, hash);
 	}
-	/** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
-	discardPending() {
-		this.index = new Map(this.worktree);
-		this.resetHard();
+	/**
+	* Twin of the emitted `git commit --allow-empty` if/case retry: a hook
+	* rejection printing "empty git commit" retries without hooks, any other
+	* rejection fails; a failing signer fails either attempt. Commits whatever is
+	* staged verbatim, like `git commit` after a soft reset.
+	*/
+	commitAsIs(message) {
+		if (this.hookRejection !== void 0 && !this.hookRejection.includes("empty git commit")) return this.hookRejection;
+		if (this.signingFails) return "error: gpg failed to sign the data";
+		if (this.hookStages !== void 0) {
+			this.worktree.set(this.hookStages.path, this.hookStages.content);
+			this.index.set(this.hookStages.path, this.hookStages.content);
+		}
+		this.writeCommit(message);
 	}
-	commitAllWithPrefix(prefix) {
+	/** 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");
 		this.index = new Map(this.worktree);
+		this.writeCommit(message);
+	}
+	/** Twin of `GitScript.keepTurn`: no hook runs; `signingFails` fails the marker. */
+	keepTurn(refPrefix, message) {
+		this.stageAll();
 		const tree = new Map(this.index);
-		const message = prefix;
 		const parent = this.head;
 		const hash = makeHash(message, parent, tree);
-		const commit = {
+		this.commits.set(hash, {
 			hash,
 			message,
 			files: new Map(tree),
 			parent,
 			seq: this.nextSeq++
-		};
-		this.commits.set(hash, commit);
-		this.head = hash;
-		this.branches.set(this.currentBranch, hash);
+		});
+		const ref = `${refPrefix}/${hash}`;
+		this.refs.set(ref, hash);
+		this.index = new Map(this.headTree());
+		if (this.signingFails) {
+			this.refs.delete(ref);
+			return "error: gpg failed to sign the data";
+		}
+		this.writeCommit(`${message}\nGtd-Kept: ${hash}`);
+		this.index = new Map(tree);
+		this.resetHard();
+	}
+	/** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
+	discardPending() {
+		this.index = new Map(this.worktree);
+		this.resetHard();
+	}
+	commitAllWithPrefix(prefix) {
+		this.index = new Map(this.worktree);
+		return this.commitAsIs(prefix);
 	}
 	static EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 	softResetTo(ref) {
@@ -11742,6 +11906,7 @@ const makeGitReaderOps = (repo, root) => ({
 		return content !== null ? succeed$6(content) : fail$5(/* @__PURE__ */ new Error(`path not found at ${ref}: ${path}`));
 	},
 	readRefOption: (ref) => {
+		if (/^[0-9a-f]{40}$/.test(ref)) return succeed$6(some(ref));
 		const hash = repo.resolveRef(ref);
 		return succeed$6(hash !== null ? some(hash) : none());
 	},
@@ -11764,10 +11929,13 @@ const makeGitReaderOps = (repo, root) => ({
 	subjectHistory: (pageSize, skip, head) => succeed$6(repo.subjectHistory(pageSize, skip, head)),
 	changedPaths: (base) => succeed$6(repo.changedPathsWorktree(base))
 });
+const failOn = (output) => {
+	if (output !== void 0) throw new Error(output);
+};
 const makeGitWriterOps = (repo) => ({
-	commitAllWithPrefix: (prefix) => tryCatch(() => repo.commitAllWithPrefix(prefix)),
+	commitAllWithPrefix: (prefix) => tryCatch(() => failOn(repo.commitAllWithPrefix(prefix))),
 	softResetTo: (ref) => tryCatch(() => repo.softResetTo(ref)),
-	commitAsIs: (message) => tryCatch(() => repo.commitAsIs(message)),
+	commitAsIs: (message) => tryCatch(() => failOn(repo.commitAsIs(message))),
 	discardPending: () => tryCatch(() => repo.discardPending()),
 	updateRef: (ref, hash) => tryCatch(() => repo.updateRef(ref, hash)),
 	deleteRef: (ref) => tryCatch(() => repo.deleteRef(ref)),
@@ -12270,25 +12438,51 @@ const conditionStatement = (block) => {
 	const end = block.indexOf(CONDITION_TERMINATOR, start);
 	return end === -1 ? block.slice(start) : block.slice(start, end);
 };
+/** `keepTurn`: an invalid ref name fails before anything moves, as `git update-ref` does. */
+const recognizeKeepTurn = (repo, block) => {
+	const [message, refDir] = extractQuotedTokens(block);
+	const ref = refDir?.slice(0, -1);
+	if (message === void 0 || ref === void 0 || keepTurn(ref, message) !== block) return;
+	if (refNameFault(ref) !== void 0) return {
+		kind: "failed",
+		error: `fatal: invalid ref format: ${ref}`,
+		status: 128
+	};
+	const failure = repo.keepTurn(ref, message);
+	return failure === void 0 ? { kind: "applied" } : {
+		kind: "failed",
+		error: failure,
+		status: 1
+	};
+};
 const recognizeGitBuilders = (repo, block) => {
 	if (block === discardPending()) {
 		repo.discardPending();
 		return { kind: "applied" };
 	}
 	const conditionLine = conditionStatement(block);
+	if (block.startsWith("git add -A || exit 1\ngtd_sign_cfg=")) return recognizeKeepTurn(repo, block);
 	if (block.startsWith("git add -A || exit 1\n")) {
 		const [message] = extractQuotedTokens(conditionLine);
 		if (message !== void 0 && commitAll(message) === block) {
-			repo.commitAllWithPrefix(message);
-			return { kind: "applied" };
+			const failure = repo.commitAllWithPrefix(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) {
-			repo.commitAsIs(message);
-			return { kind: "applied" };
+			const failure = repo.commitAsIs(message);
+			return failure === void 0 ? { kind: "applied" } : {
+				kind: "failed",
+				error: failure,
+				status: 1
+			};
 		}
 		return;
 	}
@@ -12825,7 +13019,7 @@ const testRepo = (options) => {
 	const id = `module-${++registered}`;
 	repo.writeFile("gtd.config.ts", typeof workflow === "string" ? workflow : moduleSource(id, workflow));
 	for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content);
-	repo.commitAllWithPrefix("chore: initial commit");
+	repo.seedCommit("chore: initial commit");
 	const gtd = async (...args) => {
 		const { io, result } = makeCapturingCliIo(repo, env);
 		if (typeof workflow !== "string") registry().set(id, workflow);
@@ -12893,7 +13087,7 @@ const testRepo = (options) => {
 		read: (path) => repo.readFile(path),
 		write: (path, content) => repo.writeFile(path, content),
 		remove: (path) => repo.deleteFile(path),
-		commit: (message) => repo.commitAllWithPrefix(message),
+		commit: (message) => repo.seedCommit(message),
 		show: (ref, path) => repo.fileAtRef(ref, path) ?? void 0,
 		runScript: (script) => {
 			const flow = applyFlowScript(repo, /* @__PURE__ */ new Map(), script);
@@ -12933,6 +13127,14 @@ const testRepo = (options) => {
 };
 //#endregion
 //#region src/testkit/GitTiers.ts
+const writeRejectingHook = (hooksDir, output) => {
+	mkdirSync(hooksDir, { recursive: true });
+	writeFileSync(join(hooksDir, "pre-commit"), `#!/bin/sh\ncat >&2 <<'GTD_HOOK_EOF'\n${output}\nGTD_HOOK_EOF\nexit 1\n`, { mode: 493 });
+};
+const writeStagingHook = (hooksDir, path, content) => {
+	mkdirSync(hooksDir, { recursive: true });
+	writeFileSync(join(hooksDir, "pre-commit"), `#!/bin/sh\nprintf '%s' ${shellQuote(content)} > ${shellQuote(path)} && git add ${shellQuote(path)}\nexit 0\n`, { mode: 493 });
+};
 /** No-op — these tests assert on git/config behavior, not narration. */
 const noopNarratorLayer = Narrator.layer(() => {}, false);
 const gitExecIn = (dir, ...args) => execSync(`git ${args.join(" ")}`, {
@@ -12982,7 +13184,6 @@ const makeLiveTier = (initialCommit = true) => {
 		root,
 		capabilities: {
 			onDiskContent: true,
-			commitHooks: true,
 			linkedWorktrees: true,
 			directoryChainConfig: true,
 			remotes: true
@@ -13010,7 +13211,22 @@ const makeLiveTier = (initialCommit = true) => {
 			},
 			stageAll: () => gitExec("add", "-A"),
 			updateRef: (ref, hash) => gitExec("update-ref", ref, hash),
-			mixedReset: (ref) => gitExec("reset", "--mixed", ref)
+			mixedReset: (ref) => gitExec("reset", "--mixed", ref),
+			rejectingHook: (output) => {
+				const hooks = join(root, ".git/hooks");
+				gitExec("config", "core.hooksPath", hooks);
+				writeRejectingHook(hooks, output);
+			},
+			stagingHook: (path, content) => {
+				const hooks = join(root, ".git/hooks");
+				gitExec("config", "core.hooksPath", hooks);
+				writeStagingHook(hooks, path, content);
+			},
+			failingSigner: () => {
+				gitExec("config", "commit.gpgsign", "true");
+				gitExec("config", "gpg.format", "openpgp");
+				gitExec("config", "gpg.program", "false");
+			}
 		},
 		observe: {
 			resolveRef: (ref) => gitExec("rev-parse", ref),
@@ -13076,7 +13292,7 @@ const makeInMemTier = (initialCommit = true) => {
 	const repo = new InMemRepo();
 	if (initialCommit) {
 		repo.writeFile("readme.txt", "hello");
-		repo.commitAllWithPrefix("init: first commit");
+		repo.seedCommit("init: first commit");
 	}
 	const gitLayer = gitTestLayer(repo, IN_MEM_ROOT);
 	const provide = (eff) => runPromise(eff.pipe(provide$2(gitLayer), provide$2(noopNarratorLayer)));
@@ -13086,7 +13302,6 @@ const makeInMemTier = (initialCommit = true) => {
 		root: IN_MEM_ROOT,
 		capabilities: {
 			onDiskContent: false,
-			commitHooks: false,
 			linkedWorktrees: false,
 			directoryChainConfig: true,
 			remotes: false
@@ -13097,17 +13312,29 @@ const makeInMemTier = (initialCommit = true) => {
 		seed: {
 			commit: (message, files = { "file.txt": message }) => {
 				for (const [path, content] of Object.entries(files)) repo.writeFile(path, content);
-				repo.commitAllWithPrefix(message);
+				repo.seedCommit(message);
 			},
 			writeFile: (path, content) => repo.writeFile(path, content),
 			deleteFile: (path) => repo.deleteFile(path),
 			commitDeletion: (path, message) => {
 				repo.deleteFile(path);
-				repo.commitAllWithPrefix(message);
+				repo.seedCommit(message);
 			},
 			stageAll: () => repo.stageAll(),
 			updateRef: (ref, hash) => repo.updateRef(ref, hash),
-			mixedReset: (ref) => repo.mixedResetTo(ref)
+			mixedReset: (ref) => repo.mixedResetTo(ref),
+			rejectingHook: (output) => {
+				repo.hookRejection = output;
+			},
+			stagingHook: (path, content) => {
+				repo.hookStages = {
+					path,
+					content
+				};
+			},
+			failingSigner: () => {
+				repo.signingFails = true;
+			}
 		},
 		observe: {
 			resolveRef: (ref) => {
@@ -13438,16 +13665,6 @@ const runGitServiceContract = (makeTier) => {
 			const history = await runGit(t, (g) => g.commitHistory());
 			expect(history[history.length - 1]?.message).toBe("gtd: grilled");
 		});
-		it.skipIf(!capabilities.commitHooks)("retries with --no-verify when a hook blocks the empty commit", async () => {
-			const hookPath = join(t.root, ".git/hooks/pre-commit");
-			writeFileSync(hookPath, `#!/bin/sh\necho "lint-staged prevented an empty git commit." >&2\nexit 1\n`);
-			execSync(`chmod +x "${hookPath}"`);
-			const headBefore = t.observe.resolveRef("HEAD");
-			await runGit(t, (g) => g.commitAllWithPrefix("gtd: grilled"));
-			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
-			const history = await runGit(t, (g) => g.commitHistory());
-			expect(history[history.length - 1]?.message).toBe("gtd: grilled");
-		});
 	});
 	describe("commitAsIs", () => {
 		it("commits exactly what's staged, ignoring later worktree writes (the squash mechanic)", async () => {
@@ -13466,6 +13683,29 @@ const runGitServiceContract = (makeTier) => {
 			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
 		});
 	});
+	describe.each([["commitAllWithPrefix", (g) => g.commitAllWithPrefix("gtd: building")], ["commitAsIs", (g) => g.commitAsIs("gtd: building")]])("%s seeded commit failures", (_name, commit) => {
+		it("retries with --no-verify when a hook blocks the empty commit", async () => {
+			t.seed.rejectingHook("lint-staged prevented an empty git commit.");
+			const headBefore = t.observe.resolveRef("HEAD");
+			await runGit(t, commit);
+			expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore);
+			const history = await runGit(t, (g) => g.commitHistory());
+			expect(history[history.length - 1]?.message).toBe("gtd: building");
+		});
+		it("fails on a hook rejection that is not the empty-commit one, leaving HEAD unchanged", async () => {
+			t.seed.rejectingHook("lint error");
+			const headBefore = t.observe.resolveRef("HEAD");
+			expect(isFailure(await runGitExit(t, commit))).toBe(true);
+			expect(t.observe.resolveRef("HEAD")).toBe(headBefore);
+		});
+		it("fails both attempts when the signer cannot write, leaving HEAD unchanged", async () => {
+			t.seed.rejectingHook("rejected: empty git commit");
+			t.seed.failingSigner();
+			const headBefore = t.observe.resolveRef("HEAD");
+			expect(isFailure(await runGitExit(t, commit))).toBe(true);
+			expect(t.observe.resolveRef("HEAD")).toBe(headBefore);
+		});
+	});
 	describe("softResetTo", () => {
 		it("moves HEAD back but keeps worktree changes from second commit", async () => {
 			const firstHash = t.observe.resolveRef("HEAD");
@@ -13513,6 +13753,20 @@ const runGitServiceContract = (makeTier) => {
 		it("readRefOption is None for a ref that doesn't exist — never a failure", async () => {
 			expect((await runGit(t, (g) => g.readRefOption("refs/gtd/nonexistent")))._tag).toBe("None");
 		});
+		it("readRefOption of <hash>^{commit} is Some for an existing commit", async () => {
+			const head = t.observe.resolveRef("HEAD");
+			const resolved = await runGit(t, (g) => g.readRefOption(`${head}^{commit}`));
+			expect(resolved._tag).toBe("Some");
+			if (resolved._tag === "Some") expect(resolved.value).toBe(head);
+		});
+		it("readRefOption of <hash>^{commit} is None for a 40-hex hash with no object", async () => {
+			const missing = "0123456789abcdef0123456789abcdef01234567";
+			expect((await runGit(t, (g) => g.readRefOption(`${missing}^{commit}`)))._tag).toBe("None");
+		});
+		it("readRefOption of a bare 40-hex hash with no object is Some", async () => {
+			const missing = "0123456789abcdef0123456789abcdef01234567";
+			expect((await runGit(t, (g) => g.readRefOption(missing)))._tag).toBe("Some");
+		});
 		it("deleteRef removes a ref idempotently (deleting twice is a no-op)", async () => {
 			const head = t.observe.resolveRef("HEAD");
 			await runGit(t, (g) => g.updateRef("refs/gtd/marker", head));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "25.0.0",
+  "version": "26.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -69,6 +69,7 @@
     "src/cli/",
     "src/edge/",
     "src/emit/",
+    "src/flags/",
     "src/install/",
     "src/platform/",
     "src/replay/",