sillyspec 3.27.1 → 3.27.5

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

@@ -0,0 +1,584 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+/**
+ * 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'