@pmelab/gtd 2.8.0 → 3.1.0

package/docs/upgrading.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "2.8.0",
+  "version": "3.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -84,6 +84,6 @@
     "eta": "^4.6.0",
     "prettier": "^3.8.1",
     "vscode-languageserver": "^10.1.0",
-    "vscode-languageserver-textdocument": "^1.0.12"
+    "vscode-languageserver-textdocument": "^1.0.13"
   }
 }

package/schema.json

@@ -1,82 +1,106 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$defs": {
-    "Int": {
-      "type": "integer",
-      "description": "an integer",
-      "title": "int"
-    }
-  },
   "type": "object",
   "required": [],
   "properties": {
-    "testCommand": {
-      "type": "string"
-    },
-    "models": {
+    "workflow": {
       "type": "object",
-      "required": [],
+      "description": "The whole machine definition: named states (plus the workflow's own vars: defaults). Compiled and validated by gtd at load time; content strings starting with ./ or ../ are file references inlined from the config file's directory.",
+      "additionalProperties": false,
+      "required": ["states"],
       "properties": {
-        "planning": {
-          "type": "string"
-        },
-        "execution": {
-          "type": "string"
+        "vars": {
+          "type": "object",
+          "description": "Flat name -> scalar map merged into every template's it.vars. Scalars are coerced to strings.",
+          "additionalProperties": {
+            "type": ["string", "number", "boolean"]
+          }
         },
         "states": {
           "type": "object",
-          "required": [],
-          "properties": {
-            "decompose": {
-              "type": "string"
-            },
-            "grilling": {
-              "type": "string"
-            },
-            "architecting": {
-              "type": "string"
-            },
-            "building": {
-              "type": "string"
-            },
-            "fixing": {
-              "type": "string"
-            },
-            "agentic-review": {
-              "type": "string"
-            },
-            "clean": {
-              "type": "string"
+          "description": "The workflow's named states. At least one; exactly one with initial: true.",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "description": "One workflow state. Declare exactly one content kind (script/prompt/message/commit). A commit state is final: no actor, no on.",
+            "additionalProperties": false,
+            "properties": {
+              "actor": {
+                "type": "string",
+                "description": "Who acts at this state. Required on every non-commit state; forbidden on a commit state."
+              },
+              "script": {
+                "type": "string",
+                "description": "Content kind: a shell script (Eta template). `gtd run` executes it verbatim via bash, then steps this state's actor."
+              },
+              "prompt": {
+                "type": "string",
+                "description": "Content kind: an agent prompt (Eta template), emitted by `gtd next`."
+              },
+              "message": {
+                "type": "string",
+                "description": "Content kind: a human-facing message (Eta template), emitted by `gtd next`."
+              },
+              "commit": {
+                "type": "string",
+                "description": "Content kind: entering this state ends the process by squashing it into one commit with this message (Eta template). Final — no actor, no on."
+              },
+              "on": {
+                "type": "object",
+                "description": "Ordered map of change pattern -> target state. Patterns: \"C\" (clean tree) or \"<A|M|D|*> <glob>\" over the pending diff; first declared match wins. Every target must name a defined state, and every non-initial state must be reachable through these edges (or a retry.otherwise).",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "initial": {
+                "type": "boolean",
+                "description": "Exactly one state in the workflow must declare initial: true (and it must not be a commit state)."
+              },
+              "retry": {
+                "type": "object",
+                "description": "Redirect transitions INTO this state once it has been entered `max` times in the current process.",
+                "additionalProperties": false,
+                "required": ["max", "otherwise"],
+                "properties": {
+                  "max": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Entries allowed this process before redirecting."
+                  },
+                  "otherwise": {
+                    "type": "string",
+                    "description": "Defined state to redirect to once over the cap."
+                  }
+                }
+              },
+              "model": {
+                "type": "string",
+                "description": "Opaque harness hint passed through `gtd next --json`/`gtd status --json` (e.g. \"smart\"). Never interpreted by gtd. Forbidden on a commit state."
+              },
+              "file": {
+                "type": "string",
+                "description": "The state's steering file: an Eta template naming the file a human/editor should look at while the machine rests here. Forbidden on a commit state."
+              },
+              "mode": {
+                "type": "string",
+                "enum": ["qa", "review"],
+                "description": "The steering file's format, dispatched on by the LSP. Requires a sibling `file:`. Forbidden on a commit state."
+              }
             }
-          },
-          "additionalProperties": false
+          }
         }
-      },
-      "additionalProperties": false
+      }
     },
-    "agenticReview": {
-      "type": "boolean"
-    },
-    "squash": {
-      "type": "boolean"
-    },
-    "learning": {
-      "type": "boolean"
-    },
-    "decisionLog": {
-      "type": "boolean"
-    },
-    "fixAttemptCap": {
-      "$ref": "#/$defs/Int",
-      "description": "a non-negative number",
-      "title": "greaterThanOrEqualTo(0)",
-      "minimum": 0
+    "vars": {
+      "type": "object",
+      "description": "Flat name -> scalar map merged into every template's it.vars. Scalars are coerced to strings.",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean"]
+      }
     },
-    "reviewThreshold": {
-      "$ref": "#/$defs/Int",
-      "description": "a number greater than or equal to 1",
-      "title": "greaterThanOrEqualTo(1)",
-      "minimum": 1
+    "$schema": {
+      "type": "string",
+      "description": "Editor-only pointer at this schema. Stripped by gtd before validation."
     }
   },
   "additionalProperties": false

package/docs/upgrading-from-v1.md

@@ -1,45 +0,0 @@
-# Upgrading from v1 (BREAKING CHANGE)
-
-v2 ships as a **major** semantic-release bump (`2.0.0`) so the binary and the
-loop-driving text ([docs/loop.md](loop.md), `skills/loop/SKILL.md`) can never
-skew against each other. There is **no backward compatibility with the v1
-command surface**: the single mutating `gtd` command, marker/sentinel files, the
-`autoAdvance` JSON field, and the `gtd: transport` handoff commit are all gone.
-`gtd` bare now errors rather than driving a loop; use `gtd step-agent` /
-`gtd next` / `gtd step` instead.
-
-**Commit-history compatibility is one-way.** Any repo with v1-taxonomy history
-in it (`gtd: new task`, `gtd: grilling`, `gtd: transport`, a bare
-`gtd: reviewing` with no hash, …) upgrades cleanly: those subjects fall outside
-v2's closed turn/routing grammar and parse as inert **boundary commits** — they
-are never mistaken for v2 workflow state and never error.
-
-**Finish or clean up any in-flight v1 cycle first.** If a repo has an
-**in-progress** v1 cycle — steering files present (root-level `TODO.md`,
-`REVIEW.md`, `FEEDBACK.md`, `ERRORS.md`, or `.gtd/`) whose HEAD carries v1-only
-commit subjects — the v2 binary does not know how to resume it: v1 steering
-files have no v2 turn commit backing them, so a cold v2 invocation on that tree
-can land in an unrecognized state. Either finish the v1 cycle to a clean
-boundary with your existing v1 binary before upgrading, or manually clean up
-(remove the steering files / `.gtd/`, commit the result) so the upgrade starts
-from a plain boundary HEAD.
-
-**Steering files moved into `.gtd/`.** Earlier v2 builds kept `TODO.md`,
-`REVIEW.md`, `FEEDBACK.md`, `ERRORS.md`, `HEALTH.md`, and `SQUASH_MSG.md` at the
-repository root; they now live under `.gtd/`. Upgrade at a clean boundary (idle,
-post-squash): a repo at rest needs nothing. Mid-cycle repos should either finish
-the cycle on the old build first or move the root-level steering files into
-`.gtd/` by hand and commit. History classification is backward-compatible — the
-counter folds recognize both the old root paths and the new `.gtd/` paths in
-existing commits.
-
-**Re-copy the loop skill.** If you vendor `skills/loop/` into a consuming repo
-or agent harness, upgrading the `gtd` binary also means re-copying that skill
-from this release — the v1 skill text still describes the old single-command
-loop and will drive the new binary incorrectly.
-
-For maintainers: this repo releases via `semantic-release` reading Conventional
-Commits, and needs **no config change** for a major bump — but the release
-commit/PR **must carry a `BREAKING CHANGE:` footer** (or a `!` after the type)
-for `@semantic-release/commit-analyzer` to compute `2.0.0` rather than a
-minor/patch bump.