@pmelab/gtd 8.2.0 → 8.3.0

package/README.md

@@ -115,10 +115,12 @@ steering-file entries are chosen by which file you create:
   per-package **agentic review** that verifies the package against its spec.
 
 Both flows converge on the same tail: an agent hands you a `.gtd/REVIEW.md`
-checkbox review of the diff — tick a box as you review each hunk (ticking just
-records "I read this"), and leave a **comment** to request changes: a note on a
-line, an inline `// TODO`-style comment in the code, or a direct code edit. Any
-comment sends a build + re-review round — an agent first turns your comments
+checkbox review of the diff — the prompt never inlines the diff itself; it names
+the commit the changes are based at and the agent runs `git diff` to read the
+range before writing the review. Tick a box as you review each hunk (ticking
+just records "I read this"), and leave a **comment** to request changes: a note
+on a line, an inline `// TODO`-style comment in the code, or a direct code edit.
+Any comment sends a build + re-review round — an agent first turns your comments
 into an explicit instruction list, then a build turn implements it (a re-review
 then covers only the follow-through, and a hand-edit is treated as your own fix
 the agent completes without reverting your lines; a comment can't be silently
@@ -306,6 +308,13 @@ name surfaced in `gtd next --json`/`gtd status`. The driver uses it for its
 per-beat progress lines; an outer wrapper (a terminal multiplexer, a notifier)
 can use it the same way.
 
+A state can also declare an optional `memory:` scope label: consecutive agent
+turns sharing the same label continue one agent session (remembered in the git
+dir, so it survives restarts across the same worktree), while a changed or
+absent label starts a fresh one. If the remembered session no longer exists
+(retention expired, `~/.claude/projects` wiped, a machine change), the driver
+degrades to a fresh session with a warning instead of stopping the loop.
+
 ### Terminal-multiplexer status: a herdr wrapper
 
 [herdr](https://herdr.dev) shows a per-pane status in its sidebar. This wrapper
@@ -470,6 +479,22 @@ workflow:
       mode: <modeName> # optional, requires "file" — a built-in (qa/review/prose) or a `modes:` entry
 ```
 
+Besides `it.vars` (below), a `script`/`prompt`/`message`/`commit` template sees:
+
+- **`it.startCommit`** — the process's diff base (the commit the current cycle
+  started from, or a `gtd review <commitish>` entry's resolved base).
+- **`it.reviewBase`** — the previous review round's boundary, falling back to
+  `it.startCommit` on a first review.
+- **`it.retainedBase`** — the process's trace/retry boundary, what a squash
+  actually keeps (never moved by a `gtd review` entry).
+- **`it.currentCommit`** / **`it.previousCommit`** — HEAD's hash and its parent,
+  at render time.
+
+A template never sees rendered diff CONTENT — no field carries a diff. It names
+a base and leaves the agent to run `git diff <base>` itself; this keeps every
+render cheap (no diff computed on `gtd next`/`gtd status`/`gtd lsp`) and the
+prompt small and cacheable.
+
 Authoring or editing a workflow with a coding agent? `skills/authoring/SKILL.md`
 is the agent-facing contract for producing a valid `workflow:` — the state
 model, pattern grammar, load-time rules, and how to verify a change compiles.

package/bin/gtd

@@ -23,7 +23,16 @@ set -euo pipefail
 # Every call the loop body makes below goes through `run_gtd` too, so the loop
 # always drives the exact same build/source it was launched from — no
 # dependence on a `gtd` binary being on PATH.
-SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
+# Follow symlinks first: npm's global install exposes this script as a
+# symlink in the node prefix's bin/, and dist/ only exists next to the REAL
+# script inside the package.
+SCRIPT_SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SCRIPT_SOURCE" ]]; do
+  SCRIPT_DIR="$(cd -- "$(dirname -- "$SCRIPT_SOURCE")" &>/dev/null && pwd)"
+  SCRIPT_SOURCE="$(readlink "$SCRIPT_SOURCE")"
+  [[ "$SCRIPT_SOURCE" != /* ]] && SCRIPT_SOURCE="$SCRIPT_DIR/$SCRIPT_SOURCE"
+done
+SCRIPT_DIR="$(cd -- "$(dirname -- "$SCRIPT_SOURCE")" &>/dev/null && pwd)"
 
 run_gtd() {
   if [[ -n "${GTD_BIN:-}" ]]; then
@@ -172,6 +181,23 @@ emit_output_since() {
   emit_block "$bytes"
 }
 
+# A resume that failed because the session it names no longer exists — claude
+# prints "No conversation found with session ID: <uuid>". Loose on purpose: any
+# adapter whose CLI says something session-shaped gets the same recovery
+# instead of stopping the loop.
+SESSION_GONE_RE='no conversation found with session id|no such session|session (id )?[^ ]*( was)? not found|session [^ ]* does not exist'
+
+# session_gone_since <offset> — true when the log bytes appended since <offset>
+# carry the missing-session signature above. Blind (returns false) when no log
+# is configured, so recovery is best-effort, never a hard dependency.
+session_gone_since() {
+  local offset="$1" bytes=""
+  if [[ -n "${GTD_LOOP_LOG:-}" && -f "$GTD_LOOP_LOG" ]]; then
+    bytes="$(tail -c "+$((offset + 1))" "$GTD_LOOP_LOG" 2>/dev/null || true)"
+  fi
+  [[ -n "$bytes" ]] && grep -qiE "$SESSION_GONE_RE" <<<"$bytes"
+}
+
 # emit_warn <message> — a surfaced but NON-fatal failure (a check script that
 # exited non-zero).
 emit_warn() {
@@ -330,7 +356,18 @@ fi
 # still resumes one planning session. The scope, session id, and a
 # resume-or-fresh flag are exported as $GTD_LOOP_MEMORY / $GTD_LOOP_SESSION_ID
 # / $GTD_LOOP_MEMORY_RESUME; the default adapter turns them into
-# `--resume`/`--session-id`. An adapter that ignores them keeps working.
+# `--resume`/`--session-id`. An adapter that ignores them keeps working. A
+# remembered session that has since vanished (the retention window elapsed, a
+# wiped `~/.claude/projects`, a machine change) degrades to a fresh session
+# with a warning rather than failing the turn — see run_agent_turn's own
+# comment.
+
+# new_session_id — mints an opaque session id for a fresh memory scope
+# (uuidgen, falling back to the kernel's random uuid, or empty when neither is
+# available — the default adapter then omits --session-id entirely).
+new_session_id() {
+  uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo ""
+}
 
 prev_state=""
 prev_content=""
@@ -362,7 +399,7 @@ fi
 # the resume flag; the memory scope ($memory/$session_id) is read from the
 # enclosing iteration, so a same-turn re-prompt (the validate gate) resumes the
 # same session.
-run_agent_turn() {
+invoke_agent() {
   local prompt="$1" do_resume="$2" cmd="${GTD_LOOP_AGENT_CMD:-}"
   if [[ -z "$cmd" ]]; then
     cmd='claude -p "$GTD_LOOP_PROMPT"'
@@ -379,6 +416,33 @@ run_agent_turn() {
     >>"${GTD_LOOP_LOG:-/dev/null}" 2>&1
 }
 
+# run_agent_turn <prompt> <resume> — invoke_agent, with one recovery: a
+# resumed turn (do_resume == 1) that fails AND whose output carries the
+# missing-session signature (session_gone_since) means the marker's session no
+# longer exists on disk. Rather than failing the turn (and every turn after
+# it, since the dead id would just be resumed again), mint a fresh session,
+# rewrite $memory_marker with it — the self-healing part, so a later launch
+# doesn't repeat this — and retry the SAME prompt once with resume off. $resume
+# and $session_id are the enclosing iteration's globals; recovery rewrites them
+# too, so a later validate-gate re-prompt in the same turn resumes the newly
+# pinned session. Blind to the failure mode when session_gone_since can't tell
+# (no log configured): a genuine agent failure then correctly propagates.
+run_agent_turn() {
+  local prompt="$1" do_resume="$2" offset status=0
+  offset="$(log_offset)"
+  invoke_agent "$prompt" "$do_resume" && return 0
+  status=$?
+  if [[ "$do_resume" == "1" ]] && session_gone_since "$offset"; then
+    emit_warn "the remembered agent session for '$memory' is gone — continuing in a fresh session (this turn starts without its previous context)"
+    session_id="$(new_session_id)"
+    resume=0
+    printf '%s\n%s\n' "$memory" "$session_id" >"$memory_marker"
+    invoke_agent "$prompt" 0
+    return $?
+  fi
+  return $status
+}
+
 # The furthest commit already reported to the terminal by report_commits (see
 # its own comment) — a global high-water mark rather than a per-beat
 # head_before, so a review checkout window's HEAD rewind between beats never
@@ -528,7 +592,7 @@ $next_out"
       resume=1
       session_id="$prev_session"
     else
-      session_id="$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo "")"
+      session_id="$(new_session_id)"
     fi
     printf '%s\n%s\n' "$memory" "$session_id" >"$memory_marker"
   else