sillyspec 3.25.0 → 3.25.2

package/src/run/stage.js

@@ -0,0 +1,414 @@
+/**
+ * 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, writeFileSync, mkdirSync } from 'node:fs'
+import { writeAtomicSync } from '../fs-atomic.js'
+import { resolveSpecDir, resolveChangeDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
+import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
+import { outputStep } from './prompt.js'
+import { allocateQuicklogEntry } from '../quicklog.js'
+import { checkTransition } from '../stage-contract.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 跳过审批检查')
+      }
+    }
+  }
+
+  // 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 } = await import('../task-review.js')
+    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const runtimeRoot = platformOpts?.runtimeRoot || join(execSpecBase, '.runtime')
+    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    mkdirSync(runtimeRoot, { recursive: true })
+    // 优先读取已有的变更专属标记文件
+    try {
+      if (existsSync(runIdFile)) {
+        currentExecuteRunId = readFileSync(runIdFile, 'utf8').trim()
+      }
+    } catch {}
+    if (!currentExecuteRunId) {
+      currentExecuteRunId = generateExecuteRunId()
+      writeFileSync(runIdFile, currentExecuteRunId + '\n')
+    }
+  }
+
+  // 自动探测 currentChange
+  if (autoDetectChange(progress, cwd)) {
+    progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
+    await 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>：把它标记为当前阶段
+  if (progress.currentStage !== stageName) {
+    progress.currentStage = stageName
+    progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+    await 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'
+    await 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
+    await 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 })
+      writeFileSync(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} 所有步骤已完成，但阶段未标记完成（上次可能中断）。尝试补盖完成戳…`)
+    await pm.completeStage(cwd, stageName, changeName)
+    const after = await 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') {
+    const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', 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
+    } else {
+      try {
+        const { execSync } = await import('child_process')
+        const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+        // 记录全部预存脏文件（含 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 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'
+        const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
+          description: quickOpts?.taskDescription || '',
+          linkedChanges,
+          allowedFiles,
+        })
+        progress.quickGuard = {
+          sessionId: changeName,
+          name_zh: '快速任务守卫',
+          baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
+          baselineFiles,
+          allowedFiles,
+          allowNew,
+          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('允许新增文件')
+        console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
+        console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        await pm._write(cwd, progress, changeName)
+      } 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)
+      }
+      stageData.steps[currentIdx].status = 'completed'
+      stageData.steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
+      await 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 })
+        await 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 不供给）时，校验 depsStatus 缺失 / node_modules
+ * 丢失(missing) / lockfile 变化(stale) → 触发 provisionDeps 重供给并写回 meta。
+ */
+async function ensureDepsFreshness(cwd, changeName, specBase, worktreeMeta) {
+  if (!worktreeMeta || !worktreeMeta.worktreePath) return
+  const { provisionDeps, lockfileHash } = await import('../worktree-deps.js')
+  const wtPath = worktreeMeta.worktreePath
+  const nodeModulesExists = existsSync(join(wtPath, 'node_modules'))
+  const currentHash = lockfileHash(wtPath)
+  const noStatus = !worktreeMeta.depsStatus
+  const missing = ['linked', 'installed'].includes(worktreeMeta.depsStatus) && !nodeModulesExists
+  const stale = !!(worktreeMeta.depsLockHash && currentHash && currentHash !== worktreeMeta.depsLockHash)
+  if (!noStatus && !missing && !stale) return
+  const reason = noStatus ? 'depsStatus 缺失' : (missing ? 'node_modules 丢失' : 'lockfile 变化')
+  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}`)
+  }
+}
+