@specpow/framework 0.5.11 → 0.5.13

package/builtin/skills/execution-receiving-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: execution-receiving-review
+description: SpecPow execution-receiving-review skill
+---
+
+# 接收审查
+
+> 收到代码审查反馈后的正确处理流程
+
+## 触发条件
+
+- 收到审查意见/评论
+- PR/MR 有审查反馈
+- 用户提到"处理审查"/"审查反馈"
+
+## 铁律
+
+1. **不辩解** — 审查意见是改进机会，不是攻击
+2. **逐条回应** — 每个 Finding 都要回复
+3. **修复优先** — Critical/Major 必须修复
+4. **不扩大范围** — 只修复审查指出的问题
+
+## 处理流程
+
+### 1. 分类反馈
+- Critical → 立即修复
+- Major → 本轮修复
+- Minor → 本轮修复或标注后续处理
+- Suggestion → 评估后决定
+
+### 2. 修复
+- 每个修复单独 commit
+- commit message 引用 Finding ID
+
+### 3. 回应
+```
+✅ [Critical] SQL 注入 → 已修复 (commit abc123)
+✅ [Major] 缺少事务 → 已修复 (commit def456)
+⏳ [Minor] 命名优化 → 下个迭代处理
+📝 [Suggestion] 重构 → 超出本次范围，记录到 backlog
+```
+
+## 红旗
+
+- 忽略 Critical → 必须修复
+- 反驳审查而不修改 → 重新评估
+- 修复引入新问题 → 回退并重新修复

package/builtin/skills/execution-requesting-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: execution-requesting-review
+description: SpecPow execution-requesting-review skill
+---
+
+# 请求审查
+
+> 在完成任务后，正确请求代码审查
+
+## 触发条件
+
+- 任务完成后需要请求审查
+- 准备提交 PR/MR
+- 用户提到"请求审查"/"review"
+
+## 铁律
+
+1. **自审先行** — 先自己审查一遍再请求他人
+2. **上下文充分** — 提供变更背景和影响范围
+3. **范围明确** — 指明需要重点审查的部分
+
+## 审查请求模板
+
+```markdown
+## 审查请求
+
+### 变更概述
+- 变更 ID: xxx
+- 影响范围: [文件列表]
+- 变更类型: [新功能/修复/重构]
+
+### 自审结果
+- [ ] 代码编译通过
+- [ ] 测试通过
+- [ ] 无 lint 警告
+- [ ] 文档已更新
+
+### 重点审查
+1. [文件:行号] — 请确认逻辑正确性
+2. [文件:行号] — 请确认性能可接受
+
+### 背景信息
+- 相关需求: [链接]
+- 技术决策: [说明]
+```
+
+## 红旗
+
+- 未自审就请求审查 → 先自审
+- 变更超过 500 行 → 拆分变更
+- 无测试 → 补充测试后再请求

