@pmelab/gtd 2.8.0 → 3.0.0

package/docs/design/scripted-actor.md

@@ -0,0 +1,289 @@
+# Exploration: every rest is a prompt — checks as a scripted actor
+
+> **Historical design record.** The actor-kind model this explores (v2's
+> gates/counters, actor kinds) was deleted by the v3 rewrite; superseded by
+> `docs/design/pattern-machine-plan.md` and [STATES.md](../../STATES.md).
+
+> Companion to `configurable-state-machine.md` (its Appendix C's δ-purity
+> program is now fully landed — see `delta-purity-plan.md`). This document
+> explores the next generalization: **executed commands become emitted
+> prompts**, run by the outer loop as shell scripts under a third actor kind,
+> with their results entering the machine the same way every other actor's work
+> does — as working-tree modifications captured on the next invocation.
+
+## 1. The idea
+
+Today the machine has exactly one place where it executes external code itself:
+the check (`runTest` / `runHealthCheck` in `src/Events.ts`, backed by the
+`TestRunner` service). Everything else an invocation does is git/fs bookkeeping.
+The check is also the only transition that branches on something other than a
+diff — an **exit code** — and the only reason `perform()` needs a subprocess
+executor, timeout semantics, and output capture inside the `gtd` process.
+
+The generalization: make the check an **actor**. A state that today fires
+`runTest` instead _rests_, awaiting a `check` actor. `gtd next` emits that
+state's prompt — which for a scripted actor is a **shell script** — and the
+outer loop executes it, exactly as it feeds an agent prompt to an LLM or shows a
+human prompt in a terminal. The script's effects land in the working tree
+(`.gtd/FEEDBACK.md` on a red run, nothing on green), and the next
+`gtd step check` captures them as the check's turn, with capture rules deciding
+the label from the pending diff — the same δ(label, diff) discipline every other
+actor already follows.
+
+The end state: **every rest is a prompt state** — for a human, an agent, or a
+shell. The machine performs only bookkeeping; every external effect (human
+thought, LLM inference, command execution) happens outside the loop and enters
+exclusively through the tree.
+
+```
+rest ──gtd next──▶ prompt for the awaited actor
+        human  → text in a terminal
+        agent  → LLM prompt
+        check  → shell script          ◀── the new kind
+actor acts (edits the tree, or doesn't)
+        ──gtd step <actor>──▶ capture rules label the turn from the diff
+        ──routing chains──▶ next rest
+```
+
+## 2. What executes where today (the residue)
+
+| Effect                    | Where it runs today                   | Enters the machine as               |
+| ------------------------- | ------------------------------------- | ----------------------------------- |
+| Human thought             | outside (terminal)                    | pending diff → captured turn        |
+| Agent inference           | outside (harness/LLM)                 | pending diff → captured turn        |
+| **Test / health command** | **inside `perform()` (`TestRunner`)** | **exit code → branch in `perform`** |
+| Git/fs bookkeeping        | inside `perform()`                    | commits (labels + trailers)         |
+
+The third row is the asymmetry this exploration removes. Note that Phase C
+already moved the _decision_ to write time (the red/green/cap outcome is encoded
+in the label the check writes) — but the _execution_ still lives inside the
+invocation, which is why `gtd step agent` can block for the length of a test
+suite, why `TestRunner` needs spawn-failure/timeout/empty-output handling
+in-process, and why the `@inmem` e2e tier still spawns real subprocesses for
+`testCommand`.
+
+## 3. The model
+
+### 3.1 A third actor kind: `scripted`
+
+`ActorDef.kind` gains a third value alongside `interactive` and `autonomous`:
+
+```ts
+actors: [
+  { name: "human", kind: "interactive" },
+  { name: "agent", kind: "autonomous" },
+  { name: "check", kind: "scripted" },
+]
+```
+
+The turn-taking engine keys on the kind, as it already does:
+
+- **interactive** — dirty boundary tree is the entry turn; empty turns are
+  meaningful signals.
+- **autonomous** — clean-tree steps at inert gates are no-ops; drafts are
+  structurally validated.
+- **scripted** — its prompt is executable; its turn is _mechanical_ (the driver
+  runs the script verbatim and steps — there is no judgement in between). Its
+  empty turn is typically the green signal (an opt-in `empty` rule, as
+  everywhere else).
+
+Nothing else in the engine changes: refusals, the fixpoint, and capture rules
+are actor-generic already (the actor generalization landed earlier).
+
+### 3.2 The prompt is the script — and gtd generates it
+
+The state's prompt template for a scripted actor renders a **wrapper script**,
+not the raw `testCommand`:
+
+```bash
+#!/usr/bin/env bash
+# gtd check turn — run verbatim, then: gtd step check
+set +e
+npm run test > .gtd/.check-output 2>&1
+code=$?
+if [ "$code" -ne 0 ]; then
+  mkdir -p .gtd
+  if [ -s .gtd/.check-output ]; then mv .gtd/.check-output .gtd/FEEDBACK.md
+  else echo "Test command \`npm run test\` failed with exit code $code and produced no output." > .gtd/FEEDBACK.md
+  fi
+else
+  rm -f .gtd/.check-output
+fi
+```
+
+gtd owns the wrapper's shape (output capture, the empty-failure sentinel, the
+target file), templated from config at emit time — the driver stays dumb. This
+keeps the machine the single author of check mechanics while moving the
+_execution_ out.
+
+### 3.3 Mechanics in the script, semantics at capture
+
+A crucial split, learned from the Phase C work: the script must encode only
+**mechanics** (did it exit non-zero; what was the output), never **semantics**
+(is the budget spent; is this an escalation). Semantics belong in the capture
+rules, decided from the pending diff plus the trailer vector at step time:
+
+```ts
+testing: {
+  kind: "prompt",
+  awaits: "check",
+  prompts: { check: "@run-test" },
+  captureRules: [
+    // red at the cap — same file, different label; the escalated label's
+    // routing chain renames FEEDBACK.md → ERRORS.md as bookkeeping
+    { when: (p) => p.feedbackPresent && p.counters.testFixCount >= p.fixAttemptCap,
+      label: "escalated", stamp: carry },
+    // red below the cap
+    { when: (p) => p.feedbackPresent, label: "test-failed", stamp: tPlus1 },
+    // green — the outcome labels already decided at write time today,
+    // now decided at capture of the check's empty turn
+    { empty: true, when: (p) => p.packagesPresent && !forceApprove(p), label: "agentic-review" },
+    { empty: true, when: (p) => p.packagesPresent, label: "close-package-approved" },
+    { empty: true, label: "tests-green", stamp: h0 },
+  ],
+}
+```
+
+Why this split matters: if the script encoded `capReached` (as `perform()` does
+today), a script emitted before the budget changed and executed after would
+write the wrong file — a stale-script race with two sources of truth. With
+semantics at capture, a stale script is harmless: the mechanics it performs
+(write FEEDBACK.md with the output) are timeless, and the label — the part that
+steers — is decided against the _current_ trailer when the turn is captured.
+This is the δ discipline applied once more: the diff carries facts, the capture
+encodes meaning.
+
+### 3.4 Wire format
+
+Check turns land as ordinary turn commits in the existing grammar:
+
+```
+gtd(agent): building          ← the build turn
+gtd: testing                  ← routing: rest, awaiting check   (label state today)
+gtd(check): test-failed       ← the check's captured turn (FEEDBACK.md in its diff)
+
+Gtd-Counters: t=1 r=0 h=0
+gtd(agent): fixing            ← the fixer's turn
+gtd: testing
+gtd(check): agentic-review    ← green, packages, threshold not reached
+
+Gtd-Counters: t=1 r=0 h=0
+```
+
+`git log --oneline` becomes a _complete_ trace: today the check outcome appears
+as a bare machine label; under this model it is attributed — you can see that
+the check actor ran, when, and what it concluded, exactly as for humans and
+agents. Old histories remain inert boundaries (closed-set rule), and the trailer
+scheme carries over unchanged.
+
+## 4. What each current piece becomes
+
+| Today                                             | Under the scripted actor                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `runTest` / `runHealthCheck` edge actions         | deleted — `testing`/`health-check` become prompt states awaiting `check`       |
+| `TestRunner` service (spawn, timeout, output)     | deleted from gtd; wrapper script + driver responsibility                       |
+| exit-code branch in `perform()`                   | capture rules on the check state (diff + trailer)                              |
+| `onGreen` decided at dispatch                     | green outcome decided at capture of the check's empty turn — same write moment |
+| `capReached` baked into the action                | capture-rule guard reading `p.counters` — no stale-script race                 |
+| empty-failure sentinel in TS                      | templated into the wrapper script                                              |
+| `gtd step agent` blocks for the test suite        | `gtd` returns instantly; the loop runs the script between invocations          |
+| `@inmem` e2e runs real `testCommand` subprocesses | scenarios write FEEDBACK.md by hand and `gtd step check` — fully in-memory     |
+| loop protocol: agent-only dispatch                | uniform: read `gtd next --json`, dispatch on the awaited actor's kind          |
+| `testCommand` consumed by `TestRunner`            | consumed by the prompt template (config → script text)                         |
+
+And the generalization dividend: **any state can declare a scripted gate.** A
+lint pass before review, a deploy verification after close-package, a schema
+check between grilling and architecting — all become one `StateDef` with
+`awaits: "check"` (or a second scripted actor with its own command), zero new
+engine code. This is the missing piece of the original "completely configurable
+state machine" goal: mechanical gates were the one transition type a user
+couldn't add through configuration.
+
+## 5. What this buys
+
+1. **The machine's last impurity is gone.** `perform()` becomes pure git/fs
+   bookkeeping; the Effect graph loses `TestRunner` and `CommandExecutor`; the
+   always-clean invariant becomes structural (nothing inside gtd can block or
+   die mid-run with a half-written tree).
+2. **`gtd` becomes instant and deterministic.** Every invocation is a pure
+   resolve + bookkeeping hop. All nondeterminism (LLM, human, subprocess) is
+   outside — which is also exactly what makes the property-test story and the
+   `@inmem` tier stronger.
+3. **One protocol.** The outer loop stops special-casing: every iteration is
+   "ask `gtd next` who's up and what the prompt is; produce that actor's turn;
+   `gtd step <actor>`". Timeouts, retries, and sandboxing of the test command
+   move to the driver, which already owns them for the agent.
+4. **Attributed history.** Check outcomes are turns with an author, a diff, and
+   a trailer — `git log` reads as a complete conversation between three actors.
+5. **Configurable mechanical gates** (see §4) — without touching gtd.
+
+## 6. Where it falls down
+
+1. **It breaks the CLI contract — this is NOT behavior-preserving.** Every
+   driver and all ~40 feature files change shape: `gtd step agent` no longer
+   runs the tests; a check that used to be one invocation is now three
+   (`step agent` → run script → `step check`). Unlike the δ refactor, there is
+   no way to hide this behind the same e2e suite. It is a major version with a
+   migration story, not an internal refactor.
+2. **Human ergonomics regress without a driver.** Today a human at `escalate`
+   runs `gtd step human` and the re-test happens. Under this model they must
+   copy-paste a script and run a second command. Mitigation: a thin optional
+   convenience — `gtd run` (or the loop skill) that executes the _emitted_ check
+   script verbatim and immediately steps the check actor. The machine still
+   never executes; the convenience wrapper does, behind an explicit opt-in
+   command whose only input is gtd's own emitted script. This preserves the
+   purity boundary while keeping the two-keystroke UX.
+3. **The idle carve-out gets awkward.** Idle today awaits the human, and a human
+   step re-runs the health check inline. If idle awaits `check` instead, a bare
+   `gtd step human` at idle would be refused — hostile. Options: keep the idle
+   carve-out (a human step at idle _is_ the check turn's trigger via the
+   convenience wrapper), or split idle (rest for human) from a health-check
+   state (rest for check) that the human's empty idle turn chains into. Needs a
+   decision; neither is free.
+4. **Generated bash is a liability.** Quoting the configured command, platform
+   variance (POSIX sh vs bash vs Windows), output-size limits — all move from
+   unit-tested TypeScript into templated script text that can only be tested by
+   executing it. The wrapper must stay tiny and boring; anything clever belongs
+   in capture rules.
+5. **The prompt channel now carries executable code.** `testCommand` is already
+   arbitrary code execution by config, so the _trust_ is unchanged — but the
+   _transport_ changes: drivers must execute only the script emitted by
+   `gtd next` for a scripted actor, never script-looking content from
+   agent-authored files. The `--json` output should carry the actor kind and the
+   script in a dedicated field so drivers never have to parse prose.
+6. **Two extra hops per check.** Negligible for an agent loop (the test run
+   dwarfs them), noticeable for scripted gates used as fast validations. The
+   fixpoint chaining could allow `step check` to be invoked by the driver
+   immediately after the script with no intervening `next`, keeping it to one
+   extra invocation.
+7. **A non-cooperating driver can stall the machine.** Today a check cannot be
+   skipped: `step agent` runs it, period. Under this model a driver could keep
+   stepping other actors... except it can't — the rest awaits `check`, and every
+   other actor is refused out-of-turn. The stall is real (nothing runs the
+   script), but the safety property (nothing _bypasses_ the gate) is exactly as
+   strong as today's, enforced by the same refusal mechanism.
+
+## 7. Verdict
+
+This is the natural completion of the δ program: after Phase C, the check's
+_decision_ already lives at write time and its _budget_ already rides on
+trailers — the only thing still inside the machine is the subprocess itself.
+Moving it out makes every rest a prompt and every actor a peer, at the cost of a
+breaking CLI/protocol change and a real (but boundable) bash-templating
+liability.
+
+If pursued, the phasing writes itself:
+
+- **Phase 1 — dual-mode:** add the `scripted` kind, the check states' capture
+  rules, and `gtd step check`; keep `runTest` as a deprecated inline path so the
+  existing e2e suite stays green while a parallel suite drives the new protocol.
+- **Phase 2 — flip the default:** loop skill dispatches on actor kind; `gtd run`
+  convenience lands; feature files migrate scenario by scenario (each check hop
+  becomes script-run + step).
+- **Phase 3 — delete:** `TestRunner`, `runTest`/`runHealthCheck`, and the
+  idle/testing carve-outs (per the idle decision taken in Phase 1).
+
+The one decision worth taking _before_ any of this: §3.3's mechanics/semantics
+split. Even today's inline check could be restructured so the label is decided
+purely from (written file, trailer) — that is the piece that makes the model
+safe, and it is adoptable independently of everything else here.

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

