sillyspec 3.28.10 → 3.28.11

package/src/run/complete-handlers.js

@@ -9,6 +9,9 @@
  *     srcDir 缺失时走 findAlreadyArchivedDir 幂等自愈（issue archive-stage-physical-tracking-desync）；
  *     archiveChangeDirectory + findAlreadyArchivedDir 已 export 供 test 直接 import
  *   - sanitizeProjectName / validateParsedProjects：项目名清洗 + 列表校验纯函数（handleScanProjectListStep 专用）
+ *   - assertWaveTasksComplete：execute「Wave N 执行」步骤 --done 前的完成度门（task-08 / FR-12——
+ *     本 Wave 任一 task 的 tasks.md checkbox 未勾 → exit 1；completeStep 在 status='completed' 赋值前
+ *     调用，异常 fail-open），实现收拢文件尾（同知识闭环段先例）
  *
  * 安全锚：run.js 始终 barrel。3 handler 由 run.js import 回来；sanitizeProjectName + validateParsedProjects
  * 被 test 直接 import（run-sanitize-project-name / run-scan-project-parse），run.js barrel re-export 契约保留。
@@ -46,7 +49,9 @@ import { resolveSessionIdentity } from '../progress.js'
 // ql-20260915-001 修复④：chunkPaths（argv 分批）供归档窄化 add / minePaths 精确补暂存用。
 // 无环：worktree-apply 静态闭包（worktree/task-review/quicklog 等）不引本文件；既有
 // withMainRepoLock 走动态 import 是归档链防环的历史形态，chunkPaths 纯函数无此约束。
-import { chunkPaths } from '../worktree-apply.js'
+// checkDbScriptDeclarationGate（task-04 / FR-05）同排静态引入：门函数自身纯文件集 ×
+// 文本声明对账（verify-probes 文法经 worktree-apply 顶层动态绑定），同样无环约束。
+import { chunkPaths, checkDbScriptDeclarationGate } from '../worktree-apply.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -785,6 +790,32 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
+  // ── db/*.sql 声明门·归档前置（2026-09-17-pass-cap-semantics task-04 / FR-05 / D-007/D-012
+  // 兜底第二门）── --confirm 已过、目录移动前：apply-manifest.json 的 files 过 worktree-apply
+  // 同款门（对账 verify-result.md 声明，含 db-script handover 互斥）。缺失/互斥 → 复用 !
+  // confirm 早退形态（status 回 pending + pm._write + early return），变更目录不动、输出修复
+  // 指引；apply-manifest.json 缺失 → 门空转不阻断（无 apply 面，主门在 verify 侧事实③）；
+  // manifest 读取/解析异常 → fail-open warn 放行（门异常不锁死归档）。
+  const dbGateManifestPath = join(specBase, 'changes', changeName, 'apply-manifest.json')
+  if (existsSync(dbGateManifestPath)) {
+    try {
+      const dbGateManifest = JSON.parse(readFileSync(dbGateManifestPath, 'utf8'))
+      const dbGateFiles = (dbGateManifest && Array.isArray(dbGateManifest.files) ? dbGateManifest.files : [])
+        .map((e) => (e && typeof e === 'object' ? e.path : e)).filter(Boolean)
+      const dbGate = checkDbScriptDeclarationGate({ projectRoot: cwd, specBase, changeName, files: dbGateFiles })
+      if (!dbGate.ok) {
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        pm._write(cwd, progress, changeName)
+        console.error(`⛔ db 脚本执行声明对账未过（归档阻断，变更目录未移动）：\n${dbGate.error}`)
+        return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+      }
+      if (dbGate.warning) console.warn(`⚠️  ${dbGate.warning}`)
+    } catch (e) {
+      console.warn(`⚠️  db 声明门异常降级放行（apply-manifest.json 读取/解析失败，fail-open）: ${(e && e.message) || e}`)
+    }
+  }
   // ── 归档前 delta.md 自动生成（P3d task-02，fail-soft 零阻断）──
   // 目录移走前在 changes/<name>/ 落一份 Before/Delta/After 三段式快照（四源采集容缺，
   // buildDeltaReport 见 ../archive-delta.js），随归档包留存。失败只 console.error 留痕、
@@ -2481,3 +2512,143 @@ export function extractQuickCauseField(outputText) {
   return m[1].replace(/\s+/g, ' ').trim()
 }
 
+// ── Wave 步骤完成度门（2026-09-17-pass-cap-semantics task-08 / FR-12 / D-013@v1）──
+// 动机锚：2026-09-17 本变更执行中 Wave 2 越位实证——review write 退出码被 shell 管道吞掉后
+// --done 落在下一 Wave，「Wave 2 执行」步骤被静默标 completed；既有防护（--step 意图断言
+// 可选、并发 60s 横幅仅 warn）均非阻断。本门 fail-closed 补执行期缺口，放文件尾（函数声明
+// 提升 + B1 源码文本级断言窗口约束，同知识闭环段先例——门内含 process.exit，收拢在此避免
+// 推挪 handleQuickStageCompletion 附近 detectConcurrentChanges ±[200,600] 的断言锚）。
+
+/**
+ * 解析 plan.md 第 seq 个显式 Wave 段的任务 ID 列表。
+ *
+ * 同源口径孪生（不造第二套解析）：src/stages/execute.js 的 parseWavesFromPlan 未导出，且
+ * execute.js 不在本任务 allowed_paths，无法直接 import——正则与段边界守卫逐字对齐：
+ *   - Wave 标题 /^#+\s*Wave\s*(\d+)/i（空格可选、编号后缀任意——解析侧宁可多收不可静默丢）
+ *   - 引用行 /^[-*]\s+task-(\d+)\s*$/i → 归一 task-NN（padStart(2,'0')）
+ *   - 任何非 Wave 标题行（/^#{1,6}\s+/）退出当前段（「## 自检」等后续段的行不收）
+ *   - 段序 = 出现顺序（buildExecuteSteps 的步骤名 `Wave ${i+1} 执行` 取 waves 数组位次，
+ *     非段内编号——显式段存在时两者通常一致，乱序编号时位次与 prompt 实际下发任务一致）
+ * 差异（有意）：不做 parseWavesFromPlan 的隐式 Wave 合成——门只核对显式段，plan 无显式段
+ * 一律 null 交由调用方 warn 放行（D-003@v1 隐式串行语义无段可核对，不误伤）。
+ * 漂移风险由 test/wave-task-complete-gate.test.mjs 断言锁定。
+ *
+ * @param {string} planContent plan.md 全文
+ * @param {number} seq 1-based 显式段位次（步骤名编号同源）
+ * @returns {string[]|null} 该段 task ID 列表；null = 显式段不足 seq 个（隐式/light/兜底形态）
+ */
+function parseExplicitWaveTaskIds(planContent, seq) {
+  const WAVE_HEADING_RE = /^#+\s*Wave\s*(\d+)/i   // ← execute.js parseWavesFromPlan 同源正则
+  const waveRefRe = /^[-*]\s+task-(\d+)\s*$/i     // ← execute.js parseWavesFromPlan 同源正则
+  const sections = []   // [{ index, ids }] 按出现顺序（不合成隐式 Wave）
+  let current = null
+  for (const rawLine of String(planContent || '').split('\n')) {
+    const line = rawLine.replace(/\r$/, '')
+    const waveMatch = line.match(WAVE_HEADING_RE)
+    if (waveMatch) {
+      current = { index: parseInt(waveMatch[1], 10), ids: [] }
+      sections.push(current)
+      continue
+    }
+    if (/^#{1,6}\s+/.test(line)) { current = null; continue }
+    const refMatch = line.match(waveRefRe)
+    if (refMatch && current) current.ids.push(`task-${refMatch[1].padStart(2, '0')}`)
+  }
+  const target = sections[seq - 1]
+  return target ? target.ids : null
+}
+
+/**
+ * Wave 步骤完成度门（task-08 / FR-12 / D-013@v1）：execute 阶段名为「Wave N 执行」的步骤
+ * --done 时 fail-closed 核对本 Wave 全部 task 的 tasks.md checkbox 已勾（勾选唯一真源是
+ * CLI：review write 落盘即勾 + autoCheckPlanFromReviews 兜底）。任一未勾 → console.error
+ * 列未勾清单与两条出路 + process.exit(1)，步骤保持待完成（接线点在 completeStep 的
+ * status='completed' 赋值之前，exit 时 DB 不落假完成态）。
+ *
+ * 生效面与放行面：
+ *   - 仅 steps[currentIdx].name 匹配 /^Wave (\d+) 执行$/ 时生效，其他步骤名直接 return（零行为）
+ *   - ① autoCheckPlanFromReviews 幂等先行（review pass 自动勾选——先补勾再核对，「review 已
+ *     pass 但 checkbox 未回填」形态不误拦；该函数自身全路径 try/catch 从不抛）
+ *   - plan.md 无第 N 个显式 Wave 段（隐式 Wave/light 计划）→ warn 放行（D-003@v1 不误伤）
+ *   - plan.md/tasks.md 缺失或读取失败 → warn 放行（fail-open，文档瞬态不锁死流程）
+ *   - 门自身意外异常不在本函数内吞——上抛给接线层（complete.js）fail-open warn 放行；
+ *     正常判定路径（读到未勾）必须硬拦，process.exit 不受 try/catch 影响
+ *
+ * @param {{ steps: Array<{name:string}>, currentIdx: number, changeName: string, cwd: string, specBase?: string, platformOpts?: object }} opts
+ *   changeDir 锚定与 autoCheckPlanFromReviews 写入侧同口径（driftAnchor > specRoot > specBase >
+ *   cwd/.sillyspec）——tasks.md 是 autoCheck 写的，门必须读同一份，防双真源分裂。
+ */
+export async function assertWaveTasksComplete({ steps, currentIdx, changeName, cwd, specBase, platformOpts = {} }) {
+  const stepName = String(steps?.[currentIdx]?.name || '')
+  const waveMatch = /^Wave (\d+) 执行$/.exec(stepName)
+  if (!waveMatch) return   // 非「Wave N 执行」步骤：零行为（其他 execute 步骤 / 其他阶段不门）
+  const waveSeq = parseInt(waveMatch[1], 10)
+  if (!changeName || !cwd) {
+    console.warn(`⚠️ [wave-complete-gate] 缺 changeName/cwd，跳过「${stepName}」完成度核对（fail-open）`)
+    return
+  }
+
+  // ① autoCheck 幂等先行（D-013）：兜底 catch 仅防动态 import 自身失败——warn 后继续核对
+  //   （checkbox 才是门的判定依据；勾选补偿失败留给两条出路①重跑 --done 再试，不锁死）。
+  //   autoCheckPlanFromReviews 定义于 ./complete.js（grep 实证 :1172 export；任务卡原文写
+  //   ../task-review.js 系定位笔误，该文件仅有引用注释无定义）；动态 import 防顶层环
+  //   （complete.js 静态 import 本文件，运行时调用时 complete.js 已在模块缓存，无死锁）。
+  try {
+    const { autoCheckPlanFromReviews } = await import('./complete.js')
+    await autoCheckPlanFromReviews({ stageName: 'execute', changeName, cwd, platformOpts })
+  } catch (e) {
+    console.warn(`⚠️ [wave-complete-gate] autoCheck 先行勾选失败，按 tasks.md 现状继续核对: ${(e && e.message) || e}`)
+  }
+
+  const gateSpecBase = platformOpts?.specDriftAnchor || platformOpts?.specRoot || specBase || join(cwd, '.sillyspec')
+  const changeDir = join(gateSpecBase, 'changes', changeName)
+  const planPath = join(changeDir, 'plan.md')
+  const tasksPath = join(changeDir, 'tasks.md')
+
+  let planContent, tasksContent
+  try {
+    if (!existsSync(planPath) || !existsSync(tasksPath)) {
+      console.warn(`⚠️ [wave-complete-gate] plan.md/tasks.md 缺失（${changeDir}），跳过「${stepName}」完成度核对（fail-open 放行）`)
+      return
+    }
+    planContent = readFileSync(planPath, 'utf8')
+    tasksContent = readFileSync(tasksPath, 'utf8')
+  } catch (e) {
+    console.warn(`⚠️ [wave-complete-gate] plan.md/tasks.md 读取失败（${(e && e.message) || e}），跳过核对（fail-open 放行）`)
+    return
+  }
+
+  // ② 本 Wave 任务 ID 列表（parseExplicitWaveTaskIds：execute.js parseWavesFromPlan 同源孪生）
+  const waveTaskIds = parseExplicitWaveTaskIds(planContent, waveSeq)
+  if (waveTaskIds === null) {
+    console.warn(`⚠️ [wave-complete-gate] plan.md 无第 ${waveSeq} 个显式 Wave 段（隐式 Wave/light 计划无显式段头），跳过完成度核对（fail-open 放行——D-003@v1 隐式串行语义不误伤）`)
+    return
+  }
+  if (waveTaskIds.length === 0) {
+    // 段在但无引用行：execute 启动时 validatePlanForExecute 已拦（空 Wave 段诊断），不重复拦
+    return
+  }
+
+  // ③ tasks.md checkbox 逐 ID 核对（parseTaskRegistry 是 execute.js 导出的同源解析，复用不另造）
+  const { parseTaskRegistry } = await import('../stages/execute.js')
+  const registry = parseTaskRegistry(tasksContent)
+  const regById = new Map(registry.map(t => [t.id, t]))
+  const unchecked = waveTaskIds.filter(id => regById.get(id)?.done !== true)
+
+  if (unchecked.length > 0) {
+    // ④ fail-closed 硬拦：沿用仓内 console.error + process.exit(1) 既有形态（错误信息
+    //    process.exit 前同步打印完整——Windows 下 UV_HANDLE_CLOSING 退出码坑不复现）
+    console.error(`❌ Wave ${waveSeq} 完成度门未过：本 Wave ${waveTaskIds.length} 个 task 中 ${unchecked.length} 个的 tasks.md checkbox 未勾——本次 --done 未完成，步骤「${stepName}」保持待完成。`)
+    console.error('   未勾任务：')
+    for (const id of unchecked) {
+      const reg = regById.get(id)
+      console.error(`   - ${id}${reg && reg.name ? `（${reg.name}）` : '（tasks.md 注册表无此行——plan 悬空引用）'}`)
+    }
+    console.error('   两条出路：')
+    console.error(`   ① 任务确未完成：补实现与 review write（sillyspec review write --change ${changeName} --task <task-NN> --spec pass --quality pass --force --changed-files <文件>）后重跑 --done——review pass 落盘即自动勾选`)
+    console.error(`   ② 确属误推进（步骤被越位标完成）：sillyspec run execute --reopen --from-step ${currentIdx + 1}${changeName ? ` --change ${changeName}` : ''} 退回本步重走完成`)
+    process.exit(1)
+  }
+  console.log(`🛡️ 「${stepName}」完成度门通过：${waveTaskIds.length} 个 task checkbox 全勾（${waveTaskIds.join('、')}）`)
+}
+

package/src/run/complete.js

@@ -16,7 +16,7 @@
  *   - 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'
@@ -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'
@@ -488,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) {
@@ -1009,7 +1022,33 @@ async function buildDraftContext(cwd, changeName) {
  * 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 {
@@ -1030,6 +1069,37 @@ function prefetchDiffFileSet(ctx) {
       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 {

package/src/run/gate-snapshot.js

@@ -111,6 +111,242 @@ function smokeImportPython(pythonBin, snapshotRoot, relFile) {
   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）
@@ -191,6 +427,32 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
       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)