@pmelab/gtd 7.4.2 → 7.5.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,10 +175,13 @@ 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
-[Driving the loop](docs/loop.md).
+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. See [Driving the loop](docs/loop.md).
 
 Before wiring gtd into a repo, note the
 [repository requirements](docs/cli.md#repository-requirements) — most

package/bin/gtd

@@ -3,9 +3,17 @@ 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).
 #   - 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 +33,55 @@ 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"
+}
+
+# --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 [[ $# -gt 0 && "$1" != "loop" ]]; then
   run_gtd "$@"
   exit $?
@@ -33,12 +90,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 +162,57 @@ 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 — print the 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"
+    echo "--- Your turn ($state) ---"
+    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
+    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
+  fi
+  head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
+  if [[ "$head_before" == "$head_after" ]]; then
+    herdr_report idle "$label"
+    herdr_release
+    echo "--- Done for now ($state: nothing captured) ---"
+    exit 0
+  fi
+  # else: a new commit was captured — return normally, caller keeps driving.
+}
+
 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)"
@@ -154,6 +266,12 @@ 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
@@ -161,11 +279,15 @@ if ! peek_json="$(run_gtd next --json 2>&1)"; then
   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
+      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
+    fi
+  else
+    handle_human_gate "$peek_json"
   fi
 fi
 
@@ -186,18 +308,15 @@ 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
     head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
     # Execute the emitted wrapper verbatim; its exit code is deliberately

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

package/package.json

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