@pmelab/gtd 2.7.0 → 3.0.0

package/docs/examples/advanced-workflow.md

@@ -0,0 +1,428 @@
+# Example: the full grilling → architecting → decompose → picking → review machine
+
+This is the fuller machine gtd shipped as its bundled default before the bundled
+default was drastically simplified (see
+[STATES.md §10](../../STATES.md#10-the-bundled-default-workflow) for what ships
+today — including the two steering-file validation loops the current default
+carries over `.gtd/TODO.md` and `.gtd/REVIEW.md`, which this example's own
+`grilling`/`reviewing` phases predate and don't validate). It is preserved here
+as a copy-paste-ready `.gtdrc` recipe for anyone who wants the heavier shape
+back.
+
+Compared to the simplified bundled default, this machine adds:
+
+- **Two-phase human-in-the-loop planning with Q&A loops** — `grilling` ⇄
+  `grilling-answer` develops a product-level plan from `.gtd/TODO.md` one open
+  question at a time; `architecting` ⇄ `architecting-answer` repeats the same
+  shape for `.gtd/ARCHITECTURE.md`, the technical plan built on top of the
+  converged product plan.
+- **Task decomposition** — `decompose` turns the converged architecture into an
+  ordered set of self-contained task files under `.gtd/tasks/`.
+- **The deterministic `picking` queue arbiter** — a `script` state that feeds
+  tasks into `.gtd/NEXT.md` one at a time, with a per-task `building` →
+  `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.
+- **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
+  this: it rests at `idle` on approval instead and leaves every turn commit in
+  history for the human to squash (or not) however they choose.
+
+This example also carries `file:`/`mode:` annotations on every state that rests
+on a steering file (see the state table below and
+[docs/design/state-file-association.md](../design/state-file-association.md)) —
+it is the LSP-heavy flow, with `gtd lsp` dispatching document symbols/code
+actions/diagnostics off those declarations rather than a hardcoded basename:
+`grilling`/`grilling-answer` and `architecting`/`architecting-answer` are
+`qa`-format (`vars.todoFile`/`vars.architectureFile` respectively — a new
+`architectureFile` var joins `testCommand`), `reviewing`/`await-review` are
+`review`-format (`vars.reviewFile`), and `fixing`/`escalate` declare `file:`
+alone (`vars.feedbackFile` is plain text, no LSP format).
+
+Paste the block below under a top-level `workflow:` key in your own `.gtdrc` (or
+`.gtdrc.yaml`) — it's the complete definition, unmodified in content from the
+version this example is frozen from, only re-indented to nest under `workflow:`.
+See [Configuration](../configuration.md) for the `.gtdrc` schema this slots
+into.
+
+## State table
+
+| State                 | Actor | Content | `on`                                                                              | Retry              | Model   | File                    | Mode     |
+| --------------------- | ----- | ------- | --------------------------------------------------------------------------------- | ------------------ | ------- | ----------------------- | -------- |
+| `idle` (initial)      | human | message | `* **` → `grilling`                                                               | —                  | —       | —                       | —        |
+| `grilling`            | agent | prompt  | `* **` → `grilling-answer`                                                        | —                  | `smart` | `vars.todoFile`         | `qa`     |
+| `grilling-answer`     | human | message | `C` → `architecting`; `* **` → `grilling`                                         | —                  | —       | `vars.todoFile`         | `qa`     |
+| `architecting`        | agent | prompt  | `* **` → `architecting-answer`                                                    | —                  | `smart` | `vars.architectureFile` | `qa`     |
+| `architecting-answer` | human | message | `C` → `decompose`; `* **` → `architecting`                                        | —                  | —       | `vars.architectureFile` | `qa`     |
+| `decompose`           | agent | prompt  | `* .gtd/tasks/**` → `picking`                                                     | —                  | —       | —                       | —        |
+| `picking`             | check | script  | `D .gtd/NEXT.md` → `reviewing`; `* .gtd/NEXT.md` → `building`; `C` → `reviewing`  | —                  | —       | —                       | —        |
+| `building`            | agent | prompt  | `* **` → `checking`                                                               | —                  | —       | —                       | —        |
+| `checking`            | check | script  | `A .gtd/FEEDBACK.md` → `fixing`; `M .gtd/FEEDBACK.md` → `fixing`; `C` → `picking` | —                  | —       | —                       | —        |
+| `fixing`              | agent | prompt  | `* **` → `checking`                                                               | max 3 → `escalate` | —       | `vars.feedbackFile`     | —        |
+| `escalate`            | human | message | `* **` → `checking`                                                               | —                  | —       | `vars.feedbackFile`     | —        |
+| `reviewing`           | agent | prompt  | `* .gtd/REVIEW.md` → `await-review`                                               | —                  | `smart` | `vars.reviewFile`       | `review` |
+| `await-review`        | human | message | `D .gtd/REVIEW.md` → `squashing`; `* **` → `grilling`                             | —                  | —       | `vars.reviewFile`       | `review` |
+| `squashing`           | agent | prompt  | `A .gtd/COMMIT_MSG.md` → `done`; `M .gtd/COMMIT_MSG.md` → `done`                  | —                  | —       | —                       | —        |
+| `done`                | —     | commit  | (final — squashes the whole cycle, message read from `.gtd/COMMIT_MSG.md`)        | —                  | —       |
+
+## The `.gtdrc` recipe
+
+````yaml
+workflow:
+  vars:
+    testCommand: npm test
+    todoFile: .gtd/TODO.md
+    architectureFile: .gtd/ARCHITECTURE.md
+    reviewFile: .gtd/REVIEW.md
+    feedbackFile: .gtd/FEEDBACK.md
+
+  states:
+    idle:
+      actor: human
+      initial: true
+      message: |
+        No active gtd cycle.
+
+        To start one: write `.gtd/TODO.md` with a short sketch of what you want
+        built — a few sentences is enough — then run `gtd step human`.
+      on:
+        "* **": grilling
+
+    grilling:
+      actor: agent
+      file: <%= it.vars.todoFile %>
+      mode: qa
+      # `model` is an opaque harness hint — gtd never interprets this string, it
+      # only passes it through to `gtd next --json`/`gtd status --json` so the
+      # driving loop can map it onto whatever models its agent harness
+      # provides. "smart" here just names the harness-chosen tier for the
+      # heavier planning/reviewing turns; states without a `model` use the
+      # harness's default.
+      model: smart
+      prompt: |
+        You are an autonomous coding agent. `.gtd/` holds this workflow's own
+        state (plans, task specs, review records) — never create, edit, or
+        delete anything under `.gtd/` except `<%= it.vars.todoFile %>`, which
+        this prompt tells you to write.
+
+        `<%= it.vars.todoFile %>` holds the plan under development. Read it,
+        then develop it into a concrete, product-level plan in this one turn —
+        explore the codebase before asking anything, so every open question is
+        one the codebase genuinely cannot answer.
+
+        Scope: product and user-facing decisions only. Leave implementation
+        details (file/module structure, data models, tech-stack choices) for
+        the next phase (`.gtd/ARCHITECTURE.md`).
+
+        For every remaining open question, add it under a `## Open Questions`
+        heading, one `### <question>` sub-heading each, with a
+        `Suggested default: <answer>` line the human can accept as-is. Omit the
+        section entirely once there are none.
+
+        Leave `.gtd/TODO.md` uncommitted and finish your turn — do not commit,
+        and do not run `gtd step agent` yourself; the harness does that.
+      on:
+        "* **": grilling-answer
+
+    grilling-answer:
+      actor: human
+      file: <%= it.vars.todoFile %>
+      mode: qa
+      message: |
+        `<%= it.vars.todoFile %>` holds the plan under development, with any
+        open questions under `## Open Questions` — each carrying a suggested
+        default.
+
+        To answer a question, edit its entry in place (replace
+        `Suggested default: ...` with `Answer: ...`, or annotate further), then
+        run `gtd step human`.
+
+        To accept all suggested defaults as-is and move on to technical
+        architecting, run `gtd step human` with no edits.
+      on:
+        "C": architecting
+        "* **": grilling
+
+    architecting:
+      actor: agent
+      file: <%= it.vars.architectureFile %>
+      mode: qa
+      model: smart
+      prompt: |
+        You are an autonomous coding agent. `.gtd/` holds this workflow's own
+        state — never create, edit, or delete anything under `.gtd/` except
+        `<%= it.vars.architectureFile %>` and `<%= it.vars.todoFile %>`, which
+        this prompt tells you to write and delete respectively.
+
+        Read `<%= it.vars.todoFile %>` (the converged product plan) and
+        develop `<%= it.vars.architectureFile %>` from it in this one turn:
+        file/module structure, data models, library/tech-stack choices,
+        error-handling strategy — the *how*, building on the *what* already
+        settled. Do not re-open product-level decisions from
+        `<%= it.vars.todoFile %>`; treat them as settled.
+
+        For every remaining open question, add it under a `## Open Questions`
+        heading the same way as the grilling phase (one `### <question>`
+        sub-heading, a `Suggested default: <answer>` line). Omit the section
+        once there are none.
+
+        Once `<%= it.vars.architectureFile %>` is written, delete
+        `<%= it.vars.todoFile %>` — its content has been folded in and it must
+        not linger.
+
+        Leave everything uncommitted and finish your turn.
+      on:
+        "* **": architecting-answer
+
+    architecting-answer:
+      actor: human
+      file: <%= it.vars.architectureFile %>
+      mode: qa
+      message: |
+        `<%= it.vars.architectureFile %>` holds the technical plan under
+        development, with any open questions under `## Open Questions`.
+
+        To answer a question, edit its entry in place, then run
+        `gtd step human`.
+
+        To accept all suggested defaults as-is and move on to decomposing the
+        work, run `gtd step human` with no edits.
+      on:
+        "C": decompose
+        "* **": architecting
+
+    decompose:
+      actor: agent
+      prompt: |
+        You are an autonomous coding agent. `.gtd/` holds this workflow's own
+        state — never create, edit, or delete anything under `.gtd/` except the
+        task-spec files this prompt tells you to write (under `.gtd/tasks/`),
+        and `.gtd/ARCHITECTURE.md`, which it tells you to delete.
+
+        Read `.gtd/ARCHITECTURE.md` (the converged technical plan) and
+        decompose it into an ordered set of self-contained task files under
+        `.gtd/tasks/` (e.g. `.gtd/tasks/01-short-name.md`,
+        `.gtd/tasks/02-short-name.md`, ...). Order them so the test suite can
+        pass again after each one lands; each file is self-contained
+        (description, acceptance criteria as `- [ ]` checkboxes, relevant
+        paths) since a building turn receives only that one file as context.
+
+        No task file may reference any other `.gtd/` file, or a requirement to
+        preserve/update workflow state — `.gtd/` is machine-managed and gets
+        cleaned up as the cycle proceeds.
+
+        Once the task files are written, delete `.gtd/ARCHITECTURE.md`. Leave
+        everything uncommitted and finish your turn.
+      on:
+        "* .gtd/tasks/**": picking
+
+    picking:
+      actor: check
+      script: |
+        #!/usr/bin/env bash
+        # gtd check turn (the queue arbiter) — the driver (`gtd run`) executes
+        # this verbatim, then steps the check actor. Mechanics only: take the
+        # first task file (by name) under .gtd/tasks/ into .gtd/NEXT.md, or
+        # remove .gtd/NEXT.md when the queue is empty. What NEXT.md's
+        # presence/absence MEANS (another task to build vs. the queue closing
+        # out to review) is decided by this state's own `on` rules at capture
+        # time — never here.
+        set +e
+        next=$(ls .gtd/tasks/*.md 2>/dev/null | head -n 1)
+        if [ -n "$next" ]; then
+          printf '%s' "$next" > .gtd/NEXT.md
+        else
+          rm -f .gtd/NEXT.md
+        fi
+      on:
+        "D .gtd/NEXT.md": reviewing
+        "* .gtd/NEXT.md": building
+        "C": reviewing
+
+    building:
+      actor: agent
+      prompt: |
+        You are an autonomous coding agent. `.gtd/` holds this workflow's own
+        state — never create or edit anything under `.gtd/` except deleting the
+        one task file this prompt tells you to delete; never touch
+        `.gtd/NEXT.md` yourself — the `picking` state owns it.
+
+        The task file to implement is: <%~ it.read(".gtd/NEXT.md") %>
+
+        Read that file and implement EXACTLY the one task it describes — no
+        more, no less; leave every other task file under `.gtd/tasks/`
+        untouched. Use TDD discipline: one test, then the implementation that
+        passes it, then the next — never write all the tests first.
+
+        Delete the task file once its work is complete and verified. Leave
+        everything else uncommitted and finish your turn.
+      on:
+        "* **": checking
+
+    checking:
+      actor: check
+      script: |
+        #!/usr/bin/env bash
+        # gtd check turn — the driver (`gtd run`) executes this verbatim, then
+        # steps the check actor. Mechanics only: run the test suite and record a
+        # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another
+        # fix round vs escalation) is decided by the workflow's own `on`/`retry`
+        # rules at capture time — never here.
+        #
+        # `it.vars.testCommand` defaults to "npm test" (this workflow's own
+        # `vars:` above) — override it with a top-level `.gtdrc`
+        # `vars: { testCommand: ... }` key, or a `GTD_VAR_testCommand`
+        # environment variable (highest precedence).
+        set +e
+        mkdir -p .gtd
+        <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1
+        code=$?
+        if [ "$code" -ne 0 ]; then
+          if [ -s .gtd/.check-output ]; then
+            mv .gtd/.check-output .gtd/FEEDBACK.md
+          else
+            rm -f .gtd/.check-output
+            printf 'npm test failed with exit code %s and produced no output.' "$code" > .gtd/FEEDBACK.md
+          fi
+        else
+          rm -f .gtd/.check-output
+        fi
+      on:
+        "A .gtd/FEEDBACK.md": fixing
+        "M .gtd/FEEDBACK.md": fixing
+        "C": picking
+
+    fixing:
+      actor: agent
+      file: <%= it.vars.feedbackFile %>
+      retry:
+        max: 3
+        otherwise: escalate
+      prompt: |
+        You are an autonomous coding agent. `.gtd/` holds this workflow's own
+        state — never create, edit, or delete anything under `.gtd/` except
+        `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.
+
+        Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix
+        the code so the suite passes. Keep the change focused — do not
+        refactor unrelated code. If the feedback is wrong, empty or delete
+        `<%= it.vars.feedbackFile %>` instead of "fixing" a non-issue; the
+        machine picks the dispute up either way.
+
+        Leave everything uncommitted and finish your turn — do not commit.
+      on:
+        "* **": checking
+
+    escalate:
+      actor: human
+      file: <%= it.vars.feedbackFile %>
+      message: |
+        The agent could not get the check to pass after repeated attempts.
+        `<%= it.vars.feedbackFile %>` holds the last failing output.
+
+        Investigate and fix it yourself (editing code and/or
+        `<%= it.vars.feedbackFile %>`), then run `gtd step human` to try the
+        check again.
+      on:
+        "* **": checking
+
+    reviewing:
+      actor: agent
+      file: <%= it.vars.reviewFile %>
+      mode: review
+      model: smart
+      prompt: |
+        You are an autonomous coding agent. `.gtd/` holds this workflow's own
+        state — never create, edit, or delete anything under `.gtd/` except
+        `<%= it.vars.reviewFile %>`, which this prompt tells you to write.
+
+        Write `<%= it.vars.reviewFile %>` to help a human review the cycle's
+        full diff (inlined below): group hunks semantically (same
+        feature/refactor/fix, even across files), and for each group write a
+        short heading, an explanation of what changed and why, and
+        `- [ ] ./path/to/file.ts#42` style file pointers (checkboxes are for
+        the human to tick, not you).
+
+        Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.
+        <% if (it.processDiff.trim()) { %>
+
+        ## Full cycle diff
+
+        ```diff
+        <%~ it.processDiff %>
+        ```
+        <% } %>
+      on:
+        "* .gtd/REVIEW.md": await-review
+
+    await-review:
+      actor: human
+      file: <%= it.vars.reviewFile %>
+      mode: review
+      message: |
+        `<%= it.vars.reviewFile %>` holds the review record for the completed
+        cycle.
+
+        To approve: delete `<%= it.vars.reviewFile %>` and run
+        `gtd step human`.
+
+        To request changes: edit `<%= it.vars.reviewFile %>` (or the code)
+        with what's wrong — including just ticking its checkboxes — then run
+        `gtd step human`; this sends the cycle back through grilling with your
+        feedback as the new input.
+      on:
+        "D .gtd/REVIEW.md": squashing
+        "* **": grilling
+
+    squashing:
+      actor: agent
+      prompt: |
+        You are an autonomous coding agent. The cycle is approved and done.
+        `.gtd/` holds this workflow's own state — never create, edit, or delete
+        anything under `.gtd/` except `.gtd/COMMIT_MSG.md`, which this prompt
+        tells you to write.
+
+        Write `.gtd/COMMIT_MSG.md` with ONE conventional-commits message for
+        the entire cycle (subject line `type(scope): subject`, imperative mood,
+        <= 72 characters; a body explaining the why, trade-offs, and key
+        decisions). Plain text, no markdown wrapper.
+
+        Leave `.gtd/COMMIT_MSG.md` uncommitted and finish your turn — entering
+        this file squashes the whole cycle into one commit using its content as
+        the message.
+        <% if (it.processDiff.trim()) { %>
+
+        ## Full cycle diff
+
+        ```diff
+        <%~ it.processDiff %>
+        ```
+        <% } %>
+      on:
+        "A .gtd/COMMIT_MSG.md": done
+        "M .gtd/COMMIT_MSG.md": done
+
+    done:
+      commit: '<%~ it.read(".gtd/COMMIT_MSG.md") %>'
+````
+
+A clean `gtd step human` at `grilling-answer`/`architecting-answer` (the `C`
+event) accepts the current phase's draft and moves on; any other pending change
+loops back for another round. `picking` is a `script` state whose only job is to
+inspect `.gtd/tasks/` (a tree property patterns can't see directly) and turn it
+into a diff patterns CAN see — see the walkthrough in
+[STATES.md §10](../../STATES.md#10-the-bundled-default-workflow) (the version of
+that section frozen alongside this example) for the full state-by-state
+narrative, including the `on`-declaration-order subtlety at `picking` and the
+`fixing` retry-cap pooling caveat.
+
+## See also
+
+- [docs/design/work-packages.md](../design/work-packages.md) — the arbiter's
+  decision record: why the scripted `picking` state (Option A) was chosen over
+  the agent-encoded-verdict, tree-predicate-guard, and template-enumeration
+  alternatives, plus the process-per-task topology variant.
+- [STATES.md](../../STATES.md) — the pattern-machine model this recipe compiles
+  against (pattern grammar, resolution, retry, the squash lifecycle).

package/docs/loop.md

@@ -0,0 +1,104 @@
+# Driving the loop
+
+gtd (v3, the pattern machine) exposes three commands a loop driver combines:
+
+- **`gtd step <actor>`** — authenticate as `<actor>`, match the resolved rest's
+  declared patterns against the pending changes, and commit (or squash) the one
+  resulting transition. Performs AT MOST one transition — there is no fixpoint
+  chain to drive.
+- **`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.
+
+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?}` 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).
+
+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.
+
+```bash
+gtd next --json   # ask who's up and what they should do
+```
+
+See [`skills/loop/SKILL.md`](../skills/loop/SKILL.md) for the agent-facing
+instructions that follow the same pinned contract. `gtd-loop`, installed
+alongside `gtd` (see below), is the packaged, ready-to-run implementation of
+that same script for anyone who doesn't want to drive the loop by hand.
+
+## The reference loop driver
+
+A minimal bash implementation of the pinned protocol, driving an agent CLI (e.g.
+`claude -p`) against `gtd next --json` output. This is the authoritative
+reference for what a loop driver must do; keep any other implementation
+(including `skills/loop/SKILL.md`) consistent with it rather than editing both
+independently. `bin/gtd-loop` is this exact script, packaged as the `gtd-loop`
+binary, with three additions: it stops with a diagnostic if the same `"prompt"`
+state/content repeat with no progress (see `skills/loop/SKILL.md`'s "Stall
+detection"); it lets `GTD_LOOP_AGENT_CMD` swap in any coding agent CLI in place
+of the default `claude -p`, receiving the prompt via `$GTD_LOOP_PROMPT`; and it
+exports the resolved state's optional `model` hint as `$GTD_LOOP_MODEL`,
+appending `--model "$GTD_LOOP_MODEL"` to the default `claude -p` invocation
+whenever it's non-empty.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+while true; do
+  next_json="$(gtd next --json)"
+  state="$(jq -r .state <<<"$next_json")"
+  actor="$(jq -r .actor <<<"$next_json")"
+  kind="$(jq -r .kind <<<"$next_json")"
+  content="$(jq -r .content <<<"$next_json")"
+
+  if [[ "$kind" == "message" ]]; then
+    echo "--- Your turn ($state) ---"
+    gtd next
+    exit 0
+  fi
+
+  if [[ "$kind" == "script" ]]; then
+    head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
+    gtd run
+    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) ---"
+      exit 0
+    fi
+    continue
+  fi
+
+  # kind == "prompt": feed the prompt to the agent, then close out its turn.
+  claude -p "$content" --dangerously-skip-permissions
+  gtd step "$actor" >/dev/null
+done
+```
+
+The driver — not the prompt text — owns ending the agent's turn
+(`gtd step "$actor"` right after the agent acts): every default-workflow agent
+prompt says explicitly not to run `gtd step agent` itself.
+
+## Using a different agent
+
+`gtd-loop` defaults to
+`claude -p "$GTD_LOOP_PROMPT" --dangerously-skip-permissions`, but the agent
+invocation is swappable: set `GTD_LOOP_AGENT_CMD` to any shell command, and it
+runs with the prompt available as `$GTD_LOOP_PROMPT` (and the resolved state's
+opaque `model` hint, if any, as `$GTD_LOOP_MODEL`) in its environment — an
+adapter that ignores `$GTD_LOOP_MODEL` keeps working unchanged. For example, to
+drive a different agent CLI:
+
+```bash
+GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
+```

package/docs/upgrading.md

@@ -0,0 +1,125 @@
+# Upgrading to v3 (BREAKING CHANGE)
+
+## v3 is a clean break
+
+v3 ("the pattern machine") deletes the entire v2 definition model — gates, guard
+functions, actor kinds, interrupt/fallback ladders, capture rules, turn and
+routing rules, `Gtd-Counters` trailers, conflicts, the review checkout window —
+and replaces it with the much smaller pattern machine described in
+[STATES.md](../STATES.md): named states, each with one content kind and an
+ordered map of change-patterns to next states.
+
+**All pre-v3 history is unrecognized and resolves to the initial state, by
+design — v1 and v2 subjects alike.** v3's `resolveState`
+(`src/PatternMachine.ts`) only recognizes its own `gtd(<actor>): <state>`
+subject naming a state and an actor the active workflow currently declares;
+everything else — a v1 `gtd: grilling`, a v2 `gtd(agent): building`, a plain
+`chore: …` commit, anything from a foreign repo — parses as unrecognized and
+lands at the workflow's initial state (`idle` in the bundled default). There is
+no special-casing for "this looks like an old gtd commit": the mechanism is
+exactly the same one that already made v1 history inert to v2, and v2 history
+inert to a differently-configured workflow — v3 just applies it uniformly to all
+prior history instead of drawing a v1/v2 line.
+
+**Finish or squash any in-flight cycle first.** A repo mid-cycle on v1 or v2 has
+no v3-shaped commit backing its steering files; upgrading mid-cycle lands cold
+at the initial state with those files still pending, which the new workflow's
+`on` patterns will classify as ordinary pending changes, not as the phase they
+used to represent. Finish the cycle (or squash it) on the old binary first, or
+manually clean up the steering files and commit a plain boundary, before
+upgrading.
+
+## What died
+
+- **Counters.** `Gtd-Counters` trailers, `fixAttemptCap`/`reviewThreshold`
+  config keys, and the counter-stamp machinery are gone. The only budget
+  affordance left is a state's own `retry: { max, otherwise }`
+  (§[STATES.md](../STATES.md#7-retry)) — a plain per-process entry cap
+  redirected at write time, with no trailer to read back.
+- **`.gtdrc` keys.** The old `testCommand`, `fixAttemptCap`, `reviewThreshold`,
+  `agenticReview`, `squash`, `learning`, `decisionLog`, and `models` keys are
+  all gone — `workflow:` and `vars:` are the only two blessed keys (see
+  [Configuration](configuration.md)). A check's command now lives inline in its
+  own `script:` content, reading a workflow-declared `it.vars` entry (the
+  bundled default's `testCommand`, overridable via the top-level `vars:` key or
+  a `GTD_VAR_testCommand` environment variable — see
+  [Configuration's "Variables"](configuration.md#variables)) rather than a
+  blessed `testCommand` config key; squashing is a `commit:` state instead of a
+  boolean flag; there is no learning phase, no decision log, and no model
+  tiering — a workflow author is free to build any of that shape back with
+  states of their own, but gtd no longer bakes it in.
+- **The review checkout window.** v2 rewound HEAD/index to the review base while
+  a human review rested, so editors would show the diff directly. Deleted in v3
+  (may return later as an explicit state property — not in scope now).
+- **`forceApprove`, content-inspection verdicts.** FEEDBACK.md emptiness,
+  checkbox-only REVIEW.md diffs, and doc-structure validation are gone as ENGINE
+  mechanisms — verdicts are now expressed purely by which file a turn writes or
+  deletes, matched by an ordinary `on` pattern. The bundled default workflow's
+  own two validation loops (`todo-validating`/`review-validating`/
+  `review-deciding` — see
+  [docs/design/steering-file-loops.md](design/steering-file-loops.md)) rebuild
+  checkbox-review and doc-structure verdicts as ordinary WORKFLOW data
+  (`script`-content states + `on` patterns), not an engine hook: `D REVIEW.md` =
+  approve, `M REVIEW.md` = route to the deterministic decider, in the bundled
+  default.
+- **`gtd questions` / `gtd changesets` / `gtd review <target>`.** Gone; the v3
+  command surface is `step` / `next` / `run` / `status` / `format` / `lsp` (see
+  [CLI reference](cli.md)).
+- **Model tiers, the decision log.** No `models` config key, no `Gtd-Decisions`
+  trailer scan, no grilling/architecting "prior decisions" context assembled
+  from history.
+- **LSP.** Deleted at the v3 rewrite, then resurrected file-format-keyed rather
+  than state-keyed (`gtd lsp` — see
+  [Development](development.md#the-lsp-server)). The `gtd.openSteeringFile`
+  command is BACK (see
+  [docs/design/state-file-association.md](design/state-file-association.md)) —
+  config-driven rather than the v2 hardcoded state→file map: any state may
+  declare a `file:` (an Eta template) and a `mode:` (`qa`/`review`, the file's
+  format), the LSP reads that same config the CLI does to build its path→mode
+  dispatch, and `gtd.openSteeringFile` resolves the current state and shows its
+  `file:`. No mapping declared at all (the bundled default's predecessor shape,
+  or any workflow with no `file:`/`mode:`) falls back to basename dispatch
+  (`TODO.md`/`REVIEW.md`), same as before this addition.
+
+## How to adopt
+
+`workflow:` is optional — with no config at all, the bundled default workflow
+applies: a single-shot `grilling` plan, direct `building`, a `checking`/`fixing`
+loop, and a direct-diff `await-review` that rests the cycle back at `idle` on
+approval — no squash; every turn commit stays in history for you to squash
+however you like, or not at all (see
+[STATES.md §10](../STATES.md#10-the-bundled-default-workflow)) — expressed as
+data rather than baked into the engine. The fuller grilling ⇄ grilling-answer /
+architecting ⇄ architecting-answer / decompose / picking / reviewing shape v2
+shipped — including a squash finale — is preserved as a copy-paste `.gtdrc`
+example at [docs/examples/advanced-workflow.md](examples/advanced-workflow.md)
+rather than the bundled default. Nothing to do for a repo that's happy with the
+default shape beyond a normal `npm install -g @pmelab/gtd` upgrade, from a
+settled `idle` boundary.
+
+A repo that customized v2's `workflow:` key (actors, gates, guard vocabulary,
+ladders) needs to rewrite it from scratch in the v3 schema — see
+[Configuration](configuration.md) for the schema and a complete worked example.
+There is no automatic migration: the two vocabularies don't map field-for-field
+(guards become patterns, capture rules become `on` targets, counters become
+`retry`), so a v2 `workflow:` config is simply invalid v3 config and fails
+loudly at load time rather than silently misinterpreting.
+
+**Re-copy the loop skill.** If you vendor `skills/loop/` into a consuming repo
+or agent harness, upgrading the `gtd` binary also means re-copying that skill
+from this release.
+
+## Prior breaking change: the v1 → v2 label grammar (historical)
+
+v2 replaced v1's undifferentiated turn labels with six labels carrying the
+branch outcome at capture time, moved steering files under `.gtd/`, and
+introduced `Gtd-Counters` commit trailers. All of that is itself now superseded
+by v3's clean break above — a v1 or v2 repo upgrades to v3 the same way
+(finish/squash any in-flight cycle, then upgrade from a settled boundary);
+there's no reason to upgrade v1 → v2 → v3 in two hops.
+
+For maintainers: this repo releases via `semantic-release` reading Conventional
+Commits, and needs **no config change** for a major bump — but the release
+commit/PR **must carry a `BREAKING CHANGE:` footer** (or a `!` after the type)
+for `@semantic-release/commit-analyzer` to compute the next major version rather
+than a minor/patch bump.