sillyspec 3.26.7 → 3.26.9

package/src/scan-diff.js

@@ -0,0 +1,388 @@
+/**
+ * scan-diff — scan 文档 vs 源码漂移清单（change: 2026-08-16-scan-diff-command, task-01）
+ *
+ * 定位：scan 文档是架构快照（基线 = 生成时源码 commit，frontmatter source_commit），源码持续演进。
+ * scan-diff 算出「基线之后源码变了什么、哪些模块的 scan 文档需要核对/刷新」，按四分类输出：
+ *   A         新增文件 → scan 文档缺记（缺文档）
+ *   D         已删除文件 → scan 文档多记（多文档）
+ *   M / R / C 修改 / 重命名 / 复制 → scan 文档过时
+ *   其余（T 等）→ unknown（不判漂移，只展示）
+ * 扫描范围缺省 = module-map paths 覆盖集（parseModuleMapSimple 收集全部 paths 去重），
+ * 非 src/-only——范围外的源码变更与模块文档无涉，不计入漂移。
+ *
+ * 分层：
+ *   computeScanDiff —— 计算层（git 只读 + frontmatter/module-map 读取；无渲染无落盘）。
+ *     硬错误返回 { ok:false, error }（无效 base / git 失败 / 无 source_commit）；
+ *     advisory 问题进 warnings（非祖先 base / rev-list 降级 / module-map 缺失）。
+ *   runScanDiff —— IO 面（终端聚合渲染 + --report 落盘 scan-diff-report.md），返回退出码。
+ *
+ * 复用（先读源码确认签名后使用）：parseSourceCommit（scan-staleness）、
+ *   matchFilesToModules（docs-debt，含裸名兜底）、safeGit（git-helper）、
+ *   parseModuleMapSimple（modules.js）；零新依赖。
+ */
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { safeGit } from './git-helper.js'
+import { parseSourceCommit } from './scan-staleness.js'
+import { matchFilesToModules } from './docs-debt.js'
+import { parseModuleMapSimple } from './modules.js'
+
+/** safeGit 超时（仿 docs-debt 的 GIT_TIMEOUT_MS 模式：大 diff 慢时降级不挂起） */
+const GIT_TIMEOUT_MS = 10000
+
+/** 每模块终端渲染默认上限（--full 展开全部） */
+const DEFAULT_LIST_CAP = 5
+
+/**
+ * 计算层：scan 文档 vs 源码漂移事实。
+ * @param {{ projectRoot: string, specBase: string, projectName: string, base?: string|null }} opts
+ *   projectRoot：git 锚（diff/rev-list 的 -C 目录）
+ *   specBase / projectName：scan 文档与 module-map 定位（specBase/docs/<projectName>/...）
+ *   base：基线 commit（短/长哈希、引用均可）；缺省读 scan 文档 frontmatter 的 source_commit
+ * @returns {{ ok: true, base, baseSource, head, behindCommits, daysSinceScan, scope,
+ *   added, deleted, modified, unknown, unmapped, outOfScope, renameMap, byModule, warnings, driftCount }
+ *   | { ok: false, error: string }}
+ *   ok:false = 硬错误（参数缺失 / 无 source_commit / 无效 base / git diff 失败）
+ *   added/deleted/modified/unknown：范围内变更文件（POSIX 相对路径；R/C 记新路径）
+ *   unmapped：范围内未匹配到模块的文件；outOfScope：范围外变更（不计入漂移）
+ *   renameMap：newPath → oldPath（R 归 modified 且保留 rename 细节）
+ *   byModule：{ moduleId: { doc, added, deleted, modified, files } }（A/D/M 计数 + 文件清单）
+ *   driftCount = added + deleted + modified
+ */
+export function computeScanDiff({ projectRoot, specBase, projectName, base } = {}) {
+  if (!projectRoot || !specBase || !projectName) {
+    return { ok: false, error: 'projectRoot / specBase / projectName 必填，缺一不可' }
+  }
+  const warnings = []
+  let baseSource = '--base 显式指定'
+
+  // ── 基线：缺省读 specBase/docs/<projectName>/scan/*.md frontmatter 的 source_commit ──
+  if (!base) {
+    const sourceCommit = readSourceCommit(specBase, projectName)
+    if (!sourceCommit) {
+      return {
+        ok: false, error:
+          'scan 文档无 source_commit 字段（绿地项目 / 旧版生成 / 无 scan 文档），无法定基线——请用 --base <commit> 显式指定基线',
+      }
+    }
+    base = sourceCommit
+    baseSource = 'scan 文档 frontmatter source_commit'
+  }
+  const baseDisplay = displayBase(base)
+
+  // ── base 有效性守卫（仿 computeScanStaleness 的 isAncestor 守卫）──
+  // merge-base --is-ancestor 对「无效 commit」与「有效但非祖先」都返回非 0（safeGit 记为 error），
+  // 无法直接区分——先用 rev-parse 验有效性：无效 → 报错；有效但非祖先 → 警告（diff 按两快照对比仍可算）。
+  const revRes = safeGit(projectRoot, ['rev-parse', '--verify', `${base}^{commit}`])
+  if (revRes.error || !revRes.value) {
+    return { ok: false, error: `基线 ${baseDisplay} 不是有效 commit（${revRes.error || '无输出'}），跳过 scan-diff` }
+  }
+  const resolvedBase = revRes.value.trim()
+  const headRes = safeGit(projectRoot, ['rev-parse', 'HEAD'])
+  const headShort = headRes.error ? 'HEAD' : headRes.value.trim().slice(0, 7)
+  const isAncestor = safeGit(projectRoot, ['merge-base', '--is-ancestor', resolvedBase, 'HEAD'])
+  if (isAncestor.error) {
+    warnings.push(`基线 ${baseDisplay} 不是 HEAD（${headShort}）祖先（rebase / 分支切换）——diff 按两快照对比，删除后重建可能呈假新增`)
+  }
+
+  // ── 落后计数（advisory：超时/失败降级 null，不抛）──
+  const countRes = safeGit(projectRoot, ['rev-list', '--count', `${resolvedBase}..HEAD`], { timeout: GIT_TIMEOUT_MS })
+  let behindCommits = countRes.error ? null : parseInt(countRes.value, 10)
+  if (behindCommits === null || Number.isNaN(behindCommits)) {
+    behindCommits = null
+    warnings.push('rev-list 计数失败（git 降级），behindCommits=null')
+  }
+  const dateRes = safeGit(projectRoot, ['log', '-1', '--format=%cI', resolvedBase])
+  let daysSinceScan = null
+  if (!dateRes.error && dateRes.value) {
+    daysSinceScan = Math.floor((Date.now() - new Date(dateRes.value.trim()).getTime()) / 86400000)
+  }
+
+  // ── 扫描范围：module-map paths 覆盖集（默认范围，非 src/-only）──
+  const cardsDir = join(specBase, 'docs', projectName, 'modules')
+  const mapPath = join(cardsDir, '_module-map.yaml')
+  let moduleIndex = null
+  if (existsSync(mapPath)) {
+    try { moduleIndex = parseModuleMapSimple(readFileSync(mapPath, 'utf8')) } catch { moduleIndex = null }
+  }
+  const scope = collectScope(moduleIndex)
+  if (scope.length === 0) {
+    warnings.push('module-map 缺失 / 解析为空（跑 sillyspec modules rebuild 生成）——扫描范围退化=全部变更文件，无法归模块')
+  }
+
+  // ── diff：只算路径（--find-renames 检出重命名；超时降级为错误返回）──
+  const diffRes = safeGit(projectRoot, ['diff', '--name-status', '--find-renames', `${resolvedBase}..HEAD`], { timeout: GIT_TIMEOUT_MS })
+  if (diffRes.error) {
+    return { ok: false, error: `git diff ${baseDisplay}..HEAD 失败（${diffRes.error}），跳过 scan-diff` }
+  }
+
+  // ── 四分类 + 范围过滤 ──
+  const added = [], deleted = [], modified = [], unknown = [], outOfScope = []
+  const renameMap = {} // newPath → oldPath（R 归 modified 且保留 rename 细节）
+  const scopeFilter = scope.length > 0 ? scope : null
+  for (const item of parseNameStatus(diffRes.value)) {
+    if (scopeFilter && !inScope(item.path, scopeFilter)) { outOfScope.push(item.path); continue }
+    switch (item.status) {
+      case 'A': added.push(item.path); break
+      case 'D': deleted.push(item.path); break
+      case 'M': modified.push(item.path); break
+      case 'R': modified.push(item.path); renameMap[item.path] = item.oldPath; break
+      case 'C': modified.push(item.path); break // 复制目标（新路径）视同过时
+      default: unknown.push(item.path); break // T / B 等
+    }
+  }
+
+  // ── 归模块（matchFilesToModules，含裸名兜底；结果 = 同文件清单直接调用一致）──
+  const inScopeFiles = [...added, ...deleted, ...modified, ...unknown]
+  let byModuleMap = new Map()
+  let unmapped = inScopeFiles
+  if (inScopeFiles.length > 0) {
+    try {
+      const matched = matchFilesToModules(inScopeFiles, moduleIndex || {}, { cardsDir })
+      byModuleMap = matched.byModule
+      unmapped = matched.unmapped
+    } catch {
+      warnings.push('matchFilesToModules 归模块失败（降级为全部未归模块）')
+    }
+  } else {
+    unmapped = []
+  }
+
+  // ── byModule 聚合 A/D/M 计数 ──
+  const addedSet = new Set(added)
+  const deletedSet = new Set(deleted)
+  const modifiedSet = new Set(modified)
+  const byModule = {}
+  for (const [id, entry] of byModuleMap) {
+    let a = 0, d = 0, m = 0
+    for (const f of entry.files) {
+      if (addedSet.has(f)) a++
+      else if (deletedSet.has(f)) d++
+      else if (modifiedSet.has(f)) m++
+    }
+    byModule[id] = { doc: entry.doc || '', added: a, deleted: d, modified: m, files: entry.files }
+  }
+
+  return {
+    ok: true,
+    base: baseDisplay,
+    baseSource,
+    head: headShort,
+    behindCommits,
+    daysSinceScan,
+    scope,
+    added, deleted, modified, unknown, unmapped, outOfScope,
+    renameMap,
+    byModule,
+    warnings,
+    driftCount: added.length + deleted.length + modified.length,
+  }
+}
+
+/**
+ * IO 面：终端渲染 + 可选落盘报告。
+ * @param {{ projectRoot: string, specBase: string, projectName: string, base?: string|null,
+ *   full?: boolean, report?: boolean }} opts
+ *   full：终端展开每模块全部文件（缺省每模块 ≤5 条）；report：落盘 scan-diff-report.md
+ * @returns {number} 退出码：0 无漂移 / 1 有漂移 / 2 错误（无效 base、git 失败、无 source_commit）
+ */
+export function runScanDiff(opts = {}) {
+  const { projectRoot, specBase, projectName, base = null, full = false, report = false } = opts
+  const result = computeScanDiff({ projectRoot, specBase, projectName, base })
+  if (!result.ok) {
+    console.error(`scan-diff：${result.error}`)
+    return 2
+  }
+  for (const w of result.warnings) console.warn(`  ⚠️ ${w}`)
+
+  console.log(`scan diff: ${result.base}..HEAD（${fmtNum(result.behindCommits)} commit / ${fmtNum(result.daysSinceScan)} 天）`)
+  if (result.driftCount === 0) {
+    console.log('scan 文档与源码一致（0 漂移）')
+    if (result.unknown.length > 0) {
+      console.log(`  无法归类（unknown）${result.unknown.length} 条：${result.unknown.join(', ')}`)
+    }
+  } else {
+    renderTerminal(result, { full })
+  }
+
+  if (report) {
+    const p = writeReport(result, { specBase, projectName })
+    if (p) console.log(`scan-diff 报告已落盘：${p}`)
+    else console.warn('  ⚠️ scan-diff-report.md 写入失败')
+  }
+  return result.driftCount > 0 ? 1 : 0
+}
+
+/** 终端聚合渲染：每模块计数 + 文件清单（缺省 ≤5 条，--full 展开全部） */
+function renderTerminal(r, { full }) {
+  const cap = full ? Number.MAX_SAFE_INTEGER : DEFAULT_LIST_CAP
+  console.log(`扫描范围：module-map paths 覆盖集（${r.scope.length} 条路径）——范围外的变更不计入漂移`)
+  const moduleIds = Object.keys(r.byModule).sort()
+  if (moduleIds.length > 0) {
+    console.log('按模块聚合漂移（A=缺文档 D=多文档 M=过时，--full 展开全部）：')
+    for (const id of moduleIds) {
+      const m = r.byModule[id]
+      const doc = m.doc ? `（${m.doc}）` : ''
+      console.log(`  [${id}] A${m.added} D${m.deleted} M${m.modified}${doc}`)
+      for (const f of m.files.slice(0, cap)) {
+        console.log(`    - ${statusLetter(r, f)} ${f}${r.renameMap[f] ? `（原 ${r.renameMap[f]}）` : ''}`)
+      }
+      if (m.files.length > cap) console.log(`    ... 其余 ${m.files.length - cap} 条，--full 展开`)
+    }
+  }
+  if (r.unmapped.length > 0) {
+    console.log(`未归模块（unmapped，${r.unmapped.length} 条）：`)
+    for (const f of r.unmapped.slice(0, cap)) {
+      console.log(`  - ${statusLetter(r, f)} ${f}`)
+    }
+    if (r.unmapped.length > cap) console.log(`  ... 其余 ${r.unmapped.length - cap} 条，--full 展开`)
+  }
+  if (r.unknown.length > 0) {
+    console.log(`无法归类（unknown，${r.unknown.length} 条）：${r.unknown.slice(0, cap).join(', ')}`)
+  }
+  console.log(`漂移合计：${r.driftCount} 条（A${r.added.length} / D${r.deleted.length} / M${r.modified.length}）`)
+}
+
+/** 文件归属状态字母（渲染用）：R（renameMap 命中）> A > D > M */
+function statusLetter(r, f) {
+  if (r.renameMap[f]) return 'R'
+  if (r.added.includes(f)) return 'A'
+  if (r.deleted.includes(f)) return 'D'
+  return 'M'
+}
+
+/** 落盘 scan-diff-report.md（markdown 完整清单，不截断） */
+function writeReport(r, { specBase, projectName }) {
+  const dir = join(specBase, 'docs', projectName, 'scan')
+  try { mkdirSync(dir, { recursive: true }) } catch { return null }
+  const lines = [
+    '# scan-diff 报告',
+    '',
+    `- 生成时间：${new Date().toISOString()}`,
+    `- 项目：${projectName}`,
+    `- 基线：${r.base}（${r.baseSource}）`,
+    `- 对比：\`${r.base}..HEAD\``,
+    `- 落后：${fmtNum(r.behindCommits)} commit / ${fmtNum(r.daysSinceScan)} 天`,
+    `- 扫描范围：module-map paths 覆盖集（${r.scope.length} 条路径）`,
+    '',
+    '## 漂移总览',
+    '',
+    '| 分类 | 含义 | 数量 |',
+    '| --- | --- | --- |',
+    `| added | 源码新增，scan 文档缺记 | ${r.added.length} |`,
+    `| deleted | 源码已删，scan 文档多记 | ${r.deleted.length} |`,
+    `| modified | 源码已变，scan 文档过时 | ${r.modified.length} |`,
+    `| unknown | 其他状态 | ${r.unknown.length} |`,
+    `| unmapped | 范围内未匹配模块 | ${r.unmapped.length} |`,
+    '',
+    '## 按模块聚合',
+    '',
+  ]
+  if (Object.keys(r.byModule).length === 0) {
+    lines.push('（无模块命中）', '')
+  } else {
+    for (const id of Object.keys(r.byModule).sort()) {
+      const m = r.byModule[id]
+      lines.push(`### ${id}（${m.doc || '无 doc'}）`, '')
+      lines.push(`- added：${m.added}`, `- deleted：${m.deleted}`, `- modified：${m.modified}`, '- 文件：')
+      for (const f of m.files) {
+        const ren = r.renameMap[f] ? `，原 ${r.renameMap[f]}` : ''
+        lines.push(`  - \`${f}\`（${statusLetter(r, f)}${ren}）`)
+      }
+      lines.push('')
+    }
+  }
+  if (r.unmapped.length > 0) {
+    lines.push('## 未归模块（unmapped）', '')
+    for (const f of r.unmapped) lines.push(`- \`${f}\``)
+    lines.push('')
+  }
+  if (r.outOfScope.length > 0) {
+    lines.push('## 范围外变更（不计入漂移）', '')
+    for (const f of r.outOfScope) lines.push(`- \`${f}\``)
+    lines.push('')
+  }
+  if (r.warnings.length > 0) {
+    lines.push('## 提示', '')
+    for (const w of r.warnings) lines.push(`- ${w}`)
+    lines.push('')
+  }
+  lines.push('## 结论', '')
+  lines.push(`- 漂移合计：${r.driftCount} 条（A${r.added.length} / D${r.deleted.length} / M${r.modified.length}）`)
+  if (r.driftCount === 0) {
+    lines.push('- scan 文档与源码一致（0 漂移）')
+  } else {
+    lines.push('- 存在漂移：请按需核对并刷新对应 scan 文档（sillyspec run scan）')
+  }
+  lines.push('')
+  lines.push('> 由 sillyspec scan-diff 自动生成；改动源码后请按需核对 scan 文档。')
+  const outPath = join(dir, 'scan-diff-report.md')
+  try {
+    writeFileSync(outPath, lines.join('\n') + '\n', 'utf8')
+    return outPath
+  } catch {
+    return null
+  }
+}
+
+/** 读 scan 目录任一 .md 的 source_commit（同 modules.js 写入同值，取首个命中；全失败 → null） */
+function readSourceCommit(specBase, projectName) {
+  const scanDir = join(specBase, 'docs', projectName, 'scan')
+  if (!existsSync(scanDir)) return null
+  try {
+    for (const f of readdirSync(scanDir)) {
+      if (!f.endsWith('.md')) continue
+      const c = parseSourceCommit(readFileSync(join(scanDir, f), 'utf8'))
+      if (c) return c
+    }
+  } catch { /* 读失败 → null */ }
+  return null
+}
+
+/** 收集 module-map 全部 paths 去重（归一 Windows 反斜杠 + 去尾部斜杠；无 paths → 空数组） */
+function collectScope(moduleIndex) {
+  const set = new Set()
+  for (const m of Object.values(moduleIndex || {})) {
+    if (!Array.isArray(m.paths)) continue
+    for (const raw of m.paths) {
+      if (typeof raw !== 'string' || !raw) continue
+      set.add(raw.replace(/\\/g, '/').replace(/\/+$/, ''))
+    }
+  }
+  return [...set]
+}
+
+/** 路径是否落在范围（p 可为目录或文件：精确相等或目录前缀） */
+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) {
+  const items = []
+  if (!out) return items
+  for (const line of out.split('\n')) {
+    const l = line.replace(/\r$/, '')
+    if (!l) continue
+    const tab = l.indexOf('\t')
+    if (tab === -1) continue
+    const m = l.slice(0, tab).match(/^([A-Z])(\d*)$/)
+    if (!m) continue
+    const status = m[1]
+    const parts = l.slice(tab + 1).split('\t')
+    const item = { status, path: parts[parts.length - 1] }
+    if ((status === 'R' || status === 'C') && parts.length >= 2) item.oldPath = parts[0]
+    items.push(item)
+  }
+  return items
+}
+
+/** 40 位全哈希缩成 7 位显示；引用/短哈希原样 */
+function displayBase(b) {
+  return /^[0-9a-f]{40}$/i.test(b) ? b.slice(0, 7) : b
+}
+
+/** null/NaN → '?'（降级显示） */
+function fmtNum(n) {
+  return n === null || Number.isNaN(n) ? '?' : String(n)
+}

