sillyspec 3.28.8 → 3.28.10

package/src/quick-gate-profile.js

@@ -0,0 +1,251 @@
+/**
+ * quick-gate-profile.js — quick 出口分级门禁画像（信号层，纯函数零 IO）
+ *
+ * quick --done 分级门禁的信号单一来源（2026-09-14-quick-exit-tiered-gates task-01 / FR-02）：
+ * 输入 CLI 审计链的 git 事实 changedFiles（非 --files 自声明）+ 调用方传入的 moduleIndex
+ * （_module-map.yaml 解析结果），输出 L0/L1/L2 画像与检查项，供 Wave 2 接线消费
+ * （run/shared.js 挂 review.gateProfile → complete-handlers 落账 / quick-audit 打印 /
+ * scope-audit 表格与 --json 双出口）。本模块零 IO、零子进程：moduleIndex、风险表、阈值
+ * 全部由参数或默认值提供（D-007 独立纯函数模块；R-04 画像=纯字符串运算）。
+ *
+ * 判级（阈值只引用 THRESHOLDS 常量，不散落字面量）：
+ *   正常态（moduleIndex 可用）：L2 = 跨 ≥L2_SPAN 模块 或 风险命中；L1 = 跨 ≥L1_SPAN 模块
+ *     或 ≥L1_FILES 文件；否则 L0。
+ *   降级态（moduleIndex 为 null/undefined/空，如未 scan / 无 module-map 的存量项目）：
+ *     span 退出判级，L2 = ≥L2_FILES_DEGRADED 文件 或 风险命中；L1 = ≥L1_FILES 文件。
+ *   全部 advisory（D-003：升 blocking 是另立变更的显式决策），不抛错不阻断。
+ *
+ * 计数口径（design 接口定义，勿自创字段）：
+ *   fileCount     = 全部变更文件数（判级用的「文件数」信号与之一致——与旧「≤3 文件」规则
+ *                   及 sillyhub 校准统计同基）；
+ *   testFileCount = 非文档文件中：路径含 __tests__/、/tests/ 目录段、basename test_ 前缀
+ *                   （python 风格）或 .test./_test./.spec. 命名（对齐仓内既有测试判定先例）；
+ *   codeFileCount = 其余非文档文件。文档口径沿用 docSyncHint 的 isDoc（run/shared.js
+ *                   auditQuickCompletion 内 isDocFile 同款：.md/.yaml/.yml 扩展或 docs/、
+ *                   .sillyspec/docs/ 前缀——模块卡与 changelog sidecar 均 .md 天然覆盖），
+ *                   文档文件不计入 testFileCount/codeFileCount，也不参与模块归属与风险命中。
+ */
+import { QUICK_RISK_PATH_PATTERNS } from './change-risk-profile.js'
+
+/** 代码内默认阈值（task-05 真实图谱校准定稿，缺省行为的单一事实源；local.yaml quick-gate 段可覆写，D-009）。
+ *  定稿依据（2026-09-14，sillyhub 919 条 quicklog × 5 份真实 _module-map.yaml 重算交叉表，
+ *  证据全文见主仓 changes/2026-09-14-quick-exit-tiered-gates/design.md「阈值校准记录」）：
+ *  L1_SPAN=2 落在文档同步率断崖上（≤3 文件档 span1 33.3% → span2-3 5.9%，近期口径）；
+ *  L2_SPAN=4 边界内格子全档最差（近期 span4+×4-10 文件 0-14.3%）；L1_FILES=4 维持旧规则
+ *  「≤3 文件」边界连续性（文件维度无同步率断崖——量错维度的实证本身）；L2_FILES_DEGRADED=8
+ *  覆盖降级档最差文件桶 7-10（32.9-35.3%）。四值与 brainstorm 初值一致，维持不调。 */
+export const THRESHOLDS = {
+  L1_SPAN: 2,            // 跨 ≥2 模块 → L1
+  L1_FILES: 4,           // 或 ≥4 文件 → L1
+  L2_SPAN: 4,            // 跨 ≥4 模块 → L2
+  L2_FILES_DEGRADED: 8,  // module-map 缺失降级档：≥8 文件 → L2
+}
+
+/** local.yaml quick-gate 键 → THRESHOLDS 常量键（覆写面与代码默认值的单一对照）。 */
+const GATE_KEY_TO_THRESHOLD = {
+  l1_span: 'L1_SPAN',
+  l1_files: 'L1_FILES',
+  l2_span: 'L2_SPAN',
+  l2_files_degraded: 'L2_FILES_DEGRADED',
+}
+
+/** 阈值合法性：≥1 的有限整数（0/负数会让一切改动升 L1、浮点/字符串无意义）。 */
+function isValidThreshold(v) {
+  return typeof v === 'number' && Number.isInteger(v) && v >= 1
+}
+
+/**
+ * 合并 local.yaml quick-gate 段覆写与代码默认值（D-009）。
+ * @param {object} config local.yaml 解析结果（无 quick-gate 段 → 全默认；键非法回退默认并 warn）
+ * @returns {{ l1_span: number, l1_files: number, l2_span: number, l2_files_degraded: number }}
+ */
+export function resolveGateThresholds(config) {
+  const merged = {
+    l1_span: THRESHOLDS.L1_SPAN,
+    l1_files: THRESHOLDS.L1_FILES,
+    l2_span: THRESHOLDS.L2_SPAN,
+    l2_files_degraded: THRESHOLDS.L2_FILES_DEGRADED,
+  }
+  const section = config == null ? undefined : config['quick-gate']
+  if (section == null) return merged
+  if (typeof section !== 'object' || Array.isArray(section)) {
+    console.warn('[quick-gate] local.yaml quick-gate 段须为键值对象，已忽略（使用默认阈值）')
+    return merged
+  }
+  for (const [key, constName] of Object.entries(GATE_KEY_TO_THRESHOLD)) {
+    if (!(key in section)) continue
+    const v = section[key]
+    if (isValidThreshold(v)) merged[key] = v
+    else console.warn(`[quick-gate] local.yaml 配置键 quick-gate.${key}=${JSON.stringify(v)} 非法（须为 ≥1 整数），回退默认 ${THRESHOLDS[constName]}`)
+  }
+  return merged
+}
+
+// ── 计数口径判定（文档/测试/代码三分；口径见文件头注释） ──
+
+/** 文档文件口径：沿用 docSyncHint 的 isDoc（run/shared.js auditQuickCompletion 内 isDocFile 逐款同源）。 */
+function isDocPath(p) {
+  return p.endsWith('.md') || p.endsWith('.yaml') || p.endsWith('.yml') ||
+    p.startsWith('docs/') || p.startsWith('.sillyspec/docs/')
+}
+
+/** __tests__/ 或 tests/ 目录段（/test_ 前缀与命名判定在 isTestPath 内）。 */
+const TEST_DIR_RE = /(^|\/)(__tests__|tests)\//i
+
+/** 测试文件判定：目录段、basename test_ 前缀、.test./_test./.spec. 命名三信号任一命中。 */
+function isTestPath(p) {
+  if (TEST_DIR_RE.test(p)) return true
+  const base = p.slice(p.lastIndexOf('/') + 1)
+  if (/^test_/i.test(base)) return true
+  return /[._](test|spec)\.[^.]+$/i.test(base)
+}
+
+/** moduleIndex 兼容两种形态：parseModuleMapSimple 扁平 { id: {...} } 或 { modules: {...} } 包装；空 → null（degraded）。 */
+function resolveModulesObject(moduleIndex) {
+  if (moduleIndex == null || typeof moduleIndex !== 'object') return null
+  const wrapped = moduleIndex.modules
+  const obj = wrapped && typeof wrapped === 'object' && !Array.isArray(wrapped) ? wrapped : moduleIndex
+  return Object.keys(obj).length > 0 ? obj : null
+}
+
+/** 一级归属：paths/core_files 字面量或目录前缀命中（与 docs-debt matchFilesToModules 一级口径同款，纯内存零 IO）。 */
+function matchModuleForFile(posix, modulesObj) {
+  for (const [id, m] of Object.entries(modulesObj)) {
+    if (m == null || typeof m !== 'object') continue
+    const prefixes = [...(Array.isArray(m.paths) ? m.paths : []), ...(Array.isArray(m.core_files) ? m.core_files : [])]
+    for (const raw of prefixes) {
+      const p = String(raw).replace(/\\/g, '/').replace(/\/+$/, '')
+      if (!p) continue
+      if (posix === p || posix.startsWith(p + '/')) return id
+    }
+  }
+  return null
+}
+
+/** 卡片认领判定：模块 doc 字段（如 modules/core-engine.md）对应卡片文件在 changedFiles 内。
+ *  changedFiles 为仓库根相对路径（如 .sillyspec/docs/<project>/modules/core-engine.md），
+ *  本函数无 cwd/project 入参，按字面量或后缀对齐。 */
+function cardInFiles(doc, fileSet) {
+  const d = doc.replace(/\\/g, '/').replace(/^\.\//, '')
+  for (const f of fileSet) {
+    if (f === d || f.endsWith('/' + d)) return true
+  }
+  return false
+}
+
+/**
+ * quick 出口门禁画像（纯函数：无 IO、无子进程，moduleIndex/风险表/阈值全由参数或默认值）。
+ * @param {string[]} changedFiles 变更文件（CLI 审计链 git 事实；反斜杠自动归一 POSIX）
+ * @param {object|null} moduleIndex _module-map.yaml 解析结果（null/undefined/空 → degraded）
+ * @param {object} [opts]
+ * @param {Array<{pattern: string, re: RegExp}>} [opts.riskTable] 路径模式风险表（默认 QUICK_RISK_PATH_PATTERNS）
+ * @param {object} [opts.thresholds] 已合并阈值（resolveGateThresholds 产物；缺省用 THRESHOLDS，D-009）
+ * @param {Array<{path: string}>} [opts.fileNotes] --file-notes 解析结果（perFileNotes 覆盖率判定）
+ * @param {boolean} [opts.noDocs] --no-docs 显式豁免（docClaim → exempt-no-docs）
+ * @returns 画像对象（字段与判级规则见 design.md 接口定义）
+ */
+export function computeGateProfile(changedFiles, moduleIndex, opts = {}) {
+  const riskTable = Array.isArray(opts.riskTable) ? opts.riskTable : QUICK_RISK_PATH_PATTERNS
+
+  // 阈值：opts.thresholds 逐键取合法值，否则回 THRESHOLDS 默认（warn 责任在 resolveGateThresholds）
+  const th = {}
+  for (const [key, constName] of Object.entries(GATE_KEY_TO_THRESHOLD)) {
+    const v = opts.thresholds ? opts.thresholds[key] : undefined
+    th[key] = isValidThreshold(v) ? v : THRESHOLDS[constName]
+  }
+
+  const files = (Array.isArray(changedFiles) ? changedFiles : [])
+    .map((f) => String(f).replace(/\\/g, '/'))
+    .filter(Boolean)
+
+  const notedPaths = new Set(
+    (Array.isArray(opts.fileNotes) ? opts.fileNotes : [])
+      .filter((n) => n != null && typeof n.path === 'string' && typeof n.note === 'string' && n.note.trim() !== '')
+      .map((n) => n.path.replace(/\\/g, '/')),
+  )
+
+  const codeFiles = []
+  const testFiles = []
+  for (const f of files) {
+    if (isDocPath(f)) continue // 文档文件不计入两者、不参与归属与风险命中（口径见文件头）
+    if (isTestPath(f)) testFiles.push(f)
+    else codeFiles.push(f)
+  }
+
+  const modulesObj = resolveModulesObject(moduleIndex)
+  const degraded = modulesObj === null
+
+  // 模块归属（非文档文件 × paths/core_files 前缀聚类）；degraded 时不算，modules=[]、unmappedFiles=[]
+  const modules = []
+  const unmappedFiles = []
+  if (!degraded) {
+    const byModule = new Map()
+    for (const f of [...codeFiles, ...testFiles]) {
+      const id = matchModuleForFile(f, modulesObj)
+      if (id == null) { unmappedFiles.push(f); continue }
+      const entry = byModule.get(id)
+      if (entry) entry.files.push(f)
+      else byModule.set(id, { id, files: [f] })
+    }
+    modules.push(...byModule.values())
+  }
+  const moduleSpan = degraded ? null : modules.length
+
+  // 风险命中：非文档文件 × 路径模式表（v1 仅路径模式，无 diff 关键词维度；元素只含 pattern/file）
+  const riskHits = []
+  for (const f of [...codeFiles, ...testFiles]) {
+    for (const entry of riskTable) {
+      const re = entry == null ? null : entry.re
+      if (!(re instanceof RegExp)) continue
+      if (re.global) re.lastIndex = 0 // 防调用方传入 /g 正则跨文件携带 lastIndex 状态
+      if (re.test(f)) riskHits.push({ pattern: entry.pattern, file: f })
+    }
+  }
+
+  // 判级：正常态 span 参与；degraded 态 span 退出（L1=≥l1_files、L2=≥l2_files_degraded 或风险命中）
+  let level = 'L0'
+  if (degraded) {
+    if (files.length >= th.l2_files_degraded || riskHits.length > 0) level = 'L2'
+    else if (files.length >= th.l1_files) level = 'L1'
+  } else if (moduleSpan >= th.l2_span || riskHits.length > 0) level = 'L2'
+  else if (moduleSpan >= th.l1_span || files.length >= th.l1_files) level = 'L1'
+
+  // L1：--file-notes 覆盖率（changedFiles 全集均有非空注记 → true；`path::` 空括注不算——防形式化绕过；
+  // 空集空真 true——L0 不消费）
+  const perFileNotes = files.every((f) => notedPaths.has(f))
+
+  // L1 机械规则：codeFileCount ≥2 且 testFileCount===0 → missing；codeFileCount ≤1 → na；其余 ok
+  let testDelta
+  if (codeFiles.length <= 1) testDelta = 'na'
+  else if (testFiles.length === 0) testDelta = 'missing'
+  else testDelta = 'ok'
+
+  // L2：模块文档认领（触及模块中带 doc 卡片的模块，其卡片文件全在 changedFiles → claimed；
+  // 无带卡片的触及模块（含 degraded）→ 无可认领，空真 claimed 不出假 advisory；--no-docs 优先豁免）
+  let docClaim
+  if (opts.noDocs) docClaim = 'exempt-no-docs'
+  else {
+    const fileSet = new Set(files)
+    const claimable = modules.filter((e) => {
+      const m = modulesObj == null ? null : modulesObj[e.id]
+      return m != null && typeof m === 'object' && typeof m.doc === 'string' && m.doc.trim() !== ''
+    })
+    docClaim = claimable.every((e) => cardInFiles(modulesObj[e.id].doc, fileSet)) ? 'claimed' : 'missing'
+  }
+
+  // L2 风险命中：运行时证据要求（advisory 提示，不引入 quick 没有的 wait 机制）
+  const runtimeEvidence = riskHits.length > 0 ? 'required' : 'na'
+
+  return {
+    fileCount: files.length,
+    codeFileCount: codeFiles.length,
+    testFileCount: testFiles.length,
+    moduleSpan,
+    modules,
+    unmappedFiles,
+    riskHits,
+    level,
+    degraded,
+    checks: { perFileNotes, testDelta, docClaim, runtimeEvidence },
+  }
+}

package/src/quicklog.js

@@ -479,11 +479,17 @@ async function writeAtomic(filePath, content, opts = {}) {
   }
 }
 
