sillyspec 3.26.7 → 3.26.9

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 };
+}

package/src/doctor-diagnostics.js

@@ -24,6 +24,7 @@ import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { CHECK_SEVERITY } from './constants.js';
+import { checkPlatformManaged } from './run/shared.js';
 
 // db 角色标签
 const DB_ROLE = {
@@ -216,8 +217,28 @@ function detectMultiDb(cwd, pointer) {
 
 // ── D2 pointer 健康 ───────────────────────────────────────────────────
 
-function detectPointerHealth(pointer) {
+function detectPointerHealth(pointer, cwd = null) {
   if (!pointer.present) {
+    // FR-06：指针缺失但接管声明存在 → 报 pointer_missing_but_managed（warning 非阻断）。
+    // 此状态 resolvePlatformSpecDir / runCommand 恢复链会 fail-closed 拒绝静默落本地，
+    // doctor 只读诊断给出同款恢复引导（不自动执行任何修复）。
+    if (cwd) {
+      const decl = checkPlatformManaged(cwd);
+      if (decl) {
+        return {
+          name: 'pointer_health',
+          label: '平台指针健康',
+          pass: false,
+          severity: CHECK_SEVERITY.WARNING,
+          findings: [
+            `pointer_missing_but_managed: 平台接管声明存在但恢复指针缺失（原 specRoot: ${decl.specRoot || '(未记录)'}）——` +
+            `裸调命令将 fail-closed 拒绝静默落本地。恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；` +
+            `② sillyspec platform disconnect（删除接管声明，彻底脱离平台）；③ 显式 --spec-dir <路径> 临时指定。`,
+          ],
+          safe_actions: [{ dimension: 'pointer_health', action: 'recreate_pointer', risk: 'confirm_required', rationale: '接管声明存在但指针缺失，需重建指针或显式脱离平台', next_step: '重跑平台 scan（带 --spec-root）或 sillyspec platform disconnect' }],
+        };
+      }
+    }
     return {
       name: 'pointer_health',
       label: '平台指针健康',
@@ -489,7 +510,7 @@ function detectExecuteProgressPlanMismatch(authoritySpecRoot, authDb) {
 export async function runDoctorDiagnostics({ cwd }) {
   const pointer = resolvePointer(cwd);
   const multiDb = detectMultiDb(cwd, pointer);
-  const pointerHealth = detectPointerHealth(pointer);
+  const pointerHealth = detectPointerHealth(pointer, cwd);
   const changesSplit = detectChangesSplit(cwd, pointer);
   const changeDb = detectChangeDbConsistency(cwd, pointer, multiDb);
 

package/src/git-helper.js

@@ -34,7 +34,7 @@ export function safeGit(cwd, args, opts = {}) {
   // 格式化（取首行）推迟到最终返回，避免重试分支重复格式化，并保留原始 code 供重试判定。
   const attempt = (t) => {
     try {
-      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t })
+      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t, stdio: ['ignore', 'pipe', 'pipe'] })
       if (trim) value = value.trim()
       return { value, errorObj: null }
     } catch (e) {
@@ -59,7 +59,7 @@ export function safeGit(cwd, args, opts = {}) {
 export function git(cwd, args, opts = {}) {
   const { trim = true, timeout = 5000 } = opts
   const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
-  const value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout })
+  const value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] })
   return trim ? value.trim() : value
 }
 

package/src/hooks/worktree-guard.js

@@ -748,7 +748,7 @@ export function shouldBlockWrite(filePath, cwd) {
  * @param {string} cwd - 当前工作目录
  * @returns {{ blocked: boolean, reason?: string }}
  */
-export function shouldBlockBash(command, cwd) {
+function shouldBlockBash(command, cwd) {
   if (!command || !command.trim()) return { blocked: false }
 
   const callerCwd = cwd || process.cwd()