sillyspec 3.22.8 → 3.23.0

package/src/run.js

@@ -6,6 +6,7 @@
  */
 import { basename, join, resolve, dirname, relative, isAbsolute } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, rmSync, statSync } from 'fs'
+import { randomBytes, randomUUID } from 'crypto'
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
@@ -705,16 +706,23 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<change-name>')) {
     promptText = promptText.replace(/<change-name>/g, changeName)
   }
-  // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-guard.json 读关联变更）
+  // 替换 <quick-session-id> 占位符（quick 阶段专用：sessionId == changeName == quick-<uuid8>，
+  // 见 runStage 参数解析 quickSessionId 生成。告知 agent 本会话 id + --done 需带 --change）
+  if (changeName && promptText.includes('<quick-session-id>')) {
+    promptText = promptText.replace(/<quick-session-id>/g, changeName)
+  }
+  // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-sessions/<sessionId>/guard.json 读关联变更）
   if (promptText.includes('<linked-changes>')) {
     const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
     let linkedChanges = []
     try {
-      const guardFile = join(specBaseLc, '.runtime', 'quick-guard.json')
-      if (existsSync(guardFile)) {
-        const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
-        linkedChanges = Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []
-      }
+      // D-002：guard 按 session 存。changeName == quick-<uuid8>（见 runStage 参数解析）。回退读旧单文件（兼容 task-03 前）
+      const sessionGuardFile = join(specBaseLc, '.runtime', 'quick-sessions', changeName, 'guard.json')
+      const legacyGuardFile = join(specBaseLc, '.runtime', 'quick-guard.json')
+      const guard = existsSync(sessionGuardFile)
+        ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
+        : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
+      if (guard) linkedChanges = Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []
     } catch {}
     const display = linkedChanges.length > 0 ? linkedChanges.join(', ') : '（无）'
     promptText = promptText.replace(/<linked-changes>/g, display)
@@ -776,6 +784,16 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
       platformDirectives.push(`workspace_id: ${platformOpts.workspaceId}`)
     }
     promptText = platformDirectives.join('\n') + '\n\n' + promptText
+  } else {
+    // 常规模式（无平台 specRoot）：占位符替换为 cwd/.sillyspec 下对应路径
+    // 让用 {SPEC_ROOT}/{DOCS_ROOT} 等占位符的 prompt（如 quick/scan）在常规模式也写到正确位置
+    const projectName = dbProjectName || basename(cwd)
+    const specSillyspec = join(cwd, '.sillyspec')
+    promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, join(specSillyspec, 'docs', projectName))
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, join(specSillyspec, 'projects'))
+    promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, join(specSillyspec, 'workflows'))
+    promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, join(specSillyspec, 'knowledge'))
   }
 
   // 注入 scanProfile 硬约束指令
@@ -1368,12 +1386,52 @@ export async function runCommand(args, cwd, specDir = null) {
   if (explicitLinked !== null) {
     linkedChanges = explicitLinked
   }
-  // quick 的 progress 键固定走 'default'：归属语义已由 linkedChanges 承担（→ quick-guard.json
-  // → <linked-changes> 占位符注入 prompt）。progress 不能走 pm.read(cwd, null) 的自动检测——
-  // 多活跃 change 项目里 quick 步骤进度会随活跃 change 增减在各 change/default 间漂移，
-  // 表现为 --done 时「回退」到更早步骤。固定 default 后无论是否带 --change 都稳定。
+  // quick 会话隔离（D-001@v1 + D-003@v1 + §4.4 跨进程传递）：每会话用 sessionId 作 changeName，
+  // DB 分行 progress.quick-<uuid8>，避免并行 quick 会话共享单行 progress.default.quick 互相覆盖。
+  // sessionId = crypto.randomUUID 前 8 hex（摒弃旧 quick-YYYYMMDD-HHMMSS 时间戳，同秒并发撞）。
+  // crypto.randomUUID 从 node:crypto import（兼容 engines node>=18，不依赖 Node 19+ 全局）。
+  //
+  // --done 跨进程恢复 sessionId 的优先级（§4.4）：
+  //   1. --change quick-<uuid8>（单值且匹配 sessionId 形态）→ 精确指定本会话 sessionId
+  //      （quick 的 --change 历史被复用为 linkedChanges 见上 1370-1377；此处对「恰好一个 quick-<8hex>」
+  //       特例识别为 sessionId，多值/不匹配仍走 linkedChanges 语义，向后兼容）
+  //   2. 未识别出 sessionId 且为 --done → fallback 读 .runtime/current-quick-run-id（单会话兼容；
+  //      多会话时可能拿到他者，文档声明建议带 --change）
+  //   3. 仍读不到 → 生成新 UUID（兼容旧行为；进度可能命中空行，由后续 pm.read 兜底）
+  const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
+  let quickSessionId = null
   if (stageName === 'quick') {
-    changeName = 'default'
+    // 1373-1376 已把 quick 的 --change 值清进 linkedChanges、changeName 置 null。
+    // 此处回看 --change 原始值：若恰好是单个 quick-<8hex> → 识别为本会话 sessionId（精确恢复），
+    // 并撤销把它当 linkedChanges 的误判。多值或不匹配 → 维持 linkedChanges 语义（旧兼容）。
+    const rawChange = changeIdx !== -1 && flags[changeIdx + 1] ? flags[changeIdx + 1].trim() : null
+    const rawIsSingleSid = rawChange && rawChange.indexOf(',') === -1 && QUICK_SID_RE.test(rawChange)
+    if (rawIsSingleSid) {
+      // --done --change quick-<uuid8>：精确恢复（撤销 1373-1376 把它误当 linkedChanges）
+      quickSessionId = rawChange
+      changeName = rawChange
+      linkedChanges = []
+    } else if (!changeName) {
+      // 未精确指定：非 --done 必生成新 sessionId；--done 先 fallback current-quick-run-id，读不到再生成
+      const isDoneLike = isDone || isStatus || isSkip || isReset || isReopen
+      if (isDoneLike) {
+        try {
+          const runtimeRoot = platformOpts.runtimeRoot || join(specRoot, '.runtime')
+          const idFile = join(runtimeRoot, 'current-quick-run-id')
+          if (existsSync(idFile)) {
+            const v = readFileSync(idFile, 'utf8').trim()
+            if (QUICK_SID_RE.test(v)) quickSessionId = v
+          }
+        } catch {}
+      }
+      if (!quickSessionId) {
+        quickSessionId = 'quick-' + randomUUID().slice(0, 8)
+      }
+      changeName = quickSessionId
+    } else {
+      // 用户显式传了非 sessionId 形态的变更名 → 尊重，不生成 UUID（旧兼容路径）
+      quickSessionId = changeName
+    }
   }
 
   // 解析 --files a.js,b.js（quick 专用：显式声明 allowedFiles）
@@ -1421,13 +1479,16 @@ export async function runCommand(args, cwd, specDir = null) {
   // 关键：--done 收尾时复用首次 run 持久化的 linkedChanges，不在管道/CI 下重复弹交互 prompt。
   // explicitLinked === null 且未传 --change 时才进入此分支（显式 --linked-changes none 不应触发交互）。
   if (stageName === 'quick' && explicitLinked === null && linkedChanges.length === 0) {
-    const guardFile = join(specRoot, '.runtime', 'quick-guard.json')
+    // D-002：guard 按 session 存（.runtime/quick-sessions/<sessionId>/guard.json）。
+    // sessionId == changeName == quick-<uuid8>（上面参数解析已确定）。回退读旧单文件 quick-guard.json（task-03 前兼容）。
     let persistedLinked = null
     try {
-      if (existsSync(guardFile)) {
-        const g = JSON.parse(readFileSync(guardFile, 'utf8'))
-        if (Array.isArray(g.linkedChanges)) persistedLinked = g.linkedChanges
-      }
+      const sessionGuardFile = join(specRoot, '.runtime', 'quick-sessions', changeName, 'guard.json')
+      const legacyGuardFile = join(specRoot, '.runtime', 'quick-guard.json')
+      const g = existsSync(sessionGuardFile)
+        ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
+        : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
+      if (g && Array.isArray(g.linkedChanges)) persistedLinked = g.linkedChanges
     } catch {}
     if (persistedLinked) {
       linkedChanges = persistedLinked
@@ -1466,7 +1527,7 @@ export async function runCommand(args, cwd, specDir = null) {
           process.exit(1)
         }
         const date = new Date().toISOString().slice(0, 10)
-        const autoName = `${date}-new-change`
+        const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
         console.log(`🔄 自动创建变更：${autoName}`)
         console.log(`  提示：可以用 --change <名称> 指定自定义变更名`)
         console.log(`  或事后重命名：sillyspec change-rename ${autoName} <新名称>`)
@@ -1571,9 +1632,10 @@ export async function runCommand(args, cwd, specDir = null) {
     }
   }
 
-  // quick 启动（非 --done）：reset steps + 生成 quickRunId，避免多会话共享 progress.default.quick
-  // 继承并行会话的 step1（会话 B 复用会话 A 的 ql，本会话改动无 ql 记录）。C-实用方案：
-  // 每次 quick 启动 reset steps（逻辑隔离，本会话从 step1 重跑建独立 ql）+ 写 current-quick-run-id。
+  // quick 启动（非 --done）：reset steps + 写 current-quick-run-id（本会话 sessionId，作 --done fallback）。
+  // sessionId 已在参数解析阶段生成（quickSessionId == changeName == quick-<uuid8>），
+  // 这里复用同一值写 current-quick-run-id，保证两处一致。
+  // 旧 quick-YYYYMMDD-HHMMSS 时间戳已摒弃（D-003@v1：同秒并发撞）。
   if (stageName === 'quick' && !isDone && !isStatus && !isSkip && !isReset && !isReopen) {
     const qStage = progress.stages?.quick
     if (qStage?.steps?.length) {
@@ -1581,13 +1643,14 @@ export async function runCommand(args, cwd, specDir = null) {
       qStage.status = 'in-progress'
     }
     try {
-      const now = new Date()
-      const pad = (n) => String(n).padStart(2, '0')
-      const quickRunId = `quick-${now.getFullYear()}-${pad(now.getMonth()+1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
       const runtimeRoot = platformOpts.runtimeRoot || join(specRoot, '.runtime')
       mkdirSync(runtimeRoot, { recursive: true })
-      writeFileSync(join(runtimeRoot, 'current-quick-run-id'), quickRunId)
+      writeFileSync(join(runtimeRoot, 'current-quick-run-id'), quickSessionId + '\n')
     } catch {}
+    // 显式告知 agent 本会话 sessionId + --done 需带 --change（CLI 短进程，run/done 独立进程，
+    // sessionId 靠 --change 跨进程传递；不带 --change 时 fallback 读 current-quick-run-id，多会话不可靠）
+    console.log(`📌 本 quick 会话 sessionId: ${quickSessionId}`)
+    console.log(`   完成时用: sillyspec run quick --done --change ${quickSessionId} --output "..."`)
   }
 
   // 确保步骤已初始化
@@ -1898,6 +1961,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
       const allowNew = quickOpts?.isAllowNew || false
       const forceBaseline = quickOpts?.isForceBaseline || false
       progress.quickGuard = {
+        sessionId: changeName,
         name_zh: '快速任务守卫',
         baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
         baselineFiles,
@@ -1907,8 +1971,11 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         linkedChanges: Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : [],
         startedAt: new Date().toISOString(),
       }
-      // 写入 quick-guard.json 供 worktree-guard hook 读取
-      const guardFile = join(specBase, '.runtime', 'quick-guard.json')
+      // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
+      // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
+      const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', changeName)
+      mkdirSync(sessionGuardDir, { recursive: true })
+      const guardFile = join(sessionGuardDir, 'guard.json')
       writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
       const parts = [`${baselineFiles.length} 个已有脏文件`]
       if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
@@ -2355,6 +2422,48 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
         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) {
+      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${nextStageHint}${changeName ? ` --change ${changeName}` : ''}`)
+      if (stageName === 'execute') {
+        console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
+        console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)
+        // plan.md checkbox auto-check：execute 完成 + review.json pass → 自动勾选（治本，比警告可靠）
+        try {
+          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 runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+          if (existsSync(planPath) && existsSync(runIdFile)) {
+            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}`   // 勾选
+              }
+              skippedCount++
+              return match              // 不勾
+            })
+            if (checkedCount > 0) {
+              writeFileSync(planPath, updated)
+              console.log(`   ✅ 自动勾选 ${checkedCount} 个 task checkbox（基于 review.json pass）`)
+            }
+            if (skippedCount > 0) {
+              console.warn(`   ⚠️ ${skippedCount} 个 task 未勾（review.json 缺失/fail）→ archive 会拦。补 review 后重跑 execute --done 触发自动勾`)
+            }
+          }
+        } catch {}
+      }
+    }
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
@@ -2476,6 +2585,26 @@ async function ensureDepsFreshness(cwd, changeName, specBase, worktreeMeta) {
   }
 }
 
+/**
+ * 阶段完成校验失败时回滚状态。
+ *
+ * completeStep 在跑 validator 之前就把 stageData.status 写成 'completed'，
+ * 若校验失败不回滚，DB 会与真实产物不一致（hook/doctor/下游阶段全部误判），
+ * 且所有步骤都是 completed 时 agent 无法重新 --done（"没有待完成的步骤"）。
+ * 此处将 stage 回滚为 in-progress，最后一步重置为 pending，供修复产物后重做。
+ */
+function rollbackStageCompletion(stageData, steps, currentIdx) {
+  // 辅助阶段在 validator 前已被重置为 pending（steps 也换成了新数组），不要覆盖
+  if (stageData.status === 'completed') {
+    stageData.status = 'in-progress'
+    stageData.completedAt = null
+  }
+  if (steps[currentIdx] && steps[currentIdx].status === 'completed') {
+    steps[currentIdx].status = 'pending'
+    steps[currentIdx].completedAt = null
+  }
+}
+
 async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, confirmMode = null } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
@@ -2834,27 +2963,45 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       if (!hasQuicklog) {
         console.error(`\n❌ quick 阶段完成校验失败：未检测到 QUICKLOG 记录文件。`)
         console.error(`   step 2 要求创建 quicklog 记录，但文件不存在。`) 
-        console.error(`   请先创建 quicklog 记录再 --done，或使用 --skip-approval 跳过此校验。`)
+        console.error(`   请先创建 quicklog 记录再 --done。`)
         return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
       }
-      if (progress.quickGuard) {
-        const review = await auditQuickCompletion(cwd, progress.quickGuard, { isConfirm })
-        progress.quickGuard.review = review
-        progress.quickGuard.completedAt = new Date().toISOString()
-        printQuickAuditReview(review)
-        if (review.status === 'blocked') {
-          steps[currentIdx].status = 'pending'
-          steps[currentIdx].completedAt = null
-          if (outputText) steps[currentIdx].output = null
-          process.exit(1)
+      // §4.6 quick 收尾：从 session guard.json 读 guard（不依赖 progress.quickGuard）。
+      // D-003@v1：progress._write 不持久化顶层 quickGuard，跨进程 --done 时读出的 progress 无 quickGuard，
+      // 若仍用 if (progress.quickGuard) 驱动收尾会整体跳过，导致 .runtime/quick-sessions/<sessionId>/ 残留僵尸。
+      // 改为从文件读 guard：优先 session 目录 guard.json，回退旧单文件 quick-guard.json（task-03 前兼容）。
+      // sessionId == changeName == quick-<uuid8>（completeStep 作用域内 changeName 已解构自 options）。
+      {
+        const runtimeBase = platformOpts.runtimeRoot || join(specBase, '.runtime')
+        const sessionGuardFile = join(runtimeBase, 'quick-sessions', changeName, 'guard.json')
+        const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
+        let guard = null
+        try {
+          guard = existsSync(sessionGuardFile)
+            ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
+            : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
+        } catch {}
+        if (guard) {
+          const review = await auditQuickCompletion(cwd, guard, { isConfirm: confirm })
+          printQuickAuditReview(review)
+          if (review.status === 'blocked') {
+            steps[currentIdx].status = 'pending'
+            steps[currentIdx].completedAt = null
+            if (outputText) steps[currentIdx].output = null
+            process.exit(1)
+          }
+          progress.lastQuickReview = review
         }
+        // 清理：guard 命中与缺失两种情况都执行（guard 缺失 → 跳过审计，仅清理不抛错）。
+        // rmSync {recursive,force} / unlinkSync 都容忍文件不存在（brownfield）。
         try {
           const { unlinkSync } = await import('fs')
-          const guardFile = join(specBase, '.runtime', 'quick-guard.json')
-          unlinkSync(guardFile)
+          if (changeName) {
+            const sessionDir = join(runtimeBase, 'quick-sessions', changeName)
+            rmSync(sessionDir, { recursive: true, force: true })
+          }
+          if (existsSync(legacyGuardFile)) unlinkSync(legacyGuardFile)
         } catch {}
-        progress.lastQuickReview = review
-        delete progress.quickGuard
       }
     }
 
@@ -3072,10 +3219,11 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         for (const err of contractResult.errors) {
           console.error(`   - ${err}`)
         }
-        console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
+        console.error(`\n   提示：修复缺失产物后重新完成此步骤（--skip-approval 只跳过阶段转换/审批检查，不能跳过产物校验）`)
         // 产物校验失败必须阻断完成 —— 否则 validator 形同虚设，
         // verify 会带着 FAIL/缺 verify-result.md 被 ✅ 标记完成（历史教训）。
         // plan/execute 的专项契约校验（下方）在产物齐全后才需要继续跑，故此处先 return。
+        rollbackStageCompletion(stageData, steps, currentIdx)
         progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
         await pm._write(cwd, progress, changeName)
         triggerSync(cwd, changeName, platformOpts)
@@ -3088,8 +3236,22 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         }
       }
 
-      // verify 产物校验通过 + 结论非 FAIL（否则上面已阻断），此时才能声称"验证通过"
+      // verify 产物校验通过 + 结论非 FAIL（否则上面已阻断）。
+      // 再由 CLI 亲自执行 local.yaml 的测试命令，与 verify-result.md 的自报告对账：
+      // 自报告 PASS 但实测失败 → 阻断（防止"文案通过"绕过验证）。
       if (stageName === 'verify') {
+        const { runVerifyTestCheck, printVerifyTestCheck } = await import('./verify-postcheck.js')
+        const testCheck = runVerifyTestCheck({ cwd, specBase, changeName })
+        printVerifyTestCheck(testCheck)
+        if (testCheck.status === 'failed') {
+          console.error('\n❌ verify 阶段被阻断：verify-result.md 自报告通过，但 CLI 实测测试失败。')
+          console.error('   请修复失败的测试并更新 verify-result.md 后重新完成此步骤。')
+          rollbackStageCompletion(stageData, steps, currentIdx)
+          progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+          await pm._write(cwd, progress, changeName)
+          triggerSync(cwd, changeName, platformOpts)
+          return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+        }
         console.log('\n✅ 验证通过，下一步：sillyspec run archive')
       }
 
@@ -3106,6 +3268,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
             for (const err of planValidation.errors) console.error(`   - ${err}`)
             console.error(`\n   plan.md 不满足 execute 契约，请修复后重新完成此步骤。`)
             // 阻断 completed
+            rollbackStageCompletion(stageData, steps, currentIdx)
             progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
             await pm._write(cwd, progress, changeName)
             triggerSync(cwd, changeName, platformOpts)
@@ -3146,7 +3309,18 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
               executeRunId = generateExecuteRunId()
             }
 
-            const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId, changeDir: planFile })
+            // git 真实性校验目录：worktree 存在则用 worktree（base/head commit 在其中），否则主仓库
+            let reviewGitDir = cwd
+            try {
+              const { WorktreeManager } = await import('./worktree.js')
+              const wm = new WorktreeManager({ cwd })
+              const meta = wm.getMeta(changeName)
+              if (meta?.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
+                reviewGitDir = meta.worktreePath
+              }
+            } catch {}
+
+            const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId, changeDir: planFile, gitDir: reviewGitDir })
             printReviewResult(reviewResult)
 
             if (!reviewResult.ok) {
@@ -3157,6 +3331,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
                 console.error('\n⚠️  部分任务已在 plan.md 中勾选，但 review.json 不存在。')
                 console.error('   请取消勾选这些任务的 checkbox，或补充对应的 review.json。')
               }
+              rollbackStageCompletion(stageData, steps, currentIdx)
               progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
               await pm._write(cwd, progress, changeName)
               triggerSync(cwd, changeName, platformOpts)
@@ -3173,8 +3348,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
             }
           }
         } catch (e) {
-          console.warn(`⚠️ Task Review Gate 异常: ${e.message}`)
-          // 不阻断，但记录异常
+          // fail-closed：Gate 自身异常时不能默认放行，否则异常成了绕过评审的通道
+          console.error(`❌ Task Review Gate 异常，阻断 execute 完成: ${e.message}`)
+          console.error('   请检查 review.json / plan.md 是否可读，修复后重新完成此步骤。')
+          rollbackStageCompletion(stageData, steps, currentIdx)
+          progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+          await pm._write(cwd, progress, changeName)
+          triggerSync(cwd, changeName, platformOpts)
+          return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
         }
       }
     } else if (actualCompleted < actualTotal) {

package/src/stage-contract.js

@@ -7,6 +7,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'fs'
 import { join, basename } from 'path'
+import { execFileSync } from 'child_process'
 import { detectChangeRisk, checkIntegrationEvidence } from './change-risk-profile.js'
 
 /**
@@ -528,6 +529,111 @@ function validateChangeClosed(cwd, changeName) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+// ============ Execute 代码变更客观核验 ============
+
+function gitTry(dir, args) {
+  try {
+    const out = execFileSync('git', args, {
+      cwd: dir,
+      encoding: 'utf8',
+      timeout: 15000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim()
+    return { ok: true, out }
+  } catch (e) {
+    return { ok: false, out: '', error: e.message?.split('\n')[0] || String(e) }
+  }
+}
+
+/**
+ * 客观核验 execute 阶段是否产生了真实代码变更。
+ *
+ * 历史漏洞：execute 无 stage-level validator，agent 勾选 plan.md 全部 checkbox
+ * 即可让 execute 被标 completed，代码完成度与真实变更完全脱钩。
+ *
+ * 判定顺序（fail-open on uncertainty，避免环境差异误杀）：
+ *   1. worktree meta 存在且有 baseHash → 在 worktree 内查 baseHash..HEAD diff + 未提交改动
+ *   2. sillyspec/<change> 分支存在 → 查 merge-base..branch diff
+ *   3. 主工作区存在未提交改动（apply 后未 commit 的常见形态）→ changed
+ *   4. 均无法判定 → unknown（由调用方降级为 warning）
+ *
+ * @returns {{ status: 'changed'|'unchanged'|'unknown', detail: string }}
+ */
+export function checkExecuteCodeEvidence(cwd, changeName) {
+  const metaPath = join(cwd, '.sillyspec', '.runtime', 'worktrees', changeName, 'meta.json')
+  let meta = null
+  if (existsSync(metaPath)) {
+    try { meta = JSON.parse(readFileSync(metaPath, 'utf8')) } catch {}
+  }
+
+  // 1. worktree（或 in-place）meta 有 baseHash：最权威的对账基准
+  if (meta?.baseHash) {
+    const gitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+      ? meta.worktreePath
+      : cwd
+    const diff = gitTry(gitDir, ['diff', '--name-only', `${meta.baseHash}..HEAD`])
+    const status = gitTry(gitDir, ['status', '--porcelain'])
+    if (diff.ok && status.ok) {
+      const committedFiles = diff.out ? diff.out.split('\n').filter(Boolean).length : 0
+      const hasUncommitted = status.out.trim().length > 0
+      if (committedFiles > 0 || hasUncommitted) {
+        return { status: 'changed', detail: `${committedFiles} 个已提交变更文件${hasUncommitted ? ' + 未提交改动' : ''}（base ${meta.baseHash.slice(0, 8)}）` }
+      }
+      return { status: 'unchanged', detail: `${gitDir} 相对 base ${meta.baseHash.slice(0, 8)} 无任何提交或未提交改动` }
+    }
+    return { status: 'unknown', detail: `git 核验失败: ${diff.error || status.error}` }
+  }
+
+  // 2. worktree 已清理但分支残留：diff merge-base..branch
+  const branch = `sillyspec/${changeName}`
+  const branchHash = gitTry(cwd, ['rev-parse', '--verify', '--quiet', branch])
+  if (branchHash.ok && branchHash.out) {
+    const mergeBase = gitTry(cwd, ['merge-base', 'HEAD', branch])
+    if (mergeBase.ok && mergeBase.out) {
+      const diff = gitTry(cwd, ['diff', '--name-only', `${mergeBase.out}..${branch}`])
+      if (diff.ok && diff.out.split('\n').filter(Boolean).length > 0) {
+        return { status: 'changed', detail: `分支 ${branch} 相对 merge-base 有变更` }
+      }
+    }
+  }
+
+  // 3. 主工作区未提交改动（worktree apply 后的常见形态）
+  const status = gitTry(cwd, ['status', '--porcelain'])
+  if (status.ok && status.out.trim()) {
+    return { status: 'changed', detail: '主工作区存在未提交改动' }
+  }
+
+  return { status: 'unknown', detail: '无 worktree meta 且无可对账的分支/未提交改动（变更可能已 apply 并提交），无法客观判定' }
+}
+
+/**
+ * execute 完成校验：plan.md 声明了任务时，必须存在真实代码变更。
+ * 防止"勾选 checkbox = 完成 execute"的谎报路径。
+ */
+function validateExecuteOutputs(cwd, changeName, context = {}) {
+  const { specRoot } = context
+  const errors = []
+  const warnings = []
+
+  const changeDir = resolveChangeDir(cwd, changeName, specRoot)
+  const planPath = join(changeDir, 'plan.md')
+  // 无 plan.md 的 execute（旧流程/quick 混用）不在此核验范围
+  if (!existsSync(planPath)) return { ok: true, errors, warnings }
+
+  const planContent = readFileSync(planPath, 'utf8')
+  const hasTasks = /^\s*[-*]\s*\[[ xX]\]\s*task-\d+/m.test(planContent)
+  if (!hasTasks) return { ok: true, errors, warnings }
+
+  const evidence = checkExecuteCodeEvidence(cwd, changeName)
+  if (evidence.status === 'unchanged') {
+    errors.push(`execute 代码变更核验失败：plan.md 声明了任务，但 ${evidence.detail} — 勾选 checkbox 不等于完成实现`)
+  } else if (evidence.status === 'unknown') {
+    warnings.push(`execute 代码变更无法客观核验：${evidence.detail}`)
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
 // ============ Contract Registry ============
 
 /**
@@ -564,7 +670,7 @@ const contracts = {
     description: '代码实现',
     allowedFrom: ['plan'],
     allowedTo: ['verify'],
-    validators: [],
+    validators: [validateExecuteOutputs],
   },
   verify: {
     stage: 'verify',

package/src/stages/brainstorm-auto.js

@@ -22,7 +22,7 @@ export const definition = {
 ### 操作
 1. 运行 \`sillyspec progress show\`，确认 currentStage 为 "brainstorm"
 2. 如果未初始化，提示先运行 sillyspec init
-3. **检查变更名称**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change\`），直接重命名为有意义名称，然后运行 \`sillyspec change-rename <旧名> <新名>\`
+3. **检查变更名称**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），直接重命名为有意义名称，然后运行 \`sillyspec change-rename <旧名> <新名>\`
 
 ### 加载上下文
 4. 读取 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文

package/src/stages/brainstorm.js

@@ -12,7 +12,7 @@ export const definition = {
 2. 确认 currentStage 为 "brainstorm"
 3. 如果有进行中的 brainstorm，提示选择继续或重新开始
 4. 如果未初始化，提示先运行 sillyspec init
-5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
+5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
 
 ### 输出
 当前状态摘要（1-2 句话）