sillyspec 3.28.7 → 3.28.9

package/src/run/complete.js

@@ -23,6 +23,7 @@ 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 { isExplicitReviewWrite } 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 整目录删除。
@@ -494,7 +495,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 +569,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 步骤
@@ -673,9 +676,18 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     if (stageName === 'verify') {
       try {
         const { consumeFrictionHint } = await import('../friction-tally.js')
-        const r = consumeFrictionHint({ cwd, changeName, platformOpts })
+        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 +846,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'
@@ -975,35 +987,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 +1040,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
     }
   }
@@ -1071,9 +1097,15 @@ export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, pla
         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, ctx)) {
+        // 卡片读取延后到 verdict 可用之后（2026-09-11 审查性能包③）：review 缺失或 spec/quality
+        // 已 fail 时 endToEnd 取值不影响 shouldAutoCheckTask 结果（恒 false），先读卡片是纯浪费
+        // ——持 tasks 锁期间每 task 省一次 readFileSync。
+        const verdictUsable = r?.ok
+          && r.review?.specVerdict !== 'fail'
+          && r.review?.qualityVerdict !== 'fail'
+        const endToEnd = verdictUsable
+          && isEndToEndTaskText(match + ' ' + readTaskCardText(changeDir, taskNum))
+        if (shouldAutoCheckTask(r, endToEnd, ctx, changeName)) {
           checkedCount++
           return `${p1}x${p2}`   // 勾选
         }
@@ -1169,7 +1201,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) {
@@ -1212,6 +1247,11 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
       if (step.status === 'pending' || step.status === 'in-progress') {
         step.status = 'completed'
         step.completedAt = now
+        // 乐观预标戳：这是本次 --done 的批量乐观标记而非逐步验证的完成。任一收尾 gate 失败时
+        // rollbackStageCompletion 据此一并回滚（坑 execute-batch-rollback-half-state：只回滚
+        // currentIdx 会落库「步骤 11 pending + 12-16 completed」半套状态）。内存字段，_write 只写
+        // 固定列不落库。
+        step._batchAligned = true
         aligned++
       }
     }
@@ -1251,10 +1291,11 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
     process.exit(1)
   }
 
