@xulthekl/team-flow 0.31.0 → 0.32.2

package/scripts/lib/cmd-version.mjs

@@ -19,25 +19,30 @@ const MANIFESTS = [
 // ── Text files with regex patterns (first capture group = version to replace) ──
 // Note: CLAUDE.md is intentionally gitignored (project-local AI instructions).
 const TEXT_FILES = [
-  { file: 'README.md',              pattern: /(当前版本：`v?)0\.\d+\.\d+(`?)/g,                   replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'INSTALL.md',             pattern: /(当前发布版本：\*\*v)0\.\d+\.\d+(\*\*)/g,            replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'docs/README_en.md',      pattern: /(Current: `v)0\.\d+\.\d+(`)/g,                     replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'hooks/session-start',    pattern: /(# v)0\.\d+\.\d+(: conditional injection)/g,       replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'llms.txt',               pattern: /(Current version: v)0\.\d+\.\d+(\.)/g,             replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: '.claude/always/phase-guard.md', pattern: /(# team-flow v)0\.\d+\.\d+( \|)/g,      replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'GEMINI.md',              pattern: /(# team-flow v)0\.\d+\.\d+( \|)/g,              replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/contract-builder/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/build-executor/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/build-executor/implementer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/build-executor/task-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/code-reviewer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/code-reviewer/code-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/bug-investigator/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/release-archivist/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/spec-merger/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'README.md',              pattern: /(当前版本：`v?)\d+\.\d+\.\d+(`?)/g,                   replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'INSTALL.md',             pattern: /(当前发布版本：\*\*v)\d+\.\d+\.\d+(\*\*)/g,            replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'docs/README_en.md',      pattern: /(Current: `v)\d+\.\d+\.\d+(`)/g,                     replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  // v0.32.2（P2-40）：hooks/session-start 两处版本号都纳入同步——
+  // ① 头部注释行（后缀用通配 `:.*`，防止注释措辞变更导致 pattern 腐化失配，
+  //    v0.27.2~v0.32.1 四次发版中断的根因即旧 pattern 写死了后缀措辞）；
+  // ② PLUGIN_VERSION 变量（check-version-consistency 的门禁判据）。
+  { file: 'hooks/session-start',    pattern: /(# v)\d+\.\d+\.\d+(:.*)/g,                            replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'hooks/session-start',    pattern: /(PLUGIN_VERSION=")\d+\.\d+\.\d+(")/g,                 replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'llms.txt',               pattern: /(Current version: v)\d+\.\d+\.\d+(\.)/g,             replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: '.claude/always/phase-guard.md', pattern: /(# team-flow v)\d+\.\d+\.\d+( \|)/g,      replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'GEMINI.md',              pattern: /(# team-flow v)\d+\.\d+\.\d+( \|)/g,              replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/contract-builder/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/implementer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/task-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/code-reviewer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/code-reviewer/code-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/bug-investigator/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/release-archivist/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/spec-merger/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
 ];
 
 function getNestedValue(obj, pathParts) {
@@ -72,7 +77,7 @@ export async function run(args) {
     console.error(`Invalid semver: ${newVersion}`);
     process.exit(2);
   }
-  const [, , minor, patch] = match;
+  const [, major, minor, patch] = match;
 
   console.log(`Version sync → ${newVersion}${dryRun ? ' (dry run)' : ''}\n`);
   let changed = 0;
@@ -122,7 +127,7 @@ export async function run(args) {
 
     const content = readFileSync(filePath, 'utf-8');
     const replacement = entry.replacement
-      .replace('%MINOR%', minor)
+      .replace('%MAJOR%', major).replace('%MINOR%', minor)
       .replace('%PATCH%', patch);
 
     const newContent = content.replace(entry.pattern, replacement);

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/state-loader.mjs

@@ -61,9 +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)
+  // 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"信号。
 };
 
 /**
@@ -108,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'}`);
@@ -166,9 +176,13 @@ export function writeState(changeDir, state) {
   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) ===');
+  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');
 }

package/scripts/lib/test-record.mjs

@@ -0,0 +1,212 @@
+// scripts/lib/test-record.mjs — tf test record：程序化测试证据记录（v0.13 §50）
+//
+// 设计增强方案 v0.13 §50（BUG-A 政策修正）：tests-passing 门禁锚定客观证据，
+// 不再锚定 LLM 自述。本命令解析主流测试 runner 的输出，把结构化结果写入
+// state.test_result（recorded-by=tf-test-record），并把原始输出落盘为证据文件。
+// 不提供手工自述通道（--manual）：确无自动化测试的 change 的合法出路是
+// 显式 skip（test_matrix_skipped=true + test_matrix_skip_reason），可审计、可巡检。
+//
+// 扩展性：新增 runner 只需在 PARSERS 注册表加一个解析器（零依赖）。
+import { parseArgs } from 'node:util';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path, { join } from 'node:path';
+import { readState, writeState } from './state-loader.mjs';
+
+export const SUPPORTED_RUNNERS = ['maven-surefire', 'jest', 'pytest'];
+
+// ── 解析器（全部返回 { total, passed, failed, skipped } 或 null）────────────
+
+/** maven surefire 控制台汇总行（多模块累加）："Tests run: 42, Failures: 0, Errors: 0, Skipped: 2" */
+export function parseMavenSurefire(text) {
+  const re = /Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)/g;
+  let m;
+  let total = 0; let failures = 0; let errors = 0; let skipped = 0;
+  let found = false;
+  while ((m = re.exec(text)) !== null) {
+    found = true;
+    total += parseInt(m[1], 10);
+    failures += parseInt(m[2], 10);
+    errors += parseInt(m[3], 10);
+    skipped += parseInt(m[4], 10);
+  }
+  if (!found) return null;
+  return { total, passed: total - failures - errors - skipped, failed: failures + errors, skipped };
+}
+
+/** maven surefire XML 报告目录（target/surefire-reports）：累加 <testsuite> 属性。 */
+export function parseSurefireReportDir(dir) {
+  let total = 0; let failures = 0; let errors = 0; let skipped = 0;
+  let found = false;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.xml')) continue;
+    const content = readFileSync(join(dir, name), 'utf-8');
+    for (const tag of content.matchAll(/<testsuite\b[^>]*>/g)) {
+      const attrs = tag[0];
+      const pick = (key) => {
+        const am = attrs.match(new RegExp(`\\b${key}="(\\d+)"`));
+        return am ? parseInt(am[1], 10) : 0;
+      };
+      found = true;
+      total += pick('tests');
+      failures += pick('failures');
+      errors += pick('errors');
+      skipped += pick('skipped');
+    }
+  }
+  if (!found) return null;
+  return { total, passed: total - failures - errors - skipped, failed: failures + errors, skipped };
+}
+
+/** jest --json 输出。 */
+export function parseJest(text) {
+  let data;
+  try { data = JSON.parse(text); } catch { return null; }
+  if (typeof data?.numTotalTests !== 'number') return null;
+  const total = data.numTotalTests;
+  const failed = data.numFailedTests ?? 0;
+  const passed = data.numPassedTests ?? 0;
+  const skipped = (data.numPendingTests ?? 0) + (data.numTodoTests ?? 0);
+  return { total, passed, failed, skipped };
+}
+
+/** pytest terminal summary："== 5 passed, 2 failed, 1 skipped in 3.21s ==" */
+export function parsePytest(text) {
+  const lines = text.split('\n');
+  const summaryLine = [...lines].reverse().find(l => /=+\s.*(passed|failed|error|no tests ran)/.test(l));
+  if (!summaryLine) return null;
+  const pick = (label) => {
+    const m = summaryLine.match(new RegExp(`(\\d+)\\s+${label}`));
+    return m ? parseInt(m[1], 10) : 0;
+  };
+  if (/no tests ran/.test(summaryLine)) return { total: 0, passed: 0, failed: 0, skipped: 0 };
+  const passed = pick('passed') + pick('xpassed');
+  const failed = pick('failed') + pick('error');
+  const skipped = pick('skipped') + pick('xfailed');
+  const total = passed + failed + skipped;
+  if (total === 0) return null;
+  return { total, passed, failed, skipped };
+}
+
+const PARSERS = {
+  'maven-surefire': parseMavenSurefire,
+  jest: parseJest,
+  pytest: parsePytest,
+};
+
+/** auto 识别：按内容特征匹配 runner。 */
+export function detectRunner(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{') && parseJest(trimmed)) return 'jest';
+  if (/Tests run:\s*\d+,\s*Failures:/.test(trimmed)) return 'maven-surefire';
+  if (parsePytest(trimmed)) return 'pytest';
+  return null;
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      from: { type: 'string' },
+      runner: { type: 'string', default: 'auto' },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const usageMsg = 'Usage: tf test record <change-dir> --from <runner-output-file|surefire-report-dir> [--runner auto|maven-surefire|jest|pytest] [--json]';
+  if (positionals[0] !== 'record') {
+    console.error(usageMsg);
+    process.exit(2);
+  }
+  const changeDirArg = positionals[1];
+  if (!changeDirArg) {
+    console.error(usageMsg);
+    process.exit(2);
+  }
+  const changeDir = path.resolve(changeDirArg);
+  if (!existsSync(join(changeDir, '.team-flow.yaml'))) {
+    console.error(`No state file at ${join(changeDir, '.team-flow.yaml')}. Run 'tf state init <change-dir>' first.`);
+    process.exit(1);
+  }
+  if (!values.from) {
+    console.error(usageMsg);
+    process.exit(2);
+  }
+  const fromPath = path.resolve(values.from);
+  if (!existsSync(fromPath)) {
+    console.error(`Runner output not found: ${fromPath}`);
+    process.exit(1);
+  }
+  const validRunners = ['auto', ...SUPPORTED_RUNNERS];
+  if (!validRunners.includes(values.runner)) {
+    console.error(`--runner must be one of: ${validRunners.join(', ')}`);
+    process.exit(2);
+  }
+
+  // 解析 runner 输出
+  let stats = null;
+  let runner = values.runner;
+  const fromStat = statSync(fromPath);
+  if (fromStat.isDirectory()) {
+    if (runner !== 'auto' && runner !== 'maven-surefire') {
+      console.error('Directory input is only supported for maven-surefire XML report directories');
+      process.exit(1);
+    }
+    runner = 'maven-surefire';
+    stats = parseSurefireReportDir(fromPath);
+  } else {
+    const text = readFileSync(fromPath, 'utf-8');
+    if (runner === 'auto') {
+      runner = detectRunner(text);
+      if (!runner) {
+        console.error(
+          `Could not auto-detect a supported test runner in ${fromPath}.\n`
+          + `Supported runners: ${SUPPORTED_RUNNERS.join(', ')} (or pass --runner explicitly).\n`
+          + '手工自述通道已关闭（v0.13 §50）：确无自动化测试的 change 请显式跳过：\n'
+          + "  tf state set <dir> test_matrix_skipped true + test_matrix_skip_reason '<理由>'"
+        );
+        process.exit(1);
+      }
+    }
+    stats = PARSERS[runner](text);
+  }
+  if (!stats) {
+    console.error(`Could not parse ${runner} output in ${fromPath} — no recognizable test summary found.`);
+    process.exit(1);
+  }
+
+  // 判定：failed==0 且 total>0 才算 pass（total=0 空真拒绝，v0.13 §50.2）
+  const verdict = stats.failed === 0 && stats.total > 0 ? 'pass' : 'fail';
+  const ts = new Date().toISOString();
+  const record = `${verdict}: total=${stats.total} passed=${stats.passed} failed=${stats.failed} skipped=${stats.skipped} runner=${runner} recorded-by=tf-test-record ts=${ts}`;
+
+  // 原始证据落盘（tests-passing 门禁与 doctor 巡检都要求该文件存在）
+  const evidenceDir = join(changeDir, '.superpowers', 'test-evidence');
+  mkdirSync(evidenceDir, { recursive: true });
+  const safeTs = ts.replace(/[:.]/g, '-');
+  const evidenceRel = join('.superpowers', 'test-evidence', `${safeTs}-${runner}.txt`).split(path.sep).join('/');
+  const raw = fromStat.isFile()
+    ? readFileSync(fromPath, 'utf-8')
+    : `(maven-surefire XML report directory: ${fromPath})`;
+  const MAX_EVIDENCE = 512 * 1024;
+  writeFileSync(join(changeDir, evidenceRel), raw.length > MAX_EVIDENCE ? `${raw.slice(0, MAX_EVIDENCE)}\n...[truncated]` : raw, 'utf-8');
+
+  // 程序化写入状态（test_result 不在 SETTABLE_FIELDS，只能经本命令写入）
+  const state = readState(changeDir);
+  state.test_result = record;
+  state.test_evidence_path = evidenceRel;
+  writeState(changeDir, state);
+
+  if (values.json) {
+    console.log(JSON.stringify({ ok: true, verdict, ...stats, runner, test_result: record, test_evidence_path: evidenceRel }));
+  } else {
+    console.log(`${verdict === 'pass' ? '✅' : '❌'} test_result recorded (${runner}): total=${stats.total} passed=${stats.passed} failed=${stats.failed} skipped=${stats.skipped}`);
+    console.log(`   evidence: ${evidenceRel}`);
+    if (verdict === 'fail') {
+      console.log('   closing 将被 tests-passing 门禁阻断：修复失败后重新运行测试套件并再次 tf test record。');
+    }
+  }
+  process.exit(verdict === 'pass' ? 0 : 1);
+}

package/scripts/team-flow.mjs

@@ -36,6 +36,7 @@ const COMMANDS = {
   'arch-merge':        () => import('./lib/arch-merge.mjs'),
   'test-merge':        () => import('./lib/test-merge.mjs'),
   'test-matrix-export': () => import('./lib/test-matrix-export.mjs'),
+  test:                () => import('./lib/test-record.mjs'),
 };
 
 const HELP = `team-flow (tf) — Unified workflow plugin CLI
@@ -56,6 +57,8 @@ Commands:
                         Merge test matrix results into global docs/test-ledger/
   test-matrix-export <input.json> <output.md> [--change-id <id>]
                         Convert glaf4 test-matrix.json to team-flow test-matrix.md
+  test record <dir> --from <runner-output> [--runner auto|maven-surefire|jest|pytest]
+                        Record programmatic test evidence (v0.13 §50; feeds tests-passing gate)
   config [options]      Display or modify configuration
   config --resolve-model <profile>  Resolve a configured model profile without switching models
   state <sub> <dir>     Manage .team-flow.yaml state (init|check|transition|get|rebuild)

package/skills/contract-builder/SKILL.md

@@ -11,12 +11,7 @@ Read before generating: `proposal.md`, `specs/`, `design.md`, `tasks.md`, then l
 
 **Architecture Design Outputs (v0.9 §26)**: 若 `architecture/` 目录存在，同时读取 `architecture/architecture.md` / `database.md` / `api.md`，作为执行契约的架构约束补充输入——确保 execution-contract.md 的 Implementation Constraints 段包含架构设计的关键约束（聚合边界/CQRS 分流/API 契约/schema 变更）。`architecture/` 不存在时跳过。
 
-**Test Ledger Injection (v0.12 §43.5)**: 若 `docs/test-ledger/` 存在，读取：
-1. `docs/test-ledger/INDEX.md` → 获取相关模块的测试覆盖概览（coverage_status）
-2. `docs/test-ledger/baselines/{module}.md` → 获取已有 case，避免重复设计；读取 Deferred Items → 评估本次是否可解决
-3. 将已有 baseline 和 deferred 项作为 test-matrix.md 生成的增量输入
-
-`docs/test-ledger/` 不存在时跳过（首次使用或无历史数据）。
+**Test Ledger Injection (v0.12 §43.5)**: 若 `docs/test-ledger/` 存在，读取 `INDEX.md`（模块覆盖概览 coverage_status）+ `baselines/{module}.md`（已有 case 避免重复设计；Deferred Items 评估本次是否可解决），作为 test-matrix.md 生成的增量输入。不存在时跳过（首次使用或无历史数据）。
 
 ## Artifact Mapping
 
@@ -41,10 +36,12 @@ Before finalizing:
 
 Must make obvious: approved behavior, out-of-scope, constraints, batches, test obligations, review gates, and conditions that force a rewind to planning. Prefer compression over repeating planning details.
 
-## Test Matrix Generation (v0.12 §42)
+## Test Matrix Generation (v0.12 §42, v0.13 §52 B1 强制化)
 
 `test-matrix.md` 是 `execution-contract.md` 的**附属产物**（不是独立第 6 核心产物），在 contract 的 `## Test Matrix` 段引用。
 
+**full workflow 必须生成（MUST，非建议）**：契约声明 `## Test Matrix` 段 ∧ `test-matrix.md` 存在非空 ∧ `tf state rebuild` 捕获 hash。缺契约段或矩阵文件 → `test-matrix-ready` 阻断进入 executing（入口不查 hash）；三者任一缺失或 hash 不一致 → `test-matrix-complete` 阻断 closing（v0.13 §48/§49；C1-domain-policy 事件教训：矩阵生成曾是建议级，导致零测试通过全部门禁）。确无测试需求的 change 只有一条出路：显式 skip 并留理由（见 Hotfix/Tweak Exemption）。
+
 ### Generation Protocol
 
 1. **输入来源**：specs/（Scenario + Unit/Integration 标签）、tasks.md（batch + file structure）、test-strategy skill（design_method 规则）、test-ledger baselines（增量输入）
@@ -101,14 +98,14 @@ See `test-matrix.md` for the full test case matrix (附属产物, 独立 hash).
 
 ### Hotfix/Tweak Exemption
 
-hotfix/tweak workflow 不生成 test-matrix.md（guard 豁免）。设置：
+hotfix/tweak workflow 不生成 test-matrix.md（guard 豁免）；full workflow 确无自动化测试需求的特例（纯文档/纯配置）同理。设置显式 skip + 理由（v0.13 §48.2 可审计豁免，**不允许静默不生成**）：
 ```bash
-tf state set <change-dir> test_matrix_skipped true
+tf state set <change-dir> test_matrix_skipped true && tf state set <change-dir> test_matrix_skip_reason "<一句话说明>"
 ```
 
 ### GLAF4 Java 路由
 
-当项目技术栈为 GLAF4 Java（Spring Boot / JUnit 5 / Mockito）时，提示用户是否调用 `glaf4-test:glaf4-tests` 做精细矩阵设计。用户同意后由 glaf4-tests design stage 生成 `test-matrix.json`，再转换为 team-flow 格式的 `test-matrix.md`。
+当项目技术栈为 GLAF4 Java（Spring Boot / JUnit 5 / Mockito）时，提示用户是否调用 `glaf4-test:glaf4-tests` 做精细矩阵设计。用户同意后：`glaf4-tests-design` 生成 `test-matrix.json` → `glaf4-tests-validate` 校验 → `tf test-matrix-export <test-matrix.json> <change-dir>/test-matrix.md` 转换为 team-flow 格式。完整 7 步协议见 workflow-start `references/routing-rules.md`「Route to glaf4-tests」。
 
 ## Approval Model (DP-3)
 
@@ -127,6 +124,8 @@ Refresh if: scope changed in proposal, requirements changed in specs, constraint
 
 Generate minimal contract: Intent Lock (one sentence), Task List (numbered), Approval Gate (DP-3). Skip Scope Fence, Build Rules, Review Gates, Test Evidence. Still requires DP-3 approval.
 
+**非存量 hotfix/tweak 必须设置显式 skip（v0.13 §50）**：hotfix/tweak 不生成矩阵，但 closing 的 tests-passing 门禁仍考核非存量 change——生成最小契约后立即执行 Hotfix/Tweak Exemption 段的两条 `tf state set`（`test_matrix_skipped=true` + 理由），否则 release-archivist 轻量收尾会被门禁阻断。
+
 ## Guardrails
 
 - **状态字段禁写（v0.30.0）**：仅写本 skill 的 `dp_3_*` 决策字段；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。

package/skills/release-archivist/SKILL.md

@@ -29,7 +29,15 @@ Claiming work is complete without verification is dishonesty, not efficiency. Be
 ## Verification Steps
 
 ### Step 1: Test Suite
-Run full test suite. Record total/passed/failed/skipped. Zero failures = PASS.
+Run full test suite fresh (e.g. `mvn test` / `npm test`). Record total/passed/failed/skipped. **Zero failures AND total > 0 = PASS.**
+
+**⛔ 空真拒绝（v0.13 §50，C1-domain-policy 事件修复）**：0 个测试时"0 失败"在逻辑上为真，但不是证据——**0 tests ≠ PASS**。发现测试套件为空或项目无测试文件时：要么回 build-executor 补测试（按 test-matrix.md），要么该 change 本应在 bridging 阶段显式 skip（`test_matrix_skipped=true` + 理由）；两种情况都不得写 pass。
+
+**程序化记录（v0.13 §50）**：跑完测试套件后，把 runner 输出落盘并用命令写入证据（`test_result` 已不可手工 `tf state set`）：
+```bash
+tf test record <change-dir> --from <runner-output-file>   # 支持 maven-surefire/jest/pytest，auto 识别
+```
+该命令写入结构化 `test_result`（recorded-by=tf-test-record）+ 证据文件（`.superpowers/test-evidence/`），是 `tests-passing` 门禁对非存量 change 的唯一合法凭证。
 
 ### Step 2: Completeness
 Compare contract batches against actual diff. Every SHALL/MUST must have implementation evidence. Missing = Critical severity.
@@ -45,7 +53,9 @@ If `test-matrix.md` exists:
    - Matrix coverage ≥ 90% with reasonable deferred items → **CONDITIONAL (WARN)**
    - Matrix coverage < 90% OR unexplained gaps → **FAIL**
 
-If `test-matrix.md` does NOT exist → **SKIP** (legacy change compatibility).
+If `test-matrix.md` does NOT exist（v0.13 §52 B2 修订）:
+- legacy change（.team-flow.yaml 无 `schema_version` 字段）或 `test_matrix_skipped=true` → **SKIP**
+- 非存量且未 skip → **FAIL**（矩阵缺失即验证失败；删除静默 SKIP——C1-domain-policy 事件教训）
 
 Add a report row: `| Test Matrix | PASS/FAIL/WARN/SKIP | [reconciliation summary] |`
 
@@ -82,7 +92,7 @@ If an `e2e/` suite exists for the change, fold its report into verification (see
 
 ## Final Checks
 
-**⛔ 状态字段禁写（v0.30.0）**：仅写本 skill 的 `dp_6_*`/`dp_7_*` 决策字段与 `test_result`；**MUST NOT** 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段——closing 转换由主代理经 `tf state transition` 执行（来源：workflow-feedback 2026-08-01）。
+**⛔ 状态字段禁写（v0.30.0 + v0.13 §50）**：仅写本 skill 的 `dp_6_*`/`dp_7_*` 决策字段；测试证据经 `tf test record` 程序化写入（不再手工 set `test_result`）；**MUST NOT** 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段——closing 转换由主代理经 `tf state transition` 执行（来源：workflow-feedback 2026-08-01）。
 
 - Tests passing? (cite command and output)
 - All batches complete? (cite batch status)
@@ -98,12 +108,7 @@ tf state set <change-dir> dp_6_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 If FAIL, do NOT proceed to DP-7. Route back or ask about abandonment.
 
-After recording a PASS outcome, also record it as the verification gate so the
-`executing → closing` transition is allowed (the guard accepts either
-`test_result: pass` or a `dp_6_result` starting with `pass`):
-```bash
-tf state set <change-dir> test_result pass
-```
+**测试门禁凭证（v0.13 §50 修订）**：`dp_6_result` 只是决策点记录，不再是 `tests-passing` 门禁的证据（BUG-A 等价通道仅对存量 change 保留）。非存量 change 的 `executing → closing` 放行凭证是 Step 1 中 `tf test record` 写入的结构化 `test_result`（+ 证据文件）。若 Step 1 尚未执行 `tf test record`，先补跑测试套件并记录，再守 DP-6。
 
 ### DP-7 (Archive Confirmation)
 ```bash
@@ -208,6 +213,8 @@ This check is advisory — skip if the user declines. If the user reports issues
 
 Verify files exist and are non-empty, run `node --check` on code files, skip 5-step verification. Still record DP-6 and DP-7.
 
+**⚠️ tests-passing 门禁不因轻量收尾而豁免（v0.13 §50）**：hotfix/tweak 的 `executing→closing` guard 同样挂 `tests-passing`。非存量 change 仅记 DP-6/DP-7 不足以放行——必须二选一：① `test_matrix_skipped=true` + `test_matrix_skip_reason` 已由 contract-builder 设置（hotfix/tweak 常规路径，先 `tf state get` 核实）；② 有代码变更时补跑测试套件并 `tf test record <change-dir> --from <输出>`。
+
 ## Exception Handling
 
 - **Parse failures**: Report exact file and section

package/skills/session-handoff/SKILL.md

@@ -95,6 +95,7 @@ argument-hint: "[下一个会话的关注点描述]"
 3. **必须脱敏**：所有凭据值替换为 `${PLACEHOLDER}`
 4. **不替代状态恢复**：`.team-flow/` yaml 的跨 session 恢复是自动的，handoff 补充非结构化隐性知识
 5. **handoffs/ 目录加入 .gitignore**：交接文档是临时性质
+6. **重构报告必须现场核对（v0.13 §52 B5）**：凡从会话转录（JSONL）重构的执行报告/交接摘要，其中引用的文件、大小、行数、时间戳、决策点记录，**采信前必须对照磁盘现场与状态文件核对**；无法核对的条目显式标注"未现场核对"。教训：C1-domain-policy 执行报告存在 10+ 处重构失真（虚构文件与数字），未核对的报告不能作为根因证据
 
 ## Output
 

package/skills/workflow-start/SKILL.md

@@ -54,12 +54,14 @@ Validate mode against artifact content. If hotfix/tweak criteria not met → upg
 
 ## Routing Rules
 
+> **⚠️ 路由优先级（硬规则）**：路由按文档顺序从前到后评估，**第一个匹配的路由必须执行**。关键门控：`arch_design_decision` 为 `null` 时 MUST 路由到 `architecture-design`，即使后续路由（spec-writer / contract-builder / build-executor）的其他条件也满足——架构判定是 exploring→specifying 的硬前置，不可跳过。hotfix/tweak 走快速转换，guard 不挂 `arch-design` 维度（`exploring:bridging`/`exploring:approved-for-build` 为空维度），但 **SOP 层仍须过 architecture-design 判断门，不豁免**（v0.9 §26，见 Fast-Path Routing；hotfix 可能正是架构缺陷导致）——判断结果由 architecture-design 子代理写入 `arch_design_decision`，无"自动写 skipped"行为。
+
 ### Sub-agent Dispatch Protocol (v0.30.0)
 
 产出型路由（spec-writer / contract-builder / build-executor / release-archivist）通过 `Agent(subagent_type: "team-flow:<name>")` **dispatch 子代理**执行——agent 定义经 `skills:` 预加载对应 SKILL.md，主代理**不得**凭记忆手写产物格式 prompt。need-explorer 为交互式澄清，**主进程执行**（需与用户对话；其 agent 定义 `team-flow:need-explorer` 仅作可 dispatch 后备）。
 
 - **记录 agentId**：dispatch 后立即记录子代理 ID；修复一律 SendMessage 恢复原子代理（禁启动新子代理，见 v0.29.0 §37）
-- **返回即验证（validation gate）**：子代理返回产物后**立即** `tf validate <change-dir>`；FAIL → SendMessage 回**原**子代理修复，通过后才能继续/转换。把格式失败拦截在返回时，而非状态转换时（避免浪费整次执行后再失败）
+- **返回即验证（validation gate）**：子代理返回产物后**立即** `tf validate <change-dir>`；FAIL → SendMessage 回**原**子代理修复，通过后才能继续/转换。把格式失败拦截在返回时，而非状态转换时（避免浪费整次执行后再失败）。**build-executor 附加验证（v0.13 §52 B3，SDD/full 模式）**：返回的 diff 中必须包含测试文件（src/test/ 或项目测试目录）；零测试文件的实现返回一律 BLOCK，SendMessage 回原子代理按 test-matrix.md / TDD Iron Law 补齐——不得以"手动验证"替代（C1-domain-policy 事件教训）。例外：已显式记录 `test_matrix_skipped=true` + 理由的 change（纯文档/配置类）不要求测试文件
 - **结果协议**：子代理终态须标注 `FINAL VERDICT: <DONE|BLOCKED|FAIL>`（审查类用 PASS/PASS_WITH_WARNINGS/FAIL）；**SendMessage 报告为权威结果**，task-notification.result 仅内部元数据
 - **子代理状态边界**：子代理 MUST NOT 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段（状态转换是主代理专有职责，经 `tf state transition` 执行），只写自己的 `dp_N_*` 决策字段
 
@@ -84,10 +86,10 @@ Full protocol in `references/routing-rules.md`「Route to architecture-design」
 Guard: `tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
 
 ### Route to contract-builder (dispatch sub-agent)
-Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`.
+Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`. **full workflow 必产 test-matrix.md（v0.13 §52 B1）**：契约 `## Test Matrix` 段 + 非空矩阵文件 + `tf state rebuild` 捕获 hash；确无测试需求只能显式 skip + 理由（`test_matrix_skipped=true` + `test_matrix_skip_reason`）。GLAF4 Java 项目矩阵生成的工具选择见 `references/routing-rules.md`「Route to glaf4-tests」。
 
 ### Route to build-executor (dispatch sub-agent)
-Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK.
+Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK. **v0.13 §49 门禁前移**：该 guard 含 `test-matrix-ready` 维度——full 模式非存量 change 必须"带着矩阵开工"（矩阵存在非空 OR 显式 skip 附理由）；FAIL 时回 bridging 让 contract-builder 补矩阵，或按指引显式 skip，禁止绕过。
 
 ### Route to bug-investigator
 Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.

package/skills/workflow-start/references/routing-rules.md

@@ -308,19 +308,23 @@ Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **twe
 ## Post-transition
 💡 `tf inject <change-dir>` to update phase-guard artifacts.
 
-## Route to glaf4-tests (v0.12 §46, v0.31.0)
+## Route to glaf4-tests (v0.12 §46, v0.31.0, v0.13 §52 B3 归位)
 
-**触发条件**：`project_type == glaf4-java`（Spring Boot / JUnit 5 / Mockito）AND contract-builder 需要生成 test-matrix。
+**归位说明（v0.13）**：本段的触发主体是 **bridging 阶段的 contract-builder 子代理**（矩阵生成者），workflow-start 主路由表不包含 glaf4-tests 条目——放在本文件仅作 bridging 期参考。
+
+**强制性澄清（v0.13 §52 B1）**：full workflow 生成 test-matrix.md 本身是**必选动作**（`test-matrix-ready`/`test-matrix-complete` 门禁强制）；**可选的是工具选择**——GLAF4 Java 项目可选用 glaf4-tests 流水线做精细矩阵设计，非 GLAF4 项目用内置 test-strategy skill。两条路都必须产出非空 `test-matrix.md` + contract `## Test Matrix` 段 + `tf state rebuild`。
+
+**触发条件**：`project_type == glaf4-java`（Spring Boot / JUnit 5 / Mockito）。
 
 **协议**：
 1. contract-builder 检测项目技术栈（读取 `pom.xml` / `build.gradle` 判断是否 GLAF4 Java）
 2. GLAF4 项目 → 提示用户：「检测到 GLAF4 Java 项目，是否调用 `glaf4-test:glaf4-tests` 做精细测试矩阵设计？」
 3. 用户同意 → 调用 `glaf4-test:glaf4-tests-design` 生成 `test-matrix.json`
 4. `glaf4-tests-validate` 校验矩阵完整性
-5. `scripts/lib/test-matrix-export.mjs` 转换为 team-flow 格式的 `test-matrix.md`
+5. `tf test-matrix-export <test-matrix.json> <change-dir>/test-matrix.md` 转换为 team-flow 格式
 6. 用户确认（轻量版 DP-A）
-7. 写入 `test-matrix.md`，contract 中添加 `## Test Matrix` 段引用
+7. contract 中添加 `## Test Matrix` 段引用 + `tf state rebuild` 捕获 test_matrix_hash
 
-**非 GLAF4 项目**：contract-builder 使用内置 test-strategy skill 直接生成 `test-matrix.md`。
+**非 GLAF4 项目**：contract-builder 使用预加载的 test-strategy skill 直接生成 `test-matrix.md`（同等强制）。
 
-**设计决策**：glaf4-tests 对接为**可选增强**，不是必经路径。
+**用户拒绝 glaf4-tests 时**：回退内置 test-strategy 生成（不是跳过矩阵）。确无测试需求的特例走显式 skip + 理由。