@chenguangyao/devflow-kit 0.1.43

package/skills/apply/references/worktree-swarm.md

@@ -0,0 +1,292 @@
+# apply / worktree-swarm
+
+Git worktree 并行执行模型、合并顺序、冲突处置。
+
+---
+
+## 为什么用 worktree
+
+传统 `git checkout` 切分支有痛点:
+
+- build 缓存被打乱(切一次重 build)
+- IDE 索引失效
+- 测试 watcher 中断
+- 多 task 并行时撞车
+
+`git worktree` 的核心:**同一个 repo 多个工作副本,共享 .git,独立 working tree**。
+
+devflow-kit 在此基础上:
+
+- 每个 task 一个 worktree
+- 统一目录布局:`.devflow-worktrees/<slug>/task-N/`
+- 统一分支命名:`devflow/<slug>/task-N`
+- 生命周期由 `devflow apply` / `devflow worktree` 管理
+
+---
+
+## 标准工作流
+
+### 单 task 串行
+
+```bash
+devflow apply --task 1 --start
+# → 创建 .devflow-worktrees/<slug>/task-1/ 和分支 devflow/<slug>/task-1
+# → 终端自动 cd 到该 worktree(如配置了 shell hook)
+
+# 编码、测试、commit
+cd .devflow-worktrees/<slug>/task-1
+# ...
+
+# 回到主目录
+cd /path/to/main/repo
+devflow apply --task 1 --done --note="commit <sha>"
+
+# 进入下一个
+devflow apply --task 2 --start
+```
+
+### 多 task 并行
+
+```bash
+# 假设 plan.md DAG:
+#   T-01 → T-02 → T-05
+#   T-03 (独立)
+#   T-04 → T-05 (T-05 要等 T-02 和 T-04 都完成)
+
+# 终端 A
+devflow apply --task 1 --start
+
+# 终端 B (与 T-01 无依赖关系,可同时开)
+devflow apply --task 3 --start
+
+# T-01 完成后,终端 A 继续
+devflow apply --task 1 --done
+devflow apply --task 2 --start
+
+# T-01 完成后,并发开 T-04(与 T-02 无依赖)
+devflow apply --task 4 --start  # 终端 C
+
+# 终端 A 完成 T-02,终端 C 完成 T-04 后,T-05 才能开
+```
+
+每个终端 cd 到自己的 worktree,互不干扰:
+
+- 独立 working tree,没有文件冲突
+- 独立 git index / HEAD
+- build 缓存分开(Maven `target/`, Go `vendor/`, node `node_modules/` 独立)
+
+---
+
+## 合并策略
+
+### 按依赖顺序合并回 main,不按完成顺序
+
+```
+完成顺序:T-03 → T-01 → T-04 → T-02 → T-05
+依赖顺序:T-01 → T-02, T-04 并 → T-05, T-03 独立
+
+合并顺序(推荐):
+  T-01 → main
+  T-02 → main (rebase 后 push)
+  T-03 → main (独立,任何时候)
+  T-04 → main
+  T-05 → main
+```
+
+### merge vs rebase
+
+| 方式 | 场景 | 优点 | 缺点 |
+| --- | --- | --- | --- |
+| `--no-ff` merge commit | 保留 task 分支历史 | 能看到哪个 task 做了啥 | 历史图复杂 |
+| rebase then fast-forward | 要求线性历史 | 历史干净 | 丢失 task 边界(靠 commit message) |
+| squash merge | 多 commit task 压成一个 | commit 干净 | 丢失中间过程,PR discussion 对不上 |
+
+**devflow-kit 推荐:rebase + fast-forward**(若项目允许),或 `--no-ff` 合并 + commit message 明确 task id。
+
+### 冲突处置
+
+worktree 间**不允许直接 merge**(`T-03 worktree` merge `T-01 worktree`):会让合并关系变混乱。
+
+正确做法:
+
+```bash
+# 场景:T-02 依赖 T-01 完成,T-01 已 merge 到 main,T-02 worktree 需要更新
+
+# 在 T-02 worktree 里
+git fetch
+git rebase main          # 把 main 最新(含 T-01)应用到 T-02 的 commit 上
+# 如有冲突:解决 → git add → git rebase --continue
+
+# 继续 T-02
+```
+
+绝对不要:
+
+```bash
+# ❌ T-02 分支从 T-01 分支切,两者 merge 成一团
+git merge devflow/<slug>/task-1
+```
+
+---
+
+## 何时 `--no-worktree`
+
+worktree 有开销(磁盘占用 + 初次创建时间),不是所有场景都值得:
+
+| 场景 | 用 worktree? | 说明 |
+| --- | --- | --- |
+| L2 / L3 多 task,需要并行 | ✅ 默认 | 本节主线 |
+| L1 一行改 bug | ❌ `--no-worktree` | 杀鸡焉用牛刀 |
+| 纯 spike / 实验,不打算合并 | ❌ `--no-worktree` | 做完 reset |
+| plan 只有 1 个 task | ❌ `--no-worktree` | worktree 开销 > 好处 |
+| 磁盘紧张(嵌入设备 / CI 容器) | ❌ `--no-worktree` | 按需 |
+| 项目有 symlink / 路径硬编码 | ⚠️ 先验证 | 有些工具(IDE 插件)对非 repo-root 敏感 |
+
+用法:
+
+```bash
+devflow apply --task 1 --start --no-worktree
+# 直接在当前分支上做;完成后 devflow apply --task 1 --done
+```
+
+---
+
+## 清理
+
+### 合并后清理
+
+```bash
+# task merge 到 main,分支和 worktree 都可以删
+devflow worktree cleanup <slug> --task 1
+# 等价于:
+#   git worktree remove .devflow-worktrees/<slug>/task-1
+#   git branch -D devflow/<slug>/task-1
+```
+
+### PR 未 merge 前的清理
+
+```bash
+# PR 还在 review,worktree 不需要了,但分支要留
+devflow worktree cleanup <slug> --task 1 --keep-branch
+# 等价于:
+#   git worktree remove .devflow-worktrees/<slug>/task-1
+#   (分支保留)
+```
+
+### 整 slug 完成后
+
+```bash
+devflow worktree cleanup <slug> --all
+# 删所有 task 的 worktree 和本地 devflow/<slug>/* 分支
+```
+
+### 查看
+
+```bash
+devflow worktree list <slug>
+# NAME       PATH                                 BRANCH                       STATUS
+# task-1     .devflow-worktrees/abc/task-1        devflow/abc/task-1            clean, ahead 3
+# task-2     .devflow-worktrees/abc/task-2        devflow/abc/task-2            dirty (modified)
+# task-3     —                                    devflow/abc/task-3            (branch exists, no worktree)
+```
+
+---
+
+## 故障场景
+
+### worktree 创建失败
+
+```
+Error: fatal: '.devflow-worktrees/<slug>/task-1' already exists
+```
+
+对策:
+
+```bash
+devflow worktree cleanup <slug> --task 1  # 清旧的
+devflow apply --task 1 --start            # 重开
+```
+
+### 跨 worktree 误改到 main 分支
+
+worktree 模式下 main 目录通常也是个 worktree。误 `git commit` 到 main:
+
+```bash
+# 在 main 目录
+git log --oneline  # 看误提交了什么
+git reset HEAD~1   # 撤销,保留改动
+# 切到正确的 task worktree
+cd .devflow-worktrees/<slug>/task-N
+git apply /path/to/saved/patch
+```
+
+### worktree 磁盘不够
+
+每个 worktree 的 node_modules / target / vendor 独立,会占用 N 倍空间。
+
+对策:
+
+- 限制并发 task 数(2-3 个)
+- 用 pnpm / bazel 等跨 worktree 共享缓存的工具
+- `devflow worktree prune` 清未使用的(合并后的)
+
+### 主 repo 误删 `.git`(灾难)
+
+worktree 依赖主 repo 的 `.git`。主 repo 损坏 / 误删 → 所有 worktree 失效。
+
+预防:
+
+- 主 repo 不动(代码操作都在 worktree 里)
+- `devflow doctor` 会检查 `.git` 完整性
+
+---
+
+## 与 CI 的关系
+
+- worktree 是**本地开发**优化,CI 不使用(CI 是 fresh clone)
+- CI pipeline 应按**合并后 main 的 commit** 触发,而不是单独 task 分支
+- 如果 task 分支也要跑 CI(pre-merge check),用 `devflow/<slug>/task-*` 的分支 pattern 配 CI webhook
+
+---
+
+## 并行边界
+
+**能并行**:
+
+- 改不同模块(Files 列表无重叠)
+- 都只读主干(不影响彼此)
+- 一个前端 + 一个后端 task(语言栈独立)
+
+**不能并行**:
+
+- 两个 task 都要改同一个文件(合并时必冲突,不如串行)
+- 后一个 task 依赖前一个 task 的输出(契约、DDL、migration)
+- DDL 类 task(database 不可并发同时做同一张表的 schema 改)
+
+并行决策:看 plan.md 的 DAG,相同"层级"(无依赖关系)可并行,且 Files 无重叠。
+
+---
+
+## 合并前 checklist
+
+每个 task worktree 准备合并回 main 前:
+
+- [ ] 所有测试绿(本 task 的 + 本模块回归)
+- [ ] `git status` 干净
+- [ ] `git log --oneline main..HEAD` 检查 commit 干净(没有 "wip" / "fixup")
+- [ ] 如有多 commit:按 plan.md 规定是否 squash
+- [ ] 如需 rebase:`git rebase main` 成功,无遗留冲突
+- [ ] `devflow doctor` 过
+- [ ] `devflow apply --task N --done` 记录了最终 sha
+
+然后用项目默认的合并方式(直接 push / PR / MR)合回 main。
+
+---
+
+## 不要做的
+
+- ❌ 在 worktree 里 `git checkout main`(worktree 只应该在自己的 task 分支上)
+- ❌ 跨 worktree 复制文件("A 改好了我 cp 过来")→ 合并时混乱
+- ❌ 在 worktree 里 `git push` 不属于自己的分支
+- ❌ 用 IDE 的 "open multiple folders" 混淆主 repo 和 worktree → IDE 索引错乱
+- ❌ 在 `.devflow-worktrees/` 里手动 `git worktree add`(绕过 df)→ df 状态不同步

