@boyingliu01/xp-gate 0.35.5 → 0.35.7

package/bin/xp-gate.js

@@ -277,7 +277,7 @@ const COMMANDS = {
       }
       return doctor(subargs).then(code => process.exit(code));
     },
-    usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force] | --refresh-env] | --json | --format json  (the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks; --refresh-env is read-only so it combines with them)'
+    usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force] | --refresh-env | --brief] | --json | --format json  (--brief is a read-only one-shot fact dump and refuses --fix/--sync-hooks/--install-tools/--force; the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks; --refresh-env is read-only so it combines with them)'
   },
   'ui-review': {
     description: 'Run UI review for non-sprint developers (generates .ui-gate-result.json)',
@@ -365,6 +365,21 @@ const COMMANDS = {
     },
     usage: 'xp-gate gate-coverage [--json] [--debt] [--strict] [--branch <name>]'
   },
+  'gate-rules': {
+    description: 'Print the gate limits that can block a commit, generated from the files that define them (#652)',
+    run: subargs => {
+      const { collectGateRules, renderGateRules } = require('../lib/gate-rules.js');
+      const rules = collectGateRules({ cwd: process.cwd() });
+      if (subargs.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(rules, null, 2)}\n`);
+        return;
+      }
+      // Generated, never hand-copied: a checklist that drifts from the config it
+      // describes teaches the wrong rule and then contradicts it at commit time.
+      process.stdout.write(`${renderGateRules(rules)}\n`);
+    },
+    usage: 'xp-gate gate-rules [--json]'
+  },
   'rework': {
     description: 'Report rework: first-pass rate, rounds before landing, top blocking reasons (#651)',
     run: subargs => {
@@ -673,15 +688,60 @@ function handleAudit(args) {
     return;
   }
 
+  // #668: pre-existing assertion debt, so it can be cleared in batches instead of
+  // being discovered one unrelated commit at a time.
+  if (args[0] === 'assertions') {
+    handleAuditAssertions(args);
+    return;
+  }
+
   console.error('Error: Unknown audit subcommand or missing flag');
   console.error('Usage:');
   console.error('  xp-gate audit record --gate-id X --gate-name Y --passed true/false --issues-found N --duration-ms N --trigger commit');
   console.error('  xp-gate audit --tail [N]     (default: 20)');
   console.error('  xp-gate audit --stats        (per-gate stats + anomaly summary)');
   console.error('  xp-gate audit --check        (exit 1 if the ledger has anomalies)');
+  console.error('  xp-gate audit assertions     (list pre-existing assertion debt across the repo; --json)');
   process.exit(1);
 }
 
+/**
+ * `xp-gate audit assertions` (#668) — list pre-existing vacuous assertions.
+ *
+ * Gate 5d only inspects files in the diff, so standing debt surfaces during
+ * unrelated commits and reads as if that change introduced it. This makes the debt
+ * a work queue instead of a series of false accusations.
+ *
+ * Advisory: always exits 0. A debt list that fails builds becomes a number people
+ * learn to ignore.
+ */
+function handleAuditAssertions(args) {
+  const { scanForAssertionDebt, summarizeDebt } = require(path.join(__dirname, '..', 'lib', 'assertion-debt.js'));
+  const results = scanForAssertionDebt({ cwd: process.cwd() });
+  const summary = summarizeDebt(results);
+  if (args.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({ summary, files: results }, null, 2)}\n`);
+    return;
+  }
+  if (summary.total === 0) {
+    console.log('✅ No pre-existing assertion debt found.');
+    return;
+  }
+  console.log(`Found ${summary.total} pre-existing assertion issue(s) in ${summary.files} file(s):`);
+  console.log(`  tautological   ${summary.byKind.tautological}`);
+  console.log(`  swallowed-error ${summary.byKind['swallowed-error']}`);
+  console.log('');
+  for (const entry of results) {
+    console.log(`${entry.file}  (${entry.findings.length})`);
+    for (const finding of entry.findings) {
+      console.log(`  ${finding.line}: [${finding.kind}] ${finding.text}`);
+    }
+  }
+  console.log('');
+  console.log('These predate the current diff and would be reported as "introduced by this change"');
+  console.log('if the file is touched. See skills/test-driven-development/testing-anti-patterns.md');
+}
+
 function printAuditTable(entries) {
   console.log('');
   console.log('Recent Audit Entries:');

package/hooks/lib/assertion-quality.sh

@@ -178,6 +178,53 @@ classify_swallowed_errors() {
   grep -nE 'catch([[:space:]]*\([^)]*\))?[[:space:]]*\{[[:space:]]*\}' || true
 }
 
+# #668: is the flagged line part of THIS change, or merely carried in by the file?
+#
+# Gate 5d runs over whole files, so a file that was edited anywhere gets all of its
+# assertions re-examined. Pre-existing debt then blocks an unrelated commit and
+# reads as "this change introduced it". The author who fixed `writeReport()`'s error
+# handling was stopped by four `expect(true).toBe(true)` lines that had been there
+# for months.
+#
+# The cost is not the one false block. It is that the noise teaches people to add
+# `@assertion-justified` rather than fix the test -- a gate that trains people to
+# annotate past it is worse than no gate.
+#
+# Args: $1 = file path, $2 = line number, $3 = added-line ranges ("start-end start-end")
+# Returns 0 when the line is inside an added hunk (i.e. genuinely introduced here).
+assertion_line_is_new() {
+  local _aq_file="$1" _aq_line="$2" _aq_ranges="$3"
+  local _aq_range _aq_start _aq_end
+  for _aq_range in $_aq_ranges; do
+    _aq_start="${_aq_range%%-*}"
+    _aq_end="${_aq_range##*-}"
+    if [ "$_aq_line" -ge "$_aq_start" ] 2>/dev/null && [ "$_aq_line" -le "$_aq_end" ] 2>/dev/null; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Emit "start-end" for each added hunk in the staged diff of $1.
+# Empty output means the file has no added lines at all, in which case every finding
+# is pre-existing by construction.
+staged_added_line_ranges() {
+  local _aq_file="$1"
+  git diff --cached -U0 -- "$_aq_file" 2>/dev/null \
+    | awk '
+        /^@@/ {
+          # @@ -a,b +c,d @@ -- the +side is the new-file line numbering.
+          if (match($0, /\+[0-9]+(,[0-9]+)?/)) {
+            spec = substr($0, RSTART + 1, RLENGTH - 1)
+            n = split(spec, parts, ",")
+            start = parts[1] + 0
+            count = (n > 1) ? parts[2] + 0 : 1
+            if (count > 0) printf "%d-%d ", start, start + count - 1
+          }
+        }
+      ' || true
+}
+
 # Anti-patterns 3-5 (WARNING tier): weak-only assertions, mock-echo assertions, and
 # call-order over-verification. These can be legitimate, so each is reported but
 # never blocks.

package/hooks/pre-commit

@@ -2395,17 +2395,63 @@ else
             _tauto=$(printf '%s\n' "$_tf_content" | classify_tautological_assertions || true)
             _swallow=$(printf '%s\n' "$_tf_content" | classify_swallowed_errors || true)
             _weak=$(printf '%s\n' "$_tf_content" | classify_weak_assertions || true)
+            # #668: split the findings into "added by this change" and
+            # "pre-existing". Gate 5d examines whole files, so editing a file
+            # anywhere re-examines all of its assertions; presenting standing debt
+            # under an unrelated commit is a false attribution, and false
+            # attribution is what drives people to @assertion-justified instead of
+            # a real fix.
+            _new_ranges=$(staged_added_line_ranges "$_tf" 2>/dev/null || true)
             if [ -n "$_tauto" ]; then
-              echo "❌ BLOCKED - tautological assertion(s) in $_tf (cannot fail):"
-              printf '%s\n' "$_tauto" | sed 's/^/     /'
-              echo "     See skills/test-driven-development/testing-anti-patterns.md"
-              GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+              _tauto_new=""
+              _tauto_old=""
+              while IFS= read -r _tline; do
+                [ -n "$_tline" ] || continue
+                _tnum="${_tline%%:*}"
+                if assertion_line_is_new "$_tf" "$_tnum" "$_new_ranges"; then
+                  _tauto_new="${_tauto_new}${_tline}"$'\n'
+                else
+                  _tauto_old="${_tauto_old}${_tline}"$'\n'
+                fi
+              done <<< "$_tauto"
+              if [ -n "$_tauto_new" ]; then
+                echo "❌ BLOCKED - tautological assertion(s) added by this change in $_tf (cannot fail):"
+                printf '%s' "$_tauto_new" | sed 's/^/     /'
+                echo "     See skills/test-driven-development/testing-anti-patterns.md"
+                GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+              fi
+              if [ -n "$_tauto_old" ]; then
+                echo "⚠️  WARN - PRE-EXISTING tautological assertion(s) in $_tf (NOT introduced by this change):"
+                printf '%s' "$_tauto_old" | sed 's/^/     /'
+                echo "     These predate this commit. Two options:"
+                echo "       fix them now (see 'xp-gate audit assertions'), or"
+                echo "       leave them - they are not blocking you."
+              fi
             fi
             if [ -n "$_swallow" ]; then
-              echo "❌ BLOCKED - empty catch in $_tf swallows the failure it guards:"
-              printf '%s\n' "$_swallow" | sed 's/^/     /'
-              echo "     See skills/test-driven-development/testing-anti-patterns.md"
-              GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+              # Same #668 split as the tautology branch above.
+              _sw_new=""
+              _sw_old=""
+              while IFS= read -r _sline; do
+                [ -n "$_sline" ] || continue
+                _snum="${_sline%%:*}"
+                if assertion_line_is_new "$_tf" "$_snum" "$_new_ranges"; then
+                  _sw_new="${_sw_new}${_sline}"$'\n'
+                else
+                  _sw_old="${_sw_old}${_sline}"$'\n'
+                fi
+              done <<< "$_swallow"
+              if [ -n "$_sw_new" ]; then
+                echo "❌ BLOCKED - empty catch added by this change in $_tf swallows the failure it guards:"
+                printf '%s' "$_sw_new" | sed 's/^/     /'
+                echo "     See skills/test-driven-development/testing-anti-patterns.md"
+                GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+              fi
+              if [ -n "$_sw_old" ]; then
+                echo "⚠️  WARN - PRE-EXISTING empty catch(es) in $_tf (NOT introduced by this change):"
+                printf '%s' "$_sw_old" | sed 's/^/     /'
+                echo "     These predate this commit; see 'xp-gate audit assertions'."
+              fi
             fi
             if [ -n "$_weak" ]; then
               echo "⚠️  WARN - test block(s) in $_tf assert only weak properties:"

package/lib/__tests__/assertion-debt.test.js

@@ -0,0 +1,99 @@
+/**
+ * @test REQ-668 `xp-gate audit assertions` 必须让存量断言债务可见
+ * @intent Gate 5d 只检查 **diff 范围内** 的文件。这是有意的——全仓扫描每次提交都跑
+ *         太慢——但它有个昂贵的副作用：存量债务会在 **无关改动** 时突然阻断，
+ *         制造错误的因果归因。原作者改了 `writeReport()` 的错误处理，却被
+ *         `test-alignment.test.ts` 里 4 处既有的 `expect(true).toBe(true)` 拦下。
+ *
+ *         这个副作用最坏的后果不是那一次误阻断，而是它改变修复者的行为：归因噪音
+ *         让人以为"先绕过再说"，于是倾向加 `@assertion-justified` 而不是真修掉。
+ *         一个让人更愿意豁免的门禁，比没有门禁更糟。
+ *
+ *         所以 `audit assertions` 的价值在于把"存量"变成可批处理的工作队列，
+ *         而不是让人在无关提交里逐个撞见。
+ * @covers AC-668-01, AC-668-02, AC-668-03
+ */
+'use strict';
+
+const { scanForAssertionDebt, summarizeDebt } = require('../assertion-debt');
+
+describe('xp-gate audit assertions (#668)', () => {
+  it('AC-668-01: 列出全仓存量问题，按文件分组', () => {
+    const results = scanForAssertionDebt({ cwd: process.cwd() });
+    expect(Array.isArray(results)).toBe(true);
+    // Grouped by file so a batch fixer can work one file at a time.
+    for (const entry of results) {
+      expect(typeof entry.file).toBe('string');
+      expect(Array.isArray(entry.findings)).toBe(true);
+      for (const f of entry.findings) {
+        expect(typeof f.line).toBe('number');
+        expect(['tautological', 'swallowed-error']).toContain(f.kind);
+        expect(typeof f.text).toBe('string');
+      }
+    }
+  });
+
+  it('AC-668-02: 识别两类确定性 vacuous 形态', () => {
+    // These are the two shapes Gate 5d blocks. Both are the ABSENCE of an assertion
+    // wearing assertion syntax, which is why they are the ones worth a debt list.
+    const fixture = [
+      'test("a", () => {',
+      '  expect(true).toBe(true);',
+      '  try { go(); } catch {}',
+      '});',
+      'test("b", () => {',
+      '  expect(x).toBe(1);',
+      '});',
+    ].join('\n');
+    const findings = scanForAssertionDebt({ source: fixture, file: 'fixture.test.ts' });
+    const flat = findings.flatMap((f) => f.findings);
+    expect(flat.some((f) => f.kind === 'tautological')).toBe(true);
+    expect(flat.some((f) => f.kind === 'swallowed-error')).toBe(true);
+    // A real assertion must not be reported -- a debt list that flags `expect(x).toBe(1)`
+    // is a list nobody finishes.
+    const realLine = flat.find((f) => f.text.includes('expect(x).toBe(1)'));
+    expect(realLine).toBeUndefined();
+  });
+
+  it('AC-668-03: 摘要给出可批次清零的数量，而非只是行数', () => {
+    const fixture = ['expect(true).toBe(true);', 'expect(1).toBe(1);', 'try { x(); } catch {}'].join('\n');
+    const results = scanForAssertionDebt({ source: fixture, file: 'a.test.ts' });
+    const summary = summarizeDebt(results);
+    expect(summary.files).toBe(1);
+    expect(summary.total).toBe(3);
+    // Two tautologies and one empty catch: the split matters because they are fixed
+    // by different edits (rewrite the assertion vs. handle the error).
+    expect(summary.byKind.tautological).toBe(2);
+    expect(summary.byKind['swallowed-error']).toBe(1);
+  });
+});
+
+/**
+ * @test REQ-668 fixture 不能被当作存量债务
+ * @intent 这条测试防的是一个**修债务反而删掉测试覆盖**的失败模式。
+ *
+ *         测试 Gate 5d 分类器的那批 .bats / .test.ts 文件必然包含
+ *         `'expect(true).toBe(true);'` —— 那是被校验的**输入**，不是断言。
+ *         若它们被列进"去修掉"的清单，执行清单的人会删掉钉住分类器行为的字符串，
+ *         于是债务清单本身成了覆盖率的破坏者。
+ *
+ *         反例同样重要：真正的裸断言 `expect(true).toBe(true);` 必须仍然被报出来。
+ *         只做"少报"很容易，难的是**同时**不误报也不漏报。
+ * @covers AC-668-04
+ */
+describe('fixture 与真实断言的区分 (#668)', () => {
+  it('AC-668-04: 带引号的 fixture 不报，裸断言照报', () => {
+    const { classifyLine } = require('../assertion-debt');
+    // Real code: must be reported.
+    expect(classifyLine('expect(true).toBe(true);')).toBe('tautological');
+    expect(classifyLine('    expect(1).toBe(1);')).toBe('tautological');
+    expect(classifyLine('try { x(); } catch {}')).toBe('swallowed-error');
+    // Fixture inputs: must not be reported.
+    expect(classifyLine("'    expect(true).toBe(true);',")).toBeNull();
+    expect(classifyLine('const s = "expect(true).toBe(true)";')).toBeNull();
+    // Neither is debt.
+    expect(classifyLine('// expect(true).toBe(true);')).toBeNull();
+    expect(classifyLine('expect(x).toBe(1);')).toBeNull();
+    expect(classifyLine('expect(value).toBeTruthy();')).toBeNull();
+  });
+});

package/lib/__tests__/check-single-file.test.js

@@ -0,0 +1,63 @@
+/**
+ * @test REQ-653 `check --gates` 单文件自检必须真的跑起来，且 < 2 秒
+ * @intent #653 要求提供一条"提交前自检"的快速路径，目标是让模型在写完代码后立刻
+ *         自查，而不是等一轮完整 pre-commit（Gate 5 单项就 32.5s）。
+ *
+ *         实现过程中挖出两个真 bug，它们都属于同一类：**工具没跑起来，却被报成
+ *         "你的代码有问题"**。
+ *
+ *         1. `xp-gate check <file>` 把文件路径直接当成 spawnSync 的 `cwd`。cwd 必须是
+ *            目录，指向文件时 spawnSync 返回裸 ENOENT，上层打印
+ *            "Gate 3: failed to run npx tsx" 然后计作 FAIL。
+ *         2. Windows 上曾用 `shell: true` 解析 npx.cmd，但 node 把 argv 拼成一整条
+ *            未转义的命令行（DEP0190），路径里有反斜杠或空格就会变形；改调 npx.cmd
+ *            本身又撞上 CVE-2024-27980 的 EINVAL 加固。
+ *
+ *         两个修复都要求"文件路径能跑通"，而不是"错误信息更好看"。所以断言打在
+ *         真实的 passed 计数与退出码上。
+ * @covers AC-653-04, AC-653-05
+ */
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const CLI = path.join(__dirname, '..', '..', 'bin', 'xp-gate.js');
+const REPO = path.join(__dirname, '..', '..', '..', '..');
+
+function runCheck(relPath) {
+  const started = Date.now();
+  let stdout = '';
+  let status = 0;
+  try {
+    stdout = execFileSync(process.execPath, [CLI, 'check', relPath, '--gates', 'principles'], {
+      cwd: REPO,
+      encoding: 'utf8',
+      timeout: 120000,
+    });
+  } catch (err) {
+    stdout = `${err.stdout || ''}${err.stderr || ''}`;
+    status = err.status || 1;
+  }
+  return { stdout, status, elapsed: Date.now() - started };
+}
+
+describe('check --gates 单文件自检 (#653)', () => {
+  it('AC-653-04: 传文件路径时 gate 真的执行，而不是报 spawn 失败', () => {
+    const target = 'src/npm-package/lib/doctor-brief.js';
+    expect(fs.existsSync(path.join(REPO, target))).toBe(true);
+    const { stdout } = runCheck(target);
+    // The pre-fix symptom was exactly this string followed by a FAIL verdict.
+    expect(stdout).not.toMatch(/failed to run npx tsx/);
+    expect(stdout).not.toMatch(/ENOENT|EINVAL/);
+    expect(stdout).toMatch(/principles/i);
+  });
+
+  it('AC-653-05: 单文件自检在 2 秒内给出结论', () => {
+    const { elapsed } = runCheck('src/npm-package/lib/doctor-brief.js');
+    // #653's whole value proposition: self-check before committing beats waiting
+    // for a 3-minute pre-commit. A slow "fast path" is not a fast path.
+    expect(elapsed).toBeLessThan(2000);
+  });
+});

package/lib/__tests__/doctor-brief.test.js

@@ -0,0 +1,59 @@
+/**
+ * @test REQ-653 `doctor --brief` 必须一条命令给出全部环境事实
+ * @intent 一个会话里 32.7% 的 shell 调用是纯探测（`where gcc`、`Test-Path`、
+ *         逐文件 `Get-Content`、版本探测），每次 16s 上下。这类探测的共同点是
+ *         **答案几乎不变**，却要为每个问题付一次往返。
+ *
+ *         `--brief` 的目标不是"少打印"，而是"一次问完"：模型拿到一屏结构化事实后
+ *         不需要再探任何东西。所以验收标准是**覆盖率**，不是行数——90% 的常见
+ *         探测问题必须能在这一屏里找到答案。
+ *
+ *         一个容易做错的地方：`--brief` 必须是**纯读取**。用户会因为"快"而频繁调用它，
+ *         若它顺手修了什么（比如 `--fix` 的行为），频繁调用的代价就从延迟变成了状态。
+ * @covers AC-653-01, AC-653-02, AC-653-03
+ */
+'use strict';
+
+const { buildBriefReport, BRIEF_FACTS } = require('../doctor-brief');
+
+describe('doctor --brief (#653)', () => {
+  it('AC-653-01: 覆盖常见环境探测——语言工具链、hooks、门禁、覆盖率', () => {
+    const report = buildBriefReport({ cwd: process.cwd() });
+    const keys = Object.keys(report.facts);
+    // Each of these replaces a class of exploratory probe that used to cost a
+    // round trip. If one is missing, models go back to probing for it manually.
+    for (const required of ['hooks', 'language', 'adapters', 'coverage', 'gateState']) {
+      expect(keys).toContain(required);
+    }
+    expect(BRIEF_FACTS.length).toBeGreaterThanOrEqual(5);
+  });
+
+  it('AC-653-02: 输出必须是可直接消费的结构，不是需要再解析的散文', () => {
+    const report = buildBriefReport({ cwd: process.cwd() });
+    // A model that has to regex a sentence has not saved a round trip.
+    expect(typeof report.facts.hooks.effectivePath).toBe('string');
+    expect(Array.isArray(report.facts.language.detected)).toBe(true);
+    expect(typeof report.facts.coverage.found).toBe('boolean');
+    // One-line summary for humans, but the structure carries the facts.
+    expect(typeof report.summary).toBe('string');
+    expect(report.summary.split('\n').length).toBeLessThanOrEqual(3);
+  });
+
+  it('AC-653-03: --brief 纯读取，不修改任何状态', () => {
+    const { execFileSync } = require('node:child_process');
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const before = fs.readdirSync(process.cwd()).sort().join('\n');
+    try {
+      execFileSync(process.execPath, [
+        path.join(__dirname, '..', '..', 'bin', 'xp-gate.js'), 'doctor', '--brief', '--json',
+      ], { cwd: process.cwd(), encoding: 'utf8', timeout: 120000 });
+    } catch {
+      // Exit code is not the assertion here; mutation is.
+    }
+    const after = fs.readdirSync(process.cwd()).sort().join('\n');
+    // The real cost of a --fix sneaking in is not one bad run: users call --brief
+    // often BECAUSE it is cheap, so an unintended write compounds every session.
+    expect(after).toBe(before);
+  });
+});

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

@@ -0,0 +1,58 @@
+/**
+ * @test REQ-652 BUILD 阶段的门禁清单必须从真相源生成，而非手抄
+ * @intent #652 的实证是：BUILD 阶段生成代码时，模型对 Boy Scout / CCN / jscpd /
+ *         archlint 完全不可知——不是"知道却不遵守"，是**根本不知道规则存在**。
+ *         后果是 27% 的门禁失败属于静态规则违规，即唯一 100% 可在生成前规避的类别。
+ *
+ *         补一页手写的阈值表能解决今天的问题，但会制造明天的问题：`.principlesrc`
+ *         里 `long-function` 是 50、`deep-nesting` 是 4，一旦有人调成 60/5，那一页
+ *         手抄的表就开始说谎。**一个说谎的自检清单比没有清单更糟**——它会让人按错的
+ *         规则写代码，然后在提交时被告知另一套。
+ *
+ *         所以这个清单必须从配置文件生成。真相源有几个就在几个里读，不复制。
+ * @covers AC-652-01, AC-652-02, AC-652-03
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { collectGateRules } = require('../gate-rules');
+
+const REPO = path.join(__dirname, '..', '..', '..', '..');
+
+describe('BUILD 阶段门禁清单 (#652)', () => {
+  it('AC-652-01: 从 .principlesrc 读出真实阈值，不是写死的数字', () => {
+    const rules = collectGateRules({ cwd: REPO });
+    const longFn = rules.find((r) => r.id === 'clean-code.long-function');
+    const nesting = rules.find((r) => r.id === 'clean-code.deep-nesting');
+    expect(longFn).toBeDefined();
+    expect(nesting).toBeDefined();
+    // The value must come from the config file. Reading .principlesrc here keeps the
+    // test honest: if the config changes and the generator does not follow, this fails.
+    const cfg = JSON.parse(fs.readFileSync(path.join(REPO, '.principlesrc'), 'utf8'));
+    expect(longFn.threshold).toBe(cfg.rules['clean-code']['long-function'].threshold);
+    expect(nesting.threshold).toBe(cfg.rules['clean-code']['deep-nesting'].threshold);
+  });
+
+  it('AC-652-02: 覆盖会阻断提交的每一类规则，而不只是 principles', () => {
+    const rules = collectGateRules({ cwd: REPO });
+    const sources = new Set(rules.map((r) => r.source));
+    // #652 named exactly these four as absent from BUILD docs.
+    for (const required of ['principles', 'ccn', 'jscpd', 'boy-scout']) {
+      expect(sources).toContain(required);
+    }
+  });
+
+  it('AC-652-03: 生成结果可渲染成一份自检清单，含阈值与出处', () => {
+    const rules = collectGateRules({ cwd: REPO });
+    for (const rule of rules) {
+      expect(typeof rule.id).toBe('string');
+      expect(typeof rule.source).toBe('string');
+      // Without the evidence pointer, "the threshold is 50" cannot be checked or
+      // argued with -- it is indistinguishable from a guess.
+      expect(typeof rule.evidence).toBe('string');
+      expect(rule.evidence).not.toBe('');
+      expect(['block', 'warn', 'info']).toContain(rule.severity);
+    }
+  });
+});