@xulthekl/team-flow 0.30.0 → 0.32.1

package/scripts/guard/checks/test-matrix-ready.mjs

@@ -0,0 +1,60 @@
+// scripts/guard/checks/test-matrix-ready.mjs — test preparedness gate before executing
+//
+// v0.13 §49（设计增强方案 v0.13，C1-domain-policy 事件修复，RC-3 声明驱动型绕过）：
+// full workflow 的 approved-for-build→executing 新增本维度——进入执行前强制
+// "带着矩阵开工"，缺陷在开工前暴露，而不是等 45 个文件写完才在 closing 发现。
+// 与 test-matrix-complete（出口）共用 legacy/skip 豁免语义（test-gate-exemptions.mjs）。
+import { readState } from '../../lib/state-loader.mjs';
+import {
+  isLegacyChange,
+  skipMissingReason,
+  SKIP_REASON_HINT,
+  contractDeclaresTestMatrix,
+  readTestMatrixFile,
+} from './test-gate-exemptions.mjs';
+
+/**
+ * Returns { pass, failures[], reason? }.
+ */
+export function checkTestMatrixReady(changeDir) {
+  const state = readState(changeDir);
+
+  // Exemption 1：legacy change（v0.32.0 之前初始化，无 schema_version 打戳）。
+  if (isLegacyChange(state)) {
+    return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
+  }
+
+  // Exemption 2：显式 skip（必须附理由）。
+  if (state.test_matrix_skipped === 'true') {
+    if (skipMissingReason(state)) {
+      return { pass: false, failures: [SKIP_REASON_HINT] };
+    }
+    return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
+  }
+
+  // 正常路径：契约声明 ## Test Matrix 且 test-matrix.md 存在非空。
+  const contract = contractDeclaresTestMatrix(changeDir);
+  const matrix = readTestMatrixFile(changeDir);
+  if (contract.declares && matrix.exists && !matrix.empty) {
+    return { pass: true, failures: [] };
+  }
+
+  const failures = [];
+  if (!contract.exists) {
+    failures.push('execution-contract.md is missing — run contract-builder first');
+  } else if (!contract.declares) {
+    failures.push('contract does not declare ## Test Matrix — return to bridging so contract-builder generates test-matrix.md');
+  }
+  if (contract.declares) {
+    if (!matrix.exists) {
+      failures.push('test-matrix.md is missing — generate it during bridging (contract-builder Test Matrix Generation), then run tf state rebuild');
+    } else if (matrix.empty) {
+      failures.push('test-matrix.md is empty — must contain at least a Summary section and Cases table');
+    }
+  }
+  failures.push(
+    "if this change legitimately needs no test matrix, skip explicitly: "
+    + "tf state set <dir> test_matrix_skipped true + test_matrix_skip_reason '<reason>'"
+  );
+  return { pass: false, failures };
+}

package/scripts/guard/checks/tests-passing.mjs

@@ -1,31 +1,119 @@
-// scripts/guard/checks/tests-passing.mjs — verify verification outcome is recorded as pass
+// scripts/guard/checks/tests-passing.mjs — verify test execution evidence is recorded
+//
+// v0.13 §50 重写（BUG-A 政策修正，C1-domain-policy 事件修复，RC-2 门禁锚错证据）：
+// - 非存量 change 必须提供 `tf test record` 程序化写入的结构化证据
+//   （recorded-by=tf-test-record + 证据文件存在 + failed=0 + total>0）；
+// - 废除 dp_6_result 作为等价证据（dp_6 仍是决策点记录，但不再是门禁信号）；
+// - 关闭空真：total=0 一律拒绝（除非显式 skip/legacy）；
+// - 存量 change（无 schema_version 打戳）保留 v0.31 行为——BUG-A 通道仅对存量开放。
+import fs from 'node:fs';
+import path from 'node:path';
 import { readState } from '../../lib/state-loader.mjs';
