kld-sdd 2.6.0 → 2.6.2

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/controller-strategy.md

@@ -0,0 +1,32 @@
+# Controller 层策略
+
+> 影响等级：HIGH
+
+## 策略 A：拆 RED→GREEN
+
+为每个 Controller 接口生成 RED 测试（使用 @WebMvcTest），拆为 RED→GREEN 对。
+
+适用：Controller 含业务逻辑。
+
+示例任务表：
+
+| TASK-ID | 行为点 | 类型 | 验收标准 |
+|---------|--------|------|---------|
+| CTRL-RED-1 | POST /api/v1/auth/login 返回 Token | 测试-RED | @WebMvcTest 测试运行失败 |
+| CTRL-GREEN-1 | AuthController 接线 | 实现-GREEN | RED 测试通过 |
+
+## 策略 B：非 TDD 接线任务
+
+Controller 作为非 TDD 模块，独立接口层任务，仅做编译检查。
+
+适用：Controller 为纯接线（调用 Service + 返回 Result）。
+
+示例任务表：
+
+| TASK-ID | 类型 | 验收标准 |
+|---------|------|---------|
+| CTRL | 接口层（非 TDD） | Controller 编译通过，调用对应 Service 方法，返回 Result |
+
+## 声明要求
+
+必须在 tasks.md §2.0 中声明使用哪种策略。

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/dag-generation-rules.md

@@ -0,0 +1,20 @@
+# DAG 生成规则
+
+> 影响等级：HIGH
+
+## 规则对照表
+
+| test-strategy | DAG 规则 |
+|---------------|---------|
+| `tdd` | 每个行为点拆为 RED→GREEN 对，GREEN Depends-On RED；每 3-5 个行为点后可插入 REFACTOR（Depends-On 前一个 GREEN）；模块末尾可加 VERIFY（Depends-On 最后一个 GREEN/REFACTOR） |
+| `impl-first` | 实现任务在前，测试任务 Depends-On 实现任务 |
+| `none` | 不生成测试任务，仅编译检查 |
+
+## TDD 拆分规则
+
+1. 将 spec.md 中每个需求项的每个场景拆为一个行为点
+2. 每个行为点生成一对 RED+GREEN 任务
+3. RED 任务依赖前置基础设施任务
+4. GREEN 任务依赖对应的 RED 任务
+5. 可选每 3-5 个行为点后插入 REFACTOR
+6. 模块末尾可保留 VERIFY 任务

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/des-step-annotation.md

@@ -0,0 +1,36 @@
+# DES 步骤级标注规则
+
+> 影响等级：MEDIUM
+> 引用方：opsx-design（design.md 生成）、opsx-design/checklist.md（自检）
+
+## 问题
+
+一个 DES 元素包含完整流程，多个 GREEN 任务映射到同一 DES，AI 在实现 GREEN-N 时读取 design.md 看到完整流程，自然将所有步骤一次性实现。
+
+## 规则
+
+当 `test-strategy=tdd` 时，若一个 DES 元素的流程将被拆分为多个 RED/GREEN 对，必须在流程的每个步骤后标注任务归属：
+
+```
+格式：→ [步骤描述] [GREEN-N]
+
+示例：
+→ [COUNT borrow_records → 校验 < 5]                    [GREEN-2]
+→ [SELECT books FOR UPDATE → 校验 available_count > 0] [GREEN-1]
+→ [UPDATE available_count - 1]                          [GREEN-1]
+→ [INSERT borrow_records]                               [GREEN-1]
+```
+
+### 标注规则
+
+1. 先确定该 DES 元素会被拆成几个 RED/GREEN 对（从 spec 场景数推断）
+2. 为每个步骤标注它属于哪个 GREEN-N（即哪个 RED 的断言会覆盖此步骤）
+3. 若一个步骤同时被多个 GREEN 覆盖，标注所有归属（如 `[GREEN-1, GREEN-2]`）
+4. 若一个步骤不属于任何 GREEN（如事务边界），标注 `[shared]`
+
+### 适用条件
+
+- 仅当 `test-strategy=tdd` 时强制
+- 若 DES 元素只对应一个 RED/GREEN 对，无需标注
+
+> 目的：让 apply 阶段的 AI 在实现 GREEN-N 时，只看标注了对应 `[GREEN-N]` 的步骤，避免一次性实现整个 DES 流程。

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/exception-path-coverage.md

