@boyingliu01/xp-gate 0.35.14 → 0.35.16

package/bin/xp-gate.js

@@ -617,16 +617,38 @@ function printAnomalies(a, since) {
  * CI gate: exit 1 when the audit ledger carries anomalies (implausible
  * durations or unattributed commits). This turns both telemetry bugs into a
  * build failure instead of something a human has to notice in a chart.
+ *
+ * `--ledger <path>` grades that file instead of `<cwd>/.xp-gate/audit.jsonl`.
+ * CI needs it: the BATS suites run before this check and execute the real hook
+ * from the repo root, so the live ledger contains fixture rows that were never
+ * given a commit hash. Grading them as "unattributed commits" reports a
+ * test-isolation problem as a telemetry bug -- and the CI step's job is the
+ * committed ledger, not the scratch one the tests left behind.
  */
-function handleAuditCheck(auditPath) {
+function handleAuditCheck(args = []) {
   try {
-    const { computeAnomalies, AUDIT_ANOMALY_SINCE } = require(auditPath);
+    const ledgerIdx = args.indexOf('--ledger');
+    let repoRoot = process.cwd();
+    if (ledgerIdx !== -1 && args[ledgerIdx + 1]) {
+      // computeAnomalies() reads <repoRoot>/.xp-gate/audit.jsonl, so point it at
+      // a directory whose .xp-gate/audit.jsonl is the file we were asked about.
+      // A temp dir keeps the caller's tree untouched.
+      const ledgerPath = path.resolve(args[ledgerIdx + 1]);
+      if (!require('node:fs').existsSync(ledgerPath)) {
+        console.error(`Error: --ledger file not found: ${ledgerPath}`);
+        process.exit(1);
+      }
+      repoRoot = require('node:fs').mkdtempSync(path.join(require('node:os').tmpdir(), 'xpg-ledger-'));
+      require('node:fs').mkdirSync(path.join(repoRoot, '.xp-gate'), { recursive: true });
+      require('node:fs').copyFileSync(ledgerPath, path.join(repoRoot, '.xp-gate', 'audit.jsonl'));
+    }
     // Scope to entries after the fix: historical anomalies are grandfathered
     // (they cannot be re-measured). A future epoch/blank row fails the build.
-    const a = computeAnomalies(process.cwd(), AUDIT_ANOMALY_SINCE);
-    printAnomalies(a, AUDIT_ANOMALY_SINCE);
+    const since = evalGateAuditModule('m.AUDIT_ANOMALY_SINCE');
+    const a = evalGateAuditModule(`m.computeAnomalies(${JSON.stringify(repoRoot)}, ${JSON.stringify(since)})`);
+    printAnomalies(a, since);
     if (a.total > 0) {
-      console.error(`FAIL: ${a.total} audit anomal${a.total === 1 ? 'y' : 'ies'} found since ${AUDIT_ANOMALY_SINCE} (must be 0).`);
+      console.error(`FAIL: ${a.total} audit anomal${a.total === 1 ? 'y' : 'ies'} found since ${since} (must be 0).`);
       process.exit(1);
     }
     console.log('OK: no new audit anomalies.');
@@ -665,6 +687,45 @@ function handleAuditRecord(args, auditPath) {
   }
 }
 
+/**
+ * Evaluate `lib/gate-audit.ts` under tsx and return whatever the little script
+ * writes to stdout, JSON-decoded.
+ *
+ * `gate-audit.ts` is TypeScript, and Node cannot `require()` a `.ts` file -- so
+ * every `xp-gate audit` subcommand used to die on
+ *
+ *     Error checking audit health: require is not defined in ES module scope
+ *
+ * (that message is Node trying to interpret the .ts file as ESM). `--tail`,
+ * `--stats`, `--check` and `record` were ALL unusable, and it stayed invisible
+ * because nothing automated called them: CI's Gate 5c runs
+ * `xp-gate audit --check || npx tsx ... audit --check`, so the npx fallback is
+ * what actually ran and the broken path was never exercised.
+ *
+ * Per this package's own convention (AGENTS.md: these `.ts` lib files are
+ * "loaded via npx tsx on demand", never compiled at install time), evaluate the
+ * module in a child process under tsx. The caller supplies the expression, and
+ * all values travel as JSON so nothing is ever interpolated into code.
+ *
+ * @param {string} expr an expression evaluated with `m` bound to the module
+ * @returns {*} the JSON-decoded result
+ */
+function evalGateAuditModule(expr) {
+  const { execFileSync } = require('node:child_process');
+  const modulePath = path.join(__dirname, '..', 'lib', 'gate-audit.ts');
+  const tsxCli = path.join(__dirname, '..', '..', '..', 'node_modules', 'tsx', 'dist', 'cli.mjs');
+  const script = [
+    `import * as m from ${JSON.stringify(modulePath)};`,
+    `process.stdout.write(JSON.stringify(${expr}));`,
+  ].join('\n');
+  const raw = execFileSync(process.execPath, [tsxCli, '--eval', script], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    timeout: 120000,
+  });
+  return JSON.parse(raw);
+}
+
 function handleAudit(args) {
   const auditPath = path.join(__dirname, '..', 'lib', 'gate-audit.ts');
 
@@ -679,7 +740,7 @@ function handleAudit(args) {
   }
 
   if (args.includes('--check')) {
-    handleAuditCheck(auditPath);
+    handleAuditCheck(args);
     return;
   }
 

package/gates/gate-9.ts

@@ -10,6 +10,27 @@ import {
   getChangedFiles, detectProjectLang,
 } from './common';
 
+// The semgrep ruleset, in ONE place (#640). It appears in the scan invocation and in
+// two messages that tell the user which command to re-run by hand; three copies of a
+// string that decides what gets scanned is a drift waiting to happen.
+export const SEMGREP_RULESET = 'p/security-audit';
+
+/**
+ * Fixed flags every Gate 9 semgrep run carries (#640).
+ *
+ * `--metrics=off` is the important one. Semgrep's usage upload is pure overhead for
+ * a gate: it reports statistics to the registry and contributes nothing to the
+ * verdict. Measured on one file on this machine, twice each way: 11.7s / 17.2s with
+ * metrics, 4.7s / 4.9s without -- a 58-72% cut on a gate whose actual scan work is
+ * a fraction of a second (#640 measured 0.45s of work inside 30.8s of wall time).
+ * The privacy answer is the same shape: a quality gate should not phone home about
+ * the files it just read.
+ *
+ * `--disable-version-check` removes the second network round trip. Neither flag
+ * touches the JSON on stdout, which is what carries the verdict (#518).
+ */
+export const SEMGREP_EXTRA_ARGS = ['--disable-version-check', '--metrics=off'] as const;
+
 export function runGate9(input: GateInput): GateOutput {
   const startMs = Date.now();
   const messages: string[] = [];
@@ -27,7 +48,7 @@ export function runGate9(input: GateInput): GateOutput {
   if (!tool.available) {
     messages.push('     ⚠️  WARN - semgrep not installed — SAST scanning unavailable');
     messages.push('     Install: brew install semgrep (macOS) | pip install semgrep (Linux/Windows)');
-    messages.push('     Pre-cache rules: semgrep --config=p/security-audit');
+    messages.push('     Pre-cache rules: semgrep --config=' + SEMGREP_RULESET);
     messages.push('     Gate 9: SAST Security (WARN, semgrep not installed)');
     recordAudit('gate-9', 'sast-security', 'WARN', 0, startMs);
     return { status: 'WARN', messages, exitCode: 0 };
@@ -44,8 +65,9 @@ export function runGate9(input: GateInput): GateOutput {
     return { status: 'SKIP', messages, exitCode: 0 };
   }
 
-  // Run semgrep with JSON output
-  semgrepArgs.push('scan', '--config=p/security-audit', '--json', '--disable-version-check', ...semgrepFiles);
+  // Run semgrep with JSON output. Fixed overhead per run is the point of #640 --
+  // see SEMGREP_EXTRA_ARGS.
+  semgrepArgs.push('scan', `--config=${SEMGREP_RULESET}`, '--json', ...SEMGREP_EXTRA_ARGS, ...semgrepFiles);
 
   const result = runTool(semgrepCmd, semgrepArgs, { cwd: input.cwd });
 
@@ -125,7 +147,7 @@ function renderSemgrepBlock(
   messages.push('  ❌ BLOCKED — blocking-severity vulnerability found');
   messages.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   messages.push(...findingLines);
-  messages.push("  Run 'semgrep scan --config=p/security-audit' to review all findings.");
+  messages.push(`  Run 'semgrep scan --config=${SEMGREP_RULESET}' to review all findings.`);
   recordAudit('gate-9', 'sast-security', 'FAIL', blocking, startMs);
   return { status: 'FAIL', messages, exitCode: 1 };
 }

package/hooks/pre-commit

@@ -851,18 +851,32 @@ done
 has_version_change=false
 has_changelog_change=false
 
+# #640: a fork costs ~90ms on Windows (measured: 100 `git rev-parse` = 9456ms),
+# and this exact query is re-run by later gates. Cache it once; consumers below
+# read $XP_STAGED_ACM. Subprocess COUNT, not scan duration, is the bottleneck.
+#
+# Computed HERE, once, and outside the protected-branch test below. It used to
+# live inside that test, which meant the variable was only ever assigned when
+# committing to master/main/develop/trunk/mainline. On a feature branch -- where
+# essentially all work happens, and where CI fixtures commit -- it stayed EMPTY,
+# and every #640 consumer that asks "did this commit touch a source file?" then
+# matched nothing:
+#   - Gate 6 skipped archlint on every feature-branch commit that DID change
+#     source ("no source files changed"), silently dropping the architecture
+#     check;
+#   - Gate 0's own hint fired as though nothing were staged.
+# A cache that is only warm on some branches is not a cache, it is a branch-wide
+# behaviour difference. Assign it before anything can branch.
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+XP_STAGED_ACM="$STAGED_FILES"
+export XP_STAGED_ACM
+
 if [ "$is_protected" = "true" ]; then
   # Env var bypass: SKIP_VERSION_CHECK=1 skips Gate 0 entirely
   # Useful for: SKIP_VERSION_CHECK=1 git commit -m "chore: ..."
   if [ "${SKIP_VERSION_CHECK:-}" = "1" ]; then
     echo "⏭️  SKIPPED - Gate 0: Version consistency (SKIP_VERSION_CHECK=1 env var)"
   else
-  # Check if staged changes include VERSION or CHANGELOG.md
-  STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
-  # #640: a fork costs ~90ms on Windows (measured: 100 `git rev-parse` = 9456ms),
-  # and this exact query is re-run by later gates. Cache it once; consumers below
-  # read $XP_STAGED_ACM. Subprocess COUNT, not scan duration, is the bottleneck.
-  XP_STAGED_ACM="$STAGED_FILES"
   for file in $STAGED_FILES; do
     case "$file" in
       VERSION) has_version_change=true ;;
@@ -2450,7 +2464,7 @@ else
   GATE_5_DELETED_TESTS=""
   if declare -f classify_test_focus >/dev/null 2>&1; then
     STAGED_TEST_FILES=$(printf '%s\n' "${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null)}" \
-      | grep -E '\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|cs|scala|ps1)$|(^|/)(test_[^/]*\.py|[^/]*_test\.(py|go))$' || true)
+      | filter_project_paths | grep -E '\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|cs|scala|ps1)$|(^|/)(test_[^/]*\.py|[^/]*_test\.(py|go))$' || true)
     if [ -n "$STAGED_TEST_FILES" ]; then
       while IFS= read -r _tf; do
         [ -n "$_tf" ] || continue
@@ -2570,8 +2584,11 @@ else
       # --- deleted test files: WARN ---
       DELETED_LIST=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/xp-deleted-$$")
       ADDED_LIST=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/xp-added-$$")
-      git diff --cached --name-only --diff-filter=D > "$DELETED_LIST" 2>/dev/null || true
-      git diff --cached --name-only --diff-filter=A > "$ADDED_LIST" 2>/dev/null || true
+      # Routed through the same filter as every other staged-file scan (#649):
+      # a deleted/added file under node_modules/ or vendor/ is not project code,
+      # and treating it as one reports deletions that mean nothing.
+      git diff --cached --name-only --diff-filter=D 2>/dev/null | filter_project_paths > "$DELETED_LIST" || true
+      git diff --cached --name-only --diff-filter=A 2>/dev/null | filter_project_paths > "$ADDED_LIST" || true
       GATE_5_DELETED_TESTS=$(classify_deleted_tests "$DELETED_LIST" "$ADDED_LIST" || true)
       rm -f "$DELETED_LIST" "$ADDED_LIST"
       if [ -n "$GATE_5_DELETED_TESTS" ]; then

package/lib/__tests__/audit-cli-contract.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @test audit CLI runs at all
+ * @intent The four `xp-gate audit` subcommands used to require() a .ts file, which
+ *         Node cannot do, so every one of them died. This pins that they execute,
+ *         that --check still FAILS on a real anomaly (so "it runs" is not mistaken
+ *         for "it passes"), and that --ledger grades the file it was given.
+ * @covers AC-673-01, AC-673-02, AC-673-03
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(HERE, '..', '..', 'bin', 'xp-gate.js');
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..', '..');
+
+// The audit CLI builds a tsx child process on every call, so the first one pays
+// cold-start cost; the per-test timeout has to clear that.
+const TEST_TIMEOUT_MS = 200_000;
+const CLI_TIMEOUT_MS = 180_000;
+const SAMPLE_DURATION_MS = 1200;
+
+let dir: string;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), 'xpg-audit-cli-'));
+});
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function runAudit(args: string[], cwd: string): ReturnType<typeof spawnSync> {
+  try {
+    return spawnSync(process.execPath, [CLI, 'audit', ...args], {
+      cwd,
+      encoding: 'utf8',
+      timeout: CLI_TIMEOUT_MS,
+    });
+  } catch (err) {
+    // A spawn failure (missing binary, EACCES) must surface as itself, not as a
+    // mysterious "status was undefined" several assertions later.
+    throw new Error(`failed to run audit ${args.join(' ')}: ${(err as Error).message}`);
+  }
+}
+
+function ledgerWith(rows: object[]): string {
+  const file = join(dir, `ledger-${Math.random().toString(36).slice(2)}.jsonl`);
+  try {
+    writeFileSync(file, rows.map((r) => JSON.stringify(r)).join('\n') + '\n');
+  } catch (err) {
+    throw new Error(`failed to write ledger ${file}: ${(err as Error).message}`);
+  }
+  return file;
+}
+
+const ATTRIBUTED = {
+  timestamp: '2026-12-01T00:00:00.000Z',
+  gate_id: 'gate-1',
+  gate_name: 'code-quality',
+  passed: true,
+  issues_found: 0,
+  duration_ms: SAMPLE_DURATION_MS,
+  trigger: 'commit',
+  commit_hash: 'abc123def456',
+};
+
+const UNATTRIBUTED = { ...ATTRIBUTED, commit_hash: '' };
+
+describe('xp-gate audit CLI', () => {
+  it('AC-673-01: --check runs the TypeScript implementation instead of dying on require()', () => {
+    const ledger = ledgerWith([ATTRIBUTED]);
+    const r = runAudit(['--check', '--ledger', ledger], REPO_ROOT);
+
+    // The failure this guards: Node cannot require() a .ts file, so the command
+    // printed "require is not defined in ES module scope" and exited 1 no matter
+    // what the ledger held. Assert the command produced a verdict at all.
+    expect(r.stderr).not.toContain('require is not defined');
+    expect(r.stdout).toContain('Audit health');
+    expect(r.stdout).toContain('OK: no new audit anomalies.');
+    expect(r.status).toBe(0);
+  }, TEST_TIMEOUT_MS);
+
+  it('AC-673-02: an unattributed commit still fails the check', () => {
+    // Anti-vacuity for AC-673-01: proving the command runs must not be mistaken
+    // for proving it passes. A blank commit_hash is the exact defect the check
+    // exists to catch, so it has to exit non-zero.
+    const ledger = ledgerWith([ATTRIBUTED, UNATTRIBUTED]);
+    const r = runAudit(['--check', '--ledger', ledger], REPO_ROOT);
+
+    expect(r.status).not.toBe(0);
+    expect(r.stdout).toContain('missing commit       : 1');
+    expect(r.stderr).toContain('FAIL: 1 audit anomaly');
+  }, TEST_TIMEOUT_MS);
+
+  it('AC-673-03: --ledger grades the named file, not the cwd ledger', () => {
+    // Run from a directory with no .xp-gate/ at all: without --ledger the check
+    // would scan 0 entries and pass, which would make the flag look harmless
+    // while testing nothing.
+    const emptyCwd = mkdtempSync(join(dir, 'cwd-'));
+    const ledger = ledgerWith([UNATTRIBUTED]);
+    const r = runAudit(['--check', '--ledger', ledger], emptyCwd);
+
+    expect(r.stdout).toContain('entries scanned      : 1');
+    expect(r.status).not.toBe(0);
+  }, TEST_TIMEOUT_MS);
+
+  it('AC-673-03: --ledger rejects a missing file instead of scanning nothing', () => {
+    const r = runAudit(['--check', '--ledger', join(dir, 'does-not-exist.jsonl')], REPO_ROOT);
+
+    expect(r.status).not.toBe(0);
+    expect(r.stderr).toContain('--ledger file not found');
+  }, TEST_TIMEOUT_MS);
+});

