@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/workflows/check-todos.md

@@ -19,7 +19,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `todo_count`, `todos`, `pending_dir`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 If `todo_count` is 0:
 ```

package/gsd-core/workflows/cleanup.md

@@ -19,7 +19,7 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 
 <step name="identify_completed_milestones">

package/gsd-core/workflows/code-review/steps/structural-pre-pass.md

@@ -27,21 +27,23 @@ FALLOW_STDERR_TMP=$(mktemp)
 # Phase scope uses fallow's native changed-files scoping (--changed-since <base>).
 # Derive the phase base commit; if none is found, fall back to repo scope (fallow
 # auto-detects the base branch). #3191/#3503: the grep is the SAME anchored,
-# POSIX-portable conventional-commit-scope derivation the workflow's Tier-3
-# scope step uses (subject-line `type((phase-)?N(-plan)?):`, padded or unpadded
-# phase spelling). Free prose in commit bodies — "deferred to Phase N per
-# D-09", "### Phase N" format examples — never captures the base, and a bare
-# digit substring matches version strings, dates, and other phases; the oldest
-# such false match would silently widen --changed-since far past the phase.
+# Phase-directory-anchor derivation, lockstep with the workflow's Tier-3
+# scope step (#3191/#3995): base = the parent of the first commit that added
+# anything under the phase's own directory. Commit subjects carry no milestone
+# bound — a same-numbered phase in a previous milestone used to win the grep.
 FALLOW_SCOPE_ARGS=()
 if [ \"$FALLOW_SCOPE\" = \"phase\" ]; then
-  PHASE_SCOPE_NUM=\"${PADDED_PHASE}\"
-  case \"$PADDED_PHASE\" in
-    0[0-9]*) PHASE_SCOPE_NUM=\"${PADDED_PHASE#0}|${PADDED_PHASE}\" ;;
-  esac
-  FALLOW_PHASE_COMMITS=$(git log --oneline --all --extended-regexp --grep=\"^[[:alpha:]]+!?\((phase-)?(${PHASE_SCOPE_NUM})(-[0-9]+)?\)!?:\" --format=\"%H\" 2>/dev/null)
-  if [ -n \"$FALLOW_PHASE_COMMITS\" ]; then
-    FALLOW_BASE=$(echo \"$FALLOW_PHASE_COMMITS\" | tail -1)^
+  # #3995: phase-directory anchor — same derivation as the Tier-3 scope step
+  # (lockstep per #3191). A phase number is unique within a milestone, not a
+  # repository; the former message grep matched previous milestones'
+  # same-numbered phases and tail -1 selected the oldest.
+  FALLOW_PHASE_START=$(git log --format=\"%H\" --diff-filter=A -- \"${PHASE_DIR}\" 2>/dev/null | tail -1)
+  if [ -n \"$FALLOW_PHASE_START\" ]; then
+    if git rev-parse \"${FALLOW_PHASE_START}^\" >/dev/null 2>&1; then
+      FALLOW_BASE=\"${FALLOW_PHASE_START}^\"
+    else
+      FALLOW_BASE=\"${FALLOW_PHASE_START}\"
+    fi
     FALLOW_SCOPE_ARGS=(--changed-since \"$FALLOW_BASE\")
   fi
 fi

package/gsd-core/workflows/code-review-fix.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Auto-fix issues from REVIEW.md. Validates phase, checks config gate, verifies REVIEW.md exists and has fixable issues, spawns gsd-code-fixer agent, handles --auto iteration loop (capped at 3), commits REVIEW-FIX.md once at the end, and presents results.
 </purpose>

package/gsd-core/workflows/code-review.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Review source files changed during a phase for bugs, security issues, and code quality problems. Computes file scope (--files override > SUMMARY.md > git diff fallback), checks config gate, spawns gsd-code-reviewer agent, commits REVIEW.md, and presents results to user. When --fix is passed, delegates to code-review-fix.md after review to auto-apply findings via gsd-code-fixer.
 </purpose>
@@ -81,26 +83,36 @@ fi
 </step>
 
 <step name="check_config_gate">
-Check if code review is active via the capability registry:
+Check if code review is active via `workflow.code_review` (the capability's on/off toggle — independent of `workflow.code_review_point`, the loop-point selector; a manual invocation must work regardless of which automatic point is currently configured):
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(gsd_run loop render-hooks execute:post --raw)
+CODE_REVIEW_ENABLED=$(gsd_run query config-get workflow.code_review --raw 2>/dev/null || echo "true")
 ```
 
-Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
-
-If no active code-review step hook exists:
+If `CODE_REVIEW_ENABLED` is not `"true"`:
 ```
 Code review skipped (code-review capability inactive)
 ```
 Exit workflow.
 
-Default is active through the Capability Registry schema — only skip when the registry resolves no active code-review step hook. This check runs AFTER phase validation so invalid phase errors are shown first.
+Default is active (`workflow.code_review` schema default is `true`) — only skip when explicitly disabled. This check runs AFTER phase validation so invalid phase errors are shown first.
 </step>
 
 <step name="compute_file_scope">
 Three-tier scoping with explicit precedence:
 
+Compute the phase's last review commit, if any. This narrows Tiers 2 and 3 below to what
+changed since that review (wave-scoped reviews under `workflow.code_review_point=execute:wave:post`):
+
+```bash
+# #3661: incremental scoping — when this phase has a prior review, later tiers
+# narrow to what changed since it (wave-scoped reviews under
+# workflow.code_review_point=execute:wave:post). Empty on a phase's first review
+# (the entire execute:post-default path), in which case Tiers 2 and 3 below are
+# unchanged from today.
+LAST_REVIEW_COMMIT=$(git log --format=%H -1 -- "${PHASE_DIR}/${PADDED_PHASE}-REVIEW.md" 2>/dev/null)
+```
+
 **Tier 1 — --files override (highest precedence per D-08):**
 
 If FILES_OVERRIDE is set (from --files flag):
@@ -140,7 +152,18 @@ if [ -z "$FILES_OVERRIDE" ]; then
   REVIEW_FILES=()
   
   if [ -n "$SUMMARIES" ]; then
-    for summary in $SUMMARIES; do
+    # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+    # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+    # one iteration there.
+    for summary in $(printf '%s' "$SUMMARIES"); do
+      # #3661: skip a SUMMARY.md unchanged since the phase's last review — this
+      # summary's plan was already reviewed. No-op (every summary is "changed") when
+      # LAST_REVIEW_COMMIT is empty. Fails OPEN on any git error (file stays in scope)
+      # — never silently drop a file because a git command errored.
+      if [ -n "$LAST_REVIEW_COMMIT" ] && git diff --quiet "${LAST_REVIEW_COMMIT}" HEAD -- "$summary" 2>/dev/null; then
+        continue
+      fi
+
       # Extract key_files.created and key_files.modified using node for reliable YAML parsing
       # This avoids fragile awk parsing that breaks on indentation differences
       EXTRACTED=$(node -e "
@@ -222,17 +245,31 @@ surface — so a partial SUMMARY result can no longer silently mask the rest of
 # #3191: stay POSIX-ERE portable — the boundary is the closing paren + colon,
 # never \b (not a POSIX ERE token; under --extended-regexp it silently matches
 # nothing on macOS regex(3), making this fallback dead on Apple platforms).
-PHASE_SCOPE_NUM="${PADDED_PHASE}"
-case "${PADDED_PHASE}" in
-  0[0-9]*) PHASE_SCOPE_NUM="${PADDED_PHASE#0}|${PADDED_PHASE}" ;;
-esac
-PHASE_COMMITS=$(git log --oneline --all --extended-regexp --grep="^[[:alpha:]]+!?\((phase-)?(${PHASE_SCOPE_NUM})(-[0-9]+)?\)!?:" --format="%H" 2>/dev/null)
+# #3995: a phase number is unique within a MILESTONE, not a repository. The
+# former message grep had no milestone bound, and its tail -1 deliberately
+# selected the OLDEST matching subject — dragging in previous milestones'
+# same-numbered phases and taking a 7-file phase to a 3388-file scope (plus
+# the >50 depth downgrade). The phase's own directory is the unique identity:
+# base = the parent of the first commit that added anything under PHASE_DIR
+# (the same anchor class git-base-branch's phaseStartCommit uses for
+# complexity triggering). Message subjects demonstrably do not carry enough
+# information to identify a phase — this was the grep's fifth failure.
+# KNOWN RESIDUAL: git log -- <dir> does not follow renames, so a LATER
+# milestone that reuses BOTH number and slug re-creates the same literal
+# path and the oldest A-commit is the previous occupant's. Number+slug
+# reuse is the narrow trigger; the reported archived-milestone case (dirs
+# move under milestones/ on archive) is closed.
+PHASE_START=$(git log --format="%H" --diff-filter=A -- "${PHASE_DIR}" 2>/dev/null | tail -1)
 DIFF_BASE=""
