sillyspec 3.15.2 → 3.16.1

package/src/run.js

@@ -8,6 +8,7 @@ import { basename, join } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, statSync } from 'fs'
 import { ProgressManager } from './progress.js'
 import { stageRegistry, auxiliaryStages } from './stages/index.js'
+import { checkTransition, runValidators } from './stage-contract.js'
 import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
 import { formatExecuteSummary } from './worktree-apply.js'
@@ -15,10 +16,122 @@ import { formatExecuteSummary } from './worktree-apply.js'
 /**
  * 同步触发辅助函数：_write 后 best-effort 同步到平台
  */
+/**
+ * quick 完成审计：对比 baseline 与实际变更
+ */
+async function auditQuickCompletion(cwd, guard, options = {}) {
+  const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false } = guard
+  const { isConfirm } = options
+  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [] }
+
+  try {
+    const { execSync } = await import('child_process')
+    const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+    const currentEntries = gitStatus.trim().split('\n').filter(Boolean)
+
+    const DANGEROUS_PATTERNS = [
+      '.sillyspec/',
+      'package.json',
+      'package-lock.json',
+      'yarn.lock',
+      'pnpm-lock.yaml',
+      '.eslintrc',
+      'tsconfig.json',
+    ]
+
+    for (const entry of currentEntries) {
+      const status = entry.slice(0, 2).trim()
+      const file = entry.slice(3).trim()
+      if (!file || file.startsWith('??. ')) continue
+
+      result.changedFiles.push(file)
+      if (status === 'D' || status === ' D') result.deletedFiles.push(file)
+      if (status === '??') result.newFiles.push(file)
+
+      // 检查是否命中 baseline protected files
+      if (baselineFiles.includes(file)) {
+        result.baselineHit.push(file)
+      }
+
+      // 检查危险文件（除非 force-baseline）
+      if (DANGEROUS_PATTERNS.some(p => file.includes(p)) && !forceBaseline) {
+        result.reasons.push(`危险文件变更: ${file}`)
+      }
+    }
+
+    // 检查 deleted files
+    for (const f of result.deletedFiles) {
+      result.reasons.push(`删除文件: ${f}`)
+    }
+
+    // 检查 baseline hit（除非 force-baseline）
+    if (!forceBaseline) {
+      for (const f of result.baselineHit) {
+        result.reasons.push(`覆盖 baseline 文件: ${f}`)
+      }
+    }
+
+    // 检查 new files（除非 allow-new）
+    if (!allowNew) {
+      for (const f of result.newFiles) {
+        if (!f.startsWith('.sillyspec/quicklog/') && !f.startsWith('.sillyspec/.runtime/')) {
+          result.reasons.push(`新增文件（需 --allow-new）: ${f}`)
+        }
+      }
+    }
+
+    // 检查 allowedFiles 范围
+    if (allowedFiles.length > 0) {
+      for (const f of result.changedFiles) {
+        if (!allowedFiles.includes(f) && !f.startsWith('.sillyspec/')) {
+          result.reasons.push(`超出 allowedFiles: ${f}`)
+        }
+      }
+    }
+
+    // 判定结果
+    if (result.baselineHit.length > 0 || result.deletedFiles.length > 0 || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
+      result.status = 'blocked'
+    } else if (result.newFiles.length > 0 || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+      result.status = 'warning'
+    }
+
+    // --confirm 模式：展示 diff 并等待确认
+    if (isConfirm && (result.status === 'warning' || result.status === 'blocked')) {
+      console.log(`\n📋 quick 变更概览：`)
+      console.log(`   新增: ${result.newFiles.length}, 修改: ${result.changedFiles.length - result.newFiles.length - result.deletedFiles.length}, 删除: ${result.deletedFiles.length}`)
+      if (result.changedFiles.length > 0) {
+        console.log(`\n   变更文件：`)
+        for (const f of result.changedFiles) {
+          const isBaseline = baselineFiles.includes(f)
+          const isDangerous = DANGEROUS_PATTERNS.some(p => f.includes(p))
+          const marker = isBaseline ? '🔴' : isDangerous ? '⚠️' : '  '
+          console.log(`   ${marker} ${f}`)
+        }
+      }
+      console.log(`\n   状态: ${result.status.toUpperCase()}`)
+      if (result.reasons.length > 0) {
+        console.log(`   原因:`)
+        for (const r of result.reasons) {
+          console.log(`     - ${r}`)
+        }
+      }
+      console.log(`\n   如确认接受这些变更，重新运行：sillyspec run quick --done --confirm --output "..."`)
+      console.log(`   或使用 --force-baseline 允许覆盖 baseline 文件，--allow-new 允许新增文件`)
+    }
+  } catch (e) {
+    result.reasons.push(`审计失败: ${e.message}`)
+    result.status = 'warning'
+  }
+
+  return result
+}
+
 async function triggerSync(cwd, changeName) {
   try {
+    if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) return
     const syncMod = await import('./sync.js')
-    await syncMod.sync(cwd, changeName)
+    await syncMod.sync(changeName, cwd)
   } catch (e) {
     // sync.js 不存在或同步失败，静默跳过
     console.warn('⚠️ 同步失败:', e.message)
@@ -32,7 +145,7 @@ async function triggerSync(cwd, changeName) {
 async function checkApproval(cwd, changeName) {
   try {
     const syncMod = await import('./sync.js')
-    return await syncMod.checkApproval(cwd, changeName)
+    return await syncMod.checkApproval(changeName, cwd)
   } catch (e) {
     // sync.js 不存在或检查失败，静默跳过
     return null
@@ -147,7 +260,7 @@ async function ensureStageSteps(progress, stageName, cwd) {
 /**
  * 输出当前步骤的 prompt
  */
-async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName) {
+async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}) {
   const step = steps[stepIndex]
   const total = steps.length
   const projectName = dbProjectName || basename(cwd)
@@ -218,6 +331,43 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<change-name>')) {
     promptText = promptText.replace(/<change-name>/g, changeName)
   }
+  // 平台模式：注入路径覆盖指令（仅 scan 阶段）
+  if (stageName === 'scan') {
+    const projectName = dbProjectName || basename(cwd)
+    const specSillyspec = platformOpts?.specRoot
+      ? join(platformOpts.specRoot, '.sillyspec')
+      : join(cwd, '.sillyspec')
+    const docsRoot = join(specSillyspec, 'docs', projectName)
+    const projectsRoot = join(specSillyspec, 'projects')
+
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
+
+    // 平台模式附加指令
+    if (platformOpts?.specRoot || platformOpts?.runtimeRoot) {
+      const platformDirectives = []
+      if (platformOpts.specRoot) {
+        platformDirectives.push(
+          `## ⚠️ 平台模式\n` +
+          `文档路径已参数化：\n` +
+          `- 文档根目录: \`${docsRoot}/\`\n` +
+          `- 项目注册表: \`${projectsRoot}/\`\n` +
+          `创建目录: \`mkdir -p ${docsRoot}/{scan,modules,flows} ${projectsRoot}\`\n`
+        )
+      }
+      if (platformOpts.runtimeRoot) {
+        const scanRunId = platformOpts.scanRunId || 'scan-' + new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-')
+        platformDirectives.push(
+          `运行时产物写入: \`${platformOpts.runtimeRoot}/scan-runs/${scanRunId}/\`\n`
+        )
+      }
+      if (platformOpts.workspaceId) {
+        platformDirectives.push(`workspace_id: ${platformOpts.workspaceId}`)
+      }
+      promptText = platformDirectives.join('\n') + '\n\n' + promptText
+    }
+  }
+
   console.log(promptText)
   console.log(`\n### ⚠️ 铁律`)
   console.log('- **文档是核心资产，代码是文档的产物。** 没有文档就没有代码——文档是 AI 的记忆，是团队协作的基础，是后续维护的唯一依据。任何代码产出必须先有对应的设计/规范文档支撑。')
@@ -265,6 +415,50 @@ export async function runCommand(args, cwd) {
   const isConfirm = flags.includes('--confirm')
   const isSkipApproval = flags.includes('--skip-approval')
 
+  // 平台模式参数（供 SillyHub 等平台调用）
+  const getFlagValue = (name) => {
+    const idx = flags.indexOf(name)
+    return idx !== -1 && flags[idx + 1] ? flags[idx + 1] : null
+  }
+  const platformOpts = {
+    specRoot: getFlagValue('--spec-root'),
+    runtimeRoot: getFlagValue('--runtime-root'),
+    workspaceId: getFlagValue('--workspace-id'),
+    scanRunId: getFlagValue('--scan-run-id'),
+  }
+
+  // 跨 --done 生命周期：优先从 metadata 文件恢复 platformOpts
+  // 首次 scan 时写入，后续 --done 读取
+  const platformOptsFile = join(cwd, '.sillyspec', '.runtime', 'platform-scan.json')
+  if (isDone || isSkip) {
+    // --done/--skip 阶段：从文件恢复
+    try {
+      const { readFileSync } = await import('fs')
+      const saved = JSON.parse(readFileSync(platformOptsFile, 'utf8'))
+      if (saved.specRoot) platformOpts.specRoot = saved.specRoot
+      if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
+      if (saved.workspaceId) platformOpts.workspaceId = saved.workspaceId
+      if (saved.scanRunId) platformOpts.scanRunId = saved.scanRunId
+    } catch {
+      // 文件不存在，说明不是平台模式，跳过
+    }
+  } else if (platformOpts.specRoot || platformOpts.runtimeRoot) {
+    // 首次 scan：持久化 platformOpts
+    try {
+      const { mkdirSync, writeFileSync } = await import('fs')
+      mkdirSync(join(cwd, '.sillyspec', '.runtime'), { recursive: true })
+      writeFileSync(platformOptsFile, JSON.stringify({
+        specRoot: platformOpts.specRoot,
+        runtimeRoot: platformOpts.runtimeRoot,
+        workspaceId: platformOpts.workspaceId,
+        scanRunId: platformOpts.scanRunId,
+        savedAt: new Date().toISOString(),
+      }, null, 2) + '\n')
+    } catch {
+      // 静默失败，不影响主流程
+    }
+  }
+
   // 解析 --output
   let outputText = null
   const outputIdx = flags.indexOf('--output')
@@ -286,6 +480,37 @@ export async function runCommand(args, cwd) {
     changeName = flags[changeIdx + 1]
   }
 
+  // 解析 --files a.js,b.js（quick 专用：显式声明 allowedFiles）
+  let quickFiles = []
+  const filesIdx = flags.indexOf('--files')
+  if (filesIdx !== -1 && flags[filesIdx + 1]) {
+    quickFiles = flags[filesIdx + 1].split(',').map(f => f.trim()).filter(Boolean)
+  }
+
+  const isAllowNew = flags.includes('--allow-new')
+  const isForceBaseline = flags.includes('--force-baseline')
+
+  // 未知参数 fail-fast
+  const knownFlags = new Set([
+    '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval',
+    '--output', '--input', '--change',
+    '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
+    '--files', '--allow-new', '--force-baseline',
+    '--json', '--dir', '--help',
+  ])
+  for (let i = 0; i < flags.length; i++) {
+    const f = flags[i]
+    if (f.startsWith('--')) {
+      if (!knownFlags.has(f)) {
+        console.error(`❌ 未知参数: ${f}`)
+        console.error(`已知参数: ${[...knownFlags].sort().join(', ')}`)
+        process.exit(1)
+      }
+      // 跳过 value 参数
+      i++
+    }
+  }
+
   const isAuxiliary = auxiliaryStages.includes(stageName)
 
   const pm = new ProgressManager()
@@ -361,11 +586,11 @@ export async function runCommand(args, cwd) {
 
   // --done
   if (isDone) {
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange })
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, platformOpts })
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval)
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts)
 }
 
 /**
@@ -380,7 +605,19 @@ function resolveChangeNameAuto(cwd) {
   return null
 }
 
-async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false) {
+async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}) {
+  // 状态转换校验
+  const prevStage = progress.currentStage || ''
+  const transition = checkTransition(prevStage, stageName)
+  if (!transition.allowed) {
+    console.error(`❌ 阶段转换不允许: ${prevStage || '(起始)'} → ${stageName}`)
+    console.error(`   原因: ${transition.reason}`)
+    console.error(`   提示: 使用 --skip-approval 绕过（需明确意图）`)
+    if (!skipApproval) {
+      process.exit(1)
+    }
+  }
+
   // execute 阶段启动前检查审批
   if (stageName === 'execute' && !skipApproval) {
     const approval = await checkApproval(cwd, changeName)
@@ -435,6 +672,39 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     console.log(`🔄 ${stageName} 阶段已自动重置，重新开始。\n`)
   }
 
+  // quick 阶段：记录 baselineFiles
+  if (stageName === 'quick' && !progress.quickGuard) {
+    try {
+      const { execSync } = await import('child_process')
+      const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+      const baselineFiles = gitStatus
+        .trim().split('\n').filter(Boolean)
+        .map(line => line.slice(3).trim())
+        .filter(f => !f.startsWith('.sillyspec/'))
+      const allowedFiles = quickFiles || []
+      const allowNew = isAllowNew || false
+      const forceBaseline = isForceBaseline || false
+      progress.quickGuard = {
+        baselineCommit: execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim(),
+        baselineFiles,
+        allowedFiles,
+        allowNew,
+        forceBaseline,
+        startedAt: new Date().toISOString(),
+      }
+      // 写入 quick-guard.json 供 worktree-guard hook 读取
+      const guardFile = join(cwd, '.sillyspec', '.runtime', 'quick-guard.json')
+      writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
+      const parts = [`${baselineFiles.length} 个已有脏文件`]
+      if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
+      if (allowNew) parts.push('允许新增文件')
+      console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
+      await pm._write(cwd, progress, changeName)
+    } catch (e) {
+      console.warn(`⚠️ baseline 记录失败: ${e.message}`)
+    }
+  }
+
   if (currentIdx > 0) {
     const completed = currentIdx
     const total = steps.length
@@ -444,7 +714,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
 
   const defSteps = await getStageSteps(stageName, cwd, progress)
   if (defSteps && defSteps[currentIdx]) {
-    await outputStep(stageName, currentIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(stageName, currentIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
   }
 }
 
@@ -526,8 +796,41 @@ function validateFileLocations(cwd, stageName, progress, changeName) {
   }
 }
 
+async function archiveChangeDirectory(pm, cwd, progress) {
+  const { renameSync } = await import('fs')
+  const archiveChangeName = progress.currentChange
+  if (!archiveChangeName) {
+    console.error('❌ 归档失败：未找到当前变更名（currentChange）')
+    process.exit(1)
+  }
+  const changesDir = join(cwd, '.sillyspec', 'changes')
+  const archiveDir = join(changesDir, 'archive')
+  const srcDir = join(changesDir, archiveChangeName)
+  const date = new Date().toISOString().slice(0, 10)
+  const destDir = join(archiveDir, `${date}-${archiveChangeName}`)
+
+  if (!existsSync(srcDir)) {
+    console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
+    process.exit(1)
+  }
+  if (existsSync(destDir)) {
+    console.error(`❌ 归档失败：目标目录已存在 ${destDir}`)
+    process.exit(1)
+  }
+  mkdirSync(archiveDir, { recursive: true })
+  renameSync(srcDir, destDir)
+
+  if (!existsSync(destDir) || existsSync(srcDir)) {
+    console.error('❌ 归档校验失败：移动操作异常')
+    process.exit(1)
+  }
+
+  await pm.unregisterChange(cwd, archiveChangeName)
+  console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
+}
+
 async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {} } = options
   const stageData = progress.stages[stageName]
   if (!stageData || !stageData.steps) {
     console.error(`❌ 阶段 ${stageName} 未初始化`)
@@ -548,15 +851,48 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     const MAX_OUTPUT = 200
     if (outputText.length > MAX_OUTPUT) {
       steps[currentIdx].output = outputText.slice(0, MAX_OUTPUT) + '…'
-      const artifactsDir = join(cwd, '.sillyspec', '.runtime', 'artifacts')
-      mkdirSync(artifactsDir, { recursive: true })
+      // 平台模式：artifact 写入 runtime-root，否则写 .sillyspec/.runtime/artifacts
+      const artifactBase = platformOpts?.runtimeRoot
+        ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown')
+        : join(cwd, '.sillyspec', '.runtime', 'artifacts')
+      mkdirSync(artifactBase, { recursive: true })
       const ts = new Date().toISOString().slice(0,19).replace(/[-T:]/g, '')
-      writeFileSync(join(artifactsDir, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
+      writeFileSync(join(artifactBase, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
     } else {
       steps[currentIdx].output = outputText
     }
   }
 
+  if (stageName === 'archive' && steps[currentIdx]?.name === '确认归档') {
+    if (!confirm) {
+      steps[currentIdx].status = 'pending'
+      steps[currentIdx].completedAt = null
+      if (outputText) steps[currentIdx].output = null
+      await pm._write(cwd, progress, changeName)
+      console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
+      return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+    }
+    await archiveChangeDirectory(pm, cwd, progress)
+  }
+
+  // archive "确认归档" 步骤完成后，校验归档完整性
+  if (stageName === 'archive' && steps[currentIdx]?.name === '确认归档' && confirm) {
+    const projectName = progress.project || basename(cwd)
+    const contractResult = runValidators('archive', cwd, changeName, { projectName })
+    if (contractResult.errors.length > 0) {
+      console.error(`\n❌ 归档校验失败：`)
+      for (const err of contractResult.errors) {
+        console.error(`   - ${err}`)
+      }
+    }
+    if (contractResult.warnings.length > 0) {
+      console.warn(`\n⚠️ 归档校验警告：`)
+      for (const w of contractResult.warnings) {
+        console.warn(`   - ${w}`)
+      }
+    }
+  }
+
   // plan 阶段 "展开任务" 完成后，动态插入任务蓝图协调器步骤
   if (stageName === 'plan' && steps[currentIdx]?.name === '展开任务并分组') {
     const changeDir = resolveChangeDir(cwd, progress)
@@ -683,50 +1019,61 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       appendFileSync(inputsPath, entry)
     }
 
-    validateMetadata(cwd, stageName)
-
-    // 验证关键文件是否在正确的变更目录下
-    validateFileLocations(cwd, stageName, progress, changeName)
-
-    // archive 阶段确认归档
-    if (stageName === 'archive' && steps[currentIdx]?.name === '确认归档') {
-      if (confirm) {
-        const { renameSync } = await import('fs')
-        const archiveChangeName = progress.currentChange
-        if (!archiveChangeName) {
-          console.error('❌ 归档失败：未找到当前变更名（currentChange）')
-          process.exit(1)
-        }
-        const changesDir = join(cwd, '.sillyspec', 'changes')
-        const archiveDir = join(changesDir, 'archive')
-        const srcDir = join(changesDir, archiveChangeName)
-        const date = new Date().toISOString().slice(0, 10)
-        const destDir = join(archiveDir, `${date}-${archiveChangeName}`)
-
-        if (!existsSync(srcDir)) {
-          console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
-          process.exit(1)
+    // 平台模式：scan 完成后生成 manifest.json
+    if (stageName === 'scan' && platformOpts.specRoot) {
+      try {
+        const { mkdirSync, writeFileSync } = await import('fs')
+        const { join } = await import('path')
+        const { execSync } = await import('child_process')
+        const manifestDir = join(platformOpts.specRoot, '.sillyspec')
+        mkdirSync(manifestDir, { recursive: true })
+        let sourceCommit = null
+        try {
+          sourceCommit = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim()
+        } catch {}
+        const manifest = {
+          workspace_id: platformOpts.workspaceId || null,
+          scan_run_id: platformOpts.scanRunId || null,
+          source_commit: sourceCommit,
+          generated_at: new Date().toISOString(),
+          schema_version: 1,
         }
-        if (existsSync(destDir)) {
-          console.error(`❌ 归档失败：目标目录已存在 ${destDir}`)
-          process.exit(1)
+        const manifestPath = join(manifestDir, 'manifest.json')
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+        console.log(`📄 manifest.json 已写入: ${manifestPath}`)
+        if (!sourceCommit) {
+          console.log(`⚠️  source_commit 无法获取（可能非 git 目录），已设为 null`)
         }
-        mkdirSync(archiveDir, { recursive: true })
-        renameSync(srcDir, destDir)
-
-        if (!existsSync(destDir) || existsSync(srcDir)) {
-          console.error('❌ 归档校验失败：移动操作异常')
-          process.exit(1)
+        // 清理平台参数临时文件
+        const { unlinkSync } = await import('fs')
+        const platformOptsFile = join(cwd, '.sillyspec', '.runtime', 'platform-scan.json')
+        try { unlinkSync(platformOptsFile) } catch {}
+
+        // 平台模式后置校验：检查 source_root 是否被污染
+        if (platformOpts.specRoot) {
+          const { readdirSync } = await import('fs')
+          const localDocsDir = join(cwd, '.sillyspec', 'docs')
+          try {
+            if (existsSync(localDocsDir)) {
+              const entries = readdirSync(localDocsDir, { recursive: true }).filter(e => e.endsWith('.md'))
+              if (entries.length > 0) {
+                console.warn(`⚠️ 平台模式后置校验：source_root 下存在 ${entries.length} 个文档文件：`)
+                console.warn(`   路径：${localDocsDir}/`)  
+                console.warn(`   可能原因：agent 未遵守路径覆盖，将文档写入到了 cwd 而非 spec-root`)
+              }
+            }
+          } catch {}
         }
-
-        // 从全局活跃列表移除
-        await pm.unregisterChange(cwd, archiveChangeName)
-        console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
-      } else {
-        console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
+      } catch (e) {
+        console.warn(`⚠️  manifest.json 写入失败: ${e.message}`)
       }
     }
 
+    validateMetadata(cwd, stageName)
+
+    // 验证关键文件是否在正确的变更目录下
+    validateFileLocations(cwd, stageName, progress, changeName)
+
     // 辅助阶段完成后重置步骤
     const stageDef = stageRegistry[stageName]
     if (stageDef?.auxiliary) {
@@ -739,6 +1086,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       stageData.steps = freshSteps
       stageData.status = 'pending'
       stageData.completedAt = null
+      if (progress.currentStage === stageName) progress.currentStage = ''
       await pm._write(cwd, progress, changeName)
     }
 
@@ -771,6 +1119,50 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
+  // 阶段完成校验
+  const projectName = progress.project || basename(cwd)
+  const contractResult = runValidators(stageName, cwd, changeName, { projectName })
+  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(cwd, '.sillyspec', '.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)
@@ -862,7 +1254,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   }
 
   if (printNext) {
-    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
   }
   return { stageCompleted: false, currentIdx, nextPendingIdx }
 }
@@ -900,7 +1292,7 @@ async function skipStep(pm, progress, stageName, cwd, changeName) {
   const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
   if (nextPendingIdx !== -1 && defSteps) {
     console.log('')
-    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
   }
 }
 
@@ -1045,7 +1437,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
         }
       }
     }
-    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
     return
   }
 
@@ -1054,7 +1446,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
     process.exit(1)
   }
 
-  const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName })
+  const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName, platformOpts })
   if (!result) return
   progress = await pm.read(cwd, changeName)
 
@@ -1075,7 +1467,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
         }
       }
     }
-    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
     return
   }
 
@@ -1117,6 +1509,6 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
         }
       }
     }
-    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null)
+    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null, platformOpts)
   }
 }