sillyspec 3.27.6 → 3.27.7

package/.worktrees/542c4415/src/run/quick-audit.js

@@ -0,0 +1,186 @@
+/**
+ * run/quick-audit.js（W6 Step2 从 run.js 抽出）。
+ *
+ * quick 审计结论打印 + quick 多变更关联选择（自洽，不依赖 run.js 闭包）。
+ * 安全锚：run.js 始终 barrel，本模块函数 run.js import 回来；无 test 直接 import，无需 re-export。
+ *
+ * 路径修正（相对 src/run/）：
+ *   - resolveQuickLinkedChanges 的 quick-recommend.js 动态 import './quick-recommend.js' → '../quick-recommend.js'
+ *   - 脏文件信号改用 safeGit（带 safe.directory，Q3）；不再 import execSync
+ *   - parsePorcelainPath 从 ./shared.js 重 import；checkbox 改交互分支内动态 import——
+ *     本模块被 command.js 静态 import，顶部静态拉 @inquirer/prompts 会进**每条** run 命令
+ *     启动路径（实测冷加载 100-150ms），而 checkbox 仅"≥2 活跃变更 + TTY"分支用到
+ */
+import { parsePorcelainPath, safeGit } from './shared.js'
+
+/**
+ * 打印 quick 完成审计结论（按 review.status 输出 SAFE/WARNING/BLOCKED）。
+ */
+export 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 并显式声明范围。`)
+    // 解锁咒语须在 BLOCKED 分支也给出 —— 原只在 confirm/review 分支打印，
+    // 普通 --done 走这里只看到「恢复/拆分」反方向指引，正确解法（带 flag 重跑）根本不出现。
+    // 删除：默认 fail-closed（高危操作），但 --allow-delete 显式 opt-in 可解锁（对称 --allow-new）。
+    if (review.deletedFiles && review.deletedFiles.length > 0) {
+      console.error(`\n   ⛔ 本次含删除文件 ${review.deletedFiles.length} 个：${review.deletedFiles.join(', ')}`)
+      console.error(`   删除是破坏性操作默认 fail-closed，确认删除这些文件请带 --allow-delete 显式解锁：`)
+      console.error(`     sillyspec run quick --done --allow-delete --change <id> --output "..."`)
+      console.error(`   （--force-baseline / --allow-new 不能解锁删除；不确认请 git restore 撤回删除后再 --done，或走完整流程 execute 由 review 把关）`)
+    } else {
+      console.error(`   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
+      console.error(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
+      console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件；--allow-delete 允许删除文件）`)
+      // 两套开关明示（坑 files-flag-not-unlock-protected，2026-08-22 实证：模块文档被判危险
+      // 文件，追加 --files 边界不解锁仍被拦——「追加边界」与「解锁拦截」是两套开关，交互上易误解
+      // 前者能解决后者）。命中危险文件 reason 时点名：--files 只改归属口径（哪些文件计入本
+      // 会话），不改变危险判定；受保护/危险文件的放行开关唯 --force-baseline。
+      if (review.reasons.some(r => r.startsWith('危险文件变更'))) {
+        console.error(`   ⛔ 注意：追加 --files 边界不会解锁受保护/危险文件的拦截（两套开关——--files 只声明哪些文件计入本会话，不改变危险判定）。改这类文件必须 --force-baseline。`)
+      }
+    }
+  } else if (review.status === 'warning') {
+    console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
+    for (const r of review.reasons) {
+      console.warn(`   - ${r}`)
+    }
+  } else {
+    // 区分「本轮新增」（changedFiles，已扣前序 baseline）vs「累计暂存」（stagedTotal，全部未提交）。
+    // 仅当存在前序 baseline 残留（累计 > 本轮新增）时才追加括注，避免普通场景冗余。
+    const stagedTotal = typeof review.stagedTotal === 'number' ? review.stagedTotal : review.changedFiles.length
+    if (stagedTotal > review.changedFiles.length) {
+      console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件；累计暂存 ${stagedTotal} 个，含前序 baseline ${stagedTotal - review.changedFiles.length} 个未计入本轮)`)
+    } else {
+      console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件)`)
+    }
+  }
+  // 关联变更遗留放行提示（坑 linked-change-leftover-false-block，独立于三态都打——放行可见
+  // 可审计，不静默）：这些文件属关联变更目录但不在本会话归属（启动后出现的他者遗留），
+  // 已剔除出本会话文件行，由关联变更自己的流程收尾。
+  if (Array.isArray(review.linkedChangeLeftovers) && review.linkedChangeLeftovers.length > 0) {
+    console.warn(`
+🧹 关联变更目录检测到 ${review.linkedChangeLeftovers.length} 个遗留脏文件（他者/上个 session 残留，非本会话改动）——已放行不计入本会话：`)
+    for (const f of review.linkedChangeLeftovers) console.warn(`   - ${f}`)
+    console.warn(`   它们归关联变更自己的流程管；若确系本会话需要改，用 --files 显式声明归属。`)
+  }
+
+  // 他者会话声明豁免提示（坑 foreign-session-declared-false-block，独立于三态都打——放行可见
+  // 可审计，不静默，与上块同哲学）：多 agent 并发时并行 quick 会话 --files 已声明的文件在本会话
+  // 窗口内出现——不属本会话，已退栈归该会话审计，本会话无需 --force-baseline。
+  if (Array.isArray(review.foreignSessionDeclared) && review.foreignSessionDeclared.length > 0) {
+    console.warn(`
+🔗 ${review.foreignSessionDeclared.length} 个文件已由其他 active quick 会话声明——已剔除出本会话审计，归该会话边界管：`)
+    for (const x of review.foreignSessionDeclared) console.warn(`   - ${x.file} ← ${(x.sessions || []).join(', ')}`)
+    console.warn(`   并发下无需 --force-baseline：这些文件不属本会话。若确系本会话改动，恢复会话时 --files 追加声明归属（sillyspec run quick --files <file> --change <本会话ID>）；`)
+    console.warn(`   他者会话若为崩溃残留（超 7 天未收尾），sillyspec run quick --cancel --change <他者会话ID> 清理后声明即失效。`)
+  }
+
+  // D-8 文档欠账显性化（advisory，独立于 status 三态都打）：改了源码没动文档 → 一行欠账标记。
+  // 不阻断、不解锁、纯显性化——累积欠账可事后审计 QUICKLOG reasons 追溯。
+  if (review.docSyncHint && review.docSyncHint.touchedSource > 0 && review.docSyncHint.docFiles.length === 0) {
+    console.warn(`\n📝 文档欠账标记（D-8）：本次 ${review.docSyncHint.touchedSource} 个源码文件改动未同步任何模块文档。`)
+    // O-1（docs-signals-o12）：模块归属——从"改了 N 文件"到"欠在哪"（matchFilesToModules 纯函数，map 缺失时空数组降级）
+    if (Array.isArray(review.docSyncHint.modules) && review.docSyncHint.modules.length > 0) {
+      console.warn(`   涉及模块：${review.docSyncHint.modules.map(m => m.id).join(' · ')}（模块卡待同步，execute 场景详见 [docs-debt] 块）`)
+    }
+    console.warn(`   quick 不强制文档同步，欠账已随本条 QUICKLOG「审计：」行落盘（可事后追溯）。若改动触及接口/契约，建议顺手同步模块文档。`)
+  }
+  if (review.docsCheckHint && review.docsCheckHint.invalid > 0) {
+    console.warn(`\n📎 文档引用失效（docs check）：本次改动的文档含 ${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处失效 file:line 引用。`)
+    console.warn(`   行号漂移 → 更新到当前源码；文件删改名 → 更新引用路径。跑 sillyspec docs check 可看完整清单。`)
+    console.warn(`   引用格式：\`src/foo.js:42\`（或 42-48）+ 同行反引号代码符号（如 \`runDocsCheck\`）——符号可让 --suggest 给出候选行号。`)
+  }
+  // task-03: 活文档引用真失效提示（advisory 不阻断，不改 status 三态判定）——方向与上方互补：
+  // 上方查「本次改的文档」，这里查「本次改的 src 被活文档（platform-interface-map 等）引用」。
+  // 2026-08-18 精度对齐：只渲染真失效引用（drift.invalid，auditQuickCompletion 已跑 runDocsCheck
+  // 分层校验），行号锚未真断时零输出——不再「被引用即提示」误报。
+  if (review.docsCheckHint && review.docsCheckHint.livingDocDrift) {
+    const drift = review.docsCheckHint.livingDocDrift
+    const invalid = Array.isArray(drift.invalid) ? drift.invalid : []
+    const total = typeof drift.total === 'number' ? drift.total : drift.files.length
+    if (invalid.length > 0) {
+      console.warn(`\n📎 活文档引用真失效：${drift.files.length}/${total} 个改动 src 文件被 ${drift.docs.join('、')} 引用，其中 ${invalid.length} 处引用校验失败：`)
+      for (const x of invalid.slice(0, 8)) {
+        console.warn(`   - ${x.doc}:${x.docLine} \`${x.ref}\` → ${x.reason}`)
+      }
+      if (invalid.length > 8) console.warn(`   … 共 ${invalid.length} 处，跑 sillyspec docs check 看全量与建议行号`)
+      else console.warn(`   行号漂移 → 更新到当前源码；跑 sillyspec docs check 可看建议行号。`)
+    }
+  }
+}
+
+/**
+ * quick 阶段多变更交互式选择关联变更。
+ * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
+ * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
+ * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
+ * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
+ */
+export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
+  let activeChanges = []
+  try {
+    activeChanges = pm.listChanges(cwd)
+  } catch {
+    activeChanges = []
+  }
+  if (activeChanges.length === 0) return []
+  if (activeChanges.length === 1) return [activeChanges[0]]
+
+  if (nonInteractive || !process.stdin.isTTY) {
+    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
+    return []
+  }
+
+  // 脏文件（推荐信号之一）。safeGit 带 safe.directory，避免 linked worktree/容器/挂载点下裸
+  // `git status` 抛错致推荐信号静默丢失（multi-agent-review Q3 同类）。推荐非关键路径，失败回退 []。
+  // trim:false：porcelain 首行前导空格是状态码，trim 会削掉致 parsePorcelainPath 丢首字符。
+  let baselineFiles = []
+  const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+  if (!statusResult.error) {
+    baselineFiles = (statusResult.value || '').split('\n').filter(Boolean)
+      .map(l => parsePorcelainPath(l))
+      .filter(Boolean)
+      .filter(f => !f.startsWith('.sillyspec/'))
+  }
+
+  // 推荐打分（脏文件 + 任务描述双信号）
+  let recommendations = []
+  try {
+    // quick-recommend.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
+    const { recommendChanges } = await import('../quick-recommend.js')
+    recommendations = recommendChanges({ activeChanges, specDir, baselineFiles, quickFiles, taskDescription })
+  } catch {
+    recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
+  }
+  const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
+  const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
+  const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
+
+  // 按推荐分降序展示
+  const ordered = [...activeChanges].sort((a, b) =>
+    (scoreMap.get(b) || 0) - (scoreMap.get(a) || 0) || a.localeCompare(b))
+
+  const choices = ordered.map(name => {
+    const reasons = reasonMap.get(name) || []
+    const isRec = recommendedSet.has(name)
+    return {
+      name: `${isRec ? '⭐ ' : '   '}${name}`,
+      value: name,
+      description: reasons.length > 0 ? reasons.join('；') : '无推荐信号',
+      checked: isRec,
+    }
+  })
+
+  console.log('🔗 检测到多个活跃变更，选择本次 quick 关联哪些（可多选；不勾选任何项 = 仅记 QUICKLOG，不关联变更）')
+  if (recommendedSet.size > 0) {
+    console.log('   ⭐ = 基于脏文件/任务描述推荐，已默认勾选')
+  }
+  // 动态 import：@inquirer/prompts 只在本交互分支加载，不进 run 命令通用启动路径
+  const { checkbox } = await import('@inquirer/prompts')
+  const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
+  return selected
+}

