@pmelab/gtd 9.6.0 → 9.8.0

package/README.md

@@ -90,28 +90,28 @@ The loop is one beat, repeated: run `gtd next --json` and dispatch on `kind` —
 opening beat, which the human triggered by re-running the driver: land that one,
 since changing nothing is itself a declared outcome at some gates); `"capture"`
 means a human gate the human already acted on (land it immediately); `"script"`
-means the driver runs `content` itself, then lands it; `"prompt"` means feed
-`content` to your agent — using the accompanying `session.id`/`session.resume`
-to continue or start that agent conversation (see "Driving the loop" below) —
-then run `gtd land` once it's done. gtd itself never executes anything — the
-driver owns running scripts. Every `gtd next` call is strictly mutation-free,
-safe to poll or peek at any time: `session.id`/`session.resume` are DERIVED,
-never stored, so looking is free — nothing distinguishes a peek from a dispatch,
-and there is no separate claiming form at all. A `prompt` beat whose turn
-changes nothing still lands: `gtd land` commits an EMPTY `gtd(<actor>): <state>`
-attempt instead of silently doing nothing, so the fruitless dispatch is visible
-in history rather than invisible. `"kind": "stalled"` is derived from that
-history — HEAD is an empty attempt at the resting state and the tree is clean —
-so every `gtd next --json` call reports it, and it stays reported on a repeat
-(there's no marker to consume) until something actually changes. The fix for a
-repeated stall is either a better prompt, a `retry:` cap on the state that
-redirects to an escalation state after N fruitless attempts, or — if the state
-can legitimately finish with nothing to change — declaring a `C` (clean-tree)
-pattern on it.
+means the driver runs `gtd next`'s own plain-text output itself, then lands it;
+`"prompt"` means feed `gtd next`'s output to your agent — using the accompanying
+`session.id`/`session.resume` fields off `gtd next --json` to continue or start
+that agent conversation (see "Driving the loop" below) — then run `gtd land`
+once it's done. gtd itself never executes anything — the driver owns running
+scripts. Every `gtd next` call is strictly mutation-free, safe to poll or peek
+at any time: `session.id`/`session.resume` are DERIVED, never stored, so looking
+is free — nothing distinguishes a peek from a dispatch, and there is no separate
+claiming form at all. A `prompt` beat whose turn changes nothing still lands:
+`gtd land` commits an EMPTY `gtd(<actor>): <state>` attempt instead of silently
+doing nothing, so the fruitless dispatch is visible in history rather than
+invisible. `"kind": "stalled"` is derived from that history — HEAD is an empty
+attempt at the resting state and the tree is clean — so every `gtd next --json`
+call reports it, and it stays reported on a repeat (there's no marker to
+consume) until something actually changes. The fix for a repeated stall is
+either a better prompt, a `retry:` cap on the state that redirects to an
+escalation state after N fruitless attempts, or — if the state can legitimately
+finish with nothing to change — declaring a `C` (clean-tree) pattern on it.
 
 An `on` edge may also carry a short imperative `action` (e.g. `Accept plan`)
 alongside its existing `describe` sentence — a human-facing name for the choice
-itself, not just the underlying glob pattern. `gtd status` (plain and `--json`)
+itself, not just the underlying glob pattern. `gtd next` (plain and `--json`)
 and `gtd visualize`'s diagram and inspector all render the two composed
 together: the `action` leads when the edge declares one, with the raw pattern
 (and `describe`) still shown alongside it, so a human choosing between routes
@@ -121,14 +121,14 @@ reads intent first, glob second.
 to the tree — a hand-edit to real code, a scratch note in some file, anything at
 all — as a sketch to be finished, never as work to be preserved: there is no
 fork on which steering file you happen to create, and `idle` has exactly one
-outgoing edge, into `unwind`. `.gtd/TODO.md` (the `todoFile` var) is a good
-default place to start sketching when you'd rather write a note than touch code
-— despite living beside the workflow's own state files, that sketch is your
-input for `design.triage` to fold in, never gtd bookkeeping to preserve or
-ignore. `unwind` reverts that whole diff back out of your working tree
-(`git revert --no-commit` against the commit it just landed in) before planning
-ever starts — your tree is back to exactly what it was, and your intent doesn't
-disappear, it survives in history for `design.triage` to read.
+outgoing edge, into `unwind`. `.gtd/TODO.md` is a good default place to start
+sketching when you'd rather write a note than touch code — despite living beside
+the workflow's own state files, that sketch is your input for `design.triage` to
+fold in, never gtd bookkeeping to preserve or ignore. `unwind` reverts that
+whole diff back out of your working tree (`git revert --no-commit` against the
+commit it just landed in) before planning ever starts — your tree is back to
+exactly what it was, and your intent doesn't disappear, it survives in history
+for `design.triage` to read.
 
 From there, `start-gate.check` runs your test suite on the tree as it now stands
 — which, thanks to the unwind, is simply your repo's own baseline. The rule is
@@ -222,14 +222,8 @@ rather than sitting beside it) — an actionable round leaves that identity
 entirely, so it starts a fresh session like any other process. A comment is what
 asks for changes; landing with no comment signs off, whatever the boxes say,
 which collapses the whole process into one commit (a **squash finale** whose
-message an agent drafts). Deleting `.gtd/REVIEW.md` is refused, wherever the
-review doc lives: repointing `reviewFile` out of `.gtd/` (say to `REVIEW.md` at
-the repo root) changes nothing about that refusal, since it only asks whether
-the step's diff deletes the file. The exact-path exemption issue #128 fixed
-still matters elsewhere, though: the `deciding` state's own classification and
-the feedback-progress guard both exclude the state's own `file:` by exact path,
-not merely a `.gtd/` prefix, so your own edit to a relocated steering file is
-never mistaken for a code comment.
+message an agent drafts). Deleting `.gtd/REVIEW.md` is refused — the guard only
+asks whether the step's diff deletes the file.
 
 A second entry, the same review tail's own direct entry point —
 `gtd --entry review-gate.check --var reviewBase=<commitish>` starts a brand new