@@ -0,0 +1,47 @@
+# 异常路径测试覆盖门禁
+
+> 影响等级：HIGH
+> 引用方：opsx-task（任务拆解时扫描异常分支）、opsx-apply（GREEN 完成后检查覆盖率）、opsx-check（验证异常路径覆盖）
+
+## 核心规则
+
+每个 Service 方法中的异常路径（`orElseThrow`、边界检查 `if` 分支、`throw` 语句）必须有对应的 RED 测试覆盖。
+
+## 任务拆解阶段（opsx-task 引用）
+
+在生成 TDD 任务时，必须扫描 design.md 中每个 DES 流程的所有异常分支：
+
+1. 提取每个 DES 流程图中的异常路径（如"图书不存在""可借数量=0""借阅记录不存在"等）
+2. 每个异常路径必须对应一个独立 RED 任务，或合并到同一 RED 的多个测试方法中
+3. 在 tasks.md 的 RED 任务验收标准中明确列出所有异常路径的测试方法名
+
+### 拆分策略
+
+| 场景 | 拆分方式 | 示例 |
+|------|---------|------|
+| 异常路径独立性强 | 每个异常路径一个独立 RED 任务 | `borrowBook_bookNotFound_throws4001`、`borrowBook_availableCount0_throws2002` |
+| 异常路径相似度高 | 合并为一个 RED 任务的多个测试方法 | `returnBook_recordNotFound_throws4001` + `returnBook_alreadyReturned_throws2002` 合并到一个 RED |
+| 分支覆盖（如 role+status 组合） | 每个分支一个测试方法 | `listBorrowRecords_adminWithStatus`、`listBorrowRecords_adminNoStatus`、`listBorrowRecords_userWithStatus`、`listBorrowRecords_userNoStatus` |
+
+### 检查清单
+
+- [ ] 每个 `orElseThrow` 路径有对应测试
+- [ ] 每个边界检查 `if` 分支有对应测试
+- [ ] 每个错误码（spec.md 定义）有对应测试场景
+- [ ] 多分支方法的每个分支有独立测试方法
+
+## 实施阶段（opsx-apply 引用）
+
+GREEN 任务完成后，检查异常路径覆盖率：
+
+1. 扫描 GREEN 实现的生产代码，提取所有 `throw` 语句和 `orElseThrow` 调用
+2. 对比 RED 测试方法，确认每个异常路径都有对应测试
+3. 未覆盖的异常路径 → 补充 RED 测试（不允许跳过）
+
+## 检查阶段（opsx-check 引用）
+
+在 TDD 合规性检查中，验证：
+
+- [ ] spec.md 中定义的每个错误码都有对应的 RED 测试场景
+- [ ] design.md 中每个 DES 流程的异常分支都有对应任务
+- [ ] tasks.md 中 RED 任务数量 ≥ spec 场景数 + 异常路径数

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/green-scope-declaration.md

@@ -0,0 +1,45 @@
+# GREEN 任务 Scope 声明规则
+
+> 影响等级：HIGH
+> 引用方：opsx-apply/implementer-prompt.md（子代理派发）
+
+## 问题
+
+implementer-prompt 的 YAGNI 约束是泛化的"不提前实现未要求的功能"，AI 无法判断"未要求"的边界，尤其当 design.md 展示了完整流程时。
+
+## 规则
+
+GREEN 任务执行时，在编写生产代码之前，必须完成 Scope 声明：
+
+### 执行步骤
+
+1. **列出当前 RED 测试的断言清单**
+   - 如：assertNotNull(result), assertEquals(1, availableCount), assertEquals("borrowed", status)
+
+2. **列出 design.md 中本 DES 元素的完整流程步骤**
+   - 如：count 校验 → available_count 校验 → 扣减 → 创建记录
+
+3. **标记步骤归属**
+   - ✅ 属于：当前 RED 断言会覆盖此步骤
+   - ⛔ 不属于：当前 RED 断言不会覆盖此步骤（属于后续 RED 或共享步骤）
+
+4. **仅实现标记为 ✅ 的步骤**
+
+5. **Scope 自检**
+   - 检查生产代码中是否有未被任何当前 RED 断言覆盖的逻辑路径
+   - 若存在且属于后续 RED 的行为 → 删除
+
+## 示例
+
+```
+RED-1 断言：availableCount=1, status=borrowed
+DES 流程：[count校验] [available_count校验] [扣减] [创建记录]
+
+标记：
+  [count校验]           ⛔ 不属于（RED-2 的断言覆盖此步骤）
+  [available_count校验]  ✅ 属于
+  [扣减]                ✅ 属于
+  [创建记录]            ✅ 属于
+
+→ 仅实现后三个步骤，不实现 count 校验
+```

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/green-yagni-fence.md

@@ -0,0 +1,41 @@
+# GREEN 任务 YAGNI 围栏规则
+
+> 影响等级：HIGH
+> 引用方：opsx-task（任务生成）、opsx-task/checklist.md（自检）
+
+## 问题
+
+GREEN-N 任务实现时，AI 可能提前实现后续 RED-(N+1) 的行为，导致 RED-(N+1) 测试立即通过，违反 TDD 铁律。
+
+根因：design.md 中一个 DES 元素包含完整流程，多个 GREEN 任务映射到同一 DES，AI 倾向于一次性实现整个流程。
+
+## 规则
+
+每个 GREEN-N 任务描述末尾必须追加"不提前实现"围栏声明：
+
+```
+格式：不提前实现 [RED-(N+1) 的行为描述]，仅让当前 RED 测试通过。
+```
+
+### 围栏生成逻辑
+
+1. 生成 GREEN-N 时，读取同 capability 的 RED-(N+1) 任务描述
+2. 提取 RED-(N+1) 测试的行为点（如"借阅上限校验"）
+3. 在 GREEN-N 任务描述末尾追加围栏声明
+
+### 边界情况
+
+- 若 GREEN-N 是该 capability 最后一个 GREEN（无后续 RED），围栏声明为：
+  `仅实现当前 RED 测试覆盖的行为路径，不提前实现后续 capability 的功能。`
+- 若 GREEN-N 和 RED-(N+1) 映射到不同 DES 元素，仍需围栏（防止跨 DES 越界）
+
+## 示例
+
+```
+GREEN-1: 实现 BorrowService.borrowBook()，行锁锁定图书，校验 available_count > 0，
+         扣减可借数量，创建借阅记录。
+         不提前实现借阅上限校验（RED-2 的行为），仅让当前 RED 测试通过。
+
+GREEN-2: 实现借阅上限校验（5 本），超限抛出异常（错误码 2001）。
+         不提前实现归还功能（RED-3 的行为），仅让当前 RED 测试通过。
+```

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/multi-validation-split.md

@@ -0,0 +1,36 @@
+# 多校验拆分规则
+
+> 影响等级：MEDIUM
+> 引用方：opsx-spec（spec.md 生成）、opsx-spec/checklist.md（自检）
+
+## 问题
+
+单个 STMT 捆绑多个"必须校验"条件时，AI 在实现时倾向于将同一 STMT 的所有要求一次性完成，导致后续 RED 测试立即通过。
+
+## 规则
+
+当单个 STMT 包含多个"必须校验"条件时，必须检查：
+
+1. 每个校验条件是否有对应的独立 AC 场景
+2. 若多个校验条件共享一个 AC 场景，必须拆分为独立场景
+3. 每个校验条件至少对应一个独立 AC 场景（成功场景 + 失败场景）
+
+## 反例（禁止）
+
+```
+STMT: 系统必须允许用户借阅图书，借阅时必须校验：可借数量大于 0、用户当前借阅数未达上限。
+AC-01: 借阅成功（available_count > 0 且借阅数 < 上限）
+→ 仅一个场景，两个校验条件共享
+```
+
+## 正例（要求）
+
+```
+STMT: 系统必须允许用户借阅图书，借阅时必须校验：可借数量大于 0、用户当前借阅数未达上限。
+AC-01: 借阅成功（available_count > 0 且借阅数 < 上限）
+AC-02: 借阅上限拦截（借阅数 = 上限）
+AC-03: 可借数量不足（available_count = 0）
+→ 每个校验条件有独立失败场景
+```
+
+> 目的：每个校验条件有独立场景 → 独立 RED 测试 → 独立 GREEN 实现，避免 AI 在一个 GREEN 中实现所有校验。

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/non-tdd-modules.md

@@ -0,0 +1,17 @@
+# 非 TDD 模块排除规则
+
+> 影响等级：MEDIUM
+
+## 不需要红绿循环的模块
+
+以下模块按常规任务处理，不拆红绿循环：
+
+- 前端 UI 页面（Vue 组件）→ UI层任务
+- 项目脚手架/配置 → 配置任务
+- 数据库迁移脚本（SQL DDL）→ 数据层任务
+- 前端路由/状态管理/API 封装 → UI层任务
+- Controller 层（可选）→ 接口层任务（当选择策略 B 时）
+
+## Controller 层处理策略
+
+Controller 层处理策略需在 tasks.md §2.0 中明确声明，不能默认选择。

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/refactor-checklist.md

@@ -0,0 +1,45 @@
+# REFACTOR 阶段检查点
+
+> 影响等级：HIGH
+> 引用方：opsx-tdd-core/reference.md §3（REFACTOR 执行步骤）、opsx-apply/implementer-prompt.md（REFACTOR 任务执行）、opsx-apply/checklist.md（REFACTOR 门禁）
+
+## 核心原则
+
+REFACTOR 是在测试全绿状态下改善代码结构，**不添加行为、不改变 public API、不跨模块**。
+
+## 检查清单（7 项）
+
+⛔ REFACTOR 任务完成后，必须逐项勾选：
+
+- [ ] **测试全绿**：重构前所有测试通过，重构后所有测试仍通过
+- [ ] **public API 不变**：重构前后 public 方法集合不变（无新增/删除 public 方法）
+- [ ] **测试用例集合不变**：无新增/删除测试方法（重构不改变测试，只改变实现）
+- [ ] **行为保持**：重构不引入新的业务逻辑分支（diff 中不应有新的 `if`/`for`/`while` 业务逻辑）
+- [ ] **重构范围限制**：只修改当前模块的代码，不跨模块重构
+- [ ] **代码行数控制**：重构后代码行数不应显著增加（增加超过 20% 需说明理由）
+- [ ] **具体重构点**：列出至少 2 个具体的代码改善点（如"提取 getBookForUpdate 公共方法""消除 borrowBook/returnBook 中的重复行锁查询"）
+
+## REFACTOR 跳过条件
+
+当以下条件全部满足时，可以跳过 REFACTOR 任务（在任务描述中标注"无需重构"）：
+
+1. 当前模块代码行数 < 50 行
+2. 无重复代码（无 2 处以上相似的代码块）
+3. 方法命名清晰（无缩写、无歧义）
+4. 无超过 20 行的方法
+
+## 量化评估标准
+
+| 指标 | 改善标准 | 检测方法 |
+|------|---------|---------|
+| 重复代码 | 重构后减少 | 对比重构前后相似代码块数量 |
+| 方法长度 | 最长方法行数不增加 | 对比最长方法行数 |
+| 命名质量 | 无缩写、无歧义命名 | 人工/AI 审查 |
+| 圈复杂度 | 不增加 | 对比 if/for/while/case 决策点数量 |
+
+## 禁止事项
+
+- ❌ 在 REFACTOR 阶段添加新的业务功能
+- ❌ 在 REFACTOR 阶段修改测试代码（除删除冗余测试外，但需谨慎）
+- ❌ 在 REFACTOR 阶段跨模块重构（如同时修改 Service 和 Controller）
+- ❌ 在 REFACTOR 阶段改变 public API（方法签名、返回类型等）

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/task-type-definitions.md

@@ -0,0 +1,23 @@
+# 任务类型定义
+
+> 影响等级：HIGH
+
+## TDD 任务类型
+
+| 类型 | 说明 | 验收标准要求 |
+|------|------|-------------|
+| 测试-RED | 带真实断言的失败测试 | 测试运行失败，且失败原因正确（功能未实现） |
+| 实现-GREEN | 让当前测试通过的最少代码 | 写最少代码让对应 RED 测试通过，不提前实现未要求的功能 |
+| 重构-REFACTOR | 测试全绿下的代码清理 | 所有测试仍绿，代码结构改善 |
+| 测试-验证 | 全量测试运行验证 | 全部测试通过 |
+
+## RED 任务额外必填字段
+
+- 测试方法名（`{method}_{state}_{outcome}` 格式）
+- Given-When-Then 结构描述
+- 输出文件路径
+- 关联 spec 场景编号
+
+## REFACTOR 任务额外必填字段
+
+- 具体重构方向（至少列出 2 个重构点，如"提取公共方法""消除重复代码"）

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/tdd-strategy-selection.md

