@pmelab/gtd 3.0.0 → 3.2.0

package/dist/gtd.bundle.mjs

@@ -189117,6 +189117,10 @@ const contentKindOf = (state) => {
 };
 /** True when a state is a commit (final, squash) state. */
 const isCommitState = (state) => state.commit !== void 0;
+/** True when a rest at `state` should open the review checkout window (see `StateDef.reviewWindow`). Safe for an unknown state name (returns `false`). */
+const isReviewWindowState = (def, state) => def.states[state]?.reviewWindow === true;
+/** True when `state` anchors the review window's diff base (see `StateDef.reviewBase`). Safe for an unknown state name (returns `false`). */
+const isReviewBaseState = (def, state) => def.states[state]?.reviewBase === true;
 /**
 * `gtd(<actor>): <state>` — the subject a step commit carries. Per decision
 * 2, `<actor>` is WHO AUTHORED THE STEP (the invoker), and `<state>` is the
@@ -189405,6 +189409,19 @@ const validateMode = (name, state) => {
 	if (isCommitState(state)) errors.push(`state "${name}": a commit state cannot declare "mode"`);
 	return errors;
 };
+/**
+* `reviewWindow`/`reviewBase`, when present, are booleans (the compiler
+* enforces the type) — forbidden on a commit state, same rule family as
+* `model`/`file`/`mode`: a commit state is never at rest, so no window ever
+* opens or anchors there.
+*/
+const validateReviewWindow = (name, state) => {
+	if (!isCommitState(state)) return [];
+	const errors = [];
+	if (state.reviewWindow !== void 0) errors.push(`state "${name}": a commit state cannot declare "reviewWindow"`);
+	if (state.reviewBase !== void 0) errors.push(`state "${name}": a commit state cannot declare "reviewBase"`);
+	return errors;
+};
 /** Every `on` row parses, and its target names a defined state. */
 const validateOnEdges = (name, state, names) => {
 	const errors = [];
@@ -189422,6 +189439,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];
@@ -189432,7 +189480,8 @@ const validateState = (def, name, names) => {
 		...validateRetry(name, state, names),
 		...validateModel(name, state),
 		...validateFile(name, state),
-		...validateMode(name, state)
+		...validateMode(name, state),
+		...validateReviewWindow(name, state)
 	];
 };
 /**
@@ -189449,12 +189498,21 @@ 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; `reviewWindow`/`reviewBase`, when
+* present, are 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
@@ -189578,7 +189636,9 @@ const KNOWN_STATE_KEYS = /* @__PURE__ */ new Set([
 	"retry",
 	"model",
 	"file",
-	"mode"
+	"mode",
+	"reviewWindow",
+	"reviewBase"
 ]);
 const KNOWN_TOP_KEYS = /* @__PURE__ */ new Set(["vars", "states"]);
 const formatErrors = (errors) => `workflow config:\n${errors.map((e) => `  - ${e}`).join("\n")}`;
@@ -189691,13 +189751,21 @@ const compileMode = (raw, name, errors) => {
 	return raw.mode;
 };
 /** The `initial` field: `true` only when the raw value is the literal boolean `true`. */
-const compileInitial = (raw, name, errors) => {
-	if (raw.initial === void 0) return void 0;
-	if (raw.initial !== true && raw.initial !== false) {
-		errors.push(`state "${name}": "initial" must be a boolean`);
+const compileInitial = (raw, name, errors) => compileBooleanFlag(raw, "initial", name, errors);
+/**
+* A boolean state flag (`initial`/`reviewWindow`/`reviewBase`): `true` only
+* when the raw value is the literal `true`; a non-boolean is a config error;
+* `false` (or absent) compiles away to `undefined` so it never lands in the
+* `StateDef` — `false` and "unset" mean the same thing for every such flag.
+*/
+const compileBooleanFlag = (raw, key, name, errors) => {
+	const value = raw[key];
+	if (value === void 0) return void 0;
+	if (value !== true && value !== false) {
+		errors.push(`state "${name}": "${key}" must be a boolean`);
 		return;
 	}
-	return raw.initial === true ? true : void 0;
+	return value === true ? true : void 0;
 };
 const assembleContentFields = (content) => ({
 	...content.script !== void 0 ? { script: content.script } : {},
@@ -189721,7 +189789,9 @@ const assembleStateDef = (parts) => ({
 		retry: parts.retry,
 		model: parts.model,
 		file: parts.file,
-		mode: parts.mode
+		mode: parts.mode,
+		reviewWindow: parts.reviewWindow,
+		reviewBase: parts.reviewBase
 	}),
 	...assembleContentFields(parts.content)
 });
@@ -189741,7 +189811,9 @@ const compileState = (name, raw, configDir, errors) => {
 		retry: compileRetry(raw.retry, name, errors),
 		model: compileModel(raw, name, errors),
 		file: compileFile(raw, name, errors),
-		mode: compileMode(raw, name, errors)
+		mode: compileMode(raw, name, errors),
+		reviewWindow: compileBooleanFlag(raw, "reviewWindow", name, errors),
+		reviewBase: compileBooleanFlag(raw, "reviewBase", name, errors)
 	});
 };
 /**
@@ -189791,7 +189863,7 @@ const compileWorkflowConfig = (raw, configDir) => {
 * default.yaml's content values start with `./`/`../`, so
 * `compileWorkflowConfig` never resolves a file reference against it.
 */
