@pmelab/gtd 8.0.0 → 8.2.0

package/docs/configuration.md

@@ -1,994 +0,0 @@
-# Configuration
-
-gtd reads an optional `.gtdrc` config file via
-[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). gtd ships the bundled
-**unified** workflow as its **built-in default**: with no `workflow:` configured
-anywhere in the cwd→home config chain, that default is used automatically, so a
-state command works out of the box with no config at all.
-[`gtd init`](#gtd-init) is optional — it seeds a minimal `.gtdrc.json` with the
-two things most projects tune (a `testCommand` var and a Prettier formatting
-suggestion), not the workflow. To CUSTOMIZE the machine itself, add your own
-[`workflow:`](#the-workflow-key) key. 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 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 = gtd's built-in default (the bundled unified
-  workflow) is used. Declare it to fully REPLACE that default with your own
-  machine (there is no `extends`/merge). 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
-  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
-  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 template'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
-
-> Authoring or editing a workflow with a coding agent?
-> `skills/authoring/SKILL.md` is the agent-facing contract for producing a valid
-> `workflow:` — the state model, pattern grammar, load-time rules, and how to
-> verify a change compiles. This section is the exhaustive schema reference
-> behind it.
-
-A declared `workflow:` key fully REPLACES gtd's built-in default — there is no
-`extends`, no merge-over-a-built-in. The built-in default is itself a YAML asset
-(`src/workflows/unified.yaml`) compiled through the exact same compiler
-(`compileWorkflowConfig`) your own `workflow:` value goes through — no
-privileged code path — so you can materialize it into config form as a starting
-point to edit (`renderInitConfig` in `src/workflows/templates.ts`). Its shape:
-
-```yaml
-workflow:
-  vars: # optional — the workflow's own declared `it.vars` defaults (see "Variables" below)
-    anyKey: anyScalarValue
-  modes: # optional — steering-file modes a state's `mode:` may name (see "modes:" below)
-    <name>:
-      format: <shell command> # at least one of format/validate
-      validate: <shell command>
-  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> # short form
-        "<pattern>": { to: <targetState>, describe: <sentence> } # with a human-readable route description
-      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
-      memory: <string> # optional, opaque memory-scope label — forbidden on a commit state
-      file: <string> # optional, an Eta template naming the state's steering file — forbidden on a commit state
-      mode: <modeName> # optional, requires "file" — a built-in (qa/review/prose) or a `modes:` entry; 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 directory of the `.gtdrc` that
-declared it** (not the directory `gtd` runs from) 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.
-
-Because references anchor to the declaring file, a `.gtdrc` and its
-`gtd-prompts/` (or `prompts/`) directory can live **outside** the repo — e.g. in
-a parent directory shared across several repos. gtd still runs from the repo
-root, discovers the parent `.gtdrc` by walking up the directory chain (see
-["Lookup and precedence"](#lookup-and-precedence) — cwd→home), and inlines each
-level's `./`-relative references against that level's own directory. When
-workflows are layered across levels, every reference resolves against the file
-that wrote it, so a parent's `./gtd-prompts/x.md` and a child's never collide.
-(This is a capability of a `.gtdrc` you write yourself — `gtd init` seeds only
-`vars:`/`modes:`, not a `workflow:` with file references.)
-
-```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.
-
-### `on:` values — a target, or a `{ to, describe }` route description
-
-An `on` row's value is normally the target state name. It may instead be an
-object `{ to: <target>, describe: <sentence> }`, attaching a human-readable
-`describe` — a plain sentence explaining what making that kind of change does
-next. `describe` is **inert to the engine**: it plays no part in matching, is
-never Eta-rendered — UNLIKE the pattern key itself, which IS an Eta template
-(see below) — and never affects a decision. It exists only to be surfaced. A
-state's own edges are handed to its content template as `it.edges` (an array of
-`{ pattern, target, describe? }`, `pattern` already rendered, in declaration
-order), so a human gate's `message:` can render a "what each change does next"
-list from the same routing the engine uses — one source of truth:
-
-```yaml
-workflow:
-  states:
-    await-review:
-      actor: human
-      message: |
-        Review the diff, then run `gtd step human`.
-
-        What each change does next:
-        <% it.edges.forEach(function (e) { if (e.describe) { %>
-        <%~ "- " + e.describe + "\n" %>
-        <% } }) %>
-      on:
-        "D .gtd/REVIEW.md":
-          to: idle
-          describe:
-            "Delete `.gtd/REVIEW.md` to approve the whole cycle and rest at
-            idle."
-        "* **":
-          to: planning
-          describe:
-            "Change any source file to leave feedback and start another round."
-```
-
-The `<%~ "- " + e.describe + "\n" %>` idiom keeps each bullet's own newline: Eta
-strips the template's line breaks around `<% %>` control tags (its `autoTrim`
-default), not text inside an interpolation. Edges without a `describe` are
-skipped by the `if (e.describe)` guard. `gtd next --json` and
-`gtd status --json` also emit the `edges` array; both omit it when the state has
-no `on` (a commit state), and omit a per-edge `describe` when that edge declares
-none.
-
-**The pattern key (everything before the value) is an Eta template, rendered
-against `it.vars` alone** — the same vars-only slice `on` templates could ever
-need, since a pattern only ever names a path, never a diff or commit hash. A
-literal path (`"A .gtd/FEEDBACK.md": fix`) still works unchanged; naming a var
-instead (`"A <%= it.vars.feedbackFile %>": fix`) makes that row track a
-repointed `feedbackFile` the same way `file:` does — see
-["Variables"](#variables).
-
-### `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.
-
-### `memory:` — the memory-scope label, template-rendered
-
-A state may declare `memory: <string>` — an OPAQUE label gtd never interprets;
-it is passed through so a memory-aware driving loop can decide when an agent
-turn continues from the previous turn's memory and when it starts fresh. The
-contract is a **comparison, not a command**: two agent turns that emit the SAME
-`memory` value belong to the same memory scope (the driver retains the agent's
-memory across them), and a change in value — or the very first agent turn — is
-where the driver starts fresh. Unset means "use the harness's default."
-Forbidden on a commit state (never at rest):
-
-```yaml
-workflow:
-  states:
-    planning:
-      actor: agent
-      memory: plan
-      prompt: develop the sketch into a concrete plan
-      on:
-        "* **": plan-review
-    plan-review:
-      actor: human
-      message: accept the plan, or edit it to iterate
-      on:
-        "C": building
-        "* **": planning
-    building:
-      actor: agent
-      memory: build # a different scope — implementation starts fresh
-      prompt: implement the settled plan
-      on:
-        "* **": done
-    done:
-      commit: "feat: done"
-```
-
-Because `planning` re-enters itself around the review loop, every lap emits
-`memory: plan` and the planner keeps its accumulated exploration; the move to
-`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
-unified template scopes its agent states across the four `plan`/`build`/`fix`/
-`review` memory tiers (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
-`memory: "<%= it.vars.planScope %>"` resolves against the merged `it.vars`. A
-render failure behaves exactly like a content render failure:
-`gtd next`/`gtd status` error out, nothing committed.
-`gtd next --json`/`gtd status --json` include a `"memory"` key (the RENDERED
-value) only when the resolved state declares one — **omitted entirely**, never
-`null`, when unset. Plain `gtd status` prints a `Memory:` line (right after
-`Model:`, when present).
-
-### `label:` — the opaque display name, template-rendered
-
-A state may declare `label: <string>` — an OPAQUE display name gtd never
-interprets; it is only passed through so a driver/viewer can show something
-friendlier than the raw state name. Unset means the state has no display name.
-Forbidden on a commit state (never at rest, emits nothing):
-
-```yaml
-workflow:
-  states:
-    working:
-      actor: agent
-      label: Implement the feature
-      prompt: do the thing
-      on:
-        "* **": done
-```
-
-Like `model`/`memory`, `label:` is rendered as an Eta template through the exact
-same context as the state's content — a plain string with no Eta tags
-(`Implement the feature` above) passes through unchanged, but
-`label: "<%= it.vars.stateLabel %>"` 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 `"label"` key (the RENDERED
-value) only when the resolved state declares one — it is **omitted entirely**,
-never emitted as `null`, when unset. A driver/viewer choosing to fall back to
-the raw state name when `label` is absent is that consumer's own fallback, not
-something gtd itself does.
-
-### `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 unified template, 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 — a
-**steering-file mode**. Two names are BUILT IN, each carrying a VALIDATOR gtd
-implements itself:
-
-| `mode`   | Format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `qa`     | The open-questions format (`## Open Questions` near the top and `## Answered Questions` at the bottom, one `###` sub-heading per question with a free-form body; status is positional, no marker line). The bundled advanced flow additionally writes each open question as a checkbox list (candidate answers + a `- [ ] _your answer_` slot) and gates the human's answer step with `answerGate` (exactly one tick per question) — but that convention + gate live in the workflow/edge, not in this validator, which only checks the structure above. |
-| `review` | The checkbox review format (`# Review: <hash>` header, `<!-- base: <hash> -->` comment, `##` chunks, `- [ ]` pointers).                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-
-A THIRD name, `prose`, is also built in but ships **no validator at all** — a
-known mode name a state's `mode:` may use with no `modes:` declaration, that
-formats (once a `modes:` layer gives it a `format:` command) but never
-validates. It is for a curated, free-form document with no gtd-side schema — the
-bundled template's simple-flow plan file (`.gtd/TODO.md` at
-`planning`/`plan-review`) uses it.
-
-Any other name must be declared in a `modes:` map (next section) — as must a
-`format:` command for any of the three built-ins, since gtd ships no formatter.
-A `mode:` naming neither a built-in nor a declared mode is a load error listing
-both sets (typos must not silently disable the format gate or editor support).
-
-What a mode buys the state: before capturing a turn out of it, `gtd step`
-formats that file in place and validates it, refusing the step when it is
-invalid (`gtd validate` runs the same check on demand — see
-[STATES.md §12](../STATES.md) and [docs/cli.md](cli.md#gtd-validate)). The
-ENGINE itself never branches on `mode`; the edge does, and `gtd lsp` (see
-[docs/design/state-file-association.md](design/state-file-association.md)) reads
-it to decide which document symbols/code actions/diagnostics a file gets — for
-the built-in names only.
-
-`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.
-
-**`on` pattern keys are Eta templates too.** A workflow's `on` patterns may name
-a filename var the same way `file:`/content does — e.g.
-`"A <%= it.vars.feedbackFile %>": fix` instead of a literal
-`"A .gtd/FEEDBACK.md": fix`. The edge (`src/Edge.ts`'s `renderOnEdges`) renders
-every pattern's key against `it.vars` ALONE (no diffs/commit hashes — a pattern
-only ever needs to name a path) before handing the edges to the pure engine,
-which only ever matches plain, already-rendered strings. This is what lets a
-repointed filename var (`.gtdrc`'s top-level `vars:`, or a `GTD_` override)
-reroute the machine consistently: `file:` (and any template reading/ writing
-that path) and the `on` map that decides what a change to it MEANS both follow
-the same var. A pattern written with a literal `.gtd/…` path instead of the var
-still works exactly as before — only a workflow that templates its patterns
-benefits from the repoint.
-
-### `modes:` — pluggable steering-file modes
-
-A mode is a pair of SHELL COMMANDS over one file: `format:` rewrites it in
-place, `validate:` decides whether it is well-formed. Declare them beside
-`states:` (the workflow's own modes) and/or under a top-level `modes:` key (the
-project's layer over them), and point any state's `mode:` at the name:
-
-```yaml
-workflow:
-  modes:
-    adr:
-      format: "npx prettier --write <%= it.file %>"
-      validate: "./scripts/check-adr.sh <%= it.file %>"
-  states:
-    drafting:
-      actor: agent
-      prompt: "Write the ADR."
-      file: docs/adr/0001.md
-      mode: adr
-      on:
-        "* **": reviewing
-    # ...
-```
-
-The contract:
-
-- **`it.file`** is the already-rendered `file:` path. A command is an Eta
-  template over the same context every other template sees (so `it.vars` works
-  too) plus that one extra key. A `./`-prefixed command is a COMMAND, never a
-  `./`-relative file reference the way a content string is.
-- **`validate:` exits 0 for valid.** A non-zero exit means invalid, and its
-  output (stdout then stderr) becomes the findings, one per line — that is what
-  `gtd validate` prints and what the `gtd step` gate refuses with. A failing
-  command that prints nothing still refuses, with a synthesized finding.
-- **`format:` rewrites the file in place** and runs FIRST, so validation always
-  judges the formatted file. A non-zero exit is a HARD error (broken tooling,
-  not a malformed file): nothing is validated and nothing is committed.
-- **At least one of the two is required** in any single entry; the half it
-  leaves out falls through to the layer beneath (below), or is a no-op.
-- Commands run via `bash -c` from the repository root — the only place gtd
-  itself spawns a subprocess (a `script:` state is run by the loop driver, not
-  by gtd). A `.gtdrc` is project code: only add commands you would run yourself.
-
-#### The layers, half by half
-
-`format:` and `validate:` resolve INDEPENDENTLY, each from the first layer that
-declares it:
-
-1. the top-level `.gtdrc` `modes:` key (the project's own layer, cwd→home
-   deep-merged like any other config key);
-2. the active workflow's own `modes:` map;
-3. for the two VALIDATOR built-in names only, gtd's in-process validator — `qa`
-   → `src/OpenQuestions.ts`, `review` → `src/ReviewDoc.ts`. The third built-in,
-   `prose`, has no in-process validator to fall back to, so it validates nothing
-   unless a `modes:` layer above declares its own `validate:`. There is no
-   built-in formatter at this layer for any of the three: **gtd ships no
-   formatter**, so bring your own.
-
-So for a state declaring `mode: qa`:
-
-| `modes: { qa: … }`               | formats with  | validates with              |
-| -------------------------------- | ------------- | --------------------------- |
-| (nothing declared)               | nothing       | gtd's open-questions parser |
-| `format: npx prettier --write …` | that command  | gtd's open-questions parser |
-| `validate: my-linter …`          | nothing       | that command                |
-| 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 can plug its formatter into the built-in
-default workflow (or its own) without re-declaring a `modes:` block on the
-workflow itself. **`gtd init` seeds exactly this block by default** (the
-Prettier suggestion below), so a fresh repo already formats its steering files —
-edit or drop it to taste. It is what a scaffolded `.gtdrc.json` contains
-(`gtd init` writes no `workflow:` key — the built-in default is used):
-
-```jsonc
-// .gtdrc.json — as scaffolded by `gtd init`: a testCommand var and the markdown formatter
-{
-  "vars": { "testCommand": "npm test" },
-  "modes": {
-    "qa": { "format": "npx prettier --write <%= it.file %>" },
-    "review": { "format": "npx prettier --write <%= it.file %>" },
-    "prose": { "format": "npx prettier --write <%= it.file %>" },
-  },
-}
-```
-
-**Known limitation — no live editor support for a custom mode.** `gtd lsp`
-publishes diagnostics, document symbols and code actions for the built-in
-`qa`/`review` formats only (gtd never runs a mode command per keystroke over an
-unsaved buffer). A file whose validation is a command — and a `prose` file,
-which has no validator to publish diagnostics for — is still formatted and
-validated by `gtd validate` and the `gtd step` capture gate.
-
-### `reviewWindow:`/`reviewBase:` — the review checkout window
-
-A state may declare `reviewWindow: true`. While the machine RESTS there, gtd
-opens a **review checkout window**: it rewinds HEAD and the index to the review
-base (`git reset --mixed`) with the working tree untouched, so the whole
-`base..HEAD` diff surfaces as ordinary uncommitted changes in the editor's git
-integration (SCM panel, gutters, per-file diff, discard-hunk). The window closes
-automatically on the next invocation, once the machine rests anywhere else — and
-a reviewer's own edits, made while it was open, become the resting state's
-ordinary pending changes, captured by its `on` patterns like any other diff.
-Forbidden on a commit state (never at rest).
-
-The diff base defaults to the current process's start. To narrow it, mark an
-earlier state `reviewBase: true`: the most-recent in-process commit that entered
-such a state becomes the base, so only work committed after that milestone
-surfaces.
-
-```yaml
-workflow:
-  states:
-    # …
-    building:
-      actor: agent
-      reviewBase: true # the diff shown at review starts here…
-      prompt: implement the plan
-      on:
-        "* **": review
-    review:
-      actor: human
-      reviewWindow: true # …and is surfaced while resting here
-      message: review the diff in your editor, then `gtd step human`
-      on:
-        "C": done
-        "* **": building
-```
-
-The unified template enables `reviewWindow: true` on `await-review` and marks
-`review-deciding` `reviewBase: true`, so the first review covers the whole cycle
-but each subsequent feedback round's window narrows to `last-review..HEAD`. The
-pure engine never observes an open window — it is opened/closed entirely at the
-edge; the real head is preserved under `refs/worktree/gtd/review-head` (the base
-under `refs/worktree/gtd/review-base`) for the window's lifetime — git's
-per-worktree ref namespace, so linked worktrees of one repository each get their
-own window. 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 `review-start-check` — the
-green-baseline gate in front of `reviewing`.
-
-### `fixEntry:` — the fix entry point (`gtd fix`)
-
-A state may declare `fixEntry: true` (at most one across the whole workflow;
-forbidden on a commit state and on the initial state — the same rule family as
-`reviewEntry`). It marks the state [`gtd fix`](cli.md#gtd-fix---json) enters to
-start a BRAND NEW process that goes straight into repairing the current failing
-tests.
-
-```yaml
-workflow:
-  states:
-    # …
-    fix-check:
-      actor: check
-      fixEntry: true # `gtd fix` starts a new process here
-      script: <%~ it.vars.testCommand %> || echo fail > .gtd/FEEDBACK.md
-      on:
-        "A .gtd/FEEDBACK.md": fixing # red -> repair loop
-        "C": idle # green -> nothing to fix
-```
-
-`gtd fix` requires resting at the workflow's initial state with a clean tree,
-and requires the active workflow to declare a `fixEntry` state. Unlike
-`gtd review`, it writes NO `Gtd-Review-Base:` trailer — a fix reviews its own
-fixes from the ordinary process start — so it simply writes one empty
-`gtd(human): <fix-entry-state>` turn commit and lets the workflow's own `on`
-routing take over. The bundled default enables `fixEntry: true` on `fix-check`:
-a red suite drops into the shared `fixing` loop and out through the review +
-squash tail; a green suite is a no-op back to `idle`. See
-[STATES.md §10](../STATES.md#10-the-bundled-workflow-template).
-
-### Template variables
-
-Every `script`/`prompt`/`message`/`commit`/`model`/`memory`/`file` template is
-rendered as an Eta template (`it.<name>`) with:
-
-| Variable             | Meaning                                                                                                                                                                                                                                                                                                                                    |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `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.                                                                                                                                                                                                                                                                                                 |
-| `actor`              | The actor this render is for.                                                                                                                                                                                                                                                                                                              |
-| `processDiff`        | `startCommit..HEAD` plus the pending working-tree diff.                                                                                                                                                                                                                                                                                    |
-| `lastDiff`           | The diff of the last transition alone.                                                                                                                                                                                                                                                                                                     |
-| `processCost`        | The accumulated token cost of the current process — the sum of every `Gtd-Cost:` trailer recorded by `gtd step <actor> --cost=<n>` across its turn commits, plus the in-flight step's own `--cost` (so a `commit:` squash template sees the whole-process total). A number, `0` when none recorded. See ["Token cost"](#token-cost).       |
-| `processCostByModel` | The same accumulated cost broken down per model: an array of `{ model, cost }`, highest-cost first, one entry per distinct `--model` tag (costs recorded with no `--model` group under `"unspecified"`). A squash template iterates it to itemize the feature's cost per model. Empty when none recorded. See ["Token cost"](#token-cost). |
-| `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.                                                                                                                                                                                                                         |
-
-### Token cost
-
-A loop driver that knows how many tokens the invocation it just drove cost — and
-on which model — can record both with
-`gtd step <actor> --cost=<n> [--model=<name>]` (`<n>` a non-negative number).
-gtd appends them to that turn's commit as a `Gtd-Cost: <n> <model>` trailer — a
-blank line then the trailer, below the untouched `gtd(<actor>): <from> → <to>`
-subject — so the per-turn cost and model are persisted in the git log:
-
-```
-gtd(agent): building → reviewing
-
-Gtd-Cost: 1450 claude-opus-4-8
-```
-
-`--model` is optional and requires `--cost` (a model tag with no token count
-records nothing to sum); a cost recorded without a model is grouped under
-`"unspecified"`. `gtd status` shows the process's running total and, when the
-breakdown adds information, a per-model split (a `Cost:` line with indented
-`<model>: <cost>` lines / a `cost` number and a `costByModel` array, omitted
-when nothing has been recorded). `gtd step --json` echoes what it recorded
-(`{ "state": …, "subject": …, "cost": 1450, "model": "claude-opus-4-8" }`).
-
-Every template sees the running total as `it.processCost` and the per-model
-breakdown as `it.processCostByModel` (the table above): the current process's
-turn-commit entries, plus the in-flight step's own `--cost`/`--model`. Their
-intended use is a `commit:` squash template, which renders against the pending
-tree as the process collapses — so the whole feature's total AND its per-model
-itemization (including the squashing step itself) land in the squash message
-even though the intermediate per-turn trailers are discarded with the turns they
-rode on:
-
-```yaml
-done:
-  commit: |
-    feat: ship it
-
-    Total token cost: <%= it.processCost %>
-    <% it.processCostByModel.forEach(function(m){ %>
-    - <%= m.model %>: <%= m.cost %>
-    <% }) %>
-```
-
-`--cost`/`--model` are accepted only by `gtd step` (a usage error on any other
-command), and gtd never interprets the number's unit (tokens, cents, whatever
-the driver records) or the model name — it only records, sums, and groups them.
-
-## Sub-machines (`submachines:` / `use:`)
-
-Two OPTIONAL top-level keys let you factor repeated or complex clusters of
-states into reusable **sub-machines** that are expanded into ordinary concrete
-states at load time (see [STATES.md §13](../STATES.md) and
-`src/Submachines.ts`). They add NO runtime behavior — the engine only ever sees
-the expanded states — so a workflow authored with them is exactly a workflow
-written flat.
-
-```yaml
-workflow:
-  submachines:
-    gate: # authored once
-      params: [onGreen] # names referenced as `$onGreen` below
-      states:
-        check:
-          actor: check
-          script: <%~ it.vars.testCommand %>
-          on:
-            "A .gtd/FEEDBACK.md": blocked # a local state -> renamed by `as:`
-            "C": "$onGreen" # a param -> bound by `with:`
-        blocked:
-          actor: human
-          file: <%= it.vars.feedbackFile %>
-          message: "fix the baseline"
-          on: { "* **": check }
-  use:
-    - submachine: gate
-      as: { check: start-check, blocked: start-blocked } # local -> concrete (omit for identity)
-      with: { onGreen: planning } # bind each `$param`
-      set: { check: { reviewEntry: true } } # optional extra fields on a renamed state
-  states:
-    idle:
-      { actor: human, initial: true, message: "…", on: { "* **": start-check } }
-    planning: { actor: agent, prompt: "…", on: { "* **": start-check } }
-```
-
-Rules:
-
-- **`submachines: { <name>: { params, states } }`** — `states` are ordinary
-  state definitions, except an `on`/`retry.otherwise` target or any whole field
-  value may be a `$param` placeholder.
-- **`use:`** is an ordered list. Each entry names a `submachine:` and may set:
-  - **`as:`** — a `local -> concreteName` rename map. Omit it (or a given local)
-    for identity. Alias to the names a flat workflow would use to keep history
-    and `git log` unchanged.
-  - **`with:`** — bindings for the sub-machine's `$param`s.
-  - **`set:`** — extra fields merged onto a renamed state (e.g. `reviewEntry`).
-- **Substitution is WHOLE-VALUE only.** `$name` resolves only when it is the
-  entire value of a field or target — never a substring — so bash `$x`/`${x}`
-  and Eta `<%= it.vars.x %>` inside content are untouched. Pass per-instance
-  text (a whole message/prompt/`describe`) as a whole `$name` binding.
-- A target naming one of the sub-machine's own locals is rewritten via `as:`;
-  any other target passes through verbatim (a concrete top-level state). `on`
-  PATTERN keys are never substituted.
-- Expansion strips `submachines:`/`use:`; the merged `states` are then compiled
-  and `validateDefinition`'d normally. Unknown sub-machine, unbound `$param`,
-  and generated-name collisions are load-time errors, aggregated with the rest.
-
-`gtd init` scaffolds the EXPANDED flat config, so a fresh project never sees
-`submachines:`/`use:` unless it adds them itself. The bundled template is
-authored with them (dedup: `assertGreen`/`makeGreen`/`qaLoop`; comprehension:
-`planLoop`/`humanReview`/`specGate`/`packageLoop`) and its golden test pins that
-expansion is byte-identical to the flat form.
-
-## Variables
-
-Every template — `script`/`prompt`/`message`/`commit`, and `model`/`memory`/
-`file` — 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 unified template declares
-   `vars: { testCommand: "npm test" }`, read by `checking`'s script as
-   `<%~ it.vars.testCommand %>` (see
-   [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)). The bundled
-   template also declares two model-tier vars — `plannerModel` (default `smart`)
-   and `coderModel` (default `base`) — that every agent state's `model:`
-   resolves through (`model: <%= it.vars.plannerModel %>`), so repointing one
-   var here (or via layer 2/3 below) changes every state on that tier at once.
-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_<UPPERCASE-name>` environment variables** — highest precedence,
-   checked at every invocation, case-insensitively against each name already
-   declared by layer 1 or 2: `GTD_TESTCOMMAND` overrides `testCommand`. Unlike
-   the other two layers, the environment can only OVERRIDE a name a config layer
-   already declared — an uppercased env key can't round-trip back to an
-   arbitrary camelCase name, so a `GTD_*` var matching no declared name is
-   silently ignored.
-
-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.
-
-The bundled template also declares `stateDir: .gtd` — where its check scripts
-keep their own scratch/bookkeeping (the `.check-output` temp file,
-`review-deciding`'s exclusion of gtd's other state files when deciding whether
-the human hand-edited code this round). It is independent of the per-file vars
-(`todoFile`, `feedbackFile`, `reviewFile`, …): relocating one steering file
-outside `stateDir` needs no `stateDir` change (each check script creates that
-file's own parent directory as needed), and a project relocating its state
-wholesale sets both `stateDir` and the file vars it cares about.
-
-```yaml
-# .gtdrc — overriding the unified template's testCommand
-vars:
-  testCommand: npm run test:ci
-```
-
-```bash
-# highest precedence — beats both the workflow default and the .gtdrc value above.
-# The var is read at render time, so it shows up in the script `gtd next` prints
-# (and in what the loop driver then executes).
-GTD_TESTCOMMAND="npm run test -- --bail" gtd next
-```
-
-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_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
-```
-
-`validateDefinition`'s findings include the **semantic graph checks**: every
-`on` target and `retry.otherwise` must name a defined state, and every state
-must be **reachable** from the initial state by walking `on` targets and
-`retry.otherwise` redirects — an unreachable state (typically a typo'd rename or
-a leftover) is a load error like any other, since a workflow is bound to a
-project and edited as a project-wide change.
-
-Many of these problems never reach gtd at all if your editor validates against
-the published schema: `schema.json` fully types the `workflow:` key (state
-shape, content kinds, `on`/`retry` structure, the `modes:` map), so a
-yaml-language-server-style editor flags unknown keys and wrong types as you
-type. The rules JSON Schema cannot express — exactly one content kind, exactly
-one `initial: true`, targets naming defined states, reachability — remain the
-compiler's job at load time.
-
-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`/`modes`/`$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`.
-
-## `gtd init`
-
-gtd ships the bundled unified workflow as its **built-in default**, so a state
-command works out of the box with **no** config and no init at all. `gtd init`
-is therefore optional — it just seeds the two things most projects tune:
-
-```bash
-gtd init      # takes no argument
-```
-
-`gtd init` writes a **minimal** `.gtdrc.json` at the repository root — a
-`$schema` link (so editors pick up completion/validation), a
-`vars: { "testCommand": "npm test" }` entry (the var the built-in workflow's
-check script reads), and a ready-to-edit `modes:` formatting suggestion (below).
-It writes **no** `workflow:` key — the built-in default is used until you
-declare your own. It takes **no argument** — passing one is a usage error
-(`gtd init: too many arguments — init takes no argument`).
-
-`gtd init` writes only config — it derives no git state — so it need not run in
-a git repository. It runs at a **repository root** or in a directory **outside
-any repository** (scaffolding a shared config a nested repo picks up by walking
-up — see the parent-dir note under
-[file references](#content-values-inline-or-a-file-reference)); its guidance
-adjusts to say there is nothing to commit when it is not in a repo. It refuses
-only to write into a repository **subdirectory**, where the upward config walk
-would never find the file. Either way, it will not overwrite an existing config
-at that directory (remove it first to re-scaffold).
-
-The [`modes:`](#modes--pluggable-steering-file-modes) block it seeds is a
-ready-to-edit suggestion — a Prettier `format:` for each built-in steering-file
-mode the default workflow uses:
-
-```jsonc
-"modes": {
-  "qa": { "format": "npx prettier --write <%= it.file %>" },
-  "review": { "format": "npx prettier --write <%= it.file %>" },
-  "prose": { "format": "npx prettier --write <%= it.file %>" }
-}
-```
-
-Only `format:` is declared, so gtd's built-in `qa`/`review` validators still do
-the validating, and `prose` (a format-only built-in with no validator of its own
-— see the `mode:` section above) still validates nothing (the two halves layer
-independently). gtd ships no formatter, so this is the one default it suggests:
-a fresh repo auto-formats its steering files out of the box, and you edit or
-drop the block freely (swap Prettier for dprint, point at a script, or delete
-the key).
-
-The built-in default workflow has three entry points into a shared review/squash
-tail (all walked through in
-[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)):
-
-- **the simple flow** — creating `.gtd/TODO.md` starts idle → planning ⇄
-  plan-review → building → checking ⇄ fixing (→ escalate) → reviewing →
-  await-review.
-- **the advanced flow** — creating `.gtd/REQUIREMENTS.md` starts the fuller
-  machine: two-phase Q&A planning (product then architecture), package
-  decomposition, a per-package parallel build queue with an agentic spec-review
-  gate, then the same shared tail.
-- **`gtd review <commitish>`** — enters the shared `reviewing` state directly to
-  review a foreign branch.
-
-Both file-created flows converge on `reviewing` → `await-review`, and a full
-sign-off squashes the whole cycle into one commit. To CUSTOMIZE any of this, add
-a [`workflow:`](#the-workflow-key) key that fully replaces the default.
-
-The file is written **uncommitted** — review it, then commit `.gtdrc.json`
-before your first `gtd step` (an uncommitted file is a pending change the
-initial state's `* **` edge would otherwise capture). `gtd init` refuses if the
-repo root already has its OWN gtd config (remove it first to re-init; a
-global/ancestor config such as `~/.gtdrc` does not count) and requires the
-repository root (or a directory outside any repo).
-
-## 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 (the bundled unified template's advanced flow
-carries one — see
-[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)) 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 example above is deliberately small (it is close to the bundled unified
-template's simple flow). 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 — the unified template's
-**advanced flow** (started by creating `.gtd/REQUIREMENTS.md`) is exactly that,
-walked through in
-[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates).