@opengsd/gsd-core 1.19.0 → 1.20.1

package/hooks/dist/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/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/dist/lib/isolation-sentinel.js

@@ -29,6 +29,12 @@
 // of the same repo are separate directories on disk, so each gets its own
 // sentinel with no cross-worktree collision, no lock file needed.
 //
+// #5682: the single slot above is last-writer-wins, so two orchestrators sharing one checkout
+// overwrote each other's decision and the guard discarded the foreign record. The writer now ALSO
+// records each plan-scoped decision at `<cwd>/.gsd/dispatch-isolation/<phase>--<plan>.json`
+// (same payload, same cwd-derived location and forgery posture), and `readSentinel` consults the
+// record keyed by the dispatch's own phase/plan first, falling back to the single slot.
+//
 // #3045 SECURITY F3 (LOW, accepted risk — documented, not redesigned for):
 // the sentinel lives at a fixed, predictable, gitignored path inside the
 // PRIMARY checkout. An agent already running inside a legitimately isolated
@@ -64,6 +70,31 @@ const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'n
 
 const SENTINEL_RELATIVE_PATH = path.join('.gsd', 'dispatch-isolation-sentinel.json');
 
+// #5682: per-dispatch records, one file per `<phase>--<plan>` under this directory.
+const KEYED_SENTINEL_DIR = path.join('.gsd', 'dispatch-isolation');
+const SAFE_SENTINEL_KEY_RE = /^[A-Za-z0-9._-]{1,100}$/;
+
+/** #5682: strict allow-list for a phase/plan string that becomes a path segment. */
+function isSafeSentinelKey(s) {
+  return typeof s === 'string' && SAFE_SENTINEL_KEY_RE.test(s) && s !== '.' && s !== '..';
+}
+
+/** #5682: keyed record path for a dispatch, or null unless BOTH phase and plan are safe keys. */
+function keyedSentinelPath(root, phase, plan) {
+  if (!isSafeSentinelKey(phase) || !isSafeSentinelKey(plan)) return null;
+  return path.join(root, KEYED_SENTINEL_DIR, `${phase}--${plan}.json`);
+}
+
+/**
+ * #5682: phase-level keyed record path (`<phase>.json`, written when a decision carries no plan),
+ * or null unless the phase is a safe key. Two orchestrators recording plan-less decisions for
+ * different phases each keep their own file.
+ */
+function phaseSentinelPath(root, phase) {
+  if (!isSafeSentinelKey(phase)) return null;
+  return path.join(root, KEYED_SENTINEL_DIR, `${phase}.json`);
+}
+
 // #3045 SECURITY F2 fix: how long a written sentinel is trusted as "this
 // dispatch's decision" before a reader falls back to the conservative
 // registry+config check.
