sillyspec 3.26.7 → 3.26.8

package/src/docs-check.js

@@ -0,0 +1,333 @@
+/**
+ * docs-check — 文档行号引用校验核心（change: 2026-08-15-docs-check-productize）
+ *
+ * 从 dogfood 私有测试 test/doc-ref-check.test.mjs 抽离产品化（design D-001~D-008）：
+ *   层1 存在性（所有引用必查）：文件存在 + 行号 ≥1 且 ≤ 总行数（范围引用查 end）
+ *   层2 关键词断言（keywordAssert 可配，缺省开）：引用所在文档行内的反引号代码符号 token，
+ *       断言源文件 [start-2, end+5] 窗口（实现期口径，非对称——文档行号常指向块起始行
+ *       而 token 在体首几行）内含任一 token。多候选宽容：裸文件名多命中时任一候选全过即通过。
+ *
+ * 纯函数（collectDocRefs/looksLikeCodeSymbol/validateRefLines/extractExpectedTokensFromLine）
+ * 无 fs 依赖可单测；resolveCandidates/walkGlob/runDocsCheck 是 IO 面。
+ * 只读校验（不修改任何被校验文件）；纯 Node 内置模块零依赖（D-008：glob 手写 walker，
+ * 仅「目录递归」「目录单层」「字面路径」三形态）；Windows 路径归一化；兼容 CRLF/LF。
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import jsYaml from 'js-yaml'
+
+/** 提取 file.js:line / file.js:start-end 引用（.js/.mjs，反引号包裹与裸文本均命中，全文扫描 D-006） */
+export const REF_RE = /([A-Za-z0-9_.\-\/]+\.(?:js|mjs)):(\d+)(?:-(\d+))?/g
+
+/**
+ * 读 local.yaml 的 docs-check 段（best-effort，绝不抛；缺文件/无段 → 全缺省）。
+ * @param {string} projectRoot 源码仓根（local.yaml 在 <root>/.sillyspec/local.yaml）
+ * @returns {{ paths?: string[], skip: string[], keywordAssert: boolean }}
+ */
+export function readDocsCheckConfig(projectRoot) {
+  const fallback = { paths: null, skip: [], keywordAssert: true }
+  try {
+    const p = join(projectRoot, '.sillyspec', 'local.yaml')
+    if (!existsSync(p)) return fallback
+    const doc = jsYaml.load(readFileSync(p, 'utf8'))
+    if (!doc || typeof doc !== 'object') return fallback
+    const dc = doc['docs-check']
+    if (!dc || typeof dc !== 'object') return fallback
+    return {
+      paths: Array.isArray(dc.paths) ? dc.paths.filter(s => typeof s === 'string') : null,
+      skip: Array.isArray(dc.skip) ? dc.skip.filter(s => typeof s === 'string') : [],
+      keywordAssert: typeof dc.keywordAssert === 'boolean' ? dc.keywordAssert : true,
+    }
+  } catch {
+    return fallback
+  }
+}
+
+/** 配置错误（glob 形态不支持等）→ CLI exit 2 */
+export class DocsCheckConfigError extends Error {}
+
+/**
+ * 纯函数：从 markdown 全文提取全部 file:line 引用。
+ * @param {string} md 文档全文
+ * @returns {Array<{ ref, file, start, end, docLine }>} docLine 为 1-based 文档行号
+ */
+export function collectDocRefs(md) {
+  if (!md || typeof md !== 'string') return []
+  const refs = []
+  const re = new RegExp(REF_RE.source, 'g')
+  let m
+  while ((m = re.exec(md)) !== null) {
+    refs.push({
+      ref: m[0],
+      file: m[1],
+      start: parseInt(m[2], 10),
+      end: m[3] !== undefined ? parseInt(m[3], 10) : parseInt(m[2], 10),
+      docLine: md.slice(0, m.index).split(/\r?\n/).length,
+    })
+  }
+  return refs
+}
+
+/**
+ * 纯函数：判定 token 是否「像代码符号」：首字符字母/_/$，且含大写字母/下划线/点/$ 之一。
+ * 纯小写英文单词（local/platform/abort）→ false（自然语言，跳过断言防误报）。
+ */
+export function looksLikeCodeSymbol(token) {
+  if (!/^[A-Za-z_$][A-Za-z0-9_$.]*$/.test(token)) return false
+  return /[A-Z_$.]/.test(token)
+}
+
+/**
+ * 纯函数：层1 行号边界校验。
+ * @param {number} totalLines 源文件总行数
+ * @param {number} start 1-based 起始行
+ * @param {number} end 1-based 结束行（单行引用 = start）
+ * @returns {{ ok: boolean, reasons: string[] }}
+ */
+export function validateRefLines(totalLines, start, end) {
+  const reasons = []
+  if (start < 1 || start > totalLines) reasons.push(`行号超界（start=${start} > 总行数 ${totalLines}）`)
+  if (end < start || end > totalLines) reasons.push(`范围 end=${end} 超界（总行数 ${totalLines}）`)
+  return { ok: reasons.length === 0, reasons }
+}
+
+/**
+ * 纯函数：层2 token 提取——引用所在的文档行内所有反引号 token 中的代码符号。
+ * token 归一：①剥函数括号（getDispatchMode()）；②点分名拆段（syncMod.checkApproval → 两段）。
+ * 空数组 = 纯位置引用，跳过层2。
+ * @param {string} line 引用所在的文档行全文
+ * @returns {string[]} token 列表
+ */
+export function extractExpectedTokensFromLine(line) {
+  if (!line || typeof line !== 'string') return []
+  const tokens = new Set()
+  for (const mm of line.matchAll(/`([^`\n]{1,60})`/g)) {
+    const t = mm[1].split('(')[0].trim()
+    if (!looksLikeCodeSymbol(t)) continue
+    tokens.add(t)
+    if (t.includes('.')) {
+      for (const seg of t.split('.')) {
+        if (looksLikeCodeSymbol(seg)) tokens.add(seg)
+      }
+    }
+  }
+  return [...tokens]
+}
+
+/** 递归收集 dir 下与 baseName 同名的文件（相对 dir 的 POSIX 路径数组；排除 node_modules/.git） */
+function findInTree(dir, baseName, rel = '') {
+  const out = []
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    if (e.name === 'node_modules' || e.name === '.git') continue
+    const relPath = rel ? `${rel}/${e.name}` : e.name
+    if (e.isDirectory()) out.push(...findInTree(join(dir, e.name), baseName, relPath))
+    else if (e.name === baseName) out.push(relPath)
+  }
+  return out
+}
+
+/**
+ * 解析引用文件 → 候选绝对路径数组。文档写法三种混用（首跑实证）：
+ * ①仓库根相对（src/sync.js / docs/...）→ 直拼；②src/ 内部相对（dispatch/probe.js）→
+ * src/ 前缀重试；③裸中缀（backends/sillyhub-mcp.js）→ src/ 树内按路径后缀匹配。
+ * 空数组 = 不存在。
+ */
+export function resolveCandidates(projectRoot, refFile) {
+  if (refFile.includes('/')) {
+    const direct = join(projectRoot, refFile)
+    if (existsSync(direct)) return [direct]
+    const inSrc = join(projectRoot, 'src', refFile)
+    if (existsSync(inSrc)) return [inSrc]
+    const slash = refFile.lastIndexOf('/')
+    const baseName = slash === -1 ? refFile : refFile.slice(slash + 1)
+    return findInTree(join(projectRoot, 'src'), baseName)
+      .filter((rel) => ('src/' + rel).endsWith('/' + refFile) || 'src/' + rel === 'src/' + refFile)
+      .map((rel) => join(projectRoot, 'src', rel))
+  }
+  return findInTree(join(projectRoot, 'src'), refFile).map((rel) => join(projectRoot, 'src', rel))
+}
+
+/** 读文件行数组（CRLF/LF 归一：split(/\r?\n/)，层2 只做子串查找不污染原文） */
+function readLines(absPath) {
+  try { return readFileSync(absPath, 'utf8').split(/\r?\n/) } catch { return null }
+}
+
+/** 简单通配匹配（skip 排除用，仅 * 单段） */
+function matchSimple(text, pattern) {
+  const parts = pattern.split('*')
+  let idx = 0
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '') continue
+    const found = text.indexOf(parts[i], idx)
+    if (found === -1) return false
+    if (i === 0 && found !== 0) return false
+    idx = found + parts[i].length
+  }
+  return true
+}
+
+/**
+ * glob walker（D-008：手写不引依赖）。仅支持三形态：
+ *   - `dir/「递归」*.ext` 递归收集（maxDepth 12 兜底防符号链接环）
+ *   - `dir/*.ext` 单层
+ *   - 字面路径直传（存在才返回）
+ * 其他形态（?、{a,b}、多层 * 混合等）抛 DocsCheckConfigError → CLI exit 2。
+ * @param {string} projectRoot 锚点（平台模式也锚源码仓根，design §3.3）
+ * @param {string} pattern glob 模式
+ * @param {string[]} skip 排除 glob（前缀或单 * 简单匹配）
+ * @returns {string[]} 命中文件的 POSIX 相对路径
+ */
+export function walkGlob(projectRoot, pattern, skip = []) {
+  const norm = (p) => p.replace(/\\/g, '/')
+  const isSkipped = (rel) => skip.some((s) => {
+    const sn = norm(s).replace(/\/$/, '')
+    return rel === sn || rel.startsWith(sn + '/') ||
+      (sn.includes('*') && matchSimple(rel, sn))
+  })
+  const matchExt = (name, ext) => name.endsWith(ext)
+  // 形态 1：**/*.ext
+  let m = norm(pattern).match(/^(.+?)\/\*\*\/\*(\.[A-Za-z0-9]+)$/)
+  if (m) {
+    const [, baseDir, ext] = m
+    const out = []
+    const rec = (dir, rel, depth) => {
+      if (depth > 12) return
+      let entries
+      try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+      for (const e of entries) {
+        if (e.name === 'node_modules' || e.name === '.git') continue
+        const relPath = rel ? `${rel}/${e.name}` : e.name
+        if (isSkipped(relPath)) continue
+        if (e.isDirectory()) rec(join(dir, e.name), relPath, depth + 1)
+        else if (matchExt(e.name, ext)) out.push(relPath)
+      }
+    }
+    rec(join(projectRoot, baseDir), baseDir, 0)
+    return out
+  }
+  // 形态 2：dir/*.ext（单层）
+  m = norm(pattern).match(/^(.+?)\/\*(\.[A-Za-z0-9]+)$/)
+  if (m) {
+    const [, baseDir, ext] = m
+    const out = []
+    let entries
+    try { entries = readdirSync(join(projectRoot, baseDir), { withFileTypes: true }) } catch { return out }
+    for (const e of entries) {
+      if (!e.isFile()) continue
+      const relPath = `${baseDir}/${e.name}`
+      if (isSkipped(relPath)) continue
+      if (matchExt(e.name, ext)) out.push(relPath)
+    }
+    return out
+  }
+  // 形态 3：字面路径（不含任何通配元字符才直传；含 ?、{ }、[ ] 等不支持形态落 error）
+  if (!/[*?{}\[\]]/.test(pattern)) {
+    return existsSync(join(projectRoot, pattern)) ? [norm(pattern)] : []
+  }
+  throw new DocsCheckConfigError(`不支持的 glob 形态：${pattern}（当前仅支持 dir/**/*.ext、dir/*.ext、字面路径）`)
+}
+
+/** 候选路径 → 相对 projectRoot 显示（失败信息用；Windows 反斜杠归一） */
+function relDisplay(absPath, projectRoot) {
+  return absPath
+    .replace(/\\/g, '/')
+    .replace(projectRoot.replace(/\\/g, '/') + '/', '')
+}
+
+/**
+ * IO 入口：跑一次完整校验。
+ * @param {{ projectRoot: string, docs?: string[], paths?: string[], skip?: string[], keywordAssert?: boolean }} opts
+ *   projectRoot 源码仓根（候选解析与 glob 的锚点，平台模式也传源码仓根）
+ *   docs 显式文档相对路径列表（优先于 paths glob 展开结果）
+ * @returns {{ ok: boolean, total: number, invalid: Array<{doc, docLine, ref, reason}>, warnings: string[], kwChecked: number }}
+ * @throws {DocsCheckConfigError} glob 形态不支持
+ */
+export function runDocsCheck(opts) {
+  // paths/docs 显式传 null（readDocsCheckConfig 无 local.yaml 段时的回退值）须落回缺省 glob，
+  // 解构默认值只挡 undefined 不挡 null——docs-check 无配置裸跑曾因此 null.flatMap 崩溃。
+  const { projectRoot, docs = null, paths: rawPaths = ['docs/**/*.md'], skip = [], keywordAssert = true } = opts || {}
+  const paths = Array.isArray(rawPaths) && rawPaths.length > 0 ? rawPaths : ['docs/**/*.md']
+  const warnings = []
+  if (keywordAssert === false) warnings.push('关键词断言已关闭（keywordAssert=false），仅做存在性校验')
+  const docFiles = docs && docs.length > 0
+    ? docs
+    : [...new Set(paths.flatMap((p) => walkGlob(projectRoot, p, skip)))].sort()
+
+  const invalid = []
+  let total = 0
+  let kwChecked = 0
+
+  for (const docRel of docFiles) {
+    const docAbs = join(projectRoot, docRel)
+    if (!existsSync(docAbs)) {
+      invalid.push({ doc: docRel, docLine: 0, ref: '', reason: '文档不存在' })
+      continue
+    }
+    const md = readFileSync(docAbs, 'utf8')
+    const refs = collectDocRefs(md)
+    const mdLines = md.split(/\r?\n/)
+
+    for (const r of refs) {
+      total++
+      const candidates = resolveCandidates(projectRoot, r.file)
+      if (candidates.length === 0) {
+        invalid.push({
+          doc: docRel, docLine: r.docLine, ref: r.ref,
+          reason: '文件不存在（含 / 按仓库根解析；裸文件名在 src/ 递归）',
+        })
+        continue
+      }
+      // 多候选宽容：逐候选跑层1+层2，任一全过即通过
+      const tokens = keywordAssert
+        ? extractExpectedTokensFromLine(mdLines[r.docLine - 1] || '')
+        : []
+      const candidateFails = []
+      let passedAny = false
+      for (const candAbs of candidates) {
+        const lines = readLines(candAbs)
+        if (lines === null) { candidateFails.push(`${relDisplay(candAbs, projectRoot)}: 读取失败`); continue }
+        const v = validateRefLines(lines.length, r.start, r.end)
+        // 层2：token 任一在 [start-2, end+5] 窗口命中即过
+        let kwOk = true
+        if (tokens.length > 0) {
+          const from = Math.max(0, r.start - 2)
+          const to = Math.min(lines.length, r.end + 5)
+          const window = lines.slice(from, to).join('\n')
+          kwOk = tokens.some((t) => window.includes(t))
+        }
+        if (v.ok && kwOk) { passedAny = true; break }
+        const reasons = [...v.reasons]
+        if (!kwOk) reasons.push(`关键词缺失：期望任一「${tokens.join(' / ')}」在 [start-2, end+5] 窗口内`)
+        candidateFails.push(`${relDisplay(candAbs, projectRoot)}: ${reasons.join('；')}`)
+      }
+      if (tokens.length > 0) kwChecked++
+      if (!passedAny) {
+        invalid.push({
+          doc: docRel, docLine: r.docLine, ref: r.ref,
+          reason: candidateFails.length > 1 ? `多候选全失败 → ${candidateFails.join(' | ')}` : candidateFails[0],
+          // 建议行号（--suggest）：token 在首个候选文件的全量命中行，供人工确认改锚——不自动改文件
+          suggest: suggestLines(candidates, tokens),
+        })
+      }
+    }
+  }
+
+  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked }
+}
+
+/**
+ * 建议行号计算（--suggest）：对失效引用，在候选文件里找 token 全量命中行。
+ * 无 token（纯行号断言）时返回空数组——没有符号线索无法定位，只能人工看。
+ */
+function suggestLines(candidates, tokens) {
+  if (tokens.length === 0) return []
+  try {
+    const lines = readLines(candidates[0])
+    if (lines === null) return []
+    const out = []
+    lines.forEach((l, i) => { if (tokens.some((t) => l.includes(t))) out.push(i + 1) })
+    return out.slice(0, 8)
+  } catch { return [] }
+}

