@opengsd/gsd-core 1.2.0 → 1.3.0-rc.1

package/get-shit-done/workflows/autonomous.md

@@ -284,11 +284,11 @@ Check if this phase has frontend indicators and whether a UI-SPEC already exists
 PHASE_SECTION=$(gsd_run query roadmap.get-phase ${PHASE_NUM} 2>/dev/null)
 # Shell-free word-boundary gate (#3718): Node.js helper — no locale env-var dependency.
 # Reads via stdin to avoid OS ARG_MAX limits on large phase text.
-# Path anchored to repo root; falls back to CWD if git is unavailable
-# Exit codes mirror grep: 0 = UI tokens found, 1 = not found.
-GSD_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
-printf '%s' "$PHASE_SECTION" | node "${GSD_REPO_ROOT}/bin/lib/ui-safety-gate.cjs" > /dev/null 2>&1
-HAS_UI=$?
+# Resolve the helper against the GSD install dir via RUNTIME_DIR (#448) — NOT the consuming
+# project's git root — falling back to git toplevel / $HOME/.claude. Exit codes mirror grep (0=UI,1=none).
+_GSD_RT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+UI_GATE_JS=$(for _c in "$_GSD_RT/get-shit-done/bin/lib/ui-safety-gate.cjs" "$_GSD_RT/bin/lib/ui-safety-gate.cjs" "$_GSD_RT/.claude/bin/lib/ui-safety-gate.cjs" "$HOME/.claude/get-shit-done/bin/lib/ui-safety-gate.cjs" "$HOME/.claude/bin/lib/ui-safety-gate.cjs"; do [ -f "$_c" ] && { echo "$_c"; break; }; done)
+if [ -n "$UI_GATE_JS" ]; then printf '%s' "$PHASE_SECTION" | node "$UI_GATE_JS" >/dev/null 2>&1; HAS_UI=$?; else echo "WARN: ui-safety-gate.cjs not found via RUNTIME_DIR/\$HOME (#448) — assuming UI present" >&2; HAS_UI=0; fi
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -324,6 +324,8 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 
 **If `INTERACTIVE` is set:** Dispatch plan as a background agent to keep the main context lean. While plan runs, the workflow can immediately start discussing the next phase (see step 4).
 
