@pmelab/gtd 9.0.0 → 9.1.1

package/README.md

@@ -79,25 +79,27 @@ carrying one piece of content (a script, a prompt, a message, or a squash commit
 template), with an ordered set of change-patterns routing to the next state.
 
 The loop is one beat, repeated: run `gtd next --json` and dispatch on `kind` —
-`"message"` means it's a human's move (stop and hand off); `"capture"` means a
-human gate the human already acted on (land it immediately); `"script"` means
-the driver runs `content` itself, then lands it; `"prompt"` means feed `content`
-to your agent — using the accompanying `session.id`/`session.resume` to continue
-or start that agent conversation (see "Driving the loop" below) — then run
-`gtd land` once it's done. gtd itself never executes anything — the driver owns
-running scripts. Every `gtd next` call is strictly mutation-free, safe to poll
-or peek at any time: `session.id`/`session.resume` are DERIVED, never stored, so
-looking is free — nothing distinguishes a peek from a dispatch, and there is no
-separate claiming form at all. A `prompt` beat whose turn changes nothing still
-lands: `gtd land` commits an EMPTY `gtd(<actor>): <state>` attempt instead of
-silently doing nothing, so the fruitless dispatch is visible in history rather
-than invisible. `"kind": "stalled"` is derived from that history — HEAD is an
-empty attempt at the resting state and the tree is clean — so every
-`gtd next --json` call reports it, and it stays reported on a repeat (there's no
-marker to consume) until something actually changes. The fix for a repeated
-stall is either a better prompt, a `retry:` cap on the state that redirects to
-an escalation state after N fruitless attempts, or — if the state can
-legitimately finish with nothing to change — declaring a `C` (clean-tree)
+`"message"` means it's a human's move (stop and hand off, unless it's the run's
+opening beat, which the human triggered by re-running the driver: land that one,
+since changing nothing is itself a declared outcome at some gates); `"capture"`
+means a human gate the human already acted on (land it immediately); `"script"`
+means the driver runs `content` itself, then lands it; `"prompt"` means feed
+`content` to your agent — using the accompanying `session.id`/`session.resume`
+to continue or start that agent conversation (see "Driving the loop" below) —
+then run `gtd land` once it's done. gtd itself never executes anything — the
+driver owns running scripts. Every `gtd next` call is strictly mutation-free,
+safe to poll or peek at any time: `session.id`/`session.resume` are DERIVED,
+never stored, so looking is free — nothing distinguishes a peek from a dispatch,
+and there is no separate claiming form at all. A `prompt` beat whose turn
+changes nothing still lands: `gtd land` commits an EMPTY `gtd(<actor>): <state>`
+attempt instead of silently doing nothing, so the fruitless dispatch is visible
+in history rather than invisible. `"kind": "stalled"` is derived from that
+history — HEAD is an empty attempt at the resting state and the tree is clean —
+so every `gtd next --json` call reports it, and it stays reported on a repeat
+(there's no marker to consume) until something actually changes. The fix for a
+repeated stall is either a better prompt, a `retry:` cap on the state that
+redirects to an escalation state after N fruitless attempts, or — if the state
+can legitimately finish with nothing to change — declaring a `C` (clean-tree)
 pattern on it.
 
 An `on` edge may also carry a short imperative `action` (e.g. `Accept plan`)
@@ -141,22 +143,28 @@ landing script opens a **review checkout window**: HEAD is rewound to the review
 base with the working tree untouched, so the whole reviewable change shows up as
 ordinary uncommitted changes in your editor's normal git integration (and files
 added during the process show up as ordinary untracked files, so discarding one
-deletes it). The next landing's own script closes the window before it commits.
-Tick a box as you review each hunk (ticking just records "I read this"), and
-leave a **comment** to request changes: a note on a line, an inline
-`// TODO`-style comment in the code, or a direct code edit. Any comment sends a
-build + re-review round — an agent first turns your comments into an explicit
-instruction list, then a build turn implements it (a re-review then covers only
-the follow-through, and a hand-edit is treated as your own fix the agent
-completes without reverting your lines; a comment can't be silently dropped — a
-build turn that addresses nothing is refused). For the simple flow, the build
-turn that follows through on feedback and the turn that drafts the final squash
-message both resume the same session that built the feature in the first place,
-since the review tail is nested inside that build identity rather than sitting
-beside it. Ticking every box with no comment is the sign-off, which collapses
-the whole process into one commit (a **squash finale** whose message an agent
-drafts). Landing with a box still unticked and no comment is refused (finish
-reviewing first), as is deleting `.gtd/REVIEW.md`.
+deletes it — an untracked file you leave alone is not a pending change, and only
+actually removing it from disk counts as a deletion). The next landing's own
+script closes the window before it commits. Tick a box as you review each hunk
+(ticking just records "I read this"), and leave a **comment** to request
+changes: a note on a line, an inline `// TODO`-style comment in the code, or a
+direct code edit. Any comment sends a build + re-review round — an agent first
+turns your comments into an explicit instruction list, then a build turn
+implements it (a re-review then covers only the follow-through, and a hand-edit
+is treated as your own fix the agent completes without reverting your lines; a
+comment can't be silently dropped — a build turn that addresses nothing is
+refused). For the simple flow, the build turn that follows through on feedback
+and the turn that drafts the final squash message both resume the same session
+that built the feature in the first place, since the review tail is nested
+inside that build identity rather than sitting beside it. Ticking every box with
+no comment is the sign-off, which collapses the whole process into one commit (a
+**squash finale** whose message an agent drafts). Landing with a box still
+unticked and no comment is refused (finish reviewing first), as is deleting
+`.gtd/REVIEW.md`. Both refusals hold wherever the review doc lives: repointing
+`reviewFile` out of `.gtd/` (say to `REVIEW.md` at the repo root) changes
+nothing about them — your own edit to the review doc is never mistaken for a
+code comment, and the doc's pre-turn copy is read at the review window's saved
+head rather than at the rewound `HEAD`.
 
 The same review tail also has a direct entry point —
 `gtd --entry review-gate.check --var reviewBase=<commitish>` starts a brand new