-if [ -n "$PHASE_COMMITS" ]; then
-  DIFF_BASE=$(echo "$PHASE_COMMITS" | tail -1)^
-  # Verify the parent commit exists (first commit in repo has no parent)
-  if ! git rev-parse "${DIFF_BASE}" >/dev/null 2>&1; then
-    DIFF_BASE=$(echo "$PHASE_COMMITS" | tail -1)
+if [ -n "$LAST_REVIEW_COMMIT" ]; then
+  # #3661: a prior review exists — narrow the diff base to since that review
+  # (wave-scoped) instead of the whole phase.
+  DIFF_BASE="$LAST_REVIEW_COMMIT"
+elif [ -n "$PHASE_START" ]; then
+  if git rev-parse "${PHASE_START}^" >/dev/null 2>&1; then
+    DIFF_BASE="${PHASE_START}^"
+  else
+    DIFF_BASE="${PHASE_START}"
   fi
 fi
 
@@ -517,22 +554,27 @@ Compute the review output path:
 REVIEW_PATH="${PHASE_DIR}/${PADDED_PHASE}-REVIEW.md"
 ```
 
-Compute DIFF_BASE for agent context (in case agent needs it). #3191/#3503: this
-must be the SAME anchored, POSIX-portable conventional-commit-scope derivation
-the Tier-3 scope step uses — the reviewer agent consumes `diff_base` exactly
+Compute DIFF_BASE for agent context (in case agent needs it). #3191/#3995: this
+must be the SAME phase-directory-anchor derivation the Tier-3 scope step uses —
+the reviewer agent consumes `diff_base` exactly
 when `files:` is empty, i.e. the same fail-closed scenario Tier 3 protects, so
 a divergent recomputation here re-arms the mis-scoping one tier down:
 ```bash
