@pmelab/gtd 62.0.0 → 63.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "62.0.0",
+  "version": "63.0.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

@@ -624,10 +624,10 @@ install for any of these but the testkit's: gtd resolves a `gtd.config.ts`'s
 `@pmelab/gtd/*` imports to its own copy.
 
 The `gtd` bin's commands — `next`, `land`, `start`, `abandon`, `restore`,
-`validate`, `check`, `uncheck`, `guide`, `bundle`, `summary`, `base`, `version`,
-`help`, `history list`, `history show`, `history metrics`, `history judges`,
-`history fetch`, `strays`, the tools `ui`, `lsp`, `judge` (`judge answer`,
-`judge run`) — are listed in the
+`repin`, `validate`, `check`, `uncheck`, `guide`, `bundle`, `summary`, `base`,
+`version`, `help`, `history list`, `history show`, `history metrics`,
+`history judges`, `history fetch`, `strays`, the tools `ui`, `lsp`, `judge`
+(`judge answer`, `judge run`) — are listed in the
 [CLI reference](https://github.com/pmelab/gtd/blob/main/docs/cli.md). Every
 command that prints a script takes `--json=script`, and `--` ends the options.
 
@@ -641,14 +641,20 @@ writing `gtd bundle`'s output to `.gtd/process.gtdpin`, and its last, once the
 flow has ended, an unpin beat removing it — the commit that closes the process.
 Both are ordinary `script` beats a driver runs unattended; see
 [Pin and unpin beats](https://github.com/pmelab/gtd/blob/main/docs/driver.md#pin-and-unpin-beats).
-Histories with pin commits are history format 2, which an older gtd refuses.
+Histories with pin commits are history format 2 or later, which an older gtd
+refuses.
 
 While a process is pinned, the `gtd` on your `PATH` hands every command over to
 the pin, so editing the workflow or upgrading gtd mid-process changes nothing;
 gtd notes on stderr when the live config differs from the pinned one. `ui`,
-`lsp`, `guide`, `bundle`, `help`, `version` and the `history` commands always
-run live, and `gtd --live <command>` runs the live engine for any other, at the
-risk of misreading the process. A pin in a format your gtd does not know is
+`lsp`, `guide`, `bundle`, `repin`, `help`, `version` and the `history` commands
+always run live, and `gtd --live <command>` runs the live engine for any other,
+at the risk of misreading the process. To fix a workflow mid-process, edit it
+and run `gtd repin`: its script commits a fresh pin from the live engine and
+config, and the process continues on it. Where the edited workflow no longer
+replays the process, the repin continues from the divergence: the commits it
+cannot replay stay as files, and the process rests at the step the edited
+workflow reached (history format 3). A pin in a format your gtd does not know is
 refused: upgrade gtd. See
 [Pinned processes](https://github.com/pmelab/gtd/blob/main/docs/cli.md#pinned-processes).
 

package/dist/chunks/{testkit-XQeYCNMn.mjs → testkit-DwypA7cH.mjs}

@@ -22810,9 +22810,9 @@ const withoutPath = (tree, hidden) => {
 const OLDEST_READABLE_FORMAT = 1;
 const short$1 = (hash) => hash.slice(0, 7);
 const formatFault = (commits) => {
-	const foreign = commits.find((c) => c.format < OLDEST_READABLE_FORMAT || c.format > 2);
+	const foreign = commits.find((c) => c.format < OLDEST_READABLE_FORMAT || c.format > 3);
 	if (foreign === void 0) return void 0;
-	return `gtd: commit ${short$1(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads formats ${OLDEST_READABLE_FORMAT} to 2 — run a gtd release that reads format ${foreign.format} to continue this process`;
+	return `gtd: commit ${short$1(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads formats ${OLDEST_READABLE_FORMAT} to 3 — run a gtd release that reads format ${foreign.format} to continue this process`;
 };
 //#endregion
 //#region src/replay/Trailers.ts
@@ -22943,6 +22943,9 @@ const TRAILER_READERS = {
 	"Gtd-Pin": (value, into) => {
 		if (value === "add" || value === "remove") into.pin ??= value;
 	},
+	"Gtd-Anchor": (value, into) => {
+		if (HASH_RE.test(value)) into.anchor ??= value;
+	},
 	"Gtd-Format": (value, into) => {
 		if (FORMAT_RE.test(value)) into.format ??= Number(value);
 	},
@@ -22966,6 +22969,7 @@ const parseCommitMessage = (message) => {
 		kept: void 0,
 		approved: void 0,
 		pin: void 0,
+		anchor: void 0,
 		judge: [],
 		marks: [],
 		vars: {},
@@ -22995,9 +22999,10 @@ const formatCommitMessage = (spec) => {
 		...(spec.marks ?? []).map((m) => `Gtd-Mark: ${m.name}=${m.value}`),
 		...trailer("Approved", spec.approved && encodeApproval(spec.approved)),
 		...trailer("Pin", spec.pin),
+		...trailer("Anchor", spec.anchor),
 		...trailer("Branch", spec.branch),
 		...trailer("Version", spec.version),
-		`Gtd-Format: 2`
+		`Gtd-Format: 3`
 	];
 	return `${formatSubject(spec.actor, spec.to, spec.from)}\n\n${lines.join("\n")}`;
 };
@@ -23091,6 +23096,27 @@ const budgeted = (evidence, budgetBytes) => {
 };
 const sameSkills = (a, b) => (a?.length ?? 0) === (b?.length ?? 0) && (a ?? []).every((skill, i) => skill === b?.[i]);
 const samePersona = (a, b) => a.model === b.model && a.system === b.system && sameSkills(a.skills, b.skills) && sameAccess(a.access, b.access);
+const anchorOf = (parsed) => parsed.pin === "add" ? parsed.anchor : void 0;
+const isAnchor = (commit) => anchorOf(commit.parsed) !== void 0;
+/**
+* The commits every anchor sets aside — those between the commit it names and
+* itself — or a fault for an anchor naming no commit still read.
+*/
+const setAsideBy = (base, all) => {
+	const setAside = /* @__PURE__ */ new Set();
+	if (all.every((c) => anchorOf(c.parsed) === void 0)) return { setAside };
+	let kept = [];
+	for (const commit of all) {
+		const anchor = anchorOf(commit.parsed);
+		if (anchor !== void 0) {
+			const at = anchor === base ? -1 : kept.indexOf(anchor);
+			if (anchor !== base && at === -1) return { fault: `gtd: commit ${short(commit.hash)} anchors the process at ${short(anchor)}, which is no commit replay reads in this episode` };
+			for (const hash of kept.splice(at + 1)) setAside.add(hash);
+		}
+		kept.push(commit.hash);
+	}
+	return { setAside };
+};
 /**
 * Replay one episode: run its entry flow, answering each step from the
 * episode's commits in order, until a step has no commit left — the rest.
@@ -23164,19 +23190,39 @@ const withoutPin = (input) => {
 };
 const replay = async (raw) => {
 	const input = withoutPin(raw);
-	const commits = input.episode.commits.map((c) => ({
+	const all = input.episode.commits.map((c) => ({
 		...c,
 		parsed: parseCommitMessage(c.message)
 	}));
+	const resolved = setAsideBy(input.episode.base.hash, all);
+	if ("fault" in resolved) return {
+		kind: "failed",
+		message: resolved.fault
+	};
+	const setAside = resolved.setAside;
+	const commits = all.filter((c) => !setAside.has(c.hash));
+	const pinned = (raw.episode.commits.at(-1)?.tree ?? raw.episode.base.tree).paths().includes(PIN_PATH);
 	const treeAt = (hash) => hash === input.episode.base.hash ? input.episode.base.tree : commits.find((c) => c.hash === hash)?.tree ?? (hash === input.start ? input.startTree : void 0);
 	let cursor = 0;
 	let pendingUsed = false;
 	let position = input.episode.base;
 	const skipPins = () => {
-		while (cursor < commits.length && commits[cursor].parsed.pin !== void 0) cursor++;
+		while (cursor < commits.length && commits[cursor].parsed.pin !== void 0) {
+			const commit = commits[cursor];
+			cursor++;
+			if (!isAnchor(commit)) continue;
+			position = commit;
+			const to = commit.parsed.parsed?.to;
+			expectedNext = to === void 0 || to === UNPIN_STATE ? void 0 : {
+				name: to,
+				hash: commit.hash
+			};
+			anchorPending = expectedNext !== void 0;
+		}
 	};
 	let previousPosition = input.episode.base;
 	let expectedNext;
+	let anchorPending = false;
 	const occurrences = /* @__PURE__ */ new Map();
 	const personas = /* @__PURE__ */ new Map();
 	const scopes = [];
@@ -23319,14 +23365,18 @@ const replay = async (raw) => {
 		}
 		return samePersona(seen, identity) ? void 0 : `gtd: "${step.name}" runs with a different model, system prompt, skills or file access than an earlier agent step in its conversation in memory scope "${step.memoryScope || "root"}" — a conversation has one identity`;
 	};
-	const DIVERGED = "the workflow changed under this process; run `gtd abandon` to start over";
+	const DIVERGED = pinned ? "the workflow changed under this process; run `gtd repin` to continue under it from there, or `gtd abandon` to start over" : "the workflow changed under this process; run `gtd abandon` to start over";
+	const diverged = (message, reached) => ({
+		kind: "divergence",
+		message: `${message} — ${DIVERGED}`,
+		at: position.hash,
+		reached: reached?.name
+	});
 	const blockerAt = (step) => {
 		const expected = expectedNext;
 		expectedNext = void 0;
-		if (expected !== void 0 && expected.name !== step.name) return {
-			kind: "divergence",
-			message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`
-		};
+		anchorPending = false;
+		if (expected !== void 0 && expected.name !== step.name) return diverged(`gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}"`, step);
 		const error = unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step);
 		return error === void 0 ? void 0 : {
 			kind: "failed",
@@ -23337,33 +23387,30 @@ const replay = async (raw) => {
 		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}`
-		};
+		return diverged(`gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it`, step);
 	};
 	const consumeCommit = (step, commit) => {
 		const recorded = commit.parsed.step;
 		const expected = formatStepId(step.id);
 		if (recorded === void 0 || formatStepId(recorded) !== expected) {
 			const what = recorded === void 0 ? "records no step" : `records step "${formatStepId(recorded)}"`;
-			return finish({
-				kind: "divergence",
-				message: `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}" — ${DIVERGED}`
-			});
+			return finish(diverged(`gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}"`, step));
 		}
 		const unapproved = missingApproval(step, commit, expected);
 		if (unapproved !== void 0) return finish(unapproved);
 		cursor++;
 		advance(commit);
+		expectNextOf(commit);
 		skipPins();
 		noteKept(step, commit);
+		return replyFor(step.request, commit.parsed.judge);
+	};
+	const expectNextOf = (commit) => {
 		const to = commit.parsed.parsed?.to;
 		if (to !== void 0 && to !== UNPIN_STATE) expectedNext = {
 			name: to,
 			hash: commit.hash
 		};
-		return replyFor(step.request, commit.parsed.judge);
 	};
 	const noteKept = (step, commit) => {
 		if (commit.parsed.kept === void 0) return;
@@ -23435,10 +23482,8 @@ const replay = async (raw) => {
 	};
 	const endOfFlow = (via) => {
 		skipPins();
-		return cursor < commits.length ? {
-			kind: "divergence",
-			message: `gtd: the flow ended, but commit ${short(commits[cursor].hash)} continues the episode — ${DIVERGED}`
-		} : {
+		if (anchorPending && cursor === commits.length) return diverged(`gtd: the flow ended, but commit ${short(expectedNext.hash)} continues the process at "${expectedNext.name}"`, void 0);
+		return cursor < commits.length ? diverged(`gtd: the flow ended, but commit ${short(commits[cursor].hash)} continues the episode`, void 0) : {
 			kind: "ended",
 			via,
 			trace,
@@ -23448,6 +23493,7 @@ const replay = async (raw) => {
 	};
 	const changesSince = (hash) => {
 		const tree = treeAt(hash);
+		if (setAside.has(hash)) throw new Error(`gtd: changesSince(${hash}): a repin set ${short(hash)} aside — pass a hash this run read from head() or start()`);
 		if (tree === void 0) throw new Error(`gtd: changesSince(${hash}): ${hash} is not the episode base or one of its commits — pass a hash this run read from head() or start(), not one captured earlier, read from state, or from another branch`);
 		return changesBetween(tree, position.tree);
 	};
@@ -24610,6 +24656,12 @@ const pinScript = (path) => {
 	const slash = path.lastIndexOf("/");
 	return `${slash === -1 ? "" : `mkdir -p ${shellQuote(path.slice(0, slash))}\n`}gtd bundle >${p} || { rm -f -- ${p}; exit 1; }`;
 };
+/** `gtd repin`'s pin write: a failed `gtd bundle` leaves the committed pin in place. */
+const repinScript = (path) => {
+	const p = shellQuote(path);
+	const next = shellQuote(`${path}.new`);
+	return `gtd bundle >${next} || { rm -f -- ${next}; exit 1; }\nmv -f -- ${next} ${p}`;
+};
 /** An unpin beat's script, and `gtd abandon`'s removal of the pin. */
 const unpinScript = (path) => `rm -f -- ${shellQuote(path)}`;
 /**
@@ -24850,6 +24902,12 @@ const FMT_ABANDONED = "abandoned the process resting at \"%s\" — HEAD is back
 const FMT_RESTORED = "restored the retained history — HEAD is back at %s (\"%s\"), resting at \"%s\". Resume with the loop, or `git reset` to any earlier turn to restart from there.\n";
 /** `no gtd process is underway (resting at "<initial>") — nothing to abandon` — `gtd abandon`'s no-op plain-text line. */
 const abandonNoopText = (initial) => renderFormat(FMT_ABANDON_NOOP, initial);
+/** A landed self-loop/target-change transition. */
+const transitionOutcome = (from, to) => printfLine("%s %s → %s\n", [
+	"'->'",
+	shellQuote(from),
+	shellQuote(to)
+]);
 /** One already-rendered plain line. */
 const noteOutcome = (text) => printfLine("%s\n", [shellQuote(text)]);
 /**
@@ -25366,11 +25424,21 @@ const approvalEntryOf = (hash, message) => message.approved === void 0 ? [] : [{
 	email: message.approved.email,
 	commit: hash
 }];
+const setAsideIn = (history, location) => {
+	const anchored = setAsideBy(hashAt(history, location.baseIndex) ?? EMPTY_TREE$1, history.slice(location.baseIndex + 1).map((c) => ({
+		hash: c.hash,
+		parsed: parseCommitMessage(c.message)
+	})));
+	return "setAside" in anchored ? anchored.setAside : /* @__PURE__ */ new Set();
+};
 const buildRun = (history, location, closingHash) => {
 	const allProcessCommits = history.slice(location.processStart);
 	const allParsed = allProcessCommits.map((c) => parseCommitMessage(c.message));
 	const processCommits = allProcessCommits.filter((_, i) => allParsed[i].pin !== "add");
 	const parsed = allParsed.filter((m) => m.pin !== "add");
+	const setAside = setAsideIn(history, location);
+	const answering = parsed.filter((_, i) => !setAside.has(processCommits[i].hash));
+	const answeringCommits = processCommits.filter((c) => !setAside.has(c.hash));
 	const first = parsed[0];
 	const startParentHash = hashAt(history, location.processStart - 1) ?? EMPTY_TREE$1;
 	const head = history[history.length - 1];
@@ -25382,10 +25450,10 @@ const buildRun = (history, location, closingHash) => {
 		diffBase: first?.reviewBase ?? startParentHash,
 		trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i])),
 		costEntries: parsed.flatMap((m, i) => costEntriesOf(processCommits[i].hash, m)),
-		judgeVerdicts: parsed.flatMap((m) => m.judge),
+		judgeVerdicts: answering.flatMap((m) => m.judge),
 		pinCommitted: allParsed.some((m) => m.pin === "add"),
-		marks: parsed.flatMap((m) => m.marks),
-		approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i])),
+		marks: answering.flatMap((m) => m.marks),
+		approvals: answeringCommits.flatMap((c, i) => approvalEntryOf(c.hash, answering[i])),
 		pinnedVars: { ...first?.vars },
 		headTurn: headTurnOf(head),
 		closingHash,
