@opengsd/gsd-core 1.9.1 → 1.11.0

package/scripts/lint-vendored-deps.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-vendored-deps.cjs — freshness gate for gsd-core/bin/lib/vendor/.
+ *
+ * #3477 follow-up: gsd-core/bin/** is copied by the installer into trees
+ * that have NO node_modules, so it must carry zero external requires
+ * (local/no-external-require-in-bin, eslint-rules/no-external-require-in-bin.cjs).
+ * `re2js` (src/pattern.cts's RE2 engine) is vendored verbatim under
+ * gsd-core/bin/lib/vendor/ instead — see gsd-core/bin/lib/vendor/README.md.
+ *
+ * A vendored artifact that silently drifts from its upstream package is
+ * just as dangerous as never vendoring it in the first place (a stale
+ * copy ships a different engine than the one actually reviewed/audited).
+ * This guard fails CI when:
+ *   1. gsd-core/bin/lib/vendor/re2js.cjs no longer matches
+ *      node_modules/re2js/build/index.cjs byte-for-byte.
+ *   2. gsd-core/bin/lib/vendor/re2js.d.cts no longer matches
+ *      node_modules/re2js/build/index.d.cts byte-for-byte.
+ *   3. src/vendor/re2js.d.cts (the source-side twin tsc needs to resolve
+ *      types for src/pattern.cts's relative './vendor/re2js.cjs' import —
+ *      module resolution for a .cts source is relative to src/, not the
+ *      output dir) no longer matches gsd-core/bin/lib/vendor/re2js.d.cts.
+ *   4. The `re2js` version pinned in package.json `devDependencies` no
+ *      longer matches the version actually installed at
+ *      node_modules/re2js/package.json (read there, per the dispatch
+ *      brief, rather than duplicating a second pin).
+ *
+ * Usage: node scripts/lint-vendored-deps.cjs
+ * Exit 0 when every vendored copy is fresh; 1 otherwise.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+
+const REFRESH_COMMAND =
+  'cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs && '
+  + 'cp node_modules/re2js/build/index.d.cts gsd-core/bin/lib/vendor/re2js.d.cts && '
+  + 'cp node_modules/re2js/build/index.d.cts src/vendor/re2js.d.cts';
+
+/**
+ * Compare two files byte-for-byte. Returns null when equal, or a short
+ * mismatch description (missing file / byte-length delta) otherwise.
+ * @param {string} relA
+ * @param {string} relB
+ * @returns {string | null}
+ */
+function compareFiles(relA, relB) {
+  const absA = path.join(ROOT, relA);
+  const absB = path.join(ROOT, relB);
+  if (!fs.existsSync(absA)) return `${relA} does not exist`;
+  if (!fs.existsSync(absB)) return `${relB} does not exist`;
+  const a = fs.readFileSync(absA);
+  const b = fs.readFileSync(absB);
+  if (a.equals(b)) return null;
+  return `${relA} (${a.length} bytes) != ${relB} (${b.length} bytes)`;
+}
+
+/**
+ * Strip a leading semver range operator (^, ~, >=, >, <=, <, =) from a
+ * package.json dependency spec, leaving a bare version.
+ * @param {string} spec
+ * @returns {string}
+ */
+function stripRangeOperator(spec) {
+  return String(spec || '').trim().replace(/^[\^~]|^>=|^<=|^>|^<|^=/, '').trim();
+}
+
+function main() {
+  const findings = [];
+
+  const cjsDrift = compareFiles('gsd-core/bin/lib/vendor/re2js.cjs', 'node_modules/re2js/build/index.cjs');
+  if (cjsDrift) findings.push(cjsDrift);
+
+  const dctsDrift = compareFiles('gsd-core/bin/lib/vendor/re2js.d.cts', 'node_modules/re2js/build/index.d.cts');
+  if (dctsDrift) findings.push(dctsDrift);
+
+  const srcTwinDrift = compareFiles('src/vendor/re2js.d.cts', 'gsd-core/bin/lib/vendor/re2js.d.cts');
+  if (srcTwinDrift) findings.push(srcTwinDrift);
+
+  const pkgPath = path.join(ROOT, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const pinnedSpec = pkg.devDependencies && pkg.devDependencies.re2js;
+  if (!pinnedSpec) {
+    findings.push('package.json devDependencies.re2js is missing');
+  } else {
+    const installedPkgPath = path.join(ROOT, 'node_modules', 're2js', 'package.json');
+    if (!fs.existsSync(installedPkgPath)) {
+      findings.push('node_modules/re2js/package.json does not exist (run npm install)');
+    } else {
+      const installed = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8'));
+      const pinned = stripRangeOperator(pinnedSpec);
+      if (pinned !== installed.version) {
+        findings.push(
+          `package.json devDependencies.re2js ("${pinnedSpec}" -> "${pinned}") != `
+            + `node_modules/re2js/package.json version ("${installed.version}")`,
+        );
+      }
+    }
+  }
+
+  if (findings.length > 0) {
+    const detail = findings.map((f) => `  ${f}`).join('\n');
+    throw new ExitError(
+      1,
+      'lint-vendored-deps: gsd-core/bin/lib/vendor/re2js.* has drifted from its\n'
+        + 'upstream package (or its version pin). Refresh with:\n'
+        + `  ${REFRESH_COMMAND}\n`
+        + 'Findings:\n'
+        + detail,
+    );
+  }
+
+  process.stdout.write('ok lint-vendored-deps: gsd-core/bin/lib/vendor/re2js.* matches node_modules/re2js and its pinned version\n');
+  return 0;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { compareFiles, stripRangeOperator };

package/scripts/mutation-matrix.cjs

@@ -130,6 +130,19 @@ const COVERED = {
     // minScore raised to TARGET (80) — module now meets ADR-456 goal.
     minScore: 80,
   },
+  // context-composer: extracted from prompt-budget by #2929. Needs its own entry because
+  // mutation coverage does not migrate with relocated code — scoring only prompt-budget.cjs
+  // would leave the extracted ladder unmeasured.
+  'context-composer': {
+    cjs: 'gsd-core/bin/lib/context-composer.cjs',
+    tests: [
+      'tests/prompt-budget-parity.test.cjs',
+      'tests/prompt-budget.unit.test.cjs',
+      'tests/context-composer.test.cjs',
+      'tests/context-composer.property.test.cjs',
+    ],
+    minScore: 66,
+  },
   'prompt-budget': {
     cjs: 'gsd-core/bin/lib/prompt-budget.cjs',
     tests: [

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

@@ -14,6 +14,19 @@ set -euo pipefail
 
 # ─── Patterns ────────────────────────────────────────────────────────────────
 # Each pattern is a POSIX extended regex. Keep alphabetized by category.
+#
+# Left-boundary prefix `(^|[^[:alnum:]])`: several trigger words are also
+# suffixes of ordinary English words or camelCase identifiers (fact/impact/
+# contract/artifact/interact all end in "act"; retrieval/medieval end in
+# "eval"; blueprint/reprint/fingerprint end in "print"; describeFunction/
+# wrapFunction end in "Function"; Jordan/Sudan end in "dan"), so an
+# unanchored keyword matches as a false-positive substring. `\b` is a GNU
+# grep extension and this script must also run under BSD/macOS grep, so the
+# boundary is spelled out as `(^|[^[:alnum:]])` instead. This never narrows
+# real detections: a genuine attack phrase is always preceded by start-of-
+# line, whitespace, or punctuation, never by another alnum character glued
+# directly onto the keyword. Only patterns whose leading keyword is provably
+# not a real-word suffix are left unanchored (#3175 audit).
 
 PATTERNS=(
   # Instruction override
@@ -27,7 +40,7 @@ PATTERNS=(
   'you[[:space:]]+are[[:space:]]+now[[:space:]]+(a|an|my)[[:space:]]'
   'from[[:space:]]+now[[:space:]]+on[[:space:]]+(you|pretend|act|behave)'
   'pretend[[:space:]]+(you[[:space:]]+are|to[[:space:]]+be)[[:space:]]'
-  'act[[:space:]]+as[[:space:]]+(a|an|if|my)[[:space:]]'
+  '(^|[^[:alnum:]])act[[:space:]]+as[[:space:]]+(a|an|if|my)[[:space:]]'
   'roleplay[[:space:]]+as[[:space:]]'
   'assume[[:space:]]+the[[:space:]]+role[[:space:]]+of[[:space:]]'
 
@@ -35,7 +48,7 @@ PATTERNS=(
   'output[[:space:]]+(your|the)[[:space:]]+(system[[:space:]]+)?(prompt|instructions)'
   'reveal[[:space:]]+(your|the)[[:space:]]+(system[[:space:]]+)?(prompt|instructions)'
   'show[[:space:]]+me[[:space:]]+(your|the)[[:space:]]+(system[[:space:]]+)?(prompt|instructions)'
-  'print[[:space:]]+(your|the)[[:space:]]+(system[[:space:]]+)?(prompt|instructions)'
+  '(^|[^[:alnum:]])print[[:space:]]+(your|the)[[:space:]]+(system[[:space:]]+)?(prompt|instructions)'
   'what[[:space:]]+(is|are)[[:space:]]+(your|the)[[:space:]]+(system[[:space:]]+)?(prompt|instructions)'
   'repeat[[:space:]]+(your|the|all)[[:space:]]+(system[[:space:]]+)?(prompt|instructions|rules)'
 
@@ -51,13 +64,30 @@ PATTERNS=(
   '<</SYS>>'
 
   # Tool call injection / code execution in markdown
-  'eval[[:space:]]*\([[:space:]]*["\x27]'
-  'exec[[:space:]]*\([[:space:]]*["\x27]'
-  'Function[[:space:]]*\([[:space:]]*["\x27].*return'
+  #
+  # The quote-or-apostrophe class below is spelled ["'"'"'"] (a literal `'`
+  # via bash's close-quote/escape/reopen idiom), not `["\x27]` — `\x27` is a
+  # GNU-grep-only hex escape; BSD/macOS grep treats it as four literal
+  # characters (", \, x, 2, 7) and never matches an actual apostrophe, so
+  # `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'
 
   # Jailbreak / DAN patterns
   'do[[:space:]]+anything[[:space:]]+now'
-  'DAN[[:space:]]+mode'
+  '(^|[^[:alnum:]])DAN[[:space:]]+mode'
   'developer[[:space:]]+mode[[:space:]]+(enabled|output|activated)'
   'jailbreak'
   'bypass[[:space:]]+(safety|content|security)[[:space:]]+(filter|check|rule|guard)'
@@ -108,6 +138,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() {

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/state-write-path-drift-baseline.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "ADR-3408 Decision 5 write-seam ratchet baseline (issue #3468, Phase 1; Phase 2 / #3469 lands the single write seam and Amendment 2). Every entry here is a `writeStateMd(`/`syncStateFrontmatter(`/`applyPostSyncPreservation(` bypass this guard found by a whole-repo scan (Decision 4(a)) — it is ACKNOWLEDGED, not endorsed: acknowledgment is in writing (this file), with the issue owning its removal recorded in the entry's \"owner\" field. This baseline is SHRINK-ONLY — an entry that stops firing goes STALE and fails the plain run until `--baseline` is re-run to drop it (ADR-3180 Decision 4(e)'s \"the baseline may only shrink\", adopted verbatim by ADR-3408). Phase 2 (#3469) removed the `cmdPhaseComplete` (`src/phase.cts`) and `cmdMilestoneComplete` (`src/milestone.cts`) entries by routing both through the single write-seam composition (`syncAndPreserveStateMd`, `src/state.cts`). ADR-3408 Amendment 2: \"0 bypasses\" was never this baseline's target — TWO entries are SANCTIONED PERMANENT, not debt, and Phase 4 (#3471) does NOT drive this file to empty: `cmdStateSync` (`src/state.cts`) exists precisely to let the body win (#905 — `state sync` re-derives frontmatter FROM the body), so routing it through preservation would invert the command rather than fix a bug; `REGENERATE_STATE` (`src/health-diagnostic.cts`) is `/gsd-health --repair`'s factory reset, which rebuilds STATE.md from scratch, so preservation would restore exactly the values it was invoked to discard. Neither entry may be \"consolidated\" away — a guard reporting them is reporting correctly, and a change that removes one is a regression, not progress.",
+  "entries": [
+    {
+      "file": "src/health-diagnostic.cts",
+      "source": "writeStateMd(statePath, stateContent, cwd);",
+      "symbol": "writeStateMd",
+      "count": 1,
+      "owner": "sanctioned-permanent"
+    },
+    {
+      "file": "src/state.cts",
+      "source": "writeStateMd(statePath, modified, cwd);",
+      "symbol": "writeStateMd",
+      "count": 1,
+      "owner": "sanctioned-permanent"
+    }
+  ]
+}

package/scripts/sync-runtime-launcher.cjs

@@ -19,6 +19,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { escapeRegex: escapeRegExp } = require('../gsd-core/bin/lib/pattern.cjs');
+
 const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
 const AGENTS_DIR = path.join(__dirname, '..', 'agents');
 const SNIPPET_FILE = path.join(WORKFLOWS_DIR, '_runtime-launcher.snippet.sh');
@@ -373,10 +375,6 @@ function transformFile(content, preamble) {
   return outputLines.join('\n');
 }
 
-function escapeRegExp(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * A file "delegates to the shared resolver" when it pulls the canonical gsd_run
  * preamble in from gsd-core/references/gsd-run-resolver.md via an @-include

package/skills/gsd-autonomous/SKILL.md

@@ -2,7 +2,6 @@
 name: gsd-autonomous
 description: "Run all remaining phases autonomously — discuss→plan→execute per phase"
 argument-hint: "[--from N] [--to N] [--only N] [--interactive] [--converge]"
-effort: max
 allowed-tools:
   - Read
   - Write

package/skills/gsd-code-review/SKILL.md

@@ -41,7 +41,7 @@ Optional flags parsed from $ARGUMENTS:
 - `--depth=VALUE` — Depth override (quick|standard|deep). If provided, overrides workflow.code_review_depth config.
 - `--files=file1,file2,...` — Explicit file list override. Has highest precedence for file scoping per D-08. When provided, workflow skips SUMMARY.md extraction and git diff fallback entirely.
 
-Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<files_to_read>` blocks.
+Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<required_reading>` blocks.
 </context>
 
 <process>

package/skills/gsd-execute-phase/SKILL.md

@@ -2,7 +2,6 @@
 name: gsd-execute-phase
 description: "Execute all plans in a phase with wave-based parallelization"
 argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
-effort: max
 allowed-tools:
   - Read
   - Write
@@ -56,7 +55,7 @@ Phase: $ARGUMENTS
 - If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering
 - Do not infer that a flag is active just because it is documented in this prompt
 
-Context files are resolved inside the workflow via `gsd-tools query init.execute-phase` and per-subagent `<files_to_read>` blocks.
+Context files are resolved inside the workflow via `gsd-tools query init.execute-phase` and per-subagent `<required_reading>` blocks.
 </context>
 
 <process>

package/skills/gsd-map-codebase/SKILL.md

@@ -34,7 +34,7 @@ Output: .planning/codebase/ folder with 7 structured documents about the codebas
 Arguments: $ARGUMENTS
 
 Parse the first token of $ARGUMENTS:
-- If it is `--fast`: strip the flag, run the scan workflow (passing remaining args including optional --focus).
+- If it is `--fast`: strip the flag, then read and execute `~/.claude/gsd-core/workflows/scan.md` (passing remaining args including optional --focus). Load it on demand here — it is deliberately not in `<execution_context>`, so the common full-map path does not pay for it.
 - If it is `--query`: strip the flag, run the intel workflow (passing remaining args as the subcommand).
 - Otherwise: pass all of $ARGUMENTS as focus area to the map-codebase workflow.