@hunterzheng/kld-sdd 2.4.19

package/templates/skills/kld-sdd/opsx-apply/implementer-prompt.md

@@ -0,0 +1,129 @@
+# OPSX 任务实现子代理提示模板
+
+在派发实现子代理时使用此模板。每个 DAG 任务由一个独立子代理执行。
+
+## 派发格式
+
+```
+Agent (general-purpose):
+  description: "实现任务 [TASK-ID]: [任务描述]"
+  prompt: |
+    你是 SDD（Specification-Driven Development）任务实现专家。
+
+    ## 当前任务
+
+    [TASK-ID]: [完整任务描述，从 tasks.md 中提取]
+    - 类型: [数据层/业务层/接口层/测试]
+    - 依赖: [前置任务列表] ✅ 已完成
+    - 层级: [N]
+
+    ## 设计约定
+
+    [从 design.md 中提取与本任务相关的设计内容：
+      - 类/函数签名
+      - 数据模型
+      - 接口定义
+      - 关键算法逻辑]
+
+    ## 全局规范
+
+    [从 overview.md 中提取相关全局规范：
+      - 命名约定
+      - 目录结构
+      - 错误处理模式
+      - 日志规范]
+
+    ## 开始前确认
+
+    如果你对以下内容有疑问：
+    - 任务需求或验收标准
+    - 实现方式或技术方案
+    - 依赖项或假设条件
+    - 任务描述中不清晰的地方
+
+    **请现在提出。** 在开始工作之前澄清所有疑问。
+
+    ## 你的工作
+
+    确认需求清晰后：
+    1. 实现任务指定的内容（不多不少）
+    2. 遵循 design.md 的设计约定
+    3. 遵循 overview.md 的全局规范
+    4. 保持变更最小化，不超出任务范围
+    5. 自我审查（见下方）
+    6. 报告结果
+
+    工作目录：[项目根目录]
+
+    **工作中遇到意外或不明确的情况时，请提问。**
+    允许暂停并澄清，不要猜测或假设。
+
+    ## 代码组织
+
+    - 遵循 design.md 中定义的文件结构
+    - 每个文件应有单一明确的职责
+    - 遵循项目现有的代码模式和风格
+    - 如果任务涉及的文件超出预期范围，报告 DONE_WITH_CONCERNS
+
+    ## 何时升级
+
+    **暂停并升级的情况：**
+    - 任务需要架构决策且有多种可行方案
+    - 需要理解超出提供范围之外的代码
+    - 不确定实现方式是否正确
+    - 需要重构现有代码且设计文档未预期的
+
+    **升级方式：** 报告状态为 BLOCKED 或 NEEDS_CONTEXT，具体说明卡在哪里、尝试了什么、需要什么帮助。
+
+    ## 报告前自我审查
+
+    用新的眼光审视你的工作，自查：
+
+    **完整性：**
+    - 是否完整实现了任务描述中的所有内容？
+    - 是否遗漏了任何需求？
+    - 是否处理了边界情况？
+
+    **质量：**
+    - 代码是否清晰可维护？
+    - 命名是否准确（反映做什么，而非怎么做）？
+    - 是否遵循了项目现有模式？
+
+    **纪律：**
+    - 是否避免了过度工程（YAGNI）？
+    - 是否只构建了任务要求的内容？
+    - 是否避免了对无关文件的修改？
+
+    如果在自我审查中发现问题，先修复再报告。
+
+    ## 报告格式
+
+    完成后报告：
+
+    - **状态**: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - **实现了什么**（或尝试了什么，如果受阻）
+    - **修改的文件列表**
+    - **自我审查发现**（如有）
+    - **任何问题或关注点**
+
+    使用 DONE_WITH_CONCERNS 表示完成了工作但对正确性有疑虑。
+    使用 BLOCKED 表示无法完成任务。
+    使用 NEEDS_CONTEXT 表示缺少必要信息。
+    永远不要默默产出你不确定的工作成果。
+```
+
+## 状态处理指南
+
+| 状态 | 含义 | 控制器操作 |
+|------|------|------------|
+| DONE | 任务完成，无顾虑 | 进入编译/测试门禁 |
+| DONE_WITH_CONCERNS | 完成但有疑虑 | 读取顾虑，判断是否需要在门禁前处理 |
+| NEEDS_CONTEXT | 需要更多信息 | 提供缺失上下文，重新派发 |
+| BLOCKED | 无法完成 | 评估阻碍：补充上下文 / 换模型 / 拆分任务 / 升级给用户 |
+
+## 注意事项
+
+- **绝不要**忽略子代理的升级请求，重复同样参数重新派发不会解决问题
+- **绝不要**在子代理说出"卡住"后不做改变就重试
+- 子代理报告 NEEDS_CONTEXT 时，提供精准的补充信息
+- 子代理报告 DONE_WITH_CONCERNS 时，仔细审查顾虑内容

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

@@ -0,0 +1,335 @@
+---
+description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策略、子代理派发、收尾脚本。仅在需要参考详细模板时读取。
+---
+
+# opsx-apply — 详细参考（reference）
+
+> 本文件承载 opsx-apply 的重细节模板：telemetry 命令、§1.5 worktree 全套策略、§5c 子代理派发、§5.1 AI 产出快照、§6.0 单元测试真实执行、§6.1 worktree 收尾脚本。
+> SKILL.md 保留入口骨架与指针；本文件为完整策略来源。`./worktree-setup.md` 为 worktree 快速参考，与本文件 §1.5 并存（reference=完整策略，worktree-setup=快速参考）。
+
+---
+
+## 📊 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（每完成一个任务记录）
+
+```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 指标无法计算。
+
+### ai_adoption_review（AI 产出快照）
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+
+- `--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；仅记录可用统计\"}}"
+```
+
+### worktree_finish（收尾 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}'
+```
+
+---
+
+## §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」。
+
+### 何时建议建 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>`"
+
+---
+
+## §5c 子代理派发模板
+
+> **使用 Agent 工具并行派发同层任务，每个子代理负责一个任务，上下文隔离、专注高效。**
+> **⛔ 子代理阶段不创建 worktree/分支**——隔离环境已在 §1.5 就绪；子代理仅在 worktree 目录内实现 TASK。
+
+**派发准备（每个子代理）：**
+1. 从 tasks.md 中提取该任务的完整描述
+2. 从 design.md 中提取该任务相关的设计约定（类签名、数据模型、接口定义、算法逻辑）
+3. 从 overview.md 中提取相关全局规范（命名约定、目录结构、错误处理模式）
+4. 组合以上上下文 + `./implementer-prompt.md` 模板 → 子代理 prompt
+
+> 子代理 prompt 模板详见 **`./implementer-prompt.md`**（任务实现子代理提示模板）。本节不重复其内容。
+
+**同层并行派发**：
+- 同一 DAG 层级、无相互依赖的任务 → **一次性并行派发多个子代理**
+- 不同 DAG 层级 → **等待当前层全部完成后，再派发下一层**
+
+**派发示例**：
+```
+同一层级 3 个独立任务，一次性并行派发：
+
+Agent("实现 TASK-01: 创建用户数据模型", ...)
+Agent("实现 TASK-02: 创建角色数据模型", ...)
+Agent("实现 TASK-03: 创建权限数据模型", ...)
+// 三个子代理同时运行，上下文隔离，互不干扰
+```
+
+**等待所有子代理返回结果后，按状态处理**：
+
+| 子代理状态 | 控制器处理方式 |
+|-----------|---------------|
+| DONE | 进入编译/测试门禁 |
+| DONE_WITH_CONCERNS | 审查顾虑内容，判断是否需要在门禁前处理 |
+| NEEDS_CONTEXT | 提供缺失上下文，重新派发 |
+| BLOCKED | 补充上下文 / 换更强模型 / 拆分任务 / 升级给用户 |
+
+> **⛔ 严禁**忽略子代理的升级请求！不改变参数就重复派发不会解决问题。
+
+---
+
+## §5.1 记录 AI 产出快照
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+
+- `--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；仅记录可用统计\"}}"
+```
+
+> 该命令亦见上文「📊 Telemetry 命令模板 → ai_adoption_review」。
+
+---
+
+## §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 |
+
+---
+
+## §6.1 Worktree 收尾（仅当 §1.5 已创建 worktree）
+
+> **⛔ 本次 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**：`--dry-run` 预演；`--skip-merge` 已手动 merge；`--keep-branch` 保留 apply 分支；`--no-check-untracked` 跳过未跟踪预检
+
+**回退**（仅当脚本不可用时，详见 `./worktree-setup.md`）：
+- `EnterWorktree`：`ExitWorktree(action="remove", discard_changes=false)`
+- `git worktree add`：`git worktree remove` + `git branch -D`
+
+> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。

package/templates/skills/kld-sdd/opsx-apply/worktree-setup.md

