@xulthekl/team-flow 0.29.2 → 0.31.0

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,13 @@ 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/` 不存在时跳过（首次使用或无历史数据）。
+
 ## Artifact Mapping
 
 | Source | Extract |
@@ -34,6 +41,75 @@ 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.md` 是 `execution-contract.md` 的**附属产物**（不是独立第 6 核心产物），在 contract 的 `## Test Matrix` 段引用。
+
+### 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 豁免）。设置：
+```bash
+tf state set <change-dir> test_matrix_skipped true
+```
+
+### 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`。
+
 ## Approval Model (DP-3)
 
 After drafting: summarize handoff rules, identify ambiguity, flag unmapped requirements, ask user to approve explicitly. After approval:
@@ -53,6 +129,8 @@ Generate minimal contract: Intent Lock (one sentence), Task List (numbered), App
 
 ## Guardrails
 
+- **状态字段禁写（v0.30.0）**：仅写本 skill 的 `dp_3_*` 决策字段；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
+
 - Do not continue to implementation if ambiguity remains
 - Do not approve the contract on the user's behalf
 - Do not skip the contract because planning docs look complete

package/skills/need-explorer/SKILL.md

@@ -52,6 +52,8 @@ Once DP-1 is recorded, hand off to `spec-writer`.
 
 ## Anti-Patterns
 
+- **修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段**（v0.30.0 禁止）：状态转换是主代理经 `tf state transition` 的专有职责；need-explorer 只写自己的 `dp_1_*` 决策字段（来源：workflow-feedback 2026-08-01）。
+
 - **Skipping exploration**: "Simple" changes have scope too. Five minutes of exploration prevents two hours of rework.
 - **Proposing solutions before clarifying**: If the user says "add caching," first ask what problem caching solves.
 - **Exploring indefinitely**: Stop when change name, problem statement, scope, non-goals, success criteria, and decomposition decision are all clear.

package/skills/release-archivist/SKILL.md

@@ -34,6 +34,21 @@ Run full test suite. Record total/passed/failed/skipped. Zero failures = PASS.
 ### 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 → **SKIP** (legacy change compatibility).
+
+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,6 +82,8 @@ 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）。
+
 - Tests passing? (cite command and output)
 - All batches complete? (cite batch status)
 - Scope added without artifact updates?
@@ -113,7 +130,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)
 
@@ -123,12 +140,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:

package/skills/spec-writer/SKILL.md

@@ -72,6 +72,8 @@ Run: `tf runtime config --get artifacts.order` — generate in configured order
 
 ## Working Rules
 
+**⛔ 状态字段禁写（v0.30.0）**：仅通过 `tf state set` 写本 skill 的 `dp_2_*` 决策字段；**MUST NOT** 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段——状态转换是主代理（workflow-start）经 `tf state transition` 的专有职责（来源：workflow-feedback 2026-08-01）。
+
 **Honor DP-0**: Read `dp_0_decisions`, respect confirmed constraints, don't silently expand scope. Pause on unconfirmed decisions.
 
 **Honor Brief (v0.9)**: 若 `change-brief.md` 存在，尊重其 scope 边界与 AC 列表（见 Required Inputs「Change Brief」）——不静默丢弃 brief AC、不静默超出 brief scope；与 plan.md 冲突时以 plan.md 为准并注明。
@@ -86,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.
 
