@pmelab/gtd 5.0.0 → 6.0.0

package/docs/cli.md

@@ -4,16 +4,23 @@
 Usage: gtd [command] [options]
 
 Commands:
+  init <workflow>  Scaffold a .gtdrc.json for this repo with the chosen
+                   bundled workflow inline (one of: simple, advanced). 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
                    --cost=<n> (optionally --model=<name>) to record the
                    just-finished invocation's token cost and model on the
                    turn commit (summed into it.processCost/processCostByModel)
+  review <commitish>
+                   Start a NEW review process at the workflow's declared
+                   review-entry state (reviewEntry: true), reviewing
+                   <commitish>..HEAD — e.g. a colleague's PR branch. Requires
+                   a clean tree resting at the workflow's initial state
   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)
   validate         Format and validate the steering file the resolved rest
@@ -47,6 +54,28 @@ mistyped flag can never degrade a JSON caller to plain-text mode. A bare
 `--model`, `--model` without `--cost`, or either flag on any command other than
 `gtd step` are all usage errors.
 
+## `gtd init <workflow>`
+
+Scaffolds a `.gtdrc.json` at the repository root with one of the bundled
+workflow templates inline under a `workflow:` key, plus a `$schema` link.
+`<workflow>` is required and must be `simple` or `advanced` (a missing or
+unknown name is a usage error listing both). gtd ships **no** default workflow,
+so this is the one-time setup step for a repo; a state command run before it
+fails with `gtd: no workflow configured — run \`gtd init <simple|advanced>\` …`.
+
+- `simple` — the 10-state machine (see
+  [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
+- `advanced` — the fuller machine (see
+  [advanced-workflow.md](examples/advanced-workflow.md)).
+
+The file is written **uncommitted**; review and commit it before your first
+`gtd step` (an uncommitted `.gtdrc.json` is a pending change the initial state
+would otherwise capture). `gtd init` refuses if any gtd config already exists,
+requires the repository root, and — with `gtd lsp` — is one of the two commands
+that run with no workflow configured. `--json` prints
+`{"written":".gtdrc.json","workflow":"<name>"}`. See
+[Configuration](configuration.md#gtd-init).
+
 ## `gtd step <actor> [--cost=<n>] [--model=<name>]`
 
 Authenticates `<actor>` against the resolved rest and performs the ONE resulting
@@ -103,6 +132,49 @@ not passed):
 }
 ```
 
+## `gtd review <commitish> [--json]`
+
+Starts a BRAND NEW review process at the active workflow's declared
+`reviewEntry: true` state (see
+[STATES.md §11](../STATES.md#11-the-review-checkout-window)), reviewing
+`<commitish>..HEAD` — e.g. a colleague's PR branch pushed on top of a shared
+base, with no gtd process of its own. Reuses the workflow's existing
+review/feedback machinery unmodified; there is no separate review-entry command
+surface to keep in sync.
+
+Requires, in order (any failure is a plain refusal — exit non-zero, nothing
+written):
+
+- the machine currently resting at the workflow's **initial state** (a plain
+  non-gtd branch resolves there via the inert-subject rule — the normal case; a
+  process already underway refuses);
+- a **clean working tree**;
+- the active workflow declaring a **`reviewEntry: true`** state (otherwise:
+  `gtd review: the active workflow declares no review entry state`);
+- `<commitish>` resolving to a commit, being an **ancestor of HEAD**, and
+  **differing from HEAD** (nothing to review otherwise).
+
+On success, writes ONE empty commit, `gtd(human): <review-entry-state>`,
+carrying the resolved commit's full hash as a `Gtd-Review-Base: <hash>` trailer
+(mirroring how `gtd step --cost` writes its own `Gtd-Cost:` trailer). Everything
+downstream that renders a diff — `it.processDiff`, and the review checkout
+window opened by a downstream `reviewWindow: true` state — keys off the
+process's diff base, and this trailer is exactly how that base gets re-pointed
+at `<commitish>..HEAD` (see
+[STATES.md §7](../STATES.md#7-retry)/[§11](../STATES.md#11-the-review-checkout-window)).
+
+Plain-mode output is one line, same shape as `gtd step`:
+
+```
+committed: gtd(human): reviewing
+```
+
+`--json` emits `{state, subject}` — `state` is the entered review-entry state,
+`subject` the bare commit subject (the trailer is not echoed).
+
+Takes exactly one positional argument (`<commitish>`); missing or extra
+arguments are usage errors.
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -247,9 +319,9 @@ Then:
   approve), has nothing to validate and exits `0`
   (`nothing to validate at "<state>"`). Nothing is formatted in that case.
 
-This is how the bundled default keeps its steering files well-formed without an
-in-machine validation state — and the check runs whoever last touched the file,
-agent or human:
+This is how the `simple` template keeps its steering files well-formed without
+an in-machine validation state — and the check runs whoever last touched the
+file, 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
@@ -330,8 +402,9 @@ with no `.gtdrc` in sight. Also registers an `executeCommand`,
 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 — the server needs no
-git/workflow state of its own. Rejects `--json` (exit 1,
+Dispatched before the repository-root guard and the config-reading path — the
+server needs no git/workflow state of its own (like `gtd init`, it runs with no
+workflow configured). 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.
@@ -362,8 +435,8 @@ the plain-text one.
   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`/
-  `status`/`mermaid`) 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).
+- **Repository root invocation.** Every state subcommand (`step`/`review`/
+  `next`/`status`/`mermaid`) 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

