@xulthekl/team-flow 0.30.0 → 0.31.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.30.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.31.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 23 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.30.0",
+      "version": "0.31.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.30.0",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 15 agents, one install.",
+  "version": "0.31.0",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {
     "name": "LT",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.30.0"
+    "version": "0.31.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 15 agents, one install.",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.30.0"
+    "version": "0.31.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.30.0",
+      "version": "0.31.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -164,7 +164,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
   全局作为下一 change / 下一 PRD 版本的 grounding → 闭环
 ```
 
-## Skills 索引（23 个）
+## Skills 索引（24 个）
 
 | Skill | 归属 | 用途 |
 |---|---|---|
@@ -173,6 +173,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 | spec-writer | team-flow | 写 spec |
 | contract-builder | team-flow | 构建执行契约 |
 | build-executor | team-flow | TDD 实现 |
+| test-strategy | team-flow | 测试设计方法论（design_method 三级分层 + 对抗验证 + 复杂度分级，v0.12 §41） |
 | code-reviewer | team-flow | 代码审查 |
 | spec-merger | team-flow | 合并 delta spec |
 | release-archivist | team-flow | 发布归档 |

package/CHANGELOG.md

@@ -6,6 +6,44 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-08-01
+
+### Added（设计增强方案 v0.12 §40-§46 测试矩阵驱动开发 + 测试复利闭环）
+
+#### test-strategy skill（24→25 skills）
+- **skills/test-strategy/**：新建测试设计方法论 skill（≤50 行硬规则），含 3 个 references：design-methods-detail.md（10+1 种 design_method 详细说明）、complexity-grading.md（复杂度分级规则 + 圈复杂度计算）、adversarial-patterns.md（对抗验证三招 + 攻击向量模板）
+- **agents/build-executor.md**：frontmatter `skills` 新增 `test-strategy` 预加载
+
+#### test-matrix.md 附属产物
+- **skills/contract-builder/SKILL.md**：新增 Test Matrix Generation 段（12 列格式 + 候选覆盖台账 + 对抗验证段 + GLAF4 Java 路由）
+- **skills/spec-writer/SKILL.md**：新增 Unit/Integration 可选标签（test-matrix 提取 hints）
+- **scripts/lib/hash.mjs**：新增 `computeTestMatrixHash()`（独立于 artifacts_hash，避免自循环）
+- **scripts/lib/state-loader.mjs**：BUILTIN_DEFAULTS 新增 `test_matrix_hash` / `test_matrix_skipped`
+- **scripts/lib/cmd-state.mjs**：SETTABLE_FIELDS 新增 `test_matrix_skipped`；init 计算 test_matrix_hash
+
+#### build-executor 按矩阵 TDD
+- **skills/build-executor/implementer-prompt.md**：新增 Test Matrix Protocol 段（TDD/CHARACTERIZATION/REGRESSION 三种 work_mode + 两不原则 + 五步闭环 + 矩阵覆盖率自检）
+
+#### code-reviewer Test Matrix Compliance
+- **skills/code-reviewer/SKILL.md**：新增 Step 5b Test Matrix Compliance（case-by-case 验证 + 覆盖率计算 + 候选台账审计 + 金字塔比例检查）
+- **skills/code-reviewer/code-reviewer-prompt.md**：reviewer prompt 新增 Test Matrix Compliance 检查段
+
+#### release-archivist Test Matrix Reconciliation
+- **skills/release-archivist/SKILL.md**：新增 Step 2b Test Matrix Reconciliation（条件触发 PASS/FAIL/WARN/SKIP）+ Test Merge 段 + closing 顺序更新为 arch-merge → prototype-sync → test-merge → compound promotion
+
+#### guard 维度 test-matrix-complete
+- **scripts/guard/checks/test-matrix-complete.mjs**：新建检查（~55 行），4 条豁免路径（显式 skip / 存量兼容 / 无 contract / hash 一致）
+- **scripts/guard/guard.mjs**：`executing:closing` 新增 `test-matrix-complete`（full 考核 7 维度）；hotfix `executing:closing` 新增（6 维度，豁免 test-matrix-complete）；tweak 保持 3 维度不变
+
+#### 测试复利闭环（test-ledger + test-merge）
+- **scripts/lib/test-merge.mjs**：新建 6 步流程（preCheck → mergeBaselines → resolveDeferred → appendChangelog → rewriteIndex → gitCommit）
+- **scripts/lib/test-matrix-export.mjs**：新建 glaf4 JSON → team-flow Markdown 格式转换（test_kind → test_tier 映射）
+- **scripts/team-flow.mjs**：注册 `test-merge` + `test-matrix-export` 两个新 CLI 命令
+
+#### 注入侧
+- **skills/workflow-orchestrator/references/s1-path-router.md**：新增「测试台账注入」段（读取 docs/test-ledger/INDEX.md，注入 partial 模块列表）
+- **skills/workflow-start/references/routing-rules.md**：新增「Route to glaf4-tests」段（GLAF4 Java 项目可选 glaf4-tests design stage）
+
 ## [0.30.0] - 2026-08-01
 
 ### Added（设计增强方案 v0.11 §39 workflow 健壮性增强，来源：workflow-feedback 2026-08-01 ×9）

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.30.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.31.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.30.0**。
+当前发布版本：**v0.31.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.30.0`
+> 当前版本：`v0.31.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -70,7 +70,7 @@ specs/<cap>/        每变更设计/任务/契约 + learnings.md
 STRATEGY.md CONCEPTS.md 策略 / 领域词汇
 ```
 
-## 九套能力（23 skills）
+## 九套能力（24 skills）
 
 - **team-flow**（9）：workflow-start / need-explorer / spec-writer / contract-builder / build-executor / code-reviewer / spec-merger / release-archivist / bug-investigator
 - **compound 核心子集**（6）：ce-brainstorm / ce-plan / ce-compound / ce-strategy / ce-ideate / ce-proof

package/agents/build-executor.md

@@ -28,6 +28,7 @@ color: green
 tools: ["Read", "Bash", "Grep", "Glob", "Write", "Edit"]
 skills:
   - build-executor
+  - test-strategy
 ---
 
 You are an independent Build Executor. You govern the implementation phase using `execution-contract.md` as the workflow authority, driving disciplined TDD batch execution. You operate in an independent context with Write capability for implementation code and execution receipts.

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.30.0`
+- Current: `v0.31.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 17 skills, one install.",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.30.0: auto-sync CLI version with plugin version
+# v0.31.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.29.2"
+PLUGIN_VERSION="0.31.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.30.0.
+Current version: v0.31.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Unified plugin (23 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.30.0",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 15 agents, one install.",
+  "version": "0.31.0",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"
   },

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

@@ -0,0 +1,67 @@
+// scripts/guard/checks/test-matrix-complete.mjs — verify test matrix exists and is consistent
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { computeTestMatrixHash } from '../../lib/hash.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' };
+  }
+
+  // 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' };
+    }
+  } else {
+    // No contract at all — nothing to check
+    return { pass: true, failures: [], reason: 'no execution contract — skipping test matrix check' };
+  }
+
+  // Check test-matrix.md exists and is non-empty
+  const matrixPath = path.join(changeDir, 'test-matrix.md');
+  if (!fs.existsSync(matrixPath)) {
+    return {
+      pass: false,
+      failures: ['test-matrix.md is missing — contract declares ## Test Matrix but no matrix file found'],
+    };
+  }
+
+  const content = fs.readFileSync(matrixPath, 'utf-8');
+  if (content.trim().length === 0) {
+    return {
+      pass: false,
+      failures: ['test-matrix.md is empty — must contain at least a Summary section and Cases table'],
+    };
+  }
+
+  // Hash consistency check
+  const computed = computeTestMatrixHash(changeDir);
+  if (state.test_matrix_hash && state.test_matrix_hash !== computed) {
+    return {
+      pass: false,
+      failures: [
+        `test-matrix.md has been modified since last hash — stored: ${state.test_matrix_hash}, current: ${computed}. Run 'tf state rebuild' to update.`,
+      ],
+    };
+  }
+
+  return { pass: true, failures: [] };
+}

