@pmelab/gtd 9.2.0 → 9.4.0

package/README.md

@@ -121,10 +121,14 @@ reads intent first, glob second.
 to the tree — a hand-edit to real code, a scratch note in some file, anything at
 all — as a sketch to be finished, never as work to be preserved: there is no
 fork on which steering file you happen to create, and `idle` has exactly one
-outgoing edge, into `unwind`. `unwind` reverts that whole diff back out of your
-working tree (`git revert --no-commit` against the commit it just landed in)
-before planning ever starts — your tree is back to exactly what it was, and your
-intent doesn't disappear, it survives in history for `design.triage` to read.
+outgoing edge, into `unwind`. `.gtd/TODO.md` (the `todoFile` var) is a good
+default place to start sketching when you'd rather write a note than touch code
+— despite living beside the workflow's own state files, that sketch is your
+input for `design.triage` to fold in, never gtd bookkeeping to preserve or
+ignore. `unwind` reverts that whole diff back out of your working tree
+(`git revert --no-commit` against the commit it just landed in) before planning
+ever starts — your tree is back to exactly what it was, and your intent doesn't
+disappear, it survives in history for `design.triage` to read.
 
 From there, `start-gate.check` runs your test suite on the tree as it now stands
 — which, thanks to the unwind, is simply your repo's own baseline. The rule is
@@ -181,30 +185,37 @@ alone is not a pending change, and only actually removing it from disk counts as
 a deletion). The next landing's own script closes the window before it commits.
 Tick a box as you review each hunk (ticking just records "I read this"), and
 leave a **comment** to request changes: a note on a line, an inline
-`// TODO`-style comment in the code, or a direct code edit. Any comment sends a
-build + re-review round — an agent first turns your comments into an explicit
-instruction list, then a build turn implements it (a re-review then covers only
-the follow-through, and a hand-edit is treated as your own fix the agent
-completes without reverting your lines; a comment can't be silently dropped — a
-build turn that addresses nothing is refused). The build turn that follows
-through on feedback and the turn that drafts the final squash message both
-resume the same session that built the feature in the first place, since the
-review tail is nested inside that build identity rather than sitting beside it.
-Ticking every box with no comment is the sign-off, which collapses the whole
-process into one commit (a **squash finale** whose message an agent drafts).
-Landing with a box still unticked and no comment is refused (finish reviewing
-first), as is deleting `.gtd/REVIEW.md`. Both refusals hold wherever the review
-doc lives: repointing `reviewFile` out of `.gtd/` (say to `REVIEW.md` at the
-repo root) changes nothing about them — your own edit to the review doc is never
-mistaken for a code comment, and the doc's pre-turn copy is read at the review
-window's saved head rather than at the rewound `HEAD`.
+`// TODO`-style comment in the code, or a direct code edit. A comment sends a
+FULL development lap, not a quick fix-and-re-review: an agent first judges
+whether your comment is actually actionable (a genuinely approving remark with
+no code edit short-circuits straight to sign-off instead), and an actionable
+round is re-planned from scratch through triage, architecture, and the package
+queue again — a hand-edit you made during review is treated as a **sketch**, the
+same as any other change that starts a process, not a fix the agent builds on:
+it is reverted out of the tree first, and your intent survives only in your own
+review-round commit for triage to read. There is no baseline check on the way
+back into planning. Only the turn that drafts the final squash message resumes
+the session that built the feature in the first place (the review tail is nested
+inside that build identity rather than sitting beside it) — an actionable round
+leaves that identity entirely, so it starts a fresh session like any other
+process. Ticking every box with no comment is the sign-off, which collapses the
+whole process into one commit (a **squash finale** whose message an agent
+drafts). Landing with a box still unticked and no comment is refused (finish
+reviewing first), as is deleting `.gtd/REVIEW.md`. Both refusals hold wherever
+the review doc lives: repointing `reviewFile` out of `.gtd/` (say to `REVIEW.md`
+at the repo root) changes nothing about them — your own edit to the review doc
+is never mistaken for a code comment, and the doc's pre-turn copy is read at the
+review window's saved head rather than at the rewound `HEAD`.
 
 A second entry, the same review tail's own direct entry point —
 `gtd --entry review-gate.check --var reviewBase=<commitish>` starts a brand new
