sillyspec 3.27.12 → 3.28.2

package/src/design-facts.js

@@ -0,0 +1,354 @@
+/**
+ * design-facts — 设计事实核验 + design 骨架渲染纯函数集
+ * （change: 2026-09-07-ir-stage-p3c，task-01，FR-01/FR-02，D-001@v1/D-002@v1/D-004@v1）
+ *
+ * 职责（设计文档 Wave 1 + Wave 2 的纯函数本体，接线在 task-02/03）：
+ *   1. parseDecisionDomains(decisionsText)：decisions.md 文本 → 当前版本 D 条目的模块域投影
+ *      [{ id, domains }]（NEW: 前缀项原样保留，豁免存在性核验）。
+ *   2. loadModuleMap(specRoot, project)：_module-map.yaml → { ids, prefixPairs } | null。
+ *   3. validateDecisionModuleRefs({ changeDir, specRoot, project })：模块域分级核验
+ *      （ERROR=幻觉模块/书写错误，WARNING=声明域×实改面差异，skipped=无索引/无决策）。
+ *   4. generateDesignSkeleton({ changeName, decisionsText, author, now })：design.md 十三章节
+ *      骨架字符串（章节标题逐字取自 brainstorm Step 6 模板，R-03——禁止自创措辞）。
+ *
+ * 依赖方向（R-01 单向防环）：design-facts → decision-distill / change-list / modules，
+ * 三者均不反向 import 本模块。条目解析双源说明：distill 的 parseDecisions 只吃 changeDir
+ * （内部读盘），故文本入口 parseDecisionDomains 持有其行循环的逐字镜像（正则/字段映射/
+ * 列表切分全部同源复制），validateDecisionModuleRefs 则直接复用 parseDecisions 导出——
+ * 双解析一致性由 task-04 的同一 fixture 双源测试锁定。
+ *
+ * 信封 code（task-02 接线层使用，本模块已内嵌在消息前缀）：
+ *   decision_module_ref_invalid（ERROR）/ decision_module_domain_gap（WARNING）/
+ *   decision_module_check_skipped（skipped 原因字符串，接线层包 code）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseDecisions } from './decision-distill.js'
+import { parseFileChangeListDetailed } from './change-list.js'
+import { parseModuleMapSimple } from './modules.js'
+
+// ---------------------------------------------------------------------------
+// 条目解析（distill parseDecisions 的同源镜像，R-01）
+// ---------------------------------------------------------------------------
+
+/** 模块域值解析（decision-distill.js:47 parseListValue 逐字镜像）：`[a, b]` / `a、b` / `a b` → ['a','b'] */
+function parseListValue(v) {
+  return v.replace(/^\[/, '').replace(/\]$/, '')
+    .split(/[,，、\s]+/)
+    .map(s => s.trim())
+    .filter(Boolean)
+}
+
+/** 模块域字段标签集（decision-distill.js:77 applyField 的 domains 分支同款，中英标签+中英冒号兼容） */
+const DOMAIN_LABELS = new Set(['模块域', '模块', 'domains', 'domain'])
+
+/**
+ * decisions.md 文本 → 裸条目数组（decision-distill.js:98 parseDecisions 行循环的模块域子集镜像：
+ * 头部正则 :114 / 字段行正则 :123 逐字同源；仅解析本模块消费的 id/number/version/domains）。
+ * @param {string} content decisions.md 全文
+ * @returns {Array<{ id: string, number: string, version: number, domains: string[] }>}
+ */
+function extractDomainEntries(content) {
+  const entries = []
+  let cur = null
+  const flush = () => {
+    if (!cur) return
+    entries.push(cur)
+    cur = null
+  }
+  for (const line of String(content ?? '').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}`, number: h[1], version, domains: [] }
+      continue
+    }
+    if (!cur) continue
+    const f = line.match(/^-\s+([^\s：:]+)\s*[：:]\s*(.*)$/)
+    if (f && DOMAIN_LABELS.has(f[1].toLowerCase())) cur.domains = parseListValue(f[2].trim())
+  }
+  flush()
+  return entries
+}
+
+/**
+ * 当前版本过滤（decision-distill.js:462 highestByNumber 同款）：同号只留最高版本
+ * （D-xxx@v1 与 @v2 并存时 v1 视为 superseded 旧版剔除）。
+ * @template T
+ * @param {Array<T & { number: string, version: number }>} entries
+ * @returns {T[]}
+ */
+function currentVersionEntries(entries) {
+  const highestByNumber = new Map()
+  for (const e of entries) {
+    const prev = highestByNumber.get(e.number)
+    if (!prev || e.version > prev.version) highestByNumber.set(e.number, e)
+  }
+  return [...highestByNumber.values()]
+}
+
+/**
+ * 纯函数：解析 decisions.md 文本的当前版本决策条目模块域（FR-01）。
+ * NEW: 前缀项原样保留在 domains 项内（`NEW:foo` 豁免存在性核验；`NEW: foo` 带空格会被
+ * parseListValue 切成裸项 'NEW:'/'foo'，由 validateDecisionModuleRefs 报书写错误）。
+ * @param {string} decisionsText decisions.md 全文（纯文本入参，不读盘）
+ * @returns {Array<{ id: string, domains: string[] }>} 当前版本条目（同号取最高 @vN，首现顺序）
+ */
+export function parseDecisionDomains(decisionsText) {
+  return currentVersionEntries(extractDomainEntries(decisionsText))
+    .map(e => ({ id: e.id, domains: [...e.domains] }))
+}
+
+// ---------------------------------------------------------------------------
+// 模块索引（_module-map.yaml 只读，复用 modules.js canonical 解析避免三写）
+// ---------------------------------------------------------------------------
+
+/**
+ * 读 docs/<project>/modules/_module-map.yaml → 模块 id 集合 + paths 前缀对（FR-01）。
+ * 解析复用 modules.js parseModuleMapSimple（canonical 单一真相源）；prefixPairs 含
+ * paths+core_files（与 decision-distill.js:203 matchImpactsToModules 的取并集口径一致），
+ * 目录条目去尾斜杠后按「全等或目录前缀」匹配。
+ * @param {string} specRoot 规范根目录（如 <repo>/.sillyspec——与 run/prompt.js 的 specBase 同义）
+ * @param {string} project 子项目名（docs/ 下第一段目录名）
+ * @returns {{ ids: Set<string>, prefixPairs: Array<{ id: string, path: string }> } | null}
+ *   无 map / 不可读 / 解析不出任何模块 → null（无索引不误拦，调用方走 skipped）
+ */
+export function loadModuleMap(specRoot, project) {
+  if (!specRoot || !project) return null
+  const mapPath = join(specRoot, 'docs', project, 'modules', '_module-map.yaml')
+  if (!existsSync(mapPath)) return null
+  let content
+  try { content = readFileSync(mapPath, 'utf8') } catch { return null }
+  let parsed = {}
+  try { parsed = parseModuleMapSimple(content) || {} } catch { return null }
+  const ids = new Set(Object.keys(parsed))
+  if (ids.size === 0) return null // 空/失配 map 视同无索引（fail-open，D-002）
+  const prefixPairs = []
+  for (const [id, m] of Object.entries(parsed)) {
+    for (const p of [...((m && m.paths) || []), ...((m && m.core_files) || [])]) {
+      const ps = String(p).replace(/\\/g, '/').replace(/\/+$/, '')
+      if (ps) prefixPairs.push({ id, path: ps })
+    }
+  }
+  return { ids, prefixPairs }
+}
+
+// ---------------------------------------------------------------------------
+// 核验（FR-02 分级：ERROR / WARNING / skipped）
+// ---------------------------------------------------------------------------
+
+/**
+ * design 文件清单路径 × module-map paths 前缀 → 实改模块集（decision-distill.js:212 同款
+ * 匹配语义：全等或目录前缀命中）。未命中任何模块的文件不产生推导（R-02：模块 paths 缺口
+ * 不误报，只对命中的做差异）。
+ * @param {string[]} filePaths design.md 文件变更清单路径（仓根相对、正斜杠）
+ * @param {Array<{ id: string, path: string }>} prefixPairs loadModuleMap 的前缀对
+ * @returns {Set<string>} 实改模块 id 集
+ */
+export function deriveActualModules(filePaths, prefixPairs) {
+  const actual = new Set()
+  for (const f of filePaths) {
+    const t = String(f || '').replace(/\\/g, '/').replace(/\/+$/, '')
+    if (!t) continue
+    for (const { id, path: p } of prefixPairs) {
+      if (t === p || t.startsWith(p + '/')) { actual.add(id); break }
+    }
+  }
+  return actual
+}
+
+/**
+ * 核验变更决策的模块域引用（FR-02/D-002/D-004；brainstorm「生成规范文件」步 --done gate 本体，
+ * 接线在 task-02）。分级：
+ *   - ERROR（decision_module_ref_invalid）：
+ *     · 模块域项 ∉ _module-map.yaml 且无 NEW: 前缀（模块幻觉）——出路提示二选一；
+ *     · 裸项 'NEW:'（`NEW: <名>` 冒号后带空格被列表切分）——书写错误，附正确写法。
+ *   - WARNING（decision_module_domain_gap）：
+ *     · design.md 文件清单推导的实改模块集 × 声明域并集差异（双向，措辞留人工裁量）；
+ *     · 全部条目均未填模块域 → 汇总一条（存量兼容）。
+ *   - skipped：decisions.md 不存在 / module-map 缺失（无索引不误拦）→ ok=true + skipped 原因。
+ * @param {{ changeDir: string, specRoot: string, project: string }} opts
+ *   changeDir=变更目录（含 decisions.md 与 design.md）；specRoot=规范根；project=子项目名
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], skipped?: string }}
+ *   ok = errors.length === 0（WARNING 不拦）；errors/warnings 每条已内嵌信封 code 前缀，
+ *   skipped 为原因字符串（接线层包 decision_module_check_skipped）。
+ */
+export function validateDecisionModuleRefs({ changeDir, specRoot, project } = {}) {
+  const errors = []
+  const warnings = []
+
+  if (!changeDir) {
+    return { ok: true, errors, warnings, skipped: 'changeDir 未提供——核验跳过' }
+  }
+  const parsed = parseDecisions(changeDir) // distill 权威条目解析（:98 导出，单向依赖）
+  if (parsed.missing) {
+    return { ok: true, errors, warnings, skipped: `decisions.md 不存在（${join(changeDir, 'decisions.md')}）——无决策条目可核验，跳过` }
+  }
+  const moduleMap = loadModuleMap(specRoot, project)
+  if (!moduleMap) {
+    return { ok: true, errors, warnings, skipped: `_module-map.yaml 不存在或不可解析（${join(specRoot || '?', 'docs', project || '?', 'modules', '_module-map.yaml')}）——无模块索引不误拦，跳过` }
+  }
+
+  // ① 存在性核验（ERROR）：NEW: 前缀豁免；∈ ids 通过；否则幻觉 ERROR（附出路）
+  const entries = currentVersionEntries(parsed.entries)
+    .map(e => ({ id: e.id, domains: e.domains ? [...e.domains] : [] }))
+  let anyDeclared = false
+  for (const { id, domains } of entries) {
+    if (domains.length > 0) anyDeclared = true
+    for (const item of domains) {
+      if (item === 'NEW:') {
+        errors.push(`[decision_module_ref_invalid] ${id} 模块域书写错误：出现裸项 "NEW:"（"NEW: <名>" 冒号后带空格会被列表切分成 "NEW:" 与 "<名>" 两项）——正确写法 NEW:<名>（冒号后不加空格，如 NEW:design-facts）`)
+      } else if (item.startsWith('NEW:')) {
+        // 新模块声明：豁免存在性核验（D-002/D-004），原样保留
+      } else if (!moduleMap.ids.has(item)) {
+        errors.push(`[decision_module_ref_invalid] ${id} 模块域含未注册模块 "${item}"——补录 _module-map.yaml 或改用 NEW:${item} 前缀声明新模块`)
+      }
+    }
+  }
+
+  // ② 全部条目无模块域 → 汇总一条 WARNING（存量兼容，零红门禁）
+  if (entries.length > 0 && !anyDeclared) {
+    warnings.push(`[decision_module_domain_gap] decisions.md 解析出 ${entries.length} 条当前版本决策，均未填写「模块域」可选字段——模块引用核验无对象（存量兼容放行；建议补填：模块 ID 取自 docs/${project}/modules/_module-map.yaml，新模块用 NEW:<名> 前缀声明）`)
+  }
+
+  // ③ 实改面 × 声明域差异（WARNING 双向；design.md 缺失/无清单时静默跳过——R-02 不产噪）。
+  //    声明侧只计已注册的非 NEW: 域：NEW: 域按定义不在 map 内、未注册域已由 ① 报 ERROR，
+  //    纳入只会产生重复噪音。
+  if (anyDeclared) {
+    const fileList = parseFileChangeListDetailed(join(changeDir, 'design.md')).map(e => e.path)
+    if (fileList.length > 0) {
+      const actual = deriveActualModules(fileList, moduleMap.prefixPairs)
+      const declared = new Set()
+      for (const { domains } of entries) {
+        for (const d of domains) {
+          if (!d.startsWith('NEW:') && moduleMap.ids.has(d)) declared.add(d)
+        }
+      }
+      for (const m of actual) {
+        if (!declared.has(m)) warnings.push(`[decision_module_domain_gap] 实改模块 "${m}"（design.md 文件清单命中该模块路径）未出现在任何决策的模块域声明中——请确认是遗漏声明（补填模块域）还是文件清单多列`)
+      }
+      for (const d of declared) {
+        if (!actual.has(d)) warnings.push(`[decision_module_domain_gap] 声明模块域 "${d}" 未命中 design.md 文件清单中的任何文件——可能为纯设计影响/跨模块约束（人工裁量即可），也可能是文件清单遗漏`)
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// ---------------------------------------------------------------------------
+// design.md 骨架渲染（Wave 2；R-03：章节标题逐字取自 brainstorm Step 6 模板，禁止自创）
+// ---------------------------------------------------------------------------
+
+/**
+ * 生成 design.md 十三章节骨架字符串（纯函数不落盘，写盘/幂等保护由 design-init CLI 负责）。
+ * 章节标题与 brainstorm.js「design.md 必须包含的章节」模板逐字对齐（1 背景/2 设计目标/
+ * 3 非目标/4 拆分判断/5 总体方案/6 文件变更清单/7 接口定义/7.5 生命周期契约表/8 数据模型/
+ * 9 兼容策略/10 风险登记/11 决策追踪/12 自审），满足 stage-contract-spec 的字面命中检查
+ * （文件变更清单/风险登记/自审/生命周期豁免）与 plan.design-readiness 六章就绪检查。
+ * 决策追踪表从 decisionsText 当前版本 D 条目逐行预填；文件变更清单给表头+示例注释行
+ * （注释形态不会被 plan-postcheck 清单解析计入）。
+ * @param {{ changeName?: string, decisionsText?: string, author?: string, now?: string }} opts
+ *   changeName=变更简述（入标题）；decisionsText=decisions.md 全文；author/now=frontmatter 值
+ * @returns {string} design.md 骨架全文（LF 行尾，单一尾换行）
+ */
+export function generateDesignSkeleton({ changeName, decisionsText, author, now } = {}) {
+  const change = String(changeName || '').trim() || '<变更简述>'
+  const decisions = parseDecisionDomains(decisionsText || '')
+
+  const lines = []
+  lines.push('---')
+  lines.push(`author: ${String(author || '').trim() || 'TODO（git 用户名）'}`)
+  lines.push(`created_at: ${String(now || '').trim() || 'TODO（ISO 时间）'}`)
+  lines.push('scale: large')
+  lines.push('---')
+  lines.push('')
+  lines.push(`# 设计文档（Design）— ${change}`)
+  lines.push('')
+  lines.push(`<!-- 由 sillyspec design-init 生成的骨架（${change}）——逐节填散文后删除本注释；存量手写路径不受影响 -->`)
+  lines.push('')
+
+  lines.push('## 背景')
+  lines.push('')
+  lines.push('<!-- TODO：为什么做、解决什么问题 -->')
+  lines.push('')
+
+  lines.push('## 设计目标')
+  lines.push('')
+  lines.push('<!-- TODO：要达成什么 -->')
+  lines.push('')
+
+  lines.push('## 非目标')
+  lines.push('')
+  lines.push('<!-- TODO：明确不做的事（防止 scope creep） -->')
+  lines.push('')
+
+  lines.push('## 拆分判断')
+  lines.push('')
+  lines.push('<!-- TODO（如适用）：为什么这样组织变更、为什么不走批量模式；不适用可整节删除 -->')
+  lines.push('')
+
+  lines.push('## 总体方案')
+  lines.push('')
+  lines.push('<!-- TODO：技术方案（分 Phase/Wave） -->')
+  lines.push('')
+
+  lines.push('## 文件变更清单')
+  lines.push('')
+  lines.push('| 操作 | 文件路径 | 说明 |')
+  lines.push('|---|---|---|')
+  lines.push('<!-- 示例行（替换为实际清单后删除本注释）：| 新增 | src/xxx/NewFile.java | 说明（含对外字段时交代 producer→consumer 数据流） | -->')
+  lines.push('')
+
+  lines.push('## 接口定义')
+  lines.push('')
+  lines.push('<!-- TODO（代码类任务必填）：方法签名、数据结构 -->')
+  lines.push('')
+
+  lines.push('## 生命周期契约表')
+  lines.push('')
+  lines.push('<!-- TODO：涉及 session/lease/agent_run/daemon/lifecycle/state transition/claim/heartbeat 等关键词时本表必填（事件×发起方×接收方×必需字段×状态变化 矩阵）；确实不涉及时在紧邻位置写豁免短语——否定词必须紧邻「生命周期契约/lifecycle contract」，宽写法不被识别（写法见 brainstorm 模板） -->')
+  lines.push('')
+
+  lines.push('## 数据模型')
+  lines.push('')
+  lines.push('<!-- TODO（如涉及）：表结构/字段变更；不涉及可整节删除或写明无 schema 变更 -->')
+  lines.push('')
+
+  lines.push('## 兼容策略（brownfield 必填）')
+  lines.push('')
+  lines.push('<!-- TODO（brownfield 必填）：未配置新功能时行为不变 / 新旧逻辑的回退路径 / 不改变的 API 与表结构 -->')
+  lines.push('')
+
+  lines.push('## 风险登记')
+  lines.push('')
+  lines.push('| 编号 | 风险 | 等级 | 应对策略 |')
+  lines.push('|---|---|---|---|')
+  lines.push('| R-01 | （待填风险） | P1 | （待填应对策略） |')
+  lines.push('')
+
+  lines.push('## 决策追踪')
+  lines.push('')
+  lines.push('| 决策 | 覆盖点 | 状态 |')
+  lines.push('|---|---|---|')
+  if (decisions.length > 0) {
+    for (const { id } of decisions) lines.push(`| ${id} | （待填覆盖点） | 待确认 |`)
+  } else {
+    lines.push('<!-- 未从 decisions.md 解析出当前版本决策条目——如确无决策可写「无决策记录」 -->')
+  }
+  lines.push('<!-- TODO：说明每个 D-xxx@vN 被哪些 FR-xxx / 设计章节覆盖；标注仍未解决的 D-xxx@vN 或剩余风险 -->')
+  lines.push('')
+
+  lines.push('## 自审')
+  lines.push('')
+  lines.push('- [ ] 章节齐全（背景/设计目标/非目标/总体方案/文件变更清单/接口定义/风险登记）')
+  lines.push('- [ ] frontmatter 字段齐全（author/created_at/scale）')
+  lines.push('- [ ] 引用所有当前版本 D-xxx@vN')
+  lines.push('- [ ] 涉及生命周期关键词时含「生命周期契约表」或紧邻豁免短语')
+  lines.push('- [ ] UI 原型分级核对（涉前端文件时变更目录应有 prototype-*.html 或跳过原因记入风险登记）')
+  lines.push('- [ ] 不确定的问题标注「⚠️ 自审存疑」')
+  lines.push('')
+
+  return lines.join('\n')
+}

