sillyspec 3.17.5 → 3.17.6

package/package.json

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

package/src/db.js

@@ -169,6 +169,12 @@ export class DB {
     this._migrateAddColumn('changes', 'isolation_status', 'TEXT');
     this._migrateAddColumn('changes', 'isolation_mode', 'TEXT');
     this._migrateAddColumn('changes', 'isolation_reason', 'TEXT');
+
+    // Migration: add waiting support columns to steps table (idempotent)
+    this._migrateAddColumn('steps', 'wait_reason', 'TEXT');
+    this._migrateAddColumn('steps', 'wait_options', 'TEXT');
+    this._migrateAddColumn('steps', 'wait_answer', 'TEXT');
+    this._migrateAddColumn('steps', 'waited_at', 'TEXT');
   }
 
   /**

package/src/progress.js

@@ -22,7 +22,7 @@ const CHANGES_SUBDIR = 'changes';
 const GLOBAL_FILE = 'global.json';
 const CURRENT_VERSION = 3;
 const VALID_STAGES = ['scan', 'brainstorm', 'propose', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
-const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked'];
+const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting'];
 
 const STAGE_LABELS = {
   brainstorm: '🧠 需求探索',
@@ -207,16 +207,22 @@ export class ProgressManager {
     if (stageIds.length > 0) {
       const placeholders = stageIds.map(() => '?').join(',');
       stepRows = sqlDb.exec(
-        `SELECT stage_id, name, status, output, completed_at, ordering FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`,
+        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`,
         stageIds
       );
     }
     // 按阶段分组步骤
     const stepsByStage = {};
     if (stepRows && stepRows.length > 0) {
-      for (const [stageId, name, status, output, completedAt, ordering] of stepRows[0].values) {
+      for (const [stageId, name, status, output, completedAt, ordering, waitReason, waitOptions, waitAnswer, waitedAt] of stepRows[0].values) {
         if (!stepsByStage[stageId]) stepsByStage[stageId] = [];
-        stepsByStage[stageId].push({ name, status, output, completedAt });
+        stepsByStage[stageId].push({
+          name, status, output, completedAt,
+          ...(waitReason ? { waitReason } : {}),
+          ...(waitOptions ? { waitOptions } : {}),
+          ...(waitAnswer ? { waitAnswer } : {}),
+          ...(waitedAt ? { waitedAt } : {}),
+        });
       }
     }
 
@@ -247,6 +253,10 @@ export class ProgressManager {
         status: s.status,
         output: s.output,
         completedAt: s.completedAt,
+        ...(s.waitReason ? { waitReason: s.waitReason } : {}),
+        ...(s.waitOptions ? { waitOptions: s.waitOptions } : {}),
+        ...(s.waitAnswer ? { waitAnswer: s.waitAnswer } : {}),
+        ...(s.waitedAt ? { waitedAt: s.waitedAt } : {}),
       }));
       stages[stage] = {
         status: info.status,
@@ -330,8 +340,9 @@ export class ProgressManager {
               // UPSERT 步骤（先删再插，steps 表无 UNIQUE 约束）
               sqlDb.run('DELETE FROM steps WHERE stage_id = ? AND name = ?', [stageId, step.name]);
               sqlDb.run(
-                'INSERT INTO steps (stage_id, name, status, output, completed_at, ordering) VALUES (?, ?, ?, ?, ?, ?)',
-                [stageId, step.name, step.status || 'pending', step.output || null, step.completedAt || null, i]
+                'INSERT INTO steps (stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+                [stageId, step.name, step.status || 'pending', step.output || null, step.completedAt || null, i,
+                  step.waitReason || null, step.waitOptions || null, step.waitAnswer || null, step.waitedAt || null]
               );
             }
           }
@@ -917,7 +928,7 @@ export class ProgressManager {
     console.log('  ═══════════════════════════════════════');
     console.log('');
 
-    const statusIcons = { pending: '⬜', 'in-progress': '🔵', completed: '✅', failed: '❌', blocked: '🚫' };
+    const statusIcons = { pending: '⬜', 'in-progress': '🔵', completed: '✅', failed: '❌', blocked: '🚫', waiting: '⏸️' };
 
     for (const stage of VALID_STAGES) {
       const stageData = data.stages[stage] || emptyStage();
@@ -931,7 +942,13 @@ export class ProgressManager {
         for (const step of stageData.steps) {
           const si = statusIcons[step.status] || '○';
           const out = step.output ? ` — ${step.output.slice(0, 60)}` : '';
-          console.log(`    ${si} ${step.name}${out}`);
+          const waitingTag = step.status === 'waiting' ? ' [WAITING]' : ''
+          console.log(`    ${si} ${step.name}${out}${waitingTag}`);
+          if (step.status === 'waiting') {
+            if (step.waitReason) console.log(`       原因：${step.waitReason}`);
+            if (step.waitOptions) console.log(`       选项：${(() => { try { const p = JSON.parse(step.waitOptions); return Array.isArray(p) ? p.join(', ') : step.waitOptions; } catch { return step.waitOptions; }})()}`);
+            if (step.waitedAt) console.log(`       等待时间：${step.waitedAt}`);
+          }
         }
       }
 

package/src/run.js

@@ -10,6 +10,25 @@ import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
 
+// ── Wait State Constants ──
+// 正则匹配：只识别独立一行的标记，避免误伤文档正文引用
+const WAIT_MARKER_RE = /^\s*\[(WAIT_FOR_USER|NEEDS_CONFIRM|NEEDS_DECISION)\]\s*$/m
+const WAIT_MARKERS = ['[WAIT_FOR_USER]', '[NEEDS_CONFIRM]', '[NEEDS_DECISION]']
+
+/**
+ * 格式化 waitOptions 为人类可读字符串
+ */
+function formatWaitOptions(raw) {
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw)
+    if (Array.isArray(parsed)) return parsed.join(', ')
+    return raw
+  } catch {
+    return raw
+  }
+}
+
 /**
  * 解析规范目录路径
  * @param {string} cwd - 项目根目录
@@ -277,7 +296,7 @@ async function ensureStageSteps(progress, stageName, cwd, specDir = null) {
 /**
  * 输出当前步骤的 prompt
  */
