sillyspec 3.28.8 → 3.28.10

package/src/run/complete.js

@@ -22,7 +22,8 @@ import { createHash } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
 import { withFileLock } from '../quicklog.js'
-import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir } from './shared.js'
+import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir, writePlatformDocsPointer } from './shared.js'
+import { isExplicitReviewWrite, collectWorktreeChangedFiles } from '../task-review.js'
 
 // auto 模式 brainstorm 步骤表感知解析（2026-09-08 E2E 实证 bug：--done/--wait 推进主模式 8 步表，
 // 与 runAutoMode getAutoSteps 的 4 步 auto 表双轨互踩——ensureAutoStage 判非 auto 表重种清零，
@@ -119,7 +120,7 @@ export function synthesizeStepOutput({ stageName, stepName, cwd }) {
 }
 
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, quickFiles = [] } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
   // 与 prompt.js resolvePromptSpecBase 同序：--done 收尾的 user-inputs.md/超长 artifact 落盘
   // 必须与 prompt 渲染同一根，否则写进 worktree 副本目录、随 cleanup 整目录删除。
@@ -180,6 +181,29 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
   }
 
+  // ── 意图断言（坑 execute-concurrent-done-skips-next-wave 终解，2026-09-08 实证）──
+  // --step <名|序号> 显式声明本次要完成的步骤；与当前待完成步不一致 → fail-closed 拒绝。
+  // 防并发 --done 主形态：会话 B 先推进 Wave N，会话 A 随后的 --done 落到 Wave N+1 且用
+  // Wave N 的旧摘要静默完成未实现步骤——CLI 短进程无法读心，只有显式声明能硬拦。
+  // 序号 1-based；名称精确或前缀匹配（Wave 名常带「Wave 3 — xxx」长尾，前缀够用且防呆）。
+  if (options.stepAssert) {
+    const declared = String(options.stepAssert).trim()
+    const currentName = steps[currentIdx]?.name || ''
+    let match = false
+    if (/^\d+$/.test(declared)) {
+      match = currentIdx === parseInt(declared, 10) - 1
+    } else {
+      match = currentName === declared || currentName.startsWith(declared)
+    }
+    if (!match) {
+      console.error(`❌ --step 意图断言不匹配：声明完成「${declared}」，当前待完成步骤是「${currentName}」（第 ${currentIdx + 1}/${steps.length} 步）。`)
+      console.error(`   不一致的最常见原因：并行会话刚推进了本变更的步骤（你读的是旧进度）。`)
+      console.error(`   核对：sillyspec progress show${changeName ? ` --change ${changeName}` : ''}；确认要做的是当前步则去掉 --step 重跑，确属误判自己想做的步则修正 --step 值。`)
+      process.exit(1)
+    }
+    console.log(`🛡️ 意图断言通过：--step「${declared}」= 当前步骤「${currentName}」`)
+  }
+
   // ── P0-2（noai-ir-roadmap §3）：--output 省略 → CLI 按事实合成步骤摘要 ──
   // agent 手打摘要是每步命中的幻觉源；事实面（步骤名 + 变更窗口 + 门禁以 CLI 校验为准）
   // CLI 本就持有，纯事实合成零编造（判断词留给 gate）。语义性说明（方案取舍/用户反馈）仍应
@@ -494,7 +518,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, platformOpts })
+    const _archiveEarlyReturn = await handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts, isSkipApply, sessionFlag })
     if (_archiveEarlyReturn) return _archiveEarlyReturn
   }
 
@@ -568,8 +592,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       console.log(`   恢复：sillyspec run ${stageName} --continue --answer "用户回答"${changeName ? ` --change ${changeName}` : ''}`)
       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, isAllowDelete, platformOpts, pm, quickFiles })
+    // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）；
+    // isNoDocs（task-02）--no-docs 豁免随链透传进 auditQuickCompletion options；
+    // sessionFlag（task-03）--session 随链透传进 quick 轻量归档链所有权校验
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag, platformOpts, pm, quickFiles })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤
@@ -663,6 +689,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     const total = steps.length
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
 
+    // 平台模式产物落点指针（platform-docs-dual-location，2026-09-15 EHS 实证）：完成时点在
+    // 工作树 .sillyspec/ 刷新人类可读指针（本地模式零行为，fail-soft 内部全兜）。
+    writePlatformDocsPointer(cwd, changeName, platformOpts, stageName)
+
     // task-04（2026-09-10-change-scope-audit）：execute 完成打范围对账全表+落 .runtime 快照 /
     // verify 完成出一行漂移确认。advisory fail-soft（D-006）——helper 内部全兜，绝不阻断完成。
     await printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts })
@@ -675,7 +705,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         const { consumeFrictionHint } = await import('../friction-tally.js')
         const r = await consumeFrictionHint({ cwd, changeName, platformOpts })
         if (r && r.hint) console.log(`\n${r.hint}`)
-      } catch { /* 摩擦提示失败不影响收尾 */ }
+        // 台账滚动（2026-09-15-tax-governance FR-02 主滚动点）：consume 得到的非零 counts 按
+        // change 滚动合并进 <runtimeRoot>/friction-ledger.json 幸存台账（merge-by-change——
+        // --reopen 重跑二次 consume 累加非双计）；空 counts 跳过写（防干净收尾落空文件）；
+        // archivedAt 此时不落（prune 侧落定）；runtimeRoot 与 consume 同源（specBase 同变量
+        // + resolveRuntimeRoot 单点）。台账写失败 fail-soft 在既有 try/catch 内，绝不阻断收尾。
+        if (changeName && r && r.counts && Object.keys(r.counts).length > 0) {
+          const { mergeFrictionEntry } = await import('../friction-ledger.js')
+          await mergeFrictionEntry(resolveRuntimeRoot(platformOpts, specBase), { change: changeName, counts: r.counts })
+        }
+      } catch { /* 摩擦提示/台账失败不影响收尾 */ }
     }
 
     if (stageName === 'execute') {
@@ -834,7 +873,7 @@ async function printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts,
     if (typeof frozenPatch === 'string') {
       const patchText = frozenPatch.endsWith('\n') ? frozenPatch : frozenPatch + '\n'
       writeFileSync(join(changeDir, 'scope-audit.patch'), patchText)
-      snap.patchSha256 = createHash('sha256').update(patchText, 'utf8').digest('hex')
+      snap.patchSha256 = createHash('sha256').update(patchText.replace(/\r\n/g, '\n'), 'utf8').digest('hex')
       snap.patchStatus = 'ok'
     } else if (frozenPatch === null) {
       snap.patchStatus = 'failed'
@@ -919,7 +958,11 @@ function readTaskCardText(changeDir, taskNum) {
  * 用于 autoCheckPlanFromReviews（勾选层）和 detectExecuteBatchFinish（批量层）。
  * 失败返回 null（调用方降级：勾选层不勾、批量层不过滤——向后兼容）。
  *
- * @returns {Promise<{gitDir:string, base:string, head:string}|null>}
+ * 2026-09-15-worktree-dual-truth-gates task-04（坑④/D-004@v1）：ctx 增透传 cwd/changeName/meta/
+ * baselineFiles——prefetchDiffFileSet 消费 collectWorktreeChangedFiles（与草稿归因同口径）并剔
+ * baseline 夹带。扩展字段对 shouldAutoCheckTask 只读 gitDir/base/head/diffFileSet 零影响。
+ *
+ * @returns {Promise<{gitDir:string, base:string, head:string, cwd:string, changeName:string, meta:object|null, baselineFiles:string[]}|null>}
  */
 async function buildDraftContext(cwd, changeName) {
   try {
@@ -940,7 +983,13 @@ async function buildDraftContext(cwd, changeName) {
       }
     }
     if (base && head && gitDir) {
-      return { gitDir, base, head }
+      return {
+        gitDir, base, head,
+        cwd, changeName,
+        meta: meta || null,
+        // baselineFiles 缺失/非数组按 [] 容错（prefetchDiffFileSet 剔除夹带用）
+        baselineFiles: Array.isArray(meta?.baselineFiles) ? meta.baselineFiles : [],
+      }
     }
     return null
   } catch (e) {
@@ -950,16 +999,39 @@ async function buildDraftContext(cwd, changeName) {
 }
 
 /**
- * 预取 base..head 全量 diff 文件集（一次 git spawn），供草稿零 diff 守卫按 task 内存归属判定。
+ * 预取草稿零 diff 守卫用的全量 diff 文件集，供 shouldAutoCheckTask 按 task 内存归属判定。
  * 此前每草稿 task 一次 `git diff --name-only base..head -- <files>`（同一对 base..head 查 N 次，
- * 8 task ≈ 8-16 次串行 spawn）。失败返回 null → 调用方回退逐 task 实测路径。
+ * 8 task ≈ 8-16 次串行 spawn）。失败返回 ctx 原样 → 调用方回退逐 task 实测路径。
+ *
+ * 2026-09-15-worktree-dual-truth-gates task-04（坑④ worktree-tick-guard-commit-only / D-004@v1）：
+ * 单算 base..head（已提交）在子代理默认不 commit 时恒空/缺文件 → 守卫全跳过勾选。现并入
+ * collectWorktreeChangedFiles（task-review.js 单一真相：porcelain 未提交 ∪ committed
+ * merge-base 补齐，与草稿归因同口径），再剔 meta.baselineFiles（R-07 防伪底线：merge-base..
+ * wtHEAD 含 baseline checkpoint 提交，夹带文件=非本变更改动，不剔则「声明未做恰被夹带」的
+ * task 误勾）。全空时仍不设 diffFileSet（退回逐 task 实测路径，原语义）。
  */
 function prefetchDiffFileSet(ctx) {
   if (!ctx?.gitDir || !ctx.base || !ctx.head) return ctx
   try {
     const out = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`], { trim: true })
-    if (!out) return ctx
-    return { ...ctx, diffFileSet: new Set(out.split('\n').filter(Boolean)) }
+    const diffFileSet = new Set(out ? out.split('\n').filter(Boolean) : [])
+    // D-004@v1 并入：porcelain 未提交 ∪ committed 补齐（helper 自身 fail-open，git 失败返 []
+    // → 退回 base..head 现状，不放大勾选面）；独立 try 防 helper 意外拖垮既有 base..head 集
+    try {
+      if (ctx.cwd && ctx.changeName) {
+        for (const f of collectWorktreeChangedFiles(ctx.cwd, ctx.changeName, ctx.meta)) {
+          if (f) diffFileSet.add(f)
+        }
+      }
+    } catch { /* helper 异常 → 退回 base..head 现状（fail-open） */ }
+    // 剔 baseline 夹带：按正斜杠归一 exact 匹配（两侧同 git 口径路径）；baselineFiles 缺失按 [] 容错
+    const baselineFiles = Array.isArray(ctx.baselineFiles) ? ctx.baselineFiles : []
+    for (const b of baselineFiles) {
+      const n = String(b).replace(/\\/g, '/').trim()
+      if (n) diffFileSet.delete(n)
+    }
+    if (diffFileSet.size === 0) return ctx
+    return { ...ctx, diffFileSet }
   } catch {
     return ctx
   }
@@ -975,35 +1047,49 @@ function prefetchDiffFileSet(ctx) {
  * changedFiles 非空且 git diff 实测非空。防 allowed_paths 误归属他人 diff 或陈旧 review.json 导致
  * 空任务被自动勾选/批量放行。ctx 缺省时保持现行判定（向后兼容）。
  *
- * @param {{ok?:boolean, review?:{specVerdict?:string, qualityVerdict?:string, reviewerNotes?:string, changedFiles?:string[]}}} r readReview 结果
+ * ql-20260915-001 修复②（坑 review-write-draft-marker-stuck，2026-09-14 用户实证：文档面任务
+ * 反复「草稿 changedFiles 为空，跳过自动勾选」断链）：显式 CLI 写入（writeTaskReview 通道，
+ * writtenBy 锚定，带 agent 供给 verdict）一律按非草稿处理——不受 changedFiles 空/实测 diff 空
+ * 限制（.sillyspec/ 文档面任务归因被滤、纯验证任务零 diff 是合法形态；agent 已用
+ * review write --force --changed-files 显式表态，verdict 即结论）。草稿守卫警告同步改为
+ * 可行动：含 task 名与解锁命令示例，不再只报现象。
+ *
+ * @param {{ok?:boolean, review?:{specVerdict?:string, qualityVerdict?:string, reviewerNotes?:string, changedFiles?:string[], task?:string, writtenBy?:string}}} r readReview 结果
  * @param {boolean} endToEnd 是否端到端/deployment-critical task
  * @param {{gitDir?:string, base?:string, head?:string}|null} [ctx] 实测 diff 上下文；缺省保持现行判定
+ * @param {string} [changeName] 变更名（草稿守卫警告里解锁命令示例用）
  * @returns {boolean}
  */
-export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
+export function shouldAutoCheckTask(r, endToEnd, ctx = null, changeName = '') {
   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'
 
+  // ql-20260915-001 修复②：显式 CLI 写入（review write 通道）按非草稿处理，直接勾——
+  // verdict 非 fail 已过上面守卫，文档面/纯验证任务的空 changedFiles 不再拦截
+  if (isExplicitReviewWrite(r.review)) return true
+
   // W2 task-04 草稿零 diff 守卫（FR-03）
   // ctx 给定且 review 为自动草稿时，要求 changedFiles 非空且实测 diff 非空
   if (ctx && r.review?.reviewerNotes && r.review.reviewerNotes.includes('auto-generated draft')) {
+    const taskId = r.review.task || 'task-NN'
+    const unlockCmd = `sillyspec review write${changeName ? ` --change ${changeName}` : ' --change <变更名>'} --task ${taskId} --spec pass --quality pass --force --changed-files <文件>`
     const changedFiles = r.review.changedFiles || []
     if (changedFiles.length === 0) {
-      console.warn(`⚠️ 草稿 review changedFiles 为空，跳过自动勾选`)
+      console.warn(`⚠️ 草稿 review changedFiles 为空，跳过自动勾选（task=${taskId}）——解锁：${unlockCmd}（纯验证任务用 --changed-files "" + --evidence "<验证说明>"）`)
       return false
     }
     if (!ctx.gitDir || !ctx.base || !ctx.head) {
-      console.warn(`⚠️ ctx 信息不完整（gitDir=${ctx.gitDir}, base=${ctx.base}, head=${ctx.head}），跳过草稿 diff 校验，保守不勾`)
+      console.warn(`⚠️ ctx 信息不完整（gitDir=${ctx.gitDir}, base=${ctx.base}, head=${ctx.head}），跳过草稿 diff 校验，保守不勾（task=${taskId}）——解锁：${unlockCmd}`)
       return false
     }
     // 预取路径：一次全量 diff 文件集内存归属（autoCheckPlanFromReviews/批量路径已 prefetch）
     if (ctx.diffFileSet) {
       const hit = changedFiles.filter(f => ctx.diffFileSet.has(f))
       if (hit.length === 0) {
-        console.warn(`⚠️ 草稿 review 实测 diff 为空（base=${ctx.base.slice(0, 8)}, head=${ctx.head.slice(0, 8)}, files=${changedFiles.length}），跳过自动勾选`)
+        console.warn(`⚠️ 草稿 review 实测 diff 为空（task=${taskId}, base=${ctx.base.slice(0, 8)}, head=${ctx.head.slice(0, 8)}, files=${changedFiles.length}），跳过自动勾选——解锁：${unlockCmd}`)
         return false
       }
       console.log(`   ✓ 草稿 diff 校验通过（实测 ${hit.length}/${changedFiles.length} 个声明文件有改动）`)
@@ -1014,12 +1100,12 @@ export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
       // 用数组参数避免 shell 拆词，复用 git-helper 安全模式
       const diffResult = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`, '--', ...changedFiles], { trim: true })
       if (!diffResult || diffResult.trim() === '') {
-        console.warn(`⚠️ 草稿 review 实测 diff 为空（base=${ctx.base.slice(0,8)}, head=${ctx.head.slice(0,8)}, files=${changedFiles.length}），跳过自动勾选`)
+        console.warn(`⚠️ 草稿 review 实测 diff 为空（task=${taskId}, base=${ctx.base.slice(0,8)}, head=${ctx.head.slice(0,8)}, files=${changedFiles.length}），跳过自动勾选——解锁：${unlockCmd}`)
         return false
       }
       console.log(`   ✓ 草稿 diff 校验通过（${diffResult.trim().split('\n').length} 个文件有改动）`)
     } catch (e) {
-      console.warn(`⚠️ 草稿 diff 校验失败（${e && e.message ? e.message : e}），保守不勾`)
+      console.warn(`⚠️ 草稿 diff 校验失败（task=${taskId}: ${e && e.message ? e.message : e}），保守不勾——解锁：${unlockCmd}`)
       return false
     }
   }
@@ -1079,7 +1165,7 @@ export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, pla
           && r.review?.qualityVerdict !== 'fail'
         const endToEnd = verdictUsable
           && isEndToEndTaskText(match + ' ' + readTaskCardText(changeDir, taskNum))
-        if (shouldAutoCheckTask(r, endToEnd, ctx)) {
+        if (shouldAutoCheckTask(r, endToEnd, ctx, changeName)) {
           checkedCount++
           return `${p1}x${p2}`   // 勾选
         }
@@ -1175,7 +1261,10 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
       }
 
       // review 存在：判定是否为自动草稿且零 diff
-      if (review?.reviewerNotes && review.reviewerNotes.includes('auto-generated draft')) {
+      // （ql-20260915-001 修复②：显式 CLI 写入（writeTaskReview 通道）按非草稿处理——不阻断
+      // 批量，与勾选层 shouldAutoCheckTask 同口径；agent 已显式给 verdict 的 review 不该因
+      // notes 字面残留 'auto-generated draft' 被当草稿拦截）
+      if (!isExplicitReviewWrite(review) && review?.reviewerNotes && review.reviewerNotes.includes('auto-generated draft')) {
         const changedFiles = review.changedFiles || []
         // 草稿且 changedFiles 为空 → 阻断
         if (changedFiles.length === 0) {
@@ -1517,6 +1606,8 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     // gate 全过：persist completed（task-03 移后；此处无 triggerSync）。
     pm._write(cwd, progress, changeName)
     console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)
+    // 平台模式产物落点指针：与 completeStep 完成分支同款（本路径不漏）。
+    writePlatformDocsPointer(cwd, changeName, platformOpts, stageName)
     // task-04：wait 解除完成路径与 completeStep 完成分支同源注入（Grill G-2：本路径不漏，
     // 否则 execute 快照缺失 → verify 假报「无快照可对比」）。
     await printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts })
@@ -1527,7 +1618,16 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
         const { consumeFrictionHint } = await import('../friction-tally.js')
         const r = await consumeFrictionHint({ cwd, changeName, platformOpts })
         if (r && r.hint) console.log(`\n${r.hint}`)
-      } catch { /* 摩擦提示失败不影响收尾 */ }
+        // 台账滚动（2026-09-15-tax-governance FR-02 主滚动点）：consume 得到的非零 counts 按
+        // change 滚动合并进 <runtimeRoot>/friction-ledger.json 幸存台账（merge-by-change——
+        // --reopen 重跑二次 consume 累加非双计）；空 counts 跳过写（防干净收尾落空文件）；
+        // archivedAt 此时不落（prune 侧落定）；runtimeRoot 与 consume 同源（specBase 同变量
+        // + resolveRuntimeRoot 单点）。台账写失败 fail-soft 在既有 try/catch 内，绝不阻断收尾。
+        if (changeName && r && r.counts && Object.keys(r.counts).length > 0) {
+          const { mergeFrictionEntry } = await import('../friction-ledger.js')
+          await mergeFrictionEntry(resolveRuntimeRoot(platformOpts, specBase), { change: changeName, counts: r.counts })
+        }
+      } catch { /* 摩擦提示/台账失败不影响收尾 */ }
     }
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]

