@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -19,7 +19,33 @@ Parse arguments and load project state:
 ```bash
 _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 PHASE_ARG="${1}"
-INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
+
+# Parse all code-review flags into a structured IR via code-review-flags.cjs.
+# This is the canonical flag-parsing surface — do not replicate inline bash parsing
+# for --fix/--all/--auto here; the module handles all flag extraction and implication
+# logic (e.g., --all and --auto imply --fix). Resolved BEFORE the init call below so
+# the section-manifest gate forwards the RESOLVED (post-implication) fix decision, not
+# just a literal --fix token check.
+FLAGS_JSON=$(node -e "
+  const { parseCodeReviewFlags } = require('./gsd-core/bin/lib/code-review-flags.cjs');
+  const flags = parseCodeReviewFlags(process.argv.slice(1));
+  process.stdout.write(JSON.stringify(flags));
+" -- "$@" 2>/dev/null)
+
+# Extract individual flag values from the IR
+FIX_FLAG=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).fix))")
+FIX_ALL=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).all))")
+FIX_AUTO=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).auto))")
+DEPTH_OVERRIDE=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).depth)")
+FILES_OVERRIDE=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).files)")
+
+# Forward the resolved fix decision (--fix itself, or --all/--auto implying it) to
+# init.code-review so section_manifest's flag:--fix gating (dispatch-fix section)
+# matches code-review-flags.cjs's own implication logic rather than a raw token scan.
+FIX_PARAM=""
+if [ "$FIX_FLAG" = "true" ]; then FIX_PARAM="--fix"; fi
+
+INIT=$(gsd_run query init.code-review "${PHASE_ARG}" $FIX_PARAM)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_REVIEWER=$(gsd_run query agent-skills gsd-code-reviewer)
 # #2072: resolve the routed model so model_overrides / models.verification are honored
@@ -27,7 +53,7 @@ AGENT_SKILLS_REVIEWER=$(gsd_run query agent-skills gsd-code-reviewer)
 REVIEWER_MODEL=$(gsd_run query resolve-model gsd-code-reviewer --raw)
 ```
 
-Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
+Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`, `fallow_enabled`, `fallow_scope`, `fallow_profile`, `fallow_mcp`, `fallow_max_crap`.
 
 **Input sanitization (defense-in-depth):**
 ```bash
@@ -46,27 +72,6 @@ Error: Phase ${PHASE_ARG} not found. Run /gsd:progress to see available phases.
 
 This runs BEFORE config gate check so user errors are surfaced immediately regardless of config state.
 
-Parse optional flags from $ARGUMENTS using the typed flag parser:
-
-```bash
-# Parse all code-review flags into a structured IR via code-review-flags.cjs.
-# This is the canonical flag-parsing surface — do not replicate inline bash parsing
-# for --fix/--all/--auto here; the module handles all flag extraction and implication
-# logic (e.g., --all and --auto imply --fix).
-FLAGS_JSON=$(node -e "
-  const { parseCodeReviewFlags } = require('./gsd-core/bin/lib/code-review-flags.cjs');
-  const flags = parseCodeReviewFlags(process.argv.slice(1));
-  process.stdout.write(JSON.stringify(flags));
-" -- "$@" 2>/dev/null)
-
-# Extract individual flag values from the IR
-FIX_FLAG=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).fix))")
-FIX_ALL=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).all))")
-FIX_AUTO=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).auto))")
-DEPTH_OVERRIDE=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).depth)")
-FILES_OVERRIDE=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).files)")
-```
-
 If FILES_OVERRIDE is set, split by comma into array:
 ```bash
 if [ -n "$FILES_OVERRIDE" ]; then
@@ -231,8 +236,27 @@ Additionally, whenever a reliable diff base is available, cross-check the SUMMAR
 against the diff and warn about (then add) any changed files the SUMMARY extractor did not
 surface — so a partial SUMMARY result can no longer silently mask the rest of the phase.
 ```bash
-# Compute diff base from phase commits — fail closed if no reliable base found
-PHASE_COMMITS=$(git log --oneline --all --grep="${PADDED_PHASE}" --format="%H" 2>/dev/null)
+# Compute diff base from phase commits — fail closed if no reliable base found.
+# #3503: anchor the grep to GSD's own conventional-commit phase scopes — the
+# subject-line formats this system itself emits (docs(phase-N): from
+# execute-phase.md, plan scopes feat(N-MM):/test(N-MM): from references/tdd.md,
+# bare phase scopes docs(N):). The #2989/#3191 prose anchor "[Pp]hase N"
+# matched free prose in ANY commit body — planning commits forward-reference
+# later phases ("deferred to Phase N per D-09"), doc commits use "### Phase N"
+# as a format example — and tail -1 (oldest match) turned each false positive
+# into a base unboundedly before the phase, while GSD's own scope commits
+# never contain the literal "Phase N" at all. The ^ anchor makes this a
+# subject-line match, so commit-body prose can never capture the base.
+# Workflows emit the UNPADDED roadmap phase number (docs(phase-6):) while
+# PADDED_PHASE is zero-padded ("06") — accept both spellings.
+# #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)
 DIFF_BASE=""
 if [ -n "$PHASE_COMMITS" ]; then
   DIFF_BASE=$(echo "$PHASE_COMMITS" | tail -1)^
