@pmelab/gtd 7.0.0 → 7.1.0

package/docs/cli.md

@@ -32,14 +32,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
@@ -394,46 +395,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 +430,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 +490,8 @@ 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).

package/docs/configuration.md

@@ -588,6 +588,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/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:`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "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."
               }
             }
           }