sillyspec 3.28.8 → 3.28.10

package/src/run/quick-audit.js

@@ -178,14 +178,97 @@ export function printQuickAuditReview(review) {
       else console.warn(`   行号漂移 → 更新到当前源码；跑 sillyspec docs check 可看建议行号。`)
     }
   }
+
+  // ── [gate] 分级门禁 advisory 块（FR-03，2026-09-14-quick-exit-tiered-gates task-02）：L1/L2 画像
+  // 打印级别/跨度/模块清单/风险命中/检查项 + --no-docs 指引，L0 零输出。全部 advisory：不改 status
+  // 三态与 exit code（D-003）；窗口内未声明脏文件维持既有归属分流（上方 ⚖️/🔍 块），不并入文档
+  // 认领判定（D-005）；数据源 = review.gateProfile（auditQuickCompletion 挂载，scope-audit 重放同源）。
+  const gate = review.gateProfile
+  if (gate && (gate.level === 'L1' || gate.level === 'L2')) {
+    const isL2 = gate.level === 'L2'
+    const spanTxt = gate.degraded
+      ? 'module-map 缺失（降级档：按文件数判级）'
+      : `跨 ${gate.moduleSpan} 模块${Array.isArray(gate.modules) && gate.modules.length > 0 ? `（${gate.modules.map(m => m.id).join(' · ')}）` : ''}`
+    console.warn(`\n${isL2 ? '🛑' : '🚧'} [gate] ${gate.level} 规模门（${spanTxt} · ${gate.fileCount} 文件：${gate.codeFileCount} 代码 / ${gate.testFileCount} 测试）——advisory 提示不阻断：`)
+    if (Array.isArray(gate.unmappedFiles) && gate.unmappedFiles.length > 0) {
+      console.warn(`   ⚠️ ${gate.unmappedFiles.length} 个文件未命中 module-map（${gate.unmappedFiles.slice(0, 5).join(', ')}${gate.unmappedFiles.length > 5 ? ' 等' : ''}）`)
+    }
+    if (!isL2) {
+      // L1 检查项：每文件注记（--file-notes 覆盖率）+ 测试增量（机械规则）
+      console.warn(`   - 每文件注记检查：${gate.checks?.perFileNotes ? '✅ --file-notes 已覆盖全部变更文件' : `❌ 缺失——补 --file-notes "path1::注 || path2::注"（覆盖变更文件全集）`}`)
+      const td = gate.checks?.testDelta
+      console.warn(`   - 测试增量检查：${td === 'missing' ? `❌ missing——${gate.codeFileCount} 个代码文件改动无测试文件（补 test 改动进本会话）` : td === 'ok' ? '✅ 已含测试改动' : '— 不适用（≤1 代码文件）'}`)
+    } else {
+      // L2 检查项：模块文档认领（claimed/missing/exempt-no-docs）+ 风险命中的运行时证据要求
+      const dc = gate.checks?.docClaim
+      const noClaimable = gate.degraded || !Array.isArray(gate.modules) || gate.modules.length === 0
+      if (dc === 'exempt-no-docs') {
+        console.warn(`   - 模块文档认领：🛡️ 已 --no-docs 显式豁免（豁免已留痕 QUICKLOG 审计行）`)
+      } else if (noClaimable) {
+        // degraded / 无触及模块：computeGateProfile 空真 claimed——如实显示不适用，不出「已认领」误导
+        console.warn(`   - 模块文档认领：— 不适用（${gate.degraded ? '无 module-map' : '触及文件均未命中模块'}，无可认领卡片）`)
+      } else if (dc === 'claimed') {
+        console.warn(`   - 模块文档认领：✅ 触及模块的卡片文件已在改动集`)
+      } else {
+        console.warn(`   - 模块文档认领：❌ missing——触及模块（${Array.isArray(gate.modules) && gate.modules.length > 0 ? gate.modules.map(m => m.id).join(' · ') : '—'}）的卡片文件不在改动集`)
+        console.warn(`     ➜ 同步模块卡进本次改动，或确认无需文档落盘时 --done 带 --no-docs 显式豁免（豁免留痕，不阻断完成）`)
+      }
+      if (Array.isArray(gate.riskHits) && gate.riskHits.length > 0) {
+        console.warn(`   - 风险命中 ${gate.riskHits.length} 处（运行时证据要求——风险路径改动需在 --result「结果：」附运行验证说明，advisory 不等待）：`)
+        for (const h of gate.riskHits.slice(0, 8)) {
+          console.warn(`       ⚠️ ${h.pattern} ← ${h.file}`)
+        }
+        if (gate.riskHits.length > 8) console.warn(`       … 共 ${gate.riskHits.length} 处`)
+      }
+    }
+  }
 }
 
 /**
- * quick 阶段多变更交互式选择关联变更。
- * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
- * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
+ * [gate] 分级门禁 auditNote 组装（FR-03 task-02，gate-audit-note）：L1/L2 → 单行 `[gate]` 注记
+ * （随 complete-handlers 既有 auditNotes 通道落 QUICKLOG，--no-docs 豁免同通道留痕）；
+ * L0 / 无画像 → null（零落账，验收「L0 无 gate 落账行」）。纯函数、与上方 [gate] 打印块同一
+ * review.gateProfile 数据源；单独导出为可测（buildSemanticGuardHits 同款考量——避开
+ * handleQuickStageCompletion 的 quicklog 重机件直测组装层）。
+ * @param {object|null} gate review.gateProfile（auditQuickCompletion 产物；null/异常形状 → null）
+ * @returns {string|null}
+ */
+export function buildGateAuditNote(gate) {
+  if (!gate || typeof gate !== 'object' || (gate.level !== 'L1' && gate.level !== 'L2')) return null
+  const span = gate.degraded
+    ? 'module-map 缺失（降级档按文件数判级）'
+    : `跨 ${gate.moduleSpan} 模块`
+  const seg = [`[gate] ${gate.level}（${span} · ${gate.fileCount} 文件：${gate.codeFileCount} 代码/${gate.testFileCount} 测试）advisory`]
+  if (gate.level === 'L1') {
+    seg.push(`每文件注记${gate.checks?.perFileNotes ? '已全覆盖' : '缺失（--file-notes 覆盖变更文件全集）'}`)
+    const td = gate.checks?.testDelta
+    seg.push(`测试增量${td === 'ok' ? '已含' : td === 'missing' ? `缺失（${gate.codeFileCount} 个代码文件无测试改动）` : '不适用（≤1 代码文件）'}`)
+  } else {
+    const dc = gate.checks?.docClaim
+    const noClaimable = gate.degraded || !Array.isArray(gate.modules) || gate.modules.length === 0
+    seg.push(dc === 'exempt-no-docs' ? '模块文档认领已 --no-docs 显式豁免'
+      : noClaimable ? '模块文档认领不适用（无可认领模块）'
+        : dc === 'claimed' ? '模块文档认领已覆盖（模块卡在改动集）'
+          : '模块文档认领缺失（同步模块卡进改动集，或 --no-docs 显式豁免）')
+    if (Array.isArray(gate.riskHits) && gate.riskHits.length > 0) {
+      seg.push(`风险命中 ${gate.riskHits.length} 处（${gate.riskHits.slice(0, 5).map(h => `${h.pattern}←${h.file}`).join('、')}${gate.riskHits.length > 5 ? ' 等' : ''}）需运行时证据`)
+    }
+  }
+  return seg.join('；')
+}
+
+/**
+ * quick 阶段关联变更解析（含单候选信号门控）。
+ * - 0 活跃变更 → 不关联
+ * - 1 活跃变更 → 跑 recommendChanges 双信号打分：命中（score>0）→ 自动关联 + 大声提示
+ *   + autoLinked 溯源；未命中 → 不关联 + 提示。坑 quick-single-change-auto-link（2026-09-14
+ *   实证）：原实现无条件 `return [activeChanges[0]]`——多 agent 仓库里唯一活跃变更常是他者
+ *   会话遗留，挂载污染 tasks.md 且 --done 僵尸清理通道可误归档他者变更；单候选还绕过
+ *   recommend 的 quick-<hex8> 会话过滤（新 quick 互挂另一活跃 quick）。
  * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
- * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
+ * - ≥2 活跃变更 + 非交互 → 不关联 + 提示用 --change a,b
+ * @returns {Promise<{changes: string[], autoLinked: string[]}>} changes=最终关联清单；
+ *   autoLinked=其中机器自动关联的子集（guard 落 linkedChangesAuto 溯源，--done 归档闸消费）
  */
 export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
   let activeChanges = []
