@pmelab/gtd 7.1.0 → 7.2.0

package/docs/cli.md

@@ -25,6 +25,17 @@ 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
+  restore          Hard-reset HEAD back to the pre-squash tip retained by the
+                   last squash/abandon (refs/worktree/gtd/history), undoing a
+                   squash or bringing back an abandoned process's turns.
+                   Refuses on a dirty working tree, when there is no retained
+                   history, or when HEAD has advanced past the squash with
+                   commits that would be lost
   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 +178,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 +225,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 +245,103 @@ 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 restore [--json]`
+
+Undoes the last squash or `gtd abandon` by hard-resetting HEAD back to the
+pre-squash tip that either one retains, before acting, on the per-worktree
+`refs/worktree/gtd/history` ref
+([STATES.md §8](../STATES.md#8-the-squash-lifecycle)):
+
+```
+restored the retained history — HEAD is back at 1a2b3c4 ("gtd(agent): drafting
+→ working"), resting at "await-review". Resume with the loop, or `git reset`
+to any earlier turn to restart from there.
+```
+
+Refuses on a dirty working tree — commit, stash, or discard your changes first.
+Refuses when there is no retained history to restore (nothing has been squashed
+or abandoned yet, or a previous `restore` already consumed it). Refuses when
+HEAD has advanced past the retained tip with commits that would be discarded by
+resetting:
+
+```
+gtd restore: HEAD has advanced past the squash — restoring would discard
+commits built on top of it — HEAD 4d5e6f7 is ahead of the retained tip
+1a2b3c4.
+```
+
+Takes no positional argument (extra arguments are a usage error).
+
+`--json` emits `{state, restored, to, from}` — `state` is the resolved rest
+after the reset, `restored` always `true` (a refusal exits non-zero instead),
+`to` the full hash HEAD was reset to, and `from` the state the machine rested at
+before the reset:
+
+```json
+{
+  "state": "await-review",
+  "restored": true,
+  "to": "1a2b3c4…",
+  "from": "idle"
+}
+```
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -495,3 +605,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

@@ -261,6 +261,38 @@ value) only when the resolved state declares one — **omitted entirely**, never
 `null`, when unset. Plain `gtd status` prints a `Memory:` line (right after
 `Model:`, when present).
 
+### `label:` — the opaque display name, template-rendered
+
+A state may declare `label: <string>` — an OPAQUE display name gtd never
+interprets; it is only passed through so a driver/viewer can show something
+friendlier than the raw state name. Unset means the state has no display name.
+Forbidden on a commit state (never at rest, emits nothing):
+
+```yaml
+workflow:
+  states:
+    working:
+      actor: agent
+      label: Implement the feature
+      prompt: do the thing
+      on:
+        "* **": done
+```
+
+Like `model`/`memory`, `label:` is rendered as an Eta template through the exact
+same context as the state's content — a plain string with no Eta tags
+(`Implement the feature` above) passes through unchanged, but
+`label: "<%= it.vars.stateLabel %>"` resolves against the merged `it.vars` (see
+["Variables"](#variables)). A render failure behaves exactly like a content
+render failure at the same call site: `gtd next`/`gtd status` error out, nothing
+committed.
+
+`gtd next --json` and `gtd status --json` include a `"label"` key (the RENDERED
+value) only when the resolved state declares one — it is **omitted entirely**,
+never emitted as `null`, when unset. A driver/viewer choosing to fall back to
+the raw state name when `label` is absent is that consumer's own fallback, not
+something gtd itself does.
+
 ### `file:`/`mode:` — the steering-file association
 
 A state may additionally declare `file:` — an Eta template naming THE steering
@@ -449,9 +481,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

@@ -18,13 +18,18 @@ DRIVER runs the emitted `content` and then steps that state's own actor.
 A loop is a simple cycle:
 
 1. Run `gtd next --json` — see [`cli.md`](cli.md#gtd-next---json) for the exact
-   `{state, actor, kind, content, model?, memory?}` field shape. `kind` is the
-   dispatch key: `"message"` → halt (a human rest); `"script"` → execute
+   `{state, actor, kind, content, model?, memory?, label?}` field shape. `kind`
+   is the dispatch key: `"message"` → halt (a human rest); `"script"` → execute
    `content` verbatim (ignoring its exit code), then `gtd step <actor>` to
    capture the outcome; `"prompt"` → feed `content` to the agent, then
    `gtd step <actor>` yourself once it's done acting. The optional `model` is an
    opaque string the workflow author chose, which you map onto your own
-   harness's model selection if you use one.
+   harness's model selection if you use one. The optional `label` is a
+   human-readable display name for the resolved state, present only when that
+   state declares `label:` in the workflow; when it's absent, a driver that
+   wants to show something falls back to `state` itself (that fallback lives in
+   the driver, not gtd core — see `bin/gtd-loop`'s
+   `label="$(jq -r '.label // .state' <<<"$next_json")"`).
 2. Repeat until a `"message"` rest halts the loop, or a zero-commit script step
    at idle settles it (the green terminal signal).
 
@@ -34,6 +39,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
 ```
@@ -149,3 +167,35 @@ example, to drive a different agent CLI:
 ```bash
 GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
 ```
+
+## Herdr integration (optional)
+
+`bin/gtd-loop` optionally reports its lifecycle to [Herdr](https://herdr.dev) (a
+terminal multiplexer for coding agents) via a `herdr` CLI binary, entirely at
+the driver's edge — gtd core never talks to Herdr. Every call is best-effort
+(guarded, output discarded, `|| true`), so a missing/failing `herdr` binary
+never blocks, slows, or fails the loop.
+
+The reporting is a no-op unless all three guard conditions hold: `HERDR_ENV=1`,
+a non-empty `$HERDR_PANE_ID`, and `herdr` on `$PATH`. When they do, `gtd-loop`
+makes three kinds of calls:
+
+- `herdr pane report-agent --source herdr:gtd --agent gtd --state <state> --message <label> "$HERDR_PANE_ID"`
+- `herdr pane release-agent --source herdr:gtd --agent gtd "$HERDR_PANE_ID"`
+- `herdr notification show <title> --body <label> --sound request`
+
+mapped onto the loop's states like this:
+
+| Loop moment                                                                          | Call(s)                                                                  |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| Top of every non-`"message"` iteration                                               | `report-agent --state working`                                           |
+| Right before halting at a `"message"` (human) gate                                   | `report-agent --state blocked` + `notification show`                     |
+| Right before a clean settle (a script rest, zero new commits)                        | `report-agent --state idle` + `release-agent`                            |
+| Any non-zero exit (stall guard, validate-cap, `gtd next` failure, unhandled failure) | `report-agent --state blocked` + `notification show`, via an `EXIT` trap |
+
+`working`/`blocked` reports use the resolved rest's `label` (falling back to
+`state`, per the field above); the trap falls back to `$GTD_LAST_LABEL`, the
+label tracked from the last completed iteration, when it fires outside the
+normal per-iteration flow. `report-agent` claims display authority for the
+`herdr:gtd` source, so `working` is re-reported every lap rather than once, to
+stay fresh against Herdr's own heuristic detection of the inner agent process.

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.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": {