@@ -25814,6 +25882,43 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 	};
 });
 const currentRest = restAt(void 0);
+/**
+* Where `gtd repin` anchors a pinned process the live workflow no longer
+* replays: the commit replay last stood on, and the step the live workflow
+* reaches from there on HEAD's tree — the unpin when the flow ends instead.
+* `undefined` when there is nothing to anchor: no divergence, or no pin.
+*/
+const repinAnchor = gen(function* () {
+	const git = yield* GitService;
+	const config = yield* (yield* ConfigService).load;
+	const workspace = yield* Workspace;
+	const run = yield* computeProcessRun(git, config.workflow);
+	const { def, setup } = yield* setupFor(config, run, workspace, yield* Host);
+	const diverged = yield* promise(() => replayFor(setup));
+	if (diverged.kind !== "divergence" || !headHasPin(workspace, run)) return void 0;
+	const trial = {
+		hash: "",
+		message: formatCommitMessage({
+			actor: "check",
+			from: PIN_STATES.add,
+			to: PIN_STATES.add,
+			pin: "add",
+			anchor: diverged.at
+		}),
+		tree: setup.episode.at(-1)?.tree ?? setup.base.tree
+	};
+	const outcome = yield* promise(() => replayFor({
+		...setup,
+		episode: [...setup.episode, trial]
+	}));
+	if (outcome.kind !== "divergence") return yield* fail$4(replayError(outcome) ?? /* @__PURE__ */ new Error("gtd repin: replay found no step"));
+	const to = outcome.reached ?? PIN_STATES.remove;
+	if (run.workflow === void 0 && to === def.initial) return yield* fail$4(/* @__PURE__ */ new Error(`gtd repin: the live workflow continues this process at "${to}", the default workflow's first step, where a finished process waits — run \`gtd abandon\` to start over`));
+	return {
+		at: diverged.at,
+		to
+	};
+});
 /** The step the process rests at and the trace that reached it — at an unpin, the flow's last step. */
 const restingOn = (outcome, pin) => {
 	if (outcome.kind === "rest") return {
@@ -27327,6 +27432,44 @@ const runRestoreCommand = (json, out) => gen(function* () {
 	]).required;
 	yield* writeScript(json, out, combinedScript(required, ""));
 });