-// 扫描所有 QUICKLOG-*.md（含轮转归档）当天最大 NNN + 已用 XXXX 后缀集
+// 扫描所有 QUICKLOG-*.md（含轮转归档）当天最大 NNN + 已用 XXXX 后缀集 + 当天已用全 ID 集
+// （坑 ql-id-double-occupancy 配套：全 ID 集供分配末检防整 ID 复用；容错正则见下）
 function scanExisting(quicklogDir, today) {
   let maxSeq = 0
   const usedSuffix = new Set()
+  const usedIds = new Set()
   const re = /^## ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})\b/gm
+  // 容错形态：手改/工具写入的畸形头（双空格、后缀紧贴 |）不匹配严格正则 → maxSeq 漏计 →
+  // 新分配复用同序号。第二正则只宽松空白，日期/序号/后缀结构仍须齐整；命中的序号并入
+  // maxSeq（防同序号双条目），全 ID 进 usedIds（防整 ID 复用）。引用字样（行首带前缀）不命中。
+  const reLoose = /^##[ \t]*ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})[ \t]*\|/gm
   // E22c：轮转归档按文件名日期过滤——归档名 = QUICKLOG-<user>-<YYYY-MM-DD>.md（最后条目日期），
   // 归档内全部条目 ≤ 名内日期；名内日期早于今天的归档不可能含当日条目，跳过读取
   // （O(全历史归档) → O(当日文件)，consumer 已 10 归档文件 756KB 时免全量扫描）。
@@ -493,16 +499,19 @@ function scanExisting(quicklogDir, today) {
     if (dm && dm[1] < todayDashed) continue // 早于今天的归档，必无当日条目
     let content = ''
     try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
-    let m
-    re.lastIndex = 0
-    while ((m = re.exec(content)) !== null) {
-      if (m[1] === today) {
-        maxSeq = Math.max(maxSeq, parseInt(m[2], 10))
-        usedSuffix.add(m[3].toLowerCase())
+    for (const reOne of [re, reLoose]) {
+      let m
+      reOne.lastIndex = 0
+      while ((m = reOne.exec(content)) !== null) {
+        if (m[1] === today) {
+          maxSeq = Math.max(maxSeq, parseInt(m[2], 10))
+          usedSuffix.add(m[3].toLowerCase())
+          usedIds.add(`ql-${today}-${m[2]}-${m[3].toLowerCase()}`)
+        }
       }
     }
   }
-  return { maxSeq, usedSuffix }
+  return { maxSeq, usedSuffix, usedIds }
 }
 
 // >500 行则轮转：rename QUICKLOG-<user>.md → QUICKLOG-<user>-<最后记录日期>.md
@@ -714,11 +723,128 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
 
 // ── 对外 API ──
 
+// 他者会话 guard 预留 ql-ID 的采集阈值：超龄会话的预留不再钉序号。与 run/shared.js
+// collectOtherQuickSessionDeclarations 的 FOREIGN_SESSION_STALE_MS 同口径（7 天）——正常并发
+// 会话间隔在分钟/小时级，7 天未收尾的会话按僵尸处理。本模块不 import run 层（分层：
+// run/* → quicklog，反向会成环），阈值在此独立声明。
+const GUARD_CLAIM_STALE_MS = 7 * 24 * 60 * 60 * 1000
+
+/**
+ * 采集当前库内各 quick 会话 guard.json 已预留的 ql-ID（坑 ql-id-double-occupancy）。
+ *
+ * quick 启动在锁内追加 QUICKLOG 条目后把 ql-ID 写入 guard.json。条目随后丢失（并行 git
+ * 操作回滚未提交 QUICKLOG / worktree 分裂合并等）时，QUICKLOG 扫描看不到该预留 → 下一个
+ * 会话分配复用同一序号（suffix 再撞上即整 ID 双占用，2026-09-13 实证 007-1351、历史
+ * 2026-06-04 001-7a4c 同款）。分配期对 guard 预留让位（allocateQuicklogEntry）、--done 期
+ * 对残留占用校验（complete-handlers）都以此为准。
+ *
+ * fail-open：目录不存在/损坏 guard.json/超龄僵尸/任何异常 → 跳过或空集，采集失败回到
+ * 无预留现状（不放大让位面）。
+ *
+ * @param {string} specBase .sillyspec 根目录
+ * @param {string|null} [sessionsDirHint] quick-sessions 目录（run 层经 resolveQuickSessionsDir
+ *   解析后传入；缺省 <specBase>/.runtime/quick-sessions）
+ * @param {number} [nowMs] 当前时间戳（可注入，测试用）
+ * @returns {Map<string, string[]>} qlId → 预留该 ID 的 sessionId 列表
+ */
+/**
+ * 遍历 quick-sessions 目录，按同一僵尸窗口口径读各会话 guard.json（collectGuardReservedQuicklogIds
+ * 与 collectActiveQuickGuardFiles 共用，活跃判定勿分叉）：guard.json 损坏/缺失 → guard=null 保留
+ * 条目（消费方各自决定跳过或视为空声明）；startedAt 可解析且超 GUARD_CLAIM_STALE_MS → 僵尸剔除。
+ *
+ * @param {string} dir quick-sessions 目录
+ * @param {number} [nowMs] 当前时间戳（可注入，测试用）
+ * @returns {Array<{sessionId: string, guard: object|null}>}
+ */
+function listQuickSessionGuards(dir, nowMs = Date.now()) {
+  const out = []
+  let sessionDirs = []
+  try {
+    sessionDirs = readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+  } catch { return out } // 目录不存在/不可读 → 无会话
+  for (const sessionName of sessionDirs) {
+    let guard = null
+    try { guard = JSON.parse(readFileSync(join(dir, sessionName, 'guard.json'), 'utf8')) } catch { guard = null } // 损坏/缺失 → null
+    if (guard && guard.startedAt) {
+      const startedAtMs = Date.parse(guard.startedAt)
+      if (Number.isFinite(startedAtMs) && nowMs - startedAtMs > GUARD_CLAIM_STALE_MS) continue // 僵尸不活跃
+    }
+    out.push({ sessionId: sessionName, guard })
+  }
+  return out
+}
+
+export function collectGuardReservedQuicklogIds(specBase, sessionsDirHint = null, nowMs = Date.now()) {
+  const out = new Map()
+  try {
+    const dir = sessionsDirHint || join(specBase, '.runtime', 'quick-sessions')
+    for (const { sessionId, guard } of listQuickSessionGuards(dir, nowMs)) {
+      if (!guard || typeof guard.quicklogId !== 'string' || !guard.quicklogId) continue
+      if (!out.has(guard.quicklogId)) out.set(guard.quicklogId, [])
+      out.get(guard.quicklogId).push(sessionId)
+    }
+  } catch { /* fail-open：采集失败等同无预留 */ }
+  return out
+}
+
+/**
+ * 采集各活跃 quick 会话 guard.json 声明的 allowedFiles（apply 前 guard 相交预检，FR-03 / D-002@v1）。
+ *
+ * 活跃口径与 collectGuardReservedQuicklogIds 同源（listQuickSessionGuards）：guard 目录存在即活跃
+ * （quick --done 完成时清理 guard 目录，完成态天然退出），超 7 天僵尸窗口（GUARD_CLAIM_STALE_MS，
+ * 异常残留不钉死）剔除。勿用 changes.last_active 判活跃（非周期心跳，D-002）。
+ *
+ * @param {string} specBase .sillyspec 根目录
+ * @param {{ excludeChange?: string|null, sessionsDir?: string|null, nowMs?: number }} [opts]
+ *   - excludeChange：排除自身 change 的 quick 会话——sessionId == changeName（quick 会话 id 即
+ *     change 名）或 guard.linkedChanges 显式关联该 change 的协作会话（自己人，非拦截面）
+ *   - sessionsDir：quick-sessions 目录（缺省 <specBase>/.runtime/quick-sessions）
+ *   - nowMs：当前时间戳（可注入，测试用）
+ * @returns {Map<string, string[]>} sessionId → guard.allowedFiles（无 guard/无声明 → 空数组；fail-open）
+ */
+export function collectActiveQuickGuardFiles(specBase, { excludeChange = null, sessionsDir = null, nowMs = Date.now() } = {}) {
+  const out = new Map()
+  try {
+    const dir = sessionsDir || join(specBase, '.runtime', 'quick-sessions')
+    for (const { sessionId, guard } of listQuickSessionGuards(dir, nowMs)) {
+      if (excludeChange && (sessionId === excludeChange
+        || (guard && Array.isArray(guard.linkedChanges) && guard.linkedChanges.includes(excludeChange)))) continue
+      const allowed = (guard && Array.isArray(guard.allowedFiles))
+        ? guard.allowedFiles.filter(f => typeof f === 'string' && f.length > 0)
+        : []
+      out.set(sessionId, allowed)
+    }
+  } catch { /* fail-open：采集失败等同无活跃 guard（不放大拦截面） */ }
+  return out
+}
+
+/**
+ * 数某 qlId 在所有 QUICKLOG-*.md 里的条目头出现次数（--done 占用校验用）。
+ * ≥2 = 分配竞态残留已损坏记录（同 ID 双条目）；容错空白形态与 scanExisting 的 reLoose 同口径。
+ * @returns {{count: number, files: string[]}} count=命中头总数；files=「文件名×次数」列表
+ */
+export function countQuicklogEntries(specBase, qlId) {
+  const out = { count: 0, files: [] }
+  if (!qlId || typeof qlId !== 'string') return out
+  const quicklogDir = join(specBase, 'quicklog')
+  if (!existsSync(quicklogDir)) return out
+  const re = new RegExp(`^##[ \\t]*${escapeRe(qlId)}[ \\t]*\\|`, 'gm')
+  for (const f of listQuicklogFiles(quicklogDir)) {
+    let content = ''
+    try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
+    const n = (content.match(re) || []).length
+    if (n > 0) { out.count += n; out.files.push(`${f}×${n}`) }
+  }
+  return out
+}
+
 /**
  * 分配 ql-ID 并写「进行中」条目 + 关联 tasks.md。持锁、当天唯一。
+ * 分配查重（坑 ql-id-double-occupancy）：盘上当天全 ID（含容错空白形态）+ 他者活跃会话
+ * guard 预留（sessionsDir）的序号一并让位，maxSeq 取三者最大后再 +1。
  * @returns {Promise<{qlId: string}>}
  */
-export async function allocateQuicklogEntry(specBase, gitUser, { description, linkedChanges = [], allowedFiles = [] } = {}) {
+export async function allocateQuicklogEntry(specBase, gitUser, { description, linkedChanges = [], allowedFiles = [], sessionsDir = null } = {}) {
   const quicklogDir = join(specBase, 'quicklog')
   mkdirSync(quicklogDir, { recursive: true })
   // git user.name 无字符限制，可含 / \ .. 等路径元字符（git config 或 .git/config 可控）——
@@ -737,19 +863,34 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
   // 自证），仅放弃「分配即推送」的顺序一致性（平台为 best-effort 面板，乱序窗口极小）。
   let pushPayload = null
   const { qlId } = await withFileLock(lockPath, async () => {
-    const { maxSeq, usedSuffix } = scanExisting(quicklogDir, today)
+    const { maxSeq: diskMaxSeq, usedSuffix, usedIds } = scanExisting(quicklogDir, today)
+    // 他者 guard 预留让位（坑 ql-id-double-occupancy）：同日预留序号并入 maxSeq；整 ID 进
+    // 末检集。QUICKLOG 条目丢失但 guard 仍在的窗口内，盘上扫描看不见该预留——正是
+    // 2026-09-13 007-1351 双占用的形态。
+    const claims = collectGuardReservedQuicklogIds(specBase, sessionsDir)
+    let maxSeq = diskMaxSeq
+    const claimedIds = new Set()
+    for (const [claimedId] of claims) {
+      claimedIds.add(claimedId.toLowerCase())
+      const cm = claimedId.match(/^ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})$/)
+      if (cm && cm[1] === today) maxSeq = Math.max(maxSeq, parseInt(cm[2], 10))
+    }
     const nextSeq = maxSeq + 1
-    // XXXX 4 位 hex 随机后缀（消歧；NNN 已在锁内顺序分配保证唯一，此处仅 belt-and-suspenders）
+    // XXXX 4 位 hex 随机后缀（消歧；NNN 已让位到所有已知占用之后，此处 belt-and-suspenders：
+    // usedSuffix 全日后缀避让 + 全 ID 末检，理论撞号需单日后缀空间耗尽，200 次兜底抛错）
     let suffix
+    let qlId
     let guard = 0
     do {
       suffix = randomBytes(2).toString('hex')
+      qlId = `ql-${today}-${String(nextSeq).padStart(3, '0')}-${suffix}`
       guard++
-    } while (usedSuffix.has(suffix) && guard < 100)
+    } while ((usedSuffix.has(suffix) || usedIds.has(qlId) || claimedIds.has(qlId)) && guard < 200)
+    if (usedIds.has(qlId) || claimedIds.has(qlId)) {
+      throw new Error('allocateQuicklogEntry: ql-ID 查重 200 次仍未命中空闲号（当日条目异常膨胀，请检查 quicklog/）')
+    }
 
     await rotateIfNeeded(userFile, user)
-
-    const qlId = `ql-${today}-${String(nextSeq).padStart(3, '0')}-${suffix}`
     const entry = [
       '',
       `## ${qlId} | ${nowDatetime()} | ${desc}`,
@@ -940,10 +1081,15 @@ export async function cancelQuickSession({ specBase, gitUser, qlId, sessionId =
   let quicklogFile = null
   let flipped = false
   await withFileLock(lockPath, async () => {
-    // 用户文件缺失时扫全部 QUICKLOG 文件（条目可能在别的 user 文件里，如 CI 场景 user 漂移）
-    const files = existsSync(join(quicklogDir, `QUICKLOG-${user}.md`))
-      ? [`QUICKLOG-${user}.md`]
-      : listQuicklogFiles(quicklogDir)
+    // 坑 quick-cancel-blind-after-quicklog-rotation（2026-09-16 实证）：主文件存在时旧逻辑
+    // 只扫主文件——轮转发生后历史条目在归档文件（QUICKLOG-<user>-<日期>.md）里永久不可达，
+    // 「提示清理 → 清理必失败」死循环。恒扫全部 QUICKLOG 文件（主文件优先，命中即停），
+    // 用户文件缺失的 CI user 漂移场景语义不变。
+    const allFiles = listQuicklogFiles(quicklogDir)
+    const mainFile = `QUICKLOG-${user}.md`
+    const files = existsSync(join(quicklogDir, mainFile))
+      ? [mainFile, ...allFiles.filter(f => f !== mainFile)]
+      : allFiles
     for (const f of files) {
       const p = join(quicklogDir, f)
       const content = existsSync(p) ? readFileSync(p, 'utf8') : ''

package/src/review-dispatch.js

@@ -197,7 +197,8 @@ export function persistStageReview({ runtimeRoot, stage, changeName, reviewRunId
     const h = computeDocHash(mainDocPath)
     if (h) review.docHash = h
   }
-  const schema = validateStageReviewSchema(review)
+  // ql-20260915-001 修复③：透传 stage——schema 错误文案给本 stage 期望 reviewType
+  const schema = validateStageReviewSchema(review, stage)
   if (!schema.ok) return { ok: false, errors: schema.errors }
   review.reviewedFiles = Array.isArray(review.reviewedFiles) && review.reviewedFiles.length > 0
     ? review.reviewedFiles