@xulthekl/team-flow 0.30.0 → 0.32.1

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

@@ -34,6 +34,9 @@ const COMMANDS = {
   'install-zcode':     () => import('./lib/cmd-install-zcode.mjs'),
   'prototype-sync':    () => import('./lib/prototype-sync.mjs'),
   '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
@@ -50,6 +53,12 @@ Commands:
                         Merge UX delta into global prototype/ + design-system.md
   arch-merge <change-dir> [--project-root <path>] [--dry-run]
                         Merge architecture delta into global docs/architecture/
+  test-merge <change-dir> [--project-root <path>] [--dry-run]
+                        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/build-executor/implementer-prompt.md

@@ -40,13 +40,42 @@ Subagent (general-purpose):
     ## Your Job
 
     Once you're clear on requirements:
-    1. Implement exactly what the task specifies
-    2. Write tests (following TDD if task says to)
-    3. Verify implementation works
+    1. Read test-matrix.md for this task's module section (if it exists)
+    2. Implement exactly what the task specifies, following the Test Matrix Protocol below
+    3. Verify implementation works (all matrix cases pass)
     4. Commit your work
     5. Self-review (see below)
     6. Report back
 
+    ## Test Matrix Protocol (v0.12 §44.2)
+
+    If `test-matrix.md` exists, read the module section relevant to your task.
+    For each case in the matrix, follow the protocol matching its `work_mode`:
+
+    **work_mode=TDD** (new behavior):
+    1. RED: Write failing test matching `case_id` + `test_method_name`, confirm failure
+    2. GREEN: Implement minimum code to pass
+    3. REFACTOR: Clean up, suite stays green
+    4. Report TDD Evidence: RED command + failure output, GREEN command + pass output
+
+    **work_mode=CHARACTERIZATION** (legacy behavior capture):
+    1. Write test capturing current behavior — do NOT change production code
+    2. Report: `current_behavior_note` + test output
+    3. `production_change_allowed=false` — if test reveals a bug, report it but do NOT fix
+
+    **work_mode=REGRESSION** (defect reproduction + fix):
+    1. Write failing test reproducing the defect
+    2. Fix production code, confirm green
+    3. Report: defect reproduction + fix evidence
+
+    After all cases: self-check matrix coverage = passed cases / total cases in matrix for your module.
+
+    **两不原则 (Two Prohibitions)**:
+    - ⛔ DO NOT write production code and test code simultaneously — RED first, then GREEN
+    - ⛔ DO NOT skip the RED failure confirmation — you must see the test fail before implementing
+
+    If `test-matrix.md` does NOT exist, fall back to standard TDD (Law 2): write tests first, then implement.
+
     Work from: [directory]
 
     **While you work:** If you encounter something unexpected or unclear, **ask questions**.
@@ -109,6 +138,8 @@ Subagent (general-purpose):
     - Did I follow TDD if required?
     - Are tests comprehensive?
     - Is the test output pristine (no stray warnings or noise)?
+    - If test-matrix.md exists: matrix coverage = passed cases / total cases for my module
+    - Each case's `design_method` matches the actual test approach (boundary case uses real boundary values, not happy-path disguised as boundary)
 
     If you find issues during self-review, fix them now before reporting.
 
@@ -126,6 +157,10 @@ Subagent (general-purpose):
     - **TDD Evidence** (if TDD was required for this task):
       - RED: command run, relevant failing output before implementation, and why the failure was expected
       - GREEN: command run and relevant passing output after implementation
+    - **Test Matrix Coverage** (if test-matrix.md exists):
+      - Cases implemented: N/M (list case_ids)
+      - Cases deferred: N (list case_ids + reason)
+      - Any case where expected_red did not match actual failure — report mismatch
     - Files changed
     - Self-review findings (if any)
     - Any issues or concerns

package/skills/code-reviewer/SKILL.md

@@ -134,6 +134,31 @@ Check for:
 - **Edge cases**: Tests cover boundary conditions, error cases
 - **Test quality**: Tests are meaningful (not just "it works"), assertions are specific
 
+### Step 5b: Test Matrix Compliance (v0.12 §44.3)
+
+If `test-matrix.md` exists in the change directory, audit the implementation against it:
+
+1. **Case-by-case verification**: For each case in the matrix:
+   - Check if the test implementation exists (`test_file` + `test_method_name` match)
+   - Verify assertions match the matrix's `expected` output
+   - Verify `design_method` matches actual test approach (a `boundary` case must use real boundary values, not a happy-path disguised as boundary)
+
+2. **Coverage calculation**:
+   - Matrix coverage = implemented cases / total cases in matrix
+   - Matrix coverage < 100% → **Critical finding** (test-matrix-gap)
+   - List missing case_ids
+
+3. **Candidate Coverage Ledger audit**:
+   - Entries with `decision=deferred` have a reasonable `reason`?
+   - Entries with `decision=covered` actually have corresponding tests?
+
+4. **Pyramid ratio check**:
+   - unit cases: 70-80% of total
+   - integration cases: ≤30% of total
+   - Significant deviation → **Important finding** (test-pyramid-imbalance)
+
+If `test-matrix.md` does NOT exist, skip this step silently (legacy change compatibility).
+
 ### Step 6: Documentation Review
 
 Check for:
@@ -156,7 +181,9 @@ Check for:
 |---------|-----------|
 | **PASS** | No Critical or Important findings |
 | **PASS_WITH_WARNINGS** | No Critical, but Important findings exist |
-| **FAIL** | Any Critical finding |
+| **FAIL** | Any Critical finding (including Test Matrix Compliance gaps — v0.12 §44.3) |
+
+Test Matrix Compliance Critical findings carry the same weight as Spec Compliance violations — matrix gaps are always Critical, never Important.
 
 ## Calibration Rules
 

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -68,6 +68,16 @@ Subagent (general-purpose):
     - Integration tests where they matter?
     - All tests passing?
 
+    **Test Matrix Compliance (v0.12 §44.3):**
+    If `test-matrix.md` exists, audit against it:
+    - Each case has a corresponding test implementation (test_file + test_method_name match)?
+    - Assertions match the matrix's `expected` output?
+    - `design_method` matches actual test approach (boundary case uses real boundary values)?
+    - Matrix coverage < 100% → Critical finding (test-matrix-gap)
+    - Candidate Coverage Ledger: deferred items have reasonable reasons?
+    - Pyramid ratio: unit 70-80%, integration ≤30%?
+    If `test-matrix.md` does NOT exist, skip this section silently.
+
     **Production readiness:**
     - Migration strategy if schema changed?
     - Backward compatibility considered?

package/skills/contract-builder/SKILL.md

@@ -11,6 +11,8 @@ 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/` 存在，读取 `INDEX.md`（模块覆盖概览 coverage_status）+ `baselines/{module}.md`（已有 case 避免重复设计；Deferred Items 评估本次是否可解决），作为 test-matrix.md 生成的增量输入。不存在时跳过（首次使用或无历史数据）。
+
 ## Artifact Mapping
 
 | Source | Extract |
@@ -34,6 +36,77 @@ 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, 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（增量输入）
+2. **按模块分组**：为每个有业务逻辑的模块（Service/Controller/Repository 等）生成 case 列表
+3. **复杂度分级**：每个模块标注 trivial/medium/complex，作为用例数下限判据（test-strategy §2）
+4. **design_method 覆盖**：每个模块至少 1 个 `{boundary, equivalence}` case + 1 个 `{error, exception, reject}` case（test-strategy §6 schema 强制覆盖）
+5. **对抗验证**：矩阵生成后执行三招回检（test-strategy §4），缺失则追加 adversarial case
+6. **候选覆盖台账**：列出所有被测候选（方法/类），标注 decision（covered/deferred/not_applicable）
+
+### 12-Column Format
+
+| case_id | behavior | design_method | input | expected | test_kind | test_tier | mock | work_mode | test_file | test_method_name | run_command |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+
+字段说明见 test-strategy skill 的 `references/design-methods-detail.md`。`test_tier` 从 `test_kind` 派生（unit/integration）。
+
+### Structure
+
+```markdown
+# Test Matrix — {change-name}
+
+## Summary
+- Total cases: {N}
+- Modules covered: {N} (complexity: trivial×{n}, medium×{n}, complex×{n})
+- Unit cases: {N} ({percent}%)
+- Integration cases: {N} ({percent}%)
+- Deferred items: {N}
+- Matrix revision: 1
+
+## Candidate Coverage Ledger
+| candidate | category | decision | case_ids | reason |
+
+## Cases
+### {module-name}
+| case_id | behavior | design_method | input | expected | test_kind | test_tier | mock | work_mode | test_file | test_method_name | run_command |
+
+## Adversarial Cases
+| case_id | behavior | design_method | input | expected | test_kind | test_tier | mock | work_mode | test_file | test_method_name | run_command |
+
+## Deferred Items
+| case_id | behavior | design_method | reason | deferred_since |
+```
+
+### Post-Generation
+
+写入 `test-matrix.md` 后，在 `execution-contract.md` 中添加引用段：
+```markdown
+## Test Matrix
+See `test-matrix.md` for the full test case matrix (附属产物, 独立 hash).
+- Total cases: {N}, Unit: {N}, Integration: {N}, Deferred: {N}
+```
+
+然后执行 `tf state rebuild <change-dir>` 更新 `test_matrix_hash`。
+
+### Hotfix/Tweak Exemption
+
+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_skip_reason "<一句话说明>"
+```
+
+### GLAF4 Java 路由
+
+当项目技术栈为 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)
 
 After drafting: summarize handoff rules, identify ambiguity, flag unmapped requirements, ask user to approve explicitly. After approval:
