@pmelab/gtd 5.0.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +32 -19
  2. package/dist/gtd.bundle.mjs +281 -153
  3. package/docs/cli.md +85 -12
  4. package/docs/configuration.md +116 -51
  5. package/docs/development.md +7 -5
  6. package/docs/examples/advanced-workflow.md +33 -23
  7. package/docs/upgrading.md +49 -32
  8. package/package.json +1 -1
  9. package/schema.json +4 -0
package/docs/upgrading.md CHANGED
@@ -15,8 +15,8 @@ design — v1 and v2 subjects alike.** v3's `resolveState`
15
15
  subject naming a state and an actor the active workflow currently declares;
16
16
  everything else — a v1 `gtd: grilling`, a v2 `gtd(agent): building`, a plain
17
17
  `chore: …` commit, anything from a foreign repo — parses as unrecognized and
18
- lands at the workflow's initial state (`idle` in the bundled default). There is
19
- no special-casing for "this looks like an old gtd commit": the mechanism is
18
+ lands at the workflow's initial state (`idle` in the `simple` template). There
19
+ is no special-casing for "this looks like an old gtd commit": the mechanism is
20
20
  exactly the same one that already made v1 history inert to v2, and v2 history
21
21
  inert to a differently-configured workflow — v3 just applies it uniformly to all
22
22
  prior history instead of drawing a v1/v2 line.
@@ -41,8 +41,8 @@ upgrading.
41
41
  all gone — `workflow:` and `vars:` are the only two blessed keys (see
42
42
  [Configuration](configuration.md)). A check's command now lives inline in its