-async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}) {
+async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}, prevStepAnswer = null) {
   const step = steps[stepIndex]
   const total = steps.length
   const projectName = dbProjectName || basename(cwd)
@@ -423,6 +442,11 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     }
   }
 
+  if (prevStepAnswer) {
+    console.log(`\n### 📩 上一步用户回答`) 
+    console.log(prevStepAnswer)
+  }
+
   console.log(promptText)
   console.log(`\n### ⚠️ 铁律`)
   console.log('- **文档是核心资产，代码是文档的产物。** 没有文档就没有代码——文档是 AI 的记忆，是团队协作的基础，是后续维护的唯一依据。任何代码产出必须先有对应的设计/规范文档支撑。')
@@ -448,7 +472,16 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
   }
   const changeFlag = changeName ? ` --change ${changeName}` : ''
+  // 检测当前 step prompt 是否包含 WAIT 指令（即可能需要等待用户）
+  const stepPrompt = promptText || ''
+  const mayNeedWait = WAIT_MARKER_RE.test(stepPrompt)
   console.log(`\n### 完成后执行`)
+  if (mayNeedWait) {
+    console.log(`如果需要用户决策（选择方案/确认设计等）：`)
+    console.log(`sillyspec run ${stageName} --wait --reason "等待原因" --options "选项1,选项2"${changeFlag} --output "你的摘要"`)
+    console.log(``)
+    console.log(`如果不需要用户决策，正常完成：`)
+  }
   console.log(`sillyspec run ${stageName} --done${changeFlag} --input "用户原始需求/反馈" --output "你的摘要"`)
 }
 
@@ -664,20 +697,27 @@ export async function runCommand(args, cwd, specDir = null) {
     process.exit(1)
   }
 
-  const isDone = flags.includes('--done')
-  const isSkip = flags.includes('--skip')
-  const isStatus = flags.includes('--status')
-  const isReset = flags.includes('--reset')
-  const isConfirm = flags.includes('--confirm')
-  const isSkipApproval = flags.includes('--skip-approval')
-
   // 平台模式参数（供 SillyHub 等平台调用）
   // --spec-dir 是统一参数名，--spec-root 保留为向后兼容别名
   const getFlagValue = (name) => {
     const idx = flags.indexOf(name)
     return idx !== -1 && flags[idx + 1] ? flags[idx + 1] : null
   }
-  const resolvedSpecDir = specDir || getFlagValue('--spec-dir') || getFlagValue('--spec-root');
+  const isDone = flags.includes('--done')
+  const isSkip = flags.includes('--skip')
+  const isStatus = flags.includes('--status')
+  const isReset = flags.includes('--reset')
+  const isConfirm = flags.includes('--confirm')
+  const isSkipApproval = flags.includes('--skip-approval')
+  const isWait = flags.includes('--wait')
+  const isContinue = flags.includes('--continue')
+  const isNonInteractive = flags.includes('--non-interactive')
+  const isInteractive = flags.includes('--interactive')
+  const waitReason = getFlagValue('--reason')
+  const waitOptions = getFlagValue('--options')
+  const continueAnswer = getFlagValue('--answer')
+  const confirmMode = getFlagValue('--confirm-mode')
+  const resolvedSpecDir = specDir || getFlagValue('--spec-dir') || getFlagValue('--spec-root')
   const platformOpts = {
     specRoot: resolvedSpecDir ? resolve(resolvedSpecDir) : null,
     runtimeRoot: getFlagValue('--runtime-root') ? resolve(getFlagValue('--runtime-root')) : null,
@@ -797,6 +837,8 @@ export async function runCommand(args, cwd, specDir = null) {
   // 未知参数 fail-fast
   const knownFlags = new Set([
     '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval',
+    '--wait', '--continue', '--non-interactive', '--interactive',
+    '--reason', '--options', '--answer', '--confirm-mode',
     '--output', '--input', '--change',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
     '--files', '--allow-new', '--force-baseline',
@@ -891,9 +933,19 @@ export async function runCommand(args, cwd, specDir = null) {
     return await skipStep(pm, progress, stageName, cwd, effectiveChange)
   }
 
+  // --wait: 将 step 设为 waiting（独立于 --done）
+  if (isWait) {
+    return await waitStep(pm, progress, stageName, cwd, outputText, waitReason, waitOptions, { changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts })
+  }
+
+  // --continue: 从 waiting 恢复
+  if (isContinue) {
+    return await continueStep(pm, progress, stageName, cwd, continueAnswer, { changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts })
+  }
+
   // --done
   if (isDone) {
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, platformOpts })
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode })
   }
 
   // 默认：输出当前步骤
