@pmelab/gtd 8.6.0 → 9.0.0

package/dist/gtd.bundle.mjs

@@ -4,12 +4,13 @@ const require = __createRequire(import.meta.url);
 import { createRequire } from "node:module";
 import { createServer } from "node:http";
 import * as Crypto from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as NFS from "node:fs";
 import { existsSync, readFileSync } from "node:fs";
 import * as OS from "node:os";
 import { homedir } from "node:os";
 import * as Path from "node:path";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import * as ChildProcess from "node:child_process";
 import { spawn } from "node:child_process";
 import * as NodeUrl from "node:url";
@@ -189824,7 +189825,7 @@ const STATE_FIELDS = {
 	* A STRING is a different shape entirely: an Eta template rendering a
 	* commitish. Entering that state fixes the WHOLE PROCESS's diff base to the
 	* rendered value (not a window anchor) — this is how a manual entry (e.g.
-	* `gtd step <actor> --entry review --base <commitish>`) pins what the rest
+	* `gtd --entry review --base <commitish>`) pins what the rest
 	* of the process diffs against. Rendering the template happens at the edge,
 	* not here — this module only carries the raw string and, per
 	* `isReviewBaseState`, a string value is NEVER treated as the `true`/
@@ -189884,7 +189885,7 @@ const STATE_FIELDS = {
 	},
 	/**
 	* Authoring-only: an EXTRA reachability root (`WorkflowEntries.manual`),
-	* enterable via `gtd step <actor> --entry <this state's qualified name>`.
+	* enterable via `gtd --entry <this state's qualified name>`.
 	* Never lands on the compiled `StateDef` — `compileState` validates its
 	* shape but discards the result; `compileWorkflowConfig` reads the RAW
 	* `entry: true` flag directly off each qualified state to build
@@ -189928,8 +189929,8 @@ const validateFieldRules = (name, state, key, spec) => {
 //#endregion
 //#region src/PatternMachine.ts
 /**
-* The v3 "pattern machine": gtd's ground-up rewrite of the state-machine
-* core. This module is the pure engine: definition types, the pattern grammar's
+* The pattern machine — gtd's state-machine core. This module is the pure
+* engine: definition types, the pattern grammar's
 * parser/matcher, HEAD resolution, and step decisions (refusals, no-ops,
 * commits, retry redirection, and the commit-state squash decision).
 *
@@ -189942,18 +189943,17 @@ const validateFieldRules = (name, state, key, spec) => {
 * commit states), and an optional `retry` cap. A `WorkflowDefinition`
 * separately declares `entries` — the state names a process may START at
 * (`default`, plus `manual` — every state declaring `entry: true`, enterable
-* via `gtd step <actor> --entry <state>`). A definition
+* via `gtd --entry <state>`). A definition
 * may also declare `modes:` —
 * named pairs of format/validate shell commands a state's `mode:` can point
 * at (see `ModeDef`); they are inert data here too, rendered and executed
 * only at the edge (`src/SteeringMode.ts`).
 *
 * This module is intentionally pure — no git, no filesystem, no Effect, no
-* IO of any kind. It mirrors the purity discipline documented at the top of
-* `./Subjects.ts` and `./Machine.ts`: every export here is a plain function
-* of its arguments. Rendering templates, executing scripts, walking git
-* history for the process trace, and performing the actual commit/squash
-* are all EDGE concerns for a later phase.
+* IO of any kind: every export is a plain function of its arguments.
+* Rendering templates (`src/PatternTemplates.ts`), walking git history for
+* the process trace (`src/Edge.ts`), and emitting the commit/squash scripts
+* a driver runs (`src/Edge.ts`/`src/Emit.ts`) are all EDGE concerns.
 *
 * Its one import is `./StateFields.js` — the state-field vocabulary
 * (`Actor`, `StateName`, `ContentKind`, `StateMode`, `OnEdge`, `RetryDef`,
@@ -190005,7 +190005,7 @@ const TRANSITION_SEP = " → ";
 * state being ENTERED and `<from>` the state the authored changes were made
 * in, so the subject reads as what this commit DID, not just where the machine
 * is headed. `from` is optional: when it is omitted or equals `to` (a
-* self-loop, or a manual entry like `gtd step <actor> --entry <state>` that
+* self-loop, or a manual entry like `gtd --entry <state>` that
 * has no meaningful source), the subject collapses to the bare
 * `gtd(<actor>): <to>` form.
 * `resolveState` reads back only `<to>` — the ` → ` prefix is human context.
@@ -190237,8 +190237,16 @@ const memoryScopeAt = (scopes, state, trace) => {
 * effect. Refusals: `invoker` isn't `state`'s declared actor (out-of-turn),
 * or the tree is dirty and no `on` pattern matches (no-match, naming the
 * declared patterns so the CLI can print them). A clean tree with no
-* matching pattern is a no-op (not a refusal) — the loop protocol's clean
-* steps are the default, silent case. A match's target is retry-redirected
+* matching pattern is a plain no-op at a `script`/`message` rest — the loop
+* protocol's clean steps are the default, silent case there — but at a
+* `prompt` rest it is an ATTEMPT instead: the state itself becomes the raw
+* target, so it falls through the same retry/commit-state tail as a real
+* match, tagged `attempt: true` on the resulting `"commit"` (never on a
+* `"squash"`, which a redirect straight into a commit state still produces
+* unchanged) — see `StepCommit.attempt`'s doc comment for why a fruitless
+* dispatch is committed at all, and `wouldAttempt` for the "would another
+* dispatch just repeat this" question a step itself doesn't need to ask. A
+* match's target (or an attempt's self-target) is retry-redirected
 * (`applyRetry`) before being classified: a commit-state target yields a
 * `"squash"` decision carrying its `commit` template verbatim; anything
 * else yields a `"commit"` decision naming the `gtd(<invoker>): <from> → <to>`
@@ -190260,20 +190268,23 @@ const step = (def, state, invoker, payload) => {
 		awaits: stateDef.actor
 	};
 	const onEdges = stateDef.on ?? [];
-	const rawTarget = matchOn(onEdges, payload.changes);
-	if (rawTarget === void 0) {
-		if (payload.changes.length === 0) return {
-			kind: "noop",
-			state
-		};
-		return {
+	let target = matchOn(onEdges, payload.changes);
+	let attempt = false;
+	if (target === void 0) {
+		if (payload.changes.length !== 0) return {
 			kind: "refusal",
 			reason: "no-match",
 			state,
 			patterns: onEdges.map(([pattern]) => pattern)
 		};
+		if (contentKindOf(stateDef) !== "prompt") return {
+			kind: "noop",
+			state
+		};
+		target = state;
+		attempt = true;
 	}
-	const finalTarget = applyRetry(def, rawTarget, payload.processTrace);
+	const finalTarget = applyRetry(def, target, payload.processTrace);
 	const targetDef = def.states[finalTarget];
 	if (targetDef === void 0) throw new Error(`step: "${state}" transitions to undefined state "${finalTarget}"`);
 	if (targetDef.commit !== void 0) return {
@@ -190287,10 +190298,32 @@ const step = (def, state, invoker, payload) => {
 		subject: stateSubject(invoker, finalTarget, state),
 		actor: invoker,
 		from: state,
-		to: finalTarget
+		to: finalTarget,
+		...attempt ? { attempt: true } : {}
 	};
 };
 /**
+* Would a clean step (an empty change set) at `state`, invoked by its own
+* declared actor, record ANOTHER attempt that stays AT `state` — "another
+* dispatch would just record another attempt" (see `Edge.ts`'s `stalledAt`,
+* the derived stall's other half). Runs `step` itself rather than
+* restating its retry-redirect precedence: a capped `retry` that would
+* redirect the attempt to `otherwise` (or squash it into a commit state)
+* makes this `false` — a further dispatch would actually escalate, not
+* repeat the same fruitless turn. `false` for an unknown/commit state, or
+* any state whose clean step is a signal (`C`) or a plain no-op
+* (`script`/`message`).
+*/
+const wouldAttempt = (def, state, processTrace) => {
+	const stateDef = def.states[state];
+	if (stateDef?.actor === void 0) return false;
+	const decision = step(def, state, stateDef.actor, {
+		changes: [],
+		processTrace
+	});
+	return decision.kind === "commit" && decision.attempt === true && decision.to === state;
+};
+/**
 * `entries.default` names a defined, non-commit state. Every entry in
 * `entries.manual`, when present, must likewise name a defined, non-commit
 * state distinct from `entries.default` — a manual entry is a DELIBERATE,
@@ -190402,8 +190435,8 @@ const validateRetry = (name, state, names) => {
 * `retry.otherwise` redirects (a redirect ENTERS its `otherwise` state exactly
 * like an `on` match enters its target — see `applyRetry` — so both are real
 * edges). The roots are `def.entries` — `default` PLUS every state named in
-* `entries.manual`: a manual entry is entered directly (`gtd step <actor>
-* --entry <state>`), so a state reachable only from one of them is
+* `entries.manual`: a manual entry is entered directly (`gtd --entry
+* <state>`), so a state reachable only from one of them is
 * legitimately reachable, not dead config (without seeding them, e.g. a
 * manual entry whose only inbound path is `--entry` would be wrongly
 * flagged). Plain BFS; targets naming undefined states are skipped here (they
@@ -191441,7 +191474,7 @@ const isSeededValidateCommand = (mode, command) => command === seededValidateCom
 *         label: <string>     # optional, opaque display name — never on a commit state
 *         file: <string>      # optional, an Eta template naming the state's steering file — never on a commit state
 *         mode: <modeName>    # optional, requires "file" — a built-in (qa/review) or a `modes:` entry; never on a commit state
-*         entry: true         # optional — an EXTRA reachability root (WorkflowEntries.manual), enterable via `gtd step <actor> --entry <this state's qualified name>`; distinct from the top-level `entry:` key above
+*         entry: true         # optional — an EXTRA reachability root (WorkflowEntries.manual), enterable via `gtd --entry <this state's qualified name>`; distinct from the top-level `entry:` key above
 *       <local>: { machine: <name>, with: { ... } }       # a REFERENCE — instantiates <name> as a child, see src/Machines.ts
 * ```
 *
@@ -192154,7 +192187,7 @@ const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true, f
 };
 //#endregion
 //#region src/workflows/unified.yaml
-var unified_default = "# The unified gtd workflow template — gtd's BUILT-IN DEFAULT workflow. When no\n# `workflow:` key is configured anywhere in the cwd→home config chain,\n# src/Config.ts runs this template directly, so a state command works with no\n# configuration at all. `gtd init` seeds only the settings a project tunes\n# (vars.testCommand + a modes: formatting suggestion), never the workflow\n# itself. See the README's \"How it works\" and \"Driving the loop\" sections for\n# the full walkthrough.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `renderInitConfig` (src/workflows/\n# templates.ts) can MATERIALIZE this raw source into a `.gtdrc.json`\n# `workflow:` value — the way to eject/customize the machine, and the hermetic\n# test fixture — but `gtd init` itself no longer writes the workflow.\n#\n# ── Authored with MACHINES (entry:/machines:) ───────────────────────────────\n#\n# This template is written as a tree of reusable, parameterized MACHINES (see\n# src/Machines.ts) — a gate/loop written once and instantiated several times\n# with different `with:` bindings (dedup), or a complex cluster grouped under\n# one name for source comprehension (encapsulation). Every reference below is\n# an ordinary `{ machine: <name>, with: { ... } }` local, expanded at\n# compile-time into concrete, qualified states before the pure engine ever\n# sees the definition — no runtime footprint.\n#\n# MACHINE BOUNDARIES LINE UP WITH CONVERSATIONAL IDENTITY: a machine that holds\n# an identity (a planner or a coder persona) declares its own `model:` ONCE, at\n# the machine level (stamped onto every one of its own `prompt` states — see\n# src/Machines.ts's `resolveInstanceModel`), instead of repeating `model:` on\n# every state; no state anywhere declares `model:` or `memory:` directly any\n# more (the memory key is computed from the machine tree — see\n# src/PatternMachine.ts's `memoryScopeAt` / src/Edge.ts's `memoryKeyFor`). Two\n# gate/queue machines below are deliberately IDENTITY-FREE (no `model:`):\n# `entryGate`/`healthGate` are infrastructure, not a persona, and `packageLoop`\n# is a bookkeeping queue, not a builder.\n#\n#   * entryGate (dedup ×3)    — the green-baseline gate (check + human blocked)\n#                               guarding the simple (`plan-gate`), advanced\n#                               (`spec-gate`) and review (`review-gate`)\n#                               entries. Identity-free.\n#   * healthGate (dedup ×2)   — the check/escalate health pair shared by the\n#                               simple build's own tail (`build.health.*`) and\n#                               the per-package build's own tail\n#                               (`packages.item.health.*`) — each caller's OWN\n#                               `fix` state (a coder-identity action) lives\n#                               beside this machine, not inside it, since\n#                               fixing IS a coder action and this machine has\n#                               no identity of its own. Identity-free.\n#   * advancedPlan (encap)    — the advanced flow's one design conversation:\n#                               product Q&A, technical Q&A, and decomposition\n#                               (`design.*`: product-author/-answer,\n#                               technical-author/-answer, decompose) all share\n#                               ONE machine identity, so the agent explores the\n#                               codebase once, not three times, and the human's\n#                               answer rationale survives into decomposition.\n#                               ▸ planner.\n#   * planLoop (encap)        — the simple flow's plan-iteration loop (`plan.*`).\n#                               ▸ planner.\n#   * humanReview (encap)     — the shared review tail, nested INSIDE\n#                               `simpleBuild` (`build.review.*`: reviewing →\n#                               await-review → deciding → collecting) — see\n#                               \"Why humanReview is nested, not a root sibling\"\n#                               below. ▸ planner — the implementer's OWN\n#                               follow-through on feedback is a coder action,\n#                               not a reviewer one, so it lives in\n#                               `build.addressing` instead.\n#   * specReview (encap)      — the advanced flow's per-package agentic review,\n#                               now a SINGLE state (`packages.item.spec.review`)\n#                               — a machine whose entire job is to be a\n#                               separate mind from the implementer. ▸ planner\n#                               — fixing the reviewer's own findings is a coder\n#                               action, so it lives in `packages.item.fix-spec`\n#                               instead.\n#   * packageLoop (encap)     — the advanced flow's per-package build queue\n#                               (`packages.picking`). Identity-free — the\n#                               actual per-package build identity lives in its\n#                               own `item` child (packageItem, below).\n#   * packageItem (encap)     — the advanced flow's per-package build identity\n#                               (`packages.item.*`: building, fix-suite,\n#                               fix-spec, closing), plus its own `health` and\n#                               `spec` children. ▸ coder.\n#   * simpleBuild (encap)     — the simple flow's build identity (`build.*`:\n#                               building, squashing, addressing, fix), plus its\n#                               own `health` child AND its own `review` child\n#                               (humanReview, above). ▸ coder.\n#\n# ── Why humanReview is nested, not a root sibling ───────────────────────────\n#\n# `humanReview` sits UNDER `simpleBuild` (`build.review`) rather than beside it\n# at the root, because a machine's memory scope is its dotted instance path\n# (see src/PatternMachine.ts's `memoryScopeAt`): entering a DESCENDANT scope\n# never breaks the parent's unbroken run, but entering a sibling does. The\n# review tail sits between the two coder turns that most need continuity —\n# `build.addressing` (follows through on review feedback) and `build.squashing`\n# (drafts the finale from the range this process built) — so hoisting it back\n# to a root sibling would force both of those turns to re-derive the feature\n# from scratch on every pass through the tail, instead of resuming the session\n# that built it. The reviewer itself is unaffected either way: `build.review.*`\n# is its own scope regardless of where it's nested, so it never resumes the\n# builder's session.\n#\n# ── Four entry points behind a green-baseline gate, one shared tail ─────────\n#\n# EVERY entry first runs the test suite and only proceeds when it is GREEN — you\n# never start new work (or a review) on top of a red baseline. A red run halts\n# at a human blocked gate (fix the failures and re-run, exactly like the\n# escalate states), or is what `gtd --entry fix-precheck` exists to repair.\n#\n# The initial `idle` state FORKS on which steering file the human creates,\n# routing into that flow's OWN start gate:\n#\n#   * the configured requirementsFile (default .gtd/REQUIREMENTS.md) ->\n#     `spec-gate.check` -> the ADVANCED flow (one design conversation across\n#     product + technical Q&A and decomposition, per-package parallel build +\n#     agentic spec-review).\n#   * anything else (e.g. the configured todoFile, default .gtd/TODO.md) ->\n#     `plan-gate.check` -> the SIMPLE flow (one grilling Q&A loop, a monolithic\n#     build, no decomposition, no agentic review).\n#\n# A third entry, `gtd --entry review-gate.check`, jumps there directly and,\n# once green, to `build.review.reviewing` to review a foreign branch through\n# the same shared tail. A fourth, `gtd --entry fix-precheck`, jumps there: a\n# red suite drops straight into the shared `build.fix` loop and out through the\n# review + squash tail; a green suite is a no-op back to `idle`. Both states\n# declare `entry: true` — otherwise unreachable from `entries.default`.\n#\n# All three converge at `build.review.reviewing` -> `build.review.await-review`.\n# Ticking a REVIEW.md box means only \"I reviewed this hunk\"; a COMMENT (not an\n# unticked box) is what asks for changes. Every human step at\n# `build.review.await-review` goes to `build.review.deciding`, which inspects\n# the step and routes:\n#   * no comment (every box ticked, no REVIEW.md note, no code edit) -> the diff\n#     is a bare REVIEW.md deletion -> build.squashing -> done (the ONLY path\n#     to the finale — the whole process collapses into one commit).\n#   * any comment — a note in REVIEW.md OR a hand-edit to code — ->\n#     build.review.deciding writes REVIEW_FEEDBACK.md -> build.review.collecting\n#     implements it (completing any code the human hand-edited, never\n#     reverting their lines) -> build.addressing (a coder action, not a\n#     reviewer one — see \"Why humanReview is nested\" above) -> back through\n#     `build.health.check` (the shared health pair, bound via the\n#     `$onFeedback`/local `review` reference) -> build.review.reviewing\n#     regenerates an INCREMENTAL REVIEW.md (build.review.deciding carries\n#     `reviewBase: true`, so each feedback round's review + checkout window\n#     covers only `last-review..HEAD`, i.e. the agent's follow-through, not the\n#     human's own edit) -> await-review, looping until sign-off.\n# Two dead ends never commit: the review-signoff guard (src/StepGuards.ts)\n# REFUSES a step that leaves a box unticked with no comment (finish reviewing\n# first) and a deleted REVIEW.md (restore it and tick the boxes).\n#\n# The shared health pair (`build.health.check`/`.escalate`, plus the caller's\n# own `build.fix`) serves the simple build and the feedback loop — its green\n# edge targets `build.review.reviewing`. The advanced per-package loop keeps\n# its OWN health pair (`packages.item.health.check`/`.escalate`, plus\n# `packages.item.fix-suite`) because its green edge targets the per-package\n# `packages.item.spec.review` gate instead.\n#\n# Every `on` pattern's path below is written as the matching var's Eta\n# template (e.g. `\"A <%= it.vars.feedbackFile %>\"`), not a literal `.gtd/...`\n# path — repointing a var reroutes the machine along with every template that\n# reads/writes it (see the README's \"Variables\" section).\n\nvars:\n  testCommand: npm test\n  # Where gtd keeps its own scratch/bookkeeping (the check scripts' temp output\n  # file, review-deciding's state-file exclusion). Independent of the per-file\n  # vars below — relocating a file wholesale means setting both.\n  stateDir: .gtd\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewRawFile: .gtd/REVIEW_RAW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_PLANNERMODEL` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/technical-qa/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n  # The fixed diff base for `gtd --entry review-gate.check --var\n  # reviewBase=<commitish>` — a plain non-gtd branch reviewed against that\n  # commitish rather than the process start. Declared here (rather than left\n  # undeclared) so `--var reviewBase=...` passes the CLI's declared-name\n  # check; the default empty string renders blank, which the entry command\n  # refuses (a review entry always requires an explicit base).\n  reviewBase: \"\"\n\n# `prose` is a format-only steering-file mode this workflow blesses for itself:\n# a curated free-form document with no gtd-side schema (the simple flow's plan\n# file, .gtd/TODO.md — see the `plan.planning` state below). An empty entry is\n# the format-only tier any workflow can declare for a name with no built-in\n# parser; `qa`/`review` need no entry here — src/PatternConfig.ts's compiler\n# seeds those two from the built-in registry (src/SteeringFormats.ts)\n# automatically.\nmodes:\n  prose: {}\n\nentry:\n  default: unified\n\nmachines:\n  # ── DEDUP: the green-baseline entry gate (identity-free) ──────────────────\n  # Runs the suite before any work starts (its script is the shared suite-check\n  # wrapper — red -> the configured feedbackFile, green -> remove it); the `on`\n  # rules turn that into \"halt at blocked\" vs \"proceed to $onGreen\". The script\n  # and blocked message/describe differ per entry, so they ride in as `with:`\n  # params. Kept SEPARATE from `healthGate` (below) even though both are a\n  # check+something-else shape: this gate runs BEFORE planning, so it must NOT\n  # sweep the plan/review steering files healthGate does — a human's fresh\n  # sketch legitimately still exists here.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # Anchored here and aliased by `fix-precheck` (`gtd --entry\n        # fix-precheck` entry): one suite-check script shared by all four\n        # call sites (this machine's ×3 instances plus `fix-precheck`)\n        # instead of four source copies. These gates run BEFORE planning, so\n        # — unlike `healthGate.check` — they must NOT sweep\n        # `todoFile`/`requirementsFile`: the human's fresh sketch still\n        # legitimately exists here.\n        # `entry: true` on the shared local marks all three `entryGate`\n        # instances (plan-gate/spec-gate/review-gate) as manual entries —\n        # only `review-gate.check` actually needs the reachability root (it\n        # is otherwise unreachable from `entries.default`), but the shared\n        # dedup makes marking one mark all three. Accepted as correct: all\n        # three ARE the workflow's entry gates.\n        entry: true\n        # `reviewBase: $reviewBase` — only `review-gate` binds a real\n        # template (`<%= it.vars.reviewBase %>`), fixing the whole process's\n        # diff base to whatever `gtd --entry review-gate.check --var\n        # reviewBase=<commitish>` supplies. `plan-gate`/`spec-gate` bind the\n        # literal empty string, which compiles away to \"no base\" here — they\n        # are reached from `idle`, never manually entered with a base.\n        reviewBase: $reviewBase\n        script: &suiteCheck |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n          # newline after an interpolation tag, so no tag may be the last token on\n          # a line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": blocked\n          \"M <%= it.vars.feedbackFile %>\": blocked\n          \"D <%= it.vars.feedbackFile %>\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: <%= it.vars.feedbackFile %>\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # ── DEDUP: the check/escalate health pair (identity-free) ─────────────────\n  # Runs the suite; a red run records the configured feedbackFile and routes to\n  # the caller's OWN fixer (`$onRed` — a coder-identity action that lives\n  # beside this machine, not inside it, since fixing IS a coder action and this\n  # machine has no identity); a green run cleans it up and routes to\n  # `$onGreen`. Escalation redirects here after the caller's fixer has retried\n  # `max` times without success. Instantiated for the simple build's own tail\n  # (`build.health.*`, caller's fixer is `build.fix`) and the per-package\n  # build's own tail (`packages.item.health.*`, caller's fixer is\n  # `packages.item.fix-suite`).\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # This script ALSO sweeps spent steering files (`todoFile`,\n        # `reviewRawFile`, `reviewFeedbackFile`) — a mechanic `entryGate.check`\n        # must NOT run, since it executes before planning, while a fresh\n        # sketch legitimately still exists.\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist every path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a\n          # line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          # Sweep steering files spent by the states that led here: the plan\n          # (building), the raw review capture (review.collecting), and the\n          # feedback instructions (build.addressing) — each `rm -f` is a\n          # no-op when the file is already gone or never existed on this path.\n          todo=\"<%~ it.vars.todoFile %>\"\n          reviewRaw=\"<%~ it.vars.reviewRawFile %>\"\n          reviewFeedback=\"<%~ it.vars.reviewFeedbackFile %>\"\n          rm -f \"$todo\" \"$reviewRaw\" \"$reviewFeedback\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": $onRed\n          \"M <%= it.vars.feedbackFile %>\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: <%= it.vars.feedbackFile %>\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $escalateDescribe\n\n  # ── ENCAPSULATION: the advanced flow's design conversation ─────────────────\n  # One planner identity across product Q&A -> technical Q&A -> decomposition:\n  # a single codebase exploration instead of three, and the human's answer\n  # rationale survives from product into technical and into decomposition (all\n  # five states share one memory scope, `design`). Replaces the former\n  # `qaLoop ×2` (which split one design conversation into two minds that each\n  # re-explored the codebase) plus `simpleBuild`'s own `decompose` (which\n  # landed on the coder tier only because it happened to live in the build\n  # machine — decomposition is judgement-heavy planning work, not building).\n  # ▸ planner identity — `model:` declared once here, stamped onto\n  # `product-author`, `technical-author`, and `decompose` (its own prompt\n  # states; the `*-answer` states are human turns and carry no prompt).\n  advancedPlan:\n    model: <%= it.vars.plannerModel %>\n    params: [onPackages]\n    entry: product-author\n    states:\n      product-author:\n        actor: agent\n        label: Refining the product plan\n        file: <%= it.vars.requirementsFile %>\n        mode: qa\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this turn\n          touches is `<%= it.vars.requirementsFile %>`; develop it. Do not\n          create other files to hold notes or output.\n\n          `<%= it.vars.requirementsFile %>` holds the product requirements (or the\n          plan you already wrote plus the human's answers on a return lap). Read it,\n          explore the codebase, and develop it into a concrete, PRODUCT-level plan\n          in this one turn.\n\n          Scope: product and user-facing decisions only. Leave implementation\n          details (file/module structure, data models, tech-stack choices) for the\n          next phase (`<%= it.vars.architectureFile %>`).\n\n          For every open point you cannot settle yourself, add a question under a\n          `## Open Questions` heading near the top: one `### <question>` sub-heading\n          each, followed by a checkbox list of candidate answers — aim for TWO\n          concrete options plus a final free-text slot, ALL left UNTICKED:\n\n              ### <the question>\n\n              - [ ] <first option — a concrete answer, a few words of rationale>\n              - [ ] <second option>\n              - [ ] _your answer_\n\n          Never tick a box yourself — the human ticks exactly one per question. The\n          last `- [ ] _your answer_` line is the human's own-answer slot; write it\n          with the literal `_your answer_` placeholder and leave it for them.\n\n          On a RETURN lap the human has ticked one option per question (or replaced\n          `_your answer_` with their own text). For each answered question: fold the\n          chosen answer into the plan prose, then MOVE the question down into a\n          `## Answered Questions` section as `### <question>` followed by the\n          resolved answer in plain PROSE (drop the checkboxes). Never re-raise a\n          question the human deleted; if the human deleted the whole\n          `## Open Questions` section, treat the plan as accepted and surface no new\n          questions unless something is genuinely still blocking. Omit\n          `## Open Questions` entirely once there are none left.\n\n          Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": product-answer\n\n      product-answer:\n        actor: human\n        label: Awaiting your answers\n        file: <%= it.vars.requirementsFile %>\n        mode: qa\n        answerGate: true\n        message: |\n          `<%= it.vars.requirementsFile %>` holds the product plan under\n          development. Each question under `## Open Questions` offers a few options\n          plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n          exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n          with your text and tick that line. Stepping is refused while any question\n          is unanswered.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: technical-author\n            action: Accept answers\n            describe: >-\n              with no open questions left (the agent surfaced none, or you deleted\n              the section and it finalized the plan), change nothing to move on to\n              technical Q&A (**design.technical-author**).\n          \"* **\":\n            to: product-author\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace `_your answer_` for\n              your own) to send the plan back for the agent to fold your answers in\n              (**design.product-author**). Delete a question to skip it, or delete the whole\n              `## Open Questions` section to accept the plan as-is.\n\n      technical-author:\n        actor: agent\n        label: Refining the technical plan\n        file: <%= it.vars.architectureFile %>\n        mode: qa\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.architectureFile %>` (write it) and\n          `<%= it.vars.requirementsFile %>` (delete it once its content is\n          folded in). Do not create other files to hold notes or output.\n\n          If you developed those requirements earlier in this conversation, work\n          from what you already settled; otherwise read\n          `<%= it.vars.requirementsFile %>` (the converged product plan) yourself.\n          Develop `<%= it.vars.architectureFile %>` from it in this one turn:\n          file/module structure, data models, library/tech-stack choices,\n          error-handling strategy — the *how*, building on the *what* already\n          settled. Do not re-open product-level decisions; treat them as settled.\n\n          For every open point you cannot settle yourself, add a question under a\n          `## Open Questions` heading exactly as the grilling phase does: one\n          `### <question>` each, followed by a checkbox list — TWO concrete options\n          plus a final free-text slot, ALL left UNTICKED:\n\n              ### <the question>\n\n              - [ ] <first option>\n              - [ ] <second option>\n              - [ ] _your answer_\n\n          Never tick a box yourself. On a RETURN lap the human has ticked one option\n          per question (or replaced `_your answer_` with their own text): fold each\n          chosen answer into the plan prose, then MOVE the question into a\n          `## Answered Questions` section as `### <question>` + the resolved answer\n          in plain PROSE (drop the checkboxes). Never re-raise a deleted question;\n          treat a deleted `## Open Questions` section as acceptance. Omit\n          `## Open Questions` once there are none left.\n\n          Once `<%= it.vars.architectureFile %>` is written, delete\n          `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n          must not linger. Leave everything uncommitted and finish your turn.\n        on:\n          \"* **\": technical-answer\n\n      technical-answer:\n        actor: human\n        label: Awaiting your answers\n        file: <%= it.vars.architectureFile %>\n        mode: qa\n        answerGate: true\n        message: |\n          `<%= it.vars.architectureFile %>` holds the technical plan under\n          development. Each question under `## Open Questions` offers a few options\n          plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n          exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n          with your text and tick that line. Stepping is refused while any question\n          is unanswered.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: decompose\n            action: Accept answers\n            describe: >-\n              with no open questions left (the agent surfaced none, or you deleted\n              the section and it finalized the plan), change nothing to move on to\n              decomposing the work into packages (**design.decompose**).\n          \"* **\":\n            to: technical-author\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace `_your answer_` for\n              your own) to send the plan back for the agent to fold your answers in\n              (**design.technical-author**). Delete a question to skip it, or delete the whole\n              `## Open Questions` section to accept the plan as-is.\n\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself through\n          its own state files — treat them as its private scratchpad, never as\n          project code or documentation. The only state files this turn touches\n          are the package files it writes under `<%= it.vars.packagesDir %>/` and\n          `<%= it.vars.architectureFile %>`, which it deletes. Do not create other\n          files to hold notes or output.\n\n          If you wrote `<%= it.vars.architectureFile %>` earlier in this\n          conversation, work from what you already settled; otherwise read it\n          (the converged technical plan) yourself. Decompose it into an ordered\n          set of WORK PACKAGES, one file each under\n          `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n          `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n          test suite can pass again after each one lands.\n\n          Each package file describes a set of INDEPENDENT tasks that can be\n          implemented concurrently without ordering constraints between them — a\n          single build turn will fan them out to parallel subagents. Give each task\n          a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n          relevant paths. Also state the package's overall requirement so it can be\n          reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n          package — split them across ordered packages instead.\n\n          No package file may reference any other `.gtd/` file. Once the package\n          files are written, delete `<%= it.vars.architectureFile %>`. Leave\n          everything uncommitted and finish your turn.\n        on:\n          \"* <%= it.vars.packagesDir %>/**\": $onPackages\n\n  # ── ENCAPSULATION: the simple flow's plan-iteration loop ───────────────────\n  # ▸ planner identity — `model:` declared once here, stamped onto `planning`\n  # (its only prompt state).\n  planLoop:\n    model: <%= it.vars.plannerModel %>\n    params: [onAccept]\n    entry: planning\n    states:\n      planning:\n        actor: agent\n        label: Refining the plan\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.todoFile %>`; develop it into the plan.\n          Do not create other files to hold notes or output.\n\n          `<%= it.vars.todoFile %>` holds a short sketch of what to build — or, on a\n          return lap, the plan you already wrote plus the human's edits and comments\n          on it. Read it, explore the codebase, and develop it into a concrete\n          implementation plan: the files to change, the approach, and the steps to\n          take.\n\n          Do NOT ask questions and do NOT add an \"Open Questions\" section — decide\n          every open point yourself and write the plan as a set of concrete\n          decisions. Where a decision is genuinely a judgement call, state the\n          choice you made and, in one line, why. The human iterates on the plan by\n          editing it directly, not by answering questions.\n\n          On a return lap, `<%= it.vars.todoFile %>` carries the human's edits and\n          inline comments on your previous plan. If you wrote that plan earlier in\n          this conversation, work from what you already know plus these edits;\n          otherwise read the file fresh. Fold every edit and comment into a\n          revised, self-contained plan and remove the addressed comments — the plan\n          is always the current, clean proposal, never a diff.\n\n          Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n          not commit, and do not run `gtd step agent` yourself; the harness does\n          that.\n        on:\n          \"* **\": await-plan\n\n      await-plan:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        message: |\n          `<%= it.vars.todoFile %>` holds the proposed implementation plan. Read it,\n          then either accept it as-is or edit it — rewrite a step, add a\n          constraint, or drop an inline comment — to send it back for another round.\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: $onAccept\n            action: Accept plan\n            describe: >-\n              change nothing to move on to implementation (**build.building**).\n          \"* **\":\n            to: planning\n            action: Revise plan\n            describe: >-\n              rewrite a step, add a constraint, or leave an inline comment to\n              send it back for another round (**plan.planning**).\n\n  # ── ENCAPSULATION: the shared review tail ──────────────────────────────────\n  # ▸ planner identity — `model:` declared once here, stamped onto `reviewing`\n  # and `collecting` (its only prompt states). The implementer's OWN\n  # follow-through on feedback is a coder action, not a reviewer one — it\n  # lives in `build.addressing` (`$onFeedback`), not inside this machine.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # `gtd --entry review-gate.check` (a plain non-gtd branch, e.g. a\n        # colleague's PR) does NOT enter here directly — it enters\n        # `review-gate.check` first, which runs the green-baseline gate and,\n        # once green, transitions here. The `Gtd-Review-Base:` trailer rides on that\n        # entry commit (the process's oldest), so everything below still reuses\n        # the same reviewing/await-review/feedback machinery over <commitish>..HEAD.\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.reviewFile %>`; write it at exactly\n          that path. Do not create other files to hold notes or output.\n\n          Write `<%= it.vars.reviewFile %>` to help a human review the changes in\n          this EXACT format:\n\n          - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n          - Somewhere in the document: `<!-- base: <%= it.reviewBase %> -->`\n          - At least one `## <Chunk Title>` heading, grouping hunks semantically\n            (same feature/refactor/fix, even across files) — a short explanation of\n            what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n            pointer per hunk (checkboxes are for the human to tick, not you; every\n            path is `./`-relative, with an optional `#line` and an optional\n            ` — note`).\n\n          This prompt carries no diff — read the changes yourself. The range runs\n          from `<%= it.reviewBase %>` to the working tree (committed turns plus\n          anything still pending); on a feedback round that base is the previous\n          review's boundary, so it covers only what changed since then, not items\n          already signed off.\n\n          Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # While the process rests here, gtd opens a \"review checkout window\": raw HEAD\n        # is rewound to the review base (the most-recent `deciding` commit — so a\n        # feedback round shows only `last-review..HEAD` — or the process start on\n        # the first review) with the working tree untouched, surfacing the diff\n        # as ordinary uncommitted changes. It closes on the next invocation.\n        #\n        # Every human step here routes to `deciding`, which decides sign-off vs.\n        # feedback from the step's CONTENT (a comment, not a tick). Ticking a box\n        # only records \"I reviewed this hunk\". Two dead ends can't be told apart by a\n        # file-pattern edge, so the review-signoff guard (`src/StepGuards.ts`)\n        # catches them BEFORE the step commits and refuses: an unfinished\n        # review (a box still `- [ ]` with no comment) and a deleted REVIEW.md.\n        reviewWindow: true\n        message: |\n          `<%= it.vars.reviewFile %>` holds the review record for the process — one\n          `- [ ]` checkbox per reviewable item, grouped into chunks. Tick a box\n          (`- [x]`) as you review each hunk; ticking only records that you've read\n          it, it is not sign-off.\n\n          When you've been through the whole diff, run `gtd step human`:\n\n          - **Sign off** — tick EVERY box and leave no comment — no note in\n            `<%= it.vars.reviewFile %>`, no code edit — to collapse the process into\n            one commit (**build.squashing**).\n          - **Request changes** — leave a comment: a note on a\n            `<%= it.vars.reviewFile %>` line, or a direct code edit — to send it to a\n            build + re-review round (**review.deciding** → **build.addressing**). A\n            code edit counts as your own fix: the agent completes the follow-through\n            it implies and never reverts your lines.\n\n          Stepping with a box still unticked and no comment is refused (finish\n          reviewing first); so is deleting `<%= it.vars.reviewFile %>`.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n        # the point the previous review round ended, so the next `reviewing` turn\n        # (and the review checkout window) covers only the changes since then. On\n        # the first review there is no such commit, so the base is the process start.\n        reviewBase: true\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — decide the human's review step from its CONTENT. HEAD is\n          # the human's `await-review -> deciding` commit; HEAD^ is the `reviewing`\n          # commit that wrote the agent's original REVIEW.md (the sign-off gate\n          # refuses an incomplete step, so `deciding` is entered exactly once per\n          # round — nothing commits in between). It is FEEDBACK when the human left\n          # a comment: a note in REVIEW.md (any edit beyond a \"[ ]\"->\"[x]\" tick) OR a\n          # hand-edit to any file this round other than `.gtd/` or the state's own\n          # reviewFile (which is var-configurable and may live outside `.gtd/`, e.g.\n          # a root-level REVIEW.md — issue #128). Otherwise it is a clean sign-off.\n          # This turn only CAPTURES the raw material into REVIEW_RAW.md (the\n          # `collecting` agent then turns it into instructions); it does NOT\n          # interpret it. Either way, remove REVIEW.md; what the resulting diff\n          # MEANS is decided by this state's own `on` rules — the A/M REVIEW_RAW.md\n          # rows are declared BEFORE the D REVIEW.md row so a feedback round (which\n          # also deletes REVIEW.md) is captured as feedback, not mistaken for a\n          # sign-off.\n          set +e\n          # Hoist the paths once, at the TOP: Eta's autoTrim eats the newline after\n          # an interpolation tag, so no tag may be the last token on a line — it\n          # would glue the next line onto it and break the script. Below this point\n          # everything is plain bash.\n          stateDir=\"<%~ it.vars.stateDir %>\"\n          reviewFile=\"<%~ it.vars.reviewFile %>\"\n          reviewRawFile=\"<%~ it.vars.reviewRawFile %>\"\n          head=$(git rev-parse HEAD)\n          mkdir -p \"$(dirname \"$reviewRawFile\")\"\n          # A note is any REVIEW.md change beyond a checkbox flip: normalize every\n          # \"[ ]\"/\"[x]\" to a placeholder, then compare the agent's original (HEAD^)\n          # against the human's version (HEAD).\n          before=$(git show \"HEAD^:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          after=$(git show \"HEAD:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          # Did the human hand-edit anything this round besides stateDir and the\n          # reviewFile itself (var-configurable — may live outside stateDir, so it\n          # is excluded by exact path, not just the stateDir prefix)?\n          if git diff-tree --no-commit-id --name-only -r HEAD \\\n               | grep -v \"^$stateDir/\" | grep -vxF \"$reviewFile\" | grep -q . \\\n             || [ \"$before\" != \"$after\" ]; then\n            {\n              echo \"Raw review material captured for classification. The human reviewed the changes and left the feedback below; a downstream agent turns it into an instruction list. This file is machine-captured input, not instructions — it names a commit, never inlined content.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in $reviewFile at this commit; their hand edits,\"\n              echo \"if any, are in that commit's other paths. Run: git show $head\"\n            } > \"$reviewRawFile\"\n          fi\n          rm -f \"$reviewFile\"\n        on:\n          \"A <%= it.vars.reviewRawFile %>\": collecting\n          \"M <%= it.vars.reviewRawFile %>\": collecting\n          \"D <%= it.vars.reviewFile %>\": $onSignoff\n\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        prompt: |\n          You are an autonomous coding agent turning raw review feedback into an\n          explicit instruction list for a builder. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.reviewRawFile %>` (read it, then\n          delete it) and `<%= it.vars.reviewFeedbackFile %>` (write it) — do\n          NOT change any other file, you classify, you do not build.\n\n          The raw review material is: <%~ it.read(it.vars.reviewRawFile) %>\n\n          It names a commit. If you wrote today's review earlier in this\n          conversation, work from what you already reviewed; otherwise read that\n          commit's diff yourself before classifying anything.\n\n          Classify every piece of it into `<%= it.vars.reviewFeedbackFile %>` as a\n          flat, numbered instruction list. Each item is `N. ./path/to/file.ts#line —\n          <imperative>`. Apply these rules exactly:\n\n          1. NOTES the human added to REVIEW.md — each note is a MANDATORY change,\n             regardless of whether its checkbox is ticked (ticking means only \"I read\n             this hunk\", never sign-off). Anchor each to the `./path#line` its review\n             item names (or the chunk it sits under). Emit it as a concrete\n             imperative.\n          2. Every COMMENT the human ADDED this round (a `+` line that is a code\n             comment, in the hand-edited files) is a MANDATORY instruction the human\n             is giving the builder — even a plain-prose one, even if its box is\n             ticked. Emit an imperative to satisfy it and note that the comment line\n             itself must be REMOVED once addressed. If a comment turns out to describe\n             behaviour the code already has, the instruction is still \"confirm the\n             code matches and remove the comment line\".\n          3. Every NON-comment code line the human hand-edited is an already-committed\n             INTENT, NOT a do-then-delete item. Emit an instruction that names those\n             files and says: their lines are final — complete ONLY the follow-through\n             they imply (callers, tests, types, docs) and NEVER revert or rewrite\n             them. Do not turn their own edit into a task.\n\n          Split each hand-edited hunk per line: comment `+` lines follow rule 2, the\n          surrounding real code follows rule 3.\n\n          If — and only if — nothing in the raw material is actionable (e.g. the human\n          left only an approving remark), write `<%= it.vars.reviewFeedbackFile %>`\n          containing exactly one line: `NOTHING ACTIONABLE — <one-sentence reason>`.\n          Never invent work to satisfy a non-actionable remark.\n\n          Delete `<%= it.vars.reviewRawFile %>`, leave everything else uncommitted,\n          and finish your turn.\n        on:\n          \"A <%= it.vars.reviewFeedbackFile %>\": $onFeedback\n          \"M <%= it.vars.reviewFeedbackFile %>\": $onFeedback\n\n  # ── ENCAPSULATION: the advanced flow's per-package agentic review ──────────\n  # A single state: a machine whose entire job is to be a separate MIND from\n  # the implementer, distinct from the coder identity that builds/fixes the\n  # package (`packages.item.*`). ▸ planner identity — `model:` declared once\n  # here, stamped onto `review` (its only prompt state). Fixing the reviewer's\n  # own findings is a coder action, not a reviewer one — it lives in\n  # `packages.item.fix-spec` (`$onFix`), not inside this machine.\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # Bounded per process: once entered `max` times, a transition into it is\n        # redirected to `$onApproved` (force-close the package and move on — the\n        # unresolved concern is deferred to the shared human review at the tail,\n        # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n        # pools across packages — the same documented limitation the shared\n        # `build.fix` cap has (see the README's \"Why\" section, \"Bounded, not\n        # runaway\").\n        retry:\n          max: 3\n          otherwise: $onApproved\n        prompt: |\n          You are an autonomous coding agent reviewing a freshly-built work package\n          against its own spec. This workflow steers itself through its own\n          state files — treat them as its private scratchpad, never as project\n          code or documentation. The only state file this turn touches is\n          `<%= it.vars.specFeedbackFile %>`; write it only when — and only\n          when — you find problems. Do not create other files to hold notes or\n          output.\n\n          The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n          Read that spec, then verify the package's implementation against it: are\n          all its tasks done, acceptance criteria met, and the code sound and\n          consistent with the codebase? This prompt carries no diff — read it\n          yourself: the range runs from `<%= it.startCommit %>` to the working\n          tree.\n\n          Note the range is process-wide (from the start of the whole build, not\n          just this package), so it can span earlier packages too.\n\n          - If it fully satisfies the spec, write NOTHING and finish your turn — a\n            clean turn is your approval.\n          - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n            concrete problems for a fix turn to address. Be specific.\n\n          Do not fix anything yourself and do not delete the package file — a later\n          step owns that. Finish your turn.\n        on:\n          \"A <%= it.vars.specFeedbackFile %>\": $onFix\n          \"M <%= it.vars.specFeedbackFile %>\": $onFix\n          \"D <%= it.vars.specFeedbackFile %>\": $onApproved\n          \"C\": $onApproved\n\n  # ── ENCAPSULATION: the advanced flow's per-package build queue ─────────────\n  # Identity-free (a bookkeeping queue, not a builder) — the actual per-package\n  # build identity lives in its own `item` child (packageItem, below).\n  packageLoop:\n    params: [onDrained]\n    entry: picking\n    states:\n      picking:\n        actor: check\n        label: Picking the next package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package queue arbiter) — the loop driver executes\n          # this verbatim, then steps the check actor. Mechanics only: take the\n          # first package file (by name) under the packages dir into NEXT.md, or\n          # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n          # MEANS (another package to build vs. the queue closing out to review) is\n          # decided by this state's own `on` rules at capture time — never here.\n          set +e\n          # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a line —\n          # it would glue the next line's `else`/`fi` onto it and break the script.\n          # Below this point everything is plain bash.\n          nextFile=\"<%~ it.vars.nextFile %>\"\n          # Sweep the advanced flow's spent Q&A steering files: requirementsFile\n          # is consumed by technical-qa, architectureFile by decompose — both are\n          # gone by the time the package queue starts. No-op if already removed.\n          requirements=\"<%~ it.vars.requirementsFile %>\"\n          architecture=\"<%~ it.vars.architectureFile %>\"\n          rm -f \"$requirements\" \"$architecture\"\n          next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            mkdir -p \"$(dirname \"$nextFile\")\"\n            printf '%s' \"$next\" > \"$nextFile\"\n          else\n            rm -f \"$nextFile\"\n          fi\n        on:\n          \"D <%= it.vars.nextFile %>\": $onDrained\n          \"* <%= it.vars.nextFile %>\": item.building\n          \"C\": $onDrained\n\n      # The per-package build identity — its own coder machine (below), so\n      # deleting a package file's own lifecycle stays inside `item` while the\n      # queue itself (`packages`) stays a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # ── ENCAPSULATION: the advanced flow's per-package build identity ──────────\n  # ▸ coder identity — `model:` declared once here, stamped onto `building`,\n  # `fix-suite`, and `fix-spec` (its own prompt states). `closing` ends that\n  # package file's own lifecycle; keeping it here (not in the queue) keeps\n  # `packages` itself to a single state. `packages.item.closing` -> `picking`\n  # is the ONE upward-resolving target in the whole file, so it MUST be a\n  # param (`$onNext`, bound by `packages` — see the machine's own reference).\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. This turn writes no state\n          file: do NOT delete the package file (the spec-review gate reads\n          it after you) and never touch `<%= it.vars.nextFile %>` — the\n          `picking` state owns it.\n\n          The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n          That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n          this one turn, fanning the independent tasks out to parallel subagents\n          where your harness supports it — each task is self-contained and can be\n          built concurrently. Implement EXACTLY the tasks this package describes — no\n          more, no less; leave every other package file untouched. Use TDD\n          discipline within each task.\n\n          Leave the package file in place and everything else uncommitted, then\n          finish your turn.\n        on:\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: <%= it.vars.feedbackFile %>\n        prompt: &suiteFixPrompt |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.feedbackFile %>`; fix it per its\n          contents, or delete it if the feedback turns out to be wrong. Do not\n          create other files to hold notes or output.\n\n          Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n          code so the suite passes. Keep the change focused — do not refactor\n          unrelated code. If the feedback is wrong, empty or delete\n          `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n          Leave everything uncommitted and finish your turn — do not commit.\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\n      fix-spec:\n        actor: agent\n        label: Fixing review feedback\n        file: <%= it.vars.specFeedbackFile %>\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.specFeedbackFile %>`; address it, then\n          delete it. Do not create other files to hold notes or output.\n\n          Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n          current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n          then fix the code to resolve every concern. Keep the change focused.\n\n          Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n          Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": health.check\n\n      closing:\n        actor: check\n        label: Closing out the package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package closer) — remove the just-reviewed package\n          # file (its path is in NEXT.md) plus any leftover spec feedback, so\n          # `picking` selects the NEXT package (or falls through to review when the\n          # queue is empty). Reached on approval (spec review clean) and on the\n          # spec review retry cap (force-close, deferring the concern to the tail).\n          set +e\n          pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n        on:\n          \"* **\": $onNext\n\n      # Per-package health pair: packages.item.health.check/.escalate ->\n      # packages.item.spec.review (green) or packages.item.fix-suite (red).\n      health:\n        machine: healthGate\n        with:\n          onGreen: spec\n          onRed: fix-suite\n          escalateDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` yourself\n            (**packages.item.health.check**).\n          checkLabel: Running checks\n          escalateLabel: Escalating to a human\n\n      # Per-package agentic review: packages.item.spec.review -> closing\n      # (approved), or packages.item.fix-spec (findings — re-verify via the\n      # full health check before re-reviewing).\n      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # ── ENCAPSULATION: the simple flow's build identity ────────────────────────\n  # ▸ coder identity — `model:` declared once here, stamped onto `building`,\n  # `squashing`, `addressing`, and `fix` (its own prompt states). Decomposition\n  # (`design.decompose`) belongs to the planner tier now, not here — see\n  # `advancedPlan` below. `addressing` is the implementer's OWN follow-through\n  # on review feedback (a coder action) — reached via `$onFeedback`, bound at\n  # its own `review:` reference below, not nested inside the (planner-only)\n  # `humanReview` machine. `humanReview` is nested HERE (not at the root) so\n  # the review tail's run stays inside the builder's own scope — see the\n  # header comment.\n  simpleBuild:\n    model: <%= it.vars.coderModel %>\n    params: [onDone]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        file: <%= it.vars.todoFile %>\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself through\n          its own state files — treat them as its private scratchpad, never as\n          project code or documentation. The only state file this turn touches is\n          `<%= it.vars.todoFile %>`; delete it once its work is complete. Do not\n          create other files to hold notes or output.\n\n          The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n          Read that plan and implement it in full. Use TDD discipline: one test,\n          then the implementation that passes it, then the next — never write all\n          the tests first.\n\n          Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n          and verified. Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": health.check\n\n      squashing:\n        actor: agent\n        label: Squashing\n        file: <%= it.vars.commitMsgFile %>\n        prompt: |\n          You are an autonomous coding agent. The process is approved and done. This\n          workflow steers itself through its own state files — treat them as its\n          private scratchpad, never as project code or documentation. The only\n          state file this turn touches is `<%= it.vars.commitMsgFile %>`; write\n          it. Do not create other files to hold notes or output.\n\n          Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n          entering this file squashes everything this process retains into one\n          commit using its content as the message. This prompt carries no diff —\n          if you built that range yourself earlier in this conversation, work from\n          what you already know; otherwise read the range yourself. It runs from\n          `<%= it.retainedBase %>` to the working tree, and is exactly what that\n          commit will contain, the changes THIS process made (its trace/retry\n          boundary onward). For a normal build\n          process that is the whole feature; for a `gtd --entry review-gate.check`\n          process it is only the fixes made during the review — NOT the changeset\n          that was under review.\n\n          If that range is non-empty, write `<%= it.vars.commitMsgFile %>` with ONE\n          conventional-commits message for the changes (subject line\n          `type(scope): subject`, imperative mood, <= 72 characters; a body\n          explaining the why, trade-offs, and key decisions). Plain text, no\n          markdown wrapper.\n\n          If that range is empty (a clean review sign-off with no fixes), write\n          `<%= it.vars.commitMsgFile %>` with exactly this one line and nothing\n          else:\n\n          chore: human review\n        on:\n          \"A <%= it.vars.commitMsgFile %>\": $onDone\n          \"M <%= it.vars.commitMsgFile %>\": $onDone\n\n      addressing:\n        actor: agent\n        label: Addressing your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        # Refuse a work-free turn: a step whose only pending change is deleting the\n        # instructions file (the original \"captured then discarded\" bug). The\n        # feedback-progress guard (`src/StepGuards.ts`) reads this flag and\n        # exempts a `NOTHING ACTIONABLE` sentinel (a non-actionable review round,\n        # which legitimately makes no code change). The pure engine carries it inert.\n        requireProgress: true\n        prompt: |\n          You are an autonomous coding agent addressing review feedback. This\n          workflow steers itself through its own state files — treat them as\n          its private scratchpad, never as project code or documentation. The\n          only state file this turn touches is\n          `<%= it.vars.reviewFeedbackFile %>`; address it, then delete it. Do\n          not create other files to hold notes or output.\n\n          The instructions to implement are: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n          This is a flat instruction list, not a diff — execute every item exactly as\n          written, no Q&A, no re-planning, using TDD discipline:\n\n          - An item that says the human's own lines are final: build ON TOP of them to\n            complete only the follow-through it names (callers, tests, types, docs).\n            NEVER revert or rewrite the lines they already committed.\n          - An item derived from a human comment: satisfy it AND delete that comment\n            line from the code (the human's review comments are transient — none of\n            them survive this round).\n\n          If the file's sole content is a `NOTHING ACTIONABLE` line, make no code\n          change; just delete the instructions file.\n\n          Delete `<%= it.vars.reviewFeedbackFile %>` once every item is addressed.\n          Leave everything else uncommitted and finish your turn. Deleting the\n          instructions file WITHOUT making the changes it asks for is refused — the\n          feedback must actually be addressed.\n        on:\n          \"* **\": health.check\n\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: <%= it.vars.feedbackFile %>\n        prompt: *suiteFixPrompt\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\n      # Shared health pair: build.health.check/.escalate -> build.review.reviewing\n      # (green) or build.fix (red).\n      health:\n        machine: healthGate\n        with:\n          onGreen: review\n          onRed: fix\n          escalateDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` yourself\n            (**build.health.check**).\n          checkLabel: Running checks\n          escalateLabel: Escalating to a human\n\n      # The shared review tail, nested HERE (not at the root) so its run stays\n      # inside the builder's own scope across the feedback round-trip — see\n      # the header comment. Sign-off -> squashing; feedback -> addressing (the\n      # implementer's own coder-identity follow-through, not a reviewer action).\n      review:\n        machine: humanReview\n        with:\n          onSignoff: squashing\n          onFeedback: addressing\n\n  # The root machine — the whole \"advanced/simple\" flow tree described in\n  # this file's header comment. WIRING ONLY: no identity of its own, just the\n  # shared entry/exit states and the top-level machine tree.\n  unified:\n    entry: idle\n    states:\n      # ── Shared entry ────────────────────────────────────────────────────────\n      idle:\n        actor: human\n        label: Idle\n        # Every human-gate `message:` below closes with the same rendered \"What\n        # each change does next\" list, built from `it.edges` (the resting state's\n        # own `on` edges — each edge's `describe:` is the single source of truth).\n        message: |\n          No active gtd process.\n\n          To start one, create a steering file describing what you want built:\n\n          - `<%= it.vars.todoFile %>` — a short sketch — starts the SIMPLE flow\n            (plan, build, review).\n          - `<%= it.vars.requirementsFile %>` — the product requirements — starts\n            the ADVANCED flow (product + technical Q&A, package decomposition,\n            parallel build, per-package agentic review).\n\n          What each change does next (then run `gtd step human`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* <%= it.vars.requirementsFile %>\":\n            to: spec-gate\n            action: Start advanced flow\n            describe: >-\n              save the product requirements to `.gtd/REQUIREMENTS.md` — gtd first\n              checks the test baseline is green, then the agent develops them\n              through product then technical Q&A, decomposes the work into\n              packages, and builds each in parallel (**spec-gate.check**).\n          \"* **\":\n            to: plan-gate\n            action: Start simple flow\n            describe: >-\n              save a short sketch to `.gtd/TODO.md` (or any other change) — gtd\n              first checks the test baseline is green, then the agent reads it,\n              explores the codebase, and develops it into a concrete\n              implementation plan (**plan-gate.check**).\n\n      # ── Green-baseline gate: `gtd --entry fix-precheck` entry ─────────────────\n      # `gtd --entry fix-precheck` enters HERE: run the suite, then a red run\n      # drops straight into the shared `build.fix` loop (-> build.health.check ->\n      # review + squash tail); a green run is a no-op back to `idle` (nothing\n      # to fix).\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A <%= it.vars.feedbackFile %>\": build.fix\n          \"M <%= it.vars.feedbackFile %>\": build.fix\n          \"D <%= it.vars.feedbackFile %>\": idle\n          \"C\": idle\n\n      # ── Shared tail: the finale ─────────────────────────────────────────────\n      done:\n        commit: |\n          <%~ it.read(it.vars.commitMsgFile) %>\n\n          Token cost: <%= it.processCost %>\n          <% it.processCostByModel.forEach(function(m){ %>\n          - <%= m.model %>: <%= m.cost %>\n          <% }) %>\n\n      # ── Green-baseline gate: simple flow entry. ────────────────────────────────\n      plan-gate:\n        machine: entryGate\n        with:\n          onGreen: plan\n          reviewBase: \"\"\n          blockedMessage: |\n            The test baseline is red — gtd will not start new work on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd step human`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**plan-gate.check**). To repair the baseline as its own separate\n            reviewed commit instead, abandon this start and run\n            `gtd --entry fix-precheck` from a clean `idle`.\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Green-baseline gate: advanced flow entry. ──────────────────────────────\n      spec-gate:\n        machine: entryGate\n        with:\n          onGreen: design\n          reviewBase: \"\"\n          blockedMessage: |\n            The test baseline is red — gtd will not start new work on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd step human`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**spec-gate.check**). To repair the baseline as its own separate\n            reviewed commit instead, abandon this start and run\n            `gtd --entry fix-precheck` from a clean `idle`.\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Green-baseline gate: `gtd --entry review-gate.check` entry -> build.review.reviewing. ─\n      review-gate:\n        machine: entryGate\n        with:\n          onGreen: build.review\n          reviewBase: <%= it.vars.reviewBase %>\n          blockedMessage: |\n            The test baseline is red — gtd will not start a review on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd step human`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**review-gate.check**).\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Advanced flow: the design conversation (design.product-author/.product-answer ─\n      # -> design.technical-author/.technical-answer -> design.decompose -> packages). ──\n      design:\n        machine: advancedPlan\n        with:\n          onPackages: packages\n\n      # ── Simple flow plan-iteration loop (plan.planning/.await-plan -> build.building). ──\n      plan:\n        machine: planLoop\n        with:\n          onAccept: build.building\n\n      # ── Advanced per-package build queue (packages.* -> build.review). ────────\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      # ── Simple flow's build identity (build.* -> build.review -> done). ───────\n      build:\n        machine: simpleBuild\n        with:\n          onPackages: packages\n          onDone: done\n";
+var unified_default = "# The unified gtd workflow template — gtd's BUILT-IN DEFAULT workflow. When no\n# `workflow:` key is configured anywhere in the cwd→home config chain,\n# src/Config.ts runs this template directly, so a state command works with no\n# configuration at all. `gtd init` seeds only the settings a project tunes\n# (vars.testCommand + a modes: formatting suggestion), never the workflow\n# itself. See the README's \"How it works\" and \"Driving the loop\" sections for\n# the full walkthrough.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `renderInitConfig` (src/workflows/\n# templates.ts) can MATERIALIZE this raw source into a `.gtdrc.json`\n# `workflow:` value — the way to eject/customize the machine, and the hermetic\n# test fixture — but `gtd init` itself no longer writes the workflow.\n#\n# ── Authored with MACHINES (entry:/machines:) ───────────────────────────────\n#\n# This template is written as a tree of reusable, parameterized MACHINES (see\n# src/Machines.ts) — a gate/loop written once and instantiated several times\n# with different `with:` bindings (dedup), or a complex cluster grouped under\n# one name for source comprehension (encapsulation). Every reference below is\n# an ordinary `{ machine: <name>, with: { ... } }` local, expanded at\n# compile-time into concrete, qualified states before the pure engine ever\n# sees the definition — no runtime footprint.\n#\n# MACHINE BOUNDARIES LINE UP WITH CONVERSATIONAL IDENTITY: a machine that holds\n# an identity (a planner or a coder persona) declares its own `model:` ONCE, at\n# the machine level (stamped onto every one of its own `prompt` states — see\n# src/Machines.ts's `resolveInstanceModel`), instead of repeating `model:` on\n# every state; no state anywhere declares `model:` or `memory:` directly any\n# more (the memory key is computed from the machine tree — see\n# src/PatternMachine.ts's `memoryScopeAt` / src/Edge.ts's `memoryKeyFor`). Two\n# gate/queue machines below are deliberately IDENTITY-FREE (no `model:`):\n# `entryGate`/`healthGate` are infrastructure, not a persona, and `packageLoop`\n# is a bookkeeping queue, not a builder.\n#\n#   * entryGate (dedup ×3)    — the green-baseline gate (check + human blocked)\n#                               guarding the simple (`plan-gate`), advanced\n#                               (`spec-gate`) and review (`review-gate`)\n#                               entries. Identity-free.\n#   * healthGate (dedup ×2)   — the check/escalate health pair shared by the\n#                               simple build's own tail (`build.health.*`) and\n#                               the per-package build's own tail\n#                               (`packages.item.health.*`) — each caller's OWN\n#                               `fix` state (a coder-identity action) lives\n#                               beside this machine, not inside it, since\n#                               fixing IS a coder action and this machine has\n#                               no identity of its own. Identity-free.\n#   * advancedPlan (encap)    — the advanced flow's one design conversation:\n#                               product Q&A, technical Q&A, and decomposition\n#                               (`design.*`: product-author/-answer,\n#                               technical-author/-answer, decompose) all share\n#                               ONE machine identity, so the agent explores the\n#                               codebase once, not three times, and the human's\n#                               answer rationale survives into decomposition.\n#                               ▸ planner.\n#   * planLoop (encap)        — the simple flow's plan-iteration loop (`plan.*`).\n#                               ▸ planner.\n#   * humanReview (encap)     — the shared review tail, nested INSIDE\n#                               `simpleBuild` (`build.review.*`: reviewing →\n#                               await-review → deciding → collecting) — see\n#                               \"Why humanReview is nested, not a root sibling\"\n#                               below. ▸ planner — the implementer's OWN\n#                               follow-through on feedback is a coder action,\n#                               not a reviewer one, so it lives in\n#                               `build.addressing` instead.\n#   * specReview (encap)      — the advanced flow's per-package agentic review,\n#                               now a SINGLE state (`packages.item.spec.review`)\n#                               — a machine whose entire job is to be a\n#                               separate mind from the implementer. ▸ planner\n#                               — fixing the reviewer's own findings is a coder\n#                               action, so it lives in `packages.item.fix-spec`\n#                               instead.\n#   * packageLoop (encap)     — the advanced flow's per-package build queue\n#                               (`packages.picking`). Identity-free — the\n#                               actual per-package build identity lives in its\n#                               own `item` child (packageItem, below).\n#   * packageItem (encap)     — the advanced flow's per-package build identity\n#                               (`packages.item.*`: building, fix-suite,\n#                               fix-spec, closing), plus its own `health` and\n#                               `spec` children. ▸ coder.\n#   * simpleBuild (encap)     — the simple flow's build identity (`build.*`:\n#                               building, squashing, addressing, fix), plus its\n#                               own `health` child AND its own `review` child\n#                               (humanReview, above). ▸ coder.\n#\n# ── Why humanReview is nested, not a root sibling ───────────────────────────\n#\n# `humanReview` sits UNDER `simpleBuild` (`build.review`) rather than beside it\n# at the root, because a machine's memory scope is its dotted instance path\n# (see src/PatternMachine.ts's `memoryScopeAt`): entering a DESCENDANT scope\n# never breaks the parent's unbroken run, but entering a sibling does. The\n# review tail sits between the two coder turns that most need continuity —\n# `build.addressing` (follows through on review feedback) and `build.squashing`\n# (drafts the finale from the range this process built) — so hoisting it back\n# to a root sibling would force both of those turns to re-derive the feature\n# from scratch on every pass through the tail, instead of resuming the session\n# that built it. The reviewer itself is unaffected either way: `build.review.*`\n# is its own scope regardless of where it's nested, so it never resumes the\n# builder's session.\n#\n# ── Four entry points behind a green-baseline gate, one shared tail ─────────\n#\n# EVERY entry first runs the test suite and only proceeds when it is GREEN — you\n# never start new work (or a review) on top of a red baseline. A red run halts\n# at a human blocked gate (fix the failures and re-run, exactly like the\n# escalate states), or is what `gtd --entry fix-precheck` exists to repair.\n#\n# The initial `idle` state FORKS on which steering file the human creates,\n# routing into that flow's OWN start gate:\n#\n#   * the configured requirementsFile (default .gtd/REQUIREMENTS.md) ->\n#     `spec-gate.check` -> the ADVANCED flow (one design conversation across\n#     product + technical Q&A and decomposition, per-package parallel build +\n#     agentic spec-review).\n#   * anything else (e.g. the configured todoFile, default .gtd/TODO.md) ->\n#     `plan-gate.check` -> the SIMPLE flow (one grilling Q&A loop, a monolithic\n#     build, no decomposition, no agentic review).\n#\n# A third entry, `gtd --entry review-gate.check`, jumps there directly and,\n# once green, to `build.review.reviewing` to review a foreign branch through\n# the same shared tail. A fourth, `gtd --entry fix-precheck`, jumps there: a\n# red suite drops straight into the shared `build.fix` loop and out through the\n# review + squash tail; a green suite is a no-op back to `idle`. Both states\n# declare `entry: true` — otherwise unreachable from `entries.default`.\n#\n# All three converge at `build.review.reviewing` -> `build.review.await-review`.\n# Ticking a REVIEW.md box means only \"I reviewed this hunk\"; a COMMENT (not an\n# unticked box) is what asks for changes. Every human step at\n# `build.review.await-review` goes to `build.review.deciding`, which inspects\n# the step and routes:\n#   * no comment (every box ticked, no REVIEW.md note, no code edit) -> the diff\n#     is a bare REVIEW.md deletion -> build.squashing -> done (the ONLY path\n#     to the finale — the whole process collapses into one commit).\n#   * any comment — a note in REVIEW.md OR a hand-edit to code — ->\n#     build.review.deciding writes REVIEW_FEEDBACK.md -> build.review.collecting\n#     implements it (completing any code the human hand-edited, never\n#     reverting their lines) -> build.addressing (a coder action, not a\n#     reviewer one — see \"Why humanReview is nested\" above) -> back through\n#     `build.health.check` (the shared health pair, bound via the\n#     `$onFeedback`/local `review` reference) -> build.review.reviewing\n#     regenerates an INCREMENTAL REVIEW.md (build.review.deciding carries\n#     `reviewBase: true`, so each feedback round's review + checkout window\n#     covers only `last-review..HEAD`, i.e. the agent's follow-through, not the\n#     human's own edit) -> await-review, looping until sign-off.\n# Two dead ends never commit: the review-signoff guard (src/StepGuards.ts)\n# REFUSES a step that leaves a box unticked with no comment (finish reviewing\n# first) and a deleted REVIEW.md (restore it and tick the boxes).\n#\n# The shared health pair (`build.health.check`/`.escalate`, plus the caller's\n# own `build.fix`) serves the simple build and the feedback loop — its green\n# edge targets `build.review.reviewing`. The advanced per-package loop keeps\n# its OWN health pair (`packages.item.health.check`/`.escalate`, plus\n# `packages.item.fix-suite`) because its green edge targets the per-package\n# `packages.item.spec.review` gate instead.\n#\n# Every `on` pattern's path below is written as the matching var's Eta\n# template (e.g. `\"A <%= it.vars.feedbackFile %>\"`), not a literal `.gtd/...`\n# path — repointing a var reroutes the machine along with every template that\n# reads/writes it (see the README's \"Variables\" section).\n\nvars:\n  testCommand: npm test\n  # Where gtd keeps its own scratch/bookkeeping (the check scripts' temp output\n  # file, review-deciding's state-file exclusion). Independent of the per-file\n  # vars below — relocating a file wholesale means setting both.\n  stateDir: .gtd\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewRawFile: .gtd/REVIEW_RAW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_PLANNERMODEL` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/technical-qa/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n  # The fixed diff base for `gtd --entry review-gate.check --var\n  # reviewBase=<commitish>` — a plain non-gtd branch reviewed against that\n  # commitish rather than the process start. Declared here (rather than left\n  # undeclared) so `--var reviewBase=...` passes the CLI's declared-name\n  # check; the default empty string renders blank, which the entry command\n  # refuses (a review entry always requires an explicit base).\n  reviewBase: \"\"\n\n# `prose` is a format-only steering-file mode this workflow blesses for itself:\n# a curated free-form document with no gtd-side schema (the simple flow's plan\n# file, .gtd/TODO.md — see the `plan.planning` state below). An empty entry is\n# the format-only tier any workflow can declare for a name with no built-in\n# parser; `qa`/`review` need no entry here — src/PatternConfig.ts's compiler\n# seeds those two from the built-in registry (src/SteeringFormats.ts)\n# automatically.\nmodes:\n  prose: {}\n\nentry:\n  default: unified\n\nmachines:\n  # ── DEDUP: the green-baseline entry gate (identity-free) ──────────────────\n  # Runs the suite before any work starts (its script is the shared suite-check\n  # wrapper — red -> the configured feedbackFile, green -> remove it); the `on`\n  # rules turn that into \"halt at blocked\" vs \"proceed to $onGreen\". The script\n  # and blocked message/describe differ per entry, so they ride in as `with:`\n  # params. Kept SEPARATE from `healthGate` (below) even though both are a\n  # check+something-else shape: this gate runs BEFORE planning, so it must NOT\n  # sweep the plan/review steering files healthGate does — a human's fresh\n  # sketch legitimately still exists here.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # Anchored here and aliased by `fix-precheck` (`gtd --entry\n        # fix-precheck` entry): one suite-check script shared by all four\n        # call sites (this machine's ×3 instances plus `fix-precheck`)\n        # instead of four source copies. These gates run BEFORE planning, so\n        # — unlike `healthGate.check` — they must NOT sweep\n        # `todoFile`/`requirementsFile`: the human's fresh sketch still\n        # legitimately exists here.\n        # `entry: true` on the shared local marks all three `entryGate`\n        # instances (plan-gate/spec-gate/review-gate) as manual entries —\n        # only `review-gate.check` actually needs the reachability root (it\n        # is otherwise unreachable from `entries.default`), but the shared\n        # dedup makes marking one mark all three. Accepted as correct: all\n        # three ARE the workflow's entry gates.\n        entry: true\n        # `reviewBase: $reviewBase` — only `review-gate` binds a real\n        # template (`<%= it.vars.reviewBase %>`), fixing the whole process's\n        # diff base to whatever `gtd --entry review-gate.check --var\n        # reviewBase=<commitish>` supplies. `plan-gate`/`spec-gate` bind the\n        # literal empty string, which compiles away to \"no base\" here — they\n        # are reached from `idle`, never manually entered with a base.\n        reviewBase: $reviewBase\n        script: &suiteCheck |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n          # newline after an interpolation tag, so no tag may be the last token on\n          # a line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": blocked\n          \"M <%= it.vars.feedbackFile %>\": blocked\n          \"D <%= it.vars.feedbackFile %>\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: <%= it.vars.feedbackFile %>\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # ── DEDUP: the check/escalate health pair (identity-free) ─────────────────\n  # Runs the suite; a red run records the configured feedbackFile and routes to\n  # the caller's OWN fixer (`$onRed` — a coder-identity action that lives\n  # beside this machine, not inside it, since fixing IS a coder action and this\n  # machine has no identity); a green run cleans it up and routes to\n  # `$onGreen`. Escalation redirects here after the caller's fixer has retried\n  # `max` times without success. Instantiated for the simple build's own tail\n  # (`build.health.*`, caller's fixer is `build.fix`) and the per-package\n  # build's own tail (`packages.item.health.*`, caller's fixer is\n  # `packages.item.fix-suite`).\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # This script ALSO sweeps spent steering files (`todoFile`,\n        # `reviewRawFile`, `reviewFeedbackFile`) — a mechanic `entryGate.check`\n        # must NOT run, since it executes before planning, while a fresh\n        # sketch legitimately still exists.\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n          # green run cleans it up. The `on` rules decide what that means.\n          set +e\n          mkdir -p \"<%~ it.vars.stateDir %>\"\n          # Hoist every path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a\n          # line — it would glue the next line's `else`/`fi` onto it and break\n          # the script. Below this point everything is plain bash.\n          feedback=\"<%~ it.vars.feedbackFile %>\"\n          mkdir -p \"$(dirname \"$feedback\")\"\n          # Sweep steering files spent by the states that led here: the plan\n          # (building), the raw review capture (review.collecting), and the\n          # feedback instructions (build.addressing) — each `rm -f` is a\n          # no-op when the file is already gone or never existed on this path.\n          todo=\"<%~ it.vars.todoFile %>\"\n          reviewRaw=\"<%~ it.vars.reviewRawFile %>\"\n          reviewFeedback=\"<%~ it.vars.reviewFeedbackFile %>\"\n          rm -f \"$todo\" \"$reviewRaw\" \"$reviewFeedback\"\n          <%~ it.vars.testCommand %> > <%~ it.vars.stateDir %>/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s <%~ it.vars.stateDir %>/.check-output ]; then\n              mv <%~ it.vars.stateDir %>/.check-output \"$feedback\"\n            else\n              rm -f <%~ it.vars.stateDir %>/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n            fi\n            # A repeat identical failure would otherwise leave FEEDBACK.md\n            # byte-identical to its committed copy — no diff, so the check would\n            # look GREEN. Stamp each red run with the current HEAD (which always\n            # advances between checks) so a still-red re-run always re-registers\n            # as an M/A edit and takes the red edge.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> \"$feedback\"\n          else\n            rm -f <%~ it.vars.stateDir %>/.check-output\n            rm -f \"$feedback\"\n          fi\n        on:\n          \"A <%= it.vars.feedbackFile %>\": $onRed\n          \"M <%= it.vars.feedbackFile %>\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: <%= it.vars.feedbackFile %>\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $escalateDescribe\n\n  # ── ENCAPSULATION: the advanced flow's design conversation ─────────────────\n  # One planner identity across product Q&A -> technical Q&A -> decomposition:\n  # a single codebase exploration instead of three, and the human's answer\n  # rationale survives from product into technical and into decomposition (all\n  # five states share one memory scope, `design`). Replaces the former\n  # `qaLoop ×2` (which split one design conversation into two minds that each\n  # re-explored the codebase) plus `simpleBuild`'s own `decompose` (which\n  # landed on the coder tier only because it happened to live in the build\n  # machine — decomposition is judgement-heavy planning work, not building).\n  # ▸ planner identity — `model:` declared once here, stamped onto\n  # `product-author`, `technical-author`, and `decompose` (its own prompt\n  # states; the `*-answer` states are human turns and carry no prompt).\n  advancedPlan:\n    model: <%= it.vars.plannerModel %>\n    params: [onPackages]\n    entry: product-author\n    states:\n      product-author:\n        actor: agent\n        label: Refining the product plan\n        file: <%= it.vars.requirementsFile %>\n        mode: qa\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this turn\n          touches is `<%= it.vars.requirementsFile %>`; develop it. Do not\n          create other files to hold notes or output.\n\n          `<%= it.vars.requirementsFile %>` holds the product requirements (or the\n          plan you already wrote plus the human's answers on a return lap). Read it,\n          explore the codebase, and develop it into a concrete, PRODUCT-level plan\n          in this one turn.\n\n          Scope: product and user-facing decisions only. Leave implementation\n          details (file/module structure, data models, tech-stack choices) for the\n          next phase (`<%= it.vars.architectureFile %>`).\n\n          For every open point you cannot settle yourself, add a question under a\n          `## Open Questions` heading near the top: one `### <question>` sub-heading\n          each, followed by a checkbox list of candidate answers — aim for TWO\n          concrete options plus a final free-text slot, ALL left UNTICKED:\n\n              ### <the question>\n\n              - [ ] <first option — a concrete answer, a few words of rationale>\n              - [ ] <second option>\n              - [ ] _your answer_\n\n          Never tick a box yourself — the human ticks exactly one per question. The\n          last `- [ ] _your answer_` line is the human's own-answer slot; write it\n          with the literal `_your answer_` placeholder and leave it for them.\n\n          On a RETURN lap the human has ticked one option per question (or replaced\n          `_your answer_` with their own text). For each answered question: fold the\n          chosen answer into the plan prose, then MOVE the question down into a\n          `## Answered Questions` section as `### <question>` followed by the\n          resolved answer in plain PROSE (drop the checkboxes). Never re-raise a\n          question the human deleted; if the human deleted the whole\n          `## Open Questions` section, treat the plan as accepted and surface no new\n          questions unless something is genuinely still blocking. Omit\n          `## Open Questions` entirely once there are none left.\n\n          Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": product-answer\n\n      product-answer:\n        actor: human\n        label: Awaiting your answers\n        file: <%= it.vars.requirementsFile %>\n        mode: qa\n        answerGate: true\n        message: |\n          `<%= it.vars.requirementsFile %>` holds the product plan under\n          development. Each question under `## Open Questions` offers a few options\n          plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n          exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n          with your text and tick that line. Stepping is refused while any question\n          is unanswered.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: technical-author\n            action: Accept answers\n            describe: >-\n              with no open questions left (the agent surfaced none, or you deleted\n              the section and it finalized the plan), change nothing to move on to\n              technical Q&A (**design.technical-author**).\n          \"* **\":\n            to: product-author\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace `_your answer_` for\n              your own) to send the plan back for the agent to fold your answers in\n              (**design.product-author**). Delete a question to skip it, or delete the whole\n              `## Open Questions` section to accept the plan as-is.\n\n      technical-author:\n        actor: agent\n        label: Refining the technical plan\n        file: <%= it.vars.architectureFile %>\n        mode: qa\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.architectureFile %>` (write it) and\n          `<%= it.vars.requirementsFile %>` (delete it once its content is\n          folded in). Do not create other files to hold notes or output.\n\n          If you developed those requirements earlier in this conversation, work\n          from what you already settled; otherwise read\n          `<%= it.vars.requirementsFile %>` (the converged product plan) yourself.\n          Develop `<%= it.vars.architectureFile %>` from it in this one turn:\n          file/module structure, data models, library/tech-stack choices,\n          error-handling strategy — the *how*, building on the *what* already\n          settled. Do not re-open product-level decisions; treat them as settled.\n\n          For every open point you cannot settle yourself, add a question under a\n          `## Open Questions` heading exactly as the grilling phase does: one\n          `### <question>` each, followed by a checkbox list — TWO concrete options\n          plus a final free-text slot, ALL left UNTICKED:\n\n              ### <the question>\n\n              - [ ] <first option>\n              - [ ] <second option>\n              - [ ] _your answer_\n\n          Never tick a box yourself. On a RETURN lap the human has ticked one option\n          per question (or replaced `_your answer_` with their own text): fold each\n          chosen answer into the plan prose, then MOVE the question into a\n          `## Answered Questions` section as `### <question>` + the resolved answer\n          in plain PROSE (drop the checkboxes). Never re-raise a deleted question;\n          treat a deleted `## Open Questions` section as acceptance. Omit\n          `## Open Questions` once there are none left.\n\n          Once `<%= it.vars.architectureFile %>` is written, delete\n          `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n          must not linger. Leave everything uncommitted and finish your turn.\n        on:\n          \"* **\": technical-answer\n\n      technical-answer:\n        actor: human\n        label: Awaiting your answers\n        file: <%= it.vars.architectureFile %>\n        mode: qa\n        answerGate: true\n        message: |\n          `<%= it.vars.architectureFile %>` holds the technical plan under\n          development. Each question under `## Open Questions` offers a few options\n          plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n          exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n          with your text and tick that line. Stepping is refused while any question\n          is unanswered.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: decompose\n            action: Accept answers\n            describe: >-\n              with no open questions left (the agent surfaced none, or you deleted\n              the section and it finalized the plan), change nothing to move on to\n              decomposing the work into packages (**design.decompose**).\n          \"* **\":\n            to: technical-author\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace `_your answer_` for\n              your own) to send the plan back for the agent to fold your answers in\n              (**design.technical-author**). Delete a question to skip it, or delete the whole\n              `## Open Questions` section to accept the plan as-is.\n\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself through\n          its own state files — treat them as its private scratchpad, never as\n          project code or documentation. The only state files this turn touches\n          are the package files it writes under `<%= it.vars.packagesDir %>/` and\n          `<%= it.vars.architectureFile %>`, which it deletes. Do not create other\n          files to hold notes or output.\n\n          If you wrote `<%= it.vars.architectureFile %>` earlier in this\n          conversation, work from what you already settled; otherwise read it\n          (the converged technical plan) yourself. Decompose it into an ordered\n          set of WORK PACKAGES, one file each under\n          `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n          `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n          test suite can pass again after each one lands.\n\n          Each package file describes a set of INDEPENDENT tasks that can be\n          implemented concurrently without ordering constraints between them — a\n          single build turn will fan them out to parallel subagents. Give each task\n          a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n          relevant paths. Also state the package's overall requirement so it can be\n          reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n          package — split them across ordered packages instead.\n\n          No package file may reference any other `.gtd/` file. Once the package\n          files are written, delete `<%= it.vars.architectureFile %>`. Leave\n          everything uncommitted and finish your turn.\n        on:\n          \"* <%= it.vars.packagesDir %>/**\": $onPackages\n\n  # ── ENCAPSULATION: the simple flow's plan-iteration loop ───────────────────\n  # ▸ planner identity — `model:` declared once here, stamped onto `planning`\n  # (its only prompt state).\n  planLoop:\n    model: <%= it.vars.plannerModel %>\n    params: [onAccept]\n    entry: planning\n    states:\n      planning:\n        actor: agent\n        label: Refining the plan\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.todoFile %>`; develop it into the plan.\n          Do not create other files to hold notes or output.\n\n          `<%= it.vars.todoFile %>` holds a short sketch of what to build — or, on a\n          return lap, the plan you already wrote plus the human's edits and comments\n          on it. Read it, explore the codebase, and develop it into a concrete\n          implementation plan: the files to change, the approach, and the steps to\n          take.\n\n          Do NOT ask questions and do NOT add an \"Open Questions\" section — decide\n          every open point yourself and write the plan as a set of concrete\n          decisions. Where a decision is genuinely a judgement call, state the\n          choice you made and, in one line, why. The human iterates on the plan by\n          editing it directly, not by answering questions.\n\n          On a return lap, `<%= it.vars.todoFile %>` carries the human's edits and\n          inline comments on your previous plan. If you wrote that plan earlier in\n          this conversation, work from what you already know plus these edits;\n          otherwise read the file fresh. Fold every edit and comment into a\n          revised, self-contained plan and remove the addressed comments — the plan\n          is always the current, clean proposal, never a diff.\n\n          Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n          not commit, and do not run `gtd land` yourself; the harness does\n          that.\n        on:\n          \"* **\": await-plan\n\n      await-plan:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.todoFile %>\n        mode: prose\n        message: |\n          `<%= it.vars.todoFile %>` holds the proposed implementation plan. Read it,\n          then either accept it as-is or edit it — rewrite a step, add a\n          constraint, or drop an inline comment — to send it back for another round.\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"C\":\n            to: $onAccept\n            action: Accept plan\n            describe: >-\n              change nothing to move on to implementation (**build.building**).\n          \"* **\":\n            to: planning\n            action: Revise plan\n            describe: >-\n              rewrite a step, add a constraint, or leave an inline comment to\n              send it back for another round (**plan.planning**).\n\n  # ── ENCAPSULATION: the shared review tail ──────────────────────────────────\n  # ▸ planner identity — `model:` declared once here, stamped onto `reviewing`\n  # and `collecting` (its only prompt states). The implementer's OWN\n  # follow-through on feedback is a coder action, not a reviewer one — it\n  # lives in `build.addressing` (`$onFeedback`), not inside this machine.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # `gtd --entry review-gate.check` (a plain non-gtd branch, e.g. a\n        # colleague's PR) does NOT enter here directly — it enters\n        # `review-gate.check` first, which runs the green-baseline gate and,\n        # once green, transitions here. The `Gtd-Review-Base:` trailer rides on that\n        # entry commit (the process's oldest), so everything below still reuses\n        # the same reviewing/await-review/feedback machinery over <commitish>..HEAD.\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.reviewFile %>`; write it at exactly\n          that path. Do not create other files to hold notes or output.\n\n          Write `<%= it.vars.reviewFile %>` to help a human review the changes in\n          this EXACT format:\n\n          - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n          - Somewhere in the document: `<!-- base: <%= it.reviewBase %> -->`\n          - At least one `## <Chunk Title>` heading, grouping hunks semantically\n            (same feature/refactor/fix, even across files) — a short explanation of\n            what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n            pointer per hunk (checkboxes are for the human to tick, not you; every\n            path is `./`-relative, with an optional `#line` and an optional\n            ` — note`).\n\n          This prompt carries no diff — read the changes yourself. The range runs\n          from `<%= it.reviewBase %>` to the working tree (committed turns plus\n          anything still pending); on a feedback round that base is the previous\n          review's boundary, so it covers only what changed since then, not items\n          already signed off.\n\n          Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # While the process rests here, gtd opens a \"review checkout window\": raw HEAD\n        # is rewound to the review base (the most-recent `deciding` commit — so a\n        # feedback round shows only `last-review..HEAD` — or the process start on\n        # the first review) with the working tree untouched, surfacing the diff\n        # as ordinary uncommitted changes. It closes on the next invocation.\n        #\n        # Every human step here routes to `deciding`, which decides sign-off vs.\n        # feedback from the step's CONTENT (a comment, not a tick). Ticking a box\n        # only records \"I reviewed this hunk\". Two dead ends can't be told apart by a\n        # file-pattern edge, so the review-signoff guard (`src/StepGuards.ts`)\n        # catches them BEFORE the step commits and refuses: an unfinished\n        # review (a box still `- [ ]` with no comment) and a deleted REVIEW.md.\n        reviewWindow: true\n        message: |\n          `<%= it.vars.reviewFile %>` holds the review record for the process — one\n          `- [ ]` checkbox per reviewable item, grouped into chunks. Tick a box\n          (`- [x]`) as you review each hunk; ticking only records that you've read\n          it, it is not sign-off.\n\n          When you've been through the whole diff, run `gtd land`:\n\n          - **Sign off** — tick EVERY box and leave no comment — no note in\n            `<%= it.vars.reviewFile %>`, no code edit — to collapse the process into\n            one commit (**build.squashing**).\n          - **Request changes** — leave a comment: a note on a\n            `<%= it.vars.reviewFile %>` line, or a direct code edit — to send it to a\n            build + re-review round (**review.deciding** → **build.addressing**). A\n            code edit counts as your own fix: the agent completes the follow-through\n            it implies and never reverts your lines.\n\n          Stepping with a box still unticked and no comment is refused (finish\n          reviewing first); so is deleting `<%= it.vars.reviewFile %>`.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: <%= it.vars.reviewFile %>\n        mode: review\n        # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n        # the point the previous review round ended, so the next `reviewing` turn\n        # (and the review checkout window) covers only the changes since then. On\n        # the first review there is no such commit, so the base is the process start.\n        reviewBase: true\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn — decide the human's review step from its CONTENT. HEAD is\n          # the human's `await-review -> deciding` commit; HEAD^ is the `reviewing`\n          # commit that wrote the agent's original REVIEW.md (the sign-off gate\n          # refuses an incomplete step, so `deciding` is entered exactly once per\n          # round — nothing commits in between). It is FEEDBACK when the human left\n          # a comment: a note in REVIEW.md (any edit beyond a \"[ ]\"->\"[x]\" tick) OR a\n          # hand-edit to any file this round other than `.gtd/` or the state's own\n          # reviewFile (which is var-configurable and may live outside `.gtd/`, e.g.\n          # a root-level REVIEW.md — issue #128). Otherwise it is a clean sign-off.\n          # This turn only CAPTURES the raw material into REVIEW_RAW.md (the\n          # `collecting` agent then turns it into instructions); it does NOT\n          # interpret it. Either way, remove REVIEW.md; what the resulting diff\n          # MEANS is decided by this state's own `on` rules — the A/M REVIEW_RAW.md\n          # rows are declared BEFORE the D REVIEW.md row so a feedback round (which\n          # also deletes REVIEW.md) is captured as feedback, not mistaken for a\n          # sign-off.\n          set +e\n          # Hoist the paths once, at the TOP: Eta's autoTrim eats the newline after\n          # an interpolation tag, so no tag may be the last token on a line — it\n          # would glue the next line onto it and break the script. Below this point\n          # everything is plain bash.\n          stateDir=\"<%~ it.vars.stateDir %>\"\n          reviewFile=\"<%~ it.vars.reviewFile %>\"\n          reviewRawFile=\"<%~ it.vars.reviewRawFile %>\"\n          head=$(git rev-parse HEAD)\n          mkdir -p \"$(dirname \"$reviewRawFile\")\"\n          # A note is any REVIEW.md change beyond a checkbox flip: normalize every\n          # \"[ ]\"/\"[x]\" to a placeholder, then compare the agent's original (HEAD^)\n          # against the human's version (HEAD).\n          before=$(git show \"HEAD^:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          after=$(git show \"HEAD:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          # Did the human hand-edit anything this round besides stateDir and the\n          # reviewFile itself (var-configurable — may live outside stateDir, so it\n          # is excluded by exact path, not just the stateDir prefix)?\n          if git diff-tree --no-commit-id --name-only -r HEAD \\\n               | grep -v \"^$stateDir/\" | grep -vxF \"$reviewFile\" | grep -q . \\\n             || [ \"$before\" != \"$after\" ]; then\n            {\n              echo \"Raw review material captured for classification. The human reviewed the changes and left the feedback below; a downstream agent turns it into an instruction list. This file is machine-captured input, not instructions — it names a commit, never inlined content.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in $reviewFile at this commit; their hand edits,\"\n              echo \"if any, are in that commit's other paths. Run: git show $head\"\n            } > \"$reviewRawFile\"\n          fi\n          rm -f \"$reviewFile\"\n        on:\n          \"A <%= it.vars.reviewRawFile %>\": collecting\n          \"M <%= it.vars.reviewRawFile %>\": collecting\n          \"D <%= it.vars.reviewFile %>\": $onSignoff\n\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        prompt: |\n          You are an autonomous coding agent turning raw review feedback into an\n          explicit instruction list for a builder. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state files this\n          turn touches are `<%= it.vars.reviewRawFile %>` (read it, then\n          delete it) and `<%= it.vars.reviewFeedbackFile %>` (write it) — do\n          NOT change any other file, you classify, you do not build.\n\n          The raw review material is: <%~ it.read(it.vars.reviewRawFile) %>\n\n          It names a commit. If you wrote today's review earlier in this\n          conversation, work from what you already reviewed; otherwise read that\n          commit's diff yourself before classifying anything.\n\n          Classify every piece of it into `<%= it.vars.reviewFeedbackFile %>` as a\n          flat, numbered instruction list. Each item is `N. ./path/to/file.ts#line —\n          <imperative>`. Apply these rules exactly:\n\n          1. NOTES the human added to REVIEW.md — each note is a MANDATORY change,\n             regardless of whether its checkbox is ticked (ticking means only \"I read\n             this hunk\", never sign-off). Anchor each to the `./path#line` its review\n             item names (or the chunk it sits under). Emit it as a concrete\n             imperative.\n          2. Every COMMENT the human ADDED this round (a `+` line that is a code\n             comment, in the hand-edited files) is a MANDATORY instruction the human\n             is giving the builder — even a plain-prose one, even if its box is\n             ticked. Emit an imperative to satisfy it and note that the comment line\n             itself must be REMOVED once addressed. If a comment turns out to describe\n             behaviour the code already has, the instruction is still \"confirm the\n             code matches and remove the comment line\".\n          3. Every NON-comment code line the human hand-edited is an already-committed\n             INTENT, NOT a do-then-delete item. Emit an instruction that names those\n             files and says: their lines are final — complete ONLY the follow-through\n             they imply (callers, tests, types, docs) and NEVER revert or rewrite\n             them. Do not turn their own edit into a task.\n\n          Split each hand-edited hunk per line: comment `+` lines follow rule 2, the\n          surrounding real code follows rule 3.\n\n          If — and only if — nothing in the raw material is actionable (e.g. the human\n          left only an approving remark), write `<%= it.vars.reviewFeedbackFile %>`\n          containing exactly one line: `NOTHING ACTIONABLE — <one-sentence reason>`.\n          Never invent work to satisfy a non-actionable remark.\n\n          Delete `<%= it.vars.reviewRawFile %>`, leave everything else uncommitted,\n          and finish your turn.\n        on:\n          \"A <%= it.vars.reviewFeedbackFile %>\": $onFeedback\n          \"M <%= it.vars.reviewFeedbackFile %>\": $onFeedback\n\n  # ── ENCAPSULATION: the advanced flow's per-package agentic review ──────────\n  # A single state: a machine whose entire job is to be a separate MIND from\n  # the implementer, distinct from the coder identity that builds/fixes the\n  # package (`packages.item.*`). ▸ planner identity — `model:` declared once\n  # here, stamped onto `review` (its only prompt state). Fixing the reviewer's\n  # own findings is a coder action, not a reviewer one — it lives in\n  # `packages.item.fix-spec` (`$onFix`), not inside this machine.\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # Bounded per process: once entered `max` times, a transition into it is\n        # redirected to `$onApproved` (force-close the package and move on — the\n        # unresolved concern is deferred to the shared human review at the tail,\n        # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n        # pools across packages — the same documented limitation the shared\n        # `build.fix` cap has (see the README's \"Why\" section, \"Bounded, not\n        # runaway\").\n        retry:\n          max: 3\n          otherwise: $onApproved\n        prompt: |\n          You are an autonomous coding agent reviewing a freshly-built work package\n          against its own spec. This workflow steers itself through its own\n          state files — treat them as its private scratchpad, never as project\n          code or documentation. The only state file this turn touches is\n          `<%= it.vars.specFeedbackFile %>`; write it only when — and only\n          when — you find problems. Do not create other files to hold notes or\n          output.\n\n          The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n          Read that spec, then verify the package's implementation against it: are\n          all its tasks done, acceptance criteria met, and the code sound and\n          consistent with the codebase? This prompt carries no diff — read it\n          yourself: the range runs from `<%= it.startCommit %>` to the working\n          tree.\n\n          Note the range is process-wide (from the start of the whole build, not\n          just this package), so it can span earlier packages too.\n\n          - If it fully satisfies the spec, write NOTHING and finish your turn — a\n            clean turn is your approval.\n          - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n            concrete problems for a fix turn to address. Be specific.\n\n          Do not fix anything yourself and do not delete the package file — a later\n          step owns that. Finish your turn.\n        on:\n          \"A <%= it.vars.specFeedbackFile %>\": $onFix\n          \"M <%= it.vars.specFeedbackFile %>\": $onFix\n          \"D <%= it.vars.specFeedbackFile %>\": $onApproved\n          \"C\": $onApproved\n\n  # ── ENCAPSULATION: the advanced flow's per-package build queue ─────────────\n  # Identity-free (a bookkeeping queue, not a builder) — the actual per-package\n  # build identity lives in its own `item` child (packageItem, below).\n  packageLoop:\n    params: [onDrained]\n    entry: picking\n    states:\n      picking:\n        actor: check\n        label: Picking the next package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package queue arbiter) — the loop driver executes\n          # this verbatim, then steps the check actor. Mechanics only: take the\n          # first package file (by name) under the packages dir into NEXT.md, or\n          # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n          # MEANS (another package to build vs. the queue closing out to review) is\n          # decided by this state's own `on` rules at capture time — never here.\n          set +e\n          # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n          # after an interpolation tag, so no tag may be the last token on a line —\n          # it would glue the next line's `else`/`fi` onto it and break the script.\n          # Below this point everything is plain bash.\n          nextFile=\"<%~ it.vars.nextFile %>\"\n          # Sweep the advanced flow's spent Q&A steering files: requirementsFile\n          # is consumed by technical-qa, architectureFile by decompose — both are\n          # gone by the time the package queue starts. No-op if already removed.\n          requirements=\"<%~ it.vars.requirementsFile %>\"\n          architecture=\"<%~ it.vars.architectureFile %>\"\n          rm -f \"$requirements\" \"$architecture\"\n          next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            mkdir -p \"$(dirname \"$nextFile\")\"\n            printf '%s' \"$next\" > \"$nextFile\"\n          else\n            rm -f \"$nextFile\"\n          fi\n        on:\n          \"D <%= it.vars.nextFile %>\": $onDrained\n          \"* <%= it.vars.nextFile %>\": item.building\n          \"C\": $onDrained\n\n      # The per-package build identity — its own coder machine (below), so\n      # deleting a package file's own lifecycle stays inside `item` while the\n      # queue itself (`packages`) stays a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # ── ENCAPSULATION: the advanced flow's per-package build identity ──────────\n  # ▸ coder identity — `model:` declared once here, stamped onto `building`,\n  # `fix-suite`, and `fix-spec` (its own prompt states). `closing` ends that\n  # package file's own lifecycle; keeping it here (not in the queue) keeps\n  # `packages` itself to a single state. `packages.item.closing` -> `picking`\n  # is the ONE upward-resolving target in the whole file, so it MUST be a\n  # param (`$onNext`, bound by `packages` — see the machine's own reference).\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. This turn writes no state\n          file: do NOT delete the package file (the spec-review gate reads\n          it after you) and never touch `<%= it.vars.nextFile %>` — the\n          `picking` state owns it.\n\n          The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n          That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n          this one turn, fanning the independent tasks out to parallel subagents\n          where your harness supports it — each task is self-contained and can be\n          built concurrently. Implement EXACTLY the tasks this package describes — no\n          more, no less; leave every other package file untouched. Use TDD\n          discipline within each task.\n\n          Leave the package file in place and everything else uncommitted, then\n          finish your turn.\n        on:\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: <%= it.vars.feedbackFile %>\n        prompt: &suiteFixPrompt |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.feedbackFile %>`; fix it per its\n          contents, or delete it if the feedback turns out to be wrong. Do not\n          create other files to hold notes or output.\n\n          Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n          code so the suite passes. Keep the change focused — do not refactor\n          unrelated code. If the feedback is wrong, empty or delete\n          `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n          Leave everything uncommitted and finish your turn — do not commit.\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\n      fix-spec:\n        actor: agent\n        label: Fixing review feedback\n        file: <%= it.vars.specFeedbackFile %>\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself\n          through its own state files — treat them as its private scratchpad,\n          never as project code or documentation. The only state file this\n          turn touches is `<%= it.vars.specFeedbackFile %>`; address it, then\n          delete it. Do not create other files to hold notes or output.\n\n          Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n          current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n          then fix the code to resolve every concern. Keep the change focused.\n\n          Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n          Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": health.check\n\n      closing:\n        actor: check\n        label: Closing out the package\n        script: |\n          #!/usr/bin/env bash\n          # gtd check turn (the package closer) — remove the just-reviewed package\n          # file (its path is in NEXT.md) plus any leftover spec feedback, so\n          # `picking` selects the NEXT package (or falls through to review when the\n          # queue is empty). Reached on approval (spec review clean) and on the\n          # spec review retry cap (force-close, deferring the concern to the tail).\n          set +e\n          pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n        on:\n          \"* **\": $onNext\n\n      # Per-package health pair: packages.item.health.check/.escalate ->\n      # packages.item.spec.review (green) or packages.item.fix-suite (red).\n      health:\n        machine: healthGate\n        with:\n          onGreen: spec\n          onRed: fix-suite\n          escalateDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` yourself\n            (**packages.item.health.check**).\n          checkLabel: Running checks\n          escalateLabel: Escalating to a human\n\n      # Per-package agentic review: packages.item.spec.review -> closing\n      # (approved), or packages.item.fix-spec (findings — re-verify via the\n      # full health check before re-reviewing).\n      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # ── ENCAPSULATION: the simple flow's build identity ────────────────────────\n  # ▸ coder identity — `model:` declared once here, stamped onto `building`,\n  # `squashing`, `addressing`, and `fix` (its own prompt states). Decomposition\n  # (`design.decompose`) belongs to the planner tier now, not here — see\n  # `advancedPlan` below. `addressing` is the implementer's OWN follow-through\n  # on review feedback (a coder action) — reached via `$onFeedback`, bound at\n  # its own `review:` reference below, not nested inside the (planner-only)\n  # `humanReview` machine. `humanReview` is nested HERE (not at the root) so\n  # the review tail's run stays inside the builder's own scope — see the\n  # header comment.\n  simpleBuild:\n    model: <%= it.vars.coderModel %>\n    params: [onDone]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        file: <%= it.vars.todoFile %>\n        prompt: |\n          You are an autonomous coding agent. This workflow steers itself through\n          its own state files — treat them as its private scratchpad, never as\n          project code or documentation. The only state file this turn touches is\n          `<%= it.vars.todoFile %>`; delete it once its work is complete. Do not\n          create other files to hold notes or output.\n\n          The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n          Read that plan and implement it in full. Use TDD discipline: one test,\n          then the implementation that passes it, then the next — never write all\n          the tests first.\n\n          Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n          and verified. Leave everything else uncommitted and finish your turn.\n        on:\n          \"* **\": health.check\n\n      squashing:\n        actor: agent\n        label: Squashing\n        file: <%= it.vars.commitMsgFile %>\n        prompt: |\n          You are an autonomous coding agent. The process is approved and done. This\n          workflow steers itself through its own state files — treat them as its\n          private scratchpad, never as project code or documentation. The only\n          state file this turn touches is `<%= it.vars.commitMsgFile %>`; write\n          it. Do not create other files to hold notes or output.\n\n          Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n          entering this file squashes everything this process retains into one\n          commit using its content as the message. This prompt carries no diff —\n          if you built that range yourself earlier in this conversation, work from\n          what you already know; otherwise read the range yourself. It runs from\n          `<%= it.retainedBase %>` to the working tree, and is exactly what that\n          commit will contain, the changes THIS process made (its trace/retry\n          boundary onward). For a normal build\n          process that is the whole feature; for a `gtd --entry review-gate.check`\n          process it is only the fixes made during the review — NOT the changeset\n          that was under review.\n\n          If that range is non-empty, write `<%= it.vars.commitMsgFile %>` with ONE\n          conventional-commits message for the changes (subject line\n          `type(scope): subject`, imperative mood, <= 72 characters; a body\n          explaining the why, trade-offs, and key decisions). Plain text, no\n          markdown wrapper.\n\n          If that range is empty (a clean review sign-off with no fixes), write\n          `<%= it.vars.commitMsgFile %>` with exactly this one line and nothing\n          else:\n\n          chore: human review\n        on:\n          \"A <%= it.vars.commitMsgFile %>\": $onDone\n          \"M <%= it.vars.commitMsgFile %>\": $onDone\n\n      addressing:\n        actor: agent\n        label: Addressing your feedback\n        file: <%= it.vars.reviewFeedbackFile %>\n        # Refuse a work-free turn: a step whose only pending change is deleting the\n        # instructions file (the original \"captured then discarded\" bug). The\n        # feedback-progress guard (`src/StepGuards.ts`) reads this flag and\n        # exempts a `NOTHING ACTIONABLE` sentinel (a non-actionable review round,\n        # which legitimately makes no code change). The pure engine carries it inert.\n        requireProgress: true\n        prompt: |\n          You are an autonomous coding agent addressing review feedback. This\n          workflow steers itself through its own state files — treat them as\n          its private scratchpad, never as project code or documentation. The\n          only state file this turn touches is\n          `<%= it.vars.reviewFeedbackFile %>`; address it, then delete it. Do\n          not create other files to hold notes or output.\n\n          The instructions to implement are: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n          This is a flat instruction list, not a diff — execute every item exactly as\n          written, no Q&A, no re-planning, using TDD discipline:\n\n          - An item that says the human's own lines are final: build ON TOP of them to\n            complete only the follow-through it names (callers, tests, types, docs).\n            NEVER revert or rewrite the lines they already committed.\n          - An item derived from a human comment: satisfy it AND delete that comment\n            line from the code (the human's review comments are transient — none of\n            them survive this round).\n\n          If the file's sole content is a `NOTHING ACTIONABLE` line, make no code\n          change; just delete the instructions file.\n\n          Delete `<%= it.vars.reviewFeedbackFile %>` once every item is addressed.\n          Leave everything else uncommitted and finish your turn. Deleting the\n          instructions file WITHOUT making the changes it asks for is refused — the\n          feedback must actually be addressed.\n        on:\n          \"* **\": health.check\n\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: <%= it.vars.feedbackFile %>\n        prompt: *suiteFixPrompt\n        retry:\n          max: 3\n          otherwise: health.escalate\n        on:\n          \"* **\": health.check\n\n      # Shared health pair: build.health.check/.escalate -> build.review.reviewing\n      # (green) or build.fix (red).\n      health:\n        machine: healthGate\n        with:\n          onGreen: review\n          onRed: fix\n          escalateDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` yourself\n            (**build.health.check**).\n          checkLabel: Running checks\n          escalateLabel: Escalating to a human\n\n      # The shared review tail, nested HERE (not at the root) so its run stays\n      # inside the builder's own scope across the feedback round-trip — see\n      # the header comment. Sign-off -> squashing; feedback -> addressing (the\n      # implementer's own coder-identity follow-through, not a reviewer action).\n      review:\n        machine: humanReview\n        with:\n          onSignoff: squashing\n          onFeedback: addressing\n\n  # The root machine — the whole \"advanced/simple\" flow tree described in\n  # this file's header comment. WIRING ONLY: no identity of its own, just the\n  # shared entry/exit states and the top-level machine tree.\n  unified:\n    entry: idle\n    states:\n      # ── Shared entry ────────────────────────────────────────────────────────\n      idle:\n        actor: human\n        label: Idle\n        # Every human-gate `message:` below closes with the same rendered \"What\n        # each change does next\" list, built from `it.edges` (the resting state's\n        # own `on` edges — each edge's `describe:` is the single source of truth).\n        message: |\n          No active gtd process.\n\n          To start one, create a steering file describing what you want built:\n\n          - `<%= it.vars.todoFile %>` — a short sketch — starts the SIMPLE flow\n            (plan, build, review).\n          - `<%= it.vars.requirementsFile %>` — the product requirements — starts\n            the ADVANCED flow (product + technical Q&A, package decomposition,\n            parallel build, per-package agentic review).\n\n          What each change does next (then run `gtd land`):\n          <% it.edges.forEach(function (e) { if (e.describe) { %>\n          <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n          <% } }) %>\n        on:\n          \"* <%= it.vars.requirementsFile %>\":\n            to: spec-gate\n            action: Start advanced flow\n            describe: >-\n              save the product requirements to `.gtd/REQUIREMENTS.md` — gtd first\n              checks the test baseline is green, then the agent develops them\n              through product then technical Q&A, decomposes the work into\n              packages, and builds each in parallel (**spec-gate.check**).\n          \"* **\":\n            to: plan-gate\n            action: Start simple flow\n            describe: >-\n              save a short sketch to `.gtd/TODO.md` (or any other change) — gtd\n              first checks the test baseline is green, then the agent reads it,\n              explores the codebase, and develops it into a concrete\n              implementation plan (**plan-gate.check**).\n\n      # ── Green-baseline gate: `gtd --entry fix-precheck` entry ─────────────────\n      # `gtd --entry fix-precheck` enters HERE: run the suite, then a red run\n      # drops straight into the shared `build.fix` loop (-> build.health.check ->\n      # review + squash tail); a green run is a no-op back to `idle` (nothing\n      # to fix).\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A <%= it.vars.feedbackFile %>\": build.fix\n          \"M <%= it.vars.feedbackFile %>\": build.fix\n          \"D <%= it.vars.feedbackFile %>\": idle\n          \"C\": idle\n\n      # ── Shared tail: the finale ─────────────────────────────────────────────\n      done:\n        commit: |\n          <%~ it.read(it.vars.commitMsgFile) %>\n\n          Token cost: <%= it.processCost %>\n          <% it.processCostByModel.forEach(function(m){ %>\n          - <%= m.model %>: <%= m.cost %>\n          <% }) %>\n\n      # ── Green-baseline gate: simple flow entry. ────────────────────────────────\n      plan-gate:\n        machine: entryGate\n        with:\n          onGreen: plan\n          reviewBase: \"\"\n          blockedMessage: |\n            The test baseline is red — gtd will not start new work on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**plan-gate.check**). To repair the baseline as its own separate\n            reviewed commit instead, abandon this start and run\n            `gtd --entry fix-precheck` from a clean `idle`.\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Green-baseline gate: advanced flow entry. ──────────────────────────────\n      spec-gate:\n        machine: entryGate\n        with:\n          onGreen: design\n          reviewBase: \"\"\n          blockedMessage: |\n            The test baseline is red — gtd will not start new work on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**spec-gate.check**). To repair the baseline as its own separate\n            reviewed commit instead, abandon this start and run\n            `gtd --entry fix-precheck` from a clean `idle`.\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Green-baseline gate: `gtd --entry review-gate.check` entry -> build.review.reviewing. ─\n      review-gate:\n        machine: entryGate\n        with:\n          onGreen: build.review\n          reviewBase: <%= it.vars.reviewBase %>\n          blockedMessage: |\n            The test baseline is red — gtd will not start a review on a broken suite.\n            `<%= it.vars.feedbackFile %>` holds the failing output.\n\n            What each change does next (then run `gtd land`):\n            <% it.edges.forEach(function (e) { if (e.describe) { %>\n            <%~ \"- \" + (e.action ? \"**\" + e.action + \"** — \" : \"\") + e.describe + \"\\n\" %>\n            <% } }) %>\n          blockedDescribe: >-\n            edit the code and/or `.gtd/FEEDBACK.md` to fix the failing tests\n            (**review-gate.check**).\n          checkLabel: Checking the baseline\n          blockedLabel: Baseline is red\n\n      # ── Advanced flow: the design conversation (design.product-author/.product-answer ─\n      # -> design.technical-author/.technical-answer -> design.decompose -> packages). ──\n      design:\n        machine: advancedPlan\n        with:\n          onPackages: packages\n\n      # ── Simple flow plan-iteration loop (plan.planning/.await-plan -> build.building). ──\n      plan:\n        machine: planLoop\n        with:\n          onAccept: build.building\n\n      # ── Advanced per-package build queue (packages.* -> build.review). ────────\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      # ── Simple flow's build identity (build.* -> build.review -> done). ───────\n      build:\n        machine: simpleBuild\n        with:\n          onPackages: packages\n          onDone: done\n";
 //#endregion
 //#region src/workflows/templates.ts
 /**
@@ -192798,6 +192831,7 @@ 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())),
+		gitDir: () => exec("git", "rev-parse", "--absolute-git-dir").pipe(map$4((s) => s.trim())),
 		commitHistory: (base, head = "HEAD") => {
 			const range = base !== void 0 ? `${base}..${head}` : head !== "HEAD" ? head : void 0;
 			const args = [
@@ -192908,6 +192942,79 @@ var CommandRunner = class CommandRunner extends Tag("CommandRunner")() {
 	}));
 };
 //#endregion
+//#region src/Sessions.ts
+/**
+* A conversation's session id is DERIVED, not remembered: `uuidv5(namespace,
+* memoryKey)`, where `memoryKey` (`memoryKeyFor` in `src/Edge.ts`) is already
+* a pure function of history — `<scope>#<anchor7>`, anchored to the commit
+* the current unbroken scope-run began from. Same scope-run → same key → same
+* id → the agent resumes its conversation; a new, unbroken entry into the
+* scope changes the anchor, hence the key, hence the id → a fresh
+* conversation. Nothing is written anywhere, so a peek (`gtd next --json`)
+* and a dispatch derive the exact same id — there is no table to keep in
+* sync, no write to race, no file to go stale.
+*
+* A prompt rest with no memory key (its state is absent from `stateScopes` —
+* possible only for a hand-built definition) keeps the old ephemeral
+* behaviour instead: a random id, `resume: false` — deriving something
+* stable there would resume forever across unrelated processes, and there is
+* no history to anchor a key to anyway.
+*
+* The crash edge: an agent turn that creates session X but lands no commit
+* (a crash, a killed driver) re-derives X on the next lap with the SAME
+* `resume: false` a fresh scope-run would report, so `claude --session-id X`
+* hits "id already in use" the second time around. `resolveSession` can't see
+* that from `memoryKey`/`resume` alone — the fix lives in the driver, which
+* must treat `resume` as a HINT rather than a contract: try the flag `resume`
+* points at first, and fall back to the other on failure —
+*
+*     if [ "$resume" = true ]
+*     then agent_turn --resume || agent_turn --session-id
+*     else agent_turn --session-id || agent_turn --resume
+*     fi
+*
+* — which also makes the inverse mismatch (`resume: true`, id gone: retention
+* expired, `~/.claude/projects` wiped) recover on its own, with no file to
+* delete.
+*/
+/** Fixed forever — every derived session id descends from this one constant. */
+const GTD_SESSION_NAMESPACE = "ca4be249-805e-41c1-8b6a-75a11c011e25";
+const toBytes = (uuid) => Buffer.from(uuid.replace(/-/g, ""), "hex");
+const toUuidString = (bytes) => {
+	const hex = bytes.toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+};
+/**
+* A UUIDv5 (RFC 4122 §4.3): `sha1(namespaceBytes ‖ nameBytes)`, the first 16
+* bytes, with the version nibble forced to `5` and the variant bits forced to
+* `10xx`. Hand-rolled over `node:crypto`'s SHA-1 rather than a dependency, so
+* its correctness is checked directly against the RFC's own DNS-namespace
+* test vector in `Sessions.test.ts` — not against this implementation's own
+* output.
+*/
+const uuidv5 = (namespace, name) => {
+	const bytes = createHash("sha1").update(toBytes(namespace)).update(name, "utf8").digest().subarray(0, 16);
+	bytes[6] = bytes[6] & 15 | 80;
+	bytes[8] = bytes[8] & 63 | 128;
+	return toUuidString(bytes);
+};
+/**
+* Resolve the session id a `prompt` rest's turn should use: `memoryKey ===
+* undefined` mints an ephemeral id via `mint` (defaults to `randomUUID`) and
+* forces `resume: false` — there is no history to derive a stable id from.
+* Otherwise the id is `uuidv5(GTD_SESSION_NAMESPACE, memoryKey)` and `resume`
+* is passed through verbatim (the caller — `src/Edge.ts`'s
+* `memoryResumedFor` — already computed it from the same trace the key came
+* from).
+*/
+const resolveSession = (memoryKey, resume, mint = randomUUID) => memoryKey === void 0 ? {
+	sessionId: mint(),
+	resume: false
+} : {
+	sessionId: uuidv5(GTD_SESSION_NAMESPACE, memoryKey),
+	resume
+};
+//#endregion
 //#region node_modules/eta/dist/index.mjs
 var EtaError = class extends Error {
 	constructor(message) {
@@ -193473,13 +193580,6 @@ const withHistoryTrailer = (subject, hash) => `${subject}\n\n${HISTORY_TRAILER_P
 * by a later `gtd restore` command to recover the pre-squash tip.
 */
 const parseHistoryTrailer = (message) => HISTORY_TRAILER_RE.exec(message)?.[1];
-/**
-* Record the pre-squash tip so a later `gtd restore` can find it. A no-op
-* (the git call is skipped entirely) when `tipHash === startParentHash`: an
-* empty process — no turns were ever committed — has no turn chain worth
-* keeping.
-*/
-const retainHistory = (git, tipHash, startParentHash) => tipHash === startParentHash ? _void : git.updateRef(HISTORY_REF, tipHash);
 /** A thin wrapper over `git.readRefOption(HISTORY_REF)`. */
 const readRetainedHistory = (git) => git.readRefOption(HISTORY_REF);
 /**
@@ -193514,9 +193614,10 @@ const restorability = (git, headHash, headMessage, tipHash) => gen(function* ()
 /**
 * 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.
+* `string` instead of executing it. THE emission path: every git write gtd
+* decides reaches the repository as one of these strings, assembled by
+* `src/Emit.ts` and run by an external driver — gtd itself never executes
+* them.
 *
 * 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.
@@ -193607,6 +193708,143 @@ const restoreStagedFrom = (source, paths) => {
 	].join("\n");
 };
 //#endregion
+//#region src/OutcomeScript.ts
+/**
+* The human-facing wording for what a `gtd`-emitted script just landed —
+* printed by the DRIVER's bash when it runs `required`/`optional`, authored
+* once here in TS. Pure, like `src/GitScript.ts`: no git, no filesystem, no
+* `Effect`. `OUTCOME_PREAMBLE` defines the bash functions
+* (`gtd_report_transition`/`gtd_report_commit`/`gtd_report_note`/
+* `gtd_report_abandoned`/`gtd_report_restored`) a script calls; the builders
+* below emit the one-line calls, every argument routed through
+* `src/GitScript.ts`'s `shellQuote`.
+*
+* `noopText`/`abandonNoopText` render the shared no-op wording; both reach the
+* driver only through an emitted script now (`noteOutcome(noopText(state))`
+* for a genuine `gtd land` no-op, `abandonNoopOutcome` for `gtd abandon` with
+* nothing underway) — a no-op's script always prints itself, exactly like
+* every other outcome, rather than `src/program.ts` special-casing an empty
+* script. Their format strings live once here (`FMT_*`, with
+* `%s` placeholders) and reach both sides through `renderFormat` (the plain
+* path) and `printfLine` (the bash `printf` call embedded in
+* `OUTCOME_PREAMBLE`), so the two can never drift.
+*/
+/** Substitute `args` into `fmt`'s `%s` placeholders, in order — the plain-text twin of `printfLine`. */
+const renderFormat = (fmt, ...args) => {
+	let i = 0;
+	return fmt.replace(/%s/g, () => args[i++] ?? "");
+};
+/**
+* A `printf '<fmt>' <args...>` bash statement — `args` are already-valid bash
+* tokens (a variable reference like `"$from"`), never re-quoted here: a value
+* reaches the script as a printf ARGUMENT, never interpolated into the format
+* itself, so a subject or state name containing `%` can never be read as a
+* conversion spec.
+*/
+const printfLine = (fmt, args) => `printf ${shellQuote(fmt)} ${args.join(" ")}`;
+const FMT_NOOP = "nothing to do at \"%s\"\n";
+const FMT_ABANDON_NOOP = "no gtd process is underway (resting at \"%s\") — nothing to abandon\n";
+const FMT_ABANDONED = "abandoned the process resting at \"%s\" — HEAD is back at %s (\"%s\"), resting at \"%s\".\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";
+const FMT_RESTORED = "restored the retained history — HEAD is back at %s (\"%s\"), resting at \"%s\". Resume with the loop, or `git reset` to any earlier turn to restart from there.\n";
+/** `nothing to do at "<state>"` — a no-op step's plain-text line, and the text a print-only script's `gtd_report_note` carries. */
+const noopText = (state) => renderFormat(FMT_NOOP, state);
+/** The initial-state collapse's own line — no commit landed, HEAD was rewound
+*  to the process's start parent. Trailing newline, exactly like `noopText`:
+*  printed verbatim by `program.ts` and via `noteOutcome`/`gtd_report_note` by
+*  the emitted script. */
+const COLLAPSED_TEXT = "nothing to retain — rewound to the commit before the process started\n";
+/** `no gtd process is underway (resting at "<initial>") — nothing to abandon` — `gtd abandon`'s no-op plain-text line. */
+const abandonNoopText = (initial) => renderFormat(FMT_ABANDON_NOOP, initial);
+/**
+* The bash preamble every outcome-carrying script includes, ONE block (no
+* blank lines, like `src/Emit.ts`'s `RETRY_HELPER`) so `assembleScript`'s
+* blank-line-joined sections stay intact. First line is a literal comment
+* naming this module, so a reader (or the recognizer) can tell at a glance
+* where the block comes from.
+*
+* The palette/marker detection follows the `NO_COLOR` convention
+* (`[ -t 1 ] && [ -z "${NO_COLOR:-}" ]`) with the same plain-mode fallback
+* strings (`->`/`[commit]`/`...`) the now-deleted bash `bin/gtd` used to
+* render, so existing `@live` assertions on plain output kept matching once
+* this preamble took over printing it. `gtd_files` is the diff-tree read
+* (with `--root` so a repository's very first commit shows its files too)
+* plus the 3-row cap, fused into one function, since a script-side caller
+* always has the commit, never a pre-fetched file list.
+*/
+const OUTCOME_PREAMBLE = [
+	"# gtd: human-facing outcome rendering (see src/OutcomeScript.ts)",
+	"if [ -t 1 ] && [ -z \"${NO_COLOR:-}\" ]; then",
+	"  gtd_c_reset=$'\\e[0m'; gtd_c_bold=$'\\e[1m'; gtd_c_dim=$'\\e[2m'",
+	"  gtd_c_cyan=$'\\e[36m'; gtd_c_green=$'\\e[32m'",
+	"  gtd_m_trans=\"➡️\"; gtd_m_commit=\"✅\"; gtd_m_ellipsis=\"…\"",
+	"else",
+	"  gtd_c_reset=\"\"; gtd_c_bold=\"\"; gtd_c_dim=\"\"",
+	"  gtd_c_cyan=\"\"; gtd_c_green=\"\"",
+	"  gtd_m_trans=\"->\"; gtd_m_commit=\"[commit]\"; gtd_m_ellipsis=\"...\"",
+	"fi",
+	"gtd_files() {",
+	"  local sha=\"$1\" f shown=0 total=0 files",
+	"  files=\"$(git diff-tree --no-commit-id --name-only -r --root \"$sha\" 2>/dev/null || true)\"",
+	"  [ -z \"$files\" ] && return 0",
+	"  while IFS= read -r f; do [ -n \"$f\" ] && total=$((total + 1)); done < <(printf '%s\\n' \"$files\")",
+	"  while IFS= read -r f; do",
+	"    [ -z \"$f\" ] && continue",
+	"    if [ \"$shown\" -ge 3 ]; then",
+	"      printf '   %s%s (%d more)%s\\n' \"$gtd_c_dim\" \"$gtd_m_ellipsis\" \"$((total - 3))\" \"$gtd_c_reset\"",
+	"      break",
+	"    fi",
+	"    printf '   %s%s%s\\n' \"$gtd_c_dim\" \"$f\" \"$gtd_c_reset\"",
+	"    shown=$((shown + 1))",
+	"  done < <(printf '%s\\n' \"$files\")",
+	"}",
+	"gtd_report_transition() {",
+	"  local from=\"$1\" to=\"$2\"",
+	"  printf '%s %s%s → %s%s\\n' \"$gtd_m_trans\" \"${gtd_c_bold}${gtd_c_cyan}\" \"$from\" \"$to\" \"$gtd_c_reset\"",
+	"  gtd_files HEAD",
+	"}",
+	"gtd_report_commit() {",
+	"  local subject=\"$1\"",
+	"  printf '%s %s%s%s\\n' \"$gtd_m_commit\" \"$gtd_c_green\" \"$subject\" \"$gtd_c_reset\"",
+	"  gtd_files HEAD",
+	"}",
+	"gtd_report_note() {",
+	"  printf '%s\\n' \"$1\"",
+	"}",
+	"gtd_report_abandoned() {",
+	"  local from=\"$1\" head=\"$2\" state=\"$3\" short subject",
+	"  short=\"$(git rev-parse --short \"$head\")\"",
+	"  subject=\"$(git log -1 --format=%s \"$head\")\"",
+	`  ${printfLine(FMT_ABANDONED, [
+		"\"$from\"",
+		"\"$short\"",
+		"\"$subject\"",
+		"\"$state\""
+	])}`,
+	"}",
+	"gtd_report_restored() {",
+	"  local to=\"$1\" state=\"$2\" short subject",
+	"  short=\"$(git rev-parse --short \"$to\")\"",
+	"  subject=\"$(git log -1 --format=%s \"$to\")\"",
+	`  ${printfLine(FMT_RESTORED, [
+		"\"$short\"",
+		"\"$subject\"",
+		"\"$state\""
+	])}`,
+	"}"
+].join("\n");
+/** `gtd_report_transition <from> <to>` — a landed self-loop/target-change transition, with its changed-file rows. */
+const transitionOutcome = (from, to) => `gtd_report_transition ${shellQuote(from)} ${shellQuote(to)}`;
+/** `gtd_report_commit <subject>` — a bare capture or a squash's final commit, with its changed-file rows. */
+const commitOutcome = (subject) => `gtd_report_commit ${shellQuote(subject)}`;
+/** `gtd_report_note <text>` — one already-rendered plain line, no marker. */
+const noteOutcome = (text) => `gtd_report_note ${shellQuote(text)}`;
+/** `gtd_report_abandoned <from> <head> <state>` — resolves the post-hoc short hash/subject from `head` (a commitish) in-script. */
+const abandonedOutcome = (from, head, state) => `gtd_report_abandoned ${shellQuote(from)} ${shellQuote(head)} ${shellQuote(state)}`;
+/** `gtd abandon`'s no-op outcome — the same wording `abandonNoopText` renders, printed via `gtd_report_note`. */
+const abandonNoopOutcome = (initial) => noteOutcome(abandonNoopText(initial));
+/** `gtd_report_restored <to> <state>` — resolves the post-hoc short hash/subject from `to` (a commitish) in-script. */
+const restoredOutcome = (to, state) => `gtd_report_restored ${shellQuote(to)} ${shellQuote(state)}`;
+//#endregion
 //#region src/Emit.ts
 /**
 * Assembles the two scripts a `gtd next`-time decision hands the external
@@ -193616,7 +193854,11 @@ const restoreStagedFrom = (source, paths) => {
 * 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.
+* arrives already rendered — this module only concatenates and wraps: once
+* for a `gitWrite` step's index-lock retry (`gtd_retry`), and once for a
+* `command` step's `onFailure` fix prompt (`failurePromptWrapper`), which
+* prints a ready-to-send instruction plus the command's captured output
+* ahead of propagating its exit code.
 *
 * 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
@@ -193668,6 +193910,29 @@ const reviewWindowAssertion = (ref, 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; }`;
 };
 /**
+* Wraps `command` so that a non-zero exit prints `prompt` (the ready-to-send
+* fix instruction), a blank line, then the command's own captured combined
+* output, before propagating the command's exit code — rather than letting
+* that output escape raw. The `{ … }` GROUP (not a bare command
+* substitution) is what lets a MULTI-LINE `command` be inlined verbatim
+* inside it; the assignment sits on the left of `||`, so `set -e` never trips
+* on the failing command itself. Exported (alongside `headAssertion`) solely
+* so `src/testing/EmittedScriptRecognizer.ts` can re-derive and
+* string-compare this exact shape.
+*/
+const failurePromptWrapper = (command, prompt) => {
+	return [
+		`gtd_validate_status=0`,
+		`gtd_validate_out="$( {`,
+		command,
+		`} 2>&1 )" || gtd_validate_status=$?`,
+		`if [ "$gtd_validate_status" -ne 0 ]; then`,
+		`  printf '%s\\n\\n%s\\n' ${shellQuote(prompt)} "$gtd_validate_out"`,
+		`  exit "$gtd_validate_status"`,
+		`fi`
+	].join("\n");
+};
+/**
 * `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
@@ -193706,13 +193971,18 @@ const RETRY_HELPER = [
 	`  done`,
 	`}`
 ].join("\n");
-const renderStep = (step) => step.kind === "gitWrite" ? `gtd_retry ${shellQuote(step.command)}` : step.command;
+const renderStep = (step) => {
+	if (step.kind === "gitWrite") return `gtd_retry ${shellQuote(step.command)}`;
+	if (step.kind === "command" && step.onFailure !== void 0) return failurePromptWrapper(step.command, step.onFailure);
+	return 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);
+	if (steps.some((step) => step.kind === "outcome")) sections.push(OUTCOME_PREAMBLE);
 	sections.push(...steps.map(renderStep));
 	return sections.join("\n\n");
 };
@@ -193728,6 +193998,32 @@ const emitScripts = (preconditions, required = [], optional = []) => ({
 	required: assembleScript(preconditions, required),
 	optional: assembleScript(preconditions, optional)
 });
+const DID_NOT_RUN_COMMENT = "# gtd emitted this and did NOT run it — pipe it into `bash` to land the turn";
+const PRESENTATION_ONLY_COMMENT = "# presentation only — safe to skip";
+const PRESENTATION_FAILURE_WARNING = "echo \"gtd: presentation-only follow-up failed — continuing\" >&2";
+/**
+* A plain-text (no `--json`) write command's single pasteable script: `gtd
+* land | bash` lands the turn without ever separating `required` from
+* `optional`. `required` runs verbatim (its own `set -euo pipefail` aborts
+* before `optional` ever starts if it fails); `optional`, when non-empty, is
+* wrapped in a subshell whose failure is swallowed — presentation-only, so it
+* must never turn a landed turn into a non-zero exit. Empty when `required`
+* is — unreachable in practice today (every caller's `required` is always
+* non-empty, even a genuine no-op's print-only note), kept as the function's
+* own total behavior rather than assumed by every caller.
+*/
+const combinedScript = (required, optional) => {
+	if (required.length === 0) return "";
+	if (optional.length === 0) return `${DID_NOT_RUN_COMMENT}\n\n${required}`;
+	return [
+		DID_NOT_RUN_COMMENT,
+		"",
+		required,
+		"",
+		PRESENTATION_ONLY_COMMENT,
+		`(\n${optional}\n) || ${PRESENTATION_FAILURE_WARNING}`
+	].join("\n");
+};
 //#endregion
 //#region src/Edge.ts
 /**
@@ -193810,8 +194106,8 @@ const parseCostTrailers = (messages) => {
 const REVIEW_BASE_TRAILER_PREFIX = "Gtd-Review-Base: ";
 const REVIEW_BASE_TRAILER_RE = /^Gtd-Review-Base:[ \t]*(\S+)[ \t]*$/m;
 /**
-* The `Gtd-Review-Base: <hash>` trailer recorded on a `gtd step <actor>
-* --entry <state>` entry commit (see `withEntryTrailers`), or `undefined`
+* The `Gtd-Review-Base: <hash>` trailer recorded on a `gtd --entry <state>`
+* entry commit (see `withEntryTrailers`), or `undefined`
 * when `message` carries none. Read back by `computeProcessRun` — ONLY off
 * the process's first (oldest) commit — to override the run's diff base.
 */
@@ -193906,6 +194202,27 @@ const pendingChanges = (git, base) => git.changedPaths(base).pipe(map$4((entries
 	path: e.path
 }))));
 /**
+* `ProcessRun.headTurn` from an already-fetched `commitHistory` array
+* (oldest→newest) — HEAD is its last entry. `undefined` for an empty
+* history, an unparseable/foreign subject, or a subject naming a state the
+* ACTIVE definition doesn't declare (removed by a workflow change) or that
+* IS a commit state (never a real rest — see `resolveState`'s own doc
+* comment on why a commit-state subject is never trusted at face value).
+*/
+const headTurnFrom = (def, history) => {
+	if (history.length === 0) return void 0;
+	const head = history[history.length - 1];
+	const parsed = parseStateSubject(subjectOf(head.message));
+	if (parsed === void 0) return void 0;
+	const stateDef = def.states[parsed.state];
+	if (stateDef === void 0 || isCommitState(stateDef)) return void 0;
+	return {
+		state: parsed.state,
+		actor: parsed.actor,
+		empty: head.touched.length === 0
+	};
+};
+/**
 * The `Gtd-Review-Base:`/`Gtd-Var:` overrides carried by the process's OLDEST
 * commit (its entry commit, when `planEntry` started this process) — a later
 * turn's message is never mistaken for it. `{reviewBase: undefined, vars:
@@ -193958,7 +194275,8 @@ const computeProcessRun = (git, def, hasCommits, head) => gen(function* () {
 		diffBase: EMPTY_TREE$2,
 		trace: [],
 		costEntries: [],
-		entryVars: {}
+		entryVars: {},
+		headTurn: void 0
 	};
 	const initialState = initialStateOf(def);
 	const history = yield* git.commitHistory(void 0, head);
@@ -193984,7 +194302,8 @@ const computeProcessRun = (git, def, hasCommits, head) => gen(function* () {
 		diffBase: reviewBaseOverride ?? startParentHash,
 		trace,
 		costEntries,
-		entryVars
+		entryVars,
+		headTurn: headTurnFrom(def, history)
 	};
 });
 /**
@@ -194053,6 +194372,35 @@ const memoryKeyFor = (scopes, rest, run) => {
 	const token = entryIndex <= 0 ? run.startParentHash : run.trace[entryIndex - 1].hash;
 	return `${scope || ROOT_MEMORY_SCOPE_NAME}#${token.slice(0, 7)}`;
 };
+/**
+* True iff a `prompt` rest in the CURRENT unbroken scope-run has already been
+* passed — the derivation `src/Sessions.ts`'s `resolveSession` takes its
+* `resume` flag from. `false` for any non-`prompt` rest, or when `rest.state`
+* resolves no scope at all (mirrors `memoryKeyFor`'s own two escape hatches).
+*
+* Computed over the process's rests, oldest→newest, with the process's own
+* starting state (`initialStateOf(def)`) prefixed: `run.trace`'s last entry is
+* already the current rest (a `Rest` is a snapshot of a fully-resolved state,
+* never an in-flight turn), so prefixing the ONE state before the trace began
+* is all that's missing. The prefix matters for a workflow whose
+* `entries.default` IS a prompt state — without it, the very first turn there
+* would have no predecessor to look back at.
+*
+* The root scope (`scope === ""`) matches every state, so a workflow like
+* `idle → working` puts `idle` inside `working`'s scope-run — the very first
+* agent beat of a process would otherwise claim `resume: true` for an id
+* nobody ever created. Filtering the "prior rests" slice down to `prompt`-kind
+* states (not merely non-empty) closes that hole: a message state like `idle`
+* never counts as a prior conversation turn.
+*/
+const memoryResumedFor = (def, scopes, rest, run) => {
+	if (contentKindOf(rest.stateDef) !== "prompt") return false;
+	const rests = [initialStateOf(def), ...run.trace.map((entry) => entry.state)];
+	const resolved = memoryScopeAt(scopes, rest.state, rests);
+	if (resolved === void 0) return false;
+	const { entryIndex } = resolved;
+	return rests.slice(Math.max(entryIndex, 0), rests.length - 1).some((state) => contentKindOf(def.states[state]) === "prompt");
+};
 const PREFIX = "GTD_";
 /**
 * Assemble the merged `it.vars` map every template sees, from four layers
@@ -194060,7 +194408,7 @@ const PREFIX = "GTD_";
 * (`ConfigOperations.workflowVars`), the top-level `.gtdrc` `vars:` key
 * (`ConfigOperations.rcVars`), the current process's entry commit's
 * `Gtd-Var:` trailers (`ProcessRun.entryVars` — fixed overrides recorded at
-* the moment a process like `gtd step <actor> --entry <state>` started it),
+* the moment a process like `gtd --entry <state>` started it),
 * and — for each name declared by any of those three layers — a
 * `GTD_<UPPERCASE-name>` environment variable, if defined. Unlike the first
 * three layers, the environment can only OVERRIDE a name some earlier layer
@@ -194238,6 +194586,7 @@ const restAt = (ref) => gen(function* () {
 	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 memoryResumed = memoryResumedFor(def, config.stateScopes, resolved, run);
 	const hints = yield* renderHints(resolved.stateDef, context);
 	return {
 		...resolved,
@@ -194247,6 +194596,7 @@ const restAt = (ref) => gen(function* () {
 		stepDef,
 		changes,
 		memory,
+		memoryResumed,
 		hints,
 		context
 	};
@@ -194305,11 +194655,39 @@ const renderRest = (rest) => gen(function* () {
 		content,
 		...rest.hints,
 		...rest.memory !== void 0 ? { memory: rest.memory } : {},
+		memoryResumed: rest.memoryResumed,
 		edges: rest.context.edges
 	};
 });
-/** The user-facing message for a `step` refusal — out-of-turn names the awaited actor, no-match names every declared pattern. */
-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)"}`;
+/**
+* Derived stall detection: PURE, no `Effect` — a plain fold over `rest`'s
+* already-resolved snapshot, restart-proof by construction (any process that
+* re-resolves the same HEAD reaches the same verdict). `true` iff ALL of:
+*
+* - the working tree is clean (a dirty tree is always an in-progress turn,
+*   never a stall — this is the recovery story: a human fixing the cause out
+*   of band clears the stall by touching the repo);
+* - HEAD's own commit already rests AT `rest.state` (`run.headTurn.state ===
+*   rest.state` — the previous dispatch's attempt landed here) and that
+*   commit's diff was EMPTY (`run.headTurn.empty`);
+* - ANOTHER dispatch right now would just repeat the same fruitless attempt
+*   (`wouldAttempt` — false once a retry cap would redirect it elsewhere
+*   instead, which is the escalation path OUT of a stall).
+*
+* Sticky by design (decision 4): resolving `true` twice in a row is the
+* correct, restart-proof answer, not a bug — the marker it replaces used to
+* consume itself on report; this doesn't, because there is no longer any
+* mutation to gate a "one-shot" report on.
+*/
+const stalledAt = (rest) => rest.changes.length === 0 && rest.run.headTurn?.state === rest.state && rest.run.headTurn.empty && rest.run.headTurn.actor === rest.actor && wouldAttempt(rest.stepDef, rest.state, rest.run.trace.map((entry) => entry.state));
+/**
+* The user-facing message for a `land` refusal — out-of-turn names the
+* awaited actor, no-match names every declared pattern. `land` derives its
+* invoker from `rest.actor` itself (see `planStep`), so out-of-turn is
+* unreachable by construction there; this branch stays reachable only via
+* `PatternMachine.step`'s own tests (a defensive message beats a lie).
+*/
+const formatStepRefusal = (refusal) => refusal.reason === "out-of-turn" ? `gtd land: out of turn — "${refusal.state}" awaits ${refusal.awaits}` : `gtd land: 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. A squash's commit
@@ -194317,7 +194695,7 @@ const formatStepRefusal = (invoker, refusal) => refusal.reason === "out-of-turn"
 * `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
+* `--cost`. Exported for `program.ts`'s `planLanding`, which assembles the
 * same script by hand and must pick the same context.
 */
 const contextAt = (rest, targetState, invoker, cost, model) => gen(function* () {
@@ -194328,117 +194706,129 @@ const contextAt = (rest, targetState, invoker, cost, model) => gen(function* ()
 	return yield* buildTemplateContext(git, templateRead(files), targetState, invoker, rest.run, rest.vars, onEdges, cost ?? 0, model, reviewBaseFor(rest.def, rest.run), hasCommits);
 });
 /**
-* Execute a `"commit"`/`"squash"` decision: a `"commit"` decision stages and
-* commits everything pending under the decided subject, with an optional
-* `Gtd-Cost: <cost>[ <model>]` trailer; a `"squash"` decision renders the
-* commit-state template against the PENDING tree — a render failure REFUSES
-* the step, touching nothing — then records the pre-squash tip on the
-* retained-history ref (`retainHistory`, a no-op for an empty process) before
-* soft-resetting to the process's start parent, writes ONE commit with the
-* rendered message plus a `Gtd-History: <hash>` trailer pointing at that tip,
-* and discards everything left pending (the template file included). The
-* whole-process total and per-model breakdown reach the message through
-* `it.processCost`/`it.processCostByModel` in the rendered template.
-*/
-const executeDecision = (git, run, decision, context, cost, model) => gen(function* () {
-	switch (decision.kind) {
-		case "commit":
-			yield* git.commitAllWithPrefix(withCostTrailer(decision.subject, cost, model));
-			return {
-				kind: "commit",
-				subject: decision.subject
-			};
-		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");
-			yield* retainHistory(git, tip, run.startParentHash);
-			yield* git.softResetTo(run.startParentHash);
-			yield* git.commitAsIs(withHistoryTrailer(message, tip));
-			yield* git.discardPending();
-			return {
-				kind: "squash",
-				subject: subjectOf(message)
-			};
-		}
-	}
-});
-/**
 * 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.
+* driver runs to produce its git effect — the ONE place a decision becomes
+* git commands. Every git call here is a READ (`git.resolveRef("HEAD")` for
+* the squash branch's pre-squash tip); nothing is written — gtd itself never
+* writes git, only a driven script does.
 *
 * 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
+* tree — a render failure fails this Effect, 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 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, discard-pending, then a
+* trailing `commitOutcome` naming the rendered message's bare subject line —
+* the script's own report, printed as it runs.
+*
+* The commit branch carries 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.
+* than dirtying the log with a round trip to `idle` — this COLLAPSE case
+* prints `COLLAPSED_TEXT` via a `gtd_report_note`, never a `gtd_report_commit`:
+* no commit lands, so there is nothing to report by reading `HEAD`'s files —
+* that read would list the pre-process commit's unrelated files instead.
+* 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. The ordinary commit
+* path's own trailing outcome is a `transitionOutcome` when the decided
+* subject moves to a DIFFERENT state than it started from, else a
+* `commitOutcome` naming the bare (never cost-trailer'd) subject.
+*/
+/** `updateRef(HISTORY_REF, tip)` as a single-element (or empty) step list — OMITTED when `tip === startParentHash`, mirroring `retainHistory`'s own no-op check. Shared by the squash branch and the commit branch's collapse case below. */
+const retainHistoryStep = (tip, startParentHash) => tip === startParentHash ? [] : [{
+	kind: "gitWrite",
+	command: updateRef(HISTORY_REF, tip)
+}];
+/** The commit branch's own trailing outcome: a bare `commitOutcome` for a self-loop (`from === to`), else a `transitionOutcome` naming both states. */
+const commitDecisionOutcome = (decision) => ({
+	kind: "outcome",
+	command: decision.from === decision.to ? commitOutcome(decision.subject) : transitionOutcome(decision.from, decision.to)
+});
+/**
+* True for a `"commit"` decision that is the "green re-entry into the initial
+* state retaining nothing" collapse — the process's target is the workflow's
+* initial state, it started somewhere other than the empty tree, and nothing
+* pending or already-committed since its start parent survives
+* (`retainsNothing`). Always `false` for a `"squash"` decision (a squash's
+* target is never the initial state by construction) and for an ATTEMPT
+* (`decision.attempt === true`, per decision 5): an agent that did nothing
+* must never rewind a process — the collapse is for a green re-entry that
+* retained nothing, not for a fruitless turn, and an attempt landing at the
+* initial state (a prompt state that also happens to be where the workflow
+* starts) would otherwise satisfy every OTHER criterion here identically to a
+* genuine collapse. The ONE predicate `renderDecision`'s emitted-script
+* branch calls — `program.ts`'s `planLanding` asks the same question,
+* through the exported `collapsesToInitialState` below, at the same moment,
+* so the two can never decide differently about the same run.
+*/
+const collapsesWith = (git, rest, decision) => gen(function* () {
+	if (decision.kind === "squash" || decision.attempt === true) return false;
+	return parseStateSubject(decision.subject)?.state === initialStateOf(rest.def) && rest.run.startParentHash !== EMPTY_TREE$2 && (yield* retainsNothing(git, rest.run, rest.changes));
+});
+/**
+* The service-requiring twin of `collapsesWith`, for `program.ts` to ask
+* instead of reaching into `GitService` itself — the boundary AGENTS.md pins.
+* `planLanding` calls this to fill `LandResult.settled` for a `"commit"`/
+* `"squash"` plan, off the same `rest`/`decision` `renderDecision` already
+* decided against, so the two git reads (`changedPathsSince` + `resolveRef`)
+* can never disagree with each other.
 */
