sillyspec 3.18.0 → 3.18.2

package/src/run.js

@@ -4,7 +4,7 @@
  * CLI 成为流程引擎，AI 变成步骤执行器。
  * 支持多变更并行：每个变更状态存储在 sillyspec.db 中。
  */
-import { basename, join, resolve } from 'path'
+import { basename, join, resolve, dirname } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, rmSync, statSync } from 'fs'
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
@@ -48,16 +48,49 @@ function formatWaitOptions(raw) {
   }
 }
 
+/**
+ * 格式化 repeatableWait 步骤的历史用户回答，注入到重新输出的 step prompt 前。
+ * @param {object} step - progress 中的 step 对象（含 waitAnswers 数组）
+ * @returns {string|null} 格式化的历史文本，或 null（无历史）
+ */
+function formatWaitHistory(step) {
+  const answers = Array.isArray(step.waitAnswers) ? step.waitAnswers : []
+  if (answers.length === 0) return null
+  let text = `本步骤历史用户回答（共 ${answers.length} 轮）：\n`
+  for (const item of answers) {
+    text += `\n${item.round}. ${item.answer}`
+    if (item.question) {
+      text += `\n   对应问题/摘要：${item.question}`
+    }
+  }
+  const maxRounds = step.maxWaitRounds || null
+  if (maxRounds && answers.length >= maxRounds) {
+    text += `\n\n已达到 maxWaitRounds=${maxRounds}。请基于以上回答总结需求；除非仍有阻塞问题，否则完成本步骤并进入方案讨论。`
+  } else {
+    text += `\n\n请判断信息是否足够：如果足够，完成本步骤；如果仍缺关键约束，再提出一个问题并 --wait。`
+  }
+  return text
+}
+
 /**
  * 解析规范目录路径
- * @param {string} cwd - 项目根目录
+ * 向上查找含 .sillyspec 的祖先目录，类似 git 找 .git 的逻辑。
+ * @param {string} cwd - 项目根目录（或子目录）
  * @param {object} [opts]
  * @param {string} [opts.specDir] - 用户指定的 specDir（通过 --spec-dir 或 --spec-root）
  * @returns {string} 规范目录的绝对路径
  */
 function resolveSpecDir(cwd, opts = {}) {
   if (opts.specDir) return resolve(opts.specDir)
-  return join(cwd, '.sillyspec')
+  let dir = resolve(cwd)
+  while (true) {
+    const candidate = join(dir, '.sillyspec')
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return join(resolve(cwd), '.sillyspec')
 }
 import { stageRegistry, auxiliaryStages } from './stages/index.js'
 import { checkTransition, runValidators } from './stage-contract.js'
@@ -224,19 +257,34 @@ async function auditQuickCompletion(cwd, guard, options = {}) {
     const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
     const currentEntries = gitStatus.trim().split('\n').filter(Boolean)
 
+    const normalizeGitPath = (p) => p.replace(/\\/g, '/')
+    const isQuickMetadata = (p) => {
+      const file = normalizeGitPath(p)
+      return file.startsWith('.sillyspec/quicklog/')
+        || file.startsWith('.sillyspec/.runtime/')
+        || file === '.sillyspec/knowledge/uncategorized.md'
+        || (/^\.sillyspec\/docs\/[^/]+\/modules\/[^/]+\.md$/.test(file))
+        || (/^\.sillyspec\/docs\/[^/]+\/modules\/_module-map\.yaml$/.test(file))
+    }
     const DANGEROUS_PATTERNS = [
-      '.sillyspec/',
       'package.json',
       'package-lock.json',
       'yarn.lock',
       'pnpm-lock.yaml',
       '.eslintrc',
       'tsconfig.json',
+      'src/db.js',
+      'src/progress.js',
+      'src/run.js',
+      'src/stage-contract.js',
+      'src/worktree.js',
+      'src/worktree-apply.js',
+      'src/hooks/',
     ]
 
     for (const entry of currentEntries) {
       const status = entry.slice(0, 2).trim()
-      const file = entry.slice(3).trim()
+      const file = normalizeGitPath(entry.slice(3).trim())
       if (!file || file.startsWith('??. ')) continue
 
       result.changedFiles.push(file)
@@ -249,7 +297,11 @@ async function auditQuickCompletion(cwd, guard, options = {}) {
       }
 
       // 检查危险文件（除非 force-baseline）
-      if (DANGEROUS_PATTERNS.some(p => file.includes(p)) && !forceBaseline) {
+      if (file.startsWith('.sillyspec/') && !isQuickMetadata(file) && !forceBaseline) {
+        result.reasons.push(`危险文件变更: ${file}`)
+      }
+
+      if (DANGEROUS_PATTERNS.some(p => file === p || file.startsWith(p)) && !forceBaseline) {
         result.reasons.push(`危险文件变更: ${file}`)
       }
     }
@@ -269,7 +321,7 @@ async function auditQuickCompletion(cwd, guard, options = {}) {
     // 检查 new files（除非 allow-new）
     if (!allowNew) {
       for (const f of result.newFiles) {
-        if (!f.startsWith('.sillyspec/quicklog/') && !f.startsWith('.sillyspec/.runtime/')) {
+        if (!isQuickMetadata(f)) {
           result.reasons.push(`新增文件（需 --allow-new）: ${f}`)
         }
       }
@@ -278,7 +330,7 @@ async function auditQuickCompletion(cwd, guard, options = {}) {
     // 检查 allowedFiles 范围
     if (allowedFiles.length > 0) {
       for (const f of result.changedFiles) {
-        if (!allowedFiles.includes(f) && !f.startsWith('.sillyspec/')) {
+        if (!allowedFiles.includes(f) && !isQuickMetadata(f)) {
           result.reasons.push(`超出 allowedFiles: ${f}`)
         }
       }
@@ -337,6 +389,23 @@ async function auditQuickCompletion(cwd, guard, options = {}) {
   return result
 }
 
+function printQuickAuditReview(review) {
+  if (review.status === 'blocked') {
+    console.error(`\n🚫 quick 变更边界审计 — BLOCKED：`)
+    for (const r of review.reasons) {
+      console.error(`   - ${r}`)
+    }
+    console.error(`\n   quick 已停止：请恢复/拆分这些变更，或重新运行 quick 并显式声明范围。`)
+  } else if (review.status === 'warning') {
+    console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
+    for (const r of review.reasons) {
+      console.warn(`   - ${r}`)
+    }
+  } else {
+    console.log(`\n✅ quick 变更边界审计 — SAFE (变更 ${review.changedFiles.length} 个文件)`)
+  }
+}
+
 async function triggerSync(cwd, changeName, platformOpts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
@@ -697,11 +766,22 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   const changeFlag = changeName ? ` --change ${changeName}` : ''
   // 检测当前 step prompt 是否包含 WAIT 指令（即可能需要等待用户）
   const stepPrompt = promptText || ''
-  const mayNeedWait = WAIT_MARKER_RE.test(stepPrompt)
+  const requiresWait = step.requiresWait === true
+  const conditionalWait = step.conditionalWait === true
+  const mayNeedWait = WAIT_MARKER_RE.test(stepPrompt) || requiresWait || conditionalWait
+
   console.log(`\n### 完成后执行`)
-  if (mayNeedWait) {
+  if (requiresWait) {
+    console.log(`本步骤必须等待用户输入，不能直接 --done：`)
+    console.log(`sillyspec run ${stageName} --wait --reason "${step.waitReason || '等待用户输入'}" --options "${(step.waitOptions || ['确认']).join(',')}"${changeFlag} --output "你的问题/方案摘要"`)
+    console.log(``)
+    console.log(`用户回答后执行：`)
+    console.log(`sillyspec run ${stageName} --continue --answer "用户回答"${changeFlag}`)
+    console.log(``)
+    console.log(`收到回答并完成本步骤总结后，再执行：`)
+  } else if (mayNeedWait) {
     console.log(`如果需要用户决策（选择方案/确认设计等）：`)
-    console.log(`sillyspec run ${stageName} --wait --reason "等待原因" --options "选项1,选项2"${changeFlag} --output "你的摘要"`)
+    console.log(`sillyspec run ${stageName} --wait --reason "${step.waitReason || '等待原因'}" --options "${(step.waitOptions || ['选项1', '选项2']).join(',')}"${changeFlag} --output "你的摘要"`)
     console.log(``)
     console.log(`如果不需要用户决策，正常完成：`)
   }
@@ -873,9 +953,14 @@ async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
       const { execSync } = await import('child_process')
       const manifestDir = platformOpts.specRoot
       let sourceCommit = null
+      let sourceCommitError = null
       try {
-        const { value: sourceCommit, error: scErr } = safeGit(cwd, ['rev-parse', 'HEAD'])
-      } catch {}
+        const gitResult = safeGit(cwd, ['rev-parse', 'HEAD'])
+        sourceCommit = gitResult.value
+        sourceCommitError = gitResult.error
+      } catch (e) {
+        sourceCommitError = e.message
+      }
       mkdirSync(manifestDir, { recursive: true })
       const manifest = {
         scan_profile: {
@@ -888,7 +973,7 @@ async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
         workspace_id: platformOpts.workspaceId || null,
         scan_run_id: platformOpts.scanRunId || null,
         source_commit: sourceCommit,
-        source_commit_error: sourceCommit === null ? (scErr || 'unknown') : undefined,
+        source_commit_error: sourceCommit === null ? (sourceCommitError || 'unknown') : undefined,
         generated_at: new Date().toISOString(),
         schema_version: 2,
       }
@@ -1057,6 +1142,7 @@ export async function runCommand(args, cwd, specDir = null) {
 
   const isAllowNew = flags.includes('--allow-new')
   const isForceBaseline = flags.includes('--force-baseline')
+  const isForceRescan = flags.includes('--force-rescan')
 
   // 未知参数 fail-fast
   const knownFlags = new Set([
@@ -1065,7 +1151,7 @@ export async function runCommand(args, cwd, specDir = null) {
     '--reason', '--options', '--answer', '--confirm-mode',
     '--output', '--input', '--change',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
-    '--files', '--allow-new', '--force-baseline',
+    '--files', '--allow-new', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
   ])
   for (let i = 0; i < flags.length; i++) {
@@ -1102,8 +1188,8 @@ export async function runCommand(args, cwd, specDir = null) {
         progress = { currentStage: stageName, stages: {}, lastActive: new Date().toLocaleString('zh-CN', { hour12: false }), project: '' }
       }
     } else {
-      // brainstorm / propose 作为流程入口，自动生成变更名并初始化
-      if (stageName === 'brainstorm' || stageName === 'propose') {
+      // brainstorm 作为流程入口，自动生成变更名并初始化
+      if (stageName === 'brainstorm') {
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change`
         console.log(`🔄 自动创建变更：${autoName}`)
@@ -1167,11 +1253,12 @@ export async function runCommand(args, cwd, specDir = null) {
 
   // --done
   if (isDone) {
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode })
+    const doneAnswer = getFlagValue('--answer')
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode, doneAnswer })
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan })
 }
 
 /**
@@ -1187,6 +1274,7 @@ function resolveChangeNameAuto(cwd, specDir = null) {
 }
 
 async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   // 状态转换校验
   const prevStage = progress.currentStage || ''
   const transition = checkTransition(prevStage, stageName)
@@ -1214,6 +1302,26 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     }
   }
 
+  // execute 阶段：CLI 自动创建 worktree（不等 AI agent）
+  if (stageName === 'execute' && changeName) {
+    const effectiveChange = changeName
+    const { WorktreeManager } = await import('./worktree.js')
+    const wm = new WorktreeManager({ cwd })
+    const existingMeta = wm.getMeta(effectiveChange)
+    if (existingMeta) {
+      console.log(`🔗 worktree 已存在: ${existingMeta.worktreePath} (${existingMeta.mode})`)
+    } else {
+      try {
+        const result = wm.create(effectiveChange)
+        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
+      } catch (e) {
+        console.error(`❌ worktree 创建失败: ${e.message}`)
+        console.error(`   继续执行前请解决上述问题，或使用 --no-worktree 跳过。`)
+        process.exit(1)
+      }
+    }
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
@@ -1268,6 +1376,28 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
   }
   if (scanProfile) platformOpts.scanProfile = scanProfile
 
+  if (stageName === 'scan') {
+    try {
+      const gitResult = safeGit(cwd, ['rev-parse', 'HEAD'])
+      const scanGuard = {
+        sourceCommit: gitResult.value,
+        sourceCommitError: gitResult.error,
+        startedAt: new Date().toISOString(),
+        forceRescan: quickOpts?.isForceRescan || false,
+      }
+      const guardFile = join(specBase, '.runtime', 'scan-guard.json')
+      mkdirSync(dirname(guardFile), { recursive: true })
+      writeFileSync(guardFile, JSON.stringify(scanGuard, null, 2) + '\n')
+      if (scanGuard.forceRescan) {
+        console.log('🛡️ scan 覆盖保护已记录: --force-rescan 已开启')
+      } else {
+        console.log('🛡️ scan 覆盖保护已记录: existing scan docs require current source_commit/updated_at')
+      }
+    } catch (e) {
+      console.warn(`⚠️ scan 覆盖保护记录失败: ${e.message}`)
+    }
+  }
+
   if (currentIdx === -1) {
     // 已完成 → 自动重置，重新开始
     const freshSteps = await getStageSteps(stageName, cwd, progress)
@@ -1400,9 +1530,8 @@ function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
 
   // 每个阶段完成后预期存在的文件
   const expectedFiles = {
-    propose: ['proposal.md', 'design.md', 'requirements.md', 'tasks.md'],
+    brainstorm: ['design.md', 'proposal.md', 'requirements.md', 'tasks.md'],
     plan: ['plan.md'],
-    verify: ['verify-result.md'],
     archive: ['module-impact.md'],
   }
 
@@ -1434,7 +1563,7 @@ function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
   }
 }
 
-async function archiveChangeDirectory(pm, cwd, progress) {
+async function archiveChangeDirectory(pm, cwd, progress, specBase) {
   const { renameSync } = await import('fs')
   const archiveChangeName = progress.currentChange
   if (!archiveChangeName) {
@@ -1486,6 +1615,28 @@ async function waitStep(pm, progress, stageName, cwd, outputText, waitReason, wa
     process.exit(1)
   }
 
+  // 前置检查：不允许已有 waiting 步骤时再 --wait
+  const existingWaitingIdx = stageData.steps.findIndex(s => s.status === 'waiting')
+  if (existingWaitingIdx !== -1) {
+    const ws = stageData.steps[existingWaitingIdx]
+    console.error(`❌ 已有步骤处于等待状态：Step ${existingWaitingIdx + 1} "${ws.name}"`)
+    console.error(`   请先 --continue 或 --reset 该步骤，再开始新的 --wait`)
+    process.exit(1)
+  }
+
+  // maxWaitRounds 硬上限：达到后拒绝继续 --wait
+  const currentStep = stageData.steps[currentIdx]
+  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const stepDef = defSteps?.[currentIdx] || {}
+  const maxWaitRounds = currentStep.maxWaitRounds ?? stepDef.maxWaitRounds
+  const currentWaitRound = currentStep.waitRound || 0
+  if (maxWaitRounds && currentWaitRound >= maxWaitRounds) {
+    console.error(`❌ Step "${currentStep.name}" 已达到最大等待轮次（maxWaitRounds=${maxWaitRounds}）`) 
+    console.error(`   请基于已有回答完成本步骤：`)
+    console.error(`   sillyspec run ${stageName} --done${changeName ? ` --change ${changeName}` : ''} --output "需求理解摘要"`)
+    process.exit(1)
+  }
+
   // 非交互模式下拒绝等待
   if (nonInteractive) {
     console.error(`❌ Human decision required in non-interactive mode.`)
@@ -1560,38 +1711,82 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
     process.exit(1)
   }
   const currentIdx = waitingSteps[0].idx
+  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const currentStepDef = defSteps?.[currentIdx] || {}
+  const currentStep = stageData.steps[currentIdx]
+  const isRepeatableWait = currentStepDef.repeatableWait === true || currentStep.repeatableWait === true
+  const requiresWait = currentStepDef.requiresWait === true || currentStep.requiresWait === true
+  const shouldReturnToCurrentStep = isRepeatableWait || requiresWait
 
   const now = new Date().toLocaleString('zh-CN', { hour12: false })
-  stageData.steps[currentIdx].status = 'completed'
-  stageData.steps[currentIdx].completedAt = now
-  stageData.steps[currentIdx].waitAnswer = answer
+  const prevOutput = currentStep.output || ''
+  const waitRound = (currentStep.waitRound || 0) + 1
+  currentStep.waitRound = waitRound
+  currentStep.waitAnswer = answer
+  currentStep.waitAnswers = Array.isArray(currentStep.waitAnswers) ? currentStep.waitAnswers : []
+  currentStep.waitAnswers.push({
+    round: waitRound,
+    answer,
+    question: prevOutput || null,
+    answeredAt: now,
+  })
+  currentStep.maxWaitRounds = currentStepDef.maxWaitRounds ?? currentStep.maxWaitRounds
 
   // 合并 waiting 信息到 output
-  const prevOutput = stageData.steps[currentIdx].output || ''
-  const waitInfo = stageData.steps[currentIdx].waitReason || ''
+  const waitInfo = currentStep.waitReason || ''
   if (waitInfo) {
-    stageData.steps[currentIdx].output = prevOutput
-      ? `${prevOutput} | 用户选择：${answer}`
-      : `用户选择：${answer}`
+    currentStep.output = prevOutput
+      ? `${prevOutput} | 用户回答#${waitRound}：${answer}`
+      : `用户回答#${waitRound}：${answer}`
   }
 
   // 清除等待状态
-  delete stageData.steps[currentIdx].waitReason
-  delete stageData.steps[currentIdx].waitOptions
-  delete stageData.steps[currentIdx].waitedAt
+  delete currentStep.waitReason
+  delete currentStep.waitOptions
+  delete currentStep.waitedAt
+
+  if (shouldReturnToCurrentStep) {
+    currentStep.status = 'pending'
+    currentStep.completedAt = null
+  } else {
+    currentStep.status = 'completed'
+    currentStep.completedAt = now
+  }
 
   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(`✅ Step ${currentIdx + 1}/${stageData.steps.length} 已继续：${currentStep.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`
+  const entry = `\n## ${now} | ${changeName || '?'} | ${stageName}: ${currentStep.name} [CONTINUED]\n- 回答：${answer}\n`
  appendFileSync(inputsPath, entry)
 
+  // shouldReturnToCurrentStep: 回到当前步骤继续执行（repeatable=多轮探索，requiresWait=确认后执行动作）
+  if (shouldReturnToCurrentStep) {
+    console.log(`\n🔁 Step ${currentIdx + 1}/${stageData.steps.length} 已收到用户输入，回到当前步骤继续执行。`)
+    if (isRepeatableWait) {
+      console.log(`   已收集回答轮次：${waitRound}${currentStep.maxWaitRounds ? `/${currentStep.maxWaitRounds}` : ''}`)
+    }
+    if (defSteps && defSteps[currentIdx]) {
+      console.log('')
+      await outputStep(
+        stageName,
+        currentIdx,
+        defSteps,
+        cwd,
+        changeName,
+        progress.project || null,
+        platformOpts,
+        formatWaitHistory(currentStep)
+      )
+    }
+    return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+  }
+
   // 检查阶段是否全部完成
   const nextPendingIdx = stageData.steps.findIndex(s => s.status === 'pending')
   const nextWaitingIdx = stageData.steps.findIndex(s => s.status === 'waiting')
@@ -1604,7 +1799,6 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
   }
 
   // 输出下一步
-  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)
@@ -1649,6 +1843,35 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
 
   const steps = stageData.steps
   const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  if (currentIdx === -1) {
+    console.error('没有待完成的步骤')
+    process.exit(1)
+  }
+
+  // ── requiresWait 硬门控 ──
+  const defStepsForCurrent = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const currentStepDef = defStepsForCurrent?.[currentIdx] || {}
+  const currentStep = steps[currentIdx]
+  if (currentStepDef.requiresWait === true && !currentStep.waitAnswer) {
+    // 检查 --done 是否带了 --answer：如果是，自动补全 waitAnswer 状态，一步完成
+    const doneAnswer = typeof options !== 'undefined' && options.doneAnswer ? options.doneAnswer : null
+    if (doneAnswer) {
+      currentStep.status = 'waiting'
+      currentStep.waitAnswer = doneAnswer
+      currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
+      console.log(`⚠️  Step "${currentStep.name}" 需要 wait，但 --done 带了 --answer，自动补全 wait 状态。`)
+    } else {
+      console.error(`❌ Step "${currentStep.name}" 必须先等待用户输入，不能直接 --done。`)
+      console.error(`   原因：${currentStepDef.waitReason || '该步骤需要人工确认/回答'}`)
+      if (currentStepDef.waitOptions) {
+        console.error(`   选项：${currentStepDef.waitOptions.join(', ')}`)
+      }
+      console.error(`   请先执行：`)
+      console.error(`   sillyspec run ${stageName} --wait --reason "${currentStepDef.waitReason || '等待用户输入'}" --options "${(currentStepDef.waitOptions || ['确认']).join(',')}"${changeName ? ` --change ${changeName}` : ''} --output "你的问题/方案摘要"`)
+      console.error(`   或使用 --done --answer "用户回答" 一步完成 wait + done`)
+      process.exit(1)
+    }
+  }
 
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -1679,7 +1902,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
       return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
     }
-    await archiveChangeDirectory(pm, cwd, progress)
+    await archiveChangeDirectory(pm, cwd, progress, specBase)
   }
 
   // archive "确认归档" 步骤完成后，校验归档完整性
@@ -1881,6 +2104,25 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         console.error(`   请先创建 quicklog 记录再 --done，或使用 --skip-approval 跳过此校验。`)
         return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
       }
+      if (progress.quickGuard) {
+        const review = await auditQuickCompletion(cwd, progress.quickGuard, { isConfirm })
+        progress.quickGuard.review = review
+        progress.quickGuard.completedAt = new Date().toISOString()
+        printQuickAuditReview(review)
+        if (review.status === 'blocked') {
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
+        }
+        try {
+          const { unlinkSync } = await import('fs')
+          const guardFile = join(specBase, '.runtime', 'quick-guard.json')
+          unlinkSync(guardFile)
+        } catch {}
+        progress.lastQuickReview = review
+        delete progress.quickGuard
+      }
     }
 
     stageData.status = 'completed'
@@ -1906,9 +2148,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         const manifestDir = platformOpts.specRoot
         mkdirSync(manifestDir, { recursive: true })
         let sourceCommit = null
+        let sourceCommitError = null
         try {
-          const { value: sourceCommit, error: scErr } = safeGit(cwd, ['rev-parse', 'HEAD'])
-        } catch {}
+          const gitResult = safeGit(cwd, ['rev-parse', 'HEAD'])
+          sourceCommit = gitResult.value
+          sourceCommitError = gitResult.error
+        } catch (e) {
+          sourceCommitError = e.message
+        }
         const manifest = {
           workspace_id: platformOpts.workspaceId || null,
           scan_run_id: platformOpts.scanRunId || null,
@@ -1916,7 +2163,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           spec_root: platformOpts.specRoot || null,
           runtime_root: platformOpts.runtimeRoot || null,
           source_commit: sourceCommit,
-          source_commit_error: sourceCommit === null ? (scErr || 'unknown') : undefined,
+          source_commit_error: sourceCommit === null ? (sourceCommitError || 'unknown') : undefined,
           generated_at: new Date().toISOString(),
           schema_version: 1,
           postcheck_result_path: null,
@@ -2018,10 +2265,16 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       }
     }
 
+    // 防御性守卫变量：确认所有步骤确实标记为 completed
+    const actualCompleted = steps.filter(s => s.status === 'completed').length
+    const actualTotal = steps.length
+
     validateMetadata(cwd, stageName, specBase)
 
-    // 验证关键文件是否在正确的变更目录下
-    validateFileLocations(cwd, stageName, progress, changeName, specBase)
+    // 验证关键文件是否在正确的变更目录下（仅当所有步骤确实完成时才校验）
+    if (actualCompleted === actualTotal && actualTotal > 0) {
+      validateFileLocations(cwd, stageName, progress, changeName, specBase)
+    }
 
     // 辅助阶段完成后重置步骤
     const stageDef = stageRegistry[stageName]
@@ -2065,51 +2318,30 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     } else {
       console.log(`\n下一步由你决定：sillyspec run <stage>（brainstorm/plan/execute/verify/archive 等）`)
     }
-    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
-  }
 
-  // 阶段完成校验
-  const projectName = progress.project || basename(cwd)
-  const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
-  if (contractResult.errors.length > 0) {
-    console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
-    for (const err of contractResult.errors) {
-      console.error(`   - ${err}`)
-    }
-    console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
-  }
-  if (contractResult.warnings.length > 0) {
-    console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
-    for (const w of contractResult.warnings) {
-      console.warn(`   - ${w}`)
-    }
-  }
-
-  // quick 阶段完成审计
-  if (stageName === 'quick' && progress.quickGuard) {
-    const review = await auditQuickCompletion(cwd, progress.quickGuard, { isConfirm })
-    progress.quickGuard.review = review
-    progress.quickGuard.completedAt = new Date().toISOString()
-    // 清理 quick-guard.json
-    try {
-      const { unlinkSync } = await import('fs')
-      const guardFile = join(specBase, '.runtime', 'quick-guard.json')
-      unlinkSync(guardFile)
-    } catch {}
-    if (review.status === 'blocked') {
-      console.error(`\n🚫 quick 变更边界审计 — BLOCKED：`)
-      for (const r of review.reasons) {
-        console.error(`   - ${r}`)
+    // 阶段完成校验 — 防御性守卫：仅当所有步骤确实标记为 completed 时才跑 validator
+    if (actualCompleted === actualTotal && actualTotal > 0) {
+      const projectName = progress.project || basename(cwd)
+      const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
+      if (contractResult.errors.length > 0) {
+        console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
+        for (const err of contractResult.errors) {
+          console.error(`   - ${err}`)
+        }
+        console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
       }
-      console.error(`\n   这些文件是 baseline 保护的，不应被修改。`)
-    } else if (review.status === 'warning') {
-      console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
-      for (const r of review.reasons) {
-        console.warn(`   - ${r}`)
+      if (contractResult.warnings.length > 0) {
+        console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
+        for (const w of contractResult.warnings) {
+          console.warn(`   - ${w}`)
+        }
       }
-    } else {
-      console.log(`\n✅ quick 变更边界审计 — SAFE (变更 ${review.changedFiles.length} 个文件)`)
+    } else if (actualCompleted < actualTotal) {
+      // 实际步骤未全部完成，跳过 validator（状态可能不同步）
+      console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
     }
+
+    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})