package/.worktrees/542c4415/src/run/scan-profile.js

@@ -0,0 +1,269 @@
+/**
+ * run/scan-profile.js（W6 Step2 从 run.js 抽出）。
+ *
+ * scan profile 数据生成 + quick scan CLI preflight/postcheck（自洽，不依赖 run.js 闭包）。
+ * 安全锚：run.js 始终 barrel，本模块函数 run.js import 回来；无 test 直接 import，无需 re-export。
+ *
+ * 路径修正（相对 src/run/）：
+ *   - executeScanPostcheck 的 scan-postcheck.js 动态 import './scan-postcheck.js' → '../scan-postcheck.js'
+ *   - executeScanPostcheck 原冗余动态 import('fs'/'path'/'child_process') 删除，改顶部静态（execSync 实际未直接用，纯遗留）
+ */
+import { join, basename, extname } from 'node:path'
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { safeGit } from './shared.js'
+
+/**
+ * 估算源码规模（文件数 + 字节数）—— 跨平台 Node 遍历，替代 Unix `find`（原生 Windows 无 find，
+ * 原 find 失效会让所有 Windows 项目永远 fallback 到 standard profile）。
+ * 扩展名限定源码后缀；skipDirs 排除依赖/构建产物/覆盖率等非源码目录；maxFiles 封顶避免超大仓库遍历过久
+ * （超限时 fileCount 已远超 quick/standard 阈值，不影响 profile 判定）；maxDepth 兜底防极深嵌套产物。
+ */
+export function estimateSourceSize(cwd, maxFiles = 5000, maxDepth = 6) {
+  const sourceExts = new Set(['.js','.ts','.tsx','.py','.java','.go','.rs','.rb','.php','.c','.cpp','.h','.jsx','.vue','.svelte'])
+  // skipDirs：排除依赖、版本控制、构建产物、覆盖率、临时目录等非源码目录。
+  // 原清单只排了 node_modules/.git/dist/build 等，漏了 .next/.nuxt/coverage/.svelte-kit 等构建产物，
+  // 导致带构建产物的小项目被产物里的海量 .js 拉高 fileCount/sourceBytes → 误判 deep。
+  const skipDirs = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', 'target',
+    '__pycache__', '.venv', 'venv',
+    '.next', '.nuxt', '.output', '.svelte-kit', '.astro', '.turbo', '.parcel-cache',
+    'coverage', '.nyc_output', '.vitest', '.cache',
+    'vendor', 'bower_components',
+    'dist-types',
+    '.sillyspec', '.claude',
+    'tmp', 'temp', '.tmp', 'logs',
+  ])
+  let fileCount = 0
+  let sourceBytes = 0
+  // stack 存 [dir, depth]：maxDepth 兜底，防极深嵌套的产物/生成目录在 skipDirs 漏网时被全遍历。
+  const stack = [[cwd, 0]]
+  while (stack.length) {
+    const [dir, depth] = stack.pop()
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) }
+    catch { continue }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!skipDirs.has(e.name) && depth < maxDepth) stack.push([join(dir, e.name), depth + 1])
+      } else if (e.isFile() && sourceExts.has(extname(e.name))) {
+        fileCount++
+        try { sourceBytes += statSync(join(dir, e.name)).size } catch {}
+        if (fileCount >= maxFiles) return { fileCount, sourceBytes }
+      }
+    }
+  }
+  return { fileCount, sourceBytes }
+}
+
+/**
+ * 根据 project 规模计算 scan profile
+ * quick:   fileCount≤30 && sourceBytes≤80KB && projectCount≤3 → 3 步，0 子代理，5 份文档
+ * standard: fileCount≤200 && sourceBytes≤800KB → 压缩步骤，最多 1 子代理
+ * deep:    大项目或 --deep → 完整流程
+ */
+export function computeScanProfile(cwd, platformOpts) {
+  // 显式 profile flag 优先于自动判定（三档互斥由 command.js 检测；此处取首个命中即可）
+  const flags = process.argv.slice(2)
+  if (flags.includes('--quick')) {
+    return { mode: 'quick', reason: '用户指定 --quick', maxAgentCalls: 0, maxDocs: 5 }
+  }
+  if (flags.includes('--standard')) {
+    return { mode: 'standard', reason: '用户指定 --standard', maxAgentCalls: 1, maxDocs: 8 }
+  }
+  if (flags.includes('--deep')) {
+    return { mode: 'deep', reason: '用户指定 --deep', maxAgentCalls: 4, maxDocs: 99 }
+  }
+
+  const specDir = platformOpts?.specRoot || join(cwd, '.sillyspec')
+  const projectsDir = join(specDir, 'projects')
+  let projectCount = 1
+  try {
+    if (existsSync(projectsDir)) {
+      projectCount = readdirSync(projectsDir).filter(f => f.endsWith('.yaml')).length
+    }
+  } catch {}
+
+  // 快速估算源码规模（Node 遍历，跨平台；原 Unix find 在原生 Windows 上失效会永远 fallback standard）
+  let fileCount = 0
+  let sourceBytes = 0
+  try {
+    const est = estimateSourceSize(cwd)
+    fileCount = est.fileCount
+    sourceBytes = est.sourceBytes
+  } catch {
+    // 遍历异常时假设中等规模
+    return { mode: 'standard', reason: '无法估算项目规模', maxAgentCalls: 1, maxDocs: 8 }
+  }
+
+  if (fileCount <= 30 && sourceBytes <= 80_000 && projectCount <= 3) {
+    return { mode: 'quick', reason: `${fileCount} 源文件, ${Math.round(sourceBytes / 1024)}KB`, maxAgentCalls: 0, maxDocs: 5, _fileCount: fileCount, _sourceBytes: sourceBytes, _projectCount: projectCount }
+  }
+  if (fileCount <= 200 && sourceBytes <= 800_000) {
+    return { mode: 'standard', reason: `${fileCount} 源文件, ${Math.round(sourceBytes / 1024)}KB`, maxAgentCalls: 1, maxDocs: 8, _fileCount: fileCount, _sourceBytes: sourceBytes, _projectCount: projectCount }
+  }
+  return { mode: 'deep', reason: `${fileCount} 源文件, ${Math.round(sourceBytes / 1024)}KB`, maxAgentCalls: 4, maxDocs: 99, _fileCount: fileCount, _sourceBytes: sourceBytes, _projectCount: projectCount }
+}
+
+/**
+ * quick 档 3 步表构建（唯一真相）：applyScanProfileSteps（首进程裁剪）与 getStageSteps
+ * （后续进程重取定义）共用。此前 quick 步骤表只在首进程 applyScanProfileSteps 里内联构建，
+ * getStageSteps('scan') 恒返回 11 步注册表 → 同进程 outputStep 用注册表 defSteps[1] 渲染错位
+ * prompt；跨进程 ensureStageSteps 见 3 vs 11 触发长度漂移重播种，quick 已完成步丢失、
+ * agent 从未做过的注册表步骤被 --done（坑 scan-quick-profile-step-mismatch）。
+ */
+export function buildQuickScanSteps() {
+  return [
+    {
+      name: '项目概览（自动探测）',
+      status: 'pending',
+      noAI: true,
+      _cliAction: 'scanPreflight',
+      prompt: '',
+      outputHint: 'preflight 结果',
+      optional: false
+    },
+    {
+      name: '生成核心文档',
+      status: 'pending',
+      prompt: `## Quick Scan — 核心文档生成
+
+当前为 quick profile（小项目自动判定 或 用户显式 --quick），一次性生成核心文档用于快速接入。
+
+### 操作
+1. 读取项目结构和关键文件（package.json / pyproject.toml / README / 入口文件）
+2. 生成以下 4 份文档并写入 \`{DOCS_ROOT}/scan/\`：
+   - **PROJECT.md** — 项目简介、技术栈、模块划分
+   - **ARCHITECTURE.md** — 架构概览、模块关系、技术决策
+   - **CONVENTIONS.md** — 代码风格、框架隐形规则
+   - **STRUCTURE.md** — 目录树 + 模块说明
+3. 如发现子项目，注册到 \`{PROJECTS_ROOT}/\` 下
+
+每份文档 frontmatter 必须包含：\`author\`、\`created_at\`、\`scan_depth: quick\`（标记快速接入的浅层版本；后续深度扫描 --deep 会识别此标记并覆盖升级为完整文档）。
+
+### ⛔ 硬约束
+- **严禁使用子代理（Agent/Task 工具）。** 所有文档在一个 turn 内完成。
+- 不要搜索 .sillyspec/ .claude/ .git/ node_modules/ dist/ build/
+- --output 只需要列出生成的文件名，不要写长篇总结
+
+### 输出
+生成的文件列表`,
+      outputHint: '文件列表',
+      optional: false
+    },
+    {
+      // 名字与注册表末步一致（按名匹配/迁移语义）；prompt 清空、noAI postcheck 自动执行
+      name: '自检和提交',
+      status: 'pending',
+      prompt: '',
+      outputHint: '结果',
+      optional: false,
+      noAI: true,
+      _cliAction: 'scanPostcheck'
+    }
+  ]
+}
+
+/**
+ * 根据 scanProfile 裁剪步骤
+ * quick:   3 步 — CLI preflight / AI generate / CLI postcheck
+ * standard: 跳过续扫检测(4), 跳过可选步骤(9)
+ */
+export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
+  const steps = stageData.steps
+  const mode = profile.mode
+
+  if (mode === 'quick') {
+    // 3 步表构建抽至 buildQuickScanSteps（getStageSteps 同源复用，防跨进程 3 vs 11 漂移）
+    stageData.steps = buildQuickScanSteps()
+    return
+  }
+
+  if (mode === 'standard') {
+    // 跳过 Step 4（断点续扫检测），跳过 Step 9（flows+glossary，可选）
+    const skipNames = ['断点续扫检测', '生成业务流程和术语表（可选）']
+    for (const step of stageData.steps) {
+      if (skipNames.includes(step.name) && step.status === 'pending') {
+        step.status = 'skipped'
+        step.skippedAt = new Date().toLocaleString('zh-CN', { hour12: false })
+      }
+    }
+  }
+}
+
+/**
+ * CLI-only: quick scan preflight
+ * 收集项目快照，打印 summary，不调 AI
+ */
+export async function executeScanPreflight(cwd, platformOpts, scanProfile) {
+  const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+  const projectName = basename(cwd)
+  console.log(`  📁 项目: ${projectName}`)
+  console.log(`  📊 Profile: ${scanProfile.mode} (${scanProfile.reason})`)
+  // 快速列出顶层结构（readdirSync 跨平台，避免 spawn shell + 5 个 grep 进程）
+  try {
+    const skip = new Set(['node_modules', '.git', '.sillyspec', '.claude'])
+    const dirNames = readdirSync(cwd, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !skip.has(d.name) && !d.name.startsWith('.'))
+      .slice(0, 20)
+      .map(d => d.name)
+    if (dirNames.length) {
+      console.log(`  📂 目录: ${dirNames.join(', ')}`)
+    }
+  } catch {}
+  console.log(`  ✅ Preflight 完成，准备生成核心文档\n`)
+}
+
+/**
+ * CLI-only: quick scan postcheck
+ * 执行文件存在性 + manifest 检查，不调 AI
+ */
+export async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
+  // scan-postcheck.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
+  const { runScanPostCheck, printScanPostCheckResult } = await import('../scan-postcheck.js')
+  const specDir = platformOpts?.specRoot || null
+  const result = runScanPostCheck({
+    cwd,
+    specDir,
+    scanMeta: {
+      projectListParsed: true,
+      manifestWritten: undefined,
+    },
+  })
+  printScanPostCheckResult(result)
+  // 写 manifest（如果还没写）
+  if (platformOpts?.specRoot) {
+    try {
+      const manifestDir = platformOpts.specRoot
+      let sourceCommit = null
+      let sourceCommitError = null
+      try {
+        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: {
+          mode: scanProfile.mode,
+          file_count: scanProfile._fileCount || 0,
+          source_bytes: scanProfile._sourceBytes || 0,
+          project_count: scanProfile._projectCount || 0,
+          reason: scanProfile.reason,
+        },
+        workspace_id: platformOpts.workspaceId || null,
+        scan_run_id: platformOpts.scanRunId || null,
+        source_commit: sourceCommit,
+        source_commit_error: sourceCommit === null ? (sourceCommitError || 'unknown') : undefined,
+        generated_at: new Date().toISOString(),
+        schema_version: 2,
+      }
+      const manifestPath = join(manifestDir, 'manifest.json')
+      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+      console.log(`  📄 manifest.json 已写入: ${manifestPath}`)
+    } catch (e) {
+      console.warn(`  ⚠️ manifest 写入失败: ${e.message}`)
+    }
+  }
+}