@pmelab/gtd 7.6.3 → 7.7.0

package/README.md

@@ -108,7 +108,9 @@ handful of commands drive it:
   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.
+  blocking until it exits. Low-level plumbing — for "force an edit at the
+  current human gate, then keep driving", pass `--edit` to the loop instead (see
+  below).
 
 `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
@@ -181,8 +183,12 @@ 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
+yourself; pass `--edit`/`-e` to force the editor open at the gate right now,
+overriding an ambient `GTD_NO_EDIT`/`--no-edit`. Pass `--once` to restrict a run
+to exactly one beat — one human gate, one check, or one agent turn — instead of
+driving all the way to idle; it combines freely with `--edit`/`--no-edit`. 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).

package/bin/gtd

@@ -3,21 +3,29 @@ 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.
+#   - `--no-edit` / `--edit` (`-e`) / `--once` (bare, or immediately after
+#     `loop`, in any order/combination — see the flag-parsing block below) ->
+#     stripped here; `--no-edit` disables the loop's automatic editor
+#     launching for this run, `--edit` forces it on for this run (overriding
+#     an ambient `GTD_NO_EDIT`/`--no-edit` — the two are mutually exclusive),
+#     and `--once` restricts the loop to exactly one beat (one human gate, one
+#     script check+step, or one agent prompt+step) before exiting. Dispatch
+#     then continues on the remaining arguments as if none of them had ever
+#     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).
+#     resolved rest's `.file` (or `.` when absent). Low-level plumbing now that
+#     `--edit` covers the common "force an edit, then keep driving" case; this
+#     subcommand remains for opening a specific path, or the current rest's
+#     file, WITHOUT driving the loop afterward.
 #   - `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 (other than a lone `--no-edit`) ->
-#     usage error, exit 2.
+#   - no arguments, or exactly `loop` with no further arguments (other than the
+#     flags above) -> 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`).
 # `run_gtd` is the ONE place that knows how to invoke "the bundle": by default
@@ -206,19 +214,59 @@ resolve_log_path() {
   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.
+# --no-edit / --edit (-e) / --once govern only the loop driver, recognised in
+# exactly two positions — bare (e.g. `gtd --edit --once`) or immediately after
+# `loop` (e.g. `gtd loop --once`) — in any order, each at most once. `--edit`
+# and `--no-edit` are mutually exclusive (forcing and suppressing the editor
+# in the same run is not a coherent request). A recognised, valid combination
+# is stripped here before anything below looks at "$@", so the bundle's own
+# unknown-option guard never sees it; anything else (an unknown flag, a
+# duplicate/conflicting one, or a flag mixed with a real subcommand) is left
+# untouched and falls through to the existing dispatch below, which forwards a
+# non-flag first argument to the bundle (whose own unknown-option guard
+# rejects it) or rejects a `loop` invocation carrying an unrecognised extra
+# argument.
 edit_disabled=0
+edit_forced=0
+once_mode=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
+
+if [[ "${1:-}" == "loop" ]]; then
+  loop_form=1
+  loop_flag_args=("${@:2}")
+else
+  loop_form=0
+  loop_flag_args=("$@")
+fi
+
+valid_combo=1
+n_no_edit=0
+n_edit=0
+n_once=0
+for a in ${loop_flag_args[@]+"${loop_flag_args[@]}"}; do
+  case "$a" in
+  --no-edit) n_no_edit=$((n_no_edit + 1)) ;;
+  --edit | -e) n_edit=$((n_edit + 1)) ;;
+  --once) n_once=$((n_once + 1)) ;;
+  *) valid_combo=0 ;;
+  esac
+done
+if ((n_no_edit > 1 || n_edit > 1 || n_once > 1 || (n_no_edit >= 1 && n_edit >= 1))); then
+  valid_combo=0
+fi
+
+if [[ "$valid_combo" == 1 ]]; then
+  ((n_no_edit >= 1)) && edit_disabled=1
+  ((n_edit >= 1)) && edit_forced=1
+  ((n_once >= 1)) && once_mode=1
+  # --edit overrides an ambient GTD_NO_EDIT/--no-edit for THIS run — the
+  # explicit ask to force the editor wins over the suppressing default.
+  ((edit_forced)) && edit_disabled=0
+  if [[ "$loop_form" == 1 ]]; then
+    set -- loop
+  else
+    set --
+  fi
 fi
 
 if [[ "${1:-}" == "edit" ]]; then
