@pmelab/gtd 7.0.0 → 7.1.1

package/docs/cli.md

@@ -25,6 +25,11 @@ Commands:
                    state (fixEntry: true) that goes straight into repairing the
                    current failing tests. Requires a clean tree resting at the
                    workflow's initial state
+  abandon          End the process currently underway without completing it:
+                   close any open review checkout window, then rewind HEAD to
+                   the commit the process started from, keeping everything it
+                   produced as uncommitted changes. A no-op when no process is
+                   underway
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   status           Print the resolved rest's state/actor and which declared
@@ -32,14 +37,15 @@ Commands:
   validate         Format and validate the steering file the resolved rest
                    declares, with its mode's commands (its file:/mode:);
                    exits non-zero with the findings when it is invalid
-  mermaid          Print the active workflow's shape as Mermaid
-                   stateDiagram-v2 source (no mutation)
   lsp              Start the LSP server for .gtd/ steering files (stdio)
+  visualize        Serve an interactive diagram of the active workflow locally
   version          Print version and exit
   help             Print this help and exit
 
 Options:
   --json           Output structured JSON instead of plain text
+  --port=<n>       (gtd visualize only) port to serve on (default: a free port)
+  --no-open        (gtd visualize only) do not open the browser
   --cost=<n>       (gtd step only) record the invocation's token cost
   --model=<name>   (gtd step only, with --cost) tag that cost's model
   --version, -v    Print version and exit
@@ -166,7 +172,8 @@ 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);
+  process already underway refuses — finish it, or
+  [`gtd abandon`](#gtd-abandon---json) it);
 - a **clean working tree**;
 - the active workflow declaring a **`reviewEntry: true`** state (otherwise:
   `gtd review: the active workflow declares no review entry state`);
@@ -212,7 +219,8 @@ 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 process
-  already underway refuses);
+  already underway refuses — finish it, or [`gtd abandon`](#gtd-abandon---json)
+  it);
 - a **clean working tree**;
 - the active workflow declaring a **`fixEntry: true`** state (otherwise:
   `gtd fix: the active workflow declares no fix entry state`).
@@ -231,6 +239,62 @@ unified template the fix-entry state is `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`.
 
