@pmelab/gtd 9.13.0 → 9.14.0

package/dist/gtd.bundle.mjs

@@ -30940,19 +30940,26 @@ const make$1 = (layer, memoMap) => {
 const make = make$1;
 //#endregion
 //#region src/Commentary.ts
-/** One line of stderr commentary — gated entirely by how the layer was built, never by the call site. */
+/**
+* One line of stderr commentary — `narrate` is gated entirely by how the
+* layer was built, never by the call site; `warn` is its ungated
+* counterpart, always written regardless of verbosity.
+*/
 var Narrator = class Narrator extends Tag("Narrator")() {
 	/**
 	* `write` is the raw stderr sink (`CliIo.stderr` in production, so the
 	* in-memory `CliIo` used by `@inmem` e2e scenarios captures narration into
 	* the exact same buffer it already captures errors into). `verbose` gates
-	* every line at construction time — the resulting service is a no-op
-	* writer when `false`, never a per-call check a narrating call site has to
-	* remember to make.
+	* every `narrate` line at construction time — the resulting service is a
+	* no-op writer when `false`, never a per-call check a narrating call site
+	* has to remember to make. `warn` bypasses that gate unconditionally.
 	*/
-	static layer = (write, verbose) => succeed$2(Narrator, { narrate: (line) => sync$1(() => {
-		if (verbose) write(`${line}\n`);
-	}) });
+	static layer = (write, verbose) => succeed$2(Narrator, {
+		narrate: (line) => sync$1(() => {
+			if (verbose) write(`${line}\n`);
+		}),
+		warn: (line) => sync$1(() => write(`${line}\n`))
+	});
 };
 /**
 * An error carrying REMEDIATION alongside its message — the offending config
@@ -189713,7 +189720,7 @@ const STATE_FIELDS = {
 		fileRef: true,
 		rest: "rendered",
 		viz: "field",
-		doc: "The agent harness system prompt stamped onto every one of this machine's own `prompt` states — emitted verbatim in `gtd next --json`/`--sh` for the driver to pass to its agent CLI, never interpreted by gtd. Machine-level only: a machine's `prompt` states share one resumed session, and a system prompt must be identical across every call of it. A `./` or `../` value is inlined from the declaring config file's directory. A machine declaring this with no `prompt` state is a config error."
+		doc: "The agent harness system prompt stamped onto every one of this machine's own `prompt` states — emitted verbatim in `gtd next --json` for the driver to pass to its agent CLI, never interpreted by gtd. Machine-level only: a machine's `prompt` states share one resumed session, and a system prompt must be identical across every call of it. A `./` or `../` value is inlined from the declaring config file's directory. A machine declaring this with no `prompt` state is a config error."
 	},
 	/** The raw-state-name fallback lives in the consumer (driver/viewer), not here — gtd simply omits the field when unset. */
 	label: {
@@ -190254,25 +190261,64 @@ const validateState = (def, name, names) => {
 	];
 };
 /**
+* A `script`/`message` state with no `C` row commits nothing on a clean tree
+* (the documented no-op default) — that's often deliberate, but silent for a
+* state whose author never considered the clean case. Warn, don't error.
+* Three exemptions, all load-bearing:
+*
+* - The workflow's initial state — a `C` row there would author a commit on
+*   every bare driver invocation.
+* - A `prompt` state — its clean step is an ATTEMPT by design, not a no-op.
+* - A `human`-actor state — `docs/driver.md`'s driver protocol lands a human
+*   gate's OPENING beat unconditionally on every restart while a process
+*   rests there ("Some gates could accept by INACTION..."), specifically
+*   because today that's a harmless no-op when the state has no `C` row. A
+*   `C` row on a human gate would turn every such restart into a real commit
+*   before the human has acted at all — the exact hazard the initial-state
+*   exemption above already exists to avoid, generalized to any human gate a
+*   process can rest at more than once.
+*
+* No exemption for a bare `"* **"` catch-all row or a declared `file:` — a
+* `diff` pattern (including `"* **"`) never matches a clean tree
+* (`matchesPattern`), so neither says anything about the clean case; a state
+* with either and no `C` row still no-ops on a clean tree exactly like one
+* with neither.
+*/
+const validateHasCRow = (def, name, state) => {
+	if (name === initialStateOf(def)) return [];
+	if (state.actor === "human") return [];
+	const kind = contentKindOf(state);
+	if (kind !== "script" && kind !== "message") return [];
+	if ((state.on ?? []).some(([pattern]) => pattern === "C")) return [];
+	return [`state "${name}" declares no "C" row`];
+};
+/**
 * Validate a `WorkflowDefinition`, returning human-readable error strings
-* (empty = valid). Pure — called at config-load time. Checks at least one
-* state, `entries` shape (`validateEntries`), per-state content/actor/mode/
-* file shape (`validateState`), `modes:` shape, and reachability from an
-* entry root (`validateReachability`, only when entries validated clean).
-* Every per-field rule not listed above (`on`/`retry` targets resolving,
-* `mode` naming a known vocabulary, etc.) is declared once in
-* `src/StateFields.ts`'s `STATE_FIELDS` table instead.
+* (empty = valid) plus non-fatal warning strings. Pure — called at
+* config-load time. Checks at least one state, `entries` shape
+* (`validateEntries`), per-state content/actor/mode/file shape
+* (`validateState`), `modes:` shape, and reachability from an entry root
+* (`validateReachability`, only when entries validated clean). Every
+* per-field rule not listed above (`on`/`retry` targets resolving, `mode`
+* naming a known vocabulary, etc.) is declared once in `src/StateFields.ts`'s
+* `STATE_FIELDS` table instead.
 */
 const validateDefinition = (def) => {
 	const names = Object.keys(def.states);
-	if (names.length === 0) return ["workflow must declare at least one state"];
+	if (names.length === 0) return {
+		errors: ["workflow must declare at least one state"],
+		warnings: []
+	};
 	const entriesErrors = validateEntries(def, names);
-	return [
-		...entriesErrors,
-		...validateModes(def),
-		...names.flatMap((name) => validateState(def, name, names)),
-		...entriesErrors.length === 0 ? validateReachability(def, names) : []
-	];
+	return {
+		errors: [
+			...entriesErrors,
+			...validateModes(def),
+			...names.flatMap((name) => validateState(def, name, names)),
+			...entriesErrors.length === 0 ? validateReachability(def, names) : []
+		],
+		warnings: names.flatMap((name) => validateHasCRow(def, name, def.states[name]))
+	};
 };
 //#endregion
 //#region src/Machines.ts
@@ -191863,19 +191909,20 @@ const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true, f
 		...summary !== void 0 ? { summary } : {}
 	};
 	assertScopesCoverStates(Object.keys(states), flattened.scopes, errors);
-	const definitionErrors = validateDefinition(definition);
-	const allErrors = Array.from(/* @__PURE__ */ new Set([...errors, ...definitionErrors]));
+	const definitionResult = validateDefinition(definition);
+	const allErrors = Array.from(/* @__PURE__ */ new Set([...errors, ...definitionResult.errors]));
 	if (allErrors.length > 0) throw new Error(formatErrors(allErrors));
 	return {
 		definition,
 		vars,
 		tree: flattened.tree,
-		scopes: flattened.scopes
+		scopes: flattened.scopes,
+		warnings: definitionResult.warnings
 	};
 };
 //#endregion
 //#region src/workflows/unified.yaml
