@pmelab/gtd 25.0.0 → 26.1.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -28,6 +28,8 @@ Or run without installing (prefix every `gtd` below with `npx`) — see
 for the settings most projects tune. A process setting's value is committed to
 Git history; keep secrets in an environment setting (see
 [Settings](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#settings)).
+`GTD_FLAG_<NAME>` variables toggle experimental features — see
+[Feature flags](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#feature-flags).
 
 Also install all three skill sources the bundled workflow names in its prompts —
 none is optional. See
@@ -574,6 +576,11 @@ git config --add remote.origin.fetch 'refs/gtd/history/*:refs/gtd/history/*'
 The second line makes every plain `git fetch` include them. It has no leading
 `+`, so a conflicting local ref fails instead of being overwritten.
 
+A step declared with `keep: true` files its turn under `refs/gtd/kept/` instead
+of on the branch (see [Kept tips](docs/configuration.md#kept-tips)). Those refs
+are not process history: `gtd history` does not list them, and the
+`refs/gtd/history/*` refspecs above neither push nor fetch them.
+
 ## Entrypoints
 
 gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and

package/dist/flows.mjs

@@ -109,6 +109,19 @@ const changesSince = (hash, pattern) => {
 	const all = context.changesSince(hash);
 	return toChanges(pattern === void 0 ? all : all.filter((c) => context.matches(c.path, pattern)));
 };
+/**
+* The latest kept tip of step `name` (scoped from here, same as `agent()`) in
+* this episode, or `undefined` when none.
+*/
+const kept = (name) => {
+	const context = ctx();
+	if (typeof context.kept !== "function") throw new Error("gtd: kept() needs a newer gtd — upgrade the gtd that runs it");
+	const tip = context.kept(name);
+	return tip === void 0 ? void 0 : {
+		hash: tip.hash,
+		changes: toChanges(tip.changes)
+	};
+};
 /** The commit the process stands on at this point of the flow. */
 const head = () => ctx().head();
 /** The process's diff base: the commit before it began, or the base `gtd --workflow` fixed. */
@@ -502,6 +515,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	installContext: () => installContext,
 	isFactoryWorkflow: () => isFactoryWorkflow,
 	judge: () => judge,
+	kept: () => kept,
 	moveScript: () => moveScript,
 	numeric: () => numeric,
 	openQuestions: () => openQuestions,
@@ -530,4 +544,4 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	wrote: () => wrote
 });
 //#endregion
-export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, sectionBodies, sections, showScript, skillsFor, start, flows_exports as t, threads, vars, wrote };
+export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, kept, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, sectionBodies, sections, showScript, skillsFor, start, flows_exports as t, threads, vars, wrote };

package/dist/gtd.bundle.mjs

@@ -20943,6 +20943,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
@@ -20957,6 +20959,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) => {
@@ -21695,6 +21717,19 @@ const changesSince = (hash, pattern) => {
 	const all = context.changesSince(hash);
 	return toChanges(pattern === void 0 ? all : all.filter((c) => context.matches(c.path, pattern)));
 };
+/**
+* The latest kept tip of step `name` (scoped from here, same as `agent()`) in
+* this episode, or `undefined` when none.
+*/
+const kept = (name) => {
+	const context = ctx();
+	if (typeof context.kept !== "function") throw new Error("gtd: kept() needs a newer gtd — upgrade the gtd that runs it");
+	const tip = context.kept(name);
+	return tip === void 0 ? void 0 : {
+		hash: tip.hash,
+		changes: toChanges(tip.changes)
+	};
+};
 /** The commit the process stands on at this point of the flow. */
 const head = () => ctx().head();
 /** The process's diff base: the commit before it began, or the base `gtd --workflow` fixed. */
@@ -22088,6 +22123,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	installContext: () => installContext,
 	isFactoryWorkflow: () => isFactoryWorkflow,
 	judge: () => judge,
+	kept: () => kept,
 	moveScript: () => moveScript,
 	numeric: () => numeric,
 	openQuestions: () => openQuestions,
@@ -37471,8 +37507,24 @@ var init_wire = __esmMin((() => {
 	init_Glob();
 }));
 //#endregion
-//#region src/replay/Tree.ts
+//#region src/replay/RefName.ts
 init_wire();
+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(),
 	read: (path) => Object.hasOwn(files, path) ? files[path] : void 0
@@ -37566,6 +37618,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);
@@ -37595,6 +37648,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);
 	},
@@ -37615,6 +37671,7 @@ const parseCommitMessage = (message) => {
 		reviewBase: void 0,
 		branch: void 0,
 		version: void 0,
+		kept: void 0,
 		judge: [],
 		vars: {},
 		config: {},
@@ -37729,7 +37786,8 @@ const KNOWN_OPTIONS = {
 		...STEERING_OPTIONS,
 		"model",
 		"system",
-		"allowEmpty"
+		"allowEmpty",
+		"keep"
 	]),
 	human: /* @__PURE__ */ new Set([
 		...STEERING_OPTIONS,
@@ -37761,6 +37819,7 @@ const replay = async (input) => {
 	const scopeCallIds = [];
 	let scopeCallCount = 0;
 	const trace = [];
+	const keptTips = /* @__PURE__ */ new Map();
 	let landed;
 	let outcome;
 	let signal;
@@ -37920,6 +37979,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,
@@ -37927,6 +37992,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];
@@ -37937,17 +38017,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();
@@ -38030,6 +38111,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,
@@ -38131,7 +38219,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;
@@ -38997,7 +39087,11 @@ const planStep = (snapshot, opts = {}) => {
 			...uncheckStep(snapshot),
 			{
 				kind: "gitWrite",
-				write: {
+				write: landing.keepTurn !== void 0 ? {
+					kind: "keepTurn",
+					ref: landing.keepTurn,
+					message
+				} : {
 					kind: "commitAll",
 					message
 				}
@@ -39477,6 +39571,7 @@ const promptDef = (common, request, skills, access) => ({
 	...optional$1("model", request.options.model),
 	...optional$1("system", request.options.system),
 	...optional$1("allowEmpty", request.options.allowEmpty),
+	...optional$1("keep", request.options.keep),
 	...optional$1("skills", skills),
 	...optional$1("access", access)
 });
@@ -39591,11 +39686,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,
@@ -39771,6 +39876,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",
@@ -39795,7 +39901,8 @@ const landingTo = (rest, to, branch) => {
 			} : {},
 			...finishes ? closingTrailers(branch) : {}
 		},
-		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {}
+		...finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {},
+		...keptTurn(rest)
 	};
 };
 /**
@@ -39932,7 +40039,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`
@@ -39942,6 +40049,36 @@ const commitAllowEmpty = (message) => {
 const commitAll = (message) => `git add -A || exit 1\n${commitAllowEmpty(message)}`;
 const mixedResetTo = (ref) => `git reset --mixed ${shellQuote$1(ref)}`;
 const hardResetTo = (ref) => `git reset --hard ${shellQuote$1(ref)}`;
+/**
+* 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$1(`${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$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`,
+		`  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$1(ref)} ${shellQuote$1(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$1(ref)}`;
@@ -39974,6 +40111,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);
 	}
 };
 /**
@@ -42051,7 +42189,10 @@ const runCli = (argv, io) => {
 		io.exit(2);
 	});
 	const out = bufferedArtifactOut(io);
-	return runCommand(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(plan.command, plan.json, out)), map$4(() => {
 		out.flush();
 		io.exit(0);
 	}), provide$1(io.layers(plan.verbose)), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json.kind !== "off")(cause)));