@@ -962,6 +1014,18 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
   }
 
   const steps = stageData.steps
+  // ── 检查是否有 waiting step 需要先处理 ──
+  const waitingIdx = steps.findIndex(s => s.status === 'waiting')
+  if (waitingIdx !== -1) {
+    const ws = steps[waitingIdx]
+    console.error(`\n⏸️  Step ${waitingIdx + 1}/${steps.length} 正在等待用户输入：${ws.name}`)
+    if (ws.waitReason) console.error(`   原因：${ws.waitReason}`)
+    if (ws.waitOptions) console.error(`   选项：${formatWaitOptions(ws.waitOptions)}`)
+    console.error(`\n   普通运行无法跳过等待中的步骤。请先处理：`)
+    console.error(`   sillyspec run ${stageName} --continue --answer "你的选择"${changeName ? ` --change ${changeName}` : ''}`)
+    process.exit(1)
+  }
+
   let currentIdx = steps.findIndex(s => s.status !== 'completed' && s.status !== 'skipped')
 
   // ── scanProfile: 根据 project 规模动态裁剪步骤 ──
@@ -1053,7 +1117,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
       stageData.steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
       await pm._write(cwd, progress, changeName)
       // 自动前进到下一步
-      const nextIdx = stageData.steps.findIndex(s => s.status === 'pending')
+      const nextIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
       if (nextIdx !== -1 && defSteps[nextIdx]) {
         console.log('')
         await outputStep(stageName, nextIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
@@ -1181,12 +1245,176 @@ async function archiveChangeDirectory(pm, cwd, progress) {
   console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
 }
 
+// ── Wait Step ──
+
+async function waitStep(pm, progress, stageName, cwd, outputText, waitReason, waitOptions, options = {}) {
+  const { changeName, nonInteractive = false, platformOpts = {} } = options
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+  const stageData = progress.stages[stageName]
+
+  if (!stageData || !stageData.steps) {
+    console.error(`❌ 阶段 ${stageName} 未初始化`)
+    process.exit(1)
+  }
+
+  // 查找下一个 pending 或 in-progress 的步骤
+  const currentIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  if (currentIdx === -1) {
+    console.error('没有可以等待的步骤')
+    process.exit(1)
+  }
+
+  // 非交互模式下拒绝等待
+  if (nonInteractive) {
+    console.error(`❌ Human decision required in non-interactive mode.`)
+    console.error(`   Reason: ${waitReason || '(unknown)'}`)
+    if (waitOptions) console.error(`   Options: ${formatWaitOptions(waitOptions)}`)
+    console.error(`   Fix: rerun with --interactive or provide decision via sillyspec run ${stageName} --continue --answer "..."`)
+    process.exit(2)
+  }
+
+  const now = new Date().toLocaleString('zh-CN', { hour12: false })
+  stageData.steps[currentIdx].status = 'waiting'
+  stageData.steps[currentIdx].waitedAt = now
+  if (outputText) {
+    const MAX_OUTPUT = 200
+    stageData.steps[currentIdx].output = outputText.length > MAX_OUTPUT
+      ? outputText.slice(0, MAX_OUTPUT) + '…' : outputText
+  }
+  if (waitReason) stageData.steps[currentIdx].waitReason = waitReason
+  if (waitOptions) {
+    // 统一存为 JSON 数组
+    try {
+      const parsed = JSON.parse(waitOptions)
+      if (Array.isArray(parsed)) {
+        stageData.steps[currentIdx].waitOptions = JSON.stringify(parsed)
+      } else {
+        stageData.steps[currentIdx].waitOptions = JSON.stringify(waitOptions.split(',').map(o => o.trim()))
+      }
+    } catch {
+      stageData.steps[currentIdx].waitOptions = JSON.stringify(waitOptions.split(',').map(o => o.trim()))
+    }
+  }
+
+  progress.lastActive = now
+  await pm._write(cwd, progress, changeName)
+  triggerSync(cwd, changeName, platformOpts)
+
+  console.log(`⏸️  Step ${currentIdx + 1}/${stageData.steps.length} 已暂停等待：${stageData.steps[currentIdx].name}`)
+  if (waitReason) console.log(`   原因：${waitReason}`)
+  if (waitOptions) console.log(`   选项：${formatWaitOptions(waitOptions)}`)
+  console.log(`   继续时执行：sillyspec run ${stageName} --continue --answer "你的选择"${changeName ? ` --change ${changeName}` : ''}`)
+}
+
+// ── Continue Step ──
+
+async function continueStep(pm, progress, stageName, cwd, answer, options = {}) {
+  const { changeName, platformOpts = {} } = options
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+  const stageData = progress.stages[stageName]
+
+  if (!stageData || !stageData.steps) {
+    console.error(`❌ 阶段 ${stageName} 未初始化`)
+    process.exit(1)
+  }
+
+  if (!answer) {
+    console.error('❌ --continue 需要 --answer 参数')
+    process.exit(1)
+  }
+
+  // 查找 waiting 的步骤
+  const waitingSteps = stageData.steps.map((s, i) => ({ ...s, idx: i })).filter(s => s.status === 'waiting')
+  if (waitingSteps.length === 0) {
+    console.error('没有处于等待状态的步骤')
+    process.exit(1)
+  }
+  if (waitingSteps.length > 1) {
+    console.error(`❌ 检测到 ${waitingSteps.length} 个等待中的步骤，无法确定恢复目标：`)
+    for (const ws of waitingSteps) {
+      console.error(`   Step ${ws.idx + 1}: ${ws.name}${ws.waitReason ? `（${ws.waitReason}）` : ''}`)
+    }
+    console.error(`   请使用 --reset 重置，或手动修复 DB`)
+    process.exit(1)
+  }
+  const currentIdx = waitingSteps[0].idx
+
+  const now = new Date().toLocaleString('zh-CN', { hour12: false })
+  stageData.steps[currentIdx].status = 'completed'
+  stageData.steps[currentIdx].completedAt = now
+  stageData.steps[currentIdx].waitAnswer = answer
+
+  // 合并 waiting 信息到 output
+  const prevOutput = stageData.steps[currentIdx].output || ''
+  const waitInfo = stageData.steps[currentIdx].waitReason || ''
+  if (waitInfo) {
+    stageData.steps[currentIdx].output = prevOutput
+      ? `${prevOutput} | 用户选择：${answer}`
+      : `用户选择：${answer}`
+  }
+
+  // 清除等待状态
+  delete stageData.steps[currentIdx].waitReason
+  delete stageData.steps[currentIdx].waitOptions
+  delete stageData.steps[currentIdx].waitedAt
+
+  progress.lastActive = now
+  await pm._write(cwd, progress, changeName)
+  triggerSync(cwd, changeName, platformOpts)
+
+  console.log(`✅ Step ${currentIdx + 1}/${stageData.steps.length} 已继续：${stageData.steps[currentIdx].name}`)
+  console.log(`   回答：${answer}`)
+
+  // Append to user-inputs.md
+  const inputsPath = join(specBase, '.runtime', 'user-inputs.md')
+  const entry = `\n## ${now} | ${changeName || '?'} | ${stageName}: ${stageData.steps[currentIdx].name} [CONTINUED]\n- 回答：${answer}\n`
+ appendFileSync(inputsPath, entry)
+
+  // 检查阶段是否全部完成
+  const nextPendingIdx = stageData.steps.findIndex(s => s.status === 'pending')
+  const nextWaitingIdx = stageData.steps.findIndex(s => s.status === 'waiting')
+  if (nextPendingIdx === -1 && nextWaitingIdx === -1) {
+    stageData.status = 'completed'
+    stageData.completedAt = now
+    await pm._write(cwd, progress, changeName)
+    console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)
+    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
+  }
+
+  // 输出下一步
+  const defSteps = await getStageSteps(stageName, cwd, progress)
+  if (nextPendingIdx !== -1 && defSteps) {
+    console.log('')
+    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, answer)
+  } else if (nextWaitingIdx !== -1 && defSteps) {
+    // 下一个步骤也在等待状态
+    const ws = stageData.steps[nextWaitingIdx]
+    console.log(`\n⏸️  Step ${nextWaitingIdx + 1}/${stageData.steps.length} 仍在等待：${ws.name}`)
+    if (ws.waitReason) console.log(`   原因：${ws.waitReason}`)
+    console.log(`   继续：sillyspec run ${stageName} --continue --answer "..."${changeName ? ` --change ${changeName}` : ''}`)
+  }
+
+  return { stageCompleted: false, currentIdx, nextPendingIdx: nextPendingIdx }
+}
+
 async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {} } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, confirmMode = null } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
   const scanProfile = stageData?.scanProfile || null
 
