kld-sdd 2.4.16 → 2.4.18

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

@@ -129,42 +129,187 @@ openspec list --json
    > **必须先执行质量门禁检查，再开始代码实施：**
    >
    > ```
-   > /opsx:check <change-name>
+   > /opsx-check <change-name>
    > ```
    >
    > **原因**：check 阶段验证文档完整性、一致性、可执行性，跳过 check 直接 apply 可能导致需求误解或设计缺陷。
    >
-   > **操作顺序**：`/opsx:check → /opsx:apply`
+   > **操作顺序**：`/opsx-check → /opsx-apply`
    >
    > 是否要现在执行 check？"
 
-   - 若用户确认执行 check → 引导执行 `/opsx:check`
+   - 若用户确认执行 check → 引导执行 `/opsx-check`
    - 若用户坚持跳过 → **强制拒绝**，不得跳过 check 直接 apply
 
 4. **若 telemetry 数据缺失**（如新项目无历史数据）：
-   > "⚠️ 未找到 check 阶段记录。如果这是首次执行，请先运行 `/opsx:check <change-name>` 完成质量门禁。
+   > "⚠️ 未找到 check 阶段记录。如果这是首次执行，请先运行 `/opsx-check <change-name>` 完成质量门禁。
    >
    > 是否要现在执行 check？"
 
-> **🔗 双重保障**：此技能自检与 `sdd-apply-gate.cjs` Hook 形成双重门禁。即使 Hook 因环境问题未触发，技能自检仍会拦截未 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 时校验是否**真实执行**过测试
 
-### 1.5 【隔离工作区】设置 Git Worktree
+### 1.5 【本地并行】Worktree 与工作区（建议性策略）
 
-> **🤖 使用 Git Worktree 创建隔离工作区，保护主分支不受变更影响。**
-> 与子代理并行派发配合使用——同一 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 → 跳过创建
+- 若已是 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>
@@ -178,6 +323,7 @@ openspec list --json
 
 **报告**：
 > "✅ Worktree 就绪：`<path>`
+> 集成分支：`<integration_base>`（收尾将 merge 回此分支）
 > 基线测试通过（N 个测试，0 失败）
 > 准备实施 `<change-name>/<capability-name>`"
 
@@ -243,6 +389,7 @@ b. **显示当前层级任务**
 c. **🤖 派发子代理实现代码**
 
       > **使用 Agent 工具并行派发同层任务，每个子代理负责一个任务，上下文隔离、专注高效。**
+      > **⛔ 子代理阶段不创建 worktree/分支**——隔离环境已在 §1.5 就绪；子代理仅在 worktree 目录内实现 TASK。
 
       **派发准备（每个子代理）：**
       1. 从 tasks.md 中提取该任务的完整描述
@@ -333,24 +480,85 @@ node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --proj
 > 建议执行 `/kld-review --local` 对本次变更的代码进行评审。
 > 该技能可在公司内部 SkillHub 下载安装。
 >
-> **🧹 Worktree 清理**：
-> 全部完成后，清理隔离工作区：
-> - 使用 `EnterWorktree` 时：`ExitWorktree(action="remove", discard_changes=false)`
-> - 使用 `git worktree add` 时：`git worktree remove .worktrees/<dir> && git branch -D <branch>`
-> - 需保留变更时：`ExitWorktree(action="keep")`
+> **🧹 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`** 时：
+
+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` 跳过未跟踪预检
+
+**收尾 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`
+
+> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。
 
 ---
 
 ## Guardrails
 
-- **⛔ Check 门禁检查**：apply 阶段开始前，必须确认 check 阶段已完成。若 check 未完成，**强制拒绝** apply，引导用户先执行 `/opsx:check`。与 `sdd-apply-gate.cjs` Hook 形成双重保障。
+- **⛔ Check 门禁检查**：apply 阶段开始前，必须确认 check 阶段已完成。若 check 未完成，**强制拒绝** apply，引导用户先执行 `/opsx-check`。与 `sdd-apply-gate.cjs` Hook 形成双重保障。
 - **⛔ 渐进式加载**：只加载当前 Capability 的四文档链
 - **⛔ 隔离红线**：绝对禁止加载同级其他 Capability 的文档
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - **⛔ 编译检查门禁**：每完成一个任务后，**必须运行编译检查**，编译失败禁止标记已完成
-- **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=警告, none=跳过）
+- **⛔ 测试执行门禁**：根据 `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]」
 - **保持任务聚焦**：每次只处理一个任务
 - **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问

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

@@ -1,141 +1,104 @@
-# OPSX Apply 工作区隔离指南
+# OPSX Apply — 本地 Worktree 与并行加速
 
