sillyspec 3.28.0 → 3.28.3

package/src/scan-diff.js

@@ -26,6 +26,7 @@ import { safeGit } from './git-helper.js'
 import { parseSourceCommit } from './scan-staleness.js'
 import { matchFilesToModules } from './docs-debt.js'
 import { parseModuleMapSimple } from './modules.js'
+import { collectDocRefs } from './docs-check.js'
 
 /** safeGit 超时（仿 docs-debt 的 GIT_TIMEOUT_MS 模式：大 diff 慢时降级不挂起） */
 const GIT_TIMEOUT_MS = 10000
@@ -40,7 +41,8 @@ const DEFAULT_LIST_CAP = 5
  *   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 }
+ *   added, deleted, modified, unknown, unmapped, outOfScope, renameMap, byModule,
+ *   staleRefs, warnings, driftCount }
  *   | { ok: false, error: string }}
  *   ok:false = 硬错误（参数缺失 / 无 source_commit / 无效 base / git diff 失败）
  *   added/deleted/modified/unknown：范围内变更文件（POSIX 相对路径；R/C 记新路径）
@@ -163,6 +165,40 @@ export function computeScanDiff({ projectRoot, specBase, projectName, base } = {
     byModule[id] = { doc: entry.doc || '', added: a, deleted: d, modified: m, files: entry.files }
   }
 
+  // ── 引用级漂移（archify 借鉴，2026-09-04）：scan 文档显式 file:line 引用 × 基线后变更文件集。
+  // 变更集取 parseNameStatus 全量——**不经 module-map scope 过滤**（引用自带范围：指向「已变更
+  // 但范围外」文件的引用同样过时，advisory 信号不该被 scope 吞掉）；rename 的旧路径也入集
+  //（文档写在 scan 时点，引用的是旧路径，重命名后引用必失效——最强失效信号）。
+  // best-effort（读不到文档/异常 → 空清单不阻断文件级结果），不计入 driftCount / 退出码
+  //（advisory：引用指向已变更文件 ≠ 引用失效，提示人工核对）。──
+  const staleRefs = []
+  try {
+    const scanDir = join(specBase, 'docs', projectName, 'scan')
+    if (existsSync(scanDir)) {
+      const fullChanged = new Map() // POSIX path → A/D/M/R
+      for (const item of parseNameStatus(diffRes.value)) {
+        if (item.status === 'A' || item.status === 'D') fullChanged.set(item.path, item.status)
+        else if (item.status === 'M' || item.status === 'C') fullChanged.set(item.path, 'M')
+        else if (item.status === 'R') { fullChanged.set(item.path, 'R'); fullChanged.set(item.oldPath, 'R') }
+      }
+      const hitChange = (p) => {
+        if (fullChanged.has(p)) return { file: p, change: fullChanged.get(p) }
+        // src/ 前缀双向归一：文档 src 相对写法 ↔ git 仓库根路径
+        const alt = p.startsWith('src/') ? p.slice(4) : `src/${p}`
+        return fullChanged.has(alt) ? { file: alt, change: fullChanged.get(alt) } : null
+      }
+      for (const f of readdirSync(scanDir)) {
+        if (!f.endsWith('.md')) continue
+        const content = readFileSync(join(scanDir, f), 'utf8')
+        for (const ref of collectDocRefs(content)) {
+          if (ref.repo !== null) continue
+          const hit = hitChange(ref.file.replace(/\\/g, '/'))
+          if (hit) staleRefs.push({ doc: f, ref: ref.ref, change: hit.change, file: hit.file })
+        }
+      }
+    }
+  } catch { /* 引用级漂移为 advisory，异常静默降级 */ }
+
   return {
     ok: true,
     base: baseDisplay,
@@ -174,6 +210,7 @@ export function computeScanDiff({ projectRoot, specBase, projectName, base } = {
     added, deleted, modified, unknown, unmapped, outOfScope,
     renameMap,
     byModule,
+    staleRefs,
     warnings,
     driftCount: added.length + deleted.length + modified.length,
   }
@@ -240,6 +277,13 @@ function renderTerminal(r, { full }) {
   if (r.unknown.length > 0) {
     console.log(`无法归类（unknown，${r.unknown.length} 条）：${r.unknown.slice(0, cap).join(', ')}`)
   }
+  if (r.staleRefs && r.staleRefs.length > 0) {
+    console.log(`引用过时（scan 文档 file:line 引用指向基线后已变更的文件，${r.staleRefs.length} 条，advisory）：`)
+    for (const s of r.staleRefs.slice(0, cap)) {
+      console.log(`  - ${s.doc}: \`${s.ref}\`（${s.change === 'D' ? '文件已删除' : s.change === 'A' ? '文件为基线后新增' : s.change === 'R' ? '文件已重命名' : '文件已变更'}）`)
+    }
+    if (r.staleRefs.length > cap) console.log(`    ... 其余 ${r.staleRefs.length - cap} 条，--full 展开`)
+  }
   console.log(`漂移合计：${r.driftCount} 条（A${r.added.length} / D${r.deleted.length} / M${r.modified.length}）`)
 }
 
@@ -304,6 +348,15 @@ function writeReport(r, { specBase, projectName }) {
     for (const f of r.outOfScope) lines.push(`- \`${f}\``)
     lines.push('')
   }
+  if (r.staleRefs && r.staleRefs.length > 0) {
+    lines.push('## 引用过时（advisory，不计入漂移合计）', '')
+    lines.push('scan 文档 file:line 引用指向基线后已变更的文件——不必然失效，逐条核对：', '')
+    for (const s of r.staleRefs) {
+      const label = s.change === 'D' ? '文件已删除' : s.change === 'A' ? '文件为基线后新增' : s.change === 'R' ? '文件已重命名' : '文件已变更'
+      lines.push(`- ${s.doc}: \`${s.ref}\`（${label}）`)
+    }
+    lines.push('')
+  }
   if (r.warnings.length > 0) {
     lines.push('## 提示', '')
     for (const w of r.warnings) lines.push(`- ${w}`)

package/src/scan-facts.js

@@ -0,0 +1,173 @@
+/**
+ * scan-facts.js — scan 事实底稿（archify 借鉴：机械事实预咀嚼，2026-09-05）
+ *
+ * 定位：把 scan 子代理「各自从零 grep 探索」的机械部分（端点清单 / 依赖与脚本清单 /
+ * 源码规模 / git 基线）收敛为 CLI 一次确定性抽取的共享底稿——agent 从「发现」降级为
+ * 「解读」，探索 token 不再按子代理数量重复计费（为什么 archify 快的机制 2/7，分析见
+ * docs/sillyspec/archify-reference-analysis-2026-09-04.md）。
+ *
+ * 产物：docs/<project>/scan/_facts.md（下划线前缀 = 非必需文档，workflow check 与
+ * postcheck 的 7 份清单不查它）。底稿里的 file:line 引用天然进入 scan_doc_ref_invalid
+ * 核验与 scan-diff staleRefs 漂移追踪——这份底稿即 scan IR 的「机器半边」；
+ * agent 半边（per-doc claims sidecar）走正式 change 另行落地。
+ *
+ * 约束：fail-soft——任何一段抽取失败只跳过该段（md 里附注记），绝不抛出、绝不阻断 scan。
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { scanBackendEndpoints, scanFrontendApiCalls } from './endpoint-extractor.js'
+import { estimateSourceSize } from './run/scan-profile.js'
+import { safeGit } from './git-helper.js'
+
+/** 底稿各清单的上限（防大仓把底稿撑爆反而变成新的 token 黑洞） */
+const MAX_ENDPOINTS = 60
+const MAX_FRONTEND_CALLS = 30
+const MAX_DEPS = 40
+const MAX_SCRIPTS = 20
+
+/** 依赖与脚本清单：package.json 优先（结构化最稳），pyproject.toml 做行级 best-effort，其余清单记存在性 */
+function readManifestFacts(root) {
+  const manifests = []
+  for (const f of ['package.json', 'pyproject.toml', 'pom.xml', 'go.mod', 'build.gradle', 'Cargo.toml', 'requirements.txt', 'Gemfile', 'composer.json']) {
+    if (existsSync(join(root, f))) manifests.push(f)
+  }
+  const deps = []
+  const scripts = []
+  let pkgName = null
+  if (existsSync(join(root, 'package.json'))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+      pkgName = pkg.name || null
+      for (const key of ['dependencies', 'devDependencies', 'peerDependencies']) {
+        for (const dep of Object.keys(pkg[key] || {})) deps.push(dep)
+      }
+      for (const [name, cmd] of Object.entries(pkg.scripts || {})) scripts.push(`${name} = ${cmd}`)
+    } catch { /* 坏 package.json 不阻断，仅缺该段 */ }
+  } else if (existsSync(join(root, 'pyproject.toml'))) {
+    try {
+      const lines = readFileSync(join(root, 'pyproject.toml'), 'utf8').split(/\r?\n/)
+      // 两种形态：PEP 621 `dependencies = ["pkg>=x", ...]` 数组；poetry `[tool.poetry.dependencies]` 段
+      let inArray = false
+      let section = ''
+      for (const line of lines) {
+        const sec = line.match(/^\[([^\]]+)\]\s*$/)
+        if (sec) { section = sec[1]; inArray = false; continue }
+        if (/^dependencies\s*=\s*\[/.test(line)) inArray = true
+        if (inArray) {
+          for (const m of line.matchAll(/["']([A-Za-z0-9_.-]+)\s*[\[<>=!~;]/g)) deps.push(m[1])
+          if (/\]\s*$/.test(line) && !/^dependencies/.test(line)) inArray = false
+        } else if (section === 'tool.poetry.dependencies') {
+          const m = line.match(/^\s*([A-Za-z0-9_.-]+)\s*=\s*["'{]/)
+          if (m && m[1] !== 'python') deps.push(m[1])
+        }
+      }
+    } catch { /* best-effort */ }
+  }
+  return { manifests, pkgName, deps: [...new Set(deps)].slice(0, MAX_DEPS), depsTruncated: new Set(deps).size > MAX_DEPS, scripts: scripts.slice(0, MAX_SCRIPTS) }
+}
+
+/** 端点与前端调用抽取（source 转 cwd 相对 POSIX 路径，引用形态可直接被 docs-check/staleRefs 消费） */
+function collectEndpointFacts(cwd, root) {
+  let backend = []
+  let frontend = []
+  try { backend = scanBackendEndpoints(root) } catch { /* fail-soft */ }
+  try { frontend = scanFrontendApiCalls(root) } catch { /* fail-soft */ }
+  const rel = (abs) => relative(cwd, abs).replace(/\\/g, '/')
+  return {
+    backend: backend.slice(0, MAX_ENDPOINTS).map(e => ({ method: e.method, path: e.path, ref: `${rel(e.source)}:${e.line}` })),
+    backendTotal: backend.length,
+    frontend: frontend.slice(0, MAX_FRONTEND_CALLS).map(e => ({ method: e.method, path: e.path, ref: `${rel(e.source)}:${e.line}` })),
+    frontendTotal: frontend.length,
+  }
+}
+
+/**
+ * 确定性收集 scan 机械事实（纯同步，不写盘）。
+ * @param {{ cwd: string, projectPath?: string|null }} opts cwd：仓库根（引用解析锚）；projectPath：子项目相对路径（缺省主项目）
+ * @returns {object} facts（renderScanFactsMd 的输入）
+ */
+export function collectScanFacts({ cwd, projectPath = null }) {
+  const root = projectPath ? join(cwd, projectPath) : cwd
+  const manifest = readManifestFacts(root)
+  const size = (() => { try { return estimateSourceSize(root) } catch { return { fileCount: 0, sourceBytes: 0 } } })()
+  const git = safeGit(cwd, ['rev-parse', '--short', 'HEAD'])
+  const type = manifest.manifests.includes('package.json') ? 'nodejs'
+    : (manifest.manifests.includes('pyproject.toml') || manifest.manifests.includes('requirements.txt')) ? 'python'
+    : manifest.manifests.includes('pom.xml') ? 'maven'
+    : manifest.manifests.includes('go.mod') ? 'go'
+    : manifest.manifests.includes('Cargo.toml') ? 'rust'
+    : 'generic'
+  return {
+    generatedAt: new Date().toISOString().replace('T', ' ').slice(0, 19),
+    projectPath,
+    type,
+    pkgName: manifest.pkgName,
+    gitHead: git && git.value ? git.value.trim() : null,
+    manifests: manifest.manifests,
+    deps: manifest.deps,
+    depsTruncated: manifest.depsTruncated,
+    scripts: manifest.scripts,
+    size,
+    endpoints: collectEndpointFacts(cwd, root),
+  }
+}
+
+/**
+ * 渲染事实底稿 markdown。引用一律 `cwd 相对路径:行号`（反引号），可直接被
+ * collectDocRefs / scan_doc_ref_invalid / staleRefs 消费。
+ * @param {object} facts collectScanFacts 返回值
+ * @returns {string} markdown 全文
+ */
+export function renderScanFactsMd(facts) {
+  const scope = facts.projectPath ? `${facts.projectPath}/` : '（主项目根）'
+  const lines = []
+  lines.push(`# scan 事实底稿（CLI 确定性抽取）`)
+  lines.push('')
+  lines.push(`> 生成：sillyspec scan facts · ${facts.generatedAt} · 范围：${scope} · git HEAD：${facts.gitHead || '（不可用）'}`)
+  lines.push('> 本文件由 CLI 机器生成（零 AI token）。子代理**禁止重新 grep 发现**下列机械事实，只做解读与成文；与源码冲突时以本底稿为准并标注差异。')
+  lines.push('')
+  lines.push('## 项目类型与清单')
+  lines.push('')
+  lines.push(`- 类型判定：${facts.type}${facts.pkgName ? `（包名 ${facts.pkgName}）` : ''}`)
+  lines.push(`- 清单文件：${facts.manifests.length > 0 ? facts.manifests.join(' / ') : '（未发现）'}`)
+  lines.push(`- 源码规模：${facts.size.fileCount} 个源文件 / ${Math.round(facts.size.sourceBytes / 1024)}KB`)
+  lines.push('')
+  if (facts.deps.length > 0) {
+    lines.push(`## 依赖清单${facts.depsTruncated ? `（前 ${MAX_DEPS} 个，共更多）` : ''}`)
+    lines.push('')
+    lines.push(facts.deps.join(', '))
+    lines.push('')
+  }
+  if (facts.scripts.length > 0) {
+    lines.push('## package.json scripts')
+    lines.push('')
+    for (const s of facts.scripts) lines.push(`- ${s}`)
+    lines.push('')
+  }
+  lines.push(`## 后端端点（${facts.endpoints.backendTotal} 条${facts.endpoints.backendTotal > MAX_ENDPOINTS ? `，仅列前 ${MAX_ENDPOINTS}` : ''}）`)
+  lines.push('')
+  if (facts.endpoints.backend.length === 0) lines.push('（未抽取到路由定义——非后端项目或框架不在支持列表）')
+  for (const e of facts.endpoints.backend) lines.push(`- \`${e.method} ${e.path}\` — \`${e.ref}\``)
+  lines.push('')
+  if (facts.endpoints.frontend.length > 0) {
+    lines.push(`## 前端 API 调用（${facts.endpoints.frontendTotal} 条${facts.endpoints.frontendTotal > MAX_FRONTEND_CALLS ? `，仅列前 ${MAX_FRONTEND_CALLS}` : ''}）`)
+    lines.push('')
+    for (const e of facts.endpoints.frontend) lines.push(`- \`${e.method} ${e.path}\` — \`${e.ref}\``)
+    lines.push('')
+  }
+  return lines.join('\n') + '\n'
+}
+
+/**
+ * 收集并落盘事实底稿（scan 步骤 3 / `sillyspec scan facts` CLI 共用入口）。
+ * @param {{ cwd: string, specDir: string, projectName: string, projectPath?: string|null }} opts
+ * @returns {{ outPath: string, facts: object }}
+ */
+export function buildAndWriteScanFacts({ cwd, specDir, projectName, projectPath = null }) {
+  const facts = collectScanFacts({ cwd, projectPath })
+  const outDir = join(specDir, 'docs', projectName, 'scan')
+  mkdirSync(outDir, { recursive: true })
+  const outPath = join(outDir, '_facts.md')
+  writeFileSync(outPath, renderScanFactsMd(facts), 'utf8')
+  return { outPath, facts }
+}

package/src/scan-postcheck.js

@@ -11,9 +11,45 @@ import { SCAN_STATUS, CHECK_SEVERITY, SCAN_REQUIRED_DOCS, SCAN_REQUIRED_DOCS_QUI
 import { validateScriptCommands } from './stages/cmd-existence.js'
 import { git } from './git-helper.js'
 import { nowWallClock } from './datetime.js'
+import { collectInvalidDocRefs } from './docs-check.js'
 
 const REQUIRED_SCAN_DOCS = SCAN_REQUIRED_DOCS
 
+/**
+ * scan 文档引用事实核验（archify 借鉴 P0，2026-09-04）：
+ * 对 scan 产物里显式写的 file:line 引用跑 docs-check 的联合核验（层1 存在性+行号边界 +
+ * 层2 引用行符号窗口断言，语义单一源 collectInvalidDocRefs）。
+ * repo:// 跨仓引用需要本机映射，跳过本地校验（防跨设备误报，与 docs-check 立场一致）。
+ * 只核验「显式写了引用的」事实；没写引用的散文不在范围（P2 的 scan IR 才覆盖）。
+ * WARNING 级：scan 刚写完窗口极小，失效多为笔误；docs-gate ratchet 负责长期增量收敛。
+ * @param {string} cwd 源码项目根（引用解析锚点）
+ * @param {string} scanDir scan 文档目录
+ * @param {string[]} docs 存在的文档文件名列表
+ * @returns {object|null} check 条目；无引用或全部有效时返回 null
+ */
+function checkScanDocRefs(cwd, scanDir, docs) {
+  let verified
+  try {
+    verified = collectInvalidDocRefs(cwd, docs.map(d => ({ name: d, absPath: join(scanDir, d) })))
+  } catch {
+    return null // 核验器自身故障不阻断 postcheck（fail-open，仅损失一层 advisory）
+  }
+  const { invalid, totalRefs, skippedCrossRepo } = verified
+  if (invalid.length === 0) return null
+  const sample = invalid.slice(0, 3).map(i => `${i.doc}: \`${i.ref}\`（${i.reason}）`).join('；')
+  return {
+    name: 'scan_doc_ref_invalid',
+    severity: CHECK_SEVERITY.WARNING,
+    detail: `${invalid.length} 条 file:line 引用未通过核验（${totalRefs} 条中）: ${sample}${invalid.length > 3 ? ` 等 ${invalid.length} 条` : ''}`,
+    evidence: { invalidCount: invalid.length, totalRefs, skippedCrossRepo, checkedDocs: docs.length, sample: invalid.slice(0, 3) },
+    supportedFixes: [
+      'sillyspec docs check --paths <该文档> --dry-run  查看候选锚点（fixable 条目会给出 newLine），确认后去 --dry-run 落盘重锚',
+      'sillyspec docs check --paths <该文档> --fix  对 fixable 引用自动重锚（回执附修复前后失效数对比）',
+      '先跑 sillyspec docs check --paths <该文档> 确认零候选锚点后，再删除确认无法核验的引用行',
+    ],
+  }
+}
+
 /**
  * @param {object} opts
  * @param {string} opts.cwd - 源码项目根目录 (source_root)
@@ -47,6 +83,11 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {},
       checks.push({ name: 'quick_profile_notice', severity: CHECK_SEVERITY.WARNING, detail: 'quick scan：仅生成 4 份核心文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE），深度扫描待补齐' })
     }
 
+    // 引用事实核验（archify P0）：本地模式与平台模式同规则，防「本地过平台挂」
+    const existingLocalDocs = requiredDocs.filter(f => existsSync(join(scanDir, f)))
+    const refCheck = checkScanDocRefs(cwd, scanDir, existingLocalDocs)
+    if (refCheck) checks.push(refCheck)
+
     const hasWarning = checks.some(c => c.severity === 'warning')
     return { status: hasWarning ? 'completed_with_warnings' : 'success', checks }
   }
@@ -114,10 +155,16 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {},
     checks.push({
       name: 'docs_missing_header',
       severity: CHECK_SEVERITY.WARNING,
-      detail: `${docsMissingHeader.length} 份文档缺少 author/created_at: ${docsMissingHeader.join(', ')}（sillyspec scan-fix-headers 一键补齐）`
+      detail: `${docsMissingHeader.length} 份文档缺少 author/created_at: ${docsMissingHeader.join(', ')}（sillyspec scan-fix-headers 一键补齐）`,
+      evidence: { count: docsMissingHeader.length, docs: docsMissingHeader },
+      supportedFixes: ['sillyspec scan-fix-headers'],
     })
   }
 
+  // 3.5 引用事实核验（archify 借鉴 P0）：scan 文档里显式写的 file:line 引用逐条核验
+  const refCheck = checkScanDocRefs(cwd, specScanDir, existingDocs)
+  if (refCheck) checks.push(refCheck)
+
   // 4. local.yaml 校验
   const localYamlPath = join(specDir, 'local.yaml')
   if (existsSync(localYamlPath)) {
@@ -132,7 +179,9 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {},
       checks.push({
         name: 'local_config_invalid',
         severity: CHECK_SEVERITY.WARNING,
-        detail: `local.yaml 引用不存在的命令: ${invalid.map(i => `${i.cmd} (${i.reason})`).join('; ')}`
+        detail: `local.yaml 引用不存在的命令: ${invalid.map(i => `${i.cmd} (${i.reason})`).join('; ')}`,
+        evidence: { invalid },
+        supportedFixes: ['修正 .sillyspec/local.yaml commands 中引用的 script 名（与 package.json scripts 对齐）'],
       })
     }
   }
@@ -267,6 +316,9 @@ export function formatStructuredResult(result, meta = {}) {
       name: c.name,
       severity: c.severity === 'failed' ? 'critical' : c.severity,
       detail: c.detail,
+      // 诊断信封升级（archify 借鉴 P1a，2026-09-04）：additive 字段，机器可路由的修复建议
+      ...(c.evidence !== undefined ? { evidence: c.evidence } : {}),
+      ...(Array.isArray(c.supportedFixes) ? { supportedFixes: c.supportedFixes } : {}),
     })),
   }
 
@@ -285,7 +337,7 @@ export function formatStructuredResult(result, meta = {}) {
       structured.failure_categories.missing_outputs.push(entry)
     }
     // 引用无效类
-    else if (check.name === 'local_config_invalid') {
+    else if (check.name === 'local_config_invalid' || check.name === 'scan_doc_ref_invalid') {
       structured.failure_categories.bad_references.push(entry)
     }
     // AI 输出质量类
@@ -450,6 +502,65 @@ export function backfillFrontmatter(content, { author, createdAt }) {
   return { changed: true, content: `---\n${inserts.join('\n')}\n---\n\n` + content.replace(/\r\n?/g, '\n') }
 }
 
+/**
+ * scan 文档 frontmatter CLI 原子注入（2026-09-05 ②，archify 借鉴：机器校验替代 agent 自检）。
+ *
+ * agent 只写正文，元数据由 CLI「盖章」：author / created_at / source_commit（HEAD 短哈希）/
+ * updated_at / generator: sillyspec-scan（quick 档另加 scan_depth: quick）。
+ * 只补缺失键、**绝不覆盖已有**（增量扫描时旧文档保留原 source_commit 溯源）；
+ * 插入口径与 backfillFrontmatter 逐字一致（有 --- 就地插入、无则前置整块、CRLF 归一写回）。
+ * 幂等——三个调用路径（scanFinalize / quick postcheck / 平台收尾）重复执行无害。
+ * 消灭 agent 手抄 CLI 注入值的失败模式（scan-fix-headers 从「兜底」降级为「历史文档修复工具」）。
+ *
+ * @param {{ cwd: string, specDir?: string|null, project?: string|null, mode?: string|null }} opts
+ * @returns {{ fixed: string[], skipped: string[], stampedKeys: number }}
+ */
+export function stampScanDocHeaders({ cwd, specDir = null, project = null, mode = 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 */ }
+  let headShort = null
+  try { headShort = String(git(cwd, ['rev-parse', '--short', 'HEAD']) || '').trim() || null } catch { /* 非 git 仓 → 省略 source_commit */ }
+  const now = nowWallClock()
+  const updatedIso = new Date().toISOString()
+
+  const fixed = []
+  const skipped = []
+  let stampedKeys = 0
+  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, 600)
+      const inserts = []
+      if (!/author\s*:/.test(header)) { inserts.push(`author: ${author}`); stampedKeys++ }
+      if (!/created_at\s*:/.test(header)) { inserts.push(`created_at: ${now}`); stampedKeys++ }
+      if (headShort && !/source_commit\s*:/.test(header)) { inserts.push(`source_commit: ${headShort}`); stampedKeys++ }
+      if (!/updated_at\s*:/.test(header)) { inserts.push(`updated_at: ${updatedIso}`); stampedKeys++ }
+      if (!/generator\s*:/.test(header)) { inserts.push(`generator: sillyspec-scan`); stampedKeys++ }
+      if (mode === 'quick' && !/scan_depth\s*:/.test(header)) { inserts.push(`scan_depth: quick`); stampedKeys++ }
+      if (inserts.length === 0) { skipped.push(filePath); continue }
+      const out = content.startsWith('---\n') || content.startsWith('---\r\n')
+        ? content.replace(/\r\n?/g, '\n').replace(/^---\n/, `---\n${inserts.join('\n')}\n`)
+        : `---\n${inserts.join('\n')}\n---\n\n` + content.replace(/\r\n?/g, '\n')
+      try {
+        writeFileSync(filePath, out)
+        fixed.push(filePath)
+      } catch { /* 只读文件等写失败 → 跳过不抛 */ }
+    }
+  }
+  return { fixed, skipped, stampedKeys }
+}
+
 /**
  * source_root 污染一键修复（2026-08-21 agent-手工产出审计第四批 C-3）。
  *

package/src/spec-sync.js

@@ -45,6 +45,23 @@ function debugLog(msg) {
   if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn(msg);
 }
 
+// 同步失败分类文案（坑 spec-sync-aborted-looks-exception，2026-09-07 平台执行环境实证）：
+// undici 被取消时 err.message 是英文原始串（AbortError=「This operation was aborted」、
+// TimeoutError=「The operation was aborted due to timeout」），原样拼进 warn 看起来像未知
+// 异常。按 err.name 翻译：AbortError=外部总熔断取消（run/shared.js raceWithAbort，预算经
+// SILLYSPEC_SYNC_TIMEOUT_MS 可调，故不写死秒数）；TimeoutError=单请求超时（清单 10s /
+// 推送 30s 口径）；其余错误维持原样。判别口径同 sync.js fetchJson 的 AbortError/
+// TimeoutError 先例（外部 signal abort 抛 AbortError、AbortSignal.timeout 到期抛 TimeoutError）。
+export function describeSyncError(err) {
+  if (err && err.name === 'AbortError') {
+    return '平台响应慢，本轮同步被总预算熔断让路（best-effort，下一条命令自动重试）';
+  }
+  if (err && err.name === 'TimeoutError') {
+    return '单请求超时（清单 10s / 推送 30s 口径，best-effort，下次自动重试）';
+  }
+  return err && err.message ? err.message : String(err);
+}
+
 function _hashBuffer(buf) {
   return createHash('sha256').update(buf).digest('hex');
 }
@@ -477,7 +494,7 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
     const body = await res.json().catch(() => ({}));
     serverManifest = body.files || {};
   } catch (err) {
-    console.warn(`[spec-sync] 拉取清单异常（文件树本次未同步，下次自动重试）: ${changeName}: ${err.message}`);
+    console.warn(`[spec-sync] 拉取清单异常（文件树本次未同步，下次自动重试）: ${changeName}: ${describeSyncError(err)}`);
     return { synced: 0 };
   }
 
@@ -605,7 +622,7 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
     writeBaseSnapshot(specRoot, localFiles);
     return { synced: ops.length };
   } catch (err) {
-    console.warn(`[spec-sync] 同步异常（文件树本次未同步，下次自动重试）: ${changeName}: ${err.message}`);
+    console.warn(`[spec-sync] 同步异常（文件树本次未同步，下次自动重试）: ${changeName}: ${describeSyncError(err)}`);
     return { synced: 0 };
   }
 }

package/src/stage-review.js

@@ -69,9 +69,13 @@ export function renderReviewJsonContract({ stage, changeDir, reviewRunId, tier }
     '- **推荐**:docHash 先占位(如 `"TODO"`),review.json 写完后跑',
     '  `sillyspec register-stage-review --change <变更名> --stage ' + stageLbl + ' --refresh-hash`',
     '  —— CLI 重算真实 sha256 代填,verdict/checklist 原样保留;主文档改版后同样跑这条',
-    '  (多阶段联动用 `--all` 一次处理)。gate 拦 docHash 失配时也是同一条命令修复。',
+    '  (多阶段联动用 `--all` 一次处理)。',
+    '- **忘了跑也没关系**:' + mainDoc + ' 改版后 --done 的 gate 检测到 docHash 失配会**自动机械重算放行**',
+    '  (verdict 保留;结论是否仍适用于新文档需人工确认,reviewerNotes 会留审计行)。',
     '- 兜底手算口径(极端无 CLI 场景):node `crypto.createHash(\'sha256\').update(readFileSync(...))` (原始字节)/ `sha256sum <file>` 首列 hex。',
-    '- ⚠️ **review.json 写入后若 ' + mainDoc + ' 再被改,必须重算 docHash** —— gate 会重算 reviewedFiles[0] 的 sha256 比对,不符判伪造(历史翻车根因:design 改了 rev 后 docHash 仍是旧值)',
+    '- ⚠️ **review.json 写入后若 ' + mainDoc + ' 再被改,须重算 docHash** —— 忘算也没关系:gate 会自动机械重算放行,',
+    '  但那只是「机械对齐」;大幅改版(设计要点/接口变更)时审查结论可能已过时,应人工确认结论续用或重审,',
+    '  不要把自动放行当「新文档已审过」(历史翻车根因:design 改了 rev 后结论未复核)。',
     '',
     '### 完整 JSON 示例(照抄改值)',
     '```json',
@@ -212,7 +216,8 @@ export function verifyStageReviewDocHash(review, searchDirs) {
     if (claimed !== actualRaw.toLowerCase() && claimed !== actualLf.toLowerCase()) {
       errors.push(
         `docHash 与主审查文档 ${primaryRel} 的实际内容不匹配。` +
-        `若刚改过该文档（如 design 修订后忘重算），一键修复：` +
+        `若刚改过该文档（如 design 修订后忘重算），--done gate 会自动机械重算放行（verdict 保留）；` +
+        `本调用方未走自动刷新时可手动执行：` +
         `sillyspec register-stage-review --change <变更名> --stage <阶段> --refresh-hash` +
         `（CLI 重算 docHash 代填，verdict 保留；多阶段联动加 --all）；` +
         `若未改文档，则 review.json 疑似伪造（未真正读取文档）。`
@@ -412,6 +417,60 @@ export function validateStageReview(opts) {
   return { ok: errors.length === 0, errors, warnings, review: parsed }
 }
 
+/**
+ * validateStageReview 的 gate 时刻自动刷新包装（坑 stage-review-refresh-hash-manual-forget，
+ * 2026-09-04 用户实证③：design 每次改版都要手动重跑 register-stage-review --refresh-hash，
+ * 易忘——忘则 --done 被 docHash 失配拦一轮，纯机械损耗）。
+ *
+ * 语义与 --refresh-hash 完全同源：主文档改版后的 hash 机械重算，verdict/checklist/
+ * requiredEvidence 原样保留（结论是否仍适用由人工确认——reviewerNotes 追加审计行留痕）。
+ * 自动刷新不放宽防伪造边界：
+ *   - 真正判伪造/错位的「主文档在候选基准下均不存在」不触发自动刷新（仍 fail-closed）；
+ *   - schema 失败 / verdict=fail 不碰（照常阻断）；
+ *   - 写盘失败回落原失败结果（fail-closed，不静默放行）。
+ *
+ * @param {object} opts - 同 validateStageReview，另加 opts.autoRefresh（true 才尝试自动刷新）
+ * @returns {{ result: object, autoRefreshed: boolean, refreshedPath?: string, previousErrors?: string[] }}
+ */
+export function validateStageReviewWithAutoRefresh(opts) {
+  const result = validateStageReview(opts)
+  if (result.ok) return { result, autoRefreshed: false }
+  if (!opts.autoRefresh) return { result, autoRefreshed: false }
+  // 仅「docHash 与主审查文档 …不匹配」类错误才自动刷新；「均不存在」（路径伪造/基准错位）
+  // 与 schema/verdict 错误一律原样返回
+  const mismatchOnly = result.review
+    && Array.isArray(result.errors) && result.errors.length > 0
+    && result.errors.every(e => String(e).includes('docHash 与主审查文档'))
+  if (!mismatchOnly) return { result, autoRefreshed: false }
+
+  const reviewDir = join(opts.runtimeRoot, 'stage-reviews', `${opts.stage}-${opts.reviewRunId}`)
+  const reviewPath = join(reviewDir, 'review.json')
+  // 定位主文档并重算 hash（与 verifyStageReviewDocHash 同法：reviewedFiles[0] × searchDirs）
+  const primaryRel = Array.isArray(result.review.reviewedFiles) ? result.review.reviewedFiles[0] : null
+  let docHash = null
+  if (primaryRel) {
+    for (const base of (opts.searchDirs || [])) {
+      const abs = join(base, primaryRel)
+      if (existsSync(abs)) { docHash = computeDocHash(abs); break }
+    }
+  }
+  if (!docHash) return { result, autoRefreshed: false }
+
+  const refreshedAt = new Date().toISOString().slice(0, 19).replace('T', ' ')
+  const refreshed = {
+    ...result.review,
+    docHash,
+    reviewerNotes: `${result.review.reviewerNotes || ''}\ndocHash auto-refreshed at ${refreshedAt}（gate 检测主文档改版，机械重算；verdict 保留，结论是否仍适用需人工确认）`.trim(),
+  }
+  try {
+    writeFileSync(reviewPath, JSON.stringify(refreshed, null, 2) + '\n')
+  } catch {
+    return { result, autoRefreshed: false } // 写失败回落原失败结果，不静默放行
+  }
+  const recheck = validateStageReview(opts)
+  return { result: recheck, autoRefreshed: recheck.ok, refreshedPath: reviewPath, previousErrors: result.errors }
+}
+
 /**
  * 打印 stage review 校验结果
  * @param {{ ok: boolean, errors: string[], warnings: string[] }} result

package/src/stages/archive.js

@@ -186,14 +186,14 @@ created_at: <now-datetime>
     },
     {
       name: '更新路线图和提交',
-      prompt: `更新路线图并暂存变更。
+      prompt: `更新路线图并确认归档。
 
 ### 操作
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
-2. \`git add .sillyspec/changes/archive/\` — 暂存归档结果（archive/ 下仅本次归档新增，不会裹挟 changes/ 下其他活跃变更；不要 commit，由用户通过统一提交工具处理）
-3. \`git add .sillyspec/docs/<project>/modules/\` — 暂存模块文档更新（如有；精确到本次同步的模块文档，勿 add 整个 .sillyspec/docs/）
-4. \`git add .sillyspec/knowledge/decisions/\` — 暂存决策知识库更新（如有；decision-distill 步骤的提炼产物，精确到 decisions 子目录，勿 add 整个 .sillyspec/knowledge/；不要 commit，由用户通过统一提交工具处理）
-5. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+2. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+
+### 说明
+- **git 暂存已由 CLI 自动完成**（归档完成时自动 add：\`.sillyspec/changes/archive/\`、本次同步的模块文档、\`.sillyspec/knowledge/decisions/\`——未提交，由用户通过统一提交工具处理）——你不需要也不应该手动 git add
 
 ### 输出
 归档完成确认 + 累积规范统计`,

package/src/stages/brainstorm-auto.js

@@ -28,7 +28,8 @@ export const definition = {
 ### 加载上下文
 4. 读取项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）+ 共享规范 + 子项目上下文
 5. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
-6. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
+6. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 7. 棕地项目：读取 scan 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
 8. 加载模块索引：读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（如存在）
 9. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`