sillyspec 3.27.2 → 3.27.5

package/src/docs-check.js

@@ -16,6 +16,7 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import jsYaml from 'js-yaml'
+import { parseModuleMapSimple } from './modules.js'
 
 /** 提取 file.js:line / file.js:start-end 引用（.js/.mjs，反引号包裹与裸文本均命中，全文扫描 D-006）。
  * repo:// 前缀（2026-08-20）：跨仓引用显式标记——`repo://<仓库名>/<路径>.js:行`。
@@ -596,3 +597,229 @@ export function applyFixes(projectRoot, fixes, opts = {}) {
 
   return { applied, skipped }
 }
+
+// ---------------------------------------------------------------------------
+// 决策规则族（advisory，change: 2026-08-23-adopt-harness-practices task-05，FR-06 / D-003@v1）
+//
+// 校验对象：knowledge/decisions/<模块域>.md 的 D-xxx@vN 条目（producer = decision-distill
+// 归档提炼，条目字段行 状态/锚点/最近确认 是本处的机械解析契约）。两项规则：
+//   1) 锚点校验：implemented 条目「锚点：src/…」路径存在性（锚点：未记录 → 补录提示，非失效）；
+//   2) behind 复核：锚定模块源码在「最近确认」commit 后的前进数超阈值 → 决策待复核提示
+//      （computeModuleBehind 复用 docs-debt 既有 git 口径，C-10）。
+// 铁律（docs-consistency 模块卡）：advisory 只 warn 不进 runDocsCheck 的 invalid 阻断链——
+// ok/invalid 判定与 docs gate 阻断行为不受影响；校验链路只读零写盘；无 decisions 库 /
+// 无超阈 → findings 空（无信号零输出）。豁免走 known_failures 新键 decisions.* 命名空间
+// （C-17：条目级语义键匹配，不复用 docs-gate 的 baseline ratchet）。
+// ---------------------------------------------------------------------------
+
+/** behind 复核缺省阈值（local.yaml decisions.behind_threshold 可调；schema 注册归 task-11，
+ *  本处读键按「存在则读、不存在用缺省」容错，不依赖 schema 注册）。dogfood 校准前取 10。 */
+export const DECISIONS_DEFAULT_BEHIND_THRESHOLD = 10
+
+/**
+ * known_failures 键提取——读法逐字对齐 verify-postcheck.extractKnownFailures（块式 + 流式，
+ * 剥引号/行内注释，CRLF 归一；注释互指防两处口径漂移）。此处独立复刻不 import
+ * verify-postcheck（重模块静态依赖；本模块仅消费 decisions.* 前缀键，见 isDecisionExempt）。
+ * @param {string} yamlText local.yaml 全文
+ * @returns {string[]} 键列表；无声明返回 []
+ */
+function extractKnownFailureKeys(yamlText) {
+  if (!yamlText) return []
+  const yaml = String(yamlText).replace(/\r\n?/g, '\n')
+  const inline = yaml.match(/^known_failures:\s*\[([^\]]*)\]\s*(?:#.*)?$/m)
+  if (inline) {
+    return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
+  }
+  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?)+)/m)
+  if (block) {
+    return (block[1].match(/^[ \t]+-[ \t]+(.+)/gm) || [])
+      .map(s => s.replace(/^[ \t]+-[ \t]+/, '').trim().replace(/^['"]|['"]$/g, '').replace(/#.*$/, '').trim())
+      .filter(Boolean)
+  }
+  return []
+}
+
+/**
+ * 读 local.yaml 的决策规则配置（best-effort 绝不抛；读取模式与 readDocsCheckConfig 一致：
+ * 缺文件/无段 → 全缺省）。decisions.behind_threshold 存在则读（数值校验），不存在用缺省 10
+ * ——schema 注册（config-schema.js）归 task-11，本处不依赖。
+ * @param {string} projectRoot 源码仓根（local.yaml 在 <root>/.sillyspec/local.yaml）
+ * @returns {{ behindThreshold: number, knownFailures: string[] }}
+ */
+export function readDecisionRulesConfig(projectRoot) {
+  const fallback = { behindThreshold: DECISIONS_DEFAULT_BEHIND_THRESHOLD, knownFailures: [] }
+  try {
+    const p = join(projectRoot, '.sillyspec', 'local.yaml')
+    if (!existsSync(p)) return fallback
+    const raw = readFileSync(p, 'utf8')
+    const knownFailures = extractKnownFailureKeys(raw)
+    const doc = jsYaml.load(raw)
+    if (!doc || typeof doc !== 'object') return { ...fallback, knownFailures }
+    const d = doc['decisions']
+    if (!d || typeof d !== 'object' || Array.isArray(d)) return { ...fallback, knownFailures }
+    const t = d['behind_threshold']
+    return {
+      behindThreshold: typeof t === 'number' && Number.isFinite(t) && t > 0 ? t : fallback.behindThreshold,
+      knownFailures,
+    }
+  } catch {
+    return fallback
+  }
+}
+
+/** 豁免键匹配（本变更范围先支持键匹配，非子串）：规则级 `decisions.<id>.<kind>` 精确命中，
+ *  或条目级 `decisions.<id>` 伞形命中（一条豁免该决策全部规则）。无 decisions. 前缀的键不参与。 */
+function isDecisionExempt(knownFailures, entryId, kind) {
+  const ruleKey = `decisions.${entryId}.${kind}`
+  const entryKey = `decisions.${entryId}`
+  return knownFailures.some(k => k === ruleKey || k === entryKey)
+}
+
+/**
+ * 纯函数：解析 knowledge/decisions/<域>.md 的 D-xxx@vN 条目（与 decision-distill.renderBlockLines
+ * 的写入契约对偶：producer=decision-distill → consumer=本规则族；字段行非列表项，顶层
+ * 「状态：/锚点：/最近确认：」标签精确匹配，防误吞正文）。旧格式字段缺失容错为 null。
+ * @param {string} md 域文件全文
+ * @returns {Array<{ id: string, title: string, status: string|null, anchor: string|null, lastConfirmed: string|null }>}
+ */
+export function parseDecisionEntries(md) {
+  const entries = []
+  let cur = null
+  const flush = () => { if (cur) entries.push(cur) }
+  for (const line of String(md || '').replace(/\r\n?/g, '\n').split('\n')) {
+    const h = line.match(/^##\s+(D-\d+)(?:@v(\d+))?\s*(.*)$/)
+    if (h) {
+      flush()
+      const version = h[2] ? parseInt(h[2], 10) : 1
+      cur = { id: `${h[1]}@v${version}`, title: h[3].trim(), status: null, anchor: null, lastConfirmed: null }
+      continue
+    }
+    if (!cur) continue
+    const f = line.match(/^(状态|锚点|最近确认)\s*[：:]\s*(.*)$/)
+    if (!f) continue
+    if (f[1] === '状态') cur.status = f[2].trim().split(/[\s（(]/)[0] || null
+    else if (f[1] === '锚点') cur.anchor = f[2].trim()
+    else cur.lastConfirmed = f[2].trim()
+  }
+  flush()
+  return entries
+}
+
+/** 锚点值 → 源码路径：剥「:行号 / :行号-行号 / :符号」后缀（锚点契约 `<src 路径>:<行号或符号>`；
+ *  旧条目可能只写路径）。「未记录」/空 → null（补录提示路径，非失效）。
+ *  export（2026-08-24-decision-touch-cli-drift task-01）：docs-debt.computeDecisionTouches
+ *  复用同一剥离口径（勿复刻正则防两处漂移）；仅加关键字，行为不变。 */
+export function anchorFilePath(anchor) {
+  const a = String(anchor || '').trim()
+  if (!a || a === '未记录') return null
+  return a.replace(/:(?:\d+(?:-\d+)?|[A-Za-z_$][A-Za-z0-9_$]*)$/, '').replace(/\\/g, '/') || null
+}
+
+/** specBase/docs 下任一项目的 modules/_module-map.yaml 尽力发现（对齐
+ *  decision-distill.discoverModuleIndex 口径：首个命中；失败 → null，域模块源码集退化为锚点文件兜底）。 */
+function discoverModuleMapIndex(specBase) {
+  try {
+    const docsDir = join(specBase, 'docs')
+    if (!existsSync(docsDir)) return null
+    for (const d of readdirSync(docsDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue
+      const mapPath = join(docsDir, d.name, 'modules', '_module-map.yaml')
+      if (existsSync(mapPath)) return parseModuleMapSimple(readFileSync(mapPath, 'utf8'))
+    }
+  } catch { /* 尽力而为，失败归 null */ }
+  return null
+}
+
+/**
+ * IO 入口（advisory）：跑一次决策规则族。只产出 findings（warn 语义），不进 runDocsCheck 的
+ * invalid 阻断链、不写任何文件——无 decisions 库 / 无信号 → findings 空（零输出）。
+ * computeModuleBehind 经动态 import 取自 docs-debt（本模块被 docs-debt 静态 import，静态互引
+ * 成 ESM 环——对齐 run/shared.js 对 docs-debt 的动态 import 先例）。
+ * @param {{ projectRoot: string, specBase?: string, behindThreshold?: number, knownFailures?: string[], moduleIndex?: object|null }} opts
+ *   projectRoot 源码仓根（锚点解析与 git 锚）；specBase 缺省 = <projectRoot>/.sillyspec；
+ *   behindThreshold / knownFailures 缺省读 local.yaml（decisions.behind_threshold / known_failures）；
+ *   moduleIndex 缺省按 specBase/docs 下任一项目的 modules/_module-map.yaml 尽力发现
+ * @returns {Promise<{ empty: boolean, domains: number, entries: number, implemented: number,
+ *   threshold: number, findings: Array<{ id: string, domain: string, file: string,
+ *   kind: 'anchor'|'behind', behind?: number|null, threshold?: number, anchor?: string|null,
+ *   message: string }>, exempted: Array<{ key: string, id: string, kind: string }> }>}
+ *   empty=true = decisions 库不存在（冷启动，R-02 由 doctor 层提示）；exempted 为经
+ *   known_failures decisions.* 键豁免的条目（披露不隐藏）
+ */
+export async function runDecisionRules(opts) {
+  const { projectRoot, specBase, behindThreshold = null, knownFailures = null, moduleIndex = null } = opts || {}
+  const emptyResult = (threshold) => ({ empty: true, domains: 0, entries: 0, implemented: 0, threshold, findings: [], exempted: [] })
+  if (!projectRoot) return emptyResult(DECISIONS_DEFAULT_BEHIND_THRESHOLD)
+
+  const cfg = readDecisionRulesConfig(projectRoot)
+  const threshold = typeof behindThreshold === 'number' && Number.isFinite(behindThreshold) && behindThreshold > 0
+    ? behindThreshold
+    : cfg.behindThreshold
+  const failures = Array.isArray(knownFailures) ? knownFailures : cfg.knownFailures
+
+  const kb = specBase || join(projectRoot, '.sillyspec')
+  const decisionsDir = join(kb, 'knowledge', 'decisions')
+  let domainFiles = []
+  try {
+    domainFiles = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).sort()
+  } catch {
+    return emptyResult(threshold) // 库不存在 → 零信号（doctor 层另行提示空库）
+  }
+
+  // 模块域 → 源码路径集（module-map paths∪core_files；未命中 map 的域退化为锚点文件兜底）
+  const mapIndex = moduleIndex || discoverModuleMapIndex(kb)
+  const flatIndex = mapIndex && mapIndex.modules ? mapIndex.modules : mapIndex
+  const { computeModuleBehind } = await import('./docs-debt.js')
+
+  const findings = []
+  const exempted = []
+  let entriesTotal = 0
+  let implementedTotal = 0
+  const treeCache = new Map() // resolveCandidates 全树扫描复用（同 docs check 主链路口径）
+
+  const emit = (id, domain, file, kind, extra, message) => {
+    if (isDecisionExempt(failures, id, kind)) {
+      exempted.push({ key: `decisions.${id}.${kind}`, id, kind })
+      return
+    }
+    findings.push({ id, domain, file, kind, ...extra, message })
+  }
+
+  for (const f of domainFiles) {
+    const domain = f.replace(/\.md$/, '')
+    const rel = `knowledge/decisions/${f}`
+    let entries
+    try { entries = parseDecisionEntries(readFileSync(join(decisionsDir, f), 'utf8')) } catch { continue }
+    for (const e of entries) {
+      entriesTotal++
+      if ((e.status || '').toLowerCase() !== 'implemented') continue // rejected/未知状态不做锚点与 behind 校验
+      implementedTotal++
+      const anchorPath = anchorFilePath(e.anchor)
+      // 规则 1：锚点存在性（未记录 → 补录提示；路径不存在 → 失效提示）
+      if (!anchorPath) {
+        emit(e.id, domain, rel, 'anchor', { anchor: e.anchor || null },
+          `「${e.id}」锚点未记录（${rel}）——旧格式条目，补「锚点：src/…」后可机械校验（advisory）`)
+      } else if (resolveCandidates(projectRoot, anchorPath, treeCache).length === 0) {
+        emit(e.id, domain, rel, 'anchor', { anchor: e.anchor },
+          `「${e.id}」锚点文件不存在：${anchorPath}（${rel}）——决策落点已漂移，人工复核（advisory）`)
+      }
+      // 规则 2：behind 复核（「最近确认」后锚定模块源码前进数超阈值 → 决策待复核；
+      // 「最近确认」未记录/域无源码集（无 map 无锚点）→ 无法计算，静默跳过——advisory 不产噪声）
+      if (!e.lastConfirmed || !/^[0-9a-f]{4,40}$/i.test(e.lastConfirmed)) continue
+      let srcPaths = null
+      const m = flatIndex && typeof flatIndex === 'object' ? flatIndex[domain] : null
+      if (m) srcPaths = [...(Array.isArray(m.paths) ? m.paths : []), ...(Array.isArray(m.core_files) ? m.core_files : [])]
+      if ((!srcPaths || srcPaths.length === 0) && anchorPath) srcPaths = [anchorPath]
+      if (!srcPaths || srcPaths.length === 0) continue
+      const { behind } = computeModuleBehind(domain, e.lastConfirmed, { projectRoot, srcPaths })
+      if (behind !== null && behind > threshold) {
+        emit(e.id, domain, rel, 'behind', { behind, threshold },
+          `「${e.id}」决策待复核：锚定模块 ${domain} 在最近确认 ${e.lastConfirmed} 后源码已前进 ${behind} commit，超阈值 ${threshold}（${rel}）——复核后更新「最近确认」`)
+      }
+    }
+  }
+
+  findings.sort((a, b) => a.file.localeCompare(b.file) || a.id.localeCompare(b.id))
+  exempted.sort((a, b) => a.key.localeCompare(b.key))
+  return { empty: false, domains: domainFiles.length, entries: entriesTotal, implemented: implementedTotal, threshold, findings, exempted }
+}

package/src/docs-debt.js

@@ -10,15 +10,20 @@
  *   behind = rev-list --count docCommit..srcCommit；untracked 卡 behind=null 显式"卡片从未提交"；
  *   git 失败/超时 5s → 该模块 behind=null + 降级注记，不抛。
  */
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
+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 } from './docs-check.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 相对路径）
@@ -90,7 +95,31 @@ export function matchFilesToModules(changedFiles, moduleIndex, opts = {}) {
   return { byModule, unmapped }
 }
 
-/** 单模块欠账：双 commit 时间戳判方向 + rev-list 计数。全失败 → behind null + 注记。
+/** "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 恒失败 → 走"从未提交"形态，如实呈现）。 */
@@ -102,41 +131,58 @@ function moduleDebt(projectRoot, moduleId, entry, docGitPath, docGitRoot) {
   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 失败）')
-  }
+  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 })
-    if (!docLog.error && docLog.value && docLog.value.trim()) {
-      const [h, ct] = docLog.value.trim().split(' ')
-      docCommit = { h, ct: parseInt(ct, 10) }
-    } else {
-      neverCommitted = true
-    }
+    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) {
-    // 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 }
-    }
+    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
@@ -177,7 +223,10 @@ export function computeDocsDebt(opts) {
     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)