@@ -0,0 +1,13 @@
+# TDD 策略选择
+
+> 影响等级：HIGH
+
+## 三种策略
+
+- **A) TDD（红绿重构循环）**：每个行为点先写失败测试（红），再写最少代码让它通过（绿），最后重构。DAG: RED → GREEN → REFACTOR → ...。任务数量约为模块级拆分的 3-5 倍。适合核心业务逻辑/质量要求高/需要测试驱动设计。
+- **B) Impl-First（代码先行）**：先生成实现任务，测试作为验证步骤。DAG: 实现代码 → 测试验证。适合 UI 层/配置类/快速原型。
+- **C) None（仅实现）**：不生成测试任务，仅编译检查。适合简单配置/文档更新。
+
+## 交互引导
+
+使用 AskUserQuestion 工具询问用户选择哪种策略。不得默认选择。

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/test-execution-gate.md

@@ -0,0 +1,25 @@
+# 测试执行门禁
+
+> 影响等级：HIGH
+
+## 门禁策略
+
+| test-strategy | 行为 |
+|---------------|------|
+| `tdd` | ⛔ 强制执行：RED 确认失败且失败原因是功能未实现、GREEN 确认通过、REFACTOR 运行全部测试确认仍绿、测试失败禁止继续 |
+| `impl-first` | ⚠️ 警告模式：运行测试，失败时显示警告但允许继续 |
+| `none` | 跳过：不执行测试门禁 |
+
+## TDD 执行合规自检
+
+- [ ] RED 任务执行后已运行测试并确认失败
+- [ ] RED 任务失败原因是"功能未实现"而非编译错误
+- [ ] GREEN 任务执行后已运行测试确认通过
+- [ ] GREEN 任务未提前实现没有测试要求的功能
+- [ ] REFACTOR 任务执行后已运行全部测试确认仍绿
+- [ ] 未出现"先写生产代码再补测试"的情况
+
+## 门禁体系
+
+- Check 门禁：apply 前必须确认 check 已完成
+- 测试门禁：`sdd-apply-test-gate.cjs` 在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验是否真实执行过测试，无证据则阻断

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/test-skeleton-telemetry.md

@@ -0,0 +1,19 @@
+# test-skeleton telemetry 模板
+
+> 影响等级：MEDIUM
+
+## TDD 测试骨架任务
+
+当任务是"测试骨架"（仅编写测试用例、实现尚未编写，测试预期失败/红灯）时，`task_update` 必须在 `--details-json` 中带 `"task_kind":"test-skeleton"`，`--result=success`（骨架按 TDD 计划完成即成功），`test_results.failed` 如实记录红灯数。
+
+```bash
+node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 测试骨架完成（TDD 红灯）" --details-json='{"task_kind":"test-skeleton","test_results":{"command":"<实际测试命令>","passed":0,"failed":<红灯数>,"skipped":0,"duration_ms":0}}'
+```
+
+## 实现任务
+
+实现任务不带 `task_kind`（默认 implementation），按真实测试结果记录。
+
+```bash
+node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"test_results":{"command":"<实际测试命令>","passed":<通过数>,"failed":0,"skipped":0,"duration_ms":0}}'
+```

package/templates/skills/kld-sdd/opsx-test/SKILL.md

@@ -131,6 +131,24 @@ node skywalk-sdd/log.cjs record --type=test_result --command=test --project=. --
 > |--------|------|---------|
 > | [name] | [file:line] | [error] |"
 
+### 5a. TDD 报告模式（当 test-strategy=tdd 时）
+
+在标准测试报告基础上，增加 TDD 追踪信息：
+
+| 行为点 | RED 状态 | GREEN 状态 | 测试方法 |
+|--------|---------|-----------|---------|
+| [行为点1] | ✅ 曾失败 | ✅ 已通过 | [testMethodName] |
+| [行为点2] | ✅ 曾失败 | ✅ 已通过 | [testMethodName] |
+| ... | | | |
+
+⛔ 反模式检测核心 3 项（inline）：
+- [ ] 无"测试 mock 行为而非真实行为"
+- [ ] 无"生产类中加测试专用方法"
+- [ ] 无"不理解依赖就 mock"
+
+> 完整 5 项反模式检测见 opsx-tdd-anti-patterns/SKILL.md §4
+> TDD 报告模式见 opsx-tdd-review/SKILL.md §3
+
 ### 6. 【交互引导】根据结果引导下一步
 
 **全部通过**：