sillyspec 3.25.8 → 3.25.11

package/src/run/shared.js

@@ -1,600 +1,648 @@
-/**
- * run.js 共享纯工具（W6 Step1 从 run.js 抽出）。
- *
- * 安全锚：run.js 始终是 barrel。这些函数搬至此模块后，run.js import 回来；
- * parsePorcelainPath + auditQuickCompletion 被 test 直接 import，run.js 必须 re-export。
- *
- * 路径修正（相对 src/run/）：
- *   - resolvePromptIncludes 的 templates/prompts 在仓库根 → __dirname 上两层
- *   - triggerSync 的动态 import './sync.js' → '../sync.js'（src/sync.js）
- *   - safeGit 原用顶层 require('child_process')，改静态 import execSync（更 ESM-native）
- */
-import { basename, join, resolve, dirname, sep } from 'node:path'
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-
-// ── Wait State Constants ──（W6 Step3 从 run.js 搬入：prompt.js outputStep 与 run.js wait-detection 共用）
-// 正则匹配：只识别独立一行的标记，避免误伤文档正文引用
-export const WAIT_MARKER_RE = /^\s*\[(WAIT_FOR_USER|NEEDS_CONFIRM|NEEDS_DECISION)\]\s*$/m
-
-// ── did-you-mean（命令级 + flag 级 typo 建议，零依赖）──
-// 历史：agent 打错命令名/flag 名只报「未知」+整屏列表，要自己捞正确拼写。
-export function levenshtein(a, b) {
-  const m = String(a).length, n = String(b).length
-  if (!m) return n; if (!n) return m
-  let prev = Array.from({ length: n + 1 }, (_, i) => i)
-  for (let i = 1; i <= m; i++) {
-    const cur = [i]
-    for (let j = 1; j <= n; j++) {
-      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
-    }
-    prev = cur
-  }
-  return prev[n]
-}
-export function didYouMean(input, candidates) {
-  if (!input) return null
-  let best = null, bestD = Infinity
-  for (const c of candidates) {
-    const d = levenshtein(String(input).toLowerCase(), String(c).toLowerCase())
-    if (d < bestD) { bestD = d; best = c }
-  }
-  return (best !== null && bestD <= Math.max(1, Math.floor(String(input).length / 2))) ? best : null
-}
-
-// ── 变更名路径穿越消毒（F6）──
-// change 名会被 join 进 .sillyspec/changes/<name>/ 当目录用。若含 ../ 或路径分隔符，
-// 会逃出 changes/ 写到任意位置（如 --change ../../etc/x 把 proposal.md 写到 changes 同级之外）。
-// 在 --change 解析边界统一消毒，比在每个 join 点守卫更集中。合法名：字母/数字/._-，禁分隔符与 ..
-export function assertSafeChangeName(name, label = '变更名') {
-  if (name == null) return
-  const s = String(name)
-  if (s === '') throw new Error(`${label}不能为空`)
-  // 含路径分隔符 或 父目录穿越段 → 拒绝（Windows 下 \\ 也算）
-  if (/[\\/]/.test(s) || /(^|[/\\])\.\.(?=$|[/\\])/.test(s) || s === '..' || s.includes('..')) {
-    throw new Error(`${label}「${s}」含路径分隔符或 ..，禁止路径穿越（变更名只能是 .sillyspec/changes/ 下的一个目录名，不能逃出）`)
-  }
-  if (!/^[\w.\-]+$/.test(s)) {
-    throw new Error(`${label}「${s}」含非法字符（仅允许字母、数字、._-）`)
-  }
-}
-
-import { buildExecuteSteps } from '../stages/execute.js'
-import { buildPlanSteps } from '../stages/plan.js'
-import { stageRegistry } from '../stages/index.js'
-
-/**
- * 解析 prompt 中的 {{include: <name>}} 占位符：读包内 templates/prompts/<name>.md 注入。
- * 把 stage step prompt 里 self-contained 的大块抽到外部模板，CLI 端组装时注入——
- * agent 收到的仍是自包含 prompt 字符串，无需自己 Read。单次替换（不递归）；
- * 模板缺失则保留占位符并 warn，便于发现配置错误。
- */
-export function resolvePromptIncludes(text) {
-  return text.replace(/\{\{include:\s*([\w.-]+)\s*\}\}/g, (match, name) => {
-    // shared.js 在 src/run/，templates/prompts 在仓库根 → 上两层
-    const tplPath = join(__dirname, '..', '..', 'templates', 'prompts', `${name}.md`)
-    if (!existsSync(tplPath)) {
-      console.warn(`⚠️ prompt include 模板缺失: ${name} (期望: ${tplPath})`)
-      return match
-    }
-    return readFileSync(tplPath, 'utf8')
-  })
-}
-
-/**
- * 找 .sillyspec 祖先目录：用户指定 specDir 优先，否则从 cwd 向上找。
- * @param {string} cwd
- * @param {object} [opts]
- * @param {string} [opts.specDir] - 用户指定的 specDir（通过 --spec-dir 或 --spec-root）
- * @returns {string} 规范目录的绝对路径
- */
-export function resolveSpecDir(cwd, opts = {}) {
-  if (opts.specDir) return resolve(opts.specDir)
-  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')
-}
-
-/**
- * 枚举 cwd 祖先链（含自身）上所有 .sillyspec 目录的绝对路径，上界 = git root。
- *
- * 返回顺序：从 cwd 最近开始向上到 git root（含两端命中项）。单实例项目任意子目录恒返回 [自身]。
- *
- * 上界 = git root（monorepo 天然边界）。必须有限上界：一路数到文件系统根会撞 home 等
- * 无关祖先的孤立 .sillyspec（home 下任何项目都被误报多实例）。非 git 仓库：不向上数，
- * 只看 cwd 自身（≤1，永不误报）。
- *
- * 被 countAncestorSpecDirs（漂移提醒 warn）与 locateQuickSessionGuard（quick 漂移 fail-fast
- * 守卫，坑 quick-cwd-drift-splits-specdir）共用 —— 单一真相源，避免两处各自重写祖先枚举漂移。
- */
-export function ancestorSpecDirs(cwd) {
-  const resolved = resolve(cwd)
-  // 上界 = git root。但 linked worktree 内 --show-toplevel 返回 worktree 根(非主仓根),
-  // 祖先链到不了主仓 .sillyspec → 漂移提醒/quick 守卫全哑(坑 worktree-execute-spec-drift)。
-  // 复刻 worktree.js _resolveMainRepoRoot:--git-common-dir 的 dirname 才是主仓根,取更靠上者作 ceiling。
-  // (git 可能返回相对路径,须 resolve(cwd, commonDir) 绝对化,否则相对 process.cwd 误解析。)
-  const topLevel = safeGit(resolved, ['rev-parse', '--show-toplevel']).value
-  let ceiling = topLevel ? resolve(topLevel) : null
-  const commonDir = safeGit(resolved, ['rev-parse', '--git-common-dir']).value
-  if (commonDir) {
-    const absCommonDir = resolve(resolved, commonDir)
-    if (existsSync(absCommonDir) && statSync(absCommonDir).isDirectory()) {
-      const mainRoot = dirname(absCommonDir)
-      // 主仓根是 worktree 根的祖先时取它(更靠上);monorepo/单仓两者相等不替换,行为不变
-      if (!ceiling || resolve(ceiling).startsWith(resolve(mainRoot) + sep)) ceiling = mainRoot
-    }
-  }
-  const dirs = []
-  let dir = resolved
-  while (true) {
-    if (existsSync(join(dir, '.sillyspec'))) dirs.push(join(dir, '.sillyspec'))
-    if (!ceiling || resolve(dir) === resolve(ceiling)) break
-    const parent = dirname(dir)
-    if (parent === dir) break
-    dir = parent
-  }
-  return dirs
-}
-
-/**
- * 统计 cwd 祖先链上有多少个 .sillyspec 目录（= ancestorSpecDirs(cwd).length）。
- *
- * ≥2 个 = monorepo 多实例（子项目独立 .sillyspec + 根 .sillyspec 并存），resolveSpecDir 命中的
- * 「最近」实例未必是用户意图的项目（如 cd 进被独立 scan 的子项目跑测试后忘回根）→ 漂移风险。
- * 单实例项目在任意子目录工作恒返回 1，不误报。
- */
-export function countAncestorSpecDirs(cwd) {
-  return ancestorSpecDirs(cwd).length
-}
-
-/**
- * 在 cwd 祖先链的各 specBase 中查找 quick 会话 guard.json（坑 quick-cwd-drift-splits-specdir）。
- *
- * sessionId（quick-<uuid8>）全局唯一，但 guard.json 按 specBase 分散落盘
- * （<specBase>/.runtime/quick-sessions/<sessionId>/guard.json）。cd 漂移到子项目后，当前 specBase
- * 下读不到本 session 的 guard，但祖先链别处的 specBase（创建 session 的根）仍有它 → 据此定位
- * session 真正归属，供 detectQuickSessionDrift 的 fail-fast 守卫判断。
- *
- * 遍历顺序 = ancestorSpecDirs（cwd 最近 → git root），返回第一个命中。
- *
- * @param {string} cwd
- * @param {string} sessionId - quick-<uuid8>
- * @returns {{ specBase: string, guard: object } | null}
- */
-export function locateQuickSessionGuard(cwd, sessionId) {
-  if (!sessionId) return null
-  for (const specBase of ancestorSpecDirs(cwd)) {
-    const guardFile = join(specBase, '.runtime', 'quick-sessions', sessionId, 'guard.json')
-    if (existsSync(guardFile)) {
-      try {
-        const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
-        return { specBase, guard }
-      } catch {
-        // guard.json 损坏：当作不存在，继续找下一个（不阻断主流程）
-      }
-    }
-  }
-  return null
-}
-
-/**
- * 检测 quick 会话是否跨 specDir 漂移（坑 quick-cwd-drift-splits-specdir）。
- *
- * quick 被 validateChangeExists 的 sessionId 豁免（quick-<8hex> 不在 changes/ 下），故 quick
- * 漂移除 countAncestorSpecDirs 的 warn 外无硬守卫 → 无声分裂（progress/artifact/QUICKLOG 落
- * 子项目、根 session 停滞）。本函数补这个口：
- *   - 当前 specBase 已有本 session guard → null（同一 specDir，无漂移）
- *   - 当前 specBase 没有，但祖先链别处有同 sessionId guard → 判漂移，返回引导信息供调用方 fail-fast
- *   - 别处也没有 → null（真·新会话首次启动，guard 尚未建，放行 —— 不误伤子项目主动启新 quick）
- *
- * 风格仿 validateChangeExists：null = 通过，对象 = 失败（含 message）。
- *
- * @param {string} cwd
- * @param {string} currentSpecBase - 当前命中的 specBase
- * @param {string} sessionId - quick-<uuid8>
- * @returns {{ realSpecBase: string, message: string } | null}
- */
-export function detectQuickSessionDrift(cwd, currentSpecBase, sessionId) {
-  if (!sessionId || !currentSpecBase) return null
-  // 当前 specBase 已有本 session guard → 同一 specDir，无漂移
-  const currentGuard = join(currentSpecBase, '.runtime', 'quick-sessions', sessionId, 'guard.json')
-  if (existsSync(currentGuard)) return null
-  // 当前没有 → 看祖先链别处有没有同 sessionId 的 guard
-  const located = locateQuickSessionGuard(cwd, sessionId)
-  if (!located) return null // 别处也没有 = 真·新会话首次启动，放行
-  return {
-    realSpecBase: located.specBase,
-    message: `quick 会话 "${sessionId}" 创建于 ${located.specBase}，当前 cwd 解析到 ${currentSpecBase}（跨 specDir 漂移）。` +
-      `继续会把 progress/artifact/QUICKLOG 写到错误的 spec，与原会话分裂。` +
-      `排查：① cd 回 ${dirname(located.specBase)}（原 spec 所属项目根）再跑；② 或显式 --spec-dir ${located.specBase} 指定原 spec。`,
-  }
-}
-
-/**
- * 检测 specBase 是否命中 worktree 内 checkout 出来的 .sillyspec 副本（坑 worktree-execute-spec-drift）。
- *
- * worktree 根 = <mainRepo>/.sillyspec/.runtime/worktrees/<changeName>/（worktree.js WORKTREES_REL）。
- * worktree 是主仓完整 checkout,若 .sillyspec/changes/ 被跟踪 → 副本里 change 目录真实存在,
- * validateChangeExists 被骗放行 → 进度/产出写进副本,与主仓 .sillyspec 分裂(副本随工作树清理丢失)。
- *
- * 判据:specBase 路径含 `.sillyspec/.runtime/worktrees/<seg>/.sillyspec`。主仓 specBase=<mainRepo>/.sillyspec
- * 无此段 → null,零误伤。返回 null=通过;对象=漂移(含 mainSpecBase/changeName/message),风格仿
- * validateChangeExists。覆盖 plan/execute/verify/archive(同 Set)——都要求 change 已存在、都会被副本骗过。
- * 平台模式/--spec-dir 已明确指定,由调用方跳过。
- */
-export function detectWorktreeSpecDrift(specBase) {
-  if (!specBase) return null
-  const seg = resolve(specBase).split(sep)
-  // specBase 恒以 .sillyspec 结尾(command.js specBase=join(cwd,'.sillyspec'))。worktree 副本形如
-  // <mainRepo>/.sillyspec/.runtime/worktrees/<change>/.sillyspec —— 尾段也须是 .sillyspec,
-  // 否则 worktree 根目录本身(<.../worktrees/<change>)会被误判(它不是 spec,不会作 specBase 传入)。
-  if (seg[seg.length - 1] !== '.sillyspec') return null
-  for (let i = 0; i + 3 < seg.length; i++) {
-    if (seg[i] === '.sillyspec' && seg[i + 1] === '.runtime' && seg[i + 2] === 'worktrees') {
-      const changeName = seg[i + 3]
-      const mainSpec = seg.slice(0, i + 1).join(sep) // <mainRepo>/.sillyspec
-      return {
-        changeName,
-        mainSpecBase: mainSpec,
-        message: `当前 spec 命中 worktree 副本(${specBase})——这是 ${changeName} 隔离工作树内 checkout 出来的 .sillyspec,不是主仓 spec。\n` +
-          `   在此跑 plan/execute/verify/archive 会把进度与产出写到副本,与主仓 .sillyspec 分裂(副本随工作树清理而丢失)。\n` +
-          `   排查:① cd 回 ${dirname(mainSpec)}(主仓根)再跑;② 或 --spec-dir ${mainSpec} 显式指定主仓 spec。`,
-      }
-    }
-  }
-  return null
-}
-
-/**
- * 统一查找变更目录（与 progress.js 的变更检测逻辑一致）。
- */
-export function resolveChangeDir(cwd, progress, specDir = null) {
-  const changesDir = join(specDir || resolveSpecDir(cwd), 'changes')
-  if (!existsSync(changesDir)) return null
-
-  // 1. 优先用 currentChange
-  if (progress.currentChange) {
-    const target = join(changesDir, progress.currentChange)
-    if (existsSync(target)) return target
-  }
-
-  // 2. fallback：唯一非 archive 目录
-  const entries = readdirSync(changesDir, { withFileTypes: true })
-    .filter(e => e.isDirectory() && e.name !== 'archive')
-  if (entries.length === 1) return join(changesDir, entries[0].name)
-
-  return null
-}
-
-/**
- * 触发 sync（平台模式走自己的链路，跳过；否则 await import sync.js）。
- */
-// sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
-// fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
-// 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
-const SYNC_TOTAL_TIMEOUT_MS = 8_000
-
-export async function triggerSync(cwd, changeName, platformOpts = {}) {
-  // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
-  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
-  try {
-    if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) return
-    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
-    const syncMod = await import('../sync.js')
-    let timer
-    try {
-      await Promise.race([
-        syncMod.sync(changeName, cwd),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
-    }
-  } catch (e) {
-    // sync.js 不存在或同步失败，静默跳过
-    console.warn('⚠️ 同步失败:', e.message)
-  }
-}
-
-/**
- * 审批检查：execute 阶段启动前检查（W6 Step8a 从 run.js 搬入，runStage + runAutoMode 共用）。
- * 平台模式走自己的链路，跳过；否则 await import sync.js。
- * @returns {{ status: string, reason?: string } | null}
- */
-export async function checkApproval(cwd, changeName, platformOpts = {}) {
-  // 平台模式不需要 CLI 内置审批检查
-  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return null
-  try {
-    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
-    const syncMod = await import('../sync.js')
-    return await syncMod.checkApproval(changeName, cwd)
-  } catch (e) {
-    return null
-  }
-}
-
-/**
- * 安全执行 git：-c safe.directory per-command（不污染全局 config）+ -C cwd。
- * @returns {{ value: string|null, error: string|null }}
- */
-export function safeGit(cwd, args) {
-  const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
-  try {
-    const value = execSync(['git', ...fullArgs].join(' '), { encoding: 'utf8', timeout: 5000 }).trim()
-    return { value, error: null }
-  } catch (e) {
-    return { value: null, error: e.message.split('\n')[0] }
-  }
-}
-
-/**
- * 解析 git status --porcelain 单行 → 文件路径（去引号/处理 rename/归一化）。
- * 注意：line.slice(3) —— porcelain 行前 2 字符是状态码 + 1 空格，路径从 index 3 开始。
- */
-export function parsePorcelainPath(line) {
-  if (!line) return ''
-  let path = line.slice(3).trim()
-  if (path.length >= 2 && path.startsWith('"') && path.endsWith('"')) {
-    path = path.slice(1, -1).replace(/\\(.)/g, (_, c) => c)
-  }
-  const arrow = path.indexOf(' -> ')
-  if (arrow !== -1) path = path.slice(arrow + 4)
-  return path.replace(/\\/g, '/')
-}
-
-/**
- * quick 自身写入的 .sillyspec/ 元数据判定（auditQuickCompletion 审计 与 QUICKLOG「文件：」行回填
- * 单源）。回填文件行时复用：review.changedFiles 含这些元数据时过滤掉，只留真实业务文件。
- *
- * 归类口径：
- * - quicklog/.runtime/modules/_module-map/knowledge-uncategorized 等 quick 自身产物 → 元数据
- * - .sillyspec/changes/：quick 自己没有该目录，其下文件要么是关联变更（reverse-sync），
- *   要么是并发他者会话的工作。非关联变更目录整体视为元数据放行；关联变更文件不算（属本 quick 真实改动）
- *
- * 「并发工作 vs 偷建变更」的意图软判定留给 sillyhub，确定性校验只做路径归类。
- *
- * @param {string} p 文件路径（容错 \\ / 混用）
- * @param {string[]} [linkedChanges] 关联变更名列表（影响 changes/ 归类）
- * @returns {boolean} true=quick 元数据，应从业务文件列表过滤掉
- */
-export function isQuickMetadata(p, linkedChanges = []) {
-  const normalizeGitPath = (x) => String(x).replace(/\\/g, '/')
-  const file = normalizeGitPath(p)
-  if (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))) return true
-  if (file.startsWith('.sillyspec/changes/')) {
-    const linkedChangeNames = new Set((Array.isArray(linkedChanges) ? linkedChanges : []).map(c => normalizeGitPath(c)))
-    const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
-    // bare 折叠 token（git 把全新未跟踪 changes/ 折叠成 `changes/`）或具体但非关联的变更 → 放行
-    if (!m || !linkedChangeNames.has(m[1])) return true
-  }
-  return false
-}
-
-/**
- * quick 完成审计：对比 baseline 与实际变更。
- * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number }}
- */
-export async function auditQuickCompletion(cwd, guard, options = {}) {
-  const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false } = guard
-  const { isConfirm } = options
-  // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
-  // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
-  // 避免叠加 quick 会话时把前序会话未提交文件误读为「本会话只动了 N 个」。
-  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0 }
-
-  try {
-    const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-    // 不对整段 .trim()：会削首行前导空格致首文件路径丢首字符（见 parsePorcelainPath 注释）。
-    const currentEntries = gitStatus.split('\n').filter(Boolean)
-
-    const normalizeGitPath = (p) => p.replace(/\\/g, '/')
-    // step1 启动时记录的全量脏文件 = 预存改动（非本次 quick 产生）。审计必须排除它们，
-    // 否则脏工作区下预存文件持续留在 git status → 命中 baselineFiles → 误判「覆盖 baseline」
-    // → 永远 blocked（--force-baseline 也救不回来，因为 status 判定看 baselineHit 数组）。
-    // 前缀匹配：baseline 录入时未跟踪目录会被 git 折叠成 `dir/`（带尾斜杠）token，审计时若该
-    // 目录下文件被跟踪则展开成文件级 `dir/file`——精确匹配对不上，故尾斜杠 token 按目录前缀放行。
-    const normBaseline = (baselineFiles || []).map(f => normalizeGitPath(f))
-    const baselineExact = new Set(normBaseline.filter(f => !f.endsWith('/')))
-    const baselineDirs = normBaseline.filter(f => f.endsWith('/'))
-    const isBaselineFile = (p) => {
-      const f = normalizeGitPath(p)
-      return baselineExact.has(f) || baselineDirs.some(d => f.startsWith(d))
-    }
-    const DANGEROUS_PATTERNS = [
-      '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 = parsePorcelainPath(entry)   // 已去引号/处理 rename/归一化，修正首行丢首字符
-      if (!file) continue
-
-      // 累计暂存计数：所有非 quick 元数据的未提交条目（含下方将被 baseline 跳过的前序残留）。
-      // 放在 isBaselineFile 跳过之前，确保 baseline 内文件也计入「累计暂存」。
-      if (!isQuickMetadata(file, guard.linkedChanges)) result.stagedTotal++
-
-      // 预存脏文件：step1 baseline 已记录，非本次 quick 产生，跳过审计（含折叠目录前缀匹配）
-      if (isBaselineFile(file)) 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 (file.startsWith('.sillyspec/') && !isQuickMetadata(file, guard.linkedChanges) && !forceBaseline) {
-        result.reasons.push(`危险文件变更: ${file}`)
-      }
-
-      if (DANGEROUS_PATTERNS.some(p => file === p || file.startsWith(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 (!isQuickMetadata(f, guard.linkedChanges)) {
-          result.reasons.push(`新增文件（需 --allow-new）: ${f}`)
-        }
-      }
-    }
-
-    // 检查 allowedFiles 范围
-    if (allowedFiles.length > 0) {
-      for (const f of result.changedFiles) {
-        if (!allowedFiles.includes(f) && !isQuickMetadata(f, guard.linkedChanges)) {
-          result.reasons.push(`超出 allowedFiles: ${f}`)
-        }
-      }
-    }
-
-    // 判定结果（force-baseline 降级 baselineHit → 非 blocked；allow-new 降级新增文件 → 非 warning。
-    // reasons 文案本就受这两个 flag 控制，但原判定直接看数组长度，致 flag 对 status 失效。）
-    if ((!forceBaseline && result.baselineHit.length > 0) || result.deletedFiles.length > 0 || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
-      result.status = 'blocked'
-    } else if ((!allowNew && result.newFiles.length > 0) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
-      result.status = 'warning'
-    }
-
-    // quicklog 存在性检查
-    try {
-      const quicklogDir = join(cwd, '.sillyspec', 'quicklog')
-      if (existsSync(quicklogDir)) {
-        const qlFiles = readdirSync(quicklogDir).filter(f => f.endsWith('.md'))
-        if (qlFiles.length === 0) {
-          result.reasons.push('quicklog 目录为空（无任务记录）')
-          if (result.status === 'safe') result.status = 'warning'
-        }
-      } else {
-        result.reasons.push('quicklog 目录不存在（agent 未创建任务记录）')
-        if (result.status === 'safe') result.status = 'warning'
-      }
-    } catch {}
-
-    // --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   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
-      console.log(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
-      console.log(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
-      console.log(`   或在首个 sillyspec run quick 启动（step 1）时就声明这些 flag，持久化进 guard。`)
-    }
-  } catch (e) {
-    result.reasons.push(`审计失败: ${e.message}`)
-    result.status = 'warning'
-  }
-
-  return result
-}
-
-// ── Step 处理辅助（W6 Step7a 从 run.js 搬入：getStageSteps/formatWaitOptions 被 run.js + complete.js 共用）──
-/**
- * 格式化 waitOptions 为人类可读字符串
- */
-export function formatWaitOptions(raw) {
-  if (!raw) return null
-  try {
-    const parsed = JSON.parse(raw)
-    if (Array.isArray(parsed)) return parsed.join(', ')
-    return raw
-  } catch {
-    return raw
-  }
-}
-
-
-/**
- * 获取阶段的步骤定义（execute 需要动态构建）
- */
-export async function getStageSteps(stageName, cwd, progress, specDir = null) {
-  if (stageName === 'execute') {
-    const changeDir = resolveChangeDir(cwd, progress, specDir)
-    let planFile = null
-    let worktreePath = null
-    if (changeDir) {
-      const p = join(changeDir, 'plan.md')
-      if (existsSync(p)) planFile = p
-      // 自动检测 worktree 路径，注入 Wave prompt 的 workdir 指令
-      // 修复：之前未传 worktreePath 给 buildExecuteSteps，导致 Wave prompt 缺失工作目录指令，
-      // 子代理可能把文件写到主工作区而非 worktree 内，破坏隔离。
-      try {
-        const changeName = basename(changeDir)
-        const { WorktreeManager } = await import('../worktree.js')
-        const wm = new WorktreeManager({ cwd })
-        const meta = wm.getMeta(changeName)
-        if (meta?.worktreePath && existsSync(meta.worktreePath)) {
-          worktreePath = meta.worktreePath
-        }
-      } catch {
-        // 无 worktree meta 不阻断——可能是首次启动或 in-place 模式
-      }
-    }
-    return buildExecuteSteps(planFile, { worktreePath })
-  }
-  if (stageName === 'plan') {
-    const changeDir = resolveChangeDir(cwd, progress, specDir)
-    return buildPlanSteps(changeDir)
-  }
-  const def = stageRegistry[stageName]
-  return def ? def.steps : null
-}
-
+/**
+ * run.js 共享纯工具（W6 Step1 从 run.js 抽出）。
+ *
+ * 安全锚：run.js 始终是 barrel。这些函数搬至此模块后，run.js import 回来；
+ * parsePorcelainPath + auditQuickCompletion 被 test 直接 import，run.js 必须 re-export。
+ *
+ * 路径修正（相对 src/run/）：
+ *   - resolvePromptIncludes 的 templates/prompts 在仓库根 → __dirname 上两层
+ *   - triggerSync 的动态 import './sync.js' → '../sync.js'（src/sync.js）
+ *   - safeGit 已收口到 src/git-helper.js（单一公共 git 调用入口，数组形式不经 shell），
+ *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
+ */
+import { basename, join, resolve, dirname, sep } from 'node:path'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// safeGit 收口至 src/git-helper.js：import 建本地词法绑定（本模块内部 L128/130/431 调用）+
+// re-export 供 run/ 层现有调用方继续从 shared.js 引用（pure re-export 不建本地绑定，会致内部 ReferenceError）。
+import { safeGit } from '../git-helper.js'
+export { safeGit }
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ── Wait State Constants ──（W6 Step3 从 run.js 搬入：prompt.js outputStep 与 run.js wait-detection 共用）
+// 正则匹配：只识别独立一行的标记，避免误伤文档正文引用
+export const WAIT_MARKER_RE = /^\s*\[(WAIT_FOR_USER|NEEDS_CONFIRM|NEEDS_DECISION)\]\s*$/m
+
+// ── did-you-mean（命令级 + flag 级 typo 建议，零依赖）──
+// 历史：agent 打错命令名/flag 名只报「未知」+整屏列表，要自己捞正确拼写。
+export function levenshtein(a, b) {
+  const m = String(a).length, n = String(b).length
+  if (!m) return n; if (!n) return m
+  let prev = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    const cur = [i]
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = cur
+  }
+  return prev[n]
+}
+export function didYouMean(input, candidates) {
+  if (!input) return null
+  let best = null, bestD = Infinity
+  for (const c of candidates) {
+    const d = levenshtein(String(input).toLowerCase(), String(c).toLowerCase())
+    if (d < bestD) { bestD = d; best = c }
+  }
+  return (best !== null && bestD <= Math.max(1, Math.floor(String(input).length / 2))) ? best : null
+}
+
+// ── 变更名路径穿越消毒（F6）──
+// change 名会被 join 进 .sillyspec/changes/<name>/ 当目录用。若含 ../ 或路径分隔符，
+// 会逃出 changes/ 写到任意位置（如 --change ../../etc/x 把 proposal.md 写到 changes 同级之外）。
+// 在 --change 解析边界统一消毒，比在每个 join 点守卫更集中。合法名：字母/数字/._-，禁分隔符与 ..
+export function assertSafeChangeName(name, label = '变更名') {
+  if (name == null) return
+  const s = String(name)
+  if (s === '') throw new Error(`${label}不能为空`)
+  // 含路径分隔符 或 父目录穿越段 → 拒绝（Windows 下 \\ 也算）
+  if (/[\\/]/.test(s) || /(^|[/\\])\.\.(?=$|[/\\])/.test(s) || s === '..' || s.includes('..')) {
+    throw new Error(`${label}「${s}」含路径分隔符或 ..，禁止路径穿越（变更名只能是 .sillyspec/changes/ 下的一个目录名，不能逃出）`)
+  }
+  if (!/^[\w.\-]+$/.test(s)) {
+    throw new Error(`${label}「${s}」含非法字符（仅允许字母、数字、._-）`)
+  }
+}
+
+import { buildExecuteSteps } from '../stages/execute.js'
+import { buildPlanSteps } from '../stages/plan.js'
+import { stageRegistry } from '../stages/index.js'
+
+/**
+ * 解析 prompt 中的 {{include: <name>}} 占位符：读包内 templates/prompts/<name>.md 注入。
+ * 把 stage step prompt 里 self-contained 的大块抽到外部模板，CLI 端组装时注入——
+ * agent 收到的仍是自包含 prompt 字符串，无需自己 Read。单次替换（不递归）；
+ * 模板缺失则保留占位符并 warn，便于发现配置错误。
+ */
+export function resolvePromptIncludes(text) {
+  return text.replace(/\{\{include:\s*([\w.-]+)\s*\}\}/g, (match, name) => {
+    // shared.js 在 src/run/，templates/prompts 在仓库根 → 上两层
+    const tplPath = join(__dirname, '..', '..', 'templates', 'prompts', `${name}.md`)
+    if (!existsSync(tplPath)) {
+      console.warn(`⚠️ prompt include 模板缺失: ${name} (期望: ${tplPath})`)
+      return match
+    }
+    return readFileSync(tplPath, 'utf8')
+  })
+}
+
+/**
+ * 找 .sillyspec 祖先目录：用户指定 specDir 优先，否则从 cwd 向上找。
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string} [opts.specDir] - 用户指定的 specDir（通过 --spec-dir 或 --spec-root）
+ * @returns {string} 规范目录的绝对路径
+ */
+export function resolveSpecDir(cwd, opts = {}) {
+  if (opts.specDir) return resolve(opts.specDir)
+  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')
+}
+
+/**
+ * 枚举 cwd 祖先链（含自身）上所有 .sillyspec 目录的绝对路径，上界 = git root。
+ *
+ * 返回顺序：从 cwd 最近开始向上到 git root（含两端命中项）。单实例项目任意子目录恒返回 [自身]。
+ *
+ * 上界 = git root（monorepo 天然边界）。必须有限上界：一路数到文件系统根会撞 home 等
+ * 无关祖先的孤立 .sillyspec（home 下任何项目都被误报多实例）。非 git 仓库：不向上数，
+ * 只看 cwd 自身（≤1，永不误报）。
+ *
+ * 被 countAncestorSpecDirs（漂移提醒 warn）与 locateQuickSessionGuard（quick 漂移 fail-fast
+ * 守卫，坑 quick-cwd-drift-splits-specdir）共用 —— 单一真相源，避免两处各自重写祖先枚举漂移。
+ */
+export function ancestorSpecDirs(cwd) {
+  const resolved = resolve(cwd)
+  // 上界 = git root。但 linked worktree 内 --show-toplevel 返回 worktree 根(非主仓根),
+  // 祖先链到不了主仓 .sillyspec → 漂移提醒/quick 守卫全哑(坑 worktree-execute-spec-drift)。
+  // 复刻 worktree.js _resolveMainRepoRoot:--git-common-dir 的 dirname 才是主仓根,取更靠上者作 ceiling。
+  // (git 可能返回相对路径,须 resolve(cwd, commonDir) 绝对化,否则相对 process.cwd 误解析。)
+  const topLevel = safeGit(resolved, ['rev-parse', '--show-toplevel']).value
+  let ceiling = topLevel ? resolve(topLevel) : null
+  const commonDir = safeGit(resolved, ['rev-parse', '--git-common-dir']).value
+  if (commonDir) {
+    const absCommonDir = resolve(resolved, commonDir)
+    if (existsSync(absCommonDir) && statSync(absCommonDir).isDirectory()) {
+      const mainRoot = dirname(absCommonDir)
+      // 主仓根是 worktree 根的祖先时取它(更靠上);monorepo/单仓两者相等不替换,行为不变
+      if (!ceiling || resolve(ceiling).startsWith(resolve(mainRoot) + sep)) ceiling = mainRoot
+    }
+  }
+  const dirs = []
+  let dir = resolved
+  while (true) {
+    if (existsSync(join(dir, '.sillyspec'))) dirs.push(join(dir, '.sillyspec'))
+    if (!ceiling || resolve(dir) === resolve(ceiling)) break
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return dirs
+}
+
+/**
+ * 统计 cwd 祖先链上有多少个 .sillyspec 目录（= ancestorSpecDirs(cwd).length）。
+ *
+ * ≥2 个 = monorepo 多实例（子项目独立 .sillyspec + 根 .sillyspec 并存），resolveSpecDir 命中的
+ * 「最近」实例未必是用户意图的项目（如 cd 进被独立 scan 的子项目跑测试后忘回根）→ 漂移风险。
+ * 单实例项目在任意子目录工作恒返回 1，不误报。
+ */
+export function countAncestorSpecDirs(cwd) {
+  return ancestorSpecDirs(cwd).length
+}
+
+/**
+ * 在 cwd 祖先链的各 specBase 中查找 quick 会话 guard.json（坑 quick-cwd-drift-splits-specdir）。
+ *
+ * sessionId（quick-<uuid8>）全局唯一，但 guard.json 按 specBase 分散落盘
+ * （<specBase>/.runtime/quick-sessions/<sessionId>/guard.json）。cd 漂移到子项目后，当前 specBase
+ * 下读不到本 session 的 guard，但祖先链别处的 specBase（创建 session 的根）仍有它 → 据此定位
+ * session 真正归属，供 detectQuickSessionDrift 的 fail-fast 守卫判断。
+ *
+ * 遍历顺序 = ancestorSpecDirs（cwd 最近 → git root），返回第一个命中。
+ *
+ * @param {string} cwd
+ * @param {string} sessionId - quick-<uuid8>
+ * @returns {{ specBase: string, guard: object } | null}
+ */
+export function locateQuickSessionGuard(cwd, sessionId) {
+  if (!sessionId) return null
+  for (const specBase of ancestorSpecDirs(cwd)) {
+    const guardFile = join(specBase, '.runtime', 'quick-sessions', sessionId, 'guard.json')
+    if (existsSync(guardFile)) {
+      try {
+        const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
+        return { specBase, guard }
+      } catch {
+        // guard.json 损坏：当作不存在，继续找下一个（不阻断主流程）
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 检测 quick 会话是否跨 specDir 漂移（坑 quick-cwd-drift-splits-specdir）。
+ *
+ * quick 被 validateChangeExists 的 sessionId 豁免（quick-<8hex> 不在 changes/ 下），故 quick
+ * 漂移除 countAncestorSpecDirs 的 warn 外无硬守卫 → 无声分裂（progress/artifact/QUICKLOG 落
+ * 子项目、根 session 停滞）。本函数补这个口：
+ *   - 当前 specBase 已有本 session guard → null（同一 specDir，无漂移）
+ *   - 当前 specBase 没有，但祖先链别处有同 sessionId guard → 判漂移，返回引导信息供调用方 fail-fast
+ *   - 别处也没有 → null（真·新会话首次启动，guard 尚未建，放行 —— 不误伤子项目主动启新 quick）
+ *
+ * 风格仿 validateChangeExists：null = 通过，对象 = 失败（含 message）。
+ *
+ * @param {string} cwd
+ * @param {string} currentSpecBase - 当前命中的 specBase
+ * @param {string} sessionId - quick-<uuid8>
+ * @returns {{ realSpecBase: string, message: string } | null}
+ */
+export function detectQuickSessionDrift(cwd, currentSpecBase, sessionId) {
+  if (!sessionId || !currentSpecBase) return null
+  // 当前 specBase 已有本 session guard → 同一 specDir，无漂移
+  const currentGuard = join(currentSpecBase, '.runtime', 'quick-sessions', sessionId, 'guard.json')
+  if (existsSync(currentGuard)) return null
+  // 当前没有 → 看祖先链别处有没有同 sessionId 的 guard
+  const located = locateQuickSessionGuard(cwd, sessionId)
+  if (!located) return null // 别处也没有 = 真·新会话首次启动，放行
+  return {
+    realSpecBase: located.specBase,
+    message: `quick 会话 "${sessionId}" 创建于 ${located.specBase}，当前 cwd 解析到 ${currentSpecBase}（跨 specDir 漂移）。` +
+      `继续会把 progress/artifact/QUICKLOG 写到错误的 spec，与原会话分裂。` +
+      `排查：① cd 回 ${dirname(located.specBase)}（原 spec 所属项目根）再跑；② 或显式 --spec-dir ${located.specBase} 指定原 spec。`,
+  }
+}
+
+/**
+ * 检测 specBase 是否命中 worktree 内 checkout 出来的 .sillyspec 副本（坑 worktree-execute-spec-drift）。
+ *
+ * worktree 根 = <mainRepo>/.sillyspec/.runtime/worktrees/<changeName>/（worktree.js WORKTREES_REL）。
+ * worktree 是主仓完整 checkout,若 .sillyspec/changes/ 被跟踪 → 副本里 change 目录真实存在,
+ * validateChangeExists 被骗放行 → 进度/产出写进副本,与主仓 .sillyspec 分裂(副本随工作树清理丢失)。
+ *
+ * 判据:specBase 路径含 `.sillyspec/.runtime/worktrees/<seg>/.sillyspec`。主仓 specBase=<mainRepo>/.sillyspec
+ * 无此段 → null,零误伤。返回 null=通过;对象=漂移(含 mainSpecBase/changeName/message),风格仿
+ * validateChangeExists。覆盖 plan/execute/verify/archive(同 Set)——都要求 change 已存在、都会被副本骗过。
+ * 平台模式/--spec-dir 已明确指定,由调用方跳过。
+ */
+export function detectWorktreeSpecDrift(specBase) {
+  if (!specBase) return null
+  const seg = resolve(specBase).split(sep)
+  // specBase 恒以 .sillyspec 结尾(command.js specBase=join(cwd,'.sillyspec'))。worktree 副本形如
+  // <mainRepo>/.sillyspec/.runtime/worktrees/<change>/.sillyspec —— 尾段也须是 .sillyspec,
+  // 否则 worktree 根目录本身(<.../worktrees/<change>)会被误判(它不是 spec,不会作 specBase 传入)。
+  if (seg[seg.length - 1] !== '.sillyspec') return null
+  for (let i = 0; i + 3 < seg.length; i++) {
+    if (seg[i] === '.sillyspec' && seg[i + 1] === '.runtime' && seg[i + 2] === 'worktrees') {
+      const changeName = seg[i + 3]
+      const mainSpec = seg.slice(0, i + 1).join(sep) // <mainRepo>/.sillyspec
+      return {
+        changeName,
+        mainSpecBase: mainSpec,
+        message: `当前 spec 命中 worktree 副本(${specBase})——这是 ${changeName} 隔离工作树内 checkout 出来的 .sillyspec,不是主仓 spec。\n` +
+          `   在此跑 plan/execute/verify/archive 会把进度与产出写到副本,与主仓 .sillyspec 分裂(副本随工作树清理而丢失)。\n` +
+          `   排查:① cd 回 ${dirname(mainSpec)}(主仓根)再跑;② 或 --spec-dir ${mainSpec} 显式指定主仓 spec。`,
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 统一解析 .runtime 根目录（坑 execute-runs-isolation）。
+ *
+ * 优先级：平台模式 runtimeRoot > drift 锚点 specDriftAnchor > 本地 specBase/.runtime。
+ * specDriftAnchor 仅在此处消费，不参与平台 sentinel（specRoot||runtimeRoot）判定，
+ * 避免误跳 triggerSync（:286）/ checkApproval（:313）/ 平台渲染分支（D-02）。
+ *
+ * 历史：drift 守卫（command.js）命中时只重写本地 specBase/specRoot/specDir/pm（progress 落主仓），
+ * 但漏设 platformOpts 字段——下游 15 处 runtimeRoot 解析从 cwd（仍 worktree）重算 → execute-runs /
+ * stage-reviews 落 worktree，被 cleanup 整目录删。本函数 + specDriftAnchor 锚点堵此源头。
+ *
+ * @param {object} [platformOpts] - { runtimeRoot?, specDriftAnchor?, ... }（可 null/undefined）
+ * @param {string} localSpecBase - 本地 specBase（cwd/.sillyspec），兜底落点
+ * @returns {string} .runtime 根目录绝对路径
+ */
+export function resolveRuntimeRoot(platformOpts, localSpecBase) {
+  if (platformOpts?.runtimeRoot) return platformOpts.runtimeRoot
+  if (platformOpts?.specDriftAnchor) return join(platformOpts.specDriftAnchor, '.runtime')
+  return join(localSpecBase, '.runtime')
+}
+
+/**
+ * quick 会话目录（.runtime/quick-sessions）的单一解析入口（multi-agent-review Q4）。
+ *
+ * 历史 bug：stage.js 写 guard 用 `specBase/.runtime/quick-sessions/`，收尾 handleQuickStageCompletion
+ * 读/清理用 `resolveRuntimeRoot`（runtimeRoot 被设时返回 runtimeRoot）。两者在平台模式（runtimeRoot 与
+ * specBase/.runtime 不同）下分裂——guard 写到 specBase/.runtime、收尾从 runtimeRoot 读不到 → guard=null
+ * brownfield 分支整体跳过边界审计 + 兜底重分配 qlId + session 目录清错位置。
+ *
+ * 收敛到此函数后，写/读/清理三处共用同一解析（基于 resolveRuntimeRoot），任何平台/漂移模式都对齐。
+ *
+ * @param {object} [platformOpts] - { runtimeRoot?, specDriftAnchor?, ... }（可 null/undefined）
+ * @param {string} localSpecBase - 本地 specBase（cwd/.sillyspec），兜底落点
+ * @returns {string} quick-sessions 目录绝对路径
+ */
+export function resolveQuickSessionsDir(platformOpts, localSpecBase) {
+  return join(resolveRuntimeRoot(platformOpts, localSpecBase), 'quick-sessions')
+}
+
+/**
+ * 统一查找变更目录（与 progress.js 的变更检测逻辑一致）。
+ */
+export function resolveChangeDir(cwd, progress, specDir = null) {
+  const changesDir = join(specDir || resolveSpecDir(cwd), 'changes')
+  if (!existsSync(changesDir)) return null
+
+  // 1. 优先用 currentChange
+  if (progress.currentChange) {
+    const target = join(changesDir, progress.currentChange)
+    if (existsSync(target)) return target
+  }
+
+  // 2. fallback：唯一非 archive 目录
+  const entries = readdirSync(changesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name !== 'archive')
+  if (entries.length === 1) return join(changesDir, entries[0].name)
+
+  return null
+}
+
+/**
+ * 触发 sync（平台模式走自己的链路，跳过；否则 await import sync.js）。
+ */
+// sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
+// fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
+// 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
+const SYNC_TOTAL_TIMEOUT_MS = 8_000
+
+export async function triggerSync(cwd, changeName, platformOpts = {}) {
+  // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
+  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
+  try {
+    if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) return
+    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
+    const syncMod = await import('../sync.js')
+    let timer
+    try {
+      await Promise.race([
+        syncMod.sync(changeName, cwd),
+        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
+      ])
+    } finally {
+      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
+    }
+  } catch (e) {
+    // sync.js 不存在或同步失败，静默跳过
+    console.warn('⚠️ 同步失败:', e.message)
+  }
+}
+
+/**
+ * 审批检查：execute 阶段启动前检查（W6 Step8a 从 run.js 搬入，runStage + runAutoMode 共用）。
+ * 平台模式走自己的链路，跳过；否则 await import sync.js。
+ * @returns {{ status: string, reason?: string } | null}
+ */
+export async function checkApproval(cwd, changeName, platformOpts = {}) {
+  // 平台模式不需要 CLI 内置审批检查
+  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return null
+  try {
+    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
+    const syncMod = await import('../sync.js')
+    return await syncMod.checkApproval(changeName, cwd)
+  } catch (e) {
+    return null
+  }
+}
+
+/**
+ * 解析 git status --porcelain 单行 → 文件路径（去引号/处理 rename/归一化）。
+ * 注意：line.slice(3) —— porcelain 行前 2 字符是状态码 + 1 空格，路径从 index 3 开始。
+ */
+export function parsePorcelainPath(line) {
+  if (!line) return ''
+  let path = line.slice(3).trim()
+  if (path.length >= 2 && path.startsWith('"') && path.endsWith('"')) {
+    path = path.slice(1, -1).replace(/\\(.)/g, (_, c) => c)
+  }
+  const arrow = path.indexOf(' -> ')
+  if (arrow !== -1) path = path.slice(arrow + 4)
+  return path.replace(/\\/g, '/')
+}
+
+/**
+ * quick 自身写入的 .sillyspec/ 元数据判定（auditQuickCompletion 审计 与 QUICKLOG「文件：」行回填
+ * 单源）。回填文件行时复用：review.changedFiles 含这些元数据时过滤掉，只留真实业务文件。
+ *
+ * 归类口径：
+ * - quicklog/.runtime/modules/_module-map/knowledge-uncategorized 等 quick 自身产物 → 元数据
+ * - .sillyspec/changes/：quick 自己没有该目录，其下文件要么是关联变更（reverse-sync），
+ *   要么是并发他者会话的工作。非关联变更目录整体视为元数据放行；关联变更文件不算（属本 quick 真实改动）
+ *
+ * 「并发工作 vs 偷建变更」的意图软判定留给 sillyhub，确定性校验只做路径归类。
+ *
+ * @param {string} p 文件路径（容错 \\ / 混用）
+ * @param {string[]} [linkedChanges] 关联变更名列表（影响 changes/ 归类）
+ * @returns {boolean} true=quick 元数据，应从业务文件列表过滤掉
+ */
+export function isQuickMetadata(p, linkedChanges = []) {
+  const normalizeGitPath = (x) => String(x).replace(/\\/g, '/')
+  const file = normalizeGitPath(p)
+  if (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))) return true
+  if (file.startsWith('.sillyspec/changes/')) {
+    const linkedChangeNames = new Set((Array.isArray(linkedChanges) ? linkedChanges : []).map(c => normalizeGitPath(c)))
+    const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
+    // bare 折叠 token（git 把全新未跟踪 changes/ 折叠成 `changes/`）或具体但非关联的变更 → 放行
+    if (!m || !linkedChangeNames.has(m[1])) return true
+  }
+  return false
+}
+
+/**
+ * quick 完成审计：对比 baseline 与实际变更。
+ * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number }}
+ */
+export async function auditQuickCompletion(cwd, guard, options = {}) {
+  const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false } = guard
+  const { isConfirm } = options
+  // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
+  // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
+  // 避免叠加 quick 会话时把前序会话未提交文件误读为「本会话只动了 N 个」。
+  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0 }
+
+  try {
+    // safeGit 带 -c safe.directory，避免 linked worktree/容器异 uid/挂载点下裸 `git status` 抛错被
+    // 外层 catch 吞成 warning（multi-agent-review Q3）。safeGit 返回 {value,error} 不抛；若仍有 error
+    // 说明真读不到 git 状态，保守阻断（审计无锚点不能放行），不静默降级。
+    // trim:false 必传：porcelain 首行前导空格是状态码一部分，trim 会削掉致 parsePorcelainPath 丢首字符。
+    const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+    if (statusResult.error) {
+      result.reasons.push(`审计失败（git status）: ${statusResult.error}`)
+      result.status = 'blocked'
+      return result
+    }
+    const gitStatus = statusResult.value || ''
+    // 不对整段 .trim()：会削首行前导空格致首文件路径丢首字符（见 parsePorcelainPath 注释）。
+    const currentEntries = gitStatus.split('\n').filter(Boolean)
+
+    const normalizeGitPath = (p) => p.replace(/\\/g, '/')
+    // step1 启动时记录的全量脏文件 = 预存改动（非本次 quick 产生）。审计必须排除它们，
+    // 否则脏工作区下预存文件持续留在 git status → 命中 baselineFiles → 误判「覆盖 baseline」
+    // → 永远 blocked（--force-baseline 也救不回来，因为 status 判定看 baselineHit 数组）。
+    // 前缀匹配：baseline 录入时未跟踪目录会被 git 折叠成 `dir/`（带尾斜杠）token，审计时若该
+    // 目录下文件被跟踪则展开成文件级 `dir/file`——精确匹配对不上，故尾斜杠 token 按目录前缀放行。
+    const normBaseline = (baselineFiles || []).map(f => normalizeGitPath(f))
+    const baselineExact = new Set(normBaseline.filter(f => !f.endsWith('/')))
+    const baselineDirs = normBaseline.filter(f => f.endsWith('/'))
+    const isBaselineFile = (p) => {
+      const f = normalizeGitPath(p)
+      return baselineExact.has(f) || baselineDirs.some(d => f.startsWith(d))
+    }
+    const DANGEROUS_PATTERNS = [
+      'package.json',
+      'package-lock.json',
+      'yarn.lock',
+      'pnpm-lock.yaml',
+      '.eslintrc',
+      'tsconfig.json',
+      // SillySpec 核心流程代码。W6 重构后 src/run.js（23 行 barrel）/ src/progress.js（facade）
+      // 把真正逻辑下沉到 src/run/、src/progress/ 子目录——旧的精确文件名匹配
+      // （file === 'src/run.js'）命中不到 src/run/command.js（. 与 / 不可混同），致危险文件门
+      // 静默失效。改用「目录前缀（带尾斜杠，startsWith 不会误伤 src/runtime-* 等同名前缀）+
+      // barrel/facade 本体精确名」双重覆盖。重构 src/ 模块时须同步本清单（multi-agent-review Q5）。
+      'src/run.js',
+      'src/run/',
+      'src/progress.js',
+      'src/progress/',
+      'src/db.js',
+      'src/stage-contract.js',
+      'src/stage-contract-spec.js',
+      'src/worktree.js',
+      'src/worktree-apply.js',
+      'src/hooks/',
+    ]
+
+    for (const entry of currentEntries) {
+      const status = entry.slice(0, 2).trim()
+      const file = parsePorcelainPath(entry)   // 已去引号/处理 rename/归一化，修正首行丢首字符
+      if (!file) continue
+
+      // 累计暂存计数：所有非 quick 元数据的未提交条目（含下方将被 baseline 跳过的前序残留）。
+      // 放在 isBaselineFile 跳过之前，确保 baseline 内文件也计入「累计暂存」。
+      if (!isQuickMetadata(file, guard.linkedChanges)) result.stagedTotal++
+
+      // 预存脏文件：step1 baseline 已记录，非本次 quick 产生，跳过审计（含折叠目录前缀匹配）
+      if (isBaselineFile(file)) 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 (file.startsWith('.sillyspec/') && !isQuickMetadata(file, guard.linkedChanges) && !forceBaseline) {
+        result.reasons.push(`危险文件变更: ${file}`)
+      }
+
+      if (DANGEROUS_PATTERNS.some(p => file === p || file.startsWith(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 (!isQuickMetadata(f, guard.linkedChanges)) {
+          result.reasons.push(`新增文件（需 --allow-new）: ${f}`)
+        }
+      }
+    }
+
+    // 检查 allowedFiles 范围
+    if (allowedFiles.length > 0) {
+      for (const f of result.changedFiles) {
+        if (!allowedFiles.includes(f) && !isQuickMetadata(f, guard.linkedChanges)) {
+          result.reasons.push(`超出 allowedFiles: ${f}`)
+        }
+      }
+    }
+
+    // 判定结果（force-baseline 降级 baselineHit → 非 blocked；allow-new 降级新增文件 → 非 warning。
+    // reasons 文案本就受这两个 flag 控制，但原判定直接看数组长度，致 flag 对 status 失效。）
+    if ((!forceBaseline && result.baselineHit.length > 0) || result.deletedFiles.length > 0 || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
+      result.status = 'blocked'
+    } else if ((!allowNew && result.newFiles.length > 0) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+      result.status = 'warning'
+    }
+
+    // quicklog 存在性检查
+    try {
+      const quicklogDir = join(cwd, '.sillyspec', 'quicklog')
+      if (existsSync(quicklogDir)) {
+        const qlFiles = readdirSync(quicklogDir).filter(f => f.endsWith('.md'))
+        if (qlFiles.length === 0) {
+          result.reasons.push('quicklog 目录为空（无任务记录）')
+          if (result.status === 'safe') result.status = 'warning'
+        }
+      } else {
+        result.reasons.push('quicklog 目录不存在（agent 未创建任务记录）')
+        if (result.status === 'safe') result.status = 'warning'
+      }
+    } catch {}
+
+    // --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   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
+      console.log(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
+      console.log(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+      console.log(`   或在首个 sillyspec run quick 启动（step 1）时就声明这些 flag，持久化进 guard。`)
+    }
+  } catch (e) {
+    result.reasons.push(`审计失败: ${e.message}`)
+    result.status = 'warning'
+  }
+
+  return result
+}
+
+// ── Step 处理辅助（W6 Step7a 从 run.js 搬入：getStageSteps/formatWaitOptions 被 run.js + complete.js 共用）──
+/**
+ * 格式化 waitOptions 为人类可读字符串
+ */
+export function formatWaitOptions(raw) {
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw)
+    if (Array.isArray(parsed)) return parsed.join(', ')
+    return raw
+  } catch {
+    return raw
+  }
+}
+
+
+/**
+ * 获取阶段的步骤定义（execute 需要动态构建）
+ */
+export async function getStageSteps(stageName, cwd, progress, specDir = null) {
+  if (stageName === 'execute') {
+    const changeDir = resolveChangeDir(cwd, progress, specDir)
+    let planFile = null
+    let worktreePath = null
+    if (changeDir) {
+      const p = join(changeDir, 'plan.md')
+      if (existsSync(p)) planFile = p
+      // 自动检测 worktree 路径，注入 Wave prompt 的 workdir 指令
+      // 修复：之前未传 worktreePath 给 buildExecuteSteps，导致 Wave prompt 缺失工作目录指令，
+      // 子代理可能把文件写到主工作区而非 worktree 内，破坏隔离。
+      try {
+        const changeName = basename(changeDir)
+        const { WorktreeManager } = await import('../worktree.js')
+        const wm = new WorktreeManager({ cwd })
+        const meta = wm.getMeta(changeName)
+        if (meta?.worktreePath && existsSync(meta.worktreePath)) {
+          worktreePath = meta.worktreePath
+        }
+      } catch {
+        // 无 worktree meta 不阻断——可能是首次启动或 in-place 模式
+      }
+    }
+    return buildExecuteSteps(planFile, { worktreePath })
+  }
+  if (stageName === 'plan') {
+    const changeDir = resolveChangeDir(cwd, progress, specDir)
+    return buildPlanSteps(changeDir)
+  }
+  const def = stageRegistry[stageName]
+  return def ? def.steps : null
+}
+