+import { isLegacyChange, skipMissingReason, SKIP_REASON_HINT } from './test-gate-exemptions.mjs';
 
 /**
- * Check that .team-flow.yaml records a passing verification outcome.
- *
- * Historically only `test_result: pass` was accepted, but release-archivist
- * records the verification result in `dp_6_result` (e.g. "pass: ..."). The
- * closing transition was unreachable because nothing ever wrote `test_result`,
- * so we accept either signal. See BUG-A (issue #28 root cause).
- *
- * Returns { pass, failures[] }.
+ * 解析结构化 test_result：
+ *   "pass: total=42 passed=42 failed=0 skipped=2 runner=maven-surefire recorded-by=tf-test-record ts=..."
+ * 返回 { verdict, total, passed, failed, skipped, runner, recordedBy, ts } 或 null。
+ */
+export function parseStructuredTestResult(raw) {
+  if (typeof raw !== 'string') return null;
+  const text = raw.trim().replace(/^["']|["']$/g, '');
+  const m = text.match(/^(pass|fail):\s*(.*)$/i);
+  if (!m) return null;
+  const fields = {};
+  for (const kv of m[2].matchAll(/([A-Za-z-]+)=(\S+)/g)) fields[kv[1]] = kv[2];
+  const toInt = (key) => (fields[key] !== undefined && /^\d+$/.test(fields[key]) ? parseInt(fields[key], 10) : null);
+  return {
+    verdict: m[1].toLowerCase(),
+    total: toInt('total'),
+    passed: toInt('passed'),
+    failed: toInt('failed'),
+    skipped: toInt('skipped'),
+    runner: fields.runner ?? null,
+    recordedBy: fields['recorded-by'] ?? null,
+    ts: fields.ts ?? null,
+  };
+}
+
+const SKIP_OR_RECORD_HINT =
+  "Run the project test suite, then record it: tf test record <dir> --from <runner-output-file>. "
+  + "If this change legitimately has no automated tests, skip explicitly: "
+  + "test_matrix_skipped=true + test_matrix_skip_reason='<reason>'";
+
+/**
+ * Returns { pass, failures[], reason? }.
  */
 export function checkTestsPassing(changeDir) {
   const state = readState(changeDir);
-  const markers = [state.test_result, state.dp_6_result];
-  const passed = markers.some((v) => {
-    if (typeof v !== 'string') return false;
-    const normalized = v.trim().replace(/^["']|["']$/g, '');
-    return normalized.toLowerCase().startsWith('pass');
-  });
-  if (passed) {
-    return { pass: true, failures: [] };
+
+  // Legacy（无 schema_version）：保留 v0.31 行为（BUG-A 通道仅对存量开放）。
+  if (isLegacyChange(state)) {
+    const markers = [state.test_result, state.dp_6_result];
+    const passed = markers.some((v) => {
+      if (typeof v !== 'string') return false;
+      const normalized = v.trim().replace(/^["']|["']$/g, '');
+      return normalized.toLowerCase().startsWith('pass');
+    });
+    if (passed) {
+      return { pass: true, failures: [] };
+    }
+    return {
+      pass: false,
+      failures: [
+        `verification outcome missing (legacy): test_result is '${state.test_result || 'null'}' and dp_6_result is '${state.dp_6_result || 'null'}' — expected a result starting with 'pass'. Run release-archivist verification (DP-6) first.`,
+      ],
+    };
   }
-  return {
-    pass: false,
-    failures: [
-      `verification outcome missing: test_result is '${state.test_result || 'null'}' and dp_6_result is '${state.dp_6_result || 'null'}' — expected a result starting with 'pass'. Run release-archivist verification (DP-6) first.`,
-    ],
-  };
-}
+
+  // 显式 skip（必须附理由）。
+  if (state.test_matrix_skipped === 'true') {
+    if (skipMissingReason(state)) {
+      return { pass: false, failures: [SKIP_REASON_HINT] };
+    }
+    return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
+  }
+
+  // 非存量：要求 tf test record 写入的结构化证据。
+  const parsed = parseStructuredTestResult(state.test_result);
+  if (!parsed) {
+    return {
+      pass: false,
+      failures: [`no programmatic test evidence recorded — test_result is '${state.test_result || 'null'}'. ${SKIP_OR_RECORD_HINT}`],
+    };
+  }
+  if (parsed.recordedBy !== 'tf-test-record') {
+    return {
+      pass: false,
+      failures: [
+        "test_result must be recorded by 'tf test record' (programmatic evidence); manually written values are not accepted (v0.13 §50)",
+      ],
+    };
+  }
+  // 证据文件必须存在（纵深防御：记录必须可追溯到落盘的 runner 输出）。
+  if (!state.test_evidence_path || !fs.existsSync(path.join(changeDir, state.test_evidence_path))) {
+    return {
+      pass: false,
+      failures: [
+        'test evidence file missing — test_result must trace to a saved runner output recorded by tf test record (.superpowers/test-evidence/)',
+      ],
+    };
+  }
+  if (parsed.verdict !== 'pass' || (parsed.failed ?? 0) !== 0) {
+    return {
+      pass: false,
+      failures: [
+        `test suite reported failures (failed=${parsed.failed ?? '?'}) — fix the failures, re-run the suite, and record again via tf test record`,
+      ],
+    };
+  }
+  if (!Number.isInteger(parsed.total) || parsed.total <= 0) {
+    return {
+      pass: false,
+      failures: [
+        'test_result records total=0 — an empty suite is not evidence; add tests or skip explicitly (test_matrix_skipped=true + reason)',
+      ],
+    };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/guard.mjs

@@ -14,6 +14,8 @@ import { checkDp3Approved } from './checks/dp3-approved.mjs';
 import { checkExecutionPlanReady } from './checks/execution-plan-ready.mjs';
 import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.mjs';
 import { checkCompoundCaptured } from './checks/compound-captured.mjs';
+import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
+import { checkTestMatrixReady } from './checks/test-matrix-ready.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
@@ -21,8 +23,10 @@ const TRANSITION_CHECKS = {
   'exploring:specifying':           ['artifacts-exist', 'arch-design'],
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
   'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
-  'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready'],
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
+  // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度
+  //（矩阵存在非空 OR 显式 skip 附理由；legacy 豁免）。hotfix/tweak 沿用 §45.3 豁免，不挂。
+  'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],
+  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -55,6 +59,8 @@ const WORKFLOW_TRANSITION_CHECKS = {
     'exploring:bridging': [],
     'bridging:approved-for-build': ['contract-current', 'dp3-approved'],
     'approved-for-build:executing': ['contract-current', 'dp3-approved', 'execution-plan-ready'],
+    // hotfix exemption: no test-matrix-complete (v0.12 §45.3)
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
   },
   tweak: {
     'exploring:approved-for-build': [],
@@ -167,6 +173,8 @@ async function main() {
     'execution-reviews-passed': (dir) => checkExecutionReviewsPassed(dir),
     'arch-design': (dir) => checkArchDesign(dir),
     'compound-captured': (dir) => checkCompoundCaptured(dir),
+    'test-matrix-complete': (dir) => checkTestMatrixComplete(dir),
+    'test-matrix-ready': (dir) => checkTestMatrixReady(dir),
   };
 
   const checks = [];

package/scripts/lib/cmd-doctor.mjs

@@ -258,6 +258,47 @@ function checkChangeStates(root) {
   return { pass: true, message: `${checked} change(s) have legal state values` };
 }
 
+// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）：
+// 1. test_matrix_skipped=true 必须附 test_matrix_skip_reason（可审计豁免）；
+// 2. 状态引用的产物文件必须存在（arch_review_report / test_evidence_path）——
+//    C1 现场曾出现 arch_review_report 指向不存在的 auto-review.md。
+// DP 时间戳顺序检查评估后未纳入：closing 后的 DP-7 时间戳晚于 last_transition 属合法，
+//  blanket 检查会误报，收益不抵风险。
+function checkChangeTestGates(root) {
+  const changesDir = join(root, 'changes');
+  if (!existsSync(changesDir)) {
+    return { pass: true, message: 'no changes/ directory (skipped)' };
+  }
+  const dirs = readdirSync(changesDir).filter(f => {
+    try { return statSync(join(changesDir, f)).isDirectory(); } catch { return false; }
+  });
+  const issues = [];
+  let checked = 0;
+  for (const d of dirs) {
+    const changeDir = join(changesDir, d);
+    if (!existsSync(join(changeDir, '.team-flow.yaml'))) continue;
+    checked += 1;
+    const state = readState(changeDir);
+    if (state.test_matrix_skipped === 'true'
+      && !(typeof state.test_matrix_skip_reason === 'string' && state.test_matrix_skip_reason.trim())) {
+      issues.push(`${d}: test_matrix_skipped=true without test_matrix_skip_reason`);
+    }
+    for (const field of ['arch_review_report', 'test_evidence_path']) {
+      const ref = state[field];
+      if (typeof ref === 'string' && ref.trim() && !existsSync(join(changeDir, ref))) {
+        issues.push(`${d}: ${field} references missing file '${ref}'`);
+      }
+    }
+  }
+  if (checked === 0) {
+    return { pass: true, message: 'no state files under changes/ (skipped)' };
+  }
+  if (issues.length > 0) {
+    return { pass: false, message: issues.join('; ') };
+  }
+  return { pass: true, message: `${checked} change(s) pass test-gate hygiene (skip reasons + artifact references)` };
+}
+
 export async function run(args) {
   const root = process.cwd();
   const config = loadConfig(root);
@@ -275,6 +316,7 @@ export async function run(args) {
     ['Node.js', checkNodeVersion()],
     ['Docs', checkDocs(root)],
     ['Change states', checkChangeStates(root)],
+    ['Change test gates', checkChangeTestGates(root)],
   ];
 
   // Config check
@@ -303,4 +345,4 @@ export async function run(args) {
   }
 }
 
-export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs, checkChangeStates };
+export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs, checkChangeStates, checkChangeTestGates };

package/scripts/lib/cmd-execution.mjs

@@ -22,6 +22,10 @@ export async function run(args) {
       head: { type: 'string' },
       report: { type: 'string' },
       verdict: { type: 'string' },
+      // v0.13 §51.2：wave 级测试统计（可选证据字段，三个须同时提供）
+      'tests-total': { type: 'string' },
+      'tests-passed': { type: 'string' },
+      'tests-failed': { type: 'string' },
       json: { type: 'boolean', default: false },
       help: { type: 'boolean', default: false },
     },
@@ -137,6 +141,7 @@ function recordAndPrintReview(changeDir, values) {
     base: values.base,
     head: values.head,
     report: values.report,
+    tests: parseTestsStats(values),
   });
   print(values.json, { ok: true, wave: values.wave[0], receipt }, `Review for ${values.wave[0]} recorded: ${receipt.status}.`);
 }
@@ -180,6 +185,24 @@ function requireOption(value, option) {
   if (typeof value !== 'string' || !value.trim()) throw new Error(`${option} is required`);
 }
 
+// v0.13 §51.2：--tests-total/--tests-passed/--tests-failed 三个须同时提供且为非负整数。
+function parseTestsStats(values) {
+  const raw = {
+    total: values['tests-total'],
+    passed: values['tests-passed'],
+    failed: values['tests-failed'],
+  };
+  const provided = Object.values(raw).filter(v => v !== undefined);
+  if (provided.length === 0) return undefined;
+  if (provided.length < 3) throw new Error('--tests-total, --tests-passed and --tests-failed must be provided together');
+  const parsed = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!/^\d+$/.test(String(value))) throw new Error(`--tests-${key} must be a non-negative integer`);
+    parsed[key] = parseInt(value, 10);
+  }
+  return parsed;
+}
+
 function requireSafeReason(reason) {
   if (/[\p{Cc}\p{Zl}\p{Zp}]/u.test(reason)) {
     throw new Error('--reason must not contain control characters or line separators');
@@ -202,5 +225,5 @@ function printHelp() {
   tf execution plan <dir> --mode <mode> --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
   tf execution show <dir> [--json]
   tf execution revise <dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
-  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail`);
+  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--tests-total N --tests-passed N --tests-failed N]`);
 }

package/scripts/lib/cmd-state.mjs

@@ -7,12 +7,16 @@ import { fileURLToPath } from 'node:url';
 // VALID_STATES 统一从 state-loader.mjs 引入(状态机合法值唯一真相源),不再本地硬编码。
 // 来源:workflow-feedback 2026-08-01,#100005。
 import { readState, writeState, updateField, rebuildState, VALID_STATES } from './state-loader.mjs';
-import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+import { computeArtifactsHash, computeContractHash, computeTestMatrixHash } from './hash.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// v0.13 §50（BUG-A 政策修正）：test_result 移出可手工设置字段——测试证据必须经
+// tf test record 程序化记录，手工自述值不再被 tests-passing 门禁接受。
+// v0.13 §48.2：test_matrix_skip_reason 可设置（显式 skip 的理由留痕）。
+// schema_version 不可设置（仅 init 打戳，防止伪造豁免身份，v0.13 §48.1）。
 const SETTABLE_FIELDS = [
-  'workflow', 'test_result', 'batches_completed', 'spec_merged',
+  'workflow', 'batches_completed', 'spec_merged',
   'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
   'dp_1_result', 'dp_1_timestamp', 'dp_1_decisions', 'dp_1_confirmed',
   'dp_2_result', 'dp_2_timestamp', 'dp_2_decisions', 'dp_2_confirmed',
@@ -29,6 +33,8 @@ const SETTABLE_FIELDS = [
   'dp_a_result', 'dp_a_timestamp', 'dp_a_adjustments',
   // Compound engineering capture gate (v0.24.0 复利贯穿强制化)
   'compound_skipped',
+  // Test matrix gate (v0.12 §45.4 + v0.13 §48.2)
+  'test_matrix_skipped', 'test_matrix_skip_reason',
 ];
 
 export async function run(args) {
@@ -82,17 +88,27 @@ export async function run(args) {
       if (!existsSync(changeDir)) {
         mkdirSync(changeDir, { recursive: true });
       }
+      // v0.13 §48.1：schema_version 只在 change 创建（状态文件尚不存在）时打戳。
+      // 对已有状态文件的目录重新 init 不得追加打戳——"字段缺失"是存量豁免键，
+      // 追加会把真存量 change 错误地纳入 v0.32 严格门禁。
+      const stateFileExisted = existsSync(join(changeDir, '.team-flow.yaml'));
       const hash = computeArtifactsHash(changeDir);
       const ch = computeContractHash(changeDir);
+      const tmh = computeTestMatrixHash(changeDir);
       const state = readState(changeDir);
+      if (!stateFileExisted) {
+        state.schema_version = 1;
+      }
       state.artifacts_hash = hash;
       state.contract_hash = ch;
+      // v0.12 §42.5: test_matrix_hash is independent from artifacts_hash
+      state.test_matrix_hash = tmh;
       state.last_transition = new Date().toISOString();
       writeState(changeDir, state);
       if (values.json) {
-        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch }));
+        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch, test_matrix_hash: tmh, schema_version: state.schema_version ?? null }));
       } else {
-        console.log(`State initialized. artifacts_hash: ${hash}`);
+        console.log(`State initialized. artifacts_hash: ${hash}` + (tmh ? `, test_matrix_hash: ${tmh}` : '') + (state.schema_version != null ? `, schema_version: ${state.schema_version}` : ''));
       }
       break;
     }