package/src/docs-check.js

@@ -18,13 +18,18 @@ 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）。
+/** 提取 file.js:line / file.js:start-end 引用（反引号包裹与裸文本均命中，全文扫描 D-006）。
+ * 扩展名覆盖（archify 借鉴 P1b，2026-09-04）：js/mjs/cjs/ts/tsx/jsx/py/java/go——
+ * scan 产物面向任意技术栈项目（如 SillyHub = Python + TypeScript），只认 .js 会让
+ * 非 JS 项目的文档引用全部漏检。注意：扩展会让存量文档中此前被忽略的引用新进入核验范围，
+ * 而 docs-gate ratchet 只拦增量不吸收增量（基线 0 时新失效必红 gate）——存量失效必须
+ * 在同一变更内消化（本仓 2026-09-04 已消化：跨仓 .py 引用改 repo:// 前缀、示例记法改写）。
  * repo:// 前缀（2026-08-20）：跨仓引用显式标记——`repo://<仓库名>/<路径>.js:行`。
  * 不同设备兄弟仓库位置不同，未配映射时默认跳过本地校验（防跨设备误报）；
  * 在本机 .sillyspec/local.yaml 的 docs-check.cross_repo_roots 配
  * `<仓库名>: <本机绝对路径>` 后，走与本地引用完全相同的层1（行号边界）+ 层2（关键词窗口）校验。
  * 正则组：1=仓库名（可选），2=文件，3=start，4=end。 */
