@boyingliu01/xp-gate 0.18.5 → 0.19.1

package/hooks/pre-push

@@ -867,116 +867,47 @@ if [ ! -f "$RESULT_FILE" ]; then
   exit 1
 fi
 
-# Check jq availability (MANDATORY - zero degradation)
-if ! command -v jq &> /dev/null; then
+# Check Node.js availability (MANDATORY - zero degradation)
+if ! command -v node >/dev/null 2>&1; then
   echo ""
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo "   ❌ ENVIRONMENT ERROR - PUSH BLOCKED"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
-  echo "jq is NOT installed. Required for JSON validation."
+  echo "Node.js is NOT installed. Required for JSON validation."
   echo ""
-  echo "Install jq:"
-  echo "  apt-get install jq (Debian/Ubuntu)"
-  echo "  brew install jq (macOS)"
-  echo "  choco install jq (Windows)"
-  echo ""
-  echo "Zero degradation principle: Cannot proceed without jq."
+  echo "Install Node.js 18 or newer, then retry the push."
   echo ""
   exit 1
 fi
 
-# Validate result file content
-# SHA self-reference paradox fix: if the result file was committed as part of
-# HEAD, its content references HEAD^ (the commit being reviewed), not HEAD.
-CURRENT_COMMIT=$(git rev-parse HEAD)
-if git diff-tree --no-commit-id --name-only -r HEAD 2>/dev/null | grep -qx "$RESULT_FILE"; then
-  # Result file is part of the latest commit — compare against the reviewed commit
-  EXPECTED_COMMIT=$(git rev-parse HEAD^ 2>/dev/null || echo "unknown")
-else
-  # Result file is working-tree only — compare against current HEAD
-  EXPECTED_COMMIT="$CURRENT_COMMIT"
-fi
+# Walkthrough evidence must bind to the exact feature-branch HEAD being pushed.
+EXPECTED_COMMIT=$(git rev-parse HEAD)
 
-# Check JSON validity
-if ! jq empty "$RESULT_FILE" 2>/dev/null; then
+# Validate the complete evidence contract without interpolating JSON into shell.
+HOOK_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+MW_VALIDATOR="$HOOK_DIR/lib/validate-code-walkthrough.cjs"
+if [ ! -f "$MW_VALIDATOR" ]; then
   echo ""
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo "   ❌ RESULT FILE INVALID - PUSH BLOCKED"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
-  echo "$RESULT_FILE is not valid JSON."
+  echo "Gate MW validator is missing: $MW_VALIDATOR"
   echo ""
   echo "Re-run: /delphi-review --mode code-walkthrough"
   echo ""
   exit 1
 fi
 
-RESULT_COMMIT=$(jq -r '.commit' "$RESULT_FILE")
-RESULT_VERDICT=$(jq -r '.verdict' "$RESULT_FILE")
-RESULT_EXPIRES=$(jq -r '.expires' "$RESULT_FILE")
-RESULT_BRANCH=$(jq -r '.branch' "$RESULT_FILE")
 CURRENT_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-# Branch match check (optional but recommended)
