@pmelab/gtd 3.0.0 → 3.1.0

package/dist/gtd.bundle.mjs

@@ -189422,6 +189422,37 @@ const validateRetry = (name, state, names) => {
 	if (!Number.isInteger(state.retry.max) || state.retry.max < 0) errors.push(`state "${name}": retry.max must be a non-negative integer`);
 	return errors;
 };
+/**
+* Every state is reachable from the initial state by walking `on` targets and
+* `retry.otherwise` redirects (a redirect ENTERS its `otherwise` state exactly
+* like an `on` match enters its target — see `applyRetry` — so both are real
+* edges). Plain BFS; targets naming undefined states are skipped here (they
+* are `validateOnEdges`/`validateRetry` findings of their own). Only called
+* when `validateInitial` found no problem: with zero or several `initial`
+* states there is no well-defined start to walk from, and reporting every
+* state as unreachable would bury the real finding.
+*
+* An unreachable state is an ERROR, not a warning: a workflow is bound to a
+* project and edited as a project-wide change, so "kept on purpose for manual
+* entry via a hand-authored subject" is not a supported authoring pattern —
+* an unreachable state is a typo'd rename or a leftover, and silently-dead
+* config is exactly what load-time validation exists to catch.
+*/
+const validateReachability = (def, names) => {
+	const initial = names.find((name) => def.states[name].initial === true);
+	const visited = /* @__PURE__ */ new Set([initial]);
+	const queue = [initial];
+	while (queue.length > 0) {
+		const state = def.states[queue.shift()];
+		const targets = (state.on ?? []).map(([, target]) => target);
+		if (state.retry !== void 0) targets.push(state.retry.otherwise);
+		for (const target of targets) if (def.states[target] !== void 0 && !visited.has(target)) {
+			visited.add(target);
+			queue.push(target);
+		}
+	}
+	return names.filter((name) => !visited.has(name)).map((name) => `state "${name}" is unreachable from initial state "${initial}" (no "on" target or "retry.otherwise" leads to it)`);
+};
 /** All per-state rule checkers, run over one state. */
 const validateState = (def, name, names) => {
 	const state = def.states[name];
@@ -189449,12 +189480,20 @@ const validateState = (def, name, names) => {
 * never declared on a commit state; `file`, when present, is a non-empty
 * string and is never declared on a commit state; `mode`, when present, is
 * one of the closed vocabulary (`qa`/`review`), requires a sibling `file`,
-* and is never declared on a commit state.
+* and is never declared on a commit state; every state is reachable from the
+* initial state by walking `on` targets and `retry.otherwise` redirects
+* (checked only when the initial-state rule itself passed — see
+* `validateReachability`).
 */
 const validateDefinition = (def) => {
 	const names = Object.keys(def.states);
 	if (names.length === 0) return ["workflow must declare at least one state"];
-	return [...validateInitial(def, names), ...names.flatMap((name) => validateState(def, name, names))];
+	const initialErrors = validateInitial(def, names);
+	return [
+		...initialErrors,
+		...names.flatMap((name) => validateState(def, name, names)),
+		...initialErrors.length === 0 ? validateReachability(def, names) : []
+	];
 };
 //#endregion
 //#region src/PatternConfig.ts
@@ -189811,6 +189850,22 @@ var Cwd = class Cwd extends Tag("Cwd")() {
 * `./Edge.js`'s `resolveVars`). There are no other blessed config keys (see
 * `./Config.js`'s module docstring for why).
 *
+* Both keys decode as `Schema.Unknown`: the shape is validated structurally
+* by the workflow compiler (`src/PatternConfig.ts`), not by effect/schema —
+* the shape is deep and recursive, and the compiler's errors carry rule
+* coordinates a flat schema error cannot. The `jsonSchema` ANNOTATIONS below
+* exist for one consumer only: `scripts/generate-schema.ts`, which publishes
+* `schema.json` for editor-side autocompletion/validation
+* (yaml-language-server et al). They describe the same shape the compiler
+* enforces, minus the rules JSON Schema cannot express (exactly one content
+* kind per state, exactly one `initial: true` across the workflow, `on`/
+* `retry.otherwise` targets naming defined states, reachability) — the
+* compiler stays the source of truth; the annotation is the editor's first
+* net, never a second validator to keep behaviorally in sync. When the
+* compiler's accepted shape changes (a new state key, a new content kind),
+* update the annotation here alongside `src/PatternConfig.ts`'s
+* `KNOWN_STATE_KEYS`.
+*
 * Kept in its own module, separate from `./Config.js`, so `scripts/generate-
 * schema.ts` (run via `jiti`, a plain TS-via-Babel loader with no bundler-
 * style pluggable per-extension loaders) can import JUST the schema without
@@ -189819,9 +189874,100 @@ var Cwd = class Cwd extends Tag("Cwd")() {
 * loader, something `jiti` has no equivalent for and doesn't need here: the
 * schema shape never depends on the bundled default workflow's content.
 */
+/** The `vars:` shape (top-level AND inside `workflow:`): a flat name -> scalar map (`compileVarsMap` coerces every scalar to a string). */
+const varsJsonSchema = {
+	type: "object",
+	description: "Flat name -> scalar map merged into every template's it.vars. Scalars are coerced to strings.",
+	additionalProperties: { type: [
+		"string",
+		"number",
+		"boolean"
+	] }
+};
+/** The whole `workflow:` value — see `PatternConfig.ts`'s module docstring for the authoritative schema. */
+const workflowJsonSchema = {
+	type: "object",
+	description: "The whole machine definition: named states (plus the workflow's own vars: defaults). Compiled and validated by gtd at load time; content strings starting with ./ or ../ are file references inlined from the config file's directory.",
+	additionalProperties: false,
+	required: ["states"],
+	properties: {
+		vars: varsJsonSchema,
+		states: {
+			type: "object",
+			description: "The workflow's named states. At least one; exactly one with initial: true.",
+			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). `gtd run` 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).",
+						additionalProperties: { type: "string" }
+					},
+					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."
+					},
+					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",
+						enum: ["qa", "review"],
+						description: "The steering file's format, dispatched on by the LSP. Requires a sibling `file:`. Forbidden on a commit state."
+					}
+				}
+			}
+		}
+	}
+};
 const ConfigSchema = Struct({
-	workflow: optional(Unknown),
-	vars: optional(Unknown)
+	workflow: optional(Unknown.annotations({ jsonSchema: workflowJsonSchema })),
+	vars: optional(Unknown.annotations({ jsonSchema: varsJsonSchema }))
 });
 //#endregion
 //#region src/Config.ts
