sillyspec 3.28.7 → 3.28.9

package/src/scope-audit.js

@@ -15,13 +15,20 @@
  * 行数三档（D-002）：tracked → numstat；untracked 新文件 → wc-l 记全 + 行；binary（numstat
  * 两列 '-'）→ additions/deletions=null。三态（full-flow）：planned / unplanned / untouched。
  *
+ * quick 画像出口（2026-09-14-quick-exit-tiered-gates task-03，FR-04 / D-008）：quick 模式结果
+ * 增量携带 gateProfile（实时态透传 auditQuickCompletion 挂的 review.gateProfile，不重复计算；
+ * 冻结重放态透传 quicklog/patches 记录冻结值，旧记录按 rows 清单重算），表格出口按存在性
+ * 追加 [gate] 画像段、--json 出口随结果对象序列化——画像的独立可重放出口与阈值校准数据源。
+ * 既有三态对账表/归属表/--file 出口与返回字段语义零变化（gateProfile 为增量字段）。
+ *
  * 全 advisory（D-006）：不抛错阻断、不写门禁状态；任何异常 catch 后并入 degradedReason。
  * 纯读：不落盘、不改 guard/进度库。Windows 路径 \\→/ 归一，ESM-only，零新依赖。
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { join, dirname } from 'node:path'
-import { locateQuickSessionGuard, auditQuickCompletion, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, ancestorSpecDirs } from './run/shared.js'
+import { locateQuickSessionGuard, auditQuickCompletion, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, ancestorSpecDirs, isQuickMetadata } from './run/shared.js'
+import { computeGateProfile, resolveGateThresholds } from './quick-gate-profile.js'
 import { safeGit } from './git-helper.js'
 import { parseFileChangeListDetailed, pathMatches } from './change-list.js'
 