-if [ "$RESULT_BRANCH" != "$CURRENT_BRANCH" ]; then
-  echo ""
-  echo "⚠️ WARNING: Result file is for different branch"
-  echo "  Expected: $CURRENT_BRANCH"
-  echo "  Found: $RESULT_BRANCH"
-  echo ""
-  echo "Proceeding with commit verification..."
-fi
-
-# Commit match check
-if [ "$RESULT_COMMIT" != "$EXPECTED_COMMIT" ]; then
+if ! VALIDATION_ERROR=$(node "$MW_VALIDATOR" "$RESULT_FILE" "$EXPECTED_COMMIT" "$CURRENT_BRANCH" "$CURRENT_TIME" 2>&1); then
   echo ""
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo "   ❌ RESULT FILE OUTDATED - PUSH BLOCKED"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
-  echo "Result file is for a different commit:"
-    echo "  Expected: $EXPECTED_COMMIT"
-    echo "  Found: $RESULT_COMMIT"
-  echo ""
-  echo "Re-run: /delphi-review --mode code-walkthrough"
-  echo ""
-  exit 1
-fi
-
-# Verdict check
-if [ "$RESULT_VERDICT" != "APPROVED" ]; then
-  echo ""
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo "   ❌ GATE MW: CODE WALKTHROUGH NOT APPROVED - PUSH BLOCKED"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-  echo "Verdict: $RESULT_VERDICT"
-  echo ""
-  
-  # Show issues if available
-  ISSUES=$(jq -r '.issues[] | "- [\(.severity)] \(.description)"' "$RESULT_FILE" 2>/dev/null)
-  if [ -n "$ISSUES" ]; then
-    echo "Issues found:"
-    echo "$ISSUES"
-    echo ""
-  fi
-  
-  echo "Fix issues and re-run: /delphi-review --mode code-walkthrough"
-  echo ""
-  exit 1
-fi
-
-# Expiration check
-if [[ "$CURRENT_TIME" > "$RESULT_EXPIRES" ]]; then
-  echo ""
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo "   ❌ RESULT FILE EXPIRED - PUSH BLOCKED"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-  echo "Code walkthrough result has expired:"
-  echo "  Expired: $RESULT_EXPIRES"
-  echo "  Current: $CURRENT_TIME"
+  echo "$VALIDATION_ERROR"
   echo ""
   echo "Re-run: /delphi-review --mode code-walkthrough"
   echo ""
@@ -996,16 +927,9 @@ echo "Files changed: $FILES_CHANGED"
 echo "Lines: +$LINES_ADDED -$LINES_DELETED"
 echo ""
 echo "Code walkthrough result:"
-echo "  Commit: $RESULT_COMMIT"
+echo "  Commit: $EXPECTED_COMMIT"
 echo "  Verdict: APPROVED"
-echo "  Expires: $RESULT_EXPIRES"
-
-# Show confidence if available
-CONFIDENCE=$(jq -r '.confidence' "$RESULT_FILE" 2>/dev/null)
-if [ -n "$CONFIDENCE" ] && [ "$CONFIDENCE" != "null" ]; then
-  echo "  Confidence: $CONFIDENCE/10"
-fi
 
 echo ""
 echo "Proceeding with push..."
-exit 0
+exit 0

package/lib/__tests__/check-version.test.js

