@pmelab/gtd 1.6.1 → 1.7.0

package/README.md

@@ -17,7 +17,7 @@ merge-base with the default branch (whole-history fallback when there is no
 default branch, when HEAD equals the merge-base, or when there is no merge-base
 — i.e. budgets engage on the default branch too) plus the working tree, turns
 them into a `COMMIT[]` + single terminal `RESOLVE` event stream, and folds them
-through the machine. The fold lands on exactly **one** of 17 states, which
+through the machine. The fold lands on exactly **one** of 18 states, which
 selects the prompt. A single run resolves to a single state.
 
 `resolve()` returns that state plus an optional **`EdgeAction`** (a commit,
@@ -239,7 +239,9 @@ flowchart TD
     P5 -->|no| P6{"TODO.md?"}
     P6 -->|"open markers"| GrillStop["Grilling — gtd: grilling, STOP for answers"]:::gate
     P6 -->|"dirty, no markers"| GrillIter["Grilling — gtd: grilling, agent iterates"]:::agent
-    P6 -->|"clean, no markers"| Grilled["Grilled — gtd: grilled, decompose"]:::agent
+    P6 -->|"clean, no markers"| GrilledReview["Grilled review — gtd: grilled, human review"]:::gate
+    GrilledReview -->|"re-run gtd clean"| Grilled["Grilled — gtd: grilled, decompose"]:::agent
+    GrilledReview -->|"edits present"| GrillIter
     P6 -->|absent| P7{"clean + boundary/package-done HEAD,<br/>reviewable diff?"}
     P7 -->|yes| CleanState["Clean — write REVIEW.md"]:::agent
     P7 -->|no| Idle
@@ -290,7 +292,7 @@ back into the working tree uncommitted, and re-derives state from scratch. If
 the transport commit is the repository's root commit (no parent), `gtd` fails
 immediately with a clear error instead of looping.
 
-## The 17 states
+## The 18 states
 
 Each state has a **condition** (when it wins), a deterministic **action**, the
 **commit(s)** it produces, and where it **advances**. States marked
@@ -313,8 +315,9 @@ action and re-resolves silently.
 | **Accept Review**  | edge-only, auto                  | REVIEW.md committed + pending **non-checkbox** edits (human annotated REVIEW.md with comments / edited code)                                                                | seed TODO.md from the changeset, `git checkout` to discard the code edits, rm REVIEW.md; **all uncommitted**                                                                                                                                                                                                           | Grilling                                                     |
 | **Await Review**   | edge-only, auto                  | REVIEW.md present and **uncommitted** (freshly written by Clean)                                                                                                            | commit REVIEW.md `gtd: awaiting review`                                                                                                                                                                                                                                                                                | Done (auto, same run)                                        |
 | **New Feature**    | edge-only, auto                  | boundary HEAD + pending changes (code and/or a new uncommitted TODO.md), **or** HEAD `gtd: new task` + clean tree (lost-seed regen)                                         | commit the raw input verbatim `gtd: new task` (unless already there), `git revert --no-commit` it back to a clean baseline, seed TODO.md from that diff — revert + seed left **uncommitted**                                                                                                                           | Grilling                                                     |
-| **Grilling**       | agent (iterate) / STOP (answers) | TODO.md present, not New Feature                                                                                                                                            | commit pending edits `gtd: grilling`. Open-question markers present → STOP for the human to answer inline; no markers but dirty → grilling agent iterates                                                                                                                                                              | converge (no markers, clean tree) → Grilled                  |
-| **Grilled**        | agent, auto                      | TODO.md present, no markers, clean tree                                                                                                                                     | commit pending `gtd: grilled`                                                                                                                                                                                                                                                                                          | decompose into `.gtd/` → Planning                            |
+| **Grilling**       | agent (iterate) / STOP (answers) | TODO.md present, not New Feature                                                                                                                                            | commit pending edits `gtd: grilling`. Open-question markers present → STOP for the human to answer inline; no markers but dirty → grilling agent iterates                                                                                                                                                              | converge (no markers, clean tree) → Grilled review           |
+| **Grilled review** | STOP                             | TODO.md present, no markers, clean tree, HEAD `gtd: grilled` (converged — not yet decomposed)                                                                               | none                                                                                                                                                                                                                                                                                                                   | edits → Grilling; clean re-run → Grilled                     |
+| **Grilled**        | agent, auto                      | TODO.md present, no markers, clean tree, HEAD `gtd: grilled` (returning from Grilled review with no new edits)                                                              | commit pending `gtd: grilled`                                                                                                                                                                                                                                                                                          | decompose into `.gtd/` → Planning                            |
 | **Clean**          | agent                            | no steering files, clean tree, boundary or `gtd: package done` HEAD, and the review base yields a **non-empty** diff                                                        | compute the review base (four rules — see below); agent writes REVIEW.md **uncommitted** with `# Review: <short-hash>` heading, `<!-- base: <full-hash> -->` marker, and per-hunk `- [ ]` checkboxes (ticking them signals approval → Done)                                                                            | Await Review                                                 |
 | **Idle**           | STOP                             | no steering files, clean tree, and nothing to review (HEAD `gtd: done` with `squash` disabled or after Squashing, or no reviewable diff)                                    | none                                                                                                                                                                                                                                                                                                                   | —                                                            |
 
@@ -422,9 +425,11 @@ loop before the next one starts.
    your answer, and run `gtd` again. The agent integrates answers, moves them to
    `## Resolved`, and raises fresh questions — repeat until none remain (it
    writes `no open questions — run gtd to plan` with no markers).
-4. **Converge.** A clean tree with no markers resolves to **Grilled**
-   (`gtd: grilled`), then **Planning** decomposes `TODO.md` into ordered `.gtd/`
-   work packages (`gtd: planning`).
+4. **Converge.** A clean tree with no markers resolves to **Grilled review**
+   (`gtd: grilled`) — a human STOP. Review the plan; edit and re-run `gtd` to
+   re-enter Grilling, or re-run `gtd` with no changes to advance. A clean re-run
+   triggers **Grilled** (auto-advance), which then **Planning** decomposes
+   `TODO.md` into ordered `.gtd/` work packages (`gtd: planning`).
 5. **Build.** Run `gtd` — **Building** first deletes `TODO.md` (when HEAD is
    `gtd: planning` and it is still present, committed under the same
    `gtd: planning` prefix — fires once). It then names the single next package
@@ -442,9 +447,9 @@ loop before the next one starts.
    (`gtd: done`) → **Squashing** → **Idle**. The Squashing agent authors a
    conventional-commits message from the full process diff and squashes all
    intermediate `gtd: *` commits into one with `git reset --soft <base>` +
-   <<<<<<< HEAD `git commit`, then **gtd STOPs**. The base is the parent of the
-   current cycle's start marker **nearest to HEAD** (the last `gtd: new task`;
-   for legacy cycles the last contiguous `gtd: grilling` run), and on a feature
+   `git commit`, then **gtd STOPs**. The base is the parent of the current
+   cycle's start marker **nearest to HEAD** (the last `gtd: new task`; for
+   legacy cycles the last contiguous `gtd: grilling` run), and on a feature
    branch it never reaches below the merge-base with the default branch — stray
    markers left behind by older squashes can never drag the squash into
    previously shipped features. Post-squash review does not fire automatically —
