sillyspec 3.25.9 → 3.26.0

package/src/sillyhub-mcp/config.js

@@ -0,0 +1,62 @@
+/**
+ * readMcpConfig — SillyHub MCP 凭据共享 helper（design §7.2 / §6 mcp 凭据数据流）。
+ *
+ * 统一读源，供三处消费点：① client.js 构造函数（_url/_token/_configured/_endpoint）
+ * ② dispatch/probe.js configFingerprint（缓存 key）+ no-config 快速路径 ③ execute.js
+ * getDispatchMode hasConfig（派发三态判定）。
+ *
+ * 优先级：local.yaml mcp 段（mcp.url + mcp.token 两键齐全）>
+ *         process.env.SILLYHUB_MCP_URL/TOKEN fallback；
+ *         mcp 段缺或任一键缺才回退 env。env 也缺 → 返回 null。
+ *
+ * 读法参考 src/dispatch/probe.js readProbeTtlFromLocalYaml 的 best-effort 风格：
+ * join(cwd,'.sillyspec','local.yaml') → existsSync 守卫 → jsYaml.load(readFileSync) → 取 doc.mcp。
+ *
+ * 铁律（design R-07）：
+ * - best-effort 绝不抛：文件不存在 / jsYaml.load 抛 / doc 非对象 全 try/catch 回退 env
+ * - 纯 fs + env 读，绝不发网络（保 probe no-config 快速路径「不发网络」零回归）
+ * - 不引新依赖（js-yaml 复用 dispatch/probe.js:17 已引）
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import jsYaml from 'js-yaml';
+
+/**
+ * 读 SillyHub MCP 凭据（local.yaml mcp 段 + env fallback，best-effort 不抛不发网络）。
+ * @param {string} cwd - 主仓库根（local.yaml 在 <cwd>/.sillyspec/local.yaml）
+ * @returns {{url: string, token: string} | null}
+ *   凭据齐全 → { url（尾斜杠归一）, token }；local.yaml mcp 段缺/缺键 + env 缺 → null
+ */
+export function readMcpConfig(cwd) {
+  // 1. local.yaml mcp 段优先
+  try {
+    const p = join(cwd, '.sillyspec', 'local.yaml');
+    if (existsSync(p)) {
+      const doc = jsYaml.load(readFileSync(p, 'utf8'));
+      if (doc && typeof doc === 'object') {
+        const mcp = doc.mcp;
+        if (mcp && typeof mcp === 'object') {
+          const u = typeof mcp.url === 'string' ? mcp.url : '';
+          const t = typeof mcp.token === 'string' ? mcp.token : '';
+          // 两键齐全才视为有效源（design §7.2「缺键 → 回退 env」）
+          if (u && t) {
+            return { url: u.replace(/\/+$/, ''), token: t };
+          }
+        }
+      }
+    }
+  } catch {
+    // best-effort：文件读 / js-yaml 解析失败 → 继续回退 env
+  }
+
+  // 2. env fallback（兼容旧部署 / 现有测试不设 env 场景，design §9）
+  const eu = process.env.SILLYHUB_MCP_URL;
+  const et = process.env.SILLYHUB_MCP_TOKEN;
+  if (typeof eu === 'string' && eu && typeof et === 'string' && et) {
+    return { url: eu.replace(/\/+$/, ''), token: et };
+  }
+
+  // 3. local.yaml mcp 段缺/缺键 + env 缺 → null（调用方 _configured=false 降级不发网络）
+  return null;
+}

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 路径零风险。
@@ -13,10 +13,12 @@
  *   （平台模式落 <runtimeRoot>/stage-reviews/...，与 execute-runs 同构）
  */
 
-import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs'
+import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync } 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'
+import { resolveRuntimeRoot } from './run/shared.js'
 
 // 文档型 stage review 的合法 reviewType
 export const STAGE_REVIEW_TYPES = ['design', 'plan', 'proposal', 'code', 'acceptance']
@@ -24,10 +26,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 +244,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 +262,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 +315,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 +330,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 +347,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,
     }
@@ -430,3 +435,106 @@ export function printStageReviewResult(result, context = {}) {
     }
   }
 }