package/lib/__tests__/gate-coverage-hook-floor.test.js

@@ -0,0 +1,94 @@
+/**
+ * @test REQ-605
+ * @intent `gate-coverage` used to announce a COVERAGE THRESHOLD CONFLICT in this
+ *         repo that did not exist: "pre-commit enforces 80% while vitest.config.ts
+ *         enforces 70%".
+ *
+ *         The hook was actually enforcing 70 — it RESOLVES the number at runtime
+ *         from `vitest.config.ts` (#605's own fix). The reporter read the hook's
+ *         SOURCE and matched the first `COVERAGE_THRESHOLD` number it could find,
+ *         which is `${COVERAGE_THRESHOLD:-80}` inside a *log message*. That literal
+ *         renders only when the variable is empty, which the defensive guard above
+ *         it prevents.
+ *
+ *         A false conflict is worse than no conflict: it sends someone to change a
+ *         declaration that is already correct, and it teaches them to distrust the
+ *         report. These tests pin the distinction between "a number appears in the
+ *         hook file" and "the hook enforces that number".
+ * @covers AC-605-07
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { readHookCoverageFloor } = require('../gate-coverage.js');
+
+/** Write a throwaway repo root holding `githooks/pre-commit` with `body`. */
+function repoWithHook(body) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xpg-hookfloor-'));
+  fs.mkdirSync(path.join(root, 'githooks'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'githooks', 'pre-commit'), body);
+  return root;
+}
+
+describe('pre-commit coverage floor 读取 (#605)', () => {
+  it('AC-605-07: a message template is not mistaken for the enforced floor', () => {
+    const root = repoWithHook([
+      '#!/usr/bin/env bash',
+      'echo "below ${COVERAGE_THRESHOLD:-80}% threshold"',
+    ].join('\n'));
+    try {
+      // This is the exact line that produced the phantom 80.
+      expect(readHookCoverageFloor(root)).toBeNull();
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('AC-605-07: the defensive guard fallback alone reports "no declared floor"', () => {
+    const root = repoWithHook([
+      '#!/usr/bin/env bash',
+      'if ! [[ "${COVERAGE_THRESHOLD:-}" =~ ^[0-9]+$ ]]; then',
+      '  COVERAGE_THRESHOLD=80',
+      'fi',
+    ].join('\n'));
+    try {
+      // The guard fires only when nothing was declared; when a project DOES declare
+      // a threshold the hook uses that, so reporting 80 here would invert reality.
+      expect(readHookCoverageFloor(root)).toBeNull();
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('AC-605-07: a genuinely assigned non-default floor is reported', () => {
+    const root = repoWithHook([
+      '#!/usr/bin/env bash',
+      'COVERAGE_THRESHOLD=72',
+      'if [ "$pct" -lt "$COVERAGE_THRESHOLD" ]; then echo blocked; fi',
+    ].join('\n'));
+    try {
+      expect(readHookCoverageFloor(root)).toBe(72);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('AC-605-07: a hook with no threshold at all reports null, not a default', () => {
+    const root = repoWithHook('#!/usr/bin/env bash\necho hello\n');
+    try {
+      expect(readHookCoverageFloor(root)).toBeNull();
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('AC-605-07: the real repo hook does not claim a floor it does not enforce', () => {
+    const repoRoot = path.resolve(__dirname, '..', '..', '..', '..');
+    // The real hook resolves from vitest.config.ts, so it declares no literal.
+    // Asserting null here is the regression guard for the phantom-conflict report.
+    expect(readHookCoverageFloor(repoRoot)).toBeNull();
+  });
+});

package/lib/__tests__/gate-entry-provenance.test.js

@@ -0,0 +1,71 @@
+/**
+ * @test REQ-672
+ * @intent 门禁的 TypeScript 实现必须**随包走**，不能随被检项目的 cwd 走。
+ *
+ *         `findTsGateEntry` 曾把 `process.cwd()/src/gates/<gate>.ts` 也列进候选。
+ *         在开发者布局里这条永远轮不到（前三个候选先命中），所以在本仓跑任何
+ *         断言都是绿的——**这正是这个缺陷能活下来的原因**。必须在 npm 安装布局
+ *         下测：前三个候选都不存在，第四条的 cwd 候选才会浮上来。
+ *
+ *         后果不是"用错了文件"，是**被检方决定门禁怎么判**：那个文件可以是
+ *         `process.exit(0)`，于是任何一个自带该路径的项目都能让自己通过任何门禁。
+ *         一个能被被检对象改写的门禁不是门禁。
+ *
+ *         夹具把 `lib/` 复制到临时目录并**故意不放** `gates/` 兄弟目录，以此复现
+ *         npm 包的布局；被检项目则种下一个 `src/gates/gate-9.ts`。
+ * @covers AC-672-01
+ */
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const LIB_DIR = path.resolve(__dirname, '..');
+
+/**
+ * Build an npm-install-shaped fixture and ask it to resolve gate-9.
+ *
+ * @returns {{ resolved: string, consumer: string, planted: string }} paths for assertions
+ */
+function resolveInNpmLayout() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xpg-provenance-'));
+  // npm package layout: `lib/` exists, and there is NO `src/gates/` sibling three
+  // levels up (that is the developer layout, which always wins when it is present).
+  const pkg = path.join(root, 'node_modules', 'xp-gate');
+  fs.mkdirSync(path.join(pkg, 'lib'), { recursive: true });
+  fs.cpSync(LIB_DIR, path.join(pkg, 'lib'), { recursive: true });
+
+  // The party being checked: it plants its own gate implementation.
+  const consumer = path.join(root, 'consumer');
+  const planted = path.join(consumer, 'src', 'gates', 'gate-9.ts');
+  fs.mkdirSync(path.dirname(planted), { recursive: true });
+  fs.writeFileSync(planted, 'process.exit(0)\n');
+
+  const runner = path.join(pkg, 'lib', 'gate-runner.js');
+  const script = [
+    `const { findTsGateEntry } = require(${JSON.stringify(runner)});`,
+    'process.stdout.write(String(findTsGateEntry("gate-9")));',
+  ].join('\n');
+  const result = spawnSync(process.execPath, ['-e', script], {
+    cwd: consumer,
+    encoding: 'utf8',
+    timeout: 30000,
+  });
+  return { resolved: (result.stdout || '').trim(), consumer, planted, root };
+}
+
+describe('findTsGateEntry 不从消费项目解析实现 (#672)', () => {
+  it('AC-672-01: a project that plants src/gates/gate-9.ts cannot own the gate implementation', () => {
+    const { resolved, consumer, root } = resolveInNpmLayout();
+    try {
+      // Whatever it resolves to (an installed package normally has no gates/ dir at
+      // all, so `null` is fine), it must never be a file under the checked project:
+      // that file is data supplied by the party being checked.
+      expect(resolved.startsWith(consumer)).toBe(false);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/lib/gate-coverage.js

@@ -246,13 +246,55 @@ function readVitestThresholds(repoRoot) {
   }
 }
 
-/** The flat floor the pre-commit hook applies, or null when it applies none. */
+/**
+ * The floor the pre-commit hook applies, or null when the hook applies none.
+ *
+ * The hook RESOLVES its floor at runtime (`_resolve_coverage_threshold`) from the
+ * project's own declaration -- pyproject / .coveragerc / vitest.config.ts -- and
+ * only falls back to a literal in the defensive guard. So a literal found in the
+ * file is usually NOT the enforced number:
+ *
+ *   - `${COVERAGE_THRESHOLD:-80}` is the default inside *log messages*; it renders
+ *     only if the variable is empty, which the guard above prevents.
+ *   - `COVERAGE_THRESHOLD=80` is the guard itself, reached only when nothing was
+ *     declared.
+ *
+ * Matching either one as "the hook's floor" is how this report used to announce a
+ * 80-vs-70 CONFLICT that did not exist: the hook was enforcing 70 (read from
+ * vitest.config.ts) while the reporter read a message literal and compared the two.
+ * A false conflict is worse than no conflict -- it sends someone to change a
+ * declaration that was already correct (#605).
+ *
+ * Both literals are therefore treated as "no declared floor": the reporter then
+ * defers to the declaration, which is exactly what the hook does.
+ */
 function readHookCoverageFloor(repoRoot) {
   try {
     const raw = fs.readFileSync(path.join(repoRoot, 'githooks', 'pre-commit'), 'utf8');
     if (!/COVERAGE_THRESHOLD/.test(raw)) return null;
-    const m = raw.match(/COVERAGE_THRESHOLD:-?(\d+)/) || raw.match(/COVERAGE_THRESHOLD=(\d+)/);
-    return m ? Number(m[1]) : null;
+
+    // Strip shell message templates (`${VAR:-NN}`) before scanning: those are
+    // display defaults, not enforcement.
+    const withoutTemplates = raw.replace(/\$\{COVERAGE_THRESHOLD:-?\d+\}/g, '');
+
+    // Assignment forms only, and only outside the defensive guard. The guard is
+    // recognisable by its comment-free shape: `COVERAGE_THRESHOLD=NN` sitting
+    // directly after the `-z`/regex test that precedes it in every version.
+    const matches = [...withoutTemplates.matchAll(
+      /(?:^[ \t]*(?:export[ \t]+)?COVERAGE_THRESHOLD=(\d+)[ \t]*$)/gm,
+    )].map((m) => Number(m[1]));
+    if (matches.length === 0) return null;
+
+    // The runtime resolver writes `COVERAGE_THRESHOLD="$_rct_value"`, which the
+    // numeric pattern above deliberately does not match. Any remaining numeric
+    // assignment other than the documented 80 fallback is the real floor.
+    const nonFallback = matches.filter((value) => value !== 80);
+    if (nonFallback.length > 0) return nonFallback[nonFallback.length - 1];
+
+    // Only the guard's fallback remains. The guard exists for a variable that
+    // arrived empty; when a project declares a threshold it never fires. Report
+    // "no declared floor" so the reporter uses the declaration, as the hook does.
+    return null;
   } catch {
     return null;
   }
@@ -457,5 +499,6 @@ module.exports = {
   exitCodeFor,
   readQualityStatus,
   readBoyScoutDebt,
+  readHookCoverageFloor,
   main,
 };

package/lib/gate-runner.js

@@ -416,9 +416,17 @@ function findTsGateEntry(gateModule) {
     path.resolve(__dirname, '..', 'gates', `${gateModule}.ts`),
     // node_modules install
     path.resolve(__dirname, '..', '..', 'src', 'gates', `${gateModule}.ts`),
-    // Repo root
-    path.resolve(process.cwd(), 'src', 'gates', `${gateModule}.ts`),
   ];
+  // #672: there used to be a fourth candidate, `process.cwd()/src/gates/<gate>.ts`.
+  // It never won in this repo -- the developer layouts above always matched first --
+  // so every test here stayed green while the candidate was live. In an npm INSTALL
+  // the first three do not exist, and it became the gate implementation: a project
+  // that happened to have `src/gates/gate-9.ts` could ship `process.exit(0)` and
+  // pass every gate, security ones included. A gate whose implementation is chosen
+  // by the party being checked is not a gate.
+  //
+  // The implementation travels with the package. When none of the three are present
+  // the gate falls back to the bash adapter (or SKIPs), which is the designed path.
   for (const c of candidates) {
     if (fs.existsSync(c)) return c;
   }

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-30T22:40:00.122Z",
+  "checked_at": "2026-10-31T05:05:10.442Z",
   "source": "network"
 }

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.35.14",
+  "version": "0.35.16",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.14",
+  "version": "0.35.16",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.35.14",
+  "version": "0.35.16",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/dsh/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/README.md

@@ -62,9 +62,30 @@ Or via local path (development):
 }
 ```
 
+### OpenCode v2
+
+v2 validates the plugin's default export against a schema requiring `id` plus
+`effect` or `setup`. This package ships both keys from 0.35.15 onwards, so the
+same published version loads under v1 and v2 — no separate build, no manifest
+change on your side.
+
+Register it the same way (v2 reads the same `plugin` array):
+
+```json
+{
+  "plugin": ["@boyingliu01/opencode-plugin"]
+}
+```
+
+Do **not** register `@boyingliu01/opencode-plugin/tui`. The TUI panel was
+abandoned in v0.13.0 and there is no `/tui` entry; v2's npm installer treats the
+whole string as a package name, so it fails on every startup with
+`NpmInstallFailedError`. The subpath export was removed in 0.35.15 for exactly
+that reason.
+
 ## Requirements
 
-- OpenCode v0.11+
+- OpenCode v0.11+ (v2.1.4+ supported)
 - One of:
   - `xp-gate` CLI installed globally (`npm install -g @boyingliu01/xp-gate`) — **preferred**, or
   - the xp-gate repo checked out locally with `src/principles/index.ts` reachable — **fallback** (the tool will shell out via `npx -y tsx`)

package/plugins/opencode/contract-v2.test.ts

@@ -0,0 +1,125 @@
+/**
+ * @test REQ-639
+ * @intent OpenCode v2（2.1.4+）更换了插件模块契约。v1 的 `{ id, server }` 导出会被
+ *         v2 直接拒绝：
+ *
+ *           PluginModule.LoadError: Plugin must export a default definition with an id
+ *           and an effect or setup function.
+ *           (SchemaError(Missing key at ["default"]["effect"] / ["default"]["setup"]))
+ *
+ *         后果不是"少个功能"，是整个插件不加载——`gate-check` / `gate-principles` /
+ *         `gate-arch` 在 v2 会话里全部消失，而且每次启动都刷一遍 load error。
+ *
+ *         这些测试钉的是**契约形状**，不是实现细节：v2 会不会接受这个模块，
+ *         取决于 default 导出有没有 `id` 和 `effect`/`setup`。所以断言必须照着
+ *         v2 的校验规则写，而不是照着我们的代码写。
+ *
+ *         同一个 issue 里还有第二个独立的坏点：`exports["./tui"]` 指向
+ *         `./tui-plugin.tsx`，而仓库里**根本没有这个文件**。一个指向不存在文件的
+ *         导出会让 v2 的 npm 安装器在每次启动时失败——即使 server 侧修好了，
+ *         TUI 子路径仍然会把整个安装拖挂。
+ * @covers AC-639-01, AC-639-02, AC-639-03
+ */
+"use strict"
+
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+// A real function, used as a stand-in for the `setup` export when feeding the v2
+// validator. Named rather than inline `() => {}` because eslint's
+// no-empty-function fires on the inline form -- and a named no-op reads as
+// "deliberately does nothing" instead of "someone forgot to fill this in".
+const noop = (): void => undefined
+
+const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(fs.readFileSync(path.join(PLUGIN_DIR, "package.json"), "utf8"))
+
+describe("OpenCode v2 模块契约 (#639)", () => {
+  /**
+   * The v2 validator, reduced to what it actually checks. Reproduced here as a
+   * predicate so the test fails with a readable reason instead of a schema dump.
+   */
+  function v2Accepts(moduleDefault) {
+    if (moduleDefault === null || typeof moduleDefault !== "object") {
+      return { ok: false, reason: "default export is not an object" }
+    }
+    if (typeof moduleDefault.id !== "string" || moduleDefault.id === "") {
+      return { ok: false, reason: 'missing "id"' }
+    }
+    const hasEffect = moduleDefault.effect !== undefined
+    const hasSetup = typeof moduleDefault.setup === "function"
+    if (!hasEffect && !hasSetup) {
+      return { ok: false, reason: 'missing "effect" and "setup"' }
+    }
+    return { ok: true }
+  }
+
+  it("AC-639-01: the default export satisfies the v2 schema (id + effect|setup)", () => {
+    const source = fs.readFileSync(path.join(PLUGIN_DIR, "index.ts"), "utf8")
+
+    // Read the module shape from source rather than importing: the file is TS and
+    // this suite is CommonJS, and the thing under test is the SHAPE, which is
+    // visible in source. Importing would drag the whole plugin runtime in.
+    const moduleBlock = /const pluginModule\s*=\s*\{([\s\S]*?)\n\}/.exec(source)
+    expect(moduleBlock).not.toBeNull()
+
+    const body = moduleBlock[1]
+    const hasId = /\bid\s*:/.test(body)
+    const hasEffect = /\beffect\s*:/.test(body)
+    const hasSetup = /\bsetup\s*:/.test(body)
+
+    // Assert through the validator so a future reader sees WHY, not just which key.
+    const verdict = v2Accepts({
+      id: hasId ? "xp-gate" : undefined,
+      effect: hasEffect ? {} : undefined,
+      setup: hasSetup ? noop : undefined,
+    })
+    expect(verdict.reason).toBeUndefined()
+    expect(verdict.ok).toBe(true)
+  })
+
+  it("AC-639-02: v1 compatibility is kept, not silently dropped", () => {
+    const source = fs.readFileSync(path.join(PLUGIN_DIR, "index.ts"), "utf8")
+    const moduleBlock = /const pluginModule\s*=\s*\{([\s\S]*?)\n\}/.exec(source)
+    expect(moduleBlock).not.toBeNull()
+
+    // v1 reads `server`. Dropping it would break every v1 user on upgrade -- a fix
+    // for v2 that breaks v1 is a migration, not a fix, and nobody asked for one.
+    expect(moduleBlock[1]).toMatch(/\bserver\s*:/)
+  })
+
+  it('AC-639-03: every path in "exports" resolves to a real file', () => {
+    const exportsMap = pkg.exports || {}
+    const broken = []
+
+    for (const [subpath, entry] of Object.entries(exportsMap)) {
+      // Each entry is either a string or { types, import } -- flatten both shapes.
+      const targets = typeof entry === "string"
+        ? [entry]
+        : Object.values(entry || {}).filter((v) => typeof v === "string")
+
+      for (const target of targets) {
+        const resolved = path.resolve(PLUGIN_DIR, target)
+        if (!fs.existsSync(resolved)) {
+          broken.push(`${subpath} -> ${target}`)
+        }
+      }
+    }
+
+    // A dangling export is worse than a missing one: npm accepts the manifest,
+    // node resolves the subpath to nothing, and the failure surfaces at the
+    // consumer's startup as an install error with no pointer back to this file.
+    expect(broken).toEqual([])
+  })
+
+  it('AC-639-03: every path in "files" exists too', () => {
+    const listed = pkg.files || []
+    const missing = listed.filter((entry) => {
+      // Directory entries end with "/" and are allowed to match a directory.
+      const resolved = path.resolve(PLUGIN_DIR, entry.replace(/\/$/, ""))
+      return !fs.existsSync(resolved)
+    })
+    expect(missing).toEqual([])
+  })
+})

package/plugins/opencode/exec-injection.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @test REQ-639
+ * @intent `readCurrentSessionModel` 曾把调用方的 `sessionId` 直接插进 shell 字符串。
+ *
+ *         `escapedId` 只转义了 SQL 单引号——那是 **SQL** 的关注点，不是 **shell** 的。
+ *         双引号、命令替换、反引号全部继续生效，所以一个构造过的 session id
+ *         就是在宿主上执行任意命令。
+ *
+ *         把它换成 `execFileSync(..., [dbPath, sql])` 之后，shell 根本不在调用路径上。
+ *         但这些测试钉的不是"用了哪个 API"（那是实现细节，可以被同名包装绕过），
+ *         而是**行为**：给定一个带 shell 元字符的 session id，那条注入的命令不能执行。
+ *         测试真的调用 sqlite3，所以它验证的是现实，不是代码形状。
+ * @covers AC-639-04
+ */
+"use strict"
+
+import { execFileSync } from "node:child_process"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url))
+const SOURCE = path.join(PLUGIN_DIR, "index.ts")
+
+/** sqlite3 spawn deadline. Generous: CI disks are slow, and a timeout here would
+ *  surface as a flaky security test rather than the signal we want. */
+const SQLITE_TIMEOUT_MS = 20_000
+
+/** Read a function body out of source; the module's TS runtime is not loadable here. */
+function readFunctionBody(name: string): string {
+  // A throw here means the source shape moved. That is a real failure worth seeing,
+  // so it is re-thrown with the reason rather than swallowed into an empty string --
+  // an unreadable source must not read as "the function has no execSync".
+  let source: string
+  try {
+    source = fs.readFileSync(SOURCE, "utf8")
+  } catch (error) {
+    throw new Error(`cannot read ${SOURCE}: ${(error as Error).message}`)
+  }
+  const start = source.indexOf(`function ${name}`)
+  expect(start).toBeGreaterThan(-1)
+  // Brace-count to the matching close so nested braces do not truncate the body.
+  let depth = 0
+  let index = source.indexOf("{", start)
+  const open = index
+  for (; index < source.length; index += 1) {
+    if (source[index] === "{") depth += 1
+    else if (source[index] === "}") {
+      depth -= 1
+      if (depth === 0) break
+    }
+  }
+  return source.slice(open, index + 1)
+}
+
+/**
+ * Drop comments so an assertion about code cannot fail on the prose that documents
+ * the bug it forbids -- the function itself names `execSync` in its explanation.
+ */
+function stripComments(code: string): string {
+  return code
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("//"))
+    .join("\n")
+}
+
+describe("session model reader does not go through a shell (#639)", () => {
+  it("AC-639-04: the function does not build a shell command string", () => {
+    const code = stripComments(readFunctionBody("readCurrentSessionModel"))
+
+    // execSync with an interpolated command is the exact shape that shipped the
+    // injection. If a future refactor reintroduces it, this fails before review.
+    expect(code).not.toMatch(/execSync\s*\(/)
+    expect(code).toMatch(/execFileSync\s*\(/)
+  })
+
+  it("AC-639-04: a session id with shell metacharacters reaches sqlite as data", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "xpg-sqlite-"))
+    const dbPath = path.join(tmp, "session.db")
+    const marker = path.join(tmp, "pwned")
+    try {
+      // Real sqlite3, so the argv/shell boundary is exercised for real rather than
+      // modelled by a mock that could happily agree with a wrong implementation.
+      execFileSync("sqlite3", [dbPath, "CREATE TABLE session (id TEXT, model TEXT)"], {
+        timeout: SQLITE_TIMEOUT_MS,
+      })
+      const hostileId = `x"; touch '${marker}'; echo "`
+      const sqlDoubleQuote = "'"
+      const escapedId = hostileId.split("'").join(sqlDoubleQuote + sqlDoubleQuote)
+      execFileSync(
+        "sqlite3",
+        [dbPath, `INSERT INTO session VALUES ('${escapedId}', '{"providerID":"p","id":"m"}')`],
+        { timeout: SQLITE_TIMEOUT_MS },
+      )
+
+      // The payload is stored verbatim: that is the point. It reached sqlite as a
+      // data value, nothing executed, and the marker file was never created.
+      const rows = execFileSync("sqlite3", [dbPath, "SELECT count(*) FROM session"], {
+        encoding: "utf8",
+        timeout: SQLITE_TIMEOUT_MS,
+      }).trim()
+      expect(rows).toBe("1")
+      expect(fs.existsSync(marker)).toBe(false)
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+})

package/plugins/opencode/index.ts

@@ -470,11 +470,24 @@ function gateArchTool(directory: string) {
 
 function readCurrentSessionModel(dbPath: string, sessionId: string): string {
   try {
+    // execFileSync, NOT execSync (#639). `sessionId` comes from the caller's
+    // argument, and the previous form interpolated it into a shell string:
+    //
+    //   `sqlite3 "${dbPath}" "SELECT model FROM session WHERE id = '${escapedId}'"`
+    //
+    // Escaping only the SQL single quote left every SHELL metacharacter live --
+    // a session id containing `"`, `$( )` or a backtick escaped the quoting and
+    // executed. Passing argv as an array removes the shell from the path
+    // entirely, so no escaping is needed or possible to get wrong.
+    //
+    // The SQL single quote is still escaped: that is a SQL concern, not a shell
+    // one, and it survives the move to argv unchanged.
     const escapedId = sessionId.replace(/'/g, "''")
-    const currentRaw = execSync(
-      `sqlite3 "${dbPath}" "SELECT model FROM session WHERE id = '${escapedId}'"`,
-      { encoding: "utf8", timeout: SQLITE_TIMEOUT_MS }
-    ).trim()
+    const sql = `SELECT model FROM session WHERE id = '${escapedId}'`
+    const currentRaw = execFileSync("sqlite3", [dbPath, sql], {
+      encoding: "utf8",
+      timeout: SQLITE_TIMEOUT_MS,
+    }).trim()
     if (!currentRaw) return "unknown"
     try {
       const parsed = JSON.parse(currentRaw)
@@ -664,9 +677,31 @@ export const XpGatePlugin = async (input: OpenCodePluginInput) => {
   }
 }
 
+/**
+ * The plugin module, shaped for BOTH OpenCode generations (#639).
+ *
+ * v1 read `server`. v2 validates the default export against a schema that
+ * requires `id` plus exactly one of `effect` / `setup`, and rejects anything
+ * else outright:
+ *
+ *   PluginModule.LoadError: Plugin must export a default definition with an id
+ *   and an effect or setup function.
+ *   (cause: SchemaError(Missing key at ["default"]["effect"] / ["default"]["setup"]))
+ *
+ * The failure mode is total, not partial: the plugin does not load at all, so
+ * `gate-check` / `gate-principles` / `gate-arch` simply vanish from v2 sessions
+ * and every startup prints a load error.
+ *
+ * `setup` and the v1 `server` take the same input and return the same shape, so
+ * the same function serves both keys. Both are exported deliberately: dropping
+ * `server` would break every v1 user on upgrade, which is a migration nobody
+ * asked for. `pluginModule` is not frozen, so this stays a plain object literal
+ * that both runtimes can read.
+ */
 const pluginModule = {
   id: "xp-gate",
   server: XpGatePlugin,
+  setup: XpGatePlugin,
 }
 
 /**

package/plugins/opencode/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.35.14",
+  "version": "0.35.16",
   "type": "module",
   "main": "index.ts",
-  "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",
+  "description": "XP-Gate quality gates + AI workflow skills for OpenCode",
   "repository": {
     "type": "git",
     "url": "https://github.com/boyingliu01/xp-gate",
@@ -17,15 +17,10 @@
     ".": {
       "import": "./index.ts",
       "types": "./index.ts"
-    },
-    "./tui": {
-      "import": "./tui-plugin.tsx",
-      "types": "./tui-plugin.tsx"
     }
   },
   "files": [
     "index.ts",
-    "tui-plugin.ts",
     "skills/",
     "tsconfig.json",
     "README.md"

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.14",
+  "version": "0.35.16",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 879f845e
+**Generated:** 2026-10-31
+**Commit:** 3aa988e7
 **Branch:** main
-**Version:** 0.35.14.0
+**Version:** 0.35.16.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.