@@ -453,20 +458,13 @@ loop before the next one starts.
    has no unrelated code dirty — a lone untracked `SQUASH_MSG.md` is tolerated
    and deleted before the squash commit. If unrelated code is dirty at
    `gtd: done`, gtd routes to **New Feature** instead. Set `squash: false` in
-   ======= `git commit`, then **gtd STOPs**. Post-squash review does not fire
-   automatically — it fires only on the next manual `gtd` run (when the squash
-   commit is the boundary HEAD and a reviewable diff exists). Squashing fires
-   when the tree has no unrelated code dirty — a lone untracked `SQUASH_MSG.md`
-   is tolerated and deleted before the squash commit. If unrelated code is dirty
-   at `gtd: done`, gtd routes to **New Feature** instead. Set `squash: false` in
-   > > > > > > > origin/46-config-schema `.gtdrc` to skip squashing and go
-   > > > > > > > straight to Idle. Checking off REVIEW.md checkboxes (`- [ ]` →
-   > > > > > > > `- [x]`) also counts as approval and routes to **Done** — they
-   > > > > > > > are navigation aids, not feedback. Only **non-checkbox** edits
-   > > > > > > > (code changes, inline comments, textual annotations in
-   > > > > > > > REVIEW.md) trigger **Accept Review**, which seeds a fresh
-   > > > > > > > `TODO.md` from your feedback, discards your code edits, removes
-   > > > > > > > `REVIEW.md`, and re-enters Grilling — the loop starts over.
+   `.gtdrc` to skip squashing and go straight to Idle. Checking off REVIEW.md
+   checkboxes (`- [ ]` → `- [x]`) also counts as approval and routes to **Done**
+   — they are navigation aids, not feedback. Only **non-checkbox** edits (code
+   changes, inline comments, textual annotations in REVIEW.md) trigger **Accept
+   Review**, which seeds a fresh `TODO.md` from your feedback, discards your
+   code edits, removes `REVIEW.md`, and re-enters Grilling — the loop starts
+   over.
 
 ## Configuration
 