+## `gtd abandon [--json]`
+
+Ends the process currently underway **without completing it** — the way out of a
+process nobody is going to finish, and the command `gtd review`/`gtd fix` name
+when they refuse ("finish it, or run `gtd abandon`, before starting a review").
+A workflow's own exit is its squash finale
+([STATES.md §8](../STATES.md#8-the-squash-lifecycle)); this is the human's, and
+it targets the same boundary:
+
+1. any open **review checkout window** is closed first (the bracket every state
+   subcommand runs — see
+   [STATES.md §11](../STATES.md#11-the-review-checkout-window)), so the rewind
+   starts from the real head, not the rewound base;
+2. HEAD is `git reset --mixed`ed to the commit the process started from (its
+   start parent — the same target a squash resets to).
+
+**Nothing is discarded.** Every turn commit the process wrote is dropped, and
+everything they carried — the code, the `.gtd/` steering files — stays in the
+working tree as uncommitted changes for you to keep, re-commit, or throw away
+with ordinary git:
+
+```
+abandoned the process resting at "await-review" — HEAD is back at 1a2b3c4
+("feat: add calculator"), resting at "idle".
+Everything the process produced is kept as uncommitted changes (`git status`);
+discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.
+```
+
+Takes no positional argument (extra arguments are a usage error). Resting at the
+workflow's initial state is a **no-op success**, not a refusal — a recovery
+command that fails when there is nothing to recover is a worse tool:
+
+```
+no gtd process is underway (resting at "idle") — nothing to abandon
+```
+
+The one refusal is a process whose first commit is the repository's own root
+commit: there is no earlier commit to rewind to, so its commits have to be
+removed by hand.
+
+`--json` emits `{state, abandoned, from, head}` — `state` is the initial state
+the machine returns to, `abandoned` whether anything was rewound, and (only when
+it was) `from` the state the abandoned process rested at plus `head` the full
+hash HEAD now points at:
+
+```json
+{
+  "state": "idle",
+  "abandoned": true,
+  "from": "await-review",
+  "head": "1a2b3c4…"
+}
+```
+
+The no-op reports `{"state": "idle", "abandoned": false}` and still exits 0.
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -394,46 +458,6 @@ agent or human:
 
 `gtd validate` takes no arguments.
 
-## `gtd mermaid`
-
-Pure emitter of the active workflow's **shape** — not the resolved rest — as
-Mermaid [`stateDiagram-v2`](https://mermaid.js.org/syntax/stateDiagram.html)
-source (see `src/Mermaid.ts`): one node per declared state, the `[*] -->`
-initial-state marker, one edge per declared `on` row labeled with its raw
-pattern string (same declaration order the engine itself evaluates), a `--> [*]`
-edge for every commit state (final, no outgoing edges — see
-[STATES.md §8](../STATES.md#8-the-squash-lifecycle)), and one `note right of`
-per rest naming its actor, content kind, and retry cap (e.g.
-`agent · prompt · retry 3→escalate`). No git, no HEAD resolution, no template
-rendering — purely a function of the compiled `WorkflowDefinition`, so its
-output is identical regardless of the current process/branch state.
-
-```
-$ gtd mermaid
-stateDiagram-v2
-    state "idle" as idle
-    state "planning" as planning
-    ...
-    [*] --> idle
-    idle --> planning : * **
-    ...
-    note right of idle : human · message
-    ...
-```
-
-Pipe it straight into a `.md`/`.mmd` file, a GitHub issue/PR description, or any
-Mermaid-aware renderer (GitHub, GitLab, VS Code, Obsidian, the
-[Mermaid Live Editor](https://mermaid.live)) to get a diagram of a custom
-`.gtdrc` `workflow:` with no hand-maintained docs required.
-
-State names are aliased to Mermaid-safe identifiers (non-word characters fold to
-`_`; a digit-led name gets an `s_` prefix) via a `state "<name>" as <alias>`
-declaration up front, so a hyphenated name like `plan-review` still displays
-with its exact declared spelling. Rejects `--json` (exit 1,
-`gtd mermaid does not accept --json`) — there is no structured shape to emit
-beyond the Mermaid source itself — and takes no arguments (extra positional args
-are rejected).
-
 ## `gtd lsp`
 
 Starts an LSP server over stdio for `.gtd/` steering files — document symbols
@@ -469,6 +493,39 @@ 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.
 
+## `gtd visualize [--port=<n>] [--no-open] [--json]`
+
+Serve an interactive diagram of the ACTIVE workflow on a local web server: the
+main flow as a graph (one box per sub-machine), and a click-through inspector
+with each state's actor, content kind, model/memory, steering file+mode, retry,
+flags, and outgoing/incoming edges. This is the replacement for the removed
+`gtd mermaid` — a live viewer instead of a static diagram dump.
+
+```
+$ gtd visualize
+gtd visualize running at http://127.0.0.1:53017 — Ctrl-C to stop
+```
+
+The server serves two routes: `/` (the self-contained HTML page) and
+`/workflow.json` (the model the page renders). It runs until interrupted
+(Ctrl-C), then closes cleanly. Options (orthogonal, `gtd visualize` only):
+
+- `--port=<n>` (or `--port <n>`) — serve on a specific port (0–65535); the
+  default is a free ephemeral port, printed on start.
+- `--no-open` — do not open the default browser (the URL is always printed).
+- `--json` — print the workflow model to stdout and exit WITHOUT starting a
+  server. The model is `{ states, initial, groups, vars }`; each state carries
+  its `actor`/`kind`/`model`/`memory`/`file`/`mode`/`retry`/`flags`, its `on`
+  edges, its computed `incoming` edges, and its sub-machine `group`. `groups`
+  lists each sub-machine invocation and the concrete states it produced.
+
+Dispatched before the repository-root guard and the config-reading path's review
+window — it reads the active workflow (the built-in default when none is
+configured) but touches no git/HEAD/review-window state. The diagram is rendered
+with Mermaid loaded from a CDN, so the graph needs network access the first time
+a browser loads the page; the inspector works offline regardless. Rejects
+unknown options and unexpected positional arguments.
+
 ## Error envelope
 
 Every command, in `--json` mode, reports a failure as a machine-readable
@@ -496,8 +553,16 @@ the plain-text one.
   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`/`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` (and the `help`/`version` subcommands),
-  `format`, and `lsp` skip this guard entirely (and any git/`.gtdrc` dependency
-  along with it).
+  `next`/`status`) must run from the git repository root — the workflow, pending
+  changes, and process history are resolved against the process cwd.
+  `--help`/`--version` (and the `help`/`version` subcommands), `lsp`, and
+  `visualize` skip this guard entirely (`visualize` still reads the `.gtdrc`
+  workflow, but needs no git state).
+- **Linked worktrees are independent.** N `git worktree` worktrees of one
+  repository (sharing a single `.git`) each run their own gtd process: state is
+  derived from that worktree's own HEAD, and the review checkout window's refs
+  live in git's per-worktree `refs/worktree/gtd/*` namespace, so a review
+  resting in one worktree neither blocks nor rewrites any other
+  ([STATES.md §11](../STATES.md#11-the-review-checkout-window)). This holds from
+  7.2 on; gtd ≤ 7.1 kept the window under the shared `refs/gtd/*` refs, where
+  the first worktree to open one clobbered every sibling's branch.

package/docs/configuration.md

@@ -449,9 +449,10 @@ 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/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.
+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>`)
 
@@ -588,6 +589,71 @@ done:
 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`/

package/docs/loop.md

@@ -34,6 +34,19 @@ capture for the human as its opening move (see below), so re-launching the loop
 is the only thing the human ever does — at a gate they edit and re-run, and the
 loop picks their change up.
 
+**A `"message"` rest is a real handoff, not a slow beat.** No driver signs off
+for the human: in the bundled workflow the loop runs the whole cycle unattended
+up to `await-review` and then STOPS there with the review checkout window open
+(the reviewable diff surfaced as uncommitted changes — see
+[STATES.md §11](../STATES.md#11-the-review-checkout-window)). Advancing takes a
+human edit to `.gtd/REVIEW.md`: ticking every box with **no** comment signs off
+into the squash finale, while any comment (a note, or a code edit of your own)
+is feedback that routes into another build + re-review round. Re-launching the
+loop after that edit picks the decision up. Until then the loop halts on every
+run — that is the contract, not a stall. A review nobody is going to finish is
+ended with [`gtd abandon`](cli.md#gtd-abandon---json), which drops the process's
+commits and keeps their content as uncommitted changes.
+
 ```bash
 gtd next --json   # ask who's up and what they should do
 ```

package/docs/upgrading.md

@@ -80,8 +80,14 @@ upgrading.
   existing review/feedback machinery unmodified — see
   [STATES.md §11](../STATES.md#11-the-review-checkout-window) and
   [CLI reference](cli.md#gtd-review-commitish---json). The current command
-  surface is `init` / `step` / `next` / `status` / `validate` / `mermaid` /
-  `review` / `lsp`.
+  surface is `init` / `step` / `next` / `status` / `validate` / `review` /
+  `lsp`.
+
+- **`gtd mermaid` → `gtd visualize`.** The static Mermaid emitter has been
+  replaced by `gtd visualize`, which serves an interactive diagram of the active
+  workflow (main flow, sub-machines, per-state details) on a local web server —
+  see [CLI reference](cli.md#gtd-visualize---portn---no-open---json). Both are
+  read-only views of the active workflow; nothing in the machine changes.
 
 - **`gtd format <file>`, and the bundled prettier with it.** gtd no longer
   formats anything on its own: a steering-file mode declares its own `format:`
@@ -153,6 +159,42 @@ loudly at load time rather than silently misinterpreting.
 or agent harness, upgrading the `gtd` binary also means re-copying that skill
 from this release.
 
+## 7.2: the review checkout window is now per worktree
+
+The review checkout window's two refs moved from the SHARED `refs/gtd/*`
+namespace to git's PER-WORKTREE `refs/worktree/*` one:
+
+| before (≤ 7.1)         | from 7.2                        |
+| ---------------------- | ------------------------------- |
+| `refs/gtd/review-head` | `refs/worktree/gtd/review-head` |
+| `refs/gtd/review-base` | `refs/worktree/gtd/review-base` |
+
+Nothing in a `.gtdrc` or a workflow definition references those names, so **no
+config change is needed**. What changes is behaviour in a repository checked out
+as several linked worktrees (`git worktree add`, one `.git` shared between
+them): each worktree now has its own window, so a review resting in one no
+longer "closes" from another — which, on the shared refs, mixed-reset that other
+worktree's branch onto the reviewing worktree's saved head and left every
+sibling refusing with "a process is already underway".
+
+A window an OLDER gtd left open across the upgrade still closes from the legacy
+refs, so an in-flight review in a single-worktree repo needs no attention. In a
+multi-worktree repo gtd cannot tell which worktree a shared ref belongs to, so
+it closes only when HEAD is contained in the saved head and otherwise refuses
+with the exact recovery commands — run them in the worktree that owns the
+window:
+
+```bash
+git reset --mixed refs/gtd/review-head
+git update-ref -d refs/gtd/review-head
+git update-ref -d refs/gtd/review-base
+```
+
+7.2 also adds [`gtd abandon`](cli.md#gtd-abandon---json), the supported way out
+of a process that will never be finished (it closes the window, then rewinds
+HEAD to the process's start parent, keeping everything the process produced as
+uncommitted changes) — no hand-editing of refs required.
+
 ## Prior breaking change: the v1 → v2 label grammar (historical)
 
 v2 replaced v1's undifferentiated turn labels with six labels carrying the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "7.0.0",
+  "version": "7.1.1",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/schema.json

@@ -36,6 +36,182 @@
             }
           }
         },
+        "submachines": {
+          "type": "object",
+          "description": "Optional reusable sub-machines, invoked by `use:` and expanded into concrete states at load time (see src/Submachines.ts).",
+          "additionalProperties": {
+            "type": "object",
+            "description": "A reusable, parameterized cluster of states, expanded at load time by each `use:` invocation into concrete states (see src/Submachines.ts). Purely a source-authoring convenience — the engine only ever sees the expanded states.",
+            "additionalProperties": false,
+            "required": ["states"],
+            "properties": {
+              "params": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Parameter names. A `$name` token used as a whole field value or `on`/`retry.otherwise` target is replaced by the invocation's `with:` binding."
+              },
+              "states": {
+                "type": "object",
+                "description": "The sub-machine's local states. `on`/`retry.otherwise` targets naming another local are rewritten via `as:`; a `$name` value is bound from `with:`.",
+                "minProperties": 1,
+                "additionalProperties": {
+                  "type": "object",
+                  "description": "One workflow state. Declare exactly one content kind (script/prompt/message/commit). A commit state is final: no actor, no on.",
+                  "additionalProperties": false,
+                  "properties": {
+                    "actor": {
+                      "type": "string",
+                      "description": "Who acts at this state. Required on every non-commit state; forbidden on a commit state."
+                    },
+                    "script": {
+                      "type": "string",
+                      "description": "Content kind: a shell script (Eta template). The loop driver executes it verbatim via bash, then steps this state's actor."
+                    },
+                    "prompt": {
+                      "type": "string",
+                      "description": "Content kind: an agent prompt (Eta template), emitted by `gtd next`."
+                    },
+                    "message": {
+                      "type": "string",
+                      "description": "Content kind: a human-facing message (Eta template), emitted by `gtd next`."
+                    },
+                    "commit": {
+                      "type": "string",
+                      "description": "Content kind: entering this state ends the process by squashing it into one commit with this message (Eta template). Final — no actor, no on."
+                    },
+                    "on": {
+                      "type": "object",
+                      "description": "Ordered map of change pattern -> target state. Patterns: \"C\" (clean tree) or \"<A|M|D|*> <glob>\" over the pending diff; first declared match wins. Every target must name a defined state, and every non-initial state must be reachable through these edges (or a retry.otherwise). A value is either the target state name (string) or a { to, describe } object whose describe is a human-readable sentence templates can surface as it.edges (e.g. in a human gate's message).",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string",
+                            "description": "The target state name."
+                          },
+                          {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "required": ["to"],
+                            "properties": {
+                              "to": {
+                                "type": "string",
+                                "description": "The target state name."
+                              },
+                              "describe": {
+                                "type": "string",
+                                "description": "Human-readable sentence describing where this change routes; surfaced verbatim (never Eta-rendered) to templates as it.edges[].describe."
+                              }
+                            }
+                          }
+                        ]
+                      }
+                    },
+                    "initial": {
+                      "type": "boolean",
+                      "description": "Exactly one state in the workflow must declare initial: true (and it must not be a commit state)."
+                    },
+                    "retry": {
+                      "type": "object",
+                      "description": "Redirect transitions INTO this state once it has been entered `max` times in the current process.",
+                      "additionalProperties": false,
+                      "required": ["max", "otherwise"],
+                      "properties": {
+                        "max": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "description": "Entries allowed this process before redirecting."
+                        },
+                        "otherwise": {
+                          "type": "string",
+                          "description": "Defined state to redirect to once over the cap."
+                        }
+                      }
+                    },
+                    "model": {
+                      "type": "string",
+                      "description": "Opaque harness hint passed through `gtd next --json`/`gtd status --json` (e.g. \"smart\"). Never interpreted by gtd. Forbidden on a commit state."
+                    },
+                    "memory": {
+                      "type": "string",
+                      "description": "Opaque memory-scope label passed through `gtd next --json`/`gtd status --json` (e.g. \"plan\"). A memory-aware driver retains an agent's memory across consecutive agent turns sharing this label and starts fresh when it changes. Never interpreted by gtd. Forbidden on a commit state."
+                    },
+                    "file": {
+                      "type": "string",
+                      "description": "The state's steering file: an Eta template naming the file a human/editor should look at while the machine rests here. Forbidden on a commit state."
+                    },
+                    "mode": {
+                      "type": "string",
+                      "description": "The steering file's format: the name of a built-in mode (qa/review, validated in-process by gtd) or of a `modes:` entry. gtd formats and validates the file with that mode before capturing a turn out of this state, and the LSP dispatches live diagnostics on the built-in names. Requires a sibling `file:`. Forbidden on a commit state."
+                    },
+                    "reviewWindow": {
+                      "type": "boolean",
+                      "description": "When true, gtd opens a review checkout window while the machine rests here — HEAD/index are rewound to the review base so the whole base..HEAD diff surfaces as uncommitted changes in the editor. Forbidden on a commit state."
+                    },
+                    "reviewBase": {
+                      "type": "boolean",
+                      "description": "Marks the state whose most-recent in-process commit anchors the review window's diff base; absent any, the base is the process start. Forbidden on a commit state."
+                    },
+                    "reviewEntry": {
+                      "type": "boolean",
+                      "description": "Marks the (at most one) state `gtd review <commitish>` enters to start a brand new process reviewing <commitish>..HEAD. Forbidden on a commit state and on the initial state."
+                    },
+                    "fixEntry": {
+                      "type": "boolean",
+                      "description": "Marks the (at most one) state `gtd fix` enters to start a brand new process that goes straight into repairing the current failing tests. Forbidden on a commit state and on the initial state."
+                    },
+                    "requireProgress": {
+                      "type": "boolean",
+                      "description": "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
+                    },
+                    "answerGate": {
+                      "type": "boolean",
+                      "description": "When true, a step at this state is refused unless every open question in its qa-mode `file:` is answered — exactly one checkbox ticked per question. Requires a `file:` and `mode: qa`. Forbidden on a commit state."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "use": {
+          "type": "array",
+          "description": "Sub-machine invocations. Each clones a `submachines:` entry into concrete states: `as:` renames its locals (identity when omitted), `with:` binds its `$param`s, `set:` adds extra per-instance state fields.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["submachine"],
+            "properties": {
+              "submachine": {
+                "type": "string",
+                "description": "Name of a declared sub-machine."
+              },
+              "name": {
+                "type": "string",
+                "description": "Optional label for this instance (inert to expansion; used by tooling like `gtd visualize` to name the group). Defaults to the sub-machine name."
+              },
+              "as": {
+                "type": "object",
+                "description": "Rename map: local state name -> concrete state name (identity when omitted).",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "with": {
+                "type": "object",
+                "description": "Bindings for the sub-machine's `$param`s."
+              },
+              "set": {
+                "type": "object",
+                "description": "Extra fields merged onto a renamed local state, keyed by local name.",
+                "additionalProperties": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        },
         "states": {
           "type": "object",
           "description": "The workflow's named states. At least one; exactly one with initial: true.",
@@ -148,6 +324,10 @@
               "requireProgress": {
                 "type": "boolean",
                 "description": "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
+              },
+              "answerGate": {
+                "type": "boolean",
+                "description": "When true, a step at this state is refused unless every open question in its qa-mode `file:` is answered — exactly one checkbox ticked per question. Requires a `file:` and `mode: qa`. Forbidden on a commit state."
               }
             }
           }