+const collapsesToInitialState = (rest, decision) => gen(function* () {
+	const git = yield* GitService;
+	return yield* collapsesWith(git, rest, decision);
+});
 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))) {
+			if (yield* collapsesWith(git, rest, decision)) {
 				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 [
+					...retainHistoryStep(tip, run.startParentHash),
+					{
+						kind: "gitWrite",
+						command: mixedResetTo(run.startParentHash)
+					},
+					{
+						kind: "outcome",
+						command: noteOutcome(COLLAPSED_TEXT)
+					}
+				];
 			}
 			return [{
 				kind: "gitWrite",
 				command: commitAll(withCostTrailer(decision.subject, cost, model))
-			}];
+			}, commitDecisionOutcome(decision)];
 		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;
+			return [
+				...retainHistoryStep(tip, run.startParentHash),
+				{
+					kind: "gitWrite",
+					command: softResetTo(run.startParentHash)
+				},
+				{
+					kind: "gitWrite",
+					command: commitAsIs(withHistoryTrailer(message, tip))
+				},
+				{
+					kind: "gitWrite",
+					command: discardPending()
+				},
+				{
+					kind: "outcome",
+					command: commitOutcome(subjectOf(message))
+				}
+			];
 		}
 	}
 });
@@ -194479,64 +194869,57 @@ const buildStepScripts = (git, rest, decision, context, cost, model) => gen(func
 	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.
-* `opts.cost`/`opts.model` ride along for the `Gtd-Cost:` trailer and the
-* squash template's folded `it.processCost`/`it.processCostByModel`.
-*
-* `perform` itself, in order: the "returned to the initial state retaining
-* nothing" mixed-reset branch (a green re-entry into the initial state that
-* kept nothing useful is rewound like `gtd abandon` rather than committed),
-* else `executeDecision` — against `rest.context` for a commit (which never
-* 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 = {}) => gen(function* () {
-	const decision = step(rest.stepDef, rest.state, invoker, {
+* A no-op is TERMINAL only at a `script` rest: gtd rendered the script, the
+* driver ran it, it left nothing any pattern claims, and re-running it can't
+* change that — the loop should exit rather than spin (`gtd land`'s exit-3
+* `settled` signal). A `prompt` rest can no longer produce a no-op at all (a
+* clean tree with no `C` row there is an ATTEMPT commit instead — see
+* `PatternMachine.step`'s doc comment — and `stalledAt` is its own, separately
+* reported signal). A no-op at a `message` rest is a human gate the loop
+* already halts on (`kind: "message"`), so it needs no signal either. This is
+* one of TWO settled shapes — the other is the initial-state collapse
+* (`collapsesWith`/`collapsesToInitialState`), decided independently by
+* `program.ts`'s `planLanding` for a `"commit"`/`"squash"` plan.
+*/
+const noOpSettles = (rest) => contentKindOf(rest.stateDef) === "script";
+/**
+* Decide what landing at `rest` does (`PatternMachine.step` over
+* `rest.stepDef`/`rest.changes`/`rest.run.trace`, authenticated as
+* `rest.actor` — the state's own declared actor, so out-of-turn is
+* unreachable by construction), and — for a `"commit"`/`"squash"` decision —
+* assemble the emitted `scripts` a driver runs to land it (against
+* `rest.context` for a commit, or a freshly built `contextAt` for a squash,
+* which renders a DIFFERENT state's template with the step's cost folded
+* in). `opts.cost`/`opts.model` ride along for the `Gtd-Cost:` trailer and
+* the squash template's folded `it.processCost`/`it.processCostByModel`.
+*/
+const planStep = (rest, opts = {}) => gen(function* () {
+	const decision = step(rest.stepDef, rest.state, rest.actor, {
 		changes: rest.changes,
 		processTrace: rest.run.trace.map((entry) => entry.state)
 	});
 	if (decision.kind === "refusal") return {
 		kind: "refusal",
-		message: formatStepRefusal(invoker, decision)
+		message: formatStepRefusal(decision)
 	};
 	if (decision.kind === "noop") return {
 		kind: "noop",
-		state: decision.state
+		state: decision.state,
+		settled: noOpSettles(rest)
 	};
 	const { cost, model } = opts;
-	const perform = gen(function* () {
-		const git = yield* GitService;
-		if (decision.kind === "commit") {
-			const target = parseStateSubject(decision.subject)?.state;
-			if (target === initialStateOf(rest.def) && rest.run.startParentHash !== EMPTY_TREE$2 && (yield* retainsNothing(git, rest.run, rest.changes))) {
-				yield* retainHistory(git, yield* git.resolveRef("HEAD"), rest.run.startParentHash);
-				yield* git.mixedResetTo(rest.run.startParentHash);
-				return {
-					kind: "reset",
-					state: target
-				};
-			}
-			return yield* executeDecision(git, rest.run, decision, rest.context, cost, model);
-		}
-		const context = yield* contextAt(rest, decision.state, invoker, cost, model);
-		return yield* executeDecision(git, rest.run, decision, context, cost, model);
-	});
 	const git = yield* GitService;
-	const scriptContext = decision.kind === "commit" ? rest.context : yield* contextAt(rest, decision.state, invoker, cost, model);
+	const scriptContext = decision.kind === "commit" ? rest.context : yield* contextAt(rest, decision.state, rest.actor, cost, model);
 	const scripts = yield* buildStepScripts(git, rest, decision, scriptContext, cost, model);
 	return {
 		kind: decision.kind,
 		state: rest.state,
 		decision,
-		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
+* `gtd --entry <state>`: start a brand NEW process at `entry.state` — any
 * declared, non-commit state (see `enterableStates`) — writing an ordinary
 * turn commit (`gtd(<actor>): <state>`) carrying zero or more `Gtd-Var:
 * <name>=<value>` trailers for each `entry.vars` override, plus — when
@@ -194544,7 +194927,7 @@ const planStep = (rest, invoker, opts = {}) => gen(function* () {
 * trailer pinning the new process's diff base (rendered from that template
 * against the merged `it.vars`, resolved to a commit, and checked sane).
 * Commits via `commitAllWithPrefix` — capturing whatever the working tree
-* carries at the moment of entry, exactly like an ordinary step capture,
+* carries at the moment of entry, exactly like an ordinary land capture,
 * rather than demanding a clean tree first.
 *
 * All validation is a REFUSAL, not an Effect failure — checked in order:
@@ -194617,23 +195000,17 @@ 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,
 		scripts: emitScripts(yield* buildPreconditions(scriptsGit, rest, entryState), [{
 			kind: "gitWrite",
 			command: commitAll(message)
+		}, {
+			kind: "outcome",
+			command: commitOutcome(subject)
 		}])
 	};
 });
@@ -205942,7 +206319,7 @@ const renderSteeringCommands = (resolved, file, context) => gen(function* () {
 * mode with no built-in format at all (a workflow-only name, or a declared
 * `{}` entry) dispatches to no symbols, no actions, and no diagnostics. Either
 * way the file is still formatted and validated by `gtd validate` and the
-* `gtd step` capture gate — just not live in the editor.
+* `gtd land` capture gate — just not live in the editor.
 *
 * `gtd.openSteeringFile` (an `executeCommand`) resolves the CURRENT state
 * exactly like the CLI (`resolveRest`/`computeProcessRun`/
@@ -206619,15 +206996,16 @@ const stepGuards = [
 	}
 ];
 /**
-* The `gtd step` capture gate: run every guard the resolved rest's state
+* The `gtd land` capture gate: run every guard the resolved rest's state
 * 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
-* state with no `file:`, or a state no guard applies to.
+* `gtd land: ` (the one place that prefix, and the `cliErrorLine`
+* `/^gtd[: ]/` contract, is satisfied). A no-op for a squash/no-op decision, an
+* ATTEMPT commit (`input.attempt` — see its own doc comment), a state with no
+* `file:`, or a state no guard applies to.
 */
 const enforceStepGuards = (input) => gen(function* () {
-	if (input.kind !== "commit") return;
+	if (input.kind !== "commit" || input.attempt) return;
 	const file = input.file;
 	if (file === void 0) return;
 	const applicable = stepGuards.filter((g) => g.appliesTo(input.rest));
@@ -206652,10 +207030,349 @@ const enforceStepGuards = (input) => gen(function* () {
 	};
 	for (const g of applicable) {
 		const refusal = yield* g.check(ctx);
-		if (refusal !== void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd step ${input.invoker}: ${refusal}`));
+		if (refusal !== void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd land: ${refusal}`));
 	}
 });
 //#endregion
+//#region src/Beat.ts
+/**
+* The beat kind for a rest, in precedence order:
+*
+* 1. `stalled` — `Edge.ts`'s `stalledAt` verdict, passed in as a plain
+*    boolean (this module never resolves it itself). `stalledAt` already
+*    requires a clean tree, so this can never collide with `capture` below.
+* 2. `capture` — a `message` rest with a DIRTY tree: the human already
+*    acted; a driver lands it immediately.
+* 3. Otherwise, the content kind verbatim (`script`/`prompt`, or `message`
+*    on a clean tree).
+*/
+const beatKindOf = (input) => {
+	if (input.stalled) return "stalled";
+	if (input.contentKind === "message" && input.dirty) return "capture";
+	return input.contentKind;
+};
+/**
+* The `stalled` beat's own content: a diagnosis naming the stuck state and
+* the three ways out. The first line is shaped so a stderr grep for
+* `stalled at "<state>"` stays a stable substring (see
+* `tests/integration/features/readme-driver.feature`).
+*/
+const stallDiagnosis = (state, actor) => `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty attempt, the tree is clean, and another dispatch would repeat it.\n\nThree ways out:\n  - sharpen the state's prompt so the turn has something concrete to author\n  - give the state a retry: cap, redirecting to an escalation state after\n    N fruitless attempts\n  - declare a "C" pattern on the state, if it can legitimately finish with\n    nothing to change\n`;
+/**
+* Assemble one beat document line — the newline-terminated JSON `gtd next
+* --json` prints. Key order is the emitted order: `kind`, `content`,
+* `session`, `model`, `validate`, `log`, `state`, `actor`, `label`,
+* `memory`, `file`, `mode`, `edges`.
+*
+* `session`/`validate` are the DISPATCH BLOCK: dropped unless `kind ===
+* "prompt"`, even if the caller passed one in — the gate lives here (not
+* only in the caller that computes them) so it can never drift. `content` is
+* the rendered rest's own content, except at `kind === "stalled"`, where
+* it's `stallDiagnosis`'s text instead. `model`/`memory`/`file`/`mode`/
+* `label`/`edges` are plain facts about the resting state and are emitted at
+* EVERY kind — the same discipline the old `nextJsonOutput` had: omitted
+* (never `null`) when their source is unset.
+*/
+const beatDocument = (input) => {
+	const { rendered, kind, log, session, validate } = input;
+	const dispatchable = kind === "prompt";
+	return JSON.stringify({
+		kind,
+		content: kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor) : rendered.content,
+		...dispatchable && session !== void 0 ? { session: {
+			id: session.id,
+			resume: session.resume
+		} } : {},
+		...rendered.model !== void 0 ? { model: rendered.model } : {},
+		...dispatchable && validate !== void 0 ? { validate } : {},
+		log,
+		state: rendered.state,
+		actor: rendered.actor,
+		...rendered.label !== void 0 ? { label: rendered.label } : {},
+		...rendered.memory !== void 0 ? { memory: rendered.memory } : {},
+		...rendered.file !== void 0 ? { file: rendered.file } : {},
+		...rendered.mode !== void 0 ? { mode: rendered.mode } : {},
+		...rendered.edges.length > 0 ? { edges: rendered.edges } : {}
+	}) + "\n";
+};
+//#endregion
+//#region src/WorktreeState.ts
+/**
+* The per-worktree, untracked state directory (the git dir) and the
+* driver-scoped paths gtd keeps in it — IO-shaped, so it sits at the edge
+* alongside `Edge.ts`/`RepoFiles.ts`; `PatternMachine.ts` stays pure and
+* never sees it.
+*
+* `worktreeGitDir` is resolved from the FILESYSTEM, never from a `git`
+* subprocess: `<root>/.git` is either a directory (a plain repo — the git dir
+* IS `.git`) or a `gitdir: <path>` pointer file (a linked worktree, or
+* `--separate-git-dir`). Reading it directly needs no `stat` (a failed read
+* because `.git` is a directory reads the same as a missing `.git` — both
+* fall back to `".git"`) and, unlike `git rev-parse --git-dir`, cannot be
+* diverted by a stray `GIT_DIR`/`GIT_WORK_TREE` in the ambient environment —
+* there is no subprocess for those to divert. `loopLogPath` is the ONE path
+* resolved here: gtd keeps no other per-worktree state (sessions are derived
+* from history, stall is history itself), and gtd never creates or truncates
+* even this file — the driver owns it; gtd only names it.
+*/
+const GITDIR_POINTER = /^gitdir:\s*(.+)$/m;
+/**
+* The worktree's own git dir — byte-identical to `git rev-parse --git-dir`
+* for a plain repo, a linked worktree, or `--separate-git-dir`. Never fails:
+* a read failure (no `.git`, or `.git` is a real directory) or a `.git` file
+* with no `gitdir:` line both fall back to the literal `".git"`, which is
+* also the right answer against the in-memory test tier (whose fake
+* filesystem has no `.git` entry at all).
+*/
+const worktreeGitDir = gen(function* () {
+	const { root } = yield* Cwd;
+	const content = yield* (yield* FileSystem).readFileString(join(root, ".git")).pipe(catchAll(() => succeed$3(void 0)));
+	const pointer = content === void 0 ? null : GITDIR_POINTER.exec(content);
+	if (pointer === null) return ".git";
+	const gitdir = pointer[1].trim();
+	return isAbsolute(gitdir) ? gitdir : join(root, gitdir);
+});
+/**
+* The per-worktree loop log path `gtd next --json` reports as `log`.
+* `$GTD_LOOP_LOG` (non-empty) wins verbatim — no join, no normalization — so
+* a `gtd` invoked from inside a check script inherits the enclosing run's
+* log path unchanged. Otherwise `<git-dir>/gtd-loop.log`, isolating two
+* worktrees looping concurrently from each other's log by construction (each
+* has its own git dir). Advisory metadata only — gtd neither creates nor
+* truncates the file.
+*/
+const loopLogPath = gen(function* () {
+	const { all } = yield* EnvVars;
+	const override = all.GTD_LOOP_LOG;
+	if (override !== void 0 && override !== "") return override;
+	return join(yield* worktreeGitDir, "gtd-loop.log");
+});
+//#endregion
+//#region src/Install.ts
+/**
+* The `gtd install` briefing DOCUMENT — string data plus `renderBriefing()`.
+* This module holds no protocol logic and nothing derives behaviour from it;
+* it exists purely so the binary can print, on demand, a complete and
+* self-contained explanation of how to build a gtd driver in any shell
+* or runtime — the self-serve version of README's "Writing your own driver"
+* chapter. `MINIMAL_DRIVER` is pinned equal to that chapter's own fenced
+* bash block by `Install.test.ts`, so the two can never drift.
+*/
+const GTD_VERSION$1 = createRequire(import.meta.url)("../package.json").version;
+const MINIMAL_DRIVER = `#!/usr/bin/env bash
+set -euo pipefail
+
+# The bundle plans; this executes. Emitted scripts print their own outcomes.
+# Exit 3 means SETTLED — nothing owed — so this exits the whole driver at 0.
+gtd_land() {
+  local json code=0
+  json="$(gtd land --json)" || code=$?
+  [ "$code" = 0 ] || [ "$code" = 3 ] || return "$code"
+  bash -c "$(jq -r '.required // empty' <<<"$json")" || return $?
+  bash -c "$(jq -r '.optional // empty' <<<"$json")" ||
+    echo "warn: presentation follow-up failed — continuing" >&2
+  [ "$code" = 3 ] && exit 0
+  return 0
+}
+
+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 ;;
+    capture) ;; # the human already acted — just land it
+    script) bash -c "$(jq -r .content <<<"$next")" >>"$log" 2>&1 || true ;;
+    prompt)
+      sid="$(jq -r '.session.id // empty' <<<"$next")"
+      c="$(jq -r .content <<<"$next")" model="$(jq -r '.model // empty' <<<"$next")"
+      agent_turn() { claude -p "$c" "$1" "$sid" \${model:+--model "$model"} \\
+        --dangerously-skip-permissions >>"$log" 2>&1; }
+      if [ "$(jq -r '.session.resume // false' <<<"$next")" = true ]
+      then agent_turn --resume || agent_turn --session-id
+      else agent_turn --session-id || agent_turn --resume
+      fi
+      v="$(jq -r '.validate // empty' <<<"$next")" n=0
+      while [ -n "$v" ] && ! out="$(bash -c "$v" 2>&1)"; do
+        n=$((n + 1)) && [ "$n" -gt 3 ] && { printf '%s\\n' "$out" >&2; exit 1; }
+        claude -p "$out" --resume "$sid" --dangerously-skip-permissions \\
+          >>"$log" 2>&1 # $out IS the fix prompt, verbatim
+      done ;;
+  esac
+  gtd_land || exit 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 = `
+## The beat protocol
+
+Two commands, one repeated beat: ask -> act -> land.
+
+  gtd next --json   what now - a pure read; poll it, peek it, no writes
+  gtd land --json   how to record what happened - run the script it emits
+
+Every beat that acts, lands. Every beat that rests, exits.
+
+\`gtd next --json\` is a read-only PEEK — every field (\`.session.id\`/
+\`.session.resume\` included) is DERIVED from history, never stored, so looking
+is free: nothing distinguishes a peek from a dispatch, and calling it twice in
+a row is always safe. There is no separate claiming form.
+
+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.
+- \`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
+  ignore its exit code — the outcome lives in the tree, not in the exit code.
+- \`prompt\` — send \`.content\` to your agent CLI, using the embedded
+  \`.session\`/\`.model\`/\`.validate\` fields (see below).
+`;
+const JSON_FIELD_REFERENCE = `
+## JSON field reference
+
+Every field below is always present unless marked "when set".
+
+### \`gtd next --json\` — the beat document
+
+- Always: \`kind\` (\`capture\`|\`message\`|\`script\`|\`prompt\`|\`stalled\`),
+  \`content\`, \`log\`, \`state\`, \`actor\`
+- When set: \`model\`, \`memory\`, \`label\`, \`file\`, \`mode\`, \`edges\` — plain
+  facts about the resting state, present at every kind
+- Only at \`kind: "prompt"\` (the DISPATCH BLOCK — absent at every other kind,
+  a \`stalled\` beat included, by construction): \`session\` (\`{id, resume}\`,
+  both DERIVED from history — a hash of the resting state's memory scope —
+  never stored, so a plain peek is exactly as safe to call as a dispatch would
+  be) and, when the state declares a validatable steering file, \`validate\`
+  (the same script \`gtd validate --json\`'s \`.script\` emits, embedded)
+
+### \`gtd land --json\` (also \`--entry\`)
+
+\`state\`, \`subject\` (\`null\` on a no-op), \`script\` (the combined form —
+\`required\` verbatim, \`optional\` wrapped non-fatally, so a
+\`jq -r .script | bash\` driver needs one \`bash\` call, not two), \`required\`,
+\`optional\`, \`settled\`; \`cost\`/\`model\` when recorded. \`--entry\` omits
+\`settled\` — read it as \`.settled // false\`.
+
+### \`gtd abandon\`/\`gtd restore --json\`
+
+\`required\`, \`optional\` (always \`""\`).
+
+### \`gtd validate --json\`
+
+\`state\`, \`script\` (\`""\` means nothing to validate); \`file\`/\`mode\` when the
+resolved rest declares them. On a non-zero run the script's own output IS the
+fix prompt, verbatim.
+
+### The error envelope
+
+\`{"state":"error","prompt":"<message>"}\` on stdout, plus a single \`gtd: \`
+line on stderr, exit 1 — this covers usage errors and defects too.
+
+### Exit codes (\`gtd land\` only — every other command is plain 0/1)
+
+| code | meaning                                                              |
+| ---- | --------------------------------------------------------------------- |
+| 0    | a script was emitted (capture, turn, attempt, squash), or a benign no-op at a clean \`message\` rest |
+| 3    | SETTLED — nothing owed: a no-op at a \`script\` rest, or the initial-state collapse. stdout still carries a script (a print-only note, or the collapse's real retain+rewind) — run it |
+| 1    | refusal or usage error — nothing was emitted                          |
+
+With \`set -o pipefail\`, \`gtd land | bash\` propagates gtd's own exit code
+through the pipe.
+`;
+const DRIVER_OBLIGATIONS = `
+## Driver obligations, in order
+
+1. Read exactly one \`gtd next --json\` beat document per iteration. There is
+   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.
+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.
+4. Map \`.session.id\`/\`.session.resume\` onto the agent CLI's own session
+   flags — try \`resume\`'s hinted flag first and fall back to the other on
+   failure (\`resume\` is a hint, not a contract: nothing is stored, so a
+   crashed prior turn or an expired agent session recovers by itself).
+5. After a \`prompt\` beat, run the document's own \`.validate\` script (when
+   present) and re-prompt its output verbatim on failure — the DRIVER owns
+   the retry cap, not gtd.
+6. Land only a beat you acted on (\`capture\`/\`script\`/\`prompt\`) — a stray
+   \`gtd land\` at a clean \`prompt\` rest authors an empty attempt on purpose
+   (that IS the stall bookkeeping), so don't land beats you didn't dispatch.
+7. Run \`gtd land --json\`, then execute its \`required\` (always) and
+   \`optional\` (presentation only — its failure is a warning, not a halt).
+8. Exit 3 (SETTLED) means there is nothing left to do — run the script first,
+   then stop; exit 0 continues the loop.
+`;
+const RECOVERY = `
+## Recovery
+
+gtd exiting 1 means nothing was attempted — a refusal or a usage error. Exit
+3 is NOT a failure: it means SETTLED (nothing owed), and stdout still carries
+a script to run. An emitted script exiting non-zero when YOU run it means
+something MAY have partially happened. All three recover the same way:
+re-invoke gtd. It re-reads the real repository state fresh every time, and
+every emitted script asserts its own HEAD precondition, so a script generated
+against a repository state that has since moved refuses loudly instead of
+corrupting anything. Scripts are re-runnable and assert their own HEAD
+precondition — a driver needs no retry logic beyond "ask gtd again".
+`;
+const referenceImplementation = () => `
+## Building the user's driver: interview first, then adapt
+
+The obligations above are the contract; the bash block below is one WORKED
+EXAMPLE of it. Do not copy it blindly, and do not guess the user's setup —
+INTERVIEW them, then build a driver shaped by their answers. Ask (offering
+the default when they have no preference):
+
+1. **Which agent should run the turns?** Whatever coding-agent CLI they
+   already use (default: \`claude\`). Map \`.session.id\`/\`.session.resume\`
+   onto THAT agent's continuation mechanism (obligation 4); an agent with no
+   session concept just ignores them — memory is an optimization, every
+   prompt is self-contained.
+2. **Under which permission model?** Fully autonomous turns (e.g.
+   \`--dangerously-skip-permissions\`), a sandbox, or the agent's default
+   prompting — their risk tolerance, their call. Also whether the workflow's
+   own \`.model\` hints should be honored (default: yes).
+3. **How do they want to invoke it?** A command on PATH (default:
+   \`~/.local/bin/gtd-loop\`), a project task-runner entry, a CI job step —
+   or no artifact at all: YOU drive the beats yourself, following the
+   obligations directly. Pick the runtime to match: bash, their language of
+   choice, anything that parses JSON and spawns subprocesses.
+4. **What should happen at the boundaries?** Where the log goes (obligation
+   3), and whether halting at a human gate should do anything richer than
+   print — desktop notification, terminal-multiplexer status, editor focus —
+   which belongs in their wrapper, never in gtd.
+
+Then build it, and verify safely before the first real drive:
+\`gtd next --json\` is a pure read — parse it, check your kind dispatch
+against the table above, call it as often as you like. Nothing happens until
+you run an emitted script.
+
+The reference rendering in bash (requires \`jq\`; the \`claude\` lines are
+what answers 1–2 replace):
+
+\`\`\`bash
+${MINIMAL_DRIVER}
+\`\`\`
+`;
+const PREREQUISITES = `
+## Prerequisites and portability
+
+- \`jq\` — to pull \`required\`/\`optional\`/the rest of the JSON fields above
+  back out of gtd's \`--json\` output.
+- \`gtd\` on \`PATH\` — a seeded mode \`validate:\` command is literally the
+  string \`gtd check <mode> '<file>'\`, resolved by NAME at script-run time.
+  Keep one \`gtd\` on \`PATH\`, consistently.
+
+Any runtime works: the contract is JSON in, subprocesses out.
+`;
+const renderBriefing = () => HEADER() + BEAT_PROTOCOL + JSON_FIELD_REFERENCE + DRIVER_OBLIGATIONS + RECOVERY + referenceImplementation() + PREREQUISITES;
+//#endregion
 //#region src/program.ts
 /**
 * `gtd lsp`: start the LSP server for `.gtd/` steering files over stdio. Its
@@ -206667,6 +207384,23 @@ const enforceStepGuards = (input) => gen(function* () {
 */
 const runLspCommand = () => startLspServer();
 /**
+* `gtd install`: print the driver-building briefing (`src/Install.ts`'s
+* `renderBriefing()`) — a complete, self-contained explanation of how to
+* build a gtd driver in any shell or runtime, emitted by the binary
+* itself so it is always exactly as current as the gtd that prints it.
+* Writes nothing: "install" means installing knowledge into the calling
+* agent's context. Its `needs: "none"` (see `Cli.ts`'s `needsOf`, same as
+* `gtd lsp`) means it skips the repo-root guard entirely — it resolves no
+* workflow state and reads no config, so it runs from any directory, in or
+* out of a repository. `--json` and extra arguments are already rejected by
+* `Cli.ts` before a `Command` value ever reaches here (`--json` itself is
+* accepted, wrapping the same text under a `briefing` key).
+*/
+const runInstallCommand = (json, write) => sync$1(() => {
+	const briefing = renderBriefing();
+	write(json ? JSON.stringify({ briefing }) + "\n" : briefing.endsWith("\n") ? briefing : briefing + "\n");
+});
+/**
 * `gtd init`: scaffold a MINIMAL `.gtdrc.json` seeding the default variables a
 * fresh project is most likely to change — the test command (`vars.testCommand`)
 * and a ready-to-edit Prettier formatting suggestion (`modes:`). It writes NO
@@ -206680,7 +207414,7 @@ const runLspCommand = () => startLspServer();
 * instead (`assertInitLocation`, which also allows a directory outside any
 * repository) since it writes `.gtdrc.json` at the root and refuses to
 * clobber an existing config. The file is left UNCOMMITTED, so the message
-* warns to commit it before the first `gtd step` (an uncommitted config
+* warns to commit it before the first `gtd land` (an uncommitted config
 * counts as a pending change the initial state's `* **` edge would otherwise
 * capture).
 */
@@ -206697,8 +207431,10 @@ const runInitCommand = (json, write) => gen(function* () {
 		written: ".gtdrc.json",
 		inRepo
 	}) + "\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"));
+	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 landing. Once\ncommitted, run `gtd land` 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 land` from such a repo to\nbegin.\n"));
 });
+/** `gtd land`'s exit code for the two SETTLED shapes (`LandResult.settled`) — nothing owed, but stdout still carries a script a piping driver must run. Every other successful landing exits 0. */
+const EXIT_SETTLED = 3;
 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 });
@@ -206742,6 +207478,8 @@ const openWindowScript = (rest, targetState) => {
 		})
 	}]).optional;
 };
+/** True for a `"commit"` decision that is an ATTEMPT (`PatternMachine.StepCommit.attempt`) — the one flag both `enforceStepGuards` and `buildRequiredScript` bypass their own steps for (see each call site). */
+const isAttemptDecision = (decision) => decision.kind === "commit" && decision.attempt === true;
 /**
 * The subject the required script WILL produce. A `"commit"` decision's is
 * fully deterministic already; a `"squash"` decision's is only known once its
@@ -206754,33 +207492,35 @@ const previewSubject = (decision, rest) => decision.kind === "commit" ? succeed$
 * 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* () {
+* themselves. The steering-mode step is SKIPPED for an attempt commit
+* (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.
+*/
+const buildRequiredScript = (rest, decision, 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 commitContext = decision.kind === "commit" ? rest.context : yield* contextAt(rest, decision.state, rest.actor, cost, model);
+	const isAttempt = isAttemptDecision(decision);
 	const steps = [
 		...closeDecision.shouldClose ? [{
 			kind: "gitWrite",
 			command: buildCloseWindowScript(closeDecision.refs)
 		}] : [],
-		...yield* steeringModeSteps(rest),
+		...isAttempt ? [] : 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 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
+* Decide the one resulting transition (commit or squash) for `gtd land` —
+* WITHOUT performing it. `currentRest` → `planStep` decides, authenticating
+* as `rest.actor` (the resolved rest's own declared actor — landing derives
+* who acts, it never takes an actor argument); the step-capture guards
+* (`src/StepGuards.ts`) then refuse before anything is emitted. The decision
+* is 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
@@ -206796,17 +207536,21 @@ const stepOptions = (cost, model) => ({
 * 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 planLanding = (opts = {}) => gen(function* () {
 	const rest = yield* currentRest;
-	const plan = yield* planStep(rest, invoker, stepOptions(cost, model));
+	const plan = yield* planStep(rest, opts);
 	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,
-		required: "",
-		optional: ""
+		required: emitScripts({}, [{
+			kind: "outcome",
+			command: noteOutcome(noopText(plan.state))
+		}]).required,
+		optional: "",
+		settled: plan.settled
 	};
 	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}"`));
@@ -206815,48 +207559,57 @@ const stepAsActor = (invoker, cost, model) => gen(function* () {
 		context: rest.context,
 		file: rest.hints.file,
 		changes: rest.changes,
-		invoker,
-		kind: decision.kind
+		kind: decision.kind,
+		attempt: isAttemptDecision(decision)
 	});
 	const targetState = decision.kind === "commit" ? decision.to : decision.state;
 	return {
 		state: rest.state,
 		subject: yield* previewSubject(decision, rest),
-		cost: cost ?? null,
-		model: model ?? null,
-		required: yield* buildRequiredScript(rest, decision, invoker, cost, model),
-		optional: openWindowScript(rest, targetState)
+		cost: opts.cost ?? null,
+		model: opts.model ?? null,
+		required: yield* buildRequiredScript(rest, decision, opts.cost, opts.model),
+		optional: openWindowScript(rest, targetState),
+		settled: yield* collapsesToInitialState(rest, decision)
 	};
 });
