@pmelab/gtd 8.5.0 → 8.6.0

package/dist/gtd.bundle.mjs

@@ -191387,6 +191387,20 @@ const STEERING_FORMATS = /* @__PURE__ */ new Map([["qa", QA_FORMAT], ["review",
 const builtInModeNames = () => [...STEERING_FORMATS.keys()];
 /** The built-in `SteeringFormat` named `mode`, or `undefined` when `mode` names no built-in. */
 const steeringFormatFor = (mode) => STEERING_FORMATS.get(mode);
+/**
+* The literal (unrendered) Eta template a workflow compiler seeds as a
+* built-in mode's own `validate:` command — quoted so a file path containing
+* spaces survives `renderModeCommand`'s interpolation.
+*/
+const seededValidateCommand = (mode) => `gtd check ${mode} '<%= it.file %>'`;
+/**
+* True when `command` is EXACTLY `mode`'s own seeded template string — a
+* literal comparison against the declared template, never a rendered
+* command, so recognition doesn't depend on which file the mode is applied
+* to. Lets a later mode resolver tell gtd's own seeding apart from a user's
+* hand-written override of the same mode.
+*/
+const isSeededValidateCommand = (mode, command) => command === seededValidateCommand(mode);
 //#endregion
 //#region src/PatternConfig.ts
 /**
@@ -191460,11 +191474,13 @@ const steeringFormatFor = (mode) => STEERING_FORMATS.get(mode);
 * `ConfigService` compiles through this module's `compileModesMap` and hands
 * back in as `rcModes`, merged per half by `mergeModes`. Underneath BOTH layers
 * this compiler seeds `src/SteeringFormats.ts`'s built-in registry names (`qa`/
-* `review`) as empty entries, so every compiled definition's `modes` map always
-* carries them and a workflow never has to declare them just to use gtd's own
-* validators — resolution of the merged map against the registry (whether a
-* declared `validate:` displaces a format's own parser) is the edge's job
-* (`src/SteeringMode.ts`), not this compiler's.
+* `review`) with that module's own `seededValidateCommand(name)` template as
+* their `validate:`, so every compiled definition's `modes` map always carries
+* a usable `validate:` command for them and a workflow never has to declare
+* them just to use gtd's own validators — a workflow (or `.gtdrc`) may still
+* override either half per name, and `src/SteeringFormats.ts`'s
+* `isSeededValidateCommand` lets the edge (`src/SteeringMode.ts`) tell gtd's
+* own seeding apart from a genuine user override.
 *
 * ## File references
 *
@@ -192105,7 +192121,7 @@ const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true, f
 	const unknownTopKeys = Object.keys(raw).filter((k) => !KNOWN_TOP_KEYS.has(k));
 	if (unknownTopKeys.length > 0) errors.push(`unknown top-level key(s) ${unknownTopKeys.join(", ")}`);
 	const vars = compileVarsMap(raw.vars, errors);
-	const seeded = Object.fromEntries(builtInModeNames().map((name) => [name, {}]));
+	const seeded = Object.fromEntries(builtInModeNames().map((name) => [name, { validate: seededValidateCommand(name) }]));
 	const modes = mergeModes(mergeModes(seeded, compileModesMap(raw.modes, errors)), rcModes);
 	validateMachinesShape(raw.machines, errors);
 	const flattened = flattenMachines(raw, errors);
@@ -192761,13 +192777,15 @@ 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}`),
 		changedPathsSince: (ref) => exec("git", "diff", "--name-status", ref, "HEAD").pipe(map$4(parseNameStatus)),
-		changedPaths: () => gen(function* () {
-			const nameStatusOut = yield* exec("git", "diff", "--name-status", "HEAD").pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
+		changedPaths: (base) => gen(function* () {
+			const nameStatusOut = yield* exec("git", "diff", "--name-status", base ?? "HEAD").pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
 			const trackedPaths = parseNameStatus(nameStatusOut);
-			const untracked = (yield* exec("git", "ls-files", "--others", "--exclude-standard", "-z")).split("\0").filter((s) => s.length > 0).map((path) => ({
+			const untrackedAll = (yield* exec("git", "ls-files", "--others", "--exclude-standard", "-z")).split("\0").filter((s) => s.length > 0).map((path) => ({
 				path,
 				status: "A"
 			}));
+			const atBase = base === void 0 ? /* @__PURE__ */ new Set() : new Set((yield* exec("git", "ls-tree", "-r", "--name-only", "-z", base)).split("\0").filter((s) => s.length > 0));
+			const untracked = untrackedAll.filter((entry) => !atBase.has(entry.path));
 			const seen = /* @__PURE__ */ new Set();
 			const all = [];
 			for (const entry of [...trackedPaths, ...untracked]) if (!seen.has(entry.path)) {
@@ -192780,8 +192798,8 @@ const makeGitImpl = (executor, root) => {
 		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(root, "git", "merge-base", "--is-ancestor", a, b).pipe(provide$2(succeed$2(CommandExecutor, executor)), map$4(() => true), catchAll(() => succeed$3(false))),
 		topLevel: () => exec("git", "rev-parse", "--show-toplevel").pipe(map$4((s) => s.trim())),
-		commitHistory: (base) => {
-			const range = base !== void 0 ? `${base}..HEAD` : void 0;
+		commitHistory: (base, head = "HEAD") => {
+			const range = base !== void 0 ? `${base}..${head}` : head !== "HEAD" ? head : void 0;
 			const args = [
 				"git",
 				"log",
@@ -193491,8 +193509,225 @@ const restorability = (git, headHash, headMessage, tipHash) => gen(function* ()
 		reason: "HEAD has advanced past the squash — restoring would discard commits built on top of it"
 	};
 });
-/** Idempotent: `deleteRef` already tolerates a missing ref. */
-const clearRetainedHistory = (git) => git.deleteRef(HISTORY_REF);
+//#endregion
+//#region src/GitScript.ts
+/**
+* Bash-script builders mirroring `GitWriterOperations` (`src/Git.ts`) — one
+* function per writer method, each returning the equivalent bash as a
+* `string` instead of executing it. Scaffolding for a later change that will
+* emit these scripts rather than run git directly through the `Effect`
+* `CommandExecutor`; nothing calls this module yet.
+*
+* Pure, like `src/PatternMachine.ts`: no git, no filesystem, no `Effect`, no
+* IO of any kind. Every export is a plain, total function of its arguments.
+* `src/Git.ts`'s doc comments on `GitWriterOperations` are the source of
+* truth for each shape below; read them for WHY, not just WHAT.
+*/
+/**
+* POSIX single-quote escaping: wrap `value` in `'...'`, replacing every
+* embedded `'` with `'\''` (close quote, escaped literal quote, reopen
+* quote). The only place a raw string may reach a shell command in this
+* module — every builder below routes every interpolated value through this.
+*/
+const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+/**
+* `--allow-empty` mirrors `commitAllWithPrefix`/`commitAsIs`'s load-bearing
+* use in `src/Git.ts`: gtd's workflow commits may be empty on purpose. The
+* retry-without-hooks behavior there keys off the specific "empty git commit"
+* hook-rejection message, re-failing on anything else (`src/Git.ts`'s `run`
+* doc comment records the regression a blind retry-on-any-failure would
+* reintroduce: reporting success on a genuinely rejected commit — a lint
+* error, a rejected commit-msg hook). Bash CAN inspect the message: capture
+* the first attempt's combined output and discriminate on it in a `case`,
+* exactly like `isIndexLockError`/`error.message.includes(...)` do in
+* `src/Git.ts`, instead of retrying on the exit code alone.
+*/
+const commitAllowEmpty = (message) => {
+	const m = shellQuote(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} ;;`,
+		`    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
+		`  esac`,
+		`fi`
+	].join("\n");
+};
+/**
+* `git add -A` then `git commit --allow-empty -m <message>`, retried without
+* hooks on the same hook rejection `commitAllowEmpty` guards against. Joined
+* with `&&` so a failing `git add` (e.g. a quoted path breaking it) never
+* reaches the commit — the same "lost files whose quoted paths broke a
+* swallowed `git add`" failure mode `src/Git.ts`'s `run` doc comment records.
+*/
+const commitAll = (message) => `git add -A &&\n${commitAllowEmpty(message)}`;
+/** `git commit --allow-empty -m <message>` — commits the index as-is, no implicit `git add`. */
+const commitAsIs = (message) => commitAllowEmpty(message);
+/** `git reset --soft <ref>` — HEAD moves; index and working tree untouched. */
+const softResetTo = (ref) => `git reset --soft ${shellQuote(ref)}`;
+/** `git reset --mixed <ref>` — HEAD and index move; working tree untouched. */
+const mixedResetTo = (ref) => `git reset --mixed ${shellQuote(ref)}`;
+/** `git reset --hard <ref>` — HEAD, index, AND working tree all move. */
+const hardResetTo = (ref) => `git reset --hard ${shellQuote(ref)}`;
+/**
+* `git add -A` then `git reset --hard HEAD` — discards every pending change,
+* tracked or untracked. Joined with `&&`: a failed stage must not reach the
+* hard reset, or untracked survivors remain — the exact outcome this builder
+* exists to avoid.
+*/
+const discardPending = () => `git add -A && git reset --hard HEAD`;
+/** `git update-ref <ref> <hash>` — point a repo-local ref at a commit. */
+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)}`;
+/**
+* `git restore --staged --source=<source> -- <paths…>` — tolerant of the
+* SAME two cases `src/Git.ts`'s `Effect.catchIf` tolerates (a missing ref, or
+* no path matching at `source`), and NOT tolerant of `index.lock` contention,
+* which must still fail the script rather than being swallowed here (see
+* `src/Git.ts`'s `restoreStagedFrom` doc comment and `isIndexLockError`) — a
+* lock failure silently swallowed here would mean the `.gtd/` index pin
+* silently doesn't happen, leaking `.gtd/` plumbing into the surfaced review
+* diff, the exact thing the pin exists to prevent. Captures the command's
+* output and discriminates on it, mirroring `isIndexLockError`'s two
+* substrings, exactly like `commitAllowEmpty` above. An empty `paths` emits
+* nothing at all (a harmless, syntactically valid empty script), mirroring
+* the Effect implementation's own `paths.length === 0` skip.
+*/
+const restoreStagedFrom = (source, paths) => {
+	if (paths.length === 0) return "";
+	const pathArgs = paths.map(shellQuote).join(" ");
+	return [
+		`if ! out=$(git restore --staged --source=${shellQuote(source)} -- ${pathArgs} 2>&1); then`,
+		`  case "$out" in`,
+		`    *"index.lock"*|*"Another git process seems to be running"*) printf '%s\\n' "$out" >&2; exit 1 ;;`,
+		`    *) : ;;`,
+		`  esac`,
+		`fi`
+	].join("\n");
+};
+//#endregion
+//#region src/Emit.ts
+/**
+* Assembles the two scripts a `gtd next`-time decision hands the external
+* driver: `required` (everything that decides what lands in git) and
+* `optional` (presentation only — e.g. opening the review checkout window so
+* an editor's diff view has something to show; a driver that skips it loses
+* nothing but that view). Pure, like `src/GitScript.ts`: no git, no
+* filesystem, no `Effect`. Every input string (a `GitScript.ts` builder's
+* output, a steering mode's already-rendered `format:`/`validate:` command)
+* arrives already rendered — this module only concatenates and wraps.
+*
+* Both halves are meant to stand alone: a driver may run either, both, or
+* only `required`, and a person could paste either into a terminal. That's
+* why each carries its OWN copy of the precondition asserts and the retry
+* helper, rather than the two sharing one preamble a caller has to splice
+* together correctly.
+*/
+/**
+* The CLI resolves `expectedHead` (and a review window's `expectedHash`) at
+* DECIDE time; the script may RUN later, in a process that never shared
+* memory with the one that decided. This assertion closes that
+* time-of-check/time-of-use gap. A plain `[ ... ] || { ...; exit 1; }`
+* statement, not an `if`/`fi` block, so a line-oriented consumer can still
+* recognize it, and so it stays safe under `set -e`: in an OR list, `-e`
+* exempts every command except the LAST one, so the left-hand `[ ... ]`
+* failing here never trips `set -e` on its own — only the explicit `exit 1`
+* inside the right-hand group does. Exported (alongside `reviewWindowAssertion`)
+* solely so `src/testing/EmittedScriptRecognizer.ts` can re-derive and
+* string-compare this exact shape, the same "call the real builder, never
+* hand-copy its template" discipline it already applies to every
+* `GitScript.ts` builder.
+*
+* The probe is `git rev-parse --verify --quiet HEAD 2>/dev/null`, not the
+* bare `git rev-parse HEAD` a born repo's assertion could get away with —
+* load-bearing, not cosmetic: against an UNBORN HEAD (a repository with no
+* commits), the bare form prints the literal string `HEAD` to stdout (plus a
+* `fatal:` line to stderr) and exits 128, so `"$(git rev-parse HEAD)"` reads
+* as `"HEAD"`, never `""`, and an `expectedHead === ""` comparison could
+* never pass. `--verify --quiet` makes an unborn HEAD read back as an empty
+* string instead — the same idiom `reviewWindowAssertion` already uses for a
+* missing ref — so `[ "$(…)" = '' ]` is simply the unborn case of the same
+* comparison every born repo already runs; only the `printf` wording
+* branches on it, to avoid naming a hash that doesn't exist.
+*/
+const headAssertion = (expectedHead) => {
+	const q = shellQuote(expectedHead);
+	const probe = `[ "$(git rev-parse --verify --quiet HEAD 2>/dev/null)" = ${q} ] || `;
+	return expectedHead === "" ? probe + "{ printf 'gtd: repository changed since this script was generated (expected a repository with no commits yet) — re-run gtd\\n' >&2; exit 1; }" : probe + `{ printf 'gtd: repository changed since this script was generated (expected HEAD %s) — re-run gtd\\n' ${q} >&2; exit 1; }`;
+};
+/**
+* Same shape as `headAssertion`, for the saved-head ref a review window
+* pins. `--verify --quiet ... 2>/dev/null` makes a MISSING ref read as an
+* empty string rather than erroring the substitution itself — the assertion
+* only needs to compare, never to fail outright before the `[ ... ]` runs.
+*/
+const reviewWindowAssertion = (ref, expectedHash) => {
+	const refQ = shellQuote(ref);
+	const hashQ = shellQuote(expectedHash);
+	return `[ "$(git rev-parse --verify --quiet ${refQ} 2>/dev/null)" = ${hashQ} ] || { printf 'gtd: review window ref %s changed since this script was generated (expected %s) — re-run gtd\\n' ${refQ} ${hashQ} >&2; exit 1; }`;
+};
+/**
+* `gtd_retry` takes ONE already-`shellQuote`d command string and `eval`s it,
+* mirroring `src/Git.ts`'s `withIndexLockRetry`: retry ONLY on the same two
+* substrings `isIndexLockError` matches, with jittered exponential backoff
+* (~10ms doubling, capped at 6 TOTAL attempts — the initial try plus 5
+* retries), and propagate any other failure on the very first attempt. Output
+* is captured combined (`2>&1`) so the discrimination can inspect it exactly
+* like `commitAllowEmpty`/`restoreStagedFrom` in `src/GitScript.ts` do for
+* their own single-shot retries — this is the same technique, generalized
+* into a loop. `awk` (not bash, which has no fractional `sleep` builtin)
+* turns the millisecond backoff into the fractional-second argument `sleep`
+* needs; `-v` passes the values in rather than interpolating them into the
+* awk program text, so a variable's value can never be mistaken for awk
+* syntax.
+*/
+const RETRY_HELPER = [
+	`gtd_retry() {`,
+	`  local cmd=$1 attempt=1 delay_ms=10 out total_ms jitter_ms`,
+	`  while true; do`,
+	`    if out=$(eval "$cmd" 2>&1); then`,
+	`      [ -n "$out" ] && printf '%s\\n' "$out"`,
+	`      return 0`,
+	`    fi`,
+	`    case "$out" in`,
+	`      *"index.lock"*|*"Another git process seems to be running"*) ;;`,
+	`      *) printf '%s\\n' "$out" >&2; return 1 ;;`,
+	`    esac`,
+	`    if [ "$attempt" -ge 6 ]; then`,
+	`      printf '%s\\n' "$out" >&2`,
+	`      return 1`,
+	`    fi`,
+	`    jitter_ms=$(( RANDOM % delay_ms + 1 ))`,
+	`    total_ms=$(( delay_ms + jitter_ms ))`,
+	`    sleep "$(awk -v ms="$total_ms" 'BEGIN { printf "%.3f", ms / 1000 }')"`,
+	`    delay_ms=$(( delay_ms * 2 ))`,
+	`    attempt=$(( attempt + 1 ))`,
+	`  done`,
+	`}`
+].join("\n");
+const renderStep = (step) => step.kind === "gitWrite" ? `gtd_retry ${shellQuote(step.command)}` : step.command;
+const assembleScript = (preconditions, steps) => {
+	if (steps.length === 0) return "";
+	const sections = ["set -euo pipefail"];
+	if (preconditions.expectedHead !== void 0) sections.push(headAssertion(preconditions.expectedHead));
+	if (preconditions.reviewWindow) sections.push(reviewWindowAssertion(preconditions.reviewWindow.ref, preconditions.reviewWindow.expectedHash));
+	if (steps.some((step) => step.kind === "gitWrite")) sections.push(RETRY_HELPER);
+	sections.push(...steps.map(renderStep));
+	return sections.join("\n\n");
+};
+/**
+* Build both halves from already-rendered command strings. `required`
+* defaults to `[]` (nothing to do), `optional` to `[]` (no review window to
+* open) — either omitted argument, or an explicit empty array, produces the
+* fixed empty-string result `EmittedScripts` documents: a driver checking
+* `if [ -n "$required" ]` (or the JS equivalent) never has to special-case a
+* bare preamble with no body.
+*/
+const emitScripts = (preconditions, required = [], optional = []) => ({
+	required: assembleScript(preconditions, required),
+	optional: assembleScript(preconditions, optional)
+});
 //#endregion
 //#region src/Edge.ts
 /**
@@ -193537,6 +193772,17 @@ const clearRetainedHistory = (git) => git.deleteRef(HISTORY_REF);
 * what `PatternMachine.step` consumes, despite having a single reader.
 */
 const EMPTY_TREE$2 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/**
+* The review checkout window's saved-head ref — duplicated from
+* `src/ReviewWindow.ts`'s own `REVIEW_HEAD_REF` rather than imported, because
+* `ReviewWindow.ts` already imports FROM this module (`currentRun`,
+* `reviewBaseFor`); importing it back here would be a real circular module
+* dependency. Mirrors `src/RetainedHistory.ts`'s own `HISTORY_REF` doc
+* comment on the same tradeoff. Read (never written) by `restAt`'s
+* window-aware branch and by the script preconditions below — this module
+* never opens or closes the window itself.
+*/
+const REVIEW_HEAD_REF$1 = "refs/worktree/gtd/review-head";
 const subjectOf = (message) => (message.split("\n")[0] ?? "").trim();
 const COST_TRAILER_PREFIX = "Gtd-Cost: ";
 const COST_TRAILER_RE = /^Gtd-Cost:[ \t]*([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+?))?[ \t]*$/gm;
@@ -193654,8 +193900,8 @@ const resolveRestFrom = (def, headSubject) => {
 		}
 	};
 };
-/** The working tree's pending changes vs HEAD, as the pattern grammar's `{status, path}[]`. */
-const pendingChanges = (git) => git.changedPaths().pipe(map$4((entries) => entries.map((e) => ({
+/** The working tree's pending changes vs `base` (default HEAD), as the pattern grammar's `{status, path}[]`. */
+const pendingChanges = (git, base) => git.changedPaths(base).pipe(map$4((entries) => entries.map((e) => ({
 	status: normalizeStatus(e.status),
 	path: e.path
 }))));
@@ -193696,9 +193942,16 @@ const parseEntryCommitOverrides = (processCommits) => {
 * same shape a fresh rest at a squashed boundary has always had.
 *
 * `hasCommits` is supplied by the caller (already read once — see the module
-* doc comment's stage ordering) rather than re-read here.
-*/
-const computeProcessRun = (git, def, hasCommits) => gen(function* () {
+* doc comment's stage ordering) rather than re-read here. `head` — a resolved
+* hash, never a symbolic ref — overrides the literal `HEAD` the walk would
+* otherwise end at: `restAt`'s window-aware branch passes the review
+* checkout window's saved-head hash here while the window is open, so the
+* trace still covers the commits a real `git log` would miss with HEAD
+* rewound to the review base. `undefined` (every other caller) is today's
+* exact behavior — an explicit trailing ref is passed to `git.commitHistory`
+* only when `head` differs from the literal `"HEAD"` it already defaults to.
+*/
+const computeProcessRun = (git, def, hasCommits, head) => gen(function* () {
 	if (!hasCommits) return {
 		startHash: "",
 		startParentHash: EMPTY_TREE$2,
@@ -193708,7 +193961,7 @@ const computeProcessRun = (git, def, hasCommits) => gen(function* () {
 		entryVars: {}
 	};
 	const initialState = initialStateOf(def);
-	const history = yield* git.commitHistory();
+	const history = yield* git.commitHistory(void 0, head);
 	let i = history.length - 1;
 	while (i >= 0) {
 		const parsed = parseStateSubject(subjectOf(history[i].message));
@@ -193740,12 +193993,19 @@ const computeProcessRun = (git, def, hasCommits) => gen(function* () {
 * since abandon IS the recovery command for that case) and the review
 * window's re-arm (`openReviewWindow` stays graceful there too — see its own
 * doc comment).
+*
+* Window-aware on exactly the same terms as `restAt`: while a review checkout
+* window is open, real HEAD is rewound to the review base, so walking the
+* trace from literal HEAD would see a process that has not started. Both
+* callers need the REAL head — abandon rewinds the reviewed branch tip, the
+* re-arm re-derives the review base — so the saved head is the walk's origin.
 */
 const currentRun = gen(function* () {
 	const git = yield* GitService;
 	const config = yield* (yield* ConfigService).load;
 	const hasCommits = yield* git.hasCommits();
-	return yield* computeProcessRun(git, config.workflow, hasCommits);
+	const windowHead = getOrUndefined(yield* git.readRefOption(REVIEW_HEAD_REF$1));
+	return yield* computeProcessRun(git, config.workflow, hasCommits, windowHead);
 });
 /**
 * PURE: the most-recent in-process turn commit that entered a `reviewBase`
@@ -193941,6 +194201,20 @@ const omitUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([,
 * window's saved head via `REVIEW_HEAD_REF`, or `undefined` for HEAD itself —
 * see `currentRest`). Assembles every stage documented in the module doc
 * comment, threading one `hasCommits()` read through stages 3/5/11.
+*
+* Window-aware ONLY at `ref === undefined` (`currentRest`'s own case): when
+* the review checkout window's saved-head ref (`REVIEW_HEAD_REF`) resolves,
+* its hash is used as the effective head for `lastCommitSubject` AND
+* `computeProcessRun`'s trace walk — real git HEAD has been rewound to the
+* review base while the window is open, so reading literal `HEAD` there
+* would resolve state/trace/memory against the wrong commit. An explicit
+* `ref` (`gtd visualize`'s own call pattern) never triggers this branch —
+* that path resolves exactly as it always has. Safe to land now because
+* every existing command closes the window (`program.ts`'s
+* `runInReviewWindowBracket`) before `restAt`/`currentRest` ever runs, so the
+* saved-head ref is already gone by the time this branch could fire in
+* production — see the two direct tests in `Edge.test.ts` for the only
+* coverage today.
 */
 const restAt = (ref) => gen(function* () {
 	const git = yield* GitService;
@@ -193949,16 +194223,19 @@ const restAt = (ref) => gen(function* () {
 	const envVars = yield* EnvVars;
 	const def = config.workflow;
 	const hasCommits = yield* git.hasCommits();
-	const headSubject = hasCommits ? yield* git.lastCommitSubject(ref) : "";
+	let windowHead;
+	if (ref === void 0) windowHead = getOrUndefined(yield* git.readRefOption(REVIEW_HEAD_REF$1));
+	const effectiveRef = windowHead ?? ref;
+	const headSubject = hasCommits ? yield* git.lastCommitSubject(effectiveRef) : "";
 	const resolution = resolveRestFrom(def, headSubject);
 	if (!resolution.ok) return yield* fail$2(resolution.error);
 	const resolved = resolution.rest;
-	const run = yield* computeProcessRun(git, def, hasCommits);
+	const run = yield* computeProcessRun(git, def, hasCommits, windowHead);
 	const vars = resolveVars(config.workflowVars, config.rcVars, run.entryVars, envVars.all);
 	const on = yield* renderOnEdgesOrFail(resolved.stateDef.on, vars);
 	const stepDef = withRenderedOn(def, resolved.state, on);
 	const reviewBase = reviewBaseFor(def, run);
-	const changes = yield* pendingChanges(git);
+	const changes = yield* pendingChanges(git, windowHead);
 	const context = yield* buildTemplateContext(git, templateRead(files), resolved.state, resolved.actor, run, vars, on, 0, void 0, reviewBase, hasCommits);
 	const memory = memoryKeyFor(config.stateScopes, resolved, run);
 	const hints = yield* renderHints(resolved.stateDef, context);
@@ -194035,10 +194312,13 @@ const renderRest = (rest) => gen(function* () {
 const formatStepRefusal = (invoker, refusal) => refusal.reason === "out-of-turn" ? `gtd step ${invoker}: out of turn — "${refusal.state}" awaits ${refusal.awaits}` : `gtd step ${invoker}: no declared pattern matches the pending changes at "${refusal.state}" — declared patterns: ${refusal.patterns.length > 0 ? refusal.patterns.join(", ") : "(none)"}`;
 /**
 * Build the `TemplateContext` for rendering a DIFFERENT state than `rest`'s
-* own resting one, with a step's `cost`/`model` folded in — `planStep`'s
-* squash branch is its only caller (the commit branch never reads a
-* `TemplateContext` — see `executeDecision`), so this stays unexported per
-* the module's two-caller rule.
+* own resting one, with a step's `cost`/`model` folded in. A squash's commit
+* template is the only thing that needs it (the commit branch never reads a
+* `TemplateContext` at all), and it is NOT interchangeable with `rest.context`:
+* that one is pinned to the resting state and carries `cost: 0`, so rendering
+* `it.processCost` against it silently omits the squashing step's own
+* `--cost`. Exported for `program.ts`'s `stepAsActor`, which assembles the
+* same script by hand and must pick the same context.
 */
 const contextAt = (rest, targetState, invoker, cost, model) => gen(function* () {
 	const git = yield* GitService;
@@ -194086,6 +194366,119 @@ const executeDecision = (git, run, decision, context, cost, model) => gen(functi
 	}
 });
 /**
+* Render a `"commit"`/`"squash"` decision as the `EmitStep`s the external
+* driver would run to produce the SAME effect `executeDecision` performs
+* directly — same switch, same subjects, same trailers, same ordering. Every
+* git call here is a READ (`git.resolveRef("HEAD")` for the squash branch's
+* pre-squash tip); nothing is written. `planStep`/`planEntry`'s script
+* assembly (`buildStepScripts`) and `Edge.test.ts`'s render/perform
+* equivalence tests are its two callers.
+*
+* The squash branch renders the commit-state template against the PENDING
+* tree — a render failure fails this Effect exactly like `executeDecision`'s
+* own (same message), touching no git. On success it emits, in order:
+* retain-history (`updateRef(HISTORY_REF, tip)`, OMITTED when `tip ===
+* run.startParentHash` — an empty process retains nothing, mirroring
+* `retainHistory`'s own no-op check, decided here since `tip` is already
+* known), soft-reset to the process start, commit-as-is with the rendered
+* message plus its `Gtd-History:` trailer, then discard-pending.
+*
+* The commit branch carries `executeDecision`'s one non-obvious case too: a
+* commit whose target is the workflow's INITIAL state, from a process that
+* retained nothing, is a no-op probe (`gtd --entry fix-precheck` against a
+* green suite is the shipped example) and must leave no trace at all. It
+* emits retain-history + a mixed reset to the process start instead of a
+* commit, so the entry commit and the probe collapse away together rather
+* than dirtying the log with a round trip to `idle`. Deciding it needs the
+* whole `rest` (its definition for the initial state, its pending changes for
+* the "retained nothing" test), which is why this takes a `Rest` rather than
+* the `ProcessRun` alone.
+*/
+const renderDecision = (git, rest, decision, context, cost, model) => gen(function* () {
+	const run = rest.run;
+	switch (decision.kind) {
+		case "commit":
+			if (parseStateSubject(decision.subject)?.state === initialStateOf(rest.def) && run.startParentHash !== EMPTY_TREE$2 && (yield* retainsNothing(git, run, rest.changes))) {
+				const tip = yield* git.resolveRef("HEAD");
+				const steps = [];
+				if (tip !== run.startParentHash) steps.push({
+					kind: "gitWrite",
+					command: updateRef(HISTORY_REF, tip)
+				});
+				steps.push({
+					kind: "gitWrite",
+					command: mixedResetTo(run.startParentHash)
+				});
+				return steps;
+			}
+			return [{
+				kind: "gitWrite",
+				command: commitAll(withCostTrailer(decision.subject, cost, model))
+			}];
+		case "squash": {
+			const message = yield* try_({
+				try: () => renderStateTemplate(decision.template, context),
+				catch: (e) => /* @__PURE__ */ new Error(`gtd: rendering the "${decision.state}" commit template failed — nothing was committed: ${e instanceof Error ? e.message : String(e)}`)
+			});
+			const tip = yield* git.resolveRef("HEAD");
+			const steps = [];
+			if (tip !== run.startParentHash) steps.push({
+				kind: "gitWrite",
+				command: updateRef(HISTORY_REF, tip)
+			});
+			steps.push({
+				kind: "gitWrite",
+				command: softResetTo(run.startParentHash)
+			});
+			steps.push({
+				kind: "gitWrite",
+				command: commitAsIs(withHistoryTrailer(message, tip))
+			});
+			steps.push({
+				kind: "gitWrite",
+				command: discardPending()
+			});
+			return steps;
+		}
+	}
+});
+/**
+* The `EmitPreconditions` a step's/entry's assembled scripts assert against:
+* `expectedHead` is the resolved HEAD hash the `Rest` snapshot was already
+* taken at — `rest.context.currentCommit`, passed straight through, `""`
+* included (its own convention for "no commits yet", which `headAssertion`
+* now understands natively). When `targetState` declares `reviewWindow: true`
+* AND a window is currently open (`REVIEW_HEAD_REF` resolves), the script also
+* pins the window's saved-head hash — a later run whose window has since
+* closed or moved must re-decide rather than trust a stale script. No window,
+* or a non-review-window target, carries no `reviewWindow` precondition at
+* all.
+*/
+const buildPreconditions = (git, rest, targetState) => gen(function* () {
+	const expectedHead = rest.context.currentCommit;
+	if (!isReviewWindowState(rest.def, targetState)) return { expectedHead };
+	const windowHead = yield* git.readRefOption(REVIEW_HEAD_REF$1);
+	if (isNone(windowHead)) return { expectedHead };
+	return {
+		expectedHead,
+		reviewWindow: {
+			ref: REVIEW_HEAD_REF$1,
+			expectedHash: windowHead.value
+		}
+	};
+});
+/**
+* The `EmittedScripts` a `"commit"`/`"squash"` `StepPlan` carries alongside
+* `perform` — built from the SAME `renderDecision` output, but a render
+* failure collapses to an EMPTY script (`emitScripts` with no steps) instead
+* of failing this Effect: `perform` stays the one place a render failure is
+* ever reported to a caller, unchanged by this addition.
+*/
+const buildStepScripts = (git, rest, decision, context, cost, model) => gen(function* () {
+	const targetState = decision.kind === "commit" ? decision.to : decision.state;
+	return emitScripts(yield* buildPreconditions(git, rest, targetState), yield* renderDecision(git, rest, decision, context, cost, model).pipe(catchAll(() => succeed$3([]))));
+});
+/**
 * Decide what invoking `invoker` at `rest` does (`PatternMachine.step` over
 * `rest.stepDef`/`rest.changes`/`rest.run.trace`), and — for a `"commit"`/
 * `"squash"` decision — build the `perform` Effect that actually writes it.
@@ -194099,19 +194492,19 @@ const executeDecision = (git, run, decision, context, cost, model) => gen(functi
 * reads it) or a freshly built `contextAt` for a squash (which renders a
 * DIFFERENT state's template with the step's cost folded in).
 */
-const planStep = (rest, invoker, opts = {}) => {
+const planStep = (rest, invoker, opts = {}) => gen(function* () {
 	const decision = step(rest.stepDef, rest.state, invoker, {
 		changes: rest.changes,
 		processTrace: rest.run.trace.map((entry) => entry.state)
 	});
-	if (decision.kind === "refusal") return succeed$3({
+	if (decision.kind === "refusal") return {
 		kind: "refusal",
 		message: formatStepRefusal(invoker, decision)
-	});
-	if (decision.kind === "noop") return succeed$3({
+	};
+	if (decision.kind === "noop") return {
 		kind: "noop",
 		state: decision.state
-	});
+	};
 	const { cost, model } = opts;
 	const perform = gen(function* () {
 		const git = yield* GitService;
@@ -194130,13 +194523,17 @@ const planStep = (rest, invoker, opts = {}) => {
 		const context = yield* contextAt(rest, decision.state, invoker, cost, model);
 		return yield* executeDecision(git, rest.run, decision, context, cost, model);
 	});
-	return succeed$3({
+	const git = yield* GitService;
+	const scriptContext = decision.kind === "commit" ? rest.context : yield* contextAt(rest, decision.state, invoker, cost, model);
+	const scripts = yield* buildStepScripts(git, rest, decision, scriptContext, cost, model);
+	return {
 		kind: decision.kind,
 		state: rest.state,
 		decision,
-		perform
-	});
-};
+		perform,
+		scripts
+	};
+});
 /**
 * `gtd step <actor> --entry <state>` (or its subcommand-less short form `gtd
 * --entry <state>`): start a brand NEW process at `entry.state` — any
@@ -194220,18 +194617,24 @@ const planEntry = (rest, actor, entry) => gen(function* () {
 		...base !== void 0 ? { base } : {},
 		vars: varOverrides
 	});
+	const perform = gen(function* () {
+		yield* (yield* GitService).commitAllWithPrefix(message);
+		return {
+			kind: "entry",
+			state: entryState,
+			subject
+		};
+	});
+	const scriptsGit = yield* GitService;
 	return {
 		kind: "entry",
 		state: entryState,
 		subject,
-		perform: gen(function* () {
-			yield* (yield* GitService).commitAllWithPrefix(message);
-			return {
-				kind: "entry",
-				state: entryState,
-				subject
-			};
-		})
+		perform,
+		scripts: emitScripts(yield* buildPreconditions(scriptsGit, rest, entryState), [{
+			kind: "gitWrite",
+			command: commitAll(message)
+		}])
 	};
 });
 //#endregion
@@ -194249,24 +194652,37 @@ const planEntry = (rest, actor, entry) => gen(function* () {
 * `PatternMachine.StateDef`) — the pure engine never observes an open window,
 * exactly as before.
 *
-* Lifecycle — driven from the program edge (`src/program.ts`), bracketing
-* every state subcommand:
-*
-* - `closeReviewWindow` runs BEFORE anything reads or mutates state, keyed
-*   solely on `REVIEW_HEAD_REF` existing: `git reset --mixed <that ref>`
-*   restores HEAD/index exactly, leaving only the reviewer's own edits dirty
-*   (captured by the resting state's own `on` patterns like any other pending
-*   change). The pure machine therefore never sees the window.
-* - `openReviewWindow` runs AFTER the subcommand finishes and self-guards on
-*   the resolved rest declaring `reviewWindow: true`: it saves HEAD to
-*   `REVIEW_HEAD_REF` (the base to `REVIEW_BASE_REF`), then `git reset --mixed
-*   <base>`. It re-arms after read-only commands (`gtd next` / `gtd status`)
-*   and refused invocations too, so the editor's diff view stays consistent no
-*   matter which command the loop last ran.
-*
-* Every open/close step is idempotent under re-entry, so a crash at any point
-* is recovered by the next invocation's close (the saved ref also keeps the
-* real head GC-reachable for the window's whole lifetime).
+* Lifecycle — driven from the program edge (`src/program.ts`), which DECIDES
+* with this module's pure/read-only halves and assembles the actual writes
+* into the two scripts a `gtd` command hands the external driver:
+*
+* - The CLOSE sequence (`decideCloseWindow` + `buildCloseWindowScript`) is
+*   read-only in this module — it decides whether a window is open and safe
+*   to close, keyed solely on `REVIEW_HEAD_REF` existing (the same
+*   reviewed-branch/legacy-containment guards described below) — and
+*   `program.ts`'s `buildRequiredScript` splices the resulting
+*   `mixedResetTo`/`deleteRef`/`deleteRef` bash in as the LEAD steps of the
+*   `required` script, ahead of the commit/squash steps themselves. Nothing
+*   reads or mutates state until the driver actually runs that script; once
+*   it does, HEAD/index are restored exactly, leaving only the reviewer's own
+*   edits dirty (captured by the resting state's own `on` patterns like any
+*   other pending change) — the pure machine never sees the window.
+* - The OPEN sequence (`decideOpenWindow` + `buildOpenWindowScript`) is
+*   likewise read-only — it self-guards on the STEP'S OWN target state
+*   declaring `reviewWindow: true` — and `program.ts`'s `openWindowScript`
+*   turns that into the `optional` script's `updateRef`/`updateRef`/
+*   `mixedResetTo`/`restoreStagedFrom` bash: saving HEAD to `REVIEW_HEAD_REF`
+*   (the base to `REVIEW_BASE_REF`), then rewinding to the base. The driver
+*   runs it AFTER the required script has already landed the new commit
+*   (`buildOpenWindowScript`'s own doc comment explains why it pins the
+*   literal string `"HEAD"`, never a resolved hash). It re-arms after
+*   read-only commands (`gtd next` / `gtd status`) and refused invocations
+*   too, so the editor's diff view stays consistent no matter which command
+*   the loop last ran.
+*
+* Every close/open sequence is idempotent under re-entry, so a crash at any
+* point is recovered by the next invocation's close (the saved ref also keeps
+* the real head GC-reachable for the window's whole lifetime).
 */
 /**
 * The window's two state refs live in git's PER-WORKTREE `refs/worktree/*`
@@ -194284,7 +194700,7 @@ const planEntry = (rest, actor, entry) => gen(function* () {
 const REVIEW_HEAD_REF = "refs/worktree/gtd/review-head";
 const REVIEW_BASE_REF = "refs/worktree/gtd/review-base";
 /**
-* The pre-7.2 SHARED refs. gtd never writes them any more; `closeReviewWindow`
+* The pre-7.2 SHARED refs. gtd never writes them any more; `decideCloseWindow`
 * only reads them to finish a window an older gtd left open across the upgrade
 * — and only when HEAD is still contained in the saved head, since a shared ref
 * may belong to a sibling worktree (see `openWindowRefs`).
@@ -194316,28 +194732,10 @@ const openWindowRefs = (git) => gen(function* () {
 		legacy: true
 	});
 });
-/**
-* Restore the real head if a review checkout window is open; no-op otherwise.
-* Keyed on the saved-head ref's existence (see `openWindowRefs`), NOT on any
-* config or machine state, so it always runs first and the machine never sees
-* the window.
-*
-* Fails loudly — refs left in place — when HEAD is no longer on the reviewed
-* branch (the base is not an ancestor of HEAD, e.g. after a branch switch): a
-* mixed reset there would rewrite the wrong branch's tip. Manual commits on
-* top of the base pass the guard: the reset keeps their content in the working
-* tree, where the next turn's capture picks it up as review feedback.
-*
-* A window found under the LEGACY shared refs gets one extra guard: a shared
-* ref may have been written by a sibling worktree, so the close only proceeds
-* when HEAD is contained in the saved head — the shape a window this worktree
-* opened itself has. Anything else refuses with the manual recovery rather
-* than resetting this branch onto another worktree's work (issue #118).
-*/
-const closeReviewWindow = gen(function* () {
+const decideCloseWindow = gen(function* () {
 	const git = yield* GitService;
 	const open = yield* openWindowRefs(git);
-	if (isNone(open)) return { closed: false };
+	if (isNone(open)) return { shouldClose: false };
 	const refs = open.value;
 	const base = yield* git.readRefOption(refs.baseRef);
 	if (isSome(base) && base.value !== EMPTY_TREE$1) {
@@ -194346,44 +194744,65 @@ const closeReviewWindow = gen(function* () {
 	if (refs.legacy) {
 		if (!(yield* git.isAncestor("HEAD", refs.headHash))) return yield* fail$2(/* @__PURE__ */ new Error(`a review checkout window is recorded under the shared ${LEGACY_REVIEW_HEAD_REF} (written by gtd 7.1 or older) but it does not belong to this worktree — HEAD is not contained in it. gtd now scopes the window per worktree (${REVIEW_HEAD_REF}); in the worktree that owns it, run ${manualRecovery(refs)}`));
 	}
-	yield* git.mixedResetTo(refs.headRef);
-	yield* git.deleteRef(refs.headRef);
-	yield* git.deleteRef(refs.baseRef);
-	return { closed: true };
+	return {
+		shouldClose: true,
+		refs
+	};
 });
 /**
-* Open (or re-arm) the review checkout window. Self-guarded: a no-op unless
-* the resolved rest's state declares `reviewWindow: true` and a distinct base
-* commit exists, so the caller invokes it unconditionally after every state
-* subcommand.
-*
-* The base is the most-recent in-process `reviewBase` commit
-* (`reviewBaseHash`) or, absent any such state, the process's diff base
-* (`run.diffBase` — the process start, `startParentHash`, unless a
-* `gtd review <commitish>` entry commit overrode it via a `Gtd-Review-Base:`
-* trailer, see `computeProcessRun`). When that resolves to the empty tree (a
-* process with no prior commit) or to HEAD itself (an empty process), there
-* is nothing to surface and the window stays closed.
-*
-* Ordering is crash-safe: base ref → head ref → mixed reset → `.gtd/` index
-* pin. A crash before the head-ref write leaves only a stale base ref
-* (overwritten on the next open); a crash after it leaves HEAD ==
-* review-head, which the next invocation's close restores as a no-op.
-*/
-const openReviewWindow = gen(function* () {
-	const git = yield* GitService;
-	const def = (yield* (yield* ConfigService).load).workflow;
-	if (!(yield* git.hasCommits())) return { opened: false };
-	if (!isReviewWindowState(def, resolveState(def, yield* git.lastCommitSubject()))) return { opened: false };
-	const base = reviewBaseFor(def, yield* currentRun);
-	const headHash = yield* git.resolveRef("HEAD");
-	if (base === EMPTY_TREE$1 || base === headHash) return { opened: false };
-	yield* git.updateRef(REVIEW_BASE_REF, base);
-	yield* git.updateRef(REVIEW_HEAD_REF, headHash);
-	yield* git.mixedResetTo(base);
-	yield* git.restoreStagedFrom(REVIEW_HEAD_REF, [".gtd"]);
-	return { opened: true };
-});
+* PURE: the close sequence's bash text — reset to the saved head, then delete
+* both refs — built from `src/GitScript.ts`'s `mixedResetTo`/`deleteRef`.
+* Assumes its caller's guards (the reviewed-branch check, the legacy
+* containment check — see `decideCloseWindow`) have already passed; this
+* builder performs none of them, only the write sequence for the case where
+* they did.
+*
+* The reset target is `refs.headHash` — the RESOLVED hash, not `refs.headRef`
+* by name — precisely so the sequence stays idempotent once the ref itself is
+* gone: the very next statement deletes `headRef`, so a script naming the ref
+* for the reset would fail on re-entry (the ref `git reset --mixed` would
+* need is the one the script just deleted). A hash stays resolvable
+* regardless, so a second run's reset is a true no-op (HEAD is already
+* there) and both deletes tolerate an already-missing ref. `legacy` on `refs`
+* goes unused here — the script only needs `headRef`/`baseRef`/`headHash` —
+* but the parameter carries the whole `WindowRefs` record so a caller can
+* pass `decideCloseWindow`'s resolved `refs` straight through.
+*/
+const buildCloseWindowScript = (refs) => [
+	mixedResetTo(refs.headHash),
+	deleteRef(refs.headRef),
+	deleteRef(refs.baseRef)
+].join(" &&\n");
+const decideOpenWindow = (def, target, run, head) => {
+	if (!isReviewWindowState(def, target)) return { shouldOpen: false };
+	const base = reviewBaseFor(def, run);
+	if (base === EMPTY_TREE$1 || base === head) return { shouldOpen: false };
+	return {
+		shouldOpen: true,
+		base,
+		head
+	};
+};
+/**
+* PURE: the open sequence's bash text — base-ref write, head-ref write,
+* mixed-reset-to-base, then the `.gtd/` restore-staged-from pin, built from
+* `src/GitScript.ts`'s `updateRef`/`mixedResetTo`/`restoreStagedFrom`, in the
+* same crash-safe order `openReviewWindow` uses (base ref → head ref → mixed
+* reset → `.gtd/` pin). Deliberately no `git add --intent-to-add` anywhere —
+* new files stay untracked, for the exact two reasons `openReviewWindow`'s
+* own doc comment records — and no whole-tree index write: `restoreStagedFrom`
+* is scoped to `.gtd/` alone.
+*
+* Idempotent under re-entry: `updateRef`/`mixedResetTo` re-pointing at the
+* same target is a no-op, and `restoreStagedFrom` re-pinning an already-pinned
+* path is a no-op.
+*/
+const buildOpenWindowScript = (decision) => [
+	updateRef(REVIEW_BASE_REF, decision.base),
+	updateRef(REVIEW_HEAD_REF, decision.head),
+	mixedResetTo(decision.base),
+	restoreStagedFrom(REVIEW_HEAD_REF, [".gtd"])
+].join(" &&\n");
 //#endregion
 //#region node_modules/vscode-languageserver/lib/common/utils/is.js
 var require_is$2 = /* @__PURE__ */ __commonJSMin(((exports) => {
@@ -205438,17 +205857,17 @@ const resolveBuiltInMode = (mode) => {
 };
 const steeringCapabilities = (resolved) => {
 	if (resolved === void 0) return {};
+	const seeded = resolved.builtIn !== void 0 && resolved.validate?.kind === "command" && isSeededValidateCommand(resolved.mode, resolved.validate.command);
+	const liveValidate = resolved.builtIn !== void 0 && (resolved.validate?.kind === "builtin" || seeded) ? resolved.builtIn.validate : void 0;
 	return {
 		...resolved.builtIn !== void 0 ? { format: resolved.builtIn } : {},
-		...resolved.validate?.kind === "builtin" ? { liveValidate: resolved.validate.format.validate } : {},
-		...resolved.validate?.kind === "command" ? { externalValidate: true } : {}
+		...liveValidate !== void 0 ? { liveValidate } : {},
+		...resolved.validate?.kind === "command" && !seeded ? { externalValidate: true } : {}
 	};
 };
 /** The error message for a `mode:` that resolves to nothing — lists what the active workflow does know. */
 const unknownModeMessage = (def, state, mode) => `state "${state}": mode "${mode}" is not defined by the active workflow (known modes: ${knownModes(def).join(", ")})`;
 const errorText$1 = (e) => e instanceof Error ? e.message : String(e);
-/** How a non-zero exit reads in a message: a status number, or a signal death. */
-const exitText = (status) => status === null ? "a signal" : `status ${status}`;
 /** Render one command template, turning an Eta failure into a named error rather than executing anything. */
 const renderCommand = (mode, key, command, file, context) => try_({
 	try: () => renderModeCommand(command, {
@@ -205457,41 +205876,22 @@ const renderCommand = (mode, key, command, file, context) => try_({
 	}),
 	catch: (e) => /* @__PURE__ */ new Error(`mode "${mode}": "${key}" command failed to render — ${errorText$1(e)}`)
 });
-/** The findings a non-zero `validate` exit reports: its output lines, or a synthesized line when it said nothing. */
-const findingsFrom = (mode, outcome) => {
-	const lines = outcome.output.split("\n").map((line) => line.trimEnd()).filter((line) => line.length > 0);
-	if (lines.length > 0) return lines;
-	return [`mode "${mode}": validate command exited with ${exitText(outcome.status)} and no output`];
-};
-/**
-* Format `file` in place by running the mode's `format:` command. A mode with
-* no formatter (every mode, until a `modes:` layer declares one — gtd ships
-* none) formats nothing. A failing command is a hard error: the file is left
-* exactly as it was and the caller refuses, rather than validating a
-* half-formatted file.
-*/
-const formatSteeringFile = (resolved, file, context) => gen(function* () {
-	const command = resolved.formatCommand;
-	if (command === void 0) return;
-	const rendered = yield* renderCommand(resolved.mode, "format", command, file, context);
-	const outcome = yield* (yield* CommandRunner).bash(rendered);
-	if (outcome.status !== 0) return yield* fail$2(/* @__PURE__ */ new Error(`mode "${resolved.mode}": format command exited with ${exitText(outcome.status)}${outcome.output.trim().length > 0 ? `:\n${outcome.output.trimEnd()}` : ""}`));
-});
 /**
-* Validate `file` per its mode, returning the findings (empty = valid). A
-* built-in validator runs its pure parser over `content` (the caller's already
-* read this — see `src/StepGuards.ts`, which samples the file's bytes AFTER
-* `formatSteeringFile` has run); a declared `validate:` command runs instead
-* and reads nothing itself — the command owns how it inspects the file. A mode
-* with neither reports no findings.
-*/
-const validateSteeringFile = (resolved, file, content, context) => gen(function* () {
-	const validator = resolved.validate;
-	if (validator === void 0) return [];
-	if (validator.kind === "builtin") return validator.format.validate(content);
-	const rendered = yield* renderCommand(resolved.mode, "validate", validator.command, file, context);
-	const outcome = yield* (yield* CommandRunner).bash(rendered);
-	return outcome.status === 0 ? [] : findingsFrom(resolved.mode, outcome);
+* Render a mode's `format:`/`validate:` commands as plain strings, WITHOUT
+* running either — for a caller (an emitter that prints scripts rather than
+* executing them) that wants the commands themselves, not their outcome.
+* Unlike its siblings above, this needs no `CommandRunner`: it shares their
+* `renderCommand` helper for the rendering (and its errors) but never reaches
+* for a runner to execute the result. Order matches `formatAndValidateSteeringFile`
+* (format then validate); a half the mode doesn't declare — no `formatCommand`,
+* or a `validate` that is absent or `"builtin"` (an in-process parser has no
+* shell command to render) — is OMITTED from the result, not rendered as `""`.
+*/
+const renderSteeringCommands = (resolved, file, context) => gen(function* () {
+	const commands = [];
+	if (resolved.formatCommand !== void 0) commands.push(yield* renderCommand(resolved.mode, "format", resolved.formatCommand, file, context));
+	if (resolved.validate?.kind === "command") commands.push(yield* renderCommand(resolved.mode, "validate", resolved.validate.command, file, context));
+	return commands;
 });
 //#endregion
 //#region src/Lsp.ts
@@ -206174,27 +206574,6 @@ const openInBrowser = (url) => {
 //#region src/StepGuards.ts
 /** Normalize every markdown checkbox to a single placeholder so a pure `[ ]`→`[x]` tick is invisible to a text comparison; any surviving difference is a human note. */
 const normalizeCheckboxes = (content) => content.replace(/\[[ xX]\]/g, "[_]");
-const steeringFileGuard = {
-	name: "steering-file",
-	appliesTo: (rest) => rest.stateDef.mode !== void 0,
-	prepare: (ctx) => gen(function* () {
-		const mode = ctx.rest.stateDef.mode;
-		const resolved = resolveSteeringMode(ctx.rest.def, mode);
-		if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(ctx.rest.def, ctx.rest.state, mode)));
-		if ((yield* RepoFiles).working(ctx.file) === void 0) return;
-		yield* formatSteeringFile(resolved, ctx.file, ctx.template);
-	}),
-	check: (ctx) => gen(function* () {
-		const mode = ctx.rest.stateDef.mode;
-		const resolved = resolveSteeringMode(ctx.rest.def, mode);
-		if (resolved === void 0) return void 0;
-		const current = yield* ctx.worktree;
-		if (current === void 0) return void 0;
-		const errors = yield* validateSteeringFile(resolved, ctx.file, current, ctx.template);
-		if (errors.length === 0) return void 0;
-		return `${ctx.file} is not valid at "${ctx.rest.state}" — fix these before stepping:\n${errors.map((e) => `  - ${e}`).join("\n")}`;
-	})
-};
 /** The `mode:` name of gtd's built-in REVIEW.md checkbox validator — the only mode the sign-off guard understands. */
 const REVIEW_MODE = "review";
 const reviewSignoffGuard = {
@@ -206224,9 +206603,8 @@ const feedbackProgressGuard = {
 };
 /** The `mode:` name of gtd's built-in open-questions checkbox format — the only mode the answer-completeness guard acts on. */
 const QA_MODE = "qa";
-/** The four step-capture guards, in EVALUATION order — message precedence when two would fire is observable, so this order is the contract (matches the old hand-copied call order). */
+/** The three step-capture guards, in EVALUATION order — message precedence when two would fire is observable, so this order is the contract (matches the old hand-copied call order, minus the now-removed steering-file guard). */
 const stepGuards = [
-	steeringFileGuard,
 	reviewSignoffGuard,
 	feedbackProgressGuard,
 	{
@@ -206242,7 +206620,7 @@ const stepGuards = [
 ];
 /**
 * The `gtd step` capture gate: run every guard the resolved rest's state
-* applies to, formatting (write phase) before validating (read phase) — see
+* applies to against ONE sample of the current committed/working bytes — see
 * the module docstring — and fail with the first refusal's reason, prefixed
 * `gtd step <invoker>: ` (the one place that prefix, and the `cliErrorLine`
 * `/^gtd[: ]/` contract, is satisfied). A no-op for a squash/no-op decision, a
@@ -206264,7 +206642,6 @@ const enforceStepGuards = (input) => gen(function* () {
 		hasCodeChange,
 		template: input.context
 	};
-	for (const g of applicable) if (g.prepare !== void 0) yield* g.prepare(base);
 	const files = yield* RepoFiles;
 	const head = yield* cached(files.committed(file));
 	const worktree = yield* cached(try_(() => files.working(file)));
@@ -206278,37 +206655,6 @@ const enforceStepGuards = (input) => gen(function* () {
 		if (refusal !== void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd step ${input.invoker}: ${refusal}`));
 	}
 });
-/**
-* `gtd validate`'s shared evaluation: format the resolved rest's steering
-* file in place, then validate its formatted contents — the SAME
-* format-then-validate pair the `steering-file` guard's `prepare`/`check`
-* split runs, so both format and check the same way (an agent's fresh draft
-* and a human's edit are treated alike). `present` is false — and nothing is
-* formatted or validated — when the state declares no steering file, or the
-* file is absent (e.g. a human deleted `.gtd/REVIEW.md` to approve).
-*/
-const checkSteeringFile = (rest, context, file) => gen(function* () {
-	const mode = rest.stateDef.mode;
-	if (file === void 0 || mode === void 0) return {
-		file,
-		present: false,
-		errors: []
-	};
-	const files = yield* RepoFiles;
-	if (files.working(file) === void 0) return {
-		file,
-		present: false,
-		errors: []
-	};
-	const resolved = resolveSteeringMode(rest.def, mode);
-	if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(rest.def, rest.state, mode)));
-	yield* formatSteeringFile(resolved, file, context);
-	return {
-		file,
-		present: true,
-		errors: yield* validateSteeringFile(resolved, file, files.working(file) ?? "", context)
-	};
-});
 //#endregion
 //#region src/program.ts
 /**
@@ -206353,57 +206699,144 @@ const runInitCommand = (json, write) => gen(function* () {
 	}) + "\n");
 	else write("Wrote .gtdrc.json seeding the default variables (the test command) and a\nPrettier formatting suggestion. gtd runs its built-in workflow by default — add\na workflow: key only if you want to customize the machine itself.\n\n" + (inRepo ? "Review and commit it before starting: an uncommitted .gtdrc.json counts as a\npending change, so the initial state would capture it on the first step. Once\ncommitted, run `gtd step human` to begin.\n" : "This directory is not a git repository, so there is nothing to commit here. The\nconfig applies to any gtd repository nested below it — gtd discovers it by\nwalking up from the repository root. Run `gtd step human` from such a repo to\nbegin.\n"));
 });
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/** The `EmitPreconditions` every script this file assembles asserts against: the resolved HEAD hash the snapshot driving it was taken at — `""` when the repo has no commits yet, `headAssertion`'s own convention for that case. */
+const headPreconditions = (currentCommit) => ({ expectedHead: currentCommit });
+/**
+* The resting state's own steering-mode commands, embedded ahead of the
+* commit — the step script now carries its own format/validate pair instead
+* of gtd running it in process (see `src/StepGuards.ts`'s shrunk registry).
+* Empty for a state declaring no `file:`+`mode:` pair; an unknown mode name
+* is a refusal, exactly as it was when gtd ran the commands itself.
+*/
+const steeringModeSteps = (rest) => gen(function* () {
+	const file = rest.hints.file;
+	const mode = rest.stateDef.mode;
+	if (file === void 0 || mode === void 0) return [];
+	const resolved = resolveSteeringMode(rest.def, mode);
+	if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(rest.def, rest.state, mode)));
+	return (yield* renderSteeringCommands(resolved, file, rest.context)).map((command) => ({
+		kind: "command",
+		command
+	}));
+});
+/**
+* The `optional` half: re-open the review checkout window when the step lands
+* at a `reviewWindow: true` state, `""` otherwise.
+*
+* `"HEAD"` is deliberately the literal string, not a resolved hash — git
+* resolves it at the moment this script runs, which is after the required
+* script has already landed the new commit (see `ReviewWindow.ts`'s
+* `decideOpenWindow` doc comment). For the same reason it carries no
+* `expectedHead` precondition: the HEAD it will see is a hash that does not
+* exist yet at decide time (see `EmitPreconditions`).
+*/
+const openWindowScript = (rest, targetState) => {
+	const decision = decideOpenWindow(rest.def, targetState, rest.run, "HEAD");
+	if (!decision.shouldOpen) return "";
+	return emitScripts({}, [], [{
+		kind: "gitWrite",
+		command: buildOpenWindowScript({
+			base: decision.base,
+			head: "HEAD"
+		})
+	}]).optional;
+};
+/**
+* The subject the required script WILL produce. A `"commit"` decision's is
+* fully deterministic already; a `"squash"` decision's is only known once its
+* template is rendered. Unreachable-on-failure: `renderDecision` already
+* rendered the same template and refused the command if it threw, so this
+* second render can never be the first to fail.
+*/
+const previewSubject = (decision, rest) => decision.kind === "commit" ? succeed$3(decision.subject) : try_(() => renderStateTemplate(decision.template, rest.context).split("\n")[0].trim()).pipe(catchAll(() => succeed$3(null)));
+/**
+* The `required` half: everything that decides what lands in git, in order —
+* the review-window CLOSE (when one is open), the resting state's own
+* steering-mode format/validate commands, then the commit/squash steps
+* themselves.
+*/
+const buildRequiredScript = (rest, decision, invoker, cost, model) => gen(function* () {
+	const git = yield* GitService;
+	const closeDecision = yield* decideCloseWindow;
+	const commitContext = decision.kind === "commit" ? rest.context : yield* contextAt(rest, decision.state, invoker, cost, model);
+	const steps = [
+		...closeDecision.shouldClose ? [{
+			kind: "gitWrite",
+			command: buildCloseWindowScript(closeDecision.refs)
+		}] : [],
+		...yield* steeringModeSteps(rest),
+		...yield* renderDecision(git, rest, decision, commitContext, cost, model)
+	];
+	return emitScripts(headPreconditions(rest.context.currentCommit), steps).required;
+});
+/** A step's `--cost`/`--model` as `planStep` options — each key OMITTED (never `undefined`-valued) when the flag was not given. */
+const stepOptions = (cost, model) => ({
+	...cost !== void 0 ? { cost } : {},
+	...model !== void 0 ? { model } : {}
+});
 /**
-* Authenticate `invoker` against the currently resolved rest and perform the
-* one resulting transition (commit or squash) for `gtd step`. `currentRest` →
-* `planStep` decides; the four capture gates sit between the plan and
-* `plan.perform` (nothing has written git yet), then `perform` runs. Refusals
-* fail the Effect with a formatted message; a no-op/reset returns `subject:
-* null` rather than failing (exit zero, per the plan's "clean no-op exits
-* zero").
+* Authenticate `invoker` against the currently resolved rest and decide the
+* one resulting transition (commit or squash) for `gtd step` — WITHOUT
+* performing it. `currentRest` → `planStep` decides; the step-capture guards
+* (`src/StepGuards.ts`) then refuse before anything is emitted, exactly as
+* before. What used to be `plan.perform` is now assembled by hand into a
+* `required` script (the review-window CLOSE, when one is open; the resting
+* state's steering-mode format/validate commands, when it declares
+* `file:`+`mode:`; then the commit/squash steps themselves, via
+* `renderDecision`) and an `optional` one (the review-window OPEN, when the
+* target declares `reviewWindow: true`) — see the "Review-window management"
+* recipe this mirrors. Refusals fail the Effect with a formatted message; a
+* no-op returns `subject: null` and empty scripts (exit zero, nothing to
+* run).
+*
+* `plan.scripts` (built by `Edge.ts` itself) is NOT reused here: its baked-in
+* precondition uses `rest.context.currentCommit`, the LITERAL git HEAD at
+* decide time — which, while a review window is open, is the window's BASE,
+* not the real head — and it contains no window close/open steps at all. This
+* function builds its own required/optional pair to sidestep that trap.
 */
 const stepAsActor = (invoker, cost, model) => gen(function* () {
 	const rest = yield* currentRest;
-	const plan = yield* planStep(rest, invoker, {
-		...cost !== void 0 ? { cost } : {},
-		...model !== void 0 ? { model } : {}
-	});
+	const plan = yield* planStep(rest, invoker, stepOptions(cost, model));
 	if (plan.kind === "refusal") return yield* fail$2(new Error(plan.message));
 	if (plan.kind === "noop") return {
 		state: plan.state,
 		subject: null,
 		cost: null,
-		model: null
+		model: null,
+		required: "",
+		optional: ""
 	};
+	const decision = plan.decision;
+	if (decision.kind !== "commit" && decision.kind !== "squash") return yield* fail$2(/* @__PURE__ */ new Error(`gtd: internal error — plan kind "${plan.kind}" but decision kind "${decision.kind}"`));
 	yield* enforceStepGuards({
 		rest,
 		context: rest.context,
 		file: rest.hints.file,
 		changes: rest.changes,
 		invoker,
-		kind: plan.kind
+		kind: decision.kind
 	});
-	const outcome = yield* plan.perform;
-	if (outcome.kind === "reset" || outcome.kind === "noop") return {
-		state: outcome.state,
-		subject: null,
-		cost: null,
-		model: null
-	};
+	const targetState = decision.kind === "commit" ? decision.to : decision.state;
 	return {
 		state: rest.state,
-		subject: outcome.subject,
+		subject: yield* previewSubject(decision, rest),
 		cost: cost ?? null,
-		model: model ?? null
+		model: model ?? null,
+		required: yield* buildRequiredScript(rest, decision, invoker, cost, model),
+		optional: openWindowScript(rest, targetState)
 	};
 });
-/** Renders `stepAsActor`'s result for `gtd step`. */
+/** Renders `stepAsActor`'s result for `gtd step`. Plain text names the (previewed) resulting subject exactly as before; `--json` additionally carries `required`/`optional` — the bash the external driver runs to actually land it. */
 const reportStepResult = (result, json, write) => {
 	if (json) write(JSON.stringify({
 		state: result.state,
 		subject: result.subject,
 		...result.cost !== null ? { cost: result.cost } : {},
-		...result.model !== null ? { model: result.model } : {}
+		...result.model !== null ? { model: result.model } : {},
+		required: result.required,
+		optional: result.optional
 	}) + "\n");
 	else write(result.subject !== null ? `committed: ${result.subject}\n` : `nothing to do at "${result.state}"\n`);
 };
@@ -206461,14 +206894,14 @@ const runEntryCommand = (actor, entryState, varOverrides, json, write, commandLa
 		vars: varOverrides
 	});
 	if (plan.kind === "refusal") return yield* fail$2(new Error(plan.message));
-	yield* plan.perform;
 	if (json) write(JSON.stringify({
 		state: plan.state,
-		subject: plan.subject
+		subject: plan.subject,
+		required: plan.scripts.required,
+		optional: plan.scripts.optional
 	}) + "\n");
 	else write(`committed: ${plan.subject}\n`);
 });
-const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 /**
 * `gtd abandon`: end the process currently underway WITHOUT completing it,
 * returning the machine to the workflow's initial state — the recovery path out
@@ -206500,6 +206933,13 @@ const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 * that fails when there is nothing to recover is a worse tool. The one refusal
 * is a process whose first commit is the repository's own root commit: there is
 * no earlier commit to rewind to.
+*
+* The read-side refusal/no-op checks above stay direct `GitService` reads (the
+* documented exception, `AGENTS.md`) — abandon must still work when a `Rest`
+* would refuse. The actual mutation (retaining history, then the mixed reset)
+* is no longer PERFORMED here: it's emitted as a `required` bash script for
+* the external driver to run, built from `src/GitScript.ts`'s pure
+* `updateRef`/`mixedResetTo` — narrowing the exception further still.
 */
 const runAbandonCommand = (json, write) => gen(function* () {
 	const git = yield* GitService;
@@ -206516,14 +206956,31 @@ const runAbandonCommand = (json, write) => gen(function* () {
 	}
 	const restState = run.trace[run.trace.length - 1].state;
 	if (run.startParentHash === EMPTY_TREE) return yield* fail$2(/* @__PURE__ */ new Error(`gtd abandon: the process underway (resting at "${restState}") starts at the repository's first commit — there is no earlier commit to rewind to`));
-	yield* retainHistory(git, yield* git.resolveRef("HEAD"), run.startParentHash);
-	yield* git.mixedResetTo(run.startParentHash);
-	const subject = yield* git.lastCommitSubject();
+	const closeDecision = yield* decideCloseWindow;
+	const tip = closeDecision.shouldClose ? closeDecision.refs.headHash : yield* git.resolveRef("HEAD");
+	const subject = yield* git.lastCommitSubject(run.startParentHash);
+	const steps = [
+		...closeDecision.shouldClose ? [{
+			kind: "gitWrite",
+			command: buildCloseWindowScript(closeDecision.refs)
+		}] : [],
+		{
+			kind: "gitWrite",
+			command: updateRef(HISTORY_REF, tip)
+		},
+		{
+			kind: "gitWrite",
+			command: mixedResetTo(run.startParentHash)
+		}
+	];
+	const required = emitScripts(headPreconditions(yield* git.resolveRef("HEAD")), steps).required;
 	if (json) write(JSON.stringify({
 		state: initial,
 		abandoned: true,
 		from: restState,
-		head: run.startParentHash
+		head: run.startParentHash,
+		required,
+		optional: ""
 	}) + "\n");
 	else write(`abandoned the process resting at "${restState}" — HEAD is back at ${run.startParentHash.slice(0, 7)} ("${subject}"), resting at "${initial}".\nEverything the process produced is kept as uncommitted changes (\`git status\`); discard them with \`git checkout -- . && git clean -fd .gtd\` for a clean tree.\n`);
 });
@@ -206537,7 +206994,10 @@ const runAbandonCommand = (json, write) => gen(function* () {
 * Guarded by `restorability` so it never discards work it didn't create:
 * refuses on a dirty working tree, when there is no retained history, and
 * when HEAD has advanced past the retained tip with commits that would be
-* lost by resetting.
+* lost by resetting. Those checks stay direct `GitService` reads (same
+* documented exception as `gtd abandon`); the mutation itself (the hard
+* reset, then clearing the retained-history ref) is emitted as a `required`
+* script instead of performed here.
 */
 const runRestoreCommand = (json, write) => gen(function* () {
 	const git = yield* GitService;
@@ -206549,31 +207009,69 @@ const runRestoreCommand = (json, write) => gen(function* () {
 	const headHash = yield* git.resolveRef("HEAD");
 	const check = yield* restorability(git, headHash, yield* git.lastCommitMessage(), tip);
 	if (!check.ok) return yield* fail$2(/* @__PURE__ */ new Error(`gtd restore: ${check.reason} — HEAD ${headHash.slice(0, 7)} is ahead of the retained tip ${tip.slice(0, 7)}.`));
-	yield* git.hardResetTo(tip);
-	yield* clearRetainedHistory(git);
-	const after = yield* currentRest;
-	const subject = yield* git.lastCommitSubject();
+	const after = yield* restAt(tip);
+	const subject = yield* git.lastCommitSubject(tip);
+	const steps = [{
+		kind: "gitWrite",
+		command: hardResetTo(tip)
+	}, {
+		kind: "gitWrite",
+		command: deleteRef(HISTORY_REF)
+	}];
+	const required = emitScripts(headPreconditions(headHash), steps).required;
 	if (json) write(JSON.stringify({
 		state: after.state,
 		restored: true,
 		to: tip,
-		from: before.state
+		from: before.state,
+		required,
+		optional: ""
 	}) + "\n");
 	else write(`restored the retained history — HEAD is back at ${tip.slice(0, 7)} ("${subject}"), resting at "${after.state}". Resume with the loop, or \`git reset\` to any earlier turn to restart from there.\n`);
 });
 /**
+* The mode's own resolved VALIDATE command, rendered against `file` — the
+* command `selfValidateInstruction` names. Resolution mirrors
+* `renderSteeringCommands`'s own layering (`src/SteeringMode.ts`) but picks
+* out the validate half alone: a declared `validate:` command (or, for
+* `qa`/`review`, `PatternConfig.ts`'s own seeded `gtd check <mode> '<file>'`
+* default — every compiled definition carries ONE of the two) renders as the
+* LAST command `renderSteeringCommands` would emit (format, if any, always
+* comes first); a mode resolving to a `"builtin"` validator (no shell command
+* at all — only reachable when `resolveSteeringMode` is asked about a mode
+* outside the active definition's own compiled `modes:`, since a real
+* definition always seeds one) or to no mode at all names the leaf
+* `gtd check <mode> '<file>'` invocation directly instead
+* (`seededValidateCommand`), so there is always something concrete to name.
+*/
+const resolveSelfValidateCommand = (def, mode, file, context) => gen(function* () {
+	const resolved = resolveSteeringMode(def, mode);
+	if (resolved?.validate?.kind === "command") {
+		const rendered = yield* renderSteeringCommands(resolved, file, context);
+		const validateCommand = rendered[rendered.length - 1];
+		if (validateCommand !== void 0) return validateCommand;
+	}
+	return yield* try_({
+		try: () => renderModeCommand(seededValidateCommand(mode), {
+			...context,
+			file
+		}),
+		catch: (e) => e instanceof Error ? e : new Error(String(e))
+	});
+});
+/**
 * The self-validation instruction gtd APPENDS to a `prompt` rest that declares
 * both `file:` and `mode:` — i.e. a state whose actor hands over a steering
-* file `gtd validate` formats and checks. Appended ONLY to plain `gtd next`
-* output (for a human or a simple driver who reads the prompt and hands it to
-* an agent, so the agent self-validates); withheld from `gtd next --json`,
-* where the driving loop instead runs `gtd validate` after the turn and
-* re-prompts on findings (see the `bin/gtd` loop driver). This is
-* advisory: `gtd step` runs the same format-and-validate gate and REFUSES a
-* turn whose steering file is invalid (see `stepAsActor`), so a malformed file
-* is never captured whether or not this instruction was followed.
-*/
-const selfValidateInstruction = (file) => `\nBefore finishing your turn, run \`gtd validate\` — it formats and checks ${file} — and fix every violation it reports until it exits cleanly. Do not finish while it still reports violations.\n`;
+* file some command validates. Appended ONLY to plain `gtd next` output (for a
+* human or a simple driver who reads the prompt and hands it to an agent, so
+* the agent self-validates); withheld from `gtd next --json`, where the
+* driving loop instead runs `gtd validate` after the turn and re-prompts on
+* findings (see the `bin/gtd` loop driver). This is advisory: `gtd step`
+* embeds that same command ahead of its own commit and REFUSES a turn whose
+* steering file is invalid (see `stepAsActor`), so a malformed file is never
+* captured whether or not this instruction was followed.
+*/
+const selfValidateInstruction = (command, file) => `\nBefore finishing your turn, run \`${command}\` — it checks ${file} — and fix every violation it reports until it exits cleanly. Do not finish while it still reports violations.\n`;
 /** True when a rendered rest is a `prompt` turn that hands over a validatable steering file (`file:`+`mode:` both declared). */
 const emitsValidatablePrompt = (rendered) => rendered.kind === "prompt" && rendered.file !== void 0 && rendered.mode !== void 0;
 /** `gtd next [--json]`: pure emitter of the resolved rest's rendered content (no mutation). */
@@ -206590,51 +207088,116 @@ const nextJsonOutput = (rendered) => JSON.stringify({
 	...rendered.mode !== void 0 ? { mode: rendered.mode } : {},
 	...rendered.edges.length > 0 ? { edges: rendered.edges } : {}
 }) + "\n";
-/** `gtd next`'s plain-text output: the rendered content (newline-terminated), plus the self-validation instruction when the rest is a validatable prompt (see `emitsValidatablePrompt`). */
-const nextPlainOutput = (rendered) => {
+/** `gtd next`'s plain-text output: the rendered content (newline-terminated), plus the self-validation instruction (naming `selfValidateCommand`, when resolved) when the rest is a validatable prompt. */
+const nextPlainOutput = (rendered, selfValidateCommand) => {
 	const base = rendered.content.endsWith("\n") ? rendered.content : rendered.content + "\n";
-	return emitsValidatablePrompt(rendered) ? base + selfValidateInstruction(rendered.file) : base;
+	return emitsValidatablePrompt(rendered) && selfValidateCommand !== void 0 ? base + selfValidateInstruction(selfValidateCommand, rendered.file) : base;
 };
 const runNextCommand = (json, write) => gen(function* () {
-	const rendered = yield* renderRest(yield* currentRest);
-	write(json ? nextJsonOutput(rendered) : nextPlainOutput(rendered));
+	const rest = yield* currentRest;
+	const rendered = yield* renderRest(rest);
+	const selfValidateCommand = !json && emitsValidatablePrompt(rendered) ? yield* resolveSelfValidateCommand(rest.def, rendered.mode, rendered.file, rest.context).pipe(catchAll(() => succeed$3(void 0))) : void 0;
+	write(json ? nextJsonOutput(rendered) : nextPlainOutput(rendered, selfValidateCommand));
 });
 /**
-* `gtd validate [--json]`: format (in place) then validate the steering file
-* the resolved rest declares (`file:` rendered, `mode:` selecting how), over
-* its WORKING-TREE contents. A state with no `file:`/`mode:`, or an absent
-* file, has nothing to validate (exit 0). A clean verdict exits 0; violations
-* FAIL the Effect with the findings (one per line), so the process exits
-* non-zero — the signal a producing agent (or the driver) loops on until the
-* file is valid. A built-in mode reuses the canonical `OpenQuestions`/
-* `ReviewDoc` parsers (the same the LSP publishes), so there is one source of
-* truth per format and no bash port; any `modes:`-declared command runs
-* instead (or, for `format:`, in addition).
+* `gtd validate [--json]`: emit the script that would format (in place) then
+* validate the steering file the resolved rest declares (`file:` rendered,
+* `mode:` selecting how) — the SAME commands `gtd step`'s capture guard now
+* embeds ahead of its own commit (see `stepAsActor`), rendered here for a
+* human or agent to run directly. gtd itself reads no file and executes
+* nothing: a state with no `file:`/`mode:`, or a file absent from the working
+* tree, has nothing to validate (`script: ""`, exit 0 either way) — the
+* verdict now lives in the emitted script's own future exit code, not this
+* command's, so this never fails on a bad file. `RepoFiles`/`FileSystem` is
+* used only to check the file's PRESENCE, never to read or judge its content.
 */
 const runValidateCommand = (json, write) => gen(function* () {
 	const rest = yield* currentRest;
-	const { file, present, errors } = yield* checkSteeringFile(rest, rest.context, rest.hints.file);
-	if (!present) {
+	const file = rest.hints.file;
+	const mode = rest.stateDef.mode;
+	const emitNothingToValidate = () => {
 		if (json) write(JSON.stringify({
 			state: rest.state,
-			valid: true,
-			errors: []
+			...file !== void 0 ? { file } : {},
+			...mode !== void 0 ? { mode } : {},
+			script: ""
 		}) + "\n");
 		else write(`nothing to validate at "${rest.state}"\n`);
+	};
+	if (file === void 0 || mode === void 0) {
+		emitNothingToValidate();
+		return;
+	}
+	const fs = yield* FileSystem;
+	const toError = (e) => e instanceof Error ? e : new Error(String(e));
+	if (!(yield* fs.exists(file).pipe(mapError$1(toError)))) {
+		emitNothingToValidate();
 		return;
 	}
+	const resolved = resolveSteeringMode(rest.def, mode);
+	if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(rest.def, rest.state, mode)));
+	const commands = yield* renderSteeringCommands(resolved, file, rest.context);
+	const script = emitScripts(headPreconditions(rest.context.currentCommit), commands.map((command) => ({
+		kind: "command",
+		command
+	}))).required;
+	if (json) write(JSON.stringify({
+		state: rest.state,
+		file,
+		mode,
+		script
+	}) + "\n");
+	else write(script.length > 0 ? `${script}\n` : `nothing to validate at "${rest.state}"\n`);
+});
+/**
+* `gtd check <mode> <file>`: read `<file>` and run the BUILT-IN steering
+* format named `<mode>`'s pure parser over its contents, printing each
+* finding one per line and exiting non-zero when there are any. Unlike `gtd
+* validate` (which resolves the currently resting state's own `file:`/`mode:`
+* and formats before validating), this resolves NO workflow state and reads
+* NO config — both `mode` and `file` are given explicitly, so it needs only
+* `FileSystem.FileSystem` and runs from any directory. This is what a
+* workflow's seeded `validate:` command (`SteeringFormats.ts`'s
+* `seededValidateCommand`) invokes as a leaf step; it does no formatting
+* in-place — an emitted script has no template context to format against.
+*
+* An absent file mirrors `gtd validate`'s own absent-file behavior: exit 0,
+* no output in plain mode, `{valid: true, errors: []}` under `--json`. A
+* clean parse is the same shape. A non-clean parse writes `--json`'s
+* `{valid: false, errors}` body (or each finding, one per line, in plain
+* mode) BEFORE failing the Effect. In PLAIN mode the failure then carries only
+* a summary message, landing on stderr alone (`cliErrorLine`'s line) — the
+* findings are already on stdout. Under `--json`, `Cli.ts`'s single envelope
+* writer (`report`) ALSO puts its own `{state:"error",prompt}` object on
+* stdout for any failing Effect, so a `--json` invocation with findings emits
+* stdout as two newline-delimited JSON documents — this handler's own
+* `{valid,errors}` body first, then the generic error envelope — rather than
+* one; a consumer must read line-delimited JSON, not `JSON.parse(stdout)`
+* whole. Kept as the pragmatic resolution of a real tension in this command's
+* two governing requirements ("exits non-zero" and "`--json` reports
+* `{valid,errors}`"): the alternative was piping a `--json` failure through a
+* NEW exit-code channel bypassing `Cli.ts`'s shared envelope entirely, which
+* every other command's `--json` failure goes through today.
+*/
+const runCheckCommand = (mode, file, json, write) => gen(function* () {
+	const format = steeringFormatFor(mode);
+	if (format === void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd check: unknown mode "${mode}" — known modes: ${builtInModeNames().join(", ")}`));
+	const fs = yield* FileSystem;
+	const toError = (e) => e instanceof Error ? e : new Error(String(e));
+	const errors = (yield* fs.exists(file).pipe(mapError$1(toError))) ? format.validate(yield* fs.readFileString(file).pipe(mapError$1(toError))) : [];
 	if (errors.length === 0) {
 		if (json) write(JSON.stringify({
-			state: rest.state,
-			file,
-			mode: rest.stateDef.mode,
 			valid: true,
 			errors: []
 		}) + "\n");
-		else write(`${file}: valid\n`);
 		return;
 	}
-	return yield* fail$2(/* @__PURE__ */ new Error(`${file} is not valid:\n${errors.map((e) => `  - ${e}`).join("\n")}`));
+	if (json) write(JSON.stringify({
+		valid: false,
+		errors
+	}) + "\n");
+	else write(errors.join("\n") + "\n");
+	return yield* fail$2(/* @__PURE__ */ new Error(`gtd check: ${file} is not valid under mode "${mode}" (${errors.length} finding(s))`));
 });
 /** Which declared `on` pattern (if any) each pending change matches — the pure computation `gtd status` reports (both plain and `--json`). `onEdges` is ALREADY RENDERED against `it.vars` (`renderOnEdges`) — the reported pattern is the one a real `gtd step` would match against. */
 const computeStatusChanges = (onEdges, changes) => changes.map((change) => {
@@ -206841,7 +207404,8 @@ const assertInitLocation = (git, fs) => gen(function* () {
 const needsOf = (kind) => {
 	switch (kind) {
 		case "lsp": return "none";
-		case "init": return "fs";
+		case "init":
+		case "check": return "fs";
 		case "visualize": return "config";
 		default: return "state";
 	}
@@ -206859,29 +207423,22 @@ const dispatchCommand = (command, json, write) => {
 		case "next": return runNextCommand(json, write);
 		case "status": return runStatusCommand(json, write);
 		case "validate": return runValidateCommand(json, write);
+		case "check": return runCheckCommand(command.mode, command.file, json, write);
 	}
 };
 /**
-* Runs `command` inside the bracket every state-touching command shares: the
-* repo-root guard, then close-any-open-review-window before the command sees
-* HEAD, then re-arm it afterward whether `command` succeeded or refused (see
-* `closeReviewWindow`/`openReviewWindow`).
-*/
-const runInReviewWindowBracket = (git, fs, command) => gen(function* () {
-	yield* assertRunningFromRepoRoot(git, fs);
-	yield* closeReviewWindow;
-	const outcome = yield* either(command);
-	const rearm = yield* either(openReviewWindow);
-	if (isLeft(outcome)) return yield* fail$2(outcome.left);
-	if (isLeft(rearm)) return yield* fail$2(rearm.left);
-});
-/**
 * The one entry point `Cli.ts`'s `runCli` calls for a resolved `Command`:
 * dispatches to the matching `run*Command` handler (see `dispatchCommand`),
-* wrapped in the repo-root guard + review-window bracket exactly when
-* `needsOf(command.kind) === "state"` — `lsp`/`init`/`visualize` (the
-* `standaloneKinds`) run bare. `Cli.ts` has already validated every field on
-* `command` (arity, flag scope, decoding), so nothing here re-parses argv.
+* wrapped in the repo-root guard exactly when `needsOf(command.kind) ===
+* "state"` — `lsp`/`init`/`visualize`/`check` (the `standaloneKinds`) run
+* bare. `Cli.ts` has already validated every field on `command` (arity, flag
+* scope, decoding), so nothing here re-parses argv.
+*
+* No review-window close/open bracket runs here any more: every state-command
+* handler (see `stepAsActor`) now decides for itself, off `ReviewWindow.ts`'s
+* pure `decideCloseWindow`/`decideOpenWindow`, whether a close/open belongs in
+* the script it emits — there is no in-process HEAD to rewind ahead of time
+* (gtd itself no longer writes git for a state command at all).
 */
 const runCommand = (command, json, write) => {
 	const dispatch = dispatchCommand(command, json, write);
@@ -206889,7 +207446,8 @@ const runCommand = (command, json, write) => {
 	return gen(function* () {
 		const git = yield* GitService;
 		const fs = yield* FileSystem;
-		yield* runInReviewWindowBracket(git, fs, dispatch);
+		yield* assertRunningFromRepoRoot(git, fs);
+		yield* dispatch;
 	});
 };
 //#endregion
@@ -207089,9 +207647,14 @@ const COMMAND_ROWS = [
 		kind: "validate",
 		arity: "none",
 		details: [
-			"Format and validate the steering file the resolved rest",
-			"declares, with its mode's commands (its file:/mode:);",
-			"exits non-zero with the findings when it is invalid"
+			"Print the script that formats (when declared) then",
+			"validates the resolved rest's steering file, using its",
+			"mode's commands (its file:/mode:), instead of running it —",
+			"a driver runs the script and reads the findings from its",
+			"own exit code/output. Always exits 0; --json emits",
+			"{state, file?, mode?, script} (script is \"\" when there is",
+			"nothing to validate; plain text prints \"nothing to",
+			"validate\" in that case)"
 		]
 	},
 	{
@@ -207109,6 +207672,20 @@ const COMMAND_ROWS = [
 			"local web server (--port <n>, --no-open; --json prints the",
 			"model and exits)"
 		]
+	},
+	{
+		token: "check",
+		kind: "check",
+		arity: { names: ["mode", "file"] },
+		details: [
+			"Read <file> and run the built-in steering format named",
+			"<mode> (see `gtd validate`'s modes: qa, review) over its",
+			"contents, printing each finding one per line and exiting",
+			"non-zero when there are any. Resolves no workflow state and",
+			"reads no config — standalone, runnable from any directory",
+			"with <mode>/<file> given explicitly. This is what a",
+			"workflow's emitted validation script invokes as a leaf step"
+		]
 	}
 ];
 const commandByToken = (token) => COMMAND_ROWS.find((r) => r.token === token);
@@ -207147,7 +207724,7 @@ const flagHeader = (row) => {
 };
 const renderHelp = () => {
 	const commandBlocks = COMMAND_ROWS.map((row) => {
-		const header = row.arity === "none" ? row.token : `${row.token} <${row.arity.name}>`;
+		const header = row.arity === "none" ? row.token : "names" in row.arity ? `${row.token} <${row.arity.names[0]}> <${row.arity.names[1]}>` : `${row.token} <${row.arity.name}>`;
 		return renderBlock(header, row.details);
 	});
 	return `Usage: gtd [command] [options]\n\nCommands:\n${PRELUDE_LOOP + commandBlocks[0] + commandBlocks[1] + ENTRY_SHORT_FORM + commandBlocks.slice(2).join("") + VERSION_BLOCK + HELP_BLOCK}\nOptions:\n${FLAGS.map((row) => renderBlock(flagHeader(row), row.help)).join("")}${renderBlock("--version, -v", ["Print version and exit"]) + renderBlock("--help, -h", ["Print this help and exit"])}`;
@@ -207233,6 +207810,12 @@ const scopeViolation = (kind, present) => {
 };
 const arityError = (cmd, rest, arity) => {
 	if (arity === "none") return rest.length > 0 ? `gtd ${cmd}: too many arguments — expected none, got: ${rest.join(", ")}` : void 0;
+	if ("names" in arity) {
+		const [first, second] = arity.names;
+		if (rest.length < 2) return rest.length === 0 ? `gtd ${cmd}: missing ${first} and ${second} arguments` : `gtd ${cmd}: missing ${second} argument`;
+		if (rest.length > 2) return `gtd ${cmd}: too many arguments — expected ${first} and ${second}, got: ${rest.join(", ")}`;
+		return;
+	}
 	if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`;
 	if (rest.length > 1) return `gtd ${cmd}: too many arguments — expected one ${arity.name}, got: ${rest.join(", ")}`;
 };
@@ -207339,6 +207922,15 @@ const parseArgv = (argv) => {
 		},
 		json
 	};
+	if (kind === "check") return {
+		kind: "command",
+		command: {
+			kind: "check",
+			mode: restPositionals[0],
+			file: restPositionals[1]
+		},
+		json
+	};
 	return {
 		kind: "command",
 		command: { kind },