@@ -25,20 +25,58 @@ function cleanupDir(dir) {
 describe('check-version.js — REQ-001-01', () => {
   let mod;
   let origHome;
+  let origCacheDir;
   let tmpHome;
+  let tmpCacheDir;
   let origReadFileSync;
+  let origHttpsGet;
+
+  function installFakeHttpsGet(latestVersion) {
+    const https = require('https');
+    const saved = https.get;
+    https.get = (_url, options, callbackArg) => {
+      const callback = typeof options === 'function' ? options : callbackArg;
+      if (!callback) return { on: () => undefined, destroy: () => undefined };
+      const response = {
+        statusCode: 200,
+        on: (event, handler) => {
+          const eventArgs = {
+            data: [JSON.stringify({ latest: latestVersion })],
+            end: [],
+          };
+          if (Object.hasOwn(eventArgs, event)) handler(...eventArgs[event]);
+          return response;
+        },
+      };
+      callback(response);
+      return { on: () => undefined, destroy: () => undefined };
+    };
+    return () => {
+      https.get = saved;
+    };
+  }
 
   beforeEach(() => {
     vi.resetModules();
     origHome = process.env.HOME;
-    tmpHome = fakeHome();
+    origCacheDir = process.env.XP_GATE_CACHE_DIR;
     origReadFileSync = fs.readFileSync;
+    origHttpsGet = require('https').get;
+    tmpHome = undefined;
+    tmpCacheDir = undefined;
+    tmpHome = fakeHome();
+    tmpCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ckv-cache-'));
+    process.env.XP_GATE_CACHE_DIR = tmpCacheDir;
   });
 
   afterEach(() => {
     process.env.HOME = origHome;
+    if (origCacheDir === undefined) delete process.env.XP_GATE_CACHE_DIR;
+    else process.env.XP_GATE_CACHE_DIR = origCacheDir;
     cleanupDir(tmpHome);
-    fs.readFileSync = origReadFileSync;
+    cleanupDir(tmpCacheDir);
+    if (origReadFileSync) fs.readFileSync = origReadFileSync;
+    if (origHttpsGet) require('https').get = origHttpsGet;
   });
 
   // ──────────────────────────────────────────
@@ -159,6 +197,14 @@ describe('check-version.js — REQ-001-01', () => {
       expect(() => mod.clearCache()).not.toThrow();
     });
 
+    it('does not touch the home-directory cache when XP_GATE_CACHE_DIR is set', () => {
+      const homeCache = path.join(tmpHome, '.xp-gate', 'version-cache.json');
+      fs.mkdirSync(path.dirname(homeCache), { recursive: true });
+      fs.writeFileSync(homeCache, 'sentinel');
+      mod.clearCache();
+      expect(fs.readFileSync(homeCache, 'utf8')).toBe('sentinel');
+    });
+
     it('cachePath returns null when XP_GATE_DIR is inaccessible', () => {
       // Verify clearCache handles null cachePath gracefully
       expect(() => mod.clearCache()).not.toThrow();
@@ -216,31 +262,14 @@ describe('check-version.js — REQ-001-01', () => {
       delete require.cache[resolved];
     }
 
-    function withMockedHttps(latestVersion, fn) {
+    async function withMockedHttps(latestVersion, fn) {
       const fsm = require('fs');
-      const osm = require('os');
-      const cpPath = require('path').join(osm.homedir(), '.xp-gate', 'version-cache.json');
+      const cpPath = require('path').join(process.env.XP_GATE_CACHE_DIR, 'version-cache.json');
       if (fsm.existsSync(cpPath)) {
         try { fsm.unlinkSync(cpPath); } catch { }
       }
       evictCache();
-      const https = require('https');
-      const saved = https.get;
-      const body = JSON.stringify({ latest: latestVersion });
-      https.get = (_url, _opts, cb) => {
-        const callback = typeof _opts === 'function' ? _opts : cb;
-        if (!callback) return { on: () => undefined, destroy: () => undefined };
-        const mockRes = {
-          statusCode: 200,
-          on: (evt, handler) => {
-            if (evt === 'data') handler(body);
-            if (evt === 'end') handler();
-            return mockRes;
-          },
-        };
-        callback(mockRes);
-        return { on: () => undefined, destroy: () => undefined };
-      };
+      const restoreHttpsGet = installFakeHttpsGet(latestVersion);
       // Mock getLocalVersion to return a fixed version so tests don't
       // depend on the real package.json version (which drifts over time).
       const savedReadFileSync = fsm.readFileSync;
@@ -256,9 +285,9 @@ describe('check-version.js — REQ-001-01', () => {
       };
       try {
         const m = require('../check-version');
-        return fn(m);
+        return await fn(m);
       } finally {
-        https.get = saved;
+        restoreHttpsGet();
         fsm.readFileSync = savedReadFileSync;
       }
     }
@@ -301,39 +330,31 @@ describe('check-version.js — REQ-001-01', () => {
       delete require.cache[resolved];
     }
 
-    function withMockedHttpsBox(latestVersion, fn) {
+    async function withMockedHttpsBox(latestVersion, fn) {
       const fsm = require('fs');
-      const osm = require('os');
-      const cpPath = require('path').join(osm.homedir(), '.xp-gate', 'version-cache.json');
+      const cpPath = require('path').join(process.env.XP_GATE_CACHE_DIR, 'version-cache.json');
       if (fsm.existsSync(cpPath)) {
         try { fsm.unlinkSync(cpPath); } catch { }
       }
       evictCache();
-      const https = require('https');
-      const saved = https.get;
-      const body = JSON.stringify({ latest: latestVersion });
-      https.get = (_url, _opts, cb) => {
-        const callback = typeof _opts === 'function' ? _opts : cb;
-        if (!callback) return { on: () => undefined, destroy: () => undefined };
-        const mockRes = {
-          statusCode: 200,
-          on: (evt, handler) => {
-            if (evt === 'data') handler(body);
-            if (evt === 'end') handler();
-            return mockRes;
-          },
-        };
-        callback(mockRes);
-        return { on: () => undefined, destroy: () => undefined };
-      };
+      const restoreHttpsGet = installFakeHttpsGet(latestVersion);
       try {
         const m = require('../check-version');
-        return fn(m, cpPath);
+        return await fn(m, cpPath);
       } finally {
-        https.get = saved;
+        restoreHttpsGet();
       }
     }
 
+    it('restores HTTPS after an asynchronous callback rejects', async () => {
+      const savedGet = require('https').get;
+      await expect(withMockedHttpsBox('0.18.0', async () => {
+        await Promise.resolve();
+        throw new Error('callback failed');
+      })).rejects.toThrow('callback failed');
+      expect(require('https').get).toBe(savedGet);
+    });
+
     it('rejects null version from registry — cache NOT written', async () => {
       await withMockedHttpsBox(null, async (m, cpPath) => {
         const r = await m.getRemoteVersion('@test/pkg');

package/lib/__tests__/doctor.test.js

@@ -66,7 +66,7 @@ describe('doctor', () => {
     // and reloading it would restore the full tool list, breaking the test mock setup.
     const modulesToInvalidate = [
       '../doctor', '../uninstall', '../init', '../shared-paths',
-      '../check-version.js',
+      '../check-version.js', '../doctor-tui',
     ];
     for (const mod of modulesToInvalidate) {
       try { delete require.cache[require.resolve(mod)]; } catch { /* first load */ }
@@ -126,7 +126,7 @@ describe('doctor', () => {
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(
       path.join(dir, 'pre-push'),
-      '#!/bin/bash\n# Pre-push Hook - Code Walkthrough Result Validator\n'
+      '#!/bin/bash\n# Pre-push Hook — 8 gates:\n'
     );
   }
 
@@ -148,7 +148,7 @@ describe('doctor', () => {
       path.join(dir, 'adapters', 'python.sh'),
       '#!/usr/bin/env bash\necho "py adapter"\n'
     );
-    const gateScripts = ['gate-3.sh', 'gate-4.sh', 'gate-7.sh', 'gate-8.sh', 'gate-9.sh'];
+    const gateScripts = ['gate-3.sh', 'gate-4.sh', 'gate-7.sh', 'gate-8.sh', 'gate-9.sh', 'gate-10.sh'];
     for (const script of gateScripts) {
       fs.writeFileSync(path.join(dir, 'adapters', script), `#!/bin/bash\n# ${script}\n`);
     }
@@ -187,7 +187,7 @@ describe('doctor', () => {
     fs.mkdirSync(globalAdaptersDir(), { recursive: true });
     fs.writeFileSync(path.join(globalAdaptersDir(), 'typescript.sh'), '#!/usr/bin/env bash\necho "ts adapter"\n');
     fs.writeFileSync(path.join(globalAdaptersDir(), 'python.sh'), '#!/usr/bin/env bash\necho "py adapter"\n');
-    const gateScripts = ['gate-3.sh', 'gate-4.sh', 'gate-7.sh', 'gate-8.sh', 'gate-9.sh'];
+    const gateScripts = ['gate-3.sh', 'gate-4.sh', 'gate-7.sh', 'gate-8.sh', 'gate-9.sh', 'gate-10.sh'];
     for (const script of gateScripts) {
       fs.writeFileSync(path.join(globalAdaptersDir(), script), `#!/bin/bash\n# ${script}\n`);
     }
@@ -941,7 +941,7 @@ describe('doctor', () => {
 
   function createGateScripts(dir) {
     fs.mkdirSync(dir, { recursive: true });
-    const gateScripts = ['gate-3.sh', 'gate-4.sh', 'gate-7.sh', 'gate-8.sh', 'gate-9.sh'];
+    const gateScripts = ['gate-3.sh', 'gate-4.sh', 'gate-7.sh', 'gate-8.sh', 'gate-9.sh', 'gate-10.sh'];
     for (const script of gateScripts) {
       fs.writeFileSync(path.join(dir, script), `#!/bin/bash\n# ${script}\n`);
     }
@@ -962,7 +962,7 @@ describe('doctor', () => {
       expect.stringContaining('Gate scripts')
     );
     expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('5 gate script(s)')
+      expect.stringContaining('6 gate script(s)')
     );
   });
 
@@ -1005,6 +1005,7 @@ describe('doctor', () => {
     expect(fs.existsSync(path.join(projectAdaptersDir(), 'gate-7.sh'))).toBe(true);
     expect(fs.existsSync(path.join(projectAdaptersDir(), 'gate-8.sh'))).toBe(true);
     expect(fs.existsSync(path.join(projectAdaptersDir(), 'gate-9.sh'))).toBe(true);
+    expect(fs.existsSync(path.join(projectAdaptersDir(), 'gate-10.sh'))).toBe(true);
     expect(logSpy).toHaveBeenCalledWith(
       expect.stringContaining('Restored')
     );

package/lib/__tests__/gate-runner.test.js

@@ -0,0 +1,267 @@
+/**
+ * @test REQ-standalone-gates gate-runner.js
+ * @intent 验证 runGateAdapter 独立运行 gate 适配器片段时能提供钩子上下文
+ * （gate_start_ms / record_gate_audit / now_ms / PROJECT_LANG / CHANGED_FILES），
+ * 避免 "command not found" 误报。
+ * @covers AC-STANDALONE-GATES-01, AC-STANDALONE-GATES-02, AC-STANDALONE-GATES-03, AC-STANDALONE-GATES-04, AC-STANDALONE-GATES-05
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+let tmpProject;
+let tmpAdapters;
+
+beforeEach(() => {
+  tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), 'xpgate-runner-'));
+  tmpAdapters = path.join(tmpProject, 'githooks', 'adapters');
+  fs.mkdirSync(tmpAdapters, { recursive: true });
+});
+
+afterEach(() => {
+  if (tmpProject && fs.existsSync(tmpProject)) {
+    fs.rmSync(tmpProject, { recursive: true, force: true });
+  }
+});
+
+function writeAdapterCommon() {
+  fs.writeFileSync(
+    path.join(tmpAdapters, 'adapter-common.sh'),
+    'detect_project_lang() { echo "typescript"; }'
+  );
+}
+
+function writeGateFragment(fragmentLines) {
+  fs.writeFileSync(
+    path.join(tmpAdapters, 'gate-9.sh'),
+    ['# gate-9 fragment', ...fragmentLines, 'exit 0'].join('\n')
+  );
+}
+
+function shellParameter(expression) {
+  return ['$', '{', expression, '}'].join('');
+}
+
+function initializeGitProject() {
+  execFileSync('git', ['init', '-q'], { cwd: tmpProject });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: tmpProject });
+  execFileSync('git', ['config', 'user.name', 'XP-Gate Test'], { cwd: tmpProject });
+  fs.writeFileSync(path.join(tmpProject, 'tracked.ts'), 'const value = 1;\n');
+  execFileSync('git', ['add', 'tracked.ts'], { cwd: tmpProject });
+  execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'commit', '-qm', 'initial'], {
+    cwd: tmpProject,
+  });
+}
+
+// Runs runGateAdapter in a child node process (worker threads forbid process
+// chdir, and runGateAdapter execs bash), capturing stdout/exit status.
+function runChildAdapter(gateRunnerAbsPath, fragmentPath, cwd = tmpProject) {
+  const script = [
+    `const { runGateAdapter } = require(${JSON.stringify(gateRunnerAbsPath)});`,
+    `runGateAdapter(${JSON.stringify(fragmentPath)}, ${JSON.stringify(cwd)});`,
+    "console.log('__ADAPTER_DONE__');",
+  ].join('\n');
+  try {
+    const stdout = execFileSync(process.execPath, ['-e', script], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 30000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { status: 0, stdout };
+  } catch (err) {
+    return { status: err.status ?? 1, stdout: (err.stdout || '').toString() };
+  }
+}
+
+describe('gate-runner.js — runGateAdapter', () => {
+  it('sources the fragment with hook helpers available (REQ-standalone-gates-01)', () => {
+    const runnerAbsPath = path.resolve(__dirname, '../gate-runner.js');
+    writeAdapterCommon();
+    writeGateFragment([
+      'USES_START=$(gate_start_ms)',
+      `if [ -z "${shellParameter('PROJECT_LANG:-')}" ]; then exit 99; fi`,
+      `if [ -z "${shellParameter('CHANGED_FILES+x')}" ]; then exit 98; fi`,
+      'record_gate_audit "gate-9" "sast" "PASS" "0" "$USES_START"',
+    ]);
+    const fragPath = path.join(tmpAdapters, 'gate-9.sh');
+    const { status, stdout } = runChildAdapter(runnerAbsPath, fragPath);
+    expect(status).toBe(0);
+    expect(stdout).toContain('__ADAPTER_DONE__');
+  }, 30000);
+
+  it('defines now_ms/gate_start_ms/record_gate_audit/PROJECT_LANG/CHANGED_FILES before sourcing (REQ-standalone-gates-02)', () => {
+    const runnerAbsPath = path.resolve(__dirname, '../gate-runner.js');
+    writeAdapterCommon();
+    writeGateFragment([
+      'if ! command -v gate_start_ms >/dev/null 2>&1; then exit 97; fi',
+      'if ! command -v record_gate_audit >/dev/null 2>&1; then exit 96; fi',
+      'if ! command -v now_ms >/dev/null 2>&1; then exit 95; fi',
+      `if [ -z "${shellParameter('PROJECT_LANG:-')}" ]; then exit 94; fi`,
+      `if [ -z "${shellParameter('CHANGED_FILES+x')}" ]; then exit 93; fi`,
+    ]);
+    const fragPath = path.join(tmpAdapters, 'gate-9.sh');
+    const { status, stdout } = runChildAdapter(runnerAbsPath, fragPath);
+    expect(status).toBe(0);
+    expect(stdout).toContain('__ADAPTER_DONE__');
+  }, 30000);
+
+  it('sources adapter-common.sh to provide detect_project_lang (REQ-standalone-gates-03)', () => {
+    const runnerAbsPath = path.resolve(__dirname, '../gate-runner.js');
+    writeAdapterCommon();
+    writeGateFragment([
+      `if [ "${shellParameter('PROJECT_LANG:-')}" != "typescript" ]; then exit 92; fi`,
+    ]);
+    const fragPath = path.join(tmpAdapters, 'gate-9.sh');
+    const { status, stdout } = runChildAdapter(runnerAbsPath, fragPath);
+    expect(status).toBe(0);
+    expect(stdout).toContain('__ADAPTER_DONE__');
+  }, 30000);
+
+  it('propagates changed files from the project git working tree (REQ-standalone-gates-04)', () => {
+    const runnerAbsPath = path.resolve(__dirname, '../gate-runner.js');
+    writeAdapterCommon();
+    initializeGitProject();
+    fs.writeFileSync(path.join(tmpProject, 'tracked.ts'), 'const value = 2;\n');
+    writeGateFragment([
+      `if [ "${shellParameter('CHANGED_FILES')}" != "tracked.ts" ]; then exit 91; fi`,
+    ]);
+
+    const fragPath = path.join(tmpAdapters, 'gate-9.sh');
+    const { status, stdout } = runChildAdapter(runnerAbsPath, fragPath);
+
+    expect(status).toBe(0);
+    expect(stdout).toContain('__ADAPTER_DONE__');
+  }, 30000);
+
+  it('runs a standalone gate bash fallback through the public CLI (REQ-standalone-gates-05)', () => {
+    const packageFixture = path.join(tmpProject, 'package');
+    fs.cpSync(path.resolve(__dirname, '../..'), packageFixture, { recursive: true });
+    const cliPath = path.join(packageFixture, 'bin', 'xp-gate.js');
+    const gatesDir = path.join(tmpProject, 'githooks', 'gates');
+    fs.mkdirSync(gatesDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(gatesDir, 'gate-9-public-fallback.sh'),
+      [
+        'if ! command -v gate_start_ms >/dev/null 2>&1; then exit 90; fi',
+        `if [ -z "${shellParameter('CHANGED_FILES+x')}" ]; then exit 89; fi`,
+        'echo "__PUBLIC_FALLBACK__"',
+      ].join('\n')
+    );
+
+    const result = spawnSync(process.execPath, [cliPath, 'check', '9'], {
+      cwd: tmpProject,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('__PUBLIC_FALLBACK__');
+  }, 30000);
+
+  it('isolates fallback resolution and git context to the requested target path (REQ-standalone-gates-06)', () => {
+    const packageFixture = path.join(tmpProject, 'package');
+    const callerProject = path.join(tmpProject, 'caller');
+    const targetProject = path.join(tmpProject, 'target');
+    fs.cpSync(path.resolve(__dirname, '../..'), packageFixture, { recursive: true });
+    fs.mkdirSync(path.join(callerProject, 'githooks', 'gates'), { recursive: true });
+    fs.mkdirSync(path.join(targetProject, 'githooks', 'gates'), { recursive: true });
+    fs.writeFileSync(
+      path.join(callerProject, 'githooks', 'gates', 'gate-9-caller.sh'),
+      'echo "__CALLER_REPO__"\n'
+    );
+    fs.writeFileSync(
+      path.join(targetProject, 'githooks', 'gates', 'gate-9-target.sh'),
+      [
+        'if [ "$PWD" != "$EXPECTED_TARGET" ]; then exit 88; fi',
+        'echo "__TARGET_REPO__"',
+      ].join('\n')
+    );
+
+    const result = spawnSync(
+      process.execPath,
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9', targetProject],
+      {
+        cwd: callerProject,
+        env: { ...process.env, EXPECTED_TARGET: targetProject },
+        encoding: 'utf8',
+        timeout: 30000,
+      }
+    );
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('__TARGET_REPO__');
+    expect(result.stdout).not.toContain('__CALLER_REPO__');
+  }, 30000);
+
+  it('sources fragment and helper paths containing shell metacharacters literally (REQ-standalone-gates-07)', () => {
+    const runnerAbsPath = path.resolve(__dirname, '../gate-runner.js');
+    const hostileRoot = path.join(tmpProject, 'space $HOME `marker` "quoted"');
+    tmpAdapters = path.join(hostileRoot, 'githooks', 'adapters');
+    fs.mkdirSync(tmpAdapters, { recursive: true });
+    writeAdapterCommon();
+    writeGateFragment([
+      `if [ "${shellParameter('PROJECT_LANG')}" != "typescript" ]; then exit 87; fi`,
+      'echo "__HOSTILE_PATH_OK__"',
+    ]);
+
+    const result = runChildAdapter(
+      runnerAbsPath,
+      path.join(tmpAdapters, 'gate-9.sh'),
+      hostileRoot
+    );
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('__HOSTILE_PATH_OK__');
+  }, 30000);
+
+  it('loads parent-layout adapter-common and packaged now-ms through the public CLI (REQ-standalone-gates-08)', () => {
+    const packageFixture = path.join(tmpProject, 'package');
+    fs.cpSync(path.resolve(__dirname, '../..'), packageFixture, { recursive: true });
+    const gatesDir = path.join(tmpProject, 'githooks', 'gates');
+    fs.mkdirSync(gatesDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpProject, 'githooks', 'adapter-common.sh'),
+      'detect_project_lang() { echo "parent-layout-language"; }\n'
+    );
+    fs.writeFileSync(
+      path.join(gatesDir, 'gate-9-parent-helper.sh'),
+      [
+        `if [ "${shellParameter('PROJECT_LANG')}" != "parent-layout-language" ]; then exit 86; fi`,
+        'if [ "$(now_ms)" != "424242" ]; then exit 85; fi',
+        'echo "__PARENT_HELPER_OK__"',
+      ].join('\n')
+    );
+    fs.writeFileSync(
+      path.join(packageFixture, 'hooks', 'lib', 'now-ms.sh'),
+      'now_ms() { echo 424242; }\n'
+    );
+
+    const result = spawnSync(
+      process.execPath,
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9'],
+      { cwd: tmpProject, encoding: 'utf8', timeout: 30000 }
+    );
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('__PARENT_HELPER_OK__');
+  }, 30000);
+
+  it('propagates a failing fragment exit through the public CLI (REQ-standalone-gates-09)', () => {
+    const packageFixture = path.join(tmpProject, 'package');
+    const targetProject = path.join(tmpProject, 'failing-target');
+    fs.cpSync(path.resolve(__dirname, '../..'), packageFixture, { recursive: true });
+    const gatesDir = path.join(targetProject, 'githooks', 'gates');
+    fs.mkdirSync(gatesDir, { recursive: true });
+    fs.writeFileSync(path.join(gatesDir, 'gate-9-failure.sh'), 'exit 23\n');
+
+    const result = spawnSync(
+      process.execPath,
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9', targetProject],
+      { cwd: tmpProject, encoding: 'utf8', timeout: 30000 }
+    );
+
+    expect(result.status).toBe(1);
+  }, 30000);
+});