@@ -194,13 +277,7 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   } catch {
     activeChanges = []
   }
-  if (activeChanges.length === 0) return []
-  if (activeChanges.length === 1) return [activeChanges[0]]
-
-  if (nonInteractive || !process.stdin.isTTY) {
-    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
-    return []
-  }
+  if (activeChanges.length === 0) return { changes: [], autoLinked: [] }
 
   // 脏文件（推荐信号之一）。safeGit 带 safe.directory，避免 linked worktree/容器/挂载点下裸
   // `git status` 抛错致推荐信号静默丢失（multi-agent-review Q3 同类）。推荐非关键路径，失败回退 []。
@@ -214,7 +291,7 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
       .filter(f => !f.startsWith('.sillyspec/'))
   }
 
-  // 推荐打分（脏文件 + 任务描述双信号）
+  // 推荐打分（脏文件 + 任务描述双信号）——单候选也跑（信号门控），非仅 ≥2 交互推荐用
   let recommendations = []
   try {
     // quick-recommend.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
@@ -223,6 +300,26 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   } catch {
     recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
   }
+
+  // 单候选信号门控（坑 quick-single-change-auto-link）：有真实信号（脏文件命中 design 清单 /
+  // 任务描述命中 proposal）才自动关联，且大声提示可反悔；无信号一律不关联。quick-<hex8> 会话
+  // 行已被 recommendChanges 过滤 → recommendations 无该候选 → 不关联（防会话互挂）。
+  if (activeChanges.length === 1) {
+    const name = activeChanges[0]
+    const rec = recommendations.find(r => r.name === name)
+    if (rec && rec.score > 0) {
+      console.log(`🔗 唯一活跃变更 ${name} 命中关联信号（${rec.reasons.slice(0, 2).join('；')}）——已自动关联；无关请带 --linked-changes none 重启`)
+      return { changes: [name], autoLinked: [name] }
+    }
+    console.log(`💡 唯一活跃变更 ${name} 未命中关联信号（任务描述/脏文件无重叠）——默认不关联；如需关联请带 --linked-changes ${name} 重启`)
+    return { changes: [], autoLinked: [] }
+  }
+
+  if (nonInteractive || !process.stdin.isTTY) {
+    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
+    return { changes: [], autoLinked: [] }
+  }
+
   const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
   const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
   const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
