@xulthekl/team-flow 0.30.0 → 0.32.1

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）
 
 路由判断后**必须**向用户确认，路由是建议而非决定：

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

@@ -307,3 +307,24 @@ 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, v0.13 §52 B3 归位)
+
+**归位说明（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. `tf test-matrix-export <test-matrix.json> <change-dir>/test-matrix.md` 转换为 team-flow 格式
+6. 用户确认（轻量版 DP-A）
+7. contract 中添加 `## Test Matrix` 段引用 + `tf state rebuild` 捕获 test_matrix_hash
+
+**非 GLAF4 项目**：contract-builder 使用预加载的 test-strategy skill 直接生成 `test-matrix.md`（同等强制）。
+
+**用户拒绝 glaf4-tests 时**：回退内置 test-strategy 生成（不是跳过矩阵）。确无测试需求的特例走显式 skip + 理由。