@@ -367,8 +375,19 @@ autonomous states (agent turns, check runs) and stops at the first
 non-autonomous one: reaching a human gate it prints the gate's message and
 exits. You act by editing files (answer a plan question, tick a review box, fix
 code) and re-running it — your pending edit arrives as the loop's first beat
-(`kind: "capture"`, landed immediately), so you never run `gtd land` by hand; a
-mid-process restart simply resumes driving from whatever beat is actually next.
+(`kind: "capture"`, landed immediately), so you never run `gtd land` by hand.
+
+Some gates accept by INACTION instead: the bundled template's `plan.await-plan`
+routes its `"C"` (clean-tree) pattern onward, so changing nothing there means
+"accept the plan". That reaches the driver as `kind: "message"`, which no
+inspection can tell apart from a gate you have not read yet — so the driver
+treats its OPENING beat as yours either way and lands it: you re-ran it while
+resting there, and that invocation IS the decision. Every later beat halts as
+usual, because a gate the driver produced mid-run is one you have not seen.
+Landing an opening beat at a gate with no `"C"` pattern is harmless — a benign
+no-op (see `gtd land`'s exit codes below) — and the gate then prints on the next
+beat. A mid-process restart simply resumes driving from whatever beat is
+actually next.
 
 Anything richer at that boundary — opening your editor, desktop notifications,
 terminal-multiplexer status — is the job of an outer wrapper around the driver,
@@ -642,13 +661,17 @@ gtd_land() {
   return 0
 }
 
+beat=1
 while :; do
   next="$(gtd next --json)" || exit 1
   kind="$(jq -r .kind <<<"$next")"
   log="$(jq -r .log <<<"$next")"
   case "$kind" in
     stalled) jq -r .content <<<"$next" >&2; exit 1 ;;
