sillyspec 3.28.2 → 3.28.4

package/src/design-facts.js

@@ -352,3 +352,67 @@ export function generateDesignSkeleton({ changeName, decisionsText, author, now
 
   return lines.join('\n')
 }
+
+
+// ---------------------------------------------------------------------------
+// design.md 文件清单行级核验（change: 2026-09-07-ir-hardening，D-004@v1，FR-02）
+// ---------------------------------------------------------------------------
+
+/** 剥路径中的 <...> 占位段（`docs/<project>/scan` → `docs/`；占位形态对齐 collectDocRefs 层1 容差先例） */
+function stripPathPlaceholders(p) {
+  return String(p || '').replace(/<[^/>]*>/g, '').replace(/\/{2,}/g, '/').replace(/\/$/, '')
+}
+
+/**
+ * validateDesignFileList —— design.md 文件变更清单逐条存在性核验（幻觉路径 gate）。
+ *
+ * 分级（design D-004 + Grill P2-⑤）：
+ *   - `NEW:` 前缀（解析器不剥前缀，startsWith 直判）→ 通过（计划新建文件豁免）
+ *   - 路径存在（cwd 相对 existsSync；判前剥 <...> 占位段）→ 通过
+ *   - 含 glob 字符（* / ?）→ warning 跳过（pathMatches 体系本支持 glob 合法形态，existsSync 恒 false 会假 ERROR——fail-soft）
+ *   - 其余 → errors { path, message }（信封 code design_file_ref_invalid）
+ *   - design.md 不存在/无清单段/解析异常 → warnings（small 变更可无清单；fail-soft 不阻断）
+ *
+ * 范围：keepSillyspecDocs=true——`.sillyspec/docs/**` 交付物路径在核验范围内（其余 .sillyspec/ 条目解析器本就丢弃）。
+ * 纯函数不落盘。
+ *
+ * @param {{ changeDir: string, cwd: string }} opts
+ * @returns {{ ok: boolean, errors: Array<{path, message}>, warnings: string[] }}
+ */
+export function validateDesignFileList({ changeDir, cwd } = {}) {
+  const errors = []
+  const warnings = []
+  try {
+    if (!changeDir || !cwd) {
+      return { ok: true, errors, warnings: ['design 清单核验跳过：缺少 changeDir/cwd'] }
+    }
+    const designPath = join(changeDir, 'design.md')
+    if (!existsSync(designPath)) {
+      return { ok: true, errors, warnings: ['design 清单核验跳过：design.md 不存在'] }
+    }
+    const entries = parseFileChangeListDetailed(designPath, { keepSillyspecDocs: true })
+    if (!Array.isArray(entries) || entries.length === 0) {
+      return { ok: true, errors, warnings: ['design 清单核验跳过：design.md 无文件变更清单段（small 变更可无清单）'] }
+    }
+    for (const e of entries) {
+      const raw = String((e && e.path) || '').trim()
+      if (!raw) continue
+      if (raw.startsWith('NEW:')) continue // 计划新建豁免（与 validateTargetFiles 同语义）
+      if (raw.includes('*') || raw.includes('?')) {
+        warnings.push(`design 清单条目含 glob 字符跳过存在性核验：${raw}`)
+        continue
+      }
+      const normalized = stripPathPlaceholders(raw)
+      if (!normalized || normalized === '.') continue
+      if (!existsSync(join(cwd, normalized))) {
+        errors.push({
+          path: raw,
+          message: `design_file_ref_invalid：文件变更清单条目「${raw}」既不存在也无 NEW: 前缀（幻觉路径/书写错误）——修正路径，或计划新建的文件改为 NEW:${raw} 前缀`,
+        })
+      }
+    }
+    return { ok: errors.length === 0, errors, warnings }
+  } catch (e) {
+    return { ok: true, errors, warnings: [`design 清单核验异常 fail-soft 放行：${e && e.message ? e.message : e}`] }
+  }
+}

package/src/dispatch/backends/sillyhub-mcp.js

@@ -234,11 +234,23 @@ dispatch 后在当前 step 内主动轮询，不阻塞等待：
 
 1. **轮询 \`list_workers\`**：间隔默认 15s，可配 local.yaml \`dispatch.poll_interval_ms\`
    - 入参 \`mission_id\`；关注每个 worker 的 status（pending → running → completed/failed）
-2. **per-worker 超时**：默认可配 local.yaml \`dispatch.worker_timeout_ms\`；超时 → 三步兜底：
-   - a. **标记**：调 \`report_progress\` tool（worker_id + 超时说明）记录该 worker 超时
-   - b. **kill lease 防双写**：调 \`report_progress\` tool（worker_id + \`kill: true\` + marker）终止 lease
-     （等价 client.js \`killLease(workerId)\` 路径；SillyHub 当前无专用 kill tool，路径A 落地后升级为专用 kill）
-   - c. **fallback Local 重派**：该 task 改用本机 Agent tool 重派（调 \`sillyspec dispatch hint\` 走 Local 模板）
+2. **worker 活性知情决策（2026-09-07-agent-liveness-states task-13）**：\`list_workers\`
+   返回的 worker 在 **running 期间** 附 \`liveness\` 字段（\`{ state, evidence, derived_at }\`，
+   无则为 null）——\`state\` 取值 \`working\` / \`blocked\` / \`idle\` / \`ended\` / \`unknown\`
+   （daemon liveness 推导；\`blocked\` 主源为第一方权限事件，PERMISSION_REQUEST 等人）。
+   轮询时按活性分流，替代无脑超时 kill：
+   - a. **\`liveness.state=blocked\` 且持续超阈值**（对齐平台 \`BLOCKED_ALERT_MS\`=120s 口径，
+     连续两轮轮询仍 blocked 即视为持续）→ **升级给人**：告知用户该 worker 在等权限确认
+     （harness + evidence），由人处理（平台会同步发 agent_blocked 通知）；**绝不 kill、
+     绝不自动批准**（自动批准权限提示=代人做安全决策，安全敏感）。
+   - b. **\`liveness.state=working\` 且久无终态** → 属长任务场景（日志持续增长、跑测试等），
+     按既有 \`dispatch.worker_timeout_ms\` 继续等待，**不抢跑 kill**——区分「在干活的长任务」
+     与「死了」正是活性字段的价值。
+   - c. **仅当超时且无 liveness / \`liveness.state=unknown\`** → 走既有三步兜底（超时兜底路径）：
+     - ① **标记**：调 \`report_progress\` tool（worker_id + 超时说明）记录该 worker 超时
+     - ② **kill lease 防双写**：调 \`report_progress\` tool（worker_id + \`kill: true\` + marker）终止 lease
+       （等价 client.js \`killLease(workerId)\` 路径；SillyHub 当前无专用 kill tool，路径A 落地后升级为专用 kill）
+     - ③ **fallback Local 重派**：该 task 改用本机 Agent tool 重派（调 \`sillyspec dispatch hint\` 走 Local 模板）
 3. **worker 终态（completed / failed / killed）** → 进入下方回收约定
 
 ${recycleRule}`

package/src/docs-check.js

@@ -28,11 +28,16 @@ import { parseModuleMapSimple } from './modules.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|cjs|ts|tsx|jsx|py|java|go)):(\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，绝不抛；缺文件/无段 → 全缺省）。
@@ -99,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（自然语言，跳过断言防误报）。
@@ -391,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 = []
@@ -405,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）。仅本次调用
   // 生命周期内有效，不跨调用（防测试流程中途改树后读到陈旧结果）
@@ -420,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
@@ -452,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
       }