-const REF_RE = /(?:repo:\/\/([A-Za-z0-9_.\-]+)\/)?([A-Za-z0-9_.\-\/]+\.(?:js|mjs)):(\d+)(?:-(\d+))?/g
+const REF_RE = /(?:repo:\/\/([A-Za-z0-9_.\-]+)\/)?([A-Za-z0-9_.\-\/]+\.(?:js|mjs|cjs|ts|tsx|jsx|py|java|go)):(\d+)(?:-(\d+))?/g
 
 /** 缺省扫描范围：docs/ + .sillyspec/docs/（scan/modules 产物同是文档，失效即该暴露；2026-08-16 用户裁决改缺省，见 doc-consistency-debt.md §八） */
 const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md']
@@ -183,7 +188,72 @@ export function resolveCandidates(projectRoot, refFile, treeCache = null) {
   return findInTree(join(projectRoot, 'src'), refFile, '', treeCache).map((rel) => join(projectRoot, 'src', rel))
 }
 
+/**
+ * 联合核验一组文档的全部 file:line 引用（archify 借鉴，2026-09-04）：
+ * 层1（resolveCandidates 可解析 + validateRefLines 行号边界）+ 层2（引用行反引号 token
+ * 在源文件 [start-2, end+5] 窗口内命中，窗口与 runDocsCheck 共用 keywordWindowText 单一源）。
+ * 任一候选通过即有效。scan-postcheck（scan_doc_ref_invalid）与 workflow ref_exists 检查共用。
+ * 与 runDocsCheck 的已知差异：repo:// 跨仓引用一律跳过（不读 cross_repo_roots 映射）；
+ * 层2 无条件执行（不读 keywordAssert 配置）——需要降噪时在调用方处理。
+ * 单文档不可读（如路径是目录）降级跳过并计入 readFailures，不废整批。
+ * @param {string} projectRoot 引用解析锚点（源码项目根）
+ * @param {Array<{name: string, absPath: string}>} docEntries 文档标识与绝对路径
+ * @returns {{ invalid: Array<{doc: string, ref: string, reason: string}>, totalRefs: number, skippedCrossRepo: number, readFailures: number }}
+ */
+export function collectInvalidDocRefs(projectRoot, docEntries) {
+  const invalid = []
+  let totalRefs = 0
+  let skippedCrossRepo = 0
+  let readFailures = 0
+  const treeCache = new Map()
+  const linesCache = new Map()
+  for (const { name, absPath } of docEntries) {
+    let content
+    try {
+      content = readFileSync(absPath, 'utf8')
+    } catch {
+      readFailures++
+      continue
+    }
+    const docLines = content.split(/\r?\n/)
+    for (const ref of collectDocRefs(content)) {
+      if (ref.repo !== null) { skippedCrossRepo++; continue }
+      totalRefs++
+      const candidates = resolveCandidates(projectRoot, ref.file, treeCache)
+      if (candidates.length === 0) {
+        invalid.push({ doc: name, ref: ref.ref, reason: '文件不存在' })
+        continue
+      }
+      const tokens = extractExpectedTokensFromLine(docLines[ref.docLine - 1] || '')
+      const infos = candidates.map(abs => ({ lines: readLines(abs, linesCache) }))
+      const ok = infos.some(({ lines }) => {
+        if (!lines || lines.length === 0) return false
+        if (!validateRefLines(lines.length, ref.start, ref.end).ok) return false
+        if (tokens.length === 0) return true // 纯位置引用（行内无可断言符号），只做层1
+        return tokens.some(t => keywordWindowText(lines, ref.start, ref.end).includes(t))
+      })
+      if (!ok) {
+        const readable = infos.some(({ lines }) => lines && lines.length > 0)
+        const inBounds = readable && infos.some(({ lines }) => lines && validateRefLines(lines.length, ref.start, ref.end).ok)
+        const reason = !readable
+          ? (infos.some(({ lines }) => lines && lines.length === 0) ? '空文件（无可引用内容）' : '文件不可读')
+          : !inBounds ? '行号超界' : '关键词未命中（引用行附近不含所述符号）'
+        invalid.push({ doc: name, ref: ref.ref, reason })
+      }
+    }
+  }
+  return { invalid, totalRefs, skippedCrossRepo, readFailures }
+}
+
+/** 层2 关键词窗口文本（1-based 闭区间 [start-2, end+5]，含端点）。runDocsCheck 与
+ *  collectInvalidDocRefs 共用——此前两处手写 slice 相差一行（off-by-one），此函数即窗口单一语义源。 */
+function keywordWindowText(lines, start, end) {
+  return lines.slice(Math.max(0, start - 3), Math.min(lines.length, end + 5)).join('\n')
+}
+
 /** 读文件行数组（CRLF/LF 归一：split(/\r?\n/)，层2 只做子串查找不污染原文）。
+ *  尾换行产生的「幻影 N+1 行」剥除（编辑器口径 N 行 = split 后去掉一个尾部空元素）；
+ *  空文件返回 []（length 0）——:1 引用按超界判失效，不再因 [''] 假长度通过。
  *  linesCache 给定时按绝对路径复用（同文件被 N 条引用消费免 N 次读盘+split） */
 function readLines(absPath, linesCache = null) {
   if (linesCache) {
@@ -192,7 +262,11 @@ function readLines(absPath, linesCache = null) {
     linesCache.set(absPath, lines)
     return lines
   }
-  try { return readFileSync(absPath, 'utf8').split(/\r?\n/) } catch { return null }
+  try {
+    const lines = readFileSync(absPath, 'utf8').split(/\r?\n/)
+    if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+    return lines
+  } catch { return null }
 }
 
 /** 简单通配匹配（skip 排除用，仅 * 单段） */
@@ -395,13 +469,10 @@ export function runDocsCheck(opts) {
         const lines = readLines(candAbs, linesCache)
         if (lines === null) { candidateFails.push(`${relDisplay(candAbs, projectRoot)}: 读取失败`); continue }
         const v = validateRefLines(lines.length, r.start, r.end)
-        // 层2：token 任一在 [start-2, end+5] 窗口命中即过
+        // 层2：token 任一在 [start-2, end+5] 窗口命中即过（窗口与 collectInvalidDocRefs 共用 keywordWindowText）
         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))
