sillyspec 3.18.2 → 3.18.4

package/src/stages/execute.js

@@ -1,6 +1,86 @@
 import { existsSync, readFileSync } from 'fs'
 import path from 'path'
 
+/**
+ * 校验 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) {
+    errors.push('plan.md 中没有找到 checkbox task（格式: "- [ ] task-XX: 任务名"）')
+    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(`task id 不连续: 期望 task-${String(i + 1).padStart(2, '0')}, 实际 task-${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: '波次执行',
@@ -46,6 +126,27 @@ const fixedPrefix = [
     - 用 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: '上下文摘要',
@@ -91,6 +192,12 @@ sillyspec run execute --done --output "worktree 路径 + 分支名 + 模式"`,
    - auto — 全部自动执行
 5. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
 
+### 知识命中报告
+{KNOWLEDGE_HIT_REPORT}
+
+如上所示的知识条目与本次任务相关。请阅读这些条目以获取项目约定和已知模式。
+如无命中条目（Status: no matches），跳过本节。
+
 ### 铁律
 - **不要询问用户确认频率**，确认模式由 CLI \`--confirm-mode\` 参数决定
 - 如果未检测到 \`--confirm-mode\`，默认使用 wave 模式`,
@@ -299,6 +406,48 @@ function parseWavesFromPlan(planContent) {
  * 为 Wave 生成 prompt（强制子代理执行）
  */
 function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
