@hunterzheng/kld-sdd 2.4.19

package/templates/openspec/tasks.md

@@ -0,0 +1,287 @@
+# 实施任务拆解 - [Capability 名称]
+
+> **定位**：单一 Capability 的 AI 编码引擎执行单元
+> 
+> **⚠️ 边界声明**：本任务清单仅服务于当前 Capability，严禁跨模块任务。
+> 
+> **【质量红线】颗粒度必须达到"AI能在5分钟内实现"；且拆解的任务和验证逻辑必须 100% 覆盖 spec 和 design
+
+---
+
+## 1. 任务总览
+
+### 1.1 关联文档
+
+| 文档 | 路径 | 说明 |
+|-----|------|------|
+| 全局契约 | `openspec/specs/overview.md` | 全局约束基线 |
+| 业务意图 | `proposal.md` | 变更背景 |
+| 技术契约 | `specs/[capability]/spec.md` | 当前能力规格 |
+| 技术方案 | `specs/[capability]/design.md` | 当前能力设计 |
+
+### 1.2 实现范围
+
+<!-- 本次编码要覆盖的功能范围 -->
+
+### 1.3 技术栈
+
+- 语言：
+- 框架：
+- 依赖：
+
+---
+
+## 2. 任务执行拓扑图
+
+> **⚠️ 依赖管理**：任务必须按层级执行，每层任务可并行，跨层必须等待前置完成
+
+### 2.0 测试策略
+
+<!-- 该字段从 proposal.md frontmatter 中读取，由 /opsx:propose 阶段用户选择 -->
+
+**当前测试策略**：`[测试驱动 | 实现优先 | 无测试]`
+
+| 策略 | 说明 | 拓扑结构 |
+|--------|------|------------|
+| 测试驱动 | 测试先行 | 测试骨架 → 实现代码 → 测试验证 |
+| 实现优先 | 代码先行 | 实现代码 → 测试验证 |
+| 无测试 | 仅编译检查 | 仅实现代码 |
+
+**测试驱动模式拓扑示例**：
+```
+层级 1: [TASK-01-TEST] 编写 UserService 单元测试（骨架）
+层级 2: [TASK-02-IMPL] 实现 UserService（依赖: TASK-01-TEST）
+层级 3: [TASK-03-VERIFY] 运行测试验证（依赖: TASK-02-IMPL）
+```
+
+**实现优先模式拓扑示例**：
+```
+层级 1: [TASK-01-IMPL] 实现 UserService
+层级 2: [TASK-02-TEST] 编写并运行测试（依赖: TASK-01-IMPL）
+```
+
+### 2.1 拓扑图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  层级 1 (无依赖，可并行)                                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │ TASK-XXX-01  │  │ TASK-XXX-02  │  │ TASK-XXX-03  │       │
+│  └──────┬───────┘  └──────┬───────┘  └──────────────┘       │
+│         │                 │                                  │
+│         v                 v                                  │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │  层级 2 (依赖层级 1)                                 │ │
+│  │  ┌──────────────┐  ┌──────────────┐                     │ │
+│  │  │ TASK-XXX-04  │  │ TASK-XXX-05  │                     │ │
+│  │  │ 依赖: 01    │  │ 依赖: 02    │                     │ │
+│  │  └──────┬───────┘  └──────┬───────┘                     │ │
+│  │         │                 │                              │ │
+│  │         v                 v                              │ │
+│  │  ┌─────────────────────────────────────────────────────┐│ │
+│  │  │  层级 3 (依赖层级 2)                             ││ │
+│  │  │  ┌──────────────┐                                   ││ │
+│  │  │  │ TASK-XXX-06  │                                   ││ │
+│  │  │  │ 依赖: 04,05 │                                   ││ │
+│  │  │  └──────────────┘                                   ││ │
+│  │  └─────────────────────────────────────────────────────┘│ │
+│  └─────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 层级汇总
+
+| 层级 | 任务列表 | 可并行 | 前置依赖 |
+|-----|---------|-------|--------|
+| 层级 1 | TASK-XXX-01, TASK-XXX-02 | ✅ 是 | 无 |
+| 层级 2 | TASK-XXX-03 | - | 层级 1 |
+| 层级 3 | TASK-XXX-04 | - | 层级 2 |
+
+---
+
+## 3. 原子任务清单
+
+<!-- 【质量红线】每个任务必须能在5分钟内由AI实现 -->
+
+### 3.0 任务类型说明
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| 数据层 | 实体、DTO、Mapper、数据访问 | 数据库操作相关 |
+| 接口层 | Service、Controller、API | 业务逻辑和接口 |
+| UI层 | 组件、页面、样式 | 前端展示相关 |
+| 测试-骨架 | 测试类结构、Mock设置 | 测试驱动模式下的测试前置任务 |
+| 测试-验证 | 测试用例实现、断言 | 实现后的测试验证任务 |
+| 配置 | 配置文件、依赖添加 | 项目配置相关 |
+
+---
+
+### [TASK-XXX-01] 任务名称
+
+- **类型**: 数据层 / 接口层 / UI层 / 测试
+- **依赖**: 无
+- **状态**: [ ] 未完成
+
+#### 任务描述
+<!-- 一句话描述本任务要做什么 -->
+
+#### 输入
+- 
+
+#### 输出
+- 
+
+#### 实现步骤
+1. 
+2. 
+3. 
+
+#### 验收标准
+- [ ] 验收标准 1
+- [ ] 验收标准 2
+
+#### 关联设计
+- spec.md 章节：
+- design.md 章节：
+
+---
+
+### [TASK-XXX-02] 任务名称
+
+- **类型**: 数据层 / 接口层 / UI层 / 测试
+- **依赖**: 无
+- **状态**: [ ] 未完成
+
+#### 任务描述
+
+#### 输入
+
+#### 输出
+
+#### 实现步骤
+1. 
+2. 
+3. 
+
+#### 验收标准
+- [ ] 
+- [ ] 
+
+#### 关联设计
+- spec.md 章节：
+- design.md 章节：
+
+---
+
+### [TASK-XXX-03] 任务名称
+
+- **类型**: 数据层 / 接口层 / UI层 / 测试
+- **依赖**: TASK-XXX-01, TASK-XXX-02
+- **状态**: [ ] 未完成
+
+#### 任务描述
+
+#### 输入
+
+#### 输出
+
+#### 实现步骤
+1. 
+2. 
+3. 
+
+#### 验收标准
+- [ ] 
+- [ ] 
+
+#### 关联设计
+- spec.md 章节：
+- design.md 章节：
+
+---
+
+## 4. 验证方式
+
+### 4.1 单元测试要求
+
+<!-- 【质量红线】每个任务必须有对应的单元测试 -->
+
+| 任务 ID | 测试类型 | 测试场景 | 断言内容 |
+|--------|---------|---------|---------|
+| TASK-XXX-01 | | | |
+| TASK-XXX-02 | | | |
+
+### 4.2 集成测试场景
+
+| 场景 | 前置条件 | 操作步骤 | 预期结果 |
+|-----|---------|---------|---------|
+| | | | |
+
+### 4.3 手动验证清单
+
+- [ ] 验证项 1
+- [ ] 验证项 2
+
+---
+
+## 5. 外部依赖
+
+| 依赖项 | 类型 | 提供方 | 状态 | 备注 |
+|-------|------|-------|------|------|
+| | 其他能力 / 第三方 | | ✅ 就绪 / ⏳ 等待 | |
+
+---
+
+## 6. 代码规范
+
+### 6.1 命名规范
+
+- 类名：
+- 方法名：
+- 变量名：
+
+### 6.2 代码风格
+
+- 缩进：
+- 注释：
+- 异常处理：
+
+### 6.3 日志规范
+
+- 日志级别：
+- 日志格式：
+- 敏感信息处理：
+
+---
+
+## 7. 交付物
+
+### 7.1 代码文件
+
+| 文件路径 | 说明 | 对应任务 |
+|---------|------|---------|
+| | | TASK-XXX-01 |
+
+### 7.2 测试文件
+
+| 文件路径 | 说明 | 对应任务 |
+|---------|------|---------|
+| | | TASK-XXX-01 |
+
+### 7.3 文档更新
+
+- [ ] README 更新
+- [ ] 接口文档更新
+- [ ] 变更日志更新
+
+---
+
+> **质量红线检查清单**
+> - [ ] 每个任务颗粒度符合"5分钟可实现"标准
+> - [ ] 任务清单 100% 覆盖 spec.md 定义
+> - [ ] 任务清单 100% 覆盖 design.md 定义
+> - [ ] 每个任务都有明确的验收标准
+> - [ ] 每个任务都有对应的单元测试要求
+> - [ ] **依赖拓扑已明确**（依赖字段已填写）
+> - [ ] **任务执行拓扑图已绘制**（层级关系清晰）
+> - [ ] 无循环依赖

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