-PHASE_SCOPE_NUM="${PADDED_PHASE}"
-case "${PADDED_PHASE}" in
-  0[0-9]*) PHASE_SCOPE_NUM="${PADDED_PHASE#0}|${PADDED_PHASE}" ;;
-esac
-PHASE_COMMITS=$(git log --oneline --all --extended-regexp --grep="^[[:alpha:]]+!?\((phase-)?(${PHASE_SCOPE_NUM})(-[0-9]+)?\)!?:" --format="%H" 2>/dev/null)
-if [ -n "$PHASE_COMMITS" ]; then
-  DIFF_BASE=$(echo "$PHASE_COMMITS" | tail -1)^
-  # Verify the parent commit exists (first commit in repo has no parent)
-  if ! git rev-parse "${DIFF_BASE}" >/dev/null 2>&1; then
-    DIFF_BASE=$(echo "$PHASE_COMMITS" | tail -1)
+# #3995: a phase number is unique within a MILESTONE, not a repository. The
+# former message grep had no milestone bound, and its tail -1 deliberately
+# selected the OLDEST matching subject — dragging in previous milestones'
+# same-numbered phases and taking a 7-file phase to a 3388-file scope (plus
+# the >50 depth downgrade). The phase's own directory is the unique identity:
+# base = the parent of the first commit that added anything under PHASE_DIR
+# (the same anchor class git-base-branch's phaseStartCommit uses for
+# complexity triggering). Message subjects demonstrably do not carry enough
+# information to identify a phase — this was the grep's fifth failure.
+PHASE_START=$(git log --format="%H" --diff-filter=A -- "${PHASE_DIR}" 2>/dev/null | tail -1)
+if [ -n "$PHASE_START" ]; then
+  if git rev-parse "${PHASE_START}^" >/dev/null 2>&1; then
+    DIFF_BASE="${PHASE_START}^"
+  else
+    DIFF_BASE="${PHASE_START}"
   fi
 else
   DIFF_BASE=""
@@ -756,7 +798,7 @@ If `--files` validation fails unexpectedly on macOS, install coreutils or use ab
 
 <success_criteria>
 - [ ] Phase validated before config gate check
-- [ ] Capability gate checked (execute:post code-review hook)
+- [ ] Capability gate checked (`workflow.code_review` config key)
 - [ ] --fix/--all/--auto flags parsed via code-review-flags.cjs typed IR (not ad-hoc bash)
 - [ ] Depth resolved with validation (quick|standard|deep)
 - [ ] File scope computed with 3 tiers: --files > SUMMARY.md > git diff

package/gsd-core/workflows/complete-milestone.md

@@ -46,7 +46,7 @@ RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "
 gsd_run query audit-open
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 If the output contains open items (any section with count > 0):
 
@@ -775,7 +775,10 @@ CURRENT_BRANCH=$(git branch --show-current)
 git checkout ${BASE_BRANCH}
 
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  for branch in $PHASE_BRANCHES; do
+  # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+  # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+  # one iteration there.
+  for branch in $(printf '%s' "$PHASE_BRANCHES"); do
     git merge --squash "$branch"
     # Strip .planning/ from staging if commit_docs is false
     if [ "$COMMIT_DOCS" = "false" ]; then
@@ -804,7 +807,10 @@ CURRENT_BRANCH=$(git branch --show-current)
 git checkout ${BASE_BRANCH}
 
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  for branch in $PHASE_BRANCHES; do
+  # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+  # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+  # one iteration there.
+  for branch in $(printf '%s' "$PHASE_BRANCHES"); do
     git merge --no-ff --no-commit "$branch"
     # Strip .planning/ from staging if commit_docs is false
     if [ "$COMMIT_DOCS" = "false" ]; then
@@ -830,7 +836,10 @@ git checkout "$CURRENT_BRANCH"
 
 ```bash
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  for branch in $PHASE_BRANCHES; do
+  # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+  # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+  # one iteration there.
+  for branch in $(printf '%s' "$PHASE_BRANCHES"); do
     git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
   done
 fi

package/gsd-core/workflows/debug.md

@@ -30,7 +30,7 @@ One round-trip carries everything this workflow needs (#3149 — this call repla
 - `tdd_mode` — used as `{TDD_MODE}` in the session parameter blocks below.
 - `section_manifest` — `null` today, because this workflow declares no applicability-section markers of its own. **When it is `null`, read this workflow in full.** When it is present, read only the files named in its `read` array. `null` and an empty `included` array are NOT the same: `null` means "no manifest for this workflow", an empty `included` means "nothing applies".
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 ## 1a. LIST subcommand
 

package/gsd-core/workflows/diagnose-issues.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
 
@@ -216,7 +218,9 @@ Parse each return to extract:
 - root_cause: The diagnosed cause
 - files: Files involved
 - debug_path: Path to debug session file
-- suggested_fix: Hint for gap closure plan
+- fix_hint: NON-BINDING example route for the gap closure plan — the binding payload is
+  `root_cause`; a gap plan that removes the root cause by a smaller or different mechanism has
+  closed the gap in full
 
 If agent returns `## INVESTIGATION INCONCLUSIVE`:
 - root_cause: "Investigation inconclusive - manual review needed"