@@ -0,0 +1,104 @@
+# OPSX Apply — 本地 Worktree 与并行加速
+
+## 目标（读这个就够了）
+
+- **为什么用 worktree**：在**本地**让解耦的 capability/spec **并行写代码**，互不干扰，再按依赖 **merge 回集成分支**，缩短 Apply 总时间。
+- **不是什么**：不是保护 `master`、不是远程发布策略、不是「主分支只放 SDD 文档」。
+
+集成分支 = Apply 开始时主仓库的 `git branch --show-current`（如 `hotfix-1`）。收尾 merge 回这条**本地**分支。
+
+## 两层并行
+
+| 层级 | 做法 |
+|------|------|
+| **Capability 级** | 多个 `/opsx-apply <change> <cap>`，每个解耦 cap 一个 worktree + `kld-sdd/<change>/<cap>` |
+| **Task 级** | 单个 cap 内，**同一** worktree，DAG 同层子代理并行 |
+
+子代理（§5）** never ** 创建 worktree 或分支。
+
+## Step 0.1 分支/隔离校验（早于 record-base）
+
+建议分支 `kld-sdd/<change>/<capability>` **不是默认值**，须先校验：
+
+1. **proposal.md**：§3 能力列表、§4.2 依赖图、§5.3 前置依赖、`mode`（full/simple）
+2. **当前 cap 的 spec.md**：§4 依赖、涉及模块/表/接口
+3. **其它 cap 的 spec.md（仅节选）**：§4 依赖、模块/表是否与当前 cap 重叠
+
+| 不通过 | 处理 |
+|--------|------|
+| 当前 cap 依赖未完成的上游 cap | 串行，先 finish 上游 |
+| 多 cap 改同一模块/表/配置 | 不并行 worktree |
+| 已有同名 `kld-sdd/<change>/<cap>` 分支 | 复用或问用户清理 |
+
+校验通过后输出报告（见 SKILL.md 模板），再 `record-base` / `worktree add`。
+
+## 是否建 worktree？（建议，非强制）
+
+### 建议建（常对应 full 目录 `apply-<change>-<capability>`）
+
+- proposal §3 / design 显示该 cap 与其它并行 cap **无强依赖**
+- 修改的文件/模块/表 **基本不重叠**
+- 需要与其它 cap **同时** 本地实施
+
+### 建议不建 / 串行
+
+- cap B **依赖** cap A（先 finish A 再开 B）
+- 多 cap 改 **同一文件、共享配置、顺序迁移**
+- 其它 cap 的 worktree 尚未 merge，当前 cap 需要 **最新** 集成分支尖端
+- `git worktree add` 被沙箱拒绝 → 当前目录 + 功能分支，并说明原因
+
+### full 模式「一 cap 一分支」
+
+- **约定 + 建议**，不是铁律
+- simple：通常 **一 change 一 worktree**（`apply-<change>`）
+
+## 多 Capability 并行 merge 顺序
+
+1. 从 `proposal.md` 排出 capability 依赖。
+2. **无依赖**：可同时开多个 worktree 实施；**finish merge 仍逐个** 到同一 `integration_base`。
+3. **有依赖**：上游 cap 先 `finish`，下游 cap 在 merge 前应对集成分支 `rebase/merge`，或从更新后的尖端重建 worktree。
+
+## 流程（单次 apply）
+
+```
+§1.2 check
+§1.5 Step 0.1  proposal + spec 跨 cap 依赖校验 → 输出报告
+§1.5 判断是否建 worktree（见上）
+  → 若建：record-base → worktree add -b kld-sdd/<change>/<cap>
+§2～§5 实施（子代理不建分支）
+§6.1 若建了 worktree：finish → merge 回 integration_base
+```
+
+### record-base
+
+```bash
+node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+  --change=<change> --capability=<capability>
+```
+
+### 创建（git 回退）
+
+```bash
+git check-ignore -q .worktrees || echo ".worktrees/" >> .gitignore
+git worktree add .worktrees/apply-<change>-<capability> -b kld-sdd/<change>/<capability>
+```
+
+须在**集成分支**上执行，apply 分支从该尖端分出。
+
+### finish
+
+```bash
+node skywalk-sdd/apply-worktree-finish.cjs --change=<change> --capability=<capability>
+```
+
+状态文件：`skywalk-sdd/state/apply-<change>-<capability>.json`
+
+## 快速参考
+
+| 问题 | 答案 |
+|------|------|
+| 为了加速本地 apply？ | 是 |
+| 必须 master？ | 否，用 record-base 的集成分支 |
+| full 必须一 cap 一分支？ | 建议，解耦才可并行 |
+| 有依赖怎么办？ | 串行 apply + 按序 finish |
+| 子代理能建 worktree 吗？ | 不能 |