kld-sdd 2.4.19 → 2.5.1

package/templates/hooks/codebuddy/settings.json

@@ -0,0 +1,72 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-prompt.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-skill-apply-gate.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-pre-tool.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-test-gate.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-gate.cjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-post-tool.cjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-test-gate.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-stop.cjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/openspec/proposal.md

@@ -1,6 +1,5 @@
 ---
 # 【用户选择配置 - 由 /opsx:propose 引导填写】
-mode: ""           # full=每个能力域独立文档(specs/<capability>/*), simple=单一文档(spec.md/design.md/tasks.md)
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 ---
 

package/templates/openspec/spec.md

@@ -8,9 +8,9 @@
 
 ---
 
-## 1. 需求规格（官方格式）
+## 1. 需求规格
 
-<!-- 此章节遵循 openspec 官方格式，用于与 CLI 工具兼容 -->
+<!-- SDD 模板格式（需求项 #### / 场景 #####）为本框架唯一标准 -->
 
 ### 新增需求
 

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-apply
 description: "变更实施技能 - 针对单一 Capability 按 DAG 依赖顺序实现代码"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -29,11 +29,15 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始 / 阶段结束 / `task_update` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
+> - 不得跳过任何 telemetry 记录；`task_update` 的 `--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算；TDD 测试骨架任务须在 `--details-json` 带 `"task_kind":"test-skeleton"`（P3，详见 `./reference.md`）。
+> - 较大的 `--details-json` 负载可先写入文件，再通过 `--details-file=skywalk-sdd/state/<变更名称>-<type>.json` 传递（例如 `task_update` 对应 `<变更名称>-task-update.json`）。
+> - `task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的 checkbox；录入成功后，agent 可以通过 `check-task` 命令验证该 checkbox 已更新。
+> - **⚠️ P1-2 ai_adoption_review 必填 ai_diff**：记录 AI 产出快照时，`--details-json` 必须含 `ai_diff.files_changed`（即使=0）与 `ai_diff.files`（产出文件路径数组，非空），**不得只发 `assertions`**。`vcs_mode=readonly` 时 `ai_diff.added_lines` 不得为 null——用只读 `git diff --numstat HEAD` 取值（apply Git 只读策略允许）；`vcs_mode=no-git` 时可填 null。工具侧已加记录时硬校验：`files` 空数组或 `readonly` 下 `added_lines=null` 将 **拒绝记录**（与 conformance_review 校验对称）。缺失 `ai_diff` 会导致 report 变更文件数为 null（工具侧已加 `assertions[].files` 兜底，但 `ai_diff` 是主数据源）。完整模板见 `./reference.md`「§5.1」。
+> - **⚠️ P1-3 process_note 必记**：阶段内发生 修复/澄清/决策/API 故障/换模型 时，**必须**记 `process_note` 事件（`kind` 见 `./reference.md`「必记节点清单」）。全程 0 条 process_note 视为过程记录缺失，report 过程记录区显示空。
 
 > **🔒 Git 策略（只读增强，不改变开发流）**
 > - Git 只作为可选度量数据源，不是 apply 前置条件。
@@ -111,44 +115,7 @@ openspec list --json
 ### 1.2 【Check 门禁检查】验证质量门禁状态
 
 > **⛔ 强制门禁**：apply 阶段开始前，必须确认 check 阶段已完成。这是 SDD 流程的关键质量保障。
