@opengsd/gsd-core 1.8.0 → 1.9.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gsd-core",
       "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.8.0",
+      "version": "1.9.1",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",

package/.opencode/plugins/gsd-core.js

@@ -239,6 +239,32 @@ function runHook(hookFile, payload, opts = {}) {
   return { stdout, exitCode, timedOut: result.signal === "SIGTERM" };
 }
 
+/**
+ * In-process check for whether context-usage warnings are disabled in project
+ * config. Mirrors the exact semantics of the same check inside
+ * hooks/gsd-context-monitor.js (introduced by #1073): an explicit
+ * `config.hooks.context_warnings === false` disables them; a missing or
+ * unparseable .planning/config.json keeps them enabled (the default).
+ *
+ * #2697: hoisting this check in-process lets the adapter SKIP the context-monitor
+ * spawn entirely when the user has opted out, instead of paying a full Node boot
+ * inside the child only to read the boolean and exit. Missing/unparseable config
+ * MUST behave identically to the hook (enabled) so the default path is unchanged.
+ *
+ * @param {string} cwd  project working directory (the plugin's currentCwd)
+ * @returns {boolean} true when context warnings are explicitly disabled
+ */
+function contextWarningsDisabled(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.hooks?.context_warnings === false;
+  } catch {
+    // Missing or unparseable config → proceed with defaults (context warnings enabled).
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Hook output translation → OpenCode semantics
 // ---------------------------------------------------------------------------
@@ -587,7 +613,11 @@ const GsdCorePlugin = async ({ directory } = {}) => {
 
       // gsd-context-monitor.js — context usage warnings (Bash/Edit/Write/Task/...)
       // Only meaningful when a session_id is tracked (writes metrics sentinel).
-      if (currentSessionId) {
+      // #2697: skip the subprocess spawn entirely when context warnings are
+      // explicitly disabled in project config — the hook would exit early anyway,
+      // so hoisting the check in-process avoids paying a Node boot per tool call.
+      // Missing/unparseable config = enabled (default), so the spawn still runs.
+      if (currentSessionId && !contextWarningsDisabled(cwd)) {
         const payload = {
           hook_event_name: "PostToolUse",
           tool_name: claudeTool,

package/agents/gsd-code-fixer.md

@@ -216,9 +216,36 @@ If a finding references multiple files (in Fix section or Issue section):
 
 This agent runs as a background process that makes commits. Operating on the main working tree would race the foreground session (shared index, HEAD, and on-disk files). Instead, every instance runs in its own isolated worktree.
 
+**#2825: honor `workflow.use_worktrees`.** This is the ONLY writer that hand-rolls a git worktree
+inside the agent prompt; every other writer path (`/gsd:execute-phase`, `/gsd:execute-plan`,
+`/gsd:quick`, `/gsd:diagnose-issues`) reads `workflow.use_worktrees` and skips isolation when it is
+`false`. Read the same flag here and, when it is `false`, edit and commit in the main checkout
+directly (set `wt="."`, no `reviewfix_branch`, no recovery sentinel, no `git worktree add`, and skip
+the cleanup tail — there is no worktree to remove). When the flag is not `false`, the transactional
+worktree path below runs unchanged. A user who explicitly opted out of worktrees must never have a
+worktree created; the hand-rolled worktree also cannot run the project's gates safely (no
+`node_modules`), so the opt-out is also the safe path.
+
 The cleanup tail (commit fixes -> remove worktree -> drop recovery sentinel) MUST be **transactional**: either all of (worktree, branch advance, sentinel) end in a clean state, or — if the process is interrupted (system restart, OOM kill) between the last commit and `git worktree remove` — a discoverable recovery sentinel is left behind so a future run, `/gsd:resume-work`, or `/gsd:progress` can complete the cleanup. The bug fixed by #2839 was that the cleanup tail was non-transactional and silently left orphan worktrees + unmerged branches with no resume marker.
 
 ```bash
+# #2825: honor workflow.use_worktrees — the documented opt-out. When false,
+# edit/commit in the main checkout (wt=".", no temp branch, no sentinel, no
+# cleanup tail). Read the flag the same way the four sibling writer workflows
+# do. NOTE: this read parses .planning/config.json directly via `node` rather
+# than the gsd-tools CLI, because setup_worktree runs BEFORE the canonical
+# launcher preamble is sourced — invoking the CLI here would be undefined at
+# runtime and violates the runtime-launcher-parity preamble-ordering rule.
+# Once the preamble is sourced (later steps), the CLI is available.
+USE_WORKTREES=$(node -e '
+  try {
+    const fs = require("fs");
+    const p = (process.env.GSD_PROJECT_DIR || process.cwd()) + "/.planning/config.json";
+    const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+    process.stdout.write(String((cfg.workflow && cfg.workflow.use_worktrees) ?? true));
+  } catch { process.stdout.write("true"); }
+')
+
 # Derive worktree path from padded_phase (parsed from config in next step,
 # but the shell snippet below is illustrative — adapt once config is parsed).
 # In practice: parse padded_phase from config first, then run:
@@ -264,34 +291,47 @@ if [ -f "$sentinel" ]; then
   rm -f "$sentinel"
 fi
 
-wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
-
-# Create a temp branch from the current branch tip so the worktree
-# attaches to that NEW branch rather than the user's currently-checked-out
-# branch (#2990: git refuses to check out the same branch in two
-# worktrees by default; the original `git worktree add "$wt" "$branch"`
-# failed before the agent could do any work). The temp branch shares
-# history with $branch up to the moment of creation, so commits made
-# inside the worktree fast-forward $branch on cleanup.
-reviewfix_branch="gsd-reviewfix/${padded_phase}-$$"
-git worktree add -b "$reviewfix_branch" "$wt" "$branch"
-
-# Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
-# Writing it before would leave a sentinel pointing at a worktree that does
-# not exist if `git worktree add` itself failed.
-node -e '
-  const fs = require("fs");
-  const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1);
-  fs.writeFileSync(sentinelPath, JSON.stringify({
-    worktree_path,
-    branch,
-    reviewfix_branch,
-    padded_phase,
-    started_at: new Date().toISOString()
-  }, null, 2));
-' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"
-
-cd "$wt"
+# #2825: when the user opted out of worktrees, edit/commit in the main
+# checkout directly — no temp branch, no sentinel, no cleanup tail. This is
+# the safe path: the hand-rolled worktree has no node_modules, so it cannot
+# run the project's gates, and an improvised teardown can destroy the real
+# node_modules on Windows (a junction followed by rm -rf). wt="." means every
+# downstream read/edit/commit lands in the main working tree, and the cleanup
+# tail below is a no-op (nothing to fast-forward, no worktree to remove).
+if [ "$USE_WORKTREES" = "false" ]; then
+  wt="."
+  reviewfix_branch="$branch"
+  echo "workflow.use_worktrees=false — editing/committing in the main checkout (no worktree)."
+else
+  wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
+
+  # Create a temp branch from the current branch tip so the worktree
+  # attaches to that NEW branch rather than the user's currently-checked-out
+  # branch (#2990: git refuses to check out the same branch in two
+  # worktrees by default; the original `git worktree add "$wt" "$branch"`
+  # failed before the agent could do any work). The temp branch shares
+  # history with $branch up to the moment of creation, so commits made
+  # inside the worktree fast-forward $branch on cleanup.
+  reviewfix_branch="gsd-reviewfix/${padded_phase}-$$"
+  git worktree add -b "$reviewfix_branch" "$wt" "$branch"
+
+  # Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
+  # Writing it before would leave a sentinel pointing at a worktree that does
+  # not exist if `git worktree add` itself failed.
+  node -e '
+    const fs = require("fs");
+    const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1);
+    fs.writeFileSync(sentinelPath, JSON.stringify({
+      worktree_path,
+      branch,
+      reviewfix_branch,
+      padded_phase,
+      started_at: new Date().toISOString()
+    }, null, 2));
+  ' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"
+
+  cd "$wt"
+fi
 ```
 
 Concrete steps:
@@ -305,9 +345,18 @@ Concrete steps:
 
 **If `git worktree add` fails**, surface the error and exit — do not force-remove the path, as another concurrent run may be holding it. Do not write the sentinel (the worktree does not exist). Do not delete `$reviewfix_branch` either; if `-b` failed, no temp branch was created.
 
-**Cleanup tail (transactional, ALWAYS — even on failure):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the cleanup in this exact order:
+**Cleanup tail (transactional, ALWAYS — even on failure — when a worktree was created):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the cleanup in this exact order. (When `workflow.use_worktrees` is `false`, no worktree was created — the cleanup is a no-op and the bash below early-exits.)
 
 ```bash
+# #2825: when worktrees were disabled, there is nothing to clean up — the
+# agent edited/committed on $branch directly in the main checkout (wt=".",
+# reviewfix_branch==$branch, no sentinel, no temp worktree). Skip the whole
+# tail; the four steps below are all no-ops or harmful (e.g. `git worktree
+# remove "."` ) in that mode.
+if [ "$USE_WORKTREES" = "false" ]; then
+  exit 0
+fi
+
 # Step 1 (#2990): fast-forward $branch to capture the commits the agent
 # made on $reviewfix_branch. Run from the main repo (not $wt) — the user's
 # checkout owns $branch. --ff-only ensures we never silently drop or
@@ -354,7 +403,7 @@ fi
 rm -f "$sentinel"
 ```
 
-This cleanup is unconditional — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the cleanup tail in order (fast-forward → worktree remove → temp branch delete → sentinel rm) before exit. The sentinel must NEVER be removed before `git worktree remove` succeeds. The temp branch must NEVER be deleted while the fast-forward is in a diverged state.
+This cleanup is unconditional when a worktree was created — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the cleanup tail in order (fast-forward → worktree remove → temp branch delete → sentinel rm) before exit. (When `workflow.use_worktrees` is `false`, no worktree exists and the bash above early-exits before these steps.) The sentinel must NEVER be removed before `git worktree remove` succeeds. The temp branch must NEVER be deleted while the fast-forward is in a diverged state.
 </step>
 
 <step name="load_context">
@@ -456,7 +505,7 @@ For each finding in sorted order:
 
 **If verification passed:**
 
-Use `gsd-tools query commit` with conventional format (message first, then every staged file path):
+Use `gsd_run query commit` with conventional format (message first, then every staged file path):
 ```bash
 _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 gsd_run query commit \
@@ -587,9 +636,33 @@ _Iteration: {N}_
 
 <critical_rules>
 
-**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail unconditionally when done (treat it as a finally block). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
-
-**ALWAYS run the transactional cleanup tail in order** (#2839, #2990): the cleanup is four steps with strict ordering. (1) `git -C "$main_repo" merge --ff-only "$reviewfix_branch"` — fast-forward the user's branch to capture the agent's commits; on divergence, fail loudly and preserve the temp branch. (2) `git worktree remove "$wt" --force`. (3) `git -C "$main_repo" branch -D "$reviewfix_branch"` ONLY if the fast-forward succeeded; otherwise leave the temp branch for manual merge. (4) `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. The temp branch is deleted only when the fast-forward succeeded. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind (with `reviewfix_branch` recorded) so a future run, `/gsd:resume-work`, or `/gsd:progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
+**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail when done (treat it as a finally block) — but only when a worktree was actually created; when `workflow.use_worktrees` is `false` the cleanup early-exits (no worktree to remove). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+
+**#2825 — honor `workflow.use_worktrees`.** Before creating a worktree, read the
+`workflow.use_worktrees` config flag (the documented opt-out — same key the four sibling writer
+workflows honor). `setup_worktree` reads it via `node` directly from `.planning/config.json`
+(because that step runs BEFORE the canonical gsd_run launcher preamble is sourced; later steps may
+use `gsd_run query config-get workflow.use_worktrees`). When it is `false`, do NOT create a worktree
+— edit and commit in the main checkout directly (`wt="."`, no temp branch, no sentinel, no cleanup
+tail). A user who opted out of worktrees must
+never have one created. See the `setup_worktree` step for the gated bash.
+
+**NEVER `rm -rf` a possible reparse point** (#2825). On Windows, `node_modules` inside the worktree
+may be a junction/reparse point whose target is the REAL `node_modules` in the main checkout — and
+`rm -rf` follows the link and deletes the target's contents (silent, misdiagnosable data loss). Do
+NOT improvise a `node_modules` teardown. The worktree has no `node_modules` by design; if you need
+the project's gates, run them in the main checkout after the fast-forward, OR leave the worktree's
+dependency handling to `git worktree remove` (which does not recurse into a separately-managed
+link). Never use `rm -rf` (or `2>/dev/null || rm -rf || true`) as a fallback for removing a path
+that might be a reparse point — on failure, STOP and surface the error rather than falling through
+to a destructive remove.
+
+**Record where verification ran** (#2825). The REVIEW-FIX.md verification section must state whether
+the gates ran in the main checkout or the isolated worktree, so a reader can tell whether the numbers
+are reproducible from the tree they are looking at (a worktree-env run is not reproducible from the
+main checkout after teardown).
+
+**ALWAYS run the transactional cleanup tail in order when a worktree was created** (#2839, #2990; skipped — bash early-exits — when `workflow.use_worktrees` is `false`): the cleanup is four steps with strict ordering. (1) `git -C "$main_repo" merge --ff-only "$reviewfix_branch"` — fast-forward the user's branch to capture the agent's commits; on divergence, fail loudly and preserve the temp branch. (2) `git worktree remove "$wt" --force`. (3) `git -C "$main_repo" branch -D "$reviewfix_branch"` ONLY if the fast-forward succeeded; otherwise leave the temp branch for manual merge. (4) `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. The temp branch is deleted only when the fast-forward succeeded. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind (with `reviewfix_branch` recorded) so a future run, `/gsd:resume-work`, or `/gsd:progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 

package/agents/gsd-codebase-mapper.md

@@ -175,7 +175,7 @@ Write document(s) to `.planning/codebase/` using the templates below.
 **Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
 
 **Template filling:**
-1. Replace `[YYYY-MM-DD]` with the date provided in your prompt (the `Today's date:` line). NEVER guess or infer the date — always use the exact date from the prompt.
+1. Set the `**Analysis Date:**` line, the `*... analysis: ...*` footer, and any `<!-- refreshed: ... -->` header to the date provided in your prompt (the `Today's date:` line), overwriting whatever date is already there. NEVER guess or infer the date — always use the exact date from the prompt.
 2. Replace `[Placeholder text]` with findings from exploration
 3. If something is not found, use "Not detected" or "Not applicable"
 4. Always include file paths with backticks

package/agents/gsd-debug-session-manager.md

@@ -310,6 +310,41 @@ If user selects 3: proceed to Step 4 with fix = "not applied (guardrail rejected
 
 Read the resolved (or current) debug file to extract final Resolution values.
 
+**Commit before returning a terminal summary (#2568).** This agent owns the terminal path —
+it applies fixes, archives to `resolved/`, and returns the summary — but carried no commit
+step, so `commit_docs` was never consulted on the normal `/gsd:debug` flow and session docs
+were left untracked. Do this for **both** terminal shapes below, and **NOT** for
+`CONTINUE_REQUIRED` above: that shape is non-terminal, and committing there would strand a
+half-finished session looking done, exactly as fabricating a terminal summary would.
+`CHECKPOINT REACHED` (Step 3d) likewise does not commit — it pauses for user input and loops
+back to Step 3.
+
+1. **In-session fix code.** If a fix was applied during this session and its code changes are
+   still uncommitted, commit them first. Stage **specific files only** — the files the fix
+   touched. Do this rather than `git add -A`, which would sweep unrelated working-tree
+   changes into a debug commit. Guard on staged content: `gsd-debugger.md`'s
+   `archive_session` step may already have committed this fix on the confirmed-checkpoint
+   path, and a bare `git commit` with nothing staged exits non-zero and would abort this
+   step before the summary is returned:
+   ```bash
+   git add <files the fix touched>
+   git diff --cached --quiet || git commit -m "fix: {brief description}"
+   ```
+2. **Session doc.** Commit via the CLI, which already gates on `commit_docs` and returns
+   `skipped_commit_docs_false` when disabled — call it unconditionally rather than
+   re-checking the config here, so the policy lives in one place. `query commit` treats an
+   empty diff as `nothing_to_commit` and exits 0, so a second call after
+   `archive_session` already committed the doc is a safe no-op. The canonical `gsd_run` preamble is
+   established once in Step 2 and is the single definition this agent carries (repo
+   invariant: exactly one preamble per agent file, before its first call):
+   ```bash
+   # resolved session — path spelled literally; this agent receives `slug` and
+   # `debug_file_path`, NOT a `debug_dir` variable (see <session_parameters>).
+   gsd_run query commit "docs(debug): resolve {slug} session" --files .planning/debug/resolved/{slug}.md
+   # abandoned session (checkpoint retained for `/gsd:debug continue {slug}`)
+   gsd_run query commit "docs(debug): checkpoint {slug} session" --files {debug_file_path}
+   ```
+
 Return compact summary (terminal — investigation resolved):
 
 ```markdown
@@ -349,5 +384,6 @@ If the session was abandoned by user choice, return (terminal — user stopped):
 - [ ] TDD gate applied when tdd_mode=true and ROOT CAUSE FOUND
 - [ ] Loop continues until DEBUG COMPLETE, ABANDONED, or user stops
 - [ ] Non-terminal `CONTINUE_REQUIRED` (not a fabricated terminal summary) returned when the manager's own turn/context budget is exhausted mid-investigation
+- [ ] Session doc (and any uncommitted fix code from this session) committed before a terminal summary, respecting `commit_docs` — and NOT committed on the non-terminal `CONTINUE_REQUIRED` path
 - [ ] Compact summary returned (at most 2K tokens)
 </success_criteria>

package/agents/gsd-executor.md

@@ -495,11 +495,11 @@ if [ -f .git ]; then  # worktree
     echo "DO NOT use 'git update-ref' to rewind the protected branch — surface as blocker (#2924)." >&2
     exit 1
   fi
-  # Positive allow-list: HEAD must be on the canonical Claude Code worktree-agent
-  # branch namespace (`worktree-agent-<id>`). This catches feature/* and any other
-  # arbitrary branch that the deny-list would silently allow (#2924).
-  if ! echo "$ACTUAL_BRANCH" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then
-    echo "FATAL: refusing to commit — worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace." >&2
+  # Positive allow-list: HEAD must be on a per-agent branch (`agent-<id>` or
+  # legacy `worktree-agent-<id>`). This catches feature/* and any other
+  # arbitrary branch that the deny-list would silently allow (#2924, #1995).
+  if ! echo "$ACTUAL_BRANCH" | grep -Eq '^(worktree-)?agent-[A-Za-z0-9._/-]+$'; then
+    echo "FATAL: refusing to commit — worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* namespace." >&2
     echo "Agent commits must live on per-agent branches; surface as blocker (#2924)." >&2
     exit 1
   fi
@@ -638,7 +638,16 @@ This file is the canonical output of this step. The orchestrator reads `.plannin
 
 **Use template:** @~/.claude/gsd-core/templates/summary.md
 
-**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date), status (`status: complete` — required so the audit-open scanner recognises the summary as done).
+**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date), status (`status: complete` — required so the audit-open scanner recognises the summary as done), and `actuals` (#2632).
+
+**`actuals` (required when the plan carried an `estimate`):** record what the phase ACTUALLY cost, on the SAME scale the estimate used — `estimateTokens` (chars/4) over the realized diff, NOT a harness token count. Mixing scales measures the measurement methods, not the miss.
+```yaml
+actuals:
+  tokens: 74000    # chars/4 over the files you actually changed
+  tasks: 5         # tasks completed
+  commits: 7       # commits made
+```
+These pair with the plan's `estimate` to calibrate future estimates (ADR-2629). Do not round to look closer to the estimate — a flattering number corrupts every later projection.
 
 **Title:** `# Phase [X] Plan [Y]: [Name] Summary`
 
@@ -780,7 +789,7 @@ gsd_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files \
 Separate from per-task commits — captures execution results only.
 
 **Handling the SDK return envelope (#3678):** `gsd-tools query commit` returns
-one of three shapes:
+one of these shapes:
 
 - `{committed: true, hash, reason: 'committed'}` — commit succeeded; record
   the hash in the completion format.
@@ -793,6 +802,10 @@ one of three shapes:
   success path.** Record "skipped (.planning gitignored)" and move on.
 - `{committed: false, reason: 'nothing_to_commit' | 'commit_failed', ...}` —
   no-op / genuine failure; surface in the completion notes.
+- `{committed: false, reason: 'staging_failed' | 'staging_timeout', file, error}` —
+  `git add` itself failed (#2608), e.g. an unwritable index. Nothing committed,
+  index rolled back. Surface `file` + `error` (git's stderr); do not retry — a
+  retry hits the same cause.
 
 **Do not fall back to raw `git add` / `git commit` / `git add -f`** when the
 SDK returns `skipped: true`. The SDK's skip is the user's deliberate choice

package/agents/gsd-intel-updater.md

@@ -123,7 +123,7 @@ All JSON files include a `_meta` object with `updated_at` (ISO timestamp) and `v
 }
 ```
 
-**exports constraint:** Array of ACTUAL exported symbol names extracted from `module.exports` or `export` statements. MUST be real identifiers (e.g., `"configLoad"`, `"stateUpdate"`), NOT descriptions (e.g., `"config operations"`). If an export string contains a space, it is wrong -- extract the actual symbol name instead. Use `gsd-tools intel extract-exports <file>` to get accurate exports.
+**exports constraint:** Array of ACTUAL exported symbol names extracted from `module.exports` or `export` statements. MUST be real identifiers (e.g., `"configLoad"`, `"stateUpdate"`), NOT descriptions (e.g., `"config operations"`). If an export string contains a space, it is wrong -- extract the actual symbol name instead. Use `gsd_run intel extract-exports <file>` to get accurate exports.
 
 Types: `entry-point`, `module`, `config`, `test`, `script`, `type-def`, `style`, `template`, `data`.
 
@@ -255,7 +255,7 @@ gsd_run intel patch-meta .planning/intel/arch-decisions.json
 
 ### Step 6.5: Self-Check
 
-Run: `gsd-tools intel validate`
+Run: `gsd_run intel validate`
 
 Review the output:
 
@@ -267,7 +267,7 @@ This step is MANDATORY -- do not skip it.
 
 ### Step 7: Snapshot
 
-Run: `gsd-tools intel snapshot`
+Run: `gsd_run intel snapshot`
 
 This writes `.last-refresh.json` with accurate timestamps and hashes. Do NOT write `.last-refresh.json` manually.
 </execution_flow>

package/agents/gsd-phase-researcher.md

@@ -32,6 +32,8 @@ Spawned by `/gsd:plan-phase` (integrated) or `/gsd:plan-phase --research-phase <
 
 **Package name provenance rule:** A package name discovered via WebSearch, training data, or any non-authoritative source must be tagged `[ASSUMED]` regardless of whether `npm view` confirms it exists on the registry. Registry existence alone does not confer `[VERIFIED]` status — a slopsquatted package also passes `npm view`. Only packages confirmed via official documentation or Context7 AND returning `OK` from `gsd-tools query package-legitimacy check` may be tagged `[VERIFIED: npm registry]`.
 
+**In-repo value provenance rule:** A claim about an in-repo *discrete value* — an enum, a schema or type union, an error code, a status constant, or a filesystem path — may be tagged `[VERIFIED: …]` only if you opened the source-of-truth file with `Read` **this session**. A codebase `grep` is not sufficient on its own: it confirms a string occurs, not that you read the definition. Cite the path **and line range** (`[VERIFIED: src/types/order.ts:14-22]`), and quote the values **verbatim** in RESEARCH.md beside the claim — paraphrase is forbidden. The quote is what makes the tag checkable — a citation with no quote beside it does not earn `[VERIFIED]`, however precise the line range looks. Every value appearing in a code example or skeleton must also appear in that verbatim quote; a value that does not is `[ASSUMED]`. For a filesystem path, cite the line in the script that creates it, not the location you expect it to occupy. Training memory and a web search are not substitutes for reading the file — a discrete value that merely looks right fails at the executor's `parse()`/typecheck, the most expensive place to discover it.
+
 Claims tagged `[ASSUMED]` signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision. Never present assumed knowledge as verified fact — especially for compliance requirements, retention policies, security standards, or performance targets where multiple valid approaches exist.
 </role>
 
@@ -136,7 +138,7 @@ For each item where `fetch` is present, invoke the MCP tool matching `fetch.prov
 | `exa` | `mcp__exa__web_search_exa` with `fetch.query` |
 | `tavily` | `mcp__tavily__search` with `fetch.query` |
 | `perplexity` | `mcp__perplexity__*` (use the appropriate perplexity MCP tool for the query) |
-| `brave` | `gsd-tools query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
+| `brave` | `gsd_run query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
 | `firecrawl` | `mcp__firecrawl__scrape` with url (scrape kind) or `mcp__firecrawl__search` |
 | `websearch` | built-in `WebSearch` tool |
 | `webfetch` | built-in `WebFetch` tool |
@@ -707,7 +709,7 @@ docker info 2>/dev/null | head -3
 
 ## Step 3: Execute Research Protocol
 
-For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd-tools query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd-tools query classify-confidence --provider <id>` to obtain the tier).
+For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd_run query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd_run query classify-confidence --provider <id>` to obtain the tier).
 
 ## Step 4: Validation Architecture Research (if nyquist_validation enabled)
 

package/agents/gsd-plan-checker.md

@@ -252,6 +252,19 @@ issue:
 1. Count tasks per plan
 2. Estimate files modified per plan
 3. Check against thresholds
+4. **Smart-zone estimate check (#2631, ADR-2629).** For each plan carrying an `estimate` block, run the
+   `estimate-check --calibrated` verb against its `estimate.tokens` (the `--calibrated` flag is required —
+   the plan's figure already has the factor applied, and omitting it would square the correction) (invoked in Step 1 below, after the launcher
+   preamble). The verb reads `workflow.smart_zone_tokens` and applies the project's calibration. Report
+   one line per plan: plan id, estimated tokens, the budget, and — when `over_budget` is true — the
+   returned `recommendation`, which names how many slices the phase should become.
+
+   **Over budget is a WARNING, never a blocker** (ADR-2629 Decision 5). Recommend re-slicing into a tracer
+   plus expansion slices; never fail the check on it. Report `estimate.confidence` alongside: `low` means
+   fewer than 3 completed phases carry actuals, so the figure is not yet calibrated for this project — say
+   so rather than presenting it as precise, and weigh the task/file thresholds above more heavily.
+
+   A plan with no `estimate` block is not a defect; the field is optional and additive.
 
 **Thresholds:**
 | Metric | Target | Warning | Blocker |
@@ -706,6 +719,13 @@ gsd_run query phase.list-plans "$phase_number"
 gsd_run query phase.list-artifacts "$phase_number" --type research
 gsd_run query roadmap.get-phase "$phase_number"
 gsd_run query phase.list-artifacts "$phase_number" --type summary
+
+# Smart-zone estimate check (#2631) — advisory, never fails the check.
+for plan in "${phase_dir:-$PHASE_DIR}"/*-PLAN.md; do
+  [ -f "$plan" ] || continue   # unmatched glob leaves the literal pattern — skip it
+  EST=$(sed -n '/^estimate:/,/^[a-z_]*:/p' "$plan" | grep -o 'tokens: *[0-9]*' | head -1 | grep -o '[0-9]*')
+  [ -n "$EST" ] && gsd_run query estimate-check --tokens "$EST" --calibrated 2>/dev/null || true
+done
 ```
 
 **Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.

package/agents/gsd-planner.md

@@ -288,30 +288,15 @@ See @~/.claude/gsd-core/references/planner-guidance.md for dependency graph buil
 
 <scope_estimation>
 
-## Context Budget Rules
+## Sizing and the Estimate Block
 
-Plans should complete within ~50% context (not 80%). No context anxiety, quality maintained start to finish, room for unexpected complexity.
+Full rules: @~/.claude/gsd-core/references/context-budget.md (Phase Sizing). Read before sizing.
 
-**Each plan: 2-3 tasks maximum.**
-
-| Context Weight | Tasks/Plan | Context/Task | Total |
-|----------------|------------|--------------|-------|
-| Light (CRUD, config) | 3 | ~10-15% | ~30-45% |
-| Medium (auth, payments) | 2 | ~20-30% | ~40-50% |
-| Heavy (migrations, multi-subsystem) | 1-2 | ~30-40% | ~30-50% |
-
-## Split Signals
-
-**ALWAYS split if:**
-- More than 3 tasks
-- Multiple subsystems (DB + API + UI = separate plans)
-- Any task with >5 file modifications
-- Checkpoint + implementation in same plan
-- Discovery + implementation in same plan
-
-**CONSIDER splitting:** >5 files total, natural semantic boundaries, context cost estimate exceeds 40% for a single plan. See `<planner_authority_limits>` for prohibited split reasons.
-
-See @~/.claude/gsd-core/references/planner-guidance.md for Granularity Calibration table (Coarse/Standard/Fine plans-per-phase).
+- **2-3 tasks per plan.** **ALWAYS split if:** >3 tasks, multiple subsystems, or any task touching >5 files.
+- **Emit `estimate`**: run `estimate-calibration`; `tokens` = raw projection x factor, `raw_tokens` = that
+  projection before the factor (calibration measures actual/raw), `confidence` verbatim — derived from
+  sample count, never self-rated.
+- **Over the smart-zone budget?** Re-slice: tracer + expansion slices. Advisory, never a block.
 
 </scope_estimation>
 
@@ -331,6 +316,12 @@ autonomous: true            # false if plan has checkpoints
 requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
 user_setup: []              # Human-required setup (omit if empty)
 
+estimate:                   # Projected execution cost (see Estimate Emission)
+  tokens: 60000             # calibrated projection
+  raw_tokens: 30000         # pre-factor projection
+  tasks: 3                  # task count the projection assumes
+  confidence: low           # low | med | high — DERIVED from sample count, never self-rated
+
 must_haves:
   truths: []                # Observable behaviors
   artifacts: []             # Files that must exist
@@ -412,6 +403,7 @@ Create `.planning/phases/XX-name/{padded_phase}-{plan}-SUMMARY.md` when done
 | `autonomous` | Yes | `true` if no checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement ID MUST appear in at least one plan. |
 | `user_setup` | No | Human-required setup items |
+| `estimate` | No | Projected cost `{tokens, tasks, confidence}`. See Estimate Emission. |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
 Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.
@@ -734,7 +726,7 @@ Read the most recent milestone retrospective and cross-milestone trends. Extract
 </step>
 
 <step name="inject_global_learnings">
-If `features.global_learnings` is `true`: run `gsd-tools query learnings.query --tag <tag> --limit 5` once per tag from PLAN.md frontmatter `tags` (or use the single most specific keyword). The handler matches one `--tag` at a time. Prefix matches with `[Prior learning from <project>]` as weak priors. Project-local decisions take precedence. Skip silently if disabled or no matches.
+If `features.global_learnings` is `true`: run `gsd_run query learnings.query --tag <tag> --limit 5` once per tag from PLAN.md frontmatter `tags` (or use the single most specific keyword). The handler matches one `--tag` at a time. Prefix matches with `[Prior learning from <project>]` as weak priors. Project-local decisions take precedence. Skip silently if disabled or no matches.
 </step>
 
 <step name="gather_phase_context">

package/agents/gsd-project-researcher.md

@@ -102,7 +102,7 @@ For each item where `fetch` is present, invoke the MCP tool matching `fetch.prov
 | `exa` | `mcp__exa__web_search_exa` with `fetch.query` |
 | `tavily` | `mcp__tavily__search` with `fetch.query` |
 | `perplexity` | `mcp__perplexity__*` (use the appropriate perplexity MCP tool for the query) |
-| `brave` | `gsd-tools query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
+| `brave` | `gsd_run query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
 | `firecrawl` | `mcp__firecrawl__scrape` with url (scrape kind) or `mcp__firecrawl__search` |
 | `websearch` | built-in `WebSearch` tool |
 | `webfetch` | built-in `WebFetch` tool |
@@ -490,7 +490,7 @@ Orchestrator provides: project name/description, research mode, project context,
 
 ## Step 3: Execute Research
 
-For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd-tools query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd-tools query classify-confidence --provider <id>` to obtain the tier).
+For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd_run query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd_run query classify-confidence --provider <id>` to obtain the tier).
 
 ## Step 4: Quality Check
 

package/agents/gsd-ui-auditor.md

@@ -104,46 +104,6 @@ This gate runs unconditionally on every audit. The .gitignore ensures screenshot
 
 </gitignore_gate>
 
-<playwright_mcp_approach>
-
-## Automated Screenshot Capture via Playwright-MCP (preferred when available)
-
-Before attempting the CLI screenshot approach, check whether `mcp__playwright__*`
-tools are available in this session. If they are, use them instead of the CLI approach:
-
-```
-# Preferred: Playwright-MCP automated verification
-# 1. Navigate to the component URL
-mcp__playwright__navigate(url="http://localhost:3000")
-
-# 2. Take desktop screenshot
-mcp__playwright__screenshot(name="desktop", width=1440, height=900)
-
-# 3. Take mobile screenshot
-mcp__playwright__screenshot(name="mobile", width=375, height=812)
-
-# 4. For specific components listed in UI-SPEC.md, navigate to each
-#    component route and capture targeted screenshots for comparison
-#    against the spec's stated dimensions, colors, and layout.
-
-# 5. Compare screenshots against UI-SPEC.md requirements:
-#    - Dimensions: Is component X width 70vw as specified?
-#    - Color: Is the accent color applied only on declared elements?
-#    - Layout: Are spacing values within the declared spacing scale?
-#    Report any visual discrepancies as automated findings.
-```
-
-**When Playwright-MCP is available:**
-- Use it for all screenshot capture (skip the CLI approach below)
-- Each UI checkpoint from UI-SPEC.md can be verified automatically
-- Discrepancies are reported as pillar findings with screenshot evidence
-- Items requiring subjective judgment are flagged as `needs_human_review: true`
-
-**When Playwright-MCP is NOT available:** fall back to the CLI screenshot approach
-below. Behavior is unchanged from the standard code-only audit path.
-
-</playwright_mcp_approach>
-
 <screenshot_approach>
 
 ## Screenshot Capture (CLI only — no MCP, no persistent browser)