sillyspec 3.27.12 → 3.28.0

package/.claude/worktrees/sillyspec-data-model-research/src/run/complete-handlers.js

@@ -1,1552 +0,0 @@
-/**
- * run/complete-handlers.js（W6 Step5 从 run.js 抽出）。
- *
- * completeStep 的子 handler + archive 收尾（自洽叶子模块，仅被 completeStep 调用）：
- *   - handleArchiveConfirmStep：archive「确认归档」步骤 --confirm 门控 + 推荐文档校验
- *   - handlePlanGeneratePlanStep：plan「generate_plan」完成后动态插入 coordinator + postcheck 步骤
- *   - handleScanProjectListStep：scan step 2 完成后按项目展开 perProject 步骤（用 sanitizeProjectName/validateParsedProjects）
- *   - archiveChangeDirectory：归档移动变更目录（6 处 process.exit(1) + worktree 清理；handleArchiveConfirmStep 内部调用）
- *     srcDir 缺失时走 findAlreadyArchivedDir 幂等自愈（issue archive-stage-physical-tracking-desync）；
- *     archiveChangeDirectory + findAlreadyArchivedDir 已 export 供 test 直接 import
- *   - sanitizeProjectName / validateParsedProjects：项目名清洗 + 列表校验纯函数（handleScanProjectListStep 专用）
- *
- * 安全锚：run.js 始终 barrel。3 handler 由 run.js import 回来；sanitizeProjectName + validateParsedProjects
- * 被 test 直接 import（run-sanitize-project-name / run-scan-project-parse），run.js barrel re-export 契约保留。
- * 4 目标 handler 无 test 直接 import；archiveChangeDirectory + findAlreadyArchivedDir 供自愈 test 直接 import，无需 barrel re-export。completeStep（Step7 搬）将把 import 行带走。
- *
- * 路径修正（相对 src/run/）：
- *   - resolveChangeDir 从 './shared.js'；renameSyncRetry 从 '../fs-atomic.js'；stageRegistry 从 '../stages/index.js'
- *   - 动态 import './stages/plan.js' / './worktree.js' → '../'（src/ 下，退一层；真环依赖保留动态）
- *   - 删除 archiveChangeDirectory 内死代码 `const { renameSync } = await import('fs')`（renameSync 解构未用，实际走 renameSyncRetry）
- *
- * archiveChangeDirectory 的 6 处 process.exit 全 exit(1)：5 个顶层 guard 直接终止；L1325 在 catch 内主动 exit
- * （非被外层吞）；process.exit 不可被 try 捕获 → 搬迁行为完全等价。
- */
-import { basename, join, resolve, relative, isAbsolute } from 'node:path'
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
-import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations } from './shared.js'
-import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
-import { stageRegistry } from '../stages/index.js'
-import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
-import { printQuickAuditReview } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
-import { getRule } from '../stage-contract-spec.js'
-import { archiveDestDirName } from '../stage-contract.js'
-
-/**
- * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
- * - 必须含至少一个字母（拒绝纯数字 "0"/"7"/"07"，避免 scan-projects.json 脏数据）
- * - 长度必须 ≥ 2（拒绝单字符 "a"/"0"）
- * @param {string} name - 原始项目名候选
- * @returns {string | null} 合法项目名或 null（拒绝）
- */
-export function sanitizeProjectName(name) {
-  if (!name) return null
-  const clean = String(name).replace(/[^a-zA-Z0-9_\-.]/g, '').trim()
-  if (!clean) return null
-  if (!/[a-zA-Z]/.test(clean)) return null    // 纯数字/符号拒绝（"0"/"7"/"07"）
-  if (clean.length < 2) return null           // 单字符拒绝（"a"/"0"）
-  return clean
-}
-/**
- * 校验从 step 2 解析出的项目列表。
- * 不通过则不落盘 projects/*.yaml、不展开 perProject 步骤。
- *
- * @param {Array<{id: string, path?: string}>} projects - 项目列表（含可选 path）
- * @param {string} sourceRoot - 源码根目录，用于 path 安全校验
- */
-export function validateParsedProjects(projects, sourceRoot) {
-  const errors = []
-  if (!projects || projects.length === 0) {
-    return { ok: false, errors: ['项目列表为空'] }
-  }
-  if (projects.length > 10) {
-    return { ok: false, errors: [`项目数量 ${projects.length} 超过上限 10，疑似误解析`] }
-  }
-  const safeRoot = resolve(sourceRoot)
-  const seen = new Set()
-  for (const proj of projects) {
-    const id = proj.id || proj
-    if (seen.has(id)) {
-      errors.push(`重复项目名: ${id}`)
-    }
-    seen.add(id)
-    // slug 合法性：只允许 a-z 0-9 _ - .，长度 2-64
-    if (!/^[a-zA-Z][\w\-.]{1,63}$/.test(id)) {
-      errors.push(`项目名 "${id}" 不合法（需 slug 格式：字母开头，只含 a-zA-Z0-9_-., 长度 2-64）`)
-    }
-    // path 安全校验（如果提供了 path）
-    if (proj.path) {
-      if (proj.path.includes('..')) {
-        errors.push(`项目 "${id}" 的 path 包含 .. ，拒绝越界`)
-      } else {
-        const absPath = resolve(safeRoot, proj.path)
-        const rel = relative(safeRoot, absPath)
-        if (rel.startsWith('..') || isAbsolute(rel)) {
-          errors.push(`项目 "${id}" 的 path "${proj.path}" 解析后超出 source_root`)
-        }
-        if (!existsSync(absPath)) {
-          errors.push(`项目 "${id}" 的 path "${proj.path}" 不存在`)
-        }
-      }
-    }
-  }
-  if (errors.length > 0) return { ok: false, errors }
-  return { ok: true, errors: [] }
-}
-/**
- * 在 changes/archive/ 下查找变更 <changeName> 是否已被归档（archive 脱钩自愈用）。
- *
- * 归档目录名 = 原变更名（直接移入 archive/，不重命名）。
- * 精确匹配 + 要求目录含 plan.md（归档必备产物，防止同名巧合误判）。
- * issue: archive-stage-physical-tracking-desync。
- *
- * @param {string} archiveDir - changes/archive 绝对路径
- * @param {string} changeName - 变更名（currentChange）
- * @returns {string|null} 命中的归档目录绝对路径，无则 null
- */
-export function findAlreadyArchivedDir(archiveDir, changeName) {
-  if (!existsSync(archiveDir)) return null
-  let entries
-  try {
-    entries = readdirSync(archiveDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
-  } catch {
-    return null
-  }
-  // 精确原名命中
-  const exact = entries.find((e) => e === changeName && existsSync(join(archiveDir, e, 'plan.md')))
-  if (exact) return join(archiveDir, exact)
-  return null
-}
-
-/**
- * 归档时清理可能残留的 worktree（execute 自动清理未走到 / 有未 apply 变更被遗弃）。
- * 安全策略：有未 apply 变更时保留 worktree 并警告，避免误删用户未应用的代码。
- * 同时清理该变更的 execute / stage-review runId marker（只写不删的累积物，
- * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）。
- * 从 archiveChangeDirectory 抽出，供正常归档 + 自愈归档复用。
- */
-export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
-  // ── 清理 runId marker：execute（current-execute-run-id-<change>）与 stage-review
-  //    （current-stage-review-run-id-<stage>-<change>）。marker 只服务 execute→verify→archive
-  //    期间，归档后无读者；不删则 .runtime 随变更数无限累积。runtimeRoot 解析同写入侧
-  //    （resolveRuntimeRoot 锚主仓），避免平台模式清理错位置。
-  try {
-    const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
-    if (existsSync(runtimeRoot)) {
-      // stage-review marker 精确匹配（坑 marker-suffix-overmatch）：marker 名是
-      // current-stage-review-run-id-<stage>-<change>，按 endsWith('-'+change) 后缀匹配会在归档
-      // 手工短名变更（如 login）时误删自动日期前缀变更（2026-08-01-login 天然以 '-login' 结尾）
-      // 的 marker。stage 集合与写入侧 stageReviewMarkerPath 的调用方一致。
-      const REVIEW_STAGES = ['brainstorm', 'plan', 'execute', 'verify', 'archive']
-      const markers = readdirSync(runtimeRoot).filter((f) =>
-        f === `current-execute-run-id-${archiveChangeName}` ||
-        REVIEW_STAGES.some(st => f === `current-stage-review-run-id-${st}-${archiveChangeName}`),
-      )
-      for (const m of markers) {
-        try { unlinkSync(join(runtimeRoot, m)) } catch {}
-      }
-      if (markers.length > 0) {
-        console.log(`🧹 归档清理 ${markers.length} 个 runId marker（execute/stage-review）`)
-      }
-    }
-  } catch (e) {
-    console.warn(`⚠️  归档 runId marker 清理失败（不阻断归档）: ${e.message}`)
-  }
-  try {
-    const { WorktreeManager } = await import('../worktree.js')
-    const wm = new WorktreeManager({ cwd })
-    const meta = wm.getMeta(archiveChangeName)
-    if (!meta) {
-      // 无 meta 兜底（坑 archive-cleanup-orphan-physical-dir，2026-08-21 实证）：meta 已被先行
-      // 流程注销（apply 自动 cleanup / doctor 幽灵清理）时此前直接 return——若物理目录因中途
-      // 失败残留下就是孤儿（无 meta=无锚定基准，残留即孤儿）。force 清理（幂等：什么都不存在
-      // 时 cleanup 返回 skipped 零副作用）。
-      const orphan = wm.cleanup(archiveChangeName, { force: true })
-      if (orphan.result === 'cleaned' || orphan.result === 'force-cleaned' || orphan.result === 'partial') {
-        console.log(`🧹 归档清理孤儿 worktree 残留（meta 已注销）: ${archiveChangeName}${orphan.residual?.length ? '（残留: ' + orphan.residual.join('; ') + '）' : ''}`)
-      }
-      return
-    }
-    const check = meta.mode !== 'in-place-fallback' ? wm.hasUnappliedChanges(archiveChangeName) : { hasChanges: false }
-    if (check.hasChanges) {
-      console.warn(`⚠️  归档时 worktree 仍有 ${check.changedFiles.length} 个未 apply 变更，保留 worktree`)
-      console.warn(`   确认不需要后手动清理: sillyspec worktree cleanup ${archiveChangeName} --force`)
-      return
-    }
-    const cleanResult = wm.cleanup(archiveChangeName)
-    if (cleanResult.residual?.length > 0) {
-      console.warn(`⚠️  归档 worktree 清理残留: ${cleanResult.residual.join('; ')}`)
-      console.warn(`   手动处理: sillyspec worktree cleanup ${archiveChangeName} --force`)
-    }
-  } catch (e) {
-    console.warn(`⚠️  归档 worktree 清理失败（不阻断归档）: ${e.message}`)
-  }
-}
-
-/**
- * 提取 module-impact.md「更新结果」表中的未清文档同步死信行（债单 D-5）。
- *
- * 只在「## 更新结果」段内扫描表格行（| 分隔），状态判定取**末列** trim 后精确匹配
- * pending / 待办 / 未同步 / not-done（大小写不敏感）。不做全文 grep——
- * sync_manual_get_pending / pending_review / pending-leases 等代码标识符出现在
- * 矩阵摘要列是合法内容，不能误报（实证：archive 全量扫描唯一死信形态是末列 pending）。
- *
- * 纯函数：无 fs/git 调用，export 供 test 直接 import。
- * @param {string} content module-impact.md 全文（CRLF/LF 均容）
- * @returns {string[]} 死信行原文（去首尾空白），空数组 = 无死信
- */
-export function extractPendingDocSyncRows(content) {
-  if (!content || typeof content !== 'string') return []
-  const normalized = content.replace(/\r\n/g, '\n')
-  const sectionStart = normalized.search(/^#{2,3}\s*更新结果\s*$/m)
-  if (sectionStart === -1) return []
-  // 跳过标题行本身（matchFirstLine 吃掉标题），再找下一个章节边界
-  const titleMatch = normalized.slice(sectionStart).match(/^#{2,3}\s*更新结果\s*$/m)
-  const bodyStart = sectionStart + titleMatch[0].length
-  const afterTitle = normalized.slice(bodyStart)
-  const nextSection = afterTitle.search(/^#{1,3}\s/m)
-  const section = nextSection === -1 ? afterTitle : afterTitle.slice(0, nextSection)
-  const PENDING_STATUSES = new Set(['pending', '待办', '未同步', 'not-done', 'todo'])
-  const rows = []
-  for (const line of section.split('\n')) {
-    const trimmed = line.trim()
-    if (!trimmed.startsWith('|')) continue
-    const cells = trimmed.split('|').map(c => c.trim())
-    // split 首尾产生空串（行首行尾的 |），真实单元格在中间；末列 = 最后一个非空单元格之后
-    // 表格行结构 | 模块文档 | 操作 | 状态 | → cells = ['', '模块文档', '操作', '状态', '']
-    const lastCell = cells[cells.length - 1]
-    if (lastCell === '' && cells.length >= 2) cells.pop()
-    const statusCell = cells[cells.length - 1]
-    if (statusCell && PENDING_STATUSES.has(statusCell.toLowerCase())) rows.push(trimmed)
-  }
-  return rows
-}
-
-/**
- * 提取 module-impact.md「更新结果」表中的已完成（done）行声明的目标文档路径（债单 D-4 窄口径）。
- *
- * done 行首列是目标标识：`modules/<id>.md`（模块卡片）、`_module-map.yaml`（映射索引）、
- * `.sillyspec/docs/<project>/modules/<f>.md`（含仓库前缀的全路径）等。本函数提取首列里
- * 能解析出的文档路径 token，供调用方校验文件存在性——声明 done 但目标文件不存在 = 假申报。
- *
- * 提取规则（保守，宁可漏报不误报）：
- *   - 首列以反引号包裹或裸写的 `.md`/`.yaml` 结尾路径 token（含路径分隔符 /）
- *   - `modules/<id>.md` 相对写法解析为 `<specBase>/docs/<project>/modules/<id>.md`——但 project
- *     归属需读 _module-map，此处只返回原样 token，路径解析留给调用方（有 specBase 上下文）
- *   - `_module-map.yaml` 裸名跳过（存在性由 map 本身保证，且各项目都有）
- *
- * 纯函数：无 fs/git 调用，export 供 test 直接 import。
- * @param {string} content module-impact.md 全文
- * @returns {string[]} done 行声明的文档路径 token（去重）
- */
-export function extractDoneDocTargets(content) {
-  if (!content || typeof content !== 'string') return []
-  const normalized = content.replace(/\r\n/g, '\n')
-  const sectionStart = normalized.search(/^#{2,3}\s*更新结果\s*$/m)
-  if (sectionStart === -1) return []
-  const titleMatch = normalized.slice(sectionStart).match(/^#{2,3}\s*更新结果\s*$/m)
-  const bodyStart = sectionStart + titleMatch[0].length
-  const afterTitle = normalized.slice(bodyStart)
-  const nextSection = afterTitle.search(/^#{1,3}\s/m)
-  const section = nextSection === -1 ? afterTitle : afterTitle.slice(0, nextSection)
-  const targets = new Set()
-  for (const line of section.split('\n')) {
-    const trimmed = line.trim()
-    if (!trimmed.startsWith('|')) continue
-    const cells = trimmed.split('|').map(c => c.trim())
-    if (cells.length >= 2) cells.pop() // 行尾空 cell
-    const statusCell = cells[cells.length - 1]
-    if (!statusCell || statusCell.toLowerCase() !== 'done') continue
-    // 首个非空 cell（跳过 split 产生的行首空串）
-    const firstCell = cells.slice(1).find(c => c !== '') || ''
-    // 从首列提取 .md/.yaml 结尾且含 / 的路径 token（modules/x.md 或 a/b/c.yaml）；
-    // 反引号包裹优先，裸写次之。_module-map.yaml 无 / 跳过（见 docstring）。
-    const m = firstCell.match(/`([^`]*\.(?:md|yaml))`/) || firstCell.match(/(^|\s|（)([\w./-]+\/[\w./-]*\.(?:md|yaml))/)
-    if (m) {
-      const token = (m[2] !== undefined && m[2] !== null && m[1] !== '`') ? m[2] : m[1]
-      if (token && !token.endsWith('_module-map.yaml')) targets.add(token)
-    }
-  }
-  return [...targets]
-}
-
-export async function archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts = {}) {
-  const archiveChangeName = progress.currentChange
-  if (!archiveChangeName) {
-    console.error('❌ 归档失败：未找到当前变更名（currentChange）')
-    process.exit(1)
-  }
-  const changesDir = join(specBase, 'changes')
-  const archiveDir = join(changesDir, 'archive')
-  const srcDir = join(changesDir, archiveChangeName)
-  const date = new Date().toISOString().slice(0, 10)
-  const destName = archiveDestDirName(date, archiveChangeName)
-  const destDir = join(archiveDir, destName)
-
-  if (!existsSync(srcDir)) {
-    // 幂等自愈（issue archive-stage-physical-tracking-desync）：源目录已不存在，但变更可能已被
-    // 手动 / 部分流程移到 changes/archive/ 并 commit，而 --done --confirm 从未正式跑完 → 进度 DB
-    // 卡 archive 阶段、active 列表仍列此 change。检测到已归档则回填进度（unregisterChange）并
-    // 成功返回，让收尾流程把 archive 阶段标完成，而非 exit(1) 死路（source 已移走无法重跑 move）。
-    const alreadyArchivedDir = findAlreadyArchivedDir(archiveDir, archiveChangeName)
-    if (alreadyArchivedDir) {
-      console.log(`ℹ️  源目录不存在但变更已在 archive/（${basename(alreadyArchivedDir)}），判定已归档，自愈进度 DB`)
-      // 终态一致化（坑 manual-archive-desync-status-only）：手动搬目录绕过标准归档后，本自愈路径
-      // 不能只翻 status——同时收尾 archive 阶段（steps/stages/current_stage），否则推送平台的终态
-      // 是「已归档 + 归档 0/5 + 停在 execute」的矛盾体，详情页渲染成「进度丢失」
-      pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
-      await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
-      console.log(`📦 已自愈归档：${archiveChangeName} → archive/${basename(alreadyArchivedDir)}/`)
-      return alreadyArchivedDir
-    }
-    console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
-    console.error(`   且 changes/archive/ 下未找到该变更的归档目录。若已手动归档请核对目录名；否则先补全变更产物。`)
-    process.exit(1)
-  }
-  // 移动前硬校验：变更包必须含 plan.md，否则不该归档。
-  // 在移动前阻断（而非移动后），目录尚未动，用户可直接修复后重试。
-  if (!existsSync(join(srcDir, 'plan.md'))) {
-    console.error(`❌ 归档失败：变更目录缺少 plan.md（${srcDir}）`)
-    console.error(`   plan.md 是归档的必需产物。请先补全 plan 阶段产出再归档。`)
-    process.exit(1)
-  }
-  // 移动前硬校验（债单 D-5）：module-impact.md「更新结果」表存在 pending 死信 → 阻断。
-  // 修复场景：perf-remediation 类变更把文档同步显式推给 archive（「（execute 完成后由 archive
-  // 阶段同步）| 待办 | pending」），archive 又没做 → 带 pending 归档且 verify 全 PASS，死信无人回填。
-  // 只查「## 更新结果」段内表格行的状态列（末列）精确匹配 pending/待办/未同步——不做全文 grep，
-  // 防 sync_manual_get_pending / pending_review 等代码标识符误报。
-  const impactPath = join(srcDir, 'module-impact.md')
-  if (existsSync(impactPath)) {
-    const pendingRows = extractPendingDocSyncRows(readFileSync(impactPath, 'utf8'))
-    if (pendingRows.length > 0) {
-      console.error(`❌ 归档失败：module-impact.md「更新结果」表存在 ${pendingRows.length} 个未清 pending/待办项（死信）`)
-      for (const row of pendingRows) console.error(`   - ${row}`)
-      console.error(`   这些文档同步项从未落地。请先完成同步并回填状态为 done/skipped（说明原因），再归档。`)
-      process.exit(1)
-    }
-  }
-  if (existsSync(destDir)) {
-    console.error(`❌ 归档失败：目标目录已存在 ${destDir}`)
-    process.exit(1)
-  }
-  mkdirSync(archiveDir, { recursive: true })
-  try {
-    renameSyncRetry(srcDir, destDir)
-  } catch (e) {
-    console.error(`❌ 归档失败：移动变更目录时出错（${e.message}）`)
-    console.error(`   常见原因：变更目录内文件被 IDE / 杀毒 / 索引占用，已重试 5 次仍失败。请关闭相关程序后重试。`)
-    process.exit(1)
-  }
-
-  if (!existsSync(destDir) || existsSync(srcDir)) {
-    console.error('❌ 归档校验失败：移动操作异常')
-    process.exit(1)
-  }
-
-  // 正常路径同样走终态一致化（坑 manual-archive-desync-status-only）：标准 --done --confirm 流程
-  // 中 completeStep 随后也会逐项完成，此处先收尾是幂等写同值——保证任何走出本函数的归档终态一致
-  pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
-
-  // CLI 下沉 git add（坑4，FR-04）：确定性暂存归档目录 + 模块文档，不靠 step5 prompt 驱动。
-  // step5 prompt 的 git add 保留作幂等兜底；POSIX 路径跨平台（git 接受正斜杠）。
-  // safeGit 内部已 try-catch（返回 {value,error} 不抛），外层 try 兜底防御；失败不阻断归档
-  // （目录已移动 + change 已注销），由 step5 prompt git add + agent git status 核对兜底。
-  try {
-    safeGit(cwd, ['add', '--', '.sillyspec/changes/archive/'])
-    safeGit(cwd, ['add', '--', '.sillyspec/docs/'])
-  } catch {}
-
-  // ── 他者半归档残留探测（坑 archive-other-residual-rename，2026-08-21 实证）──
-  // 并行变更的手动归档把 R 残留（源目录 rename 目标行）留在暂存区；本变更归档提交时
-  // git status 显示它们，agent 会误判「还没提交完 / 要做第二次提交」。区分：
-  //   本变更：未暂存的源侧移动（` D changes/<me>/...` + 未跟踪 archive/<me>/...）→ 补暂存
-  //           让归档成单次原子提交；
-  //   他者：已暂存的 rename（`R  changes/<他人>/... -> changes/archive/<他人>/...`）→ 只 warn
-  //         提示归属（不 stage 不动——别人的归别人的）。
-  try {
-    const raw = gitQuiet(cwd, ['status', '--porcelain'], { trim: false, timeout: 30000 })
-    if (raw && raw.trim()) {
-      const changesPrefix = '.sillyspec/changes/'
-      const minePaths = []
-      const othersResidual = []
-      for (const line of raw.split('\n')) {
-        if (!line || line.length < 4) continue
-        const x = line[0], y = line[1]
-        const body = line.slice(3).trim()
-        const arrow = body.indexOf(' -> ')
-        const src = arrow !== -1 ? body.slice(0, arrow).replace(/^"|"$/g, '') : null
-        const dst = (arrow !== -1 ? body.slice(arrow + 4) : body).replace(/^"|"$/g, '')
-        if (x === 'R' && y === ' ' && arrow !== -1 && dst.startsWith(changesPrefix + 'archive/')) {
-          // 已暂存 rename → 半归档残留；按目标目录名归属他者变更
-          const m = /^\.sillyspec\/changes\/archive\/([^/]+)\//.exec(dst)
-          const owner = m ? m[1] : '?'
-          if (owner !== archiveChangeName) othersResidual.push(owner)
-        } else if (x === ' ' && (y === 'D' || y === 'A' || y === 'M')) {
-          // 未暂存的源侧移动：源目录 D / 新位置 A——指向本变更的补暂存
-          const p = dst || src
-          if (p && (p.startsWith(changesPrefix + archiveChangeName + '/')
-                    || p.startsWith(changesPrefix + 'archive/' + archiveChangeName + '/'))) {
-            minePaths.push(p)
-          }
-        }
-      }
-      if (minePaths.length > 0) {
-        try { safeGit(cwd, ['add', '-A', '--', changesPrefix]) } catch {}
-        console.log(`🧾 已补暂存本变更归档的源侧移动（${minePaths.length} 项，归档成单次原子提交）`)
-      }
-      if (othersResidual.length > 0) {
-        const owners = [...new Set(othersResidual)].filter(Boolean)
-        console.warn(`⚠️  检测到「他者半归档」残留（暂存区存在其他变更的 rename 记录）：${owners.join('、')}`)
-        console.warn(`   这些是别的变更此前手动归档留下的暂存项，不属于本次归档——git status 里看到它们是正常的，`)
-        console.warn(`   本变更归档已完成，无需为其做第二次提交；如需清理走它们自己的收尾（或 git restore --staged 后核对）。`)
-      }
-    }
-  } catch { /* 探测失败不阻断归档（advisory） */ }
-
-  // 归档时清理可能残留的 worktree（自愈路径也复用，见上方 srcDir 缺失分支）。
-  await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
-
-  console.log(`📦 已归档：${archiveChangeName} → archive/${destName}/`)
-  return destDir
-}
-/**
- * archive 阶段「确认归档」步骤的收尾处理器（从 completeStep 抽出，行为保持）。
- *
- * 两件事：
- *   1. --confirm 门控：缺 --confirm → 回退 step 状态、提示、返回 early-return 对象（completeStep 透传）
- *   2. --confirm 通过 → archiveChangeDirectory 移动变更目录 + 推荐文档（design.md / module-impact.md）校验
- *      （contracts.archive.validators 为空，两个 validator 生效窗口互斥；plan.md 已在移动前硬校验阻断）
- *
- * @returns {{stageCompleted:false,currentIdx,nextPendingIdx:number}|null}
- */
-export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts = {} }) {
-  if (stageName !== 'archive' || steps[currentIdx]?.name !== '确认归档') return null
-  if (!confirm) {
-    steps[currentIdx].status = 'pending'
-    steps[currentIdx].completedAt = null
-    if (outputText) steps[currentIdx].output = null
-    pm._write(cwd, progress, changeName)
-    console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
-    return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
-  }
-  // 主仓互斥锁（坑 main-repo-no-mutex 二批）：archiveChangeDirectory 改主仓共享状态（目录
-  // rename + 共享 index 的 git add + marker 删除 + worktree 清理），与并行会话的 apply/cleanup
-  // 互踩。exit 钩子兜底：其内部 guard 失败 exit(1) 时锁也会被清（见 withMainRepoLock）。
-  const { withMainRepoLock } = await import('../worktree-apply.js')
-  const archivedDir = await withMainRepoLock(cwd, changeName, 'archive-finalize', () => archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts))
-  if (archivedDir && existsSync(archivedDir)) {
-    // 内存快照同步（坑 archive-progress-show-stale，2026-08-21 实证）：archiveChangeDirectory 内
-    // unregisterChange 已在 DB 写 current_stage='archive'（终态一致化），但本进程 progress 是命令
-    // 开始时读的旧快照——不同步的话，completeStep 后续 _write 会用旧值（如停在 verify）把
-    // DB 覆盖回去，progress show 就一直显示归档前的阶段
-    progress.currentStage = 'archive'
-    const recommendedDocs = ['design.md', 'module-impact.md']
-    const missingRecommended = recommendedDocs.filter(d => !existsSync(join(archivedDir, d)))
-    if (missingRecommended.length > 0) {
-      console.warn(`\n⚠️ 归档校验警告：归档目录缺少推荐文档`)
-      for (const d of missingRecommended) console.warn(`   - ${d}（${archivedDir}）`)
-    } else {
-      console.log(`\n✅ 归档校验通过：核心文档齐全`)
-    }
-    // D-4 窄口径：更新结果表 done 行声明的目标文档存在性对账（warning 不阻断——
-    // 目标路径写法多样（modules/x.md 相对/全路径）+ 语义对账推 sillyhub，此处只抓
-    // 能确定性解析且确实不存在的假申报）。
-    const impactContent = existsSync(join(archivedDir, 'module-impact.md'))
-      ? readFileSync(join(archivedDir, 'module-impact.md'), 'utf8') : ''
-    const doneTargets = extractDoneDocTargets(impactContent)
-    if (doneTargets.length > 0) {
-      const missing = doneTargets.filter(t => {
-        // 相对 specBase 解析：modules/<x> → docs/<project>/modules/<x> 由 _module-map 归属，
-        // CLI 不猜 project——只对全路径（.sillyspec/docs/ 开头或含 3+ 段路径）做存在性判定
-        if (!t.includes('/')) return false
-        const abs = isAbsolute(t) ? t : resolve(cwd, t)
-        return !existsSync(abs)
-      })
-      if (missing.length > 0) {
-        console.warn(`\n⚠️ 归档校验警告：module-impact「更新结果」声明 done 的文档路径不存在（假申报嫌疑）`)
-        for (const t of missing) console.warn(`   - ${t}`)
-        console.warn(`   相对写法（modules/<id>.md）不在此校验范围；全路径声明但文件不存在请核实。`)
-      }
-    }
-  }
-  return null
-}
-/**
- * plan 阶段「generate_plan」步骤完成后，动态插入任务蓝图（coordinator）+ postcheck 步骤
- * （从 completeStep 抽出，行为保持）。使用稳定 id 匹配，不依赖中文标题。
- *
- * plan.md 已含任务时，buildPlanSteps 返回 [fixedPrefix(classify/generate_plan/review_plan),
- * coordinator, postcheck]；本函数把 generate_plan 之后的 coordinator+postcheck 插到当前步后。
- */
-export async function handlePlanGeneratePlanStep({ stageName, steps, currentIdx, defStepsForCurrent, cwd, progress }) {
-  if (stageName !== 'plan') return
-  const currentStepDef = defStepsForCurrent?.[currentIdx]
-  const currentStepEntry = steps[currentIdx]
-  const stepId = currentStepDef?.id || currentStepEntry?.id || currentStepEntry?._stepId
-  if (stepId !== 'generate_plan') return
-  const changeDir = resolveChangeDir(cwd, progress)
-  if (!changeDir) return
-  const planFile = join(changeDir, 'plan.md')
-  if (!existsSync(planFile)) return
-  const planContent = readFileSync(planFile, 'utf8')
-  const { buildPlanSteps, fixedPrefix, fixedSuffix } = await import('../stages/plan.js')
-  const fullSteps = buildPlanSteps(changeDir, planContent)
-  const prefixLen = fixedPrefix.length
-  const suffixLen = fixedSuffix.length
-  // 新结构：[...fixedPrefix, coordinatorStep?, postcheckStep?]；fixedSuffix 为空，coordinator+postcheck 都在 prefix 之后
-  const coordinatorSteps = fullSteps.slice(prefixLen, suffixLen > 0 ? -suffixLen : undefined)
-  if (coordinatorSteps.length === 0) return
-  for (let i = 0; i < coordinatorSteps.length; i++) {
-    const stepDef = coordinatorSteps[i]
-    const stepEntry = {
-      id: stepDef.id,
-      name: stepDef.name,
-      status: 'pending',
-      prompt: stepDef.prompt || '',
-      outputHint: stepDef.outputHint,
-      optional: stepDef.optional
-    }
-    // 传递 noAI / _cliAction 属性
-    if (stepDef.noAI) stepEntry.noAI = true
-    if (stepDef._cliAction) stepEntry._cliAction = stepDef._cliAction
-    steps.splice(currentIdx + 1 + i, 0, stepEntry)
-  }
-  console.log(`  📝 已动态插入 ${coordinatorSteps.length} 个步骤（${coordinatorSteps.map(s => s.name).join(', ')}）`)
-}
-/**
- * scan 阶段 step 2「构建扫描项目列表」完成后，按项目展开 perProject 步骤（从 completeStep 抽出，行为保持）。
- *
- * 只接受结构化输出（scan_projects YAML block 或 BEGIN_PROJECT_LIST 标记块），校验通过后
- * 自动注册 projects/<id>.yaml + 写 scan-projects.json + 把 perProject 步骤按项目展开。
- * 不展开 completeStep 提前 return（失败只记 validationError，由 completeStep 继续推进下一步）。
- */
-export async function handleScanProjectListStep({ stageName, steps, currentIdx, outputText, stageData, specBase, cwd, platformOpts }) {
-  if (stageName !== 'scan' || steps[currentIdx]?.name !== '构建扫描项目列表') return
-  // 解析项目列表：只接受结构化输出（YAML block 或 BEGIN_PROJECT_LIST 标记）
-  // 不再从自由文本猜测项目名——自由文本列表的误解析会导致垃圾项目落盘
-  let parsedProjects = [] // Array<{id, path?}>
-  let parsedFromStructuredOutput = false
-  if (outputText) {
-    // 格式 A: YAML block — 匹配 scan_projects: 下所有 - id: xxx 条目（含多行属性）
-    const yamlBlock = outputText.match(/scan_projects:\s*\n([\s\S]+?)(?=$|\n[^\s])/)
-    if (yamlBlock) {
-      const entries = [...yamlBlock[1].matchAll(/-\s+id:\s*(\S+)(?:[\s\S]*?)(?=\n\s+-\s+id:|$)/g)]
-      for (const m of entries) {
-        const id = sanitizeProjectName(m[1])
-        if (!id) continue
-        // 提取可选 path 字段
-        const pathMatch = m[0].match(/path:\s*(\S+)/)
-        const entry = pathMatch ? { id, path: pathMatch[1].trim() } : { id }
-        parsedProjects.push(entry)
-      }
-      parsedFromStructuredOutput = parsedProjects.length > 0
-    }
-    // 格式 B: BEGIN_PROJECT_LIST ... END_PROJECT_LIST 标记块
-    if (!parsedFromStructuredOutput) {
-      const blockMatch = outputText.match(/BEGIN_PROJECT_LIST\s*\n([\s\S]*?)\n*END_PROJECT_LIST/)
-      if (blockMatch) {
-        const raw = [...blockMatch[1].matchAll(/^-\s+(\S+)/gm)].map(m => m[1])
-        parsedProjects = raw.map(s => sanitizeProjectName(s)).filter(Boolean).map(id => ({ id }))
-        parsedFromStructuredOutput = parsedProjects.length > 0
-      }
-    }
-  }
-
-  const projectNames = parsedProjects.map(p => p.id)
-
-  if (parsedFromStructuredOutput) {
-    stageData.scanMeta = stageData.scanMeta || {}
-    stageData.scanMeta.projectListParsed = true
-  } else {
-    // 结构化输出未解析到 → 回退读取已有 projects/*.yaml
-    // 读取时也校验：path 不存在的 yaml 视为垃圾，直接跳过
-    console.warn('⚠️  step 2 未输出结构化项目列表，回退扫描已注册项目')
-    stageData.scanMeta = stageData.scanMeta || {}
-    stageData.scanMeta.projectListParsed = false
-    const projectsDir = join(specBase, 'projects')
-    if (existsSync(projectsDir)) {
-      const yamlFiles = readdirSync(projectsDir).filter(f => f.endsWith('.yaml'))
-      const fallbackProjects = []
-      const fallbackSkipped = []
-      for (const yf of yamlFiles) {
-        const pName = yf.replace(/\.yaml$/, '')
-        const yamlContent = readFileSync(join(projectsDir, yf), 'utf8')
-        const pathMatch = yamlContent.match(/^path:\s*(.+)/m)
-        const pPath = pathMatch ? pathMatch[1].trim() : pName
-        // 校验 path 是否存在且在 source_root 内。
-        // 用 relative 判越界（与 validateParsedProjects 同口径）：startsWith 前缀比较
-        // 无分隔符，C:\repo 会放行兄弟目录 C:\repository2（体检 BUG-13）
-        const absPath = resolve(cwd, pPath)
-        const rel = relative(resolve(cwd), absPath)
-        if (rel.startsWith('..') || isAbsolute(rel)) {
-          fallbackSkipped.push(`${pName} (path 越界: ${pPath})`)
-          continue
-        }
-        if (!existsSync(absPath)) {
-          fallbackSkipped.push(`${pName} (path 不存在: ${pPath})`)
-          continue
-        }
-        fallbackProjects.push({ id: pName, path: pPath })
-      }
-      if (fallbackSkipped.length > 0) {
-        console.warn(`⚠️  跳过 ${fallbackSkipped.length} 个垃圾/过期项目配置：${fallbackSkipped.join(', ')}`)
-        console.warn('   建议清理 projects/ 下的无效 yaml 文件')
-      }
-      parsedProjects = fallbackProjects
-      projectNames.length = 0
-      projectNames.push(...fallbackProjects.map(p => p.id))
-    }
-    if (parsedProjects.length === 0) {
-      // 无结构化输出 + 无合法已有项目 → step 2 失败
-      console.error('❌ step 2 未输出结构化项目列表，且 projects/ 下无合法项目配置')
-      console.error('   请在 --output 中输出 scan_projects YAML block 或 BEGIN_PROJECT_LIST 标记块')
-      steps[currentIdx].validationError = '未输出结构化项目列表且无合法 fallback'
-      // 不展开 perProject 步骤，直接跳到下一步
-    }
-  }
-
-  // 校验解析出的项目列表（原子守卫：不通过就不落盘）
-  const validation = validateParsedProjects(parsedProjects, cwd)
-  if (!validation.ok) {
-    console.error(`❌ 项目列表校验失败: ${validation.errors.join('; ')}`)
-    console.error('   step 2 完成，但不展开 perProject 步骤。请检查 --output 中的项目列表。')
-    steps[currentIdx].validationError = validation.errors.join('; ')
-  }
-
-  // 自动注册 + 保存 runtime + 展开 perProject 步骤（仅在校验通过时）
-  const projectsDir = join(specBase, 'projects')
-  if (validation.ok) {
-    for (const proj of parsedProjects) {
-      const pName = proj.id
-      const projYaml = join(projectsDir, `${pName}.yaml`)
-      if (!existsSync(projYaml)) {
-        mkdirSync(projectsDir, { recursive: true })
-        const candidates = [
-          join(cwd, pName),
-          join(cwd, 'backend', pName),
-          join(cwd, 'packages', pName),
-          join(cwd, 'apps', pName),
-          join(cwd, 'services', pName),
-        ]
-        const detected = candidates.find(c => existsSync(c))
-        const regPath = detected || join(cwd, pName)
-        writeFileSync(projYaml, `name: ${pName}\npath: ${regPath}\nstatus: active\n`)
-        console.log(`  📝 自动注册子项目: ${pName} → ${regPath}`)
-      }
-    }
-
-    // 保存 runtime 状态
-    const scanStatePath = join(specBase, '.runtime', 'scan-projects.json')
-    mkdirSync(join(specBase, '.runtime'), { recursive: true })
-    let scanState = { projects: projectNames, expanded: false }
-    if (existsSync(scanStatePath)) {
-      try { scanState = JSON.parse(readFileSync(scanStatePath, 'utf8')) } catch {}
-    }
-
-    // 收集当前步骤之后所有 perProject 步骤
-    const stageDef = stageRegistry[stageName]
-    const allSteps = stageDef?.steps || []
-    const perProjectSteps = allSteps.filter(s => s.perProject)
-
-    // 防重复展开
-    const alreadyExpanded = scanState.expanded || steps.some(s => s.name?.match(/\[.+\]\s*$/))
-    if (!alreadyExpanded && perProjectSteps.length > 0) {
-    // 找到当前步骤（step 2）在动态 steps 中的位置
-    const insertBase = currentIdx + 1
-    let insertPos = insertBase
-    for (const pName of projectNames) {
-      // 读取项目配置获取 projectRoot
-      const projYaml = join(specBase, 'projects', `${pName}.yaml`)
-      let projectRoot = '.'
-      if (existsSync(projYaml)) {
-        const yamlContent = readFileSync(projYaml, 'utf8')
-        const pathMatch = yamlContent.match(/^path:\s*(.+)/m)
-        if (pathMatch) projectRoot = pathMatch[1].trim()
-      }
-      const docOutputDir = platformOpts.specRoot ? `${specBase}/docs/${pName}` : `.sillyspec/docs/${pName}`
-      const contextPrefix = `\n---\n## 当前项目\n- **项目名**: ${pName}\n- **项目路径**: ${projectRoot}\n- **文档输出**: ${docOutputDir}\n\n⚠️ 本步骤只处理上面这个项目，不要处理其他项目。\n---\n\n`
-
-      for (const ppStep of perProjectSteps) {
-        steps.splice(insertPos, 0, {
-          name: `${ppStep.name} [${pName}]`,
-          project: pName,
-          status: 'pending',
-          prompt: contextPrefix + ppStep.prompt,
-          outputHint: ppStep.outputHint,
-          optional: ppStep.optional
-        })
-        insertPos++
-      }
-    }
-    // 移除原始的 perProject 步骤（未展开的版本）
-    for (let i = steps.length - 1; i >= 0; i--) {
-      if (steps[i].perProject && !steps[i].name?.includes('[')) {
-        steps.splice(i, 1)
-      }
-    }
-    console.log(`  📝 已按项目展开 ${perProjectSteps.length} 个步骤 × ${projectNames.length} 个项目 = ${perProjectSteps.length * projectNames.length} 个项目步骤`)
-    console.log(`  📁 扫描项目：${projectNames.join(', ')}`)
-    // 标记已展开，防止 resume 重复插入
-    scanState.expanded = true
-    writeFileSync(scanStatePath, JSON.stringify(scanState))
-  } // end !alreadyExpanded
-  } // end validation.ok
-}
-/**
- * Workflow post_check（W6 Step6 从 completeStep 内联块抽出）：
- *   - scan「深度扫描」完成 → 跑 scan-docs workflow postcheck，失败阻断推进（early-return）
- *   - archive「extract-module-impact」完成 → 跑 archive-impact workflow postcheck（impact-analyzer 结果）
- * 返回 early-return 对象（{stageCompleted:false,...}）由 completeStep 透传；null = 放行。
- *
- * ctx 字段：stageName/steps/currentIdx/cwd/specBase/progress/platformOpts/changeName（completeStep 局部）。
- * 辅助函数直接 import：basename/join/existsSync/readdirSync（顶部静态）；loadWorkflow/runPostCheck/
- * formatCheckReport/saveWorkflowRun 动态 import ../workflow.js（真环依赖保留动态）。
- *
- *搬迁清理：删除死代码 `typeof change !== 'undefined'`（completeStep 作用域无 change 变量，恒 null）。
- */
-export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cwd, specBase, progress, platformOpts, changeName }) {
-  // Workflow post_check：scan 深度扫描完成后自动检查产物
-  if (stageName === 'scan' && steps[currentIdx]?.name?.includes('深度扫描')) {
-    try {
-      const { loadWorkflow, runPostCheck, formatCheckReport, saveWorkflowRun } = await import('../workflow.js')
-      const wf = loadWorkflow(cwd, 'scan-docs')
-      if (wf) {
-        // 确定当前项目（优先级链）：
-        //   progress.project (dbProjectName，平台模式真实项目名，与 outputStep 占位符渲染对齐)
-        //   > change?.project (变更对象的项目字段，平台模式 change 创建时传入)
-        //   > steps[idx].project (perProject 展开标记，兼容旧模式)
-        //   > steps[idx].name 正则提取 [xxx] 后缀
-        //   > null（回退检查所有项目）
-        // task-05 修复：日志显示项目名变 frontend 是 perProject 误展开 bug，
-        // 用 progress.project（与 outputStep 占位符渲染路径一致）修正 myaaa/frontend 分裂。
-        const currentProjectName = progress.project
-          || steps[currentIdx].project
-          || (steps[currentIdx].name.match(/\[([^\]]+)\]\s*$/) || [])[1]
-          || null
-
-        // 确定要检查的项目列表
-        let projectsToCheck = []
-        if (currentProjectName) {
-          // 按项目展开模式：只检查当前项目
-          projectsToCheck = [currentProjectName]
-        } else {
-          // 兼容旧模式（未展开）：检查所有项目
-          const projectsDir = join(specBase, 'projects')
-          const projectFiles = existsSync(projectsDir)
-            ? readdirSync(projectsDir).filter(f => f.endsWith('.yaml'))
-            : []
-          projectsToCheck = projectFiles.map(f => f.replace(/\.yaml$/, ''))
-        }
-
-        let anyFailed = false
-        for (const pName of projectsToCheck) {
-          const result = runPostCheck(wf, cwd, pName, {}, specBase)
-          const report = formatCheckReport(result)
-          console.log(report)
-          if (result.status === 'fail') {
-            anyFailed = true
-            // retry_prompts 由 _checkWorkflow 自动生成
-            for (const rp of (result.retry_prompts || [])) {
-              console.log(`\n🔄 重试提示（项目 ${pName}）：\n`)
-              console.log(rp.prompt)
-            }
-          }
-          const saved = saveWorkflowRun(result, {
-            cwd,
-            source: 'run.js',
-            stage: 'scan',
-            step: steps[currentIdx]?.name,
-            ...(platformOpts.runtimeRoot ? { runtimeRoot: platformOpts.runtimeRoot } : {}),
-            ...(platformOpts.scanRunId ? { scanRunId: platformOpts.scanRunId } : {})
-          })
-          if (saved) console.log(`📁 结果已归档：${saved}`)
-        }
-        if (anyFailed) {
-          console.log(`\n⚠️ 存在检查失败项，请按上面的重试提示修复后再继续。`)
-          // task-07: 阻断推进（与 task-06 平台模式 scan-postcheck 失败分支 return 结构对齐）
-          // scan 深度扫描产物校验未通过时，不允许 clean success / 进入下一 step，
-          // 让上层走"完成但不推进"分支，--done 被拒。
-          return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
-        }
-      }
-    } catch (e) {
-      console.warn(`⚠️ workflow 检查跳过：${e.message}`)
-    }
-  }
-
-  // Workflow post_check：archive extract-module-impact 完成后检查产物
-  if (stageName === 'archive' && steps[currentIdx]?.name?.includes('extract-module-impact')) {
-    try {
-      const { loadWorkflow, runPostCheck, formatCheckReport, saveWorkflowRun } = await import('../workflow.js')
-      const wf = loadWorkflow(cwd, 'archive-impact')
-      if (wf && changeName) {
-        const raw = JSON.stringify(wf)
-        const resolved = JSON.parse(raw.replace(/<change-name>/g, changeName))
-        const result = runPostCheck(resolved, cwd, progress.project || basename(cwd), {}, specBase)
-        // 只报告 impact-analyzer 的结果（doc-syncer 是后续步骤）
-        const impactResult = (result.roles || []).find(r => r.id === 'impact-analyzer')
-        if (impactResult) {
-          const icon = impactResult.status === 'pass' ? '✅' : '❌'
-          console.log(`${icon} module-impact.md 检查${impactResult.status === 'pass' ? '通过' : '失败'}`)
-          for (const f of (result.failures || []).filter(f => f.role_id === 'impact-analyzer')) {
-            // f 是 {level,role_id,output,check,message} 对象——直接 ${f} 打印裸 [object Object]（ql-20260819-006）；
-            // message 才是人类可读 detail（如「缺少章节: …」），缺字段时 stringify 兜底防再退化成不可诊断输出
-            console.log(`   └─ ${f.message ?? JSON.stringify(f)}`)
-          }
-        }
-        const saved = saveWorkflowRun(result, {
-          cwd,
-          source: 'run.js',
-          stage: 'archive',
-          step: steps[currentIdx]?.name,
-          ...(platformOpts.runtimeRoot ? { runtimeRoot: platformOpts.runtimeRoot } : {}),
-          ...(platformOpts.scanRunId ? { scanRunId: platformOpts.scanRunId } : {})
-        })
-        if (saved) console.log(`📁 结果已归档：${saved}`)
-      }
-    } catch (e) {
-      console.warn(`⚠️ workflow 检查跳过：${e.message}`)
-    }
-  }
-  return null
-}
-/**
- * quick 阶段完成收尾（W6 Step6b 从 completeStep 内联块抽出）：
- * 强校验 QUICKLOG 条目 + 审计（auditQuickCompletion）+ 结果摘要结构校验 + 翻状态/勾 tasks.md
- * （CLI 接管 QUICKLOG 分配/写入/收尾）。blocked → process.exit(1)（无 early-return，调用点纯 await）。
- *
- * ctx：stageName/steps/currentIdx/cwd/progress/changeName/specBase/outputText/confirm/
- * isForceBaseline/isAllowNew/platformOpts。辅助函数直接 import（safeGit/auditQuickCompletion ← shared，
- * printQuickAuditReview ← quick-audit，4 个 quicklog fns ← quicklog，unlinkSync/rmSync ← fs 静态）。
- */
-export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm }) {
-  // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
-  if (stageName === 'quick') {
-    // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
-    // D-003@v1：progress._write 不持久化顶层 quickGuard，跨进程 --done 时读出的 progress 无 quickGuard，
-    // 若仍用 if (progress.quickGuard) 驱动收尾会整体跳过，导致 .runtime/quick-sessions/<sessionId>/ 残留僵尸。
-    // 改为从文件读 guard：优先 session 目录 guard.json，回退旧单文件 quick-guard.json（task-03 前兼容）。
-    // sessionId == changeName == quick-<uuid8>（completeStep 作用域内 changeName 已解构自 options）。
-    // session 目录经 resolveQuickSessionsDir 单一解析（multi-agent-review Q4）：与 stage.js 写入路径对齐，
-    // 平台模式 runtimeRoot 与 specBase/.runtime 不同时不再读不到 guard。
-    const sessionGuardFile = join(resolveQuickSessionsDir(platformOpts, specBase), changeName, 'guard.json')
-    const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
-    let guard = null
-    try {
-      guard = existsSync(sessionGuardFile)
-        ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
-        : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
-    } catch {}
-
-    // 强校验 / 收尾：本会话必须有一条真实 QUICKLOG 条目（治「报 SAFE 但漏写」bug）。
-    // guard 缺失（brownfield：新代码前启动的会话）不阻断——兜底补写一条记录，保住「完成必有记录」不变量。
-    const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
-    let qlId = guard?.quicklogId || null
-    const linkedChanges = Array.isArray(guard?.linkedChanges) ? guard.linkedChanges : []
-    // 审计结果（仅 guard 存在时填充）。提到 if(guard) 外声明，供下方回填 QUICKLOG 文件行复用
-    // review.changedFiles；brownfield 无 guard 时保持 null → 文件行不回填（降级，不报错）。
-    let review = null
-
-    // 审计：仅在有 guard 时跑（brownfield 无 guard 跳过，兼容 D-003 brownfield 行为）。
-    // task-02：mergedGuard 提升到 if 外声明，供下方并发预检钩子复用与 auditQuickCompletion
-    // 同源的 guard 字段（baselineFiles/linkedChanges）。brownfield 无 guard 时保持 null，
-    // 钩子 ownFiles/linkedChanges 走 ?? [] 兜底（D-003 不抛 TypeError）。
-    let mergedGuard = null
-    if (guard) {
-      // --done 的 --force-baseline/--allow-new 并入 guard（与 step1 持久化值取或）。
-      // 修复 ql-20260713-002-7628：旧代码解析了这两个 flag 但只传 {isConfirm} 给审计，
-      // 致 --done --force-baseline 静默无效、用户被误导「重跑 --confirm」也无法解锁。
-      mergedGuard = {
-        ...guard,
-        forceBaseline: guard.forceBaseline || isForceBaseline,
-        allowNew: guard.allowNew || isAllowNew,
-        allowDelete: guard.allowDelete || isAllowDelete,
-        // O-1（docs-signals-o12）：specBase/projectName 透传给审计——docSyncHint 模块归属用
-        // （平台模式 resolveSpecDir(cwd) 会 miss specRoot 静默丢信号，plan 审查 gap-5）
-        specBase,
-        projectName: progress?.project || null,
-        // 他者 active 会话声明索引（坑 foreign-session-declared-false-block）：多 agent 并发时
-        // 并行会话 --files 声明的文件退栈归该会话审计，不再误拦本会话。与上方 guard 读取同源
-        // （resolveQuickSessionsDir 同参，平台模式 runtimeRoot 对齐）；fail-open：采集失败 → 空
-        // → 回到无豁免现状。
-        otherSessionsDeclared: collectOtherQuickSessionDeclarations(platformOpts, specBase, changeName),
-      }
-      review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
-      printQuickAuditReview(review)
-      if (review.status === 'blocked') {
-        steps[currentIdx].status = 'pending'
-        steps[currentIdx].completedAt = null
-        if (outputText) steps[currentIdx].output = null
-        process.exit(1)
-      }
-      progress.lastQuickReview = review
-    }
-
-    // task-02 并发预检（FR-05/FR-07，纯副作用 advisory）：auditQuickCompletion 返回后、推进前
-    // 扫工作树，识别他者未提交改动 / 他者脏变更目录，有则 console.warn。不改 status/gate、
-    // 不 exit、不 return early（FR-07 铁律）。ownFiles 必含 baselineFiles（D-001：脏工作树 quick
-    // 完成时本会话 baseline 不被他者误报）；review/mergedGuard 均可能为 null（brownfield 无 guard，
-    // D-003），用 ?. + ?? [] 兜底防 spread undefined 抛 TypeError（B-005）。整钩子 try/catch 隔离
-    // ——detect 本就 fail-open，保守再包一层，任何异常只吞不 bubble，主完成流程不受影响。
-    try {
-      // ownFiles 锚点（2026-08-18 误归属修复）：声明会话 = baselineFiles ∪ allowedFiles（声明即归属），
-      // 不再用 changedFiles 全量——他者窗口文件已被污染进 changedFiles，旧口径自吞致预检对
-      // ql-20260818-003 形态结构性失明。未声明会话维持旧口径（changed ∪ baseline）：无声明无归属
-      // 信息，收窄锚点会把自身未声明改动全误报他者。resolveConcurrentAnchor 纯函数（concurrent-detect）。
-      const ownFiles = resolveConcurrentAnchor({
-        changedFiles: review?.changedFiles ?? [],
-        baselineFiles: mergedGuard?.baselineFiles ?? [],
-        allowedFiles: mergedGuard?.allowedFiles ?? [],
-      })
-      const detected = detectConcurrentChanges(cwd, {
-        changeName,
-        linkedChanges: mergedGuard?.linkedChanges ?? [],
-        ownFiles,
-      })
-      const warn = formatConcurrentWarning(detected)
-      if (warn) console.warn(warn)
-    } catch (e) {
-      // fail-open：并发预检异常绝不阻断主完成流程（FR-07）。
-    }
-
-    // 结果摘要结构校验（最后一步、isDone 且带了 --output 时）：--output 是 QUICKLOG「结果：」
-    // 归档的唯一来源，要求按 需求/根因/方案/结果 模板给全（见 stages/quick.js step3 prompt）。
-    // 确定性校验：只查必填字段是否齐全，不判内容质量。缺字段 → 本次不完成（回滚 step 状态 +
-    // exit 1），保留「进行中」条目，agent 补全 --output 后重跑 --done 即可，不丢进度。
-    // 仅 completeQuicklogEntry 会实际持久化时才校验；前两个 step 的 --done output 不入 QUICKLOG，不校验。
-    // Q6：quick 末步 --done 必须带 --output（四字段结果是 QUICKLOG「结果：」唯一来源）。缺则回退 pending +
-    // exit(1)，不静默落空结果条目（原 if(outputText) 守卫致 outputText 为空时跳过校验，completeQuicklogEntry
-    // 又用 outputText||'' 兜底 → 结果块为空却翻「已完成」）。handleQuickStageCompletion 仅在阶段完成（=末步）时触发。
-    const isLastStep = currentIdx === steps.length - 1
-    if (isLastStep && !outputText) {
-      console.error('\n❌ quick 最后一步 --done 必须带 --output（四字段结果模板）。')
-      console.error('   --output 是 QUICKLOG「结果：」归档的唯一来源。补全后重跑 --done（不丢进度），推荐四参数形式（CLI 自动合成，无嵌套冒号事故面）：')
-      console.error('     sillyspec run quick --done --change <changeName> --req "一句话语义化短标题" --cause "为什么这样改" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"')
-      console.error('   兼容旧形式：--output "需求：… 根因：… 方案：… 结果：…"')
-      steps[currentIdx].status = 'pending'
-      steps[currentIdx].completedAt = null
-      process.exit(1)
-    }
-    if (outputText) {
-      const resultCheck = validateQuickResult(outputText)
-      if (!resultCheck.ok) {
-        console.error('\n' + getRule('quick.result-labels').failMessage.replaceAll('${missing}', resultCheck.missing.join('、')))
-        console.error(`   --output 是 QUICKLOG「结果：」归档的唯一来源，四个标签必须放在 --output 里（不是 --input）。`)
-        console.error(`   补全后重跑 --done（不丢进度）。推荐四参数形式（CLI 自动合成结构化模板，避免旧形式嵌套全角冒号被拆分判定缺字段）：`)
-        console.error(`     sillyspec run quick --done --change <changeName> --req "一句话语义化短标题（即 QUICKLOG 条目标题）" --cause "为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"`)
-        console.error(`   或照抄旧形式模板：`)
-        console.error(`     sillyspec run quick --done --change <changeName> --output "需求：用户/任务要什么`)
-        console.error(`     根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
-        console.error(`     方案：怎么改的`)
-        console.error(`     结果：验证情况（测试数 / lint / typecheck / 部署状态）"`)
-        steps[currentIdx].status = 'pending'
-        steps[currentIdx].completedAt = null
-        if (outputText) steps[currentIdx].output = null
-        process.exit(1)
-      }
-    }
-
-    if (!qlId) {
-      // 无 ql-ID（guard 缺失或 brownfield 无 quicklogId）：补分配后立即完成，不阻断。
-      try {
-        const alloc = await allocateQuicklogEntry(specBase, gitUser, {
-          description: guard?.taskDescription || '(补分配)',
-          linkedChanges,
-          allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
-        })
-        qlId = alloc.qlId
-        console.log(`📝 QUICKLOG 兜底补写: ${qlId}（guard 缺失/brownfield 会话）`)
-      } catch (e) {
-        console.error(`\n❌ QUICKLOG 补分配失败: ${e.message}`)
-        steps[currentIdx].status = 'pending'
-        steps[currentIdx].completedAt = null
-        if (outputText) steps[currentIdx].output = null
-        process.exit(1)
-      }
-    }
-    if (!findQuicklogEntry(specBase, gitUser, qlId)) {
-      console.error(`\n❌ quick 阶段完成校验失败：QUICKLOG 条目 ${qlId} 不存在。`)
-      console.error(`   会话期间记录被删除或从未写入。请检查 .sillyspec/quicklog/ 后重跑 --done。`)
-      steps[currentIdx].status = 'pending'
-      steps[currentIdx].completedAt = null
-      if (outputText) steps[currentIdx].output = null
-      process.exit(1)
-    }
-    // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
-    // resultText 不再截断：结构化结果块（需求/根因/方案/结果）完整落盘，多行写成字段化块。
-    try {
-      // 回填实际改动文件：review.changedFiles 含 quick 自身元数据（quicklog/.runtime/modules 等），
-      // 用 isQuickMetadata 过滤掉，只留真实业务文件。brownfield 无 review → 空数组，文件行不动。
-      // 归属口径（2026-08-18 误归属修复）：声明会话优先 attributedFiles（窗口∩声明∪同文件并发命中），
-      // 他者窗口文件不进文件行；未声明会话/旧 review 无 attributedFiles → 兜底 changedFiles 全量。
-      const auditFiles = Array.isArray(review?.attributedFiles)
-        ? review.attributedFiles
-        : (Array.isArray(review?.changedFiles) ? review.changedFiles : [])
-      const realFiles = auditFiles.filter(f => !isQuickMetadata(f, linkedChanges))
-      // D-8 落盘（2026-08-18 修）：advisory 欠账信号从「纯打印」升级为「随条目落盘」——修复
-      // 「欠账已记录（QUICKLOG reasons）」的不实承诺（交叉审查实证 reasons 纯 stdout，事后不可审计）。
-      // 两周实测（2026-08-31 裁决，doc-consistency-debt §七）需要分母：信号触发次数必须可追溯。
-      const auditNotes = []
-      if (review?.docSyncHint && review.docSyncHint.touchedSource > 0 && review.docSyncHint.docFiles.length === 0) {
-        const mods = Array.isArray(review.docSyncHint.modules) && review.docSyncHint.modules.length > 0
-          ? `（涉及模块：${review.docSyncHint.modules.map((m) => m.id).join(' · ')}）` : ''
-        auditNotes.push(`📝 文档欠账（D-8）：${review.docSyncHint.touchedSource} 个源码文件改动未同步任何模块文档${mods}`)
-      }
-      if (review?.docsCheckHint && review.docsCheckHint.invalid > 0) {
-        auditNotes.push(`📎 文档引用失效：${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处 file:line 失效（sillyspec docs check 可复现）`)
-      }
-      // 归属切分注（2026-08-18 误归属修复）：窗口内未声明脏文件不进「文件：」行，但必须落盘可追溯
-      // （多 agent 并发仓他者窗口改动 / 本会话漏声明均可能），防真实改动被静默挤走。
-      if (Array.isArray(review?.undeclaredFiles) && review.undeclaredFiles.length > 0) {
-        const undeclared = review.undeclaredFiles.filter(f => !isQuickMetadata(f, linkedChanges))
-        if (undeclared.length > 0) {
-          auditNotes.push(`⚖️ 归属切分：${undeclared.length} 个窗口内未声明脏文件未计入文件行（并行会话改动或本会话漏声明）：${undeclared.join(', ')}`)
-        }
-      }
-      await completeQuicklogEntry(specBase, gitUser, qlId, {
-        resultText: outputText || '',
-        linkedChanges,
-        changedFiles: realFiles,
-        auditNotes,
-      })
-      console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
-      // 刷新 DB title：从 step3「需求：」提取（agent 可改 title 的途径），覆盖启动时的兜底快照。
-      // 与 QUICKLOG 标题刷新（flipEntryInContent 内 extractTitleFromResult）同源，保持 DB↔QUICKLOG 一致。
-      try {
-        const refinedTitle = extractTitleFromResult(outputText || '');
-        if (refinedTitle) pm.updateChangeMeta(cwd, changeName, { title: refinedTitle });
-      } catch { /* title 刷新失败不阻断完成 */ }
-    } catch (e) {
-      console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
-    }
-
-    // 轻量归档任务已全勾选的关联真实变更
-    try {
-      const closeResult = await closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges, platformOpts })
-      if (closeResult.closed.length > 0) {
-        console.log(`📦 已自动归档 ${closeResult.closed.length} 个关联变更：${closeResult.closed.join(', ')}`)
-      }
-      if (closeResult.skipped.length > 0) {
-        for (const s of closeResult.skipped) {
-          console.log(`⏭️ 关联变更 ${s.name} 未归档：${s.reason}`)
-        }
-      }
-    } catch (e) {
-      console.warn(`⚠️ 关联变更轻量归档失败（不阻断 quick 完成）: ${e.message}`)
-    }
-
-    // 清理 session 目录（rmSync/unlinkSync 容忍不存在）。路径与写入对齐（Q4 resolveQuickSessionsDir）。
-    try {
-      if (changeName) {
-        const sessionDir = join(resolveQuickSessionsDir(platformOpts, specBase), changeName)
-        rmSync(sessionDir, { recursive: true, force: true })
-      }
-      if (existsSync(legacyGuardFile)) unlinkSync(legacyGuardFile)
-    } catch {}
-
-    // 注销 quick 会话注册的 changes 行（quick-<uuid8>），避免 active 行随每次 quick 单调累积污染
-    // listChanges / doctor / resolveQuickLinkedChanges（multi-agent-review Q1）。quick 是收尾型会话，
-    // 不走 archive，旧代码从不调 unregisterChange → DB 里 active 的 quick-<hex> 行只增不减。
-    // 仅对 quick-<8hex> sessionId 注销——非 sessionId 形态的变更名是旧兼容路径/真实关联变更，
-    // 误注销会把用户真实变更标 archived（与 command.js:569 sessionId 守卫同形正则）。
-    if (changeName && /^quick-[0-9a-f]{8}$/.test(changeName)) {
-      try {
-        pm.unregisterChange(cwd, changeName)
-      } catch (e) {
-        console.warn(`⚠️ 注销 quick 会话 changes 行失败（不阻断完成）: ${e.message}`)
-      }
-    }
-  }
-
-  return null
-}
-
-/**
- * 判定变更 tasks.md 是否全部勾选完成。
- * 无 tasks.md 或有未勾选项均返回 false（保守策略）。
- *
- * @param {string} specBase - .sillyspec 根目录
- * @param {string} changeName - 变更名
- * @returns {boolean}
- */
-function isChangeTasksComplete(specBase, changeName) {
-  const tasksPath = join(specBase, 'changes', changeName, 'tasks.md')
-  if (!existsSync(tasksPath)) return false
-  try {
-    const content = readFileSync(tasksPath, 'utf8').replace(/\r\n/g, '\n')
-    return !/^-\s*\[\s*\]\s+/m.test(content)
-  } catch {
-    return false
-  }
-}
-
-/**
- * 对单个已完成的关联真实变更执行轻量归档（不校验 plan.md/module-impact.md）。
- *
- * @param {Object} opts
- * @param {ProgressManager} opts.pm
- * @param {string} opts.cwd
- * @param {string} opts.specBase
- * @param {string} opts.changeName
- * @param {Object} [opts.platformOpts]
- * @returns {Promise<{closed:boolean, destDir?:string, reason?:string}>}
- */
-async function closeSingleQuickLinkedChange({ pm, cwd, specBase, changeName, platformOpts = {} }) {
-  const srcDir = join(specBase, 'changes', changeName)
-  if (!existsSync(srcDir)) {
-    return { closed: false, reason: '源目录不存在' }
-  }
-  const changesDir = join(specBase, 'changes')
-  const archiveDir = join(changesDir, 'archive')
-  const date = new Date().toISOString().slice(0, 10)
-  const destName = archiveDestDirName(date, changeName)
-  const destDir = join(archiveDir, destName)
-
-  // 幂等：目标目录已存在或已在 archive/ 中
-  if (existsSync(destDir) || findAlreadyArchivedDir(archiveDir, changeName)) {
-    return { closed: false, reason: `目标目录已存在（${destName}）` }
-  }
-
-  mkdirSync(archiveDir, { recursive: true })
-  try {
-    renameSyncRetry(srcDir, destDir)
-  } catch (e) {
-    return { closed: false, reason: `移动目录失败：${e.message}` }
-  }
-
-  // 终态一致化同标准归档（坑 manual-archive-desync-status-only）：轻量归档路径不能只翻 status
-  pm.unregisterChange(cwd, changeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
-  await archiveWorktreeCleanup(cwd, changeName, specBase, platformOpts)
-  safeGit(cwd, ['add', '--', `.sillyspec/changes/archive/${destName}/`])
-
-  console.log(`📦 关联变更已自动归档：${changeName} → archive/${destName}/`)
-  return { closed: true, destDir }
-}
-
-/**
- * quick 轻量归档的阶段闸允许集：仅「从未进入完整流程」的变更可被 quick --done 自动归档
- * （d192f89 原始场景：评估 small 转 quick、停在 brainstorm 的僵尸变更）。execute 完成后
- * tasks.md 必然全勾选而流程未收尾——不看 current_stage 会把 verify/中途的完整流程变更
- * 绕过 verify/archive 校验直接归档注销（quick-close-midflight 缺陷）。
- *
- * 阶段名允许集之外还有「阶段完成态」闸（ql-20260819-010，quick-done-autoarchive-misfire
- * 缺陷①）：current_stage=brainstorm 但该阶段 status=completed（brainstorm 收尾到 plan
- * 开始之间的空窗）≠ 僵尸变更——此时关联 quick --done 会把即将进 plan 的进行中变更误
- * 轻量归档。stage_status=completed 一律走原流程收尾。
- */
-const QUICK_CLOSE_ALLOWED_STAGES = new Set(['', 'scan', 'brainstorm'])
-
-/**
- * quick --done 完成后，自动关闭任务已全部完成的关联真实变更。
- * quick-<hex> sessionId 自身不在此处理（由调用方单独注销）。
- * 单个归档失败 catch warn，不阻断 quick 完成。
- *
- * 阶段闸（fail-closed）：先查 changes.current_stage——无 DB 记录（未注册目录桩）或停在
- * scan/brainstorm 才继续 tasks 判定；plan/execute/verify/archive 一律 skip 走原流程收尾。
- * pm 缺 getChangeStage 接口或查询抛错同样 skip，不静默放行。
- *
- * @param {Object} opts
- * @param {ProgressManager} opts.pm
- * @param {string} opts.cwd
- * @param {string} opts.specBase
- * @param {string[]} [opts.linkedChanges]
- * @param {Object} [opts.platformOpts]
- * @returns {Promise<{closed:string[], skipped:{name:string,reason:string}[]}>}
- */
-export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges = [], platformOpts = {} }) {
-  const closed = []
-  const skipped = []
-  // 只处理真实变更，跳过 quick 会话 sessionId
-  const realChanges = linkedChanges.filter((name) => !/^quick-[0-9a-f]{8}$/.test(name))
-  for (const changeName of realChanges) {
-    try {
-      if (typeof pm.getChangeStage !== 'function') {
-        skipped.push({ name: changeName, reason: '进度库接口缺失（getChangeStage），无法判定流程阶段，不自动归档' })
-        continue
-      }
-      const stageInfo = pm.getChangeStage(cwd, changeName)
-      if (stageInfo !== null && !QUICK_CLOSE_ALLOWED_STAGES.has(stageInfo.current_stage || '')) {
-        skipped.push({
-          name: changeName,
-          reason: `变更处于完整流程「${stageInfo.current_stage}」阶段（tasks.md 全勾不等于流程收尾），不自动归档——请走原流程收尾（sillyspec progress show 查看进度）`,
-        })
-        continue
-      }
-      // ql-20260819-010（quick-done-autoarchive-misfire 缺陷①）：当前阶段已完成 ≠
-      // 从未进入完整流程的僵尸。brainstorm 收尾到 plan 开始之间的空窗里 current_stage
-      // 仍读 brainstorm，只看阶段名会把即将进 plan 的变更误轻量归档（propose 骨架
-      // tasks.md 除 quick 追加的 ql 行外没有任务行，「无未勾选框=全勾」恒真）。
-      // stage_status=completed 一律原流程收尾；null（无阶段行/brownfield）与旧调用方
-      // mock 缺字段（undefined）均按未完成放行，僵尸逃生通道行为不变。
-      if (stageInfo !== null && stageInfo.stage_status === 'completed') {
-        skipped.push({
-          name: changeName,
-          reason: `变更当前阶段「${stageInfo.current_stage || '(空)'}」已完成（推进/收尾中，非僵尸变更），不自动归档——请走原流程收尾（sillyspec progress show 查看进度）`,
-        })
-        continue
-      }
-      if (!isChangeTasksComplete(specBase, changeName)) {
-        skipped.push({ name: changeName, reason: 'tasks.md 未全勾选或不存在' })
-        continue
-      }
-      const result = await closeSingleQuickLinkedChange({ pm, cwd, specBase, changeName, platformOpts })
-      if (result.closed) {
-        closed.push(changeName)
-      } else {
-        skipped.push({ name: changeName, reason: result.reason || '未知原因' })
-      }
-    } catch (e) {
-      console.warn(`⚠️ 关联变更 ${changeName} 轻量归档失败（不阻断 quick 完成）: ${e.message}`)
-      skipped.push({ name: changeName, reason: e.message })
-    }
-  }
-  return { closed, skipped }
-}
-
-/**
- * execute「Wave N 执行」步骤完成后扫 worktree 提取 provider endpoint artifact（W6 Step6c 从
- * completeStep 内联块抽出）。供 verify 阶段 parity 对账 + consumer task 上游契约注入。
- * 接线自 contract-matrix pipeline。step 级（每个 Wave 执行步骤后跑），无 early-return（try/catch warn）。
- *
- * ctx：stageName/steps/currentIdx/changeName/specBase/cwd。extractArtifactsForChange ← 动态 ../contract-matrix.js，
- * WorktreeManager ← 动态 ../worktree.js（真环依赖保留动态）。
- */
-export async function handleExecuteWaveArtifact({ stageName, steps, currentIdx, changeName, specBase, cwd }) {
-  if (stageName === 'execute' && /^Wave \d+ 执行$/.test(steps[currentIdx]?.name || '')) {
-    try {
-      const { extractArtifactsForChange } = await import('../contract-matrix.js')
-      let worktreePath = null
-      try {
-        const { WorktreeManager } = await import('../worktree.js')
-        const meta = new WorktreeManager({ cwd }).getMeta(changeName)
-        if (meta?.worktreePath && existsSync(meta.worktreePath)) worktreePath = meta.worktreePath
-      } catch {}
-      const msg = extractArtifactsForChange({ changeDir: join(specBase, 'changes', changeName), specBase, changeName, worktreePath })
-      if (msg) console.log(msg)
-    } catch (e) { console.warn(`⚠️ 契约 artifact 提取跳过: ${e?.message || e}`) }
-  }
-  return null
-}
-
-/**
- * 聚合最新 execute run 各 task review.json 的 changedFiles（主仓 repo 过滤）。
- *
- * 复用 resolveLatestExecuteRunIdWithTasks（task-review.js:684，规避 marker 漂移）+ readReview。
- * 仅主仓 repo（review.repo 缺省或 'main'）的 changedFiles 参与主仓核验；跨仓 repo 的 task 文件
- * 由跨仓仓独立落地，不在主仓 worktree/分支，混入会误报 missing（Grill M11）。
- *
- * @param {{ runtimeRoot: string, changeName: string }} opts
- * @returns {Promise<string[]>} 主仓 changedFiles 聚合（去重保序）；无 run / 无 tasks / 读取失败 → []
- */
-export async function collectExecuteChangedFiles({ runtimeRoot, changeName }) {
-  if (!runtimeRoot || !changeName) return []
-  const { resolveLatestExecuteRunIdWithTasks, readReview, normalizeRepoKey } = await import('../task-review.js')
-  // changeName 透传：run 解析按 change 戳优先归属（坑 worktree-cleanup-marker-chain），
-  // 避免 marker 断裂后聚合到其他变更 run 的 changedFiles 误报 missing
-  const runId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName })
-  if (!runId) return []
-  const tasksDir = join(runtimeRoot, 'execute-runs', runId, 'tasks')
-  if (!existsSync(tasksDir)) return []
-  let taskIds
-  try {
-    taskIds = readdirSync(tasksDir)
-  } catch {
-    return []
-  }
-  const files = []
-  for (const taskId of taskIds) {
-    const r = readReview(join(tasksDir, taskId, 'review.json'))
-    if (!r.ok || !r.review) continue
-    // 跨仓 repo 过滤：仅主仓（repo 缺省视 'main'）参与主仓核验，避免误报
-    if (normalizeRepoKey(r.review.repo) !== 'main') continue
-    if (Array.isArray(r.review.changedFiles)) {
-      for (const f of r.review.changedFiles) {
-        // 交付物过滤（与 worktree.js hasUnappliedChanges isDeliverable 同口径）：.sillyspec/ 蓝图/
-        // runtime 产物与 meta.json 不参与落盘核验——它们随主仓/并行 session 维护，不在 worktree 分支，
-        // 混入会误报 missing
-        if (typeof f !== 'string' || f.trim() === '') continue
-        if (f.startsWith('.sillyspec/') || f === 'meta.json') continue
-        files.push(f)
-      }
-    }
-  }
-  return [...new Set(files)]
-}
-
-/**
- * execute 阶段级核验（防空跑谎报，D-002@v1 / FR-04/05/06）：聚合最新 execute run 各 task review 声称的
- * 交付文件，用 findMissingDeliverables 核验其存在于 worktree 分支 tree 或 worktree 工作区。
- *
- * - missing 文件 → console.warn 列清单，提示"apply 将无源可复制"（宽松非阻断，不 exit 不 throw）。
- * - checked:false（worktree 目录 / 分支不存在）→ 保守提示"无法核验，请人工确认"。
- * - 与 Task Review Gate 既有校验（零改动伪造 / 不相交伪造，task-review.js:590-623）互补不重复拦截：
- *   本核验的真实增量窗口是「review 通过后文件被删且未 commit」+「无法核验时给人工确认提示」。
- *
- * 由 handleExecuteWorktreeCleanup 开头调用：核验发生在 worktree cleanup 之前，目录被清前先判定
- * 交付文件是否落盘。整个钩子 try/catch 兜底——任何异常只 warn，绝不影响 execute 完成（FR-07）。
- *
- * ctx：stageName/changeName/cwd。WorktreeManager + findMissingDeliverables ← 动态 ../worktree.js；
- * task-review 读取 ← 动态 ../task-review.js。runtimeRoot 用本地 specBase 解析（无 platformOpts 传入
- * 时平台 runtimeRoot 不在本函数作用域，降级为本仓 .runtime，读不到 review 则跳过，零误报）。
- */
-export async function handleExecuteDeliverableCheck({ stageName, changeName, cwd }) {
-  if (stageName !== 'execute' || !changeName) return null
-  try {
-    const { WorktreeManager, findMissingDeliverables } = await import('../worktree.js')
-    const wm = new WorktreeManager({ cwd })
-    const meta = wm.getMeta(changeName)
-    if (!meta) return null // 无 worktree meta（非 worktree execute / 已清），无需核验
-    const specBase = join(cwd, '.sillyspec')
-    const runtimeRoot = resolveRuntimeRoot({}, specBase)
-    const changedFiles = await collectExecuteChangedFiles({ runtimeRoot, changeName })
-    if (changedFiles.length === 0) return null
-    const { missing, checked } = findMissingDeliverables({
-      worktreePath: meta.worktreePath,
-      branch: meta.branch,
-      changedFiles,
-    })
-    if (!checked) {
-      console.warn('⚠️ execute 阶段级核验：无法核验（worktree 目录或分支不存在），请人工确认交付文件已落盘。')
-      return null
-    }
-    if (missing.length > 0) {
-      console.warn(`⚠️ execute 阶段级核验：以下 ${missing.length} 个声称实现的交付文件既不在分支也不在工作区，疑似空跑/从未落盘：`)
-      for (const f of missing) console.warn(`   ${f}`)
-      console.warn('   请检查子代理是否真实实现，或先 commit 到分支；apply 将无源可复制。')
-    }
-  } catch (e) {
-    console.warn(`⚠️ execute 阶段级核验跳过: ${e?.message || e}`)
-  }
-  return null
-}
-
-/**
- * execute 阶段完成时条件性清理 worktree（W6 Step6c 从 completeStep 完成路径内联块抽出）。
- * 不依赖 AI agent 的完成确认步骤：有未 apply 变更 → 保留 worktree；否则 cleanup（含 in-place 安全清理）。
- * stage 级（execute 阶段全部完成时跑），无 early-return（try/catch warn）。
- *
- * ctx：stageName/changeName/cwd。WorktreeManager ← 动态 ../worktree.js。
- */
-export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd }) {
-  // 阶段级核验（D-002@v1，防空跑谎报）：cleanup 之前判定 review 声称实现的交付文件是否落盘。
-  // 宽松非阻断：缺失 warn / 无法核验保守提示 / 异常只 warn，均不影响下方 cleanup 与 execute 完成。
-  await handleExecuteDeliverableCheck({ stageName, changeName, cwd })
-  if (stageName === 'execute' && changeName) {
-    try {
-      const { WorktreeManager } = await import('../worktree.js');
-      const wm = new WorktreeManager({ cwd });
-      const meta = wm.getMeta(changeName);
-      if (!meta) {
-        console.log('🔗 Worktree: n/a (no meta)');
-      } else if (meta.mode === 'native-worktree') {
-        console.log('🔗 Worktree: kept (外部隔离环境)');
-      } else {
-        // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）。
-        // 主仓互斥锁（坑 main-repo-no-mutex 二批）：检查+清理与并行会话的 apply/cleanup 互斥
-        // （防 TOCTOU：检查时他者正在 apply → 判定漂移）。best-effort：锁超时不阻断 execute
-        // 完成，降级为保留 worktree + 手动清理指引。
-        try {
-          const { withMainRepoLock } = await import('../worktree-apply.js')
-          const cleanResult = await withMainRepoLock(cwd, changeName, 'execute-cleanup', () => {
-            const check = wm.hasUnappliedChanges(changeName);
-            if (check.hasChanges) {
-              return { kept: true, check }
-            }
-            return { kept: false, result: wm.cleanup(changeName) }
-          })
-          if (cleanResult.kept) {
-            console.log(`🔗 Worktree: pending apply (${cleanResult.check.changedFiles.length} 个未应用变更)`);
-            console.log(`   下一步: sillyspec worktree apply ${changeName}`);
-          } else {
-            console.log(`🔗 Worktree: ${cleanResult.result.result}`);
-            if (cleanResult.result.residual?.length > 0) {
-              console.warn(`   ⚠️ 清理残留: ${cleanResult.result.residual.join('; ')}`);
-              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
-            } else if (cleanResult.result.details?.length > 0) {
-              for (const d of cleanResult.result.details) {
-                if (d.startsWith('⚠️')) console.log(`   ${d}`);
-              }
-            }
-          }
-        } catch (lockErr) {
-          if (/互斥锁被占用/.test(String(lockErr.message))) {
-            console.log(`🔗 Worktree 自动清理跳过（主仓互斥锁被他者会话持有）——稍后手动: sillyspec worktree cleanup ${changeName}`);
-          } else {
-            console.warn(`⚠️ worktree 清理异常（不阻断）: ${lockErr.message}`);
-          }
-        }
-      }
-    } catch (e) {
-      console.warn(`🔗 Worktree: check failed — ${e.message}`);
-    }
-  }
-  return null
-}
-/**
- * scan 阶段完成后处理（W6 Step6d 从 completeStep 完成路径内联块抽出）：
- *   - 平台模式（specRoot/runtimeRoot）：写 manifest.json + 跑 scan-postcheck + 结构化结果 +
- *     更新平台指针（SCAN_COMPLETED）+ failed_post_check 阻断（exit 1 / early-return）
- *   - 非平台模式：轻量 postcheck + 结构化结果写 .runtime/
- * 返回 early-return 对象（platform failed_post_check 非 exit 路径）由 completeStep 透传；null = 放行。
- *
- * ctx：stageName/currentIdx/cwd/progress/pm/stageData/changeName/outputText/platformOpts。
- * safeGit/triggerSync ← shared；writeAtomicSync ← fs-atomic；SCAN_STATUS/POINTER_STATUS ← constants；
- * mkdirSync/writeFileSync/readFileSync/unlinkSync/join ← 顶部静态；runScanPostCheck 等 ← 动态 ../scan-postcheck.js。
- *
- * 搬迁清理：删 4 个冗余动态 builtin import（fs/path/child_process，execSync 死代码）+ _readFileSync 别名改回 readFileSync。
- */
-export async function handleScanStageCompleted({ stageName, currentIdx, cwd, progress, pm, stageData, changeName, outputText, platformOpts }) {
-  // 平台模式：scan 完成后生成 manifest.json + post-check
-  if (stageName === 'scan' && (platformOpts.specRoot || platformOpts.runtimeRoot)) {
-    if (!platformOpts.specRoot) {
-      // 只传 runtimeRoot 无 specRoot（command.js 允许的组合）：manifest 无处落盘。
-      // 显式 fail-closed 报错——此前 mkdirSync(null) 抛 TypeError 被外层 catch 吞掉，
-      // postcheck/指针升级/阻断全部静默跳过，scan 失败也"干净成功"（体检 BUG-12）
-      console.error(`❌ 平台模式缺少 --spec-root，无法写 manifest.json（scan postcheck 中止）`)
-      stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false
-      stageData.scanMeta.manifestError = 'missing specRoot'
-      return
-    }
-    try {
-      stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false; // 默认失败
-      const manifestDir = platformOpts.specRoot
-      mkdirSync(manifestDir, { recursive: true })
-      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
-      }
-      const manifest = {
-        workspace_id: platformOpts.workspaceId || null,
-        scan_run_id: platformOpts.scanRunId || null,
-        source_root: cwd,
-        spec_root: platformOpts.specRoot || null,
-        runtime_root: platformOpts.runtimeRoot || null,
-        source_commit: sourceCommit,
-        source_commit_error: sourceCommit === null ? (sourceCommitError || 'unknown') : undefined,
-        generated_at: new Date().toISOString(),
-        schema_version: 1,
-        scan_profile: stageData.scanProfile
-          ? { mode: stageData.scanProfile.mode, reason: stageData.scanProfile.reason }
-          : null,
-        postcheck_result_path: null,
-        workflow_runs_dir: platformOpts.runtimeRoot
-          ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown', 'workflow-runs')
-          : null,
-        platform_pointer_path: join(cwd, '.sillyspec-platform.json'),
-        platform_pointer_status: POINTER_STATUS.ACTIVE,
-      }
-      const manifestPath = join(manifestDir, 'manifest.json')
-      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
-      console.log(`📄 manifest.json 已写入: ${manifestPath}`)
-      stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = true;
-      if (!sourceCommit) {
-        console.log(`⚠️  source_commit 无法获取（可能非 git 目录），已设为 null`)
-      }
-      // 清理平台参数临时文件
-      const platformOptsFile = join(manifestDir, '.runtime', 'platform-scan.json')
-      try { unlinkSync(platformOptsFile) } catch {}
-
-      // CLI 层 post-check（替代旧的简单检查）
-      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
-      const postResult = runScanPostCheck({
-        cwd,
-        specDir: platformOpts.specRoot,
-        outputText,
-        scanMeta: {
-          projectListParsed: stageData.scanMeta?.projectListParsed ?? null,
-          manifestWritten: stageData.scanMeta?.manifestWritten ?? null,
-        },
-        scanProfile: stageData.scanProfile || null,
-      })
-      printScanPostCheckResult(postResult)
-
-      // 生成结构化 JSON 并写入 runtime（供 SillyHub 消费）
-      const structured = formatStructuredResult(postResult, {
-        workspace_id: platformOpts.workspaceId,
-        scan_run_id: platformOpts.scanRunId,
-        source_root: cwd,
-        spec_root: platformOpts.specRoot,
-        runtime_root: platformOpts.runtimeRoot,
-      })
-      const postcheckJsonPath = writeStructuredResult(structured, platformOpts.specRoot, {
-        runtimeRoot: platformOpts.runtimeRoot,
-        scanRunId: platformOpts.scanRunId,
-      })
-      if (postcheckJsonPath) {
-        console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
-        manifest.postcheck_result_path = postcheckJsonPath
-      }
-
-      // 将 post-check 结果写入 manifest
-      manifest.scan_post_check = {
-        status: postResult.status,
-        checks: postResult.checks,
-      }
-      // 更新 manifest
-      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
-      console.log(`📄 manifest.json 已更新（含 post-check 结果）`)
-
-      // 更新平台指针状态为 scan_completed
-      const pointerPath = join(cwd, '.sillyspec-platform.json')
-      try {
-        const pointer = JSON.parse(readFileSync(pointerPath, 'utf8'))
-        pointer.status = POINTER_STATUS.SCAN_COMPLETED
-        pointer.completedAt = new Date().toISOString()
-        pointer.scanStatus = postResult.status
-        writeAtomicSync(pointerPath, JSON.stringify(pointer, null, 2) + '\n')
-      } catch (e) {
-        // 不阻断 scan 主流程，但暴露失败——pointer 写失败会让平台看不到 scan_completed，
-        // 与项目 fail-loud 原则一致：宁可可见地 warn，也不静默吞错。
-        console.warn(`⚠️ 更新平台指针状态失败（scan_completed 可能未落盘）: ${e.message}`)
-      }
-
-      // failed_post_check 时强制阻止 clean success
-      if (postResult.status === 'failed_post_check') {
-        stageData.status = SCAN_STATUS.FAILED_POST_CHECK
-        stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
-        pm._write(cwd, progress, changeName)
-        triggerSync(cwd, changeName, platformOpts)
-        console.error(`\n❌ scan post-check 失败，状态设为 failed_post_check。不允许 clean success。`)
-        console.error(`   请检查上方错误信息并修复后重新 scan。`)
-        // 平台模式：exit(1) 让 daemon/SillyHub 感知非 0 退出码（manifest.json 已落盘，不会被撤销）
-        if (platformOpts.specRoot || platformOpts.runtimeRoot) {
-          console.error('   平台模式：CLI 将以 exit code 1 退出，通知 SillyHub scan 失败。')
-          process.exit(1)
-        }
-        // 接口与 plan contract (run.js:2551 附近 plan 失败分支) 对齐：
-        // 返回 { stageCompleted:false, currentIdx, nextPendingIdx: currentIdx }
-        // 让上层 runStage 走"完成但不推进"分支，--done 被拒
-        return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
-      } else if (postResult.status === 'completed_with_warnings') {
-        // 警告不阻止完成，但记录
-        stageData.status = 'completed'
-        stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
-        pm._write(cwd, progress, changeName)
-      }
-    } catch (e) {
-      console.warn(`⚠️  manifest.json 写入失败: ${e.message}`)
-    }
-  }
-
-  // 非 platform 模式 scan 也做轻量 post-check + 结构化输出
-  if (stageName === 'scan' && !platformOpts.specRoot && !platformOpts.runtimeRoot) {
-    const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
-    const postResult = runScanPostCheck({ cwd, specDir: null, outputText, scanProfile: stageData.scanProfile || null })
-    printScanPostCheckResult(postResult)
-    // 结构化结果写入 .sillyspec/.runtime/
-    const structured = formatStructuredResult(postResult, { source_root: cwd })
-    const postcheckJsonPath = writeStructuredResult(structured, join(cwd, '.sillyspec'))
-    if (postcheckJsonPath) {
-      console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
-    }
-  }
-  return null
-}
-