@boyingliu01/xp-gate 0.18.5 → 0.19.1

package/lib/gate-runner.js

@@ -1,17 +1,24 @@
-'use strict';
-
-const { execSync, execFileSync, spawnSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
+const { execSync, execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
 
 /**
- * Run a bash shell script cross-platform.
- * On Unix: uses bash directly.
- * On Windows: tries bash from PATH (Git Bash / WSL), falls back to a clear message.
+ * Run a gate adapter fragment standalone.
+ *
+ * The gate fragments in githooks/adapters/gate-*.sh are designed to be *sourced*
+ * into the pre-commit hook, which pre-defines the context they rely on:
+ *   - PROJECT_LANG (from detect_project_lang)
+ *   - CHANGED_FILES (from git)
+ *   - gate_start_ms() / record_gate_audit() / now_ms() audit & timing helpers
+ *
+ * When `xp-gate check` invokes a gate standalone, that context is missing and
+ * the fragments fail with "command not found". This wrapper reconstructs the
+ * same preamble the pre-commit hook sets up, then *sources* the fragment so it
+ * behaves exactly as it does inside the commit hook.
  */
-function runBashScript(scriptPath) {
+function runGateAdapter(scriptPath, cwd = process.cwd()) {
   if (process.platform === 'win32') {
-    // Check if bash is available on Windows (Git Bash, MSYS2, WSL)
     try {
       execSync('bash --version', { stdio: 'pipe', timeout: 5000 });
     } catch {
@@ -21,8 +28,44 @@ function runBashScript(scriptPath) {
       return;
     }
   }
-  // bash is available — run the script (Unix always, or Windows after check above)
-  execSync(`bash "${scriptPath}"`, { stdio: 'inherit' });
+  const scriptDir = path.dirname(scriptPath);
+  const commonScript = [
+    path.join(scriptDir, 'adapter-common.sh'),
+    path.join(scriptDir, '..', 'adapter-common.sh'),
+    path.join(cwd, 'githooks', 'adapter-common.sh'),
+  ].find(candidate => fs.existsSync(candidate)) || '';
+  const nowMsScript = [
+    path.join(scriptDir, 'lib', 'now-ms.sh'),
+    path.join(scriptDir, '..', 'lib', 'now-ms.sh'),
+    path.resolve(__dirname, '..', 'hooks', 'lib', 'now-ms.sh'),
+  ].find(candidate => fs.existsSync(candidate)) || '';
+  const changedFilesParameter = ['$', '{CHANGED_FILES}'].join('');
+
+  // Build the shell preamble the pre-commit hook would otherwise inject before
+  // sourcing the gate fragment, then source that fragment. Deliberately NOT
+  // set -u (the pre-commit hook does not use it), so fragments that reference
+  // a not-yet-defined variable fail the same way inside the commit hook.
+  const wrap = [
+    'if [ -n "$1" ] && [ -f "$1" ]; then source "$1"; fi',
+    'if [ -n "$2" ] && [ -f "$2" ]; then source "$2"; fi',
+    'if ! command -v now_ms >/dev/null 2>&1; then now_ms() { "$4" -e "console.log(Date.now())"; }; fi',
+    'gate_start_ms() { now_ms; }',
+    'record_gate_audit() { :; }',
+    'PROJECT_LANG="$(detect_project_lang 2>/dev/null || echo unknown)"',
+    'CHANGED_FILES="$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)"',
+    `if [ -z "${changedFilesParameter}" ] && [ -n "$(git rev-parse HEAD 2>/dev/null)" ]; then`,
+    '  CHANGED_FILES="$(git diff HEAD --name-only --diff-filter=ACM 2>/dev/null || true)"',
+    'fi',
+    'source "$3"',
+  ].join('\n');
+
+  // execFileSync avoids an extra /bin/sh layer, so bash receives the script as a
+  // single argv arg (no shell-metacharacter injection through the path).
+  execFileSync(
+    'bash',
+    ['--noprofile', '--norc', '-c', wrap, 'xp-gate', commonScript, nowMsScript, scriptPath, process.execPath],
+    { stdio: 'inherit', cwd }
+  );
 }
 
 // Gate metadata registry — maps gate IDs to names, descriptions, and how to run them.
@@ -35,12 +78,14 @@ function runBashScript(scriptPath) {
  * Falls back to bash script if TypeScript module not found.
  */
 function runTsGate(gateModule, targetPath) {
+  const targetCwd = targetPath ? path.resolve(targetPath) : process.cwd();
   const entry = findTsGateEntry(gateModule);
   if (!entry) {
     // Fallback to bash script
-    const script = resolveGateScript(gateModule.replace('gate-', ''));
+    const gateNum = gateModule.replace('gate-', '');
+    const script = resolveGateScript(gateNum, targetCwd);
     if (script) {
-      runBashScript(script);
+      runGateAdapter(script, targetCwd);
     } else {
       console.log(`Gate ${gateModule}: TypeScript module not found and no bash fallback available.`);
     }
@@ -53,7 +98,7 @@ function runTsGate(gateModule, targetPath) {
   const result = spawnSync('npx', args, {
     stdio: 'inherit',
     shell: process.platform === 'win32',
-    cwd: targetPath || process.cwd(),
+    cwd: targetCwd,
     timeout: 120000,
   });
 
@@ -76,6 +121,7 @@ function findTsGateEntry(gateModule) {
   }
   return null;
 }
+// allow: SIZE_OK - this module's bulk is the declarative gate registry below.
 const GATE_REGISTRY = {
   '0': {
     name: 'Version Consistency',
@@ -130,7 +176,7 @@ const GATE_REGISTRY = {
     name: 'Architecture + Boy Scout Rule',
     description: 'Architecture layer boundary validation and warning baseline enforcement',
     aliases: ['architecture', 'arch', '6'],
-    run: (targetPath) => {
+    run: () => {
       const { arch } = require('./arch.js');
       return arch([]);
     },
@@ -242,17 +288,16 @@ function findConfig(basePath, fileName) {
   return null;
 }
 
-function resolveGateScript(gateNum) {
+function resolveGateScript(gateNum, cwd = process.cwd()) {
   const candidates = [
-    path.join(process.cwd(), 'githooks', 'gates', `gate-${gateNum}-*.sh`),
-    path.join(process.cwd(), 'githooks', `gate-${gateNum}.sh`),
+    path.join(cwd, 'githooks', 'gates', `gate-${gateNum}-*.sh`),
+    path.join(cwd, 'githooks', `gate-${gateNum}.sh`),
   ];
 
   // Try glob patterns
   for (const pattern of candidates) {
     if (pattern.includes('*')) {
       const dir = path.dirname(pattern);
-      const prefix = path.basename(pattern).replace('*', '');
       if (fs.existsSync(dir)) {
         const match = fs.readdirSync(dir).find(f => f.startsWith(`gate-${gateNum}-`) && f.endsWith('.sh'));
         if (match) return path.join(dir, match);
@@ -263,7 +308,7 @@ function resolveGateScript(gateNum) {
   }
 
   // Check global install
-  const globalDir = path.join(require('os').homedir(), '.config', 'xp-gate', 'adapters');
+  const globalDir = path.join(os.homedir(), '.config', 'xp-gate', 'adapters');
   const globalScript = path.join(globalDir, `gate-${gateNum}.sh`);
   if (fs.existsSync(globalScript)) return globalScript;
 
@@ -289,7 +334,7 @@ async function runGate(gateId, targetPath) {
   const gate = GATE_REGISTRY[String(gateId)];
   if (!gate) {
     console.error(`Unknown gate: ${gateId}`);
-    console.error('Available gates: ' + Object.keys(GATE_REGISTRY).join(', '));
+    console.error(`Available gates: ${Object.keys(GATE_REGISTRY).join(', ')}`);
     return 1;
   }
 
@@ -319,4 +364,4 @@ async function runGate(gateId, targetPath) {
   return 1;
 }
 
-module.exports = { GATE_REGISTRY, getGateInfo, getAllGates, runGate, resolveAlias, getAliases };
+module.exports = { GATE_REGISTRY, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript };

package/lib/init.js

@@ -24,6 +24,27 @@ function copyRecursive(src, dest) {
   }
 }
 
+// Third-party packages imported by the copied quality-gate modules. When the
+// modules run via `npx tsx` from <CONFIG_DIR>/modules/<module>, these must be
+// resolvable from an ancestor directory, so they are installed once into
+// <CONFIG_DIR>/node_modules. Keep in sync with each module's imports.
+const MODULE_RUNTIME_DEPS = { 'js-yaml': '^5.2.2', 'zod': '^4.4.3' };
+
+function installModuleRuntimeDeps(configDir) {
+  const { execSync } = require('child_process');
+  const pkgPath = path.join(configDir, 'package.json');
+  try {
+    const existing = fs.existsSync(pkgPath) ? JSON.parse(fs.readFileSync(pkgPath, 'utf8')) : {};
+    const mergedDeps = { ...(existing.dependencies || {}), ...MODULE_RUNTIME_DEPS };
+    fs.writeFileSync(pkgPath, JSON.stringify({ ...existing, dependencies: mergedDeps }, null, 2) + '\n');
+    execSync('npm install --omit=dev --no-audit --no-fund', { cwd: configDir, stdio: ['ignore', 'inherit', 'inherit'] });
+    console.log(`  module runtime deps -> ${path.join(configDir, 'node_modules')}`);
+  } catch (e) {
+    console.warn(`  Warning: could not install module runtime deps into ${configDir} (${e.message})`);
+    console.warn('  Gate ML (mock-policy) may SKIP until deps are available.');
+  }
+}
+
 function logDeps(depCheck) {
   if (!depCheck.ok) {
     console.warn('Warning: Missing dependencies');
@@ -471,9 +492,9 @@ async function installLocal(args) {
   copyAdapters(srcDir, path.join(projectRoot, 'githooks'));
   console.log(`  adapter-common.sh + adapters -> ${projectRoot}/githooks/`);
 
-  // Install principles/, mutation/, mock-policy/ to .xp-gate/modules/
+  // Install principles/, mutation/, mock-policy/, build-integrity/ to .xp-gate/modules/
   const modulesDir = path.join(projectRoot, '.xp-gate', 'modules');
-  ['principles', 'mutation', 'mock-policy'].forEach(module => {
+  ['principles', 'mutation', 'mock-policy', 'build-integrity'].forEach(module => {
     const moduleSrc = path.join(srcDir, module);
     const moduleDest = path.join(modulesDir, module);
     if (fs.existsSync(moduleSrc)) {
@@ -482,6 +503,7 @@ async function installLocal(args) {
       console.log(`  ${module}/ -> .xp-gate/modules/${module}/`);
     }
   });
+  installModuleRuntimeDeps(path.join(projectRoot, '.xp-gate'));
 
   fs.mkdirSync(TEMPLATE_DIR, { recursive: true });
   copyHooks(srcDir, TEMPLATE_DIR);
@@ -551,10 +573,10 @@ async function setupGlobal(args) {
   copyAdapters(srcDir, GLOBAL_ADAPTERS_DIR);
   console.log(`  adapter-common.sh + adapters -> ${GLOBAL_ADAPTERS_DIR}`);
 
-  // Install principles/, mutation/, mock-policy/ to global modules dir
+  // Install principles/, mutation/, mock-policy/, build-integrity/ to global modules dir
   console.log('[setup-global] Installing quality gate modules...');
   const globalModulesDir = path.join(CONFIG_DIR, 'modules');
-  ['principles', 'mutation', 'mock-policy'].forEach(module => {
+  ['principles', 'mutation', 'mock-policy', 'build-integrity'].forEach(module => {
     const moduleSrc = path.join(srcDir, module);
     const moduleDest = path.join(globalModulesDir, module);
     if (fs.existsSync(moduleSrc)) {
@@ -564,6 +586,13 @@ async function setupGlobal(args) {
     }
   });
 
+  // Copied modules are pure TS sourced into <CONFIG_DIR>/modules/. Any of them
+  // that import third-party packages (currently only mock-policy: js-yaml, zod)
+  // resolve them via Node's ancestor lookup up from the module location, so we
+  // install those deps into <CONFIG_DIR>/node_modules once. Best-effort: a
+  // missing register/network must not break global setup.
+  installModuleRuntimeDeps(CONFIG_DIR);
+
   console.log('[setup-global] Configuring git...');
   const { execSync } = require('child_process');
   try {
@@ -742,4 +771,4 @@ function injectKarpathyPrinciples(projectRoot) {
   }
 }
 
-module.exports = { init, promptBootstrap };
+module.exports = { init, promptBootstrap, installModuleRuntimeDeps };

package/lib/install-skill.js

@@ -32,6 +32,7 @@ function getCliVersion() {
 const SKILLS_REGISTRY = {
   'admin-template-guidelines': { repo: 'boyingliu01/xp-gate', path: 'skills/admin-template-guidelines' },
   'batch-grill-me': { repo: 'boyingliu01/xp-gate', path: 'skills/batch-grill-me' },
+  'clipboard-vision': { repo: 'boyingliu01/xp-gate', path: 'skills/clipboard-vision' },
   'delphi-review': { repo: 'boyingliu01/xp-gate', path: 'skills/delphi-review' },
   'domain-modeling': { repo: 'boyingliu01/xp-gate', path: 'skills/domain-modeling' },
   'grill-with-docs': { repo: 'boyingliu01/xp-gate', path: 'skills/grill-with-docs' },

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-07-29T02:23:45.690Z",
+  "checked_at": "2026-08-30T15:25:50.166Z",
   "source": "network"
 }

package/lib/phase-transition.js

@@ -25,7 +25,7 @@
 const path = require('path');
 const fs = require('fs');
 const crypto = require('crypto');
-const { execSync } = require('child_process');
+const { execFileSync, execSync } = require('child_process');
 const { SprintStateManager } = require('./sprint-state-manager');
 
 /**
@@ -45,7 +45,10 @@ const PHASE_NAMES = {
 const EVIDENCE_FILES = {
   2: {
     path: '.sprint-state/phase-outputs/requirements-reviewed.json',
-    requiredFields: ['verdict', 'requirements_hash'],
+    requiredFields: [
+      'verdict', 'requirements_statement', 'timestamp', 'consensus_ratio',
+      'expert_verdicts', 'head_commit', 'requirements_hash',
+    ],
     blockingCheck: (data) => data.verdict === 'APPROVED',
     blockingMessage: 'Requirements review verdict is not APPROVED',
   },
@@ -57,22 +60,79 @@ const EVIDENCE_FILES = {
   },
 };
 
+const GIT_REPOSITORY_ENV_VARS = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS',
+  'GIT_CONFIG_COUNT', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', 'GIT_INDEX_FILE',
+  'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_PREFIX',
+  'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+];
+
+function createRepositoryGitEnv() {
+  const env = { ...process.env };
+  for (const name of GIT_REPOSITORY_ENV_VARS) {
+    delete env[name];
+  }
+  return env;
+}
+
 /**
  * Get current HEAD commit hash from a project directory.
- * Returns 'unknown' if not in a git repo.
+ * Returns null if HEAD cannot be resolved.
  * @param {string} projectDir
- * @returns {string}
+ * @returns {string | null}
  */
 function getCurrentHeadCommit(projectDir) {
   try {
     return execSync('git rev-parse HEAD', {
       cwd: projectDir,
+      env: createRepositoryGitEnv(),
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
   } catch {
-    return 'unknown';
+    return null;
+  }
+}
+
+function validateRequirementsExpertEvidence(data) {
+  const validationErrors = [];
+  if (!Array.isArray(data.expert_verdicts) || data.expert_verdicts.length !== 3) {
+    validationErrors.push('expert_verdicts must contain exactly 3 expert results');
+    return validationErrors;
+  }
+
+  const expectedRoles = new Set(['architecture', 'technical', 'feasibility']);
+  const roles = data.expert_verdicts.map(expert => expert?.role);
+  if (roles.some(role => !expectedRoles.has(role)) || new Set(roles).size !== expectedRoles.size) {
+    validationErrors.push('expert_verdicts roles must be exactly architecture, technical, and feasibility');
+  }
+  if (data.expert_verdicts.some(expert => expert?.verdict !== 'APPROVED')) {
+    validationErrors.push('every expert verdict must be APPROVED');
+  }
+  if (data.expert_verdicts.some(expert => expert?.result_type !== 'delphi_expert_result')) {
+    validationErrors.push('every expert result_type must be delphi_expert_result');
   }
+  if (data.expert_verdicts.some(expert =>
+    (expert?.error !== undefined && expert.error !== false && expert.error !== null)
+    || (expert?.fallback !== undefined && expert.fallback !== false && expert.fallback !== null)
+  )) {
+    validationErrors.push('expert results must not contain an error or fallback marker');
+  }
+
+  const requestedModels = data.expert_verdicts.map(expert =>
+    typeof expert?.requested_model === 'string' ? expert.requested_model.trim() : ''
+  );
+  if (requestedModels.some(model => model.length === 0)) {
+    validationErrors.push('every requested_model must be a non-empty trimmed string');
+  } else if (new Set(requestedModels).size !== requestedModels.length) {
+    validationErrors.push('requested_model values must be distinct after trimming');
+  }
+
+  if (!Number.isFinite(data.consensus_ratio) || data.consensus_ratio < 0.9 || data.consensus_ratio > 1) {
+    validationErrors.push('consensus_ratio must be a finite number from 0.90 through 1');
+  }
+  return validationErrors;
 }
 
 /**
@@ -85,6 +145,66 @@ function computeFileHash(filePath) {
   return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
 }
 
+function parseEvidenceDate(timestamp) {
+  if (typeof timestamp !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(timestamp)) {
+    return null;
+  }
+  const parsed = new Date(timestamp);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== timestamp.slice(0, 10)) {
+    return null;
+  }
+  return timestamp.slice(0, 10);
+}
+
+function readRequirementsContext(data, projectDir) {
+  const contextFile = data.context_file_used;
+  if (contextFile === null || contextFile === undefined || contextFile === '') {
+    return { content: '' };
+  }
+  if (typeof contextFile !== 'string' || path.isAbsolute(contextFile)) {
+    return { error: 'context_file_used must be a safe project-relative regular file path' };
+  }
+
+  const projectRoot = fs.realpathSync(projectDir);
+  const candidatePath = path.resolve(projectRoot, contextFile);
+  const relativeCandidate = path.relative(projectRoot, candidatePath);
+  if (relativeCandidate.startsWith('..') || path.isAbsolute(relativeCandidate) || !fs.existsSync(candidatePath)) {
+    return { error: 'context_file_used must be a safe project-relative regular file path' };
+  }
+
+  const realContextPath = fs.realpathSync(candidatePath);
+  const relativeRealPath = path.relative(projectRoot, realContextPath);
+  if (relativeRealPath.startsWith('..') || path.isAbsolute(relativeRealPath) || !fs.statSync(realContextPath).isFile()) {
+    return { error: 'context_file_used must be a safe project-relative regular file path' };
+  }
+  return { content: fs.readFileSync(realContextPath, 'utf8') };
+}
+
+function computeRequirementsHash(data, projectDir) {
+  if (typeof data.requirements_statement !== 'string') {
+    return { error: 'requirements_statement must be a string' };
+  }
+  const evidenceDate = parseEvidenceDate(data.timestamp);
+  if (evidenceDate === null) {
+    return { error: 'timestamp must be a valid UTC ISO-8601 timestamp' };
+  }
+
+  let context;
+  try {
+    context = readRequirementsContext(data, projectDir);
+  } catch {
+    return { error: 'context_file_used must be a safe project-relative regular file path' };
+  }
+  if (context.error) {
+    return context;
+  }
+  return {
+    hash: crypto.createHash('sha256')
+      .update(`${data.requirements_statement}${context.content}${evidenceDate}`, 'utf8')
+      .digest('hex'),
+  };
+}
+
 /**
  * Validate phase evidence files for a given phase transition.
  *
@@ -149,6 +269,15 @@ function validateEvidence(phase, projectDir) {
     return { ok: false, errors, warnings };
   }
 
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    const msg = `${fileName} must contain a JSON object`;
+    if (isLegacySprint) {
+      warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      return { ok: true, errors: [], warnings };
+    }
+    return { ok: false, errors: [msg], warnings };
+  }
+
   // Check required fields
   for (const field of evidenceConfig.requiredFields) {
     if (!(field in data)) {
@@ -168,7 +297,7 @@ function validateEvidence(phase, projectDir) {
 
   // Run blocking check
   if (!evidenceConfig.blockingCheck(data)) {
-    const msg = `${fileName}: ${evidenceConfig.blockingMessage} (got: ${JSON.stringify(data[evidenceConfig.requiredFields[0]])})`;
+    const msg = `${fileName}: ${evidenceConfig.blockingMessage}`;
     if (isLegacySprint) {
       warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
       return { ok: true, errors: [], warnings };
@@ -178,10 +307,16 @@ function validateEvidence(phase, projectDir) {
   }
 
   // Phase-specific anti-staleness checks
-  if (phase === 4) {
-    // head_commit check
+  if (phase === 2 || phase === 4) {
     const currentHead = getCurrentHeadCommit(projectDir);
-    if (data.head_commit !== currentHead) {
+    if (currentHead === null) {
+      const msg = `${fileName}: unable to resolve current Git HEAD; evidence identity cannot be verified`;
+      if (isLegacySprint) {
+        warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      } else {
+        errors.push(msg);
+      }
+    } else if (data.head_commit !== currentHead) {
       const msg = `${fileName}: head_commit mismatch — report has "${data.head_commit}", current HEAD is "${currentHead}"`;
       if (isLegacySprint) {
         warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
@@ -189,7 +324,9 @@ function validateEvidence(phase, projectDir) {
         errors.push(msg);
       }
     }
+  }
 
+  if (phase === 4) {
     // spec_hash check (only if specification.yaml exists)
     const specPath = path.join(projectDir, 'specification.yaml');
     if (fs.existsSync(specPath)) {
@@ -205,10 +342,42 @@ function validateEvidence(phase, projectDir) {
     }
   }
 
-  // Phase 2: requirements_hash existence check (full verification in v0.18.0)
   if (phase === 2) {
-    if (typeof data.requirements_hash !== 'string' || data.requirements_hash.length === 0) {
-      const msg = `${fileName}: requirements_hash must be a non-empty string`;
+    if (typeof data.requirements_hash !== 'string' || !/^[a-fA-F0-9]{64}$/.test(data.requirements_hash)) {
+      const msg = `${fileName}: requirements_hash must be a 64-character hexadecimal SHA-256 digest`;
+      if (isLegacySprint) {
+        warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      } else {
+        errors.push(msg);
+      }
+    } else {
+      const computedHash = computeRequirementsHash(data, projectDir);
+      const hashError = computedHash.error || (
+        data.requirements_hash.toLowerCase() !== computedHash.hash
+          ? 'requirements_hash mismatch; regenerate the requirements review from current inputs'
+          : null
+      );
+      if (hashError) {
+        const msg = `${fileName}: ${hashError}`;
+        if (isLegacySprint) {
+          warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+        } else {
+          errors.push(msg);
+        }
+      }
+    }
+    for (const validationError of validateRequirementsExpertEvidence(data)) {
+      const msg = `${fileName}: ${validationError}`;
+      if (isLegacySprint) {
+        warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      } else {
+        errors.push(msg);
+      }
+    }
+
+    const currentHead = getCurrentHeadCommit(projectDir);
+    if (data.head_commit !== currentHead) {
+      const msg = `${fileName}: head_commit mismatch — review has "${data.head_commit}", current HEAD is "${currentHead}"; regenerate the requirements review for the current commit`;
       if (isLegacySprint) {
         warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
       } else {
@@ -240,7 +409,7 @@ function logEvidenceSkip(projectDir, phase, reason) {
     event: 'evidence_skipped',
     phase,
     reason,
-    commit_hash: getCurrentHeadCommit(projectDir),
+    commit_hash: getCurrentHeadCommit(projectDir) ?? 'unknown',
   };
   fs.appendFileSync(path.join(auditDir, 'audit.jsonl'), JSON.stringify(entry) + '\n', 'utf8');
 }
@@ -539,16 +708,25 @@ function checkWalkthrough(projectDir) {
     return { ok: false, errors, warnings };
   }
 
-  // Check commit is ancestor of HEAD
-  if (data.commit) {
-    try {
-      execSync(`git merge-base --is-ancestor ${data.commit} HEAD`, {
-        cwd: projectDir, stdio: 'pipe',
-      });
-    } catch {
-      errors.push(`Code walkthrough commit ${data.commit} is not an ancestor of HEAD`);
+  if (typeof data.commit !== 'string' || !/^[0-9a-f]{7,64}$/i.test(data.commit)) {
+    errors.push('Code walkthrough commit must be a hexadecimal Git commit ID');
+    return { ok: false, errors, warnings };
+  }
+
+  try {
+    const currentCommit = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: projectDir,
+      env: createRepositoryGitEnv(),
+      encoding: 'utf8',
+      stdio: 'pipe',
+    }).trim();
+    if (data.commit !== currentCommit) {
+      errors.push(`Code walkthrough commit ${data.commit} does not match HEAD ${currentCommit}`);
       return { ok: false, errors, warnings };
     }
+  } catch {
+    errors.push('Unable to resolve the current Git commit for code walkthrough validation');
+    return { ok: false, errors, warnings };
   }
 
   // Check expiration
@@ -585,8 +763,10 @@ function checkBypassAudit(projectDir) {
       if (entry.type === 'precommit_bypass' && entry.commit) {
         // Verify the commit is on the current branch
         try {
-          execSync(`git merge-base --is-ancestor ${entry.commit} HEAD`, {
-            cwd: projectDir, stdio: 'pipe',
+          execFileSync('git', ['merge-base', '--is-ancestor', entry.commit, 'HEAD'], {
+            cwd: projectDir,
+            env: createRepositoryGitEnv(),
+            stdio: 'pipe',
           });
           bypassedCommits.push(entry.commit);
         } catch {

package/lib/shared-paths.js

@@ -20,6 +20,7 @@ const CONFIG_DIR = path.join(HOME_DIR, '.config', 'xp-gate');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'xp-gate.json');
 const GLOBAL_HOOKS_DIR = path.join(CONFIG_DIR, 'hooks');
 const GLOBAL_ADAPTERS_DIR = path.join(CONFIG_DIR, 'adapters');
+const GLOBAL_MODULES_DIR = path.join(CONFIG_DIR, 'modules');
 
 /**
  * Detect which AI agent platform is currently in use.
@@ -61,6 +62,7 @@ module.exports = {
   TEMPLATE_DIR,
   GLOBAL_HOOKS_DIR,
   GLOBAL_ADAPTERS_DIR,
+  GLOBAL_MODULES_DIR,
   detectPlatform,
   getTemplateDir,
 };

package/lib/sprint-status.js

@@ -9,7 +9,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const { discoverActiveSprints } = require('./sprint-discovery');
 const { SprintStateManager } = require('./sprint-state-manager');
 
@@ -229,9 +229,20 @@ const FIX_RE = /^(fix(\(.+\))?:)|\b(fix|bugfix|hotfix|patch|修复)\b/i;
  */
 function getFixCommitCount(repoDir, sinceDate) {
   try {
-    const out = execSync(
-      `git log --all --since="${sinceDate}" --pretty=format:"%s"`,
-      { cwd: repoDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    const gitEnv = { ...process.env };
+    for (const name of [
+      'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS',
+      'GIT_CONFIG_COUNT', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE',
+      'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', 'GIT_INDEX_FILE',
+      'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_PREFIX',
+      'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+    ]) {
+      delete gitEnv[name];
+    }
+    const out = execFileSync(
+      'git',
+      ['log', '--all', '--since', sinceDate, '--pretty=format:%s'],
+      { cwd: repoDir, env: gitEnv, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
     );
     return out.split('\n').filter(l => l.trim() && FIX_RE.test(l.trim())).length;
   } catch {