@opengsd/gsd-core 1.18.0 → 1.20.0

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.18.0",
+      "version": "1.20.0",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",
@@ -18,5 +18,6 @@
     "claude-code",
     "gsd"
   ],
+  "commands": [],
   "skills": "./skills/"
 }

package/.opencode/plugins/gsd-core.js

@@ -365,7 +365,7 @@ function handleHookResult(hookResult, output) {
     throw new Error(reason);
   }
 
-  // Advisory: inject additionalContext into metadata + log
+  // Advisory: inject additionalContext into metadata
   const advisory =
     parsed &&
     parsed.hookSpecificOutput &&
@@ -382,8 +382,7 @@ function handleHookResult(hookResult, output) {
       }
       output.metadata._gsdAdvisory.push(advisory);
     }
-    // Best-effort visibility when metadata isn't surfaced to the model
-    console.error(advisory);
+    // Not written to stderr: the OpenCode TUI draws a plugin's stderr over the prompt input (#5648).
     // >>> gsd:opencode-parity
     deliverAdvisory(advisory, output);
     // <<< gsd:opencode-parity

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

@@ -73,12 +73,12 @@ After applying each fix:
 | Language | Check Command |
 |----------|--------------|
 | JavaScript | `node -c {file}` (syntax check) |
-| TypeScript | `npx tsc --noEmit {file}` (if tsconfig.json exists) |
+| TypeScript | Project-aware check only, output filtered to `{file}`: the project's own typecheck (`npm run typecheck` / `tsc -b`) if it exists, else `npx tsc --noEmit -p <nearest tsconfig*.json>` whose `--listFilesOnly` output lists `{file}`; no config includes `{file}` → Tier 1 only. Never pass `{file}` to `tsc` positionally. |
 | Python | `python -c "import ast; ast.parse(open('{file}').read())"` |
 | JSON | `node -e "JSON.parse(require('fs').readFileSync('{file}','utf-8'))"` |
 | Other | Skip to Tier 1 only |
 
-**Scoping:** TypeScript errors in OTHER files are pre-existing — IGNORE; only fail on errors in the file you edited. `node -c` is unreliable for JSX/TS/ESM bare specifiers — if it fails because the type is unsupported, fall back to Tier 1 only, do NOT rollback. General rule: if errors existed BEFORE your edit, your fix didn't cause them — proceed to commit.
+**Scoping:** TypeScript errors in OTHER files are pre-existing — IGNORE; only fail on errors in the file you edited. A solution-style root `tsconfig.json` (`"files": []` plus `references`) checks no source files and exits 0 — NOT a passing check; use a referenced config whose `--listFilesOnly` lists `{file}`, or fall back to Tier 1. TypeScript procedure: prefer a `typecheck` script in the nearest `package.json`; else walk up from `{file}` to the nearest `tsconfig.json` (solution-style: try each referenced config in turn), run from that config's directory `npx tsc --noEmit -p <config> --listFilesOnly` and keep the first config listing `{file}` (none → Tier 1), then `npx tsc --noEmit -p <config>` (never `-b`: no build artifacts) keeping only output lines for `{file}`; roll back only for errors on lines you changed, otherwise treat as pre-existing and proceed. `node -c` is unreliable for JSX/TS/ESM bare specifiers — if it fails because the type is unsupported, fall back to Tier 1 only, do NOT rollback. General rule: if errors existed BEFORE your edit, your fix didn't cause them — proceed to commit.
 
 - Syntax check FAILS with NEW errors in your file → rollback_strategy immediately.
 - FAILS with pre-existing errors only → proceed to commit.
@@ -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

@@ -110,13 +110,14 @@ Run syntax/parse check appropriate to file type:
 | Language | Check Command |
 |----------|--------------|
 | JavaScript | `node -c {file}` (syntax check) |
-| TypeScript | `npx tsc --noEmit {file}` (if tsconfig.json exists in project) |
+| TypeScript | Project-aware check only, output filtered to `{file}`: the project's own typecheck (`npm run typecheck` / `tsc -b`) if it exists, else `npx tsc --noEmit -p <nearest tsconfig*.json>` whose `--listFilesOnly` output lists `{file}`; no config includes `{file}` → Tier 1 only. Never pass `{file}` to `tsc` positionally. |
 | Python | `python -c "import ast; ast.parse(open('{file}').read())"` |
 | JSON | `node -e "JSON.parse(require('fs').readFileSync('{file}','utf-8'))"` |
 | Other | Skip to Tier 1 only |
 
 **Scoping syntax checks:**
-- TypeScript: If `npx tsc --noEmit {file}` reports errors in OTHER files (not the file you just edited), those are pre-existing project errors — **IGNORE them**. Only fail if errors reference the specific file you modified.
+- TypeScript: Run the project-aware check from the table above. If it reports errors in OTHER files (not the file you just edited), those are pre-existing project errors — **IGNORE them**. Only fail if errors reference the specific file you modified. A solution-style root `tsconfig.json` (`"files": []` plus `references`) checks no source files and exits 0, so it is NOT a passing check: use a referenced config whose `--listFilesOnly` output includes `{file}`, or fall back to Tier 1.
+- TypeScript procedure: (1) Look for a `typecheck` script in the nearest `package.json` and prefer it. (2) Otherwise start at `{file}`'s directory and walk up to the nearest `tsconfig.json`; if it is solution-style, take each config it references (e.g. `tsconfig.app.json`, `tsconfig.node.json`) and try them in turn. (3) Run from the config's own directory with `npx tsc --noEmit -p <config> --listFilesOnly` and keep the first config whose listing includes `{file}`; if none does, fall back to Tier 1. (4) Run `npx tsc --noEmit -p <config>` (use `-p`, never `-b`, so no build artifacts or `.tsbuildinfo` files are written) and keep only output lines that start with `{file}`'s path as `tsc` prints it relative to that directory. (5) Roll back only for errors on lines you changed; errors you cannot attribute to your edit are pre-existing — fall back to Tier 1 and proceed.
 - JavaScript: `node -c {file}` is reliable for plain .js but NOT for JSX, TypeScript, or ESM with bare specifiers. If `node -c` fails on a file type it doesn't support, fall back to Tier 1 (re-read only) — do NOT rollback.
 - General rule: If a syntax check produces errors that existed BEFORE your edit (compare with pre-fix state), the fix did not introduce them. Proceed to commit.
 
@@ -157,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
@@ -438,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:**
@@ -464,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
@@ -472,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">
@@ -701,7 +707,7 @@ main checkout after teardown).
 
 **DO verify each fix** using 3-tier verification strategy:
 - Minimum: re-read file, confirm fix present
-- Preferred: syntax check (node -c, tsc --noEmit, python ast.parse, etc.)
+- Preferred: syntax check (node -c, project-aware tsc -p, python ast.parse, etc.)
 - Fallback: accept minimum if no syntax checker available
 
 **DO skip findings that cannot be applied cleanly** — do not force broken fixes. Mark as skipped with clear reason.

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/agents/gsd-verifier.md

@@ -689,7 +689,7 @@ verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
 covered_files: [...]
-covered_digest: "v3:sha256:..."
+covered_digest: "v4:sha256:..."
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised); each is detailed in behavior_unverified_items below (and in human_verification when status is human_needed)
 overrides_applied: 0 # Count of PASSED (override) items included in score
 overrides: # Only if overrides exist — carried forward or newly added