@@ -125,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`

package/skills/test-strategy/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: test-strategy
+description: 测试设计方法论 skill——design_method 选择、分层策略、对抗验证、复杂度分级。build-executor 通过 skills: 预加载。
+user-invocable: false
+---
+
+# Test Strategy
+
+测试设计方法论的硬规则。build-executor 通过 `skills: [test-strategy]` 预加载。
+详细说明见 `references/design-methods-detail.md`、`references/complexity-grading.md`、`references/adversarial-patterns.md`。
+
+## 1. Design Method 选择规则（三级分层）
+
+### 基础级（必选——每个被测目标必须覆盖）
+- **equivalence**: 输入域有有效/无效分类
+- **boundary**: 数字/长度/日期/金额/分页存在边界（6 值法：min-1/min/min+1/max-1/max/max+1）
+- **error**: 业务异常、空值、外部依赖失败
+
+### 扩展级（条件触发）
+- **path**: 方法存在多分支（圈复杂度 M = 判定节点+1，用例数 ≥ M）
+- **state**: 对象状态改变或业务规则依赖状态迁移
+- **exception**: 显式覆盖异常类型/消息/框架异常映射
+- **reject**: 业务拒绝、准入失败、权限拒绝
+
+### 高级（场景触发）
+- **permission**: API 权限、租户、用户上下文
+- **idempotency**: 重复调用、重复消息、补偿逻辑
+- **concurrency**: 锁、事务、异步消息、并发更新
+- **contract**: 跨模块/跨服务接口契约（Feign、MQ 消息格式、领域事件字段）
+
+## 2. 复杂度分级用例数
+
+| 复杂度 | 判据 | 最少用例 |
+|--------|------|---------|
+| trivial | is_trivial=true（enum/constant/POJO） | ≥3（仅 equivalence + error，boundary 可省） |
+| medium | 默认（无判据命中） | ≥5 |
+| complex | public_methods>15 或 lines>800 或 圈复杂度>10 或 param_count>6 | ≥7 |
+
+保守默认：事实是估算非实测 → 强制 medium 档(≥5)。
+
+## 3. 分层策略（测试金字塔比例）
+
+- unit（test_tier=unit）：70-80% 的 case
+- integration（test_tier=integration）：≤30% 的 case
+- e2e：由 e2e skill 独立覆盖，不计入本矩阵
+
+## 4. 对抗验证三招（矩阵生成后必检）
+
+1. **恶意输入**：至少 1 个 case 覆盖 null/空串/超大值/特殊字符
+2. **并发场景**：涉及锁/事务/异步 → 至少 1 个 concurrency case
+3. **依赖失败**：涉及外部依赖 → 至少 1 个 dependency_failure case（超时/熔断/返回空）
+
+## 5. 自检门口诀
+
+每个方法至少：**1 正常 + 1 边界 + 1 异常 + 1 null/空**
+
+## 6. Schema 强制覆盖（test-matrix.md 校验）
+
+1. cases 必须包含至少 1 个 `design_method ∈ {boundary, equivalence}` 的 case
+2. cases 必须包含至少 1 个 `design_method ∈ {error, exception, reject}` 的 case
+3. `complexity_tier=trivial` 时降级：允许只覆盖 equivalence + error
+4. 对抗验证段必须存在（恶意输入/并发/依赖失败三类之一，视目标而定）
+
+## 7. work_mode 三种模式
+
+| work_mode | 适用场景 | TDD 节奏 |
+|---|---|---|
+| **TDD** | 新功能/新行为 | RED→GREEN→REFACTOR |
+| **CHARACTERIZATION** | 遗留代码行为捕获 | 只写不改（不改生产代码） |
+| **REGRESSION** | 缺陷复现+修复 | 先复现再修 |

package/skills/test-strategy/references/complexity-grading.md

@@ -0,0 +1,137 @@
+# Complexity Grading
+
+复杂度分级的详细规则。SKILL.md §2 的扩展参考。
+
+---
+
+## 1. 分级标准
+
+### trivial（简单）
+
+**判据**（命中任一）：
+- 纯常量/枚举类（无方法体）
+- POJO/DTO（仅 getter/setter，无业务逻辑）
+- 工具方法的简单委托（`return delegate.doSomething(x)`）
+- 配置文件读取（无校验逻辑）
+
+**最少用例数**：≥3
+- equivalence: 1 个正常输入
+- error: 1 个 null/空值
+- boundary: **可省**（trivial 降级特权）
+
+**示例**：
+```java
+// ErrorCode.java — 纯枚举
+// OrderDTO.java — 仅 getter/setter
+// StringUtils.isBlank() — 简单委托
+```
+
+### medium（中等）— 默认
+
+**判据**：无 trivial 或 complex 判据命中时，强制 medium。
+
+**最少用例数**：≥5
+- equivalence: ≥1 正常 + ≥1 无效
+- boundary: ≥2（至少 1 个下边界 + 1 个上边界）
+- error: ≥1
+
+### complex（复杂）
+
+**判据**（命中任一）：
+- public_methods > 15
+- lines > 800（含注释和空行）
+- 圈复杂度 > 10
+- param_count > 6（单个方法参数超过 6 个）
+- 涉及 ≥3 个外部依赖交互
+- 包含状态机（≥4 个状态）
+
+**最少用例数**：≥7
+- equivalence: ≥2 正常 + ≥2 无效
+- boundary: ≥3（至少含 1 个 6 值法完整覆盖）
+- error: ≥1
+- path: ≥1（如果有分支）
+
+---
+
+## 2. 圈复杂度计算方法
+
+### 手动计算
+
+从 1 开始（方法本身的 1 条直线执行路径），每遇到以下结构 +1：
+
+| 结构 | 增量 |
+|---|---|
+| `if` / `else if` | +1 |
+| `switch` 每个 `case`（含 `default`） | +1 per case |
+| `for` / `while` / `do-while` | +1 |
+| `&&` / `||` 短路运算 | +1 per operator |
+| `catch` | +1 |
+| `?:`（三元表达式） | +1 |
+
+**示例**：
+```java
+public void process(Order order) {            // 1
+  if (order == null) { ... }                  // +1 = 2
+  if (order.getStatus() == PAID               // +1 = 3
+      && order.getAmount() > 1000) { ... }    // +1 = 4
+  for (Item item : order.getItems()) {        // +1 = 5
+    if (item.isDiscounted()) { ... }          // +1 = 6
+    switch (item.getType()) {
+      case PHYSICAL: ... break;              // +1 = 7
+      case DIGITAL: ... break;               // +1 = 8
+      default: ...                           // +1 = 9
+    }
+  }
+}
+// 圈复杂度 = 9 → medium 档（未超 10）
+```
+
+### 工具辅助
+
+| 语言 | 工具 | 命令 |
+|---|---|---|
+| Java | Checkstyle / PMD | `mvn checkstyle:check` / `pmd check` |
+| Java | SonarQube | 自动扫描 |
+| TypeScript | complexity-report | `npx complexity-report src/` |
+| Python | radon | `radon cc src/` |
+
+---
+
+## 3. 校准规则
+
+### 保守默认
+
+- 事实是估算非实测 → 不确定时强制 medium 档(≥5)
+- 宁可多做不可漏做 → 边界 case 优先于 happy path
+
+### 方法拆分时的处理
+
+如果一个方法被拆分为多个小方法：
+- 拆分前：complex（圈复杂度 12）
+- 拆分后：每个子方法 medium（圈复杂度 4-6）
+- **但**：拆分前的 complex 级用例数仍需保留（不因拆分而降级）
+
+### 组合方法的计算
+
+如果类有多个 public 方法：
+- 每个方法独立计算复杂度
+- 类的总复杂度 = 各方法圈复杂度之和
+- 类的用例数 = 各方法用例数之和（去重共享的 setup/teardown case）
+
+---
+
+## 4. 与 test-matrix.md 的关联
+
+在 test-matrix.md 的 `## Summary` 段中标注每个模块的复杂度分级：
+
+```markdown
+## Summary
+- Total cases: 35
+- Modules covered: 4
+  - OrderService: complex (圈复杂度 14, ≥7 cases)
+  - PaymentValidator: medium (圈复杂度 6, ≥5 cases)
+  - ErrorCode: trivial (纯枚举, ≥3 cases)
+  - OrderConverter: trivial (POJO 映射, ≥3 cases)
+```
+
+contract-builder 在生成矩阵时，必须为每个模块标注复杂度分级，作为用例数下限的判据。

