chore(#604): rename get-shit-done/ runtime directory to gsd-core/ (#615)

* chore(#604): rename get-shit-done/ runtime directory to gsd-core/ Renames the installed runtime directory `get-shit-done/` to `gsd-core/` so the on-disk name matches the package (`@opengsd/gsd-core`), repo, and binary (`gsd-tools`). The npm package name and binary are unchanged; npx/npm consumers are unaffected. Mechanical (bulk, ~90% of the diff): - `git mv get-shit-done gsd-core` - Swept path/identifier references across the repo via `perl -pe 's/get-shit-done(?!-\w)/gsd-core/g'`. The negative lookahead preserves the five legitimate slug variants that are NOT the directory: get-shit-done-{OLD,cc,classic,cli,redux} (old package/repo names). - Build/manifest wiring: package.json (bin, files, coverage globs), tsconfig.build.json (outDir), ~86 .gitignore build-output entries, stryker.config.mjs, scan-ignore files, install.js path strings. - Frozen (not rewritten): CHANGELOG.md history; translated docs (README.<locale>.md and docs/{ja-JP,ko-KR,pt-BR,zh-CN}/). New logic (review here): - src/installer-migrations/003-rename-get-shit-done-to-gsd-core.cts: a proper ADR-0008 installer migration. On upgrade it walks the legacy `~/.claude/get-shit-done/` tree, classifies each file via the prior install manifest, and emits remove-managed / backup-and-remove for managed files while PRESERVING unknown user-added files. Symlink-safe (skips a symlinked root and symlinked entries; bounds-checks every path under configDir). The framework rolls back on install failure. Emptied dirs may remain (framework has no recursive dir-removal primitive) — documented. - scripts/lint-legacy-dir-name.cjs: CI regression guard forbidding the bare `get-shit-done` directory token (split token to avoid self-match; case- insensitive; `(?!-\w)` lookahead allows the slug variants; allowlists CHANGELOG, translated docs, and `gsd-allow-legacy-name` marker lines). Wired into the lint-tests CI job. - Restored scripts/lint-package-identity-drift.cjs detection regexes (the mechanical sweep had wrongly rewritten the old-name patterns it exists to detect) and marked them as intentional legacy references. - TDD tests for the migration and the guard; do.md slash-command guard regex tightened so a `/gsd-core/bin` path segment is not mistaken for a command; changeset + docs/installer-migrations.md row added. Breaking: the installed runtime path moves `~/.claude/get-shit-done/` -> `~/.claude/gsd-core/`. Migration 003 removes the stale legacy dir's managed files (preserving user files) on upgrade. Users with custom hooks/configs hardcoding the old path must update them. Closes #604 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): unsweep pending changesets + allowlist injection-example docs CI fixes for the rename PR: - Do not sweep pending .changeset/*.md (ephemeral release-note fragments, like CHANGELOG); reverted those body edits so 5 pre-existing malformed fragments (missing type/pr) no longer enter the PR diff and trip docs-lint. Allowlisted .changeset/ in the legacy-name guard accordingly. - Allowlisted TEST-EXAMPLES.md and docs/explanation/security-model.md in prompt-injection-scan.sh: they contain intentional injection examples / security-model prose; the path-reference rewrites are kept. CodeQL alerts on this PR are pre-existing (alert lines unchanged by this PR; none in the new migration/guard) and are out of scope for the rename. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): resolve CodeQL alerts surfaced on this PR The rename diff touched files carrying pre-existing CodeQL findings; per the no-pre-existing-dismissal rule, fixing every surfaced alert rather than waving them off. All behavior-preserving: - scripts/ci-test-scope.cjs: build the config-path match from string .includes() instead of a RegExp over an arg-derived value (js/regex-injection). - src/profile-output.cts: escape backslashes before pipe-escaping desc/safeName so the table-cell escape is complete (js/incomplete-sanitization). - tests/{bug-2643,bug-2808,docs-parity-live-registry}: two-pass HTML-comment strip so a bare/unclosed `/g,'')` can let ` replace), so loop fixes do not satisfy it. Made these paths regex-free: - ci-test-scope.cjs splitFiles: char-by-char separator tokenizer (no /[,\\s]+/). - 3 test files: indexOf/slice HTML-comment stripper (no .replace(/<!--/)). Behavior preserved; ci-test-scope + the 3 suites pass; guard clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): unblock security base64 scan on the large rename diff The security job hit its 10m timeout: base64-scan.sh choked on the binary test fixture tests/feat-3594-parser-property-style.test.cjs (embedded NUL/ non-UTF8 bytes -> thousands of bogus blobs + "ignored null byte" warnings), and the ~800-file rename diff is slow to scan regardless. - scripts/base64-scan.sh: skip binary-by-content files (grep -Iq .) — they can't carry base64-obfuscated *text* and feeding NUL bytes through the per-line scanner is pathologically slow. collect_files already filtered binary *extensions*; this catches binary *content* in text extensions. - .github/workflows/security-scan.yml: raise the security job timeout 10m->30m to accommodate very large diffs (the scan itself is unchanged). Verified locally: scan skips the fixture, 0 "ignored null byte" warnings, 0 findings, exit 0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): sweep get-shit-done refs introduced by merging next The branch was updated with next (#614/#384/#618 etc.), which reference the get-shit-done/ dir (still named that on next). Swept the stale references in the merged files to gsd-core so the rename stays consistent and lint:legacy-name passes: - commands/gsd/discuss-phase.md (runtime-launcher shim paths) - src/core.cts (getAgentsDir layout comments) - tests/bug-384-agents-runtime-aware.test.cjs (require path to runtime lib) Verified: guard 0 violations; build green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): exclude gsd-core/ path segments from bug-3683 command cross-ref invariant The #614 runtime-launcher shim added to discuss-phase.md references `${_GSD_RUNTIME_ROOT}/gsd-core/bin/...`. bug-3683's REF_PATTERN excluded path-y refs only via lookbehind, but `}` precedes `/gsd-core/` in the shim, so it mis-read the directory path as a dangling `/gsd-core` command ref (same class as the #604 bug-2954 fix). Added a trailing `(?![\w-]*\/)` so `/gsd-<x>/...` path segments are not treated as slash-command references. Verified locally on BOTH platforms before pushing: - mac (node 26) full suite: 0 failures - gsd-test-runner (linux, node22 image) full suite: 0 failures - bug-3683 + bug-2954 pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): lazily resolve findProjectRoot in gsd-tools (harden flaky CI) CI intermittently failed state.test's gsd-tools subprocess with "findProjectRoot is not a function" (flip-flopping across legs; not reproducible on mac full suite, gsd-test linux full suite, test:unit, or state.test x8). findProjectRoot is a re-export from core.cjs (sourced from project-root.cjs); binding it via destructure at module-load can be undefined under a load-ordering edge. Resolve it lazily at call time via a small wrapper so the lookup happens after core.cjs is fully initialized. Verified green on BOTH platforms before pushing: - mac (node 26) full suite: 0 failures - gsd-test-runner (linux, node22) full suite: 0 failures - state.test.cjs: 106/106; gsd-tools loads cleanly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): allowlist verification-patterns.md placeholder examples in secret scan The rename git-mv'd references/verification-patterns.md into gsd-core/, pulling it into the secret-scan diff. It documents stub/placeholder RED-FLAG env-var examples (illustrative Stripe test-key / database-URL / API-key placeholders) — not real credentials. Added it to .secretscanignore with the strict annotation, mirroring the existing gsd-core/workflows/plan-phase.md exception. Verified locally: secret-scan-lint --strict OK; secret-scan --diff origin/next exits 0 with 0 findings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-02 18:35:29 -04:00
parent b177c1704f
commit 463cffd894
845 changed files with 3316 additions and 2373 deletions
--- a/gsd-core/bin/check-latest-version.cjs
+++ b/gsd-core/bin/check-latest-version.cjs
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Deterministic latest-version check for /gsd-update (#2992).
+ *
+ * The /gsd-update workflow's check_latest_version step was previously
+ * prescribed in LLM-driven prose ("run `npm view gsd-core
+ * version`"). The executing model could shortcut the prescription and
+ * invent npm queries against wrong-shaped names (`@gsd-core/cli`,
+ * `get-shit-done-cli`, `gsd`), all of which 404 or — worse — return an
+ * unrelated typosquat package.
+ *
+ * This script makes the package name a CONSTANT in code, not a free
+ * choice at execution time. The workflow calls it via `npm run
+ * check-latest-version -- --json` and parses the structured response.
+ *
+ * Tests assert on the typed CHECK_REASON enum and the structured result
+ * record, never on console prose. See CONTRIBUTING.md "Prohibited: Raw
+ * Text Matching on Test Outputs".
+ */
+
+const { execNpm } = require('./lib/shell-command-projection.cjs');
+
+// Sourced from the single Package Identity seam (#498), not re-typed. The seam
+// bakes the value from package.json at build time, so it is a code constant —
+// still NOT a runtime choice for the caller (#2992) — and a rename propagates
+// from one place (#378). The drift-guard lint forbids re-introducing a literal.
+const { packageName: PACKAGE_NAME } = require('./lib/package-identity.cjs');
+
+const CHECK_REASON = Object.freeze({
+  OK: 'ok',
+  FAIL_NPM_FAILED: 'fail_npm_failed',
+  FAIL_INVALID_OUTPUT: 'fail_invalid_output',
+});
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+/**
+ * Pure-ish: takes an injected spawn function so tests don't actually run npm.
+ * In production, defaults to execNpm() from the shell-projection seam.
+ */
+function checkLatestVersion(opts = {}) {
+  // Default path routes through the shell-projection seam (execNpm owns the
+  // Windows shell-flag policy and timeout default). The injection point
+  // remains spawnSync-shaped for test compatibility — the adapter below
+  // translates { exitCode } → { status } so the consumer logic is unchanged.
+  // Bounded at 15s so a hung registry doesn't block /gsd-update (#2993 CR).
+  const defaultSpawn = () => {
+    const r = execNpm(['view', PACKAGE_NAME, 'version'], { timeout: 15_000 });
+    return {
+      status: r.exitCode,
+      stdout: r.stdout,
+      stderr: r.stderr,
+      signal: r.signal,
+      error: r.error,
+    };
+  };
+  const spawn = opts.spawn || defaultSpawn;
+
+  const r = spawn();
+  if (!r || r.status !== 0) {
+    // Distinguish timeout (status null, signal set, stderr empty) from a
+    // genuine npm failure. Without this, both surfaced as "npm exited
+    // non-zero" and the operator couldn't tell which (#2993 CR).
+    let detail;
+    if (r && r.signal) {
+      detail = `npm timed out (signal: ${r.signal})`;
+    } else if (r && r.stderr) {
+      detail = r.stderr.trim();
+    } else {
+      detail = 'npm exited non-zero';
+    }
+    return {
+      ok: false,
+      reason: CHECK_REASON.FAIL_NPM_FAILED,
+      detail,
+    };
+  }
+  const version = (r.stdout || '').trim();
+  if (!SEMVER_RE.test(version)) {
+    return {
+      ok: false,
+      reason: CHECK_REASON.FAIL_INVALID_OUTPUT,
+      detail: version || '(empty)',
+    };
+  }
+  return { ok: true, version, reason: CHECK_REASON.OK };
+}
+
+function main() {
+  const json = process.argv.includes('--json');
+  const r = checkLatestVersion();
+  if (json) {
+    process.stdout.write(JSON.stringify(r) + '\n');
+  } else if (r.ok) {
+    process.stdout.write(r.version + '\n');
+  } else {
+    process.stderr.write(`check-latest-version: ${r.reason}: ${r.detail}\n`);
+  }
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkLatestVersion, CHECK_REASON, PACKAGE_NAME };
--- a/gsd-core/bin/gsd-tools.cjs
+++ b/gsd-core/bin/gsd-tools.cjs
--- a/gsd-core/bin/lib/legacy-cleanup.cjs
+++ b/gsd-core/bin/lib/legacy-cleanup.cjs
@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * legacy-cleanup.cjs — detect and remove leftover artifacts from the old package.
+ *
+ * Provides a pure-ish scan phase (planLegacyCleanup) and a thin IO applier
+ * (applyLegacyCleanup) that together root out stale files from the old
+ * package across every GSD-managed runtime config directory.
+ *
+ * Issue: #607
+ *
+ * House style: CommonJS, 'use strict', pure functions + thin IO appliers.
+ * Seams (opts.fs, opts.logger) allow full unit-test coverage without touching
+ * the real filesystem except in the apply phase.
+ */
+
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * Substring that identifies a file as belonging to the old package.
+ * Assembled from parts so this source file itself never contains the literal
+ * as a plain substring (avoids self-flagging if the content scan were ever
+ * widened back to include this subtree).
+ */
+const OLD_PACKAGE_SIGNAL = 'gsd-core' + '-cc';
+
+/**
+ * Subtrees within a configDir that GSD actively scans for old-package content.
+ * Deliberately excludes 'gsd-core' — the current package's own infra and
+ * docs live there (CHANGELOG.md, this file, etc.) and are overwritten by
+ * install anyway. Poisoning hooks from the old package live in 'hooks/', which
+ * IS scanned.
+ */
+const GSD_MANAGED_SUBTREES = ['hooks', 'commands'];
+
+/**
+ * Extensions eligible for the content-reference scan.
+ *
+ * WHY: The current @opengsd/gsd-core package ships ZERO references to the old
+ * package name in any code file (.js/.cjs/.mjs/.sh). Therefore a code file
+ * that still contains that string is genuinely a leftover from the old package
+ * and is safe to flag.
+ *
+ * Markdown, JSON, TOML, YAML, and other doc/config files, however,
+ * legitimately cite the old name in historical or reference context
+ * (e.g. CHANGELOG.md, workflow .md files). Scanning them caused the
+ * installer to delete the freshly-installed gsd-core/CHANGELOG.md,
+ * breaking installs. Fix: restrict the content scan to code extensions only.
+ */
+const CODE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.sh']);
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Return true if any segment of the absolute file path is `dev-preferences`
+ * or the file is named `dev-preferences.md`. These are always user artifacts.
+ *
+ * @param {string} absPath
+ * @returns {boolean}
+ */
+function isDevPreferencesPath(absPath) {
+  const parts = absPath.split(path.sep);
+  return parts.some(
+    (seg) => seg === 'dev-preferences' || seg === 'dev-preferences.md'
+  );
+}
+
+/**
+ * Recursively collect all file paths under `dir` (bounded; skips
+ * unreadable entries silently).
+ *
+ * @param {string} dir
+ * @param {object} fsMod - injectable fs module
+ * @returns {string[]} absolute file paths
+ */
+function collectFilesUnder(dir, fsMod) {
+  const results = [];
+  let entries;
+  try {
+    entries = fsMod.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFilesUnder(full, fsMod));
+    } else if (entry.isFile()) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Return true if the file at `absPath` contains the old-package substring.
+ * Skips unreadable files (returns false on any error).
+ *
+ * @param {string} absPath
+ * @param {object} fsMod
+ * @returns {boolean}
+ */
+function fileContainsOldPackageSignal(absPath, fsMod) {
+  try {
+    const content = fsMod.readFileSync(absPath, 'utf8');
+    return content.includes(OLD_PACKAGE_SIGNAL);
+  } catch {
+    return false;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Scan `configDirs` for leftover old-package artifacts and the legacy
+ * shared cache, returning an ordered array of removal candidates.
+ *
+ * Possible reasons in returned entries:
+ *   - 'content-references-old-package': a code file whose content contains
+ *     the old package name signal (hooks/ and commands/ subtrees only).
+ *   - 'legacy-shared-cache': the old package's shared update-check cache file.
+ *
+ * @param {string[]} configDirs - absolute paths to runtime config dirs to scan
+ * @param {object}  [opts]
+ * @param {string}  [opts.homeDir]  - home directory (default: os.homedir())
+ * @param {object}  [opts.fs]       - injectable fs module (default: require('node:fs'))
+ * @returns {{ path: string, reason: string }[]}
+ */
+function planLegacyCleanup(configDirs, opts = {}) {
+  const homeDir  = opts.homeDir || os.homedir();
+  const fsMod    = opts.fs || fs;
+
+  /** @type {Map<string, string>} path → reason (de-dup by path) */
+  const candidates = new Map();
+
+  const addCandidate = (absPath, reason) => {
+    if (!candidates.has(absPath)) {
+      candidates.set(absPath, reason);
+    }
+  };
+
+  for (const configDir of configDirs) {
+    for (const subtree of GSD_MANAGED_SUBTREES) {
+      const subtreeDir = path.join(configDir, subtree);
+
+      // Collect all files under this subtree (skip if absent)
+      const files = collectFilesUnder(subtreeDir, fsMod);
+
+      for (const absPath of files) {
+        // Never flag user-authored dev-preferences artifacts
+        if (isDevPreferencesPath(absPath)) continue;
+
+        // Content signal: code files referencing the old package name.
+        // Only scan files with code extensions — docs/config files (.md, .json,
+        // .yml, etc.) legitimately cite the old name in historical context and
+        // must never be deleted (see CODE_EXTENSIONS declaration above).
+        const ext = path.extname(absPath).toLowerCase();
+        if (CODE_EXTENSIONS.has(ext) && fileContainsOldPackageSignal(absPath, fsMod)) {
+          addCandidate(absPath, 'content-references-old-package');
+        }
+      }
+    }
+  }
+
+  // Legacy shared cache (fixed name from the old package)
+  const legacyCachePath = path.join(homeDir, '.cache', 'gsd', 'gsd-update-check.json');
+  try {
+    const stat = fsMod.statSync(legacyCachePath);
+    if (stat.isFile()) {
+      addCandidate(legacyCachePath, 'legacy-shared-cache');
+    }
+  } catch {
+    // absent — skip
+  }
+
+  // Sort deterministically by path
+  const sorted = [...candidates.entries()]
+    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+    .map(([p, reason]) => ({ path: p, reason }));
+
+  return sorted;
+}
+
+/**
+ * Execute the plan returned by `planLegacyCleanup`.
+ *
+ * @param {{ path: string, reason: string }[]} plan
+ * @param {object}  [opts]
+ * @param {boolean} [opts.dryRun=false] - when true, log but do not remove
+ * @param {object}  [opts.fs]           - injectable fs module
+ * @param {object}  [opts.logger]       - injectable logger (default: console)
+ * @returns {{ removed: string[], skipped: string[], errors: Array<{path:string,error:string}>, dryRun: boolean }}
+ */
+function applyLegacyCleanup(plan, opts = {}) {
+  const dryRun  = opts.dryRun === true;
+  const fsMod   = opts.fs || fs;
+  const logger  = opts.logger || console;
+
+  if (dryRun) {
+    for (const item of plan) {
+      logger.log('[dry-run] would remove: ' + item.path + '  (' + item.reason + ')');
+    }
+    return {
+      removed: [],
+      skipped: plan.map((item) => item.path),
+      errors: [],
+      dryRun: true,
+    };
+  }
+
+  const removed = [];
+  const errors  = [];
+
+  for (const item of plan) {
+    let lastErr;
+    const maxAttempts = process.platform === 'win32' ? 3 : 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        if (attempt > 0) {
+          // Synchronous 100ms delay before retry (win32 EBUSY/EPERM from Defender)
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        }
+        fsMod.rmSync(item.path, { force: true });
+        lastErr = undefined;
+        break;
+      } catch (err) {
+        lastErr = err;
+        if (process.platform !== 'win32' ||
+            (err.code !== 'EBUSY' && err.code !== 'EPERM')) {
+          break; // non-retryable error; stop immediately
+        }
+      }
+    }
+    if (lastErr) {
+      errors.push({ path: item.path, error: lastErr.message });
+    } else {
+      removed.push(item.path);
+    }
+  }
+
+  return { removed, skipped: [], errors, dryRun: false };
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  planLegacyCleanup,
+  applyLegacyCleanup,
+};
--- a/gsd-core/bin/lib/package-identity.cjs
+++ b/gsd-core/bin/lib/package-identity.cjs
@@ -0,0 +1,35 @@
+// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.
+// Single source for GSD package coordinates (issue #498). Regenerate with:
+//   node scripts/generate-package-identity.cjs
+'use strict';
+
+const packageName = "@opengsd/gsd-core";
+const binName = "gsd-core";
+const repoSlug = "open-gsd/gsd-core";
+const repoUrl = "https://github.com/open-gsd/gsd-core";
+const changelogRawUrl = "https://raw.githubusercontent.com/open-gsd/gsd-core/main/CHANGELOG.md";
+const cacheSlug = "opengsd-gsd-core";
+const updateCacheFileName = "gsd-update-check-opengsd-gsd-core.json";
+
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+function manualInstallCommand(opts = {}) {
+  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });
+}
+
+module.exports = Object.freeze({
+  packageName,
+  // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it
+  // survives the installed tree's synthetic package.json (fixes the #378 undefined).
+  PACKAGE_NAME: packageName,
+  binName,
+  repoSlug,
+  repoUrl,
+  changelogRawUrl,
+  cacheSlug,
+  updateCacheFileName,
+  manualInstallCommand,
+});
--- a/gsd-core/bin/shared/config-defaults.manifest.json
+++ b/gsd-core/bin/shared/config-defaults.manifest.json
@@ -0,0 +1,98 @@
+{
+  "_comment": "Canonical CONFIG_DEFAULTS for the Configuration Module. Nested shape is canonical. CJS flat projection (branching_strategy, sub_repos, etc.) is handled by consumers at the boundary. Security keys (security_enforcement, security_asvs_level, security_block_on) and post_planning_gaps live in workflow.* as their canonical location. resolve_model_ids, context_window, phase_naming are CJS-originated top-level keys included here. brave_search, firecrawl, exa_search default to false in the manifest; at runtime buildNewProjectConfig detects API keys. The plan_checker (CJS flat) → workflow.plan_check (canonical nested) divergence is resolved: canonical name is workflow.plan_check. _auto_chain_active is a runtime-state field included for completeness.",
+  "model_profile": "balanced",
+  "commit_docs": true,
+  "parallelization": true,
+  "search_gitignored": false,
+  "brave_search": false,
+  "firecrawl": false,
+  "exa_search": false,
+  "resolve_model_ids": false,
+  "context_window": 200000,
+  "phase_naming": "sequential",
+  "project_code": null,
+  "phase_id_convention": null,
+  "mode": "interactive",
+  "claude_md_path": "./CLAUDE.md",
+  "git": {
+    "branching_strategy": "none",
+    "create_tag": true,
+    "base_branch": null,
+    "phase_branch_template": "gsd/phase-{phase}-{slug}",
+    "milestone_branch_template": "gsd/{milestone}-{slug}",
+    "quick_branch_template": null
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "ai_integration_phase": true,
+    "tdd_mode": false,
+    "human_verify_mode": "end-of-phase",
+    "auto_advance": false,
+    "_auto_chain_active": false,
+    "node_repair": true,
+    "node_repair_budget": 2,
+    "ui_phase": true,
+    "ui_safety_gate": true,
+    "text_mode": false,
+    "research_before_questions": false,
+    "discuss_mode": "discuss",
+    "skip_discuss": false,
+    "max_discuss_passes": 3,
+    "subagent_timeout": 300000,
+    "context_coverage_gate": true,
+    "code_review": true,
+    "code_review_depth": "standard",
+    "code_review_command": null,
+    "pattern_mapper": true,
+    "plan_bounce": false,
+    "plan_bounce_script": null,
+    "plan_bounce_passes": 2,
+    "auto_prune_state": false,
+    "post_planning_gaps": true,
+    "security_enforcement": true,
+    "security_asvs_level": 1,
+    "security_block_on": "high"
+  },
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false,
+    "sub_repos": [],
+    "granularity": "standard"
+  },
+  "hooks": {
+    "context_warnings": true,
+    "workflow_guard": false
+  },
+  "ship": {
+    "pr_body_sections": []
+  },
+  "graphify": {
+    "auto_update": false
+  },
+  "agent_skills": {},
+  "effort": {
+    "default": "high",
+    "routing_tier_defaults": {
+      "light": "low",
+      "standard": "high",
+      "heavy": "xhigh"
+    },
+    "agent_overrides": {}
+  },
+  "fast_mode": {
+    "enabled": false,
+    "routing_tier_defaults": {
+      "light": true,
+      "standard": false,
+      "heavy": false
+    },
+    "agent_overrides": {}
+  },
+  "plan_review": {
+    "source_grounding": true,
+    "source_grounding_authority": "grep"
+  }
+}
--- a/gsd-core/bin/shared/config-schema.manifest.json
+++ b/gsd-core/bin/shared/config-schema.manifest.json
@@ -0,0 +1,191 @@
+{
+  "_comment": "Canonical schema manifest for valid config key paths. This manifest is the single CJS source of truth for valid config keys; dynamicKeyPatterns source strings are recompiled to RegExp at runtime by config-schema.cjs. runtimeStateKeys mirrors RUNTIME_STATE_KEYS.",
+  "validKeys": [
+    "mode",
+    "granularity",
+    "parallelization",
+    "commit_docs",
+    "model_profile",
+    "search_gitignored",
+    "brave_search",
+    "firecrawl",
+    "exa_search",
+    "workflow.research",
+    "workflow.plan_check",
+    "workflow.verifier",
+    "workflow.nyquist_validation",
+    "workflow.ai_integration_phase",
+    "workflow.ui_phase",
+    "workflow.ui_safety_gate",
+    "workflow.auto_advance",
+    "workflow.node_repair",
+    "workflow.node_repair_budget",
+    "workflow.tdd_mode",
+    "workflow.human_verify_mode",
+    "workflow.text_mode",
+    "workflow.research_before_questions",
+    "workflow.discuss_mode",
+    "workflow.skip_discuss",
+    "workflow.auto_prune_state",
+    "workflow.use_worktrees",
+    "workflow.worktree_skip_hooks",
+    "workflow.code_review",
+    "workflow.code_review_depth",
+    "workflow.code_review_command",
+    "workflow.pattern_mapper",
+    "workflow.plan_bounce",
+    "workflow.plan_bounce_script",
+    "workflow.plan_bounce_passes",
+    "workflow.plan_chunked",
+    "workflow.plan_review_convergence",
+    "workflow.post_planning_gaps",
+    "workflow.security_enforcement",
+    "workflow.security_asvs_level",
+    "workflow.security_block_on",
+    "workflow.drift_threshold",
+    "workflow.drift_action",
+    "code_quality.fallow.enabled",
+    "code_quality.fallow.scope",
+    "code_quality.fallow.profile",
+    "code_quality.fallow.mcp",
+    "ship.pr_body_sections",
+    "git.branching_strategy",
+    "git.base_branch",
+    "git.create_tag",
+    "git.phase_branch_template",
+    "git.milestone_branch_template",
+    "git.quick_branch_template",
+    "planning.commit_docs",
+    "planning.search_gitignored",
+    "planning.sub_repos",
+    "review.ollama_host",
+    "review.lm_studio_host",
+    "review.llama_cpp_host",
+    "review.default_reviewers",
+    "review.max_prompt_tokens",
+    "review.max_prompt_tokens_per_reviewer",
+    "workflow.cross_ai_execution",
+    "workflow.cross_ai_command",
+    "workflow.cross_ai_timeout",
+    "workflow.subagent_timeout",
+    "executor.stall_detect_interval_minutes",
+    "executor.stall_threshold_minutes",
+    "workflow.inline_plan_threshold",
+    "hooks.context_warnings",
+    "hooks.workflow_guard",
+    "workflow.context_coverage_gate",
+    "statusline.show_last_command",
+    "statusline.context_position",
+    "workflow.ui_review",
+    "workflow.max_discuss_passes",
+    "features.thinking_partner",
+    "context",
+    "features.global_learnings",
+    "learnings.max_inject",
+    "project_code",
+    "phase_id_convention",
+    "phase_naming",
+    "manager.flags.discuss",
+    "manager.flags.plan",
+    "manager.flags.execute",
+    "response_language",
+    "context_window",
+    "intel.enabled",
+    "graphify.enabled",
+    "graphify.build_timeout",
+    "graphify.auto_update",
+    "claude_md_path",
+    "claude_md_assembly.mode",
+    "runtime",
+    "resolve_model_ids",
+    "effort.default",
+    "fast_mode.enabled",
+    "plan_review.source_grounding",
+    "plan_review.source_grounding_authority",
+    "model_policy.provider",
+    "model_policy.budget",
+    "model_policy.high",
+    "model_policy.medium",
+    "model_policy.low"
+  ],
+  "runtimeStateKeys": [
+    "workflow._auto_chain_active"
+  ],
+  "dynamicKeyPatterns": [
+    {
+      "topLevel": "agent_skills",
+      "source": "^agent_skills\\.[a-zA-Z0-9_-]+$",
+      "description": "agent_skills.<agent-type>"
+    },
+    {
+      "topLevel": "review",
+      "source": "^review\\.models\\.[a-zA-Z0-9_-]+$",
+      "description": "review.models.<cli-name>"
+    },
+    {
+      "topLevel": "features",
+      "source": "^features\\.[a-zA-Z0-9_]+$",
+      "description": "features.<feature_name>"
+    },
+    {
+      "topLevel": "claude_md_assembly",
+      "source": "^claude_md_assembly\\.blocks\\.[a-zA-Z0-9_]+$",
+      "description": "claude_md_assembly.blocks.<section>"
+    },
+    {
+      "topLevel": "model_profile_overrides",
+      "source": "^model_profile_overrides\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",
+      "description": "model_profile_overrides.<runtime>.<opus|sonnet|haiku>"
+    },
+    {
+      "topLevel": "models",
+      "source": "^models\\.(planning|discuss|research|execution|verification|completion)$",
+      "description": "models.<planning|discuss|research|execution|verification|completion>"
+    },
+    {
+      "topLevel": "granularities",
+      "source": "^granularities\\.(planning|discuss|research|execution|verification|completion)$",
+      "description": "granularities.<planning|discuss|research|execution|verification|completion>"
+    },
+    {
+      "topLevel": "dynamic_routing",
+      "source": "^dynamic_routing\\.(enabled|escalate_on_failure|max_escalations|tier_models\\.(light|standard|heavy))$",
+      "description": "dynamic_routing.<enabled|escalate_on_failure|max_escalations|tier_models.<light|standard|heavy>>"
+    },
+    {
+      "topLevel": "model_overrides",
+      "source": "^model_overrides\\.[a-zA-Z0-9_-]+$",
+      "description": "model_overrides.<agent-id>"
+    },
+    {
+      "topLevel": "effort",
+      "source": "^effort\\.routing_tier_defaults\\.(light|standard|heavy)$",
+      "description": "effort.routing_tier_defaults.<light|standard|heavy>"
+    },
+    {
+      "topLevel": "effort",
+      "source": "^effort\\.agent_overrides\\.[a-zA-Z0-9_-]+$",
+      "description": "effort.agent_overrides.<agent-id>"
+    },
+    {
+      "topLevel": "fast_mode",
+      "source": "^fast_mode\\.routing_tier_defaults\\.(light|standard|heavy)$",
+      "description": "fast_mode.routing_tier_defaults.<light|standard|heavy>"
+    },
+    {
+      "topLevel": "fast_mode",
+      "source": "^fast_mode\\.agent_overrides\\.[a-zA-Z0-9_-]+$",
+      "description": "fast_mode.agent_overrides.<agent-id>"
+    },
+    {
+      "topLevel": "review",
+      "source": "^review\\.max_prompt_tokens_per_reviewer\\.[a-zA-Z0-9_-]+$",
+      "description": "review.max_prompt_tokens_per_reviewer.<reviewer-slug>"
+    },
+    {
+      "topLevel": "model_policy",
+      "source": "^model_policy\\.runtime_tiers\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",
+      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku>"
+    }
+  ]
+}
--- a/gsd-core/bin/shared/model-catalog.json
+++ b/gsd-core/bin/shared/model-catalog.json
@@ -0,0 +1,149 @@
+{
+  "profiles": ["quality", "balanced", "budget", "adaptive", "inherit"],
+  "phaseTypes": ["planning", "discuss", "research", "execution", "verification", "completion"],
+  "adaptiveTierMap": {
+    "heavy": "opus",
+    "standard": "sonnet",
+    "light": "haiku"
+  },
+  "runtimeTierDefaults": {
+    "claude": {
+      "opus": { "model": "claude-opus-4-8" },
+      "sonnet": { "model": "claude-sonnet-4-6" },
+      "haiku": { "model": "claude-haiku-4-5" }
+    },
+    "codex": {
+      "opus": { "model": "gpt-5.5", "reasoning_effort": "xhigh" },
+      "sonnet": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" },
+      "haiku": { "model": "gpt-5.4-mini", "reasoning_effort": "medium" }
+    },
+    "gemini": {
+      "opus": { "model": "gemini-3-pro" },
+      "sonnet": { "model": "gemini-3-flash" },
+      "haiku": { "model": "gemini-2.5-flash-lite" }
+    },
+    "qwen": {
+      "opus": { "model": "qwen3-max-2026-01-23" },
+      "sonnet": { "model": "qwen3-coder-plus" },
+      "haiku": { "model": "qwen3-coder-next" }
+    },
+    "opencode": {
+      "opus": { "model": "anthropic/claude-opus-4-8" },
+      "sonnet": { "model": "anthropic/claude-sonnet-4-6" },
+      "haiku": { "model": "anthropic/claude-haiku-4-5" }
+    },
+    "copilot": {
+      "opus": { "model": "claude-opus-4-8" },
+      "sonnet": { "model": "claude-sonnet-4-6" },
+      "haiku": { "model": "claude-haiku-4-5" }
+    },
+    "hermes": {
+      "opus": { "model": "anthropic/claude-opus-4-8" },
+      "sonnet": { "model": "anthropic/claude-sonnet-4-6" },
+      "haiku": { "model": "anthropic/claude-haiku-4-5" }
+    },
+    "kilo": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "cline": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "cursor": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "windsurf": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "augment": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "trae": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "codebuddy": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
+    "antigravity": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    }
+  },
+  "providerPresets": {
+    "anthropic": {
+      "opus":   { "low": { "model": "claude-opus-4-5" }, "medium": { "model": "claude-opus-4-8" }, "high": { "model": "claude-opus-4-8" } },
+      "sonnet": { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-sonnet-4-6" }, "high": { "model": "claude-opus-4-8" } },
+      "haiku":  { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-haiku-4-5" }, "high": { "model": "claude-sonnet-4-6" } }
+    },
+    "openai": {
+      "opus":   { "low": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" }, "medium": { "model": "gpt-5.5", "reasoning_effort": "high" }, "high": { "model": "gpt-5.5", "reasoning_effort": "xhigh" } },
+      "sonnet": { "low": { "model": "gpt-5.4-mini", "reasoning_effort": "low" }, "medium": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.5", "reasoning_effort": "medium" } },
+      "haiku":  { "low": { "model": "gpt-5.4-mini", "reasoning_effort": "minimal" }, "medium": { "model": "gpt-5.4-mini", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" } }
+    },
+    "google": {
+      "opus":   { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-3-flash" }, "high": { "model": "gemini-3-pro" } },
+      "sonnet": { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-3-flash" }, "high": { "model": "gemini-3-flash" } },
+      "haiku":  { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-2.5-flash-lite" }, "high": { "model": "gemini-3-flash" } }
+    },
+    "qwen": {
+      "opus":   { "low": { "model": "qwen3-coder-plus" }, "medium": { "model": "qwen3-max-2026-01-23" }, "high": { "model": "qwen3-max-2026-01-23" } },
+      "sonnet": { "low": { "model": "qwen3-coder-next" }, "medium": { "model": "qwen3-coder-plus" }, "high": { "model": "qwen3-max-2026-01-23" } },
+      "haiku":  { "low": { "model": "qwen3-coder-next" }, "medium": { "model": "qwen3-coder-next" }, "high": { "model": "qwen3-coder-plus" } }
+    },
+    "generic": {
+      "opus":   { "low": null, "medium": null, "high": null },
+      "sonnet": { "low": null, "medium": null, "high": null },
+      "haiku":  { "low": null, "medium": null, "high": null }
+    }
+  },
+  "agents": {
+    "gsd-planner":                { "golden": "opus",   "balanced": "opus",   "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
+    "gsd-roadmapper":             { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
+    "gsd-executor":               { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "execution",    "routingTier": "standard" },
+    "gsd-phase-researcher":       { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-project-researcher":     { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-research-synthesizer":   { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "light" },
+    "gsd-debugger":               { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "execution",    "routingTier": "heavy" },
+    "gsd-codebase-mapper":        { "golden": "sonnet", "balanced": "haiku",  "budget": "haiku",  "phaseType": "research",     "routingTier": "light" },
+    "gsd-verifier":               { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "standard" },
+    "gsd-plan-checker":           { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-integration-checker":    { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-nyquist-auditor":        { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-pattern-mapper":         { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "planning",     "routingTier": "light" },
+    "gsd-ui-researcher":          { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-ui-checker":             { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-ui-auditor":             { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-doc-writer":             { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "execution",    "routingTier": "standard" },
+    "gsd-doc-verifier":           { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+
+    "gsd-advisor-researcher":     { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-ai-researcher":          { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-assumptions-analyzer":   { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "discuss",      "routingTier": "heavy" },
+    "gsd-code-fixer":             { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "execution",    "routingTier": "standard" },
+    "gsd-code-reviewer":          { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "verification", "routingTier": "standard" },
+    "gsd-debug-session-manager":  { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "execution",    "routingTier": "heavy" },
+    "gsd-doc-classifier":         { "golden": "sonnet", "balanced": "haiku",  "budget": "haiku",  "phaseType": "research",     "routingTier": "light" },
+    "gsd-doc-synthesizer":        { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-domain-researcher":      { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
+    "gsd-eval-auditor":           { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "standard" },
+    "gsd-eval-planner":           { "golden": "opus",   "balanced": "opus",   "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
+    "gsd-framework-selector":     { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
+    "gsd-intel-updater":          { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "light" },
+    "gsd-security-auditor":       { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "verification", "routingTier": "heavy" },
+    "gsd-user-profiler":          { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "research",     "routingTier": "heavy" }
+  }
+}
--- a/gsd-core/bin/shared/runtime-aliases.manifest.json
+++ b/gsd-core/bin/shared/runtime-aliases.manifest.json
@@ -0,0 +1,75 @@
+{
+  "claude": [
+    "claude",
+    "claude-code",
+    "claude-cli"
+  ],
+  "opencode": [
+    "opencode",
+    "open-code",
+    "opencode-cli"
+  ],
+  "kilo": [
+    "kilo",
+    "kilo-cli"
+  ],
+  "gemini": [
+    "gemini",
+    "gemini-cli",
+    "gemini-code"
+  ],
+  "codex": [
+    "codex",
+    "codex-app",
+    "codex-cli",
+    "codex_desktop",
+    "codex-desktop"
+  ],
+  "copilot": [
+    "copilot",
+    "copilot-cli",
+    "github-copilot"
+  ],
+  "antigravity": [
+    "antigravity",
+    "antigravity-cli",
+    "antigravity-agent"
+  ],
+  "cursor": [
+    "cursor",
+    "cursor-cli",
+    "cursor-nightly"
+  ],
+  "windsurf": [
+    "windsurf",
+    "windsurf-cli",
+    "windsurf-next"
+  ],
+  "augment": [
+    "augment",
+    "augment-code",
+    "augment-cli"
+  ],
+  "trae": [
+    "trae",
+    "trae-cli"
+  ],
+  "qwen": [
+    "qwen",
+    "qwen-code",
+    "qwen-cli"
+  ],
+  "hermes": [
+    "hermes",
+    "hermes-agent",
+    "hermes-cli"
+  ],
+  "codebuddy": [
+    "codebuddy",
+    "codebuddy-cli"
+  ],
+  "cline": [
+    "cline",
+    "cline-cli"
+  ]
+}
--- a/gsd-core/bin/verify-reapply-patches.cjs
+++ b/gsd-core/bin/verify-reapply-patches.cjs
@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Deterministic verifier for the /gsd-reapply-patches Step 5 "Hunk Verification
+ * Gate". For each backed-up patch file, asserts that the user's added lines
+ * (computed from a real diff against the pristine baseline, not from the
+ * LLM's prose summary) survive into the merged output.
+ *
+ * Usage:
+ *   node scripts/verify-reapply-patches.cjs \
+ *     --patches-dir <path>        \  # gsd-local-patches/
+ *     --config-dir <path>         \  # ~/.claude (or runtime equivalent)
+ *     [--pristine-dir <path>]        # gsd-pristine/; if absent, falls back to
+ *                                    # treating every significant backup line as
+ *                                    # required (over-broad but safe for #2969:
+ *                                    # false-positive halts beat silent successes
+ *                                    # on lost content)
+ *     [--json]                       # emit JSON report instead of human text
+ *
+ * Exit codes:
+ *   0 — every user-added line is present in the merged file (gate passes)
+ *   1 — at least one missing line in at least one file (gate fails)
+ *   2 — usage / structural error (e.g. patches dir missing)
+ *
+ * Bug #2969: the Step 5 gate previously trusted Claude's free-text "verified:
+ * yes/no" reporting per hunk. The LLM was filling in `yes` even when content
+ * had been silently dropped. Moving the check to a deterministic script is the
+ * durability fix.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const SIGNIFICANT_MIN_CHARS = 12;
+const GSD_HOOK_VERSION_LINE_RE = /^(?:\/\/|#)\s*gsd-hook-version:\s*\S+\s*$/i;
+
+function parseArgs(argv) {
+  const opts = { patchesDir: null, configDir: null, pristineDir: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--patches-dir') opts.patchesDir = argv[++i];
+    else if (arg === '--config-dir') opts.configDir = argv[++i];
+    else if (arg === '--pristine-dir') opts.pristineDir = argv[++i];
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') {
+      process.stdout.write(
+        'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json]\n',
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown argument: ${arg}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function isSignificantLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length < SIGNIFICANT_MIN_CHARS) return false;
+  // Pure punctuation / closing brackets carry too little structural info to
+  // reliably distinguish a survived hunk from incidental similarity.
+  if (/^[\s})\];,]+$/.test(trimmed)) return false;
+  // Generic decorative comments like `// ----` similarly fail the test.
+  if (/^[\s\-=#*/]+$/.test(trimmed)) return false;
+  return true;
+}
+
+function normalizeUpstreamOwnedLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return line;
+  if (GSD_HOOK_VERSION_LINE_RE.test(trimmed)) {
+    const prefix = trimmed.startsWith('#') ? '#' : '//';
+    return `${prefix} gsd-hook-version: __GSD_VERSION_TOKEN__`;
+  }
+  return line;
+}
+
+/**
+ * Compute the SHA-256 hex digest of a string (UTF-8 encoded).
+ */
+function sha256(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Read the `pristine_hashes` map from backup-meta.json in the patches dir.
+ * Returns an empty object if backup-meta.json is absent, unreadable, or has no
+ * `pristine_hashes` field — callers must treat an empty map as "no recorded
+ * hash for any file" (no hash-validation possible, not an error).
+ */
+function readPristineHashes(patchesDir) {
+  const metaPath = path.join(patchesDir, 'backup-meta.json');
+  try {
+    const raw = fs.readFileSync(metaPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.pristine_hashes === 'object' && parsed.pristine_hashes !== null) {
+      return parsed.pristine_hashes;
+    }
+  } catch {
+    // absent or unreadable — not an error, just no recorded hashes
+  }
+  return {};
+}
+
+/**
+ * Walk a directory, returning every file's path relative to the root.
+ */
+function walk(rootDir, relPrefix = '') {
+  const out = [];
+  if (!fs.existsSync(rootDir)) return out;
+  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    const rel = relPrefix ? path.join(relPrefix, entry.name) : entry.name;
+    const abs = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walk(abs, rel));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the set of "user-added" lines: lines present in the backup but
+ * absent from the pristine baseline. If no pristine is provided, falls back
+ * to using every significant line in the backup (over-broad but safe — favours
+ * false-positive failures over silent successes, which is the right side to
+ * err on for #2969).
+ */
+function computeUserAddedLines(backupContent, pristineContent) {
+  const backupLines = backupContent.split(/\r?\n/);
+  if (!pristineContent) {
+    return backupLines.filter(isSignificantLine);
+  }
+  const pristineSet = new Set(
+    pristineContent.split(/\r?\n/).map(normalizeUpstreamOwnedLine),
+  );
+  return backupLines.filter((line) => {
+    if (!isSignificantLine(line)) return false;
+    return !pristineSet.has(normalizeUpstreamOwnedLine(line));
+  });
+}
+
+/**
+ * Stable reason codes for the per-file result. Tests assert via
+ * `assert.equal(result.reason, REASON.X)` rather than regex-matching prose,
+ * so the diagnostic surface is a typed enum, not free text.
+ *
+ * Adding a new reason requires updating the REASON map AND the tests'
+ * shape assertion that locks the documented set of codes.
+ */
+const REASON = Object.freeze({
+  OK_NO_USER_LINES_VS_PRISTINE: 'ok_no_user_lines_vs_pristine',
+  OK_NO_SIGNIFICANT_BACKUP_LINES: 'ok_no_significant_backup_lines',
+  // Bug #3657: the on-disk gsd-pristine/ file's SHA-256 does not match the
+  // hash recorded in backup-meta.json.pristine_hashes.  This means the
+  // pristine snapshot was refreshed to a newer GSD version after the backup
+  // was captured.  Using the wrong-version pristine as the diff baseline would
+  // invert the delta (upstream removals appear as "missing user lines").
+  // The verifier skips this file rather than false-failing it.  A separate
+  // re-anchor step (or the git-aware fallback in the workflow) is needed to
+  // resolve this file; the guard here ensures the gate does not report spurious
+  // failures in the meantime.
+  OK_PRISTINE_DRIFT_DETECTED: 'ok_pristine_drift_detected',
+  FAIL_INSTALLED_MISSING: 'fail_installed_missing',
+  FAIL_INSTALLED_NOT_REGULAR_FILE: 'fail_installed_not_regular_file',
+  FAIL_READ_ERROR: 'fail_read_error',
+  FAIL_USER_LINES_MISSING: 'fail_user_lines_missing',
+});
+
+function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes }) {
+  const backupPath = path.join(patchesDir, relPath);
+  const installedPath = path.join(configDir, relPath);
+  const result = { file: relPath, status: 'ok', missing: [], reason: null };
+
+  if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isFile()) {
+    return result; // walked entry no longer exists — non-fatal
+  }
+
+  // Installed path checks: must exist, must be a regular file, must be
+  // readable. Anything else is a fail-with-diagnostic, not a crash that
+  // aborts the whole gate run and drops structured output.
+  let installedStat;
+  try {
+    installedStat = fs.statSync(installedPath);
+  } catch {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_INSTALLED_MISSING;
+    return result;
+  }
+  if (!installedStat.isFile()) {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_INSTALLED_NOT_REGULAR_FILE;
+    return result;
+  }
+
+  let backupContent;
+  let installedContent;
+  try {
+    backupContent = fs.readFileSync(backupPath, 'utf8');
+    installedContent = fs.readFileSync(installedPath, 'utf8');
+  } catch {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_READ_ERROR;
+    return result;
+  }
+
+  let pristineContent = null;
+  if (pristineDir) {
+    const pristinePath = path.join(pristineDir, relPath);
+    try {
+      const stat = fs.statSync(pristinePath);
+      if (stat.isFile()) {
+        const candidate = fs.readFileSync(pristinePath, 'utf8');
+        // Bug #3657: if backup-meta.json recorded a pristine_hash for this
+        // file, validate that the on-disk pristine matches it.  A mismatch
+        // means the installer refreshed gsd-pristine/ to a newer GSD version
+        // after the backup was captured.  Using the wrong-version pristine as
+        // the diff baseline inverts the delta: upstream removals appear as
+        // "user-added lines that must survive", causing FAIL_USER_LINES_MISSING
+        // false positives.  When the hash is stale, skip the pristine and fall
+        // through to over-broad mode (every significant backup line is checked).
+        // Over-broad mode never false-fails for a different reason because all
+        // backup lines that are genuinely user-added will still be present in a
+        // correctly merged install.
+        // Normalize to forward slashes so the key lookup matches on Windows
+        // where path.join produces backslash-separated relPath values but
+        // backup-meta.json stores keys written with forward slashes.
+        const hashKey = relPath.replace(/\\/g, '/');
+        const recordedHash = pristineHashes && pristineHashes[hashKey];
+        if (recordedHash) {
+          if (sha256(candidate) === recordedHash) {
+            // Hash matches: the on-disk pristine is the correct baseline.
+            pristineContent = candidate;
+          } else {
+            // Hash mismatch: the on-disk gsd-pristine/ was refreshed to a newer
+            // GSD version after the backup was captured.  Using it as the diff
+            // baseline would invert the delta and produce false FAIL_USER_LINES_MISSING
+            // reports (Bug #3657).  Report the file as ok with a diagnostic code
+            // so the gate does not false-fail; a re-anchor or git-aware baseline
+            // step is required to verify this file correctly.
+            result.reason = REASON.OK_PRISTINE_DRIFT_DETECTED;
+            return result;
+          }
+        } else {
+          // No recorded hash for this file (older installer or absent
+          // backup-meta) — use the on-disk pristine as-is (pre-fix behaviour).
+          pristineContent = candidate;
+        }
+      }
+    } catch {
+      // Pristine missing or unreadable — fall through to over-broad mode.
+    }
+  }
+
+  const userAdded = computeUserAddedLines(backupContent, pristineContent);
+  if (userAdded.length === 0) {
+    // Backup and pristine match exactly (or no significant content) — nothing
+    // to verify but also nothing to lose. Report as ok with diagnostic code.
+    result.reason = pristineContent
+      ? REASON.OK_NO_USER_LINES_VS_PRISTINE
+      : REASON.OK_NO_SIGNIFICANT_BACKUP_LINES;
+    return result;
+  }
+
+  for (const line of userAdded) {
+    if (!installedContent.includes(line)) {
+      result.missing.push(line.trim());
+    }
+  }
+  if (result.missing.length > 0) {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_USER_LINES_MISSING;
+  }
+  return result;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts.patchesDir || !opts.configDir) {
+    process.stderr.write('--patches-dir and --config-dir are required\n');
+    process.exit(2);
+  }
+  if (!fs.existsSync(opts.patchesDir)) {
+    process.stderr.write(`patches dir not found: ${opts.patchesDir}\n`);
+    process.exit(2);
+  }
+  if (!fs.existsSync(opts.configDir)) {
+    process.stderr.write(`config dir not found: ${opts.configDir}\n`);
+    process.exit(2);
+  }
+
+  const files = walk(opts.patchesDir).filter((f) => !f.endsWith('backup-meta.json'));
+  // Bug #3657: read pristine_hashes from backup-meta.json once and share
+  // across all per-file verifications so each can detect drift independently.
+  const pristineHashes = readPristineHashes(opts.patchesDir);
+  const results = files.map((relPath) =>
+    verifyFile({
+      relPath,
+      patchesDir: opts.patchesDir,
+      configDir: opts.configDir,
+      pristineDir: opts.pristineDir,
+      pristineHashes,
+    }),
+  );
+
+  const failures = results.filter((r) => r.status === 'fail');
+
+  // Bug #3657 (Finding 1): aggregate drifted files into top-level report fields
+  // so workflow Step 5a can gate on drift distinctly from failures.  Drift is
+  // NOT a failure (exit code stays 0) but the workflow now has structured data
+  // to decide whether to proceed.  Per-file shape is unchanged: each drifted
+  // result still has status:'ok' + reason:OK_PRISTINE_DRIFT_DETECTED for
+  // backward compat.  The new top-level fields are purely additive.
+  const driftedResults = results.filter((r) => r.reason === REASON.OK_PRISTINE_DRIFT_DETECTED);
+  const drifted = driftedResults.length;
+  const drifted_files = driftedResults.map((r) => r.file);
+
+  if (opts.json) {
+    process.stdout.write(
+      JSON.stringify({ checked: results.length, failures: failures.length, drifted, drifted_files, results }, null, 2) + '\n',
+    );
+  } else {
+    process.stdout.write(`# Hunk Verification Gate (#2969)\n\n`);
+    process.stdout.write(`Checked: ${results.length} file(s)\n`);
+    process.stdout.write(`Failures: ${failures.length}\n\n`);
+    if (failures.length > 0) {
+      process.stdout.write(`## Files with missing user-added content\n\n`);
+      for (const r of failures) {
+        process.stdout.write(`- ${r.file}\n`);
+        if (r.reason) process.stdout.write(`  reason: ${r.reason}\n`);
+        for (const line of r.missing.slice(0, 5)) {
+          process.stdout.write(`  missing: ${line}\n`);
+        }
+        if (r.missing.length > 5) {
+          process.stdout.write(`  …and ${r.missing.length - 5} more line(s)\n`);
+        }
+      }
+    }
+  }
+
+  process.exit(failures.length > 0 ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, walk, REASON, readPristineHashes, sha256 };