sillyspec 3.28.7 → 3.28.9

package/src/run/shared.js

@@ -20,6 +20,9 @@ import os from 'node:os'
 // unquoteGitPath 同理：parsePorcelainPath 内部消费 + re-export。
 import { safeGit, unquoteGitPath } from '../git-helper.js'
 import { createHash } from 'node:crypto'
+// 分级门禁画像信号层（2026-09-14-quick-exit-tiered-gates task-01 / FR-02）：纯函数零 IO，
+// 仅依赖 change-risk-profile，无环——auditQuickCompletion 静态 import 安全（task-02 接线）。
+import { computeGateProfile, resolveGateThresholds } from '../quick-gate-profile.js'
 export { safeGit, unquoteGitPath }
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -299,7 +302,7 @@ export function detectWorktreeSpecDrift(specBase) {
   const seg = resolve(specBase).split(sep)
   // specBase 恒以 .sillyspec 结尾(command.js specBase=join(cwd,'.sillyspec'))。worktree 副本形如
   // <mainRepo>/.sillyspec/.runtime/worktrees/<change>/.sillyspec —— 尾段也须是 .sillyspec,
-  // 否则 worktree 根目录本身(<.../worktrees/<change>)会被误判(它不是 spec,不会作 specBase 传入)。
+  // 否则 worktree 根目录本身(<.../worktrees/<change>>)会被误判(它不是 spec,不会作 specBase 传入)。
   if (seg[seg.length - 1] !== '.sillyspec') return null
   for (let i = 0; i + 3 < seg.length; i++) {
     if (seg[i] === '.sillyspec' && seg[i + 1] === '.runtime' && seg[i + 2] === 'worktrees') {
@@ -317,6 +320,33 @@ export function detectWorktreeSpecDrift(specBase) {
   return null
 }
 
+/**
+ * 判定「目录在 sillyspec 管理的隔离 worktree 内」（坑 worktree-cwd-silent-split，2026-08-29 用户实证：
+ * Bash cwd 残留两次误在 worktree 内跑 sillyspec——第一次走 status 类命令完全静默，进度险些写进
+ * worktree 副本 .sillyspec 与主仓进度库分裂）。
+ *
+ * 与 detectWorktreeSpecDrift 的分工：那边判 specBase（恒以 .sillyspec 结尾，runCommand 内自动
+ * 锚定用，只覆盖 plan/execute/verify/archive 四 stage）；这边判任意目录（CLI 入口硬拦用，目录
+ * 可以是 worktree 根或其任意子目录，无尾段要求）。
+ *
+ * @param {string} dir 目标目录（通常为 process.cwd() 或 --dir 显式值）
+ * @returns {{ changeName: string, mainRepoRoot: string, worktreeRoot: string } | null} null=不在 worktree 内
+ */
+export function detectCwdInsideWorktree(dir) {
+  if (!dir) return null
+  const seg = resolve(dir).split(sep)
+  for (let i = 0; i + 3 < seg.length; i++) {
+    if (seg[i] === '.sillyspec' && seg[i + 1] === '.runtime' && seg[i + 2] === 'worktrees' && seg[i + 3]) {
+      return {
+        changeName: seg[i + 3],
+        mainRepoRoot: seg.slice(0, i).join(sep),
+        worktreeRoot: seg.slice(0, i + 4).join(sep),
+      }
+    }
+  }
+  return null
+}
+
 /**
  * 统一解析 .runtime 根目录（坑 execute-runs-isolation）。
  *
@@ -791,14 +821,15 @@ export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {})
  * 与 triggerSync 同款契约：quick 会话降级跳过（无 progress 实体）、未连接平台在
  * sync() 内部静默跳过、8s 总熔断（raceWithAbort + abort 在飞请求）、失败只 warn 不抛。
  *
- * 接线说明（本变更 allowed_paths 约束）：步骤 prompt 渲染点（run/stage.js outputStep
- * 前段 / run/prompt.js）不在本变更可改文件集内——本导出即「步骤开始钩子」本体，
- * 渲染侧一行 `triggerStepStartSync(cwd, changeName, platformOpts)` 的接线由后续
- * 变更补上；execute 阶段的任务粒度信号已由 X4（stages/execute.js Wave prompt
+ * 接线说明：已接线——run/prompt.js outputStep 步骤渲染前段 fire-and-forget 调用本钩子
+ * （task-13 当时 allowed_paths 不含渲染层，遗留活跃坑由 2026-08-29 docs/sillyspec
+ * 定期收口补上）；execute 阶段的任务粒度信号另由 X4（stages/execute.js Wave prompt
  * 每任务上报指引）覆盖。
  */
 export async function triggerStepStartSync(cwd, changeName, platformOpts = {}, opts = {}) {
   try {
+    // 无 changeName（渲染层个别路径/测试 fixture）直接静默——sync(null) 只会打 warn 噪音
+    if (!changeName) return
     const tsSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
     if (changeName && QUICK_SID_RE.test(changeName) && !existsSync(join(tsSpecBase, 'changes', changeName))) {
       return // quick 会话无 progress 实体（与 triggerSync 同判），无步骤可报
@@ -948,16 +979,20 @@ export function warnApprovalUnknown(cwd, changeName, reason) {
 /**
  * 审批检查：execute 阶段启动前检查（W6 Step8a 从 run.js 搬入，runStage + runAutoMode 共用）。
  * 平台模式走自己的链路，跳过；否则 await import sync.js。
+ * 返回语义：null = 平台模式有意跳过；{status:'unknown'} = 检查链路意外失败——调用方走
+ * warnApprovalUnknown 横幅 + approval-unknown.log 留痕（HUB-07）。异常折叠成 null 会绕过
+ * unknown 留痕静默放行（2026-09-11 审查）。
  * @returns {{ status: string, reason?: string } | null}
- */export async function checkApproval(cwd, changeName, platformOpts = {}) {
+ */export async function checkApproval(cwd, changeName, platformOpts = {}, { loadSyncMod = null } = {}) {
   // 平台模式不需要 CLI 内置审批检查；自指回环（repo-native junction）按本地模式处理
   if (isPlatformMode(platformOpts, cwd)) return null
+  const load = loadSyncMod || (() => import('../sync.js'))
   try {
-    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
-    const syncMod = await import('../sync.js')
+    // shared.js 在 src/run/，sync.js 在 src/ → 退一层；loadSyncMod 为测试缝（注入抛错验证 unknown 路由）
+    const syncMod = await load()
     return await syncMod.checkApproval(changeName, cwd)
   } catch (e) {
-    return null
+    return { status: 'unknown', reason: `审批检查异常: ${e?.message || e}` }
   }
 }
 
@@ -1119,7 +1154,7 @@ export function matchSameModuleTestFiles(declaredFiles, undeclaredFiles) {
 
 /**
  * quick 完成审计：对比 baseline 与实际变更。
- * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number, attributedFiles: string[], undeclaredFiles: string[], softTestFiles: string[], foreignSessionDeclared: Array<{file: string, sessions: string[]}> }}
+ * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number, attributedFiles: string[], undeclaredFiles: string[], softTestFiles: string[], foreignSessionDeclared: Array<{file: string, sessions: string[]}>, gateProfile: object|null }}
  */
 /**
  * D-8 O-1 模块归属（2026-08-15 docs-signals-o12）：quick 欠账 hint 从"改了 N 文件"升级为
@@ -1131,13 +1166,8 @@ export function matchSameModuleTestFiles(declaredFiles, undeclaredFiles) {
 async function matchQuickModules(srcChanged, specBase, projectName) {
   if (!specBase || !projectName || srcChanged.length === 0) return []
   try {
-    const { join } = await import('node:path')
-    const { existsSync: ex, readFileSync: rf } = await import('node:fs')
-    const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
-    if (!ex(mapPath)) return []
-    const { parseModuleMapSimple } = await import('../modules.js')
-    const idx = parseModuleMapSimple(rf(mapPath, 'utf8'))
-    if (!idx || Object.keys(idx).length === 0) return []
+    const idx = await loadQuickModuleIndex(specBase, projectName)
+    if (!idx) return []
     const { matchFilesToModules } = await import('../docs-debt.js')
     const cardsDir = join(specBase, 'docs', projectName, 'modules')
     const { byModule } = matchFilesToModules(srcChanged, idx, { cardsDir })
@@ -1147,6 +1177,30 @@ async function matchQuickModules(srcChanged, specBase, projectName) {
   }
 }
 
+/**
+ * quick 审计链的 _module-map.yaml 原始索引加载（2026-09-14-quick-exit-tiered-gates task-02 抽取）：
+ * D-8 模块归属（matchQuickModules）与门禁画像（auditQuickCompletion 挂 review.gateProfile）的
+ * 同源单一加载点——路径 <specBase>/docs/<projectName>/modules/_module-map.yaml，解析
+ * parseModuleMapSimple（canonical）。缺失/解析空/specBase 缺参/异常 → null（画像走 degraded
+ * 降级档：span 退出判级，兼容策略第 1 条——未 scan/无 module-map 的存量项目零强制变化）。
+ * join/existsSync/readFileSync 用本模块顶部静态 import（auditQuickCompletion 既有同款）。
+ * @param {string} specBase .sillyspec 目录（guard 透传）
+ * @param {string} projectName 项目名（progress.project）
+ * @returns {Promise<object|null>} 模块索引（扁平 { id: {...} }）；不可得 → null
+ */
+async function loadQuickModuleIndex(specBase, projectName) {
+  if (!specBase || !projectName) return null
+  try {
+    const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
+    if (!existsSync(mapPath)) return null
+    const { parseModuleMapSimple } = await import('../modules.js')
+    const idx = parseModuleMapSimple(readFileSync(mapPath, 'utf8'))
+    return idx && Object.keys(idx).length > 0 ? idx : null
+  } catch {
+    return null
+  }
+}
+
 // ── task-03（2026-08-16-state-split-fixes）: 活文档漂移提示辅助 ──
 // 背景：platform-interface-map.md 等活文档持续维护 src 主入口的 file:line 映射；并行会话改
 // src/ 后引用行号静默失效，docs gate 只能事后拦到别人的流程上。审计（auditQuickCompletion）
@@ -1225,11 +1279,14 @@ export function matchInvalidRefsToChanged(invalidRefs, srcChangedFiles) {
 
 export async function auditQuickCompletion(cwd, guard, options = {}) {
   const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false, allowDelete = false, specBase = null, projectName = null } = guard
-  const { isConfirm } = options
+  // noDocs/fileNotes（task-02）：--no-docs 显式豁免与 --file-notes 解析结果经 options 进审计链
+  // （command.js knownFlags 登记 → complete.js → complete-handlers 透传；scope-audit 重放不传 →
+  // noDocs/fileNotes 缺省的纯默认画像）。
+  const { isConfirm, noDocs = false, fileNotes = null } = options
   // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
   // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
   // 避免叠加 quick 会话时把前序会话未提交文件误读为「本会话只动了 N 个」。
-  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0, attributedFiles: [], undeclaredFiles: [], softTestFiles: [], foreignSessionDeclared: [] }
+  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0, attributedFiles: [], undeclaredFiles: [], softTestFiles: [], foreignSessionDeclared: [], gateProfile: null }
 
   try {
     // safeGit 带 -c safe.directory，避免 linked worktree/容器异 uid/挂载点下裸 `git status` 抛错被
@@ -1249,6 +1306,23 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 不对整段 .trim()：会削首行前导空格致首文件路径丢首字符（见 parsePorcelainPath 注释）。
     const currentEntries = gitStatus.split('\n').filter(Boolean)
 
+    // EOL-only 噪声过滤（坑 eol-rewrite-fake-mtime-noise，2026-09-12 驾驭第十六批②，用户实证
+    // gen:types 重写行尾制造假 M）：git diff --ignore-cr-at-eol HEAD 的变更名单是「真实内容变更」
+    // 集——tracked 修改出现在 porcelain 但不在此集 = 纯行尾重写。单次对照调用，剔出 changedFiles
+    // 归 eolOnlyFiles 软警告（.gitattributes 指引），不再计入文件行/触发各门。
+    // 注意：gitQuiet 不在本模块 import 面（safeGit 才是）——首版用 gitQuiet 触发
+    // ReferenceError 被 catch 吞成 null，又被 new Set(null) 包装成空集 → 全部 tracked 修改
+    // 被误判 EOL-only 剔除（audit-quick-completion 回归抓出）。改用 safeGit（已 import，
+    // 返回 {value,error}），失败显式落 null 透传不过滤。
+    const eolRawList = (() => {
+      try {
+        const res = safeGit(cwd, ['diff', '--name-only', '--ignore-cr-at-eol', 'HEAD'], { timeout: 30000 })
+        if (!res || res.error) return null
+        return String(res.value || '').split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/'))
+      } catch { return null }
+    })()
+    const eolRealChanged = eolRawList === null ? null : new Set(eolRawList)
+
     const normalizeGitPath = (p) => p.replace(/\\/g, '/')
     // step1 启动时记录的全量脏文件 = 预存改动（非本次 quick 产生）。审计必须排除它们，
     // 否则脏工作区下预存文件持续留在 git status → 命中 baselineFiles → 误判「覆盖 baseline」
@@ -1321,6 +1395,14 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
         continue
       }
 
+      // EOL-only（坑 eol-rewrite-fake-mtime-noise）：tracked 修改但真实内容零变化（仅行尾重写）
+      // → 剔出审计归属（changedFiles/各门），归 eolOnlyFiles 软警告。untracked（??）不经此径。
+      if (eolRealChanged instanceof Set && status !== '??' && rawStatus[0] !== 'D' && rawStatus[1] !== 'D'
+        && !eolRealChanged.has(file)) {
+        result.eolOnlyFiles = result.eolOnlyFiles || []
+        result.eolOnlyFiles.push(file)
+        continue
+      }
       result.changedFiles.push(file)
       if (rawStatus[0] === 'D' || rawStatus[1] === 'D') result.deletedFiles.push(file)
       if (status === '??') result.newFiles.push(file)
@@ -1357,8 +1439,28 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     }
 
     // 检查 deleted files（--allow-delete 显式放行：删除是破坏性操作，默认 fail-closed，flag 即知情 opt-in）
+    // spec 共享面降级（坑 foreign-spec-churn-fail-closed，2026-09-12 驾驭第十六批①，用户实证
+    // 并行会话归档移动 docs/sillyspec + changes/ 被拦只能 --allow-delete）：.sillyspec/ 与 docs/
+    // 是多会话共享 spec 面——非本会话声明的删除在此面发生时，归因「并行他者 spec 收尾/归档移动」
+    // 降级软警告不阻断（src/test 交付面删除仍 fail-closed——那是本会话可支配域）。
+    const isSpecSharedPath = (p) => {
+      const n = p.replace(/\\/g, '/')
+      return n.startsWith('.sillyspec/') || n.startsWith('docs/')
+    }
     if (!allowDelete) {
+      const stillBlocked = []
       for (const f of result.deletedFiles) {
+        if (isSpecSharedPath(f) && !ownDeclaredNorm.has(f.replace(/\\/g, '/'))) {
+          result.foreignSpecChurn = result.foreignSpecChurn || []
+          result.foreignSpecChurn.push(f)
+          continue
+        }
+        stillBlocked.push(f)
+      }
+      // 整栈退（对齐 linkedChangeLeftovers 模式）：归他者的 spec 面删除从 deletedFiles 移除——
+      // 下方 status 判定与 --allow-delete 渲染均不再见它（否则 blocked-with-empty-reasons）
+      result.deletedFiles = stillBlocked
+      for (const f of stillBlocked) {
         result.reasons.push(`删除文件: ${f}`)
       }
     }
@@ -1374,7 +1476,18 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     if (!allowNew) {
       for (const f of result.newFiles) {
         if (!isQuickMetadata(f, guard.linkedChanges)) {
-          result.reasons.push(`新增文件（需 --allow-new）: ${f}`)
+          // mtime 归因（坑 foreign-spec-churn-fail-closed 配套，用户建议「按 quick 启动后
+          // mtime 软判定」）：早于会话启动 = 预存残留（baseline 漏记或并行会话预存，非本
+          // 会话窗口新建）——reason 标注供裁决，门语义不变（新增本就 warning 档）。
+          let mtimeNote = ''
+          try {
+            const st = statSync(join(cwd, f))
+            const startedAtMs = guard.startedAt ? new Date(guard.startedAt).getTime() : 0
+            if (startedAtMs && st.mtimeMs < startedAtMs) {
+              mtimeNote = '（mtime 早于会话启动——预存残留/并行预存，非本会话新建；--files 声明归属或忽略）'
+            }
+          } catch { /* stat 失败无注记 */ }
+          result.reasons.push(`新增文件（需 --allow-new）: ${f}${mtimeNote}`)
         }
       }
     }
@@ -1551,6 +1664,47 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       result.softTestFiles = []
     }
 
+    // ── 分级门禁画像（FR-03，2026-09-14-quick-exit-tiered-gates task-02）：照 docSyncHint 先例
+    // 挂 review.gateProfile（audit result 即 printQuickAuditReview 的 review / progress.lastQuickReview
+    // / scope-audit 重放的 audit），全部 advisory——不改 status 三态 / reasons / exit code（D-003），
+    // fail-open：任何异常只跳过（内层 try/catch，绝不落外层 catch 的 warning 语义）。
+    // 输入纪律：
+    //   - changedFiles = 本函数已算的 git 事实窗口（非 --files 自声明）；先经 isQuicklogFileLineNoise
+    //     滤会话簿记（quicklog/.runtime/_module-map 等）但保留模块卡与 changelog sidecar——模块卡恰是
+    //     L2 docClaim 的认领对象，用 isQuickMetadata 会把 claimed 判死成 missing（记录面谓词分叉）；
+    //   - moduleIndex 复用 matchQuickModules 同源加载（loadQuickModuleIndex，单点）；
+    //   - 阈值经 resolveGateThresholds 合并 local.yaml quick-gate 段覆写（读取走 readLocalYamlRaw +
+    //     js-yaml 动态 import，与 resolveLivingDocs 同款链路；未配置/坏 YAML → 纯默认，D-009）；
+    //   - noDocs/fileNotes 由 options 透传（--no-docs 豁免 / --file-notes 覆盖率）。
+    // 不加 git 子进程（约束：画像纯字符串运算，R-04）；未声明脏文件维持上方归属分流不并入
+    // docClaim 判定（D-005）——级判（span/files/risk）仍用 git 事实全窗口（防 37.1% 未声明面
+    // 漏判级），docClaim 单独用归属口径重算覆盖（他者窗口内改模块卡不得伪造成「已认领」）。
+    try {
+      let thresholds = null
+      const rawLocalYaml = readLocalYamlRaw(cwd)
+      if (rawLocalYaml) {
+        try {
+          const mod = await import('js-yaml')
+          const yamlLoad = mod.load || mod.default?.load
+          const cfg = yamlLoad(rawLocalYaml)
+          if (cfg && typeof cfg === 'object') thresholds = resolveGateThresholds(cfg)
+        } catch { /* 坏 YAML → 纯默认阈值 */ }
+      }
+      const gateFiles = result.changedFiles.filter(f => !isQuicklogFileLineNoise(f, guard.linkedChanges))
+      const gateOpts = {
+        ...(thresholds ? { thresholds } : {}),
+        ...(noDocs ? { noDocs: true } : {}),
+        ...(Array.isArray(fileNotes) && fileNotes.length > 0 ? { fileNotes } : {}),
+      }
+      const moduleIndex = await loadQuickModuleIndex(specBase, projectName)
+      result.gateProfile = computeGateProfile(gateFiles, moduleIndex, gateOpts)
+      if (result.undeclaredFiles.length > 0) {
+        const undeclaredNorm = new Set(result.undeclaredFiles.map(f => String(f).replace(/\\/g, '/')))
+        const attrGateFiles = gateFiles.filter(f => !undeclaredNorm.has(String(f).replace(/\\/g, '/')))
+        result.gateProfile.checks.docClaim = computeGateProfile(attrGateFiles, moduleIndex, gateOpts).checks.docClaim
+      }
+    } catch { /* 画像 fail-open：异常只跳过（gateProfile 保持 null，D-003 不碰 status） */ }
+
     // --confirm 模式：展示 diff 并等待确认
     if (isConfirm && (result.status === 'warning' || result.status === 'blocked')) {
       console.log(`\n📋 quick 变更概览：`)

package/src/run/stage.js

@@ -440,6 +440,9 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
           description: quickDesc,
           linkedChanges,
           allowedFiles,
+          // 他者会话 guard 预留让位（坑 ql-id-double-occupancy）：与 guard 落盘同源目录
+          // （Q4 单一解析，平台模式 runtimeRoot 分裂时也对齐）
+          sessionsDir: resolveQuickSessionsDir(platformOpts, specBase),
         })
         progress.quickGuard = {
           sessionId: changeName,
@@ -461,6 +464,9 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
           allowDelete,
           forceBaseline,
           linkedChanges,
+          // 机器自动关联溯源（坑 quick-single-change-auto-link）：--done 归档闸对仅被自动
+          // 关联（信号命中猜测，非 --linked-changes 显式协作声明）的变更不触发轻量归档
+          linkedChangesAuto: Array.isArray(quickOpts?.linkedChangesAuto) ? quickOpts.linkedChangesAuto : [],
           quicklogId: qlId,
           // 刀①（2026-09-08）：启动 --input 的任务描述落 guard——prompt.js 渲染 step1 时据此做
           // 模块上下文关键词匹配（changeName 是 quick-<hash> 无语义，step.prompt 全文噪音大）

package/src/run/verify-quality-scan.js

@@ -276,7 +276,7 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
       const { createVerifyGateSnapshot } = await import('./gate-snapshot.js')
       snap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts })
       if (snap) {
-        console.log(`🧪 noAI 扫描隔离快照：HEAD + 本变更 ${snap.changeFileCount} 个文件${snap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与判定）`)
+        console.log(`🧪 noAI 扫描隔离快照（根：${snap.snapshotRoot}）：HEAD + 本变更 ${snap.changeFileCount} 个文件${snap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与判定）`)
       }
     } catch { /* 快照链路异常 → 主仓现行为 */ }
   }
@@ -292,7 +292,14 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
   try {
     testCheck = runVerifyTestCheck({ cwd: gateCwd, specBase: gateSpecBase, changeName })
     printVerifyTestCheck(testCheck)
-    lintCheck = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase })
+    lintCheck = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: snap ? 5 * 60 * 1000 : undefined })
+    // 快照 lint 超时回退主仓（2026-09-12 dogfood 两连实证：junction I/O 病态慢，3min/5min 均被
+    // 超时杀——主仓 60~110s 正常。按用户建议「自动回退」而非假败/advisory：主仓复跑保硬门，
+    // 并行噪声混入时失败输出带归属鉴定提示）
+    if (snap && lintCheck.status === 'failed' && /超时/.test(String(lintCheck.reason || ''))) {
+      console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
+      lintCheck = runVerifyLintCheck({ cwd, specBase })
+    }
   if (lintCheck.status !== 'skipped') {
     console.log(`\n⏳ noAI 质量扫描：CLI 亲自实测 commands.lint…`)
   }
