@pmelab/gtd 8.5.0 → 8.6.0

package/README.md

@@ -227,13 +227,26 @@ Commands:
   next             Print the resolved rest's rendered script/prompt/message (no mutation)
   status           Print the resolved rest's state/actor and which declared
                    pattern (if any) each pending change matches (no mutation)
-  validate         Format and validate the steering file the resolved rest
-                   declares, with its mode's commands (its file:/mode:);
-                   exits non-zero with the findings when it is invalid
+  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)
   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)
+  check <mode> <file>
+                   Read <file> and run the built-in steering format named
+                   <mode> (see `gtd validate`'s modes: qa, review) over its
+                   contents, printing each finding one per line and exiting
+                   non-zero when there are any. Resolves no workflow state and
+                   reads no config — standalone, runnable from any directory
+                   with <mode>/<file> given explicitly. This is what a
+                   workflow's emitted validation script invokes as a leaf step
   version          Print version and exit
   help             Print this help and exit
 
@@ -469,6 +482,123 @@ Optionally,
 sets a value renderable as `$summary` in an Agent sidebar row, if you want more
 than the state itself.
 
+## Writing your own driver
+
+`bin/gtd` is gtd's own reference driver, not a 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 step [<actor>]` (including
+`--entry <state>`), `gtd abandon`, and `gtd restore` — perform no git write when
+run. Instead, under `--json`, each one's output object carries two extra string
+fields, `required` and `optional`: bash scripts for YOU to execute. (Plain-text
+output, without `--json`, never shows these — it prints only the human-facing
+result line, e.g. `committed: <subject>`, so a plain-text caller never sees a
+script at all.) A driver that only prints gtd's plain-text output is not driving
+anything; to actually land a turn, run `gtd ... --json`, pull `required`/
+`optional` out with `jq`, and execute them.
+
+- **`required`** is everything that decides what lands in git — closing an open
+  review checkout window, the resting state's own steering-mode
+  `format:`/`validate:` commands, then the commit or squash itself (`gtd step`
+  and `gtd --entry <state>`), or the ref update and reset that undo a process
+  (`gtd abandon`, `gtd restore`). Run this one. Skipping it means the turn never
+  lands.
+- **`optional`** is presentation only: re-opening the review checkout window
+  (the `<<<<<<< HEAD` diff view) after a `gtd step` 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).
+
+Either field may be the empty string `""`, meaning "nothing to do here" — a
+no-op `gtd step` (a clean tree matching no `on` pattern) emits
+`required: ""`/`optional: ""` and exits zero; run nothing and move on. 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.
+
+### Failure taxonomy and recovery
+
+Two different things can go wrong, and they mean different things:
+
+- **`gtd` itself exits non-zero.** Nothing was attempted — this is a refusal (a
+  guard rejected the turn) or a usage error. No script was ever produced.
+- **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.
+
+Recovery is the same in both cases: **re-invoke `gtd`.** 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 opens
+by asserting its own precondition
+(`[ "$(git rev-parse --verify --quiet HEAD 2>/dev/null)" = <expected> ] || { ...; exit 1; }`,
+and the same shape for a review window's saved ref — see `src/Emit.ts`'s
+`headAssertion`/`reviewWindowAssertion`), so a script generated against a
+repository state that has since moved refuses loudly instead of corrupting
+anything. In a repository with no commits yet, `<expected>` is the empty string
+— the deciding read's own convention for "no commits yet" — so the first
+workflow commit is allowed to land instead of being blocked by an unborn `HEAD`.
+**Emitted scripts are re-runnable**: this is the single most important property
+for a driver's recovery logic. Re-running a script that already fully applied is
+a no-op (its git writes are `--allow-empty` commits, idempotent ref updates, and
+tolerant staged-restore calls), and re-running one that only partially applied
+resumes correctly, because the precondition either still holds (nothing landed
+yet — safe to retry verbatim) or gtd's next invocation reads the new real state
+and emits a fresh script for what remains. A driver never needs 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.
+- **`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
+  script, not by absolute path (see `src/SteeringFormats.ts`'s
+  `seededValidateCommand`). This is a deliberate trade: a readable, overridable,
+  copy-pasteable command in exchange for depending on shell name resolution at
+  the moment the script runs. The sharp edge: if the `gtd` binary you invoked to
+  GENERATE the script differs from the `gtd` that resolves on `PATH` when the
+  script later RUNS (a locally-built dev binary vs. a globally-installed
+  release, say), you can get version skew between the two — the command that
+  validates may not be the command that decided. Keep the two in sync (one `gtd`
+  on `PATH`, consistently) if you care about that gap.
+
+### The normalization-only contract on `format:`
+
+A mode's `format:` command may reformat a steering file — whitespace, wrapping,
+reordering — but must NEVER change what a step-capture guard would decide. gtd's
+guards (the review sign-off check, the feedback-progress check, the
+answer-completeness check — `src/StepGuards.ts`) decide ONCE, against whichever
+bytes are on disk at the moment `gtd step` runs, which may be before OR after an
+emitted script's own `format:` line has run (the script runs `format:` then
+`validate:` then the commit — see `src/SteeringMode.ts`'s
+`renderSteeringCommands` — but gtd's decision and the driver's script execution
+are different processes at different times, so there's no guaranteed ordering
+between "gtd decided" and "the script formatted"). That's only safe because
+every built-in guard judges content, not incidental formatting (e.g. it
+normalizes `[ ]`/`[x]` checkboxes before comparing). If you plug in your own
+`format:` command, the same rule binds it: a formatter that also changes meaning
+— ticking a box, stripping a paragraph — makes the guard's decision and the
+file's actual content disagree, and gtd will not catch that for you.
+
+### Built-in steering formats are ordinary modes
+
+`qa` and `review` are gtd's two built-in steering-file formats (parsed and
+validated in-process because `gtd lsp` needs the same parsers for live
+diagnostics), but their `validate:` is not hardcoded or hidden: the compiler
+SEEDS every workflow's `modes:` map with `qa`/`review` entries whose `validate:`
+is the same `gtd check <mode> '<file>'` string described above
+(`src/PatternConfig.ts`, `src/SteeringFormats.ts`'s `seededValidateCommand`).
+That seeded command is visible in `gtd visualize`'s compiled model and in the
+editor JSON schema like any other mode, and it's overridable the same way any
+mode is — declare `modes: { qa: { validate: "your-own-command" } }` (in the
+workflow or in `.gtdrc`) and your command displaces the seed; declaring only a
+`format:` for `qa`/`review` composes with the seeded `validate:` rather than
+replacing it. There is no special-cased built-in behavior a driver needs to know
+about beyond the ordinary mode-resolution rules already documented under
+[The `workflow:` key](#the-workflow-key).
+
 ## Configuration
 
 gtd reads an optional `.gtdrc` config file via
@@ -799,8 +929,8 @@ but `gtd lsp` never runs a shell command per keystroke, so live diagnostics
 become one `Information` notice pointing at `gtd validate` instead of the
 built-in findings. Any OTHER mode name — `prose` (used by the simple flow's plan
 file), or a project's own declared name — has no built-in format, so it gets no
-live editor support at all: `gtd validate` and the `gtd step` gate still format
-and validate it like any other mode.
+live editor support at all: `gtd validate`'s emitted script and the `gtd step`
+gate still format and validate it like any other mode.
 
 ## Development
 

package/bin/gtd

@@ -10,8 +10,13 @@ set -euo pipefail
 #   - no arguments, or exactly `loop` with no further arguments -> fall through
 #     into the loop body below (the loop protocol comment further down).
 #   - `loop` with an unrecognised extra argument -> usage error, exit 2.
-#   - anything else -> hand off to the bundle via `run_gtd`, forwarding all
-#     arguments unchanged (e.g. `bin/gtd status`, `bin/gtd step human`).
+#   - anything else -> a WRITE subcommand (`step`, the `--entry` forms,
+#     `abandon`, `restore` — see `is_write_command`) routes through
+#     `run_gtd_command`, which actually performs the bundle's emitted
+#     `required`/`optional` scripts (the bundle itself only ever PRINTS them
+#     now); everything else (`status`, `next`, `validate`, `visualize`, `lsp`,
+#     `check`, `init`) hands off straight to the bundle via `run_gtd`,
+#     forwarding all arguments unchanged (e.g. `bin/gtd status`).
 # The loop's whole job is to drive the process until it rests at a
 # NON-AUTONOMOUS state (a human gate) or settles. Everything beyond that —
 # editors, desktop notifications, terminal-multiplexer status — is an OUTER
@@ -61,6 +66,19 @@ else
   M_FIX="[fix]"; M_COMMIT="[commit]"; M_SETTLE="[done]"; M_ERROR="[err]"; M_WARN="[warn]"; M_ELLIPSIS="..."
 fi
 
+# `jq` used to be a loop-only dependency (the loop's own `next --json`
+# parsing); now every write subcommand's `--json` response (parsed by
+# `run_gtd_command`, below) carries the `required`/`optional` scripts this
+# script must execute for ANY invocation, not just `loop`. Checked once, up
+# front, before any dispatch below ever reaches for `jq` — a plain
+# `echo`/`exit` rather than `emit_error` since that helper (and the
+# fancy/plain markers it relies on) isn't the point; keeping the check
+# dependency-free is.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "gtd: jq is required (used to parse the bundle's --json output) — install it and retry" >&2
+  exit 1
+fi
+
 # emit_file_rows <files> — render a commit's changed files as dim, indented
 # rows BELOW the transition/commit line: at most 3, then a "… (N more)" row
 # when there are more. <files> is a newline-separated list (git diff-tree
@@ -234,9 +252,18 @@ parse_subject() {
 # when it reported at least one; returns non-zero (having emitted nothing,
 # and leaving $reported_head unchanged) when there were no new commits. Global
 # rather than per-beat so the review checkout window's HEAD rewinds between
-# beats never cause an already-reported commit to replay.
+# beats never cause an already-reported commit to replay. $reported_head ==
+# "none" (the repo had no commits at all when it was last captured) can't
+# form a "none"..HEAD range — `git rev-list` would fail resolving "none" as a
+# revision — so that case walks the whole history from the root instead.
 report_commits() {
   local sha subject files reported=0
+  local range
+  if [[ "$reported_head" == none ]]; then
+    range="HEAD"
+  else
+    range="$reported_head..HEAD"
+  fi
   while IFS= read -r sha; do
     [[ -z "$sha" ]] && continue
     reported=1
@@ -247,13 +274,130 @@ report_commits() {
       transition) emit_transition "$S_FROM" "$S_TO" "$files" ;;
       capture | squash) emit_commit "$subject" "$files" ;;
     esac
-  done < <(git rev-list --reverse "$reported_head"..HEAD)
+  done < <(git rev-list --reverse "$range")
   if [[ "$reported" == 1 ]]; then
     reported_head="$(git rev-parse HEAD)"
   fi
   [[ "$reported" == 1 ]]
 }
 
+# ── Write-command execution (is_write_command, run_gtd_command) ────────────
+# The bundle no longer performs a WRITE subcommand's git effect itself: its
+# `--json` response for `step`/the `--entry` forms/`abandon`/`restore` now
+# carries `required` (a bash script that performs the command's whole
+# effect — commit/reset/etc, including any review-window close/open
+# management) and `optional` (presentation-only, e.g. re-opening the review
+# checkout window — safe to skip), alongside whichever keys that command's
+# JSON always carried. This script is the ONE driver for every invocation
+# (not just the loop's), so it — not the bundle — must run those scripts.
+
+# is_write_command <token> — true for exactly the tokens whose command
+# mutates the repo: `step` (with or without `--entry` trailing), `abandon`,
+# `restore`, and the bare `--entry` short form (`gtd --entry <state>`, where
+# `--entry` itself is $1 since there is no subcommand token in front of it).
+# Everything else (next/status/validate/visualize/lsp/check/init, or an
+# unrecognised token) is read-only or has its own arity/usage errors and is
+# left to the existing plain `run_gtd "$@"` forwarding.
+# `--entry` takes both spellings (`--entry <state>` and `--entry=<state>`), so
+# the bare short form has to be recognised either way.
+is_write_command() {
+  case "${1:-}" in
+    step | abandon | restore | --entry | --entry=*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# run_gtd_command <subcommand-and-args...> — the ONE execution path for every
+# write subcommand, used both by the direct dispatch below and by the loop
+# body's own step calls (so there is one execution path rather than two, not
+# a loop-only one and a separate direct one). Fetches the bundle's `--json`
+# response for "$@" (forcing --json on regardless of whether the caller's own
+# arguments already carry it — repeating `--json` is harmless, see
+# `Cli.ts`'s arity-0 flag handling), runs `.required` via `bash -c` (aborting
+# — returning its exit code — before `.optional` ever runs, mirroring `set
+# -e`), then `.optional` via `bash -c` (a non-zero exit there is only ever a
+# warning: it is presentation-only, e.g. re-opening the review checkout
+# window, per its own "safe to skip" billing). On success it prints, on
+# stdout, the plain human-facing line in TODAY's exact wording — the same
+# text `runStepCommand`/`runEntryCommand`/`runAbandonCommand`/
+# `runRestoreCommand` printed themselves before this rewrite moved the git
+# write into `required`. A direct caller lets that line stream straight to
+# the terminal; the loop instead captures it (`$(... 2>&1)`, the file's
+# established idiom) and logs it, since its own on-screen presentation is
+# `report_commits`. `abandon`/`restore` have no `subject` in their JSON (never
+# did — the original handlers computed it from git AFTER writing), so this
+# recomputes it from HEAD after `.required` has run; every other field used
+# below (`state`, `from`, `head`, `to`) is one of the contract's own preserved
+# "existing keys". On failure (the JSON fetch itself — a refusal/usage error —
+# or `.required`), the combined fetch output is sent to stderr and the
+# function returns non-zero; a failing `.required`'s own output streams
+# (or is captured by the caller) exactly as it happened, unredirected here.
+run_gtd_command() {
+  local subcmd="${1:-}" json_out required optional opt_status
+  local state subject head to from
+
+  if ! json_out="$(run_gtd "$@" --json 2>&1)"; then
+    printf '%s' "$json_out" >&2
+    return 1
+  fi
+
+  # `// empty` guards a command whose JSON doesn't (yet, or ever) carry these
+  # keys for a given branch — e.g. `gtd abandon`'s "nothing to abandon" no-op
+  # reply has neither key at all — so a missing/null field reads as "" (jq's
+  # own `null` stringifies to the 4-character text "null" otherwise, which
+  # would misread as a non-empty script).
+  required="$(jq -r '.required // empty' <<<"$json_out")"
+  optional="$(jq -r '.optional // empty' <<<"$json_out")"
+
+  if [[ -n "$required" ]]; then
+    bash -c "$required" || return $?
+  fi
+
+  if [[ -n "$optional" ]]; then
+    opt_status=0
+    bash -c "$optional" || opt_status=$?
+    if ((opt_status != 0)); then
+      emit_warn "the presentation-only follow-up after '$subcmd' failed (exit $opt_status) — continuing"
+    fi
+  fi
+
+  case "$subcmd" in
+    abandon)
+      if [[ -z "$required" ]]; then
+        state="$(jq -r '.state' <<<"$json_out")"
+        printf 'no gtd process is underway (resting at "%s") — nothing to abandon\n' "$state"
+      else
+        from="$(jq -r '.from' <<<"$json_out")"
+        state="$(jq -r '.state' <<<"$json_out")"
+        head="$(jq -r '.head' <<<"$json_out")"
+        subject="$(git log -1 --format=%s HEAD)"
+        printf 'abandoned the process resting at "%s" — HEAD is back at %s ("%s"), resting at "%s".\n' \
+          "$from" "${head:0:7}" "$subject" "$state"
+        printf 'Everything the process produced is kept as uncommitted changes (`git status`); discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.\n'
+      fi
+      ;;
+    restore)
+      to="$(jq -r '.to' <<<"$json_out")"
+      state="$(jq -r '.state' <<<"$json_out")"
+      subject="$(git log -1 --format=%s HEAD)"
+      printf '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' \
+        "${to:0:7}" "$subject" "$state"
+      ;;
+    *)
+      # `step` (subject nullable — a no-op prints "nothing to do") and the
+      # `--entry` forms (subject never null — always "committed: ...") share
+      # this one branch: the null-check alone tells them apart.
+      subject="$(jq -r '.subject' <<<"$json_out")"
+      if [[ -n "$subject" && "$subject" != "null" ]]; then
+        printf 'committed: %s\n' "$subject"
+      else
+        state="$(jq -r '.state' <<<"$json_out")"
+        printf 'nothing to do at "%s"\n' "$state"
+      fi
+      ;;
+  esac
+}
+
 # ── Log file (resolve_log_path) ─────────────────────────────────────────────
 
 # worktree_git_dir — the git dir of the working tree gtd is operating in,