-
-**检查方式**：
-
-1. **读取 telemetry 事件数据**，检查当前 change 是否已有完成的 check 阶段：
-   ```bash
-   node skywalk-sdd/log.cjs doctor --project=. --change=<change-name>
-   ```
-   或在 `skywalk-sdd/data/events/<change-name>/` 目录中搜索 `stage_end` + `command=check` + `result=success` 事件。
-
-2. **若 check 已完成** ✅：
-   > "✅ Check 门禁已通过（事件 ID: evt_xxx），继续 apply 流程。"
-
-3. **若 check 未完成** ❌：
-   > "⛔ **[Check 门禁未通过]** 检测到当前 change (`<change-name>`) 尚未执行 check 阶段或 check 未通过。
-   >
-   > **必须先执行质量门禁检查，再开始代码实施：**
-   >
-   > ```
-   > /opsx-check <change-name>
-   > ```
-   >
-   > **原因**：check 阶段验证文档完整性、一致性、可执行性，跳过 check 直接 apply 可能导致需求误解或设计缺陷。
-   >
-   > **操作顺序**：`/opsx-check → /opsx-apply`
-   >
-   > 是否要现在执行 check？"
-
-   - 若用户确认执行 check → 引导执行 `/opsx-check`
-   - 若用户坚持跳过 → **强制拒绝**，不得跳过 check 直接 apply
-
-4. **若 telemetry 数据缺失**（如新项目无历史数据）：
-   > "⚠️ 未找到 check 阶段记录。如果这是首次执行，请先运行 `/opsx-check <change-name>` 完成质量门禁。
-   >
-   > 是否要现在执行 check？"
-
-> **🔗 门禁体系**：
-> - 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 时校验是否**真实执行**过测试
+> 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
 
 ### 1.5 【本地并行】Worktree 与工作区（建议性策略）
 
@@ -166,166 +133,7 @@ openspec list --json
 - 本技能单次仍只实施**一个** capability；「多 spec 并行」= 多个 apply 会话 + 多个 worktree，不是一次加载多个 capability 文档。
 - §5 子代理并行 **不** 再建 worktree；Capability 级并行在 §1.5 决定「本次是否建 worktree」。
 
