@pmelab/gtd 7.1.0 → 7.1.1

package/README.md

@@ -76,8 +76,8 @@ over — a `workflow:` is the whole definition). See
 
 gtd is a small **pattern machine**: named states, each awaiting one actor and
 carrying one piece of content (a script, a prompt, a message, or a squash commit
-template), with an ordered set of change-patterns routing to the next state.
-Four commands drive it:
+template), with an ordered set of change-patterns routing to the next state. A
+handful of commands drive it:
 
 - **`gtd step <actor>`** — authenticate as `<actor>` and perform the one
   transition the pending changes match.
@@ -91,6 +91,9 @@ Four commands drive it:
 - **`gtd fix`** — start a brand new process that goes straight into repairing
   the current failing tests, then runs the shared review/squash tail (a no-op if
   the suite is already green).
+- **`gtd abandon`** — end the process underway without completing it: rewind to
+  the commit it started from, keeping everything it produced as uncommitted
+  changes (nothing is discarded).
 - **`gtd visualize`** — serve an interactive diagram of the active workflow on a
   local web server (the main flow, its sub-machines, and per-state details).
 

package/dist/gtd.bundle.mjs

@@ -191805,7 +191805,7 @@ const renderDiff = (files) => {
 };
 //#endregion
 //#region src/Git.ts
-const EMPTY_TREE$2 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const EMPTY_TREE$3 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 /**
 * Parse `git diff --name-status` output into `{ path, status }` pairs.
 * Status codes: A (added), D (deleted), M (modified), R (renamed), C (copied), etc.
@@ -191936,7 +191936,7 @@ const makeGitImpl = (executor, root) => {
 		readFileAtRef: (ref, path) => exec("git", "show", `${ref}:${path}`),
 		commitDiff: (hash, exclude = []) => gen(function* () {
 			yield* exec("git", "rev-parse", "--verify", hash);
-			const parent = yield* exec("git", "rev-parse", "--verify", `${hash}~1`).pipe(map$4((s) => s.trim()), catchAll(() => succeed$3(EMPTY_TREE$2)));
+			const parent = yield* exec("git", "rev-parse", "--verify", `${hash}~1`).pipe(map$4((s) => s.trim()), catchAll(() => succeed$3(EMPTY_TREE$3)));
 			const nameStatusOut = yield* exec("git", "diff", "--name-status", parent, hash).pipe(catchAll(() => succeed$3("")));
 			const allPaths = parseNameStatus(nameStatusOut);
 			const filtered = applyExcludes(allPaths, exclude);
@@ -192578,7 +192578,7 @@ const renderModeCommand = (template, context) => eta.renderString(template, cont
 * one commit (or one squash). A caller that wants several transitions issues
 * several invocations.
 */
-const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const EMPTY_TREE$2 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const subjectOf$1 = (message) => (message.split("\n")[0] ?? "").trim();
 const COST_TRAILER_PREFIX = "Gtd-Cost: ";
 const COST_TRAILER_RE = /^Gtd-Cost:[ \t]*([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+?))?[ \t]*$/gm;