@@ -266,18 +273,20 @@ function filterPatchForFiles(patchText, filesSet) {
 }
 
 /**
-/** patch 内容 sha256（A-F01 防篡改锚——写入方存 json.patchSha256，读取方校验） */
-function sha256Text(text) {
-  return createHash('sha256').update(text, 'utf8').digest('hex')
+ * patch sha256——换行归一化口径（quick-ec5fc714）：git autocrlf 会在提交/检出时把 patch
+ * 转 CRLF（平台仓实测 mtime 晚落盘一天的假篡改告警）——双侧统一 LF 归一后取 hash。
+ */
+function sha256PatchNormalized(text) {
+  return createHash('sha256').update(String(text).replace(/\r\n/g, '\n'), 'utf8').digest('hex')
 }
 
 /**
- * 冻结 patch 完整性校验（A-F01）：json 记录的 patchSha256 与 patch 实文比对。
+ * 冻结 patch 完整性校验（A-F01）：json 记录的 patchSha256 与 patch 实文比对（LF 归一口径）。
  * @returns {boolean|null} true=一致；false=不匹配（可能被篡改）；null=未记录 hash（旧记录）
  */
 function verifyPatchIntegrity(recordedSha, patchText) {
   if (!recordedSha || typeof recordedSha !== 'string') return null
-  return sha256Text(patchText) === recordedSha
+  return sha256PatchNormalized(patchText) === recordedSha
 }
 
 /**
@@ -344,7 +353,8 @@ function slicePatchForFile(patchText, filePath) {
 
 /**
  * quick 记录态反查（guard 清理后）：扫祖先链各 specBase 的 quicklog/patches/*.json，
- * 按 json 内冗余的 sessionId 匹配。返回记录 + patch 路径（--file 切片源）。
+ * 按 json 内冗余的 sessionId 匹配。返回记录 + patch 路径（--file 切片源）+ specBase
+ * （命中目录——画像重放的 module-map/local.yaml 加载锚，task-03）。
  */
 function findQuickPatchRecord(cwd, sessionId) {
   for (const sb of ancestorSpecDirs(cwd)) {
@@ -355,7 +365,7 @@ function findQuickPatchRecord(cwd, sessionId) {
       try {
         const j = JSON.parse(readFileSync(join(dir, f), 'utf8'))
         if (j && j.sessionId === sessionId && Array.isArray(j.rows)) {
-          return { record: j, patchPath: join(dir, f.replace(/\.json$/, '.patch')), qlId: j.qlId || f.replace(/\.json$/, '') }
+          return { record: j, patchPath: join(dir, f.replace(/\.json$/, '.patch')), qlId: j.qlId || f.replace(/\.json$/, ''), specBase: sb }
         }
       } catch { /* 单文件损坏跳过 */ }
     }
@@ -363,6 +373,167 @@ function findQuickPatchRecord(cwd, sessionId) {
   return null
 }
 
+/** QUICKLOG 条目号形态（ql-20260914-001-abcd：日期-序号-短 hash，短 hash 4 hex） */
+const QL_ID_RE = /^ql-\d{8}-\d{3}-[0-9a-f]{4}$/
+
+/**
+ * ql-xxx → quick-xxx 反查（用户「为什么不直接用 ql-xxx 查」根治，ql-20260910-014 设计：
+ * 映射只在本机 guard，会话结束即清；patches 记录按 qlId 命名且 json 冗余 sessionId——
+ * 平台可抓的持久映射）。按文件名前缀匹配（qlId=文件名），避免逐文件解析全目录。
+ */
+function findQuickSessionByQlId(cwd, qlId) {
+  const norm = String(qlId || '').trim()
+  if (!QL_ID_RE.test(norm)) return null
+  for (const sb of ancestorSpecDirs(cwd)) {
+    try {
+      const jsonPath = join(sb, 'quicklog', 'patches', `${norm}.json`)
+      if (!existsSync(jsonPath)) continue
+      const j = JSON.parse(readFileSync(jsonPath, 'utf8'))
+      if (j && typeof j.sessionId === 'string' && QUICK_SID_RE.test(j.sessionId)) {
+        return { sessionId: j.sessionId, record: j, patchPath: join(sb, 'quicklog', 'patches', `${norm}.patch`), qlId: norm, specBase: sb }
+      }
+    } catch { /* 单文件损坏跳过 */ }
+  }
+  return null
+}
+
+/**
+ * quick 记录态回放结果构建（共用：guard 清理后 sessionId 反查 + ql-xxx 反查两入口）。
+ * 画像重放（FR-04 / D-008 / task-03）+ 「声明即归属」过滤（quick-ec5fc714）。
+ */
+async function buildQuickRecordResult(rec, requestedName) {
+  let gateProfile = null
+  try {
+    if (rec.record.gateProfile && typeof rec.record.gateProfile === 'object') {
+      gateProfile = rec.record.gateProfile
+    } else {
+      const rowsPaths = rec.record.rows
+        .map(r => (r && typeof r.path === 'string' ? r.path : ''))
+        .filter(Boolean)
+      if (rowsPaths.length > 0) {
+        const thresholds = await resolveReplayGateThresholds(rec.specBase)
+        gateProfile = computeGateProfile(
+          rowsPaths,
+          await loadGateModuleIndex(rec.specBase, rowsPaths),
+          thresholds ? { thresholds } : {},
+        )
+      }
+    }
+  } catch { gateProfile = null }
+  const filteredRows = rec.record.rows.filter(r => r && !isQuickMetadata(r.path || '', []))
+  const filterDropped = rec.record.rows.length - filteredRows.length
+  const viaQl = requestedName !== rec.record.sessionId && QL_ID_RE.test(requestedName)
+  return {
+    mode: 'quick', ok: true, degradedReason: null,
+    baseAnchor: rec.record.baseAnchor || `quick-window:${rec.record.sessionId || requestedName}`,
+    totals: rec.record.totals && typeof rec.record.totals === 'object' && filterDropped === 0
+      ? rec.record.totals
+      : { files: filteredRows.length, ...sumTotals(filteredRows) },
+    rows: filteredRows,
+    excluded: rec.record.excluded && Array.isArray(rec.record.excluded.foreignDeclared)
+      ? rec.record.excluded
+      : { foreignDeclared: [] },
+    frozenPatchPath: rec.patchPath,
+    patchSha256: rec.record.patchSha256 || null,
+    patchStatus: rec.record.patchStatus || null,
+    gateProfile,
+    note: `quick 会话已收尾——记录态（quicklog/patches/${rec.qlId}，${rec.record.savedAt ? String(rec.record.savedAt).replace('T', ' ').slice(0, 19) + ' 落盘' : '--done 时点冻结'}）${viaQl ? `；经 ql-Id 反查（会话 ${rec.record.sessionId}）` : ''}${filterDropped > 0 ? `；回放已剔除 ${filterDropped} 个 quick 元数据/并行变更目录文件（范围视图收紧）` : ''}`,
+  }
+}
+
+/**
+ * quick 审计链 module-map 的项目推导（2026-09-14-quick-exit-tiered-gates task-03）：
+ * loadQuickModuleIndex（run/shared.js，未 export）的加载路径是
+ * <specBase>/docs/<projectName>/modules/_module-map.yaml——scope-audit 侧无 progress 上下文
+ * 拿 projectName，按候选 map 推导：
+ *   - 单候选 → 直取（绝大多数仓单项目）；
+ *   - 多候选 + 样本文件（实时态=guard.allowedFiles 声明面 / 重放态=记录 rows 冻结集）→ 按
+ *     「样本归属得分唯一最高」消歧（computeGateProfile.unmappedFiles 同款归属口径，纯函数
+ *     零 IO 重用——本仓 dashboard+sillyspec 双 map 实证需要）；
+ *   - 零候选 / 无样本 / 得分平分 → null（画像走 degraded 档，fail-open 不猜，兼容策略第 1 条）。
+ * @param {string} specBase
+ * @returns {string[]} 带 _module-map.yaml 的项目名清单
+ */
+function listModuleMapProjects(specBase) {
+  if (!specBase) return []
+  try {
+    const docsDir = join(specBase, 'docs')
+    return readdirSync(docsDir).filter(n => existsSync(join(docsDir, n, 'modules', '_module-map.yaml')))
+  } catch {
+    return []
+  }
+}
+
+/** 单项目 _module-map.yaml 读取（parseModuleMapSimple canonical 解析，与 loadQuickModuleIndex 同款）；不可得/解析空 → null。 */
+async function readModuleMap(specBase, project) {
+  try {
+    const { parseModuleMapSimple } = await import('./modules.js')
+    const idx = parseModuleMapSimple(readFileSync(join(specBase, 'docs', project, 'modules', '_module-map.yaml'), 'utf8'))
+    return idx && Object.keys(idx).length > 0 ? idx : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 项目名推导（口径见 listModuleMapProjects 头注释）：唯一得分（样本非文档文件中归属最少
+ * unmapped 的 map）才采信，平分/无样本/多候选全失败 → null。
+ * @param {string} specBase
+ * @param {string[]} [sampleFiles] 归属得分样本（声明面 / 记录 rows）
+ * @returns {Promise<string|null>}
+ */
+async function pickModuleMapProject(specBase, sampleFiles = []) {
+  const names = listModuleMapProjects(specBase)
+  if (names.length === 1) return names[0]
+  if (names.length === 0 || !Array.isArray(sampleFiles)) return null
+  const files = sampleFiles.map(f => String(f || '')).filter(Boolean)
+  if (files.length === 0) return null
+  let best = null
+  let bestUnmapped = Infinity
+  let tie = false
+  for (const n of names) {
+    const idx = await readModuleMap(specBase, n)
+    if (!idx) continue
+    const unmapped = computeGateProfile(files, idx).unmappedFiles.length
+    if (unmapped < bestUnmapped) { best = n; bestUnmapped = unmapped; tie = false }
+    else if (unmapped === bestUnmapped) tie = true
+  }
+  return tie ? null : best
+}
+
+/**
+ * 画像重放的 moduleIndex 加载（task-03，FR-04）：与 run/shared.js loadQuickModuleIndex 同链路
+ * ——同路径 + parseModuleMapSimple（canonical）解析，项目按记录 rows 样本消歧；不可得 → null
+ * （computeGateProfile 走 degraded 档）。动态 import modules.js 隔离依赖（shared.js 同款）。
+ * @param {string} specBase quicklog/patches 记录命中的 spec 根
+ * @param {string[]} [sampleFiles] 项目消歧样本（记录 rows）
+ * @returns {Promise<object|null>}
+ */
+async function loadGateModuleIndex(specBase, sampleFiles = []) {
+  const project = await pickModuleMapProject(specBase, sampleFiles)
+  return project ? readModuleMap(specBase, project) : null
+}
+
+/**
+ * 画像重放的阈值合并（task-03，D-009）：与 auditQuickCompletion 画像挂载段同链路——
+ * <specBase>/local.yaml（= 实时态 readLocalYamlRaw(sessionRoot) 读的同一文件）+ js-yaml +
+ * resolveGateThresholds；缺失/坏 YAML → null（computeGateProfile 内回 THRESHOLDS 默认）。
+ * @param {string} specBase
+ * @returns {Promise<object|null>}
+ */
+async function resolveReplayGateThresholds(specBase) {
+  try {
+    const p = join(specBase, 'local.yaml')
+    if (!existsSync(p)) return null
+    const mod = await import('js-yaml')
+    const yamlLoad = mod.load || mod.default?.load
+    const cfg = yamlLoad(readFileSync(p, 'utf8'))
+    return cfg && typeof cfg === 'object' ? resolveGateThresholds(cfg) : null
+  } catch {
+    return null
+  }
+}
+
 /** 汇总非 null 行数（binary 与降级 null 不计入，不出伪数据） */
 function sumTotals(rows) {
   let additions = 0
@@ -391,6 +562,16 @@ async function computeQuickAudit({ cwd, platformOpts, sessionId, located, collec
   try {
     const mergedGuard = {
       ...guard,
+      // 画像输入对齐（2026-09-14-quick-exit-tiered-gates task-03，FR-04）：specBase/projectName
+      // 透传——complete-handlers :1050 同款 merge（「--done 收尾同源实时采集」的既有约定）补齐。
+      // guard.json 落盘不含这两键，缺省会让 auditQuickCompletion 挂的 review.gateProfile 恒走
+      // degraded 档（moduleSpan=null），与 --done 时点 review.gateProfile 字段不一致。projectName
+      // 无 progress 上下文，按 module-map 候选推导（声明会话以 allowedFiles 为归属得分样本；
+      // 零候选/无样本/平分 → null → degraded，fail-open）。specBase/projectName 在 audit 内只喂
+      // quicklog 目录解析（与 cwd 推导同一路径）、docSyncHint 模块归属与 gate 画像（computeQuickAudit
+      // 不消费 docSyncHint），不触 status/reasons/归属切分语义。
+      specBase: guardSpecBase,
+      projectName: await pickModuleMapProject(guardSpecBase, guard.allowedFiles),
       otherSessionsDeclared: collectOtherQuickSessionDeclarations(platformOpts, guardSpecBase, sessionId),
     }
     audit = await auditQuickCompletion(sessionRoot, mergedGuard, {})
@@ -419,14 +600,39 @@ async function computeQuickAudit({ cwd, platformOpts, sessionId, located, collec
     return { ...base, ok: false, degradedReason: `quick 窗口审计失败: ${hardFailure}` }
   }
 
-  // 归属切分（消费 auditQuickCompletion 产物，不重算）：attributedFiles（含 sameFileHits）→
-  // declared；undeclaredFiles − softTestFiles → undeclared；softTestFiles → soft。
+  // 归属切分（quick-ec5fc714 平台实测修正）：scope-audit 是**范围视图**不是门禁——按
+  // 「声明即归属」硬切：declared=声明∩窗口；soft=软归属；其余（含 quick 元数据/其他变更
+  // 目录/linkedChanges 文件——audit 侧刻意保留它们供审计行落盘不静默挤走，范围视图则不该
+  // 把别人的活算进来）归为 undeclared 仅 note 交代。窗口文件全在 undeclared（如声明文件
+  // 已提交无 diff）时，undeclared 升格进 rows（范围视图只展示改了的东西）——本 quick
+  // 实测：声明两 pi-rpc 文件已提交 + 他者变更目录 19 文件未声明，行数贡献恰来自后者。
   const attributed = Array.isArray(audit.attributedFiles) ? audit.attributedFiles.map(toPosix) : []
   const undeclared = Array.isArray(audit.undeclaredFiles) ? audit.undeclaredFiles.map(toPosix) : []
   const softSet = new Set((Array.isArray(audit.softTestFiles) ? audit.softTestFiles : []).map(toPosix))
   const attrSet = new Set(attributed)
-
-  const rowFiles = [...new Set([...attributed, ...undeclared])]
+  const linkedChangesArr = Array.isArray(guard.linkedChanges) ? guard.linkedChanges.map(c => String(c).replace(/\\/g, '/')) : []
+  const isLinkedLeftover = (f) => linkedChangesArr.some(lc => f.startsWith(`.sillyspec/changes/${lc}/`) || f.startsWith(`.sillyspec/changes/archive/${lc}/`))
+
+  let rowFiles
+  let dropNote = null
+  if (attributed.length > 0 || softSet.size > 0) {
+    // 有归属文件时：undeclared 全部剔出范围视图——undeclared 即「不属于本 quick」的文件
+    // （他者变更目录/quicklog 产物/无关未提交），audit 侧留它们供审计行追溯，范围视图不该
+    // 展示（平台仓实测：窗口 13 个文件里 11 个是他者变更目录，唯二归属文件已提交）。
+    rowFiles = [...new Set([...attributed, ...softSet])]
+    if (undeclared.length > 0) {
+      dropNote = `${undeclared.length} 个未声明文件不计入范围视图（他者变更目录/quicklog 产物/漏声明——audit 行有追溯）`
+    }
+  } else {
+    // 窗口全 undeclared（如声明文件已提交无 diff）：范围视图仍剔 quick 元数据/变更目录
+    // ——audit 侧留它们供审计行追溯，范围视图不展示他者活（platform quick-ffb92f60 实测：
+    // 19 个 undeclared 中 17 个是他者变更目录/quicklog 产物，唯二声明文件已提交）。真未知的
+    // 源码/业务文件保留进 rows（他者窗口改动或漏声明，note 交代）。
+    rowFiles = [...new Set(undeclared.filter(f => !isQuickMetadata(f, linkedChangesArr) && !isLinkedLeftover(f)))]
+    if (rowFiles.length < undeclared.length) {
+      dropNote = `${undeclared.length - rowFiles.length} 个 quick 元数据/他者变更目录文件不计入范围视图`
+    }
+  }
   const stats = collectNumstatByPath(sessionRoot, rowFiles, { baseRef: 'HEAD' })
 
   const rows = rowFiles.map(f => {
@@ -446,7 +652,7 @@ async function computeQuickAudit({ cwd, platformOpts, sessionId, located, collec
 
   // 「quick 已提交」降级（design 总体方案）：窗口空（changedFiles 空）且 QUICKLOG 已有该会话
   // 条目 → 记录态提示读 QUICKLOG，不以空表冒充实时。
-  let note = null
+  let note = dropNote
   if (rowFiles.length === 0) {
     const qlId = guard.quicklogId || null
     if (quicklogHasEntry(guardSpecBase, qlId)) {
@@ -475,6 +681,11 @@ async function computeQuickAudit({ cwd, platformOpts, sessionId, located, collec
     },
     frozenPatch,
     note,
+    // 画像透传（FR-04 / task-03 gateProfile-json）：auditQuickCompletion 挂的 review.gateProfile
+    // 原样随 review 携带进结果对象——不重复计算（与 --done 时点同源）；fail-open 时为 null
+    // （消费方按存在性读取）。complete-handlers --done 落 quicklog/patches/<qlId>.json 时随
+    // 快照对象冻结，供冻结重放路径透传。
+    gateProfile: audit.gateProfile && typeof audit.gateProfile === 'object' ? audit.gateProfile : null,
   }
 }
 
@@ -562,16 +773,71 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
       : `design.md 不存在（${toPosix(designMdPath)}）——降级实际侧 only 视图（不出三态列）`
   }
 
-  // —— 实际侧（verify-postcheck.js task-02 契约：files + baseAnchor；动态 import 隔离
-  //    并行时序——task-02 未落地时降级说明而非炸）——
+  // —— 实际侧采集 ——
+  // 形态 A（worktree 存活，quick-ec5fc714）：**自采纯 worktree 口径**——锚（meta baselineCommit
+  // 优先）..worktree 工作区 = 本变更真实边界（子代理未提交改动 + 分支已提交）。不沿用
+  // resolveVerifyChangedFiles（其语义是「verify 证据核验面」：主仓∪worktree 并集——对证据核验
+  // 合理，对本变更范围全是噪音：主仓侧 20 并行文件混入，且它们对 worktree 锚 diff miss 后落
+  // wc-l 档记成整文件行数，两放大器叠加出 +11840/22 文件的巨型表）。
+  // 形态 B（post-apply）：继续走 resolveReconcileActualFiles 三源（本变更活已回主仓，语义正确）。
   let actual = null
   let actualFailure = null
   try {
-    const mod = await import('./verify-postcheck.js')
-    if (typeof mod.resolveReconcileActualFiles !== 'function') {
-      throw new Error('resolveReconcileActualFiles 未导出（依赖契约未就绪）')
+    const metaPath = join(sb, '.runtime', 'worktrees', changeName, 'meta.json')
+    if (existsSync(metaPath)) {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
+      const wtRoot = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+        ? meta.worktreePath
+        : cwd
+      const anchor = meta.baselineCommit || meta.actualBaseHash || meta.baseHash || null
+      if (anchor) {
+        const diffOut = safeGit(wtRoot, ['diff', '--name-only', anchor], { timeout: 30 * 1000 })
+        if (!diffOut.error && typeof diffOut.value === 'string') {
+          // 过滤口径与 resolveVerifyChangedFiles 的 wtFiles 同款（保留 docs 交付物，排运行时/进度面）
+          const wtFilter = (p) => p && p !== '.sillyspec'
+            && !p.startsWith('.sillyspec/changes/')
+            && !p.startsWith('.sillyspec/.runtime/')
+            && !p.startsWith('.sillyspec/quicklog/')
+          const files = diffOut.value.split('\n')
+            .map(p => toPosix(p.replace(/^"|"$/g, '').trim()))
+            .filter(wtFilter)
+          // untracked 新文件不在 diff（git diff 只看 tracked）——status --porcelain 并入
+          // （与旧链路 includeWorkingTree 的 wtFiles 半边同覆盖，行数侧走 wc-l 档）
+          const st = safeGit(wtRoot, ['status', '--porcelain', '--untracked-files=all'], { timeout: 30 * 1000, trim: false })
+          if (!st.error && typeof st.value === 'string') {
+            for (const line of st.value.split('\n')) {
+              if (!line.startsWith('??')) continue
+              const p = toPosix(line.slice(3).trim().replace(/^"|"$/g, '').split(' -> ').pop() || '')
+              if (wtFilter(p) && !files.includes(p)) files.push(p)
+            }
+          }
+          actual = { ok: true, form: 'worktree', files, sources: ['worktree:diff-anchor..worktree', 'worktree:status-untracked'], foreignExcluded: 0, degradedReason: null, baseAnchor: anchor }
+        } else {
+          actual = { ok: false, form: 'worktree', files: [], sources: [], foreignExcluded: 0, degradedReason: 'worktree 锚定 diff 失败', baseAnchor: null }
+        }
+      } else {
+        // 无锚 meta（baseHash 等字段缺失）：退 HEAD 未提交窗口口径——文件集=status 全量
+        // （tracked 改动 + untracked），行数侧由主链路 HEAD 兜底（quick-8aa52289 契约不变）
+        const st = safeGit(wtRoot, ['status', '--porcelain', '--untracked-files=all'], { timeout: 30 * 1000, trim: false })
+        const files = []
+        if (!st.error && typeof st.value === 'string') {
+          for (const line of st.value.split('\n')) {
+            const p = toPosix(line.slice(3).trim().replace(/^"|"$/g, '').split(' -> ').pop() || '')
+            if (p && p !== '.sillyspec'
+              && !p.startsWith('.sillyspec/changes/')
+              && !p.startsWith('.sillyspec/.runtime/')
+              && !p.startsWith('.sillyspec/quicklog/')) files.push(p)
+          }
+        }
+        actual = { ok: true, form: 'worktree', files, sources: ['worktree:status-porcelain(HEAD-window)'], foreignExcluded: 0, degradedReason: null, baseAnchor: null }
+      }
+    } else {
+      const mod = await import('./verify-postcheck.js')
+      if (typeof mod.resolveReconcileActualFiles !== 'function') {
+        throw new Error('resolveReconcileActualFiles 未导出（依赖契约未就绪）')
+      }
+      actual = mod.resolveReconcileActualFiles({ cwd, specBase: sb, runtimeRoot, changeName })
     }
-    actual = mod.resolveReconcileActualFiles({ cwd, specBase: sb, runtimeRoot, changeName })
   } catch (e) {
     actualFailure = e && e.message ? String(e.message).split('\n')[0] : String(e)
   }
@@ -596,6 +862,29 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
     return { ...base, degradedReason: [reason, planDegraded].filter(Boolean).join('；') }
   }
 
+  // —— execute --done 采集·apply-pathspec 归属收窄（quick-ec5fc714）：apply 时点在 .runtime
+  // 落过本变更精确文件清单（worktree-apply.js 产 apply-pathspec-<change>.txt）——execute 采集
+  // 形态（freshActual+collectPatch，仅 printExecuteScopeAudit 组合）下按它收窄 actual.files，
+  // 快照/patch 冻**归属面**而非开放区间（平台仓实测：186KB 快照中 23/44 段为并行会话 docs
+  // 同步等噪音）。查询面不收窄（快照说什么是什么）；pathspec 缺失退开放区间（in-place 等）。
+  let narrowNote = null
+  if (freshActual && collectPatch) {
+    try {
+      const pathspecFile = join(runtimeRoot, `apply-pathspec-${changeName}.txt`)
+      const owned = readFileSync(pathspecFile, 'utf8').split('\n').map(l => toPosix(l.trim())).filter(Boolean)
+      if (owned.length > 0) {
+        const ownedSet = new Set(owned)
+        const before = actual.files.length
+        actual = { ...actual, files: actual.files.filter(f => ownedSet.has(toPosix(f))) }
+        // 收窄掉的并行噪音可见性保留（审计不静默挤走）
+        const dropped = before - actual.files.length
+        if (dropped > 0) {
+          narrowNote = `快照已按 apply-pathspec 收窄至本变更归属文件（剔除开放区间并行文件 ${dropped} 个——它们归属各自会话/变更）`
+        }
+      }
+    } catch { /* pathspec 缺失 → 开放区间（旧行为） */ }
+  }
+
   // —— 已收尾变更·冻结快照优先（真实 > 冻结记录 > 实时开放区间）：归档变更的范围应封闭在
   // apply 时点，不随后续主仓改动漂移（quick-f5acdeeb）；quick-bd84b852 放宽——**post-apply
   // （分支已删 = execute 已 apply 收尾）的活跃变更同样收尾**，此后实时区间只会被并行演进泡大
@@ -669,6 +958,7 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
   const degraded = []
   if (planDegraded) degraded.push(planDegraded)
   const notes = []
+  if (narrowNote) notes.push(narrowNote)
   // 已收尾但快照缺失（上方分支置位）：实时开放区间兜底，明示漂移语义——快照机制上线
   // （2026-09-10）前收尾的旧变更冻结记录无法重建，如实告知替代渠道。
   if (noSnapshotDrift) {
@@ -766,7 +1056,12 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
  *                 kind: 'binary'|'new'|'modified'|'deleted',
  *                 verdict?: 'planned'|'unplanned'|'untouched', attribution?: 'declared'|'soft'|'undeclared' }>,
  *   excluded: { foreignDeclared: Array<{ file: string, sessions: string[] }> },
- *   note?: string|null }>}
+ *   note?: string|null,
+ *   gateProfile?: object|null }>}
+ *   gateProfile（2026-09-14-quick-exit-tiered-gates task-03 增量字段，消费方按存在性读取）：
+ *   仅 quick 模式携带——实时态透传 auditQuickCompletion 挂的 review.gateProfile（不重复计算）；
+ *   冻结重放态透传 quicklog/patches 记录冻结值（旧记录无 → rows 文件清单现算重放）。full-flow
+ *   全流程变更恒无该字段（零回归契约）。
  */
 export async function computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts, collectPatch, freshActual } = {}) {
   const empty = {
@@ -778,6 +1073,21 @@ export async function computeChangeScopeAudit({ cwd, specBase, changeName, platf
     if (!cwd || !changeName) {
       return { ...empty, degradedReason: '参数缺失：cwd 与 changeName 必填' }
     }
+    // ql-xxx 反查（「为什么不直接用 ql-xxx 查」根治）：patches 记录按 qlId 命名且 json 冗余
+    // sessionId——ql-xxx → quick-xxx 映射在 patches 里持久可查（guard 已清也能出记录态）。
+    // 提升到 quick 判定外层：ql-xxx 不匹配 QUICK_SID_RE，在内部分支永远进不去。
+    if (QL_ID_RE.test(changeName)) {
+      const byQl = findQuickSessionByQlId(cwd, changeName)
+      if (byQl) {
+        const rec = { record: byQl.record, patchPath: byQl.patchPath, qlId: byQl.qlId, specBase: byQl.specBase }
+        return buildQuickRecordResult(rec, changeName)
+      }
+      return {
+        ...empty,
+        mode: 'quick',
+        degradedReason: `quick 条目 ${changeName} 在 quicklog/patches/ 无记录——会话未产生改动、早于记录机制，或 patches 目录已被清理`,
+      }
+    }
     // quick 模式判定（pattern + guard 双条件，与 run/command.js :140/:652 口径一致）
     if (QUICK_SID_RE.test(changeName)) {
       const located = locateQuickSessionGuard(cwd, changeName)
@@ -788,21 +1098,7 @@ export async function computeChangeScopeAudit({ cwd, specBase, changeName, platf
       // 命中出冻结记录（行数为 --done 时点真值），patch 可供 --file 切片
       const rec = findQuickPatchRecord(cwd, changeName)
       if (rec) {
-        return {
-          mode: 'quick', ok: true, degradedReason: null,
-          baseAnchor: rec.record.baseAnchor || `quick-window:${changeName}`,
-          totals: rec.record.totals && typeof rec.record.totals === 'object'
-            ? rec.record.totals
-            : { files: rec.record.rows.length, ...sumTotals(rec.record.rows) },
-          rows: rec.record.rows,
-          excluded: rec.record.excluded && Array.isArray(rec.record.excluded.foreignDeclared)
-            ? rec.record.excluded
-            : { foreignDeclared: [] },
-          frozenPatchPath: rec.patchPath,
-          patchSha256: rec.record.patchSha256 || null,
-          patchStatus: rec.record.patchStatus || null,
-          note: `quick 会话已收尾——记录态（quicklog/patches/${rec.qlId}，${rec.record.savedAt ? String(rec.record.savedAt).replace('T', ' ').slice(0, 19) + ' 落盘' : '--done 时点冻结'}）`,
-        }
+        return buildQuickRecordResult(rec, changeName)
       }
       return {
         ...empty,
@@ -936,6 +1232,8 @@ function fmtCount(n) {
  *
  * 防御式：result 任意字段缺失/畸形不抛（advisory 展示层）。opts.maxRows 截断 + 指引行
  * （R-03：大表注入场景由调用方传 60，命令直跑缺省全表）。
+ * [gate] 画像段（task-03，gate-table-section）：result.gateProfile 存在时（quick 模式）追加
+ * 级别/跨度/模块/风险命中/缺失检查项段；字段缺失/为 null（full-flow / 重放不可得）→ 零输出零回归。
  *
  * @param {object} result computeChangeScopeAudit 返回值
  * @param {{ maxRows?: number }} [opts] 可选截断（缺省不截）
@@ -1001,6 +1299,38 @@ export function renderScopeAuditTable(result, opts = {}) {
   const undeclared = rows.filter(x => x && x.attribution === 'undeclared').length
   if (undeclared > 0) lines.push(`   ⚠️ 未声明 ${undeclared} 文件——超出 allowedFiles 声明面，补 --files 声明或注明原因`)
 
+  // ── [gate] 画像段（2026-09-14-quick-exit-tiered-gates task-03，FR-04 / D-008 gate-table-section）：
+  // quick 会话分级门禁画像的表格出口。按 gateProfile 存在性渲染——full-flow 变更 / 画像为 null
+  // → 零输出零回归；检查项随级别分层（L1：每文件注记+测试增量；L2：模块文档认领+风险命中），
+  // 与 run/quick-audit.js [gate] 打印块同一 review.gateProfile 数据源、同 tier 语义（advisory 展示，
+  // 不构成门禁）。防御式：字段缺失/畸形不抛（degraded 无 span、modules 空集等均有占位）。
+  const gate = r.gateProfile && typeof r.gateProfile === 'object' ? r.gateProfile : null
+  if (gate) {
+    const gateModules = Array.isArray(gate.modules) ? gate.modules.filter(m => m && typeof m === 'object') : []
+    const spanTxt = gate.degraded
+      ? '无 module-map（降级档：span 不参与判级）'
+      : `跨 ${gate.moduleSpan ?? '—'} 模块${gateModules.length > 0 ? `（${gateModules.map(m => String(m.id)).join(' · ')}）` : ''}`
+    lines.push(`   🚦 [gate] ${gate.level ?? '—'} 规模门（${spanTxt} · ${gate.fileCount ?? '—'} 文件：${gate.codeFileCount ?? '—'} 代码 / ${gate.testFileCount ?? '—'} 测试）——advisory 画像不阻断`)
+    if (Array.isArray(gate.unmappedFiles) && gate.unmappedFiles.length > 0) {
+      lines.push(`   ⚠️ ${gate.unmappedFiles.length} 个文件未命中 module-map（${gate.unmappedFiles.slice(0, 5).join(', ')}${gate.unmappedFiles.length > 5 ? ' 等' : ''}）`)
+    }
+    const checks = gate.checks && typeof gate.checks === 'object' ? gate.checks : {}
+    if (gate.level === 'L1') {
+      if (checks.perFileNotes === false) lines.push('   - 每文件注记缺失——补 --file-notes "path1::注 || path2::注"（覆盖变更文件全集）')
+      if (checks.testDelta === 'missing') lines.push(`   - 测试增量缺失——${gate.codeFileCount} 个代码文件改动无测试文件`)
+    } else if (gate.level === 'L2') {
+      if (checks.docClaim === 'missing') lines.push('   - 模块文档认领缺失——触及模块的卡片文件不在改动集（补模块卡/changelog 或 --no-docs 豁免）')
+      if (checks.docClaim === 'exempt-no-docs') lines.push('   - 模块文档认领：--no-docs 显式豁免')
+    }
+    if (Array.isArray(gate.riskHits) && gate.riskHits.length > 0) {
+      lines.push(`   - 风险命中 ${gate.riskHits.length} 处（运行时证据要求——风险路径改动需附运行验证说明）：`)
+      for (const h of gate.riskHits.slice(0, 5)) {
+        if (h && typeof h === 'object') lines.push(`     · [${h.pattern}] ${h.file}`)
+      }
+      if (gate.riskHits.length > 5) lines.push(`     … 共 ${gate.riskHits.length} 处`)
+    }
+  }
+
   // 他者会话声明排除面（R-04：不进 rows，单列可见）
   if (foreignDeclared.length > 0) {
     lines.push(`   他者会话声明（不进上表，归属对应会话审计）：`)

package/src/spec-sync.js

@@ -124,6 +124,9 @@ export function hashFiles(entries) {
       hash: _hashBuffer(buf),
       mtime: Math.floor(e.mtimeMs / 1000),
       absPath: e.absPath,
+      // 批 E-①：buf 随行携带（computeSpecOps 的 update/add 直接取用）——消除变更文件二次
+      // readFileSync（大文件双读）。docs 树为文本内容、量级有限，整批驻留可接受。
+      buf,
     };
   });
 }
@@ -177,20 +180,22 @@ export function computeSpecOps(serverManifest, localFiles) {
     return [];
   }
 
-  // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同
+  // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同。
+  // 批 E-①：候选新路径按 hash 建索引 O(N+M)——旧双重循环 O(N×M)，万级文件树明显变慢。
   const renames = [];
-  const consumedNew = new Set();
+  const newByHash = new Map(); // hash → 未被服务器收录且未被消费的新路径队列
+  for (const [newPath, entry] of localMap) {
+    if (serverSet.has(newPath)) continue
+    const list = newByHash.get(entry.hash)
+    if (list) list.push(newPath); else newByHash.set(entry.hash, [newPath])
+  }
   for (const oldPath of serverPaths) {
-    if (localSet.has(oldPath)) continue;
-    const cachedEntry = server[oldPath];
-    for (const newPath of localMap.keys()) {
-      if (serverSet.has(newPath)) continue;
-      if (consumedNew.has(newPath)) continue;
-      if (localMap.get(newPath).hash === cachedEntry.hash) {
-        renames.push({ oldPath, newPath });
-        consumedNew.add(newPath);
-        break;
-      }
+    if (localSet.has(oldPath)) continue
+    const candidates = newByHash.get(server[oldPath].hash)
+    if (candidates && candidates.length > 0) {
+      const newPath = candidates.shift()
+      renames.push({ oldPath, newPath })
+      if (candidates.length === 0) newByHash.delete(server[oldPath].hash)
     }
   }
   const renamedOld = new Set(renames.map((r) => r.oldPath));
@@ -212,7 +217,7 @@ export function computeSpecOps(serverManifest, localFiles) {
     if (localSet.has(p)) {
       const localEntry = localMap.get(p);
       if (localEntry.hash !== server[p].hash) {
-        const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+        const content = (localEntry.buf ?? readFileSync(localEntry.absPath ?? join('.', p))).toString('base64');
         ops.push({
           op: 'update',
           path: p,
@@ -235,7 +240,7 @@ export function computeSpecOps(serverManifest, localFiles) {
     if (renamedNew.has(p)) continue;
     if (!serverSet.has(p)) {
       const localEntry = localMap.get(p);
-      const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+      const content = (localEntry.buf ?? readFileSync(localEntry.absPath ?? join('.', p))).toString('base64');
       ops.push({
         op: 'add',
         path: p,

package/src/stage-contract-spec.js

@@ -317,10 +317,11 @@ const PLAN_RULES = [
     target: { root: 'change', path: 'design.md', scope: 'full' },
     data: {
       messageMissingList: 'design.md 缺少「文件变更清单」章节（或清单解析为空），无法做文件覆盖对账。该章节在 brainstorm 模板中为必填；请在 design.md 补上完整的文件变更清单（列出本次新增/修改/删除的源码文件）后重试。',
-      messageUncovered: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。',
+      messageUncovered: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。\n   若跨仓文件被标为 [main]：多为仓变更段头未被识别（段头须为「## <repo-key> 仓变更」），先核对段头格式再补 task。',
+      messageMalformedHeader: 'design.md「文件变更清单」内疑似仓变更段头但格式无法解析：「${line}」\n   该段下文件会被记到上一段仓（或 main）→ 文件覆盖对账整段错位（误报未覆盖或漏检）。\n   修复：段头写成「## <repo-key> 仓变更」（repo-key 限字母数字._-，可加编号前缀与（…）备注后缀）；若这是下一章节标题而非段头，请改名避免形如「<词> 仓变更…」。',
     },
-    spec: 'design.md「文件变更清单」中的每个源码文件,必须被至少一个 task 的 allowed_paths 覆盖(前缀/glob 容差匹配),否则 execute 子代理无权改它→必然漏改。有 task 卡片但 design 缺「文件变更清单」章节也阻断(清单是覆盖对账的基准)。',
-    failMessage: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。',
+    spec: 'design.md「文件变更清单」中的每个源码文件,必须被至少一个 task 的 allowed_paths 覆盖(前缀/glob 容差匹配),否则 execute 子代理无权改它→必然漏改。有 task 卡片但 design 缺「文件变更清单」章节也阻断(清单是覆盖对账的基准)。疑似仓变更段头但格式解析不了(repo-key 非法/仓变更后接自由文本)同样阻断并点名该行——段头错记仓会让对账整段错位。',
+    failMessage: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。\n   若跨仓文件被标为 [main]：多为仓变更段头未被识别（段头须为「## <repo-key> 仓变更」），先核对段头格式再补 task。',
   },
   // task-plan-reconciliation(custom):plan.md 声明任务 ↔ tasks/ 卡片双向对账（债单 D-2b）。
   // 修复场景：plan 列 17 个任务只生成 12 张卡（尾部文档同步类任务漏卡），execute 审计只看