sillyspec 3.27.2 → 3.27.6

package/.claude/worktrees/sillyspec-data-model-research/src/docs-debt.js

@@ -0,0 +1,393 @@
+/**
+ * docs-debt — 模块文档欠账事实计算（change: 2026-08-15-docs-debt-inject，债单第六节）
+ *
+ * 原则："CLI 算事实注入"——git 事实算出本变更触及模块的文档欠账，注入 Wave prompt 的是
+ * 结论不是要求（advisory 不阻断，无债零输出，D-005）。
+ *
+ * 归属三级（D-003）：module.paths || module.core_files（读端口径同 prompt.js loadModuleContextIndex）
+ *   → 模块卡 doc 内容中的文件路径字面量（v1 map 兼容）→ 未匹配归 unmapped。
+ * behind 口径（D-004）：每模块两次 git log -1 --format="%h %ct" 取时间戳判方向，
+ *   behind = rev-list --count docCommit..srcCommit；untracked 卡 behind=null 显式"卡片从未提交"；
+ *   git 失败/超时 5s → 该模块 behind=null + 降级注记，不抛。
+ */
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { safeGit } from './git-helper.js'
+import { parseModuleMapSimple } from './modules.js'
+import { runDocsCheck, readDocsCheckConfig, parseDecisionEntries, anchorFilePath } from './docs-check.js'
+
+/** safeGit 超时（大仓 git log 慢时降级该模块，不挂起 Wave 渲染） */
+const GIT_TIMEOUT_MS = 5000
+
+/** realpath 归一（失败回退原值——路径不可及时保持调用方原有行为） */
+function realpathSafe(p) {
+  try { return realpathSync(p) } catch { return p }
+}
+
+/**
+ * 纯函数：把 changedFiles 归属到模块。
+ * @param {string[]} changedFiles 变更文件（POSIX 相对路径）
+ * @param {object} moduleIndex parseModuleMapSimple 返回值（{ modules: { id: { paths?, core_files?, doc? } } }）
+ * @param {{ cardsDir: string }} opts cardsDir = <specBase>/docs/<project>/modules
+ * @returns {{ byModule: Map<string, { doc: string, files: string[] }>, unmapped: string[] }}
+ */
+export function matchFilesToModules(changedFiles, moduleIndex, opts = {}) {
+  const byModule = new Map()
+  const unmapped = []
+  // parseModuleMapSimple 返回扁平模块对象（{ id: {paths?, core_files?, doc?} }，无 .modules 包层）
+  const modules = moduleIndex && !moduleIndex.modules ? moduleIndex : (moduleIndex?.modules || {})
+  const cardsDir = opts.cardsDir
+
+  // 模块 → 候选路径集合（一级：paths || core_files；同时预载卡片内容供二级）
+  const modulePaths = new Map() // moduleId → string[]
+  const cardContents = new Map() // moduleId → string
+  for (const [id, m] of Object.entries(modules)) {
+    const ps = [...(Array.isArray(m.paths) ? m.paths : []), ...(Array.isArray(m.core_files) ? m.core_files : [])]
+    modulePaths.set(id, ps)
+    if (cardsDir && m.doc) {
+      const cardPath = join(cardsDir, m.doc.replace(/^modules\//, ''))
+      if (existsSync(cardPath)) {
+        try { cardContents.set(id, readFileSync(cardPath, 'utf8')) } catch { /* 降级二级 */ }
+      }
+    }
+  }
+
+  for (const f of changedFiles) {
+    let matched = null
+    // 一级：paths/core_files 前缀或字面量命中
+    for (const [id, ps] of modulePaths) {
+      if (ps.some(p => p === f || f.startsWith(p.replace(/\/$/, '') + '/') || p.startsWith(f.split('/')[0] + '/') && p === f)) {
+        matched = id; break
+      }
+    }
+    // 二级：卡片 doc 内容中的文件路径字面量（精确子串）
+    if (!matched) {
+      for (const [id, content] of cardContents) {
+        if (content && content.includes(f)) { matched = id; break }
+      }
+    }
+    // 二级b：裸文件名匹配——卡片引用习惯是裸名（`execute.js` 而非 `src/stages/execute.js`，
+    // 本仓 stages.md 实证），全路径 includes 对这类卡永远落空 → 归属 unmapped（假"无归属"）。
+    // 规则：基名在卡内存在"独立出现"（两侧均非路径/标识符字符），防 a.js 误配 xa.js.txt 等。
+    // 全路径命中（上面循环）优先，裸名仅在未命中时兜底。
+    if (!matched) {
+      const base = f.slice(f.lastIndexOf('/') + 1)
+      if (base && !base.startsWith('.')) {
+        outer: for (const [id, content] of cardContents) {
+          if (!content) continue
+          let pos = content.indexOf(base)
+          while (pos !== -1) {
+            const before = pos > 0 ? content[pos - 1] : ''
+            const after = content[pos + base.length] || ''
+            const beforeOk = before === '' || !/[A-Za-z0-9_\/.\-]/.test(before)
+            const afterOk = after === '' || !/[A-Za-z0-9_\-./]/.test(after)
+            if (beforeOk && afterOk) { matched = id; break outer }
+            pos = content.indexOf(base, pos + 1)
+          }
+        }
+      }
+    }
+    if (!matched) { unmapped.push(f); continue }
+    const entry = byModule.get(matched) || { doc: modules[matched].doc || '', files: [] }
+    entry.files.push(f)
+    byModule.set(matched, entry)
+  }
+  return { byModule, unmapped }
+}
+
+/** "h ct" 输出解析（git log -1 --format=%h %ct 的单行值）→ { h, ct }；空输出 → null。
+ *  刻意不额外校验 ct 可析性——与 moduleDebt 原内联解析逐字等价（含畸形输出 NaN ct 形态），
+ *  保证公共抽取零行为漂移。 */
+function parseHct(out) {
+  if (!out || !out.trim()) return null
+  const [h, ct] = out.trim().split(' ')
+  return { h, ct: parseInt(ct, 10) }
+}
+
+/** behind 公共口径（D-004；2026-08-23-adopt-harness-practices task-05 抽公共实现）：双 commit
+ *  时间戳判方向 + rev-list 计数。src.ct >= ref.ct → rev-list --count ref..src（git 失败 →
+ *  behind=null + degraded=true，不抛）；src 时间戳落后 ref → behind=0。ct 相等也进对账
+ *  （同一秒内的提交——测试/快速序列场景），由 rev-list count 分晓。
+ *  moduleDebt 与 computeModuleBehind 共用——behind 口径单一真相源。 */
+function behindWithDirection(gitRoot, srcCommit, refCommit) {
+  if (srcCommit.ct >= refCommit.ct) {
+    const cnt = safeGit(gitRoot, ['rev-list', '--count', `${refCommit.h}..${srcCommit.h}`], { timeout: GIT_TIMEOUT_MS })
+    const behind = cnt.error ? null : parseInt(cnt.value, 10)
+    return { behind, degraded: behind === null }
+  }
+  return { behind: 0, degraded: false }
+}
+
+/** 单模块欠账：双 commit 时间戳判方向 + rev-list 计数（复用 parseHct/behindWithDirection 公共
+ * 实现，抽取前后逐字等价，C-10）。全失败 → behind null + 注记。
+ * docGitPath：模块卡的 git 相对路径（specBase 相对 projectRoot 换算——specBase 在项目内时
+ * 是 .sillyspec/docs/<p>/modules/<id>.md；平台模式 specBase 在仓外时卡片不在 git 内 →
+ * docLog 恒失败 → 走"从未提交"形态，如实呈现）。 */
+function moduleDebt(projectRoot, moduleId, entry, docGitPath, docGitRoot) {
+  const notes = []
+  const srcPaths = entry.files
+  const srcLog = safeGit(projectRoot, ['log', '-1', '--format=%h %ct', '--', ...srcPaths], { timeout: GIT_TIMEOUT_MS })
+  let behind = null
+  let srcCommit = null
+  let docCommit = null
+  let neverCommitted = false
+  srcCommit = (!srcLog.error && srcLog.value) ? parseHct(srcLog.value) : null
+  if (!srcCommit) notes.push('源码 commit 历史不可得（新文件或 git 失败）')
+  if (docGitPath) {
+    // 卡片历史在卡片所在 git 仓查（docGitRoot；linked worktree 场景 = 主仓根），
+    // 源码历史在 projectRoot 查——两侧 commit 同属一个仓库历史可 rev-list 对账
+    const docGitCwd = docGitRoot || projectRoot
+    const docLog = safeGit(docGitCwd, ['log', '-1', '--format=%h %ct', '--', docGitPath], { timeout: GIT_TIMEOUT_MS })
+    docCommit = (!docLog.error && docLog.value) ? parseHct(docLog.value) : null
+    if (!docCommit) neverCommitted = true
+  }
+  if (srcCommit && !docCommit) {
+    // 有源码历史但卡片从未提交 → 欠账最重形态
+    return { module: moduleId, ...entry, srcCommit: srcCommit.h, docCommit: null, behind: null, neverCommitted: true, notes }
+  }
+  if (srcCommit && docCommit) {
+    behind = behindWithDirection(docGitRoot || projectRoot, srcCommit, docCommit).behind
+    if (behind === null) notes.push('rev-list 失败降级')
+  }
+  return { module: moduleId, ...entry, srcCommit: srcCommit?.h || null, docCommit: docCommit?.h || null, behind, neverCommitted, notes }
+}
+
+/**
+ * 公共导出（C-10，2026-08-23-adopt-harness-practices task-05）：模块源码在参考 commit 后的
+ * 前进数（behind）。口径同 moduleDebt（D-004：双 commit 时间戳判方向 + rev-list 计数，复用
+ * behindWithDirection；git 失败/输入缺失 → behind=null + degraded=true，不抛）。
+ * 消费方：docs-check 决策规则 behind 复核（决策锚定模块源码在「最近确认」commit 后的前进数）。
+ * 不改 moduleDebt 对外行为与既有返回结构（computeDocsDebt / matchFilesToModules 输出不变）。
+ * @param {string} moduleId 模块 id（_module-map.yaml 键；决策规则里 = 条目所在域文件名）
+ * @param {string} lastConfirmedCommit 参考 commit（决策「最近确认」hash；空/「未记录」/非 hash 串 → degraded）
+ * @param {{ projectRoot?: string, srcPaths?: string[], moduleIndex?: object }} [opts]
+ *   projectRoot git 锚（缺省 process.cwd()）；srcPaths 显式源码路径集（优先）；
+ *   moduleIndex _module-map 解析结果（平铺或 {modules} 包裹均可，取该模块 paths∪core_files 兜底）
+ * @returns {{ behind: number|null, degraded: boolean }} degraded=true = behind 不可得
+ *   （路径集为空 / 参考 commit 不可解析 / git 失败），调用方降级呈现不阻断
+ */
+export function computeModuleBehind(moduleId, lastConfirmedCommit, opts = {}) {
+  const projectRoot = opts.projectRoot || process.cwd()
+  let srcPaths = Array.isArray(opts.srcPaths) ? opts.srcPaths.filter(Boolean).map(p => String(p)) : null
+  if ((!srcPaths || srcPaths.length === 0) && opts.moduleIndex) {
+    const flat = opts.moduleIndex.modules ? opts.moduleIndex.modules : opts.moduleIndex
+    const m = flat && typeof flat === 'object' ? flat[moduleId] : null
+    if (m) srcPaths = [...(Array.isArray(m.paths) ? m.paths : []), ...(Array.isArray(m.core_files) ? m.core_files : [])]
+  }
+  if (!srcPaths || srcPaths.length === 0) return { behind: null, degraded: true }
+  const ref = String(lastConfirmedCommit || '').trim()
+  if (!/^[0-9a-f]{4,40}$/i.test(ref)) return { behind: null, degraded: true }
+  const srcCommit = parseHct(safeGit(projectRoot, ['log', '-1', '--format=%h %ct', '--', ...srcPaths], { timeout: GIT_TIMEOUT_MS }).value)
+  const refCommit = parseHct(safeGit(projectRoot, ['log', '-1', '--format=%h %ct', ref], { timeout: GIT_TIMEOUT_MS }).value)
+  if (!srcCommit || !refCommit) return { behind: null, degraded: true }
+  return behindWithDirection(projectRoot, srcCommit, refCommit)
+}
+
+/**
+ * IO 入口：算模块文档欠账事实。
+ * @param {{ projectRoot: string, specBase: string, projectName: string, changedFiles: string[] }} opts
+ *   projectRoot：git 锚（worktree 根或 cwd）；specBase/projectName：module-map 与卡片定位
+ * @returns {{ ok: boolean, facts: string, entries: object[], unmapped: string[] }}
+ *   ok=false = 归属数据缺失（map 不存在/解析空）→ facts 为单行说明
+ *   facts 空 = 无债（调用方零输出）
+ */
+export function computeDocsDebt(opts) {
+  const { projectRoot, specBase, projectName, changedFiles = [] } = opts || {}
+  const cardsDir = specBase && projectName ? join(specBase, 'docs', projectName, 'modules') : null
+  const mapPath = cardsDir ? join(cardsDir, '_module-map.yaml') : null
+  if (!mapPath || !existsSync(mapPath)) {
+    return { ok: false, facts: '[docs-debt] 无 _module-map.yaml，模块归属数据缺失（跑 sillyspec modules rebuild 生成）', entries: [], unmapped: changedFiles }
+  }
+  let moduleIndex
+  try {
+    moduleIndex = parseModuleMapSimple(readFileSync(mapPath, 'utf8'))
+  } catch (e) {
+    return { ok: false, facts: `[docs-debt] module-map 解析失败（${e.message}），跳过欠账计算`, entries: [], unmapped: changedFiles }
+  }
+  if (!moduleIndex || Object.keys(moduleIndex.modules ? moduleIndex.modules : moduleIndex).length === 0) {
+    return { ok: false, facts: '[docs-debt] module-map 解析为空（0 模块），归属数据缺失', entries: [], unmapped: changedFiles }
+  }
+  const { byModule, unmapped } = matchFilesToModules(changedFiles, moduleIndex, { cardsDir })
+  if (byModule.size === 0) {
+    return { ok: true, facts: '', entries: [], unmapped }
+  }
+  const entries = []
+  // doc 的 git 锚定（execute 审查 FAIL-1 修复）：卡片查询按 specBase 所在 git 仓根算相对路径，
+  // 不按 projectRoot——dogfood execute 场景 projectRoot=worktree 而 specBase=主仓/.sillyspec，
+  // linked worktree 共享 git 历史，git -C <worktree> log -- <主仓相对路径> 查得到卡片真实历史；
+  // 若按 projectRoot relative 判 null 会把"卡片在主仓 git 内"误报为"从未提交"（假事实）。
+  // 平台模式 specRoot 在仓外（git -C specBase 失败/无 git）→ docGitPath=null 走"从未提交"如实呈现。
+  let docGitRoot = null
+  let docPathPrefix = null
+  try {
+    const specTop = safeGit(specBase, ['rev-parse', '--show-toplevel'], { timeout: GIT_TIMEOUT_MS })
+    if (!specTop.error && specTop.value) {
+      docGitRoot = specTop.value.trim()
+      // macOS 坑：git 返回 realpath（/var → /private/var 的 symlink 解析），cardsDir 可能是
+      // symlink 形态（tmpdir/用户项目路径经符号链接）——两侧不归一时 relative() 产出 ../..
+      // 前缀 → 卡片被误判"从未提交"（假账）。两侧 realpathSync 归一后再算（失败回退原值）。
+      const rel = relative(realpathSafe(docGitRoot), realpathSafe(cardsDir))
+      if (rel && !rel.startsWith('..')) docPathPrefix = rel.replace(/\\/g, '/')
+    }
+  } catch { /* 保持 null */ }
+  for (const [id, entry] of byModule) {
+    const docGitPath = docPathPrefix && entry.doc ? `${docPathPrefix}/${entry.doc.replace(/^modules\//, '')}` : null
+    entries.push(moduleDebt(projectRoot, id, entry, docGitPath, docGitPath ? docGitRoot : null))
+  }
+  // 只报欠账（behind>0 / neverCommitted / behind=null 降级注记）；behind=0 不出（无债零输出）
+  const debtEntries = entries.filter(e => e.neverCommitted || (e.behind !== null && e.behind > 0) || (e.behind === null && !e.neverCommitted))
+  if (debtEntries.length === 0) return { ok: true, facts: '', entries, unmapped }
+  const lines = ['[docs-debt] 本变更已触及以下模块（CLI 算，diff × _module-map.yaml，累计）：']
+  for (const e of debtEntries) {
+    if (e.neverCommitted) {
+      lines.push(`  - ${e.module}：模块卡 ${e.doc} 从未提交（欠账最重）`)
+    } else if (e.behind === null) {
+      lines.push(`  - ${e.module}：欠账数不可得（${(e.notes || []).join('；') || 'git 降级'}）`)
+    } else {
+      lines.push(`  - ${e.module}：源码 ${e.behind} commit 未同步卡（卡停 ${e.docCommit}，源码到 ${e.srcCommit}）`)
+    }
+    // O-2（docs-signals-o12）：内联卡片失效引用 + 建议行号——agent 从"知道欠账"到"知道改哪行"。
+    // 守卫 docGitPath && docGitRoot（D-004 同锚；平台模式仓外跳过）；每模块上限 3 条（D-002）；
+    // 异常整块降级跳过（advisory 链不因增强而脆）。
+    const inline = inlineCardInvalidRefs(e, docGitRoot, docPathPrefix)
+    if (inline) lines.push(inline)
+    lines.push(`    涉及文件：${e.files.join(', ')}`)
+  }
+  return { ok: true, facts: lines.join('\n'), entries, unmapped }
+}
+
+/** O-2：欠账模块卡片的失效引用内联行（docs check 层1 单文档）。无失效/不可跑 → null。 */
+function inlineCardInvalidRefs(entry, docGitRoot, docPathPrefix) {
+  if (!docGitRoot || !docPathPrefix || !entry.doc) return null
+  try {
+    const docGitPath = `${docPathPrefix}/${entry.doc.replace(/^modules\//, '')}`
+    // HUB-06：补传 crossRepoRoots（与 docs gate 同口径），repo:// 跨仓引用不再恒跳过；
+    // 配置读取失败（无 local.yaml 段等）→ 不启用跨仓，与原行为一致
+    let crossRepoRoots
+    try { crossRepoRoots = readDocsCheckConfig(docGitRoot)?.crossRepoRoots } catch { crossRepoRoots = undefined }
+    const check = runDocsCheck({ projectRoot: docGitRoot, docs: [docGitPath], crossRepoRoots })
+    if (check.ok || !Array.isArray(check.invalid) || check.invalid.length === 0) return null
+    const parts = check.invalid.slice(0, 3).map((inv) => {
+      const sug = Array.isArray(inv.suggest) && inv.suggest.length > 0 ? `→建议 L${inv.suggest.join('/L')}` : ''
+      return `${inv.ref || inv.doc}${sug}`
+    })
+    const more = check.invalid.length > 3 ? ` · 等 ${check.invalid.length} 处` : ''
+    return `    卡内失效引用 ${check.invalid.length} 处：${parts.join(' · ')}${more}`
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 决策锚点触碰事实（change: 2026-08-24-decision-touch-cli-drift task-01，W-A）
+// 同「CLI 算事实注入」原则：execute 期改到决策锚定文件时立即呈现「触碰 N 条决策锚点」
+// 事实（advisory 不阻断，无触碰零输出）。条目解析/锚点剥离复用 docs-check 口径
+// （parseDecisionEntries + anchorFilePath 静态 import，本文件已 import docs-check 无环），
+// 勿复刻正则防两处口径漂移。
+// ---------------------------------------------------------------------------
+
+/** 触碰事实行条数上限（R-05 prompt 体积）：超出截断 +「…另有 N 条」 */
+export const DECISION_TOUCH_RENDER_LIMIT = 5
+
+/**
+ * 纯事实计算：变更文件 × 决策锚点前缀匹配 → 触碰事实（唯一真相形态）。
+ * @param {string[]} changedFiles 变更文件（入口统一 POSIX 化——调用方不重复处理）
+ * @param {string} knowledgeRoot 知识库根（<specBase>/knowledge；decisions 库在其 decisions/ 子目录，
+ *   与 docs-check runDecisionRules 的 <specBase>/knowledge/decisions 同布局）
+ * @returns {{ touches: Array<{ id: string, title: string, anchorFile: string, touchedFile: string, file: string }>, empty: boolean }}
+ *   touches 每项 = 一条 implemented 决策 × 一个命中变更文件（file = 条目来源域文件
+ *   knowledge/decisions/<域>.md）；empty=true = decisions 库不存在（冷启动）；
+ *   无触碰 → touches=[] 且 empty=false（零输出由渲染层保证）
+ */
+export function computeDecisionTouches(changedFiles, knowledgeRoot) {
+  const emptyResult = { touches: [], empty: true }
+  if (!knowledgeRoot) return emptyResult
+  const decisionsDir = join(knowledgeRoot, 'decisions')
+  let domainFiles = []
+  try {
+    domainFiles = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).sort()
+  } catch {
+    return emptyResult // decisions 库不存在 → 零信号（与 runDecisionRules 冷启动同语义）
+  }
+  const changed = (Array.isArray(changedFiles) ? changedFiles : [])
+    .filter(Boolean).map(f => String(f).replace(/\\/g, '/'))
+  const touches = []
+  for (const f of domainFiles) {
+    const file = `knowledge/decisions/${f}`
+    let entries
+    try { entries = parseDecisionEntries(readFileSync(join(decisionsDir, f), 'utf8')) } catch { continue }
+    for (const e of entries) {
+      if ((e.status || '').toLowerCase() !== 'implemented') continue // 仅 implemented（对齐 docs-check.js:793 先例，rejected 不提示）
+      const anchorPath = anchorFilePath(e.anchor) // 剥 :行号/:行号-行号/:符号 后缀 + POSIX 化；「未记录」/空 → null 跳过
+      if (!anchorPath) continue
+      for (const c of changed) {
+        // 前缀匹配粒度 = 文件或其子路径（R-03：锚点是文件级非目录级，防同前缀不同文件误报）
+        if (c === anchorPath || c.startsWith(anchorPath + '/')) {
+          touches.push({ id: e.id, title: e.title, anchorFile: anchorPath, touchedFile: c, file })
+        }
+      }
+    }
+  }
+  touches.sort((a, b) => a.file.localeCompare(b.file) || a.id.localeCompare(b.id) || a.touchedFile.localeCompare(b.touchedFile))
+  return { touches, empty: false }
+}
+
+/**
+ * 触碰事实 → 事实行文本（advisory）：无触碰返回 ''（零输出）；≤DECISION_TOUCH_RENDER_LIMIT 条
+ * 逐条呈现，超出截断加「…另有 N 条」（R-05）。双渲染点（run/prompt.js {DOCS_DEBT} 注入处 +
+ * stages/execute.js buildWavePrompt）共用同一渲染实现，防两处文案漂移。
+ * @param {Array<{ id: string, title: string, anchorFile: string, touchedFile: string, file: string }>} touches
+ * @returns {string}
+ */
+export function renderDecisionTouchFacts(touches) {
+  if (!Array.isArray(touches) || touches.length === 0) return ''
+  const shown = touches.slice(0, DECISION_TOUCH_RENDER_LIMIT)
+  const lines = [`[decision-touch] 本次变更触碰 ${touches.length} 条决策锚点（改动可能使该决策需复核）：`]
+  for (const t of shown) {
+    lines.push(`  - ${t.id}（${t.title || '无标题'}，锚点 ${t.anchorFile}）← 触碰文件 ${t.touchedFile}（${t.file}）`)
+  }
+  if (touches.length > DECISION_TOUCH_RENDER_LIMIT) {
+    lines.push(`  …另有 ${touches.length - DECISION_TOUCH_RENDER_LIMIT} 条`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * execute 期事实注入的 changedFiles 公共口径（D-003 主/次渲染点同源，勿双写）：
+ * worktree 根解析（changeName → <specBase>/.runtime/worktrees/<changeName>/ 存在即锚，
+ * 否则 cwd/显式 projectRoot）+ porcelain 未提交（剥 .sillyspec/ 前缀、rename 取新路径）∪
+ * worktree meta.json baselineCommit..HEAD 已提交并集，POSIX 化。从 run/prompt.js {DOCS_DEBT}
+ * 内联实现抽取（行为逐字等价）；execute.js buildWavePrompt（主渲染点）同源复用。
+ * git 失败/meta 读失败 → 只用可用集合，不抛。
+ * @param {{ specBase?: string, changeName?: string|null, cwd?: string|null, projectRoot?: string|null }} opts
+ * @returns {{ root: string, changedFiles: string[] }} root = 实际 git 锚（computeDocsDebt 的 projectRoot 同值）
+ */
+export function collectExecuteChangedFiles({ specBase, changeName, cwd, projectRoot } = {}) {
+  const wtRoot = specBase ? join(specBase, '.runtime', 'worktrees', changeName || '') : null
+  const root = projectRoot || (wtRoot && changeName && existsSync(wtRoot) ? wtRoot : cwd) || process.cwd()
+  const changed = new Set()
+  const statusRes = safeGit(root, ['status', '--porcelain'], { trim: false })
+  if (!statusRes.error && statusRes.value) {
+    for (const line of statusRes.value.split('\n')) {
+      if (!line.trim()) continue
+      // "XY path" / rename "R  old -> new" 取 new
+      const pathPart = line.slice(3).split('->').pop().trim().replace(/"/g, '')
+      if (pathPart && !pathPart.startsWith('.sillyspec/')) changed.add(pathPart.replace(/\\/g, '/'))
+    }
+  }
+  const metaPath = wtRoot ? join(wtRoot, 'meta.json') : null
+  if (metaPath && changeName && existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
+      if (meta.baselineCommit) {
+        const diffRes = safeGit(root, ['diff', '--name-only', `${meta.baselineCommit}..HEAD`], { trim: false })
+        if (!diffRes.error && diffRes.value) {
+          for (const f of diffRes.value.split('\n')) {
+            if (f.trim() && !f.trim().startsWith('.sillyspec/')) changed.add(f.trim().replace(/\\/g, '/'))
+          }
+        }
+      }
+    } catch { /* meta 读失败只用未提交集 */ }
+  }
+  return { root, changedFiles: [...changed] }
+}

package/.claude/worktrees/sillyspec-data-model-research/src/docs-gate.js

@@ -0,0 +1,107 @@
+/**
+ * docs gate：docs check 的 ratchet 门（欠账只许减少不许增加）。
+ *
+ * 动机（doc-consistency-debt 第七节裁决）：behind 计数是代理信号不能当阈值（源码活跃
+ * 不代表卡错，误报会让所有人学会忽略报警）；docs check 失效数是直接信号（每条都是
+ * 具体的错），ratchet 语义 = 失效数 ≤ 基线即过、超基线拦——不管历史存量，只拦增量。
+ *
+ * 基线文件：.sillyspec/docs-check-baseline（纯数字一行，可手工改）。首次无基线时
+ * 必须显式 --init-baseline 生成（不悄悄合法化存量欠账——与 quick fail-closed 调性
+ * 一致）；--init-baseline 幂等，重跑以当前实测数覆盖。
+ *
+ * exit code：0 过（≤基线）/ 1 拦（>基线）/ 2 配置或 IO 错误（含无基线）。
+ * 纯判定逻辑（evaluateRatchet）与 IO 面（runDocsGate）分离，前者可单测。
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError } from './docs-check.js';
+
+/** 基线文件名（相对 specBase/.sillyspec 根；specBase 由调用方传入完整路径锚） */
+export const BASELINE_FILENAME = 'docs-check-baseline';
+
+/** 展示用基线路径（文案用，POSIX 风格；join 防 specBase 带不带尾分隔符两种形态） */
+function baselineDisplay(specBase) {
+  return [specBase.replace(/[\\/]+$/, ''), BASELINE_FILENAME].join('/').replace(/\\/g, '/');
+}
+
+/**
+ * 纯判定：ratchet 语义。
+ * @param {{ current: number, baseline: number }} r
+ * @returns {{ ok: boolean, delta: number, message: string }}
+ *   delta = current - baseline；负值（清偿了）提示可下调基线但不强制。
+ */
+export function evaluateRatchet({ current, baseline }) {
+  const delta = current - baseline;
+  if (delta <= 0) {
+    const hint = delta < 0
+      ? `✅ docs gate: ${current} 处失效 ≤ 基线 ${baseline}（清偿了 ${-delta} 处，可跑 --init-baseline 下调基线锁住成果）`
+      : `✅ docs gate: ${current} 处失效 = 基线 ${baseline}，放行`;
+    return { ok: true, delta, message: hint };
+  }
+  return {
+    ok: false, delta,
+    message: `❌ docs gate: ${current} 处失效 > 基线 ${baseline}（新增 ${delta} 处），拦截。修掉新增引用或显式 --init-baseline 重置基线（需你确认存量合法）`,
+  };
+}
+
+/** 读基线：不存在返回 null（调用方决定 init 或报错）；内容非数字行返回 NaN（按损坏报错）。 */
+export function readBaseline(specBase) {
+  const p = join(specBase, BASELINE_FILENAME);
+  if (!existsSync(p)) return null;
+  const raw = readFileSync(p, 'utf8').trim();
+  const n = parseInt(raw, 10);
+  return Number.isInteger(n) && n >= 0 ? n : NaN;
+}
+
+/** 写基线（--init-baseline）：以实测当前失效数覆盖。 */
+export function writeBaseline(specBase, value) {
+  writeFileSync(join(specBase, BASELINE_FILENAME), `${value}\n`, 'utf8');
+}
+
+/**
+ * IO 入口：跑一次 gate。
+ * @param {{ projectRoot: string, specBase: string, initBaseline?: boolean }} opts
+ *   projectRoot 源码仓根（docs check 锚）；specBase .sillyspec 根（基线文件所在）
+ * @param {object} checkOpts 透传 runDocsCheck（paths/skip/keywordAssert 覆盖；缺省读 local.yaml）
+ * @returns {Promise<{ exitCode: 0|1|2, ok: boolean, current: number, baseline: number|null,
+ *                     delta: number|null, message: string, inited: boolean }>}
+ */
+export async function runDocsGate(opts = {}, checkOpts = {}) {
+  const { projectRoot, specBase, initBaseline = false } = opts;
+  let result;
+  try {
+    const cfg = readDocsCheckConfig(projectRoot);
+    result = runDocsCheck({
+      projectRoot,
+      paths: checkOpts.paths || cfg.paths,
+      skip: checkOpts.skip || cfg.skip,
+      keywordAssert: checkOpts.keywordAssert ?? cfg.keywordAssert,
+      crossRepoRoots: checkOpts.crossRepoRoots || cfg.crossRepoRoots,
+    });
+  } catch (e) {
+    if (e instanceof DocsCheckConfigError) {
+      return { exitCode: 2, ok: false, current: null, baseline: null, delta: null, message: `docs gate 配置错误：${e.message}`, inited: false };
+    }
+    throw e;
+  }
+  const current = result.invalid.length;
+
+  if (initBaseline) {
+    writeBaseline(specBase, current);
+    return { exitCode: 0, ok: true, current, baseline: current, delta: 0, message: `📌 docs gate: 基线已初始化为当前实测 ${current} 处失效（${baselineDisplay(specBase)}）`, inited: true };
+  }
+
+  const baseline = readBaseline(specBase);
+  if (baseline === null) {
+    return {
+      exitCode: 2, ok: false, current, baseline: null, delta: null,
+      message: `❌ docs gate: 无基线文件（${baselineDisplay(specBase)}）。首次使用先跑 sillyspec docs gate --init-baseline（以当前实测数立基线，存量既往不咎只拦增量）`,
+      inited: false,
+    };
+  }
+  if (Number.isNaN(baseline)) {
+    return { exitCode: 2, ok: false, current, baseline: null, delta: null, message: `❌ docs gate: 基线文件损坏（非非负整数），手工修正或 --init-baseline 重置`, inited: false };
+  }
+  const v = evaluateRatchet({ current, baseline });
+  return { exitCode: v.ok ? 0 : 1, ok: v.ok, current, baseline, delta: v.delta, message: v.message, inited: false };
+}