sillyspec 3.18.0 → 3.18.2

package/src/stage-contract.js

@@ -5,7 +5,7 @@
  * CLI 不再相信 prompt 完成，completeStep 后必须过 validator。
  */
 
-import { existsSync, readdirSync } from 'fs'
+import { existsSync, readdirSync, readFileSync } from 'fs'
 import { join, basename } from 'path'
 
 /**
@@ -26,6 +26,117 @@ import { join, basename } from 'path'
 
 // ============ Validators ============
 
+function resolveChangeDir(cwd, changeName, specRoot = null) {
+  const changesRoot = specRoot ? join(specRoot, 'changes') : join(cwd, '.sillyspec', 'changes')
+  return join(changesRoot, changeName)
+}
+
+function collectIdsFromLine(line, re, ids) {
+  for (const match of line.matchAll(re)) {
+    ids.add(match[0].toUpperCase())
+  }
+}
+
+function extractIds(content, prefix) {
+  if (!content) return []
+  const ids = new Set()
+  const idRe = new RegExp(`\\b${prefix}-\\d+(?:@v\\d+)?\\b`, 'gi')
+  const headingLineRe = /^\s{0,3}#{1,6}\s+/i
+  const fieldLineRe = /^\s*(?:[-*]\s*)?(?:id|decision[-_ ]?ids?|requirement[-_ ]?ids?|covers?|coverage|references?|impacts?|覆盖(?:来源|决策|需求)?)\s*[:：]/i
+  const tableLineRe = /^\s*\|/
+  const listStartsWithIdRe = new RegExp(`^\\s*(?:[-*]|\\d+\\.)\\s*(?:\\[[ xX]\\]\\s*)?${prefix}-\\d+(?:@v\\d+)?\\b`, 'i')
+
+  for (const line of content.split(/\r?\n/)) {
+    if (!headingLineRe.test(line) && !fieldLineRe.test(line) && !tableLineRe.test(line) && !listStartsWithIdRe.test(line)) continue
+    collectIdsFromLine(line, idRe, ids)
+  }
+  return [...ids].sort()
+}
+
+function readDecisionField(body, fieldPattern, fallback = '') {
+  const re = new RegExp(`^\\s*(?:[-*]\\s*)?(?:${fieldPattern})\\s*[:：]\\s*([^\\n]+)`, 'im')
+  return (body.match(re)?.[1] || fallback).trim()
+}
+
+function buildDecisionRecord(id, body) {
+  const status = readDecisionField(body, 'status', 'accepted').toLowerCase()
+  const blockerValue = readDecisionField(body, 'blocker', 'false').toLowerCase()
+  const blocker = ['true', 'yes', '1'].includes(blockerValue)
+  const priorityValue = readDecisionField(body, 'priority|level|severity')
+  const priorityMissing = priorityValue.length === 0
+  const fallbackPriority = (['unresolved', 'blocking'].includes(status) || blocker) ? 'P1' : 'P2'
+  const priority = (priorityValue.match(/P[0-2]/i)?.[0] || fallbackPriority).toUpperCase()
+  return { id: id.toUpperCase(), body, status, priority, blocker, priorityMissing }
+}
+
+function findNextDecisionBoundary(content, startIndex) {
+  const boundaryRe = /^(\s{0,3}#{2,6}\s+D-\d+(?:@v\d+)?\b|\s*(?:[-*]\s*)?(?:id|decision[-_ ]?id|decision)\s*[:：]\s*D-\d+(?:@v\d+)?\b)/gmi
+  boundaryRe.lastIndex = startIndex
+  const next = boundaryRe.exec(content)
+  return next ? next.index : content.length
+}
+
+function isInsideRange(index, ranges) {
+  return ranges.some(range => index >= range.start && index < range.end)
+}
+
+function parseDecisionRecords(content) {
+  if (!content) return []
+  const records = []
+  const ranges = []
+  const headingRe = /^\s{0,3}#{2,6}\s+(D-\d+(?:@v\d+)?)(?:\b|:)[^\n]*$/gmi
+  const headings = []
+  let match
+  while ((match = headingRe.exec(content)) !== null) {
+    headings.push({ id: match[1].toUpperCase(), index: match.index, end: headingRe.lastIndex })
+  }
+  for (let i = 0; i < headings.length; i++) {
+    const current = headings[i]
+    const next = headings[i + 1]
+    const body = content.slice(current.end, next ? next.index : content.length)
+    const end = next ? next.index : content.length
+    ranges.push({ start: current.index, end })
+    records.push(buildDecisionRecord(current.id, body))
+  }
+
+  const idLineRe = /^\s*(?:[-*]\s*)?(?:id|decision[-_ ]?id|decision)\s*[:：]\s*(D-\d+(?:@v\d+)?)(?:\b|$)/gmi
+  while ((match = idLineRe.exec(content)) !== null) {
+    if (isInsideRange(match.index, ranges)) continue
+    const bodyEnd = findNextDecisionBoundary(content, idLineRe.lastIndex)
+    const body = content.slice(match.index, bodyEnd)
+    records.push(buildDecisionRecord(match[1], body))
+  }
+
+  return records
+}
+
+function extractCurrentDecisionIds(content) {
+  const records = parseDecisionRecords(content)
+  if (records.length === 0) return extractIds(content, 'D')
+  return records
+    .filter(r => !['superseded', 'rejected'].includes(r.status))
+    .map(r => r.id)
+    .sort()
+}
+
+function findBlockingDecisionIssues(content) {
+  return parseDecisionRecords(content)
+    .filter(r => (r.blocker || ['unresolved', 'blocking'].includes(r.status)) && ['P0', 'P1'].includes(r.priority))
+    .map(r => `${r.id} (${r.priority}${r.priorityMissing ? ', priority=missing->P1' : ''}, status=${r.status})`)
+}
+
+function readIfExists(file) {
+  return existsSync(file) ? readFileSync(file, 'utf8') : ''
+}
+
+function warnMissingIds(warnings, ids, targetContent, targetName, sourceName) {
+  for (const id of ids) {
+    if (!targetContent.toUpperCase().includes(id)) {
+      warnings.push(`${targetName} 未引用 ${sourceName} 中的 ${id}`)
+    }
+  }
+}
+
 /**
  * scan 完成校验：检查 7 份 scan 文档 + manifest
  */