@@ -315,9 +322,13 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
   // lint 失败（SILLYSPEC_VERIFY_LINT_GATE=advisory 时不 throw）同样是摩擦信号，计数不应随
   // 逃生阀漂移。recordFrictionEvent 自带静默降级，不影响本步推进/throw 语义。
   if (testFailed || lintCheck.status === 'failed') {
-    recordFrictionEvent({ cwd, changeName, platformOpts, type: 'verify_run_failed', detail: testFailed ? 'test' : 'lint' })
+    await recordFrictionEvent({ cwd, changeName, platformOpts, type: 'verify_run_failed', detail: testFailed ? 'test' : 'lint' })
   }
   if (testFailed || lintBlocked) {
+    if (snap) {
+      try { const { printSnapshotFailureHint } = await import('./gate-snapshot.js')
+        printSnapshotFailureHint(snap) } catch { /* 提示失败不影响阻断 */ }
+    }
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
     await renderVerifyTestAttribution({ cwd, changeName, specBase, runtimeRoot })
     const which = testFailed ? '测试' : 'lint'

package/src/scan-diff.js

@@ -60,7 +60,7 @@ export function computeScanDiff({ projectRoot, specBase, projectName, base } = {
 
   // ── 基线：缺省读 specBase/docs/<projectName>/scan/*.md frontmatter 的 source_commit ──
   if (!base) {
-    const sourceCommit = readSourceCommit(specBase, projectName)
+    const sourceCommit = readSourceCommit(specBase, projectName, projectRoot)
     if (!sourceCommit) {
       return {
         ok: false, error:
@@ -169,34 +169,20 @@ export function computeScanDiff({ projectRoot, specBase, projectName, base } = {
   // 变更集取 parseNameStatus 全量——**不经 module-map scope 过滤**（引用自带范围：指向「已变更
   // 但范围外」文件的引用同样过时，advisory 信号不该被 scope 吞掉）；rename 的旧路径也入集
   //（文档写在 scan 时点，引用的是旧路径，重命名后引用必失效——最强失效信号）。
+  // 命中逻辑抽为导出 collectStaleRefs（2026-09-14-scan-incremental-refresh D-003@v2：scan-refresh
+  // 复用同一单源，防 A/D/M/R 标注与 src/ 前缀归一规则双源漂移）。
   // best-effort（读不到文档/异常 → 空清单不阻断文件级结果），不计入 driftCount / 退出码
   //（advisory：引用指向已变更文件 ≠ 引用失效，提示人工核对）。──
   const staleRefs = []
   try {
     const scanDir = join(specBase, 'docs', projectName, 'scan')
-    if (existsSync(scanDir)) {
-      const fullChanged = new Map() // POSIX path → A/D/M/R
-      for (const item of parseNameStatus(diffRes.value)) {
-        if (item.status === 'A' || item.status === 'D') fullChanged.set(item.path, item.status)
-        else if (item.status === 'M' || item.status === 'C') fullChanged.set(item.path, 'M')
-        else if (item.status === 'R') { fullChanged.set(item.path, 'R'); fullChanged.set(item.oldPath, 'R') }
-      }
-      const hitChange = (p) => {
-        if (fullChanged.has(p)) return { file: p, change: fullChanged.get(p) }
-        // src/ 前缀双向归一：文档 src 相对写法 ↔ git 仓库根路径
-        const alt = p.startsWith('src/') ? p.slice(4) : `src/${p}`
-        return fullChanged.has(alt) ? { file: alt, change: fullChanged.get(alt) } : null
-      }
-      for (const f of readdirSync(scanDir)) {
-        if (!f.endsWith('.md')) continue
-        const content = readFileSync(join(scanDir, f), 'utf8')
-        for (const ref of collectDocRefs(content)) {
-          if (ref.repo !== null) continue
-          const hit = hitChange(ref.file.replace(/\\/g, '/'))
-          if (hit) staleRefs.push({ doc: f, ref: ref.ref, change: hit.change, file: hit.file })
-        }
-      }
+    const fullChanged = new Map() // POSIX path → A/D/M/R
+    for (const item of parseNameStatus(diffRes.value)) {
+      if (item.status === 'A' || item.status === 'D') fullChanged.set(item.path, item.status)
+      else if (item.status === 'M' || item.status === 'C') fullChanged.set(item.path, 'M')
+      else if (item.status === 'R') { fullChanged.set(item.path, 'R'); fullChanged.set(item.oldPath, 'R') }
     }
+    staleRefs.push(...collectStaleRefs(scanDir, fullChanged))
   } catch { /* 引用级漂移为 advisory，异常静默降级 */ }
 
   return {
@@ -380,18 +366,62 @@ function writeReport(r, { specBase, projectName }) {
   }
 }
 
-/** 读 scan 目录任一 .md 的 source_commit（同 modules.js 写入同值，取首个命中；全失败 → null） */
-function readSourceCommit(specBase, projectName) {
+/**
+ * 读 scan 目录全部 .md 的 source_commit，多文档异基线保守聚合（D-003@v2/D-009@v1）。
+ * 聚合=落后最多：去重基线逐个 `rev-list --count <c>..HEAD` 取计数最大者——拓扑序免疫
+ * rebase/amend 日期倒挂，且落后最多=漂移窗最大=保守目标本体。git 全失败 fail-soft 回退
+ * 首个命中（与旧版批次同值场景输出一致）。
+ * @param {string} specBase @param {string} projectName @param {string} [projectRoot] git 锚（计数用；缺省不聚合）
+ * @returns {string|null}
+ */
+function readSourceCommit(specBase, projectName, projectRoot) {
   const scanDir = join(specBase, 'docs', projectName, 'scan')
   if (!existsSync(scanDir)) return null
+  const commits = []
   try {
     for (const f of readdirSync(scanDir)) {
       if (!f.endsWith('.md')) continue
       const c = parseSourceCommit(readFileSync(join(scanDir, f), 'utf8'))
-      if (c) return c
+      if (c) commits.push(c)
+    }
+  } catch { /* 读失败 → 按空清单处理 */ }
+  if (commits.length === 0) return null
+  const distinct = [...new Set(commits)]
+  if (distinct.length === 1 || !projectRoot) return distinct[0]
+  let best = null, bestCount = -1
+  for (const c of distinct) {
+    const r = safeGit(projectRoot, ['rev-list', '--count', `${c}..HEAD`], { timeout: GIT_TIMEOUT_MS })
+    const n = r.error ? null : parseInt(r.value, 10)
+    if (n !== null && !Number.isNaN(n) && n > bestCount) { best = c; bestCount = n }
+  }
+  return best !== null ? best : distinct[0]
+}
+
+/**
+ * 引用级漂移命中（scan-refresh 与 computeScanDiff 共用单源，2026-09-14-scan-incremental-refresh）。
+ * @param {string} scanDir scan 文档目录
+ * @param {Map<string,string>} fullChanged POSIX 路径 → A/D/M/R（R 的旧路径须已入集）
+ * @returns {{doc:string, ref:string, change:string, file:string}[]} 命中清单（目录不存在/异常 → 空数组）
+ */
+export function collectStaleRefs(scanDir, fullChanged) {
+  const staleRefs = []
+  if (!existsSync(scanDir)) return staleRefs
+  const hitChange = (p) => {
+    if (fullChanged.has(p)) return { file: p, change: fullChanged.get(p) }
+    // src/ 前缀双向归一：文档 src 相对写法 ↔ git 仓库根路径
+    const alt = p.startsWith('src/') ? p.slice(4) : `src/${p}`
+    return fullChanged.has(alt) ? { file: alt, change: fullChanged.get(alt) } : null
+  }
+  for (const f of readdirSync(scanDir)) {
+    if (!f.endsWith('.md')) continue
+    const content = readFileSync(join(scanDir, f), 'utf8')
+    for (const ref of collectDocRefs(content)) {
+      if (ref.repo !== null) continue
+      const hit = hitChange(ref.file.replace(/\\/g, '/'))
+      if (hit) staleRefs.push({ doc: f, ref: ref.ref, change: hit.change, file: hit.file })
     }
-  } catch { /* 读失败 → null */ }
-  return null
+  }
+  return staleRefs
 }
 
 /** 收集 module-map 全部 paths 去重（归一 Windows 反斜杠 + 去尾部斜杠；无 paths → 空数组） */
@@ -412,8 +442,9 @@ function inScope(filePath, scope) {
   return scope.some((p) => p && (filePath === p || filePath.startsWith(p + '/')))
 }
 
-/** 解析 `git diff --name-status --find-renames` 输出 → [{ status, path, oldPath? }]（R/C 双路径） */
-function parseNameStatus(out) {
+/** 解析 `git diff --name-status --find-renames` 输出 → [{ status, path, oldPath? }]（R/C 双路径）。
+ * 导出供 scan-refresh 复用（同单源，2026-09-14-scan-incremental-refresh）。 */
+export function parseNameStatus(out) {
   const items = []
   if (!out) return items
   for (const line of out.split('\n')) {

package/src/scan-postcheck.js

@@ -561,6 +561,80 @@ export function stampScanDocHeaders({ cwd, specDir = null, project = null, mode
   return { fixed, skipped, stampedKeys }
 }
 
+/**
+ * per-doc 基线推进盖章（2026-09-14-scan-incremental-refresh，D-002@v1/D-003@v2）。
+ * 与 stampScanDocHeaders 的「只补缺不覆盖」契约相互独立：本函数**只改点名文档**的
+ * source_commit / updated_at / generator 三键（已有则替换、缺失则补），其余 frontmatter 键
+ * 与其余文档逐字节不动——增量刷新（scan refresh --done）专用。幂等：同值重跑零 diff。
+ *
+ * @param {{ cwd: string, specDir?: string|null, project?: string|null, docs?: string[],
+ *   headShort?: string|null, generator?: string }} opts
+ *   docs：scan 目录内文档文件名列表（如 ['ARCHITECTURE.md']）；project 缺省时遍历全部项目
+ * @returns {{ bumped: string[], skipped: { file: string, reason: string }[] }}
+ */
+export function bumpScanDocBaselines({ cwd, specDir = null, project = null, docs = [], headShort = null, generator = 'sillyspec-scan-refresh' }) {
+  const specBase = specDir ? specDir : join(cwd, '.sillyspec')
+  const docsRoot = join(specBase, 'docs')
+  const projects = project
+    ? [project]
+    : (existsSync(docsRoot) ? readdirSync(docsRoot, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) : [])
+  if (!headShort) {
+    try { headShort = String(git(cwd, ['rev-parse', '--short', 'HEAD']) || '').trim() || null } catch { headShort = null }
+  }
+  const updatedIso = new Date().toISOString()
+  const bumped = []
+  const skipped = []
+  for (const p of projects) {
+    const scanDir = join(docsRoot, p, 'scan')
+    if (!existsSync(scanDir)) {
+      for (const name of docs) skipped.push({ file: name, reason: `无 scan 目录：${scanDir}` })
+      continue
+    }
+    for (const name of docs) {
+      const filePath = join(scanDir, name)
+      let content
+      try { content = readFileSync(filePath, 'utf8') } catch (e) {
+        skipped.push({ file: name, reason: `读取失败：${String((e && e.message) || e).split('\n')[0]}` })
+        continue
+      }
+      // headShort 拿不到（非 git 仓）→ source_commit 键跳过不写坏值；updated_at/generator 恒写
+      const out = bumpFrontmatterKeys(content, {
+        source_commit: headShort || undefined,
+        updated_at: updatedIso,
+        generator,
+      })
+      if (out === null) { skipped.push({ file: name, reason: 'frontmatter 写入失败（内部错误）' }); continue }
+      try { writeFileSync(filePath, out); bumped.push(filePath) } catch (e) {
+        skipped.push({ file: name, reason: `写入失败：${String((e && e.message) || e).split('\n')[0]}` })
+      }
+    }
+  }
+  return { bumped, skipped }
+}
+
+/** frontmatter 键替换内核：已有行替换、缺失行在 frontmatter 内补（无 frontmatter 则新建头部）。
+ * 值为 undefined 的键跳过；键名限安全标识符（内部调用方固定三键，不做正则转义）。
+ * 尾部 `---` 无换行（agent 手编删尾换行的中间态）也认既有 frontmatter——否则会走「无
+ * frontmatter」分支头部新建一段、旧块残留正文（双 frontmatter，重审 P3 实证）。 */
+function bumpFrontmatterKeys(content, bumpKeys) {
+  const normalized = content.replace(/\r\n?/g, '\n')
+  const entries = Object.entries(bumpKeys).filter(([, v] ) => v !== undefined)
+  if (entries.length === 0) return null
+  const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)
+  if (!fmMatch) {
+    return `---\n${entries.map(([k, v]) => `${k}: ${v}`).join('\n')}\n---\n\n` + normalized
+  }
+  let fm = fmMatch[1]
+  for (const [k, v] of entries) {
+    const re = new RegExp(`^${k}:[^\\n]*$`, 'm')
+    if (re.test(fm)) fm = fm.replace(re, `${k}: ${v}`)
+    else fm += `\n${k}: ${v}`
+  }
+  // 重建 frontmatter 块（fmMatch[0] 可能无尾换行——重建统一补 \n，余下正文原样接回）
+  const rest = normalized.slice(fmMatch[0].length)
+  return `---\n${fm}\n---\n${rest}`
+}
+
 /**
  * source_root 污染一键修复（2026-08-21 agent-手工产出审计第四批 C-3）。
  *