-在 Apply 阶段使用 Git Worktree 隔离工作区，保护主分支不受代码变更影响。
+## 目标（读这个就够了）
 
-## 核心原则
+- **为什么用 worktree**：在**本地**让解耦的 capability/spec **并行写代码**，互不干扰，再按依赖 **merge 回集成分支**，缩短 Apply 总时间。
+- **不是什么**：不是保护 `master`、不是远程发布策略、不是「主分支只放 SDD 文档」。
 
-- **优先使用平台原生工具**：Claude Code 的 `EnterWorktree` / `ExitWorktree`
-- **回退到 git 命令**：仅当原生工具不可用时
-- **所有子代理共享同一 Worktree**：DAG 分析确保同层任务不冲突
-- **非 Git 项目跳过**：`vcs_mode=no-git` 时无需隔离
+集成分支 = Apply 开始时主仓库的 `git branch --show-current`（如 `hotfix-1`）。收尾 merge 回这条**本地**分支。
 
-## 设置流程
+## 两层并行
 
-### Step 0: 检测当前状态
-
-在执行任何操作前，先检查是否已在隔离工作区中：
-
-```bash
-git rev-parse --is-inside-work-tree 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null
-```
-
-**已在 Worktree 中**（`GIT_DIR != GIT_COMMON_DIR` 且非 submodule）：
-→ 跳过创建，直接进入上下文加载阶段。
-> "📍 已在隔离工作区 `<path>` 中，跳过 Worktree 创建。"
-
-**在主仓库中**（`GIT_DIR == GIT_COMMON_DIR` 或非 Git 项目）：
-→ 继续 Step 1（非 Git 项目跳过）。
-
-### Step 1: 创建隔离工作区
+| 层级 | 做法 |
+|------|------|
+| **Capability 级** | 多个 `/opsx-apply <change> <cap>`，每个解耦 cap 一个 worktree + `kld-sdd/<change>/<cap>` |
+| **Task 级** | 单个 cap 内，**同一** worktree，DAG 同层子代理并行 |
 
-#### 1a. 平台原生工具（首选）
+子代理（§5）** never ** 创建 worktree 或分支。
 
-**Claude Code 环境**：直接调用 `EnterWorktree` 工具。
+## Step 0.1 分支/隔离校验（早于 record-base）
 
-```
-EnterWorktree(name="apply-<change-name>-<capability-name>")
-```
+建议分支 `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 重叠
 
-> **注意**：确认变更名称和 Capability 后，在开始上下文加载前创建 Worktree。
+| 不通过 | 处理 |
+|--------|------|
+| 当前 cap 依赖未完成的上游 cap | 串行，先 finish 上游 |
+| 多 cap 改同一模块/表/配置 | 不并行 worktree |
+| 已有同名 `kld-sdd/<change>/<cap>` 分支 | 复用或问用户清理 |
 
-#### 1b. Git Worktree 回退（仅当无原生工具时）
+校验通过后输出报告（见 SKILL.md 模板），再 `record-base` / `worktree add`。
 
-**仅当 Step 1a 不可用时使用**，手动创建 Worktree：
+## 是否建 worktree？（建议，非强制）
 
-```bash
-# 1. 确定 Worktree 目录
-WORKTREE_DIR=".worktrees/apply-<change-name>-<capability-name>"
+### 建议建（常对应 full 目录 `apply-<change>-<capability>`）
 
-# 2. 验证 .worktrees 已被 gitignore
-git check-ignore -q .worktrees || echo ".worktrees/" >> .gitignore
+- proposal §3 / design 显示该 cap 与其它并行 cap **无强依赖**
+- 修改的文件/模块/表 **基本不重叠**
+- 需要与其它 cap **同时** 本地实施
 
-# 3. 创建 Worktree
-BRANCH="kld-sdd/<change-name>/<capability-name>"
-git worktree add "$WORKTREE_DIR" -b "$BRANCH"
-cd "$WORKTREE_DIR"
-```
+### 建议不建 / 串行
 
-**权限错误回退**：如果 `git worktree add` 因沙箱限制失败，告知用户后在当前目录继续工作。
+- cap B **依赖** cap A（先 finish A 再开 B）
+- 多 cap 改 **同一文件、共享配置、顺序迁移**
+- 其它 cap 的 worktree 尚未 merge，当前 cap 需要 **最新** 集成分支尖端
+- `git worktree add` 被沙箱拒绝 → 当前目录 + 功能分支，并说明原因
 
-### Step 2: 项目初始设置
+### full 模式「一 cap 一分支」
 
-在 Worktree 中自动检测并运行项目设置：
+- **约定 + 建议**，不是铁律
+- simple：通常 **一 change 一 worktree**（`apply-<change>`）
 
-```bash
-# Node.js
-[ -f package.json ] && npm install
+## 多 Capability 并行 merge 顺序
 
