sillyspec 3.26.6 → 3.26.8

package/src/stages/execute.js

@@ -1,967 +1,985 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
-import path from 'path'
-import { buildContractMatrix, buildConsumerInjection, buildContractFieldInjection } from '../contract-matrix.js'
-import { getRule } from '../stage-contract-spec.js'
-import { renderDispatchInstruction } from '../dispatch/strategy.js'
-import { isPathASupported } from '../dispatch/backends/sillyhub-mcp.js'
-import { readMcpConfig } from '../sillyhub-mcp/config.js'
-import { gitQuiet } from '../git-helper.js'
-import { parseRepo } from './plan-postcheck.js'
-
-/**
- * 校验 plan.md 是否满足 execute 执行契约
- * @param {string} planContent - plan.md 文件内容
- * @returns {{ ok: boolean, errors: string[], warnings: string[], tasks: object[], waves: object[] }}
- */
-export function validatePlanForExecute(planContent) {
-  const errors = []
-  const warnings = []
-
-  if (!planContent || !planContent.trim()) {
-    return { ok: false, errors: ['plan.md 内容为空'], warnings, tasks: [], waves: [] }
-  }
-
-  const waves = parseWavesFromPlan(planContent)
-
-  // 收集所有 task
-  const allTasks = []
-  for (const wave of waves) {
-    for (const task of wave.tasks) {
-      allTasks.push(task)
-    }
-  }
-
-  // 检查 1: 至少有一个 checkbox task
-  if (allTasks.length === 0) {
-    // 诊断根因（坑 plan-md-format-contract-hidden）：笼统报"没有找到 checkbox task"逼 agent 试错。
-    // 区分：无 Wave/Tasks 段 / Wave 标题格式不对 / task 用 ### 标题 / checkbox 被非 Wave 标题打断。
-    const diags = diagnoseNoTaskRootCause(planContent)
-    errors.push('plan.md 中没有找到 checkbox task（格式: "- [ ] task-XX: 任务名"）')
-    for (const d of diags) errors.push(`  诊断：${d}`)
-    return { ok: false, errors, warnings, tasks: allTasks, waves }
-  }
-
-  // 检查 2: task id 唯一性
-  const idCounts = {}
-  for (const task of allTasks) {
-    if (task.index != null) {
-      const key = `task-${task.index}`
-      idCounts[key] = (idCounts[key] || 0) + 1
-    }
-  }
-  for (const [id, count] of Object.entries(idCounts)) {
-    if (count > 1) {
-      errors.push(`task id 重复: ${id} 出现 ${count} 次`)
-    }
-  }
-
-  // 检查 3: task id 连续性（从 1 开始）
-  const ids = allTasks
-    .map(t => t.index)
-    .filter(i => i != null)
-    .sort((a, b) => a - b)
-  if (ids.length > 0) {
-    const expected = Array.from({ length: ids.length }, (_, i) => ids[0] + i)
-    // 只检查以 task-01 起始的情况（常见模式）
-    if (ids[0] === 1) {
-      for (let i = 0; i < ids.length; i++) {
-        if (ids[i] !== i + 1) {
-          errors.push(getRule('plan.task-id-continuity').failMessage.replaceAll('${expected}', String(i + 1).padStart(2, '0')).replaceAll('${actual}', String(ids[i]).padStart(2, '0')))
-          break
-        }
-      }
-    }
-  }
-
-  // 检查 4: task name 非空
-  for (const task of allTasks) {
-    if (!task.name || !task.name.trim()) {
-      errors.push(`task-${String(task.index || '?').padStart(2, '0')}: 任务名为空`)
-    }
-  }
-
-  // 检查 5: task 无 id 的 warning（不限制只在有 id 时检查）
-  for (const wave of waves) {
-    for (const task of wave.tasks) {
-      if (task.index == null) {
-        warnings.push(`Wave ${wave.index}: task "${task.name}" 没有 task id（建议格式 task-XX: 名称）`)
-      }
-    }
-  }
-
-  return { ok: errors.length === 0, errors, warnings, tasks: allTasks, waves }
-}
-
-export const definition = {
-  name: 'execute',
-  title: '波次执行',
-  description: '子代理并行 + 强制 TDD + 两阶段审查',
-  steps: [] // 动态构建，由 buildExecuteSteps() 生成
-}
-
-// 固定前缀步骤定义
-const fixedPrefix = [
-  {
-    name: '进度确认',
-    migratedFrom: ['状态检查'],
-    prompt: `检查当前进度，确认可以执行 execute。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
-
-### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 execute
-3. 如果不是 → 检查是否有未完成的 tasks.md
-4. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
-
-### 输出
-当前状态 + 执行范围确认`,
-    outputHint: '当前状态 + 执行范围',
-    optional: false
-  },
-  {
-    name: '加载上下文',
-    prompt: `加载计划、设计和代码库上下文。
-
-### 操作
-1. 读取 tasks.md（执行计划）
-2. 读取 design.md（技术方案）
-3. 读取 CONVENTIONS.md、ARCHITECTURE.md
-4. 读取 local.yaml（构建命令）；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
-5. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）
-
-### 模块文档加载
-6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-7. 根据 plan.md 中的任务文件路径匹配 _module-map.yaml 中的模块
-8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
-9. 实现代码时遵循模块文档中描述的接口约定、数据流和依赖关系
-10. **利用模块索引快速定位源码**：
-    - 用 entrypoints 字段直接找到模块对外 API 的源码位置
-    - 用 main_symbols 字段找到核心类/函数的定义位置
-    - 子代理优先读模块卡片理解语义，再读 entrypoints/main_symbols 对应的源码
-
-### 符号影响面扩展检查
-11. **符号影响面扫描**（Critical — execute 前必做）：
-    - 读取所有 tasks/task-NN.md，提取每个任务涉及的修改文件
-    - 对每个修改文件，检查是否涉及以下变更类型：
-      - class 构造函数参数变更（新增/删除/修改参数）
-      - 接口（interface）定义变更
-      - DTO / 类型定义变更
-      - API client 方法签名变更
-      - 函数/方法签名变更（参数增删改）
-    - 如果涉及上述变更类型，执行调用点搜索：
-      \`\`\`bash
-      rg "new ClassName\(" src/
-      rg "ClassName\(" src/
-      rg "methodName\(" src/
-      rg "import.*from.*filePath" src/
-      \`\`\`
-    - 将搜索到的调用点与 plan.md 和 tasks/task-NN.md 的 allowed_paths 对比
-    - **发现调用点不在任何 task 的 allowed_paths 中 → 直接阻断 execute**
-    - 报告：列出每个受影响符号、调用点位置、是否在任务范围内
-    - 如果调用点不在范围内但任务明确写了"不改原因"，记录但不阻断
-
-### 输出
-已加载的上下文摘要（含模块文档 + 源码锚点）`,
-    outputHint: '上下文摘要',
-    optional: false
-  },
-  {
-    name: '确认 worktree 路径',
-    prompt: `确认当前 worktree 状态，提取隔离路径。
-
-### 操作
-1. 运行 \`sillyspec worktree meta <change-name>\` 读取 meta.json
-2. 从输出中提取 worktreePath、branch、mode 字段
-3. 确认 worktree 目录存在（如果是 worktree/native-worktree 模式）
-4. **确认工具链可用**：worktree 内项目工具链（lint/format/test 二进制，如 ruff / prettier / uv）可能不全——对本次会用到的工具先跑一次 \`--version\` 确认；缺失则按项目方式安装（Python 项目 \`uv tool install ruff\` / \`uv sync\`，Node 项目 node_modules 已由 CLI 链接主仓）。不要等到 commit 才发现二进制不在 PATH 被 hook 拦
-
-### 铁律
-- **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
-- **后续所有子代理的 cwd 必须设为该 worktree 路径**
-- 如果 meta.json 不存在（说明创建失败），停止并报错
-- **不要自行检查 git dirty/uncommitted 状态来判断是否可以进入 worktree，CLI 已自动处理**
-
-### 输出
-worktree 路径 + 分支名 + 模式
-
-`,
-    outputHint: 'worktree 路径 + 分支名 + 模式',
-    optional: false
-  },
-  {
-    name: '确认执行范围',
-    prompt: `解析任务，确认执行范围和确认模式。
-
-### 操作
-1. 从 plan 中解析 Wave 分组和任务列表
-2. 模型档位：若 tasks.md 中某 task 标注了 [model:xxx]，启动该 task 子代理时按标签选模型（档位由 plan 阶段或用户在 tasks.md 显式标注，execute 不在此自动建议——关键词→档位无统一映射，自动建议反而易误导）
-3. 确认频率：默认每个 Wave 完成后展示结果（wave 模式）；用户口头指定按 Task 展示或全自动时遵从
-4. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
-
-### 知识命中报告
-{KNOWLEDGE_HIT_REPORT}
-
-如上所示的知识条目与本次任务相关。请阅读这些条目以获取项目约定和已知模式。
-如无命中条目（Status: no matches），跳过本节。
-
-### 铁律
-- **不要询问用户确认频率**，默认 wave 模式；用户已明确口头指定时遵从其指定`,
-    outputHint: 'Wave 分组 + 模型分配',
-    optional: false
-  }
-]
-
-// 全局验收步骤定义
-const acceptanceSteps = [
-  {
-    name: '对照设计检查',
-    mode: 'acceptance',
-    prompt: `对照 design.md 检查所有实现是否与设计一致。
-
-### 执行方式（CLI 按变更规模判定，占位符由 run.js 注入）
-tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
-- tier=self：当前 agent 汇总执行（对照 design.md 逐项检查 + 偏差说明）
-- tier=independent：必须用 Agent tool 启动一个独立的 QA 子代理（独立上下文，不共享实现者的分析），子代理对照 design.md 逐项检查实现一致性并输出 review.json。review.json 产物契约（CLI Stage Review Gate 将硬校验，schema + 完整示例 + docHash 算法如下，照抄改值；reviewedFiles 除主文档 design.md 外可追加 git diff 涉及的源码文件）:
-{REVIEW_JSON_CONTRACT}
-  该 acceptance review 同时覆盖"代码审查"视角（风格/bug/安全/冗余），后续代码审查步骤仅需轻量复审。
-
-### 操作
-1. 读取 design.md（技术方案）
-2. 逐一对照 design.md 中的设计要点与实际代码实现
-3. 检查接口签名、数据结构、模块划分是否一致
-4. 记录偏差项（偏差 ≠ 错误，可能是合理的实现调整）
-
-### 输出
-检查清单：每项设计要点的实现状态 ✅/⚠️/❌ + 偏差说明`,
-    outputHint: '设计对照检查清单',
-    optional: false
-  },
-  {
-    name: '运行测试',
-    mode: 'acceptance',
-    prompt: `运行所有测试，验证代码质量。
-
-### 执行方式
-本步骤由当前 agent 执行，不需要启动独立子代理。
-
-### 操作
-1. 读取 local.yaml 获取构建和测试命令；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
-2. 运行测试套件（单元测试、集成测试）
-3. 运行 lint 检查 **+ 格式化**：凡变更涉及的源码，既跑 lint check 也跑 formatter（如 \`ruff format\` / \`prettier --write\` / \`black\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截
-4. 如果有测试失败 → 分析原因，标注是代码问题还是测试本身的问题
-5. 汇总测试结果
-
-### 铁律
-- 长测试/构建/lint 命令必须**前台同步执行**，禁止 run_in_background:true / & / nohup / disown——后台任务易被会话生命周期回收导致中断无果
-
-### 输出
-测试结果摘要：通过/失败/跳过数量 + 失败项分析`,
-    outputHint: '测试结果摘要',
-    optional: false
-  },
-  {
-    name: '代码审查',
-    mode: 'acceptance',
-    prompt: `对本次变更进行代码审查。
-
-### 执行方式
-本步骤由当前 agent 或一个 QA agent 汇总执行，不需要为每个文件启动独立子代理。
-
-### 操作
-1. 检查 git diff 查看所有变更
-2. 审查要点：
-   - 代码风格是否符合 CONVENTIONS.md
-   - 是否有明显的 bug 或安全漏洞
-   - 是否有未处理的 TODO/FIXME
-   - 错误处理是否完善
-   - 是否有冗余代码或可简化的逻辑
-3. 对照 ARCHITECTURE.md 检查架构合规性
-
-### 输出
-审查结果：问题列表（严重程度 + 建议修复方式）+ 总体评价`,
-    outputHint: '代码审查结果',
-    optional: true
-  }
-]
-
-// 固定后缀步骤定义
-const fixedSuffix = [
-  {
-    name: '知识库审阅',
-    prompt: `检查本轮执行产生的新知识。
-
-### 操作
-1. 检查 \`.sillyspec/knowledge/uncategorized.md\` 中待确认条目
-2. 如有 → 提示用户审阅
-3. 用户确认后改为 [已确认]，可归类到专题文件
-
-### 输出
-新知识条目数量 + 审阅提示（或"无新知识"）`,
-    outputHint: '知识条目数量',
-    optional: true
-  },
-  {
-    name: '完成确认',
-    prompt: `所有任务完成后的收尾。
-
-先检查当前 worktree 的隔离模式：
-\`\`\`bash
-node -e "import('./src/worktree.js').then(w => { const wm = new w.WorktreeManager(); const m = wm.getMeta('<change-name>'); console.log(m ? JSON.stringify({mode: m.mode, path: m.worktreePath}) : 'no meta'); })"
-\`\`\`
-
-### 操作（mode = worktree，SillySpec 创建的隔离 worktree）
-
-**自动审计流程（不需要用户确认代码）：**
-
-1. 运行 \`sillyspec worktree assess <change-name>\` 自动风险审计
-2. 系统自动检查：
-   - patch --check 是否通过
-   - 变更是否在 allowed_paths 内
-   - 主工作区是否有未提交 dirty（拦截；已提交推进交 --3way 自动三路合并）
-   - 是否有高风险文件（lockfile/migration/配置/入口）
-   - diff 规模是否异常
-3. 输出 Apply Decision：
-
-\`\`\`
-Worktree Apply Decision
-────────────────────────
-Decision: SAFE | WARNING | BLOCKED
-Changed files: N
-Additions: +N  Deletions: -N
-Risky files: none | <list>
-Action: auto-applied | blocked
-\`\`\`
-
-4. **SAFE** → 自动 \`sillyspec worktree apply <change-name>\` + cleanup
-5. **WARNING** → 自动 apply（有警告但不阻断）+ cleanup
-6. **BLOCKED** → 不 apply，输出原因，提示用户检查：
-   - \`sillyspec worktree diff <change-name>\` 查看具体变更
-   - \`sillyspec worktree cleanup <change-name>\` 丢弃
-7. 建议下一步：\`sillyspec run verify\`
-
-### 操作（mode = native-worktree，用户已有的 linked worktree）
-1. 同上自动审计流程
-2. SAFE/WARNING → \`sillyspec worktree apply <change-name>\`
-3. **不要运行 cleanup**
-4. 输出 Worktree: kept
-5. 建议下一步：\`sillyspec run verify\`
-
-### 操作（mode = in-place-fallback，降级模式无隔离目录）
-1. 展示本次执行摘要（\`git diff\` 查看变更）
-2. 跳过 apply 和 cleanup
-3. 输出 Worktree: none
-4. 建议下一步：\`sillyspec run verify\`
-
-### 输出
-Apply Decision + 下一步建议
-
-### 注意
-- 完成后运行 \`sillyspec run execute --done\` 即可自动推进阶段`,
-    outputHint: 'apply 结果',
-    optional: false
-  }
-]
-
-/**
- * 诊断 plan.md 无 checkbox task 的根因（坑 plan-md-format-contract-hidden）。
- * 纯函数：读 planContent 文本，返回诊断提示数组。validatePlanForExecute 无 task 时追加到报错，
- * 帮 agent 区分 4 条隐性格式契约（Wave 标题字面 / task checkbox / task-XX 编号 / ### 打断 Wave 段）。
- * @param {string} planContent
- * @returns {string[]}
- */
-function diagnoseNoTaskRootCause(planContent) {
-  const diags = []
-  const hasWaveHeading = /^#+\s*Wave\s+\d+/im.test(planContent)         // "## Wave N"（字面）
-  const hasWaveWord = /^#+\s*(wave\s*\d+|w\d+|波次\s*\d+)/im.test(planContent) // 疑似 Wave 标题（含 W1/Wave1/波次1）
-  const hasCheckboxTask = /^[-*]\s*\[[ x]\]\s*task-\d+/im.test(planContent) // "- [ ] task-XX:" checkbox
-  const hasTaskHeading = /^#+\s*task-\d+/im.test(planContent)            // "### task-XX:" 标题（非 checkbox）
-  const hasTasksSection = /^#+\s*(tasks?|任务)\s*$/im.test(planContent)  // "## Tasks" / "## 任务"
-
-  if (!hasWaveHeading && !hasTasksSection) {
-    if (hasWaveWord) {
-      diags.push('Wave 标题格式不对：必须字面 "## Wave N"（Wave + 空格 + 数字），"## W1" / "## Wave1" / "## 波次1" 都不被识别')
-    } else if (hasCheckboxTask) {
-      diags.push('有 task checkbox 但不在 "## Wave N"（full）或 "## Tasks"（light/none）段内——非任务区的 checkbox 不收')
-    } else {
-      diags.push('plan.md 缺任务区：full 需 "## Wave 1" 标题，light/none 需 "## Tasks" 标题')
-    }
-  }
-  if (hasTaskHeading) {
-    diags.push('task 用了 "### task-XX:" 标题（非 checkbox）：标题会打断 Wave 段导致后续 checkbox 全被跳过，请改用 "- [ ] task-XX: 名称"（英文冒号）')
-  }
-  if (hasWaveHeading && hasCheckboxTask && !hasTaskHeading) {
-    diags.push('有 Wave 段也有 checkbox task 但未收容：checkbox 可能落在非任务区（如 "## 自检" 段）或被 "###" 标题打断，请检查 task 是否紧跟在 "## Wave N" 下')
-  }
-  return diags
-}
-
-/**
- * 从 plan 文件解析 Wave 分组
- */
-function parseWavesFromPlan(planContent) {
-  const waves = []
-  const lines = planContent.split('\n')
-  let currentWave = null
-  let currentTask = null
-  // light/none plan.md 用 `## Tasks`（无 `## Wave N`）包任务，需识别为隐式任务区，
-  // 让其中的 task checkbox 能被收进惰性创建的隐式 Wave（见下方 taskMatch 分支）。
-  let inImplicitTaskSection = false
-
-  for (const line of lines) {
-    const waveMatch = line.match(/^#+\s*Wave\s+(\d+)/i)
-    if (waveMatch) {
-      currentWave = { index: parseInt(waveMatch[1]), tasks: [] }
-      currentTask = null
-      inImplicitTaskSection = false
-      waves.push(currentWave)
-      continue
-    }
-
-    // 任何非 Wave 的标题行：
-    //   1) 退出当前显式 Wave 段，避免「## 自检」段里的 - [x] checkbox 被误当 task 定义解析
-    //      （导致 Contract 校验报 task id 重复/不连续，详见 docs/sillyspec/plan-postcheck-self-check-checkbox-false-dup.md）
-    //   2) 识别 light/none 的 `## Tasks`/`## 任务` 任务区（无 Wave 标题），置位隐式任务区标志
-    const headingMatch = line.match(/^#+\s+(.+?)\s*$/)
-    if (headingMatch) {
-      currentWave = null
-      currentTask = null
-      const headingText = headingMatch[1].trim().toLowerCase()
-      inImplicitTaskSection = /^(tasks?|任务)$/.test(headingText)
-      continue
-    }
-
-    const taskMatch = line.match(/^[-*]\s*\[[ x]\]\s*(.+)/)
-    if (taskMatch) {
-      const taskNoMatch = taskMatch[1].match(/\btask-(\d+)\b/i)
-      // full plan.md：task 必须在显式 Wave 段内（currentWave 非 null），正常收容。
-      // light/none plan.md（无 Wave 标题，任务在 `## Tasks` 下）：在隐式任务区内，遇含
-      // task-XX 编号的 checkbox 时惰性创建隐式 Wave 收容，否则 validatePlanForExecute 会报
-      // "没有找到 checkbox task"。详见 docs/sillyspec/plan-light-needs-wave-heading.md
-      // 不收的情况：非任务区（## 自检/## 验收 等）的 checkbox，或任务区内无 task-XX 编号的 checkbox。
-      if (!currentWave) {
-        if (!inImplicitTaskSection || !taskNoMatch) continue
-        const nextIndex = waves.length === 0 ? 1 : (waves[waves.length - 1].index || waves.length) + 1
-        currentWave = { index: nextIndex, tasks: [], implicit: true }
-        currentTask = null
-        waves.push(currentWave)
-      }
-      currentTask = {
-        index: taskNoMatch ? parseInt(taskNoMatch[1], 10) : null,
-        name: taskMatch[1].trim(),
-        file: '',
-        steps: '',
-        reference: ''
-      }
-      // 兼容旧格式：任务名后跟 (文件路径)
-      const fileMatch = taskMatch[1].match(/\(([^)]+)\)$/)
-      if (fileMatch) {
-        currentTask.file = fileMatch[1]
-        currentTask.name = taskMatch[1].replace(/\([^)]+\)$/, '').trim()
-      }
-      currentWave.tasks.push(currentTask)
-      continue
-    }
-
-    // 解析子行信息（修改/参考/步骤）
-    if (currentTask) {
-      const modMatch = line.match(/^\s+-\s*修改:\s*(.+)/)
-      if (modMatch) { currentTask.file = modMatch[1].trim(); continue }
-
-      const refMatch = line.match(/^\s+-\s*参考:\s*(.+)/)
-      if (refMatch) { currentTask.reference = refMatch[1].trim(); continue }
-
-      const stepMatch = line.match(/^\s+-\s*步骤:/)
-      if (stepMatch) { currentTask.steps = line.replace(/^\s+-\s*步骤:\s*/, '').trim(); continue }
-
-      // 步骤续行（数字开头的子步骤）
-      if (currentTask.steps && line.match(/^\s+\d+\./)) {
-        currentTask.steps += '\n' + line.trim()
-      }
-    }
-  }
-
-  return waves
-}
-
-/**
- * 同步判定派发后端模式（不发网络，零回归关键）— task-07
- *
- * stub 下 isPathASupported()=false → 有配置也只 local-fallback（加提示），不注入完整 SillyHub 指令。
- * 现有测试套件不设 SILLYHUB_MCP_URL/TOKEN 且无 local.yaml mcp 段 → readMcpConfig 返回 null → 默认 'local' → buildWavePrompt 不注入派发段，
- * 输出与改前字节一致（零回归，D-005）。
- *
- * @returns {'local' | 'local-fallback' | 'sillyhub'}
- *   - local：无 MCP 配置（零回归，与现状一致）
- *   - local-fallback：有配置但路径A 未落地（isPathASupported()=false），派发仍走 Local + 短提示
- *   - sillyhub：有配置且路径A 落地（isPathASupported()=true），注入完整 SillyHub 派发指令
- */
-export function getDispatchMode() {
-  const hasConfig = !!readMcpConfig(process.cwd())
-  if (!hasConfig) return 'local'
-  return isPathASupported() ? 'sillyhub' : 'local-fallback'
-}
-
-/**
- * 解析 task 卡的 repo 归属（W3 task-08，D-012）。
- * 读 changeDir/tasks/task-<num>.md 的 frontmatter `repo:` 字段；缺省/无卡/'main' → 'main'。
- * 单仓 change（无 repo: 字段）恒返 'main'，零回归。
- *
- * @param {{ index?: number, name?: string }} task - wave.tasks 元素
- * @param {string|null} changeDir - change 目录绝对路径
- * @returns {string} repoKey，'main' 或 parseRepo 返回值
- */
-function resolveTaskRepo(task, changeDir) {
-  if (!changeDir || !task || task.index == null) return 'main'
-  const num = String(task.index).padStart(2, '0')
-  const taskFile = path.join(changeDir, 'tasks', `task-${num}.md`)
-  if (!existsSync(taskFile)) return 'main'
-  try {
-    const content = readFileSync(taskFile, 'utf8')
-    const repo = parseRepo(content)
-    return repo || 'main'
-  } catch {
-    return 'main'
-  }
-}
-
-/**
- * 把 base_commit 锡点写入 task 卡 frontmatter（W3 task-08，D-010）。
- * 派发跨仓 task 前 CLI 实时 git rev-parse HEAD 落盘——锁定子代理起改的 base 锚点，
- * 防止同 Wave 多 task 改同一跨仓仓时 HEAD 推进致 diff 范围漂移（design §5.3 约束① / R-01）。
- *
- * 策略：幂等写——frontmatter 有 base_commit 行则就地替换，无则紧跟 repo 行后插入（
- * 无 frontmatter 时整段创建）。仅改 frontmatter 不动正文。已存在相同值不重复写。
- *
- * @param {string} taskFilePath - task-NN.md 绝对路径
- * @param {string} baseCommit - 跨仓仓 HEAD sha
- * @returns {boolean} 是否实际写入（false = 文件不存在 / 写失败 / 值未变）
- */
-function writeBaseCommitToTaskCard(taskFilePath, baseCommit) {
-  if (!taskFilePath || !baseCommit) return false
-  if (!existsSync(taskFilePath)) return false
-  let content
-  try {
-    content = readFileSync(taskFilePath, 'utf8')
-  } catch {
-    return false
-  }
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
-  if (!fmMatch) return false
-  const fm = fmMatch[1]
-  const baseLineRe = /^base_commit:\s*.*$/m
-  let newFm
-  if (baseLineRe.test(fm)) {
-    const existing = (fm.match(baseLineRe) || [''])[0]
-    if (existing === `base_commit: ${baseCommit}`) return false // 值未变，幂等跳过
-    newFm = fm.replace(baseLineRe, `base_commit: ${baseCommit}`)
-  } else {
-    // 紧跟 repo 行后插入（与 D-010 协议同源顺序 repo→base_commit→head_commit）
-    const repoLineRe = /^repo:\s*.*$/m
-    const anchor = `base_commit: ${baseCommit}\n`
-    if (repoLineRe.test(fm)) {
-      newFm = fm.replace(repoLineRe, m => m + '\n' + anchor.trimEnd())
-    } else {
-      // 无 repo 行：插到 frontmatter 首部（frontmatter 首字段）
-      newFm = anchor.trimEnd() + '\n' + fm
-    }
-  }
-  const newContent = content.replace(/^---\n[\s\S]*?\n---/, `---\n${newFm}\n---`)
-  if (newContent === content) return false
-  try {
-    writeFileSync(taskFilePath, newContent)
-    return true
-  } catch {
-    return false
-  }
-}
-
-/**
- * 为 Wave 生成 prompt（强制子代理执行）
- *
- * W3 task-08（D-012 per-task workdir）：签名加可选 `ctx`（MultiRepoContext）参数。
- * - 无 ctx（单仓 change / 旧调用方）→ 退化为单 worktreePath 单值 worktreeSection（零回归）
- * - 有 ctx → 按 task 逐个解析 repo 归属，构造 per-task workdir 多值表，跨仓 task 派发前
- *   落 base_commit 锡点（D-010），注入跨仓 task commit 指引 + head_commit 落盘指引。
- * 同 Wave 允许主仓+跨仓 task 混合（各独立 Task 调用各传 workdir，不强制同 Wave 同 repo）。
- */
-export function buildWavePrompt(wave, waveIndex, changeDir, worktreePath, options = {}) {
-  const ctx = options.ctx || null
-  // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
-  let contractInjection = ''
-  let prototypeInjection = ''
-  if (changeDir) {
-    try {
-      const planFile = path.join(changeDir, 'plan.md')
-      if (existsSync(planFile)) {
-        const planContent = readFileSync(planFile, 'utf8')
-        // 收集本 wave 所有 task（端点注入与字段注入共用）
-        const waveTasks = wave.tasks.map((t, ti) => {
-          const num = String(t.index || (ti + 1)).padStart(2, '0')
-          return `task-${num}`
-        })
-
-        // 1) 端点级契约（provider/consumer via buildContractMatrix）
-        const contracts = buildContractMatrix(planContent, changeDir)
-        const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
-        if (relevantContracts.length > 0) {
-          contractInjection = `
-### API Contract Matrix
-本 Wave 存在前端/后端跨 task 契约：
-${relevantContracts.map(c => `- **${c.consumer}** 消费 **${c.provider}** 产出的 API`).join('\n')}
-`
-          for (const taskName of waveTasks) {
-            const injection = buildConsumerInjection(changeDir, path.join(changeDir, '..', '..'), taskName, contracts)
-            if (injection) {
-              contractInjection += `
-### 子代理 ${taskName} 的端点契约注入
-为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
-
-<contract-injection>
-${injection}
-</contract-injection>
-`
-            }
-          }
-        }
-
-        // 2) 字段级契约（expects_from ↔ provides）
-        // 命中「provider 漏字段、consumer fallback 编造 → 运行时 403/500」这类 bug：
-        // 把 consumer 期望字段 vs provider 承诺字段显式注入子代理 prompt
-        for (const taskName of waveTasks) {
-          const fi = buildContractFieldInjection(changeDir, taskName)
-          if (fi) {
-            contractInjection += `
-### 子代理 ${taskName} 的字段契约注入
-为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
-
-<contract-field-injection>
-${fi}
-</contract-field-injection>
-`
-          }
-        }
-      }
-    } catch (e) {
-      // 契约注入是 best-effort：失败不阻断 execute，只记录
-      console.warn(`  ⚠️ 契约注入跳过: ${e?.message || e}`)
-    }
-
-    // 原型引用注入：brainstorm 阶段的 HTML 原型（确认过的布局/组件/交互），
-    // 让 execute 实现前端/UI task 时参考原型，而非凭 design 文字重新发明（避免原型浪费）。
-    try {
-      const prototypes = readdirSync(changeDir).filter(f => /^prototype-.*\.html$/i.test(f))
-      if (prototypes.length > 0) {
-        const protoRelDir = `.sillyspec/changes/${path.basename(changeDir)}`
-        prototypeInjection = `
-### 📐 原型参考（brainstorm 可视化确认）
-本次变更有 HTML 原型（brainstorm 阶段确认过的视觉/交互），实现前端/UI 相关 task 时参考：
-${prototypes.map(p => `- \`${path.join(protoRelDir, p)}\``).join('\n')}
-
-照原型的布局/组件/交互实现，不要凭 design.md 文字重新发明。纯后端/无 UI 的 task 忽略本节。
-`
-      }
-    } catch {}
-  }
-
-  // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
-  const taskSummary = wave.tasks.map((t, ti) => {
-    const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
-    const taskRelPath = changeDir
-      ? `.sillyspec/changes/${path.basename(changeDir)}/tasks/task-${taskNum}.md`
-      : `task-${taskNum}.md`
-    const fileInfo = t.file ? ` (${t.file})` : ''
-    return `task-${taskNum}: ${t.name}${fileInfo} → ${taskRelPath}`
-  }).join('\n')
-
-  const taskList = wave.tasks.map((t, ti) => {
-    const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
-    let s = `- [ ] ${t.name}`
-    if (t.file) s += ` (${t.file})`
-    return s
-  }).join('\n')
-
-  // ── per-task workdir 解析（W3 task-08，D-012）──
-  // 无 ctx（单仓 change）→ 全 task workdir=主仓 worktreePath，沿用旧单值逻辑（零回归）。
-  // 有 ctx → 按 task 卡 repo: 字段逐个解析：主仓 task workdir=主仓 worktreePath，跨仓 task
-  // workdir=ctx.resolve(repo).worktreePath（跨仓仓根）。同 Wave 允许主仓+跨仓混合。
-  const taskRepos = wave.tasks.map(t => ctx ? resolveTaskRepo(t, changeDir) : 'main')
-  const hasCrossRepoWave = ctx ? taskRepos.some(r => r !== 'main') : false
-
-  // per-task workdir 映射（用于多值 worktreeSection + 跨仓 commit 指引）
-  // 无 ctx 或无跨仓 task → 不构造（沿用旧单值 worktreePath 注入）
-  let perTaskWorkdirs = null
-  let crossRepoCommitSection = ''
-  let baseCommitWrites = [] // [{ taskNum, repo, taskFile, written }] 跨仓 task base 锡点落盘记录
-  if (ctx && hasCrossRepoWave) {
-    perTaskWorkdirs = wave.tasks.map((t, ti) => {
-      const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
-      const repo = taskRepos[ti]
-      const entry = ctx.resolve(repo)
-      const workdir = entry ? entry.worktreePath : (worktreePath || '')
-      return { taskNum, repo, workdir }
-    })
-
-    // D-010 跨仓 task base 锡点：派发前实时 git rev-parse HEAD 落 task 卡 base_commit
-    // 仅对跨仓 task（repo≠'main'）落盘，主仓 task 锚 meta.baseHash（MultiRepoContext 已处理）
-    for (const item of perTaskWorkdirs) {
-      if (item.repo === 'main') continue
-      const entry = ctx.resolve(item.repo)
-      if (!entry) continue
-      const baseCommit = gitQuiet(entry.gitDir, ['rev-parse', 'HEAD'])
-      if (!baseCommit) continue // git 不可达已由 MultiRepoContext 构造时 fail-closed 拦截，此处置防御
-      const taskFile = changeDir
-        ? path.join(changeDir, 'tasks', `task-${item.taskNum}.md`)
-        : null
-      const written = taskFile ? writeBaseCommitToTaskCard(taskFile, baseCommit) : false
-      baseCommitWrites.push({ taskNum: item.taskNum, repo: item.repo, taskFile, written, baseCommit })
-    }
-
-    // 跨仓 task commit 指引 + head_commit 落盘指引（D-010 回收时机）
-    const crossLines = perTaskWorkdirs
-      .filter(i => i.repo !== 'main')
-      .map(i => `- task-${i.taskNum} → repo \`${i.repo}\`，workdir=\`${i.workdir}\``)
-      .join('\n')
-    crossRepoCommitSection = `
-### 跨仓 task 派发与双锡点（必须严格遵守）
-
-本 Wave 含跨仓 task（直接改跨仓仓主干，**不经主仓 worktree**）：
-
-${crossLines}
-
-**派发跨仓 task 前（base 锡点，CLI 已在 prompt 构造时落盘）：**
-- 跨仓 task 卡 frontmatter 的 \`base_commit\` 已由 CLI 实时 \`git -C <跨仓仓根> rev-parse HEAD\` 锁定（base 锡点，约束①）。子代理在此 HEAD 上改+commit，不受同 Wave 其他 task 推进 HEAD 影响。
-
-**回收跨仓 task review 前（head 锡点，你必须在子代理完成后落盘）：**
-- 跨仓 task 子代理完成 commit 后、写 review.json / 勾选 checkbox **之前**，你必须运行 \`git -C <跨仓仓根> rev-parse HEAD\` 把结果写入该 task 卡 frontmatter \`head_commit:\` 字段（与 \`base_commit:\` 同源 frontmatter 锡点写入）。
-- review.json 的 \`base\` 取 task 卡 \`base_commit\`、\`head\` 取 task 卡 \`head_commit\`（**非瞬时 HEAD**），锁 diff 范围不漂移。
-
-**跨仓 task 子代理 prompt 必须注入：**
-> 该 task 改的是 \`<repo>\` 仓，workdir=\`<跨仓仓根>\`。**直接在该仓主干工作区改+commit（git add + git commit 到该仓主干），不经主仓 worktree、不建分支。** commit 到该仓主干即落盘，apply 阶段对跨仓 task 为 no-op（design §5.4 G1）。
-`
-  }
-
-  // worktreeSection：无 ctx / 无跨仓 task → 旧单值（零回归）；有 ctx 含跨仓 task → per-task 多值表
-  let worktreeSection
-  if (ctx && hasCrossRepoWave && perTaskWorkdirs) {
-    const workdirLines = perTaskWorkdirs.map(i =>
-      `  - task-${i.taskNum} (repo: ${i.repo}) → workdir: "${i.workdir}"`
-    ).join('\n')
-    worktreeSection = `
-### 工作目录（必须严格遵守，per-task）
-
-调用 Task 工具启动子代理时，**workdir 参数是强制必传的**，且本 Wave 内不同 task 的 workdir 不同（主仓 task vs 跨仓 task）。
-
-**per-task workdir 表（每个子代理按其 task 对应的 workdir 启动）：**
-
-${workdirLines}
-
-不传 workdir 或传错 workdir 会导致：主仓 task 写到跨仓仓 / 跨仓 task 写到主仓 worktree，破坏隔离与 apply 归属。
-
-\`\`\`json
-{
-  "subagent_type": "general",
-  "workdir": "<按上方 per-task 表选>",
-  "prompt": "在此编写任务描述..."
-}
-\`\`\`
-
-### 注意
-蓝图文件（tasks.md / design.md / proposal.md / requirements.md / tasks/task-XX.md）在主工作区 .sillyspec/changes/<change>/ 下，它们不在跨仓仓也不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree / 跨仓仓路径下。
-`
-  } else {
-    worktreeSection = (worktreePath)
-      ? `
-### 工作目录（必须严格遵守）
-
-调用 Task 工具启动子代理时，**workdir 参数是强制必传的**。
-不传 workdir 会导致子代理把文件写到主工作区而非 worktree，破坏隔离。
-
-\`\`\`json
-{
-  "subagent_type": "general",
-  "workdir": "${worktreePath}",
-  "prompt": "在此编写任务描述..."
-}
-\`\`\`
-
-### 注意
-蓝图文件（tasks.md / design.md / proposal.md / requirements.md）在主工作区 .sillyspec/changes/<change>/ 下，它们可能不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree 路径下。
-`
-      : ''
-  }
-
-  // ── 派发后端段注入（task-07，D-006 / D-007 / D-008 接入）──
-  // 同步判定（不发网络，零回归关键）：local（无 MCP 配置）→ dispatchSection='' → 本 prompt 与改前
-  // 字节一致；sillyhub（配置 + 路径A 落地）→ 注入完整 SillyHub 派发指令（一 Wave 一 mission /
-  // dispatch_worker / 轮询 list_workers / 超时 kill lease 防双写 / 回收 + Local 兜底）；local-fallback
-  // （配置但路径A 未落地）→ 短提示，派发仍走 Local（与默认行为一致）。worktreePath 为空时不注入
-  // （无 worktree 无谓派发指令）。测试/调用方可经 options.dispatchMode 覆盖，避免 env 污染。
-  const dispatchMode = options.dispatchMode || getDispatchMode()
-  let dispatchSection = ''
-  if (worktreePath && dispatchMode === 'sillyhub') {
-    // 路径A 落地后：注入完整 SillyHub 派发指令（renderDispatchInstruction 已含 Local 兜底全文）
-    const contract = {
-      brief: '本 Wave 任务（见上方任务摘要与 tasks/task-XX.md）',
-      worktreePath,
-      branch: options.branch || '<未提供 branch>',
-      allowedPaths: [],
-      readOnly: false,
-      runId: '{EXECUTE_RUN_ID}',   // 占位符，prompt.js 注入阶段替换为真实 run id
-    }
-    const { instruction } = renderDispatchInstruction(contract, { available: true })
-    dispatchSection = `\n### 派发后端：SillyHub MCP（探测可用，一 Wave 一 mission）\n\n本次 Wave 派发经 SillyHub MCP。按以下派发指令执行（含 create_mission / dispatch_worker / 轮询 list_workers / 超时 kill lease 防双写 / 回收 + Local 兜底）：\n\n${instruction}\n`
-  } else if (worktreePath && dispatchMode === 'local-fallback') {
-    // 有 MCP 配置但路径A 未落地：加短提示，派发仍走 Local（与默认行为一致）
-    dispatchSection = `\n### 派发后端提示：SillyHub MCP 已配置但路径A 未落地\n\n检测到 local.yaml mcp 段或 env 配置，但 SillyHub \`dispatch_worker\` 尚不支持 \`worktree_path\`（路径A 跨仓未落地）。本次派发走 Local（本机 Agent tool），与默认行为一致——上方「执行方式」与「工作目录」段适用。\n`
-  }
-  // dispatchMode === 'local'（无配置）或 worktreePath 为空 → dispatchSection = '' → 输出与改前字节一致（零回归）
-
-  return `## Wave ${waveIndex}: 执行以下任务
-
-## 执行方式（必须严格遵守）
-
-**每个任务必须由独立子代理执行，你不要自己写代码。**
-
-你的角色是调度者 + 审查者：
-1. 为每个任务启动一个子代理（Agent tool），同 Wave 内可并行
-2. 子代理完成后审查结果
-3. 勾选 plan.md 中的 checkbox
-4. 记录改动文件和测试结果
-
-${worktreeSection}${crossRepoCommitSection}${dispatchSection}
-### 任务摘要（按需读取完整蓝图）
-为每个任务启动子代理时，**只需告知任务目标和蓝图文件路径，让子代理按需读取**：
-
-${taskSummary}
-
-子代理 prompt 要点：
-1. 任务目标（简短描述）
-2. 蓝图文件路径（让子代理自行读取详情）
-3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowed_paths
-4. 如存在模块文档（.sillyspec/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流
-5. 任务含测试代码时，把下方「测试用例设计」整段复制进子代理 prompt，要求子代理按此设计测试用例
-
-{{include: testcase-design}}
-
-### Wave 开始前
-1. 读取 design.md 的「非目标」与「兼容策略」章节（如存在），确保子代理不超范围、不破坏旧逻辑
-2. 读取 plan.md 了解全局任务划分和依赖关系
-3. 确认本 Wave 的输入/输出契约（前置 Wave 产出了什么，本 Wave 需要消费什么）
-4. 检查前置 Wave 的产出是否完整（文件是否存在、测试是否通过）
-5. **上下文分层加载**：
-   - 🔥 热上下文：design.md 非目标/兼容策略 + 当前 Wave 任务（必须加载）
-   - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
-   - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
-
-### 中断续跑（如曾中断恢复）
-execute 按 Wave 持久化进度，task 级进度靠 plan.md checkbox 勾选。若本 Wave 曾因 429/API 配额/崩溃中断：
-- plan.md 中**已勾选 \`- [x]\` 的 task 已完成，跳过不重跑**（子代理也可能在完成前中断，重跑前先确认该 task 产出文件是否完整）
-- 用 \`sillyspec status\` 查当前进度，重新 \`sillyspec run execute\` 会回到当前 Wave step 继续，**不要从零重置或重跑已完成 Wave**
-- 本 Wave 已完成但不完整（产出缺文件）的 task 补做，不牵连其他 task
-
-${contractInjection}${prototypeInjection}
-### 本 Wave 任务
-${taskList}
-
-### 调度要求
-1. **同一 Wave 内的任务必须并行启动子代理，禁止串行等待。** Wave 的定义就是"无依赖、可并行"，不要自行分析依赖关系。如果有依赖应该在 plan.md 的不同 Wave 中。
-2. **Reverse Sync**：子代理报告实现与 design.md 不一致时，先检查是代码错了还是文档有遗漏
-3. **不要频繁编译！** 编译很慢，只在以下情况运行：
-   - 写了大量代码后需要验证语法正确性
-   - 最后一个 Wave 完成后做一次全量编译验证
-   - 用户明确要求编译时
-4. 每个任务完成后：
-   - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
-   - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
-   - 记录改动文件和测试结果
-5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
-
-### Task Review Gate（必须执行，不可跳过）
-
-每个子代理完成后、勾选 checkbox **之前**，你必须创建 task review。
-
-**操作步骤：**
-1. 读取当前 task 的 git diff（从 task 开始到完成的变更）
-2. 对照 plan.md 中该 task 的描述和 tasks/task-XX.md（如果存在）检查实现是否符合要求
-3. 写入 review.json 文件
-4. **只有 review.json 写入成功后，才允许勾选 plan.md 中的 checkbox**
-
-**review.json 路径：**
-
-task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX/review.json
-
-本 execute run 的固定 ID 是：{EXECUTE_RUN_ID}
-**所有 task 的 review.json 必须使用这个 ID，不要自行创建新目录。**
-
-**review.json 必填字段：**
-
-{ "name_zh": "任务评审", "schemaVersion": {REVIEW_SCHEMA_VERSION}, "task": "task-XX", "base": "<git-base-commit>", "head": "<git-head-commit>",
- "changedFiles": ["src/foo.js"], "specVerdict": "pass|fail|cannot_verify",
- "qualityVerdict": "pass|fail|cannot_verify", "reviewerNotes": "评审说明",
- "requiredEvidence": [] }
-
-**评审铁律：**
-- 不信任 implementer 自报结果，对照 diff 和 task brief 验证
-- 只看当前 task 的 diff，不做全仓库漫游审查
-- \`cannot_verify\` 只在确实无法验证且有待补充证据时使用，且 requiredEvidence 必须非空
-- \`sillyspec run execute --done\` 会校验所有 task 的 review.json，缺失或 fail 会阻断完成
-
-### module-impact.md 更新（主代理在本 Wave 所有 task 完成后汇总）
-本 Wave 内所有 task 子代理完成、review.json 写好后，**由你（主代理/调度者）**汇总本 Wave 的实际代码变更，更新 {SPEC_ROOT}/changes/<change>/module-impact.md（plan 阶段已生成首版）：
-- 基于本 Wave 各 task 的实际 git diff（不是计划）+ {SPEC_ROOT}/docs/<project>/modules/_module-map.yaml 对照
-- 更新受影响模块的影响类型/说明（实际改动可能与 plan 首版预估不同，据实修正）
-- **不由各 task 子代理分别改**（同 Wave 并行子代理改同一文件会互相覆盖）——只由主代理在 Wave 收尾统一更新一次
-- 无 _module-map.yaml 时跳过模块匹配，仅按文件清单更新 unmapped 部分
-这是可选更新（不阻断 execute 完成），但保持 module-impact 与实际变更一致利于 verify 核对与 archive 终审。
-
-### 完成后
-1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
-   - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
-   - 将端点清单写入 {SPEC_ROOT}/.runtime/contract-artifacts/<task-name>/endpoints.json
-   - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
-`
-}
-
-/**
- * 动态构建 execute 步骤列表
- * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave
- * @param {{ worktreePath?: string, noWorktree?: boolean }} options
- * @returns {Array} 步骤列表
- */
-export function buildExecuteSteps(planFilePath = null, options = {}) {
-  const noWorktree = !!options.noWorktree
-  let waves
-  let changeDir = null
-
-  if (planFilePath && existsSync(planFilePath)) {
-    const planContent = readFileSync(planFilePath, 'utf8')
-    // Plan → Execute 契约由 plan 阶段完成时的 postcheck 把关（run.js completeStep），
-    // 此处只负责解析 waves，避免 buildExecuteSteps 与进程退出耦合。
-    waves = parseWavesFromPlan(planContent)
-    changeDir = path.dirname(planFilePath)
-  }
-
-  // 没解析出 Wave（plan 不存在或不含可识别 task）→ 默认 3 Wave（向后兼容）
-  if (!waves || waves.length === 0) {
-    waves = []
-    for (let i = 1; i <= 3; i++) {
-      waves.push({ index: i, tasks: [{ name: `默认任务 ${i}`, file: 'TBD' }] })
-    }
-  }
-
-  // 尝试获取 worktree 路径（可能由前缀步骤创建）
-  const worktreePath = options.worktreePath || null
-
-  // W3 task-08：ctx 由 execute 启动入口（task-09）透传，进程级单例贯穿 execute/apply/verify
-  // （D-013）。缺省=null → buildWavePrompt 退化为单仓单 worktreePath（零回归）。
-  const ctx = options.ctx || null
-
-  const waveSteps = waves.map((wave, i) => ({
-    name: `Wave ${i + 1} 执行`,
-    mode: 'implementation',
-    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath, { dispatchMode: options.dispatchMode, branch: options.branch, ctx }),
-    outputHint: `Wave ${i + 1} 执行结果`,
-    optional: false
-  }))
-
-  return [...fixedPrefix, ...waveSteps, ...acceptanceSteps, ...fixedSuffix]
-}
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
+import path from 'path'
+import { buildContractMatrix, buildConsumerInjection, buildContractFieldInjection } from '../contract-matrix.js'
+import { getRule } from '../stage-contract-spec.js'
+import { renderDispatchInstruction } from '../dispatch/strategy.js'
+import { isPathASupported } from '../dispatch/backends/sillyhub-mcp.js'
+import { readMcpConfig } from '../sillyhub-mcp/config.js'
+import { gitQuiet } from '../git-helper.js'
+import { parseRepo } from './plan-postcheck.js'
+
+/**
+ * 校验 plan.md 是否满足 execute 执行契约
+ * @param {string} planContent - plan.md 文件内容
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], tasks: object[], waves: object[] }}
+ */
+export function validatePlanForExecute(planContent) {
+  const errors = []
+  const warnings = []
+
+  if (!planContent || !planContent.trim()) {
+    return { ok: false, errors: ['plan.md 内容为空'], warnings, tasks: [], waves: [] }
+  }
+
+  const waves = parseWavesFromPlan(planContent)
+
+  // 检查 0: Wave 编号带字母后缀（如 "## Wave 2b"）→ 显式报错（坑 plan-wave-letter-suffix）
+  // 解析正则 ^#+\s*Wave\s+(\d+) 不锚定结尾，"Wave 2b" 会被 parseInt 截断成 Wave 2 静默收容，
+  // 与显式 Wave 2 合并为同一 Wave 强制并行——串行意图静默失效且无任何提示，排查到源码才明白。
+  const letterSuffixWaves = [...planContent.matchAll(/^#+\s*Wave\s+(\d+)([a-z])(?![a-z0-9])/gim)]
+  for (const m of letterSuffixWaves) {
+    errors.push(
+      `Wave 编号带字母后缀：${m[0].trim()}（"${m[1]}${m[2]}"）不被支持。` +
+      `解析器只认纯数字编号（"## Wave N"），字母后缀会被截断为 "${m[1]}" 与显式 Wave ${m[1]} 静默合并强制并行。` +
+      `解法：改顺序纯数字编号（Wave 3/4…）或并入相邻 Wave`
+    )
+  }
+
+  // 收集所有 task
+  const allTasks = []
+  for (const wave of waves) {
+    for (const task of wave.tasks) {
+      allTasks.push(task)
+    }
+  }
+
+  // 检查 1: 至少有一个 checkbox task
+  if (allTasks.length === 0) {
+    // 诊断根因（坑 plan-md-format-contract-hidden）：笼统报"没有找到 checkbox task"逼 agent 试错。
+    // 区分：无 Wave/Tasks 段 / Wave 标题格式不对 / task 用 ### 标题 / checkbox 被非 Wave 标题打断。
+    const diags = diagnoseNoTaskRootCause(planContent)
+    errors.push('plan.md 中没有找到 checkbox task（格式: "- [ ] task-XX: 任务名"）')
+    for (const d of diags) errors.push(`  诊断：${d}`)
+    return { ok: false, errors, warnings, tasks: allTasks, waves }
+  }
+
+  // 检查 2: task id 唯一性
+  const idCounts = {}
+  for (const task of allTasks) {
+    if (task.index != null) {
+      const key = `task-${task.index}`
+      idCounts[key] = (idCounts[key] || 0) + 1
+    }
+  }
+  for (const [id, count] of Object.entries(idCounts)) {
+    if (count > 1) {
+      errors.push(`task id 重复: ${id} 出现 ${count} 次`)
+    }
+  }
+
+  // 检查 3: task id 连续性（从 1 开始）
+  const ids = allTasks
+    .map(t => t.index)
+    .filter(i => i != null)
+    .sort((a, b) => a - b)
+  if (ids.length > 0) {
+    const expected = Array.from({ length: ids.length }, (_, i) => ids[0] + i)
+    // 只检查以 task-01 起始的情况（常见模式）
+    if (ids[0] === 1) {
+      for (let i = 0; i < ids.length; i++) {
+        if (ids[i] !== i + 1) {
+          errors.push(getRule('plan.task-id-continuity').failMessage.replaceAll('${expected}', String(i + 1).padStart(2, '0')).replaceAll('${actual}', String(ids[i]).padStart(2, '0')))
+          break
+        }
+      }
+    }
+  }
+
+  // 检查 4: task name 非空
+  for (const task of allTasks) {
+    if (!task.name || !task.name.trim()) {
+      errors.push(`task-${String(task.index || '?').padStart(2, '0')}: 任务名为空`)
+    }
+  }
+
+  // 检查 5: task 无 id 的 warning（不限制只在有 id 时检查）
+  for (const wave of waves) {
+    for (const task of wave.tasks) {
+      if (task.index == null) {
+        warnings.push(`Wave ${wave.index}: task "${task.name}" 没有 task id（建议格式 task-XX: 名称）`)
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings, tasks: allTasks, waves }
+}
+
+export const definition = {
+  name: 'execute',
+  title: '波次执行',
+  description: '子代理并行 + 强制 TDD + 两阶段审查',
+  steps: [] // 动态构建，由 buildExecuteSteps() 生成
+}
+
+// 固定前缀步骤定义
+const fixedPrefix = [
+  {
+    name: '进度确认',
+    migratedFrom: ['状态检查'],
+    prompt: `检查当前进度，确认可以执行 execute。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
+
+### 操作
+1. 运行 \`sillyspec progress show\`
+2. 确认 currentStage 为 execute
+3. 如果不是 → 检查是否有未完成的 tasks.md
+4. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
+
+### 输出
+当前状态 + 执行范围确认`,
+    outputHint: '当前状态 + 执行范围',
+    optional: false
+  },
+  {
+    name: '加载上下文',
+    prompt: `加载计划、设计和代码库上下文。
+
+### 操作
+1. 读取 tasks.md（执行计划）
+2. 读取 design.md（技术方案）
+3. 读取 CONVENTIONS.md、ARCHITECTURE.md
+4. 读取 local.yaml（构建命令）；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+5. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）
+
+### 模块文档加载
+6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+7. 根据 plan.md 中的任务文件路径匹配 _module-map.yaml 中的模块
+8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+9. 实现代码时遵循模块文档中描述的接口约定、数据流和依赖关系
+10. **利用模块索引快速定位源码**：
+    - 用 entrypoints 字段直接找到模块对外 API 的源码位置
+    - 用 main_symbols 字段找到核心类/函数的定义位置
+    - 子代理优先读模块卡片理解语义，再读 entrypoints/main_symbols 对应的源码
+
+### 符号影响面扩展检查
+11. **符号影响面扫描**（Critical — execute 前必做）：
+    - 读取所有 tasks/task-NN.md，提取每个任务涉及的修改文件
+    - 对每个修改文件，检查是否涉及以下变更类型：
+      - class 构造函数参数变更（新增/删除/修改参数）
+      - 接口（interface）定义变更
+      - DTO / 类型定义变更
+      - API client 方法签名变更
+      - 函数/方法签名变更（参数增删改）
+    - 如果涉及上述变更类型，执行调用点搜索：
+      \`\`\`bash
+      rg "new ClassName\(" src/
+      rg "ClassName\(" src/
+      rg "methodName\(" src/
+      rg "import.*from.*filePath" src/
+      \`\`\`
+    - 将搜索到的调用点与 plan.md 和 tasks/task-NN.md 的 allowed_paths 对比
+    - **发现调用点不在任何 task 的 allowed_paths 中 → 直接阻断 execute**
+    - 报告：列出每个受影响符号、调用点位置、是否在任务范围内
+    - 如果调用点不在范围内但任务明确写了"不改原因"，记录但不阻断
+
+### 输出
+已加载的上下文摘要（含模块文档 + 源码锚点）`,
+    outputHint: '上下文摘要',
+    optional: false
+  },
+  {
+    name: '确认 worktree 路径',
+    prompt: `确认当前 worktree 状态，提取隔离路径。
+
+### 操作
+1. 运行 \`sillyspec worktree meta <change-name>\` 读取 meta.json
+2. 从输出中提取 worktreePath、branch、mode 字段
+3. 确认 worktree 目录存在（如果是 worktree/native-worktree 模式）
+4. **确认工具链可用**：worktree 内项目工具链（lint/format/test 二进制，如 ruff / prettier / uv）可能不全——对本次会用到的工具先跑一次 \`--version\` 确认；缺失则按项目方式安装（Python 项目 \`uv tool install ruff\` / \`uv sync\`，Node 项目 node_modules 已由 CLI 链接主仓）。不要等到 commit 才发现二进制不在 PATH 被 hook 拦
+
+### 铁律
+- **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
+- **后续所有子代理的 cwd 必须设为该 worktree 路径**
+- 如果 meta.json 不存在（说明创建失败），停止并报错
+- **不要自行检查 git dirty/uncommitted 状态来判断是否可以进入 worktree，CLI 已自动处理**
+
+### 输出
+worktree 路径 + 分支名 + 模式
+
+`,
+    outputHint: 'worktree 路径 + 分支名 + 模式',
+    optional: false
+  },
+  {
+    name: '确认执行范围',
+    prompt: `解析任务，确认执行范围和确认模式。
+
+### 操作
+1. 从 plan 中解析 Wave 分组和任务列表
+2. 模型档位：若 tasks.md 中某 task 标注了 [model:xxx]，启动该 task 子代理时按标签选模型（档位由 plan 阶段或用户在 tasks.md 显式标注，execute 不在此自动建议——关键词→档位无统一映射，自动建议反而易误导）
+3. 确认频率：默认每个 Wave 完成后展示结果（wave 模式）；用户口头指定按 Task 展示或全自动时遵从
+4. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
+
+### 知识命中报告
+{KNOWLEDGE_HIT_REPORT}
+
+如上所示的知识条目与本次任务相关。请阅读这些条目以获取项目约定和已知模式。
+如无命中条目（Status: no matches），跳过本节。
+
+### 模块文档欠账（CLI 算事实）
+{DOCS_DEBT}
+
+如上为 CLI 用 git 事实算出的本变更触及模块文档欠账（无输出=无欠账或归属数据缺失）。
+欠账处理：Wave 收尾时顺手同步对应模块卡（变更索引追加条目），不必为此停下。
+
+### 铁律
+- **不要询问用户确认频率**，默认 wave 模式；用户已明确口头指定时遵从其指定`,
+    outputHint: 'Wave 分组 + 模型分配',
+    optional: false
+  }
+]
+
+// 全局验收步骤定义
+const acceptanceSteps = [
+  {
+    name: '对照设计检查',
+    mode: 'acceptance',
+    prompt: `对照 design.md 检查所有实现是否与设计一致。
+
+### 执行方式（CLI 按变更规模判定，占位符由 run.js 注入）
+tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
+- tier=self：当前 agent 汇总执行（对照 design.md 逐项检查 + 偏差说明）
+- tier=independent：必须用 Agent tool 启动一个独立的 QA 子代理（独立上下文，不共享实现者的分析），子代理对照 design.md 逐项检查实现一致性并输出 review.json。review.json 产物契约（CLI Stage Review Gate 将硬校验，schema + 完整示例 + docHash 算法如下，照抄改值；reviewedFiles 除主文档 design.md 外可追加 git diff 涉及的源码文件）:
+{REVIEW_JSON_CONTRACT}
+  该 acceptance review 同时覆盖"代码审查"视角（风格/bug/安全/冗余），后续代码审查步骤仅需轻量复审。
+
+### 操作
+1. 读取 design.md（技术方案）
+2. 逐一对照 design.md 中的设计要点与实际代码实现
+3. 检查接口签名、数据结构、模块划分是否一致
+4. 记录偏差项（偏差 ≠ 错误，可能是合理的实现调整）
+
+### 输出
+检查清单：每项设计要点的实现状态 ✅/⚠️/❌ + 偏差说明`,
+    outputHint: '设计对照检查清单',
+    optional: false
+  },
+  {
+    name: '运行测试',
+    mode: 'acceptance',
+    prompt: `运行所有测试，验证代码质量。
+
+### 执行方式
+本步骤由当前 agent 执行，不需要启动独立子代理。
+
+### 操作
+1. 读取 local.yaml 获取构建和测试命令；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+2. 运行测试套件（单元测试、集成测试）
+3. 运行 lint 检查 **+ 格式化**：凡变更涉及的源码，既跑 lint check 也跑 formatter（如 \`ruff format\` / \`prettier --write\` / \`black\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截
+4. 如果有测试失败 → 分析原因，标注是代码问题还是测试本身的问题
+5. 汇总测试结果
+
+### 铁律
+- 长测试/构建/lint 命令必须**前台同步执行**，禁止 run_in_background:true / & / nohup / disown——后台任务易被会话生命周期回收导致中断无果
+
+### 输出
+测试结果摘要：通过/失败/跳过数量 + 失败项分析`,
+    outputHint: '测试结果摘要',
+    optional: false
+  },
+  {
+    name: '代码审查',
+    mode: 'acceptance',
+    prompt: `对本次变更进行代码审查。
+
+### 执行方式
+本步骤由当前 agent 或一个 QA agent 汇总执行，不需要为每个文件启动独立子代理。
+
+### 操作
+1. 检查 git diff 查看所有变更
+2. 审查要点：
+   - 代码风格是否符合 CONVENTIONS.md
+   - 是否有明显的 bug 或安全漏洞
+   - 是否有未处理的 TODO/FIXME
+   - 错误处理是否完善
+   - 是否有冗余代码或可简化的逻辑
+3. 对照 ARCHITECTURE.md 检查架构合规性
+
+### 输出
+审查结果：问题列表（严重程度 + 建议修复方式）+ 总体评价`,
+    outputHint: '代码审查结果',
+    optional: true
+  }
+]
+
+// 固定后缀步骤定义
+const fixedSuffix = [
+  {
+    name: '知识库审阅',
+    prompt: `检查本轮执行产生的新知识。
+
+### 操作
+1. 检查 \`.sillyspec/knowledge/uncategorized.md\` 中待确认条目
+2. 如有 → 提示用户审阅
+3. 用户确认后改为 [已确认]，可归类到专题文件
+
+### 输出
+新知识条目数量 + 审阅提示（或"无新知识"）`,
+    outputHint: '知识条目数量',
+    optional: true
+  },
+  {
+    name: '完成确认',
+    prompt: `所有任务完成后的收尾。
+
+先检查当前 worktree 的隔离模式：
+\`\`\`bash
+node -e "import('./src/worktree.js').then(w => { const wm = new w.WorktreeManager(); const m = wm.getMeta('<change-name>'); console.log(m ? JSON.stringify({mode: m.mode, path: m.worktreePath}) : 'no meta'); })"
+\`\`\`
+
+### 操作（mode = worktree，SillySpec 创建的隔离 worktree）
+
+**自动审计流程（不需要用户确认代码）：**
+
+1. 运行 \`sillyspec worktree assess <change-name>\` 自动风险审计
+2. 系统自动检查：
+   - patch --check 是否通过
+   - 变更是否在 allowed_paths 内
+   - 主工作区是否有未提交 dirty（拦截；已提交推进交 --3way 自动三路合并）
+   - 是否有高风险文件（lockfile/migration/配置/入口）
+   - diff 规模是否异常
+3. 输出 Apply Decision：
+
+\`\`\`
+Worktree Apply Decision
+────────────────────────
+Decision: SAFE | WARNING | BLOCKED
+Changed files: N
+Additions: +N  Deletions: -N
+Risky files: none | <list>
+Action: auto-applied | blocked
+\`\`\`
+
+4. **SAFE** → 自动 \`sillyspec worktree apply <change-name>\` + cleanup
+5. **WARNING** → 自动 apply（有警告但不阻断）+ cleanup
+6. **BLOCKED** → 不 apply，输出原因，提示用户检查：
+   - \`sillyspec worktree diff <change-name>\` 查看具体变更
+   - \`sillyspec worktree cleanup <change-name>\` 丢弃
+7. 建议下一步：\`sillyspec run verify\`
+
+### 操作（mode = native-worktree，用户已有的 linked worktree）
+1. 同上自动审计流程
+2. SAFE/WARNING → \`sillyspec worktree apply <change-name>\`
+3. **不要运行 cleanup**
+4. 输出 Worktree: kept
+5. 建议下一步：\`sillyspec run verify\`
+
+### 操作（mode = in-place-fallback，降级模式无隔离目录）
+1. 展示本次执行摘要（\`git diff\` 查看变更）
+2. 跳过 apply 和 cleanup
+3. 输出 Worktree: none
+4. 建议下一步：\`sillyspec run verify\`
+
+### 输出
+Apply Decision + 下一步建议
+
+### 注意
+- 完成后运行 \`sillyspec run execute --done\` 即可自动推进阶段`,
+    outputHint: 'apply 结果',
+    optional: false
+  }
+]
+
+/**
+ * 诊断 plan.md 无 checkbox task 的根因（坑 plan-md-format-contract-hidden）。
+ * 纯函数：读 planContent 文本，返回诊断提示数组。validatePlanForExecute 无 task 时追加到报错，
+ * 帮 agent 区分 4 条隐性格式契约（Wave 标题字面 / task checkbox / task-XX 编号 / ### 打断 Wave 段）。
+ * @param {string} planContent
+ * @returns {string[]}
+ */
+function diagnoseNoTaskRootCause(planContent) {
+  const diags = []
+  const hasWaveHeading = /^#+\s*Wave\s+\d+/im.test(planContent)         // "## Wave N"（字面）
+  const hasWaveWord = /^#+\s*(wave\s*\d+|w\d+|波次\s*\d+)/im.test(planContent) // 疑似 Wave 标题（含 W1/Wave1/波次1）
+  const hasCheckboxTask = /^[-*]\s*\[[ x]\]\s*task-\d+/im.test(planContent) // "- [ ] task-XX:" checkbox
+  const hasTaskHeading = /^#+\s*task-\d+/im.test(planContent)            // "### task-XX:" 标题（非 checkbox）
+  const hasTasksSection = /^#+\s*(tasks?|任务)\s*$/im.test(planContent)  // "## Tasks" / "## 任务"
+
+  if (!hasWaveHeading && !hasTasksSection) {
+    if (hasWaveWord) {
+      diags.push('Wave 标题格式不对：必须字面 "## Wave N"（Wave + 空格 + 数字），"## W1" / "## Wave1" / "## 波次1" 都不被识别')
+    } else if (hasCheckboxTask) {
+      diags.push('有 task checkbox 但不在 "## Wave N"（full）或 "## Tasks"（light/none）段内——非任务区的 checkbox 不收')
+    } else {
+      diags.push('plan.md 缺任务区：full 需 "## Wave 1" 标题，light/none 需 "## Tasks" 标题')
+    }
+  }
+  if (hasTaskHeading) {
+    diags.push('task 用了 "### task-XX:" 标题（非 checkbox）：标题会打断 Wave 段导致后续 checkbox 全被跳过，请改用 "- [ ] task-XX: 名称"（英文冒号）')
+  }
+  if (hasWaveHeading && hasCheckboxTask && !hasTaskHeading) {
+    diags.push('有 Wave 段也有 checkbox task 但未收容：checkbox 可能落在非任务区（如 "## 自检" 段）或被 "###" 标题打断，请检查 task 是否紧跟在 "## Wave N" 下')
+  }
+  return diags
+}
+
+/**
+ * 从 plan 文件解析 Wave 分组
+ */
+function parseWavesFromPlan(planContent) {
+  const waves = []
+  const lines = planContent.split('\n')
+  let currentWave = null
+  let currentTask = null
+  // light/none plan.md 用 `## Tasks`（无 `## Wave N`）包任务，需识别为隐式任务区，
+  // 让其中的 task checkbox 能被收进惰性创建的隐式 Wave（见下方 taskMatch 分支）。
+  let inImplicitTaskSection = false
+
+  for (const line of lines) {
+    const waveMatch = line.match(/^#+\s*Wave\s+(\d+)/i)
+    if (waveMatch) {
+      currentWave = { index: parseInt(waveMatch[1]), tasks: [] }
+      currentTask = null
+      inImplicitTaskSection = false
+      waves.push(currentWave)
+      continue
+    }
+
+    // 任何非 Wave 的标题行：
+    //   1) 退出当前显式 Wave 段，避免「## 自检」段里的 - [x] checkbox 被误当 task 定义解析
+    //      （导致 Contract 校验报 task id 重复/不连续，详见 docs/sillyspec/plan-postcheck-self-check-checkbox-false-dup.md）
+    //   2) 识别 light/none 的 `## Tasks`/`## 任务` 任务区（无 Wave 标题），置位隐式任务区标志
+    const headingMatch = line.match(/^#+\s+(.+?)\s*$/)
+    if (headingMatch) {
+      currentWave = null
+      currentTask = null
+      const headingText = headingMatch[1].trim().toLowerCase()
+      inImplicitTaskSection = /^(tasks?|任务)$/.test(headingText)
+      continue
+    }
+
+    const taskMatch = line.match(/^[-*]\s*\[[ x]\]\s*(.+)/)
+    if (taskMatch) {
+      const taskNoMatch = taskMatch[1].match(/\btask-(\d+)\b/i)
+      // full plan.md：task 必须在显式 Wave 段内（currentWave 非 null），正常收容。
+      // light/none plan.md（无 Wave 标题，任务在 `## Tasks` 下）：在隐式任务区内，遇含
+      // task-XX 编号的 checkbox 时惰性创建隐式 Wave 收容，否则 validatePlanForExecute 会报
+      // "没有找到 checkbox task"。详见 docs/sillyspec/plan-light-needs-wave-heading.md
+      // 不收的情况：非任务区（## 自检/## 验收 等）的 checkbox，或任务区内无 task-XX 编号的 checkbox。
+      if (!currentWave) {
+        if (!inImplicitTaskSection || !taskNoMatch) continue
+        const nextIndex = waves.length === 0 ? 1 : (waves[waves.length - 1].index || waves.length) + 1
+        currentWave = { index: nextIndex, tasks: [], implicit: true }
+        currentTask = null
+        waves.push(currentWave)
+      }
+      currentTask = {
+        index: taskNoMatch ? parseInt(taskNoMatch[1], 10) : null,
+        name: taskMatch[1].trim(),
+        file: '',
+        steps: '',
+        reference: ''
+      }
+      // 兼容旧格式：任务名后跟 (文件路径)
+      const fileMatch = taskMatch[1].match(/\(([^)]+)\)$/)
+      if (fileMatch) {
+        currentTask.file = fileMatch[1]
+        currentTask.name = taskMatch[1].replace(/\([^)]+\)$/, '').trim()
+      }
+      currentWave.tasks.push(currentTask)
+      continue
+    }
+
+    // 解析子行信息（修改/参考/步骤）
+    if (currentTask) {
+      const modMatch = line.match(/^\s+-\s*修改:\s*(.+)/)
+      if (modMatch) { currentTask.file = modMatch[1].trim(); continue }
+
+      const refMatch = line.match(/^\s+-\s*参考:\s*(.+)/)
+      if (refMatch) { currentTask.reference = refMatch[1].trim(); continue }
+
+      const stepMatch = line.match(/^\s+-\s*步骤:/)
+      if (stepMatch) { currentTask.steps = line.replace(/^\s+-\s*步骤:\s*/, '').trim(); continue }
+
+      // 步骤续行（数字开头的子步骤）
+      if (currentTask.steps && line.match(/^\s+\d+\./)) {
+        currentTask.steps += '\n' + line.trim()
+      }
+    }
+  }
+
+  return waves
+}
+
+/**
+ * 同步判定派发后端模式（不发网络，零回归关键）— task-07
+ *
+ * stub 下 isPathASupported()=false → 有配置也只 local-fallback（加提示），不注入完整 SillyHub 指令。
+ * 现有测试套件不设 SILLYHUB_MCP_URL/TOKEN 且无 local.yaml mcp 段 → readMcpConfig 返回 null → 默认 'local' → buildWavePrompt 不注入派发段，
+ * 输出与改前字节一致（零回归，D-005）。
+ *
+ * @returns {'local' | 'local-fallback' | 'sillyhub'}
+ *   - local：无 MCP 配置（零回归，与现状一致）
+ *   - local-fallback：有配置但路径A 未落地（isPathASupported()=false），派发仍走 Local + 短提示
+ *   - sillyhub：有配置且路径A 落地（isPathASupported()=true），注入完整 SillyHub 派发指令
+ */
+export function getDispatchMode() {
+  const hasConfig = !!readMcpConfig(process.cwd())
+  if (!hasConfig) return 'local'
+  return isPathASupported() ? 'sillyhub' : 'local-fallback'
+}
+
+/**
+ * 解析 task 卡的 repo 归属（W3 task-08，D-012）。
+ * 读 changeDir/tasks/task-<num>.md 的 frontmatter `repo:` 字段；缺省/无卡/'main' → 'main'。
+ * 单仓 change（无 repo: 字段）恒返 'main'，零回归。
+ *
+ * @param {{ index?: number, name?: string }} task - wave.tasks 元素
+ * @param {string|null} changeDir - change 目录绝对路径
+ * @returns {string} repoKey，'main' 或 parseRepo 返回值
+ */
+function resolveTaskRepo(task, changeDir) {
+  if (!changeDir || !task || task.index == null) return 'main'
+  const num = String(task.index).padStart(2, '0')
+  const taskFile = path.join(changeDir, 'tasks', `task-${num}.md`)
+  if (!existsSync(taskFile)) return 'main'
+  try {
+    const content = readFileSync(taskFile, 'utf8')
+    const repo = parseRepo(content)
+    return repo || 'main'
+  } catch {
+    return 'main'
+  }
+}
+
+/**
+ * 把 base_commit 锡点写入 task 卡 frontmatter（W3 task-08，D-010）。
+ * 派发跨仓 task 前 CLI 实时 git rev-parse HEAD 落盘——锁定子代理起改的 base 锚点，
+ * 防止同 Wave 多 task 改同一跨仓仓时 HEAD 推进致 diff 范围漂移（design §5.3 约束① / R-01）。
+ *
+ * 策略：幂等写——frontmatter 有 base_commit 行则就地替换，无则紧跟 repo 行后插入（
+ * 无 frontmatter 时整段创建）。仅改 frontmatter 不动正文。已存在相同值不重复写。
+ *
+ * @param {string} taskFilePath - task-NN.md 绝对路径
+ * @param {string} baseCommit - 跨仓仓 HEAD sha
+ * @returns {boolean} 是否实际写入（false = 文件不存在 / 写失败 / 值未变）
+ */
+function writeBaseCommitToTaskCard(taskFilePath, baseCommit) {
+  if (!taskFilePath || !baseCommit) return false
+  if (!existsSync(taskFilePath)) return false
+  let content
+  try {
+    content = readFileSync(taskFilePath, 'utf8')
+  } catch {
+    return false
+  }
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!fmMatch) return false
+  const fm = fmMatch[1]
+  const baseLineRe = /^base_commit:\s*.*$/m
+  let newFm
+  if (baseLineRe.test(fm)) {
+    const existing = (fm.match(baseLineRe) || [''])[0]
+    if (existing === `base_commit: ${baseCommit}`) return false // 值未变，幂等跳过
+    newFm = fm.replace(baseLineRe, `base_commit: ${baseCommit}`)
+  } else {
+    // 紧跟 repo 行后插入（与 D-010 协议同源顺序 repo→base_commit→head_commit）
+    const repoLineRe = /^repo:\s*.*$/m
+    const anchor = `base_commit: ${baseCommit}\n`
+    if (repoLineRe.test(fm)) {
+      newFm = fm.replace(repoLineRe, m => m + '\n' + anchor.trimEnd())
+    } else {
+      // 无 repo 行：插到 frontmatter 首部（frontmatter 首字段）
+      newFm = anchor.trimEnd() + '\n' + fm
+    }
+  }
+  const newContent = content.replace(/^---\n[\s\S]*?\n---/, `---\n${newFm}\n---`)
+  if (newContent === content) return false
+  try {
+    writeFileSync(taskFilePath, newContent)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 为 Wave 生成 prompt（强制子代理执行）
+ *
+ * W3 task-08（D-012 per-task workdir）：签名加可选 `ctx`（MultiRepoContext）参数。
+ * - 无 ctx（单仓 change / 旧调用方）→ 退化为单 worktreePath 单值 worktreeSection（零回归）
+ * - 有 ctx → 按 task 逐个解析 repo 归属，构造 per-task workdir 多值表，跨仓 task 派发前
+ *   落 base_commit 锡点（D-010），注入跨仓 task commit 指引 + head_commit 落盘指引。
+ * 同 Wave 允许主仓+跨仓 task 混合（各独立 Task 调用各传 workdir，不强制同 Wave 同 repo）。
+ */
+export function buildWavePrompt(wave, waveIndex, changeDir, worktreePath, options = {}) {
+  const ctx = options.ctx || null
+  // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
+  let contractInjection = ''
+  let prototypeInjection = ''
+  if (changeDir) {
+    try {
+      const planFile = path.join(changeDir, 'plan.md')
+      if (existsSync(planFile)) {
+        const planContent = readFileSync(planFile, 'utf8')
+        // 收集本 wave 所有 task（端点注入与字段注入共用）
+        const waveTasks = wave.tasks.map((t, ti) => {
+          const num = String(t.index || (ti + 1)).padStart(2, '0')
+          return `task-${num}`
+        })
+
+        // 1) 端点级契约（provider/consumer via buildContractMatrix）
+        const contracts = buildContractMatrix(planContent, changeDir)
+        const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
+        if (relevantContracts.length > 0) {
+          contractInjection = `
+### API Contract Matrix
+本 Wave 存在前端/后端跨 task 契约：
+${relevantContracts.map(c => `- **${c.consumer}** 消费 **${c.provider}** 产出的 API`).join('\n')}
+`
+          for (const taskName of waveTasks) {
+            const injection = buildConsumerInjection(changeDir, path.join(changeDir, '..', '..'), taskName, contracts)
+            if (injection) {
+              contractInjection += `
+### 子代理 ${taskName} 的端点契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-injection>
+${injection}
+</contract-injection>
+`
+            }
+          }
+        }
+
+        // 2) 字段级契约（expects_from ↔ provides）
+        // 命中「provider 漏字段、consumer fallback 编造 → 运行时 403/500」这类 bug：
+        // 把 consumer 期望字段 vs provider 承诺字段显式注入子代理 prompt
+        for (const taskName of waveTasks) {
+          const fi = buildContractFieldInjection(changeDir, taskName)
+          if (fi) {
+            contractInjection += `
+### 子代理 ${taskName} 的字段契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-field-injection>
+${fi}
+</contract-field-injection>
+`
+          }
+        }
+      }
+    } catch (e) {
+      // 契约注入是 best-effort：失败不阻断 execute，只记录
+      console.warn(`  ⚠️ 契约注入跳过: ${e?.message || e}`)
+    }
+
+    // 原型引用注入：brainstorm 阶段的 HTML 原型（确认过的布局/组件/交互），
+    // 让 execute 实现前端/UI task 时参考原型，而非凭 design 文字重新发明（避免原型浪费）。
+    try {
+      const prototypes = readdirSync(changeDir).filter(f => /^prototype-.*\.html$/i.test(f))
+      if (prototypes.length > 0) {
+        const protoRelDir = `.sillyspec/changes/${path.basename(changeDir)}`
+        prototypeInjection = `
+### 📐 原型参考（brainstorm 可视化确认）
+本次变更有 HTML 原型（brainstorm 阶段确认过的视觉/交互），实现前端/UI 相关 task 时参考：
+${prototypes.map(p => `- \`${path.join(protoRelDir, p)}\``).join('\n')}
+
+照原型的布局/组件/交互实现，不要凭 design.md 文字重新发明。纯后端/无 UI 的 task 忽略本节。
+`
+      }
+    } catch {}
+  }
+
+  // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
+  const taskSummary = wave.tasks.map((t, ti) => {
+    const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
+    const taskRelPath = changeDir
+      ? `.sillyspec/changes/${path.basename(changeDir)}/tasks/task-${taskNum}.md`
+      : `task-${taskNum}.md`
+    const fileInfo = t.file ? ` (${t.file})` : ''
+    return `task-${taskNum}: ${t.name}${fileInfo} → ${taskRelPath}`
+  }).join('\n')
+
+  const taskList = wave.tasks.map((t, ti) => {
+    const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
+    let s = `- [ ] ${t.name}`
+    if (t.file) s += ` (${t.file})`
+    return s
+  }).join('\n')
+
+  // ── per-task workdir 解析（W3 task-08，D-012）──
+  // 无 ctx（单仓 change）→ 全 task workdir=主仓 worktreePath，沿用旧单值逻辑（零回归）。
+  // 有 ctx → 按 task 卡 repo: 字段逐个解析：主仓 task workdir=主仓 worktreePath，跨仓 task
+  // workdir=ctx.resolve(repo).worktreePath（跨仓仓根）。同 Wave 允许主仓+跨仓混合。
+  const taskRepos = wave.tasks.map(t => ctx ? resolveTaskRepo(t, changeDir) : 'main')
+  const hasCrossRepoWave = ctx ? taskRepos.some(r => r !== 'main') : false
+
+  // per-task workdir 映射（用于多值 worktreeSection + 跨仓 commit 指引）
+  // 无 ctx 或无跨仓 task → 不构造（沿用旧单值 worktreePath 注入）
+  let perTaskWorkdirs = null
+  let crossRepoCommitSection = ''
+  let baseCommitWrites = [] // [{ taskNum, repo, taskFile, written }] 跨仓 task base 锡点落盘记录
+  if (ctx && hasCrossRepoWave) {
+    perTaskWorkdirs = wave.tasks.map((t, ti) => {
+      const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
+      const repo = taskRepos[ti]
+      const entry = ctx.resolve(repo)
+      const workdir = entry ? entry.worktreePath : (worktreePath || '')
+      return { taskNum, repo, workdir }
+    })
+
+    // D-010 跨仓 task base 锡点：派发前实时 git rev-parse HEAD 落 task 卡 base_commit
+    // 仅对跨仓 task（repo≠'main'）落盘，主仓 task 锚 meta.baseHash（MultiRepoContext 已处理）
+    for (const item of perTaskWorkdirs) {
+      if (item.repo === 'main') continue
+      const entry = ctx.resolve(item.repo)
+      if (!entry) continue
+      const baseCommit = gitQuiet(entry.gitDir, ['rev-parse', 'HEAD'])
+      if (!baseCommit) continue // git 不可达已由 MultiRepoContext 构造时 fail-closed 拦截，此处置防御
+      const taskFile = changeDir
+        ? path.join(changeDir, 'tasks', `task-${item.taskNum}.md`)
+        : null
+      const written = taskFile ? writeBaseCommitToTaskCard(taskFile, baseCommit) : false
+      baseCommitWrites.push({ taskNum: item.taskNum, repo: item.repo, taskFile, written, baseCommit })
+    }
+
+    // 跨仓 task commit 指引 + head_commit 落盘指引（D-010 回收时机）
+    const crossLines = perTaskWorkdirs
+      .filter(i => i.repo !== 'main')
+      .map(i => `- task-${i.taskNum} → repo \`${i.repo}\`，workdir=\`${i.workdir}\``)
+      .join('\n')
+    crossRepoCommitSection = `
+### 跨仓 task 派发与双锡点（必须严格遵守）
+
+本 Wave 含跨仓 task（直接改跨仓仓主干，**不经主仓 worktree**）：
+
+${crossLines}
+
+**派发跨仓 task 前（base 锡点，CLI 已在 prompt 构造时落盘）：**
+- 跨仓 task 卡 frontmatter 的 \`base_commit\` 已由 CLI 实时 \`git -C <跨仓仓根> rev-parse HEAD\` 锁定（base 锡点，约束①）。子代理在此 HEAD 上改+commit，不受同 Wave 其他 task 推进 HEAD 影响。
+
+**回收跨仓 task review 前（head 锡点，你必须在子代理完成后落盘）：**
+- 跨仓 task 子代理完成 commit 后、写 review.json / 勾选 checkbox **之前**，你必须运行 \`git -C <跨仓仓根> rev-parse HEAD\` 把结果写入该 task 卡 frontmatter \`head_commit:\` 字段（与 \`base_commit:\` 同源 frontmatter 锡点写入）。
+- review.json 的 \`base\` 取 task 卡 \`base_commit\`、\`head\` 取 task 卡 \`head_commit\`（**非瞬时 HEAD**），锁 diff 范围不漂移。
+
+**跨仓 task 子代理 prompt 必须注入：**
+> 该 task 改的是 \`<repo>\` 仓，workdir=\`<跨仓仓根>\`。**直接在该仓主干工作区改+commit（git add + git commit 到该仓主干），不经主仓 worktree、不建分支。** commit 到该仓主干即落盘，apply 阶段对跨仓 task 为 no-op（design §5.4 G1）。
+`
+  }
+
+  // worktreeSection：无 ctx / 无跨仓 task → 旧单值（零回归）；有 ctx 含跨仓 task → per-task 多值表
+  let worktreeSection
+  if (ctx && hasCrossRepoWave && perTaskWorkdirs) {
+    const workdirLines = perTaskWorkdirs.map(i =>
+      `  - task-${i.taskNum} (repo: ${i.repo}) → workdir: "${i.workdir}"`
+    ).join('\n')
+    worktreeSection = `
+### 工作目录（必须严格遵守，per-task）
+
+调用 Task 工具启动子代理时，**workdir 参数是强制必传的**，且本 Wave 内不同 task 的 workdir 不同（主仓 task vs 跨仓 task）。
+
+**per-task workdir 表（每个子代理按其 task 对应的 workdir 启动）：**
+
+${workdirLines}
+
+不传 workdir 或传错 workdir 会导致：主仓 task 写到跨仓仓 / 跨仓 task 写到主仓 worktree，破坏隔离与 apply 归属。
+
+\`\`\`json
+{
+  "subagent_type": "general",
+  "workdir": "<按上方 per-task 表选>",
+  "prompt": "在此编写任务描述..."
+}
+\`\`\`
+
+### 注意
+蓝图文件（tasks.md / design.md / proposal.md / requirements.md / tasks/task-XX.md）在主工作区 .sillyspec/changes/<change>/ 下，它们不在跨仓仓也不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree / 跨仓仓路径下。
+`
+  } else {
+    worktreeSection = (worktreePath)
+      ? `
+### 工作目录（必须严格遵守）
+
+调用 Task 工具启动子代理时，**workdir 参数是强制必传的**。
+不传 workdir 会导致子代理把文件写到主工作区而非 worktree，破坏隔离。
+
+\`\`\`json
+{
+  "subagent_type": "general",
+  "workdir": "${worktreePath}",
+  "prompt": "在此编写任务描述..."
+}
+\`\`\`
+
+### 注意
+蓝图文件（tasks.md / design.md / proposal.md / requirements.md）在主工作区 .sillyspec/changes/<change>/ 下，它们可能不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree 路径下。
+`
+      : ''
+  }
+
+  // ── 派发后端段注入（task-07，D-006 / D-007 / D-008 接入）──
+  // 同步判定（不发网络，零回归关键）：local（无 MCP 配置）→ dispatchSection='' → 本 prompt 与改前
+  // 字节一致；sillyhub（配置 + 路径A 落地）→ 注入完整 SillyHub 派发指令（一 Wave 一 mission /
+  // dispatch_worker / 轮询 list_workers / 超时 kill lease 防双写 / 回收 + Local 兜底）；local-fallback
+  // （配置但路径A 未落地）→ 短提示，派发仍走 Local（与默认行为一致）。worktreePath 为空时不注入
+  // （无 worktree 无谓派发指令）。测试/调用方可经 options.dispatchMode 覆盖，避免 env 污染。
+  const dispatchMode = options.dispatchMode || getDispatchMode()
+  let dispatchSection = ''
+  if (worktreePath && dispatchMode === 'sillyhub') {
+    // 路径A 落地后：注入完整 SillyHub 派发指令（renderDispatchInstruction 已含 Local 兜底全文）
+    const contract = {
+      brief: '本 Wave 任务（见上方任务摘要与 tasks/task-XX.md）',
+      worktreePath,
+      branch: options.branch || '<未提供 branch>',
+      allowedPaths: [],
+      readOnly: false,
+      runId: '{EXECUTE_RUN_ID}',   // 占位符，prompt.js 注入阶段替换为真实 run id
+    }
+    const { instruction } = renderDispatchInstruction(contract, { available: true })
+    dispatchSection = `\n### 派发后端：SillyHub MCP（探测可用，一 Wave 一 mission）\n\n本次 Wave 派发经 SillyHub MCP。按以下派发指令执行（含 create_mission / dispatch_worker / 轮询 list_workers / 超时 kill lease 防双写 / 回收 + Local 兜底）：\n\n${instruction}\n`
+  } else if (worktreePath && dispatchMode === 'local-fallback') {
+    // 有 MCP 配置但路径A 未落地：加短提示，派发仍走 Local（与默认行为一致）
+    dispatchSection = `\n### 派发后端提示：SillyHub MCP 已配置但路径A 未落地\n\n检测到 local.yaml mcp 段或 env 配置，但 SillyHub \`dispatch_worker\` 尚不支持 \`worktree_path\`（路径A 跨仓未落地）。本次派发走 Local（本机 Agent tool），与默认行为一致——上方「执行方式」与「工作目录」段适用。\n`
+  }
+  // dispatchMode === 'local'（无配置）或 worktreePath 为空 → dispatchSection = '' → 输出与改前字节一致（零回归）
+
+  return `## Wave ${waveIndex}: 执行以下任务
+
+## 执行方式（必须严格遵守）
+
+**每个任务必须由独立子代理执行，你不要自己写代码。**
+
+你的角色是调度者 + 审查者：
+1. 为每个任务启动一个子代理（Agent tool），同 Wave 内可并行
+2. 子代理完成后审查结果
+3. 勾选 plan.md 中的 checkbox
+4. 记录改动文件和测试结果
+
+${worktreeSection}${crossRepoCommitSection}${dispatchSection}
+### 任务摘要（按需读取完整蓝图）
+为每个任务启动子代理时，**只需告知任务目标和蓝图文件路径，让子代理按需读取**：
+
+${taskSummary}
+
+子代理 prompt 要点：
+1. 任务目标（简短描述）
+2. 蓝图文件路径（让子代理自行读取详情）
+3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowed_paths
+4. 如存在模块文档（.sillyspec/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流
+5. 任务含测试代码时，把下方「测试用例设计」整段复制进子代理 prompt，要求子代理按此设计测试用例
+
+{{include: testcase-design}}
+
+### Wave 开始前
+1. 读取 design.md 的「非目标」与「兼容策略」章节（如存在），确保子代理不超范围、不破坏旧逻辑
+2. 读取 plan.md 了解全局任务划分和依赖关系
+3. 确认本 Wave 的输入/输出契约（前置 Wave 产出了什么，本 Wave 需要消费什么）
+4. 检查前置 Wave 的产出是否完整（文件是否存在、测试是否通过）
+5. **上下文分层加载**：
+   - 🔥 热上下文：design.md 非目标/兼容策略 + 当前 Wave 任务（必须加载）
+   - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
+   - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
+
+### 中断续跑（如曾中断恢复）
+execute 按 Wave 持久化进度，task 级进度靠 plan.md checkbox 勾选。若本 Wave 曾因 429/API 配额/崩溃中断：
+- plan.md 中**已勾选 \`- [x]\` 的 task 已完成，跳过不重跑**（子代理也可能在完成前中断，重跑前先确认该 task 产出文件是否完整）
+- 用 \`sillyspec status\` 查当前进度，重新 \`sillyspec run execute\` 会回到当前 Wave step 继续，**不要从零重置或重跑已完成 Wave**
+- 本 Wave 已完成但不完整（产出缺文件）的 task 补做，不牵连其他 task
+
+${contractInjection}${prototypeInjection}
+### 本 Wave 任务
+${taskList}
+
+### 调度要求
+1. **同一 Wave 内的任务必须并行启动子代理，禁止串行等待。** Wave 的定义就是"无依赖、可并行"，不要自行分析依赖关系。如果有依赖应该在 plan.md 的不同 Wave 中。
+2. **Reverse Sync**：子代理报告实现与 design.md 不一致时，先检查是代码错了还是文档有遗漏
+3. **不要频繁编译！** 编译很慢，只在以下情况运行：
+   - 写了大量代码后需要验证语法正确性
+   - 最后一个 Wave 完成后做一次全量编译验证
+   - 用户明确要求编译时
+4. 每个任务完成后：
+   - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
+   - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
+   - 记录改动文件和测试结果
+5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
+
+### Task Review Gate（必须执行，不可跳过）
+
+每个子代理完成后、勾选 checkbox **之前**，你必须创建 task review。
+
+**操作步骤：**
+1. 读取当前 task 的 git diff（从 task 开始到完成的变更）
+2. 对照 plan.md 中该 task 的描述和 tasks/task-XX.md（如果存在）检查实现是否符合要求
+3. 写入 review.json 文件
+4. **只有 review.json 写入成功后，才允许勾选 plan.md 中的 checkbox**
+
+**review.json 路径：**
+
+task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX/review.json
+
+本 execute run 的固定 ID 是：{EXECUTE_RUN_ID}
+**所有 task 的 review.json 必须使用这个 ID，不要自行创建新目录。**
+
+**review.json 必填字段：**
+
+{ "name_zh": "任务评审", "schemaVersion": {REVIEW_SCHEMA_VERSION}, "task": "task-XX", "base": "<git-base-commit>", "head": "<git-head-commit>",
+ "changedFiles": ["src/foo.js"], "specVerdict": "pass|fail|cannot_verify",
+ "qualityVerdict": "pass|fail|cannot_verify", "reviewerNotes": "评审说明",
+ "requiredEvidence": [] }
+
+**评审铁律：**
+- 不信任 implementer 自报结果，对照 diff 和 task brief 验证
+- 只看当前 task 的 diff，不做全仓库漫游审查
+- \`cannot_verify\` 只在确实无法验证且有待补充证据时使用，且 requiredEvidence 必须非空
+- \`sillyspec run execute --done\` 会校验所有 task 的 review.json，缺失或 fail 会阻断完成
+
+### module-impact.md 更新（主代理在本 Wave 所有 task 完成后汇总）
+本 Wave 内所有 task 子代理完成、review.json 写好后，**由你（主代理/调度者）**汇总本 Wave 的实际代码变更，更新 {SPEC_ROOT}/changes/<change>/module-impact.md（plan 阶段已生成首版）：
+- 基于本 Wave 各 task 的实际 git diff（不是计划）+ {SPEC_ROOT}/docs/<project>/modules/_module-map.yaml 对照
+- 更新受影响模块的影响类型/说明（实际改动可能与 plan 首版预估不同，据实修正）
+- **不由各 task 子代理分别改**（同 Wave 并行子代理改同一文件会互相覆盖）——只由主代理在 Wave 收尾统一更新一次
+- 无 _module-map.yaml 时跳过模块匹配，仅按文件清单更新 unmapped 部分
+这是可选更新（不阻断 execute 完成），但保持 module-impact 与实际变更一致利于 verify 核对与 archive 终审。
+
+### 完成后
+1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
+   - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
+   - 将端点清单写入 {SPEC_ROOT}/.runtime/contract-artifacts/<task-name>/endpoints.json
+   - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
+`
+}
+
+/**
+ * 动态构建 execute 步骤列表
+ * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave
+ * @param {{ worktreePath?: string, noWorktree?: boolean }} options
+ * @returns {Array} 步骤列表
+ */
+export function buildExecuteSteps(planFilePath = null, options = {}) {
+  const noWorktree = !!options.noWorktree
+  let waves
+  let changeDir = null
+
+  if (planFilePath && existsSync(planFilePath)) {
+    const planContent = readFileSync(planFilePath, 'utf8')
+    // Plan → Execute 契约由 plan 阶段完成时的 postcheck 把关（run.js completeStep），
+    // 此处只负责解析 waves，避免 buildExecuteSteps 与进程退出耦合。
+    waves = parseWavesFromPlan(planContent)
+    changeDir = path.dirname(planFilePath)
+  }
+
+  // 没解析出 Wave（plan 不存在或不含可识别 task）→ 默认 3 Wave（向后兼容）
+  if (!waves || waves.length === 0) {
+    waves = []
+    for (let i = 1; i <= 3; i++) {
+      waves.push({ index: i, tasks: [{ name: `默认任务 ${i}`, file: 'TBD' }] })
+    }
+  }
+
+  // 尝试获取 worktree 路径（可能由前缀步骤创建）
+  const worktreePath = options.worktreePath || null
+
+  // W3 task-08：ctx 由 execute 启动入口（task-09）透传，进程级单例贯穿 execute/apply/verify
+  // （D-013）。缺省=null → buildWavePrompt 退化为单仓单 worktreePath（零回归）。
+  const ctx = options.ctx || null
+
+  const waveSteps = waves.map((wave, i) => ({
+    name: `Wave ${i + 1} 执行`,
+    mode: 'implementation',
+    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath, { dispatchMode: options.dispatchMode, branch: options.branch, ctx }),
+    outputHint: `Wave ${i + 1} 执行结果`,
+    optional: false
+  }))
+
+  return [...fixedPrefix, ...waveSteps, ...acceptanceSteps, ...fixedSuffix]
+}