@pmelab/gtd 4.0.0 → 5.1.0

package/README.md

@@ -62,29 +62,34 @@ Four commands drive it:
   transition the pending changes match.
 - **`gtd next [--json]`** — print whichever actor is awaited and what they
   should do, without mutating anything.
-- **`gtd run`** — execute the awaited script (the only place gtd itself spawns a
-  subprocess), then step its actor.
 - **`gtd status`** — a dry-run report of the resolved state and which pattern
   each pending change matches.
+- **`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.
 
 The loop is one beat, repeated: run `gtd next --json` and dispatch on `kind` —
-`"message"` means it's a human's move (stop and hand off); `"script"` means
-`gtd run` it; `"prompt"` means feed `content` to your agent, then run
-`gtd step <actor>` once it's done. See [STATES.md](STATES.md) for the model and
-[Driving the loop](docs/loop.md) for the full protocol.
+`"message"` means it's a human's move (stop and hand off); `"script"` means the
+driver runs `content` itself, then steps its actor; `"prompt"` means feed
+`content` to your agent, then run `gtd step <actor>` once it's done. gtd itself
+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.
 
 Along the way, the bundled default workflow develops your sketch into an
 implementation plan — asking any open question it can't settle itself via a
 deterministic `.gtd/TODO.md` format, validated before it ever reaches you —
 builds it, runs your tests (looping on failures), and hands you a
 `.gtd/REVIEW.md` checkbox review of the cycle's diff: tick a box to approve that
-item, or edit/untick for feedback. Approving rests the cycle back at idle, with
-every turn commit still sitting in history for you to squash however you like
-(or not at all; gtd makes no assumption) — see
-[STATES.md](STATES.md#10-the-bundled-default-workflow) for the full shape. A
-heavier machine — two-phase Q&A planning, an architecture phase, task
-decomposition, a per-task build loop, and a squash finale — is preserved as a
-copy-paste `.gtdrc` example at
+item, or edit/untick for feedback. The same review flow also has a direct entry
+point — `gtd review <commitish>` starts a brand new process reviewing
+`<commitish>..HEAD` with no cycle of its own, e.g. a colleague's PR branch.
+Approving rests the cycle back at idle, with every turn commit still sitting in
+history for you to squash however you like (or not at all; gtd makes no
+assumption) — see [STATES.md](STATES.md#10-the-bundled-default-workflow) for the
+full shape. A heavier machine — two-phase Q&A planning, an architecture phase,
+task decomposition, a per-task build loop, and a squash finale — is preserved as
+a copy-paste `.gtdrc` example at
 [docs/examples/advanced-workflow.md](docs/examples/advanced-workflow.md). The
 workflow itself is just `.gtdrc` config — swap it for your own (see
 [Configuration](docs/configuration.md)).

package/bin/gtd-loop

@@ -4,9 +4,10 @@ set -euo pipefail
 # Drives the v3 pattern-machine loop (see docs/loop.md): each iteration asks
 # `gtd next --json` who's up and what they should do, dispatching on `kind`:
 #   - "message" (a human rest)  -> halt, tell the user what gtd is waiting on.
-#   - "script"  (a check rest) -> `gtd run` executes it and steps the check
-#     actor in one command; zero new commits = green with nothing owed (the
-#     terminal signal at idle).
+#   - "script"  (a check rest) -> execute `content` (the emitted wrapper
+#     script) verbatim via bash — exit code deliberately ignored, the outcome
+#     lives in the tree — then `gtd step <actor>` to capture it; zero new
+#     commits = green with nothing owed (the terminal signal at idle).
 #   - "prompt"  (an agent rest) -> feed `content` to the agent, run the
 #     self-validation gate (`gtd validate`, re-prompting on findings — see the
 #     gate's own comment below), then `gtd step <actor>` ourselves — the
@@ -86,7 +87,12 @@ while true; do
 
   if [[ "$kind" == "script" ]]; then
     head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
-    gtd run
+    # Execute the emitted wrapper verbatim; its exit code is deliberately
+    # ignored (`|| true` under `set -e`) — the script encodes its outcome in
+    # the tree, and `gtd step` captures whatever it left there via the state's
+    # own `on` patterns.
+    bash -c "$content" || true
+    gtd step "$actor" >/dev/null
     head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
     if [[ "$head_before" == "$head_after" ]]; then
       echo "--- Settled ($state: check passed, nothing to do) ---"

package/dist/gtd.bundle.mjs

@@ -189117,6 +189117,10 @@ const isCommitState = (state) => state.commit !== void 0;
 const isReviewWindowState = (def, state) => def.states[state]?.reviewWindow === true;
 /** True when `state` anchors the review window's diff base (see `StateDef.reviewBase`). Safe for an unknown state name (returns `false`). */
 const isReviewBaseState = (def, state) => def.states[state]?.reviewBase === true;
+/** 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;
+};
 /**
 * `gtd(<actor>): <state>` — the subject a step commit carries. Per decision
 * 2, `<actor>` is WHO AUTHORED THE STEP (the invoker), and `<state>` is the
@@ -189445,6 +189449,29 @@ const validateReviewWindow = (name, state) => {
 	if (state.reviewBase !== void 0) errors.push(`state "${name}": a commit state cannot declare "reviewBase"`);
 	return errors;
 };
+/**
+* `reviewEntry`, when present, is forbidden on a commit state (never at
+* rest — same rule family as `reviewWindow`/`reviewBase`) and on the initial
+* state: a review entry is a deliberate, distinct starting point from the
+* workflow's ordinary "no active cycle" rest (`gtd review` itself REQUIRES
+* resting at the initial state before it will act — see `src/program.ts` —
+* so the two must stay distinguishable rather than collapsing into one).
+* The at-most-one-state rule is checked separately, over the whole
+* definition (see `validateReviewEntryUniqueness`), since it isn't a
+* per-state finding.
+*/
+const validateReviewEntry = (name, state) => {
+	if (state.reviewEntry === void 0) return [];
+	const errors = [];
+	if (isCommitState(state)) errors.push(`state "${name}": a commit state cannot declare "reviewEntry"`);
+	if (state.initial === true) errors.push(`state "${name}": the initial state cannot declare "reviewEntry"`);
+	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(", ")})`] : [];
+};
 /** Every `on` row parses, and its target names a defined state. */
 const validateOnEdges = (name, state, names) => {
 	const errors = [];
@@ -189505,7 +189532,8 @@ const validateState = (def, name, names) => {
 		...validateMemory(name, state),
 		...validateFile(name, state),
 		...validateMode(def, name, state),
-		...validateReviewWindow(name, state)
+		...validateReviewWindow(name, state),
+		...validateReviewEntry(name, state)
 	];
 };
 /**
@@ -189527,9 +189555,11 @@ 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; 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`, 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
 * `validateReachability`).
 */
 const validateDefinition = (def) => {
@@ -189540,6 +189570,7 @@ const validateDefinition = (def) => {
 		...initialErrors,
 		...validateModes(def),
 		...names.flatMap((name) => validateState(def, name, names)),
+		...validateReviewEntryUniqueness(def, names),
 		...initialErrors.length === 0 ? validateReachability(def, names) : []
 	];
 };
@@ -189749,7 +189780,8 @@ const KNOWN_STATE_KEYS = /* @__PURE__ */ new Set([
 	"file",
 	"mode",
 	"reviewWindow",
-	"reviewBase"
+	"reviewBase",
+	"reviewEntry"
 ]);
 const KNOWN_TOP_KEYS = /* @__PURE__ */ new Set([
 	"vars",
@@ -189909,7 +189941,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`): `true` only
+* A boolean state flag (`initial`/`reviewWindow`/`reviewBase`/`reviewEntry`): `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.
@@ -189948,7 +189980,8 @@ const assembleStateDef = (parts) => ({
 		file: parts.file,
 		mode: parts.mode,
 		reviewWindow: parts.reviewWindow,
-		reviewBase: parts.reviewBase
+		reviewBase: parts.reviewBase,
+		reviewEntry: parts.reviewEntry
 	}),
 	...assembleContentFields(parts.content)
 });
@@ -189971,7 +190004,8 @@ const compileState = (name, raw, configDir, errors) => {
 		file: compileFile(raw, name, errors),
 		mode: compileMode(raw, name, errors),
 		reviewWindow: compileBooleanFlag(raw, "reviewWindow", name, errors),
-		reviewBase: compileBooleanFlag(raw, "reviewBase", name, errors)
+		reviewBase: compileBooleanFlag(raw, "reviewBase", name, errors),
+		reviewEntry: compileBooleanFlag(raw, "reviewEntry", name, errors)
 	});
 };
 /**
@@ -190028,7 +190062,7 @@ const compileWorkflowConfig = (raw, configDir, rcModes) => {
 * default.yaml's content values start with `./`/`../`, so
 * `compileWorkflowConfig` never resolves a file reference against it.
 */
