sillyspec 3.18.2 → 3.18.3

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

@@ -202,8 +202,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 +259,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 状态：
+- 失败模式排除：
+
 ## 代码审查
 （问题列表 + 总体评价）
 \`\`\`

package/test/brainstorm-plan-contract.test.mjs

@@ -0,0 +1,273 @@
+/**
+ * Brainstorm → Plan Contract v1 测试
+ *
+ * 验证 design.md 到 plan 的输入契约：
+ * 1. 合法 design 通过
+ * 2. 缺关键章节失败
+ * 3. warning 不阻断
+ */
+import { validateDesignForPlan } from '../src/stages/plan.js'
+
+let failed = 0
+const failures = []
+
+function assert(condition, msg) {
+  if (!condition) {
+    failed++
+    failures.push(msg)
+    console.log(`  ❌ FAIL: ${msg}`)
+  } else {
+    console.log(`  ✅ PASS: ${msg}`)
+  }
+}
+
+console.log('=== Brainstorm → Plan Contract v1 测试 ===\n')
+
+// ─────────────────────────────────────────
+// Case 1: valid design 通过
+// ─────────────────────────────────────────
+console.log('--- Case 1: valid design 通过 ---')
+{
+  const design = `# Design: 用户认证系统
+
+## 背景
+需要实现用户认证。
+
+## 设计目标
+- 支持 OAuth2
+- 支持手机号登录
+
+## 非目标
+- 不做 SSO
+
+## 总体方案
+使用 JWT + Refresh Token。
+
+## 决策
+- D-001@v1: 选择 JWT 而非 Session
+
+## 约束
+- 必须兼容现有 API
+
+## 文件变更清单
+| 操作 | 文件路径 | 说明 |
+|------|---------|------|
+| 新增 | src/auth.js | 认证模块 |
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '完整 design 应校验通过')
+  assert(result.errors.length === 0, '不应有 errors')
+  assert(result.warnings.length === 0, '不应有 warnings')
+}
+
+// ─────────────────────────────────────────
+// Case 2: empty design 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 2: empty design 失败 ---')
+{
+  assert(!validateDesignForPlan('').ok, '空字符串应失败')
+  assert(!validateDesignForPlan(null).ok, 'null 应失败')
+  assert(!validateDesignForPlan('   ').ok, '纯空格应失败')
+}
+
+// ─────────────────────────────────────────
+// Case 3: missing goal 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 3: missing goal/背景 失败 ---')
+{
+  const design = `# Design
+
+## 总体方案
+用 JWT。
+
+## 决策
+D-001@v1: 选 JWT
+`
+  const result = validateDesignForPlan(design)
+  assert(!result.ok, '缺目标/背景应失败')
+  assert(result.errors.some(e => e.includes('目标') || e.includes('背景')), '错误应提到目标/背景')
+}
+
+// ─────────────────────────────────────────
+// Case 4: missing scope/方案 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 4: missing scope/方案 失败 ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 决策
+D-001@v1: 选 JWT
+`
+  const result = validateDesignForPlan(design)
+  assert(!result.ok, '缺范围/方案应失败')
+  assert(result.errors.some(e => e.includes('范围') || e.includes('方案')), '错误应提到范围/方案')
+}
+
+// ─────────────────────────────────────────
+// Case 5: missing decisions 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 5: missing decisions 失败 ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。
+`
+  const result = validateDesignForPlan(design)
+  assert(!result.ok, '缺决策应失败')
+  assert(result.errors.some(e => e.includes('决策')), '错误应提到决策')
+}
+
+// ─────────────────────────────────────────
+// Case 6: decisions.md 引用也算决策
+// ─────────────────────────────────────────
+console.log('\n--- Case 6: decisions.md 引用算决策 ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。详见 decisions.md。
+
+## 文件变更清单
+| 操作 | 文件 | 说明 |
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, 'decisions.md 引用应满足决策检查')
+}
+
+// ─────────────────────────────────────────
+// Case 7: missing non-goals 只有 warning
+// ─────────────────────────────────────────
+console.log('\n--- Case 7: missing non-goals warning ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。
+
+## 决策
+D-001@v1: 选 JWT
+
+## 约束
+必须兼容现有 API。
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '缺非目标不应阻断')
+  assert(result.warnings.some(w => w.includes('非目标') || w.includes('Non-goals')), '应有非目标 warning')
+}
+
+// ─────────────────────────────────────────
+// Case 8: missing constraints 只有 warning
+// ─────────────────────────────────────────
+console.log('\n--- Case 8: missing constraints warning ---')
+{
+  const design = `# Design
+
+## 目标
+实现认证。
+
+## 设计方案
+用 JWT。
+
+## 决策
+选择 JWT。
+
+## 非目标
+不做 SSO。
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '缺约束不应阻断')
+  assert(result.warnings.some(w => w.includes('约束') || w.includes('风险') || w.includes('Trade-off')), '应有约束/风险 warning')
+}
+
+// ─────────────────────────────────────────
+// Case 9: missing 文件变更清单 warning
+// ─────────────────────────────────────────
+console.log('\n--- Case 9: missing 文件变更清单 warning ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。
+
+## 决策
+D-001@v1: 选 JWT
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '缺文件变更清单不应阻断')
+  assert(result.warnings.some(w => w.includes('文件变更')), '应有文件变更 warning')
+}
+
+// ─────────────────────────────────────────
+// Case 10: 英文 design 通过
+// ─────────────────────────────────────────
+console.log('\n--- Case 10: 英文 design 通过 ---')
+{
+  const design = `# Design: Auth System
+
+## Background
+We need authentication.
+
+## Solution
+Use JWT + Refresh Token.
+
+## Decision
+D-001@v1: Choose JWT over Session
+
+## Non-goals
+No SSO.
+
+## Constraints
+Must be backwards compatible.
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '英文 design 应校验通过')
+  assert(result.errors.length === 0, '不应有 errors')
+}
+
+// ─────────────────────────────────────────
+// Case 11: 最小合法 design
+// ─────────────────────────────────────────
+console.log('\n--- Case 11: 最小合法 design ---')
+{
+  const design = `# Design
+
+## 目标
+修 bug。
+
+## 方案
+改代码。
+
+## 决策
+D-001@v1: 直接改。
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '最小合法 design 应通过')
+  // 可能有 warning 但 ok
+}
+
+// ── 结果 ──
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${11 - failed}  ❌ 失败: ${failed}`)
+if (failures.length > 0) {
+  console.log(`失败项:`)
+  failures.forEach(f => console.log(`  - ${f}`))
+}
+console.log(`${'='.repeat(50)}`)
+
+if (failed > 0) process.exit(1)