+  // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
+  let contractInjection = ''
+  if (changeDir) {
+    try {
+      const { buildContractMatrix, buildConsumerInjection } = require('../contract-matrix.js')
+      const planFile = path.join(changeDir, 'plan.md')
+      if (existsSync(planFile)) {
+        const planContent = readFileSync(planFile, 'utf8')
+        const contracts = buildContractMatrix(planContent, changeDir)
+        if (contracts.length > 0) {
+          // 收集本 wave 所有 task 的注入内容
+          const waveTasks = wave.tasks.map((t, ti) => {
+            const num = String(t.index || (ti + 1)).padStart(2, '0')
+            return `task-${num}`
+          })
+          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')}
+`
+            // 为每个 consumer task 生成详细注入
+            for (const taskName of waveTasks) {
+              const injection = buildConsumerInjection(changeDir, join(changeDir, '..', '..'), taskName, contracts)
+              if (injection) {
+                contractInjection += `
+### 子代理 ${taskName} 的契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-injection>
+${injection}
+</contract-injection>
+`
+              }
+            }
+          }
+        }
+      }
+    } catch {}
+  }
+
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
   const taskSummary = wave.tasks.map((t, ti) => {
     const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
@@ -369,7 +518,7 @@ ${taskSummary}
    - 🔥 热上下文：design.md 编码铁律 + 当前 Wave 任务（必须加载）
    - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
    - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
-
+${contractInjection}
 ### 本 Wave 任务
 ${taskList}
 
@@ -386,7 +535,11 @@ ${taskList}
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
 
 ### 完成后
-运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
+1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
+   - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
+   - 将端点清单写入 .sillyspec/.runtime/contract-artifacts/<task-name>/endpoints.json
+   - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
+2. 运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
 }
 
 
@@ -403,12 +556,13 @@ export function buildExecuteSteps(planFilePath = null, options = {}) {
 
   if (planFilePath && existsSync(planFilePath)) {
     const planContent = readFileSync(planFilePath, 'utf8')
+    // Plan → Execute 契约由 plan 阶段完成时的 postcheck 把关（run.js completeStep），
+    // 此处只负责解析 waves，避免 buildExecuteSteps 与进程退出耦合。
     waves = parseWavesFromPlan(planContent)
-    // 从 planFilePath 推导 changeDir: .sillyspec/changes/<name>/plan.md
     changeDir = path.dirname(planFilePath)
   }
 
-  // 如果没解析出 Wave，生成默认 3 个
+  // 没解析出 Wave（plan 不存在或不含可识别 task）→ 默认 3 Wave（向后兼容）
   if (!waves || waves.length === 0) {
     waves = []
     for (let i = 1; i <= 3; i++) {

package/src/stages/plan.js

@@ -1,6 +1,64 @@
 import { existsSync, readFileSync } from 'fs'
 import path from 'path'
 
+/**
+ * 校验 design.md 是否满足 plan 执行契约
+ * 第一版是轻量 markdown 结构检查，不强 schema。
+ * @param {string} designContent - design.md 文件内容
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateDesignForPlan(designContent) {
+  const errors = []
+  const warnings = []
+
+  if (!designContent || !designContent.trim()) {
+    return { ok: false, errors: ['design.md 内容为空'], warnings }
+  }
+
+  const lower = designContent.toLowerCase()
+
+  // 检查 1: 必须包含目标/问题描述（error）
+  const hasGoal = /(^|\n)#{2,}\s*.*(目标|goal|objective|背景|background|问题|problem|purpose|目的)/i.test(designContent)
+  if (!hasGoal) {
+    errors.push('design.md 缺少「目标/背景/问题描述」章节 — plan 需要知道要达成什么')
+  }
+
+  // 检查 2: 必须包含范围/scope（error）
+  const hasScope = /(^|\n)#{2,}\s*.*(范围|scope|总体方案|方案|approach|solution|设计|design)/i.test(designContent)
+  if (!hasScope) {
+    errors.push('design.md 缺少「范围/总体方案/设计」章节 — plan 需要知道做什么和怎么做')
+  }
+
+  // 检查 3: 必须包含决策/方案选择（error）
+  const hasDecisions = /(^|\n)#{2,}\s*.*(决策|decision|选择|choice|方案选择)/i.test(designContent)
+  || /d-\d+@v\d+/i.test(designContent) // decisions.md 引用 ID
+  || /decisions?\.md/i.test(designContent) // 引用 decisions.md
+  if (!hasDecisions) {
+    errors.push('design.md 缺少「决策/方案选择」— plan 需要基于明确的技术决策来拆分任务')
+  }
+
+  // 检查 4 (warning): 缺非目标/non-goals
+  const hasNonGoals = /(^|\n)#{2,}\s*.*(非目标|non-goals?|不做|out of scope|不在范围)/i.test(designContent)
+  if (!hasNonGoals) {
+    warnings.push('design.md 缺少「非目标/Non-goals」— 建议明确不做什么，防止 scope creep')
+  }
+
+  // 检查 5 (warning): 缺约束/风险
+  const hasConstraints = /(^|\n)#{2,}\s*.*(约束|constraint|限制|limitation|风险|risk|trade-?off)/i.test(designContent)
+  if (!hasConstraints) {
+    warnings.push('design.md 缺少「约束/风险/Trade-off」— 建议记录已知约束和风险')
+  }
+
+  // 检查 6 (warning): 缺文件变更清单
+  const hasFileChanges = /文件变更|file change|变更清单|changed files/i.test(designContent)
+  || /^\|\s*(新增|修改|删除|new|modify|delete|update)\s*\|/im.test(designContent)
+  if (!hasFileChanges) {
+    warnings.push('design.md 缺少「文件变更清单」— 建议列出预期改动的文件')
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
 export const definition = {
   name: 'plan',
   title: '实现计划',
@@ -326,6 +384,8 @@ plan_level + 计划内容（none 级别输出建议操作）`,
 - [ ] （brownfield）全局验收包含兼容性条款
 - [ ] 没有实现细节（接口定义、代码示例等不应该在 plan.md 里）
 - [ ] plan.md 与 design.md 的文件变更清单一致
+- [ ] 如果涉及构造函数/接口/DTO/client 方法变更，是否搜索了所有调用点并纳入任务范围？
+- [ ] 调用点搜索命令的输出是否记录在 plan.md 或 task-NN.md 中？
 - [ ] 如果有 Mermaid 图，依赖关系确实非平凡（非线性/非全并行）
 - [ ] 没有泛泛风险分析（如"需要充分测试"）
 
@@ -376,6 +436,28 @@ export const fixedSuffix = [
    - 依赖关系和 plan.md 的 Wave 分组是否一致
    - 验收标准和 plan.md 的全局标准是否矛盾
    - 接口定义是否自洽
+5. **生产接线路径检查**（Critical）：
+   - 读取 design.md，搜索以下关键词：
+     - 注入 / inject / 构造 / constructor / 初始化 / init / 启动路径 / startup / main / cli / entrypoint / daemon start / bootstrap
+     - 如果命中，提取提到的具体文件名（如 "在 cli.ts 中"、"main.ts 中实例化"、"Daemon 构造函数"）
+   - 收集所有 tasks/task-NN.md 的 frontmatter 中 \`allowed_paths\` 列表
+   - 检查：design 中提到的生产入口文件是否在某个 task 的 allowed_paths 中？
+   - 如果 design 提到了入口文件但所有 task 的 allowed_paths 都不含该文件：
+     - **这是 plan contract 失败**
+     - 列出具体矛盾：\`design says: X 实例化 Y，但 allowed_paths 不含 Z\`
+     - **不自动修复**，暂停等待用户决定
+   - 如果 design 明确说"不需要改入口文件"并给出了理由，视为通过
+   - 调用：\`sillyspec run plan --wait --reason "生产接线路径检查失败" --options "修改 allowed_paths,修改 design,确认不需要改入口" --output "矛盾清单"\`
+6. **符号影响面检查**（Critical）：
+   - 对每个 task 涉及的文件，检查是否修改了构造函数、接口、DTO、API client 方法签名
+   - 如果是，搜索所有调用点：
+     \`\`\`bash
+     rg "new <ClassName>" src/
+     rg "<methodName>" src/ --type ts --type js
+     \`\`\`
+   - 对比调用点与 plan.md/task 的 allowed_paths
+   - 发现调用点不在任务范围内 → **plan contract 失败**
+   - 调用：\`sillyspec run plan --wait --reason "符号影响面检查发现遗漏调用点" --options "扩展 allowed_paths,添加新任务,确认不需要改" --output "遗漏调用点清单"\`
 3. 发现问题 → 列出问题清单，暂停等待用户决定
    - 调用：\`sillyspec run plan --wait --reason "审查发现一致性问题" --options "自动修复,手动修复,忽略并继续" --output "问题清单"\`
    - **绝对禁止**：自己决定修复方向然后自动修复

package/src/stages/scan.js

@@ -454,6 +454,46 @@ step1 → step2 → step3
       outputHint: '流程和术语表生成状态',
       optional: true
     },
+    {
+      name: 'Extract Project Knowledge',
+      perProject: true,
+      prompt: `从本次 scan 产物中提取长期有效、跨变更复用的项目知识，写入知识库。
+
+### 知识分类
+| 文件 | 内容 |
+|------|------|
+| conventions.md | 项目约定：目录规范、命名规范、提交规范、测试规范 |
+| patterns.md | 可复用模式：鉴权方式、错误处理方式、模块组织方式 |
+| known-issues.md | 已知坑：不可直接改的模块、历史兼容问题、代理限制 |
+| uncategorized.md | 不确定分类、需要人工确认的知识 |
+
+INDEX.md 维护索引，格式（每行：关键词1|关键词2 → [条目名](文件#锚点)；关键词用于 execute 阶段命中匹配，必须给出能区分该知识的词）：
+\`\`\`markdown
+# Knowledge Index
+
+## Conventions
+- ESM|module|import → [ESM Only](conventions.md#esm-only)
+\`\`\`
+
+### ⛔ 硬规则（必须遵守）
+1. **只写未来变更会反复用到的知识** — 不要把 scan 报告摘要塞进知识库
+2. **不要重复 knowledge 文件中已有的内容** — 读取现有文件，追加新条目，不覆盖
+3. **不确定分类或不确定长期有效 → uncategorized.md** — 宁可不确定也不要放错
+4. **每个正式分类条目必须更新 INDEX.md** — 添加对应分类下的链接
+5. **每个条目用 markdown 锚点格式** — 文件内用 \`## 标题\`，INDEX 用 \`[#标题]\` 或 \`(文件名#标题)\`
+
+### 操作
+1. 读取现有 knowledge 文件：\`{KNOWLEDGE_ROOT}/INDEX.md\`、\`{KNOWLEDGE_ROOT}/conventions.md\` 等
+2. 遍历 scan 产物（\`{DOCS_ROOT}/scan/*.md\`、\`{DOCS_ROOT}/modules/*.md\`），识别可复用知识
+3. 将新知识按分类写入对应文件（追加模式，不覆盖已有内容）
+4. 更新 INDEX.md 索引
+5. 如果确实没有新知识可提取（已有文件已覆盖），输出"无新知识"而非创建空条目
+
+### 输出
+新增知识条目数量 + 分类分布（或"无新知识"）`,
+      outputHint: '知识条目数量',
+      optional: false
+    },
     {
       name: '自检和提交',
       perProject: true,

package/src/stages/verify.js

@@ -134,6 +134,31 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 5. 任意 D-xxx@vN 无下游覆盖时标记为 ⚠️ 决策未闭环
 6. 任意 P0/P1 unresolved/blocking 决策标记为 FAIL blocker
 
+**探针 5：API Contract Parity Check（跨前后端契约对账）**
+此探针仅在以下条件满足时执行：
+- 存在 \.sillyspec/.runtime/contract-artifacts/ 目录（说明 execute 阶段生成了 endpoint artifact）
+- 或者项目同时有 backend/ 和 frontend/ 目录
+
+执行步骤：
+1. 收集所有 provider endpoint artifacts：
+   - 读取 .sillyspec/.runtime/contract-artifacts/*/endpoints.json
+   - 汇总为 backend 端点清单
+2. 扫描前端 API 调用：
+   - 在 frontend/ 目录中搜索 apiFetch/request/axios/fetch 调用
+   - 提取所有 API 路径（归一化动态参数为 {param}）
+3. Diff 对账：
+   - 前端调用路径在 backend 端点清单中找不到 → **❌ Missing backend endpoint**（FAIL blocker）
+   - backend 端点在前端无调用 → ⚠️ Unused backend endpoint（warning，不阻断）
+4. 输出对账结果表格：
+   \
+\
+   | 状态 | 前端调用 | 后端端点 | 文件 |
+   |---|---|---|---|
+   | ❌ missing | GET /api/ppm/project-plan/{param}/plan-nodes | — | frontend/src/lib/ppm/plan.ts |
+\
+\
+   如果发现 Missing backend endpoint，必须在验证报告中标记为 ❌ contract gap。
+
 ### 探针结果处理
 - 将四个探针的结果汇总为「探针报告」
 - 如果探针发现问题（未实现标记、关键词缺失、测试缺失、决策未闭环），在最终验证报告中明确标注
@@ -202,8 +227,32 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 
 ### 操作
 1. 汇总以上所有检查结果
-2. 生成 verify-result.md 文件，保存到 \`.sillyspec/changes/<change-name>/verify-result.md\`
-3. 给出结论：PASS / PASS WITH NOTES / FAIL
+2. **判定变更风险等级（change_risk_profile）**：
+
+### 变更风险分级规则
+扫描 design.md 和 plan.md 的关键词，自动判定 verify 强度：
+
+| 触发条件 | verify 要求 |
+|---|---|
+| 只改文案/文档 | 静态检查即可 |
+| 单模块纯函数 | 单测即可 |
+| API contract / DTO / client | 单测 + contract test |
+| daemon/backend 跨进程 | **必须真实集成** |
+| session/lease/run 状态机 | **必须生命周期端到端验证** |
+| 部署启动路径 | **必须真实启动一次** |
+
+触发关键词：daemon, backend, session, lease, agent_run, lifecycle, state_transition, claim, heartbeat, cross-process, cli.ts, main.ts, server.ts, bootstrap, entrypoint
+
+### 风险门控规则
+- **integration-critical** 或 **deployment-critical** 变更：
+  - 结论为 PASS WITH NOTES → **降级为 FAIL**
+  - mock 单测通过但没有真实集成证据 → **FAIL**
+  - 必须在 verify-result.md 中包含 **Runtime Evidence** section
+- **contract-required** 变更：需要 contract test 证据
+- **unit-sufficient** 变更：单测即可
+
+3. 生成 verify-result.md 文件，保存到 \`.sillyspec/changes/<change-name>/verify-result.md\`
+4. 给出结论：PASS / PASS WITH NOTES / FAIL（受风险门控约束）
 
 ### verify-result.md 格式
 \`\`\`markdown
@@ -235,6 +284,18 @@ PASS / PASS WITH NOTES / FAIL
 ## 技术债务
 （TODO/FIXME/HACK 统计）
 
+## 变更风险等级
+（自动检测的 change_risk_profile: doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical）
+
+## Runtime Evidence（integration-critical / deployment-critical 必填）
+- daemon 启动命令：
+- backend 地址：
+- 创建 session / 调用核心 API 的请求：
+- daemon 日志关键片段（不能出现 session_control_no_manager / fallback to task_runner / submitMessages agent_run_id empty / 422）：
+- backend 状态（AgentRun running -> completed/failed）：
+- session / lease end 状态：
+- 失败模式排除：
+
 ## 代码审查
 （问题列表 + 总体评价）
 \`\`\`