@opengsd/gsd-core 1.12.0 → 1.14.0

package/hooks/gsd-write-guard.js

@@ -105,10 +105,37 @@ const FLOOR_LINES = 40;
 // default to, a differently-cased path is the SAME real file — a Write to
 // '.planning/roadmap.md' clobbers ROADMAP.md while a case-sensitive match
 // waves it through.
+// #4455: workstream-scoped (and optionally project-scoped) variants —
+// planningDir(cwd) (src/planning-workspace.cts) resolves to
+// `.planning/[<project>/]workstreams/<ws>/...` whenever GSD_WORKSTREAM is
+// set. Before this, none of these three root-only patterns matched a
+// workstream-scoped target at all, so the ENTIRE guard (not just the
+// sentinel step — the shrink-ratio check too) silently never engaged for a
+// workstream-scoped ROADMAP.md/STATE.md/milestone-archive Write: exactly
+// the catastrophic-shrink scenario this file exists to stop, unguarded
+// under an active workstream. consumeSentinelFor's own `.planning`
+// derivation below is unaffected by this addition — it locates the single
+// outer `.planning` segment regardless of what's nested inside it, which is
+// also where the workflow's sentinel `printf` already writes, so no change
+// was needed there.
+//
+// Same gap exists one level up: planningDir(cwd) ALSO resolves to
+// `.planning/<project>/...` when GSD_PROJECT is set with NO GSD_WORKSTREAM
+// (project-only mode — the two env vars are independent; see planningDir's
+// own body). None of the patterns above cover that shape either. Found
+// during #4455's own review pass (same root cause, one more path variant)
+// — fixed in the same change rather than deferred, since it is the
+// identical defect class this PR already exists to close.
 const CURATED_PATTERNS = [
   /(?:^|\/)\.planning\/ROADMAP\.md$/i,
   /(?:^|\/)\.planning\/STATE\.md$/i,
   /(?:^|\/)\.planning\/milestones\/[^/]+-ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/milestones\/[^/]+-ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/milestones\/[^/]+-ROADMAP\.md$/i,
 ];
 
 // Count logical lines, ignoring a single trailing newline so that
@@ -156,7 +183,25 @@ function consumeSentinelFor(filePath, normalized) {
     // Path-bound: the token names exactly one file, resolved against the
     // .planning/ dir's parent (repo root) — same case-insensitive stance as
     // the curated match itself.
-    const namedNorm = path.resolve(path.join(planningDir, '..'), token).replace(/\\/g, '/').toLowerCase();
+    let namedPath = path.resolve(path.join(planningDir, '..'), token);
+    // Symmetry with the caller's own resolution (#4455 CI finding, macOS
+    // full-test shard): `filePath`/`normalized` were already realpath-resolved
+    // before this function was called (round 9 Minor 1's symlink-before-match
+    // fix), but `token` — typically an already-absolute path composed by the
+    // workflow's own init.* fields — was compared WITHOUT that same
+    // resolution. Wherever cwd sits under a symlink (macOS's /var ->
+    // /private/var is the common case, since that's exactly what os.tmpdir()
+    // resolves through, but any symlinked project/worktree checkout hits the
+    // same asymmetry), the token names the lexical path while `normalized`
+    // names the realpath — a validly-armed sentinel then never matches, and a
+    // legitimate milestone-reset Write stays incorrectly blocked. The named
+    // file is already known to exist (the caller only reaches this function
+    // after successfully reading it), so realpath is expected to succeed;
+    // keep the lexical path on failure, matching the caller's own fallback.
+    try {
+      namedPath = fs.realpathSync(namedPath);
+    } catch { /* keep the lexical path */ }
+    const namedNorm = namedPath.replace(/\\/g, '/').toLowerCase();
     if (namedNorm !== normalized.toLowerCase()) {
       return false; // armed for a different file — leave it for that write
     }

package/hooks/hooks.json

@@ -28,6 +28,12 @@
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-write-guard.js\"", "timeout": 5 }
         ]
       },