-process reviewing `<commitish>..HEAD` with no build of its own, e.g. a
-colleague's PR branch (`review-gate.check`'s `reviewBase:` is a template bound
-to the `reviewBase` var, so supplying it via `--var` fixes the whole process's
-diff base to that commitish). Its squash keeps and describes only the fixes made
+process reviewing `<commitish>..HEAD` with no build of its own on a clean
+sign-off, e.g. a colleague's PR branch (`review-gate.check`'s `reviewBase:` is a
+template bound to the `reviewBase` var, so supplying it via `--var` fixes the
+whole process's diff base to that commitish) — though an actionable round on
+this entry runs the same full triage → gates → architecture → package-queue lap
+as any other, same as `re-unwind` re-plans a build process's own review
+feedback. A clean sign-off's squash keeps and describes only the fixes made
 _during_ the review (not the reviewed changeset); a clean sign-off with no fixes
 becomes an empty `chore: human review` commit. A third entry,
 `gtd --entry fix-precheck`, starts from a clean `idle` and goes straight into
@@ -227,13 +238,27 @@ to target a state.
 Every agent state routes its model through two `vars` tiers — `plannerModel`
 (heavier planning and review) and `coderModel` (the coding turns) — so you can
 repoint the models globally in one place (a `vars:` edit or a `GTD_PLANNERMODEL`
-override) instead of per state. Steering-file path vars (`feedbackFile`,
-`reviewFile`, …) work the same way, and propagate to the `on` patterns that
-route on them too — a repointed path var actually reroutes the machine, not just
-the templates that read/write the file. A separate `stateDir` var (default
-`.gtd`) names only where the check scripts keep their own scratch/bookkeeping,
+override) instead of per state. Steering-file path vars (`todoFile`,
+`feedbackFile`, `reviewFile`, …) work the same way, and propagate to the `on`
+patterns that route on them too — a repointed path var actually reroutes the
+machine, not just the templates that read/write the file. `todoFile` (default
+`.gtd/TODO.md`, `idle`'s own `file:` hint) is the one exception: it's the only
+per-file var gtd never writes and never reads, since it names your own sketch
+pad, not a file any state produces. A separate `stateDir` var (default `.gtd`)
+names only where the check scripts keep their own scratch/bookkeeping,
 independent of the per-file vars — relocate one steering file without touching
-it.
+it. The workflow declares its plumbing directory once, at the top level of the
+`workflow:` value (`stateDir: <%= it.vars.stateDir %>` in the bundled template),
+rendered from that same `stateDir` var — this is what the engine itself reads to
+tell gtd's own bookkeeping apart from your code (e.g. the review window's revert
+pathspec, the step guards' code-vs-plumbing check), not just a value the
+templates happen to share. The rendered value is constrained: it must name a
+directory inside the repository — not the repo root, not an absolute path, and
+not a path that escapes the repository via `..` — and it must be spelled
+canonically: no `.` and no empty path segments (`a/./state` or `a//state` are
+rejected, not rewritten), though a leading `./` and a trailing `/` are accepted
+— or the next `gtd next`/`gtd status`/`gtd land` fails loudly with that message,
+rather than silently excluding the whole tree from the review window's revert.
 
 To inspect or change the machine itself, see [Configuration](#configuration) —
 the workflow is just `.gtdrc` config.
@@ -453,11 +478,15 @@ started FROM. Entering a **descendant** scope (e.g. dipping from `build` into
 a nested child machine, then back to the parent, still resumes the SAME parent
 conversation; entering a **sibling or unrelated** scope does start a fresh one.
 The bundled template's `build.review` (the human review tail) is a worked
-example: it is nested INSIDE `build` (the builder's own machine) precisely
-because that descendant relationship is what lets `build.addressing` and
-`build.squashing` resume the session that built the feature across a full review
-round-trip, instead of a root-level sibling breaking that run on every pass
-through the tail. Two instances of the same reusable machine (e.g.
+example: it is nested INSIDE `build` (the builder's own machine) so that a
+`gtd --entry fix-precheck` run — `build.fix` -> `build.health.check` ->
+`build.review.*` -> `build.squashing` — stays inside one subtree, letting
+`build.squashing` resume the SAME session that made the fixes instead of a
+root-level sibling forcing it to re-derive the range from scratch on every pass
+through the tail. (An actionable review round breaks the run on purpose instead
+— it leaves `build` entirely through a root-level `re-unwind` state and a full
+re-plan, since a hand-edit made during review is a sketch to reconsider, not a
+fix to build on.) Two instances of the same reusable machine (e.g.
 `build.health` and `packages.item.health`, both instantiating `healthGate`) get
 different scopes and so never share a key, even though they're the "same shaped"
 machine. One consequence is a structural guarantee: **a reviewer's turn never
@@ -823,18 +852,19 @@ its own retry/resume logic beyond "if the script failed, ask gtd again."
 A mode's `format:` command may reformat a steering file — whitespace, wrapping,
 reordering — but must NEVER change what a land-capture guard would decide. gtd's
 guards (the review sign-off check, the feedback-progress check, the
-answer-completeness check — `src/StepGuards.ts`) decide ONCE, against whichever
-bytes are on disk at the moment `gtd land` runs, which may be before OR after an
-emitted script's own `format:` line has run (the script runs `format:` then
-`validate:` then the commit — see `src/SteeringMode.ts`'s
-`renderSteeringCommands` — but gtd's decision and the driver's script execution
-are different processes at different times, so there's no guaranteed ordering
-between "gtd decided" and "the script formatted"). That's only safe because
-every built-in guard judges content, not incidental formatting (e.g. it
-normalizes `[ ]`/`[x]` checkboxes before comparing). If you plug in your own
-`format:` command, the same rule binds it: a formatter that also changes meaning
-— ticking a box, stripping a paragraph — makes the guard's decision and the
-file's actual content disagree, and gtd will not catch that for you.
+answer-completeness check, the require-revert check — `src/StepGuards.ts`)
+decide ONCE, against whichever bytes are on disk at the moment `gtd land` runs,
+which may be before OR after an emitted script's own `format:` line has run (the
+script runs `format:` then `validate:` then the commit — see
+`src/SteeringMode.ts`'s `renderSteeringCommands` — but gtd's decision and the
+driver's script execution are different processes at different times, so there's
+no guaranteed ordering between "gtd decided" and "the script formatted"). That's
+only safe because every built-in guard judges content, not incidental formatting
+(e.g. it normalizes `[ ]`/`[x]` checkboxes before comparing). If you plug in
+your own `format:` command, the same rule binds it: a formatter that also
+changes meaning — ticking a box, stripping a paragraph — makes the guard's
+decision and the file's actual content disagree, and gtd will not catch that for
+you.
 
 One case never runs your `format:` (or `validate:`) at all: a step whose diff
 DELETES the state's own `file:`. Deleting it is a legitimate outcome — a review
@@ -921,6 +951,7 @@ workflow:
     <name>:
       format: <shell command> # both optional — {} is the format-only tier
       validate: <shell command>
+  stateDir: <string> # optional, an Eta template naming where this workflow keeps its own plumbing (default ".gtd") — the definition-level declaration the engine reads, distinct from the `vars.stateDir` var the bundled template renders it from
   entry:
     default: <machine name> # which machine is the ROOT instance
   machines:
@@ -953,6 +984,7 @@ workflow:
           # reviewBase: <Eta template> # OR a template — rendered (only meaningful entering via --entry) to a commitish that fixes the WHOLE PROCESS's diff base
           requireProgress: true # optional, requires "file" — refuse a turn whose only change deletes this state's own `file:`
           answerGate: true # optional, requires "file" — refuse a turn until every open question in the (qa-mode) `file:` is answered
+          requireRevert: true # optional, requires "file" — refuse a turn until the human's review-round paths actually match the review base's parent
           entry: true # optional — an EXTRA reachability root (`entries.manual`), enterable via `gtd --entry <this state's qualified name>` — NOT a precondition for `--entry` (any declared, non-commit state is a valid target)
         <local>: { machine: <name>, with: { <param>: <value> } } # a REFERENCE — instantiates <name> as a child, qualified as `<local>.<childLocal>`
 ```
@@ -965,7 +997,11 @@ derives a driver's session id).
 The top-level `entry:` key (naming the root machine, `entry.default`) and a
 state's own `entry: true` flag are the same word at two different levels, by
 design: one selects the workflow's root machine, the other opts one state in as
-an extra manual entry point.
+an extra manual entry point. The top-level `stateDir:` key and the
+`vars.stateDir` var it renders from are the same call: the definition-level
+declaration is what the engine reads (e.g. to tell gtd's own plumbing apart from
+your code), while the var is the knob you actually override — repointing
+`vars.stateDir` moves both.
 
 A workflow is authored as a TREE of reusable, parameterized machines — a
 gate/loop written once and instantiated several times with different `with:`
@@ -985,7 +1021,12 @@ Besides `it.vars` (below), a `script`/`prompt`/`message`/`commit` template sees:
 - **`it.startCommit`** — the process's diff base (the commit the current process
   started from, or the base a `--var reviewBase=<commitish>` entry resolved to).
 - **`it.reviewBase`** — the previous review round's boundary, falling back to
-  `it.startCommit` on a first review.
+  `it.startCommit` on a first review. In the bundled template, an actionable
+  round's NEXT review therefore covers the revert of the human's own lines
+  (`re-unwind`) followed by the whole lap that re-derives and re-implements them
+  — the net diff is the final implementation, the right thing to review, but no
+  longer the tiny "just the fixes" delta a quick fix-and-re-review would have
+  shown.
 - **`it.retainedBase`** — the process's trace/retry boundary, what a squash
   actually keeps (never moved by a review entry's fixed base).
 - **`it.currentCommit`** / **`it.previousCommit`** — HEAD's hash and its parent,
@@ -1080,11 +1121,23 @@ model, pattern grammar, load-time rules, and how to verify a change compiles.
 > `design.gate.answer`, `design.technical-author` → `architecture.author`,
 > `design.technical-answer` → `architecture.gate.answer`, `design.decompose` →
 > `architecture.decompose` (architecture is now its own sibling machine with its
-> own memory scope, not nested under `design`). The `todoFile` var and the
-> `prose` mode are both gone — there is no more free-form plan file. As with
-> every rename above, an in-flight process resting at one of the old names can
-> no longer be resumed; `gtd abandon` it (or finish it on the pre-upgrade
-> workflow version) before upgrading.
+> own memory scope, not nested under `design`). The `prose` mode is gone and
+> there is no more free-form _plan_ file — `todoFile` itself came back later
+> with a different job: `idle`'s own mode-less `file:` hint, gtd's sketch pad
+> that no state writes or reads. As with every rename above, an in-flight
+> process resting at one of the old names can no longer be resumed;
+> `gtd abandon` it (or finish it on the pre-upgrade workflow version) before
+> upgrading.
+
+> **Upgrading a `workflow:` that still references `build.addressing`?** That
+> state is REMOVED, not renamed — the implementer's own follow-through on review
+> feedback is gone outright, since an actionable review round is now re-planned
+> from scratch through a new root-level `re-unwind` state (reverting the human's
+> hand-edit) instead of being built upon. A non-actionable round (an approving
+> remark with no code edit) short-circuits straight to `build.squashing` instead
+> of spending a lap on nothing. As with every rename above, an in-flight process
+> resting at `build.addressing` can no longer be resumed after upgrading;
+> `gtd abandon` it (or finish it on the pre-upgrade workflow version) first.
 
 ### Variables
 
@@ -1197,7 +1250,14 @@ separator), symbols over a `qa`-mode file's open questions plus "pick this
 option"/"uncheck this option" code actions on each option — offered anywhere on
 the option's list item, including any wrapped continuation lines, not just its
 own `- [ ]` line — diagnostics for both (live as you edit), and a
-`gtd.openSteeringFile` command that jumps to the current state's steering file.
+`gtd.openSteeringFile` command that jumps to the current state's steering file —
+including `idle`, whose `todoFile` hint gives the one keybinding an answer even
+before a process has started. The command only names that path — it never
+stat-checks or creates it — so on a repo that has never run gtd, `.gtd/` may not
+exist yet and editors differ on opening a file whose parent directory is missing
+(an empty buffer that creates it on save vs. refusing the path outright); this
+bites only the very first sketch in a fresh repo, since the workflow's own check
+scripts create the state directory on the first `gtd next`/`gtd land`.
 
 It is config-driven via each state's `file:`/`mode:`, and falls back to basename
 dispatch (`REVIEW.md` → `review`) with no config in sight. `qa` and `review` are