package/skills/test-strategy/references/design-methods-detail.md

@@ -0,0 +1,183 @@
+# Design Methods Detail
+
+10+1 种测试设计方法的详细说明。SKILL.md §1 的扩展参考。
+
+---
+
+## 基础级（必选）
+
+### equivalence（等价类划分）
+
+**触发条件**：输入域有有效/无效分类。
+
+**方法**：
+1. 识别输入参数的有效等价类和无效等价类
+2. 每个等价类取 1 个代表值
+3. 有效类 → 验证正常行为；无效类 → 验证拒绝/异常
+
+**示例（Java）**：
+```java
+// 有效等价类：validOrderId (正整数)
+// 无效等价类：null, 0, -1, 超过 MAX_LONG
+@Test void shouldFindOrder_whenValidId() { ... }
+@Test void shouldThrow_whenNullId() { ... }
+@Test void shouldThrow_whenNegativeId() { ... }
+```
+
+### boundary（边界值分析）
+
+**触发条件**：数字/长度/日期/金额/分页存在边界。
+
+**6 值法**：对每个边界取 min-1 / min / min+1 / max-1 / max / max+1
+
+| 边界类型 | 示例（金额 0.01 ~ 999999.99） |
+|---|---|
+| min-1 | 0.00 → 拒绝 |
+| min | 0.01 → 接受（最小合法） |
+| min+1 | 0.02 → 接受 |
+| max-1 | 999999.98 → 接受 |
+| max | 999999.99 → 接受（最大合法） |
+| max+1 | 1000000.00 → 拒绝 |
+
+**日期边界特殊处理**：
+- 闰年：2024-02-29 / 2025-02-28
+- 月末/月初：1月31日 → 2月1日
+- 时区切换：UTC+8 的 23:59 vs UTC 的 15:59
+
+### error（错误/异常路径）
+
+**触发条件**：业务异常、空值、外部依赖失败。
+
+**必须覆盖的三类**：
+1. **参数校验错误**：null、空串、格式错误
+2. **业务规则违反**：库存不足、余额不够、重复操作
+3. **外部依赖失败**：DB 连接超时、HTTP 5xx、MQ 消费失败
+
+**示例**：
+```java
+@Test void shouldThrowBizException_whenInsufficientStock() { ... }
+@Test void shouldReturnEmpty_whenDbReturnsNull() { ... }
+@Test void shouldRetry_whenExternalApiTimeout() { ... }
+```
+
+---
+
+## 扩展级（条件触发）
+
+### path（路径覆盖）
+
+**触发条件**：方法存在多分支。
+
+**圈复杂度计算**：M = 判定节点数 + 1
+- `if` → +1
+- `else if` → +1
+- `switch` 每个 `case` → +1
+- `for` / `while` → +1
+- `&&` / `||` 短路运算 → +1
+
+**用例数 ≥ M**。示例：M=4（1 个 if + 1 个 switch 3-case）→ ≥4 个 case。
+
+### state（状态迁移）
+
+**触发条件**：对象状态改变或业务规则依赖状态迁移。
+
+**方法**：
+1. 画出状态迁移图（初始态 → 中间态 → 终态）
+2. 每条迁移边至少 1 个 case
+3. 非法迁移（如 CLOSED → PROCESSING）→ 1 个 reject case
+
+**示例（订单状态机）**：
+```
+CREATED → PAID → SHIPPED → DELIVERED → CLOSED
+  ↓                      ↑
+CANCELLED ←──────────────┘ (仅 PAID 前可取消)
+```
+
+### exception（异常覆盖）
+
+**触发条件**：显式覆盖异常类型/消息/框架异常映射。
+
+**必须验证**：
+1. 异常类型是否正确（BusinessException vs SystemException）
+2. 异常消息是否包含上下文（errorCode + 参数值）
+3. 框架异常映射（Spring 的 `@ResponseStatus` → HTTP 状态码）
+
+### reject（业务拒绝）
+
+**触发条件**：业务拒绝、准入失败、权限拒绝。
+
+**与 error 的区别**：error 是"系统出了问题"，reject 是"系统正确地拒绝了"。
+
+**示例**：
+```java
+@Test void shouldReject_whenOrderAlreadyClosed() { ... }
+@Test void shouldReject_whenUserNotInWhitelist() { ... }
+@Test void shouldReject_whenDuplicateRequest() { ... }
+```
+
+---
+
+## 高级（场景触发）
+
+### permission（权限控制）
+
+**触发条件**：API 权限、租户、用户上下文。
+
+**覆盖维度**：
+1. 角色权限：ADMIN / USER / GUEST / ANONYMOUS
+2. 租户隔离：租户 A 不能访问租户 B 的数据
+3. 数据权限：只能操作自己创建的资源
+
+### idempotency（幂等性）
+
+**触发条件**：重复调用、重复消息、补偿逻辑。
+
+**验证模式**：
+1. 调用 N 次 → 效果等同于调用 1 次
+2. MQ 重复消费 → 不重复处理
+3. 补偿操作 → 正向 + 逆向 = 无净效果
+
+**示例**：
+```java
+@Test void shouldNotDuplicateOrder_whenRetryCreate() {
+  var first = orderService.create(request);
+  var second = orderService.create(request);
+  assertThat(second.getId()).isEqualTo(first.getId());
+}
+```
+
+### concurrency（并发安全）
+
+**触发条件**：锁、事务、异步消息、并发更新。
+
+**验证模式**：
+1. 乐观锁冲突 → 重试或拒绝
+2. 分布式锁 → 同一时刻只有一个执行者
+3. 事务隔离 → 读未提交 / 读已提交 / 可重复读
+4. 异步消息 → 最终一致性
+
+### contract（接口契约）
+
+**触发条件**：跨模块/跨服务接口契约。
+
+**覆盖维度**：
+1. Feign 客户端：请求/响应格式与 provider 一致
+2. MQ 消息：字段名/类型/必填项
+3. 领域事件：事件名/载荷/版本
+
+---
+
+## 派生字段：test_tier
+
+从 `test_kind` 派生 `test_tier`（语言无关的粗粒度分类）：
+
+| test_kind 值 | test_tier |
+|---|---|
+| pure_unit, mockito_unit, spring_assisted_unit | unit |
+| vitest_unit, vue_test_utils_mount | unit |
+| api_mockmvc_standalone, api_mockmvc_slice, api_mockmvc_boot | integration |
+| service_social, repository_h2 | integration |
+| rabbitmq_social, redis_social | integration |
+| external_api_stub, test_infrastructure | integration |
+
+**用途**：test_tier 用于统计和 CI 分级；test_kind 用于路由到正确的编写模板。

package/skills/workflow-orchestrator/references/s1-path-router.md

@@ -48,6 +48,10 @@ S1 只做编排动作（需求选择、存在性检查、路径判断、阻塞
 
 工作流模式复利（L2）：S1 路由时额外注入历史 `workflow_pattern` top-3（confidence ≥ 0.5）。详见 state-model.md「工作流模式复利 L2」。
 
+## 测试台账注入（v0.12 §43.5，advisory 级）
+
+读取 `docs/test-ledger/INDEX.md`（如存在），注入 `coverage_status=partial` 的模块列表。新 change 涉及这些模块时，提示「有未解决的 deferred 测试项，本次可考虑解决」。读取失败时静默跳过，不阻断。
+
 ## 路由结果显式呈现（强制，B3）
 
 路由判断后**必须**向用户确认，路由是建议而非决定：