+      {
+        "matcher": "Read|Grep|Bash",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-secret-read-guard.js\"", "timeout": 5 }
+        ]
+      },
       {
         "matcher": "Agent|Task",
         "hooks": [

package/hooks/lib/dispatch-identity.js

@@ -0,0 +1,187 @@
+'use strict';
+// hooks/lib/dispatch-identity.js — the ONE canonical owner of the
+// `[gsd:dispatch phase="…" plan="…"]` marker format and its prose fallback
+// (#4594, epic #4630 Phase 1). See
+// `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md` for the full
+// rationale (behavior table, negative space, rejected alternatives).
+//
+// COLD-LOAD CONSTRAINT (load-bearing, not a style choice): this module MUST
+// require NOTHING — no `fs`, no `path`, and above all nothing under
+// `gsd-core/bin/lib/` or `ensure-runtime-build`. The guard hooks that consume
+// this module must load on a raw plugin-marketplace install where the
+// compiled lib is absent and the self-healing build seam has not run — a
+// hook that dies at module load is worse than one carrying a mirror. See
+// `tests/dispatch-identity.test.cjs`'s "cold tree load" test, which asserts
+// this by monkeypatching `Module._load` to throw on exactly those paths.
+
+// DISPATCH_PHASE_TOKEN_SOURCE is a DELIBERATE MIRROR of
+// `CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE` in `src/phase-id.cts`
+// (ADR-2121 owns the phase-token grammar; `gsd-core/bin/lib/phase-id.cjs` is
+// its compiled form). It cannot be an `require()`-based import: importing the
+// compiled lib here would violate the cold-load constraint above (either a
+// direct dependency on `gsd-core/bin/lib/` or a forced self-heal via
+// `ensure-runtime-build`), which is exactly the failure mode this module
+// exists to avoid for the guard hooks that consume it.
+//
+// Because this is a hand-copied mirror and not a shared reference, a
+// hand-edited grammar change on one side that is not mirrored on the other
+// does NOT fail loudly — both sides remain independently valid regex
+// sources, so the failure mode is a silent, invisible non-match (a dispatch
+// whose phase token the two owners now parse differently), never a thrown
+// error. `tests/dispatch-identity.test.cjs`'s "templates: prose token source
+// matches the case-flexible phase-id grammar" test pins this string equal to
+// the compiled source at test time specifically to turn that silent drift
+// into a loud, in-CI failure.
+const DISPATCH_PHASE_TOKEN_SOURCE = '\\d+[A-Za-z]?(?:\\.\\d+)*';
+
+// Bounded marker grammar: `[gsd:dispatch key="value" key2="value2"]`.
+// - Key names bounded to {1,31} — no key we emit or expect is anywhere near
+//   that long; this is purely a backstop against pathological input.
+// - Values bounded to {0,200} and forbidden from containing `"`, `]`, or any
+//   control character that could either close the marker early or forge a
+//   sibling key — enforced structurally by the negated character class, not
+//   by a separate validation pass.
+// Global flag so `findMarker` can scan forward through a large prompt.
+const MARKER_RE = /\[gsd:dispatch((?:\s+[A-Za-z][A-Za-z0-9_-]{0,31}="[^"\]\r\n]{0,200}")*)\s*\]/g;
+const MARKER_KV_RE = /([A-Za-z][A-Za-z0-9_-]{0,31})="([^"\]\r\n]{0,200})"/g;
+
+// Prose fallback frame: `execute plan <token> of phase <PHASE TOKEN>`.
+// - Case-insensitive, `\s+` throughout so CRLF (and any run of whitespace)
+//   parses identically to LF.
+// - The plan token is bounded (`\S{1,80}`) but its VALUE is deliberately
+//   discarded by the caller (see `parseDispatchIdentity` below) — captured
+//   only so the phase token can be anchored correctly after it.
+// - The phase token is bounded by `DISPATCH_PHASE_TOKEN_SOURCE`, replacing
+//   the old greedy `(\S+)`, so a directory-name suffix (`-auth`) or a
+//   sentence-terminating period is never swept into the token.
+const PROSE_RE = new RegExp(
+  `execute\\s+plan\\s+(\\S{1,80})\\s+of\\s+phase\\s+(${DISPATCH_PHASE_TOKEN_SOURCE})`,
+  'i',
+);
+
+/**
+ * Render the `[gsd:dispatch phase="…" plan="…"]` marker for a producer to
+ * embed verbatim in a dispatch description/prompt. Never throws.
+ *
+ * Emits only keys whose value is a non-empty string not containing `"`, `]`,
+ * `\r`, or `\n` — such a value is UNUSABLE and that key is omitted entirely,
+ * because embedding it could close the marker early and forge a second,
+ * attacker-controlled field. Key order is always `phase` then `plan`.
+ * Returns `''` when neither key is usable (nothing worth emitting).
+ */
+function renderDispatchIdentityMarker(input) {
+  const value = input && typeof input === 'object' ? input : {};
+  const parts = [];
+  for (const key of ['phase', 'plan']) {
+    const v = value[key];
+    if (typeof v === 'string' && v.length > 0 && !/["\]\r\n]/.test(v)) {
+      parts.push(`${key}="${v}"`);
+    }
+  }
+  if (parts.length === 0) return '';
+  return `[gsd:dispatch ${parts.join(' ')}]`;
+}
+
+function emptyResult() {
+  return { phase: null, plan: null, source: null };
+}
+
+/**
+ * Scan `texts` in order for the first well-formed marker that yields at
+ * least one recognized key (`phase` and/or `plan`). Returns `{ phase, plan }`
+ * (one of the two possibly null, never both) or `null` if no QUALIFYING
+ * marker was found in any text. Unrecognized keys inside a marker are
+ * ignored (forward compatibility — a later `run=`/`wave=` key must not break
+ * a deployed parser).
+ *
+ * #4594 F1 fix: a marker that matches `MARKER_RE` but carries neither
+ * `phase=` nor `plan=` (e.g. only unrecognized keys, or an empty kv block)
+ * is NOT treated as "found" — it is skipped and scanning continues (later
+ * markers in the same text, then subsequent texts), falling through to the
+ * prose fallback if nothing qualifying turns up. Without this, prompt text
+ * that merely CONTAINS the literal marker syntax with no usable identifiers
+ * silently suppressed the prose fallback entirely, since the old
+ * implementation returned on the first syntactic match regardless of
+ * content.
+ */
+function findMarker(texts) {
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue;
+    MARKER_RE.lastIndex = 0;
+    let match;
+    while ((match = MARKER_RE.exec(text)) !== null) {
+      const kvBlock = match[1] || '';
+      let phase = null;
+      let plan = null;
+      MARKER_KV_RE.lastIndex = 0;
+      let kv;
+      while ((kv = MARKER_KV_RE.exec(kvBlock)) !== null) {
+        const [, key, val] = kv;
+        if (key === 'phase' && phase === null) phase = val;
+        else if (key === 'plan' && plan === null) plan = val;
+      }
+      if (phase === null && plan === null) continue;
+      return { phase, plan };
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan `texts` in order for the first `execute plan <token> of phase
+ * <PHASE TOKEN>` frame. Returns `{ phase }` or `null`.
+ *
+ * The prose fallback returns `plan: null` DELIBERATELY (enforced by the
+ * caller, not here): the prose plan token (e.g. `02`) is a bare in-phase
+ * plan number, a different namespace from the sentinel's `plan_id` (e.g.
+ * `03-02-hardening`, which is phase-prefixed AND slugged). Reporting the
+ * prose plan token as the parsed `plan` is exactly the false-mismatch bug
+ * this module exists to fix — an absent value is honestly "cannot compare",
+ * while a wrong value silently forges a mismatch on every dispatch. Do not
+ * "fix" this by threading the plan token through — that was the bug.
+ */
+function findProse(texts) {
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue;
+    const match = PROSE_RE.exec(text);
+    if (match) {
+      return { phase: match[2] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse dispatch identity out of one or more texts (a short description, a
+ * full prompt body, etc). Never throws for any input type; non-string
+ * entries are skipped.
+ *
+ * Pass 1: scan all texts in order for a well-formed marker; the first one
+ * wins outright (marker beats prose even if prose appears earlier in the
+ * same text — see the design doc's row 8).
+ * Pass 2 (only if no marker was found anywhere): scan all texts in order for
+ * the prose frame; the first match wins. `plan` is always `null` from this
+ * path (see `findProse`'s doc comment).
+ *
+ * Returns `{ phase, plan, source }` where `source` is `'marker' | 'prose' |
+ * null`.
+ */
+function parseDispatchIdentity(...texts) {
+  const marker = findMarker(texts);
+  if (marker) {
+    return { phase: marker.phase, plan: marker.plan, source: 'marker' };
+  }
+
+  const prose = findProse(texts);
+  if (prose) {
+    return { phase: prose.phase, plan: null, source: 'prose' };
+  }
+
+  return emptyResult();
+}
+
+module.exports = {
+  DISPATCH_PHASE_TOKEN_SOURCE,
+  renderDispatchIdentityMarker,
+  parseDispatchIdentity,
+};

package/hooks/lib/filename-classification.js

@@ -0,0 +1,64 @@
+'use strict';
+// hooks/lib/filename-classification.js — hand-written, NOT generated. One
+// tiny, deliberately-named filename slicer.
+//
+// WHY this exists: issue #4580 was caused by comparing "everything after the
+// `.env.` prefix" — a multi-segment token like `local.example` — against a
+// set whose members are FINAL EXTENSIONS (`example`). `.env.local.example`
+// was classified by its full `local.example` tail, which is not in a set
+// built from bare extensions, so the comparison silently failed. This module
+// deliberately exposes ONLY the final-extension answer so the wrong token
+// can't be picked by accident at a call site. The "everything after the
+// first dot" form is intentionally NOT exported: no caller needs it, and an
+// unused export is dead code.
+
+/**
+ * The segment after the LAST dot in `name`. A string with no dot IS its own
+ * final extension. Inert on non-strings/empty input: never throws, returns
+ * ''.
+ *
+ * @param {*} name
+ * @returns {string}
+ */
+function finalExtension(name) {
+  if (typeof name !== 'string' || name === '') return '';
+  const i = name.lastIndexOf('.');
+  return i === -1 ? name : name.slice(i + 1);
+}
+
+/**
+ * Strips ALL trailing dots and spaces from `name`, repeatedly, from the end
+ * of the basename.
+ *
+ * WHY: Win32 strips trailing dots and trailing spaces from each path
+ * component when resolving a filesystem path — `.env.`, `.env..`, `.env `,
+ * and `.env. ` all resolve to the same on-disk file as `.env` on Windows.
+ * These are therefore ALIASES for the protected name, not distinct names,
+ * and a guard that classifies the literal string without normalizing first
+ * can be bypassed by any of them. This is not cosmetic tidying — it closes
+ * that Windows path-alias bypass.
+ *
+ * This runs UNCONDITIONALLY on every host platform (macOS, Linux, Windows),
+ * not only when actually running on Windows: the guard must behave
+ * identically everywhere, and a name is judged by what Win32 would resolve
+ * it to, regardless of what OS the hook happens to run on.
+ *
+ * @param {*} name
+ * @returns {string}
+ */
+function normalizeWindowsBasename(name) {
+  if (typeof name !== 'string' || name === '') return '';
+  let end = name.length;
+  while (end > 0 && (name[end - 1] === '.' || name[end - 1] === ' ')) end--;
+  return name.slice(0, end);
+}
+
+// Last `/`- or `\`-separated segment, ignoring trailing separators. A string
+// with no separator IS its own last segment.
+function lastSegment(tok) {
+  const s = tok.replace(/[\\/]+$/, '');
+  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
+  return i === -1 ? s : s.slice(i + 1);
+}
+
+module.exports = { finalExtension, normalizeWindowsBasename, lastSegment };

package/hooks/lib/git-cmd.js

@@ -180,4 +180,213 @@ function isGitSubcommand(cmd, sub) {
   return tokens[subIdx] === sub;
 }
 
-module.exports = { isGitSubcommand, tokenize, extractBranchArgument, skipToSubcommand };
+/**
+ * Resolve a `-m` message argument to its SUBJECT — the first line of the commit
+ * message — resolving the command-substituted heredoc form to the heredoc
+ * BODY's first line.
+ *
+ * PURE STRING FUNCTION. It deliberately does NOT tokenize or walk the command
+ * line: selecting *which* argument is the message stays with the caller, exactly
+ * as before, so this cannot change which commands are validated. An earlier
+ * revision of this fix did walk tokens and regressed four separate cases —
+ * `git commit -- -m WIP` (a pathspec), `git commit --amend && echo -m WIP` (a
+ * later command's flag), `-m "" --allow-empty-message` (the scanner drops empty
+ * tokens, so the following flag became the subject), and unquoted
+ * `git commit -m WIP`. All were allowed upstream and would have started being
+ * blocked. Reported in review of #3802.
+ *
+ * The defect this DOES fix: `gsd-validate-commit.sh` captured the message with
+ * `-m[[:space:]]+"([^"]+)"`, and bash `[^"]` matches newlines, so the widely
+ * used agent-authored commit idiom
+ *
+ *     git commit -m "$(cat <<'EOF'
+ *     feat(auth): add login flow
+ *     EOF
+ *     )"
+ *
+ * captured the whole span up to the final quote at `)"`. Taking its first line
+ * yielded the literal `$(cat <<'EOF'`, which can never satisfy Conventional
+ * Commits, so every heredoc-form commit was blocked regardless of its message.
+ *
+ * Recognition is anchored at BOTH ends and requires a command substitution, so
+ * an ordinary message merely CONTAINING — or ending in — `<<WORD` is not
+ * mistaken for an opener. Without the `^\$\(` anchor,
+ * `-m "WIP notes <<EOF\nfix: smuggled subject"` resolved to the second line and
+ * ALLOWED a non-conforming commit: an enforcement bypass, not just a
+ * misclassification (review of #3802).
+ *
+ * NOT resolved, by design: an UNQUOTED delimiter (`<<EOF`). bash expands `$var`
+ * and `$(...)` in that body, so the literal text here is not what git receives.
+ * An earlier revision resolved it anyway and called the gap "the same
+ * pre-existing limit as expansions in a plain `-m` argument" — that framing was
+ * wrong on both halves: on base the whole heredoc form was blocked, so this fix
+ * CREATED the path, and it dodged the length gate as well as the format gate.
+ * See the expansion guard in the body (review of #3816, round 4).
+ *
+ * KNOWN LIMIT: the DOUBLE-QUOTED delimiter spelling (`<<"EOF"`) is resolvable
+ * here but unreachable through the caller — `gsd-validate-commit.sh`'s
+ * double-quoted `-m` capture stops at the first `"`, which in that spelling is
+ * the delimiter's own quote, so the resolver only ever sees a truncated opener
+ * and the commit stays blocked. Its single-quoted `-m` capture DOES deliver the
+ * spelling intact, which is why an earlier revision's claim of unreachability
+ * was false; the caller now gates the resolver on the double-quoted arm alone
+ * (review of #3816, round 4), so the claim holds again — for that reason, not
+ * by luck. That is the pre-fix behaviour for the whole form (fail closed, a
+ * false positive on one rare spelling), and widening the bash capture to span
+ * inner quotes would change what is captured for EVERY message containing one —
+ * a regression class this fix deliberately does not touch (Codex review of
+ * #3816). The same capture truncation blocks a `"` in the SUBJECT LINE itself,
+ * where it lands inside the line being measured. It does NOT block a `"` on a
+ * later body line: the subject is already complete before the truncation point,
+ * so that message resolves and is allowed (measured; an earlier revision of this
+ * comment and of the changeset claimed a `"` ANYWHERE blocked, which is false —
+ * Codex review of #3816, round 4). The truncation guard below is what keeps the
+ * unmeasurable half fail-closed. Two more legal-but-unrecognized spellings
+ * stay blocked the same fail-closed way: an env-prefixed cat
+ * (`$(A=1 cat <<'EOF'`) and an option-terminated cat (`$(cat -- <<'EOF'`) —
+ * recognizing either would mean modelling bash prefix words here, cost with
+ * no reported user (review of #3816, round 3).
+ *
+ * @param {string} messageArg - the raw `-m` argument, already selected by the caller
+ * @returns {string} the subject to validate
+ */
+function resolveCommitSubject(messageArg) {
+  // CRLF-tolerant split. With a bare split('\n') every body line kept its \r,
+  // so `body.indexOf(delimiter)` never matched on CRLF input: the truncation
+  // guard was inert, an empty CRLF message resolved to 'EOF\r' instead of '',
+  // and a real 72-char subject measured 73 (review of #3816). Splitting on
+  // /\r?\n/ is the repo-wide remedy for this recurring defect class.
+  const lines = String(messageArg == null ? '' : messageArg).split(/\r?\n/);
+  // The path prefix is a PATH-CHARACTER class, not \S*: `\S*` accepted
+  // `id;/bin/cat`, so `$(id;/bin/cat <<'EOF' ...` was resolved to its heredoc
+  // body while bash actually runs `id` first and git's real subject is `id`'s
+  // OUTPUT — an enforcement bypass (Codex review of #3816). A prefix carrying
+  // any shell metacharacter now fails recognition, which falls back to the
+  // opener line and the format gate: fail closed, exactly the pre-fix
+  // behaviour for the whole form.
+  //
+  // Whitespace inside the recognition is ASCII space/tab — [ \t], never \s —
+  // because JavaScript \s includes Unicode whitespace bash does NOT split on:
+  // `$(<NBSP>/bin/cat <<'EOF'` was recognized here while bash reads
+  // `<NBSP>/bin/cat` as the executable NAME, so recognition claimed a
+  // substitution that does not run cat (Codex review of #3816, round 2). The
+  // same ASCII rule as the blank-line skip below, for the same reason.
+  // `cat[ \t]*<<`, not `+`: bash accepts `cat<<'EOF'` with no space (review of
+  // #3816, round 3), and recognizing it costs nothing — the token before `<<`
+  // is still literally `cat`.
+  //
+  // The path prefix must be ABSOLUTE (Codex review of #3816, round 4). The old
+  // `[\w./-]*\/` also accepted `./cat` and `../evil/cat`, so a relative
+  // executable that merely ENDS in `cat` was trusted to echo its stdin: with a
+  // planted `../evil/cat` printing `WIP injected`, the resolver validated the
+  // heredoc body while git's real subject was `WIP injected` (measured
+  // base=2 -> head=0 against a real commit). Requiring `/` up front costs
+  // nothing real — `/bin/cat` and a bare `cat` both still resolve.
+  //
+  // AN ABSOLUTE PATH IS NOT AN IDENTITY EITHER (independent review of #3816,
+  // round 8). Round 4 stopped at "must be absolute", so any absolute path
+  // ENDING in `/cat` was still trusted to echo its stdin — the very thing the
+  // round-4 reasoning rejected one spelling earlier. With an executable at
+  // `/some/scratch/dir/cat` printing `WIP injected`, the resolver validated
+  // the conforming heredoc body while git's real subject was `WIP injected`
+  // (measured on bash 3.2.57 and 5.3.15 against a real commit: hook exit 0,
+  // `git cat-file -p` subject `WIP injected`, while the same command through
+  // `./cat` was already refused). The prefix is now the canonical system
+  // locations, which is the only claim a string can support. `/usr/local/bin`
+  // is deliberately excluded: it is user-writable on ordinary machines, which
+  // is the plantable case this guard exists for.
+  //
+  // RESIDUAL, not fixable from a string: a bare `cat` shadowed earlier on PATH
+  // has the same effect and is indistinguishable here. It is also not a
+  // meaningful boundary — anyone who can plant an executable on PATH can run
+  // `git commit` directly — so this hook stays an authoring guard, not a
+  // security control.
+  //
+  // The delimiter alternatives are split so the BARE spelling is its own group:
+  // `\\(...)` (backslash-quoted) and `(...)` (bare) were one `\\?(...)` branch,
+  // which conflated the only two spellings that differ in bash. See the
+  // expansion guard below.
+  const opener = /^\$\([ \t]*(?:\/(?:usr\/)?bin\/)?cat[ \t]*<<(-?)[ \t]*(?:'([^']+)'|"([^"]+)"|\\([^\s'"();|&<>\\]+)|([^\s'"();|&<>\\]+))[ \t]*$/
+    .exec(lines[0]);
+  if (!opener) return lines[0];
+
+  // EXPANSION GUARD (review of #3816, round 4 — BLOCKER). Only `<<'D'`, `<<"D"`
+  // and `<<\D` suppress expansion. A BARE `<<D` is expanded by bash, so the body
+  // captured here is NOT the text git receives, and measuring it is an
+  // enforcement bypass in both gates at once:
+  //
+  //     -m "$(cat <<EOF\nfeat: $UNSET_VAR\nEOF\n)"   git gets `feat:`  -> format gate dodged
+  //     -m "$(cat <<EOF\nfeat: ${LONG}\nEOF\n)"      git gets any length -> length gate dodged
+  //
+  // Both measured base=2 -> head=0 against the real hook. This is NOT the
+  // pre-existing plain-`-m` expansion limit an earlier revision claimed it was:
+  // on base the whole heredoc form was blocked, so no expansion inside a body
+  // ever reached an allow — this fix created the path, and closes it here.
+  // Same rule every other guard in this function follows: when the real subject
+  // cannot be known, fall back to the opener line, which fails the format gate.
+  if (opener[5]) return lines[0];
+
+  // `<<-` strips leading TABS from every body line, including the terminator.
+  const stripTabs = opener[1] === '-';
+  const delimiter = opener[2] || opener[3] || opener[4];
+  const body = lines.slice(1).map((l) => (stripTabs ? l.replace(/^\t+/, '') : l));
+
+  // TRUNCATION GUARD. The capture that produced this argument stops at the first
+  // `"`, so a message containing one arrives here missing its tail — and its
+  // terminator. Resolving anyway would hand the length gate a PREFIX of the real
+  // subject and let an over-long message through, an enforcement hole that did
+  // not exist before this fix (review of #3802). A body with no terminator is
+  // therefore not resolved at all: returning the opener line fails the format
+  // gate, which is exactly what this whole form did before the fix. The fix
+  // applies where the capture is complete and changes nothing where it is not.
+  const end = body.indexOf(delimiter);
+
+  // POST-TERMINATOR GUARD (review of #3816, round 3 — BLOCKER). Everything
+  // after the terminator is still part of the real message once bash
+  // substitutes: `-m "$(cat <<'EOF'\nfeat: ok\nEOF\n) <200 a's>"` expands to a
+  // single 200+ char subject, but discarding the tail measured 8 and DODGED
+  // COMMIT_SUBJECT_TOO_LONG — the same prefix-measurement class the truncation
+  // guard below exists for, missed on the other side of the terminator. The
+  // canonical idiom's tail is exactly one closing-paren line; anything else
+  // means the substitution is composed with more text, so fall back to the
+  // opener line — blocked, the pre-fix behaviour for the whole form.
+  if (end !== -1) {
+    const tail = body.slice(end + 1);
+    if (tail.length !== 1 || !/^[ \t]*\)[ \t]*$/.test(tail[0])) return lines[0];
+  }
+
+  // git's default `cleanup=whitespace` strips leading blank lines, so the subject
+  // is the first NON-EMPTY body line, not blindly the first one. Taking lines[1]
+  // returned '' for a body that starts blank and falsely blocked a conforming
+  // commit — the very defect class #3802 reports (review of #3802).
+  const scan = end === -1 ? body : body.slice(0, end);
+  // "Blank" is git's ASCII definition — space and tab — never JavaScript's
+  // trim(), whose Unicode whitespace class skips lines git KEEPS: a body whose
+  // first line is a NBSP resolved to the SECOND line while git's real subject
+  // is the NBSP line — an enforcement bypass (Codex review of #3816, verified
+  // against `git stripspace`, which preserves the c2a0 bytes). A Unicode-blank
+  // first line is now returned as the subject and fails the format gate: the
+  // same fail-closed direction git itself takes.
+  const idx = scan.findIndex((l) => !/^[ \t]*$/.test(l));
+  if (idx === -1) return end === -1 ? lines[0] : '';
+
+  // Truncation is only fatal to the line it lands IN. A captured line is complete
+  // exactly when another line follows it, because the capture kept its newline.
+  // So an unterminated body whose subject line is followed by more text is still
+  // measurable; only a subject line that runs to the end of a truncated capture
+  // is not, and that one falls back to the opener — which fails the format gate,
+  // exactly as this whole form did before the fix. Without this, the length gate
+  // measured a PREFIX of the real subject and let an over-long message through
+  // (review of #3802).
+  if (end === -1 && idx >= body.length - 1) return lines[0];
+
+  // git's `cleanup=whitespace` strips whitespace at BOTH ends of the line, not
+  // just leading blanks. Measuring the raw line rejected `feat: <66 x's>` plus
+  // three trailing spaces as 75 chars when git's actual subject is a conforming
+  // 72 — a still-blocked conforming commit, the very defect #3802 reports
+  // (review of #3816). Trailing only, here: leading blank-LINE handling is the
+  // findIndex above, and `<<-` leading-tab stripping already happened.
+  return scan[idx].replace(/[ \t]+$/, '');
+}
+
+module.exports = { isGitSubcommand, tokenize, extractBranchArgument, skipToSubcommand, resolveCommitSubject };

package/hooks/lib/injection-patterns.js

@@ -26,11 +26,29 @@
  */
 
 const INJECTION_PATTERNS = Object.freeze([
-  /ignore\s+(all\s+)?previous\s+instructions/i,
-  /ignore\s+(all\s+)?above\s+instructions/i,
-  /disregard\s+(all\s+)?previous/i,
-  /forget\s+(all\s+)?(your\s+)?instructions/i,
-  /override\s+(system|previous)\s+(prompt|instructions)/i,
+  // #4016: ONE filler-tolerant imperative-override pattern. It REPLACES the
+  // five narrow verb patterns (ignore x2 / disregard / forget / override) that
+  // used to sit here: they tolerated no filler between verb and noun, so a
+  // planted "forget all of your ..." phrasing (measured in the wild) matched
+  // nothing. A single pattern rather than narrow-plus-combined because both
+  // consumers count one finding PER PATTERN toward the severity threshold
+  // (3 = HIGH, blockable under security.injection_blocking): overlapping
+  // patterns made one sentence count twice and pushed a two-phrasing LOW
+  // payload to HIGH (PR #4061 review).
+  //   verbs    ignore|disregard|forget|discard|override. `override` carries
+  //            the old `override system|previous prompt|instructions` family;
+  //            `discard` is the synonym seen in the same planted phrasings.
+  //   fillers  at least ONE of all|of|the|your|my|<qualifier> must sit between
+  //            verb and noun (a lookahead, no repetition). Bare "override
+  //            rules" / "ignore instructions" are ordinary repo prose
+  //            (measured: 6 hits across docs and source) and stay unmatched.
+  //   tails    `disregard (all) previous` with no noun, and bare `forget` +
+  //            `instructions`, are kept verbatim because the old narrow
+  //            patterns accepted them; the superset is pinned by
+  //            tests/injection-patterns-parity.security.test.cjs.
+  //   known FP determined linter-doc prose such as "ignore (the) rules" trips
+  //            a single-pattern LOW advisory; one pattern can never block.
+  /(?:ignore|disregard|forget|discard|override)\s+(?=(?:all|of|the|your|my|system|previous|prior|above|earlier)\s)(?:all\s+)?(?:of\s+)?(?:the\s+|your\s+|my\s+)?(?:(?:system|previous|prior|above|earlier)\s+)?(?:instructions|directives|prompts?|rules)|disregard\s+(?:all\s+)?previous|forget\s+instructions/i,
   /you\s+are\s+now\s+(?:a|an|the)\s+/i,
   /act\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,
   /pretend\s+(?:you(?:'re| are)\s+|to\s+be\s+)/i,
@@ -42,4 +60,16 @@ const INJECTION_PATTERNS = Object.freeze([
   /<<\s*SYS\s*>>/i,
 ]);
 
-module.exports = { INJECTION_PATTERNS };
+// Short single-line label for a matched pattern, used for both the rendered
+// advisory prose and the typed `findings[].match` field in BOTH consumer
+// hooks. The raw regex source is not user-facing: the #4016 superset pattern
+// is ~280 characters, and gsd-prompt-guard.js echoed it verbatim into its
+// advisory (PR #4061 review nit). Byte-identical to the transform
+// gsd-read-injection-scanner.js carried inline since #3523, hoisted here so
+// one finding renders the same way in both hooks. Both hooks already require
+// this module, so this adds no new staging dependency.
+function describePattern(pattern) {
+  return pattern.source.replace(/\\s\+/g, '-').replace(/[()\\]/g, '').substring(0, 50);
+}
+
+module.exports = { INJECTION_PATTERNS, describePattern };

package/hooks/lib/isolation-deny-reason.js

@@ -36,4 +36,56 @@ const REASON_CODE = Object.freeze({
   NOT_ISOLATED_WORKTREE: 'not_isolated_worktree',
 });
 
-module.exports = { REASON_CODE };
+// #4594 row 15 / F2: values interpolated into a deny reason (sentinel/dispatch
+// phase and plan) come from a sentinel file on disk and, transitively, from
+// model-authored prompt text, neither of which is trusted — bound length and
+// strip control characters/newlines so a crafted value cannot forge extra
+// lines or otherwise inject content into the guard's stdout/stderr message
+// (same discipline as escaping an untrusted token before embedding it in a
+// message, e.g. phase-plan-index's `depends_on` warning).
+//
+// Originally duplicated byte-for-byte in hooks/gsd-agent-isolation-guard.js
+// and hooks/gsd-cursor-subagent-start.js (#4594 F2 review finding) — both
+// hooks already require this dependency-free module, so there is no
+// cold-load justification for the duplication the way there is for
+// hooks/lib/dispatch-identity.js's grammar mirror. Moved here as the single
+// owner; both hooks now import it.
+const REASON_INTERPOLATION_MAX_LEN = 64;
+
+// F6: also strip Unicode line/paragraph separators (U+2028/U+2029) and the
+// bidi-override/isolate control characters (U+202A-U+202E, U+2066-U+2069) —
+// none of these are in `[\x00-\x1f\x7f]`, so a crafted sentinel or dispatch
+// value carrying them could still visually reflow the deny message onto a
+// new line or reverse/hide part of it despite the ASCII control-char strip.
+const REASON_UNSAFE_CHARS_RE = new RegExp(
+  // eslint-disable-next-line no-control-regex -- deliberately stripping control chars/newlines
+  '[\\x00-\\x1f\\x7f\\u2028\\u2029\\u202a-\\u202e\\u2066-\\u2069]',
+  'g',
+);
+
+function sanitizeForReason(value) {
+  if (typeof value !== 'string' || value.length === 0) return '(none)';
+  const stripped = value.replace(REASON_UNSAFE_CHARS_RE, '');
+  return stripped.length > REASON_INTERPOLATION_MAX_LEN
+    ? `${stripped.slice(0, REASON_INTERPOLATION_MAX_LEN)}…`
+    : stripped;
+}
+
+function describeSentinelDiscard(sentinelDiscarded) {
+  const sentinelPhase = sanitizeForReason(sentinelDiscarded.sentinel.phase);
+  const sentinelPlan = sanitizeForReason(sentinelDiscarded.sentinel.plan);
+  const dispatchPhase = sanitizeForReason(sentinelDiscarded.dispatch.phase);
+  const dispatchPlan = sanitizeForReason(sentinelDiscarded.dispatch.plan);
+  return (
+    ` A fresh dispatch-isolation sentinel was present but did not apply to this dispatch ` +
+    `(sentinel phase="${sentinelPhase}" plan="${sentinelPlan}"; dispatch phase="${dispatchPhase}" ` +
+    `plan="${dispatchPlan}"), so it was not consulted.`
+  );
+}
+
+module.exports = {
+  REASON_CODE,
+  REASON_INTERPOLATION_MAX_LEN,
+  sanitizeForReason,
+  describeSentinelDiscard,
+};