sillyspec 3.18.1 → 3.18.3

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,33 +126,52 @@ 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: '上下文摘要',
     optional: false
   },
   {
-    name: '创建 worktree',
-    prompt: `为本次执行创建隔离的 git worktree。
+    name: '确认 worktree 路径',
+    prompt: `确认当前 worktree 状态，提取隔离路径。
 
 ### 操作
-1. 运行 \`sillyspec worktree create <change-name>\`
-2. 记录输出的 worktree 路径
-3. 后续所有子代理的 cwd 设为该 worktree 路径
-4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+1. 运行 \`sillyspec worktree meta <change-name>\` 读取 meta.json
+2. 从输出中提取 worktreePath、branch、mode 字段
+3. 确认 worktree 目录存在（如果是 worktree/native-worktree 模式）
 
-### 降级模式
-CLI 可能自动降级（sandbox 限制、已在 linked worktree 中）：
-- \`mode: native-worktree\` — 已在 linked worktree，直接复用
-- \`mode: in-place-fallback\` — git worktree add 失败，降级为 in-place + baseline protection
-- 这两种模式都会输出 worktree 路径和分支名，正常继续即可
+### 铁律
+- **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
+- **后续所有子代理的 cwd 必须设为该 worktree 路径**
+- 如果 meta.json 不存在（说明创建失败），停止并报错
 
 ### 输出
-worktree 路径 + 分支名 + 模式（如果有）
+worktree 路径 + 分支名 + 模式
 
 ### 完成后执行
-sillyspec run execute --done --output "worktree 路径 + 分支名"`,
-    outputHint: 'worktree 路径 + 分支名',
+sillyspec run execute --done --output "worktree 路径 + 分支名 + 模式"`,
+    outputHint: 'worktree 路径 + 分支名 + 模式',
     optional: false
   },
   {
@@ -93,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 模式`,
@@ -405,12 +510,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

@@ -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)