@pmelab/gtd 7.11.2 → 8.1.0

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

@@ -1,283 +0,0 @@
-# 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

@@ -1,164 +0,0 @@
-# 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.

package/docs/design/pluggable-steering-modes.md

@@ -1,154 +0,0 @@
-# Pluggable steering-file modes
-
-> Status: IMPLEMENTED. The authoritative reference is
-> [STATES.md §12](../../STATES.md) (the model) and
-> [docs/configuration.md](../configuration.md#modes--pluggable-steering-file-modes)
-> (the config surface); this doc is the design record. Builds on
-> [steering-file-validation-command.md](steering-file-validation-command.md),
-> which introduced `gtd validate` and the `gtd step` capture gate.
-
-## 1. Motivation
-
-`mode:` was a CLOSED vocabulary of two names — `qa` and `review` — each
-hardwired to a parser gtd ships (`src/OpenQuestions.ts` / `src/ReviewDoc.ts`).
-That is fine for the bundled default workflow, whose steering files ARE those
-two formats, but it makes the rest of the machine's extensibility story stop
-short: a workflow is data (states, actors, patterns, content, `vars:`) right up
-to the moment it wants a state whose output is checkable in some other way — an
-ADR, a JSON spec, an OpenAPI document, a translation catalogue. Such a state can
-declare a `file:`, but not what "valid" means for it, so the format gate the
-whole design leans on (a human gate is only ever handed a well-formed file)
-simply doesn't exist for it.
-
-Meanwhile gtd already knows how to let a workflow bring its own executable
-behavior: the scripted check actor (`script:` content run verbatim through
-`bash`, its outcome read back off the tree). Modes are the same shape of problem
-and deserve the same answer — a shell command, not a code change in gtd.
-
-## 2. The design
-
-A **mode is a pair of shell commands over one file**: `format` (rewrite it in
-place) and `validate` (exit 0, or exit non-zero with the findings on
-stdout/stderr). Both optional; at least one required.
-
-```yaml
-workflow:
-  modes:
-    adr:
-      format: "npx prettier --write <%= it.file %>"
-      validate: "./scripts/check-adr.sh <%= it.file %>"
-  states:
-    drafting:
-      actor: agent
-      prompt: "Write the ADR."
-      file: docs/adr/<%= it.vars.slug %>.md
-      mode: adr
-```
-
-Five decisions:
-
-### 2.1 Modes are workflow data, with a project layer over it
-
-A `modes:` map sits beside `states:` and `vars:` INSIDE `workflow:`, compiling
-onto `WorkflowDefinition.modes`: a mode exists to serve a state's `mode:`, and
-states are workflow data, so a workflow that needs a custom mode carries its
-own.
-
-A top-level `.gtdrc` `modes:` key layers over that, per half (`mergeModes`),
-exactly the way the top-level `vars:` key layers over the workflow's own
-`vars:`. Without it, a project on the BUNDLED default workflow could not plug in
-a formatter at all without copying every state into its `.gtdrc` — and since gtd
-ships no formatter (§2.2), that is precisely the common case. The rc layer is
-merged into the definition BEFORE `validateDefinition` runs
-(`compileWorkflowConfig`'s `rcModes` argument), so a state may name a mode
-either layer declares and the load-time name check (§2.3) stays a pure function
-of one definition.
-
-### 2.2 `qa` and `review` stay built in — as VALIDATORS, and only that
-
-The two existing modes' parsers are also what `gtd lsp` publishes as live
-diagnostics and what its document symbols and code actions are built on —
-shelling out per keystroke over an unsaved buffer is a different (and much
-worse) design. So gtd keeps them as its `BUILT_IN_MODES`, available in every
-workflow without being declared.
-
-Their FORMATTING half went the other way. gtd used to bundle prettier and expose
-it as a `gtd format <file>` subcommand, which the built-in modes then called;
-both are gone (the subcommand, and prettier as a runtime dependency — the
-single-file bundle drops from ~15 MB to ~10 MB). A project brings its own
-formatter and plugs it into whichever mode should use it. The two built-ins
-therefore VALIDATE and nothing else, until a `modes:` entry gives them a
-`format:`.
-
-Which forces the resolution rule: the halves resolve INDEPENDENTLY, first layer
-wins per half.
-`modes: { qa: { format: "npx prettier --write <%= it.file %>" } }` adds
-formatting to `qa` and keeps gtd's open-questions validation; declaring
-`validate:` instead displaces the parser. (An earlier draft of this design had a
-declared entry REPLACE a built-in wholesale — that cannot express "gtd's
-validation plus my formatter", which is the common case.)
-
-### 2.3 `mode:` stays load-time-validated, against a definition-derived set
-
-`validateDefinition` no longer checks a hardcoded vocabulary; it checks
-`knownModes(def)` — the built-ins plus the declared names — exactly the way the
-commit grammar's closed actor set derives from `declaredActors`. A typo'd mode
-must not silently disable both the capture gate and the editor's diagnostics, so
-this stays an error at config-load time, and its message lists both sets.
-
-### 2.4 Commands are Eta templates with `it.file`, executed at the edge
-
-A command sees the resting state's full template context plus `it.file`, the
-already-rendered steering-file path (`PatternTemplates.ModeCommandContext`) — so
-a command can read `it.vars`, and a workflow whose `file:` is vars-parameterized
-never has to repeat the path. Execution is `bash -c` from the repo root, output
-captured (unlike `gtd run`'s scripted actor, whose output is for the human).
-
-`./scripts/check-adr.sh` in a command is a COMMAND, never a `./`-relative file
-reference the way a content string is — inlining it as template text would break
-the obvious reading.
-
-### 2.5 The pure engine still never validates anything
-
-Everything above is an edge concern, in one new module, `src/SteeringMode.ts`
-(resolution + execution) — the same shape as `src/ReviewWindow.ts`. The engine
-carries `modes:` as inert data and validates its shape; `PatternMachine.step`
-never sees a mode.
-
-## 3. What changed
-
-| Area                                    | Change                                                                                                                                                                                             |
-| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/PatternMachine.ts`                 | `ModeDef`; `WorkflowDefinition.modes`; `StateMode` widened from `"qa" \| "review"` to `string`; `BuiltInMode`/`isBuiltInMode`/`knownModes`; `validateModes`; `validateMode` now definition-derived |
-| `src/PatternConfig.ts`                  | `compileModesMap` + `mergeModes` (mirroring `compileVarsMap`), `modes` added to `KNOWN_TOP_KEYS`, `compileWorkflowConfig`'s `rcModes` argument                                                     |
-| `src/Config.ts` / `src/ConfigSchema.ts` | the third blessed top-level key, `modes:` (`compileRcModes`), layered over the compiled workflow (or the bundled default) per half                                                                 |
-| `src/Format.ts`, `gtd format <file>`    | DELETED, and `prettier` dropped from the runtime dependencies — formatting is a mode's own command now                                                                                             |
-| `src/PatternTemplates.ts`               | `ModeCommandContext` (`TemplateContext` + `file`) and `renderModeCommand`                                                                                                                          |
-| `src/SteeringMode.ts` (new)             | `resolveSteeringMode` (per half), `formatSteeringFile`, `validateSteeringFile`, `formatAndValidateSteeringFile`, `unknownModeMessage`                                                              |
-| `src/program.ts`                        | `formatAndCheckSteeringFile` routes through the resolved mode (was: a hardcoded `qa`/`review` switch plus `formatFile`); `gtd validate` and the capture gate are otherwise unchanged               |
-| `src/ConfigSchema.ts` / `schema.json`   | the `modes:` object; `mode:`'s `enum` dropped                                                                                                                                                      |
-| `src/Lsp.ts`                            | docs only — a custom mode gets no live diagnostics/symbols/code actions (documented limitation)                                                                                                    |
-| `src/workflows/default.yaml`            | unchanged — the bundled default keeps `qa`/`review`, which resolve to the built-in validators                                                                                                      |
-
-One behavior change for existing users: steering files are no longer
-auto-formatted, because gtd no longer has a formatter to do it with. Validation
-is untouched. A project that wants the old behavior adds four lines to its
-`.gtdrc` (the `modes: { qa: { format: … } }` snippet in
-[configuration.md](../configuration.md#modes--pluggable-steering-file-modes)).
-
-## 4. Known limitations
-
-- **No live editor support for a custom mode.** `gtd lsp` dispatches on the
-  built-in names only; a workflow-declared mode's file gets no diagnostics, no
-  document symbols, no code actions. It is still formatted and validated by
-  `gtd validate` and the `gtd step` gate.
-- **Nothing is formatted out of the box.** The bundled default declares no
-  `format:` command, so a fresh install validates but never rewrites. This was
-  the deliberate alternative to shipping an `npx prettier` default, which would
-  make every gate depend on prettier resolving in the user's project.
-- **A command runs on the developer's machine, unsandboxed** — same trust model
-  as a `script:` state: a `.gtdrc` is project code.
-- **`gtd next`'s self-validation instruction** is appended for any `prompt` rest
-  declaring `file:`+`mode:`, including a mode that declares only `format:`
-  (where `gtd validate` can only ever pass). Harmless, and keeps the rule "a
-  state that hands over a steering file tells its agent to check it".