package/builtin/skills/execution-sdd-orchestrator/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: execution-sdd-orchestrator
+description: SDD 编排技能。将 controller.ts 的 implement→review→fix 循环转化为宿主 Agent 可执行的指令。当执行 specpow apply 或用户要求实现变更时使用。
+version: 1.0.0
+trigger: on-demand
+---
+
+# SDD 编排技能
+
+当执行 `specpow apply` 或用户要求实现变更时，按以下流程执行。
+
+## 前置条件
+
+- 变更提案已完成：`.specpow/openspec/changes/{change}/` 存在
+- 任务清单已生成：`.specpow/openspec/changes/{change}/task-manifest.json`（Host-Driven 模式由 `apply.ts` 生成）
+- Ledger 位置：`.specpow/sdd/{change}/progress.md`
+
+## 执行流程
+
+### 步骤 1：初始化
+
+1. 读取 Ledger（`progress.md`），检查是否有已完成的任务（断点续跑）
+2. 读取任务清单：`.specpow/openspec/changes/{change}/task-manifest.json`（包含增强描述和 specConstraints）
+3. 记录 BASE commit：`git rev-parse HEAD`
+
+### 步骤 2：逐任务执行
+
+对每个未完成任务：
+
+#### 2a. 创建 Brief
+
+读取任务信息，创建 brief 文件：
+- **路径**：`.specpow/sdd/{change}/task-{N}-brief.md`
+- **内容**：
+  ```markdown
+  # Task {N}: {title}
+
+  ## 描述
+  {description}
+
+  ## 涉及文件
+  {files list}
+
+  ## Spec 约束
+  {spec constraints from specs/ directory}
+
+  ## 输出要求
+  完成后写 Report JSON 到：`.specpow/sdd/{change}/task-{N}-report.md`
+  ```
+
+#### 2b. 派发实现者子代理
+
+使用宿主原生 subagent 工具派发：
+- **Prompt**：读取 brief 文件 + TDD 指令 + spec 约束
+- **模型选择**（参考，可根据实际情况调整）：
+  - ≤2 文件 + 完整 spec → `cheap`（haiku）
+  - 多文件协调 → `standard`（sonnet）
+  - 需要架构判断 → `capable`（opus）
+- **指令**：
+  1. 读取 brief 文件
+  2. TDD 流程：RED → GREEN → REFACTOR
+  3. 遵守 spec 约束
+  4. 完成后写 Report JSON 到 reportPath
+
+#### 2c. 检查 Report
+
+读取 `.specpow/sdd/{change}/task-{N}-report.md`，解析 JSON：
+```json
+{
+  "status": "done|blocked|in_progress|done_with_concerns|needs_context",
+  "commits": ["sha1", "sha2"],
+  "testSummary": "X tests passed",
+  "concerns": "any issues or null",
+  "fixReport": "修复说明（仅 fix 轮次）"
+}
+```
+
+- `status === 'blocked'` → 记录到 Ledger：`Task {N}: BLOCKED — {concerns}`，跳过此任务
+- `status === 'done'` → 继续审查
+
+#### 2d. 生成审查包
+
+运行 `git diff` 生成变更摘要：
+```bash
+BASE_COMMIT={recorded base commit}
+HEAD_COMMIT=$(git rev-parse HEAD)
+git diff ${BASE_COMMIT}..${HEAD_COMMIT} > .specpow/sdd/{change}/review-package.md
+```
+
+#### 2e. 派发审查者子代理
+
+使用宿主原生 subagent 工具派发：
+- **Prompt**：brief + review package + spec 约束
+- **指令**：
+  1. 读取 brief 文件
+  2. 读取 review package（diff）
+  3. 两阶段审查：
+     - **阶段 A：Spec 合规性** — 实现是否满足 spec 要求
+     - **阶段 B：代码质量** — bug、安全问题、性能问题
+     - **阶段 C：TDD 合规** — 测试是否充分
+  4. 输出 Review JSON 到 `.specpow/sdd/{change}/review-result.json`：
+     ```json
+     {
+       "specCompliant": true/false,
+       "qualityApproved": true/false,
+       "findings": [
+         {
+           "id": "F1",
+           "severity": "critical|important|minor",
+           "description": "...",
+           "file": "src/foo.ts",
+           "line": 42,
+           "isLoadBearing": false
+         }
+       ],
+       "cannotVerify": ["..."]
+     }
+     ```
+     **注意**：初始审查不输出 `addressed` 字段（由重审者在修复循环中填充）。
+
+#### 2f. 运行测试
+
+执行项目测试：
+```bash
+# 检测包管理器并运行测试
+if [ -f pnpm-lock.yaml ]; then
+  pnpm test --silent
+elif [ -f yarn.lock ]; then
+  yarn test --silent
+else
+  npm test --silent
+fi
+```
+
+记录测试结果：通过/失败。
+
+#### 2g. 分析审查结果
+
+读取 review JSON，判定：
+- `specCompliant === true && qualityApproved === true && tests passed` → **PASS**
+  - 记录到 Ledger：`Task {N}: complete (commits {BASE}..{HEAD}, review clean)`
+  - 进入下一任务
+- `findings.length > 0 || tests failed` → **需要修复**，进入修复循环
+
+### 步骤 3：修复循环（最多 5 轮）
+
+每轮：
+
+1. **派发实现者修复（复用原始 brief）**
+   - Brief 路径不变：`.specpow/sdd/{change}/task-{N}-brief.md`（不修改 brief 文件）
+   - Open findings 通过指令传递给实现者，不写入 brief 文件
+   - **模型升级**：第 4-5 轮使用比当前高一级模型
+   - **指令**：修复 findings → 写 Report JSON 到 `task-{N}-report.md.fix-{R}`
+
+2. **生成修复 diff**
+   ```bash
+   FIX_BASE=$(git rev-parse HEAD)
+   # 实现者修复后...
+   FIX_HEAD=$(git rev-parse HEAD)
+   git diff ${FIX_BASE}..${FIX_HEAD} > .specpow/sdd/{change}/review-package.md
+   ```
+
+3. **派发重审者（范围限定）**
+   - **只审查修复部分**，不重新审查整个任务
+   - **指令**：对每个 finding 判定 `addressed: true/false`
+   - 输出更新后的 review JSON 到 `.specpow/sdd/{change}/re-review-result.json`
+
+4. **运行测试**
+
+5. **分析结果**
+   - 所有 findings addressed + tests passed → **PASS**
+   - 仍有 open findings → 继续下一轮
+
+6. **记录到 Ledger**
+   ```
+   Task {N}: fix round {R}/5 ({A} addressed, {O} open — {finding1_summary}; {finding2_summary}; commits {BASE}..{HEAD})
+   ```
+
+**断路器**：5 轮后仍未通过 → 对每个 finding 判定：
+- `isLoadBearing === false` → **park**（延后，记录到 Ledger）
+- `isLoadBearing === true` → **block**（阻塞，任务标记为 BLOCKED）
+
+### 步骤 4：完成
+
+所有任务完成后，输出总结：
+```
+✅ SDD 执行完成
+- 完成任务：X/Y
+- 阻塞任务：Z
+- 停放发现：N（已记录到 Ledger）
+```
+
+## 并行执行模式
+
+当用户指定 `--parallel` 或任务数量 ≥ 3 且无强依赖时，可启用并行执行。
+
+### 前置条件
+
+- 任务清单已读取
+- 依赖分析完成（参考 `buildParallelLayers` 逻辑）
+
+### 执行流程
+
+#### 1. 依赖分析与分层
+
+分析任务依赖关系，构建并行层：
+- **文件级依赖**：多个任务修改同一文件 → 顺序执行
+- **逻辑级依赖**：tasks.md 中显式声明的依赖
+- **分层结果**：每层内的任务彼此独立，可并行执行
+
+```
+示例：
+- 层 1: [T1, T2, T3] — 无依赖，可并行
+- 层 2: [T4] — 依赖 T1 的输出
+- 层 3: [T5, T6] — 无依赖，可并行
+```
+
+#### 2. 逐层并行执行
+
+对每一层：
+
+##### 2a. 为每个任务创建 Git Worktree
+
+```bash
+# 为每个任务创建独立 worktree
+BASE_COMMIT=$(git rev-parse HEAD)
+BRANCH_NAME="specpow-parallel-{TASK_NUM}-{TIMESTAMP}"
+WORKTREE_PATH=".specpow/sdd/{change}/.worktrees/task-{TASK_NUM}"
+
+git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" "$BASE_COMMIT"
+```
+
+**关键**：
+- 每个任务在独立的 worktree 中工作，消除并行竞态
+- worktree 拥有独立的 HEAD 和工作目录
+- 所有文件编辑和 git 操作必须在 worktree 中执行
+
+##### 2b. 并行派发实现者子代理
+
+使用宿主原生 subagent 工具**同时**派发多个实现者：
+
+```
+对层内的每个任务：
+  派发子代理（isolation: "worktree"）：
+    - prompt: 读取 brief + TDD 指令 + spec 约束
+    - 指令：在 worktree 中工作，完成后写 report
+    - 模型选择：参考串行模式的模型选择表
+```
+
+**并行派发示例**（Claude Code）：
+```
+同时发起多个 Agent 调用：
+- Agent 1: "Task 1 in worktree .specpow/sdd/{change}/.worktrees/task-1"
+- Agent 2: "Task 2 in worktree .specpow/sdd/{change}/.worktrees/task-2"
+- Agent 3: "Task 3 in worktree .specpow/sdd/{change}/.worktrees/task-3"
+```
+
+##### 2c. 等待所有子代理完成
+
+所有子代理完成后，检查各自的 report 文件。
+
+##### 2d. 顺序合并分支
+
+```bash
+# 按任务编号顺序合并
+for TASK_NUM in 1 2 3; do
+  BRANCH="specpow-parallel-${TASK_NUM}-xxx"
+  git merge "$BRANCH" --no-edit
+  
+  # 检查冲突
+  if [ $? -ne 0 ]; then
+    echo "冲突：任务 $TASK_NUM 合并失败"
+    # 记录到 Ledger
+  fi
+done
+```
+
+##### 2e. 冲突检测
+
+检查哪些文件被多个任务修改：
+```bash
+# 对每个完成的任务，获取变更文件列表
+for TASK_NUM in 1 2 3; do
+  git diff --name-only "$BASE_COMMIT".."$HEAD_COMMIT"
+done
+
+# 如果同一文件出现在多个任务的变更列表中 → 冲突
+```
+
+##### 2f. 清理 Worktree
+
+```bash
+# 删除 worktree 和分支
+git worktree remove ".specpow/sdd/{change}/.worktrees/task-{TASK_NUM}" --force
+git branch -D "specpow-parallel-{TASK_NUM}-xxx"
+```
+
+##### 2g. 运行集成测试
+
+所有任务合并后，运行完整测试套件：
+```bash
+pnpm test --silent
+```
+
+##### 2h. 记录到 Ledger
+
+```
+Layer {L}: complete ({N} tasks merged, {C} conflicts detected)
+```
+
+#### 3. 层间串行
+
+前一层合并完成后，才开始下一层。这确保了依赖关系的正确性。
+
+### 并行执行的注意事项
+
+1. **绝不并行修改同一文件** — 依赖分析必须准确
+2. **合并后必须运行完整测试** — 并行执行可能引入集成问题
+3. **冲突是并行代价** — 显式报告冲突，而非静默丢失
+4. **Worktree 清理必须彻底** — 即使任务失败也要清理
+5. **断路器保护** — 如果一层中有 ≥ 50% 任务失败，停止后续层
+
+### 何时使用并行模式
+
+| 场景 | 推荐模式 |
+|------|----------|
+| 3+ 个独立任务，无文件重叠 | 并行 |
+| 任务间有强依赖 | 串行 |
+| CI/CD 自动化 | 并行（节省时间） |
+| 交互式开发，需要实时反馈 | 串行（更易调试） |
+| 多文件非依赖变更 | 并行 |
+
+## Ledger 记录格式
+
+每完成一个操作，**追加一行**到 `.specpow/sdd/{change}/progress.md`。
+格式为**扁平日志行**（不是结构化 markdown），ledger.ts 用正则解析这些行。
+
+首行固定为：
+```
+# SDD ledger — plan: {planFile}
+```
+
+后续追加的日志行格式：
+
+```
+Task {N}: complete (commits {BASE}..{HEAD}, review clean)
+Task {N}: complete (commits {BASE}..{HEAD}, review with parked)
+Task {N}: fix round {R}/{MAX} ({A} addressed, {O} open — {summary1}; {summary2}; commits {RANGE})
+Task {N}: BLOCKED — {reason}
+Task {N}: parked — {description} — ruling: {ruling}
+Task {N}: minor (deferred): {description}
+```
+
+**注意**：
+- 每行独立，不分组、不嵌套
+- `review clean` 表示审查通过无停放；`review with parked` 表示有停放发现
+- fix round 行中的 summaries 用分号分隔，每个 summary 对应一个 open finding 的描述
+- `{MAX}` 来自配置 `sdd.maxFixRounds`（默认 5）
+
+## 关键原则
+
+1. **文件即接口** — 所有产物通过文件传递，不占用上下文
+2. **信任 Ledger** — 断点续跑时读取 Ledger，不信任记忆
+3. **模型升级** — 修复轮次 4-5 升级模型，避免卡死
+4. **范围限定重审** — 修复后只审查修复部分，提高效率
+5. **断路器保护** — 5 轮后强制判定，避免无限循环