@pmelab/gtd 8.0.0 → 8.2.0

package/docs/development.md

@@ -1,109 +0,0 @@
-# Development
-
-```bash
-npm install
-npm run dev          # run from source, no build (node dev/run.mjs)
-npm run build        # tsdown → dist/gtd.bundle.mjs
-npm test             # format:check, typecheck, lint, unit + e2e tests, fallow
-npm run test:unit    # vitest unit tests (the pure resolver) — --project unit
-npm run test:e2e     # gherkin e2e via vitest + quickpickle — --project e2e
-npm run test:mutation # StrykerJS mutation testing (manual only, ~2 min)
-npm run typecheck
-npm run lint
-```
-
-## Pre-commit hook
-
-A pre-commit hook is installed automatically via the `prepare` script when you
-run `npm install` on a fresh clone — no manual setup needed. The hook runs
-[lint-staged](https://github.com/lint-staged/lint-staged) with
-[oxfmt](https://oxc.rs/docs/guide/usage/formatter.html), formatting every staged
-file before each commit (`oxfmt --no-error-on-unmatched-pattern --write`),
-mirroring the `format:check` step enforced in CI (`oxfmt --check .`).
-
-## Templates
-
-Every state's content (`script`/`prompt`/`message`/`commit`) is an Eta template
-string, rendered by `src/PatternTemplates.ts`'s `renderStateTemplate` against
-the variable set documented in
-[Configuration](configuration.md#template-variables). There is no template-file
-registry to keep in sync: a workflow's content strings are either inline in its
-YAML/`.gtdrc` or a `./`-relative file reference auto-inlined at config load
-(`src/PatternConfig.ts`) — see
-[Configuration](configuration.md#content-values-inline-or-a-file-reference). The
-bundled workflow template (`src/workflows/unified.yaml`) gtd runs as its
-built-in default (and materializes into config form via `renderInitConfig`) is
-imported as raw text via tsdown's `.yaml`-as-text loader (`tsdown.config.ts`)
-and compiled through the same path a `.gtdrc` `workflow:` key goes through
-(`src/workflows/templates.ts`) — no privileged code path.
-
-`npm run dev` runs `src/main.ts` directly via Node's native TypeScript
-type-stripping (requires Node 22.6+). It registers `dev/hooks.mjs`, which
-resolves `./Foo.js` specifiers to the on-disk `./Foo.ts` and imports `*.yaml`
-files as raw text, mirroring tsdown's `.yaml`-as-text loader — this is what lets
-`src/workflows/unified.yaml` resolve when running from source.
-
-The decision core is pure and IO-free: the pattern machine's shape (states,
-patterns, retry) is a plain-data `WorkflowDefinition` (`src/PatternMachine.ts`),
-and the same module's `resolveState`/`step` are the pure resolver/interpreter
-over it — so the whole engine is trivially unit-testable in isolation; all
-git/filesystem/template IO is confined to the edge (`src/Edge.ts`).
-
-`npm run build` produces `dist/gtd.bundle.mjs`, which npm exposes as the `gtd`
-binary via the `bin` field in `package.json`.
-
-## The LSP server
-
-`gtd lsp` (`src/Lsp.ts`) serves editor tooling over `.gtd/`'s two steering-file
-formats — document symbols and diagnostics for `.gtd/TODO.md`'s open questions
-and `.gtd/REVIEW.md`'s review chunks/hunks, plus check/uncheck code actions for
-the latter. It's keyed on file NAME, not workflow state: a v3 workflow declares
-no state→file mapping (a state names no file), so the server needs no
-git/`.gtdrc` dependency at all and serves whatever content the editor hands it
-over the LSP protocol, exactly like any other document.
-
-`src/OpenQuestions.ts` and `src/ReviewDoc.ts` are the pure parsers behind both
-the LSP and the `gtd validate` command, which resolves the current state, reads
-its `file:`, and evaluates it per its `mode:` — ONE source of truth per format,
-no bash port and no dual-implementation contract to keep in sync. Mode dispatch
-itself lives in `src/SteeringMode.ts`, half by half: the two BUILT-IN mode names
-validate with these parsers (`qa` → `parseOpenQuestions`, `review` →
-`parseReviewDoc`), while a `modes:` entry's `format:`/`validate:` shell commands
-take precedence per half — gtd itself ships no formatter. See
-[docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
-and
-[docs/design/pluggable-steering-modes.md](design/pluggable-steering-modes.md)
-and [STATES.md §12](../STATES.md) for the command, and each module's own doc
-comment for the format it defines. Their unit tests are that format's spec
-tests.
-
-## Mutation testing
-
-Run mutation testing on-demand with `npm run test:mutation` (StrykerJS) — never
-run it as part of routine development; it is a deliberate, manually-triggered
-check. `stryker.config.json`'s `mutate` list names the v3 pattern-machine module
-set (`src/PatternMachine.ts`, `src/PatternConfig.ts`, `src/PatternTemplates.ts`,
-`src/Edge.ts`, `src/Config.ts`, `src/Format.ts` — see
-[Architecture](../AGENTS.md#the-pattern-machine-module-map) for the v3 module
-map), plus the steering-file format parsers and the LSP built on them
-(`src/OpenQuestions.ts`, `src/ReviewDoc.ts`, `src/Lsp.ts` — see
-["The LSP server"](#the-lsp-server) below). `src/Lsp.ts`'s protocol-adapter tail
-(`startLspServer`) is exercised only by the `@live` e2e (excluded from the
-mutation run's Cucumber harness), so mutants confined to that tail may survive
-without it being a coverage gap in the ordinary test suite — the pure
-symbol/edit/diagnostic builders above it are unit-tested and mutation-checked
-normally.
-
-`src/Git.ts` is excluded: the Cucumber harness stubs git at the Effect boundary,
-so `Git.ts` mutants have zero in-memory coverage.
-
-The HTML report lands in `reports/mutation/mutation.html` (git-ignored).
-
-## Releasing
-
-Releases are automatic. Push releasable Conventional Commits (`fix:`, `feat:`,
-or breaking changes) to `main` and the Release workflow runs the tests, then
-`npx semantic-release`. Semantic-release computes the next version, writes it
-into `package.json`, builds the bundle, commits the bump back as
-`chore(release): X.Y.Z [skip ci]`, tags `vX.Y.Z`, and creates the GitHub release
-with `gtd.bundle.mjs` attached.

package/docs/loop.md

@@ -1,219 +0,0 @@
-# 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. Pass `--cost=<n>` (optionally `--model=<name>`) to record the
-  just-finished invocation's token cost and model on the turn commit; gtd sums
-  them across the process into `it.processCost`/`it.processCostByModel` (see
-  [Configuration: Token cost](configuration.md#token-cost)).
-- **`gtd next`** — print the resolved rest's rendered script/prompt/message,
-  without mutating anything.
-
-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?, label?}` field shape. `kind`
-   is the 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. The optional `label` is a
-   human-readable display name for the resolved state, present only when that
-   state declares `label:` in the workflow; when it's absent, a driver that
-   wants to show something falls back to `state` itself (that fallback lives in
-   the driver, not gtd core — see `bin/gtd-loop`'s
-   `label="$(jq -r '.label // .state' <<<"$next_json")"`).
-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); `gtd step human` captures the edit as their turn. A driver can run that
-capture for the human as its opening move (see below), so re-launching the loop
-is the only thing the human ever does — at a gate they edit and re-run, and the
-loop picks their change up.
-
-**A `"message"` rest is a real handoff, not a slow beat.** No driver signs off
-for the human: in the bundled workflow the loop runs the whole cycle unattended
-up to `await-review` and then rests there with the review checkout window open
-(the reviewable diff surfaced as uncommitted changes — see
-[STATES.md §11](../STATES.md#11-the-review-checkout-window)). Advancing takes a
-human edit to `.gtd/REVIEW.md`: ticking every box with **no** comment signs off
-into the squash finale, while any comment (a note, or a code edit of your own)
-is feedback that routes into another build + re-review round. That gate is the
-contract, not a stall — nothing advances until the edit is captured, whether the
-capture happens within the same run or a later one. A review nobody is going to
-finish is ended with [`gtd abandon`](cli.md#gtd-abandon---json), which drops the
-process's commits and keeps their content as uncommitted changes.
-
-**The loop drives only the autonomous states.** Reaching a `"message"` rest, it
-prints the gate via `gtd next` and exits 0 — the human edits and re-launches the
-loop, whose opening move captures what they left. Anything richer at that
-boundary (opening an editor on the gate's file, desktop notifications,
-terminal-multiplexer status) is deliberately an OUTER wrapper's responsibility,
-not `bin/gtd`'s.
-
-Pass `--once` — see [`cli.md`](cli.md#--once) for its exact syntax and
-positioning — to restrict the loop to exactly one beat — one human-gate capture,
-one script check+step, or one agent prompt+step — then exit, instead of driving
-all the way to idle/settled.
-
-```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` itself (bare, or with
-`loop` as its first argument — 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. Both open with the same move — capture the human's pending edit
-when the machine rests at a `"message"` gate — so `gtd` is the only command a
-human runs. `bin/gtd` is the packaged entry point: invoked bare, or with `loop`
-as its first argument, it runs this exact script; any other first argument (e.g.
-`next`, `step`, `status`) hands off to `node dist/gtd.bundle.mjs` instead. The
-loop body it runs adds five things on top of the reference script above: it can
-restrict itself to exactly one beat via `--once` instead of driving to
-idle/settled; 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`; 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; and it acts on the optional `memory` scope hint (see "Agent memory
-scope" below) — continuing one agent session across consecutive same-scope turns
-and starting fresh when the scope changes.
-
-`bin/gtd` resolves both its bundle hand-off and the loop's own internal `gtd`
-calls against `dist/gtd.bundle.mjs` next to its own location. Set `GTD_BIN` — a
-full command, not just a path — to point both at source instead, e.g. for
-development or testing:
-
-```bash
-GTD_BIN="node $PWD/dev/run.mjs" bin/gtd
-```
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Opening move: if the machine rests at a human gate, capture the human's
-# pending edit first, so re-launching the loop is the ONLY thing a human does
-# (they never run `gtd step human` by hand). Peek with the pure `gtd next
-# --json` and step only at a `"message"` rest — at an agent/check rest
-# `gtd step human` would refuse out-of-turn, and a mid-cycle restart must just
-# resume driving. A clean gate is a no-op; a genuine refusal (malformed steering
-# file, unrecognized edit) stops the loop instead of being driven past.
-if [[ "$(gtd next --json | jq -r .kind)" == "message" ]]; then
-  gtd step human >/dev/null
-fi
-
-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)"    # bin/gtd renders this via emit_gate instead
-    gtd next
-    exit 0
-  fi
-
-  if [[ "$kind" == "script" ]]; then
-    head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
-    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)"   # bin/gtd renders this via emit_settled instead
-      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.
-
-The loop's logfile lives at `"$(worktree_git_dir)/gtd-loop.log"` by default, or
-`$GTD_LOOP_LOG` verbatim when set. `worktree_git_dir` derives the git dir from
-the cwd with `GIT_DIR`/`GIT_WORK_TREE` scrubbed, so an inherited `GIT_DIR`
-(leaked from a parent git process, a hook, or another worktree's shell) can
-never key the log — or the loop's memory marker — to a different worktree; two
-worktrees looping at once each keep their own log.
-
-## Rendered output and logging
-
-`bin/gtd` detects its output capability once at startup (`FANCY`, true when
-stdout is a real terminal AND `NO_COLOR` is unset): on a real terminal it prints
-one colored/emoji line per event, and under `NO_COLOR` or a piped/redirected
-stdout it prints the same events as plain ASCII with no escape codes, per the
-[NO_COLOR convention](https://no-color.org). Normal events (a state transition,
-a captured commit, an agent/check turn starting, settling at idle) render to
-stdout; refusals, stalls, and validate-cap halts render to stderr, each followed
-by a `📄 see <log>` pointer (plain: `see <log>`).
-
-The three previously terminal-visible subprocess streams — the agent turn's own
-output, the check script's own output, and `gtd step`'s own output — are no
-longer printed directly: they're appended to the per-repo/per-worktree log file
-(truncated once at the start of the run) instead — the loop prints the log's
-path as its first line, ready to `tail -f`.
-
-## Agent memory scope
-
-A `"prompt"` beat may carry an optional `memory` key — an opaque scope label the
-workflow author chose (e.g. `plan`, `build`, `fix`). gtd never interprets it; it
-signals to the driver whether this agent turn should continue from the previous
-turn's memory or start fresh. The rule is a comparison, not a command: track the
-`memory` of the last `"prompt"` beat (script/message beats have none and never
-change it), and when a new `"prompt"` beat's `memory` **equals** the tracked
-value, continue the same agent session; when it **differs** — or it is the first
-turn, or either side has no `memory` — start fresh.
-
-This is what makes a loop retain memory while a phase boundary clears it: a loop
-that keeps re-entering one state emits the same label every lap, so the agent
-accumulates context across the loop; the move to the next phase's
-differently-labelled state resets it. `bin/gtd` implements this by mapping the
-signal onto claude's session flags — `--session-id` to pin a fresh session when
-the scope changes, `--resume` to continue it while the scope holds — and
-persists the current scope + session id in the git dir (never the working tree,
-so `gtd status` and the pending diff never see them) so retention survives even
-across the restarts a human gate forces mid-loop. See `skills/loop/SKILL.md`'s
-"Agent memory scope" for the same contract stated for a hand-driven loop.
-
-## Using a different agent
-
-`gtd` (bare, or `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` in its environment, along
-with the resolved state's opaque `model` hint (if any) as `$GTD_LOOP_MODEL` and
-its `memory` scope as `$GTD_LOOP_MEMORY` / `$GTD_LOOP_SESSION_ID` /
-`$GTD_LOOP_MEMORY_RESUME` (`1` when this turn should continue the prior
-session). An adapter that ignores any of these keeps working unchanged. For
-example, to drive a different agent CLI:
-
-```bash
-GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd
-```

package/docs/upgrading.md

@@ -1,293 +0,0 @@
-# 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>): <from> → <to>`
-subject (or the bare `gtd(<actor>): <to>`) naming a state and an actor the
-active workflow currently declares; everything else — a v1 `gtd: grilling`, a v2
-`gtd(agent): building`, a plain `chore: …` commit, anything from a foreign repo
-— parses as unrecognized and lands at the workflow's initial state (`idle` in
-the unified template). There is no special-casing for "this looks like an old
-gtd commit": the mechanism is exactly the same one that already made v1 history
-inert to v2, and v2 history inert to a differently-configured workflow — v3 just
-applies it uniformly to all prior history instead of drawing a v1/v2 line.
-
-**Finish or squash any in-flight cycle first.** A repo mid-cycle on v1 or v2 has
-no v3-shaped commit backing its steering files; upgrading mid-cycle lands cold
-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
-  unified template's `testCommand`, overridable via the top-level `vars:` key or
-  a `GTD_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. Dropped in the
-  v3.0 rewrite, then RE-INTRODUCED as the explicit state property it was always
-  meant to become: a state declaring `reviewWindow: true` opens the window while
-  the machine rests there (base = the process start, or a state marked
-  `reviewBase: true`). The unified template enables it on `await-review`. Unlike
-  v2's hardwired gate, it is pure workflow DATA and the engine stays oblivious —
-  see [STATES.md §11](../STATES.md) and the `file:`/`mode:` neighbours in
-  [configuration.md](configuration.md).
-- **`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 unified template's own
-  checkbox-review verdict (`review-deciding`) is ordinary WORKFLOW data (an `on`
-  pattern), not an engine hook: `D REVIEW.md` = approve, `M REVIEW.md` = route
-  to the deterministic decider, in the unified template. Deterministic
-  format-checking of the steering files is likewise no longer a pair of
-  in-machine `check`/`script` states — the old `todo-validating`/
-  `review-validating` states and their `.gtd/FORMAT.md` steering file are gone,
-  replaced by the `gtd validate` command plus producing-agent self-validation
-  (see
-  [docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
-  and [STATES.md §12](../STATES.md)).
-- **`gtd review <target>`.** Gone in the initial v3 rewrite, 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). The current command
-  surface is `init` / `step` / `next` / `status` / `validate` / `review` /
-  `lsp`.
-
-- **`gtd mermaid` → `gtd visualize`.** The static Mermaid emitter has been
-  replaced by `gtd visualize`, which serves an interactive diagram of the active
-  workflow (main flow, sub-machines, per-state details) on a local web server —
-  see [CLI reference](cli.md#gtd-visualize---portn---no-open---json). Both are
-  read-only views of the active workflow; nothing in the machine changes.
-
-- **`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
-  four lines to `.gtdrc` restores (and improves on) the old auto-formatting for
-  the unified template:
-
-  ```yaml
-  modes:
-    qa:
-      format: "npx prettier --write <%= it.file %>"
-    review:
-      format: "npx prettier --write <%= it.file %>"
-  ```
-
-  Validation is unaffected — `qa`/`review` remain gtd's own built-in validators.
-  See
-  [docs/design/pluggable-steering-modes.md](design/pluggable-steering-modes.md)
-  and [Configuration](configuration.md#modes--pluggable-steering-file-modes).
-
-- **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:` (the file's format — the
-  built-in `qa`/`review`, or a workflow-declared `modes:` entry, though the LSP
-  itself only understands the two built-ins), 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 template'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** — gtd ships the bundled **unified** workflow as its
-built-in default, so after upgrading a repo works with **no** config and no init
-at all. The default forks on which steering file you create: `.gtd/TODO.md`
-starts the **simple flow** (a `planning` ⇄ `plan-review` plan-iteration loop,
-direct `building`, a `checking`/`fixing` loop), while `.gtd/REQUIREMENTS.md`
-starts the **advanced flow** (two-phase grilling ⇄ grilling-answer /
-architecting ⇄ architecting-answer / decompose / picking / per-package build
-with an agentic spec-review gate). Both converge on the same `reviewing` →
-`await-review` tail, and a full sign-off squashes the whole cycle into one
-commit (see [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
-
-`gtd init` is now optional and no longer writes a workflow — it seeds only a
-minimal `.gtdrc.json` (a `testCommand` var and a Prettier formatting
-suggestion). Run it if you want to tune those; otherwise nothing is required:
-
-```bash
-gtd init      # optional — seeds testCommand + a formatting suggestion
-```
-
-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.
-
-## Unreleased: bundled prompts no longer name `.gtd/`; a new `stateDir` var
-
-The bundled template's agent prompts used to open with a sentence naming `.gtd/`
-as the directory the agent must never touch except its own owned file. That
-framing broke down once a project repointed a steering-file var (e.g.
-`reviewFile`) outside `.gtd/`: the prompt still pointed the agent at a directory
-that no longer held the file it was writing. Every prompt's opener now states a
-path-agnostic principle instead — "this workflow steers itself through its own
-state files — treat them as its private scratchpad, never as project code or
-documentation" — and names only the specific file(s) its `vars:` entry owns.
-
-The check scripts also gained a new `vars.stateDir` (default `.gtd`) —
-independent of the per-file vars — naming only where they keep their own
-scratch/bookkeeping (the `.check-output` temp file, `review-deciding`'s
-exclusion of gtd's other state files). Each script now also creates its target
-file's own parent directory (`mkdir -p "$(dirname "$feedback")"`, etc.), so a
-per-file var repointed outside `stateDir` (or to a nested path with no existing
-parent) no longer fails to write.
-
-**Fully backward-compatible: no config change is needed.** Both `stateDir` and
-every per-file var keep their existing `.gtd/…` defaults, so an unconfigured
-repo renders byte-identical scripts and behavior to before. A repo that already
-relocated a steering-file var outside `.gtd/` (working around issue #128 for
-`reviewFile`) can keep its override as-is; nothing further to change.
-
-## The var-override env prefix is now `GTD_<UPPERCASE-name>`, not `GTD_VAR_<name>`
-
-The environment-variable layer of `it.vars` (see
-[Configuration's "Variables"](configuration.md#variables)) changed its naming
-scheme: the exact-case `GTD_VAR_<name>` prefix is gone, replaced by
-`GTD_<UPPERCASE-name>` matched case-insensitively against each name already
-declared by the workflow's own `vars:` or the top-level `.gtdrc` `vars:` key.
-`GTD_VAR_testCommand` becomes `GTD_TESTCOMMAND`; `GTD_VAR_plannerModel` becomes
-`GTD_PLANNERMODEL`.
-
-This is also a narrowing, not just a rename: because an uppercased env key can't
-round-trip back to an arbitrary camelCase name, the environment can no longer
-introduce a var no config layer declared — a `GTD_*` env var matching no
-declared name is now silently ignored, where it previously appeared verbatim
-under its post-prefix name.
-
-## 7.4: `gtd-loop` is gone — bare `gtd` and `gtd loop` run it directly
-
-`gtd-loop`, the standalone loop-driver binary installed alongside `gtd`, no
-longer exists. Its body now lives in `bin/gtd` itself, which is a bash entry
-script that dispatches on its first argument:
-
-| behavior                                               | before (≤ 7.3)                                 | from 7.4                                        |
-| ------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------- |
-| `gtd-loop`                                             | separate installed binary                      | removed                                         |
-| bare `gtd` (no subcommand)                             | usage error, prints help, exits 1              | runs the loop driver immediately                |
-| `gtd loop`                                             | not a recognized subcommand                    | runs the loop driver immediately                |
-| any other subcommand (`step`, `status`, `validate`, …) | handled by `node dist/gtd.bundle.mjs` directly | same, now reached via `bin/gtd`'s hand-off/exec |
-
-**Bare `gtd` is a behavior flip, not merely an addition** — the same kind of
-change as the v1 → v2 label grammar below: previously it printed the help text
-and exited 1 without touching the repository; from 7.4 it launches the loop
-driver immediately, identically to `gtd loop`. A script that relied on bare
-`gtd` failing fast (e.g. to detect a missing subcommand) now gets a running loop
-instead of an error.
-
-Because `bin/gtd` is a bash script for every invocation now, **running `gtd` at
-all — including any subcommand — requires bash**. Before 7.4, only the loop
-driver (`gtd-loop`) needed bash; a subcommand could be invoked directly via the
-bundle (e.g. `node node_modules/.bin/gtd`) with no bash in between. This is
-intentional and accepted, not an oversight: gtd's loop, its `script`-content
-checks, and a steering-file mode's own `format:`/`validate:` commands already
-run via `bash -c` (see
-[Configuration](configuration.md#modes--pluggable-steering-file-modes)) — gtd
-already assumes a unix/bash agent environment everywhere else, so the entry
-point catching up removes an inconsistency rather than introducing a new
-dependency.
-
-**Migration:**
-
-- Anyone invoking `gtd-loop` directly — in scripts, CI, or docs — should invoke
-  `gtd` or `gtd loop` instead.
-- Anyone relying on `node node_modules/.bin/gtd` resolving straight to the
-  bundle should note `gtd` is now a bash script that execs the bundle for
-  subcommands, so behavior for actual subcommands (`gtd step`, `gtd status`,
-  etc.) is unchanged — only the underlying file changed.
-
-## 7.2: the review checkout window is now per worktree
-
-The review checkout window's two refs moved from the SHARED `refs/gtd/*`
-namespace to git's PER-WORKTREE `refs/worktree/*` one:
-
-| before (≤ 7.1)         | from 7.2                        |
-| ---------------------- | ------------------------------- |
-| `refs/gtd/review-head` | `refs/worktree/gtd/review-head` |
-| `refs/gtd/review-base` | `refs/worktree/gtd/review-base` |
-
-Nothing in a `.gtdrc` or a workflow definition references those names, so **no
-config change is needed**. What changes is behaviour in a repository checked out
-as several linked worktrees (`git worktree add`, one `.git` shared between
-them): each worktree now has its own window, so a review resting in one no
-longer "closes" from another — which, on the shared refs, mixed-reset that other
-worktree's branch onto the reviewing worktree's saved head and left every
-sibling refusing with "a process is already underway".
-
-A window an OLDER gtd left open across the upgrade still closes from the legacy
-refs, so an in-flight review in a single-worktree repo needs no attention. In a
-multi-worktree repo gtd cannot tell which worktree a shared ref belongs to, so
-it closes only when HEAD is contained in the saved head and otherwise refuses
-with the exact recovery commands — run them in the worktree that owns the
-window:
-
-```bash
-git reset --mixed refs/gtd/review-head
-git update-ref -d refs/gtd/review-head
-git update-ref -d refs/gtd/review-base
-```
-
-7.2 also adds [`gtd abandon`](cli.md#gtd-abandon---json), the supported way out
-of a process that will never be finished (it closes the window, then rewinds
-HEAD to the process's start parent, keeping everything the process produced as
-uncommitted changes) — no hand-editing of refs required.
-
-## 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.