@pmelab/gtd 2.6.0 → 2.8.0

package/docs/cli.md

@@ -0,0 +1,356 @@
+# CLI reference
+
+```
+Usage: gtd [command] [options]
+
+Commands:
+  step             Advance the workflow as the human actor (to fixpoint)
+  step-agent       Advance the workflow as the agent actor (to fixpoint)
+  next             Print the prompt for whichever actor is awaited (no mutation)
+  status           Predict the next commit and state from the working tree (no mutation)
+  review <target>  Anchor an ad-hoc human review against a git ref or branch
+  questions        List open questions from the active grilling/architecting doc
+  changesets       List changesets/files from the active review doc
+  format <file>    Format a markdown file in place
+
+Options:
+  --json           Output structured JSON instead of plain text
+  --version, -v    Print version and exit
+  --help, -h       Print this help and exit
+```
+
+`--version` (`-v`) and `--help` (`-h`) short-circuit before any git or
+repository-state work — they run outside a repo and in any repo state. 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 steering files, diffs, and pathspecs relative
+to cwd, so it refuses with a clear error if invoked from a subdirectory.
+
+`--json` is the only long option. 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.
+
+One nuance to "(no mutation)": `next` and `status` never author commits or
+change workflow state, but while a human review is pending they do maintain the
+review checkout window (closing it to read state, re-arming it on the way out —
+see [Human review gate](workflow.md#human-review-gate)), which transiently moves
+HEAD and the index. The working tree is never touched.
+
+## `gtd step` / `gtd step-agent`
+
+Both drive the **same fixpoint loop** — gather → resolve → perform the returned
+edge action → repeat — differing only in which actor's turn they are allowed to
+capture:
+
+- **`gtd step`** captures the **human** turn at whichever gate is awaiting one.
+- **`gtd step-agent`** captures the **agent** turn.
+
+**Fixpoint advance.** A single invocation may author several commits: it authors
+the awaited actor's turn commit, then keeps performing any further mid-chain
+routing (a test run, a routing commit, a package close, …) until it reaches a
+rest where a prompt would be shown, or a fixpoint where nothing changed.
+`gtd step`/`gtd step-agent` never print a prompt themselves — that's
+`gtd next`'s job.
+
+**Idempotence.** Re-running the same command again once the tree is settled at a
+rest authors **zero** new commits. It exits 0 while the rest still awaits that
+command's actor (an inert empty agent turn, the idle health check); once the
+rest awaits the _other_ actor, the re-run is an out-of-turn refusal — still zero
+commits, but non-zero exit.
+
+**Out-of-turn refusal.** Human and agent turns are strictly separated: the wrong
+mutator always errors, at every state, on clean and dirty trees alike.
+`gtd step-agent` while a human turn is awaited refuses with
+`"<state> awaits a human turn — run \`gtd step\`"`; `gtd
+step`while an agent turn is awaited refuses with`"<state> awaits an agent turn —
+run \`gtd
+step-agent\`"`— exit non-zero, zero commits either way. Human edits made while the agent is awaited (e.g. amendment notes in`.gtd/`package files after the`gtd:
+planning` commit lands) stay pending in the working tree and ride along as input
+to the agent's next captured turn; left unamended, the build proceeds.
+
+**Red-test fixpoints exit 0.** A red test run below the fix-attempt cap (or the
+health-fix cap) still writes its findings and commits — it is a normal,
+successful step of the loop, not a failure of the `step`/`step-agent`
+invocation. `step`/`step-agent` only exit non-zero for a genuine refusal or an
+operational error (bad config, missing test binary, corrupted state).
+
+**Output.** Plain mode prints one `committed: <subject>` line per commit this
+invocation authored (oldest→newest), then a final `state: <state>` line:
+
+```
+committed: gtd(human): grilling
+committed: gtd: architecting
+state: architecting
+```
+
+`--json` emits `{state, actions, commits}` instead (see
+[JSON schemas](#json-schemas)).
+
+## `gtd next`
+
+Pure prompt emitter — it **never mutates** the repository. It reports whichever
+actor is currently awaited and, if the tree is at a genuine rest, the full
+prompt for that actor.
+
+**Purity.** No commits, no file writes, no test runs — `gtd next` only gathers
+and resolves.
+
+**Dirty-tree refusal.** If the working tree has pending changes outside the
+steering-file set, `gtd next` refuses rather than guess at a prompt for a state
+that hasn't been captured yet:
+
+```
+gtd next: working tree is dirty — run `gtd status` to inspect it, then advance with `gtd step` or `gtd step-agent` (whichever actor is awaited)
+```
+
+**Pending.** If HEAD is mid-chain — bookkeeping the next `step`/`step-agent`
+invocation would perform before reaching a rest — `gtd next` reports
+`pending: true` with no prompt. Mid-chain bookkeeping is invoker-agnostic, so
+either mutator resumes it; the report names the actor whose chain it is. In
+plain mode an agent-driven checkpoint prints `"mid-chain checkpoint — run \`gtd
+step-agent\` to continue, then run \`gtd next\`
+again"`, a human-driven one prints `"mid-chain checkpoint — run \`gtd step\` to
+continue"`.
+
+**Agent tail lines.** In plain-mode output, a prompt for the **agent** actor
+ends with the pinned tail:
+
+```
+Finish your turn by running `gtd step-agent`. Then run `gtd next` and follow
+its output — repeat this cycle as long as the output is addressed to you (the
+agent); when it awaits the human, stop and hand off.
+```
+
+The first sentence closes the current turn; the second closes the outer loop —
+it is what lets a plain-text agent chain multiple iterations (e.g. successive
+test/fix cycles) without an external driver, until a human gate is reached.
+Human-actor prompts carry no tail. `--json` output never embeds the tail into
+`prompt` either — the structured `actor` field (see
+[JSON schemas](#json-schemas) below) carries the same information: `"agent"`
+means another agent round, `"human"` means stop and hand off.
+
+## `gtd status`
+
+Pure, read-only **dry-run prediction** — the same gather+resolve `gtd next`
+runs, but reporting a prediction of the next turn rather than the actual prompt.
+Performs no git mutation, no test run, no file write — guaranteed side-effect
+free, including on a dirty tree.
+
+Prints four fields:
+
+```
+State: grilling
+Awaits: human
+Predicted commit: gtd(human): grilling
+Predicted state: grilling
+```
+
+- **State** — the currently resolved state.
+- **Awaits** — the actor (`human` or `agent`) whose turn it is.
+- **Predicted commit** — the subject `step`/`step-agent` would author next, or
+  `(none)` at a fixpoint (e.g. idle with nothing to do).
+- **Predicted state** — the state that commit would land in.
+
+`gtd status` takes no arguments — extra positional args are rejected.
+
+## `gtd review <target>`
+
+A pure mutator that **anchors, then exits** — it never prints a prompt itself.
+Use it to start an ad-hoc human review against an explicit git ref or branch,
+independent of the automatic review base the workflow otherwise computes.
+
+1. Refuses on a dirty tree.
+2. Resolves `<target>` via merge-base semantics and computes the diff HEAD adds
+   over `merge-base(<target>, HEAD)`.
+3. Refuses if that diff is empty after filtering ("nothing to review").
+4. Authors exactly one commit: `gtd: reviewing <full-hash-of-the-base>`.
+5. Prints a short confirmation pointing at `gtd next` — it does **not** print
+   the review prompt itself.
+
+```bash
+gtd review main
+# anchored review at <hash> — run `gtd next` to get the review prompt
+gtd next --json
+# {"actor":"agent", ...} — the review-record prompt scoped to that anchor
+```
+
+Errors (all exit 1, message on stderr):
+
+- Missing target: `gtd review: missing target argument`
+- Extra arguments:
+  `gtd review: too many arguments — expected one target, got: …`
+- Unresolvable ref: `gtd review: cannot resolve ref '<target>': <error message>`
+- Empty diff:
+  `gtd review: nothing to review (<target> diff is empty after filtering)`
+
+## `gtd questions` / `gtd changesets`
+
+Pure, read-only reporters — no dirty-tree check, no mutation — that parse the
+structured content out of the active grilling/architecting and review documents,
+for a future UI:
+
+- **`gtd questions`** reads whichever of `.gtd/TODO.md` / `.gtd/ARCHITECTURE.md`
+  is present and reports its `## Open Questions` list (see
+  [Structured grilling/architecting and review files](workflow.md#structured-grillingarchitecting-and-review-files)).
+  Reports an empty list when neither file exists.
+- **`gtd changesets`** reads `.gtd/REVIEW.md`, if present, and reports its
+  chunks/file-pointer list. Reports an empty list when the file doesn't exist.
+
+Both take no arguments and always exit 0 — a malformed file is reported via the
+`errors` field/lines rather than failing the command (the same diagnosis
+`gtd step-agent` would refuse the agent's next turn capture with).
+
+```bash
+gtd questions --json
+# {"file":".gtd/TODO.md","questions":[{"question":"Which operations?","status":"suggested","text":"add and subtract."}],"errors":[]}
+gtd changesets --json
+# {"file":".gtd/REVIEW.md","shortHash":"abc1234","fullHash":"abc1234...","changesets":[...],"errors":[]}
+```
+
+## `gtd format <file>`
+
+Formats a markdown file in place with a bundled prettier (`parser: "markdown"`,
+`printWidth: 80`, `proseWrap: "always"`), ignoring the host repo's own
+`.prettierrc` so `.gtd/TODO.md`/`.gtd/REVIEW.md` stay consistently formatted
+regardless of the host project's toolchain. Rejects `--json` (exit 1,
+`gtd format does not accept --json`) — it is a plain file operation, not a v2
+state command.
+
+Errors (all exit 1, message on stderr):
+
+- Missing path: `gtd format: missing file path argument`
+- Extra arguments: `gtd format: too many arguments — expected one path, got: …`
+- Non-markdown file:
+  `gtd format: <file> is not a markdown file (expected .md or .markdown)`
+- File not found: `gtd: skipped formatting <file>: not found`
+
+## JSON schemas
+
+Pass `--json` to `step`, `step-agent`, `next`, `status`, `review`, `questions`,
+or `changesets` for machine-readable single-line JSON output instead of plain
+text.
+
+**`step` / `step-agent`** — `{state, actions, commits}`:
+
+```json
+{
+  "state": "architecting",
+  "actions": ["capture the human turn as \"gtd(human): grilling\""],
+  "commits": ["gtd(human): grilling", "gtd: architecting"]
+}
+```
+
+- `state` — the final resolved state after the fixpoint loop settled.
+- `actions` — human-readable descriptions of every edge action this invocation
+  performed, oldest→newest.
+- `commits` — every commit subject this invocation authored, oldest→newest.
+
+**`next`** — `{state, actor, pending, prompt}`:
+
+```json
+{
+  "state": "building",
+  "actor": "agent",
+  "pending": false,
+  "prompt": "..."
+}
+```
+
+- `state` — the resolved state.
+- `actor` — `"human"` or `"agent"`: who owns the next move. This is the single
+  loop-driver signal: `"agent"` means proceed with another round — act on
+  `prompt` when present, then run `gtd step-agent`; at an agent-driven pending
+  checkpoint (`prompt` is `null`, nothing to act on) just run `gtd step-agent`.
+  `"human"` means halt and hand off (a human rest, whose prompt body already
+  tells the human what to do, or a human-driven pending checkpoint resumed by
+  `gtd step`).
+- `pending` — `true` at a mid-chain HEAD (no prompt yet — resume with a mutator
+  first); `false` at a genuine rest.
+- `prompt` — the full prompt markdown when `pending` is `false`, else `null`.
+
+**`status`** — `{state, actor, predictedCommit, predictedState}`:
+
+```json
+{
+  "state": "grilling",
+  "actor": "human",
+  "predictedCommit": "gtd(human): grilling",
+  "predictedState": "grilling"
+}
+```
+
+`predictedCommit` is `null` when the next invocation would author nothing (e.g.
+idle with a green health check).
+
+**`questions`** — `{file, questions, errors}`:
+
+```json
+{
+  "file": ".gtd/TODO.md",
+  "questions": [
+    {
+      "question": "Which operations?",
+      "status": "suggested",
+      "text": "add and subtract."
+    }
+  ],
+  "errors": []
+}
+```
+
+`file` is `null` when neither `.gtd/TODO.md` nor `.gtd/ARCHITECTURE.md` is
+present. `errors` lists any structural problems in the file — the same diagnosis
+that would make `gtd step-agent` refuse the agent's next turn capture.
+
+**`changesets`** — `{file, shortHash, fullHash, changesets, errors}`:
+
+```json
+{
+  "file": ".gtd/REVIEW.md",
+  "shortHash": "abc1234",
+  "fullHash": "abc1234def5678901234567890123456789abcd",
+  "changesets": [
+    {
+      "title": "Add calculator",
+      "description": "New add function for the calculator.",
+      "files": [{ "path": "./src/calc.ts", "line": 1, "checked": false }]
+    }
+  ],
+  "errors": []
+}
+```
+
+`file` is `null` when `.gtd/REVIEW.md` doesn't exist. `errors` mirrors
+`questions`' field above.
+
+**Error envelope** — every command, in `--json` mode, reports failures inside
+the JSON object rather than as unstructured text, and still exits 1:
+
+```json
+{ "state": "error", "prompt": "<message>" }
+```
+
+There is no auto-advance flag anywhere in the wire format — `actor` replaces it.
+The caller decides whether to keep looping based on `actor` (halt on `"human"`)
+and `pending` (re-run `step`/`step-agent` first when `true`), not on a boolean
+auto-advance flag.
+
+## Repository requirements
+
+- **Single writer, linear branch.** State is folded from **first-parent**
+  history only. A merge commit at HEAD is unsupported (documented, not handled)
+  — it degrades gracefully on the default branch rather than crashing, but do
+  not rely on merge commits mid-cycle.
+- **Test/build artifacts must be gitignored.** This is **load-bearing**, not a
+  style preference: every fixpoint hop in `gtd step`/`gtd step-agent` detects
+  "clean" via `git status --porcelain`, which silently omits anything matched by
+  `.gitignore`. If your `testCommand` (or the build it triggers) writes
+  tracked-but-untracked output — a `dist/`, a coverage report, a log file — into
+  the working tree, the tree never goes clean after a green test run, and the
+  fixpoint loop cannot converge: it will either loop forever re-detecting a
+  "dirty" boundary or misclassify build output as the human's next feature
+  capture. Gitignore every path your test/build toolchain writes before wiring
+  gtd into a repo.
+- **Repository root invocation.** Every subcommand except `--help`/`--version`
+  must run from the git repository root — steering files and diffs are resolved
+  against the process cwd.

package/docs/configuration.md

@@ -0,0 +1,113 @@
+# Configuration
+
+gtd reads an optional `.gtdrc` config file via
+[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). With no config, the
+built-in defaults apply. Supported filenames (searched in this order):
+
+- `.gtdrc`
+- `.gtdrc.json`
+- `.gtdrc.yaml`
+- `.gtdrc.yml`
+- `gtd.config.json`
+- `gtd.config.yaml`
+
+## Schema
+
+- **`testCommand`** (string, default `npm run test`) — the command the edge runs
+  after a build turn, and on the idle health-check path.
+- **`fixAttemptCap`** (non-negative integer, default `3`) — the test-fix budget:
+  how many `gtd: errors` attempts are allowed per sub-loop before the failure is
+  escalated to `.gtd/ERRORS.md` (Escalate). `0` disables the cap (escalates
+  immediately on the first red run). Also reused as the health-fix budget — no
+  separate config key.
+- **`reviewThreshold`** (integer ≥ 1, default `3`) — the review-fix budget: how
+  many agentic-review findings rounds are allowed per package before Agentic
+  Review force-approves.
+- **`agenticReview`** (boolean, default `true`) — kill-switch for the
+  per-package Agentic Review gate. Set `false` to force-approve every package
+  and proceed directly to human review.
+- **`squash`** (boolean, default `true`) — after `gtd: done` (or, once learning
+  has run, `gtd: learning applied`), collapse the cycle's `gtd: *` commits into
+  a single conventional-commits commit. Set `false` to keep the granular
+  history.
+- **`learning`** (boolean, default `true`) — after `gtd: done` (or the
+  health-fix path's green re-test), distill durable lessons from the cycle into
+  `.gtd/LEARNINGS.md`, have a human review them, then integrate them into the
+  project's own docs before the squash decision runs. Set `false` to skip the
+  phase entirely — independent of `squash`.
+- **`decisionLog`** (boolean, default `true`) — squashing records this cycle's
+  resolved open questions as a `## Decisions` section in the squash commit
+  message; grilling/architecting inline every past squash commit's section,
+  oldest to newest, as prior-decision context. Set `false` to skip both.
+- **`models`** — model selection for the subagent-spawning states:
+  - `planning` — high-reasoning tier (default `claude-opus-4-8`), used by
+    `decompose` (the `grilled`/`planning` states), `grilling`, `architecting`,
+    `agentic-review`, and `clean` (the `review`/`squashing`/`learning`/
+    `learning-apply` states).
+  - `execution` — everyday tier (default `claude-sonnet-4-8`), used by
+    `building` and `fixing`.
+  - `states.*` — per-state overrides keyed by `decompose`, `grilling`,
+    `architecting`, `building`, `fixing`, `agentic-review`, `clean`. Unknown
+    `states` keys are **rejected**.
+- **`$schema`** (string, optional) — stripped before validation, so it never
+  counts as an unknown key. Point it at the published schema for editor-backed
+  autocompletion. A `schema.json` is generated from the config schema at build
+  time and ships with the package.
+
+## Validation and errors
+
+If a config file fails to load or is invalid, gtd **exits with code 1** and
+writes a human-readable error to **stderr** (never stdout):
+
+- **Parse errors** (malformed YAML/JSON) — message includes the offending
+  filename.
+- **Non-object top-level** — a YAML list or `null` at the root is rejected with
+  the filename in the message.
+- **Schema violations** — unknown keys or out-of-range values emit
+  `Invalid gtd config: <field>: <reason>`.
+- **Missing test binary** — if `testCommand` names an executable that cannot be
+  found (`ENOENT`), gtd exits 1 with `gtd: test command not found: <command>` on
+  stderr. A non-zero test _exit code_ is not an error — it drives the normal red
+  path.
+
+## Lookup and precedence
+
+gtd walks from the current working directory **up to your home directory** (or
+to the filesystem root when cwd is outside home), collecting every `.gtdrc` it
+finds along the way. All found levels are **deep-merged**, with the **innermost
+(cwd) config winning** on conflicts — so a shared `.gtdrc` in a worktree-parent
+directory cascades to every checkout beneath it, while any individual checkout
+can still override settings with its own `.gtdrc`.
+
+## Auto-init
+
+On every **state command** (`step`, `step-agent`, `next`, `status`, `review`)
+that has passed the repo-root guard, if the cwd→root walk finds **no** config
+anywhere, gtd creates and commits a starter `.gtdrc.json` at the repository root
+containing only a `$schema` link. Auto-init never runs for `--version`/`--help`,
+`format`, bare/unknown commands, or an invocation refused by the repo-root guard
+— those perform no repository mutation of any kind. On a repo with no commits
+yet, or whose HEAD is a plain (non-`gtd:`) commit, the stub is committed as its
+own `chore: add .gtdrc.json`. If HEAD is already a `gtd:`-owned commit
+(mid-workflow), the stub is instead **amended into HEAD** — stacking a fresh
+boundary commit there would produce an unrecognized HEAD most workflow states
+can't resolve past.
+
+## Example
+
+```yaml
+# .gtdrc.yaml
+testCommand: pnpm test
+fixAttemptCap: 3
+reviewThreshold: 3
+agenticReview: true
+squash: true
+learning: true
+decisionLog: true
+models:
+  planning: claude-opus-4-8
+  execution: claude-sonnet-4-8
+  states:
+    decompose: claude-opus-4-8
+    building: claude-sonnet-4-8
+```

package/docs/development.md

@@ -0,0 +1,82 @@
+# Development
+
+```bash
+npm install
+npm run dev          # run from source, no build (node dev/run.mjs)
+npm run build        # tsdown → dist/gtd.bundle.mjs
+npm test             # format:check, typecheck, lint, unit + e2e tests, fallow
+npm run test:unit    # vitest unit tests (the pure resolver) — --project unit
+npm run test:e2e     # gherkin e2e via vitest + quickpickle — --project e2e
+npm run test:mutation # StrykerJS mutation testing (manual only, ~2 min)
+npm run typecheck
+npm run lint
+```
+
+## Pre-commit hook
+
+A pre-commit hook is installed automatically via the `prepare` script when you
+run `npm install` on a fresh clone — no manual setup needed. The hook runs
+[lint-staged](https://github.com/lint-staged/lint-staged) with
+[oxfmt](https://oxc.rs/docs/guide/usage/formatter.html), formatting every staged
+file before each commit (`oxfmt --no-error-on-unmatched-pattern --write`),
+mirroring the `format:check` step enforced in CI (`oxfmt --check .`).
+
+## Prompt templates
+
+Each prompt-bearing state has a self-contained Eta template in
+`src/prompts/*.md` that owns its full prompt — header, context, and body. Shared
+fragments live as partials in `src/prompts/partials/`: `header`, the context
+renderers (`diff`, `feedback`, `package`), and the single `agent-turn` tail
+partial (the pinned "Finish your turn by running `gtd step-agent`. Then run
+`gtd next` …" loop-closing instructions).
+
+At module load, `src/Prompt.ts` registers every template on a single `new Eta()`
+instance via `loadTemplate`. `readFile` and `resolvePath` are nulled afterward
+so rendering resolves exclusively from the in-memory cache — the compiled ESM
+bundle carries no runtime `fs` dependency.
+
+`buildPrompt(result, resolveModel?, output?)` selects the state's template,
+builds a view-model (model string, tail partial name, context), renders it,
+collapses runs of three or more blank lines to two, and ensures exactly one
+trailing newline. It throws for the five states that render no prompt at all
+(`testing`, `planning`, `close-package`, `done`, `health-check`) — those are
+performed entirely by the edge.
+
+`npm run dev` runs `src/main.ts` directly via Node's native TypeScript
+type-stripping (requires Node 22.6+). It registers `dev/hooks.mjs`, which fills
+the two gaps the tsdown build otherwise covers: resolving `./Foo.js` specifiers
+to the on-disk `./Foo.ts`, and importing `*.md` prompt files as text. Pass CLI
+args after `--`, e.g. `npm run dev -- format <file>`.
+
+The decision core (`src/Machine.ts`) is pure and IO-free, so the whole state
+ladder and the counter folds are trivially unit-testable in isolation; all
+git/filesystem IO is confined to the edge (`src/Events.ts`).
+
+`npm run build` produces `dist/gtd.bundle.mjs`, which npm exposes as the `gtd`
+binary via the `bin` field in `package.json`.
+
+## Mutation testing
+
+Run mutation testing on-demand with `npm run test:mutation` (StrykerJS, ~2 min)
+— never run it as part of routine development; it is a deliberate,
+manually-triggered check. The single `stryker.config.json` mutates six core
+files:
+
+```
+src/Machine.ts  src/Prompt.ts  src/Config.ts
+src/Format.ts   src/State.ts   src/Events.ts
+```
+
+`src/Git.ts` is excluded: the Cucumber harness stubs git at the Effect boundary,
+so `Git.ts` mutants have zero in-memory coverage.
+
+The HTML report lands in `reports/mutation/mutation.html` (git-ignored).
+
+## Releasing
+
+Releases are automatic. Push releasable Conventional Commits (`fix:`, `feat:`,
+or breaking changes) to `main` and the Release workflow runs the tests, then
+`npx semantic-release`. Semantic-release computes the next version, writes it
+into `package.json`, builds the bundle, commits the bump back as
+`chore(release): X.Y.Z [skip ci]`, tags `vX.Y.Z`, and creates the GitHub release
+with `gtd.bundle.mjs` attached.

package/docs/loop.md

@@ -0,0 +1,104 @@
+# Driving the loop
+
+gtd splits what used to be one mutating command into three:
+
+- **`gtd step`** — advance the workflow as the **human** actor, to fixpoint.
+- **`gtd step-agent`** — advance the workflow as the **agent** actor, to
+  fixpoint.
+- **`gtd next`** — print the prompt for whichever actor is currently awaited,
+  without mutating anything.
+
+An agent loop is a two-beat protocol repeated forever:
+
+1. Run `gtd step-agent` to advance any agent-owned bookkeeping to a fixpoint.
+2. Run `gtd next --json` and read the `actor` field. If it is `"human"`,
+   **halt** — the human owns the next move, and the agent's job is done for this
+   turn. If it is `"agent"`, feed `prompt` (when non-null) to the agent, let it
+   act, then go back to step 1; at a pending checkpoint (`prompt` is null) go
+   straight back to step 1.
+
+A human acts by editing files (answering questions in `.gtd/TODO.md` or
+`.gtd/ARCHITECTURE.md`, annotating `.gtd/REVIEW.md`, fixing code) and then
+running `gtd step` to capture the edit as their turn and hand control back to
+the agent side of the loop.
+
+```bash
+gtd step-agent            # advance the machine's own bookkeeping
+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.
+
+## The reference loop driver
+
+A minimal bash implementation of the pinned two-beat protocol, driving an agent
+CLI (e.g. `claude -p`) against `gtd --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.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+while true; do
+  # 1. Advance the machine's own agent-owned bookkeeping to a fixpoint.
+  gtd step-agent --json >/dev/null || true
+
+  # 2. Ask who's up next. `actor` is the single "proceed" signal.
+  next="$(gtd next --json)"
+  actor="$(jq -r .actor <<<"$next")"
+  prompt="$(jq -r .prompt <<<"$next")"
+
+  if [[ "$actor" != "agent" ]]; then
+    echo "Halting — the human owns the next move."
+    break
+  fi
+
+  if [[ "$prompt" == "null" ]]; then
+    # Agent-driven pending checkpoint: nothing to act on — loop back to
+    # step 1, whose `gtd step-agent` resumes the mid-chain bookkeeping.
+    continue
+  fi
+
+  # Agent's turn: feed the prompt to the agent, then let it finish with
+  # `gtd step-agent` itself (the prompt's tail instructs it to).
+  claude -p "$prompt" --dangerously-skip-permissions
+done
+```
+
+The agent is expected to run `gtd step-agent` itself once it finishes acting on
+the prompt (the plain-mode tail says exactly this) — the driver's own
+`step-agent` calls exist to advance any bookkeeping the agent doesn't own
+(routing commits, test runs) between agent turns.
+
+The loop halts on `actor: "human"` alone: a human rest (`pending: false`, the
+prompt body addresses the human) or a human-driven pending checkpoint
+(`pending: true`, resumed by the human's own `gtd step`). Everything the agent
+side can drive — agent rests and agent-driven checkpoints — reports
+`actor: "agent"`, so multiple agent turns and commits (e.g. successive test/fix
+cycles, a force-approved package close) chain without human involvement until an
+actual human gate is hit.
+
+`bin/gtd-loop`, installed as the `gtd-loop` binary, is the packaged
+implementation of this exact script — kept in sync with it the same way
+`skills/loop/SKILL.md` is. It additionally attempts `gtd step` (not just
+`gtd step-agent`) every iteration, so a plain rerun after you've edited a file
+at a human gate (no commit needed) picks up your edit and keeps going, and it
+halts with a diagnostic if the same state and prompt repeat with no progress
+(see `skills/loop/SKILL.md`'s "Stall detection").
+
+## Using a different agent
+
+`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. For
+example, to drive a different agent CLI:
+
+```bash
+GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
+```