-  // 查找下一个 pending 或 in-progress 的步骤
-  const currentIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  // 查找下一个 pending / in-progress / blocked 的步骤（blocked 同为当前步——与 completeStep
+  // 的 findIndex 口径对齐，否则 blocked 后 --wait 落到其后第一个 pending 步上错步记账）
+  const currentIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')
   if (currentIdx === -1) {
-    console.error(`没有可以等待的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
+    console.error(`没有可以等待的步骤（阶段 ${stageName} 已无 pending/in-progress/blocked 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
     process.exit(1)
   }
 
@@ -1513,9 +1554,18 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     if (stageName === 'verify') {
       try {
         const { consumeFrictionHint } = await import('../friction-tally.js')
-        const r = consumeFrictionHint({ cwd, changeName, platformOpts })
+        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]
@@ -1569,7 +1619,10 @@ export async function skipStep(pm, progress, stageName, cwd, changeName, platfor
   }
 
   const steps = stageData.steps
-  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  // blocked 同为当前步——与 completeStep 的 findIndex 口径对齐（坑 deps-gate-blocked-invisible
+  // 在 completeStep 修过但此处漏同步：blocked 后 --skip 落到其后第一个 pending 步上，错步跳过
+  // 且 blocked 步永久卡死只能 --reset）
+  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')
 
   if (currentIdx === -1) {
     const wsIdx = steps.findIndex(s => s.status === 'waiting')
@@ -1577,11 +1630,15 @@ export async function skipStep(pm, progress, stageName, cwd, changeName, platfor
       console.error(`⏸️  Step ${wsIdx + 1} 正在等待用户输入，不能跳过。`)
       console.error(`   请先使用 --continue --answer "..." 继续，或用 --reset 重置。`)
     } else {
-      console.error(`没有待跳过的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
+      console.error(`没有待跳过的步骤（阶段 ${stageName} 已无 pending/in-progress/blocked 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
     }
     process.exit(1)
   }
 
+  if (steps[currentIdx].status === 'blocked') {
+    console.log(`⚠️  Step "${steps[currentIdx].name}" 此前被门控阻断（blocked），本次 --skip 将跳过该步——若门控条件已修复，更宜直接 --done 推进。`)
+  }
+
   const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const stepDef = defSteps ? defSteps[currentIdx] : null
   if (stepDef && !stepDef.optional) {

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>。
@@ -151,6 +152,103 @@ export function formatConcurrentWarning(detected) {
     for (const c of otherActiveChanges) lines.push(`  - ${c}`)
   }
 
-  lines.push('提交请用显式 pathspec 隔离本变更文件，勿 git add . 扫入他者工作。')
+  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

@@ -34,6 +34,16 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null }) {
     // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
     git(cwd, ['rev-parse', 'HEAD'])
 
+    // symlink-store 布局探测（坑 gate-snapshot-pnpm-store-break，2026-09-12 驾驭第十七批②，
+    // 用户第三次踩「lint 沙箱临时目录跑 pnpm 必假败」）：pnpm/bun/lerna 的 node_modules 内部
+    // 是指向 store 的符号链接网——junction 进临时目录后跨根解析失效，实测必假败。
+    // 与其让沙箱报无关错误逼 advisory，不如布局命中即作废快照回退主仓（宁可主仓口径）。
+    const layoutHit = detectSymlinkStoreLayout(cwd)
+    if (layoutHit) {
+      console.warn(`⚠️ 门禁快照对 ${layoutHit} 布局不可靠（node_modules 符号链接 store 经 junction 跨根失效，实测必假败）——跳过快照回退主仓实测；主仓失败再做污染归属鉴定`)
+      return null
+    }
+
     snapshotRoot = mkdtempSync(join(tmpdir(), 'sillyspec-gate-'))
     git(cwd, ['worktree', 'add', '--detach', '--quiet', snapshotRoot, 'HEAD'])
 
@@ -58,11 +68,39 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null }) {
       overlaid++
     }
 
-    // node_modules junction（依赖主仓安装态；junction Windows 无需特权，POSIX 用 symlink）
-    const nmSrc = join(cwd, 'node_modules')
-    if (existsSync(nmSrc)) {
-      try { symlinkSync(nmSrc, join(snapshotRoot, 'node_modules'), 'junction') }
-      catch { /* 依赖链接失败：test/lint 可能跑不起来 → 仍返回快照，命令层报错走 fallback */ }
+    // 环境目录链接（坑 gate-snapshot-env-mismatch，2026-09-12 驾驭第十三批③，用户实证：
+    // 沙箱实测 venv 不装 dev 依赖（xdist 缺失）+ node_modules 缺失——快照只链 node_modules 时
+    // Python 项目的 commands.test 在快照内找不到 venv，误伤持续且难归因）。链接面扩 venv 族
+    // （.venv/venv/env——链接后 dev 依赖与主仓同源，不缺 xdist）；链接失败/主仓本就没有时
+    // ⚠️ 显式可见（环境不一致的门禁会持续误伤——宁可吵不可静默错）。
+    // 递归依赖发现（坑 gate-snapshot-monorepo-layout，2026-09-12 驾驭第十五批①，用户实证
+    // 「对 monorepo 依赖布局完全不可用，四次重试才定位」）：pnpm/nx/lerna workspace 的
+    // packages/<pkg>/node_modules 子目录依赖不在根四目录——深度≤3 扫描发现集逐个 junction。
+    const envRelDirs = discoverEnvDirs(cwd)
+    for (const rel of envRelDirs) {
+      const src = join(cwd, rel)
+      const dst = join(snapshotRoot, rel)
+      try {
+        mkdirSync(dirname(dst), { recursive: true })
+        symlinkSync(src, dst, 'junction')
+      } catch (e) {
+        console.warn(`⚠️ 门禁快照环境目录链接失败（${rel}）：${e && e.message ? e.message : e}——快照内实测可能因缺该目录误伤，失败时先核对快照环境`)
+      }
+    }
+    if (envRelDirs.length === 0) {
+      console.warn(`⚠️ 门禁快照：主仓未发现任何环境目录（node_modules / venv 族，含子包递归）——commands.test/lint 若依赖它们将快照/主仓都不可用（环境未安装？）`)
+    }
+
+    // 环境完整性预检（坑 gate-snapshot-env-mismatch 二阶，2026-09-12 驾驭第十四批①，用户
+    // 实证「verify lint 沙箱必挂 node_modules 缺失只能 advisory」）：主仓存在某环境目录而
+    // 快照内缺失（链接失败/布局差异）→ 快照对该仓 commands 是假环境，实测必挂——快照作废
+    // 回退主仓现行为（主仓口径可能被并行脏文件污染，但环境真实；两害取轻 + 回退原因可见）。
+    const envMissing = envDirsLinked(cwd, snapshotRoot)
+    if (envMissing.length > 0) {
+      console.warn(`⚠️ 门禁快照环境不完整（${envMissing.join('、')} 在主仓存在、快照内缺失）——快照作废回退主仓实测（宁可主仓口径不可假沙箱硬挂；回退后失败先做污染归属鉴定）`)
+      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {}
+      try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch {}
+      return null
     }
 
     // local.yaml（gitignore 不进 HEAD；门禁命令配置来源）+ package-lock 保持 HEAD 版（npm test 不装新依赖）
@@ -90,6 +128,78 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null }) {
   }
 }
 
+
+/** symlink-store 包管理布局探测：命中即 junction 快照不可靠。返回布局名或 null。 */
+export function detectSymlinkStoreLayout(cwd) {
+  try {
+    if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
+    if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) return 'bun'
+    if (existsSync(join(cwd, 'lerna.json'))) return 'lerna'
+    try {
+      const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))
+      const pm = pkg && pkg.packageManager ? String(pkg.packageManager) : ''
+      if (/pnpm@/.test(pm)) return 'pnpm(packageManager)'
+      if (/yarn@/.test(pm)) return 'yarn(packageManager)'
+      if (/bun@/.test(pm)) return 'bun(packageManager)'
+    } catch { /* 无 package.json/损坏 → 仅锁文件判据 */ }
+    return null
+  } catch { return null }
+}
+
+/** 环境目录名集（根与子包通用） */
+const ENV_DIR_NAMES = new Set(['node_modules', '.venv', 'venv', 'env'])
+
+/**
+ * 递归依赖发现（坑 gate-snapshot-monorepo-layout）：深度 ≤3 扫描（跳过环境目录自身内部/
+ * .git/dist/build/.sillyspec），返回所有环境目录的仓库根相对 POSIX 路径（含根级四目录）。
+ * pnpm/nx/lerna workspace 的 packages/<pkg>/node_modules 覆盖。
+ */
+export function discoverEnvDirs(cwd, { maxDepth = 3 } = {}) {
+  const out = []
+  const skip = new Set(['.git', 'dist', 'build', '.sillyspec', 'out', 'target'])
+  const walk = (dir, rel, depth) => {
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (!e.isDirectory() || skip.has(e.name)) continue
+      const childRel = rel ? rel + '/' + e.name : e.name
+      if (ENV_DIR_NAMES.has(e.name)) {
+        out.push(childRel)
+        continue // 环境目录内部不再下钻（node_modules/node_modules 无意义且巨大）
+      }
+      if (depth < maxDepth) walk(join(dir, e.name), childRel, depth + 1)
+    }
+  }
+  walk(cwd, '', 0)
+  return out
+}
+
+/**
+ * 环境完整性纯检（坑 gate-snapshot-env-mismatch 二阶，发现集口径）：主仓存在（递归发现）
+ * 而快照缺失的环境目录清单。任一命中 = 快照对该仓 commands 是假环境，调用方作废回退主仓。
+ * @returns {string[]} 缺失目录相对路径（空数组 = 完整/主仓本就无环境目录）
+ */
+export function envDirsLinked(cwd, snapshotRoot) {
+  const missing = []
+  for (const rel of discoverEnvDirs(cwd)) {
+    try {
+      if (existsSync(join(cwd, rel)) && !existsSync(join(snapshotRoot, rel))) missing.push(rel)
+    } catch { missing.push(rel) /* 判定异常按缺失算（保守作废快照） */ }
+  }
+  return missing
+}
+
+/**
+ * 快照内实测失败的归属提示（坑 gate-snapshot-monorepo-layout 配套：用户四次重试才从日志
+ * 摸到 Temp\sillyspec-gate-* 路径——失败时路径/疑点/对照复跑出口必须直给）。
+ * 调用方在「快照内执行且失败」的分支打印。
+ */
+export function printSnapshotFailureHint(snapInfo, { offEnv = 'SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF' } = {}) {
+  if (!snapInfo || !snapInfo.snapshotRoot) return
+  console.error(`   🔬 本次实测执行于隔离快照：${snapInfo.snapshotRoot}（HEAD + 本变更 ${snapInfo.changeFileCount ?? '?'} 个文件${snapInfo.sourceRoot ? '，overlay 自 worktree' : ''}）`)
+  console.error(`   失败疑点排查顺序：① 本变更文件自身的真实失败（最常见）→ 修代码；② 快照环境差异（monorepo 依赖布局/环境目录链接缺失）→ 设 ${offEnv}=1 回退主仓复跑对照——主仓过而快照挂即环境问题；③ 并行污染已被快照隔离，不在疑点内。`)
+}
+
 /**
  * verify 门专用快照（2026-09-10 驾驭小结第八批，用户第二次真实阻塞：verify 实测门跑
  * main 工作区，多会话并发任何人的 WIP 都能弄红别人的门）。等价「--worktree 定向跑」：