sillyspec 3.25.6 → 3.25.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.25.6",
+  "version": "3.25.8",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/init.js

@@ -123,6 +123,70 @@ function injectInstructions(tool, projectDir) {
   writeFileSync(filePath, content.trimEnd() + '\n\n' + INJECTION_CONTENT);
 }
 
+// ── 注入 CLAUDE.md（claude，版本感知幂等）──
+// 与 codex/gemini/opencode 不同：claude 需要完整 CLAUDE.md 模板 + 版本感知三态。
+// 故 claude 不进 INSTRUCTION_TOOLS，单独走此函数（design: 2026-08-02-init-claude-md）。
+const CLAUDE_TEMPLATE_PATH = join(__dirname, '..', 'templates', 'claude-instruction.md');
+
+/**
+ * 为 Claude Code 注入 CLAUDE.md（版本感知幂等）。
+ * - 不存在：写完整模板（templates/claude-instruction.md）+ 顶部版本注释
+ * - 存在无标记：追加受管段（INJECTION_CONTENT）+ 版本块标记
+ * - 存在同版本标记：跳过
+ * - 存在异版本标记：追加态刷新块 / 完整态仅 stderr 提示
+ * @param {string} projectDir - 源码项目根
+ */
+export function injectClaudeInstructions(projectDir) {
+  const filePath = join(projectDir, 'CLAUDE.md');
+  const version = getVersion();
+  // 完整态顶部注释（新文件首行，轻量、不限制后续编辑）
+  const fullHeader = `<!-- SillySpec v${version} — 由 sillyspec init 生成，可自由编辑；重跑 init 同版本不更新 -->`;
+  // 追加态受管段（包版本块标记，明确"勿手动编辑此段"）
+  const appendBlock =
+    `<!-- SillySpec v${version} START — 由 sillyspec init 注入，勿手动编辑此段 -->\n` +
+    INJECTION_CONTENT.trimEnd() +
+    `\n<!-- SillySpec END -->`;
+
+  // 状态 1：文件不存在 → 写完整模板 + 顶部版本注释
+  if (!existsSync(filePath)) {
+    let template = '';
+    try {
+      template = readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8');
+    } catch {
+      console.error(`❌ [sillyspec] 未找到 Claude 模板：${CLAUDE_TEMPLATE_PATH}`);
+      return;
+    }
+    writeFileSync(filePath, fullHeader + '\n' + template);
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已生成（SillySpec v${version}）`));
+    return;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+
+  // 无任何 `<!-- SillySpec v` 标记 → 状态 2：追加受管段（原文字节保留）
+  const markMatch = content.match(/<!-- SillySpec v(\S+)/);
+  if (!markMatch) {
+    writeFileSync(filePath, content.trimEnd() + '\n\n' + appendBlock + '\n');
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已追加 SillySpec 受管段（v${version}）`));
+    return;
+  }
+
+  const existingVersion = markMatch[1];
+  // 状态 3：同版本 → 跳过（幂等，不写）
+  if (existingVersion === version) return;
+
+  // 状态 4：异版本（升级）。区分追加态（有 START...END 块）/ 完整态（仅顶部注释）。
+  const startBlockRe = /<!-- SillySpec v\S+\s+START[\s\S]*?<!-- SillySpec END -->/;
+  if (startBlockRe.test(content)) {
+    // 4a：追加态 → 用当前版本受管段替换该块（块外用户内容字节保留）
+    writeFileSync(filePath, content.replace(startBlockRe, appendBlock));
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 受管段已升级（v${existingVersion} → v${version}）`));
+  } else {
+    // 4b：完整态 → 不覆盖（保留用户改动），仅 stderr 打印升级提示
+    console.error(`⚠️ [sillyspec] SillySpec 升级 v${existingVersion}→v${version}，CLAUDE.md 未自动更新（保留你的改动）。如需采用新模板：备份后删除 CLAUDE.md 再跑 sillyspec init。`);
+  }
+}
+
 // ── 检测工具 ──
 
 function detectTools(projectDir) {
@@ -273,6 +337,11 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
     }
   }
 
+  // 注入 CLAUDE.md（claude，版本感知幂等三态四分支；claude 不进 INSTRUCTION_TOOLS）
+  if (tools.includes('claude')) {
+    injectClaudeInstructions(projectDir);
+  }
+
   // 复制 skills 到各工具目录
   const skillToolDirs = {
     claude: '.claude/skills',

package/src/progress/consistency-doctor.js

@@ -2,6 +2,7 @@
 // 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm.read / pm._write /
 // pm._ensureRuntimeDir / pm._runtimePath（persistence-core 留 facade 本体）。
 import { appendFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { STAGE_ORDER } from './shared.js';
 
 export class ConsistencyDoctor {
@@ -193,8 +194,46 @@ export class ConsistencyDoctor {
         });
       }
 
-      // Manual a: completed stage 里有 pending/stale/in-progress steps
-      if (sd.status === 'completed' && sd.steps) {
+      // Fix e: execute 阶段 completed stage 有 pending/stale/in-progress step，但 review.json 客观产出已全通过 → 状态脱钩自动修
+      // （坑 verify-archive-flow-pitfalls 坑1+坑5：plan 加 Wave / execute Wave step 未走 --done，但 task 实际有 review.json verdict 且非 fail）
+      // 安全边界：仅当 changeName 有效、source=review.json（客观源可用）且 pending=0（所有 task verdict 通过）才自动修，
+      // 否则回落到 Manual a（保守不动）。不碰非 execute 阶段。
+      let executeAutoFixed = false;
+      if (stageName === 'execute' && changeName && sd.status === 'completed' && sd.steps) {
+        const badSteps = sd.steps.filter(st => ['pending', 'stale', 'in-progress'].includes(st.status));
+        if (badSteps.length > 0) {
+          try {
+            const changeDir = this.pm._changePath(cwd, changeName);
+            if (changeDir && existsSync(changeDir)) {
+              const runtimeRoot = this.pm._runtimePath(cwd);
+              const { summarizeTaskCompletion } = await import('../task-review.js');
+              const summary = summarizeTaskCompletion({ changeDir, runtimeRoot, changeName });
+              if (summary.source === 'review.json' && summary.total > 0 && summary.pending.length === 0) {
+                const desc = `execute: ${badSteps.length} 个 step 状态脱钩（${badSteps.map(st => st.name).join(', ')}）——review.json 客观产出全通过（${summary.completed}/${summary.total}），自动标 completed`;
+                fixable.push({
+                  stage: stageName,
+                  action: 'align_execute_steps_to_reviews',
+                  description: desc,
+                  apply: (d) => {
+                    for (const st of d.stages[stageName].steps) {
+                      if (['pending', 'stale', 'in-progress'].includes(st.status)) {
+                        st.status = 'completed';
+                        st.completedAt = st.completedAt || now;
+                      }
+                    }
+                  },
+                });
+                executeAutoFixed = true;
+              }
+            }
+          } catch (e) {
+            console.warn(`⚠️  execute 产出核验异常（回落 manual）: ${e.message}`);
+          }
+        }
+      }
+
+      // Manual a: completed stage 里有 pending/stale/in-progress steps（execute 已由 Fix e 自动修则跳过）
+      if (!executeAutoFixed && sd.status === 'completed' && sd.steps) {
         const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
         for (const step of badSteps) {
           manual.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed（需手动确认）`);

