@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/templates/user-setup.compact.md

@@ -0,0 +1,199 @@
+# User Setup Template
+
+Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required configuration that Claude cannot automate.
+
+**Purpose:** Document setup tasks that literally require human action - account creation, dashboard configuration, secret retrieval. Claude automates everything possible; this file captures only what remains.
+
+---
+
+## File Template
+
+```markdown
+# Phase {X}: User Setup Required
+
+**Generated:** [YYYY-MM-DD]
+**Phase:** {phase-name}
+**Status:** Incomplete
+
+Complete these items for the integration to function. Claude automated everything possible; these items require human access to external dashboards/accounts.
+
+## Environment Variables
+
+| Status | Variable | Source | Add to |
+|--------|----------|--------|--------|
+| [ ] | `ENV_VAR_NAME` | [Service Dashboard → Path → To → Value] | `.env.local` |
+| [ ] | `ANOTHER_VAR` | [Service Dashboard → Path → To → Value] | `.env.local` |
+
+## Account Setup
+
+[Only if new account creation is required]
+
+- [ ] **Create [Service] account**
+  - URL: [signup URL]
+  - Skip if: Already have account
+
+## Dashboard Configuration
+
+[Only if dashboard configuration is required]
+
+- [ ] **[Configuration task]**
+  - Location: [Service Dashboard → Path → To → Setting]
+  - Set to: [Required value or configuration]
+  - Notes: [Any important details]
+
+## Verification
+
+After completing setup, verify with:
+
+```bash
+# [Verification commands]
+```
+
+Expected results:
+- [What success looks like]
+
+---
+
+**Once all items complete:** Mark status as "Complete" at top of file.
+```
+
+---
+
+## When to Generate
+
+Generate `{phase}-USER-SETUP.md` when plan frontmatter contains `user_setup` field.
+
+**Trigger:** `user_setup` exists in PLAN.md frontmatter and has items.
+
+**Location:** Same directory as PLAN.md and SUMMARY.md.
+
+**Timing:** Generated during execute-plan.md after tasks complete, before SUMMARY.md creation.
+
+---
+
+## Frontmatter Schema
+
+In PLAN.md, `user_setup` declares human-required configuration:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "Payment processing requires API keys"
+    env_vars:
+      - name: STRIPE_SECRET_KEY
+        source: "Stripe Dashboard → Developers → API keys → Secret key"
+      - name: STRIPE_WEBHOOK_SECRET
+        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
+    dashboard_config:
+      - task: "Create webhook endpoint"
+        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
+        details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed, customer.subscription.*"
+    local_dev:
+      - "Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+      - "Use the webhook secret from CLI output for local testing"
+```
+
+---
+
+## The Automation-First Rule
+
+**USER-SETUP.md contains ONLY what Claude literally cannot do.**
+
+| Claude CAN Do (not in USER-SETUP) | Claude CANNOT Do (→ USER-SETUP) |
+|-----------------------------------|--------------------------------|
+| `npm install stripe` | Create Stripe account |
+| Write webhook handler code | Get API keys from dashboard |
+| Create `.env.local` file structure | Copy actual secret values |
+| Run `stripe listen` | Authenticate Stripe CLI (browser OAuth) |
+| Configure package.json | Access external service dashboards |
+| Write any code | Retrieve secrets from third-party systems |
+
+**The test:** "Does this require a human in a browser, accessing an account Claude doesn't have credentials for?"
+- Yes → USER-SETUP.md
+- No → Claude does it automatically
+
+---
+
+## Service-Specific Example
+
+<stripe_example>
+```markdown
+# Phase 10: User Setup Required
+
+**Generated:** 2025-01-14
+**Phase:** 10-monetization
+**Status:** Incomplete
+
+Complete these items for Stripe integration to function.
+
+## Environment Variables
+
+| Status | Variable | Source | Add to |
+|--------|----------|--------|--------|
+| [ ] | `STRIPE_SECRET_KEY` | Stripe Dashboard → Developers → API keys → Secret key | `.env.local` |
+| [ ] | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe Dashboard → Developers → API keys → Publishable key | `.env.local` |
+| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Developers → Webhooks → [endpoint] → Signing secret | `.env.local` |
+
+## Account Setup
+
+- [ ] **Create Stripe account** (if needed)
+  - URL: https://dashboard.stripe.com/register
+  - Skip if: Already have Stripe account
+
+## Dashboard Configuration
+
+- [ ] **Create webhook endpoint**
+  - Location: Stripe Dashboard → Developers → Webhooks → Add endpoint
+  - Endpoint URL: `https://[your-domain]/api/webhooks/stripe`
+  - Events to send:
+    - `checkout.session.completed`
+    - `customer.subscription.created`
+    - `customer.subscription.updated`
+    - `customer.subscription.deleted`
+
+- [ ] **Create products and prices** (if using subscription tiers)
+  - Location: Stripe Dashboard → Products → Add product
+  - Create each subscription tier
+  - Copy Price IDs to:
+    - `STRIPE_STARTER_PRICE_ID`
+    - `STRIPE_PRO_PRICE_ID`
+
+## Local Development
+
+For local webhook testing:
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+Use the webhook signing secret from CLI output (starts with `whsec_`).
+
+## Verification
+
+After completing setup:
+
+```bash
+# Verify build passes
+npm run build
+
+# Test webhook endpoint (should return 400 bad signature, not 500 crash)
+curl -X POST http://localhost:3000/api/webhooks/stripe \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Expected: Build passes, webhook returns 400 (signature validation working).
+
+---
+
+**Once all items complete:** Mark status as "Complete" at top of file.
+```
+</stripe_example>
+
+---
+
+## Guidelines
+
+**Never include:** Actual secret values. Steps Claude can automate (package installs, code changes).
+
+**Naming:** `{phase}-USER-SETUP.md` matches the phase number pattern.
+**Status tracking:** User marks checkboxes and updates status line when complete.
+**Searchability:** `grep -r "USER-SETUP" .planning/` finds all phases with user requirements.