@@ -51,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,11 +29,36 @@ 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.
 
+### Step 2b: Test Matrix Reconciliation (conditional, v0.12 §44.4)
+
+If `test-matrix.md` exists:
+1. **Statistics**: total cases / implemented / passed
+2. **Candidate Coverage Ledger audit**: any `decision=deferred` without reasonable reason?
+3. **Complexity tier check**: cases per module meet minimum (trivial≥3 / medium≥5 / complex≥7)?
+4. **Verdict**:
+   - Matrix coverage = 100% AND all cases pass → **PASS**
+   - Matrix coverage ≥ 90% with reasonable deferred items → **CONDITIONAL (WARN)**
+   - Matrix coverage < 90% OR unexplained gaps → **FAIL**
+
+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] |`
+
 ### Step 3: Coherence
 Compare design decisions against code. Check naming consistency. Inconsistencies = IMPORTANT.
 
@@ -67,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)
@@ -83,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
@@ -115,7 +135,7 @@ tf arch-merge <change-dir>
 
 This merges `architecture/{architecture,database,api}.md` and `architecture/sql/` into the global architecture docs. Skip silently when `architecture/` does not exist (architecture-design was `skipped`).
 
-**Execution order (mandatory)**: `arch-merge` → `prototype-sync` → `compound promotion`. Do not parallelise — global docs must not be in a half-updated state.
+**Execution order (mandatory, v0.12 §43.4)**: `arch-merge` → `prototype-sync` → `test-merge` → `compound promotion`. Do not parallelise — global docs must not be in a half-updated state.
 
 ### Prototype Sync (v0.5)
 
@@ -125,12 +145,30 @@ After `arch-merge` completes, run prototype-sync to merge UX deltas back to the
 tf prototype-sync <change-dir>
 ```
 