package/src/progress/stage-machine.js

@@ -97,7 +97,7 @@ export class StageMachine {
       if (stageRow && stageRow.length > 0 && stageRow[0].values.length > 0) {
         const stageId = stageRow[0].values[0][0];
         sqlDb.run(
-          'UPDATE steps SET status = "completed", completed_at = ? WHERE stage_id = ? AND status = "pending"',
+          'UPDATE steps SET status = "completed", completed_at = ? WHERE stage_id = ? AND status IN ("pending", "stale")', // stale 一并回填（reopen --done 场景，坑 brainstorm-reopen-step-state-desync）
           [now, stageId]
         );
       }
@@ -295,11 +295,12 @@ export class StageMachine {
     // 改为：不要求 steps(空=该开始了)；upstream 必须全 completed(pending 不算就绪)——
     // archive 只在 scan/brainstorm/plan/execute/verify 全完成后才可能被推荐。
     for (const s of STAGE_ORDER) {
+      if (s === 'scan') continue  // scan 是 auxiliary（按需显式跑），不作"下一步"推荐——否则未 completed 时恒处 STAGE_ORDER 首位且 upstream 空→恒就绪→误推 scan（回头路，与 complete.js brainstorm/quick 专属分支同类根因）。prompt-control-debt plan-c。
       const sd = data.stages[s];
       if (!sd) continue;
       if (sd.status === 'completed' || sd.status === 'skipped') continue;
       const idx = STAGE_ORDER.indexOf(s);
-      const upstream = STAGE_ORDER.slice(0, idx);
+      const upstream = STAGE_ORDER.slice(0, idx).filter(us => us !== 'scan');  // scan(auxiliary)不算上游——否则 scan 未 completed 会阻塞所有主流程阶段，与上面跳过 scan 的迭代矛盾
       const upstreamOk = upstream.every(us => data.stages[us]?.status === 'completed');
       if (upstreamOk) {
         return {

package/src/quicklog.js

@@ -81,6 +81,36 @@ function sanitizeDesc(description) {
   return s.length > 120 ? s.slice(0, 120) + '…' : s
 }
 
+// 从关联变更的 proposal/design 提取首个 # 标题（去「提案书（Proposal）— / 设计文档（Design）—」固定前缀）。
+// 让 quick --linked-changes 启动时（用户常不带 --input）也能拿到语义标题，而非 (quick 任务) 占位。
+// 读不到任何标题返回 ''（调用方再回退占位符，保持向后兼容）。
+export function deriveTitleFromLinkedChange(specBase, change) {
+  if (!change) return ''
+  for (const f of ['proposal.md', 'design.md']) {
+    let content
+    try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
+    const m = content.match(/^#\s+(.+?)\s*$/m)
+    if (!m) continue
+    const raw = m[1].trim()
+    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc
+    const dash = raw.match(/[—-]\s*(.+)$/)
+    return dash ? dash[1].trim() : raw
+  }
+  return ''
+}
+
+// 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
+// （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
+function extractTitleFromResult(result) {
+  if (!result) return ''
+  const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
+  if (!m) return ''
+  let t = m[1].replace(/[，。；,;].*$/, '').trim() // 截到首个标点，取核心句
+  if (!t) return ''
+  if (t.length > 80) t = t.slice(0, 80) + '…'
+  return t
+}
+
 function sanitizeResult(resultText) {
   // 保留换行：结果块支持字段化结构（需求：/根因：/方案：/结果：...）。多行时 flipEntryInContent
   // 写成字段块（追加在「状态：」行下方），不是单条「结果：<长行>」。仅去首尾空白。
@@ -189,10 +219,13 @@ function tasksPath(specBase, change) {
   return join(specBase, 'changes', change, 'tasks.md')
 }
 
-// 追加未勾选 task；幂等（已含同 qlId 则跳过）
+// 追加未勾选 task；幂等（已含同 qlId 则跳过）。
+// 关联变更目录不存在（笔误 / 未建 / 仅作标签关联）→ 不 fabricate stub 目录（历史坑 quick-change-phantom：
+// mkdirSync 硬造 changes/<名>/tasks.md，致 quick --done 边界审计自造自拦 BLOCK）。关联仍记入
+// QUICKLOG「关联变更」行（allocateQuicklogEntry 独立写入，不依赖本函数）。
 function appendTaskCheckbox(specBase, change, qlId, desc) {
   const dir = join(specBase, 'changes', change)
-  mkdirSync(dir, { recursive: true })
+  if (!existsSync(dir)) return
   const p = tasksPath(specBase, change)
   let content = existsSync(p) ? readFileSync(p, 'utf8') : ''
   if (content.includes(qlId)) return
@@ -215,10 +248,52 @@ async function checkTaskCheckbox(specBase, change, qlId) {
 // 可能是 CRLF，split('\n') 后每行带 \r。原代码 `lines[i] === '状态：进行中'` 精确匹配
 // 恒失败 → 走 splice「兜底插入」→ 条目内同时出现「状态：已完成」+「状态：进行中」。
 // 状态行匹配与「已完成」判断统一用行首前缀匹配，容忍行尾 \r；写入保持 CRLF 不扩大改动。
+// 单行四字段（需求：/根因：/方案：/结果：）切段。先按「字段边界」严格扫描：真实标签 = 上一标签之后首次
+// 出现的、前导是串首/空白/句末标点（。；！？）的对应标签——字段正文引用标签字样（根因写「双层「结果：」
+// 前缀」或正则 split(/(?=需求：|根因：|方案：|结果：)/)）因前导是「/|( 等非边界字符而跳过。严格失败
+// （如真实标签前导是「，」这类弱标点）退回宽松顺序扫描（上一标签之后首次出现）。缺标签返回 null → 落单行
+// 兜底（--done 契约校验仍会拦缺字段）。残余边界：正文引用标签且前导恰好是空白/句末标点时仍可能错位。
+function isFieldBoundary(body, idx) {
+  if (idx <= 0) return true
+  const prev = body[idx - 1]
+  return /\s/.test(prev) || '。；！？'.includes(prev)
+}
+function findBoundaryLabel(body, label, from) {
+  let idx = body.indexOf(label, from)
+  while (idx !== -1 && !isFieldBoundary(body, idx)) {
+    idx = body.indexOf(label, idx + label.length)
+  }
+  return idx
+}
+function scanFields(body, findLabel) {
+  const labels = ['需求：', '根因：', '方案：', '结果：']
+  const positions = []
+  let cursor = 0
+  for (const label of labels) {
+    const idx = findLabel(body, label, cursor)
+    if (idx === -1) return null
+    positions.push(idx)
+    cursor = idx + label.length
+  }
+  return positions.map((start, i) => {
+    const end = i + 1 < positions.length ? positions[i + 1] : body.length
+    return body.slice(start, end).trim()
+  })
+}
+function splitSingleLineFields(body) {
+  return scanFields(body, findBoundaryLabel) ?? scanFields(body, (b, l, f) => b.indexOf(l, f))
+}
+
 function flipEntryInContent(content, qlId, result, changedFiles = []) {
   const lines = content.split('\n')
   const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
   if (startIdx === -1) return null
+  // 翻完成时若能从结果提取「需求：」摘要，刷新标题行（覆盖启动时的占位/弱标题）
+  const newTitle = extractTitleFromResult(result)
+  if (newTitle) {
+    const headerCore = lines[startIdx].match(/^(## \S+ \| [^|]+ \| )/)
+    if (headerCore) lines[startIdx] = headerCore[1] + newTitle
+  }
   let endIdx = lines.length
   for (let i = startIdx + 1; i < lines.length; i++) {
     if (lines[i].startsWith('## ')) { endIdx = i; break }
@@ -241,13 +316,25 @@ function flipEntryInContent(content, qlId, result, changedFiles = []) {
     endIdx += 1
   }
   if (result && !hasResult) {
+    // quick step3 --output 常被压成单行「需求：…根因：…方案：…结果：…」（agent 未加换行），
+    // 直接落盘会得到双层前缀「结果：需求：…结果：…」。把单行四字段归一为多行字段块，省 agent 手工
+    // 拆行精修（prompt-control-debt quick-①）。多行 / 单句结果不受影响。
+    let body = result
+    if (!/\r?\n/.test(body) && /^需求：/.test(body)) {
+      // 单行四字段归一为多行。不能 split(/(?=需求：|根因：|方案：|结果：)/)——正文引用字段标签字样
+      // （如根因里写「双层「结果：」前缀」）会被任意位置误切。改按序扫描：真实标签 = 上一标签之后
+      // 首次出现，字段正文引用更靠后的标签不误断（quick-① 2026-08-04 实证补丁）。缺标签返回 null
+      // → 落单行兜底（--done 契约校验仍会拦缺字段）。
+      const segs = splitSingleLineFields(body)
+      if (segs) body = segs.join('\n')
+    }
     // 多行结果（结构化 需求/根因/方案/结果 字段块）：逐行插入为独立字段行。
     // 单行结果：保持「结果：<一句话>」一行，向后兼容简单用例。
-    if (/\r?\n/.test(result)) {
-      const resultLines = result.split(/\r?\n/).filter(l => l.trim() !== '')
+    if (/\r?\n/.test(body)) {
+      const resultLines = body.split(/\r?\n/).filter(l => l.trim() !== '')
       lines.splice(endIdx, 0, ...resultLines)
     } else {
-      lines.splice(endIdx, 0, `结果：${result}`)
+      lines.splice(endIdx, 0, `结果：${body}`)
     }
   }
   return lines.join('\n')

package/src/run/complete.js

@@ -54,6 +54,22 @@ function validateMetadata(cwd, stageName, specBase) {
   }
 }
 
+/**
+ * 读取 design.md frontmatter 的 scale 字段（brainstorm 末步写入 'small'|'large'）。
+ * completeStep 的下一步提示据此分叉：small→quick，large/读不到→plan（fail-safe 走重流程）。
+ * 只解析首个 YAML frontmatter 块，避免误读正文里的 "scale:"。
+ */
+function readDesignScale(specBase, changeName) {
+  if (!changeName) return null
+  const designPath = join(specBase, 'changes', changeName, 'design.md')
+  if (!existsSync(designPath)) return null
+  const text = readFileSync(designPath, 'utf8')
+  const fm = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
+  if (!fm) return null
+  const m = fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
+  return m ? m[1] : null
+}
+
 /**
  * 验证关键文件是否存在于正确的变更目录下
  * 防止 AI 将文件写到错误的路径
@@ -100,6 +116,36 @@ function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
   }
 }
 
+/**
+ * 坑1：用 --done --answer 解掉「已 waiting 的步骤」。
+ *
+ * completeStep 的 currentIdx 选择（findIndex pending||in-progress）排除 waiting，导致
+ * --done --answer 落到已 --wait 暂停的 requiresWait 步骤时跳过它、--answer 静默丢失、步骤永久
+ * 卡 WAITING、末步报「Step N 等待用户输入」无法 finish。本函数把首个 waiting 步骤拉回 pending
+ * + 补 waitAnswer（对齐 continueStep 对 requiresWait 的 shouldReturnToCurrentStep=回 pending 语义），
+ * 让主流程 requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。
+ *
+ * @param {object[]} steps - stageData.steps（原地修改）
+ * @param {string|null|undefined} doneAnswer - --answer 值；空则不触发（返回 -1）
+ * @param {string} nowStr - 时间戳字符串（用于 waitAnswers[].answeredAt）
+ * @returns {number} 被解的 waiting 步骤 idx；无 waiting 或无 answer 返回 -1
+ */
+export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
+  if (!doneAnswer) return -1
+  const waitIdx = steps.findIndex(s => s && s.status === 'waiting')
+  if (waitIdx === -1) return -1
+  const ws = steps[waitIdx]
+  ws.waitAnswer = doneAnswer
+  ws.waitAnswers = Array.isArray(ws.waitAnswers) ? ws.waitAnswers : []
+  ws.waitAnswers.push({ round: (ws.waitRound || 0) + 1, answer: doneAnswer, answeredAt: nowStr })
+  delete ws.waitReason
+  delete ws.waitOptions
+  delete ws.waitedAt
+  ws.status = 'pending'
+  ws.completedAt = null
+  return waitIdx
+}
+
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, confirmMode = null, isForceBaseline = false, isAllowNew = false } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
@@ -129,7 +175,17 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   const steps = stageData.steps
-  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  let currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  // ── 坑1：--done --answer 解「已 waiting 的步骤」──
+  // findIndex 仅查 pending/in-progress，排除 waiting；故 --done --answer 落到已 --wait 暂停的
+  // requiresWait 步骤时会跳过它、把 --answer 静默丢弃，步骤永久卡 WAITING、末步报「等待用户输入」。
+  // 修复：带 doneAnswer 且存在 waiting 步骤时，把首个 waiting 拉回 pending + 补 waitAnswer，主流程
+  // requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。仅 --answer 触发，普通 --done 零变化。
+  const _resolvedWaitIdx = resolveWaitingStepWithAnswer(steps, options && options.doneAnswer, new Date().toLocaleString('zh-CN', { hour12: false }))
+  if (_resolvedWaitIdx !== -1) {
+    currentIdx = _resolvedWaitIdx
+    console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
+  }
   if (currentIdx === -1) {
     console.error('没有待完成的步骤')
     process.exit(1)
@@ -264,6 +320,23 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）
     await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, platformOpts })
 
+    // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
+    // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤
+    // （reopen --from-step N 把 N+1..end 置 stale，但方案未变、无需重跑），需同步回填为
+    // completed，否则进度数字与实际步骤明细矛盾（阶段已完成 + 6/8）。
+    // 安全边界：仅进入阶段完成分支时才回填（stale 本就被跳过、不回填也照常标 completed），
+    // 不改变单步推进行为；stale 若确需重跑，运行流（stage.js:141-148）会先于本分支转 pending 执行。
+    const staleSteps = steps.filter(s => s.status === 'stale')
+    if (staleSteps.length > 0) {
+      const nowStr = new Date().toLocaleString('zh-CN',{hour12:false})
+      for (const st of staleSteps) {
+        st.status = 'completed'
+        st.completedAt = st.completedAt || nowStr
+      }
+      await pm._write(cwd, progress, changeName)
+      console.log(`  ⚠️ 同步回填 ${staleSteps.length} 个 stale 步骤为 completed（reopen --from-step N 后 --done，方案未变）`)
+    }
+
     stageData.status = 'completed'
     stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -332,6 +405,22 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     } else if (stageName === 'verify') {
       // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
       // 避免校验失败（FAIL / 缺 verify-result.md）时仍声称"验证通过可以归档"。
+    } else if (stageName === 'brainstorm') {
+      // brainstorm 下一步按 design.md 的 scale 分叉（与末步 prompt 的 large→plan / small→quick 对齐），
+      // 不走下方 _getNextSuggestion —— 后者按全局状态机「第一个未完成且上游就绪的阶段」推荐，
+      // 当 scan 未完成时会误推 scan（回头路），与 brainstorm 已完成、应进入 plan/quick 矛盾。
+      // 历史教训：曾因此让 agent 在 brainstorm 完成后被误导去跑 scan。
+      const _bscale = readDesignScale(specBase, changeName)
+      if (_bscale === 'small') {
+        console.log(`\n👉 brainstorm 已完成（small）。下一步：sillyspec run quick --linked-changes ${changeName}`)
+      } else {
+        console.log(`\n👉 brainstorm 已完成。下一步：sillyspec run plan${changeName ? ` --change ${changeName}` : ''}（scale=large 或未标 small 走完整 plan）`)
+      }
+    } else if (stageName === 'quick') {
+      // quick 是收尾阶段（辅助流程，不走主链 scan→archive），完成后该提交，而非推 scan。
+      // 走下方 _getNextSuggestion 会因 scan 是 STAGE_ORDER 首位、永未完成而误推 scan（回头路），
+      // 与 brainstorm 同类问题（见上注释），故给 quick 专属分支。
+      console.log('\n👉 quick 已完成。下一步：提交本次改动（git commit / sillyspec-commit），或 sillyspec run <stage> 继续其他阶段。')
     } else {
       // D1 暗衔接修：阶段刚完成，CLI 本就知道状态机下一步是哪个阶段（_getNextSuggestion），
       // 却只丢一句「下一步由你决定」让 agent 自己猜命令。改为按 progress 实际状态给出精确命令。
@@ -738,7 +827,16 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {
-      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${nextStageHint}${changeName ? ` --change ${changeName}` : ''}`)
+      // brainstorm 按 design.md frontmatter 的 scale 分叉（与末步 prompt 对齐）：
+      //   small → quick --linked-changes（小变更免走完整 plan）；large / 读不到 scale → plan（保守默认）。
+      // 修历史 bug：此处曾硬编码 brainstorm→plan 不读 scale，small 档与末步 prompt（quick）矛盾、误导小变更进 plan。
+      let hintStage = nextStageHint
+      let hintChangeFlag = changeName ? ` --change ${changeName}` : ''
+      if (stageName === 'brainstorm' && changeName && readDesignScale(specBase, changeName) === 'small') {
+        hintStage = 'quick'
+        hintChangeFlag = ` --linked-changes ${changeName}`
+      }
+      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${hintStage}${hintChangeFlag}`)
       if (stageName === 'execute') {
         console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
         console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)

package/src/run/gates.js

@@ -204,6 +204,8 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
   // 自报告 PASS 但实测失败 → 阻断（防止"文案通过"绕过验证）。
   if (stageName === 'verify') {
     const { runVerifyTestCheck, printVerifyTestCheck } = await import('../verify-postcheck.js')
+    // 测试实测是同步 execSync，长套件可跑 2~10min 且中途无输出——先预告避免 agent 误判卡死
+    console.log(`\n⏳ Verify 测试对账：CLI 亲自执行 local.yaml 的 commands.test（同步，耗时可能较长，请等待…）`)
     const testCheck = runVerifyTestCheck({ cwd, specBase, changeName })
     printVerifyTestCheck(testCheck)
     if (testCheck.status === 'failed') {

package/src/run/shared.js

@@ -278,6 +278,11 @@ export function resolveChangeDir(cwd, progress, specDir = null) {
 /**
  * 触发 sync（平台模式走自己的链路，跳过；否则 await import sync.js）。
  */
+// sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
+// fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
+// 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
+const SYNC_TOTAL_TIMEOUT_MS = 8_000
+
 export async function triggerSync(cwd, changeName, platformOpts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
@@ -285,7 +290,15 @@ export async function triggerSync(cwd, changeName, platformOpts = {}) {
     if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) return
     // shared.js 在 src/run/，sync.js 在 src/ → 退一层
     const syncMod = await import('../sync.js')
-    await syncMod.sync(changeName, cwd)
+    let timer
+    try {
+      await Promise.race([
+        syncMod.sync(changeName, cwd),
+        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
+      ])
+    } finally {
+      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
+    }
   } catch (e) {
     // sync.js 不存在或同步失败，静默跳过
     console.warn('⚠️ 同步失败:', e.message)

package/src/run/stage.js

@@ -22,7 +22,7 @@ import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
-import { allocateQuicklogEntry } from '../quicklog.js'
+import { allocateQuicklogEntry, deriveTitleFromLinkedChange } from '../quicklog.js'
 import { checkTransition } from '../stage-contract.js'
 
 export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
@@ -239,8 +239,14 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
         // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
         const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+        // 标题回退：启动 quick 不带 --input 时，从关联变更的 proposal/design 提取语义标题，
+        // 避免 QUICKLOG/tasks.md 落 (quick 任务) 占位（deriveTitleFromLinkedChange 读不到则空→sanitizeDesc 回退占位）。
+        let quickDesc = quickOpts?.taskDescription || ''
+        if (!quickDesc && linkedChanges.length > 0) {
+          quickDesc = deriveTitleFromLinkedChange(specBase, linkedChanges[0])
+        }
         const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
-          description: quickOpts?.taskDescription || '',
+          description: quickDesc,
           linkedChanges,
           allowedFiles,
         })

package/src/stage-review.js

@@ -41,7 +41,7 @@ const STAGE_REVIEW_TYPE = { brainstorm: 'design', plan: 'plan', propose: 'propos
  */
 export function renderReviewJsonContract({ stage, changeDir, reviewRunId, tier } = {}) {
   if (tier === 'self') {
-    return '> review.json 契约:tier=self(变更规模小),无需产出 review.json,当前 agent 自审即可。'
+    return '> review.json 契约:tier=self(此刻 design.md 变更文件数 ≤3,当前 agent 自审即可)。⚠️ 注意:本判定基于此刻 design.md 快照——Stage Review Gate 会以 --done 时刻的 design.md 重新判定,若 design 后续扩大到 >3 文件,tier 将升级为 independent 并硬要求独立审查子代理产出 review.json。以 gate 实际校验结果为准(FAILED 即 independent 需补 review.json),勿据本提示提前断言无需 review.json。'
   }
   const reviewType = STAGE_REVIEW_TYPE[stage] || 'design'
   const mainDoc = STAGE_MAIN_DOC[stage] || 'design.md'
@@ -270,7 +270,13 @@ export function getLatestStageReviewRunId(runtimeRoot, stage, changeName) {
     const markerPath = stageReviewMarkerPath(runtimeRoot, stage, changeName)
     if (existsSync(markerPath)) {
       const content = readFileSync(markerPath, 'utf8').trim()
-      if (content) return content
+      // marker 内容格式校验（execute 复盘 b2）：必须 review- 前缀（generateStageReviewRunId 格式）。
+      // agent 手写 marker 可能误填 execute 的 exec- 前缀 → 按 stage-reviews/<stage>-<runId> 拼目录必找不到，
+      // 与其读坏 ID 报误导错误，不如显式 warn 并退回目录扫描。
+      if (content) {
+        if (/^review-/.test(content)) return content
+        console.warn(`⚠️ stage-review marker ${markerPath} 内容 "${content.slice(0, 40)}" 不是 review- 前缀（应为 generateStageReviewRunId 格式，勿填 execute 的 exec- ID），忽略并退回目录扫描`)
+      }
     }
   } catch {}
 
@@ -284,6 +290,21 @@ export function getLatestStageReviewRunId(runtimeRoot, stage, changeName) {
       .sort()
       .reverse()
     if (!entries[0]) return null
+    // cross-change 防护（execute 复盘 b1）：changeName 提供时按 review.json 的 reviewedFiles[0] 归属过滤。
+    // 契约 reviewedFiles[0] = `changes/<change>/<mainDoc>`（renderReviewJsonContract），据此排除他变更的 review，
+    // 否则批量完成 marker 缺失时可能读到 proxy 等其他变更的 acceptance review 报错误导。
+    if (changeName) {
+      const matching = entries.find(e => {
+        try {
+          const rj = JSON.parse(readFileSync(join(dir, e, 'review.json'), 'utf8'))
+          const r0 = Array.isArray(rj.reviewedFiles) ? String(rj.reviewedFiles[0]) : ''
+          return r0.includes(`changes/${changeName}/`)
+        } catch { return false }
+      })
+      if (matching) return matching.slice(stage.length + 1)
+      console.warn(`⚠️ 无 ${stage} 的 review marker，且 stage-reviews/ 下无归属变更 ${changeName} 的 review（reviewedFiles 应含 changes/${changeName}/）；为避免跨变更串台不再取最新，返回 null（fail-closed，由调用方报缺 review.json）`)
+      return null
+    }
     // entries[0] = "plan-review-2026-..."，剥掉 `${stage}-` 前缀得到 runId "review-2026-..."
     return entries[0].slice(stage.length + 1)
   } catch {

package/src/stages/archive.js

@@ -59,6 +59,9 @@ module-impact.md 第一行标题必须用中文：# 模块影响分析（Module
     },
     {
       name: 'sync-module-docs',
+      // 坑 verify-archive-flow-pitfalls 坑4：缺 requiresWait 时 --continue --answer 会直接标 completed、
+      // agent 无机会按 module-impact.md 写入模块卡片。加 requiresWait 使 --continue 确认后回到本步执行写入
+      requiresWait: true,
       prompt: `根据 module-impact.md 同步更新模块索引和卡片文档。
 
 ### ⚠️ 核心原则：结构化事实改 _module-map.yaml，语义解释改模块卡片

package/src/stages/execute.js

@@ -596,6 +596,13 @@ ${taskSummary}
    - 🔥 热上下文：design.md 非目标/兼容策略 + 当前 Wave 任务（必须加载）
    - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
    - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
+
+### 中断续跑（如曾中断恢复）
+execute 按 Wave 持久化进度，task 级进度靠 plan.md checkbox 勾选。若本 Wave 曾因 429/API 配额/崩溃中断：
+- plan.md 中**已勾选 \`- [x]\` 的 task 已完成，跳过不重跑**（子代理也可能在完成前中断，重跑前先确认该 task 产出文件是否完整）
+- 用 \`sillyspec status\` 查当前进度，重新 \`sillyspec run execute\` 会回到当前 Wave step 继续，**不要从零重置或重跑已完成 Wave**
+- 本 Wave 已完成但不完整（产出缺文件）的 task 补做，不牵连其他 task
+
 ${contractInjection}${prototypeInjection}
 ### 本 Wave 任务
 ${taskList}

package/src/stages/plan-postcheck.js

@@ -532,6 +532,11 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
 
     if (!taskId) errors.push(fsRule.data.messageId.replaceAll('${id}', file))
     if (!title) errors.push(fsRule.data.messageTitle.replaceAll('${id}', file))
+    // title_zh（中文标题）完整性：子代理常为压 plan.js 的 20~40 行硬上限合并 title/title_zh（静默丢失），
+    // postcheck 不校验行数（那是 prompt 劝说）但强制 frontmatter 字段齐全（enforcement 优于放宽劝说）。
+    // 无对应 manifest 文案，内联（其余字段文案走 fsRule.data.messageXxx）。prompt-control-debt plan-b。
+    const titleZh = (fm.match(/^title_zh:\s*(.+)/m)?.[1] || '').trim()
+    if (!titleZh) errors.push(`${taskId || file}: frontmatter 缺少 title_zh（中文标题）——不得为压行数合并/删除字段`)
     if (taskId) allTaskIds.push(taskId)
 
     // 2. allowed_paths 不为空

package/src/stages/plan.js

@@ -241,6 +241,7 @@ task-01 → task-03（最长路径，决定最短交付周期）
 
 ## 全局验收标准
 - [ ] 所有单元测试通过
+- [ ] 集成敏感 task（路由/layout/跨进程装配）建议加集成冒烟验收——组件单测全绿 ≠ 集成正确
 - [ ] （brownfield）未配置新功能时行为不变
 
 ## 覆盖矩阵（如存在 decisions.md）

package/src/stages/verify.js

@@ -38,7 +38,7 @@ export const definition = {
     {
       name: '进度确认',
       migratedFrom: ['状态检查'],
-      prompt: `> 💡 先说清楚：\`sillyspec run verify\`（不带 --done）**只下发执行指令，不会替你跑测试/构建**——真正的测试由你（Agent）在「运行测试和质量扫描」那步自己执行；CLI 只在最后 --done 时亲自跑 local.yaml 的 test 对账。别以为敲了 run verify 就自动验证了。
+      prompt: `> 💡 先说清楚：\`sillyspec run verify\`（不带 --done）**只下发执行指令，不会替你跑测试/构建**——真正的测试由 CLI 在最后 --done 时统一执行（local.yaml 的 commands.test，同步对账可能耗时较长）；「运行测试和质量扫描」那步**不需要你重复手动跑全量**（避免与 CLI 对账重复耗时），只做 lint/静态检查 + 可选快速冒烟。别以为敲了 run verify 就自动验证了。
 
 检查当前进度，确认可以执行 verify。
 
@@ -156,28 +156,25 @@ export const definition = {
     },
     {
       name: '运行测试和质量扫描',
-      prompt: `运行测试和代码质量扫描。
+      prompt: `运行代码质量扫描（测试实测统一由 CLI 对账执行，本步不重复手动跑全量）。
 
 ### 操作
-1. 读取 \`.sillyspec/local.yaml\` 获取构建和测试命令
-2. 如果 local.yaml 有 test 命令，使用它（仅测试变更涉及的模块，非全量）
-3. 如果 local.yaml 无 test 命令，根据项目类型选择：
+1. 读取 \`.sillyspec/local.yaml\` 获取构建、测试和 lint 命令
+2. **不要手动重复跑 commands.test**——CLI 会在最终 --done 时统一执行一次（按变更命中模块子集），本步再跑 = 与 CLI 对账重复耗时（实测 198s×2）。如为提前发现实现问题，可对变更模块做**针对性快速冒烟**（可选，非必需）：
    - Maven：\`mvn test -pl <变更模块> -am\`（仅编译变更模块及其依赖）
    - Gradle：\`./gradlew :<模块>:test\`
    - npm/pnpm：\`pnpm test --filter=<包名>\` 或 \`npm test -- --testPathPattern=<相关文件>\`
    - Python：\`pytest <变更模块路径>/\`
-4. 记录通过/失败数量，分析失败原因
-5. 搜索技术债务：grep TODO/FIXME/HACK/XXX（仅限变更文件）
-6. 如果 local.yaml 有 lint 命令，运行 lint 检查
+3. 如果 local.yaml 有 lint 命令，运行 lint 检查
+4. 搜索技术债务：grep TODO/FIXME/HACK/XXX（仅限变更文件）
 
 ### 注意
-- 不要全量编译/测试整个项目，只测变更涉及的模块
-- 如果变更模块不确定，优先使用 local.yaml 中的命令
-- **CLI 对账机制**：verify 阶段最终 --done 时，CLI 会亲自执行 local.yaml 的 commands.test 并与你的报告对账；实测失败会直接阻断 verify 完成，谎报测试结果没有意义
+- **CLI 对账机制**：verify 阶段最终 --done 时，CLI 会亲自执行 local.yaml 的 commands.test（同步，耗时可能较长）；实测失败会直接阻断 verify 完成，谎报测试结果没有意义
+- 冒烟测试非必需：全量/模块实测结果以 CLI 对账为准，本步跑的结果仅供你提前发现问题并写入验证报告
 
 ### 输出
-测试结果 + 技术债务标记`,
-      outputHint: '测试结果 + 技术债务',
+质量扫描结果 + 技术债务标记`,
+      outputHint: '质量扫描结果 + 技术债务',
       optional: false
     },
     {

package/src/task-review.js

@@ -460,6 +460,21 @@ function runGit(gitDir, args) {
   }).trim()
 }
 
+// porcelain 状态行 → 变更文件路径（对齐 shared.js:343 parsePorcelainPath：`XY path`、引号包裹、
+// rename `R old -> new` 取箭头后）。未 commit 的 working-tree 改动对账用。
+function parsePorcelainFiles(statusOut) {
+  const files = []
+  for (const line of String(statusOut).split('\n')) {
+    if (line.trim() === '') continue
+    let p = line.slice(3).trim()
+    if (p.length >= 2 && p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1).replace(/\\(.)/g, (_, c) => c)
+    const arrow = p.indexOf(' -> ')
+    if (arrow !== -1) p = p.slice(arrow + 4)
+    if (p) files.push(p.replace(/\\/g, '/'))
+  }
+  return files
+}
+
 /**
  * 校验 review.json 的 base/head 是否指向真实 git 提交，且 diff 非空。
  *
@@ -514,23 +529,27 @@ export function verifyReviewGitEvidence(review, gitDir) {
     return { ok: true, emptyDiff: false, errors, warnings, unavailable: false }
   }
 
-  const emptyDiff = diffFiles.length === 0
-  // emptyDiff 回退：子代理可能未 commit，base..head 无 commit diff 但 working-tree 有改动。
-  // 对齐 checkExecuteCodeEvidence（stage-contract.js 同时查 working-tree）语义，避免误判零改动伪造。
-  let workingTreeChanged = false
-  if (emptyDiff) {
-    try {
-      const wtStatus = runGit(gitDir, ['status', '--porcelain'])
-      workingTreeChanged = !!wtStatus && wtStatus.trim().length > 0
-    } catch {}
-    if (workingTreeChanged) {
-      warnings.push(`base..head 无 commit diff（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}），但 working-tree 有未提交改动 —— 按有效改动处理，不判零改动伪造`)
+  // 并入 working-tree 未提交改动（execute 复盘 a）：子代理默认不 commit，base..head 无 commit diff 时
+  // diffFiles 留空 → 下方交叉比对拿空集对非空 changedFiles 必判「完全不相交」伪造，逼 agent 强制 commit
+  // + 改 7 个 review head。对齐 checkExecuteCodeEvidence（stage-contract.js 同时查 working-tree）语义，
+  // 未提交改动也算有效对账源。working-tree 有改动时无条件并入（覆盖「部分 commit + 未提交」）。
+  const commitDiffFiles = diffFiles.slice()
+  try {
+    const wtStatus = runGit(gitDir, ['status', '--porcelain'])
+    if (wtStatus && wtStatus.trim().length > 0) {
+      const wtFiles = parsePorcelainFiles(wtStatus)
+      if (wtFiles.length > 0) diffFiles = diffFiles.concat(wtFiles)
+      if (commitDiffFiles.length === 0) {
+        warnings.push(`base..head 无 commit diff（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}），交叉对账并入 working-tree 未提交改动 ${wtFiles.length} 个文件 —— 按有效改动处理，不判零改动伪造`)
+      }
     }
-  }
-  const effectiveEmptyDiff = emptyDiff && !workingTreeChanged
+  } catch {}
+  diffFiles = [...new Set(diffFiles)].filter(Boolean)
+
+  const emptyDiff = diffFiles.length === 0
 
-  // changedFiles 交叉比对：完全不相交 = review 描述的改动与实际 diff 无关
-  if (!effectiveEmptyDiff && Array.isArray(review.changedFiles) && review.changedFiles.length > 0) {
+  // changedFiles 交叉比对：完全不相交 = review 描述的改动与实际 diff 无关（diffFiles 已含 working-tree）
+  if (!emptyDiff && Array.isArray(review.changedFiles) && review.changedFiles.length > 0) {
     const normalize = (p) => String(p).replace(/^\.\//, '')
     const diffSet = new Set(diffFiles.map(normalize))
     const hasOverlap = review.changedFiles.some(f => {
@@ -543,7 +562,7 @@ export function verifyReviewGitEvidence(review, gitDir) {
     }
   }
 
-  return { ok: errors.length === 0, emptyDiff: effectiveEmptyDiff, errors, warnings, unavailable: false }
+  return { ok: errors.length === 0, emptyDiff, errors, warnings, unavailable: false }
 }
 
 /**

package/src/worktree-apply.js

@@ -94,6 +94,29 @@ function getBlobHashMap(cwd, treeish, files) {
   return map;
 }
 
+/**
+ * apply 的文件清单 = design §6 清单 ∪ plan TaskCard allowed_paths（execute 复盘 c）。
+ *
+ * design §6 常只列源码、漏测试/产物文件，而 task allowed_paths（plan 阶段产出）已含——apply 若只认
+ * design 清单会在测试/产物文件上误拦（assess 用 task allowed_paths 已放行、apply 用 design 清单又拦，
+ * 两 gate 口径不一致）。union 后两源并集为准；plan 已过 validateDesignFileCoverage 单向校验（design ⊆
+ * plan），union 不会放开 design/plan 之外的任意文件（仍拦完全越界文件）。
+ *
+ * @param {string} projectRoot - 主仓库根
+ * @param {string} changeName - 变更名
+ * @returns {Set<string>} 并集清单（无 design 清单且无 task 卡片时为空集）
+ */
+export function resolveApplyAllowSet(projectRoot, changeName) {
+  const allowSet = parseFileChangeList(join(projectRoot, CHANGES_REL, changeName, 'design.md'));
+  const tasksDir = join(projectRoot, CHANGES_REL, changeName, 'tasks');
+  if (existsSync(tasksDir)) {
+    for (const tf of readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))) {
+      for (const p of parseAllowedPaths(readFileSync(join(tasksDir, tf), 'utf8'))) allowSet.add(p);
+    }
+  }
+  return allowSet;
+}
+
 /**
  * apply worktree 变更到主工作区
  *
@@ -178,9 +201,8 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     return result;
   }
 
-  // --- 3. 解析 design.md 文件变更清单 ---
-  const designPath = join(projectRoot, CHANGES_REL, changeName, 'design.md');
-  const allowSet = parseFileChangeList(designPath);
+  // --- 3. 解析 apply 文件清单（design §6 清单 ∪ plan TaskCard allowed_paths，execute 复盘 c） ---
+  const allowSet = resolveApplyAllowSet(projectRoot, changeName);
   const hasAllowList = allowSet.size > 0;
 
   // --- 4. 校验：变更文件 ⊆ 清单（无清单则跳过）---

package/templates/claude-instruction.md

@@ -0,0 +1,23 @@
+# Claude Code 指引
+
+## 项目说明
+本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器，不是给人类直接使用的产品，也不是处理业务逻辑的工具——你（Agent）通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+
+## 核心规则
+1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
+2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
+3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
+4. **小修复 / 小调整走 quick**：`sillyspec run quick`。
+5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
+6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
+7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
+8. **实证核验再 `--done`**：`quick --done` 前，触及 `src`/`test` 的改动先 `npm test` + `npm run lint`；纯 doc/配置改动可跳过（lint 不扫 docs/，空转无信息），以落盘文件与测试结果为准，不信口头"已完成"。
+9. **中途停下用 `sillyspec status` / `sillyspec resume` 存进度**，不直接 commit 半成品。
+10. **实现完成后对照文档验收**（design.md / 模块文档），并检查是否影响已有测试。
+11. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
+12. **hook 拦截提交时禁止跳过**（`.husky/pre-push`），修复问题后再提交。
+13. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
+14. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠；quick 同一 QUICKLOG 按 ql-ID 条目追加，不冲突。
+15. **quicklog 手动精修**：CLI 只写骨架，`--done` 后手动补语义化标题 / 文件多行带括注 / 结果四段。
+16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
+17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。

package/templates/prompts/verify-probes.md

@@ -20,6 +20,7 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 1. 读取变更目录下的 tasks.md，提取所有 checkbox 任务
 2. 对每个 task，**递归**检查对应模块目录及其**所有子目录**下是否存在测试文件（*test*、*spec*、*Test*、*Spec*）——包括模块内 co-located 的 tests/ 目录（如 `backend/app/modules/*/tests/`），**不要只看顶层 `tests/`**，否则会把测试就在模块内部的项目误判为“无测试”
 3. 没有测试文件的 task 标记为 ⚠️ 缺少测试
+4. **集成盲区提示**：测试文件存在 ≠ 集成正确——路由/layout 守卫重定向、跨模块装配这类集成 bug 组件单测覆盖不到，只有集成/冒烟/E2E 才暴露。对路由/layout/跨进程装配敏感的 task，额外检查是否有集成冒烟覆盖；无则标 ⚠️ 集成层未验证（需人工或部署确认）
 
 **探针 4：决策追踪覆盖探针（如存在 decisions.md）**
 1. 从 decisions.md 提取所有当前版本 D-xxx@vN

package/CLAUDE.md

@@ -1,40 +0,0 @@
-# Claude Code 指引
-
-# SillySpec工具定位
-1. 是给Agent调用的CLI工具，非人类直接使用
-2. 管理Agent工作流的CLI工具，非业务工具
-
-## 文件生命周期文档同步
-每次修改 `src/stages/` 下的阶段定义（prompt、步骤、输出文件名等）或 `src/run.js`、`src/progress.js` 等影响文件生命周期的代码后，**必须同步更新** `docs/sillyspec/file-lifecycle.md`，确保文档与代码一致。
-
-### 触发更新的典型改动
-- 新增/删除/重命名阶段步骤
-- 修改步骤 prompt 中的输出文件名（如 verify-result.md）
-- 修改阶段间的流转逻辑（如 archive 归档方式）
-- 新增/删除运行时文件类型（如 gate-status.json）
-- 修改 ProgressManager 的数据存储方式（如 SQLite 表结构变更）
-
-### 更新检查清单
-- [ ] 文件名引用一致（prompt 输出的文件名 == validateFileLocations 期望的文件名）
-- [ ] 阶段步骤描述与 `src/stages/*.js` 一致
-- [ ] 归档/清理流程描述与实际代码逻辑一致
-- [ ] 数据库 Schema 描述与 `src/db.js` 一致
-- [ ] 更新文档头部 `updated_at` 时间戳
-
-## 提示词文档同步（docs/prompt/）
-`docs/prompt/` 收录各阶段 CLI→Agent 的**逐步提示词原文**（人类可读 md 参考）。详见 `docs/prompt/README.md`。
-
-### 数据源关系（重要 — 避免双写漂移）
-- **唯一数据源 = `src/stages/*.js`**（`definition.steps[].prompt`，CLI 运行时读这里）+ `src/run/prompt.js`（注入框架：persona / 铁律 / 占位符替换 / 完成后执行命令模板）。
-- `docs/prompt/*.md` 是源码的**机械提取人类可读镜像**，由 `node docs/prompt/_extract.mjs` 一键再生（源码 → `_extracted.json` → md）。提取脚本对静态阶段直接读 `definition.steps`，对动态阶段（plan/execute）用示例输入跑 `buildPlanSteps`/`buildExecuteSteps` 得到真实 prompt。
-- **禁止手改 md 里的 prompt 原文**（下次提取会被覆盖，且与源码不一致）。要改提示词，改源码后重跑脚本。
-
-### 触发同步的改动
-- 修改 `src/stages/*.js`：`definition.steps[].prompt`、步骤名、步骤增删/重排、wait 配置、`_globalGuardrails`、title/description
-- 修改 `src/run/prompt.js`：persona / 铁律 / 占位符替换 / 完成后执行命令模板
-- 修改 `stage-review.js` / `review-tier.js` / `knowledge-match.js`：影响 `{REVIEW_JSON_CONTRACT}` / `{REVIEW_TIER}` / `{KNOWLEDGE_HIT_REPORT}` 等动态块
-
-### 同步步骤
-1. 改源码
-2. 运行 `node docs/prompt/_extract.mjs`（刷新 `docs/prompt/_extracted.json`）
-3. 按变动同步对应 `docs/prompt/<stage>.md`（prompt 正文以 `_extracted.json` 为准逐字替换）+ 必要时更新 `docs/prompt/README.md`（占位符总表 / persona 表 / CLI 注入框架）