@@ -192674,8 +192674,8 @@ const pendingChanges = (git) => git.changedPaths().pipe(map$4((entries) => entri
 const computeProcessRun = (git, def) => gen(function* () {
 	if (!(yield* git.hasCommits())) return {
 		startHash: "",
-		startParentHash: EMPTY_TREE$1,
-		diffBase: EMPTY_TREE$1,
+		startParentHash: EMPTY_TREE$2,
+		diffBase: EMPTY_TREE$2,
 		trace: [],
 		costEntries: []
 	};
@@ -192691,7 +192691,7 @@ const computeProcessRun = (git, def) => gen(function* () {
 	const processCommits = history.slice(startIdx);
 	const trace = processCommits.map((h) => parseStateSubject(subjectOf$1(h.message)).state);
 	const costEntries = parseCostTrailers(processCommits.map((h) => h.message));
-	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE$1;
+	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE$2;
 	return {
 		startHash: startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash,
 		startParentHash,
@@ -192908,25 +192908,45 @@ const executeDecision = (git, run, decision, context, cost, model) => gen(functi
 * every state subcommand:
 *
 * - `closeReviewWindow` runs BEFORE anything reads or mutates state, keyed
-*   solely on `refs/gtd/review-head` existing: `git reset --mixed
-*   refs/gtd/review-head` restores HEAD/index exactly, leaving only the
-*   reviewer's own edits dirty (captured by the resting state's own `on`
-*   patterns like any other pending change). The pure machine therefore never
-*   sees the window.
+*   solely on `REVIEW_HEAD_REF` existing: `git reset --mixed <that ref>`
+*   restores HEAD/index exactly, leaving only the reviewer's own edits dirty
+*   (captured by the resting state's own `on` patterns like any other pending
+*   change). The pure machine therefore never sees the window.
 * - `openReviewWindow` runs AFTER the subcommand finishes and self-guards on
 *   the resolved rest declaring `reviewWindow: true`: it saves HEAD to
-*   `refs/gtd/review-head` (the base to `refs/gtd/review-base`), then `git
-*   reset --mixed <base>`. It re-arms after read-only commands (`gtd next` /
-*   `gtd status`) and refused invocations too, so the editor's diff view stays
-*   consistent no matter which command the loop last ran.
+*   `REVIEW_HEAD_REF` (the base to `REVIEW_BASE_REF`), then `git reset --mixed
+*   <base>`. It re-arms after read-only commands (`gtd next` / `gtd status`)
+*   and refused invocations too, so the editor's diff view stays consistent no
+*   matter which command the loop last ran.
 *
 * Every open/close step is idempotent under re-entry, so a crash at any point
 * is recovered by the next invocation's close (the saved ref also keeps the
 * real head GC-reachable for the window's whole lifetime).
 */
-const REVIEW_HEAD_REF = "refs/gtd/review-head";
-const REVIEW_BASE_REF = "refs/gtd/review-base";
-const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/**
+* The window's two state refs live in git's PER-WORKTREE `refs/worktree/*`
+* namespace, so linked worktrees sharing one `.git` (`git worktree add`) each
+* get their OWN window: a review resting in one worktree is invisible to — and
+* un-clobberable by — every other one, and git drops the refs with the
+* worktree.
+*
+* gtd ≤ 7.1 kept them in the SHARED `refs/gtd/*` namespace (the legacy names
+* below), which made a second worktree's very first gtd invocation close the
+* FIRST worktree's window: its `git reset --mixed` moved the second worktree's
+* branch onto the other worktree's saved head, and every later invocation
+* refused with "a process is already underway" (issue #118).
+*/
+const REVIEW_HEAD_REF = "refs/worktree/gtd/review-head";
+const REVIEW_BASE_REF = "refs/worktree/gtd/review-base";
+/**
+* The pre-7.2 SHARED refs. gtd never writes them any more; `closeReviewWindow`
+* only reads them to finish a window an older gtd left open across the upgrade
+* — and only when HEAD is still contained in the saved head, since a shared ref
+* may belong to a sibling worktree (see `openWindowRefs`).
+*/
+const LEGACY_REVIEW_HEAD_REF = "refs/gtd/review-head";
+const LEGACY_REVIEW_BASE_REF = "refs/gtd/review-base";
+const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const subjectOf = (message) => (message.split("\n")[0] ?? "").trim();
 /**
 * The diff base while the window is open: the hash of the most-recent
@@ -192945,28 +192965,63 @@ const reviewBaseHash = (git, def, run) => gen(function* () {
 	}
 	return base;
 });
+/** The manual-recovery incantation every close refusal ends with. */
+const manualRecovery = (refs) => `\`git reset --mixed ${refs.headRef} && git update-ref -d ${refs.headRef} && git update-ref -d ${refs.baseRef}\``;
+/**
+* Which ref pair (if any) records an open window: this worktree's own
+* `refs/worktree/gtd/*` pair first, falling back to the pre-7.2 shared
+* `refs/gtd/*` pair so an upgrade mid-window still closes cleanly.
+*/
+const openWindowRefs = (git) => gen(function* () {
+	const scoped = yield* git.readRefOption(REVIEW_HEAD_REF);
+	if (isSome(scoped)) return some({
+		headRef: REVIEW_HEAD_REF,
+		baseRef: REVIEW_BASE_REF,
+		headHash: scoped.value,
+		legacy: false
+	});
+	const legacy = yield* git.readRefOption(LEGACY_REVIEW_HEAD_REF);
+	if (isNone(legacy)) return none$4();
+	return some({
+		headRef: LEGACY_REVIEW_HEAD_REF,
+		baseRef: LEGACY_REVIEW_BASE_REF,
+		headHash: legacy.value,
+		legacy: true
+	});
+});
 /**
 * Restore the real head if a review checkout window is open; no-op otherwise.
-* Keyed on `refs/gtd/review-head` existence, NOT on any config or machine
-* state, so it always runs first and the machine never sees the window.
+* Keyed on the saved-head ref's existence (see `openWindowRefs`), NOT on any
+* config or machine state, so it always runs first and the machine never sees
+* the window.
 *
 * Fails loudly — refs left in place — when HEAD is no longer on the reviewed
 * branch (the base is not an ancestor of HEAD, e.g. after a branch switch): a
 * mixed reset there would rewrite the wrong branch's tip. Manual commits on
 * top of the base pass the guard: the reset keeps their content in the working
 * tree, where the next turn's capture picks it up as review feedback.
+*
+* A window found under the LEGACY shared refs gets one extra guard: a shared
+* ref may have been written by a sibling worktree, so the close only proceeds
+* when HEAD is contained in the saved head — the shape a window this worktree
+* opened itself has. Anything else refuses with the manual recovery rather
+* than resetting this branch onto another worktree's work (issue #118).
 */
 const closeReviewWindow = gen(function* () {
 	const git = yield* GitService;
-	const savedHead = yield* git.readRefOption(REVIEW_HEAD_REF);
-	if (isNone(savedHead)) return { closed: false };
-	const base = yield* git.readRefOption(REVIEW_BASE_REF);
-	if (isSome(base) && base.value !== EMPTY_TREE) {
-		if (!(yield* git.isAncestor(base.value, "HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error("a gtd review checkout window is open but HEAD has moved off the reviewed branch — 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);
+	const open = yield* openWindowRefs(git);
+	if (isNone(open)) return { closed: false };
+	const refs = open.value;
+	const base = yield* git.readRefOption(refs.baseRef);
+	if (isSome(base) && base.value !== EMPTY_TREE$1) {
+		if (!(yield* git.isAncestor(base.value, "HEAD"))) return yield* fail$2(/* @__PURE__ */ new Error(`a gtd review checkout window is open but HEAD has moved off the reviewed branch — return to it, or restore manually with ${manualRecovery(refs)}`));
+	}
+	if (refs.legacy) {
+		if (!(yield* git.isAncestor("HEAD", refs.headHash))) return yield* fail$2(/* @__PURE__ */ new Error(`a review checkout window is recorded under the shared ${LEGACY_REVIEW_HEAD_REF} (written by gtd 7.1 or older) but it does not belong to this worktree — HEAD is not contained in it. gtd now scopes the window per worktree (${REVIEW_HEAD_REF}); in the worktree that owns it, run ${manualRecovery(refs)}`));
+	}
+	yield* git.mixedResetTo(refs.headRef);
+	yield* git.deleteRef(refs.headRef);
+	yield* git.deleteRef(refs.baseRef);
 	return { closed: true };
 });
 /**
@@ -192996,7 +193051,7 @@ const openReviewWindow = gen(function* () {
 	const run = yield* computeProcessRun(git, def);
 	const base = (yield* reviewBaseHash(git, def, run)) ?? run.diffBase;
 	const headHash = yield* git.resolveRef("HEAD");
-	if (base === EMPTY_TREE || base === headHash) return { opened: false };
+	if (base === EMPTY_TREE$1 || base === headHash) return { opened: false };
 	yield* git.updateRef(REVIEW_BASE_REF, base);
 	yield* git.updateRef(REVIEW_HEAD_REF, headHash);
 	yield* git.mixedResetTo(base);
@@ -205112,6 +205167,11 @@ Commands:
                    state (fixEntry: true) that goes straight into repairing the
                    current failing tests. Requires a clean tree resting at the
                    workflow's initial state
+  abandon          End the process currently underway without completing it:
+                   close any open review checkout window, then rewind HEAD to
+                   the commit the process started from, keeping everything it
+                   produced as uncommitted changes. A no-op when no process is
+                   underway
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   status           Print the resolved rest's state/actor and which declared
@@ -205375,7 +205435,7 @@ const runReviewCommand = (argv, json, write) => gen(function* () {
 	const commitish = args[0];
 	const git = yield* GitService;
 	const rest = yield* resolveRest();
-	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: a process is already underway (resting at "${rest.state}") — finish or abandon it before starting a review`));
+	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd review: a process is already underway (resting at "${rest.state}") — finish it, or run \`gtd abandon\`, before starting a review`));
 	if ((yield* pendingChanges(git)).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: the working tree must be clean before starting a review"));
 	const entryState = reviewEntryStateOf(rest.def);
 	if (entryState === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd review: the active workflow declares no review entry state"));
@@ -205412,7 +205472,7 @@ const runFixCommand = (argv, json, write) => gen(function* () {
 	yield* rejectExtraArgs("fix", argv);
 	const git = yield* GitService;
 	const rest = yield* resolveRest();
-	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd fix: a process is already underway (resting at "${rest.state}") — finish or abandon it before starting a fix`));
+	if (rest.state !== initialStateOf(rest.def)) return yield* fail$2(/* @__PURE__ */ new Error(`gtd fix: a process is already underway (resting at "${rest.state}") — finish it, or run \`gtd abandon\`, before starting a fix`));
 	if ((yield* pendingChanges(git)).length > 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd fix: the working tree must be clean before starting a fix"));
 	const entryState = fixEntryStateOf(rest.def);
 	if (entryState === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd fix: the active workflow declares no fix entry state"));
@@ -205424,6 +205484,53 @@ const runFixCommand = (argv, json, write) => gen(function* () {
 	}) + "\n");
 	else write(`committed: ${subject}\n`);
 });
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/**
+* `gtd abandon`: end the process currently underway WITHOUT completing it,
+* returning the machine to the workflow's initial state — the recovery path out
+* of a process nobody is going to finish (the refusals of `gtd review`/`gtd fix`
+* name it: "finish or abandon it before starting a review").
+*
+* NOTHING is discarded. The shared bracket in `makeProgram` has already closed
+* any open review checkout window (so HEAD is the real head), and abandon then
+* `git reset --mixed`es HEAD to the commit the process started from
+* (`computeProcessRun`'s `startParentHash` — the same boundary a squash resets
+* to). Every turn commit the process wrote is dropped, and everything they
+* carried — the code, the `.gtd/` steering files — stays in the working tree as
+* uncommitted changes for the human to keep, re-commit, or discard with
+* ordinary git.
+*
+* Idempotent: resting at the initial state (a plain non-gtd branch, or a
+* just-squashed cycle) is a no-op SUCCESS, not a refusal — a recovery command
+* that fails when there is nothing to recover is a worse tool. The one refusal
+* is a process whose first commit is the repository's own root commit: there is
+* no earlier commit to rewind to.
+*/
+const runAbandonCommand = (argv, json, write) => gen(function* () {
+	yield* rejectExtraArgs("abandon", argv);
+	const git = yield* GitService;
+	const rest = yield* resolveRest();
+	const initial = initialStateOf(rest.def);
+	if (rest.state === initial) {
+		if (json) write(JSON.stringify({
+			state: initial,
+			abandoned: false
+		}) + "\n");
+		else write(`no gtd process is underway (resting at "${initial}") — nothing to abandon\n`);
+		return;
+	}
+	const run = yield* computeProcessRun(git, rest.def);
+	if (run.startParentHash === EMPTY_TREE) return yield* fail$2(/* @__PURE__ */ new Error(`gtd abandon: the process underway (resting at "${rest.state}") starts at the repository's first commit — there is no earlier commit to rewind to`));
+	yield* git.mixedResetTo(run.startParentHash);
+	const subject = yield* git.lastCommitSubject();
+	if (json) write(JSON.stringify({
+		state: initial,
+		abandoned: true,
+		from: rest.state,
+		head: run.startParentHash
+	}) + "\n");
+	else write(`abandoned the process resting at "${rest.state}" — HEAD is back at ${run.startParentHash.slice(0, 7)} ("${subject}"), resting at "${initial}".\nEverything the process produced is kept as uncommitted changes (\`git status\`); discard them with \`git checkout -- . && git clean -fd .gtd\` for a clean tree.\n`);
+});
 /**
 * The self-validation instruction gtd APPENDS to a `prompt` rest that declares
 * both `file:` and `mode:` — i.e. a state whose actor hands over a steering
@@ -205852,6 +205959,7 @@ const KNOWN_SUBCOMMANDS = [
 	"step",
 	"review",
 	"fix",
+	"abandon",
 	"next",
 	"status",
 	"validate"
@@ -205923,6 +206031,7 @@ const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 		case "step": return runStepCommand(argv, json, write, cost, model);
 		case "review": return runReviewCommand(argv, json, write);
 		case "fix": return runFixCommand(argv, json, write);
+		case "abandon": return runAbandonCommand(argv, json, write);
 		case "next": return runNextCommand(json, write);
 		case "status": return runStatusCommand(argv, json, write);
 		case "validate": return runValidateCommand(argv, json, write);

package/docs/cli.md

@@ -25,6 +25,11 @@ Commands:
                    state (fixEntry: true) that goes straight into repairing the
                    current failing tests. Requires a clean tree resting at the
                    workflow's initial state
+  abandon          End the process currently underway without completing it:
+                   close any open review checkout window, then rewind HEAD to
+                   the commit the process started from, keeping everything it
+                   produced as uncommitted changes. A no-op when no process is
+                   underway
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   status           Print the resolved rest's state/actor and which declared
@@ -167,7 +172,8 @@ written):
 
 - the machine currently resting at the workflow's **initial state** (a plain
   non-gtd branch resolves there via the inert-subject rule — the normal case; a
-  process already underway refuses);
+  process already underway refuses — finish it, or
+  [`gtd abandon`](#gtd-abandon---json) it);
 - a **clean working tree**;
 - the active workflow declaring a **`reviewEntry: true`** state (otherwise:
   `gtd review: the active workflow declares no review entry state`);
@@ -213,7 +219,8 @@ Requires, in order (any failure is a plain refusal — exit non-zero, nothing
 written):
 
 - the machine currently resting at the workflow's **initial state** (a process
-  already underway refuses);
+  already underway refuses — finish it, or [`gtd abandon`](#gtd-abandon---json)
+  it);
 - a **clean working tree**;
 - the active workflow declaring a **`fixEntry: true`** state (otherwise:
   `gtd fix: the active workflow declares no fix entry state`).
@@ -232,6 +239,62 @@ unified template the fix-entry state is `fix-check`: a red suite drops into the
 shared `fixing` loop and out through the review + squash tail; a green suite is
 a no-op back to `idle`.
 
+## `gtd abandon [--json]`
+
+Ends the process currently underway **without completing it** — the way out of a
+process nobody is going to finish, and the command `gtd review`/`gtd fix` name
+when they refuse ("finish it, or run `gtd abandon`, before starting a review").
+A workflow's own exit is its squash finale
+([STATES.md §8](../STATES.md#8-the-squash-lifecycle)); this is the human's, and
+it targets the same boundary:
+
+1. any open **review checkout window** is closed first (the bracket every state
+   subcommand runs — see
+   [STATES.md §11](../STATES.md#11-the-review-checkout-window)), so the rewind
+   starts from the real head, not the rewound base;
+2. HEAD is `git reset --mixed`ed to the commit the process started from (its
+   start parent — the same target a squash resets to).
+
+**Nothing is discarded.** Every turn commit the process wrote is dropped, and
+everything they carried — the code, the `.gtd/` steering files — stays in the
+working tree as uncommitted changes for you to keep, re-commit, or throw away
+with ordinary git:
+
+```
+abandoned the process resting at "await-review" — HEAD is back at 1a2b3c4
+("feat: add calculator"), resting at "idle".
+Everything the process produced is kept as uncommitted changes (`git status`);
+discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.
+```
+
+Takes no positional argument (extra arguments are a usage error). Resting at the
+workflow's initial state is a **no-op success**, not a refusal — a recovery
+command that fails when there is nothing to recover is a worse tool:
+
+```
+no gtd process is underway (resting at "idle") — nothing to abandon
+```
+
+The one refusal is a process whose first commit is the repository's own root
+commit: there is no earlier commit to rewind to, so its commits have to be
+removed by hand.
+
+`--json` emits `{state, abandoned, from, head}` — `state` is the initial state
+the machine returns to, `abandoned` whether anything was rewound, and (only when
+it was) `from` the state the abandoned process rested at plus `head` the full
+hash HEAD now points at:
+
+```json
+{
+  "state": "idle",
+  "abandoned": true,
+  "from": "await-review",
+  "head": "1a2b3c4…"
+}
+```
+
+The no-op reports `{"state": "idle", "abandoned": false}` and still exits 0.
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -495,3 +558,11 @@ the plain-text one.
   `--help`/`--version` (and the `help`/`version` subcommands), `lsp`, and
   `visualize` skip this guard entirely (`visualize` still reads the `.gtdrc`
   workflow, but needs no git state).
+- **Linked worktrees are independent.** N `git worktree` worktrees of one
+  repository (sharing a single `.git`) each run their own gtd process: state is
+  derived from that worktree's own HEAD, and the review checkout window's refs
+  live in git's per-worktree `refs/worktree/gtd/*` namespace, so a review
+  resting in one worktree neither blocks nor rewrites any other
+  ([STATES.md §11](../STATES.md#11-the-review-checkout-window)). This holds from
+  7.2 on; gtd ≤ 7.1 kept the window under the shared `refs/gtd/*` refs, where
+  the first worktree to open one clobbered every sibling's branch.

package/docs/configuration.md

@@ -449,9 +449,10 @@ The unified template enables `reviewWindow: true` on `await-review` and marks
 `review-deciding` `reviewBase: true`, so the first review covers the whole cycle
 but each subsequent feedback round's window narrows to `last-review..HEAD`. The
 pure engine never observes an open window — it is opened/closed entirely at the
-edge; the real head is preserved under `refs/gtd/review-head` (the base under
-`refs/gtd/review-base`) for the window's lifetime. See
-[STATES.md §11](../STATES.md) for the full lifecycle.
+edge; the real head is preserved under `refs/worktree/gtd/review-head` (the base
+under `refs/worktree/gtd/review-base`) for the window's lifetime — git's
+per-worktree ref namespace, so linked worktrees of one repository each get their
+own window. See [STATES.md §11](../STATES.md) for the full lifecycle.
 
 ### `reviewEntry:` — the review entry point (`gtd review <commitish>`)
 

package/docs/loop.md

@@ -34,6 +34,19 @@ capture for the human as its opening move (see below), so re-launching the loop
 is the only thing the human ever does — at a gate they edit and re-run, and the
 loop picks their change up.
 
+**A `"message"` rest is a real handoff, not a slow beat.** No driver signs off
+for the human: in the bundled workflow the loop runs the whole cycle unattended
+up to `await-review` and then STOPS there with the review checkout window open
+(the reviewable diff surfaced as uncommitted changes — see
+[STATES.md §11](../STATES.md#11-the-review-checkout-window)). Advancing takes a
+human edit to `.gtd/REVIEW.md`: ticking every box with **no** comment signs off
+into the squash finale, while any comment (a note, or a code edit of your own)
+is feedback that routes into another build + re-review round. Re-launching the
+loop after that edit picks the decision up. Until then the loop halts on every
+run — that is the contract, not a stall. A review nobody is going to finish is
+ended with [`gtd abandon`](cli.md#gtd-abandon---json), which drops the process's
+commits and keeps their content as uncommitted changes.
+
 ```bash
 gtd next --json   # ask who's up and what they should do
 ```

package/docs/upgrading.md

@@ -159,6 +159,42 @@ loudly at load time rather than silently misinterpreting.
 or agent harness, upgrading the `gtd` binary also means re-copying that skill
 from this release.
 
+## 7.2: the review checkout window is now per worktree
+
+The review checkout window's two refs moved from the SHARED `refs/gtd/*`
+namespace to git's PER-WORKTREE `refs/worktree/*` one:
+
+| before (≤ 7.1)         | from 7.2                        |
+| ---------------------- | ------------------------------- |
+| `refs/gtd/review-head` | `refs/worktree/gtd/review-head` |
+| `refs/gtd/review-base` | `refs/worktree/gtd/review-base` |
+
+Nothing in a `.gtdrc` or a workflow definition references those names, so **no
+config change is needed**. What changes is behaviour in a repository checked out
+as several linked worktrees (`git worktree add`, one `.git` shared between
+them): each worktree now has its own window, so a review resting in one no
+longer "closes" from another — which, on the shared refs, mixed-reset that other
+worktree's branch onto the reviewing worktree's saved head and left every
+sibling refusing with "a process is already underway".
+
+A window an OLDER gtd left open across the upgrade still closes from the legacy
+refs, so an in-flight review in a single-worktree repo needs no attention. In a
+multi-worktree repo gtd cannot tell which worktree a shared ref belongs to, so
+it closes only when HEAD is contained in the saved head and otherwise refuses
+with the exact recovery commands — run them in the worktree that owns the
+window:
+
+```bash
+git reset --mixed refs/gtd/review-head
+git update-ref -d refs/gtd/review-head
+git update-ref -d refs/gtd/review-base
+```
+
+7.2 also adds [`gtd abandon`](cli.md#gtd-abandon---json), the supported way out
+of a process that will never be finished (it closes the window, then rewinds
+HEAD to the process's start parent, keeping everything the process produced as
+uncommitted changes) — no hand-editing of refs required.
+
 ## Prior breaking change: the v1 → v2 label grammar (historical)
 
 v2 replaced v1's undifferentiated turn labels with six labels carrying the

package/package.json

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