@pmelab/gtd 9.3.0 → 9.5.0

package/README.md

@@ -150,7 +150,11 @@ questions: each open question offers a couple of candidate answers plus a
 `- [ ] _your answer_` slot, and you tick exactly one per question (the gate
 won't let the phase advance while any question is unanswered) — but a phase
 whose document has no open questions skips that human stop entirely and falls
-straight through.
+straight through. If a question's options ever come out as prose instead of
+`- [ ]` rows, there is no checkbox for the gate to see, so it stays permanently
+unanswered; un-wedge it yourself: hand-write the `- [ ]` rows and tick one,
+delete that question, or delete the whole `## Open Questions` section to accept
+the plan as-is.
 
 Once the product questions are settled, `architecture.author` picks up as a
 **cold reader** — a separate machine with its own memory scope, so it does not
@@ -185,30 +189,41 @@ 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. If a styled `.gtd/REVIEW.md` ever comes out malformed (a
+paragraph where a `- [ ] ./path#line` row belongs), `gtd check review` refuses
+the step before it commits: the file stays exactly as written in the working
+tree, unlanded, and re-running the same prompt is the recovery — nothing is
+lost. 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
@@ -240,7 +255,18 @@ 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.
@@ -460,11 +486,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
@@ -830,18 +860,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
@@ -928,6 +959,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:
@@ -960,6 +992,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>`
 ```
@@ -972,7 +1005,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:`
@@ -992,7 +1029,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,
@@ -1095,6 +1137,16 @@ model, pattern grammar, load-time rules, and how to verify a change compiles.
 > `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
 
 Every template — `script`/`prompt`/`message`/`commit`, a machine's own `model:`,
@@ -1134,6 +1186,52 @@ vars:
 GTD_TESTCOMMAND="npm run test -- --bail" gtd next
 ```
 
+#### The voice
+
+gtd ships its own writing voice for the files it generates — the default, not an
+opt-in. It is a specialisation of the "Spartan" output style from
+[alexgreensh/attention-span](https://github.com/alexgreensh/attention-span)
+(AGPL-3.0), written from a reading of that project's version `0.6`: gtd's own
+prose stating the same density discipline, rewritten for deliverables (files
+that run as long as the work needs) rather than chat replies. No upstream text
+ships in gtd's bundle. This is a point-in-time derivation with no refresh
+mechanism — it will silently go stale as upstream moves on, and nothing in gtd
+will notice.
+
+It is two independently-overridable variables, each an ordinary `vars:` entry
+that can be overridden or blanked through the same layers as any other (a
+top-level `.gtdrc` `vars:` key, or the matching `GTD_STYLEBLOCK` /
+`GTD_STYLEFORMATCONTRACT` environment variable):
+
+- **`styleBlock`** — the voice itself, injected at all seven prompt states that
+  generate content, not just three: the free-prose ones — the `packagesDir`
+  package files (`architecture.decompose`), `specFeedbackFile`
+  (`packages.item.spec.review`), and `commitMsgFile` (`build.squashing`) — plus
+  the four machine-parsed states named in the next bullet. Blanking
+  `GTD_STYLEBLOCK` strips the voice from all seven, including the machine-parsed
+  ones, not only the free-prose three. In short: why density matters before any
+  rule, answer-first with no preamble or restatement, blunt and imperative,
+  plain words, bold carries the load, ship the artifact bare, compressing is not
+  dropping, one idea per block, flag risk in one blunt line, never narrate the
+  work — and never-trim outranks every other rule in the set.
+- **`styleFormatContract`** — the structural override for machine-parsed files:
+  the format contract (headings, checkbox rows, marker lines) outranks the
+  voice, and a violation refuses the turn. It renders at the top of the prompt,
+  ahead of the role sentence and well before any state-specific format-contract
+  text — `styleBlock` first, then `styleFormatContract`, at the four prompt
+  states whose output a parser reads: the two `qa`-mode steering files
+  (`requirementsFile` at `design.triage`, `architectureFile` at
+  `architecture.author`) and the `review`-mode one (`reviewFile` at
+  `build.review.reviewing`), plus `requirementsFile` again at
+  `build.review.collecting`, which classifies a review round straight into it.
+
+Three more generated files carry no injected voice, because a script — not an
+agent — writes them: `feedbackFile` (verbatim test-suite output plus a HEAD
+stamp — the tool's content, not gtd's prose), `nextFile` (a bare path, no prose
+to style), and `reviewRawFile` (gtd's own prose, hand-tightened in the voice
+directly in `build.review.deciding`'s script rather than templated in through
+either variable).
+
 ### Lookup and precedence
 
 gtd walks from the current working directory **up to your home directory** (or