@opengsd/gsd-core 1.12.0 → 1.13.0

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/managed-hooks-registry.cjs

@@ -36,6 +36,7 @@ const MANAGED_HOOKS = [
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',
   'gsd-read-injection-scanner.js',
+  'gsd-secret-read-guard.js',
   'gsd-session-state.sh',
   'gsd-statusline.js',
   'gsd-update-banner.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.12.0",
+  "version": "1.13.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": {
@@ -121,7 +121,8 @@
     "lint:table-schema-drift": "node scripts/lint-table-schema-drift.cjs",
     "lint:frontmatter-scalar-broad-grep": "node scripts/lint-frontmatter-scalar-broad-grep.cjs",
     "lint:removed-but-needed": "node scripts/lint-removed-but-needed.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 && 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/validate-registry.cjs && node scripts/lint-table-schema-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",
+    "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 && 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/validate-registry.cjs && node scripts/lint-table-schema-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",
     "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",
@@ -148,13 +149,12 @@
     "test:qa": "node scripts/run-tests.cjs --suite qa",
     "test:affected": "node scripts/run-affected-tests.cjs",
     "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --reporter text --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs",
-    "test:coverage:scripts-floor": "c8 check-coverage --lines 55 --include 'scripts/**/*.cjs' --exclude 'tests/**' --all",
+    "test:coverage:scripts-floor": "c8 report --check-coverage --lines 55 --merge-async --include 'scripts/**/*.cjs' --exclude 'tests/**' --all",
     "test:coverage:unit": "c8 --reporter text --reporter json-summary --merge-async --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs --suite unit && node scripts/check-coverage-gate.cjs",
-    "test:coverage:unit:raw": "c8 --reporter none node scripts/run-tests.cjs --suite unit",
+    "test:coverage:unit:raw": "c8 --reporter none --merge-async node scripts/run-tests.cjs --suite unit",
     "test:coverage:report": "c8 report --reporter text --reporter json-summary --merge-async --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all && node scripts/check-coverage-gate.cjs",
     "test:coverage:all": "npm run test:coverage",
     "test:mutation": "stryker run",
-    "test:mutation:since": "stryker run --incremental --since origin/next",
     "gen:features": "node scripts/gen-features.cjs",
     "gen:state-md-docs": "node scripts/gen-state-md-docs.cjs"
   },

package/scripts/build-hooks.js

@@ -61,6 +61,8 @@ const HOOKS_TO_COPY = [
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',
   'gsd-read-injection-scanner.js',
+  // Secret-file read guard (#4221) — replaces the installer's Read(.env*) deny rules
+  'gsd-secret-read-guard.js',
   'gsd-statusline.js',
   'gsd-update-banner.js',
   'gsd-workflow-guard.js',
@@ -71,10 +73,15 @@ const HOOKS_TO_COPY = [
   'gsd-session-state.sh',
   'gsd-validate-commit.sh',
   'gsd-phase-boundary.sh',
-  // Portable node resolver (#3662). Not a registered hook itself: managed JS
-  // hook commands under --portable-hooks route through it (bash <resolver>
-  // <baked-node> <script>) so node resolves at hook-fire time in every
-  // environment sharing the config root. Staged verbatim — no templating.
+  // Portable node resolver (#3662). Managed JS hook commands under
+  // --portable-hooks route through it (bash <resolver> <baked-node>
+  // <script>) so node resolves at hook-fire time in every environment
+  // sharing the config root. It IS registered in MANAGED_HOOKS
+  // (managed-hooks-registry.cjs) for staleness tracking like every other
+  // shipped .sh hook, and install.js stamps its {{GSD_VERSION}} header the
+  // same way (#4076 — the prior comment here claimed the opposite on both
+  // counts, which is why the header was missing and staleness detection was
+  // permanently broken for this file).
   'gsd-node-runner.sh',
   // Graphify auto-update hook (#3347 / PR #3557 / #3579). Opt-in via
   // .planning/config.json graphify.auto_update; off by default.

package/scripts/ci-test-scope.cjs

@@ -97,6 +97,10 @@ const RULES = [
     tests: [
       'tests/run-tests-harness.test.cjs',
       'tests/workflow-shell-pinning.test.cjs',
+      // #4220: the run-scoped temp root + computeSweepProtectSet ancestor-walk
+      // termination coverage — was previously not re-selected by an edit to
+      // scripts/run-tests.cjs, the exact file that shipped the #4020 hang.
+      'tests/run-tests-temp-root.test.cjs',
     ],
   },
   {
@@ -302,6 +306,9 @@ const RULES = [
       'tests/require-userprofile-with-home.rule.test.cjs',
       'tests/normalize-path-in-content.rule.test.cjs',
       'tests/require-fs-op-fallback.rule.test.cjs',
+      // #4244 (origin #4020/#4220 Windows CI hang) — see ADR-1703 amendment.
+      'tests/require-full-tmpdir-triad.rule.test.cjs',
+      'tests/no-unbounded-dirname-walk.rule.test.cjs',
     ],
   },
   {

package/scripts/docs-guard-registry.cjs

@@ -335,6 +335,16 @@ const DOCS_GUARD_TESTS = {
   ],
   'tests/progress-forensic.test.cjs': ['docs/COMMANDS.md'],
   'tests/repo-layout.test.cjs': ['docs/contributing/bootstrap.md'],
+  // Reads REQ-LANG-04 and runs every form it offers an author through the
+  // matcher that enforces it, so a reword of the requirement alone is exactly
+  // the change this guard must run on (#2529). Both paths are named because
+  // #3840 made docs/FEATURES.md a generated projection: the requirement's
+  // source is the fragment, and an edit there that is not regenerated would
+  // otherwise reach this guard through neither path.
+  'tests/response-language-coverage.test.cjs': [
+    'docs/FEATURES.md',
+    'docs/features/response-language-config.md',
+  ],
   'tests/reversibility-tagging.test.cjs': ['docs/reference/plan-md.md'],
   'tests/reviewer-docs-parity.test.cjs': [
     'docs/COMMANDS.md',

package/scripts/gen-loop-host-contract.cjs

@@ -30,7 +30,13 @@ const CONTRACT_PATH = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'loop-host-contr
 // The five step workflows in pipeline order
 const STEP_WORKFLOWS = [
   { file: 'discuss-phase.md', step: 'discuss' },
-  { file: 'plan-phase.md',    step: 'plan' },
+  {
+    file: 'plan-phase.md',
+    step: 'plan',
+    auxiliaryHosts: [
+      { file: 'quick.md', point: 'plan:pre', kinds: ['contribution'], into: 'planner' },
+    ],
+  },
   { file: 'execute-phase.md', step: 'execute' },
   { file: 'verify-work.md',   step: 'verify' },
   { file: 'ship.md',          step: 'ship' },
@@ -295,7 +301,7 @@ function buildContract(workflowsDir) {
   const contract = [];
   const allErrors = [];
 
-  for (const { file, step } of STEP_WORKFLOWS) {
+  for (const { file, step, auxiliaryHosts = [] } of STEP_WORKFLOWS) {
     const filePath = path.join(resolvedDir, file);
     let content;
     try {
@@ -325,6 +331,34 @@ function buildContract(workflowsDir) {
     const roleErrors = crossCheckRoles(content, entry.agentRoles, file);
     allErrors.push(...roleErrors);
 
+    for (const auxiliary of auxiliaryHosts) {
+      let auxiliaryContent;
+      try {
+        auxiliaryContent = fs.readFileSync(path.join(resolvedDir, auxiliary.file), 'utf8');
+      } catch (err) {
+        allErrors.push('Could not read auxiliary host ' + auxiliary.file + ': ' + String(err.message));
+        continue;
+      }
+
+      const wiredPoints = scanWiredPoints(auxiliaryContent);
+      if (!wiredPoints.has(auxiliary.point)) {
+        allErrors.push(
+          auxiliary.file + ': auxiliary host missing expected point "' + auxiliary.point + '"',
+        );
+        continue;
+      }
+
+      const wiredKinds = scanWiredKinds(auxiliaryContent, auxiliary.into).get(auxiliary.point) || new Set();
+      for (const kind of auxiliary.kinds) {
+        if (!wiredKinds.has(kind)) {
+          allErrors.push(
+            auxiliary.file + ': auxiliary host point "' + auxiliary.point +
+            '" missing expected kind "' + kind + '"',
+          );
+        }
+      }
+    }
+
     contract.push(entry);
   }
 
@@ -437,7 +471,10 @@ function main() {
  * registry generator, conformance gate) must derive from this rather than maintaining
  * a separate hardcoded list.
  */
-const HOST_LOOP_FILES = STEP_WORKFLOWS.map((w) => 'gsd-core/workflows/' + w.file);
+const HOST_LOOP_FILES = STEP_WORKFLOWS.flatMap(({ file, auxiliaryHosts = [] }) => [
+  'gsd-core/workflows/' + file,
+  ...auxiliaryHosts.map((host) => 'gsd-core/workflows/' + host.file),
+]);
 
 /**
  * Pure function: scan a text string for `loop render-hooks <point>` call sites.
@@ -475,9 +512,11 @@ const HOOK_KINDS = ['contribution', 'step', 'gate'];
  * - A deferral line (one carrying an `@`-included path to the generic
  *   contract, e.g. `@gsd-core/references/loop-hook-dispatch.md`) that names a
  *   kind (`kind == "step"`) covers that kind; a deferral line with no kind
- *   discriminator ("apply each entry") covers every kind. A bare §-citation
- *   of the reference (validation guidance only, no `@`) covers nothing —
- *   plan-phase cites the gate-validation section while dispatching only gates.
+ *   discriminator ("apply each entry") covers every kind only when no role
+ *   target is required. With `expectedInto`, the same segment must explicitly
+ *   name both the kind and that exact `into` target. A bare §-citation of the
+ *   reference (validation guidance only, no `@`) covers nothing — plan-phase
+ *   cites the gate-validation section while dispatching only gates.
  * - Otherwise a kind is covered when some LINE dispatches it unconditionally:
  *   a `kind == "<kind>"` discriminator with NO same-line narrowing to one
  *   hook (`ref.skill ==`, `ref.agent ==`, `ref.command ==`). A narrowed line
@@ -491,19 +530,26 @@ const HOOK_KINDS = ['contribution', 'step', 'gate'];
  * Pure: same input, same output; CRLF-safe (line splitting tolerates \r).
  *
  * @param {string} region  Dispatch text following one call site.
+ * @param {string} [expectedInto]  Optional role target required in the same segment.
  * @returns {Set<string>}
  */
-function coveredKindsInRegion(region) {
+function coveredKindsInRegion(region, expectedInto) {
   const covered = new Set();
   // Same-SEGMENT narrowing to ONE hook voids credit: `ref.skill ==`, `capId ==`,
-  // and `into ==` each special-case a subset, not the kind generally
+  // and `into ==` each special-case a subset, not the kind generally. An
+  // auxiliary host may name the one role it actually hosts via `expectedInto`;
+  // any other role target still voids credit.
   // (plan-phase's `kind == "contribution" and capId == "security"` is the
   // hand-rolled shape; `into == "planner"` covers only planner-targeted
   // contributions). Segments, not lines: execute-phase legitimately writes
   // "dispatch `kind == "step"` hooks per … . `ref.skill == "code-review"`:" —
   // the deferral is one sentence, the specialization the next; narrowing in a
   // DIFFERENT segment must not void the deferral's credit.
-  const narrowingRe = /(?:ref\.(?:skill|agent|command)|capId|into)\s*={2,3}/;
+  const identityNarrowingRe = /(?:ref\.(?:skill|agent|command)|capId)\s*={2,3}/;
+  const intoNarrowingRe = /into\s*={2,3}/;
+  const expectedIntoRe = expectedInto
+    ? new RegExp(`into\\s*={2,3}\\s*["']${escapeRegExp(expectedInto)}["']`)
+    : null;
   // Negated mentions describe an absence, not a dispatch ("Branch 1 — no active
   // step hooks (`activeHooks` has no entry with `kind == "step"`)" — ship.md).
   const negationRe = /\b(?:no|without|absent|lacks?|missing)\b[^.|]*kind\s*={2,3}/;
@@ -519,17 +565,22 @@ function coveredKindsInRegion(region) {
       }
       if (kindDiscriminators.length === 0) {
         // A deferral with no kind discriminator ("apply each entry per …")
-        // still covers every kind.
-        if (deferralRe.test(segment)) for (const kind of HOOK_KINDS) covered.add(kind);
+        // still covers every kind for generic hosts. An auxiliary host with a
+        // required role target must state both its kind and target explicitly.
+        if (!expectedInto && deferralRe.test(segment)) for (const kind of HOOK_KINDS) covered.add(kind);
         continue;
       }
       if (negationRe.test(segment)) continue;
+      const narrowed = identityNarrowingRe.test(segment) ||
+        (expectedInto
+          ? !expectedIntoRe.test(segment)
+          : intoNarrowingRe.test(segment));
       if (deferralRe.test(segment)) {
         // Deferral naming kinds ("dispatch `kind == "step"` hooks per …").
-        if (!narrowingRe.test(segment)) for (const kind of kindDiscriminators) covered.add(kind);
+        if (!narrowed) for (const kind of kindDiscriminators) covered.add(kind);
         continue;
       }
-      if (!narrowingRe.test(segment)) for (const kind of kindDiscriminators) covered.add(kind);
+      if (!narrowed) for (const kind of kindDiscriminators) covered.add(kind);
     }
   }
   return covered;
@@ -540,9 +591,10 @@ function coveredKindsInRegion(region) {
  * per point, the union of hook kinds its dispatch regions cover (#3606).
  *
  * @param {string} text  Content of a workflow file (or any text).
+ * @param {string} [expectedInto]  Optional role target an auxiliary host must dispatch.
  * @returns {Map<string, Set<string>>}  point → covered kinds.
  */
-function scanWiredKinds(text) {
+function scanWiredKinds(text, expectedInto) {
   const result = new Map();
   const siteRe = CALL_SITE_RE;
   const sites = [];
@@ -552,7 +604,7 @@ function scanWiredKinds(text) {
   for (let i = 0; i < sites.length; i++) {
     const regionEnd = i + 1 < sites.length ? sites[i + 1].start : Math.min(text.length, sites[i].start + REGION_CAP);
     const region = text.slice(sites[i].start, regionEnd);
-    const covered = coveredKindsInRegion(region);
+    const covered = coveredKindsInRegion(region, expectedInto);
     if (!result.has(sites[i].point)) result.set(sites[i].point, new Set());
     for (const kind of covered) result.get(sites[i].point).add(kind);
   }