@@ -249,7 +346,8 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   // 动态 import：@inquirer/prompts 只在本交互分支加载，不进 run 命令通用启动路径
   const { checkbox } = await import('@inquirer/prompts')
   const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
-  return selected
+  // 用户在 TTY 上亲手勾选确认 = 显式协作声明，不进 autoLinked
+  return { changes: selected, autoLinked: [] }
 }
 
 // ============ quick --done test+lint 硬门禁（2026-09-02 跨 agent 工单 P0-2）============

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))
@@ -632,6 +635,71 @@ export function checkPlatformManaged(cwd) {
   }
 }
 
+/**
+ * 平台模式产物落点指针（坑 platform-docs-dual-location，2026-09-15 EHS 生产实证：
+ * 变更 9 文档落 daemon specs 目录，工作树 .sillyspec/ 只剩旧变更残留、worktree 无
+ * .sillyspec——人类在工作树里找变更文档扑空，只有平台 changes files API 能读，双位置
+ * 造成「文件去哪了」困惑）。阶段 --done 完成时在工作树 .sillyspec/ 落一份人类可读指针
+ * PLATFORM-DOCS-POINTER.md：specRoot/runtimeRoot 物理路径 + workspaceId + 本变更文档
+ * 清单（.md 文件名+mtime + tasks/ 计数）+ 获取方式提示。
+ *
+ * 口径与 writePlatformPointer 三写同款豁免：本地模式（无 specRoot/runtimeRoot）零行为；
+ * 自指回环（repo-native junction 指回 cwd/.sillyspec）不写；temp 残留形态（specRoot 在
+ * 系统 temp 而项目不在）不写。fail-soft：任何写失败只 warn 不抛（对齐 user-inputs.md
+ * 追加先例）——指针是便利件，绝不阻断阶段完成。
+ *
+ * @param {string} cwd 项目根（指针落 cwd/.sillyspec/）
+ * @param {string|null} changeName 变更名（可空——无变更上下文时只写根路径头部）
+ * @param {{specRoot?: string|null, runtimeRoot?: string|null, workspaceId?: string|null}} [platformOpts]
+ * @param {string|null} [stageName] 触发阶段（展示用）
+ * @returns {{written: boolean, reason?: string, path?: string, error?: string}}
+ */
+export function writePlatformDocsPointer(cwd, changeName, platformOpts = {}, stageName = null) {
+  try {
+    const specRoot = platformOpts?.specRoot || null
+    const runtimeRoot = platformOpts?.runtimeRoot || null
+    if (!specRoot && !runtimeRoot) return { written: false, reason: 'local-mode' }
+    if (specRoot && isSelfReferentialSpecRoot(cwd, specRoot)) return { written: false, reason: 'self-referential' }
+    if (isTempResidueSpecRoot(cwd, specRoot)) return { written: false, reason: 'temp-residue' }
+    const localSpecDir = join(cwd, '.sillyspec')
+    mkdirSync(localSpecDir, { recursive: true })
+    const ts = new Date().toLocaleString('zh-CN', { hour12: false })
+    const lines = [
+      '<!-- sillyspec 平台模式产物落点指针（CLI 在阶段 --done 完成时自动维护；本地模式不生成本文件） -->',
+      '# 变更文档实际落点（工作树 .sillyspec/ 不是本仓权威数据面）',
+      '',
+      `- 平台 spec 根（proposal/design/verify-result 等变更文档）: ${specRoot || '（未指定）'}`,
+      `- 运行时根（worktrees/contract-artifacts/verify-logs）: ${runtimeRoot || '（未指定）'}`,
+      platformOpts?.workspaceId ? `- 工作区 ID: ${platformOpts.workspaceId}` : null,
+      `- 最近更新: ${stageName || '?'} 阶段完成 @ ${ts}${changeName ? `（change: ${changeName}）` : ''}`,
+    ].filter(Boolean)
+    const changeDir = (specRoot && changeName) ? join(specRoot, 'changes', changeName) : null
+    if (changeDir && existsSync(changeDir)) {
+      const docs = []
+      for (const f of readdirSync(changeDir)) {
+        if (!f.endsWith('.md')) continue
+        try {
+          const mtime = statSync(join(changeDir, f)).mtime.toLocaleString('zh-CN', { hour12: false })
+          docs.push(`- ${f}（mtime ${mtime}）`)
+        } catch { docs.push(`- ${f}`) }
+      }
+      const tasksDir = join(changeDir, 'tasks')
+      if (existsSync(tasksDir)) {
+        const cards = readdirSync(tasksDir).filter(f => f.endsWith('.md'))
+        if (cards.length > 0) docs.push(`- tasks/（${cards.length} 张任务卡）`)
+      }
+      if (docs.length > 0) lines.push('', `## 本变更文档（${changeName}）`, ...docs)
+    }
+    lines.push('', '获取方式：直接读上行物理路径，或经平台 changes files API（/changes/{id}/files/raw?path=...）逐文件下载。')
+    const pointerPath = join(localSpecDir, 'PLATFORM-DOCS-POINTER.md')
+    writeFileSync(pointerPath, lines.join('\n') + '\n')
+    return { written: true, path: pointerPath }
+  } catch (e) {
+    console.warn('⚠️ 平台产物落点指针写入失败（不阻断）:', e && e.message ? e.message : e)
+    return { written: false, reason: 'error', error: e && e.message }
+  }
+}
+
 /**
  * 自指 specRoot 判定（repo-native junction 回环检测，变更 2026-08-23-repo-native-spec-backfill）。
  *
@@ -1032,7 +1100,12 @@ export function isQuickMetadata(p, linkedChanges = []) {
   const file = normalizeGitPath(p)
   if (file.startsWith('.sillyspec/quicklog/')
     || file.startsWith('.sillyspec/.runtime/')
-    || file === '.sillyspec/knowledge/uncategorized.md'
+    // 知识库整体白名单（2026-09-15 用户实测反馈：登记知识条目是 quick 收尾常规动作，此前
+    // INDEX/known-issues/patterns/conventions/decisions 非元数据 → 危险门 blocked 只能 --force-baseline，
+    // 且 perFileNotes 强制 --file-notes 覆盖）：knowledge/ 是 CLI 自管面（classify append-only +
+    // validate 守门），与 quicklog 同级。可追溯性靠 quicklog 结构化条目 + git diff，不靠文件行。
+    // 前缀带尾斜杠：knowledge-base/ 等相近目录不命中。
+    || file.startsWith('.sillyspec/knowledge/')
     || (/^\.sillyspec\/docs\/[^/]+\/modules\/[^/]+\.md$/.test(file))
     || (/^\.sillyspec\/docs\/[^/]+\/modules\/_module-map\.yaml$/.test(file))) return true
   if (file.startsWith('.sillyspec/changes/')) {
@@ -1151,7 +1224,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 文件"升级为
@@ -1163,13 +1236,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 })
@@ -1179,6 +1247,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）
@@ -1257,11 +1349,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` 抛错被
@@ -1639,6 +1734,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/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）。
  *