+
+/**
+ * 注册一个 stage 级 review（确定性 writer）—— 生成 run 目录 + review.json 骨架（或 adopt
+ * agent 草稿）+ 写 marker，治 tier=independent 时「调度者手动派独立子代理 → marker 不写 →
+ * gate 取错 run」的死锁。与 task 级 generateTaskReviewDrafts（task-review.js）对称。
+ *
+ * docHash 由 CLI 直接 computeDocHash 算（命令有文件访问权），消除 agent 手算 hash 易错
+ * （部分实现 P6.1b defer：仅本 scaffold 路径确定性，不改 agent 自写 review.json 的 hash 链路）。
+ *
+ * 纯新增，不改 validateStageReview / getLatestStageReviewRunId / renderReviewJsonContract 等
+ * 现有函数；self-check 只验 mechanics（schema + docHash），verdict 留给 Stage Review Gate 判。
+ *
+ * @param {object} opts
+ * @param {string} opts.changeName - 变更名
+ * @param {string} opts.stage - brainstorm|plan|execute
+ * @param {string} [opts.fromFile] - adopt 模式：agent 已写的 review.json（保留 verdict/checklist，重算 docHash + 规范化 reviewedFiles[0]）
+ * @param {string} opts.cwd - 主仓 cwd（解析 specBase）
+ * @param {object} [opts.platformOpts] - 平台选项（specRoot 等）
+ * @returns {{ ok: boolean, reviewRunId: string, reviewPath: string, markerPath: string, mode: 'skeleton'|'adopted', mainDoc: string, review: object }}
+ * @throws {Error} changeName 空 / stage 非法 / 主文档缺失 / --from 不存在或 schema 不过
+ */
+export function registerStageReview({ changeName, stage, fromFile, cwd, platformOpts = {} }) {
+  if (!changeName) throw new Error('register-stage-review: changeName 不能为空')
+  if (!stage || !STAGE_MAIN_DOC[stage]) {
+    throw new Error(`register-stage-review: stage 无效 "${stage}"（应为 brainstorm|plan|execute）`)
+  }
+
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+  const changeDir = join(specBase, 'changes', changeName)
+  const reviewType = STAGE_REVIEW_TYPE[stage]
+  const mainDoc = STAGE_MAIN_DOC[stage]
+  const mainDocPath = join(changeDir, mainDoc)
+  if (!existsSync(mainDocPath)) {
+    throw new Error(`register-stage-review: 主审查文档不存在 ${mainDocPath}（${stage} 审 ${mainDoc}），无法算 docHash`)
+  }
+  const docHash = computeDocHash(mainDocPath)
+  if (!docHash) {
+    throw new Error(`register-stage-review: 计算 docHash 失败（computeDocHash 返回 null）：${mainDocPath}`)
+  }
+  const reviewedFiles = [`changes/${changeName}/${mainDoc}`]
+
+  let review
+  let mode
+  if (fromFile) {
+    // adopt 模式：保留 agent 的 verdict/checklist/reviewerNotes/requiredEvidence，仅修 mechanics
+    const fromAbs = existsSync(fromFile) ? fromFile : join(cwd, fromFile)
+    if (!existsSync(fromAbs)) {
+      throw new Error(`register-stage-review: --from 文件不存在 ${fromFile}（相对 cwd ${fromAbs} 也未命中）`)
+    }
+    let parsed
+    try {
+      parsed = JSON.parse(readFileSync(fromAbs, 'utf8'))
+    } catch (e) {
+      throw new Error(`register-stage-review: --from 文件 JSON 解析失败 ${fromAbs}: ${e.message}`)
+    }
+    const schemaResult = validateStageReviewSchema(parsed)
+    if (!schemaResult.ok) {
+      throw new Error(`register-stage-review: --from 文件 schema 校验失败 — ${schemaResult.errors.join('; ')}`)
+    }
+    review = { ...parsed, docHash, reviewedFiles }
+    mode = 'adopted'
+  } else {
+    // 骨架模式：cannot_verify 待审占位（schema 反逃逸：cannot_verify 必须带非空 requiredEvidence）
+    review = {
+      schemaVersion: REVIEW_SCHEMA_VERSION,
+      reviewType,
+      specVerdict: 'cannot_verify',
+      qualityVerdict: 'cannot_verify',
+      reviewedFiles,
+      docHash,
+      requiredEvidence: [`待独立审查子代理对照 ${mainDoc} 逐节核验（骨架由 register-stage-review 生成）`],
+      reviewerNotes: '骨架由 register-stage-review 生成，verdict 待独立审查子代理填写',
+    }
+    mode = 'skeleton'
+  }
+
+  const reviewRunId = generateStageReviewRunId()
+  const reviewDir = join(runtimeRoot, 'stage-reviews', `${stage}-${reviewRunId}`)
+  const reviewPath = join(reviewDir, 'review.json')
+  mkdirSync(reviewDir, { recursive: true })
+  writeFileSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
+
+  const markerPath = stageReviewMarkerPath(runtimeRoot, stage, changeName)
+  if (existsSync(markerPath)) {
+    console.warn(`⚠️ register-stage-review: marker 已存在 ${markerPath}，将被覆盖为 ${reviewRunId}`)
+  }
+  mkdirSync(runtimeRoot, { recursive: true })
+  writeFileSync(markerPath, reviewRunId + '\n')
+
+  // self-check（fail-closed）：刚写的 review 必过 schema + docHash 真实性。只验 mechanics，
+  // 不判 verdict（verdict 是 agent/子代理的审查结论，even fail 也如实落盘，由 Stage Review Gate 裁决）。
+  const schemaRecheck = validateStageReviewSchema(review)
+  if (!schemaRecheck.ok) {
+    throw new Error(`register-stage-review: 写入后 schema 自检失败（不应发生）— ${schemaRecheck.errors.join('; ')}`)
+  }
+  const hashRecheck = verifyStageReviewDocHash(review, [specBase, changeDir, cwd])
+  if (!hashRecheck.ok) {
+    throw new Error(`register-stage-review: 写入后 docHash 自检失败（不应发生）— ${hashRecheck.errors.join('; ')}`)
+  }
+
+  return { ok: true, reviewRunId, reviewPath, markerPath, mode, mainDoc, review }
+}

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）
 
 ### 输出（摘要）
 规范文件路径列表（各一句话说明）