sillyspec 3.27.11 → 3.28.0

package/.claude/worktrees/sillyspec-data-model-research/src/scan-postcheck.js

@@ -1,512 +0,0 @@
-/**
- * scan-postcheck.js — CLI 层 scan 完成后强制校验
- *
- * 不依赖 AI agent 的自检报告，由 CLI 代码直接检查文件系统。
- * 平台模式下必须通过所有 check 才能 success，否则降级。
- */
-
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, renameSync, rmdirSync } from 'fs'
-import { join, basename } from 'path'
-import { SCAN_STATUS, CHECK_SEVERITY, SCAN_REQUIRED_DOCS, SCAN_REQUIRED_DOCS_QUICK } from './constants.js'
-import { validateScriptCommands } from './stages/cmd-existence.js'
-import { git } from './git-helper.js'
-import { nowWallClock } from './datetime.js'
-
-const REQUIRED_SCAN_DOCS = SCAN_REQUIRED_DOCS
-
-/**
- * @param {object} opts
- * @param {string} opts.cwd - 源码项目根目录 (source_root)
- * @param {string} opts.specDir - 规范目录 (spec-root)，null 时为非平台模式
- * @param {string} [opts.outputText] - 最后一步（自检）的 AI 输出文本
- * @param {object} [opts.scanMeta] - scan 元数据（由 runCommand 传入）
- * @param {boolean} [opts.scanMeta.projectListParsed] - Step 2 项目列表是否成功解析
- * @param {boolean} [opts.scanMeta.manifestWritten] - manifest.json 是否写入成功
- * @param {number} [opts.scanMeta.projectCount] - 实际展开的项目数量
- * @returns {{ status: 'success'|'completed_with_warnings'|'failed_post_check', checks: Array<{name, severity, detail}> }}
- */
-export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {}, scanProfile = null } ) {
-  const isPlatform = !!specDir
-  // profile 感知：quick 档只要求 4 份核心文档，否则要求完整 7 份。
-  // 否则 quick 扫描（--quick 显式 或 小项目自动判定）在平台模式会因缺 INTEGRATIONS/TESTING/CONCERNS 直接判 failed。
-  const mode = scanProfile?.mode || null
-  const requiredDocs = mode === 'quick' ? SCAN_REQUIRED_DOCS_QUICK : SCAN_REQUIRED_DOCS
-  const checks = []
-
-  if (!isPlatform) {
-    // 非平台模式：只做轻量检查
-    const localSpec = join(cwd, '.sillyspec')
-    const scanDir = join(localSpec, 'docs', basename(cwd), 'scan')
-
-    // 检查必需文档是否存在（quick profile 按 4 份清单，否则 7 份）
-    const missing = requiredDocs.filter(f => !existsSync(join(scanDir, f)))
-    if (missing.length > 0) {
-      checks.push({ name: 'missing_docs', severity: CHECK_SEVERITY.WARNING, detail: `缺少 ${missing.length} 份 scan 文档（${mode || 'full'} profile）: ${missing.join(', ')}` })
-    }
-    if (mode === 'quick') {
-      checks.push({ name: 'quick_profile_notice', severity: CHECK_SEVERITY.WARNING, detail: 'quick scan：仅生成 4 份核心文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE），深度扫描待补齐' })
-    }
-
-    const hasWarning = checks.some(c => c.severity === 'warning')
-    return { status: hasWarning ? 'completed_with_warnings' : 'success', checks }
-  }
-
-  // ── 平台模式：严格检查 ──
-
-  const projectName = basename(cwd)
-
-  // 1. source_root 污染检查（docs/projects/workflows/knowledge/manifest/local）
-  const pollutePaths = ['docs', 'projects', 'workflows', 'knowledge']
-  const polluteFiles = ['manifest.json', 'local.yaml']
-  for (const sub of pollutePaths) {
-    const localSub = join(cwd, '.sillyspec', sub)
-    if (existsSync(localSub)) {
-      try {
-        const leaked = readdirSync(localSub, { recursive: true }).filter(e => String(e).endsWith('.md') || String(e).endsWith('.yaml') || String(e).endsWith('.json'))
-        if (leaked.length > 0) {
-          checks.push({
-            name: sub === 'docs' ? 'source_root_docs_leak' : 'source_root_leak',
-            severity: CHECK_SEVERITY.FAILED,
-            detail: `source_root/.sillyspec/${sub}/ 下存在 ${leaked.length} 个文件（${localSub}/），agent 写入到了错误路径`
-          })
-        }
-      } catch {}
-    }
-  }
-  for (const file of polluteFiles) {
-    const filePath = join(cwd, '.sillyspec', file)
-    if (existsSync(filePath)) {
-      checks.push({
-        name: 'source_root_leak',
-        severity: CHECK_SEVERITY.FAILED,
-        detail: `source_root/.sillyspec/${file} 存在，agent 写入到了错误路径（${filePath}）`
-      })
-    }
-  }
-
-  // 2. spec_root 检查必需文档（quick profile 按 4 份清单，否则 7 份）
-  const specScanDir = join(specDir, 'docs', projectName, 'scan')
-  const missingDocs = requiredDocs.filter(f => !existsSync(join(specScanDir, f)))
-  if (missingDocs.length > 0) {
-    checks.push({
-      name: missingDocs.length === requiredDocs.length ? 'all_docs_missing' : 'partial_docs_missing',
-      severity: CHECK_SEVERITY.FAILED,
-      detail: missingDocs.length === requiredDocs.length
-        ? `spec_root 下无任何 scan 文档（${specScanDir}/），扫描可能未执行`
-        : `spec_root 缺少必需文档: ${missingDocs.join(', ')}（${mode === 'quick' ? 'quick profile 要求 4 份核心文档' : '7 份 scan 文档均为 required'}）`
-    })
-  }
-  if (mode === 'quick') {
-    checks.push({ name: 'quick_profile_notice', severity: CHECK_SEVERITY.WARNING, detail: 'quick scan：仅生成 4 份核心文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE），深度扫描待补齐' })
-  }
-
-  // 3. 检查文档 header（author / created_at）— 只看文件头部，避免正文出现同名词被误判
-  const existingDocs = requiredDocs.filter(f => existsSync(join(specScanDir, f)))
-  const docsMissingHeader = []
-  for (const doc of existingDocs) {
-    const content = readFileSync(join(specScanDir, doc), 'utf8')
-    const headerSlice = content.slice(0, 512)
-    if (!/author\s*:/.test(headerSlice) || !/created_at\s*:/.test(headerSlice)) {
-      docsMissingHeader.push(doc)
-    }
-  }
-  if (docsMissingHeader.length > 0) {
-    checks.push({
-      name: 'docs_missing_header',
-      severity: CHECK_SEVERITY.WARNING,
-      detail: `${docsMissingHeader.length} 份文档缺少 author/created_at: ${docsMissingHeader.join(', ')}（sillyspec scan-fix-headers 一键补齐）`
-    })
-  }
-
-  // 4. local.yaml 校验
-  const localYamlPath = join(specDir, 'local.yaml')
-  if (existsSync(localYamlPath)) {
-    const yamlContent = readFileSync(localYamlPath, 'utf8')
-    // 改调共享 validateScriptCommands（H2，去重 plan/scan 两处命令校验）。
-    // 严重度维持 WARNING（design D-04：scan 阶段保守，local.yaml 命令误报不阻断 init）；
-    // 不传 modules → 仅查根 package.json，与历史行为一致（monorepo 子包感知由 plan-postcheck 启用）。
-    // 仅校验 `npm|pnpm|yarn run <script>` 这类可静态对账的命令；install/typecheck/npx 等直接
-    // 包管理器调用不在范围（沿用 cmd-existence.js:126-129 注释立场，正则天然不匹配它们）。
-    const { invalid } = validateScriptCommands(yamlContent, { projectRoot: cwd })
-    if (invalid.length > 0) {
-      checks.push({
-        name: 'local_config_invalid',
-        severity: CHECK_SEVERITY.WARNING,
-        detail: `local.yaml 引用不存在的命令: ${invalid.map(i => `${i.cmd} (${i.reason})`).join('; ')}`
-      })
-    }
-  }
-
-  // 5. 检查 AI 输出中的真实错误标记
-  // 注意：不对 agent 描述性文本做全文正则匹配，防止误报。
-  // 只检测明显是 agent 运行时失败的信号（未被捕获的错误块），
-  // 而非 agent 正常描述中提到这些词。
-  if (outputText) {
-    // 5a: 检测未被恢复的 API 错误（连续多次、非描述性提及）
-    const apiErrorCount = (outputText.match(/API Error\b.*?\b529\b/gi) || []).length
-    if (apiErrorCount >= 2) {
-      checks.push({ name: 'api_error_529', severity: CHECK_SEVERITY.WARNING, detail: 'AI 输出中包含多次 API Error 529' })
-    }
-    const rateLimitCount = (outputText.match(/rate.?limit.*?exhausted/gi) || []).length
-    if (rateLimitCount >= 2) {
-      checks.push({ name: 'rate_limit_exhausted', severity: CHECK_SEVERITY.WARNING, detail: 'AI 输出中包含多次 rate_limit exhausted' })
-    }
-    // tool_use_error 和 fallback 已移除：agent 描述性文本中正常提及这些词
-    // 不应触发 warning。真正的问题会通过文档缺失、manifest 失败等其他检查捕获。
-  }
-
-  // 6. manifest 写入状态检查
-  if (scanMeta.manifestWritten === false) {
-    checks.push({
-      name: 'manifest_write_failed',
-      severity: CHECK_SEVERITY.FAILED,
-      detail: 'manifest.json 写入失败，平台无法消费 scan 结果'
-    })
-  }
-
-  // 7. 项目列表解析状态检查
-  if (scanMeta.projectListParsed === false) {
-    checks.push({
-      name: 'project_list_parse_failed',
-      severity: CHECK_SEVERITY.WARNING,
-      detail: 'Step 2 项目列表解析失败，回退到注册项目列表，可能遗漏子项目'
-    })
-  }
-
-  // 7.5 knowledge 产物校验
-  const knowledgeDir = join(specDir, 'knowledge')
-  if (existsSync(knowledgeDir)) {
-    const indexPath = join(knowledgeDir, 'INDEX.md')
-    if (!existsSync(indexPath)) {
-      checks.push({
-        name: 'knowledge_index_missing',
-        severity: CHECK_SEVERITY.WARNING,
-        detail: `knowledge/INDEX.md 不存在`
-      })
-    } else {
-      // 检查 INDEX.md 引用的文件是否真实存在
-      const indexContent = readFileSync(indexPath, 'utf8')
-      const referencedFiles = [...indexContent.matchAll(/\(([^)]+\.md)/g)].map(m => m[1])
-      const missingRefs = referencedFiles.filter(f => !existsSync(join(knowledgeDir, f)))
-      if (missingRefs.length > 0) {
-        checks.push({
-          name: 'knowledge_broken_refs',
-          severity: CHECK_SEVERITY.WARNING,
-          detail: `INDEX.md 引用了不存在的文件: ${missingRefs.join(', ')}`
-        })
-      }
-    }
-  } else {
-    checks.push({
-      name: 'knowledge_dir_missing',
-      severity: CHECK_SEVERITY.WARNING,
-      detail: `knowledge/ 目录不存在`
-    })
-  }
-
-  // 8. 计算 finalStatus
-  const hasFailed = checks.some(c => c.severity === CHECK_SEVERITY.FAILED)
-  const hasWarning = checks.some(c => c.severity === CHECK_SEVERITY.WARNING)
-
-  let status
-  if (hasFailed) {
-    status = SCAN_STATUS.FAILED_POST_CHECK
-  } else if (hasWarning) {
-    status = SCAN_STATUS.COMPLETED_WITH_WARNINGS
-  } else {
-    status = SCAN_STATUS.SUCCESS
-  }
-
-  return { status, checks }
-}
-
-/**
- * 将 postcheck 结果转换为结构化 JSON（SillyHub 可消费格式）
- *
- * failure_category 标准化：
- *   - warning  : 非致命问题，不阻塞流程
- *   - error    : 文档缺失/内容不完整，需要修复
- *   - critical : 安全问题（source_root 泄漏/路径污染）
- *
- * 结构化字段：
- *   - violations      : 明确违反约束的条目（source_root 泄漏等）
- *   - missing_outputs : 预期文件不存在
- *   - path_pollution  : 产物写入了错误路径
- *   - bad_references  : 引用了不存在的命令/资源
- *   - quality_warnings: AI 输出中包含错误标记等质量信号
- *
- * @param {object} result - runScanPostCheck 返回值
- * @param {object} [meta] - 附带元数据（workspace_id, scan_run_id, timestamp 等）
- * @returns {object} 结构化 JSON
- */
-export function formatStructuredResult(result, meta = {}) {
-  const structured = {
-    schema_version: 1,
-    generated_at: new Date().toISOString(),
-    overall_status: result.status,
-    // 路径溯源（供平台消费）
-    ...(meta.workspace_id ? { workspace_id: meta.workspace_id } : {}),
-    ...(meta.scan_run_id ? { scan_run_id: meta.scan_run_id } : {}),
-    ...(meta.source_root ? { source_root: meta.source_root } : {}),
-    ...(meta.spec_root ? { spec_root: meta.spec_root } : {}),
-    ...(meta.runtime_root ? { runtime_root: meta.runtime_root } : {}),
-    summary: {
-      total_checks: result.checks.length,
-      critical: 0,
-      error: 0,
-      warning: 0,
-    },
-    failure_categories: {
-      violations: [],
-      missing_outputs: [],
-      path_pollution: [],
-      bad_references: [],
-      quality_warnings: [],
-    },
-    checks: result.checks.map(c => ({
-      name: c.name,
-      severity: c.severity === 'failed' ? 'critical' : c.severity,
-      detail: c.detail,
-    })),
-  }
-
-  // 分类到 failure_categories
-  for (const check of result.checks) {
-    const severity = check.severity === 'failed' ? 'critical' : check.severity
-    const entry = { name: check.name, detail: check.detail, severity }
-
-    // 路径污染类
-    if (check.name === 'source_root_leak' || check.name === 'source_root_docs_leak') {
-      structured.failure_categories.path_pollution.push(entry)
-      structured.failure_categories.violations.push(entry)
-    }
-    // 文档缺失类
-    else if (check.name === 'all_docs_missing' || check.name === 'partial_docs_missing' || check.name === 'missing_docs') {
-      structured.failure_categories.missing_outputs.push(entry)
-    }
-    // 引用无效类
-    else if (check.name === 'local_config_invalid') {
-      structured.failure_categories.bad_references.push(entry)
-    }
-    // AI 输出质量类
-    else if (['api_error_529', 'rate_limit_exhausted'].includes(check.name)) {
-      structured.failure_categories.quality_warnings.push(entry)
-    }
-    // manifest/project 列表问题
-    else if (check.name === 'manifest_write_failed' || check.name === 'project_list_parse_failed') {
-      structured.failure_categories.violations.push(entry)
-    }
-    // 文档缺少 header
-    else if (check.name === 'docs_missing_header') {
-      structured.failure_categories.quality_warnings.push(entry)
-    }
-    // quick profile 说明（informational warning，非缺陷）
-    else if (check.name === 'quick_profile_notice') {
-      structured.failure_categories.quality_warnings.push(entry)
-    }
-    // 兜底：归入 violations
-    else {
-      structured.failure_categories.violations.push(entry)
-    }
-  }
-
-  // 汇总计数
-  for (const check of result.checks) {
-    if (check.severity === 'failed') structured.summary.critical++
-    else structured.summary.warning++
-  }
-
-  return structured
-}
-
-/**
- * 将结构化结果写入 JSON 文件（平台模式供 SillyHub 消费）
- *
- * 本地模式：写入 specDir/.runtime/postcheck-result.json
- * 平台模式：写入 runtimeRoot/scan-runs/{scan_run_id}/postcheck-result.json
- *
- * @param {object} structured - formatStructuredResult 返回值
- * @param {string} specDir - 规范目录（本地模式使用）
- * @param {object} [opts] - 平台模式选项
- * @param {string} [opts.runtimeRoot] - 平台模式运行时根目录
- * @param {string} [opts.scanRunId] - scan run ID
- * @returns {string|null} 写入的文件路径，失败时返回 null
- */
-export function writeStructuredResult(structured, specDir, opts = {}) {
-  if (!specDir && !opts.runtimeRoot) return null
-  try {
-    let outPath
-    if (opts.runtimeRoot && opts.scanRunId) {
-      const scanRunDir = join(opts.runtimeRoot, 'scan-runs', opts.scanRunId)
-      mkdirSync(scanRunDir, { recursive: true })
-      outPath = join(scanRunDir, 'postcheck-result.json')
-    } else if (specDir) {
-      const runtimeDir = join(specDir, '.runtime')
-      mkdirSync(runtimeDir, { recursive: true })
-      outPath = join(runtimeDir, 'postcheck-result.json')
-    } else {
-      return null
-    }
-
-    writeFileSync(outPath, JSON.stringify(structured, null, 2) + '\n')
-    return outPath
-  } catch (e) {
-    console.warn(`  ⚠️ postcheck-result.json 写入失败: ${e.message}`)
-    return null
-  }
-}
-
-/**
- * 打印 post-check 结果到 stdout
- */
-export function printScanPostCheckResult(result) {
-  if (result.checks.length === 0) {
-    console.log('  ✅ CLI post-check: 全部通过')
-    return
-  }
-
-  for (const check of result.checks) {
-    const icon = check.severity === 'failed' ? '❌' : '⚠️'
-    console.log(`  ${icon} CLI post-check [${check.name}]: ${check.detail}`)
-  }
-  console.log(`  📋 最终状态: ${result.status}`)
-}
-
-/**
- * scan 文档 header 幂等补填（2026-08-21 agent-手工产出审计第三批 E3）。
- *
- * runScanPostCheck 对缺 author/created_at 只 warning，agent 手改常忘——本函数补齐：
- * author = git user.name（回退 unknown），created_at = 当前时间。已有两键的文件不动；
- * 有 frontmatter（--- 开头）就地插缺失键，无则补一段 frontmatter。
- * `sillyspec scan-fix-headers [--project <名>]` 入口；与 runScanPostCheck 的
- * 「头部 512 字符含 author:/created_at:」判定口径一致。
- *
- * @param {{ cwd: string, specDir?: string|null, project?: string|null }} opts
- * @returns {{ fixed: string[], skipped: string[] }}
- */
-export function fixScanDocHeaders({ cwd, specDir = null, project = null }) {
-  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) : [])
-
-  let author = 'unknown'
-  try {
-    author = git(cwd, ['config', 'user.name']) || 'unknown'
-  } catch { /* git 不可用 → unknown */ }
-  const now = nowWallClock()
-
-  const fixed = []
-  const skipped = []
-  for (const p of projects) {
-    const scanDir = join(docsRoot, p, 'scan')
-    if (!existsSync(scanDir)) continue
-    for (const f of readdirSync(scanDir)) {
-      if (!f.endsWith('.md')) continue
-      const filePath = join(scanDir, f)
-      let content
-      try {
-        content = readFileSync(filePath, 'utf8')
-      } catch {
-        continue
-      }
-      const header = content.slice(0, 512)
-      const hasAuthor = /author\s*:/.test(header)
-      const hasCreated = /created_at\s*:/.test(header)
-      if (hasAuthor && hasCreated) {
-        skipped.push(filePath)
-        continue
-      }
-      const inserts = []
-      if (!hasAuthor) inserts.push(`author: ${author}`)
-      if (!hasCreated) inserts.push(`created_at: ${now}`)
-      let newContent
-      if (content.startsWith('---\n') || content.startsWith('---\r\n')) {
-        // 有 frontmatter：插到开标签后（CRLF 归一写回，与其它 CLI 写入口径一致）
-        const normalized = content.replace(/\r\n?/g, '\n')
-        newContent = normalized.replace(/^---\n/, `---\n${inserts.join('\n')}\n`)
-      } else {
-        newContent = `---\n${inserts.join('\n')}\n---\n\n` + content
-      }
-      try {
-        writeFileSync(filePath, newContent)
-        fixed.push(filePath)
-      } catch { /* 只读文件等写失败 → 跳过不抛 */ }
-    }
-  }
-  return { fixed, skipped }
-}
-
-/**
- * source_root 污染一键修复（2026-08-21 agent-手工产出审计第四批 C-3）。
- *
- * runScanPostCheck 对「agent 把产物写到 <source_root>/.sillyspec/ 而非平台 specRoot」只报
- * FAILED 不修——agent 手工搬目录常搬错。本函数把检查枚举的同款清单（docs/projects/workflows/
- * knowledge 目录 + manifest.json/local.yaml）搬到 specRoot 对应位置（已存在的不覆盖，报告
- * skipped），搬完源目录若空则删除。与检查的路径口径逐字一致（pollutePaths/polluteFiles）。
- *
- * @param {{ cwd: string, specDir: string }} opts cwd=source_root，specDir=平台 spec_root 绝对路径
- * @returns {{ moved: string[], skipped: string[], removedDirs: string[] }}
- */
-export function fixSourceRootLeak({ cwd, specDir }) {
-  if (!cwd || !specDir) return { moved: [], skipped: [], removedDirs: [] }
-  const moved = []
-  const skipped = []
-  const removedDirs = []
-  const pollutePaths = ['docs', 'projects', 'workflows', 'knowledge']
-  const polluteFiles = ['manifest.json', 'local.yaml']
-
-  // 目标目录确保存在
-  try { mkdirSync(join(specDir, '.runtime'), { recursive: true }) } catch {}
-
-  for (const file of polluteFiles) {
-    const src = join(cwd, '.sillyspec', file)
-    const dst = join(specDir, file)
-    if (!existsSync(src)) continue
-    if (existsSync(dst)) {
-      skipped.push(`local.yaml 已存在于 specRoot（保留两份，人工合并凭据后删源）`.replace('local.yaml', file))
-      continue
-    }
-    try {
-      renameSync(src, dst)
-      moved.push(`.sillyspec/${file} → specRoot/${file}`)
-    } catch (e) {
-      skipped.push(`.sillyspec/${file} 搬移失败: ${e.message}`)
-    }
-  }
-
-  for (const sub of pollutePaths) {
-    const srcDir = join(cwd, '.sillyspec', sub)
-    if (!existsSync(srcDir)) continue
-    let entries = []
-    try { entries = readdirSync(srcDir, { withFileTypes: true }) } catch { continue }
-    if (entries.length === 0) {
-      try { rmdirSync(srcDir); removedDirs.push(`.sillyspec/${sub}/（空目录）`) } catch {}
-      continue
-    }
-    const dstDir = join(specDir, sub)
-    mkdirSync(dstDir, { recursive: true })
-    let allMoved = true
-    for (const e of entries) {
-      const src = join(srcDir, e.name)
-      const dst = join(dstDir, e.name)
-      if (existsSync(dst)) {
-        skipped.push(`.sillyspec/${sub}/${e.name}（specRoot 已有同名，不覆盖——人工比对后择一保留）`)
-        allMoved = false
-        continue
-      }
-      try {
-        renameSync(src, dst)
-        moved.push(`.sillyspec/${sub}/${e.name} → specRoot/${sub}/${e.name}`)
-      } catch (err) {
-        skipped.push(`.sillyspec/${sub}/${e.name} 搬移失败: ${err.message}`)
-        allMoved = false
-      }
-    }
-    if (allMoved) {
-      try { rmdirSync(srcDir); removedDirs.push(`.sillyspec/${sub}/`) } catch {}
-    }
-  }
-  return { moved, skipped, removedDirs }
-}

package/.claude/worktrees/sillyspec-data-model-research/src/scan-staleness.js

@@ -1,95 +0,0 @@
-/**
- * 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 刷新基线`,
-  }
-}