-var unified_default = "# gtd's BUILT-IN DEFAULT workflow — used when no `workflow:` key is\n# configured anywhere in the cwd→home config chain; `gtd init` seeds only\n# vars.testCommand + a modes: suggestion, never this file. Compiled through\n# the same `compileWorkflowConfig` a user's own `workflow:` goes through — no\n# privileged path. See skills/authoring/SKILL.md for how to read or edit it\n# (machines, patterns, templates) and docs/driver.md for how a driver runs it.\n#\n# One flow: any change to the tree starts the process. `idle` -> `unwind`\n# reverts that diff (intent survives only in history) -> a green-baseline\n# gate -> `design.triage` groups the reverted diff into ordered, classified\n# concerns and resolves the PRODUCT ones' open questions (`design.gate`) ->\n# `architecture.author` works out the *how* and resolves the TECHNICAL ones\n# (`architecture.gate`) -> `architecture.decompose` writes one package file\n# per concern -> the per-package queue (`packages.*`) builds and reviews each\n# -> the shared tail (`build.review.*`) decides sign-off (-> `idle`, landing\n# an ordinary commit that closes the process — every per-turn commit stays on\n# the branch; run `gtd summary` afterward for a closing-message prompt) vs.\n# actionable feedback (-> `re-unwind` -> back to `design.triage`, a full\n# re-plan lap that never builds on the human's hand-edit). `--entry\n# review-gate.check --var reviewBase=<commitish>` and `--entry fix-precheck`\n# are the two other entries into this same flow.\nvars:\n  testCommand: npm test\n  # plannerModel: the heavier tier for one-shot triage/design/review turns.\n  # coderModel: the tier for build/fix turns. Both repointable via a\n  # top-level `vars:` key or a `GTD_<NAME>` env var, like any other var.\n  plannerModel: smart\n  coderModel: base\n  # Declared (not left undeclared) so `--var reviewBase=...` passes the CLI's\n  # declared-name check; blank renders empty, which the review entry refuses.\n  reviewBase: \"\"\n  # gtd's own voice for generated files — adapted from the \"Spartan\" output\n  # style (https://github.com/alexgreensh/attention-span, AGPL-3.0, version 0.6),\n  # rewritten in gtd's own words for deliverables rather than chat replies;\n  # no upstream text ships. A point-in-time derivation with no refresh\n  # mechanism.\n  styleBlock: |-\n    This file is a deliverable, not a chat reply — size follows the work, and\n    padding is the target of any cut. Lead with the answer immediately; never\n    circle back to restate it once it has landed.\n\n    Write flat, commanding sentences — commit to the claim, do not hedge it.\n    Favor everyday vocabulary; where a term is unavoidable, define it in five\n    words or fewer on first use.\n\n    In markdown, bold carries the load: bold the claim, not the sentence around\n    it — reading only the bold text must yield the full point and every risk.\n\n    Never trim a risk, a number, a threshold, or a scoped condition to save\n    space. This outranks every other rule here.\n\n    Ship the artifact bare — no lead-in, no sign-off wrapped around it.\n    Compressing is not dropping: a task with three load-bearing parts ships all\n    three, each shorter, never two of three.\n\n    One idea per block; break when the idea shifts. Flag risk in one blunt\n    line rather than hedged prose. Never narrate the work — do it.\n  styleFormatContract: |-\n    This file is machine-read; its format contract outranks every style rule\n    above it: keep every `##`/`###` heading, every `- [ ]` checkbox row, and\n    every marker line exactly as specified — do not renumber or rename a\n    heading or replace a checkbox list with prose. A parser reads these\n    literally; a violation refuses the turn outright.\n\n    Voice rules above govern the prose between these elements, never the\n    elements themselves.\n\n  # One persona per prompt-bearing machine below, stamped as its `system:`\n  # (see src/StateFields.ts's `system`). `--system-prompt` REPLACES a\n  # harness's default system prompt — including its injected cwd/env/\n  # git-status block — so each persona is written self-contained, restating\n  # that context explicitly rather than relying on it.\n\n  # Shared conduct tail, appended after every persona's own role paragraph:\n  # use tools without asking, orient yourself with git, and go inspect what\n  # the turn's message names. Deliberately NOT named `*Persona`:\n  # `templates.test.ts` derives its six-name persona set from\n  # `it\\.vars\\.(\\w+Persona)`, so that suffix would silently grow the set.\n  agentConduct: |-\n    You have shell and file tools — bash, read, write, edit — and you are\n    expected to use them without asking first. This runs unattended: there is\n    no one to grant permission, confirm a command, or approve a plan before\n    you act. Investigate with real commands rather than assuming what a file,\n    a commit, or a decision's status actually is, then act on what you find.\n\n    You are already inside a git repository, at the working directory you\n    should treat as your whole world for this turn. There is no injected\n    status block — no cwd, no branch, no recent history, no tree state. Run\n    `git status`, `git log`, `ls` and the like yourself before you do\n    anything else; that is the normal first move of this turn, not an extra\n    step.\n\n    The message you receive each turn names a commit, a range, or a file for\n    you to go inspect yourself — `git show`, `git diff`, reading the file\n    directly — never a diff or a summary rendered into the conversation. Go\n    look before you act. Across the several turns one conversation may span,\n    work from what you already read and settled earlier rather than\n    re-deriving it from a cold read every time, unless the turn's own\n    instructions tell you this is a fresh, cold pass.\n  designPersona: |-\n    You are the product-facing planning voice in an autonomous build pipeline\n    called gtd. Your job is to turn a raw, half-formed sketch — a hand-edit to\n    real code, a scratch note, or both — into an ordered, classified list of\n    concerns a build can execute, and to carry a running conversation with a\n    human about the product decisions that list depends on. You are read by\n    that human, so write plainly and decisively; you are not read by a parser\n    except where a state's own instructions say otherwise.\n  architectPersona: |-\n    You are the technical planning voice in an autonomous build pipeline\n    called gtd. You take over once the product-facing concerns are settled,\n    reading them cold — you do not carry over the product conversation, only\n    its written, settled output. Your job is to work out the technical *how*\n    for each settled concern — file and module structure, data models,\n    library and tech-stack choices, error-handling strategy — raise the\n    technical open questions a human still needs to decide, and once every\n    question is answered, write one package spec file per concern with no\n    further judgement call: the grouping and ordering were already decided\n    upstream, and this final step is a mechanical write-out of a plan you\n    already converged on.\n  reviewerPersona: |-\n    You are the independent reviewing mind in an autonomous build pipeline\n    called gtd — deliberately a separate identity from whichever agent wrote\n    the code under review, so you bring no attachment to how it got built.\n    Your job splits into two distinct turns: first, writing a structured\n    review document that groups a diff into reviewable chunks for a human to\n    read through and comment on; later, reading back a round of that human's\n    feedback — a note, a hand-edit — and classifying whether it is genuinely\n    actionable or just an approving remark, without fixing anything yourself\n    either way. You judge and you classify; you never build.\n  specReviewerPersona: |-\n    You are the adversarial spec-conformance checker in an autonomous build\n    pipeline called gtd, reviewing one freshly-built work package against the\n    written spec it was built from. Your only job is to verify: are the\n    package's tasks actually done, its acceptance criteria actually met, and\n    the code sound and consistent with the rest of the codebase? You write\n    concrete, actionable feedback only when something is genuinely wrong —\n    and when nothing is, you write nothing at all, because a clean turn from\n    you IS the approval. You never fix a problem you find; naming it\n    precisely enough for someone else's fix turn to act on is the whole job.\n  builderPersona: |-\n    You are the TDD implementer in an autonomous build pipeline called gtd.\n    Your job is to build exactly one package's declared scope end to end,\n    tests first, and to come back and fix things when redirected: a failing\n    check's output, or a reviewer's concrete feedback. Stay strictly inside\n    the package in front of you, touching neither another package's files nor\n    code outside the current task. Treat feedback you're given as the\n    diagnosis to act on; discard it, with reason, only when it is simply\n    wrong.\n  finisherPersona: |-\n    You are the closing identity in an autonomous build pipeline called gtd —\n    the last coder this process hands work to before it closes. You are\n    handed a late-breaking failing check after sign-off; fix it, focused and\n    minimal, before the process can close. Every turn you land stays its own\n    commit on the branch — nothing here gets squashed away.\n\n  # The scratchpad-opener sentence shared by every prompt-content state (see\n  # STATE_FIELDS's `prompt`) — this workflow's own state files are its private\n  # working notes, never project code or documentation a human reads. Injected\n  # as the leading line of every prompt body that touches a `.gtd/` file\n  # directly; each state's own \"the only state file this turn touches is X\"\n  # sentence stays local, immediately after the tag. Some states splice a\n  # role clause into this same opening sentence (`build.review.collecting`,\n  # `packages.item.spec.review`) — those hoist the clause to its own leading\n  # sentence ahead of the tag instead, keeping every word.\n  stateFileRules: |-\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.\n  # The open-questions warrant test, decide-it-yourself sink, and `## Open\n  # Questions` checkbox shape shared by `design.triage` and\n  # `architecture.author` — written phase-agnostic (no PRODUCT/TECHNICAL\n  # bake-in) so both sites can inject it verbatim. Each site's own\n  # phase-scope sentence (triage: product-only, technical waits; architecture:\n  # every point here is TECHNICAL) stays local around the tag — the two\n  # genuinely disagree on scope, so that sentence is never shared.\n  # `questionBarReturn` is the return-lap half — split out so each site can\n  # inject it under its own `## Return lap` heading instead of burying\n  # return-lap behaviour inside the first lap's own section.\n  questionBar: |-\n    For every open point, a question is warranted only when all three hold:\n    the answer is a genuine fork with divergent outcomes — user-visible for a\n    product question, materially different implementations for a technical\n    one; the sketch, the entry diff, and history do not already settle it\n    (treat anything the entry diff states explicitly — a directive in\n    `.gtd/TODO.md`, a committed choice in a hand-edit — as already settled,\n    and on a review loop-back lap treat whatever the human's own review-round\n    edit or note states explicitly the same way); and getting it wrong would\n    survive all the way to the human review tail.\n\n    Anything below that bar, decide yourself: record the decision under\n    `## Answered Questions` — the same section a human-answered question\n    lands in — as `### <the point phrased as a question>` followed by the\n    decision and a one-line rationale in prose, no checkboxes.\n\n    A question that clears the bar is written under a `## Open Questions`\n    heading near the top and takes this shape: one `### <question>`\n    sub-heading each, followed by a checkbox list of candidate answers — 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.\n  questionBarReturn: |-\n    The human has ticked one option per question (or replaced\n    `_your answer_` with their own text): fold each chosen answer into its\n    concern's prose, then move the question into a `## Answered Questions`\n    section as `### <question>` followed by the resolved answer in plain\n    prose (drop the checkboxes). Never re-raise a deleted question; treat a\n    deleted `## Open Questions` section as acceptance. Omit `## Open\n    Questions` entirely once there are none left.\n  # The body `packages.item.fix-suite` and `build.fix` share byte for byte —\n  # both fix a red `.gtd/FEEDBACK.md`. `fix-suite` appends its own\n  # cross-package paragraph right after this tag (before the shared\n  # \"Leave everything uncommitted\" close, which stays local at both sites so\n  # the appended paragraph lands in the same position it renders in today);\n  # `build.fix` renders the tag alone.\n  fixFeedbackPrompt: |-\n    The only state file this turn touches is `.gtd/FEEDBACK.md`; 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 `.gtd/FEEDBACK.md` (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    `.gtd/FEEDBACK.md` instead of \"fixing\" a non-issue.\n\n# `gtd summary`'s prompt — printed cold, no session identity, no diff inlined.\n# Names the hashes/range for the agent to inspect itself; renders the same\n# it.processCost/it.processCostByModel the old squash finale used to.\nsummary: |\n  <%~ it.vars.styleBlock %>\n\n\n  Write the closing message for the process HEAD closes or currently sits\n  inside — the text a driver may use for a squash, an amend, or a pull\n  request body. You are starting cold: read every decision back out of the\n  commits named below rather than assuming any prior context.\n\n  Cover the initial motivation, the important decisions, and the trade-offs\n  made, and the high-level architectural changes — never which files\n  changed; that is what `git diff --stat` is for, not this message.\n\n  The process's entry commit is `<%= it.entryCommit %>`. <% if\n  (it.humanCommits.length > 0) { %>The human contributed at these commits,\n  oldest to newest:\n  <% it.humanCommits.forEach(function (c) { %>\n  - `<%= c.hash %>` (entering `<%= c.state %>`)\n  <% }) %><% } else { %>The human left no comment or edit this process —\n  every commit is machine-authored.<% } %>\n\n  Inspect the range yourself: `git log <%= it.processBase %>..<%= it.processTip %>`\n  and `git diff <%= it.processBase %> <%= it.processTip %>`. That range is\n  exactly what a squash or PR body should describe.\n\n  Token cost: <%= it.processCost %>\n  <% it.processCostByModel.forEach(function(m){ %>\n  - <%= m.model %>: <%= m.cost %>\n  <% }) %>\n\n  Print the closing message and stop — this command writes nothing itself.\n\nentry:\n  default: unified\n\nmachines:\n  # Shared green-baseline gate — start-gate/review-gate/fix-precheck all\n  # alias this script via &suiteCheck.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: &suiteCheck |\n          #!/usr/bin/env sh\n          set +e\n          mkdir -p .gtd\n          # Sweep a raw review capture an earlier, abandoned process may have\n          # left behind — no ordinary path from deciding/collecting reaches\n          # this check.\n          rm -f .gtd/REVIEW_RAW.md\n          <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s .gtd/.check-output ]; then\n              mv .gtd/.check-output .gtd/FEEDBACK.md\n            else\n              rm -f .gtd/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > .gtd/FEEDBACK.md\n            fi\n            # Stamp with HEAD so a repeat identical failure still re-registers\n            # as an M/A edit instead of looking byte-identical (GREEN).\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/FEEDBACK.md\n          else\n            rm -f .gtd/.check-output\n            rm -f .gtd/FEEDBACK.md\n          fi\n        # Marks BOTH entryGate instances (start-gate/review-gate); only\n        # review-gate strictly needs it, but the shared dedup makes marking\n        # one mark both — both ARE entry gates.\n        entry: true\n        # Only review-gate binds a real reviewBase (via --var); start-gate\n        # binds \"\" (no base), since it's reached from idle, never entered.\n        reviewBase: $reviewBase\n        on:\n          \"A .gtd/FEEDBACK.md\": blocked\n          \"M .gtd/FEEDBACK.md\": blocked\n          \"D .gtd/REVIEW_RAW.md\": $onGreen\n          \"D .gtd/FEEDBACK.md\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: FEEDBACK.md\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # Shared check/escalate pair for build.health.*/packages.item.health.* —\n  # the caller's own coder fix-state ($onRed), not this machine, handles red.\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # See the shared suite check on `entryGate.check` above.\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": $onRed\n          \"M .gtd/FEEDBACK.md\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: FEEDBACK.md\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `.gtd/FEEDBACK.md` 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  # Shared check/answer pair for design.gate/architecture.gate. No `file:`\n  # PARAM for the probe script itself: machine `$param` substitution is\n  # whole-value only, so a path can't be spliced into a shared script body —\n  # `file` here is instead the `answer` param's own `file:` (the human gate).\n  questionGate:\n    params: [file, message, onNone, onRevise, checkLabel, answerLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: |\n          #!/usr/bin/env sh\n          # Exactly one of REQUIREMENTS.md/ARCHITECTURE.md exists on disk at\n          # a time — architecture.author deletes the former in the same turn\n          # it writes the latter — so this probe is unambiguous either way.\n          set +e\n          mkdir -p .gtd\n          file=.gtd/REQUIREMENTS.md\n          [ -f \"$file\" ] || file=.gtd/ARCHITECTURE.md\n          gtd check qa \"$file\" --open-questions > /dev/null 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            printf 'open questions remain in %s\\n' \"$file\" > .gtd/QUESTIONS.md\n            # See the shared suite check's cache-buster rationale on\n            # `entryGate.check` above.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/QUESTIONS.md\n          else\n            rm -f .gtd/QUESTIONS.md\n          fi\n        on:\n          \"A .gtd/QUESTIONS.md\": answer\n          \"M .gtd/QUESTIONS.md\": answer\n          \"D .gtd/QUESTIONS.md\": $onNone\n          \"C\": $onNone\n      answer:\n        actor: human\n        label: $answerLabel\n        file: $file\n        mode: qa\n        answerGate: true\n        message: $message\n        on:\n          \"* **\":\n            to: $onRevise\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace\n              `_your answer_` for your own) to send it back for the agent to\n              fold your answers in. Delete a question to skip it, or delete\n              the whole `## Open Questions` section to accept the plan as-is.\n\n  # The triage phase — one conversation across the whole back-and-forth (the\n  # human's answer rationale survives every return lap). A review loop-back\n  # lap runs the suite itself and files any breakage as its own FIRST\n  # concern, rather than spending one of packages.item.fix-suite's\n  # (per-episode) retries on breakage the package didn't cause.\n  # ▸ planner identity.\n  designPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.designPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onArchitecture]\n    entry: triage\n    states:\n      triage:\n        actor: agent\n        label: Triaging the change\n        file: REQUIREMENTS.md\n        mode: qa\n        # Guards against discarding assembled review input without folding\n        # it in (the original bug this guard was added for).\n        requireProgress: true\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this turn touches is `.gtd/REQUIREMENTS.md`; develop it. Do\n          not create other files to hold notes or output.\n\n          `.gtd/TODO.md` is the likely home of the sketch that\n          started this process. Despite living beside this workflow's own\n          state files, it is the human's input — the sketch to be folded into\n          the concerns below like any other part of the start diff. It is\n          never a state file to preserve, and never gtd bookkeeping to ignore.\n\n          This process started at commit `<%= it.startCommit %>`. The change\n          that started it was reverted out of the working tree by the\n          `unwind` beat right after it landed, so `git diff <%= it.startCommit %>`\n          (against the working tree) is now empty — its content survives only\n          in history. Find the entry commit yourself: run\n          `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n          (the process's very first turn, landed immediately after\n          `<%= it.startCommit %>`, before any later baseline-repair commits) —\n          then `git show` that commit to see everything that started this\n          process: a hand-edit to real code, a scratch note in some file, or\n          both.\n\n          Whichever lap this is, leave `.gtd/REQUIREMENTS.md` uncommitted and\n          finish your turn once it reflects this lap's own work below.\n\n          ## First lap\n\n          `.gtd/REQUIREMENTS.md` does not exist yet (or holds whatever the\n          human's own change happened to leave there). Build it from that\n          start diff:\n\n          ### Group into concerns\n\n          Group the diff into an ordered list of concerns — each one a\n          coherent piece of work that can leave the test suite green on\n          its own, in the order you'd want them built. If a concern would\n          red-light tests that a later concern is meant to fix, that is\n          not a valid split: merge the two into one concern.\n\n          Two more tests sit beside that green floor, not instead of it.\n          Vertical, not horizontal: slice by capability, never by layer. A\n          concern that only prepares for a later one — types, scaffolding,\n          renames — is folded into the first concern that uses it. Distinct\n          acceptance: each concern needs an observable check that fails\n          before it and passes after; if you can't name one, merge it into\n          its neighbour. Prefer fewer, larger packages — the smallest\n          independently valuable change, not the smallest change that\n          compiles.\n\n          ### Classify each concern\n\n          Classify each concern as PRODUCT (a user-facing/requirements\n          decision) or TECHNICAL (an implementation decision).\n\n          <%~ it.vars.questionBar %>\n\n\n          Raise questions only for product concerns here — a technical\n          concern's open points wait for the next phase. When every concern\n          in this lap is TECHNICAL, write no `## Open Questions` section at\n          all.\n\n          ### Fold in the sketch\n\n          Fold everything the entry commit added into the concerns above —\n          a scratch note and a real code edit are both just a sketch of\n          the intent, a spec to be finished, never work to be preserved;\n          `unwind` already reverted both out of the tree, so there is\n          nothing left to delete. Describe each piece under the concern it\n          belongs to.\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n\n          ## Review loop-back\n\n          `.gtd/REQUIREMENTS.md` already holds concerns and none of them\n          have a ticked-but-unfolded answer waiting — that shape means a\n          completed REVIEW round put this material here, not a question you\n          asked. Develop those existing concerns further with whatever the\n          round raised; never rediscover or regroup them from a cold read\n          the way the first lap does.\n\n          The human's own edit from that review round has been reverted out\n          of the working tree the same way the entry commit is — read it\n          from history, never the working tree: run\n          `git show <%= it.reviewBase %>` to see it. (On the first lap that\n          same hash is the process's own diff base, `<%= it.startCommit %>`,\n          so this branch does not apply: `.gtd/REQUIREMENTS.md`\n          does not exist yet for a review round to have happened against.)\n\n          Whatever this round touches, every decision already settled under\n          `## Answered Questions` stays settled on this lap too — never\n          re-open one. A genuinely open PRODUCT point in the round's own\n          material may still raise a fresh question under\n          `## Open Questions`: the product gate sits on this path exactly as\n          it does on the first lap, and will ask it.\n\n          Before grouping anything on this lap, run\n          `<%= it.vars.testCommand %>` yourself as part of reading the\n          situation: a review loop-back runs no green-baseline gate between\n          the revert above and this turn, so the tree may already be red —\n          reverting the human's edit can undo a fix that edit had put in. If\n          the suite is red, make that breakage the first concern in your\n          ordered list, ahead of everything else — every later concern's\n          \"leaves the suite green on its own\" property assumes the suite\n          already started green.\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: REQUIREMENTS.md\n          onNone: $onArchitecture\n          onRevise: triage\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your product answers\n          message: |\n            `.gtd/REQUIREMENTS.md` holds the concerns under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question 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\n  # A separate machine from designPlan (its own memory scope — a COLD read,\n  # not a resumed conversation). Merge authority lives in `author`, the first\n  # state that knows the *how*: it alone may re-merge concerns, never split;\n  # `decompose` carries that grouping over verbatim. ▸ planner identity.\n  archPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.architectPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onPackages]\n    entry: author\n    states:\n      author:\n        actor: agent\n        label: Refining the technical plan\n        file: ARCHITECTURE.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state files this\n          turn touches are `.gtd/ARCHITECTURE.md` (write it) and\n          `.gtd/REQUIREMENTS.md` (delete it once its content is\n          folded in). Do not create other files to hold notes or output.\n\n          You do not resume the design conversation — this is a separate\n          machine with its own memory, a cold read every time. Read\n          `.gtd/REQUIREMENTS.md` (the settled, ordered, classified\n          concerns) in full. Treat every decision recorded there — plain\n          prose or a resolved `## Answered Questions` entry, PRODUCT or\n          TECHNICAL alike — as settled; never re-open it.\n\n          Cold means the machine carries no conversational memory of\n          triage's own back-and-forth; it never meant no git access. This\n          process started at commit `<%= it.startCommit %>`. Find the\n          process's first turn yourself: run\n          `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n          then `git show` that commit to see everything that started this\n          process: a hand-edit to real code, a scratch note in some file,\n          or both.\n\n          Whichever lap this is, once `.gtd/ARCHITECTURE.md` is written,\n          delete `.gtd/REQUIREMENTS.md` — its content has been folded in and\n          it must not linger. Leave everything uncommitted and finish your\n          turn.\n\n          ## First lap\n\n          Develop `.gtd/ARCHITECTURE.md` from those concerns: for each one,\n          in the same order, work out the *how* — file/module structure,\n          data models, library/tech-stack choices, error-handling strategy —\n          building on the *what* already settled.\n\n          You now know the *how*, so you know each concern's file footprint —\n          list each concern's primary paths. Merge concerns whose footprints\n          center on the same files into one, unless the later one only\n          consumes an interface the earlier one creates: that exception is\n          what keeps a genuine build-on-top sequence from collapsing into one\n          blob. This authority is to merge only, never to split — granting\n          split authority here would work directly against the goal; the\n          whole problem is over-granularity. Record every merge under a\n          dedicated `## Merged Concerns` heading, carrying both merged requirements\n          verbatim so the per-package spec review still covers each one\n          independently. A merge raises no open question and stops for no\n          human — do not route it to `architecture.gate` for a veto; the\n          human still sees every merge when they review the plan, and the\n          per-package spec review is the real safety net. Prefer fewer,\n          larger packages — the smallest independently valuable change, not\n          the smallest change that compiles.\n\n          Every open point here is TECHNICAL — triage already resolved the\n          product ones, one phase earlier.\n\n          <%~ it.vars.questionBar %>\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: ARCHITECTURE.md\n          onNone: decompose\n          onRevise: author\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your technical answers\n          message: |\n            `.gtd/ARCHITECTURE.md` holds the technical plan under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question 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\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state files this turn touches\n          are the package files it writes under `.gtd/packages/` and\n          `.gtd/ARCHITECTURE.md`, which it deletes. Do not create other\n          files to hold notes or output.\n\n          If you wrote `.gtd/ARCHITECTURE.md` earlier in this\n          conversation, work from what you already settled; otherwise read it\n          (the converged technical plan) yourself. It already lists an\n          ordered set of concerns with every merge/split judgement\n          `architecture.author` made — this turn is a mechanical write-out,\n          not a planning one. A `## Merged Concerns` heading there is a\n          record of those merges, never a concern of its own: write no\n          package file for it.\n\n          Write one package file per concern, in the settled order, under\n          `.gtd/packages/` (e.g.\n          `.gtd/packages/01-name.md`,\n          `.gtd/packages/02-name.md`, ...). Each package file\n          carries that concern's requirement(s) (so it can be reviewed\n          against its spec — both, independently, when the concern was\n          merged), its independent tasks, and each task's acceptance\n          criteria as `- [ ]` checkboxes and relevant paths. Do not merge or\n          split concerns here — that judgement already happened in\n          `architecture.author`; carry the settled grouping over verbatim.\n          No package file may reference any other `.gtd/` file.\n\n          Once the package files are written, delete\n          `.gtd/ARCHITECTURE.md`. Leave everything uncommitted and\n          finish your turn.\n        on:\n          \"* .gtd/packages/**\": $onPackages\n\n  # The shared review tail. ▸ planner identity — `collecting` only judges/\n  # classifies feedback; there's no coder follow-through inside this machine.\n  #\n  # Nested inside buildTail (build.review), not a root sibling: a machine's\n  # memory scope is its dotted instance path, so nesting keeps `build.fix ->\n  # build.health.check -> build.review.*` (the `--entry fix-precheck` path)\n  # inside one scope, so the sign-off's boundary commit lands from the same\n  # scope that made the fixes.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.reviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # `gtd --entry review-gate.check` enters via review-gate.check first\n        # (never straight here), which sets the Gtd-Review-Base trailer this\n        # tail reuses.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this turn touches is `.gtd/REVIEW.md`; write it at exactly\n          that path. Do not create other files to hold notes or output.\n\n          Write `.gtd/REVIEW.md` 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 file pointer per hunk (checkboxes are\n            for the human to tick, not you; every path is `./`-relative, with an\n            optional `#line`). Put the note's opening line right on the\n            pointer's own line, after a dash — the reflow-proof shape:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n\n            If the note needs more than one line, continue it on the line(s)\n            below the pointer, indented exactly two spaces — never four or\n            more, which after a blank line reads as an indented code block\n            and never reflows:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n                  and here is more detail, continued below it\n\n            A note that sits entirely on the line(s) beneath the pointer is\n            also valid. Either way, the explanation itself must never start\n            with a bare `./path` token — that parses as a second hunk pointer,\n            not a 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 `.gtd/REVIEW.md` uncommitted and finish your turn.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: REVIEW.md\n        mode: review\n        message: |\n          `.gtd/REVIEW.md` 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          Review the diff yourself, with whatever tool you like — gtd checks\n          nothing out and touches no ref; `gtd base` prints this same hash any\n          time you need it again. The range runs from the review base to the\n          working tree:\n\n              git diff <%= it.reviewBase %>\n\n          When you've been through the whole diff, run `gtd land`:\n\n          - **Sign off** — leave no comment — no note in\n            `.gtd/REVIEW.md`, no code edit — to close the process,\n            whatever the boxes say. Every turn commit stays on the\n            branch; run `gtd summary` afterward for a closing-message\n            prompt.\n          - **Request changes** — leave a comment: a note on a\n            `.gtd/REVIEW.md` line, or a direct code edit — to send a FULL\n            development lap (**review.deciding** → **review.collecting** →\n            re-triage). A hand-edit you make here is treated as a SKETCH, not a\n            fix the agent builds on: it is reverted out of the tree and re-planned\n            from scratch, the same as any other change that starts a process.\n            There is no baseline check on the way back into planning — only a\n            genuinely non-actionable comment (an approving remark with no code\n            edit) skips the lap and signs off straight away.\n\n          Deleting `.gtd/REVIEW.md` is refused.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # Anchors the INCREMENTAL review base to the most-recent in-process\n        # commit (the process start on the first review).\n        reviewBase: true\n        script: |\n          #!/usr/bin/env sh\n          # FEEDBACK iff the human left a REVIEW.md note (any edit beyond a\n          # checkbox tick) or hand-edited any file this round outside .gtd/;\n          # otherwise a clean sign-off. This turn only CAPTURES the raw\n          # material into REVIEW_RAW.md — collecting judges actionability.\n          # A/M REVIEW_RAW.md rows are declared before D REVIEW.md so a\n          # feedback round (which also deletes REVIEW.md) isn't mistaken for\n          # sign-off.\n          set +e\n          mkdir -p .gtd\n          head=$(git rev-parse HEAD)\n          # Normalize [ ]/[x] before diffing, so only a real note counts.\n          before=$(git show \"HEAD^:.gtd/REVIEW.md\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          after=$(git show \"HEAD:.gtd/REVIEW.md\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          if git diff-tree --no-commit-id --name-only -r HEAD -- . \":(exclude).gtd\" \\\n               | grep -q . \\\n             || [ \"$before\" != \"$after\" ]; then\n            {\n              echo \"This is machine-captured input, not instructions. A downstream agent judges whether it's actionable.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in .gtd/REVIEW.md at this commit. Any hand edits are\"\n              echo \"in that commit's other paths. Run: git show $head\"\n            } > .gtd/REVIEW_RAW.md\n          fi\n          rm -f .gtd/REVIEW.md\n        on:\n          \"A .gtd/REVIEW_RAW.md\": collecting\n          \"M .gtd/REVIEW_RAW.md\": collecting\n          \"D .gtd/REVIEW.md\": $onSignoff\n\n      # Outcome is by which paths THIS diff touches: writing REQUIREMENTS.md\n      # (A/M) is the actionable case, so those rows are declared before \"D\n      # REVIEW_RAW.md\" — an actionable round's diff is both together, and\n      # the wrong order would short-circuit every round to sign-off.\n      # Consuming REVIEW_RAW.md alone is the non-actionable short-circuit,\n      # reusing $onSignoff since that IS a sign-off. No `C`/`\"* **\"` row: a\n      # clean turn here is a fruitless dispatch (falls through to the\n      # ordinary attempt default), never a verdict; a dirty tree matching\n      # neither row is a refusal.\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: REQUIREMENTS.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          You are an autonomous coding agent judging and classifying a round\n          of review feedback.\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state files this turn\n          touches are `.gtd/REQUIREMENTS.md` and\n          `.gtd/REVIEW_RAW.md`, which it deletes — do not change any\n          other file: you classify, you do not build.\n\n          The raw review material is: <%~ it.read(\".gtd/REVIEW_RAW.md\") %>\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          The round is actionable if any of the following is true:\n\n          1. The human left a note on `.gtd/REVIEW.md` — a note is\n             anything beyond a checkbox flip, regardless of whether the box\n             itself is ticked (ticking means only \"I read this hunk\", never\n             sign-off). A note is a mandatory concern below, whether or not\n             its box is ticked.\n          2. The human added a code comment this round (a `+` line that is a\n             comment, in a hand-edited file) — even a plain-prose one. That\n             comment is an instruction: describe it as a concern below, and\n             note that the comment line itself is transient — it must not\n             survive the lap that satisfies it.\n          3. The human hand-edited any non-comment code this round. That code\n             is no longer an already-committed intent to build on top of — it\n             is a sketch, like the entry commit's own diff: describe what it\n             was reaching for under the concern it belongs to, and expect the\n             lap that follows to re-derive it from scratch. Never say the\n             human's lines are final or that they must survive unchanged.\n\n          The round is not actionable only when none of the above holds — the\n          human left nothing but an approving remark (a compliment, a \"looks\n          good\", or similar) with no code edit and no substantive note. Never\n          invent actionability where the definition above doesn't hold — it\n          manufactures a lap nothing asked for — and never dismiss a real note\n          or edit as approval, which drops feedback the human left.\n\n          If the round is actionable: write `.gtd/REQUIREMENTS.md`\n          with an ordered list of concerns, each classified PRODUCT (a\n          user-facing/requirements decision) or TECHNICAL (an implementation\n          decision) — the same shape `design.triage` builds, one\n          `## <heading>` per concern, in the order you'd want them built. Fold\n          every note, comment, and hand-edit from this round in under the\n          concern it belongs to, per the rules above. Raise no open\n          questions here — write no `## Open Questions` section;\n          `design.triage` owns that, one phase later. Then delete\n          `.gtd/REVIEW_RAW.md` and finish your turn.\n\n          If the round is not actionable: delete\n          `.gtd/REVIEW_RAW.md` and finish your turn, writing nothing\n          to `.gtd/REQUIREMENTS.md` — consuming the capture with no\n          other change is the sign-off.\n        on:\n          \"A .gtd/REQUIREMENTS.md\": $onFeedback\n          \"M .gtd/REQUIREMENTS.md\": $onFeedback\n          \"D .gtd/REVIEW_RAW.md\": $onSignoff\n\n  # The per-package review — a separate MIND from the implementer. ▸ planner\n  # identity; fixing findings is a coder action (packages.item.fix-spec).\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.specReviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # No retry cap: the loop only re-enters through\n        # `fix-spec`/`health.check`, so under the per-episode rule this state's\n        # episode count can never exceed 1 and a cap could never fire. The\n        # spec-review loop is genuinely unbounded — see docs/configuration.md's\n        # `retry` documentation.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          You are an autonomous coding agent reviewing a freshly-built work package\n          against its own spec.\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this turn touches is\n          `.gtd/SPEC_FEEDBACK.md`; 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(\".gtd/NEXT.md\") %>\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 `.gtd/SPEC_FEEDBACK.md` 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 .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"M .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"D .gtd/SPEC_FEEDBACK.md\": $onApproved\n          \"C\": $onApproved\n\n  # The per-package build queue — identity-free; build identity lives in\n  # 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 sh\n          # Mechanics only — NEXT.md's presence/absence is interpreted by\n          # the `on` rows below, never here.\n          set +e\n          mkdir -p .gtd\n          # Sweep spent design/architecture steering files (gone by now) and\n          # any REVIEW_RAW.md the review loop-back left behind — the only\n          # sweeper on that path before it would leak into a later `gtd\n          # summary` prompt's diff range.\n          rm -f .gtd/REQUIREMENTS.md .gtd/ARCHITECTURE.md .gtd/QUESTIONS.md .gtd/REVIEW_RAW.md\n          # Names are gtd-authored, never containing whitespace — safe to\n          # disable SC2012.\n          # shellcheck disable=SC2012\n          next=$(ls .gtd/packages/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            printf '%s' \"$next\" > .gtd/NEXT.md\n          else\n            rm -f .gtd/NEXT.md\n          fi\n        on:\n          \"D .gtd/NEXT.md\": $onDrained\n          \"* .gtd/NEXT.md\": item.building\n          \"C\": $onDrained\n\n      # Its own coder machine (below) keeps `packages` itself a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # The per-package build identity. ▸ coder identity. packages.item.closing\n  # -> picking is the one upward-resolving target in the file, hence $onNext.\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.builderPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this\n          turn may write is `.gtd/SATISFIED.md` (see below); do not\n          delete the package file (the spec-review gate reads it after you)\n          and never touch `.gtd/NEXT.md` — the `picking` state owns\n          it.\n\n          The package to implement is: <%~ it.read(\".gtd/NEXT.md\") %>\n\n          Before implementing anything, check the package's acceptance criteria\n          against the current tree — an earlier package's fix turn may already\n          have satisfied them. If **every** criterion is already met, implement\n          nothing: write `.gtd/SATISFIED.md` recording each criterion\n          and the concrete evidence it is already satisfied (the commit, file,\n          or symbol that proves it), change nothing else, and finish your turn.\n          If any criterion is outstanding, implement the package normally and\n          do not write that file.\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          \"A .gtd/SATISFIED.md\": &satisfied\n            to: health.check\n            action: Close as already satisfied\n            describe: >-\n              record per-criterion evidence in .gtd/SATISFIED.md when this\n              package's work already landed (an earlier package's fix turn\n              pulled it in) — the package still runs the checks and the spec\n              review, then closes out.\n          \"M .gtd/SATISFIED.md\": *satisfied\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\n          If the\n          only way to green the suite is to implement work that another\n          package file describes, make the smallest change that gets there and\n          do it — that later package will then legitimately report itself\n          already satisfied when its turn comes.\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: SPEC_FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n          The only state file this\n          turn touches is `.gtd/SPEC_FEEDBACK.md`; address it, then\n          delete it. Do not create other files to hold notes or output.\n\n          Read `.gtd/SPEC_FEEDBACK.md` (the reviewer's concerns about the\n          current package) and the package spec (`<%= it.read(\".gtd/NEXT.md\") %>`),\n          then fix the code to resolve every concern. Keep the change focused.\n\n          Delete `.gtd/SPEC_FEEDBACK.md` 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 sh\n          # Removes the just-reviewed package file (path in NEXT.md) plus\n          # leftover spec feedback/evidence, so picking selects the next.\n          # Reached only on spec-review approval — that loop carries no retry\n          # cap, so there is no force-close path here.\n          set +e\n          pkg=$(cat .gtd/NEXT.md 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f .gtd/SPEC_FEEDBACK.md .gtd/NEXT.md .gtd/SATISFIED.md\n        on:\n          \"* **\": $onNext\n\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      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # The process's build identity. ▸ coder identity — model/system stamped\n  # onto fix.\n  buildTail:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.finisherPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onDone, onFeedback]\n    # entry: is required by the machine grammar even though nothing resolves\n    # this machine bare; `fix` is an arbitrary pick.\n    entry: fix\n    states:\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\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      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      # Nested here (not root) so the sign-off's boundary commit stays inside\n      # the builder's own scope — see humanReview above.\n      review:\n        machine: humanReview\n        with:\n          onSignoff: $onDone\n          onFeedback: $onFeedback\n\n  # WIRING ONLY — the root ties together the machine tree above.\n  unified:\n    entry: idle\n    states:\n      idle:\n        actor: human\n        label: Idle\n        file: TODO.md\n        message: |\n          No active gtd process.\n\n          To start one, make ANY change — a hand-edit to real code, a scratch\n          note, anything at all. .gtd/TODO.md is a good default\n          place to start sketching. gtd treats it as a SKETCH, not finished\n          work: the very next beat unwinds it out of your working tree (its\n          intent survives in history, for the triage phase to read), then\n          checks the test baseline is green, then triages the reverted diff\n          into ordered, classified concerns: product questions, then\n          technical questions, then one package per concern, built and\n          reviewed in parallel.\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: unwind\n            action: Start\n            describe: >-\n              make any change — gtd unwinds it out of your working tree (its\n              intent survives in history) before checking the test baseline is\n              green, then triages the reverted diff into ordered, classified\n              concerns and resolves product questions, then technical ones,\n              before building each concern's package (**unwind** ->\n              **start-gate.check**).\n\n      # --entry fix-precheck: a red suite drops into build.fix (-> health ->\n      # review tail); a green suite is a no-op back to idle.\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": build.fix\n          \"M .gtd/FEEDBACK.md\": build.fix\n          \"D .gtd/REVIEW_RAW.md\": idle\n          \"D .gtd/FEEDBACK.md\": idle\n          \"C\": idle\n\n      # Separate from start-gate.check: that gate's blocked -> check retry\n      # edge would otherwise re-run a revert here and discard a human's\n      # baseline repair. One inbound edge (from idle) means unwind runs\n      # exactly once, so it needs no idempotence guard itself.\n      unwind:\n        actor: check\n        label: Unwinding your input\n        script: |\n          #!/usr/bin/env sh\n          set +e\n          # Hoisted here, 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.\n          # Uses it.currentCommit (render-time), not bare HEAD, so a\n          # late-running driver still reverts the right commit.\n          commit=\"<%~ it.currentCommit %>\"\n          git revert --no-commit \"$commit\"\n        on:\n          \"* **\": start-gate\n\n      # Reverts the human's own review-round hand-edit before re-planning,\n      # scoped to real code (`.gtd/` excluded — REVIEW.md is already gone by\n      # now). Names the commit via it.reviewBase (reviewBaseFor's own\n      # `await-review -> deciding` commit), never bare HEAD.\n      #\n      # requireRevert (below) re-checks the tree itself and refuses the step\n      # if residue remains, rather than trusting the script's exit code — a\n      # clean-filter round-trip or binary path can make `git apply -R` a\n      # silent no-op. Both `on` rows below target `design`: a hand-edited\n      # round leaves a dirty tree, a note-only round's patch is empty and\n      # leaves the tree clean — both are legitimate outcomes here, not a\n      # stall.\n      #\n      # `file: REVIEW.md` + `requireRevert: true` exist only to give that\n      # guard the path to exempt (it reads Rest.hints.file, never this\n      # literal) — REVIEW.md is already gone two commits earlier, so this\n      # state never renders it.\n      re-unwind:\n        actor: check\n        label: Re-unwinding your review edit\n        file: REVIEW.md\n        requireRevert: true\n        script: |\n          #!/usr/bin/env sh\n          # Scoped revert of the human's review-round edit — .gtd/ excluded\n          # (the guard's isCodePath re-derives the same exemption; keep both\n          # in sync). Expected to succeed; requireRevert catches a silent\n          # apply failure.\n          set +e\n          # Hoisted here, 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.\n          commit=\"<%~ it.reviewBase %>\"\n          patch=.gtd/.re-unwind.patch\n          mkdir -p .gtd\n          git diff --binary \"$commit^\" \"$commit\" -- . \":(exclude).gtd\" > \"$patch\"\n          if [ -s \"$patch\" ]; then\n            git apply -R \"$patch\" || echo \"re-unwind: could not revert $commit\" >&2\n          fi\n          rm -f \"$patch\"\n        on:\n          \"* **\": design # a code hand-edit was reverted\n          \"C\": design # note-only round: nothing to revert\n\n      start-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            `.gtd/FEEDBACK.md` 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            (**start-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      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            `.gtd/FEEDBACK.md` 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      design:\n        machine: designPlan\n        with:\n          onArchitecture: architecture\n\n      architecture:\n        machine: archPlan\n        with:\n          onPackages: packages\n\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      build:\n        machine: buildTail\n        with:\n          onDone: idle\n          onFeedback: re-unwind\n";
+var unified_default = "# gtd's BUILT-IN DEFAULT workflow — used when no `workflow:` key is\n# configured anywhere in the cwd→home config chain; `gtd init` seeds only\n# vars.testCommand + a modes: suggestion, never this file. Compiled through\n# the same `compileWorkflowConfig` a user's own `workflow:` goes through — no\n# privileged path. See skills/authoring/SKILL.md for how to read or edit it\n# (machines, patterns, templates) and docs/driver.md for how a driver runs it.\n#\n# One flow: any change to the tree starts the process. `idle` -> `unwind`\n# reverts that diff (intent survives only in history) -> a green-baseline\n# gate -> `design.triage` groups the reverted diff into ordered, classified\n# concerns and resolves the PRODUCT ones' open questions (`design.gate`) ->\n# `architecture.author` works out the *how* and resolves the TECHNICAL ones\n# (`architecture.gate`) -> `architecture.decompose` writes one package file\n# per concern -> the per-package queue (`packages.*`) builds and reviews each\n# -> the shared tail (`build.review.*`) decides sign-off (-> `idle`, landing\n# an ordinary commit that closes the process — every per-turn commit stays on\n# the branch; run `gtd summary` afterward for a closing-message prompt) vs.\n# actionable feedback (-> `re-unwind` -> back to `design.triage`, a full\n# re-plan lap that never builds on the human's hand-edit). `--entry\n# review-gate.check --var reviewBase=<commitish>` and `--entry fix-precheck`\n# are the two other entries into this same flow.\nvars:\n  testCommand: npm test\n  # plannerModel: the heavier tier for one-shot triage/design/review turns.\n  # coderModel: the tier for build/fix turns. Both repointable via a\n  # top-level `vars:` key or a `GTD_<NAME>` env var, like any other var.\n  plannerModel: smart\n  coderModel: base\n  # Declared (not left undeclared) so `--var reviewBase=...` passes the CLI's\n  # declared-name check; blank renders empty, which the review entry refuses.\n  reviewBase: \"\"\n  # gtd's own voice for generated files — adapted from the \"Spartan\" output\n  # style (https://github.com/alexgreensh/attention-span, AGPL-3.0, version 0.6),\n  # rewritten in gtd's own words for deliverables rather than chat replies;\n  # no upstream text ships. A point-in-time derivation with no refresh\n  # mechanism.\n  styleBlock: |-\n    This file is a deliverable, not a chat reply — size follows the work, and\n    padding is the target of any cut. Lead with the answer immediately; never\n    circle back to restate it once it has landed.\n\n    Write flat, commanding sentences — commit to the claim, do not hedge it.\n    Favor everyday vocabulary; where a term is unavoidable, define it in five\n    words or fewer on first use.\n\n    In markdown, bold carries the load: bold the claim, not the sentence around\n    it — reading only the bold text must yield the full point and every risk.\n\n    Never trim a risk, a number, a threshold, or a scoped condition to save\n    space. This outranks every other rule here.\n\n    Ship the artifact bare — no lead-in, no sign-off wrapped around it.\n    Compressing is not dropping: a task with three load-bearing parts ships all\n    three, each shorter, never two of three.\n\n    One idea per block; break when the idea shifts. Flag risk in one blunt\n    line rather than hedged prose. Never narrate the work — do it.\n  styleFormatContract: |-\n    This file is machine-read; its format contract outranks every style rule\n    above it: keep every `##`/`###` heading, every `- [ ]` checkbox row, and\n    every marker line exactly as specified — do not renumber or rename a\n    heading or replace a checkbox list with prose. A parser reads these\n    literally; a violation refuses the turn outright.\n\n    Voice rules above govern the prose between these elements, never the\n    elements themselves.\n\n  # One persona per prompt-bearing machine below, stamped as its `system:`\n  # (see src/StateFields.ts's `system`). `--system-prompt` REPLACES a\n  # harness's default system prompt — including its injected cwd/env/\n  # git-status block — so each persona is written self-contained, restating\n  # that context explicitly rather than relying on it.\n\n  # Shared conduct tail, appended after every persona's own role paragraph:\n  # use tools without asking, orient yourself with git, and go inspect what\n  # the turn's message names. Deliberately NOT named `*Persona`:\n  # `templates.test.ts` derives its six-name persona set from\n  # `it\\.vars\\.(\\w+Persona)`, so that suffix would silently grow the set.\n  agentConduct: |-\n    You have shell and file tools — bash, read, write, edit — and you are\n    expected to use them without asking first. This runs unattended: there is\n    no one to grant permission, confirm a command, or approve a plan before\n    you act. Investigate with real commands rather than assuming what a file,\n    a commit, or a decision's status actually is, then act on what you find.\n\n    You are already inside a git repository, at the working directory you\n    should treat as your whole world for this turn. There is no injected\n    status block — no cwd, no branch, no recent history, no tree state. Run\n    `git status`, `git log`, `ls` and the like yourself before you do\n    anything else; that is the normal first move of this turn, not an extra\n    step.\n\n    The message you receive each turn names a commit, a range, or a file for\n    you to go inspect yourself — `git show`, `git diff`, reading the file\n    directly — never a diff or a summary rendered into the conversation. Go\n    look before you act. Across the several turns one conversation may span,\n    work from what you already read and settled earlier rather than\n    re-deriving it from a cold read every time, unless the turn's own\n    instructions tell you this is a fresh, cold pass.\n  designPersona: |-\n    You are the product-facing planning voice in an autonomous build pipeline\n    called gtd. Your job is to turn a raw, half-formed sketch — a hand-edit to\n    real code, a scratch note, or both — into an ordered, classified list of\n    concerns a build can execute, and to carry a running conversation with a\n    human about the product decisions that list depends on. You are read by\n    that human, so write plainly and decisively; you are not read by a parser\n    except where a state's own instructions say otherwise.\n  architectPersona: |-\n    You are the technical planning voice in an autonomous build pipeline\n    called gtd. You take over once the product-facing concerns are settled,\n    reading them cold — you do not carry over the product conversation, only\n    its written, settled output. Your job is to work out the technical *how*\n    for each settled concern — file and module structure, data models,\n    library and tech-stack choices, error-handling strategy — raise the\n    technical open questions a human still needs to decide, and once every\n    question is answered, write one package spec file per concern with no\n    further judgement call: the grouping and ordering were already decided\n    upstream, and this final step is a mechanical write-out of a plan you\n    already converged on.\n  reviewerPersona: |-\n    You are the independent reviewing mind in an autonomous build pipeline\n    called gtd — deliberately a separate identity from whichever agent wrote\n    the code under review, so you bring no attachment to how it got built.\n    Your job splits into two distinct turns: first, writing a structured\n    review document that groups a diff into reviewable chunks for a human to\n    read through and comment on; later, reading back a round of that human's\n    feedback — a note, a hand-edit — and classifying whether it is genuinely\n    actionable or just an approving remark, without fixing anything yourself\n    either way. You judge and you classify; you never build.\n  specReviewerPersona: |-\n    You are the adversarial spec-conformance checker in an autonomous build\n    pipeline called gtd, reviewing one freshly-built work package against the\n    written spec it was built from. Your only job is to verify: are the\n    package's tasks actually done, its acceptance criteria actually met, and\n    the code sound and consistent with the rest of the codebase? You write\n    concrete, actionable feedback only when something is genuinely wrong —\n    and when nothing is, you write nothing at all, because a clean turn from\n    you IS the approval. You never fix a problem you find; naming it\n    precisely enough for someone else's fix turn to act on is the whole job.\n  builderPersona: |-\n    You are the TDD implementer in an autonomous build pipeline called gtd.\n    Your job is to build exactly one package's declared scope end to end,\n    tests first, and to come back and fix things when redirected: a failing\n    check's output, or a reviewer's concrete feedback. Stay strictly inside\n    the package in front of you, touching neither another package's files nor\n    code outside the current task. Treat feedback you're given as the\n    diagnosis to act on; discard it, with reason, only when it is simply\n    wrong.\n  finisherPersona: |-\n    You are the closing identity in an autonomous build pipeline called gtd —\n    the last coder this process hands work to before it closes. You are\n    handed a late-breaking failing check after sign-off; fix it, focused and\n    minimal, before the process can close. Every turn you land stays its own\n    commit on the branch — nothing here gets squashed away.\n\n  # The scratchpad-opener sentence shared by every prompt-content state (see\n  # STATE_FIELDS's `prompt`) — this workflow's own state files are its private\n  # working notes, never project code or documentation a human reads. Injected\n  # as the leading line of every prompt body that touches a `.gtd/` file\n  # directly; each state's own \"the only state file this turn touches is X\"\n  # sentence stays local, immediately after the tag. Some states splice a\n  # role clause into this same opening sentence (`build.review.collecting`,\n  # `packages.item.spec.review`) — those hoist the clause to its own leading\n  # sentence ahead of the tag instead, keeping every word.\n  stateFileRules: |-\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.\n  # The open-questions warrant test, decide-it-yourself sink, and `## Open\n  # Questions` checkbox shape shared by `design.triage` and\n  # `architecture.author` — written phase-agnostic (no PRODUCT/TECHNICAL\n  # bake-in) so both sites can inject it verbatim. Each site's own\n  # phase-scope sentence (triage: product-only, technical waits; architecture:\n  # every point here is TECHNICAL) stays local around the tag — the two\n  # genuinely disagree on scope, so that sentence is never shared.\n  # `questionBarReturn` is the return-lap half — split out so each site can\n  # inject it under its own `## Return lap` heading instead of burying\n  # return-lap behaviour inside the first lap's own section.\n  questionBar: |-\n    For every open point, a question is warranted only when all three hold:\n    the answer is a genuine fork with divergent outcomes — user-visible for a\n    product question, materially different implementations for a technical\n    one; the sketch, the entry diff, and history do not already settle it\n    (treat anything the entry diff states explicitly — a directive in\n    `.gtd/TODO.md`, a committed choice in a hand-edit — as already settled,\n    and on a review loop-back lap treat whatever the human's own review-round\n    edit or note states explicitly the same way); and getting it wrong would\n    survive all the way to the human review tail.\n\n    Anything below that bar, decide yourself: record the decision under\n    `## Answered Questions` — the same section a human-answered question\n    lands in — as `### <the point phrased as a question>` followed by the\n    decision and a one-line rationale in prose, no checkboxes.\n\n    A question that clears the bar is written under a `## Open Questions`\n    heading near the top and takes this shape: one `### <question>`\n    sub-heading each, followed by a checkbox list of candidate answers — 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.\n  questionBarReturn: |-\n    The human has ticked one option per question (or replaced\n    `_your answer_` with their own text): fold each chosen answer into its\n    concern's prose, then move the question into a `## Answered Questions`\n    section as `### <question>` followed by the resolved answer in plain\n    prose (drop the checkboxes). Never re-raise a deleted question; treat a\n    deleted `## Open Questions` section as acceptance. Omit `## Open\n    Questions` entirely once there are none left.\n  # The body `packages.item.fix-suite` and `build.fix` share byte for byte —\n  # both fix a red `.gtd/FEEDBACK.md`. `fix-suite` appends its own\n  # cross-package paragraph right after this tag (before the shared\n  # \"Leave everything uncommitted\" close, which stays local at both sites so\n  # the appended paragraph lands in the same position it renders in today);\n  # `build.fix` renders the tag alone.\n  fixFeedbackPrompt: |-\n    The only state file this turn touches is `.gtd/FEEDBACK.md`; 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 `.gtd/FEEDBACK.md` (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    `.gtd/FEEDBACK.md` instead of \"fixing\" a non-issue.\n\n# `gtd summary`'s prompt — printed cold, no session identity, no diff inlined.\n# Names the hashes/range for the agent to inspect itself; renders the same\n# it.processCost/it.processCostByModel the old squash finale used to.\nsummary: |\n  <%~ it.vars.styleBlock %>\n\n\n  Write the closing message for the process HEAD closes or currently sits\n  inside — the text a driver may use for a squash, an amend, or a pull\n  request body. You are starting cold: read every decision back out of the\n  commits named below rather than assuming any prior context.\n\n  Cover the initial motivation, the important decisions, and the trade-offs\n  made, and the high-level architectural changes — never which files\n  changed; that is what `git diff --stat` is for, not this message.\n\n  The process's entry commit is `<%= it.entryCommit %>`. <% if\n  (it.humanCommits.length > 0) { %>The human contributed at these commits,\n  oldest to newest:\n  <% it.humanCommits.forEach(function (c) { %>\n  - `<%= c.hash %>` (entering `<%= c.state %>`)\n  <% }) %><% } else { %>The human left no comment or edit this process —\n  every commit is machine-authored.<% } %>\n\n  Inspect the range yourself: `git log <%= it.processBase %>..<%= it.processTip %>`\n  and `git diff <%= it.processBase %> <%= it.processTip %>`. That range is\n  exactly what a squash or PR body should describe.\n\n  Token cost: <%= it.processCost %>\n  <% it.processCostByModel.forEach(function(m){ %>\n  - <%= m.model %>: <%= m.cost %>\n  <% }) %>\n\n  Print the closing message and stop — this command writes nothing itself.\n\nentry:\n  default: unified\n\nmachines:\n  # Shared green-baseline gate — start-gate/review-gate/fix-precheck all\n  # alias this script via &suiteCheck.\n  entryGate:\n    params: [onGreen, blockedMessage, blockedDescribe, checkLabel, blockedLabel, reviewBase]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: &suiteCheck |\n          #!/usr/bin/env sh\n          set +e\n          mkdir -p .gtd\n          # Sweep a raw review capture an earlier, abandoned process may have\n          # left behind — no ordinary path from deciding/collecting reaches\n          # this check.\n          rm -f .gtd/REVIEW_RAW.md\n          <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            if [ -s .gtd/.check-output ]; then\n              mv .gtd/.check-output .gtd/FEEDBACK.md\n            else\n              rm -f .gtd/.check-output\n              printf 'the test command failed with exit code %s and produced no output.' \"$code\" > .gtd/FEEDBACK.md\n            fi\n            # Stamp with HEAD so a repeat identical failure still re-registers\n            # as an M/A edit instead of looking byte-identical (GREEN).\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/FEEDBACK.md\n          else\n            rm -f .gtd/.check-output\n            rm -f .gtd/FEEDBACK.md\n          fi\n        # Marks BOTH entryGate instances (start-gate/review-gate); only\n        # review-gate strictly needs it, but the shared dedup makes marking\n        # one mark both — both ARE entry gates.\n        entry: true\n        # Only review-gate binds a real reviewBase (via --var); start-gate\n        # binds \"\" (no base), since it's reached from idle, never entered.\n        reviewBase: $reviewBase\n        on:\n          \"A .gtd/FEEDBACK.md\": blocked\n          \"M .gtd/FEEDBACK.md\": blocked\n          \"D .gtd/REVIEW_RAW.md\": $onGreen\n          \"D .gtd/FEEDBACK.md\": $onGreen\n          \"C\": $onGreen\n      blocked:\n        actor: human\n        label: $blockedLabel\n        file: FEEDBACK.md\n        message: $blockedMessage\n        on:\n          \"* **\":\n            to: check\n            action: Retry check\n            describe: $blockedDescribe\n\n  # Shared check/escalate pair for build.health.*/packages.item.health.* —\n  # the caller's own coder fix-state ($onRed), not this machine, handles red.\n  healthGate:\n    params: [onGreen, onRed, escalateDescribe, checkLabel, escalateLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        # See the shared suite check on `entryGate.check` above.\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": $onRed\n          \"M .gtd/FEEDBACK.md\": $onRed\n          \"* **\": $onGreen\n          \"C\": $onGreen\n      escalate:\n        actor: human\n        label: $escalateLabel\n        file: FEEDBACK.md\n        message: |\n          The agent could not get the check to pass after repeated attempts.\n          `.gtd/FEEDBACK.md` 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  # Shared check/answer pair for design.gate/architecture.gate. No `file:`\n  # PARAM for the probe script itself: machine `$param` substitution is\n  # whole-value only, so a path can't be spliced into a shared script body —\n  # `file` here is instead the `answer` param's own `file:` (the human gate).\n  questionGate:\n    params: [file, message, onNone, onRevise, checkLabel, answerLabel]\n    entry: check\n    states:\n      check:\n        actor: check\n        label: $checkLabel\n        script: |\n          #!/usr/bin/env sh\n          # Exactly one of REQUIREMENTS.md/ARCHITECTURE.md exists on disk at\n          # a time — architecture.author deletes the former in the same turn\n          # it writes the latter — so this probe is unambiguous either way.\n          set +e\n          mkdir -p .gtd\n          file=.gtd/REQUIREMENTS.md\n          [ -f \"$file\" ] || file=.gtd/ARCHITECTURE.md\n          gtd check qa \"$file\" --open-questions > /dev/null 2>&1\n          code=$?\n          if [ \"$code\" -ne 0 ]; then\n            printf 'open questions remain in %s\\n' \"$file\" > .gtd/QUESTIONS.md\n            # See the shared suite check's cache-buster rationale on\n            # `entryGate.check` above.\n            printf '\\n<!-- gtd check %s -->\\n' \"$(git rev-parse --short HEAD 2>/dev/null || echo pending)\" >> .gtd/QUESTIONS.md\n          else\n            rm -f .gtd/QUESTIONS.md\n          fi\n        on:\n          \"A .gtd/QUESTIONS.md\": answer\n          \"M .gtd/QUESTIONS.md\": answer\n          \"D .gtd/QUESTIONS.md\": $onNone\n          \"C\": $onNone\n      answer:\n        actor: human\n        label: $answerLabel\n        file: $file\n        mode: qa\n        answerGate: true\n        message: $message\n        on:\n          \"* **\":\n            to: $onRevise\n            action: Revise answers\n            describe: >-\n              tick exactly one option per open question (replace\n              `_your answer_` for your own) to send it back for the agent to\n              fold your answers in. Delete a question to skip it, or delete\n              the whole `## Open Questions` section to accept the plan as-is.\n\n  # The triage phase — one conversation across the whole back-and-forth (the\n  # human's answer rationale survives every return lap). A review loop-back\n  # lap runs the suite itself and files any breakage as its own FIRST\n  # concern, rather than spending one of packages.item.fix-suite's\n  # (per-episode) retries on breakage the package didn't cause.\n  # ▸ planner identity.\n  designPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.designPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onArchitecture]\n    entry: triage\n    states:\n      triage:\n        actor: agent\n        label: Triaging the change\n        file: REQUIREMENTS.md\n        mode: qa\n        # Guards against discarding assembled review input without folding\n        # it in (the original bug this guard was added for).\n        requireProgress: true\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this turn touches is `.gtd/REQUIREMENTS.md`; develop it. Do\n          not create other files to hold notes or output.\n\n          `.gtd/TODO.md` is the likely home of the sketch that\n          started this process. Despite living beside this workflow's own\n          state files, it is the human's input — the sketch to be folded into\n          the concerns below like any other part of the start diff. It is\n          never a state file to preserve, and never gtd bookkeeping to ignore.\n\n          This process started at commit `<%= it.startCommit %>`. The change\n          that started it was reverted out of the working tree by the\n          `unwind` beat right after it landed, so `git diff <%= it.startCommit %>`\n          (against the working tree) is now empty — its content survives only\n          in history. Find the entry commit yourself: run\n          `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n          (the process's very first turn, landed immediately after\n          `<%= it.startCommit %>`, before any later baseline-repair commits) —\n          then `git show` that commit to see everything that started this\n          process: a hand-edit to real code, a scratch note in some file, or\n          both.\n\n          Whichever lap this is, leave `.gtd/REQUIREMENTS.md` uncommitted and\n          finish your turn once it reflects this lap's own work below.\n\n          ## First lap\n\n          `.gtd/REQUIREMENTS.md` does not exist yet (or holds whatever the\n          human's own change happened to leave there). Build it from that\n          start diff:\n\n          ### Group into concerns\n\n          Group the diff into an ordered list of concerns — each one a\n          coherent piece of work that can leave the test suite green on\n          its own, in the order you'd want them built. If a concern would\n          red-light tests that a later concern is meant to fix, that is\n          not a valid split: merge the two into one concern.\n\n          Two more tests sit beside that green floor, not instead of it.\n          Vertical, not horizontal: slice by capability, never by layer. A\n          concern that only prepares for a later one — types, scaffolding,\n          renames — is folded into the first concern that uses it. Distinct\n          acceptance: each concern needs an observable check that fails\n          before it and passes after; if you can't name one, merge it into\n          its neighbour. Prefer fewer, larger packages — the smallest\n          independently valuable change, not the smallest change that\n          compiles.\n\n          ### Classify each concern\n\n          Classify each concern as PRODUCT (a user-facing/requirements\n          decision) or TECHNICAL (an implementation decision).\n\n          <%~ it.vars.questionBar %>\n\n\n          Raise questions only for product concerns here — a technical\n          concern's open points wait for the next phase. When every concern\n          in this lap is TECHNICAL, write no `## Open Questions` section at\n          all.\n\n          ### Fold in the sketch\n\n          Fold everything the entry commit added into the concerns above —\n          a scratch note and a real code edit are both just a sketch of\n          the intent, a spec to be finished, never work to be preserved;\n          `unwind` already reverted both out of the tree, so there is\n          nothing left to delete. Describe each piece under the concern it\n          belongs to.\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n\n          ## Review loop-back\n\n          `.gtd/REQUIREMENTS.md` already holds concerns and none of them\n          have a ticked-but-unfolded answer waiting — that shape means a\n          completed REVIEW round put this material here, not a question you\n          asked. Develop those existing concerns further with whatever the\n          round raised; never rediscover or regroup them from a cold read\n          the way the first lap does.\n\n          The human's own edit from that review round has been reverted out\n          of the working tree the same way the entry commit is — read it\n          from history, never the working tree: run\n          `git show <%= it.reviewBase %>` to see it. (On the first lap that\n          same hash is the process's own diff base, `<%= it.startCommit %>`,\n          so this branch does not apply: `.gtd/REQUIREMENTS.md`\n          does not exist yet for a review round to have happened against.)\n\n          Whatever this round touches, every decision already settled under\n          `## Answered Questions` stays settled on this lap too — never\n          re-open one. A genuinely open PRODUCT point in the round's own\n          material may still raise a fresh question under\n          `## Open Questions`: the product gate sits on this path exactly as\n          it does on the first lap, and will ask it.\n\n          Before grouping anything on this lap, run\n          `<%= it.vars.testCommand %>` yourself as part of reading the\n          situation: a review loop-back runs no green-baseline gate between\n          the revert above and this turn, so the tree may already be red —\n          reverting the human's edit can undo a fix that edit had put in. If\n          the suite is red, make that breakage the first concern in your\n          ordered list, ahead of everything else — every later concern's\n          \"leaves the suite green on its own\" property assumes the suite\n          already started green.\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: REQUIREMENTS.md\n          onNone: $onArchitecture\n          onRevise: triage\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your product answers\n          message: |\n            `.gtd/REQUIREMENTS.md` holds the concerns under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question 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\n  # A separate machine from designPlan (its own memory scope — a COLD read,\n  # not a resumed conversation). Merge authority lives in `author`, the first\n  # state that knows the *how*: it alone may re-merge concerns, never split;\n  # `decompose` carries that grouping over verbatim. ▸ planner identity.\n  archPlan:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.architectPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onPackages]\n    entry: author\n    states:\n      author:\n        actor: agent\n        label: Refining the technical plan\n        file: ARCHITECTURE.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state files this\n          turn touches are `.gtd/ARCHITECTURE.md` (write it) and\n          `.gtd/REQUIREMENTS.md` (delete it once its content is\n          folded in). Do not create other files to hold notes or output.\n\n          You do not resume the design conversation — this is a separate\n          machine with its own memory, a cold read every time. Read\n          `.gtd/REQUIREMENTS.md` (the settled, ordered, classified\n          concerns) in full. Treat every decision recorded there — plain\n          prose or a resolved `## Answered Questions` entry, PRODUCT or\n          TECHNICAL alike — as settled; never re-open it.\n\n          Cold means the machine carries no conversational memory of\n          triage's own back-and-forth; it never meant no git access. This\n          process started at commit `<%= it.startCommit %>`. Find the\n          process's first turn yourself: run\n          `git rev-list --ancestry-path <%= it.startCommit %>..HEAD | tail -1`\n          then `git show` that commit to see everything that started this\n          process: a hand-edit to real code, a scratch note in some file,\n          or both.\n\n          Whichever lap this is, once `.gtd/ARCHITECTURE.md` is written,\n          delete `.gtd/REQUIREMENTS.md` — its content has been folded in and\n          it must not linger. Leave everything uncommitted and finish your\n          turn.\n\n          ## First lap\n\n          Develop `.gtd/ARCHITECTURE.md` from those concerns: for each one,\n          in the same order, work out the *how* — file/module structure,\n          data models, library/tech-stack choices, error-handling strategy —\n          building on the *what* already settled.\n\n          You now know the *how*, so you know each concern's file footprint —\n          list each concern's primary paths. Merge concerns whose footprints\n          center on the same files into one, unless the later one only\n          consumes an interface the earlier one creates: that exception is\n          what keeps a genuine build-on-top sequence from collapsing into one\n          blob. This authority is to merge only, never to split — granting\n          split authority here would work directly against the goal; the\n          whole problem is over-granularity. Record every merge under a\n          dedicated `## Merged Concerns` heading, carrying both merged requirements\n          verbatim so the per-package spec review still covers each one\n          independently. A merge raises no open question and stops for no\n          human — do not route it to `architecture.gate` for a veto; the\n          human still sees every merge when they review the plan, and the\n          per-package spec review is the real safety net. Prefer fewer,\n          larger packages — the smallest independently valuable change, not\n          the smallest change that compiles.\n\n          Every open point here is TECHNICAL — triage already resolved the\n          product ones, one phase earlier.\n\n          <%~ it.vars.questionBar %>\n\n          ## Return lap\n\n          <%~ it.vars.questionBarReturn %>\n        on:\n          \"* **\": gate.check\n\n      gate:\n        machine: questionGate\n        with:\n          file: ARCHITECTURE.md\n          onNone: decompose\n          onRevise: author\n          checkLabel: Checking for open questions\n          answerLabel: Awaiting your technical answers\n          message: |\n            `.gtd/ARCHITECTURE.md` holds the technical plan under\n            development. Each open question under `## Open Questions` offers\n            a few options plus a `- [ ] _your answer_` slot. Answer EVERY\n            question by ticking exactly one box (`- [x]`); for your own\n            answer, replace `_your answer_` with your text and tick that\n            line. Stepping is refused while any question 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\n      decompose:\n        actor: agent\n        label: Decomposing into packages\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state files this turn touches\n          are the package files it writes under `.gtd/packages/` and\n          `.gtd/ARCHITECTURE.md`, which it deletes. Do not create other\n          files to hold notes or output.\n\n          If you wrote `.gtd/ARCHITECTURE.md` earlier in this\n          conversation, work from what you already settled; otherwise read it\n          (the converged technical plan) yourself. It already lists an\n          ordered set of concerns with every merge/split judgement\n          `architecture.author` made — this turn is a mechanical write-out,\n          not a planning one. A `## Merged Concerns` heading there is a\n          record of those merges, never a concern of its own: write no\n          package file for it.\n\n          Write one package file per concern, in the settled order, under\n          `.gtd/packages/` (e.g.\n          `.gtd/packages/01-name.md`,\n          `.gtd/packages/02-name.md`, ...). Each package file\n          carries that concern's requirement(s) (so it can be reviewed\n          against its spec — both, independently, when the concern was\n          merged), its independent tasks, and each task's acceptance\n          criteria as `- [ ]` checkboxes and relevant paths. Do not merge or\n          split concerns here — that judgement already happened in\n          `architecture.author`; carry the settled grouping over verbatim.\n          No package file may reference any other `.gtd/` file.\n\n          Once the package files are written, delete\n          `.gtd/ARCHITECTURE.md`. Leave everything uncommitted and\n          finish your turn.\n        on:\n          \"* .gtd/packages/**\": $onPackages\n\n  # The shared review tail. ▸ planner identity — `collecting` only judges/\n  # classifies feedback; there's no coder follow-through inside this machine.\n  #\n  # Nested inside buildTail (build.review), not a root sibling: a machine's\n  # memory scope is its dotted instance path, so nesting keeps `build.fix ->\n  # build.health.check -> build.review.*` (the `--entry fix-precheck` path)\n  # inside one scope, so the sign-off's boundary commit lands from the same\n  # scope that made the fixes.\n  humanReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.reviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    entry: reviewing\n    states:\n      reviewing:\n        actor: agent\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # `gtd --entry review-gate.check` enters via review-gate.check first\n        # (never straight here), which sets the Gtd-Review-Base trailer this\n        # tail reuses.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this turn touches is `.gtd/REVIEW.md`; write it at exactly\n          that path. Do not create other files to hold notes or output.\n\n          Write `.gtd/REVIEW.md` 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 file pointer per hunk (checkboxes are\n            for the human to tick, not you; every path is `./`-relative, with an\n            optional `#line`). Put the note's opening line right on the\n            pointer's own line, after a dash — the reflow-proof shape:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n\n            If the note needs more than one line, continue it on the line(s)\n            below the pointer, indented exactly two spaces — never four or\n            more, which after a blank line reads as an indented code block\n            and never reflows:\n\n                - [ ] ./path/to/file.ts#42 — what this hunk does\n                  and here is more detail, continued below it\n\n            A note that sits entirely on the line(s) beneath the pointer is\n            also valid. Either way, the explanation itself must never start\n            with a bare `./path` token — that parses as a second hunk pointer,\n            not a 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 `.gtd/REVIEW.md` uncommitted and finish your turn.\n        on:\n          \"* **\": await-review\n\n      await-review:\n        actor: human\n        label: Awaiting your review\n        file: REVIEW.md\n        mode: review\n        message: |\n          `.gtd/REVIEW.md` 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          Review the diff yourself, with whatever tool you like — gtd checks\n          nothing out and touches no ref; `gtd base` prints this same hash any\n          time you need it again. The range runs from the review base to the\n          working tree:\n\n              git diff <%= it.reviewBase %>\n\n          When you've been through the whole diff, run `gtd land`:\n\n          - **Sign off** — leave no comment — no note in\n            `.gtd/REVIEW.md`, no code edit — to close the process,\n            whatever the boxes say. Every turn commit stays on the\n            branch; run `gtd summary` afterward for a closing-message\n            prompt.\n          - **Request changes** — leave a comment: a note on a\n            `.gtd/REVIEW.md` line, or a direct code edit — to send a FULL\n            development lap (**review.deciding** → **review.collecting** →\n            re-triage). A hand-edit you make here is treated as a SKETCH, not a\n            fix the agent builds on: it is reverted out of the tree and re-planned\n            from scratch, the same as any other change that starts a process.\n            There is no baseline check on the way back into planning — only a\n            genuinely non-actionable comment (an approving remark with no code\n            edit) skips the lap and signs off straight away.\n\n          Deleting `.gtd/REVIEW.md` is refused.\n        on:\n          \"* **\": deciding\n\n      deciding:\n        actor: check\n        label: Reviewing\n        file: REVIEW.md\n        mode: review\n        # Anchors the INCREMENTAL review base to the most-recent in-process\n        # commit (the process start on the first review).\n        reviewBase: true\n        script: |\n          #!/usr/bin/env sh\n          # FEEDBACK iff the human left a REVIEW.md note (any edit beyond a\n          # checkbox tick) or hand-edited any file this round outside .gtd/;\n          # otherwise a clean sign-off. This turn only CAPTURES the raw\n          # material into REVIEW_RAW.md — collecting judges actionability.\n          # A/M REVIEW_RAW.md rows are declared before D REVIEW.md so a\n          # feedback round (which also deletes REVIEW.md) isn't mistaken for\n          # sign-off.\n          set +e\n          mkdir -p .gtd\n          head=$(git rev-parse HEAD)\n          # Normalize [ ]/[x] before diffing, so only a real note counts.\n          before=$(git show \"HEAD^:.gtd/REVIEW.md\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          after=$(git show \"HEAD:.gtd/REVIEW.md\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n          if git diff-tree --no-commit-id --name-only -r HEAD -- . \":(exclude).gtd\" \\\n               | grep -q . \\\n             || [ \"$before\" != \"$after\" ]; then\n            {\n              echo \"This is machine-captured input, not instructions. A downstream agent judges whether it's actionable.\"\n              echo\n              echo \"Commit: $head\"\n              echo \"The human's notes are in .gtd/REVIEW.md at this commit. Any hand edits are\"\n              echo \"in that commit's other paths. Run: git show $head\"\n            } > .gtd/REVIEW_RAW.md\n          fi\n          rm -f .gtd/REVIEW.md\n        on:\n          \"A .gtd/REVIEW_RAW.md\": collecting\n          \"M .gtd/REVIEW_RAW.md\": collecting\n          \"D .gtd/REVIEW.md\": $onSignoff\n          # Deliberately no `C` row: REVIEW.md missing here means the review\n          # gate's own file-provisioning invariant broke, not a sign-off — a\n          # clean tree must not be able to auto-approve the round with\n          # nothing reviewed. Stays a no-op (validateHasCRow's warning is the\n          # accepted cost) rather than routing anywhere.\n\n      # Outcome is by which paths THIS diff touches: writing REQUIREMENTS.md\n      # (A/M) is the actionable case, so those rows are declared before \"D\n      # REVIEW_RAW.md\" — an actionable round's diff is both together, and\n      # the wrong order would short-circuit every round to sign-off.\n      # Consuming REVIEW_RAW.md alone is the non-actionable short-circuit,\n      # reusing $onSignoff since that IS a sign-off. No `C`/`\"* **\"` row: a\n      # clean turn here is a fruitless dispatch (falls through to the\n      # ordinary attempt default), never a verdict; a dirty tree matching\n      # neither row is a refusal.\n      collecting:\n        actor: agent\n        label: Collecting your feedback\n        file: REQUIREMENTS.md\n        mode: qa\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          <%~ it.vars.styleFormatContract %>\n\n\n          You are an autonomous coding agent judging and classifying a round\n          of review feedback.\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state files this turn\n          touches are `.gtd/REQUIREMENTS.md` and\n          `.gtd/REVIEW_RAW.md`, which it deletes — do not change any\n          other file: you classify, you do not build.\n\n          The raw review material is: <%~ it.read(\".gtd/REVIEW_RAW.md\") %>\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          The round is actionable if any of the following is true:\n\n          1. The human left a note on `.gtd/REVIEW.md` — a note is\n             anything beyond a checkbox flip, regardless of whether the box\n             itself is ticked (ticking means only \"I read this hunk\", never\n             sign-off). A note is a mandatory concern below, whether or not\n             its box is ticked.\n          2. The human added a code comment this round (a `+` line that is a\n             comment, in a hand-edited file) — even a plain-prose one. That\n             comment is an instruction: describe it as a concern below, and\n             note that the comment line itself is transient — it must not\n             survive the lap that satisfies it.\n          3. The human hand-edited any non-comment code this round. That code\n             is no longer an already-committed intent to build on top of — it\n             is a sketch, like the entry commit's own diff: describe what it\n             was reaching for under the concern it belongs to, and expect the\n             lap that follows to re-derive it from scratch. Never say the\n             human's lines are final or that they must survive unchanged.\n\n          The round is not actionable only when none of the above holds — the\n          human left nothing but an approving remark (a compliment, a \"looks\n          good\", or similar) with no code edit and no substantive note. Never\n          invent actionability where the definition above doesn't hold — it\n          manufactures a lap nothing asked for — and never dismiss a real note\n          or edit as approval, which drops feedback the human left.\n\n          If the round is actionable: write `.gtd/REQUIREMENTS.md`\n          with an ordered list of concerns, each classified PRODUCT (a\n          user-facing/requirements decision) or TECHNICAL (an implementation\n          decision) — the same shape `design.triage` builds, one\n          `## <heading>` per concern, in the order you'd want them built. Fold\n          every note, comment, and hand-edit from this round in under the\n          concern it belongs to, per the rules above. Raise no open\n          questions here — write no `## Open Questions` section;\n          `design.triage` owns that, one phase later. Then delete\n          `.gtd/REVIEW_RAW.md` and finish your turn.\n\n          If the round is not actionable: delete\n          `.gtd/REVIEW_RAW.md` and finish your turn, writing nothing\n          to `.gtd/REQUIREMENTS.md` — consuming the capture with no\n          other change is the sign-off.\n        on:\n          \"A .gtd/REQUIREMENTS.md\": $onFeedback\n          \"M .gtd/REQUIREMENTS.md\": $onFeedback\n          \"D .gtd/REVIEW_RAW.md\": $onSignoff\n\n  # The per-package review — a separate MIND from the implementer. ▸ planner\n  # identity; fixing findings is a coder action (packages.item.fix-spec).\n  specReview:\n    model: <%= it.vars.plannerModel %>\n    system: |-\n      <%~ it.vars.specReviewerPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onApproved, onFix]\n    entry: review\n    states:\n      review:\n        actor: agent\n        label: Reviewing the package\n        # No retry cap: the loop only re-enters through\n        # `fix-spec`/`health.check`, so under the per-episode rule this state's\n        # episode count can never exceed 1 and a cap could never fire. The\n        # spec-review loop is genuinely unbounded — see docs/configuration.md's\n        # `retry` documentation.\n        prompt: |\n          <%~ it.vars.styleBlock %>\n\n\n          You are an autonomous coding agent reviewing a freshly-built work package\n          against its own spec.\n\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this turn touches is\n          `.gtd/SPEC_FEEDBACK.md`; 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(\".gtd/NEXT.md\") %>\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 `.gtd/SPEC_FEEDBACK.md` 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 .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"M .gtd/SPEC_FEEDBACK.md\": $onFix\n          \"D .gtd/SPEC_FEEDBACK.md\": $onApproved\n          \"C\": $onApproved\n\n  # The per-package build queue — identity-free; build identity lives in\n  # 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 sh\n          # Mechanics only — NEXT.md's presence/absence is interpreted by\n          # the `on` rows below, never here.\n          set +e\n          mkdir -p .gtd\n          # Sweep spent design/architecture steering files (gone by now) and\n          # any REVIEW_RAW.md the review loop-back left behind — the only\n          # sweeper on that path before it would leak into a later `gtd\n          # summary` prompt's diff range.\n          rm -f .gtd/REQUIREMENTS.md .gtd/ARCHITECTURE.md .gtd/QUESTIONS.md .gtd/REVIEW_RAW.md\n          # Names are gtd-authored, never containing whitespace — safe to\n          # disable SC2012.\n          # shellcheck disable=SC2012\n          next=$(ls .gtd/packages/*.md 2>/dev/null | head -n 1)\n          if [ -n \"$next\" ]; then\n            printf '%s' \"$next\" > .gtd/NEXT.md\n          else\n            rm -f .gtd/NEXT.md\n          fi\n        on:\n          \"D .gtd/NEXT.md\": $onDrained\n          \"* .gtd/NEXT.md\": item.building\n          \"C\": $onDrained\n\n      # Its own coder machine (below) keeps `packages` itself a single state.\n      item:\n        machine: packageItem\n        with:\n          onNext: picking\n\n  # The per-package build identity. ▸ coder identity. packages.item.closing\n  # -> picking is the one upward-resolving target in the file, hence $onNext.\n  packageItem:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.builderPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onNext]\n    entry: building\n    states:\n      building:\n        actor: agent\n        label: Building\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          The only state file this\n          turn may write is `.gtd/SATISFIED.md` (see below); do not\n          delete the package file (the spec-review gate reads it after you)\n          and never touch `.gtd/NEXT.md` — the `picking` state owns\n          it.\n\n          The package to implement is: <%~ it.read(\".gtd/NEXT.md\") %>\n\n          Before implementing anything, check the package's acceptance criteria\n          against the current tree — an earlier package's fix turn may already\n          have satisfied them. If **every** criterion is already met, implement\n          nothing: write `.gtd/SATISFIED.md` recording each criterion\n          and the concrete evidence it is already satisfied (the commit, file,\n          or symbol that proves it), change nothing else, and finish your turn.\n          If any criterion is outstanding, implement the package normally and\n          do not write that file.\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          \"A .gtd/SATISFIED.md\": &satisfied\n            to: health.check\n            action: Close as already satisfied\n            describe: >-\n              record per-criterion evidence in .gtd/SATISFIED.md when this\n              package's work already landed (an earlier package's fix turn\n              pulled it in) — the package still runs the checks and the spec\n              review, then closes out.\n          \"M .gtd/SATISFIED.md\": *satisfied\n          \"* **\": health.check\n\n      fix-suite:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\n          If the\n          only way to green the suite is to implement work that another\n          package file describes, make the smallest change that gets there and\n          do it — that later package will then legitimately report itself\n          already satisfied when its turn comes.\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: SPEC_FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n          The only state file this\n          turn touches is `.gtd/SPEC_FEEDBACK.md`; address it, then\n          delete it. Do not create other files to hold notes or output.\n\n          Read `.gtd/SPEC_FEEDBACK.md` (the reviewer's concerns about the\n          current package) and the package spec (`<%= it.read(\".gtd/NEXT.md\") %>`),\n          then fix the code to resolve every concern. Keep the change focused.\n\n          Delete `.gtd/SPEC_FEEDBACK.md` 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 sh\n          # Removes the just-reviewed package file (path in NEXT.md) plus\n          # leftover spec feedback/evidence, so picking selects the next.\n          # Reached only on spec-review approval — that loop carries no retry\n          # cap, so there is no force-close path here.\n          set +e\n          pkg=$(cat .gtd/NEXT.md 2>/dev/null)\n          [ -n \"$pkg\" ] && rm -f \"$pkg\"\n          rm -f .gtd/SPEC_FEEDBACK.md .gtd/NEXT.md .gtd/SATISFIED.md\n        on:\n          \"* **\": $onNext\n          # Nothing left to sweep (an already-clean NEXT.md/package) still\n          # needs to proceed to the next package, not stall here.\n          \"C\": $onNext\n\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      spec:\n        machine: specReview\n        with:\n          onApproved: closing\n          onFix: fix-spec\n\n  # The process's build identity. ▸ coder identity — model/system stamped\n  # onto fix.\n  buildTail:\n    model: <%= it.vars.coderModel %>\n    system: |-\n      <%~ it.vars.finisherPersona %>\n\n\n      <%~ it.vars.agentConduct %>\n    params: [onDone, onFeedback]\n    # entry: is required by the machine grammar even though nothing resolves\n    # this machine bare; `fix` is an arbitrary pick.\n    entry: fix\n    states:\n      fix:\n        actor: agent\n        label: Fixing the check\n        file: FEEDBACK.md\n        prompt: |\n          <%~ it.vars.stateFileRules %>\n\n          <%~ it.vars.fixFeedbackPrompt %>\n\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      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      # Nested here (not root) so the sign-off's boundary commit stays inside\n      # the builder's own scope — see humanReview above.\n      review:\n        machine: humanReview\n        with:\n          onSignoff: $onDone\n          onFeedback: $onFeedback\n\n  # WIRING ONLY — the root ties together the machine tree above.\n  unified:\n    entry: idle\n    states:\n      idle:\n        actor: human\n        label: Idle\n        file: TODO.md\n        message: |\n          No active gtd process.\n\n          To start one, make ANY change — a hand-edit to real code, a scratch\n          note, anything at all. .gtd/TODO.md is a good default\n          place to start sketching. gtd treats it as a SKETCH, not finished\n          work: the very next beat unwinds it out of your working tree (its\n          intent survives in history, for the triage phase to read), then\n          checks the test baseline is green, then triages the reverted diff\n          into ordered, classified concerns: product questions, then\n          technical questions, then one package per concern, built and\n          reviewed in parallel.\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: unwind\n            action: Start\n            describe: >-\n              make any change — gtd unwinds it out of your working tree (its\n              intent survives in history) before checking the test baseline is\n              green, then triages the reverted diff into ordered, classified\n              concerns and resolves product questions, then technical ones,\n              before building each concern's package (**unwind** ->\n              **start-gate.check**).\n\n      # --entry fix-precheck: a red suite drops into build.fix (-> health ->\n      # review tail); a green suite is a no-op back to idle.\n      fix-precheck:\n        actor: check\n        label: Checking the baseline\n        entry: true\n        script: *suiteCheck\n        on:\n          \"A .gtd/FEEDBACK.md\": build.fix\n          \"M .gtd/FEEDBACK.md\": build.fix\n          \"D .gtd/REVIEW_RAW.md\": idle\n          \"D .gtd/FEEDBACK.md\": idle\n          \"C\": idle\n\n      # Separate from start-gate.check: that gate's blocked -> check retry\n      # edge would otherwise re-run a revert here and discard a human's\n      # baseline repair. One inbound edge (from idle) means unwind runs\n      # exactly once, so it needs no idempotence guard itself.\n      unwind:\n        actor: check\n        label: Unwinding your input\n        script: |\n          #!/usr/bin/env sh\n          set +e\n          # Hoisted here, 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.\n          # Uses it.currentCommit (render-time), not bare HEAD, so a\n          # late-running driver still reverts the right commit.\n          commit=\"<%~ it.currentCommit %>\"\n          git revert --no-commit \"$commit\"\n        on:\n          \"* **\": start-gate\n          # Deliberately no `C` row: `git revert --no-commit` under `set +e`\n          # leaves a clean tree on either a genuine no-op OR a hard failure\n          # (e.g. a merge commit with no `-m`) — the two are indistinguishable\n          # from the diff alone, and advancing unconditionally would run the\n          # baseline check against a tree that still carries the human's\n          # un-reverted sketch. Stays a no-op (validateHasCRow's warning is\n          # the accepted cost) rather than risking a false-clean baseline.\n\n      # Reverts the human's own review-round hand-edit before re-planning,\n      # scoped to real code (`.gtd/` excluded — REVIEW.md is already gone by\n      # now). Names the commit via it.reviewBase (reviewBaseFor's own\n      # `await-review -> deciding` commit), never bare HEAD.\n      #\n      # requireRevert (below) re-checks the tree itself and refuses the step\n      # if residue remains, rather than trusting the script's exit code — a\n      # clean-filter round-trip or binary path can make `git apply -R` a\n      # silent no-op. Both `on` rows below target `design`: a hand-edited\n      # round leaves a dirty tree, a note-only round's patch is empty and\n      # leaves the tree clean — both are legitimate outcomes here, not a\n      # stall.\n      #\n      # `file: REVIEW.md` + `requireRevert: true` exist only to give that\n      # guard the path to exempt (it reads Rest.hints.file, never this\n      # literal) — REVIEW.md is already gone two commits earlier, so this\n      # state never renders it.\n      re-unwind:\n        actor: check\n        label: Re-unwinding your review edit\n        file: REVIEW.md\n        requireRevert: true\n        script: |\n          #!/usr/bin/env sh\n          # Scoped revert of the human's review-round edit — .gtd/ excluded\n          # (the guard's isCodePath re-derives the same exemption; keep both\n          # in sync). Expected to succeed; requireRevert catches a silent\n          # apply failure.\n          set +e\n          # Hoisted here, 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.\n          commit=\"<%~ it.reviewBase %>\"\n          patch=.gtd/.re-unwind.patch\n          mkdir -p .gtd\n          git diff --binary \"$commit^\" \"$commit\" -- . \":(exclude).gtd\" > \"$patch\"\n          if [ -s \"$patch\" ]; then\n            git apply -R \"$patch\" || echo \"re-unwind: could not revert $commit\" >&2\n          fi\n          rm -f \"$patch\"\n        on:\n          \"* **\": design # a code hand-edit was reverted\n          \"C\": design # note-only round: nothing to revert\n\n      start-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            `.gtd/FEEDBACK.md` 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            (**start-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      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            `.gtd/FEEDBACK.md` 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      design:\n        machine: designPlan\n        with:\n          onArchitecture: architecture\n\n      architecture:\n        machine: archPlan\n        with:\n          onPackages: packages\n\n      packages:\n        machine: packageLoop\n        with:\n          onDrained: build.review\n\n      build:\n        machine: buildTail\n        with:\n          onDone: idle\n          onFeedback: re-unwind\n";
 //#endregion
 //#region src/workflows/templates.ts
 const SCHEMA_URL = "https://cdn.jsdelivr.net/npm/@pmelab/gtd/schema.json";