-# Rust
-[ -f Cargo.toml ] && cargo build
+1. 从 `proposal.md` 排出 capability 依赖。
+2. **无依赖**：可同时开多个 worktree 实施；**finish merge 仍逐个** 到同一 `integration_base`。
+3. **有依赖**：上游 cap 先 `finish`，下游 cap 在 merge 前应对集成分支 `rebase/merge`，或从更新后的尖端重建 worktree。
 
-# Python
-[ -f requirements.txt ] && pip install -r requirements.txt
-[ -f pyproject.toml ] && poetry install
+## 流程（单次 apply）
 
-# Go
-[ -f go.mod ] && go mod download
+```
+§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
 ```
 
-### Step 3: 验证干净基线
-
-运行测试确保 Worktree 从干净状态开始：
+### record-base
 
 ```bash
-# 使用项目对应的测试命令
-npm test / cargo test / pytest / go test ./...
+node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+  --change=<change> --capability=<capability>
 ```
 
-**测试失败**：报告失败，询问用户是否继续。
-**测试通过**：报告就绪。
+### 创建（git 回退）
 
-```
-✅ Worktree 就绪：<full-path>
-   基线测试通过（N 个测试，0 失败）
-   准备实施 <change-name>/<capability-name>
+```bash
+git check-ignore -q .worktrees || echo ".worktrees/" >> .gitignore
+git worktree add .worktrees/apply-<change>-<capability> -b kld-sdd/<change>/<capability>
 ```
 
-## 清理流程
+须在**集成分支**上执行，apply 分支从该尖端分出。
 
-### 应用完成后
+### finish
 
-**使用原生工具时**：
-```
-ExitWorktree(action="remove", discard_changes=false)
-```
-
-**使用 git 命令时**：
 ```bash
-# 返回主仓库
-cd "$MAIN_REPO"
-
-# 移除 Worktree
-git worktree remove "$WORKTREE_DIR"
-
-# 删除分支
-git branch -D "kld-sdd/<change-name>/<capability-name>"
+node skywalk-sdd/apply-worktree-finish.cjs --change=<change> --capability=<capability>
 ```
 
-**保留选项**：若用户需要保留变更待审查，使用 `ExitWorktree(action="keep")`。
-
-## 与子代理的配合
-
-- **所有子代理共享同一 Worktree**
-- DAG 分析确保同层任务不修改相同文件
-- 子代理无需关心 Worktree 存在（透明隔离）
-- 控制器（主会话）负责 Worktree 的创建和清理
+状态文件：`skywalk-sdd/state/apply-<change>-<capability>.json`
 
 ## 快速参考
 
-| 场景 | 操作 |
+| 问题 | 答案 |
 |------|------|
-| 已在 Worktree 中 | 跳过创建 |
-| 非 Git 项目 | 跳过（`vcs_mode=no-git`） |
-| Claude Code 环境 | 使用 `EnterWorktree` |
-| 无原生工具 | `git worktree add` 回退 |
-| `.worktrees/` 存在 | 直接使用 |
-| `.worktrees/` 不存在 | 创建并验证 gitignore |
-| 权限错误 | 在当前目录继续工作 |
-| 基线测试失败 | 报告 + 询问用户 |
-| 完成 | `ExitWorktree(action="remove")` |
+| 为了加速本地 apply？ | 是 |
+| 必须 master？ | 否，用 record-base 的集成分支 |
+| full 必须一 cap 一分支？ | 建议，解耦才可并行 |
+| 有依赖怎么办？ | 串行 apply + 按序 finish |
+| 子代理能建 worktree 吗？ | 不能 |

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

@@ -65,6 +65,16 @@ node skywalk-sdd/log.cjs start --command=archive --project=. --change=<变更名
 
 记录为 `<归档原因>`，它会进入 `archive-manifest.json`、archive telemetry 和最终报告。
 
+### 2.5 确认无残留 Apply Worktree（Git 项目）
+
+若项目使用 Apply worktree 隔离，归档前确认：
+
+```bash
+git worktree list
+```
+
+应仅剩主工作区；或 telemetry 中存在 `worktree_finish` + `result=success` 事件。若仍有 `.worktrees/apply-*`，先执行 `node skywalk-sdd/apply-worktree-finish.cjs` 或手工清理。
+
 ### 3. 运行 telemetry doctor
 
 ```bash

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

@@ -23,7 +23,7 @@ allowed-tools:
 > - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
 >
 > 即使检查发现代码相关问题，也只记录在检查报告中，**不自动修复代码**。
