@pmelab/gtd 7.3.0 → 7.4.1

package/README.md

@@ -167,11 +167,11 @@ through two `vars` tiers — `plannerModel` (heavier planning and review) and
 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. 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
+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).
 
 Before wiring gtd into a repo, note the
@@ -196,7 +196,7 @@ Both halves are enforced by `gtd validate` and the `gtd step` gate.
 
 Herdr integration: a workflow state can declare an optional `label:` — a
 human-readable display name surfaced in `gtd next --json`/`gtd status`. The
-reference `bin/gtd-loop` driver uses it to report its lifecycle
+reference `bin/gtd` driver uses it to report its lifecycle
 (working/blocked/idle) to a [Herdr](https://herdr.dev) pane sidebar via the
 `herdr` CLI when running under Herdr (`HERDR_ENV=1`, a pane ID, and `herdr` on
 `$PATH`); outside Herdr this is a complete no-op. See
@@ -210,8 +210,8 @@ reporting contract.
   sub-machines, and the bundled workflow template
 - [CLI reference](docs/cli.md) — every command, exit codes, JSON schemas,
   repository requirements
-- [Driving the loop](docs/loop.md) — the reference loop driver, `gtd-loop`,
-  custom agents
+- [Driving the loop](docs/loop.md) — the reference loop driver,
+  `gtd`/`gtd loop`, custom agents
 - [Configuration](docs/configuration.md) — `gtd init`, the `.gtdrc` `workflow:`
   schema, lookup
 - [Upgrading](docs/upgrading.md) — breaking changes and migration

package/bin/{gtd-loop → gtd}

@@ -1,6 +1,41 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# This file is the single published `bin` entry: `bin/gtd`. Before anything
+# else, it dispatches on $1:
+#   - 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.
+#   - 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
+# it resolves `dist/gtd.bundle.mjs` relative to this script's own location
+# (not cwd), but `GTD_BIN` (a dev/test override for the whole invocation
+# command, e.g. `GTD_BIN="node $PWD/dev/run.mjs"`) takes precedence when set.
+# Every call the loop body makes below goes through `run_gtd` too, so the loop
+# always drives the exact same build/source it was launched from — no
+# dependence on a `gtd` binary being on PATH.
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
+
+run_gtd() {
+  if [[ -n "${GTD_BIN:-}" ]]; then
+    eval "$GTD_BIN" '"$@"'
+  else
+    node "$SCRIPT_DIR/../dist/gtd.bundle.mjs" "$@"
+  fi
+}
+
+if [[ $# -gt 0 && "$1" != "loop" ]]; then
+  run_gtd "$@"
+  exit $?
+fi
+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.
+
 # 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.
@@ -32,20 +67,38 @@ set -euo pipefail
 # `--resume`/`--session-id`. An adapter that ignores them keeps working.
 herdr_ok() { [ "${HERDR_ENV:-}" = 1 ] && [ -n "${HERDR_PANE_ID:-}" ] && command -v herdr >/dev/null 2>&1; }
 
+# Run a `herdr` invocation best-effort. Normally output is discarded and a
+# failure is swallowed (`|| true`) so a missing/incompatible herdr never blocks
+# the loop. Set GTD_HERDR_DEBUG=1 to instead surface every call and its exit
+# code on stderr — the escape hatch that makes a silent CLI-signature mismatch
+# (e.g. an arg herdr rejects) visible again.
+herdr_run() {
+  if [ "${GTD_HERDR_DEBUG:-}" = 1 ]; then
+    printf 'gtd/herdr: %s\n' "$*" >&2
+    herdr "$@" >&2
+    printf 'gtd/herdr: exit=%s\n' "$?" >&2
+  else
+    herdr "$@" >/dev/null 2>&1 || true
+  fi
+}
+
+# NOTE: herdr requires the positional <PANE_ID> BEFORE the options for
+# `pane` subcommands — passing it last makes herdr reject the first option as
+# `unknown option` (exit 2). Keep the pane id first here.
 herdr_report() {  # $1=state (working|blocked|idle)  $2=message
   herdr_ok || return 0
-  herdr pane report-agent --source herdr:gtd --agent gtd \
-    --state "$1" --message "$2" "$HERDR_PANE_ID" >/dev/null 2>&1 || true
+  herdr_run pane report-agent "$HERDR_PANE_ID" \
+    --source herdr:gtd --agent gtd --state "$1" --message "$2"
 }
 
 herdr_notify() {  # $1=title  $2=body
   herdr_ok || return 0
-  herdr notification show "$1" --body "$2" --sound request >/dev/null 2>&1 || true
+  herdr_run notification show "$1" --body "$2" --sound request
 }
 
 herdr_release() {  # hand the pane back to Herdr's normal detection
   herdr_ok || return 0
-  herdr pane release-agent --source herdr:gtd --agent gtd "$HERDR_PANE_ID" >/dev/null 2>&1 || true
+  herdr_run pane release-agent "$HERDR_PANE_ID" --source herdr:gtd --agent gtd
 }
 
 trap 'code=$?; if [ "$code" -ne 0 ]; then
@@ -101,14 +154,14 @@ 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.
-if ! peek_json="$(gtd next --json 2>&1)"; then
+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
   exit 1
 fi
 if [[ "$(jq -r .kind <<<"$peek_json")" == "message" ]]; then
-  if ! step_out="$(gtd step human 2>&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
@@ -117,7 +170,7 @@ if [[ "$(jq -r .kind <<<"$peek_json")" == "message" ]]; then
 fi
 
 while true; do
-  if ! next_json="$(gtd next --json 2>&1)"; then
+  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
@@ -141,7 +194,7 @@ while true; do
     herdr_report blocked "$label"
     herdr_notify "gtd needs you — $(basename "$PWD")" "$label"
     echo "--- Your turn ($state) ---"
-    gtd next
+    run_gtd next
     exit 0
   fi
 
@@ -152,7 +205,7 @@ while true; do
     # the tree, and `gtd step` captures whatever it left there via the state's
     # own `on` patterns.
     bash -c "$content" || true
-    gtd step "$actor" >/dev/null
+    run_gtd step "$actor" >/dev/null
     head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
     if [[ "$head_before" == "$head_after" ]]; then
       herdr_report idle "$label"
@@ -170,7 +223,7 @@ while true; do
   # 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
-    gtd next >&2
+    run_gtd next >&2
     exit 1
   fi
   prev_state="$state"
@@ -213,7 +266,7 @@ while true; do
   run_agent_turn "$content" "$resume"
 
   fix_attempt=0
-  while ! validate_out="$(gtd validate 2>&1)"; do
+  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
@@ -228,5 +281,5 @@ while true; do
     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
 
-  gtd step "$actor" >/dev/null
+  run_gtd step "$actor" >/dev/null
 done

package/dist/gtd.bundle.mjs

@@ -205351,6 +205351,11 @@ const GTD_VERSION = createRequire(import.meta.url)("../package.json").version;
 const HELP_TEXT = `Usage: gtd [command] [options]
 
 Commands:
+  (no command), loop
+                   Launch the loop driver (bin/gtd), which repeatedly drives
+                   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
   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

@@ -4,12 +4,19 @@
 Usage: gtd [command] [options]
 
 Commands:
-  init             Scaffold a minimal .gtdrc.json for this repo, seeding a
-                   testCommand var (npm test) and a ready-to-edit Prettier
-                   formatting suggestion under modes:. Writes no workflow — gtd
-                   runs the bundled unified workflow as its built-in default.
-                   Takes no argument. Refuses if a gtd config already exists.
-                   Leaves the file uncommitted for you to review and commit
+  (no command), loop
+                   Launch the loop driver (bin/gtd), which repeatedly drives
+                   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
+  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
+                   built-in workflow by default, so no workflow is written —
+                   add a workflow: key only to customize the machine itself.
+                   Takes no argument. Run once per repo; refuses if a gtd
+                   config already exists. Leaves the file uncommitted for you
+                   to review and commit
   step <actor>     Authenticate as <actor>, match the resolved rest's
                    declared patterns against the pending changes, and commit
                    (or squash) the one resulting transition. Pass
@@ -44,7 +51,9 @@ Commands:
                    declares, with its mode's commands (its file:/mode:);
                    exits non-zero with the findings when it is invalid
   lsp              Start the LSP server for .gtd/ steering files (stdio)
-  visualize        Serve an interactive diagram of the active workflow locally
+  visualize        Serve an interactive diagram of the active workflow on a
+                   local web server (--port <n>, --no-open; --json prints the
+                   model and exits)
   version          Print version and exit
   help             Print this help and exit
 
@@ -61,9 +70,11 @@ Options:
 `--version` (`-v`) / `gtd version` and `--help` (`-h`) / `gtd help`
 short-circuit before any git or repository-state work — they run outside a repo
 and in any repo state (the bare subcommands are exact equivalents of their flag
-forms). Bare `gtd` (no subcommand) is a usage error: it prints the help text and
-exits 1 without touching the repository. Every other command must be run from
-the **repository root** — gtd derives the workflow, pending changes, and process
+forms). Bare `gtd` (no subcommand) and `gtd loop` both launch the loop driver
+(`bin/gtd`) immediately — neither is a usage error. Any other, truly unknown
+subcommand remains a usage error: it prints the help text and exits 1 without
+touching the repository. Every other (recognized) command must be run from the
+**repository root** — gtd derives the workflow, pending changes, and process
 history relative to cwd, so it refuses with a clear error if invoked from a
 subdirectory.
 
@@ -401,7 +412,7 @@ which are JSON-only. `--json` emits
 
 There is no `gtd` subcommand that executes a workflow script — gtd never runs a
 workflow script itself. When `gtd next` resolves to a `script`-content rest, the
-**driver** (`bin/gtd-loop`, or any loop harness) executes the emitted `content`
+**driver** (`bin/gtd`, or any loop harness) executes the emitted `content`
 verbatim via `bash -c` — foreground, inherited stdio, exit code deliberately
 ignored (a check script encodes its outcome in the tree, e.g. writing a findings
 file, never in its exit status) — then runs `gtd step <actor>` for that state's
@@ -493,7 +504,7 @@ agent or human:
 - **The producing agent self-validates.** Plain `gtd next` appends a "run
   `gtd validate` and fix all violations" instruction to a `prompt` rest that
   declares `file:`+`mode:`; `gtd next --json` withholds it and the driving loop
-  runs `gtd validate` after the turn instead (see `bin/gtd-loop` /
+  runs `gtd validate` after the turn instead (see `bin/gtd` /
   [STATES.md §12](../STATES.md#12-steering-file-validation-gtd-validate)).
 - **`gtd step` enforces the same gate.** Capturing a turn out of a state that
   declares `file:`+`mode:` formats that file in place and validates it first

package/docs/loop.md

@@ -57,9 +57,10 @@ gtd next --json   # ask who's up and what they should do
 ```
 
 See [`skills/loop/SKILL.md`](../skills/loop/SKILL.md) for the agent-facing
-instructions that follow the same pinned contract. `gtd-loop`, installed
-alongside `gtd` (see below), is the packaged, ready-to-run implementation of
-that same script for anyone who doesn't want to drive the loop by hand.
+instructions that follow the same pinned contract. `gtd` itself (bare, or with
+`loop` as its first argument — see below) is the packaged, ready-to-run
+implementation of that same script for anyone who doesn't want to drive the loop
+by hand.
 
 ## The reference loop driver
 
@@ -68,17 +69,29 @@ A minimal bash implementation of the pinned protocol, driving an agent CLI (e.g.
 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. 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
-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.
+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.
+
+`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
+full command, not just a path — to point both at source instead, e.g. for
+development or testing:
+
+```bash
+GTD_BIN="node $PWD/dev/run.mjs" bin/gtd
+```
 
 ```bash
 #!/usr/bin/env bash
@@ -144,9 +157,9 @@ turn, or either side has no `memory` — start fresh.
 This is what makes a loop retain memory while a phase boundary clears it: a loop
 that keeps re-entering one state emits the same label every lap, so the agent
 accumulates context across the loop; the move to the next phase's
-differently-labelled state resets it. `bin/gtd-loop` implements this by mapping
-the signal onto claude's session flags — `--session-id` to pin a fresh session
-when the scope changes, `--resume` to continue it while the scope holds — and
+differently-labelled state resets it. `bin/gtd` implements this by mapping the
+signal onto claude's session flags — `--session-id` to pin a fresh session when
+the scope changes, `--resume` to continue it while the scope holds — and
 persists the current scope + session id in the git dir (never the working tree,
 so `gtd status` and the pending diff never see them) so retention survives even
 across the restarts a human gate forces mid-loop. See `skills/loop/SKILL.md`'s
@@ -154,7 +167,7 @@ across the restarts a human gate forces mid-loop. See `skills/loop/SKILL.md`'s
 
 ## Using a different agent
 
-`gtd-loop` defaults to
+`gtd` (bare, or `gtd loop`) defaults to
 `claude -p "$GTD_LOOP_PROMPT" --dangerously-skip-permissions`, but the agent
 invocation is swappable: set `GTD_LOOP_AGENT_CMD` to any shell command, and it
 runs with the prompt available as `$GTD_LOOP_PROMPT` in its environment, along
@@ -165,23 +178,26 @@ session). An adapter that ignores any of these keeps working unchanged. For
 example, to drive a different agent CLI:
 
 ```bash
-GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
+GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd
 ```
 
 ## Herdr integration (optional)
 
-`bin/gtd-loop` optionally reports its lifecycle to [Herdr](https://herdr.dev) (a
+`bin/gtd` optionally reports its lifecycle to [Herdr](https://herdr.dev) (a
 terminal multiplexer for coding agents) via a `herdr` CLI binary, entirely at
 the driver's edge — gtd core never talks to Herdr. Every call is best-effort
 (guarded, output discarded, `|| true`), so a missing/failing `herdr` binary
-never blocks, slows, or fails the loop.
+never blocks, slows, or fails the loop. Because that guard also hides a herdr
+CLI-signature mismatch, set `GTD_HERDR_DEBUG=1` to surface every `herdr` call
+and its exit code on stderr instead.
 
 The reporting is a no-op unless all three guard conditions hold: `HERDR_ENV=1`,
-a non-empty `$HERDR_PANE_ID`, and `herdr` on `$PATH`. When they do, `gtd-loop`
-makes three kinds of calls:
+a non-empty `$HERDR_PANE_ID`, and `herdr` on `$PATH`. When they do, `gtd` makes
+three kinds of calls (note the positional `<PANE_ID>` comes BEFORE the options —
+herdr's `pane` subcommands reject a trailing pane id):
 
-- `herdr pane report-agent --source herdr:gtd --agent gtd --state <state> --message <label> "$HERDR_PANE_ID"`
-- `herdr pane release-agent --source herdr:gtd --agent gtd "$HERDR_PANE_ID"`
+- `herdr pane report-agent "$HERDR_PANE_ID" --source herdr:gtd --agent gtd --state <state> --message <label>`
+- `herdr pane release-agent "$HERDR_PANE_ID" --source herdr:gtd --agent gtd`
 - `herdr notification show <title> --body <label> --sound request`
 
 mapped onto the loop's states like this:

package/docs/upgrading.md

@@ -159,6 +159,47 @@ loudly at load time rather than silently misinterpreting.
 or agent harness, upgrading the `gtd` binary also means re-copying that skill
 from this release.
 
+## 7.4: `gtd-loop` is gone — bare `gtd` and `gtd loop` run it directly
+
+`gtd-loop`, the standalone loop-driver binary installed alongside `gtd`, no
+longer exists. Its body now lives in `bin/gtd` itself, which is a bash entry
+script that dispatches on its first argument:
+
+| behavior                                               | before (≤ 7.3)                                 | from 7.4                                        |
+| ------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------- |
+| `gtd-loop`                                             | separate installed binary                      | removed                                         |
+| bare `gtd` (no subcommand)                             | usage error, prints help, exits 1              | runs the loop driver immediately                |
+| `gtd loop`                                             | not a recognized subcommand                    | runs the loop driver immediately                |
+| any other subcommand (`step`, `status`, `validate`, …) | handled by `node dist/gtd.bundle.mjs` directly | same, now reached via `bin/gtd`'s hand-off/exec |
+
+**Bare `gtd` is a behavior flip, not merely an addition** — the same kind of
+change as the v1 → v2 label grammar below: previously it printed the help text
+and exited 1 without touching the repository; from 7.4 it launches the loop
+driver immediately, identically to `gtd loop`. A script that relied on bare
+`gtd` failing fast (e.g. to detect a missing subcommand) now gets a running loop
+instead of an error.
+
+Because `bin/gtd` is a bash script for every invocation now, **running `gtd` at
+all — including any subcommand — requires bash**. Before 7.4, only the loop
+driver (`gtd-loop`) needed bash; a subcommand could be invoked directly via the
+bundle (e.g. `node node_modules/.bin/gtd`) with no bash in between. This is
+intentional and accepted, not an oversight: gtd's loop, its `script`-content
+checks, and a steering-file mode's own `format:`/`validate:` commands already
+run via `bash -c` (see
+[Configuration](configuration.md#modes--pluggable-steering-file-modes)) — gtd
+already assumes a unix/bash agent environment everywhere else, so the entry
+point catching up removes an inconsistency rather than introducing a new
+dependency.
+
+**Migration:**
+
+- Anyone invoking `gtd-loop` directly — in scripts, CI, or docs — should invoke
+  `gtd` or `gtd loop` instead.
+- Anyone relying on `node node_modules/.bin/gtd` resolving straight to the
+  bundle should note `gtd` is now a bash script that execs the bundle for
+  subcommands, so behavior for actual subcommands (`gtd step`, `gtd status`,
+  etc.) is unchanged — only the underlying file changed.
+
 ## 7.2: the review checkout window is now per worktree
 
 The review checkout window's two refs moved from the SHARED `refs/gtd/*`

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@pmelab/gtd",
-  "version": "7.3.0",
+  "version": "7.4.1",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
-    "gtd": "dist/gtd.bundle.mjs",
-    "gtd-loop": "bin/gtd-loop"
+    "gtd": "bin/gtd"
   },
   "files": [
     "dist/",