@@ -296,7 +320,7 @@ fi
 
 **Post-processing (all tiers):**
 
-1. **Expand tilde paths:** SUMMARY.md `key-files` entries may record a `~/...`-prefixed path (e.g. `~/.claude/gsd-core/workflows/verify-phase.md`). Bash only tilde-expands a literal `~` written in source text, never one arriving as the value of an already-expanded variable, so every later `[ -f "$file" ]` check must see a real, expanded path or it misclassifies the file as deleted.
+1. **Expand tilde paths:** SUMMARY.md `key-files` entries may record a `~/...`-prefixed path (e.g. `~/.claude/gsd-core/workflows/verify-work.md`). Bash only tilde-expands a literal `~` written in source text, never one arriving as the value of an already-expanded variable, so every later `[ -f "$file" ]` check must see a real, expanded path or it misclassifies the file as deleted.
 ```bash
 EXPANDED_FILES=()
 for file in "${REVIEW_FILES[@]}"; do
@@ -389,20 +413,7 @@ Exit workflow. Do NOT spawn agent or create REVIEW.md.
 <step name="structural_pre_pass">
 Optional structural cross-module pass powered by fallow.
 
-Read fallow config gates:
-```bash
-FALLOW_ENABLED=$(gsd_run query config-get code_quality.fallow.enabled 2>/dev/null || echo "false")
-FALLOW_SCOPE=$(gsd_run query config-get code_quality.fallow.scope 2>/dev/null || echo "phase")
-FALLOW_PROFILE=$(gsd_run query config-get code_quality.fallow.profile 2>/dev/null || echo "standard")
-FALLOW_MCP=$(gsd_run query config-get code_quality.fallow.mcp 2>/dev/null || echo "false")
-# profile maps to a --max-crap threshold since fallow has no native profile concept.
-# minimal=50 (more lenient), standard=30 (default), strict=15 (tighter).
-case "$FALLOW_PROFILE" in
-  minimal) FALLOW_MAX_CRAP=50 ;;
-  strict)  FALLOW_MAX_CRAP=15 ;;
-  *)       FALLOW_MAX_CRAP=30 ;;  # standard (default)
-esac
-```
+Parse `fallow_enabled`, `fallow_scope`, `fallow_profile`, `fallow_mcp`, `fallow_max_crap` from the init JSON as `FALLOW_ENABLED`, `FALLOW_SCOPE`, `FALLOW_PROFILE`, `FALLOW_MCP`, `FALLOW_MAX_CRAP`. These are resolved once by `init.code-review` at init time — consuming the pre-resolved values here (instead of a `config-get` call inside this step) avoids gating this section's own inclusion on a fact its own body would otherwise compute (see `state:fallow-enabled` in docs/reference/workflow-fragments.md).
 
 Defaults are fail-closed and opt-in:
 - `enabled=false` (skip entirely)
@@ -410,88 +421,9 @@ Defaults are fail-closed and opt-in:
 - `profile=standard` (maps to `--max-crap 30`; minimal=50, standard=30, strict=15 — fallow has no native profile concept)
 - `mcp=false`
 
-When `FALLOW_ENABLED=true`:
-
-1) Resolve binary via PATH first, then `node_modules/.bin/fallow`.
-```bash
-FALLOW_BIN=$(FALLOW_CWD="$(pwd)" node -e "
-const { resolveFallowBinary } = require('./gsd-core/bin/lib/fallow-runner.cjs');
-const resolved = resolveFallowBinary({ cwd: process.env.FALLOW_CWD });
-if (resolved) process.stdout.write(resolved);
-")
-```
-
-2) If binary is missing, fail with actionable message:
-```bash
-if [ -z \"$FALLOW_BIN\" ]; then
-  echo \"Error: fallow is enabled but no binary was found.\"
-  echo \"Install fallow via \`npm install -D fallow\` or \`cargo install fallow\`.\"
-  # Exit workflow
-fi
-```
-
-3) Execute structural pass and persist JSON (bounded at 120s). Note: `fallow audit` exits 0 when clean and 1 when issues are found — BOTH are successful runs. Only a timeout (124), usage error (2), or crash yields no usable JSON; success is decided by whether the output parses as a valid fallow report, not by exit code:
-```bash
-FALLOW_JSON_PATH="${PHASE_DIR}/FALLOW.json"
-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).
-FALLOW_SCOPE_ARGS=()
-if [ \"$FALLOW_SCOPE\" = \"phase\" ]; then
-  FALLOW_PHASE_COMMITS=$(git log --oneline --all --grep=\"${PADDED_PHASE}\" --format=\"%H\" 2>/dev/null)
-  if [ -n \"$FALLOW_PHASE_COMMITS\" ]; then
-    FALLOW_BASE=$(echo \"$FALLOW_PHASE_COMMITS\" | tail -1)^
-    FALLOW_SCOPE_ARGS=(--changed-since \"$FALLOW_BASE\")
-  fi
-fi
-
-gsd_run run-with-timeout 120 -- \"$FALLOW_BIN\" audit --format json --quiet --max-crap \"$FALLOW_MAX_CRAP\" \"${FALLOW_SCOPE_ARGS[@]+\"${FALLOW_SCOPE_ARGS[@]}\"}\" > \"${FALLOW_JSON_PATH}.tmp\" 2>\"$FALLOW_STDERR_TMP\"
-FALLOW_EXIT=$?
-
-# fallow exits 0 (clean) or 1 (issues found) — BOTH are successful runs that produce a
-# valid JSON report. Only a timeout (124), usage error (2), or crash yields no usable JSON.
-# Decide success by whether the output parses as a fallow report, not by exit code.
-FALLOW_OK=$(FALLOW_TMP=\"${FALLOW_JSON_PATH}.tmp\" node -e \"
-  try {
-    const fs = require('fs');
-    const txt = fs.readFileSync(process.env.FALLOW_TMP, 'utf8');
-    const o = JSON.parse(txt);
-    process.stdout.write(o && typeof o === 'object' && 'verdict' in o ? '1' : '0');
-  } catch { process.stdout.write('0'); }
-\")
-if [ \"$FALLOW_OK\" != \"1\" ]; then
-  FALLOW_STDERR_SUMMARY=$(head -5 \"$FALLOW_STDERR_TMP\")
-  rm -f \"${FALLOW_JSON_PATH}.tmp\" \"$FALLOW_STDERR_TMP\"
-  # #2667: distinguish a hard EXECUTION failure (the binary was found at step 1
-  # but would not run) from the binary-missing path (step 2). Exit 124 = timeout,
-  # 2 = usage error, 125 = spawn failure (e.g. Windows EINVAL on a .cmd shim —
-  # CVE-2024-27980, now mediated by run-with-timeout), 126/127 = not executable /
-  # not found. A non-zero exit here with a resolved binary means fallow is
-  # installed but did not produce a report — surface that loudly so a Windows
-  # user does not mistake it for "fallow absent".
-  case \"$FALLOW_EXIT\" in
-    124) FALLOW_FAIL_KIND=\"timed out\" ;;
-    2)   FALLOW_FAIL_KIND=\"usage error\" ;;
-    125) FALLOW_FAIL_KIND=\"spawn failure (the binary was found but did not start — e.g. a Windows .cmd shim; run-with-timeout mediates this)\" ;;
-    126) FALLOW_FAIL_KIND=\"not executable\" ;;
-    127) FALLOW_FAIL_KIND=\"not found\" ;;
-    *)   FALLOW_FAIL_KIND=\"crashed\" ;;
-  esac
-  echo \"WARNING: fallow structural pre-pass failed (${FALLOW_FAIL_KIND}, exit ${FALLOW_EXIT}): ${FALLOW_STDERR_SUMMARY}\"
-  FALLOW_JSON_PATH=\"\"
-else
-  mv \"${FALLOW_JSON_PATH}.tmp\" \"$FALLOW_JSON_PATH\"
-  rm -f \"$FALLOW_STDERR_TMP\"
-fi
-```
-
-On any failure of the structural pre-pass (binary missing at step 2, or an execution failure here — timeout, spawn failure, crash, empty output, or unparseable JSON), the workflow continues with no `<structural_findings>` injection; the reviewer agent receives a normal review request. The WARNING above names the failure KIND so a hard execution failure (e.g. a Windows `.cmd` spawn failure) is not mistaken for an absent optional dependency.
-
-4) Optional MCP bridge path (runtime-dependent):
-- If `FALLOW_MCP=true`, set reviewer input mode to MCP-backed structural findings.
-- Otherwise pass static JSON findings from `FALLOW.json`.
+<!-- gsd:section id="structural-pre-pass" when="state:fallow-enabled" -->
+If `section_manifest` is `null` or `"structural-pre-pass"` is in its `included` list: read and execute `gsd-core/workflows/code-review/steps/structural-pre-pass.md`. Otherwise skip — do not read the file.
+<!-- /gsd:section -->
 
 When disabled, set:
 ```bash
@@ -505,17 +437,29 @@ Compute the review output path:
 REVIEW_PATH="${PHASE_DIR}/${PADDED_PHASE}-REVIEW.md"
 ```
 
-Compute DIFF_BASE for agent context (in case agent needs it):
+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
+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_COMMITS=$(git log --oneline --all --grep="${PADDED_PHASE}" --format="%H" 2>/dev/null)
+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)
+  fi
 else
   DIFF_BASE=""
 fi
 ```
 
-Build files_to_read block for agent:
+Build required_reading block for agent:
 ```bash
 FILES_TO_READ=""
 for file in "${REVIEW_FILES[@]}"; do
@@ -570,9 +514,9 @@ Print: `◆ Spawning code reviewer... (runs in a subagent — no output until it
 
 ```
 Agent(subagent_type="gsd-code-reviewer", model="{REVIEWER_MODEL}", prompt="
-<files_to_read>
+<required_reading>
 ${FILES_TO_READ}
-</files_to_read>
+</required_reading>
 
 ${STRUCTURAL_FINDINGS_BLOCK}
 
@@ -636,45 +580,9 @@ fi
 ```
 </step>
 
-<step name="dispatch_fix">
-If the `--fix` flag was passed (`FIX_FLAG=true`), delegate to the `code-review-fix.md` workflow
-to auto-apply findings from the REVIEW.md that was just written (or that already existed).
-
-This step runs AFTER `commit_review` so REVIEW.md is guaranteed to be on disk before the fixer
-is invoked. If REVIEW.md was not created (agent failed, scope was empty, etc.), the `code-review-fix.md`
-workflow handles the missing-review error and exits cleanly.
-
-```bash
-if [ "$FIX_FLAG" = "true" ]; then
-  echo ""
-  echo "─────────────────────────────────────────────────────────────────"
-  echo "  --fix: delegating to code-review-fix.md"
-  echo "─────────────────────────────────────────────────────────────────"
-  echo ""
-
-  # Build the fix sub-arguments: pass phase arg plus any --all/--auto flags
-  FIX_ARGS="${PHASE_ARG}"
-  if [ "$FIX_ALL" = "true" ]; then
-    FIX_ARGS="${FIX_ARGS} --all"
-  fi
-  if [ "$FIX_AUTO" = "true" ]; then
-    FIX_ARGS="${FIX_ARGS} --auto"
-  fi
-
-  # Load and execute the code-review-fix workflow.
-  # The fix workflow is the canonical implementation for all fix logic:
-  # gsd-code-fixer agent dispatch, --auto iteration loop, REVIEW-FIX.md commit,
-  # and result presentation. Do not duplicate that logic here.
-  Workflow(workflow="gsd-core/workflows/code-review-fix.md", args="${FIX_ARGS}")
-
-  # Exit after fix workflow completes — present_results is for review-only output.
-  # The fix workflow has its own present_results step.
-  # Exit workflow.
-fi
-```
-
-If `FIX_FLAG` is false, skip this step entirely and proceed to `present_results`.
-</step>
+<!-- gsd:section id="dispatch-fix" when="flag:--fix" -->
+If `section_manifest` is `null` or `"dispatch-fix"` is in its `included` list: read and execute `gsd-core/workflows/code-review/steps/dispatch-fix.md`. Otherwise skip — do not read the file; proceed to `present_results`.
+<!-- /gsd:section -->
 
 <step name="present_results">
 Read the REVIEW.md YAML frontmatter to extract finding counts.

package/gsd-core/workflows/complete-milestone/steps/git-tag.md

@@ -0,0 +1,29 @@
+<step name="git_tag">
+
+Create git tag:
+
+```bash
+# Pre-check: skip if tag already exists (prevents silent failure on retry)
+if git rev-parse "v[X.Y]" >/dev/null 2>&1; then echo "Tag v[X.Y] already exists, skipping"; exit 0; fi
+git tag -a v[X.Y] -m "v[X.Y] [Name]
+
+Delivered: [One sentence]
+
+Key accomplishments:
+- [Item 1]
+- [Item 2]
+- [Item 3]
+
+See .planning/MILESTONES.md for full details."
+```
+
+Confirm: "Tagged: v[X.Y]"
+
+Ask: "Push tag to remote? (y/n)"
+
+If yes:
+```bash
+git push origin v[X.Y]
+```
+
+</step>