-> 代码修复将在 `/opsx:apply` 阶段进行。
+> 代码修复将在 `/opsx-apply` 阶段进行。
 
 
 > **🖥️ 跨平台执行规则**
@@ -58,7 +58,7 @@ allowed-tools:
 openspec list
 ```
 
-若变更不存在，提示用户先运行 `/opsx:propose <name>` 创建变更。
+若变更不存在，提示用户先运行 `/opsx-propose <name>` 创建变更。
 
 ### 2. 读取完整文档链
 
@@ -168,13 +168,13 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 
 **全部通过**：
 > "✅ 质量检查通过！建议下一步：
-> - A. 运行 `/opsx:apply` 开始实施
+> - A. 运行 `/opsx-apply` 开始实施
 > - B. 再次确认某个文档细节"
 
 **有问题**：
 > "❌ 发现 [N] 个问题需要修复：
-> - 问题 1：[描述] → 建议运行 `/opsx:spec` 修复
-> - 问题 2：[描述] → 建议运行 `/opsx:design` 修复
+> - 问题 1：[描述] → 建议运行 `/opsx-spec` 修复
+> - 问题 2：[描述] → 建议运行 `/opsx-design` 修复
 >
 > 请选择：
 > - A. 逐个修复（引导到对应命令）

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

@@ -23,7 +23,7 @@ allowed-tools:
 > - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
 > - ⛔ **单阶段原则**：完成 design.md 后**必须立即停止**，等待用户主动触发下一阶段
 >
-> 代码实现将在 `/opsx:apply` 阶段进行。
+> 代码实现将在 `/opsx-apply` 阶段进行。
 > **完成本阶段后，绝对禁止自动继续执行 task 等后续阶段。**
 
 > **⚠️ 渐进式上下文加载原则**
@@ -172,7 +172,7 @@ openspec list
 
 最终输出：
 - 文档路径
-- 下一步提示："运行 `/opsx:task <name> <capability>` 创建任务拆解文档"
+- 下一步提示："运行 `/opsx-task <name> <capability>` 创建任务拆解文档"
 
 ---
 
@@ -185,4 +185,4 @@ openspec list
 - 必须 100% 覆盖 spec.md 定义的需求项
 - 代码锚点必须具体到类/方法级别
 - **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
-- **⛔ 单阶段原则：完成 design.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:task`，**绝对禁止自动执行 task 等后续阶段**。每个阶段必须由用户主动触发。
+- **⛔ 单阶段原则：完成 design.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx-task`，**绝对禁止自动执行 task 等后续阶段**。每个阶段必须由用户主动触发。

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

@@ -47,7 +47,7 @@ openspec list
 ```
 
 若没有任何变更，提示：
-> "当前项目还没有任何变更。运行 `/opsx:propose <变更描述>` 开始第一个变更。"
+> "当前项目还没有任何变更。运行 `/opsx-propose <变更描述>` 开始第一个变更。"
 
 ### 2. 检查每个变更的 SDD 文档完整性
 
@@ -68,18 +68,18 @@ openspec status --change "<name>" --json
 >
 > | 变更名称 | P | S | D | T | openspec状态 | 建议下一步 |
 > |---------|---|---|---|---|------------|---------|
-> | add-user-auth | ✅ | ✅ | ✅ | ❌ | PENDING | `/opsx:task add-user-auth` |
-> | payment-refund | ✅ | ❌ | ❌ | ❌ | PENDING | `/opsx:spec payment-refund` |
-> | points-exchange | ✅ | ✅ | ✅ | ✅ | IMPLEMENTING | `/opsx:check points-exchange` |"
+> | add-user-auth | ✅ | ✅ | ✅ | ❌ | PENDING | `/opsx-task add-user-auth` |
+> | payment-refund | ✅ | ❌ | ❌ | ❌ | PENDING | `/opsx-spec payment-refund` |
+> | points-exchange | ✅ | ✅ | ✅ | ✅ | IMPLEMENTING | `/opsx-check points-exchange` |"
 
 ### 4. 【交互引导】选择操作
 
 使用 **AskUserQuestion** 让用户选择：
 > "请选择操作：
 > - A. 查看变更详情：输入变更名称
-> - B. 创建新变更：运行 `/opsx:propose`
-> - C. 执行质量检查：运行 `/opsx:check <name>`
-> - D. 申请实施：运行 `/opsx:apply <name>`
+> - B. 创建新变更：运行 `/opsx-propose`
+> - C. 执行质量检查：运行 `/opsx-check <name>`
+> - D. 申请实施：运行 `/opsx-apply <name>`
 > - E. 退出浏览"
 
 ### 5. 若用户选择查看详情