@pmelab/gtd 2.1.0 → 2.2.0

package/README.md

@@ -116,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
@@ -547,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/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,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "2.1.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": {