@@ -382,8 +430,12 @@ Fix the reported issue and re-run gtd-loop."
     exit 0
   fi
   # A new commit was captured — render it, then return normally so the
-  # caller keeps driving.
+  # caller keeps driving, unless --once says this one human gate is the whole
+  # run.
   report_commits "$head_before"
+  if [[ "$once_mode" == 1 ]]; then
+    exit 0
+  fi
 }
 
 trap 'code=$?; if [ "$code" -ne 0 ]; then
@@ -456,7 +508,10 @@ run_agent_turn() {
 # (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.
+# into the loop below. Either way, --once treats a captured commit here as the
+# run's one beat and exits (see handle_human_gate's own once-mode exit for the
+# editing-ON path); a clean/no-op gate captures nothing, so it isn't a beat —
+# it falls into the loop below exactly as it would without --once.
 if ! peek_json="$(run_gtd next --json 2>&1)"; then
   emit_error "could not determine the next step:
 $peek_json
@@ -464,8 +519,10 @@ Run \`gtd status\` to inspect the repo."
   emit_log_pointer
   exit 1
 fi
-if [[ "$(jq -r .kind <<<"$peek_json")" == "message" ]]; then
+peek_kind="$(jq -r .kind <<<"$peek_json")"
+if [[ "$peek_kind" == "message" ]]; then
   if [[ "$edit_disabled" == 1 ]]; then
+    opening_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
@@ -473,9 +530,21 @@ Fix the reported issue and re-run gtd-loop."
       emit_log_pointer
       exit 1
     fi
+    if [[ "$once_mode" == 1 && "$opening_head_before" != "$(git rev-parse HEAD 2>/dev/null || echo none)" ]]; then
+      exit 0
+    fi
   else
     handle_human_gate "$peek_json"
   fi
+elif [[ "$edit_forced" == 1 ]]; then
+  # Honesty caveat: a forced edit only means something at a human gate — the
+  # machine isn't resting at one right now, so say so instead of pretending,
+  # and just keep driving.
+  if [[ "$FANCY" == 1 ]]; then
+    printf '%sℹ️  --edit: not at a human gate yet — continuing to drive%s\n' "$C_DIM" "$C_RESET"
+  else
+    printf '%s--edit: not at a human gate yet — continuing to drive%s\n' "$C_DIM" "$C_RESET"
+  fi
 fi
 
 while true; do
@@ -527,6 +596,9 @@ while true; do
     fi
     prev_state=""
     prev_content=""
+    if [[ "$once_mode" == 1 ]]; then
+      exit 0
+    fi
     continue
   fi
 
@@ -610,4 +682,7 @@ Stopping rather than stepping with a malformed steering file."
   # 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
+  if [[ "$once_mode" == 1 ]]; then
+    exit 0
+  fi
 done

package/docs/cli.md

@@ -48,7 +48,9 @@ Commands:
   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
+                   declares none). Never reads --no-edit/--edit/GTD_NO_EDIT.
+                   Low-level plumbing — --edit covers the common "force an
+                   edit, then keep driving" case
   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
@@ -69,6 +71,13 @@ Options:
   --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
+  --edit, -e       (bare gtd or gtd loop only) force the editor open at the
+                   current human gate, overriding --no-edit/GTD_NO_EDIT; a
+                   no-op note (not an error) when not at a human gate
+  --once           (bare gtd or gtd loop only) run exactly one loop beat (one
+                   human gate, one script check+step, or one agent
+                   prompt+step), then exit — combines freely with
+                   --edit/--no-edit
   --version, -v    Print version and exit
   --help, -h       Print this help and exit
 ```
@@ -92,25 +101,52 @@ 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)
+`--no-edit`, `--edit`/`-e`, and `--once` are separate, bash-level flags handled
+entirely by `bin/gtd` itself, stripped before anything reaches the bundle — see
 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.