package/gsd-core/templates/user-setup.md

@@ -171,9 +171,6 @@ Use the webhook signing secret from CLI output (starts with `whsec_`).
 After completing setup:
 
 ```bash
-# Check env vars are set
-grep STRIPE .env.local
-
 # Verify build passes
 npm run build
 
@@ -232,9 +229,6 @@ Complete these items for Supabase Auth to function.
 After completing setup:
 
 ```bash
-# Check env vars
-grep SUPABASE .env.local
-
 # Verify connection (run in project directory)
 npx supabase status
 ```
@@ -285,9 +279,6 @@ Complete these items for SendGrid email to function.
 After completing setup:
 
 ```bash
-# Check env var
-grep SENDGRID .env.local
-
 # Test email sending (replace with your test email)
 curl -X POST http://localhost:3000/api/test-email \
   -H "Content-Type: application/json" \

package/gsd-core/templates/verification-report.md

@@ -12,6 +12,11 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+covered_files: # #4155 — see agents/gsd-verifier.md's "Create VERIFICATION.md" step for what belongs here and how to compute it
+  - .planning/phases/XX-name/{phase_num}-{plan}-PLAN.md
+  - .planning/phases/XX-name/{phase_num}-{plan}-SUMMARY.md
+  - src/{changed-file}.cts
+covered_digest: "v1:sha256:{digest from verification.fingerprint}"
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised)
 behavior_unverified_items: # Only if behavior_unverified > 0 — the truths above as structured items; emitted regardless of overall status
   - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"

package/gsd-core/workflows/add-backlog.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 # Add Backlog Item Workflow
 
 Invoked by `/gsd:capture --backlog` (`commands/gsd/capture.md`).

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

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
 </purpose>

package/gsd-core/workflows/add-tests.md

@@ -40,7 +40,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `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.
 
 Verify the phase directory exists. If not:
 ```

package/gsd-core/workflows/add-todo.md

@@ -19,7 +19,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_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.
 
 Ensure directories exist:
 ```bash
@@ -145,8 +145,9 @@ files:
 <step name="update_state">
 If `.planning/STATE.md` exists:
 
-1. Use `todo_count` from init context (or re-run `init todos` if count changed)
-2. Update "### Pending Todos" under "## Accumulated Context"
+1. Re-run `gsd_run query init.todos` to get a fresh, post-write JSON snapshot (the count and rendering must reflect the change just made).
+2. **Fail-safe check (#2618):** if the JSON failed to parse, or `pending_read_ok` is not `true`, or `pending_todos_markdown` is not a string, do NOT touch the "### Pending Todos" section — leave it exactly as-is and continue to the next step. A partial or malformed `init.todos` result must never overwrite a good existing section.
+3. Otherwise, replace the entire body of "### Pending Todos" (under "## Accumulated Context") with the literal value of `pending_todos_markdown` — verbatim, one bullet per pending todo already rendered and length-capped by `init.todos`. Do not reformat, re-wrap, re-order, or hand-edit the bullets; do not append to the old body — replace it wholesale (this is what makes an old run-on-sentence section get superseded cleanly with no migration step).
 </step>
 
 <step name="git_commit">

package/gsd-core/workflows/ai-integration-phase.md

@@ -27,7 +27,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`, `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.
 
 **File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`.
 

package/gsd-core/workflows/analyze-dependencies.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/gsd:manager`.
 </purpose>

package/gsd-core/workflows/audit-fix.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Autonomous audit-to-fix pipeline. Runs an audit, parses findings, classifies each as
 auto-fixable vs manual-only, spawns executor agents for fixable issues, runs tests

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

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
 </purpose>

package/gsd-core/workflows/audit-uat.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Cross-phase audit of all UAT and verification files. Finds every outstanding item (pending, skipped, blocked, human_needed), optionally verifies against the codebase to detect stale docs, and produces a prioritized human test plan.
 </purpose>

package/gsd-core/workflows/autonomous.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 
 Drive milestone phases autonomously — all remaining phases, a range via `--from N`/`--to N`, or a single phase via `--only N`. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. When `--converge` or `--cross-ai` is set, route the planning step through plan-review convergence before execution. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
@@ -133,7 +135,9 @@ Run phase discovery:
 ```bash
 INIT_MANAGER=$(gsd_run query init.manager)
 if [[ "$INIT_MANAGER" == @file:* ]]; then INIT_MANAGER=$(cat "${INIT_MANAGER#@file:}"); fi
-STATE_CONTENT=$(cat .planning/STATE.md 2>/dev/null || true)
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+STATE_PATH=$(_gsd_field "$INIT_MANAGER" state_path)
+STATE_CONTENT=$(cat "$STATE_PATH" 2>/dev/null || true)
 ```
 
 Parse the JSON `phases` array.
@@ -598,22 +602,19 @@ Read and execute: `$HOME/.claude/gsd-core/references/autonomous-smart-discuss.md
 
 Proceed to lifecycle step (partial completion skips audit/complete/cleanup). Exit cleanly.
 
-**Otherwise:** After each phase, re-read manager projection:
+**Otherwise:** After each phase, re-read manager projection, then read STATE.md fresh (same fence — a single `gsd_run query init.manager` fetch backs both the JSON re-filter below and the raw re-read, no double-fetch):
 
 ```bash
 INIT_MANAGER=$(gsd_run query init.manager)
 if [[ "$INIT_MANAGER" == @file:* ]]; then INIT_MANAGER=$(cat "${INIT_MANAGER#@file:}"); fi
-STATE_CONTENT=$(cat .planning/STATE.md 2>/dev/null || true)
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+STATE_PATH=$(_gsd_field "$INIT_MANAGER" state_path)
+STATE_CONTENT=$(cat "$STATE_PATH" 2>/dev/null || true)
+cat "$STATE_PATH"
 ```
 
 Re-filter incomplete phases using discover_phases logic: keep phases where `phase_complete !== true` or `verification_status !== "passed"`, drop deferred phases from the autonomous queue, re-apply `--from` / `--to`, then sort by number ascending.
 
-Read STATE.md fresh:
-
-```bash
-cat .planning/STATE.md
-```
-
 Check for blockers in the Blockers/Concerns section. If blockers are found, go to handle_blocker with the blocker description.
 
 If incomplete phases remain: proceed to next phase, loop back to execute_phase.
@@ -725,7 +726,11 @@ Skill(skill="gsd-complete-milestone", args="${milestone_version}")
 After complete-milestone returns, verify it produced output:
 
 ```bash
-ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null || true
+INIT_MANAGER=$(gsd_run query init.manager)
+if [[ "$INIT_MANAGER" == @file:* ]]; then INIT_MANAGER=$(cat "${INIT_MANAGER#@file:}"); fi
+_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
+ARCHIVE_DIR=$(_gsd_field "$INIT_MANAGER" archive_dir)
+ls "${ARCHIVE_DIR}/v${milestone_version}-ROADMAP.md" 2>/dev/null || true
 ```
 
 If the archive file does not exist, go to handle_blocker: "Complete milestone did not produce expected archive files."

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:
 ```
@@ -150,9 +150,11 @@ Return to list_todos step.
 </step>
 
 <step name="update_state">
-After any action that changes todo count:
+If `.planning/STATE.md` exists:
 
-Re-run `init todos` to get updated count, then update STATE.md "### Pending Todos" section if exists.
+1. Re-run `gsd_run query init.todos` to get a fresh, post-write JSON snapshot (the count and rendering must reflect the change just made).
+2. **Fail-safe check (#2618):** if the JSON failed to parse, or `pending_read_ok` is not `true`, or `pending_todos_markdown` is not a string, do NOT touch the "### Pending Todos" section — leave it exactly as-is and continue to the next step. A partial or malformed `init.todos` result must never overwrite a good existing section.
+3. Otherwise, replace the entire body of "### Pending Todos" (under "## Accumulated Context") with the literal value of `pending_todos_markdown` — verbatim, one bullet per pending todo already rendered and length-capped by `init.todos`. Do not reformat, re-wrap, re-order, or hand-edit the bullets; do not append to the old body — replace it wholesale (this is what makes an old run-on-sentence section get superseded cleanly with no migration step).
 </step>
 
 <step name="git_commit">

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">
@@ -223,9 +223,11 @@ Notes:
 Commit the changes:
 
 ```bash
-gsd_run query commit "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/ .planning/quick/ .planning/STATE.md
+gsd_run query commit "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/STATE.md --files-removed .planning/phases/ .planning/quick/
 ```
 
+`.planning/phases/` and `.planning/quick/` go under `--files-removed`, not `--files` (#4208): a `--files` directory entry stages everything under it, so it would also commit any in-flight phase or quick-task file a concurrent session had written there. `--files-removed` stages only the tracked files under those directories that the archival `mv` moved away, and leaves everything still present untouched.
+
 </step>
 
 <step name="report">

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

@@ -27,21 +27,30 @@ 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.
+# #4467: the BASE half above is lockstep with Tier 3 (#3995); the TIP is not.
+# fallow's own --changed-since is one-sided by design (no upper-bound flag
+# exists in fallow 2.70.0 — --diff-file only scopes line ranges within the
+# hot-path-touched verdict, it is not a general file-scoping control), so
+# reviewing an earlier phase after a later one has landed pulls the later
+# phase's files into this pass's audited set. Do not assume this step and
+# Tier 3's scope step agree on the tip just because they agree on the base.
 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>
@@ -33,9 +35,9 @@ Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
 
 **Input sanitization (defense-in-depth):**
 ```bash
-# Validate PADDED_PHASE contains only digits and optional dot (e.g., "02", "03.1")
-if ! [[ "$PADDED_PHASE" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
-  echo "Error: Invalid phase number format: '${PADDED_PHASE}'. Expected digits (e.g., 02, 03.1)."
+# Validate PADDED_PHASE contains only digits and dotted segments (e.g., "02", "03.1", "23.1.2")
+if ! [[ "$PADDED_PHASE" =~ ^[0-9]+(\.[0-9]+)*$ ]]; then
+  echo "Error: Invalid phase number format: '${PADDED_PHASE}'. Expected digits (e.g., 02, 03.1, 23.1.2)."
   # Exit workflow
 fi
 ```