-const compiled = compileWorkflowConfig((0, import_dist$1.parse)("# The bundled default gtd workflow (v3 \"pattern machine\" — see\n# docs/design/pattern-machine-plan.md, and\n# docs/design/steering-file-loops.md for the two validation loops below).\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/default.ts does the compiling).\n#\n# Every content string below is INLINE (no `./`-relative file references):\n# the bundled default ships inside a single-file build\n# (`dist/gtd.bundle.mjs`), so its content must already be resolved at BUILD\n# time rather than read from disk at RUNTIME — the same reason\n# `src/prompts/*.md` are imported through tsdown's `.md`-as-text loader\n# instead of read via `fs` at runtime. `default.yaml` itself is imported the\n# same way (tsdown/vitest both treat `.yaml` as text — see\n# tsdown.config.ts / tests/vitest.rawMd.ts), so this file never needs a\n# sibling prompts/ directory to exist on disk once installed.\n#\n# States, in cycle order — 12 states, no squash:\n#   idle (initial, human, message)\n#     -> grilling (agent, prompt): reads .gtd/TODO.md's sketch (or a prior\n#     lap's feedback), explores the codebase, and develops it into a concrete\n#     implementation plan, stating any open question it can't settle itself\n#     under a `## Open Questions` heading (see \"Loop 1\" below) rather than\n#     guessing silently.\n#   grilling -> todo-validating (check, script): mechanics-only parser port\n#     of the open-questions format (see src/OpenQuestions.ts's module doc for\n#     the executable spec this is a bash rendition of). Malformed ->\n#     .gtd/FORMAT.md -> back to grilling; valid -> grilling-answer.\n#   todo-validating -> grilling-answer (human, message): tick off suggested\n#     defaults by replacing them with `Answer:` lines; a clean step accepts\n#     every remaining default -> building; any edit loops back to grilling.\n#   grilling-answer -> building (agent, prompt): implements the plan in\n#     .gtd/TODO.md directly (no task decomposition, no per-task queue) and\n#     deletes .gtd/TODO.md once the work is complete and verified.\n#   building -> checking (check, script): runs the test command inline;\n#     A/M .gtd/FEEDBACK.md -> fixing (capped, redirects to escalate); D\n#     .gtd/FEEDBACK.md (a green run that just cleaned up prior feedback) or C\n#     (green, nothing to clean) -> reviewing.\n#   fixing (agent, prompt) <-> checking\n#   escalate (human, message): manual intervention, then back to checking\n#   checking (green) -> reviewing (agent, prompt): writes .gtd/REVIEW.md in\n#     the checkbox review format (see \"Loop 2\" below), grouping the cycle's\n#     full diff into reviewable chunks.\n#   reviewing -> review-validating (check, script): mechanics-only parser\n#     port of the review format (see src/ReviewDoc.ts's module doc for the\n#     executable spec). Malformed -> .gtd/FORMAT.md -> back to reviewing;\n#     valid -> await-review.\n#   review-validating -> await-review (human, message): tick a pointer's `- [\n#     ]` to `- [x]` to approve that item; deleting .gtd/REVIEW.md outright is\n#     the power-user approve-everything shortcut; anything else pending\n#     (code edits with REVIEW.md untouched) is feedback straight to grilling.\n#   await-review -> review-deciding (check, script), entered by any `M\n#     .gtd/REVIEW.md` step: if no unticked `- [ ]` pointer remains, the cycle\n#     is approved (rm .gtd/REVIEW.md -> idle); otherwise the still-unticked\n#     pointers (with their notes) are extracted into a fresh .gtd/TODO.md and\n#     .gtd/REVIEW.md is removed (-> grilling, feedback lap).\n#\n# The cycle ends at human approval, resting back at idle — there is no\n# squash state. The cycle's commits stay in history; whether/how to squash\n# them (amend, interactive rebase, a PR's squash-merge) is entirely the\n# human's business once they're done reviewing — gtd makes no assumption.\n# That squash-flavored finale (a `squashing` prompt state + a `done` commit\n# state) still exists as an ENGINE capability (see STATES.md §8) and is kept\n# as part of the fuller machine at docs/examples/advanced-workflow.md.\n#\n# A `gtd(<actor>): idle` commit — entering the workflow's own initial state —\n# is therefore a PROCESS BOUNDARY (see `computeProcessRun` in src/Edge.ts):\n# the next cycle's `retry` counts, `startCommit`, and diffs never reach back\n# across an approved cycle's own idle-entering commit.\n#\n# HYGIENE INVARIANT (asserted in e2e — see default-workflow.feature): an\n# approved cycle leaves `.gtd/` empty. FEEDBACK.md is cleaned up by a green\n# `checking` run; FORMAT.md by a valid validator run (either loop); REVIEW.md\n# by the review-deciding approval branch; TODO.md by `building`.\n#\n# Loop 1 — TODO.md open questions (src/OpenQuestions.ts is this format's\n# EXECUTABLE SPEC — its unit tests are the format's spec tests; the\n# `todo-validating`/`review-validating` bash scripts below are a pragmatic\n# grep/awk PORT of the exact same rules, not a full markdown parser. Keep\n# both in sync by hand — there is no shared code path between the two\n# implementations, by design: the engine stays git/filesystem/Effect-free,\n# and the LSP's parsers stay dependency-free).\n#\n# Loop 2 — REVIEW.md checkboxes: same dual-implementation contract, this time\n# against src/ReviewDoc.ts.\n#\n# `grilling` and `reviewing` both declare `model: smart` — an opaque harness\n# hint (see the comment at `grilling` below) for their heavier one-shot\n# planning/reviewing turns. Every other state is unset (harness default).\n#\n# `vars.testCommand` is this workflow's own declared default for `checking`'s\n# script (see it.vars in PatternTemplates.ts) — override it per-repo with a\n# top-level `.gtdrc` `vars: { testCommand: ... }` key, or per-invocation with\n# a `GTD_VAR_testCommand` environment variable (highest precedence).\n#\n# `vars.todoFile`/`reviewFile`/`feedbackFile` are this workflow's ONE source\n# of truth for the three steering-file paths every prompt/script below reads\n# or writes — each appears in templates as `<%~ it.vars.todoFile %>` etc\n# (see docs/design/state-file-association.md §2). Every state that rests on\n# one of these files also declares a `file:`/`mode:` pair (see STATES.md's\n# property table) so `gtd status`/`gtd next --json` and the LSP (`gtd lsp`)\n# know which file a human/editor should look at, and in what format\n# (`qa` for TODO.md's open-questions format, `review` for REVIEW.md's\n# checkbox format) — `fixing`/`escalate` declare `file:` alone (FEEDBACK.md\n# is plain text, no LSP format). KNOWN LIMITATION: `on` pattern keys below are\n# NOT Eta templates — they keep the LITERAL `.gtd/...` paths matching these\n# vars' DEFAULT values. Repointing `todoFile`/`reviewFile`/`feedbackFile` via\n# `.gtdrc`'s top-level `vars:` or a `GTD_VAR_` override changes what `file:`\n# renders to (and what a template reads/writes) WITHOUT changing what the\n# `on` patterns match against — desyncing the machine. See\n# docs/configuration.md's `file:`/`mode:` section for the full caveat.\n#\n# A fuller machine — two-phase Q&A planning, an architecture phase, task\n# decomposition, a deterministic per-task builder loop, agent-prepared\n# review, and the squash finale (`squashing` + `done`) — is preserved as a\n# copy-paste `.gtdrc` example at docs/examples/advanced-workflow.md.\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  reviewFile: .gtd/REVIEW.md\n  feedbackFile: .gtd/FEEDBACK.md\n\nstates:\n  idle:\n    actor: human\n    initial: true\n    message: |\n      No active gtd cycle.\n\n      To start one: write `.gtd/TODO.md` with a short sketch of what you want\n      built — a few sentences is enough — then run `gtd step human`.\n    on:\n      \"* **\": grilling\n\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # `model` is an opaque harness hint — gtd never interprets this string, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so the\n    # driving loop can map it onto whatever models its agent harness\n    # provides. \"smart\" here just names the harness-chosen tier for the\n    # heavier planning turn; states without a `model` use the harness's\n    # default.\n    model: smart\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.todoFile %>`, which this prompt tells you to develop. Never\n      touch `.gtd/FORMAT.md` yourself if it exists — a validator writes it,\n      and only the validator removes it once you've fixed the underlying\n      problem.\n\n      If `.gtd/FORMAT.md` exists, it holds format findings from your last\n      draft of `<%= it.vars.todoFile %>` — fix those findings first, then\n      continue below.\n\n      `<%= it.vars.todoFile %>` holds a short sketch of what to build (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete implementation plan.\n\n      For every question you cannot settle yourself, add it under a\n      `## Open Questions` heading, one `### <question>` sub-heading each,\n      whose body's FIRST non-blank line is exactly\n      `Suggested default: <your answer>` — the human can accept it as-is or\n      override it. Omit the section entirely once there are no open\n      questions. If `<%= it.vars.todoFile %>` already carries\n      `## Open Questions` entries from a previous lap, fold any\n      `Answer: <text>` line into the plan; every remaining entry's body must\n      still start with either `Suggested default: ...` or `Answer: ...` —\n      never anything else.\n\n      Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n      not commit, and do not run `gtd step agent` yourself; the harness does\n      that.\n    on:\n      \"* **\": todo-validating\n\n  todo-validating:\n    actor: check\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: a pragmatic grep/awk port of\n      # src/OpenQuestions.ts's parser rules (the format's executable spec) —\n      # free-form prose, plus an OPTIONAL \"## Open Questions\" section; every\n      # \"### \" sub-heading directly under it is one question whose body's\n      # first non-blank line must start with \"Suggested default: \" or\n      # \"Answer: \". A violation is one finding line (file + line + rule) in\n      # .gtd/FORMAT.md; a clean parse removes any stale .gtd/FORMAT.md\n      # instead. What FORMAT.md's presence/absence MEANS (another drafting\n      # round vs. proceeding to the human) is decided by this state's own\n      # `on` rules at capture time — never here.\n      set +e\n      mkdir -p .gtd\n      awk '\n        BEGIN { in_section = 0; have_question = 0; question = \"\"; qline = 0; body_seen = 0 }\n        {\n          trimmed = $0\n          gsub(/^[ \\t]+|[ \\t]+$/, \"\", trimmed)\n\n          level = 0\n          if (match(trimmed, /^#+/)) level = RLENGTH\n\n          if (in_section && level >= 1 && level <= 2) {\n            if (have_question && !body_seen) {\n              printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n            }\n            in_section = 0\n            have_question = 0\n          }\n\n          if (trimmed == \"## Open Questions\") { in_section = 1; next }\n\n          if (in_section && level == 3) {\n            if (have_question && !body_seen) {\n              printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n            }\n            question = trimmed\n            sub(/^### */, \"\", question)\n            qline = NR\n            have_question = 1\n            body_seen = 0\n            next\n          }\n\n          if (in_section && have_question && !body_seen && trimmed != \"\") {\n            if (trimmed ~ /^Suggested default: *.+/ || trimmed ~ /^Answer: *.+/) {\n              body_seen = 1\n            } else {\n              printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n              body_seen = 1\n            }\n          }\n        }\n        END {\n          if (in_section && have_question && !body_seen) {\n            printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n          }\n        }\n      ' <%~ it.vars.todoFile %> > .gtd/.format-findings\n\n      if [ -s .gtd/.format-findings ]; then\n        mv .gtd/.format-findings .gtd/FORMAT.md\n      else\n        rm -f .gtd/.format-findings\n        rm -f .gtd/FORMAT.md\n      fi\n    on:\n      \"A .gtd/FORMAT.md\": grilling\n      \"M .gtd/FORMAT.md\": grilling\n      \"D .gtd/FORMAT.md\": grilling-answer\n      \"C\": grilling-answer\n\n  grilling-answer:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.todoFile %>` holds the plan under development, with any\n      open questions under `## Open Questions` — each carrying a suggested\n      default.\n\n      To answer a question, edit its entry in place (replace\n      `Suggested default: ...` with `Answer: ...`, or add further detail),\n      then run `gtd step human`.\n\n      To accept all suggested defaults as-is and move on to implementation,\n      run `gtd step human` with no edits.\n    on:\n      \"C\": building\n      \"* **\": grilling\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create or edit anything under `.gtd/` except deleting\n      `<%= it.vars.todoFile %>`, which this prompt tells you to delete once\n      its work is complete.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write\n      all the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: run the test suite and record a\n      # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another\n      # fix round vs escalation) is decided by the workflow's own `on`/`retry`\n      # rules at capture time — never here.\n      #\n      # `it.vars.testCommand` defaults to \"npm test\" (this workflow's own\n      # `vars:` above) — override it with a top-level `.gtdrc`\n      # `vars: { testCommand: ... }` key, or a `GTD_VAR_testCommand`\n      # environment variable (highest precedence).\n      #\n      # A green run also removes any `<%= it.vars.feedbackFile %>` left over\n      # from an earlier red run — there is no squash to discard it for us\n      # anymore, so the script cleans it up itself before moving on to\n      # review.\n      set +e\n      mkdir -p .gtd\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output <%~ it.vars.feedbackFile %>\n        else\n          rm -f .gtd/.check-output\n          printf 'npm test failed with exit code %s and produced no output.' \"$code\" > <%~ it.vars.feedbackFile %>\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f <%~ it.vars.feedbackFile %>\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix\n      the code so the suite passes. Keep the change focused — do not\n      refactor unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue; the\n      machine picks the dispute up either way.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      Investigate and fix it yourself (editing code and/or\n      `<%= it.vars.feedbackFile %>`), then run `gtd step human` to try the\n      check again.\n    on:\n      \"* **\": checking\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: smart\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewFile %>`, which this prompt tells you to write.\n      Never touch `.gtd/FORMAT.md` yourself if it exists — a validator writes\n      it, and only the validator removes it once you've fixed the underlying\n      problem.\n\n      If `.gtd/FORMAT.md` exists, it holds format findings from your last\n      draft of `<%= it.vars.reviewFile %>` — fix those findings first, then\n      continue below.\n\n      Write `<%= it.vars.reviewFile %>` to help a human review the cycle's\n      full diff (inlined below) in this EXACT format:\n\n      - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n      - Somewhere in the document: `<!-- base: <%= it.startCommit %> -->`\n      - At least one `## <Chunk Title>` heading, grouping hunks semantically\n        (same feature/refactor/fix, even across files) — a short explanation\n        of what changed and why, then one\n        `- [ ] ./path/to/file.ts#42 — note` file pointer per hunk (checkboxes\n        are for the human to tick, not you; every path is `./`-relative, with\n        an optional `#line` and an optional ` — note`).\n\n      Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"* **\": review-validating\n\n  review-validating:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: a pragmatic grep/awk port of\n      # src/ReviewDoc.ts's parser rules (the format's executable spec) — a\n      # `# Review: <hash>` header as the first non-blank line, a\n      # `<!-- base: <hash> -->` comment, and at least one `##` chunk with at\n      # least one `- [ ]`/`- [x]` file pointer. A violation is one finding\n      # line (file + line + rule) in .gtd/FORMAT.md; a clean parse removes any\n      # stale .gtd/FORMAT.md instead. What FORMAT.md's presence/absence MEANS\n      # (another drafting round vs. handing off to the human) is decided by\n      # this state's own `on` rules at capture time — never here.\n      set +e\n      mkdir -p .gtd\n      awk '\n        BEGIN {\n          first_nonblank_seen = 0\n          header_ok = 0\n          base_ok = 0\n          chunk_open = 0\n          chunk_title = \"\"\n          chunk_line = 0\n          chunk_files = 0\n          chunk_count = 0\n        }\n        {\n          trimmed = $0\n          gsub(/^[ \\t]+|[ \\t]+$/, \"\", trimmed)\n\n          if (!first_nonblank_seen && trimmed != \"\") {\n            first_nonblank_seen = 1\n            if (trimmed ~ /^# Review: [^ ]+$/) {\n              header_ok = 1\n            } else {\n              printf \"<%~ it.vars.reviewFile %>:%d: first non-blank line must be \\\"# Review: <hash>\\\"\\n\", NR\n            }\n          }\n\n          if (trimmed ~ /^<!-- *base: *[^ ]+ *-->$/) base_ok = 1\n\n          if (trimmed ~ /^## [^ ]/) {\n            if (chunk_open && chunk_files == 0) {\n              printf \"<%~ it.vars.reviewFile %>:%d: chunk \\\"%s\\\" has no file pointers\\n\", chunk_line, chunk_title\n            }\n            chunk_open = 1\n            chunk_title = trimmed\n            sub(/^## /, \"\", chunk_title)\n            chunk_line = NR\n            chunk_files = 0\n            chunk_count++\n            next\n          }\n\n          if (chunk_open) {\n            if (trimmed ~ /^-[ \\t]*\\[[ xX]\\][ \\t]*\\.\\/[^ \\t]+/) {\n              chunk_files++\n            } else if (trimmed ~ /^-[ \\t]*\\[/) {\n              printf \"<%~ it.vars.reviewFile %>:%d: file pointer does not match \\\"- [ ] ./path#line — note\\\"\\n\", NR\n            }\n          }\n        }\n        END {\n          if (chunk_open && chunk_files == 0) {\n            printf \"<%~ it.vars.reviewFile %>:%d: chunk \\\"%s\\\" has no file pointers\\n\", chunk_line, chunk_title\n          }\n          if (!header_ok) {\n            print \"<%~ it.vars.reviewFile %>:1: missing or malformed \\\"# Review: <hash>\\\" header as first line\"\n          }\n          if (!base_ok) {\n            print \"<%~ it.vars.reviewFile %>:1: missing \\\"<!-- base: <hash> -->\\\" comment\"\n          }\n          if (chunk_count == 0) {\n            print \"<%~ it.vars.reviewFile %>:1: no \\\"##\\\" chunks found\"\n          }\n        }\n      ' <%~ it.vars.reviewFile %> > .gtd/.format-findings\n\n      if [ -s .gtd/.format-findings ]; then\n        mv .gtd/.format-findings .gtd/FORMAT.md\n      else\n        rm -f .gtd/.format-findings\n        rm -f .gtd/FORMAT.md\n      fi\n    on:\n      \"A .gtd/FORMAT.md\": reviewing\n      \"M .gtd/FORMAT.md\": reviewing\n      \"D .gtd/FORMAT.md\": await-review\n      \"C\": await-review\n\n  await-review:\n    actor: human\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the completed\n      cycle — tick a pointer's `- [ ]` box to `- [x]` to approve that item;\n      add notes, untick, or edit code for feedback.\n\n      To approve: tick every box, then run `gtd step human`.\n\n      To approve the whole cycle without ticking every box individually:\n      delete `<%= it.vars.reviewFile %>` and run `gtd step human`.\n\n      To request changes: edit `<%= it.vars.reviewFile %>`\n      (ticking/unticking boxes, adding notes) and/or the code, then run\n      `gtd step human` — any edit to `<%= it.vars.reviewFile %>` sends the\n      cycle to a deterministic check that either closes the cycle out (every\n      box ticked) or extracts the still-unticked items into a fresh\n      `<%= it.vars.todoFile %>` and routes back through grilling with that\n      feedback. Code-only edits (leaving `<%= it.vars.reviewFile %>`\n      untouched) go straight back to grilling.\n    on:\n      \"D .gtd/REVIEW.md\": idle\n      \"M .gtd/REVIEW.md\": review-deciding\n      \"* **\": grilling\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: if .gtd/REVIEW.md still has any\n      # unticked \"- [ ]\" pointer, extract those pointers (with their notes)\n      # into a fresh .gtd/TODO.md; either way, remove .gtd/REVIEW.md. What\n      # the resulting diff MEANS (feedback lap vs. full approval) is decided\n      # by this state's own `on` rules at capture time — never here. The\n      # A/M .gtd/TODO.md row is declared BEFORE the D .gtd/REVIEW.md row (see\n      # this workflow's `on` map below) so a feedback lap — which always also\n      # deletes .gtd/REVIEW.md — is captured as feedback, not mistaken for an\n      # approval.\n      set +e\n      mkdir -p .gtd\n      if grep -qE '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %> 2>/dev/null; then\n        {\n          echo \"Feedback from review — address these before continuing:\"\n          echo\n          grep -E '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %>\n        } > <%~ it.vars.todoFile %>\n      fi\n      rm -f <%~ it.vars.reviewFile %>\n    on:\n      \"A .gtd/TODO.md\": grilling\n      \"M .gtd/TODO.md\": grilling\n      \"D .gtd/REVIEW.md\": idle\n      \"C\": await-review\n"), ".");
+const compiled = compileWorkflowConfig((0, import_dist$1.parse)("# The bundled default gtd workflow (v3 \"pattern machine\" — see\n# docs/design/pattern-machine-plan.md, and\n# docs/design/steering-file-loops.md for the two validation loops below).\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/default.ts does the compiling).\n#\n# Every content string below is INLINE (no `./`-relative file references):\n# the bundled default ships inside a single-file build\n# (`dist/gtd.bundle.mjs`), so its content must already be resolved at BUILD\n# time rather than read from disk at RUNTIME — the same reason\n# `src/prompts/*.md` are imported through tsdown's `.md`-as-text loader\n# instead of read via `fs` at runtime. `default.yaml` itself is imported the\n# same way (tsdown/vitest both treat `.yaml` as text — see\n# tsdown.config.ts / tests/vitest.rawMd.ts), so this file never needs a\n# sibling prompts/ directory to exist on disk once installed.\n#\n# States, in cycle order — 12 states, no squash:\n#   idle (initial, human, message)\n#     -> grilling (agent, prompt): reads .gtd/TODO.md's sketch (or a prior\n#     lap's feedback), explores the codebase, and develops it into a concrete\n#     implementation plan, stating any open question it can't settle itself\n#     under a `## Open Questions` heading (see \"Loop 1\" below) rather than\n#     guessing silently.\n#   grilling -> todo-validating (check, script): mechanics-only parser port\n#     of the open-questions format (see src/OpenQuestions.ts's module doc for\n#     the executable spec this is a bash rendition of). Malformed ->\n#     .gtd/FORMAT.md -> back to grilling; valid -> grilling-answer.\n#   todo-validating -> grilling-answer (human, message): tick off suggested\n#     defaults by replacing them with `Answer:` lines; a clean step accepts\n#     every remaining default -> building; any edit loops back to grilling.\n#   grilling-answer -> building (agent, prompt): implements the plan in\n#     .gtd/TODO.md directly (no task decomposition, no per-task queue) and\n#     deletes .gtd/TODO.md once the work is complete and verified.\n#   building -> checking (check, script): runs the test command inline;\n#     A/M .gtd/FEEDBACK.md -> fixing (capped, redirects to escalate); D\n#     .gtd/FEEDBACK.md (a green run that just cleaned up prior feedback) or C\n#     (green, nothing to clean) -> reviewing.\n#   fixing (agent, prompt) <-> checking\n#   escalate (human, message): manual intervention, then back to checking\n#   checking (green) -> reviewing (agent, prompt): writes .gtd/REVIEW.md in\n#     the checkbox review format (see \"Loop 2\" below), grouping the cycle's\n#     full diff into reviewable chunks.\n#   reviewing -> review-validating (check, script): mechanics-only parser\n#     port of the review format (see src/ReviewDoc.ts's module doc for the\n#     executable spec). Malformed -> .gtd/FORMAT.md -> back to reviewing;\n#     valid -> await-review.\n#   review-validating -> await-review (human, message): tick a pointer's `- [\n#     ]` to `- [x]` to approve that item; deleting .gtd/REVIEW.md outright is\n#     the power-user approve-everything shortcut; anything else pending\n#     (code edits with REVIEW.md untouched) is feedback straight to grilling.\n#   await-review -> review-deciding (check, script), entered by any `M\n#     .gtd/REVIEW.md` step: if no unticked `- [ ]` pointer remains, the cycle\n#     is approved (rm .gtd/REVIEW.md -> idle); otherwise the still-unticked\n#     pointers (with their notes) are extracted into a fresh .gtd/TODO.md and\n#     .gtd/REVIEW.md is removed (-> grilling, feedback lap).\n#\n# The cycle ends at human approval, resting back at idle — there is no\n# squash state. The cycle's commits stay in history; whether/how to squash\n# them (amend, interactive rebase, a PR's squash-merge) is entirely the\n# human's business once they're done reviewing — gtd makes no assumption.\n# That squash-flavored finale (a `squashing` prompt state + a `done` commit\n# state) still exists as an ENGINE capability (see STATES.md §8) and is kept\n# as part of the fuller machine at docs/examples/advanced-workflow.md.\n#\n# A `gtd(<actor>): idle` commit — entering the workflow's own initial state —\n# is therefore a PROCESS BOUNDARY (see `computeProcessRun` in src/Edge.ts):\n# the next cycle's `retry` counts, `startCommit`, and diffs never reach back\n# across an approved cycle's own idle-entering commit.\n#\n# HYGIENE INVARIANT (asserted in e2e — see default-workflow.feature): an\n# approved cycle leaves `.gtd/` empty. FEEDBACK.md is cleaned up by a green\n# `checking` run; FORMAT.md by a valid validator run (either loop); REVIEW.md\n# by the review-deciding approval branch; TODO.md by `building`.\n#\n# Loop 1 — TODO.md open questions (src/OpenQuestions.ts is this format's\n# EXECUTABLE SPEC — its unit tests are the format's spec tests; the\n# `todo-validating`/`review-validating` bash scripts below are a pragmatic\n# grep/awk PORT of the exact same rules, not a full markdown parser. Keep\n# both in sync by hand — there is no shared code path between the two\n# implementations, by design: the engine stays git/filesystem/Effect-free,\n# and the LSP's parsers stay dependency-free).\n#\n# Loop 2 — REVIEW.md checkboxes: same dual-implementation contract, this time\n# against src/ReviewDoc.ts.\n#\n# `grilling` and `reviewing` both declare `model: smart` — an opaque harness\n# hint (see the comment at `grilling` below) for their heavier one-shot\n# planning/reviewing turns. Every other state is unset (harness default).\n#\n# `vars.testCommand` is this workflow's own declared default for `checking`'s\n# script (see it.vars in PatternTemplates.ts) — override it per-repo with a\n# top-level `.gtdrc` `vars: { testCommand: ... }` key, or per-invocation with\n# a `GTD_VAR_testCommand` environment variable (highest precedence).\n#\n# `vars.todoFile`/`reviewFile`/`feedbackFile` are this workflow's ONE source\n# of truth for the three steering-file paths every prompt/script below reads\n# or writes — each appears in templates as `<%~ it.vars.todoFile %>` etc\n# (see docs/design/state-file-association.md §2). Every state that rests on\n# one of these files also declares a `file:`/`mode:` pair (see STATES.md's\n# property table) so `gtd status`/`gtd next --json` and the LSP (`gtd lsp`)\n# know which file a human/editor should look at, and in what format\n# (`qa` for TODO.md's open-questions format, `review` for REVIEW.md's\n# checkbox format) — `fixing`/`escalate` declare `file:` alone (FEEDBACK.md\n# is plain text, no LSP format). KNOWN LIMITATION: `on` pattern keys below are\n# NOT Eta templates — they keep the LITERAL `.gtd/...` paths matching these\n# vars' DEFAULT values. Repointing `todoFile`/`reviewFile`/`feedbackFile` via\n# `.gtdrc`'s top-level `vars:` or a `GTD_VAR_` override changes what `file:`\n# renders to (and what a template reads/writes) WITHOUT changing what the\n# `on` patterns match against — desyncing the machine. See\n# docs/configuration.md's `file:`/`mode:` section for the full caveat.\n#\n# A fuller machine — two-phase Q&A planning, an architecture phase, task\n# decomposition, a deterministic per-task builder loop, agent-prepared\n# review, and the squash finale (`squashing` + `done`) — is preserved as a\n# copy-paste `.gtdrc` example at docs/examples/advanced-workflow.md.\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  reviewFile: .gtd/REVIEW.md\n  feedbackFile: .gtd/FEEDBACK.md\n\nstates:\n  idle:\n    actor: human\n    initial: true\n    message: |\n      No active gtd cycle.\n\n      To start one: write `.gtd/TODO.md` with a short sketch of what you want\n      built — a few sentences is enough — then run `gtd step human`.\n    on:\n      \"* **\": grilling\n\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # `model` is an opaque harness hint — gtd never interprets this string, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so the\n    # driving loop can map it onto whatever models its agent harness\n    # provides. \"smart\" here just names the harness-chosen tier for the\n    # heavier planning turn; states without a `model` use the harness's\n    # default.\n    model: smart\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.todoFile %>`, which this prompt tells you to develop. Never\n      touch `.gtd/FORMAT.md` yourself if it exists — a validator writes it,\n      and only the validator removes it once you've fixed the underlying\n      problem.\n\n      If `.gtd/FORMAT.md` exists, it holds format findings from your last\n      draft of `<%= it.vars.todoFile %>` — fix those findings first, then\n      continue below.\n\n      `<%= it.vars.todoFile %>` holds a short sketch of what to build (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete implementation plan.\n\n      For every question you cannot settle yourself, add it under a\n      `## Open Questions` heading, one `### <question>` sub-heading each,\n      whose body's FIRST non-blank line is exactly\n      `Suggested default: <your answer>` — the human can accept it as-is or\n      override it. Omit the section entirely once there are no open\n      questions. If `<%= it.vars.todoFile %>` already carries\n      `## Open Questions` entries from a previous lap, fold any\n      `Answer: <text>` line into the plan; every remaining entry's body must\n      still start with either `Suggested default: ...` or `Answer: ...` —\n      never anything else.\n\n      Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n      not commit, and do not run `gtd step agent` yourself; the harness does\n      that.\n    on:\n      \"* **\": todo-validating\n\n  todo-validating:\n    actor: check\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: a pragmatic grep/awk port of\n      # src/OpenQuestions.ts's parser rules (the format's executable spec) —\n      # free-form prose, plus an OPTIONAL \"## Open Questions\" section; every\n      # \"### \" sub-heading directly under it is one question whose body's\n      # first non-blank line must start with \"Suggested default: \" or\n      # \"Answer: \". A violation is one finding line (file + line + rule) in\n      # .gtd/FORMAT.md; a clean parse removes any stale .gtd/FORMAT.md\n      # instead. What FORMAT.md's presence/absence MEANS (another drafting\n      # round vs. proceeding to the human) is decided by this state's own\n      # `on` rules at capture time — never here.\n      set +e\n      mkdir -p .gtd\n      awk '\n        BEGIN { in_section = 0; have_question = 0; question = \"\"; qline = 0; body_seen = 0 }\n        {\n          trimmed = $0\n          gsub(/^[ \\t]+|[ \\t]+$/, \"\", trimmed)\n\n          level = 0\n          if (match(trimmed, /^#+/)) level = RLENGTH\n\n          if (in_section && level >= 1 && level <= 2) {\n            if (have_question && !body_seen) {\n              printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n            }\n            in_section = 0\n            have_question = 0\n          }\n\n          if (trimmed == \"## Open Questions\") { in_section = 1; next }\n\n          if (in_section && level == 3) {\n            if (have_question && !body_seen) {\n              printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n            }\n            question = trimmed\n            sub(/^### */, \"\", question)\n            qline = NR\n            have_question = 1\n            body_seen = 0\n            next\n          }\n\n          if (in_section && have_question && !body_seen && trimmed != \"\") {\n            if (trimmed ~ /^Suggested default: *.+/ || trimmed ~ /^Answer: *.+/) {\n              body_seen = 1\n            } else {\n              printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n              body_seen = 1\n            }\n          }\n        }\n        END {\n          if (in_section && have_question && !body_seen) {\n            printf \"<%~ it.vars.todoFile %>:%d: open question \\\"%s\\\" is missing a \\\"Suggested default: ...\\\" or \\\"Answer: ...\\\" line\\n\", qline, question\n          }\n        }\n      ' <%~ it.vars.todoFile %> > .gtd/.format-findings\n\n      if [ -s .gtd/.format-findings ]; then\n        mv .gtd/.format-findings .gtd/FORMAT.md\n      else\n        rm -f .gtd/.format-findings\n        rm -f .gtd/FORMAT.md\n      fi\n    on:\n      \"A .gtd/FORMAT.md\": grilling\n      \"M .gtd/FORMAT.md\": grilling\n      \"D .gtd/FORMAT.md\": grilling-answer\n      \"C\": grilling-answer\n\n  grilling-answer:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.todoFile %>` holds the plan under development, with any\n      open questions under `## Open Questions` — each carrying a suggested\n      default.\n\n      To answer a question, edit its entry in place (replace\n      `Suggested default: ...` with `Answer: ...`, or add further detail),\n      then run `gtd step human`.\n\n      To accept all suggested defaults as-is and move on to implementation,\n      run `gtd step human` with no edits.\n    on:\n      \"C\": building\n      \"* **\": grilling\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create or edit anything under `.gtd/` except deleting\n      `<%= it.vars.todoFile %>`, which this prompt tells you to delete once\n      its work is complete.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write\n      all the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: run the test suite and record a\n      # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another\n      # fix round vs escalation) is decided by the workflow's own `on`/`retry`\n      # rules at capture time — never here.\n      #\n      # `it.vars.testCommand` defaults to \"npm test\" (this workflow's own\n      # `vars:` above) — override it with a top-level `.gtdrc`\n      # `vars: { testCommand: ... }` key, or a `GTD_VAR_testCommand`\n      # environment variable (highest precedence).\n      #\n      # A green run also removes any `<%= it.vars.feedbackFile %>` left over\n      # from an earlier red run — there is no squash to discard it for us\n      # anymore, so the script cleans it up itself before moving on to\n      # review.\n      set +e\n      mkdir -p .gtd\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output <%~ it.vars.feedbackFile %>\n        else\n          rm -f .gtd/.check-output\n          printf 'npm test failed with exit code %s and produced no output.' \"$code\" > <%~ it.vars.feedbackFile %>\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f <%~ it.vars.feedbackFile %>\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix\n      the code so the suite passes. Keep the change focused — do not\n      refactor unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue; the\n      machine picks the dispute up either way.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      Investigate and fix it yourself (editing code and/or\n      `<%= it.vars.feedbackFile %>`), then run `gtd step human` to try the\n      check again.\n    on:\n      \"* **\": checking\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: smart\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewFile %>`, which this prompt tells you to write.\n      Never touch `.gtd/FORMAT.md` yourself if it exists — a validator writes\n      it, and only the validator removes it once you've fixed the underlying\n      problem.\n\n      If `.gtd/FORMAT.md` exists, it holds format findings from your last\n      draft of `<%= it.vars.reviewFile %>` — fix those findings first, then\n      continue below.\n\n      Write `<%= it.vars.reviewFile %>` to help a human review the cycle's\n      full diff (inlined below) in this EXACT format:\n\n      - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n      - Somewhere in the document: `<!-- base: <%= it.startCommit %> -->`\n      - At least one `## <Chunk Title>` heading, grouping hunks semantically\n        (same feature/refactor/fix, even across files) — a short explanation\n        of what changed and why, then one\n        `- [ ] ./path/to/file.ts#42 — note` file pointer per hunk (checkboxes\n        are for the human to tick, not you; every path is `./`-relative, with\n        an optional `#line` and an optional ` — note`).\n\n      Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"* **\": review-validating\n\n  review-validating:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: a pragmatic grep/awk port of\n      # src/ReviewDoc.ts's parser rules (the format's executable spec) — a\n      # `# Review: <hash>` header as the first non-blank line, a\n      # `<!-- base: <hash> -->` comment, and at least one `##` chunk with at\n      # least one `- [ ]`/`- [x]` file pointer. A violation is one finding\n      # line (file + line + rule) in .gtd/FORMAT.md; a clean parse removes any\n      # stale .gtd/FORMAT.md instead. What FORMAT.md's presence/absence MEANS\n      # (another drafting round vs. handing off to the human) is decided by\n      # this state's own `on` rules at capture time — never here.\n      set +e\n      mkdir -p .gtd\n      awk '\n        BEGIN {\n          first_nonblank_seen = 0\n          header_ok = 0\n          base_ok = 0\n          chunk_open = 0\n          chunk_title = \"\"\n          chunk_line = 0\n          chunk_files = 0\n          chunk_count = 0\n        }\n        {\n          trimmed = $0\n          gsub(/^[ \\t]+|[ \\t]+$/, \"\", trimmed)\n\n          if (!first_nonblank_seen && trimmed != \"\") {\n            first_nonblank_seen = 1\n            if (trimmed ~ /^# Review: [^ ]+$/) {\n              header_ok = 1\n            } else {\n              printf \"<%~ it.vars.reviewFile %>:%d: first non-blank line must be \\\"# Review: <hash>\\\"\\n\", NR\n            }\n          }\n\n          if (trimmed ~ /^<!-- *base: *[^ ]+ *-->$/) base_ok = 1\n\n          if (trimmed ~ /^## [^ ]/) {\n            if (chunk_open && chunk_files == 0) {\n              printf \"<%~ it.vars.reviewFile %>:%d: chunk \\\"%s\\\" has no file pointers\\n\", chunk_line, chunk_title\n            }\n            chunk_open = 1\n            chunk_title = trimmed\n            sub(/^## /, \"\", chunk_title)\n            chunk_line = NR\n            chunk_files = 0\n            chunk_count++\n            next\n          }\n\n          if (chunk_open) {\n            if (trimmed ~ /^-[ \\t]*\\[[ xX]\\][ \\t]*\\.\\/[^ \\t]+/) {\n              chunk_files++\n            } else if (trimmed ~ /^-[ \\t]*\\[/) {\n              printf \"<%~ it.vars.reviewFile %>:%d: file pointer does not match \\\"- [ ] ./path#line — note\\\"\\n\", NR\n            }\n          }\n        }\n        END {\n          if (chunk_open && chunk_files == 0) {\n            printf \"<%~ it.vars.reviewFile %>:%d: chunk \\\"%s\\\" has no file pointers\\n\", chunk_line, chunk_title\n          }\n          if (!header_ok) {\n            print \"<%~ it.vars.reviewFile %>:1: missing or malformed \\\"# Review: <hash>\\\" header as first line\"\n          }\n          if (!base_ok) {\n            print \"<%~ it.vars.reviewFile %>:1: missing \\\"<!-- base: <hash> -->\\\" comment\"\n          }\n          if (chunk_count == 0) {\n            print \"<%~ it.vars.reviewFile %>:1: no \\\"##\\\" chunks found\"\n          }\n        }\n      ' <%~ it.vars.reviewFile %> > .gtd/.format-findings\n\n      if [ -s .gtd/.format-findings ]; then\n        mv .gtd/.format-findings .gtd/FORMAT.md\n      else\n        rm -f .gtd/.format-findings\n        rm -f .gtd/FORMAT.md\n      fi\n    on:\n      \"A .gtd/FORMAT.md\": reviewing\n      \"M .gtd/FORMAT.md\": reviewing\n      \"D .gtd/FORMAT.md\": await-review\n      \"C\": await-review\n\n  await-review:\n    actor: human\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # While the cycle rests here for human review, gtd opens a \"review checkout\n    # window\": HEAD and the index are temporarily rewound to this cycle's start\n    # (the process boundary — no `reviewBase` state is declared, so the base\n    # defaults to it) with the working tree untouched, so the whole cycle diff\n    # surfaces as ordinary uncommitted changes in the editor's git integration.\n    # The window closes automatically on the next invocation, once the cycle\n    # rests anywhere else (see src/ReviewWindow.ts, STATES.md §11).\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the completed\n      cycle — tick a pointer's `- [ ]` box to `- [x]` to approve that item;\n      add notes, untick, or edit code for feedback.\n\n      To approve: tick every box, then run `gtd step human`.\n\n      To approve the whole cycle without ticking every box individually:\n      delete `<%= it.vars.reviewFile %>` and run `gtd step human`.\n\n      To request changes: edit `<%= it.vars.reviewFile %>`\n      (ticking/unticking boxes, adding notes) and/or the code, then run\n      `gtd step human` — any edit to `<%= it.vars.reviewFile %>` sends the\n      cycle to a deterministic check that either closes the cycle out (every\n      box ticked) or extracts the still-unticked items into a fresh\n      `<%= it.vars.todoFile %>` and routes back through grilling with that\n      feedback. Code-only edits (leaving `<%= it.vars.reviewFile %>`\n      untouched) go straight back to grilling.\n    on:\n      \"D .gtd/REVIEW.md\": idle\n      \"M .gtd/REVIEW.md\": review-deciding\n      \"* **\": grilling\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: if .gtd/REVIEW.md still has any\n      # unticked \"- [ ]\" pointer, extract those pointers (with their notes)\n      # into a fresh .gtd/TODO.md; either way, remove .gtd/REVIEW.md. What\n      # the resulting diff MEANS (feedback lap vs. full approval) is decided\n      # by this state's own `on` rules at capture time — never here. The\n      # A/M .gtd/TODO.md row is declared BEFORE the D .gtd/REVIEW.md row (see\n      # this workflow's `on` map below) so a feedback lap — which always also\n      # deletes .gtd/REVIEW.md — is captured as feedback, not mistaken for an\n      # approval.\n      set +e\n      mkdir -p .gtd\n      if grep -qE '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %> 2>/dev/null; then\n        {\n          echo \"Feedback from review — address these before continuing:\"\n          echo\n          grep -E '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %>\n        } > <%~ it.vars.todoFile %>\n      fi\n      rm -f <%~ it.vars.reviewFile %>\n    on:\n      \"A .gtd/TODO.md\": grilling\n      \"M .gtd/TODO.md\": grilling\n      \"D .gtd/REVIEW.md\": idle\n      \"C\": await-review\n"), ".");
 const defaultWorkflowDefinition = compiled.definition;
 /** The default workflow's own declared `vars:` defaults — `{ testCommand: "npm test" }`, overridable via a top-level `.gtdrc` `vars:` key or a `GTD_VAR_testCommand` environment variable (see `src/Edge.ts`'s `resolveVars`). */
 const defaultWorkflowVars = compiled.vars;