+## `--no-edit`, `--edit`, `--once`
+
+Three flags on the loop driver only (`--edit` also has the short form `-e`),
+each recognized bare (`gtd --no-edit`) or immediately after `loop`
+(`gtd loop --no-edit`) — the two positions are equivalent, since bare `gtd` and
+`gtd loop` are themselves equivalent. All three combine freely with each other,
+in any order (e.g. `gtd --edit --once`, `gtd loop --once --edit`), except
+`--edit`/`--no-edit` together, which conflict (forcing and suppressing the
+editor in the same run is not a coherent request). Any other placement (e.g.
+`gtd step --once`), a duplicated flag (`gtd --once --once`), or the
+`--edit`/`--no-edit` conflict is a usage error, surfaced via whatever guard the
+misplaced argument first reaches (the compiled bundle's own
+unknown-option/unknown-command rejection for a misplaced flag, or
+`gtd: 'loop' takes no arguments` for one misplaced after `loop`) — never
+silently ignored or silently resolved one way.
+
+**`--no-edit`** (or the `GTD_NO_EDIT` environment variable, any non-empty value)
+disables the loop's default behavior of launching an editor at human gates,
+restoring the halt-and-print-and-exit behavior with no editor involved.
+
+**`--edit`** (`-e`) is `--no-edit`'s mirror: it forces the editor open at the
+current human gate, overriding an ambient `GTD_NO_EDIT`/`--no-edit` default for
+this one run. It is only meaningful when the machine currently rests at a human
+gate — the honesty caveat: at any other rest, forcing an edit is undefined, so
+`bin/gtd` prints a note that it isn't at a human gate yet and simply keeps
+driving, rather than pretending to force something. Both flags govern only the
+loop's own automatic launching — `gtd edit` invoked directly never reads either
+(see [`gtd edit`](#gtd-edit-path) above).
+
+**`--once`** restricts the loop to exactly one beat — one human gate, one script
+check+step, or one agent prompt+step — then exits, instead of driving all the
+way back to idle/settled. Precisely: at most one commit/transition is made;
+whichever of the three kinds the currently-resolved rest is, that one gets
+processed (including any internal `gtd validate` fix-reprompt rounds a producing
+agent turn needs — those are all part of finishing the ONE prompt beat, not
+separate beats) and the loop exits 0 immediately after, without re-peeking at
+what comes next. A clean human gate with nothing to capture (the opening move's
+silent capture attempt under `--no-edit`, or a no-op editor session) is not a
+beat and falls through to the driver's ordinary halt, same as without `--once`.
+
+See [Driving the loop](loop.md) and `skills/loop/SKILL.md` for the full
+gate-flow description.
 
 ## `gtd init`
 
@@ -436,6 +472,12 @@ which are JSON-only. `--json` emits
 
 ## `gtd edit [path]`
 
+Low-level plumbing: for the common case of "force an edit at the current human
+gate, then keep driving the loop", use `--edit` (below) instead. `gtd edit`
+itself only opens an editor on a path — it never drives anything afterward,
+which makes it the right tool for opening a SPECIFIC path (or peeking at the
+current rest's file) without starting a loop.
+
 Handled entirely in `bin/gtd`'s own bash — unlike every other subcommand, it is
 **never forwarded** to the compiled bundle (`dist/gtd.bundle.mjs`).
 
@@ -457,8 +499,8 @@ 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
+`gtd edit` **never** reads `--no-edit`/`--edit`/`GTD_NO_EDIT` — those 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.
 

package/docs/loop.md

@@ -66,11 +66,25 @@ the state declares none), blocking until the editor exits, then runs
   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
+[`cli.md`](cli.md#--no-edit---edit---once) 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.
 
+Pass `--edit` (`-e`) to force the editor open at the current human gate right
+now, overriding an ambient `GTD_NO_EDIT`/`--no-edit` for this one run — useful
+when a shell profile sets `GTD_NO_EDIT` by default but you want to edit
+interactively just this once. It only means something when the machine is
+actually resting at a human gate: at any other rest, `bin/gtd` prints a note
+that it isn't at one yet and simply keeps driving, rather than pretending to
+force something undefined.
+
+Pass `--once` to restrict the loop to exactly one beat — one human gate, one
+script check+step, or one agent prompt+step — then exit, instead of driving all
+the way to idle/settled. It combines freely with `--edit`/`--no-edit` (e.g.
+`gtd --edit --once` forces the editor at the current gate, captures the edit,
+and stops right there rather than continuing to drive).
+
 ```bash
 gtd next --json   # ask who's up and what they should do
 ```
@@ -92,18 +106,21 @@ 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 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.
+loop body it runs adds six 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, while `--edit`/`-e` forces it on for this run
+even over an ambient `GTD_NO_EDIT`); it can restrict itself to exactly one beat
+via `--once` instead of driving to idle/settled; 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.6.3",
+  "version": "7.7.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {