@opengsd/gsd-core 1.19.0 → 1.20.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gsd-core",
       "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.19.0",
+      "version": "1.20.1",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.19.0",
+  "version": "1.20.1",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",

package/agents/gsd-code-fixer.compact.md

@@ -256,17 +256,17 @@ Treat this as a finally-block obligation: even on early exit (config error, no f
 
 <step name="load_context">
 1. Read all `<required_reading>` files if present.
-2. Parse `<config>` block: `phase_dir`, `padded_phase`, `review_path` (full path to REVIEW.md), `fix_scope` ("critical_warning" default, or "all" includes Info), `fix_report_path` (output REVIEW-FIX.md path).
+2. Parse `<config>` block: `phase_dir`, `padded_phase`, `review_path` (full path to REVIEW.md), `fix_scope` ("critical_warning" default, or "all" includes Info and necessity), `fix_report_path` (output REVIEW-FIX.md path).
 3. `cat {review_path}`.
 4. Parse frontmatter `status:`. If `"clean"` or `"skipped"`: exit with "No issues to fix -- REVIEW.md status is {status}." — do NOT create REVIEW-FIX.md, exit 0 (not an error).
 5. Load project context (`<project_context>`): CLAUDE.md, skills.
 </step>
 
 <step name="parse_findings">
-1. Extract findings via `<finding_parser>` rules: `id`, `severity` (Critical CR-*/BL-*, Warning WR-*, Info IN-*), `title`, `file` (primary), `files` (all referenced, for multi-file fixes), `line` (or null), `issue`, `fix` (may be multi-line/code fences).
-2. Filter by `fix_scope`: `critical_warning` → CR-*/BL-*/WR-* only; `all` → + IN-*.
-3. Sort: Critical first, then Warning, then Info; same-severity keeps document order.
-4. Record `findings_in_scope` count for frontmatter.
+1. Extract findings via `<finding_parser>` rules: `id`, `severity` (Critical CR-*/BL-*, Warning WR-*, Info IN-*), `category` (`necessity` when the finding carries a `**Category:** necessity` line, #4100 — unnecessary code, not broken code), `title`, `file` (primary), `files` (all referenced, for multi-file fixes), `line` (or null), `issue`, `fix` (may be multi-line/code fences).
+2. Filter by `fix_scope`: `critical_warning` → CR-*/BL-*/WR-* only, and `critical_warning` excludes necessity findings (removal is the human's scope call; the marker overrides the prefix, so a WR-* carrying `**Category:** necessity` is out of scope and skipped with no edit); `all` → + IN-*, and `all` includes necessity findings, ordered last — record each as `fixed: requires human verification`.
+3. Sort: Critical first, then Warning, then Info, then necessity; same-severity keeps document order.
+4. Record `findings_in_scope` count for frontmatter. If `findings_in_scope` is 0, apply nothing: write REVIEW-FIX.md with `fixed: 0`, `skipped: 0`, `status: all_fixed`, and a body stating no finding was in scope and the out-of-scope findings remain in REVIEW.md.
 </step>
 
 <step name="apply_fixes">

package/agents/gsd-code-fixer.md

@@ -158,6 +158,8 @@ Each finding starts with:
 
 Where ID matches: `CR-\d+` or `BL-\d+` (Critical-tier-equivalent), `WR-\d+` (Warning), or `IN-\d+` (Info)
 
+A finding whose body carries a `**Category:** necessity` line is a **necessity finding** (#4100): code the reviewer judged unnecessary, not broken. Its prefix still gives its severity.
+
 **Required Fields:**
 
 - **File:** line contains primary file path
@@ -439,7 +441,7 @@ This cleanup is unconditional when a worktree was created — register it mental
 - `phase_dir`: Path to phase directory (e.g., `.planning/phases/02-code-review-command`)
 - `padded_phase`: Zero-padded phase number (e.g., "02")
 - `review_path`: Full path to REVIEW.md (e.g., `.planning/phases/02-code-review-command/02-REVIEW.md`)
-- `fix_scope`: "critical_warning" (default) or "all" (includes Info findings)
+- `fix_scope`: "critical_warning" (default) or "all" (includes Info and necessity findings)
 - `fix_report_path`: Full path for REVIEW-FIX.md output (e.g., `.planning/phases/02-code-review-command/02-REVIEW-FIX.md`)
 
 **3. Read REVIEW.md:**
@@ -465,6 +467,7 @@ Read `./CLAUDE.md` and check for `.claude/skills/` or `.agents/skills/` (as desc
 For each finding, extract:
 - `id`: Finding identifier (e.g., CR-01, WR-03, IN-12)
 - `severity`: Critical (CR-* or BL-*), Warning (WR-*), Info (IN-*)
+- `category`: `necessity` when the finding carries a `**Category:** necessity` line, otherwise none
 - `title`: Issue title from `### ` heading
 - `file`: Primary file path from **File:** line
 - `files`: ALL file paths referenced in finding (including in Fix section) — for multi-file fixes
@@ -473,15 +476,17 @@ For each finding, extract:
 - `fix`: Full fix content from **Fix:** section (may be multi-line, may contain code fences)
 
 **2. Filter by fix_scope:**
-- If `fix_scope == "critical_warning"`: include only CR-*, BL-*, and WR-* findings
-- If `fix_scope == "all"`: include CR-*, BL-*, WR-*, and IN-* findings
+- If `fix_scope == "critical_warning"`: include only CR-*, BL-*, and WR-* findings; `critical_warning` excludes necessity findings (removing code is a scope decision for the human, #4100). The marker overrides the prefix: a WR-* finding carrying `**Category:** necessity` is OUT of scope here, and is skipped without applying any edit
+- If `fix_scope == "all"`: include CR-*, BL-*, WR-*, and IN-* findings; `all` includes necessity findings, ordered last. A necessity fix removes code, so record it as `fixed: requires human verification`
 
 **3. Sort findings by severity:**
-- Critical (CR-* and BL-*) first, then Warning, then Info
+- Critical (CR-* and BL-*) first, then Warning, then Info, then necessity findings
 - Within same severity, maintain document order
 
 **4. Count findings in scope:**
 Record `findings_in_scope` for REVIEW-FIX.md frontmatter.
+
+If `findings_in_scope` is 0, apply nothing: write REVIEW-FIX.md with `fixed: 0`, `skipped: 0`, `status: all_fixed`, and a body stating that no finding was in scope and the out-of-scope findings remain in REVIEW.md.
 </step>
 
 <step name="apply_fixes">

package/agents/gsd-code-reviewer.compact.md

@@ -49,6 +49,8 @@ Read `./CLAUDE.md` if present — follow project guidelines, security requiremen
 
 **3. Code Quality** — dead code, unused imports/variables, poor naming, missing error handling, inconsistent patterns, overly complex functions (high cyclomatic complexity), code duplication, magic numbers, commented-out code
 
+**4. Necessity** (#4100) — reachable code whose guarded-against problem cannot occur in this stack: impossible-state guard, already-defended-elsewhere, cargo-culted pattern, phantom requirement, generality without instantiation. At `standard`/`deep`, Read `~/.claude/gsd-core/references/necessity-review.md` before classifying; if unreadable, say so in the Summary and omit `necessity:`. `quick` does not assess necessity. Warning when provable from the repo, Info when judgment, Never Critical; cite the evidence the state cannot occur and add a `**Category:** necessity` line.
+
 **Out of Scope (v1):** performance issues (O(n²) algorithms, memory leaks, inefficient queries) — NOT in scope. Focus on correctness, security, maintainability.
 
 </review_scope>
@@ -56,10 +58,12 @@ Read `./CLAUDE.md` if present — follow project guidelines, security requiremen
 <depth_levels>
 
 **quick** — pattern-matching only, grep/regex scan for common anti-patterns, no full file reads. Target: <2 min.
-Patterns: hardcoded secrets `(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['"][^'"]+['"]`; dangerous fns `eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec|passthru`; debug artifacts `console\.log|debugger;|TODO|FIXME|XXX|HACK`; empty catch `catch\s*\([^)]*\)\s*\{\s*\}`; commented-out code `^\s*//.*[{};]|^\s*#.*:|^\s*/\*`.
+Checks (commands in `review_by_depth`): Hardcoded secrets; Dangerous functions; Debug artifacts; Empty catch blocks; Commented-out code; Unpinned actions; Non-idempotent install; Missing job timeout.
+The last three: GitHub Actions workflows only.
 
 **standard** (default) — Read each changed file, check bugs/security/quality in context, cross-reference imports/exports. Target: 5-15 min.
 Language-aware checks: **JS/TS** unchecked `.length`, missing `await`, unhandled promise rejection, `as any`, `==` vs `===`, null coalescing issues. **Python** bare `except:`, mutable default args, f-string injection, `eval()`, missing `with` for file ops. **Go** unchecked error returns, goroutine leaks, context not passed, `defer` in loops, race conditions. **C/C++** buffer overflow patterns, use-after-free, null pointer deref, missing bounds checks, memory leaks. **Shell** unquoted variables, `eval`, missing `set -e`, command injection via interpolation.
+**CI/CD pipelines** (by path: `.github/workflows/*.yml`, `Dockerfile*`, `docker-compose*.yml`, deploy scripts): Read `~/.claude/gsd-core/references/cicd-review-patterns.md`; if it cannot be read, say so in the Summary and check: non-idempotent steps (`npm install` vs `npm ci`, unlocked `pip install`, unguarded `mkdir`/`rm`), no job `timeout-minutes`, deploy without `concurrency` + `cancel-in-progress`, per-environment rebuild (not build-once), no health check or rollback, load-bearing `continue-on-error`, static credentials where OIDC works, unpinned actions.
 
 **deep** — all of standard + cross-file analysis: trace call chains across imports, check type consistency at API boundaries (TS interfaces, API contracts), verify error propagation (thrown errors caught by callers), check state mutation consistency across modules, detect circular dependencies/coupling. Target: 15-30 min.
 
@@ -109,6 +113,7 @@ Use its `files`. A `status` of `unresolvable` (exit 69, JSON still printed), or
 NOTE: do NOT exclude all `.md` — commands, workflows, and agents are source code in this codebase.
 
 **2. Group by language/type:** JS/TS (`.js`,`.jsx`,`.ts`,`.tsx`), Python (`.py`), Go (`.go`), C/C++ (`.c`,`.cpp`,`.h`,`.hpp`), Shell (`.sh`,`.bash`), other → generic.
+CI/CD (by path): `.github/workflows/*.yml`/`*.yaml`, `Dockerfile*`, `docker-compose*.yml`, `deploy*.sh` (also Shell).
 
 **3. Exit early if empty:** create REVIEW.md with `status: skipped`, all finding counts 0. Body: "No source files to review after filtering. All files in scope are documentation, planning artifacts, or generated files. Use `status: skipped` (not `clean`) because no actual review was performed."
 
@@ -116,14 +121,47 @@ NOTE: `status: clean` = reviewed, no issues. `status: skipped` = no reviewable f
 </step>
 
 <step name="review_by_depth">
-**depth=quick:** run grep patterns from `<depth_levels>` against all files:
+**depth=quick:** run every check from `<depth_levels>`:
 ```bash
-grep -n -E "(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['\"]\w+['\"]" file
-grep -n -E "eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec" file
-grep -n -E "console\.log|debugger;|TODO|FIXME|XXX|HACK" file
-grep -n -E "catch\s*\([^)]*\)\s*\{\s*\}" file
+# Set FILE per scoped path with: while IFS= read -r FILE (never paste a name into code).
+
+# Hardcoded secrets
+grep -n -E -- "(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['\"][^'\"]+['\"]" "$FILE"
+
+# Dangerous functions
+grep -n -E -- "eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec|passthru" "$FILE"
+
+# Debug artifacts
+grep -n -E -- "console\.log|debugger;|TODO|FIXME|XXX|HACK" "$FILE"
+
+# Empty catch blocks
+grep -n -E -- "catch\s*\([^)]*\)\s*\{\s*\}" "$FILE"
+
+# Commented-out code
+grep -n -E -- "^\s*//.*[{};]|^\s*#[[:space:]]*(if|for|while|def|class|elif|else|try|except|with)[[:space:](].*:[[:space:]]*$|^\s*/\*[^*].*[{};]" "$FILE"
+
+# Unpinned actions
+grep -n -E -- "^[[:space:]]*(-[[:space:]]+)?uses:[[:space:]]*['\"]?[^[:space:]'\"]+@(main|master|latest)['\"]?([[:space:]]|$)" "$FILE"
+
+# Non-idempotent install
+[ -f package-lock.json ] && grep -n -E -- "(^|[^[:alnum:]_-])npm[[:space:]]+(install|i)([[:space:]]|$)" "$FILE" | grep -v -E "^[0-9]+:[[:space:]]*#|[[:space:]](-g|--global)([[:space:]]|$)"
+
+# Missing job timeout
+awk '
+function flush() { if (job != "" && runs && !timed) print line ": " job ": no job-level timeout-minutes"; job = "" }
+{ sub(/\r$/, "") }
+/^[^[:space:]#]/ { flush(); injobs = ($0 ~ /^jobs:[[:space:]]*(#.*)?$/); jind = -1; next }
+!injobs || /^[[:space:]]*(#.*)?$/ { next }
+{ ind = match($0, /[^ ]/) - 1 }
+jind < 0 { jind = ind }
+ind == jind { flush(); job = $0; sub(/^ +/, "", job); sub(/:.*/, "", job); line = NR; kind = -1; runs = 0; timed = 0; next }
+kind < 0 { kind = ind }
+ind == kind && /^ *runs-on:/ { runs = 1 }
+ind == kind && /^ *timeout-minutes:/ { timed = 1 }
+END { flush() }
+' "$FILE"
 ```
-Severity: secrets/dangerous=Critical, debug=Info, empty catch=Warning.
+Severity: secrets/dangerous=Critical, debug and commented-out code=Info, empty catch and the three CI/CD checks=Warning.
 
 **depth=standard:** per file — Read full content, apply language-specific checks, check for: functions >50 lines, deep nesting (>4 levels), missing error handling in async functions, hardcoded config values, type safety issues (TS `any`, loose Python typing). Record findings with file path, line number, description.
 
@@ -133,7 +171,7 @@ Severity: secrets/dangerous=Critical, debug=Info, empty catch=Warning.
 <step name="classify_findings">
 **Critical** — security vulnerabilities, data loss, crashes, auth bypasses: SQL/command/path-traversal injection, hardcoded secrets in production code, null pointer derefs that crash, auth/authz bypasses, unsafe deserialization, buffer overflows.
 
-**Warning** — logic errors, unhandled edge cases, missing error handling, code smells that could cause bugs: unchecked array access, missing async error handling, off-by-one errors, `==` vs `===` coercion, unhandled promise rejections, dead code paths indicating logic errors.
+**Warning** — logic errors, unhandled edge cases, missing error handling, code smells that could cause bugs: unchecked array access, missing async error handling, off-by-one errors, `==` vs `===` coercion, unhandled promise rejections, dead code paths indicating logic errors; CI/CD pipeline findings: every check in the CI/CD entry.
 
 **Info** — style, naming, dead code, unused imports, suggestions: unused imports/variables, poor naming (single letters except loop counters), commented-out code, TODO/FIXME, magic numbers, duplication.
 
@@ -158,10 +196,13 @@ findings:
   warning: N
   info: N
   total: N
+  necessity: N
 status: clean | issues_found
 ---
 ```
 
+`necessity:` only at standard/deep: the necessity findings among `warning` + `info`, never added to `total`.
+
 **3. Body sections (required order):**
 1) `## Structural Findings (fallow)` — only if structural findings provided; normalized items first.
 2) `## Narrative Findings (AI reviewer)` — your adversarial findings, including any external claim independently verified (`(external: {slug})`).

package/agents/gsd-code-reviewer.md

@@ -61,6 +61,8 @@ This ensures project-specific patterns, conventions, and best practices are appl
 
 **3. Code Quality** — Dead code, unused imports/variables, poor naming conventions, missing error handling, inconsistent patterns, overly complex functions (high cyclomatic complexity), code duplication, magic numbers, commented-out code
 
+**4. Necessity** (#4100) — reachable code whose guarded-against problem cannot occur in this stack: impossible-state guard, already-defended-elsewhere, cargo-culted pattern, phantom requirement, generality without instantiation. At `standard`/`deep`, Read `~/.claude/gsd-core/references/necessity-review.md` before classifying findings; if it cannot be read, say so in the Summary and omit `necessity:`. `quick` does not assess necessity. Warning when provable from the repo, Info when it rests on judgment, Never Critical; each finding cites the evidence that the state cannot occur and carries a `**Category:** necessity` line.
+
 **Out of Scope (v1):** Performance issues (O(n²) algorithms, memory leaks, inefficient queries) are NOT in scope for v1. Focus on correctness, security, and maintainability.
 
 </review_scope>
@@ -71,12 +73,17 @@ This ensures project-specific patterns, conventions, and best practices are appl
 
 **quick** — Pattern-matching only. Use grep/regex to scan for common anti-patterns without reading full file contents. Target: under 2 minutes.
 
-Patterns checked:
-- Hardcoded secrets: `(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['"][^'"]+['"]`
-- Dangerous functions: `eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec|passthru`
-- Debug artifacts: `console\.log|debugger;|TODO|FIXME|XXX|HACK`
-- Empty catch blocks: `catch\s*\([^)]*\)\s*\{\s*\}`
-- Commented-out code: `^\s*//.*[{};]|^\s*#.*:|^\s*/\*`
+Checks (commands in `review_by_depth`):
+- Hardcoded secrets
+- Dangerous functions
+- Debug artifacts
+- Empty catch blocks
+- Commented-out code
+- Unpinned actions
+- Non-idempotent install
+- Missing job timeout
+
+The last three: GitHub Actions workflows only.
 
 **standard** (default) — Read each changed file. Check for bugs, security issues, and quality problems in context. Cross-reference imports and exports. Target: 5-15 minutes.
 
@@ -86,6 +93,7 @@ Language-aware checks:
 - **Go**: Unchecked error returns, goroutine leaks, context not passed, `defer` in loops, race conditions
 - **C/C++**: Buffer overflow patterns, use-after-free indicators, null pointer dereferences, missing bounds checks, memory leaks
 - **Shell**: Unquoted variables, `eval` usage, missing `set -e`, command injection via interpolation
+- **CI/CD pipelines** (by path: `.github/workflows/*.yml`, `Dockerfile*`, `docker-compose*.yml`, deploy scripts): Read `~/.claude/gsd-core/references/cicd-review-patterns.md`; if it cannot be read, say so in the Summary and check: non-idempotent steps (`npm install` vs `npm ci`, unlocked `pip install`, unguarded `mkdir`/`rm`), no job `timeout-minutes`, deploy without `concurrency` + `cancel-in-progress`, per-environment rebuild (not build-once), no health check or rollback, load-bearing `continue-on-error`, static credentials where OIDC works, unpinned actions
 
 **deep** — All of standard, plus cross-file analysis. Trace function call chains across imports. Target: 15-30 minutes.
 
@@ -174,6 +182,7 @@ NOTE: Do NOT exclude all `.md` files — commands, workflows, and agents are sou
 - Go: `.go`
 - C/C++: `.c`, `.cpp`, `.h`, `.hpp`
 - Shell: `.sh`, `.bash`
+- CI/CD (by path): `.github/workflows/*.yml`/`*.yaml`, `Dockerfile*`, `docker-compose*.yml`, `deploy*.sh` (also Shell)
 - Other: Review generically
 
 **3. Exit early if empty:** If no source files remain after filtering, create REVIEW.md with:
@@ -194,22 +203,48 @@ NOTE: `status: clean` means "reviewed and found no issues." `status: skipped` me
 Branch on depth level:
 
 **For depth=quick:**
-Run grep patterns (from `<depth_levels>` quick section) against all files:
+Run every check from `<depth_levels>` quick section:
 ```bash
+# Set FILE per scoped path with: while IFS= read -r FILE (never paste a name into code).
+
 # Hardcoded secrets
-grep -n -E "(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['\"]\w+['\"]" file
+grep -n -E -- "(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['\"][^'\"]+['\"]" "$FILE"
 
 # Dangerous functions
-grep -n -E "eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec" file
+grep -n -E -- "eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec|passthru" "$FILE"
 
 # Debug artifacts
-grep -n -E "console\.log|debugger;|TODO|FIXME|XXX|HACK" file
-
-# Empty catch
-grep -n -E "catch\s*\([^)]*\)\s*\{\s*\}" file
+grep -n -E -- "console\.log|debugger;|TODO|FIXME|XXX|HACK" "$FILE"
+
+# Empty catch blocks
+grep -n -E -- "catch\s*\([^)]*\)\s*\{\s*\}" "$FILE"
+
+# Commented-out code
+grep -n -E -- "^\s*//.*[{};]|^\s*#[[:space:]]*(if|for|while|def|class|elif|else|try|except|with)[[:space:](].*:[[:space:]]*$|^\s*/\*[^*].*[{};]" "$FILE"
+
+# Unpinned actions
+grep -n -E -- "^[[:space:]]*(-[[:space:]]+)?uses:[[:space:]]*['\"]?[^[:space:]'\"]+@(main|master|latest)['\"]?([[:space:]]|$)" "$FILE"
+
+# Non-idempotent install
+[ -f package-lock.json ] && grep -n -E -- "(^|[^[:alnum:]_-])npm[[:space:]]+(install|i)([[:space:]]|$)" "$FILE" | grep -v -E "^[0-9]+:[[:space:]]*#|[[:space:]](-g|--global)([[:space:]]|$)"
+
+# Missing job timeout
+awk '
+function flush() { if (job != "" && runs && !timed) print line ": " job ": no job-level timeout-minutes"; job = "" }
+{ sub(/\r$/, "") }
+/^[^[:space:]#]/ { flush(); injobs = ($0 ~ /^jobs:[[:space:]]*(#.*)?$/); jind = -1; next }
+!injobs || /^[[:space:]]*(#.*)?$/ { next }
+{ ind = match($0, /[^ ]/) - 1 }
+jind < 0 { jind = ind }
+ind == jind { flush(); job = $0; sub(/^ +/, "", job); sub(/:.*/, "", job); line = NR; kind = -1; runs = 0; timed = 0; next }
+kind < 0 { kind = ind }
+ind == kind && /^ *runs-on:/ { runs = 1 }
+ind == kind && /^ *timeout-minutes:/ { timed = 1 }
+END { flush() }
+' "$FILE"
 ```
 
-Record findings with severity: secrets/dangerous=Critical, debug=Info, empty catch=Warning
+Record findings with severity: secrets/dangerous=Critical, debug and commented-out code=Info, empty catch and the three CI/CD checks=Warning
 
 **For depth=standard:**
 For each file:
@@ -253,6 +288,7 @@ For each finding, assign severity:
 - Type coercion issues (`==` vs `===`)
 - Unhandled promise rejections
 - Dead code paths that indicate logic errors
+- CI/CD pipeline findings: every check in the CI/CD entry
 
 **Info** — Style issues, naming improvements, dead code, unused imports, suggestions:
 - Unused imports/variables
@@ -287,10 +323,13 @@ findings:
   warning: N
   info: N
   total: N
+  necessity: N
 status: clean | issues_found
 ---
 ```
 
+Emit `necessity:` only at standard/deep depth. It counts the necessity findings among `warning` + `info` and is never added to `total`.
+
 **3. Body sections (required order):**
 1) `## Structural Findings (fallow)` — only when structural findings were provided; list normalized items first.
 2) `## Narrative Findings (AI reviewer)` — your adversarial findings from direct code review, including any external-reviewer claim you independently verified (`(external: {slug})`, see `load_context` step 5).

package/agents/gsd-executor.md

@@ -766,7 +766,14 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails.
 </self_check>
 
 <state_updates>
-After SUMMARY.md, update STATE.md using `gsd-tools query` state handlers (named flags):
+After SUMMARY.md, update ROADMAP.md progress FIRST, then STATE.md. The ROADMAP write is the step that can decline (`missing_phase_details`), and a decline stops the plan before any STATE.md write, so STATE.md never advances past a plan the ROADMAP did not record:
+
+```bash
+# Update ROADMAP.md progress for this phase (plan counts, status). A decline stops here, before STATE.md moves.
+PROGRESS=$(gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}") && REASON=$(jq -er '.reason//""' <<<"$PROGRESS") && [ "$REASON" != missing_phase_details ] || { echo "ERROR: ROADMAP update-plan-progress did not complete for ${PHASE_NUMBER}-${PLAN} (missing_phase_details decline, failed query, or jq not installed). STOP: skip this plan's completion steps." >&2; exit 1; }
+```
+
+Then update STATE.md using `gsd-tools query` state handlers (named flags):
 
 ```bash
 # Advance plan counter (handles edge cases automatically)
@@ -793,9 +800,6 @@ gsd_run query state.record-session \
 ```
 
 ```bash
-# Update ROADMAP.md progress for this phase (plan counts, status)
-gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}"
-
 # Mark completed requirements from PLAN.md frontmatter
 # Extract the `requirements` array from the plan's frontmatter, then mark each complete
 gsd_run query requirements.mark-complete ${REQ_IDS}

package/bin/install.js

@@ -2659,7 +2659,15 @@ function convertSlashCommandsToTraeSkillMentions(content) {
   });
 }
 
-function convertClaudeToTraeMarkdown(content) {
+function convertClaudeToTraeMarkdown(content, pathPrefix) {
+  return runtimeArtifactConversion._shieldEmittedPrefix(
+    runtimeArtifactConversion._resolveTraeInstructionFileAtPrefix(content, pathPrefix),
+    pathPrefix,
+    convertClaudeToTraeMarkdownBody,
+  );
+}
+
+function convertClaudeToTraeMarkdownBody(content) {
   let converted = convertSlashCommandsToTraeSkillMentions(filterRuntimeNotesForTarget(content, 'trae'));
   converted = converted.replace(/\bBash\(/g, 'Shell(');
   converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
@@ -2719,9 +2727,10 @@ function convertClaudeToTraeMarkdown(content) {
   converted = converted.replace(/\.\/\.claude\//g, './.trae/');
   converted = converted.replace(/\.claude\//g, '.trae/');
   // Bare forms (no trailing slash) — after slash forms to avoid double-rewrite.
-  // Use negative lookahead (?![\w-]) to preserve .claude-plugin and .claudeignore.
-  converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.trae');
-  converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.trae');
+  // Use negative lookahead (?![\w-]|\.\w) to preserve .claude-plugin, .claudeignore and .claude.json.
+  // #5715: an emitted prefix is shielded by convertClaudeToTraeMarkdown; the skills path runs this before the prefix pass, and the profile maps the own-dir forms.
+  converted = converted.replace(/~\/\.claude(?![\w-]|\.\w)/g, '~/.trae');
+  converted = converted.replace(/\$HOME\/\.claude(?![\w-]|\.\w)/g, () => '$HOME/.trae');
   // Environment variable name rewrite
   converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'TRAE_CONFIG_DIR');
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
@@ -2765,8 +2774,8 @@ function convertClaudeCommandToTraeSkill(content, skillName) {
   return `${fm}\n${body}`;
 }
 
-function convertClaudeAgentToTraeAgent(content) {
-  let converted = convertClaudeToTraeMarkdown(content);
+function convertClaudeAgentToTraeAgent(content, _isGlobal, meta) {
+  let converted = convertClaudeToTraeMarkdown(content, meta && meta.pathPrefix);
 
   const { frontmatter, body } = extractFrontmatterAndBody(converted);
   if (!frontmatter) return converted;
@@ -7279,14 +7288,16 @@ function installCodexConfig(targetDir, agentsSrc, sandboxTier = 'codex-agent-san
     content = composeWorkflow(content, { sourcePath: agentTomlSourcePath });
     // Replace full .claude/gsd-core prefix so path resolves to the Codex
     // GSD install before generic .claude → .codex conversion rewrites it.
-    content = content.replace(/~\/\.claude\/gsd-core\//g, codexGsdPath);
-    content = content.replace(/\$HOME\/\.claude\/gsd-core\//g, codexGsdPath);
+    // #5715: one pass, function replacement: a string replacement would expand `$&` in a
+    // config dir, and a second pass would rescan the path the first emitted.
+    content = content.replace(/(?:~|\$HOME)\/\.claude\/gsd-core\//g, () => codexGsdPath);
     // Route TOML emit through the same full Claude→Codex conversion pipeline
     // used on the `.md` emit path (#2639). Covers: slash-command rewrites,
     // $ARGUMENTS → {{GSD_ARGS}}, /clear removal, anchored and bare .claude/
     // paths, .claudeignore → .codexignore, and standalone "Claude" /
     // CLAUDE.md neutralization via neutralizeAgentReferences(..., 'AGENTS.md').
-    content = convertClaudeToCodexMarkdown(content);
+    // #5715: the converter runs after the path above was emitted; shield it from the converter.
+    content = runtimeArtifactConversion._shieldEmittedPrefix(content, codexGsdPath, convertClaudeToCodexMarkdown);
     const { frontmatter } = extractFrontmatterAndBody(content);
     // #3897 security review F1 (blocker, post-merge): this loop used to key
     // the sandbox/hold decision off ONLY the filename stem while the emitted
@@ -7949,7 +7960,9 @@ const RUNTIME_CONTENT_DISPATCH = {
     },
   },
   trae: {
-    md: (content) => convertClaudeToTraeMarkdown(content),
+    // #5715: the Trae converter shields (and resolves) the emitted prefix itself.
+    mdShieldsPrefix: true,
+    md: (content, ctx) => convertClaudeToTraeMarkdown(content, ctx && ctx.pathPrefix),
     js: (content) => {
       content = content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
         return `/gsd-${commandName}`;
@@ -8152,33 +8165,8 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
         // balanced masking grammar used by this path and the rewrite engine.
         const rewriteGenericPaths = (body) => {
           content = body;
-          const globalClaudeRegex = /~\/\.claude\//g;
-          const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
-          const localClaudeRegex = /\.\/\.claude\//g;
-          content = content.replace(globalClaudeRegex, pathPrefix);
-          content = content.replace(globalClaudeHomeRegex, pathPrefix);
-          content = content.replace(localClaudeRegex, `./${dirName}/`);
-          // #3544 review (Finding 1 fallout): guarded with the SAME
-          // negative-lookahead convention already used at ~:2859-2860 below
-          // ("preserve .claude-plugin and .claudeignore"). A naive `\b` here
-          // is satisfied by ANY non-word character, including '-' — so for a
-          // --config-dir whose name EXTENDS '.claude' (e.g. '.claude-work',
-          // pathPrefix '$HOME/.claude-work/'), this pass re-matched the
-          // '$HOME/.claude' PREFIX of its own slash-form output (lines above)
-          // and re-appended the full prefix, corrupting every emitted path to
-          // '$HOME/.claude-work-work/...'. Harmless no-op for the literal
-          // default '.claude' (self-replace with an identical string), which
-          // is why this went undetected until a non-default config-dir name
-          // was exercised.
-          content = content.replace(/~\/\.claude(?![\w-])/g, pathPrefix.replace(/\/$/, ''));
-          content = content.replace(/\$HOME\/\.claude(?![\w-])/g, pathPrefix.replace(/\/$/, ''));
-          content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
-          content = content.replace(/~\/\.qwen\//g, pathPrefix);
-          content = content.replace(/\$HOME\/\.qwen\//g, pathPrefix);
-          content = content.replace(/\.\/\.qwen\//g, `./${dirName}/`);
-          content = content.replace(/~\/\.hermes\//g, pathPrefix);
-          content = content.replace(/\$HOME\/\.hermes\//g, pathPrefix);
-          content = content.replace(/\.\/\.hermes\//g, `./${dirName}/`);
+          // #5715: every generic source form in ONE pass (no rescan of the emitted prefix).
+          content = runtimeArtifactConversion._rewriteSpecTreeConfigDirForms(content, pathPrefix, dirName);
           // #3544: restore @-file-reference lines to the tilde form Claude Code
           // actually expands — the SAME correction #3133 already applies to
           // skill/command bodies via _applyRuntimeRewrites's 'claude' case (see
@@ -8215,7 +8203,15 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       content = normalizeAgentBodyForRuntime(content, runtime, readGsdCommandNames());
 
       // Apply per-runtime .md converter (if any)
-      if (dispatch.md) content = dispatch.md(content, ctx);
+      // #5715: the generic pass above emitted `pathPrefix`; shield it from the converter
+      // (a converter that skips the generic pass emitted nothing to shield).
+      if (dispatch.md) {
+        content = runtimeArtifactConversion._shieldEmittedPrefix(
+          content,
+          dispatch.mdSkipGenericRewrite || dispatch.mdShieldsPrefix ? undefined : pathPrefix,
+          (shielded) => dispatch.md(shielded, ctx),
+        );
+      }
 
       // Re-run attribution after converter for runtimes that need it (copilot, antigravity)
       if (dispatch.mdReattributeAfter) content = processAttribution(content, getCommitAttribution(runtime));
@@ -10087,8 +10083,8 @@ const MANIFEST_NAME = 'gsd-file-manifest.json';
  * Compute SHA256 hash of file contents
  */
 function fileHash(filePath) {
-  const content = fs.readFileSync(filePath);
-  return crypto.createHash('sha256').update(content).digest('hex');
+  // #5683: single owner of the per-file hash, shared with `effort sync`.
+  return require('../gsd-core/bin/lib/install-manifest-record.cjs').fileHash(filePath);
 }
 
 /**

package/commands/gsd/new-milestone.md

@@ -9,7 +9,7 @@ allowed-tools:
   - Grep
   - Agent
   - AskUserQuestion
-requires: [new-project, phase, plan-phase]
+requires: [new-project, phase, plan-phase, discuss-phase, execute-phase]
 ---
 
 <arguments>$ARGUMENTS</arguments>
@@ -28,7 +28,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 - `.planning/ROADMAP.md` — phase structure (continues numbering)
 - `.planning/STATE.md` — reset for new milestone
 
-**After:** `/gsd:plan-phase [N]` to start execution.
+**After:** Run `/gsd:discuss-phase [N]` to clarify the approach (or `/gsd:plan-phase [N]` to plan directly); then `/gsd:execute-phase [N]` to execute.
 </objective>
 
 <execution_context>

package/commands/gsd/new-project.md

@@ -9,7 +9,7 @@ allowed-tools:
   - Write
   - Agent
   - AskUserQuestion
-requires: [config, phase, plan-phase]
+requires: [config, phase, plan-phase, discuss-phase, execute-phase]
 ---
 
 <arguments>$ARGUMENTS</arguments>
@@ -36,7 +36,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
 
-**After this command:** Run `/gsd:plan-phase 1` to start execution.
+**After this command:** Run `/gsd:discuss-phase 1` to clarify the approach (or `/gsd:plan-phase 1` to plan directly); then `/gsd:execute-phase 1` to execute.
 </objective>
 
 <execution_context>

package/commands/gsd/update.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:update
 description: Update GSD to latest version with changelog display
-argument-hint: "[--sync | --reapply | --next | --rc]"
+argument-hint: "[--sync | --reapply | --next | --rc] [--interactive=exceptions|all]"
 allowed-tools:
   - Read
   - Write
@@ -35,14 +35,17 @@ Routes to the update workflow which handles:
 <flags>
 - **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
 - **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+  - **--interactive[=exceptions|all]** (with `--reapply` only): show each user edit next to the stock text with a recommended disposition and wait for a keep / retire / rewrite decision per edit. `all` shows every edit; `exceptions` (bare `--interactive`) shows only edits upstream adopted, partly adopted, reworded around, or orphaned, and keeps the rest. Without it, `--reapply` behaves exactly as before.
 - **--next** (alias **--rc**): Target the `@next` RC dist-tag instead of `@latest` so you can install or refresh a release candidate (e.g. `1.4.0-rc.1`) through the normal update flow — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all still apply. Omitting it keeps targeting `@latest` (no change). See ADR #660 for the RC channel.
 - **(no flag)**: Standard update — check for new version, show changelog, install.
 </flags>
 
 <process>
+If the arguments contain `--interactive` (bare or with a value) but not `--reapply`, STOP with: `--interactive applies only to --reapply (for example: /gsd:update --reapply --interactive=all)`. Do nothing else.
+
 Parse the first token of the `<arguments>` block:
 - If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
-- If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
+- If it is `--reapply`: strip the flag, execute the reapply-patches workflow, passing the remaining arguments (for example `--interactive=all`) to it.
 - Otherwise (including `--next` / `--rc`): execute the update workflow end-to-end, passing the `<arguments>` block through so the workflow's parse_update_channel step can select the release channel.
 
 </process>