@pmelab/gtd 7.4.2 → 7.6.0

package/README.md

@@ -106,6 +106,9 @@ handful of commands drive it:
   pending changes, and which action leads where. The panel and diagram highlight
   refresh live (~every 3s) while the page is open, so advancing the process
   elsewhere shows up without a manual refresh.
+- **`gtd edit [path]`** — open `<path>` (or, with no argument, the current
+  resting state's steering file, or the repo dir) in `${VISUAL:-$EDITOR}`,
+  blocking until it exits.
 
 `gtd version` (or `gtd --version`/`-v`) prints the installed version and exits;
 `gtd help` (or `gtd --help`/`-h`) prints the command list. Both short-circuit
@@ -172,9 +175,16 @@ the file.
 
 Bare `gtd` (or `gtd loop`) is a ready-to-run driver for the whole protocol —
 point it at a repo and it runs the loop until it's your turn. It is the only
-command you run: at a gate you edit files (answer a plan question, tick a review
-box, fix code) and re-launch it, and it captures your edit as its opening move
-before driving on — so you never run `gtd step human` by hand. See
+command you run: at a human gate it now opens `${VISUAL:-$EDITOR}` on the gate's
+file for you automatically (answer a plan question, tick a review box, fix
+code), waits for you to save and exit, then captures your edit itself and keeps
+driving — or halts if you left nothing changed — so you never run
+`gtd step human` by hand. Pass `--no-edit` (or set `GTD_NO_EDIT`) to fall back
+to halting and printing the gate instead, if you'd rather edit and re-launch it
+yourself. 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.
+`gtd log` opens that logfile in your editor. See
 [Driving the loop](docs/loop.md).
 
 Before wiring gtd into a repo, note the

package/bin/gtd

@@ -3,9 +3,21 @@ set -euo pipefail
 
 # This file is the single published `bin` entry: `bin/gtd`. Before anything
 # else, it dispatches on $1:
+#   - `--no-edit` (bare, or immediately after `loop`) -> stripped here and
+#     disables the loop's automatic editor launching for this run (see
+#     `edit_disabled`/`GTD_NO_EDIT` below); dispatch then continues on the
+#     remaining arguments as if it had never been given.
+#   - `edit [path]` -> handled entirely here in bash, never forwarded to the
+#     bundle: opens `${VISUAL:-$EDITOR}` on `path`, or (no `path` given) on the
+#     resolved rest's `.file` (or `.` when absent).
+#   - `log` -> handled entirely here in bash, never forwarded to the bundle:
+#     opens `${VISUAL:-$EDITOR}` on the current repo/worktree's loop logfile
+#     (see `resolve_log_path`), refusing rather than opening an empty buffer
+#     when no loop has produced one yet.
 #   - no arguments, or exactly `loop` with no further arguments -> fall through
 #     into the loop body below (the loop protocol comment further down).
-#   - `loop` with additional arguments -> usage error, exit 2.
+#   - `loop` with additional arguments (other than a lone `--no-edit`) ->
+#     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`).
 # `run_gtd` is the ONE place that knows how to invoke "the bundle": by default
@@ -25,6 +37,211 @@ run_gtd() {
   fi
 }
 
+# Shared editor-launch helper — used by both the `edit` subcommand below and
+# the loop's human-gate flow further down. Resolves the editor git-style
+# ($VISUAL, then $EDITOR — no fallback to `vi`), then launches it blocking in
+# the foreground with the target path passed as a positional parameter
+# (never string-spliced into the command), so a multi-word command
+# (`code --wait`) and a path with special characters both work. A launch
+# failure (bad/missing editor binary) is a plain non-zero return, propagating
+# under `set -e`; the editor's own exit code is otherwise ignored entirely —
+# the outcome is judged from tree state afterward, not from this function.
+launch_editor() {
+  local target="$1" editor="${VISUAL:-${EDITOR:-}}"
+  if [[ -z "$editor" ]]; then
+    echo "gtd: no editor configured — set \$EDITOR (or \$VISUAL)" >&2
+    return 1
+  fi
+  bash -c "$editor \"\$1\"" gtd-edit "$target"
+}
+
+# ── Rendering primitives (capability detection, palette/markers, emitters) ──
+# Additive: nothing below calls these yet. `FANCY=1` only when stdout (fd 1)
+# is a real terminal AND `NO_COLOR` is unset — any pipe/redirect/non-tty
+# stdout, or `NO_COLOR` set to any value, gives plain ASCII with no escape
+# codes, per the NO_COLOR convention (https://no-color.org).
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then FANCY=1; else FANCY=0; fi
+
+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="❌"
+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]"
+fi
+
+# emit_transition <from> <to> <files> — a captured state-to-state move. The
+# "→" separator is literal (not FANCY-dependent) — the same separator the
+# engine's commit grammar itself uses, per the package spec.
+emit_transition() {
+  local from="$1" to="$2" files="$3"
+  if [[ -n "$files" ]]; then
+    printf '%s  %s%s → %s%s  (%s%s%s)\n' \
+      "$M_TRANS" "$C_BOLD$C_CYAN" "$from" "$to" "$C_RESET" \
+      "$C_DIM" "$files" "$C_RESET"
+  else
+    printf '%s  %s%s → %s%s\n' \
+      "$M_TRANS" "$C_BOLD$C_CYAN" "$from" "$to" "$C_RESET"
+  fi
+}
+
+# emit_action <marker> <label> — the heartbeat printed before a turn runs.
+emit_action() {
+  local marker="$1" label="$2"
+  printf '%s %s%s\n' "$marker" "$label" "$C_RESET"
+}
+
+# emit_commit <subject> <files> — a non-transition capture (a bare-subject
+# self-loop, or the squash's agent-authored final commit).
+emit_commit() {
+  local subject="$1" files="$2"
+  if [[ -n "$files" ]]; then
+    printf '%s %s%s%s  (%s%s%s)\n' "$M_COMMIT" "$C_GREEN" "$subject" "$C_RESET" \
+      "$C_DIM" "$files" "$C_RESET"
+  else
+    printf '%s %s%s%s\n' "$M_COMMIT" "$C_GREEN" "$subject" "$C_RESET"
+  fi
+}
+
+# emit_gate <state> <message> — the human-instruction line at a message rest.
+emit_gate() {
+  local message="$2"
+  printf '%s  %s%s%s\n' "$M_HUMAN" "$C_BOLD$C_YELLOW" "$message" "$C_RESET"
+}
+
+# emit_settled <state> — the terminal "nothing left to do" signal.
+emit_settled() {
+  printf '%s %ssettled — nothing left to do%s\n' "$M_SETTLE" "$C_GREEN" "$C_RESET"
+}
+
+# emit_error <message> — refusals/stalls/failures, to stderr; <message> may be
+# multi-line and is passed through verbatim.
+emit_error() {
+  local message="$1"
+  printf '%s %s%s%s\n' "$M_ERROR" "$C_RED" "$message" "$C_RESET" >&2
+}
+
+# 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_log_pointer() {
+  if [[ "$FANCY" == 1 ]]; then
+    printf '%s📄 see %s%s\n' "$C_DIM" "$GTD_LOOP_LOG" "$C_RESET" >&2
+  else
+    printf '%ssee %s%s\n' "$C_DIM" "$GTD_LOOP_LOG" "$C_RESET" >&2
+  fi
+}
+
+# ── Git-derivation helpers (parse_subject, report_commits) ──────────────────
+# Additive: nothing below calls these yet. Replaces today's
+# head_before/head_after string comparisons in a later change.
+
+# parse_subject <subject> — sets S_ACTOR / S_FROM / S_TO / S_KIND. Patterns are
+# held in variables (rather than inlined) so bash's [[ =~ ]] doesn't need the
+# literal parens/spaces quoted inline.
+parse_subject() {
+  local subject="$1"
+  local transition_re='^gtd\(([^)]+)\): (.+) → (.+)$'
+  local capture_re='^gtd\(([^)]+)\): (.+)$'
+  S_ACTOR="" S_FROM="" S_TO="" S_KIND=""
+  if [[ "$subject" =~ $transition_re ]]; then
+    S_KIND=transition
+    S_ACTOR="${BASH_REMATCH[1]}"
+    S_FROM="${BASH_REMATCH[2]}"
+    S_TO="${BASH_REMATCH[3]}"
+  elif [[ "$subject" =~ $capture_re ]]; then
+    S_KIND=capture
+    S_ACTOR="${BASH_REMATCH[1]}"
+    S_TO="${BASH_REMATCH[2]}"
+  else
+    S_KIND=squash
+    S_TO="$subject"
+  fi
+}
+
+# report_commits <head_before> — walks <head_before>..HEAD in order, emitting
+# a transition/commit line per new commit; returns non-zero (having emitted
+# nothing) when there were no new commits.
+report_commits() {
+  local head_before="$1" sha subject files reported=0
+  while IFS= read -r sha; do
+    [[ -z "$sha" ]] && continue
+    reported=1
+    subject="$(git log -1 --format=%s "$sha")"
+    files="$(git diff-tree --no-commit-id --name-only -r "$sha" | paste -sd, - | sed 's/,/, /g')"
+    parse_subject "$subject"
+    case "$S_KIND" in
+      transition) emit_transition "$S_FROM" "$S_TO" "$files" ;;
+      capture | squash) emit_commit "$subject" "$files" ;;
+    esac
+  done < <(git rev-list --reverse "$head_before"..HEAD)
+  [[ "$reported" == 1 ]]
+}
+
+# ── Log file (resolve_log_path, gtd log) ────────────────────────────────────
+
+# resolve_log_path — echoes the loop's logfile path: $GTD_LOOP_LOG verbatim if
+# set, else "$(git rev-parse --git-dir)/gtd-loop.log" (per-repository AND
+# per-worktree automatically, since a linked worktree's git-dir is its own
+# private .git/worktrees/<name>).
+resolve_log_path() {
+  if [[ -n "${GTD_LOOP_LOG:-}" ]]; then
+    echo "$GTD_LOOP_LOG"
+  else
+    echo "$(git rev-parse --git-dir)/gtd-loop.log"
+  fi
+}
+
+# --no-edit / GTD_NO_EDIT govern only the loop's automatic editor launching at
+# human gates (see handle_human_gate further down) — `gtd edit` itself never
+# reads either. `--no-edit` is recognised in exactly the two sanctioned
+# positions (bare, or right after `loop`) and stripped before anything below
+# looks at "$@", so the bundle's own unknown-option guard never sees it.
+edit_disabled=0
+[[ -n "${GTD_NO_EDIT:-}" ]] && edit_disabled=1
+if [[ "${1:-}" == "--no-edit" && $# -eq 1 ]]; then
+  edit_disabled=1
+  shift
+elif [[ "${1:-}" == "loop" && "${2:-}" == "--no-edit" && $# -eq 2 ]]; then
+  edit_disabled=1
+  set -- loop
+fi
+
+if [[ "${1:-}" == "edit" ]]; then
+  shift
+  if [[ $# -gt 0 ]]; then
+    launch_editor "$1"
+  else
+    if ! peek_json="$(run_gtd next --json 2>&1)"; then
+      echo "gtd edit: could not determine the next step:" >&2
+      echo "$peek_json" >&2
+      exit 1
+    fi
+    file="$(jq -r '.file // empty' <<<"$peek_json")"
+    launch_editor "${file:-.}"
+  fi
+  exit 0
+fi
+
+if [[ "${1:-}" == "log" ]]; then
+  shift
+  if [[ $# -gt 0 ]]; then
+    echo "gtd log: takes no arguments" >&2
+    exit 2
+  fi
+  log_path="$(resolve_log_path)"
+  if [[ ! -f "$log_path" ]]; then
+    echo "gtd log: no loop log yet at $log_path" >&2
+    exit 1
+  fi
+  launch_editor "$log_path"
+  exit 0
+fi
+
 if [[ $# -gt 0 && "$1" != "loop" ]]; then
   run_gtd "$@"
   exit $?
@@ -33,12 +250,16 @@ if [[ "${1:-}" == "loop" && $# -gt 1 ]]; then
   echo "gtd: 'loop' takes no arguments" >&2
   exit 2
 fi
-# otherwise ($# -eq 0, or exactly "loop" with no further args): fall through
-# into the existing loop body below, unchanged in behavior.
+# otherwise ($# -eq 0, or exactly "loop" with no further args, --no-edit
+# already stripped above): fall through into the existing loop body below,
+# unchanged in behavior.
 
 # Drives the v3 pattern-machine loop (see docs/loop.md): each iteration asks
 # `gtd next --json` who's up and what they should do, dispatching on `kind`:
-#   - "message" (a human rest)  -> halt, tell the user what gtd is waiting on.
+#   - "message" (a human rest)  -> see handle_human_gate above: with editing on
+#     (the default) open the editor at the gate and step human, driving on a
+#     captured commit; with editing off (--no-edit/GTD_NO_EDIT), halt and tell
+#     the user what gtd is waiting on, unchanged from before this feature.
 #   - "script"  (a check rest) -> execute `content` (the emitted wrapper
 #     script) verbatim via bash — exit code deliberately ignored, the outcome
 #     lives in the tree — then `gtd step <actor>` to capture it; zero new
@@ -101,6 +322,60 @@ herdr_release() {  # hand the pane back to Herdr's normal detection
   herdr_run pane release-agent "$HERDR_PANE_ID" --source herdr:gtd --agent gtd
 }
 
+# Shared human-gate handler for a "message" (human) rest — used both by the
+# opening move (when editing is on) and by every "message" rest the main loop
+# encounters. $1 is the rest's `next --json` blob.
+#
+# Editing OFF ($edit_disabled): today's behavior, unchanged — render the gate
+# via emit_gate and exit 0 without touching an editor.
+#
+# Editing ON (the default): open the editor on the rest's `.file` (or `.` when
+# absent), wait for it to exit, then run `gtd step human`:
+#   - a NEW commit was authored -> return normally so the caller keeps driving.
+#   - ZERO commits were authored -> halt, exit 0 (closing the editor without a
+#     capturable change means "done for now" — and keeps a gate with no `C`
+#     pattern, e.g. idle, from being reopened forever).
+#   - the step REFUSES (non-zero exit: malformed steering file, unfinished
+#     review) -> surface it verbatim and halt, exit non-zero — the same
+#     wording an opening-move refusal already used before this function
+#     existed.
+handle_human_gate() {
+  local json="$1" file label state step_out head_before head_after
+  label="$(jq -r '.label // .state' <<<"$json")"
+  state="$(jq -r .state <<<"$json")"
+
+  if [[ "$edit_disabled" == 1 ]]; then
+    herdr_report blocked "$label"
+    herdr_notify "gtd needs you — $(basename "$PWD")" "$label"
+    emit_gate "$state" "$label"
+    run_gtd next
+    exit 0
+  fi
+
+  file="$(jq -r '.file // empty' <<<"$json")"
+  herdr_report working "$label"
+  launch_editor "${file:-.}"
+
+  head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
+  if ! step_out="$(run_gtd 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."
+    emit_log_pointer
+    exit 1
+  fi
+  head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
+  if [[ "$head_before" == "$head_after" ]]; then
+    herdr_report idle "$label"
+    herdr_release
+    emit_action "$M_HUMAN" "done for now (nothing captured)"
+    exit 0
+  fi
+  # A new commit was captured — render it, then return normally so the
+  # caller keeps driving.
+  report_commits "$head_before"
+}
+
 trap 'code=$?; if [ "$code" -ne 0 ]; then
         herdr_report blocked "${GTD_LAST_LABEL:-stopped}: exited $code"
         herdr_notify "gtd stopped — $(basename "$PWD")" "${GTD_LAST_LABEL:-loop} failed (exit $code)"
@@ -112,6 +387,17 @@ prev_content=""
 # across iterations and across restarts. In the git dir, never the work tree.
 memory_marker="$(git rev-parse --git-dir 2>/dev/null || echo .git)/gtd-loop-memory"
 
+# Truncated once here (not every iteration), so the file always reflects the
+# current run but survives after the loop exits for a later `gtd log`.
+log_path="$(resolve_log_path)"
+: >"$log_path"
+export GTD_LOOP_LOG="$log_path"
+if [[ "$FANCY" == 1 ]]; then
+  printf '%s📄 log: %s  (tail -f to follow)%s\n' "$C_DIM" "$log_path" "$C_RESET"
+else
+  printf '%slog: %s  (tail -f to follow)%s\n' "$C_DIM" "$log_path" "$C_RESET"
+fi
+
 # Swappable agent adapter: GTD_LOOP_AGENT_CMD lets any coding agent CLI stand
 # in for the default, receiving the prompt via $GTD_LOOP_PROMPT, the state's
 # opaque model hint (if any) via $GTD_LOOP_MODEL, and the memory scope via
@@ -137,7 +423,8 @@ run_agent_turn() {
     cmd="$cmd"' --dangerously-skip-permissions'
   fi
   GTD_LOOP_PROMPT="$prompt" GTD_LOOP_MODEL="$model" GTD_LOOP_MEMORY="$memory" \
-    GTD_LOOP_SESSION_ID="$session_id" GTD_LOOP_MEMORY_RESUME="$do_resume" bash -c "$cmd"
+    GTD_LOOP_SESSION_ID="$session_id" GTD_LOOP_MEMORY_RESUME="$do_resume" bash -c "$cmd" \
+    >>"${GTD_LOOP_LOG:-/dev/null}" 2>&1
 }
 
 # Opening move: capture the human's pending edit so gtd-loop is the ONLY command
@@ -154,18 +441,30 @@ run_agent_turn() {
 # a harmless no-op; a genuine refusal there (a malformed steering file, or an
 # edit no `on` pattern accepts) is surfaced and stops the loop rather than being
 # driven past.
+#
+# Editing ON: route through the exact same gate logic the main loop uses below
+# (open the editor there first, THEN step) instead of blindly stepping human
+# and moving on. Editing OFF: unchanged from before this function existed —
+# step silently, refusal surfaced and halts, a clean/committed gate just falls
+# into the loop below.
 if ! peek_json="$(run_gtd next --json 2>&1)"; then
-  echo "gtd-loop: could not determine the next step:" >&2
-  echo "$peek_json" >&2
-  echo "Run \`gtd status\` to inspect the repo." >&2
+  emit_error "could not determine the next step:
+$peek_json
+Run \`gtd status\` to inspect the repo."
+  emit_log_pointer
   exit 1
 fi
 if [[ "$(jq -r .kind <<<"$peek_json")" == "message" ]]; then
-  if ! step_out="$(run_gtd step human 2>&1)"; then
-    echo "gtd-loop: could not capture your changes at the human gate:" >&2
-    echo "$step_out" >&2
-    echo "Fix the reported issue and re-run gtd-loop." >&2
-    exit 1
+  if [[ "$edit_disabled" == 1 ]]; then
+    if ! step_out="$(run_gtd 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."
+      emit_log_pointer
+      exit 1
+    fi
+  else
+    handle_human_gate "$peek_json"
   fi
 fi
 
@@ -186,31 +485,34 @@ while true; do
   label="$(jq -r '.label // .state' <<<"$next_json")"
   GTD_LAST_LABEL="$label"
 
-  if [[ "$kind" != "message" ]]; then
-    herdr_report working "$label"
-  fi
-
   if [[ "$kind" == "message" ]]; then
-    herdr_report blocked "$label"
-    herdr_notify "gtd needs you — $(basename "$PWD")" "$label"
-    echo "--- Your turn ($state) ---"
-    run_gtd next
-    exit 0
+    # handle_human_gate exits 0/non-zero itself on a halt/refusal; it only
+    # returns here when a new commit was captured, so we keep driving.
+    handle_human_gate "$next_json"
+    continue
   fi
 
+  herdr_report working "$label"
+
   if [[ "$kind" == "script" ]]; then
+    emit_action "$M_CHECK" "$label"
     head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
     # 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.
-    bash -c "$content" || true
-    run_gtd step "$actor" >/dev/null
-    head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
-    if [[ "$head_before" == "$head_after" ]]; then
+    # own `on` patterns. Its own output goes to the log, not the terminal.
+    bash -c "$content" >>"$GTD_LOOP_LOG" 2>&1 || true
+    if ! step_out="$(run_gtd step "$actor" 2>&1)"; then
+      printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
+      emit_error "$step_out"
+      emit_log_pointer
+      exit 1
+    fi
+    printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
+    if ! report_commits "$head_before"; then
       herdr_report idle "$label"
       herdr_release
-      echo "--- Settled ($state: check passed, nothing to do) ---"
+      emit_settled "$state"
       exit 0
     fi
     prev_state=""
@@ -222,8 +524,10 @@ while true; do
   # agent-owned state and content repeating means the last dispatch made no
   # progress; stop rather than spin on it.
   if [[ "$state" == "$prev_state" && "$content" == "$prev_content" ]]; then
-    echo "gtd-loop: no progress at '$state' — the agent's last turn changed nothing. Stopping to avoid spinning." >&2
-    run_gtd next >&2
+    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.
+$next_out"
+    emit_log_pointer
     exit 1
   fi
   prev_state="$state"
@@ -263,23 +567,37 @@ while true; do
   # 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"
+  head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
   run_agent_turn "$content" "$resume"
 
   fix_attempt=0
   while ! validate_out="$(run_gtd validate 2>&1)"; do
     fix_attempt=$((fix_attempt + 1))
     if ((fix_attempt > 3)); then
-      echo "gtd-loop: '$state' still fails \`gtd validate\` after 3 fix attempts:" >&2
-      echo "$validate_out" >&2
-      echo "Stopping rather than stepping with a malformed steering file." >&2
+      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
     # 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"
   done
 
-  run_gtd step "$actor" >/dev/null
+  if ! step_out="$(run_gtd step "$actor" 2>&1)"; then
+    printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
+    emit_error "$step_out"
+    emit_log_pointer
+    exit 1
+  fi
+  printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
+  # A no-op step (nothing matched a declared pattern on a clean tree) reports
+  # zero commits here — report_commits returns non-zero, and that's fine: the
+  # NEXT iteration's stall check is what catches unchanged state/content.
+  report_commits "$head_before" || true
 done

package/dist/gtd.bundle.mjs

@@ -205428,6 +205428,10 @@ Commands:
                    an agent through gtd next/gtd step calls until the
                    workflow returns to its initial state again. A bare gtd
                    invocation and gtd loop both launch it identically
+  edit [path]      Open \${VISUAL:-$EDITOR} on <path>, or — with no path — on
+                   the resolved rest's declared file (or the repo directory
+                   if it declares none). Handled entirely by bin/gtd, not
+                   this bundle
   init             Scaffold a minimal .gtdrc.json for this repo, seeding the
                    default variables you are most likely to change (the test
                    command) and a Prettier formatting suggestion. gtd runs its

package/docs/cli.md

@@ -45,6 +45,10 @@ Commands:
                    commits that would be lost
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
+  edit [path]      Open <path> (repo-relative) in $VISUAL/$EDITOR, blocking
+                   until the editor exits. With no argument, opens the
+                   resolved rest's declared file (or the repo root if it
+                   declares none). Never reads --no-edit/GTD_NO_EDIT
   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
@@ -63,6 +67,8 @@ Options:
   --no-open        (gtd visualize only) do not open the browser
   --cost=<n>       (gtd step only) record the invocation's token cost
   --model=<name>   (gtd step only, with --cost) tag that cost's model
+  --no-edit        (bare gtd or gtd loop only) disable the loop's automatic
+                   editor launching at human gates
   --version, -v    Print version and exit
   --help, -h       Print this help and exit
 ```
@@ -79,12 +85,32 @@ history relative to cwd, so it refuses with a clear error if invoked from a
 subdirectory.
 
 `--json`, `--cost=<n>`, and `--model=<name>` (the latter two only for
-`gtd step`) are the only long options. Any other `--` option (including a typo
-like `--jsn`) is rejected with a usage error rather than silently ignored, so a
-mistyped flag can never degrade a JSON caller to plain-text mode. A bare
-`--cost`/`--model` with no value, a non-numeric or negative `--cost`, an empty
-`--model`, `--model` without `--cost`, or either flag on any command other than
-`gtd step` are all usage errors.
+`gtd step`) are the only long options the compiled bundle recognizes. Any other
+`--` option (including a typo like `--jsn`) is rejected with a usage error
+rather than silently ignored, so a mistyped flag can never degrade a JSON caller
+to plain-text mode. A bare `--cost`/`--model` with no value, a non-numeric or
+negative `--cost`, an empty `--model`, `--model` without `--cost`, or either
+flag on any command other than `gtd step` are all usage errors.
+
+`--no-edit` is a separate, bash-level flag handled entirely by `bin/gtd` itself,
+stripped before anything reaches the bundle — see [`--no-edit`](#--no-edit)
+below.
+
+## `--no-edit`
+
+A flag on the loop driver only — bare `gtd --no-edit` or `gtd loop --no-edit`
+(the two are equivalent, since bare `gtd` and `gtd loop` are themselves
+equivalent). Recognized in exactly those two positions; any other
+placement/combination (e.g. `gtd step --no-edit`, or combined with any other
+argument) is a usage error. The `GTD_NO_EDIT` environment variable (any
+non-empty value) does the same thing.
+
+Disables the loop's default behavior of launching an editor at human gates,
+restoring the previous halt-and-print-and-exit behavior with no editor involved.
+It governs only the loop's own automatic launching — `gtd edit` invoked directly
+never reads it (see [`gtd edit`](#gtd-edit-path) above). See
+[Driving the loop](loop.md) and `skills/loop/SKILL.md` for the full gate-flow
+description.
 
 ## `gtd init`
 
@@ -408,6 +434,40 @@ which are JSON-only. `--json` emits
   when the state has no `on` (a commit state); a per-edge `describe` is likewise
   omitted when that edge declares none.
 
+## `gtd edit [path]`
+
+Handled entirely in `bin/gtd`'s own bash — unlike every other subcommand, it is
+**never forwarded** to the compiled bundle (`dist/gtd.bundle.mjs`).
+
+With `<path>` given (repo-relative), opens it in `${VISUAL:-$EDITOR}` (git's own
+precedence — `$VISUAL` first, then `$EDITOR`; no fallback to `vi`), blocking in
+the foreground until the editor exits. It creates nothing if `<path>` doesn't
+exist — the path is handed straight to the editor command verbatim. The editor's
+own exit code is ignored entirely; success is judged from tree state afterward,
+not from this command.
+
+With no argument, it peeks with `gtd next --json` to find the resolved rest's
+declared `.file`, and opens that (repo-relative), or the repo directory (`.`)
+when the resolved state declares no `file:`. If `gtd next --json` itself fails
+(e.g. not in a repo), it prints an error and exits non-zero without attempting
+to open an editor:
+
+```
+gtd edit: could not determine the next step:
+<gtd next --json's own error output>
+```
+
+`gtd edit` **never** reads `--no-edit`/`GTD_NO_EDIT` — those two govern only the
+loop's own automatic editor launching at human gates (see
+[Driving the loop](loop.md) and `skills/loop/SKILL.md`), not this command.
+Invoked directly, `gtd edit` always launches, unconditionally.
+
+If neither `$VISUAL` nor `$EDITOR` is set, no editor is launched:
+
+```
+gtd: no editor configured — set $EDITOR (or $VISUAL)
+```
+
 ## Running `script` rests (no `gtd` subcommand)
 
 There is no `gtd` subcommand that executes a workflow script — gtd never runs a

package/docs/loop.md

@@ -41,16 +41,35 @@ loop picks their change up.
 
 **A `"message"` rest is a real handoff, not a slow beat.** No driver signs off
 for the human: in the bundled workflow the loop runs the whole cycle unattended
-up to `await-review` and then STOPS there with the review checkout window open
+up to `await-review` and then rests there with the review checkout window open
 (the reviewable diff surfaced as uncommitted changes — see
 [STATES.md §11](../STATES.md#11-the-review-checkout-window)). Advancing takes a
 human edit to `.gtd/REVIEW.md`: ticking every box with **no** comment signs off
 into the squash finale, while any comment (a note, or a code edit of your own)
-is feedback that routes into another build + re-review round. Re-launching the
-loop after that edit picks the decision up. Until then the loop halts on every
-run — that is the contract, not a stall. A review nobody is going to finish is
-ended with [`gtd abandon`](cli.md#gtd-abandon---json), which drops the process's
-commits and keeps their content as uncommitted changes.
+is feedback that routes into another build + re-review round. That gate is the
+contract, not a stall — nothing advances until the edit is captured, whether the
+capture happens within the same run or a later one. A review nobody is going to
+finish is ended with [`gtd abandon`](cli.md#gtd-abandon---json), which drops the
+process's commits and keeps their content as uncommitted changes.
+
+**Editing is on by default.** Reaching a `"message"` rest, `bin/gtd` opens
+`${VISUAL:-$EDITOR}` on the rest's declared `.file` (or the repo root `.` when
+the state declares none), blocking until the editor exits, then runs
+`gtd step human` to capture whatever changed:
+
+- a new commit was captured → the loop keeps driving on its own; re-launching is
+  never necessary;
+- zero commits were captured (a clean tree once the editor closed) → the loop
+  halts, exit 0 — "done for now";
+- the step refuses (a malformed steering file, or an edit matching no declared
+  pattern) → the refusal is surfaced verbatim and the loop halts non-zero,
+  exactly as a manual `gtd step human` refusal would.
+
+Set `GTD_NO_EDIT` (any non-empty value), or pass `--no-edit` — see
+[`cli.md`'s `--no-edit`](cli.md#--no-edit) for its exact syntax and positioning
+— to disable this and restore the original halt-and-print behavior: the loop
+prints the gate via `gtd next` and exits 0 without touching an editor, leaving
+the human to edit and re-launch the loop themselves.
 
 ```bash
 gtd next --json   # ask who's up and what they should do
@@ -73,16 +92,18 @@ when the machine rests at a `"message"` gate — so `gtd` is the only command a
 human runs. `bin/gtd` is the packaged entry point: invoked bare, or with `loop`
 as its first argument, it runs this exact script; any other first argument (e.g.
 `next`, `step`, `status`) hands off to `node dist/gtd.bundle.mjs` instead. The
-loop body it runs adds four things on top of the reference script above: it
-stops with a diagnostic if the same `"prompt"` state/content repeat with no
-progress (see `skills/loop/SKILL.md`'s "Stall detection"); it lets
-`GTD_LOOP_AGENT_CMD` swap in any coding agent CLI in place of the default
-`claude -p`, receiving the prompt via `$GTD_LOOP_PROMPT`; it exports the
-resolved state's optional `model` hint as `$GTD_LOOP_MODEL`, appending
-`--model "$GTD_LOOP_MODEL"` to the default `claude -p` invocation whenever it's
-non-empty; and it acts on the optional `memory` scope hint (see "Agent memory
-scope" below) — continuing one agent session across consecutive same-scope turns
-and starting fresh when the scope changes.
+loop body it runs adds five things on top of the reference script above: it
+opens an editor at every `"message"` gate instead of just printing it (see
+"Editing is on by default" above; `--no-edit`/`GTD_NO_EDIT` fall back to the
+reference script's plain print-and-exit); it stops with a diagnostic if the same
+`"prompt"` state/content repeat with no progress (see `skills/loop/SKILL.md`'s
+"Stall detection"); it lets `GTD_LOOP_AGENT_CMD` swap in any coding agent CLI in
+place of the default `claude -p`, receiving the prompt via `$GTD_LOOP_PROMPT`;
+it exports the resolved state's optional `model` hint as `$GTD_LOOP_MODEL`,
+appending `--model "$GTD_LOOP_MODEL"` to the default `claude -p` invocation
+whenever it's non-empty; and it acts on the optional `memory` scope hint (see
+"Agent memory scope" below) — continuing one agent session across consecutive
+same-scope turns and starting fresh when the scope changes.
 
 `bin/gtd` resolves both its bundle hand-off and the loop's own internal `gtd`
 calls against `dist/gtd.bundle.mjs` next to its own location. Set `GTD_BIN` — a
@@ -116,7 +137,7 @@ while true; do
   content="$(jq -r .content <<<"$next_json")"
 
   if [[ "$kind" == "message" ]]; then
-    echo "--- Your turn ($state) ---"
+    echo "your turn ($state)"    # bin/gtd renders this via emit_gate instead
     gtd next
     exit 0
   fi
@@ -127,7 +148,7 @@ while true; do
     gtd step "$actor" >/dev/null # capture whatever it left in the tree
     head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
     if [[ "$head_before" == "$head_after" ]]; then
-      echo "--- Settled ($state: check passed, nothing to do) ---"
+      echo "settled ($state: check passed, nothing to do)"   # bin/gtd renders this via emit_settled instead
       exit 0
     fi
     continue
@@ -143,6 +164,29 @@ The driver — not the prompt text — owns ending the agent's turn
 (`gtd step "$actor"` right after the agent acts): every default-workflow agent
 prompt says explicitly not to run `gtd step agent` itself.
 
+`bin/gtd log` opens the current repo/worktree's loop logfile —
+`"$(git rev-parse --git-dir)/gtd-loop.log"` by default, or `$GTD_LOOP_LOG`
+verbatim when set — in `${VISUAL:-$EDITOR}`, the same editor resolution
+`bin/gtd edit` uses. It takes no arguments and errors out (rather than opening
+an empty buffer) if no loop has produced a log yet.
+
+## Rendered output and logging
+
+`bin/gtd` detects its output capability once at startup (`FANCY`, true when
+stdout is a real terminal AND `NO_COLOR` is unset): on a real terminal it prints
+one colored/emoji line per event, and under `NO_COLOR` or a piped/redirected
+stdout it prints the same events as plain ASCII with no escape codes, per the
+[NO_COLOR convention](https://no-color.org). Normal events (a state transition,
+a captured commit, an agent/check turn starting, settling at idle) render to
+stdout; refusals, stalls, and validate-cap halts render to stderr, each followed
+by a `📄 see <log>` pointer (plain: `see <log>`).
+
+The three previously terminal-visible subprocess streams — the agent turn's own
+output, the check script's own output, and `gtd step`'s own output — are no
+longer printed directly: they're appended to the per-repo/per-worktree log file
+(truncated once at the start of the run) instead, and surfaced with
+`bin/gtd log` above.
+
 ## Agent memory scope
 
 A `"prompt"` beat may carry an optional `memory` key — an opaque scope label the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "7.4.2",
+  "version": "7.6.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {