sillyspec 3.27.12 → 3.28.0

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

@@ -1,584 +0,0 @@
-/**
- * run/stage.js（W6 Step8b 从 run.js 抽出）。
- *
- * `run <stage>` 默认路径的执行主干（runStage）+ 其私有 helper：
- *   - runStage：输出当前 step prompt（重 execute/scan/quick 启动期副作用——worktree 创建、
- *     executeRunId 固定、scanProfile 裁剪、quick baseline 录入、plan design 契约校验、noAI 步骤代理）
- *   - autoDetectChange：唯一变更目录时自动设置 currentChange（runStage 私有）
- *   - executePlanPostcheck：noAI planPostcheck 步骤代理（runStage 私有）
- *   - ensureDepsFreshness：execute 入口已存在 worktree 时 deps 自检重供给（runStage 私有）
- *
- * 安全锚：run.js 始终 barrel。runStage 由 run.js import 回来（无 test 直接 import，无需 re-export）。
- * checkApproval（runStage + runAutoMode 共用）已先下沉 shared.js（Step8a），避免 command/stage 环依赖。
- *
- * 路径修正（相对 src/run/）：
- *   - 动态 import './worktree.js' / './task-review.js' / './stages/plan.js' /
- *     './stages/plan-postcheck.js' / './worktree-deps.js' → '../'（src/ 下退一层）
- *   - 'child_process'（execSync）裸模块名不变
- */
-import { join, dirname } from 'node:path'
-import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs'
-import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown } from './shared.js'
-import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
-import { outputStep } from './prompt.js'
-import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
-import { createHash } from 'node:crypto'
-import { checkTransition } from '../stage-contract.js'
-import { AUXILIARY_STAGES } from '../constants.js'
-import { completeStageGates } from './gates.js'
-
-export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
-  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
-  // 状态转换校验
-  const prevStage = progress.currentStage || ''
-  // task-07: 提取 prevStage 的 stageData，传给 checkTransition 检测 failed_post_check 门控
-  const fromStageData = (progress.stages && prevStage && progress.stages[prevStage]) || undefined
-  const transition = checkTransition(prevStage, stageName, fromStageData ? { fromStageData } : {})
-  if (!transition.allowed) {
-    console.error(`❌ 阶段转换不允许: ${prevStage || '(起始)'} → ${stageName}`)
-    console.error(`   原因: ${transition.reason}`)
-    console.error(`   提示: 使用 --skip-approval 绕过（需明确意图）`)
-    if (!skipApproval) {
-      process.exit(1)
-    }
-  }
-
-  // execute 阶段启动前检查审批
-  if (stageName === 'execute' && !skipApproval) {
-    const approval = await checkApproval(cwd, changeName, platformOpts)
-    if (approval) {
-      if (approval.status === 'rejected') {
-        console.error(`❌ 变更 ${changeName} 的执行已被拒绝：${approval.reason || '无原因'}`)
-        process.exit(1)
-      }
-      if (approval.status === 'pending') {
-        console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
-        console.log('  提示：使用 --skip-approval 跳过审批检查')
-      }
-      // HUB-07：unknown（连接了平台但 404/断网/非 JSON）此前静默落空（fail-open 无提示）——
-      // 醒目警告 + 留痕，放行但可审计
-      if (approval.status === 'unknown') {
-        warnApprovalUnknown(cwd, changeName, approval.reason)
-      }
-    }
-  }
-
-  // execute 阶段：CLI 自动创建 worktree（不等 AI agent）
-  if (stageName === 'execute' && changeName) {
-    const effectiveChange = changeName
-    const { WorktreeManager } = await import('../worktree.js')
-    const wm = new WorktreeManager({ cwd })
-    const existingMeta = wm.getMeta(effectiveChange)
-    if (existingMeta) {
-      console.log(`🔗 worktree 已存在: ${existingMeta.worktreePath} (${existingMeta.mode})`)
-    } else {
-      try {
-        const result = wm.create(effectiveChange)
-        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
-      } catch (e) {
-        console.error(`❌ worktree 创建失败: ${e.message}`)
-        console.error(`   修复建议：`)
-        console.error(`   1. 运行 sillyspec worktree doctor --fix 检查并修复 worktree 状态`)
-        console.error(`   2. 或手动清理残留：git worktree prune && git branch -D sillyspec/${effectiveChange}`)
-        console.error(`   3. 必要时删除残留目录 .sillyspec/.runtime/worktrees/${effectiveChange}/ 后重试`)
-        process.exit(1)
-      }
-    }
-    // 入口 deps 自检（D-002）：已存在 worktree（create short-circuit 不供给）时重供给
-    if (existingMeta) {
-      const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-      await ensureDepsFreshness(cwd, effectiveChange, execSpecBase, existingMeta)
-    }
-  }
-
-  // ── execute 阶段启动时固定 executeRunId（绑定变更名，避免跨变更复用） ──
-  let currentExecuteRunId = null
-  if (stageName === 'execute') {
-    const { generateExecuteRunId, isValidExecuteRunId } = await import('../task-review.js')
-    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-    const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
-    mkdirSync(runtimeRoot, { recursive: true })
-    // 优先读取已有的变更专属标记文件（agent 可写内容，格式校验防注入/穿越，非法视为缺失重生成）
-    try {
-      if (existsSync(runIdFile)) {
-        const c = readFileSync(runIdFile, 'utf8').trim()
-        if (c && !isValidExecuteRunId(c)) {
-          console.warn(`⚠️ execute run marker 内容非法（期望 exec-YYYY-MM-DD-HHMMSS，实得 ${JSON.stringify(c.slice(0, 60))}），重新生成`)
-        } else {
-          currentExecuteRunId = c
-        }
-      }
-    } catch {}
-    if (!currentExecuteRunId) {
-      currentExecuteRunId = generateExecuteRunId()
-      // D-001#1 主写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：marker 在则目录在，
-      // archive 完成度扫描/漂移兜底不再落到「有 marker 无目录」的空 run）。失败直接 throw——execute
-      // 启动即失败优于事后 review 错配（调用方 runCommand 冒到 CLI 顶层 exit 1，给出修复指引）。
-      try {
-        mkdirSync(join(runtimeRoot, 'execute-runs', currentExecuteRunId, 'tasks'), { recursive: true })
-      } catch (e) {
-        throw new Error(`execute run 目录创建失败（${join(runtimeRoot, 'execute-runs', currentExecuteRunId)}）: ${e.message}；` +
-          `请检查该路径是否为普通文件/只读，清理后重跑（sillyspec run execute --change ${changeName} --skip-approval）`)
-      }
-      writeAtomicSync(runIdFile, currentExecuteRunId + '\n')
-      // change 归属戳（坑 worktree-cleanup-marker-chain 根治）：run 目录自带变更身份，
-      // marker 断裂（worktree cleanup / 归档清理 / 并行误删）后按戳归属，不再错配其他变更的 run
-      const { stampExecuteRunChange } = await import('../task-review.js')
-      stampExecuteRunChange(runtimeRoot, currentExecuteRunId, changeName)
-    }
-  }
-
-  // ── 跨变更文件冲突预警（坑 cross-change-conflict-no-warning，2026-08-22 实证：并行变更改
-  // 同一文件靠人工发现——f578a08e 的「锚点更新」是好实践但工具无预警）。execute 启动时把本变更
-  // 的 diff 文件集与其他活跃变更的 diff 文件集求交集，advisory warn 交集与对端变更名 + 锚点
-  // 更新提示。best-effort：任何异常静默跳过（预警不阻断 execute 启动）。
-  if (stageName === 'execute' && changeName) {
-    try {
-      const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
-      const activeChanges = (pm.listChanges(cwd) || []).filter(c => c && c !== changeName)
-      if (activeChanges.length > 0) {
-        const myFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
-        const mySet = new Set(myFiles.map(f => f.replace(/\\/g, '/')).filter(f => !f.startsWith('.sillyspec/')))
-        if (mySet.size > 0) {
-          const conflicts = []
-          for (const other of activeChanges) {
-            const otherFiles = resolveVerifyChangedFiles(cwd, other, null, { includeWorkingTree: true }) || []
-            const overlap = [...new Set(otherFiles.map(f => f.replace(/\\/g, '/')))]
-              .filter(f => mySet.has(f))
-            if (overlap.length > 0) conflicts.push({ other, overlap })
-          }
-          if (conflicts.length > 0) {
-            console.warn(`⚠️ 跨变更文件冲突预警：本变更（${changeName}}）与其他活跃变更改动重叠——`)
-            for (const c of conflicts) {
-              console.warn(`   与 ${c.other} 重叠 ${c.overlap.length} 个文件：${c.overlap.slice(0, 5).join(', ')}${c.overlap.length > 5 ? ` …（共 ${c.overlap.length}）` : ''}`)
-            }
-            console.warn(`   并行 apply/归档时重叠文件会互相覆盖或冲突。实践：后完成方在其 verify/design 里记录「锚点更新」`)
-            console.warn(`  （说明基于对方已合入的版本重新锚定），并考虑串行化这两个变更的 apply。`)
-          }
-        }
-      }
-    } catch { /* 预警失败不阻断 execute */ }
-  }
-
-  // ── 共享主仓竞态防护（坑 parallel-shared-main-race，2026-08-23 实证：并行会话共享主仓
-  // 工作区/共享部署库的竞态——文件被清、alembic 被推进、staged 混入他者文件）。execute/verify
-  // 启动时探测三类信号并 advisory（不阻断——并发是合法工作模式，但要让 agent 知道环境在变）：
-  //   1. 主仓未提交改动中含非本变更文件（staged 混入：commit 时注意 pathspec）
-  //   2. worktree 存在时 base..HEAD 主仓推进（主仓在他者 apply 后已前进，diff 口径注意）
-  // best-effort：异常静默。
-  if ((stageName === 'execute' || stageName === 'verify') && changeName) {
-    try {
-      const mainDirty = (safeGit(cwd, ['status', '--porcelain'], { trim: false }).value || '')
-        .split('\n').filter(Boolean).map(l => l.slice(3).trim().split(' -> ').pop() || '')
-        .map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/'))
-        .filter(p => p && !p.startsWith('.sillyspec/'))
-      const myFiles = (await import('../verify-postcheck.js')).resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
-      const mySet = new Set(myFiles.map(f => f.replace(/\\/g, '/')))
-      const foreign = mainDirty.filter(p => !mySet.has(p))
-      if (foreign.length > 0) {
-        console.warn(`⚠️ 主仓含 ${foreign.length} 个非本变更的未提交文件（并行会话工作/部署产物混入）——`)
-        console.warn(`   提交时用精确 pathspec（勿 git add -A / 目录级 add 夹带）：${foreign.slice(0, 4).join(', ')}${foreign.length > 4 ? ` …` : ''}`)
-        console.warn(`   交接物核对（文件被清/迁移被推进类异常）先确认是否他者会话所谓，再判定本变更问题。`)
-      }
-    } catch { /* 探测失败不阻断 */ }
-  }
-
-  // 自动探测 currentChange
-  if (autoDetectChange(progress, cwd)) {
-    progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
-    pm._write(cwd, progress, changeName)
-    triggerSync(cwd, changeName, platformOpts)
-  }
-
-  const stageData = progress.stages[stageName]
-  if (!stageData || !stageData.steps) {
-    console.error(`❌ 阶段 ${stageName} 未初始化`)
-    process.exit(1)
-  }
-
-  // 用户显式调用 sillyspec run <stage>：把它标记为当前阶段
-  // （D-003@v1：auxiliary 阶段不写 currentStage，避免 scan/quick/explore/archive/status/doctor
-  //   执行后污染主流程当前阶段；lastActive 心跳与 pm._write/triggerSync 照常）
-  if (progress.currentStage !== stageName) {
-    if (!AUXILIARY_STAGES.includes(stageName)) {
-      progress.currentStage = stageName
-    }
-    progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-    pm._write(cwd, progress, changeName)
-    triggerSync(cwd, changeName, platformOpts)
-  }
-
-  const steps = stageData.steps
-  // ── 检查是否有 waiting step 需要先处理 ──
-  const waitingIdx = steps.findIndex(s => s.status === 'waiting')
-  if (waitingIdx !== -1) {
-    const ws = steps[waitingIdx]
-    console.error(`\n⏸️  Step ${waitingIdx + 1}/${steps.length} 正在等待用户输入：${ws.name}`)
-    if (ws.waitReason) console.error(`   原因：${ws.waitReason}`)
-    if (ws.waitOptions) console.error(`   选项：${formatWaitOptions(ws.waitOptions)}`)
-    console.error(`\n   普通运行无法跳过等待中的步骤。请先处理：`)
-    console.error(`   sillyspec run ${stageName} --continue --answer "你的选择"${changeName ? ` --change ${changeName}` : ''}`)
-    process.exit(1)
-  }
-
-  let currentIdx = steps.findIndex(s => s.status !== 'completed' && s.status !== 'skipped')
-
-  // stale 步骤视为可执行（等同于 pending）
-  if (currentIdx !== -1 && steps[currentIdx].status === 'stale') {
-    steps[currentIdx].status = 'pending'
-    pm._write(cwd, progress, changeName)
-    triggerSync(cwd, changeName, platformOpts)
-  }
-
-  // ── scanProfile: 根据 project 规模动态裁剪步骤 ──
-  let scanProfile = null
-  if (stageName === 'scan' && steps.length > 0 && currentIdx === 0) {
-    scanProfile = computeScanProfile(cwd, platformOpts)
-    console.log(`\n📊 Scan Profile: ${scanProfile.mode} (原因: ${scanProfile.reason})`)
-    if (scanProfile.mode !== 'deep') {
-      applyScanProfileSteps(stageData, scanProfile, cwd, platformOpts)
-      // 步骤被裁剪后 currentIdx 需要重新计算
-      currentIdx = 0
-    }
-    // 保存 profile 供后续 postcheck 使用
-    stageData.scanProfile = scanProfile
-    pm._write(cwd, progress, changeName)
-  } else if (stageName === 'scan' && stageData.scanProfile) {
-    scanProfile = stageData.scanProfile
-  }
-  if (scanProfile) platformOpts.scanProfile = scanProfile
-
-  if (stageName === 'scan') {
-    try {
-      const gitResult = safeGit(cwd, ['rev-parse', 'HEAD'])
-      const scanGuard = {
-        name_zh: '扫描守卫',
-        sourceCommit: gitResult.value,
-        sourceCommitError: gitResult.error,
-        startedAt: new Date().toISOString(),
-        forceRescan: quickOpts?.isForceRescan || false,
-      }
-      const guardFile = join(specBase, '.runtime', 'scan-guard.json')
-      mkdirSync(dirname(guardFile), { recursive: true })
-      // 原子写：hook 进程（worktree-guard 的 readScanGuard）并发读，裸 truncate→write 的
-      // 半截窗口会被 JSON.parse 吞成 null → 覆盖保护静默失效（fail-open）
-      writeAtomicSync(guardFile, JSON.stringify(scanGuard, null, 2) + '\n')
-      if (scanGuard.forceRescan) {
-        console.log('🛡️ scan 覆盖保护已记录: --force-rescan 已开启')
-      } else {
-        console.log('🛡️ scan 覆盖保护已记录: existing scan docs require current source_commit/updated_at')
-      }
-    } catch (e) {
-      console.warn(`⚠️ scan 覆盖保护记录失败: ${e.message}`)
-    }
-  }
-
-  if (currentIdx === -1) {
-    // 所有步骤已 completed/skipped，但阶段未盖到 completed —— 这是上次最后一步完成后、
-    // stage 升级事务未提交的崩溃中间态（正常完成会被上方 stageStatus==='completed' 守卫拦下）。
-    // 旧逻辑无条件清空 steps 为 pending 会丢掉已完成的进度且不可恢复。改为走正式
-    // completeStage：产物齐则补盖完成戳，不齐则给出 actionable 提示，永不静默清空步骤。
-    console.log(`\nℹ️  ${stageName} 所有步骤已完成，但阶段未标记完成（上次可能中断）。尝试补盖完成戳…`)
-    pm.completeStage(cwd, stageName, changeName)
-    const after = pm.read(cwd, changeName)
-    if (after?.stages?.[stageName]?.status === 'completed') {
-      console.log(`   ✅ 已补盖完成戳。下一步: sillyspec run <下一阶段>，或 sillyspec run ${stageName} --status 查看。`)
-      process.exit(0)
-    }
-    // completeStage 已打印产物校验失败的明细；这里只补充恢复指引
-    console.error(`\n   ⚠️ 已保留步骤进度（未清空）。修复产物后重跑，或：`)
-    console.error(`   - 重新开始: sillyspec run ${stageName} --reset`)
-    console.error(`   - 强制补盖: sillyspec progress complete-stage ${stageName}${changeName ? ` --change ${changeName}` : ''} --force`)
-    process.exit(1)
-  }
-
-  // quick 阶段：记录 baselineFiles + 分配 ql-ID（CLI 接管 QUICKLOG 写入）
-  // 幂等判据是 session guard.json 文件（跨进程可靠），不是 progress.quickGuard
-  // （D-003@v1：顶层 quickGuard 不跨进程持久化；agent 在 step 间用 `run quick` 取下一步
-  // prompt 时每个新进程都进此块，按文件判幂等才不会重复分配 ql-ID / 重复写条目）。
-  if (stageName === 'quick') {
-    // quick-sessions 目录经 resolveQuickSessionsDir 单一解析（multi-agent-review Q4）：
-    // 平台模式 runtimeRoot 与 specBase/.runtime 不同时，写/读须对齐，否则 guard 写一处、收尾读另一处。
-    const sessionGuardDir = join(resolveQuickSessionsDir(platformOpts, specBase), changeName)
-    const guardFile = join(sessionGuardDir, 'guard.json')
-    let existingGuard = null
-    try {
-      if (existsSync(guardFile)) existingGuard = JSON.parse(readFileSync(guardFile, 'utf8'))
-    } catch {}
-    if (existingGuard) {
-      // 跨进程重入：复用已分配的 ql-ID，跳过 baseline 重捕与分配（幂等）
-      progress.quickGuard = existingGuard
-      // 中途追加边界：会话中途发现要改启动声明外的文件，此前 resume 会把 --files 静默丢弃、
-      // 边界冻结在启动时刻，只能靠事后归属/审计行兜底。恢复时带 --files 即并入 allowedFiles
-      // （追加不替换、去重保序），同时点录 allowedFilesHash 供同文件并发检测（文件不存在跳过，
-      // 与启动同语义）。--done 审计直读 guard.json（complete-handlers §4.6），追加即被归属消费。
-      const resumeFiles = Array.isArray(quickOpts?.quickFiles) ? quickOpts.quickFiles.filter(Boolean) : []
-      if (resumeFiles.length > 0) {
-        const known = new Set(progress.quickGuard.allowedFiles || [])
-        const added = resumeFiles.filter(f => !known.has(f))
-        if (added.length > 0) {
-          progress.quickGuard.allowedFiles = [...(progress.quickGuard.allowedFiles || []), ...added]
-          progress.quickGuard.allowedFilesHash = { ...(progress.quickGuard.allowedFilesHash || {}) }
-          for (const f of added) {
-            try { progress.quickGuard.allowedFilesHash[f] = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex') }
-            catch { /* 预声明将新建的文件，与启动时 allowedFilesHash 同语义：不存在跳过 */ }
-          }
-          writeAtomicSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
-          console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${progress.quickGuard.allowedFiles.length} 个）: ${added.join(', ')}`)
-        }
-      }
-    } else {
-      // baseline 采集用 safeGit（带 -c safe.directory，避免 linked worktree/容器异 uid/Windows 挂载点
-      // 下裸 `git status` 抛错）。safeGit 已消除 safe.directory 类失败；若仍失败（真非 git 目录等），
-      // 不硬阻断 quick 启动（平台模式/非 git 目录仍需渲染 step prompt），但 fail-visible：大声 warn +
-      // baseline 置空。--done 时 auditQuickCompletion 的 safeGit 同样失败 → blocked，故不存在「静默
-      // 完成」路径（multi-agent-review Q3）。
-      const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
-      if (statusResult.error) {
-        console.warn(`⚠️ quick baseline 采集失败（git status）: ${statusResult.error}`)
-        console.warn(`   baseline 置空；--done 审计将因 git 不可用而阻断（无静默完成路径）。`)
-        console.warn(`   排查：仓库 safe.directory 配置 / 非 git 目录。`)
-      }
-      try {
-        const gitStatus = statusResult.value || ''
-        // 记录全部预存脏文件（含 untracked + .sillyspec/ 路径）。quick 会话期间自身写入的元数据
-        // （quicklog/.runtime/modules/_module-map 等）由 auditQuickCompletion 的 isQuickMetadata 精确豁免，
-        // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
-        // 却在 audit 被当「危险(.sillyspec/)+新增」误判永久 blocked（ql-20260713-002-7628 修复）。
-        const baselineFiles = gitStatus
-          .split('\n').filter(Boolean)
-          .map(line => parsePorcelainPath(line))
-          .filter(Boolean)
-        const allowedFiles = quickOpts?.quickFiles || []
-        const allowNew = quickOpts?.isAllowNew || false
-        const allowDelete = quickOpts?.isAllowDelete || false
-        const forceBaseline = quickOpts?.isForceBaseline || false
-        const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
-        // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
-        const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
-        // 标题回退：启动 quick 不带 --input 时，从关联变更的 proposal/design 提取语义标题，
-        // 避免 QUICKLOG/tasks.md 落 (quick 任务) 占位（deriveTitleFromLinkedChange 读不到则空→sanitizeDesc 回退占位）。
-        let quickDesc = quickOpts?.taskDescription || ''
-        if (!quickDesc && linkedChanges.length > 0) {
-          quickDesc = deriveTitleFromLinkedChange(specBase, linkedChanges[0])
-        }
-        const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
-          description: quickDesc,
-          linkedChanges,
-          allowedFiles,
-        })
-        progress.quickGuard = {
-          sessionId: changeName,
-          // 锚定创建时的 specBase（坑 quick-cwd-drift-splits-specdir）：sessionId 全局复用但
-          // guard 按 specDir 落盘，记下归属让漂移可自证（detectQuickSessionDrift 靠目录定位即可，
-          // 此字段供诊断/未来一致性校验）。
-          specDir: specBase,
-          name_zh: '快速任务守卫',
-          baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
-          baselineFiles,
-          allowedFiles,
-          // task-01: 录每个 allowedFile 内容 sha256，供 --done auditQuickCompletion 检测同文件并发
-          // （allowedFile 在 baseline 且当前 hash ≠ 此值 = 我也改了 → 同文件并发 warn）。文件不存在/读失败跳过。
-          allowedFilesHash: Object.fromEntries(allowedFiles.flatMap(f => {
-            try { return [[f, createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex')]] }
-            catch { return [] }
-          })),
-          allowNew,
-          allowDelete,
-          forceBaseline,
-          linkedChanges,
-          quicklogId: qlId,
-          startedAt: new Date().toISOString(),
-        }
-        // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
-        // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
-        mkdirSync(sessionGuardDir, { recursive: true })
-        writeAtomicSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
-        const parts = [`${baselineFiles.length} 个已有脏文件`]
-        if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
-        if (allowNew) parts.push('允许新增文件')
-        if (allowDelete) parts.push('允许删除文件')
-        console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
-        console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
-        // 缺 --input 且关联变更无可提取标题 → 条目落「(quick 任务)」占位标题，平台「快速修复」列表
-        // 默认隐藏进行中占位（task-06 口径），长会话全程不可见、语义标题要到最终 --done 才回填。
-        // 此刻会话刚起步零沉没成本，提示放弃重启带 --input 是最便宜的自愈点。
-        if (!quickDesc) {
-          console.warn('')
-          console.warn('⚠️ 本次 quick 未带 --input：QUICKLOG 条目将以占位标题「(quick 任务)」落盘')
-          console.warn('   平台「快速修复」列表默认隐藏进行中的占位条目，语义标题要到最终 --done 才回填。')
-          console.warn('   长任务建议放弃本会话、带一句话任务描述重启（旧会话 run quick --reset --change <sessionId> 重置）：')
-          console.warn('     sillyspec run quick --input "<一句话任务描述>" [--linked-changes <a,b>] [--files <...>]')
-        }
-        // 回填 DB changes 行的 title + quicklog_id，让 quick-<hex> 可读、DB↔QUICKLOG 可对账。
-        // title 用 quickDesc（任务描述或关联变更标题）经 sanitizeDesc 压一行限长，与 QUICKLOG 条目标题同源。
-        try {
-          pm.updateChangeMeta(cwd, changeName, { title: sanitizeDesc(quickDesc), quicklogId: qlId });
-        } catch { /* 回填失败不阻断 quick 启动 */ }
-        pm._write(cwd, progress, changeName)
-        // ql-20260819-009：起步即推「进行中」占位条目到平台。runStage 前段三处 triggerSync
-        // （autoDetectChange / currentStage 切换 / stale 复位）全在本块之前执行——「进行中」骨架
-        // 此前要等第一次 --done 才上平台，平台快速修复列表存在起步盲窗。此刻骨架已分配 + 进度已
-        // 落盘，补一次 triggerSync 立即推 QUICKLOG（quick-<hex8> 会话自动降级 syncSpecTreeOnly
-        // 只推 spec 树；未连接平台静默跳过、8s 熔断 best-effort，均不阻断 quick 启动）。平台派发
-        // （claim）模式起步同样走 runStage 本块，一处插入全覆盖；guard 已存在的跨进程重入走上方
-        // existingGuard 分支跳过本块，条目已在平台，不重复推。
-        triggerSync(cwd, changeName, platformOpts)
-      } catch (e) {
-        console.warn(`⚠️ baseline 记录失败: ${e.message}`)
-      }
-    }
-  }
-
-  if (currentIdx > 0) {
-    const completed = currentIdx
-    const total = steps.length
-    console.log(`⚠️  ${stageName} 已进行到第 ${currentIdx + 1}/${total} 步（前 ${completed} 步已完成）。`)
-    console.log(`  继续执行将从中断处恢复，用 --reset 可重新开始。\n`)
-  }
-
-  // ── Brainstorm → Plan Contract：plan 启动前校验 design.md ──
-  if (stageName === 'plan' && currentIdx === 0) {
-    const changeDir = resolveChangeDir(cwd, progress, platformOpts?.specRoot || null)
-    const designPath = changeDir ? join(changeDir, 'design.md') : null
-    if (designPath && existsSync(designPath)) {
-      const { validateDesignForPlan } = await import('../stages/plan.js')
-      const designContent = readFileSync(designPath, 'utf8')
-      const designValidation = validateDesignForPlan(designContent)
-      if (!designValidation.ok) {
-        console.error(`\n❌ Brainstorm → Plan Contract 校验失败：`)
-        for (const err of designValidation.errors) console.error(`   - ${err}`)
-        console.error(`\n   design.md 不满足 plan 契约，请先修复后重试。`)
-        console.error(`   提示：sillyspec run brainstorm --reopen --from-step <步骤> 修订设计文档`)
-        process.exit(1)
-      }
-      if (designValidation.warnings.length > 0) {
-        console.log(`⚠️  Design contract 警告（不阻断）：`)
-        for (const w of designValidation.warnings) console.log(`   - ${w}`)
-        console.log()
-      }
-    }
-  }
-
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
-  if (defSteps && defSteps[currentIdx]) {
-    // noAI 步骤自动完成（CLI-only，不需要 Agent 参与）
-    if (defSteps[currentIdx].noAI || stageData.steps[currentIdx]?.noAI) {
-      const stepName = defSteps[currentIdx].name
-      const cliAction = defSteps[currentIdx]._cliAction || stageData.steps[currentIdx]?._cliAction
-      console.log(`⚙️ Step ${currentIdx + 1}/${stageData.steps.length}: ${stepName}（CLI 自动执行，无需 Agent）`)
-      if (cliAction === 'scanPreflight') {
-        await executeScanPreflight(cwd, platformOpts, scanProfile)
-      } else if (cliAction === 'scanPostcheck') {
-        await executeScanPostcheck(cwd, platformOpts, scanProfile)
-      } else if (cliAction === 'planPostcheck') {
-        await executePlanPostcheck(cwd, platformOpts, progress)
-      } else {
-        throw new Error(`noAI 步骤 ${stepName} 的未知 _cliAction: ${cliAction}——请在 stage.js 注册对应分支`)
-      }
-      stageData.steps[currentIdx].status = 'completed'
-      stageData.steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
-      pm._write(cwd, progress, changeName)
-      // 自动前进到下一步
-      const nextIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
-      if (nextIdx !== -1 && defSteps[nextIdx]) {
-        console.log('')
-        await outputStep(stageName, nextIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
-      } else {
-        // 所有步骤完成
-        stageData.status = 'completed'
-        stageData.completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
-        // persist _write 移到 completeStageGates 成功之后（task-02 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
-        // 阶段完成收尾共享管线（noAI 末步核心修复 S1：plan postcheck independent-tier review verdict=fail /
-        // 平台 scan manifest 此前被绕过）。gate 失败已 rollback 为 in-progress，early-return（不 fall through 到末尾 return）。
-        const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText: null })
-        // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1（与 completeStep/continueStep 同语义）。
-        if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
-        if (_stageGatesResult) return _stageGatesResult
-        // gate 全过：persist completed（task-02 移后；此处无 triggerSync，与同文件 noAI 末步语义一致）。
-        pm._write(cwd, progress, changeName)
-        console.log(`\n✅ ${stageName} 阶段全部完成。`)
-      }
-      return
-    }
-    await outputStep(stageName, currentIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
-  }
-}
-
-
-
-
-
-
-/**
- * 自动探测并设置 currentChange（唯一变更目录时）
- * @returns {boolean} 是否设置了 currentChange
- */
-function autoDetectChange(progress, cwd, specDir = null) {
-  if (progress.currentChange) return false
-  const changesDir = join(specDir || resolveSpecDir(cwd), 'changes')
-  if (!existsSync(changesDir)) return false
-  const entries = readdirSync(changesDir, { withFileTypes: true })
-    .filter(e => e.isDirectory() && e.name !== 'archive')
-  if (entries.length === 1) {
-    progress.currentChange = entries[0].name
-    return true
-  }
-  return false
-}
-
-
-/**
- * Plan postcheck 的执行代理：委托给 plan-postcheck.js 模块
- */
-async function executePlanPostcheck(cwd, platformOpts, progress) {
-  // resolveChangeDir 从 ./shared.js 导入（W6 Step1 抽出的纯函数，原 run.js 本地函数）；历史上曾误从 ./modules.js
-  // 导入（该模块未导出此函数，得到 undefined），导致 plan-postcheck.js:388 抛
-  // "resolveChangeDir is not a function"。详见 docs/sillyspec/plan-postcheck-resolvechangedir-not-a-function.md
-  const { executePlanPostcheck: runPostcheck } = await import('../stages/plan-postcheck.js')
-  await runPostcheck({
-    cwd,
-    specRoot: platformOpts?.specRoot,
-    resolveChangeDir,
-    progress
-  })
-}
-
-
-
-/**
- * execute 入口 deps 自检（D-002，change 2026-06-28-worktree-deps-provision）。
- * 已存在 worktree（create short-circuit 不供给）时，校验 deps 状态缺失/漂移 → 触发 provisionDeps 重供给并写回 meta。
- *
- * 判定改调共享 checkDepsFreshness（H1，change 2026-08-05-tooling-feedback-fixes task-04）：
- *   - status ∈ {missing, stale, main-drift, failed} → 触发重供给（main-drift 为新增主仓 lockfile 漂移触发）
- *   - status === fresh → 跳过
- *   行为与原内联 noStatus/missing/stale 三判定等价（provisionDeps 调用 / meta 写回不变），新增 main-drift 触发。
- */
-async function ensureDepsFreshness(cwd, changeName, specBase, worktreeMeta) {
-  if (!worktreeMeta || !worktreeMeta.worktreePath) return
-  const { provisionDeps, checkDepsFreshness } = await import('../worktree-deps.js')
-  const wtPath = worktreeMeta.worktreePath
-  const fresh = checkDepsFreshness(worktreeMeta, wtPath, cwd)
-  if (fresh.status === 'fresh') return
-  const reason = fresh.detail || fresh.status
-  console.log(`🔄 worktree deps 自检：${reason}（depsStatus=${worktreeMeta.depsStatus || 'unknown'}），重新供给...`)
-  let deps = {}
-  try {
-    deps = provisionDeps(wtPath, cwd, { specBase }) || {}
-  } catch (e) {
-    deps = { depsStatus: 'failed', depsError: `provisionDeps crashed: ${e.message}` }
-  }
-  try {
-    const { WorktreeManager } = await import('../worktree.js')
-    const metaPath = join(new WorktreeManager({ cwd }).getWorktreePath(changeName), 'meta.json')
-    const updated = { ...worktreeMeta, ...deps }
-    writeAtomicSync(metaPath, JSON.stringify(updated, null, 2) + '\n')
-    console.log(`✅ deps 重新供给完成：depsStatus=${deps.depsStatus}`)
-  } catch (e) {
-    console.warn(`⚠️  deps meta 写回失败：${e.message}`)
-  }
-}
-

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

@@ -1,23 +0,0 @@
-/**
- * sillyspec run 命令实现（W6 Step8 后退化为 barrel）。
- *
- * 实际逻辑在 src/run/*.js 叶子模块（shared / prompt / quick-audit / scan-profile /
- * gates / complete-handlers / complete / stage / command）。run.js 仅作 barrel：
- * 外部 import 契约通过 re-export 保留（run.js 是 index.js 懒加载入口，零入边叶子，
- * 外部 import 零感知）。
- *
- * test 直接 import 的契约（7 个）：runCommand / ensureStageSteps /
- * parsePorcelainPath / auditQuickCompletion /
- * applyRootPlaceholders / sanitizeProjectName / validateParsedProjects。
- * （outputStep 由 test/output-step-render + archive-task-completion-injection 直接自
- * ./run/prompt.js import，无需 barrel 转出；completeStep/outputStep 的 `_xxxForTest` 测试别名
- * 2026-08-13 全部移除——completion 行为走 CLI 子进程，纯渲染器 outputStep 直 import 源模块。）
- */
-// W6 Step8c: 主命令分发（runCommand）+ auto 模式 + ensureStageSteps 搬至 ./run/command.js
-export { runCommand, ensureStageSteps } from './run/command.js'
-// barrel re-export: parsePorcelainPath + auditQuickCompletion + isQuickMetadata + collectOtherQuickSessionDeclarations 被 test 直接 import（契约保留）
-export { parsePorcelainPath, auditQuickCompletion, isQuickMetadata, collectOtherQuickSessionDeclarations } from './run/shared.js'
-// barrel re-export: applyRootPlaceholders 被 test/prompt-placeholders.test.mjs 直接 import（契约保留）
-export { applyRootPlaceholders } from './run/prompt.js'
-// barrel re-export: sanitizeProjectName + validateParsedProjects 被 test 直接 import（随 handleScan 搬走，契约保留）
-export { sanitizeProjectName, validateParsedProjects } from './run/complete-handlers.js'