@opengsd/gsd-core 1.10.0 → 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/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

@@ -72,6 +72,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 +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: high
 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: high
 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.
 

package/skills/gsd-mempalace-capture/SKILL.md

@@ -86,7 +86,7 @@ On any error or timeout, stop and let the phase continue -- capture is best-effo
    # Mine with --wing only — no --room flag; detect_room() assigns from the folder path
    mempalace mine "$STAGE" --wing <wing>
    ```
-3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Under `augment` these are an *additive* mirror of GSD's native `.planning/graphs/`. Under `kg_backend`/`replace` the palace KG is the *authoritative* fact store — GSD still produces `.planning/graphs/` through its normal graphify, so an unreachable palace never loses a fact.
+3. **Mirror KG facts** unless `config.mempalace.mirror_kg === false` (registry default is true — an absent key means enabled): extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Under `augment` these are an *additive* mirror of GSD's native `.planning/graphs/`. Under `kg_backend`/`replace` the palace KG is the *authoritative* fact store — GSD still produces `.planning/graphs/` through its normal graphify, so an unreachable palace never loses a fact.
 4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
 
 ## Step 4 -- Report

package/skills/gsd-mempalace-recall/SKILL.md

@@ -66,7 +66,7 @@ All calls in this step are side-effect-free. On any error or timeout, stop retri
 2. **Targeted search:**
    - Interactive: `mempalace_search(query=<topic>, wing=<wing>)`.
    - Headless: `mempalace search "<topic>" --wing <wing>`.
-3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Under `augment` the palace KG *supplements* GSD's native `.planning/graphs/` — combine both, do not treat the palace as the sole source. Under `kg_backend` or `replace` the palace KG is the *primary* graph source — query it first and use `.planning/graphs/` only as a fallback when the palace is unreachable.
+3. **Knowledge-graph facts** (unless `config.mempalace.mirror_kg !== false` — registry default is true, an absent key means enabled): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Under `augment` the palace KG *supplements* GSD's native `.planning/graphs/` — combine both, do not treat the palace as the sole source. Under `kg_backend` or `replace` the palace KG is the *primary* graph source — query it first and use `.planning/graphs/` only as a fallback when the palace is unreachable.
 4. **Dedup** the returned drawers/facts; keep the top results.
 
 ## Step 4 -- Write MEMORY-RECALL.md

package/skills/gsd-new-milestone/SKILL.md

@@ -36,7 +36,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 <context>
 Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
-Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
+Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<required_reading>` blocks where subagents are used.
 </context>
 
 <process>

package/skills/gsd-next/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: gsd-next
 description: "Smart entry — detect project state and route to the right next GSD action."
-effort: low
 allowed-tools:
   - Read
   - Bash

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

@@ -2,7 +2,6 @@
 name: gsd-plan-phase
 description: "Create detailed phase plan (PLAN.md) with verification loop"
 argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--skip-ui] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--bounce] [--skip-bounce] [--chunked] [--tdd] [--mvp] [--granularity <coarse|standard|fine>] [--no-tracer] [--no-reversibility-gates]"
-effort: high
 allowed-tools:
   - Read
   - Write

package/skills/gsd-progress/SKILL.md

@@ -2,7 +2,6 @@
 name: gsd-progress
 description: "Check progress, advance workflow, or dispatch freeform intent — the unified GSD situational command"
 argument-hint: "[--forensic | --next [--auto] [--converge] | --do \\\"task description\\\"]"
-effort: low
 allowed-tools:
   - Read
   - Bash

package/skills/gsd-quick/SKILL.md

@@ -46,7 +46,7 @@ Granular flags are composable: `--discuss --research --validate` gives the same
 <context>
 $ARGUMENTS
 
-Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
+Context files are resolved inside the workflow (`init quick`) and delegated via `<required_reading>` blocks.
 </context>
 
 <process>

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

@@ -18,7 +18,8 @@ milestone sequence or remove stale entries.
 
 1. **List backlog items:**
    ```bash
-   ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
+   _BACKLOG=( .planning/phases/999* )
+   if [ -e "${_BACKLOG[0]}" ]; then ls -d "${_BACKLOG[@]}"; else echo "No backlog items found"; fi
    ```
 
 2. **Read ROADMAP.md** and extract all 999.x phase entries: