@boyingliu01/xp-gate 0.35.15 → 0.35.17

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
@@ -2642,7 +2659,13 @@ else
   # Exclusions come from filter_project_paths (#649). The hand-maintained list
   # this replaced omitted vendor/target/coverage/out, so a staged vendor/x.ts
   # was reported as new source with no test.
-  NEW_TS_FILES=$(git diff --cached --name-only --diff-filter=A | filter_project_paths | grep -E '\.(ts|tsx)$' | grep -v '\.d\.ts$' | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__snapshots__' | grep -Ev '(^|/)vitest\.config\.' | grep -Ev '(^|/)vite\.config\.' | grep -Ev '(^|/)jest\.config\.' | grep -Ev '(^|/)tsconfig\.' | grep -Ev '(^|/)eslint\.' | grep -Ev '(^|/)prettier\.' | grep -Ev '(^|/)tailwind\.' || true)
+  #
+  # Byte-identical mirrors under src/npm-package/ are excluded the same way
+  # lint (#494) and Boy Scout (#649) already exclude them. A mirror cannot
+  # carry its own test: the next resync overwrites the directory, so the
+  # requirement is structurally unsatisfiable and blocked every commit that
+  # added a file to a mirrored module. The canonical source keeps its test.
+  NEW_TS_FILES=$(git diff --cached --name-only --diff-filter=A | filter_project_paths | grep -Ev "$MIRROR_PATH_FILTER" | grep -E '\.(ts|tsx)$' | grep -v '\.d\.ts$' | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__snapshots__' | grep -Ev '(^|/)vitest\.config\.' | grep -Ev '(^|/)vite\.config\.' | grep -Ev '(^|/)jest\.config\.' | grep -Ev '(^|/)tsconfig\.' | grep -Ev '(^|/)eslint\.' | grep -Ev '(^|/)prettier\.' | grep -Ev '(^|/)tailwind\.' || true)
 
   # Strip PROJECT_SUBDIR prefix from new-TS-file paths ONLY when the hook
   # actually cd'd into the subdirectory (IN_PROJECT_SUBDIR=1; single-language

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:49:35.688Z",
+  "checked_at": "2026-10-31T07:40:57.523Z",
   "source": "network"
 }

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-30
-**Commit:** 6091e238
+**Generated:** 2026-10-31
+**Commit:** 26a741de
 **Branch:** main
-**Version:** 0.35.15.0
+**Version:** 0.35.17.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:** 6091e238
+**Generated:** 2026-10-31
+**Commit:** 26a741de
 **Branch:** main
-**Version:** 0.35.15.0
+**Version:** 0.35.17.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.