sillyspec 3.25.9 → 3.25.11

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)
   }
 
@@ -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,15 +255,15 @@ 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) {
@@ -350,36 +272,15 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       appendFileSync(inputsPath, entry)
     }
 
-    // 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
-
-    validateMetadata(cwd, stageName, specBase)
+    // 阶段完成收尾共享管线（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
 
-    // 验证关键文件是否在正确的变更目录下（仅当所有步骤确实完成时才校验）
-    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,23 +335,11 @@ 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
@@ -469,6 +358,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 +378,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 +411,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 +522,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 +581,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 +608,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 +684,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}`)
@@ -793,37 +723,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 +791,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 +806,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}`)

package/src/run/concurrent-detect.js

@@ -0,0 +1,132 @@
+/**
+ * concurrent-detect — 多 agent 并发写预检的纯函数检测核心（design §7）。
+ *
+ * 单次 git status --porcelain 扫描，复用 isQuickMetadata 的「关联 vs 他者」分类口径，
+ * 产出两类并发信号：
+ *   - foreignFiles: 脏文件里非 metadata、不在 ownFiles 的真实业务文件（他者未提交改动）
+ *   - otherActiveChanges: 脏文件落在 .sillyspec/changes/<他者变更>/ 下去重成的变更名集合
+ *
+ * 非阻塞 advisory：检测结果仅在调用点本地消费（→ formatConcurrentWarning → console.warn），
+ * 不改 audit status / gate 通过性 / isQuickMetadata 语义（design §2/§9）。
+ *
+ * 纯函数无副作用：不写盘、不 console（console 留给调用点 task-02/03）。
+ */
+import { safeGit, parsePorcelainPath, isQuickMetadata } from './shared.js'
+
+/**
+ * 内联解析 .sillyspec/changes/<dir>/ 路径取 <dir>。
+ * 与 shared.js isQuickMetadata 内部 regex（^\.sillyspec\/changes\/([^/]+)(\/|$)）同源——
+ * D-008 deferred：暂不抽 shared.js 公共 helper，改其一改其二。
+ * @param {string} file 已归一化（正斜杠）的 git 路径
+ * @returns {string|null} 变更目录名，不在 changes/ 下返回 null
+ */
+function extractChangeDir(file) {
+  const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
+  return m ? m[1] : null
+}
+
+/** git 路径反斜杠归一（跨平台 Windows 兼容）。 */
+function normalizeGitPath(p) {
+  return String(p).replace(/\\/g, '/')
+}
+
+/**
+ * 检测工作树里的并发他者改动（非阻塞 advisory 用）。
+ *
+ * @param {string} cwd 主仓库根
+ * @param {{ changeName: string, linkedChanges?: string[], ownFiles?: string[], specDir?: string }} opts
+ *   - changeName: 当前变更名（排除自身变更目录）
+ *   - linkedChanges: 关联变更（透传给 isQuickMetadata 的关联归类，同时从 otherActiveChanges 排除）
+ *   - ownFiles: 本 --done 负责的文件（从 foreignFiles 排除，避免把自己当他者）
+ *   - specDir: 规范目录（保留参数，当前实现用 .sillyspec/ 前缀 regex 定位，暂未使用）
+ * @returns {{ hasForeign: boolean, foreignFiles: string[], otherActiveChanges: string[], gitError: string|null }}
+ *   - foreignFiles: 脏文件里非 metadata、不在 ownFiles 的真实业务文件
+ *   - otherActiveChanges: 脏文件落在 .sillyspec/changes/<他者变更>/ 下，去重成的变更名集合
+ *   - gitError: git status 读失败时填错误串，hasForeign=false（FR-04 fail-open，不抛异常）
+ */
+export function detectConcurrentChanges(cwd, { changeName, linkedChanges = [], ownFiles = [], specDir } = {}) {
+  // safeGit 必传 trim:false（D-004）：porcelain 首行前导空格是状态码一部分，trim 会削掉致
+  // parsePorcelainPath 丢首字符（坑见 shared.js auditQuickCompletion :448 注释）。
+  const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+
+  // FR-04 fail-open：git status 读不到不崩、不阻断、不误报（advisory 漏报可接受，最坏漏报而非误阻）。
+  if (statusResult.error) {
+    return { hasForeign: false, foreignFiles: [], otherActiveChanges: [], gitError: statusResult.error }
+  }
+
+  const gitStatus = statusResult.value || ''
+  // 不整段 trim：同 auditQuickCompletion :455 注释，会削首行前导空格致首文件路径丢首字符。
+  const entries = gitStatus.split('\n').filter(Boolean)
+
+  // 本变更 + 关联变更目录集合：rule1 据此把「自己/关联」从他者变更中排除。
+  const ownChangeSet = new Set(
+    (Array.isArray(linkedChanges) ? linkedChanges : [])
+      .map(normalizeGitPath)
+      .filter(Boolean)
+  )
+  if (changeName) ownChangeSet.add(normalizeGitPath(changeName))
+
+  // ownFiles 归一化集合：rule3 据此把本会话产出从他者业务文件中排除。
+  const ownFileSet = new Set(
+    (Array.isArray(ownFiles) ? ownFiles : [])
+      .map(normalizeGitPath)
+      .filter(Boolean)
+  )
+
+  const foreignFiles = []
+  const otherActiveSet = new Set()
+
+  for (const line of entries) {
+    // parsePorcelainPath：去引号 / 处理 rename / 归一化反斜杠（跨平台）。
+    const file = parsePorcelainPath(line)
+    if (!file) continue
+
+    // rule1：落 .sillyspec/changes/<dir>/ 且 <dir> 非本变更非关联 → otherActiveChanges 去重。
+    const dir = extractChangeDir(file)
+    if (dir && !ownChangeSet.has(normalizeGitPath(dir))) {
+      otherActiveSet.add(dir)
+      continue
+    }
+
+    // rule2：isQuickMetadata 为 true（quick 元数据 / 关联变更目录 / quicklog/.runtime/modules 等）→ 跳过。
+    // 注意：当前变更自己的 changes/<changeName>/ 也走这里——changeName 通常不在 linkedChanges，
+    // isQuickMetadata 视为元数据放行，与本变更自身目录不该当他者的语义一致。
+    if (isQuickMetadata(file, linkedChanges)) continue
+
+    // rule3：真实业务文件 → 不在 ownFiles 则归入他者 foreignFiles。
+    if (!ownFileSet.has(file)) {
+      foreignFiles.push(file)
+    }
+  }
+
+  const otherActiveChanges = [...otherActiveSet]
+  const hasForeign = foreignFiles.length > 0 || otherActiveChanges.length > 0
+  return { hasForeign, foreignFiles, otherActiveChanges, gitError: null }
+}
+
+/**
+ * 把检测结果格式化为多行 ⚠️ 警告串。
+ * @param {{ hasForeign: boolean, foreignFiles?: string[], otherActiveChanges?: string[], gitError?: string|null }|null} detected
+ * @returns {string|null} 无他者并发（hasForeign 为 false / null 输入）返回 null，调用点据此跳过 console.warn
+ */
+export function formatConcurrentWarning(detected) {
+  if (!detected || !detected.hasForeign) return null
+  const foreignFiles = Array.isArray(detected.foreignFiles) ? detected.foreignFiles : []
+  const otherActiveChanges = Array.isArray(detected.otherActiveChanges) ? detected.otherActiveChanges : []
+
+  const lines = ['⚠️ 检测到工作树存在并发他者改动（非阻断 advisory，请人工确认）：']
+
+  if (foreignFiles.length > 0) {
+    lines.push('他者业务文件（git-dirty，可能非本变更产出）：')
+    for (const f of foreignFiles) lines.push(`  - ${f}`)
+  }
+
+  if (otherActiveChanges.length > 0) {
+    // D-005：文案用「脏变更目录」+ git-dirty 标注，勿用「活跃」防与 DB active 状态混淆。
+    lines.push('他者脏变更目录（git-dirty，非 DB active）：')
+    for (const c of otherActiveChanges) lines.push(`  - ${c}`)
+  }
+
+  lines.push('提交请用显式 pathspec 隔离本变更文件，勿 git add . 扫入他者工作。')
+  return lines.join('\n')
+}