@opengsd/gsd-core 1.19.0 → 1.20.0

package/hooks/dist/gsd-workflow-guard.js

@@ -22,7 +22,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard is almost entirely advisory (fail open — a broken advisory must
 // never wedge every tool call), with ONE hard block (#3504 force-add-on-
@@ -83,6 +83,7 @@ function forceGitAddCwds(command, defaultCwd) {
 function currentBranch(cwd) {
   const result = spawnSync('git', ['branch', '--show-current'], { // allow-index-refresh: reads HEAD only, never opens the index
     cwd,
+    env: gitEnv(),
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
     windowsHide: true,

package/hooks/dist/gsd-worktree-path-guard.js

@@ -18,7 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard's outer catch has always exited 0 (fail open): a path guard that
 // cannot resolve the worktree must not block the user's edit — its whole job
@@ -49,10 +49,10 @@ const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeou
 // Parity: tests/git-optional-locks-parity.test.cjs.
 // A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
 // (#3582), so the compiled owner can be absent. This guard only runs
-// `git rev-parse`, which never opens the index, so the unmodified environment
+// `git rev-parse`, which never opens the index, so the scrubbed gitEnv() base
 // loses nothing; requiring the artifact unguarded would throw at load and the
 // containment guard would silently stop running.
-let readOnlyGitEnv = () => process.env;
+let readOnlyGitEnv = (base = process.env) => base;
 try {
   const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
   ensureRuntimeBuild();
@@ -62,7 +62,7 @@ try {
 }
 
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv(gitEnv()) });
 }
 
 // Walk up from `start` to find the nearest existing directory.

package/hooks/dist/lib/git-probe.js

@@ -92,7 +92,23 @@ function reportIfUndetermined(hookName, probeLabel, result) {
 const BLOCKING_GUARD_PROBE_TIMEOUT_MS = 5000;
 const BLOCKING_GUARD_MAX_SEQUENTIAL_PROBES = 3;
 
+// #5548: repo-location vars git sets in hooks; inherited, they override the
+// probe's cwd/-C. Parity-tested copy of GIT_LOCATION_ENV_VARS in
+// src/shell-command-projection.cts (hooks ship standalone and cannot import it).
+const GIT_LOCATION_ENV_VARS = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', 'GIT_INDEX_FILE', 'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE', 'GIT_PREFIX', 'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+];
+
+/** `env` (default process.env) minus the repo-location vars (case-insensitive, for Windows). */
+function gitEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([k]) => !GIT_LOCATION_ENV_VARS.includes(k.toUpperCase())));
+}
+
 module.exports = {
+  GIT_LOCATION_ENV_VARS,
+  gitEnv,
   classifyGitProbe,
   reportIfUndetermined,
   BLOCKING_GUARD_PROBE_TIMEOUT_MS,

package/hooks/gsd-graphify-update.sh

@@ -81,6 +81,12 @@ case "$COMMAND" in
   *) exit 0 ;;
 esac
 
+# #5548: inherited repo-location vars (GIT_DIR, GIT_INDEX_FILE, ...) would override
+# cwd for every git call below. Drop git's own list minus the config-injection vars.
+for v in $(git rev-parse --local-env-vars 2>/dev/null); do
+  case "$v" in GIT_CONFIG|GIT_CONFIG_PARAMETERS|GIT_CONFIG_COUNT) ;; *) unset "$v" ;; esac
+done
+
 # Gate 3 — inside git repo
 git rev-parse --git-dir >/dev/null 2>&1 || exit 0
 

package/hooks/gsd-statusline.js

@@ -18,6 +18,7 @@ const os = require('os');
 // monkeypatching childProcess.execFileSync.
 const childProcess = require('child_process');
 const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+const { gitEnv } = require('./lib/git-probe.js');
 
 // This hook's build-seam outer catch (require.main guard just below) has
 // always exited 0 (fail open — the statusline renders on EVERY prompt, so a
@@ -934,7 +935,7 @@ function readGitStatus(dir) {
     // or untracked files; overflow still degrades safely to segment-absent via
     // the catch below.
     return childProcess.execFileSync('git', ['-C', dir, 'status', '--porcelain=v2', '--branch'],
-      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env: readOnlyGitEnv() });
+      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env: readOnlyGitEnv(gitEnv()) });
   } catch (e) {
     return null;
   }