package/scripts/guard/guard.mjs

@@ -14,6 +14,7 @@ import { checkDp3Approved } from './checks/dp3-approved.mjs';
 import { checkExecutionPlanReady } from './checks/execution-plan-ready.mjs';
 import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.mjs';
 import { checkCompoundCaptured } from './checks/compound-captured.mjs';
+import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
@@ -22,7 +23,7 @@ const TRANSITION_CHECKS = {
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
   'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready'],
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
+  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -55,6 +56,8 @@ const WORKFLOW_TRANSITION_CHECKS = {
     'exploring:bridging': [],
     'bridging:approved-for-build': ['contract-current', 'dp3-approved'],
     'approved-for-build:executing': ['contract-current', 'dp3-approved', 'execution-plan-ready'],
+    // hotfix exemption: no test-matrix-complete (v0.12 §45.3)
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
   },
   tweak: {
     'exploring:approved-for-build': [],
@@ -167,6 +170,7 @@ async function main() {
     'execution-reviews-passed': (dir) => checkExecutionReviewsPassed(dir),
     'arch-design': (dir) => checkArchDesign(dir),
     'compound-captured': (dir) => checkCompoundCaptured(dir),
+    'test-matrix-complete': (dir) => checkTestMatrixComplete(dir),
   };
 
   const checks = [];

package/scripts/lib/cmd-state.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 // VALID_STATES 统一从 state-loader.mjs 引入(状态机合法值唯一真相源),不再本地硬编码。
 // 来源:workflow-feedback 2026-08-01,#100005。
 import { readState, writeState, updateField, rebuildState, VALID_STATES } from './state-loader.mjs';
-import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+import { computeArtifactsHash, computeContractHash, computeTestMatrixHash } from './hash.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -29,6 +29,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',
 ];
 
 export async function run(args) {
@@ -84,15 +86,18 @@ export async function run(args) {
       }
       const hash = computeArtifactsHash(changeDir);
       const ch = computeContractHash(changeDir);
+      const tmh = computeTestMatrixHash(changeDir);
       const state = readState(changeDir);
       state.artifacts_hash = hash;
       state.contract_hash = ch;
+      // v0.12 §42.5: test_matrix_hash is independent from artifacts_hash
+      state.test_matrix_hash = tmh;
       state.last_transition = new Date().toISOString();
       writeState(changeDir, state);
       if (values.json) {
-        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch }));
+        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch, test_matrix_hash: tmh }));
       } else {
-        console.log(`State initialized. artifacts_hash: ${hash}`);
+        console.log(`State initialized. artifacts_hash: ${hash}` + (tmh ? `, test_matrix_hash: ${tmh}` : ''));
       }
       break;
     }