-#### 何时建议建 worktree / 按 capability 切分支？（模型判断，非强制）
-
-**倾向创建**（full 模式常见：`.worktrees/apply-<change>-<capability>` + `kld-sdd/<change>/<capability>`）：
-
-- `proposal.md` §3 中该 capability 与并行中的其他能力**无**「修改同一模块 / 共享表 / 必须先合入」等描述
-- `design.md` 显示文件路径、包、表与并行中的其他 cap **基本不重叠**
-- 用户需要在**同一集成分支**上并行推进多个 cap，且机器资源允许（多份 `node_modules`）
-
-**倾向不建 / 串行 apply**（仍在集成分支上改，或只开一个 worktree）：
-
-- proposal 写明 capability **依赖**（B 依赖 A 已合入）
-- 多 cap 改**同一文件/模块/配置**（merge 冲突几乎必然）
-- 数据库迁移、公共类型、单例注册等**顺序敏感**
-- 已有另一个 capability 的 worktree **尚未 finish merge** 到集成分支，且当前 cap 需要基于**最新**集成结果开发
-- 沙箱禁止 `git worktree add` → 回退当前目录 + 功能分支，并告知用户
-
-**full 模式「一 capability 一分支」**：是**命名与目录约定 + 建议**，须先通过下方 **§1.5 Step 0.1 校验** 再命名/建 worktree。simple 模式通常**一 change 一 worktree**。
-
-#### Step 0.1 【必做】分支/隔离校验（早于 record-base 与 `git worktree add`）
-
-> 在建议分支名 `kld-sdd/<change>/<capability>` 或创建 worktree **之前**，用 `proposal.md` + 各 capability **spec 依赖信息** 做交叉校验。未通过则**不**按 full 并行策略拆分支，改为串行或本次不建 worktree。
-
-**Step A — 读变更级能力清单（允许读 proposal，不读其它 cap 的 design/tasks）**
-
-从 `changes/<change-name>/proposal.md` 提取：
-
-| 字段 | 用途 |
-|------|------|
-| frontmatter `mode` | `full` → 倾向 `apply-<change>-<cap>`；`simple` → 倾向 `apply-<change>` |
-| §3.1 / §3.2 能力列表 | 本 change 下全部 capability 名 |
-| §4.2 依赖关系图 | 能力间先后 / 上下游 |
-| §5.3 前置依赖 checkbox | 未满足则当前 cap 不宜并行 |
-
-**Step B — 读当前 capability 的 spec 依赖（§2 正式加载前仅此文件）**
-
-读取**当前** capability 的 `spec.md`（路径按 mode）：
-
-- **full**：`changes/<change>/specs/<capability>/spec.md` 或 `openspec/changes/.../specs/<capability>/spec.md`（以项目实际为准）
-- **simple**：`changes/<change>/spec.md`
-
-只重点读 spec 中：**能力边界 / 涉及模块 / §4 内部与外部依赖**（是否写明依赖其它 capability、共享表、必须先发布的接口）。
-
-**Step C — 跨 capability 轻量交叉（隔离例外，仅本节）**
-
-对 §3 中**其它** capability，**只**读取其 `spec.md` 的：
-
-- 标题与能力简述
-- **§4 依赖**（是否依赖 `<当前 capability>` 或其它 cap）
-- **涉及模块 / 数据表 / 公共配置**（若有）
-
-⛔ 禁止为校验而加载其它 cap 的 `design.md`、`tasks.md`（完整实施上下文仍遵守 §2 隔离红线）。
-
-**Step D — 判定矩阵（输出给用户）**
-
-| 校验项 | 不通过时的处理 |
-|--------|----------------|
-| proposal §4.2 / §5.3 写明当前 cap **依赖** 未完成的其它 cap | **串行**：先 finish 上游，再 apply 当前；不并行拆分支 |
-| 其它 cap 的 spec 写明 **依赖当前 cap** 且当前 cap 未 finish | 当前可并行实施，但提醒下游须等本次 finish |
-| 多 cap spec 出现**相同模块路径 / 同表 / 同配置文件** | **不并行** worktree；串行或合并为一个 apply 范围 |
-| 当前 cap spec §4 要求接口/表已由其它 cap 提供 | 若其它 cap 未 merge 到集成分支 → **不建** worktree，先完成上游 |
-| `git branch --list 'kld-sdd/<change>/*'` 已存在同名分支 | 复用既有 worktree/分支，或询问用户是否清理后重建 |
-| 沙箱 / 环境无法 `worktree add` | 不建 worktree；集成分支上直接开发 |
-
-**Step E — 分支与目录命名（校验通过后）**
-
-| mode | worktree 目录（建议） | apply 分支（建议） |
-|------|----------------------|-------------------|
-| full + 可隔离 | `.worktrees/apply-<change>-<capability>` | `kld-sdd/<change>/<capability>` |
-| simple 或 change 内单实现体 | `.worktrees/apply-<change>` | `kld-sdd/<change>/<capability>`（cap 可与 change 同名） |
-| 校验不通过但仍需隔离 | `.worktrees/apply-<change>-<capability>` 或单 worktree | 仍用 `kld-sdd/<change>/<capability>`，但**不得**与其它 cap 并行 |
-
-**报告模板**（创建 worktree 前必须输出）：
-
-```
-📋 Apply 隔离校验 — <change>/<capability>
-- mode: full | simple
-- 本 change 能力域: [cap-a, cap-b, …]
-- 与当前 cap 冲突/依赖: [无 | cap-a 必须先合入 | 与 cap-b 共享模块 X]
-- 并行建议: [可独立 worktree | 串行等待 cap-a | 不建 worktree，原地 apply]
-- 分支（建议）: kld-sdd/<change>/<capability>
-- 集成分支（将 record-base）: <当前 git 分支>
-```
-
-#### 多 Capability 并行时的合并顺序（本地）
-
-1. 各 capability 在各自 worktree 内完成 + `§6.1 finish` 前，先根据 `proposal.md` 排出 **capability 依赖 DAG**。
-2. **按 DAG 顺序**依次 `finish` merge 到**同一** `integration_base`（先 A 合入，再 B；B 的 worktree 若基于旧尖端，merge 前应在 B 的 worktree 内 `merge/rebase integration_base` 或由用户选择重建 worktree）。
-3. 有依赖的 cap **不要**与上游 cap 同时 finish；无依赖的可并行实施，但 **merge 仍建议逐个** 以降低冲突。
-
-向用户简要说明判断结果：
-> "📌 并行建议：cap-A、cap-C 可并行 worktree；cap-B 依赖 A，待 A finish 后再 apply。"
-
-#### 分支 / Worktree 创建时机（勿与子代理混淆）
-
-| 时机 | 做什么 | 谁执行 |
-|------|--------|--------|
-| **§1.5 Step 0.25～1（仅一次）** | 记录集成分支 → 创建 worktree + 新建 `kld-sdd/<change>/<capability>` | **主会话** |
-| §2～§4 | 读文档、解析 DAG | 主会话 |
-| **§5 子代理** | 在**已有** worktree 内实现任务 | **子代理**（不建 worktree、不建分支） |
-| **§6.1** | merge 回集成分支 → remove worktree → 删 apply 分支 | **主会话** + `apply-worktree-finish.cjs` |
-
-- 集成分支 = Apply **开始时**主仓库 `git branch --show-current`（例：用户在 `hotfix-1` 上开始，则 merge 回 `hotfix-1`）。
-- `git worktree add -b` 在主仓库处于集成分支时执行，apply 分支从该分支尖端分出。
-- **子代理禁止** `EnterWorktree` / `git worktree add` / `checkout -b`；同层并行共享**同一** worktree 与 apply 分支。
-
-**设置流程**（详见 `./worktree-setup.md`）：
-
-**Step 0: 检测当前状态**
-- 若已是 Git Worktree → 跳过创建（集成分支应已在 state 文件中）
-- 若非 Git 项目（`vcs_mode=no-git`）→ 跳过
-
-**Step 0.1: 分支/隔离校验** — 见上文「Step 0.1 【必做】」，**通过后再执行** 0.25 / 0.5 / Step 1
-
-**Step 0.25: 记录集成分支（Git 项目必做，创建 worktree 之前）**
-
-在主仓库根目录、**尚未** `cd` 进 `.worktrees/` 时执行：
-
-```bash
-node skywalk-sdd/apply-worktree-finish.cjs --record-base \
-  --change=<变更名称> \
-  --capability=<capability-name>
-```
-
-- 将当前具名分支写入 `skywalk-sdd/state/apply-<change>-<capability>.json` 的 `integration_base`
-- 若为 detached HEAD，先 `git checkout` 到具名分支再记录
-- simple 模式可省略 `--capability`（默认与 change 相同）
-
-**Step 0.5: 主仓库冲突预检（Git 项目必做）**
-- 在主仓库根目录执行 `git status`，确认**无**与本次 Apply 将修改路径冲突的**未跟踪**实现文件（如 `src/`、`package.json` 等）
-- 若存在，先移走、提交或删除；否则收尾 `merge` 会报 `untracked working tree files would be overwritten`
-- 收尾脚本默认启用 `--check-untracked` 预检并给出明确报错
-
-**Step 1: 创建隔离工作区**
-
-> 确认主仓库仍检出在 **Step 0.25 记录的集成分支**（或与其一致的尖端），再创建 worktree。
-
-- **首选**：使用 `EnterWorktree` 工具（Claude Code 原生）
-  ```
-  EnterWorktree(name="apply-<change-name>-<capability-name>")
-  ```
-- **回退**：仅当原生工具不可用时，使用 `git worktree add`
-  - **full 模式**目录：`.worktrees/apply-<change-name>-<capability-name>`
-  - **simple 模式**目录：`.worktrees/apply-<change-name>`（无 capability 后缀）
-  - **分支命名**：仅当 Step 0.1 校验通过后，使用报告中的 `kld-sdd/<change-name>/<capability-name>`（勿对强依赖 cap 强行并行拆分支）
-  ```bash
-  git worktree add .worktrees/apply-<change-name>-<capability-name> \
-    -b kld-sdd/<change-name>/<capability-name>
-  ```
-
-**Step 2: 项目设置**
-- 自动检测并安装依赖（`npm install` / `pip install` 等）
-
-**Step 3: 验证基线**
-- 运行编译/测试，确保工作区干净
-
-**报告**：
-> "✅ Worktree 就绪：`<path>`
-> 集成分支：`<integration_base>`（收尾将 merge 回此分支）
-> 基线测试通过（N 个测试，0 失败）
-> 准备实施 `<change-name>/<capability-name>`"
+> **完整策略**（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. 渐进式上下文加载
 
