sillyspec 3.28.0 → 3.28.3

package/src/docs-check.js

@@ -18,16 +18,26 @@ 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
+ * 正则组：1=仓库名（可选），2=文件，3=start，4=end。
+ * 文件段展开循环形（D-006，2026-09-08-docs-fix-capability）：普通段可选 + 零或多个「闭合括号段+普通段」
+ * 迭代——支持 Next.js 路由组 (dashboard) 等括号路径；markdown 链接 [t](foo.js:12) 在 `(` 处括号段
+ * 要求 `)` 先于 `:` 闭合而失败，回落 foo.js:12 零回归；嵌套 ((x)) 部分提取（与旧行为一致）。
+ * ⚠ 不用原子序列 (?:A+|B+)+——经典嵌套量词 ReDoS（Grill 实证 n=30 长 token 73.8s），
+ * 展开循环每次迭代必含括号段 → 划分唯一 → 线性。 */
+const REF_RE = /(?:repo:\/\/([A-Za-z0-9_.\-]+)\/)?([A-Za-z0-9_.\-\/]*(?:\([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']
+export const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md']
 
 /**
  * 读 local.yaml 的 docs-check 段（best-effort，绝不抛；缺文件/无段 → 全缺省）。
@@ -94,6 +104,44 @@ export function collectDocRefs(md) {
   return refs
 }
 
+/**
+ * 豁免判定双通道（FR-3 / D-003，2026-09-08-docs-fix-capability）：
+ * ①路径段：POSIX 归一后任一路径段 === archive 或 finished（历史快照/归档文档天然过时）；
+ * ②frontmatter：文件头 --- 块内行 `doc_type: snapshot`（机械精确匹配——容忍行内注释与首尾
+ * 空白，带引号 doc_type: "snapshot" 不识别，不做 YAML 解析）。
+ * 拆两函数：路径段判免 IO（readFileSync 前）；frontmatter 判需文件内容。
+ * @param {string} relPath 文档相对路径（POSIX 或 Windows 反斜杠均可）
+ * @returns {boolean}
+ */
+export function isExemptDocPath(relPath) {
+  if (typeof relPath !== 'string' || relPath === '') return false
+  const segs = relPath.replace(/\\/g, '/').split('/')
+  return segs.some(s => s === 'archive' || s === 'finished')
+}
+
+/**
+ * frontmatter 通道：文件头 --- 块内机械扫描 `doc_type: snapshot` 行。
+ * @param {string} mdText 文档全文（已读取）
+ * @returns {boolean}
+ */
+export function isExemptDocFrontmatter(mdText) {
+  if (typeof mdText !== 'string' || !mdText.startsWith('---')) return false
+  const end = mdText.indexOf('\n---', 3)
+  if (end === -1) return false
+  const block = mdText.slice(3, end)
+  return /^[ \t]*doc_type:[ \t]*snapshot[ \t]*(?:#.*)?$/m.test(block)
+}
+
+/**
+ * 双通道合并（调用方便利包装）。
+ * @param {string} relPath 文档相对路径
+ * @param {string} [mdText] 文档全文（路径段命中时可省——调用方先判路径段免 IO）
+ * @returns {boolean}
+ */
+export function isExemptDoc(relPath, mdText) {
+  return isExemptDocPath(relPath) || (mdText !== undefined && isExemptDocFrontmatter(mdText))
+}
+
 /**
  * 纯函数：判定 token 是否「像代码符号」：首字符字母/_/$，且含大写字母/下划线/点/$ 之一。
  * 纯小写英文单词（local/platform/abort）→ false（自然语言，跳过断言防误报）。
@@ -183,7 +231,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 +305,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 排除用，仅 * 单段） */
@@ -317,7 +434,7 @@ export function runDocsCheck(opts) {
   // 解构默认值只挡 undefined 不挡 null——docs-check 无配置裸跑曾因此 null.flatMap 崩溃。
   const {
     projectRoot, docs = null, paths: rawPaths = DEFAULT_DOC_PATHS, skip = [],
-    keywordAssert = true, crossRepoRoots = {},
+    keywordAssert = true, crossRepoRoots = {}, exempt = true,
   } = opts || {}
   const paths = Array.isArray(rawPaths) && rawPaths.length > 0 ? rawPaths : DEFAULT_DOC_PATHS
   const warnings = []
@@ -331,6 +448,10 @@ export function runDocsCheck(opts) {
   let kwChecked = 0
   // repo:// 跨仓引用：未配映射被跳过的数量（不计入 total/invalid，跨设备零误报）
   let crossRepoSkipped = 0
+  // 豁免文档数（archive/finished 路径段或 frontmatter doc_type: snapshot，不计 invalid——FR-3）
+  let skippedExempt = 0
+  // 模糊路径引用数（含 `...` 省略号，跳过校验——FR-1.2）
+  let skippedFuzzy = 0
   // per-call 缓存：裸名引用的 src/ 全树扫描结果 + 候选文件行数组——100 文档 × 10 裸名引用
   // 此前 = 1000 次全树 walk + 同文件 N 次重读（2026-08-21 性能审查 PERF-5）。仅本次调用
   // 生命周期内有效，不跨调用（防测试流程中途改树后读到陈旧结果）
@@ -346,11 +467,17 @@ export function runDocsCheck(opts) {
       })
       continue
     }
+    // 豁免双通道（FR-3 / D-003）：路径段判定免 IO（readFileSync 前）；
+    // frontmatter 判定需读文件（读取后）。豁免文档整体跳过不计 invalid。
+    if (exempt && isExemptDocPath(docRel)) { skippedExempt++; continue }
     const md = readFileSync(docAbs, 'utf8')
+    if (exempt && isExemptDocFrontmatter(md)) { skippedExempt++; continue }
     const refs = collectDocRefs(md)
     const mdLines = md.split(/\r?\n/)
 
     for (const r of refs) {
+      // 模糊路径（含 `...` 省略号）：跳过校验（FR-1.2，宁漏不误报——文档作者明示意图非精确路径）
+      if (r.file.includes('...')) { skippedFuzzy++; continue }
       // repo:// 跨仓引用：未配映射 → 跳过（不同设备仓库位置不同，不按本仓解析误报）；
       // 配了映射 → 以映射根为唯一候选，走与本地引用相同的层1+层2 校验。
       let candidates
@@ -378,10 +505,20 @@ export function runDocsCheck(opts) {
       }
       total++
       if (candidates.length === 0) {
+        // FR-4（candidates JSON）：带 / 路径的文件不存在引用，basename 树扫非空 → 附同名文件候选
+        // （机械数据供脚本消费；裸文件名引用 resolveCandidates 已全树扫返回空时重扫恒空，无意义——Grill 修正）
+        const fixEntry = { fixable: false, reason: '文件不存在，无法自动定位' }
+        if (r.file.includes('/')) {
+          const baseName = r.file.slice(r.file.lastIndexOf('/') + 1)
+          const sameName = findInTree(join(projectRoot, 'src'), baseName, '', treeCache)
+          if (sameName.length > 0) {
+            fixEntry.candidates = sameName.map(rel => ({ file: 'src/' + rel }))
+          }
+        }
         invalid.push({
           doc: docRel, docLine: r.docLine, ref: r.ref,
           reason: '文件不存在（含 / 按仓库根解析；裸文件名在 src/ 递归）',
-          fix: { fixable: false, reason: '文件不存在，无法自动定位' },
+          fix: fixEntry,
         })
         continue
       }
@@ -395,13 +532,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]
@@ -418,13 +552,13 @@ export function runDocsCheck(opts) {
           // 建议行号（--suggest）：token 在首个候选文件的全量命中行，供人工确认改锚——不自动改文件
           suggest: suggestLines(candidates, tokens, linesCache),
           // 修复分类（--fix 判定依据）：全量候选 token 命中打分——唯一命中或选优严格领先可自动重锚
-          fix: classifyFix(candidates, tokens, r.start, linesCache),
+          fix: classifyFix(candidates, tokens, r.start, linesCache, projectRoot),
         })
       }
     }
   }
 
-  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked, crossRepoSkipped }
+  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked, crossRepoSkipped, skippedExempt, skippedFuzzy }
 }
 
 /**
@@ -461,13 +595,14 @@ function suggestLines(candidates, tokens, linesCache = null) {
  * @param {string[]} candidates resolveCandidates 返回的全量候选绝对路径
  * @param {string[]} tokens 层2 提取的期望 token（keywordAssert=false 时为空数组）
  * @param {number|null} [refStart] 文档引用的旧行号（打分用距离信号；范围引用取 start）
- * @returns {{ fixable: boolean, newLine?: number, reason: string }}
+ * @param {string} [projectRootHint] candidates 相对路径显示锚（tie candidates 的 file 字段用）
+ * @returns {{ fixable: boolean, newLine?: number, candidates?: Array<{file?: string, line: number}>, reason: string }}
  */
 function escapeReLocal(s) {
   return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
-function classifyFix(candidates, tokens, refStart = null, linesCache = null) {
+function classifyFix(candidates, tokens, refStart = null, linesCache = null, projectRootHint = '') {
   if (tokens.length === 0) {
     return { fixable: false, reason: '无 token 符号线索（纯位置引用或关键词断言关闭），无法自动定位' }
   }
@@ -507,7 +642,16 @@ function classifyFix(candidates, tokens, refStart = null, linesCache = null) {
     }
   }
   const shown = ranked.slice(0, 8).map(([l]) => l).join('、') + (ranked.length > 8 ? '…' : '')
-  return { fixable: false, reason: `token 多处命中且最优两行同分（候选行号：${shown}），歧义需人工确认（D-006 保守默认）` }
+  // FR-4（candidates JSON）：tie 歧义时附机械候选行号数组（供 --json 消费，无置信度——D-001 边界）。
+  // file 字段仅在单候选文件时有意义（多候选同分行号已合并，行号不区分文件归属）。
+  const tieCandidates = ranked.slice(0, 8).map(([l]) =>
+    candidates.length === 1 ? { file: relDisplay(candidates[0], projectRootHint), line: l } : { line: l }
+  )
+  return {
+    fixable: false,
+    candidates: tieCandidates,
+    reason: `token 多处命中且最优两行同分（候选行号：${shown}），歧义需人工确认（D-006 保守默认）`,
+  }
 }
 
 /**
@@ -630,23 +774,35 @@ function extractKnownFailureKeys(yamlText) {
   if (inline) {
     return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
   }
-  // 坑 verify-known-failures-comment-line-truncation 同款（与 verify-postcheck.extractKnownFailures
-  // 口径互指对齐）：块内注释行/空行打断连续列表项捕获链 → 注释后的键静默丢失。块定义放行
-  // 注释行与空行；提取侧只认 - 项行；行尾注释须 # 前有空白（裸 # 不截）；引号值原样保留。
-  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?|[ \t]*#[^\n]*\n?|[ \t]*\n)+)/m)
-  if (block) {
-    return (block[1].match(/^[ \t]+-[ \t]+(.+)/gm) || [])
-      .map(s => {
-        const item = s.replace(/^[ \t]+-[ \t]+/, '').trim()
-        const full = item.match(/^(['"])(.*)\1$/)
-        if (full) return full[2]
-        const stripped = item.replace(/[ \t]+#.*$/, '').trim()
-        const q2 = stripped.match(/^(['"])(.*)\1$/)
-        return q2 ? q2[2] : stripped
-      })
-      .filter(Boolean)
+  // 坑 verify-known-failures-comment-line-truncation → verify-known-failures-block-fragile-chain
+  // （与 verify-postcheck.extractKnownFailures 口径互指对齐，逐字同步）：块式捕获曾要求
+  // 「- 项行 / 注释行 / 空行」连续成链，手改残留的缩进杂行/空项断链 → 其后键静默丢失。
+  // 改为逐行扫描：块 = 头之后连续的「缩进行 / 注释行（任意缩进含列首）/ 空行」，列首正文行
+  // 收块；块内杂行容忍不提取但不断链，`- ` 项行无论隔着什么都提取。
+  // 行尾注释须 # 前有空白（裸 # 不截）；引号值原样保留。
+  const lines = yaml.split('\n')
+  const headIdx = lines.findIndex(l => /^known_failures:\s*(?:#.*)?$/.test(l))
+  if (headIdx === -1) return []
+  const itemRe = /^[ \t]+-[ \t]+(.+)$/
+  const items = []
+  for (let i = headIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (l.trim() === '') continue // 空行：块内分隔，放行
+    if (/^[ \t]*#/.test(l)) continue // 注释行（任意缩进含列首）：段头/归因注记，放行
+    if (!/^[ \t]/.test(l)) break // 列首正文行：下一个顶层键，收块
+    const m = l.match(itemRe) // 其余缩进行一律留在块内；项行才提取（杂行不提取但不断链）
+    if (m) items.push(m[1])
   }
-  return []
+  return items
+    .map(s => {
+      const item = s.trim()
+      const full = item.match(/^(['"])(.*)\1$/)
+      if (full) return full[2]
+      const stripped = item.replace(/[ \t]+#.*$/, '').trim()
+      const q2 = stripped.match(/^(['"])(.*)\1$/)
+      return q2 ? q2[2] : stripped
+    })
+    .filter(Boolean)
 }
 
 /**
@@ -662,8 +818,15 @@ export function readDecisionRulesConfig(projectRoot) {
     const p = join(projectRoot, '.sillyspec', 'local.yaml')
     if (!existsSync(p)) return fallback
     const raw = readFileSync(p, 'utf8')
+    // knownFailures 用容错行扫描提取（与 verify-postcheck.extractKnownFailures 同款），且先于
+    // jsYaml——YAML 整体不合法（如 known_failures 块内手改残迹行）时 jsYaml 抛错不能连带丢掉
+    // 豁免键（坑 verify-known-failures-block-fragile-chain：曾整段 catch 回 fallback、键静默丢）。
+    // jsYaml 只供 behind_threshold，单独兜底；豁免键在任何形态下存活。
     const knownFailures = extractKnownFailureKeys(raw)
-    const doc = jsYaml.load(raw)
+    let doc = null
+    try {
+      doc = jsYaml.load(raw)
+    } catch { doc = null }
     if (!doc || typeof doc !== 'object') return { ...fallback, knownFailures }
     const d = doc['decisions']
     if (!d || typeof d !== 'object' || Array.isArray(d)) return { ...fallback, knownFailures }

package/src/docs-migrate.js

@@ -0,0 +1,124 @@
+/**
+ * docs migrate：确定性批量路径前缀迁移（2026-09-08-docs-fix-capability / D-002+D-004）。
+ *
+ * 动机：文档引用批量路径迁移（如 modules/ → backend/app/modules/）是已知改名规则的确定性
+ * 替换，不该靠手写临时脚本。薄模块——import 复用 docs-check 的提取/校验/写回，不复制解析正则。
+ *
+ * 语义（D-002）：只做用户显式给定的 --from/--to 前缀替换（零推断）；改动面=docs check 所辖
+ * .md 文件中的 file:line 引用文本；默认 dry-run 列计划，--apply 才写盘；写盘后自动 docs check
+ * 复核（防 from/to 写反）。不碰 git 历史、不改非引用文本。
+ *
+ * exit code（CLI 层）：0=dry-run 零计划或 --apply 后 postCheck 全绿；1=--apply 后仍失效或
+ * unverified>0；2=用法/配置错误；dry-run 有计划恒 0（预览不判成败）。
+ *
+ * 纯 Node 内置模块零依赖（与 docs-check.js 同款）。
+ */
+import { join } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import {
+  collectDocRefs,
+  resolveCandidates,
+  readDocsCheckConfig,
+  applyFixes,
+  runDocsCheck,
+  DEFAULT_DOC_PATHS,
+  walkGlob,
+} from './docs-check.js'
+
+/**
+ * 生成迁移计划（纯函数，不写盘）。
+ * 文档集与 docs check 同源（readDocsCheckConfig paths/skip——校验面即改写面）。
+ * @param {{ projectRoot: string, from: string, to: string, docs?: string[], paths?: string[], skip?: string[] }} opts
+ *   from/to 为用户显式前缀（如 'modules/' → 'backend/app/modules/'）
+ * @returns {{ plans: Array<{doc, docLine, ref, newRef, verified}>, scanned: number }}
+ *   plans 按 doc+docLine 排序；verified=false 表示新路径经 resolveCandidates 验证 0 候选（unverified）
+ */
+export function planDocsMigrate(opts) {
+  const { projectRoot, from, to } = opts || {}
+  if (!projectRoot || typeof from !== 'string' || from === '' || typeof to !== 'string' || to === '') {
+    throw new Error('planDocsMigrate: from/to 必填且非空')
+  }
+  const cfg = readDocsCheckConfig(projectRoot)
+  const paths = (opts.paths && opts.paths.length > 0 ? opts.paths : null)
+    || cfg.paths
+    || DEFAULT_DOC_PATHS
+  const skip = opts.skip || cfg.skip
+  const docFiles = (opts.docs && opts.docs.length > 0)
+    ? opts.docs
+    : [...new Set(paths.flatMap(p => walkGlob(projectRoot, p, skip)))].sort()
+
+  const plans = []
+  const treeCache = new Map()
+  for (const docRel of docFiles) {
+    const docAbs = join(projectRoot, docRel)
+    if (!existsSync(docAbs)) continue
+    const md = readFileSync(docAbs, 'utf8')
+    const refs = collectDocRefs(md)
+    for (const r of refs) {
+      if (r.repo) continue // 跨仓引用不迁移（repo:// 前缀）
+      if (!r.file.startsWith(from)) continue
+      if (from === to) continue // from=to 时 newRef === ref，无迁移意义（零计划）
+      const newFile = to + r.file.slice(from.length)
+      const linePart = r.end !== r.start ? `:${r.start}-${r.end}` : `:${r.start}`
+      const newRef = newFile + linePart
+      const newCandidates = resolveCandidates(projectRoot, newFile, treeCache)
+      plans.push({
+        doc: docRel,
+        docLine: r.docLine,
+        ref: r.ref,
+        newRef,
+        verified: newCandidates.length > 0,
+      })
+    }
+  }
+  plans.sort((a, b) => a.doc.localeCompare(b.doc) || a.docLine - b.docLine)
+  return { plans, scanned: docFiles.length }
+}
+
+/**
+ * 执行迁移：默认 dry-run 输出计划表；--apply 写盘（applyFixes）+ 自动 docs check 复核。
+ * @param {{ projectRoot: string, from: string, to: string, apply?: boolean, docs?: string[], paths?: string[], skip?: string[] }} opts
+ * @returns {{ plans, applied, skipped, unverified, postCheck?: {invalid, total} }}
+ */
+export function runDocsMigrate(opts) {
+  const { apply = false } = opts || {}
+  const { plans, scanned } = planDocsMigrate(opts)
+  const unverified = plans.filter(p => !p.verified)
+
+  if (!apply) {
+    // dry-run：打印计划表，零写盘
+    if (plans.length === 0) {
+      console.log(`✅ docs migrate: 扫描 ${scanned} 个文档，无可迁移引用（from=${opts.from} 无匹配）`)
+    } else {
+      console.log(`📋 docs migrate 计划（dry-run 未写盘）：扫描 ${scanned} 个文档，${plans.length} 处引用可迁移${unverified.length > 0 ? `（${unverified.length} 处 unverified）` : ''}：`)
+      for (const p of plans) {
+        const mark = p.verified ? '✅' : '⚠️'
+        console.log(`  ${mark} [${p.doc}:L${p.docLine}] ${p.ref} → ${p.newRef}${p.verified ? '' : '（目标不存在）'}`)
+      }
+      console.log(`\n确认后加 --apply 写盘；unverified 项请核对 from/to 是否写反。`)
+    }
+    return { plans, applied: 0, skipped: [], unverified: unverified.length }
+  }
+
+  // --apply：applyFixes 写盘（shape 一致，含 R-04 行内偏移防护）
+  const { applied, skipped } = applyFixes(opts.projectRoot, plans)
+  // 写盘后自动 docs check 复核（防 from/to 写反）
+  const postCheck = runDocsCheck({
+    projectRoot: opts.projectRoot,
+    paths: opts.paths || null,
+    skip: opts.skip || [],
+  })
+  console.log(`✅ docs migrate: ${applied} 处已写回${skipped.length > 0 ? `、${skipped.length} 处写回跳过` : ''}（${unverified.length} 处 unverified）。`)
+  console.log(`📊 迁移后 docs check：${postCheck.invalid.length}/${postCheck.total} 处失效。`)
+  if (unverified.length > 0) {
+    console.warn(`⚠️ ${unverified.length} 处 unverified（目标不存在），请核对 from/to 是否写反：`)
+    for (const p of unverified.slice(0, 10)) console.warn(`   - [${p.doc}:L${p.docLine}] ${p.ref} → ${p.newRef}`)
+  }
+  return {
+    plans,
+    applied,
+    skipped,
+    unverified: unverified.length,
+    postCheck: { invalid: postCheck.invalid.length, total: postCheck.total },
+  }
+}

package/src/doctor-diagnostics.js

@@ -26,7 +26,7 @@ import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSy
 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 = {
@@ -424,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 个空壳即此漏网形态）。
@@ -1059,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)))