@@ -209,7 +225,7 @@ export async function run(args) {
       break;
     }
     case 'rebuild': {
-      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash });
+      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash, computeTestMatrixHash });
       if (values.json) {
         console.log(JSON.stringify({ ok: true, state: state.state }));
       } else {
@@ -235,6 +251,18 @@ export async function run(args) {
             `   tf state transition <change-dir 绝对路径> <目标状态>\n` +
             `   合法状态:${VALID_STATES.join('/')}`
           );
+        } else if (field === 'test_result') {
+          // v0.13 §50（BUG-A 政策修正）：测试证据程序化，手工自述通道关闭。
+          console.error(
+            `⛔ 'test_result' 不再支持手工 set(v0.13 §50)。测试证据必须程序化记录:\n` +
+            `   运行项目测试套件后: tf test record <change-dir> --from <runner 输出文件>\n` +
+            `   确无自动化测试时显式跳过(可审计): tf state set <dir> test_matrix_skipped true\n` +
+            `                                    + tf state set <dir> test_matrix_skip_reason "<理由>"`
+          );
+        } else if (field === 'schema_version') {
+          console.error(
+            `⛔ 'schema_version' 不可手工设置(v0.13 §48.1)。它只由 tf state init 在 change 创建时打戳,是测试门禁的存量豁免键。`
+          );
         } else {
           console.error(`⛔ Field '${field}' is not settable (use 'transition' for state, or check SETTABLE_FIELDS)`);
         }