-/** 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) => {
+/** Renders `planLanding`'s result for `gtd land`. Plain text prints the combined script exactly as before (its own outcome rendering, including a genuine no-op's "nothing to do at …" note and the initial-state collapse's `COLLAPSED_TEXT` note, is already baked in — see `renderDecision`'s collapse branch); `--json` additionally carries `required`/`optional`/`script`/`settled`. */
+const reportLanding = (result, json, write) => {
+	const script = combinedScript(result.required, result.optional);
 	if (json) write(JSON.stringify({
 		state: result.state,
 		subject: result.subject,
 		...result.cost !== null ? { cost: result.cost } : {},
 		...result.model !== null ? { model: result.model } : {},
+		script,
 		required: result.required,
-		optional: result.optional
+		optional: result.optional,
+		settled: result.settled
 	}) + "\n");
-	else write(result.subject !== null ? `committed: ${result.subject}\n` : `nothing to do at "${result.state}"\n`);
-};
-/**
-* `gtd step <actor> [--cost=<n>] [--model=<name>]`: authenticate as `<actor>`
-* and perform the one resulting transition, recording `--cost`/`--model` as a
-* `Gtd-Cost:` trailer. `--entry <state>` no longer nests inside this handler —
-* `Cli.ts`'s `--entry` selector resolves that combination to its own
-* `"entry"` command kind (see `runEntryCommand`) before `runCommand` ever
-* dispatches here, so a `step` `Command` is always the ordinary pattern-
-* matched step.
-*/
-const runStepCommand = (actor, cost, model, json, write) => gen(function* () {
-	const result = yield* stepAsActor(actor, cost, model);
-	reportStepResult(result, json, write);
+	else write(script);
+};
+/**
+* `gtd land [--cost=<n>] [--model=<name>]`: land whatever the tree now shows
+* at the currently resolved rest — authenticated as the rest's own actor,
+* never a caller-supplied one — recording `--cost`/`--model` as a `Gtd-Cost:`
+* trailer. `--entry <state>` no longer nests inside this handler — `Cli.ts`'s
+* `--entry` selector resolves that combination to its own `"entry"` command
+* kind (see `runEntryCommand`) before `runCommand` ever dispatches here, so a
+* `land` `Command` is always the ordinary pattern-matched landing.
+*
+* Returns the exit code `runCommand`/`Cli.ts`'s `runCli` should use: `0` for
+* an ordinary landing, `EXIT_SETTLED` (3) when `result.settled` — nothing
+* owed, but stdout still carries a script a piping driver must run (see
+* `EXIT_SETTLED`'s own doc comment).
+*/
+const runLandCommand = (opts, json, write) => gen(function* () {
+	const result = yield* planLanding(opts);
+	reportLanding(result, json, write);
+	return result.settled ? EXIT_SETTLED : 0;
 });
 /**
-* `gtd step <actor> --entry <state> [--var <name>=<value> ...]` (or its
-* subcommand-less short form `gtd --entry <state> ...`, `actor` defaulting to
-* `human` there — see `Cli.ts`'s `--entry` selector): start a brand NEW process at `<state>`
+* `gtd --entry <state> [--var <name>=<value> ...]` (`actor` always `"human"`
+* — see `Cli.ts`'s `--entry` selector): start a brand NEW process at `<state>`
 * — any declared, non-commit state (see `PatternMachine.enterableStates`) —
 * replacing the two former named commands `gtd review <commitish>`/`gtd fix`
 * with one generic mechanism. Writes an ordinary turn commit
@@ -206867,7 +207620,7 @@ const runStepCommand = (actor, cost, model, json, write) => gen(function* () {
 * the merged `it.vars`, resolved to a commit, and checked sane). Unlike the
 * old commands (which required a clean tree and used `commitAsIs`), this
 * commits via `commitAllWithPrefix` — capturing whatever the working tree
-* carries at the moment of entry, exactly like an ordinary `gtd step`
+* carries at the moment of entry, exactly like an ordinary `gtd land`
 * capture, rather than demanding a clean tree first.
 *
 * Any failure below is a plain refusal: nothing is written. Checked in order:
@@ -206900,7 +207653,7 @@ const runEntryCommand = (actor, entryState, varOverrides, json, write, commandLa
 		required: plan.scripts.required,
 		optional: plan.scripts.optional
 	}) + "\n");
-	else write(`committed: ${plan.subject}\n`);
+	else write(combinedScript(plan.scripts.required, plan.scripts.optional));
 });
 /**
 * `gtd abandon`: end the process currently underway WITHOUT completing it,
@@ -206947,18 +207700,23 @@ const runAbandonCommand = (json, write) => gen(function* () {
 	const initial = initialStateOf(def);
 	const run = yield* currentRun;
 	if (run.trace.length === 0) {
+		const required = emitScripts({}, [{
+			kind: "outcome",
+			command: abandonNoopOutcome(initial)
+		}]).required;
 		if (json) write(JSON.stringify({
 			state: initial,
-			abandoned: false
+			abandoned: false,
+			required,
+			optional: ""
 		}) + "\n");
-		else write(`no gtd process is underway (resting at "${initial}") — nothing to abandon\n`);
+		else write(combinedScript(required, ""));
 		return;
 	}
 	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`));
 	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",
@@ -206971,6 +207729,10 @@ const runAbandonCommand = (json, write) => gen(function* () {
 		{
 			kind: "gitWrite",
 			command: mixedResetTo(run.startParentHash)
+		},
+		{
+			kind: "outcome",
+			command: abandonedOutcome(restState, run.startParentHash, initial)
 		}
 	];
 	const required = emitScripts(headPreconditions(yield* git.resolveRef("HEAD")), steps).required;
@@ -206982,7 +207744,7 @@ const runAbandonCommand = (json, write) => gen(function* () {
 		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`);
+	else write(combinedScript(required, ""));
 });
 /**
 * `gtd restore`: hard-reset HEAD back to the pre-squash tip a squash or
@@ -207010,14 +207772,20 @@ const runRestoreCommand = (json, write) => gen(function* () {
 	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)}.`));
 	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 steps = [
+		{
+			kind: "gitWrite",
+			command: hardResetTo(tip)
+		},
+		{
+			kind: "gitWrite",
+			command: deleteRef(HISTORY_REF)
+		},
+		{
+			kind: "outcome",
+			command: restoredOutcome(tip, after.state)
+		}
+	];
 	const required = emitScripts(headPreconditions(headHash), steps).required;
 	if (json) write(JSON.stringify({
 		state: after.state,
@@ -207027,7 +207795,7 @@ const runRestoreCommand = (json, write) => gen(function* () {
 		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`);
+	else write(combinedScript(required, ""));
 });
 /**
 * The mode's own resolved VALIDATE command, rendered against `file` — the
@@ -207066,50 +207834,135 @@ const resolveSelfValidateCommand = (def, mode, file, context) => gen(function* (
 * 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.
+* findings (see the README's minimal driver, and `fixPromptInstruction` below
+* — its driver-side counterpart). This is advisory: `gtd land` embeds that same
+* command ahead of its own commit and REFUSES a turn whose steering file is
+* invalid (see `planLanding`), 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`;
+/**
+* The driver-side counterpart of `selfValidateInstruction` above — the same
+* gate, expressed for a loop that RUNS the validate script itself and
+* re-prompts the same agent session on a non-zero exit, rather than for an
+* agent that self-validates before finishing. Wrapped onto the emitted
+* validate script's last command via `Emit.ts`'s `onFailure` (see
+* `runValidateCommand`), so a driver's fix re-prompt is exactly this text
+* plus the script's own captured findings — never hand-composed in bash.
+*/
+const fixPromptInstruction = (file) => `Your last turn does not pass its own validation script. Fix these format violations in ${file}, then finish:`;
 /** 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). */
-/** `gtd next --json`'s single-line object — omitting each optional key (never `null`-valued) when its source is unset, exactly like `gtd status --json`. */
-const nextJsonOutput = (rendered) => JSON.stringify({
-	state: rendered.state,
-	actor: rendered.actor,
-	kind: rendered.kind,
-	content: rendered.content,
-	...rendered.model !== void 0 ? { model: rendered.model } : {},
-	...rendered.memory !== void 0 ? { memory: rendered.memory } : {},
-	...rendered.label !== void 0 ? { label: rendered.label } : {},
-	...rendered.file !== void 0 ? { file: rendered.file } : {},
-	...rendered.mode !== void 0 ? { mode: rendered.mode } : {},
-	...rendered.edges.length > 0 ? { edges: rendered.edges } : {}
-}) + "\n";
+/**
+* Resolve the resting state's own steering-file validate script — the SAME
+* script both `gtd validate --json` (`runValidateCommand`, its thin caller
+* now) and `gtd next --json`'s embedded `validate` field emit, from one
+* shared resolver so the two surfaces can't drift. `undefined` = nothing to
+* validate: no `file:`+`mode:` declared, or the declared file is absent from
+* the working tree. An unknown `mode:` FAILS this Effect (exactly as
+* `runValidateCommand` always has) — `runNextCommand` is the one caller that
+* degrades that failure to omitting `validate`, mirroring how the plain-text
+* self-validation instruction already degrades on the same failure.
+*/
+const resolveValidateScript = (rest) => gen(function* () {
+	const file = rest.hints.file;
+	const mode = rest.stateDef.mode;
+	if (file === void 0 || mode === void 0) return void 0;
+	const fs = yield* FileSystem;
+	const toError = (e) => e instanceof Error ? e : new Error(String(e));
+	if (!(yield* fs.exists(file).pipe(mapError$1(toError)))) return void 0;
+	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 lastIndex = commands.length - 1;
+	const steps = commands.map((command, index) => ({
+		kind: "command",
+		command,
+		...index === lastIndex && resolved.validate?.kind === "command" ? { onFailure: fixPromptInstruction(file) } : {}
+	}));
+	return {
+		file,
+		mode,
+		script: emitScripts(headPreconditions(rest.context.currentCommit), steps).required
+	};
+});
 /** `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) && selfValidateCommand !== void 0 ? base + selfValidateInstruction(selfValidateCommand, rendered.file) : base;
 };
+/**
+* `gtd next --json`'s output: the whole BEAT DOCUMENT (`src/Beat.ts`'s
+* `beatDocument`) for the resolved rest — one self-describing, POLLABLE line.
+* `stalledAt` (a pure read off history) and the dirty-tree test both feed
+* `beatKindOf`, which picks the driver-facing `kind`; the dispatch block
+* (`session`/`validate`) is resolved only when `kind === "prompt"`, since
+* `beatDocument` drops it at every other kind regardless. Nothing is written
+* by any of this — `resolveSession` derives the same id for a peek as it
+* would for a dispatch, and `resolveValidateScript` only READS the file/mode
+* it inspects — so there is nothing left for a separate claiming form to
+* protect (see `runNextCommand` below).
+*/
+const nextBeatOutput = (rest, rendered) => gen(function* () {
+	const kind = beatKindOf({
+		contentKind: rendered.kind,
+		dirty: rest.changes.length > 0,
+		stalled: stalledAt(rest)
+	});
+	const session = kind === "prompt" ? resolveSession(rendered.memory, rendered.memoryResumed) : void 0;
+	const resolvedValidate = kind === "prompt" ? yield* resolveValidateScript(rest).pipe(catchAll(() => succeed$3(void 0))) : void 0;
+	const validate = resolvedValidate !== void 0 && resolvedValidate.script.length > 0 ? resolvedValidate.script : void 0;
+	return beatDocument({
+		rendered,
+		kind,
+		log: yield* loopLogPath,
+		...session !== void 0 ? { session: {
+			id: session.sessionId,
+			resume: session.resume
+		} } : {},
+		...validate !== void 0 ? { validate } : {}
+	});
+});
+/**
+* `gtd next`: pure emitter of the resolved rest's rendered content — no
+* mutation at all. Plain-text output is the human rendering, unchanged: the
+* rendered content plus (when resolvable) the self-validation instruction;
+* `--json` hands off to `nextBeatOutput` above. Nothing is written either
+* way, so a peek and a would-be dispatch are the same call — there is no
+* separate claiming form any more.
+*/
 const runNextCommand = (json, write) => gen(function* () {
 	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));
+	if (json) {
+		write(yield* nextBeatOutput(rest, rendered));
+		return;
+	}
+	if (rendered.kind === "prompt" && rest.changes.length === 0 && stalledAt(rest)) {
+		write(stallDiagnosis(rendered.state, rendered.actor));
+		return;
+	}
+	const selfValidateCommand = emitsValidatablePrompt(rendered) ? yield* resolveSelfValidateCommand(rest.def, rendered.mode, rendered.file, rest.context).pipe(catchAll(() => succeed$3(void 0))) : void 0;
+	write(nextPlainOutput(rendered, selfValidateCommand));
 });
 /**
 * `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
+* `mode:` selecting how) — the SAME commands `gtd land`'s capture guard now
+* embeds ahead of its own commit (see `planLanding`), 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.
+* When the resolved mode's validate half is a `command` (never a `"builtin"`
+* validator, which renders no shell command at all), the LAST rendered
+* command carries `onFailure: fixPromptInstruction(file)` (`Emit.ts`'s
+* `failurePromptWrapper`) — so a non-zero exit from the script prints the
+* COMPLETE ready-to-send fix prompt (instruction + findings) rather than bare
+* findings, letting a driver treat the script's captured output as opaque
+* prompt text (see the README's minimal driver).
 */
 const runValidateCommand = (json, write) => gen(function* () {
 	const rest = yield* currentRest;
@@ -207124,30 +207977,16 @@ const runValidateCommand = (json, write) => gen(function* () {
 		}) + "\n");
 		else write(`nothing to validate at "${rest.state}"\n`);
 	};
