sillyspec 3.22.9 → 3.23.0

package/src/run.js

@@ -6,7 +6,7 @@
  */
 import { basename, join, resolve, dirname, relative, isAbsolute } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, rmSync, statSync } from 'fs'
-import { randomBytes } from 'crypto'
+import { randomBytes, randomUUID } from 'crypto'
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
@@ -706,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)
@@ -1379,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）
@@ -1432,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
@@ -1582,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) {
@@ -1592,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 "..."`)
   }
 
   // 确保步骤已初始化
@@ -1909,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,
@@ -1918,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`)
@@ -2529,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')
@@ -2887,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
       }
     }
 
@@ -3125,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)
@@ -3141,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')
       }
 
@@ -3159,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)
@@ -3199,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) {
@@ -3210,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)
@@ -3226,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/quick.js

@@ -8,6 +8,12 @@ export const definition = {
       name: '理解任务',
       prompt: `解析任务参数，加载项目上下文。
 
+### 📌 本 quick 会话 sessionId: \`<quick-session-id>\`
+- CLI 是短进程，run 与 done 是独立进程，sessionId 靠 \`--change\` 跨进程传递
+- **完成每个 step 用**：\`sillyspec run quick --done --change <quick-session-id> --output "..."\`
+  - 多会话并发时**必须带 \`--change <quick-session-id>\`**，否则可能命中他者会话的状态
+  - 不带 \`--change\` 时 fallback 读 \`current-quick-run-id\`（单会话兼容；多会话不可靠）
+
 ### 操作
 1. 检查关联变更（\`<linked-changes>\`，逗号分隔的变更名列表；显示「（无）」= 不关联变更），确定记录方式
 2. 理解任务：模糊则问一个问题确认
@@ -81,6 +87,11 @@ quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上
       name: '暂存和更新记录',
       prompt: `Git 暂存并更新任务记录。
 
+### 📌 收尾确认 — sessionId: \`<quick-session-id>\`
+- 本步骤是最后一步，完成后 quick 会话即结束
+- **完成本 step 用**：\`sillyspec run quick --done --change <quick-session-id> --output "暂存和记录确认"\`
+  - 多会话并发**必须带 \`--change <quick-session-id>\`**，不带会 fallback 读 \`current-quick-run-id\` 可能命中他者会话
+
 ### 操作
 1. 查看 \`git status --porcelain\`，确认只包含本次 quick 相关文件
 2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）

package/src/stages/scan.js

@@ -182,19 +182,15 @@ export const definition = {
 
 ### 操作
 1. 检查 {SPEC_ROOT}/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
-2. 根据项目类型生成默认配置：
-   - **Node.js**（有 package.json）：build: "npm run build", test: "npm test", lint: "npm run lint", type: nodejs
-   - **Maven**（有 pom.xml）：build: "mvn compile", test: "mvn test", lint: "mvn checkstyle:check", type: maven
-   - **Gradle**（有 build.gradle）：build: "./gradlew build", test: "./gradlew test", type: gradle
-   - **通用项目**：只写注释模板, type: generic
-3. 确保目录存在：mkdir -p {SPEC_ROOT}
-4. 原子写入（先写 tmp 文件再 rename）
-
-### 文件格式
+2. 调用 \`sillyspec local detect\` 命令生成 local.yaml（该命令封装了纯 fs 项目类型嗅探：package.json→nodejs / pom.xml→maven / build.gradle→gradle / Makefile→make / 否则 generic，对应默认 commands）。**不要自行嗅探 package.json/pom.xml/build.gradle 等文件**——探测逻辑唯一归属 local-detect.js，本步骤只负责调用命令并报告结果。
+3. 该命令内部已处理：确保目录存在（mkdir -p）、已存在则跳过、原子写入（先写 tmp 再 rename）。
+4. 报告生成的 project.type 与 local.yaml 路径。
+
+### 输出格式参考（由 \`sillyspec local detect\` 自动产出）
 \`\`\`yaml
 # SillySpec 本地配置（自动生成，可手动修改）
 project:
-  type: nodejs  # nodejs/maven/gradle/generic
+  type: nodejs  # nodejs/maven/gradle/make/generic
 
 commands:
   build: "npm run build"
@@ -203,15 +199,10 @@ commands:
 
 # 测试策略：full=全量测试, module=只测变更模块, skip=跳过测试
 test_strategy: module
-
-# 模块测试路径映射（可选）
-# module_paths:
-#   user-service: "user/"
-#   order-service: "order/"
 \`\`\`
 
 ### 输出
-local.yaml 生成结果（已存在/已生成）`,
+local.yaml 生成结果（已存在/已生成 + project.type）`,
       outputHint: 'local.yaml 生成状态',
       optional: false
     },

package/src/stages/verify.js

@@ -223,6 +223,7 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 ### 注意
 - 不要全量编译/测试整个项目，只测变更涉及的模块
 - 如果变更模块不确定，优先使用 local.yaml 中的命令
+- **CLI 对账机制**：verify 阶段最终 --done 时，CLI 会亲自执行 local.yaml 的 commands.test 并与你的报告对账；实测失败会直接阻断 verify 完成，谎报测试结果没有意义
 
 ### 输出
 测试结果 + 技术债务标记`,
@@ -314,7 +315,8 @@ verify-result.md 路径 + 验证报告摘要 + 下一步命令
 ### 注意
 - PASS → 运行 \`sillyspec run archive\` 归档
 - FAIL → 修复后运行 \`sillyspec run verify\` 重新验证
-- verify-result.md 是变更包的正式验收记录，归档后保留`,
+- verify-result.md 是变更包的正式验收记录，归档后保留
+- **CLI 对账机制**：本步骤 --done 时 CLI 会亲自执行 local.yaml 的 commands.test；结论写 PASS 但实测失败 → verify 完成被阻断`,
       outputHint: '验证报告',
       optional: false
     }