package/scripts/lib/cmd-validate.mjs

@@ -3,6 +3,8 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { loadConfig } from './config-loader.mjs';
 import { validateSpecPathLayout, relativeSpecPath } from './spec-paths.mjs';
+import { readState } from './state-loader.mjs';
+import { computeTestMatrixHash } from './hash.mjs';
 
 async function getValidator() {
   const mod = await import('../../dist/index.js');
@@ -94,6 +96,46 @@ export async function run(args) {
     if (!report.valid) hasErrors = true;
   }
 
+  // v0.13 §52 B1：test-matrix 双向互锁（contract '## Test Matrix' 段 ↔ test-matrix.md）
+  // 非存量（有 schema_version 打戳）且未显式 skip 的 change：
+  //   契约声明段 → 矩阵文件必须存在非空；矩阵文件存在 → 契约必须声明段（孤儿矩阵）。
+  // 两者皆无不算错（矩阵是否必产由 test-matrix-ready 门禁在转换时强制）。
+  const contractForMatrixPath = join(changeDir, 'execution-contract.md');
+  if (existsSync(contractForMatrixPath)) {
+    const stateForMatrix = readState(changeDir);
+    const legacyChange = stateForMatrix.schema_version == null;
+    const matrixSkipped = stateForMatrix.test_matrix_skipped === 'true';
+    const contractContent = readFileSync(contractForMatrixPath, 'utf-8');
+    const declaresMatrix = contractContent.includes('## Test Matrix');
+    const matrixPath = join(changeDir, 'test-matrix.md');
+    const matrixExists = existsSync(matrixPath) && readFileSync(matrixPath, 'utf-8').trim().length > 0;
+    const issues = [];
+    if (!legacyChange && !matrixSkipped) {
+      if (declaresMatrix && !matrixExists) {
+        issues.push({ level: 'ERROR', path: 'test-matrix.md', message: 'contract declares ## Test Matrix but test-matrix.md is missing or empty — generate the matrix (contract-builder) or remove the section' });
+      }
+      if (!declaresMatrix && matrixExists) {
+        issues.push({ level: 'ERROR', path: 'execution-contract.md', message: 'test-matrix.md exists but contract does not declare ## Test Matrix — add the section or remove the orphaned matrix' });
+      }
+    }
+    if (declaresMatrix && matrixExists) {
+      const computed = computeTestMatrixHash(changeDir);
+      if (!stateForMatrix.test_matrix_hash) {
+        issues.push({ level: 'WARNING', path: 'test-matrix.md', message: "test_matrix_hash not recorded — run 'tf state rebuild' to capture the matrix hash" });
+      } else if (stateForMatrix.test_matrix_hash !== computed) {
+        issues.push({ level: 'WARNING', path: 'test-matrix.md', message: "test_matrix_hash drifted from test-matrix.md — run 'tf state rebuild'" });
+      }
+    }
+    if (issues.length > 0) {
+      printReport('test-matrix cross-lock', {
+        valid: issues.filter(i => i.level === 'ERROR').length === 0,
+        issues,
+        summary: { errors: issues.filter(i => i.level === 'ERROR').length, warnings: issues.filter(i => i.level === 'WARNING').length, info: 0 },
+      });
+      if (issues.some(i => i.level === 'ERROR')) hasErrors = true;
+    }
+  }
+
   console.log('');
   if (hasErrors) {
     console.log('❌ Validation failed with errors.');

package/scripts/lib/execution-plan.mjs

@@ -132,12 +132,26 @@ export function recordReview(changeDir, waveId, receipt) {
   for (const field of ['base', 'head']) requireText(receipt?.[field], `receipt.${field}`);
   const report = validateReviewReportEvidence(changeDir, receipt?.report);
   const { base, head } = validateReviewRange(changeDir, receipt.base, receipt.head);
+  // v0.13 §51.2：测试统计为可选证据字段（提供时必须为非负整数）。
+  // 硬门禁在入口（test-matrix-ready）与 closing（tests-passing），此处只沉淀证据，
+  // 避免单 wave 零测试造成 BUG-A 式过严死锁（DDL/脚手架类 wave 可能合理无测试）。
+  let tests;
+  if (receipt?.tests !== undefined) {
+    if (!isObject(receipt.tests)) throw new Error('receipt.tests must be an object');
+    for (const key of ['total', 'passed', 'failed']) {
+      if (!Number.isInteger(receipt.tests[key]) || receipt.tests[key] < 0) {
+        throw new Error(`receipt.tests.${key} must be a non-negative integer`);
+      }
+    }
+    tests = { total: receipt.tests.total, passed: receipt.tests.passed, failed: receipt.tests.failed };
+  }
 
   const savedReceipt = {
     status: receipt.status,
     base,
     head,
     report,
+    ...(tests ? { tests } : {}),
     plan_hash: plan.hash,
     plan_revision: plan.revision,
     recorded_at: new Date().toISOString(),
@@ -252,6 +266,15 @@ function validateReviewRange(changeDir, base, head) {
   const gitRoot = getGitRoot(changeDir);
   const resolvedBase = resolveGitCommit(gitRoot, base, 'base');
   const resolvedHead = resolveGitCommit(gitRoot, head, 'head');
+  // v0.13 §51.1：禁止空 diff review（base === head）。
+  // C1-domain-policy 现场曾出现 6 个 receipt 全部 base==head==初始 commit，
+  // 即 review 对空 diff 进行。本校验同时强制"每 wave 落 commit"的纪律。
+  if (resolvedBase === resolvedHead) {
+    throw new Error(
+      'Review receipt base must differ from head — head must contain new commits over base; '
+      + 'commit the wave changes before recording a review'
+    );
+  }
   try {
     execFileSync('git', ['-C', gitRoot, 'merge-base', '--is-ancestor', resolvedBase, resolvedHead], {
       stdio: 'ignore',

package/scripts/lib/hash.mjs

@@ -67,6 +67,17 @@ export function computeContractHash(changeDir) {
   return `sha256:${hash.digest('hex')}`;
 }
 
+// Compute SHA256 hash of test-matrix.md alone (v0.12 §42.5).
+// Independent from artifacts_hash to avoid self-circulation:
+// modify matrix → contract stale → rollback bridging → regenerate matrix.
+export function computeTestMatrixHash(changeDir) {
+  const matrix = path.join(changeDir, 'test-matrix.md');
+  if (!fs.existsSync(matrix)) return null;
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(matrix, 'utf-8'));
+  return `sha256:${hash.digest('hex')}`;
+}
+
 // Fast staleness check: compare stored artifacts_hash against current.
 export function isContractFresh(changeDir, stateLoader) {
   const stateFile = path.join(changeDir, '.team-flow.yaml');

package/scripts/lib/state-loader.mjs

@@ -61,6 +61,14 @@ const BUILTIN_DEFAULTS = {
   dp_a_adjustments: null,
   // Compound engineering capture gate (v0.24.0 复利贯穿强制化)
   compound_skipped: null,
+  // Test matrix gate (v0.12 §42.5 + §45.4; v0.13 §48 补 skip 理由字段)
+  test_matrix_hash: null,
+  test_matrix_skipped: null,
+  test_matrix_skip_reason: null,
+  // Test evidence (v0.13 §50：tf test record 落盘的 runner 输出证据路径)
+  test_evidence_path: null,
+  // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
+  // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
 
 /**
@@ -105,6 +113,11 @@ export function writeState(changeDir, state) {
   lines.push(`state: ${state.state || 'exploring'}`);
   lines.push(`workflow: ${state.workflow || 'auto'}`);
   lines.push(`revision: ${state.revision ?? 'null'}`);
+  // v0.13 §48.1：schema_version 仅由 tf state init 在 change 创建时打戳；
+  // 缺失 = 存量 change（测试门禁豁免键）。rebuild/set 不追加，故条件序列化。
+  if (state.schema_version != null) {
+    lines.push(`schema_version: ${state.schema_version}`);
+  }
   lines.push('');
   lines.push('# === Hashes (fast staleness detection) ===');
   lines.push(`artifacts_hash: ${state.artifacts_hash ?? 'null'}`);
@@ -162,6 +175,14 @@ export function writeState(changeDir, state) {
   lines.push('');
   lines.push('# === Compound engineering capture gate (v0.24.0) ===');
   lines.push(`compound_skipped: ${state.compound_skipped ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Test matrix gate (v0.12 §42.5 + v0.13 §48) ===');
+  lines.push(`test_matrix_hash: ${state.test_matrix_hash ?? 'null'}`);
+  lines.push(`test_matrix_skipped: ${state.test_matrix_skipped ?? 'null'}`);
+  lines.push(`test_matrix_skip_reason: ${state.test_matrix_skip_reason ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Test evidence (v0.13 §50) ===');
+  lines.push(`test_evidence_path: ${state.test_evidence_path ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }
@@ -179,10 +200,14 @@ export function updateField(changeDir, field, value) {
  * Rebuild state file from artifacts — recomputes hashes.
  * Requires hash functions to be passed in (avoids circular dependency).
  */
-export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash }) {
+export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash, computeTestMatrixHash }) {
   const state = readState(changeDir);
   state.artifacts_hash = computeArtifactsHash(changeDir);
   state.contract_hash = computeContractHash(changeDir);
+  // v0.12 §42.5: test_matrix_hash is independent from artifacts_hash
+  if (computeTestMatrixHash) {
+    state.test_matrix_hash = computeTestMatrixHash(changeDir);
+  }
   writeState(changeDir, state);
   return state;
 }