@@ -317,6 +461,10 @@ if [[ "$valid_combo" == 1 && "$n_once" == 1 ]]; then
 fi
 
 if [[ $# -gt 0 && "$1" != "loop" ]]; then
+  if is_write_command "${1:-}"; then
+    run_gtd_command "$@"
+    exit $?
+  fi
   run_gtd "$@"
   exit $?
 fi
@@ -501,7 +649,7 @@ run_agent_turn() {
 # its own comment) — a global high-water mark rather than a per-beat
 # head_before, so a review checkout window's HEAD rewind between beats never
 # causes an already-printed transition to replay.
-reported_head="$(git rev-parse HEAD 2>/dev/null || echo none)"
+reported_head="$(git rev-parse --verify --quiet HEAD || echo none)"
 
 # Opening move: capture the human's pending edit so gtd-loop is the ONLY command
 # a human runs. A human acts at a gate by editing files (a plan answer, a review
@@ -528,8 +676,8 @@ Run \`gtd status\` to inspect the repo."
 fi
 peek_kind="$(jq -r .kind <<<"$peek_json")"
 if [[ "$peek_kind" == "message" ]]; then
-  opening_head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
-  if ! step_out="$(run_gtd step human 2>&1)"; then
+  opening_head_before="$(git rev-parse --verify --quiet HEAD || echo none)"
+  if ! step_out="$(run_gtd_command step human 2>&1)"; then
     emit_error "could not capture your changes at the human gate:
 $step_out
 Fix the reported issue and re-run gtd-loop."
@@ -539,7 +687,7 @@ Fix the reported issue and re-run gtd-loop."
   # This branch reports nothing — advance the marker past whatever was just
   # (silently) captured so the first loop-body beat below doesn't newly
   # print it.
-  reported_head="$(git rev-parse HEAD 2>/dev/null || echo none)"
+  reported_head="$(git rev-parse --verify --quiet HEAD || echo none)"
   if [[ "$once_mode" == 1 && "$opening_head_before" != "$reported_head" ]]; then
     exit 0
   fi
@@ -590,7 +738,7 @@ Run \`gtd status\` to inspect the repo."
       emit_warn "the check script at '$state' exited $script_status — continuing; the outcome is whatever it left in the tree:"
       emit_output_since "$script_offset"
     fi
-    if ! step_out="$(run_gtd step "$actor" 2>&1)"; then
+    if ! step_out="$(run_gtd_command step "$actor" 2>&1)"; then
       printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
       emit_error "$step_out"
       emit_log_pointer
@@ -616,7 +764,7 @@ Run \`gtd status\` to inspect the repo."
   # stall from a return lap back into the same state (e.g. checking ->
   # fixing): a static prompt looks identical to last time, but a commit
   # landed in between, so HEAD has moved and this isn't a stall.
-  cur_head="$(git rev-parse HEAD 2>/dev/null || echo none)"
+  cur_head="$(git rev-parse --verify --quiet HEAD || echo none)"
   if [[ "$state" == "$prev_state" && "$content" == "$prev_content" && "$cur_head" == "$prev_head" ]]; then
     next_out="$(run_gtd next 2>&1)" || true
     emit_error "no progress at '$state' — the agent's last turn changed nothing. Stopping to avoid spinning.
@@ -653,12 +801,15 @@ $next_out"
   # Run the agent turn (see run_agent_turn's own comment for the adapter
   # contract). Then the self-validation gate: a producing state may declare a
   # `file:`/`mode:` pair (e.g. the default workflow's grilling/reviewing),
-  # making its output's format checkable. `gtd validate` is a no-op (exit 0)
-  # when the resolved rest has nothing to validate, so run it after EVERY agent
-  # turn; on findings, re-prompt the SAME agent session to fix them (up to a
-  # cap) before stepping — the plain-`gtd next` self-validation instruction's
-  # driver-side equivalent, so the next rest is only ever handed a well-formed
-  # file. gtd itself never validates at step time — this is the loop's job.
+  # making its output's format checkable. `gtd validate --json` always exits
+  # 0 now — it hands back the SCRIPT that formats/checks the file (`.script`,
+  # empty when the resolved rest has nothing to validate) rather than running
+  # it itself, so this driver runs that script after EVERY agent turn and
+  # re-prompts the SAME agent session on ITS non-zero exit (up to a cap)
+  # before stepping — the plain-`gtd next` self-validation instruction's
+  # driver-side equivalent, so the next rest is only ever handed a
+  # well-formed file. gtd itself never validates at step time — this is the
+  # loop's job.
   emit_action "$M_AGENT" "$label"
   turn_offset="$(log_offset)"
   agent_status=0
@@ -670,12 +821,24 @@ $next_out"
     exit 1
   fi
 
+  if ! validate_json="$(run_gtd validate --json 2>&1)"; then
+    emit_error "could not resolve the validation script at '$state':
+$validate_json
+Stopping rather than stepping with a possibly-malformed steering file."
+    emit_log_pointer
+    exit 1
+  fi
+  validate_script="$(jq -r '.script' <<<"$validate_json")"
+
   fix_attempt=0
-  while ! validate_out="$(run_gtd validate 2>&1)"; do
+  while [[ -n "$validate_script" ]]; do
+    validate_status=0
+    validate_out="$(bash -c "$validate_script" 2>&1)" || validate_status=$?
+    ((validate_status == 0)) && break
     fix_attempt=$((fix_attempt + 1))
     if ((fix_attempt > 3)); then
       printf '%s\n' "$validate_out" >>"$GTD_LOOP_LOG"
-      emit_error "'$state' still fails \`gtd validate\` after 3 fix attempts:
+      emit_error "'$state' still fails its own validation script after 3 fix attempts:
 $validate_out
 Stopping rather than stepping with a malformed steering file."
       emit_log_pointer
@@ -689,7 +852,7 @@ Stopping rather than stepping with a malformed steering file."
     [[ -n "$session_id" ]] && fix_resume=1
     turn_offset="$(log_offset)"
     agent_status=0
-    run_agent_turn "$content"$'\n\n'"Your last turn does not pass \`gtd validate\`. Fix these format violations, then finish:"$'\n'"$validate_out" "$fix_resume" || agent_status=$?
+    run_agent_turn "$content"$'\n\n'"Your last turn does not pass its own validation script. Fix these format violations, then finish:"$'\n'"$validate_out" "$fix_resume" || agent_status=$?
     if ((agent_status != 0)); then
       emit_error "the agent's fix attempt $fix_attempt at '$state' failed (exit $agent_status):"
       emit_output_since "$turn_offset"
@@ -698,7 +861,7 @@ Stopping rather than stepping with a malformed steering file."
     fi
   done
 
-  if ! step_out="$(run_gtd step "$actor" 2>&1)"; then
+  if ! step_out="$(run_gtd_command step "$actor" 2>&1)"; then
     printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
     emit_error "$step_out"
     emit_log_pointer