@pmelab/gtd 6.14.0 → 7.1.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 (8) hide show
  1. package/README.md +21 -19
  2. package/dist/gtd.bundle.mjs +850 -322
  3. package/docs/cli.md +69 -72
  4. package/docs/configuration.md +120 -57
  5. package/docs/development.md +2 -1
  6. package/docs/upgrading.md +23 -21
  7. package/package.json +1 -1
  8. package/schema.json +180 -0
package/schema.json CHANGED
@@ -36,6 +36,182 @@
36
36
  }
37
37
  }
38
38
  },
39
+ "submachines": {
40
+ "type": "object",
41
+ "description": "Optional reusable sub-machines, invoked by `use:` and expanded into concrete states at load time (see src/Submachines.ts).",
42
+ "additionalProperties": {
43
+ "type": "object",
44
+ "description": "A reusable, parameterized cluster of states, expanded at load time by each `use:` invocation into concrete states (see src/Submachines.ts). Purely a source-authoring convenience — the engine only ever sees the expanded states.",
45
+ "additionalProperties": false,
46
+ "required": ["states"],
47
+ "properties": {
48
+ "params": {
49
+ "type": "array",
50
+ "items": {
51
+ "type": "string"
52
+ },
53
+ "description": "Parameter names. A `$name` token used as a whole field value or `on`/`retry.otherwise` target is replaced by the invocation's `with:` binding."
54
+ },
55
+ "states": {
56
+ "type": "object",
57
+ "description": "The sub-machine's local states. `on`/`retry.otherwise` targets naming another local are rewritten via `as:`; a `$name` value is bound from `with:`.",
58
+ "minProperties": 1,
59
+ "additionalProperties": {
60
+ "type": "object",
61
+ "description": "One workflow state. Declare exactly one content kind (script/prompt/message/commit). A commit state is final: no actor, no on.",
62
+ "additionalProperties": false,
63
+ "properties": {
64
+ "actor": {
65
+ "type": "string",
66
+ "description": "Who acts at this state. Required on every non-commit state; forbidden on a commit state."
67
+ },
68
+ "script": {
69
+ "type": "string",
70
+ "description": "Content kind: a shell script (Eta template). The loop driver executes it verbatim via bash, then steps this state's actor."
71
+ },
72
+ "prompt": {
73
+ "type": "string",
74
+ "description": "Content kind: an agent prompt (Eta template), emitted by `gtd next`."
75
+ },
76
+ "message": {
77
+ "type": "string",
78
+ "description": "Content kind: a human-facing message (Eta template), emitted by `gtd next`."
79
+ },
80
+ "commit": {
81
+ "type": "string",
82
+ "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."
83
+ },
84
+ "on": {
85
+ "type": "object",
86
+ "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). A value is either the target state name (string) or a { to, describe } object whose describe is a human-readable sentence templates can surface as it.edges (e.g. in a human gate's message).",
87
+ "additionalProperties": {
88
+ "oneOf": [
89
+ {
90
+ "type": "string",
91
+ "description": "The target state name."
92
+ },
93
+ {
94
+ "type": "object",
95
+ "additionalProperties": false,
96
+ "required": ["to"],
97
+ "properties": {
98
+ "to": {
99
+ "type": "string",
100
+ "description": "The target state name."
101
+ },
102
+ "describe": {
103
+ "type": "string",
104
+ "description": "Human-readable sentence describing where this change routes; surfaced verbatim (never Eta-rendered) to templates as it.edges[].describe."
105
+ }
106
+ }
107
+ }
108
+ ]
109
+ }
110
+ },
111
+ "initial": {
112
+ "type": "boolean",
113
+ "description": "Exactly one state in the workflow must declare initial: true (and it must not be a commit state)."
114
+ },
115
+ "retry": {
116
+ "type": "object",
117
+ "description": "Redirect transitions INTO this state once it has been entered `max` times in the current process.",
118
+ "additionalProperties": false,
119
+ "required": ["max", "otherwise"],
120
+ "properties": {
121
+ "max": {
122
+ "type": "integer",
123
+ "minimum": 0,
124
+ "description": "Entries allowed this process before redirecting."
125
+ },
126
+ "otherwise": {
127
+ "type": "string",
128
+ "description": "Defined state to redirect to once over the cap."
129
+ }
130
+ }
131
+ },
132
+ "model": {
133
+ "type": "string",
134
+ "description": "Opaque harness hint passed through `gtd next --json`/`gtd status --json` (e.g. \"smart\"). Never interpreted by gtd. Forbidden on a commit state."
135
+ },
136
+ "memory": {
137
+ "type": "string",
138
+ "description": "Opaque memory-scope label passed through `gtd next --json`/`gtd status --json` (e.g. \"plan\"). A memory-aware driver retains an agent's memory across consecutive agent turns sharing this label and starts fresh when it changes. Never interpreted by gtd. Forbidden on a commit state."
139
+ },
140
+ "file": {
141
+ "type": "string",
142
+ "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."
143
+ },
144
+ "mode": {
145
+ "type": "string",
146
+ "description": "The steering file's format: the name of a built-in mode (qa/review, validated in-process by gtd) or of a `modes:` entry. gtd formats and validates the file with that mode before capturing a turn out of this state, and the LSP dispatches live diagnostics on the built-in names. Requires a sibling `file:`. Forbidden on a commit state."
147
+ },
148
+ "reviewWindow": {
149
+ "type": "boolean",
150
+ "description": "When true, gtd opens a review checkout window while the machine rests here — HEAD/index are rewound to the review base so the whole base..HEAD diff surfaces as uncommitted changes in the editor. Forbidden on a commit state."
151
+ },
152
+ "reviewBase": {
153
+ "type": "boolean",
154
+ "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."
155
+ },
156
+ "reviewEntry": {
157
+ "type": "boolean",
158
+ "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."
159
+ },
160
+ "fixEntry": {
161
+ "type": "boolean",
162
+ "description": "Marks the (at most one) state `gtd fix` enters to start a brand new process that goes straight into repairing the current failing tests. Forbidden on a commit state and on the initial state."
163
+ },
164
+ "requireProgress": {
165
+ "type": "boolean",
166
+ "description": "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
167
+ },
168
+ "answerGate": {
169
+ "type": "boolean",
170
+ "description": "When true, a step at this state is refused unless every open question in its qa-mode `file:` is answered — exactly one checkbox ticked per question. Requires a `file:` and `mode: qa`. Forbidden on a commit state."
171
+ }
172
+ }
173
+ }
174
+ }
175
+ }
176
+ }
177
+ },
178
+ "use": {
179
+ "type": "array",
180
+ "description": "Sub-machine invocations. Each clones a `submachines:` entry into concrete states: `as:` renames its locals (identity when omitted), `with:` binds its `$param`s, `set:` adds extra per-instance state fields.",
181
+ "items": {
182
+ "type": "object",
183
+ "additionalProperties": false,
184
+ "required": ["submachine"],
185
+ "properties": {
186
+ "submachine": {
187
+ "type": "string",
188
+ "description": "Name of a declared sub-machine."
189
+ },
190
+ "name": {
191
+ "type": "string",
192
+ "description": "Optional label for this instance (inert to expansion; used by tooling like `gtd visualize` to name the group). Defaults to the sub-machine name."
193
+ },
194
+ "as": {
195
+ "type": "object",
196
+ "description": "Rename map: local state name -> concrete state name (identity when omitted).",
197
+ "additionalProperties": {
198
+ "type": "string"
199
+ }
200
+ },
201
+ "with": {
202
+ "type": "object",
203
+ "description": "Bindings for the sub-machine's `$param`s."
204
+ },
205
+ "set": {
206
+ "type": "object",
207
+ "description": "Extra fields merged onto a renamed local state, keyed by local name.",
208
+ "additionalProperties": {
209
+ "type": "object"
210
+ }
211
+ }
212
+ }
213
+ }
214
+ },
39
215
  "states": {
40
216
  "type": "object",
41
217
  "description": "The workflow's named states. At least one; exactly one with initial: true.",
@@ -148,6 +324,10 @@
148
324
  "requireProgress": {
149
325
  "type": "boolean",
150
326
  "description": "When true, a step at this state is refused if its only pending change is deleting the state's own `file:` — a work-free turn that discards its input without addressing it. A `NOTHING ACTIONABLE` sentinel file is exempt (a legitimately non-actionable round makes no code change). Requires a `file:`. Forbidden on a commit state."
327
+ },
328
+ "answerGate": {
329
+ "type": "boolean",
330
+ "description": "When true, a step at this state is refused unless every open question in its qa-mode `file:` is answered — exactly one checkbox ticked per question. Requires a `file:` and `mode: qa`. Forbidden on a commit state."
151
331
  }
152
332
  }
153
333
  }