+          kwOk = tokens.some((t) => keywordWindowText(lines, r.start, r.end).includes(t))
         }
         if (v.ok && kwOk) { passedAny = true; break }
         const reasons = [...v.reasons]

package/src/doctor-diagnostics.js

@@ -21,11 +21,12 @@
  * writer 落盘到 <authoritySpecDir>/.runtime/。
  */
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
+import { safeGit } from './git-helper.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, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './run/shared.js';
+import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME, QUICK_SID_RE } from './run/shared.js';
 
 // db 角色标签
 const DB_ROLE = {
@@ -423,7 +424,12 @@ function detectChangeDbConsistency(cwd, pointer, multiDb) {
     : [];
   const dirSet = new Set(dirChanges);
   const activeSet = new Set(activeNames);
-  const ghostRows = activeNames.filter((n) => !dirSet.has(n));
+  // ghost 判定排除 quick 会话行（quick-<8hex>）：initChange 对 quick 特意不建 changes/ 目录
+  // （进度存 SQL 不需要实体目录），「active + 无目录」是它的设计形态而非残留——不排除则
+  // 进行中 quick 从写库起即误报（2026-09-07 quick-inflight-ghost-misjudge）。与
+  // stage-machine overview/show 同源（同正则）；cleanupGhostChanges 不在此排除——
+  // 「QUICKLOG 已完成但 DB 行仍 active」的收尾中断行仍由它归档（兜底出口）。
+  const ghostRows = activeNames.filter((n) => !dirSet.has(n) && !QUICK_SID_RE.test(n));
   const orphanDirs = dirChanges.filter((n) => !activeSet.has(n));
   // SS-2b：空壳——db active + 目录存在但 0 文件 + last_active 超过 7 天。有目录所以
   // 逃过 ghostRows 的「无目录」判定（2026-08-15 清理时 6 个空壳即此漏网形态）。
@@ -750,8 +756,10 @@ export async function runDoctorDiagnostics({ cwd }) {
   const executeMismatch = detectExecuteProgressPlanMismatch(authoritySpecDir, authDb);
   const docBloat = detectDocBloat(authoritySpecDir);
   const repoNativeChain = detectRepoNativeChain(cwd, pointer);
+  // P2-2-②：file-lifecycle 文档欠账（git behind 事实计算，治「改了生命周期代码忘同步文档」）
+  const lifecycleDoc = detectLifecycleDocStaleness(cwd);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain];
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc];
 
   return {
     dimensions,
@@ -763,6 +771,66 @@ export async function runDoctorDiagnostics({ cwd }) {
   };
 }
 
+// ── D8 file-lifecycle 文档欠账（P2-2-②，2026-09-02 跨 agent 工单）──────────────────
+
+/** 生命周期敏感路径（CLAUDE.md「文件生命周期文档同步」界定的触及面） */
+const LIFECYCLE_DOC_REL = 'docs/sillyspec/file-lifecycle.md';
+const LIFECYCLE_SENSITIVE_PATHS = ['src/stages/', 'src/run.js', 'src/run/', 'src/progress.js', 'src/progress/', 'src/db.js'];
+
+/**
+ * file-lifecycle.md 是否落后于生命周期代码改动（git 提交时间事实比较，只读）。
+ * 与 docs-debt（模块卡 behind 计算）同哲学：CLI 算事实、WARNING 提示不阻断——把 CLAUDE.md
+ * 的「更新检查清单」从人工 checklist 变 doctor 自动卡点（agent 忘同步 → 体检可见）。
+ * 降级语义：文档不存在 / 非 git 仓 / git 失败 → pass: true + findings 注记（不误报）。
+ */
+function detectLifecycleDocStaleness(cwd) {
+  const base = { name: 'lifecycle_doc_staleness', label: '生命周期文档同步', safe_actions: [] };
+  const docAbs = join(cwd, LIFECYCLE_DOC_REL);
+  if (!existsSync(docAbs)) {
+    return { ...base, pass: true, severity: null, findings: [`未找到 ${LIFECYCLE_DOC_REL}（本仓无生命周期总文档，跳过）`] };
+  }
+  // 文档最后提交时间（untracked = 从未提交 → 直接提示）
+  const docLog = safeGit(cwd, ['log', '-1', '--format=%ct', '--', LIFECYCLE_DOC_REL]);
+  if (!docLog.value) {
+    return {
+      ...base,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      findings: [`${LIFECYCLE_DOC_REL} 存在但从未提交（untracked）——首次提交后本检查生效`],
+    };
+  }
+  const docTs = Number(docLog.value);
+  if (!Number.isFinite(docTs)) {
+    return { ...base, pass: true, severity: null, findings: ['文档时间戳不可解析，跳过（不误报）'] };
+  }
+  // 生命周期代码侧最新提交（取各敏感路径 max %ct；任一路径 untracked 新文件不在 log 里，
+  // git 不可见性注记——工作树未提交改动本就不该由 doctor 报，提交后自然可见）
+  let srcTs = 0;
+  let srcPath = null;
+  for (const p of LIFECYCLE_SENSITIVE_PATHS) {
+    const r = safeGit(cwd, ['log', '-1', '--format=%ct', '--', p]);
+    const ts = Number(r.value);
+    if (Number.isFinite(ts) && ts > srcTs) { srcTs = ts; srcPath = p; }
+  }
+  if (srcTs === 0) {
+    return { ...base, pass: true, severity: null, findings: ['生命周期代码无提交历史，跳过'] };
+  }
+  if (docTs < srcTs) {
+    const days = Math.floor((srcTs - docTs) / 86400);
+    return {
+      ...base,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      findings: [
+        `${LIFECYCLE_DOC_REL} 落后生命周期代码改动（最新代码提交 ${srcPath}，文档已落后 ${days} 天）——` +
+        `请按 CLAUDE.md「文件生命周期文档同步」检查清单核对并更新文档 + updated_at 时间戳`,
+      ],
+      safe_actions: [{ dimension: 'lifecycle_doc_staleness', action: 'sync_file_lifecycle_doc', risk: 'manual_edit', rationale: '文档落后于生命周期代码', next_step: `按 CLAUDE.md 检查清单更新 ${LIFECYCLE_DOC_REL} 与头部 updated_at` }],
+    };
+  }
+  return { ...base, pass: true, severity: null, findings: ['file-lifecycle.md 与生命周期代码改动时间线一致'] };
+}
+
 /**
  * 转结构化 JSON（sillyspec doctor --json 输出 + 落盘格式）。
  * severity 口径对齐 scan-postcheck：CHECK_SEVERITY.FAILED → 'critical'。
@@ -996,6 +1064,10 @@ export async function cleanupGhostChanges({ cwd, specDir = null, confirm = false
     db = openDatabase(dbPath, { readOnly: !confirm });
     // last_active 与 name 一起取：空壳判定需要时间门槛（见 isStaleLastActive）。
     const activeRows = db.prepare("SELECT name, last_active FROM changes WHERE status='active'").all();
+    // 有意不排除 quick 会话行（与 D4 ghost 判定不对称是设计，2026-09-07 quick-inflight-ghost
+    // -misjudge 文档明示）：quick 按设计无 changes/ 目录，D4/overview 豁免其 ghost 误报；
+    // 而本函数是「QUICKLOG 已完成但 DB 行仍 active」收尾中断形态的兜底归档出口，保留归档
+    // 能力。归档仅翻 status（可逆），进行中 quick 被误归档时其 --done 收尾链不受影响。
     const ghosts = activeRows.filter((r) => !dirSet.has(r.name)).map((r) => r.name);
     const emptyShells = activeRows
       .filter((r) => dirSet.has(r.name) && isStaleLastActive(r.last_active) && dirHasNoFiles(join(changesDir, r.name)))