sillyspec 3.17.15 → 3.18.1

package/src/run.js

@@ -4,11 +4,12 @@
  * 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)
 import { ProgressManager } from './progress.js'
+import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
 
 /**
  * 在容器/Docker 环境下，git 可能因目录所有权不匹配报 dubious ownership。
@@ -47,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'
@@ -223,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)
@@ -248,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}`)
       }
     }
@@ -268,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}`)
         }
       }
@@ -277,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}`)
         }
       }
@@ -336,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
@@ -613,21 +683,29 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     }
     profileDirectives.push(`--output 只需要列出文件名，不要写长篇总结。`)
     promptText = profileDirectives.join('\n') + '\n\n' + promptText
+
+    // scanProfile 分支也要替换占位符（非 platform 模式也会走到这里）
+    const _pName = dbProjectName || basename(cwd)
+    const _specSS = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const _docsRoot = join(_specSS, 'docs', _pName)
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, _docsRoot)
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, join(_specSS, 'projects'))
+    promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, join(_specSS, 'workflows'))
+    promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, join(_specSS, 'knowledge'))
+    promptText = promptText.replace(/\{SPEC_ROOT\}/g, _specSS)
   } else {
     // 非 platform 模式也要替换占位符
-    if (stageName === 'scan') {
-      const projectName = dbProjectName || basename(cwd)
-      const specSillyspec = join(cwd, '.sillyspec')
-      const docsRoot = join(specSillyspec, 'docs', projectName)
-      const projectsRoot = join(specSillyspec, 'projects')
-      const workflowsRoot = join(specSillyspec, 'workflows')
-      const knowledgeRoot = join(specSillyspec, 'knowledge')
-      promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
-      promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
-      promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, workflowsRoot)
-      promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, knowledgeRoot)
-      promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
-    }
+    const projectName = dbProjectName || basename(cwd)
+    const specSillyspec = join(cwd, '.sillyspec')
+    const docsRoot = join(specSillyspec, 'docs', projectName)
+    const projectsRoot = join(specSillyspec, 'projects')
+    const workflowsRoot = join(specSillyspec, 'workflows')
+    const knowledgeRoot = join(specSillyspec, 'knowledge')
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
+    promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, workflowsRoot)
+    promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, knowledgeRoot)
+    promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
   }
 
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
@@ -688,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(`如果不需要用户决策，正常完成：`)
   }
@@ -864,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: {
@@ -879,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,
       }
@@ -1048,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([
@@ -1056,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++) {
@@ -1093,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}`)
@@ -1162,7 +1257,7 @@ export async function runCommand(args, cwd, specDir = null) {
   }
 
   // 默认：输出当前步骤
-  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 })
 }
 
 /**
@@ -1178,6 +1273,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)
@@ -1259,6 +1355,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)
@@ -1391,9 +1509,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'],
   }
 
@@ -1425,7 +1542,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) {
@@ -1477,6 +1594,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.`)
@@ -1551,38 +1690,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')
@@ -1595,7 +1778,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)
@@ -1640,6 +1822,25 @@ 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) {
+    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 "你的问题/方案摘要"`)
+    process.exit(1)
+  }
 
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -1670,7 +1871,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 "确认归档" 步骤完成后，校验归档完整性
@@ -1872,6 +2073,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'
@@ -1891,22 +2111,36 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     if (stageName === 'scan' && (platformOpts.specRoot || platformOpts.runtimeRoot)) {
       try {
         stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false; // 默认失败
-        const { mkdirSync, writeFileSync } = await import('fs')
+        const { mkdirSync, writeFileSync, readFileSync: _readFileSync } = await import('fs')
         const { join } = await import('path')
         const { execSync } = await import('child_process')
         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,
+          source_root: cwd,
+          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,
+          workflow_runs_dir: platformOpts.runtimeRoot
+            ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown', 'workflow-runs')
+            : null,
+          platform_pointer_path: join(cwd, '.sillyspec-platform.json'),
+          platform_pointer_status: POINTER_STATUS.ACTIVE,
         }
         const manifestPath = join(manifestDir, 'manifest.json')
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
@@ -1947,6 +2181,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         })
         if (postcheckJsonPath) {
           console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
+          manifest.postcheck_result_path = postcheckJsonPath
         }
 
         // 将 post-check 结果写入 manifest
@@ -1958,9 +2193,19 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
         console.log(`📄 manifest.json 已更新（含 post-check 结果）`)
 
+        // 更新平台指针状态为 scan_completed
+        const pointerPath = join(cwd, '.sillyspec-platform.json')
+        try {
+          const pointer = JSON.parse(_readFileSync(pointerPath, 'utf8'))
+          pointer.status = POINTER_STATUS.SCAN_COMPLETED
+          pointer.completedAt = new Date().toISOString()
+          pointer.scanStatus = postResult.status
+          writeFileSync(pointerPath, JSON.stringify(pointer, null, 2) + '\n')
+        } catch {}
+
         // failed_post_check 时强制阻止 clean success
         if (postResult.status === 'failed_post_check') {
-          stageData.status = 'failed_post_check'
+          stageData.status = SCAN_STATUS.FAILED_POST_CHECK
           stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
           await pm._write(cwd, progress, changeName)
           console.error(`\n❌ scan post-check 失败，状态设为 failed_post_check。不允许 clean success。`)
@@ -2056,33 +2301,6 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     }
   }
 
-  // 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}`)
-      }
-      console.error(`\n   这些文件是 baseline 保护的，不应被修改。`)
-    } 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} 个文件)`)
-    }
-  }
-
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
   await pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
@@ -2135,7 +2353,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
               console.log(rp.prompt)
             }
           }
-          const saved = saveWorkflowRun(result, { cwd, source: 'run.js', stage: 'verify', step: steps[currentIdx]?.name })
+          const saved = saveWorkflowRun(result, {
+            cwd,
+            source: 'run.js',
+            stage: 'scan',
+            step: steps[currentIdx]?.name,
+            ...(platformOpts.runtimeRoot ? { runtimeRoot: platformOpts.runtimeRoot } : {}),
+            ...(platformOpts.scanRunId ? { scanRunId: platformOpts.scanRunId } : {})
+          })
           if (saved) console.log(`📁 结果已归档：${saved}`)
         }
         if (anyFailed) {
@@ -2165,7 +2390,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
             console.log(`   └─ ${f}`)
           }
         }
-        const saved = saveWorkflowRun(result, { cwd, source: 'run.js', stage: 'archive', step: steps[currentIdx]?.name })
+        const saved = saveWorkflowRun(result, {
+          cwd,
+          source: 'run.js',
+          stage: 'archive',
+          step: steps[currentIdx]?.name,
+          ...(platformOpts.runtimeRoot ? { runtimeRoot: platformOpts.runtimeRoot } : {}),
+          ...(platformOpts.scanRunId ? { scanRunId: platformOpts.scanRunId } : {})
+        })
         if (saved) console.log(`📁 结果已归档：${saved}`)
       }
     } catch (e) {