package/src/docs-debt.js

@@ -0,0 +1,226 @@
+/**
+ * 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 } from 'node:fs'
+import { join, relative } from 'node:path'
+import { safeGit } from './git-helper.js'
+import { parseModuleMapSimple } from './modules.js'
+import { runDocsCheck } from './docs-check.js'
+
+/** safeGit 超时（大仓 git log 慢时降级该模块，不挂起 Wave 渲染） */
+const GIT_TIMEOUT_MS = 5000
+
+/**
+ * 纯函数：把 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 }
+}
+
+/** 单模块欠账：双 commit 时间戳判方向 + rev-list 计数。全失败 → 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
+  if (!srcLog.error && srcLog.value && srcLog.value.trim()) {
+    const [h, ct] = srcLog.value.trim().split(' ')
+    srcCommit = { h, ct: parseInt(ct, 10) }
+  } else {
+    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 })
+    if (!docLog.error && docLog.value && docLog.value.trim()) {
+      const [h, ct] = docLog.value.trim().split(' ')
+      docCommit = { h, ct: parseInt(ct, 10) }
+    } else {
+      neverCommitted = true
+    }
+  }
+  if (srcCommit && !docCommit) {
+    // 有源码历史但卡片从未提交 → 欠账最重形态
+    return { module: moduleId, ...entry, srcCommit: srcCommit.h, docCommit: null, behind: null, neverCommitted: true, notes }
+  }
+  if (srcCommit && docCommit) {
+    // ct 相等也进对账（同一秒内的提交——测试/快速序列场景），由 rev-list count 分晓
+    if (srcCommit.ct >= docCommit.ct) {
+      const cnt = safeGit(docGitRoot || projectRoot, ['rev-list', '--count', `${docCommit.h}..${srcCommit.h}`], { timeout: GIT_TIMEOUT_MS })
+      behind = cnt.error ? null : parseInt(cnt.value, 10)
+      if (behind === null) notes.push('rev-list 失败降级')
+    } else {
+      return { module: moduleId, ...entry, srcCommit: srcCommit.h, docCommit: docCommit.h, behind: 0, neverCommitted: false, notes }
+    }
+  }
+  return { module: moduleId, ...entry, srcCommit: srcCommit?.h || null, docCommit: docCommit?.h || null, behind, neverCommitted, notes }
+}
+
+/**
+ * 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()
+      const rel = relative(docGitRoot, 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\//, '')}`
+    const check = runDocsCheck({ projectRoot: docGitRoot, docs: [docGitPath] })
+    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
+  }
+}

package/src/docs-gate.js

@@ -0,0 +1,106 @@
+/**
+ * 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,
+    });
+  } 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 };
+}