@pmelab/gtd 3.4.0 → 3.6.0

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;
@@ -191766,6 +191766,40 @@ const renderStateTemplate = (template, context) => eta.renderString(template, co
 */
 const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const subjectOf$1 = (message) => (message.split("\n")[0] ?? "").trim();
+const COST_TRAILER_PREFIX = "Gtd-Cost: ";
+const COST_TRAILER_RE = /^Gtd-Cost:[ \t]*([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+?))?[ \t]*$/gm;
+/** The bucket a cost with no `--model` tag is grouped under, kept distinct so a mixed history still totals correctly. */
+const UNATTRIBUTED_MODEL = "unspecified";
+/**
+* Append a `Gtd-Cost: <cost>[ <model>]` trailer (after a blank line) to a
+* commit `subject`, or return the subject unchanged when no cost was supplied.
+* The subject (first line) is never touched, so `parseStateSubject`/
+* `resolveState` still read `gtd(<actor>): <state>` back exactly as before.
+*/
+const withCostTrailer = (subject, cost, model) => cost === void 0 ? subject : `${subject}\n\n${COST_TRAILER_PREFIX}${cost}${model !== void 0 ? ` ${model}` : ""}`;
+/** Every `Gtd-Cost:` entry found across the given commit messages (each entry's model defaults to `UNATTRIBUTED_MODEL`). */
+const parseCostTrailers = (messages) => {
+	const entries = [];
+	for (const message of messages) for (const match of message.matchAll(COST_TRAILER_RE)) {
+		const model = match[2]?.trim();
+		entries.push({
+			cost: Number(match[1]),
+			model: model !== void 0 && model !== "" ? model : UNATTRIBUTED_MODEL
+		});
+	}
+	return entries;
+};
+/** The total token cost across the given entries (`0` when none). */
+const totalCostOf = (entries) => entries.reduce((sum, entry) => sum + entry.cost, 0);
+/** Per-model token totals, highest-cost first (ties broken by model name for a stable order). */
+const costByModel = (entries) => {
+	const byModel = /* @__PURE__ */ new Map();
+	for (const entry of entries) byModel.set(entry.model, (byModel.get(entry.model) ?? 0) + entry.cost);
+	return [...byModel.entries()].map(([model, cost]) => ({
+		model,
+		cost
+	})).sort((a, b) => b.cost - a.cost || a.model.localeCompare(b.model));
+};
 /** Collapse an arbitrary git status letter to the pattern grammar's closed `A|M|D` set (mirrors the plan's decision 5 — only those three are meaningful statuses). */
 const normalizeStatus = (raw) => raw === "A" ? "A" : raw === "D" ? "D" : "M";
 /** Resolve HEAD's subject against the active workflow definition (the bundled default, or a compiled `.gtdrc` `workflow:` key). */
@@ -191810,7 +191844,8 @@ const computeProcessRun = (git, def) => gen(function* () {
 	if (!(yield* git.hasCommits())) return {
 		startHash: "",
 		startParentHash: EMPTY_TREE$1,
-		trace: []
+		trace: [],
+		costEntries: []
 	};
 	const initialState = initialStateOf(def);
 	const history = yield* git.commitHistory();
@@ -191821,12 +191856,15 @@ const computeProcessRun = (git, def) => gen(function* () {
 		i--;
 	}
 	const startIdx = i + 1;
-	const trace = history.slice(startIdx).map((h) => parseStateSubject(subjectOf$1(h.message)).state);
+	const processCommits = history.slice(startIdx);
+	const trace = processCommits.map((h) => parseStateSubject(subjectOf$1(h.message)).state);
+	const costEntries = parseCostTrailers(processCommits.map((h) => h.message));
 	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE$1;
 	return {
 		startHash: startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash,
 		startParentHash,
-		trace
+		trace,
+		costEntries
 	};
 });
 /** The `GTD_VAR_`-prefix stripped, exact-case, from every matching entry — the highest-precedence `it.vars` layer. A `value === undefined` entry (a name declared-but-unset in the environment) is skipped, never coerced to the string `"undefined"`. */
@@ -191863,13 +191901,27 @@ const toTemplateEdges = (edges) => (edges ?? []).map(([pattern, target, describe
 	pattern,
 	target
 });
-/** Build the `PatternTemplates.TemplateContext` for rendering `state`'s content at the resolved rest. `vars` is the already-merged three-layer map (see `resolveVars`); `edges` is the resting state's own `on` edges (see `toTemplateEdges`). */
-const buildTemplateContext = (git, read, state, actor, run, vars, edges) => gen(function* () {
+/**
+* Build the `PatternTemplates.TemplateContext` for rendering `state`'s content
+* at the resolved rest. `vars` is the already-merged three-layer map (see
+* `resolveVars`); `edges` is the resting state's own `on` edges (see
+* `toTemplateEdges`). `currentCost`/`currentModel` are the in-flight step's own
+* `--cost`/`--model` (folded into the process's committed cost entries so a
+* `commit:` squash template sees the whole-process total AND per-model
+* breakdown including the squashing step) — `0`/absent for the pure emitters
+* (`gtd next`/`gtd status`), where no step is being performed.
+*/
+const buildTemplateContext = (git, read, state, actor, run, vars, edges, currentCost = 0, currentModel) => gen(function* () {
 	const hasCommits = yield* git.hasCommits();
 	const currentCommit = hasCommits ? yield* git.resolveRef("HEAD") : "";
 	const previousCommit = hasCommits ? yield* git.resolveRef("HEAD~1").pipe(catchAll(() => succeed$3(run.startParentHash))) : "";
 	const processDiff = [yield* git.diffRef(run.startParentHash).pipe(catchAll(() => succeed$3(""))), yield* git.diffHead().pipe(catchAll(() => succeed$3("")))].filter((d) => d.trim().length > 0).join("\n\n");
 	const lastDiff = run.trace.length > 0 ? yield* git.commitDiff(currentCommit).pipe(catchAll(() => succeed$3(""))) : "";
+	const stepEntry = currentCost > 0 || currentModel !== void 0 ? [{
+		cost: currentCost,
+		model: currentModel ?? "unspecified"
+	}] : [];
+	const allCostEntries = [...run.costEntries, ...stepEntry];
 	return {
 		startCommit: run.startHash,
 		currentCommit,
@@ -191878,6 +191930,8 @@ const buildTemplateContext = (git, read, state, actor, run, vars, edges) => gen(
 		actor,
 		processDiff,
 		lastDiff,
+		processCost: totalCostOf(allCostEntries),
+		processCostByModel: costByModel(allCostEntries),
 		read,
 		vars,
 		edges: toTemplateEdges(edges)
@@ -191945,18 +191999,22 @@ const renderRest = (rest, context) => gen(function* () {
 });
 /**
 * Execute a `PatternMachine.step` decision: a `"commit"` decision stages and
-* commits everything pending under the decided subject; a `"squash"`
-* decision renders the commit-state template against the PENDING tree — a
-* render failure REFUSES the step, touching nothing — then soft-resets to
-* the process's start parent, writes ONE commit with the rendered message
-* (via `commitAsIs`, so the still-uncommitted template file is excluded), and
-* discards everything left pending (the template file included). A `"noop"`
-* performs no IO.
-*/
-const executeDecision = (git, run, decision, context) => gen(function* () {
+* commits everything pending under the decided subject, with an optional
+* `Gtd-Cost: <cost>[ <model>]` trailer (the invocation's `--cost`/`--model`,
+* persisted in the git log); a `"squash"` decision renders the commit-state
+* template against the PENDING tree — a render failure REFUSES the step,
+* touching nothing — then soft-resets to the process's start parent, writes
+* ONE commit with the rendered message (via `commitAsIs`, so the
+* still-uncommitted template file is excluded), and discards everything left
+* pending (the template file included). A squash records no trailer of its own
+* — the whole-process total and per-model breakdown reach the message through
+* `it.processCost`/`it.processCostByModel` in the rendered template. A
+* `"noop"` performs no IO.
+*/
+const executeDecision = (git, run, decision, context, cost, model) => gen(function* () {
 	switch (decision.kind) {
 		case "commit":
-			yield* git.commitAllWithPrefix(decision.subject);
+			yield* git.commitAllWithPrefix(withCostTrailer(decision.subject, cost, model));
 			return {
 				kind: "commit",
 				subject: decision.subject
@@ -364338,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/);
@@ -364459,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/);
@@ -364486,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
@@ -364555,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/);
@@ -364595,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/);
@@ -364727,6 +364784,8 @@ const buildFileModeMap = (def, vars, root) => {
 				actor: "",
 				processDiff: "",
 				lastDiff: "",
+				processCost: 0,
+				processCostByModel: [],
 				read: (path) => {
 					throw new Error(`"file:" is not readable while building the path→mode map (path: ${path})`);
 				},
@@ -364922,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
@@ -364978,13 +365037,20 @@ const HELP_TEXT = `Usage: gtd [command] [options]
 Commands:
   step <actor>     Authenticate as <actor>, match the resolved rest's
                    declared patterns against the pending changes, and commit
-                   (or squash) the one resulting transition
+                   (or squash) the one resulting transition. Pass
+                   --cost=<n> (optionally --model=<name>) to record the
+                   just-finished invocation's token cost and model on the
+                   turn commit (summed into it.processCost/processCostByModel)
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   run              Execute the resolved rest's emitted script, then step its
                    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
@@ -364992,6 +365058,8 @@ Commands:
 
 Options:
   --json           Output structured JSON instead of plain text
+  --cost=<n>       (gtd step only) record the invocation's token cost
+  --model=<name>   (gtd step only, with --cost) tag that cost's model
   --version, -v    Print version and exit
   --help, -h       Print this help and exit
 `;
@@ -365007,6 +365075,58 @@ const markEnveloped = (error) => Object.assign(error, { [ENVELOPED]: true });
 const isEnveloped = (error) => typeof error === "object" && error !== null && error[ENVELOPED] === true;
 /** Non-flag positional arguments past the subcommand name (argv[3..]). */
 const commandArgs = (argv) => argv.slice(3).filter((a) => a.length > 0 && !a.startsWith("--"));
+const COST_FLAG = "--cost=";
+/**
+* Parse the optional `--cost=<n>` flag (only `gtd step` accepts it — see
+* `makeProgram`). `<n>` is the token cost of the invocation that produced the
+* pending changes, recorded as a `Gtd-Cost:` trailer on the turn commit. Must
+* be a non-negative finite number; a bare `--cost` (no `=`) or a non-numeric/
+* negative value is a usage error. Returns `undefined` when the flag is absent.
+*/
+const parseCostFlag = (argv) => {
+	if (argv.slice(2).includes("--cost")) return fail$2(/* @__PURE__ */ new Error("gtd: --cost requires a value — use --cost=<number>"));
+	const flag = argv.slice(2).find((a) => a.startsWith(COST_FLAG));
+	if (flag === void 0) return succeed$3(void 0);
+	const raw = flag.slice(7);
+	const n = Number(raw);
+	if (raw.trim() === "" || !Number.isFinite(n) || n < 0) return fail$2(/* @__PURE__ */ new Error(`gtd: --cost must be a non-negative number — got "${raw}"`));
+	return succeed$3(n);
+};
+const MODEL_FLAG = "--model=";
+/**
+* Parse the optional `--model=<name>` flag (only `gtd step`, and only
+* alongside `--cost` — see `makeProgram`). `<name>` tags the recorded cost
+* with the model the invocation ran on, appended to the `Gtd-Cost:` trailer
+* and grouped in `it.processCostByModel`. Must be non-empty and single-line
+* (it rides on one trailer line); a bare `--model` (no `=`) or an empty/
+* multiline value is a usage error. Returns `undefined` when the flag is absent.
+*/
+const parseModelFlag = (argv) => {
+	if (argv.slice(2).includes("--model")) return fail$2(/* @__PURE__ */ new Error("gtd: --model requires a value — use --model=<name>"));
+	const flag = argv.slice(2).find((a) => a.startsWith(MODEL_FLAG));
+	if (flag === void 0) return succeed$3(void 0);
+	const raw = flag.slice(8);
+	if (raw.trim() === "" || /[\r\n]/.test(raw)) return fail$2(/* @__PURE__ */ new Error("gtd: --model must be a non-empty, single-line value"));
+	return succeed$3(raw);
+};
+/**
+* Parse and validate the `--cost`/`--model` step flags together. Both are
+* orthogonal to `--json` but only meaningful to `gtd step` — rejected on any
+* other command rather than silently ignored (same discipline as `--json` on
+* `format`) — and `--model` requires `--cost` (a model tag with no token count
+* records nothing to sum).
+*/
+const parseStepFlags = (argv, positional) => gen(function* () {
+	const cost = yield* parseCostFlag(argv);
+	const model = yield* parseModelFlag(argv);
+	if (cost !== void 0 && positional !== "step") return yield* fail$2(/* @__PURE__ */ new Error("gtd: --cost is only valid for `gtd step`"));
+	if (model !== void 0 && positional !== "step") return yield* fail$2(/* @__PURE__ */ new Error("gtd: --model is only valid for `gtd step`"));
+	if (model !== void 0 && cost === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd: --model requires --cost — it tags the recorded cost with the model that ran"));
+	return {
+		cost,
+		model
+	};
+});
 /** Rejects extra positional arguments for a subcommand that takes none (`status`, `run`). */
 const rejectExtraArgs = (command, argv) => {
 	const args = commandArgs(argv);
@@ -365055,6 +365175,8 @@ const resolveRestContext = (git) => gen(function* () {
 		context: yield* buildTemplateContext(git, worktree.read, rest.state, rest.actor, run, vars, rest.stateDef.on)
 	};
 });
+/** The user-facing message for a `step` refusal — out-of-turn names the awaited actor, no-match names every declared pattern. */
+const formatStepRefusal = (invoker, refusal) => refusal.reason === "out-of-turn" ? `gtd step ${invoker}: out of turn — "${refusal.state}" awaits ${refusal.awaits}` : `gtd step ${invoker}: no declared pattern matches the pending changes at "${refusal.state}" — declared patterns: ${refusal.patterns.length > 0 ? refusal.patterns.join(", ") : "(none)"}`;
 /**
 * Authenticate `invoker` against the resolved rest and perform the one
 * resulting transition (commit or squash), shared by `gtd step` and
@@ -365063,7 +365185,7 @@ const resolveRestContext = (git) => gen(function* () {
 * `subject: null` rather than failing (exit zero, per the plan's "clean
 * no-op exits zero").
 */
-const stepAsActor = (invoker) => gen(function* () {
+const stepAsActor = (invoker, cost, model) => gen(function* () {
 	const git = yield* GitService;
 	const config = yield* ConfigService;
 	const worktree = yield* WorktreeReader;
@@ -365075,56 +365197,166 @@ const stepAsActor = (invoker) => gen(function* () {
 		changes,
 		processTrace: run.trace
 	});
-	if (decision.kind === "refusal") {
-		const message = decision.reason === "out-of-turn" ? `gtd step ${invoker}: out of turn — "${decision.state}" awaits ${decision.awaits}` : `gtd step ${invoker}: no declared pattern matches the pending changes at "${decision.state}" — declared patterns: ${decision.patterns.length > 0 ? decision.patterns.join(", ") : "(none)"}`;
-		return yield* fail$2(new Error(message));
-	}
+	if (decision.kind === "refusal") return yield* fail$2(new Error(formatStepRefusal(invoker, decision)));
 	if (decision.kind === "noop") return {
 		state: decision.state,
-		subject: null
+		subject: null,
+		cost: null,
+		model: null
 	};
 	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));
+	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
+		subject: outcome.kind === "noop" ? null : outcome.subject,
+		cost: cost ?? null,
+		model: model ?? null
 	};
 });
 /** Renders `stepAsActor`'s result the same way for both `gtd step` and `gtd run`. */
 const reportStepResult = (result, json, write) => {
 	if (json) write(JSON.stringify({
 		state: result.state,
-		subject: result.subject
+		subject: result.subject,
+		...result.cost !== null ? { cost: result.cost } : {},
+		...result.model !== null ? { model: result.model } : {}
 	}) + "\n");
 	else write(result.subject !== null ? `committed: ${result.subject}\n` : `nothing to do at "${result.state}"\n`);
 };
-/** `gtd step <actor>`: authenticate as `<actor>` and perform the one resulting transition. */
-const runStepCommand = (argv, json, write) => gen(function* () {
+/** `gtd step <actor> [--cost=<n>] [--model=<name>]`: authenticate as `<actor>` and perform the one resulting transition, recording `--cost`/`--model` as a `Gtd-Cost:` trailer. */
+const runStepCommand = (argv, json, write, cost, model) => gen(function* () {
 	const args = commandArgs(argv);
 	if (args.length === 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd step: missing actor argument"));
 	if (args.length > 1) return yield* fail$2(/* @__PURE__ */ new Error(`gtd step: too many arguments — expected one actor, got: ${args.join(", ")}`));
-	const result = yield* stepAsActor(args[0]);
+	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
@@ -365164,8 +365396,21 @@ const computeStatusChanges = (onEdges, changes) => changes.map((change) => {
 		pattern: matchedRow?.[0] ?? null
 	};
 });
-/** `gtd status --json`'s emission — `{state, actor, changes, model?, memory?, file?, mode?}`. */
-const writeStatusJson = (write, rest, statusChanges, model, memory, file) => {
+/**
+* True when the per-model breakdown adds information beyond the `Cost:` total:
+* more than one model, or a single model that carries an actual `--model` tag
+* (a lone `unspecified` bucket just restates the total, so it's suppressed).
+*/
+const breakdownIsInformative = (byModel) => byModel.length > 1 || byModel.length === 1 && byModel[0].model !== "unspecified";
+/** The plain-text `Cost:` line(s) for `gtd status` — empty when nothing recorded, plus an indented per-model split when informative. */
+const costStatusLines = (cost, byModel) => {
+	if (cost <= 0) return [];
+	const lines = [`Cost: ${cost}`];
+	if (breakdownIsInformative(byModel)) for (const m of byModel) lines.push(`  ${m.model}: ${m.cost}`);
+	return lines;
+};
+/** `gtd status --json`'s emission — `{state, actor, changes, model?, memory?, file?, mode?, cost?, costByModel?, edges?}`. */
+const writeStatusJson = (write, rest, statusChanges, model, memory, file, cost, costByModel) => {
 	const edges = toTemplateEdges(rest.stateDef.on);
 	write(JSON.stringify({
 		state: rest.state,
@@ -365175,16 +365420,19 @@ const writeStatusJson = (write, rest, statusChanges, model, memory, file) => {
 		...memory !== void 0 ? { memory } : {},
 		...file !== void 0 ? { file } : {},
 		...rest.stateDef.mode !== void 0 ? { mode: rest.stateDef.mode } : {},
+		...cost > 0 ? { cost } : {},
+		...cost > 0 ? { costByModel } : {},
 		...edges.length > 0 ? { edges } : {}
 	}) + "\n");
 };
-/** `gtd status`'s plain-text emission — `State:`/`Awaits:`/`Model:`/`Memory:`/`File:`/`Mode:`/`Pending:` lines. */
-const writeStatusPlain = (write, rest, statusChanges, model, memory, file) => {
+/** `gtd status`'s plain-text emission — `State:`/`Awaits:`/`Model:`/`Memory:`/`File:`/`Mode:`/`Cost:`/`Pending:` lines. */
+const writeStatusPlain = (write, rest, statusChanges, model, memory, file, cost, costByModel) => {
 	const lines = [`State: ${rest.state}`, `Awaits: ${rest.actor}`];
 	if (model !== void 0) lines.push(`Model: ${model}`);
 	if (memory !== void 0) lines.push(`Memory: ${memory}`);
 	if (file !== void 0) lines.push(`File: ${file}`);
 	if (rest.stateDef.mode !== void 0) lines.push(`Mode: ${rest.stateDef.mode}`);
+	lines.push(...costStatusLines(cost, costByModel));
 	if (statusChanges.length === 0) lines.push("Pending: (clean)");
 	else {
 		lines.push("Pending:");
@@ -365202,8 +365450,8 @@ const runStatusCommand = (argv, json, write) => gen(function* () {
 	const memory = yield* renderMemory(rest.stateDef, context);
 	const file = yield* renderFile(rest.stateDef, context);
 	const statusChanges = computeStatusChanges(rest.stateDef.on ?? [], changes);
-	if (json) writeStatusJson(write, rest, statusChanges, model, memory, file);
-	else writeStatusPlain(write, rest, statusChanges, model, memory, file);
+	if (json) writeStatusJson(write, rest, statusChanges, model, memory, file, context.processCost, context.processCostByModel);
+	else writeStatusPlain(write, rest, statusChanges, model, memory, file, context.processCost, context.processCostByModel);
 });
 /**
 * `gtd mermaid`: pure emitter of the active workflow's SHAPE (not the
@@ -365225,6 +365473,7 @@ const KNOWN_SUBCOMMANDS = [
 	"next",
 	"run",
 	"status",
+	"validate",
 	"mermaid"
 ];
 /**
@@ -365269,12 +365518,13 @@ const assertRunningFromRepoRoot = (git, fs) => gen(function* () {
 	if ((yield* fs.realPath(topLevel)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd must be run from the repository root (${topLevel}); the current directory is ${process.cwd()}`));
 });
 /** Dispatches to the named `run*Command` handler for every known subcommand. */
-const dispatchKnownSubcommand = (sub, argv, json, write) => {
+const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 	switch (sub) {
-		case "step": return runStepCommand(argv, json, write);
+		case "step": return runStepCommand(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);
 	}
 };
@@ -365299,8 +365549,9 @@ function makeProgram(opts = {}) {
 	const positional = argv.slice(2).find((a) => !a.startsWith("--"));
 	return gen(function* () {
 		if (runVersionOrHelp(argv, write)) return;
-		const unknownOption = argv.slice(2).find((a) => a.startsWith("--") && a !== "--json");
+		const unknownOption = argv.slice(2).find((a) => a.startsWith("--") && a !== "--json" && a !== "--cost" && a !== "--model" && !a.startsWith(COST_FLAG) && !a.startsWith(MODEL_FLAG));
 		if (unknownOption !== void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: unknown option '${unknownOption}' — see \`gtd --help\``));
+		const { cost, model } = yield* parseStepFlags(argv, positional);
 		if (positional === "format") return yield* runFormatCommand(argv, json);
 		if (positional === "lsp") return yield* runLspCommand(argv, json);
 		const sub = yield* requireKnownSubcommand(positional, json, write);
@@ -365309,7 +365560,7 @@ function makeProgram(opts = {}) {
 		yield* assertRunningFromRepoRoot(git, fs);
 		yield* closeReviewWindow;
 		yield* (yield* ConfigInit).ensure;
-		const outcome = yield* either(dispatchKnownSubcommand(sub, argv, json, write));
+		const outcome = yield* either(dispatchKnownSubcommand(sub, argv, json, write, cost, model));
 		const rearm = yield* either(openReviewWindow);
 		if (isLeft(outcome)) return yield* fail$2(outcome.left);
 		if (isLeft(rearm)) return yield* fail$2(rearm.left);