@@ -174,11 +205,51 @@ function resolveSentinelRoot(cwd) {
  * per the repo's clock-seam convention, so staleness is testable without
  * asserting on wall-clock time.
  */
-function readSentinel(cwd, { clock = Date } = {}) {
+function readSentinel(cwd, { clock = Date, dispatchIds = null } = {}) {
   const root = resolveSentinelRoot(cwd);
+
+  // #5682: candidates are the record keyed by this dispatch's own phase/plan, the phase-level
+  // record for its phase, and the single legacy slot. A keyed candidate counts only when it is
+  // well-formed and its contents agree with its own filename key; the legacy slot only when it
+  // applies to this dispatch. Among FRESH candidates the latest `writtenAt` wins, so a newer
+  // phase-level decision is not shadowed by an older plan-scoped one (and vice versa).
+  const keyedCandidates = [];
+  if (dispatchIds) {
+    const planFile = keyedSentinelPath(root, dispatchIds.phase, dispatchIds.plan);
+    if (planFile) {
+      const c = parseSentinelFile(planFile, clock);
+      if (c.present && !c.malformed && c.phase === dispatchIds.phase && c.plan === dispatchIds.plan) keyedCandidates.push(c);
+    }
+    const phaseFile = phaseSentinelPath(root, dispatchIds.phase);
+    if (phaseFile) {
+      const c = parseSentinelFile(phaseFile, clock);
+      if (c.present && !c.malformed && c.phase === dispatchIds.phase && c.plan === null) keyedCandidates.push(c);
+    }
+  }
+
+  const legacy = parseSentinelFile(sentinelPath(root), clock);
+  const legacyApplies = legacy.present && !legacy.malformed && sentinelAppliesToDispatch(legacy, dispatchIds);
+
+  const fresh = keyedCandidates.filter((c) => !c.stale);
+  if (legacyApplies && !legacy.stale) fresh.push(legacy);
+  if (fresh.length > 0) return latestWritten(fresh);
+
+  // Nothing fresh: a stale keyed record still feeds the aged-none path; otherwise the legacy
+  // slot is returned exactly as before.
+  if (keyedCandidates.length > 0) return latestWritten(keyedCandidates);
+  return legacy;
+}
+
+/** The candidate with the greatest `writtenAt` (ties keep the earlier-listed, i.e. most specific). */
+function latestWritten(candidates) {
+  return candidates.reduce((best, c) => (c.writtenAt > best.writtenAt ? c : best));
+}
+
+/** Parse and validate one sentinel file. Never throws. Shape: see `readSentinel`. */
+function parseSentinelFile(file, clock) {
   let raw;
   try {
-    raw = fs.readFileSync(sentinelPath(root), 'utf-8');
+    raw = fs.readFileSync(file, 'utf-8');
   } catch {
     return { present: false };
   }
@@ -348,6 +419,10 @@ function buildSentinelDiscard(sentinel, dispatchIds) {
 module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
+  KEYED_SENTINEL_DIR,
+  isSafeSentinelKey,
+  keyedSentinelPath,
+  phaseSentinelPath,
   SENTINEL_STALE_MS,
   AGED_NONE_MAX_MS,
   sentinelPath,

package/hooks/gsd-agent-isolation-guard.js

@@ -422,7 +422,7 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
     return { gsdProject: false, isolation: null, harnessFlag: null, error: null, sentinelDiscarded: null };
   }
 
-  const sentinel = readSentinel(cwd, { clock });
+  const sentinel = readSentinel(cwd, { clock, dispatchIds });
   // Hoisted so the "sentinel was present/fresh but did not apply" case below
   // (#4594 row 15 — Postel's-Law finding) can distinguish itself from
   // "absent"/"stale" without re-deriving applicability.

package/hooks/gsd-cursor-subagent-start.js

@@ -512,7 +512,7 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
   // Hoisted (readSentinel never throws) so the "present, fresh, but did not
   // apply" case (#4594 row 15) can be reported on every deny path below
   // instead of silently discarded.
-  const sentinel = readSentinel(root, { clock });
+  const sentinel = readSentinel(root, { clock, dispatchIds });
   const applies = sentinelAppliesToDispatch(sentinel, dispatchIds);
   const sentinelDiscarded = buildSentinelDiscard(sentinel, dispatchIds);
 

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/hooks/lib/isolation-sentinel.js

@@ -29,6 +29,12 @@
 // of the same repo are separate directories on disk, so each gets its own
 // sentinel with no cross-worktree collision, no lock file needed.
 //
+// #5682: the single slot above is last-writer-wins, so two orchestrators sharing one checkout
+// overwrote each other's decision and the guard discarded the foreign record. The writer now ALSO
+// records each plan-scoped decision at `<cwd>/.gsd/dispatch-isolation/<phase>--<plan>.json`
+// (same payload, same cwd-derived location and forgery posture), and `readSentinel` consults the
+// record keyed by the dispatch's own phase/plan first, falling back to the single slot.
+//
 // #3045 SECURITY F3 (LOW, accepted risk — documented, not redesigned for):
 // the sentinel lives at a fixed, predictable, gitignored path inside the
 // PRIMARY checkout. An agent already running inside a legitimately isolated
@@ -64,6 +70,31 @@ const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'n
 
 const SENTINEL_RELATIVE_PATH = path.join('.gsd', 'dispatch-isolation-sentinel.json');
 
+// #5682: per-dispatch records, one file per `<phase>--<plan>` under this directory.
+const KEYED_SENTINEL_DIR = path.join('.gsd', 'dispatch-isolation');
+const SAFE_SENTINEL_KEY_RE = /^[A-Za-z0-9._-]{1,100}$/;
+
+/** #5682: strict allow-list for a phase/plan string that becomes a path segment. */
+function isSafeSentinelKey(s) {
+  return typeof s === 'string' && SAFE_SENTINEL_KEY_RE.test(s) && s !== '.' && s !== '..';
+}
+
+/** #5682: keyed record path for a dispatch, or null unless BOTH phase and plan are safe keys. */
+function keyedSentinelPath(root, phase, plan) {
+  if (!isSafeSentinelKey(phase) || !isSafeSentinelKey(plan)) return null;
+  return path.join(root, KEYED_SENTINEL_DIR, `${phase}--${plan}.json`);
+}
+
+/**
+ * #5682: phase-level keyed record path (`<phase>.json`, written when a decision carries no plan),
+ * or null unless the phase is a safe key. Two orchestrators recording plan-less decisions for
+ * different phases each keep their own file.
+ */
+function phaseSentinelPath(root, phase) {
+  if (!isSafeSentinelKey(phase)) return null;
+  return path.join(root, KEYED_SENTINEL_DIR, `${phase}.json`);
+}
+
 // #3045 SECURITY F2 fix: how long a written sentinel is trusted as "this
 // dispatch's decision" before a reader falls back to the conservative
 // registry+config check.
@@ -174,11 +205,51 @@ function resolveSentinelRoot(cwd) {
  * per the repo's clock-seam convention, so staleness is testable without
  * asserting on wall-clock time.
  */
-function readSentinel(cwd, { clock = Date } = {}) {
+function readSentinel(cwd, { clock = Date, dispatchIds = null } = {}) {
   const root = resolveSentinelRoot(cwd);
+
+  // #5682: candidates are the record keyed by this dispatch's own phase/plan, the phase-level
+  // record for its phase, and the single legacy slot. A keyed candidate counts only when it is
+  // well-formed and its contents agree with its own filename key; the legacy slot only when it
+  // applies to this dispatch. Among FRESH candidates the latest `writtenAt` wins, so a newer
+  // phase-level decision is not shadowed by an older plan-scoped one (and vice versa).
+  const keyedCandidates = [];
+  if (dispatchIds) {
+    const planFile = keyedSentinelPath(root, dispatchIds.phase, dispatchIds.plan);
+    if (planFile) {
+      const c = parseSentinelFile(planFile, clock);
+      if (c.present && !c.malformed && c.phase === dispatchIds.phase && c.plan === dispatchIds.plan) keyedCandidates.push(c);
+    }
+    const phaseFile = phaseSentinelPath(root, dispatchIds.phase);
+    if (phaseFile) {
+      const c = parseSentinelFile(phaseFile, clock);
+      if (c.present && !c.malformed && c.phase === dispatchIds.phase && c.plan === null) keyedCandidates.push(c);
+    }
+  }
+
+  const legacy = parseSentinelFile(sentinelPath(root), clock);
+  const legacyApplies = legacy.present && !legacy.malformed && sentinelAppliesToDispatch(legacy, dispatchIds);
+
+  const fresh = keyedCandidates.filter((c) => !c.stale);
+  if (legacyApplies && !legacy.stale) fresh.push(legacy);
+  if (fresh.length > 0) return latestWritten(fresh);
+
+  // Nothing fresh: a stale keyed record still feeds the aged-none path; otherwise the legacy
+  // slot is returned exactly as before.
+  if (keyedCandidates.length > 0) return latestWritten(keyedCandidates);
+  return legacy;
+}
+
+/** The candidate with the greatest `writtenAt` (ties keep the earlier-listed, i.e. most specific). */
+function latestWritten(candidates) {
+  return candidates.reduce((best, c) => (c.writtenAt > best.writtenAt ? c : best));
+}
+
+/** Parse and validate one sentinel file. Never throws. Shape: see `readSentinel`. */
+function parseSentinelFile(file, clock) {
   let raw;
   try {
-    raw = fs.readFileSync(sentinelPath(root), 'utf-8');
+    raw = fs.readFileSync(file, 'utf-8');
   } catch {
     return { present: false };
   }
@@ -348,6 +419,10 @@ function buildSentinelDiscard(sentinel, dispatchIds) {
 module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
+  KEYED_SENTINEL_DIR,
+  isSafeSentinelKey,
+  keyedSentinelPath,
+  phaseSentinelPath,
   SENTINEL_STALE_MS,
   AGED_NONE_MAX_MS,
   sentinelPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/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.",
   "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">