package/src/scan-staleness.js

@@ -0,0 +1,95 @@
+/**
+ * scan-staleness — scan 文档新鲜度提示（债单 D-7 方案 A，change: 2026-08-15 ql-20260815-013；
+ * 2026-08-16 ql-20260816-009-fb44 修正判定语义）
+ *
+ * 原则（doc-consistency-debt 第六节用户裁决）：CLI 算事实注入——git 算出 scan 文档落后程度，
+ * 注入给 agent 的是一行结论不是一段劝说指令。brainstorm「加载项目上下文」读 scan 文档前
+ * 就知道"我读的 scan 文档可能没跟上近期结构变更"，按提示核对或重扫，而非盲信。
+ *
+ * 判定语义（2026-08-16 修正，与第七节「behind 计数不参与判定」对齐）：source_commit vs HEAD
+ * 的 `rev-list --count` 落后数只是「建议核对/重扫」的提示信号（旧快照可能未收录近期新增模块），
+ * 不是「文档失效/失真」的判据——文档引用是否失效由 docs-check（直接信号，src/docs-check.js）
+ * 负责，与 docs-gate 原则一致。status 三态 fresh / needs-refresh / unknown：needs-refresh =
+ * 该刷新/核对，不是文档判错。
+ *
+ * 纯读操作（git 只读 + frontmatter 解析），任何失败降级 null/unknown（advisory 信号不阻断流程）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { safeGit } from './git-helper.js'
+
+/** 刷新提示阈值（commit 数 / 天数，超过任一即 needs-refresh；advisory 提示允许保守默认） */
+export const STALENESS_THRESHOLDS = { commits: 50, days: 14 }
+
+/**
+ * 纯函数：从 scan 文档内容解析 frontmatter 的 source_commit。
+ * @param {string} content 文档全文
+ * @returns {string|null} commit hex（短/长均可）；无字段/无 frontmatter → null
+ */
+export function parseSourceCommit(content) {
+  if (!content || typeof content !== 'string') return null
+  // \r? 容错 CRLF（$ 前的 \r 会致 LF 正则失配）
+  const m = content.match(/^---\r?\n[\s\S]*?^source_commit:\s*([0-9a-f]{7,40})\s*\r?$/m)
+  return m ? m[1] : null
+}
+
+/**
+ * 计算单个 project 的 scan 文档漂移事实。
+ * @param {{ projectRoot: string, specBase: string, projectName: string, thresholds?: { commits: number, days: number } }} opts
+ * @returns {{ status: 'fresh'|'needs-refresh'|'unknown', behindCommits: number|null, daysSinceScan: number|null, sourceCommit: string|null, message: string }|null}
+ *   null = 无 scan 文档目录（绿地项目等），调用方直接跳过；unknown = 有文档但算不出（无
+ *   source_commit 字段 / git 失败），message 说明降级原因。
+ */
+export function computeScanStaleness(opts) {
+  const { projectRoot, specBase, projectName, thresholds = STALENESS_THRESHOLDS } = opts || {}
+  if (!projectRoot || !specBase || !projectName) return null
+  const scanDir = join(specBase, 'docs', projectName, 'scan')
+  if (!existsSync(scanDir)) return null
+
+  // 任一 scan 文档带 source_commit 即可代表整批（modules.js 同批写入同值）
+  let sourceCommit = null
+  let checked = 0
+  for (const f of readdirSync(scanDir)) {
+    if (!f.endsWith('.md')) continue
+    checked++
+    const c = parseSourceCommit(readFileSync(join(scanDir, f), 'utf8'))
+    if (c) { sourceCommit = c; break }
+  }
+  if (checked === 0) return null
+  if (!sourceCommit) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit: null,
+      message: 'scan 文档无 source_commit 字段（旧版生成），无法算漂移提示——文档引用是否失效以 docs check 为准；如架构已大改建议重跑 sillyspec run scan --standard' }
+  }
+
+  const head = safeGit(projectRoot, ['rev-parse', 'HEAD'])
+  if (head.error || !head.value) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit,
+      message: `git 读取失败（${head.error || '无 HEAD'}），跳过漂移判定` }
+  }
+  const isAncestor = safeGit(projectRoot, ['merge-base', '--is-ancestor', sourceCommit, head.value.trim()])
+  if (isAncestor.error) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit,
+      message: `source_commit ${sourceCommit.slice(0, 7)} 不在当前分支历史（分支切换/rebase），跳过漂移判定` }
+  }
+  const countRes = safeGit(projectRoot, ['rev-list', '--count', `${sourceCommit}..HEAD`])
+  const behindCommits = countRes.error ? null : parseInt(countRes.value, 10)
+  if (behindCommits === null || Number.isNaN(behindCommits)) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit,
+      message: 'rev-list 计数失败，跳过漂移判定' }
+  }
+  const dateRes = safeGit(projectRoot, ['log', '-1', '--format=%cI', sourceCommit])
+  const daysSinceScan = dateRes.error ? null
+    : Math.floor((Date.now() - new Date(dateRes.value.trim()).getTime()) / 86400000)
+
+  const stale = behindCommits >= thresholds.commits || (daysSinceScan !== null && daysSinceScan >= thresholds.days)
+  if (!stale) {
+    return { status: 'fresh', behindCommits, daysSinceScan, sourceCommit,
+      message: `scan 文档无需刷新（落后 ${behindCommits} commit / ${daysSinceScan ?? '?'} 天，低于提示阈值）` }
+  }
+  return {
+    status: 'needs-refresh', behindCommits, daysSinceScan, sourceCommit,
+    message: `⚠️ scan 文档已落后源码 ${behindCommits} commit / ${daysSinceScan ?? '?'} 天（基线 ${sourceCommit.slice(0, 7)}）。` +
+      `落后数≠文档错误——文档引用是否失效由 docs check 判定；旧快照可能未收录近期新增模块/流程，` +
+      `涉及结构/模块判断建议核对源码，或跑 sillyspec run scan --standard --force-rescan 刷新基线`,
+  }
+}