@@ -489,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 }
 }
 
 /**
@@ -532,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 符号线索（纯位置引用或关键词断言关闭），无法自动定位' }
   }
@@ -578,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 保守默认）`,
+  }
 }
 
 /**
@@ -701,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)
 }
 
 /**
@@ -733,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 }
@@ -1030,3 +1122,37 @@ export function runChangeNameAdvisory(opts) {
   findings.sort((a, b) => a.doc.localeCompare(b.doc) || a.docLine - b.docLine || a.name.localeCompare(b.name))
   return { empty: scanned === 0, scannedDocs: scanned, mentions, uniqueNames: seenNames.size, findings, exempted }
 }
+
+/**
+ * 行号漂移自动重锚（quick --done 接线面，2026-09-08 用户反馈②）：活文档 file:line 硬编码
+ * 随任何源码插入失效，每回手跑 `docs check --fix` 是机械活。本函数 = --fix 主链路的编程化
+ * 封装：对给定文档集跑一次失效收集 → 取分类器判定确定性的条目（fixable 唯一/优选命中，
+ * 与 index.js --fix 同源构造 fixes）→ applyFixes 写回 → 同口径复跑得回执。
+ *
+ * 边界（与 --fix 的既定红线一致）：歧义/零命中条目不动（无 --force 逃生口）；仅改写
+ * fixable 条目的行号段，文件名与 token 原样。任何异常上抛由调用方 fail-open。
+ *
+ * @param {string} projectRoot 源码仓根
+ * @param {string[]} docs 本次改动文档的相对路径列表（audit 口径：changedFiles 中的 .md）
+ * @param {{ crossRepoRoots?: string[] }} [cfg] docs-check 配置（readDocsCheckConfig 产物）
+ * @returns {{ applied: number, invalidBefore: number, invalidAfter: number, remaining: number }}
+ *   applied=0 时 invalidBefore/After 同值（无可自动修条目，调用方维持纯 advisory）
+ */
+export function autoReanchorDocRefs(projectRoot, docs, cfg = {}) {
+  // 与 index.js --fix 完全同口径（skip/keywordAssert 透传；undefined 时 runDocsCheck 解构
+  // 默认值兜底：paths 缺省 glob、keywordAssert=true、exempt=true）
+  const scope = { projectRoot, docs, skip: cfg.skip, keywordAssert: cfg.keywordAssert, crossRepoRoots: cfg.crossRepoRoots };
+  const before = runDocsCheck(scope);
+  const fixes = [];
+  for (const inv of before.invalid) {
+    if (inv.fix && inv.fix.fixable === true && Number.isInteger(inv.fix.newLine)) {
+      fixes.push({ doc: inv.doc, docLine: inv.docLine, ref: inv.ref, newRef: inv.ref.replace(/(\d+)(?:-\d+)?$/, String(inv.fix.newLine)) });
+    }
+  }
+  if (fixes.length === 0) {
+    return { applied: 0, invalidBefore: before.invalid.length, invalidAfter: before.invalid.length, remaining: before.invalid.length };
+  }
+  const applied = applyFixes(projectRoot, fixes);
+  const after = runDocsCheck(scope);
+  return { applied: applied.applied, invalidBefore: before.invalid.length, invalidAfter: after.invalid.length, remaining: after.invalid.length };
+}

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