@boyingliu01/xp-gate 0.35.6 → 0.35.8

package/bin/xp-gate.js

@@ -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

@@ -342,7 +342,9 @@ file_exists_in_subdir() {
 # in every gate, so their definitions lead the first call.
 # ============================================================================
 AUDIT_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT_FOR_AUDIT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$AUDIT_SCRIPT_DIR/../..")"
+# PROJECT_ROOT is resolved once above (line ~235); re-running `git rev-parse` here
+# costs another ~90ms fork on every commit for the same answer (#640).
+PROJECT_ROOT_FOR_AUDIT="${PROJECT_ROOT:-$(cd "$AUDIT_SCRIPT_DIR/../.." 2>/dev/null && pwd)}"
 
 # Audit attribution safety net: if a previous commit's post-commit never fired
 # (hooks skipped, crash, or an earlier --no-verify), its staged entries are
@@ -759,6 +761,10 @@ if [ "$is_protected" = "true" ]; then
   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 ;;
@@ -918,7 +924,7 @@ echo ""
 # scope rationale as the mirror exclusion (#507 Delphi round-2 follow-up).
 MIRROR_PATH_FILTER='^src/npm-package/'
 DASHBOARD_PATH_FILTER='^dashboard/'
-RAW_CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+RAW_CHANGED_FILES="${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM)}"
 
 # Dependencies and build output are not project code (#649).
 #
@@ -2345,7 +2351,7 @@ else
   GATE_5_SKIP_COUNT=0
   GATE_5_DELETED_TESTS=""
   if declare -f classify_test_focus >/dev/null 2>&1; then
-    STAGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+    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)
     if [ -n "$STAGED_TEST_FILES" ]; then
       while IFS= read -r _tf; do
@@ -2395,17 +2401,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:"
@@ -2705,7 +2757,7 @@ else
   # Gate 5b: Mock Density ADVISORY Scan (pure bash — no npx tsx overhead)
   # 30% = ADVISORY, 50% = suggests @mock-justified. Does NOT block commit.
   # ========================================================================
-  CHANGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM | filter_project_paths | grep -E '\.(test|spec)\.(ts|tsx|js|jsx|cjs|mjs|py|go)$' || true)
+  CHANGED_TEST_FILES=$(printf '%s\n' "${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM)}" | filter_project_paths | grep -E '\.(test|spec)\.(ts|tsx|js|jsx|cjs|mjs|py|go)$' || true)
 
   # Nested plugin sub-projects (plugins/<name>/) own their own vitest config and
   # are excluded from the root suite (`vitest.config.ts` excludes `plugins/**`,
@@ -2853,7 +2905,7 @@ else
           CHANGED_TEST_FILE_COUNT=$(echo "$SELECTED_TEST_FILES" | grep -c '.' || true)
           
           # Also get changed source files (non-test) for related-test lookup