@@ -814,37 +812,6 @@ Run `npm run test:mutation` after making changes to the mutated files to check
 whether surviving mutants increased. The HTML report lands in
 `reports/mutation/mutation.html` (git-ignored).
 
-### Mutation testing
-
-Run mutation testing on-demand with `npm run test:mutation` (StrykerJS, ~2 min).
-The single `stryker.config.json` mutates six core files:
-
-```
-src/Machine.ts  src/Prompt.ts  src/Config.ts
-src/Format.ts   src/State.ts   src/Events.ts
-```
-
-`src/Git.ts` is excluded: the Cucumber harness stubs git at the Effect boundary,
-so Git.ts mutants have zero in-memory coverage. Measuring its post-refactor
-Live-tier kill rate is a follow-up before re-including it.
-
-**`process.chdir()` gotcha (resolved).** `@stryker-mutator/vitest-runner`
-hardcodes `pool: 'threads'` internally, and `process.chdir()` is unsupported in
-worker threads. Before the cwd refactor (package 01), four test files
-(`Events.test.ts`, `Git.test.ts`, `Config.test.ts`, `TestRunner.test.ts`) had to
-be excluded from all Stryker runs. The refactor eliminated those calls, letting
-all four files rejoin the run.
-
-Two additional notes: `vitest.related` is disabled for feature-file runs because
-feature files don't import source files directly (Stryker's coverage-based
-filtering would assign zero tests to every mutant). Compile-error mutants are
-counted as kills by the TypeScript checker — they represent real signal, not a
-configuration problem.
-
-Run `npm run test:mutation` after making changes to the mutated files to check
-whether surviving mutants increased. The HTML report lands in
-`reports/mutation/mutation.html` (git-ignored).
-
 ## Releasing
 
 Releases are automatic. Push releasable Conventional Commits (`fix:`, `feat:`,

package/dist/gtd.bundle.mjs

@@ -368486,6 +368486,9 @@ var squashing_default = '<%~ include("@header") %>\n\n<%~ include("@context", {
 // src/prompts/escalate.md
 var escalate_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nThe agent was not able to fix all errors on its own. The last error report is\nstored in `ERRORS.md` for a human to investigate.\n\nNext steps for the human developer:\n\n1. Investigate and fix errors reported in `ERRORS.md`\n2. Delete `ERRORS.md`\n3. Continue the process when you are ready\n\n<%~ include(it.tail) %>\n';
 
+// src/prompts/grilled-review.md
+var grilled_review_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %> The\nplan in `TODO.md` has converged \u2014 no open questions remain \u2014 and has been\ncommitted as `gtd: grilled`.\n\n### Human review gate\n\nThis is a human review point. Tell the user to open `TODO.md` and review the\nfinalized plan:\n\n- To **proceed**, continue with a clean working tree \u2014 the plan will be\n  decomposed into `.gtd/` work packages.\n- To **revise**, edit `TODO.md` (or sketch code) and continue \u2014 the changes\n  re-enter the grilling loop for another convergence round.\n\n<%~ include(it.tail) %>\n';
+
 // src/prompts/idle.md
 var idle_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nReport that the repository is idle \u2014 nothing to do.\n\n<%~ include(it.tail) %>\n';
 
@@ -368533,11 +368536,13 @@ eta.loadTemplate("@agentic-review", agentic_review_default);
 eta.loadTemplate("@clean", clean_default);
 eta.loadTemplate("@squashing", squashing_default);
 eta.loadTemplate("@escalate", escalate_default);
+eta.loadTemplate("@grilled-review", grilled_review_default);
 eta.loadTemplate("@idle", idle_default);
 eta.readFile = null;
 eta.resolvePath = null;
 var STATE_TEMPLATE = {
   grilled: "@decompose",
+  "grilled-review": "@grilled-review",
   planning: "@decompose",
   building: "@building",
   fixing: "@fixing",
@@ -388987,9 +388992,16 @@ var resolveGrilling = (p4, counters, head7) => {
       context: buildContext(p4, counters, "iterate")
     };
   }
+  if (head7 === "gtd: grilled") {
+    return {
+      state: "grilled",
+      autoAdvance: true,
+      context: buildContext(p4, counters)
+    };
+  }
   return {
-    state: "grilled",
-    autoAdvance: true,
+    state: "grilled-review",
+    autoAdvance: false,
     edgeAction: { kind: "commitPending", prefix: "gtd: grilled" },
     context: buildContext(p4, counters)
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {