kld-sdd 2.4.18 → 2.5.0

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-spec
 description: "技术契约文档技能 - 为每个能力创建 spec.md，定义业务场景与技术规范"
 argument-hint: "[change-name] [上下文文件...]"
@@ -26,16 +26,14 @@ allowed-tools:
 > 即使用户提供了代码作为上下文，也只用于分析现有实现，**不执行任何代码操作**。
 > 代码实现将在 `/opsx-apply` 阶段进行。
 > **完成本阶段后，绝对禁止自动继续执行 design/task 等后续阶段。**
-
+> 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
 ---
 
@@ -48,7 +46,7 @@ allowed-tools:
 | 上游依赖 | proposal.md（能力列表） |
 | 下游依赖 | design.md → tasks.md |
 
-**【文件结构】**：每个 capability 生成一个独立的 spec 文件：
+**【文件结构】**（Full 模式，默认）：每个 capability 生成一个独立的 spec 文件：
 ```
 openspec/changes/<name>/
 ├── proposal.md
@@ -62,10 +60,27 @@ openspec/changes/<name>/
 └── tasks.md
 ```
 
+**【文件结构】**（Simple 模式，proposal.md frontmatter `mode: simple`）：文档落变更根目录，不创建 specs/ 子目录：
+```
+openspec/changes/<name>/
+├── proposal.md
+├── spec.md              # 单一 spec 文件
+├── design.md
+└── tasks.md
+```
+
 ---
 
 ## 启动流程
 
+### 0. 【S1 模式检测】读取 proposal.md mode
+
+读取当前变更的 `proposal.md` frontmatter，提取 `mode` 字段：
+- `mode: simple` → Simple 模式（文档落变更根目录）
+- `mode: full` 或未设置 → Full 模式（默认，文档落 specs/<capability>/）
+
+Simple 模式下跳过 Capability 选择，直接在变更根目录创建 `spec.md`。
+
 ### 1. 【交互引导】确认变更名称
 
 若未提供，列出当前所有变更供用户选择：
@@ -88,15 +103,9 @@ openspec list
 
 ### 3. 【上下文加载】识别并读取用户提供的文件
 
-**自动识别上下文文件**：
-若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
+**自动识别上下文文件**：若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
 
-**上下文类型与用途**：
-| 上下文类型 | 用途 | 如何融入 spec |
-|------------|------|--------------|
-| 需求文档 | 提取验收标准、用户故事 | 转化为需求项和场景 |
-| 代码文件 | 了解现有实现约束 | 纳入技术契约和约束条件 |
-| API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
+> 上下文类型（需求文档 / 代码文件 / API 文档）与用途见 `./reference.md`「§3 上下文类型与用途」。
 
 **【可选】业务知识库检索**：
 术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
@@ -134,40 +143,19 @@ openspec list
 - 需求项使用 `####`（4个#）
 - 场景使用 `#####`（5个#）
 
-### 7. 质量红线自检
-
-写入文档前，逐项确认：
-- [ ] 文档结构完全符合 `openspec-templates/spec.md` 模板
-- [ ] 需求项格式正确（`#### 需求项：`，4个#）
-- [ ] 场景格式正确（`##### 场景：`，5个#）
-- [ ] 每个需求项都有验收标准
-- [ ] 技术契约章节完整（数据模型、接口契约）
-- [ ] 文档末尾包含质量红线检查清单
-- [ ] 100% 覆盖 proposal.md 中该 Capability 的描述
+### 6.5 【Node 版本约束来源校验】
 
-**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+若 spec.md 中声明了 Node 版本约束（如 `>=14`、`>=18` 等），必须在该需求项或 proposal.md 中**声明来源**：
 
-**【必须输出】质量自检报告**：
+- 来源可为：`package.json` 的 `engines.node`、官方运行时要求、上游框架最低版本等。
+- 若 proposal.md 未声明来源且 spec.md 新增了 Node 版本约束 → 提示用户确认：「spec.md 中 Node 版本约束 `<version>` 未在 proposal.md 声明来源，请确认依据（package.json/运行时/框架要求），避免版本约束无追溯。」
+- 用户确认后在 spec.md 需求项备注来源，或回补 proposal.md 的约束条件章节。
 
-自检完成后，**必须**向用户展示结构化的自检报告：
+> 目的：避免 spec 凭空写入 Node 版本约束而无上下游依据，导致契约不可追溯。
 
-> "### 质量自检结果
->
-> | 检查项 | 状态 | 说明 |
-> |--------|------|------|
-> | 文档结构符合模板 | ✅/❌ | |
-> | 需求项格式正确（4个#） | ✅/❌ | 共 N 个需求项 |
-> | 场景格式正确（5个#） | ✅/❌ | 共 M 个场景 |
-> | 每个需求项有验收标准 | ✅/❌ | |
-> | 技术契约章节完整 | ✅/❌ | |
-> | 质量红线检查清单 | ✅/❌ | |
-> | 覆盖 proposal.md 描述 | ✅/❌ | |
-> | 使用「必须」强制要求 | ✅/⚠️ | |
-> | 技术选型包含版本 | ✅/⚠️ | |
->
-> **结论**：全部通过 ✅ / 存在问题需修复 ❌"
+### 7. 质量红线自检
 
-**未通过项处理**：若有 ❌ 项，自动修复后重新输出报告，直至全部 ✅。
+> 写入文档前逐项确认，完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。自检完成后**必须**输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出，直至全部 ✅。
 
 ### 8. 确认文档并输出结果
 
@@ -190,10 +178,18 @@ openspec list
 
 ## Guardrails
 
-- **必须以 `openspec-templates/spec.md` 为模板基准**
-- spec.md 聚焦【What】，不写 How（留给 design.md）
-- **需求项格式必须正确**：`####` 需求项、`#####` 场景
-- 每个需求项必须有清晰的验收标准
-- 技术契约必须可执行、无歧义
-- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
-- **⛔ 单阶段原则：完成 spec.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx-design`，**绝对禁止自动执行 design/task 等后续阶段**。每个阶段必须由用户主动触发。
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **必须以 `openspec-templates/spec.md` 为模板基准**。
+- spec.md 聚焦【What】，不写 How（留给 design.md）。
+- **需求项格式必须正确**：`####` 需求项、`#####` 场景；每个需求项必须有清晰的验收标准。
+- 技术契约必须可执行、无歧义。
+- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作。
+- **⛔ 单阶段原则**：完成 spec.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-design`，绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 spec 需要校验时 — 含阶段边界⛔（Spec 阶段约束）、§7 质量红线自检（7 项）、Guardrails ⛔ 强制项勾选表。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§3 上下文类型与用途表、§7 质量自检报告模板（结构化表格）。

package/templates/skills/kld-sdd/opsx-spec/checklist.md

@@ -0,0 +1,46 @@
+---
+description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 spec 需要校验时读取。
+---
+
+# opsx-spec — 检查清单（checklist）
+
+> 执行 opsx-spec 时逐项校验。含阶段边界⛔、§7 质量红线自检、Guardrails ⛔ 强制项。
+> 详细模板（telemetry 命令 / §3 上下文类型表 / §7 质量自检报告模板）见 `./reference.md`。
+
+---
+
+## 阶段边界⛔（Spec 阶段约束）
+
+- [ ] ✅ 允许：创建/编辑 spec.md 文档、读取代码/文档作为上下文分析
+- [ ] ❌ 禁止：创建/修改任何代码文件、执行代码生成、运行测试
+- [ ] ⛔ 单阶段原则：完成 spec.md 后必须立即停止，等待用户主动触发下一阶段
+- [ ] 即使用户提供代码作为上下文，只用于分析现有实现，不执行任何代码操作
+- [ ] 代码实现将在 `/opsx-apply` 阶段进行
+- [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 design/task 等后续阶段
+
+---
+
+## §7 质量红线自检
+
+写入文档前，逐项确认：
+- [ ] 文档结构完全符合 `openspec-templates/spec.md` 模板
+- [ ] 需求项格式正确（`#### 需求项：`，4个#）
+- [ ] 场景格式正确（`##### 场景：`，5个#）
+- [ ] 每个需求项都有验收标准
+- [ ] 技术契约章节完整（数据模型、接口契约）
+- [ ] 文档末尾包含质量红线检查清单
+- [ ] 100% 覆盖 proposal.md 中该 Capability 的描述
+
+**如有任意一项未满足，重新生成对应章节，直至全部通过。** 自检完成后必须输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出。
+
+---
+
+## Guardrails ⛔ 强制项
+
+- [ ] 必须以 `openspec-templates/spec.md` 为模板基准
+- [ ] spec.md 聚焦【What】，不写 How（留给 design.md）
+- [ ] **需求项格式必须正确**：`####` 需求项、`#####` 场景
+- [ ] 每个需求项必须有清晰的验收标准
+- [ ] 技术契约必须可执行、无歧义
+- [ ] ⛔ **阶段边界**：禁止执行任何代码创建/修改操作
+- [ ] ⛔ **单阶段原则**：完成 spec.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-design`，绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。

package/templates/skills/kld-sdd/opsx-spec/reference.md

@@ -0,0 +1,49 @@
+---
+description: opsx-spec 的详细模板：telemetry 命令、上下文类型表、质量自检报告模板。仅在需要参考详细模板时读取。
+---
+
+# opsx-spec — 详细参考（reference）
+
+> 本文件承载 opsx-spec 的重细节模板：telemetry 命令、§3 上下文类型表、§7 质量自检报告模板。
+> SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## §3 上下文类型与用途
+
+| 上下文类型 | 用途 | 如何融入 spec |
+|------------|------|--------------|
+| 需求文档 | 提取验收标准、用户故事 | 转化为需求项和场景 |
+| 代码文件 | 了解现有实现约束 | 纳入技术契约和约束条件 |
+| API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
+
+---
+
+## §7 质量自检报告模板
+
+自检完成后，**必须**向用户展示结构化的自检报告：
+
+> "### 质量自检结果
+>
+> | 检查项 | 状态 | 说明 |
+> |--------|------|------|
+> | 文档结构符合模板 | ✅/❌ | |
+> | 需求项格式正确（4个#） | ✅/❌ | 共 N 个需求项 |
+> | 场景格式正确（5个#） | ✅/❌ | 共 M 个场景 |
+> | 每个需求项有验收标准 | ✅/❌ | |
+> | 技术契约章节完整 | ✅/❌ | |
+> | 质量红线检查清单 | ✅/❌ | |
+> | 覆盖 proposal.md 描述 | ✅/❌ | |
+> | 使用「必须」强制要求 | ✅/⚠️ | |
+> | 技术选型包含版本 | ✅/⚠️ | |
+>
+> **结论**：全部通过 ✅ / 存在问题需修复 ❌"
+
+**未通过项处理**：若有 ❌ 项，自动修复后重新输出报告，直至全部 ✅。

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-task
 description: "局部任务拆解技能 - 针对单一 Capability 创建 DAG 任务清单"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -26,23 +26,23 @@ allowed-tools:
 > tasks.md 定义的是「待执行的任务清单」，**不是立即执行代码**。
 > 请引导用户使用 `/opsx-apply` 进入实施阶段。
 > **完成本阶段后，绝对禁止自动继续执行 apply/check 等后续阶段。**
+> 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **⚠️ 渐进式上下文加载原则**
 >
-> - 本技能针对**单一 Capability** 执行任务拆解
-> - **输入路径**：`changes/<name>/specs/<capability>/design.md`
-> - **输出路径**：`changes/<name>/specs/<capability>/tasks.md`
-> - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的文档
-
+> - 本技能针对**单一 Capability** 执行任务拆解（Simple 模式例外，见下方 S1 说明）
+> - **输入路径**（Full 模式）：`changes/<name>/specs/<capability>/design.md`
+> - **输出路径**（Full 模式）：`changes/<name>/specs/<capability>/tasks.md`
+> - **输入路径**（Simple 模式）：`changes/<name>/design.md`
+> - **输出路径**（Simple 模式）：`changes/<name>/tasks.md`
+> - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的文档（Full 模式）
 
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
 ---
 
@@ -59,6 +59,18 @@ allowed-tools:
 
 ## 启动流程
 
+### 0. 【S1 模式检测】读取 proposal.md mode
+
+读取当前变更的 `proposal.md` frontmatter，提取 `mode` 字段：
+- `mode: simple` → Simple 模式（tasks.md 落变更根目录，跳过 Capability 选择）
+- `mode: full` 或未设置 → Full 模式（默认，tasks.md 落 specs/<capability>/）
+
+### 0a. 【S2/M6 单文件拆解策略】
+
+Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。按可独立测试的函数/单元拆分任务，每个任务对应一个可独立验证的代码单元。同文件多处改动有顺序依赖时合并为一个任务。
+
+## 启动流程
+
 ### 1. 【交互引导】确认变更名称和 Capability
 
 若未提供参数，列出已有 design.md 的 Capability 供用户选择。
@@ -120,7 +132,7 @@ allowed-tools:
 
 **若已设置**：向用户确认
 > "🧪 **当前测试策略：[test-strategy]**
-> 
+>
 > - `tdd`: 测试驱动 - 测试任务作为实现任务的前置依赖
 > - `impl-first`: 实现优先 - 先实现后测试
 > - `none`: 无测试 - 不生成测试任务
@@ -148,15 +160,7 @@ allowed-tools:
 
 ### 6. 【交互引导】确认任务拆解策略
 
-向用户确认拆解维度、任务粒度、预计 DAG 层级。
-
-**根据 test-strategy 调整 DAG 生成规则：**
-
-| test-strategy | DAG 生成规则 |
-|---------------|---------------|
-| `tdd` | 每个实现任务前必须有对应的测试任务，实现任务 Depends-On 测试任务 |
-| `impl-first` | 实现任务在前，测试任务 Depends-On 实现任务 |
-| `none` | 不生成测试任务，仅编译检查 |
+向用户确认拆解维度、任务粒度、预计 DAG 层级。**根据 test-strategy 调整 DAG 生成规则**，规则表（tdd / impl-first / none 对应的 DAG 生成规则）见 `./reference.md`「§6 DAG 生成规则表」。
 
 ### 7. 创建局部 tasks.md（含 DAG 拓扑）
 
@@ -164,26 +168,11 @@ allowed-tools:
 
 **以 `openspec-templates/tasks.md` 的结构为骨架**，填充内容。
 
-**必须包含**：
-1. **任务执行拓扑图（DAG）** - 层级关系清晰
-2. **原子任务清单** - 每个任务包含：
-   - `[TASK-XXX-01]` 唯一标识
-   - `类型`: 数据层 / 接口层 / UI层 / 测试
-   - `依赖`: 前置依赖（无 或 TASK-ID 列表）
-   - `状态`: [ ] 未完成
-   - 任务描述、输入、输出、实现步骤、验收标准
+> **必须包含**：任务执行拓扑图（DAG）+ 原子任务清单。任务结构字段（TASK-ID / 类型 / 依赖 / 状态 / 描述等）见 `./reference.md`「§7 任务结构」。
 
 ### 8. 质量红线自检
 
-- [ ] 文档结构完全符合 `openspec-templates/tasks.md` 模板
-- [ ] **拓扑图已绘制**：层级关系清晰
-- [ ] **依赖字段已填写**：每个任务的依赖已明确
-- [ ] **无循环依赖**：拓扑中不存在环
-- [ ] 每个任务颗粒度 ≤ 5 分钟
-- [ ] 100% 覆盖 design.md 定义
-- [ ] 每个任务都有验收标准
-
-**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+> 逐项确认，完整 7 项自检清单（结构符合模板 / 拓扑图已绘制 / 依赖字段已填写 / 无循环依赖 / 颗粒度 ≤5 分钟 / 100% 覆盖 design / 每任务有验收标准）见 `./checklist.md`「§8 质量红线自检」。如有任意一项未满足，重新生成对应章节，直至全部通过。
 
 ### 9. 确认任务并输出
 
@@ -200,17 +189,25 @@ allowed-tools:
 
 最终输出：
 - 文档路径
-- 下一步提示："运行 `/opsx-check <name>` 执行质量检查，或 `/opsx-apply <name> <capability>` 开始实施"
+- 下一步提示："下一步：运行 `/opsx-check <name>` 完成质量检查，通过后再 `/opsx-apply <name> <capability>` 开始实施"
 
 ---
 
 ## Guardrails
 
-- **必须以 `openspec-templates/tasks.md` 为模板基准**
-- **⛔ 渐进式加载**：严格按 overview.md → proposal.md → spec.md → design.md 顺序
-- **⛔ 隔离红线**：绝对禁止读取同级其他 Capability 的文档
-- **⛔ DAG 必须完整**：每个任务必须有依赖字段
-- **⛔ 无循环依赖**：DAG 中不允许存在环
-- 任务颗粒度宁可过细也不要过粗
-- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
-- **⛔ 单阶段原则：完成 tasks.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx-check` 或 `/opsx-apply`，**绝对禁止自动执行 apply/check 等后续阶段**。每个阶段必须由用户主动触发。
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **必须以 `openspec-templates/tasks.md` 为模板基准**。
+- **⛔ 渐进式加载**：严格按 overview.md → proposal.md → spec.md → design.md 顺序。
+- **⛔ 隔离红线**：绝对禁止读取同级其他 Capability 的文档。
+- **⛔ DAG 必须完整**：每个任务必须有依赖字段；**⛔ 无循环依赖**：DAG 中不允许存在环。
+- 任务颗粒度宁可过细也不要过粗。
+- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作。
+- **⛔ 单阶段原则**：完成 tasks.md 后必须立即停止。仅提示用户下一步 **check 优先**：先运行 `/opsx-check` 通过质量检查，再 `/opsx-apply`（apply 须在 check 通过后）；绝对禁止自动执行 apply/check 等后续阶段。每个阶段必须由用户主动触发。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 task 需要校验时 — 含阶段边界⛔（Task 阶段约束）、§8 质量红线自检（7 项）、Guardrails ⛔ 强制项勾选表。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§6 DAG 生成规则表（tdd/impl-first/none）、§7 任务结构（TASK-ID/类型/依赖/状态/描述等字段）。