@@ -364489,6 +364635,76 @@ const startLspServer = () => gen(function* () {
 	});
 });
 //#endregion
+//#region src/Mermaid.ts
+/**
+* `gtd mermaid`: a pure emitter of the active workflow's SHAPE as Mermaid
+* `stateDiagram-v2` source — one node per state, the `[*] -->` initial-state
+* marker, one edge per declared `on` row (labeled with its raw pattern
+* string), `--> [*]` for every commit state (final, no outgoing edges), and
+* one `note right of` per rest naming its actor/content-kind/retry cap. No
+* git, no Effect, no template rendering: same purity discipline as
+* `PatternMachine.ts` — a plain function of an already-`validateDefinition`d
+* `WorkflowDefinition` (see `Config.ts`'s `toOperations`/`compileWorkflowConfig`
+* — every `WorkflowDefinition` this module ever sees has already been
+* validated, so an `on` target or `retry.otherwise` is trusted to name a
+* defined state rather than re-checked here).
+*/
+/**
+* Mermaid identifiers must avoid quotes/newlines inside a quoted label —
+* collapse both so the label stays on one line and the diagram stays
+* parseable even if a state name or `on` pattern happens to carry either.
+*/
+const escapeLabel = (text) => text.replace(/"/g, "'").replace(/\r?\n/g, " ");
+/**
+* A Mermaid-safe node id for one state name: every non-word character folds
+* to `_` (state names may carry hyphens — `todo-validating`,
+* `review-deciding` — which Mermaid's bare identifier grammar doesn't
+* guarantee), and a leading digit gets an `s_` prefix (Mermaid ids can't
+* start with one). The exact original name still reaches the diagram via
+* this alias's `state "<name>" as <alias>` declaration.
+*/
+const aliasFor = (name) => {
+	const folded = name.replace(/[^A-Za-z0-9_]/g, "_");
+	return /^[0-9]/.test(folded) ? `s_${folded}` : folded;
+};
+/** One rest's actor/content-kind/retry-cap summary, for a `note right of` line. */
+const stateNote = (state) => {
+	const parts = [state.actor, contentKindOf(state)].filter((p) => p !== void 0);
+	const retry = state.retry !== void 0 ? [`retry ${state.retry.max}→${state.retry.otherwise}`] : [];
+	return [...parts, ...retry].join(" · ");
+};
+/**
+* Render `def`'s shape as Mermaid `stateDiagram-v2` source. One
+* `state "<name>" as <alias>` declaration per state up front (so every
+* transition/note below can reference the safe alias while the rendered
+* diagram still shows the exact declared name), then the initial-state
+* marker, then one edge per `on` row (declaration order — same "first match
+* wins" order the engine itself evaluates), then `<alias> --> [*]` for every
+* commit state, then one actor/content-kind/retry note per rest.
+*/
+const renderMermaid = (def) => {
+	const names = Object.keys(def.states);
+	const alias = new Map(names.map((name) => [name, aliasFor(name)]));
+	const lines = ["stateDiagram-v2"];
+	for (const name of names) lines.push(`    state "${escapeLabel(name)}" as ${alias.get(name)}`);
+	lines.push(`    [*] --> ${alias.get(initialStateOf(def))}`);
+	for (const name of names) {
+		const state = def.states[name];
+		const from = alias.get(name);
+		if (isCommitState(state)) {
+			lines.push(`    ${from} --> [*]`);
+			continue;
+		}
+		for (const [pattern, target] of state.on ?? []) lines.push(`    ${from} --> ${alias.get(target)} : ${escapeLabel(pattern)}`);
+	}
+	for (const name of names) {
+		const state = def.states[name];
+		if (isCommitState(state)) continue;
+		lines.push(`    note right of ${alias.get(name)} : ${escapeLabel(stateNote(state))}`);
+	}
+	return lines.join("\n") + "\n";
+};
+//#endregion
 //#region src/program.ts
 const _require = createRequire(import.meta.url);
 const GTD_VERSION = _require("../package.json").version;
@@ -364504,6 +364720,8 @@ Commands:
                    actor (the built-in script driver)
   status           Print the resolved rest's state/actor and which declared
                    pattern (if any) each pending change matches (no mutation)
+  mermaid          Print the active workflow's shape as Mermaid
+                   stateDiagram-v2 source (no mutation)
   format <file>    Format a markdown file in place
   lsp              Start the LSP server for .gtd/ steering files (stdio)
 
@@ -364714,11 +364932,27 @@ const runStatusCommand = (argv, json, write) => gen(function* () {
 	if (json) writeStatusJson(write, rest, statusChanges, model, file);
 	else writeStatusPlain(write, rest, statusChanges, model, file);
 });
+/**
+* `gtd mermaid`: pure emitter of the active workflow's SHAPE (not the
+* resolved rest) as Mermaid `stateDiagram-v2` source — see `src/Mermaid.ts`.
+* Needs only `ConfigService` (no HEAD resolution, no rendering), but is
+* dispatched alongside `next`/`status` since it still depends on the active
+* `.gtdrc` — unlike `format`/`lsp`, which need neither git nor config — so it
+* goes through the same repository-root guard and auto-init. Rejects
+* `--json`: there is no structured shape to emit beyond the Mermaid source
+* itself.
+*/
+const runMermaidCommand = (argv, json, write) => gen(function* () {
+	if (json) return yield* fail$2(/* @__PURE__ */ new Error("gtd mermaid does not accept --json"));
+	yield* rejectExtraArgs("mermaid", argv);
+	write(renderMermaid((yield* ConfigService).workflow));
+});
 const KNOWN_SUBCOMMANDS = [
 	"step",
 	"next",
 	"run",
-	"status"
+	"status",
+	"mermaid"
 ];
 /**
 * `--version`/`-v` or `--help`/`-h`: short-circuits before any git or state
@@ -364768,6 +365002,7 @@ const dispatchKnownSubcommand = (sub, argv, json, write) => {
 		case "next": return runNextCommand(json, write);
 		case "run": return runRunCommand(argv, json, write);
 		case "status": return runStatusCommand(argv, json, write);
+		case "mermaid": return runMermaidCommand(argv, json, write);
 	}
 };
 /**

package/docs/cli.md

@@ -13,6 +13,8 @@ Commands:
                    actor (the built-in script driver)
   status           Print the resolved rest's state/actor and which declared
                    pattern (if any) each pending change matches (no mutation)
+  mermaid          Print the active workflow's shape as Mermaid
+                   stateDiagram-v2 source (no mutation)
   format <file>    Format a markdown file in place
   lsp              Start the LSP server for .gtd/ steering files (stdio)
 
@@ -175,6 +177,46 @@ never `null`, otherwise):
 
 `gtd status` takes no arguments — extra positional args are rejected.
 
+## `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 "grilling" as grilling
+    ...
+    [*] --> idle
+    idle --> grilling : * **
+    ...
+    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 `todo-validating` 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 format <file>`
 
 Formats a markdown file in place with a bundled prettier (`parser: "markdown"`,
@@ -249,7 +291,7 @@ 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`/`next`/`run`/
-  `status`) must run from the git repository root — the workflow, pending
-  changes, and process history are resolved against the process cwd.
+  `status`/`mermaid`) must run from the git repository root — the workflow,
+  pending changes, and process history are resolved against the process cwd.
   `--help`/`--version`, `format`, and `lsp` skip this guard entirely (and any
   git/`.gtdrc` dependency along with it).

package/docs/configuration.md

@@ -261,6 +261,21 @@ workflow config:
   - 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 `mode` vocabulary), 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

package/docs/design/state-machine-validation.md

@@ -0,0 +1,437 @@
+# Research: static validation of workflow definitions
+
+> Status: PARTIALLY IMPLEMENTED. Scope decision: a workflow is bound to a
+> project and edited as a project-wide change (never mid-process), so the
+> mid-flight/backward-compat concerns in §6 don't apply, and no warning channel
+> is needed — implemented checks are plain errors. Landed: the full `workflow:`
+> typing in `schema.json` (§6.1, via `jsonSchema` annotations in
+> `src/ConfigSchema.ts`) and the unreachable-state error (§3.1, as
+> `validateReachability` in `src/PatternMachine.ts` — invalid `on`/
+> `retry.otherwise` targets were already errors). Everything else in this
+> document is deliberately on hold.
+
+## 1. What is validated today (baseline)
+
+Two layers run at config-load time, both aggregate-all-findings-then-throw
+(`compileWorkflowConfig` merges its shape errors with `validateDefinition`'s
+findings into one error — a bad config fails loudly at load, never at step
+time):
+
+- **Config shape** (`src/PatternConfig.ts`): unknown top-level/state/retry keys,
+  wrong types, unreadable `./` file references, non-scalar `vars:` values.
+- **Definition rules** (`src/PatternMachine.ts` `validateDefinition`): at least
+  one state; exactly one non-commit `initial`; exactly one content kind per
+  state; commit states carry no `actor`/`on`/`model`/`file`/`mode`; non-commit
+  states carry an `actor`; every `on` pattern parses; every `on` target and
+  `retry.otherwise` names a defined state; `retry.max` is a non-negative
+  integer; `file`/`model` non-empty; `mode` ∈ {qa, review} and requires `file`.
+
+Every one of these checks is **local** — a rule over one state (or one field) at
+a time. Nothing today looks at the definition as a _graph_. The v2 design doc
+(`configurable-state-machine.md` §3.11) planned exactly that class of checks
+(totality, reachability, ambiguity, livelock bounds); the v3 rewrite shipped
+without them.
+
+## 2. The gap: definitions that validate clean but are broken
+
+Each of these passes today's validation:
+
+1. **Unreachable state** — defined, valid, but no `on` target or
+   `retry.otherwise` ever names it (typically a rename that missed the edges).
+   It silently never runs.
+2. **Dead-end state** — a non-commit state with no `on` map (or an empty one).
+   Once entered, every step is a no-op (clean) or refusal (dirty) forever; the
+   process can never leave.
+3. **Trap cycle** — a group of states that reach each other but from which no
+   terminal (a commit state, or re-entry into the initial state — the bundled
+   default's only "end") is reachable. The process runs but can never complete.
+4. **Unbounded agent loop (livelock)** — a cycle consisting only of agent/check
+   states with no `retry` cap on any member. The default's `fixing ↔ checking`
+   loop is safe only because `fixing` carries
+   `retry: {max: 3, otherwise: escalate}`; delete that key and the machine
+   validates clean but can ping-pong forever with no human in the loop.
+5. **Shadowed `on` row** — `on` is first-match-wins, so
+   `{"* **": a, "A .gtd/FORMAT.md": b}` never routes to `b`: the catch-all
+   subsumes the specific row. Dead rows are silent today.
+6. **`retry.otherwise` cycle / self-reference** — `applyRetry` terminates at
+   runtime via its `visited` guard, but the guard's "accept the repeated target
+   as final" behavior is almost certainly not what the author meant; the config
+   is accepted silently.
+7. **Pointless `retry`** — retry redirection applies when a state is entered _as
+   a transition target_; a `retry` on a state nothing targets never fires.
+8. **Template errors discovered at step time** — Eta syntax errors in
+   `prompt`/`script`/`message`/`commit`/`file` templates surface only when that
+   state is first rendered, contradicting the "fails at load, never at step
+   time" contract everything else honors.
+9. **The documented `vars` ↔ `on` desync** (`default.yaml`'s KNOWN LIMITATION) —
+   `on` patterns are literal strings while `file:` and content templates read
+   `it.vars.todoFile` etc.; repointing a var moves what templates read/write
+   without moving what patterns match.
+
+## 3. Algorithm survey
+
+The good news: a gtd workflow is a small, explicit, finite directed graph (the
+bundled default: 12 nodes, ~25 edges; a custom one is the same order of
+magnitude). Every algorithm below is textbook material and costs microseconds at
+this size — there is no need for a model checker, SAT solver, or symbolic
+anything. The edge set for all graph checks is `on` targets ∪ `retry.otherwise`
+targets.
+
+### 3.1 Reachability — accessible states (BFS/DFS from the initial state)
+
+The classic "useless states" removal from automata theory, first half: a state
+is _accessible_ iff some path from the start state reaches it. One BFS/DFS from
+the `initial` state over the edge set, O(V+E). Anything not visited is finding
+#1 (unreachable).
+
+**gtd nuance:** history is an attributed state trace, and `resolveState` accepts
+_any_ hand-authored `gtd(<actor>): <state>` subject naming a defined non-commit
+state and a declared actor — so an edge-unreachable state is still _enterable_
+by writing a commit by hand. That makes unreachability a **warning**, not a hard
+error: it is almost always a typo'd rename, but a deliberate "manual entry
+point" state is expressible and legal. (It also means an unreachable state's
+`actor` still widens the closed-world actor vocabulary — one more reason the
+finding deserves surfacing.)
+
+### 3.2 Co-reachability — can-complete (reverse BFS from terminals)
+
+The second half of the same textbook construction: a state is _co-accessible_
+iff a terminal is reachable from it; an automaton restricted to accessible ∩
+co-accessible states is called _trim_. Reverse the edges, BFS from the terminal
+set, flag unvisited states.
+
+**gtd's terminal set** is `commit` states ∪ the `initial` state — the bundled
+default has no commit state at all; its cycle "ends" by re-entering `idle` (the
+process-boundary rule in `computeProcessRun`). A reachable state that is not
+co-accessible is a trap (finding #3); a state with no outgoing edges at all
+(finding #2) is the degenerate case but deserves its own, more specific message.
+
+This is also exactly what **workflow-net soundness** (van der Aalst; the Woflan
+validator) checks in the Petri-net world: _option to complete_ (from every
+reachable marking, the end is reachable) plus _no dead transitions_. gtd's
+machine has no concurrency/tokens, so full soundness collapses to the two
+reachability passes above — the whole "soundness" property is two BFS runs here.
+
+### 3.3 Livelock heuristic — SCC analysis (Tarjan)
+
+Full progress proofs are out of reach (whether a pattern fires depends on what
+an agent writes), but the v2 plan's "livelock bounds" idea translates cleanly:
+compute strongly connected components (Tarjan, O(V+E)), and for each cyclic SCC
+check that it contains an _escape guarantee_:
+
+- a state whose `actor` is a human-ish rest point (the machine stops and waits —
+  a human can always steer out), **or**
+- a member with a `retry` cap whose `otherwise` leaves the SCC (bounded
+  redirection out).
+
+An SCC with neither — e.g. `building → checking → fixing → checking` with no cap
+— is a machine that can loop autonomously forever. Since "human-ish" is not
+knowable (actors are open-vocabulary strings; the engine deliberately blesses no
+names), the practical formulation is: **flag any cycle in which no member state
+either awaits a different actor than the cycle's dominant one or carries a retry
+cap escaping the cycle** — or, simpler and honest, make it a warning listing the
+cycle and what would bound it. This mirrors how linters handle undecidable
+properties: name the risk, don't pretend to prove it.
+
+### 3.4 Shadowed/dead `on` rows — pattern subsumption (match-arm usefulness)
+
+`on` is an ordered first-match-wins list — semantically identical to ML/Rust
+`match` arms, where compilers warn on unreachable arms using the _usefulness_
+algorithm (Maranget, "Warnings for pattern matching"). gtd's pattern grammar is
+far simpler than ML patterns, so full usefulness reduces to pairwise
+subsumption:
+
+- Row _j_ is dead iff some earlier row _i_ fires on every diff row _j_ fires on.
+  Matching is existential over the change set, so language inclusion is
+  sufficient: if row _i_'s (status, glob) language ⊇ row _j_'s, any change
+  matching _j_ also matches _i_, hence _i_ fires first.
+- `C` is disjoint from every diff row (clean vs. dirty), so it can only be
+  shadowed by an earlier duplicate `C`.
+- Status subsumption is trivial (`*` ⊇ `A`/`M`/`D`; equal otherwise). Glob
+  inclusion over the grammar {literal chars, `*`, `**`} is decidable — both
+  compile to regular languages (`globToRegExp` already builds the regexes), and
+  regular-language inclusion is decidable via product construction. In practice
+  a direct segment-wise structural check (the approach gitignore/ file-watcher
+  tooling uses) covers it without regex machinery, and even the cheap sufficient
+  subset catches the real-world cases:
+  - an exact duplicate pattern string earlier in the list (see also §4.1 — YAML
+    may reject or silently drop these before the compiler sees them),
+  - `* **` (or `* <glob>` with the identical glob) declared before a
+    more-specific row,
+  - same glob, earlier row's status `*` vs. later row's specific letter.
+
+This one is a hard **error** candidate: a dead row is never intentional, and the
+fix (reorder) is mechanical.
+
+Deliberately **not** worth adopting from the match-checking world:
+_exhaustiveness_. A dirty tree matching no row is a refusal **by design**
+(AGENTS.md: "something happened that nothing recognizes" is a signal distinct
+from a no-op), and a clean step with no `C` row is the documented default no-op.
+The event space is intentionally non-total; a totality lint would fight the
+semantics.
+
+### 3.5 Retry-chain analysis — cycle detection on a functional graph
+
+`retry.otherwise` edges form a functional graph (≤1 outgoing edge per state), so
+cycle detection is a trivial colored DFS (or Floyd's, but at this size DFS with
+a visited set is clearer — `applyRetry` already contains the runtime version of
+it). Findings: `otherwise` chains that cycle (error — the runtime guard's
+"accept the repeated target" fallback is a documented we-must-terminate
+behavior, not a meaning), `otherwise: <self>` (degenerate case of the same), and
+a `retry` on a state that no `on` edge targets (warning — it can never fire, per
+`applyRetry`'s entry-as-target semantics).
+
+### 3.6 Template validation — compile at load time
+
+Eta exposes compilation separately from rendering: `compile()` every
+`prompt`/`script`/`message`/`commit`/`file` string at load and report syntax
+errors as load errors, closing gap #8 without executing anything impure
+(rendering stays an edge concern; compiling is pure).
+
+One step further, the **undefined-variable lint**: scan template source for
+`it.vars.<name>` references and compare against the merged
+workflow-`vars:`/rc-`vars:` keys. Because a third layer (`GTD_VAR_*` env vars)
+can legitimately supply a name at run time, an unknown name is a **warning**,
+not an error. (A full "render with a tracking proxy and record misses" approach
+also works but executes template code at load — scanning the source is safer and
+catches the common typo just as well.)
+
+### 3.7 Domain cross-checks (gtd-specific lints)
+
+Not from the literature — from this codebase's own documented failure modes:
+
+- **`file:` ↔ `on` consistency** (gap #9): render each state's `file:` template
+  with the workflow's _declared default_ vars (pure — the defaults are right
+  there in the definition) and warn when the rendered path is matched by none of
+  the workflow's `on` globs. This turns `default.yaml`'s KNOWN LIMITATION
+  comment into a machine-checked finding whenever a var repoint desyncs
+  templates from patterns. The same check re-run at `gtd status` time with the
+  _actual_ merged vars (env layer included) closes the runtime half of the gap.
+- **Actor typo proximity**: the actor vocabulary is open by design, so `agnet`
+  is a legal actor — but a state awaiting it will never be stepped by the loop
+  driving `agent`. A Levenshtein "did you mean" warning when one declared actor
+  is within edit distance 1 of another (a pattern lifted from CLI arg parsers
+  and `git`'s command suggestions). Warning-only; false positives are possible
+  (`qa1`/`qa2`), so never an error.
+
+### 3.8 Dynamic validation — model-based testing (complement, not substitute)
+
+Since `step` is a pure function, the graph can be _executed_ exhaustively in
+tests: for every state and every `on` row, synthesize a minimal diff that the
+row's pattern matches (invert the glob: replace `*`/`**` with a literal segment)
+and assert `step` routes there — i.e., every declared edge is exercisable. This
+is the state-machine-testing pattern XState ships as `@xstate/graph`
+(`getShortestPaths`/`getSimplePaths` for path coverage) and what the
+model-based-testing literature calls transition coverage. It overlaps §3.4 (a
+shadowed row shows up as an unexercisable edge) but from the behavioral side,
+and it doubles as a regression harness for the pattern grammar itself. Fits
+naturally as a property test over `defaultWorkflowDefinition` rather than a
+load-time check.
+
+## 4. Patterns from comparable systems
+
+- **Automata theory** — _trim_ construction (accessible ∩ co-accessible),
+  §3.1/§3.2. The canonical "early problem detection" for FSMs.
+- **Workflow nets** — soundness (option to complete, no dead transitions);
+  degenerates to the same two BFS passes for token-free graphs.
+- **SCXML / W3C statecharts** — conformance validation is exactly this flavor:
+  every `target` IDREF resolves, `initial` names a real child, etc. gtd already
+  has the local half; the graph half is what's missing.
+- **XState** — beyond TS-level typegen, its ecosystem does reachability via path
+  enumeration (`@xstate/graph`) and visual inspection (Stately inspector) rather
+  than a lint pass — an argument for also shipping a human-readable graph dump
+  (see §5, `gtd lint`).
+- **ML/Rust match checking** — usefulness/unreachable-arm warnings, §3.4; also
+  the precedent for making dead-arm a _warning_ in some compilers and an _error_
+  in none... but gtd's rows are config, not code paths, and a dead row means a
+  whole state may be unreachable — error is defensible.
+- **Model checking (CTL/LTL)** — names the property taxonomy worth keeping:
+  today's checks are all _safety_ ("nothing malformed"); §3.2/§3.3 add the cheap
+  _liveness_ half ("something good stays reachable"). At 12 nodes,
+  `AG EF terminal` is just reverse-BFS — no checker needed.
+- **Linter architecture (ESLint et al.)** — severity tiers (error/warning),
+  collect-everything-then-report (gtd already does this for errors), stable
+  finding identifiers, and machine-readable output. The missing piece in gtd is
+  a **warning channel**: `compileWorkflowConfig` can only throw-or-pass, so
+  warning-tier findings (§3.1's manual-entry nuance, §3.3's heuristic, §3.6's
+  env-supplied vars, §3.7) currently have nowhere to go.
+
+## 5. Recommendation
+
+Tier the findings and keep every new check a pure function over
+`WorkflowDefinition` (they need nothing but the definition — they belong in
+`PatternMachine.ts` next to `validateDefinition`, except the Eta compile check,
+which imports Eta and belongs in `PatternTemplates.ts`):
+
+**Errors** (extend `validateDefinition`'s existing thrown aggregate; all
+unambiguous, mechanical fixes):
+
+1. Non-commit state with no `on` rows (dead end, §3.2's degenerate case).
+2. Reachable state from which no terminal (commit state or initial) is reachable
+   (trap, §3.2).
+3. `on` row strictly subsumed by an earlier row (§3.4).
+4. `retry.otherwise` self-reference or cycle (§3.5).
+5. Eta template that does not compile (§3.6).
+
+**Warnings** (requires adding a `{ severity, message }` shape and a channel —
+print to stderr at load and/or surface under `gtd status`; a `gtd lint`
+subcommand that prints all findings plus the state graph would follow the
+XState-inspector precedent and cost little):
+
+6. State unreachable via edges from `initial` (§3.1 — legal via hand-authored
+   subjects, almost always a typo).
+7. Autonomous cycle with no retry-capped escape (§3.3 heuristic).
+8. `retry` on a state no edge targets (§3.5).
+9. `it.vars.<name>` reference with no declared default (§3.6 — env layer may
+   supply it).
+10. `file:` rendering (with declared-default vars) to a path no `on` glob
+    matches (§3.7).
+11. Declared actor within edit distance 1 of another (§3.7).
+
+**Test-side** (not load-time): transition-coverage property test over the
+bundled default — synthesize a matching diff per `on` row, assert `step` takes
+the edge (§3.8).
+
+Sizing check: all graph passes are O(V+E) (two BFS + one Tarjan), subsumption is
+O(rows² per state) over a trivial grammar, and template compilation is the only
+cost that scales with content size. On workflows of tens of states this is
+sub-millisecond — safe to run on every invocation, exactly like today's
+`validateDefinition`.
+
+### Interactions to respect
+
+- **Severity of unreachability** hinges on `resolveState`'s hand-authored
+  subject entry (§3.1) — do not promote finding 6 to an error without also
+  deciding that manual-entry states are unsupported.
+- **The bundled default must stay finding-free** — findings 7 and 10 are
+  calibrated against it (`fixing`'s cap bounds the check loop; the literal
+  `.gtd/...` patterns match the declared default vars). Any new check must be
+  validated against `default.yaml` and `docs/examples/advanced-workflow.md`
+  before landing.
+- **Warning channel is the only architectural change** — everything else slots
+  into the existing collect-and-merge flow in `compileWorkflowConfig`.
+
+## 6. Reframe: safeguards for USER-authored machines
+
+§1–§5 read as "validate the definition harder." The actual product goal is
+narrower and different: the bundled default is already covered by e2e; what
+needs protecting is a **user hand-writing a `workflow:` key in `.gtdrc`** — and
+that shifts the design in three ways:
+
+1. **Static analysis is structurally insufficient.** Whether an `on` pattern
+   ever fires depends on what an agent writes into the tree at run time. No
+   load-time check can prove a user's machine makes progress — it can only catch
+   the mechanically-dead shapes (§2's findings 1–8). The worst user-facing
+   failures — an agent↔check loop burning tokens all night, a process resting in
+   a state whose patterns never match what its own prompt asks the agent to
+   produce — need **runtime bounds**, not better proofs.
+2. **Severity must be recalibrated for other people's configs.** A new hard
+   error is a breaking change: a config that ran yesterday must not brick the
+   repo after `npm update`, _especially_ mid-process. Checks that are
+   "error-worthy" for a definition we author (§5's shadowed-row, trap-state)
+   default to **warnings** for user configs; hard errors stay reserved for
+   definitions that cannot execute at all (today's structural rules, plus
+   templates that don't compile).
+3. **A broken config must never take reporting down with it.** Today
+   `compileWorkflowConfig` throws, and everything — including `gtd status` —
+   dies with it. For a user mid-flight that's the difference between "gtd tells
+   me what's wrong" and "gtd won't even tell me where I am."
+
+The safeguards form four layers, ordered by when they catch the problem:
+
+### 6.1 Authoring time — before the machine ever runs
+
+- **A real JSON Schema.** `schema.json` is generated from `ConfigSchema.ts`,
+  where `workflow`/`vars` are `Schema.Unknown` — so the published schema says
+  `"title": "unknown"` and editors validate NOTHING about the one key users
+  hand-write. Hand-authoring the workflow shape into the schema (states map,
+  actor, the four content kinds, `on` as string→string, `retry`
+  `{max, otherwise}`, `model`/`file`/`mode`) gives every yaml-language-server
+  editor squiggles and autocomplete for free, with zero gtd code. The compiler
+  stays the source of truth (the schema can't express "exactly one content kind"
+  or cross-state rules); the schema is the fast first net, not a replacement.
+  Cheapest, highest-leverage single item in this document.
+- **`gtd lint` (a.k.a. "check my machine before I trust it").** Compile the
+  config, run every §5 check, print ALL findings (errors + warnings) plus a
+  human-readable dump of the graph — states, actors, edges, retry caps, and the
+  reachability/terminal classification per state — so an author can _see_ the
+  machine they wrote (mermaid `stateDiagram-v2` output fits: renderable in any
+  markdown viewer, no new dependency to emit text). Also dry-compiles every Eta
+  template. This is where warnings can be exhaustive and loud, because the user
+  explicitly asked.
+
+### 6.2 Load time — every invocation, quiet by default
+
+- **The §5 checks with user-config severities**: structural rules and
+  template-compile failures stay throwing errors; all graph findings
+  (unreachable, trap, shadowed row, retry cycle, autonomous cycle) surface as
+  stderr warnings — one line each, prefixed (`gtd: workflow warning: ...`),
+  never fatal. Errors keep the current all-findings-in-one-throw behavior.
+- **Degrade reporting gracefully**: `gtd status` should still answer with the
+  findings when the config is broken (resolve HEAD against nothing, print the
+  compile errors as the status) rather than crashing with a stack trace.
+  `step`/`run`/`next` keep refusing — acting on a broken machine is worse than
+  stopping — but the _reporting_ path must survive any config.
+
+### 6.3 Run time — the bounds static analysis cannot provide
+
+These are the actual safeguards, in the circuit-breaker sense. All three are
+pure functions of data the engine already has (`processTrace`, the pending diff,
+the definition) — they fit `PatternMachine.step`'s purity discipline.
+
+- **A per-process autonomous-turn budget.** The v2 plan's "chain-depth limit"
+  (§3.11: "bound it and hard-error past, say, 32 hops"), reborn for v3: count
+  process-trace entries into states whose actor differs from the workflow's
+  human-facing rest points — concretely, entries since the last turn authored by
+  a DIFFERENT actor than the loop's autonomous pair, or simplest and honest:
+  total trace length. Past a cap (workflow-overridable via a reserved-ish var or
+  top-level config key, default generous — e.g. 50), `step` refuses with a new
+  refusal reason (`"budget"`) naming the count and how to raise the cap. This is
+  the one safeguard that holds NO MATTER WHAT the user's graph looks like — the
+  livelock heuristic (§3.3) can then stay a soft warning without leaving a hole.
+- **Stall detection in the engine, not the skill.** `skills/loop/SKILL.md`
+  currently tells the driver, in prose, to stop when the same state+content
+  repeats with no new commits. Promote the signal: `gtd next --json` (and
+  `status --json`) can report `"revisits": <n>` — how many times the current
+  state already appears in the process trace. Any driver (not just one that read
+  the skill carefully) can then apply its own stop rule; the skill's prose
+  heuristic becomes one consumer of a first-class field. No behavior change in
+  the engine's own decisions.
+- **Self-explaining refusals.** A no-match refusal already lists the state's
+  declared patterns; for a user debugging their own machine, also list the
+  pending changes that failed to match (status + path, first N). "Your tree has
+  `M src/x.ts` but this state only matches `A .gtd/FORMAT.md`" turns the most
+  common custom-workflow dead end from a mystery into a diff-vs-pattern
+  diagnosis the user can act on immediately.
+
+### 6.4 Recovery — no config may trap the repository
+
+Already true, worth asserting and documenting as a guarantee: the machine's
+whole state is HEAD's commit subject, so a hand-authored commit
+(`git commit --allow-empty -m "gtd(human): <state>"` for any defined non-commit
+state, or any non-gtd subject to fall back to the initial state) exits ANY state
+a broken config strands a process in. A user's workflow can waste turns; it
+cannot brick a repo. An e2e scenario pinning this (hand-commit out of an
+intentionally-trapped custom workflow) makes the guarantee load-bearing instead
+of incidental — and it is the reason every graph finding in §6.2 can afford to
+be a warning.
+
+### What deliberately stays out
+
+- No sandboxing or vetting of `script:` content — the workflow author is
+  trusted; scripts already run verbatim by design (`gtd run`).
+- No engine interpretation of actor names for the budget/livelock rules beyond
+  counting — the actor vocabulary stays unblessed.
+- No auto-repair ("we removed your unreachable state") — findings report; the
+  user decides.
+
+### Revised priority (user-safeguard lens)
+
+1. JSON Schema for the `workflow:` shape (§6.1) — editor-time, zero engine code.
+2. Warning channel + graceful `gtd status` degradation (§6.2) — the
+   architectural enabler.
+3. Autonomous-turn budget refusal (§6.3) — the unconditional backstop.
+4. Graph warnings from §5, demoted to warning severity (§6.2).
+5. Refusal diagnostics + `revisits` in `--json` (§6.3).
+6. `gtd lint` with graph dump (§6.1) — subsumes nothing above, packages all of
+   it for the authoring moment.

package/package.json

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

@@ -4,12 +4,103 @@
   "required": [],
   "properties": {
     "workflow": {
-      "$id": "/schemas/unknown",
-      "title": "unknown"
+      "type": "object",
+      "description": "The whole machine definition: named states (plus the workflow's own vars: defaults). Compiled and validated by gtd at load time; content strings starting with ./ or ../ are file references inlined from the config file's directory.",
+      "additionalProperties": false,
+      "required": ["states"],
+      "properties": {
+        "vars": {
+          "type": "object",
+          "description": "Flat name -> scalar map merged into every template's it.vars. Scalars are coerced to strings.",
+          "additionalProperties": {
+            "type": ["string", "number", "boolean"]
+          }
+        },
+        "states": {
+          "type": "object",
+          "description": "The workflow's named states. At least one; exactly one with initial: true.",
+          "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). `gtd run` 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).",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "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."
+              },
+              "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",
+                "enum": ["qa", "review"],
+                "description": "The steering file's format, dispatched on by the LSP. Requires a sibling `file:`. Forbidden on a commit state."
+              }
+            }
+          }
+        }
+      }
     },
     "vars": {
-      "$id": "/schemas/unknown",
-      "title": "unknown"
+      "type": "object",
+      "description": "Flat name -> scalar map merged into every template's it.vars. Scalars are coerced to strings.",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean"]
+      }
+    },
+    "$schema": {
+      "type": "string",
+      "description": "Editor-only pointer at this schema. Stripped by gtd before validation."
     }
   },
   "additionalProperties": false