-          CHANGED_SRC_FILES=$(git diff --cached --name-only --diff-filter=ACM | filter_project_paths | grep -E '\.(ts|tsx|js|jsx)$' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__tests__' | grep -v '\.d\.ts$' | grep -v '__snapshots__' || true)
+          CHANGED_SRC_FILES=$(printf '%s\n' "${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM)}" | filter_project_paths | grep -E '\.(ts|tsx|js|jsx)$' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__tests__' | grep -v '\.d\.ts$' | grep -v '__snapshots__' || true)
           # Nested plugin sub-projects are excluded from the root suite; their
           # sources must not drive root-vitest related-test lookup either (it
           # would resolve to plugin-local paths vitest cannot collect).
@@ -3088,16 +3140,16 @@ else
             #     partial so Stage 2 warns instead of falsely blocking.
             #   full -> unchanged behavior: whole suite + real threshold.
             #   skip -> nothing test-relevant changed; no pytest at all.
-            PY_CHANGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+            PY_CHANGED_TEST_FILES=$(printf '%s\n' "${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null)}" \
               | filter_project_paths \
               | grep -E '(^|/)test_[^/]*\.py$|_test\.py$' || true)
-            PY_CHANGED_SRC_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+            PY_CHANGED_SRC_FILES=$(printf '%s\n' "${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null)}" \
               | filter_project_paths \
               | grep -E '\.py$' | grep -vE '(^|/)test_[^/]*\.py$|_test\.py$' || true)
             # NOT filtered on purpose: this list answers "did a requirements
             # file change", which is a property of the whole commit including
             # paths under a vendor/ tree that filter_project_paths removes.
-            PY_CHANGED_ALL=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)
+            PY_CHANGED_ALL="${XP_STAGED_ACM:-$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)}"
             # `grep -c '.'` prints its own zero AND exits 1 on an empty list
             # (#493), so the count is derived with `|| true` + wc -l instead.
             PY_TEST_COUNT=$(printf '%s\n' "$PY_CHANGED_TEST_FILES" | grep -c '.' || true)
@@ -3844,14 +3896,21 @@ else
           exit 1
         fi
          echo "     Running archlint for TypeScript..."
-          # Use diff mode with baseline for ratchet (block only new violations)
-          # Fall back to raw scan if no baseline exists (new project, zero-tolerance)
-          if [ -f "$PROJECT_ROOT/.architecture-baseline.json" ]; then
+          # #640: archlint costs ~8s and scans the whole tree, but an architecture
+          # violation cannot be introduced by a commit that touches no source file.
+          # Gating on "did any source change" removes the single largest fixed cost
+          # from docs/config-only commits without weakening the check at all.
+          if ! printf '%s\n' "${XP_STAGED_ACM:-}" | grep -qE '\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|kts|rs|cpp|cc|cxx|c|h|hpp|swift|dart)$'; then
+            echo "     ⏭️  SKIPPED - Architecture validation (no source files changed)"
+            ARCHLINT_OUTPUT=""
+            ARCHLINT_EXIT=0
+          elif [ -f "$PROJECT_ROOT/.architecture-baseline.json" ]; then
             ARCHLINT_OUTPUT=$(run_archlint diff .architecture-baseline.json --fail-on high 2>&1)
+            ARCHLINT_EXIT=$?
           else
             ARCHLINT_OUTPUT=$(run_archlint scan . -f table --quiet 2>&1)
+            ARCHLINT_EXIT=$?
           fi
-         ARCHLINT_EXIT=$?
          echo "$ARCHLINT_OUTPUT" | tail -30
          if [ "$ARCHLINT_EXIT" -ne 0 ]; then
            echo ""
@@ -4560,7 +4619,58 @@ fi
 # ============================================================================
 
 # ============================================================================
-# GATE 13: Compiler Strictness Check
+# GATE 12b: Mirror Parity (#654)
+#
+# `githooks/**` and `plugins/*/src/**` are canonical; `src/npm-package/**` holds
+# byte-identical mirrors that get published. Editing only the mirror means the next
+# prepack silently regenerates it over the change -- v0.27.3 shipped exactly that
+# bug, and mirror/sync rework accounts for 58 failures in the session logs.
+#
+# The check used to run only at pre-push, which turns a two-second fix into a
+# five-minute wait. It runs here now, but ONLY over files in this commit: a
+# full-tree scan on every commit is the cost that pushed it to pre-push in the
+# first place.
+# ============================================================================
+MIRROR_STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+if [ -n "$MIRROR_STAGED" ] && printf '%s\n' "$MIRROR_STAGED" | grep -qE '^(githooks/|plugins/[^/]+/src/)'; then
+  # Reuse PROJECT_ROOT: `git rev-parse` costs ~90ms per fork on Windows and this
+  # gate must not add two of them to every commit (#640).
+  MIRROR_REPO_ROOT="${PROJECT_ROOT:-}"
+  if [ -n "$MIRROR_REPO_ROOT" ] && [ -f "$MIRROR_REPO_ROOT/scripts/check-hook-mirror.sh" ]; then
+    # Scope to the touched families only: a mirror pair is clean or dirty
+    # independently, and checking untouched families is the slow path this gate
+    # exists to avoid.
+    MIRROR_FAIL=0
+    while IFS= read -r _mf; do
+      [ -n "$_mf" ] || continue
+      case "$_mf" in
+        githooks/*) _mm="src/npm-package/hooks/${_mf#githooks/}" ;;
+        plugins/*/src/*) _mm=$(printf '%s' "$_mf" | sed 's|^plugins/\([^/]*\)/src/|src/npm-package/plugins/\1/src/|') ;;
+        *) continue ;;
+      esac
+      if [ ! -f "$MIRROR_REPO_ROOT/$_mm" ]; then
+        echo "❌ BLOCKED - Gate 12b: $_mf has no mirror at $_mm"
+        echo "     Run: node src/npm-package/scripts/sync-package-content.js --fix"
+        MIRROR_FAIL=$((MIRROR_FAIL + 1))
+      elif ! cmp -s "$MIRROR_REPO_ROOT/$_mf" "$MIRROR_REPO_ROOT/$_mm"; then
+        echo "❌ BLOCKED - Gate 12b: $_mm differs from canonical $_mf"
+        echo "     Run: node src/npm-package/scripts/sync-package-content.js --fix"
+        MIRROR_FAIL=$((MIRROR_FAIL + 1))
+      fi
+    done <<< "$MIRROR_STAGED"
+    if [ "$MIRROR_FAIL" -gt 0 ]; then
+      echo ""
+      echo "❌ BLOCKED - Gate 12b: $MIRROR_FAIL mirror parity violation(s)."
+      echo "   The mirror is what gets published; a mirror-only fix is silently"
+      echo "   reverted by the next prepack (v0.27.3 shipped that bug)."
+      GATE_FAILED=1
+    else
+      echo "✅ PASSED - Gate 12b: mirror parity (touched files)"
+    fi
+  fi
+fi
+# ============================================================================
+
 # The compiler is the first and cheapest static analyser for a compiled language
 # and XP-Gate never used it as one: cpp.sh only runs clang-tidy/cppcheck over the
 # first 20 files, and Gate 9's build-integrity half is TypeScript-and-Maven only.

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__/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);
+    }
+  });
+});

package/lib/__tests__/mirror-manifest.test.js

@@ -0,0 +1,64 @@
+/**
+ * @test REQ-654 镜像清单必须自证完整：漏登记的规范源文件要报错，而不是静默不同步
+ * @intent 会话日志里 `mirror/sync` 类失败 **58 次**，git 历史反复出现
+ *         `fix(mirror): ...` / `fix(package): 把 java.sh 改动落到真正的源文件`。
+ *
+ *         根因不是模型不知道规则——`AGENTS.md` 写得很清楚——而是这类约束是
+ *         **结构性信息**：哪个文件是源、哪个是镜像、谁依赖谁。模型即使知道规则，
+ *         也要在多文件编辑中持续追踪映射关系，而这正是工具该做的事。
+ *
+ *         提示词救不了的部分，必须靠**漏登记即报错**来兜底。静默不同步是最坏的形态：
+ *         它让一次疏忽变成一次发布回滚（v0.27.3 正是只改镜像导致发布回滚）。
+ * @covers AC-654-01, AC-654-02, AC-654-03
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { findUnlistedSources, declareSources } = require('../mirror-manifest');
+
+const REPO = path.join(__dirname, '..', '..', '..', '..');
+
+describe('镜像清单完整性 (#654)', () => {
+  it('AC-654-01: 列出 canonical 目录下所有应被镜像的文件', () => {
+    const declared = declareSources({ cwd: REPO });
+    expect(Array.isArray(declared)).toBe(true);
+    // A manifest that silently returns nothing would pass every other assertion here,
+    // so pin the shape: real file lists are non-trivial.
+    expect(declared.length).toBeGreaterThan(20);
+    for (const entry of declared) {
+      expect(typeof entry.source).toBe('string');
+      expect(typeof entry.mirror).toBe('string');
+      // Both paths are repo-relative, forward-slashed, so drift messages are readable.
+      expect(entry.source.includes('\\')).toBe(false);
+      expect(entry.mirror.includes('\\')).toBe(false);
+    }
+  });
+
+  it('AC-654-02: 实际存在的规范源文件若未登记，必须被报出来', () => {
+    const unlisted = findUnlistedSources({ cwd: REPO });
+    // The invariant the issue asks for: zero unlisted sources. This is the assertion
+    // that turns "someone forgot to register java.sh" from a publish-time rollback
+    // into a red test at commit time.
+    expect(unlisted).toEqual([]);
+  });
+
+  it('AC-654-03: 合成一个未登记文件时能被检出（防止检测器本身失效）', () => {
+    // A detector that never fires is indistinguishable from "no drift". Prove it fires
+    // on a synthetic tree rather than trusting the empty result above.
+    const fixture = {
+      'githooks/pre-commit': 'x',
+      'githooks/lib/known.sh': 'x',
+      'githooks/lib/orphan.sh': 'x',
+    };
+    const unlisted = findUnlistedSources({
+      cwd: REPO,
+      files: Object.keys(fixture),
+      declared: [
+        { source: 'githooks/pre-commit', mirror: 'src/npm-package/hooks/pre-commit' },
+        { source: 'githooks/lib/known.sh', mirror: 'src/npm-package/hooks/lib/known.sh' },
+      ],
+    });
+    expect(unlisted).toEqual(['githooks/lib/orphan.sh']);
+  });
+});