@@ -55,7 +166,7 @@ function validateScanOutputs(cwd, changeName, context = {}) {
 
   for (const doc of requiredDocs) {
     if (!existsSync(join(docsRoot, doc))) {
-      errors.push(`scan 文档缺失: ${docsRoot}/${doc}`)
+      errors.push(`scan 文档缺失: ${join(docsRoot, doc)}`)
     }
   }
 
@@ -75,12 +186,93 @@ function validateScanOutputs(cwd, changeName, context = {}) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+/**
+ * brainstorm 完成校验：检查四件套规范文件是否生成
+ */
+function validateBrainstormOutputs(cwd, changeName, context = {}) {
+  const { specRoot } = context
+  const changesRoot = specRoot ? join(specRoot, 'changes') : join(cwd, '.sillyspec', 'changes')
+  if (specRoot && !existsSync(changesRoot)) {
+    return { ok: false, errors: [`平台模式 specRoot 缺少 changes 目录: ${changesRoot}`], warnings: [] }
+  }
+  const changeDir = resolveChangeDir(cwd, changeName, specRoot)
+  const errors = []
+  const warnings = []
+
+  const requiredFiles = ['design.md', 'proposal.md', 'requirements.md', 'tasks.md']
+
+  for (const file of requiredFiles) {
+    if (!existsSync(join(changeDir, file))) {
+      errors.push(`brainstorm 产物缺失: ${join(changeDir, file)}`)
+    }
+  }
+
+  // 内容校验（文件存在时检查关键章节）
+  if (existsSync(join(changeDir, 'proposal.md'))) {
+    const content = readFileSync(join(changeDir, 'proposal.md'), 'utf8')
+    if (!content.includes('不在范围内') && !content.includes('Non-Goals') && !content.includes('非目标')) {
+      warnings.push('proposal.md 缺少「不在范围内/Non-Goals」章节')
+    }
+  }
+
+  if (existsSync(join(changeDir, 'requirements.md'))) {
+    const content = readFileSync(join(changeDir, 'requirements.md'), 'utf8')
+    if (!/FR-\d+/i.test(content)) {
+      warnings.push('requirements.md 缺少 FR 编号的需求项')
+    }
+  }
+
+  if (existsSync(join(changeDir, 'design.md'))) {
+    const content = readFileSync(join(changeDir, 'design.md'), 'utf8')
+    if (!content.includes('文件变更清单') && !content.includes('File Changes') && !content.includes('文件清单')) {
+      warnings.push('design.md 缺少「文件变更清单」章节')
+    }
+    if (!content.includes('风险登记') && !content.includes('Risk') && !content.includes('风险')) {
+      warnings.push('design.md 缺少「风险登记」章节')
+    }
+    if (!content.includes('自审') && !content.includes('Self-Review') && !content.includes('Self-review')) {
+      warnings.push('design.md 缺少「自审」章节')
+    }
+  }
+
+  if (existsSync(join(changeDir, 'tasks.md'))) {
+    const content = readFileSync(join(changeDir, 'tasks.md'), 'utf8')
+    const lines = content.split('\n').filter(l => l.trim().startsWith('-') || l.trim().startsWith('*') || /^\d+\./.test(l.trim()))
+    if (lines.length === 0) {
+      warnings.push('tasks.md 没有任务列表项')
+    }
+  }
+
+  const decisionsFile = join(changeDir, 'decisions.md')
+  if (existsSync(decisionsFile)) {
+    const decisions = readFileSync(decisionsFile, 'utf8')
+    const blockers = findBlockingDecisionIssues(decisions)
+    for (const issue of blockers) {
+      errors.push(`decisions.md 存在 P0/P1 未决阻塞: ${issue}`)
+    }
+    const decisionIds = extractCurrentDecisionIds(decisions)
+    if (decisionIds.length === 0) {
+      warnings.push('decisions.md 存在但没有当前版本 D-xxx@vN 决策 ID')
+    } else {
+      const design = readIfExists(join(changeDir, 'design.md'))
+      const requirements = readIfExists(join(changeDir, 'requirements.md'))
+      const tasks = readIfExists(join(changeDir, 'tasks.md'))
+      warnMissingIds(warnings, decisionIds, design, 'design.md', 'decisions.md')
+      warnMissingIds(warnings, decisionIds, requirements, 'requirements.md', 'decisions.md')
+      warnMissingIds(warnings, decisionIds, tasks, 'tasks.md', 'decisions.md')
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
 /**
  * plan 完成校验：检查 plan.md 生成
  */
-function validatePlanOutputs(cwd, changeName) {
-  const planDir = join(cwd, '.sillyspec', 'changes', changeName)
-  const planFile = join(planDir, 'plan.md')
+function validatePlanOutputs(cwd, changeName, context = {}) {
+  const { specRoot } = context
+  const changeDir = resolveChangeDir(cwd, changeName, specRoot)
+  const planFile = join(changeDir, 'plan.md')
   const errors = []
 
   if (!existsSync(planFile)) {
@@ -88,20 +280,60 @@ function validatePlanOutputs(cwd, changeName) {
   }
 
   const warnings = []
+  if (existsSync(planFile)) {
+    const plan = readFileSync(planFile, 'utf8')
+    const requirements = readIfExists(join(changeDir, 'requirements.md'))
+    const requirementIds = extractIds(requirements, 'FR')
+    warnMissingIds(warnings, requirementIds, plan, 'plan.md', 'requirements.md')
+
+    const decisions = readIfExists(join(changeDir, 'decisions.md'))
+    const blockers = findBlockingDecisionIssues(decisions)
+    for (const issue of blockers) {
+      errors.push(`decisions.md 存在 P0/P1 未决阻塞: ${issue}`)
+    }
+    const decisionIds = extractCurrentDecisionIds(decisions)
+    warnMissingIds(warnings, decisionIds, plan, 'plan.md', 'decisions.md')
+  }
   return { ok: errors.length === 0, errors, warnings }
 }
 
 /**
- * verify 完成校验：检查 verify 报告存在
+ * verify 完成校验：检查变更目录和 verify 产物
  */
-function validateVerifyOutputs(cwd, changeName) {
-  const planDir = join(cwd, '.sillyspec', 'changes', changeName)
+function validateVerifyOutputs(cwd, changeName, context = {}) {
+  const { specRoot } = context
+  const changeDir = resolveChangeDir(cwd, changeName, specRoot)
   const errors = []
   const warnings = []
 
-  // verify 至少应该有 run 记录
-  if (!existsSync(join(planDir, 'plan.md'))) {
-    errors.push(`变更目录缺失: ${planDir}`)
+  if (!existsSync(changeDir)) {
+    errors.push(`变更目录缺失: ${changeDir}`)
+    return { ok: false, errors, warnings }
+  }
+
+  // verify 阶段应该产出 verify-result.md（或类似报告）
+  const verifyResult = join(changeDir, 'verify-result.md')
+  if (!existsSync(verifyResult)) {
+    warnings.push('verify-result.md 不存在（verify 阶段建议产出验证报告）')
+  }
+
+  // 确保核心规范文件仍然存在
+  const requiredDocs = ['design.md', 'plan.md']
+  for (const doc of requiredDocs) {
+    if (!existsSync(join(changeDir, doc))) {
+      errors.push(`核心文档缺失: ${join(changeDir, doc)}`)
+    }
+  }
+
+  if (existsSync(verifyResult)) {
+    const verify = readFileSync(verifyResult, 'utf8')
+    const decisions = readIfExists(join(changeDir, 'decisions.md'))
+    const blockers = findBlockingDecisionIssues(decisions)
+    for (const issue of blockers) {
+      errors.push(`decisions.md 存在 P0/P1 未决阻塞: ${issue}`)
+    }
+    const decisionIds = extractCurrentDecisionIds(decisions)
+    warnMissingIds(warnings, decisionIds, verify, 'verify-result.md', 'decisions.md')
   }
 
   return { ok: errors.length === 0, errors, warnings }
@@ -187,7 +419,7 @@ const contracts = {
     description: '需求分析与设计',
     allowedFrom: [],           // 任何变更的起始阶段
     allowedTo: ['plan'],
-    validators: [],
+    validators: [validateBrainstormOutputs],
   },
   plan: {
     stage: 'plan',
@@ -288,6 +520,11 @@ export function checkTransition(fromStage, toStage) {
     return { allowed: true }
   }
 
+  // 同阶段内重复运行：允许（继续执行当前阶段的下一步）
+  if (fromStage === toStage) {
+    return { allowed: true }
+  }
+
   // archive 特殊处理：从 verify 来的允许，从其他主流程阶段来的需要校验
   if (toStage === 'archive') {
     if (fromStage === 'verify') {

package/src/stages/brainstorm.js

@@ -98,6 +98,9 @@ export const definition = {
     },
     {
       name: '需求范围评估',
+      conditionalWait: true,
+      waitReason: '等待用户确认拆分/批量模式方案',
+      waitOptions: ['同意拆分', '不需要拆分', '走批量模式'],
       prompt: `评估需求复杂度，判断是否需要拆分或走批量模式。
 
 ### 操作
@@ -146,6 +149,11 @@ export const definition = {
     },
     {
       name: '对话式探索',
+      requiresWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 3,
+      waitReason: '等待用户回答需求问题',
+      waitOptions: ['继续补充', '信息够了，进入方案讨论'],
       prompt: `通过对话探索需求细节。
 
 ### 操作
@@ -172,13 +180,84 @@ export const definition = {
       outputHint: '需求理解摘要',
       optional: false
     },
+    {
+      name: '需求澄清 Grill',
+      conditionalWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 8,
+      waitReason: '等待用户回答需求澄清 Grill',
+      waitOptions: ['回答见--answer', '信息够了，结束需求澄清'],
+      prompt: `执行可选的需求澄清 Grill pass。
+
+### 定位
+这是 design.md 之前的需求澄清，不是设计后的 Design Grill。目标是把需求/术语/边界中仍需要人类判断的点问清楚；Design Grill 后续仍会默认执行，用来审查已经写出的 design.md 是否自洽。
+
+### 入口判断
+1. 汇总「对话式探索」后仍未稳定的歧义点，按类型列出：
+   - 术语歧义：同一个词可能指向不同实体/角色/状态
+   - 边界歧义：哪些场景做、哪些不做、失败怎么处理
+   - 前提风险：这个需求是否不该存在，是否已有更简单的现有方案
+   - 代码冲突：用户描述与现有代码/scan/module 文档不一致
+2. 能通过代码或文档确认的不要问用户，先读取：
+   - \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
+   - \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
+   - \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+   - 相关源码文件
+3. 给每个未解决歧义分级：
+   - P0：影响数据模型、权限边界、状态机/工作流、兼容策略、不可逆架构取舍、跨模块所有权
+   - P1：影响用户场景、验收标准、错误处理、默认值
+   - P2：文案、展示细节、低风险交互偏好
+4. 执行规则：
+   - P1/P2 歧义 0-2 个且无 P0：输出"需求澄清 Grill skipped"，在后续设计中内联处理并记录依据
+   - P1/P2 歧义 >= 3 个：进入本 pass，按优先级逐个澄清
+   - 任意 P0 歧义：进入本 pass；如果需要用户判断，必须暂停问一个问题
+5. 不要问用户"要不要 Grill"。本步骤由 AI 根据歧义风险决定是否执行；只在需要业务判断/取舍时等待用户回答。
+
+### 追问策略
+1. **一次只问一个问题**：按 P0 → P1 → P2 顺序，深度优先处理最关键歧义。
+2. **能查代码就不问**：如果问题可由源码、scan 文档、模块文档回答，先查证并给出结论；只有业务判断/取舍才问用户。
+3. **术语碰撞立即指出**：用户用词与 glossary/代码实体/模块文档冲突时，当场说明冲突并要求选择 canonical term。
+4. **模糊词精化**：把"账户/任务/状态/会话/执行"这类多义词拆成明确实体或状态。
+5. **场景压力测试**：用具体 case 逼出边界，例如失败重试、部分成功、历史数据、权限不足、并发修改、兼容旧配置。
+6. **前提挑战优先**：如果现有设计或代码已有简单路径，先说明"可能不该新增"，不要直接优化错误前提。
+
+### 决策记录草稿
+每解决一个有实现影响的问题，生成一个稳定 ID 的记录草稿。不要把闲聊都记录进去。
+
+\`\`\`markdown
+## D-001@v1: <短标题>
+- type: term | boundary | premise | architecture | compatibility | risk
+- status: accepted | rejected | superseded
+- source: user | code | docs
+- question: <被解决的问题>
+- answer: <用户确认或代码查证结果>
+- normalized_requirement: <可测试的约束>
+- impacts: [FR-?, task-?, verify-?]
+- evidence: <文件路径/代码位置/用户回答轮次>
+\`\`\`
+
+### 铁律 — 等待用户
+- 每轮最多提出一个问题，然后调用：
+  \`sillyspec run brainstorm --wait --reason "等待用户回答需求澄清 Grill" --options "回答见--answer,信息够了，结束需求澄清" --output "你的单个问题或查证结论"\`
+- 用户通过 \`--continue --answer "回答"\` 回答后，本步骤会再次执行；继续处理下一个最关键歧义。
+- 达到 maxWaitRounds=8 后，必须总结已确认内容和剩余风险，不要无限追问。
+
+### 输出
+需求澄清结论摘要 + D-xxx@vN 决策记录草稿 + 剩余风险（如有）`,
+      outputHint: '需求澄清和决策记录草稿',
+      optional: true
+    },
     {
       name: '提出 2-3 种方案',
-      prompt: `基于需求理解，提出 2-3 种实现方案。
+      requiresWait: true,
+      waitReason: '等待用户选择方案',
+      waitOptions: ['方案A', '方案B', '方案C'],
+      prompt: `基于需求理解和 Grill 结果，提出 2-3 种实现方案。
 
 ### 操作
 1. 每种方案列出：核心思路、优势、劣势
-2. 给出推荐方案和理由
+2. 如果 Grill 产生 D-xxx@vN 决策记录，方案必须说明覆盖/违反哪些当前版本决策
+3. 给出推荐方案和理由
 
 ### 铁律 — 必须等待用户选择方案
 - **不要替用户选择方案。** 列出方案对比表和推荐后，必须暂停等待用户选择。
@@ -197,6 +276,9 @@ export const definition = {
     },
     {
       name: '分段展示设计',
+      requiresWait: true,
+      waitReason: '等待用户确认设计方案',
+      waitOptions: ['确认', '需要修改', '推翻重来'],
       prompt: `展示完整设计方案供用户确认。
 
 ### 操作
@@ -273,14 +355,26 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
 |---|---|---|---|
 | R-01 | ... | P0/P1/P2 | ... |
 
-11. **自审**（AI 对自身设计的校验）
+11. **决策追踪**（如存在 Grill/重大决策）：
+   - 列出当前版本 D-xxx@vN 决策 ID
+   - 说明每个 D-xxx@vN 被哪些 FR-xxx / 设计章节覆盖
+   - 标注仍未解决的 D-xxx@vN 或剩余风险
+12. **自审**（AI 对自身设计的校验）
 
 ### 操作
 1. 确认变更目录存在：\`mkdir -p .sillyspec/changes/<change-name>\`（Windows 用 \`mkdir .sillyspec\\changes\\<变更名>\` 或 PowerShell \`New-Item -ItemType Directory -Force -Path .sillyspec/changes/<change-name>\`）
    - 变更名格式必须为 \`YYYY-MM-DD-<简短描述>\`（如 \`2026-05-13-user-auth\`）
 2. 将确认的设计写入 \`.sillyspec/changes/<change-name>/design.md\`
-3. 自审检查：
+3. 如果 Grill 或方案讨论产生了实现相关决策，写入 \`.sillyspec/changes/<change-name>/decisions.md\`：
+   - decisions.md 是本次变更的决策台账，不是长期术语表
+   - 只记录有实现/验收影响的决策，闲聊和低风险偏好不记录
+   - 每条记录必须有稳定版本 ID：D-001@v1、D-002@v1 ...
+   - 若后续 Design Grill 修正该决策，新记录使用 D-001@v2，并写明 supersedes: D-001@v1
+   - 每条记录必须包含：type、status、source、question、answer、normalized_requirement、impacts、evidence、priority
+   - 长期术语只在 archive/scan 时再提升到 \`.sillyspec/docs/<project>/glossary.md\`
+4. 自审检查：
    - 需求覆盖：是否完整覆盖对话式探索中确认的需求
+   - Grill 覆盖：如果存在 decisions.md，design.md 是否引用所有当前版本 D-xxx@vN
    - 约束一致性：是否与 CONVENTIONS.md、ARCHITECTURE.md 一致
    - 真实性：表名/字段名/类名/方法名来自真实代码或标注"新增"
    - YAGNI：是否包含不必要功能
@@ -288,8 +382,8 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
    - 非目标清晰：是否明确界定了不做的事
    - 兼容策略（brownfield）：是否说明了回退路径
    - 风险识别：是否识别了关键技术风险和对策
-4. 自审发现问题 → 修改后重新检查
-5. 全部通过 → 进入下一步
+5. 自审发现问题 → 修改后重新检查
+6. 全部通过 → 进入下一步
 
 ### 输出
 design.md 文件路径 + 自审结果
@@ -300,8 +394,108 @@ design.md 文件路径 + 自审结果
       outputHint: 'design.md 文件路径 + 自审结果',
       optional: false
     },
+    {
+      name: 'Design Grill 交叉审查',
+      conditionalWait: true,
+      waitReason: '等待用户处理 Design Grill 发现的结构性问题',
+      waitOptions: ['按推荐修正', '补充回答', '显式跳过'],
+      prompt: `默认执行 Design Grill，对已经写出的 design.md 做交叉审查。
+
+### 定位
+这是设计完成后的质量门，不是需求探索。目标不是继续发散，而是找出 design.md 内部、四件套之间、文档与外部约束之间的结构性矛盾。
+
+### 默认行为
+1. 默认必须执行一次交叉审查；不要让用户凭主观判断决定"要不要 Grill"。
+2. 只有以下情况可以轻量跳过，并必须记录原因：
+   - 用户明确要求 no-grill / 显式跳过
+   - 文档是一页以内、单模块、无状态流转、无 schema/API/兼容策略变更
+   - plan_level 明确为 none，且只改 1-2 个文件
+3. 即使跳过，也要输出"Design Grill skipped"和原因，不能静默跳过。
+
+### 输入材料
+1. 必须读取完整 \`.sillyspec/changes/<change-name>/design.md\`
+2. 读取 proposal.md、requirements.md、tasks.md、decisions.md（如存在）
+3. 读取 scan/module docs：
+   - \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
+   - \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
+   - \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+   - 命中的模块文档
+4. 按 design.md 文件变更清单读取相关源码、测试、配置、schema 或样例数据；矛盾经常藏在设计与外部约束交叉处，素材宁可多读，不要只读摘要。
+
+### 交叉审查模型
+按三层检查并输出 cross-check matrix：
+1. **定义层**：模糊概念是否有可测试定义。例如"高可用""异常数据""本地缓存""重试"。
+2. **一致性层**：跨章节/跨产物是否打架。例如数据流 vs 容错策略、schema vs 输入格式、非目标 vs tasks。
+3. **可行性层**：关键假设是否有来源。例如 P99 延迟、上游 SLA、缓存 TTL、数据量、权限模型、兼容旧配置。
+
+### 交叉点抽取
+重点找这些交叉点：
+- 模块 A 依赖模块 B 的实体/状态/接口
+- requirements.md 的 FR 与 design.md 的数据模型/API/状态机
+- design.md 的容错策略与数据流、缓存、重试、回滚
+- tasks.md 的执行范围与 design.md 的非目标
+- decisions.md 的 D-xxx@vN 与 design.md 当前说法
+- scan/module docs 或源码中的真实约束与 design.md 假设
+
+### 问答处理
+1. 先自动交叉审查，不要一上来问用户。
+2. 没有结构性问题：正常完成，输出"Design Grill passed"，附 cross-check matrix。
+3. 发现问题：
+   - 对能从代码/文档确定的问题，直接给出推荐修正。
+   - 对需要业务判断的问题，每次只问一个最关键问题，然后等待用户。
+   - P0/P1 未决项必须进入 Unresolved Blockers，不能带着进入 plan。
+4. 用户回答后，更新 design.md 和 decisions.md；如果推翻旧决策，新增版本 D-xxx@v2，而不是覆盖 D-xxx@v1。
+
+### decisions.md 版本规则
+\`\`\`markdown
+## D-001@v2: 缓存异常时的 fallback 语义
+- type: definition | consistency | feasibility | boundary | architecture | compatibility | risk
+- priority: P0 | P1 | P2
+- status: accepted | unresolved | rejected | superseded
+- supersedes: D-001@v1
+- source: design-grill
+- question: §3 数据流与 §7 容错策略冲突时以哪个为准？
+- answer: 采用 §7 的重试语义，缓存只作为只读 fallback。
+- normalized_requirement: TTL 过期且上游仍异常时返回 stale 标记，不刷新缓存。
+- impacts: [FR-02, task-03, verify-02]
+- evidence: design.md §3/§7, src/cache/...
+\`\`\`
+
+### 输出格式
+\`\`\`markdown
+## Design Grill Result
+status: passed | needs-user-input | blocked | skipped
+
+## Cross-Check Matrix
+| ID | 层级 | 交叉点 | 证据 A | 证据 B | 结论 | 决策 |
+|---|---|---|---|---|---|---|
+| X-001 | consistency | 数据流 vs 容错 | design §3 | design §7 | conflict | D-001@v2 |
+
+## Question Distribution
+| 分类 | 数量 | 含义 |
+|---|---|---|
+| immediately_answered | N | 心里清楚但文档缺失 |
+| needs_thinking | N | 需要用户判断 |
+| unresolved | N | 真正设计漏洞 |
+
+## Unresolved Blockers
+| ID | priority | 问题 | 阻塞原因 | 下一步 |
+|---|---|---|---|---|
+\`\`\`
+
+### 铁律 — 等待用户
+- 发现 P0/P1 结构性矛盾且需要用户判断时，调用：
+  \`sillyspec run brainstorm --wait --reason "等待用户处理 Design Grill 发现的结构性问题" --options "按推荐修正,补充回答,显式跳过" --output "Design Grill 问题摘要"\`
+- 用户显式跳过时，必须在 decisions.md 记录 accepted risk；P0/P1 skip 仍必须写入 Unresolved Blockers。
+- 完成前必须确认：没有 P0/P1 unresolved blocker；否则不能进入 plan。`,
+      outputHint: 'Design Grill 交叉审查结果',
+      optional: false
+    },
     {
       name: '用户确认并生成规范文件',
+      requiresWait: true,
+      waitReason: '等待用户最终确认设计方案',
+      waitOptions: ['确认', '需要修改', '推翻重来'],
       prompt: `用户确认设计方案，生成规范文件。
 
 ### 操作
@@ -309,9 +503,10 @@ design.md 文件路径 + 自审结果
 2. 暂停等待用户选择：✅ 确认 / ✏️ 修改 / ❌ 推翻重来
 3. 确认后，在 \`.sillyspec/changes/<change-name>/\` 下生成所有规范文件：
    - **design.md**：架构决策、文件变更清单、数据模型、API 设计、兼容策略、风险登记、自审
+   - **decisions.md**（可选）：Grill/重大决策台账，使用 D-001@v1 稳定版本 ID
    - **proposal.md**：动机、关键问题（为什么现有方案不够）、变更范围、不在范围内（显式清单）、成功标准（可验证条件）
-   - **requirements.md**：角色表 + FR 编号需求 + Given/When/Then 行为规格 + 非功能需求
-   - **tasks.md**：任务列表（只列名称和对应文件路径，细节在 plan 阶段展开）
+   - **requirements.md**：角色表 + FR 编号需求 + Given/When/Then 行为规格 + 非功能需求 + D-xxx@vN 覆盖关系
+   - **tasks.md**：任务列表（只列名称、对应文件路径、覆盖的 FR-xxx/D-xxx@vN，细节在 plan 阶段展开）
    - \`git add .sillyspec/\` — 暂存规范文件（不要 commit）
 
 所有规范文件头部必须包含 YAML frontmatter：
@@ -357,6 +552,7 @@ created_at: <now-datetime>
 ## 功能需求
 
 ### FR-01: 需求名称
+覆盖决策：D-001@v1, D-002@v1（如适用）
 Given 前提条件
 When 触发动作
 Then 期望结果
@@ -367,6 +563,28 @@ Then 期望结果
 - 兼容性：...
 - 可回退：...
 - 可测试：...
+
+## 决策覆盖矩阵（如存在 decisions.md）
+| 决策 ID | 覆盖的 FR | 说明 |
+|---|---|---|
+| D-001@v1 | FR-01 | ... |
+\`\`\`
+
+### decisions.md 格式要求（仅在有 Grill/重大决策时生成）
+\`\`\`markdown
+# Decisions
+
+## D-001@v1: 决策短标题
+- type: definition | consistency | feasibility | term | boundary | premise | architecture | compatibility | risk
+- priority: P0 | P1 | P2
+- status: accepted | unresolved | rejected | superseded
+- supersedes:
+- source: user | code | docs
+- question: 被解决的问题
+- answer: 用户确认或代码查证结果
+- normalized_requirement: 可测试的约束
+- impacts: [FR-01, task-01, verify-01]
+- evidence: 用户回答轮次或代码/文档路径
 \`\`\`
 
 ### 后续变更包处理
@@ -395,6 +613,8 @@ Then 期望结果
 - 禁止自动 commit
 - 推翻重来回到 Step 6（对话式探索）
 - 表名/字段名/类名必须来自真实代码或标注"新增"
+- 如果存在 decisions.md，requirements.md 必须引用全部当前版本 D-xxx@vN；没有覆盖的 D-xxx@vN 必须标注为剩余风险
+- 如果 Design Grill 产生 P0/P1 unresolved blocker，必须回到 design 修正，不能进入 plan
 - tasks.md 只列任务名，细节在 plan 阶段展开`,
 
     }