+Print: `◆ Spawning background planner for phase ${PHASE_NUM}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+
 ```
 Agent(
   description="Plan phase ${PHASE_NUM}: ${PHASE_NAME}",

package/get-shit-done/workflows/cleanup.md

@@ -85,17 +85,38 @@ These phase directories will be archived:
 Destination: .planning/milestones/v{X.Z}-phases/
 ```
 
-If no phase directories remain to archive (all already moved or deleted):
+**Stale local branches (upstream gone):**
+
+First, update remote-tracking refs so the candidate list matches the execution list exactly:
+
+```bash
+git fetch --prune 2>/dev/null || true
+```
+
+Then enumerate candidates (protected branch names are excluded even if their upstream is gone):
+
+```bash
+git branch -vv | awk '/: gone\]/ { if ($1 !~ /^\*$|^main$|^next$|^trunk$|^develop$/) print $1 }'
+```
+
+Show each branch name. If none, show:
+
+```
+No stale local branches detected.
+```
+
+If no phase directories remain to archive (all already moved or deleted) AND no stale branches exist:
 
 ```
 No phase directories found to archive. Phases may have been removed or archived previously.
+No stale local branches detected either.
 ```
 
 Stop here.
 
 
 **Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
-AskUserQuestion: "Proceed with archiving?" with options: "Yes — archive listed phases" | "Cancel"
+AskUserQuestion: "Proceed with archiving and pruning?" with options: "Yes — archive phases and prune stale branches" | "Cancel"
 
 If "Cancel": Stop.
 
@@ -119,6 +140,22 @@ Repeat for all milestones in the cleanup set.
 
 </step>
 
+<step name="prune_local_branches">
+
+After phase archival, prune local branches whose upstream has been deleted. Use the same filter as the dry-run so the execution list matches exactly what the user confirmed:
+
+```bash
+git branch -vv | awk '/: gone\]/ { if ($1 !~ /^\*$|^main$|^next$|^trunk$|^develop$/) print $1 }' | xargs -r git branch -D
+```
+
+Notes:
+- `git fetch --prune` already ran in `show_dry_run` — the tracking refs are current and this step enumerates from the same state the user confirmed.
+- `!~ /^\*$/` skips the currently checked-out branch (prefixed with `* ` in `git branch -vv` output, so `$1` yields `*`).
+- `!~ /^main$|^next$|^trunk$|^develop$/` excludes protected branch names even if their upstream is gone — matches the dry-run exclusion exactly.
+- `xargs -r` prevents `git branch -D` from running with no arguments when no stale branches exist.
+
+</step>
+
 <step name="commit">
 
 Commit the changes:
@@ -137,6 +174,8 @@ Archived:
 {For each milestone}
 - v{X.Y}: {N} phase directories → .planning/milestones/v{X.Y}-phases/
 
+Pruned: {N} local branches whose upstream is gone.
+
 .planning/phases/ cleaned up.
 ```
 
@@ -148,8 +187,9 @@ Archived:
 
 - [ ] All completed milestones without existing phase archives identified
 - [ ] Phase membership determined from archived ROADMAP snapshots
-- [ ] Dry-run summary shown and user confirmed
+- [ ] Dry-run summary shown and user confirmed (covers both archival and pruning)
 - [ ] Phase directories moved to `.planning/milestones/v{X.Y}-phases/`
+- [ ] Stale local branches pruned (branches whose upstream is gone)
 - [ ] Changes committed
 
 </success_criteria>

package/get-shit-done/workflows/code-review-fix.md

@@ -179,7 +179,7 @@ If REVIEW.md contains a `files_reviewed_list` frontmatter field, use that as the
 </step>
 
 <step name="spawn_fixer">
-Spawn the gsd-code-fixer agent with config:
+Spawn the gsd-code-fixer agent with config (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```bash
 # Build config for agent
@@ -271,7 +271,7 @@ if [ "$AUTO_MODE" = "true" ]; then
       done
     fi
     
-    # Spawn gsd-code-reviewer agent to re-review
+    # Spawn gsd-code-reviewer agent to re-review (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
     # (This overwrites REVIEW_PATH with latest review state)
     Agent(subagent_type="gsd-code-reviewer", prompt="
 <config>
@@ -304,7 +304,7 @@ Do NOT commit the output — the orchestrator handles that.
       break
     fi
     
-    # Still has issues — spawn fixer again
+    # Still has issues — spawn fixer again (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
     echo "Issues remain. Applying fixes for iteration ${ITERATION}..."
     
     Agent(subagent_type="gsd-code-fixer", prompt="

package/get-shit-done/workflows/code-review.md

@@ -441,6 +441,8 @@ fi
 
 Spawn the gsd-code-reviewer agent:
 
+Print: `◆ Spawning code reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+
 ```
 Agent(subagent_type="gsd-code-reviewer", prompt="
 <files_to_read>

package/get-shit-done/workflows/debug.md

@@ -101,7 +101,7 @@ Eliminated: {count}
 
 Surface to user. Then delegate directly to the session manager (skip Steps 2 and 3 — pass `symptoms_prefilled: true` and set the slug from SLUG variable). The existing file IS the context.
 
-Print before spawning:
+Print before spawning (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 ```
 [debug] Session: .planning/debug/{SLUG}.md
 [debug] Status: {status}
@@ -190,6 +190,11 @@ Create `.planning/debug/{slug}.md` with initial state using the Write tool (neve
 
 After initial context setup, spawn the session manager to handle the full checkpoint/continuation loop. The session manager handles specialist_hint dispatch internally: when gsd-debugger returns ROOT CAUSE FOUND it extracts the specialist_hint field and invokes the matching skill (e.g. typescript-expert, swift-concurrency) before offering fix options.
 
+Print before spawning (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
+```
+[debug] Delegating loop to session manager...
+```
+
 ```
 Agent(
   prompt="""

package/get-shit-done/workflows/diagnose-issues.md

@@ -96,6 +96,8 @@ EXPECTED_BASE=$(git rev-parse HEAD)
 
 For each gap, fill the debug-subagent-prompt template and spawn:
 
+Print: `◆ Spawning diagnostics agent... (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)`
+
 ```
 Agent(
   prompt=filled_debug_subagent_prompt + "\n\n<worktree_branch_check>\nFIRST ACTION: assert this is a disposable worktree branch before any repair. Run:\n```bash\nHEAD_REF=$(git symbolic-ref --quiet HEAD || echo \"DETACHED\")\nACTUAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)\nif [ \"$HEAD_REF\" = \"DETACHED\" ] || echo \"$ACTUAL_BRANCH\" | grep -Eq '^(main|master|develop|trunk|release/.*)$'; then\n  echo \"FATAL: diagnose worktree HEAD on '$ACTUAL_BRANCH'; refusing reset --hard on a protected branch.\" >&2\n  exit 1\nfi\nif ! echo \"$ACTUAL_BRANCH\" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then\n  echo \"FATAL: diagnose worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace; refusing reset --hard.\" >&2\n  exit 1\nfi\nACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})\nif [ \"$ACTUAL_BASE\" != \"{EXPECTED_BASE}\" ]; then\n  git reset --hard {EXPECTED_BASE}\n  [ \"$(git rev-parse HEAD)\" != \"{EXPECTED_BASE}\" ] && { echo \"ERROR: Could not correct worktree base\"; exit 1; }\nfi\n```\nFixes EnterWorktree creating branches from main on all platforms while preventing protected-branch data loss.\n</worktree_branch_check>\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}",

package/get-shit-done/workflows/discuss-phase/modes/advisor.md

@@ -86,7 +86,7 @@ This reframing applies to:
 After the user selects gray areas in `present_gray_areas`, spawn parallel
 research agents.
 
-1. Display brief status: `Researching {N} areas...`
+1. Display brief status: `Researching {N} areas...` (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)
 
 2. For EACH user-selected gray area, spawn a `Agent()` in parallel:
 

package/get-shit-done/workflows/discuss-phase-assumptions.md

@@ -252,7 +252,7 @@ Map to calibration tier:
 
 If no USER-PROFILE.md: calibration_tier = "standard"
 
-**Spawn Explore subagent:**
+**Spawn Explore subagent** (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)**:**
 
 ```
 Agent(subagent_type="gsd-assumptions-analyzer", prompt="""
@@ -310,7 +310,7 @@ Parse the subagent's response. Extract:
 <step name="external_research">
 **Skip if:** `needs_research` from deep_codebase_analysis is empty.
 
-If research topics were flagged, spawn a general-purpose research agent:
+If research topics were flagged, spawn a general-purpose research agent (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```
 Agent(subagent_type="general-purpose", prompt="""

package/get-shit-done/workflows/docs-update.md

@@ -374,7 +374,7 @@ After all decisions recorded, continue to detect_runtime_capabilities.
 <step name="dispatch_wave_1" condition="Task tool is available">
 **Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — use `canonical_queue` items with `wave: 1` for this step.
 
-Spawn 3 parallel gsd-doc-writer agents for Wave 1 docs: README, ARCHITECTURE, CONFIGURATION.
+Spawn 3 parallel gsd-doc-writer agents for Wave 1 docs: README, ARCHITECTURE, CONFIGURATION (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze).
 
 These are foundational docs with no cross-references needed, making them ideal for parallel generation.
 
@@ -831,7 +831,8 @@ Extract `canonical_queue` (items with `status: "completed"`) and `review_queue`
 
 For each doc in `canonical_queue` that was successfully written to disk:
 
-1. Spawn the `gsd-doc-verifier` agent (or invoke sequentially if Task tool is unavailable) with a `<verify_assignment>` block:
+1. Print: `◆ Spawning doc verifier for {doc_path}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+   Spawn the `gsd-doc-verifier` agent (or invoke sequentially if Task tool is unavailable) with a `<verify_assignment>` block:
    ```xml
    <verify_assignment>
    doc_path: {relative path to the doc file, e.g. README.md}
@@ -849,7 +850,8 @@ This is NOT optional. Every doc in `review_queue` MUST be verified.
 
 For each doc in `review_queue` from the manifest:
 
-1. Spawn the `gsd-doc-verifier` agent with the same `<verify_assignment>` block as above.
+1. Print: `◆ Spawning doc verifier for {doc_path}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+   Spawn the `gsd-doc-verifier` agent with the same `<verify_assignment>` block as above.
 2. Read the result JSON from `.planning/tmp/verify-{doc_filename}.json`.
 3. Update the manifest: set `status: "verified"` for each review_queue doc processed.
 
@@ -900,7 +902,10 @@ Correct flagged inaccuracies by re-sending failing docs to the doc-writer in fix
 **For each iteration (while iteration < MAX_FIX_ITERATIONS and there are docs with failures):**
 
 1. For each doc with `claims_failed > 0` in the latest verification_results:
-   a. Read the current file content from disk.
+   a. Read the current file content from disk. Record the pre-fix line count:
+      ```bash
+      PRE_FIX_LINES=$(wc -l < "{doc_path}" 2>/dev/null || echo 0)
+      ```
    b. Spawn `gsd-doc-writer` agent (or invoke sequentially) with a fix assignment:
       ```xml
       <doc_assignment>
@@ -917,6 +922,15 @@ Correct flagged inaccuracies by re-sending failing docs to the doc-writer in fix
       </doc_assignment>
       ```
    c. One agent spawn per doc with failures. Do not batch multiple docs into one spawn.
+   d. **Post-fix truncation guard:** After the fix agent completes, check for file corruption:
+      ```bash
+      POST_FIX_LINES=$(wc -l < "{doc_path}" 2>/dev/null || echo 0)
+      ```
+      If `POST_FIX_LINES` is less than 10% of `PRE_FIX_LINES` (i.e. the file shrank by more than 90%), the fix agent corrupted the file via a full-file Write. Restore it immediately:
+      - Write the `existing_content` captured in step 1a back to `"{doc_path}"` using the Write tool
+      - Log: `WARNING: Fix agent corrupted {doc_path} ({POST_FIX_LINES} lines after fix, was {PRE_FIX_LINES}). Restored from pre-fix content. Failures for this doc require manual correction.`
+      - Mark this doc as `"fix-corrupted"` in the manifest; it will appear in remaining failures at the end
+      - Do NOT attempt to fix this doc again this iteration. It is still included in the step 2 re-verification (so its failures are counted) but no further fix agent will be dispatched for it in this iteration.
 
 2. After all fix agents complete, re-verify ALL docs (not just the ones that were fixed):
    - Re-run the same verification process as verify_docs step.

package/get-shit-done/workflows/eval-review.md

@@ -73,7 +73,7 @@ Build file list for auditor:
 ## 3. Spawn gsd-eval-auditor
 
 ```
-◆ Spawning eval auditor...
+◆ Spawning eval auditor... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Build prompt:

package/get-shit-done/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -49,7 +49,7 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 AGENT_SKILLS_MAPPER=$(gsd_run query agent-skills gsd-codebase-mapper)
 ```
 
-Then spawn `gsd-codebase-mapper` agents with the `--paths` hint:
+Then spawn `gsd-codebase-mapper` agents with the `--paths` hint (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```text
 Agent(

package/get-shit-done/workflows/execute-phase.md

@@ -491,7 +491,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    **{Plan ID}: {Plan Name}**
    {2-3 sentences: what this builds, technical approach, why it matters}
 
-   Spawning {count} agent(s)...
+   Spawning {count} agent(s)... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
    ---
    ```
 
@@ -1406,11 +1406,11 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 
 **Step A: Persist human verification items as UAT file.**
 
-Create `{phase_dir}/{phase_num}-HUMAN-UAT.md` using UAT template format:
+Create `{phase_dir}/{phase_num}-UAT.md` using UAT template format:
 
 ```markdown
 ---
-status: partial
+status: testing
 phase: {phase_num}-{phase_name}
 source: [{phase_num}-VERIFICATION.md]
 started: [now ISO]
@@ -1419,7 +1419,11 @@ updated: [now ISO]
 
 ## Current Test
 
-[awaiting human testing]
+number: 1
+name: {first human_verification item description}
+expected: |
+  {expected behavior from VERIFICATION.md}
+awaiting: user response
 
 ## Tests
 
@@ -1443,26 +1447,32 @@ blocked: 0
 
 Commit the file:
 ```bash
-gsd_run query commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-HUMAN-UAT.md"
+gsd_run query commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-UAT.md"
 ```
 
 **Step B: Present to user:**
 
 ```
-## ✓ Phase {X}: {Name} — Human Verification Required
+## ◷ Phase {X}: {Name} — Human Verification Needed
 
-All automated checks passed. {N} items need human testing:
+All automated checks passed. {N} item(s) require human testing before this phase can be marked complete:
 
 {From VERIFICATION.md human_verification section}
 
-Items saved to `{phase_num}-HUMAN-UAT.md` — they will appear in `/gsd:progress` and `/gsd:audit-uat`.
+Tests saved to `{phase_num}-UAT.md`.
 
-"approved" → continue | Report issues → gap closure
+When ready to run the tests:
+
+`/gsd:verify-work {X} ${GSD_WS}`
+
+Verify-work will walk you through each item and mark the phase complete when all tests pass.
 ```
 
-**If user says "approved":** Proceed to `update_roadmap`. The HUMAN-UAT.md file persists with `status: partial` and will surface in future progress checks until the user runs `/gsd:verify-work` on it.
+**Do NOT advance the phase from this branch.** Phase completion is handled by verify-work's auto-transition after UAT passes.
+
+**If user acknowledges without reporting issues (including "ok", "noted", "ack", "got it", "approved", "done", "yes", "pass", or similar):** Stop. The phase remains pending. No further orchestrator action — wait for the user to run `/gsd:verify-work`.
 
-**If user reports issues:** Proceed to gap closure as currently implemented.
+**If user reports issues now (before running verify-work):** Proceed to gap closure as currently implemented.
 
 **If gaps_found:**
 ```

package/get-shit-done/workflows/execute-plan.md

@@ -92,7 +92,7 @@ Otherwise: Apply checkpoint-based routing below.
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn Agent(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to: (1) FIRST assert `git symbolic-ref HEAD` resolves to a per-agent branch (NOT a protected ref like `main`/`master`/`develop`/`trunk`/`release/*`) and HALT with a blocker if not — never self-recover via `git update-ref refs/heads/<protected>` (#2924); (2) only after that assertion passes, run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, hard-reset the branch with `git reset --hard {EXPECTED_BASE}` before starting work, then verify with `[ "$(git rev-parse HEAD)" != "{EXPECTED_BASE}" ] && exit 1`. The HEAD assertion (Step 1) MUST run before any reset/checkout. This corrects a known issue where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD (affects all platforms — #2015) and prevents the destructive HEAD-on-master self-recovery path (#2924).
+**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → print `Spawning executor agent (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)` → spawn Agent(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to: (1) FIRST assert `git symbolic-ref HEAD` resolves to a per-agent branch (NOT a protected ref like `main`/`master`/`develop`/`trunk`/`release/*`) and HALT with a blocker if not — never self-recover via `git update-ref refs/heads/<protected>` (#2924); (2) only after that assertion passes, run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, hard-reset the branch with `git reset --hard {EXPECTED_BASE}` before starting work, then verify with `[ "$(git rev-parse HEAD)" != "{EXPECTED_BASE}" ] && exit 1`. The HEAD assertion (Step 1) MUST run before any reset/checkout. This corrects a known issue where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD (affects all platforms — #2015) and prevents the destructive HEAD-on-master self-recovery path (#2924).
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 

package/get-shit-done/workflows/explore.md

@@ -59,6 +59,8 @@ This would take ~30 seconds and might surface useful context.
 ```
 
 If yes, spawn a research agent:
+
+Print: `◆ Spawning explorer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
 ```
 Agent(
   prompt="Quick research: {specific_question}. Return 3-5 key findings, no more than 200 words.",

package/get-shit-done/workflows/help/modes/default.md

@@ -1,11 +1,11 @@
 <purpose>
-One-page newcomer-oriented tour of GSD. Output ONLY the `<reference>` content below. No additions.
+One-page newcomer-oriented tour of GSD Core. Output ONLY the `<reference>` content below. No additions.
 </purpose>
 
 <reference>
-# GSD — Get Shit Done
+# GSD Core — Git. Ship. Done.
 
-Plan-driven development for solo agentic work with Claude Code. GSD turns a vague idea into a hierarchical plan, then executes it phase by phase with state tracking and atomic commits.
+Plan-driven development for solo agentic work with Claude Code. GSD Core turns a vague idea into a hierarchical plan, then executes it phase by phase with state tracking and atomic commits.
 
 ## Start here (3 commands)
 

package/get-shit-done/workflows/help/modes/full.md

@@ -1,11 +1,11 @@
 <purpose>
-Display the complete GSD command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+Display the complete GSD Core command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
 </purpose>
 
 <reference>
-# GSD Command Reference
+# GSD Core Command Reference
 
-**GSD** (Get Shit Done) creates hierarchical project plans optimized for solo agentic development with Claude Code.
+**GSD Core** (Git. Ship. Done.) creates hierarchical project plans optimized for solo agentic development with Claude Code.
 
 ## Quick Start
 
@@ -418,10 +418,10 @@ Usage: `/gsd:ship 4` or `/gsd:ship 4 --draft`
 
 ---
 
-**`/gsd:review --phase N [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--all]`**
+**`/gsd:review --phase N [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--agy] [--all]`**
 Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
 
-- Detects available CLIs (gemini, claude, codex, coderabbit)
+- Detects available CLIs (gemini, claude, codex, coderabbit, agy)
 - Each CLI reviews plans independently with the same structured prompt
 - CodeRabbit reviews the current git diff (not a prompt) — may take up to 5 minutes
 - Produces REVIEWS.md with per-reviewer feedback and consensus summary

package/get-shit-done/workflows/import.md

@@ -197,6 +197,8 @@ Write the PLAN.md file to the target directory.
 
 Delegate validation to gsd-plan-checker:
 
+Print: "Delegating to gsd-plan-checker (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)"
+
 ```
 Agent({
   subagent_type: "gsd-plan-checker",

package/get-shit-done/workflows/ingest-docs.md

@@ -180,7 +180,7 @@ Collect the one-line confirmations from each classifier. If any classifier error
 
 <step name="synthesize">
 
-Spawn `gsd-doc-synthesizer` once:
+Spawn `gsd-doc-synthesizer` once (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```
 Agent({
@@ -247,7 +247,7 @@ Proceed to routing silently, or optionally display `GSD > No conflicts. Auto-res
 
 Audit PROJECT.md field requirements that `gsd-roadmapper` expects. For fields derivable from `.planning/intel/SYNTHESIS.md` (project scope, goals/non-goals, constraints, locked decisions), synthesize from the intel. For fields NOT derivable (project name, developer-facing success metric, target runtime), prompt via `AskUserQuestion` one at a time — minimal question set, no interrogation.
 
-Delegate to `gsd-roadmapper`:
+Delegate to `gsd-roadmapper` (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```
 Agent({

package/get-shit-done/workflows/manager.md

@@ -269,7 +269,7 @@ Important: You are running in the background. Do NOT use AskUserQuestion — mak
 Display:
 
 ```
-◆ Spawning planner for Phase {N}: {phase_name}...
+◆ Spawning planner for Phase {N}: {phase_name}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Loop back to dashboard step.
@@ -303,7 +303,7 @@ Important: You are running in the background. Do NOT use AskUserQuestion — mak
 Display:
 
 ```
-◆ Spawning executor for Phase {N}: {phase_name}...
+◆ Spawning executor for Phase {N}: {phase_name}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Loop back to dashboard step.

package/get-shit-done/workflows/map-codebase.md

@@ -144,6 +144,8 @@ Use Agent tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model
 
 **CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
 
+Print: "Spawning 4 parallel codebase mapper agents (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)"
+
 **Agent 1: Tech Focus**
 
 ```text

package/get-shit-done/workflows/new-milestone.md

@@ -287,7 +287,7 @@ AskUserQuestion: "Research the domain ecosystem for new features before defining
  GSD ► RESEARCHING
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning 4 researchers in parallel...
+◆ Spawning 4 researchers in parallel... (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)
   → Stack, Features, Architecture, Pitfalls
 ```
 
@@ -455,7 +455,7 @@ gsd_run query commit "docs: define milestone v[X.Y] requirements" --files .plann
  GSD ► CREATING ROADMAP
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning roadmapper...
+◆ Spawning roadmapper... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 **Starting phase number:**

package/get-shit-done/workflows/new-project.md

@@ -869,7 +869,7 @@ Check if this is greenfield or subsequent milestone:
 Display spawning indicator:
 
 ```
-◆ Spawning 4 researchers in parallel...
+◆ Spawning 4 researchers in parallel... (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)
   → Stack research
   → Features research
   → Architecture research
@@ -1265,7 +1265,7 @@ Display stage banner:
  GSD ► CREATING ROADMAP
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning roadmapper...
+◆ Spawning roadmapper... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 **ROADMAP.md template — mode-aware emit.** When generating the initial ROADMAP.md:

package/get-shit-done/workflows/plan-phase.md

@@ -99,7 +99,7 @@ The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--force` (override closed-phase gate, see §1.5)).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--force` (override closed-phase gate, see §1.5)).
 
 **`--research-phase <N>` — research-only mode (#3042 + #3044).** When this flag is present, parse `<N>` as the phase number (overrides any positional phase argument), set `RESEARCH_ONLY=true`, and treat the rest of this workflow as a research-dispatch only — the planner spawn (step 8), plan-checker, verification, gaps, bounce, and post-planning-gaps blocks all skip on `RESEARCH_ONLY`. Use this for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops. Replaces the deleted `/gsd-research-phase` command.
 
@@ -127,10 +127,10 @@ Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from in
 ```bash
 MVP_FLAG_ARG=""
 if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--tdd([[:space:]]|$) ]]; then TDD_MODE=true; fi
 ```
 
-Defer the `phase.mvp-mode` query until `PHASE` is finalized (after explicit argument parsing/fallback phase detection + validation).
-The verb returns `true|false`. Full result also exposes `source` (`cli_flag` | `roadmap` | `config` | `none`) for diagnostics. The mode is **all-or-nothing per phase** (PRD decision Q1) — never selective per task.
+Defer the `phase.mvp-mode` query until `PHASE` is finalized (after explicit argument parsing/fallback phase detection + validation). The verb returns `true|false`; full result also exposes `source` (`cli_flag` | `roadmap` | `config` | `none`) for diagnostics. Mode is **all-or-nothing per phase** (PRD decision Q1).
 
 **Walking Skeleton gate.** When `MVP_MODE=true` AND `phase_number == "01"` AND there are zero prior phase summaries (new project), the planner runs in **Walking Skeleton mode** (per PRD decision Q2 — new projects only). Detect with:
 
@@ -480,7 +480,7 @@ Display banner:
  GSD ► RESEARCHING PHASE {X}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning researcher...
+◆ Spawning researcher... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 ### Spawn gsd-phase-researcher
@@ -625,11 +625,11 @@ Check if phase has frontend indicators:
 PHASE_SECTION=$(gsd_run query roadmap.get-phase "${PHASE}" 2>/dev/null)
 # Shell-free word-boundary gate (#3718): Node.js helper — no locale env-var dependency.
 # Reads via stdin to avoid OS ARG_MAX limits on large phase text.
-# Path anchored to repo root; falls back to CWD if git is unavailable
-# Exit codes mirror grep: 0 = UI tokens found, 1 = not found.
-GSD_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
-printf '%s' "$PHASE_SECTION" | node "${GSD_REPO_ROOT}/bin/lib/ui-safety-gate.cjs" > /dev/null 2>&1
-HAS_UI=$?
+# Resolve the helper against the GSD install dir via RUNTIME_DIR (#448) — NOT the consuming
+# project's git root — falling back to git toplevel / $HOME/.claude. Exit codes mirror grep (0=UI,1=none).
+_GSD_RT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+UI_GATE_JS=$(for _c in "$_GSD_RT/get-shit-done/bin/lib/ui-safety-gate.cjs" "$_GSD_RT/bin/lib/ui-safety-gate.cjs" "$_GSD_RT/.claude/bin/lib/ui-safety-gate.cjs" "$HOME/.claude/get-shit-done/bin/lib/ui-safety-gate.cjs" "$HOME/.claude/bin/lib/ui-safety-gate.cjs"; do [ -f "$_c" ] && { echo "$_c"; break; }; done)
+if [ -n "$UI_GATE_JS" ]; then printf '%s' "$PHASE_SECTION" | node "$UI_GATE_JS" >/dev/null 2>&1; HAS_UI=$?; else echo "WARN: ui-safety-gate.cjs not found via RUNTIME_DIR/\$HOME (#448) — assuming UI present" >&2; HAS_UI=0; fi
 ```
 
 **If `HAS_UI` is 0 (frontend indicators found):**
@@ -815,7 +815,7 @@ Display banner:
  GSD ► PATTERN MAPPING PHASE {X}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning pattern mapper...
+◆ Spawning pattern mapper... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Pattern mapper prompt:
@@ -877,7 +877,7 @@ Display banner:
  GSD ► PLANNING PHASE {X}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning planner...
+◆ Spawning planner... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Planner prompt:
@@ -1040,7 +1040,7 @@ fi
 
 Display:
 ```text
-◆ Chunked mode: spawning outline planner...
+◆ Chunked mode: spawning outline planner... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Spawn the planner in **outline-only** mode — it must write only the outline manifest, not any
@@ -1087,7 +1087,7 @@ For each plan entry extracted from `PLAN-OUTLINE.md`:
 
 2. Display:
    ```text
-   ◆ Chunked mode: planning {plan_id} ({k}/{N})...
+   ◆ Chunked mode: planning {plan_id} ({k}/{N})... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
    ```
 
 3. Spawn the planner in **single-plan** mode — it must write exactly one PLAN.md file:
@@ -1225,7 +1225,7 @@ Display banner:
  GSD ► VERIFYING PLANS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning plan checker...
+◆ Spawning plan checker... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
 Checker prompt:
@@ -1627,7 +1627,8 @@ one place before execution begins.
 ```bash
 POST_PLANNING_GAPS=$(gsd_run query config-get workflow.post_planning_gaps --default true 2>/dev/null || echo true)
 if [ "$POST_PLANNING_GAPS" = "true" ]; then
-  node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" gap-analysis --phase-dir "${PHASE_DIR}"
+  # Scope to this phase's mapped REQ-IDs (#447); null/TBD skips the requirements comparison (CONTEXT.md decisions still reported), mirroring §13.
+  node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" gap-analysis --phase-dir "${PHASE_DIR}" --phase-req-ids "$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" query init.plan-phase "$PHASE" --pick phase_req_ids 2>/dev/null || echo TBD)"
 fi
 ```