sillyspec 3.25.8 → 3.25.11

package/src/spec-dir-typo.js

@@ -0,0 +1,71 @@
+/**
+ * SillySpec spec 目录拼写变体检测
+ *
+ * review.json missing 时调用：检测 SPEC_ROOT 父目录下是否存在 .sillyspec 的
+ * 近似拼写变体目录（如 .silyspec / .sillyspc），命中则提示「路径疑似拼错」。
+ *
+ * 触发场景：agent/用户手动创建 review.json 时把 .sillyspec 拼错（少 l / 多 k 等），
+ * 文件落到变体目录，CLI 按规范名找不到。给一条模糊匹配提示比静默报 missing 友好。
+ *
+ * 放独立模块（而非 stage-review.js / task-review.js 内联）的原因：两者已存在
+ * stage-review → task-review 的常量依赖，反向 import 会形成循环依赖。
+ */
+
+import { dirname, basename, join } from 'path'
+import { readdirSync } from 'fs'
+
+/**
+ * 计算两字符串的 Levenshtein 编辑距离（大小写不敏感比较字符）。
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  const m = a.length
+  const n = b.length
+  if (m === 0) return n
+  if (n === 0) return m
+  let prev = Array.from({ length: n + 1 }, (_, j) => j)
+  let curr = new Array(n + 1)
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
+    }
+    ;[prev, curr] = [curr, prev]
+  }
+  return prev[n]
+}
+
+/**
+ * 检测 spec 目录拼写变体。
+ * @param {string} runtimeRoot — .runtime 目录绝对路径（= <SPEC_ROOT>/.runtime）
+ * @returns {{ typoDir: string, canonical: string } | null} 命中返回变体目录与规范名，否则 null
+ */
+export function detectSpecDirTypo(runtimeRoot) {
+  if (!runtimeRoot) return null
+  // runtimeRoot = <SPEC_ROOT>/.runtime → SPEC_ROOT = dirname(runtimeRoot)
+  const specRoot = dirname(runtimeRoot)
+  const parent = dirname(specRoot)
+  const canonical = basename(specRoot) // 期望 '.sillyspec'
+  if (!canonical.startsWith('.')) return null // 非隐藏目录命名，跳过（避免误报）
+
+  let siblings = []
+  try {
+    siblings = readdirSync(parent, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name.startsWith('.') && !d.name.startsWith('..') && d.name !== canonical)
+      .map((d) => d.name)
+  } catch {
+    return null
+  }
+  if (siblings.length === 0) return null
+
+  // 编辑距离 ≤2 视为拼写变体（覆盖少 l / 多 k / 漏字母等常见笔误）
+  const typo = siblings.find((name) => {
+    const dist = levenshtein(name, canonical)
+    return dist > 0 && dist <= 2
+  })
+  if (!typo) return null
+  return { typoDir: join(parent, typo), canonical }
+}

package/src/stage-contract-engine.js

@@ -112,13 +112,33 @@ function formatFail(failMessage, absPath) {
     : failMessage
 }
 
+/**
+ * 规则条件判定：condition 不满足时规则跳过(同 enabled=false)。
+ * 用于「某规则仅在特定上下文生效」——如 brainstorm 的 proposal/requirements/tasks 仅在 scale≠small 时必需
+ * (小变更 scale=small 只产 design.md，见 BRAINSTORM_RULES)。
+ *
+ * condition schema: { ctxField: '<ctx 键名>', ne|eq: <值> }
+ *   - ne: ctx[ctxField] !== ne 时条件成立(规则适用);相等则跳过
+ *   - eq: ctx[ctxField] === eq 时条件成立;否则跳过
+ * fail-safe：ctx 或 ctxField 缺失 → ne 判定为「undefined !== ne 值」成立(eq 不成立)，
+ *   即 scale 读不到时四件套仍全要求(保守默认，走重流程)，不会因 condition 误放开必填项。
+ */
+function conditionHolds(condition, ctx) {
+  if (!condition) return true
+  const actual = ctx ? ctx[condition.ctxField] : undefined
+  if ('ne' in condition) return actual !== condition.ne
+  if ('eq' in condition) return actual === condition.eq
+  return true  // 未知操作符,放过(不阻断),避免新操作符上线时误杀
+}
+
 // ============ 主入口 ============
 
 /**
  * 对某 stage 的全部纯 kind 规则跑判定。custom kind / target 基缺失 / enabled=false 的规则计入 skipped。
  *
  * @param {string} stage
- * @param {{ changeDir?: string, docsRoot?: string, archiveDir?: string, specBase?: string }} ctx
+ * @param {{ changeDir?: string, docsRoot?: string, archiveDir?: string, specBase?: string, scale?: string }} ctx
+ *        规则 target.root 解析基目录;额外字段(如 scale)供 rule.condition 按 ctxField 判定(见 conditionHolds)
  * @param {{ readFile?: Function, readDir?: Function }} [io]  默认原生 fs;plan-postcheck 可注入 CRLF-normalizing reader
  * @returns {{ ok: boolean, errors: string[], warnings: string[], applied: string[], skipped: string[] }}
  */