package/gsd-core/workflows/discuss-phase/modes/advisor.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # Advisor mode — research-backed comparison tables
 
 > **Lazy-loaded and gated.** The parent `workflows/discuss-phase.md` Reads

package/gsd-core/workflows/discuss-phase/modes/all.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --all mode — auto-select ALL gray areas, discuss interactively
 
 > **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when

package/gsd-core/workflows/discuss-phase/modes/analyze.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --analyze mode — trade-off tables before each question
 
 > **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`

package/gsd-core/workflows/discuss-phase/modes/auto.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --auto mode — fully autonomous discuss-phase
 
 > **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when

package/gsd-core/workflows/discuss-phase/modes/batch.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --batch mode — grouped question batches
 
 > **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`

package/gsd-core/workflows/discuss-phase/modes/chain.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --chain mode — interactive discuss, then auto-advance
 
 > **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when

package/gsd-core/workflows/discuss-phase/modes/default.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # Default mode — interactive discuss-phase
 
 > **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when no

package/gsd-core/workflows/discuss-phase/modes/power.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --power mode — bulk question generation, async answering
 
 > **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when

package/gsd-core/workflows/discuss-phase/modes/text.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # --text mode — plain-text overlay (no AskUserQuestion)
 
 > **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`

package/gsd-core/workflows/discuss-phase/templates/context.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # CONTEXT.md template — for discuss-phase write_context step
 
 > **Lazy-loaded.** Read this file only inside the `write_context` step of

package/gsd-core/workflows/discuss-phase/templates/discussion-log.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # DISCUSSION-LOG.md template — for discuss-phase git_commit step
 
 > **Lazy-loaded.** Read this file only inside the `git_commit` step of

package/gsd-core/workflows/discuss-phase-assumptions.md

@@ -73,7 +73,7 @@ AGENT_SKILLS_ANALYZER=$(gsd_run query agent-skills gsd-assumptions-analyzer)
 ANALYZER_MODEL=$(gsd_run query resolve-model gsd-assumptions-analyzer --raw)
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
 `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`,

package/gsd-core/workflows/discuss-phase-power.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Power user mode for discuss-phase. Generates ALL questions upfront into a JSON state file and an HTML companion UI, then waits for the user to answer at their own pace. When the user signals readiness, processes all answers in one pass and generates CONTEXT.md.
 

package/gsd-core/workflows/discuss-phase.md

@@ -122,7 +122,7 @@ AGENT_SKILLS_ADVISOR=$(gsd_run query agent-skills gsd-advisor-researcher)
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 **If `phase_found` is false:**
 ```

package/gsd-core/workflows/do.md

@@ -13,7 +13,7 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 <step name="validate">
 **Check for input.**
@@ -41,23 +41,31 @@ Track whether `.planning/` exists — some routes require it, others don't.
 <step name="route">
 **Match intent to command.**
 
-Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching** rule:
+Evaluate `$ARGUMENTS` against these routing rules. Rules are ordered **most-specific first**: apply the **first matching** rule, and never let a generic keyword rule ("set up", "spike", "review") preempt a more specific operation that also matches ("set up this existing codebase", "wrap up the spike findings", "review the changed source code").
 
 | If the text describes... | Route to | Why |
 |--------------------------|----------|-----|
