@pmelab/gtd 1.8.0 → 1.9.0

package/README.md

@@ -50,7 +50,14 @@ No config file, no setup subcommand.
 
 Run `gtd` from your repository's working directory — it prints the next prompt
 to stdout. It takes **no ref argument** — the review base is always
-auto-computed.
+auto-computed. The one exception is `gtd review <target>`: an explicit,
+on-demand human review against a chosen base (see
+[Review subcommand](#review-subcommand) below).
+
+On an idle tree outside a process (no steering files, nothing reviewable), `gtd`
+now runs a **health check** instead of stopping immediately — `gtd review` is
+the only way to start an ad-hoc review when the automatic review base yields no
+diff.
 
 ## JSON output mode
 
@@ -181,7 +188,8 @@ The complete set:
 `gtd: new task` · `gtd: grilling` · `gtd: grilled` · `gtd: planning` ·
 `gtd: building` · `gtd: errors` · `gtd: feedback` · `gtd: fixing` ·
 `gtd: package done` · `gtd: awaiting review` · `gtd: done` · `gtd: health-check`
-· `gtd: health-fix` — plus the hand-made `gtd: transport` (see below).
+· `gtd: health-fix` · `gtd: reviewing` — plus the hand-made `gtd: transport`
+(see below).
 
 The last commit subject is bucketed two ways:
 
@@ -494,9 +502,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 —
@@ -505,20 +513,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
 
@@ -738,10 +739,50 @@ When there are genuinely no open questions left, the agent writes the sentinel
 line `no open questions — run gtd to plan` and leaves **no** markers — a clean
 tree with no markers is what advances the plan to **Grilled** and decomposition.
 
-## Formatting
+## Subcommands
+
+gtd ships two subcommands: `format` and `review`.
+
+## Review subcommand
+
+```bash
+gtd review <target>
+```
+
+Starts an explicit, on-demand human review of the diff between HEAD and
+`merge-base(<target>, HEAD)`. Use this when the automatic review base yields no
+diff (idle tree outside a process) or when you want to review against a specific
+base regardless of workflow state.
+
+### Flow
+
+1. `gtd review <target>` computes the diff HEAD adds over
+   `merge-base(<target>, HEAD)`.
+2. The edge writes an empty anchor commit `gtd: reviewing` (no content — just
+   the marker).
+3. The **Clean** state writes `REVIEW.md` with the computed diff and emits the
+   normal review prompt. `--json` is accepted and enables auto-advance mode
+   (same behavior as the default command).
+4. The normal loop then drives: **Await Review** → **Done** → **Squashing**,
+   collapsing back to the `gtd: reviewing` anchor commit.
+
+### Error handling
+
+All errors exit with **code 1** and write a message to **stderr**:
+
+- **Missing target** — `gtd review` with no argument:
+  `gtd review: missing target argument`
+- **Extra arguments** — `gtd review main extra`:
+  `gtd review: too many arguments — expected one target, got: …`
+- **Unresolvable ref** — the target cannot be resolved by git:
+  `gtd review: cannot resolve ref '<target>': <error message>`
+- **Empty diff** — the merge-base diff between `<target>` and HEAD is empty
+  (nothing to review):
+  `gtd review: nothing to review (<target> diff is empty after filtering)`
+
+## Format subcommand
 
-gtd ships a `format` subcommand — the **only** subcommand — that formats a
-markdown file in place:
+`gtd format` formats a markdown file in place:
 
 ```bash
 gtd format <file>

package/dist/gtd.bundle.mjs

@@ -368477,8 +368477,8 @@ var fixing_default = '<%~ include("@header") %>\n\n<%~ include("@context", { con
 // src/prompts/agentic-review.md
 var agentic_review_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nSpawn a **reviewing subagent** using model `<%= it.model %>`. The package\'s task spec\nfiles and its cumulative diff are found below. The subagent must:\n\n1. **Read the task spec files** \u2014 they define the acceptance criteria. Every\n   requirement must be checked.\n2. **Read the package diff** \u2014 examine every hunk to determine whether the\n   implementation satisfies the spec.\n3. **Always write `FEEDBACK.md`** in the repo root:\n   - **Fully satisfies the spec** \u2192 write an **empty** `FEEDBACK.md` (zero bytes\n     or whitespace only). This empty file is the **approval** signal.\n   - **Does not fully satisfy** \u2192 write concrete, actionable findings anchored\n     to specific file and symbol names, grouped under short headings, so the fix\n     agent can act without re-reading the diff.\n4. **Do not edit source files and do not commit** \u2014 the reviewer only writes\n   `FEEDBACK.md`, left uncommitted.\n<% if (it.context.packages[0]) { %>\n<%~ include("@package", { pkg: it.context.packages[0], fenceFor: it.fenceFor }) %>\n<% } %><% if (it.context.refDiff && it.context.refDiff.trim()) { %>\n<%~ include("@diff", { heading: "Package diff", diff: it.context.refDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
 
-// src/prompts/clean.md
-var clean_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nSpawn a **planning-model subagent** using model `<%= it.model %>` to author a\n`REVIEW.md` file that will help a human to review the changes. It must:\n\n1. **Read the diff inlined below** \u2014 extract the changed hunks with their file\n   paths.\n2. **Group hunks semantically** \u2014 cluster hunks that serve the same logical\n   concern (the same feature, refactor, or fix), even across files. Aim for the\n   fewest chunks that keep the review navigable.\n3. **Write `REVIEW.md`** in the repo root in this format:\n\n   ```markdown\n   # Review: <short-hash>\n\n   <!-- base: <full-hash> -->\n\n   ## <Chunk Title>\n\n   <What this chunk changes and why>\n\n   - [ ] ./path/to/file.ts#42\n   - [ ] ./path/to/file.ts#99\n\n   ## <Another Chunk Title>\n\n   <Explanation>\n\n   - [ ] ./path/to/another.ts#1\n   ```\n\n   - `<short-hash>` is the first 7 characters of the review base SHA;\n     `<full-hash>` is the full SHA. Both are read from the `Review base:` line /\n     diff label in the prompt context.\n   - Chunk titles are short imperative phrases (\u2264 6 words).\n   - Explanations describe _what_ changed and _why_, not just where.\n   - File pointers are relative, prefixed with `./`; the line numbers (`#42`)\n     are creation-time hints that will drift \u2014 not authoritative.\n   - Checkboxes (`- [ ]`) signal approval \u2014 ticking them (with no other edits)\n     counts as approving the review (`gtd: done`). Only non-checkbox edits to\n     `REVIEW.md` (or any code edits) are treated as a change-request.\n   - The user checks off or edits items in place as they work through the\n     review; there is no separate Resolved section.\n\n4. Leave `REVIEW.md` **uncommitted**, the outer loop will process it.\n<% if (it.context.refDiff && it.context.refDiff.trim()) { %>\n<%= it.context.reviewBase !== undefined ? "\\nReview base: " + it.context.reviewBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Changes to review (`git diff " + (it.context.reviewBase !== undefined ? it.context.reviewBase : "<base>") + " HEAD`)", diff: it.context.refDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
+// src/prompts/review.md
+var review_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nSpawn a **planning-model subagent** using model `<%= it.model %>` to author a\n`REVIEW.md` file that will help a human to review the changes. It must:\n\n1. **Read the diff inlined below** \u2014 extract the changed hunks with their file\n   paths.\n2. **Group hunks semantically** \u2014 cluster hunks that serve the same logical\n   concern (the same feature, refactor, or fix), even across files. Aim for the\n   fewest chunks that keep the review navigable.\n3. **Write `REVIEW.md`** in the repo root in this format:\n\n   ```markdown\n   # Review: <short-hash>\n\n   <!-- base: <full-hash> -->\n\n   ## <Chunk Title>\n\n   <What this chunk changes and why>\n\n   - [ ] ./path/to/file.ts#42\n   - [ ] ./path/to/file.ts#99\n\n   ## <Another Chunk Title>\n\n   <Explanation>\n\n   - [ ] ./path/to/another.ts#1\n   ```\n\n   - `<short-hash>` is the first 7 characters of the review base SHA;\n     `<full-hash>` is the full SHA. Both are read from the `Review base:` line /\n     diff label in the prompt context.\n   - Chunk titles are short imperative phrases (\u2264 6 words).\n   - Explanations describe _what_ changed and _why_, not just where.\n   - File pointers are relative, prefixed with `./`; the line numbers (`#42`)\n     are creation-time hints that will drift \u2014 not authoritative.\n   - Checkboxes (`- [ ]`) signal approval \u2014 ticking them (with no other edits)\n     counts as approving the review (`gtd: done`). Only non-checkbox edits to\n     `REVIEW.md` (or any code edits) are treated as a change-request.\n   - The user checks off or edits items in place as they work through the\n     review; there is no separate Resolved section.\n\n4. Leave `REVIEW.md` **uncommitted**, the outer loop will process it.\n<% if (it.context.refDiff && it.context.refDiff.trim()) { %>\n<%= it.context.reviewBase !== undefined ? "\\nReview base: " + it.context.reviewBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Changes to review (`git diff " + (it.context.reviewBase !== undefined ? it.context.reviewBase : "<base>") + " HEAD`)", diff: it.context.refDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
 
 // src/prompts/squashing.md
 var squashing_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nThe process is **approved and done**. Your job is to author a clean\nconventional-commits squash message and hand it off to the harness.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` commits. Look for changes to `TODO.md`\n\u2014 specifically the `## Captured input (grilling)` sections and any edits to plan\ntext. Extract **key decisions, trade-offs, and design choices** made during\ngrilling rounds. These will appear in the commit body so the history is\nself-documenting.\n\n### Step 2 \u2014 Draft the commit message\n\nDraft ONE conventional-commits message:\n\n```\ntype(scope): subject\n\nbody (explain the why \u2014 motivation, trade-offs, key decisions from grilling)\n```\n\n- **type**: `feat` / `fix` / `refactor` / `chore` / `docs` / `test`\n- **subject**: imperative mood, \u2264 72 characters, lowercase after the colon\n- **body**: include the important decisions / trade-offs from grilling sessions.\n  Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Write SQUASH_MSG.md and hand off\n\nWrite the commit message (plain text, no markdown wrapper) to `SQUASH_MSG.md` in\nthe repo root, then leave it uncommitted \u2014 the harness handles the squash commit\non the next cycle once it sees `SQUASH_MSG.md`.\n\n**Do not run `git reset --soft` or `git commit` yourself** \u2014 the harness handles\nthe squash commit.\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nSquash base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
@@ -368532,7 +368532,7 @@ eta.loadTemplate("@decompose", decompose_default);
 eta.loadTemplate("@building", building_default);
 eta.loadTemplate("@fixing", fixing_default);
 eta.loadTemplate("@agentic-review", agentic_review_default);
-eta.loadTemplate("@clean", clean_default);
+eta.loadTemplate("@review", review_default);
 eta.loadTemplate("@squashing", squashing_default);
 eta.loadTemplate("@escalate", escalate_default);
 eta.loadTemplate("@idle", idle_default);
@@ -368544,7 +368544,7 @@ var STATE_TEMPLATE = {
   building: "@building",
   fixing: "@fixing",
   "agentic-review": "@agentic-review",
-  clean: "@clean",
+  clean: "@review",
   squashing: "@squashing",
   escalate: "@escalate",
   idle: "@idle",
@@ -385730,7 +385730,7 @@ function clean(original, cloned) {
   }
   return cloned;
 }
-var clean_default2 = clean;
+var clean_default = clean;
 function printFrontMatter({ node }) {
   return node.raw;
 }
@@ -385835,7 +385835,7 @@ function normalizePrinter(printer2) {
   if (originalCleanFunction && frontMatterSupport.massageAstNode) {
     massageAstNode = new Proxy(originalCleanFunction, {
       apply(target, thisArgument, argumentsList) {
-        clean_default2(...argumentsList);
+        clean_default(...argumentsList);
         return Reflect.apply(target, thisArgument, argumentsList);
       }
     });
@@ -388279,6 +388279,7 @@ var PACKAGE_DONE_SUBJECT = "gtd: package done";
 var AWAITING_REVIEW_SUBJECT = "gtd: awaiting review";
 var DONE_SUBJECT = "gtd: done";
 var REVIEW_FEEDBACK_SUBJECT = "gtd: review feedback";
+var REVIEWING_SUBJECT = "gtd: reviewing";
 var SQUASH_MSG_FILE = "SQUASH_MSG.md";
 var STEERING_FILES = [
   TODO_FILE,
@@ -388577,7 +388578,7 @@ var gatherEvents = () => (
         const squashCycle = squashHistory.slice(prevDoneIdx + 1, lastDoneIdxForSquash + 1);
         let startIdx = -1;
         for (let i = squashCycle.length - 1; i >= 0; i--) {
-          if (subjectOf(squashCycle[i]) === NEW_TASK_SUBJECT) {
+          if (subjectOf(squashCycle[i]) === NEW_TASK_SUBJECT || subjectOf(squashCycle[i]) === REVIEWING_SUBJECT) {
             startIdx = i;
             break;
           }
@@ -388684,6 +388685,15 @@ var captureAndRevert = (git, subject, onRegen) => Effect_exports.gen(function* (
   yield* git.revertNoCommit("HEAD");
   return captured;
 });
+var reviewAgainst = (target) => Effect_exports.gen(function* () {
+  const git = yield* GitService;
+  const targetHash = yield* git.resolveRef(target);
+  const mergeBase = yield* git.mergeBase(target, "HEAD");
+  const mergeBaseHash = Option_exports.isNone(mergeBase) || mergeBase.value === targetHash ? targetHash : mergeBase.value;
+  const refDiff = yield* git.diffRef(mergeBaseHash, WORKFLOW_FILE_EXCLUDES);
+  if (refDiff.trim().length === 0) return void 0;
+  return { reviewBase: mergeBaseHash, refDiff };
+});
 var perform = (action) => (
   // fallow-ignore-next-line complexity
   Effect_exports.gen(function* () {
@@ -389198,6 +389208,20 @@ var resolve4 = (events) => {
   if (p4.todoExists) return resolveGrilling(p4, counters, head7);
   return resolveCleanOrIdle(p4, counters, head7) ?? corrupt();
 };
+var cleanResult = (args2) => ({
+  state: "clean",
+  autoAdvance: args2.autoAdvance,
+  context: {
+    ...buildContext(
+      {
+        ...DEFAULT_PAYLOAD,
+        reviewBase: args2.reviewBase,
+        refDiff: args2.refDiff
+      },
+      { testFixCount: 0, reviewFixCount: 0, healthFixCount: 0 }
+    )
+  }
+});
 
 // src/State.ts
 var EDGE_ONLY_STATES2 = /* @__PURE__ */ new Set([
@@ -389257,10 +389281,6 @@ function makeProgram(opts = {}) {
       yield* formatFile(args2[0]);
       return;
     }
-    if (sub !== void 0) {
-      return yield* Effect_exports.fail(new Error(`unknown command '${sub}'`));
-    }
-    const config2 = yield* ConfigService;
     const git = yield* GitService;
     const fs9 = yield* FileSystem_exports.FileSystem;
     const topLevel = yield* git.topLevel();
@@ -389273,6 +389293,50 @@ function makeProgram(opts = {}) {
         )
       );
     }
+    const config2 = yield* ConfigService;
+    if (sub === "review") {
+      const args2 = argv.slice(3).filter((a5) => a5.length > 0 && !a5.startsWith("--"));
+      if (args2.length === 0) {
+        return yield* Effect_exports.fail(new Error("gtd review: missing target argument"));
+      }
+      if (args2.length > 1) {
+        return yield* Effect_exports.fail(
+          new Error(
+            `gtd review: too many arguments \u2014 expected one target, got: ${args2.join(", ")}`
+          )
+        );
+      }
+      const target = args2[0];
+      const reviewResult = yield* reviewAgainst(target).pipe(
+        Effect_exports.catchAll(
+          (error) => Effect_exports.fail(new Error(`gtd review: cannot resolve ref '${target}': ${error.message}`))
+        )
+      );
+      if (reviewResult === void 0) {
+        return yield* Effect_exports.fail(
+          new Error(`gtd review: nothing to review (${target} diff is empty after filtering)`)
+        );
+      }
+      const { reviewBase, refDiff } = reviewResult;
+      yield* git.commitAllWithPrefix(REVIEWING_SUBJECT);
+      const result = cleanResult({ reviewBase, refDiff, autoAdvance: json2 });
+      const builtPrompt = buildPrompt(result, config2.resolveModel, json2 ? "json" : "plain");
+      if (json2) {
+        write4(
+          JSON.stringify({
+            state: result.state,
+            autoAdvance: result.autoAdvance,
+            prompt: builtPrompt
+          }) + "\n"
+        );
+      } else {
+        write4(builtPrompt);
+      }
+      return;
+    }
+    if (sub !== void 0) {
+      return yield* Effect_exports.fail(new Error(`unknown command '${sub}'`));
+    }
     let hops = 0;
     while (true) {
       hops += 1;

package/package.json

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