-**Write-back order (mandatory)**: `arch-merge` → `prototype-sync` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/` and `prototype/` must not be in a half-updated state when the next change grounds on them.
+**Write-back order (mandatory, v0.12 §43.4)**: `arch-merge` → `prototype-sync` → `test-merge` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/`, `prototype/`, and `docs/test-ledger/` must not be in a half-updated state when the next change grounds on them.
 
 If `prototype-sync` reports conflicts, list them in the closing summary and flag for manual resolution. Do not block closing on prototype-sync conflicts (advisory level).
 
 **Execution verification（v0.24.0）**：`prototype-sync` 命令执行后，检查其 stdout 输出确认合并完成（输出含 `merged`/`no UX delta`/`conflicts` 之一）。若命令未执行或执行失败，Step 5 Report 的 `Prototype sync` 行必须标注 `SKIPPED` 或 `FAILED`，并在 closing summary 中说明原因。**禁止在 prototype-sync 未执行时将 Prototype sync 行标注为已完成**。
 
+### Test Merge (v0.12 §43)
+
+After `prototype-sync` completes, run test-merge to write test matrix results back to the global test ledger:
+
+```bash
+tf test-merge <change-dir>
+```
+
+This merges `test-matrix.md` into `docs/test-ledger/`:
+- **mergeBaselines**: extract cases by module, incrementally update `baselines/{module}.md`
+- **resolveDeferred**: new cases covering old deferred items → remove from Deferred
+- **appendChangelog**: archive test-matrix.md → `changelog/{change-id}.md`
+- **rewriteIndex**: recalculate module/case/deferred counts, rewrite `INDEX.md`
+
+Skip silently when `test-matrix.md` does not exist (legacy change or test_matrix_skipped=true).
+
+**Execution verification**: check stdout output for `test-merge complete` confirmation. If the command did not execute or failed, Step 5 Report's `Test Matrix` row (from Step 2b) must note the reason.
+
 ### Compound Promotion (v0.5)
 
 During closing, promote change-level learnings to the global solutions library:
