@pmelab/gtd 2.7.0 → 3.0.0

package/docs/cli.md

@@ -0,0 +1,255 @@
+# CLI reference
+
+```
+Usage: gtd [command] [options]
+
+Commands:
+  step <actor>     Authenticate as <actor>, match the resolved rest's
+                   declared patterns against the pending changes, and commit
+                   (or squash) the one resulting transition
+  next             Print the resolved rest's rendered script/prompt/message
+                   (no mutation)
+  run              Execute the resolved rest's emitted script, then step its
+                   actor (the built-in script driver)
+  status           Print the resolved rest's state/actor and which declared
+                   pattern (if any) each pending change matches (no mutation)
+  format <file>    Format a markdown file in place
+  lsp              Start the LSP server for .gtd/ steering files (stdio)
+
+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 the workflow, pending changes, and process
+history 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.
+
+## `gtd step <actor>`
+
+Authenticates `<actor>` against the resolved rest and performs the ONE resulting
+transition. Unlike v2, there is no fixpoint chain to drive: the pattern
+machine's `on` edges are direct one-hop transitions, so a single invocation
+authors at most one commit (a normal turn) or performs one squash
+(§[STATES.md](../STATES.md#8-the-squash-lifecycle)) — never both, never a chain
+of several. A caller that wants several transitions issues several invocations.
+
+- **Out-of-turn refusal** — `<actor>` isn't the resolved state's declared actor:
+  exit non-zero, zero commits.
+  `gtd step <actor>: out of turn — "<state>" awaits <awaited-actor>`
+- **No-match refusal** — the tree is dirty and no declared `on` pattern matches:
+  exit non-zero, zero commits, naming every declared pattern.
+  `gtd step <actor>: no declared pattern matches the pending changes at "<state>" — declared patterns: <p1>, <p2>, …`
+- **No-op** — the tree is clean and the state declares no `C` pattern: exit
+  **0**, zero commits. This is the default, silent case a loop driver relies on
+  (see [Driving the loop](loop.md)).
+- **Commit/squash** — a pattern matched: exit 0, one commit (or one squash)
+  authored.
+
+Plain-mode output is one line:
+
+```
+committed: gtd(human): grilling
+```
+
+or, at a no-op:
+
+```
+nothing to do at "idle"
+```
+
+`--json` emits `{state, subject}` — `subject` is `null` at a no-op:
+
+```json
+{ "state": "grilling", "subject": "gtd(human): grilling" }
+```
+
+## `gtd next [--json]`
+
+Pure emitter of the resolved rest's rendered content — it **never mutates** the
+repository (no commits, no file writes, no script execution). Resolves HEAD
+exactly like `gtd step`, renders that state's declared
+`script`/`prompt`/`message` template, and prints it. `kind` is never `"commit"`
+here: resolution never rests at a commit state (entering one always ends the
+process in the same step that entered it — see
+[STATES.md §5](../STATES.md#5-resolution)).
+
+Plain mode prints the rendered content verbatim (with exactly one trailing
+newline) — never the `model`/`file`/`mode` hints, which are JSON-only. `--json`
+emits `{state, actor, kind, content, model?, file?, mode?}`:
+
+```json
+{
+  "state": "building",
+  "actor": "agent",
+  "kind": "prompt",
+  "content": "You are an autonomous coding agent. ..."
+}
+```
+
+- `state` — the resolved state.
+- `actor` — the state's declared actor.
+- `kind` — `"script"` | `"prompt"` | `"message"` — the dispatch key a driver
+  switches on (see [Driving the loop](loop.md)).
+- `content` — the fully rendered template.
+- `model` — the state's opaque `model:` hint, RENDERED through the same template
+  context as `content` (see
+  [Configuration](configuration.md#model--the-opaque-harness-hint-template-rendered)),
+  present only when the state declares one; **omitted entirely** (never `null`)
+  when unset.
+- `file` — the state's declared steering file, RENDERED the same way; `mode` —
+  its format, verbatim (`"qa"` | `"review"`) (see
+  [Configuration](configuration.md#filemode--the-steering-file-association)).
+  Both present only when the state declares them; **omitted entirely** (never
+  `null`) otherwise.
+
+## `gtd run`
+
+The built-in driver for a `script`-content rest — the **only** place gtd itself
+spawns a subprocess. Renders the resolved rest exactly like `gtd next`, executes
+its 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 own actor to capture the outcome in one command. Refuses (exit
+non-zero, no execution, no step) when the resolved rest isn't a script:
+
+```
+gtd run: "<state>" awaits a <kind> from "<actor>" — nothing scripted to run
+```
+
+Reports the same `{state, subject}` (or `committed: …` / `nothing to do at "…"`)
+as `gtd step` for the capturing step it performs. Takes no arguments — extra
+positional args are rejected.
+
+## `gtd status [--json]`
+
+Pure, read-only dry-run reporter — the same resolution `gtd next` performs, but
+reporting the resolved state/actor and, for every pending change, which declared
+`on` pattern (if any) matches it — no mutation, and no CONTENT rendering (the
+`script`/`prompt`/`message`/`commit` template is never rendered here, unlike
+`gtd next`). It DOES render the resolved state's `model:`/`file:` hints (if
+declared) through the same `it.vars`-carrying template context `gtd next` uses —
+see
+[Configuration](configuration.md#model--the-opaque-harness-hint-template-rendered)
+— so a templated `model:`/`file:` failing to render fails `gtd status` too,
+exactly like it would fail `gtd next`.
+
+```
+State: working
+Awaits: agent
+Pending:
+  A DONE.md -> A DONE.md
+  A scratch.txt -> (no match)
+```
+
+or, on a clean tree: `Pending: (clean)`. A `Model: <value>` line appears right
+after `Awaits:` when the resolved state declares a `model:` hint, and
+`File: <value>`/`Mode: <value>` lines appear after that (in that order) when
+declared — each independently, only when set.
+
+`--json` emits
+`{state, actor, changes: [{status, path, pattern}], model?, file?, mode?}` —
+`pattern` is `null` when no declared row matches that change; `model`/`file`/
+`mode` are present only when the resolved state declares them (omitted entirely,
+never `null`, otherwise):
+
+```json
+{
+  "state": "working",
+  "actor": "agent",
+  "changes": [
+    { "status": "A", "path": "DONE.md", "pattern": "A DONE.md" },
+    { "status": "A", "path": "scratch.txt", "pattern": null }
+  ]
+}
+```
+
+`gtd status` takes no arguments — extra positional args are rejected.
+
+## `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/`-tracked files stay consistently formatted regardless of
+the host project's toolchain. Rejects `--json` (exit 1,
+`gtd format does not accept --json`) — it's a plain file operation, not a 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`
+
+## `gtd lsp`
+
+Starts an LSP server over stdio for `.gtd/` steering files — document symbols
+for a `qa`-mode file's open questions and a `review`-mode file's review
+chunks/hunks, code actions to check/uncheck a hunk or a whole chunk, and
+diagnostics publishing the same parser findings the bundled workflow's
+`.gtd/FORMAT.md` validators produce (see `src/OpenQuestions.ts` /
+`src/ReviewDoc.ts` and
+[STATES.md §10](../STATES.md#10-the-bundled-default-workflow)).
+
+**Config-driven** (see
+[docs/design/state-file-association.md](design/state-file-association.md)): the
+server locates the active gtd config the same way the CLI does, from the
+`initialize` request's workspace root (falling back to the open document's own
+directory), renders every state's `file:` into an absolute-path → `mode` map,
+and dispatches on it — first declaring state wins a path conflict. A path the
+map doesn't cover (or no config at all) falls back to the basename dispatch
+(`TODO.md` → `qa`, `REVIEW.md` → `review`), so the server still works standalone
+with no `.gtdrc` in sight. Also registers an `executeCommand`,
+`gtd.openSteeringFile`: resolves the current state exactly like `gtd status`
+(config + git HEAD) and asks the client to show its `file:`
+(`window/showDocument`); a state with no `file:` gets an informational message
+naming the state instead — bind it to an editor keybinding for a "jump to the
+active steering file" command.
+
+Dispatched before the repository-root guard and auto-init, like `gtd format`.
+Rejects `--json` (exit 1, `gtd lsp does not accept --json`) and extra positional
+arguments — it's a long-running server, not a state command. Runs until the
+client disconnects (the LSP `exit` notification), then exits cleanly.
+
+## Error envelope
+
+Every command, in `--json` mode, reports a failure as a machine-readable
+envelope on **stdout**, and still exits 1:
+
+```json
+{ "state": "error", "prompt": "<message>" }
+```
+
+A human-readable `gtd: <message>` line is still written to **stderr** regardless
+of `--json` — the envelope adds a structured stdout channel, it does not replace
+the plain-text one.
+
+## Repository requirements
+
+- **Single writer, linear branch.** A process's history is walked via
+  **first-parent** commits only.
+- **Test/build artifacts must be gitignored.** This is **load-bearing**, not a
+  style preference: every step decision detects "clean" via
+  `git diff --name-status HEAD` (tracked changes) unioned with
+  `git ls-files --others --exclude-standard` (untracked files), which silently
+  omits anything matched by `.gitignore`. If a `script` state's command (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 run, and the check's `"C"` pattern never fires. Gitignore every path
+  your scripts write before wiring gtd into a repo.
+- **Repository root invocation.** Every state subcommand (`step`/`next`/`run`/
+  `status`) must run from the git repository root — the workflow, pending
+  changes, and process history are resolved against the process cwd.
+  `--help`/`--version`, `format`, and `lsp` skip this guard entirely (and any
+  git/`.gtdrc` dependency along with it).

package/docs/configuration.md

@@ -0,0 +1,377 @@
+# Configuration
+
+gtd reads an optional `.gtdrc` config file via
+[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). With no config, the
+bundled default workflow applies (see
+[STATES.md](../STATES.md#10-the-bundled-default-workflow)). Supported filenames
+(searched in this order):
+
+- `.gtdrc`
+- `.gtdrc.json`
+- `.gtdrc.yaml`
+- `.gtdrc.yml`
+- `gtd.config.json`
+- `gtd.config.yaml`
+
+## Schema
+
+v3's `.gtdrc` has exactly two blessed top-level keys:
+
+- **`workflow`** (object, optional) — the whole machine definition, compiled by
+  `src/PatternConfig.ts`. Absent = the bundled default workflow. See
+  ["The `workflow:` key" below](#the-workflow-key) for its schema.
+- **`vars`** (object, optional) — a flat `name -> scalar` map, one layer of the
+  merged `it.vars` every template sees — see ["Variables"](#variables) below.
+- **`$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 `src/ConfigSchema.ts` at
+  build time and ships with the package.
+
+Any other top-level key is **rejected** (`onExcessProperty: "error"`) — v3 has
+no `testCommand`, `fixAttemptCap`, `reviewThreshold`, `agenticReview`, `squash`,
+`learning`, `decisionLog`, or `models` keys; all of that machinery is gone (see
+[Upgrading](upgrading.md)). The engine blesses no VARIABLE NAMES either —
+`testCommand` (the bundled default workflow's own var, see
+["Variables"](#variables)) is workflow-authored data like any other `it.vars`
+entry, not a special key gtd interprets.
+
+## The `workflow:` key
+
+The `workflow:` key is the **only** definition source — there is no `extends`,
+no merge-over-a-built-in; the bundled default workflow is itself a YAML asset
+compiled through the exact same compiler (`src/workflows/default.yaml` →
+`compileWorkflowConfig`). Its shape:
+
+```yaml
+workflow:
+  vars: # optional — the workflow's own declared `it.vars` defaults (see "Variables" below)
+    anyKey: anyScalarValue
+  states:
+    <name>:
+      actor: <string> # forbidden on a commit state, required otherwise
+      script: <string> # exactly one of script/prompt/message/commit
+      prompt: <string>
+      message: <string>
+      commit: <string>
+      on: # a mapping, DECLARATION ORDER PRESERVED
+        "<pattern>": <targetState>
+      initial: true # exactly one state across the whole workflow
+      retry:
+        max: <number>
+        otherwise: <targetState>
+      model: <string> # optional, opaque harness hint — forbidden on a commit state
+      file: <string> # optional, an Eta template naming the state's steering file — forbidden on a commit state
+      mode: qa | review # optional, requires "file" — forbidden on a commit state
+```
+
+See [STATES.md](../STATES.md#1-the-model) for what each field means to the
+engine, and [§3](../STATES.md#3-pattern-grammar) for the pattern grammar.
+
+### Content values: inline or a file reference
+
+A `script`/`prompt`/`message`/`commit` value starting with `./` or `../` is a
+**file reference** — resolved relative to the config file's own directory and
+read at load time. A missing or unreadable file reference is a **load error**,
+collected and thrown with every other config problem — never silently treated as
+inline text. Any other string (including one that merely contains a `/`, or an
+absolute path) is inline Eta template source, used verbatim.
+
+```yaml
+workflow:
+  states:
+    working:
+      actor: agent
+      prompt: ./prompts/working.md # read from alongside this .gtdrc
+      on:
+        "* **": done
+```
+
+A `vars:` key sibling to `states:` inside `workflow:` declares the workflow's
+own defaults for `it.vars` — see ["Variables"](#variables) below for the full
+three-layer picture.
+
+### `model:` — the opaque harness hint, template-rendered
+
+A state may declare `model: <string>` — an OPAQUE label (e.g. `smart`, `fast`,
+or a concrete model id) gtd never interprets; it is only passed through so the
+driving loop can map it onto whatever models its agent harness provides. Unset
+means "use the harness's default." Forbidden on a commit state (never at rest,
+emits nothing):
+
+```yaml
+workflow:
+  states:
+    working:
+      actor: agent
+      model: smart
+      prompt: do the thing
+      on:
+        "* **": done
+```
+
+Like every content string, `model:` is rendered as an Eta template through the
+exact same context as the state's content — a plain string with no Eta tags
+(`smart` above) passes through unchanged, but
+`model: "<%= it.vars.reviewModel %>"` resolves against the merged `it.vars` (see
+["Variables"](#variables)). A render failure behaves exactly like a content
+render failure at the same call site: `gtd next`/`gtd status` error out, nothing
+committed.
+
+`gtd next --json` and `gtd status --json` include a `"model"` key (the RENDERED
+value) only when the resolved state declares one — it is **omitted entirely**,
+never emitted as `null`, when unset.
+
+### `file:`/`mode:` — the steering-file association
+
+A state may additionally declare `file:` — an Eta template naming THE steering
+file this state is about: the file a human/editor should look at while the
+machine rests here (rendered through the same `it.vars`-carrying context as
+content/`model`; must render non-empty). Forbidden on a commit state (never at
+rest). Multiple states may share one `file:` (and, in the bundled default, do):
+
+```yaml
+workflow:
+  vars:
+    planFile: .gtd/PLAN.md
+  states:
+    working:
+      actor: agent
+      file: <%= it.vars.planFile %>
+      mode: qa
+      prompt: develop the plan
+      on:
+        "* **": done
+```
+
+`mode:` requires a sibling `file:` and names the file's FORMAT, from a closed,
+documented vocabulary:
+
+| `mode`   | Format                                                                                                                       |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `qa`     | The open-questions format (`## Open Questions`, one `###` sub-heading per question, `Suggested default: ...`/`Answer: ...`). |
+| `review` | The checkbox review format (`# Review: <hash>` header, `<!-- base: <hash> -->` comment, `##` chunks, `- [ ]` pointers).      |
+
+An unknown `mode` value is a load error naming the allowed values (typos must
+not silently disable editor support) — like `model`, the ENGINE never branches
+on `mode`; only `gtd lsp` (see
+[docs/design/state-file-association.md](design/state-file-association.md))
+interprets it, to decide which document symbols/code actions/diagnostics a file
+gets.
+
+`gtd next --json`/`gtd status --json` gain `"file"` (the RENDERED path) and
+`"mode"` (verbatim) keys, each **omitted entirely** (never `null`) when the
+resolved state declares none — exactly like `model`. Plain `gtd status` prints
+`File:`/`Mode:` lines (right after `Model:`, when present) when set.
+
+**Known limitation — `on` pattern keys are NOT Eta templates.** A workflow's
+`on` patterns keep LITERAL `.gtd/…` paths, so repointing a filename var
+(`.gtdrc`'s top-level `vars:`, or a `GTD_VAR_` override) without ALSO overriding
+the workflow's `on` patterns desyncs the machine: `file:` (and any template
+reading/writing that path) follows the var, but the `on` map that decides what a
+change to that path MEANS keeps matching the old literal path. The vars are a
+DRY mechanism inside templates and the state↔file association, not a rename
+switch. (Making pattern keys var-aware at compile time is possible future work.)
+
+### Template variables
+
+Every `script`/`prompt`/`message`/`commit`/`model` template is rendered as an
+Eta template (`it.<name>`) with:
+
+| Variable         | Meaning                                                                                                                                                                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `startCommit`    | The hash the current process started from (before its first turn).                                                                                                                                                                      |
+| `currentCommit`  | HEAD's hash at render time.                                                                                                                                                                                                             |
+| `previousCommit` | The hash before the last transition (HEAD's parent, in-process).                                                                                                                                                                        |
+| `state`          | The state whose content is being rendered.                                                                                                                                                                                              |
+| `actor`          | The actor this render is for.                                                                                                                                                                                                           |
+| `processDiff`    | `startCommit..HEAD` plus the pending working-tree diff.                                                                                                                                                                                 |
+| `lastDiff`       | The diff of the last transition alone.                                                                                                                                                                                                  |
+| `read(path)`     | Reads a working-tree file (pending contents, not HEAD's) by repo-relative path. Throws for a missing/unreadable path — for a `commit:` template, that throw refuses the step (see [STATES.md §8](../STATES.md#8-the-squash-lifecycle)). |
+| `vars`           | The merged three-layer variable map, always a flat `Record<string, string>` — see ["Variables"](#variables) below.                                                                                                                      |
+
+## Variables
+
+Every template — `script`/`prompt`/`message`/`commit`, and now `model` — sees
+`it.vars`: a flat `Record<string, string>` assembled from three layers, **later
+wins**:
+
+1. **The workflow's own `vars:` key** (sibling to `states:`, shown above) — the
+   workflow author's declared defaults. The bundled default workflow declares
+   `vars: { testCommand: "npm test" }`, read by `checking`'s script as
+   `<%~ it.vars.testCommand %>` (see
+   [STATES.md §10](../STATES.md#10-the-bundled-default-workflow)).
+2. **A top-level `.gtdrc` `vars:` key** (a sibling of `workflow:`, NOT nested
+   inside it) — per-repo tuning without redefining the whole workflow. Subject
+   to the same cwd→home deep merge as everything else in `.gtdrc` (innermost
+   wins per-key).
+3. **`GTD_VAR_<name>` environment variables** — highest precedence, checked at
+   every invocation. The prefix is stripped and the REMAINING CASE matched
+   exactly: `GTD_VAR_testCommand` sets `testCommand`, not `TESTCOMMAND` or
+   `testcommand`. This is the only layer that may introduce a name neither
+   config layer declared.
+
+Values in layers 1–2 must be YAML scalars (string/number/boolean) — coerced to
+strings at load time; an object or array value is a load error, collected
+alongside every other config-shape finding (see
+["Validation and errors"](#validation-and-errors)). Environment values are
+already strings.
+
+```yaml
+# .gtdrc — overriding the bundled default's testCommand
+vars:
+  testCommand: npm run test:ci
+```
+
+```bash
+# highest precedence — beats both the workflow default and the .gtdrc value above
+GTD_VAR_testCommand="npm run test -- --bail" gtd run
+```
+
+A template reads any of it as `it.vars.<name>`:
+
+```yaml
+workflow:
+  vars:
+    reviewer: alice
+  states:
+    working:
+      actor: agent
+      prompt: "Assigned reviewer: <%= it.vars.reviewer %>"
+      model: "<%= it.vars.reviewModel %>" # a GTD_VAR_reviewModel override, or a .gtdrc vars: entry
+      on:
+        "* **": done
+```
+
+No variable name is blessed by the engine — `testCommand` is workflow-authored
+data like any other `it.vars` entry, not a special key gtd interprets; a custom
+workflow is free to declare and read any names it likes.
+
+## Validation and errors
+
+Config-shape problems (unknown keys, wrong types, unreadable file references)
+are collected together; if the shape is clean, the assembled definition is
+additionally run through the engine's own `validateDefinition` (see
+[STATES.md §9](../STATES.md#9-validation)). A bad config throws **one** error
+listing every finding, at load time — before anything touches the repository —
+never partially, and never deferred to step time:
+
+```
+workflow config:
+  - state "idle": must declare exactly one of script/prompt/message/commit (found 2)
+  - state "idle": "on" target "nowhere" is not a defined state
+```
+
+Other load failures:
+
+- **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.
+- **Unknown top-level key** — anything besides `workflow`/`vars`/`$schema` emits
+  `Invalid gtd config: <field>: <reason>`.
+- **A bad top-level `vars:` entry** — an object/array value fails the same way
+  as a bad workflow-level `vars:` entry (see ["Variables"](#variables)), one
+  aggregated error:
+  `gtd config:\n  - "vars.<name>" must be a string, number, or boolean, got <type>`.
+
+All of these exit **1** and write to **stderr**, never stdout.
+
+## 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 with its own `.gtdrc`.
+
+## Auto-init
+
+On every **state command** (`step`, `next`, `run`, `status`) 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 isn't a `gtd(actor): state` commit, the stub is committed as its own
+`chore: add .gtdrc.json`. If HEAD is already a `gtd(actor): state` commit
+(mid-process), the stub is instead **amended into HEAD** — stacking a fresh
+boundary commit there would produce an unrecognized HEAD that resolves back to
+the workflow's initial state.
+
+## A complete example
+
+A three-state note-taking machine: draft, revise-or-accept, and a squashed
+commit — one prompt/message pair reading a workflow-declared `it.vars` entry:
+
+```yaml
+# .gtdrc.yaml
+workflow:
+  vars:
+    reviewer: alice
+  states:
+    idle:
+      actor: human
+      initial: true
+      message: |
+        No active note. Write NOTE.md with what you want written up, then run
+        `gtd step human`.
+      on:
+        "* **": drafting
+
+    drafting:
+      actor: agent
+      prompt: |
+        Read NOTE.md and draft a short write-up in DRAFT.md.
+        Reviewer of record: <%= it.vars.reviewer %>.
+        Leave DRAFT.md uncommitted and finish your turn.
+      on:
+        "* **": revising
+
+    revising:
+      actor: human
+      message: |
+        DRAFT.md holds the draft. Edit it for another round, or run
+        `gtd step human` with no edits to accept it and write the commit
+        message.
+      on:
+        "C": working
+        "* **": drafting
+
+    working:
+      actor: agent
+      prompt: |
+        The draft is accepted. Write COMMIT_MSG.md with one conventional-
+        commits message for the whole cycle, then finish your turn.
+      on:
+        "A COMMIT_MSG.md": done
+        "M COMMIT_MSG.md": done
+
+    done:
+      commit: '<%~ it.read("COMMIT_MSG.md") %>'
+```
+
+A clean `gtd step human` at `revising` (the `C` event) accepts the draft and
+moves to `working`; any other pending change loops back to `drafting`. Writing
+`COMMIT_MSG.md` at `working` enters `done`, which squashes every commit since
+`idle` into one, using `COMMIT_MSG.md`'s content as the message, and discards
+the file.
+
+## Recipe: a per-task builder loop without a script state
+
+A `picking`-style queue arbiter (see
+[docs/examples/advanced-workflow.md](examples/advanced-workflow.md)) is a
+`script` state that turns a task-queue glob into a diff patterns can see. A
+driver that can't run scripts can get the same per-task loop out of pure
+prompt/`on` declarations instead, at the cost of trusting the agent to honor a
+marker protocol rather than a deterministic `ls`: see
+[docs/design/work-packages.md §3](design/work-packages.md) ("Option B —
+agent-encoded verdict") for the worked example.
+
+## A fuller example: two-phase planning, task decomposition, agent-prepared review
+
+The bundled default above is deliberately small. For a heavier machine — Q&A
+planning loops, an architecture phase, task decomposition, the deterministic
+per-task `picking` arbiter, and agent-prepared `.gtd/REVIEW.md` review — see
+[docs/examples/advanced-workflow.md](examples/advanced-workflow.md), a
+copy-paste-ready `.gtdrc` recipe.