package/src/stage-contract-spec.js

@@ -39,7 +39,7 @@ import { hasAllSections, hasNoPlaceholderLine, lineCount, meetsMinLines, missing
 import { SCAN_REQUIRED_DOCS } from './constants.js'
 
 // custom kind 集合:判定算法留在各 validator(复杂条件),引擎跳过不计入 errors/warnings。
-export const CUSTOM_KINDS = new Set([
+const CUSTOM_KINDS = new Set([
   'lifecycle-exemption',     // design.md 生命周期关键词触发 + 多层豁免(validateBrainstormOutputs)
   'entry-point-wiring',      // design.md 入口实例化 → task allowed_paths 覆盖对账(validatePlanOutputs)
   'id-traceability',         // FR/D 引用追踪(extractIds / warnMissingIds)
@@ -47,6 +47,7 @@ export const CUSTOM_KINDS = new Set([
   'cross-task-contract',     // task 卡片 provides/expects_from 对账(plan-postcheck)
   'design-file-coverage',    // design.md 文件清单 vs allowed_paths 覆盖(plan-postcheck)
   'task-id-continuity',      // task-NN id 连续性
+  'task-plan-reconciliation', // plan.md 声明任务 ↔ tasks/ 卡片双向对账(plan-postcheck)
   'design-readiness',        // design.md 进入 plan 前的章节就绪检查(validateDesignForPlan)
   'task-card-fields',        // task-NN.md 卡片字段存在性(validateBlueprintConsistency + validatePlanFeasibility)
   'verify-conclusion-gate',  // verify-result.md 结论 PASS/FAIL 门控
@@ -321,6 +322,20 @@ const PLAN_RULES = [
     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「不修改文件」章节说明不改原因。',
   },
+  // task-plan-reconciliation(custom):plan.md 声明任务 ↔ tasks/ 卡片双向对账（债单 D-2b）。
+  // 修复场景：plan 列 17 个任务只生成 12 张卡（尾部文档同步类任务漏卡），execute 审计只看
+  // 卡片 → 漏卡任务零失败信号（sillyhub conversation-driven T-13~T-17 实证）。
+  // ${declared}/${cards} replaceAll。
+  {
+    id: 'plan.task-plan-reconciliation', stage: 'plan', source: 'validateBlueprintConsistency', severity: 'error', kind: 'task-plan-reconciliation',
+    target: { root: 'change', path: 'tasks' },
+    data: {
+      messageMissingCards: 'plan.md 声明了 ${declared} 个任务，但 tasks/ 只有部分卡片。缺卡: ${missing}\n   无卡片的任务不进 Wave、不受 execute 审计（allowed_paths/review.json 都不覆盖）→ 必然漏做（典型：尾部文档同步类任务）。\n   修复：为每个缺卡任务补 task-NN.md（含 allowed_paths/验收标准），或从 plan.md 删除该任务。',
+      messageOrphanCards: 'tasks/ 存在 plan.md 未声明的卡片: ${orphans}\n   这些任务不进任何 Wave，execute 不会执行。修复：在 plan.md 补声明，或删除孤儿卡片。',
+    },
+    spec: 'plan.md 中声明的每个 task-NN 必须有对应 tasks/task-NN.md 卡片（反向亦然），否则阻断——无卡片任务不受 execute 审计，必然漏做。',
+    failMessage: 'plan.md 任务与 tasks/ 卡片不对账',
+  },
   // task-id-continuity(custom):task-NN id 从 task-01 起连续。算法留 validatePlanFeasibility。
   // ${expected}/${actual} replaceAll(零填充 2 位)。
   {

package/src/stage-contract.js

@@ -12,6 +12,7 @@ import { detectChangeRisk, checkIntegrationEvidence, VERIFICATION_NEEDS, RISK_LE
 import { SCAN_REQUIRED_DOCS, AUXILIARY_STAGES } from './constants.js'
 import { evaluateRules } from './stage-contract-engine.js'
 import { getRule } from './stage-contract-spec.js'
+import { parseAllowedPaths } from './stages/plan-postcheck.js'
 
 /**
  * 校验结果
@@ -381,11 +382,13 @@ function validatePlanOutputs(cwd, changeName, context = {}) {
         const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/i.test(f))
         for (const taskFile of taskFiles) {
           const taskContent = readFileSync(join(tasksDir, taskFile), 'utf8')
-          const allowedSection = taskContent.match(/allowed_paths:\s*\n((?:\s+-\s+.+\n?)+)/)
-          if (allowedSection) {
-            const paths = allowedSection[1].match(/-\s+(.+)/g) || []
-            for (const p of paths) allAllowedPaths.add(p.replace(/^-\s+/, '').trim().toLowerCase())
-          }
+          // 复用 parseAllowedPaths（坑6①：认 inline 数组/缩进块/顶格块 + 剥反引号 + CRLF 归一，
+          // 消除此处内联正则与 plan-postcheck 的解析漂移）。卡片无 frontmatter 时退全文扫描
+          // （包裹伪 frontmatter 复用同一解析器）——原内联正则是全文匹配语义，entry-point-wiring
+          // 只关心路径覆盖，卡片格式合法性归 plan-postcheck 把关，此处不收紧。
+          const paths = parseAllowedPaths(taskContent)
+          const effective = paths.length > 0 ? paths : parseAllowedPaths(`---\n${taskContent}\n---`)
+          for (const p of effective) allAllowedPaths.add(p.toLowerCase())
         }
       }
       // 也从 plan.md 文件变更清单中收集

package/src/stage-review.js

@@ -21,7 +21,7 @@ import { detectSpecDirTypo } from './spec-dir-typo.js'
 import { resolveRuntimeRoot } from './run/shared.js'
 
 // 文档型 stage review 的合法 reviewType
-export const STAGE_REVIEW_TYPES = ['design', 'plan', 'proposal', 'code', 'acceptance']
+const STAGE_REVIEW_TYPES = ['design', 'plan', 'proposal', 'code', 'acceptance']
 
 // checklist 每项 result 的合法值
 const CHECKLIST_RESULTS = ['pass', 'gap', 'fail']

package/src/stages/brainstorm-auto.js

@@ -66,7 +66,6 @@ export const definition = {
       maxWaitRounds: 5,
       waitReason: '等待用户回答需求问题',
       waitOptions: ['回答见--answer', '信息够了，进入设计'],
-      waitFreeAnswer: true, // 开放回答型：--answer 内容为自由文本（需求澄清回答），非封闭单选，豁免 enforceWaitChoice
       prompt: `分析需求，必要时追问，然后设计方案。
 
 ### 操作

package/src/stages/brainstorm.js

@@ -32,6 +32,7 @@ export const definition = {
 
 ### 操作
 1. 读取项目总览 \`{SPEC_ROOT}/docs/<project>/scan/PROJECT.md\` + 共享规范 + 子项目上下文
+   - 漂移事实（CLI 算）：{SCAN_STALENESS}
 2. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`
 3. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`
 4. 棕地项目：读取 {SPEC_ROOT}/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
@@ -79,7 +80,6 @@ export const definition = {
       maxWaitRounds: 8,
       waitReason: '等待用户回答需求问题或澄清',
       waitOptions: ['回答见--answer', '信息够了，进入方案讨论'],
-      waitFreeAnswer: true, // 开放回答型：--answer 内容为自由文本（需求澄清回答），非封闭单选，豁免 enforceWaitChoice
       prompt: `通过对话探索需求细节、分析原型（如有）、判断拆分/批量、并对歧义点做需求澄清 Grill。本步骤合并了原有的对话探索、原型分析、需求范围评估、需求澄清 Grill 四个环节——按下方 A→D 顺序按需执行。提问遵守「一次只问一个」（见 D 节追问策略）：必须问的问题逐个问，能查代码/文档解决的不问；不要把多个歧义打包成一屏清单一次抛给用户（用户记不住、答不全，反而漏掉关键约束）；也不要为凑数把单个问题拖成多轮。
 
 ### A. 原型/设计图分析（如用户提供）
@@ -330,8 +330,8 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - 长期术语只在 archive/scan 时再提升到 \`{SPEC_ROOT}/docs/<project>/glossary.md\`
 4. 格式自检（只查章节齐全；语义一致性/可行性/YAGNI 不在本步查，交给下一步 Design Grill 独立审查）：
    - design.md 含全部必填章节（背景/设计目标/非目标/总体方案/文件变更清单/接口定义/风险登记）
-   - design.md 头部 YAML frontmatter 字段齐全（author/created_at/scale 等）——step8 完成契约硬要求，审查前就补齐避免后续 docHash 漂移
-   - design.md 含「自审」字面命中章节（自审 / Self-Review / Self-review）——step8 完成契约 brainstorm.design.self-review 硬要求，写在本步自审段即可
+   - design.md 头部 YAML frontmatter 字段齐全（author/created_at/scale 等）——「生成规范文件」步完成契约硬要求，审查前就补齐避免后续 docHash 漂移
+   - design.md 含「自审」字面命中章节（自审 / Self-Review / Self-review）——「生成规范文件」步完成契约 brainstorm.design.self-review 硬要求，写在本步自审段即可
    - 如存在 decisions.md，design.md 是否引用所有当前版本 D-xxx@vN
    - 涉及 session/lease/agent_run/daemon/lifecycle 等关键词时，是否含「生命周期契约表」
 5. 缺章节 → 补齐后重检；章节齐全 → 进入下一步（Design Grill 做语义层交叉审查）