@@ -189811,6 +189883,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 +189907,108 @@ 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."
+					},
+					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."
+					}
+				}
+			}
+		}
+	}
+};
 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
@@ -190735,7 +190922,7 @@ const renderDiff = (files) => {
 };
 //#endregion
 //#region src/Git.ts
-const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const EMPTY_TREE$2 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 /**
 * Parse `git diff --name-status` output into `{ path, status }` pairs.
 * Status codes: A (added), D (deleted), M (modified), R (renamed), C (copied), etc.
@@ -190865,7 +191052,7 @@ const makeGitImpl = (executor, root) => {
 		}),
 		commitDiff: (hash, exclude = []) => gen(function* () {
 			yield* exec("git", "rev-parse", "--verify", hash);
-			const parent = yield* exec("git", "rev-parse", "--verify", `${hash}~1`).pipe(map$4((s) => s.trim()), catchAll(() => succeed$3(EMPTY_TREE$1)));
+			const parent = yield* exec("git", "rev-parse", "--verify", `${hash}~1`).pipe(map$4((s) => s.trim()), catchAll(() => succeed$3(EMPTY_TREE$2)));
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", parent, hash).pipe(catchAll(() => succeed$3("")));
 			const allPaths = parseNameStatus(nameStatusOut);
 			const filtered = applyExcludes(allPaths, exclude);
@@ -190909,6 +191096,8 @@ const makeGitImpl = (executor, root) => {
 			return all;
 		}),
 		resolveRef: (ref) => exec("git", "rev-parse", "--verify", ref).pipe(map$4((s) => s.trim()), flatMap$4((hash) => /^[0-9a-f]{40}$/.test(hash) ? succeed$3(hash) : fail$2(/* @__PURE__ */ new Error(`Invalid ref: ${ref}`)))),