@@ -0,0 +1,251 @@
+---
+name: opsx-apply
+description: "变更实施技能 - 针对单一 Capability 按 DAG 依赖顺序实现代码"
+argument-hint: "[change-name] [capability-name] [上下文文件...]"
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: sdd-team
+  version: "3.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - EnterWorktree
+  - ExitWorktree
+  - Agent
+---
+
+你是一个 SDD（Specification-Driven Development）变更实施专家。激活本技能后，你将引导用户按 DAG 依赖顺序逐任务实施代码。
+
+
+> **⚠️ 渐进式上下文加载原则**
+>
+> - 本技能针对**单一 Capability** 执行实施
+> - **上下文**：overview.md → proposal.md → 当前 capability 的 spec/design/tasks
+> - ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
+> **📊 Telemetry（必做，不得跳过）**
+> - 阶段开始 / 阶段结束 / `task_update` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
+> - 不得跳过任何 telemetry 记录；`task_update` 的 `--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算。
+
+> **🔒 Git 策略（只读增强，不改变开发流）**
+> - Git 只作为可选度量数据源，不是 apply 前置条件。
+> - 禁止自动执行 `git init`、`git add`、`git commit`、`git checkout -b`、`git switch -c`。
+> - 若项目已有 Git，仅允许读取 `git rev-parse HEAD`、`git diff --numstat` 等只读信息。
+> - 若项目不是 Git 仓库，进入 `vcs_mode=no-git`，`base_git_sha=none`，继续实施，不得中断。
+> - 只有用户明确要求时，才允许提交或创建分支；SDD 度量本身不得主动提交。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | Apply - 单一 Capability 代码实施 |
+| 输入 | overview.md → proposal.md → spec.md → design.md → tasks.md |
+| 输出 | 代码文件、测试文件、任务状态更新 |
+| 关键机制 | DAG 依赖拦截、编译门禁、测试门禁、实时状态更新 |
+
+---
+
+## 启动流程
+
+### 0. 【Telemetry 必做】只读探测 Git 基线
+
+先以只读方式探测版本控制状态。Git 只是增强数据源，失败不得中断 apply。
+
+禁止事项：
+- 禁止自动执行 `git init`
+- 禁止自动执行 `git add`
+- 禁止自动执行 `git commit`
+- 禁止自动创建或切换分支
+
+探测流程：
+```bash
+git rev-parse --is-inside-work-tree
+```
+
+若命令成功，设置：
+- `vcs_mode=readonly`
+- `base_git_sha=<git rev-parse HEAD 的输出>`
+
+只读读取基线 SHA：
+```bash
+git rev-parse HEAD
+```
+
+若命令失败，设置：
+- `vcs_mode=no-git`
+- `base_git_sha=none`
+
+非 Git 项目必须继续实施，不得为了度量自动创建仓库或提交快照。
+
+### 1. 【交互引导】确认变更名称和 Capability
+
+**步骤 1a - 确认变更名称**：
+若未提供 change-name，列出当前所有变更供用户选择：
+```bash
+openspec list --json
+```
+
+**步骤 1b - 确认 Capability**：
+若未提供 capability-name，读取已存在 tasks.md 的 Capability 列表，使用 **AskUserQuestion** 让用户选择：
+> "请选择要实施的 Capability：
+> - A. `user-auth`（用户认证）- tasks.md ✅ 已就绪
+> - B. `user-profile`（用户资料）- tasks.md ✅ 已就绪
+> - C. `data-export`（数据导出）- tasks.md ❌ 未拆解"
+
+**【路径确认】**：
+> "📍 当前操作目标：
+> - **变更**：`<change-name>`
+> - **Capability**：`<capability-name>`
+> - **任务文件**：`changes/<name>/specs/<capability>/tasks.md`"
+
+### 1.2 【Check 门禁检查】验证质量门禁状态
+
+> **⛔ 强制门禁**：apply 阶段开始前，必须确认 check 阶段已完成。这是 SDD 流程的关键质量保障。
+> 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 形成双重保障。
+
+### 1.5 【本地并行】Worktree 与工作区（建议性策略）
+
+> **目标（本质）**：在**本地仓库**加快 SDD Apply——让**解耦**的 spec/capability 可以各自实现、互不踩目录，做完再按依赖顺序合并回你**当时所在的分支**（集成分支，如 `hotfix-1`）。
+>
+> **不是**：保护 `master`、不是「主分支只放文档」、不是远程流水线分支策略。一切基于**本地 Git + 本地 worktree**。
+
+#### 两层并行（不要混为一谈）
+
+| 层级 | 手段 | 适用 |
+|------|------|------|
+| **Capability 级**（跨 spec） | 每个解耦的 capability **单独**跑一次 `/opsx-apply` + **独立** worktree/apply 分支 | proposal 中能力**可并行**、无文件/接口/数据强依赖 |
+| **Task 级**（cap 内） | **同一** worktree 内，DAG 同层子代理并行 | tasks.md 同层任务不改相同文件 |
+
+- 本技能单次仍只实施**一个** capability；「多 spec 并行」= 多个 apply 会话 + 多个 worktree，不是一次加载多个 capability 文档。
+- §5 子代理并行 **不** 再建 worktree；Capability 级并行在 §1.5 决定「本次是否建 worktree」。
+
+> **完整策略**（Step 0.1 分支/隔离校验、Step 0.25 record-base、Step 0.5 冲突预检、Step 1 创建、多 cap 合并顺序、设置流程）见 `./reference.md`「§1.5 本地并行」。**快速参考**见 `./worktree-setup.md`（与 reference §1.5 并存：reference=完整策略，worktree-setup=快速参考）。
+
+### 2. 渐进式上下文加载
+
+**⛔ 只加载当前 Capability 的四文档链：**
+
+```
+第 1 层：全局基线
+  → openspec/specs/overview.md
+
+第 2 层：宏观背景
+  → changes/<name>/proposal.md
+
+第 3 层：当前 Capability 四文档
+  → spec.md → design.md → tasks.md
+
+⛔ 隔离红线：禁止加载其他 Capability 的文档！
+```
+
+**【可选】业务知识库检索**：
+编码中遇到不明业务名词时，可调用 **opsx-knowledge** skill 辅助理解。
+不得因知识库建议偏离 tasks/spec；查询失败时继续实施。
+
+### 3. 解析 DAG 任务拓扑
+
+从 tasks.md 中：
+- 提取所有任务的 `[TASK-ID]` 和 `依赖` 字段
+- 构建 DAG 拓扑图
+- 计算执行层级（Layer）
+- **检测循环依赖**，若存在则中止
+
+### 4. 显示进度和 DAG 拓扑
+
+向用户展示当前进度、DAG 状态、下一个可执行任务。
+
+### 5. 按 DAG 顺序逐任务实施
+
+**⛔ DAG 依赖拦截机制**：
+
+```
+对于每个待处理任务：
+
+1. 读取任务的依赖字段
+2. 检查所有前置任务的状态是否为 [x]
+3. 若前置任务未完成 → 拦截并提示
+4. 若前置任务已完成 → 允许执行
+```
+
+**执行每个任务**（a-g 步骤）：
+
+a. **DAG 依赖检查 & 层级收集** — 收集依赖已满足的待执行任务；同层多个独立任务可并行派发子代理。
+b. **显示当前层级任务** — `📍 层级 [X]：准备派发 [K] 个子代理并行处理 [M] 个任务`。
+c. **🤖 派发子代理实现代码** — 使用 Agent 工具并行派发同层任务，⛔ 子代理阶段不创建 worktree/分支。**派发模板与状态处理见 `./reference.md`「§5c 子代理派发模板」+ `./implementer-prompt.md`**。
+d. **⛔ 编译检查门禁** — 每完成一个任务后必须编译通过；**详细见 `./checklist.md`「§5d 编译检查门禁」**。
+e. **⛔ 测试执行门禁** — 按 `proposal.md` 的 `test-strategy` 决定（tdd=强制, impl-first=警告, none=跳过）；**详细见 `./checklist.md`「§5e 测试执行门禁」**。
+f. **⛔ 立即更新任务状态** — tasks.md `- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]` 两种格式同步；显示 `✅ [TASK-ID] 已完成 [N/M]`；记录任务级 Telemetry（`task_update`，命令模板见 `./reference.md`）。
+g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下一层级任务。
+
+### 5.1 【Telemetry 必做】记录 AI 产出快照
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。**完整命令模板与说明见 `./reference.md`「§5.1 记录 AI 产出快照」**。
+
+### 6. 完成或暂停时显示状态
+
+展示 DAG 执行摘要，引导下一步：
+> "📊 **实施进度摘要**：
+> - 已完成：[N/M] 任务
+> - 当前层级：Layer [X]
+> - 下一步建议：[继续实施 / 运行测试 / 归档]"
+>
+> **💡 代码评审提示**：
+> 建议执行 `/kld-review --local` 对本次变更的代码进行评审。
+> 该技能可在公司内部 SkillHub 下载安装。
+>
+> **🧹 Worktree 收尾**：若本次使用了 worktree，见 **§6.1**；若判定未建 worktree，跳过 §6.1。
+> **其他 capability**：若并行 apply 中仍有未 finish 的 worktree，提示按 proposal 依赖顺序继续 `finish`。
+
+### 6.0 【条件必做】单元测试真实执行（`test-strategy` 非 `none`）
+
+当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时，在结束 apply 或执行 §6.1 收尾之前，必须真实运行单元测试并留 telemetry 证据。**详细执行要求与证据形式见 `./reference.md`「§6.0」+ `./checklist.md`「§6.0 单元测试真实执行自检」**。Claude Code 的 `sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验；无证据则阻断。
+
+### 6.1 【条件必做】Worktree 收尾（仅当 §1.5 已创建 worktree）
+
+> **⛔ 本次 Apply 若创建了 worktree**：DAG 全部完成且 §6.0 测试门禁（若适用）通过后，必须在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）。
+> 若 §1.5 判定未建 worktree（串行、强依赖、沙箱回退），跳过本节。
+
+**前置条件、执行命令、脚本行为、常用 flags、回退方式见 `./reference.md`「§6.1 Worktree 收尾」+ `./checklist.md`「§6.1 Worktree 收尾前置条件自检」**。
+
+> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。
+
+---
+
+## Guardrails
+
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 双重保障。
+- **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，禁止加载同级其他 Capability 的文档。
+- **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截。
+- **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
+- **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据。
+- **⛔ 必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式同步。
+- **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行。
+- **⛔ Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告。
+- **Worktree 为加速手段，非必选项**：校验通过且解耦方可多 worktree；有依赖或共享修改面则串行。
+- **本地集成分支**：使用 worktree 时 `--record-base` 记录用户当前本地分支为 merge 目标，禁止默认写死 `master`。
+- **⛔ 已建 worktree 则收尾必做**：`apply-worktree-finish.cjs` merge 回 `integration_base`；多 cap 并行时按依赖顺序逐个 finish。
+- **⛔ 子代理不建分支**：worktree/apply 分支仅在 §1.5（主会话）创建一次，§5 子代理不得再建。
+- **显示进度反馈**：每完成一个任务显示「✅ [TASK-ID] 已完成 [N/M]」。
+- **保持任务聚焦**：每次只处理一个任务。
+- **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 apply 需要校验门禁/自检时 — 含 §1.2 Check 门禁检查点、§5d/§5e 编译/测试门禁自检、§6.0 单元测试真实执行自检、§6.1 worktree 收尾前置条件、Guardrails ⛔ 强制项勾选表。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end/task_update/ai_adoption_review/worktree_finish）、§1.5 worktree 全套策略（Step 0.1-3 + record-base + 多 cap 合并顺序）、§5c 子代理派发、§5.1 AI 产出快照、§6.0 单元测试、§6.1 worktree 收尾脚本。
+- `implementer-prompt.md` 为子代理派发提示模板（§5c 派发时组合 tasks/design/overview 上下文使用）。
+- `worktree-setup.md` 为 worktree 快速参考（§1.5 策略的精简版，与 reference.md §1.5 完整版并存：reference=完整策略，worktree-setup=快速参考）。

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