@@ -1,10 +1,11 @@
 # 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):
+gtd reads a required `.gtdrc` config file via
+[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). gtd ships **no**
+default workflow: scaffold one for the repo with [`gtd init`](#gtd-init) (once),
+which writes a `.gtdrc.json` carrying a bundled workflow template inline. A
+state command run with no `workflow:` configured fails, pointing you at
+`gtd init`. Supported filenames (searched in this order):
 
 - `.gtdrc`
 - `.gtdrc.json`
@@ -17,16 +18,17 @@ bundled default workflow applies (see
 
 v3's `.gtdrc` has exactly three blessed top-level keys:
 
-- **`workflow`** (object, optional) — the whole machine definition (its states,
-  plus its own `vars:` defaults and `modes:`), compiled by
-  `src/PatternConfig.ts`. Absent = the bundled default workflow. See
+- **`workflow`** (object, **required**) — the whole machine definition (its
+  states, plus its own `vars:` defaults and `modes:`), compiled by
+  `src/PatternConfig.ts`. Absent = a hard error pointing at
+  [`gtd init`](#gtd-init); there is no bundled default. 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.
 - **`modes`** (object, optional) — steering-file modes (`format:`/`validate:`
   shell commands), layered over the active workflow's own `modes:` and gtd's
   built-in validators, so a project can plug its formatter or linter into the
-  BUNDLED default without re-declaring a workflow. See
+  configured workflow without re-declaring that mode on the workflow itself. See
   ["`modes:`"](#modes--pluggable-steering-file-modes) below.
 - **`$schema`** (string, optional) — stripped before validation, so it never
   counts as an unknown key. Point it at the published schema for editor-backed
@@ -37,16 +39,18 @@ 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.
+`testCommand` (the bundled templates' 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:
+no merge-over-a-built-in. The bundled templates `gtd init` scaffolds are
+themselves YAML assets (`src/workflows/simple.yaml`,
+`src/workflows/advanced.yaml`) compiled through the exact same compiler
+(`compileWorkflowConfig`); `gtd init` just writes one of them, inline, under
+this key. Its shape:
 
 ```yaml
 workflow:
@@ -219,9 +223,9 @@ Because `grilling` re-enters itself around the answer loop, every lap emits
 `building` emits a different label (`build`), which is where the driver clears
 memory for a fresh implementation turn. A loop of same-labelled turns retains; a
 differently-labelled state at a phase boundary clears. This is exactly how the
-bundled default scopes its four agent states (`plan`/`build`/`fix`/`review` —
-see [STATES.md §10](../STATES.md#10-the-bundled-default-workflow)), and how the
-loop driver reads it is spelled out in `skills/loop/SKILL.md`.
+`simple` template scopes its four agent states (`plan`/`build`/`fix`/`review` —
+see [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)), and how
+the loop driver reads it is spelled out in `skills/loop/SKILL.md`.
 
 Like `model`, `memory:` is rendered as an Eta template through the same context
 as the state's content — a plain label (`plan`) passes through unchanged, while
@@ -239,7 +243,8 @@ 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):
+rest). Multiple states may share one `file:` (and, in the `simple` template,
+do):
 
 ```yaml
 workflow:
@@ -357,16 +362,20 @@ So for a state declaring `mode: qa`:
 | both                             | its `format:` | its `validate:`             |
 
 That is what makes the built-in modes extensible rather than all-or-nothing —
-and the top-level key means a project on the BUNDLED default workflow can plug
-in its formatter without copying a single state:
-
-```yaml
-# .gtdrc — keep the bundled default workflow, add your own markdown formatter
-modes:
-  qa:
-    format: "npx prettier --write <%= it.file %>"
-  review:
-    format: "npx prettier --write <%= it.file %>"
+and the top-level key means a project can plug its formatter into whichever
+workflow it scaffolded (`gtd init simple`/`advanced`) without re-declaring a
+`modes:` block on the workflow itself. Add it alongside the `workflow:` key in
+your `.gtdrc.json`:
+
+```jsonc
+// .gtdrc.json — the workflow from `gtd init`, plus your own markdown formatter
+{
+  "workflow": { "...": "..." },
+  "modes": {
+    "qa": { "format": "npx prettier --write <%= it.file %>" },
+    "review": { "format": "npx prettier --write <%= it.file %>" },
+  },
+}
 ```
 
 **Known limitation — no live editor support for a custom mode.** `gtd lsp`
@@ -411,13 +420,50 @@ workflow:
         "* **": building
 ```
 
-The bundled default enables `reviewWindow: true` on `await-review` (no
+The `simple` template enables `reviewWindow: true` on `await-review` (no
 `reviewBase` state, so the base is the whole cycle). The pure engine never
 observes an open window — it is opened/closed entirely at the edge; the real
 head is preserved under `refs/gtd/review-head` (the base under
 `refs/gtd/review-base`) for the window's lifetime. See
 [STATES.md §11](../STATES.md) for the full lifecycle.
 
+### `reviewEntry:` — the review entry point (`gtd review <commitish>`)
+
+A state may separately declare `reviewEntry: true` (at most one across the whole
+workflow; forbidden on a commit state and on the initial state). It marks the
+state [`gtd review <commitish>`](cli.md#gtd-review-commitish---json) enters to
+start a BRAND NEW process reviewing `<commitish>..HEAD` — e.g. a colleague's PR
+branch with no gtd process of its own — reusing whatever `on`/
+`reviewWindow`/`reviewBase` machinery that state and its downstream states
+already declare, with zero duplicated logic.
+
+```yaml
+workflow:
+  states:
+    # …
+    review:
+      actor: agent
+      reviewEntry: true # `gtd review <commitish>` starts a new process here
+      prompt: summarize <%~ it.processDiff %> for a human to check
+      on:
+        "* **": await-review
+```
+
+`gtd review <commitish>` requires resting at the workflow's initial state with a
+clean tree, and requires the active workflow to declare a `reviewEntry` state.
+It resolves `<commitish>` (which must name an ancestor of HEAD other than HEAD
+itself) and writes one empty `gtd(human): <review-entry-state>` turn commit
+carrying the resolved hash as a `Gtd-Review-Base:` trailer — read back by
+`computeProcessRun` to override the new process's diff base (`it.startCommit`
+and `it.processDiff` then cover `<commitish>..HEAD`, and a downstream
+`reviewWindow: true` state's checkout window opens over that same range). The
+process's `retry`/squash trace boundary is untouched: the entry commit's own
+parent is a non-workflow commit, so the ordinary boundary rule already stops
+there. See [STATES.md §11](../STATES.md#11-the-review-checkout-window) for the
+full mechanism.
+
+The bundled default enables `reviewEntry: true` on `reviewing` itself.
+
 ### Template variables
 
 Every `script`/`prompt`/`message`/`commit`/`model`/`memory`/`file` template is
@@ -425,7 +471,7 @@ rendered as an Eta template (`it.<name>`) with:
 
 | Variable             | Meaning                                                                                                                                                                                                                                                                                                                                    |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `startCommit`        | The hash the current process started from (before its first turn).                                                                                                                                                                                                                                                                         |
+| `startCommit`        | The current process's diff base — normally the process start, but re-pointed to `<commitish>`'s hash for a process `gtd review <commitish>` started (see ["`reviewEntry:`"](#reviewentry--the-review-entry-point-gtd-review-commitish)).                                                                                                   |
 | `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.                                                                                                                                                                                                                                                                                                 |
@@ -491,10 +537,10 @@ Every template — `script`/`prompt`/`message`/`commit`, and `model`/`memory`/
 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
+   workflow author's declared defaults. The `simple` template 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)).
+   [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
 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
@@ -512,7 +558,7 @@ alongside every other config-shape finding (see
 already strings.
 
 ```yaml
-# .gtdrc — overriding the bundled default's testCommand
+# .gtdrc — overriding the `simple` template's testCommand
 vars:
   testCommand: npm run test:ci
 ```
@@ -598,19 +644,38 @@ finds along the way. All found levels are **deep-merged**, with the **innermost
 directory cascades to every checkout beneath it, while any individual checkout
 can still override with its own `.gtdrc`.
 
-## Auto-init
+## `gtd init`
+
+gtd ships **no** default workflow, so a repo must scaffold one before any state
+command works:
+
+```bash
+gtd init simple      # or: gtd init advanced
+```
+
+`gtd init <workflow>` writes a `.gtdrc.json` at the repository root with the
+chosen bundled template's whole workflow inline under a `workflow:` key, plus a
+`$schema` link (so editors pick up completion/validation). The two templates:
+
+- **`simple`** — the 10-state machine walked through in
+  [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates): idle →
+  grilling ⇄ grilling-answer → building → checking ⇄ fixing (→ escalate) →
+  reviewing → await-review, resting back at idle on approval (no squash).
+- **`advanced`** — the fuller machine (two-phase Q&A planning, an architecture
+  phase, task decomposition, a per-task build queue, and a squash finale),
+  walked through at
+  [docs/examples/advanced-workflow.md](examples/advanced-workflow.md).
+
+The file is written **uncommitted** — review it, then commit it before your
+first `gtd step` (an uncommitted `.gtdrc.json` is a pending change the initial
+state's `* **` edge would otherwise capture). `gtd init` refuses if any gtd
+config already exists (remove it first to re-init), requires the repository
+root, and is one of the two commands (with `gtd lsp`) that run with no workflow
+configured. A state command run before `gtd init` fails with:
 
-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.
+```
+gtd: no workflow configured — run `gtd init <simple|advanced>` to create .gtdrc.json
+```
 
 ## A complete example
 
@@ -683,8 +748,8 @@ 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.
+The example above is deliberately small (it is close to the `simple` template).
+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 — run `gtd init advanced`, walked through at
+[docs/examples/advanced-workflow.md](examples/advanced-workflow.md).

package/docs/development.md

@@ -31,16 +31,18 @@ registry to keep in sync: a workflow's content strings are either inline in its
 YAML/`.gtdrc` or a `./`-relative file reference auto-inlined at config load
 (`src/PatternConfig.ts`) — see
 [Configuration](configuration.md#content-values-inline-or-a-file-reference). The
-bundled default workflow (`src/workflows/default.yaml`) is imported as raw text
-via tsdown's `.yaml`-as-text loader (`tsdown.config.ts`) and compiled through
-the same path a `.gtdrc` `workflow:` key goes through
-(`src/workflows/default.ts`) — no privileged code path.
+bundled workflow templates (`src/workflows/simple.yaml`,
+`src/workflows/advanced.yaml`) `gtd init` scaffolds are imported as raw text via
+tsdown's `.yaml`-as-text loader (`tsdown.config.ts`) and compiled through the
+same path a `.gtdrc` `workflow:` key goes through (`src/workflows/templates.ts`)
+— no privileged code path.
 
 `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
 resolves `./Foo.js` specifiers to the on-disk `./Foo.ts` and imports `*.yaml`
 files as raw text, mirroring tsdown's `.yaml`-as-text loader — this is what lets
-`src/workflows/default.yaml` resolve when running from source.
+`src/workflows/simple.yaml` and `src/workflows/advanced.yaml` resolve when
+running from source.
 
 The decision core is pure and IO-free: the pattern machine's shape (states,
 patterns, retry) is a plain-data `WorkflowDefinition` (`src/PatternMachine.ts`),

package/docs/examples/advanced-workflow.md

@@ -1,15 +1,17 @@
-# Example: the full grilling → architecting → decompose → picking → review machine
+# The `advanced` template: the full grilling → architecting → decompose → picking → review machine
 
-This is the fuller machine gtd shipped as its bundled default before the bundled
-default was drastically simplified (see
-[STATES.md §10](../../STATES.md#10-the-bundled-default-workflow) for what ships
-today — including the two steering-file validation loops the current default
-carries over `.gtd/TODO.md` and `.gtd/REVIEW.md`, which this example's own
-`grilling`/`reviewing` phases predate and don't validate). It is preserved here
-as a copy-paste-ready `.gtdrc` recipe for anyone who wants the heavier shape
-back.
+This walks through the **`advanced`** bundled workflow template — the fuller
+machine `gtd init advanced` scaffolds (`src/workflows/advanced.yaml`). The other
+bundled template, **`simple`** (`gtd init simple`), is the smaller 10-state
+machine walked through in
+[STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates) — including
+the two steering-file validation loops it carries over `.gtd/TODO.md` and
+`.gtd/REVIEW.md`, which this machine's own `grilling`/`reviewing` phases predate
+and don't validate. `gtd init advanced` writes the block below directly, so you
+normally don't paste it by hand; it's reproduced here as the annotated
+reference.
 
-Compared to the simplified bundled default, this machine adds:
+Compared to the `simple` template, this machine adds:
 
 - **Two-phase human-in-the-loop planning with Q&A loops** — `grilling` ⇄
   `grilling-answer` develops a product-level plan from `.gtd/TODO.md` one open
@@ -23,12 +25,15 @@ Compared to the simplified bundled default, this machine adds:
   `checking`/`fixing` loop, until the queue empties.
 - **Agent-prepared review** — `reviewing` has the agent write `.gtd/REVIEW.md`
   summarizing the full cycle diff for a human to check before `await-review`
-  resolves an approval or feedback.
+  resolves an approval or feedback. `reviewing` also declares
+  `reviewEntry: true`, so `gtd review <commitish>` can start a review process
+  here directly over `<commitish>..HEAD` (e.g. a colleague's PR branch) — see
+  [STATES.md §11](../../STATES.md#11-the-review-checkout-window).
 - **A squash finale** — approval at `await-review` moves to `squashing` (the
   agent authors `.gtd/COMMIT_MSG.md`) and then `done`, a `commit:` state that
-  squashes the whole cycle into one commit. The simplified bundled default drops
-  this: it rests at `idle` on approval instead and leaves every turn commit in
-  history for the human to squash (or not) however they choose.
+  squashes the whole cycle into one commit. The `simple` template drops this: it
+  rests at `idle` on approval instead and leaves every turn commit in history
+  for the human to squash (or not) however they choose.
 
 This example also carries `file:`/`mode:` annotations on every state that rests
 on a steering file (see the state table below and
@@ -41,11 +46,12 @@ actions/diagnostics off those declarations rather than a hardcoded basename:
 `review`-format (`vars.reviewFile`), and `fixing`/`escalate` declare `file:`
 alone (`vars.feedbackFile` is plain text, no LSP format).
 
-Paste the block below under a top-level `workflow:` key in your own `.gtdrc` (or
-`.gtdrc.yaml`) — it's the complete definition, unmodified in content from the
-version this example is frozen from, only re-indented to nest under `workflow:`.
-See [Configuration](../configuration.md) for the `.gtdrc` schema this slots
-into.
+Running `gtd init advanced` writes this whole definition into `.gtdrc.json`
+under a `workflow:` key for you. The block below is the same definition in YAML
+form (the source is `src/workflows/advanced.yaml`), nested under `workflow:` —
+paste it into your own `.gtdrc`/`.gtdrc.yaml` if you'd rather hand-author or
+tweak it. See [Configuration](../configuration.md) for the `.gtdrc` schema this
+slots into.
 
 ## State table
 
@@ -222,7 +228,7 @@ workflow:
       actor: check
       script: |
         #!/usr/bin/env bash
-        # gtd check turn (the queue arbiter) — the driver (`gtd run`) executes
+        # gtd check turn (the queue arbiter) — the loop driver executes
         # this verbatim, then steps the check actor. Mechanics only: take the
         # first task file (by name) under .gtd/tasks/ into .gtd/NEXT.md, or
         # remove .gtd/NEXT.md when the queue is empty. What NEXT.md's
@@ -265,7 +271,7 @@ workflow:
       actor: check
       script: |
         #!/usr/bin/env bash
-        # gtd check turn — the driver (`gtd run`) executes this verbatim, then
+        # gtd check turn — the loop driver executes this verbatim, then
         # steps the check actor. Mechanics only: run the test suite and record a
         # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another
         # fix round vs escalation) is decided by the workflow's own `on`/`retry`
@@ -333,6 +339,10 @@ workflow:
       file: <%= it.vars.reviewFile %>
       mode: review
       model: smart
+      # A second way in: `gtd review <commitish>` (clean tree, resting at the
+      # initial state) enters here directly over <commitish>..HEAD — see
+      # STATES.md §11.
+      reviewEntry: true
       prompt: |
         You are an autonomous coding agent. `.gtd/` holds this workflow's own
         state — never create, edit, or delete anything under `.gtd/` except
@@ -429,8 +439,8 @@ event) accepts the current phase's draft and moves on; any other pending change
 loops back for another round. `picking` is a `script` state whose only job is to
 inspect `.gtd/tasks/` (a tree property patterns can't see directly) and turn it
 into a diff patterns CAN see — see the walkthrough in
-[STATES.md §10](../../STATES.md#10-the-bundled-default-workflow) (the version of
-that section frozen alongside this example) for the full state-by-state
+[STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates) (the version
+of that section frozen alongside this example) for the full state-by-state
 narrative, including the `on`-declaration-order subtlety at `picking` and the
 `fixing` retry-cap pooling caveat.