@@ -1029,7 +1030,7 @@ function readStateHeadCommits(root, stamp) {
   try {
     return childProcess.execFileSync('git', // allow-index-refresh: rev-list walks the commit graph and never opens the index
       ['-C', root, 'rev-list', '--left-right', '--count', `${stamp}...HEAD`],
-      { encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
+      { env: gitEnv(), encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
         stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
   } catch (e) {
     return null;

package/hooks/gsd-windsurf-pre-write.js

@@ -31,7 +31,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { allow, deny } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // #3911 (ADR-3889 Phase 7): the exit(2) call site (block(), below) is
 // migrated to hook-exit.js's deny(undefined, reason) — see
@@ -64,10 +64,10 @@ const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeou
 // Parity: tests/git-optional-locks-parity.test.cjs.
 // A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
 // (#3582), so the compiled owner can be absent. This guard only runs
-// `git rev-parse`, which never opens the index, so the unmodified environment
+// `git rev-parse`, which never opens the index, so the scrubbed gitEnv() base
 // loses nothing; requiring the artifact unguarded would throw at load and the
 // containment guard would silently stop running.
-let readOnlyGitEnv = () => process.env;
+let readOnlyGitEnv = (base = process.env) => base;
 try {
   const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
   ensureRuntimeBuild();
@@ -77,7 +77,7 @@ try {
 }
 
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv(gitEnv()) });
 }
 
 // Walk up from `start` to find the nearest existing DIRECTORY (not merely an

package/hooks/gsd-workflow-guard.js

@@ -22,7 +22,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard is almost entirely advisory (fail open — a broken advisory must
 // never wedge every tool call), with ONE hard block (#3504 force-add-on-
@@ -83,6 +83,7 @@ function forceGitAddCwds(command, defaultCwd) {
 function currentBranch(cwd) {
   const result = spawnSync('git', ['branch', '--show-current'], { // allow-index-refresh: reads HEAD only, never opens the index
     cwd,
+    env: gitEnv(),
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
     windowsHide: true,

package/hooks/gsd-worktree-path-guard.js

@@ -18,7 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard's outer catch has always exited 0 (fail open): a path guard that
 // cannot resolve the worktree must not block the user's edit — its whole job
@@ -49,10 +49,10 @@ const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeou
 // Parity: tests/git-optional-locks-parity.test.cjs.
 // A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
 // (#3582), so the compiled owner can be absent. This guard only runs
-// `git rev-parse`, which never opens the index, so the unmodified environment
+// `git rev-parse`, which never opens the index, so the scrubbed gitEnv() base
 // loses nothing; requiring the artifact unguarded would throw at load and the
 // containment guard would silently stop running.
-let readOnlyGitEnv = () => process.env;
+let readOnlyGitEnv = (base = process.env) => base;
 try {
   const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
   ensureRuntimeBuild();
@@ -62,7 +62,7 @@ try {
 }
 
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv(gitEnv()) });
 }
 
 // Walk up from `start` to find the nearest existing directory.

package/hooks/lib/git-probe.js

@@ -92,7 +92,23 @@ function reportIfUndetermined(hookName, probeLabel, result) {
 const BLOCKING_GUARD_PROBE_TIMEOUT_MS = 5000;
 const BLOCKING_GUARD_MAX_SEQUENTIAL_PROBES = 3;
 
+// #5548: repo-location vars git sets in hooks; inherited, they override the
+// probe's cwd/-C. Parity-tested copy of GIT_LOCATION_ENV_VARS in
+// src/shell-command-projection.cts (hooks ship standalone and cannot import it).
+const GIT_LOCATION_ENV_VARS = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', 'GIT_INDEX_FILE', 'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE', 'GIT_PREFIX', 'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+];
+
+/** `env` (default process.env) minus the repo-location vars (case-insensitive, for Windows). */
+function gitEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([k]) => !GIT_LOCATION_ENV_VARS.includes(k.toUpperCase())));
+}
+
 module.exports = {
+  GIT_LOCATION_ENV_VARS,
+  gitEnv,
   classifyGitProbe,
   reportIfUndetermined,
   BLOCKING_GUARD_PROBE_TIMEOUT_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "main": ".opencode/plugins/gsd-core.js",
   "bin": {
@@ -91,7 +91,7 @@
     "gpt-tokenizer": "4.0.0",
     "js-yaml": "^4.3.2",
     "mutation-testing-metrics": "^3.7.3",
-    "re2js": "^2.8.6",
+    "re2js": "^2.8.7",
     "saxes": "6.0.0",
     "tap-parser": "18.3.4",
     "typescript": "^6.0.3",
@@ -146,7 +146,7 @@
     "lint:gate-positive-control": "node scripts/lint-gate-positive-control.cjs",
     "lint:frontmatter-fence-drift": "node scripts/lint-frontmatter-fence-drift.cjs",
     "lint:response-language": "node scripts/lint-response-language-coverage.cjs",
-    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && npm run lint:retired-runtime-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/lint-portable-grep.cjs && node scripts/lint-allowed-tools-parity.cjs && node scripts/lint-phase-arg-assignment.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-planning-document-positive-control.cjs && node scripts/lint-pr-branch-pattern-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs && node scripts/lint-workflow-shellcheck.cjs && npm run lint:response-language && node scripts/lint-verify-lifecycle-writes.cjs && node scripts/lint-frontmatter-fence-drift.cjs && node scripts/lint-evaluation-scope-drift.cjs && node scripts/lint-gate-evidence-drift.cjs && node scripts/lint-gate-positive-control.cjs",
+    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && npm run lint:retired-runtime-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/lint-portable-grep.cjs && node scripts/lint-allowed-tools-parity.cjs && node scripts/lint-phase-arg-assignment.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-planning-document-positive-control.cjs && node scripts/lint-pr-branch-pattern-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs && node scripts/lint-workflow-shellcheck.cjs && npm run lint:response-language && node scripts/lint-verify-lifecycle-writes.cjs && node scripts/lint-frontmatter-fence-drift.cjs && node scripts/lint-evaluation-scope-drift.cjs && node scripts/lint-gate-evidence-drift.cjs && node scripts/lint-gate-positive-control.cjs && node scripts/lint-roadmap-progress-drift.cjs",
     "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
     "lint:regression-names": "node scripts/lint-regression-test-names.cjs",
     "lint:descriptions": "node scripts/lint-descriptions.cjs",

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

@@ -157,6 +157,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 +440,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 +466,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 +475,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/pi/package-agents/gsd-code-reviewer.md

@@ -60,6 +60,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 `__GSD_PI_ENGINE_ROOT__/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>
@@ -70,12 +72,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.
 
@@ -85,6 +92,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 `__GSD_PI_ENGINE_ROOT__/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.
 
@@ -173,6 +181,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:
@@ -193,22 +202,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:
@@ -252,6 +287,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
@@ -286,10 +322,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/pi/package-agents/gsd-executor.md

@@ -761,7 +761,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)
@@ -788,9 +795,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/pi/package-agents/manifest.json

@@ -3,8 +3,8 @@
     "gsd-advisor-researcher.md": "6988b236b53568bbcea7886d11ca9f0badf9aedb3f650d42ca894211d91aafe4",
     "gsd-ai-researcher.md": "bdc567357f7361d7e427a2730bdac17c0b28ecb1bcbbc687df68d573f0ee9f3e",
     "gsd-assumptions-analyzer.md": "56b243f4c50403cbc133ad8c91ae40aa1aeceadd6624d0fd26406ebf8c113205",
-    "gsd-code-fixer.md": "11a76631ffe74bf5deb707d69b8412bf4251fe8ae87e03cdd59bc28fc6e3904d",
-    "gsd-code-reviewer.md": "de2a37a6e76bf1d70ff16cb16881326b60a7236194d6126abe5a40d0fd9a98f5",
+    "gsd-code-fixer.md": "2d806b6bae3797a7757b4872a93790fe33a4f22e90f6e71f6344b52df3048d52",
+    "gsd-code-reviewer.md": "459b38676fd7e6b7bf147a9c3d88243630ff289366a359c7c489536d38b2bd21",
     "gsd-codebase-mapper.md": "5901db6721a6f2365be52819a41ab1c1590a7cbbbdc6d992dce2a7b99f7d12fb",
     "gsd-debug-session-manager.md": "7b68386a6ab0169eb4c1b44afa921b8196db1eac1af3a0dd07a87d5ae2b208ef",
     "gsd-debugger.md": "7328920b7fbee1b76af7259a14b96290562544d97c6ced1291e1e1f3529e1598",
@@ -16,7 +16,7 @@
     "gsd-domain-researcher.md": "f1b07d9c79dcb89c90e5af7f61adfa5dc73ebe8429783d8cb281d7ae2bdc682b",
     "gsd-eval-auditor.md": "9d77e7329c52741e7e62185b566231eb872c6b34afa6c869960a922af573b3d5",
     "gsd-eval-planner.md": "efc12a2822d77a5989db2e3efe83b7fda9f0509bb203910d7e26eb9369f89949",
-    "gsd-executor.md": "2302fb8b45608b422eb956db27d449e7d5f5c2d41c772188d675ad4f260c342e",
+    "gsd-executor.md": "45e9540f6380b1883ad5b144411b21447eef20f310cbd0ab7c72c2bdaf5f8c47",
     "gsd-framework-selector.md": "96d52931468372ee88c4f1d551c13c97d2be8079053b55d992e0ea1720d3d5c9",
     "gsd-integration-checker.md": "a233ab8c5c97b6099c649d1e9a09e88ff1ed1bf7df7c1b13bc766c33d58e09b9",
     "gsd-intel-updater.md": "26c70b81580cc5bf713959bdcc84a16a35569861d2e79c07c71258ccd05ba9bc",

package/pi/package-skills/gsd-update/SKILL.md

@@ -33,14 +33,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: /skill: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>