sillyspec 3.25.9 → 3.26.0

package/src/run/complete.js

@@ -1,7 +1,7 @@
 /**
  * run/complete.js（W6 Step7b 从 run.js 抽出）。
  *
- * step 完成处理核心：completeStep（调度主干——WAIT/scanProfile/requiresWait 门控 + 各 handler 调用 +
+ * step 完成处理核心：completeStep（调度主干——WAIT/requiresWait 门控 + 各 handler 调用 +
  * completion path 收尾 + single-step path）+ skipStep/waitStep/continueStep（W6 Step7b-2 续搬）。
  * 本 commit（7b-1）先搬 completeStep + 2 独占 helper（validateMetadata/validateFileLocations）。
  *
@@ -15,106 +15,19 @@
  *   - node: join(path) + existsSync/readdirSync/readFileSync/mkdirSync/writeFileSync/appendFileSync/statSync(fs)
  */
 import { join } from 'node:path'
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, appendFileSync, statSync } from 'node:fs'
-import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions } from './shared.js'
+import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
+import { writeAtomicSync } from '../fs-atomic.js'
+import { withFileLock } from '../quicklog.js'
+import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot } from './shared.js'
 import { outputStep } from './prompt.js'
-import { enforceDepsGate, enforceReviewJsonGate, runStageCompletionGates } from './gates.js'
-import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact, handleExecuteWorktreeCleanup, handleScanStageCompleted } from './complete-handlers.js'
-import { stageRegistry } from '../stages/index.js'
+import { enforceDepsGate, enforceReviewJsonGate, completeStageGates, readDesignScale } from './gates.js'
+import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
+import { isEndToEndTaskText } from '../change-risk-profile.js'
 
-function validateMetadata(cwd, stageName, specBase) {
-  const changesDir = join(specBase, 'changes')
-  if (!existsSync(changesDir)) return
-
-  const cutoff = Date.now() - 10 * 60 * 1000
-  const missing = []
-
-  function walk(dir) {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name)
-      try {
-        if (entry.isDirectory()) { walk(full); continue }
-        if (!/\.(md|yaml|yml)$/.test(entry.name)) continue
-        const mtime = statSync(full).mtimeMs
-        if (mtime < cutoff) continue
-        const content = readFileSync(full, 'utf-8')
-        if (!content.includes('author:') && !content.includes('author：')) missing.push(full)
-        if (!content.includes('created_at:') && !content.includes('created_at：')) missing.push(full)
-      } catch (e) { /* skip unreadable files */ }
-    }
-  }
-
-  walk(changesDir)
-  const unique = [...new Set(missing)]
-  if (unique.length > 0) {
-    console.log(`\n⚠️  以下文件缺少 author 或 created_at 元数据：`)
-    unique.forEach(f => console.log(`  - ${f.replace(cwd + '/', '')}`))
-    console.log('请在文件头部添加 author（git 用户名）和 created_at（精确到秒）')
-  }
-}
-
-/**
- * 读取 design.md frontmatter 的 scale 字段（brainstorm 末步写入 'small'|'large'）。
- * completeStep 的下一步提示据此分叉：small→quick，large/读不到→plan（fail-safe 走重流程）。
- * 只解析首个 YAML frontmatter 块，避免误读正文里的 "scale:"。
- */
-function readDesignScale(specBase, changeName) {
-  if (!changeName) return null
-  const designPath = join(specBase, 'changes', changeName, 'design.md')
-  if (!existsSync(designPath)) return null
-  const text = readFileSync(designPath, 'utf8')
-  const fm = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
-  if (!fm) return null
-  const m = fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
-  return m ? m[1] : null
-}
-
-/**
- * 验证关键文件是否存在于正确的变更目录下
- * 防止 AI 将文件写到错误的路径
- */
-function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
-  const effectiveChange = changeName || progress.currentChange
-  if (!effectiveChange) return
-
-  const changeDir = join(specBase, 'changes', effectiveChange)
-  if (!existsSync(changeDir)) return
-
-  // 每个阶段完成后预期存在的文件
-  const expectedFiles = {
-    brainstorm: ['design.md', 'proposal.md', 'requirements.md', 'tasks.md'],
-    plan: ['plan.md'],
-    archive: ['module-impact.md'],
-  }
-
-  const expected = expectedFiles[stageName]
-  if (!expected) return
-
-  const missing = []
-  for (const file of expected) {
-    if (!existsSync(join(changeDir, file))) {
-      missing.push(file)
-    }
-  }
-
-  if (missing.length > 0) {
-    console.log(`\n⚠️  文件位置验证：以下文件未在变更目录中找到`)
-    console.log(`  变更目录：${changeDir.replace(cwd + '/', '')}/`)
-    for (const f of missing) {
-      // 检查是否写到了错误的位置
-      const wrongPath = join(specBase, 'changes', 'change', effectiveChange, f)
-      if (existsSync(wrongPath)) {
-        console.log(`  ❌ ${f} — 不存在，但发现了错误路径：${wrongPath.replace(cwd + '/', '')}`)
-        console.log(`     提示：应该写入 ${changeDir.replace(cwd + '/', '')}/${f}`)
-      } else {
-        console.log(`  ⬜ ${f} — 未找到（该阶段可能未产出此文件）`)
-      }
-    }
-  } else {
-    console.log(`\n✅ 文件位置验证：所有 ${expected.length} 个预期文件均在变更目录中`)
-  }
-}
+// validateMetadata / readDesignScale / validateFileLocations 已迁至 ./gates.js（completeStageGates
+// 共享收尾管线，消除 noAI 末步 / continueStep 完成分支绕过 gate 的 S1/S2/S3 不对称）。
+// completeStep 阶段完成分支（task-02 接入 completeStageGates）+ brainstorm 下一步提示改 import 自 gates.js。
 
 /**
  * 坑1：用 --done --answer 解掉「已 waiting 的步骤」。
@@ -147,10 +60,9 @@ export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
 }
 
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, confirmMode = null, isForceBaseline = false, isAllowNew = false } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
-  const scanProfile = stageData?.scanProfile || null
 
   // ── WAIT MARKER 硬校验 ──
   // 如果 output 包含等待标记，拒绝 --done 推进
@@ -163,12 +75,6 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       process.exit(1)
     }
   }
-
-  // scanProfile 非 deep 模式：截断 outputText 减少 token 传递
-  let effectiveOutput = outputText
-  if (scanProfile && scanProfile.mode !== 'deep' && outputText && outputText.length > 1000) {
-    effectiveOutput = outputText.slice(0, 1000) + '\n\n…[输出已截断，完整内容见 artifact]'
-  }
   if (!stageData || !stageData.steps) {
     console.error(`❌ 阶段 ${stageName} 未初始化`)
     process.exit(1)
@@ -181,13 +87,29 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // requiresWait 步骤时会跳过它、把 --answer 静默丢弃，步骤永久卡 WAITING、末步报「等待用户输入」。
   // 修复：带 doneAnswer 且存在 waiting 步骤时，把首个 waiting 拉回 pending + 补 waitAnswer，主流程
   // requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。仅 --answer 触发，普通 --done 零变化。
-  const _resolvedWaitIdx = resolveWaitingStepWithAnswer(steps, options && options.doneAnswer, new Date().toLocaleString('zh-CN', { hour12: false }))
+  const _doneAnswer = options && options.doneAnswer
+  // ── 多 waiting 歧义守卫（对齐 continueStep 742-751 的同名保护）──
+  // resolveWaitingStepWithAnswer 只 findIndex 解「第一个」waiting；阶段内 ≥2 个 waiting 时
+  // --done --answer 会静默把 answer 填给第一个，可能答错对象。与 --continue 对齐：多 waiting 时报错列出。
+  if (_doneAnswer) {
+    const waitingIdxs = steps.map((s, i) => (s && s.status === 'waiting') ? i : -1).filter(i => i !== -1)
+    if (waitingIdxs.length > 1) {
+      console.error(`❌ 检测到 ${waitingIdxs.length} 个等待中的步骤，--done --answer 无法确定解哪一个：`)
+      for (const i of waitingIdxs) {
+        console.error(`   Step ${i + 1}: ${steps[i].name}${steps[i].waitReason ? `（${steps[i].waitReason}）` : ''}`)
+      }
+      console.error(`   出路：用 --continue 逐个指定恢复（每次解一个 waiting，降到 1 个后即可 --done --answer）：`)
+      console.error(`   sillyspec run ${stageName} --continue --from-step <序号|名称> --answer "..."${changeName ? ` --change ${changeName}` : ''}`)
+      process.exit(1)
+    }
+  }
+  const _resolvedWaitIdx = resolveWaitingStepWithAnswer(steps, _doneAnswer, new Date().toLocaleString('zh-CN', { hour12: false }))
   if (_resolvedWaitIdx !== -1) {
     currentIdx = _resolvedWaitIdx
     console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
   }
   if (currentIdx === -1) {
-    console.error('没有待完成的步骤')
+    console.error(`没有待完成的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
     process.exit(1)
   }
 
@@ -257,7 +179,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // archive「确认归档」收尾：--confirm 门控 + archiveChangeDirectory 移动 + 推荐文档校验
   // （抽成 handleArchiveConfirmStep；缺 --confirm 时返回 early-return 对象，completeStep 透传）
   {
-    const _archiveEarlyReturn = await handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase })
+    const _archiveEarlyReturn = await handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts })
     if (_archiveEarlyReturn) return _archiveEarlyReturn
   }
 
@@ -311,14 +233,14 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     if (hasWaiting) {
       // 有等待中的步骤，阶段未完成
       progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-      await pm._write(cwd, progress, changeName)
+      pm._write(cwd, progress, changeName)
       const wsIdx = steps.findIndex(s => s.status === 'waiting')
       console.log(`\n⏸️  阶段暂停：Step ${wsIdx + 1} 等待用户输入`)
       if (steps[wsIdx].waitReason) console.log(`   原因：${steps[wsIdx].waitReason}`)
       return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
     }
     // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）
-    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, platformOpts })
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, platformOpts, pm })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤
@@ -333,53 +255,37 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         st.status = 'completed'
         st.completedAt = st.completedAt || nowStr
       }
-      await pm._write(cwd, progress, changeName)
+      pm._write(cwd, progress, changeName)
       console.log(`  ⚠️ 同步回填 ${staleSteps.length} 个 stale 步骤为 completed（reopen --from-step N 后 --done，方案未变）`)
     }
 
     stageData.status = 'completed'
     stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-    await pm._write(cwd, progress, changeName)
-    triggerSync(cwd, changeName, platformOpts)
+    // persist（_write + triggerSync）移到 completeStageGates 成功之后（task-01 / review-2026-08-09 #2）：
+    // gate 任一段异常/失败 → rollbackCompletionAndReturn 回 in-progress 并落盘；此处未到 _write，DB 不留假 completed。
 
     // Append to user-inputs.md
     if (outputText) {
       const inputsPath = join(specBase, '.runtime', 'user-inputs.md')
       const entry = `\n## ${new Date().toLocaleString('zh-CN',{hour12:false})} | ${changeName || '?'} | ${stageName}: ${steps[currentIdx].name}\n${inputText ? "- 输入：" + inputText + "\n" : ""}- 输出：${outputText}\n`
-      appendFileSync(inputsPath, entry)
+      try {
+        appendFileSync(inputsPath, entry)
+      } catch (e) {
+        // best-effort：Windows AV/索引占用偶发 EPERM，历史日志写失败不阻断主流程（review-2026-08-09 #7，对齐 shared.js triggerSync）
+        console.warn('⚠️ user-inputs.md 追加失败（不阻断）:', e.message)
+      }
     }
 
-    // scan 平台 manifest + post-check（W6 Step6d 抽至 complete-handlers.js handleScanStageCompleted）
-    const _scanResult = await handleScanStageCompleted({ stageName, currentIdx, cwd, progress, pm, stageData, changeName, outputText, platformOpts })
-    if (_scanResult) return _scanResult
-
-    // 防御性守卫变量：确认所有步骤确实标记为 completed
-    const actualCompleted = steps.filter(s => s.status === 'completed').length
-    const actualTotal = steps.length
+    // 阶段完成收尾共享管线（handleScan manifest + validateMetadata/FileLocations + auxiliary 重置 +
+    // runStageCompletionGates + execute worktree cleanup），消除 S1/S2/S3 三处收尾不对称（task-01 抽出）。
+    // gate 失败已 rollback，early-return 跳过下方"阶段已完成/下一步"提示（合理收紧：回滚不该打完成提示）。
+    const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText })
+    if (_stageGatesResult) return _stageGatesResult
 
-    validateMetadata(cwd, stageName, specBase)
-
-    // 验证关键文件是否在正确的变更目录下（仅当所有步骤确实完成时才校验）
-    if (actualCompleted === actualTotal && actualTotal > 0) {
-      validateFileLocations(cwd, stageName, progress, changeName, specBase)
-    }
-
-    // 辅助阶段完成后重置步骤
-    const stageDef = stageRegistry[stageName]
-    if (stageDef?.auxiliary) {
-      const freshSteps = (stageDef.steps || []).map(s => ({
-        name: s.name,
-        status: 'pending',
-        output: null,
-        completedAt: null
-      }))
-      stageData.steps = freshSteps
-      stageData.status = 'pending'
-      stageData.completedAt = null
-      if (progress.currentStage === stageName) progress.currentStage = ''
-      await pm._write(cwd, progress, changeName)
-    }
+    // gate 全过：persist completed（task-01 移后）。此处到 _write 之间若崩，DB 仍 in-progress（内存已 completed 但未落盘），下次进 CLI 读 DB 即 in-progress，不产生"假 completed"。
+    pm._write(cwd, progress, changeName)
+    triggerSync(cwd, changeName, platformOpts)
 
     const total = steps.length
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
@@ -434,30 +340,22 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       }
     }
 
-    // 阶段完成校验 — 防御性守卫：仅当所有步骤确实标记为 completed 时才跑 validator
-    if (actualCompleted === actualTotal && actualTotal > 0) {
-      const _gateEarlyReturn = await runStageCompletionGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx })
-      if (_gateEarlyReturn) return _gateEarlyReturn
-    } else if (actualCompleted < actualTotal) {
-      // 实际步骤未全部完成，跳过 validator（状态可能不同步）
-      console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
-    }
-
-    // execute worktree cleanup（W6 Step6c 抽至 complete-handlers.js handleExecuteWorktreeCleanup）
-    await handleExecuteWorktreeCleanup({ stageName, changeName, cwd })
-
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-  await pm._write(cwd, progress, changeName)
+  pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
 
   // Append to user-inputs.md
   if (outputText) {
     const inputsPath = join(specBase, '.runtime', 'user-inputs.md')
     const entry = `\n## ${new Date().toLocaleString('zh-CN',{hour12:false})} | ${changeName || '?'} | ${stageName}: ${steps[currentIdx].name}\n${inputText ? "- 输入：" + inputText + "\n" : ""}- 输出：${outputText}\n`
-    appendFileSync(inputsPath, entry)
+    try {
+      appendFileSync(inputsPath, entry)
+    } catch (e) {
+      console.warn('⚠️ user-inputs.md 追加失败（不阻断）:', e.message)
+    }
   }
 
   const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
@@ -469,6 +367,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 
   if (printNext) {
     await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
+    // task-08：底部锚定行——outputStep 渲染的长 prompt 易被 tail 截断，末尾再打一行推进位置，
+    // 让 agent 只看末几行也能知道「推进到第几步」。仅单步推进分支（阶段完成分支已有 ✅ 阶段已完成）。
+    // defSteps 越界防御：平台模式 buildPlanSteps 长度漂移时 nextPendingIdx 可能越界
+    // （参照 prompt.js:174-179 越界降级先例），越界时静默跳过，不崩。
+    if (defSteps && defSteps[nextPendingIdx]) {
+      console.log(`\n🚀 advanced to step ${nextPendingIdx + 1}/${steps.length}: ${defSteps[nextPendingIdx].name}`)
+    }
   }
   return { stageCompleted: false, currentIdx, nextPendingIdx }
 }
@@ -482,6 +387,31 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
  * @returns {{autoChecked:boolean, checkedCount:number, skippedCount:number, planTotal:number, planChecked:number}}
  *   planTotal/planChecked 在调用方于本函数之后用 readPlanCheckboxStatus 重读（勾选已落盘）。
  */
+/**
+ * 读 task 卡片文本（plan.md task 行外的详细描述/allowed_paths），用于端到端 task 判定。
+ * 卡片缺失返回空串（仅靠 plan.md task 行文本判）。
+ */
+function readTaskCardText(changeDir, taskNum) {
+  try { return readFileSync(join(changeDir, 'tasks', `task-${taskNum}.md`), 'utf8') } catch { return '' }
+}
+
+/**
+ * 判定 task 是否该被 autoCheckPlanFromReviews 自动勾选。
+ * 端到端/deployment-critical task 要求 review spec+quality 双 pass（cannot_verify 不算，防批量完成
+ * 放行未真验的端到端 task）；普通 task 非 fail 即可（保主 agent 直接实现模式体验，其 cannot_verify
+ * 草稿仍可批量收尾）。坑 execute-batch-complete-endtoend-checkbox。
+ * @param {{ok?:boolean, review?:{specVerdict?:string, qualityVerdict?:string}}} r readReview 结果
+ * @param {boolean} endToEnd 是否端到端/deployment-critical task
+ * @returns {boolean}
+ */
+export function shouldAutoCheckTask(r, endToEnd) {
+  if (!r?.ok) return false
+  const spec = r.review?.specVerdict
+  const quality = r.review?.qualityVerdict
+  if (spec === 'fail' || quality === 'fail') return false
+  if (endToEnd) return spec === 'pass' && quality === 'pass'
+  return true
+}
 async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
   if (stageName !== 'execute' || !changeName) {
     return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
@@ -490,31 +420,40 @@ async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOp
     const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
     const changeDir = join(specBaseLc, 'changes', changeName)
     const planPath = join(changeDir, 'plan.md')
-    const runtimeRoot = platformOpts?.runtimeRoot || join(specBaseLc, '.runtime')
+    const runtimeRoot = resolveRuntimeRoot(platformOpts, specBaseLc)
     const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
     if (!existsSync(planPath) || !existsSync(runIdFile)) {
       return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
     }
     const executeRunId = readFileSync(runIdFile, 'utf8').trim()
-    const planContent = readFileSync(planPath, 'utf8')
     const { readReview } = await import('../task-review.js')
-    let checkedCount = 0
-    let skippedCount = 0
-    const updated = planContent.replace(/^(\s*[-*]\s*\[)\s(\]\s*task-\d+)/gim, (match, p1, p2) => {
-      const taskNum = match.match(/task-(\d+)/)[1].padStart(2, '0')
-      const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', `task-${taskNum}`, 'review.json')
-      const r = readReview(reviewPath)
-      if (r.ok && r.review?.specVerdict !== 'fail' && r.review?.qualityVerdict !== 'fail') {
-        checkedCount++
-        return `${p1}x${p2}`   // 勾选
+    // plan.md 是 agent 与 CLI 都会写的共享文件（agent 勾 checkbox、此处 autoCheck 也勾选）。
+    // 读-改-写必须整体持锁（withFileLock 串行化多进程），否则并发 execute --done / 手动勾选互相覆盖
+    // （后到者覆盖先到者）；写入用 writeAtomicSync（tmp+rename 原子），防 Windows 整文件覆盖被读半截
+    // （fs-atomic.js 头注明的 reader-writer 竞态坑）。锁文件放 changeDir，与 QUICKLOG 同机制。
+    const lockPath = join(changeDir, '.plan.md.lock')
+    return await withFileLock(lockPath, async () => {
+      const planContent = readFileSync(planPath, 'utf8')
+      let checkedCount = 0
+      let skippedCount = 0
+      const updated = planContent.replace(/^(\s*[-*]\s*\[)\s(\]\s*task-\d+)/gim, (match, p1, p2) => {
+        const taskNum = match.match(/task-(\d+)/)[1].padStart(2, '0')
+        const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', `task-${taskNum}`, 'review.json')
+        const r = readReview(reviewPath)
+        // 端到端 task：必须 pass（cannot_verify 不算）；普通 task：非 fail 即可（坑 execute-batch-complete-endtoend-checkbox）
+        const endToEnd = isEndToEndTaskText(match + ' ' + readTaskCardText(changeDir, taskNum))
+        if (shouldAutoCheckTask(r, endToEnd)) {
+          checkedCount++
+          return `${p1}x${p2}`   // 勾选
+        }
+        skippedCount++
+        return match              // 不勾
+      })
+      if (checkedCount > 0) {
+        writeAtomicSync(planPath, updated)
       }
-      skippedCount++
-      return match              // 不勾
+      return { autoChecked: checkedCount > 0, checkedCount, skippedCount }
     })
-    if (checkedCount > 0) {
-      writeFileSync(planPath, updated)
-    }
-    return { autoChecked: checkedCount > 0, checkedCount, skippedCount }
   } catch {
     return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
   }
@@ -592,7 +531,7 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
   // 查找下一个 pending 或 in-progress 的步骤
   const currentIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
   if (currentIdx === -1) {
-    console.error('没有可以等待的步骤')
+    console.error(`没有可以等待的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
     process.exit(1)
   }
 
@@ -651,7 +590,7 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
   }
 
   progress.lastActive = now
-  await pm._write(cwd, progress, changeName)
+  pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
 
   console.log(`⏸️  Step ${currentIdx + 1}/${stageData.steps.length} 已暂停等待：${stageData.steps[currentIdx].name}`)
@@ -678,7 +617,7 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   // 查找 waiting 的步骤
   const waitingSteps = stageData.steps.map((s, i) => ({ ...s, idx: i })).filter(s => s.status === 'waiting')
   if (waitingSteps.length === 0) {
-    console.error('没有处于等待状态的步骤')
+    console.error(`没有处于等待状态的步骤（阶段 ${stageName} 当前无 waiting 步骤，--continue 无目标）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
     process.exit(1)
   }
 
@@ -754,7 +693,7 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   }
 
   progress.lastActive = now
-  await pm._write(cwd, progress, changeName)
+  pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
 
   console.log(`✅ Step ${currentIdx + 1}/${stageData.steps.length} 已继续：${currentStep.name}`)
@@ -763,7 +702,11 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   // Append to user-inputs.md
   const inputsPath = join(specBase, '.runtime', 'user-inputs.md')
   const entry = `\n## ${now} | ${changeName || '?'} | ${stageName}: ${currentStep.name} [CONTINUED]\n- 回答：${answer}\n`
- appendFileSync(inputsPath, entry)
+  try {
+    appendFileSync(inputsPath, entry)
+  } catch (e) {
+    console.warn('⚠️ user-inputs.md 追加失败（不阻断）:', e.message)
+  }
 
   // shouldReturnToCurrentStep: 回到当前步骤继续执行（repeatable=多轮探索，requiresWait=确认后执行动作）
   if (shouldReturnToCurrentStep) {
@@ -793,37 +736,14 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   if (nextPendingIdx === -1 && nextWaitingIdx === -1) {
     stageData.status = 'completed'
     stageData.completedAt = now
-    await pm._write(cwd, progress, changeName)
+    // persist _write 移到 completeStageGates 成功之后（task-03 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
+    // 阶段完成收尾共享管线（含 execute worktree cleanup），消除 continueStep 完成分支绕过 gate 的 S2（task-01 抽出）。
+    // gate 失败已 rollback，early-return 跳过下方"阶段已完成/下一步"提示（与 completeStep 同语义）。
+    const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps: stageData.steps, currentIdx, outputText: null })
+    if (_stageGatesResult) return _stageGatesResult
+    // gate 全过：persist completed（task-03 移后；此处无 triggerSync）。
+    pm._write(cwd, progress, changeName)
     console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)
-    // ── execute 阶段完成时条件性清理 worktree ──
-    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，不碰主工作区）
-          const check = wm.hasUnappliedChanges(changeName);
-          if (check.hasChanges) {
-            console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
-            console.log(`   下一步: sillyspec worktree apply ${changeName}`);
-          } else {
-            const cleanResult = wm.cleanup(changeName);
-            console.log(`🔗 Worktree: ${cleanResult.result}`);
-            if (cleanResult.residual?.length > 0) {
-              console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
-              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
-            }
-          }
-        }
-      } catch (e) {
-        console.warn(`🔗 Worktree: check failed — ${e.message}`);
-      }
-    }
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {
@@ -884,7 +804,7 @@ export async function skipStep(pm, progress, stageName, cwd, changeName, platfor
       console.error(`⏸️  Step ${wsIdx + 1} 正在等待用户输入，不能跳过。`)
       console.error(`   请先使用 --continue --answer "..." 继续，或用 --reset 重置。`)
     } else {
-      console.error('没有待跳过的步骤')
+      console.error(`没有待跳过的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
     }
     process.exit(1)
   }
@@ -899,7 +819,7 @@ export async function skipStep(pm, progress, stageName, cwd, changeName, platfor
   steps[currentIdx].status = 'skipped'
   steps[currentIdx].skippedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-  await pm._write(cwd, progress, changeName)
+  pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
 
   console.log(`⏭️ Step ${currentIdx + 1}/${steps.length} 已跳过：${steps[currentIdx].name}`)