@pmelab/gtd 2.8.0 → 3.1.0

package/docs/design/delta-purity-plan.md

@@ -0,0 +1,283 @@
+# Implementation plan: full δ(label, diff)
+
+> **Historical design record.** The counters/labels machinery this plan built on
+> (turn labels, capture rules, `Gtd-Counters` trailers) was deleted by the v3
+> rewrite; superseded by `docs/design/pattern-machine-plan.md` and
+> [STATES.md](../../STATES.md).
+
+> **Status (updated during implementation):**
+>
+> - **Phase 0+A — LANDED.** Phase 0's table review surfaced a major
+>   simplification the plan's draft table over-engineered: the actor is already
+>   part of every turn label (`gtd(human): X` ≠ `gtd(agent): X`), so only labels
+>   whose OWN diff disambiguated their meaning needed splitting — six new labels
+>   (`grilling-accepted`, `architecting-accepted`, `review-approved`,
+>   `review-feedback`, `agentic-approved`, `agentic-findings`) instead of the
+>   drafted ~30-state redraw. Turn capture is rule-driven (`captureRules` per
+>   state), inert-by-default with opt-in `empty` rules, the fixpoint is a label
+>   fact, `headTurnIsEmpty` / `headTurnReviewSubstantive` are deleted, and the
+>   FEEDBACK.md interrupt dissolved into the verdict labels (a fallback rung
+>   keeps rider/crash recovery).
+> - **Phase B — LANDED.** Template probes are pending-diff matchers
+>   (`squashMsgDirty` / `learningMsgDirty`); content inspection is down to
+>   FEEDBACK.md emptiness and REVIEW.md checkbox-only, both consumed at capture.
+>   The effects-as-diffs invariant holds structurally (every `perform()` arm
+>   ends in a commit or a stop).
+> - **Phase C1 — LANDED.** `gtd: escalated`: a red check at the cap writes
+>   ERRORS.md and labels the escalation at write time (runTest AND
+>   runHealthCheck). `gtd: test-failed`/`gtd: health-check` classify
+>   unconditionally, the ERRORS interrupt dissolved (fallback recovery rung
+>   kept), `ClassifyFlags.errorsPresent` and the at-cap health carve-out are
+>   deleted.
+> - **Phase C2 — LANDED.** `runTest.onGreen` decided at dispatch: packages +
+>   threshold → INLINE close (one `gtd: close-package` commit, no marker);
+>   packages → new machine label `gtd: agentic-review` (rest for the verdict);
+>   no packages → `gtd: tests-green`, now health-path-only with a settle-only
+>   routing rule. The step-agent checkpoint guard keys on the agentic-review
+>   label; the recovery-ladder `runTest` gets the same fill.
+> - **Phase C3 — LANDED.** Counter trailers: every machine-written commit (turns
+>   AND labels) carries its vector as a `Gtd-Counters: t=n r=n h=n` body
+>   trailer, computed by the writer — label stamps live in `labelCounterStamps`
+>   (`test-failed` t+1, `health-check` h+1, `building`/`close-package` t=r=0,
+>   `tests-green` h=0), turn stamps in `CaptureRule.stamp` (verdict turns r+1,
+>   the escalate turn's ERRORS-deletion t=h=0). The machine attaches vectors at
+>   dispatch (`attachCounters` + `fillInActionBudgets`); write-time-decided
+>   labels (runTest/runHealthCheck outcomes, the inline close) get the previous
+>   vector and the edge applies the chosen label's stamp. `gatherEvents` reads
+>   ONE trailer (nearest workflow commit) into `payload.counters`;
+>   `foldCounters` and all `CommitEvent` counter flags are deleted; squash
+>   commits carry no trailer. Zero vector is the no-trailer default (the upgrade
+>   rule). E2e grew `Given a commit "…" with counters "t=… r=… h=…"` and the
+>   cap/threshold scenarios spell their vectors explicitly; two scenarios pin
+>   the trailer wire format on machine-written commits.
+> - **Phase D — LANDED.** (1) The δ conformance property test
+>   (`src/Machine.property.test.ts`): with the history fold gone, `resolve` /
+>   `predictTurn` output is a function of the nearest workflow commit plus the
+>   RESOLVE payload — the test replaces older history, injects boundary commits
+>   before and after the nearest workflow commit, and asserts identical output
+>   (including thrown corruption errors). (2) Hardening as
+>   definition-consistency unit tests (`src/Workflow.test.ts`): declared-actor
+>   references in states, prompts, capture rules, turn/routing/ladder outcomes;
+>   stamp non-negativity. (No new compiler machinery — the contract types
+>   already make gates/phases/outcome sets closed at compile time.) (3) Docs:
+>   STATES.md §1 states the δ contract, §2 rewritten as the current transition
+>   tables (branch labels, write-time check outcomes, `gtd: escalated` /
+>   `gtd: agentic-review` rows, the `Gtd-Counters` trailer, the v1
+>   `grilling`/`building` collision note); AGENTS.md and the upgrading doc
+>   describe the trailer scheme and its zero-vector upgrade rule.
+
+> Companion to `configurable-state-machine.md` Appendix C. Decisions taken:
+> **full purity** (all five moves, including counters and config at write time),
+> **keep the corruption refusal** (steering files + no label → hard error),
+> **split states are the public vocabulary** (labels, `gtd status`, `--json`,
+> docs), **phased rollout** with every phase landing green.
+>
+> Target invariant, stated once: at every resolution,
+> `next = δ(nearest label (incl. its trailers), pending diff)` — the invoker
+> authenticates but adds no information; counters, config outcomes, and branch
+> decisions are baked into labels at write time; the external world enters only
+> through diffs; exactly two sanctioned impurities remain (the boundary-skip
+> walk and the corruption refusal).
+
+## 1. The target machine (draft label/state table)
+
+States have exactly ONE awaited actor (rest) or ONE machine act —
+`awaits: "dynamic"` is abolished. Labels are the transitions; `stateOf(label)`
+is a total map. Names are draft — Phase 0 finalizes them.
+
+### Entry (from `start` = no labeled commit reachable)
+
+| From state | Diff matcher (invoker: human) | Label written                    | Enters state         |
+| ---------- | ----------------------------- | -------------------------------- | -------------------- |
+| start      | adds `.gtd/HEALTH.md`         | `gtd(human): health-entry`       | health-briefed       |
+| start      | adds `.gtd/PLAN.md`           | `gtd(human): plan-entry`         | seed-from-plan (act) |
+| start      | adds `.gtd/ARCHITECTURE.md`   | `gtd(human): architecting-entry` | architecting-draft   |
+| start      | anything else (dirty)         | `gtd(human): grilling-entry`     | grilling-draft       |
+
+`start` with steering files present but NO reachable label → **corruption
+refusal** (the one retained guess-refusal; supersedes today's illegal-
+combination table for the no-label case).
+
+### Grilling / architecting (the dynamic-gate split)
+
+| From state (awaits)     | Diff matcher                | Label                           | Enters               |
+| ----------------------- | --------------------------- | ------------------------------- | -------------------- |
+| grilling-draft (agent)  | touches TODO.md (validated) | `gtd(agent): grilling-draft`    | grilling-answer      |
+| grilling-answer (human) | non-empty                   | `gtd(human): grilling-answered` | grilling-draft       |
+| grilling-answer (human) | **empty**                   | `gtd(human): grilling-accepted` | seed-from-todo (act) |
+| seed-from-todo (act)    | writes ARCH, deletes TODO   | `gtd: architecting`             | architecting-draft   |
+
+Architecting mirrors it (`architecting-draft/-answered/-accepted`, accepted →
+`gtd: grilled` → decompose). The empty-turn _meaning_ is now a declared
+diff-matcher rule (`empty`), not a classification of HEAD's past diff —
+`headTurnIsEmpty` and `headTurnReviewSubstantive` are deleted from
+`ResolvePayload`.
+
+### Build / test / fix loop (counters ride labels — see §2)
+
+| From state         | Trigger                        | Label                           | Enters             |
+| ------------------ | ------------------------------ | ------------------------------- | ------------------ |
+| decompose (agent)  | adds package dirs              | `gtd(agent): decomposed`        | consume-arch (act) |
+| consume-arch (act) | removes ARCH                   | `gtd: building`                 | building           |
+| building (agent)   | code diff                      | `gtd(agent): building`          | testing (act)      |
+| testing (act)      | red below cap, writes FEEDBACK | `gtd: test-failed` + trailers   | fixing             |
+| testing (act)      | red at cap, writes ERRORS      | `gtd: escalated`                | escalate           |
+| testing (act)      | green, pkgs, threshold reached | `gtd: close-package`            | close-pkg (act)    |
+| testing (act)      | green, pkgs                    | `gtd: agentic-review`           | agentic-review     |
+| testing (act)      | green, no pkgs (health rerun)  | settle label (§ settle)         | —                  |
+| fixing (agent)     | any diff                       | `gtd(agent): fixing` + trailers | testing (act)      |
+| escalate (human)   | deletes ERRORS.md              | `gtd(human): escalate-resumed`  | testing (act)      |
+
+`gtd: tests-green` and `gtd: test-failed`'s read-time branches are gone: **the
+check decides and labels** (write-time config + counters). The force-approve
+guard moves from `routingRules["tests-green"]` into the `runTest` act.
+
+### Agentic review (emptiness read from the DIFF)
+
+| From state             | Diff matcher                   | Label                          | Enters          |
+| ---------------------- | ------------------------------ | ------------------------------ | --------------- |
+| agentic-review (agent) | adds FEEDBACK, zero content    | `gtd(agent): agentic-approved` | close-pkg (act) |
+| agentic-review (agent) | adds FEEDBACK, non-empty       | `gtd(agent): agentic-findings` | fixing          |
+| close-pkg (act)        | rm pkg+FEEDBACK; pkgs remain   | `gtd: building`                | building        |
+| close-pkg (act)        | none remain, reviewable        | `gtd: review-record`           | review-record   |
+| close-pkg (act)        | none remain, nothing to review | settle label                   | —               |
+
+The delete-dispute (`pendingFeedbackDeletion`) becomes a matcher row on the
+fixing state (deletes/empties FEEDBACK → still a fixing turn), not a payload
+special case.
+
+### Human review, learning, squash, health, idle
+
+| From state             | Trigger                              | Label                                                                     | Enters                |
+| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------- | --------------------- |
+| review-record (agent)  | adds REVIEW.md (validated)           | `gtd(agent): review-record`                                               | await-review (window) |
+| await-review (human)   | empty / checkbox-only / deletes R    | `gtd(human): review-approved`                                             | cycle-close (act)     |
+| await-review (human)   | anything else                        | `gtd(human): review-feedback`                                             | regrill (act)         |
+| cycle-close (act)      | rm REVIEW                            | `gtd: done`                                                               | settle                |
+| regrill (act)          | rm REVIEW                            | `gtd: grilling`                                                           | grilling-draft        |
+| settle (act)           | learning on + base                   | `gtd: learning` (writes template)                                         | learning-draft        |
+| settle (act)           | squash on + base                     | `gtd: squashing` (writes template)                                        | squash-draft          |
+| settle (act)           | neither                              | `gtd: idle`                                                               | idle                  |
+| learning-draft (agent) | **touches LEARNINGS.md**             | `gtd(agent): learning-draft`                                              | learning-review       |
+| squash-draft (agent)   | **touches SQUASH_MSG.md**            | `gtd(agent): squash-draft`                                                | do-squash (act)       |
+| idle (human)           | step (clean) → act runs health check | red: `gtd: health-fixing` / cap: `gtd: escalated` / green: stop or settle | …                     |
+| health-briefed (agent) | any NON-empty diff                   | `gtd(agent): health-fixed`                                                | testing (act)         |
+| health-fixing (agent)  | any diff **or empty**                | `gtd(agent): health-fixed`                                                | testing (act)         |
+
+Two dissolutions worth naming: the template-unmodified probe becomes "diff
+touches the template file" (a matcher), and health-fixing's
+`inertWhen: humanEntryHead` guard becomes two states — `health-briefed` (entered
+via the human's entry; no empty-rule, so an empty agent step is inert by
+_absence of a rule_) vs `health-fixing` (entered via a red check; empty-rule
+present = environmental-fix signal).
+
+## 2. Counters: commit-message trailers, not subject suffixes
+
+Counters must be derivable from the nearest label alone, but a loop's counter
+lives across several states (test-failed → fixing → testing), and
+`reviewFixCount` spans the whole package loop. Encoding decision:
+
+- Subjects stay clean (`gtd(agent): fixing`).
+- Every label written _inside a counted loop_ carries a structured trailer:
+
+  ```
+  gtd(agent): fixing
+
+  Gtd-Counters: t=2/3 r=1/3
+  ```
+
+- The writer computes each value from the previous label's trailer (+increment /
+  reset per the definition's counter rules); a label with no trailer means
+  all-zero (loop entry). `δ` reads label = (subject, trailers).
+- `foldCounters` is deleted; caps are checked at act time from the trailer.
+
+Why trailers: subjects remain human-scannable and e2e-assertable; trailers are
+already precedent (`Gtd-Decisions`); `git log --format=%B` is already fetched
+(decisionLog reuses it — no new subprocess); and squash collapses them away at
+cycle end. Wire-format cost acknowledged: changing a budget's _semantics_
+becomes a history-compat concern (mitigated: values are `n/cap` so the cap
+travels with the count; a config cap change affects only future writes).
+
+## 3. What gets deleted (the payoff)
+
+| Deleted                                                                                                                                                | Replaced by                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| interrupt ladder + fallback ladder                                                                                                                     | `stateOf(label)` + per-state matcher rules; ONE retained refusal           |
+| `classifyHead` turn/routing branch rules                                                                                                               | total `stateOf` map (labels are unambiguous)                               |
+| `foldCounters` + `CommitEvent` flags (`isErrors`, `isFeedback`, …)                                                                                     | counter trailers                                                           |
+| `headTurnIsEmpty`, `headTurnReviewSubstantive`, `pendingFeedbackDeletion`, `squashMsgIsTemplate`, `learningMsgIsTemplate`, `feedbackEmpty` (as guards) | diff matchers at capture time                                              |
+| `emptyAgentTurn` policies (`inert`/`inertWhen`)                                                                                                        | inert-by-default: no matching rule = no-op (empty-rules are opt-in)        |
+| illegal-combination table (mostly)                                                                                                                     | can't arise: every write commits with its label; kept as capture-time lint |
+| `agenticReviewForceApproved` read-time guard, `settle` read-time branches                                                                              | write-time decisions in `runTest`/`closePackage`/`settle` acts             |
+| `awaits: "dynamic"`, `GATE_OVERRIDES`-style sharing                                                                                                    | one actor per state                                                        |
+
+`ResolvePayload` shrinks to: invoker, pending-diff facts (per-artifact
+touched/added/deleted/empty-add/checkbox-only), steering-file presence (for the
+corruption refusal + prompts), config (consumed by ACTS only), and prompt
+passthrough (diffs/content for templates — prompts remain impure by design, per
+Appendix C §C.4.2).
+
+## 4. Phases
+
+Each phase: full suite green (unit + all 263 e2e scenarios' behavior preserved,
+labels/state names mapped), `feat!:` commit, docs synced.
+
+**Phase 0 — Spec (no code).** Finalize the label/state table above as the new
+STATES.md §1 (names, matchers, trailer grammar, `stateOf`). Acceptance: a table
+review — every current e2e scenario hand-traced onto new labels with no
+ambiguity. This is where naming bikesheds happen, deliberately.
+
+**Phase A — State splitting + capture-time turn labels.** (`~21 → ~30` states;
+the `dynamic` gates, review approval/feedback, health-briefed split, entry
+labels.) Turn capture evaluates diff matchers and writes the decided label;
+`stateOf` replaces turn-rule branching; `headTurn*` payload fields deleted.
+Machine act labels unchanged in this phase. Biggest e2e churn (every
+`gtd(actor): <gate>` assertion), but mechanical per scenario since the exercised
+branch is evident from surrounding steps.
+
+**Phase B — Probes → diff matchers + effects-as-diffs invariant.** Template
+probes become touch-matchers; feedback emptiness read from the capture diff;
+delete-dispute becomes a matcher row. Add the engine invariant (dev/test
+assert): every `perform()` must commit a label and/or change files, or return
+stop. Mostly internal; small e2e deltas around crash-recovery scenarios (retrace
+them explicitly — this is where content-vs-diff divergence lives).
+
+**Phase C — Write-time outcomes + counter trailers.** `tests-green`/
+`test-failed` read-time branches move into the acts (labels
+`agentic-review`/`close-package`/`escalated`/`test-failed`+trailer);
+close-package decides building/review/settle at write time; settle decided at
+`done`/green with config in hand; `foldCounters`, commit-event flags, and both
+ladders deleted; corruption refusal re-anchored on "steering files present, no
+label reachable". Second wire-format break; e2e label updates are
+context-dependent this time (a green assertion becomes whichever outcome label
+the scenario's context produced) — budget one careful pass.
+
+**Phase D — Conformance + hardening.** (1) The δ property test: generate
+histories, then mutate anything _other than_ the nearest label+trailers and the
+pending diff (permute older commits, inject boundary commits, vary config where
+an act already decided) and assert `resolve` output is byte-identical. This test
+IS the purity claim. (2) Compiler checks: `stateOf` total, one actor per state,
+every act's outcome set covered, trailer continuity (a counted loop's labels all
+carry the vector). (3) STATES.md rewritten as the transition table; upgrading
+doc gains the third grammar migration note (old labels → boundary → `start`,
+refusal if steering files linger).
+
+## 5. Risks and open items
+
+- **Kill-switch semantics change (accepted):** config flips no longer affect a
+  rest already labeled; document loudly in configuration.md.
+- **Idle green stop:** a green idle health check commits nothing (today's
+  behavior) — fine for δ (no transition happened), but it means `start`/ `idle`
+  must be re-derivable cheaply every run; unchanged from today.
+- **Review checkout window:** unchanged (program-edge; keyed on the await-review
+  state's label).
+- **Trailer parsing:** extend `parseSubject` → `parseLabel(subject, body)`; Git
+  already returns full messages on the history read — verify no extra subprocess
+  creeps in (AGENTS.md decisionLog rule).
+- **Squash-base / review-base scans:** remain history reads inside acts and
+  prompts (sanctioned impurity); unchanged.
+- **Naming risk:** the table above is draft; Phase 0 exists so name changes cost
+  a review, not a re-implementation.
+- **Rough sizing:** Phase 0 small; A the largest (engine + ~35 feature files); B
+  small-medium; C medium with careful e2e mapping; D medium (property test is
+  the substance).

package/docs/design/pattern-machine-plan.md

@@ -0,0 +1,164 @@
+# Plan: the pattern machine (gtd v3)
+
+> **Status: implemented** (commits `b89e1ae..HEAD`). Two amendments made during
+> implementation, not reflected in the plan text below: (1) the commit subject's
+> `<actor>` half was fixed to record WHO STEPPED (the invoker), not the resolved
+> state's own declared actor — see `PatternMachine.ts`'s `resolveState` doc
+> comment and commit `09cd9df`; (2) the bundled default workflow's content is
+> fully INLINE, with no `./`-relative file references — the single-file
+> `dist/gtd.bundle.mjs` build can't ship a sibling `prompts/` directory to
+> resolve them against at runtime, unlike a `.gtdrc`-configured workflow, which
+> resolves file refs relative to its own config file's location on disk.
+
+> Interview outcome (all decided with the user, 2026-07-22):
+>
+> 1. **Ground-up v3.** The current definition model (gates, guard functions,
+>    actor kinds, interrupt/fallback ladders, counters-as-trailers, conflicts)
+>    is DELETED. The engine shrinks to: states, change-pattern transitions, and
+>    one content property per state. The shipped default workflow is re-authored
+>    in the new vocabulary as a bundled config; the e2e suite is rewritten
+>    around it; behavior changes where the old shape doesn't map.
+> 2. **Commit format:** `gtd(<actor>): <state>` — every workflow commit records
+>    the state being ENTERED and who authored the step. History is an attributed
+>    state trace; resolution = read HEAD's state name.
+> 3. **Scripts: the driver executes.** gtd only ever emits the rendered script
+>    (`gtd next`); the outer loop or the built-in `gtd run` convenience executes
+>    it and steps. The machine stays execution-free.
+> 4. **Budgets:** one engine affordance only — a per-state retry limit that
+>    redirects the transition to a named state when the limit is hit. Everything
+>    else (verdict encoding, force-approve, content signals) moves out of the
+>    engine into which files scripts/agents write or delete. `Gtd-Counters`
+>    trailers die.
+> 5. **Patterns:** contains-match over the pending diff, declaration order,
+>    first match wins. Statuses `A` (added), `M` (modified), `D` (deleted), `*`
+>    (any change kind), plus the special `C` (clean tree). Glob paths (`*`
+>    within a segment, `**` across segments).
+> 6. **No-match dirty step:** refusal — exit non-zero, name the state's declared
+>    patterns, commit nothing.
+> 7. **Squash = the `commit:` content kind** (revised 2026-07-22, replacing the
+>    earlier `final: true` flag). A state whose content property is `commit:` is
+>    the final state — no separate flag, no actor. Entering it performs, in one
+>    execution: (a) render the `commit:` Eta template against the PENDING
+>    working tree (`it.read(path)` reads files as they sit — the message file is
+>    never committed first; a failed render refuses the step and touches
+>    nothing), (b) soft-reset to the process's start parent and write ONE commit
+>    with the rendered message, (c) discard all remaining uncommitted changes,
+>    message file included. Squashing is optional (no `commit:` state = no
+>    squash) and nothing about it is hardcoded: the message filename appears
+>    only in user-authored patterns/templates, and the standard shape is an
+>    ordinary prompt state (`squashing`) whose agent authors the message file,
+>    with `"A COMMIT_MSG.md": done` routing to the commit state.
+> 8. **Template variables** for script/prompt/message/commit (all Eta; inline or
+>    a path relative to the config file, auto-inlined): `startCommit`,
+>    `currentCommit`, `previousCommit`, `state`, `actor`, `processDiff`
+>    (startCommit..HEAD + pending), `lastDiff` (the last transition's diff),
+>    `read(path)` (working-tree file read, available in every content kind), and
+>    `config` passthrough. No blessed config keys: there is no `testCommand` — a
+>    check's command lives inline in its `script:` (or the referenced file).
+
+## 1. The model
+
+A workflow is a set of named **states**. Each state declares:
+
+| Property                                      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor`                                       | A plain string: who is expected to act here. No kinds — every actor just creates modifications in the tree. `gtd step <actor>` authenticates against it. Commit states have NO actor — gtd itself performs them.                                                                                                                                                                                                                                          |
+| `script` \| `prompt` \| `message` \| `commit` | Exactly one — the content kind. `script` — an executable the DRIVER runs (`gtd next` emits it rendered; `gtd run` executes + steps). `prompt` — instructions for an agent. `message` — text for a human (drivers halt here). `commit` — the squash-commit message template; having it makes the state FINAL (see decision 7). Inline string or a file path relative to the config file (auto-inlined). All are Eta templates over the variable set above. |
+| `on`                                          | An ordered map of change patterns → next state. Evaluated at step time against the pending diff; first match wins; the step commits everything pending as `gtd(<actor>): <next-state>` — unless the target is a commit state, in which case the step performs the squash instead (decision 7). A commit state has no `on`: the process ends there.                                                                                                        |
+| `initial: true`                               | Exactly one state: where an unrecognized HEAD (any non-`gtd(actor): state` subject, or a state name outside this workflow) resolves. THE entry point; replaces entry rules, the fallback ladder, and boundary handling.                                                                                                                                                                                                                                   |
+| `retry`                                       | Optional: `{ max: <n>, otherwise: <state> }` — when a transition would enter this state for the (max+1)-th time within the current process, it enters `otherwise` instead, decided at write time and encoded in the committed label. Visit counting walks only the current process's commits (start → HEAD), so it stays bounded and resets naturally at entry/squash.                                                                                    |
+
+Pattern grammar: `<status> <glob>` where status ∈ `A|M|D|*`, or the bare token
+`C` (clean tree — the empty step as an explicit, opt-in event). Contains-match:
+a pattern fires if any pending change matches it. `"* *"` is the catch-all for
+any dirty tree.
+
+Resolution stays δ-pure and gets simpler:
+`next = f(HEAD's state name, pending diff pattern)` with exactly one impurity
+left (the retry count's process-scoped walk). Turn-taking keeps only:
+out-of-turn refusal (invoker ≠ state's actor), the no-match refusal, and the
+clean-step no-op when no `C` event is declared.
+
+## 2. What dies
+
+- Actor kinds (`interactive`/`autonomous`/`scripted`) and every carve-out keyed
+  on them (dirty-boundary entry turn, inert-clean-step defaults, draft
+  validation).
+- Gates, `TurnGate`, capture rules, turn rules, routing rules — replaced by `on`
+  maps. The two-namespace grammar collapses to one subject form.
+- Guard functions and the `WorkflowConfig` guard vocabulary (fact/all/any/
+  counterAtLeast/…) — replaced by change patterns.
+- Interrupt/fallback ladders, conflicts (illegal combinations), entry rules —
+  replaced by the initial state + explicit `on` edges.
+- `Gtd-Counters` trailers, stamps, forceApprove, fixAttemptCap/ reviewThreshold
+  config keys — replaced by `retry` + script-owned logic.
+- The content-inspection exceptions (FEEDBACK.md emptiness, checkbox-only
+  REVIEW.md diffs, doc-structure validation): verdicts are now expressed by
+  which file is written or deleted (`D FEEDBACK.md` = approve, `M FEEDBACK.md` =
+  findings).
+- The review checkout window (v3.0 drops it; may return later as a state flag —
+  noted as a follow-up, not in scope).
+
+## 3. What the CLI becomes
+
+- `gtd step <actor>` — authenticate, match patterns, commit
+  `gtd(<actor>): <next-state>` (with retry redirection at write time). A
+  transition targeting a commit state performs the squash instead of a turn
+  commit. Refusals: out-of-turn, no-match, failed `commit:` render.
+- `gtd next [--json]` — emit the resolved state's rendered
+  script/prompt/message; JSON carries
+  `{state, actor, kind: script|prompt|message, content}` as the driver dispatch
+  key. Resolution never rests AT a commit state (entering one ends the process),
+  so `kind: commit` never appears here.
+- `gtd run` — the built-in script driver: execute the emitted script verbatim,
+  then `gtd step <actor>`.
+- `gtd status` — state, actor, and which pattern each pending change matches.
+- `bin/gtd-loop` / the loop skill dispatch on `kind`.
+
+## 4. The bundled default workflow (re-authored)
+
+Sketch (final shape decided during Phase 3): `idle` (initial; message;
+`"* *" → grilling`… actually entry captures the dirty tree), `grilling` ⇄
+`grilling-answer`, `architecting` ⇄ `architecting-answer`, `decompose`,
+`building`, `checking` (script — the test command lives INLINE in the script, no
+`testCommand` config key; `A FEEDBACK.md → fixing`, retry max 3 → `escalate`,
+`C → reviewing`), `fixing`, `reviewing`, `await-review`
+(`D REVIEW.md → squashing`, `M REVIEW.md → grilling`), `escalate`, `squashing`
+(prompt: author the commit-message file; `A COMMIT_MSG.md → done`), `done`
+(`commit: <%~ it.read("COMMIT_MSG.md") %>`). Health path becomes `idle`'s own
+script + `A HEALTH.md` edge. Verdict changes vs today: agentic approval = DELETE
+FEEDBACK.md; review approval = DELETE REVIEW.md; the check script owns its
+attempt count only if we want output-dependent budgets (the engine `retry`
+covers the standard case).
+
+## 5. Phases (each lands green, committed, pushed)
+
+1. **Engine core.** New `src/PatternMachine.ts` (or repurposed Machine.ts):
+   state defs, pattern parser/matcher, resolve (HEAD state name → state;
+   unrecognized → initial), step semantics (refusals, C-event, no-match), retry
+   redirection, the commit-state squash action (render-then-squash-then-drop,
+   refusal on render failure). New minimal `ResolvePayload` (pending changes as
+   `{status, path}[]`, hashes, clean flag). Unit + property tests (δ: next =
+   f(state, diff); totality; refusal invariants).
+2. **Config + templates.** The `workflow:` key becomes the ONLY definition
+   source (bundled default = a YAML asset compiled the same way): states, actor
+   strings, script/prompt/message/commit (inline or file-relative, auto-inlined
+   at load), `on` maps, validation (exactly one initial, exactly one content
+   property, every target defined, retry.otherwise defined, commit states carry
+   no actor and no `on`). Eta rendering with the agreed variable set, including
+   the `read(path)` helper.
+3. **Default workflow re-authoring + CLI.** Write the bundled default config;
+   rewire program.ts (step/next/run/status), gtd-loop, loop skill; delete the
+   old model (Workflow.ts rules, WorkflowConfig guard language, Subjects
+   two-namespace grammar → one subject parser over the active state set;
+   Events.ts flag/trailer plumbing).
+4. **E2e rewrite.** New feature files pinning the engine semantics (patterns,
+   refusals, retry, final squash, initial-state entry, driver protocol) +
+   default-workflow journeys. Old features deleted or rewritten.
+5. **Docs.** STATES.md replaced by the v3 model reference; configuration.md
+   workflow section rewritten; upgrading doc gains the v3 note (old histories:
+   all previous subjects are unrecognized → initial state, by design); AGENTS.md
+   updated.
+
+Sizing: phases 1–2 are the substance (new core + compiler); phase 3 is the big
+deletion; phase 4 is broad but mechanical; phase 5 small.