-| Starting a new greenfield project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
-| First-time setup for an existing codebase, brownfield onboarding | `/gsd:onboard` | Safe map → docs ingest → project setup sequence |
+| First-time setup for an existing codebase, brownfield onboarding, "onboard this codebase" | `/gsd:onboard` | Safe map → docs ingest → project setup sequence |
+| Starting a new greenfield project, "set up", "initialize" (no existing codebase named) | `/gsd:new-project` | Needs full project initialization |
 | Mapping or analyzing an existing codebase map | `/gsd:map-codebase` | Codebase discovery or refresh |
 | A bug, error, crash, failure, or something broken | `/gsd:debug` | Needs systematic investigation |
-| Spiking, "test if", "will this work", "experiment", "prove this out", validate feasibility | `/gsd:spike` | Throwaway experiment to validate feasibility |
-| Sketching, "mockup", "what would this look like", "prototype the UI", "design this", explore visual direction | `/gsd:sketch` | Throwaway HTML mockups to explore design |
 | Wrapping up spikes, "package the spikes", "consolidate spike findings" | `/gsd:spike --wrap-up` | Package spike findings into reusable skill |
 | Wrapping up sketches, "package the designs", "consolidate sketch findings" | `/gsd:sketch --wrap-up` | Package sketch findings into reusable skill |
+| Spiking, "test if", "will this work", "experiment", "prove this out", validate feasibility | `/gsd:spike` | Throwaway experiment to validate feasibility |
+| Sketching, "mockup", "what would this look like", "prototype the UI", "design this", explore visual direction | `/gsd:sketch` | Throwaway HTML mockups to explore design |
+| Reviewing changed source code for bugs, security issues, or code quality ("code review the changes") | `/gsd:code-review` | Source review of phase-changed files |
+| Requesting peer review of phase plans from another AI CLI ("plan review", "review the plan") | `/gsd:review` | Cross-AI plan review |
+| Reviewing or hardening implemented UI ("visual audit", "review the UI") | `/gsd:ui-review` | Retroactive 6-pillar visual audit |
+| Verifying security mitigations of a completed phase ("security check", "secure phase N") | `/gsd:secure-phase` | Retroactive threat-mitigation verification |
+| Auditing milestone completion against original intent ("audit the milestone") | `/gsd:audit-milestone` | Milestone audit against original intent |
+| An autonomous audit-to-fix pass ("audit and fix", "audit the repo and fix what it finds") | `/gsd:audit-fix` | Audit-to-fix pipeline |
+| Generating or updating project documentation ("update the docs", "documentation update") | `/gsd:docs-update` | Docs verified against the codebase |
 | Exploring, researching, comparing, or "how does X work" | `/gsd:explore` | Socratic ideation and idea routing |
 | Discussing vision, "how should X look", brainstorming | `/gsd:discuss-phase` | Needs context gathering |
-| A complex task: refactoring, migration, multi-file architecture, system redesign | `/gsd:phase` | Needs a full phase with plan/build cycle |
 | Planning a specific phase or "plan phase N" | `/gsd:plan-phase` | Direct planning request |
-| Executing a phase or "build phase N", "run phase N" | `/gsd:execute-phase` | Direct execution request |
+| Executing a phase or "build phase N", "run phase N" (SDD dependency-aware wave execution) | `/gsd:execute-phase` | Direct execution request |
+| Adding, inserting, removing, or editing phases in the roadmap ("multi-phase", roadmap phase management) | `/gsd:phase` | Roadmap phase CRUD |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/gsd:plan-phase` | Needs a full phase with plan/build cycle |
 | Running all remaining phases automatically | `/gsd:autonomous` | Full autonomous execution |
 | A review or quality concern about existing work | `/gsd:verify-work` | Needs verification |
 | Checking progress, status, "where am I" | `/gsd:progress` | Status check |
@@ -73,7 +81,7 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching**
 
 ```
 "Refactor the authentication system" could be:
-1. /gsd:phase — Full planning cycle (recommended for multi-file refactors)
+1. /gsd:plan-phase — Full planning cycle (recommended for multi-file refactors)
 2. /gsd:quick — Quick execution (if scope is small and clear)
 
 Which approach fits better?
