@pmelab/gtd 6.12.0 → 6.14.0

package/README.md

@@ -88,6 +88,9 @@ Four commands drive it:
 - **`gtd review <commitish>`** — start a brand new review process reviewing
   `<commitish>..HEAD` (e.g. a colleague's PR branch), reusing the workflow's
   existing review/feedback machinery over that diff.
+- **`gtd fix`** — start a brand new process that goes straight into repairing
+  the current failing tests, then runs the shared review/squash tail (a no-op if
+  the suite is already green).
 
 `gtd version` (or `gtd --version`/`-v`) prints the installed version and exits;
 `gtd help` (or `gtd --help`/`-h`) prints the command list. Both short-circuit
@@ -101,16 +104,22 @@ never executes anything — the driver owns running scripts. See
 [STATES.md](STATES.md) for the model and [Driving the loop](docs/loop.md) for
 the full protocol.
 
-The unified workflow has **two entry points into one shared tail**, chosen by
-which steering file you create:
+The unified workflow has **entry points behind a green-baseline gate, into one
+shared tail**. Every entry first runs your test suite and only starts once it's
+green — you never build (or review) on top of a red baseline; a red run halts
+and tells you to repair it first (that's what `gtd fix` is for). The two
+steering-file entries are chosen by which file you create:
 
 - Create **`.gtd/TODO.md`** with a short sketch to start the **simple** flow: an
-  agent develops your sketch into a plan — asking any open question it can't
-  settle itself via a deterministic `.gtd/TODO.md` format, validated before it
-  ever reaches you — you answer inline, then it builds the plan in one turn and
+  agent develops your sketch into a concrete plan — deciding open points itself
+  rather than asking questions — and hands it back for you to accept as-is or
+  edit. Editing sends it round again; accepting builds the plan in one turn and
   runs your tests (looping on failures).
 - Create **`.gtd/REQUIREMENTS.md`** to start the **advanced** flow: two-phase
-  product then technical Q&A (`.gtd/REQUIREMENTS.md` → `.gtd/ARCHITECTURE.md`),
+  product then technical Q&A (`.gtd/REQUIREMENTS.md` → `.gtd/ARCHITECTURE.md`) —
+  each open question offers a couple of candidate answers plus a
+  `- [ ] _your answer_` slot, and you tick exactly one per question (the gate
+  won't let a phase advance while any question is unanswered) — then
   decomposition into work **packages** (each a set of independent tasks a single
   build turn fans out to parallel subagents), a per-package test loop, and a
   per-package **agentic review** that verifies the package against its spec.
@@ -132,7 +141,9 @@ unticked and no comment is refused (finish reviewing first), as is deleting
 `<commitish>..HEAD` with no cycle of its own, e.g. a colleague's PR branch. Its
 squash keeps and describes only the fixes made _during_ the review (not the
 reviewed changeset); a clean sign-off with no fixes becomes an empty
-`chore: human review` commit. See
+`chore: human review` commit. A fourth entry, `gtd fix`, starts from a clean
+`idle` and goes straight into repairing a red baseline — repair, review, and
+squash into one commit (a no-op if the suite is already green). See
 [STATES.md](STATES.md#10-the-bundled-workflow-template) for the full shape. The
 workflow is just `.gtdrc` config — edit it or write your own (see
 [Configuration](docs/configuration.md)). Every agent state routes its model
@@ -153,14 +164,15 @@ Before wiring gtd into a repo, note the
 importantly: gitignore everything your scripts write.
 
 Editor integration: `gtd lsp` starts an LSP server over stdio for `.gtd/`
-steering files — symbols and check/uncheck actions over a `review`-mode file's
-chunks, go-to-definition from a `review`-mode hunk line into the file it points
-at (at its `#line`), symbols over a `qa`-mode file's open questions, diagnostics
-for both (live as you edit), and a `gtd.openSteeringFile` command that jumps to
-the current state's steering file. Config-driven via each state's
+steering files — a symbol per `review`-mode chunk that still has an unchecked
+hunk (an outline of the packages left to review) plus check/uncheck actions over
+those chunks, go-to-definition from a `review`-mode hunk line into the file it
+points at (at its `#line`), symbols over a `qa`-mode file's open questions,
+diagnostics for both (live as you edit), and a `gtd.openSteeringFile` command
+that jumps to the current state's steering file. Config-driven via each state's
 `file:`/`mode:` (see [CLI reference](docs/cli.md#gtd-lsp)) — falls back to
-basename dispatch (`TODO.md`/`REVIEW.md`) with no config in sight. Those two
-formats are gtd's built-in steering-file MODES — validators, not formatters: a
+basename dispatch (`REVIEW.md` → `review`) with no config in sight. `qa` and
+`review` are gtd's built-in steering-file MODES — validators, not formatters: a
 mode's `format:` and `validate:` are shell commands a workflow (or a project's
 `.gtdrc`) declares for itself, so you bring your own formatter and your own
 checkers (see

package/dist/gtd.bundle.mjs

@@ -189105,10 +189105,16 @@ const isReviewWindowState = (def, state) => def.states[state]?.reviewWindow ===
 const isReviewBaseState = (def, state) => def.states[state]?.reviewBase === true;
 /** True when a step at `state` must be refused if its only change is deleting the state's `file:` (see `StateDef.requireProgress`). Safe for an unknown state name (returns `false`). */
 const isRequireProgressState = (def, state) => def.states[state]?.requireProgress === true;
+/** True when a step at `state` must be refused unless every open question in its `qa`-mode file is answered (see `StateDef.answerGate`). Safe for an unknown state name (returns `false`). */
+const isAnswerGateState = (def, state) => def.states[state]?.answerGate === true;
 /** The workflow's declared review-entry state name (see `StateDef.reviewEntry`) — `gtd review <commitish>` (`src/program.ts`) enters this state to start a new review process. `undefined` when no state declares one; `validateDefinition` guarantees at most one does, so the first (only) match wins. */
 const reviewEntryStateOf = (def) => {
 	for (const [name, state] of Object.entries(def.states)) if (state.reviewEntry === true) return name;
 };
+/** The workflow's declared fix-entry state name (see `StateDef.fixEntry`) — `gtd fix` (`src/program.ts`) enters this state to start a new fix process. `undefined` when no state declares one; `validateDefinition` guarantees at most one does, so the first (only) match wins. */
+const fixEntryStateOf = (def) => {
+	for (const [name, state] of Object.entries(def.states)) if (state.fixEntry === true) return name;
+};
 /** The ` → ` that separates a transition subject's source state from its target. */
 const TRANSITION_SEP = " → ";
 /**
@@ -189475,6 +189481,20 @@ const validateReviewEntry = (name, state) => {
 	return errors;
 };
 /**
+* `fixEntry`, when present, is forbidden on a commit state and on the initial
+* state — the same rule family as `reviewEntry` (see `validateReviewEntry`):
+* `gtd fix` REQUIRES resting at the initial state before it acts, so its entry
+* target must be a distinct state. The at-most-one-state rule is checked
+* separately over the whole definition (see `validateFixEntryUniqueness`).
+*/
+const validateFixEntry = (name, state) => {
+	if (state.fixEntry === void 0) return [];
+	const errors = [];
+	if (isCommitState(state)) errors.push(`state "${name}": a commit state cannot declare "fixEntry"`);
+	if (state.initial === true) errors.push(`state "${name}": the initial state cannot declare "fixEntry"`);
+	return errors;
+};
+/**
 * `requireProgress`, when present, is forbidden on a commit state (never at
 * rest — same rule family as `reviewWindow`/`reviewBase`) and REQUIRES a
 * `file:`: the edge gate refuses a turn whose sole change is deleting that
@@ -189487,11 +189507,31 @@ const validateRequireProgress = (name, state) => {
 	if (state.file === void 0) errors.push(`state "${name}": "requireProgress" requires "file"`);
 	return errors;
 };
+/**
+* `answerGate`, when present, is forbidden on a commit state (never at rest —
+* same rule family as `reviewWindow`/`requireProgress`) and REQUIRES a `file:`:
+* the edge gate reads that file's open questions to check every one is answered,
+* so a state with no `file:` to name has nothing to gate. The gate only ACTS
+* when the state also declares `mode: qa` (the built-in checkbox format), but
+* that pairing is an edge concern, not enforced here.
+*/
+const validateAnswerGate = (name, state) => {
+	if (state.answerGate === void 0) return [];
+	const errors = [];
+	if (isCommitState(state)) errors.push(`state "${name}": a commit state cannot declare "answerGate"`);
+	if (state.file === void 0) errors.push(`state "${name}": "answerGate" requires "file"`);
+	return errors;
+};
 /** At most one state may declare `reviewEntry: true` — `gtd review <commitish>` (`src/program.ts`) needs a single, unambiguous state name to enter (see `reviewEntryStateOf`). */
 const validateReviewEntryUniqueness = (def, names) => {
 	const entryNames = names.filter((name) => def.states[name].reviewEntry === true);
 	return entryNames.length > 1 ? [`at most one state may declare "reviewEntry" (found ${entryNames.length}: ${entryNames.join(", ")})`] : [];
 };
+/** At most one state may declare `fixEntry: true` — `gtd fix` (`src/program.ts`) needs a single, unambiguous state name to enter (see `fixEntryStateOf`). */
+const validateFixEntryUniqueness = (def, names) => {
+	const entryNames = names.filter((name) => def.states[name].fixEntry === true);
+	return entryNames.length > 1 ? [`at most one state may declare "fixEntry" (found ${entryNames.length}: ${entryNames.join(", ")})`] : [];
+};
 /** Every `on` row parses, and its target names a defined state. */
 const validateOnEdges = (name, state, names) => {
 	const errors = [];
@@ -189510,14 +189550,18 @@ const validateRetry = (name, state, names) => {
 	return errors;
 };
 /**
-* Every state is reachable from the initial state by walking `on` targets and
+* Every state is reachable from an ENTRY ROOT by walking `on` targets and
 * `retry.otherwise` redirects (a redirect ENTERS its `otherwise` state exactly
 * like an `on` match enters its target — see `applyRetry` — so both are real
-* edges). Plain BFS; targets naming undefined states are skipped here (they
-* are `validateOnEdges`/`validateRetry` findings of their own). Only called
-* when `validateInitial` found no problem: with zero or several `initial`
-* states there is no well-defined start to walk from, and reporting every
-* state as unreachable would bury the real finding.
+* edges). The roots are the initial state PLUS the CLI-command entry states
+* (`reviewEntry`/`fixEntry`): a command enters those directly, so a state
+* reachable only from one of them is legitimately reachable, not dead config
+* (without seeding them, e.g. a `fixEntry` check whose only inbound path is
+* `gtd fix` would be wrongly flagged). Plain BFS; targets naming undefined
+* states are skipped here (they are `validateOnEdges`/`validateRetry` findings
+* of their own). Only called when `validateInitial` found no problem: with zero
+* or several `initial` states there is no well-defined start to walk from, and
+* reporting every state as unreachable would bury the real finding.
 *
 * An unreachable state is an ERROR, not a warning: a workflow is bound to a
 * project and edited as a project-wide change, so "kept on purpose for manual
@@ -189526,9 +189570,13 @@ const validateRetry = (name, state, names) => {
 * config is exactly what load-time validation exists to catch.
 */
 const validateReachability = (def, names) => {
-	const initial = names.find((name) => def.states[name].initial === true);
-	const visited = /* @__PURE__ */ new Set([initial]);
-	const queue = [initial];
+	const roots = [
+		names.find((name) => def.states[name].initial === true),
+		reviewEntryStateOf(def),
+		fixEntryStateOf(def)
+	].filter((name) => name !== void 0);
+	const visited = new Set(roots);
+	const queue = [...roots];
 	while (queue.length > 0) {
 		const state = def.states[queue.shift()];
 		const targets = (state.on ?? []).map(([, target]) => target);
@@ -189538,7 +189586,7 @@ const validateReachability = (def, names) => {
 			queue.push(target);
 		}
 	}
-	return names.filter((name) => !visited.has(name)).map((name) => `state "${name}" is unreachable from initial state "${initial}" (no "on" target or "retry.otherwise" leads to it)`);
+	return names.filter((name) => !visited.has(name)).map((name) => `state "${name}" is unreachable from any entry state (${roots.join(", ")}) (no "on" target or "retry.otherwise" leads to it)`);
 };
 /** All per-state rule checkers, run over one state. */
 const validateState = (def, name, names) => {
@@ -189554,7 +189602,9 @@ const validateState = (def, name, names) => {
 		...validateMode(def, name, state),
 		...validateReviewWindow(name, state),
 		...validateReviewEntry(name, state),
-		...validateRequireProgress(name, state)
+		...validateFixEntry(name, state),
+		...validateRequireProgress(name, state),
+		...validateAnswerGate(name, state)
 	];
 };
 /**
@@ -189576,11 +189626,12 @@ const validateState = (def, name, names) => {
 * `knownModes`), requires a sibling `file`, and is never declared on a commit
 * state; every `modes:` entry declares at least one non-blank
 * `format`/`validate` command; `reviewWindow`/`reviewBase`, when
-* present, are never declared on a commit state; `reviewEntry`, when present,
-* is never declared on a commit state or the initial state, and at most one
-* state across the whole workflow may declare it; every state is reachable
-* from the initial state by walking `on` targets and `retry.otherwise`
-* redirects (checked only when the initial-state rule itself passed — see
+* present, are never declared on a commit state; `reviewEntry`/`fixEntry`, when
+* present, are never declared on a commit state or the initial state, and at
+* most one state across the whole workflow may declare each; every state is
+* reachable from an entry root (the initial state plus any `reviewEntry`/
+* `fixEntry` state) by walking `on` targets and `retry.otherwise` redirects
+* (checked only when the initial-state rule itself passed — see
 * `validateReachability`).
 */
 const validateDefinition = (def) => {
@@ -189592,6 +189643,7 @@ const validateDefinition = (def) => {
 		...validateModes(def),
 		...names.flatMap((name) => validateState(def, name, names)),
 		...validateReviewEntryUniqueness(def, names),
+		...validateFixEntryUniqueness(def, names),
 		...initialErrors.length === 0 ? validateReachability(def, names) : []
 	];
 };
@@ -189803,7 +189855,9 @@ const KNOWN_STATE_KEYS = /* @__PURE__ */ new Set([
 	"reviewWindow",
 	"reviewBase",
 	"reviewEntry",
-	"requireProgress"
+	"fixEntry",
+	"requireProgress",
+	"answerGate"
 ]);
 const KNOWN_TOP_KEYS = /* @__PURE__ */ new Set([
 	"vars",
@@ -190017,7 +190071,7 @@ const compileMode = (raw, name, errors) => {
 /** The `initial` field: `true` only when the raw value is the literal boolean `true`. */
 const compileInitial = (raw, name, errors) => compileBooleanFlag(raw, "initial", name, errors);
 /**
-* A boolean state flag (`initial`/`reviewWindow`/`reviewBase`/`reviewEntry`): `true` only
+* A boolean state flag (`initial`/`reviewWindow`/`reviewBase`/`reviewEntry`/`fixEntry`/`requireProgress`/`answerGate`): `true` only
 * when the raw value is the literal `true`; a non-boolean is a config error;
 * `false` (or absent) compiles away to `undefined` so it never lands in the
 * `StateDef` — `false` and "unset" mean the same thing for every such flag.
@@ -190058,7 +190112,9 @@ const assembleStateDef = (parts) => ({
 		reviewWindow: parts.reviewWindow,
 		reviewBase: parts.reviewBase,
 		reviewEntry: parts.reviewEntry,
-		requireProgress: parts.requireProgress
+		fixEntry: parts.fixEntry,
+		requireProgress: parts.requireProgress,
+		answerGate: parts.answerGate
 	}),
 	...assembleContentFields(parts.content)
 });
@@ -190083,7 +190139,9 @@ const compileState = (name, raw, configDir, errors, inlineFileRefs) => {
 		reviewWindow: compileBooleanFlag(raw, "reviewWindow", name, errors),
 		reviewBase: compileBooleanFlag(raw, "reviewBase", name, errors),
 		reviewEntry: compileBooleanFlag(raw, "reviewEntry", name, errors),
-		requireProgress: compileBooleanFlag(raw, "requireProgress", name, errors)
+		fixEntry: compileBooleanFlag(raw, "fixEntry", name, errors),
+		requireProgress: compileBooleanFlag(raw, "requireProgress", name, errors),
+		answerGate: compileBooleanFlag(raw, "answerGate", name, errors)
 	});
 };
 /**
@@ -190310,6 +190368,10 @@ const workflowJsonSchema = {
 						type: "boolean",
 						description: "Marks the (at most one) state `gtd review <commitish>` enters to start a brand new process reviewing <commitish>..HEAD. Forbidden on a commit state and on the initial state."
 					},
+					fixEntry: {
+						type: "boolean",
+						description: "Marks the (at most one) state `gtd fix` enters to start a brand new process that goes straight into repairing the current failing tests. Forbidden on a commit state and on the initial state."
+					},
 					requireProgress: {
 						type: "boolean",
 						description: "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
@@ -191496,7 +191558,7 @@ var WorktreeReader = class WorktreeReader extends Tag("WorktreeReader")() {
 };
 //#endregion
 //#region src/workflows/unified.yaml
-var unified_default = "# The unified gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init` (no argument). gtd ships no\n# default workflow: a repo picks this bundled template 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 full walkthrough.\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). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `gtd init` DERIVES the scaffolded\n# `.gtdrc.json` from this inline source (`renderInitScaffold`): each agent\n# state's `prompt:` is written out as an editable `gtd-prompts/<state>.md`\n# file; human `message:`/check `script:`/the `done` `commit:` body stay inline.\n#\n# ── Three entry points, one shared tail ────────────────────────────────────\n#\n# The initial `idle` state FORKS on which steering file the human creates:\n#\n#   * .gtd/REQUIREMENTS.md -> the ADVANCED flow (product + technical Q&A,\n#     package decomposition, per-package parallel build + agentic spec-review).\n#   * anything else (e.g. .gtd/TODO.md) -> the SIMPLE flow (one grilling Q&A\n#     loop, a monolithic build, no decomposition, no agentic review).\n#\n# A third entry, `gtd review <commitish>`, jumps straight to `reviewing`\n# (reviewEntry) to review a foreign branch through the same shared tail.\n#\n# All three converge at `reviewing` -> `await-review`. Ticking a REVIEW.md box\n# means only \"I reviewed this hunk\"; a COMMENT (not an unticked box) is what asks\n# for changes. Every human step at `await-review` goes to `review-deciding`,\n# which inspects the step and routes:\n#   * no comment (every box ticked, no REVIEW.md note, no code edit) -> the diff\n#     is a bare REVIEW.md deletion -> squashing -> done (the ONLY path to the\n#     finale — the whole cycle collapses into one commit).\n#   * any comment — a note in REVIEW.md OR a hand-edit to code — ->\n#     review-deciding writes REVIEW_FEEDBACK.md -> feedback-building implements\n#     it (completing any code the human hand-edited, never reverting their\n#     lines) -> checking -> reviewing regenerates an INCREMENTAL REVIEW.md\n#     (review-deciding carries `reviewBase: true`, so each feedback round's\n#     review + checkout window covers only `last-review..HEAD`, i.e. the agent's\n#     follow-through, not the human's own edit) -> await-review, looping until\n#     sign-off.\n# Two dead ends never commit: the sign-off gate (src/program.ts) REFUSES a step\n# that leaves a box unticked with no comment (finish reviewing first) and a\n# deleted REVIEW.md (restore it and tick the boxes).\n#\n# The shared health segment (`checking`/`fixing`/`escalate`) serves the simple\n# build and the feedback loop — its green edge targets\n# `reviewing`. The advanced per-package loop keeps its OWN health triple\n# (`adv-checking`/`adv-fixing`/`adv-escalate`) because its green edge targets\n# the per-package `spec-review` gate instead.\n#\n# KNOWN LIMITATION: `on` pattern keys are NOT Eta templates — they keep the\n# LITERAL `.gtd/...` paths matching these vars' DEFAULT values. Repointing a\n# file var changes what templates read/write WITHOUT changing what the `on`\n# patterns match, desyncing the machine (see docs/configuration.md).\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewRawFile: .gtd/REVIEW_RAW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/architecting/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n\nstates:\n  # ── Shared entry ────────────────────────────────────────────────────────\n  idle:\n    actor: human\n    initial: true\n    # Every human-gate `message:` below closes with the same rendered \"What\n    # each change does next\" list, built from `it.edges` (the resting state's\n    # own `on` edges — each edge's `describe:` is the single source of truth).\n    message: |\n      No active gtd cycle.\n\n      To start one, create a steering file describing what you want built:\n\n      - `.gtd/TODO.md` — a short sketch — starts the SIMPLE flow (plan, build,\n        review).\n      - `.gtd/REQUIREMENTS.md` — the product requirements — starts the ADVANCED\n        flow (product + technical Q&A, package decomposition, parallel build,\n        per-package agentic review).\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      \"* .gtd/REQUIREMENTS.md\":\n        to: adv-grilling\n        describe: >-\n          Save the product requirements to `.gtd/REQUIREMENTS.md` to start the\n          ADVANCED flow — the agent develops them through product then technical\n          Q&A, decomposes the work into packages, and builds each in parallel\n          (**adv-grilling**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save a short sketch to `.gtd/TODO.md` (or any other change) to start\n          the SIMPLE flow — the agent reads it, explores the codebase, and\n          develops it into a concrete implementation plan (**grilling**).\n\n  # ── Simple flow: one Q&A loop, monolithic build ───────────────────────────\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\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 none.\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 — the human's edit\n      where they gave one, your own suggestion where they left it untouched (an\n      untouched suggestion IS acceptance) — and MOVE each resolved\n      `### <question>` block down into a `## Answered Questions` section at the\n      bottom. Raise any genuinely new questions under `## Open Questions`.\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.\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    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 its\n      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 all\n      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  # ── Advanced flow: product + technical Q&A ────────────────────────────────\n  adv-grilling:\n    actor: agent\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\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.requirementsFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.requirementsFile %>` holds the product requirements (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete, PRODUCT-level plan in this one turn.\n\n      Scope: product and user-facing decisions only. Leave implementation\n      details (file/module structure, data models, tech-stack choices) for the\n      next phase (`<%= it.vars.architectureFile %>`).\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 your\n      suggested answer in plain prose (always suggest one). Omit the section\n      once there are none. On a return lap, fold the whole answered batch into\n      the plan and move each resolved `### <question>` block down into a\n      `## Answered Questions` section at the bottom.\n\n      Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n    on:\n      \"* **\": adv-grilling-answer\n\n  adv-grilling-answer:\n    actor: human\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.requirementsFile %>` holds the product plan under\n      development, with any open questions under `## Open Questions` — each\n      carrying a suggested answer. Answer a question by editing its body in\n      place; leave a suggestion untouched to accept it.\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: architecting\n        describe: >-\n          Change nothing to accept the product plan and move on to technical\n          architecting (**architecting**).\n      \"* **\":\n        to: adv-grilling\n        describe: >-\n          Edit the product plan — answer a question, add detail, or raise a new\n          one — to send it back for another round (**adv-grilling**).\n\n  architecting:\n    actor: agent\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\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.architectureFile %>` and `<%= it.vars.requirementsFile %>`,\n      which this prompt tells you to write and delete respectively.\n\n      Read `<%= it.vars.requirementsFile %>` (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; treat them as settled.\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading exactly as the grilling phase does (one `### <question>` each, its\n      body your suggested answer). Omit the section once there are none. On a\n      return lap, fold the whole answered batch in and move each resolved block\n      down into a `## Answered Questions` section at the bottom.\n\n      Once `<%= it.vars.architectureFile %>` is written, delete\n      `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n      must not linger. 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`. Answer a\n      question by editing its body in place; leave a suggestion untouched to\n      accept it.\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: decompose\n        describe: >-\n          Change nothing to accept the technical plan and move on to decomposing\n          the work into packages (**decompose**).\n      \"* **\":\n        to: architecting\n        describe: >-\n          Edit the technical plan to send it back for another round\n          (**architecting**).\n\n  # ── Advanced flow: decomposition + per-package parallel build loop ─────────\n  decompose:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\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      package files this prompt tells you to write (under\n      `<%= it.vars.packagesDir %>/`), and `<%= it.vars.architectureFile %>`,\n      which it tells you to delete.\n\n      Read `<%= it.vars.architectureFile %>` (the converged technical plan) and\n      decompose it into an ordered set of WORK PACKAGES, one file each under\n      `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n      `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n      test suite can pass again after each one lands.\n\n      Each package file describes a set of INDEPENDENT tasks that can be\n      implemented concurrently without ordering constraints between them — a\n      single build turn will fan them out to parallel subagents. Give each task\n      a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n      relevant paths. Also state the package's overall requirement so it can be\n      reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n      package — split them across ordered packages instead.\n\n      No package file may reference any other `.gtd/` file. Once the package\n      files are written, delete `<%= it.vars.architectureFile %>`. Leave\n      everything uncommitted and finish your turn.\n    on:\n      \"* .gtd/packages/**\": picking\n\n  picking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package queue arbiter) — the loop driver executes\n      # this verbatim, then steps the check actor. Mechanics only: take the\n      # first package file (by name) under the packages dir into NEXT.md, or\n      # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n      # MEANS (another package to build vs. the queue closing out to review) is\n      # decided by this state's own `on` rules at capture time — never here.\n      set +e\n      # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n      # after an interpolation tag, so no tag may be the last token on a line —\n      # it would glue the next line's `else`/`fi` onto it and break the script.\n      # Below this point everything is plain bash.\n      nextFile=\"<%~ it.vars.nextFile %>\"\n      next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n      if [ -n \"$next\" ]; then\n        printf '%s' \"$next\" > \"$nextFile\"\n      else\n        rm -f \"$nextFile\"\n      fi\n    on:\n      \"D .gtd/NEXT.md\": reviewing\n      \"* .gtd/NEXT.md\": adv-building\n      \"C\": reviewing\n\n  adv-building:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\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/`; in\n      particular do NOT delete the package file (the `spec-review` gate reads it\n      after you) and never touch `<%= it.vars.nextFile %>` — the `picking` state\n      owns it.\n\n      The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n      That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n      this one turn, fanning the independent tasks out to parallel subagents\n      where your harness supports it — each task is self-contained and can be\n      built concurrently. Implement EXACTLY the tasks this package describes — no\n      more, no less; leave every other package file untouched. Use TDD\n      discipline within each task.\n\n      Leave the package file in place and everything else uncommitted, then\n      finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  adv-checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": adv-fixing\n      \"M .gtd/FEEDBACK.md\": adv-fixing\n      \"D .gtd/FEEDBACK.md\": spec-review\n      \"C\": spec-review\n\n  adv-fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    retry:\n      max: 3\n      otherwise: adv-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 the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": adv-checking\n\n  adv-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: adv-checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or\n          `.gtd/FEEDBACK.md` — to re-run the check (**adv-checking**).\n\n  spec-review:\n    actor: agent\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # Bounded per cycle: once entered `max` times, a transition into it is\n    # redirected to `closing` (force-close the package and move on — the\n    # unresolved concern is deferred to the shared human review at the tail,\n    # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n    # pools across packages — the same documented limitation the shared\n    # `fixing` cap has (see STATES.md / docs/configuration.md).\n    retry:\n      max: 3\n      otherwise: closing\n    prompt: |\n      You are an autonomous coding agent reviewing a freshly-built work package\n      against its own spec. `.gtd/` holds this workflow's own state — never\n      create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.specFeedbackFile %>`, which this prompt tells you to write\n      when — and only when — you find problems.\n\n      The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n      Read that spec, then verify the package's implementation (the diff below)\n      against it: are all its tasks done, acceptance criteria met, and the code\n      sound and consistent with the codebase?\n\n      - If it fully satisfies the spec, write NOTHING and finish your turn — a\n        clean turn is your approval.\n      - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n        concrete problems for a fix turn to address. Be specific.\n\n      Do not fix anything yourself and do not delete the package file — a later\n      step owns that. Finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Diff under review\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"M .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"D .gtd/SPEC_FEEDBACK.md\": closing\n      \"C\": closing\n\n  spec-fix:\n    actor: agent\n    file: <%= it.vars.specFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\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.specFeedbackFile %>`, which this prompt tells you to address\n      and then delete.\n\n      Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n      current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n      then fix the code to resolve every concern. Keep the change focused.\n\n      Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n      Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  closing:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package closer) — remove the just-reviewed package\n      # file (its path is in NEXT.md) plus any leftover spec feedback, so\n      # `picking` selects the NEXT package (or falls through to review when the\n      # queue is empty). Reached on approval (spec-review clean) and on the\n      # spec-review retry cap (force-close, deferring the concern to the tail).\n      set +e\n      pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n      [ -n \"$pkg\" ] && rm -f \"$pkg\"\n      rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n    on:\n      \"* **\": picking\n\n  # ── Shared health segment (simple build, feedback loop, code-only edits) ──\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\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    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 the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\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  # ── Shared tail: agent review -> human review -> squash finale ────────────\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: <%= it.vars.plannerModel %>\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 same\n    # reviewing/await-review/feedback machinery over <commitish>..HEAD.\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 diff below in\n      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 of\n        what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n        pointer per hunk (checkboxes are for the human to tick, not you; every\n        path is `./`-relative, with an optional `#line` and an optional\n        ` — note`).\n\n      The diff below is `it.reviewDiff` — on a feedback round it covers ONLY the\n      changes made since the previous review, so you review just what changed,\n      not items already signed off. Leave `<%= it.vars.reviewFile %>`\n      uncommitted and finish your turn.\n      <% if (it.reviewDiff.trim()) { %>\n\n      ## Full diff under review\n\n      ```diff\n      <%~ it.reviewDiff %>\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, gtd opens a \"review checkout window\": raw HEAD\n    # is rewound to the review base (the most-recent `review-deciding` commit —\n    # so a feedback round shows only `last-review..HEAD` — or the process start\n    # on the first review) with the working tree untouched, surfacing the diff\n    # as ordinary uncommitted changes. It closes on the next invocation.\n    #\n    # Every human step here routes to `review-deciding`, which decides sign-off\n    # vs. feedback from the step's CONTENT (a comment, not a tick). Ticking a box\n    # only records \"I reviewed this hunk\". Two dead ends can't be told apart by a\n    # file-pattern edge, so the sign-off gate (`enforceReviewSignoffGate` in\n    # src/program.ts) catches them BEFORE the step commits and refuses: an\n    # unfinished review (a box still `- [ ]` with no comment) and a deleted\n    # REVIEW.md.\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the cycle — one\n      `- [ ]` checkbox per reviewable item, grouped into chunks. Tick a box\n      (`- [x]`) as you review each hunk; ticking only records that you've read\n      it, it is not sign-off.\n\n      When you've been through the whole diff, run `gtd step human`:\n\n      - Tick EVERY box and leave no comment — no note in\n        `<%= it.vars.reviewFile %>`, no code edit — to sign off and collapse the\n        cycle into one commit (**squashing**).\n      - Leave a comment to request changes — a note on a\n        `<%= it.vars.reviewFile %>` line, or a direct code edit — to send it to a\n        build + re-review round (**review-deciding** → **feedback-building**). A\n        code edit counts as your own fix: the agent completes the follow-through\n        it implies and never reverts your lines.\n\n      Stepping with a box still unticked and no comment is refused (finish\n      reviewing first); so is deleting `<%= it.vars.reviewFile %>`.\n    on:\n      \"* **\": review-deciding\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n    # the point the previous review round ended, so the next `reviewing` turn\n    # (and the review checkout window) covers only the changes since then. On\n    # the first review there is no such commit, so the base is the cycle start.\n    reviewBase: true\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — decide the human's review step from its CONTENT. HEAD is\n      # the human's `await-review -> review-deciding` commit; HEAD^ is the\n      # `reviewing` commit that wrote the agent's original REVIEW.md (the sign-off\n      # gate refuses an incomplete step, so review-deciding is entered exactly\n      # once per round — nothing commits in between). It is FEEDBACK when the\n      # human left a comment: a note in REVIEW.md (any edit beyond a \"[ ]\"->\"[x]\"\n      # tick) OR a hand-edit to any non-.gtd/ file this round. Otherwise it is a\n      # clean sign-off. This turn only CAPTURES the raw material into REVIEW_RAW.md\n      # (the `feedback-collecting` agent then turns it into instructions); it does\n      # NOT interpret it. Either way, remove REVIEW.md; what the resulting diff\n      # MEANS is decided by this state's own `on` rules — the A/M REVIEW_RAW.md\n      # rows are declared BEFORE the D REVIEW.md row so a feedback round (which\n      # also deletes REVIEW.md) is captured as feedback, not mistaken for a\n      # sign-off.\n      set +e\n      mkdir -p .gtd\n      # Hoist the paths once, at the TOP: Eta's autoTrim eats the newline after\n      # an interpolation tag, so no tag may be the last token on a line — it\n      # would glue the next line onto it and break the script. Below this point\n      # everything is plain bash.\n      reviewFile=\"<%~ it.vars.reviewFile %>\"\n      reviewRawFile=\"<%~ it.vars.reviewRawFile %>\"\n      # Which non-.gtd/ files did the human hand-edit this round?\n      codeFiles=$(git diff-tree --no-commit-id --name-only -r HEAD | grep -v '^\\.gtd/')\n      # A note is any REVIEW.md change beyond a checkbox flip: normalize every\n      # \"[ ]\"/\"[x]\" to a placeholder, then compare the agent's original (HEAD^)\n      # against the human's version (HEAD).\n      notes=\"\"\n      before=$(git show \"HEAD^:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n      after=$(git show \"HEAD:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n      if [ \"$before\" != \"$after\" ]; then notes=1; fi\n      if [ -n \"$codeFiles\" ] || [ -n \"$notes\" ]; then\n        {\n          echo \"Raw review material captured for classification. The human reviewed the diff and left the feedback below; a downstream agent turns it into an instruction list. This file is machine-captured input, not instructions.\"\n          if [ -n \"$notes\" ]; then\n            echo\n            echo \"## Notes the human added to REVIEW.md this round\"\n            echo\n            echo '```diff'\n            git show HEAD --format= -- \"$reviewFile\"\n            echo '```'\n          fi\n          if [ -n \"$codeFiles\" ]; then\n            echo\n            echo \"## Files the human hand-edited this round (already committed)\"\n            echo\n            echo '```diff'\n            git show HEAD --format= -- $codeFiles\n            echo '```'\n          fi\n        } > \"$reviewRawFile\"\n      fi\n      rm -f \"$reviewFile\"\n    on:\n      \"A .gtd/REVIEW_RAW.md\": feedback-collecting\n      \"M .gtd/REVIEW_RAW.md\": feedback-collecting\n      \"D .gtd/REVIEW.md\": squashing\n\n  feedback-collecting:\n    actor: agent\n    file: <%= it.vars.reviewFeedbackFile %>\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    prompt: |\n      You are an autonomous coding agent turning raw review feedback into an\n      explicit instruction list for a builder. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewRawFile %>` (delete it when done) and\n      `<%= it.vars.reviewFeedbackFile %>` (write it). Do NOT change any other\n      file — you classify, you do not build.\n\n      The raw review material is: <%~ it.read(it.vars.reviewRawFile) %>\n\n      Classify every piece of it into `<%= it.vars.reviewFeedbackFile %>` as a\n      flat, numbered instruction list. Each item is `N. ./path/to/file.ts#line —\n      <imperative>`. Read the two RAW sections and apply these rules exactly:\n\n      1. NOTES the human added to REVIEW.md — each note is a MANDATORY change,\n         regardless of whether its checkbox is ticked (ticking means only \"I read\n         this hunk\", never sign-off). Anchor each to the `./path#line` its review\n         item names (or the chunk it sits under). Emit it as a concrete\n         imperative.\n      2. Every COMMENT the human ADDED this round (a `+` line that is a code\n         comment, in the hand-edited files) is a MANDATORY instruction the human\n         is giving the builder — even a plain-prose one, even if its box is\n         ticked. Emit an imperative to satisfy it and note that the comment line\n         itself must be REMOVED once addressed. If a comment turns out to describe\n         behaviour the code already has, the instruction is still \"confirm the\n         code matches and remove the comment line\".\n      3. Every NON-comment code line the human hand-edited is an already-committed\n         INTENT, NOT a do-then-delete item. Emit an instruction that names those\n         files and says: their lines are final — complete ONLY the follow-through\n         they imply (callers, tests, types, docs) and NEVER revert or rewrite\n         them. Do not turn their own edit into a task.\n\n      Split each hand-edited hunk per line: comment `+` lines follow rule 2, the\n      surrounding real code follows rule 3.\n\n      If — and only if — nothing in the raw material is actionable (e.g. the human\n      left only an approving remark), write `<%= it.vars.reviewFeedbackFile %>`\n      containing exactly one line: `NOTHING ACTIONABLE — <one-sentence reason>`.\n      Never invent work to satisfy a non-actionable remark.\n\n      Delete `<%= it.vars.reviewRawFile %>`, leave everything else uncommitted,\n      and finish your turn.\n    on:\n      \"A .gtd/REVIEW_FEEDBACK.md\": feedback-building\n      \"M .gtd/REVIEW_FEEDBACK.md\": feedback-building\n\n  feedback-building:\n    actor: agent\n    file: <%= it.vars.reviewFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    # Refuse a work-free turn: a step whose only pending change is deleting the\n    # instructions file (the original \"captured then discarded\" bug). The edge\n    # gate (`enforceFeedbackProgressGate` in src/program.ts) reads this flag and\n    # exempts a `NOTHING ACTIONABLE` sentinel (a non-actionable review round,\n    # which legitimately makes no code change). The pure engine carries it inert.\n    requireProgress: true\n    prompt: |\n      You are an autonomous coding agent addressing review feedback. `.gtd/`\n      holds this workflow's own state — never create, edit, or delete anything\n      under `.gtd/` except `<%= it.vars.reviewFeedbackFile %>`, which this\n      prompt tells you to address and then delete.\n\n      The instructions to implement are: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n      This is a flat instruction list, not a diff — execute every item exactly as\n      written, no Q&A, no re-planning, using TDD discipline:\n\n      - An item that says the human's own lines are final: build ON TOP of them to\n        complete only the follow-through it names (callers, tests, types, docs).\n        NEVER revert or rewrite the lines they already committed.\n      - An item derived from a human comment: satisfy it AND delete that comment\n        line from the code (the human's review comments are transient — none of\n        them survive this round).\n\n      If the file's sole content is a `NOTHING ACTIONABLE` line, make no code\n      change; just delete the instructions file.\n\n      Delete `<%= it.vars.reviewFeedbackFile %>` once every item is addressed.\n      Leave everything else uncommitted and finish your turn. Deleting the\n      instructions file WITHOUT making the changes it asks for is refused — the\n      feedback must actually be addressed.\n    on:\n      \"* **\": checking\n\n  squashing:\n    actor: agent\n    file: <%= it.vars.commitMsgFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\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 `<%= it.vars.commitMsgFile %>`, which this\n      prompt tells you to write.\n\n      Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n      entering this file squashes everything this process retains into one\n      commit using its content as the message. The diff below is exactly what\n      that commit will contain: `it.retainedDiff`, the changes THIS process\n      made (its trace/retry boundary onward). For a normal build cycle that is\n      the whole feature; for a `gtd review` process it is only the fixes made\n      during the review — NOT the changeset that was under review.\n      <% if (it.retainedDiff.trim()) { %>\n\n      Write `<%= it.vars.commitMsgFile %>` with ONE conventional-commits message\n      for the changes below (subject line `type(scope): subject`, imperative\n      mood, <= 72 characters; a body explaining the why, trade-offs, and key\n      decisions). Plain text, no markdown wrapper.\n\n      ## Retained diff\n\n      ```diff\n      <%~ it.retainedDiff %>\n      ```\n      <% } else { %>\n\n      This process retained NO changes (a clean review sign-off with no fixes).\n      Write `<%= it.vars.commitMsgFile %>` with exactly this one line and\n      nothing else:\n\n      chore: human review\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(it.vars.commitMsgFile) %>\n\n      Token cost: <%= it.processCost %>\n      <% it.processCostByModel.forEach(function(m){ %>\n      - <%= m.model %>: <%= m.cost %>\n      <% }) %>\n";
+var unified_default = "# The unified gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init` (no argument). gtd ships no\n# default workflow: a repo picks this bundled template 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 full walkthrough.\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). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `gtd init` DERIVES the scaffolded\n# `.gtdrc.json` from this inline source (`renderInitScaffold`): each agent\n# state's `prompt:` is written out as an editable `gtd-prompts/<state>.md`\n# file; human `message:`/check `script:`/the `done` `commit:` body stay inline.\n#\n# ── Four entry points behind a green-baseline gate, one shared tail ─────────\n#\n# EVERY entry first runs the test suite and only proceeds when it is GREEN — you\n# never start new work (or a review) on top of a red baseline. A red run halts\n# at a human `*-start-blocked` gate (fix the failures and re-run, exactly like\n# the `escalate` states), or is what `gtd fix` exists to repair.\n#\n# The initial `idle` state FORKS on which steering file the human creates,\n# routing into that flow's OWN start gate:\n#\n#   * .gtd/REQUIREMENTS.md -> `adv-start-check` -> the ADVANCED flow (product +\n#     technical Q&A, package decomposition, per-package parallel build +\n#     agentic spec-review).\n#   * anything else (e.g. .gtd/TODO.md) -> `start-check` -> the SIMPLE flow (one\n#     grilling Q&A loop, a monolithic build, no decomposition, no agentic\n#     review).\n#\n# A third entry, `gtd review <commitish>`, jumps to `review-start-check`\n# (reviewEntry) and, once green, to `reviewing` to review a foreign branch\n# through the same shared tail. A fourth, `gtd fix`, jumps to `fix-check`\n# (fixEntry): a red suite drops straight into the shared `fixing` loop and out\n# through the review + squash tail; a green suite is a no-op back to `idle`.\n#\n# All three converge at `reviewing` -> `await-review`. Ticking a REVIEW.md box\n# means only \"I reviewed this hunk\"; a COMMENT (not an unticked box) is what asks\n# for changes. Every human step at `await-review` goes to `review-deciding`,\n# which inspects the step and routes:\n#   * no comment (every box ticked, no REVIEW.md note, no code edit) -> the diff\n#     is a bare REVIEW.md deletion -> squashing -> done (the ONLY path to the\n#     finale — the whole cycle collapses into one commit).\n#   * any comment — a note in REVIEW.md OR a hand-edit to code — ->\n#     review-deciding writes REVIEW_FEEDBACK.md -> feedback-building implements\n#     it (completing any code the human hand-edited, never reverting their\n#     lines) -> checking -> reviewing regenerates an INCREMENTAL REVIEW.md\n#     (review-deciding carries `reviewBase: true`, so each feedback round's\n#     review + checkout window covers only `last-review..HEAD`, i.e. the agent's\n#     follow-through, not the human's own edit) -> await-review, looping until\n#     sign-off.\n# Two dead ends never commit: the sign-off gate (src/program.ts) REFUSES a step\n# that leaves a box unticked with no comment (finish reviewing first) and a\n# deleted REVIEW.md (restore it and tick the boxes).\n#\n# The shared health segment (`checking`/`fixing`/`escalate`) serves the simple\n# build and the feedback loop — its green edge targets\n# `reviewing`. The advanced per-package loop keeps its OWN health triple\n# (`adv-checking`/`adv-fixing`/`adv-escalate`) because its green edge targets\n# the per-package `spec-review` gate instead.\n#\n# KNOWN LIMITATION: `on` pattern keys are NOT Eta templates — they keep the\n# LITERAL `.gtd/...` paths matching these vars' DEFAULT values. Repointing a\n# file var changes what templates read/write WITHOUT changing what the `on`\n# patterns match, desyncing the machine (see docs/configuration.md).\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewRawFile: .gtd/REVIEW_RAW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/architecting/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n\nstates:\n  # ── Shared entry ────────────────────────────────────────────────────────\n  idle:\n    actor: human\n    initial: true\n    # Every human-gate `message:` below closes with the same rendered \"What\n    # each change does next\" list, built from `it.edges` (the resting state's\n    # own `on` edges — each edge's `describe:` is the single source of truth).\n    message: |\n      No active gtd cycle.\n\n      To start one, create a steering file describing what you want built:\n\n      - `.gtd/TODO.md` — a short sketch — starts the SIMPLE flow (plan, build,\n        review).\n      - `.gtd/REQUIREMENTS.md` — the product requirements — starts the ADVANCED\n        flow (product + technical Q&A, package decomposition, parallel build,\n        per-package agentic review).\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      \"* .gtd/REQUIREMENTS.md\":\n        to: adv-start-check\n        describe: >-\n          Save the product requirements to `.gtd/REQUIREMENTS.md` to start the\n          ADVANCED flow — gtd first checks the test baseline is green, then the\n          agent develops them through product then technical Q&A, decomposes the\n          work into packages, and builds each in parallel (**adv-start-check**).\n      \"* **\":\n        to: start-check\n        describe: >-\n          Save a short sketch to `.gtd/TODO.md` (or any other change) to start\n          the SIMPLE flow — gtd first checks the test baseline is green, then the\n          agent reads it, explores the codebase, and develops it into a concrete\n          implementation plan (**start-check**).\n\n  # ── Green-baseline gate: simple flow ──────────────────────────────────────\n  # Runs the suite before any planning starts. Its script is `checking`'s test\n  # wrapper verbatim (red -> .gtd/FEEDBACK.md, green -> remove it); the `on`\n  # rules turn that into \"halt at start-blocked\" vs \"proceed to planning\".\n  start-check:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite before starting new work; a red run\n      # records .gtd/FEEDBACK.md (halt), a green run cleans it up (proceed).\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": start-blocked\n      \"M .gtd/FEEDBACK.md\": start-blocked\n      \"D .gtd/FEEDBACK.md\": planning\n      \"C\": planning\n\n  start-blocked:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The test baseline is red — gtd will not start new work on a broken suite.\n      `<%= it.vars.feedbackFile %>` holds the 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: start-check\n        describe: >-\n          Fix the failing tests — edit the code and/or `.gtd/FEEDBACK.md` — to\n          re-run the baseline check (**start-check**). To repair the baseline as\n          its own separate reviewed commit instead, abandon this start and run\n          `gtd fix` from a clean `idle`.\n\n  # ── Simple flow: plan-iteration loop, monolithic build ────────────────────\n  planning:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    model: <%= it.vars.plannerModel %>\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, on a\n      return lap, the plan you already wrote plus the human's edits and comments\n      on it. Read it, explore the codebase, and develop it into a concrete\n      implementation plan: the files to change, the approach, and the steps to\n      take.\n\n      Do NOT ask questions and do NOT add an \"Open Questions\" section — decide\n      every open point yourself and write the plan as a set of concrete\n      decisions. Where a decision is genuinely a judgement call, state the\n      choice you made and, in one line, why. The human iterates on the plan by\n      editing it directly, not by answering questions.\n\n      On a return lap, `<%= it.vars.todoFile %>` carries the human's edits and\n      inline comments on your previous plan. Fold every edit and comment into a\n      revised, self-contained plan and remove the addressed comments — the plan\n      is always the current, clean proposal, never a diff.\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      \"* **\": plan-review\n\n  plan-review:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    message: |\n      `<%= it.vars.todoFile %>` holds the proposed implementation plan. Read it,\n      then either accept it as-is or edit it — rewrite a step, add a\n      constraint, or drop an inline comment — to send it back for another round.\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 the plan as-is and move on to implementation\n          (**building**).\n      \"* **\":\n        to: planning\n        describe: >-\n          Edit the plan — rewrite a step, add a constraint, or leave an inline\n          comment — to send it back for another round (**planning**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    model: <%= it.vars.coderModel %>\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 its\n      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 all\n      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  # ── Green-baseline gate: advanced flow ────────────────────────────────────\n  adv-start-check:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite before starting the advanced flow; a red\n      # run records .gtd/FEEDBACK.md (halt), a green run cleans it up (proceed).\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": adv-start-blocked\n      \"M .gtd/FEEDBACK.md\": adv-start-blocked\n      \"D .gtd/FEEDBACK.md\": adv-grilling\n      \"C\": adv-grilling\n\n  adv-start-blocked:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The test baseline is red — gtd will not start new work on a broken suite.\n      `<%= it.vars.feedbackFile %>` holds the 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: adv-start-check\n        describe: >-\n          Fix the failing tests — edit the code and/or `.gtd/FEEDBACK.md` — to\n          re-run the baseline check (**adv-start-check**). To repair the baseline\n          as its own separate reviewed commit instead, abandon this start and run\n          `gtd fix` from a clean `idle`.\n\n  # ── Advanced flow: product + technical Q&A ────────────────────────────────\n  adv-grilling:\n    actor: agent\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\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.requirementsFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.requirementsFile %>` holds the product requirements (or the\n      plan you already wrote plus the human's answers on a return lap). Read it,\n      explore the codebase, and develop it into a concrete, PRODUCT-level plan\n      in this one turn.\n\n      Scope: product and user-facing decisions only. Leave implementation\n      details (file/module structure, data models, tech-stack choices) for the\n      next phase (`<%= it.vars.architectureFile %>`).\n\n      For every open point you cannot settle yourself, add a question under a\n      `## Open Questions` heading near the top: one `### <question>` sub-heading\n      each, followed by a checkbox list of candidate answers — aim for TWO\n      concrete options plus a final free-text slot, ALL left UNTICKED:\n\n          ### <the question>\n\n          - [ ] <first option — a concrete answer, a few words of rationale>\n          - [ ] <second option>\n          - [ ] _your answer_\n\n      Never tick a box yourself — the human ticks exactly one per question. The\n      last `- [ ] _your answer_` line is the human's own-answer slot; write it\n      with the literal `_your answer_` placeholder and leave it for them.\n\n      On a RETURN lap the human has ticked one option per question (or replaced\n      `_your answer_` with their own text). For each answered question: fold the\n      chosen answer into the plan prose, then MOVE the question down into a\n      `## Answered Questions` section as `### <question>` followed by the\n      resolved answer in plain PROSE (drop the checkboxes). Never re-raise a\n      question the human deleted; if the human deleted the whole\n      `## Open Questions` section, treat the plan as accepted and surface no new\n      questions unless something is genuinely still blocking. Omit\n      `## Open Questions` entirely once there are none left.\n\n      Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n    on:\n      \"* **\": adv-grilling-answer\n\n  adv-grilling-answer:\n    actor: human\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    answerGate: true\n    message: |\n      `<%= it.vars.requirementsFile %>` holds the product plan under\n      development. Each question under `## Open Questions` offers a few options\n      plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n      exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n      with your text and tick that line. Stepping is refused while any question\n      is unanswered.\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: architecting\n        describe: >-\n          With no open questions left (the agent surfaced none, or you deleted\n          the section and it finalized the plan), change nothing to accept the\n          product plan and move on to technical architecting (**architecting**).\n      \"* **\":\n        to: adv-grilling\n        describe: >-\n          Tick exactly one option per open question (replace `_your answer_` for\n          your own) to send the plan back for the agent to fold your answers in\n          (**adv-grilling**). Delete a question to skip it, or delete the whole\n          `## Open Questions` section to accept the plan as-is.\n\n  architecting:\n    actor: agent\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\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.architectureFile %>` and `<%= it.vars.requirementsFile %>`,\n      which this prompt tells you to write and delete respectively.\n\n      Read `<%= it.vars.requirementsFile %>` (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; treat them as settled.\n\n      For every open point you cannot settle yourself, add a question under a\n      `## Open Questions` heading exactly as the grilling phase does: one\n      `### <question>` each, followed by a checkbox list — TWO concrete options\n      plus a final free-text slot, ALL left UNTICKED:\n\n          ### <the question>\n\n          - [ ] <first option>\n          - [ ] <second option>\n          - [ ] _your answer_\n\n      Never tick a box yourself. On a RETURN lap the human has ticked one option\n      per question (or replaced `_your answer_` with their own text): fold each\n      chosen answer into the plan prose, then MOVE the question into a\n      `## Answered Questions` section as `### <question>` + the resolved answer\n      in plain PROSE (drop the checkboxes). Never re-raise a deleted question;\n      treat a deleted `## Open Questions` section as acceptance. Omit\n      `## Open Questions` once there are none left.\n\n      Once `<%= it.vars.architectureFile %>` is written, delete\n      `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n      must not linger. 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    answerGate: true\n    message: |\n      `<%= it.vars.architectureFile %>` holds the technical plan under\n      development. Each question under `## Open Questions` offers a few options\n      plus a `- [ ] _your answer_` slot. Answer EVERY question by ticking\n      exactly one box (`- [x]`); for your own answer, replace `_your answer_`\n      with your text and tick that line. Stepping is refused while any question\n      is unanswered.\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: decompose\n        describe: >-\n          With no open questions left (the agent surfaced none, or you deleted\n          the section and it finalized the plan), change nothing to accept the\n          technical plan and move on to decomposing the work into packages\n          (**decompose**).\n      \"* **\":\n        to: architecting\n        describe: >-\n          Tick exactly one option per open question (replace `_your answer_` for\n          your own) to send the plan back for the agent to fold your answers in\n          (**architecting**). Delete a question to skip it, or delete the whole\n          `## Open Questions` section to accept the plan as-is.\n\n  # ── Advanced flow: decomposition + per-package parallel build loop ─────────\n  decompose:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\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      package files this prompt tells you to write (under\n      `<%= it.vars.packagesDir %>/`), and `<%= it.vars.architectureFile %>`,\n      which it tells you to delete.\n\n      Read `<%= it.vars.architectureFile %>` (the converged technical plan) and\n      decompose it into an ordered set of WORK PACKAGES, one file each under\n      `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n      `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n      test suite can pass again after each one lands.\n\n      Each package file describes a set of INDEPENDENT tasks that can be\n      implemented concurrently without ordering constraints between them — a\n      single build turn will fan them out to parallel subagents. Give each task\n      a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n      relevant paths. Also state the package's overall requirement so it can be\n      reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n      package — split them across ordered packages instead.\n\n      No package file may reference any other `.gtd/` file. Once the package\n      files are written, delete `<%= it.vars.architectureFile %>`. Leave\n      everything uncommitted and finish your turn.\n    on:\n      \"* .gtd/packages/**\": picking\n\n  picking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package queue arbiter) — the loop driver executes\n      # this verbatim, then steps the check actor. Mechanics only: take the\n      # first package file (by name) under the packages dir into NEXT.md, or\n      # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n      # MEANS (another package to build vs. the queue closing out to review) is\n      # decided by this state's own `on` rules at capture time — never here.\n      set +e\n      # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n      # after an interpolation tag, so no tag may be the last token on a line —\n      # it would glue the next line's `else`/`fi` onto it and break the script.\n      # Below this point everything is plain bash.\n      nextFile=\"<%~ it.vars.nextFile %>\"\n      next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n      if [ -n \"$next\" ]; then\n        printf '%s' \"$next\" > \"$nextFile\"\n      else\n        rm -f \"$nextFile\"\n      fi\n    on:\n      \"D .gtd/NEXT.md\": reviewing\n      \"* .gtd/NEXT.md\": adv-building\n      \"C\": reviewing\n\n  adv-building:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\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/`; in\n      particular do NOT delete the package file (the `spec-review` gate reads it\n      after you) and never touch `<%= it.vars.nextFile %>` — the `picking` state\n      owns it.\n\n      The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n      That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n      this one turn, fanning the independent tasks out to parallel subagents\n      where your harness supports it — each task is self-contained and can be\n      built concurrently. Implement EXACTLY the tasks this package describes — no\n      more, no less; leave every other package file untouched. Use TDD\n      discipline within each task.\n\n      Leave the package file in place and everything else uncommitted, then\n      finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  adv-checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": adv-fixing\n      \"M .gtd/FEEDBACK.md\": adv-fixing\n      \"D .gtd/FEEDBACK.md\": spec-review\n      \"C\": spec-review\n\n  adv-fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    retry:\n      max: 3\n      otherwise: adv-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 the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": adv-checking\n\n  adv-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: adv-checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or\n          `.gtd/FEEDBACK.md` — to re-run the check (**adv-checking**).\n\n  spec-review:\n    actor: agent\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # Bounded per cycle: once entered `max` times, a transition into it is\n    # redirected to `closing` (force-close the package and move on — the\n    # unresolved concern is deferred to the shared human review at the tail,\n    # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n    # pools across packages — the same documented limitation the shared\n    # `fixing` cap has (see STATES.md / docs/configuration.md).\n    retry:\n      max: 3\n      otherwise: closing\n    prompt: |\n      You are an autonomous coding agent reviewing a freshly-built work package\n      against its own spec. `.gtd/` holds this workflow's own state — never\n      create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.specFeedbackFile %>`, which this prompt tells you to write\n      when — and only when — you find problems.\n\n      The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n      Read that spec, then verify the package's implementation (the diff below)\n      against it: are all its tasks done, acceptance criteria met, and the code\n      sound and consistent with the codebase?\n\n      - If it fully satisfies the spec, write NOTHING and finish your turn — a\n        clean turn is your approval.\n      - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n        concrete problems for a fix turn to address. Be specific.\n\n      Do not fix anything yourself and do not delete the package file — a later\n      step owns that. Finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Diff under review\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"M .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"D .gtd/SPEC_FEEDBACK.md\": closing\n      \"C\": closing\n\n  spec-fix:\n    actor: agent\n    file: <%= it.vars.specFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\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.specFeedbackFile %>`, which this prompt tells you to address\n      and then delete.\n\n      Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n      current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n      then fix the code to resolve every concern. Keep the change focused.\n\n      Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n      Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  closing:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package closer) — remove the just-reviewed package\n      # file (its path is in NEXT.md) plus any leftover spec feedback, so\n      # `picking` selects the NEXT package (or falls through to review when the\n      # queue is empty). Reached on approval (spec-review clean) and on the\n      # spec-review retry cap (force-close, deferring the concern to the tail).\n      set +e\n      pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n      [ -n \"$pkg\" ] && rm -f \"$pkg\"\n      rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n    on:\n      \"* **\": picking\n\n  # ── Shared health segment (simple build, feedback loop, code-only edits) ──\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\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    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 the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\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  # ── Green-baseline gate: `gtd review` entry ───────────────────────────────\n  # `gtd review <commitish>` enters HERE (reviewEntry), not `reviewing`. It runs\n  # the suite on HEAD first; green proceeds to `reviewing`, red halts. The\n  # `Gtd-Review-Base:` trailer rides on this state's entry commit, so the review\n  # window / incremental-diff machinery downstream is unchanged.\n  review-start-check:\n    actor: check\n    reviewEntry: true\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite before reviewing; a red run records\n      # .gtd/FEEDBACK.md (halt), a green run cleans it up (proceed to reviewing).\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": review-start-blocked\n      \"M .gtd/FEEDBACK.md\": review-start-blocked\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  review-start-blocked:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The test baseline is red — gtd will not start a review on a broken suite.\n      `<%= it.vars.feedbackFile %>` holds the 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: review-start-check\n        describe: >-\n          Fix the failing tests — edit the code and/or `.gtd/FEEDBACK.md` — to\n          re-run the baseline check (**review-start-check**).\n\n  # ── Green-baseline gate: `gtd fix` entry ──────────────────────────────────\n  # `gtd fix` enters HERE (fixEntry): run the suite, then a red run drops\n  # straight into the shared `fixing` loop (-> checking -> review + squash\n  # tail); a green run is a no-op back to `idle` (nothing to fix).\n  fix-check:\n    actor: check\n    fixEntry: true\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite to find what needs fixing; a red run\n      # records .gtd/FEEDBACK.md (-> fixing), a green run cleans it up (-> idle).\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\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 \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": idle\n      \"C\": idle\n\n  # ── Shared tail: agent review -> human review -> squash finale ────────────\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n    # does NOT enter here directly — it enters `review-start-check` (reviewEntry)\n    # first, which runs the green-baseline gate and, once green, transitions\n    # here. The `Gtd-Review-Base:` trailer rides on that entry commit (the\n    # process's oldest), so everything below still reuses the same\n    # reviewing/await-review/feedback machinery over <commitish>..HEAD.\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 diff below in\n      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 of\n        what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n        pointer per hunk (checkboxes are for the human to tick, not you; every\n        path is `./`-relative, with an optional `#line` and an optional\n        ` — note`).\n\n      The diff below is `it.reviewDiff` — on a feedback round it covers ONLY the\n      changes made since the previous review, so you review just what changed,\n      not items already signed off. Leave `<%= it.vars.reviewFile %>`\n      uncommitted and finish your turn.\n      <% if (it.reviewDiff.trim()) { %>\n\n      ## Full diff under review\n\n      ```diff\n      <%~ it.reviewDiff %>\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, gtd opens a \"review checkout window\": raw HEAD\n    # is rewound to the review base (the most-recent `review-deciding` commit —\n    # so a feedback round shows only `last-review..HEAD` — or the process start\n    # on the first review) with the working tree untouched, surfacing the diff\n    # as ordinary uncommitted changes. It closes on the next invocation.\n    #\n    # Every human step here routes to `review-deciding`, which decides sign-off\n    # vs. feedback from the step's CONTENT (a comment, not a tick). Ticking a box\n    # only records \"I reviewed this hunk\". Two dead ends can't be told apart by a\n    # file-pattern edge, so the sign-off gate (`enforceReviewSignoffGate` in\n    # src/program.ts) catches them BEFORE the step commits and refuses: an\n    # unfinished review (a box still `- [ ]` with no comment) and a deleted\n    # REVIEW.md.\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the cycle — one\n      `- [ ]` checkbox per reviewable item, grouped into chunks. Tick a box\n      (`- [x]`) as you review each hunk; ticking only records that you've read\n      it, it is not sign-off.\n\n      When you've been through the whole diff, run `gtd step human`:\n\n      - Tick EVERY box and leave no comment — no note in\n        `<%= it.vars.reviewFile %>`, no code edit — to sign off and collapse the\n        cycle into one commit (**squashing**).\n      - Leave a comment to request changes — a note on a\n        `<%= it.vars.reviewFile %>` line, or a direct code edit — to send it to a\n        build + re-review round (**review-deciding** → **feedback-building**). A\n        code edit counts as your own fix: the agent completes the follow-through\n        it implies and never reverts your lines.\n\n      Stepping with a box still unticked and no comment is refused (finish\n      reviewing first); so is deleting `<%= it.vars.reviewFile %>`.\n    on:\n      \"* **\": review-deciding\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n    # the point the previous review round ended, so the next `reviewing` turn\n    # (and the review checkout window) covers only the changes since then. On\n    # the first review there is no such commit, so the base is the cycle start.\n    reviewBase: true\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — decide the human's review step from its CONTENT. HEAD is\n      # the human's `await-review -> review-deciding` commit; HEAD^ is the\n      # `reviewing` commit that wrote the agent's original REVIEW.md (the sign-off\n      # gate refuses an incomplete step, so review-deciding is entered exactly\n      # once per round — nothing commits in between). It is FEEDBACK when the\n      # human left a comment: a note in REVIEW.md (any edit beyond a \"[ ]\"->\"[x]\"\n      # tick) OR a hand-edit to any non-.gtd/ file this round. Otherwise it is a\n      # clean sign-off. This turn only CAPTURES the raw material into REVIEW_RAW.md\n      # (the `feedback-collecting` agent then turns it into instructions); it does\n      # NOT interpret it. Either way, remove REVIEW.md; what the resulting diff\n      # MEANS is decided by this state's own `on` rules — the A/M REVIEW_RAW.md\n      # rows are declared BEFORE the D REVIEW.md row so a feedback round (which\n      # also deletes REVIEW.md) is captured as feedback, not mistaken for a\n      # sign-off.\n      set +e\n      mkdir -p .gtd\n      # Hoist the paths once, at the TOP: Eta's autoTrim eats the newline after\n      # an interpolation tag, so no tag may be the last token on a line — it\n      # would glue the next line onto it and break the script. Below this point\n      # everything is plain bash.\n      reviewFile=\"<%~ it.vars.reviewFile %>\"\n      reviewRawFile=\"<%~ it.vars.reviewRawFile %>\"\n      # Which non-.gtd/ files did the human hand-edit this round?\n      codeFiles=$(git diff-tree --no-commit-id --name-only -r HEAD | grep -v '^\\.gtd/')\n      # A note is any REVIEW.md change beyond a checkbox flip: normalize every\n      # \"[ ]\"/\"[x]\" to a placeholder, then compare the agent's original (HEAD^)\n      # against the human's version (HEAD).\n      notes=\"\"\n      before=$(git show \"HEAD^:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n      after=$(git show \"HEAD:$reviewFile\" 2>/dev/null | sed -E 's/\\[[ xX]\\]/[_]/g')\n      if [ \"$before\" != \"$after\" ]; then notes=1; fi\n      if [ -n \"$codeFiles\" ] || [ -n \"$notes\" ]; then\n        {\n          echo \"Raw review material captured for classification. The human reviewed the diff and left the feedback below; a downstream agent turns it into an instruction list. This file is machine-captured input, not instructions.\"\n          if [ -n \"$notes\" ]; then\n            echo\n            echo \"## Notes the human added to REVIEW.md this round\"\n            echo\n            echo '```diff'\n            git show HEAD --format= -- \"$reviewFile\"\n            echo '```'\n          fi\n          if [ -n \"$codeFiles\" ]; then\n            echo\n            echo \"## Files the human hand-edited this round (already committed)\"\n            echo\n            echo '```diff'\n            git show HEAD --format= -- $codeFiles\n            echo '```'\n          fi\n        } > \"$reviewRawFile\"\n      fi\n      rm -f \"$reviewFile\"\n    on:\n      \"A .gtd/REVIEW_RAW.md\": feedback-collecting\n      \"M .gtd/REVIEW_RAW.md\": feedback-collecting\n      \"D .gtd/REVIEW.md\": squashing\n\n  feedback-collecting:\n    actor: agent\n    file: <%= it.vars.reviewFeedbackFile %>\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    prompt: |\n      You are an autonomous coding agent turning raw review feedback into an\n      explicit instruction list for a builder. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewRawFile %>` (delete it when done) and\n      `<%= it.vars.reviewFeedbackFile %>` (write it). Do NOT change any other\n      file — you classify, you do not build.\n\n      The raw review material is: <%~ it.read(it.vars.reviewRawFile) %>\n\n      Classify every piece of it into `<%= it.vars.reviewFeedbackFile %>` as a\n      flat, numbered instruction list. Each item is `N. ./path/to/file.ts#line —\n      <imperative>`. Read the two RAW sections and apply these rules exactly:\n\n      1. NOTES the human added to REVIEW.md — each note is a MANDATORY change,\n         regardless of whether its checkbox is ticked (ticking means only \"I read\n         this hunk\", never sign-off). Anchor each to the `./path#line` its review\n         item names (or the chunk it sits under). Emit it as a concrete\n         imperative.\n      2. Every COMMENT the human ADDED this round (a `+` line that is a code\n         comment, in the hand-edited files) is a MANDATORY instruction the human\n         is giving the builder — even a plain-prose one, even if its box is\n         ticked. Emit an imperative to satisfy it and note that the comment line\n         itself must be REMOVED once addressed. If a comment turns out to describe\n         behaviour the code already has, the instruction is still \"confirm the\n         code matches and remove the comment line\".\n      3. Every NON-comment code line the human hand-edited is an already-committed\n         INTENT, NOT a do-then-delete item. Emit an instruction that names those\n         files and says: their lines are final — complete ONLY the follow-through\n         they imply (callers, tests, types, docs) and NEVER revert or rewrite\n         them. Do not turn their own edit into a task.\n\n      Split each hand-edited hunk per line: comment `+` lines follow rule 2, the\n      surrounding real code follows rule 3.\n\n      If — and only if — nothing in the raw material is actionable (e.g. the human\n      left only an approving remark), write `<%= it.vars.reviewFeedbackFile %>`\n      containing exactly one line: `NOTHING ACTIONABLE — <one-sentence reason>`.\n      Never invent work to satisfy a non-actionable remark.\n\n      Delete `<%= it.vars.reviewRawFile %>`, leave everything else uncommitted,\n      and finish your turn.\n    on:\n      \"A .gtd/REVIEW_FEEDBACK.md\": feedback-building\n      \"M .gtd/REVIEW_FEEDBACK.md\": feedback-building\n\n  feedback-building:\n    actor: agent\n    file: <%= it.vars.reviewFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    # Refuse a work-free turn: a step whose only pending change is deleting the\n    # instructions file (the original \"captured then discarded\" bug). The edge\n    # gate (`enforceFeedbackProgressGate` in src/program.ts) reads this flag and\n    # exempts a `NOTHING ACTIONABLE` sentinel (a non-actionable review round,\n    # which legitimately makes no code change). The pure engine carries it inert.\n    requireProgress: true\n    prompt: |\n      You are an autonomous coding agent addressing review feedback. `.gtd/`\n      holds this workflow's own state — never create, edit, or delete anything\n      under `.gtd/` except `<%= it.vars.reviewFeedbackFile %>`, which this\n      prompt tells you to address and then delete.\n\n      The instructions to implement are: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n      This is a flat instruction list, not a diff — execute every item exactly as\n      written, no Q&A, no re-planning, using TDD discipline:\n\n      - An item that says the human's own lines are final: build ON TOP of them to\n        complete only the follow-through it names (callers, tests, types, docs).\n        NEVER revert or rewrite the lines they already committed.\n      - An item derived from a human comment: satisfy it AND delete that comment\n        line from the code (the human's review comments are transient — none of\n        them survive this round).\n\n      If the file's sole content is a `NOTHING ACTIONABLE` line, make no code\n      change; just delete the instructions file.\n\n      Delete `<%= it.vars.reviewFeedbackFile %>` once every item is addressed.\n      Leave everything else uncommitted and finish your turn. Deleting the\n      instructions file WITHOUT making the changes it asks for is refused — the\n      feedback must actually be addressed.\n    on:\n      \"* **\": checking\n\n  squashing:\n    actor: agent\n    file: <%= it.vars.commitMsgFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\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 `<%= it.vars.commitMsgFile %>`, which this\n      prompt tells you to write.\n\n      Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n      entering this file squashes everything this process retains into one\n      commit using its content as the message. The diff below is exactly what\n      that commit will contain: `it.retainedDiff`, the changes THIS process\n      made (its trace/retry boundary onward). For a normal build cycle that is\n      the whole feature; for a `gtd review` process it is only the fixes made\n      during the review — NOT the changeset that was under review.\n      <% if (it.retainedDiff.trim()) { %>\n\n      Write `<%= it.vars.commitMsgFile %>` with ONE conventional-commits message\n      for the changes below (subject line `type(scope): subject`, imperative\n      mood, <= 72 characters; a body explaining the why, trade-offs, and key\n      decisions). Plain text, no markdown wrapper.\n\n      ## Retained diff\n\n      ```diff\n      <%~ it.retainedDiff %>\n      ```\n      <% } else { %>\n\n      This process retained NO changes (a clean review sign-off with no fixes).\n      Write `<%= it.vars.commitMsgFile %>` with exactly this one line and\n      nothing else:\n\n      chore: human review\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(it.vars.commitMsgFile) %>\n\n      Token cost: <%= it.processCost %>\n      <% it.processCostByModel.forEach(function(m){ %>\n      - <%= m.model %>: <%= m.cost %>\n      <% }) %>\n";
 //#endregion
 //#region src/workflows/templates.ts
 /**
@@ -203537,8 +203599,6 @@ function getWellformedEdit(textEdit) {
 	};
 	return textEdit;
 }
-//#endregion
-//#region src/OpenQuestions.ts
 const OPEN_QUESTIONS_HEADING = "## Open Questions";
 const ANSWERED_QUESTIONS_HEADING = "## Answered Questions";
 /**
@@ -203587,15 +203647,62 @@ const splitQuestionBlocks = (lines, start) => {
 	}
 	return blocks;
 };
+/** A markdown task-list checkbox line: `- [ ]` / `- [x]` / `* [X]`, optional leading indent, optional trailing text. */
+const CHECKBOX_RE = /^\s*[-*]\s*\[([ xX])\]\s?(.*)$/;
+/**
+* Extracts the checkbox options from a question block's body, in document
+* order. The LAST option is the free-text slot (`freeText: true`); its text is
+* normalized to `""` when it still carries the unfilled `FREE_TEXT_PLACEHOLDER`.
+* `bodyStart` is the absolute 0-based line index of `body[0]` (the line right
+* after the `###` heading), so each option carries its true source line.
+*/
+const parseOptions = (body, bodyStart) => {
+	const raw = [];
+	body.forEach((line, i) => {
+		const match = CHECKBOX_RE.exec(line);
+		if (!match) return;
+		raw.push({
+			checked: match[1] !== " ",
+			text: match[2].trim(),
+			sourceLine: bodyStart + i
+		});
+	});
+	const lastIndex = raw.length - 1;
+	return raw.map((option, i) => {
+		const freeText = i === lastIndex;
+		const normalized = freeText && option.text.trim().toLowerCase() === "_your answer_" ? "" : option.text;
+		return {
+			checked: option.checked,
+			text: normalized,
+			freeText,
+			sourceLine: option.sourceLine
+		};
+	});
+};
+/**
+* An OPEN question is answered iff EXACTLY ONE option is ticked and — when that
+* option is the free-text slot — its (placeholder-normalized) text is non-empty.
+* Zero ticks (unanswered), two+ ticks (ambiguous), or a ticked-but-empty
+* free-text slot all read as not answered.
+*/
+const isAnswered = (options) => {
+	const ticked = options.filter((o) => o.checked);
+	if (ticked.length !== 1) return false;
+	const chosen = ticked[0];
+	return !(chosen.freeText && chosen.text.length === 0);
+};
 /** Parses one question block into a well-formed `OpenQuestion`, or an error message. */
 const parseQuestionBlock = (block, status) => {
 	if (block.question.length === 0) return { error: "An '### ' question heading under '## Open Questions' or '## Answered Questions' has no question text" };
 	const firstNonBlank = block.body.map((line) => line.trim()).find((line) => line.length > 0) ?? "";
+	const options = status === "open" ? parseOptions(block.body, block.headingLine + 1) : [];
 	return {
 		question: block.question,
 		status,
 		text: firstNonBlank,
-		headingLine: block.headingLine
+		headingLine: block.headingLine,
+		options,
+		answered: status === "open" && options.length > 0 && isAnswered(options)
 	};
 };
 /**
@@ -203780,8 +203887,11 @@ const parseReviewDoc = (content) => {
 * declaring state wins a path conflict, logged as a warning. Config is
 * (re)loaded lazily, fresh per request (no watcher, no cache — v1). A path
 * this map doesn't cover (or no config at all) falls back to today's basename
-* dispatch (`TODO.md` → `qa`, `REVIEW.md` → `review`), so the server still
-* works standalone with no `.gtdrc` in sight.
+* dispatch (`REVIEW.md` → `review`), so the server still works standalone with
+* no `.gtdrc` in sight. (`.gtd/TODO.md` is NOT dispatched by basename — the
+* bundled template's simple flow iterates on a free-form plan there, not a
+* `qa`-format file; a custom workflow that wants qa validation on TODO.md
+* declares it with `file:`+`mode: qa`, which the config-driven map covers.)
 *
 * KNOWN LIMITATION — this server understands only the two BUILT-IN modes
 * (`qa`/`review`, whose parsers it owns). A workflow-declared mode (a `modes:`
@@ -203824,20 +203934,37 @@ const spanRange = (lines, startLine, endLine) => ({
 		character: (lines[endLine] ?? "").length
 	}
 });
-const statusMarker = (status) => status === "answered" ? "[answered]" : "[open]";
-/** Document symbols for `.gtd/TODO.md`'s open questions. */
+/**
+* The outline marker for one question. Answered-section questions are
+* `[answered]`. An OPEN question is `[answered]` once exactly one option is
+* ticked (see `OpenQuestion.answered`) and `[unanswered]` otherwise — so the
+* `[unanswered]` entries are exactly the questions still blocking the
+* answer-completeness gate, navigable straight from the outline.
+*/
+const statusMarker = (question) => {
+	if (question.status === "answered") return "[answered]";
+	return question.answered ? "[answered]" : "[unanswered]";
+};
+/** Document symbols for a `qa`-mode file's open/answered questions (each option a navigable child of an open question). */
 const questionSymbols = (content) => {
 	const { questions } = parseOpenQuestions(content);
 	const lines = content.split(/\r?\n/);
 	return questions.map((question, i) => {
 		const start = question.headingLine;
 		const end = Math.max(start, (questions[i + 1]?.headingLine ?? lines.length) - 1);
+		const children = question.options.map((option) => ({
+			name: `${option.checked ? "[x]" : "[ ]"} ${option.text || "your answer"}`,
+			kind: import_main.SymbolKind.Boolean,
+			range: lineRange(lines, option.sourceLine),
+			selectionRange: lineRange(lines, option.sourceLine)
+		}));
 		return {
-			name: `${statusMarker(question.status)} ${question.question}`,
+			name: `${statusMarker(question)} ${question.question}`,
 			detail: question.text,
 			kind: import_main.SymbolKind.Boolean,
 			range: spanRange(lines, start, end),
-			selectionRange: lineRange(lines, start)
+			selectionRange: lineRange(lines, start),
+			...children.length > 0 ? { children } : {}
 		};
 	});
 };
@@ -203853,12 +203980,7 @@ const questionDiagnostics = (content) => {
 		source: "gtd"
 	}));
 };
-const hunkLabel = (file) => {
-	const box = file.checked ? "[x]" : "[ ]";
-	const location = file.line !== void 0 ? `${file.path}#${file.line}` : file.path;
-	return file.note ? `${box} ${location} — ${file.note}` : `${box} ${location}`;
-};
-/** Document symbols for `.gtd/REVIEW.md`'s chunks (the user-facing "work packages") and their hunks. */
+/** Document symbols for `.gtd/REVIEW.md`: only the headlines of chunks (the user-facing "work packages") that still carry at least one unchecked hunk — the outline is the list of packages left to review, nothing else. */
 const reviewSymbols = (content) => {
 	const { changesets } = parseReviewDoc(content);
 	const lines = content.split(/\r?\n/);
@@ -203866,20 +203988,14 @@ const reviewSymbols = (content) => {
 		const start = chunk.headingLine;
 		const end = Math.max(start, (changesets[i + 1]?.headingLine ?? lines.length) - 1);
 		const checkedCount = chunk.files.filter((file) => file.checked).length;
-		const children = chunk.files.map((file) => ({
-			name: hunkLabel(file),
-			kind: import_main.SymbolKind.Boolean,
-			range: lineRange(lines, file.sourceLine),
-			selectionRange: lineRange(lines, file.sourceLine)
-		}));
 		return {
 			name: `${chunk.title} (${checkedCount}/${chunk.files.length})`,
 			kind: import_main.SymbolKind.Package,
 			range: spanRange(lines, start, end),
 			selectionRange: lineRange(lines, start),
-			children
+			unchecked: checkedCount < chunk.files.length
 		};
-	});
+	}).filter((symbol) => symbol.unchecked).map(({ unchecked: _unchecked, ...symbol }) => symbol);
 };
 /** 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) => {
@@ -203979,6 +204095,67 @@ const reviewCodeActions = (uri, content, range) => {
 	});
 	return actions;
 };
+/** Flips the `[ ]`/`[x]` box of the checkbox on line `line`, preserving the rest of the line exactly. `undefined` when the line has no checkbox. */
+const toggleOptionEdit = (content, line) => {
+	const raw = content.split(/\r?\n/)[line];
+	if (raw === void 0) return void 0;
+	const match = /\[([ xX])\]/.exec(raw);
+	if (!match) return void 0;
+	const character = match.index + 1;
+	return {
+		range: {
+			start: {
+				line,
+				character
+			},
+			end: {
+				line,
+				character: character + 1
+			}
+		},
+		newText: match[1] === " " ? "x" : " "
+	};
+};
+/** The edits that make `option` the sole ticked option in `question` (radio semantics): check it, and uncheck any already-ticked sibling — so the question ends with exactly one tick (what the completeness gate wants). */
+const pickOptionEdits = (content, question, option) => {
+	const edits = [];
+	for (const sibling of question.options) {
+		if (sibling.sourceLine !== option.sourceLine && !sibling.checked) continue;
+		const edit = toggleOptionEdit(content, sibling.sourceLine);
+		if (edit) edits.push(edit);
+	}
+	return edits;
+};
+/** The single code action for the option line the cursor sits on: uncheck it if ticked, else pick it (radio). `undefined` when there is no edit to make. */
+const optionCodeAction = (uri, content, question, option) => {
+	const edits = option.checked ? [toggleOptionEdit(content, option.sourceLine)].filter((e) => e !== void 0) : pickOptionEdits(content, question, option);
+	if (edits.length === 0) return void 0;
+	return {
+		title: option.checked ? "gtd: uncheck this option" : "gtd: pick this option",
+		kind: import_main.CodeActionKind.QuickFix,
+		edit: { changes: { [uri]: edits } }
+	};
+};
+/**
+* Code actions for a `qa`-mode file: on an open question's option line, "pick
+* this option" (radio semantics — check it and uncheck every sibling in the
+* same question, so exactly one stays ticked) or "uncheck this option" when it
+* is already the chosen one. No action off an option line, or on an
+* answered-section (prose) question.
+*/
+const questionCodeActions = (uri, content, range) => {
+	const { questions } = parseOpenQuestions(content);
+	const cursorLine = range.start.line;
+	const actions = [];
+	for (const question of questions) {
+		if (question.status !== "open") continue;
+		const option = question.options.find((o) => o.sourceLine === cursorLine);
+		if (!option) continue;
+		const action = optionCodeAction(uri, content, question, option);
+		if (action) actions.push(action);
+	}
+	return actions;
+};
 /**
 * Go-to-definition target for a `.gtd/REVIEW.md` hunk line: the file the hunk
 * pointer at `line` (0-based, `params.position.line`) points into. `root` is
@@ -204013,9 +204190,8 @@ const hunkDefinitionLocation = (content, line, root) => {
 		}
 	};
 };
-/** The basename dispatch this server has always had — the fallback for any path the active workflow's `file:` map doesn't cover (or when no config resolves at all). */
+/** The basename dispatch this server has always had — the fallback for any path the active workflow's `file:` map doesn't cover (or when no config resolves at all). `TODO.md` is intentionally NOT mapped: the bundled template's simple flow now iterates on a free-form plan there, not a `qa`-format file. */
 const basenameFallbackMode = (name) => {
-	if (name === "TODO.md") return "qa";
 	if (name === "REVIEW.md") return "review";
 };
 /**
@@ -204204,8 +204380,11 @@ const startLspServer = () => gen(function* () {
 		const document = documents.get(params.textDocument.uri);
 		if (!document) return [];
 		const map = await loadModeMap(rootFor(document.uri), warn);
-		if (modeForDocument(document.uri, map) !== "review") return [];
-		return reviewCodeActions(document.uri, document.getText(), params.range);
+		switch (modeForDocument(document.uri, map)) {
+			case "review": return reviewCodeActions(document.uri, document.getText(), params.range);
+			case "qa": return questionCodeActions(document.uri, document.getText(), params.range);
+			default: return [];
+		}
 	});
 	connection.onDefinition(async (params) => {
 		const document = documents.get(params.textDocument.uri);
@@ -204271,7 +204450,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 — `grilling-answer`,
+* to `_` (state names may carry hyphens — `plan-review`,
 * `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
@@ -204454,6 +204633,10 @@ Commands:
                    review-entry state (reviewEntry: true), reviewing
                    <commitish>..HEAD — e.g. a colleague's PR branch. Requires
                    a clean tree resting at the workflow's initial state
+  fix              Start a NEW process at the workflow's declared fix-entry
+                   state (fixEntry: true) that goes straight into repairing the
+                   current failing tests. Requires a clean tree resting at the
+                   workflow's initial state
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   status           Print the resolved rest's state/actor and which declared
@@ -204667,6 +204850,7 @@ const stepAsActor = (invoker, cost, model) => gen(function* () {
 	yield* enforceSteeringGate(worktree.read, invoker, rest, context, decision.kind);
 	yield* enforceReviewSignoffGate(worktree.read, invoker, rest, context, changes, decision.kind);
 	yield* enforceFeedbackProgressGate(invoker, rest, context, changes, decision.kind);
+	yield* enforceAnswerCompletenessGate(worktree.read, invoker, rest, context, decision.kind);
 	const outcome = yield* executeDecision(git, run, executable, context, cost, model);
 	return {
 		state: rest.state,
@@ -204740,6 +204924,40 @@ const runReviewCommand = (argv, json, write) => gen(function* () {
 	else write(`committed: ${subject}\n`);
 });
 /**
+* `gtd fix`: start a brand NEW process at the active workflow's declared
+* `fixEntry: true` state (see `PatternMachine.fixEntryStateOf`), which goes
+* straight into repairing the current failing tests. Mirrors `runReviewCommand`
+* but simpler — it takes no argument and writes NO `Gtd-Review-Base:` trailer:
+* the fix process reviews its own fixes from the ordinary process start, so a
+* plain empty turn commit (`gtd(human): <fix-entry-state>`) is all it needs.
+* `computeProcessRun` then treats that commit as the process's first turn like
+* any other, and the shared health/review/squash tail runs unmodified.
+*
+* Any failure below is a plain refusal: nothing is written.
+*
+* a. The machine must currently rest at the workflow's INITIAL state — a
+*    dedicated `gtd fix` entry is distinct from the "no active cycle" rest, and
+*    a process already underway refuses (finish or abandon it first).
+* b. The working tree must be clean — the fixes belong to their own process.
+* c. The active workflow must declare a `fixEntry: true` state.
+*/
+const runFixCommand = (argv, json, write) => gen(function* () {
+	yield* rejectExtraArgs("fix", argv);
+	const git = yield* GitService;
+	const rest = yield* resolveRest();
+	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd fix: a process is already underway (resting at "${rest.state}") — finish or abandon it before starting a fix`));
+	if ((yield* pendingChanges(git)).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd fix: the working tree must be clean before starting a fix"));
+	const entryState = fixEntryStateOf(rest.def);
+	if (entryState === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd fix: the active workflow declares no fix entry state"));
+	const subject = stateSubject("human", entryState);
+	yield* git.commitAsIs(subject);
+	if (json) write(JSON.stringify({
+		state: entryState,
+		subject
+	}) + "\n");
+	else write(`committed: ${subject}\n`);
+});
+/**
 * 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`
@@ -204930,6 +205148,53 @@ const enforceFeedbackProgressGate = (invoker, rest, context, changes, kind) => g
 	});
 	if (verdict.kind === "refuse") return yield* fail$2(new Error(verdict.reason));
 });
+/** The `mode:` name of gtd's built-in open-questions checkbox format — the only mode the answer-completeness gate below acts on. */
+const QA_MODE = "qa";
+/**
+* The PURE core of the answer-completeness gate (see
+* `enforceAnswerCompletenessGate`). Parses the working-tree `content` of a
+* `qa`-mode file and refuses when any OPEN question is not answered — EXACTLY
+* ONE checkbox ticked, and (for a ticked free-text slot) non-empty text (see
+* `OpenQuestions.answered`). An open question with NO checkbox options is also
+* unanswered — a decision can't have been made on it. Zero remaining open
+* questions (the section was deleted, or the agent surfaced none) allows the
+* step: that is BOTH the tick-then-loop path and the clean advance / accept-all
+* escape. Kept separate from the Effect so it is directly unit-tested (see
+* program.test.ts).
+*/
+const classifyAnswerCompleteness = (input) => {
+	const unanswered = parseOpenQuestions(input.content).questions.filter((q) => q.status === "open").filter((q) => !q.answered);
+	if (unanswered.length === 0) return { kind: "allow" };
+	const list = unanswered.map((q) => `  - ${q.question}`).join("\n");
+	return {
+		kind: "refuse",
+		reason: `gtd step ${input.invoker}: ${unanswered.length} open question(s) in ${input.file} not answered at "${input.stateName}" — tick exactly one option per question (or delete a question you don't want to answer, or delete the whole "## Open Questions" section to accept the plan as-is):\n${list}`
+	};
+};
+/**
+* The answer-completeness gate (edge, like the sign-off gate above). At an
+* `answerGate: true` state with `mode: qa` (the unified template's
+* `adv-grilling-answer`/`architecting-answer`), a human step is refused unless
+* every open question in the file is answered — the pure
+* `classifyAnswerCompleteness` decides over the WORKING-TREE contents. A no-op
+* when the state is not an answer gate (so the agent's own authoring step, which
+* writes all-unticked options, is never gated), the mode isn't `qa`, or the
+* decision is a squash/no-op.
+*/
+const enforceAnswerCompletenessGate = (worktreeRead, invoker, rest, context, kind) => gen(function* () {
+	if (kind !== "commit") return;
+	if (!isAnswerGateState(rest.def, rest.state) || rest.stateDef.mode !== QA_MODE) return;
+	const file = yield* renderFile(rest.stateDef, context);
+	if (file === void 0) return;
+	const current = yield* try_(() => worktreeRead(file)).pipe(catchAll(() => succeed$3("")));
+	const verdict = classifyAnswerCompleteness({
+		file,
+		stateName: rest.state,
+		invoker,
+		content: current
+	});
+	if (verdict.kind === "refuse") return yield* fail$2(new Error(verdict.reason));
+});
 /**
 * `gtd validate [--json]`: format (in place) then validate the steering file
 * the resolved rest declares (`file:` rendered, `mode:` selecting how), over
@@ -205057,6 +205322,7 @@ const runMermaidCommand = (argv, json, write) => gen(function* () {
 const KNOWN_SUBCOMMANDS = [
 	"step",
 	"review",
+	"fix",
 	"next",
 	"status",
 	"validate",
@@ -205128,6 +205394,7 @@ const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 	switch (sub) {
 		case "step": return runStepCommand(argv, json, write, cost, model);
 		case "review": return runReviewCommand(argv, json, write);
+		case "fix": return runFixCommand(argv, json, write);
 		case "next": return runNextCommand(json, write);
 		case "status": return runStatusCommand(argv, json, write);
 		case "validate": return runValidateCommand(argv, json, write);
@@ -205142,8 +205409,9 @@ const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 * this with no arguments; the test world supplies an in-memory layer set and
 * captures stdout via the `write` callback.
 *
-* v3 command surface: `step <actor>` / `next` / `status` / `validate` /
-* `mermaid` (see `src/Edge.ts` and `docs/design/pattern-machine-plan.md` §3),
+* v3 command surface: `step <actor>` / `review <commitish>` / `fix` / `next` /
+* `status` / `validate` / `mermaid` (see `src/Edge.ts` and
+* `docs/design/pattern-machine-plan.md` §3),
 * plus `lsp` and `init` — both dispatched before the config-reading
 * path since they must work with no workflow configured yet. Bare `gtd` or an
 * unknown subcommand is a usage error. Shared setup (argv parsing, the

package/docs/cli.md

@@ -21,6 +21,10 @@ Commands:
                    review-entry state (reviewEntry: true), reviewing
                    <commitish>..HEAD — e.g. a colleague's PR branch. Requires
                    a clean tree resting at the workflow's initial state
+  fix              Start a NEW process at the workflow's declared fix-entry
+                   state (fixEntry: true) that goes straight into repairing the
+                   current failing tests. Requires a clean tree resting at the
+                   workflow's initial state
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   status           Print the resolved rest's state/actor and which declared
@@ -69,12 +73,15 @@ default workflow, so this is the one-time setup step for a repo; a state command
 run before it fails with `gtd: no workflow configured — run \`gtd init\` to
 create .gtdrc.json`.
 
-The unified template has three entry points into one shared review/squash tail
-(see [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)): creating
-`.gtd/TODO.md` starts the simple flow (grilling → building → checking), creating
+The unified template has four entry points — each behind a green-baseline gate
+that runs the suite before starting — into one shared review/squash tail (see
+[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)): creating
+`.gtd/TODO.md` starts the simple flow (planning → building → checking), creating
 `.gtd/REQUIREMENTS.md` starts the advanced flow (two-phase Q&A planning,
-per-package parallel build, agentic spec-review), and `gtd review <commitish>`
-enters review directly.
+per-package parallel build, agentic spec-review), `gtd review <commitish>`
+enters review directly, and `gtd fix` goes straight into repairing failing
+tests. A red baseline halts at a `*-start-blocked` gate rather than starting new
+work.
 
 The file is written **uncommitted**; review and commit it before your first
 `gtd step` (an uncommitted `.gtdrc.json` is a pending change the initial state
@@ -119,7 +126,7 @@ to `--json`.
 Plain-mode output is one line:
 
 ```
-committed: gtd(human): idle → grilling
+committed: gtd(human): idle → planning
 ```
 
 or, at a no-op:
@@ -135,7 +142,7 @@ not passed):
 ```json
 {
   "state": "idle",
-  "subject": "gtd(human): idle → grilling",
+  "subject": "gtd(human): idle → planning",
   "cost": 1450,
   "model": "claude-opus-4-8"
 }
@@ -175,7 +182,7 @@ at `<commitish>..HEAD` (see
 Plain-mode output is one line, same shape as `gtd step`:
 
 ```
-committed: gtd(human): reviewing
+committed: gtd(human): review-start-check
 ```
 
 `--json` emits `{state, subject}` — `state` is the entered review-entry state,
@@ -184,6 +191,43 @@ committed: gtd(human): reviewing
 Takes exactly one positional argument (`<commitish>`); missing or extra
 arguments are usage errors.
 
+In the bundled unified template the review-entry state is `review-start-check` —
+a green-baseline gate that runs the suite and, once green, transitions to
+`reviewing`; a red run halts at `review-start-blocked` (see
+[STATES.md §10](../STATES.md#10-the-bundled-workflow-template)).
+
+## `gtd fix [--json]`
+
+Starts a BRAND NEW process at the active workflow's declared `fixEntry: true`
+state (see [STATES.md §10](../STATES.md#10-the-bundled-workflow-template)) that
+goes straight into repairing the current failing tests. It is the standalone
+counterpart to the entry gates: the gates refuse to start new work on a red
+baseline, and `gtd fix` is the dedicated way to get back to green — repair,
+review, and squash a broken baseline into one commit.
+
+Requires, in order (any failure is a plain refusal — exit non-zero, nothing
+written):
+
+- the machine currently resting at the workflow's **initial state** (a process
+  already underway refuses);
+- a **clean working tree**;
+- the active workflow declaring a **`fixEntry: true`** state (otherwise:
+  `gtd fix: the active workflow declares no fix entry state`).
+
+Takes no positional argument (extra arguments are a usage error). Unlike
+`gtd review`, it writes NO `Gtd-Review-Base:` trailer — a fix reviews its own
+fixes from the ordinary process start — so on success it writes just one empty
+commit, `gtd(human): <fix-entry-state>`:
+
+```
+committed: gtd(human): fix-check
+```
+
+`--json` emits `{state, subject}`, same shape as `gtd review`. In the bundled
+unified template the fix-entry state is `fix-check`: a red suite drops into the
+shared `fixing` loop and out through the review + squash tail; a green suite is
+a no-op back to `idle`.
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -341,7 +385,7 @@ agent or human:
   declares `file:`+`mode:` formats that file in place and validates it first
   (with the very same mode commands), and **refuses the step** (committing
   nothing) when it is invalid — so a human's edit at a gate (answering at
-  `grilling-answer`, reviewing at `await-review`) is formatted and checked
+  `adv-grilling-answer`, reviewing at `await-review`) is formatted and checked
   exactly like an agent's draft, and a malformed steering file is never
   committed.
 
@@ -365,10 +409,10 @@ output is identical regardless of the current process/branch state.
 $ gtd mermaid
 stateDiagram-v2
     state "idle" as idle
-    state "grilling" as grilling
+    state "planning" as planning
     ...
     [*] --> idle
-    idle --> grilling : * **
+    idle --> planning : * **
     ...
     note right of idle : human · message
     ...
@@ -381,7 +425,7 @@ Mermaid-aware renderer (GitHub, GitLab, VS Code, Obsidian, the
 
 State names are aliased to Mermaid-safe identifiers (non-word characters fold to
 `_`; a digit-led name gets an `s_` prefix) via a `state "<name>" as <alias>`
-declaration up front, so a hyphenated name like `grilling-answer` still displays
+declaration up front, so a hyphenated name like `plan-review` still displays
 with its exact declared spelling. Rejects `--json` (exit 1,
 `gtd mermaid does not accept --json`) — there is no structured shape to emit
 beyond the Mermaid source itself — and takes no arguments (extra positional args
@@ -390,13 +434,14 @@ are rejected).
 ## `gtd lsp`
 
 Starts an LSP server over stdio for `.gtd/` steering files — document symbols
-for a `qa`-mode file's open questions and a `review`-mode file's review
-chunks/hunks, code actions to check/uncheck a hunk or a whole chunk,
-go-to-definition (`textDocument/definition`) from a `review`-mode hunk pointer
-line into the file it points at (at its 1-based `#line`, or the top of the file
-for a bare `./path`; the `./`-relative path resolves against the repo's git
-toplevel), and diagnostics publishing the same parser findings `gtd validate`
-reports (see `src/OpenQuestions.ts` / `src/ReviewDoc.ts` and
+for a `qa`-mode file's open questions and, for a `review`-mode file, one symbol
+per chunk that still has an unchecked hunk (the outline lists only the packages
+left to review, with no hunk children), code actions to check/uncheck a hunk or
+a whole chunk, go-to-definition (`textDocument/definition`) from a `review`-mode
+hunk pointer line into the file it points at (at its 1-based `#line`, or the top
+of the file for a bare `./path`; the `./`-relative path resolves against the
+repo's git toplevel), and diagnostics publishing the same parser findings
+`gtd validate` reports (see `src/OpenQuestions.ts` / `src/ReviewDoc.ts` and
 [STATES.md §12](../STATES.md#12-steering-file-validation-gtd-validate)).
 
 **Config-driven** (see

package/docs/configuration.md

@@ -156,7 +156,7 @@ workflow:
             "Delete `.gtd/REVIEW.md` to approve the whole cycle and rest at
             idle."
         "* **":
-          to: grilling
+          to: planning
           describe:
             "Change any source file to leave feedback and start another round."
 ```
@@ -214,18 +214,18 @@ Forbidden on a commit state (never at rest):
 ```yaml
 workflow:
   states:
-    grilling:
+    planning:
       actor: agent
       memory: plan
-      prompt: develop the plan; ask open questions
+      prompt: develop the sketch into a concrete plan
       on:
-        "* **": grilling-answer
-    grilling-answer:
+        "* **": plan-review
+    plan-review:
       actor: human
-      message: answer the open questions
+      message: accept the plan, or edit it to iterate
       on:
         "C": building
-        "* **": grilling
+        "* **": planning
     building:
       actor: agent
       memory: build # a different scope — implementation starts fresh
@@ -236,7 +236,7 @@ workflow:
       commit: "feat: done"
 ```
 
-Because `grilling` re-enters itself around the answer loop, every lap emits
+Because `planning` re-enters itself around the review loop, every lap emits
 `memory: plan` and the planner keeps its accumulated exploration; the move to
 `building` emits a different label (`build`), which is where the driver clears
 memory for a fresh implementation turn. A loop of same-labelled turns retains; a
@@ -282,10 +282,10 @@ workflow:
 **steering-file mode**. Two names are BUILT IN, each carrying a VALIDATOR gtd
 implements itself:
 
-| `mode`   | Format                                                                                                                                                                                                  |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `qa`     | The open-questions format (`## Open Questions` near the top and `## Answered Questions` at the bottom, one `###` sub-heading per question with a free-form body; status is positional, no marker line). |
-| `review` | The checkbox review format (`# Review: <hash>` header, `<!-- base: <hash> -->` comment, `##` chunks, `- [ ]` pointers).                                                                                 |
+| `mode`   | Format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `qa`     | The open-questions format (`## Open Questions` near the top and `## Answered Questions` at the bottom, one `###` sub-heading per question with a free-form body; status is positional, no marker line). The bundled advanced flow additionally writes each open question as a checkbox list (candidate answers + a `- [ ] _your answer_` slot) and gates the human's answer step with `answerGate` (exactly one tick per question) — but that convention + gate live in the workflow/edge, not in this validator, which only checks the structure above. |
+| `review` | The checkbox review format (`# Review: <hash>` header, `<!-- base: <hash> -->` comment, `##` chunks, `- [ ]` pointers).                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 Any other name must be declared in a `modes:` map (next section) — as must a
 `format:` command for these two, since gtd ships no formatter. A `mode:` naming
@@ -482,7 +482,39 @@ parent is a non-workflow commit, so the ordinary boundary rule already stops
 there. See [STATES.md §11](../STATES.md#11-the-review-checkout-window) for the
 full mechanism.
 
-The bundled default enables `reviewEntry: true` on `reviewing` itself.
+The bundled default enables `reviewEntry: true` on `review-start-check` — the
+green-baseline gate in front of `reviewing`.
+
+### `fixEntry:` — the fix entry point (`gtd fix`)
+
+A state may declare `fixEntry: true` (at most one across the whole workflow;
+forbidden on a commit state and on the initial state — the same rule family as
+`reviewEntry`). It marks the state [`gtd fix`](cli.md#gtd-fix---json) enters to
+start a BRAND NEW process that goes straight into repairing the current failing
+tests.
+
+```yaml
+workflow:
+  states:
+    # …
+    fix-check:
+      actor: check
+      fixEntry: true # `gtd fix` starts a new process here
+      script: <%~ it.vars.testCommand %> || echo fail > .gtd/FEEDBACK.md
+      on:
+        "A .gtd/FEEDBACK.md": fixing # red -> repair loop
+        "C": idle # green -> nothing to fix
+```
+
+`gtd fix` requires resting at the workflow's initial state with a clean tree,
+and requires the active workflow to declare a `fixEntry` state. Unlike
+`gtd review`, it writes NO `Gtd-Review-Base:` trailer — a fix reviews its own
+fixes from the ordinary process start — so it simply writes one empty
+`gtd(human): <fix-entry-state>` turn commit and lets the workflow's own `on`
+routing take over. The bundled default enables `fixEntry: true` on `fix-check`:
+a red suite drops into the shared `fixing` loop and out through the review +
+squash tail; a green suite is a no-op back to `idle`. See
+[STATES.md §10](../STATES.md#10-the-bundled-workflow-template).
 
 ### Template variables
 
@@ -720,8 +752,8 @@ The one bundled template has three entry points into a shared review/squash tail
 (all walked through in
 [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)):
 
-- **the simple flow** — creating `.gtd/TODO.md` starts idle → grilling ⇄
-  grilling-answer → building → checking ⇄ fixing (→ escalate) → reviewing →
+- **the simple flow** — creating `.gtd/TODO.md` starts idle → planning ⇄
+  plan-review → building → checking ⇄ fixing (→ escalate) → reviewing →
   await-review.
 - **the advanced flow** — creating `.gtd/REQUIREMENTS.md` starts the fuller
   machine: two-phase Q&A planning (product then architecture), package

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

@@ -84,11 +84,13 @@ same `file:`/`mode:` annotations (it is the LSP-heavy flow), including
   (vars-layer context; the LSP process's env supplies `GTD_VAR_` overrides like
   any invocation), and build a map of absolute rendered paths → mode. Document
   features dispatch on that map: `qa` files get question symbols + parser-error
-  diagnostics; `review` files get chunk/hunk symbols + check/uncheck code
-  actions + diagnostics. Conflicting modes for one path: first declaring state
-  wins, log a warning. **Fallback:** when NO config resolves (or a `.gtd` file
-  isn't mapped), keep today's basename dispatch (`TODO.md` → qa, `REVIEW.md` →
-  review) so the server still works standalone.
+  diagnostics; `review` files get one headline symbol per chunk that still has
+  an unchecked hunk (an outline of the packages left to review — no hunk
+  children) + check/uncheck code actions + diagnostics. Conflicting modes for
+  one path: first declaring state wins, log a warning. **Fallback:** when NO
+  config resolves (or a `.gtd` file isn't mapped), keep today's basename
+  dispatch (`TODO.md` → qa, `REVIEW.md` → review) so the server still works
+  standalone.
 - **The jump command returns:** `gtd.openSteeringFile` — resolve the CURRENT
   state exactly like the CLI (config + git HEAD via the existing Edge helpers;
   this re-adds the git/config wiring the v2 server had), render its `file:`, and

package/docs/upgrading.md

@@ -132,8 +132,8 @@ gtd init      # takes no argument
 `gtd init` (no argument) writes a `.gtdrc.json` for the single bundled
 **unified** template (its agent prompts extracted to editable `gtd-prompts/*.md`
 files the config references). The template forks on which steering file you
-create: `.gtd/TODO.md` starts the **simple flow** (a single-shot `grilling`
-plan, direct `building`, a `checking`/`fixing` loop), while
+create: `.gtd/TODO.md` starts the **simple flow** (a `planning` ⇄ `plan-review`
+plan-iteration loop, direct `building`, a `checking`/`fixing` loop), while
 `.gtd/REQUIREMENTS.md` starts the **advanced flow** (two-phase grilling ⇄
 grilling-answer / architecting ⇄ architecting-answer / decompose / picking /
 per-package build with an agentic spec-review gate). Both converge on the same

package/package.json

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

package/schema.json

@@ -141,6 +141,10 @@
                 "type": "boolean",
                 "description": "Marks the (at most one) state `gtd review <commitish>` enters to start a brand new process reviewing <commitish>..HEAD. Forbidden on a commit state and on the initial state."
               },
+              "fixEntry": {
+                "type": "boolean",
+                "description": "Marks the (at most one) state `gtd fix` enters to start a brand new process that goes straight into repairing the current failing tests. Forbidden on a commit state and on the initial state."
+              },
               "requireProgress": {
                 "type": "boolean",
                 "description": "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."