@xulthekl/team-flow 0.31.0 → 0.32.2

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

@@ -1,60 +1,84 @@
 // scripts/guard/checks/test-matrix-complete.mjs — verify test matrix exists and is consistent
-import fs from 'node:fs';
-import path from 'node:path';
+//
+// v0.13 §48 重写（C1-domain-policy 事件修复，RC-1/RC-3）：
+// 豁免键由 contract 内容改为 state schema_version；删除 v0.12 的两条结构性豁免：
+//   ✗ "contract 无 '## Test Matrix' 段 → PASS"（内容型豁免，新 change 漏生成矩阵同样命中）
+//   ✗ "stored hash 为 null 时短路跳过一致性校验"（矩阵生成后未 rebuild 即无保护）
+// 判定顺序见设计增强方案 v0.13 §48.3。
 import { readState } from '../../lib/state-loader.mjs';
 import { computeTestMatrixHash } from '../../lib/hash.mjs';
+import {
+  isLegacyChange,
+  skipMissingReason,
+  SKIP_REASON_HINT,
+  contractDeclaresTestMatrix,
+  readTestMatrixFile,
+} from './test-gate-exemptions.mjs';
 
 /**
- * Check that test-matrix.md exists and its hash is consistent with state.
- *
- * Exemption paths (v0.12 §45.3):
- * 1. Legacy: execution-contract.md has no "## Test Matrix" section → PASS
- * 2. Explicit skip: test_matrix_skipped === 'true' → PASS
- * 3. test-matrix.md exists and hash matches → PASS
- * 4. test-matrix.md missing or hash mismatch → FAIL
- *
  * Returns { pass, failures[], reason? }.
  */
 export function checkTestMatrixComplete(changeDir) {
   const state = readState(changeDir);
 
-  // Exemption 1: explicit skip
-  if (state.test_matrix_skipped === 'true') {
-    return { pass: true, failures: [], reason: 'explicitly skipped via test_matrix_skipped' };
+  // Step 1 — legacy：v0.32.0 之前初始化的 change（无 schema_version 打戳）保留旧行为。
+  if (isLegacyChange(state)) {
+    return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
   }
 
-  // Exemption 2: legacy contract without Test Matrix section
-  const contractPath = path.join(changeDir, 'execution-contract.md');
-  if (fs.existsSync(contractPath)) {
-    const contract = fs.readFileSync(contractPath, 'utf-8');
-    if (!contract.includes('## Test Matrix')) {
-      return { pass: true, failures: [], reason: 'legacy contract — no test matrix section' };
+  // Step 2 — 显式 skip：必须附理由（可审计豁免）。
+  if (state.test_matrix_skipped === 'true') {
+    if (skipMissingReason(state)) {
+      return { pass: false, failures: [SKIP_REASON_HINT] };
     }
-  } else {
-    // No contract at all — nothing to check
-    return { pass: true, failures: [], reason: 'no execution contract — skipping test matrix check' };
+    return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
   }
 
-  // Check test-matrix.md exists and is non-empty
-  const matrixPath = path.join(changeDir, 'test-matrix.md');
-  if (!fs.existsSync(matrixPath)) {
+  // Step 3 — 非存量 change 的契约必须声明矩阵（v0.13：内容型豁免删除）。
+  const contract = contractDeclaresTestMatrix(changeDir);
+  if (!contract.exists) {
     return {
       pass: false,
-      failures: ['test-matrix.md is missing — contract declares ## Test Matrix but no matrix file found'],
+      failures: ['execution-contract.md is missing — a non-legacy change must have a contract declaring ## Test Matrix'],
+    };
+  }
+  if (!contract.declares) {
+    return {
+      pass: false,
+      failures: [
+        'non-legacy contract must declare ## Test Matrix — return to bridging so contract-builder generates test-matrix.md, '
+        + 'or explicitly skip (test_matrix_skipped=true + test_matrix_skip_reason)',
+      ],
     };
   }
 
-  const content = fs.readFileSync(matrixPath, 'utf-8');
-  if (content.trim().length === 0) {
+  // Step 4 — test-matrix.md 存在且非空。
+  const matrix = readTestMatrixFile(changeDir);
+  if (!matrix.exists) {
+    return {
+      pass: false,
+      failures: ['test-matrix.md is missing — contract declares ## Test Matrix but no matrix file found'],
+    };
+  }
+  if (matrix.empty) {
     return {
       pass: false,
       failures: ['test-matrix.md is empty — must contain at least a Summary section and Cases table'],
     };
   }
 
-  // Hash consistency check
+  // Step 5 — hash 必须已记录（v0.13：删除 state.test_matrix_hash && 的空值短路）。
+  // 矩阵在 bridging 阶段生成（晚于 state init），contract-builder 生成后必须 tf state rebuild 捕获 hash。
   const computed = computeTestMatrixHash(changeDir);
-  if (state.test_matrix_hash && state.test_matrix_hash !== computed) {
+  if (!state.test_matrix_hash) {
+    return {
+      pass: false,
+      failures: ["test_matrix_hash not recorded — run 'tf state rebuild' after generating test-matrix.md"],
+    };
+  }
+
+  // Step 6 — hash 一致性。
+  if (state.test_matrix_hash !== computed) {
     return {
       pass: false,
       failures: [

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

@@ -15,14 +15,22 @@ 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 = {
   // Forward transitions
-  'exploring:specifying':           ['artifacts-exist', 'arch-design'],
+  // v0.32.2 (P3-10): artifacts-exist removed from exploring:specifying —
+  // the four planning artifacts are PRODUCED by spec-writer during specifying,
+  // so requiring them before the transition was a chicken-and-egg deadlock
+  // (C1 事件：主代理被此门禁逼出绕行行为)。Artifact completeness is enforced
+  // by specifying:bridging (artifacts-exist remains there, single owner).
+  'exploring:specifying':           ['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'],
+  // 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
@@ -171,6 +179,7 @@ async function main() {
     '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

@@ -11,8 +11,12 @@ import { computeArtifactsHash, computeContractHash, computeTestMatrixHash } from
 
 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,8 +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)
-  'test_matrix_skipped',
+  // Test matrix gate (v0.12 §45.4 + v0.13 §48.2)
+  'test_matrix_skipped', 'test_matrix_skip_reason',
 ];
 
 export async function run(args) {
@@ -84,10 +88,17 @@ 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
@@ -95,9 +106,9 @@ export async function run(args) {
       state.last_transition = new Date().toISOString();
       writeState(changeDir, state);
       if (values.json) {
-        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch, test_matrix_hash: tmh }));
+        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}` + (tmh ? `, test_matrix_hash: ${tmh}` : ''));
+        console.log(`State initialized. artifacts_hash: ${hash}` + (tmh ? `, test_matrix_hash: ${tmh}` : '') + (state.schema_version != null ? `, schema_version: ${state.schema_version}` : ''));
       }
       break;
     }
@@ -240,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.');