@@ -92,12 +100,33 @@ Which approach fits better?
 ```
 </step>
 
+<step name="confirm">
+**Confirm the route before dispatching (REQ-DO-03).**
+
+Before invoking anything, ask the user to confirm the displayed route via AskUserQuestion:
+
+```
+Route to {chosen command}?
+1. Yes — proceed with {chosen command} (recommended)
+2. Choose a different command
+3. Cancel — do not dispatch
+```
+
+- **Yes / proceed:** continue to the dispatch step.
+- **Choose a different command:** present the 2-3 next-best routes from the routing table as options and loop back through display + confirm with the new selection.
+- **Cancel:** stop. Do not invoke any command.
+
+**TEXT_MODE:** present the same choices as a plain-text numbered list and ask the user to type their choice number, exactly like other AskUserQuestion calls in this workflow.
+</step>
+
 <step name="dispatch">
-**Invoke the chosen command.**
+**Invoke the chosen command with only the arguments it accepts.**
 
-Run the selected `/gsd-*` command, passing `$ARGUMENTS` as args.
+Read the chosen command's frontmatter `argument-hint` (in `commands/gsd/<name>.md`) and forward **only arguments that command accepts**. Do NOT pass the full freeform sentence wholesale.
 
-If the chosen command expects a phase number and one wasn't provided in the text, extract it from context or ask via AskUserQuestion.
+- If the command expects a phase number or flags only (e.g. `/gsd:verify-work [phase number]`, `/gsd:plan-phase`, `/gsd:execute-phase`), extract the phase number / flags from the input; if none was provided, extract it from context or ask via AskUserQuestion. Drop the surrounding prose.
+- If the command explicitly accepts a freeform task description (e.g. `/gsd:quick`, `/gsd:debug`, `/gsd:spike`, `/gsd:sketch`), forward the relevant portion of `$ARGUMENTS` as the description.
+- If the command takes no arguments, invoke it without arguments.
 
 After invoking the command, stop. The dispatched command handles everything from here.
 </step>
@@ -110,6 +139,7 @@ After invoking the command, stop. The dispatched command handles everything from
 - [ ] Ambiguity resolved via user question (if needed)
 - [ ] Project existence checked for routes that require it
 - [ ] Routing decision displayed before dispatch
-- [ ] Command invoked with appropriate arguments
+- [ ] Route confirmed by the user before dispatch (REQ-DO-03), with TEXT_MODE equivalent
+- [ ] Command invoked with only the arguments it accepts (argument-hint aware; freeform text only where the command takes a freeform description)
 - [ ] No work done directly — dispatcher only
 </success_criteria>

package/gsd-core/workflows/docs-update.md

@@ -34,7 +34,7 @@ Extract from init JSON:
 - `monorepo_workspaces` — array of workspace glob patterns (empty if not a monorepo)
 - `section_manifest` — parsed from `INIT_DOCS_UPDATE` (not `INIT`); gates the `dispatch-monorepo-packages` section below
 - `project_root` — absolute path to the project root
-- `response_language` — if set, present all user-facing questions, prompts, and explanations in this workflow in that language; technical terms, code, file paths, and subagent prompts stay in English
+- `response_language` — if set, present all user-facing output of this workflow in that language — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations; technical terms, code, file paths, and subagent prompts stay in English
 </step>
 
 <step name="classify_project">

package/gsd-core/workflows/edit-phase.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Edit any field of an existing phase in ROADMAP.md in place. The phase number and position are always preserved. Guarded against in-progress and completed phases unless --force is passed. Validates depends_on references before writing. Shows a diff and requests confirmation before writing.
 </purpose>

package/gsd-core/workflows/eval-review.md

@@ -19,7 +19,7 @@ INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
 

package/gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # Step: codebase_drift_gate
 
 Post-execution structural drift detection (#2003). Runs after the last wave

package/gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md

@@ -161,6 +161,18 @@ Assign the composed prompt to a shell variable so it can be passed as one argume
 #      no host subagent machinery, so the role definition must ride the prompt
 #      (#3637 acceptance: resolved agent instructions as launch-level
 #      instructions + provenance of which role definition was used).
+# Resolve TDD-applicability for THIS plan (#4266/#4272) — fail closed on
+# command failure, mirroring the ISOLATION resolution above: an absent
+# verdict must never silently resolve to "not TDD" (ADR-3473 §8.4), since
+# that would silently drop a real TDD plan's RED/GREEN/REFACTOR procedure.
+_TDD_APPLICABLE_RAW=$(gsd_run query phase.tdd-applicable "{phase_dir}/{plan_file}" --pick applicable 2>/dev/null)
+_TDD_APPLICABLE_RC=$?
+if [ $_TDD_APPLICABLE_RC -ne 0 ]; then
+  echo "FATAL: could not resolve TDD-applicability for plan {plan_number} — 'gsd_run query phase.tdd-applicable' failed. Refusing to guess whether this dispatch needs the TDD procedure. Halting." >&2
+  exit 1
+fi
+TDD_APPLICABLE="$_TDD_APPLICABLE_RAW"
+
 EXECUTOR_PROMPT='<objective>
 Execute plan {plan_number} of phase {phase_number}-{phase_name}.
 Commit each task atomically. Create SUMMARY.md.
@@ -181,7 +193,7 @@ the executor workflow from repository search.
   SUMMARY commit semantics and the gitignored-planning skip contract)
 - summary.md template
 - checkpoints.md
-- tdd.md
+${TDD_APPLICABLE ? "- tdd.md" : ""}  # #3990/#4265: only when this dispatch is TDD (plan type: tdd, a tdd="true" task, or workflow.tdd_mode config)
 - worktree-path-safety.md
 - agents/gsd-executor.md (the ROLE DEFINITION you are executing — its steps
   0/0a/0b per-commit HEAD/cwd-drift/path-guard discipline applies to every
@@ -257,6 +269,10 @@ printf '%s' "$EXECUTOR_PROMPT" | grep -q '\${AGENT_SKILLS}' && {
   echo "FATAL: executor prompt for plan {plan_number} still contains the un-substituted \${AGENT_SKILLS} marker — the role definition was not spliced in (#3637). Halting." >&2
   exit 1
 }
+printf '%s' "$EXECUTOR_PROMPT" | grep -q '\${TDD_APPLICABLE' && {
+  echo "FATAL: executor prompt for plan {plan_number} still contains the un-substituted \${TDD_APPLICABLE marker — the TDD-applicability decision was not resolved into the prompt (#4266). Halting." >&2
+  exit 1
+}
 ```
 
 The prompt body must contain no single-quote character, since the assignment above is single-quoted; keep apostrophes out of it when editing.

package/gsd-core/workflows/execute-phase/steps/per-plan-worktree-gate.md

@@ -48,12 +48,18 @@ if [ -n "$SUBMODULE_PATHS" ] && [ "$USE_WORKTREES_FOR_PLAN" != "false" ]; then
     # submodule "vendor/foo".
     INTERSECT=""
     set -f  # disable globbing while iterating literal patterns
-    for sm_raw in $SUBMODULE_PATHS; do
+    # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+    # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+    # one iteration there.
+    for sm_raw in $(printf '%s' "$SUBMODULE_PATHS"); do
       # Normalize submodule path: strip ./ prefix and trailing /
       sm="${sm_raw#./}"
       sm="${sm%/}"
       [ -z "$sm" ] && continue
-      for pf_raw in $PLAN_SCOPE_PATHS; do
+      # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+      # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+      # one iteration there.
+      for pf_raw in $(printf '%s' "$PLAN_SCOPE_PATHS"); do
         # Normalize planned path the same way
         pf="${pf_raw#./}"
         pf="${pf%/}"