package/src/run/concurrent-detect.js

@@ -12,6 +12,7 @@
  * 纯函数无副作用：不写盘、不 console（console 留给调用点 task-02/03）。
  */
 import { safeGit, parsePorcelainPath, isQuickMetadata } from './shared.js'
+import { basename } from 'node:path'
 
 /**
  * 内联解析 .sillyspec/changes/<dir>/ 路径取 <dir>。
@@ -154,3 +155,100 @@ export function formatConcurrentWarning(detected) {
   lines.push('提交请用显式 pathspec 隔离本变更文件，勿 git add . 扫入他者工作（execute task 内建议 sillyspec wt-commit 串行提交）。')
   return lines.join('\n')
 }
+
+// ── 坑 mixed-baseline-drift-hint（ql-20260915-004）committed-drift 混合基线检测 ──
+// 背景（用户 2026-09-15 实证）：并行会话合并断言不同步——worktree 内基于旧快照写的测试断言
+// （旧 id），主仓已合入 id 统一修复 → verify 测试门红——测试源=worktree 快照、被测源=主仓
+// HEAD 的混合基线漂移此前无任何提示。本函数算「主仓自本变更基点后的已提交推进 ∩ 本变更
+// 相关文件」，交两挂点（worktree-apply 成功尾声 / gates.js verify 测试门前）advisory 提示。
+
+/** 测试形态文件名：foo.test.mjs / foo.spec.js（与探针 7 isProbe7TestPath 的 .test. 口径同族） */
+const DRIFT_TEST_FORM_RE = /\.(?:test|spec)\.[A-Za-z0-9]+$/
+
+/** git 路径反斜杠归一（detectCommittedDrift 内部用，与 normalizeGitPath 同义独立小函数） */
+function toPosix(p) {
+  return String(p || '').replace(/\\/g, '/')
+}
+
+/**
+ * 文件名 stem 键：剥扩展名与 .test./.spec. 中缀（foo.js → foo；foo.test.mjs → foo；
+ * foo_test.js → foo_test——下划线形不在变体口径内，仅精确匹配兜底）。小写归一。
+ */
+function driftStemKey(p) {
+  const name = basename(toPosix(p))
+  const m = name.match(/^(.+?)\.(?:test|spec)\.[A-Za-z0-9]+$/)
+  if (m) return m[1].toLowerCase()
+  const dot = name.lastIndexOf('.')
+  return (dot > 0 ? name.slice(0, dot) : name).toLowerCase()
+}
+
+/**
+ * 检测混合基线漂移（非阻断 advisory 用）：主仓 `git diff --name-only <baseHash>..<head>`
+ * （基点后已提交推进面）∩ 本变更 touchedFiles（或其同 basename 的 .test./.spec. 变体）非空
+ * → drift。变体口径：stem 相同且至少一侧为测试形态（src/foo.js ↔ test/foo.test.mjs）——
+ * 换位覆盖两方向（他者推进我的源文件的测试变体 / 他者推进我测试文件对应的源文件）。
+ *
+ * fail-open：baseHash 缺失 / git 异常 → 返回 null（调用方视为未检测，零输出零阻断）；
+ * diff 空（基点后无推进）→ { drift:false, files:[] }。
+ *
+ * @param {{ projectRoot: string, baseHash: string, touchedFiles: string[],
+ *           excludeFiles?: string[], head?: string }} opts
+ *   - baseHash：worktree 基点（meta.baselineCommit || baseHash）
+ *   - touchedFiles：本变更交付文件面（apply-manifest files / changedFiles）
+ *   - excludeFiles：从推进面剔除的文件（verify 挂点传本变更自身面——apply 已提交时
+ *     baseHash..HEAD 含自身交付，不剔会把「自己合自己」误报成他者推进；apply 挂点用
+ *     精确 preMergeHead，无需剔除）
+ *   - head：推进面终点 ref（缺省 HEAD；merge 路径传 merge 前 HEAD）
+ * @returns {{ drift: boolean, files: string[], hint?: string }|null}
+ */
+export function detectCommittedDrift({ projectRoot, baseHash, touchedFiles, excludeFiles = [], head = 'HEAD' }) {
+  if (!projectRoot || !baseHash) return null
+  const touched = (Array.isArray(touchedFiles) ? touchedFiles : []).map(toPosix).filter(Boolean)
+  if (touched.length === 0) return null
+  // FR fail-open（与 detectConcurrentChanges 同族）：git 读不到不崩不误报
+  const diff = safeGit(projectRoot, ['diff', '--name-only', `${baseHash}..${head}`], { timeout: 30000 })
+  if (diff.error) return null
+  if (!diff.value) return { drift: false, files: [] }
+
+  const excl = new Set((Array.isArray(excludeFiles) ? excludeFiles : []).map(toPosix).filter(Boolean))
+  const touchedSet = new Set(touched)
+  const touchedStems = new Set(touched.map(driftStemKey).filter(Boolean))
+  const touchedHasTestForm = touched.some(f => DRIFT_TEST_FORM_RE.test(basename(f)))
+
+  const files = []
+  for (const raw of diff.value.split('\n').map(s => s.trim()).filter(Boolean)) {
+    const p = toPosix(raw)
+    if (excl.has(p)) continue
+    const exact = touchedSet.has(p)
+    // 变体：非精确命中时，stem 相同且至少一侧为测试形态（防 docs/foo.md ↔ test/foo.test.mjs
+    // 之外的松散同名误报——两侧都非测试形态的不同目录同名不算相关）
+    const variant = !exact
+      && touchedStems.has(driftStemKey(p))
+      && (DRIFT_TEST_FORM_RE.test(basename(p)) || touchedHasTestForm)
+    if (exact || variant) files.push(p)
+  }
+  if (files.length === 0) return { drift: false, files: [] }
+  return {
+    drift: true,
+    files,
+    hint: `主仓自基点 ${String(baseHash).slice(0, 8)} 后已合入触及 ${files.length} 个本变更相关文件的推进（${files.slice(0, 5).join('、')}${files.length > 5 ? ' 等' : ''}）——worktree 快照内验证过的断言可能漂移，建议合并态复跑相关测试`,
+  }
+}
+
+/**
+ * committed-drift 检测结果 → 多行 ⚠️ 提示串（两挂点共用文案，与 formatConcurrentWarning 同族）。
+ * @param {{ drift: boolean, files?: string[], hint?: string }|null} drift detectCommittedDrift 产物
+ * @param {{ tailNote?: string }} [opts] tailNote 追加在首行末的挂点语境注（如 verify 挂点的
+ *   「实测若红先做合并态归因」）；缺省无
+ * @returns {string|null} 无漂移/未检测返回 null
+ */
+export function formatCommittedDriftWarning(drift, opts = {}) {
+  if (!drift || !drift.drift) return null
+  const files = Array.isArray(drift.files) ? drift.files : []
+  const note = opts.tailNote ? `（${opts.tailNote}）` : ''
+  return [
+    '⚠️ 混合基线提示：主仓自本变更基点后已合入触及以下本变更相关文件的推进'
+      + `（${files.length} 个）——worktree 快照内验证过的断言可能漂移，建议合并态复跑相关测试${note}：`,
+    ...files.map(f => `  - ${f}`),
+  ].join('\n')
+}