package/skills/archive/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: devflow-archive
+description: |
+  把 change 合进"真源"。默认 workspace 模式下，从
+  `~/.devflow/workspace/changes/<feature-xx>/` 读取过程文件，合并 spec delta 到
+  各项目仓的 `devflow/specs/`，并归档到 `~/.devflow/workspace/archive/<yyyy-mm-dd-feature-xx>/`。
+  同时同步归档各服务仓的局部 change。
+  knowledge deposit 统一从当前需求 workspace 的 `knowledge/` 执行。
+  触发:`devflow archive` 或 `/df:archive`。
+when_to_use: |
+  deliver 完成 **且** change 已 merge 到 main **且**(L3)rollout 通过稳定期。
+  不完成 archive,spec 库和生产就不一致,下一个 change 的 design 会基于漂移的 spec。
+---
+
+# archive
+
+**"把代码做的事写回 spec"**。生产里真实运行什么,`devflow/specs/` 就该反映什么。archive 是让这两者同步的最后一步。
+
+## 何时真的可以 archive
+
+archive 不是 deliver 后立刻做,要看 rollout 稳定性:
+
+| 级别 | archive 时机 |
+| --- | --- |
+| L1(简单修复) | merge 后即可 |
+| L2 | merge 后 24-48h 无 P0/P1 issue |
+| L3 | 完成 rollout(灰度 → 全量)+ 稳定期(3-7 天)无重大回滚 |
+
+**早 archive 的风险**:rollout 失败回滚 → spec 已经写了新行为 → spec 和生产不一致 → 下一个 change 基于错误 spec。
+
+## 前置检查
+
+| 条件 | 必需 | 失败处理 |
+| --- | --- | --- |
+| `state.delivery.status === "completed"` | 是 | 等 deliver |
+| change 已 merge 到 main(或对应 target) | 是 | 等合并 |
+| L3:rollout 稳定期已过 | L3 必须 | 等稳定 |
+| 有 `delta/*.md`(改了系统能力) | L2/L3 必须 | 补写 delta，或确认本次无 capability 变更 |
+| 有 `knowledge/` 条目 | L2/L3 推荐 | 没有可复用经验时可为空；有经验直接写到 `knowledge/<分类>/` |
+| 无 blocking concern(如回滚待跟进) | 是 | 先处理 concern |
+
+> **delta 文件在哪产生**：`devflow design --with-spec` 阶段，默认 workspace 模式下 agent 应在
+> `~/.devflow/workspace/changes/<feature-xx>/delta/` 下创建；服务局部 delta 可放
+> `<service-repo>/devflow/changes/<slug>/delta/` 作为对应服务仓的输入。
+> `<capability>.md`，frontmatter 写 `capability: <域>/<能力名>`（例：`coupon/grant`、`order/create`）。
+> 格式支持 `## ADDED Requirements` / `## MODIFIED Requirements` / `## REMOVED Requirements`。
+> 如果 tech-spec 阶段没有生成 delta，archive 时 spec 不会更新，须手动补写后重跑 `devflow archive`。
+
+## 核心动作
+
+### 1. Spec delta merge
+
+CLI **递归**扫 workspace 的 `changes/delta/` 以及各服务仓局部 `devflow/changes/<slug>/delta/`（含子目录），按 OpenSpec 语义合并到对应项目仓的 `devflow/specs/`：
+
+| section | 动作 |
+| --- | --- |
+| `## ADDED Requirements` | 在目标 spec 的 `## Requirements` 下 append |
+| `## MODIFIED Requirements` | 找到同名 `### heading` 块替换 |
+| `## REMOVED Requirements` | 找到同名块删除 |
+| `## REJECTED Alternatives` | 追加到目标 spec 的 `## REJECTED Alternatives` 段 |
+
+**落盘路径由 frontmatter `capability` 决定**（不是文件名）：
+
+| frontmatter `capability` | 目标 spec 路径                         |
+|--------------------------|----------------------------------------|
+| `coupon/grant`           | `specs/coupon/spec.md`                 |
+| `order/create`           | `specs/order/spec.md`                  |
+| _(无 capability 字段)_   | `specs/<文件名>.md`（兼容旧格式）      |
+
+不同业务域自动分目录，`specs/` 下结构清晰：
+```
+devflow/specs/
+├── coupon/grant.md
+├── order/create.md
+└── payment/alipay.md
+```
+
+合并的语义细节、多个 delta 顺序、heading 匹配规则、边界 case:见 [`references/spec-merge.md`](references/spec-merge.md)。
+
+### 2. 归档 workspace change
+
+```
+~/.devflow/workspace/changes/<feature-xx>/
+   → ~/.devflow/workspace/archive/<YYYY-MM-DD>-<feature-xx>/
+```
+
+完整保留所有过程文件(proposal / requirement / design / plan / review / verify / reports / state / delta)。
+
+archive 里的 state.json 会加一条:
+
+```json
+{
+  "phase": "archived",
+  "archivedAt": "2026-04-24T20:30:00Z",
+  "archivedBy": "@eng-a",
+  "mergedSha": "abc1234",
+  "specDeltasApplied": ["order-refund.md", "user-notification.md"]
+}
+```
+
+### 3. Knowledge deposit（自动）
+
+`devflow archive` 在移动文件夹前会**自动**执行 knowledge deposit：
+
+- 读 workspace `knowledge/` / `design.md` / 事件记录
+- 默认分类写入 `~/.devflow/workspace/changes/<feature-xx>/knowledge/`
+- 历史 in-repo 模式的 `<repo>/devflow/knowledge/` 仅做兼容，不作为新流程默认目标
+- 无需手动运行 `devflow knowledge deposit`
+
+如需跳过（例如已单独提前跑过）：`devflow archive --skip-deposit`。
+
+knowledge deposit 分类规则、写入格式:见 [`references/knowledge-deposit.md`](references/knowledge-deposit.md)。
+
+### 4. Workspace + 服务仓双归档
+
+workspace 使用 `changes/<feature-xx>/` 作为主归档对象：
+
+```
+~/.devflow/workspace/changes/<feature-xx>/
+  → ~/.devflow/workspace/archive/<YYYY-MM-DD>-<feature-xx>/
+```
+
+同时，每个涉及服务仓只归档该服务局部 change：
+
+```
+<service-repo>/devflow/changes/<slug>/
+  → <service-repo>/devflow/archive/<YYYY-MM-DD>-<slug>/
+```
+
+**归档职责边界：**
+
+- workspace archive：保存跨服务需求、总方案、总测试、统一知识沉淀、跨服务状态。
+- service archive：保存本服务 design / plan / verify / review / MR 相关材料。
+- knowledge 只从 workspace 的 `knowledge/` 统一同步到外部 KB；服务仓不再各自沉淀一份，避免重复和分类漂移。
+
+## Conflict 处理
+
+merge 时 heading 找不到(MODIFIED/REMOVED 的 target 不存在):
+
+```
+✗ conflict: delta/order-refund.md
+  MODIFIED: "退款请求处理流程"
+  → specs/order-refund.md 里没有 "退款请求处理流程" 这个 ### heading
+```
+
+**不要**直接 `--force`。选择:
+
+1. **heading 拼错**(最常见):改 `delta/*.md` 的 heading 让它匹配 specs
+2. **specs 原文 heading 被别人改过**:协调上游,要么按新 heading 写 delta,要么先合 heading 改回来
+3. **spec 基线漂移**:本 slug 的 delta 写在老基线上,基线已变 → 重新对齐(可能要回 tech-spec 看是否 design 也要调整)
+
+冲突决策树、`--force` 审计流程、多人并发 archive 的处置:见 [`references/conflict-resolution.md`](references/conflict-resolution.md)。
+
+**`--force` 何时可用**:仅当明确接受"把 MODIFIED 当 ADDED 追加"(例如 heading 就是新的,写错了前缀)。每次 `--force` 都要 `--reason="..."` 并写入 state 审计。
+
+## 后置动作
+
+archive 完成后 CLI 会自动：
+
+1. 合并 spec delta → 各项目仓 `devflow/specs/`
+2. Knowledge deposit / sync → `~/.devflow/workspace/changes/<feature-xx>/knowledge/`
+3. workspace `changes/<feature-xx>/` → workspace `archive/<date>-<feature-xx>/`
+4. 各服务仓局部 `devflow/changes/<slug>/` → `devflow/archive/<date>-<slug>/`
+5. 关闭 state（`phase=archived`）
+6. 打印 `workflow complete for <slug>`
+
+archive 是**工作流最后一步**，执行完即全流程结束。无需再手动跑 knowledge deposit。
+
+**不自动做**:
+
+- 不自动 `git push specs`(用户自行 commit 决定)
+- 不自动清本地分支(`devflow worktree cleanup` 用户自己调)
+- 不自动 close JIRA issue(用 deliver 后的 hook)
+
+## 撤销 archive(紧急)
+
+罕见但需要:rollout 后发现问题要大回滚。
+
+```bash
+devflow archive --undo <slug>
+```
+
+- spec 回退(git 层用 revert 或 reset,取决于 repo 策略)
+- change 从 archive/ 搬回 changes/
+- state 恢复到 archive 前 phase
+
+**副作用**:
+
+- 若已 `devflow knowledge deposit`,不自动撤销(knowledge 单独处理)
+- 若 archive 已 push 到 git,需要协调团队(revert commit + 通知)
+
+该操作需 `--confirm` 双重确认,审计记录到 `devflow/archive/undo-log.md`。
+
+## 完成状态协议
+
+```
+---STATUS---
+result: DONE | BLOCKED | NEEDS_INPUT
+archiveStatus: completed
+outputs:
+  - devflow/archive/2026-04-24-coupon-batch-grant/
+  - devflow/specs/coupon-management.md (MODIFIED)
+  - devflow/specs/coupon-batch-grant.md (CREATED)
+deltasApplied:
+  - coupon-management.md: 1 MODIFIED
+  - coupon-batch-grant.md: 3 ADDED
+conflicts: []
+nextAction: workflow complete
+---END_STATUS---
+```
+
+## 反模式
+
+- **不管 rollout,merge 后立刻 archive**:L3 要等稳定期,否则 spec 可能和生产不一致
+- **--force 吞冲突**:冲突是"spec 基线漂了"的信号,吞了等于把问题延迟到下一次 change
+- **delta 写得太模糊**(比如 "优化退款流程"):spec 读者看不懂做了什么,归档价值低
+- **把经验同时写 `learnings.md` 和 `knowledge/解决方案/`**:两份内容会重复漂移；新流程只保留 `knowledge/`
+- **archive 完不提 git**:spec 改了没 push → 下一个人基于老 spec 做 design → 重走冲突
+- **把所有 change 的 delta 合成一份大 delta**:失去细粒度,反查不方便
+- **重复 archive 同 slug**:目录冲突,且审计混乱;应 rename 或先 undo
+- **改 archive 里的内容**:archive 应该是只读快照;要改就 undo + 重 archive
+- **knowledge deposit 前不检查分类**:AI 自动归类可能不准,要 human 审
+- **archive 后立刻启动下一个相关 change**:如果 specs merge 后还有未 deploy 的部分,会踩坑;确认 rollout 稳定
+
+## 参考
+
+- [`references/spec-merge.md`](references/spec-merge.md) — delta → spec 合并语义、heading 规则、多 delta 顺序、边界 case
+- [`references/conflict-resolution.md`](references/conflict-resolution.md) — 冲突决策树、`--force` 审计、并发 archive 处置
+- [`references/knowledge-deposit.md`](references/knowledge-deposit.md) — 经验沉淀分类规则、写入格式、provider 与同步