@pmelab/gtd 6.3.0 → 6.4.0

package/README.md

@@ -113,7 +113,10 @@ globally in one place (a `vars:` edit or a `GTD_VAR_plannerModel` override)
 instead of per state.
 
 `gtd-loop`, installed alongside `gtd`, 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. See
+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).
 
 Before wiring gtd into a repo, note the

package/bin/gtd-loop

@@ -64,6 +64,35 @@ run_agent_turn() {
     GTD_LOOP_SESSION_ID="$session_id" GTD_LOOP_MEMORY_RESUME="$do_resume" bash -c "$cmd"
 }
 
+# Opening move: capture the human's pending edit so gtd-loop is the ONLY command
+# a human runs. A human acts at a gate by editing files (a plan answer, a review
+# tick, a code fix) and re-launching the loop — they should never have to run
+# `gtd step human` by hand first. So before driving, if the machine currently
+# rests at a human gate, step the human once to commit whatever they left, then
+# fall into the loop below from the resulting state.
+#
+# We peek with the pure, mutation-free `gtd next --json` and step ONLY when it
+# reports a human rest (`kind == "message"`): at an agent/check rest
+# `gtd step human` would refuse out-of-turn (non-zero, aborting under `set -e`),
+# and a mid-cycle restart must simply resume driving, not fail. A clean gate is
+# 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.
+if ! peek_json="$(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
+  exit 1
+fi
+if [[ "$(jq -r .kind <<<"$peek_json")" == "message" ]]; then
+  if ! step_out="$(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
+fi
+
 while true; do
   if ! next_json="$(gtd next --json 2>&1)"; then
     echo "gtd-loop: could not determine the next step:" >&2

package/docs/loop.md

@@ -28,8 +28,11 @@ A loop is a simple cycle:
 2. Repeat until a `"message"` rest halts the loop, or a zero-commit script step
    at idle settles it (the green terminal signal).
 
-A human acts by editing files (e.g. writing/editing `.gtd/TODO.md`, fixing code)
-and then running `gtd step human` to capture the edit as their turn.
+A human acts by editing files (e.g. writing/editing `.gtd/TODO.md`, fixing
+code); `gtd step human` captures the edit as their turn. A driver can run that
+capture for the human as its opening move (see below), so re-launching the loop
+is the only thing the human ever does — at a gate they edit and re-run, and the
+loop picks their change up.
 
 ```bash
 gtd next --json   # ask who's up and what they should do
@@ -46,7 +49,9 @@ A minimal bash implementation of the pinned protocol, driving an agent CLI (e.g.
 `claude -p`) against `gtd next --json` output. This is the authoritative
 reference for what a loop driver must do; keep any other implementation
 (including `skills/loop/SKILL.md`) consistent with it rather than editing both
-independently. `bin/gtd-loop` is this exact script, packaged as the `gtd-loop`
+independently. Both open with the same move — capture the human's pending edit
+when the machine rests at a `"message"` gate — so `gtd-loop` is the only command
+a human runs. `bin/gtd-loop` is this exact script, packaged as the `gtd-loop`
 binary, with four additions: 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
@@ -61,6 +66,17 @@ same-scope turns and starting fresh when the scope changes.
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Opening move: if the machine rests at a human gate, capture the human's
+# pending edit first, so re-launching the loop is the ONLY thing a human does
+# (they never run `gtd step human` by hand). Peek with the pure `gtd next
+# --json` and step only at a `"message"` rest — at an agent/check rest
+# `gtd step human` would refuse out-of-turn, and a mid-cycle restart must just
+# resume driving. A clean gate is a no-op; a genuine refusal (malformed steering
+# file, unrecognized edit) stops the loop instead of being driven past.
+if [[ "$(gtd next --json | jq -r .kind)" == "message" ]]; then
+  gtd step human >/dev/null
+fi
+
 while true; do
   next_json="$(gtd next --json)"
   state="$(jq -r .state <<<"$next_json")"

package/package.json

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