package/src/run/gate-snapshot.js

@@ -14,7 +14,7 @@
  * 快照生命周期：一次门禁一批（create → run → cleanup）；崩溃残留由 git worktree prune /
  * 临时目录自然回收（OS tmp 清理），不进主仓 .runtime。
  */
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import { mkdtempSync, mkdirSync, copyFileSync, writeFileSync, rmSync, existsSync, readdirSync, statSync, symlinkSync, readFileSync } from 'node:fs'
 import { join, dirname, relative, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -23,12 +23,100 @@ function git(cwd, args) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000 }).trim()
 }
 
+/**
+ * overlay import 冒烟多轮收敛（坑 verify-sandbox-overlay-partial-state-importerror）：
+ * 单轮回退有两个盲点——①坏的是依赖文件（缺名/缺模块），报错的是 importer，回退 importer
+ * 不解决问题；②一次回退后依赖关系变化。策略：最多 3 轮，每轮对未回退的 overlay .py 冒烟；
+ * 失败时解析报错点名的模块名 → 若能映射到**另一个 overlay .py 文件**则回退那个依赖文件
+ *（事故形态：crud.py 半成品缺名，importer 报错点名 crud → 回退 crud 的 HEAD 健版），
+ * 否则回退报错文件自身（语法坏/自身缺依赖）；HEAD 无版的新文件回退不了 → warn 保留。
+ */
+function runOverlayImportSmoke(pythonBin, snapshotRoot, overlaidFiles) {
+  const reverted = new Set()
+  const byModule = new Map() // 末段模块名 → 文件（映射报错点名）
+  for (const f of overlaidFiles) byModule.set(f.split('/').pop().replace(/\.py$/, ''), f)
+  const revertToHead = (f, why) => {
+    try {
+      writeFileSync(join(snapshotRoot, f), git(snapshotRoot, ['show', `HEAD:${f}`]))
+      reverted.add(f)
+      console.warn(`⚠️ 快照 overlay 冒烟：${f} ${why}——已回退 HEAD 版（并行会话半成品部分态不进沙箱）`)
+      return true
+    } catch {
+      console.warn(`⚠️ 快照 overlay 冒烟：${f} ${why}且 HEAD 无该文件（新增半成品）——保留原样，模块子集实测若红先查此文件`)
+      return false
+    }
+  }
+  for (let round = 0; round < 3; round++) {
+    let acted = false
+    for (const f of overlaidFiles) {
+      if (reverted.has(f)) continue
+      const bad = smokeImportPython(pythonBin, snapshotRoot, f)
+      if (!bad) continue
+      acted = true
+      // 依赖归因：报错点名另一 overlay 文件 → 回退依赖（ importer 自身往往无恙）
+      const named = bad.match(/(?:No module named|from)\s+['"]?([A-Za-z_][\w.]*)/i)
+      const depFile = named ? byModule.get(named[1].split('.').pop()) : null
+      if (depFile && depFile !== f && !reverted.has(depFile)) {
+        if (revertToHead(depFile, `被 ${f} 的 import 报错点名（${bad.slice(0, 60)}）`)) continue
+      }
+      revertToHead(f, `import 失败（${bad.slice(0, 60)}）`)
+    }
+    if (!acted) return
+  }
+}
+
+/**
+ * 快照内寻找 python 解释器（overlay 冒烟用）：环境目录发现集里的 venv 族
+ *（.venv/venv/env）在快照内已 junction——按平台拼 Scripts/bin 下的 python 路径。
+ * @returns {string|null} 解释器绝对路径；找不到返回 null
+ */
+function findSnapshotPython(envRelDirs, snapshotRoot) {
+  for (const rel of envRelDirs) {
+    if (!/(^|\/)(\.?venv|env)(\/|$)/.test(rel)) continue
+    const bin = process.platform === 'win32'
+      ? join(snapshotRoot, rel, 'Scripts', 'python.exe')
+      : join(snapshotRoot, rel, 'bin', 'python')
+    if (existsSync(bin)) return bin
+  }
+  return null
+}
+
+/**
+ * 单文件 import 冒烟：`python -c "import <mod>"`，cwd 取该文件所在包根（模块路径按
+ * 目录结构推导：剥 .py、/→.、丢 __init__；相对包根 import）。非 0 退出且 stderr 命中
+ * ImportError/ModuleNotFoundError/SyntaxError 才判坏（其余失败如缺第三方依赖是环境问题，
+ * 不回退——回退语义只针对「部分态坏文件」）。超时 10s 防挂。
+ * @returns {string|null} 失败原因（判坏时）；通过/环境性失败返回 null
+ */
+function smokeImportPython(pythonBin, snapshotRoot, relFile) {
+  const noExt = relFile.replace(/\.py$/, '')
+  const parts = noExt.split('/')
+  while (parts.length > 0 && parts[parts.length - 1] === '__init__') parts.pop()
+  if (parts.length === 0) return null
+  // 包根推导：从深到浅尝试（backend/app/x/y.py → 先 app.x.y（cwd=backend）再 x.y（cwd=backend/app））
+  for (let cut = 0; cut < parts.length; cut++) {
+    const mod = parts.slice(cut).join('.')
+    if (!mod || !/^[A-Za-z_][\w.]*$/.test(mod)) continue
+    const pkgRoot = join(snapshotRoot, ...parts.slice(0, cut))
+    const r = spawnSync(pythonBin, ['-c', `import ${mod}`], {
+      cwd: pkgRoot, encoding: 'utf-8', timeout: 10_000,
+    })
+    if (r.status === 0) return null
+    const err = String((r.stderr || '') + (r.stdout || ''))
+    if (/ImportError|ModuleNotFoundError|SyntaxError|cannot import name/i.test(err)) {
+      return (err.match(/(?:ImportError|ModuleNotFoundError|SyntaxError|cannot import name)[^\n]*/) || ['import 失败'])[0].slice(0, 120)
+    }
+    // 环境性失败（如缺第三方依赖、非模块入口冲突）→ 不判坏，继续试更浅包根
+  }
+  return null
+}
+
 /**
  * 创建隔离快照：HEAD worktree + 会话文件 overlay + node_modules junction + local.yaml。
  * @param {{ cwd: string, files: string[] }} opts cwd=主仓根；files=本会话变更文件（仓库根相对 POSIX）
  * @returns {{ snapshotRoot: string, cleanup: () => void, reason?: string }|null} 失败返回 null（调用方回退主仓）
  */
-export function createGateSnapshot({ cwd, files, sourceRoot = null }) {
+export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSmoke = false }) {
   let snapshotRoot = null
   try {
     // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
@@ -112,6 +200,26 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null }) {
       }
     }
 
+    // ── overlay import 闭合冒烟（坑 verify-sandbox-overlay-partial-state-importerror，
+    // 2026-09-13 实证：in-place 变更的文件集含主仓未提交并行 WIP——「改了引用方没改被引用方」
+    // 的部分态进快照，模块子集测试 197 ERROR 只能人工三步排查）──
+    // 对 overlay 进快照的 .py 文件逐个 `python -c import`（用快照内链接的 venv 解释器）；
+    // ImportError/SyntaxError → 该文件回退 HEAD 版（git show）+ warn——半成品坏文件不进沙箱，
+    // HEAD 健版保证 import 图闭合。新增文件（HEAD 无版）无法回退 → 醒目 warn 保留。
+    // 全链 fail-open：找不到解释器/基建异常只 warn 不作废快照（主场景是 Python 项目，
+    // JS/TS 的 vitest load 冒烟成本高留后续）。
+    const overlaidPyFiles = files.filter(f => typeof f === 'string' && f.endsWith('.py')
+      && !f.startsWith('.sillyspec/')
+      && existsSync(join(snapshotRoot, f)))
+    if (overlaidPyFiles.length > 0 && !skipImportSmoke) {
+      const pythonBin = findSnapshotPython(envRelDirs, snapshotRoot)
+      if (pythonBin) {
+        runOverlayImportSmoke(pythonBin, snapshotRoot, overlaidPyFiles)
+      } else {
+        console.warn(`⚠️ 快照 overlay 冒烟跳过：快照内未找到 python 解释器（venv 族未链接）——并行半成品部分态可能引发 ImportError 假红，实测红先 SNAPSHOT_OFF 对照`)
+      }
+    }
+
     const cleanup = () => {
       try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {
         try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch { /* 残留交 OS tmp 清理 */ }