@@ -373,100 +181,37 @@ node skywalk-sdd/apply-worktree-finish.cjs --record-base \
 4. 若前置任务已完成 → 允许执行
 ```
 
-**执行每个任务**：
-
-a. **DAG 依赖检查 & 层级收集**
-   - 解析当前层级：收集所有依赖已满足的待执行任务
-   - 若依赖未满足，暂停并提示用户先完成前置任务
-   - 同一层级多个独立任务 → 可并行派发子代理
-
-b. **显示当前层级任务**
-   > "📍 **层级 [X]**：准备派发 [K] 个子代理并行处理 [M] 个任务
-   > - [TASK-01]: <任务描述> - 依赖 ✅ 已满足
-   > - [TASK-02]: <任务描述> - 依赖 ✅ 已满足
-   > ..."
-
-c. **🤖 派发子代理实现代码**
-
-      > **使用 Agent 工具并行派发同层任务，每个子代理负责一个任务，上下文隔离、专注高效。**
-      > **⛔ 子代理阶段不创建 worktree/分支**——隔离环境已在 §1.5 就绪；子代理仅在 worktree 目录内实现 TASK。
-
-      **派发准备（每个子代理）：**
-      1. 从 tasks.md 中提取该任务的完整描述
-      2. 从 design.md 中提取该任务相关的设计约定（类签名、数据模型、接口定义、算法逻辑）
-      3. 从 overview.md 中提取相关全局规范（命名约定、目录结构、错误处理模式）
-      4. 组合以上上下文 + `./implementer-prompt.md` 模板 → 子代理 prompt
-
-      **同层并行派发**：
-      - 同一 DAG 层级、无相互依赖的任务 → **一次性并行派发多个子代理**
-      - 不同 DAG 层级 → **等待当前层全部完成后，再派发下一层**
-
-      **派发示例**：
-      ```
-      同一层级 3 个独立任务，一次性并行派发：
-
-      Agent("实现 TASK-01: 创建用户数据模型", ...)
-      Agent("实现 TASK-02: 创建角色数据模型", ...)
-      Agent("实现 TASK-03: 创建权限数据模型", ...)
-      // 三个子代理同时运行，上下文隔离，互不干扰
-      ```
-
-      **等待所有子代理返回结果后，按状态处理**：
-      | 子代理状态 | 控制器处理方式 |
-      |-----------|---------------|
-      | DONE | 进入编译/测试门禁 |
-      | DONE_WITH_CONCERNS | 审查顾虑内容，判断是否需要在门禁前处理 |
-      | NEEDS_CONTEXT | 提供缺失上下文，重新派发 |
-      | BLOCKED | 补充上下文 / 换更强模型 / 拆分任务 / 升级给用户 |
-
-      > **⛔ 严禁**忽略子代理的升级请求！不改变参数就重复派发不会解决问题。
-
-d. **⛔ 编译检查门禁**
-   
-   > **⛔ 红线：每完成一个任务后，必须确保代码可以编译通过！**
-   
-   - 检测项目类型并执行编译命令
-   - 编译成功 → 继续下一步
-   - **编译失败 → 必须立即修复，禁止标记为已完成！**
-
-e. **⛔ 测试执行门禁**
-   
-   > **根据 proposal.md 的 `test-strategy` 字段决定测试门禁行为**
-   
-   | test-strategy | 门禁行为 |
-   |---------------|----------|
-   | `tdd` | **⛔ 强制执行**：运行相关测试，测试失败禁止继续，必须修复 |
-   | `impl-first` | **⚠️ 警告模式**：运行测试，失败时显示警告但允许继续 |
-   | `none` | **跳过**：不执行测试门禁 |
-
-f. **⛔ 立即更新任务状态**
-   - 修改 tasks.md：将 `- [ ]` 替换为 `- [x]`（包括拓扑图和任务详情中的复选框）
-   - 同时修改：`- **状态**: [ ] 未完成` → `- **状态**: [x] 已完成`
-   - **两种格式必须同步更新**，不可遗漏
-   - 验证修改成功
-   - 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
-   - 记录任务级 Telemetry：
-     ```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\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"
-     ```
-     **⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算。
-
-g. **继续下一个层级**
-   - 重新检查 DAG，找出所有依赖已满足的下一层级任务
-   - 若同层有多个可执行任务 → 并行派发子代理
-   - 若当前层级有未完成的任务 → 等待或重新派发
+**执行每个任务**（a-g 步骤）：
 
-### 5.1 【Telemetry 必做】记录 AI 产出快照
+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，找出依赖已满足的下一层级任务。
 
-当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+**【S2 逐任务红绿节奏】**：每个任务完成后，在编译检查（d）和测试门禁（e）之外，如果 `test-strategy` 为 `tdd`，要求：
+1. 先写/确认该任务相关的测试存在且 RED（失败原因与该任务目标直接相关）
+2. 实现代码使测试 GREEN
+3. 再进入下一个任务
 
-- `--status=ai_snapshot` 用于记录 AI 初始产出快照，P2 指标在无 final 事件时会使用此快照数据
-- 若用户进行了人工 review 并确认保留率，可补录 `--status=final` 事件（`review_status: "final"`），P2 指标将优先使用 final 数据
+这确保每个任务都有对应的测试保护，而非最后统一跑测试。
 
-Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：
-```bash
-node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"未自动创建 Git 仓库，未自动提交 commit；仅记录可用统计\"}}"
-```
+### 5f. 【S3 apply 结束前 checkbox 全量自检】
+
+在 apply 阶段结束前（所有任务完成后），执行全量自检：
+1. 遍历 tasks.md 所有任务行（`- [ ]`/`- [x]` 和 `**状态**: [ ]`/`[x]` 两种格式）
+2. 确认所有任务状态与实际完成情况一致
+3. 确认手动验证清单（如有）已勾选
+4. 确认文档更新（如有）已完成
+5. 若有不一致，提示用户确认后再进入收尾
+
+此自检确保 tasks.md 的 checkbox 与实际代码状态完全同步。
+
+### 5.1 【Telemetry 必做】记录 AI 产出快照
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。**完整命令模板与说明见 `./reference.md`「§5.1 记录 AI 产出快照」**。
 
 ### 6. 完成或暂停时显示状态
 
@@ -485,80 +230,44 @@ node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --proj
 
 ### 6.0 【条件必做】单元测试真实执行（`test-strategy` 非 `none`）
 
-当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时：
-
-1. **在结束 apply 或执行 §6.1 收尾之前**，必须在项目根或 worktree 内**真实运行**单元测试命令（`npm test` / `pytest` / `go test` 等）。
-2. 须留下可核验的 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`
-3. **Claude Code**：`sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验；无证据则**阻断**并提示补跑测试。
-
-| test-strategy | 行为 |
-|---------------|------|
-| `tdd` | 无测试证据不得结束 apply / 不得 finish worktree |
-| `impl-first` | 同上，实现后必须补跑并记录 |
-| `none` | 跳过本节与 test gate |
+当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时，在结束 apply 或执行 §6.1 收尾之前，必须真实运行单元测试并留 telemetry 证据。**详细执行要求与证据形式见 `./reference.md`「§6.0」+ `./checklist.md`「§6.0 单元测试真实执行自检」**。${HOOK_GATE_DESCRIPTION}
 
 ### 6.1 【条件必做】Worktree 收尾（仅当 §1.5 已创建 worktree）
 
-> **⛔ 本次 Apply 若创建了 worktree**：DAG 全部完成且 **§6.0 测试门禁（若适用）** 通过后，必须在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）。
+> **⛔ 本次 Apply 若创建了 worktree**：DAG 全部完成且 §6.0 测试门禁（若适用）通过后，必须在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）。
 > 若 §1.5 判定未建 worktree（串行、强依赖、沙箱回退），跳过本节。
 
-**前置条件**：
-- worktree 内 `git status` 干净（实现代码已全部 commit）
-- 主仓库无与 merge 冲突的未跟踪文件（见 §1.5 Step 0.5）
-- `test-strategy` 为 `tdd`/`impl-first` 时，§6.0 测试证据已存在
-
-**执行**（主仓库根目录）：
-```bash
-node skywalk-sdd/apply-worktree-finish.cjs \
-  --change=<变更名称> \
-  --capability=<capability-name>
-```
-
-- **默认 merge 目标**：§1.5 `--record-base` 写入的 `integration_base`（**不是**默认 master）
-- 仅当 state 缺失或需覆盖时传 `--target=<集成分支>`
-- **simple 模式**：`--capability` 可省略；目录为 `.worktrees/apply-<change>`
-- **full 模式**：目录为 `.worktrees/apply-<change>-<capability>`
-
-**脚本行为**：`checkout 集成分支` → `merge --no-ff` apply 分支 → `worktree remove` → 删临时目录 → `branch -d` apply 分支
+**前置条件、执行命令、脚本行为、常用 flags、回退方式见 `./reference.md`「§6.1 Worktree 收尾」+ `./checklist.md`「§6.1 Worktree 收尾前置条件自检」**。
 
-**常用 flags**：`--dry-run` 预演；`--skip-merge` 已手动 merge；`--keep-branch` 保留 apply 分支；`--no-check-untracked` 跳过未跟踪预检
+> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。
 
-**收尾 Telemetry（推荐）**：
-```bash
-node skywalk-sdd/log.cjs record --type=worktree_finish \
-  --command=apply --project=. --change=<变更名称> --capability=<capability-name> \
-  --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> \
-  --result=success --summary="merge+remove completed" \
-  --details-json='{"integration_base":"<branch>","merge_commit":"<sha>","worktree_removed":true}'
-```
+---
 
-**回退**（仅当脚本不可用时，详见 `./worktree-setup.md`）：
-- `EnterWorktree`：`ExitWorktree(action="remove", discard_changes=false)`
-- `git worktree add`：`git worktree remove` + `git branch -D`
+## Guardrails
 
-> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
+- **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，禁止加载同级其他 Capability 的文档。
+- **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截。
+- **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
+- **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry。${HOOK_GATE_DESCRIPTION}
+- **⛔ 必须实时更新任务状态**：每完成一个任务立即改 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]」。
+- **保持任务聚焦**：每次只处理一个任务。
+- **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问。
 
 ---
 
-## Guardrails
+## 渐进披露
 
-- **⛔ Check 门禁检查**：apply 阶段开始前，必须确认 check 阶段已完成。若 check 未完成，**强制拒绝** apply，引导用户先执行 `/opsx-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]」
-- **保持任务聚焦**：每次只处理一个任务
-- **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问
+- 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=快速参考）。