-const compiled = compileWorkflowConfig((0, import_dist$1.parse)("# The bundled default gtd workflow (v3 \"pattern machine\" — see\n# docs/design/pattern-machine-plan.md, and\n# docs/design/steering-file-validation-command.md for the `gtd validate`\n# self-validation model that replaced the old in-machine validation loops).\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/default.ts does the compiling).\n#\n# Every content string below is INLINE (no `./`-relative file references):\n# the bundled default ships inside a single-file build\n# (`dist/gtd.bundle.mjs`), so its content must already be resolved at BUILD\n# time rather than read from disk at RUNTIME — the same reason\n# `src/prompts/*.md` are imported through tsdown's `.md`-as-text loader\n# instead of read via `fs` at runtime. `default.yaml` itself is imported the\n# same way (tsdown/vitest both treat `.yaml` as text — see\n# tsdown.config.ts / tests/vitest.rawMd.ts), so this file never needs a\n# sibling prompts/ directory to exist on disk once installed.\n#\n# States, in cycle order — 10 states, no squash:\n#   idle (initial, human, message)\n#     -> grilling (agent, prompt): reads .gtd/TODO.md's sketch (or a prior\n#     lap's feedback), explores the codebase, and develops it into a concrete\n#     implementation plan, stating any open question it can't settle itself\n#     under a `## Open Questions` heading rather than guessing silently. Its\n#     `file:`/`mode:` (TODO.md/`qa`) makes the plan's format checkable — it\n#     self-validates before finishing (see \"Steering-file validation\" below).\n#   grilling -> grilling-answer (human, message): tick off suggested\n#     defaults by replacing them with `Answer:` lines; a clean step accepts\n#     every remaining default -> building; any edit loops back to grilling.\n#   grilling-answer -> building (agent, prompt): implements the plan in\n#     .gtd/TODO.md directly (no task decomposition, no per-task queue) and\n#     deletes .gtd/TODO.md once the work is complete and verified.\n#   building -> checking (check, script): runs the test command inline;\n#     A/M .gtd/FEEDBACK.md -> fixing (capped, redirects to escalate); D\n#     .gtd/FEEDBACK.md (a green run that just cleaned up prior feedback) or C\n#     (green, nothing to clean) -> reviewing.\n#   fixing (agent, prompt) <-> checking\n#   escalate (human, message): manual intervention, then back to checking\n#   checking (green) -> reviewing (agent, prompt): writes .gtd/REVIEW.md in\n#     the checkbox review format, grouping the cycle's full diff into\n#     reviewable chunks; its `file:`/`mode:` (REVIEW.md/`review`) makes that\n#     format checkable, so it self-validates before finishing.\n#   reviewing -> await-review (human, message): tick a pointer's `- [\n#     ]` to `- [x]` to approve that item; deleting .gtd/REVIEW.md outright is\n#     the power-user approve-everything shortcut; anything else pending\n#     (code edits with REVIEW.md untouched) is feedback straight to grilling.\n#   await-review -> review-deciding (check, script), entered by any `M\n#     .gtd/REVIEW.md` step: if no unticked `- [ ]` pointer remains, the cycle\n#     is approved (rm .gtd/REVIEW.md -> idle); otherwise the still-unticked\n#     pointers (with their notes) are extracted into a fresh .gtd/TODO.md and\n#     .gtd/REVIEW.md is removed (-> grilling, feedback lap).\n#\n# The cycle ends at human approval, resting back at idle — there is no\n# squash state. The cycle's commits stay in history; whether/how to squash\n# them (amend, interactive rebase, a PR's squash-merge) is entirely the\n# human's business once they're done reviewing — gtd makes no assumption.\n# That squash-flavored finale (a `squashing` prompt state + a `done` commit\n# state) still exists as an ENGINE capability (see STATES.md §8) and is kept\n# as part of the fuller machine at docs/examples/advanced-workflow.md.\n#\n# A `gtd(<actor>): idle` commit — entering the workflow's own initial state —\n# is therefore a PROCESS BOUNDARY (see `computeProcessRun` in src/Edge.ts):\n# the next cycle's `retry` counts, `startCommit`, and diffs never reach back\n# across an approved cycle's own idle-entering commit.\n#\n# HYGIENE INVARIANT (asserted in e2e — see default-workflow.feature): an\n# approved cycle leaves `.gtd/` empty. FEEDBACK.md is cleaned up by a green\n# `checking` run; REVIEW.md by the review-deciding approval branch; TODO.md by\n# `building`.\n#\n# Steering-file validation. `grilling` and `reviewing` each declare a\n# `file:`/`mode:` pair (TODO.md as `qa`, REVIEW.md as `review`), so their\n# output has a checkable format. src/OpenQuestions.ts and src/ReviewDoc.ts are\n# those two formats' EXECUTABLE SPECS (their unit tests are the format spec\n# tests), and `gtd validate` FORMATS the resolved state's rendered `file:` in\n# place then runs the SAME parser over it, exiting non-zero with findings when\n# it violates the format. There is no in-machine validation state and no bash\n# port to keep in sync — the producing agent self-validates before finishing\n# (plain `gtd next` appends the \"run `gtd validate` and fix all violations\"\n# instruction; under `--json` the driving loop runs it after the turn and\n# re-prompts on findings — see skills/loop/SKILL.md), AND `gtd step` runs the\n# same format-and-validate gate on capture, refusing a turn whose steering file\n# is invalid. So the check runs after a human edits too — at the human gates\n# `grilling-answer` (TODO.md) and `await-review` (REVIEW.md) — and a human gate\n# is only ever handed a tidy, well-formed file. The same parsers back the LSP's\n# live diagnostics (src/Lsp.ts).\n#\n# `grilling` and `reviewing` both declare `model: smart` — an opaque harness\n# hint (see the comment at `grilling` below) for their heavier one-shot\n# planning/reviewing turns. Every other state is unset (harness default).\n#\n# The four agent states each declare a `memory:` scope label (`plan`,\n# `build`, `fix`, `review` — see the comment at `grilling` below) — another\n# opaque hint a memory-aware driver reads to decide when an agent turn keeps\n# the previous turn's memory and when it starts fresh: a loop that re-enters\n# one state (grilling around its answer loop, fixing around checking) keeps\n# the same label and retains memory across its laps; crossing to the next\n# phase's differently-labelled state clears it. gtd never interprets the\n# label (see STATES.md §1 and skills/loop/SKILL.md's driver contract).\n#\n# `vars.testCommand` is this workflow's own declared default for `checking`'s\n# script (see it.vars in PatternTemplates.ts) — override it per-repo with a\n# top-level `.gtdrc` `vars: { testCommand: ... }` key, or per-invocation with\n# a `GTD_VAR_testCommand` environment variable (highest precedence).\n#\n# `vars.todoFile`/`reviewFile`/`feedbackFile` are this workflow's ONE source\n# of truth for the three steering-file paths every prompt/script below reads\n# or writes — each appears in templates as `<%~ it.vars.todoFile %>` etc\n# (see docs/design/state-file-association.md §2). Every state that rests on\n# one of these files also declares a `file:`/`mode:` pair (see STATES.md's\n# property table) so `gtd status`/`gtd next --json` and the LSP (`gtd lsp`)\n# know which file a human/editor should look at, and in what format\n# (`qa` for TODO.md's open-questions format, `review` for REVIEW.md's\n# checkbox format) — `fixing`/`escalate` declare `file:` alone (FEEDBACK.md\n# is plain text, no LSP format). KNOWN LIMITATION: `on` pattern keys below are\n# NOT Eta templates — they keep the LITERAL `.gtd/...` paths matching these\n# vars' DEFAULT values. Repointing `todoFile`/`reviewFile`/`feedbackFile` via\n# `.gtdrc`'s top-level `vars:` or a `GTD_VAR_` override changes what `file:`\n# renders to (and what a template reads/writes) WITHOUT changing what the\n# `on` patterns match against — desyncing the machine. See\n# docs/configuration.md's `file:`/`mode:` section for the full caveat.\n#\n# A fuller machine — two-phase Q&A planning, an architecture phase, task\n# decomposition, a deterministic per-task builder loop, agent-prepared\n# review, and the squash finale (`squashing` + `done`) — is preserved as a\n# copy-paste `.gtdrc` example at docs/examples/advanced-workflow.md.\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  reviewFile: .gtd/REVIEW.md\n  feedbackFile: .gtd/FEEDBACK.md\n\nstates:\n  idle:\n    actor: human\n    initial: true\n    # Every human-gate `message:` below closes with the SAME rendered block —\n    # a \"What each change does next\" list built from `it.edges`, the resting\n    # state's own `on` edges (see PatternTemplates.TemplateContext.edges). Each\n    # edge's human-readable route lives in its `describe:` (the single source\n    # of truth), so the list can never drift from the routing it documents.\n    # The block skips edges without a `describe`, and each `<%~ ... \"\\n\" %>`\n    # keeps the bullet's own newline (Eta's autoTrim strips the template's own\n    # line breaks around `<% %>` tags, not text inside an interpolation).\n    message: |\n      No active gtd cycle.\n\n      To start one, write `.gtd/TODO.md` with a short sketch of what you want\n      built — a few sentences is enough.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save your sketch to `.gtd/TODO.md` (any working-tree change) to start\n          the cycle — the agent reads it, explores the codebase, and develops it\n          into a concrete implementation plan (**grilling**).\n\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # `model` is an opaque harness hint — gtd never interprets this string, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so the\n    # driving loop can map it onto whatever models its agent harness\n    # provides. \"smart\" here just names the harness-chosen tier for the\n    # heavier planning turn; states without a `model` use the harness's\n    # default.\n    model: smart\n    # `memory` is an opaque memory-scope label — gtd never interprets it, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so a\n    # memory-aware driving loop can decide when an agent turn continues from\n    # the previous turn's memory and when it starts fresh: consecutive agent\n    # turns that emit the SAME label share memory, a change (or the first\n    # turn) is where the driver starts fresh. `grilling` re-enters itself\n    # around the grilling-answer loop, so labelling every lap\n    # `plan` keeps the planner's accumulated exploration across the loop; the\n    # next phase (`building`) carries a different label, clearing it.\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.todoFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.todoFile %>` holds a short sketch of what to build (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete implementation plan.\n\n      For every question you cannot settle yourself, add it under a\n      `## Open Questions` heading, one `### <question>` sub-heading each,\n      whose body's FIRST non-blank line is exactly\n      `Suggested default: <your answer>` — the human can accept it as-is or\n      override it. Omit the section entirely once there are no open\n      questions. If `<%= it.vars.todoFile %>` already carries\n      `## Open Questions` entries from a previous lap, fold any\n      `Answer: <text>` line into the plan; every remaining entry's body must\n      still start with either `Suggested default: ...` or `Answer: ...` —\n      never anything else.\n\n      Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n      not commit, and do not run `gtd step agent` yourself; the harness does\n      that.\n    on:\n      \"* **\": grilling-answer\n\n  grilling-answer:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.todoFile %>` holds the plan under development, with any\n      open questions under `## Open Questions` — each carrying a suggested\n      default. Answer a question by editing its entry in place: replace its\n      `Suggested default: ...` line with `Answer: ...`, or add further detail.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: building\n        describe: >-\n          Change nothing to accept every suggested default as-is and move on to\n          implementation (**building**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Edit the plan — answer a question, add detail, or raise a new one — to\n          send it back for another round of grilling (**grilling**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # A distinct memory scope from `plan`: implementation starts fresh, with\n    # the plan already settled in `.gtd/TODO.md` (which this prompt reads\n    # below) rather than carried in the planner's working memory.\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create or edit anything under `.gtd/` except deleting\n      `<%= it.vars.todoFile %>`, which this prompt tells you to delete once\n      its work is complete.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write\n      all the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: run the test suite and record a\n      # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another\n      # fix round vs escalation) is decided by the workflow's own `on`/`retry`\n      # rules at capture time — never here.\n      #\n      # `it.vars.testCommand` defaults to \"npm test\" (this workflow's own\n      # `vars:` above) — override it with a top-level `.gtdrc`\n      # `vars: { testCommand: ... }` key, or a `GTD_VAR_testCommand`\n      # environment variable (highest precedence).\n      #\n      # A green run also removes any `<%= it.vars.feedbackFile %>` left over\n      # from an earlier red run — there is no squash to discard it for us\n      # anymore, so the script cleans it up itself before moving on to\n      # review.\n      set +e\n      mkdir -p .gtd\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output <%~ it.vars.feedbackFile %>\n        else\n          rm -f .gtd/.check-output\n          printf 'npm test failed with exit code %s and produced no output.' \"$code\" > <%~ it.vars.feedbackFile %>\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f <%~ it.vars.feedbackFile %>\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    # Its own memory scope: the fix loop re-enters `fixing` around `checking`\n    # (up to the retry cap), so labelling every attempt `fix` lets the agent\n    # remember what it already tried across the loop; a green check moves on\n    # to the differently-labelled `reviewing`, clearing it.\n    memory: fix\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix\n      the code so the suite passes. Keep the change focused — do not\n      refactor unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue; the\n      machine picks the dispute up either way.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or `.gtd/FEEDBACK.md` —\n          to re-run the check (**checking**).\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: smart\n    # A distinct memory scope again: the reviewer looks at the cycle's full\n    # diff (inlined into its prompt) with a fresh perspective, not the\n    # builder's or fixer's working memory.\n    memory: review\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewFile %>`, which this prompt tells you to write.\n\n      Write `<%= it.vars.reviewFile %>` to help a human review the cycle's\n      full diff (inlined below) in this EXACT format:\n\n      - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n      - Somewhere in the document: `<!-- base: <%= it.startCommit %> -->`\n      - At least one `## <Chunk Title>` heading, grouping hunks semantically\n        (same feature/refactor/fix, even across files) — a short explanation\n        of what changed and why, then one\n        `- [ ] ./path/to/file.ts#42 — note` file pointer per hunk (checkboxes\n        are for the human to tick, not you; every path is `./`-relative, with\n        an optional `#line` and an optional ` — note`).\n\n      Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"* **\": await-review\n\n  await-review:\n    actor: human\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # While the cycle rests here for human review, gtd opens a \"review checkout\n    # window\": HEAD and the index are temporarily rewound to this cycle's start\n    # (the process boundary — no `reviewBase` state is declared, so the base\n    # defaults to it) with the working tree untouched, so the whole cycle diff\n    # surfaces as ordinary uncommitted changes in the editor's git integration.\n    # The window closes automatically on the next invocation, once the cycle\n    # rests anywhere else (see src/ReviewWindow.ts, STATES.md §11).\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the completed\n      cycle — one `- [ ]` checkbox per reviewable item, grouped into chunks.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"D .gtd/REVIEW.md\":\n        to: idle\n        describe: >-\n          Delete `.gtd/REVIEW.md` outright to approve the whole cycle at once\n          and rest back at the start (**idle**).\n      \"M .gtd/REVIEW.md\":\n        to: review-deciding\n        describe: >-\n          Edit `.gtd/REVIEW.md` — tick a `- [ ]` box to `- [x]` to approve that\n          item, or add notes — to hand it to a deterministic check\n          (**review-deciding**) that closes the cycle out when every box is\n          ticked, or extracts the still-unticked items into a fresh\n          `.gtd/TODO.md` and loops back through **grilling** with that feedback.\n      \"* **\":\n        to: grilling\n        describe: >-\n          Change only code, leaving `.gtd/REVIEW.md` untouched, to send that as\n          feedback straight back to **grilling**.\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the driver (`gtd run`) executes this verbatim, then\n      # steps the check actor. Mechanics only: if .gtd/REVIEW.md still has any\n      # unticked \"- [ ]\" pointer, extract those pointers (with their notes)\n      # into a fresh .gtd/TODO.md; either way, remove .gtd/REVIEW.md. What\n      # the resulting diff MEANS (feedback lap vs. full approval) is decided\n      # by this state's own `on` rules at capture time — never here. The\n      # A/M .gtd/TODO.md row is declared BEFORE the D .gtd/REVIEW.md row (see\n      # this workflow's `on` map below) so a feedback lap — which always also\n      # deletes .gtd/REVIEW.md — is captured as feedback, not mistaken for an\n      # approval.\n      set +e\n      mkdir -p .gtd\n      if grep -qE '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %> 2>/dev/null; then\n        {\n          echo \"Feedback from review — address these before continuing:\"\n          echo\n          grep -E '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %>\n        } > <%~ it.vars.todoFile %>\n      fi\n      rm -f <%~ it.vars.reviewFile %>\n    on:\n      \"A .gtd/TODO.md\": grilling\n      \"M .gtd/TODO.md\": grilling\n      \"D .gtd/REVIEW.md\": idle\n      \"C\": await-review\n"), ".");
+const compiled = compileWorkflowConfig((0, import_dist$1.parse)("# The bundled default gtd workflow (v3 \"pattern machine\" — see\n# docs/design/pattern-machine-plan.md, and\n# docs/design/steering-file-validation-command.md for the `gtd validate`\n# self-validation model that replaced the old in-machine validation loops).\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/default.ts does the compiling).\n#\n# Every content string below is INLINE (no `./`-relative file references):\n# the bundled default ships inside a single-file build\n# (`dist/gtd.bundle.mjs`), so its content must already be resolved at BUILD\n# time rather than read from disk at RUNTIME — the same reason\n# `src/prompts/*.md` are imported through tsdown's `.md`-as-text loader\n# instead of read via `fs` at runtime. `default.yaml` itself is imported the\n# same way (tsdown/vitest both treat `.yaml` as text — see\n# tsdown.config.ts / tests/vitest.rawMd.ts), so this file never needs a\n# sibling prompts/ directory to exist on disk once installed.\n#\n# States, in cycle order — 10 states, no squash:\n#   idle (initial, human, message)\n#     -> grilling (agent, prompt): reads .gtd/TODO.md's sketch (or a prior\n#     lap's feedback), explores the codebase, and develops it into a concrete\n#     implementation plan, stating any open question it can't settle itself\n#     under a `## Open Questions` heading rather than guessing silently. Its\n#     `file:`/`mode:` (TODO.md/`qa`) makes the plan's format checkable — it\n#     self-validates before finishing (see \"Steering-file validation\" below).\n#   grilling -> grilling-answer (human, message): tick off suggested\n#     defaults by replacing them with `Answer:` lines; a clean step accepts\n#     every remaining default -> building; any edit loops back to grilling.\n#   grilling-answer -> building (agent, prompt): implements the plan in\n#     .gtd/TODO.md directly (no task decomposition, no per-task queue) and\n#     deletes .gtd/TODO.md once the work is complete and verified.\n#   building -> checking (check, script): runs the test command inline;\n#     A/M .gtd/FEEDBACK.md -> fixing (capped, redirects to escalate); D\n#     .gtd/FEEDBACK.md (a green run that just cleaned up prior feedback) or C\n#     (green, nothing to clean) -> reviewing.\n#   fixing (agent, prompt) <-> checking\n#   escalate (human, message): manual intervention, then back to checking\n#   checking (green) -> reviewing (agent, prompt): writes .gtd/REVIEW.md in\n#     the checkbox review format, grouping the cycle's full diff into\n#     reviewable chunks; its `file:`/`mode:` (REVIEW.md/`review`) makes that\n#     format checkable, so it self-validates before finishing. `reviewing`\n#     ALSO declares `reviewEntry: true` — a second way in: `gtd review\n#     <commitish>` (a clean tree resting at idle) writes an empty\n#     `gtd(human): reviewing` entry commit carrying <commitish>'s hash as a\n#     `Gtd-Review-Base:` trailer, starting a brand new process that reviews\n#     <commitish>..HEAD (e.g. a colleague's PR branch) through this exact same\n#     reviewing/await-review/feedback-lap machinery.\n#   reviewing -> await-review (human, message): tick a pointer's `- [\n#     ]` to `- [x]` to approve that item; deleting .gtd/REVIEW.md outright is\n#     the power-user approve-everything shortcut; anything else pending\n#     (code edits with REVIEW.md untouched) is feedback straight to grilling.\n#   await-review -> review-deciding (check, script), entered by any `M\n#     .gtd/REVIEW.md` step: if no unticked `- [ ]` pointer remains, the cycle\n#     is approved (rm .gtd/REVIEW.md -> idle); otherwise the still-unticked\n#     pointers (with their notes) are extracted into a fresh .gtd/TODO.md and\n#     .gtd/REVIEW.md is removed (-> grilling, feedback lap).\n#\n# The cycle ends at human approval, resting back at idle — there is no\n# squash state. The cycle's commits stay in history; whether/how to squash\n# them (amend, interactive rebase, a PR's squash-merge) is entirely the\n# human's business once they're done reviewing — gtd makes no assumption.\n# That squash-flavored finale (a `squashing` prompt state + a `done` commit\n# state) still exists as an ENGINE capability (see STATES.md §8) and is kept\n# as part of the fuller machine at docs/examples/advanced-workflow.md.\n#\n# A `gtd(<actor>): idle` commit — entering the workflow's own initial state —\n# is therefore a PROCESS BOUNDARY (see `computeProcessRun` in src/Edge.ts):\n# the next cycle's `retry` counts, `startCommit`, and diffs never reach back\n# across an approved cycle's own idle-entering commit.\n#\n# HYGIENE INVARIANT (asserted in e2e — see default-workflow.feature): an\n# approved cycle leaves `.gtd/` empty. FEEDBACK.md is cleaned up by a green\n# `checking` run; REVIEW.md by the review-deciding approval branch; TODO.md by\n# `building`.\n#\n# Steering-file validation. `grilling` and `reviewing` each declare a\n# `file:`/`mode:` pair (TODO.md as `qa`, REVIEW.md as `review`), so their\n# output has a checkable format. src/OpenQuestions.ts and src/ReviewDoc.ts are\n# those two formats' EXECUTABLE SPECS (their unit tests are the format spec\n# tests), and `gtd validate` FORMATS the resolved state's rendered `file:` in\n# place then runs the SAME parser over it, exiting non-zero with findings when\n# it violates the format. There is no in-machine validation state and no bash\n# port to keep in sync — the producing agent self-validates before finishing\n# (plain `gtd next` appends the \"run `gtd validate` and fix all violations\"\n# instruction; under `--json` the driving loop runs it after the turn and\n# re-prompts on findings — see skills/loop/SKILL.md), AND `gtd step` runs the\n# same format-and-validate gate on capture, refusing a turn whose steering file\n# is invalid. So the check runs after a human edits too — at the human gates\n# `grilling-answer` (TODO.md) and `await-review` (REVIEW.md) — and a human gate\n# is only ever handed a tidy, well-formed file. The same parsers back the LSP's\n# live diagnostics (src/Lsp.ts).\n#\n# `grilling` and `reviewing` both declare `model: smart` — an opaque harness\n# hint (see the comment at `grilling` below) for their heavier one-shot\n# planning/reviewing turns. Every other state is unset (harness default).\n#\n# The four agent states each declare a `memory:` scope label (`plan`,\n# `build`, `fix`, `review` — see the comment at `grilling` below) — another\n# opaque hint a memory-aware driver reads to decide when an agent turn keeps\n# the previous turn's memory and when it starts fresh: a loop that re-enters\n# one state (grilling around its answer loop, fixing around checking) keeps\n# the same label and retains memory across its laps; crossing to the next\n# phase's differently-labelled state clears it. gtd never interprets the\n# label (see STATES.md §1 and skills/loop/SKILL.md's driver contract).\n#\n# `vars.testCommand` is this workflow's own declared default for `checking`'s\n# script (see it.vars in PatternTemplates.ts) — override it per-repo with a\n# top-level `.gtdrc` `vars: { testCommand: ... }` key, or per-invocation with\n# a `GTD_VAR_testCommand` environment variable (highest precedence).\n#\n# `vars.todoFile`/`reviewFile`/`feedbackFile` are this workflow's ONE source\n# of truth for the three steering-file paths every prompt/script below reads\n# or writes — each appears in templates as `<%~ it.vars.todoFile %>` etc\n# (see docs/design/state-file-association.md §2). Every state that rests on\n# one of these files also declares a `file:`/`mode:` pair (see STATES.md's\n# property table) so `gtd status`/`gtd next --json` and the LSP (`gtd lsp`)\n# know which file a human/editor should look at, and in what format\n# (`qa` for TODO.md's open-questions format, `review` for REVIEW.md's\n# checkbox format) — `fixing`/`escalate` declare `file:` alone (FEEDBACK.md\n# is plain text, no LSP format). KNOWN LIMITATION: `on` pattern keys below are\n# NOT Eta templates — they keep the LITERAL `.gtd/...` paths matching these\n# vars' DEFAULT values. Repointing `todoFile`/`reviewFile`/`feedbackFile` via\n# `.gtdrc`'s top-level `vars:` or a `GTD_VAR_` override changes what `file:`\n# renders to (and what a template reads/writes) WITHOUT changing what the\n# `on` patterns match against — desyncing the machine. See\n# docs/configuration.md's `file:`/`mode:` section for the full caveat.\n#\n# A fuller machine — two-phase Q&A planning, an architecture phase, task\n# decomposition, a deterministic per-task builder loop, agent-prepared\n# review, and the squash finale (`squashing` + `done`) — is preserved as a\n# copy-paste `.gtdrc` example at docs/examples/advanced-workflow.md.\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  reviewFile: .gtd/REVIEW.md\n  feedbackFile: .gtd/FEEDBACK.md\n\nstates:\n  idle:\n    actor: human\n    initial: true\n    # Every human-gate `message:` below closes with the SAME rendered block —\n    # a \"What each change does next\" list built from `it.edges`, the resting\n    # state's own `on` edges (see PatternTemplates.TemplateContext.edges). Each\n    # edge's human-readable route lives in its `describe:` (the single source\n    # of truth), so the list can never drift from the routing it documents.\n    # The block skips edges without a `describe`, and each `<%~ ... \"\\n\" %>`\n    # keeps the bullet's own newline (Eta's autoTrim strips the template's own\n    # line breaks around `<% %>` tags, not text inside an interpolation).\n    message: |\n      No active gtd cycle.\n\n      To start one, write `.gtd/TODO.md` with a short sketch of what you want\n      built — a few sentences is enough.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save your sketch to `.gtd/TODO.md` (any working-tree change) to start\n          the cycle — the agent reads it, explores the codebase, and develops it\n          into a concrete implementation plan (**grilling**).\n\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # `model` is an opaque harness hint — gtd never interprets this string, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so the\n    # driving loop can map it onto whatever models its agent harness\n    # provides. \"smart\" here just names the harness-chosen tier for the\n    # heavier planning turn; states without a `model` use the harness's\n    # default.\n    model: smart\n    # `memory` is an opaque memory-scope label — gtd never interprets it, it\n    # only passes it through to `gtd next --json`/`gtd status --json` so a\n    # memory-aware driving loop can decide when an agent turn continues from\n    # the previous turn's memory and when it starts fresh: consecutive agent\n    # turns that emit the SAME label share memory, a change (or the first\n    # turn) is where the driver starts fresh. `grilling` re-enters itself\n    # around the grilling-answer loop, so labelling every lap\n    # `plan` keeps the planner's accumulated exploration across the loop; the\n    # next phase (`building`) carries a different label, clearing it.\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.todoFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.todoFile %>` holds a short sketch of what to build (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete implementation plan.\n\n      For every question you cannot settle yourself, add it under a\n      `## Open Questions` heading, one `### <question>` sub-heading each,\n      whose body's FIRST non-blank line is exactly\n      `Suggested default: <your answer>` — the human can accept it as-is or\n      override it. Omit the section entirely once there are no open\n      questions. If `<%= it.vars.todoFile %>` already carries\n      `## Open Questions` entries from a previous lap, fold any\n      `Answer: <text>` line into the plan; every remaining entry's body must\n      still start with either `Suggested default: ...` or `Answer: ...` —\n      never anything else.\n\n      Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n      not commit, and do not run `gtd step agent` yourself; the harness does\n      that.\n    on:\n      \"* **\": grilling-answer\n\n  grilling-answer:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.todoFile %>` holds the plan under development, with any\n      open questions under `## Open Questions` — each carrying a suggested\n      default. Answer a question by editing its entry in place: replace its\n      `Suggested default: ...` line with `Answer: ...`, or add further detail.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: building\n        describe: >-\n          Change nothing to accept every suggested default as-is and move on to\n          implementation (**building**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Edit the plan — answer a question, add detail, or raise a new one — to\n          send it back for another round of grilling (**grilling**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    # A distinct memory scope from `plan`: implementation starts fresh, with\n    # the plan already settled in `.gtd/TODO.md` (which this prompt reads\n    # below) rather than carried in the planner's working memory.\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create or edit anything under `.gtd/` except deleting\n      `<%= it.vars.todoFile %>`, which this prompt tells you to delete once\n      its work is complete.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write\n      all the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the loop driver executes this verbatim, then\n      # steps the check actor. Mechanics only: run the test suite and record a\n      # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another\n      # fix round vs escalation) is decided by the workflow's own `on`/`retry`\n      # rules at capture time — never here.\n      #\n      # `it.vars.testCommand` defaults to \"npm test\" (this workflow's own\n      # `vars:` above) — override it with a top-level `.gtdrc`\n      # `vars: { testCommand: ... }` key, or a `GTD_VAR_testCommand`\n      # environment variable (highest precedence).\n      #\n      # A green run also removes any `<%= it.vars.feedbackFile %>` left over\n      # from an earlier red run — there is no squash to discard it for us\n      # anymore, so the script cleans it up itself before moving on to\n      # review.\n      set +e\n      mkdir -p .gtd\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output <%~ it.vars.feedbackFile %>\n        else\n          rm -f .gtd/.check-output\n          printf 'npm test failed with exit code %s and produced no output.' \"$code\" > <%~ it.vars.feedbackFile %>\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f <%~ it.vars.feedbackFile %>\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    # Its own memory scope: the fix loop re-enters `fixing` around `checking`\n    # (up to the retry cap), so labelling every attempt `fix` lets the agent\n    # remember what it already tried across the loop; a green check moves on\n    # to the differently-labelled `reviewing`, clearing it.\n    memory: fix\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix\n      the code so the suite passes. Keep the change focused — do not\n      refactor unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue; the\n      machine picks the dispute up either way.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or `.gtd/FEEDBACK.md` —\n          to re-run the check (**checking**).\n\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: smart\n    # A distinct memory scope again: the reviewer looks at the cycle's full\n    # diff (inlined into its prompt) with a fresh perspective, not the\n    # builder's or fixer's working memory.\n    memory: review\n    # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n    # enters here directly, recording the resolved base as a `Gtd-Review-Base:`\n    # trailer on its empty entry commit — everything below then reuses the\n    # existing reviewing/await-review/feedback-lap machinery unmodified over\n    # <commitish>..HEAD (see STATES.md §11).\n    reviewEntry: true\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewFile %>`, which this prompt tells you to write.\n\n      Write `<%= it.vars.reviewFile %>` to help a human review the cycle's\n      full diff (inlined below) in this EXACT format:\n\n      - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n      - Somewhere in the document: `<!-- base: <%= it.startCommit %> -->`\n      - At least one `## <Chunk Title>` heading, grouping hunks semantically\n        (same feature/refactor/fix, even across files) — a short explanation\n        of what changed and why, then one\n        `- [ ] ./path/to/file.ts#42 — note` file pointer per hunk (checkboxes\n        are for the human to tick, not you; every path is `./`-relative, with\n        an optional `#line` and an optional ` — note`).\n\n      Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"* **\": await-review\n\n  await-review:\n    actor: human\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # While the cycle rests here for human review, gtd opens a \"review checkout\n    # window\": HEAD and the index are temporarily rewound to this cycle's start\n    # (the process boundary — no `reviewBase` state is declared, so the base\n    # defaults to it) with the working tree untouched, so the whole cycle diff\n    # surfaces as ordinary uncommitted changes in the editor's git integration.\n    # The window closes automatically on the next invocation, once the cycle\n    # rests anywhere else (see src/ReviewWindow.ts, STATES.md §11).\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the completed\n      cycle — one `- [ ]` checkbox per reviewable item, grouped into chunks.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"D .gtd/REVIEW.md\":\n        to: idle\n        describe: >-\n          Delete `.gtd/REVIEW.md` outright to approve the whole cycle at once\n          and rest back at the start (**idle**).\n      \"M .gtd/REVIEW.md\":\n        to: review-deciding\n        describe: >-\n          Edit `.gtd/REVIEW.md` — tick a `- [ ]` box to `- [x]` to approve that\n          item, or add notes — to hand it to a deterministic check\n          (**review-deciding**) that closes the cycle out when every box is\n          ticked, or extracts the still-unticked items into a fresh\n          `.gtd/TODO.md` and loops back through **grilling** with that feedback.\n      \"* **\":\n        to: grilling\n        describe: >-\n          Change only code, leaving `.gtd/REVIEW.md` untouched, to send that as\n          feedback straight back to **grilling**.\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — the loop driver executes this verbatim, then\n      # steps the check actor. Mechanics only: if .gtd/REVIEW.md still has any\n      # unticked \"- [ ]\" pointer, extract those pointers (with their notes)\n      # into a fresh .gtd/TODO.md; either way, remove .gtd/REVIEW.md. What\n      # the resulting diff MEANS (feedback lap vs. full approval) is decided\n      # by this state's own `on` rules at capture time — never here. The\n      # A/M .gtd/TODO.md row is declared BEFORE the D .gtd/REVIEW.md row (see\n      # this workflow's `on` map below) so a feedback lap — which always also\n      # deletes .gtd/REVIEW.md — is captured as feedback, not mistaken for an\n      # approval.\n      set +e\n      mkdir -p .gtd\n      if grep -qE '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %> 2>/dev/null; then\n        {\n          echo \"Feedback from review — address these before continuing:\"\n          echo\n          grep -E '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %>\n        } > <%~ it.vars.todoFile %>\n      fi\n      rm -f <%~ it.vars.reviewFile %>\n    on:\n      \"A .gtd/TODO.md\": grilling\n      \"M .gtd/TODO.md\": grilling\n      \"D .gtd/REVIEW.md\": idle\n      \"C\": await-review\n"), ".");
 const defaultWorkflowDefinition = compiled.definition;
 /** The default workflow's own declared `vars:` defaults — `{ testCommand: "npm test" }`, overridable via a top-level `.gtdrc` `vars:` key or a `GTD_VAR_testCommand` environment variable (see `src/Edge.ts`'s `resolveVars`). */
 const defaultWorkflowVars = compiled.vars;
