@pmelab/gtd 8.1.0 → 8.2.1

package/README.md

@@ -115,10 +115,12 @@ steering-file entries are chosen by which file you create:
   per-package **agentic review** that verifies the package against its spec.
 
 Both flows converge on the same tail: an agent hands you a `.gtd/REVIEW.md`
-checkbox review of the diff — tick a box as you review each hunk (ticking just
-records "I read this"), and leave a **comment** to request changes: a note on a
-line, an inline `// TODO`-style comment in the code, or a direct code edit. Any
-comment sends a build + re-review round — an agent first turns your comments
+checkbox review of the diff — the prompt never inlines the diff itself; it names
+the commit the changes are based at and the agent runs `git diff` to read the
+range before writing the review. Tick a box as you review each hunk (ticking
+just records "I read this"), and leave a **comment** to request changes: a note
+on a line, an inline `// TODO`-style comment in the code, or a direct code edit.
+Any comment sends a build + re-review round — an agent first turns your comments
 into an explicit instruction list, then a build turn implements it (a re-review
 then covers only the follow-through, and a hand-edit is treated as your own fix
 the agent completes without reverting your lines; a comment can't be silently
@@ -285,20 +287,106 @@ re-launching it — its opening move captures whatever you left, so you never ru
 
 Anything richer at that boundary — opening your editor, desktop notifications,
 terminal-multiplexer status — is the job of an outer wrapper around `gtd`, not
-of the loop itself. Pass `--once` to restrict a run to exactly one beat — one
-human-gate capture, one check, or one agent turn — instead of driving all the
-way to idle.
+of the loop itself; see
+[Terminal-multiplexer status: a herdr wrapper](#terminal-multiplexer-status-a-herdr-wrapper)
+below for a worked example. Pass `--once` to restrict a run to exactly one beat
+— one human-gate capture, one check, or one agent turn — instead of driving all
+the way to idle.
 
 Bare `gtd` prints one line per event — colored and emoji on a real terminal,
 plain ASCII under `NO_COLOR` or when piped — and redirects the noisier
 agent/check/step subprocess output to a per-repo/per-worktree log file (its path
-is the run's first output line, ready to `tail -f`).
+is the run's first output line, ready to `tail -f`). Any execution that FAILS
+also replays its last 20 lines of output inline on stderr, on top of the log
+still holding the complete record: an agent turn that fails stops the loop (it
+would fail identically next lap), while a check script that exits non-zero is
+reported as a warning and the loop carries on, because the outcome lives in the
+tree, not in the script's exit code.
 
 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
 per-beat progress lines; an outer wrapper (a terminal multiplexer, a notifier)
 can use it the same way.
 
+### Terminal-multiplexer status: a herdr wrapper
+
+[herdr](https://herdr.dev) shows a per-pane status in its sidebar. This wrapper
+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 next --json`'s `.actor`
+field, which the loop's driver already reads at every beat.
+
+Save this as `~/.local/bin/gtdh`, `chmod +x` it, and run `gtdh` in place of
+`gtd` — it's a plain bash file, so it works from fish or any other shell, and it
+forwards every argument (`gtdh --once`, `gtdh status`, ...).
+
+```bash
+#!/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 next --json`. Outside herdr it is a plain
+# passthrough. Requires `jq` — so does gtd's own loop driver.
+set -uo pipefail
+
+pane="${HERDR_PANE_ID:-}"
+
+# `--agent gtd` is deliberate: herdr only lets screen detection (or a visible
+# approval prompt) override a reported state when the reported label names a
+# KNOWN agent. "gtd" names none, so the loop's `claude -p` turns can never move
+# this pane's status.
+report() { # report <state>
+  [ -n "$pane" ] || return 0
+  herdr pane report-agent "$pane" \
+    --source custom:gtd --agent gtd --state "$1" >/dev/null 2>&1 || true
+}
+
+report working
+trap 'report blocked; exit 130' INT TERM
+
+# HERDR_PANE_ID is unset for the loop: herdr's Claude Code hook needs it, and
+# without it no `claude -p` turn reports a claude SESSION identity for this
+# pane. That is load-bearing, not cosmetic — a pane that owns one rejects every
+# later state report, so the report below would be dropped.
+env -u HERDR_PANE_ID gtd "$@"
+rc=$?
+
+# Whose turn is it now? `gtd next --json` is mutation-free. A human actor means
+# gtd is waiting on you; anything else means the run ended with nothing owed.
+actor="$(gtd next --json 2>/dev/null | jq -r '.actor // ""' 2>/dev/null || true)"
+
+if [ "$rc" -ne 0 ] || [ -z "$actor" ] || [ "$actor" = human ]; then
+  report blocked
+else
+  report idle
+fi
+
+exit $rc
+```
+
+A few things to know before relying on it:
+
+- **Give `gtd` its own pane.** Run an interactive `claude` (or any agent whose
+  herdr integration reports session identity) in the same pane and that pane
+  owns a `herdr:claude` session until the process exits; while it does, the
+  wrapper's reports are silently ignored and the sidebar stops tracking `gtd`.
+- **`blocked` covers the resting `idle` state too** — gtd's own `idle` is a
+  human gate (it waits for you to write a steering file), so a finished cycle
+  reads as "your turn", which is what it is.
+- The status **persists after the wrapper exits** — that's the point: the
+  sidebar keeps showing which worktree is waiting on you. Hand the pane back to
+  ordinary detection with
+  `herdr pane release-agent "$HERDR_PANE_ID" --source custom:gtd --agent gtd`.
+- A non-zero exit (a stall, a refusal, an error) reports `blocked`: herdr has no
+  failure state, and those all need a human.
+- Ctrl-C reports `blocked` rather than leaving a stale `working`.
+
+Optionally,
+`herdr pane report-metadata "$HERDR_PANE_ID" --source custom:gtd-display --token summary=<text>`
+sets a value renderable as `$summary` in an Agent sidebar row, if you want more
+than the state itself.
+
 ## Configuration
 
 gtd reads an optional `.gtdrc` config file via
@@ -384,6 +472,22 @@ workflow:
       mode: <modeName> # optional, requires "file" — a built-in (qa/review/prose) or a `modes:` entry
 ```
 
+Besides `it.vars` (below), a `script`/`prompt`/`message`/`commit` template sees:
+
+- **`it.startCommit`** — the process's diff base (the commit the current cycle
+  started from, or a `gtd review <commitish>` entry's resolved base).
+- **`it.reviewBase`** — the previous review round's boundary, falling back to
+  `it.startCommit` on a first review.
+- **`it.retainedBase`** — the process's trace/retry boundary, what a squash
+  actually keeps (never moved by a `gtd review` entry).
+- **`it.currentCommit`** / **`it.previousCommit`** — HEAD's hash and its parent,
+  at render time.
+
+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.
+
 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
 model, pattern grammar, load-time rules, and how to verify a change compiles.
@@ -483,9 +587,11 @@ compiler's job at load time.
 per `review`-mode chunk that still has an unchecked hunk (an outline of the
 packages left to review) plus check/uncheck actions over those chunks,
 go-to-definition from a `review`-mode hunk line into the file it points at (at
-its `#line`), symbols over a `qa`-mode file's open questions, diagnostics for
-both (live as you edit), and a `gtd.openSteeringFile` command that jumps to the
-current state's steering file.
+its `#line`), symbols over a `qa`-mode file's open questions plus "pick this
+option"/"uncheck this option" code actions on each option — offered anywhere on
+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.
 
 It is config-driven via each state's `file:`/`mode:`, and falls back to basename
 dispatch (`REVIEW.md` → `review`) with no config in sight. `qa` and `review` are

package/bin/gtd

@@ -44,12 +44,12 @@ if [[ "$FANCY" == 1 ]]; then
   C_RESET=$'\e[0m'; C_BOLD=$'\e[1m'; C_DIM=$'\e[2m'
   C_CYAN=$'\e[36m'; C_GREEN=$'\e[32m'; C_YELLOW=$'\e[33m'; C_RED=$'\e[31m'
   M_TRANS="➡️"; M_AGENT="🤖"; M_CHECK="🔧"; M_HUMAN="✍️"
-  M_FIX="🔁"; M_COMMIT="✅"; M_SETTLE="🎉"; M_ERROR="❌"; M_ELLIPSIS="…"
+  M_FIX="🔁"; M_COMMIT="✅"; M_SETTLE="🎉"; M_ERROR="❌"; M_WARN="⚠️"; M_ELLIPSIS="…"
 else
   C_RESET=""; C_BOLD=""; C_DIM=""
   C_CYAN=""; C_GREEN=""; C_YELLOW=""; C_RED=""
   M_TRANS="->"; M_AGENT="[agent]"; M_CHECK="[check]"; M_HUMAN="[you]"
-  M_FIX="[fix]"; M_COMMIT="[commit]"; M_SETTLE="[done]"; M_ERROR="[err]"; M_ELLIPSIS="..."
+  M_FIX="[fix]"; M_COMMIT="[commit]"; M_SETTLE="[done]"; M_ERROR="[err]"; M_WARN="[warn]"; M_ELLIPSIS="..."
 fi
 
 # emit_file_rows <files> — render a commit's changed files as dim, indented
@@ -114,8 +114,10 @@ emit_error() {
 }
 
 # emit_log_pointer — the "see the log" line printed right after every
-# emit_error call, to stderr: suppression must never hide a failure, so every
-# error points at where the redirected subprocess output actually went.
+# emit_error call, to stderr: it names the log as the OVERFLOW channel — the
+# failing execution's own output is already replayed inline (see emit_block/
+# emit_output_since below); the log is where the rest of it, and the full
+# run's other output, lives.
 emit_log_pointer() {
   if [[ "$FANCY" == 1 ]]; then
     printf '%s📄 see %s%s\n' "$C_DIM" "$GTD_LOOP_LOG" "$C_RESET" >&2
@@ -124,6 +126,58 @@ emit_log_pointer() {
   fi
 }
 
+# Suppressed subprocess output goes to $GTD_LOOP_LOG in full, but a FAILING
+# execution also replays inline: mark the log's size before the call, print
+# what was appended since. Bounded to the last $ERR_TAIL_LINES lines — the log
+# holds the rest, and the overflow row says where.
+ERR_TAIL_LINES=20
+
+# log_offset — the log's current size in bytes (0 when it doesn't exist yet).
+log_offset() {
+  local n=0
+  if [[ -n "${GTD_LOOP_LOG:-}" && -f "$GTD_LOOP_LOG" ]]; then n="$(wc -c <"$GTD_LOOP_LOG")"; fi
+  printf '%s' "${n// /}"
+}
+
+# emit_block <text> — replay captured subprocess output to stderr, dim and
+# indented like emit_file_rows, capped at the LAST $ERR_TAIL_LINES lines with
+# an overflow row naming the log. Empty <text> prints nothing. CSI escapes are
+# stripped under FANCY=0 (the plain-ASCII promise), using a sed form (\e, not
+# \x1b) that both BSD and GNU sed accept.
+emit_block() {
+  local text="$1" total overflow
+  [[ -z "$text" ]] && return 0
+  if [[ "$FANCY" == 0 ]]; then
+    text="$(sed $'s/\e\\[[0-9;]*[a-zA-Z]//g' <<<"$text")"
+  fi
+  total="$(wc -l <<<"$text")"
+  total="${total// /}"
+  if ((total > ERR_TAIL_LINES)); then
+    overflow=$((total - ERR_TAIL_LINES))
+    printf '   %s%s (%d earlier lines in %s)%s\n' "$C_DIM" "$M_ELLIPSIS" "$overflow" "$GTD_LOOP_LOG" "$C_RESET" >&2
+    text="$(tail -n "$ERR_TAIL_LINES" <<<"$text")"
+  fi
+  while IFS= read -r line; do
+    printf '   %s%s%s\n' "$C_DIM" "$line" "$C_RESET" >&2
+  done <<<"$text"
+}
+
+# emit_output_since <offset> — emit_block over the log bytes appended since
+# <offset>.
+emit_output_since() {
+  local offset="$1" bytes=""
+  if [[ -n "${GTD_LOOP_LOG:-}" && -f "$GTD_LOOP_LOG" ]]; then
+    bytes="$(tail -c "+$((offset + 1))" "$GTD_LOOP_LOG" 2>/dev/null || true)"
+  fi
+  emit_block "$bytes"
+}
+
+# emit_warn <message> — a surfaced but NON-fatal failure (a check script that
+# exited non-zero).
+emit_warn() {
+  printf '%s %s%s%s\n' "$M_WARN" "$C_YELLOW" "$1" "$C_RESET" >&2
+}
+
 # ── Git-derivation helpers (parse_subject, report_commits) ──────────────────
 
 # parse_subject <subject> — sets S_ACTOR / S_FROM / S_TO / S_KIND. Patterns are
@@ -375,9 +429,10 @@ fi
 
 while true; do
   if ! next_json="$(run_gtd next --json 2>&1)"; then
-    echo "gtd-loop: could not determine the next step:" >&2
-    echo "$next_json" >&2
-    echo "Run \`gtd status\` to inspect the repo." >&2
+    emit_error "could not determine the next step:
+$next_json
+Run \`gtd status\` to inspect the repo."
+    emit_log_pointer
     exit 1
   fi
 
@@ -394,17 +449,29 @@ while true; do
     # (or an outer wrapper) edits and re-launches; the opening move above
     # captures what they left.
     emit_gate "$state" "$label"
-    run_gtd next
+    if ! gate_out="$(run_gtd next 2>&1)"; then
+      emit_error "$gate_out"
+      emit_log_pointer
+      exit 1
+    fi
+    printf '%s\n' "$gate_out"
     exit 0
   fi
 
   if [[ "$kind" == "script" ]]; then
     emit_action "$M_CHECK" "$label"
-    # Execute the emitted wrapper verbatim; its exit code is deliberately
-    # ignored (`|| true` under `set -e`) — the script encodes its outcome in
-    # the tree, and `gtd step` captures whatever it left there via the state's
-    # own `on` patterns. Its own output goes to the log, not the terminal.
-    bash -c "$content" >>"$GTD_LOOP_LOG" 2>&1 || true
+    # Execute the emitted wrapper verbatim; its exit code decides nothing
+    # (the script encodes its outcome in the tree, and `gtd step` captures
+    # whatever it left there via the state's own `on` patterns) but a non-zero
+    # exit is surfaced as a warning — its own output goes to the log, and to
+    # the terminal too when it exits non-zero.
+    script_offset="$(log_offset)"
+    script_status=0
+    bash -c "$content" >>"$GTD_LOOP_LOG" 2>&1 || script_status=$?
+    if ((script_status != 0)); then
+      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
       printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
       emit_error "$step_out"
@@ -478,24 +545,42 @@ $next_out"
   # 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"
-  run_agent_turn "$content" "$resume"
+  turn_offset="$(log_offset)"
+  agent_status=0
+  run_agent_turn "$content" "$resume" || agent_status=$?
+  if ((agent_status != 0)); then
+    emit_error "the agent turn at '$state' failed (exit $agent_status):"
+    emit_output_since "$turn_offset"
+    emit_log_pointer
+    exit 1
+  fi
 
   fix_attempt=0
   while ! validate_out="$(run_gtd validate 2>&1)"; do
     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:
 $validate_out
 Stopping rather than stepping with a malformed steering file."
       emit_log_pointer
       exit 1
     fi
+    printf '%s\n' "$validate_out" >>"$GTD_LOOP_LOG"
+    emit_action "$M_FIX" "attempt $fix_attempt"
     # Resume the same session when there is one (the agent just wrote the file);
     # otherwise a fresh invocation still gets the findings via the prompt.
     fix_resume=0
     [[ -n "$session_id" ]] && fix_resume=1
-    emit_action "$M_FIX" "attempt $fix_attempt"
-    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"
+    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=$?
+    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"
+      emit_log_pointer
+      exit 1
+    fi
   done
 
   if ! step_out="$(run_gtd step "$actor" 2>&1)"; then