@@ -209,7 +214,7 @@ export async function run(args) {
       break;
     }
     case 'rebuild': {
-      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash });
+      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash, computeTestMatrixHash });
       if (values.json) {
         console.log(JSON.stringify({ ok: true, state: state.state }));
       } else {

package/scripts/lib/hash.mjs

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

package/scripts/lib/state-loader.mjs

@@ -61,6 +61,9 @@ 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_hash: null,
+  test_matrix_skipped: null,
 };
 
 /**
@@ -162,6 +165,10 @@ export function writeState(changeDir, state) {
   lines.push('');
   lines.push('# === Compound engineering capture gate (v0.24.0) ===');
   lines.push(`compound_skipped: ${state.compound_skipped ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Test matrix gate (v0.12 §42.5) ===');
+  lines.push(`test_matrix_hash: ${state.test_matrix_hash ?? 'null'}`);
+  lines.push(`test_matrix_skipped: ${state.test_matrix_skipped ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }
@@ -179,10 +186,14 @@ export function updateField(changeDir, field, value) {
  * Rebuild state file from artifacts — recomputes hashes.
  * Requires hash functions to be passed in (avoids circular dependency).
  */
-export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash }) {
+export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash, computeTestMatrixHash }) {
   const state = readState(changeDir);
   state.artifacts_hash = computeArtifactsHash(changeDir);
   state.contract_hash = computeContractHash(changeDir);
+  // v0.12 §42.5: test_matrix_hash is independent from artifacts_hash
+  if (computeTestMatrixHash) {
+    state.test_matrix_hash = computeTestMatrixHash(changeDir);
+  }
   writeState(changeDir, state);
   return state;
 }