+/** The step an ordinary repin rests at — the one the process rests at now. */
+const repinTarget = gen(function* () {
+	const rest = yield* currentRest;
+	const refusal = rest.pin === "add" ? "the next beat pins the process already — run it (`gtd next --json=content`), then land" : rest.pin === "remove" ? "the flow has ended — its unpin beat is next, so there is nothing to repin" : noProcessUnderway(rest) ? "no gtd process is underway — nothing to repin" : void 0;
+	if (refusal !== void 0) return yield* fail$4(/* @__PURE__ */ new Error(`gtd repin: ${refusal}`));
+	return rest.step.name;
+});
+/**
+* `gtd repin`: the pin beat's script and landing, on demand. It runs live: a
+* pinned process the live workflow no longer replays is anchored where it
+* diverged, and any other failure to read the rest refuses before any pin is
+* written.
+*/
+const runRepinCommand = (json, out) => gen(function* () {
+	const anchor = yield* repinAnchor;
+	const to = anchor?.to ?? (yield* repinTarget);
+	const message = formatCommitMessage({
+		actor: "check",
+		from: PIN_STATES.add,
+		to,
+		pin: "add",
+		...anchor !== void 0 ? { anchor: anchor.at } : {}
+	});
+	yield* writeScript(json, out, combinedScript(emitScripts([
+		{
+			kind: "gitWrite",
+			command: repinScript(PIN_PATH)
+		},
+		{
+			kind: "gitWrite",
+			command: commitPath(PIN_PATH, message)
+		},
+		{
+			kind: "outcome",
+			command: transitionOutcome(PIN_STATES.add, to)
+		}
+	]).required, ""));
+});
 /**
 * The mode's own validate command for `file`: a declared `validate:` command
 * verbatim; a `"builtin"` validator or no mode at all names the leaf
@@ -27594,6 +27737,7 @@ const dispatchVoidCommand = (command, json, out) => {
 		case "start": return runStartCommand(command, json, out);
 		case "abandon": return runAbandonCommand(json, out);
 		case "restore": return runRestoreCommand(json, out);
+		case "repin": return runRepinCommand(json, out);
 		case "next": return runNextCommand(json, out);
 		case "validate": return runValidateCommand(json, out);
 		case "check":
@@ -27722,6 +27866,7 @@ const SCRIPT_KINDS = /* @__PURE__ */ new Set([
 	"start",
 	"abandon",
 	"restore",
+	"repin",
 	"validate",
 	"historyFetch"
 ]);