@@ -190130,7 +190164,7 @@ const workflowJsonSchema = {
 					},
 					script: {
 						type: "string",
-						description: "Content kind: a shell script (Eta template). `gtd run` executes it verbatim via bash, then steps this state's actor."
+						description: "Content kind: a shell script (Eta template). The loop driver executes it verbatim via bash, then steps this state's actor."
 					},
 					prompt: {
 						type: "string",
@@ -190210,6 +190244,10 @@ const workflowJsonSchema = {
 					reviewBase: {
 						type: "boolean",
 						description: "Marks the state whose most-recent in-process commit anchors the review window's diff base; absent any, the base is the process start. Forbidden on a commit state."
+					},
+					reviewEntry: {
+						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."
 					}
 				}
 			}
@@ -191952,6 +191990,23 @@ const parseCostTrailers = (messages) => {
 	}
 	return entries;
 };
+const REVIEW_BASE_TRAILER_PREFIX = "Gtd-Review-Base: ";
+const REVIEW_BASE_TRAILER_RE = /^Gtd-Review-Base:[ \t]*(\S+)[ \t]*$/m;
+/**
+* Append a `Gtd-Review-Base: <base>` trailer (after a blank line) to a commit
+* `subject` — the entry commit `gtd review <commitish>` writes to start a new
+* review process. Mirrors `withCostTrailer`'s placement: the subject (first
+* line) is untouched, so `parseStateSubject`/`resolveState` read it back
+* exactly like any other turn commit.
+*/
+const withReviewBaseTrailer = (subject, base) => `${subject}\n\n${REVIEW_BASE_TRAILER_PREFIX}${base}`;
+/**
+* The `Gtd-Review-Base: <hash>` trailer recorded on a `gtd review <commitish>`
+* entry commit (see `withReviewBaseTrailer`), or `undefined` when `message`
+* carries none. Read back by `computeProcessRun` — ONLY off the process's
+* first (oldest) commit — to override the run's diff base.
+*/
+const parseReviewBaseTrailer = (message) => REVIEW_BASE_TRAILER_RE.exec(message)?.[1];
 /** The total token cost across the given entries (`0` when none). */
 const totalCostOf = (entries) => entries.reduce((sum, entry) => sum + entry.cost, 0);
 /** Per-model token totals, highest-cost first (ties broken by model name for a stable order). */
