@pmelab/gtd 3.5.0 → 3.6.0

package/bin/gtd-loop

@@ -7,9 +7,10 @@ set -euo pipefail
 #   - "script"  (a check rest) -> `gtd run` executes it and steps the check
 #     actor in one command; zero new commits = green with nothing owed (the
 #     terminal signal at idle).
-#   - "prompt"  (an agent rest) -> feed `content` to the agent, then
-#     `gtd step <actor>` ourselves — the harness owns ending the turn, not
-#     the prompt text.
+#   - "prompt"  (an agent rest) -> feed `content` to the agent, run the
+#     self-validation gate (`gtd validate`, re-prompting on findings — see the
+#     gate's own comment below), then `gtd step <actor>` ourselves — the
+#     harness owns ending the turn, not the prompt text.
 # `.model` (optional, opaque) is exported as $GTD_LOOP_MODEL for the agent
 # adapter invoked at a "prompt" rest; the default adapter appends `--model
 # "$GTD_LOOP_MODEL"` only when it's non-empty.
@@ -34,6 +35,34 @@ prev_content=""
 # across iterations and across restarts. In the git dir, never the work tree.
 memory_marker="$(git rev-parse --git-dir 2>/dev/null || echo .git)/gtd-loop-memory"
 
+# Swappable agent adapter: GTD_LOOP_AGENT_CMD lets any coding agent CLI stand
+# in for the default, receiving the prompt via $GTD_LOOP_PROMPT, the state's
+# opaque model hint (if any) via $GTD_LOOP_MODEL, and the memory scope via
+# $GTD_LOOP_MEMORY / $GTD_LOOP_SESSION_ID / $GTD_LOOP_MEMORY_RESUME ("1" when
+# this turn should continue the prior session). An adapter that ignores any of
+# these keeps working — they're exported alongside $GTD_LOOP_PROMPT, never
+# required. The default adapter maps the memory signal onto claude's own
+# session flags: --resume to continue the scope's session, --session-id to pin
+# a fresh one so the next same-scope turn can resume it. $1 is the prompt, $2
+# the resume flag; the memory scope ($memory/$session_id) is read from the
+# enclosing iteration, so a same-turn re-prompt (the validate gate) resumes the
+# same session.
+run_agent_turn() {
+  local prompt="$1" do_resume="$2" cmd="${GTD_LOOP_AGENT_CMD:-}"
+  if [[ -z "$cmd" ]]; then
+    cmd='claude -p "$GTD_LOOP_PROMPT"'
+    [[ -n "$model" ]] && cmd="$cmd"' --model "$GTD_LOOP_MODEL"'
+    if [[ "$do_resume" == "1" ]]; then
+      cmd="$cmd"' --resume "$GTD_LOOP_SESSION_ID"'
+    elif [[ -n "$session_id" ]]; then
+      cmd="$cmd"' --session-id "$GTD_LOOP_SESSION_ID"'
+    fi
+    cmd="$cmd"' --dangerously-skip-permissions'
+  fi
+  GTD_LOOP_PROMPT="$prompt" GTD_LOOP_MODEL="$model" GTD_LOOP_MEMORY="$memory" \
+    GTD_LOOP_SESSION_ID="$session_id" GTD_LOOP_MEMORY_RESUME="$do_resume" bash -c "$cmd"
+}
+
 while true; do
   if ! next_json="$(gtd next --json 2>&1)"; then
     echo "gtd-loop: could not determine the next step:" >&2
@@ -104,28 +133,32 @@ while true; do
     rm -f "$memory_marker"
   fi
 
-  # Swappable agent adapter: GTD_LOOP_AGENT_CMD lets any coding agent CLI
-  # stand in for the default, receiving the prompt via $GTD_LOOP_PROMPT, the
-  # state's opaque model hint (if any) via $GTD_LOOP_MODEL, and the memory
-  # scope via $GTD_LOOP_MEMORY / $GTD_LOOP_SESSION_ID / $GTD_LOOP_MEMORY_RESUME
-  # ("1" when this turn should continue the prior session). An adapter that
-  # ignores any of these keeps working — they're exported alongside
-  # $GTD_LOOP_PROMPT, never required. The default adapter maps the memory
-  # signal onto claude's own session flags: --resume to continue the scope's
-  # session, --session-id to pin a fresh one so the next same-scope turn can
-  # resume it.
-  cmd="${GTD_LOOP_AGENT_CMD:-}"
-  if [[ -z "$cmd" ]]; then
-    cmd='claude -p "$GTD_LOOP_PROMPT"'
-    [[ -n "$model" ]] && cmd="$cmd"' --model "$GTD_LOOP_MODEL"'
-    if [[ "$resume" == "1" ]]; then
-      cmd="$cmd"' --resume "$GTD_LOOP_SESSION_ID"'
-    elif [[ -n "$session_id" ]]; then
-      cmd="$cmd"' --session-id "$GTD_LOOP_SESSION_ID"'
+  # Run the agent turn (see run_agent_turn's own comment for the adapter
+  # contract). Then the self-validation gate: a producing state may declare a
+  # `file:`/`mode:` pair (e.g. the default workflow's grilling/reviewing),
+  # making its output's format checkable. `gtd validate` is a no-op (exit 0)
+  # when the resolved rest has nothing to validate, so run it after EVERY agent
+  # turn; on findings, re-prompt the SAME agent session to fix them (up to a
+  # cap) before stepping — the plain-`gtd next` self-validation instruction's
+  # driver-side equivalent, so the next rest is only ever handed a well-formed
+  # file. gtd itself never validates at step time — this is the loop's job.
+  run_agent_turn "$content" "$resume"
+
+  fix_attempt=0
+  while ! validate_out="$(gtd validate 2>&1)"; do
+    fix_attempt=$((fix_attempt + 1))
+    if ((fix_attempt > 3)); then
+      echo "gtd-loop: '$state' still fails \`gtd validate\` after 3 fix attempts:" >&2
+      echo "$validate_out" >&2
+      echo "Stopping rather than stepping with a malformed steering file." >&2
+      exit 1
     fi
-    cmd="$cmd"' --dangerously-skip-permissions'
-  fi
-  GTD_LOOP_PROMPT="$content" GTD_LOOP_MODEL="$model" GTD_LOOP_MEMORY="$memory" \
-    GTD_LOOP_SESSION_ID="$session_id" GTD_LOOP_MEMORY_RESUME="$resume" bash -c "$cmd"
+    # Resume the same session when there is one (the agent just wrote the file);
+    # otherwise a fresh invocation still gets the findings via the prompt.
+    fix_resume=0
+    [[ -n "$session_id" ]] && fix_resume=1
+    run_agent_turn "$content"$'\n\n'"Your last turn does not pass \`gtd validate\`. Fix these format violations, then finish:"$'\n'"$validate_out" "$fix_resume"
+  done
+
   gtd step "$actor" >/dev/null
 done

package/dist/gtd.bundle.mjs