@@ -27989,6 +28134,16 @@ With no <name>, list every workflow and door it can start. An unknown <name>, th
 		summary: "Bring back the last abandoned process",
 		details: `Bring back the process the last \`gtd abandon\` stopped: the printed script resets HEAD to that process's last commit. Refuses on a dirty working tree, when nothing was abandoned, or when commits made since would be lost.`
 	},
+	{
+		token: "repin",
+		kind: "repin",
+		arity: "none",
+		group: "Start and stop",
+		summary: "Pin the process to the live gtd and workflow",
+		details: `Switch the process underway to the live engine and workflow, the way out when the workflow needs a fix mid-process: the printed script runs the pin beat again, writing \`gtd bundle\`'s output to .gtd/process.gtdpin and committing that file alone. Always runs on the gtd on PATH, never on the pin. When the live workflow no longer replays the process, the commit continues from the divergence: a Gtd-Anchor trailer names the last commit it replays, the later commits stay as files only, and the process rests at the step the live workflow reached there. Refuses when no process is underway, when the next beat is a pin or unpin beat already, when an unpinned process diverges, or when the live workflow would continue at the default workflow's first step.
+
+  s=$(gtd repin --json=script) && sh -c "$s"`
+	},
 	{
 		token: "summary",
 		kind: "summary",
@@ -29892,9 +30047,9 @@ const recognizeGitBuilders = (repo, block) => {
 };
 /** What the in-memory `gtd bundle` prints: a pin header, and no engine behind it. */
 const IN_MEMORY_PIN = "gtdpin 1 gtd in-memory\n";
-/** A pin or unpin beat's script. */
+/** A pin or unpin beat's script, or `gtd repin`'s. */
 const recognizePinScripts = (repo, block) => {
-	if (block === pinScript(".gtd/process.gtdpin")) {
+	if (block === pinScript(".gtd/process.gtdpin") || block === repinScript(".gtd/process.gtdpin")) {
 		repo.writeFile(PIN_PATH, IN_MEMORY_PIN);
 		return { kind: "applied" };
 	}