package/templates/skills/kld-sdd/opsx-task/checklist.md

@@ -0,0 +1,46 @@
+---
+description: opsx-task 的阶段强制检查点与自检清单。仅在执行 task 需要校验时读取。
+---
+
+# opsx-task — 检查清单（checklist）
+
+> 执行 opsx-task 时逐项校验。含阶段边界⛔、§8 质量红线自检、Guardrails ⛔ 强制项。
+> 详细模板（telemetry 命令 / §6 DAG 生成规则表 / §7 任务结构）见 `./reference.md`。
+
+---
+
+## 阶段边界⛔（Task 阶段约束）
+
+- [ ] ✅ 允许：创建/编辑 tasks.md 文档、读取代码作为任务分析参考
+- [ ] ❌ 禁止：创建/修改任何代码文件、执行代码生成、运行测试
+- [ ] ⛔ 单阶段原则：完成 tasks.md 后必须立即停止，等待用户主动触发下一阶段
+- [ ] tasks.md 定义的是「待执行的任务清单」，不是立即执行代码
+- [ ] 引导用户使用 `/opsx-apply` 进入实施阶段
+- [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 apply/check 等后续阶段
+
+---
+
+## §8 质量红线自检
+
+- [ ] 文档结构完全符合 `openspec-templates/tasks.md` 模板
+- [ ] **拓扑图已绘制**：层级关系清晰
+- [ ] **依赖字段已填写**：每个任务的依赖已明确
+- [ ] **无循环依赖**：拓扑中不存在环
+- [ ] 每个任务颗粒度 ≤ 5 分钟
+- [ ] 100% 覆盖 design.md 定义
+- [ ] 每个任务都有验收标准
+
+**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+
+---
+
+## Guardrails ⛔ 强制项
+
+- [ ] 必须以 `openspec-templates/tasks.md` 为模板基准
+- [ ] ⛔ **渐进式加载**：严格按 overview.md → proposal.md → spec.md → design.md 顺序
+- [ ] ⛔ **隔离红线**：绝对禁止读取同级其他 Capability 的文档
+- [ ] ⛔ **DAG 必须完整**：每个任务必须有依赖字段
+- [ ] ⛔ **无循环依赖**：DAG 中不允许存在环
+- [ ] 任务颗粒度宁可过细也不要过粗
+- [ ] ⛔ **阶段边界**：禁止执行任何代码创建/修改操作
+- [ ] ⛔ **单阶段原则**：完成 tasks.md 后必须立即停止；仅提示用户下一步 **check 优先**：先运行 `/opsx-check` 通过质量检查，再 `/opsx-apply`（apply 须在 check 通过后）；绝对禁止自动执行 apply/check 等后续阶段。每个阶段必须由用户主动触发。

package/templates/skills/kld-sdd/opsx-task/reference.md

@@ -0,0 +1,40 @@
+---
+description: opsx-task 的详细模板：telemetry 命令、DAG 生成规则表、任务结构。仅在需要参考详细模板时读取。
+---
+
+# opsx-task — 详细参考（reference）
+
+> 本文件承载 opsx-task 的重细节模板：telemetry 命令、§6 DAG 生成规则表、§7 任务结构。
+> SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## §6 DAG 生成规则表
+
+**根据 test-strategy 调整 DAG 生成规则：**
+
+| test-strategy | DAG 生成规则 |
+|---------------|---------------|
+| `tdd` | 每个实现任务前必须有对应的测试任务，实现任务 Depends-On 测试任务 |
+| `impl-first` | 实现任务在前，测试任务 Depends-On 实现任务 |
+| `none` | 不生成测试任务，仅编译检查 |
+
+---
+
+## §7 任务结构
+
+**必须包含**：
+1. **任务执行拓扑图（DAG）** - 层级关系清晰
+2. **原子任务清单** - 每个任务包含：
+   - `[TASK-XXX-01]` 唯一标识
+   - `类型`: 数据层 / 接口层 / UI层 / 测试
+   - `依赖`: 前置依赖（无 或 TASK-ID 列表）
+   - `状态`: [ ] 未完成
+   - 任务描述、输入、输出、实现步骤、验收标准

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

@@ -101,6 +101,18 @@ allowed-tools:
 | JUnit (Maven) | `mvn test` |
 | JUnit (Gradle) | `./gradlew test` |
 
+### 4a. 【M3 Telemetry】记录测试结果
+
+测试执行完成后，在 stage_end 之前记录 `test_result` 事件：
+
+```bash
+node skywalk-sdd/log.cjs record --type=test_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="[passed]/[total] passed" --details-json="{\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":<passed>,\"failed\":<failed>,\"skipped\":<skipped>,\"coverage\":<coverage>,\"duration_ms\":<duration_ms>}}"
+```
+
+此事件供 report 的 `test_pass_summary` 采集（M3），确保报告能显示真实测试通过率。
+
+> **⚠️ P1-4 coverage 不得为 null**：`test_results.coverage` 必须填实测覆盖率数值（跑了 `--coverage` 就填数值，如 `86.5`）；未跑 `--coverage` 时填字符串 `"not-run"` 并在 summary 说明原因。**禁止填 `null`**。若 `proposal.md` 含"覆盖率 ≥ X%"验收标准，强制使用 `--coverage` 运行测试。
+
 ### 5. 输出结构化测试报告
 
 > "📊 **测试执行报告**