@@ -189919,7 +189919,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# The four agent states each declare a `memory:` scope label (`plan`,\n# `build`, `fix`, `review` — see the comment at `grilling` below) — another\n# opaque hint a memory-aware driver reads to decide when an agent turn keeps\n# the previous turn's memory and when it starts fresh: a loop that re-enters\n# one state (grilling around its answer loop, fixing around checking) keeps\n# the same label and retains memory across its laps; crossing to the next\n# phase's differently-labelled state clears it. gtd never interprets the\n# label (see STATES.md §1 and skills/loop/SKILL.md's driver contract).\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    # Every human-gate `message:` below closes with the SAME rendered block —\n    # a \"What each change does next\" list built from `it.edges`, the resting\n    # state's own `on` edges (see PatternTemplates.TemplateContext.edges). Each\n    # edge's human-readable route lives in its `describe:` (the single source\n    # of truth), so the list can never drift from the routing it documents.\n    # The block skips edges without a `describe`, and each `<%~ ... \"\\n\" %>`\n    # keeps the bullet's own newline (Eta's autoTrim strips the template's own\n    # line breaks around `<% %>` tags, not text inside an interpolation).\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.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save your sketch to `.gtd/TODO.md` (any working-tree change) to start\n          the cycle — the agent reads it, explores the codebase, and develops it\n          into a concrete implementation plan (**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    # `memory` is an opaque memory-scope label — gtd never interprets it, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so a\n    # memory-aware driving loop can decide when an agent turn continues from\n    # the previous turn's memory and when it starts fresh: consecutive agent\n    # turns that emit the SAME label share memory, a change (or the first\n    # turn) is where the driver starts fresh. `grilling` re-enters itself\n    # around the todo-validating/grilling-answer loop, so labelling every lap\n    # `plan` keeps the planner's accumulated exploration across the loop; the\n    # next phase (`building`) carries a different label, clearing it.\n    memory: plan\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. Answer a question by editing its entry in place: replace its\n      `Suggested default: ...` line with `Answer: ...`, or add further detail.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: building\n        describe: >-\n          Change nothing to accept every suggested default as-is and move on to\n          implementation (**building**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Edit the plan — answer a question, add detail, or raise a new one — to\n          send it back for another round of grilling (**grilling**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # A distinct memory scope from `plan`: implementation starts fresh, with\n    # the plan already settled in `.gtd/TODO.md` (which this prompt reads\n    # below) rather than carried in the planner's working memory.\n    memory: build\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    # Its own memory scope: the fix loop re-enters `fixing` around `checking`\n    # (up to the retry cap), so labelling every attempt `fix` lets the agent\n    # remember what it already tried across the loop; a green check moves on\n    # to the differently-labelled `reviewing`, clearing it.\n    memory: fix\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      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or `.gtd/FEEDBACK.md` —\n          to re-run the check (**checking**).\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: smart\n    # A distinct memory scope again: the reviewer looks at the cycle's full\n    # diff (inlined into its prompt) with a fresh perspective, not the\n    # builder's or fixer's working memory.\n    memory: review\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 — one `- [ ]` checkbox per reviewable item, grouped into chunks.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"D .gtd/REVIEW.md\":\n        to: idle\n        describe: >-\n          Delete `.gtd/REVIEW.md` outright to approve the whole cycle at once\n          and rest back at the start (**idle**).\n      \"M .gtd/REVIEW.md\":\n        to: review-deciding\n        describe: >-\n          Edit `.gtd/REVIEW.md` — tick a `- [ ]` box to `- [x]` to approve that\n          item, or add notes — to hand it to a deterministic check\n          (**review-deciding**) that closes the cycle out when every box is\n          ticked, or extracts the still-unticked items into a fresh\n          `.gtd/TODO.md` and loops back through **grilling** with that feedback.\n      \"* **\":\n        to: grilling\n        describe: >-\n          Change only code, leaving `.gtd/REVIEW.md` untouched, to send that as\n          feedback straight back to **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-validation-command.md for the `gtd validate`\n# self-validation model that replaced the old in-machine validation loops).\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 — 10 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 rather than guessing silently. Its\n#     `file:`/`mode:` (TODO.md/`qa`) makes the plan's format checkable — it\n#     self-validates before finishing (see \"Steering-file validation\" below).\n#   grilling -> 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, grouping the cycle's full diff into\n#     reviewable chunks; its `file:`/`mode:` (REVIEW.md/`review`) makes that\n#     format checkable, so it self-validates before finishing.\n#   reviewing -> 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; REVIEW.md by the review-deciding approval branch; TODO.md by\n# `building`.\n#\n# Steering-file validation. `grilling` and `reviewing` each declare a\n# `file:`/`mode:` pair (TODO.md as `qa`, REVIEW.md as `review`), so their\n# output has a checkable format. src/OpenQuestions.ts and src/ReviewDoc.ts are\n# those two formats' EXECUTABLE SPECS (their unit tests are the format spec\n# tests), and `gtd validate` FORMATS the resolved state's rendered `file:` in\n# place then runs the SAME parser over it, exiting non-zero with findings when\n# it violates the format. There is no in-machine validation state and no bash\n# port to keep in sync — the producing agent self-validates before finishing\n# (plain `gtd next` appends the \"run `gtd validate` and fix all violations\"\n# instruction; under `--json` the driving loop runs it after the turn and\n# re-prompts on findings — see skills/loop/SKILL.md), AND `gtd step` runs the\n# same format-and-validate gate on capture, refusing a turn whose steering file\n# is invalid. So the check runs after a human edits too — at the human gates\n# `grilling-answer` (TODO.md) and `await-review` (REVIEW.md) — and a human gate\n# is only ever handed a tidy, well-formed file. The same parsers back the LSP's\n# live diagnostics (src/Lsp.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# The four agent states each declare a `memory:` scope label (`plan`,\n# `build`, `fix`, `review` — see the comment at `grilling` below) — another\n# opaque hint a memory-aware driver reads to decide when an agent turn keeps\n# the previous turn's memory and when it starts fresh: a loop that re-enters\n# one state (grilling around its answer loop, fixing around checking) keeps\n# the same label and retains memory across its laps; crossing to the next\n# phase's differently-labelled state clears it. gtd never interprets the\n# label (see STATES.md §1 and skills/loop/SKILL.md's driver contract).\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    # Every human-gate `message:` below closes with the SAME rendered block —\n    # a \"What each change does next\" list built from `it.edges`, the resting\n    # state's own `on` edges (see PatternTemplates.TemplateContext.edges). Each\n    # edge's human-readable route lives in its `describe:` (the single source\n    # of truth), so the list can never drift from the routing it documents.\n    # The block skips edges without a `describe`, and each `<%~ ... \"\\n\" %>`\n    # keeps the bullet's own newline (Eta's autoTrim strips the template's own\n    # line breaks around `<% %>` tags, not text inside an interpolation).\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.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save your sketch to `.gtd/TODO.md` (any working-tree change) to start\n          the cycle — the agent reads it, explores the codebase, and develops it\n          into a concrete implementation plan (**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    # `memory` is an opaque memory-scope label — gtd never interprets it, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so a\n    # memory-aware driving loop can decide when an agent turn continues from\n    # the previous turn's memory and when it starts fresh: consecutive agent\n    # turns that emit the SAME label share memory, a change (or the first\n    # turn) is where the driver starts fresh. `grilling` re-enters itself\n    # around the grilling-answer loop, so labelling every lap\n    # `plan` keeps the planner's accumulated exploration across the loop; the\n    # next phase (`building`) carries a different label, clearing it.\n    memory: plan\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.\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      \"* **\": 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. Answer a question by editing its entry in place: replace its\n      `Suggested default: ...` line with `Answer: ...`, or add further detail.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: building\n        describe: >-\n          Change nothing to accept every suggested default as-is and move on to\n          implementation (**building**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Edit the plan — answer a question, add detail, or raise a new one — to\n          send it back for another round of grilling (**grilling**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # A distinct memory scope from `plan`: implementation starts fresh, with\n    # the plan already settled in `.gtd/TODO.md` (which this prompt reads\n    # below) rather than carried in the planner's working memory.\n    memory: build\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    # Its own memory scope: the fix loop re-enters `fixing` around `checking`\n    # (up to the retry cap), so labelling every attempt `fix` lets the agent\n    # remember what it already tried across the loop; a green check moves on\n    # to the differently-labelled `reviewing`, clearing it.\n    memory: fix\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      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or `.gtd/FEEDBACK.md` —\n          to re-run the check (**checking**).\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: smart\n    # A distinct memory scope again: the reviewer looks at the cycle's full\n    # diff (inlined into its prompt) with a fresh perspective, not the\n    # builder's or fixer's working memory.\n    memory: review\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\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      \"* **\": 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 — one `- [ ]` checkbox per reviewable item, grouped into chunks.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"D .gtd/REVIEW.md\":\n        to: idle\n        describe: >-\n          Delete `.gtd/REVIEW.md` outright to approve the whole cycle at once\n          and rest back at the start (**idle**).\n      \"M .gtd/REVIEW.md\":\n        to: review-deciding\n        describe: >-\n          Edit `.gtd/REVIEW.md` — tick a `- [ ]` box to `- [x]` to approve that\n          item, or add notes — to hand it to a deterministic check\n          (**review-deciding**) that closes the cycle out when every box is\n          ticked, or extracts the still-unticked items into a fresh\n          `.gtd/TODO.md` and loops back through **grilling** with that feedback.\n      \"* **\":\n        to: grilling\n        describe: >-\n          Change only code, leaving `.gtd/REVIEW.md` untouched, to send that as\n          feedback straight back to **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;
@@ -364396,8 +364396,8 @@ const parseQuestionBlock = (block) => {
 * always returns a result, never throws. `errors` is non-empty exactly when
 * the document violates the required structure (a `###` question under
 * `## Open Questions` with no recognized response line) — the caller decides
-* what to do with that (the machine refuses the agent's turn capture; the
-* `gtd questions` CLI command just reports it alongside whatever parsed).
+* what to do with that (`gtd validate` exits non-zero with them; the LSP
+* publishes them as diagnostics).
 */
 const parseOpenQuestions = (content) => {
 	const lines = content.split(/\r?\n/);
@@ -364517,9 +364517,8 @@ const parseChangesets = (lines) => {
 * Parses the review structure out of `content` (the raw text of
 * `.gtd/REVIEW.md`). Total and side-effect-free: always returns a result,
 * never throws. `errors` is non-empty exactly when the document violates the
-* required structure — the caller decides what to do with that (the machine
-* refuses the agent's turn capture; the `gtd changesets` CLI command just
-* reports it alongside whatever parsed).
+* required structure — the caller decides what to do with that (`gtd validate`
+* exits non-zero with them; the LSP publishes them as diagnostics).
 */
 const parseReviewDoc = (content) => {
 	const lines = content.split(/\r?\n/);
@@ -364544,10 +364543,10 @@ const parseReviewDoc = (content) => {
 * LSP server for `.gtd/` steering files — document symbols for a `qa`-mode
 * file's open questions and a `review`-mode file's review chunks/hunks, code
 * actions to check/uncheck a hunk or a whole chunk, and diagnostics publishing
-* the same parsers' `errors` the bundled workflow's `.gtd/FORMAT.md`
-* validators produce (see `src/OpenQuestions.ts` / `src/ReviewDoc.ts`'s
-* module docs for the "executable spec ↔ bash validator" contract this server
-* rides on top of).
+* the same parsers' `errors` the `gtd validate` CLI command reports (see
+* `src/OpenQuestions.ts` / `src/ReviewDoc.ts`'s module docs — those parsers
+* are each format's single source of truth, shared by this server and the
+* command).
 *
 * CONFIG-DRIVEN (see `docs/design/state-file-association.md` §3): the server
 * locates the active gtd config the SAME way the CLI does (`ConfigService`'s
@@ -364613,7 +364612,7 @@ const questionSymbols = (content) => {
 		};
 	});
 };
-/** Diagnostics for `.gtd/TODO.md` — the same findings the workflow's `todo-validating` script would write to `.gtd/FORMAT.md`, published live over LSP instead. Whole-document range: `OpenQuestionsDoc.errors` carries no per-line position. */
+/** Diagnostics for `.gtd/TODO.md` — the same findings `gtd validate` reports for a `qa`-mode file, published live over LSP instead. Whole-document range: `OpenQuestionsDoc.errors` carries no per-line position. */
 const questionDiagnostics = (content) => {
 	const { errors } = parseOpenQuestions(content);
 	const lines = content.split(/\r?\n/);
@@ -364653,7 +364652,7 @@ const reviewSymbols = (content) => {
 		};
 	});
 };