@@ -0,0 +1,112 @@
+# Design: state ↔ steering-file association (`file:` + `mode:`)
+
+> Status: LANDED (2026-07-22). Goal: retain the v2 relationship between states
+> and steering files — but as pure workflow CONFIGURATION that works for any
+> state machine. Each state may declare one associated `file:` (an Eta template,
+> so filenames live in `vars:` and are never repeated) and a `mode:` (`qa` |
+> `review`) naming the file's FORMAT. The LSP stops hardcoding basenames: it
+> reads the gtd config from the workspace (cwd/parent lookup, same cosmiconfig
+> search the CLI uses), maps rendered file paths to modes, and regains the
+> jump-to-relevant- file command — full v2 functionality, zero hardcoded
+> workflow knowledge.
+
+## 1. The two new state properties
+
+| Property | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `file:`  | Optional. THE steering file this state is about — the file a human/editor should look at while the machine rests here. An **Eta template** rendered with the standard `TemplateContext` (in practice `<%= it.vars.… %>`; the full context is available). Forbidden on commit states (never at rest), must render non-empty.                                                                                                                                                 |
+| `mode:`  | Optional, requires `file:`. The file's FORMAT, from a closed, documented vocabulary: `qa` (the open-questions format — `## Open Questions`, `###` question, `Suggested default:`/`Answer:`) or `review` (the checkbox review format — `# Review:` header, `##` chunks, `- [ ]` pointers). Unknown values are a load error (typos must not silently disable editor support). The ENGINE never branches on it — like `model`, it is emitted data; only the LSP interprets it. |
+
+Multiple states may (and in the default, do) share one file+mode — the mode
+describes the file, the association is per state.
+
+**Emission:** `gtd next --json` and `gtd status --json` gain optional `file`
+(rendered) and `mode` fields, omitted when unset (exactly like `model`); plain
+`gtd status` prints `File:`/`Mode:` lines when set. This gives drivers and
+editors the jump target without speaking LSP, and gives e2e an assertion
+surface.
+
+**Engine/compiler touch points:** `StateDef` gains `file?`/`mode?`;
+`validateDefinition` gains the rules above (non-empty strings, mode ∈ {qa,
+review}, mode requires file, both forbidden on commit states, errors
+aggregated); `PatternConfig` compiles the two keys (KNOWN_STATE_KEYS, string
+checks); `Edge`/`program` render `file:` at rest exactly where `model` is
+rendered (a render failure errors like a model render failure).
+
+## 2. The bundled default gets the association
+
+New `vars:` entries (single source for the filenames):
+
+```yaml
+vars:
+  testCommand: npm test
+  todoFile: .gtd/TODO.md
+  reviewFile: .gtd/REVIEW.md
+  feedbackFile: .gtd/FEEDBACK.md
+```
+
+Per-state mapping (12 states):
+
+| States                                                              | `file:`                       | `mode:`                   |
+| ------------------------------------------------------------------- | ----------------------------- | ------------------------- |
+| `grilling`, `todo-validating`, `grilling-answer`, `building`        | `<%= it.vars.todoFile %>`     | `qa`                      |
+| `reviewing`, `review-validating`, `await-review`, `review-deciding` | `<%= it.vars.reviewFile %>`   | `review`                  |
+| `fixing`, `escalate`                                                | `<%= it.vars.feedbackFile %>` | — (plain text, no format) |
+| `idle`, `checking`                                                  | —                             | —                         |
+
+Prompts and scripts that already name these files switch to the vars
+(`<%~ it.vars.todoFile %>` etc.) so each filename has ONE source of truth in
+templates. **Known limitation, documented:** `on` pattern keys are NOT Eta
+templates — the default's patterns keep literal `.gtd/…` paths, so repointing a
+filename var (`.gtdrc`/`GTD_VAR_`) without also overriding the workflow's
+patterns desyncs the machine. The vars are a DRY mechanism inside templates and
+the state↔file association, not a rename switch. (Making pattern keys var-aware
+at compile time is noted as possible future work.)
+
+The advanced example (`docs/examples/advanced-workflow.md`) gains the same
+`file:`/`mode:` annotations (it is the LSP-heavy flow), including
+`architectureFile` for its architecting phases (also `qa`-format).
+
+## 3. The LSP becomes config-driven
+
+- **Config discovery:** the server locates the gtd config by the SAME
+  cosmiconfig search the CLI uses, from the workspace root (initialize
+  `workspaceFolders`/`rootUri`), falling back to the open document's directory
+  walking upward. Reuse `ConfigService`'s loading/compiling — no second config
+  code path. Config is (re)loaded lazily per request (it is small); no watcher
+  needed for v1.
+- **Path→mode dispatch:** compile the definition, render every state's `file:`
+  (vars-layer context; the LSP process's env supplies `GTD_VAR_` overrides like
+  any invocation), and build a map of absolute rendered paths → mode. Document
+  features dispatch on that map: `qa` files get question symbols + parser-error
+  diagnostics; `review` files get chunk/hunk symbols + check/uncheck code
+  actions + diagnostics. Conflicting modes for one path: first declaring state
+  wins, log a warning. **Fallback:** when NO config resolves (or a `.gtd` file
+  isn't mapped), keep today's basename dispatch (`TODO.md` → qa, `REVIEW.md` →
+  review) so the server still works standalone.
+- **The jump command returns:** `gtd.openSteeringFile` — resolve the CURRENT
+  state exactly like the CLI (config + git HEAD via the existing Edge helpers;
+  this re-adds the git/config wiring the v2 server had), render its `file:`, and
+  `ShowDocumentRequest` it; a state with no `file:` yields an informational
+  message naming the state (v2 behavior). Registered as an executeCommand;
+  documented for editor keybinding.
+
+## 4. Change chart
+
+| Area                             | Change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/PatternMachine.ts`          | `StateDef.file?/mode?` + validation rules (closed mode set).                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `src/PatternConfig.ts`           | Compile `file`/`mode` keys.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `src/Edge.ts` / `src/program.ts` | Render `file:` at rest; `file`/`mode` in both `--json` payloads + plain `status` lines.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `src/Lsp.ts`                     | Config discovery, path→mode dispatch (with basename fallback), `gtd.openSteeringFile`.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `src/workflows/default.yaml`     | §2's vars + per-state `file:`/`mode:`; templates switch to filename vars.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Docs                             | STATES.md property table + §10; configuration.md (`file:`/`mode:` section + mode vocabulary + the pattern-literal limitation); cli.md JSON contracts; examples/advanced-workflow.md annotations; upgrading note (jump command is back, config-driven).                                                                                                                                                                                                                                     |
+| Tests                            | Unit: validation (mode vocabulary, mode-requires-file, commit-state prohibition, aggregation), compile, `file:` render + failure path; LSP path→mode dispatch, fallback, openSteeringFile (pure helpers). E2e: `driver-json-status.feature` file/mode emission (present + omitted); `lsp.feature` @live — documentSymbol served for a CUSTOM-named qa file mapped via a real `.gtdrc` (proving config-driven dispatch), and the jump command returning the rendered path at a known state. |
+| Live verification                | Scratch repo with a custom workflow whose `file:` uses a var: `gtd status` shows the rendered `File:`/`Mode:`; LSP smoke against the custom filename; default workflow spot-check (`grilling` → `File: .gtd/TODO.md`, `Mode: qa`).                                                                                                                                                                                                                                                         |
+
+## 5. Out of scope
+
+- Eta-rendering of `on` pattern keys (the rename-switch story) — future work,
+  noted in §2.
+- New LSP modes beyond `qa`/`review` — the vocabulary can grow with new formats;
+  adding one means: parser (spec), validator recipe, LSP dispatch arm, docs.

package/docs/design/steering-file-loops.md

@@ -0,0 +1,164 @@
+# Plan: steering-file validation loops in the default workflow
+
+> Status: §2–§4 (the two validation loops in the default workflow) AND §5 (the
+> LSP resurrection) both LANDED 2026-07-22. Goal: the bundled default workflow
+> completely maps the functionality the deleted v2 LSP server (`src/Lsp.ts`,
+> removed in the v3 rewrite) provided over the two steering files: the
+> **open-questions format** in `.gtd/TODO.md` and the **checkbox review format**
+> in `.gtd/REVIEW.md` — including a deterministic validation loop for each.
+> Everything is pure workflow configuration; the engine is untouched.
+
+## 1. The formats (authoritative spec = the deleted parsers)
+
+Extract the exact rules from git history —
+`git show 60c7490^:src/OpenQuestions.ts` and
+`git show 60c7490^:src/ReviewDoc.ts` — and embed them BOTH in the agent prompts
+(so drafts are born valid) and in the validator scripts (so malformed drafts
+bounce):
+
+**`.gtd/TODO.md` open questions** (`OpenQuestions.ts`):
+
+- Free-form prose, plus an OPTIONAL `## Open Questions` section (absent = zero
+  questions, valid).
+- Every `###` sub-heading directly under that section is one question; its
+  body's FIRST non-blank line must be `Suggested default: <text>` (agent's
+  unanswered default) or `Answer: <text>` (human's answer / folded-in) —
+  anything else is a format error.
+- The section ends at the next level-1/2 heading or EOF.
+
+**`.gtd/REVIEW.md`** (`ReviewDoc.ts`):
+
+- First non-blank line: `# Review: <short-hash>`.
+- A `<!-- base: <hash> -->` comment somewhere in the document.
+- At least one `## <Chunk Title>` (non-empty title), each with at least one file
+  pointer matching `- [ ] ./path/to/file.ts#42 — note` / `- [x] …` (checkbox,
+  `./`-relative path, optional `#line`, optional `—`/`-` note) — the deleted
+  `FILE_POINTER_RE` is the shape to port.
+
+## 2. The new default workflow (12 states)
+
+Current 7 states, plus the two loops. `smart` on `grilling` and `reviewing`.
+
+| State               | Actor | Content | `on` (declaration order matters)                                                                                                                 |
+| ------------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `idle` (initial)    | human | message | `* **` → `grilling`                                                                                                                              |
+| `grilling`          | agent | prompt  | `* **` → `todo-validating`                                                                                                                       |
+| `todo-validating`   | check | script  | `A/M .gtd/FORMAT.md` → `grilling`; `D .gtd/FORMAT.md` → `grilling-answer`; `C` → `grilling-answer`                                               |
+| `grilling-answer`   | human | message | `C` → `building`; `* **` → `grilling`                                                                                                            |
+| `building`          | agent | prompt  | `* **` → `checking`                                                                                                                              |
+| `checking`          | check | script  | `A/M .gtd/FEEDBACK.md` → `fixing`; `D .gtd/FEEDBACK.md` → `reviewing`; `C` → `reviewing`                                                         |
+| `fixing` (retry 3)  | agent | prompt  | `* **` → `checking`                                                                                                                              |
+| `escalate`          | human | message | `* **` → `checking`                                                                                                                              |
+| `reviewing`         | agent | prompt  | `* **` → `review-validating`                                                                                                                     |
+| `review-validating` | check | script  | `A/M .gtd/FORMAT.md` → `reviewing`; `D .gtd/FORMAT.md` → `await-review`; `C` → `await-review`                                                    |
+| `await-review`      | human | message | `D .gtd/REVIEW.md` → `idle`; `M .gtd/REVIEW.md` → `review-deciding`; `* **` → `grilling`; (no `C` row — a clean step is a no-op, still awaiting) |
+| `review-deciding`   | check | script  | `A/M .gtd/TODO.md` → `grilling`; `D .gtd/REVIEW.md` → `idle`; `C` → `await-review` (defensive)                                                   |
+
+**Loop 1 — TODO.md questions (maps the LSP's question symbols/format):**
+
+- `grilling` develops `.gtd/TODO.md` with the exact Open Questions format; if
+  `.gtd/FORMAT.md` exists, its prompt says to fix those findings first.
+- `todo-validating` (deterministic script): parse-check TODO.md against §1's
+  rules. Malformed → write findings to `.gtd/FORMAT.md` (one line each) → back
+  to `grilling`. Valid → `rm -f .gtd/FORMAT.md` → `grilling-answer`.
+- `grilling-answer` (human): answer by replacing `Suggested default:` with
+  `Answer:` in place; accept all remaining defaults with a clean step (`C` →
+  `building`); any edit loops back to `grilling` (the agent folds answers in,
+  possibly asks follow-ups, and re-validates).
+
+**Loop 2 — REVIEW.md checkboxes (maps the LSP's review chunks/check actions):**
+
+- Green `checking` now goes to `reviewing` (not straight to `await-review`).
+- `reviewing` (agent, `model: smart`) writes `.gtd/REVIEW.md` in §1's exact
+  format — header hash from `<%= it.currentCommit %>` (short slice), base
+  comment from `<%= it.startCommit %>`, chunks grouped semantically over the
+  embedded `it.processDiff` (reuse the advanced example's reviewing prompt as
+  the base, tightened to the format spec).
+- `review-validating` (deterministic script): structure check (header, base
+  comment, ≥1 chunk, every pointer matches the shape). Malformed →
+  `.gtd/FORMAT.md` → `reviewing`; valid → `await-review`.
+- `await-review` (human): tick a pointer's checkbox to approve that item; when
+  EVERY box is ticked the cycle is approved. Add notes / untick / edit code for
+  feedback. Deleting `.gtd/REVIEW.md` outright is the power-user approve
+  shortcut. Any `M .gtd/REVIEW.md` step routes to the decider (declared before
+  `* **`, so a step that also touches code still goes to the decider); code-only
+  edits are feedback straight to `grilling`.
+- `review-deciding` (deterministic script): if NO unticked `- [ ]` pointer
+  remains → approve: `rm .gtd/REVIEW.md` (→ `idle`). Otherwise → extract the
+  unticked pointers and their notes into a fresh `.gtd/TODO.md` (the next lap's
+  input) AND `rm .gtd/REVIEW.md` — the diff then contains both `A .gtd/TODO.md`
+  and `D .gtd/REVIEW.md`, and the `A/M .gtd/TODO.md` row is declared FIRST so
+  feedback wins (first-match declaration order is load-bearing here; pin it with
+  a test).
+
+**Hygiene invariant (assert in e2e):** an approved cycle leaves `.gtd/` empty —
+FEEDBACK.md is cleaned by green `checking`, FORMAT.md by a valid validation run,
+REVIEW.md by the approval, TODO.md by `building`.
+
+## 3. What the validators look like
+
+Same discipline as `checking`/the old `picking`: mechanics-only bash, verdict =
+file op, semantics = the `on` map. Grep/awk ports of the parser rules
+(pragmatic, not a full markdown parser): e.g. a question block whose first
+non-blank body line matches neither `^Answer:` nor `^Suggested default:` is a
+finding; a pointer line failing the `- [(x| )] ./path(#N)?( — note)?` shape is a
+finding; `- [ ]` presence is the review-deciding branch condition. Findings go
+into `.gtd/FORMAT.md` verbatim (file + line + rule), so the fixing agent gets
+actionable input.
+
+## 4. Change chart
+
+| Area                                                  | Change                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/workflows/default.yaml`                          | +5 states (`todo-validating`, `grilling-answer`, `reviewing`, `review-validating`, `review-deciding`); `checking`'s green rows retarget `reviewing`; `await-review` rewritten (checkbox semantics, decider routing); prompts gain the format specs; header comment updated.                                                                                |
+| Engine / TypeScript                                   | **No changes.** Everything is workflow data.                                                                                                                                                                                                                                                                                                               |
+| `STATES.md` §10                                       | New table + walkthrough (both loops, the declaration-order subtleties, the hygiene invariant).                                                                                                                                                                                                                                                             |
+| `tests/integration/features/default-workflow.feature` | Rewritten: malformed-TODO lap (simulate `todo-validating` by writing `.gtd/FORMAT.md` + `gtd step check` — @inmem never executes scripts), valid draft → answer lap → accept; malformed-REVIEW lap; tick-all approve → `idle` with empty `.gtd/`; partial-tick feedback → TODO.md extraction → `grilling`; delete-shortcut approve; retry/escalation kept. |
+| `smoke.feature`                                       | Hop updates (`grilling` now routes to `todo-validating`).                                                                                                                                                                                                                                                                                                  |
+| Docs                                                  | `configuration.md` / `README.md` walkthrough mentions; `docs/examples/advanced-workflow.md` intro gains one line noting the default now carries the validation loops (the example itself is NOT reworked in this change — noted as a possible follow-up to rebase it on the new default).                                                                  |
+| Live verification                                     | Real-script drive (`gtd run` at each validator) covering: agent writes malformed TODO → FORMAT.md → fixed lap; answers folded; malformed REVIEW lap; tick-all approve; partial-tick feedback extracting TODO.md; final tree `.gtd`-free at idle.                                                                                                           |
+
+## 5. The LSP server comes back (v3-shaped)
+
+The v2 LSP (`src/Lsp.ts`, deleted at the v3 rewrite) is resurrected, scoped to
+what is workflow-agnostic — the FILE FORMATS, not any particular state machine:
+
+- **Restore the pure parsers verbatim from history** —
+  `git show 60c7490^:src/OpenQuestions.ts` / `:src/ReviewDoc.ts` (+ their unit
+  tests) — they are pure (no git/fs/Effect) and restore cleanly. They are the
+  executable spec of §1; the bash validators in §3 implement the SAME rules
+  (note this dual-implementation contract in both places — the parsers' unit
+  tests are the format's spec tests).
+- **New `src/Lsp.ts`** (recover from history, then STRIP the v2-model
+  dependencies — Events/Machine/ReviewWindow/STATE_FILE are gone): keyed on FILE
+  NAME, not state. For `.gtd/TODO.md`: document symbols for open questions
+  ([suggested]/[answered]). For `.gtd/REVIEW.md`: chunk/hunk symbols and the
+  check/uncheck code actions (hunk and whole-chunk). BOTH files: publish the
+  parsers' `errors` as diagnostics — the same findings the workflow's
+  `.gtd/FORMAT.md` validators produce, live in the editor. The v2
+  `gtd.openSteeringFile` command and its hardcoded state→file map are NOT
+  restored (a v3 workflow is arbitrary data; a state names no file) — noted as a
+  possible future addition driven by workflow config.
+- **CLI**: re-add the `gtd lsp` subcommand (stdio transport, as before) to
+  `program.ts` dispatch + help + `docs/cli.md`; re-add the
+  `vscode-languageserver` / `vscode-languageserver-textdocument` dependencies;
+  confirm the tsdown single-file bundle still builds and the subcommand starts
+  from `dist/gtd.bundle.mjs`.
+- **Tests**: parser unit tests restored; the LSP's pure helpers
+  (symbol/edit/diagnostic builders) unit-tested as in v2 (recover `Lsp.test.ts`
+  from history and adapt); restore/adapt the old protocol-level e2e
+  (`lsp.steps.ts` + feature) if it adapts cleanly, otherwise a minimal @live
+  smoke that `gtd lsp` starts and answers `initialize`.
+- **Housekeeping**: add the restored pure modules to `stryker.config.json`'s
+  mutate list; `docs/development.md` + `docs/upgrading.md` notes (the LSP is
+  back, file-format-keyed); README one-liner on editor integration.
+
+## 6. Explicitly out of scope
+
+- `ARCHITECTURE.md` (the old second question phase) — the default keeps a single
+  grilling step; the advanced example still shows the two-phase shape.
+- Engine-level validation of steering files — validation stays a workflow
+  concern, per the v3 charter; the LSP is editor tooling over the same formats,
+  not an engine hook.
+- The `gtd.openSteeringFile` command (needs a state→file mapping that v3
+  workflows don't declare — future work, possibly a per-state `file:` hint).