fix(3668): isolate --local install from global gsd-sdk (#89)

* fix(3668): isolate --local install from global gsd-sdk

- `buildGsdSdkVersionMismatchReport` now accepts `opts.isLocal`; when
  true it sets `fix_command` to `npx get-shit-done-cc@latest --claude
  --local` instead of `npm install -g …`, removing the misleading global
  upgrade suggestion for local installs.
- Propagate `isLocal` from `installSdkIfNeeded` into the mismatch report
  builder so the right fix_command reaches the renderer.
- Export `buildGsdSdkVersionMismatchReport` and
  `renderGsdSdkVersionMismatchReport` so tests can assert on the IR
  contract directly.
- Add `command -v gsd-sdk … elif node "$GSD_TOOLS"` preflight SDK
  resolution block to all 69 workflow files that called bare `gsd-sdk`
  with no fallback, matching the pattern established in update.md,
  execute-phase.md, and quick.md.
- Add `tests/bug-3668-local-install-sdk-soft-dep.test.cjs` with 5 tests
  covering Defects 1-3, including a CI lint guard that blocks future
  workflow regressions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* changeset: add Fixed entry for #3668

* fix(3668): add allow-test-rule to suppress false lint-no-source-grep violation

The test reads workflow .md files (product content) to assert structural
invariants — not .cjs source files. The file-presence check is the only
viable IR for markdown guard patterns. Add the // allow-test-rule annotation
so lint-no-source-grep passes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(3668): fix do.md false-positive and discuss-phase.md size overflow

Two CI failures introduced by the 69-workflow preflight block:

1. do.md: the path `bin/gsd-tools.cjs` contains `/gsd-tools` which the
   bug-2954 parity test regex `/\/gsd[:-]([a-z][a-z0-9-]*)/g` mistakenly
   extracts as a slash command named `tools`. Fix: store the shim filename
   in _GSD_SHIM_NAME so the path construction no longer contains a static
   `/gsd-tools` literal. Also wire $GSD_SDK into the actual query call.

2. discuss-phase.md: the file was at 499 lines (the 500-line budget from
   #2551). Adding the 11-line preflight block pushed it to 510, failing
   workflow-size-budget.test.cjs. Fix: compress the 11-line preflight +
   2-line invocations into 3 lines (one-liner guard + two $GSD_SDK calls)
   returning the file to 499 lines while retaining the command -v guard
   required by bug-3668-local-install-sdk-soft-dep.test.cjs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(3668): wire \$GSD_SDK through all workflow callsites (#3797)

PR #3797 introduced the resolution preflight block (setting \$GSD_SDK) in
69 workflows but left every downstream gsd-sdk callsite using the bare
command. On local-only installs the preflight exits cleanly, then the
very next line fails with 'command not found'. This is the structural
gap the Codex review flagged.

Changes:
- 687 bare `gsd-sdk` callsites replaced with `\$GSD_SDK` across 75
  workflow files (all bash/sh fenced blocks excluding the resolution
  guard blocks themselves)
- execute-phase.md: was missing the preflight block entirely — added
  the standard 11-line resolution block at the initialize step
- execute-phase.md: inline `if command -v gsd-sdk` availability guard
  (legacy #3384 fallback) replaced with `\$GSD_SDK` + error fallback
  since the new preflight guarantees SDK availability or exits 1
- 6 sub-workflow files (discuss-phase/modes/*, execute-phase/steps/*)
  that have no preflight of their own but use \$GSD_SDK — these are
  loaded by parent workflows that set the variable; callsites updated
  to use \$GSD_SDK so they work when variable is in scope

Transformation script used: /private/tmp/fw2.js (regex-based fence
parser with segment join invariant verification — preserves all blank
lines and prose formatting).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(3668): upgrade CI guard to detect bare callsite routing (#3797)

The previous Defect 3 test checked that 'command -v gsd-sdk' appeared
as a string in the file — a guard-presence check, not a callsite-routing
check. A workflow with the preflight block but 40 bare gsd-sdk calls
below it passed the old test. This is exactly the bug state PR #3797
was supposed to fix.

Upgraded test:
- Parses each workflow file into markdown segments using a regex-based
  fence extractor (preserves all content invariantly)
- Skips bash/sh blocks that contain 'command -v gsd-sdk' (those are
  resolution guards — bare references there are expected)
- Flags any remaining bash/sh block line that invokes gsd-sdk without
  the \$ prefix (isBareGsdSdkInvocation predicate)
- Counter-test proves the predicate correctly flags real callsite lines
  and correctly exempts guard assignments, comments, and \$GSD_SDK refs

Also adds helper functions parseMarkdownSegments, isBareGsdSdkInvocation,
and findMdFiles which are used by both the upgraded Defect 3 test and
the counter-test.

This test would have caught the originally-shipped bug: the preflight
block was present but callsites still used bare gsd-sdk.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(tests): update workflow content tests to accept \$GSD_SDK callsite form (#3797)

Six regression tests assert on the exact textual pattern of gsd-sdk calls
inside workflow .md files. After the #3797 callsite replacement (687 bare
`gsd-sdk` invocations replaced with `\$GSD_SDK`), these tests failed because
they searched for the literal string `gsd-sdk query <cmd>` which no longer
appears at callsites.

Updated each test to accept both the pre-#3797 bare form and the post-#3797
variable form using `(?:\$GSD_SDK|gsd-sdk)` regex alternation (or two-branch
`includes()` checks for non-regex assertions). The structural invariants each
test enforces are unchanged — we're accepting the same behavioral contract
through the new callsite surface.

Tests fixed:
- bug-2334-quick-gsd-sdk-preflight: find init.quick call via \$GSD_SDK or bare
- bug-2661-roadmap-sync-parallel: roadmap.update-plan-progress call pattern
- bug-3360-codex-execute-phase-worktrees: RUNTIME config-get call detection
- bug-3381-verify-work-workstream: init.verify-work / phase.mvp-mode calls
- enh-2433-todo-phase-linking: commit call in new-milestone.md
- enh-2792-namespace-skills: validate.context invocation in context_check step

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(tests): update remaining workflow content tests to accept \$GSD_SDK form (#3797)

After #3797 callsite replacement, ultraplan-phase.test.cjs and worktree-cleanup.test.cjs
still assert bare gsd-sdk form. Update to accept either \$GSD_SDK or gsd-sdk. Also trim
the execute-phase.md preflight comment to stay within the XL line-count budget (1810).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(3668): adopt inline-per-fence SDK resolution + restore safety semantics

The brief offered three options:
  (a) inline preflight block per fence
  (b) wrapper script
  (c) shared shell fragment sourced at the top

71 of 72 workflow files already had inline preflight blocks (just broken ones).
Option (b)/(c) would have required changes to install.js + a new shared artifact,
with significant risk of breaking the install pipeline. Option (a) was the path
of least resistance and least new blast radius.

**BLOCKER 1+2+3 (quick.md — GSD_SDK never assigned):**
- quick.md had 12 `$GSD_SDK` references but zero `GSD_SDK=` assignments.
- Added proper local-first preflight block with `git rev-parse --show-toplevel`
  path (not the broken `CLAUDE_FILE_PATHS` which is always empty in Claude Code).
- Each Bash fence in Claude Code runs as a fresh `bash -c`, so env vars don't
  persist. The preflight block must appear in every fence that uses $GSD_SDK.

**BLOCKER 4 (execute-phase.md — || exit 1 dropped):**
- Restored `|| exit 1` after every `worktree.cleanup-wave` call. SDK safety
  refusals (drift detection #3174, deletion block #2384) must surface, not be
  swallowed by the old `|| { fallback }` branch.

**F5 (verify-work.md untyped fence):**
- Changed bare `gsd-sdk` in an untyped fence to `$GSD_SDK`.
- Changed fence tag from untyped to `bash`.

**F6 (non-recursive readdirSync):**
- Defect 2 test now uses `findMdFiles` (recursive) to cover workflow
  subdirectories, not the flat `fs.readdirSync` that missed subdirs.

**F7 (lint misses untyped fences):**
- `parseMarkdownSegments` now treats `lang === ''` fences as bash-fences.

**F8 (missing propagation test):**
- Added two propagation tests in the Defect 3 describe block.

**F9 (priority inverted — global before local):**
- All 72 workflow files now check `[ -f "$GSD_TOOLS" ]` before `command -v gsd-sdk`.
- Path: `$(git rev-parse --show-toplevel 2>/dev/null || pwd)/get-shit-done/bin/gsd-tools.cjs`

**F10/F11 (broken quoting):**
- Changed `GSD_SDK="node "$GSD_TOOLS""` → `GSD_SDK="node $GSD_TOOLS"` across all files.

**SDK-absence fallback removal:**
- The old `|| { STATE_BACKUP=...; while IFS=...WAS_DELETED...; done }` fallback
  code was dead — preflight now exits if neither local nor global SDK exists.
  Removed from quick.md, execute-phase.md. Tests updated to verify SDK delegation
  rather than inline shell mechanics.

**Tests updated:**
- bug-2384, bug-2501, bug-2838, bug-3091, bug-3195, bug-3521, bug-3668,
  worktree-cleanup — all updated to reflect SDK delegation contract.
- Defect 2 test now uses bash-fence scan (not raw content) to skip docs-only
  gsd-sdk prose references (e.g. discuss-phase/modes/text.md).

Closes #3668

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(3668): restore _GSD_SHIM_NAME indirection in do.md to prevent false-positive

The top commit re-introduced a literal /get-shit-done/bin/gsd-tools.cjs path
in do.md, causing bug-2954 test to match /gsd-tools as an unshipped slash
command. Restore the _GSD_SHIM_NAME variable indirection (from ff9939e5) to
break the literal path while preserving local-first preference order.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(tests): update worktree.test.cjs to accept SDK delegation contract (#3797)

Mirror the contract update already applied to worktree-cleanup.test.cjs:
- pre-merge deletion check tests: accept worktree.cleanup-wave + deletion
  mention as valid (inline --diff-filter=D was in the removed shell fallback)
- quick.md bug-2431 tests (lock-aware, unlock retry, residual warning): accept
  worktree.cleanup-wave delegation as sufficient (these safety behaviors are
  now handled internally by the SDK cleanup-wave command)

execute-phase.md tests unchanged: it retains inline .git/worktrees/, locked,
git worktree unlock, and Residual worktree in its cleanup-tail snippet.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(3668): refactor bug-2384 and bug-2838 from grep to structured assertions

Replace content.includes() on readFileSync-bound variables with parser
functions that split lines and return typed boolean fields, matching the
project's no-source-grep contract (lint-no-source-grep rule F/G).

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-05-22 14:54:20 -04:00
committed by GitHub
parent 3eec334533
commit 7ad1a5edf5
95 changed files with 2058 additions and 1266 deletions

View File

@@ -66,9 +66,20 @@ If `--wave` is absent, preserve the current behavior of executing all incomplete
Load all context in one call:
```bash
INIT=$(gsd-sdk query init.execute-phase "${PHASE_ARG}")
# SDK resolution: prefer local gsd-tools.cjs, fall back to global gsd-sdk (#3668)
GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
if [ -f "$GSD_TOOLS" ]; then
GSD_SDK="node $GSD_TOOLS"
elif command -v gsd-sdk >/dev/null 2>&1; then
GSD_SDK="gsd-sdk"
else
echo "ERROR: gsd-sdk not found on PATH and $GSD_TOOLS does not exist." >&2
echo "Run: npx get-shit-done-cc@latest --claude --local" >&2
exit 1
fi
INIT=$($GSD_SDK query init.execute-phase "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS=$(gsd-sdk query agent-skills gsd-executor)
AGENT_SKILLS=$($GSD_SDK query agent-skills gsd-executor)
```
Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
@@ -80,17 +91,17 @@ Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelizat
Read runtime/worktree config and fail closed before any executor dispatch:
```bash
RUNTIME=$(gsd-sdk query config-get runtime --default claude 2>/dev/null || echo "claude")
USE_WORKTREES=$(gsd-sdk query config-get workflow.use_worktrees 2>/dev/null || echo "true")
EXECUTOR_STALL_INTERVAL_MINUTES=$(gsd-sdk query config-get executor.stall_detect_interval_minutes 2>/dev/null || echo "5")
EXECUTOR_STALL_THRESHOLD_MINUTES=$(gsd-sdk query config-get executor.stall_threshold_minutes 2>/dev/null || echo "10")
RUNTIME=$($GSD_SDK query config-get runtime --default claude 2>/dev/null || echo "claude")
USE_WORKTREES=$($GSD_SDK query config-get workflow.use_worktrees 2>/dev/null || echo "true")
EXECUTOR_STALL_INTERVAL_MINUTES=$($GSD_SDK query config-get executor.stall_detect_interval_minutes 2>/dev/null || echo "5")
EXECUTOR_STALL_THRESHOLD_MINUTES=$($GSD_SDK query config-get executor.stall_threshold_minutes 2>/dev/null || echo "10")
if [ "$RUNTIME" = "codex" ] && [ "$USE_WORKTREES" != "false" ]; then
echo "FATAL: Codex execute-phase worktree isolation is unsupported. Set workflow.use_worktrees=false or use a runtime with Agent isolation=\"worktree\" support." >&2
exit 1
fi
# Sweep orphaned locked worktrees from prior crashed sessions before spawning executors (#3707).
[ "$USE_WORKTREES" != "false" ] && gsd-sdk query worktree.reap-orphans 2>/dev/null || true
[ "$USE_WORKTREES" != "false" ] && $GSD_SDK query worktree.reap-orphans 2>/dev/null || true
```
Codex maps subagents to `spawn_agent`, which has no direct Codex mapping for Claude Code's `isolation="worktree"` parameter. Failing closed prevents main-checkout edits while the workflow believes agents are isolated.
@@ -113,7 +124,7 @@ When `USE_WORKTREES` (project-level) is `false`, all executor agents run without
Read context window size for adaptive prompt enrichment:
```bash
CONTEXT_WINDOW=$(gsd-sdk query config-get context_window 2>/dev/null || echo "200000")
CONTEXT_WINDOW=$($GSD_SDK query config-get context_window 2>/dev/null || echo "200000")
```
When `CONTEXT_WINDOW >= 500000` (1M-class models), subagent prompts include richer context:
@@ -145,7 +156,7 @@ inline path for each plan.
```bash
# REQUIRED: prevents stale auto-chain from previous --auto runs
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
gsd-sdk query config-set workflow._auto_chain_active false || true
$GSD_SDK query config-set workflow._auto_chain_active false || true
fi
```
@@ -153,8 +164,8 @@ Resolve `MVP_MODE` once via the centralized `phase.mvp-mode` query verb (precede
```bash
MVP_FLAG_ARG=""
if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi
MVP_MODE=$(gsd-sdk query phase.mvp-mode "${PHASE_NUMBER}" $MVP_FLAG_ARG --pick active)
TDD_MODE=$(gsd-sdk query config-get workflow.tdd_mode 2>/dev/null || echo "false")
MVP_MODE=$($GSD_SDK query phase.mvp-mode "${PHASE_NUMBER}" $MVP_FLAG_ARG --pick active)
TDD_MODE=$($GSD_SDK query config-get workflow.tdd_mode 2>/dev/null || echo "false")
```
<step name="safe_resume_gate">
@@ -176,11 +187,11 @@ Offer these recovery options:
**MVP+TDD gate.** Task-scoped enforcement runs inside plan execution (immediately before each implementation step), where `TASK_FILE`, `PLAN_ID`, and `TASK_ID` are defined. Keep the same predicate and RED-commit contract:
```bash
if [ "$MVP_MODE" = "true" ] && [ "$TDD_MODE" = "true" ]; then
IS_BEHAVIOR_ADDING=$(gsd-sdk query task.is-behavior-adding "$TASK_FILE" --pick is_behavior_adding)
IS_BEHAVIOR_ADDING=$($GSD_SDK query task.is-behavior-adding "$TASK_FILE" --pick is_behavior_adding)
if [ "$IS_BEHAVIOR_ADDING" = "true" ]; then
RED_COMMIT=$(git log --oneline --grep="^test(${PHASE_NUMBER}-${PLAN_ID}):" -- "**/*.test.*" "**/*.spec.*" "tests/" | head -1)
if [ -z "$RED_COMMIT" ]; then
gsd-sdk query state.update last_gate_trip "${PLAN_ID}/${TASK_ID}" || true
$GSD_SDK query state.update last_gate_trip "${PLAN_ID}/${TASK_ID}" || true
echo "MVP+TDD GATE TRIPPED: missing RED commit for ${PLAN_ID}/${TASK_ID}"
exit 1
fi
@@ -306,7 +317,7 @@ Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)
**Update STATE.md for phase start:**
```bash
gsd-sdk query state.begin-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}" --plans "${PLAN_COUNT}"
$GSD_SDK query state.begin-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}" --plans "${PLAN_COUNT}"
```
This updates Status, Last Activity, Current focus, Current Position, and plan counts in STATE.md so frontmatter and body text reflect the active phase immediately.
</step>
@@ -315,7 +326,7 @@ This updates Status, Last Activity, Current focus, Current Position, and plan co
Load plan inventory with wave grouping in one call:
```bash
PLAN_INDEX=$(gsd-sdk query phase-plan-index "${PHASE_NUMBER}")
PLAN_INDEX=$($GSD_SDK query phase-plan-index "${PHASE_NUMBER}")
```
Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
@@ -357,9 +368,9 @@ executor skips them.
`workflow.cross_ai_execution` is `true`. Plans matching both conditions are marked for cross-AI.
```bash
CROSS_AI_ENABLED=$(gsd-sdk query config-get workflow.cross_ai_execution 2>/dev/null || echo "false")
CROSS_AI_CMD=$(gsd-sdk query config-get workflow.cross_ai_command 2>/dev/null || echo "")
CROSS_AI_TIMEOUT=$(gsd-sdk query config-get workflow.cross_ai_timeout 2>/dev/null || echo "300")
CROSS_AI_ENABLED=$($GSD_SDK query config-get workflow.cross_ai_execution 2>/dev/null || echo "false")
CROSS_AI_CMD=$($GSD_SDK query config-get workflow.cross_ai_command 2>/dev/null || echo "")
CROSS_AI_TIMEOUT=$($GSD_SDK query config-get workflow.cross_ai_timeout 2>/dev/null || echo "300")
```
**If no plans are marked for cross-AI:** Skip to execute_waves.
@@ -717,7 +728,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
5. **Post-wave hook validation (parallel mode only):** Hooks run on every executor commit by default (#2924); this post-wave run only fires when `workflow.worktree_skip_hooks=true` opted out of per-commit hooks:
```bash
SKIP_HOOKS=$(gsd-sdk query config-get workflow.worktree_skip_hooks 2>/dev/null || echo "false")
SKIP_HOOKS=$($GSD_SDK query config-get workflow.worktree_skip_hooks 2>/dev/null || echo "false")
if [ "$SKIP_HOOKS" = "true" ]; then
# Stash uncommitted changes under a named ref so we always pop (bare `git stash` strands them on hook/script failure). #3542: `refs/stash` is shared across worktrees, so this helper runs ONLY in the orchestrator's main checkout after all wave worktrees have been merged + removed; executors are forbidden from running any `git stash` subcommand (see `<destructive_git_prohibition>` in `agents/gsd-executor.md`).
STASHED=false
@@ -759,104 +770,8 @@ increases monotonically across waves. `{status}` is `complete` (success),
ORCH_BRANCH=$(git rev-parse --abbrev-ref HEAD)
[ -z "${EXPECTED_BRANCH:-}" ] || [ "$ORCH_BRANCH" = "$EXPECTED_BRANCH" ] || { echo "FATAL: orchestrator on '$ORCH_BRANCH' but expected '$EXPECTED_BRANCH' before worktree cleanup — refusing to merge (#3174-class drift)" >&2; exit 1; }
if command -v gsd-sdk >/dev/null 2>&1; then
gsd-sdk query worktree.cleanup-wave --manifest "$WAVE_WORKTREE_MANIFEST" || exit 1
else
echo "WARN: gsd-sdk unavailable; using manifest-scoped shell fallback (#3384)." >&2
WT_PATHS_FILE=$(mktemp "${TMPDIR:-/tmp}/gsd-worktree-paths-XXXXXX")
node -e 'const fs=require("fs");const p=process.env.WAVE_WORKTREE_MANIFEST;try{if(!p)throw new Error("WAVE_WORKTREE_MANIFEST is unset");if(!fs.existsSync(p))throw new Error("manifest does not exist");const s=fs.readFileSync(p,"utf8");if(!s.trim())throw new Error("manifest is empty");const j=JSON.parse(s);for(const w of j.worktrees||[])if(w.worktree_path)console.log(w.worktree_path)}catch(e){console.error(`ERROR: cannot read worktree manifest ${p||"(unset)"}: ${e.message}`);process.exit(1)}' > "$WT_PATHS_FILE" || { echo "BLOCKED: cannot read WAVE_WORKTREE_MANIFEST; refusing cleanup (#3384)." >&2; exit 1; }
while IFS= read -r WT; do
[ -z "$WT" ] && continue
WT_BRANCH=$(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null)
if [ -n "$WT_BRANCH" ] && [ "$WT_BRANCH" != "HEAD" ]; then
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
STATE_BACKUP=$(mktemp)
ROADMAP_BACKUP=$(mktemp)
[ -f .planning/STATE.md ] && cp .planning/STATE.md "$STATE_BACKUP" || true
[ -f .planning/ROADMAP.md ] && cp .planning/ROADMAP.md "$ROADMAP_BACKUP" || true
DELETIONS=$(git diff --diff-filter=D --name-only HEAD..."$WT_BRANCH" 2>/dev/null || true)
if [ -n "$DELETIONS" ]; then
echo "BLOCKED: Worktree branch $WT_BRANCH contains file deletions: $DELETIONS"
echo "Review these deletions before merging. If intentional, remove this guard and re-run."
rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
continue
fi
git merge "$WT_BRANCH" --no-ff --no-edit -m "chore: merge executor worktree ($WT_BRANCH)" 2>&1 || {
echo "⚠ Merge conflict from worktree $WT_BRANCH — resolve manually"
echo " STATE.md backup: $STATE_BACKUP"
echo " ROADMAP.md backup: $ROADMAP_BACKUP"
echo " Restore with: cp \$STATE_BACKUP .planning/STATE.md && cp \$ROADMAP_BACKUP .planning/ROADMAP.md"
break
}
MERGE_DEL_COUNT=$(git diff --diff-filter=D --name-only HEAD~1 HEAD 2>/dev/null | grep -vc '^\.planning/' || true)
if [ "$MERGE_DEL_COUNT" -gt 5 ] && [ "${ALLOW_BULK_DELETE:-0}" != "1" ]; then
MERGE_DELETIONS=$(git diff --diff-filter=D --name-only HEAD~1 HEAD 2>/dev/null | grep -v '^\.planning/' || true)
echo "⚠ BLOCKED: Merge of $WT_BRANCH deleted $MERGE_DEL_COUNT files outside .planning/ — reverting to protect repository integrity (#2384)"
echo "$MERGE_DELETIONS"
echo " If these deletions are intentional, re-run with ALLOW_BULK_DELETE=1"
git reset --hard HEAD~1 2>/dev/null || true
rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
continue
fi
if [ -s "$STATE_BACKUP" ]; then
cp "$STATE_BACKUP" .planning/STATE.md
fi
if [ -s "$ROADMAP_BACKUP" ]; then
cp "$ROADMAP_BACKUP" .planning/ROADMAP.md
fi
rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
# Detect files deleted on main but re-added by worktree merge (#2501).
DELETED_FILES=$(git diff --diff-filter=A --name-only HEAD~1 -- .planning/ 2>/dev/null || true)
for RESURRECTED in $DELETED_FILES; do
WAS_DELETED=$(git log --follow --diff-filter=D --name-only --format="" HEAD~1 -- "$RESURRECTED" 2>/dev/null | grep -c . || true)
if [ "${WAS_DELETED:-0}" -gt 0 ]; then
git rm -f "$RESURRECTED" 2>/dev/null || true
fi
done
if ! git diff --quiet .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || \
[ -n "$DELETED_FILES" ]; then
COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")
if [ "$COMMIT_DOCS" != "false" ]; then
git add .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || true
git commit --amend --no-edit 2>/dev/null || true
fi
fi
# Safety net: rescue uncommitted SUMMARY.md before worktree removal (#2070, #2838).
while IFS= read -r SUMMARY; do
[ -z "$SUMMARY" ] && continue
REL_PATH="${SUMMARY#$WT/}"
if [ ! -f "$REL_PATH" ] || ! cmp -s "$SUMMARY" "$REL_PATH"; then
mkdir -p "$(dirname "$REL_PATH")"
cp "$SUMMARY" "$REL_PATH"
echo "⚠ Rescued $REL_PATH from worktree before removal"
fi
done < <(find "$WT/.planning" -name "*SUMMARY.md" 2>/dev/null)
REMOVE_OK=false
if git worktree remove "$WT" --force; then
REMOVE_OK=true
else
WT_NAME=$(basename "$WT")
if [ -f ".git/worktrees/${WT_NAME}/locked" ]; then
echo "⚠ Worktree $WT is locked — attempting to unlock and retry"
git worktree unlock "$WT" 2>/dev/null || true
if git worktree remove "$WT" --force; then
REMOVE_OK=true
else
echo "⚠ Residual worktree at $WT — manual cleanup required after session exits:"
echo " git worktree unlock \"$WT\" && git worktree remove \"$WT\" --force && git branch -D \"$WT_BRANCH\""
fi
else
echo "⚠ Residual worktree at $WT (remove failed) — investigate manually"
fi
fi
if [ "$REMOVE_OK" = "true" ]; then
git branch -D "$WT_BRANCH" 2>/dev/null || true
else
echo "⚠ Keeping branch $WT_BRANCH because worktree removal failed (#3384)"
fi
fi
done < "$WT_PATHS_FILE"
fi
# Fail closed: SDK refusal (safety guard #3174/#3384) must surface — do not swallow exit 1.
$GSD_SDK query worktree.cleanup-wave --manifest "$WAVE_WORKTREE_MANIFEST" || exit 1
```
**Cleanup-tail snippet (use after any wave whose merges did not flow through the templated path above):**
@@ -929,12 +844,12 @@ increases monotonically across waves. `{status}` is `complete` (success),
if [ "${TEST_EXIT}" -eq 0 ]; then
# Update ROADMAP plan progress for each completed plan in this wave
for plan_id in {completed_plan_ids}; do
gsd-sdk query roadmap.update-plan-progress "${PHASE_NUMBER}" "${plan_id}" "complete"
$GSD_SDK query roadmap.update-plan-progress "${PHASE_NUMBER}" "${plan_id}" "complete"
done
# Only commit tracking files if they actually changed
if ! git diff --quiet .planning/ROADMAP.md .planning/STATE.md 2>/dev/null; then
gsd-sdk query commit "docs(phase-${PHASE_NUMBER}): update tracking after wave ${N}" --files .planning/ROADMAP.md .planning/STATE.md
$GSD_SDK query commit "docs(phase-${PHASE_NUMBER}): update tracking after wave ${N}" --files .planning/ROADMAP.md .planning/STATE.md
fi
elif [ "${TEST_EXIT}" -eq 124 ]; then
echo "⚠ Skipping tracking update — test suite timed out. Plans remain in-progress. Run tests manually to confirm."
@@ -1010,7 +925,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
7. **Handle failures:**
**Step 7.0 — classify before branching (#3095):**
```bash
CLASS_JSON=$(gsd-sdk query agent.classify-failure -- "$AGENT_RETURN_BODY")
CLASS_JSON=$($GSD_SDK query agent.classify-failure -- "$AGENT_RETURN_BODY")
CLASS=$(echo "$CLASS_JSON" | jq -r '.class')
SENTINEL=$(echo "$CLASS_JSON" | jq -r '.sentinel // empty')
RETRY_AFTER=$(echo "$CLASS_JSON" | jq -r '.retryAfterSeconds // empty')
@@ -1049,7 +964,7 @@ Plans with `autonomous: false` require user interaction.
**Auto-mode checkpoint handling:**
Read auto-advance config (chain flag OR user preference — same boolean as `check.auto-mode`):
```bash
AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
AUTO_MODE=$($GSD_SDK query check auto-mode --pick active 2>/dev/null || echo "false")
```
When executor returns a checkpoint AND `AUTO_MODE` is `true`:
@@ -1110,7 +1025,7 @@ After all waves:
**Security gate check:**
```bash
SECURITY_CFG=$(gsd-sdk query config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
SECURITY_CFG=$($GSD_SDK query config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
```
@@ -1134,7 +1049,7 @@ If `SECURITY_CFG` is `true` AND SECURITY.md exists: check frontmatter `threats_o
**Optional step — TDD collaborative review.**
```bash
TDD_MODE=$(gsd-sdk query config-get workflow.tdd_mode 2>/dev/null || echo "false")
TDD_MODE=$($GSD_SDK query config-get workflow.tdd_mode 2>/dev/null || echo "false")
```
**Skip if `TDD_MODE` is `false`.**
@@ -1187,7 +1102,7 @@ The verifier agent (step `verify_phase_goal`) still checks TDD discipline in bot
If `WAVE_FILTER` was used, re-run plan discovery after execution:
```bash
POST_PLAN_INDEX=$(gsd-sdk query phase-plan-index "${PHASE_NUMBER}")
POST_PLAN_INDEX=$($GSD_SDK query phase-plan-index "${PHASE_NUMBER}")
```
Apply the same "incomplete" filtering rules as earlier:
@@ -1219,7 +1134,7 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
**Config gate:**
```bash
CODE_REVIEW_ENABLED=$(gsd-sdk query config-get workflow.code_review 2>/dev/null || echo "true")
CODE_REVIEW_ENABLED=$($GSD_SDK query config-get workflow.code_review 2>/dev/null || echo "true")
```
If `CODE_REVIEW_ENABLED` is `"false"`: display "Code review skipped (workflow.code_review=false)" and proceed to next step.
@@ -1262,7 +1177,7 @@ fi
**2. Find parent UAT file:**
```bash
PARENT_INFO=$(gsd-sdk query find-phase "${PARENT_PHASE}" --raw)
PARENT_INFO=$($GSD_SDK query find-phase "${PARENT_PHASE}" --raw)
# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
```
@@ -1293,7 +1208,7 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
**6. Commit updated artifacts:**
```bash
gsd-sdk query commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
$GSD_SDK query commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
```
</step>
@@ -1321,7 +1236,7 @@ Collect all unique test file paths into `REGRESSION_FILES`.
```bash
# Resolve test command: project config > Makefile > language sniff
REG_TEST_CMD=$(gsd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
REG_TEST_CMD=$($GSD_SDK query config-get workflow.test_command --default "" 2>/dev/null || true)
if [ -z "$REG_TEST_CMD" ]; then
if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
REG_TEST_CMD="make test"
@@ -1377,7 +1292,7 @@ build/types pass because TypeScript types come from config, not the live databas
**Run after execution completes but BEFORE verification marks success.**
```bash
SCHEMA_DRIFT=$(gsd-sdk query verify.schema-drift "${PHASE_NUMBER}" 2>/dev/null)
SCHEMA_DRIFT=$($GSD_SDK query verify.schema-drift "${PHASE_NUMBER}" 2>/dev/null)
```
Parse JSON result for: `drift_detected`, `blocking`, `schema_files`, `orms`, `unpushed_orms`, `message`.
@@ -1451,7 +1366,7 @@ spawn template, and the two `workflow.drift_*` config keys.
Verify phase achieved its GOAL, not just completed tasks.
```bash
VERIFIER_SKILLS=$(gsd-sdk query agent-skills gsd-verifier)
VERIFIER_SKILLS=$($GSD_SDK query agent-skills gsd-verifier)
```
```
@@ -1536,7 +1451,7 @@ blocked: 0
Commit the file:
```bash
gsd-sdk query commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-HUMAN-UAT.md"
$GSD_SDK query commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-HUMAN-UAT.md"
```
**Step B: Present to user:**
@@ -1585,7 +1500,7 @@ Gap closure cycle: `/gsd:plan-phase {X} --gaps ${GSD_WS}` reads VERIFICATION.md
**Mark phase complete and update all tracking files:**
```bash
COMPLETION=$(gsd-sdk query phase.complete "${PHASE_NUMBER}")
COMPLETION=$($GSD_SDK query phase.complete "${PHASE_NUMBER}")
```
The CLI handles:
@@ -1608,7 +1523,7 @@ These items are tracked and will appear in `/gsd:progress` and `/gsd:audit-uat`.
```
```bash
gsd-sdk query commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
$GSD_SDK query commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
```
</step>
@@ -1620,7 +1535,7 @@ entries from the completed phase to the global learnings store at `~/.gsd/knowle
**Check config gate:**
```bash
GL_ENABLED=$(gsd-sdk query config-get features.global_learnings --raw 2>/dev/null || echo "false")
GL_ENABLED=$($GSD_SDK query config-get features.global_learnings --raw 2>/dev/null || echo "false")
```
**If `GL_ENABLED` is not `true`:** Skip this step entirely (feature disabled by default).
@@ -1630,7 +1545,7 @@ GL_ENABLED=$(gsd-sdk query config-get features.global_learnings --raw 2>/dev/nul
1. Check if LEARNINGS.md exists in the phase directory (use the `phase_dir` value from init context)
2. If found, copy to global store:
```bash
gsd-sdk query learnings.copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
$GSD_SDK query learnings.copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
```
Copy failure must NOT block phase completion.
</step>
@@ -1658,7 +1573,7 @@ for TODO_FILE in "$PENDING_DIR"/*.md; do
done
if [ ${#CLOSED[@]} -gt 0 ]; then
gsd-sdk query commit "docs(phase-${PHASE_NUMBER}): auto-close ${#CLOSED[@]} todo(s) resolved by this phase" --files .planning/todos/completed/ .planning/STATE.md|| true
$GSD_SDK query commit "docs(phase-${PHASE_NUMBER}): auto-close ${#CLOSED[@]} todo(s) resolved by this phase" --files .planning/todos/completed/ .planning/STATE.md|| true
echo "◆ Closed ${#CLOSED[@]} todo(s) resolved by Phase ${PHASE_NUMBER}:"
for f in "${CLOSED[@]}"; do echo " ✓ $f"; done
fi
@@ -1683,7 +1598,7 @@ PROJECT.md falls behind silently over multiple phases.
5. Commit the change:
```bash
gsd-sdk query commit "docs(phase-{X}): evolve PROJECT.md after phase completion" --files .planning/PROJECT.md
$GSD_SDK query commit "docs(phase-{X}): evolve PROJECT.md after phase completion" --files .planning/PROJECT.md
```
**Skip this step if** `.planning/PROJECT.md` does not exist.
@@ -1721,7 +1636,7 @@ STOP. Do not proceed to auto-advance or transition.
1. Parse `--auto` flag from $ARGUMENTS
2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
```bash
AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
AUTO_MODE=$($GSD_SDK query check auto-mode --pick active 2>/dev/null || echo "false")
```
**If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**