sillyspec 3.26.8 → 3.26.9

package/src/run/stage.js

@@ -25,6 +25,7 @@ import { outputStep } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
 import { createHash } from 'node:crypto'
 import { checkTransition } from '../stage-contract.js'
+import { AUXILIARY_STAGES } from '../constants.js'
 import { completeStageGates } from './gates.js'
 
 export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
@@ -107,6 +108,15 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     } catch {}
     if (!currentExecuteRunId) {
       currentExecuteRunId = generateExecuteRunId()
+      // D-001#1 主写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：marker 在则目录在，
+      // archive 完成度扫描/漂移兜底不再落到「有 marker 无目录」的空 run）。失败直接 throw——execute
+      // 启动即失败优于事后 review 错配（调用方 runCommand 冒到 CLI 顶层 exit 1，给出修复指引）。
+      try {
+        mkdirSync(join(runtimeRoot, 'execute-runs', currentExecuteRunId, 'tasks'), { recursive: true })
+      } catch (e) {
+        throw new Error(`execute run 目录创建失败（${join(runtimeRoot, 'execute-runs', currentExecuteRunId)}）: ${e.message}；` +
+          `请检查该路径是否为普通文件/只读，清理后重跑（sillyspec run execute --change ${changeName} --skip-approval）`)
+      }
       writeFileSync(runIdFile, currentExecuteRunId + '\n')
     }
   }
@@ -125,8 +135,12 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   }
 
   // 用户显式调用 sillyspec run <stage>：把它标记为当前阶段
+  // （D-003@v1：auxiliary 阶段不写 currentStage，避免 scan/quick/explore/archive/status/doctor
+  //   执行后污染主流程当前阶段；lastActive 心跳与 pm._write/triggerSync 照常）
   if (progress.currentStage !== stageName) {
-    progress.currentStage = stageName
+    if (!AUXILIARY_STAGES.includes(stageName)) {
+      progress.currentStage = stageName
+    }
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
     pm._write(cwd, progress, changeName)
     triggerSync(cwd, changeName, platformOpts)
@@ -375,6 +389,8 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         // 阶段完成收尾共享管线（noAI 末步核心修复 S1：plan postcheck independent-tier review verdict=fail /
         // 平台 scan manifest 此前被绕过）。gate 失败已 rollback 为 in-progress，early-return（不 fall through 到末尾 return）。
         const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText: null })
+        // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1（与 completeStep/continueStep 同语义）。
+        if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
         if (_stageGatesResult) return _stageGatesResult
         // gate 全过：persist completed（task-02 移后；此处无 triggerSync，与同文件 noAI 末步语义一致）。
         pm._write(cwd, progress, changeName)

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

@@ -1,19 +1,24 @@
 /**
- * scan-staleness — scan 文档漂移检测（债单 D-7 方案 A，change: 2026-08-15 ql-20260815-013）
+ * 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 文档可能没跟上近期结构变更"，按提示核对或重扫，而非盲信。
  *
- * 判定口径：scan 文档 frontmatter 的 source_commit（modules.js 写入、worktree-guard 覆盖
- * 保护同源字段）vs 当前 HEAD——`git rev-list --count <source_commit>..HEAD` + 提交时间差。
- * 纯读操作（git 只读 + frontmatter 解析），任何失败降级 null（advisory 信号不阻断流程）。
+ * 判定语义（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 数 / 天数，超过任一即 stale；advisory 性质允许保守默认） */
+/** 刷新提示阈值（commit 数 / 天数，超过任一即 needs-refresh；advisory 提示允许保守默认） */
 export const STALENESS_THRESHOLDS = { commits: 50, days: 14 }
 
 /**
@@ -31,7 +36,7 @@ export function parseSourceCommit(content) {
 /**
  * 计算单个 project 的 scan 文档漂移事实。
  * @param {{ projectRoot: string, specBase: string, projectName: string, thresholds?: { commits: number, days: number } }} opts
- * @returns {{ status: 'fresh'|'stale'|'unknown', behindCommits: number|null, daysSinceScan: number|null, sourceCommit: string|null, message: string }|null}
+ * @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 说明降级原因。
  */
@@ -53,7 +58,7 @@ export function computeScanStaleness(opts) {
   if (checked === 0) return null
   if (!sourceCommit) {
     return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit: null,
-      message: 'scan 文档无 source_commit 字段（旧版生成），无法判漂移——如架构已大改建议重跑 sillyspec run scan --standard' }
+      message: 'scan 文档无 source_commit 字段（旧版生成），无法算漂移提示——文档引用是否失效以 docs check 为准；如架构已大改建议重跑 sillyspec run scan --standard' }
   }
 
   const head = safeGit(projectRoot, ['rev-parse', 'HEAD'])
@@ -79,12 +84,12 @@ export function computeScanStaleness(opts) {
   const stale = behindCommits >= thresholds.commits || (daysSinceScan !== null && daysSinceScan >= thresholds.days)
   if (!stale) {
     return { status: 'fresh', behindCommits, daysSinceScan, sourceCommit,
-      message: `scan 文档新鲜（落后 ${behindCommits} commit / ${daysSinceScan ?? '?'} 天）` }
+      message: `scan 文档无需刷新（落后 ${behindCommits} commit / ${daysSinceScan ?? '?'} 天，低于提示阈值）` }
   }
   return {
-    status: 'stale', behindCommits, daysSinceScan, sourceCommit,
-    message: `⚠️ scan 文档过期：停在 ${sourceCommit.slice(0, 7)}（${daysSinceScan ?? '?'} 天前），期间源码已推进 ${behindCommits} commit。` +
-      `本次加载的架构/结构描述可能失真——涉及结构变更的 design 不要盲信 scan 文档，以实读代码为准；` +
-      `如需刷新基线跑 sillyspec run scan --standard --force-rescan`,
+    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)

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.js

@@ -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 做语义层交叉审查）