@pmelab/gtd 2.0.0 → 2.2.0

package/README.md

@@ -67,6 +67,9 @@ gtd next --json            # ask who's up and what they should do
 See [The reference loop driver](#the-reference-loop-driver) for a full script
 implementing this protocol, and [`skills/loop/SKILL.md`](skills/loop/SKILL.md)
 for the agent-facing instructions that follow the same pinned contract.
+`gtd-loop`, installed alongside `gtd` (see below), is the packaged, ready-to-run
+implementation of that same script for anyone who doesn't want to drive the loop
+by hand.
 
 ## Installation
 
@@ -113,6 +116,12 @@ to cwd, so it refuses with a clear error if invoked from a subdirectory.
 `--jsn`) is rejected with a usage error rather than silently ignored, so a
 mistyped flag can never degrade a JSON caller to plain-text mode.
 
+One nuance to "(no mutation)": `next` and `status` never author commits or
+change workflow state, but while a human review is pending they do maintain the
+review checkout window (closing it to read state, re-arming it on the way out —
+see [Human review gate](#human-review-gate)), which transiently moves HEAD and
+the index. The working tree is never touched.
+
 ### `gtd step` / `gtd step-agent`
 
 Both drive the **same fixpoint loop** — gather → resolve → perform the returned
@@ -397,6 +406,26 @@ side can drive — agent rests and agent-driven checkpoints — reports
 cycles, a force-approved package close) chain without human involvement until an
 actual human gate is hit.
 
+`bin/gtd-loop`, installed as the `gtd-loop` binary, is the packaged
+implementation of this exact script — kept in sync with it the same way
+`skills/loop/SKILL.md` is. It additionally attempts `gtd step` (not just
+`gtd step-agent`) every iteration, so a plain rerun after you've edited a file
+at a human gate (no commit needed) picks up your edit and keeps going, and it
+halts with a diagnostic if the same state and prompt repeat with no progress
+(see `skills/loop/SKILL.md`'s "Stall detection").
+
+### Using a different agent
+
+`gtd-loop` defaults to
+`claude -p "$GTD_LOOP_PROMPT" --dangerously-skip-permissions`, but the agent
+invocation is swappable: set `GTD_LOOP_AGENT_CMD` to any shell command, and it
+runs with the prompt available as `$GTD_LOOP_PROMPT` in its environment. For
+example, to drive a different agent CLI:
+
+```bash
+GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
+```
+
 ## States & subjects overview
 
 `resolve()` lands on exactly one of **16 states**: `grilling`, `grilled`,
@@ -524,12 +553,39 @@ Once `.gtd/` is fully closed, the machine writes `.gtd/REVIEW.md` and rests at
   plus routing `gtd: done`.
 - Flipping only `- [ ]` → `- [x]` checkboxes in `.gtd/REVIEW.md` — checkbox-only
   edits are also treated as clean approval.
+- Deleting `.gtd/REVIEW.md` outright.
 
 Any **substantive** edit — to `.gtd/REVIEW.md` prose, or to the reviewed code
 itself — is feedback: `gtd(human): review` plus routing `gtd: review feedback`,
 `.gtd/REVIEW.md` removed, and `gtd next` re-emits a grilling prompt to the agent
 that inlines the human's finding.
 
+**The review diff lives in your editor.** While the gate is pending, gtd holds
+open a _review checkout window_: it saves the real head to
+`refs/gtd/review-head`, then rewinds HEAD and the index to the review base with
+`git reset --mixed`, leaving the working tree untouched. Every editor's standard
+git integration now shows the entire reviewable diff as ordinary uncommitted
+changes — SCM panel, gutter marks, per-file diffs. Review it there:
+
+- **Edit** anything (code or `.gtd/REVIEW.md` prose) → feedback.
+- **Discard a hunk** in the editor → that reversion IS the feedback: the agent
+  is re-grilled with it.
+- **Delete a surfaced file** → reject-this-file feedback.
+- Touch nothing (or tick checkboxes / delete `.gtd/REVIEW.md`) → approval.
+
+Any gtd invocation closes the window first (restoring HEAD/index exactly, so
+only your own edits remain dirty — they land as their own separate
+`gtd(human): review` commit, never mixed into the reviewed work), and
+`gtd next`/`gtd status` re-arm it on their way out. The mechanics are
+crash-safe; details and invariants in STATES.md ("The review checkout window").
+
+Caveats while a review is pending: don't push (the branch tip rests at the
+review base — the real head is safe under `refs/gtd/review-head`); commits you
+make manually survive as working-tree content and become review feedback, but
+their commit message is discarded; linked `git worktree` checkouts are
+unsupported. If you switch branches mid-review, gtd refuses to touch the foreign
+branch and prints the manual recovery command.
+
 ### Squash
 
 With `squash: true` (the default), `gtd: done` is **not** a rest — the same

package/bin/gtd-loop

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Drives the two-beat protocol (README.md "The reference loop driver") to a
+# human gate. Both mutators are attempted every iteration, refusal-tolerant:
+# whichever actor is actually awaited claims the turn (captures the human's
+# uncommitted edit after a halt, or the agent's own edit from the previous
+# iteration), the other refuses harmlessly.
+prev_state=""
+prev_prompt=""
+
+while true; do
+  gtd step --json >/dev/null 2>&1 || true
+  gtd step-agent --json >/dev/null 2>&1 || true
+
+  if ! next_json="$(gtd next --json 2>&1)"; then
+    echo "gtd-loop: could not determine the next step:" >&2
+    echo "$next_json" >&2
+    echo "Run \`gtd status\` to inspect the repo." >&2
+    exit 1
+  fi
+
+  actor="$(jq -r .actor <<<"$next_json")"
+  pending="$(jq -r .pending <<<"$next_json")"
+  state="$(jq -r .state <<<"$next_json")"
+  prompt="$(jq -r .prompt <<<"$next_json")"
+
+  if [[ "$actor" != "agent" ]]; then
+    echo "--- Your turn ($state) ---"
+    gtd next
+    exit 0
+  fi
+
+  if [[ "$pending" == "true" ]]; then
+    prev_state=""
+    prev_prompt=""
+    continue
+  fi
+
+  # Stall detection (skills/loop/SKILL.md): the same agent-owned state and
+  # prompt repeating means the last dispatch made no progress — stop rather
+  # than spin on it.
+  if [[ "$state" == "$prev_state" && "$prompt" == "$prev_prompt" ]]; then
+    echo "gtd-loop: no progress at '$state' — the agent's last turn changed nothing. Stopping to avoid spinning." >&2
+    gtd next >&2
+    exit 1
+  fi
+  prev_state="$state"
+  prev_prompt="$prompt"
+
+  # Swappable agent adapter: GTD_LOOP_AGENT_CMD lets any coding agent CLI
+  # stand in for the default, receiving the prompt via $GTD_LOOP_PROMPT.
+  cmd="${GTD_LOOP_AGENT_CMD:-}"
+  if [[ -z "$cmd" ]]; then
+    cmd='claude -p "$GTD_LOOP_PROMPT" --dangerously-skip-permissions'
+  fi
+  GTD_LOOP_PROMPT="$prompt" bash -c "$cmd"
+done

package/dist/gtd.bundle.mjs

@@ -367862,6 +367862,10 @@ var makeGitImpl = (executor, root2) => {
         (hash3) => /^[0-9a-f]{40}$/.test(hash3) ? Effect_exports.succeed(hash3) : Effect_exports.fail(new Error(`Invalid ref: ${ref}`))
       )
     ),