+      // 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 */ }
@@ -228,3 +277,117 @@ function inlineCardInvalidRefs(entry, docGitRoot, docPathPrefix) {
     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/src/doctor-diagnostics.js

@@ -23,8 +23,9 @@
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join } from 'path';
+import jsYaml from 'js-yaml';
 import { CHECK_SEVERITY } from './constants.js';
-import { checkPlatformManaged } from './run/shared.js';
+import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './run/shared.js';
 
 // db 角色标签
 const DB_ROLE = {
@@ -580,6 +581,104 @@ function detectExecuteProgressPlanMismatch(authoritySpecRoot, authDb) {
   return dim;
 }
 
+// ── D6 repo-native 断链画像（FR-4，变更 2026-08-23-repo-native-spec-backfill）─────
+//
+// repo-native 工作区的投毒残留三画像（daemon junction 回环：--spec-root 缓存路径指回源项目
+// <cwd>/.sillyspec）。新版 CLI（≥3.27.3）对三者均自动免疫（恢复忽略/写入拦截/声明降级），
+// 本维度把残留显性化给用户/agent——残留本身无阻断风险，凭据缺失才是上行断链的无感知杀手
+//（design 风险 5：内置 sync best-effort 静默跳过）。自指判定复用 run/shared.js 单一数据源
+//（本模块已有 checkPlatformManaged 静态 import 链，无独立脚本复制问题）。
+//
+// 三画像（均 WARNING 级 advisory，doctor 只读绝不自动清理）：
+//   ① 指针存在且自指（旧 CLI 中毒残留，建议升级 CLI 或删指针文件）
+//   ② 接管声明存在但指针缺失且自指（陈旧声明，可 sillyspec platform disconnect 清理）
+//   ③ cwd/.sillyspec 存在但 local.yaml 无 platform 段 + 自指残留（凭据缺失，上行静默失败）
+
+/** local.yaml 是否有 platform 段（url/token 凭据）。读失败/无文件/无段 → false（宁报缺勿漏报）。 */
+function localYamlHasPlatformSection(cwd) {
+  try {
+    const p = join(cwd, '.sillyspec', 'local.yaml');
+    if (!existsSync(p)) return false;
+    const doc = jsYaml.load(readFileSync(p, 'utf8'));
+    return !!(doc && typeof doc === 'object' && doc.platform && typeof doc.platform === 'object');
+  } catch {
+    return false;
+  }
+}
+
+function detectRepoNativeChain(cwd, pointer) {
+  const dim = {
+    name: 'repo_native_chain',
+    label: 'repo-native 断链画像',
+    safe_actions: [],
+    findings: [],
+  };
+  const decl = checkPlatformManaged(cwd);
+  const ptrSelfRef = pointer.present && !pointer.corrupted && isSelfReferentialSpecRoot(cwd, pointer.specRoot);
+  const declSelfRef = !!decl && isSelfReferentialSpecRoot(cwd, decl.specRoot);
+  let triggered = false;
+
+  // 画像①：自指指针在盘（runCommand 会忽略并按本地模式运行，但残留说明旧 CLI 投过毒）
+  if (ptrSelfRef) {
+    triggered = true;
+    dim.findings.push(
+      `repo_native_self_referential_pointer: 平台指针 specRoot 自指回环（realpath = 本地 .sillyspec，` +
+      `repo-native junction 投毒残留）：${pointer.specRoot}——新版 CLI 已自动忽略按本地模式运行；` +
+      `建议删除指针文件 ${pointer.path} 或升级 CLI（≥3.27.3）防旧版再中毒`
+    );
+    dim.safe_actions.push({
+      dimension: 'repo_native_chain',
+      action: 'remove_self_referential_pointer',
+      target: pointer.path,
+      risk: 'confirm_required',
+      rationale: '自指指针对新版 CLI 无效但会持续触发忽略告警；删除后本地模式零残留',
+      next_step: `rm "${pointer.path}"（保留 local.yaml 平台凭据）`,
+    });
+  }
+
+  // 画像②：陈旧自指声明（指针已删/未写，声明残留——runCommand 降级本地模式不阻断）
+  if (!pointer.present && declSelfRef) {
+    triggered = true;
+    dim.findings.push(
+      `repo_native_stale_declaration: 自指平台接管声明残留（原 specRoot 自指回环且恢复指针缺失）：` +
+      `${join(cwd, PLATFORM_MANAGED_FILENAME)}——新版 CLI 已降级按本地模式运行（不 fail-closed）；` +
+      `可 sillyspec platform disconnect 清理声明残留`
+    );
+    dim.safe_actions.push({
+      dimension: 'repo_native_chain',
+      action: 'platform_disconnect_cleanup',
+      risk: 'low',
+      rationale: '陈旧自指声明只触发降级告警；disconnect 三清（指针/声明/local.yaml platform 段）彻底出清',
+      next_step: 'sillyspec platform disconnect（若仍需上行同步，先确认 local.yaml 凭据再重连）',
+    });
+  }
+
+  // 画像③：repo-native 凭据缺失 + 自指残留（design 风险 5：内置 sync best-effort 静默跳过，
+  // 上行断链且无感知——CLI 本地模式化后 local.yaml platform 段是唯一上行通道）
+  if (existsSync(join(cwd, '.sillyspec')) && !localYamlHasPlatformSection(cwd) && (ptrSelfRef || declSelfRef)) {
+    triggered = true;
+    dim.findings.push(
+      `repo_native_missing_credentials: cwd/.sillyspec 存在但 local.yaml 无 platform 段，` +
+      `且存在自指指针/声明残留——内置 sync 因凭据缺失静默跳过，本地变更上行将静默失败` +
+      `（平台变更中心看不到，无任何告警）。恢复：sillyspec platform connect <url> <token> 写入凭据`
+    );
+    dim.safe_actions.push({
+      dimension: 'repo_native_chain',
+      action: 'platform_connect_credentials',
+      risk: 'low',
+      rationale: 'repo-native 源项目的上行通道是 CLI 内置 sync（local.yaml platform 段凭据 + resolve-by-root-path），凭据缺失即断链',
+      next_step: 'sillyspec platform connect <url> <token>（写入 local.yaml platform 段后自动恢复上行）',
+    });
+  }
+
+  dim.pass = !triggered;
+  dim.severity = triggered ? CHECK_SEVERITY.WARNING : null;
+  if (!triggered) {
+    dim.findings.push('无 repo-native 自指残留（指针/接管声明均健康或不存在）');
+  }
+  return dim;
+}
+
 // ── 主入口 ────────────────────────────────────────────────────────────
 
 // ── 文档膨胀检测（token 成本优化 P0b/P2b，2026-08-22-token-cost-optimization）──
@@ -650,8 +749,9 @@ export async function runDoctorDiagnostics({ cwd }) {
   const authDb = (multiDb.dbs || []).find((d) => d.role === DB_ROLE.AUTHORITY);
   const executeMismatch = detectExecuteProgressPlanMismatch(authoritySpecDir, authDb);
   const docBloat = detectDocBloat(authoritySpecDir);
+  const repoNativeChain = detectRepoNativeChain(cwd, pointer);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat];
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain];
 
   return {
     dimensions,