+  // ── WAIT MARKER 硬校验 ──
+  // 如果 output 包含等待标记，拒绝 --done 推进
+  if (outputText) {
+    const match = WAIT_MARKER_RE.exec(outputText)
+    if (match) {
+      console.error(`❌ Refused: step output contains ${match[1]} — human input required.`)
+      console.error(`   使用 --wait 替代 --done，例如：`)
+      console.error(`   sillyspec run ${stageName} --wait --reason "等待用户决策" --output "你的摘要"${changeName ? ` --change ${changeName}` : ''}`)
+      process.exit(1)
+    }
+  }
+
   // scanProfile 非 deep 模式：截断 outputText 减少 token 传递
   let effectiveOutput = outputText
   if (scanProfile && scanProfile.mode !== 'deep' && outputText && outputText.length > 1000) {
@@ -1198,12 +1426,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   }
 
   const steps = stageData.steps
-  const currentIdx = steps.findIndex(s => s.status === 'pending')
-
-  if (currentIdx === -1) {
-    console.error('没有待完成的步骤')
-    process.exit(1)
-  }
+  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
 
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -1407,9 +1630,20 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     }
   }
 
-  const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
+  const nextPendingIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
 
   if (nextPendingIdx === -1) {
+    // 也检查是否有 waiting 的步骤
+    const hasWaiting = steps.some(s => s.status === 'waiting')
+    if (hasWaiting) {
+      // 有等待中的步骤，阶段未完成
+      progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+      await pm._write(cwd, progress, changeName)
+      const wsIdx = steps.findIndex(s => s.status === 'waiting')
+      console.log(`\n⏸️  阶段暂停：Step ${wsIdx + 1} 等待用户输入`)
+      if (steps[wsIdx].waitReason) console.log(`   原因：${steps[wsIdx].waitReason}`)
+      return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
+    }
     stageData.status = 'completed'
     stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -1700,10 +1934,16 @@ async function skipStep(pm, progress, stageName, cwd, changeName) {
   }
 
   const steps = stageData.steps
-  const currentIdx = steps.findIndex(s => s.status === 'pending')
+  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
 
   if (currentIdx === -1) {
-    console.error('没有待跳过的步骤')
+    const wsIdx = steps.findIndex(s => s.status === 'waiting')
+    if (wsIdx !== -1) {
+      console.error(`⏸️  Step ${wsIdx + 1} 正在等待用户输入，不能跳过。`)
+      console.error(`   请先使用 --continue --answer "..." 继续，或用 --reset 重置。`)
+    } else {
+      console.error('没有待跳过的步骤')
+    }
     process.exit(1)
   }
 
@@ -1722,10 +1962,17 @@ async function skipStep(pm, progress, stageName, cwd, changeName) {
 
   console.log(`⏭️ Step ${currentIdx + 1}/${steps.length} 已跳过：${steps[currentIdx].name}`)
 
-  const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
+  const nextPendingIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
   if (nextPendingIdx !== -1 && defSteps) {
     console.log('')
     await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
+  } else {
+    const wsIdx = steps.findIndex(s => s.status === 'waiting')
+    if (wsIdx !== -1) {
+      console.log(`\n⏸️  Step ${wsIdx + 1}/${steps.length} 正在等待：${steps[wsIdx].name}`)
+      if (steps[wsIdx].waitReason) console.log(`   原因：${steps[wsIdx].waitReason}`)
+      console.log(`   继续：sillyspec run ${stageName} --continue --answer "..."${changeName ? ` --change ${changeName}` : ''}`)
+    }
   }
 }
 
@@ -1746,7 +1993,7 @@ function showStatus(progress, stageName) {
   console.log(`阶段：${stageName}（${stageDef.title}）`)
   console.log(`进度：[${bar}] ${completed}/${steps.length}\n`)
 
-  const firstPending = steps.findIndex(s => s.status === 'pending')
+  const firstPending = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
 
   if (progress.batchProgress) {
     const bp = progress.batchProgress
@@ -1765,9 +2012,15 @@ function showStatus(progress, stageName) {
   }
 
   steps.forEach((step, i) => {
-    const icon = step.status === 'completed' ? '✅' : step.status === 'skipped' ? '⏭️' : '⬜'
-    const isCurrent = step.status === 'pending' && i === firstPending
-    console.log(`${icon} Step ${i + 1}: ${step.name}${isCurrent ? ' ← 当前' : ''}`)
+    const icon = step.status === 'completed' ? '✅' : step.status === 'skipped' ? '⏭️' : step.status === 'waiting' ? '⏸️' : '⬜'
+    const isCurrent = (step.status === 'pending' || step.status === 'in-progress') && i === firstPending
+    const isWaiting = step.status === 'waiting'
+    console.log(`${icon} Step ${i + 1}: ${step.name}${isCurrent ? ' ← 当前' : ''}${isWaiting ? ' [WAITING]' : ''}`)
+    if (isWaiting) {
+      if (step.waitReason) console.log(`       原因：${step.waitReason}`)
+      if (step.waitOptions) console.log(`       选项：${formatWaitOptions(step.waitOptions)}`)
+      if (step.waitedAt) console.log(`       等待时间：${step.waitedAt}`)
+    }
   })
 }
 
@@ -1849,8 +2102,16 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
     console.log('')
 
     const defSteps = await getStageSteps(currentStage, cwd, progress)
-    const pendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending') ?? -1
+    const pendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
     if (pendingIdx === -1) {
+      const wsIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'waiting') ?? -1
+      if (wsIdx !== -1) {
+        const ws = progress.stages[currentStage].steps[wsIdx]
+        console.log(`⏸️  Step ${wsIdx + 1} 等待用户输入：${ws.name}`)
+        if (ws.waitReason) console.log(`   原因：${ws.waitReason}`)
+        console.log(`   继续：sillyspec run auto --continue --answer "..."`)
+        return
+      }
       const next = nextInFlow(currentStage)
       if (next) console.log(`${currentStage} is complete. Run: sillyspec run auto --done --output "${currentStage} complete"`)
       else console.log('All auto flow stages are complete.')
@@ -1883,7 +2144,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
   if (!result) return
   progress = await pm.read(cwd, changeName)
 
-  const nextPendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending') ?? -1
+  const nextPendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
   if (nextPendingIdx !== -1) {
     const defSteps = await getStageSteps(currentStage, cwd, progress)
     // execute 阶段启动前检查审批
@@ -1926,7 +2187,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
 
   console.log(`\n${currentStage} complete. Auto advanced to ${next}.`)
   const nextSteps = await getStageSteps(next, cwd, progress)
-  const firstPending = progress.stages[next]?.steps?.findIndex(step => step.status === 'pending') ?? -1
+  const firstPending = progress.stages[next]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
   if (firstPending !== -1) {
     // execute 阶段启动前检查审批
     if (next === 'execute' && !skipApproval) {

package/src/stages/archive.js

@@ -11,7 +11,8 @@ export const definition = {
 1. 读取 \`.sillyspec/changes/<change-name>/plan.md\`
 2. 检查所有 \`- [x]\` checkbox 是否已勾选
 3. 如果 plan.md 不存在，回退读取 tasks.md 作为备选
-4. 如有遗漏 → 询问用户是否继续归档
+4. 如有遗漏 → **必须暂停等待用户决定**，不要自行判断"可以归档"
+   - 调用：\`sillyspec run archive --wait --reason "存在未完成任务，是否继续归档" --options "继续归档,回到execute完成剩余任务" --output "未完成任务列表"\`
 
 ### 输出
 完成度报告（已勾选/总数 + 未完成任务列表）`,
@@ -110,8 +111,10 @@ module_id: <module-id>
 <!-- MANUAL_NOTES_END -->
 \`\`\`
 
-4. 展示所有更新内容（diff 摘要），请用户确认
-5. 用户确认后，写入 _module-map.yaml 和受影响的模块卡片
+4. 展示所有更新内容（diff 摘要），**必须暂停等待用户确认**
+   - 调用：\`sillyspec run archive --wait --reason "等待用户确认模块文档同步" --options "确认写入,跳过同步" --output "diff 摘要"\`
+5. **只有用户通过 --continue --answer "确认写入" 后才写入文件**
+   - 写入 _module-map.yaml 和受影响的模块卡片
 6. 用户拒绝时，不写入，但提示"module-impact.md 已保留，可稍后手动同步"
 7. 回填 module-impact.md 的"更新结果"表格，区分目标：
    - 目标列写 "\`_module-map.yaml: <module-id>\`" 或 "\`modules/<module-id>.md\`"

package/src/stages/brainstorm.js

@@ -12,7 +12,7 @@ export const definition = {
 2. 确认 currentStage 为 "brainstorm"
 3. 如果有进行中的 brainstorm，提示选择继续或重新开始
 4. 如果未初始化，提示先运行 sillyspec init
-5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change\`），先询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
+5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
 
 ### 输出
 当前状态摘要（1-2 句话）
@@ -32,13 +32,12 @@ export const definition = {
 1. 读取 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文
 2. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
 3. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
-4. 询问本次需求属于哪个子项目
-5. 棕地项目：读取 .sillyspec/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
-6. **加载模块索引**：读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（如存在）
-   - 这一步是高频操作，_module-map.yaml 回答“哪个文件属于哪个模块、模块之间怎么依赖”
+4. 棕地项目：读取 .sillyspec/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
+5. **加载模块索引**：读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（如存在）
+   - 这一步是高频操作，_module-map.yaml 回答"哪个文件属于哪个模块、模块之间怎么依赖"
    - 用 tags/aliases 字段做需求关键词→模块的粗匹配
    - 用 entrypoints 字段快速了解模块对外能力
-7. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
+6. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
 
 ### 模块匹配方法
 读取 _module-map.yaml 后，根据用户描述的需求关键词，匹配相关模块：
@@ -46,11 +45,15 @@ export const definition = {
 - 需求中提到特定文件路径 → 匹配 paths 字段
 - 匹配结果用于后续 design.md 的文件变更清单
 
+### 子项目判定
+- 单项目：直接确认，不需要等待
+- 多项目且用户已指定：直接确认，不需要等待
+- 多项目且用户未指定：列出项目列表，需要用户确认本次需求属于哪个子项目
+
 ### 输出
-项目现状理解摘要（3-5 句话，关键约定和架构决策）+ 可能涉及的模块列表
+项目现状理解摘要（3-5 句话，关键约定和架构决策）+ 可能涉及的模块列表 + 本次需求所属子项目
 
 ### 注意
-- 始终询问本次需求属于哪个子项目
 - 棕地项目必须读取数据模型章节
 - 模块匹配只是粗筛，后续步骤会细化`,
       outputHint: '上下文摘要',
@@ -128,13 +131,16 @@ export const definition = {
 - 建议用「继承 + override」配置解决特殊任务，配置解决不了的才写定制代码
 - 架构设计时预留扩展点（hooks/overrides），让特殊任务能"挂上去"而不是"另起炉灶"
 
+### 铁律 — 何时需要等待用户
+- **需要拆分或批量模式时**：列出方案并暂停等待用户确认
+  - 调用：\`sillyspec run brainstorm --wait --reason "等待用户确认拆分方案" --options "同意拆分,不需要拆分" --output "拆分方案摘要"\`
+- **不需要拆分也不需要批量模式时**：正常完成即可
+
 ### 输出
 拆分方案 / 批量模式确认 / "无需拆分"确认
 
 ### 注意
-- 简单 CRUD 不拆
-- 拆分方案需用户确认
-- 批量模式需用户确认`,
+- 简单 CRUD 不拆`,
       outputHint: '拆分方案或无需拆分确认',
       optional: true
     },
@@ -144,18 +150,25 @@ export const definition = {
 
 ### 操作
 1. 从最核心的一个问题开始（用户到底想要什么？）
-2. 等待用户回答后再问下一个
-3. 根据回答判断：信息够了 → 进入方案 / 需要追问 → 只问一个
+2. **提出问题后必须暂停等待用户回答**，不要替用户回答
+3. 根据用户回答判断：信息够了 → 正常完成 / 需要追问 → 暂停等待下一个回答
 4. 探索顺序（按需）：目的 → 约束 → 边界 → 成功标准
 
+### 铁律 — 不要自问自答
+- **这是人机协作步骤，你必须暂停等待用户输入。**
+- 每次提出问题后，调用：
+  \`sillyspec run brainstorm --wait --reason "等待用户回答需求问题" --options "回答见--answer" --output "你的问题"\`
+- **绝对禁止**：在自己输出中模拟用户的回答，然后说"需求已明确"
+- 2-3 轮问答就应进入方案讨论
+- 多选题优于开放式问题
+- YAGNI — 砍掉不需要的功能
+
 ### 输出
 需求理解摘要（用户确认的需求点列表）
 
-### 铁律
-- 一次只问一个问题
-- 2-3 轮问答就应进入方案讨论
-- 多选题优于开放式问题
-- YAGNI — 砍掉不需要的功能`,
+### 注意
+- 第一次进入此步骤时，提出第一个问题并暂停
+- 用户通过 \`--continue --answer "回答"\` 回答后，本步骤会再次执行，此时检查是否需要追问或可以结束`,
       outputHint: '需求理解摘要',
       optional: false
     },
@@ -166,7 +179,12 @@ export const definition = {
 ### 操作
 1. 每种方案列出：核心思路、优势、劣势
 2. 给出推荐方案和理由
-3. 等待用户选择或调整
+
+### 铁律 — 必须等待用户选择方案
+- **不要替用户选择方案。** 列出方案对比表和推荐后，必须暂停等待用户选择。
+- 列出方案后，调用：
+  \`sillyspec run brainstorm --wait --reason "等待用户选择方案" --options "方案A,方案B,方案C" --output "方案对比摘要"\`
+- **绝对禁止**：在输出中自己说"推荐方案 A"然后当用户选了
 
 ### 输出
 方案对比表 + 推荐方案
@@ -179,21 +197,26 @@ export const definition = {
     },
     {
       name: '分段展示设计',
-      prompt: `按复杂度分段展示设计方案，逐段确认。
+      prompt: `展示完整设计方案供用户确认。
 
 ### 操作
 1. 简单项目：几句话整体描述
-2. 复杂项目：每段 200-300 字，逐段展示
-3. 每段展示后等待用户确认
-4. 收集修改意见，调整设计
-5. 确认设计后，确定变更名（格式：\`YYYY-MM-DD-<简短描述>\`，例如 \`2026-05-13-user-auth\`）
+2. 复杂项目：按模块/Phase 分段展示，每段 200-300 字
+3. 展示完整设计方案（不要逐段停顿，一次性展示）
+4. 确认变更名（格式：\`YYYY-MM-DD-<简短描述>\`，例如 \`2026-05-13-user-auth\`）
+5. 暂停等待用户确认或修改意见
+
+### 铁律 — 必须等待用户确认设计
+- **不要替用户确认设计。** 展示完整设计方案后，必须暂停等待用户确认。
+- 列出设计后，调用：
+  \`sillyspec run brainstorm --wait --reason "等待用户确认设计方案" --options "确认,需要修改,推翻重来" --output "设计方案摘要"\`
+- **绝对禁止**：在输出中自己说"设计已充分确认"然后推进
 
 ### 输出
-用户确认的完整设计方案 + 变更名
+完整设计方案 + 变更名
 
 ### 注意
-- 不要一次输出大段文字
-- 逐段确认，确保用户跟上
+- 不要一次输出大段文字，按模块/Phase 分段
 - 变更名必须以当天日期开头（YYYY-MM-DD-），后跟英文短横线分隔的简短描述`,
       outputHint: '用户确认的设计方案',
       optional: false
@@ -257,7 +280,7 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
    - 变更名格式必须为 \`YYYY-MM-DD-<简短描述>\`（如 \`2026-05-13-user-auth\`）
 2. 将确认的设计写入 \`.sillyspec/changes/<change-name>/design.md\`
 3. 自审检查：
-   - 需求覆盖：是否完整覆盖 Step 6 确认的需求
+   - 需求覆盖：是否完整覆盖对话式探索中确认的需求
    - 约束一致性：是否与 CONVENTIONS.md、ARCHITECTURE.md 一致
    - 真实性：表名/字段名/类名/方法名来自真实代码或标注"新增"
    - YAGNI：是否包含不必要功能
@@ -283,7 +306,7 @@ design.md 文件路径 + 自审结果
 
 ### 操作
 1. 展示 design.md 摘要给用户
-2. 请用户选择：✅ 确认 / ✏️ 修改 / ❌ 推翻重来
+2. 暂停等待用户选择：✅ 确认 / ✏️ 修改 / ❌ 推翻重来
 3. 确认后，在 \`.sillyspec/changes/<change-name>/\` 下生成所有规范文件：
    - **design.md**：架构决策、文件变更清单、数据模型、API 设计、兼容策略、风险登记、自审
    - **proposal.md**：动机、关键问题（为什么现有方案不够）、变更范围、不在范围内（显式清单）、成功标准（可验证条件）
@@ -358,14 +381,19 @@ Then 期望结果
 4. \`git add .sillyspec/\` — 暂存所有新增文件（不要 commit）
 5. 后续变更包的骨架文件同样必须包含 \`author: <git-user>\` 和 \`created_at: <now-datetime>\`
 
+### 铁律 — 必须等待用户最终确认
+- **展示 design.md 摘要后，暂停等待用户确认。** 不要替用户确认。
+- 调用：\`sillyspec run brainstorm --wait --reason "等待用户确认设计方案" --options "确认,需要修改,推翻重来" --output "design.md 摘要"\`
+- **绝对禁止**：在输出中自己说"用户已确认"然后生成文件
+- **只有用户通过 --continue --answer "确认" 后才生成规范文件**
+
 ### 输出
 所有规范文件路径（含后续变更包目录列表）
 
 ### 注意
-- 必须等待用户明确确认
 - 禁止在确认前推进到后续阶段
 - 禁止自动 commit
-- 推翻重来回到 Step 6
+- 推翻重来回到 Step 6（对话式探索）
 - 表名/字段名/类名必须来自真实代码或标注"新增"
 - tasks.md 只列任务名，细节在 plan 阶段展开`,
 

package/src/stages/execute.js

@@ -87,17 +87,15 @@ sillyspec run execute --done --output "worktree 路径 + 分支名"`,
    - 简单修改 → 快速模型
    - 文档/写作 → 写作模型
 3. 用户在 tasks.md 中的 [model:xxx] 标签优先
-4. 询问用户执行确认频率：
-   - 每个 Wave 确认 — 每个 Wave 完成后展示结果
-   - AI 自主判断 — BLOCKED 或计划外变更时才询问
-   - 全自动 — 全部自动执行
+4. 读取 \`--confirm-mode\` 参数（由 CLI 传入，不需要询问用户）：
+   - wave — 每个 Wave 完成后展示结果（默认）
+   - task — 每个 Task 完成后展示结果
+   - auto — 全部自动执行
 5. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
 
-### 输出
-Wave 分组 + 模型分配 + 确认模式 + 知识库匹配结果
-
-### 注意
-- 默认推荐"每个 Wave 确认"`,
+### 铁律
+- **不要询问用户确认频率**，确认模式由 CLI \`--confirm-mode\` 参数决定
+- 如果未检测到 \`--confirm-mode\`，默认使用 wave 模式`,
     outputHint: 'Wave 分组 + 模型分配',
     optional: false
   }

package/src/stages/plan.js

@@ -207,7 +207,10 @@ export const fixedSuffix = [
    - 依赖关系和 plan.md 的 Wave 分组是否一致
    - 验收标准和 plan.md 的全局标准是否矛盾
    - 接口定义是否自洽
-3. 发现问题 → 列出问题清单，暂停等用户决定是否修复
+3. 发现问题 → 列出问题清单，暂停等待用户决定
+   - 调用：\`sillyspec run plan --wait --reason "审查发现一致性问题" --options "自动修复,手动修复,忽略并继续" --output "问题清单"\`
+   - **绝对禁止**：自己决定修复方向然后自动修复
+4. 无问题 → 正常完成
 
 ### 输出
 一致性审查结果`,

package/src/stages/scan.js

@@ -51,12 +51,14 @@ export const definition = {
 2. dashboard（子项目）— scan 文档：0/7 已存在
 \`\`\`
 
-4. **必须停下来问用户**：
+4. **如果存在歧义（多项目且无法自动判定），必须暂停等待用户**：
    - 选择要扫描的项目（默认全部）
    - 每个项目的扫描策略：**重新扫描（全部覆盖）** / **只补扫描缺失的文档** / **跳过**
+   - 调用：\`sillyspec run scan --wait --reason "等待用户确认扫描项目列表" --options "全部重新扫描,只补缺失,跳过" --output "项目列表和策略建议"\`
+5. **如果只有单一项目且已明确，正常完成即可，不需要等待。**
 
 ### ⛔ 重要
-- **不要自行决定跳过**，等用户选择后再继续
+- **不要自行决定跳过**，有歧义时暂停等用户选择后再继续
 - 最终确定的项目列表将用于后续所有步骤
 - **后续每个需要生成文档的步骤，都必须对列表中的每个项目分别执行**
 
@@ -308,10 +310,11 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 1. 读取 \`{DOCS_ROOT}/modules/_module-map.yaml\`，获取模块列表和路径
 2. 检查 \`{DOCS_ROOT}/modules/\` 下已有的模块文档（<module>.md）
 3. 列出每个模块的状态：已有文档 / 缺失
-4. **必须停下来问用户**：
+4. **如果有覆盖风险（已有模块文档会被覆盖），必须暂停等待用户**：
    - 展示模块列表及现有文档状态
    - 明确提供选项：**为缺失模块生成初始文档** / **全部重新生成（覆盖已有）** / **跳过**
-5. 用户选择后执行
+   - 调用：\`sillyspec run scan --wait --reason "检测到已有模块文档覆盖风险" --options "只生成缺失,全部重新生成,跳过" --output "受影响模块列表"\`
+5. **如果没有覆盖风险（全部都是缺失模块），正常完成即可，不需要等待。**
 
 ### 生成方法（子代理并行，只针对用户选中的模块）
 **你必须为每个模块启动独立子代理执行，不要自己写文档。**