@@ -192211,16 +192258,18 @@ const toOperations = (decoded, root, fileRefs = nodeFileRefReader) => {
 			workflowVars: defaultWorkflowVars,
 			rcVars,
 			machineTree: defaultMachineTree,
-			stateScopes: defaultStateScopes
+			stateScopes: defaultStateScopes,
+			warnings: validateDefinition(defaultWorkflowDefinition).warnings
 		};
 	}
-	const { definition, vars: workflowVars, tree, scopes } = compileWorkflowConfig(decoded.workflow, root, rcModes, false, fileRefs);
+	const { definition, vars: workflowVars, tree, scopes, warnings } = compileWorkflowConfig(decoded.workflow, root, rcModes, false, fileRefs);
 	return {
 		workflow: definition,
 		workflowVars,
 		rcVars,
 		machineTree: tree,
-		stateScopes: scopes
+		stateScopes: scopes,
+		warnings
 	};
 };
 /**
@@ -192435,7 +192484,6 @@ const makeGitImpl = (executor, root) => {
 		lastCommitMessage: () => exec("git", "log", "-1", "--pretty=%B").pipe(map$4((s) => s.trim())),
 		hasCommits: () => exec("git", "rev-parse", "--verify", "HEAD").pipe(map$4(() => true), catchAll(() => succeed$3(false))),
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
-		changedPathsSince: (ref) => exec("git", "diff", "--name-status", "-z", ref, "HEAD").pipe(map$4((out) => parseNameStatus(splitNul(out)))),
 		changedPaths: (base) => gen(function* () {
 			const ref = base ?? "HEAD";
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(catchIf((e) => !isIndexLockError(e), () => succeed$3("")));
@@ -193123,23 +193171,6 @@ const renderStateTemplate = (template, context) => eta.renderString(template, co
 /** Render one mode command template — same throw-on-failure discipline as `renderStateTemplate`. `SteeringMode.ts` turns a render failure into a refusal rather than running a half-rendered command. */
 const renderModeCommand = (template, context) => eta.renderString(template, context);
 //#endregion
