@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/pr-changed-files.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * Shared truncation-detection helper for `gh pr view --json files` (#3211).
+ *
+ * GitHub's GraphQL `files` connection on a pull request is a paginated
+ * connection. `gh pr view --json files` requests it with a single page at
+ * `first: 100` and does NOT paginate through the rest — so any PR touching
+ * more than 100 files silently returns only the first 100, with no error and
+ * no indication in the `files` array itself that entries are missing.
+ * `changedFiles` (a separate, non-paginated scalar field) reports the true
+ * total. A policy that relaxes a gate based on "every changed file matches
+ * pattern X" must treat a `files` list it cannot confirm is complete as
+ * incomplete — i.e. fail closed — rather than silently approving a PR whose
+ * 101st+ file might violate the policy.
+ *
+ * This file lives at the top level of scripts/ rather than in scripts/lib/
+ * because scripts/lib/** is enumerated in bin/install.js and ships to users
+ * on install; this is CI-only tooling with no reason to be installed.
+ */
+
+// GitHub's GraphQL `files` connection is requested at `first: 100` by
+// `gh pr view --json files`; `gh` does not paginate this field.
+const FILE_LIST_PAGE_LIMIT = 100;
+
+/**
+ * Returns true iff `changedFiles` can be trusted as the COMPLETE list of
+ * files changed in the PR (i.e. it was not silently truncated).
+ *
+ * - An empty/non-array list cannot confirm anything about the PR — mirror
+ *   the fail-closed stance `allPathsAreTooling` already takes on an empty
+ *   list in scripts/pr-template-policy.cjs.
+ * - When the true total is known it is the AUTHORITY, at every list size —
+ *   not just when the list has hit the page cap. The 100-entry page cap is
+ *   only ONE way a list can be short of the truth; a `$GITHUB_OUTPUT`
+ *   heredoc terminated early by an attacker-named file, or a path
+ *   containing a newline, truncates or inflates the list just as
+ *   effectively, and at any length. Comparing against the total catches all
+ *   of them without enumerating the mechanisms.
+ * - Only when no total is supplied do we fall back to the page-cap
+ *   heuristic: a list below the cap cannot have been truncated BY THE CAP,
+ *   which is the only mechanism a caller without a total can rule out.
+ */
+function fileListIsComplete(changedFiles, changedFilesTotal) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return false;
+  if (Number.isInteger(changedFilesTotal)) return changedFilesTotal === changedFiles.length;
+  return changedFiles.length < FILE_LIST_PAGE_LIMIT;
+}
+
+/**
+ * Parses a newline-delimited env var (as produced by `git diff --name-only`
+ * or `gh pr view --json files -q '.files[].path'`) into a trimmed,
+ * empty-line-free array. Returns [] for null/undefined/empty input.
+ */
+function parseChangedFilesEnv(value) {
+  if (!value) return [];
+  return String(value)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+module.exports = { fileListIsComplete, FILE_LIST_PAGE_LIMIT, parseChangedFilesEnv };

package/scripts/pr-template-policy.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { matchesGlob } = require('path');
+const { fileListIsComplete, parseChangedFilesEnv } = require('./pr-changed-files.cjs');
 
 const TRUSTED_AUTHOR_ASSOCIATIONS = new Set([
   'CONTRIBUTOR',
@@ -142,8 +143,12 @@ function matchingTemplate(body) {
  * pattern in the allowlist. Returns false for an empty file list (no
  * files means we cannot confirm it is a tooling-only PR).
  */
-function allPathsAreTooling(changedFiles, allowlist) {
+function allPathsAreTooling(changedFiles, allowlist, changedFilesTotal) {
   if (!Array.isArray(changedFiles) || changedFiles.length === 0) return false;
+  // #3211: `gh pr view --json files` truncates at 100 entries with no
+  // in-band signal. A truncated list must not relax enforcement — an unseen
+  // 101st+ file could fall outside the tooling allowlist entirely.
+  if (!fileListIsComplete(changedFiles, changedFilesTotal)) return false;
   return changedFiles.every((file) =>
     allowlist.some((pattern) => matchesGlob(file, pattern)),
   );
@@ -159,13 +164,13 @@ function hasExemptMarker(body, regex) {
   return match[1].trim().length > 0;
 }
 
-function evaluatePrTemplate(body, authorAssociation, changedFiles) {
+function evaluatePrTemplate(body, authorAssociation, changedFiles, changedFilesTotal) {
   const association = String(authorAssociation || '').toUpperCase();
   const trusted = TRUSTED_AUTHOR_ASSOCIATIONS.has(association);
   const normalizedBody = String(body || '').trim();
 
   // --- Carve-out 1: all changed files are in the tooling allowlist ---
-  if (allPathsAreTooling(changedFiles, TOOLING_PATH_ALLOWLIST)) {
+  if (allPathsAreTooling(changedFiles, TOOLING_PATH_ALLOWLIST, changedFilesTotal)) {
     return {
       valid: true,
       action: 'pass',
@@ -235,13 +240,18 @@ function evaluatePrTemplate(body, authorAssociation, changedFiles) {
 }
 
 function main() {
+  // Preserve the existing distinction between "unset" (undefined) and
+  // "set but empty" ([]) — allPathsAreTooling treats them differently.
   const changedFiles = process.env.CHANGED_FILES
-    ? process.env.CHANGED_FILES.split('\n').map((f) => f.trim()).filter(Boolean)
+    ? parseChangedFilesEnv(process.env.CHANGED_FILES)
     : undefined;
+  const parsedTotal = Number.parseInt(process.env.CHANGED_FILES_TOTAL, 10);
+  const changedFilesTotal = Number.isNaN(parsedTotal) ? undefined : parsedTotal;
   const result = evaluatePrTemplate(
     process.env.PR_BODY || '',
     process.env.AUTHOR_ASSOCIATION || '',
     changedFiles,
+    changedFilesTotal,
   );
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (process.env.GITHUB_OUTPUT) {

package/scripts/prompt-injection-scan.sh

@@ -6,12 +6,29 @@
 #   scripts/prompt-injection-scan.sh --file path/to/file   # Scan a single file
 #   scripts/prompt-injection-scan.sh --dir agents/          # Scan all files in a directory
 #
-# Exit codes:
-#   0 = clean
-#   1 = findings detected
-#   2 = usage error
+# Exit codes (ADR-3889, #3908 — registered in gsd-core/bin/shared/exit-codes.json):
+#   0                = clean
+#   1                = findings detected
+#   $EXIT_USAGE       (64) = usage error (bad argv, missing --file/--dir target)
+#   $EXIT_NO_INPUT    (66) = ran; scope established; zero files in scope (genuinely empty)
+#   $EXIT_UNAVAILABLE (69) = could not establish scope (bad ref, not a repo, unreadable dir)
 set -euo pipefail
 
+# ─── Exit-code registry (ADR-3889, #3908) ────────────────────────────────────
+# Resolved relative to THIS script's location, not the caller's cwd. Loud,
+# non-zero failure if the fragment is missing — never fall back to a guessed
+# literal integer, and never let a missing registry silently degrade to
+# exit 0.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXIT_CODES_SH="$SCRIPT_DIR/../gsd-core/bin/shared/exit-codes.sh"
+if [[ ! -f "$EXIT_CODES_SH" ]]; then
+  echo "prompt-injection-scan: FATAL: exit-code registry not found at $EXIT_CODES_SH" >&2
+  echo "  Regenerate with: node scripts/gen-exit-code-registry.cjs --write" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+. "$EXIT_CODES_SH"
+
 # ─── Patterns ────────────────────────────────────────────────────────────────
 # Each pattern is a POSIX extended regex. Keep alphabetized by category.
 #
@@ -72,6 +89,15 @@ PATTERNS=(
   # `eval('...')` (single-quoted) silently went undetected on macOS while
   # passing on GNU-grep CI runners. Found auditing #3175; fixed here since it
   # is the same unanchored/portability defect class as the boundary fix.
+  #
+  # `exec` stays receiver-blind on purpose. A left boundary that excludes a
+  # preceding `.` would drop every member-position `.exec('…')` — including
+  # `require('child_process').exec('…')`, the single most common Node spelling
+  # of the vector this pattern exists to catch — and a receiver allowlist
+  # cannot restore it, because the literal `child_process` is not adjacent to
+  # `.exec`. The cost is that `RegExp.prototype.exec`, which takes a subject
+  # string rather than code, also matches; files that legitimately call it are
+  # handled by ALLOWLIST below, never by narrowing the pattern.
   '(^|[^[:alnum:]])eval[[:space:]]*\([[:space:]]*["'"'"']'
   'exec[[:space:]]*\([[:space:]]*["'"'"']'
   '(^|[^[:alnum:]])Function[[:space:]]*\([[:space:]]*["'"'"'].*return'
@@ -129,6 +155,22 @@ ALLOWLIST=(
   # asserts nothing: it is the payload the guard is required to catch, carried
   # as test DATA. Same class as the read-injection-scanner suites above.
   'tests/kimi-payload-field-shadowing.security.test.cjs'
+  # Phase-ID grammar regression tests exercise `RegExp.prototype.exec` via
+  # `re.exec('<phase-id>')` against fixtures like 'MANIFOLD-64-auth' / 'CK-64-auth'.
+  # The scanner's `exec('` code-execution pattern matches that benign method call,
+  # not an attack vector — same DEFECT.PROMPT-INJECTION-SCAN-COLLISION class as the
+  # test fixtures above. Pre-existing content (16 such calls on `next`); it surfaces
+  # here only because #2573's W024 `state_head` assertions make the file appear in
+  # the changed-file set the diff-mode scan walks.
+  'tests/health-validation.test.cjs'
+  # #2528 — same collision, same disposition: the continuation-grammar suite
+  # drives the tokenizer regexes directly via `re.exec('05-80-20')`, so the
+  # argument is the subject string, not a command. Exempted per file rather
+  # than by narrowing the `exec(` pattern: a left boundary excluding a preceding
+  # `.` would drop `require('child_process').exec('…')`, and a receiver
+  # allowlist cannot reach it either, because the literal `child_process` is
+  # not adjacent to `.exec`. See the note at the pattern itself.
+  'tests/continuation-grammar-parity.test.cjs'
 )
 
 is_allowlisted() {
@@ -150,33 +192,73 @@ collect_files() {
   case "$mode" in
     --diff)
       local base="${1:-origin/main}"
-      # Get changed files in the diff, filter to scannable extensions
-      git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>/dev/null \
-        | grep -E '\.(md|cjs|js|json|yml|yaml|sh)$' || true
+      # Run git separately from the filter pipe so its OWN exit status (not
+      # grep's) decides whether the diff could be established. stdout and
+      # stderr are captured SEPARATELY (never merged with `2>&1`) so that a
+      # warning git writes to stderr on an otherwise successful diff can
+      # never be mistaken for a filename in the file list. On failure the
+      # captured stderr is emitted as the diagnostic; on success it is
+      # forwarded as a warning, never folded into the file list.
+      # `|| true` on the filter below is CORRECT (not gratuitous): `grep -E`
+      # exits 1 when nothing matches the scannable extensions (e.g. a diff
+      # touching only non-scannable file types), which is a legitimate empty
+      # result, not a failure to run.
+      local raw status err_file
+      err_file=$(mktemp)
+      raw=$(git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>"$err_file")
+      status=$?
+      if (( status != 0 )); then
+        cat "$err_file" >&2
+        rm -f "$err_file"
+        exit "$EXIT_UNAVAILABLE"
+      fi
+      if [[ -s "$err_file" ]]; then
+        echo "Warning: git diff emitted stderr output:" >&2
+        cat "$err_file" >&2
+      fi
+      rm -f "$err_file"
+      printf '%s\n' "$raw" | grep -E '\.(md|cjs|js|json|yml|yaml|sh)$' || true
       ;;
     --file)
       if [[ -f "$1" ]]; then
         echo "$1"
       else
         echo "Error: file not found: $1" >&2
-        exit 2
+        exit "$EXIT_USAGE"
       fi
       ;;
     --dir)
       local dir="$1"
       if [[ ! -d "$dir" ]]; then
         echo "Error: directory not found: $dir" >&2
-        exit 2
+        exit "$EXIT_USAGE"
+      fi
+      # Same treatment as --diff: a `find` that fails (e.g. permission
+      # denied) must not be reported as an empty directory, and stdout/stderr
+      # are captured separately so a stderr warning never enters the file list.
+      local raw status err_file
+      err_file=$(mktemp)
+      raw=$(find "$dir" -type f \( -name '*.md' -o -name '*.cjs' -o -name '*.js' -o -name '*.json' -o -name '*.yml' -o -name '*.yaml' -o -name '*.sh' \) \
+        ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' 2>"$err_file")
+      status=$?
+      if (( status != 0 )); then
+        cat "$err_file" >&2
+        rm -f "$err_file"
+        exit "$EXIT_UNAVAILABLE"
+      fi
+      if [[ -s "$err_file" ]]; then
+        echo "Warning: find emitted stderr output:" >&2
+        cat "$err_file" >&2
       fi
-      find "$dir" -type f \( -name '*.md' -o -name '*.cjs' -o -name '*.js' -o -name '*.json' -o -name '*.yml' -o -name '*.yaml' -o -name '*.sh' \) \
-        ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' 2>/dev/null || true
+      rm -f "$err_file"
+      printf '%s\n' "$raw"
       ;;
     --stdin)
       cat
       ;;
     *)
       echo "Usage: $0 --diff [base] | --file <path> | --dir <path> | --stdin" >&2
-      exit 2
+      exit "$EXIT_USAGE"
       ;;
   esac
 }
@@ -215,7 +297,7 @@ scan_file() {
 main() {
   if [[ $# -eq 0 ]]; then
     echo "Usage: $0 --diff [base] | --file <path> | --dir <path>" >&2
-    exit 2
+    exit "$EXIT_USAGE"
   fi
 
   local mode="$1"
@@ -225,8 +307,12 @@ main() {
   files=$(collect_files "$mode" "$@")
 
   if [[ -z "$files" ]]; then
+    # collect_files already exited (UNAVAILABLE/USAGE) for anything that
+    # could not establish scope. Reaching here with an empty result means
+    # scope WAS established and is genuinely empty — that is NO_INPUT, not a
+    # silent clean pass.
     echo "prompt-injection-scan: no files to scan"
-    exit 0
+    exit "$EXIT_NO_INPUT"
   fi
 
   local total=0

package/scripts/require-issue-link-policy.cjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Require-issue-link policy (#3211, preserving #1389).
+ *
+ * Replaces the shell-only `grep -qiE '(closes|fixes|resolves)\s+#[0-9]+'`
+ * step with a pure, testable `evaluateIssueLink` verdict function so a PR
+ * that only REFERENCES an issue (rather than closing it — e.g. a follow-up
+ * regression-coverage PR) is not forced to fabricate a closing keyword, while
+ * two pre-existing constraints are preserved exactly:
+ *
+ *   1. (#1389, anti-forgery) The backmerge exemption only fires when the
+ *      head ref carries the backmerge prefix AND the PR is same-repo (not a
+ *      fork) — dropping the `sameRepo` conjunct would let a fork forge a
+ *      branch name to bypass the issue-link requirement entirely.
+ *   2. (#3211, truncation) `gh pr view --json files` truncates the file list
+ *      at 100 entries with no in-band signal that it did so (see
+ *      scripts/pr-changed-files.cjs). The reference-only carve-out below
+ *      only applies when every changed file is a test/doc file, so a PR
+ *      whose file list may be truncated must fail closed rather than let an
+ *      unseen 101st+ file (which could touch `src/`) slip through.
+ *
+ * Tests assert on the typed ISSUE_LINK_REASON enum, never on free text.
+ */
+
+const { fileListIsComplete, parseChangedFilesEnv } = require('./pr-changed-files.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const ISSUE_LINK_REASON = Object.freeze({
+  OK_CLOSING_KEYWORD: 'ok_closing_keyword',
+  OK_BACKMERGE_EXEMPT: 'ok_backmerge_exempt',
+  OK_FOLLOWUP_REFERENCE: 'ok_followup_reference',
+  FAIL_NO_ISSUE_REFERENCE: 'fail_no_issue_reference',
+  FAIL_REFERENCE_NEEDS_CLOSING: 'fail_reference_needs_closing',
+  FAIL_FILE_LIST_INCOMPLETE: 'fail_file_list_incomplete',
+});
+
+// #1389: backmerge PRs are opened by CI against `next`, never by a human or a
+// fork, so they are exempt from the issue-link requirement outright — but
+// ONLY when combined with `sameRepo === true` below (see header comment).
+const BACKMERGE_BRANCH_PREFIX = 'chore/backmerge-main-to-next-';
+
+// A follow-up-only PR (references an issue without closing it) is only
+// allowed to skip the closing keyword when every changed file is a test or
+// doc file — i.e. it cannot be the PR that actually implements the fix.
+const EXEMPT_PATH_PREFIXES = ['tests/', 'docs/'];
+
+// Root-level markdown is documentation — this mirrors the repo's own doc-only
+// classifier (.claude/hooks/pre-pr-gate.sh:111), whose `[^/]+\.md` anchor is
+// deliberately root-only so runtime-loaded text under a subdirectory
+// (gsd-core/workflows/*.md, agents/*.md, commands/**/*.md) stays gated.
+// CHANGELOG.md is excluded: scripts/changeset/lint.cjs classes a direct edit to
+// it as user-facing precisely to close a bypass, so it must not ride in on the
+// docs carve-out either.
+const EXCLUDED_ROOT_DOCS = new Set(['CHANGELOG.md']);
+
+// Case-insensitive lookup set derived from EXCLUDED_ROOT_DOCS. The exclusion
+// check below is case-insensitive because the `.md` extension test above it
+// already is (`/\.md$/i`) — `changelog.md` or `CHANGELOG.MD` would otherwise
+// slip past the exclusion while still passing the extension test. In
+// practice this is defense in depth rather than a live bypass: the GitHub
+// API always reports the real path with its actual, fixed casing (the
+// filesystem is case-sensitive on the runners this executes on), so a PR
+// cannot rename CHANGELOG.md to bypass the check by casing alone.
+const EXCLUDED_ROOT_DOCS_UPPER = new Set(
+  Array.from(EXCLUDED_ROOT_DOCS, (name) => name.toUpperCase()),
+);
+
+function isRootLevelDoc(normalizedPath) {
+  if (!normalizedPath) return false;
+  if (normalizedPath.includes('/')) return false;
+  if (!/\.md$/i.test(normalizedPath)) return false;
+  if (EXCLUDED_ROOT_DOCS_UPPER.has(normalizedPath.toUpperCase())) return false;
+  return true;
+}
+
+// Mirrors the shipped `grep -qiE '(closes|fixes|resolves)\s+#[0-9]+'` exactly:
+// no additional keywords, no `\b` anchors (the shell grep it replaces has
+// none either) — see the corpus-parity test in
+// tests/require-issue-link-policy.test.cjs.
+const CLOSING_KEYWORD_REGEX = /(?:closes|fixes|resolves)\s+#[0-9]+/i;
+
+// Accepts a soft "this PR relates to #N" reference without claiming to close
+// it. The leading `\b` prevents matching inside a longer word (e.g. `xref#1`,
+// `prefs #1`) because there is no word-boundary transition between the
+// preceding word character and the start of the alternative — verified
+// explicitly for `preferences #1` / `unreferenced #1` in the test suite.
+const FOLLOWUP_REFERENCE_REGEX = /\b(?:refs?|references?|relates\s+to|related\s+to|follow[-\s]?up\s+to)\s+#[0-9]+/i;
+
+function hasClosingKeyword(body) {
+  return CLOSING_KEYWORD_REGEX.test(String(body || ''));
+}
+
+function hasFollowUpReference(body) {
+  return FOLLOWUP_REFERENCE_REGEX.test(String(body || ''));
+}
+
+// Path separator normalization — unconditional, per repo convention (see
+// CLAUDE.md "Path-sep normalization"), so a Windows-style diff entry like
+// `tests\windows\a.test.cjs` is still recognized as tests/-prefixed.
+function normalizePath(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+/**
+ * Returns true iff every changed file qualifies as a test/doc file, i.e. each
+ * one is one of:
+ *   1. under one of EXEMPT_PATH_PREFIXES (`tests/`, `docs/`) — the trailing
+ *      slash on each prefix makes this directory-boundary aware, so
+ *      lookalikes like `tests-e2e/`, `testsuite/`, or `docsite/` are
+ *      correctly rejected (they are not `tests/` or `docs/`); or
+ *   2. a root-level markdown file (no `/`, `.md` extension, case-insensitive)
+ *      that is not in EXCLUDED_ROOT_DOCS — see isRootLevelDoc.
+ */
+function allPathsAreTestsOrDocs(changedFiles) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return false;
+  return changedFiles.every((file) => {
+    const normalized = normalizePath(file);
+    if (EXEMPT_PATH_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return true;
+    return isRootLevelDoc(normalized);
+  });
+}
+
+function evaluateIssueLink({ prBody, headRef, sameRepo, changedFiles, changedFilesTotal }) {
+  if (hasClosingKeyword(prBody)) {
+    return { ok: true, reason: ISSUE_LINK_REASON.OK_CLOSING_KEYWORD };
+  }
+
+  // #1389: `sameRepo === true` is required, not just the branch-name prefix —
+  // a fork PR could otherwise name its branch to forge this exemption.
+  if (String(headRef || '').startsWith(BACKMERGE_BRANCH_PREFIX) && sameRepo === true) {
+    return { ok: true, reason: ISSUE_LINK_REASON.OK_BACKMERGE_EXEMPT };
+  }
+
+  if (!hasFollowUpReference(prBody)) {
+    return { ok: false, reason: ISSUE_LINK_REASON.FAIL_NO_ISSUE_REFERENCE };
+  }
+
+  // #3211: a truncated file list cannot be trusted to prove "tests/docs
+  // only" — fail closed rather than risk approving on an unseen file.
+  if (!fileListIsComplete(changedFiles, changedFilesTotal)) {
+    return { ok: false, reason: ISSUE_LINK_REASON.FAIL_FILE_LIST_INCOMPLETE };
+  }
+
+  if (allPathsAreTestsOrDocs(changedFiles)) {
+    return { ok: true, reason: ISSUE_LINK_REASON.OK_FOLLOWUP_REFERENCE };
+  }
+
+  return { ok: false, reason: ISSUE_LINK_REASON.FAIL_REFERENCE_NEEDS_CLOSING };
+}
+
+function main() {
+  const changedFiles = parseChangedFilesEnv(process.env.CHANGED_FILES);
+  const parsedTotal = Number.parseInt(process.env.CHANGED_FILES_TOTAL, 10);
+  const changedFilesTotal = Number.isNaN(parsedTotal) ? undefined : parsedTotal;
+
+  const result = evaluateIssueLink({
+    prBody: process.env.PR_BODY || '',
+    headRef: process.env.HEAD_REF || '',
+    sameRepo: process.env.SAME_REPO === 'true',
+    changedFiles,
+    changedFilesTotal,
+  });
+
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (process.env.GITHUB_OUTPUT) {
+    const fs = require('node:fs');
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `ok=${result.ok ? 'true' : 'false'}\n`);
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `reason=${result.reason}\n`);
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `result=${JSON.stringify(result)}\n`);
+  }
+
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = {
+  ISSUE_LINK_REASON,
+  BACKMERGE_BRANCH_PREFIX,
+  EXEMPT_PATH_PREFIXES,
+  EXCLUDED_ROOT_DOCS,
+  CLOSING_KEYWORD_REGEX,
+  FOLLOWUP_REFERENCE_REGEX,
+  hasClosingKeyword,
+  hasFollowUpReference,
+  normalizePath,
+  isRootLevelDoc,
+  allPathsAreTestsOrDocs,
+  evaluateIssueLink,
+};

package/scripts/secret-scan.sh

@@ -17,10 +17,12 @@
 #              This flag does not change secret-detection logic — only which
 #              exclusions are applied.
 #
-# Exit codes:
-#   0 = clean
-#   1 = findings detected
-#   2 = usage error
+# Exit codes (ADR-3889, #3908 — registered in gsd-core/bin/shared/exit-codes.json):
+#   0                = clean
+#   1                = findings detected
+#   $EXIT_USAGE       (64) = usage error (bad argv, missing --file/--dir target)
+#   $EXIT_NO_INPUT    (66) = ran; scope established; zero files in scope (genuinely empty)
+#   $EXIT_UNAVAILABLE (69) = could not establish scope (bad ref, not a repo, unreadable dir)
 #
 # Annotation format for .secretscanignore (required for --strict compliance):
 #   # allow: <pattern>  reason="..."  owner="..."  expires="YYYY-MM-DD"  [rule-id="..."]
@@ -39,6 +41,21 @@
 #   cannot permanently hide secrets. See SECURITY.md for the audit runbook.
 set -euo pipefail
 
+# ─── Exit-code registry (ADR-3889, #3908) ────────────────────────────────────
+# Resolved relative to THIS script's location, not the caller's cwd, so this
+# works regardless of where the scanner is invoked from. Loud, non-zero
+# failure if the fragment is missing — never fall back to a guessed literal
+# integer, and never let a missing registry silently degrade to exit 0.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXIT_CODES_SH="$SCRIPT_DIR/../gsd-core/bin/shared/exit-codes.sh"
+if [[ ! -f "$EXIT_CODES_SH" ]]; then
+  echo "secret-scan: FATAL: exit-code registry not found at $EXIT_CODES_SH" >&2
+  echo "  Regenerate with: node scripts/gen-exit-code-registry.cjs --write" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+. "$EXIT_CODES_SH"
+
 # ─── Global mode flag ─────────────────────────────────────────────────────────
 STRICT_MODE=false
 
@@ -235,7 +252,31 @@ collect_files() {
   case "$mode" in
     --diff)
       local base="${1:-origin/main}"
-      git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>/dev/null \
+      # Run git separately from the filter pipe so its OWN exit status (not
+      # grep's) decides whether the diff could be established. stdout and
+      # stderr are captured SEPARATELY (never merged with `2>&1`) so that a
+      # warning git writes to stderr on an otherwise successful diff can
+      # never be mistaken for a filename in the file list. On failure the
+      # captured stderr is emitted as the diagnostic; on success it is
+      # forwarded as a warning, never folded into the file list.
+      # `|| true` on the filter below is CORRECT (not gratuitous): `grep -v`
+      # exits 1 when every line is filtered out (e.g. an all-images diff),
+      # which is a legitimate empty result, not a failure to run.
+      local raw status err_file
+      err_file=$(mktemp)
+      raw=$(git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>"$err_file")
+      status=$?
+      if (( status != 0 )); then
+        cat "$err_file" >&2
+        rm -f "$err_file"
+        exit "$EXIT_UNAVAILABLE"
+      fi
+      if [[ -s "$err_file" ]]; then
+        echo "Warning: git diff emitted stderr output:" >&2
+        cat "$err_file" >&2
+      fi
+      rm -f "$err_file"
+      printf '%s\n' "$raw" \
         | grep -vE '\.(png|jpg|jpeg|gif|ico|woff|woff2|ttf|eot|otf|zip|tar|gz|pdf)$' || true
       ;;
     --file)
@@ -243,24 +284,41 @@ collect_files() {
         echo "$1"
       else
         echo "Error: file not found: $1" >&2
-        exit 2
+        exit "$EXIT_USAGE"
       fi
       ;;
     --dir)
       local dir="$1"
       if [[ ! -d "$dir" ]]; then
         echo "Error: directory not found: $dir" >&2
-        exit 2
+        exit "$EXIT_USAGE"
+      fi
+      # Same treatment as --diff: a `find` that fails (e.g. permission
+      # denied) must not be reported as an empty directory, and stdout/stderr
+      # are captured separately so a stderr warning never enters the file list.
+      local raw status err_file
+      err_file=$(mktemp)
+      raw=$(find "$dir" -type f ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \
+        ! -name '*.png' ! -name '*.jpg' ! -name '*.gif' ! -name '*.woff*' 2>"$err_file")
+      status=$?
+      if (( status != 0 )); then
+        cat "$err_file" >&2
+        rm -f "$err_file"
+        exit "$EXIT_UNAVAILABLE"
+      fi
+      if [[ -s "$err_file" ]]; then
+        echo "Warning: find emitted stderr output:" >&2
+        cat "$err_file" >&2
       fi
-      find "$dir" -type f ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \
-        ! -name '*.png' ! -name '*.jpg' ! -name '*.gif' ! -name '*.woff*' 2>/dev/null || true
+      rm -f "$err_file"
+      printf '%s\n' "$raw"
       ;;
     --stdin)
       cat
       ;;
     *)
       echo "Usage: $0 --diff [base] | --file <path> | --dir <path> | --stdin" >&2
-      exit 2
+      exit "$EXIT_USAGE"
       ;;
   esac
 }
@@ -300,7 +358,7 @@ scan_file() {
 main() {
   if [[ $# -eq 0 ]]; then
     echo "Usage: $0 --diff [base] | --file <path> | --dir <path> [--strict]" >&2
-    exit 2
+    exit "$EXIT_USAGE"
   fi
 
   # Parse --strict flag first (may appear anywhere in argv)
@@ -316,7 +374,7 @@ main() {
 
   if [[ $# -eq 0 ]]; then
     echo "Usage: $0 --diff [base] | --file <path> | --dir <path> [--strict]" >&2
-    exit 2
+    exit "$EXIT_USAGE"
   fi
 
   load_ignorelist
@@ -328,8 +386,12 @@ main() {
   files=$(collect_files "$mode" "$@")
 
   if [[ -z "$files" ]]; then
+    # collect_files already exited (UNAVAILABLE/USAGE) for anything that
+    # could not establish scope. Reaching here with an empty result means
+    # scope WAS established and is genuinely empty (e.g. an all-images
+    # diff) — that is NO_INPUT, not a silent clean pass.
     echo "secret-scan: no files to scan"
-    exit 0
+    exit "$EXIT_NO_INPUT"
   fi
 
   local total=0