@pmelab/gtd 6.5.1 → 6.7.0

package/README.md

@@ -30,8 +30,9 @@ No chat scrollback. No lost sessions. No infinite fix loops. Just git.
 - **Bounded, not runaway.** Fix attempts are capped (`retry` on a state). When
   the cap is hit, gtd redirects to a human gate instead of burning tokens
   rewriting the same test for the 47th time.
-- **Your call on history.** Every intermediate `gtd(actor): state` commit is a
-  real, attributed commit — nothing hidden in chat. Squash them into one
+- **Your call on history.** Every intermediate `gtd(actor): from → to` commit is
+  a real, attributed commit — the subject names both the state the work was done
+  in and where it advanced to, nothing hidden in chat. Squash them into one
   conventional commit if you want that (an interactive rebase, an amend, a PR's
   squash-merge, or a custom workflow with a `commit:` finale), or don't — gtd
   makes no assumption.
@@ -57,9 +58,13 @@ gtd init simple      # or: gtd init advanced
 This writes a `.gtdrc.json` for the chosen workflow, with each agent state's
 prompt saved as an editable Markdown file under `gtd-prompts/` and referenced
 from the config (review and commit both). Edit a prompt by editing its
-`gtd-prompts/*.md` file — no config edit needed. gtd ships **no** default
-workflow: a state command run before `gtd init` fails, pointing you back here.
-See [Configuration](docs/configuration.md#gtd-init) for the two templates.
+`gtd-prompts/*.md` file — no config edit needed. It also seeds a top-level
+`modes:` block suggesting **Prettier** as the steering-file formatter
+(`npx prettier --write` for the built-in `qa`/`review` modes — format only, so
+gtd still validates); edit or drop it freely (swap in dprint, a script, or
+delete the key). gtd ships **no** default workflow: a state command run before
+`gtd init` fails, pointing you back here. See
+[Configuration](docs/configuration.md#gtd-init) for the two templates.
 
 ## How it works
 

package/dist/gtd.bundle.mjs

@@ -189107,27 +189107,46 @@ const isReviewBaseState = (def, state) => def.states[state]?.reviewBase === true
 const reviewEntryStateOf = (def) => {
 	for (const [name, state] of Object.entries(def.states)) if (state.reviewEntry === true) return name;
 };
-/**
-* `gtd(<actor>): <state>` — the subject a step commit carries. Per decision
-* 2, `<actor>` is WHO AUTHORED THE STEP (the invoker), and `<state>` is the
-* state being ENTERED; `resolveState` reads back only the state name.
-*/
-const stateSubject = (actor, state) => `gtd(${actor}): ${state}`;
+/** The ` → ` that separates a transition subject's source state from its target. */
+const TRANSITION_SEP = " → ";
+/**
+* `gtd(<actor>): <from> → <to>` — the subject a step commit carries. Per
+* decision 2, `<actor>` is WHO AUTHORED THE STEP (the invoker); `<to>` is the
+* state being ENTERED and `<from>` the state the authored changes were made
+* in, so the subject reads as what this commit DID, not just where the machine
+* is headed. `from` is optional: when it is omitted or equals `to` (a
+* self-loop, or a manual entry like `gtd review` that has no meaningful
+* source), the subject collapses to the bare `gtd(<actor>): <to>` form.
+* `resolveState` reads back only `<to>` — the ` → ` prefix is human context.
+*/
+const stateSubject = (actor, to, from) => from === void 0 || from === to ? `gtd(${actor}): ${to}` : `gtd(${actor}): ${from}${TRANSITION_SEP}${to}`;
 const SUBJECT_RE = /^gtd\(([^()]+)\): (.+)$/;
 /**
-* Parse a raw commit subject as `gtd(<actor>): <state>`. Returns `undefined`
-* for anything else (non-gtd, malformed, or missing either half) — never
-* throws. Trims surrounding whitespace before matching.
+* Parse a raw commit subject as `gtd(<actor>): <from> → <to>` (or the bare
+* `gtd(<actor>): <to>` form). Returns `undefined` for anything else (non-gtd,
+* malformed, or missing either half) — never throws. Trims surrounding
+* whitespace before matching. `state` is always the ENTERED state (`<to>`, the
+* segment after the last ` → `); the pre-arrow segment, when present, is
+* surfaced as `from` for display but is never consulted by `resolveState`.
 */
 const parseStateSubject = (subject) => {
 	const match = SUBJECT_RE.exec(subject.trim());
 	if (match === null) return void 0;
 	const actor = match[1];
-	const state = match[2];
-	if (actor === void 0 || actor === "" || state === void 0 || state === "") return void 0;
+	const rest = match[2];
+	if (actor === void 0 || actor === "" || rest === void 0 || rest === "") return void 0;
+	const sepIndex = rest.lastIndexOf(TRANSITION_SEP);
+	if (sepIndex === -1) return {
+		actor,
+		state: rest
+	};
+	const from = rest.slice(0, sepIndex);
+	const state = rest.slice(sepIndex + 3);
+	if (from === "" || state === "") return void 0;
 	return {
 		actor,
-		state
+		state,
+		from
 	};
 };
 /**
@@ -189288,9 +189307,9 @@ const applyRetry = (def, target, trace, visited = /* @__PURE__ */ new Set()) =>
 * steps are the default, silent case. A match's target is retry-redirected
 * (`applyRetry`) before being classified: a commit-state target yields a
 * `"squash"` decision carrying its `commit` template verbatim; anything
-* else yields a `"commit"` decision naming the `gtd(<invoker>): <to>` subject
-* to write — `<invoker>` is who authored this step, per decision 2, not `to`'s
-* own declared actor (see `StepCommit`'s doc comment). Throws only on a
+* else yields a `"commit"` decision naming the `gtd(<invoker>): <from> → <to>`
+* subject to write — `<invoker>` is who authored this step, per decision 2, not
+* `to`'s own declared actor (see `StepCommit`'s doc comment). Throws only on a
 * structurally invalid call (an undefined
 * `state`, or a commit-state `state` — stepping AT a commit state is a
 * caller error: a commit state ends the process, `resolveState` never rests
@@ -189331,7 +189350,7 @@ const step = (def, state, invoker, payload) => {
 	if (targetDef.actor === void 0) throw new Error(`step: "${finalTarget}" is not a commit state but declares no actor`);
 	return {
 		kind: "commit",
-		subject: stateSubject(invoker, finalTarget),
+		subject: stateSubject(invoker, finalTarget, state),
 		actor: invoker,
 		from: state,
 		to: finalTarget
@@ -191370,7 +191389,7 @@ var WorktreeReader = class WorktreeReader extends Tag("WorktreeReader")() {
 var advanced_default = "# The \"advanced\" gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init advanced`. See\n# docs/examples/advanced-workflow.md for the full state-by-state walkthrough\n# and STATES.md §10 for how it relates to the \"simple\" template.\n#\n# This is the fuller machine: two-phase human-in-the-loop planning\n# (grilling ⇄ grilling-answer for the product plan, architecting ⇄\n# architecting-answer for the technical plan), task decomposition\n# (decompose → .gtd/tasks/), a deterministic per-task builder queue (picking →\n# building → checking/fixing), agent-prepared review (reviewing → await-review),\n# and a squash finale (squashing → done, a `commit:` state that collapses the\n# whole cycle into one commit whose message the agent authored in\n# .gtd/COMMIT_MSG.md).\n#\n# Every content string below is INLINE (no `./`-relative file references): the\n# bundled templates ship inside a single-file build (`dist/gtd.bundle.mjs`), so\n# their content must already be resolved at BUILD time rather than read from\n# disk at RUNTIME. `advanced.yaml` is imported as raw text (tsdown's `.yaml`\n# text loader / the vitest rawMd transform), so this module never touches the\n# filesystem.\n#\n# `gtd init advanced` DERIVES the scaffolded `.gtdrc.json` from this inline\n# source (src/workflows/templates.ts `renderInitScaffold`): each agent state's\n# `prompt:` below is written out as an editable `gtd-prompts/<state>.md` file\n# and the config value is rewritten to a `./gtd-prompts/<state>.md` reference\n# `compileWorkflowConfig` inlines back at load time. Human `message:`/check\n# `script:` bodies and the `done` `commit:` template stay inline in the config.\n# This YAML stays fully inline regardless — the split happens only at scaffold\n# time, on real disk.\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  reviewFile: .gtd/REVIEW.md\n  feedbackFile: .gtd/FEEDBACK.md\n  # The two model tiers every agent state draws from (see the model comment at\n  # `grilling` below). Both are opaque harness hints — repoint them here (or\n  # via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var) to\n  # change every state on that tier at once.\n  plannerModel: smart\n  coderModel: base\n\nstates:\n  idle:\n    actor: human\n    initial: true\n    message: |\n      No active gtd cycle.\n\n      To start one: write `.gtd/TODO.md` with a short sketch of what you want\n      built — a few sentences is enough — then run `gtd step human`.\n    on:\n      \"* **\": grilling\n\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # `model` is an opaque harness hint — gtd never interprets this string, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so the\n    # driving loop can map it onto whatever models its agent harness provides.\n    # Every agent state draws its tier from a `vars` model entry (see `vars:`\n    # above) so the tiers repoint in one place: `plannerModel` (default\n    # \"smart\") names the heavier tier for the one-shot planning/architecting/\n    # reviewing turns, `coderModel` (default \"base\") the tier for the\n    # decompose/build/fix/squash turns.\n    model: <%= it.vars.plannerModel %>\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state (plans, task specs, review records) — never create, edit, or\n      delete anything under `.gtd/` except `<%= it.vars.todoFile %>`, which\n      this prompt tells you to write.\n\n      `<%= it.vars.todoFile %>` holds the plan under development. Read it,\n      then develop it into a concrete, product-level plan in this one turn —\n      explore the codebase before asking anything, so every open question is\n      one the codebase genuinely cannot answer.\n\n      Scope: product and user-facing decisions only. Leave implementation\n      details (file/module structure, data models, tech-stack choices) for\n      the next phase (`.gtd/ARCHITECTURE.md`).\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading near the top, one `### <question>` sub-heading each, its body\n      your suggested answer in plain prose (always suggest one — the human\n      accepts it by leaving it untouched, or overrides it by editing it). Omit\n      the section entirely once there are none.\n\n      If `.gtd/TODO.md` already carries a `## Open Questions` section from a\n      previous lap, the human has now responded to that whole batch: fold every\n      one of those questions into the plan — the human's edit where they gave\n      one, your own suggestion where they left it untouched (an untouched\n      suggestion IS acceptance) — and MOVE each resolved `### <question>` block\n      down into a `## Answered Questions` section at the bottom. Raise any\n      genuinely new questions under `## Open Questions` at the top.\n\n      Leave `.gtd/TODO.md` uncommitted and finish your turn — do not commit,\n      and do not run `gtd step agent` yourself; the harness does 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      answer.\n\n      To answer a question, edit its body in place, then run\n      `gtd step human`; leave a suggestion untouched to accept it as-is. On the\n      next lap the agent folds every answered question into the plan and moves\n      it down to `## Answered Questions`.\n\n      To accept all suggested answers as-is and move on to technical\n      architecting, run `gtd step human` with no edits.\n    on:\n      \"C\": architecting\n      \"* **\": grilling\n\n  architecting:\n    actor: agent\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\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.architectureFile %>` and `<%= it.vars.todoFile %>`, which\n      this prompt tells you to write and delete respectively.\n\n      Read `<%= it.vars.todoFile %>` (the converged product plan) and\n      develop `<%= it.vars.architectureFile %>` from it in this one turn:\n      file/module structure, data models, library/tech-stack choices,\n      error-handling strategy — the *how*, building on the *what* already\n      settled. Do not re-open product-level decisions from\n      `<%= it.vars.todoFile %>`; treat them as settled.\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading the same way as the grilling phase (one `### <question>`\n      sub-heading, its body your suggested answer in plain prose). Omit the\n      section once there are none. On a return lap, fold the whole answered\n      batch into the plan and move each resolved `### <question>` block down\n      into a `## Answered Questions` section at the bottom, exactly as grilling\n      does.\n\n      Once `<%= it.vars.architectureFile %>` is written, delete\n      `<%= it.vars.todoFile %>` — its content has been folded in and it must\n      not linger.\n\n      Leave everything uncommitted and finish your turn.\n    on:\n      \"* **\": architecting-answer\n\n  architecting-answer:\n    actor: human\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.architectureFile %>` holds the technical plan under\n      development, with any open questions under `## Open Questions`.\n\n      To answer a question, edit its body in place, then run `gtd step human`;\n      leave a suggestion untouched to accept it as-is.\n\n      To accept all suggested answers as-is and move on to decomposing the\n      work, run `gtd step human` with no edits.\n    on:\n      \"C\": decompose\n      \"* **\": architecting\n\n  decompose:\n    actor: agent\n    model: <%= it.vars.coderModel %>\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 the\n      task-spec files this prompt tells you to write (under `.gtd/tasks/`),\n      and `.gtd/ARCHITECTURE.md`, which it tells you to delete.\n\n      Read `.gtd/ARCHITECTURE.md` (the converged technical plan) and\n      decompose it into an ordered set of self-contained task files under\n      `.gtd/tasks/` (e.g. `.gtd/tasks/01-short-name.md`,\n      `.gtd/tasks/02-short-name.md`, ...). Order them so the test suite can\n      pass again after each one lands; each file is self-contained\n      (description, acceptance criteria as `- [ ]` checkboxes, relevant\n      paths) since a building turn receives only that one file as context.\n\n      No task file may reference any other `.gtd/` file, or a requirement to\n      preserve/update workflow state — `.gtd/` is machine-managed and gets\n      cleaned up as the cycle proceeds.\n\n      Once the task files are written, delete `.gtd/ARCHITECTURE.md`. Leave\n      everything uncommitted and finish your turn.\n    on:\n      \"* .gtd/tasks/**\": picking\n\n  picking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the queue arbiter) — the loop driver executes this\n      # verbatim, then steps the check actor. Mechanics only: take the\n      # first task file (by name) under .gtd/tasks/ into .gtd/NEXT.md, or\n      # remove .gtd/NEXT.md when the queue is empty. What NEXT.md's\n      # presence/absence MEANS (another task to build vs. the queue closing\n      # out to review) is decided by this state's own `on` rules at capture\n      # time — never here.\n      set +e\n      next=$(ls .gtd/tasks/*.md 2>/dev/null | head -n 1)\n      if [ -n \"$next\" ]; then\n        printf '%s' \"$next\" > .gtd/NEXT.md\n      else\n        rm -f .gtd/NEXT.md\n      fi\n    on:\n      \"D .gtd/NEXT.md\": reviewing\n      \"* .gtd/NEXT.md\": building\n      \"C\": reviewing\n\n  building:\n    actor: agent\n    model: <%= it.vars.coderModel %>\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 the\n      one task file this prompt tells you to delete; never touch\n      `.gtd/NEXT.md` yourself — the `picking` state owns it.\n\n      The task file to implement is: <%~ it.read(\".gtd/NEXT.md\") %>\n\n      Read that file and implement EXACTLY the one task it describes — no\n      more, no less; leave every other task file under `.gtd/tasks/`\n      untouched. Use TDD discipline: one test, then the implementation that\n      passes it, then the next — never write all the tests first.\n\n      Delete the task file once its work is complete and verified. Leave\n      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 loop driver executes this verbatim, then steps\n      # 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      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 .gtd/FEEDBACK.md\n        else\n          rm -f .gtd/.check-output\n          printf 'npm test failed with exit code %s and produced no output.' \"$code\" > .gtd/FEEDBACK.md\n        fi\n      else\n        rm -f .gtd/.check-output\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"C\": picking\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix\n      the code so the suite passes. Keep the change focused — do not\n      refactor unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue; the\n      machine picks the dispute up either way.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      Investigate and fix it yourself (editing code and/or\n      `<%= it.vars.feedbackFile %>`), then run `gtd step human` to try the\n      check again.\n    on:\n      \"* **\": checking\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: <%= it.vars.plannerModel %>\n    # A direct entry point: `gtd review <commitish>` starts a fresh review\n    # process here over `<commitish>..HEAD` (e.g. a colleague's PR branch).\n    reviewEntry: true\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): group hunks semantically (same\n      feature/refactor/fix, even across files), and for each group write a\n      short heading, an explanation of what changed and why, and\n      `- [ ] ./path/to/file.ts#42` style file pointers (checkboxes are for\n      the human to tick, not you).\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      \"* .gtd/REVIEW.md\": 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.\n\n      To approve: delete `<%= it.vars.reviewFile %>` and run\n      `gtd step human`.\n\n      To request changes: edit `<%= it.vars.reviewFile %>` (or the code)\n      with what's wrong — including just ticking its checkboxes — then run\n      `gtd step human`; this sends the cycle back through grilling with your\n      feedback as the new input.\n    on:\n      \"D .gtd/REVIEW.md\": squashing\n      \"* **\": grilling\n\n  squashing:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    prompt: |\n      You are an autonomous coding agent. The cycle is approved and done.\n      `.gtd/` holds this workflow's own state — never create, edit, or delete\n      anything under `.gtd/` except `.gtd/COMMIT_MSG.md`, which this prompt\n      tells you to write.\n\n      Write `.gtd/COMMIT_MSG.md` with ONE conventional-commits message for\n      the entire cycle (subject line `type(scope): subject`, imperative mood,\n      <= 72 characters; a body explaining the why, trade-offs, and key\n      decisions). Plain text, no markdown wrapper.\n\n      Leave `.gtd/COMMIT_MSG.md` uncommitted and finish your turn — entering\n      this file squashes the whole cycle into one commit using its content as\n      the message.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/COMMIT_MSG.md\": done\n      \"M .gtd/COMMIT_MSG.md\": done\n\n  done:\n    commit: |\n      <%~ it.read(\".gtd/COMMIT_MSG.md\") %>\n\n      Token cost: <%= it.processCost %>\n      <% it.processCostByModel.forEach(function(m){ %>\n      - <%= m.model %>: <%= m.cost %>\n      <% }) %>\n";
 //#endregion
 //#region src/workflows/simple.yaml
-var simple_default = "# The \"simple\" gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init simple`. gtd ships no default\n# workflow: a repo picks one of the bundled templates with `gtd init`, and a\n# state command run with no workflow configured fails (see src/Config.ts).\n# See STATES.md §10 for the walkthrough and docs/examples/advanced-workflow.md\n# for the fuller `advanced` template.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling).\n#\n# Every content string below is INLINE (no `./`-relative file references):\n# the bundled templates ship inside a single-file build\n# (`dist/gtd.bundle.mjs`), so their content must already be resolved at BUILD\n# time rather than read from disk at RUNTIME. `simple.yaml` itself is imported\n# as raw text (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# `gtd init simple` DERIVES the scaffolded `.gtdrc.json` from this inline\n# source (src/workflows/templates.ts `renderInitScaffold`): each agent state's\n# `prompt:` below is written out as an editable `gtd-prompts/<state>.md` file\n# and the config value is rewritten to a `./gtd-prompts/<state>.md` reference\n# `compileWorkflowConfig` inlines back at load time. Human `message:`/check\n# `script:` bodies stay inline in the config. This YAML stays fully inline\n# regardless — the split happens only at scaffold time, on real disk.\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): answer a question by\n#     editing its body in place, or leave a suggestion untouched to accept it;\n#     a clean step accepts every remaining suggestion -> building; any edit\n#     loops back to grilling (which folds the whole answered batch into the\n#     plan and moves it down to `## Answered Questions`).\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. `reviewing`\n#     ALSO declares `reviewEntry: true` — a second way in: `gtd review\n#     <commitish>` (a clean tree resting at idle) writes an empty\n#     `gtd(human): reviewing` entry commit carrying <commitish>'s hash as a\n#     `Gtd-Review-Base:` trailer, starting a brand new process that reviews\n#     <commitish>..HEAD (e.g. a colleague's PR branch) through this exact same\n#     reviewing/await-review/feedback-lap machinery.\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# Every agent state draws its `model` from a `vars` tier entry (see `vars:`\n# below and the comment at `grilling`) rather than a hardcoded string, so both\n# tiers repoint in one place: `plannerModel` (default \"smart\") for the heavier\n# one-shot planning/reviewing turns (`grilling`, `reviewing`), `coderModel`\n# (default \"base\") for the coding turns (`building`, `fixing`). Both are opaque\n# hints the driving loop maps onto its harness.\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  # The two model tiers every agent state draws from (see the model comment at\n  # `grilling` below). Both are opaque harness hints — repoint them here (or\n  # via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var) to\n  # change every state on that tier at once.\n  plannerModel: smart\n  coderModel: base\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 provides.\n    # Every agent state draws its tier from a `vars` model entry (see `vars:`\n    # above) so the tiers repoint in one place: `plannerModel` (default\n    # \"smart\") names the heavier tier for the one-shot planning/reviewing\n    # turns, `coderModel` (default \"base\") the tier for the coding turns.\n    model: <%= it.vars.plannerModel %>\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 near the top, one `### <question>`\n      sub-heading each, its body your suggested answer in plain prose (always\n      suggest one — the human accepts it by leaving it untouched, or overrides\n      it by editing it). Omit the section entirely once there are no open\n      questions.\n\n      If `<%= it.vars.todoFile %>` already carries a `## Open Questions`\n      section from a previous lap, the human has now responded to that whole\n      batch: fold every one of those questions into the plan — using the\n      human's edit where they gave one, your own suggested answer where they\n      left it untouched (an untouched suggestion IS acceptance) — and MOVE each\n      resolved `### <question>` block down into a `## Answered Questions`\n      section at the very bottom, keeping it as a record. Raise any genuinely\n      new questions this lap under `## Open Questions` at the top.\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      answer. Answer a question by editing its body in place; leave a\n      suggestion untouched to accept it as-is. On the next lap the agent folds\n      every answered question into the plan and moves it down to\n      `## Answered Questions`.\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 answer 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    model: <%= it.vars.coderModel %>\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 loop driver 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    model: <%= it.vars.coderModel %>\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: <%= it.vars.plannerModel %>\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    # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n    # enters here directly, recording the resolved base as a `Gtd-Review-Base:`\n    # trailer on its empty entry commit — everything below then reuses the\n    # existing reviewing/await-review/feedback-lap machinery unmodified over\n    # <commitish>..HEAD (see STATES.md §11).\n    reviewEntry: true\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 loop driver 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";
+var simple_default = "# The \"simple\" gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init simple`. gtd ships no default\n# workflow: a repo picks one of the bundled templates with `gtd init`, and a\n# state command run with no workflow configured fails (see src/Config.ts).\n# See STATES.md §10 for the walkthrough and docs/examples/advanced-workflow.md\n# for the fuller `advanced` template.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling).\n#\n# Every content string below is INLINE (no `./`-relative file references):\n# the bundled templates ship inside a single-file build\n# (`dist/gtd.bundle.mjs`), so their content must already be resolved at BUILD\n# time rather than read from disk at RUNTIME. `simple.yaml` itself is imported\n# as raw text (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# `gtd init simple` DERIVES the scaffolded `.gtdrc.json` from this inline\n# source (src/workflows/templates.ts `renderInitScaffold`): each agent state's\n# `prompt:` below is written out as an editable `gtd-prompts/<state>.md` file\n# and the config value is rewritten to a `./gtd-prompts/<state>.md` reference\n# `compileWorkflowConfig` inlines back at load time. Human `message:`/check\n# `script:` bodies stay inline in the config. This YAML stays fully inline\n# regardless — the split happens only at scaffold time, on real disk.\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): answer a question by\n#     editing its body in place, or leave a suggestion untouched to accept it;\n#     a clean step accepts every remaining suggestion -> building; any edit\n#     loops back to grilling (which folds the whole answered batch into the\n#     plan and moves it down to `## Answered Questions`).\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. `reviewing`\n#     ALSO declares `reviewEntry: true` — a second way in: `gtd review\n#     <commitish>` (a clean tree resting at idle) writes an empty\n#     `gtd(human): reviewing` entry commit carrying <commitish>'s hash as a\n#     `Gtd-Review-Base:` trailer, starting a brand new process that reviews\n#     <commitish>..HEAD (e.g. a colleague's PR branch) through this exact same\n#     reviewing/await-review/feedback-lap machinery.\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>): <from> → idle` commit — entering the workflow's own initial\n# state — 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# Every agent state draws its `model` from a `vars` tier entry (see `vars:`\n# below and the comment at `grilling`) rather than a hardcoded string, so both\n# tiers repoint in one place: `plannerModel` (default \"smart\") for the heavier\n# one-shot planning/reviewing turns (`grilling`, `reviewing`), `coderModel`\n# (default \"base\") for the coding turns (`building`, `fixing`). Both are opaque\n# hints the driving loop maps onto its harness.\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  # The two model tiers every agent state draws from (see the model comment at\n  # `grilling` below). Both are opaque harness hints — repoint them here (or\n  # via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var) to\n  # change every state on that tier at once.\n  plannerModel: smart\n  coderModel: base\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 provides.\n    # Every agent state draws its tier from a `vars` model entry (see `vars:`\n    # above) so the tiers repoint in one place: `plannerModel` (default\n    # \"smart\") names the heavier tier for the one-shot planning/reviewing\n    # turns, `coderModel` (default \"base\") the tier for the coding turns.\n    model: <%= it.vars.plannerModel %>\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 near the top, one `### <question>`\n      sub-heading each, its body your suggested answer in plain prose (always\n      suggest one — the human accepts it by leaving it untouched, or overrides\n      it by editing it). Omit the section entirely once there are no open\n      questions.\n\n      If `<%= it.vars.todoFile %>` already carries a `## Open Questions`\n      section from a previous lap, the human has now responded to that whole\n      batch: fold every one of those questions into the plan — using the\n      human's edit where they gave one, your own suggested answer where they\n      left it untouched (an untouched suggestion IS acceptance) — and MOVE each\n      resolved `### <question>` block down into a `## Answered Questions`\n      section at the very bottom, keeping it as a record. Raise any genuinely\n      new questions this lap under `## Open Questions` at the top.\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      answer. Answer a question by editing its body in place; leave a\n      suggestion untouched to accept it as-is. On the next lap the agent folds\n      every answered question into the plan and moves it down to\n      `## Answered Questions`.\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 answer 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    model: <%= it.vars.coderModel %>\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 loop driver 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    model: <%= it.vars.coderModel %>\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: <%= it.vars.plannerModel %>\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    # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n    # enters here directly, recording the resolved base as a `Gtd-Review-Base:`\n    # trailer on its empty entry commit — everything below then reuses the\n    # existing reviewing/await-review/feedback-lap machinery unmodified over\n    # <commitish>..HEAD (see STATES.md §11).\n    reviewEntry: true\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 loop driver 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";
 //#endregion
 //#region src/workflows/templates.ts
 /**
@@ -191388,6 +191407,27 @@ const SCHEMA_URL = "https://raw.githubusercontent.com/pmelab/gtd/main/schema.jso
 */
 const PROMPTS_DIR = "gtd-prompts";
 /**
+* The top-level `modes:` block `gtd init` SEEDS into the scaffolded
+* `.gtdrc.json` as a ready-to-edit suggestion: a `format:` command for each
+* built-in steering-file mode the bundled templates use (`qa` for the plan /
+* open-questions files, `review` for REVIEW.md), so a fresh project's steering
+* files are auto-formatted with Prettier before gtd validates them. Only
+* `format:` is declared — gtd's built-in `qa`/`review` validators still do the
+* validating (the two halves layer independently — see STATES.md §12 /
+* docs/configuration.md `modes:`). gtd ships no formatter, so this is the one
+* place a default is suggested; a project edits or drops it freely (swap
+* Prettier for dprint, point at a script, delete the key).
+*
+* Seeded only by `renderInitScaffold` (the real `gtd init` write path), NOT by
+* `renderInitConfig`: the latter is reused as a hermetic test fixture (the
+* `Given the "…" workflow` step) that must not depend on Prettier being
+* installed or spawn a subprocess at every steering-file gate.
+*/
+const MODES_SUGGESTION = {
+	qa: { format: "npx prettier --write <%= it.file %>" },
+	review: { format: "npx prettier --write <%= it.file %>" }
+};
+/**
 * The bundled workflow templates `gtd init <name>` can scaffold, keyed by the
 * name the user passes. Each value is the raw YAML text of the template file,
 * imported as a string (tsdown's `.yaml` text loader / the vitest `rawMd`
@@ -191414,6 +191454,12 @@ const isWorkflowTemplateName = (name) => Object.prototype.hasOwnProperty.call(WO
 * (they are workflow mechanics, not prompts). The bundled YAML template itself
 * stays fully inline (it ships inside the single-file bundle); this function is
 * the only place the split happens, at scaffold time.
+*
+* It also seeds a top-level `modes:` block (`MODES_SUGGESTION`) — a ready-to-
+* edit Prettier `format:` for the built-in `qa`/`review` steering-file modes —
+* so a fresh project auto-formats its steering files out of the box. This lives
+* here rather than in `renderInitConfig` so the latter stays a hermetic test
+* fixture (see `MODES_SUGGESTION`).
 */
 const renderInitScaffold = (name) => {
 	const workflow = (0, import_dist$1.parse)(WORKFLOW_TEMPLATES[name]);
@@ -191429,6 +191475,7 @@ const renderInitScaffold = (name) => {
 	return {
 		config: JSON.stringify({
 			$schema: SCHEMA_URL,
+			modes: MODES_SUGGESTION,
 			workflow
 		}, null, 2) + "\n",
 		prompts

package/docs/cli.md

@@ -116,7 +116,7 @@ to `--json`.
 Plain-mode output is one line:
 
 ```
-committed: gtd(human): grilling
+committed: gtd(human): idle → grilling
 ```
 
 or, at a no-op:
@@ -131,8 +131,8 @@ not passed):
 
 ```json
 {
-  "state": "grilling",
-  "subject": "gtd(human): grilling",
+  "state": "idle",
+  "subject": "gtd(human): idle → grilling",
   "cost": 1450,
   "model": "claude-opus-4-8"
 }

package/docs/configuration.md

@@ -371,8 +371,10 @@ So for a state declaring `mode: qa`:
 That is what makes the built-in modes extensible rather than all-or-nothing —
 and the top-level key means a project can plug its formatter into whichever
 workflow it scaffolded (`gtd init simple`/`advanced`) without re-declaring a
-`modes:` block on the workflow itself. Add it alongside the `workflow:` key in
-your `.gtdrc.json`:
+`modes:` block on the workflow itself. **`gtd init` seeds exactly this block by
+default** (the Prettier suggestion below), so a fresh repo already formats its
+steering files — edit or drop it to taste. It sits alongside the `workflow:` key
+in your `.gtdrc.json`:
 
 ```jsonc
 // .gtdrc.json — the workflow from `gtd init`, plus your own markdown formatter
@@ -496,11 +498,11 @@ A loop driver that knows how many tokens the invocation it just drove cost — a
 on which model — can record both with
 `gtd step <actor> --cost=<n> [--model=<name>]` (`<n>` a non-negative number).
 gtd appends them to that turn's commit as a `Gtd-Cost: <n> <model>` trailer — a
-blank line then the trailer, below the untouched `gtd(<actor>): <state>` subject
-— so the per-turn cost and model are persisted in the git log:
+blank line then the trailer, below the untouched `gtd(<actor>): <from> → <to>`
+subject — so the per-turn cost and model are persisted in the git log:
 
 ```
-gtd(agent): reviewing
+gtd(agent): building → reviewing
 
 Gtd-Cost: 1450 claude-opus-4-8
 ```
@@ -673,8 +675,26 @@ config references it via a `./gtd-prompts/<state>.md`
 [file reference](#content-values-inline-or-a-file-reference) — gtd inlines it at
 load time, so a prompt is editable Markdown and editing it changes the workflow
 with no config edit. Human `message:` blocks and check `script:` bodies stay
-inline in the config (they are workflow mechanics, not prompts). The two
-templates:
+inline in the config (they are workflow mechanics, not prompts).
+
+It also seeds a top-level [`modes:`](#modes--pluggable-steering-file-modes)
+block as a ready-to-edit suggestion — a Prettier `format:` for each built-in
+steering-file mode the templates use:
+
+```jsonc
+"modes": {
+  "qa": { "format": "npx prettier --write <%= it.file %>" },
+  "review": { "format": "npx prettier --write <%= it.file %>" }
+}
+```
+
+Only `format:` is declared, so gtd's built-in `qa`/`review` validators still do
+the validating (the two halves layer independently). gtd ships no formatter, so
+this is the one default it suggests: a fresh repo auto-formats its steering
+files out of the box, and you edit or drop the block freely (swap Prettier for
+dprint, point at a script, or delete the key).
+
+The two templates:
 
 - **`simple`** — the 10-state machine walked through in
   [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates): idle →

package/docs/upgrading.md

@@ -11,15 +11,15 @@ ordered map of change-patterns to next states.
 
 **All pre-v3 history is unrecognized and resolves to the initial state, by
 design — v1 and v2 subjects alike.** v3's `resolveState`
-(`src/PatternMachine.ts`) only recognizes its own `gtd(<actor>): <state>`
-subject naming a state and an actor the active workflow currently declares;
-everything else — a v1 `gtd: grilling`, a v2 `gtd(agent): building`, a plain
-`chore: …` commit, anything from a foreign repo — parses as unrecognized and
-lands at the workflow's initial state (`idle` in the `simple` template). There
-is no special-casing for "this looks like an old gtd commit": the mechanism is
-exactly the same one that already made v1 history inert to v2, and v2 history
-inert to a differently-configured workflow — v3 just applies it uniformly to all
-prior history instead of drawing a v1/v2 line.
+(`src/PatternMachine.ts`) only recognizes its own `gtd(<actor>): <from> → <to>`
+subject (or the bare `gtd(<actor>): <to>`) naming a state and an actor the
+active workflow currently declares; everything else — a v1 `gtd: grilling`, a v2
+`gtd(agent): building`, a plain `chore: …` commit, anything from a foreign repo
+— parses as unrecognized and lands at the workflow's initial state (`idle` in
+the `simple` template). There is no special-casing for "this looks like an old
+gtd commit": the mechanism is exactly the same one that already made v1 history
+inert to v2, and v2 history inert to a differently-configured workflow — v3 just
+applies it uniformly to all prior history instead of drawing a v1/v2 line.
 
 **Finish or squash any in-flight cycle first.** A repo mid-cycle on v1 or v2 has
 no v3-shaped commit backing its steering files; upgrading mid-cycle lands cold

package/package.json

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