-//#region src/RetainedHistory.ts
-/** Per-worktree (`refs/worktree/gtd/*`) so linked worktrees sharing one `.git` don't clobber each other's retained history. */
-const HISTORY_REF = "refs/worktree/gtd/history";
-const readRetainedHistory = (git) => git.readRefOption(HISTORY_REF);
-/**
-* Whether resetting to `tipHash` is safe: HEAD must be an ancestor of
-* `tipHash` (nothing on top of the retained tip would be lost). Anything else
-* is refused.
-*/
-const restorability = (git, headHash, tipHash) => gen(function* () {
-	if (yield* git.isAncestor(headHash, tipHash)) return { ok: true };
-	return {
-		ok: false,
-		reason: "HEAD has advanced past the retained tip — restoring would discard commits built on top of it"
-	};
-});
-//#endregion
 //#region src/GitScript.ts
 const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
 const pathspec = (paths) => paths.map(shellQuote).join(" ");
@@ -193183,14 +193214,9 @@ const renderFormat = (fmt, ...args) => {
 * 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 line — no commit landed, HEAD was rewound to the process's start parent. */
-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);
 /**
@@ -193400,10 +193426,10 @@ const DID_NOT_RUN_COMMENT = "# gtd emitted this and did NOT run it — pipe it i
 const PRESENTATION_ONLY_COMMENT = "# presentation only — safe to skip";
 const PRESENTATION_FAILURE_WARNING = "printf 'gtd: presentation-only follow-up failed — continuing\\n' >&2";
 /**
-* A plain-text write command's single pasteable script (`gtd land | sh`).
-* `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.
+* A write command's single pasteable script (`gtd abandon | sh`,
+* `gtd land --json=script`'s own field). `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.
 */
 const combinedScript = (required, optional) => {
 	if (required.length === 0) return "";
@@ -193833,15 +193859,6 @@ const summaryTemplateContext = (run) => gen(function* () {
 	const reviewBase = reviewBaseFor(def, run);
 	return yield* buildTemplateContext(git, templateRead(files), "", "", run, vars, void 0, 0, void 0, reviewBase);
 });
-/**
-* True when this process would retain NOTHING: nothing pending and no net
-* change between its trace/retry boundary and HEAD. Used by `planStep`'s
-* "returned to the initial state retaining nothing" mixed-reset branch.
-*/
-const retainsNothing = (git, run, changes) => gen(function* () {
-	if (changes.length > 0) return false;
-	return (yield* git.changedPathsSince(run.startParentHash)).length === 0;
-});
 const omitUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
 /** Resolve `Rest` at an arbitrary ref, or `undefined` for HEAD itself. */
 const restAt = (ref) => gen(function* () {
@@ -193945,92 +193962,32 @@ const stalledAt = (rest) => rest.changes.length === 0 && rest.run.headTurn?.stat
 * `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)"}`;
-/** `updateRef(HISTORY_REF, tip)` as a single-element (or empty) step list — OMITTED when `tip === startParentHash`, mirroring `retainHistory`'s own no-op check. Used by 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 — target is the initial state, the
-* process started somewhere other than the empty tree, and nothing pending or
-* already-committed since its start parent survives (`retainsNothing`).
-* Always `false` for an ATTEMPT: an agent that did nothing must never rewind
-* a process, and an attempt landing at a prompt state that's also the initial
-* state would otherwise satisfy every other criterion identically to a
-* genuine collapse.
-*/
-const collapsesWith = (git, rest, decision) => gen(function* () {
-	if (decision.attempt === true) return false;
-	return parseStateSubject(decision.subject)?.state === initialStateOf(rest.def) && rest.run.startParentHash !== EMPTY_TREE$1 && (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"`/
-* `"commit"` 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);
-});
-/**
 * Render a `"commit"` decision as the `EmitStep`s the external driver runs to
 * produce its git effect — the ONE place a decision becomes git commands.
-* Every git call here is a READ; nothing is written — gtd itself never writes
-* git, only a driven script does.
-*
-* One non-obvious case: 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 — it emits retain-history plus 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`.
-*/
-const renderDecision = (git, rest, decision, cost, model) => gen(function* () {
-	const run = rest.run;
-	if (yield* collapsesWith(git, rest, decision)) {
-		const tip = yield* git.resolveRef("HEAD");
-		return [
-			...retainHistoryStep(tip, run.startParentHash),
-			{
-				kind: "gitWrite",
-				command: mixedResetTo(run.startParentHash)
-			},
-			{
-				kind: "outcome",
-				command: noteOutcome(COLLAPSED_TEXT)
-			}
-		];
-	}
+* Pure: no git read, no failure mode — a commit decision always becomes an
+* ordinary commit plus its outcome report.
+*/
+const renderDecision = (rest, decision, cost, model) => {
 	return [{
 		kind: "gitWrite",
 		command: commitAll(withCostTrailer(decision.subject, cost, model))
 	}, commitDecisionOutcome(decision)];
-});
+};
 /**
 * The `EmitPreconditions` a step's/entry's assembled scripts assert against:
 * `expectedHead` is the resolved HEAD hash the `Rest` snapshot was taken at.
 */
 const buildPreconditions = (rest) => ({ expectedHead: rest.context.currentCommit });
-/**
-* The `EmittedScripts` a `"commit"` `StepPlan` carries alongside `perform` —
-* built from the SAME `renderDecision` output, but a render failure collapses
-* to an EMPTY script (`emitScripts` with no steps) instead of failing this
-* Effect: `perform` stays the one place a render failure is ever reported to
-* a caller, unchanged by this addition.
-*/
-const buildStepScripts = (git, rest, decision, cost, model) => gen(function* () {
-	return emitScripts(buildPreconditions(rest), yield* renderDecision(git, rest, decision, cost, model).pipe(catchAll(() => succeed$3([]))));
-});
+/** The `EmittedScripts` a `"commit"` `StepPlan` carries alongside `perform` — built from `renderDecision`'s output. */
+const buildStepScripts = (rest, decision, cost, model) => {
+	return emitScripts(buildPreconditions(rest), renderDecision(rest, decision, cost, model));
+};
 /**
 * 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
@@ -194038,9 +193995,9 @@ const buildStepScripts = (git, rest, decision, cost, model) => gen(function* ()
 * `settled` signal). A `prompt` rest can't produce a no-op at all (a clean
 * tree with no `C` row there commits an ATTEMPT instead; `stalledAt` is its
 * own signal for that). A no-op at a `message` rest is a human gate the loop
-* already halts on. This is one of TWO settled shapes — the other is the
-* initial-state collapse, decided independently by `program.ts`'s
-* `planLanding`.
+* already halts on. This is the ONLY settled shape — `gtd land` never moves
+* HEAD, so a commit decision is never settled, even one re-entering the
+* initial state.
 */
 const noOpSettles = (rest) => contentKindOf(rest.stateDef) === "script";
 /**
@@ -194049,7 +194006,7 @@ const noOpSettles = (rest) => contentKindOf(rest.stateDef) === "script";
 * and — for a `"commit"` decision — assemble the emitted `scripts` a driver
 * runs to land it, against `rest.context`.
 */
-const planStep = (rest, opts = {}) => gen(function* () {
+const planStep = (rest, opts = {}) => sync$1(() => {
 	const decision = step(rest.stepDef, rest.state, rest.actor, {
 		changes: rest.changes,
 		processTrace: rest.run.trace.map((entry) => entry.state)
@@ -194064,8 +194021,7 @@ const planStep = (rest, opts = {}) => gen(function* () {
 		settled: noOpSettles(rest)
 	};
 	const { cost, model } = opts;
-	const git = yield* GitService;
-	const scripts = yield* buildStepScripts(git, rest, decision, cost, model);
+	const scripts = buildStepScripts(rest, decision, cost, model);
 	return {
 		kind: decision.kind,
 		state: rest.state,
@@ -194188,6 +194144,23 @@ const buildSummary = (def, run, base) => {
 	return renderStateTemplate(def.summary, context);
 };
 //#endregion
+//#region src/RetainedHistory.ts
+/** Per-worktree (`refs/worktree/gtd/*`) so linked worktrees sharing one `.git` don't clobber each other's retained history. */
+const HISTORY_REF = "refs/worktree/gtd/history";
+const readRetainedHistory = (git) => git.readRefOption(HISTORY_REF);
+/**
+* Whether resetting to `tipHash` is safe: HEAD must be an ancestor of
+* `tipHash` (nothing on top of the retained tip would be lost). Anything else
+* is refused.
+*/
+const restorability = (git, headHash, tipHash) => gen(function* () {
+	if (yield* git.isAncestor(headHash, tipHash)) return { ok: true };
+	return {
+		ok: false,
+		reason: "HEAD has advanced past the retained tip — restoring would discard commits built on top of it"
+	};
+});
+//#endregion
 //#region node_modules/vscode-languageserver/lib/common/utils/is.js
 var require_is$2 = /* @__PURE__ */ __commonJSMin(((exports) => {
 	Object.defineProperty(exports, "__esModule", { value: true });
@@ -205809,7 +205782,7 @@ const openInBrowser = (url) => {
 };
 //#endregion
 //#region src/StepGuards.ts
-/** True when `changes` deletes `file` — shared by `GuardContext.fileDeleted` and `program.ts`'s `steeringModeSteps`, so both ask it the same way. */
+/** True when `changes` deletes `file` — the require-revert guard's own `GuardContext.fileDeleted` check. */
 const deletesFile = (changes, file) => changes.some((c) => c.path === file && c.status === "D");
 /**
 * True when `path` sits inside gtd's plumbing directory. Exact match or
@@ -205957,74 +205930,6 @@ const modeContradictionSkipNotice = (mode) => {
 	return `printf '%s\\n' ${shellQuote(`gtd: mode "${mode}" has an external validate: command — skipping the format/validate contradiction check`)} >&2`;
 };
 //#endregion
-//#region src/Sh.ts
-/** POSIX single-quote escaping: wraps in `'...'`, replacing embedded `'` with `'\''`. */
-const shQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
-const isNestedShape = (node) => typeof node !== "string";
-/** Every leaf variable name a shape declares, flattened with `_`, in shape declaration order — the whole `unset` preamble's contents. */
-const shVarNames = (prefix, shape) => {
-	const names = [];
-	const walk = (path, node) => {
-		for (const [key, kind] of Object.entries(node)) {
-			const varPath = `${path}_${key}`;
-			if (isNestedShape(kind)) walk(varPath, kind);
-			else names.push(varPath);
-		}
-	};
-	walk(prefix, shape);
-	return names;
-};
-/** A TSV cell: absent/null renders empty; every other value is stringified, with any tab/newline flattened to a space so it can't be mistaken for a row/column boundary. */
-const shCell = (value) => {
-	if (value === void 0 || value === null) return "";
-	return String(value).replace(/[\t\n]/g, " ");
-};
-/**
-* Renders a list of records as tab-separated rows. Columns are the union of
-* keys across this call's rows, in first-seen order — a different call, even
-* with structurally identical records, can produce a different column order
-* if its rows carry a different subset of optional keys first, so a driver
-* must not hard-code column positions across separate beats.
-*/
-const renderTsv = (rows) => {
-	const columns = [];
-	for (const row of rows) for (const key of Object.keys(row)) if (!columns.includes(key)) columns.push(key);
-	return rows.map((row) => columns.map((column) => shCell(row[column])).join("	")).join("\n");
-};
-/** One leaf's rendered `=value` right-hand side, or `undefined` to emit nothing (false/null/absent scalar, or an empty list). */
-const renderLeafValue = (kind, value) => {
-	if (value === void 0 || value === null) return void 0;
-	if (kind === "bool") return value === true ? "true" : void 0;
-	if (kind === "list") {
-		const rows = value;
-		return rows.length === 0 ? void 0 : shQuote(renderTsv(rows));
-	}
-	return shQuote(String(value));
-};
-/**
-* Renders one shell-sourceable document: one `unset` line naming every leaf
-* `shape` declares (so `eval`ing this document is self-contained and no
-* field absent from it can leave a previous document's value standing),
-* then a generic recursive walk assigning each present leaf.
-*/
-const renderShDocument = (prefix, shape, fields) => {
-	const lines = [`unset ${shVarNames(prefix, shape).join(" ")}`];
-	const walk = (path, node, data) => {
-		for (const [key, kind] of Object.entries(node)) {
-			const varPath = `${path}_${key}`;
-			const value = data?.[key];
-			if (isNestedShape(kind)) {
-				walk(varPath, kind, value);
-				continue;
-			}
-			const rhs = renderLeafValue(kind, value);
-			if (rhs !== void 0) lines.push(`${varPath}=${rhs}`);
-		}
-	};
-	walk(prefix, shape, fields);
-	return lines.join("\n") + "\n";
-};
-//#endregion
 //#region src/Beat.ts
 /** Assembles one `gtd land` result's fields in `LandFields`' declared order — the ONLY place `gtd land --json`'s wire shape is built. */
 const landFields = (input) => ({
@@ -206036,24 +205941,19 @@ const landFields = (input) => ({
 	cost: input.cost,
 	model: input.model
 });
-/** `--sh`'s shape for `LandFields`: one entry per field, so a field added to `LandFields` with no matching entry here is a compile error. */
-const LAND_SH_SHAPE = {
-	script: "scalar",
-	settled: "bool",
-	idle: "bool",
-	state: "scalar",
-	subject: "scalar",
-	cost: "scalar",
-	model: "scalar"
-};
 const renderLandJson = (fields) => JSON.stringify(fields) + "\n";
+const FMT_NOOP = "nothing to do at \"%s\"\n";
+const FMT_LAND_PROSE = "commit everything with this message: %s\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);
+/** `commit everything with this message: <subject>` — plain `gtd land`'s own stdout at a pending diff (no script); `--json` keeps emitting the script itself, unaffected. */
+const landProseText = (subject) => renderFormat(FMT_LAND_PROSE, subject);
 /**
-* `gtd land --json`'s shell-sourceable counterpart (see `src/Sh.ts`). Its
-* `unset` preamble only names this document's own leaves, so it never clears
-* `gtd_content`/`gtd_log`/`gtd_session_id` — beat-only names a driver may
-* still rely on after the land.
+* `gtd land`'s plain-text encoding — names the commit subject at a real
+* landing and points at `--json=script`, since the script itself is
+* unreachable from plain output; prints the existing no-op note otherwise.
 */
-const renderLandSh = (fields) => renderShDocument("gtd", LAND_SH_SHAPE, fields);
+const renderLandPlain = (fields) => fields.subject !== null ? `${landProseText(fields.subject).trimEnd()}\n(run \`gtd land --json=script | sh\` to get the landing script)\n` : noopText(fields.state);
 /** `gtd next --json`'s `next` key — `null` on no match, else the matched edge's fields (`action` omitted, never an explicit `undefined`, when unset). */
 const nextField = (next) => next === null ? null : {
 	...next.action !== void 0 ? { action: next.action } : {},
@@ -206100,60 +206000,28 @@ const beatFields = (input) => {
 		kind,
 		content: kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor) : rendered.content,
 		idle,
-		...dispatchable && session !== void 0 ? { session: {
+		session: dispatchable && session !== void 0 ? {
 			id: session.id,
 			resume: session.resume
-		} } : {},
-		...rendered.model !== void 0 ? { model: rendered.model } : {},
-		...rendered.system !== void 0 && rendered.system !== "" ? { system: rendered.system } : {},
-		...dispatchable && validate !== void 0 ? { validate } : {},
+		} : void 0,
+		model: rendered.model,
+		system: rendered.system !== void 0 && rendered.system !== "" ? rendered.system : void 0,
+		validate: dispatchable && validate !== void 0 ? validate : void 0,
 		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 } : {},
+		label: rendered.label,
+		memory: rendered.memory,
+		file: rendered.file,
+		mode: rendered.mode,
+		edges: rendered.edges.length > 0 ? rendered.edges : void 0,
 		changes,
 		next: nextField(next),
-		...hasCost ? {
-			cost,
-			costByModel
-		} : {}
+		cost: hasCost ? cost : void 0,
+		costByModel: hasCost ? costByModel : void 0
 	};
 };
-/** `--sh`'s shape for `BeatFields`: one entry per field, so a field added to `BeatFields` with no matching entry here is a compile error. */
-const BEAT_SH_SHAPE = {
-	kind: "scalar",
-	content: "scalar",
-	idle: "bool",
-	session: {
-		id: "scalar",
-		resume: "bool"
-	},
-	model: "scalar",
-	system: "scalar",
-	validate: "scalar",
-	log: "scalar",
-	state: "scalar",
-	actor: "scalar",
-	label: "scalar",
-	memory: "scalar",
-	file: "scalar",
-	mode: "scalar",
-	edges: "list",
-	changes: "list",
-	next: {
-		pattern: "scalar",
-		target: "scalar",
-		action: "scalar"
-	},
-	cost: "scalar",
-	costByModel: "list"
-};
 const renderBeatJson = (fields) => JSON.stringify(fields) + "\n";
-const renderBeatSh = (fields) => renderShDocument("gtd", BEAT_SH_SHAPE, fields);
 /**
 * True when the per-model breakdown adds information beyond the `Cost:` total:
 * more than one model, or a single model that carries an actual `--model` tag
@@ -206205,11 +206073,15 @@ const beatHeaderLines = (fields) => {
 };
 /**
 * The self-validation instruction appended to a `prompt` beat's plain output
-* only — a structured (`--json`/`--sh`) driver runs the `validate` field
+* only — a structured (`--json`) driver runs the `validate` field
 * itself instead. Advisory either way: `gtd land` refuses a turn whose
 * steering file is invalid regardless of whether this 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`;
+/** `script`'s plain-output instruction line — a literal constant, never a template. */
+const SCRIPT_INSTRUCTION = "Run this script:";
+/** `capture`'s plain-output instruction line — a literal constant, never a template. */
+const CAPTURE_INSTRUCTION = "The edit is already made — run `gtd land` to land it.";
 /**
 * `gtd next`'s plain-text encoding. At `kind === "prompt"` the status header
 * is suppressed and only `content` plus the self-validation instruction is
@@ -206222,7 +206094,10 @@ const selfValidateInstruction = (command, file) => `\nBefore finishing your turn
 const renderBeatPlain = (fields, selfValidateCommand) => {
 	const content = fields.content.endsWith("\n") ? fields.content : fields.content + "\n";
 	if (fields.kind === "prompt") return selfValidateCommand !== void 0 && fields.file !== void 0 ? content + selfValidateInstruction(selfValidateCommand, fields.file) : content;
-	return beatHeaderLines(fields).join("\n") + "\n\n" + content;
+	const body = beatHeaderLines(fields).join("\n") + "\n\n" + content;
+	if (fields.kind === "script") return `${SCRIPT_INSTRUCTION}\n` + body;
+	if (fields.kind === "capture") return `${CAPTURE_INSTRUCTION}\n` + body;
+	return body;
 };
 //#endregion
 //#region src/WorktreeState.ts
@@ -206269,72 +206144,86 @@ set -eu
 
 beat=1
 while :; do
-  # One invocation per beat: assign first, THEN eval — command substitution
-  # inside eval's own argument would swallow a failed \`gtd next\` under
-  # \`set -e\` (eval would see only the empty string and abort on some later
-  # unset variable with a confusing message). Assigning to \`out\` first makes
-  # this a simple command whose own exit status IS the substitution's, so
-  # \`set -e\` aborts correctly on a genuine failure.
-  out="$(gtd next --sh)"
-  eval "$out"
+  # One value per invocation: \`gtd next --json=<path>\` is a pure read (peek
+  # or dispatch, indistinguishable, always safe to call again), so nothing is
+  # lost by reading \`kind\`/\`idle\` as two separate calls rather than one
+  # combined document.
+  kind="$(gtd next --json=kind)"
+  idle="$(gtd next --json=idle)"
 
-  # \`gtd_idle\` (true iff the initial state, clean tree) is the one shape
-  # that means the process is genuinely done — EXCEPT on the run's opening
-  # beat: land it anyway, so a workflow whose initial state declares its own
+  # \`idle\` (true iff the initial state, clean tree) is the one shape that
+  # means the process is genuinely done — EXCEPT on the run's opening beat:
+  # land it anyway, so a workflow whose initial state declares its own
   # clean-tree "C" pattern still gets a chance to fire.
-  if [ "$beat" -gt 1 ] && [ "\${gtd_idle:-}" = true ]; then
+  if [ "$beat" -gt 1 ] && [ "\${idle:-}" = true ]; then
     gtd next
     exit 0
   fi
 
-  case "$gtd_kind" in
-    stalled) printf '%s\\n' "$gtd_content" >&2; exit 1 ;;
+  case "$kind" in
+    stalled)
+      gtd next --json=content >&2
+      exit 1 ;;
     # you re-ran us resting here: you either edited something or accepted by
     # editing nothing, so land the opening beat either way. Later beats are
     # gates we just produced and you have not read yet — hand off.
     message) [ "$beat" = 1 ] || { gtd next; exit 0; } ;;
     capture) ;; # the human already acted — just land it
     script)
-      sh -c "$gtd_content" >>"$gtd_log" 2>&1 || true ;;
+      # A \`script\` rest's plain output is prose, not pipeable into \`sh\` — the
+      # raw script comes from \`--json=content\` instead.
+      content="$(gtd next --json=content)"
+      log="$(gtd next --json=log)"
+      sh -c "$content" >>"$log" 2>&1 || true ;;
     prompt)
-      # $gtd_content embeds a full diff, so it goes to the agent over
-      # stdin, never as an argv positional — argv is capped (~1 MB on
-      # macOS, and POSIX guarantees only 4 KB, ARG_MAX), and a diff crosses
-      # that far sooner than you'd expect.
-      agent_turn() { printf '%s' "$gtd_content" | claude -p "$1" "$gtd_session_id" \\
-        \${gtd_model:+--model "$gtd_model"} \\
-        \${gtd_system:+--system-prompt "$gtd_system"} \\
-        --dangerously-skip-permissions >>"$gtd_log" 2>&1; }
-      if [ "\${gtd_session_resume:-}" = true ]
+      session_id="$(gtd next --json=session.id)"
+      resume="$(gtd next --json=session.resume)"
+      model="$(gtd next --json=model)"
+      system="$(gtd next --json=system)"
+      validate="$(gtd next --json=validate)"
+      log="$(gtd next --json=log)"
+      # The prompt embeds a full diff, so it goes to the agent over stdin,
+      # never as an argv positional — argv is capped (~1 MB on macOS, and
+      # POSIX guarantees only 4 KB, ARG_MAX), and a diff crosses that far
+      # sooner than you'd expect. Piping plain \`gtd next\` (not
+      # --json=content) means the diff is rendered once, for this input,
+      # rather than twice.
+      agent_turn() { gtd next | claude -p "$1" "$session_id" \\
+        \${model:+--model "$model"} \\
+        \${system:+--system-prompt "$system"} \\
+        --dangerously-skip-permissions >>"$log" 2>&1; }
+      if [ "\${resume:-}" = true ]
       then agent_turn --resume || agent_turn --session-id
       else agent_turn --session-id || agent_turn --resume
       fi
       n=0
-      while [ -n "\${gtd_validate:-}" ] && ! fix="$(sh -c "$gtd_validate" 2>&1)"; do
+      while [ -n "\${validate:-}" ] && ! fix="$(sh -c "$validate" 2>&1)"; do
         n=$((n + 1)) && [ "$n" -gt 3 ] && { printf '%s\\n' "$fix" >&2; exit 1; }
-        # $fix IS the fix prompt, verbatim — piped for the same reason as
-        # $gtd_content above. Whether \`claude --resume\` re-applies the
+        # $fix IS the fix prompt, verbatim — piped for the same reason the
+        # agent's own turn above is. Whether \`claude --resume\` re-applies the
         # original session's model/system prompt is a harness detail gtd
         # cannot verify from outside, so this passes the identical
-        # $gtd_model/$gtd_system on both calls rather than assume it does —
+        # $model/$system on both calls rather than assume it does —
         # otherwise this fix turn might silently fall back to Claude Code's
         # own defaults while the turn that produced the file ran under the
         # workflow's own model and persona.
-        printf '%s' "$fix" | claude -p --resume "$gtd_session_id" \\
-          \${gtd_model:+--model "$gtd_model"} \\
-          \${gtd_system:+--system-prompt "$gtd_system"} \\
-          --dangerously-skip-permissions >>"$gtd_log" 2>&1
+        printf '%s' "$fix" | claude -p --resume "$session_id" \\
+          \${model:+--model "$model"} \\
+          \${system:+--system-prompt "$system"} \\
+          --dangerously-skip-permissions >>"$log" 2>&1
       done ;;
   esac
 
-  # \`gtd land --sh\` carries \`settled\`/\`idle\` alongside the script itself —
-  # one invocation tells us both what to run and whether to stop, with no
-  # second read needed to decide either.
-  out="$(gtd land --sh)"
-  eval "$out"
-  printf '%s\\n' "$gtd_script" | sh
-  if [ "\${gtd_settled:-}" = true ]; then
-    [ "\${gtd_idle:-}" = true ] && gtd next
+  # Read every value the landing needs BEFORE piping the script to \`sh\`:
+  # \`gtd land\` itself never mutates — it only plans and prints — so
+  # \`settled\`/\`idle\`/\`script\` planned against the same untouched tree all
+  # agree, whatever order they're read in, as long as all three are read
+  # before the script runs and changes the tree out from under them.
+  settled="$(gtd land --json=settled)"
+  idle="$(gtd land --json=idle)"
+  gtd land --json=script | sh
+  if [ "\${settled:-}" = true ]; then
+    [ "\${idle:-}" = true ] && gtd next
     exit 0
   fi
   beat=$((beat + 1))
@@ -206342,102 +206231,104 @@ done`;
 const EDIT_COMMAND = `#!/usr/bin/env sh
 set -eu
 cd "$(git rev-parse --show-toplevel)"
-out="$(gtd next --sh)"
-eval "$out"
-f="\${gtd_file:-.gtd/TODO.md}"
+f="$(gtd next --json=file)"
+f="\${f:-.gtd/TODO.md}"
 mkdir -p "$(dirname "$f")"
 exec "\${EDITOR:-vi}" "$f"`;
-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 HEADER = () => `gtd ${GTD_VERSION$1} — driver protocol\n\ngtd decides and prints; the driver executes. gtd never runs git, never runs\nyour agent, never runs a check script, and never runs a steering mode's own\nformat:/validate: command either — that pair is text in the script gtd next\n--json's validate field (or gtd validate) prints, for the driver to run\nitself ahead of gtd land.\n`;
 const BEAT_PROTOCOL = `
 ## The beat protocol
 
 Two reads and one write, repeated: ask -> act -> land.
 
-  gtd next --sh   which kind is next, as gtd_-prefixed POSIX shell
-                  assignments (eval it) — a pure read; poll it, peek it, no writes
-  gtd next          what to run/show, in plain text — the SAME rest the --sh read just fetched
-  gtd land --sh   how to record what happened, and whether anything is
-                  still owed (gtd_script to run, gtd_settled to check) — eval it, run gtd_script
+  gtd next --json=<path>   which kind is next, and any other field, one pure
+                            scalar read per value (kind, content, idle,
+                            session.id, model, validate, log, ...)
+  gtd next                   what to run/show, in plain text — the SAME rest
+                            the --json=<path> reads above are peeking at
+  gtd land --json=<path>   how to record what happened, and whether anything
+                            is still owed (script to run, settled to check)
 
 Every beat that acts, lands. Every beat that rests, exits.
 
-Both reads are pure PEEKS — every field \`gtd next --sh\`/\`--json\` reports
-(\`gtd_session_id\`/\`gtd_session_resume\` included) is DERIVED from history,
-never stored, so looking is free: nothing distinguishes a peek from a
-dispatch, and calling either one twice in a row is always safe. There is no
-separate claiming form.
+Every \`gtd next --json=<path>\`/\`gtd land --json=<path>\` read is a pure PEEK —
+every field it reports (\`session.id\`/\`session.resume\` included) is DERIVED
+from history, never stored, so looking is free: nothing distinguishes a peek
+from a dispatch, and calling either one twice in a row is always safe. There
+is no separate claiming form.
 
-\`gtd next\` has \`--json\`/\`--sh\` encodings, mutually exclusive, reading the
-SAME field set whether you call \`gtd next --json\` or \`gtd next --sh\` —
-\`--json\`'s keys, or \`--sh\`'s \`gtd_\`-prefixed shell assignments. An AI
-driver reads \`gtd_kind\`/\`gtd_session_id\` and the rest straight off \`--sh\`
-without parsing anything — no JSON library, no \`jq\`; this briefing's own
-reference driver uses \`--sh\` throughout. Plain
-\`gtd next\` (no flag) is NOT a parsing surface: \`content\` is the bare step
-in every encoding; plain adds the self-validation instruction at a
+\`gtd next\` has one structured encoding, \`--json\`: bare \`--json\` prints the
+whole document, \`--json=<path>\` (a dotted key path, e.g. \`kind\`, \`content\`,
+\`session.id\`) prints just that one value — a scalar raw and unquoted, a
+boolean as \`true\`/\`false\`, a list one JSON entry per line. An absent
+optional field prints nothing and exits 0; an unknown path is a usage error
+(exit 2). An AI driver reads \`kind\`/\`session.id\` and the rest straight off
+\`--json=<path>\`, one call per value, without parsing anything — no JSON
+library, no \`jq\`; this briefing's own reference driver reads every field this
+way. Plain \`gtd next\` (no flag) is NOT a parsing surface: \`content\` is the
+bare step in every encoding; plain adds the self-validation instruction at a
 validatable \`prompt\` rest, and adds a status-summary header at every kind
 EXCEPT \`prompt\` (those bytes are the agent's own input, so no header is
-prefixed there). A driver that wants \`content\` programmatically reads it
-off \`--json\`/\`--sh\` (\`gtd_content\` under \`--sh\`), never by scraping plain
-text.
+prefixed there). A driver that wants \`content\` programmatically reads it off
+\`--json=content\`, never by scraping plain text.
 
-The \`kind\` field (\`gtd_kind\` under \`--sh\`) selects what to do:
+The \`kind\` field (\`--json=kind\`) selects what to do:
 
-- \`stalled\` — print \`gtd_content\` (the diagnosis, already in hand) to
+- \`stalled\` — print \`--json=content\` (the diagnosis, already in hand) to
   stderr and exit non-zero. Terminal: another dispatch would just repeat the
   same fruitless turn.
 - \`message\` — print plain \`gtd next\`'s output (the richer status header,
-  not bare \`gtd_content\`) and exit 0. This is a human gate. EXCEPT on the
-  run's opening beat: the human invoked you while resting there, so land it
+  not bare \`content\`) and exit 0. This is a human gate. EXCEPT on the run's
+  opening beat: the human invoked you while resting there, so land it
   instead of printing. Some gates route a \`"C"\` (clean-tree) pattern
   onward, making "change nothing" a real decision that looks identical to a
   gate nobody has read yet; landing an opening beat at a gate without one is
   a benign no-op, and it prints on the next beat.
 - \`capture\` — a human gate the human already acted on (the tree is dirty).
   Land it immediately, no display needed.
-- \`script\` — run \`gtd_content\` with \`sh -c\`, appending its output to
-  \`gtd_log\`, and ignore its exit code — the outcome lives in the tree, not
-  in the exit code.
-- \`prompt\` — send \`gtd_content\` to your agent CLI over stdin, using the
-  accompanying \`gtd_session_id\`/\`gtd_model\`/\`gtd_validate\` fields off the
-  SAME \`--sh\` read (see below).
+- \`script\` — run \`--json=content\` with \`sh -c\`, appending its output to
+  \`--json=log\`, and ignore its exit code — the outcome lives in the tree,
+  not in the exit code.
+- \`prompt\` — send plain \`gtd next\`'s own output to your agent CLI over
+  stdin (it's the bare content at this kind, so no separate \`--json=content\`
+  read is needed), using the accompanying \`session.id\`/\`session.resume\`/
+  \`model\`/\`validate\` fields, each its own \`--json=<path>\` read (see
+  below).
 `;
 const JSON_FIELD_REFERENCE = `
 ## Field reference
 
-\`gtd next\` and \`gtd land\` each carry one field set, in two encodings:
-\`--json\`'s keys, or \`--sh\`'s \`gtd_\`-prefixed shell assignments — this
-driver's own beats poll \`--sh\` throughout (see the beat protocol above).
-There is no version field — the field set itself is the contract, and a
-breaking change to it is a major release. Every field below is always
-present unless marked "when set" — omitted under \`--json\` (never \`null\`),
-genuinely unset under \`--sh\` (its own \`unset\` preamble, so read an optional
-one as \`\${gtd_model:-}\` or \`\${gtd_model:+...}\`, never bare).
+\`gtd next\` and \`gtd land\` each carry one field set, read through \`--json\`
+(bare for the whole document, \`--json=<path>\` for one value) — this driver's
+own beats read fields one at a time via \`--json=<path>\` throughout (see the
+beat protocol above). There is no version field — the field set itself is the
+contract, and a breaking change to it is a major release. Every field below
+is always present unless marked "when set" — omitted under bare \`--json\`
+(never \`null\`); under \`--json=<path>\` an absent field prints nothing and
+exits 0, so read it in a shell variable and guard on emptiness
+(\`\${x:-}\`/\`\${x:+...}\`) rather than assuming it is always populated.
 
 \`gtd next\` fields — Always: \`kind\` (\`capture\`|\`message\`|\`script\`|\`prompt\`|
 \`stalled\`), \`content\` (the bare step in every encoding — plain \`gtd next\`
 adds the self-validation instruction at a validatable \`prompt\` rest, and a
 status-summary header at every OTHER kind; \`content\` itself never carries
 either), \`idle\` (\`true\` iff the resolved rest is the workflow's initial
-state with a clean tree — under \`--sh\`, present only when \`true\`), \`log\`,
-\`state\`, \`actor\`, \`changes\` (which declared \`on\` pattern, if any, each
-pending change matches), \`next\` (the first declared \`on\` edge that would
-fire right now — \`{action?, pattern, target}\` — or \`null\` on no match).
-Only at \`kind: "prompt"\` (the DISPATCH BLOCK — absent at every other kind,
-a \`stalled\` beat included, by construction): \`session\` (\`{id, resume}\` —
-\`gtd_session_id\`/\`gtd_session_resume\` under \`--sh\` — both DERIVED from
-history, 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 script that formats then validates it). When set:
-\`model\`, \`memory\`, \`label\`, \`file\`, \`mode\`, \`edges\`. When a cost has been
-recorded (a prior \`gtd land --cost=<n>\`): \`cost\`, \`costByModel\`.
+state with a clean tree), \`log\`, \`state\`, \`actor\`, \`changes\` (which
+declared \`on\` pattern, if any, each pending change matches), \`next\` (the
+first declared \`on\` edge that would fire right now — \`{action?, pattern,
+target}\` — or \`null\` on no match). Only at \`kind: "prompt"\` (the DISPATCH
+BLOCK — absent at every other kind, a \`stalled\` beat included, by
+construction): \`session.id\`/\`session.resume\` — both DERIVED from history,
+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 script that formats then validates it). When set: \`model\`, \`memory\`,
+\`label\`, \`file\`, \`mode\`, \`edges\`. When a cost has been recorded (a prior
+\`gtd land --cost=<n>\`): \`cost\`, \`costByModel\`.
 
-\`gtd land\` fields, in fixed order: \`script\` (the POSIX sh to run —
-\`gtd_script\` under \`--sh\`), \`settled\` (true for either terminal shape: a
-no-op at a \`script\` rest, or a decision that collapses back to the initial
-state retaining nothing — stop immediately, nothing more to read), \`idle\`
-(true iff the state landing rests at is the workflow's initial state),
-\`state\`, \`subject\`, \`cost\`, \`model\` (the last three \`null\`, never
+\`gtd land\` fields, in fixed order: \`script\` (the POSIX sh to run), \`settled\`
+(true for a no-op at a \`script\` rest — stop immediately, nothing more to
+read), \`idle\` (true iff the state landing rests at is the workflow's initial
+state), \`state\`, \`subject\`, \`cost\`, \`model\` (the last three \`null\`, never
 omitted, for a genuine no-op).
 
 ### The error envelope
@@ -206449,63 +206340,62 @@ stdout stays byte-empty: \`{"state":"error","prompt":"<message>"}\` rides
 or defect, exit 2 for a usage error (nothing was even attempted). This is
 true of every command, not only \`gtd next\` — an invocation that carries (or
 misuses) \`--json\` still gets this envelope on its own failure. A driver
-piping stdout into a JSON parser on a failed run reads nothing; read stderr
-or the exit code to learn why.
+reading stdout on a failed run reads nothing; read stderr or the exit code
+to learn why.
 `;
 const DRIVER_OBLIGATIONS = `
 ## Driver obligations, in order
 
-1. Read the resolved rest's \`kind\` off \`gtd next --sh\` once per iteration
-   (assign its output to a variable, THEN \`eval\` that variable — never
-   \`eval "$(gtd next --sh)"\` directly, since a failed \`gtd next\` would then
-   eval the empty string and die later on some unrelated unset variable
-   instead of aborting cleanly). Exit code is uniformly \`0\` on success now —
-   it never says whose turn is next; only \`1\`/\`2\` means gtd itself failed.
-   There is no opening move: a human's pending edit arrives as a
-   \`kind: "capture"\` beat, which you land immediately without executing
-   anything. EXCEPT: don't trust \`gtd_idle\` on the run's very first
-   iteration — land that beat first, so a workflow whose initial state
-   declares its own clean-tree \`"C"\` pattern still gets one chance to
-   advance before you conclude nothing is owed.
-2. Read the content to run/show off the SAME \`--sh\` read's \`gtd_content\` —
-   never off plain \`gtd next\`, which is not a parsing surface (it wraps
-   \`content\` in a status-summary header at every kind but \`prompt\`; see the
-   beat protocol above). At a \`prompt\` beat this content embeds a full
-   diff, so hand it to the agent CLI over STDIN, never as a command-line
-   argument — argv is capped (roughly 1 MB on macOS, and POSIX guarantees
-   only 4 KB, \`ARG_MAX\`), both reachable by an ordinary diff, and an
-   argv-passing driver fails on the first large one in a way that looks
-   like an agent error rather than a driver bug.
-3. A \`kind: "stalled"\` beat prints \`gtd_content\` (already in hand — no
-   re-invocation needed) to stderr and halts with a non-zero exit; a
-   \`kind: "message"\` beat prints plain \`gtd next\`'s output and exits 0,
-   unless it is the run's opening beat — land that one, since the human's
-   re-invocation while resting there is itself their decision.
-4. Run scripts with their output appended to \`gtd_log\` — gtd never creates
-   or truncates that file itself; truncate it once per run. \`$GTD_LOOP_LOG\`
-   overrides its path.
-5. Map \`gtd_session_id\`/\`gtd_session_resume\` onto the agent CLI's own
+1. Read the resolved rest's \`kind\` off \`gtd next --json=kind\` once per
+   iteration. Exit code is uniformly \`0\` on success now — it never says
+   whose turn is next; only \`1\`/\`2\` means gtd itself failed. There is no
+   opening move: a human's pending edit arrives as a \`kind: "capture"\` beat,
+   which you land immediately without executing anything. EXCEPT: don't
+   trust \`idle\` on the run's very first iteration — land that beat first, so
+   a workflow whose initial state declares its own clean-tree \`"C"\` pattern
+   still gets one chance to advance before you conclude nothing is owed.
+2. Read the content to run/show off \`--json=content\` — never off plain
+   \`gtd next\`, which is not a parsing surface (it wraps \`content\` in a
+   status-summary header at every kind but \`prompt\`; see the beat protocol
+   above). At a \`prompt\` beat, though, pipe plain \`gtd next\`'s own output to
+   the agent instead of reading \`--json=content\` separately — it IS the bare
+   content at that kind, so a second read would only render the same diff
+   twice. Whichever form you read, hand it to the agent CLI over STDIN, never
+   as a command-line argument — argv is capped (roughly 1 MB on macOS, and
+   POSIX guarantees only 4 KB, \`ARG_MAX\`), both reachable by an ordinary
+   diff, and an argv-passing driver fails on the first large one in a way
+   that looks like an agent error rather than a driver bug.
+3. A \`kind: "stalled"\` beat prints \`--json=content\` to stderr and halts with
+   a non-zero exit; a \`kind: "message"\` beat prints plain \`gtd next\`'s
+   output and exits 0, unless it is the run's opening beat — land that one,
+   since the human's re-invocation while resting there is itself their
+   decision.
+4. Run scripts with their output appended to \`--json=log\` — gtd never
+   creates or truncates that file itself; truncate it once per run.
+   \`$GTD_LOOP_LOG\` overrides its path.
+5. Map \`--json=session.id\`/\`--json=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).
-6. After a \`prompt\` beat, run the same read's own \`gtd_validate\` script
+6. After a \`prompt\` beat, run the same beat's own \`--json=validate\` script
    (when set) and re-prompt its output verbatim on failure — the DRIVER
    owns the retry cap, not gtd.
 7. 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.
-8. Run \`gtd land --sh\` (assign, then \`eval\`, exactly like obligation 1) and
-   pipe its own \`gtd_script\` into \`sh\` — never a bare \`gtd land | sh\`,
-   which would hand an empty script to \`sh\` on a refusal instead of
-   stopping first.
-9. Check the SAME \`gtd land --sh\` read's \`gtd_settled\`/\`gtd_idle\` fields —
-   no second read needed to decide. \`gtd_settled = true\` means stop right
-   there (a no-op at a \`script\` rest settles in place; nothing more to
-   read); otherwise keep looping, and the run finishes when a LATER
-   \`gtd next --sh\` reports \`gtd_idle = true\` (read once more with plain
-   \`gtd next\` only to show that gate's message, the decision to stop
-   already made). Exit code carries none of this any more — every command
-   exits \`0\` on success uniformly.
+8. Read \`--json=settled\`/\`--json=idle\` from \`gtd land\` BEFORE running the
+   script — \`gtd land\` never mutates, it only plans and prints, so these
+   reads and the \`--json=script\` read that follows all agree, planned
+   against the same untouched tree. Pipe \`--json=script\`'s own output into
+   \`sh\` — never a bare \`gtd land | sh\`, which would hand an empty script to
+   \`sh\` on a refusal instead of stopping first.
+9. Check the settled/idle values read in step 8 — no second read needed to
+   decide. \`settled = true\` means stop right there (a no-op at a \`script\`
+   rest settles in place; nothing more to read); otherwise keep looping, and
+   the run finishes when a LATER \`gtd next --json=idle\` reports \`true\`
+   (read once more with plain \`gtd next\` only to show that gate's message,
+   the decision to stop already made). Exit code carries none of this any
+   more — every command exits \`0\` on success uniformly.
 `;
 const RECOVERY = `
 ## Recovery
@@ -206513,14 +206403,14 @@ const RECOVERY = `
 gtd exiting 2 means nothing was even attempted — a usage error; exiting 1
 means a refusal — nothing was emitted either. An emitted script exiting
 non-zero when YOU run it means something MAY have partially happened. Both
-recover the same way: re-invoke gtd (\`gtd next --sh\`, \`gtd next\`, then
-\`gtd land --sh\`). It re-reads the real repository state fresh every time —
-never a cached plan — and emits whatever still needs to happen from there.
-This works because 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".
+recover the same way: re-invoke gtd (\`gtd next --json=kind\`, \`gtd next\`,
+then \`gtd land --json=<path>\`). It re-reads the real repository state fresh
+every time — never a cached plan — and emits whatever still needs to happen
+from there. This works because 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
@@ -206549,19 +206439,19 @@ follow in the same numbered list.
    committing it first turns the config into the very first thing the
    process plans against. Commit it, THEN start driving.
 4. **Which agent should run the turns?** Whatever coding-agent CLI they
-   already use (default: \`claude\`). Map \`gtd_session_id\`/
-   \`gtd_session_resume\` onto THAT agent's continuation mechanism
-   (obligation 5); an agent with no session concept just ignores them —
-   memory is an optimization, every prompt is self-contained.
+   already use (default: \`claude\`). Map \`session.id\`/\`session.resume\`
+   onto THAT agent's continuation mechanism (obligation 5); an agent with
+   no session concept just ignores them — memory is an optimization, every
+   prompt is self-contained.
 5. **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 \`gtd_model\` hints should be honored (default: yes).
+   own \`model\` hints should be honored (default: yes).
 6. **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\`/\`--sh\` and spawns subprocesses.
+   choice, anything that reads \`--json=<path>\` and spawns subprocesses.
 7. **What should happen at the boundaries?** Where the log goes (obligation
    4), and whether halting at a human gate should do anything richer than
    print — desktop notification, terminal-multiplexer status, editor focus —
@@ -206573,13 +206463,13 @@ follow in the same numbered list.
    (\`~/.local/bin/gtd-loop\`) — the interview can override either name.
 
 Then build it, and verify safely before the first real drive:
-\`gtd next --sh\`/\`gtd next\` are both pure reads — eval/parse them, check
-your kind dispatch against the table above, call them as often as you like.
-Nothing happens until you run an emitted script.
+\`gtd next --json=<path>\`/\`gtd next\` are both pure reads — read/parse them,
+check your kind dispatch against the table above, call them as often as you
+like. Nothing happens until you run an emitted script.
 
-The reference rendering in sh (no \`jq\`, no JSON parser at all — \`--sh\`'s
-own \`gtd_\`-prefixed shell assignments are eval'd directly; the \`claude\`
-lines are what answers 1–2 replace):
+The reference rendering in sh (no \`jq\`, no JSON parser at all — each
+\`--json=<path>\` call prints its one value directly; the \`claude\` lines are
+what answers 1–2 replace):
 
 \`\`\`bash
 ${MINIMAL_DRIVER}
@@ -206593,15 +206483,16 @@ a second artifact to the same interview (questions 8–9 above): an edit
 command that opens the steering file the process is resting at right now,
 suggested at \`~/.local/bin/gtd-edit\`.
 
-\`gtd next --sh\` already reports \`file\` (\`gtd_file\` under \`--sh\`) for every
-state that declares one — the edit command needs no new engine surface, just
-a read and an editor spawn. \`file\` is an OPTIONAL field: it is genuinely
-unset under \`--sh\` at a state that declares no \`file:\`, so read it as
-\`\${gtd_file:-.gtd/TODO.md}\`, never bare — a bare read, or a
-\`gtd next --json | jq .file\` recipe (the idea, never the recipe: \`--json\`
-needs \`jq\`, and \`jq .file\` prints the string \`null\` on an unset field, which
-opens a file literally named \`null\` in the repository root), ships that bug
-to every user.
+\`gtd next --json=file\` already reports the file for every state that
+declares one — the edit command needs no new engine surface, just a read and
+an editor spawn. \`file\` is an OPTIONAL field: \`--json=file\` prints nothing
+(not the string \`null\`) at a state that declares no \`file:\`, so read it into
+a shell variable and fall back explicitly — \`f="$(gtd next --json=file)"\`
+then \`f="\${f:-.gtd/TODO.md}"\`, never assume the read populated anything. This
+is also the general rule for every optional field \`--json=<path>\` exposes:
+an absent field is silence, not the string \`null\` a \`jq .field\` recipe would
+print on the same input — code that treats empty output as "field genuinely
+absent" is correct, code that expects a literal \`null\` string is not.
 
 This is also how a human starts a process at all: at the initial \`idle\`
 state the resting file IS \`.gtd/TODO.md\`, so on a clean repository the edit
@@ -206621,19 +206512,108 @@ const PREREQUISITES = `
 ## Prerequisites and portability
 
 - A POSIX \`sh\` (dash, ash, bash's own POSIX mode, etc.) — gtd's own emitted
-  scripts (\`gtd land\`, \`gtd --entry <state>\`, \`gtd abandon\`,
+  scripts (\`gtd land --json=script\`, \`gtd --entry <state>\`, \`gtd abandon\`,
   \`gtd restore\`) are POSIX sh; captured, then piped into it (see obligation
-  8 above). \`eval\`ing \`gtd next --sh\`/\`gtd land --sh\`'s own output needs
-  nothing beyond the same POSIX \`sh\`.
+  8 above). Reading \`gtd next --json=<path>\`/\`gtd land --json=<path>\`'s own
+  output needs nothing beyond the same POSIX \`sh\` — no \`eval\`, no parser.
 - \`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\`/\`--sh\` in, subprocesses out.
+Any runtime works: the contract is \`--json\`/\`--json=<path>\` in, subprocesses
+out.
 `;
 const renderBriefing = () => HEADER() + BEAT_PROTOCOL + JSON_FIELD_REFERENCE + DRIVER_OBLIGATIONS + RECOVERY + referenceImplementation() + editCommand() + PREREQUISITES;
 //#endregion
+//#region src/Select.ts
+/**
+* Renders a fully-walked leaf value: scalars/booleans stringify directly,
+* arrays become one `JSON.stringify` per entry, newline-joined.
+* `selectPath`'s loop already returns `absent` for `undefined`/`null` after
+* every segment (including the last), so neither ever reaches here.
+*/
+const toSelection = (value) => {
+	if (Array.isArray(value)) return {
+		kind: "value",
+		text: value.map((entry) => JSON.stringify(entry)).join("\n")
+	};
+	if (typeof value === "object") return {
+		kind: "value",
+		text: JSON.stringify(value)
+	};
+	return {
+		kind: "value",
+		text: String(value)
+	};
+};
+/** A segment that resolves to no key at all (missing from an object, or numeric/absent against an array) — distinct from a present key holding `undefined`. */
+const NOT_FOUND = Symbol("not-found");
+/**
+* One step of the walk: looks `segment` up on `current`, or reports
+* `NOT_FOUND` for a key that was never there (no array indexing; a primitive
+* has no keys). Presence is an OWN-property test
+* (`Object.prototype.hasOwnProperty`), never the `in` operator — `in` walks
+* the prototype chain, so it would resolve inherited members
+* (`constructor`, `toString`, `hasOwnProperty`, `valueOf`, ...) as real
+* document fields. An array declares no non-index own key the document ever
+* uses, so every array segment is `NOT_FOUND` (all-digit ones already were;
+* this also now excludes `length`/`map`/every other inherited array member).
+*/
+const resolveSegment = (current, segment) => {
+	if (Array.isArray(current)) return NOT_FOUND;
+	if (typeof current === "object" && current !== null) {
+		const record = current;
+		return Object.prototype.hasOwnProperty.call(record, segment) ? record[segment] : NOT_FOUND;
+	}
+	return NOT_FOUND;
+};
+/**
+* Walks `fields` by dotted key path. Never throws — any unwalkable shape
+* (a primitive mid-path, an array indexed by a numeric segment) degrades to
+* `unknown`, and a present-but-`undefined` value anywhere along the path
+* short-circuits the whole remaining path to `absent` rather than reporting
+* a key that was never actually missing.
+*/
+const selectPath = (fields, path) => {
+	try {
+		let current = fields;
+		for (const segment of path.split(".")) {
+			current = resolveSegment(current, segment);
+			if (current === NOT_FOUND) return {
+				kind: "unknown",
+				path
+			};
+			if (current === void 0 || current === null) return { kind: "absent" };
+		}
+		return toSelection(current);
+	} catch {
+		return {
+			kind: "unknown",
+			path
+		};
+	}
+};
+//#endregion
 //#region src/program.ts
+/**
+* A command-level failure that should exit like a CLI usage error (2), not a
+* generic runtime failure (1) — currently only the `--json=<unknown-path>`
+* selector case.
+*/
+var SelectorUsageError = class extends Error {};
+/**
+* The `--json=<path>` select branch, shared by `runNextCommand` and
+* `runLandCommand` so the two never drift on the unknown-selector message: a
+* `value` writes its text plus exactly one trailing newline, `absent` writes
+* nothing (the caller's normal success path continues), and `unknown` fails
+* with `SelectorUsageError` (mapped to `EXIT_USAGE_ERROR` by `Cli.ts`'s
+* `report`).
+*/
+const writeSelection = (out, fields, path) => gen(function* () {
+	const selection = selectPath(fields, path);
+	if (selection.kind === "value") out.write(`${selection.text}\n`);
+	else if (selection.kind === "unknown") return yield* fail$2(new SelectorUsageError(`gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``));
+});
 /** `needs: "none"` skips the repo-root guard — the server is keyed on file name, not workflow state. */
 const runLspCommand = () => startLspServer();
 /** Emitted by the binary itself (`src/Install.ts`'s `renderBriefing()`) so it's always current. Writes nothing else; runs from any directory since it resolves no workflow state. */
@@ -206670,49 +206650,22 @@ const runInitCommand = (out) => gen(function* () {
 * `normalizeTrailingNewline` rather than imported, to avoid a circular value
 * dependency (`Cli.ts` already depends on this module). `LandResult.script`
 * must carry its own trailing newline because it's embedded verbatim inside
-* the `--json`/`--sh` documents too, never re-normalized at their tail.
+* the `--json` document, never re-normalized at its tail.
 */
 const normalizeScriptNewline = (script) => script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`;
 const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const headPreconditions = (currentCommit) => ({ expectedHead: currentCommit });
-/**
-* The resting state's own steering-mode format/validate commands, embedded
-* ahead of the commit. Empty for a state declaring no `file:`+`mode:` pair;
-* an unknown mode name is a refusal.
-*
-* Also empty when the step deletes that file, or when it's absent from the
-* working tree — either way there's nothing left to format/validate.
-* Emitting `format:` anyway would make the step unlandable for a formatter
-* that errors on a missing path (e.g. `prettier --write`), since it's the
-* first command in a `set -euo pipefail` script and would abort the whole
-* thing — window close, commit and all — before anything could land.
-*/
-const steeringModeSteps = (rest) => gen(function* () {
-	const file = rest.hints.file;
-	const mode = rest.stateDef.mode;
-	if (file === void 0 || mode === void 0) return [];
-	if (deletesFile(rest.changes, file)) return [];
-	if ((yield* RepoFiles).working(file) === void 0) return [];
-	const resolved = resolveSteeringMode(rest.def, mode);
-	if (resolved === void 0) return yield* fail$2(new Error(unknownModeMessage(rest.def, rest.state, mode)));
-	return yield* renderSteeringModeCommandSteps(resolved, file, rest.context);
-});
-/** 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). */
+/** True for a `"commit"` decision that is an ATTEMPT (`PatternMachine.StepCommit.attempt`) — the one flag `enforceStepGuards` bypasses its own steps for (see its call site). */
 const isAttemptDecision = (decision) => decision.kind === "commit" && decision.attempt === true;
 /** The subject the required script will produce. */
 const previewSubject = (decision) => succeed$3(decision.subject);
 /**
-* The `required` half: the resting state's own steering-mode commands, then
-* the commit steps. The steering-mode step is skipped for an attempt commit —
-* nothing to format/validate in an empty diff, and running `format:` ahead of
-* the commit could dirty the tree and turn an "empty" attempt non-empty,
-* breaking `stalledAt`'s derivation.
+* The `required` half: the HEAD assertion plus the commit steps, nothing
+* else. The steering-file format/validate pair is no longer part of the
+* landing script — that's a driver contract now (`gtd next --json`'s
+* `validate` field), not a gtd guarantee (see `resolveSelfValidateCommand`).
 */
-const buildRequiredScript = (rest, decision, cost, model) => gen(function* () {
-	const git = yield* GitService;
-	const steps = [...isAttemptDecision(decision) ? [] : yield* steeringModeSteps(rest), ...yield* renderDecision(git, rest, decision, cost, model)];
-	return emitScripts(headPreconditions(rest.context.currentCommit), steps).required;
-});
+const buildRequiredScript = (rest, decision, cost, model) => succeed$3(emitScripts(headPreconditions(rest.context.currentCommit), renderDecision(rest, decision, cost, model)).required);
 /**
 * Decide the one resulting transition (a commit) for `gtd land`
 * without performing it, authenticating as `rest.actor`. Refusals fail the
@@ -206749,7 +206702,6 @@ const planLanding = (opts = {}) => gen(function* () {
 		attempt: isAttemptDecision(decision)
 	});
 	const restingState = decision.to;
-	const settled = yield* collapsesToInitialState(rest, decision);
 	const required = yield* buildRequiredScript(rest, decision, opts.cost, opts.model);
 	return {
 		state: restingState,
@@ -206757,7 +206709,7 @@ const planLanding = (opts = {}) => gen(function* () {
 		cost: opts.cost ?? null,
 		model: opts.model ?? null,
 		script: normalizeScriptNewline(combinedScript(required, "")),
-		settled,
+		settled: false,
 		idle: restingState === initialStateOf(rest.def)
 	};
 });
@@ -206796,16 +206748,19 @@ const runBaseCommand = (out) => gen(function* () {
 /**
 * `gtd land [--cost=<n>] [--model=<name>]`: land whatever the tree shows at
 * the currently resolved rest, authenticated as the rest's own actor.
-* Plain output writes `result.script` verbatim so `gtd land | sh` keeps
-* working; `--json`/`--sh` emit `script` alongside `settled`/`idle`/`state`/
-* `subject`/`cost`/`model`. Exit code is uniformly `EXIT_OK` on success —
-* whose turn is next lives in the following `gtd next --json`'s `kind` field.
-*/
-const runLandCommand = (opts, json, sh, out) => gen(function* () {
-	const result = yield* planLanding(opts);
-	if (json) out.write(renderLandJson(landFields(result)));
-	else if (sh) out.write(renderLandSh(landFields(result)));
-	else out.write(result.script);
+* Plain output is `renderLandPlain`'s prose — the commit subject plus a
+* pointer at `--json=script`, or the no-op note when nothing landed — never
+* the script itself; `--json` emits `script` (byte-identical to before)
+* alongside `settled`/`idle`/`state`/`subject`/`cost`/`model`, so it stays
+* the machine path a driver pipes to `sh`. Exit code is uniformly `EXIT_OK`
+* on success — whose turn is next lives in the following `gtd next --json`'s
+* `kind` field.
+*/
+const runLandCommand = (opts, json, out) => gen(function* () {
+	const built = landFields(yield* planLanding(opts));
+	if (json.kind === "document") out.write(renderLandJson(built));
+	else if (json.kind === "select") yield* writeSelection(out, built, json.path);
+	else out.write(renderLandPlain(built));
 });
 /**
 * `gtd --entry <state> [--var <name>=<value> ...]` (`actor` always `"human"`):
@@ -206887,8 +206842,7 @@ const runAbandonCommand = (out) => gen(function* () {
 	out.write(combinedScript(required, ""));
 });
 /**
-* `gtd restore`: hard-reset HEAD back to the tip `gtd abandon` (or the
-* initial-state collapse's own mixed reset) retained.
+* `gtd restore`: hard-reset HEAD back to the tip `gtd abandon` retained.
 *
 * Guarded by `restorability` so it never discards work it didn't create:
 * refuses on a dirty working tree, no retained history, or HEAD having
@@ -206950,9 +206904,8 @@ const emitsValidatablePrompt = (rendered) => rendered.kind === "prompt" && rende
 /**
 * Render `resolved`'s format:/validate: commands as `EmitStep[]`, wrapping
 * the last one with `onFailure: fixPromptInstruction(file)` when the
-* validator is a command — shared by `resolveValidateScript` and
-* `steeringModeSteps` so the two never drift on which command gets the
-* routable fix prompt.
+* validator is a command — `resolveValidateScript`'s own helper, split out
+* so its render logic isn't inlined into that function's body.
 */
 const renderSteeringModeCommandSteps = (resolved, file, context) => gen(function* () {
 	const commands = yield* renderSteeringCommands(resolved, file, context);
@@ -207066,20 +207019,20 @@ const restBeatKind = (rest) => beatKindOf({
 /** `idle` means exactly one thing: the machine rests at the workflow's initial state with a clean tree — the process is genuinely done. */
 const restIsIdle = (rest) => rest.state === initialStateOf(rest.def) && rest.changes.length === 0;
 /**
-* `gtd next`: pure emitter of the resolved rest's beat, in three encodings —
-* `--json`/`--sh` and plain (the default). No mutation: nothing is written,
+* `gtd next`: pure emitter of the resolved rest's beat, in two encodings —
+* `--json` and plain (the default). No mutation: nothing is written,
 * so a peek and a would-be dispatch are the same call. Exit code is
 * `EXIT_OK` unconditionally — whose turn is next lives in the beat
 * document's own `kind` field, never the exit code.
 */
-const runNextCommand = (json, sh, out) => gen(function* () {
+const runNextCommand = (json, out) => gen(function* () {
 	const rest = yield* currentRest;
 	const rendered = yield* renderRest(rest);
 	const fields = yield* gatherBeatFields(rest, rendered);
 	const narrator = yield* Narrator;
 	for (const change of fields.changes) yield* narrator.narrate(`pending: ${change.status} ${change.path} -> ${change.pattern ?? "(no match)"}`);
-	if (json) out.write(renderBeatJson(fields));
-	else if (sh) out.write(renderBeatSh(fields));
+	if (json.kind === "document") out.write(renderBeatJson(fields));
+	else if (json.kind === "select") yield* writeSelection(out, fields, json.path);
 	else {
 		const selfValidateCommand = emitsValidatablePrompt(rendered) ? yield* resolveSelfValidateCommand(rest.def, rendered.mode, rendered.file, rest.context).pipe(catchAll(() => succeed$3(void 0))) : void 0;
 		out.write(renderBeatPlain(fields, selfValidateCommand));
@@ -207183,7 +207136,7 @@ const computeNextMatch = (onEdges, changes) => {
 	}
 	return null;
 };
-/** Everything one beat needs beyond the resolved rest itself, gathered once so plain/`--json`/`--sh` can never describe different rests for the same beat. */
+/** Everything one beat needs beyond the resolved rest itself, gathered once so plain/`--json` can never describe different rests for the same beat. */
 const gatherBeatFields = (rest, rendered) => gen(function* () {
 	const kind = restBeatKind(rest);
 	const session = kind === "prompt" ? resolveSession(rendered.memory, rendered.memoryResumed) : void 0;
@@ -207299,7 +207252,7 @@ const needsOf = (kind) => {
 * unrepresentable: every branch returns `Effect<void>`, and `Cli.ts`'s
 * `runCli` supplies `EXIT_OK` once, after this Effect succeeds.
 */
-const dispatchVoidCommand = (command, json, sh, out) => {
+const dispatchVoidCommand = (command, json, out) => {
 	switch (command.kind) {
 		case "lsp": return runLspCommand();
 		case "init": return runInitCommand(out);
@@ -207307,11 +207260,11 @@ const dispatchVoidCommand = (command, json, sh, out) => {
 		case "land": return runLandCommand({
 			...command.cost !== void 0 ? { cost: command.cost } : {},
 			...command.model !== void 0 ? { model: command.model } : {}
-		}, json, sh, out);
+		}, json, out);
 		case "entry": return runEntryCommand(command.actor, command.state, command.vars, out, command.label);
 		case "abandon": return runAbandonCommand(out);
 		case "restore": return runRestoreCommand(out);
-		case "next": return runNextCommand(json, sh, out);
+		case "next": return runNextCommand(json, out);
 		case "validate": return runValidateCommand(out);
 		case "check": return runCheckCommand(command.mode, command.file, command.openQuestions ?? false);
 		case "install": return runInstallCommand(out);
@@ -207326,14 +207279,20 @@ const dispatchVoidCommand = (command, json, sh, out) => {
 * (the `standaloneKinds` run bare). Both guard checks run before `dispatch`,
 * so a refusal writes nothing and emits no script by construction.
 */
-const runCommand = (command, json, sh, out) => {
-	const dispatch = dispatchVoidCommand(command, json, sh, out);
+const runCommand = (command, json, out) => {
+	const dispatch = dispatchVoidCommand(command, json, out);
 	if (needsOf(command.kind) !== "state") return dispatch;
 	return gen(function* () {
 		const git = yield* GitService;
 		const fs = yield* FileSystem;
 		yield* assertRunningFromRepoRoot(git, fs);
 		yield* assertRepositoryHasCommits(git);
+		const narrator = yield* Narrator;
+		const config = yield* (yield* ConfigService).load.pipe(provideService(Narrator, {
+			narrate: () => _void,
+			warn: () => _void
+		}));
+		for (const warning of config.warnings) yield* narrator.warn(`gtd: warning: ${warning}`);
 		yield* dispatch;
 	});
 };
@@ -207348,29 +207307,24 @@ const nonNegativeNumber = (raw, flag) => {
 const FLAGS = [
 	{
 		name: "--json",
-		arity: 0,
+		arity: "optional",
 		repeatable: false,
 		scope: (kind) => kind === "next" || kind === "land",
-		decode: () => right(true),
+		decode: ([raw]) => right(raw ?? ""),
 		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
-		valueHint: "",
-		help: ["(gtd next/gtd land only) output structured JSON", "instead of plain text. Mutually exclusive with --sh"],
-		conflicts: ["--sh"]
-	},
-	{
-		name: "--sh",
-		arity: 0,
-		repeatable: false,
-		scope: (kind) => kind === "next" || kind === "land",
-		decode: () => right(true),
-		scopeError: "gtd: --sh is only valid for `gtd next`/`gtd land` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
-		valueHint: "",
+		valueHint: "<path>",
 		help: [
-			"(gtd next/gtd land only) output gtd_-prefixed POSIX",
-			"shell assignments instead of plain text. Mutually",
-			"exclusive with --json"
-		],
-		conflicts: ["--json"]
+			"(gtd next/gtd land only) output structured JSON. Bare",
+			"--json prints the whole document; --json=<path> (a dotted",
+			"key path into that document, e.g. kind, content,",
+			"session.id) prints just that value: a scalar raw and",
+			"unquoted, a boolean as true/false, a list one JSON entry",
+			"per line. An absent optional field prints nothing and",
+			"exits 0 — including when an earlier segment of <path> is",
+			"itself absent/null (e.g. session.id at a non-prompt rest),",
+			"which never counts as unknown; an unknown path is a usage",
+			"error (exit 2)."
+		]
 	},
 	{
 		name: "--port",
@@ -207526,13 +207480,15 @@ const COMMAND_ROWS = [
 			"--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). Plain (the default) prints ONLY the",
-			"script that records the landing; a driver runs it, e.g.",
-			"`gtd land | sh`. --json/--sh instead emit script (that",
-			"same script, byte-identical) alongside settled, idle,",
-			"state (the post-land target), subject, cost and model —",
-			"--json/--sh are mutually exclusive. Exits 0 on success, 1",
-			"on any refusal — see the Exit codes section below"
+			"processCostByModel). Plain (the default) prints one",
+			"human-readable sentence naming the commit subject (or a",
+			"no-op note) plus a pointer to `gtd land --json=script | sh`",
+			"to get the landing script — never the script itself.",
+			"--json emits script (the actual POSIX sh",
+			"a driver runs) alongside settled, idle, state (the",
+			"post-land target), subject, cost and model. Exits 0 on",
+			"success, 1 on any refusal — see the Exit codes section",
+			"below"
 		]
 	},
 	{
@@ -207566,19 +207522,22 @@ const COMMAND_ROWS = [
 		details: [
 			"Print the resolved rest's beat (no mutation, safe to",
 			"poll), in one of three encodings. Plain (the default): a",
-			"status summary, a blank line, then the step verbatim —",
-			"except at a prompt rest, which is the bare step (plus the",
-			"self-validation instruction when applicable) with no",
-			"header, since those bytes are the agent's own input. --json",
-			"emits the one structured surface gtd has: kind",
-			"(capture|message|script|prompt|stalled) selects what a",
-			"driver does, content is what it runs or shows, idle marks",
-			"the workflow's initial state with a clean tree, plus the",
-			"prompt session, model, validate script, log path, changes,",
-			"next and the resting state's own fields. --sh emits the",
-			"same fields as gtd_-prefixed POSIX shell assignments.",
-			"--json/--sh are mutually exclusive. Exits 0 — see the",
-			"Exit codes section below"
+			"status summary, a blank line, then the step verbatim — at a",
+			"script/capture rest an instruction line ('Run this",
+			"script:' / 'The edit is already made — run `gtd land` to",
+			"land it.') precedes the status summary; at a prompt rest",
+			"it's the bare step (plus the self-validation instruction",
+			"when applicable) with no header at all, since those bytes",
+			"are the agent's own input. --json emits the one structured",
+			"surface gtd has: kind (capture|message|script|prompt|",
+			"stalled) selects what a driver does, content is what it",
+			"runs or shows, idle marks the workflow's initial state with",
+			"a clean tree, plus the prompt session, model, validate",
+			"script, log path, changes, next and the resting state's own",
+			"fields. --json=<path> (a dotted key path into that same",
+			"document, e.g. kind, content, session.id) prints just that",
+			"value instead of the whole document — see --json's own help",
+			"above. Exits 0 — see the Exit codes section below"
 		]
 	},
 	{
@@ -207737,6 +207696,7 @@ const tokenize = (tail) => {
 			jsonSeen
 		};
 		const eq = tok.indexOf("=");
+		const alreadyPresent = present.has(row.name);
 		present.add(row.name);
 		if (row.name === "--json") jsonSeen = true;
 		if (row.arity === 0) {
@@ -207748,6 +207708,25 @@ const tokenize = (tail) => {
 			if (!byFlag.has(row.name)) byFlag.set(row.name, []);
 			continue;
 		}
+		if (row.arity === "optional") {
+			if (!row.repeatable && alreadyPresent) return {
+				kind: "error",
+				message: `gtd: ${row.name} may be given at most once`,
+				jsonSeen
+			};
+			if (eq !== -1) {
+				const value = tok.slice(eq + 1);
+				if (value === "") return {
+					kind: "error",
+					message: `gtd: ${row.name} requires a value — use ${row.name}=${row.valueHint}`,
+					jsonSeen
+				};
+				byFlag.set(row.name, [value]);
+				continue;
+			}
+			if (!byFlag.has(row.name)) byFlag.set(row.name, []);
+			continue;
+		}
 		let raw;
 		if (eq !== -1) raw = tok.slice(eq + 1);
 		else {
@@ -207812,6 +207791,7 @@ const decodeFlags = (byFlag) => {
 	for (const row of FLAGS) {
 		const raws = byFlag.get(row.name);
 		if (raws === void 0) continue;
+		if (row.arity === "optional" && raws.length === 0) continue;
 		const decoded = row.decode(raws);
 		if (isLeft(decoded)) return left(decoded.left);
 		bag[row.name] = decoded.right;
@@ -207875,16 +207855,17 @@ const parseArgv = (argv) => {
 	const decoded = decodeFlags(byFlag);
 	if (isLeft(decoded)) return usagePlan(decoded.left, jsonSeen);
 	const bag = decoded.right;
-	const json = present.has("--json");
-	const sh = present.has("--sh");
+	const json = !present.has("--json") ? { kind: "off" } : bag["--json"] !== void 0 ? {
+		kind: "select",
+		path: bag["--json"]
+	} : { kind: "document" };
 	const verbose = present.has("--verbose");
 	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);
+		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", jsonSeen);
 		return {
 			kind: "command",
 			command: buildLandCommand(bag),
 			json,
-			sh,
 			verbose
 		};
 	}
@@ -207900,7 +207881,6 @@ const parseArgv = (argv) => {
 				label
 			},
 			json,
-			sh,
 			verbose
 		};
 	}
@@ -207912,7 +207892,6 @@ const parseArgv = (argv) => {
 			open: !(bag["--no-open"] ?? false)
 		},
 		json,
-		sh,
 		verbose
 	};
 	if (kind === "check") return {
@@ -207924,14 +207903,12 @@ const parseArgv = (argv) => {
 			...bag["--open-questions"] !== void 0 ? { openQuestions: bag["--open-questions"] } : {}
 		},
 		json,
-		sh,
 		verbose
 	};
 	return {
 		kind: "command",
 		command: { kind },
 		json,
-		sh,
 		verbose
 	};
 };
@@ -207971,10 +207948,14 @@ const bufferedArtifactOut = (io) => {
 * The single envelope writer: `{state:"error",prompt}` on **stderr** under
 * `--json`, `renderFailure` on stderr always, exit `EXIT_RUNTIME_ERROR`.
 * stdout is never touched here — the command's `ArtifactOut` buffer was never
-* flushed, so a `--json` driver piping stdout into `jq` on a failed run must
-* read stderr or the exit code instead. `Effect.sandbox` means this also
-* fires for a DEFECT, not just a typed error. Never reached for a USAGE
-* error — those never build a layer at all.
+* flushed, so a `--json` driver reading stdout on a failed run reads nothing
+* — it must read stderr or the exit code instead. `Effect.sandbox` means this also
+* fires for a DEFECT, not just a typed error. Unreached by an ordinary usage
+* error (an unknown flag, bad arity, a scope violation) — those never build a
+* layer at all. The one exception is `SelectorUsageError`: an unknown
+* `--json=<path>` selector can only be judged after the layer is built and
+* the fields object it's reduced against is fully resolved, so it fails HERE
+* rather than in `parseArgv` — `EXIT_USAGE_ERROR` still applies to it below.
 */
 const report = (io, json) => (cause) => sync$1(() => {
 	const error = squash(cause);
@@ -207986,7 +207967,7 @@ const report = (io, json) => (cause) => sync$1(() => {
 		})}\n`);
 	}
 	io.stderr(`${renderFailure(error)}\n`);
-	io.exit(1);
+	io.exit(error instanceof SelectorUsageError ? 2 : 1);
 });
 const runCli = (argv, io) => {
 	const plan = parseArgv(argv);
@@ -208001,10 +207982,10 @@ const runCli = (argv, io) => {
 		io.exit(2);
 	});
 	const out = bufferedArtifactOut(io);
-	return runCommand(plan.command, plan.json, plan.sh, out).pipe(map$4(() => {
+	return runCommand(plan.command, plan.json, out).pipe(map$4(() => {
 		out.flush();
 		io.exit(0);
-	}), provide$2(io.layers(plan.verbose)), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json)(cause)));
+	}), provide$2(io.layers(plan.verbose)), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json.kind !== "off")(cause)));
 };
 //#endregion
 //#region src/main.ts