-/** Diagnostics for `.gtd/REVIEW.md` — the same findings the workflow's `review-validating` script would write to `.gtd/FORMAT.md`, published live over LSP instead. Whole-document range: `ReviewDoc.errors` carries no per-line position. */
+/** Diagnostics for `.gtd/REVIEW.md` — the same findings `gtd validate` reports for a `review`-mode file, published live over LSP instead. Whole-document range: `ReviewDoc.errors` carries no per-line position. */
 const reviewDiagnostics = (content) => {
 	const { errors } = parseReviewDoc(content);
 	const lines = content.split(/\r?\n/);
@@ -364982,7 +364981,7 @@ const startLspServer = () => gen(function* () {
 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`,
+* to `_` (state names may carry hyphens — `grilling-answer`,
 * `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
@@ -365048,6 +365047,10 @@ 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)
+  validate         Validate the steering file the resolved rest declares
+                   (its file:/mode:) against that mode's format; exits
+                   non-zero with findings when the file violates it (no
+                   mutation)
   mermaid          Print the active workflow's shape as Mermaid
                    stateDiagram-v2 source (no mutation)
   format <file>    Format a markdown file in place
@@ -365204,7 +365207,9 @@ const stepAsActor = (invoker, cost, model) => gen(function* () {
 	const executable = decision;
 	const vars = resolveVars(config.workflowVars, config.rcVars, envVars.all);
 	const renderedState = decision.kind === "squash" ? decision.state : rest.state;
-	const outcome = yield* executeDecision(git, run, executable, yield* buildTemplateContext(git, worktree.read, renderedState, invoker, run, vars, rest.def.states[renderedState]?.on, cost ?? 0, model), cost, model);
+	const context = yield* buildTemplateContext(git, worktree.read, renderedState, invoker, run, vars, rest.def.states[renderedState]?.on, cost ?? 0, model);
+	yield* enforceSteeringGate(worktree.read, invoker, rest, context, decision.kind);
+	const outcome = yield* executeDecision(git, run, executable, context, cost, model);
 	return {
 		state: rest.state,
 		subject: outcome.kind === "noop" ? null : outcome.subject,
@@ -365230,23 +365235,128 @@ const runStepCommand = (argv, json, write, cost, model) => gen(function* () {
 	const result = yield* stepAsActor(args[0], cost, model);
 	reportStepResult(result, json, write);
 });
+/**
+* The self-validation instruction gtd APPENDS to a `prompt` rest that declares
+* both `file:` and `mode:` — i.e. a state whose actor hands over a steering
+* file `gtd validate` formats and checks. Appended ONLY to plain `gtd next`
+* output (for a human or a simple driver who reads the prompt and hands it to
+* an agent, so the agent self-validates); withheld from `gtd next --json`,
+* where the driving loop instead runs `gtd validate` after the turn and
+* re-prompts on findings (see `bin/gtd-loop` / `skills/loop/SKILL.md`). This is
+* advisory: `gtd step` runs the same format-and-validate gate and REFUSES a
+* turn whose steering file is invalid (see `stepAsActor`), so a malformed file
+* is never captured whether or not this instruction was followed.
+*/
+const selfValidateInstruction = (file) => `\nBefore finishing your turn, run \`gtd validate\` — it formats and checks ${file} — and fix every violation it reports until it exits cleanly. Do not finish while it still reports violations.\n`;
+/** True when a rendered rest is a `prompt` turn that hands over a validatable steering file (`file:`+`mode:` both declared). */
+const emitsValidatablePrompt = (rendered) => rendered.kind === "prompt" && rendered.file !== void 0 && rendered.mode !== void 0;
 /** `gtd next [--json]`: pure emitter of the resolved rest's rendered content (no mutation). */
+/** `gtd next --json`'s single-line object — omitting each optional key (never `null`-valued) when its source is unset, exactly like `gtd status --json`. */
+const nextJsonOutput = (rendered) => JSON.stringify({
+	state: rendered.state,
+	actor: rendered.actor,
+	kind: rendered.kind,
+	content: rendered.content,
+	...rendered.model !== void 0 ? { model: rendered.model } : {},
+	...rendered.memory !== void 0 ? { memory: rendered.memory } : {},
+	...rendered.file !== void 0 ? { file: rendered.file } : {},
+	...rendered.mode !== void 0 ? { mode: rendered.mode } : {},
+	...rendered.edges.length > 0 ? { edges: rendered.edges } : {}
+}) + "\n";
+/** `gtd next`'s plain-text output: the rendered content (newline-terminated), plus the self-validation instruction when the rest is a validatable prompt (see `emitsValidatablePrompt`). */
+const nextPlainOutput = (rendered) => {
+	const base = rendered.content.endsWith("\n") ? rendered.content : rendered.content + "\n";
+	return emitsValidatablePrompt(rendered) ? base + selfValidateInstruction(rendered.file) : base;
+};
 const runNextCommand = (json, write) => gen(function* () {
 	const git = yield* GitService;
 	const { rest, context } = yield* resolveRestContext(git);
 	const rendered = yield* renderRest(rest, context);
-	if (json) write(JSON.stringify({
-		state: rendered.state,
-		actor: rendered.actor,
-		kind: rendered.kind,
-		content: rendered.content,
-		...rendered.model !== void 0 ? { model: rendered.model } : {},
-		...rendered.memory !== void 0 ? { memory: rendered.memory } : {},
-		...rendered.file !== void 0 ? { file: rendered.file } : {},
-		...rendered.mode !== void 0 ? { mode: rendered.mode } : {},
-		...rendered.edges.length > 0 ? { edges: rendered.edges } : {}
-	}) + "\n");
-	else write(rendered.content.endsWith("\n") ? rendered.content : rendered.content + "\n");
+	write(json ? nextJsonOutput(rendered) : nextPlainOutput(rendered));
+});
+/** The parser findings for a steering file's content, dispatched on its `mode:`. */
+const validationErrorsFor = (mode, content) => mode === "qa" ? parseOpenQuestions(content).errors : parseReviewDoc(content).errors;
+const MARKDOWN_STEERING_RE = /\.(?:md|markdown)$/i;
+/**
+* Format the resolved rest's steering file in place, then validate its
+* formatted contents. When the state declares both `file:` and `mode:` and
+* that file exists in the working tree, it is formatted (markdown only) and
+* parsed against the `mode:` format. `present` is false — and nothing is
+* formatted or validated — when the state declares no steering file, or the
+* file is absent (e.g. `building` deleted `.gtd/TODO.md`, or a human deleted
+* `.gtd/REVIEW.md` to approve), so those flows pass cleanly. Shared by
+* `gtd validate` and the `gtd step` capture gate, so both format and check the
+* SAME way — an agent's fresh draft and a human's edit are treated alike.
+*/
+const formatAndCheckSteeringFile = (worktreeRead, stateDef, context) => gen(function* () {
+	const file = yield* renderFile(stateDef, context);
+	const mode = stateDef.mode;
+	if (file === void 0 || mode === void 0) return {
+		file,
+		present: false,
+		errors: []
+	};
+	if (!(yield* (yield* FileSystem).exists(file))) return {
+		file,
+		present: false,
+		errors: []
+	};
+	if (MARKDOWN_STEERING_RE.test(file)) yield* formatFile(file);
+	return {
+		file,
+		present: true,
+		errors: validationErrorsFor(mode, worktreeRead(file))
+	};
+});
+/**
+* The `gtd step` capture gate: format + validate the rest state's steering file
+* (see `formatAndCheckSteeringFile`) and FAIL with the findings when it is
+* invalid, so a malformed steering file — an agent's draft or a human's edit —
+* is never committed. A no-op when there is nothing to validate.
+*/
+const enforceSteeringGate = (worktreeRead, invoker, rest, context, kind) => gen(function* () {
+	if (kind !== "commit") return;
+	const gate = yield* formatAndCheckSteeringFile(worktreeRead, rest.stateDef, context);
+	if (gate.errors.length > 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd step ${invoker}: ${gate.file} is not valid at "${rest.state}" — fix these before stepping:\n${gate.errors.map((e) => `  - ${e}`).join("\n")}`));
+});
+/**
+* `gtd validate [--json]`: format (in place) then validate the steering file
+* the resolved rest declares (`file:` rendered, `mode:` selecting the parser),
+* over its WORKING-TREE contents. A state with no `file:`/`mode:`, or an absent
+* file, has nothing to validate (exit 0). A clean parse exits 0; violations
+* FAIL the Effect with the findings (one per line), so the process exits
+* non-zero — the signal a producing agent (or the driver) loops on until the
+* file is valid. Reuses the canonical `OpenQuestions`/`ReviewDoc` parsers (the
+* same the LSP publishes), so there is one source of truth per format and no
+* bash port.
+*/
+const runValidateCommand = (argv, json, write) => gen(function* () {
+	yield* rejectExtraArgs("validate", argv);
+	const git = yield* GitService;
+	const worktree = yield* WorktreeReader;
+	const { rest, context } = yield* resolveRestContext(git);
+	const { file, present, errors } = yield* formatAndCheckSteeringFile(worktree.read, rest.stateDef, context);
+	if (!present) {
+		if (json) write(JSON.stringify({
+			state: rest.state,
+			valid: true,
+			errors: []
+		}) + "\n");
+		else write(`nothing to validate at "${rest.state}"\n`);
+		return;
+	}
+	if (errors.length === 0) {
+		if (json) write(JSON.stringify({
+			state: rest.state,
+			file,
+			mode: rest.stateDef.mode,
+			valid: true,
+			errors: []
+		}) + "\n");
+		else write(`${file}: valid\n`);
+		return;
+	}
+	return yield* fail$2(/* @__PURE__ */ new Error(`${file} is not valid:\n${errors.map((e) => `  - ${e}`).join("\n")}`));
 });
 /**
 * `gtd run`: the built-in driver for a `script`-content rest. Renders the
@@ -365363,6 +365473,7 @@ const KNOWN_SUBCOMMANDS = [
 	"next",
 	"run",
 	"status",
+	"validate",
 	"mermaid"
 ];
 /**
@@ -365413,6 +365524,7 @@ const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 		case "next": return runNextCommand(json, write);
 		case "run": return runRunCommand(argv, json, write);
 		case "status": return runStatusCommand(argv, json, write);
+		case "validate": return runValidateCommand(argv, json, write);
 		case "mermaid": return runMermaidCommand(argv, json, write);
 	}
 };

package/docs/cli.md

@@ -16,6 +16,10 @@ 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)
+  validate         Validate the steering file the resolved rest declares
+                   (its file:/mode:) against that mode's format; exits
+                   non-zero with findings when the file violates it (no
+                   mutation)
   mermaid          Print the active workflow's shape as Mermaid
                    stateDiagram-v2 source (no mutation)
   format <file>    Format a markdown file in place
@@ -226,6 +230,43 @@ when the state has no `on` (all omitted entirely, never `null`, otherwise):
 
 `gtd status` takes no arguments — extra positional args are rejected.
 
+## `gtd validate [--json]`
+
+Format **and** validate the steering file the resolved rest declares. It
+resolves the current state exactly like `gtd status`, renders that state's
+`file:`, **formats that file in place** (the same markdown formatter as
+`gtd format`), then runs the parser its `mode:` selects over the formatted
+contents — `qa` → `src/OpenQuestions.ts`, `review` → `src/ReviewDoc.ts` (the
+same pure parsers the LSP publishes as diagnostics, so there is one source of
+truth per format).
+
+- A well-formed file exits `0` (`<file>: valid`, or `{"valid":true, ...}` with
+  `--json`) — and is left formatted.
+- Violations exit **non-zero** with the findings, one per line — the signal a
+  producing agent, or the driving loop, loops on until the file is well-formed.
+- A state that declares no `file:`/`mode:`, or whose file is **absent** (e.g.
+  `building` deleted `.gtd/TODO.md`, or a human deleted `.gtd/REVIEW.md` to
+  approve), has nothing to validate and exits `0`
+  (`nothing to validate at "<state>"`). Nothing is formatted in that case.
+
+This is how the bundled default keeps its steering files tidy and well-formed
+without an in-machine validation state — and the check runs whoever last touched
+the file, agent or human:
+
+- **The producing agent self-validates.** Plain `gtd next` appends a "run
+  `gtd validate` and fix all violations" instruction to a `prompt` rest that
+  declares `file:`+`mode:`; `gtd next --json` withholds it and the driving loop
+  runs `gtd validate` after the turn instead (see `bin/gtd-loop` /
+  [STATES.md §12](../STATES.md#12-steering-file-validation-gtd-validate)).
+- **`gtd step` enforces the same gate.** Capturing a turn out of a state that
+  declares `file:`+`mode:` formats that file in place and validates it first,
+  and **refuses the step** (committing nothing) when it is invalid — so a
+  human's edit at a gate (answering at `grilling-answer`, reviewing at
+  `await-review`) is formatted and checked exactly like an agent's draft, and a
+  malformed steering file is never committed.
+
+`gtd validate` takes no arguments.
+
 ## `gtd mermaid`
 
 Pure emitter of the active workflow's **shape** — not the resolved rest — as
@@ -260,7 +301,7 @@ Mermaid-aware renderer (GitHub, GitLab, VS Code, Obsidian, the
 
 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
+declaration up front, so a hyphenated name like `grilling-answer` 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
@@ -288,10 +329,9 @@ Errors (all exit 1, message on stderr):
 Starts an LSP server over stdio for `.gtd/` steering files — document symbols
 for a `qa`-mode file's open questions and a `review`-mode file's review
 chunks/hunks, code actions to check/uncheck a hunk or a whole chunk, and
-diagnostics publishing the same parser findings the bundled workflow's
-`.gtd/FORMAT.md` validators produce (see `src/OpenQuestions.ts` /
-`src/ReviewDoc.ts` and
-[STATES.md §10](../STATES.md#10-the-bundled-default-workflow)).
+diagnostics publishing the same parser findings `gtd validate` reports (see
+`src/OpenQuestions.ts` / `src/ReviewDoc.ts` and
+[STATES.md §12](../STATES.md#12-steering-file-validation-gtd-validate)).
 
 **Config-driven** (see
 [docs/design/state-file-association.md](design/state-file-association.md)): the

package/docs/design/state-file-association.md

@@ -45,14 +45,14 @@ vars:
   feedbackFile: .gtd/FEEDBACK.md
 ```
 
-Per-state mapping (12 states):
+Per-state mapping (10 states):
 
-| States                                                              | `file:`                       | `mode:`                   |
-| ------------------------------------------------------------------- | ----------------------------- | ------------------------- |
-| `grilling`, `todo-validating`, `grilling-answer`, `building`        | `<%= it.vars.todoFile %>`     | `qa`                      |
-| `reviewing`, `review-validating`, `await-review`, `review-deciding` | `<%= it.vars.reviewFile %>`   | `review`                  |
-| `fixing`, `escalate`                                                | `<%= it.vars.feedbackFile %>` | — (plain text, no format) |
-| `idle`, `checking`                                                  | —                             | —                         |
+| States                                         | `file:`                       | `mode:`                   |
+| ---------------------------------------------- | ----------------------------- | ------------------------- |
+| `grilling`, `grilling-answer`, `building`      | `<%= it.vars.todoFile %>`     | `qa`                      |
+| `reviewing`, `await-review`, `review-deciding` | `<%= it.vars.reviewFile %>`   | `review`                  |
+| `fixing`, `escalate`                           | `<%= it.vars.feedbackFile %>` | — (plain text, no format) |
+| `idle`, `checking`                             | —                             | —                         |
 
 Prompts and scripts that already name these files switch to the vars
 (`<%~ it.vars.todoFile %>` etc.) so each filename has ONE source of truth in
@@ -109,4 +109,5 @@ The advanced example (`docs/examples/advanced-workflow.md`) gains the same
 - Eta-rendering of `on` pattern keys (the rename-switch story) — future work,
   noted in §2.
 - New LSP modes beyond `qa`/`review` — the vocabulary can grow with new formats;
-  adding one means: parser (spec), validator recipe, LSP dispatch arm, docs.
+  adding one means: parser (spec), a `gtd validate` dispatch arm for the mode,
+  LSP dispatch arm, docs.

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

@@ -51,7 +51,7 @@ Each of these passes today's validation:
    `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
+   `{"* **": a, "A .gtd/FEEDBACK.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
@@ -400,7 +400,7 @@ the definition) — they fit `PatternMachine.step`'s purity discipline.
 - **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
+  `M src/x.ts` but this state only matches `A .gtd/FEEDBACK.md`" turns the most
   common custom-workflow dead end from a mystery into a diff-vs-pattern
   diagnosis the user can act on immediately.
 

package/docs/design/steering-file-loops.md

@@ -1,5 +1,16 @@
 # Plan: steering-file validation loops in the default workflow
 
+> SUPERSEDED (§2–§4): the in-machine validation-loop states this plan added —
+> `todo-validating` and `review-validating` — and their `.gtd/FORMAT.md`
+> steering file have all been DELETED. Deterministic format-checking now lives
+> in the `gtd validate` command (which runs the same pure `parseOpenQuestions` /
+> `parseReviewDoc` parsers the state's `mode:` selects) plus producing-agent
+> self-validation, rather than in bash-port `check`/`script` states. The default
+> workflow is now 10 states, not 12. See
+> [docs/design/steering-file-validation-command.md](steering-file-validation-command.md)
+> and [STATES.md §12](../STATES.md). §1 (the file formats) and §5 (the LSP
+> resurrection) below remain valid and current.
+
 > Status: §2–§4 (the two validation loops in the default workflow) AND §5 (the
 > LSP resurrection) both LANDED 2026-07-22. Goal: the bundled default workflow
 > completely maps the functionality the deleted v2 LSP server (`src/Lsp.ts`,

package/docs/design/steering-file-validation-command.md

@@ -0,0 +1,386 @@
+# Replacing the steering-file validation _states_ with a `gtd validate` command
+
+> Status: IMPLEMENTED. The authoritative reference is now
+> [STATES.md §12](../../STATES.md) (the model) and §10 (the 10-state bundled
+> default); this doc is the design record. Supersedes the two validation-loop
+> states in [steering-file-loops.md](steering-file-loops.md) §2–§4
+> (`todo-validating`, `review-validating`); everything else that doc describes
+> (the file formats §1, the LSP resurrection §5) stays.
+>
+> **As built — two decisions differ from the first draft of this plan:**
+>
+> 1. **No new state property.** A state is treated as "must hand over a valid
+>    file" purely by declaring both `file:` and `mode:` — there is no
+>    `validate:` flag and no `PatternMachine`/`PatternConfig`/`schema.json`
+>    change. This is the "Alternative considered" from §2.3, chosen for zero
+>    engine surface.
+> 2. **`gtd next --json` is unchanged.** It emits no new field (it already
+>    carries `file`/`mode`); the driver simply runs `gtd validate` after every
+>    agent turn (a no-op, exit 0, when the state has nothing to validate). Only
+>    plain `gtd next` changed — it appends the self-validation instruction to a
+>    `prompt` rest that declares `file:`+`mode:`.
+>
+> **Follow-up refinement (also built):**
+>
+> 3. **`gtd validate` also formats**, and the check runs after a human edits
+>    too. `gtd validate` now formats the steering file in place (the
+>    `gtd format` markdown formatter) before parsing it. And `gtd step` runs the
+>    SAME format-and-validate as a capture gate (`enforceSteeringGate` in
+>    `src/program.ts`): committing a turn out of a state that declares
+>    `file:`+`mode:` formats+validates that file and REFUSES the step when it is
+>    invalid. That makes the check apply to a human's edit at a gate
+>    (`grilling-answer`, `await-review`) exactly as to an agent's draft, and a
+>    malformed steering file is never committed. An absent file (a deletion —
+>    `building`'s TODO.md, an `await-review` delete-to-approve) is a no-op, so
+>    those flows still pass. `gtd validate`'s earlier "missing file read as
+>    empty" behavior is dropped in favor of "absent → nothing to validate".
+>
+> The sections below are the original plan; read §2.1–§3.2 through these
+> decisions (esp.: validate formats and is enforced at `gtd step`, and an absent
+> file is a no-op rather than parsed-as-empty).
+
+## 1. Motivation
+
+The bundled default workflow (`src/workflows/default.yaml`) currently carries
+two dedicated `check` states whose only job is to parse a steering file and
+bounce a malformed draft back to its authoring agent via a `.gtd/FORMAT.md`
+findings file:
+
+- `todo-validating` — validates `.gtd/TODO.md`'s open-questions format after
+  `grilling`, before the human answers at `grilling-answer`.
+- `review-validating` — validates `.gtd/REVIEW.md`'s checkbox format after
+  `reviewing`, before the human reviews at `await-review`.
+
+This is noise in the state machine:
+
+1. **2 of 12 states** exist only to re-derive a format check.
+2. **A hand-synced dual implementation.** Each validator is a `grep/awk` port of
+   `src/OpenQuestions.ts` / `src/ReviewDoc.ts` — an explicit "executable spec ↔
+   bash validator" contract kept in sync _by hand_, with no shared code path. A
+   whole class of drift bugs.
+3. **A third steering file** (`.gtd/FORMAT.md`) with its own lifecycle and
+   hygiene rules, plus "never touch FORMAT.md" / "fix FORMAT.md first" clauses
+   bolted onto the `grilling` and `reviewing` prompts.
+4. **Two extra commits on every happy-path cycle** (`gtd(check): …` turns that
+   only say "the format was fine").
+
+The core realization: the validation is redundant with tooling we already have.
+`src/OpenQuestions.ts` / `src/ReviewDoc.ts` are pure parsers, and `src/Lsp.ts`
+already publishes their `errors` as live editor diagnostics. What was missing
+was a way for the **producing agent** to run the same canonical check itself,
+mid-turn, so the human is only ever handed a _validated_ file.
+
+## 2. The design
+
+Validation stops being a **state** and becomes a **tool the producing agent uses
+before it finishes its turn** (or that the driver runs on the agent's behalf).
+No bash port, no `.gtd/FORMAT.md`, no extra states. The pure engine
+(`src/PatternMachine.ts`) never validates a steering file — as today, that stays
+out of scope for the engine (steering-file-loops.md §6). The only engine-shaped
+addition is one declarative state property that marks _which_ states must hand
+over a valid file (see §2.3).
+
+Three parts:
+
+### 2.1 A `gtd validate` command (current-state-scoped, canonical parsers)
+
+A new subcommand that resolves the current state exactly like `gtd status`,
+renders that state's `file:`, reads its working-tree contents, and runs the
+parser its `mode:` selects:
+
+- `mode: qa` → `parseOpenQuestions(content).errors`
+- `mode: review` → `parseReviewDoc(content).errors`
+
+Behavior:
+
+- **Nothing to validate** — the resolved state declares no `file:` **or** no
+  `mode:` → exit 0, report "nothing to validate at \"\<state\>\"".
+- **Valid** — the parser returns no `errors` → exit 0, report "\<file\>: valid".
+- **Invalid** — the parser returns `errors` → **fail the Effect** with the
+  findings (one per line, each prefixed with the rendered file path), which
+  makes `main.ts` print `gtd: …` to stderr and exit non-zero. This non-zero exit
+  is the whole point: the producing agent (or the driver) loops
+  `write → gtd validate → fix` until it exits 0.
+- A **missing** `file:` on disk is read as empty content (catch the read error,
+  treat as `""`), NOT as a hard error. For `qa` an empty/absent file is
+  trivially valid (no `## Open Questions` section); for `review` an empty file
+  fails the parser (no header, no chunks) — both are the correct outcomes.
+  Keeping validate purely a function of the parser over the file's content is
+  the crisp contract: **`gtd validate` fails ⟺ the file exists and violates its
+  format.**
+
+`--json` shape: on success
+`{ "state", "file"?, "mode"?, "valid": true, "errors": [] }`; on violations, the
+existing error envelope (`{ "state": "error", "prompt": "<findings>" }`) via
+`makeProgram`'s `--json` `catchAll` — consistent with how step refusals surface
+under `--json`.
+
+`gtd validate` takes no positional args (`rejectExtraArgs("validate", argv)`),
+accepts `--json`, and — like every state command — goes through the repo-root
+guard, auto-init, and the review-window close-first/re-arm-last bracketing.
+
+### 2.2 Conditional self-validation instruction on `gtd next` (THE key rule)
+
+The instruction that tells the agent to validate its own output is **not** a
+static line in the YAML prompt. gtd appends it **only in plain (non-JSON)
+`gtd next` output**; under `--json` it is withheld and the _driver_ owns the
+validate-and-retry loop — mirroring how the driver already owns turn
+orchestration.
+
+- **`gtd next` (plain text):** when the resolved rest is a state that must hand
+  over a valid file (see §2.3), append a standard block to the rendered prompt,
+  referencing the rendered `file:`, e.g.:
+
+  ```
+  <rendered prompt…>
+
+  Before finishing your turn, run `gtd validate` and fix every violation it
+  reports in <file> until it exits cleanly. Do not finish while it still
+  reports violations.
+  ```
+
+  This is for a human (or a simple driver) who reads `gtd next` and hands the
+  text to an agent: the agent self-validates.
+
+- **`gtd next --json`:** do **NOT** append the block. The `content` field stays
+  the clean rendered prompt. Instead emit the marker field `"validate": true`
+  (omitted when false — same discipline as `model`/`memory`/`file`/`mode`). The
+  driver reads this and, after the agent's turn but **before** `gtd step`, runs
+  `gtd validate`; on a non-zero exit it re-invokes the agent with the findings
+  and loops until `gtd validate` passes (subject to a cap — §2.5), then steps.
+  This is the JSON-mode equivalent of the appended self-instruction.
+
+The appended text is gtd-owned (a constant in `program.ts`); it references the
+already-rendered `rest.file`. It is emitted only by `runNextCommand`'s
+plain-text branch — `gtd run` drives _script_ states (the `check` actor), never
+prompt states, so it is unaffected.
+
+### 2.3 A `validate: true` state property (the marker)
+
+Add one optional boolean state property, `validate: true`, meaning: _the actor
+at this state must hand over a `file:` that passes `gtd validate` (per its
+`mode:`) before the turn is considered done._ Set it on `grilling` and
+`reviewing` in the bundled default.
+
+Why a dedicated property rather than keying off `mode:` presence: `building`
+also declares `mode: qa` but its job is to **delete** `.gtd/TODO.md`, not
+produce it — keying self-validation on `mode:` would wrongly target `building`.
+`validate: true` names exactly the producing states.
+
+Semantics / validation (in `validateDefinition`):
+
+- `validate: true` **requires** both `file:` and `mode:` on the same state
+  (there is nothing to validate without a file and a format).
+- **Forbidden on a commit state** (never at rest — same rule as
+  `reviewWindow`/`reviewBase`).
+- Engine never branches on it at step time; it is edge/emission-only data, read
+  by `renderRest`/`gtd next` and surfaced in `--json`.
+
+> **Alternative considered (no new property, lower engine risk):** skip
+> `validate: true`; in plain `gtd next` append the block to any `prompt` state
+> declaring `file:`+`mode:` (accepting a harmless no-op instruction on
+> `building`, whose deleted TODO validates as empty-valid), and have the driver
+> run `gtd validate` after _every_ agent turn (a no-op exit 0 whenever there is
+> nothing to validate). This removes all `PatternMachine`/`PatternConfig`/schema
+> changes. It is viable but less self-documenting (no `validate:true` in
+> `--json` or `gtd status`, and the `building` prompt carries an odd line).
+> **Recommended: the explicit property.** If the implementer prefers to avoid
+> engine changes, the alternative is acceptable — pick one and keep it
+> consistent across code, docs, and tests.
+
+## 3. Concrete change list
+
+### 3.1 New command — `src/program.ts`
+
+- Import `parseOpenQuestions` (`./OpenQuestions.js`) and `parseReviewDoc`
+  (`./ReviewDoc.js`); `WorktreeReader` is already imported.
+- Add `runValidateCommand(argv, json, write)`:
+  - `rejectExtraArgs("validate", argv)`.
+  - `git = yield* GitService`; `worktree = yield* WorktreeReader`.
+  - `{ rest, context } = yield* resolveRestContext(git)` (reuse the existing
+    helper — it builds the same context `gtd status`/`gtd next` use).
+  - `file = yield* renderFile(rest.stateDef, context)`;
+    `mode = rest.stateDef.mode`.
+  - No `file`/no `mode` → success "nothing to validate".
+  - Read `file` via `worktree.read`, catching a missing-file error into `""`.
+  - `errors = mode === "qa" ? parseOpenQuestions(content).errors : parseReviewDoc(content).errors`.
+  - Empty `errors` → success ("\<file\>: valid" / JSON `valid:true`).
+  - Non-empty →
+    `Effect.fail(new Error(<file> + " is not valid:\n" + errors.map(e => "  - " + e).join("\n")))`.
+- Add `"validate"` to `KNOWN_SUBCOMMANDS` and a `case "validate":` in
+  `dispatchKnownSubcommand`.
+- Add the appended-instruction constant and wire it into `runNextCommand`'s
+  **plain** branch only (append when `rendered` is a prompt state with the
+  `validate` marker and a defined `rendered.file`); in the `--json` branch add
+  `...(rendered.validate ? { validate: true } : {})` to the emitted object and
+  do NOT touch `content`.
+- Add the `validate` line to `HELP_TEXT`.
+
+Exit-code note: failing the Effect is the mechanism for non-zero exit (see
+`main.ts` `catchAll`). Findings land on stderr in plain mode, and under `prompt`
+in the `--json` error envelope.
+
+### 3.2 New state property — engine + compiler + emission
+
+- `src/PatternMachine.ts`: add `validate?: boolean` to `StateDef`; in
+  `validateDefinition` add the two rules from §2.3 (requires `file`+`mode`;
+  forbidden on commit states).
+- `src/PatternConfig.ts`: compile the `validate:` key (boolean; reject
+  non-boolean) in the per-state field compilers.
+- `src/Edge.ts`: add `validate?: boolean` to `RenderedRest`; set it in
+  `renderRest` (`...(rest.stateDef.validate ? { validate: true } : {})`).
+- `src/program.ts`: emit `validate` in `gtd next --json` (see §3.1) and,
+  optionally, in `gtd status --json` + a `Validate: yes` plain line for symmetry
+  with `model`/`memory`/`file`/`mode`.
+- `schema.json`: add the `validate` boolean to the per-state schema.
+
+### 3.3 `src/workflows/default.yaml`
+
+- **Delete** the `todo-validating` and `review-validating` states.
+- **Rewire**: `grilling.on: "* **": grilling-answer`;
+  `reviewing.on: "* **": await-review`.
+- **Mark**: add `validate: true` to `grilling` and `reviewing` (they already
+  declare `file:`+`mode:`).
+- **Prompts**: from `grilling` and `reviewing`, remove the `.gtd/FORMAT.md`
+  clauses ("If `.gtd/FORMAT.md` exists…", "Never touch `.gtd/FORMAT.md`…"). Do
+  NOT add a `gtd validate` line — gtd appends it in plain mode (§2.2). **Keep**
+  the embedded format spec (so drafts are born valid).
+- **Header comment**: 12 → 10 states; drop the `todo-validating`/
+  `review-validating` cycle-order lines and rewrite Loop 1 / Loop 2 to describe
+  self-validation via `gtd validate`; remove `.gtd/FORMAT.md` from the hygiene
+  invariant (it no longer exists); update the "dual-implementation contract"
+  paragraph (there is no bash port anymore — `OpenQuestions.ts`/`ReviewDoc.ts`
+  are the single source of truth, consumed by the LSP and `gtd validate`).
+
+Reachability after rewiring (assert mentally / via `validateDefinition`): all 10
+states reachable —
+`idle→grilling→grilling-answer→building→checking→(fixing| reviewing)`,
+`fixing↔checking`, `fixing→escalate→checking`,
+`reviewing→ await-review→(idle|review-deciding|grilling)`,
+`review-deciding→(grilling|idle| await-review)`.
+
+### 3.4 Driver contract — `skills/loop/SKILL.md` + `bin/gtd-loop`
+
+Teach the reference driver the `--json` half of §2.2:
+
+- After emitting an agent `prompt` turn whose `gtd next --json` carried
+  `"validate": true`, and after the agent has acted but **before**
+  `gtd step <actor>`, run `gtd validate`.
+- On a non-zero exit, re-invoke the agent with a fix instruction that includes
+  the `gtd validate` findings, then run `gtd validate` again. Loop until it
+  passes.
+- Cap the fix attempts (§2.5) and reuse the loop's existing no-progress / stall
+  handling to avoid spinning; surface a clear message on the cap.
+- Then `gtd step <actor>` as today.
+
+Document the same contract in `skills/loop/SKILL.md` (it is a genuine addition
+to the driver protocol — `dispatch on kind` + the new validate gate).
+
+### 3.5 Doc / comment sweep
+
+- **`STATES.md`**: §1 property table — add the `validate` row. §10 — table 12 →
+  10 states (drop the two validator rows; update `grilling`/`reviewing` `on`;
+  note `validate: true` on `grilling`/`reviewing`); rewrite the Loop 1 / Loop 2
+  walkthrough; drop `.gtd/FORMAT.md` from the hygiene invariant.
+- **`docs/cli.md`**: document `gtd validate` (and the `--json` shape).
+- **`docs/configuration.md`**: document the `validate:` property; remove the
+  FORMAT-loop description; keep the `file:`/`mode:` known-limitation.
+- **`docs/design/steering-file-loops.md`**: add a status banner at the top
+  pointing here and noting §2–§4's validator states were replaced by
+  `gtd validate` + the `validate:` marker (leave §1 formats and §5 LSP intact).
+- **`docs/upgrading.md`**, **`docs/development.md`**,
+  **`docs/design/state-file-association.md`**,
+  **`docs/design/state-machine-validation.md`**: replace `todo-validating`/
+  `review-validating`/`.gtd/FORMAT.md` references with the `gtd validate` model.
+- **`README.md`**: adjust the steering-file / editor-integration mention.
+- **`AGENTS.md`**: update the "Changing the Workflow" e2e feature list and the
+  "Scripted Check Actor" / dual-implementation notes to reflect that the bundled
+  default no longer ships the two validator states (the `check` actor still
+  exists for `checking`/`review-deciding`).
+- **`src/OpenQuestions.ts` / `src/ReviewDoc.ts`** docstrings: remove the
+  "executable spec ↔ bash validator contract" paragraph and the stale
+  `gtd questions` / `gtd changesets` command references; state they are now the
+  single source of truth consumed by the LSP (`src/Lsp.ts`) and `gtd validate`.
+- **`src/Lsp.ts`** docstrings: the two "same findings the workflow's
+  `todo-validating`/`review-validating` script would write to `.gtd/FORMAT.md`"
+  comments → reference `gtd validate` instead.
+
+### 3.6 Tests
+
+- **`tests/integration/features/smoke.feature`**: happy path becomes
+  `idle → grilling → grilling-answer → building → checking` (drop the
+  `todo-validating` hop and its `gtd step check`).
+- **`tests/integration/features/default-workflow.feature`**: major rewrite.
+  Remove the `.gtd/FORMAT.md` malformed-lap simulations from the main journey
+  and the two standalone "malformed … bounces back" scenarios (that machinery is
+  gone). New hops: `grilling → grilling-answer` and `reviewing → await-review`
+  directly. The `.gtd/FORMAT.md does not exist` hygiene assertion can stay
+  (trivially true); update the comment that attributed its cleanup to the
+  validators.
+- **`tests/integration/features/mermaid.feature`**: drop the
+  `state "todo-validating" as todo_validating` assertion (no longer a default
+  state); keep the rest.
+- **`src/Mermaid.test.ts`**: the hyphenated-name unit test uses
+  `"todo-validating"` as a _synthetic_ fixture name — fine to leave, it is not
+  the bundled default. The "renders the bundled default … covering every state"
+  test iterates actual states and needs no change.
+- **New `tests/integration/features/validate.feature` (@inmem)** — cucumber
+  scenarios for the new feature (per `AGENTS.md`: one scenario per feature,
+  composable `Given` steps, real file content in the scenario text). `@inmem` is
+  fine: `gtd validate` reads the working tree and runs a pure parser — no script
+  execution. Cover, with HEAD placed at the relevant state via
+  `a commit "gtd(<actor>): <state>" that adds …`:
+  - `grilling` + a valid `.gtd/TODO.md` → `gtd validate` succeeds, stdout
+    "valid".
+  - `grilling` + a malformed `.gtd/TODO.md` (an `### ` question with no
+    `Suggested default:`/`Answer:` line) → `gtd validate` fails, stderr carries
+    the finding.
+  - `reviewing` + a malformed `.gtd/REVIEW.md` (missing `# Review:` header) →
+    fails with the finding; a valid one → succeeds.
+  - a state with a `file:` but no `mode:` (e.g. `fixing`) → succeeds with
+    "nothing to validate".
+  - `gtd next` at `grilling` (plain) **contains** the appended validate
+    instruction; `gtd next --json` at `grilling` **does not** contain it in
+    `content` and **does** emit `"validate":true`.
+- **Optional (nice-to-have) `@live`**: a `gtd-loop`-style scenario proving the
+  driver runs `gtd validate` after a producing agent turn and re-runs the agent
+  on findings before stepping. If added, follow `gtd-loop.feature`'s stub-agent
+  pattern. May be deferred if the driver-contract change is landed with unit
+  coverage instead.
+
+### 3.7 No change needed
+
+- `stryker.config.json` — the parsers stay in the mutate list; nothing removed.
+- `src/PatternTemplates.ts` — the append happens in `program.ts`, not in
+  template rendering.
+
+## 4. Acceptance checklist
+
+- [ ] `gtd validate` exists, is current-state-scoped, exits non-zero with
+      findings on a malformed file and 0 otherwise; `--json` shape as in §2.1.
+- [ ] `gtd next` (plain) appends the self-validation instruction at
+      `grilling`/`reviewing`; `gtd next --json` withholds it and emits
+      `"validate": true`.
+- [ ] `validate:` property compiles, validates (requires `file`+`mode`,
+      forbidden on commit states), and is emitted in `--json`.
+- [ ] The bundled default is 10 states; `todo-validating`/`review-validating`/
+      `.gtd/FORMAT.md` are gone; an approved cycle still leaves `.gtd/` empty.
+- [ ] The reference driver runs `gtd validate` after a `validate:true` agent
+      turn and loops the agent on findings before stepping (capped).
+- [ ] `npm test` green; `npm run build` (single-file bundle) green; docs and
+      `AGENTS.md` updated. (Do NOT run `npm run test:mutation`.)
+
+## 5. Notes for the implementer
+
+- Keep CLI flags orthogonal (`AGENTS.md`): `gtd validate` accepts only `--json`;
+  reject unknown `--` options (the existing `unknownOption` guard already covers
+  this once `validate` is a known subcommand).
+- `gtd validate` resolves the CURRENT state — during a producing agent's turn,
+  HEAD still points at the commit that entered `grilling`/`reviewing` and the
+  agent's file is uncommitted in the working tree, so resolution +
+  `worktree.read` see exactly the right thing. No `gtd step` has happened yet.
+- The `file:`/`mode:` known-limitation (STATES.md §10, configuration.md) still
+  applies: `on` pattern keys are literal `.gtd/...` paths. `gtd validate` reads
+  the _rendered_ `file:`, so repointing `todoFile`/`reviewFile` via `vars:`
+  keeps validate correct even though the (now-removed) `on` FORMAT rows used to
+  desync.

package/docs/development.md

@@ -62,12 +62,14 @@ git/`.gtdrc` dependency at all and serves whatever content the editor hands it
 over the LSP protocol, exactly like any other document.
 
 `src/OpenQuestions.ts` and `src/ReviewDoc.ts` are the pure parsers behind both
-the LSP and the bundled default workflow's own bash validators
-(`todo-validating`/`review-validating` in `src/workflows/default.yaml`) — see
-[docs/design/steering-file-loops.md](design/steering-file-loops.md) for the
-"executable spec ↔ bash validator" contract linking the two independent
-implementations, and each module's own doc comment for the format it defines.
-Their unit tests are that format's spec tests.
+the LSP and the `gtd validate` command, which resolves the current state, reads
+its `file:`, and runs the parser its `mode:` selects (`qa` →
+`parseOpenQuestions`, `review` → `parseReviewDoc`) — ONE source of truth per
+format, no bash port and no dual-implementation contract to keep in sync. See
+[docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
+and [STATES.md §12](../STATES.md) for the command, and each module's own doc
+comment for the format it defines. Their unit tests are that format's spec
+tests.
 
 ## Mutation testing
 

package/docs/upgrading.md

@@ -61,15 +61,18 @@ upgrading.
   checkbox-only REVIEW.md diffs, and doc-structure validation are gone as ENGINE
   mechanisms — verdicts are now expressed purely by which file a turn writes or
   deletes, matched by an ordinary `on` pattern. The bundled default workflow's
-  own two validation loops (`todo-validating`/`review-validating`/
-  `review-deciding` — see
-  [docs/design/steering-file-loops.md](design/steering-file-loops.md)) rebuild
-  checkbox-review and doc-structure verdicts as ordinary WORKFLOW data
-  (`script`-content states + `on` patterns), not an engine hook: `D REVIEW.md` =
-  approve, `M REVIEW.md` = route to the deterministic decider, in the bundled
-  default.
-- **`gtd questions` / `gtd changesets` / `gtd review <target>`.** Gone; the v3
-  command surface is `step` / `next` / `run` / `status` / `format` / `lsp` (see
+  own checkbox-review verdict (`review-deciding`) is ordinary WORKFLOW data (an
+  `on` pattern), not an engine hook: `D REVIEW.md` = approve, `M REVIEW.md` =
+  route to the deterministic decider, in the bundled default. Deterministic
+  format-checking of the steering files is likewise no longer a pair of
+  in-machine `check`/`script` states — the old `todo-validating`/
+  `review-validating` states and their `.gtd/FORMAT.md` steering file are gone,
+  replaced by the `gtd validate` command plus producing-agent self-validation
+  (see
+  [docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
+  and [STATES.md §12](../STATES.md)).
+- **`gtd review <target>`.** Gone; the v3 command surface is `step` / `next` /
+  `run` / `status` / `format` / `validate` / `lsp` (see
   [CLI reference](cli.md)).
 - **Model tiers, the decision log.** No `models` config key, no `Gtd-Decisions`
   trailer scan, no grilling/architecting "prior decisions" context assembled

package/package.json

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