-	if (file === void 0 || mode === void 0) {
+	const resolved = yield* resolveValidateScript(rest);
+	if (resolved === 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
+		...resolved
 	}) + "\n");
-	else write(script.length > 0 ? `${script}\n` : `nothing to validate at "${rest.state}"\n`);
+	else write(resolved.script.length > 0 ? `${resolved.script}\n` : `nothing to validate at "${rest.state}"\n`);
 });
 /**
 * `gtd check <mode> <file>`: read `<file>` and run the BUILT-IN steering
@@ -207199,7 +208038,7 @@ const runCheckCommand = (mode, file, json, write) => gen(function* () {
 	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. */
+/** 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 land` would match against. */
 const computeStatusChanges = (onEdges, changes) => changes.map((change) => {
 	const matchedRow = onEdges.find(([patternStr]) => {
 		const parsed = parsePattern(patternStr);
@@ -207403,20 +208242,20 @@ const assertInitLocation = (git, fs) => gen(function* () {
 */
 const needsOf = (kind) => {
 	switch (kind) {
-		case "lsp": return "none";
+		case "lsp":
+		case "install": return "none";
 		case "init":
 		case "check": return "fs";
 		case "visualize": return "config";
 		default: return "state";
 	}
 };
-/** Dispatches to the named `run*Command` handler for every `Command.kind` — the counterpart of `Cli.ts`'s `parseArgv`, which has already validated every field a handler receives. */
-const dispatchCommand = (command, json, write) => {
+/** Dispatches to the named `run*Command` handler for every `Command.kind` EXCEPT `"land"` (which alone returns a non-zero exit code — see `dispatchCommand`) — the counterpart of `Cli.ts`'s `parseArgv`, which has already validated every field a handler receives. */
+const dispatchVoidCommand = (command, json, write) => {
 	switch (command.kind) {
 		case "lsp": return runLspCommand();
 		case "init": return runInitCommand(json, write);
 		case "visualize": return runVisualizeCommand(command.port, command.open, json, write);
-		case "step": return runStepCommand(command.actor, command.cost, command.model, json, write);
 		case "entry": return runEntryCommand(command.actor, command.state, command.vars, json, write, command.label);
 		case "abandon": return runAbandonCommand(json, write);
 		case "restore": return runRestoreCommand(json, write);
@@ -207424,18 +208263,35 @@ const dispatchCommand = (command, json, write) => {
 		case "status": return runStatusCommand(json, write);
 		case "validate": return runValidateCommand(json, write);
 		case "check": return runCheckCommand(command.mode, command.file, json, write);
+		case "install": return runInstallCommand(json, write);
 	}
 };
 /**
+* Dispatches every `Command` to its exit code — `"land"` alone can return
+* non-zero (`EXIT_SETTLED`, via `runLandCommand`); every other kind always
+* succeeds at `0` (`dispatchVoidCommand`, piped through `Effect.as(0)`).
+* Splitting the exhaustive switch out to `dispatchVoidCommand` keeps this
+* function's own branching to the one kind that actually varies.
+*/
+const dispatchCommand = (command, json, write) => {
+	if (command.kind === "land") return runLandCommand({
+		...command.cost !== void 0 ? { cost: command.cost } : {},
+		...command.model !== void 0 ? { model: command.model } : {}
+	}, json, write);
+	return dispatchVoidCommand(command, json, write).pipe(as(0));
+};
+/**
 * 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 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.
+* scope, decoding), so nothing here re-parses argv. Returns the exit code
+* `Cli.ts`'s `runCli` should use — `0` for every command except a `land` that
+* settles (`EXIT_SETTLED`).
 *
 * No review-window close/open bracket runs here any more: every state-command
-* handler (see `stepAsActor`) now decides for itself, off `ReviewWindow.ts`'s
+* handler (see `planLanding`) 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).
@@ -207447,7 +208303,7 @@ const runCommand = (command, json, write) => {
 		const git = yield* GitService;
 		const fs = yield* FileSystem;
 		yield* assertRunningFromRepoRoot(git, fs);
-		yield* dispatch;
+		return yield* dispatch;
 	});
 };
 //#endregion
@@ -207506,21 +208362,21 @@ const FLAGS = [
 		name: "--cost",
 		arity: 1,
 		repeatable: false,
-		scope: (kind) => kind === "step",
+		scope: (kind) => kind === "land",
 		decode: ([raw]) => nonNegativeNumber(raw ?? "", "--cost"),
-		scopeError: "gtd: --cost is only valid for `gtd step` without --entry — an entry is not a metered agent turn",
+		scopeError: "gtd: --cost is only valid for `gtd land` — an entry is not a metered agent turn",
 		valueHint: "<n>",
-		help: ["(gtd step only) record the invocation's token cost"]
+		help: ["(gtd land only) record the invocation's token cost"]
 	},
 	{
 		name: "--model",
 		arity: 1,
 		repeatable: false,
-		scope: (kind) => kind === "step",
+		scope: (kind) => kind === "land",
 		decode: ([raw]) => raw === void 0 || raw.trim() === "" || /[\r\n]/.test(raw) ? left("gtd: --model must be a non-empty, single-line value") : right(raw),
-		scopeError: "gtd: --model is only valid for `gtd step` without --entry — an entry is not a metered agent turn",
+		scopeError: "gtd: --model is only valid for `gtd land` — an entry is not a metered agent turn",
 		valueHint: "<name>",
-		help: ["(gtd step only, with --cost) tag that cost's model"]
+		help: ["(gtd land only, with --cost) tag that cost's model"]
 	},
 	{
 		name: "--entry",
@@ -207528,14 +208384,12 @@ const FLAGS = [
 		repeatable: false,
 		scope: (kind) => kind === "entry",
 		decode: ([raw]) => right(raw ?? ""),
-		scopeError: "gtd: --entry is only valid for `gtd step` or the bare `gtd --entry <state>` form",
+		scopeError: "gtd: --entry is only valid with no other command — use the bare `gtd --entry <state>` form; landing and entering are different verbs",
 		valueHint: "<state>",
 		help: [
-			"(gtd step, or with no command at all) start a brand new",
-			"process at <state> — any declared, non-commit state —",
-			"instead of stepping the one currently resting. Not",
-			"combinable with --cost/--model (an entry is not a metered",
-			"agent turn)"
+			"(with no command at all) start a brand new process at",
+			"<state> — any declared, non-commit state — authenticated",
+			"as human"
 		]
 	},
 	{
@@ -207589,20 +208443,22 @@ const COMMAND_ROWS = [
 		]
 	},
 	{
-		token: "step",
-		kind: "step",
-		arity: { name: "actor" },
+		token: "land",
+		kind: "land",
+		arity: "none",
 		details: [
-			"Authenticate as <actor>, match the resolved rest's",
-			"declared patterns against the pending changes, and commit",
-			"(or squash) the one resulting transition. Pass",
-			"--cost=<n> (optionally --model=<name>) to record the",
-			"just-finished invocation's token cost and model on the",
-			"turn commit (summed into it.processCost/processCostByModel).",
-			"Pass --entry <state> to start a brand NEW process at",
-			"<state> instead — any declared, non-commit state — with",
-			"repeatable --var <name>=<value> supplying that new",
-			"process's fixed it.vars overrides"
+			"Land whatever the tree now shows at the currently",
+			"resolved rest — a human capture, an agent/check turn, an",
+			"empty attempt (a fruitless prompt turn), or a squash — and",
+			"print the script that records it; a driver runs the",
+			"script, e.g. `gtd land | bash`. Pass --cost=<n>",
+			"(optionally --model=<name>) to record the just-finished",
+			"invocation's token cost and model on the turn commit",
+			"(summed into it.processCost/processCostByModel). Exits 0",
+			"when a script is emitted (or a benign no-op at a clean",
+			"message rest), 3 when SETTLED — nothing owed: a no-op at a",
+			"script rest, or the initial-state collapse (stdout still",
+			"carries the script) — 1 on any refusal"
 		]
 	},
 	{
@@ -207634,7 +208490,14 @@ const COMMAND_ROWS = [
 		token: "next",
 		kind: "next",
 		arity: "none",
-		details: ["Print the resolved rest's rendered script/prompt/message (no mutation)"]
+		details: [
+			"Print the resolved rest's rendered script/prompt/message",
+			"(no mutation, safe to poll). --json emits the whole beat",
+			"document instead: kind (capture|message|script|prompt|",
+			"stalled) selects what a driver does, content is what it",
+			"runs or shows, plus the prompt session, model, validate",
+			"script, log path and the resting state's own fields"
+		]
 	},
 	{
 		token: "status",
@@ -207654,7 +208517,10 @@ const COMMAND_ROWS = [
 			"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)"
+			"validate\" in that case). On a non-zero validate exit",
+			"the emitted script prints a ready-to-send fix prompt",
+			"(instruction + findings) and exits with the",
+			"validator's own code"
 		]
 	},
 	{
@@ -207686,6 +208552,19 @@ const COMMAND_ROWS = [
 			"with <mode>/<file> given explicitly. This is what a",
 			"workflow's emitted validation script invokes as a leaf step"
 		]
+	},
+	{
+		token: "install",
+		kind: "install",
+		arity: "none",
+		details: [
+			"Print a complete, self-contained briefing that teaches an",
+			"agent (or a human) to build a gtd driver in any shell or",
+			"runtime — the self-serve version of README's 'Writing",
+			"your own driver'. Writes nothing: this installs knowledge",
+			"into the calling agent's context, not files on disk. Runs",
+			"from any directory, in or out of a repository"
+		]
 	}
 ];
 const commandByToken = (token) => COMMAND_ROWS.find((r) => r.token === token);
@@ -207698,8 +208577,10 @@ const commandByToken = (token) => COMMAND_ROWS.find((r) => r.token === token);
 * enterable states.
 */
 const REMOVED = {
-	review: "gtd: `gtd review <commitish>` is gone — this workflow's own state names aren't known to gtd; run `gtd step <actor> --entry <review-state> --var <name>=<value> ...` instead — run it with an unknown <review-state> to see this workflow's own enterable states",
-	fix: "gtd: `gtd fix` is gone — this workflow's own state names aren't known to gtd; run `gtd step <actor> --entry <fix-state>` instead — run it with an unknown <fix-state> to see this workflow's own enterable states"
+	step: "gtd: `gtd step <actor>` is gone — landing is actorless; run `gtd land` instead (`gtd --entry <state>` for entries)",
+	review: "gtd: `gtd review <commitish>` is gone — this workflow's own state names aren't known to gtd; run `gtd --entry <review-state> --var <name>=<value> ...` instead — run it with an unknown <review-state> to see this workflow's own enterable states",
+	fix: "gtd: `gtd fix` is gone — this workflow's own state names aren't known to gtd; run `gtd --entry <fix-state>` instead — run it with an unknown <fix-state> to see this workflow's own enterable states",
+	loop: "gtd: `gtd loop` is gone — gtd decides and prints, a driver executes. Copy the driver from the README's \"A complete minimal driver\" section and run that instead"
 };
 const COLUMN = 19;
 const renderBlock = (header, lines) => {
@@ -207707,14 +208588,7 @@ const renderBlock = (header, lines) => {
 	const headerCell = `  ${header}`;
 	return (headerCell.length < COLUMN ? `${headerCell.padEnd(COLUMN)}${first ?? ""}\n` : `${headerCell}\n${" ".repeat(COLUMN)}${first ?? ""}\n`) + rest.map((l) => `${" ".repeat(COLUMN)}${l}\n`).join("");
 };
-const PRELUDE_LOOP = renderBlock("(no command), loop", [
-	"Launch the loop driver (bin/gtd), which repeatedly drives",
-	"an agent through gtd next/gtd step calls until the",
-	"workflow rests at a human gate (a non-autonomous state)",
-	"or settles. A bare gtd invocation and gtd loop both",
-	"launch it identically"
-]);
-const ENTRY_SHORT_FORM = renderBlock("(no command) --entry <state>", ["Short form of 'step human --entry <state>' — starts a new", "process authenticated as human, e.g. 'gtd --entry <state>'"]);
+const ENTRY_SHORT_FORM = renderBlock("(no command) --entry <state>", ["Starts a new process authenticated as human, e.g.", "'gtd --entry <state>'"]);
 const VERSION_BLOCK = renderBlock("version", ["Print version and exit"]);
 const HELP_BLOCK = renderBlock("help", ["Print this help and exit"]);
 const SPACE_FORM_FLAGS = /* @__PURE__ */ new Set(["--entry", "--var"]);
@@ -207727,7 +208601,14 @@ const renderHelp = () => {
 		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"])}`;
+	return `Usage: gtd [command] [options]\n\nCommands:\n${[
+		commandBlocks[0],
+		commandBlocks[1],
+		ENTRY_SHORT_FORM,
+		...commandBlocks.slice(2),
+		VERSION_BLOCK,
+		HELP_BLOCK
+	].join("")}\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"])}`;
 };
 /**
 * The stderr line for a CLI error: a `gtd: ` prefix UNLESS the message
@@ -207834,6 +208715,12 @@ const decodeFlags = (byFlag) => {
 	}
 	return right(bag);
 };
+/** Assembles a `land` `Command` from its already-scope-checked flag bag — split out of `parseArgv` so its two independent, omit-when-absent optional fields don't inflate that function's own branching. */
+const buildLandCommand = (bag) => ({
+	kind: "land",
+	...bag["--cost"] !== void 0 ? { cost: bag["--cost"] } : {},
+	...bag["--model"] !== void 0 ? { model: bag["--model"] } : {}
+});
 const parseArgv = (argv) => {
 	if (argv.includes("--help") || argv.includes("-h")) return {
 		kind: "output",
@@ -207859,12 +208746,12 @@ const parseArgv = (argv) => {
 	};
 	const row = first === void 0 ? void 0 : commandByToken(first);
 	const removedMessage = first === void 0 ? void 0 : REMOVED[first];
-	const selectsEntry = entryPresent && (first === void 0 || row?.kind === "step");
+	const selectsEntry = entryPresent && first === void 0;
 	const kind = selectsEntry ? "entry" : row?.kind;
 	if (row === void 0 && removedMessage === void 0 && !selectsEntry) {
 		const violation = scopeViolation(void 0, present);
 		if (violation !== void 0) return usagePlan(violation, jsonSeen);
-		if (first === void 0) return usagePlan("gtd: missing command — see usage above (`gtd --help`)", jsonSeen, renderHelp());
+		if (first === void 0) return usagePlan("gtd: missing command — gtd decides and prints, a driver executes; copy one from the README's \"A complete minimal driver\" section and run that, or see usage above (`gtd --help`)", jsonSeen, renderHelp());
 		return usagePlan(`unknown command '${first}'`, jsonSeen);
 	}
 	if (removedMessage !== void 0 && !selectsEntry) {
@@ -207875,8 +208762,7 @@ const parseArgv = (argv) => {
 	if (kind === "entry" && first === void 0) {
 		if (restPositionals.length > 0) return usagePlan(`gtd: too many arguments — expected none, got: ${restPositionals.join(", ")}`, jsonSeen);
 	} else {
-		const arityRow = kind === "entry" ? commandByToken("step") : row;
-		const arityMsg = arityError(first, restPositionals, arityRow.arity);
+		const arityMsg = arityError(first, restPositionals, row.arity);
 		if (arityMsg !== void 0) return usagePlan(arityMsg, jsonSeen);
 	}
 	const violation = scopeViolation(kind, present);
@@ -207885,27 +208771,21 @@ const parseArgv = (argv) => {
 	if (isLeft(decoded)) return usagePlan(decoded.left, jsonSeen);
 	const bag = decoded.right;
 	const json = present.has("--json");
-	if (kind === "step") {
+	if (kind === "land") {
 		if (bag["--model"] !== void 0 && bag["--cost"] === void 0) return usagePlan("gtd: --model requires --cost — it tags the recorded cost with the model that ran", json);
 		return {
 			kind: "command",
-			command: {
-				kind: "step",
-				actor: restPositionals[0],
-				...bag["--cost"] !== void 0 ? { cost: bag["--cost"] } : {},
-				...bag["--model"] !== void 0 ? { model: bag["--model"] } : {}
-			},
+			command: buildLandCommand(bag),
 			json
 		};
 	}
 	if (kind === "entry") {
-		const actor = first === void 0 ? "human" : restPositionals[0];
-		const label = first === void 0 ? `gtd --entry ${entryRaw}` : `gtd step ${actor} --entry ${entryRaw}`;
+		const label = `gtd --entry ${entryRaw}`;
 		return {
 			kind: "command",
 			command: {
 				kind: "entry",
-				actor,
+				actor: "human",
 				state: entryRaw,
 				vars: bag["--var"] ?? {},
 				label
@@ -207979,7 +208859,9 @@ const runCli = (argv, io) => {
 		io.stderr(`${cliErrorLine(plan.message)}\n`);
 		io.exit(1);
 	});
-	return runCommand(plan.command, plan.json, io.stdout).pipe(provide$2(io.layers()), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json)(cause)));
+	return runCommand(plan.command, plan.json, io.stdout).pipe(map$4((code) => {
+		if (code !== 0) io.exit(code);
+	}), provide$2(io.layers()), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json)(cause)));
 };
 //#endregion
 //#region src/main.ts