@@ -0,0 +1,94 @@
+---
+description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 apply 需要校验时读取。
+---
+
+# opsx-apply — 检查清单（checklist）
+
+> 执行 opsx-apply 时逐项校验。含阶段强制阻断检查点（Check 门禁）、编译/测试门禁自检、单元测试真实执行自检、worktree 收尾前置条件、Guardrails ⛔ 强制项。
+> 详细命令模板与策略见 `./reference.md`；worktree 快速参考见 `./worktree-setup.md`。
+
+---
+
+## 阶段强制阻断检查点
+
+### §1.2 Check 门禁（apply 前必做）
+
+- [ ] 读取 telemetry 事件数据，检查当前 change 是否已有完成的 check 阶段
+  - `node skywalk-sdd/log.cjs doctor --project=. --change=<change-name>` 或搜 `skywalk-sdd/data/events/<change-name>/` 的 `stage_end` + `command=check` + `result=success`
+- [ ] check 已完成 ✅ → 继续 apply 流程
+- [ ] check 未完成 ❌ → **强制拒绝** apply，引导用户先执行 `/opsx-check <change-name>`（不得跳过）
+- [ ] telemetry 数据缺失（新项目无历史） → 提示首次执行先运行 `/opsx-check`，询问是否现在执行
+- [ ] 用户坚持跳过 check → **强制拒绝**，不得跳过 check 直接 apply
+
+> 🔗 门禁体系：Check = `sdd-skill-apply-gate` + `sdd-apply-gate` + 本技能 §1.2；单元测试（`test-strategy: tdd | impl-first`）= `sdd-apply-test-gate`，在 `log.cjs end` / `apply-worktree-finish` / Stop 时校验是否**真实执行**过测试。
+
+---
+
+## 编译/测试门禁自检（每完成一个任务）
+
+### §5d 编译检查门禁
+
+- [ ] 检测项目类型并执行编译命令
+- [ ] 编译成功 → 继续下一步
+- [ ] 编译失败 → **必须立即修复，禁止标记为已完成！**
+
+### §5e 测试执行门禁（按 `proposal.md` 的 `test-strategy`）
+
+- [ ] `tdd` → **⛔ 强制执行**：运行相关测试，测试失败禁止继续，必须修复
+- [ ] `impl-first` → **⚠️ 警告模式**：运行测试，失败时显示警告但允许继续
+- [ ] `none` → **跳过**：不执行测试门禁
+
+### 任务状态实时更新
+
+- [ ] tasks.md：`- [ ]` → `- [x]`（拓扑图和任务详情中的复选框）
+- [ ] 同时：`- **状态**: [ ] 未完成` → `- **状态**: [x] 已完成`
+- [ ] 两种格式同步更新，不可遗漏
+- [ ] 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
+- [ ] 记录任务级 Telemetry（`task_update`，`--task-id=<TASK-ID>` 必填，否则 E4 指标无法计算）
+
+---
+
+## §6.0 单元测试真实执行自检（`test-strategy` 非 `none`）
+
+- [ ] 在结束 apply 或 §6.1 收尾之前，在项目根或 worktree 内**真实运行**单元测试命令（`npm test` / `pytest` / `go test` 等）
+- [ ] 留下可核验 telemetry 证据（任选其一）：
+  - `node skywalk-sdd/log.cjs record --type=test_result ...`（`test_results.command` 非空，且 `passed`/`failed`/`duration_ms` 有实际值）
+  - `task_update` 的 `details-json` 中 `test_results` 含真实执行数据
+  - 或单独运行 `/opsx-test` 并完成 `command=test` 的 `stage_end`
+- [ ] `tdd`：无测试证据不得结束 apply / 不得 finish worktree
+- [ ] `impl-first`：实现后必须补跑并记录
+- [ ] `none`：跳过本节与 test gate
+
+---
+
+## §6.1 Worktree 收尾前置条件自检（仅当 §1.5 已建 worktree）
+
+- [ ] worktree 内 `git status` 干净（实现代码已全部 commit）
+- [ ] 主仓库无与 merge 冲突的未跟踪文件（见 §1.5 Step 0.5）
+- [ ] `test-strategy` 为 `tdd`/`impl-first` 时，§6.0 测试证据已存在
+- [ ] 在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）
+- [ ] 执行：`node skywalk-sdd/apply-worktree-finish.cjs --change=<变更名称> --capability=<capability-name>`
+- [ ] 默认 merge 目标 = §1.5 `--record-base` 写入的 `integration_base`（**不是**默认 master）
+- [ ] 若 §1.5 判定未建 worktree（串行、强依赖、沙箱回退）→ 跳过本节
+
+---
+
+## Guardrails ⛔ 强制项（全流程）
+
+- [ ] ⛔ **Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 形成双重保障
+- [ ] ⛔ **渐进式加载**：只加载当前 Capability 的四文档链
+- [ ] ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
+- [ ] ⛔ **DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
+- [ ] ⛔ **编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成
+- [ ] ⛔ **测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据
+- [ ] ⛔ **必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式（`- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]`）同步
+- [ ] **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行
+- [ ] ⛔ **Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告；未通过不得按 full 并行策略拆 `kld-sdd/<change>/<cap>`
+- [ ] **Worktree 为加速手段，非必选项**：校验通过且解耦方可多 worktree；有依赖或共享修改面则串行
+- [ ] **本地集成分支**：使用 worktree 时 `--record-base` 记录用户当前本地分支为 merge 目标，禁止默认写死 `master`
+- [ ] ⛔ **已建 worktree 则收尾必做**：`apply-worktree-finish.cjs` merge 回 `integration_base`；多 cap 并行时按依赖顺序逐个 finish
+- [ ] ⛔ **子代理不建分支**：worktree/apply 分支仅在 §1.5（主会话）创建一次，§5 子代理不得再建
+- [ ] **Capability 级并行**：多个 `/opsx-apply` 会话 = 多个 worktree；禁止为未解耦的 cap 仅因 full 模式而拆分支
+- [ ] **显示进度反馈**：每完成一个任务显示「✅ [TASK-ID] 已完成 [N/M]」
+- [ ] **保持任务聚焦**：每次只处理一个任务
+- [ ] **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问