+    readRefOption: (ref) => exec2("git", "rev-parse", "--verify", "--quiet", ref).pipe(
+      Effect_exports.map((s5) => Option_exports.some(s5.trim())),
+      Effect_exports.catchAll(() => Effect_exports.succeed(Option_exports.none()))
+    ),
     topLevel: () => exec2("git", "rev-parse", "--show-toplevel").pipe(Effect_exports.map((s5) => s5.trim())),
     resolveDefaultBranch: () => exec2("git", "rev-parse", "--abbrev-ref", "origin/HEAD").pipe(
       Effect_exports.map((s5) => s5.trim()),
@@ -367995,7 +367999,20 @@ var makeGitImpl = (executor, root2) => {
         )
       );
     }).pipe(Effect_exports.asVoid),
-    softResetTo: (ref) => exec2("git", "reset", "--soft", ref).pipe(Effect_exports.asVoid)
+    softResetTo: (ref) => exec2("git", "reset", "--soft", ref).pipe(Effect_exports.asVoid),
+    updateRef: (ref, hash3) => exec2("git", "update-ref", ref, hash3).pipe(Effect_exports.asVoid),
+    deleteRef: (ref) => exec2("git", "update-ref", "-d", ref).pipe(
+      Effect_exports.asVoid,
+      Effect_exports.catchAll(() => Effect_exports.void)
+    ),
+    mixedResetTo: (ref) => exec2("git", "reset", "--mixed", ref).pipe(Effect_exports.asVoid),
+    restoreStagedFrom: (source2, paths) => paths.length === 0 ? Effect_exports.void : exec2("git", "restore", "--staged", `--source=${source2}`, "--", ...paths).pipe(
+      Effect_exports.asVoid,
+      // `git restore` errors when a pathspec matches nothing at either
+      // side — for an optional dir like `.gtd/` that's a no-op, not a failure.
+      Effect_exports.catchAll(() => Effect_exports.void)
+    ),
+    addIntentToAdd: () => exec2("git", "add", "--intent-to-add", ".").pipe(Effect_exports.asVoid)
   };
 };
 var makeLiveEffect = Effect_exports.gen(function* () {
@@ -389493,6 +389510,78 @@ var buildPrompt = (result, resolveModel = builtinResolveModel, output = "plain")
   return raw.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
 };
 
+// src/ReviewWindow.ts
+var REVIEW_HEAD_REF = "refs/gtd/review-head";
+var REVIEW_BASE_REF = "refs/gtd/review-base";
+var AWAITING_REVIEW_SUBJECT = ROUTING_SUBJECT["awaiting-review"];
+var subjectOf2 = (message) => message.split("\n")[0] ?? "";
+var reviewWindowBase = (history) => {
+  const beforeHead = history.slice(0, -1);
+  let lastDoneIdx = -1;
+  for (let i = 0; i < beforeHead.length; i++) {
+    if (subjectOf2(beforeHead[i].message) === ROUTING_SUBJECT.done) lastDoneIdx = i;
+  }
+  const currentCycle = beforeHead.slice(lastDoneIdx + 1);
+  let anchor;
+  let lastAwaitingReview;
+  let firstGrilling;
+  for (const c7 of currentCycle) {
+    const parsed = parseSubject(subjectOf2(c7.message));
+    if (parsed.kind === "routing" && parsed.phase === "reviewing" && parsed.param !== void 0) {
+      anchor = parsed.param;
+    }
+    if (parsed.kind === "routing" && parsed.phase === "awaiting-review") {
+      lastAwaitingReview = c7.hash;
+    }
+    if (parsed.kind === "turn" && parsed.gate === "grilling" && firstGrilling === void 0) {
+      firstGrilling = c7.hash;
+    }
+  }
+  return anchor ?? lastAwaitingReview ?? firstGrilling;
+};
+var closeReviewWindow = Effect_exports.gen(
+  function* () {
+    const git = yield* GitService;
+    const savedHead = yield* git.readRefOption(REVIEW_HEAD_REF);
+    if (Option_exports.isNone(savedHead)) return { closed: false };
+    const base = yield* git.readRefOption(REVIEW_BASE_REF);
+    if (Option_exports.isSome(base)) {
+      const onReviewedBranch = yield* git.isAncestor(base.value, "HEAD");
+      if (!onReviewedBranch) {
+        return yield* Effect_exports.fail(
+          new Error(
+            "a gtd review checkout window is open but HEAD has moved off the reviewed branch \u2014 return to it, or restore manually with `git reset --mixed refs/gtd/review-head && git update-ref -d refs/gtd/review-head && git update-ref -d refs/gtd/review-base`"
+          )
+        );
+      }
+    }
+    yield* git.mixedResetTo(REVIEW_HEAD_REF);
+    yield* git.deleteRef(REVIEW_HEAD_REF);
+    yield* git.deleteRef(REVIEW_BASE_REF);
+    return { closed: true };
+  }
+);
+var openReviewWindow = Effect_exports.gen(
+  function* () {
+    const git = yield* GitService;
+    const hasCommits = yield* git.hasCommits();
+    if (!hasCommits) return { opened: false };
+    const subject = yield* git.lastCommitSubject();
+    if (subject !== AWAITING_REVIEW_SUBJECT) return { opened: false };
+    const history = yield* git.commitHistory();
+    const base = reviewWindowBase(history);
+    if (base === void 0) return { opened: false };
+    const headHash = yield* git.resolveRef("HEAD");
+    if (base === headHash) return { opened: false };
+    yield* git.updateRef(REVIEW_BASE_REF, base);
+    yield* git.updateRef(REVIEW_HEAD_REF, headHash);
+    yield* git.mixedResetTo(base);
+    yield* git.restoreStagedFrom(REVIEW_HEAD_REF, [".gtd"]);
+    yield* git.addIntentToAdd();
+    return { opened: true };
+  }
+);
+
 // src/State.ts
 var edgeActionHandlers = {
   captureTurn: (a5) => `capture the ${a5.actor} turn as "gtd(${a5.actor}): ${a5.gate}"`,
@@ -389807,9 +389896,13 @@ function makeProgram(opts = {}) {
     const git = yield* GitService;
     const fs9 = yield* FileSystem_exports.FileSystem;
     yield* assertRunningFromRepoRoot(git, fs9);
+    yield* closeReviewWindow;
     yield* (yield* ConfigInit).ensure;
     const config2 = yield* ConfigService;
-    yield* dispatchKnownSubcommand(sub, argv, git, config2, json2, write4);
+    yield* dispatchKnownSubcommand(sub, argv, git, config2, json2, write4).pipe(
+      Effect_exports.tap(() => openReviewWindow),
+      Effect_exports.tapError(() => openReviewWindow.pipe(Effect_exports.ignore))
+    );
   }).pipe(
     json2 ? Effect_exports.catchAll(
       (error) => Effect_exports.sync(

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@pmelab/gtd",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
-    "gtd": "dist/gtd.bundle.mjs"
+    "gtd": "dist/gtd.bundle.mjs",
+    "gtd-loop": "bin/gtd-loop"
   },
   "files": [
     "dist/",
+    "bin/",
     "README.md",
     "LICENSE",
     "schema.json"