43
43
  own `script:` content, reading a workflow-declared `it.vars` entry (the
44
- bundled default's `testCommand`, overridable via the top-level `vars:` key or
45
- a `GTD_VAR_testCommand` environment variable — see
44
+ `simple` template's `testCommand`, overridable via the top-level `vars:` key
45
+ or a `GTD_VAR_testCommand` environment variable — see
46
46
  [Configuration's "Variables"](configuration.md#variables)) rather than a
47
47
  blessed `testCommand` config key; squashing is a `commit:` state instead of a
48
48
  boolean flag; there is no learning phase, no decision log, and no model
@@ -53,17 +53,17 @@ upgrading.
53
53
  v3.0 rewrite, then RE-INTRODUCED as the explicit state property it was always
54
54
  meant to become: a state declaring `reviewWindow: true` opens the window while
55
55
  the machine rests there (base = the process start, or a state marked
56
- `reviewBase: true`). The bundled default enables it on `await-review`. Unlike
57
- v2's hardwired gate, it is pure workflow DATA and the engine stays oblivious —
58
- see [STATES.md §11](../STATES.md) and the `file:`/`mode:` neighbours in
59
- [configuration.md](configuration.md).
56
+ `reviewBase: true`). The `simple` template enables it on `await-review`.
57
+ Unlike v2's hardwired gate, it is pure workflow DATA and the engine stays
58
+ oblivious — see [STATES.md §11](../STATES.md) and the `file:`/`mode:`
59
+ neighbours in [configuration.md](configuration.md).
60
60
  - **`forceApprove`, content-inspection verdicts.** FEEDBACK.md emptiness,
61
61
  checkbox-only REVIEW.md diffs, and doc-structure validation are gone as ENGINE
62
62
  mechanisms — verdicts are now expressed purely by which file a turn writes or
63
- deletes, matched by an ordinary `on` pattern. The bundled default workflow's
64
- own checkbox-review verdict (`review-deciding`) is ordinary WORKFLOW data (an
65
- `on` pattern), not an engine hook: `D REVIEW.md` = approve, `M REVIEW.md` =
66
- route to the deterministic decider, in the bundled default. Deterministic
63
+ deletes, matched by an ordinary `on` pattern. The `simple` template's own
64
+ checkbox-review verdict (`review-deciding`) is ordinary WORKFLOW data (an `on`
65
+ pattern), not an engine hook: `D REVIEW.md` = approve, `M REVIEW.md` = route
66
+ to the deterministic decider, in the `simple` template. Deterministic
67
67
  format-checking of the steering files is likewise no longer a pair of
68
68
  in-machine `check`/`script` states — the old `todo-validating`/
69
69
  `review-validating` states and their `.gtd/FORMAT.md` steering file are gone,
@@ -71,14 +71,23 @@ upgrading.
71
71
  (see
72
72
  [docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
73
73
  and [STATES.md §12](../STATES.md)).
74
- - **`gtd review <target>`.** Gone; the v3 command surface is `step` / `next` /
75
- `run` / `status` / `validate` / `mermaid` / `lsp` (see
76
- [CLI reference](cli.md)).
74
+ - **`gtd review <target>`.** Gone in the initial v3 rewrite, then RETURNED in
75
+ this version with different, narrower semantics: it no longer inspects an
76
+ arbitrary target the way v2 did — it starts a brand NEW review process at a
77
+ workflow-declared `reviewEntry: true` state, reviewing `<target>..HEAD` (e.g.
78
+ a colleague's PR branch with no gtd process of its own) by writing one empty
79
+ entry commit with a `Gtd-Review-Base:` trailer and reusing the workflow's
80
+ existing review/feedback machinery unmodified — see
81
+ [STATES.md §11](../STATES.md#11-the-review-checkout-window) and
82
+ [CLI reference](cli.md#gtd-review-commitish---json). The current command
83
+ surface is `init` / `step` / `next` / `status` / `validate` / `mermaid` /
84
+ `review` / `lsp`.
85
+
77
86
  - **`gtd format <file>`, and the bundled prettier with it.** gtd no longer
78
87
  formats anything on its own: a steering-file mode declares its own `format:`
79
88
  SHELL COMMAND, so a project brings whatever formatter it already uses. Adding
80
89
  four lines to `.gtdrc` restores (and improves on) the old auto-formatting for
81
- the bundled default workflow:
90
+ the `simple` template:
82
91
 
83
92
  ```yaml
84
93
  modes:
@@ -107,25 +116,33 @@ upgrading.
107
116
  itself only understands the two built-ins), the LSP reads that same config the
108
117
  CLI does to build its path→mode dispatch, and `gtd.openSteeringFile` resolves
109
118
  the current state and shows its `file:`. No mapping declared at all (the
110
- bundled default's predecessor shape, or any workflow with no `file:`/`mode:`)
111
- falls back to basename dispatch (`TODO.md`/`REVIEW.md`), same as before this
112
- addition.
119
+ `simple` template's predecessor shape, or any workflow with no
120
+ `file:`/`mode:`) falls back to basename dispatch (`TODO.md`/`REVIEW.md`), same
121
+ as before this addition.
113
122
 
114
123
  ## How to adopt
115
124
 
116
- `workflow:` is optional — with no config at all, the bundled default workflow
117
- applies: a single-shot `grilling` plan, direct `building`, a `checking`/`fixing`
118
- loop, and a direct-diff `await-review` that rests the cycle back at `idle` on
119
- approval — no squash; every turn commit stays in history for you to squash
120
- however you like, or not at all (see
121
- [STATES.md §10](../STATES.md#10-the-bundled-default-workflow)) — expressed as
122
- data rather than baked into the engine. The fuller grilling ⇄ grilling-answer /
123
- architecting ⇄ architecting-answer / decompose / picking / reviewing shape v2
124
- shipped — including a squash finale — is preserved as a copy-paste `.gtdrc`
125
- example at [docs/examples/advanced-workflow.md](examples/advanced-workflow.md)
126
- rather than the bundled default. Nothing to do for a repo that's happy with the
127
- default shape beyond a normal `npm install -g @pmelab/gtd` upgrade, from a
128
- settled `idle` boundary.
125
+ `workflow:` is now **required** — gtd ships no default workflow, so after
126
+ upgrading each repo must scaffold one **once**:
127
+
128
+ ```bash
129
+ gtd init simple # or: gtd init advanced
130
+ ```
131
+
132
+ `gtd init simple` writes a `.gtdrc.json` with the `simple` template inline: a
133
+ single-shot `grilling` plan, direct `building`, a `checking`/`fixing` loop, and
134
+ a direct-diff `await-review` that rests the cycle back at `idle` on approval —
135
+ no squash; every turn commit stays in history for you to squash however you
136
+ like, or not at all (see
137
+ [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
138
+ `gtd init advanced` writes the fuller grilling ⇄ grilling-answer / architecting
139
+ ⇄ architecting-answer / decompose / picking / reviewing machine — including a
140
+ squash finale — walked through at
141
+ [docs/examples/advanced-workflow.md](examples/advanced-workflow.md). Review and
142
+ commit the generated `.gtdrc.json`, then continue from a settled `idle`
143
+ boundary. **Note:** a repo relying on earlier gtd's auto-created `.gtdrc.json`
144
+ `$schema` stub (which carried no `workflow:`) will now fail until you `gtd init`
145
+ — the stub alone is no longer enough.
129
146
 
130
147
  A repo that customized v2's `workflow:` key (actors, gates, guard vocabulary,
131
148
  ladders) needs to rewrite it from scratch in the v3 schema — see
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pmelab/gtd",
3
- "version": "5.0.0",
3
+ "version": "6.0.0",
4
4
  "private": false,
5
5
  "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
6
6
  "bin": {
package/schema.json CHANGED
@@ -136,6 +136,10 @@
136
136
  "reviewBase": {
137
137
  "type": "boolean",
138
138
  "description": "Marks the state whose most-recent in-process commit anchors the review window's diff base; absent any, the base is the process start. Forbidden on a commit state."
139
+ },
140
+ "reviewEntry": {
141
+ "type": "boolean",
142
+ "description": "Marks the (at most one) state `gtd review <commitish>` enters to start a brand new process reviewing <commitish>..HEAD. Forbidden on a commit state and on the initial state."
139
143
  }
140
144
  }
141
145
  }