sillyspec 3.27.12 → 3.28.2

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,41 @@ 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 --suggest 查看候选锚点后修正引用', '删除无法核验的引用（引用了不存在的文件/行号）'],
+  }
+}
+
 /**
  * @param {object} opts
  * @param {string} opts.cwd - 源码项目根目录 (source_root)
@@ -47,6 +79,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 +151,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 +175,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 +312,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 +333,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 +498,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

@@ -16,7 +16,7 @@
  */
 
 import { createHash } from 'crypto';
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join, relative, sep } from 'path';
 
 // 与 sillyhub-daemon/src/spec-sync.ts 共用排除口径（task-07 / FR-06 / D-008@v2）：
@@ -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');
 }
@@ -323,6 +340,123 @@ function writeLastSyncTs(specRoot) {
   } catch { /* 标记失败只损失下次的防回推过滤，不影响本次同步结果 */ }
 }
 
+// 本地内容基线快照（坑 quicksync-conflict-granularity，2026-09-03 实证）：
+// 上次成功同步时刻的**本地文件 hash 全集**。「本地未改动」的内容级判据——
+// filterStaleUpdates 的 mtime 启发式会被 git 操作（pull/checkout/归档重写）刷新
+// mtime 击穿（本地 164 个旧归档全部伪装成「刚改过」，重试路径把陈旧副本静默
+// 推上服务器=回退）。hash 基线免疫 mtime 刷新：内容没变就是没改，服务器前进
+// 属正常多端演进 → 跟随服务器（不发 op、冲突时自动消解），只有内容真变了的
+// 文件才进冲突人工裁决。语义锚定「local at last sync」而非「server at last sync」：
+// 判据只回答「本地是否改过」，与服务器无关（bundle 拉回的新内容与快照不同 →
+// 视为本地改动照推，服务器同内容豁免兜底，无副作用）。
+const BASE_SNAPSHOT = 'spec-sync-base.json';
+
+function readBaseSnapshot(specRoot) {
+  try {
+    const raw = readFileSync(join(specRoot, '.runtime', BASE_SNAPSHOT), 'utf8');
+    const hashes = JSON.parse(raw).hashes;
+    return hashes && typeof hashes === 'object' ? hashes : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeBaseSnapshot(specRoot, localFiles) {
+  try {
+    const hashes = {};
+    for (const f of localFiles) hashes[f.path] = f.hash;
+    mkdirSync(join(specRoot, '.runtime'), { recursive: true });
+    writeFileSync(join(specRoot, '.runtime', BASE_SNAPSHOT), JSON.stringify({ ts: Date.now(), hashes }, null, 2) + '\n', 'utf8');
+  } catch { /* 快照失败只损失下次的内容级防回推，不影响本次同步结果 */ }
+}
+
+/**
+ * 丢弃「跟随服务器」型 update op（坑 quicksync-conflict-granularity ①）。
+ *
+ * 判据：本地文件 hash 与基线快照一致 = 自上次同步内容未变——此刻与服务器 hash
+ * 不同只可能是他端会话推进了服务器，本地是陈旧副本，推送即回退（spec-sync-
+ * parallel-stale-overwrite 同族，但 mtime 免疫）。与 filterStaleUpdates 互补：
+ * 快照覆盖内容级判定，mtime 兜底快照缺失（首次同步/快照损坏）的过渡期。
+ * 快照无该路径（新文件/过渡期）→ 保留 op 维持旧行为。
+ *
+ * @param {Array} ops computeSpecOps 产物
+ * @param {Array} localFiles hashFiles 产物
+ * @param {object|null} baseHashes 基线快照 { [path]: hash }；null → 不过滤
+ * @returns {{ ops: Array, followed: string[] }}
+ */
+export function dropFollowServerUpdates(ops, localFiles, baseHashes) {
+  if (!baseHashes || !Array.isArray(ops) || ops.length === 0) {
+    return { ops, followed: [] };
+  }
+  const hashByPath = new Map(localFiles.map((f) => [f.path, f.hash]));
+  const followed = [];
+  const kept = [];
+  for (const op of ops) {
+    if (op.op === 'update') {
+      const base = baseHashes[op.path];
+      const loc = hashByPath.get(op.path);
+      if (base !== undefined && loc !== undefined && base === loc) {
+        followed.push(op.path);
+        continue;
+      }
+    }
+    kept.push(op);
+  }
+  return { ops: kept, followed };
+}
+
+/**
+ * 冲突路径分流（坑 quicksync-conflict-granularity ②）：服务器 conflict 回告的路径里，
+ * 区分「本地未改动 → 自动跟随服务器」与「本地真改动 → 需人工裁决」。
+ * follower 判据 = 内容基线命中（hash 级）或 mtime 兜底（filterStaleUpdates 同款）。
+ * @returns {{ followers: string[], real: object }} real = { [path]: server_version }
+ */
+export function partitionConflictPaths(serverVersions, localFiles, baseHashes, lastSyncTs) {
+  const hashByPath = new Map(localFiles.map((f) => [f.path, f.hash]));
+  const mtimeByPath = new Map(localFiles.map((f) => [f.path, f.mtime]));
+  const followers = [];
+  const real = {};
+  for (const [path, version] of Object.entries(serverVersions || {})) {
+    const base = baseHashes?.[path];
+    const loc = hashByPath.get(path);
+    const mtime = mtimeByPath.get(path);
+    const contentUnchanged = base !== undefined && loc !== undefined && base === loc;
+    const mtimeStale = mtime !== undefined && lastSyncTs && mtime * 1000 + 1000 <= lastSyncTs;
+    if (contentUnchanged || mtimeStale) followers.push(path);
+    else real[path] = version;
+  }
+  return { followers, real };
+}
+
+/**
+ * 未决 spec 树冲突同集判定（坑 spec-sync-conflict-banner-spam）：读 .runtime 下该变更的
+ * 冲突文件，conflicting_paths 与本轮真冲突集完全一致 → 重复轮次（横幅单行降噪依据）。
+ * 文件缺失/损坏/集合增减 → false（按首报或集变化处理，全幅横幅+重写文件）。
+ */
+function isSamePendingSpecConflict(specRoot, changeName, realPaths) {
+  try {
+    const raw = readFileSync(join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`), 'utf8');
+    const prev = JSON.parse(raw).conflicting_paths;
+    if (!Array.isArray(prev) || prev.length !== realPaths.length) return false;
+    const prevSet = new Set(prev);
+    return realPaths.every((p) => prevSet.has(p));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 清残留未决冲突标记（坑 spec-sync-conflict-banner-spam）：本轮同步无冲突 = 此前的
+ * spec 树冲突已不存在（对端停推后 last-writer-wins 收敛/本地覆盖成功），残留文件会让
+ * status 永久红标、每轮横幅去重单行提示不消。best-effort，失败只影响下一轮横幅形态。
+ */
+function clearSpecConflictMarker(specRoot, changeName) {
+  try {
+    const p = join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`);
+    if (existsSync(p)) unlinkSync(p);
+  } catch { /* 清理失败不影响同步结果 */ }
+}
+
 /**
  * 同步本地 .sillyspec 树到平台（CLI 直跑增量同步入口）。
  *
@@ -360,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 };
   }
 
@@ -369,15 +503,29 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
   const localFiles = hashFiles(entries);
   let ops = computeSpecOps(serverManifest, localFiles);
 
-  // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容
+  // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容。
+  // 双层判据（坑 quicksync-conflict-granularity）：内容基线快照（hash 级，免疫 git 操作刷新
+  // mtime——pull/checkout/归档重写后的旧文件内容未变即「未改动」）为主，mtime 启发式兜底
+  // 快照缺失的过渡期/新文件。forcePush（resolve --keep-local 强制重推）全旁路——用户显式
+  // 裁决「以本地为准」时本地意志高于跟随服务器语义，不得被防回推削掉。
   const lastSyncTs = readLastSyncTs(specRoot);
-  const filtered = filterStaleUpdates(ops, localFiles, lastSyncTs);
-  if (filtered.stale.length > 0) {
-    console.warn(
-      `[spec-sync] 拦下 ${filtered.stale.length} 个旧副本回推（本地自上次同步未改动而服务器已前进，如确需以本地为准：重存后重推）: ${filtered.stale.slice(0, 5).join(', ')}${filtered.stale.length > 5 ? ' 等' : ''}`
-    );
+  const baseHashes = readBaseSnapshot(specRoot);
+  if (!opts.forcePush) {
+    const dropped = dropFollowServerUpdates(ops, localFiles, baseHashes);
+    if (dropped.followed.length > 0) {
+      console.log(
+        `[spec-sync] ${dropped.followed.length} 个本地未改动文件自动跟随服务器（他端推进，内容未变不回推）: ${dropped.followed.slice(0, 5).join(', ')}${dropped.followed.length > 5 ? ' 等' : ''}`
+      );
+    }
+    ops = dropped.ops;
+    const filtered = filterStaleUpdates(ops, localFiles, lastSyncTs);
+    if (filtered.stale.length > 0) {
+      console.warn(
+        `[spec-sync] 拦下 ${filtered.stale.length} 个旧副本回推（本地自上次同步未改动而服务器已前进，如确需以本地为准：重存后重推）: ${filtered.stale.slice(0, 5).join(', ')}${filtered.stale.length > 5 ? ' 等' : ''}`
+      );
+    }
+    ops = filtered.ops;
   }
-  ops = filtered.ops;
 
   if (ops.length === 0) {
     debugLog(`[spec-sync] 无差异，跳过同步: ${changeName}`);
@@ -404,7 +552,43 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       // HUB-08 冲突闭环：落 spec-sync-conflict-<change>.json（与进度 sync-conflict-* 同目录），
       // 供 platform status 列出 + platform resolve 三态处置。此前只 warn 返回，下次 sync 用
       // 同一 base_version 继续冲突循环，无人工裁决入口。
+      //
+      // 坑 quicksync-conflict-granularity（2026-09-03 实证 164 个旧归档整树冲突）：GET 清单
+      // → 全树 hash → POST 的竞态窗内他端推进，base_version 过期引发大规模「假冲突」——
+      // 这些文件本地根本没改（与本次 quick 零交集），却把冲突文件坐实、后续自动同步进
+      // resolve 流程。冲突粒度收窄：follower（本地未改动，内容基线/mtime 判定）自动跟随
+      // 服务器、不进冲突文件；服务器「冲突 op 跳过、其余照常 apply」语义下本会话真改动
+      // 已落——follower 清空即视为本轮同步成功（写基线，下次起 pre-POST 即拦）。
       const serverVersions = body.server_versions || {};
+      const { followers, real } = opts.forcePush
+        ? { followers: [], real: serverVersions }
+        : partitionConflictPaths(serverVersions, localFiles, baseHashes, lastSyncTs);
+      const realPaths = Object.keys(real);
+
+      // 冲突横幅降噪（坑 spec-sync-conflict-banner-spam，与 sync() 进度侧 2026-08-23 修法同族）：
+      // 未决 spec 树冲突存在期间，每步自动同步都会对同一批真冲突路径再撞一次——此前每轮
+      // 重写冲突文件 + 空行+全幅双线横幅（含整包 server_versions JSON dump），「已卡死不会
+      // 自愈」连环刷屏。冲突文件在且冲突集未变 = 用户已被告知：重复轮次单行提示（可见但不
+      // 吓人），不重写文件（created_at 稳定，status 红标语义不变）；冲突集变化才重写+全幅。
+      // forcePush（resolve --keep-local 刚裁决完重推）不参与去重——需真实判定与文件刷新。
+      const pendingSame = !opts.forcePush && realPaths.length > 0 && isSamePendingSpecConflict(specRoot, changeName, realPaths);
+      if (pendingSame) {
+        if (followers.length > 0) {
+          debugLog(`[spec-sync] ${followers.length} 个本地未改动文件自动跟随服务器: ${followers.slice(0, 5).join(', ')}${followers.length > 5 ? ' 等' : ''}`);
+        }
+        console.warn(`⚠️ [spec-sync] 变更 ${changeName} 存在未决 spec 树冲突（${realPaths.length} 个文件待裁决，本轮非冲突改动已照常同步）。处理：sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort`);
+        return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath: join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`), suppressed: true };
+      }
+      if (followers.length > 0) {
+        console.warn(`[spec-sync] ${followers.length} 个本地未改动文件自动跟随服务器（正常多端前进，无需人工裁决）: ${followers.slice(0, 5).join(', ')}${followers.length > 5 ? ' 等' : ''}`);
+      }
+      if (realPaths.length === 0) {
+        writeLastSyncTs(specRoot);
+        writeBaseSnapshot(specRoot, localFiles);
+        clearSpecConflictMarker(specRoot, changeName);
+        console.log(`[spec-sync] 冲突已自动消解（0 个需人工裁决；本会话改动 ${ops.length - followers.length > 0 ? '已同步' : '无差异'}）: ${changeName}`);
+        return { synced: Math.max(ops.length - followers.length, 0), conflict: false, autoResolved: followers.length };
+      }
       let conflictPath = null;
       try {
         const runtimeDir = join(specRoot, '.runtime');
@@ -414,23 +598,31 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
           change: changeName,
           kind: 'spec-tree',
           created_at: new Date().toISOString(),
-          server_versions: serverVersions,
-          conflicting_paths: Object.keys(serverVersions),
-          note: 'spec 树文件冲突（服务器版本领先于本地 diff 基线）。resolve --keep-local 以本地为准重推；--take-platform 暂不支持（平台无文件下载端点）',
+          server_versions: real,
+          conflicting_paths: realPaths,
+          auto_followed: followers,
+          note: 'spec 树文件冲突（仅列本地真改动文件；本地未改动文件已自动跟随服务器）。resolve --keep-local 以本地为准重推；--take-platform 拉平台 bundle 覆盖冲突文件（接受服务器版本，2026-09-03 起支持）',
         }, null, 2) + '\n', 'utf8');
       } catch (e) {
         console.warn(`[spec-sync] 冲突文件写入失败（冲突信息仅打印）: ${e.message}`);
       }
+      // 横幅只列前 5 个路径（截断防刷屏，坑 spec-sync-conflict-banner-spam）：逐文件服务器
+      // 版本在冲突详情文件里，不再整包 JSON.stringify dump 到终端。
+      const shownPaths = realPaths.slice(0, 5).join(', ') + (realPaths.length > 5 ? ' 等' : '');
       console.warn('');
-      console.warn(`⚠️ [spec-sync] 检测到 spec 树冲突（${Object.keys(serverVersions).length} 个文件，服务器版本: ${JSON.stringify(serverVersions)}）`);
-      console.warn(`⚠️ 处置：sillyspec platform resolve ${changeName} --keep-local | --abort（冲突详情: ${conflictPath || '(写入失败)'}）`);
-      return { synced: 0, conflict: true, serverVersions, conflictPath };
+      console.warn(`⚠️ [spec-sync] 检测到 spec 树冲突（${realPaths.length} 个文件: ${shownPaths}；逐文件服务器版本见冲突详情文件）`);
+      console.warn(`⚠️ 处置：sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort（冲突详情: ${conflictPath || '(写入失败)'}）`);
+      return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath };
     }
     console.log(`[spec-sync] 已同步 ${ops.length} 个文件变更: ${changeName}`);
+    // 本轮无冲突 = 此前的未决 spec 树冲突已不存在，清残留标记（否则 status 永久红标、
+    // 横幅去重单行提示不消——坑 spec-sync-conflict-banner-spam）
+    clearSpecConflictMarker(specRoot, changeName);
     writeLastSyncTs(specRoot);
+    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 };
   }
 }
@@ -441,5 +633,7 @@ export default {
   computeSpecOps,
   extractChangeDirs,
   filterStaleUpdates,
+  dropFollowServerUpdates,
+  partitionConflictPaths,
   syncSpecTree,
 };