sillyspec 3.28.9 → 3.28.11

package/src/run/complete.js

@@ -16,14 +16,14 @@
  *   - stages/plan-postcheck.js: executePlanPostcheck（noAI 硬门）
  *   - node: join(path) + existsSync/readdirSync/readFileSync/mkdirSync/writeFileSync/appendFileSync/statSync(fs)
  */
-import { join } from 'node:path'
+import { join, isAbsolute, resolve } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 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 { isExplicitReviewWrite } from '../task-review.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 表重种清零，
@@ -43,10 +43,10 @@ async function getStageStepsAutoAware(stageName, cwd, progress, specDir) {
 import { executeScanPreflight, executeScanPostcheck, computeScanProfile, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
 import { executeProgressConfirm } from './progress-confirm.js'
 import { AUXILIARY_STAGES } from '../constants.js'
-import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
+import { executePlanPostcheck as runPlanPostcheckLib, parseRepoRegistry } from '../stages/plan-postcheck.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, warnMissingUiPrototype, completeStageGates, readDesignScale } from './gates.js'
-import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
+import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact, assertWaveTasksComplete } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
 import { validateDecisionModuleRefs } from '../design-facts.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
@@ -181,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）。语义性说明（方案取舍/用户反馈）仍应
@@ -465,6 +488,19 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     process.exit(1)
   }
 
+  // ── Wave 步骤完成度门（2026-09-17-pass-cap-semantics task-08 / FR-12 / D-013@v1）──
+  // 动机锚：2026-09-17 本变更执行中 Wave 2 越位实证——review write 退出码被 shell 管道吞掉后
+  // --done 落在下一 Wave，步骤被静默标 completed；既有防护（--step 可选断言 / 60s 并发横幅）
+  // 均非阻断。本门 fail-closed：名为「Wave N 执行」的步骤 --done 时本 Wave 任一 task 的
+  // tasks.md checkbox 未勾 → exit 1（先 autoCheckPlanFromReviews 幂等补勾再核对，见
+  // complete-handlers.js assertWaveTasksComplete）。门自身异常 fail-open warn——门 bug 不
+  // 锁死完成路径，正常判定路径硬拦；exit 时 status 尚未赋 completed，DB 不落假完成态。
+  try {
+    await assertWaveTasksComplete({ steps, currentIdx, changeName, cwd, specBase, platformOpts })
+  } catch (e) {
+    console.warn(`⚠️ Wave 完成度门异常，fail-open 放行（不阻断本次完成）: ${(e && e.message) || e}`)
+  }
+
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   if (outputText) {
@@ -666,6 +702,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 })
@@ -931,7 +971,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 {
@@ -952,7 +996,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) {
@@ -962,16 +1012,96 @@ 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 实测路径，原语义）。
+ *
+ * task-05 FR-08：另并入跨仓仓根双源（diff HEAD~1..HEAD ∪ status porcelain，见函数体
+ * collectCrossRepoDiffRoots 注记）——跨仓 task 的 changedFiles 按其仓根相对路径命中。
  */
+/**
+ * 跨仓仓根收集（task-05 / FR-08 diff 源层）：读侧口径 = <cwd>/.sillyspec/local.yaml 的
+ * parseRepoRegistry（与 design-facts.js 有段头分支 / execute MultiRepoContext 同款）；相对
+ * 注册路径按 cwd resolve，绝对路径原样，根不存在跳过。local.yaml 不可读/解析失败 fail-open
+ * 返回 []（不炸勾选主流程、不放大勾选面）。
+ */
+function collectCrossRepoDiffRoots(cwd) {
+  const roots = []
+  try {
+    if (!cwd) return roots
+    const localYamlPath = join(cwd, '.sillyspec', 'local.yaml')
+    if (!existsSync(localYamlPath)) return roots
+    const registry = parseRepoRegistry(readFileSync(localYamlPath, 'utf8'))
+    if (!registry) return roots
+    for (const raw of registry.values()) {
+      if (!raw) continue
+      const root = isAbsolute(raw) ? raw : resolve(cwd, raw)
+      if (root && existsSync(root)) roots.push(root)
+    }
+  } catch { /* registry 不可读 → 空表（fail-open） */ }
+  return roots
+}
+
 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)
+    }
+    // task-05 FR-08：跨仓仓根 diff 双源并入（adopt 通道跨仓 review 的 changedFiles 是其仓根
+    // 相对路径，只算主仓源时 shouldAutoCheckTask 的 ctx.diffFileSet.has(f) 恒 miss → 跨仓
+    // task 自动勾选断链）。双源 = git diff --name-only HEAD~1..HEAD ∪ git status --porcelain
+    // --untracked-files=all（cross-repo-reconcile.js:94-106 双源口径只读复用，数组参数防
+    // shell 拆词），产物正斜杠归一；置于剔 baseline 之后（跨仓仓不含主仓 baseline checkpoint
+    // 提交，不被主仓夹带清单误剔）。git 失败/registry 不可读 fail-open 跳过该仓不炸主流程。
+    try {
+      for (const root of collectCrossRepoDiffRoots(ctx.cwd)) {
+        let anySource = false
+        const diffOut = gitQuiet(root, ['diff', '--name-only', 'HEAD~1..HEAD'], { timeout: 30 * 1000 })
+        if (diffOut !== null) {
+          anySource = true
+          for (const f of String(diffOut).split('\n')) {
+            const n = String(f || '').trim().replace(/^\.\//, '').replace(/\\/g, '/')
+            if (n) diffFileSet.add(n)
+          }
+        }
+        const statusOut = gitQuiet(root, ['status', '--porcelain', '--untracked-files=all'], { timeout: 30 * 1000, trim: false })
+        if (statusOut !== null) {
+          anySource = true
+          for (const line of String(statusOut).split('\n')) {
+            // porcelain 行 = XY<space>path（剥前 3 列）；rename 取 -> 后新路径；剥引号、正斜杠归一
+            let p = line.slice(3).trim()
+            if (p.includes(' -> ')) p = p.slice(p.lastIndexOf(' -> ') + 4).trim()
+            p = p.replace(/^"|"$/g, '').replace(/\\/g, '/')
+            if (p) diffFileSet.add(p)
+          }
+        }
+        if (!anySource) console.warn(`⚠️ 跨仓仓根 ${root} git 不可用/非仓库（diff 与 status 双失败），跳过该仓 diff 源（fail-open，不阻断勾选主流程）`)
+      }
+    } catch { /* 跨仓源异常 → 不炸主流程（fail-open） */ }
+    if (diffFileSet.size === 0) return ctx
+    return { ...ctx, diffFileSet }
   } catch {
     return ctx
   }
@@ -1546,6 +1676,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 })

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,336 @@ 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
+}
+
+/**
+ * local.yaml `gate_snapshot:` 段 `copy:` 列表的轻量行扫描（与 verify-postcheck
+ * extractLintCommand 同风格——单键定向取值，不引 js-yaml，本文件零新依赖）。
+ *
+ * 认块列表（缩进 `- <path>` 条目）与 inline flow（`copy: [a, b]`）两形态（对齐
+ * worktree.supplyFiles 等既有数组键的「块列表或 inline flow 均可解析」约定）；空行/注释行
+ * 跳过不破段；离开 gate_snapshot 段（缩进回收到段头及以下 / 新顶层键）即止。容错：值剥
+ * 尾注（` #…`）与成对引号。
+ * @param {string} yamlText local.yaml 原文
+ * @returns {string[]} copy 条目原始值（未规整，交 applyGateSnapshotCopy 逐条规整）
+ */
+function _stripYamlValue(v) {
+  let s = String(v).trim()
+  const hash = s.indexOf(' #')
+  if (hash >= 0) s = s.slice(0, hash).trim()
+  if ((s.startsWith('"') && s.endsWith('"') && s.length >= 2) || (s.startsWith("'") && s.endsWith("'") && s.length >= 2)) {
+    s = s.slice(1, -1).trim()
+  }
+  return s
+}
+
+function parseGateSnapshotCopy(yamlText) {
+  if (!yamlText) return []
+  const out = []
+  let inGate = false   // 位于 gate_snapshot: 段内
+  let gateIndent = -1
+  let inCopy = false   // 位于段内 copy: 列表内
+  let copyIndent = -1
+  for (const raw of String(yamlText).split(/\r?\n/)) {
+    const content = raw.trim()
+    if (!content || content.startsWith('#')) continue // 空行/注释行不破段
+    const indent = raw.match(/^[ \t]*/)[0].length
+    if (!inGate) {
+      if (/^gate_snapshot:\s*(?:#.*)?$/.test(content)) { inGate = true; gateIndent = indent; inCopy = false }
+      continue
+    }
+    if (indent <= gateIndent) { inGate = false; inCopy = false; continue } // 出段（新顶层键）
+    if (!inCopy) {
+      const flow = content.match(/^copy:\s*\[([^\]]*)\]/)
+      if (flow) {
+        for (const part of flow[1].split(',')) {
+          const v = _stripYamlValue(part)
+          if (v) out.push(v)
+        }
+        continue // inline flow 当行自洽，继续扫段内后续内容
+      }
+      if (/^copy:\s*(?:#.*)?$/.test(content)) { inCopy = true; copyIndent = indent }
+      continue // 段内其它子键忽略
+    }
+    if (indent < copyIndent) { inCopy = false; continue } // 缩进回收出列表
+    const item = content.match(/^-\s*(.+)$/)
+    if (!item) { inCopy = false; continue } // 同层非列表行 = 列表结束
+    const v = _stripYamlValue(item[1])
+    if (v) out.push(v)
+  }
+  return out
+}
+
+/**
+ * local.yaml `gate_snapshot:` 段 `commands:` 列表扫描（2026-09-17-feedback-hardening
+ * R1 / FR-01 / D-002@v2，坑 gate-snapshot-missing-generated-artifacts 二阶——copy 面只搬
+ * 「主仓现有态」，主仓侧生成物缺失（fresh clone 未跑 postinstall）或过期（build-id 类
+ * 构建期产物随版本变）时供给缺失/陈旧态，快照内全量 lint/test 必挂，用户 2026-09-17
+ * 负面①实证）。与 parseGateSnapshotCopy 同风格段内单键扫描（本文件零新依赖，不引
+ * js-yaml）；认块列表（缩进 `- <cmd>` 条目）与 inline flow（`commands: [a, b]`）双形态
+ *（对齐 supplyFiles/copy 既有数组键约定）；空行/注释行不破段；缩进回收到段头及以下/
+ * 新顶层键即出段——段外同名键（顶层 `commands:` 命令段 / 其它段内嵌 commands）不误收。
+ * @param {string} yamlText local.yaml 原文
+ * @returns {string[]} 命令串（未配置/空段/读失败 → []）
+ */
+export function parseGateSnapshotCommands(yamlText) {
+  if (!yamlText) return []
+  const out = []
+  let inGate = false    // 位于 gate_snapshot: 段内
+  let gateIndent = -1
+  let inCmds = false    // 位于段内 commands: 列表内
+  let cmdsIndent = -1
+  for (const raw of String(yamlText).split(/\r?\n/)) {
+    const content = raw.trim()
+    if (!content || content.startsWith('#')) continue // 空行/注释行不破段
+    const indent = raw.match(/^[ \t]*/)[0].length
+    if (!inGate) {
+      if (/^gate_snapshot:\s*(?:#.*)?$/.test(content)) { inGate = true; gateIndent = indent; inCmds = false }
+      continue
+    }
+    if (indent <= gateIndent) { inGate = false; inCmds = false; continue } // 出段（新顶层键）
+    if (!inCmds) {
+      const flow = content.match(/^commands:\s*\[([^\]]*)\]/)
+      if (flow) {
+        for (const part of flow[1].split(',')) {
+          const v = _stripYamlValue(part)
+          if (v) out.push(v)
+        }
+        continue // inline flow 当行自洽，继续扫段内后续内容
+      }
+      if (/^commands:\s*(?:#.*)?$/.test(content)) { inCmds = true; cmdsIndent = indent }
+      continue // 段内其它子键（copy 等）忽略
+    }
+    if (indent < cmdsIndent) { inCmds = false; continue } // 缩进回收出列表
+    const item = content.match(/^-\s*(.+)$/)
+    if (!item) { inCmds = false; continue } // 同层非列表行 = 列表结束
+    const v = _stripYamlValue(item[1])
+    if (v) out.push(v)
+  }
+  return out
+}
+
+/**
+ * gate_snapshot.commands 执行段（D-002@v2）：快照构建期在快照根逐条执行生成物命令，产出
+ * 「本仓应然态」。调用契约：cwd=**快照根**（环境目录 junction 已就位；命令产出真实文件
+ * → 后续 copy 面对已存在 dst 跳过，新鲜度优先）。每条 300s 超时帽；非零退出/超时只
+ * warn（含 cmd 与输出尾 ≤300 字）继续下一条——fail-open 与 copy 面同策略，不作废快照；
+ * 执行结果不落 meta（快照即用即弃，console 输出即审计面）。信任级与
+ * commands.install/test/lint 同：主仓 local.yaml 用户自持配置，不加命令白名单。
+ * 内部导出（createGateSnapshot 唯一运行时消费方；直测断言返回值）。
+ * @param {string} snapshotRoot 快照根（命令 cwd）
+ * @param {string[]} commands 命令串列表（parseGateSnapshotCommands 产物）
+ * @returns {{ ran: number, failed: Array<{cmd: string, reason: string}> }} ran=实际执行条数（含失败），failed=逐条失败记录
+ */
+export function runGateSnapshotCommands(snapshotRoot, commands) {
+  if (!Array.isArray(commands) || commands.length === 0) return { ran: 0, failed: [] }
+  let ran = 0
+  const failed = []
+  for (const raw of commands) {
+    const cmd = String(raw).trim()
+    if (!cmd) continue
+    ran++
+    let r = null
+    try {
+      r = spawnSync(cmd, { shell: true, cwd: snapshotRoot, timeout: 300_000, encoding: 'utf8' })
+    } catch (e) {
+      const reason = `spawn 异常：${e && e.message ? e.message : e}`
+      failed.push({ cmd, reason })
+      console.warn(`⚠️ gate_snapshot.commands 条目失败（${reason}，不作废快照）：${cmd}`)
+      continue
+    }
+    const timedOut = r && r.error && (r.error.code === 'ETIMEDOUT' || /ETIMEDOUT/i.test(String(r.error.message || '')))
+    if (r.error || r.status !== 0) {
+      const reason = timedOut
+        ? '超时（>300s 帽）'
+        : (r.error ? `spawn 失败：${r.error.message}` : `非零退出码 ${r.status}`)
+      failed.push({ cmd, reason })
+      const tail = String((r.stdout || '') + (r.stderr || '')).trim().slice(-300)
+      console.warn(`⚠️ gate_snapshot.commands 条目失败（${reason}，不作废快照继续下一条）：${cmd}${tail ? `｜输出尾：${tail}` : ''}`)
+      continue
+    }
+  }
+  return { ran, failed }
+}
+
+/** 目录递归复制（copy 面 junction 不可用时的回退）。符号链接条目跳过（生成物目录内不追链）。 */
+function copyDirRecursive(srcDir, dstDir) {
+  mkdirSync(dstDir, { recursive: true })
+  for (const e of readdirSync(srcDir, { withFileTypes: true })) {
+    const s = join(srcDir, e.name)
+    const d = join(dstDir, e.name)
+    if (e.isDirectory()) copyDirRecursive(s, d)
+    else if (e.isFile()) copyFileSync(s, d)
+  }
+}
+
+/**
+ * gate_snapshot.copy 面（2026-09-16-friction5-hardening R4 / FR-04 / D-002@v1，坑
+ * gate-snapshot-missing-generated-artifacts——用户 2026-09-16 驾驭小结④实证只能
+ * SNAPSHOT_OFF 对照）：HEAD 快照缺 gitignored 生成物（api-types/generated 类不进 HEAD
+ * 也不在会话文件集）→ 快照内 lint/test 环境性假败。按主仓 local.yaml 的 copy 清单把
+ * 生成物从主仓 junction 链接进快照（失败回退复制），消除环境性假败。
+ *
+ * 调用契约：cwd=**主仓**根（local.yaml 从主仓读——快照内 local.yaml 是稍后复制的复制件，
+ * copy 面必须先于复制生效）；在 overlay 之后调用（dst 已存在 = overlay 已覆盖本变更最新态，
+ * 跳过不覆盖）。
+ *
+ * 逐条容错（fail-open，与本文件快照基建策略一致，任何失败不作废快照）：路径规整
+ *（String、反斜杠→正斜杠、trim）；含 '..' 或绝对路径形态（POSIX / 与 Windows 盘符）拒绝
+ * warn 跳过；主仓不存在 warn 跳过；junction 抛错回退递归 copy（目录）/ copyFileSync（文件）；
+ * 再失败 warn 跳过。成功 ≥1 条 console.log 一行报备。未配置/空清单/读失败 → 全段空转
+ * 零输出零行为（存量 local.yaml 逐字节不变）。
+ *
+ * ⚠️ junction 是活链接：快照内再跑生成命令会写穿到主仓该目录（constraints 明示，
+ * config-schema desc 与 renderExample 注释同步警告）。
+ *
+ * 新增内部导出（symbol-impact：内部测试直测边界条目用；createGateSnapshot 唯一运行时消费方）。
+ * @param {string} cwd 主仓根
+ * @param {string} snapshotRoot 快照根
+ * @returns {number} 成功链接/复制的条目数
+ */
+export function applyGateSnapshotCopy(cwd, snapshotRoot) {
+  let entries = []
+  try {
+    const cfgPath = join(cwd, '.sillyspec', 'local.yaml')
+    if (!existsSync(cfgPath)) return 0
+    entries = parseGateSnapshotCopy(readFileSync(cfgPath, 'utf8'))
+  } catch { return 0 } // 读侧容错：解析/读失败与未配置同兜底（空转，不连坐快照）
+  if (!Array.isArray(entries) || entries.length === 0) return 0
+  let linked = 0
+  for (const raw of entries) {
+    const p = String(raw).replace(/\\/g, '/').trim()
+    if (!p) continue
+    if (p.includes('..') || p.startsWith('/') || /^[A-Za-z]:\//.test(p)) {
+      console.warn(`⚠️ gate_snapshot.copy 条目「${p}」含 .. 或绝对路径形态，拒绝（快照外写面）——跳过`)
+      continue
+    }
+    let srcStat = null
+    try { srcStat = statSync(join(cwd, p)) } catch { /* 主仓不存在，下方 warn 跳过 */ }
+    if (!srcStat) {
+      console.warn(`⚠️ gate_snapshot.copy 条目主仓不存在，跳过：${p}`)
+      continue
+    }
+    const src = join(cwd, p)
+    const dst = join(snapshotRoot, p)
+    if (existsSync(dst)) continue // overlay 已覆盖（本变更最新态优先）
+    try {
+      mkdirSync(dirname(dst), { recursive: true })
+      let viaLink = false
+      try {
+        symlinkSync(src, dst, 'junction')
+        // Windows 文件 junction 可「建成但不解析」（重解析点指向非目录，symlinkSync 不抛、
+        // existsSync 为假）——链接后验真，假成功回退复制（平台差异实测坑）
+        viaLink = existsSync(dst)
+      } catch { viaLink = false }
+      if (!viaLink) {
+        try { rmSync(dst, { recursive: true, force: true }) } catch { /* 假链接残留清不掉 → 下方复制报错走 warn */ }
+        if (srcStat.isDirectory()) copyDirRecursive(src, dst)
+        else copyFileSync(src, dst)
+      }
+      linked++
+    } catch (e) {
+      console.warn(`⚠️ gate_snapshot.copy 条目「${p}」junction/复制均失败：${e && e.message ? e.message : e}——跳过（不作废快照）`)
+    }
+  }
+  if (linked > 0) {
+    console.log(`🔬 门禁快照 copy 面：${linked} 个 gate_snapshot.copy 条目自主仓 junction/复制进快照（⚠️ junction 是活链接，快照内再跑生成命令会写穿到主仓该目录）`)
+  }
+  return linked
+}
+
 /**
  * 创建隔离快照：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 环境回退主仓现行为）
@@ -103,6 +427,32 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null }) {
       return null
     }
 
+    // gate_snapshot.commands 命令面（D-002@v2，2026-09-17-feedback-hardening R1，用户
+    // 2026-09-17 负面①实证「全量快照必挂」）：主仓侧生成物缺失（fresh clone 未跑
+    // postinstall）或过期时，copy 面只搬「主仓现有态」供给缺失/陈旧态——本段在环境链接
+    // 就位后、copy 面前于快照根逐条执行 postinstall 类生成命令，产出「本仓应然态」（命令
+    // 产出真实文件 → copy 面对已存在 dst 跳过，新鲜度优先）。配置恒从主仓 cwd 读原文
+    //（local.yaml 复制段在后面，快照内副本不采信——与 copy 键同源）。未配置 → 全段空转
+    // 零输出（存量快照逐字节不变）；整段 try/catch fail-open：任何异常只 warn 不作废快照。
+    try {
+      const gsCfgPath = join(cwd, '.sillyspec', 'local.yaml')
+      const gsCommands = existsSync(gsCfgPath) ? parseGateSnapshotCommands(readFileSync(gsCfgPath, 'utf8')) : []
+      if (gsCommands.length > 0) {
+        console.log(`🔬 门禁快照 commands 面：${gsCommands.length} 条 gate_snapshot.commands 在快照内逐条执行（cwd=快照根，产出本仓应然态生成物）`)
+        console.warn(`⚠️ 环境目录是活链接：命令不得改写 node_modules/venv 等环境目录（写会穿透到主仓）——只放生成物命令（npm run gen:build-id 类）`)
+        runGateSnapshotCommands(snapshotRoot, gsCommands)
+      }
+    } catch (e) {
+      console.warn(`⚠️ gate_snapshot.commands 执行段异常（不作废快照）：${e && e.message ? e.message : e}`)
+    }
+
+    // gate_snapshot.copy 面（R4 / D-002@v1，2026-09-16-friction5-hardening）：gitignored
+    // 生成物从主仓 junction/复制进快照。位置=环境目录链接段之后（环境优先级最高）、
+    // local.yaml 复制段之前（从主仓 cwd 读原文——快照内 local.yaml 是稍后才复制的复制件，
+    // 且 copy 面必须先于复制生效）；overlay 已在上面完成（dst 已存在即跳过，本变更最新态优先）。
+    // 未配置 gate_snapshot.copy → 全段空转零行为（见 applyGateSnapshotCopy jsdoc）。
+    applyGateSnapshotCopy(cwd, snapshotRoot)
+
     // local.yaml（gitignore 不进 HEAD；门禁命令配置来源）+ package-lock 保持 HEAD 版（npm test 不装新依赖）
     for (const cfg of [join('.sillyspec', 'local.yaml')]) {
       const src = join(cwd, cfg)
@@ -112,6 +462,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 清理 */ }