package/src/endpoint-baseline.js

@@ -0,0 +1,109 @@
+/**
+ * endpoint-baseline.js — 变更级端点 before/after 基线（变更 2026-09-07-endpoint-baseline）
+ *
+ * 背景：contract-matrix 只有 provider 完成后的 endpoints.json 事后快照，无变更前基线——
+ * 端点增删（archify Delta 核心内容之一）无法计算。本模块补齐：
+ *   - captureEndpointBaseline：变更起点拍端点集快照（幂等，已存在不覆盖）
+ *   - diffEndpointSets：基线 × 现算的集合运算纯函数（method+path 粒度）
+ *
+ * 消费链：CLI `endpoints baseline`（task-02）→ endpoint-baselines/<change>.json →
+ * archive-delta 第五源（Wave 2）对比出 delta.md「端点增删」节。
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { scanBackendEndpoints, normalizePath } from './endpoint-extractor.js'
+import { gitQuiet } from './git-helper.js'
+
+/**
+ * diff 键归一：method 大写 + normalizePath 参数归一（endpoint-extractor.js 既有导出，
+ * diffApiParity 同款——`:id/{plan_id}` / `{plan_id}/{id}` 等参数形态统一为 `{param}`）
+ * + 去尾斜杠（`/api/x/` 与 `/api/x` 同键；全斜杠归一为 `/`）。
+ * @param {{ method?: string, path?: string }} ep
+ * @returns {string} 形如 `GET /api/ppm/project-plan/{param}`
+ */
+function endpointKey(ep) {
+  const normalized = normalizePath(ep.path || '').replace(/\/+$/, '') || '/'
+  return `${(ep.method || '').toUpperCase()} ${normalized}`
+}
+
+/**
+ * 拍变更前端点基线：endpoint-extractor 现扫 cwd → 写 <runtimeRoot>/endpoint-baselines/<change>.json。
+ *
+ * - 幂等：目标文件已存在 → {written:false, reason:'exists'}（不读旧内容不覆盖——首次跑
+ *   即变更前状态，重跑保持原快照）；存在性检查先于扫描（已拍过直接跳过，不做无效重扫）。
+ * - fail-soft：扫描异常返回错误对象不抛（调用方降级注记，不阻断流程）。
+ * - cwd 锚定主仓根由调用方保证（task-02 CLI 层职责），本函数不做锚定。
+ *
+ * @param {{ cwd: string, changeName: string, runtimeRoot?: string }} opts
+ *   runtimeRoot 缺省 join(cwd, '.sillyspec', '.runtime')
+ * @returns {{ written: boolean, reason?: 'exists', count?: number, path?: string, error?: string }}
+ */
+export function captureEndpointBaseline({ cwd, changeName, runtimeRoot } = {}) {
+  const root = runtimeRoot || join(cwd, '.sillyspec', '.runtime')
+  const baselineDir = join(root, 'endpoint-baselines')
+  const baselinePath = join(baselineDir, `${changeName}.json`)
+
+  // 幂等守卫在前：已存在直接跳过（不读旧内容不覆盖）
+  if (existsSync(baselinePath)) return { written: false, reason: 'exists' }
+
+  let endpoints
+  try {
+    endpoints = scanBackendEndpoints(cwd)
+  } catch (e) {
+    return { written: false, error: (e && e.message) || String(e) }
+  }
+
+  // git rev-parse fail-soft：非仓库/git 缺失 → null（基线仍可拍，端点集是主体）
+  const baseCommit = gitQuiet(cwd, ['rev-parse', '--short', 'HEAD']) || null
+
+  const payload = {
+    schemaVersion: 1,
+    change: changeName,
+    baseCommit,
+    generatedAt: new Date().toISOString(),
+    endpoints: endpoints.map(e => ({ method: e.method, path: e.path, source: e.source })),
+  }
+
+  mkdirSync(baselineDir, { recursive: true })
+  writeFileSync(baselinePath, JSON.stringify(payload, null, 2) + '\n', 'utf8')
+  return { written: true, count: payload.endpoints.length, path: baselinePath }
+}
+
+/**
+ * 端点集合 diff：baseline × current 按 method+归一 path 做 Map 集合运算。
+ *
+ * - 任一输入为 null/非数组 → null（调用方降级：无基线不比）。
+ * - added：current 有 baseline 无（带 current 的 source）；removed：反向（带 baseline 的 source）。
+ * - changed（同 path 参数改名等）不配对——归一键相同则判同（`:id/{plan_id}` vs
+ *   `{param}/{plan_id}` 同键不假报）；键不同的变更天然呈 removed+added 两条独立行
+ *   （design Gap-3 显式声明，防止实现期发明配对逻辑）。
+ *
+ * @param {Array<{method:string,path:string,source:string}>|null} baselineEndpoints
+ * @param {Array<{method:string,path:string,source:string}>|null} currentEndpoints
+ * @returns {{ added: Array<{method,path,source}>, removed: Array<{method,path,source}> } | null}
+ */
+export function diffEndpointSets(baselineEndpoints, currentEndpoints) {
+  if (!Array.isArray(baselineEndpoints) || !Array.isArray(currentEndpoints)) return null
+
+  const baselineMap = new Map()
+  for (const ep of baselineEndpoints) {
+    const key = endpointKey(ep)
+    if (!baselineMap.has(key)) baselineMap.set(key, ep) // 同键保留首个，防重复行
+  }
+  const currentMap = new Map()
+  for (const ep of currentEndpoints) {
+    const key = endpointKey(ep)
+    if (!currentMap.has(key)) currentMap.set(key, ep)
+  }
+
+  const added = []
+  for (const [key, ep] of currentMap) {
+    if (!baselineMap.has(key)) added.push({ method: ep.method, path: ep.path, source: ep.source })
+  }
+  const removed = []
+  for (const [key, ep] of baselineMap) {
+    if (!currentMap.has(key)) removed.push({ method: ep.method, path: ep.path, source: ep.source })
+  }
+  return { added, removed }
+}