@@ -132,6 +152,7 @@ export function evaluateRules(stage, ctx, io, opts = {}) {
 
   for (const rule of getRulesFor(stage, { source: opts.source })) {
     if (rule.enabled === false) { skipped.push(rule.id); continue }
+    if (rule.condition && !conditionHolds(rule.condition, ctx)) { skipped.push(rule.id); continue }
     if (isCustomKind(rule.kind)) { skipped.push(rule.id); continue }
     const absPath = resolveTargetPath(rule.target, ctx)
     if (absPath == null) { skipped.push(rule.id); continue }

package/src/stage-contract-spec.js

@@ -20,6 +20,9 @@
  *   failMessage 失败报错(逐字 == 现有报错文案;支持 ${path} 占位 → 引擎替换为解析后的绝对路径)
  *   hint?       可选出路提示(renderStageContract 附在 spec 后)
  *   enabled?    默认 true,置 false 灰度停用
+ *   condition?  可选条件对象 { ctxField, ne|eq };不满足时规则跳过(同 enabled=false)。
+ *               供「仅在特定上下文生效」的规则,如 brainstorm proposal/requirements/tasks 仅 scale≠small 时必需
+ *               (小变更只产 design.md)。判定见 stage-contract-engine.js conditionHolds(fail-safe:ctx 字段缺失时 ne 成立)。
  *
  * 纯 kind(stage-contract-engine.dispatchPure 直接判定):
  *   file-exists / dir-exists / literal-any / literal-all / regex / contains-section /
@@ -67,7 +70,7 @@ const BRAINSTORM_RULES = [
     stage: 'brainstorm', source: 'validateBrainstormOutputs', severity: 'error', kind: 'file-exists',
     target: { root: 'change', path: 'design.md' },
     data: {},
-    spec: '产出 `design.md`(四件套之一;brainstorm 四件套齐全才能完成)',
+    spec: '产出 `design.md`(brainstorm 必产;scale=small 时这是唯一必需产物,proposal/requirements/tasks 豁免)',
     failMessage: 'brainstorm 产物缺失: ${path}',
   },
   {
@@ -75,7 +78,9 @@ const BRAINSTORM_RULES = [
     stage: 'brainstorm', source: 'validateBrainstormOutputs', severity: 'error', kind: 'file-exists',
     target: { root: 'change', path: 'proposal.md' },
     data: {},
-    spec: '产出 `proposal.md`(四件套之一)',
+    // scale=small(小变更)豁免:brainstorm 末步指引 small 只产 design.md 后转 quick,四件套不全不应阻断
+    condition: { ctxField: 'scale', ne: 'small' },
+    spec: '产出 `proposal.md`(四件套之一;scale=small 时豁免——小变更只需 design.md)',
     failMessage: 'brainstorm 产物缺失: ${path}',
   },
   {
@@ -83,7 +88,8 @@ const BRAINSTORM_RULES = [
     stage: 'brainstorm', source: 'validateBrainstormOutputs', severity: 'error', kind: 'file-exists',
     target: { root: 'change', path: 'requirements.md' },
     data: {},
-    spec: '产出 `requirements.md`(四件套之一)',
+    condition: { ctxField: 'scale', ne: 'small' },
+    spec: '产出 `requirements.md`(四件套之一;scale=small 时豁免——小变更只需 design.md)',
     failMessage: 'brainstorm 产物缺失: ${path}',
   },
   {
@@ -91,7 +97,8 @@ const BRAINSTORM_RULES = [
     stage: 'brainstorm', source: 'validateBrainstormOutputs', severity: 'error', kind: 'file-exists',
     target: { root: 'change', path: 'tasks.md' },
     data: {},
-    spec: '产出 `tasks.md`(四件套之一)',
+    condition: { ctxField: 'scale', ne: 'small' },
+    spec: '产出 `tasks.md`(四件套之一;scale=small 时豁免——小变更只需 design.md)',
     failMessage: 'brainstorm 产物缺失: ${path}',
   },
   // 内容章节(warning)—— 逐字对齐 validateBrainstormOutputs 内容校验段

package/src/stage-contract.js

@@ -257,15 +257,28 @@ function validateBrainstormOutputs(cwd, changeName, context = {}) {
     return { ok: false, errors: [`平台模式 specRoot 缺少 changes 目录: ${changesRoot}`], warnings: [] }
   }
   const changeDir = resolveChangeDir(cwd, changeName, specRoot)
+  // 读 design.md frontmatter scale(若有)传入引擎 ctx,供 BRAINSTORM_RULES 的 condition 判定:
+  // scale=small → proposal/requirements/tasks 三规则跳过(小变更只产 design.md,与末步 prompt 一致,
+  // 避免"照 Step8 small 指引只写 design.md 后 --done 必撞四件套 error墙")。
+  // fail-safe:design.md 不存在或无 scale → null → condition(ne 'small')成立 → 四件套全要求(保守走重流程)。
+  const designPath = join(changeDir, 'design.md')
+  let scale = null
+  let designContent = null
+  if (existsSync(designPath)) {
+    designContent = readFileSync(designPath, 'utf8')
+    const fm = designContent.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
+    const sm = fm && fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
+    if (sm) scale = sm[1]
+  }
   // 纯 kind 规则(四件套存在性 + proposal/requirements/design 章节 + tasks 列表)由引擎消费
   // stage-contract-spec.js manifest,与报错文案 + prompt 事前契约严格同源(事前给的 == 事后查的)。
   // custom kind(lifecycle / decisions)保留下方旧逻辑,数据/文案在 Batch 3 迁入 manifest。
-  const engineResult = evaluateRules('brainstorm', { changeDir })
+  const engineResult = evaluateRules('brainstorm', { changeDir, scale })
   const errors = [...engineResult.errors]
   const warnings = [...engineResult.warnings]
 
-  if (existsSync(join(changeDir, 'design.md'))) {
-    const content = readFileSync(join(changeDir, 'design.md'), 'utf8')
+  if (designContent) {
+    const content = designContent
 
     // lifecycle-exemption(custom kind):判定算法保留(trigger/exemption/table 三段短路),
     // data + failMessage/exemptionPassedMessage 从 stage-contract-spec.js manifest 同源。
@@ -446,6 +459,16 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
     })
     const conclusion = extractVerifyConclusion(verify)
     if (['integration-critical', 'deployment-critical'].includes(changeRiskProfile.level)) {
+      // 关键词误伤早期引导（坑2，FR-02）：命中高危关键词且无 frontmatter risk_level 时，
+      // 无条件透出 frontmatter 覆盖指引（不依赖 conclusion / evidence），让 agent 早期即可
+      // 判断是否属误判并显式覆盖，而非撞到 evidence gate 末尾才发现出路③。遵 6417a27：不做
+      // body 否定语境扫描，只走 frontmatter 显式覆盖通道。
+      if (!changeRiskProfile.explicit) {
+        warnings.push(
+          `[${changeRiskProfile.level}] 本次变更被关键词判级（命中：${changeRiskProfile.triggers.join(', ')}）。` +
+          `若属关键词误伤（实际未触碰 daemon/session/启动入口/跨进程），可在 design.md frontmatter 加 risk_level: <真实等级>（如 unit-sufficient）显式覆盖后重跑。`
+        )
+      }
       // 显式 risk_level 声明（design frontmatter，非关键词误判）下，PASS WITH NOTES 视为对残留项的
       // 诚实声明，不强求全量集成证据——豁免本就来自 design 的明确判断。自动关键词判级维持严格：
       // PASS WITH NOTES 仍要求证据齐全，防 agent 用 PASS WITH NOTES 绕证据门控。

package/src/stage-review.js

@@ -3,7 +3,7 @@
  *
  * 与 task-review.js 的关系：
  *   task-review 校验 execute 每个 task 的 review.json（git 代码 diff 证据：base/head）。
- *   stage-review 校验 brainstorm/plan/propose/execute-acceptance 的阶段级 review.json
+ *   stage-review 校验 brainstorm/plan/execute-acceptance 的阶段级 review.json
  *   （文档证据：reviewedFiles + docHash）。两者 verdict 语义一致（pass/fail/cannot_verify
  *   三态 + cannot_verify 必须带 requiredEvidence 的反逃逸规则），复用 task-review 导出的
  *   VALID_VERDICTS / REVIEW_SCHEMA_VERSION 常量；task-review.js 本身不改、execute 路径零风险。
@@ -17,6 +17,7 @@ import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs'
 import { join } from 'path'
 import { createHash } from 'crypto'
 import { VALID_VERDICTS, REVIEW_SCHEMA_VERSION } from './task-review.js'
+import { detectSpecDirTypo } from './spec-dir-typo.js'
 
 // 文档型 stage review 的合法 reviewType
 export const STAGE_REVIEW_TYPES = ['design', 'plan', 'proposal', 'code', 'acceptance']
@@ -24,10 +25,10 @@ export const STAGE_REVIEW_TYPES = ['design', 'plan', 'proposal', 'code', 'accept
 // checklist 每项 result 的合法值
 const CHECKLIST_RESULTS = ['pass', 'gap', 'fail']
 
-// stage → 主审查文档(brainstorm/execute 审 design.md;plan 审 plan.md;propose 审 proposal.md)
-const STAGE_MAIN_DOC = { brainstorm: 'design.md', plan: 'plan.md', propose: 'proposal.md', execute: 'design.md' }
+// stage → 主审查文档(brainstorm/execute 审 design.md;plan 审 plan.md)
+const STAGE_MAIN_DOC = { brainstorm: 'design.md', plan: 'plan.md', execute: 'design.md' }
 // stage → reviewType(对齐 gates.js Stage Review Gate 的映射)
-const STAGE_REVIEW_TYPE = { brainstorm: 'design', plan: 'plan', propose: 'proposal', execute: 'acceptance' }
+const STAGE_REVIEW_TYPE = { brainstorm: 'design', plan: 'plan', execute: 'acceptance' }
 
 /**
  * 渲染 review.json 产物契约(markdown)给 review 子代理事前看 —— schema 表 + 完整 JSON 示例 +
@@ -242,7 +243,7 @@ export function generateStageReviewRunId() {
  * （同一 stage 不同变更的 review 各自独立 marker）；changeName 缺失时退化为按 stage 分。
  *
  * @param {string} runtimeRoot - .runtime 绝对路径
- * @param {string} stage - brainstorm|plan|propose|execute
+ * @param {string} stage - brainstorm|plan|execute
  * @param {string} [changeName] - 变更名（防多 change 串台）
  * @returns {string} marker 文件绝对路径
  */
@@ -260,7 +261,7 @@ export function stageReviewMarkerPath(runtimeRoot, stage, changeName) {
  * stage-reviews/<stage>-review-* 目录取字典序最新（向后兼容无 marker 旧数据）。
  *
  * @param {string} runtimeRoot - .runtime 绝对路径
- * @param {string} stage - brainstorm|plan|propose|execute
+ * @param {string} stage - brainstorm|plan|execute
  * @param {string} [changeName] - 变更名（读对应 marker，防多 change 串台）
  * @returns {string|null} run id（如 'review-2026-07-16-143000'），无则 null
  */
@@ -313,7 +314,7 @@ export function getLatestStageReviewRunId(runtimeRoot, stage, changeName) {
 }
 
 /**
- * stage-level review 总校验（brainstorm/plan/propose/execute-acceptance 的 done gate）
+ * stage-level review 总校验（brainstorm/plan/execute-acceptance 的 done gate）
  *
  * 规则（与 task-review.validateTaskReviews 对称）：
  *   - review.json 缺失 → error 阻断
@@ -328,7 +329,7 @@ export function getLatestStageReviewRunId(runtimeRoot, stage, changeName) {
  * tier=independent 才调用。
  *
  * @param {object} opts
- * @param {string} opts.stage - brainstorm|plan|propose|execute
+ * @param {string} opts.stage - brainstorm|plan|execute
  * @param {string} opts.reviewType - design|plan|proposal|code|acceptance
  * @param {string} opts.runtimeRoot - .runtime 绝对路径（平台模式为 runtimeRoot）
  * @param {string} opts.reviewRunId - stage review run id（review-<ts>）
@@ -345,9 +346,12 @@ export function validateStageReview(opts) {
   const reviewPath = join(reviewDir, 'review.json')
 
   if (!reviewRunId || !existsSync(reviewPath)) {
+    const errs = [`缺少 ${stage} 阶段的 stage review.json — tier=independent 要求独立审查子代理产出（期望路径：${reviewPath}）`]
+    const typo = detectSpecDirTypo(runtimeRoot)
+    if (typo) errs.push(`💡 路径疑似拼错：发现 ${typo.typoDir} 目录（应为 ${typo.canonical}），review.json 可能误存于此——检查是否把 .sillyspec 拼成了变体`)
     return {
       ok: false,
-      errors: [`缺少 ${stage} 阶段的 stage review.json — tier=independent 要求独立审查子代理产出（期望路径：${reviewPath}）`],
+      errors: errs,
       warnings,
       review: null,
     }

package/src/stages/archive.js

@@ -51,9 +51,7 @@ module-impact.md 第一行标题必须用中文：# 模块影响分析（Module
    needs_review：如果影响无法完全确定，标记为 true
 
 8. 未匹配到任何模块的文件归入"未匹配文件"表格
-9. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\`
-10. 完成后运行 workflow 检查：
-    \`node -e "import('./src/workflow.js').then(w => { /* 用 loadWorkflow 加载 archive-impact，用 runPostCheck 检查 */ })\``,
+9. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\``,
       outputHint: 'module-impact.md 路径 + 影响摘要',
       optional: false
     },
@@ -128,7 +126,7 @@ module_id: <module-id>
 6. 用户拒绝时，不写入，但提示"module-impact.md 已保留，可稍后手动同步"
 7. 回填 module-impact.md 的"更新结果"表格，区分目标：
    - 目标列写 "\`_module-map.yaml: <module-id>\`" 或 "\`modules/<module-id>.md\`"
-8. **同步完成后**，运行 \`sillyspec modules rebuild\` 刷新索引（如果需要），或手动更新 dependencies.md
+8. **同步完成后**，如需刷新 \`_module-map.yaml\` 索引：\`sillyspec modules rebuild --force\`（默认 dry-run 只预览不写；\`--force\` 才覆盖，但会清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段——与 archive-impact 的「人工备注保护」约束冲突，仅当手动字段已并入骨架或可接受覆盖时用；优先手动更新 dependencies.md / 模块卡片）
 
 ### 输出
 已更新的文件路径列表 + 用户确认状态`,
@@ -157,8 +155,8 @@ module_id: <module-id>
 
 ### 操作
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
-2. \`git add .sillyspec/changes/\` — 暂存归档结果（不要 commit，由用户通过统一提交工具处理）
-3. \`git add .sillyspec/docs/\` — 暂存模块文档更新（如有）
+2. \`git add .sillyspec/changes/archive/\` — 暂存归档结果（archive/ 下仅本次归档新增，不会裹挟 changes/ 下其他活跃变更；不要 commit，由用户通过统一提交工具处理）
+3. \`git add .sillyspec/docs/<project>/modules/\` — 暂存模块文档更新（如有；精确到本次同步的模块文档，勿 add 整个 .sillyspec/docs/）
 4. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
 
 ### 输出

package/src/stages/brainstorm-auto.js

@@ -3,7 +3,7 @@
  *
  * 与 brainstorm.js 的区别：
  * 1. artifact-first：直接写文件，对话只输出摘要
- * 2. 自动决策：基于 AC-001~AC-010 checklist，不频繁请示
+ * 2. 自动决策：基于 AC-001~AC-011 checklist，不频繁请示
  * 3. next-action.json：结构化产物，驱动下游推进
  * 4. 只有 blocking questions 才 wait 用户
  * 5. 步骤从 ~13 步精简为 4 步
@@ -56,7 +56,12 @@ export const definition = {
     },
     {
       name: '需求分析与方案设计',
-      requiresWait: true,
+      // conditionalWait（非 requiresWait）：与主模式 Step3 对齐。prompt 明确「目标明确→跳过追问，
+      // 直接进入方案设计」「checklist 全 ✅ → AUTO_DECIDED」——这两种场景 AI 无需追问，必须能直接 --done。
+      // 若用 requiresWait，CLI 硬门强制要 --answer（complete.js:223），AI 只能伪造 --answer「无需追问」
+      // （正是 Grill 第三病）或 --wait 一个不存在的问题。conditionalWait 让「无需追问」路径直接 --done，
+      // 只在真正需要用户决策（方案选择/拆分确认）时才走 --wait（multi-agent-review B1）。
+      conditionalWait: true,
       repeatableWait: true,
       maxWaitRounds: 5,
       waitReason: '等待用户回答需求问题',
@@ -92,7 +97,7 @@ export const definition = {
 
 #### D. 方案设计（自动决策优先）
 1. 基于需求理解和上下文，提出 1-3 种实现方案
-2. **使用自动决策 checklist（AC-001~AC-010）判断是否需要用户选择：**
+2. **使用自动决策 checklist（AC-001~AC-011）判断是否需要用户选择：**
 
 \`\`\`
 AC-001: 未修改公共 API
@@ -105,12 +110,13 @@ AC-007: 已有项目约定可复用
 AC-008: 不影响向后兼容
 AC-009: 不涉及数据迁移
 AC-010: 单模块范围内可完成
+AC-011: 不涉及业务规则/产品范围/默认行为/用户可见行为变更
 \`\`\`
 
 3. **自动决策判定：**
    - 只有一个明显合理方案 + checklist 全部 ✅ → **自动选择，标记 AUTO_DECIDED**
    - 有多个方案但影响不大（checklist 全部 ✅）→ **自动选推荐方案，标记 AUTO_DECIDED**
-   - 有多个方案且 checklist 有 ❌（影响架构/数据/接口/权限/兼容性）→ **只有这一种情况才暂停等用户选择**
+   - 有多个方案且 checklist 有 ❌（影响架构/数据/接口/权限/兼容性/业务）→ **只有这一种情况才暂停等用户选择**
 
 4. 如果需要用户选择方案：
    - 调用：\`sillyspec run brainstorm --wait --reason "等待用户选择方案" --options "方案A,方案B,方案C" --output "方案对比摘要"\`
@@ -136,15 +142,16 @@ AC-010: 单模块范围内可完成
       prompt: `将设计方案写入文件（artifact-first），不回显正文。
 
 ### 操作
-1. 确保变更目录存在：\`mkdir -p .sillyspec/changes/<change-name>/brainstorm\`
+1. 确保变更目录存在：\`mkdir -p .sillyspec/changes/<change-name>\`
 2. **直接将设计方案写入文件，不要先在对话中输出完整内容再写文件。**
+3. 产物写入**变更根目录**（\`.sillyspec/changes/<change-name>/\`），不要建 \`brainstorm/\` 子目录——stage validator 只认根目录，写进子目录会在 \`--done\` 校验时被判产物缺失。
 
 ### 产物文件
 
-#### design.md（必填，写入 \`brainstorm/design.md\`）
+#### design.md（必填，写入变更根目录 \`design.md\`）
 包含：背景、设计目标、非目标、总体方案、文件变更清单、接口定义、数据模型（如涉及）、兼容策略（brownfield）、风险登记、决策追踪。
 
-#### decisions.md（必填，写入 \`brainstorm/decisions.md\`）
+#### decisions.md（必填，写入变更根目录 \`decisions.md\`）
 记录所有决策：
 \`\`\`markdown
 ## D-001@v1: 决策短标题
@@ -160,13 +167,13 @@ AC-010: 单模块范围内可完成
 - evidence: 代码/文档路径或用户回答轮次
 \`\`\`
 
-#### gaps.md（必填，写入 \`brainstorm/gaps.md\`）
+#### gaps.md（必填，写入变更根目录 \`gaps.md\`）
 记录已识别的缺口。status=BLOCKER 的缺口会在 plan-postcheck 中触发回退。
 
-#### assumptions.md（必填，写入 \`brainstorm/assumptions.md\`）
+#### assumptions.md（必填，写入变更根目录 \`assumptions.md\`）
 记录隐含假设和验证方法。
 
-#### next-action.json（必填，写入 \`brainstorm/next-action.json\`）
+#### next-action.json（必填，写入变更根目录 \`next-action.json\`）
 \`\`\`json
 {
   "status": "ready_for_plan" | "waiting_for_user",
@@ -189,12 +196,12 @@ AC-010: 单模块范围内可完成
 ### 输出（artifact-first）
 只输出摘要：
 \`\`\`
-已生成设计产物（5 个文件）：
-- brainstorm/design.md — 采用 xxx 方案，涉及 N 个文件变更
-- brainstorm/decisions.md — M 个决策，K 个 AUTO_DECIDED
-- brainstorm/gaps.md — J 个缺口，0 个 BLOCKER
-- brainstorm/assumptions.md — L 个假设
-- brainstorm/next-action.json — ready_for_plan / waiting_for_user
+已生成设计产物（5 个文件，均在变更根目录）：
+- design.md — 采用 xxx 方案，涉及 N 个文件变更
+- decisions.md — M 个决策，K 个 AUTO_DECIDED
+- gaps.md — J 个缺口，0 个 BLOCKER
+- assumptions.md — L 个假设
+- next-action.json — ready_for_plan / waiting_for_user
 \`\`\``,
       outputHint: '产物摘要',
       optional: false
@@ -207,13 +214,12 @@ AC-010: 单模块范围内可完成
       prompt: `生成 proposal.md / requirements.md / tasks.md，让用户确认。
 
 ### 操作
-1. 基于 brainstorm/ 下的设计产物，生成规范文件（直接写文件）：
+1. 基于变更根目录下的设计产物（design.md / decisions.md / gaps.md / assumptions.md / next-action.json），生成规范文件（直接写入变更根目录）：
    - **proposal.md**：动机、关键问题、变更范围、不在范围内、成功标准
    - **requirements.md**：角色表 + FR 编号需求 + Given/When/Then + 非功能需求
    - **tasks.md**：任务列表（只列名称，细节在 plan 阶段展开）
-2. 如果 brainstorm/decisions.md 有 AUTO_DECIDED 决策，在变更根目录也写一份 decisions.md
-3. 所有规范文件头部包含 YAML frontmatter
-4. \`git add .sillyspec/\` — 暂存规范文件（不要 commit）
+2. 所有规范文件头部包含 YAML frontmatter
+3. \`git add {SPEC_ROOT}/changes/<change-name>/\` — 暂存本变更的规范文件（勿用 .sillyspec/ 整目录——会裹挟其他活跃变更；不要 commit）
 
 ### 输出（摘要）
 规范文件路径列表（各一句话说明）

package/src/stages/brainstorm.js

@@ -79,7 +79,7 @@ export const definition = {
       maxWaitRounds: 8,
       waitReason: '等待用户回答需求问题或澄清',
       waitOptions: ['回答见--answer', '信息够了，进入方案讨论'],
-      prompt: `通过对话探索需求细节、分析原型（如有）、判断拆分/批量、并对歧义点做需求澄清 Grill。本步骤合并了原有的对话探索、原型分析、需求范围评估、需求澄清 Grill 四个环节——按下方 A→D 顺序按需执行，能一次问清的不要拆成多轮。
+      prompt: `通过对话探索需求细节、分析原型（如有）、判断拆分/批量、并对歧义点做需求澄清 Grill。本步骤合并了原有的对话探索、原型分析、需求范围评估、需求澄清 Grill 四个环节——按下方 A→D 顺序按需执行。提问遵守「一次只问一个」（见 D 节追问策略）：必须问的问题逐个问，能查代码/文档解决的不问；不要把多个歧义打包成一屏清单一次抛给用户（用户记不住、答不全，反而漏掉关键约束）；也不要为凑数把单个问题拖成多轮。
 
 ### A. 原型/设计图分析（如用户提供）
 如果用户提供了截图、图片或 HTML 原型，先分析提取：
@@ -176,7 +176,7 @@ export const definition = {
 ### 铁律 — 不要自问自答 / 等待用户
 - 这是人机协作步骤：提出问题后必须暂停等用户回答，**不要在输出里模拟用户回答然后说"需求已明确"**（命令由 CLI 在下方注入）
 - 需要拆分或批量模式时：列出方案并暂停等用户确认
-- 不需要追问、无歧义、需求已清晰时：可正常完成本步骤（不必强行 --wait）
+- 不需要追问、无歧义、需求已清晰时：可正常完成本步骤（不必强行 --wait）。但「正常完成」的前提是**输出一份可否决的确认清单**——在输出里明确列出「已确认需求点清单」（逐条），让用户能一眼看到并喊停；未与用户确认过任何需求点、纯凭自身判断的场景，不得仅凭「我觉得清晰」直接放行（这是把默认共识伪装成共识的逃逸口）
 - 2-3 轮问答即进入方案讨论；达到 maxWaitRounds=8 后必须总结已确认内容与剩余风险，不要无限追问
 
 ### 输出
@@ -272,6 +272,10 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
 | 修改 | src/xxx/ExistingFile.java | 新增 xx 方法 |
 | 删除 | src/xxx/OldFile.java | 已被 xx 替代 |
 
+   **字段数据流标注**（避免新增字段到 execute 才发现没透传）：当清单含「新增/修改对外字段、接口、DTO、响应体、事件 payload、配置键」时，对应行「说明」列必须交代 producer→consumer 数据流——产出方（producer）→ 每跳流转/归一化点（序列化/反序列化/字段映射/默认值兜底）→ 消费方（consumer）。漏标 = 字段在某跳 dormant（声明了却没透传），到 execute/verify 才暴露，属设计层缺口。
+   - 示例：「修改 daemon.ts：新增 budget_tokens，producer=backend/api-types.ts → ws_hub envelope 透传 → daemon.ts normalizeUsage 归一化（snake→camel）→ consumer=runtime/lease.ts 写 lease」
+   - 仅改内部实现、无对外字段变动时，说明列照常写「新增 xx 方法」即可，无需数据流。
+
 7. **接口定义**：方法签名、数据结构（代码类任务必填）
 7.5. **生命周期契约表**（涉及以下关键词时必填，否则可省略）：
 
@@ -458,7 +462,7 @@ status: passed | needs-user-input | blocked | skipped
 1. **按规模生成规范文件**：
    - **scale=large**：在 \`{SPEC_ROOT}/changes/<change-name>/\` 下生成完整四件套（design.md / decisions.md 可选 / proposal.md / requirements.md / tasks.md），实现路径 → \`sillyspec run plan --change <变更名>\`
    - **scale=small**：只生成/补全 design.md（proposal/requirements/tasks 对 quick 无用，不生成），实现路径 → \`sillyspec run quick --linked-changes <变更名>\`
-   - 两种规模都执行 \`git add .sillyspec/\` — 暂存规范文件（不要 commit，由用户通过统一提交工具处理）。**平台模式跳过 git add**（specRoot 不在 sourceRoot 的 git repo 内）
+   - 两种规模都执行 \`git add {SPEC_ROOT}/changes/<change-name>/\` — 暂存本变更的规范文件（精确到变更目录，勿用 .sillyspec/ 整目录——会裹挟其他活跃变更；不要 commit，由用户通过统一提交工具处理）。**平台模式跳过 git add**（specRoot 不在 sourceRoot 的 git repo 内）
 
 2. 生成完成后展示 design.md 摘要 + **规模评估结果（small/large + 一句依据）** + 实现路径建议，告知用户“如有异议直接说，可修改文件、改 scale 或 --reopen 回退”（不暂停，展示完直接 --done）
 
@@ -472,6 +476,10 @@ created_at: <now-datetime>
 
 ### proposal.md 格式要求
 \`\`\`markdown
+---
+author: <git-user>
+created_at: <now-datetime>
+---
 # 提案书（Proposal）
 
 ## 动机
@@ -495,6 +503,10 @@ created_at: <now-datetime>
 
 ### requirements.md 格式要求
 \`\`\`markdown
+---
+author: <git-user>
+created_at: <now-datetime>
+---
 # 需求规格（Requirements）
 
 ## 角色
@@ -523,6 +535,18 @@ Then 期望结果
 | D-001@v1 | FR-01 | ... |
 \`\`\`
 
+### tasks.md 格式要求（scale=large 时生成骨架，plan 阶段展开）
+\`\`\`markdown
+---
+author: <git-user>
+created_at: <now-datetime>
+---
+# 任务清单（Tasks）
+
+- [ ] task-01: <任务名>
+- [ ] task-02: <任务名>
+\`\`\`
+
 ### decisions.md 格式要求（仅在有 Grill/重大决策时生成）
 \`\`\`markdown
 # 决策记录（Decisions）
@@ -549,7 +573,7 @@ Then 期望结果
    - \`design.md\`：从 MASTER.md 中提取该包的职责描述（标记为「待设计 - 本包 design 在该包进入 brainstorm 时完善」）
    - \`requirements.md\`：从 MASTER.md 中提取该包的需求范围（标记为「待完善」）
    - \`tasks.md\`：创建空任务列表，标记为「待 plan 阶段展开」
-4. \`git add .sillyspec/\` — 暂存所有新增文件（不要 commit，由用户通过统一提交工具处理）。**平台模式跳过 git add**（specRoot 不在 sourceRoot 的 git repo 内）
+4. \`git add {SPEC_ROOT}/changes/<本步骤创建的各变更包名>/\` — 逐个暂存本步骤新建的变更包（勿用 .sillyspec/ 整目录——会裹挟其他活跃变更；不要 commit，由用户通过统一提交工具处理）。**平台模式跳过 git add**（specRoot 不在 sourceRoot 的 git repo 内）
 5. 后续变更包的骨架文件同样必须包含 \`author: <git-user>\` 和 \`created_at: <now-datetime>\`
 
 ### 输出
@@ -563,7 +587,7 @@ Then 期望结果
 - 如果存在 decisions.md，requirements.md 必须引用全部当前版本 D-xxx@vN；没有覆盖的 D-xxx@vN 必须标注为剩余风险
 - 如果 Design Grill 产生 P0/P1 unresolved blocker，必须回到 design 修正，不能进入 plan/quick
 - tasks.md 只列任务名，细节在 plan 阶段展开
-- **规范 md 文件第一行标题用中文**（sillyhub 平台解析识别用）：tasks.md 第一行用 # 任务清单（Tasks）（proposal/design/requirements/decisions 见各自模板，均已含中文标题）`,
+- **规范 md 文件标题用中文**（sillyhub 平台解析识别用，frontmatter 在标题之前）：tasks.md 标题用 # 任务清单（Tasks）（proposal/requirements/tasks/decisions 见各自模板 + design 见「写设计文档并自审」步；均含 frontmatter + 中文标题）`,
 
     }
   ]