@@ -192007,6 +192062,7 @@ const computeProcessRun = (git, def) => gen(function* () {
 	if (!(yield* git.hasCommits())) return {
 		startHash: "",
 		startParentHash: EMPTY_TREE$1,
+		diffBase: EMPTY_TREE$1,
 		trace: [],
 		costEntries: []
 	};
@@ -192026,6 +192082,7 @@ const computeProcessRun = (git, def) => gen(function* () {
 	return {
 		startHash: startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash,
 		startParentHash,
+		diffBase: (processCommits.length > 0 ? parseReviewBaseTrailer(processCommits[0].message) : void 0) ?? startParentHash,
 		trace,
 		costEntries
 	};
@@ -192078,7 +192135,7 @@ const buildTemplateContext = (git, read, state, actor, run, vars, edges, current
 	const hasCommits = yield* git.hasCommits();
 	const currentCommit = hasCommits ? yield* git.resolveRef("HEAD") : "";
 	const previousCommit = hasCommits ? yield* git.resolveRef("HEAD~1").pipe(catchAll(() => succeed$3(run.startParentHash))) : "";
-	const processDiff = [yield* git.diffRef(run.startParentHash).pipe(catchAll(() => succeed$3(""))), yield* git.diffHead().pipe(catchAll(() => succeed$3("")))].filter((d) => d.trim().length > 0).join("\n\n");
+	const processDiff = [yield* git.diffRef(run.diffBase).pipe(catchAll(() => succeed$3(""))), yield* git.diffHead().pipe(catchAll(() => succeed$3("")))].filter((d) => d.trim().length > 0).join("\n\n");
 	const lastDiff = run.trace.length > 0 ? yield* git.commitDiff(currentCommit).pipe(catchAll(() => succeed$3(""))) : "";
 	const stepEntry = currentCost > 0 || currentModel !== void 0 ? [{
 		cost: currentCost,
@@ -192086,7 +192143,7 @@ const buildTemplateContext = (git, read, state, actor, run, vars, edges, current
 	}] : [];
 	const allCostEntries = [...run.costEntries, ...stepEntry];
 	return {
-		startCommit: run.startHash,
+		startCommit: run.diffBase,
 		currentCommit,
 		previousCommit,
 		state,
@@ -192289,10 +192346,12 @@ const closeReviewWindow = gen(function* () {
 * subcommand.
 *
 * The base is the most-recent in-process `reviewBase` commit
-* (`reviewBaseHash`) or, absent any such state, the process start
-* (`startParentHash`). When that resolves to the empty tree (a process with no
-* prior commit) or to HEAD itself (an empty process), there is nothing to
-* surface and the window stays closed.
+* (`reviewBaseHash`) or, absent any such state, the process's diff base
+* (`run.diffBase` — the process start, `startParentHash`, unless a
+* `gtd review <commitish>` entry commit overrode it via a `Gtd-Review-Base:`
+* trailer, see `computeProcessRun`). When that resolves to the empty tree (a
+* process with no prior commit) or to HEAD itself (an empty process), there
+* is nothing to surface and the window stays closed.
 *
 * Ordering is crash-safe: base ref → head ref → mixed reset → `.gtd/` index
 * pin → intent-to-add. A crash before the head-ref write leaves only a stale
@@ -192305,7 +192364,7 @@ const openReviewWindow = gen(function* () {
 	if (!(yield* git.hasCommits())) return { opened: false };
 	if (!isReviewWindowState(def, resolveState(def, yield* git.lastCommitSubject()))) return { opened: false };
 	const run = yield* computeProcessRun(git, def);
-	const base = (yield* reviewBaseHash(git, def, run)) ?? run.startParentHash;
+	const base = (yield* reviewBaseHash(git, def, run)) ?? run.diffBase;
 	const headHash = yield* git.resolveRef("HEAD");
 	if (base === EMPTY_TREE || base === headHash) return { opened: false };
 	yield* git.updateRef(REVIEW_BASE_REF, base);
@@ -204046,8 +204105,9 @@ const resolveSteeringMode = (def, mode) => {
 const unknownModeMessage = (def, state, mode) => `state "${state}": mode "${mode}" is not defined by the active workflow (known modes: ${knownModes(def).join(", ")})`;
 /**
 * Run one rendered mode command through `bash -c` in `cwd`, capturing output
-* instead of inheriting the terminal (unlike `gtd run`'s scripted actor, whose
-* output IS the point): here the output is data — a validate command's findings
+* instead of inheriting the terminal (unlike a workflow script, which the driver
+* runs with inherited stdio because its output IS the point): here the output is
+* data — a validate command's findings
 * are reported to the agent that must fix them. A spawn failure (no `bash`, an
 * unreadable cwd) fails the Effect; a non-zero EXIT is a value, since that is
 * the mode's way of saying "invalid".
@@ -204130,8 +204190,7 @@ const formatAndValidateSteeringFile = (resolved, file, readContent, context, cwd
 });
 //#endregion
 //#region src/program.ts
-const _require = createRequire(import.meta.url);
-const GTD_VERSION = _require("../package.json").version;
+const GTD_VERSION = createRequire(import.meta.url)("../package.json").version;
 const HELP_TEXT = `Usage: gtd [command] [options]
 
 Commands:
@@ -204141,10 +204200,13 @@ Commands:
                    --cost=<n> (optionally --model=<name>) to record the
                    just-finished invocation's token cost and model on the
                    turn commit (summed into it.processCost/processCostByModel)
+  review <commitish>
+                   Start a NEW review process at the workflow's declared
+                   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
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
-  run              Execute the resolved rest's emitted script, then step its
-                   actor (the built-in script driver)
   status           Print the resolved rest's state/actor and which declared
                    pattern (if any) each pending change matches (no mutation)
   validate         Format and validate the steering file the resolved rest
@@ -204247,7 +204309,7 @@ const runLspCommand = (argv, json) => gen(function* () {
 /**
 * Resolve HEAD's rest, the current process run, and the template context for
 * rendering that rest's OWN state/actor — the common prefix shared by `gtd
-* next`, `gtd run`, and `gtd status` (each fetches `git` itself first, since
+* next` and `gtd status` (each fetches `git` itself first, since
 * `gtd status` also needs it for `pendingChanges`; `stepAsActor`'s squash
 * path renders a DIFFERENT state, so it builds its own context inline
 * instead of sharing this helper).
@@ -204269,8 +204331,7 @@ const resolveRestContext = (git) => gen(function* () {
 const formatStepRefusal = (invoker, refusal) => refusal.reason === "out-of-turn" ? `gtd step ${invoker}: out of turn — "${refusal.state}" awaits ${refusal.awaits}` : `gtd step ${invoker}: no declared pattern matches the pending changes at "${refusal.state}" — declared patterns: ${refusal.patterns.length > 0 ? refusal.patterns.join(", ") : "(none)"}`;
 /**
 * Authenticate `invoker` against the resolved rest and perform the one
-* resulting transition (commit or squash), shared by `gtd step` and
-* `gtd run` (which steps the script's own actor after executing it).
+* resulting transition (commit or squash) for `gtd step`.
 * Refusals fail the Effect with a formatted message; a no-op returns
 * `subject: null` rather than failing (exit zero, per the plan's "clean
 * no-op exits zero").
@@ -204307,7 +204368,7 @@ const stepAsActor = (invoker, cost, model) => gen(function* () {
 		model: model ?? null
 	};
 });
-/** Renders `stepAsActor`'s result the same way for both `gtd step` and `gtd run`. */
+/** Renders `stepAsActor`'s result for `gtd step`. */
 const reportStepResult = (result, json, write) => {
 	if (json) write(JSON.stringify({
 		state: result.state,
@@ -204326,6 +204387,52 @@ const runStepCommand = (argv, json, write, cost, model) => gen(function* () {
 	reportStepResult(result, json, write);
 });
 /**
+* `gtd review <commitish>`: start a brand NEW review process at the active
+* workflow's declared `reviewEntry: true` state (see
+* `PatternMachine.reviewEntryStateOf`), reviewing `<commitish>..HEAD` — e.g. a
+* colleague's PR branch pushed on top of a shared base, with no gtd process of
+* its own. Writes an ordinary EMPTY turn commit
+* (`gtd(human): <review-entry-state>`) carrying the resolved `<commitish>`'s
+* full hash as a `Gtd-Review-Base:` trailer (`withReviewBaseTrailer`) —
+* `computeProcessRun` reads that trailer back off this same commit (its
+* process's own oldest) to override the new process's diff base, so the
+* ENTIRE existing review flow (reviewing → await-review → feedback laps, the
+* `await-review` review checkout window) operates over `<commitish>..HEAD`
+* with zero duplicated logic — see `src/Edge.ts`/`src/ReviewWindow.ts`.
+*
+* Any failure below is a plain refusal: nothing is written.
+*
+* a. The machine must currently rest at the workflow's INITIAL state — a
+*    plain non-gtd branch (the normal case) resolves there via the
+*    inert-subject rule (STATES.md §5); a process already underway refuses.
+* b. The working tree must be clean.
+* c. The active workflow must declare a `reviewEntry: true` state.
+* d. `<commitish>` must resolve to a commit, be an ancestor of HEAD, and
+*    differ from HEAD (nothing to review otherwise).
+*/
+const runReviewCommand = (argv, json, write) => gen(function* () {
+	const args = commandArgs(argv);
+	if (args.length === 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: missing <commitish> argument"));
+	if (args.length > 1) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: too many arguments — expected one <commitish>, got: ${args.join(", ")}`));
+	const commitish = args[0];
+	const git = yield* GitService;
+	const rest = yield* resolveRest();
+	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: a process is already underway (resting at "${rest.state}") — finish or abandon it before starting a review`));
+	if ((yield* pendingChanges(git)).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: the working tree must be clean before starting a review"));
+	const entryState = reviewEntryStateOf(rest.def);
+	if (entryState === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: the active workflow declares no review entry state"));
+	const resolvedBase = yield* git.resolveRef(commitish).pipe(mapError$1(() => /* @__PURE__ */ new Error(`gtd review: "${commitish}" does not resolve to a commit`)));
+	if (resolvedBase === (yield* git.resolveRef("HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: "${commitish}" is HEAD — nothing to review`));
+	if (!(yield* git.isAncestor(resolvedBase, "HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: "${commitish}" is not an ancestor of HEAD`));
+	const subject = stateSubject("human", entryState);
+	yield* git.commitAsIs(withReviewBaseTrailer(subject, resolvedBase));
+	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`
@@ -204450,32 +204557,6 @@ const runValidateCommand = (argv, json, write) => gen(function* () {
 	}
 	return yield* fail$2(/* @__PURE__ */ new Error(`${file} is not valid:\n${errors.map((e) => `  - ${e}`).join("\n")}`));
 });
-/**
-* `gtd run`: the built-in driver for a `script`-content rest. Renders the
-* resolved rest exactly like `gtd next`, executes its content verbatim via
-* `bash` (the ONLY place gtd spawns a subprocess), then steps that state's
-* own actor to capture the outcome. Refuses when the resolved rest isn't a
-* script (nothing to run).
-*/
-const runRunCommand = (argv, json, write) => gen(function* () {
-	yield* rejectExtraArgs("run", argv);
-	const git = yield* GitService;
-	const { rest, context } = yield* resolveRestContext(git);
-	const rendered = yield* renderRest(rest, context);
-	if (rendered.kind !== "script") return yield* fail$2(/* @__PURE__ */ new Error(`gtd run: "${rest.state}" awaits a ${rendered.kind} from "${rest.actor}" — nothing scripted to run`));
-	yield* try_({
-		try: () => {
-			const { spawnSync } = _require("node:child_process");
-			spawnSync("bash", ["-c", rendered.content], {
-				cwd: process.cwd(),
-				stdio: "inherit"
-			});
-		},
-		catch: (e) => e instanceof Error ? e : new Error(String(e))
-	});
-	const result = yield* stepAsActor(rest.actor);
-	reportStepResult(result, json, write);
-});
 /** Which declared `on` pattern (if any) each pending change matches — the pure computation `gtd status` reports (both plain and `--json`). */
 const computeStatusChanges = (onEdges, changes) => changes.map((change) => {
 	const matchedRow = onEdges.find(([patternStr]) => {
@@ -204562,8 +204643,8 @@ const runMermaidCommand = (argv, json, write) => gen(function* () {
 });
 const KNOWN_SUBCOMMANDS = [
 	"step",
+	"review",
 	"next",
-	"run",
 	"status",
 	"validate",
 	"mermaid"
@@ -204613,8 +204694,8 @@ const assertRunningFromRepoRoot = (git, fs) => gen(function* () {
 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 "next": return runNextCommand(json, write);
-		case "run": return runRunCommand(argv, json, write);
 		case "status": return runStatusCommand(argv, json, write);
 		case "validate": return runValidateCommand(argv, json, write);
 		case "mermaid": return runMermaidCommand(argv, json, write);

package/docs/cli.md

@@ -10,6 +10,11 @@ Commands:
                    --cost=<n> (optionally --model=<name>) to record the
                    just-finished invocation's token cost and model on the
                    turn commit (summed into it.processCost/processCostByModel)
+  review <commitish>
+                   Start a NEW review process at the workflow's declared
+                   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
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   run              Execute the resolved rest's emitted script, then step its
@@ -103,6 +108,49 @@ not passed):
 }
 ```
 
+## `gtd review <commitish> [--json]`
+
+Starts a BRAND NEW review process at the active workflow's declared
+`reviewEntry: true` state (see
+[STATES.md §11](../STATES.md#11-the-review-checkout-window)), reviewing
+`<commitish>..HEAD` — e.g. a colleague's PR branch pushed on top of a shared
+base, with no gtd process of its own. Reuses the workflow's existing
+review/feedback machinery unmodified; there is no separate review-entry command
+surface to keep in sync.
+
+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 plain
+  non-gtd branch resolves there via the inert-subject rule — the normal case; a
+  process already underway refuses);
+- a **clean working tree**;
+- the active workflow declaring a **`reviewEntry: true`** state (otherwise:
+  `gtd review: the active workflow declares no review entry state`);
+- `<commitish>` resolving to a commit, being an **ancestor of HEAD**, and
+  **differing from HEAD** (nothing to review otherwise).
+
+On success, writes ONE empty commit, `gtd(human): <review-entry-state>`,
+carrying the resolved commit's full hash as a `Gtd-Review-Base: <hash>` trailer
+(mirroring how `gtd step --cost` writes its own `Gtd-Cost:` trailer). Everything
+downstream that renders a diff — `it.processDiff`, and the review checkout
+window opened by a downstream `reviewWindow: true` state — keys off the
+process's diff base, and this trailer is exactly how that base gets re-pointed
+at `<commitish>..HEAD` (see
+[STATES.md §7](../STATES.md#7-retry)/[§11](../STATES.md#11-the-review-checkout-window)).
+
+Plain-mode output is one line, same shape as `gtd step`:
+
+```
+committed: gtd(human): reviewing
+```
+
+`--json` emits `{state, subject}` — `state` is the entered review-entry state,
+`subject` the bare commit subject (the trailer is not echoed).
+
+Takes exactly one positional argument (`<commitish>`); missing or extra
+arguments are usage errors.
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -158,23 +206,15 @@ which are JSON-only. `--json` emits
   when the state has no `on` (a commit state); a per-edge `describe` is likewise
   omitted when that edge declares none.
 
-## `gtd run`
-
-The built-in driver for a `script`-content rest — the **only** place gtd itself
-spawns a subprocess. Renders the resolved rest exactly like `gtd next`, executes
-its content verbatim via `bash -c` (foreground, inherited stdio, exit code
-deliberately ignored — a check script encodes its outcome in the tree, e.g.
-writing a findings file, never in its exit status), then runs `gtd step <actor>`
-for that state's own actor to capture the outcome in one command. Refuses (exit
-non-zero, no execution, no step) when the resolved rest isn't a script:
-
-```
-gtd run: "<state>" awaits a <kind> from "<actor>" — nothing scripted to run
-```
+## Running `script` rests (no `gtd` subcommand)
 
-Reports the same `{state, subject}` (or `committed: …` / `nothing to do at "…"`)
-as `gtd step` for the capturing step it performs. Takes no arguments — extra
-positional args are rejected.
+There is no `gtd` subcommand that executes a workflow script — gtd never runs a
+workflow script itself. When `gtd next` resolves to a `script`-content rest, the
+**driver** (`bin/gtd-loop`, or any loop harness) executes the emitted `content`
+verbatim via `bash -c` — foreground, inherited stdio, exit code deliberately
+ignored (a check script encodes its outcome in the tree, e.g. writing a findings
+file, never in its exit status) — then runs `gtd step <actor>` for that state's
+own actor to capture the outcome. See [Driving the loop](loop.md).
 
 ## `gtd status [--json]`
 
@@ -370,8 +410,8 @@ the plain-text one.
   report, a log file — into the working tree, the tree never goes clean after a
   green run, and the check's `"C"` pattern never fires. Gitignore every path
   your scripts write before wiring gtd into a repo.
-- **Repository root invocation.** Every state subcommand (`step`/`next`/`run`/
-  `status`/`mermaid`) must run from the git repository root — the workflow,
-  pending changes, and process history are resolved against the process cwd.
-  `--help`/`--version`, `format`, and `lsp` skip this guard entirely (and any
-  git/`.gtdrc` dependency along with it).
+- **Repository root invocation.** Every state subcommand (`step`/`review`/
+  `next`/`status`/`mermaid`) must run from the git repository root — the
+  workflow, pending changes, and process history are resolved against the
+  process cwd. `--help`/`--version`, `format`, and `lsp` skip this guard
+  entirely (and any git/`.gtdrc` dependency along with it).

package/docs/configuration.md

@@ -331,9 +331,9 @@ The contract:
   not a malformed file): nothing is validated and nothing is committed.
 - **At least one of the two is required** in any single entry; the half it
   leaves out falls through to the layer beneath (below), or is a no-op.
-- Commands run via `bash -c` from the repository root — the only place besides a
-  `script:` state's `gtd run` where gtd spawns a subprocess. A `.gtdrc` is
-  project code: only add commands you would run yourself.
+- Commands run via `bash -c` from the repository root — the only place gtd
+  itself spawns a subprocess (a `script:` state is run by the loop driver, not
+  by gtd). A `.gtdrc` is project code: only add commands you would run yourself.
 
 #### The layers, half by half
 
@@ -418,6 +418,43 @@ head is preserved under `refs/gtd/review-head` (the base under
 `refs/gtd/review-base`) for the window's lifetime. See
 [STATES.md §11](../STATES.md) for the full lifecycle.
 
+### `reviewEntry:` — the review entry point (`gtd review <commitish>`)
+
+A state may separately declare `reviewEntry: true` (at most one across the whole
+workflow; forbidden on a commit state and on the initial state). It marks the
+state [`gtd review <commitish>`](cli.md#gtd-review-commitish---json) enters to
+start a BRAND NEW process reviewing `<commitish>..HEAD` — e.g. a colleague's PR
+branch with no gtd process of its own — reusing whatever `on`/
+`reviewWindow`/`reviewBase` machinery that state and its downstream states
+already declare, with zero duplicated logic.
+
+```yaml
+workflow:
+  states:
+    # …
+    review:
+      actor: agent
+      reviewEntry: true # `gtd review <commitish>` starts a new process here
+      prompt: summarize <%~ it.processDiff %> for a human to check
+      on:
+        "* **": await-review
+```
+
+`gtd review <commitish>` requires resting at the workflow's initial state with a
+clean tree, and requires the active workflow to declare a `reviewEntry` state.
+It resolves `<commitish>` (which must name an ancestor of HEAD other than HEAD
+itself) and writes one empty `gtd(human): <review-entry-state>` turn commit
+carrying the resolved hash as a `Gtd-Review-Base:` trailer — read back by
+`computeProcessRun` to override the new process's diff base (`it.startCommit`
+and `it.processDiff` then cover `<commitish>..HEAD`, and a downstream
+`reviewWindow: true` state's checkout window opens over that same range). The
+process's `retry`/squash trace boundary is untouched: the entry commit's own
+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.
+
 ### Template variables
 
 Every `script`/`prompt`/`message`/`commit`/`model`/`memory`/`file` template is
@@ -425,7 +462,7 @@ rendered as an Eta template (`it.<name>`) with:
 
 | Variable             | Meaning                                                                                                                                                                                                                                                                                                                                    |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `startCommit`        | The hash the current process started from (before its first turn).                                                                                                                                                                                                                                                                         |
+| `startCommit`        | The current process's diff base — normally the process start, but re-pointed to `<commitish>`'s hash for a process `gtd review <commitish>` started (see ["`reviewEntry:`"](#reviewentry--the-review-entry-point-gtd-review-commitish)).                                                                                                   |
 | `currentCommit`      | HEAD's hash at render time.                                                                                                                                                                                                                                                                                                                |
 | `previousCommit`     | The hash before the last transition (HEAD's parent, in-process).                                                                                                                                                                                                                                                                           |
 | `state`              | The state whose content is being rendered.                                                                                                                                                                                                                                                                                                 |
@@ -518,8 +555,10 @@ vars:
 ```
 
 ```bash
-# highest precedence — beats both the workflow default and the .gtdrc value above
-GTD_VAR_testCommand="npm run test -- --bail" gtd run
+# highest precedence — beats both the workflow default and the .gtdrc value above.
+# The var is read at render time, so it shows up in the script `gtd next` prints
+# (and in what the loop driver then executes).
+GTD_VAR_testCommand="npm run test -- --bail" gtd next
 ```
 
 A template reads any of it as `it.vars.<name>`:

package/docs/examples/advanced-workflow.md

@@ -23,7 +23,10 @@ Compared to the simplified bundled default, this machine adds:
   `checking`/`fixing` loop, until the queue empties.
 - **Agent-prepared review** — `reviewing` has the agent write `.gtd/REVIEW.md`
   summarizing the full cycle diff for a human to check before `await-review`
-  resolves an approval or feedback.
+  resolves an approval or feedback. `reviewing` also declares
+  `reviewEntry: true`, so `gtd review <commitish>` can start a review process
+  here directly over `<commitish>..HEAD` (e.g. a colleague's PR branch) — see
+  [STATES.md §11](../../STATES.md#11-the-review-checkout-window).
 - **A squash finale** — approval at `await-review` moves to `squashing` (the
   agent authors `.gtd/COMMIT_MSG.md`) and then `done`, a `commit:` state that
   squashes the whole cycle into one commit. The simplified bundled default drops
@@ -333,6 +336,10 @@ workflow:
       file: <%= it.vars.reviewFile %>
       mode: review
       model: smart
+      # A second way in: `gtd review <commitish>` (clean tree, resting at the
+      # initial state) enters here directly over <commitish>..HEAD — see
+      # STATES.md §11.
+      reviewEntry: true
       prompt: |
         You are an autonomous coding agent. `.gtd/` holds this workflow's own
         state — never create, edit, or delete anything under `.gtd/` except

package/docs/loop.md

@@ -11,21 +11,22 @@ gtd (v3, the pattern machine) exposes three commands a loop driver combines:
   [Configuration: Token cost](configuration.md#token-cost)).
 - **`gtd next`** — print the resolved rest's rendered script/prompt/message,
   without mutating anything.
-- **`gtd run`** — execute the resolved rest's emitted script (only for a
-  `script`-content rest), then step that state's own actor to capture the
-  outcome. The only place gtd spawns a subprocess.
+
+gtd never executes a workflow script itself: at a `script`-content rest the
+DRIVER runs the emitted `content` and then steps that state's own actor.
 
 A loop is a simple cycle:
 
 1. Run `gtd next --json` — see [`cli.md`](cli.md#gtd-next---json) for the exact
    `{state, actor, kind, content, model?, memory?}` field shape. `kind` is the
-   dispatch key: `"message"` → halt (a human rest); `"script"` → run `gtd run`;
-   `"prompt"` → feed `content` to the agent, then `gtd step <actor>` yourself
-   once it's done acting. The optional `model` is an opaque string the workflow
-   author chose, which you map onto your own harness's model selection if you
-   use one.
-2. Repeat until a `"message"` rest halts the loop, or a zero-commit `gtd run` at
-   idle settles it (the green terminal signal).
+   dispatch key: `"message"` → halt (a human rest); `"script"` → execute
+   `content` verbatim (ignoring its exit code), then `gtd step <actor>` to
+   capture the outcome; `"prompt"` → feed `content` to the agent, then
+   `gtd step <actor>` yourself once it's done acting. The optional `model` is an
+   opaque string the workflow author chose, which you map onto your own
+   harness's model selection if you use one.
+2. Repeat until a `"message"` rest halts the loop, or a zero-commit script step
+   at idle settles it (the green terminal signal).
 
 A human acts by editing files (e.g. writing/editing `.gtd/TODO.md`, fixing code)
 and then running `gtd step human` to capture the edit as their turn.
@@ -75,7 +76,8 @@ while true; do
 
   if [[ "$kind" == "script" ]]; then
     head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
-    gtd run
+    bash -c "$content" || true   # run the emitted script; exit code ignored
+    gtd step "$actor" >/dev/null # capture whatever it left in the tree
     head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
     if [[ "$head_before" == "$head_after" ]]; then
       echo "--- Settled ($state: check passed, nothing to do) ---"

package/docs/upgrading.md

@@ -71,9 +71,16 @@ upgrading.
   (see
   [docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
   and [STATES.md §12](../STATES.md)).
-- **`gtd review <target>`.** Gone; the v3 command surface is `step` / `next` /
-  `run` / `status` / `validate` / `mermaid` / `lsp` (see
-  [CLI reference](cli.md)).
+- **`gtd review <target>`.** Gone in the initial v3 rewrite (the command surface
+  was `step` / `next` / `run` / `status` / `validate` / `mermaid` / `lsp`), then
+  RETURNED in this version with different, narrower semantics: it no longer
+  inspects an arbitrary target the way v2 did — it starts a brand NEW review
+  process at a workflow-declared `reviewEntry: true` state, reviewing
+  `<target>..HEAD` (e.g. a colleague's PR branch with no gtd process of its own)
+  by writing one empty entry commit with a `Gtd-Review-Base:` trailer and
+  reusing the workflow's existing review/feedback machinery unmodified — see
+  [STATES.md §11](../STATES.md#11-the-review-checkout-window) and
+  [CLI reference](cli.md#gtd-review-commitish---json).
 - **`gtd format <file>`, and the bundled prettier with it.** gtd no longer
   formats anything on its own: a steering-file mode declares its own `format:`
   SHELL COMMAND, so a project brings whatever formatter it already uses. Adding

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "4.0.0",
+  "version": "5.1.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

@@ -51,7 +51,7 @@
               },
               "script": {
                 "type": "string",
-                "description": "Content kind: a shell script (Eta template). `gtd run` executes it verbatim via bash, then steps this state's actor."
+                "description": "Content kind: a shell script (Eta template). The loop driver executes it verbatim via bash, then steps this state's actor."
               },
               "prompt": {
                 "type": "string",
@@ -136,6 +136,10 @@
               "reviewBase": {
                 "type": "boolean",
                 "description": "Marks the state whose most-recent in-process commit anchors the review window's diff base; absent any, the base is the process start. Forbidden on a commit state."
+              },
+              "reviewEntry": {
+                "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."
               }
             }
           }