kld-sdd 2.4.17 → 2.4.19

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