@@ -262,27 +256,9 @@ to target a state.
 Every agent state routes its model through two `vars` tiers — `plannerModel`
 (heavier planning and review) and `coderModel` (the coding turns) — so you can
 repoint the models globally in one place (a `vars:` edit or a `GTD_PLANNERMODEL`
-override) instead of per state. Steering-file path vars (`todoFile`,
-`feedbackFile`, `reviewFile`, …) work the same way, and propagate to the `on`
-patterns that route on them too — a repointed path var actually reroutes the
-machine, not just the templates that read/write the file. `todoFile` (default
-`.gtd/TODO.md`, `idle`'s own `file:` hint) is the one exception: it's the only
-per-file var gtd never writes and never reads, since it names your own sketch
-pad, not a file any state produces. A separate `stateDir` var (default `.gtd`)
-names only where the check scripts keep their own scratch/bookkeeping,
-independent of the per-file vars — relocate one steering file without touching
-it. The workflow declares its plumbing directory once, at the top level of the
-`workflow:` value (`stateDir: <%= it.vars.stateDir %>` in the bundled template),
-rendered from that same `stateDir` var — this is what the engine itself reads to
-tell gtd's own bookkeeping apart from your code (e.g. the review window's revert
-pathspec, the step guards' code-vs-plumbing check), not just a value the
-templates happen to share. The rendered value is constrained: it must name a
-directory inside the repository — not the repo root, not an absolute path, and
-not a path that escapes the repository via `..` — and it must be spelled
-canonically: no `.` and no empty path segments (`a/./state` or `a//state` are
-rejected, not rewritten), though a leading `./` and a trailing `/` are accepted
-— or the next `gtd next`/`gtd status`/`gtd land` fails loudly with that message,
-rather than silently excluding the whole tree from the review window's revert.
+override) instead of per state. Every steering file the bundled workflow reads
+or writes lives at a fixed path under `.gtd/`; `testCommand`, `plannerModel`,
+`coderModel`, and `reviewBase` are the only vars left to tune.
 
 To inspect or change the machine itself, see [Configuration](#configuration) —
 the workflow is just `.gtdrc` config.
@@ -301,18 +277,19 @@ Commands:
                    Takes no argument. Run once per repo; refuses if a gtd
                    config already exists. Leaves the file uncommitted for you
                    to review and commit
-  land             Land whatever the tree now shows at the currently
-                   resolved rest — a human capture, an agent/check turn, an
-                   empty attempt (a fruitless prompt turn), or a squash — and
-                   print the script that records it; a driver runs the
-                   script, e.g. `gtd land | bash`. Pass --cost=<n>
-                   (optionally --model=<name>) to record the just-finished
-                   invocation's token cost and model on the turn commit
-                   (summed into it.processCost/processCostByModel). Exits 0
-                   when a script is emitted (or a benign no-op at a clean
-                   message rest), 3 when SETTLED — nothing owed: a no-op at a
-                   script rest, or the initial-state collapse (stdout still
-                   carries the script) — 1 on any refusal
+  land             Land whatever the tree now shows at the currently resolved
+                   rest — a human capture, an agent/check turn, an empty
+                   attempt (a fruitless prompt turn), or a squash. Pass
+                   --cost=<n> (optionally --model=<name>) to record the
+                   just-finished invocation's token cost and model on the
+                   turn commit (summed into it.processCost/
+                   processCostByModel). 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
   (no command) --entry <state>
                    Starts a new process authenticated as human, e.g.
                    'gtd --entry <state>'
@@ -327,29 +304,35 @@ Commands:
                    Refuses on a dirty working tree, when there is no retained
                    history, or when HEAD has advanced past the squash with
                    commits that would be lost
-  next             Print the resolved rest's rendered script/prompt/message
-                   (no mutation, safe to poll). --json emits the whole beat
-                   document instead: kind (capture|message|script|prompt|
-                   stalled) selects what a driver does, content is what it
-                   runs or shows, plus the prompt session, model, validate
-                   script, log path and the resting state's own fields
-  status           Print the resolved rest's state/actor and which declared
-                   pattern (if any) each pending change matches (no mutation)
+  next             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
   validate         Print the script that formats (when declared) then
                    validates the resolved rest's steering file, using its
                    mode's commands (its file:/mode:), instead of running it —
                    a driver runs the script and reads the findings from its
-                   own exit code/output. Always exits 0; --json emits
-                   {state, file?, mode?, script} (script is "" when there is
-                   nothing to validate; plain text prints "nothing to
-                   validate" in that case). On a non-zero validate exit
-                   the emitted script prints a ready-to-send fix prompt
-                   (instruction + findings) and exits with the
-                   validator's own code
+                   own exit code/output. Always exits 0; prints "nothing to
+                   validate" when the resolved rest declares nothing to run.
+                   On a non-zero validate exit the emitted script prints a
+                   ready-to-send fix prompt (instruction + findings) and
+                   exits with the validator's own code
   lsp              Start the LSP server for .gtd/ steering files (stdio)
   visualize        Serve an interactive diagram of the active workflow on a
-                   local web server (--port <n>, --no-open; --json prints the
-                   model and exits)
+                   local web server (--port <n>, --no-open). Prints the
+                   chosen port on its own line — with --port 0, this is the
+                   only way to learn which port was picked
   check <mode> <file>
                    Read <file> and run the built-in steering format named
                    <mode> (see `gtd validate`'s modes: qa, review) over its
@@ -370,7 +353,11 @@ Commands:
   help             Print this help and exit
 
 Options:
-  --json           Output structured JSON instead of plain text
+  --json           (gtd next/gtd land only) output structured JSON
+                   instead of plain text. Mutually exclusive with --sh
+  --sh             (gtd next/gtd land only) output gtd_-prefixed POSIX
+                   shell assignments instead of plain text. Mutually
+                   exclusive with --json
   --port=<n>       (gtd visualize only) port to serve on (default: a free port)
   --no-open        (gtd visualize only) do not open the browser
   --cost=<n>       (gtd land only) record the invocation's token cost
@@ -386,23 +373,73 @@ Options:
                    instead run the qa open-questions predicate over <file>,
                    printing each unanswered question one per line and exiting
                    non-zero when any remain
-  --version, -v    Print version and exit
+  --verbose        enable stderr narration for this invocation: which rest
+                   resolved, which declared pattern each pending change
+                   matched, which review-window action was emitted, and how
+                   config resolved across layers. Aliased to -v
+  --version, -V    Print version and exit
   --help, -h       Print this help and exit
 ```
 
-`--version` (`-v`) / `gtd version` and `--help` (`-h`) / `gtd help`
+### Plain output is not a parsing surface
+
+`gtd next`'s plain encoding is for a human, or a driver that merely displays it
+— never for scraping. Parsing lives in `--json`/`--sh`, both of which read from
+the exact same field set (`gtd install`'s briefing has the full reference);
+anything that greps, cuts, or `awk`s plain text is unsupported, and its shape
+may change across releases with no warning.
+
+### Exit codes
+
+Closed at five numbers, five meanings — a new command never grows this table;
+whose turn is next lives in `gtd next --json`'s own `kind` field instead.
+
+| Code      | Meaning          |
+| --------- | ---------------- |
+| 0         | success          |
+| 1         | runtime error    |
+| 2         | usage error      |
+| 130 / 143 | SIGINT / SIGTERM |
+
+Every command follows this table uniformly, `next`/`land` included: `0` on
+success, `1` on refusal, `2` on usage error, `130`/`143` when gtd itself dies by
+that signal — a parent's `wait` sees a real signal death (`WIFSIGNALED`), not a
+chosen exit code that merely reuses the same number. No command's exit code
+carries a second meaning.
+
+**Migration — read this even if you already migrated for a prior release.** This
+is the second inversion in as many releases, folded into one note rather than
+two to compose in your head: `10`/`20` (whose turn was next) are gone — every
+command exits `0`/`1`/`2` uniformly now; `gtd status` is gone (folded into
+`gtd next`); and plain `gtd next` now prints a status header at every kind
+EXCEPT `prompt` — agent input is untouched, since plain `gtd next` at a `prompt`
+rest is byte-identical to before. A driver must read whose turn is next off
+`gtd next --json`'s own `kind` field
+(`capture`/`message`/`script`/`prompt`/`stalled`) — never off gtd's exit code,
+which no longer carries that signal at all.
+
+Every usage mistake — an unknown option or command, missing/extra arguments, a
+scope violation (e.g. `--cost` on a command other than `gtd land`), a bad flag
+value — is a USAGE error (`2`), never a runtime error (`1`): nothing was even
+attempted. `--help`/`--version` still exit `0`.
+
+`--version` (`-V`) / `gtd version` and `--help` (`-h`) / `gtd help`
 short-circuit before any git or repository-state work — they run outside a repo
-and in any repo state. Bare `gtd` (no subcommand) and `gtd loop` are both usage
-errors that exit 1 and print help — gtd decides and prints, full stop; driving a
-loop is a driver's job, not a bundled command (see
-[Driving the loop](#driving-the-loop) below). Any other, truly unknown
-subcommand is likewise a usage error: it prints the help text and exits 1
-without touching the repository. The state commands (`land`, `--entry`,
-`abandon`, `restore`, `next`, `status`, `validate`) must run from the
-**repository root** — gtd derives the workflow, pending changes, and process
-history relative to cwd, so they refuse with a clear error from a subdirectory;
-`lsp`, `init`, `visualize`, `check`, and `install` are standalone and run from
-anywhere (see each command's own help entry).
+and in any repo state, and print to **stdout** at exit 0. `--verbose` (`-v`) is
+not a short-circuit — it gates narration for whatever command follows (see
+[Narration and remediation](#narration-and-remediation) below). Bare `gtd` (no
+subcommand) is a usage error that exits 2 — gtd decides and prints, full stop;
+driving a loop is a driver's job, not a bundled command (see
+[Driving the loop](#driving-the-loop) below) — printing its help text to
+**stderr**, not stdout: stdout stays byte-empty on every failure, a usage error
+included (see [Error envelope](#error-envelope) below). Any other, truly unknown
+subcommand is likewise a usage error exiting 2 without touching the repository.
+The state commands (`land`, `--entry`, `abandon`, `restore`, `next`, `status`,
+`validate`) must run from the **repository root** — gtd derives the workflow,
+pending changes, and process history relative to cwd, so they refuse with a
+clear error from a subdirectory; `lsp`, `init`, `visualize`, `check`, and
+`install` are standalone and run from anywhere (see each command's own help
+entry).
 
 `--json`, `--cost=<n>`, `--model=<name>` (the latter two only for `gtd land`),
 `--entry <state>` (no other command at all), and `--var <name>=<value>` (with
@@ -418,7 +455,7 @@ command are all usage errors too — landing and entering are different verbs, s
 `--model`, `--model` without `--cost`, or `--cost`/`--model` on any command
 other than `gtd land` are all usage errors.
 
-### `gtd status`'s `Next:`/`next`
+### `gtd next`'s `Next:`/`next`
 
 Both plain and `--json` output include a headline preview of what would happen
 next: the first declared `on` edge whose pattern matches the pending changes AS
@@ -435,23 +472,68 @@ real `gtd land` lands.
 
 ### Error envelope
 
-Every command, in `--json` mode, reports a failure as a machine-readable
-envelope on **stdout**, and still exits 1:
+**stdout is either the complete artifact or byte-empty — never a partial write
+followed by an error.** Every command buffers everything it would print and
+flushes that buffer to stdout exactly once, only after it succeeds; on any
+failure the buffer is simply discarded, so stdout never carries a half-written
+prompt/script alongside a message about why it stopped. `gtd visualize` is the
+one exception worth knowing: it flushes its served-URL line immediately, before
+blocking on `Ctrl-C`, since a flush-on-success would never otherwise fire.
+
+Any invocation that carries `--json` (valid only for `gtd next`/`gtd land` —
+every other command usage-errors on it) reports a failure as a machine-readable
+envelope on **stderr** — including the scope violation itself, so a driver that
+always adds `--json` still gets a parseable envelope on every failure, not only
+`gtd next`'s/`gtd land`'s own:
 
 ```json
 { "state": "error", "prompt": "<message>" }
 ```
 
-This covers every failure mode, not just a command's own refusal: a **usage
-error** (an unknown flag, a missing argument, `gtd --entry version`'s "not an
-enterable state") and a **defect** (a layer throwing outside the ordinary error
-channel) both get the same envelope — there is no failure path that reaches
-`--json` without one.
-
-A human-readable `gtd: <message>` line is still written to **stderr** regardless
-of `--json` — the envelope adds a structured stdout channel, it does not replace
-the plain-text one. Stderr always carries exactly one `gtd: ` prefix: a message
-already authored with its own `gtd:`/`gtd <cmd>:` prefix is never doubled.
+This covers every failure mode, not just a command's own refusal (exit 1): a
+**usage error** (an unknown flag, a missing argument, `gtd --entry version`'s
+"not an enterable state" — exit 2) and a **defect** (a layer throwing outside
+the ordinary error channel — exit 1) both get the same envelope shape — there is
+no failure path that reaches `--json` without one — but a usage error's exit
+code is 2, never 1, so a driver can tell "you invoked gtd wrong" apart from "gtd
+refused/broke" (see [Exit codes](#exit-codes)).
+
+A human-readable `gtd: <message>` line is also always written to **stderr**,
+right after the envelope — stdout carries neither one on a failing run. Stderr
+always carries exactly one `gtd: ` prefix: a message already authored with its
+own `gtd:`/`gtd <cmd>:` prefix is never doubled.
+
+**Accepted cost:** a driver that pipes stdout into `jq` on a failed run now
+reads nothing instead of a parseable error object — it must read stderr or the
+exit code to learn why a run failed.
+
+### Narration and remediation
+
+Stderr carries two things beyond the `gtd: ` message line above: NARRATION,
+gated by `--verbose`/`-v`, and REMEDIATION, unconditional.
+
+`--verbose` (alias `-v`) turns on one line of commentary per in-process fact a
+command's dispatch already computes — which rest resolved, which declared
+pattern each pending change matched, which review-window action was emitted, and
+how config resolved across `.gtdrc` layers. Without it, none of this is printed;
+stdout is never touched either way — narration is a stderr-only concern, exactly
+like the error envelope above.
+
+A failure's remediation detail is unconditional — it prints at every verbosity,
+on the line(s) right after the `gtd: `-prefixed message, each indented two
+spaces: a bad config key names the offending key and which `.gtdrc` layer it
+came from, a corrupted ref names the ref, and a missing binary in a steering
+mode's `format:`/`validate:` command names the resolved `$PATH` it was looked up
+in.
+
+### Non-interactive today
+
+gtd is non-interactive: no readline, no `/dev/tty`, no prompt call anywhere in
+`src/`. If interaction is ever added, it goes to `/dev/tty`, never stderr, and
+never blocks — a question fails with a code when the tty cannot be opened rather
+than hanging. The reason is the section above: stderr already has two occupants,
+narration and remediation, and a question mixed into that stream would deadlock
+a driver that never reads stderr.
 
 ## Driving the loop
 
@@ -485,38 +567,62 @@ not of the loop itself; see
 below for a worked example.
 
 A workflow state can declare an optional `label:` — a human-readable display
-name surfaced in `gtd next --json`/`gtd status`. The driver uses it for its
+name surfaced in `gtd next --json`/plain `gtd next`. The driver uses it for its
 per-beat progress lines; an outer wrapper (a terminal multiplexer, a notifier)
 can use it the same way.
 
+A machine may also declare `system:` — like `model:`, stamped once at the
+machine level onto every one of that machine's own `prompt` states, never
+authored on an individual state. It is passed to the agent CLI as (in the
+reference driver's case) `--system-prompt`, which **replaces** the harness's own
+default system prompt outright rather than appending to it (contrast with an
+`--append-system-prompt`-shaped flag) — so a machine declaring `system:` loses
+not only the harness's own tool-use instructions but also its dynamic per-turn
+sections: current working directory, environment info, memory-path information,
+git status. A workflow author reaching for `system:` for the first time is
+therefore writing a complete replacement system prompt, not a tweak on top of
+the harness's own. The scoping is machine-level for the same reason memory is
+machine-scoped below: a machine is the unit of conversational identity, so its
+system prompt — like its model tier — is one property of that identity, constant
+across every turn of the one resumed session, never a per-state override. Like
+`model:`/`file:`, a `system:` value prefixed `./` or `../` is inlined from the
+declaring config file's own directory at compile time — for a user's own
+`.gtdrc` `workflow:` config only; the bundled template ships no filesystem
+references at all, since it has to work inside a single-file build. The bundled
+default template ships six such personas already, one per prompt-bearing machine
+— `designPersona`, `architectPersona`, `reviewerPersona`, `specReviewerPersona`,
+`builderPersona`, `finisherPersona` — and, like any other bundled var, each is
+overridable through a top-level `.gtdrc` `vars:` key or a `GTD_<NAME>`-style
+environment variable (e.g. `GTD_DESIGNPERSONA`) — gtd's existing, generic
+vars-override mechanism, nothing new.
+
 Memory is **entry-scoped to a machine**, not a state-authored label: each
 machine instance (a node in the `machines:` tree, e.g. `build`, `build.health`,
 `packages.item`, `packages.item.health`) owns its own conversational scope, and
-a `prompt`-content state's `memory` key — surfaced in `gtd next --json`/
-`gtd status --json`'s `memory` field, and as a `Memory: <key>` line in plain
-`gtd status` — is computed, never authored, as `<scope>#<hash7>`: `<scope>` is
-that machine instance's dotted path (the root instance is shown as `root`), and
-`<hash7>` anchors to the commit the CURRENT unbroken entry into that scope
-started FROM. Entering a **descendant** scope (e.g. dipping from `build` into
-`build.health`) does not break the parent's unbroken run — a full agent turn in
-a nested child machine, then back to the parent, still resumes the SAME parent
-conversation; entering a **sibling or unrelated** scope does start a fresh one.
-The bundled template's `build.review` (the human review tail) is a worked
-example: it is nested INSIDE `build` (the builder's own machine) so that a
-`gtd --entry fix-precheck` run — `build.fix` -> `build.health.check` ->
-`build.review.*` -> `build.squashing` — stays inside one subtree, letting
-`build.squashing` resume the SAME session that made the fixes instead of a
-root-level sibling forcing it to re-derive the range from scratch on every pass
-through the tail. (An actionable review round breaks the run on purpose instead
-— it leaves `build` entirely through a root-level `re-unwind` state and a full
-re-plan, since a hand-edit made during review is a sketch to reconsider, not a
-fix to build on.) Two instances of the same reusable machine (e.g.
-`build.health` and `packages.item.health`, both instantiating `healthGate`) get
-different scopes and so never share a key, even though they're the "same shaped"
-machine. One consequence is a structural guarantee: **a reviewer's turn never
-resumes an implementer's session, and vice versa** — a reviewer machine and the
-implementer machine it reviews are always different instances with different
-scopes.
+a `prompt`-content state's `memory` key — surfaced in `gtd next --json`'s
+`memory` field, and as a `Memory: <key>` line in plain `gtd next` — is computed,
+never authored, as `<scope>#<hash7>`: `<scope>` is that machine instance's
+dotted path (the root instance is shown as `root`), and `<hash7>` anchors to the
+commit the CURRENT unbroken entry into that scope started FROM. Entering a
+**descendant** scope (e.g. dipping from `build` into `build.health`) does not
+break the parent's unbroken run — a full agent turn in a nested child machine,
+then back to the parent, still resumes the SAME parent conversation; entering a
+**sibling or unrelated** scope does start a fresh one. The bundled template's
+`build.review` (the human review tail) is a worked example: it is nested INSIDE
+`build` (the builder's own machine) so that a `gtd --entry fix-precheck` run —
+`build.fix` -> `build.health.check` -> `build.review.*` -> `build.squashing` —
+stays inside one subtree, letting `build.squashing` resume the SAME session that
+made the fixes instead of a root-level sibling forcing it to re-derive the range
+from scratch on every pass through the tail. (An actionable review round breaks
+the run on purpose instead — it leaves `build` entirely through a root-level
+`re-unwind` state and a full re-plan, since a hand-edit made during review is a
+sketch to reconsider, not a fix to build on.) Two instances of the same reusable
+machine (e.g. `build.health` and `packages.item.health`, both instantiating
+`healthGate`) get different scopes and so never share a key, even though they're
+the "same shaped" machine. One consequence is a structural guarantee: **a
+reviewer's turn never resumes an implementer's session, and vice versa** — a
+reviewer machine and the implementer machine it reviews are always different
+instances with different scopes.
 
 `gtd` itself stores NOTHING to make this work: `session.id` is
 `UUIDv5(<fixed gtd namespace>, <memory key>)` — a deterministic hash of the
@@ -550,7 +656,7 @@ reports `gtd`'s own lifecycle to that status without any herdr-specific
 knowledge in `gtd` itself: `working` while the loop drives, `blocked` when it
 comes to rest on a human (a gate, a stall, a non-zero exit), and `idle`
 (rendered as "done" once the pane's tab is unfocused) when a run ends without
-anything owed. It needs nothing from `gtd` beyond `gtd status --json`'s `.actor`
+anything owed. It needs nothing from `gtd` beyond `gtd next --sh`'s `gtd_actor`
 field — a strictly read-only orientation peek.
 
 Save this as `~/.local/bin/gtdh`, `chmod +x` it, and run `gtdh` in place of
@@ -560,8 +666,8 @@ Save this as `~/.local/bin/gtdh`, `chmod +x` it, and run `gtdh` in place of
 #!/usr/bin/env bash
 # Report gtd's own lifecycle to the herdr pane it runs in: working while the
 # loop drives, blocked when it rests on you, idle (shown as "done") otherwise.
-# Needs nothing from gtd but `gtd status --json`. Outside herdr it is a plain
-# passthrough. Requires `jq` — so does the README's minimal driver.
+# Needs nothing from gtd but `gtd next --sh`. Outside herdr it is a plain
+# passthrough.
 set -uo pipefail
 
 pane="${HERDR_PANE_ID:-}"
@@ -586,14 +692,16 @@ trap 'report blocked; exit 130' INT TERM
 env -u HERDR_PANE_ID gtd-loop
 rc=$?
 
-# Whose turn is it now? `gtd status --json` is a strictly read-only peek —
-# every gtd command is, including `gtd next --json` (its prompt session id is
-# derived, never minted/stored) — only the emitted scripts a driver runs
-# actually touch git. A human actor means gtd is waiting on you; anything else
-# means the run ended with nothing owed.
-actor="$(gtd status --json 2>/dev/null | jq -r '.actor // ""' 2>/dev/null || true)"
+# Whose turn is it now? `gtd next --sh` is a strictly read-only peek — every
+# gtd command is, including `gtd next` (its prompt session id is derived,
+# never minted/stored) — only the emitted scripts a driver runs actually
+# touch git. A human actor means gtd is waiting on you; anything else means
+# the run ended with nothing owed. Assign first, THEN eval — same reason as
+# the driver above.
+out="$(gtd next --sh 2>/dev/null)" || out=""
+eval "${out:-}" 2>/dev/null || true
 
-if [ "$rc" -ne 0 ] || [ -z "$actor" ] || [ "$actor" = human ]; then
+if [ "$rc" -ne 0 ] || [ -z "${gtd_actor:-}" ] || [ "$gtd_actor" = human ]; then
   report blocked
 else
   report idle
@@ -632,7 +740,7 @@ to build a driver without leaving your terminal. The briefing ends by directing
 the agent to INTERVIEW you first — which agent CLI runs the turns, under what
 permission model, how you want to invoke the loop, what should happen at a human
 gate — and to build the driver your answers describe rather than copying the
-reference bash. It writes nothing: "install" means installing knowledge into the
+reference sh. It writes nothing: "install" means installing knowledge into the
 calling agent's context, and the briefing it prints is always exactly as current
 as the `gtd` that printed it.
 
@@ -641,88 +749,109 @@ privileged one — the engine itself is a supported public surface, and anything
 below holds for any driver you write against it. gtd decides and prints; it
 never touches git itself. The four commands that change anything — `gtd land`,
 `gtd --entry <state>`, `gtd abandon`, and `gtd restore` — perform no git write
-when run. Instead, each one's output carries `required`/ `optional`: bash
-scripts for YOU to execute. Plain-text output (no `--json`) prints them combined
-into ONE pasteable script — `required` verbatim, then `optional` wrapped so its
-own failure can't turn a landed turn into a non-zero exit — so `gtd land | bash`
-is a complete, single-command way to land a turn. Under `--json`, each one's
-output object instead carries `required`/`optional` as two separate string
-fields (plus, for `gtd land`, the same two combined into `script`), for a driver
-that wants to run them apart (e.g. to skip `optional` outright). Either way,
-printing gtd's output and never running it is not driving anything; a driver
-must pipe or `jq`-and-execute what gtd prints.
-
-- **`required`** is everything that decides what lands in git — closing an open
-  review checkout window, the resting state's own steering-mode
+when run: each one prints ONE POSIX sh script for YOU to execute
+(`src/Emit.ts`'s `combinedScript`) — a leading comment ("gtd emitted this and
+did NOT run it — pipe it into `sh` to land the turn"), then the REQUIRED half
+verbatim, then, only when there's a presentation-only follow-up, a second
+comment ("presentation only — safe to skip") and the OPTIONAL half wrapped in a
+subshell whose own non-zero exit is swallowed (reported to stderr as a warning,
+never turning a landed turn into a failing one). Printing gtd's output and never
+running it is not driving anything; a driver must pipe or execute what gtd
+prints — e.g. the capture-then-pipe form the reference driver below uses — never
+a bare `gtd land | sh`, which would hand an empty script to a shell on a refusal
+instead of stopping first (see the reference driver's own use of `gtd land --sh`
+below).
+
+Every script gtd emits — `gtd land`, `gtd --entry <state>`, `gtd abandon`,
+`gtd restore`, and the format/validate script `gtd validate` prints — is POSIX
+`sh`, portable to `dash`: a driver may run any of them with any POSIX-compliant
+shell, not specifically bash. The same convention extends to the workflow's own
+`vars.testCommand` (what a `script`-content check state actually executes): it
+is expected to be POSIX sh-compatible too, but this is a DOCUMENTED CONVENTION
+only — gtd never inspects or validates `testCommand`'s shell dialect itself, it
+only renders the value into a script and hands it to whatever shell the driver
+invokes that script with.
+
+- **The required half** is everything that decides what lands in git — closing
+  an open review checkout window, the resting state's own steering-mode
   `format:`/`validate:` commands, the commit or squash itself (`gtd land` and
   `gtd --entry <state>`), or the ref update and reset that undo a process
   (`gtd abandon`, `gtd restore`) — and, last, a printed line naming what just
   landed (`src/OutcomeScript.ts`'s `gtd_report_*` calls): a transition or
   capture's changed-file rows, or the abandon/restore prose, resolved from the
-  repository AFTER the write above it. Run this one. Skipping it means the turn
-  never lands, and you never see what it did.
-- **`optional`** is presentation only: re-opening the review checkout window
-  (the `<<<<<<< HEAD` diff view) after `gtd land` lands at a
+  repository AFTER the write above it. Its own exit code IS the printed script's
+  exit code — skipping it means the turn never lands, and you never see what it
+  did.
+- **The optional half** is presentation only: re-opening the review checkout
+  window (the `<<<<<<< HEAD` diff view) after `gtd land` lands at a
   `reviewWindow: true` state, so an editor's diff view has something to show.
-  Skip it and you lose nothing but that view — the workflow is still driven
-  correctly. `gtd abandon`/`gtd restore` always emit `optional: ""` (there is no
-  window to reopen after either).
+  Its own failure is swallowed by the wrapping subshell (a warning on stderr,
+  nothing more) — skip it (or let it fail) and you lose nothing but that view,
+  the workflow is still driven correctly. `gtd abandon`/`gtd restore` never
+  carry one — there is no window to reopen after either, so their printed
+  artifact is the required half alone, with no trailing comment/subshell at all.
 
 `gtd next --json` carries one more field worth a custom driver's attention:
 
 - **`log`** — the per-worktree loop log path, always present. It's derived from
   the worktree's own git dir, so two worktrees looping concurrently never share
-  one file; set `$GTD_LOOP_LOG` to override it verbatim. gtd itself neither
-  creates nor truncates this file — a driver appends subprocess output to it and
-  truncates once at the start of a run, exactly like the driver above does.
-
-`optional` may be the empty string `""`, meaning "nothing to do here".
-`required` is never empty — even a genuine no-op `gtd land` (a clean tree
-matching no `on` pattern) emits a PRINT-ONLY script: no git write, just the same
-`nothing to do at "<state>"` line the script prints when a driver runs it (or,
-under plain text with no `--json`, when gtd prints the very same script back to
-you). Both scripts are self-contained (each carries its own precondition assert
-and retry helper) and safe to run standalone, in sequence, or not at all — paste
-either into a terminal and it does exactly what it says, printed output
-included: the scripts detect their own tty/`NO_COLOR` at RUN time (not at the
-moment gtd generated them), so the fancy/plain rendering always matches wherever
-you actually run them.
+  one file; set `$GTD_LOOP_LOG` to override it verbatim, or `$GIT_DIR` to name
+  the git dir directly (both honored the same way every git subprocess already
+  honors them — an inherited `$GIT_DIR` moves the log path along with it). gtd
+  itself neither creates nor truncates this file — a driver appends subprocess
+  output to it and truncates once at the start of a run, exactly like the driver
+  above does.
+
+Even a genuine no-op `gtd land` (a clean tree matching no `on` pattern) prints a
+PRINT-ONLY script: no git write, just the same `nothing to do at "<state>"` line
+the script prints when a driver runs it. Every encoding (plain, `--json`,
+`--sh`) carries that same script verbatim in its `script` field — running it is
+never optional, whichever encoding a driver reads it from. The script is
+self-contained (it carries its own precondition assert and retry helper) and
+safe to run standalone, in sequence, or not at all — paste it into a terminal
+and it does exactly what it says, printed output included: it detects its own
+tty/`NO_COLOR` at RUN time (not at the moment gtd generated it), so the
+fancy/plain rendering always matches wherever you actually run it.
 
 A driver has no opening move. It does not need to know whose turn it is before
-it starts — `gtd next --json` tells it, and a human's pending edit arrives as an
-ordinary `kind: "capture"` beat that the driver lands like any other. The rule
-this replaces: never `gtd land` outside a beat you dispatched. A stray land at a
-clean `prompt` rest authors an empty attempt on purpose (that IS the stall
-bookkeeping), so an unconditional opening land would manufacture a stall out of
-a fresh start.
-
-`gtd land`'s exit code IS the settled signal: 0 for an ordinary landing
-(capture, turn, attempt, squash, or a benign no-op at a clean `message` rest), 3
-for SETTLED, 1 for a refusal or usage error. SETTLED means nothing owed, for
-either of two terminal shapes — a no-op at a `script` rest (the check ran, left
-nothing any pattern claims, and re-running the same beat cannot change that), or
-a step whose decision rewinds the process back to the workflow's initial state
-retaining nothing (`gtd --entry fix-precheck` against a green suite is the
-shipped example — the probe collapses away rather than landing a round trip
-through the log). Either way a loop should exit rather than spin — with
-`set -o pipefail`, `gtd land | bash` propagates gtd's own exit code through the
-pipe, and `--json` carries the same fact as `settled: true`. A no-op at a
-`prompt` rest is NOT settled — an agent that was asked to act and produced
-nothing is a stall, a driver's own concern, not this signal's. Declaring a `C`
-edge on a `script` state is the workflow-side way to make the state advance
-instead of settling.
-
-### Drivers other than bash
-
-The protocol above is JSON in, subprocesses out — bash is one convenient shape,
-not the only one. A **program** parses `gtd next --json`, switches on `kind`,
-and runs `content`/`required`/`optional` as subprocesses — no bash anywhere in
-it. A **human** runs plain `gtd next` (no `--json`), does what it says, and
-pastes `gtd land | bash`: plain-text output exists for exactly this, printing
-`required` and `optional` already combined into one pasteable script. An
-**agent** gets `gtd install` as its instructions — the same protocol, in a form
-built to be pasted into a context window rather than read. A **CI job** is the
-program case with the `prompt` arm pointed at a headless agent CLI, and
+it starts — `gtd next --json`/`--sh` tells it, and a human's pending edit
+arrives as an ordinary `kind: "capture"` beat that the driver lands like any
+other. The rule this replaces: never `gtd land` outside a beat you dispatched. A
+stray land at a clean `prompt` rest authors an empty attempt on purpose (that IS
+the stall bookkeeping), so an unconditional opening land would manufacture a
+stall out of a fresh start. The one EXCEPTION is the run's very first beat: land
+it before trusting `idle` there too, so a workflow whose initial state declares
+its own clean-tree `"C"` pattern still gets a chance to advance on a human's
+bare re-invocation, rather than the driver concluding "nothing owed" without
+ever giving that edge a turn (see the reference driver's own comment on this).
+
+Exit code carries none of this any more — every command, `next`/`land` included,
+exits `0` on success (see [Exit codes](#exit-codes) above). Whose turn is next,
+and whether a landing settles, are both PLAIN FIELDS on `gtd next --json`/`--sh`
+and `gtd land --json`/`--sh`: `next`'s own `kind`
+(`capture`/`message`/`script`/`prompt`/`stalled`) and `idle`; `land`'s own
+`settled` and `idle`. `gtd land --sh` carries `settled`/`idle` alongside the
+script itself, so ONE invocation both runs the landing and tells the driver
+whether to stop — no second read needed to decide. A no-op at a `script` rest
+settles right where it rests (stop immediately, nothing more to read); an
+ordinary or squash landing that finishes the whole process instead resolves
+`idle` on the FOLLOWING `gtd next` — the reference driver below reads once more
+only to DISPLAY that gate's message, never to decide whether to stop. Declaring
+a `C` edge on a `script` state is the workflow-side way to make the state
+advance instead of settling.
+
+### Drivers other than sh
+
+The protocol above is JSON in (from `gtd next --json` alone), subprocesses out —
+sh is one convenient shape, not the only one. A **program** parses
+`gtd next --json`, switches on `kind`, and runs `gtd next`'s (plain-text) output
+and `gtd land`'s (POSIX sh) output as subprocesses — no sh anywhere in it. A
+**human** runs plain `gtd next` (there is no JSON form of it at all), does what
+it says, and pastes `gtd land | sh`: plain-text output exists for exactly this,
+printing the combined script ready to paste. An **agent** gets `gtd install` as
+its instructions — the same protocol, in a form built to be pasted into a
+context window rather than read. A **CI job** is the program case with the
+`prompt` arm pointed at a headless agent CLI, and
 `kind: "message"`/`kind: "stalled"` mapped onto "stop and report".
 
 ### A complete minimal driver
@@ -737,102 +866,173 @@ This exact fenced block is extracted and executed by
 `tests/integration/features/readme-driver.feature` — renaming the heading above
 or splitting the block into more than one fence breaks the build.
 
+**Pipe the prompt to the agent CLI on stdin — never pass it as a command-line
+argument.** A `prompt` beat's content embeds a full diff, and argv is capped:
+roughly 1 MB on macOS, and POSIX guarantees only 4 KB (`ARG_MAX`). Both are
+reachable by an ordinary diff, so a driver that passes the prompt as an argument
+works in testing and then fails on the first large change, in a way that looks
+like an agent error rather than a driver bug. The driver below pipes `$c`/`$out`
+into `claude -p` over stdin for exactly this reason.
+
 ```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# The bundle plans; this executes. Emitted scripts print their own outcomes.
-# Exit 3 means SETTLED — nothing owed — so this exits the whole driver at 0.
-gtd_land() {
-  local json code=0
-  json="$(gtd land --json)" || code=$?
-  [ "$code" = 0 ] || [ "$code" = 3 ] || return "$code"
-  bash -c "$(jq -r '.required // empty' <<<"$json")" || return $?
-  bash -c "$(jq -r '.optional // empty' <<<"$json")" ||
-    echo "warn: presentation follow-up failed — continuing" >&2
-  [ "$code" = 3 ] && exit 0
-  return 0
-}
+#!/usr/bin/env sh
+set -eu
 
 beat=1
 while :; do
-  next="$(gtd next --json)" || exit 1
-  kind="$(jq -r .kind <<<"$next")"
-  log="$(jq -r .log <<<"$next")"
-  case "$kind" in
-    stalled) jq -r .content <<<"$next" >&2; exit 1 ;;
+  # 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"
+
+  # `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
+  # clean-tree "C" pattern still gets a chance to fire.
+  if [ "$beat" -gt 1 ] && [ "${gtd_idle:-}" = true ]; then
+    gtd next
+    exit 0
+  fi
+
+  case "$gtd_kind" in
+    stalled) printf '%s\n' "$gtd_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 ] || { jq -r .content <<<"$next"; exit 0; } ;;
+    message) [ "$beat" = 1 ] || { gtd next; exit 0; } ;;
     capture) ;; # the human already acted — just land it
-    script) bash -c "$(jq -r .content <<<"$next")" >>"$log" 2>&1 || true ;;
+    script)
+      sh -c "$gtd_content" >>"$gtd_log" 2>&1 || true ;;
     prompt)
-      sid="$(jq -r '.session.id // empty' <<<"$next")"
-      c="$(jq -r .content <<<"$next")" model="$(jq -r '.model // empty' <<<"$next")"
-      agent_turn() { claude -p "$c" "$1" "$sid" ${model:+--model "$model"} \
-        --dangerously-skip-permissions >>"$log" 2>&1; }
-      if [ "$(jq -r '.session.resume // false' <<<"$next")" = true ]
+      # $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 ]
       then agent_turn --resume || agent_turn --session-id
       else agent_turn --session-id || agent_turn --resume
       fi
-      v="$(jq -r '.validate // empty' <<<"$next")" n=0
-      while [ -n "$v" ] && ! out="$(bash -c "$v" 2>&1)"; do
-        n=$((n + 1)) && [ "$n" -gt 3 ] && { printf '%s\n' "$out" >&2; exit 1; }
-        claude -p "$out" --resume "$sid" --dangerously-skip-permissions \
-          >>"$log" 2>&1 # $out IS the fix prompt, verbatim
+      n=0
+      while [ -n "${gtd_validate:-}" ] && ! fix="$(sh -c "$gtd_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
+        # 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 —
+        # 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
       done ;;
   esac
-  gtd_land || exit 1
+
+  # `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
+    exit 0
+  fi
   beat=$((beat + 1))
 done
 ```
 
-Line by line it is the protocol described above: no opening move at all — a
-human's pending edit arrives as the `capture` beat, and a stray `gtd land`
-outside a beat you acted on would author an empty attempt at a clean prompt rest
-on purpose; one `gtd next --json` beat document read per loop (`kind: "stalled"`
-guarding against a spinning agent); `message` halts unless it is the opening
-beat, which the human's own re-invocation authored and which therefore lands
-like any other decision (see [Driving the loop](#driving-the-loop) above — this
-is the one place the driver, not gtd, decides, because "has the human read this
-gate" is run-scoped knowledge gtd deliberately does not keep); `capture` lands a
-human's already-made edit outright, `script` runs in the driver, `prompt` goes
-to the agent with the document's own `session.id`/`session.resume` mapped onto
-the agent's session flags — trying `resume`'s hinted flag first and falling back
-to the other on failure, since `session.id` is derived, not remembered (see
-[Driving the loop](#driving-the-loop) above) — and its embedded `.validate`
+Line by line it is the protocol described above: `out="$(gtd next --sh)"` then
+`eval "$out"` is one invocation per beat — assigning first is what lets `set -e`
+abort correctly on a genuine failure, where `eval "$(gtd next --sh)"` would
+instead eval the empty string and die later on some unrelated unset variable;
+the driver carries no `unset` of its own, since the `--sh` document's own
+preamble makes `eval` self-contained. The very first beat lands even when
+`gtd_idle` is already true, so a workflow whose initial state declares its own
+clean-tree `"C"` pattern still gets a chance to fire before the driver calls it
+done. `kind: "stalled"` prints `$gtd_content` (the diagnosis itself) to stderr
+and stops — no re-invocation needed, since the beat already fetched it;
+`message` halts unless it is the opening beat, which the human's own
+re-invocation authored and which therefore lands like any other decision (see
+[Driving the loop](#driving-the-loop) above — this is the one place the driver,
+not gtd, decides, because "has the human read this gate" is run-scoped knowledge
+gtd deliberately does not keep); `capture` lands a human's already-made edit
+outright, no display needed; `script` runs `$gtd_content` in the driver;
+`prompt` sends it to the agent over stdin with
+`$gtd_session_id`/`$gtd_model`/`$gtd_system` mapped onto the agent's session
+flags — trying `resume`'s hinted flag first and falling back to the other on
+failure, since the session id is derived, not remembered (see
+[Driving the loop](#driving-the-loop) above) — and its own `$gtd_validate`
 script's output re-prompted verbatim on failure (the driver owns only the retry
-cap); and every landed turn executed — and reported — by the emitted scripts
-themselves, with `gtd land`'s exit 3 (SETTLED) ending a run that has nothing
-left to do.
+cap). Every optional variable (`$gtd_model`, `$gtd_system`, `$gtd_validate`,
+`$gtd_session_resume`, `$gtd_idle`, `$gtd_settled`) is read as `${var:-}` or
+`${var:+...}` — under `set -u`, the `--sh` document's own `unset` preamble makes
+an absent field genuinely unset, not empty, so a bare `$gtd_model` would abort
+the driver. Every landed turn is executed — and reported — by the emitted
+scripts themselves, via `gtd land --sh`'s own `$gtd_script` field, captured then
+piped to `sh`. `$gtd_settled` ends a run that has nothing left to do: a no-op at
+a `script` rest settles right where it rests (stop immediately, nothing more to
+read), while an ordinary or squash landing that finishes the whole process
+instead resolves `$gtd_idle` on the FOLLOWING beat's own `gtd next --sh` read —
+the reference driver reads once more (a plain `gtd next`) only to DISPLAY that
+gate's own message, the decision to stop already made from `$gtd_settled`/
+`$gtd_idle` alone.
+
+This paste passes `$gtd_system` on argv, and POSIX guarantees only 4 KB of argv
+(`ARG_MAX`) — real systems are far higher (roughly 1 MB on both macOS and
+Linux), and the bundled personas are only a few KB each, so this works
+everywhere in practice. A driver shipping much larger system prompts, or
+targeting a platform sitting at the POSIX floor, should write the string to a
+file and pass that instead: gtd's own contract ends at emitting `gtd_system` as
+a string, and how a driver hands that string to its agent CLI — argv, a temp
+file, or something else — is the driver's own call, since it alone knows its
+platform's argv limit and whether it has a writable temp directory; gtd adds no
+flag, no file, and no mechanism of its own for this. (The doc-test below only
+proves this paste parses and runs against a `claude` shim — not that the flag is
+spelled or placed correctly; that's a `claude --help` check plus one live run,
+not something the green suite can catch.)
 
 ### The self-validation gate
 
 After an agent turn at a state that declares `file:`+`mode:`, run the script:
 either `gtd next --json`'s own embedded `.validate` field (present at every
 `prompt` beat that hands over a validatable file), or, standalone,
-`gtd validate --json`'s `.script` — both resolve the exact same script from one
-shared resolver. Exit 0 means the file is well-formed — proceed to `gtd land`. A
-non-zero exit means the script's own captured output IS a complete,
-ready-to-send fix prompt (an instruction plus the findings, see `src/Emit.ts`'s
-`failurePromptWrapper`): send it back to the same agent session verbatim, and
-cap how many fix attempts you allow yourself — the driver owns that retry count,
-not gtd. Landing never TRUSTS that you validated, either: the emitted `land`
-script carries the same format/validate commands ahead of its own commit and
-fails without committing when they fail, so a malformed file is never captured
-whether or not you ran the validate script first.
+`gtd validate`'s own plain-text output — both resolve the exact same script from
+one shared resolver. Exit 0 means the file is well-formed — proceed to
+`gtd land`. A non-zero exit means the script's own captured output IS a
+complete, ready-to-send fix prompt (an instruction plus the findings, see
+`src/Emit.ts`'s `failurePromptWrapper`): send it back to the same agent session
+verbatim, and cap how many fix attempts you allow yourself — the driver owns
+that retry count, not gtd. Landing never TRUSTS that you validated, either: the
+emitted `land` script carries the same format/validate commands ahead of its own
+commit and fails without committing when they fail, so a malformed file is never
+captured whether or not you ran the validate script first.
 
 ### Failure taxonomy and recovery
 
-Two different things can go wrong, and they mean different things — and one
-non-zero-looking exit is not a failure at all:
+Several different things can go wrong, and they mean different things — and most
+non-zero-looking exits are not a failure at all:
 
 - **`gtd` itself exits 1.** Nothing was attempted — this is a refusal (a guard
-  rejected the turn) or a usage error. No script was ever produced.
-- **`gtd land` exits 3 (SETTLED).** This is NOT a failure: nothing is owed, and
-  stdout still carries a script (a print-only note, or a genuine retain+rewind)
-  that a driver must still run.
+  rejected the turn). No script was ever produced.
+- **`gtd` itself exits 2.** A usage error — nothing was even attempted, the
+  invocation itself was wrong (unknown option/command, bad arity, a scope
+  violation).
+- **`gtd land` succeeds (exit 0) but doesn't settle.** This is NOT a failure:
+  whose turn is next lives in the FOLLOWING `gtd next`'s own `kind` field, not
+  in `gtd land`'s exit code (see [Exit codes](#exit-codes)) — and `gtd land`'s
+  own stdout still carries a script (a print-only note, or a genuine
+  retain+rewind, or an ordinary commit) that a driver must still run.
 - **An emitted script exits non-zero when YOU run it.** Something may have
   partially happened — e.g. a `gtd_retry`-wrapped git write landed but a later
   step in the same script failed.
@@ -856,8 +1056,10 @@ its own retry/resume logic beyond "if the script failed, ask gtd again."
 
 ### Prerequisites
 
-- **`jq`** — to pull the `required`/`optional` strings back out of gtd's
-  `--json` output.
+- **A POSIX `sh`** (dash, ash, bash's own POSIX mode, etc.) — gtd's own emitted
+  scripts (`gtd land`, `gtd --entry <state>`, `gtd abandon`, `gtd restore`) are
+  POSIX sh; captured, then piped into it (see
+  [Writing your own driver](#writing-your-own-driver) above).
 - **`gtd` on `PATH`** — a mode's seeded `validate:` command (the one the
   compiler fills in for the built-in `qa`/`review` formats) is literally the
   string `gtd check <mode> '<file>'`, invoked by NAME from inside an emitted
@@ -896,7 +1098,7 @@ One case never runs your `format:` (or `validate:`) at all: a step whose diff
 DELETES the state's own `file:`. Deleting it is a legitimate outcome — a review
 sign-off's whole diff is the review doc's deletion — and there is nothing left
 to format. Emitting the command anyway would make such a step unlandable, since
-`format:` is the first line of a `set -euo pipefail` script and a formatter like
+`format:` is the first line of a `set -eu` script and a formatter like
 `prettier --write` exits non-zero on a path that is not there.
 
 ### Built-in steering formats are ordinary modes
@@ -977,7 +1179,6 @@ workflow:
     <name>:
       format: <shell command> # both optional — {} is the format-only tier
       validate: <shell command>
-  stateDir: <string> # optional, an Eta template naming where this workflow keeps its own plumbing (default ".gtd") — the definition-level declaration the engine reads, distinct from the `vars.stateDir` var the bundled template renders it from
   entry:
     default: <machine name> # which machine is the ROOT instance
   machines:
@@ -1002,8 +1203,8 @@ workflow:
           retry:
             max: <number>
             otherwise: <targetState>
-          label: <string> # optional, opaque display name passed through `gtd next --json`/`gtd status --json`
-          file: <string> # optional, an Eta template naming the state's steering file
+          label: <string> # optional, opaque display name passed through `gtd next --json`
+          file: <string> # optional, an Eta template naming the state's steering file RELATIVE to ".gtd/" — the compiler prepends that directory automatically
           mode: <modeName> # optional, requires "file" — must be declared in `modes:` (qa/review are seeded for you; everything else, including prose, you declare)
           reviewWindow: true # optional — open the review checkout window at rest here
           reviewBase: true # optional — anchor the review window's diff base to this state's most-recent commit
@@ -1023,11 +1224,7 @@ derives a driver's session id).
 The top-level `entry:` key (naming the root machine, `entry.default`) and a
 state's own `entry: true` flag are the same word at two different levels, by
 design: one selects the workflow's root machine, the other opts one state in as
-an extra manual entry point. The top-level `stateDir:` key and the
-`vars.stateDir` var it renders from are the same call: the definition-level
-declaration is what the engine reads (e.g. to tell gtd's own plumbing apart from
-your code), while the var is the knob you actually override — repointing
-`vars.stateDir` moves both.
+an extra manual entry point.
 
 A workflow is authored as a TREE of reusable, parameterized machines — a
 gate/loop written once and instantiated several times with different `with:`
@@ -1060,8 +1257,8 @@ Besides `it.vars` (below), a `script`/`prompt`/`message`/`commit` template sees:
 
 A template never sees rendered diff CONTENT — no field carries a diff. It names
 a base and leaves the agent to run `git diff <base>` itself; this keeps every
-render cheap (no diff computed on `gtd next`/`gtd status`/`gtd lsp`) and the
-prompt small and cacheable.
+render cheap (no diff computed on `gtd next`/`gtd lsp`) and the prompt small and
+cacheable.
 
 Authoring or editing a workflow with a coding agent? `skills/authoring/SKILL.md`
 is the agent-facing contract for producing a valid `workflow:` — the state
@@ -1222,10 +1419,10 @@ top-level `.gtdrc` `vars:` key, or the matching `GTD_STYLEBLOCK` /
 `GTD_STYLEFORMATCONTRACT` environment variable):
 
 - **`styleBlock`** — the voice itself, injected at all seven prompt states that
-  generate content, not just three: the free-prose ones — the `packagesDir`
-  package files (`architecture.decompose`), `specFeedbackFile`
-  (`packages.item.spec.review`), and `commitMsgFile` (`build.squashing`) — plus
-  the four machine-parsed states named in the next bullet. Blanking
+  generate content, not just three: the free-prose ones — the `.gtd/packages/`
+  package files (`architecture.decompose`), `.gtd/SPEC_FEEDBACK.md`
+  (`packages.item.spec.review`), and `.gtd/COMMIT_MSG.md` (`build.squashing`) —
+  plus the four machine-parsed states named in the next bullet. Blanking
   `GTD_STYLEBLOCK` strips the voice from all seven, including the machine-parsed
   ones, not only the free-prose three. In short: why density matters before any
   rule, answer-first with no preamble or restatement, blunt and imperative,
@@ -1238,17 +1435,17 @@ top-level `.gtdrc` `vars:` key, or the matching `GTD_STYLEBLOCK` /
   ahead of the role sentence and well before any state-specific format-contract
   text — `styleBlock` first, then `styleFormatContract`, at the four prompt
   states whose output a parser reads: the two `qa`-mode steering files
-  (`requirementsFile` at `design.triage`, `architectureFile` at
-  `architecture.author`) and the `review`-mode one (`reviewFile` at
-  `build.review.reviewing`), plus `requirementsFile` again at
+  (`.gtd/REQUIREMENTS.md` at `design.triage`, `.gtd/ARCHITECTURE.md` at
+  `architecture.author`) and the `review`-mode one (`.gtd/REVIEW.md` at
+  `build.review.reviewing`), plus `.gtd/REQUIREMENTS.md` again at
   `build.review.collecting`, which classifies a review round straight into it.
 
 Three more generated files carry no injected voice, because a script — not an
-agent — writes them: `feedbackFile` (verbatim test-suite output plus a HEAD
-stamp — the tool's content, not gtd's prose), `nextFile` (a bare path, no prose
-to style), and `reviewRawFile` (gtd's own prose, hand-tightened in the voice
-directly in `build.review.deciding`'s script rather than templated in through
-either variable).
+agent — writes them: `.gtd/FEEDBACK.md` (verbatim test-suite output plus a HEAD
+stamp — the tool's content, not gtd's prose), `.gtd/NEXT.md` (a bare path, no
+prose to style), and `.gtd/REVIEW_RAW.md` (gtd's own prose, hand-tightened in
+the voice directly in `build.review.deciding`'s script rather than templated in
+through either variable).
 
 ### Lookup and precedence
 
@@ -1323,8 +1520,8 @@ option"/"uncheck this option" code actions on each option — offered anywhere o
 the option's list item, including any wrapped continuation lines, not just its
 own `- [ ]` line — diagnostics for both (live as you edit), and a
 `gtd.openSteeringFile` command that jumps to the current state's steering file —
-including `idle`, whose `todoFile` hint gives the one keybinding an answer even
-before a process has started. The command only names that path — it never
+including `idle`, whose `.gtd/TODO.md` hint gives the one keybinding an answer
+even before a process has started. The command only names that path — it never
 stat-checks or creates it — so on a repo that has never run gtd, `.gtd/` may not
 exist yet and editors differ on opening a file whose parent directory is missing
 (an empty buffer that creates it on save vs. refusing the path outright); this