@@ -175,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/spec-writer/SKILL.md

@@ -88,6 +88,8 @@ Every requirement must be testable. Use SHALL or MUST. Every requirement must ha
 
 Optional structured AC tags under a Scenario are supported for E2E extraction (v0.4, design spec ch.16): `##### Exception:` (→ EX AC, ×2), `##### State:` (→ ST AC, ×2), `##### Boundary:` (→ BND AC, ×1). These are **OPTIONAL** — omitting them does NOT fail validation. The `e2e` skill applies dimension-conditional gating (absent dimension = N/A, not 0%) plus keyword fallback (error/invalid/fail/边界), so no spec is forced to add tags.
 
+Optional test-dimension tags under a Scenario are supported for test-matrix extraction (v0.12 §44.1): `##### Unit:` (→ unit test hints: equivalence classes, boundary values), `##### Integration:` (→ integration test hints: cross-module, transaction boundaries). These are **OPTIONAL** — omitting them does NOT fail validation. The `contract-builder` extracts matrix skeletons from these tags when present, but does not require them.
+
 ### design.md
 Must have: Context (current state, constraints, stakeholders), Goals, Decisions (Choice + Rationale + Alternatives considered), Risks And Trade-Offs.
 
@@ -127,7 +129,7 @@ Generate one at a time. Confirm each before next. This prevents scope drift —
 - `## Why` > 50 chars, `## What Changes`, `## Scope` (In/Out), `## Impact`, `## Capabilities`, no TBD/TODO
 
 ### specs/
-- SHALL/MUST for required behavior, `#### Scenario:` with WHEN/THEN per requirement, grouped under delta headers, no contradictions; optional `##### Exception:/State:/Boundary:` sub-tags allowed but NOT required (absent dimension = N/A, not 0%). Regression: a spec containing `##### Exception:` must still pass `npm run validate` (validateDeltaSpec must not reject unknown sub-headings).
+- SHALL/MUST for required behavior, `#### Scenario:` with WHEN/THEN per requirement, grouped under delta headers, no contradictions; optional `##### Exception:/State:/Boundary:` sub-tags allowed but NOT required (absent dimension = N/A, not 0%); optional `##### Unit:/Integration:` sub-tags allowed but NOT required (test-matrix hints for contract-builder). Regression: a spec containing `##### Exception:` must still pass `npm run validate` (validateDeltaSpec must not reject unknown sub-headings).
 
 ### design.md
 - `## Context`, `## Goals`, `## Decisions` (≥1, with Choice+Rationale+Alternatives), `## Risks And Trade-Offs`