+		readRefOption: (ref) => exec("git", "rev-parse", "--verify", "--quiet", ref).pipe(map$4((s) => some(s.trim())), catchAll(() => succeed$3(none$4()))),
+		isAncestor: (a, b) => run(root, "git", "merge-base", "--is-ancestor", a, b).pipe(provide$1(succeed$2(CommandExecutor, executor)), map$4(() => true), catchAll(() => succeed$3(false))),
 		topLevel: () => exec("git", "rev-parse", "--show-toplevel").pipe(map$4((s) => s.trim())),
 		commitHistory: (base) => {
 			const range = base !== void 0 ? `${base}..HEAD` : void 0;
@@ -190943,7 +191132,12 @@ const makeGitImpl = (executor, root) => {
 		discardPending: () => gen(function* () {
 			yield* exec("git", "add", "-A");
 			yield* exec("git", "reset", "--hard", "HEAD");
-		}).pipe(asVoid)
+		}).pipe(asVoid),
+		updateRef: (ref, hash) => exec("git", "update-ref", ref, hash).pipe(asVoid),
+		deleteRef: (ref) => exec("git", "update-ref", "-d", ref).pipe(asVoid),
+		mixedResetTo: (ref) => exec("git", "reset", "--mixed", ref).pipe(asVoid),
+		restoreStagedFrom: (source, paths) => paths.length === 0 ? _void : exec("git", "restore", "--staged", `--source=${source}`, "--", ...paths).pipe(catchAll(() => _void)),
+		addIntentToAdd: () => exec("git", "add", "--intent-to-add", ".").pipe(asVoid)
 	};
 };
 const makeLiveEffect = gen(function* () {
@@ -191493,8 +191687,8 @@ const renderStateTemplate = (template, context) => eta.renderString(template, co
 * one commit (or one squash). A caller that wants several transitions issues
 * several invocations.
 */
-const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
-const subjectOf = (message) => (message.split("\n")[0] ?? "").trim();
+const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const subjectOf$1 = (message) => (message.split("\n")[0] ?? "").trim();
 /** Collapse an arbitrary git status letter to the pattern grammar's closed `A|M|D` set (mirrors the plan's decision 5 — only those three are meaningful statuses). */
 const normalizeStatus = (raw) => raw === "A" ? "A" : raw === "D" ? "D" : "M";
 /** Resolve HEAD's subject against the active workflow definition (the bundled default, or a compiled `.gtdrc` `workflow:` key). */
@@ -191538,20 +191732,20 @@ const pendingChanges = (git) => git.changedPaths().pipe(map$4((entries) => entri
 const computeProcessRun = (git, def) => gen(function* () {
 	if (!(yield* git.hasCommits())) return {
 		startHash: "",
-		startParentHash: EMPTY_TREE,
+		startParentHash: EMPTY_TREE$1,
 		trace: []
 	};
 	const initialState = initialStateOf(def);
 	const history = yield* git.commitHistory();
 	let i = history.length - 1;
 	while (i >= 0) {
-		const parsed = parseStateSubject(subjectOf(history[i].message));
+		const parsed = parseStateSubject(subjectOf$1(history[i].message));
 		if (parsed === void 0 || parsed.state === initialState) break;
 		i--;
 	}
 	const startIdx = i + 1;
-	const trace = history.slice(startIdx).map((h) => parseStateSubject(subjectOf(h.message)).state);
-	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE;
+	const trace = history.slice(startIdx).map((h) => parseStateSubject(subjectOf$1(h.message)).state);
+	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE$1;
 	return {
 		startHash: startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash,
 		startParentHash,
@@ -191675,7 +191869,7 @@ const executeDecision = (git, run, decision, context) => gen(function* () {
 			yield* git.discardPending();
 			return {
 				kind: "squash",
-				subject: subjectOf(message)
+				subject: subjectOf$1(message)
 			};
 		}
 		case "noop": return {
@@ -191685,6 +191879,120 @@ const executeDecision = (git, run, decision, context) => gen(function* () {
 	}
 });
 //#endregion
+//#region src/ReviewWindow.ts
+/**
+* The review checkout window (v3 re-introduction — see
+* `docs/design/pattern-machine-plan.md`'s follow-up note and STATES.md §11).
+* While a process RESTS at a state declaring `reviewWindow: true` (the
+* bundled default's `await-review`), HEAD and the index are temporarily
+* rewound to the review base with the working tree untouched, so the entire
+* `base..HEAD` diff surfaces as ordinary uncommitted changes in any editor's
+* standard git integration (SCM panel, gutters, per-file diffs, discard-hunk).
+*
+* v2 hard-wired this to a single `awaiting-review` gate; v3 drives it purely
+* from the DECLARATIVE `reviewWindow`/`reviewBase` state properties (see
+* `PatternMachine.StateDef`) — the pure engine never observes an open window,
+* exactly as before.
+*
+* Lifecycle — driven from the program edge (`src/program.ts`), bracketing
+* every state subcommand:
+*
+* - `closeReviewWindow` runs BEFORE anything reads or mutates state, keyed
+*   solely on `refs/gtd/review-head` existing: `git reset --mixed
+*   refs/gtd/review-head` restores HEAD/index exactly, leaving only the
+*   reviewer's own edits dirty (captured by the resting state's own `on`
+*   patterns like any other pending change). The pure machine therefore never
+*   sees the window.
+* - `openReviewWindow` runs AFTER the subcommand finishes and self-guards on
+*   the resolved rest declaring `reviewWindow: true`: it saves HEAD to
+*   `refs/gtd/review-head` (the base to `refs/gtd/review-base`), then `git
+*   reset --mixed <base>`. It re-arms after read-only commands (`gtd next` /
+*   `gtd status`) and refused invocations too, so the editor's diff view stays
+*   consistent no matter which command the loop last ran.
+*
+* Every open/close step is idempotent under re-entry, so a crash at any point
+* is recovered by the next invocation's close (the saved ref also keeps the
+* real head GC-reachable for the window's whole lifetime).
+*/
+const REVIEW_HEAD_REF = "refs/gtd/review-head";
+const REVIEW_BASE_REF = "refs/gtd/review-base";
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const subjectOf = (message) => (message.split("\n")[0] ?? "").trim();
+/**
+* The diff base while the window is open: the hash of the most-recent
+* in-process turn commit that ENTERED a `reviewBase` state, or `undefined`
+* when the workflow declares no such state (the caller then falls back to the
+* process start). Walks the current process run's commits (oldest→newest, via
+* `commitHistory(startParentHash)`), so it never reaches across the process
+* boundary into a previous cycle.
+*/
+const reviewBaseHash = (git, def, run) => gen(function* () {
+	const history = yield* git.commitHistory(run.startParentHash);
+	let base;
+	for (const commit of history) {
+		const parsed = parseStateSubject(subjectOf(commit.message));
+		if (parsed !== void 0 && isReviewBaseState(def, parsed.state)) base = commit.hash;
+	}
+	return base;
+});
+/**
+* Restore the real head if a review checkout window is open; no-op otherwise.
+* Keyed on `refs/gtd/review-head` existence, NOT on any config or machine
+* state, so it always runs first and the machine never sees the window.
+*
+* Fails loudly — refs left in place — when HEAD is no longer on the reviewed
+* branch (the base is not an ancestor of HEAD, e.g. after a branch switch): a
+* mixed reset there would rewrite the wrong branch's tip. Manual commits on
+* top of the base pass the guard: the reset keeps their content in the working
+* tree, where the next turn's capture picks it up as review feedback.
+*/
+const closeReviewWindow = gen(function* () {
+	const git = yield* GitService;
+	const savedHead = yield* git.readRefOption(REVIEW_HEAD_REF);
+	if (isNone(savedHead)) return { closed: false };
+	const base = yield* git.readRefOption(REVIEW_BASE_REF);
+	if (isSome(base) && base.value !== EMPTY_TREE) {
+		if (!(yield* git.isAncestor(base.value, "HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error("a gtd review checkout window is open but HEAD has moved off the reviewed branch — return to it, or restore manually with `git reset --mixed refs/gtd/review-head && git update-ref -d refs/gtd/review-head && git update-ref -d refs/gtd/review-base`"));
+	}
+	yield* git.mixedResetTo(REVIEW_HEAD_REF);
+	yield* git.deleteRef(REVIEW_HEAD_REF);
+	yield* git.deleteRef(REVIEW_BASE_REF);
+	return { closed: true };
+});
+/**
+* Open (or re-arm) the review checkout window. Self-guarded: a no-op unless
+* the resolved rest's state declares `reviewWindow: true` and a distinct base
+* commit exists, so the caller invokes it unconditionally after every state
+* subcommand.
+*
+* The base is the most-recent in-process `reviewBase` commit
+* (`reviewBaseHash`) or, absent any such state, the process start
+* (`startParentHash`). When that resolves to the empty tree (a process with no
+* prior commit) or to HEAD itself (an empty process), there is nothing to
+* surface and the window stays closed.
+*
+* Ordering is crash-safe: base ref → head ref → mixed reset → `.gtd/` index
+* pin → intent-to-add. A crash before the head-ref write leaves only a stale
+* base ref (overwritten on the next open); a crash after it leaves HEAD ==
+* review-head, which the next invocation's close restores as a no-op.
+*/
+const openReviewWindow = gen(function* () {
+	const git = yield* GitService;
+	const def = (yield* ConfigService).workflow;
+	if (!(yield* git.hasCommits())) return { opened: false };
+	if (!isReviewWindowState(def, resolveState(def, yield* git.lastCommitSubject()))) return { opened: false };
+	const run = yield* computeProcessRun(git, def);
+	const base = (yield* reviewBaseHash(git, def, run)) ?? run.startParentHash;
+	const headHash = yield* git.resolveRef("HEAD");
+	if (base === EMPTY_TREE || base === headHash) return { opened: false };
+	yield* git.updateRef(REVIEW_BASE_REF, base);
+	yield* git.updateRef(REVIEW_HEAD_REF, headHash);
+	yield* git.mixedResetTo(base);
+	yield* git.restoreStagedFrom(REVIEW_HEAD_REF, [".gtd"]);
+	yield* git.addIntentToAdd();
+	return { opened: true };
+});
+//#endregion
 //#region node_modules/prettier/doc.mjs
 var doc_exports = /* @__PURE__ */ __exportAll({
 	builders: () => builders,
@@ -364489,6 +364797,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 +364882,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 +365094,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 +365164,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);
 	}
 };
 /**
@@ -364799,8 +365196,12 @@ function makeProgram(opts = {}) {
 		const git = yield* GitService;
 		const fs = yield* FileSystem;
 		yield* assertRunningFromRepoRoot(git, fs);
+		yield* closeReviewWindow;
 		yield* (yield* ConfigInit).ensure;
-		yield* dispatchKnownSubcommand(sub, argv, json, write);
+		const outcome = yield* either(dispatchKnownSubcommand(sub, argv, json, write));
+		const rearm = yield* either(openReviewWindow);
+		if (isLeft(outcome)) return yield* fail$2(outcome.left);
+		if (isLeft(rearm)) return yield* fail$2(rearm.left);
 	}).pipe(json ? catchAll((error) => sync$1(() => write(JSON.stringify({
 		state: "error",
 		prompt: error.message