-    message) jq -r .content <<<"$next"; exit 0 ;;
+    # you re-ran us resting here: you either edited something or accepted by
+    # editing nothing, so land the opening beat either way. Later beats are
+    # gates we just produced and you have not read yet — hand off.
+    message) [ "$beat" = 1 ] || { jq -r .content <<<"$next"; exit 0; } ;;
     capture) ;; # the human already acted — just land it
     script) bash -c "$(jq -r .content <<<"$next")" >>"$log" 2>&1 || true ;;
     prompt)
@@ -668,6 +691,7 @@ while :; do
       done ;;
   esac
   gtd_land || exit 1
+  beat=$((beat + 1))
 done
 ```
 
@@ -675,11 +699,15 @@ Line by line it is the protocol described above: no opening move at all — a
 human's pending edit arrives as the `capture` beat, and a stray `gtd land`
 outside a beat you acted on would author an empty attempt at a clean prompt rest
 on purpose; one `gtd next --json` beat document read per loop (`kind: "stalled"`
-guarding against a spinning agent); `message` halts, `capture` lands a human's
-already-made edit outright, `script` runs in the driver, `prompt` goes to the
-agent with the document's own `session.id`/`session.resume` mapped onto the
-agent's session flags — trying `resume`'s hinted flag first and falling back to
-the other on failure, since `session.id` is derived, not remembered (see
+guarding against a spinning agent); `message` halts unless it is the opening
+beat, which the human's own re-invocation authored and which therefore lands
+like any other decision (see [Driving the loop](#driving-the-loop) above — this
+is the one place the driver, not gtd, decides, because "has the human read this
+gate" is run-scoped knowledge gtd deliberately does not keep); `capture` lands a
+human's already-made edit outright, `script` runs in the driver, `prompt` goes
+to the agent with the document's own `session.id`/`session.resume` mapped onto
+the agent's session flags — trying `resume`'s hinted flag first and falling back
+to the other on failure, since `session.id` is derived, not remembered (see
 [Driving the loop](#driving-the-loop) above) — and its embedded `.validate`
 script's output re-prompted verbatim on failure (the driver owns only the retry
 cap); and every landed turn executed — and reported — by the emitted scripts
@@ -771,6 +799,13 @@ normalizes `[ ]`/`[x]` checkboxes before comparing). If you plug in your own
 — ticking a box, stripping a paragraph — makes the guard's decision and the
 file's actual content disagree, and gtd will not catch that for you.
 
+One case never runs your `format:` (or `validate:`) at all: a step whose diff
+DELETES the state's own `file:`. Deleting it is a legitimate outcome — a review
+sign-off's whole diff is the review doc's deletion — and there is nothing left
+to format. Emitting the command anyway would make such a step unlandable, since
+`format:` is the first line of a `set -euo pipefail` script and a formatter like
+`prettier --write` exits non-zero on a path that is not there.
+
 ### Built-in steering formats are ordinary modes
 
 `qa` and `review` are gtd's two built-in steering-file formats (parsed and
@@ -1076,12 +1111,14 @@ the compiler's job at load time.
 - **Test/build artifacts must be gitignored.** This is **load-bearing**, not a
   style preference: every land decision detects "clean" via
   `git diff --name-status HEAD` (tracked changes) unioned with
-  `git ls-files --others --exclude-standard` (untracked files), which silently
-  omits anything matched by `.gitignore`. If a `script` state's command (or the
-  build it triggers) writes output — a `dist/`, a coverage report, a log file —
-  into the working tree, the tree never goes clean after a green run, and the
-  check's `"C"` pattern never fires. Gitignore every path your scripts write
-  before wiring gtd into a repo.
+  `git ls-files --others --exclude-standard` (untracked files, classified by
+  content against the base — one that is already there with the same bytes is
+  not a change, and a file that exists on disk is never reported as a deletion,
+  however the index sees it), which silently omits anything matched by
+  `.gitignore`. If a `script` state's command (or the build it triggers) writes
+  output — a `dist/`, a coverage report, a log file — into the working tree, the
+  tree never goes clean after a green run, and the check's `"C"` pattern never
+  fires. Gitignore every path your scripts write before wiring gtd into a repo.
 - **Repository root invocation.** Every state subcommand must run from the git
   repository root. `--help`/`--version` (and the `help`/`version` subcommands),
   `lsp`, `init`, `visualize`, `check`, and `install` skip this guard entirely

package/dist/gtd.bundle.mjs

@@ -192745,6 +192745,87 @@ const parseNameStatus = (out) => {
 	}
 	return result;
 };
+/** Split a `-z` git output into its entries, dropping the trailing empty one. */
+const splitNul = (out) => out.split("\0").filter((s) => s.length > 0);
+/**
+* `git ls-tree` the given paths at `ref` → `path → blob object id`; a path
+* absent from the map does not exist at `ref`. Pathspec-limited, so the cost
+* tracks the candidate list rather than the size of the tree. An unresolvable
+* `ref` (an empty repo has no `HEAD`) yields an empty map — every candidate
+* then reads as "not at `ref`", exactly the pre-`base` behaviour.
+*/
+const blobsAtRef = (exec, ref, paths) => exec("git", "ls-tree", "-r", "-z", ref, "--", ...paths).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")), map$4((out) => {
+	const blobs = /* @__PURE__ */ new Map();
+	for (const entry of splitNul(out)) {
+		const tab = entry.indexOf("	");
+		if (tab === -1) continue;
+		const [, type, oid] = entry.slice(0, tab).split(" ");
+		if (type === "blob" && oid !== void 0) blobs.set(entry.slice(tab + 1), oid);
+	}
+	return blobs;
+}));
+/**
+* `git hash-object` every path's CURRENT bytes in ONE call → `path → object id`
+* (git prints one id per path, in argument order). An empty map when the call
+* fails at all (an unreadable file): every candidate then reads as "differs",
+* which is the safe direction — a file that EXISTS must never be reported
+* deleted.
+*
+* These ids are directly comparable with the ones `git ls-tree` reports because
+* hash-object applies the repo's own CLEAN FILTERS, looking each file's
+* attributes up from its own path — so in a `text=auto`/`core.autocrlf` repo an
+* untouched CRLF working-tree file hashes to the same LF-normalized blob git
+* stored, and is correctly read as unchanged. Never add `--no-filters` (nor
+* `--path=<other>`) here: that would report every such file `M`, i.e. a
+* spurious "the human edited something real" (`StepGuards`'s `hasCodeChange`),
+* which walks the review-signoff guard past its unticked-box check, plus a
+* spurious change for any `on` pattern to match. Both tiers of the
+* `changedPaths` contract pin this (`src/testing/GitTiers.ts`).
+*
+* A symlink is the one residual inexactness: hash-object reads through it, so it
+* hashes the target's content rather than the link text git stores, and reads as
+* `M`. Still never `D`.
+*/
+const hashObjects = (exec, paths) => exec("git", "hash-object", "--", ...paths).pipe(map$4((out) => new Map(out.trim().split("\n").map((oid, i) => [paths[i] ?? "", oid.trim()]))), catchIf((e) => !isIndexLockError(e), () => succeed$3(/* @__PURE__ */ new Map())));
+/**
+* Classify every untracked path against `ref`'s tree, by CONTENT:
+*
+* - not at `ref` → `A`, an ordinary untracked addition
+* - at `ref` with different bytes → `M`
+* - at `ref` with identical bytes → no entry at all
+*
+* The last two exist because "untracked" does not mean "new": the review
+* checkout window's `git reset --mixed <base>` moves the index to the review
+* base, so every file the reviewed range ADDED is untracked while being
+* perfectly present (and usually unchanged) at the window's saved head. Read
+* from the worktree rather than the index, this is the same tree-vs-worktree
+* comparison the in-memory double has always done (`InMemRepo`'s
+* `changedPathsWorktree`) — production used to disagree with it here.
+*
+* "Different bytes" is decided the way GIT decides it — `hashObjects` hashes
+* through the repo's own clean filters, so a `text=auto` repo's untouched CRLF
+* file matches the LF blob it was stored as. Over-reporting `M` for an untouched
+* file would not be cosmetic: it is a spurious "the human edited something real"
+* (`StepGuards`'s `hasCodeChange`), which sends the review-signoff guard down
+* its it-is-a-comment branch and past the unticked-box check, plus a spurious
+* change for any `on` pattern to match.
+*/
+const classifyUntracked = (exec, ref, untrackedPaths) => gen(function* () {
+	const atRef = yield* blobsAtRef(exec, ref, untrackedPaths);
+	const candidates = untrackedPaths.filter((path) => atRef.has(path));
+	const onDisk = candidates.length === 0 ? /* @__PURE__ */ new Map() : yield* hashObjects(exec, candidates);
+	return untrackedPaths.flatMap((path) => {
+		const at = atRef.get(path);
+		if (at === void 0) return [{
+			path,
+			status: "A"
+		}];
+		return onDisk.get(path) === at ? [] : [{
+			path,
+			status: "M"
+		}];
+	});
+});
 /**
 * True when `error` is git's `index.lock` contention failure — another process
 * held the index lock when git tried to take it. gtd shares one worktree index
@@ -192811,17 +192892,17 @@ const makeGitImpl = (executor, root) => {
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
 		changedPathsSince: (ref) => exec("git", "diff", "--name-status", ref, "HEAD").pipe(map$4(parseNameStatus)),
 		changedPaths: (base) => gen(function* () {
-			const nameStatusOut = yield* exec("git", "diff", "--name-status", base ?? "HEAD").pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
+			const ref = base ?? "HEAD";
+			const nameStatusOut = yield* exec("git", "diff", "--name-status", ref).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
 			const trackedPaths = parseNameStatus(nameStatusOut);
-			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 untrackedRaw = yield* exec("git", "ls-files", "--others", "--exclude-standard", "-z");
+			const untrackedPaths = splitNul(untrackedRaw);
+			if (untrackedPaths.length === 0) return trackedPaths;
+			const untrackedChanges = yield* classifyUntracked(exec, ref, untrackedPaths);
+			const untrackedSet = new Set(untrackedPaths);
 			const seen = /* @__PURE__ */ new Set();
 			const all = [];
-			for (const entry of [...trackedPaths, ...untracked]) if (!seen.has(entry.path)) {
+			for (const entry of [...trackedPaths.filter((e) => !untrackedSet.has(e.path)), ...untrackedChanges]) if (!seen.has(entry.path)) {
 				seen.add(entry.path);
 				all.push(entry);
 			}
@@ -194595,6 +194676,7 @@ const restAt = (ref) => gen(function* () {
 		on,
 		stepDef,
 		changes,
+		windowHead,
 		memory,
 		memoryResumed,
 		hints,
@@ -195173,6 +195255,20 @@ const decideOpenWindow = (def, target, run, head) => {
 * 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.
+*
+* `".gtd"` stays a LITERAL, deliberately, rather than being derived from the
+* workflow's own `stateDir`/`file:` declarations. The pin exists to keep gtd's
+* PLUMBING out of the reviewer's editor, and `.gtd/` is the conventional
+* directory it lives in — including the parts no state declares (a check
+* script's temp output), which a `file:`-derived list would miss. A steering
+* file a workflow repoints outside it (`vars: { reviewFile: REVIEW.md }`)
+* simply stays untracked in the window, which is harmless: `changedPaths`
+* classifies untracked paths by content (`src/Git.ts`), so an unedited one is
+* not a pending change and never a phantom deletion. Making the list dynamic
+* would also cost the in-memory tier its trust property — the recognizer
+* (`src/testing/EmittedScriptRecognizer.ts`'s `recognizeReviewWindowOpen`)
+* re-derives this exact string and compares, which only works while the paths
+* are fixed. Don't trade that for cosmetics.
 */
 const buildOpenWindowScript = (decision) => [
 	updateRef(REVIEW_BASE_REF, decision.base),
@@ -206949,6 +207045,15 @@ const openInBrowser = (url) => {
 };
 //#endregion
 //#region src/StepGuards.ts
+/**
+* True when `changes` deletes `file` — the one question BOTH this registry's
+* `GuardContext.fileDeleted` and `program.ts`'s `steeringModeSteps` ask about a
+* state's `file:`, so they ask it in exactly one place. A deletion is a
+* legitimate step outcome at some states (a review sign-off's bare REVIEW.md
+* deletion) and a refusal at others (see `reviewSignoffGuard`), but either way
+* there is no file left to format or validate.
+*/
+const deletesFile = (changes, file) => changes.some((c) => c.path === file && c.status === "D");
 /** 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, "[_]");
 /** The `mode:` name of gtd's built-in REVIEW.md checkbox validator — the only mode the sign-off guard understands. */
@@ -207010,8 +207115,8 @@ const enforceStepGuards = (input) => gen(function* () {
 	if (file === void 0) return;
 	const applicable = stepGuards.filter((g) => g.appliesTo(input.rest));
 	if (applicable.length === 0) return;
-	const fileDeleted = input.changes.some((c) => c.path === file && c.status === "D");
-	const hasCodeChange = input.changes.some((c) => !c.path.startsWith(".gtd/"));
+	const fileDeleted = deletesFile(input.changes, file);
+	const hasCodeChange = input.changes.some((c) => !c.path.startsWith(".gtd/") && c.path !== file);
 	const base = {
 		rest: input.rest,
 		file,
@@ -207021,7 +207126,7 @@ const enforceStepGuards = (input) => gen(function* () {
 		template: input.context
 	};
 	const files = yield* RepoFiles;
-	const head = yield* cached(files.committed(file));
+	const head = yield* cached(files.committed(file, input.windowHead));
 	const worktree = yield* cached(try_(() => files.working(file)));
 	const ctx = {
 		...base,
@@ -207175,13 +207280,17 @@ gtd_land() {
   return 0
 }
 
+beat=1
 while :; do
   next="$(gtd next --json)" || exit 1
   kind="$(jq -r .kind <<<"$next")"
   log="$(jq -r .log <<<"$next")"
   case "$kind" in
     stalled) jq -r .content <<<"$next" >&2; exit 1 ;;
-    message) jq -r .content <<<"$next"; exit 0 ;;
+    # you re-ran us resting here: you either edited something or accepted by
+    # editing nothing, so land the opening beat either way. Later beats are
+    # gates we just produced and you have not read yet — hand off.
+    message) [ "$beat" = 1 ] || { jq -r .content <<<"$next"; exit 0; } ;;
     capture) ;; # the human already acted — just land it
     script) bash -c "$(jq -r .content <<<"$next")" >>"$log" 2>&1 || true ;;
     prompt)
@@ -207201,6 +207310,7 @@ while :; do
       done ;;
   esac
   gtd_land || exit 1
+  beat=$((beat + 1))
 done`;
 const HEADER = () => `gtd ${GTD_VERSION$1} — driver protocol\n\ngtd decides and prints; the driver executes. gtd never runs git, never runs\nyour agent, and never runs a check script. The one subprocess gtd ever spawns\nitself is a steering mode's own format:/validate: command, during a\nland-capture guard.\n`;
 const BEAT_PROTOCOL = `
@@ -207222,7 +207332,12 @@ The \`kind\` field selects what to do:
 
 - \`stalled\` — print \`.content\` (a diagnosis) to stderr and exit non-zero.
   Terminal: another dispatch would just repeat the same fruitless turn.
-- \`message\` — print \`.content\` and exit 0. This is a human gate.
+- \`message\` — print \`.content\` and exit 0. This is a human gate. EXCEPT on
+  the run's opening beat: the human invoked you while resting there, so land
+  it instead of printing. Some gates route a \`"C"\` (clean-tree) pattern
+  onward, making "change nothing" a real decision that looks identical to a
+  gate nobody has read yet; landing an opening beat at a gate without one is
+  a benign no-op, and it prints on the next beat.
 - \`capture\` — a human gate the human already acted on (the tree is dirty).
   Land it immediately, no display needed.
 - \`script\` — run \`bash -c .content\`, appending its output to \`.log\`, and
@@ -207289,7 +207404,9 @@ const DRIVER_OBLIGATIONS = `
    no opening move: a human's pending edit arrives as a \`kind: "capture"\`
    beat, which you land immediately without executing anything.
 2. A \`kind: "stalled"\` beat halts the driver with a non-zero exit; a
-   \`kind: "message"\` beat prints \`content\` and exits 0.
+   \`kind: "message"\` beat prints \`content\` and exits 0, unless it is the
+   run's opening beat — land that one, since the human's re-invocation while
+   resting there is itself their decision.
 3. Run scripts with their output appended to \`.log\` — gtd never creates or
    truncates that file itself; truncate it once per run. \`$GTD_LOOP_LOG\`
    overrides its path.
@@ -207444,11 +207561,22 @@ const headPreconditions = (currentCommit) => ({ expectedHead: currentCommit });
 * 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.
+*
+* Also empty when the step DELETES that file (`deletesFile`). A deletion is a
+* legitimate outcome at some states — `build.review.deciding`'s sign-off diff
+* is a bare REVIEW.md deletion — and there is nothing left to format or
+* validate either way. Emitting the mode's `format:` anyway made the step
+* UNLANDABLE for any formatter that treats a missing path as an error
+* (`prettier --write` exits non-zero with "No files matching the pattern were
+* found"): it is the first command in a `set -euo pipefail` script, so it
+* aborted the whole thing — window close, commit and all — before anything
+* could land, and a driver saw only a non-zero exit.
 */
 const steeringModeSteps = (rest) => gen(function* () {
 	const file = rest.hints.file;
 	const mode = rest.stateDef.mode;
 	if (file === void 0 || mode === void 0) return [];
+	if (deletesFile(rest.changes, file)) 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) => ({
@@ -207496,8 +207624,10 @@ const previewSubject = (decision, rest) => decision.kind === "commit" ? succeed$
 * (decision 6): there is nothing to format/validate in an empty diff, and a
 * `format:` command running ahead of the commit could dirty the tree and
 * turn an "empty" attempt non-empty, breaking the derivation `stalledAt`
-* relies on (`Edge.ts`). The review-window close still runs regardless —
-* committing with a window open would land the attempt on the review base.
+* relies on (`Edge.ts`). It is skipped for a step that DELETES the state's
+* own `file:` too — see `steeringModeSteps`. The review-window close still
+* runs regardless — committing with a window open would land the attempt on
+* the review base.
 */
 const buildRequiredScript = (rest, decision, cost, model) => gen(function* () {
 	const git = yield* GitService;
@@ -207559,6 +207689,7 @@ const planLanding = (opts = {}) => gen(function* () {
 		context: rest.context,
 		file: rest.hints.file,
 		changes: rest.changes,
+		windowHead: rest.windowHead,
 		kind: decision.kind,
 		attempt: isAttemptDecision(decision)
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "9.0.0",
+  "version": "9.1.1",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {