sillyspec 3.28.4 → 3.28.6

package/src/run/complete-handlers.js

@@ -34,6 +34,8 @@ import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate } f
 import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult, parseFileNotes, getQuickFileNotes } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
+import { collectNumstatByPath } from '../scope-audit.js'
+import { recordFrictionEvent, consumeFrictionHint } from '../friction-tally.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -169,6 +171,13 @@ export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
     if (existsSync(pathspec)) gone(pathspec)
   } catch {}
 
+  // friction tally（friction-signal-hint FR-05）：摩擦计数随变更终态一并回收——真实变更的
+  // friction-tally-<change>.json 落 runtimeRoot，变更归档/删除后无读者，残留即孤儿文件。
+  try {
+    const fp = join(runtimeRoot, `friction-tally-${changeName}.json`)
+    if (existsSync(fp)) gone(fp)
+  } catch {}
+
   try {
     const execDir = join(runtimeRoot, 'execute-runs')
     if (existsSync(execDir)) {
@@ -1055,6 +1064,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         steps[currentIdx].status = 'pending'
         steps[currentIdx].completedAt = null
         if (outputText) steps[currentIdx].output = null
+        // 摩擦计数（friction-signal-hint task-04）：quick 审计被拦也是摩擦信号——exit 前记
+        // 一笔（changeName=quick 会话 id，tally 落 session 目录，成功收尾 consume 后随目录清理）。
+        recordFrictionEvent({ cwd, changeName, platformOpts, type: 'gate_rollback', detail: 'quick-audit' })
         process.exit(1)
       }
       // P0-2（2026-09-02 跨 agent 工单）：触及 src/test 的 quick --done 内置 test+lint
@@ -1075,6 +1087,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         steps[currentIdx].status = 'pending'
         steps[currentIdx].completedAt = null
         if (outputText) steps[currentIdx].output = null
+        // 摩擦计数（friction-signal-hint task-04）：test/lint 实测门禁拦下同记摩擦——exit 前
+        // 落 session tally，与 quick-audit 同款静默降级。
+        recordFrictionEvent({ cwd, changeName, platformOpts, type: 'gate_rollback', detail: 'quick-test-lint' })
         process.exit(1)
       }
       progress.lastQuickReview = review
@@ -1203,6 +1218,14 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         ? review.attributedFiles
         : (Array.isArray(review?.changedFiles) ? review.changedFiles : [])
       const realFiles = auditFiles.filter(f => !isQuicklogFileLineNoise(f, linkedChanges))
+      // 软归属（2026-09-10 用户反馈：--file-notes 括注只落声明文件，同模块测试文件漏声明时文件行
+      // 不自动补齐，连续多批手工核对）：auditQuickCompletion 判定的「窗口内未声明同模块测试文件」
+      // → 补入文件行 bullet 带软归属括注；审计面单列 🔍 行（可追溯、错认可手工剔除），⚠️ 不进
+      // attributedFiles——硬归属口径「声明即归属」不变（2026-08-18 误归属修复）。
+      const softFiles = (Array.isArray(review?.softTestFiles) ? review.softTestFiles : [])
+        .map(f => String(f).replace(/\\/g, '/')).filter(f => !isQuickMetadata(f, linkedChanges))
+      // task-06（FR-04）：文件行/审计行并上 numstat 行数——attachQuickLineCounts 见文件尾（声明提升）
+      const { annotatedRealFiles, annotatedSoftFiles, fmtLineCounts } = attachQuickLineCounts({ cwd, realFiles, softFiles, review, auditFiles, qlId })
       // D-8 落盘（2026-08-18 修）：advisory 欠账信号从「纯打印」升级为「随条目落盘」——修复
       // 「欠账已记录（QUICKLOG reasons）」的不实承诺（交叉审查实证 reasons 纯 stdout，事后不可审计）。
       // 两周实测（2026-08-31 裁决，doc-consistency-debt §七）需要分母：信号触发次数必须可追溯。
@@ -1214,6 +1237,10 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       }
       if (review?.docsCheckHint && review.docsCheckHint.invalid > 0) {
         auditNotes.push(`📎 文档引用失效：${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处 file:line 失效（sillyspec docs check 可复现）`)
+        // 逐条指名（2026-09-11 同 quick-audit 侧：门禁输出直接带文件:行号，封顶 5 保持注记紧凑）
+        for (const i of (review.docsCheckHint.invalidRefs || []).slice(0, 5)) {
+          auditNotes.push(`   ❌ [${i.doc}:${i.docLine}] ${i.ref} → ${i.reason}`)
+        }
         // 行号漂移自动重锚（2026-09-08 用户反馈②：活文档 file:line 硬编码随任何插入失效，
         // 每回手跑 docs check --fix 是机械活）：autoReanchorDocRefs = --fix 主链路编程化封装
         // （fixable 唯一/优选命中才改 + 定点替换 + 同口径回执），只作用于本次改动的文档。
@@ -1236,19 +1263,74 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       }
       // 归属切分注（2026-08-18 误归属修复）：窗口内未声明脏文件不进「文件：」行，但必须落盘可追溯
       // （多 agent 并发仓他者窗口改动 / 本会话漏声明均可能），防真实改动被静默挤走。
+      // 软归属拆分（2026-09-10）：softFiles 中的同模块测试文件已补入文件行，不再占 ⚖️「未计入」
+      // 文案（否则审计行与文件行自相矛盾），单列 🔍 行交代软归属依据与剔除指引。
       if (Array.isArray(review?.undeclaredFiles) && review.undeclaredFiles.length > 0) {
-        const undeclared = review.undeclaredFiles.filter(f => !isQuickMetadata(f, linkedChanges))
+        const softSet = new Set(softFiles)
+        const undeclared = review.undeclaredFiles.filter(f => !isQuickMetadata(f, linkedChanges) && !softSet.has(String(f).replace(/\\/g, '/')))
         if (undeclared.length > 0) {
-          auditNotes.push(`⚖️ 归属切分：${undeclared.length} 个窗口内未声明脏文件未计入文件行（并行会话改动或本会话漏声明）：${undeclared.join(', ')}`)
+          auditNotes.push(`⚖️ 归属切分：${undeclared.length} 个窗口内未声明脏文件未计入文件行（并行会话改动或本会话漏声明）：${undeclared.map(f => `${f}${fmtLineCounts(f)}`).join(', ')}`)
+        }
+        if (softFiles.length > 0) {
+          auditNotes.push(`🔍 软归属：${softFiles.length} 个窗口内未声明同模块测试文件已补入文件行（若属并行会话改动请手工剔除）：${annotatedSoftFiles.join(', ')}`)
+          console.log(`🔍 软归属：${softFiles.length} 个窗口内未声明同模块测试文件已按软归属补入文件行（若属并行会话改动请手工剔除）：${annotatedSoftFiles.join(', ')}`)
         }
       }
       await completeQuicklogEntry(specBase, gitUser, qlId, {
         resultText: outputText || '',
         linkedChanges,
-        changedFiles: realFiles,
+        changedFiles: annotatedRealFiles,
         auditNotes,
+        softFiles,
       })
       console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      // 范围快照/patch 审计级落盘（quick-359a48f1）：quicklog/patches/<qlId>.json+.patch——按
+      // ql-ID 对齐 QUICKLOG 条目（平台按条目抓取），json 冗余 sessionId 供 guard 清理后记录态
+      // 反查（computeQuickAudit → findQuickPatchRecord 同链）。patch 为 --done 时点全量冻结
+      // （HEAD 未提交窗口，untracked 自拼 hunk）。fail-soft：失败只提示，不阻断收尾。
+      try {
+        const { computeChangeScopeAudit, collectNumstatByPath, buildFrozenPatch } = await import('../scope-audit.js')
+        // changeName == sessionId（handleQuickStageCompletion 作用域内，§4.6 注释同款约定）
+        const snapResult = await computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts, collectPatch: true })
+        let quickRows = snapResult && snapResult.mode === 'quick' && Array.isArray(snapResult.rows)
+          ? snapResult.rows.filter(r => r && r.attribution !== 'undeclared')
+          : null
+        let frozenPatch = snapResult ? snapResult.frozenPatch : undefined
+        // 窗口空兜底（baseline 会话常态）：--files 声明文件是会话启动时预存脏（audit baseline
+        // 剔除后窗口空，quickRows 空），但声明即归属——改用声明文件集构造 rows + patch（行数按
+        // HEAD 未提交窗口采集，同口径）。
+        if ((!quickRows || quickRows.length === 0) && Array.isArray(guard?.allowedFiles) && guard.allowedFiles.length > 0) {
+          const sessionRoot = dirname(specBase)
+          const declaredPosix = guard.allowedFiles.map(f => String(f).replace(/\\/g, '/')).filter(Boolean)
+          const stats = collectNumstatByPath(sessionRoot, declaredPosix, { baseRef: 'HEAD' })
+          quickRows = declaredPosix.filter(f => stats.has(f) || existsSync(join(sessionRoot, f)))
+            .map(f => {
+              const st = stats.get(f) || { additions: null, deletions: null, kind: existsSync(join(sessionRoot, f)) ? 'modified' : 'deleted' }
+              return { path: f, declared: true, additions: st.additions, deletions: st.deletions, kind: st.kind, attribution: 'declared' }
+            })
+          frozenPatch = buildFrozenPatch(sessionRoot, quickRows.map(r => r.path), { baseRef: 'HEAD' })
+        }
+        if (quickRows && quickRows.length > 0) {
+          const patchesDir = join(specBase, 'quicklog', 'patches')
+          mkdirSync(patchesDir, { recursive: true })
+          const { ...snapRest } = snapResult || {}
+          delete snapRest.frozenPatch
+          writeFileSync(join(patchesDir, `${qlId}.json`), JSON.stringify({
+            ...snapRest,
+            rows: quickRows,
+            totals: { files: quickRows.length, additions: quickRows.reduce((n, r) => n + (Number.isFinite(r.additions) ? r.additions : 0), 0), deletions: quickRows.reduce((n, r) => n + (Number.isFinite(r.deletions) ? r.deletions : 0), 0) },
+            qlId,
+            sessionId: changeName,
+            savedAt: new Date().toISOString(),
+          }, null, 2) + '\n')
+          if (typeof frozenPatch === 'string' && frozenPatch) {
+            writeFileSync(join(patchesDir, `${qlId}.patch`), frozenPatch.endsWith('\n') ? frozenPatch : frozenPatch + '\n')
+          }
+          console.log(`📦 范围快照已落 quicklog/patches/${qlId}.json${typeof frozenPatch === 'string' && frozenPatch ? ' + .patch（--done 时点冻结）' : ''}`)
+        }
+      } catch (e) {
+        console.warn(`   ⚠️ quick 范围快照落盘失败（不阻断收尾）：${e && e.message ? String(e.message).split('\n')[0] : e}`)
+      }
       // 刷新 DB title：从 step3「需求：」提取（agent 可改 title 的途径），覆盖启动时的兜底快照。
       // 与 QUICKLOG 标题刷新（flipEntryInContent 内 extractTitleFromResult）同源，保持 DB↔QUICKLOG 一致。
       try {
@@ -1274,6 +1356,14 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       console.warn(`⚠️ 关联变更轻量归档失败（不阻断 quick 完成）: ${e.message}`)
     }
 
+    // 摩擦信号消费（friction-signal-hint task-04）：必须在 session 目录清理**前**——清理后
+    // tally 随目录删除，晚于此就读不到。QUICKLOG 完成打印之后 consume，提示里的 postmortem
+    // 建议有落点可循；全零/读失败零输出，摩擦提示失败不影响收尾。
+    try {
+      const fr = consumeFrictionHint({ cwd, changeName, platformOpts })
+      if (fr && fr.hint) console.log(`\n${fr.hint}`)
+    } catch { /* 摩擦提示失败不影响收尾 */ }
+
     // 清理 session 目录（rmSync/unlinkSync 容忍不存在）。路径与写入对齐（Q4 resolveQuickSessionsDir）。
     try {
       if (changeName) {
@@ -1828,3 +1918,46 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
   return null
 }
 
+// ── task-06（2026-09-10-change-scope-audit，FR-04）：quick 文件行/审计行 numstat 行数注入 ──
+// collectNumstatByPath 与 scope-audit 命令同源采集（D-003 单一真相；R-03 单次 git 调用非逐文件）。
+// 基点 'HEAD' = 未提交工作区窗口（D-004：quick 无 merge-base 锚，对未提交窗口采集语义自洽；
+// untracked 新文件 wc-l 记全 + 行、binary 显 BIN）。纯展示列（advisory，D-006）：采集失败/行数
+// 不可得 → 括注省略不出伪数据；不改 auditQuickCompletion 判定、runQuickTestLintGate 与任何门禁。
+// 放文件尾（函数声明提升）而不内联进 handleQuickStageCompletion：docs/platform-interface-map
+// 行号锚在上方（complete-handlers.js:1695 handleScanStageCompleted），内联大块会把 doc-ref 锚
+// 推出关键词窗口。
+//
+// 消费分工（调用方 quick 收尾）：
+//   - annotatedRealFiles → completeQuicklogEntry changedFiles（QUICKLOG「文件：」行/bullet 带括注；
+//     fileNotes 模式下 realFiles 本就不渲染，括注只出现在回退渲染面）
+//   - annotatedSoftFiles → 🔍 软归属审计行 + console；softFiles 传参保持**裸路径**——
+//     flipEntryInContent 用它与 fileNotes.path 精确等值去重（带括注会不等值 → 同文件双 bullet）
+//   - fmtLineCounts → ⚖️ 归属切分审计行逐文件括注（降级返回空串 → 原样不带）
+//   - 已提交降级（D-004）：窗口空（改动已 commit/会话未产生改动）且 QUICKLOG 条目已存在 →
+//     记录态提示读 QUICKLOG 条目文件行，不以空表冒充实时（与 scope-audit quick 模式 note 同口径）
+function attachQuickLineCounts({ cwd, realFiles, softFiles, review, auditFiles, qlId }) {
+  const posix = (f) => String(f).replace(/\\/g, '/')
+  const lineCountFiles = [...new Set([...(realFiles || []).map(posix), ...(softFiles || [])])]
+  let numstatByPath = new Map()
+  if (lineCountFiles.length > 0) {
+    try {
+      numstatByPath = collectNumstatByPath(cwd, lineCountFiles, { baseRef: 'HEAD' })
+    } catch { /* 采集异常 → 行数列整体降级省略（fail-soft） */ }
+  }
+  const fmtLineCounts = (f) => {
+    const st = numstatByPath.get(posix(f))
+    if (!st) return ''
+    if (st.kind === 'binary') return '（BIN）'
+    if (!Number.isFinite(st.additions) || !Number.isFinite(st.deletions)) return ''
+    return `（+${st.additions}/-${st.deletions}）`
+  }
+  const annotatedRealFiles = (realFiles || []).map(f => `${f}${fmtLineCounts(f)}`)
+  const annotatedSoftFiles = (softFiles || []).map(f => `${f}${fmtLineCounts(f)}`)
+  if (lineCountFiles.length > 0) {
+    console.log(`📊 变更行数（vs HEAD 未提交窗口）：${[...annotatedRealFiles, ...annotatedSoftFiles].join(', ')}`)
+  } else if (review && Array.isArray(auditFiles) && auditFiles.length === 0) {
+    console.log(`ℹ️ 本会话无未提交改动（窗口已提交或会话未产生改动）——实时行数不可采，文件行请读 QUICKLOG 条目 ${qlId}（记录态）`)
+  }
+  return { annotatedRealFiles, annotatedSoftFiles, fmtLineCounts }
+}
+

package/src/run/complete.js

@@ -19,6 +19,7 @@
 import { join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 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'
 
@@ -48,7 +49,6 @@ import { formatExecuteSummary } from '../worktree-apply.js'
 import { validateDecisionModuleRefs } from '../design-facts.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
 import { deriveTitleFromLinkedChange } from '../quicklog.js'
-import { gitQuiet } from '../git-helper.js'
 
 // validateMetadata / readDesignScale / validateFileLocations 已迁至 ./gates.js（completeStageGates
 // 共享收尾管线，消除 noAI 末步 / continueStep 完成分支绕过 gate 的 S1/S2/S3 不对称）。
@@ -97,6 +97,26 @@ export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
   return waitIdx
 }
 
+/**
+ * 事实性步骤摘要合成（P0-2，noai-ir-roadmap §3）：--output 省略时由 CLI 按既有事实合成
+ * ——步骤名 + 变更窗口（git porcelain 计数与前几个路径）+ 门禁以 CLI 校验输出为准。
+ * 纯事实零编造（无「通过/成功」等判断词——判断在 gate，不在摘要）；语义性说明（方案
+ * 取舍/用户反馈）不合成，摘要自带手写指引。长度控制在 MAX_OUTPUT(200) 截断线内。
+ */
+export function synthesizeStepOutput({ stageName, stepName, cwd }) {
+  let windowNote = ''
+  try {
+    const porcelain = gitQuiet(cwd, ['status', '--porcelain'])
+    if (porcelain !== null) {
+      const paths = porcelain.split('\n').filter(Boolean).map((l) => (l.slice(3) || '').trim()).filter(Boolean)
+      windowNote = paths.length === 0
+        ? '；工作区无未提交变更'
+        : `；变更窗口 ${paths.length} 文件（${paths.slice(0, 3).map((p) => p.split(/[\\/]/).pop()).join('、')}${paths.length > 3 ? ' 等' : ''}）`
+    }
+  } catch { /* git 不可读 → 窗口段缺省（摘要仍成立） */ }
+  return `【CLI 合成】步骤「${stepName}」完成${windowNote}；门禁以本次 CLI 校验输出为准（方案取舍等语义说明需 --output 手写）`
+}
+
 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
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
@@ -158,6 +178,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     currentIdx = _resolvedWaitIdx
     console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
   }
+
+  // ── P0-2（noai-ir-roadmap §3）：--output 省略 → CLI 按事实合成步骤摘要 ──
+  // agent 手打摘要是每步命中的幻觉源；事实面（步骤名 + 变更窗口 + 门禁以 CLI 校验为准）
+  // CLI 本就持有，纯事实合成零编造（判断词留给 gate）。语义性说明（方案取舍/用户反馈）仍应
+  // --output 手写——合成摘要自带该指引。quick 阶段除外（末步四字段硬契约
+  // validateQuickResult，合成文本过不了四字段校验；quick 的省略提示由其阶段文案承担）。
+  if (!outputText && stageName !== 'quick' && currentIdx !== -1 && steps[currentIdx]) {
+    outputText = synthesizeStepOutput({ stageName, stepName: steps[currentIdx].name, cwd })
+    console.log(`🤖 --output 未提供——CLI 已按事实合成步骤摘要（gate 校验照常；方案取舍等语义说明下次带 --output 手写）。`)
+  }
   // ── waiting 前置守卫（坑 archive-step3-wait-answer-hint-late）──
   // 普通 --done（无 --answer）时若存在 waiting 步骤：currentIdx 会跳过它推进后续步骤
   //（findIndex 只查 pending/in-progress），步骤被静默越过 + --answer 要求要到别处报错才暴露。
@@ -380,6 +410,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     } else if (_cliAction === 'progressConfirm') {
       // 与 stage.js noAI 分支同语义（brainstorm/execute/verify step1 进度确认）
       executeProgressConfirm({ stageName, cwd, stageData, changeName, pm })
+    } else if (_cliAction === 'verifyRunQualityScan') {
+      // 与 stage.js noAI 分支同语义（P0-1 noai-ir-roadmap §3：verify 测试步实测提前 + 指纹复用；
+      // 失败 throw → completeStep 不推进，步骤保持 pending）
+      const { executeVerifyQualityScan } = await import('./verify-quality-scan.js')
+      await executeVerifyQualityScan({ cwd, specBase, changeName, platformOpts })
+    } else if (_cliAction === 'archiveDistill') {
+      // 与 stage.js noAI 分支同语义（P0-4 安全变体：distill 提炼 CLI 机械执行，needsWait 裁决
+      // 收敛到「确认归档 --confirm」；全路径不抛）
+      const { executeArchiveDistill } = await import('./archive-distill.js')
+      await executeArchiveDistill({ cwd, specBase, changeName })
     } else if (_cliAction === 'doctorRunDiagnostics') {
       // 2026-09-09-doctor-noai：与 stage.js 分支同语义（诊断+渲染+落盘）
       const { runDoctorDiagnostics, renderDoctorSummary, writeDoctorDiagnosis } = await import('../doctor-diagnostics.js')
@@ -622,6 +662,21 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     const total = steps.length
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
 
+    // task-04（2026-09-10-change-scope-audit）：execute 完成打范围对账全表+落 .runtime 快照 /
+    // verify 完成出一行漂移确认。advisory fail-soft（D-006）——helper 内部全兜，绝不阻断完成。
+    await printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts })
+
+    // 摩擦信号消费（friction-signal-hint task-03）：verify 收尾读一次 friction tally，非零打
+    // 一行 advisory 引导补 postmortem（consume 内部提示后清零）；全零/读失败零输出——
+    // 摩擦提示失败不影响收尾。
+    if (stageName === 'verify') {
+      try {
+        const { consumeFrictionHint } = await import('../friction-tally.js')
+        const r = consumeFrictionHint({ cwd, changeName, platformOpts })
+        if (r && r.hint) console.log(`\n${r.hint}`)
+      } catch { /* 摩擦提示失败不影响收尾 */ }
+    }
+
     if (stageName === 'execute') {
       // execute run summary：展示真实可得的结构化信息
       try {
@@ -666,6 +721,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       // 走下方 _getNextSuggestion 会因 scan 是 STAGE_ORDER 首位、永未完成而误推 scan（回头路），
       // 与 brainstorm 同类问题（见上注释），故给 quick 专属分支。
       console.log('\n👉 quick 已完成。下一步：提交本次改动（git commit / sillyspec-commit），或 sillyspec run <stage> 继续其他阶段。')
+      console.log('   ⚠️ 多会话共享仓禁目录级 git add / git add -A（会夹带并行会话文件，2026-09-10 实证误删已提交文档）：用显式 pathspec（git add -- 文件…），提交前 git status 核对暂存面。')
     } else {
       // D1 暗衔接修：阶段刚完成，CLI 本就知道状态机下一步是哪个阶段（_getNextSuggestion），
       // 却只丢一句「下一步由你决定」让 agent 自己猜命令。改为按 progress 实际状态给出精确命令。
@@ -729,6 +785,106 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   return { stageCompleted: false, currentIdx, nextPendingIdx }
 }
 
+// ── 变更范围对账 advisory 注入（2026-09-10-change-scope-audit task-04，FR-03）──
+// execute 完成打全表+落快照、verify 完成出一行漂移确认；completeStep 与 continueStep（wait
+// 解除完成）两路径收敛点同调 printStageCompletionScopeAudit（Grill G-2：单锚 completeStep 会漏
+// wait 解除路径致 verify 假报无快照）。全程 fail-soft（D-006）：任何异常只打单行 ⚠️，不阻断
+// 阶段完成、不进任何门禁判定。scope-audit.js 经动态 import 接入（本文件 runtime-hygiene /
+// design-facts 等同款先例）——只读纯函数模块，模块缓存下零重复加载。
+//   - execute：renderScopeAuditTable 全表（maxRows 60 截断 + 完整表跑 scope-audit 指引 +
+//     ⚠️ 出口指引行——计划外补 design.md 声明或 --output 注明原因，均 renderer 内置）+ 落
+//     .runtime/scope-audit-<change>.json 快照（结构即 ScopeAuditResult + savedAt 落盘时间戳，
+//     只写 .runtime 运行时产物区不动 git 状态）。
+//   - verify：读快照对比文件集差集出一行「变更范围：N 文件 +X/-Y（vs execute 时点：一致|漂移
+//     M 文件：<列表截断>）」。漂移过滤面 = filterDeliverableFiles 结果（resolveReconcileActualFiles
+//     已过、本就保留 docs 子树）再排除 .sillyspec/docs/**——verify 阶段合法文档同步不计漂移
+//     （Grill C-5/P2-②：组合过滤在本侧做，不动 worktree-apply.js 过滤器本体）。快照缺失/降级 →
+//     跳过对比只打当前 totals 一行。
+
+/** 漂移对比排除面：verify 阶段合法文档同步子树（posix 归一后前缀匹配） */
+const SCOPE_DRIFT_EXCLUDE_RE = /^\.sillyspec\/docs\//
+
+/** 快照/当前结果 → 漂移对比用文件集（posix 归一 + docs 子树排除）；畸形结构防御式得空集 */
+function scopeAuditPathSet(result) {
+  const rows = Array.isArray(result?.rows) ? result.rows : []
+  const set = new Set()
+  for (const r of rows) {
+    const p = r && typeof r.path === 'string' ? r.path.replace(/\\/g, '/') : ''
+    if (p && !SCOPE_DRIFT_EXCLUDE_RE.test(p)) set.add(p)
+  }
+  return set
+}
+
+/** execute 完成路径：全表 + 审计级快照/patch 落盘（quick-359a48f1：changes/<变更名>/ 随归档
+ *  入库；patch 为收尾时点全量冻结——--file 真·当时内容比对的数据源。写失败只提示，verify
+ *  对比按无快照降级） */
+async function printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit, renderScopeAuditTable }) {
+  const result = await computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts, collectPatch: true })
+  console.log(`\n${renderScopeAuditTable(result, { maxRows: 60 })}`)
+  try {
+    const changeDir = join(specBase, 'changes', changeName)
+    mkdirSync(changeDir, { recursive: true })
+    const { frozenPatch, ...snap } = result
+    writeFileSync(join(changeDir, 'scope-audit.json'), JSON.stringify({ ...snap, savedAt: new Date().toISOString() }, null, 2) + '\n')
+    if (typeof frozenPatch === 'string') {
+      writeFileSync(join(changeDir, 'scope-audit.patch'), frozenPatch.endsWith('\n') ? frozenPatch : frozenPatch + '\n')
+    }
+    console.log(`   📦 范围快照已落变更目录（scope-audit.json${typeof frozenPatch === 'string' ? ' + scope-audit.patch（收尾时点冻结）' : ''}）`)
+  } catch (e) {
+    console.warn(`   ⚠️ 范围对账快照写入失败（不阻断，verify 漂移对比将按无快照降级）：${e && e.message ? String(e.message).split('\n')[0] : e}`)
+  }
+}
+
+/** verify 完成路径：读 execute 时点快照对比文件集差集，一行结论（行数不比——execute 形态 A 锚
+ *  worktree meta、verify 形态 B 锚 merge-base，基点不同行数天然抖动，比行数必假阳） */
+async function printVerifyScopeDrift({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit }) {
+  const result = await computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts })
+  const totals = result?.totals && typeof result.totals === 'object' ? result.totals : {}
+  const scopeLine = `变更范围：${totals.files ?? (Array.isArray(result?.rows) ? result.rows.length : 0)} 文件 +${totals.additions ?? 0}/-${totals.deletions ?? 0}`
+  if (result?.ok !== true) {
+    console.log(`   ⚠️ ${scopeLine}（对账降级：${result?.degradedReason || '实际侧文件集解析失败'}——advisory，不影响 verify 完成）`)
+    return
+  }
+  let snapshot = null
+  // 快照读取链（quick-359a48f1）：变更目录（审计级，execute --done 落）→ .runtime（存量兼容）
+  try {
+    snapshot = JSON.parse(readFileSync(join(specBase, 'changes', changeName, 'scope-audit.json'), 'utf8'))
+  } catch {
+    try {
+      snapshot = JSON.parse(readFileSync(join(resolveRuntimeRoot(platformOpts, specBase), `scope-audit-${changeName}.json`), 'utf8'))
+    } catch { /* 快照缺失/损坏 → 跳过对比只打当前 totals */ }
+  }
+  if (!snapshot || snapshot.ok !== true) {
+    console.log(`   ${scopeLine}（无 execute 时点快照可对比——完整表跑 sillyspec scope-audit --change ${changeName}）`)
+    return
+  }
+  const current = scopeAuditPathSet(result)
+  const baseline = scopeAuditPathSet(snapshot)
+  const drift = [...new Set([...current, ...baseline])].filter(p => current.has(p) !== baseline.has(p)).sort()
+  if (drift.length === 0) {
+    console.log(`   ${scopeLine}（vs execute 时点：一致）`)
+  } else {
+    const shown = drift.slice(0, 5).join(', ')
+    const tail = drift.length > 5 ? ` 等 ${drift.length} 个` : ''
+    console.log(`   ${scopeLine}（vs execute 时点：漂移 ${drift.length} 文件：${shown}${tail}——advisory 不阻断，请确认 verify 期改动并按需补 design.md 声明）`)
+  }
+}
+
+/** 两完成路径公共入口（stage 派发 + 动态 import + fail-soft 兜底，D-006） */
+async function printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts }) {
+  try {
+    if (!changeName || (stageName !== 'execute' && stageName !== 'verify')) return
+    const { computeChangeScopeAudit, renderScopeAuditTable } = await import('../scope-audit.js')
+    if (stageName === 'execute') {
+      await printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit, renderScopeAuditTable })
+    } else {
+      await printVerifyScopeDrift({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit })
+    }
+  } catch (e) {
+    console.warn(`⚠️ 变更范围对账输出异常（advisory，不阻断 ${stageName} 阶段完成）：${e && e.message ? String(e.message).split('\n')[0] : e}`)
+  }
+}
+
 // ── Step 调度兄弟函数（W6 Step7b-2 从 run.js 搬入：skip/wait/continue + formatWaitHistory）──
 /**
  * plan.md checkbox 自动勾选：execute 完成 + 各 task review.json 双 verdict 非 fail → 自动勾选。
@@ -858,7 +1014,7 @@ export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
 
   return true
 }
-async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
+export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
   if (stageName !== 'execute' || !changeName) {
     return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
   }
@@ -1337,6 +1493,18 @@ 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} 步）`)
+    // task-04：wait 解除完成路径与 completeStep 完成分支同源注入（Grill G-2：本路径不漏，
+    // 否则 execute 快照缺失 → verify 假报「无快照可对比」）。
+    await printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts })
+    // 摩擦信号消费（friction-signal-hint task-03）：与 completeStep 完成分支同款（Grill CC-03：
+    // 漏此则 --continue 收尾丢提示丢清零）。全零/读失败零输出，摩擦提示失败不影响收尾。
+    if (stageName === 'verify') {
+      try {
+        const { consumeFrictionHint } = await import('../friction-tally.js')
+        const r = consumeFrictionHint({ cwd, changeName, platformOpts })
+        if (r && r.hint) console.log(`\n${r.hint}`)
+      } catch { /* 摩擦提示失败不影响收尾 */ }
+    }
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {

package/src/run/gate-snapshot.js

@@ -0,0 +1,159 @@
+/**
+ * gate-snapshot.js — quick --done test+lint 门禁的隔离快照执行（2026-09-10 驾驭小结第六批②，
+ * 用户实证「lint 实测对账在主仓跑，被并行会话的脏文件拦门」）。
+ *
+ * 问题：门禁在主仓工作区跑 commands.test/lint——多会话共享仓里并行会话的未提交 src/test
+ * 改动（语法错误/半成品/锚漂）会污染实测结果，把无辜会话的 --done 拦在门上（只能走
+ * advisory 逃生口）。
+ *
+ * 修法：HEAD 干净快照 + 会话文件 overlay——`git worktree add --detach <tmp> HEAD` 取干净
+ * 基线（并行脏文件天然不在），把本会话审计/声明的变更文件覆盖进快照，node_modules 经
+ * junction 复用主仓依赖（零拷贝），local.yaml 从主仓复制（gitignore 不进 HEAD），在快照
+ * cwd 跑对账。快照基建任何失败 → 返回 null，调用方回退主仓现行为（零回归兜底）。
+ *
+ * 快照生命周期：一次门禁一批（create → run → cleanup）；崩溃残留由 git worktree prune /
+ * 临时目录自然回收（OS tmp 清理），不进主仓 .runtime。
+ */
+import { execFileSync } 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'
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000 }).trim()
+}
+
+/**
+ * 创建隔离快照：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 }) {
+  let snapshotRoot = null
+  try {
+    // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
+    git(cwd, ['rev-parse', 'HEAD'])
+
+    snapshotRoot = mkdtempSync(join(tmpdir(), 'sillyspec-gate-'))
+    git(cwd, ['worktree', 'add', '--detach', '--quiet', snapshotRoot, 'HEAD'])
+
+    // 会话文件 overlay：主仓工作区版本覆盖进快照（本会话的最新态；文件不存在=已删，跳过）。
+    // sourceRoot（verify 门定向跑用，2026-09-10 驾驭小结第八批）：overlay 源切换为本变更
+    // worktree 根——「--worktree 定向跑本变更分支内容」的快照实现（缺省仍是主仓 cwd）。
+    // .sillyspec/ 跳过面收窄（P2-d 落地实证的快照盲区）：原一刀切跳过整个 .sillyspec/ ——
+    // 会话声明的 tracked docs（module-map 补录/知识库/模块卡）进不了快照，门禁读到 HEAD
+    // 旧版恒误报（src 未录 module-map 的修复在主仓生效、快照里仍然失败）。真正需要隔离的
+    // 是共享运行时面：.runtime/（sqlite 锁/在途 marker）与 quicklog/（跨会话共享账本）；
+    // local.yaml 由下方 cfg 段显式复制（单一来源，不经 overlay）。
+    const overlayRoot = sourceRoot || cwd
+    let overlaid = 0
+    for (const f of files) {
+      const isSillyspecRuntime = typeof f === 'string' && (f.startsWith('.sillyspec/.runtime/') || f.startsWith('.sillyspec/quicklog/') || f === '.sillyspec/local.yaml' || f === '.sillyspec/.sillyspec-platform.json')
+      if (typeof f !== 'string' || f.includes('..') || f.startsWith('/') || isSillyspecRuntime) continue
+      const src = join(overlayRoot, f)
+      if (!existsSync(src)) continue
+      const dst = join(snapshotRoot, f)
+      mkdirSync(dirname(dst), { recursive: true })
+      copyFileSync(src, dst)
+      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 */ }
+    }
+
+    // local.yaml（gitignore 不进 HEAD；门禁命令配置来源）+ package-lock 保持 HEAD 版（npm test 不装新依赖）
+    for (const cfg of [join('.sillyspec', 'local.yaml')]) {
+      const src = join(cwd, cfg)
+      if (existsSync(src)) {
+        mkdirSync(dirname(join(snapshotRoot, cfg)), { recursive: true })
+        copyFileSync(src, join(snapshotRoot, cfg))
+      }
+    }
+
+    const cleanup = () => {
+      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {
+        try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch { /* 残留交 OS tmp 清理 */ }
+      }
+    }
+    return { snapshotRoot, cleanup, overlaid }
+  } catch (e) {
+    // 基建失败（worktree add 拒绝/磁盘满/…）：尽力清理后回退主仓
+    if (snapshotRoot) {
+      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {}
+      try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch {}
+    }
+    return null
+  }
+}
+
+/**
+ * verify 门专用快照（2026-09-10 驾驭小结第八批，用户第二次真实阻塞：verify 实测门跑
+ * main 工作区，多会话并发任何人的 WIP 都能弄红别人的门）。等价「--worktree 定向跑」：
+ * overlay 文件集 = resolveVerifyChangedFiles（worktree-aware：含 merge-base 补齐与
+ * working-tree），overlay 源 = 本变更 worktree 根（meta 感知；in-place 退主仓 cwd）——
+ * 并行会话的在途文件物理不进快照。变更文档（changes/<name>/**，test_strategy 的
+ * module-impact.md 等消费）从主仓 specBase 随快照复制。
+ * @param {{ cwd: string, changeName: string, specBase: string, platformOpts?: object }} opts
+ * @returns {Promise<{snapshotRoot: string, cleanup: () => void, overlaid: number, changeFileCount: number}|null>}
+ */
+export async function createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts = {} }) {
+  try {
+    const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
+    const { resolveRuntimeRoot } = await import('./shared.js')
+    const { splitOwnVsForeignDiffFiles } = await import('../foreign-declared.js')
+    let changeFiles = resolveVerifyChangedFiles(cwd, changeName, null, {
+      specBase, includeWorkingTree: true,
+    }) || []
+    if (changeFiles.length === 0) return null // 无变更文件集 → 无从定向，回退主仓
+    // 他者声明归属过滤（坑 verify-reconcile-foreign-wip 同款）：in-place 模式 working-tree
+    // 并入后主仓全部在途文件进场——他者活跃变更显式声明的文件（quick --files / 他者 design
+    // 清单）剔除，只留本变更相关面（无主文件保留，fail-closed 口径与 probe6 一致）。
+    try {
+      const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+      const { foreign } = splitOwnVsForeignDiffFiles(cwd, changeName, changeFiles, { specBase, runtimeRoot })
+      if (foreign.length > 0) {
+        const foreignSet = new Set(foreign.map(x => x.file))
+        changeFiles = changeFiles.filter(f => !foreignSet.has(f))
+        if (changeFiles.length === 0) return null
+      }
+    } catch { /* 过滤失败退全量（fail-closed：宁可多 overlay 不漏本变更文件） */ }
+
+    // overlay 源：worktree meta 感知（native worktree 在则从 worktree 根取「本变更分支内容」）
+    let sourceRoot = null
+    try {
+      const { WorktreeManager } = await import('../worktree.js')
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (meta && meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
+        sourceRoot = meta.worktreePath
+      }
+    } catch { /* meta 读取失败 → 主仓 cwd 源（files 已含本变更 working-tree 改动） */ }
+
+    const snap = createGateSnapshot({ cwd, files: changeFiles, sourceRoot })
+    if (!snap) return null
+
+    // 变更文档随快照：module-impact.md（test_strategy=evidence-auto 消费）/tasks.md 等
+    // 在 .sillyspec（gitignore）不进 HEAD，从主仓 specBase 复制 changes/<name>/**
+    try {
+      const changeDir = join(specBase, 'changes', changeName)
+      if (existsSync(changeDir)) {
+        const copyDir = (srcDir, dstDir) => {
+          for (const e of readdirSync(srcDir, { withFileTypes: true })) {
+            const s = join(srcDir, e.name); const d = join(dstDir, e.name)
+            if (e.isDirectory()) { mkdirSync(d, { recursive: true }); copyDir(s, d) }
+            else { mkdirSync(dirname(d), { recursive: true }); copyFileSync(s, d) }
+          }
+        }
+        copyDir(changeDir, join(snap.snapshotRoot, '.sillyspec', 'changes', changeName))
+      }
+    } catch { /* 文档复制失败不连坐快照（test_strategy 降级 module 集仍可跑） */ }
+
+    return { ...snap, changeFileCount: changeFiles.length, sourceRoot }
+  } catch {
+    return null // 任一链路异常 → 回退主仓现行为
+  }
+}