sillyspec 3.33.7 → 3.33.9

package/src/index.js

@@ -148,7 +148,12 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec change-rename <旧变更名> <新变更名>
   sillyspec change-delete <变更名> [--confirm]  删除变更（DB status='deleted' 与归档语义分离 +
                                       移目录 + 清 worktree + 推平台墓碑；默认 dry-run）
-  sillyspec knowledge <search --query "..." --limit N
+  sillyspec checkpoint --change <名> [--diff <sha> [--path <p>]] [--restore <sha>
+                                      [--path <p>|--all] --yes] [--delete-ref]
+                                      影子存档面：列出 task tick 自动落的存档链，预览/按路径读档
+  sillyspec overlap                  查询活跃变更 target-file 声明重叠（advisory——检出即附
+                                      worktree 分流与落地序列指引）
+  sillyspec knowledge <search --query "..." --limit N [--include-resolved]
                         | inspect --id "..."
                         | validate | refresh
                         | propose --title "..." --category <name>
@@ -3619,50 +3624,9 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       }
       break;
     }
-    case 'quicklog': {
-      // known-issues ④ v1（2026-09-16）：QUICKLOG 多会话条目交织——本会话提交 git add 整文件
-      // 会夹带并行会话未完成条目，只能手工四步舞（备份→剥离→commit→恢复）。本命令一键机制化：
-      // 切片（HEAD 基线+本会话条目块）→ 显式 pathspec 提交（QUICKLOG 文件+patches sidecar+额外
-      // pathspec）→ 恢复工作区（并行条目留未提交态）。参数面照抄 wt-commit 先例（--change/-m/--
-      // pathspec）+ 可重复 --ql（guard 缺失/损坏时的显式逃生门；含已取消条目）。
-      if (filteredArgs[1] !== 'commit') {
-        console.error(`❌ 未知 quicklog 子命令: ${filteredArgs[1] || '(空)'}——当前支持: sillyspec quicklog commit [--change <quick会话ID>] -m <信息> [--ql <ql-id>]... [-- <额外pathspec...>]`);
-        process.exit(1);
-      }
-      const qlRest = filteredArgs.slice(2);
-      const qlDd = qlRest.indexOf('--');
-      const qlFlags = qlDd === -1 ? qlRest : qlRest.slice(0, qlDd);
-      const qlExtra = qlDd === -1 ? [] : qlRest.slice(qlDd + 1);
-      let qlChange = null;
-      let qlMessage = null;
-      const qlIds = [];
-      for (let i = 0; i < qlFlags.length; i++) {
-        if (qlFlags[i] === '--change' && qlFlags[i + 1]) qlChange = qlFlags[++i];
-        else if ((qlFlags[i] === '-m' || qlFlags[i] === '--message') && qlFlags[i + 1]) qlMessage = qlFlags[++i];
-        else if (qlFlags[i] === '--ql' && qlFlags[i + 1]) qlIds.push(qlFlags[++i]);
-      }
-      try {
-        const { resolvePlatformSpecDir, resolvePlatformOpts } = await import('./progress.js');
-        const qlSpecBase = resolvePlatformSpecDir(dir, specDir);
-        const { resolveQuickSessionsDir } = await import('./run/shared.js');
-        const qlSessionsDir = resolveQuickSessionsDir(resolvePlatformOpts(dir, specDir), qlSpecBase);
-        let qlUser = 'unknown';
-        try { qlUser = (await import('./git-helper.js')).git(dir, ['config', 'user.name']) || 'unknown'; } catch {}
-        const { runQuicklogCommit } = await import('./quicklog.js');
-        const r = await runQuicklogCommit({
-          specBase: qlSpecBase, cwd: dir, gitUser: qlUser, qlIds,
-          changeName: qlChange, sessionsDir: qlSessionsDir,
-          message: qlMessage, extraPathspecs: qlExtra,
-        });
-        if (json) console.log(JSON.stringify({ command: 'quicklog commit', ...r }, null, 2));
-        else if (r.skipped) console.log(`⏭️  quicklog commit 无新内容跳过（HEAD 不动）：${r.shortHead}（条目均已收编：${(r.skippedQlIds || []).join(', ') || '（无）'}）`);
-        else console.log(`✅ quicklog commit 完成：${r.shortHead}（${r.files.length} 文件；收编 ${(r.committedQlIds || []).join(', ')}）\n   并行会话条目已恢复为工作区未提交态；备份：${(r.backupPaths || []).join(' , ')}`);
-      } catch (e) {
-        console.error(`❌ quicklog commit 失败：${e.message}`);
-        process.exit(1);
-      }
-      break;
-    }
+    // quicklog CLI 子命令已下线（2026-11-03-quicklog-business-retire）：
+    // quicklog 业务面（QUICKLOG 日志系统）用户已停用；工具函数（withFileLock/标题推导等）
+    // 保留在 quicklog.js 供其他模块消费。knowledge-quicklog.js 解析层同批删除。
     case 'worktree': {
       const { WorktreeManager } = await import('./worktree.js');
       const { ProgressManager, resolveSessionIdentity } = await import('./progress.js');
@@ -5055,6 +5019,96 @@ checkbox 行；depends_on 自动反填行内注解 "(depends_on: task-01,02)"；
       process.exitCode = r.ok ? 0 : 1;
       break;
     }
+    case 'checkpoint': {
+      // 2026-10-28-shadow-checkpoint：影子存档面——task tick 自动落档（refs/sillyspec/
+      // checkpoints/<change>），本动词提供列出/预览/读档/清 ref 的人工面。恢复纪律（FR-03）：
+      // --restore 必须显式 --yes；先 --diff 同参预览再执行是推荐路径。
+      const cpVal = (flag) => {
+        const i = filteredArgs.indexOf(flag);
+        return i >= 0 && filteredArgs[i + 1] && !String(filteredArgs[i + 1]).startsWith('--')
+          ? filteredArgs[i + 1] : null;
+      };
+      const cpChange = cpVal('--change');
+      if (!cpChange) {
+        console.error('❌ 用法: sillyspec checkpoint --change <名> [--diff <sha> [--path <p>]] [--restore <sha> [--path <p>|--all] --yes] [--delete-ref]');
+        process.exitCode = 2;
+        break;
+      }
+      const { listCheckpoints, previewRestore, restoreCheckpoint, deleteCheckpointRef } = await import('./checkpoint.js');
+      const cpDiffSha = cpVal('--diff');
+      const cpRestoreSha = cpVal('--restore');
+      const pathArgs = [];
+      for (let i = 0; i < filteredArgs.length - 1; i++) {
+        if (filteredArgs[i] === '--path' && !String(filteredArgs[i + 1]).startsWith('--')) pathArgs.push(filteredArgs[i + 1]);
+      }
+      const cpAll = filteredArgs.includes('--all');
+      const cpYes = filteredArgs.includes('--yes');
+      const cpDeleteRef = filteredArgs.includes('--delete-ref');
+      if (cpDeleteRef) {
+        const okDel = deleteCheckpointRef(dir, cpChange);
+        console.log(okDel ? `🗑️  已删除 refs/sillyspec/checkpoints/${cpChange}` : `ℹ️  无 refs/sillyspec/checkpoints/${cpChange}（无可删）`);
+        break;
+      }
+      if (cpDiffSha) {
+        try {
+          const pv = await previewRestore({ repoRoot: dir, sha: cpDiffSha, paths: pathArgs });
+          console.log(pv.stat || '（无差异）');
+          if (pv.patch) console.log(pv.patch);
+        } catch (e) {
+          console.error(`❌ 预览失败：${e && e.message ? e.message : e}`);
+          process.exitCode = 1;
+        }
+        break;
+      }
+      if (cpRestoreSha) {
+        if (!cpYes) {
+          console.error(`❌ 恢复需显式 --yes（建议先 --diff 同参预览）：sillyspec checkpoint --change ${cpChange} --diff <sha> [--path p] 再 --restore <sha> --path <p> --yes`);
+          process.exitCode = 2;
+          break;
+        }
+        if (!cpAll && pathArgs.length === 0) {
+          console.error('❌ 整树恢复需 --all（按路径恢复用 --path <p>，可多次）');
+          process.exitCode = 2;
+          break;
+        }
+        const rr = await restoreCheckpoint({ repoRoot: dir, sha: cpRestoreSha, changeName: cpChange, paths: pathArgs, all: cpAll });
+        if (rr.ok) console.log(`🗂️  已读档 ${cpRestoreSha.slice(0, 8)} → ${(cpAll ? ['.'] : pathArgs).join(' ')}（仅写工作区，共享暂存区未动）`);
+        else { console.error(`❌ ${rr.reason}`); process.exitCode = 1; }
+        break;
+      }
+      const list = await listCheckpoints({ repoRoot: dir, changeName: cpChange });
+      if (!list.length) {
+        console.log(`ℹ️  变更 ${cpChange} 暂无影子存档（task tick 成功勾选时自动落档；checkpoint.enabled=false 时关闭）`);
+        break;
+      }
+      console.log(`🗂️  变更 ${cpChange} 影子存档链（${list.length} 档，新→旧）：`);
+      for (const c of list) {
+        const when = new Date(c.ts).toISOString().replace('T', ' ').slice(0, 19);
+        console.log(`   ${c.sha.slice(0, 8)}  ${when}  ${c.taskId || '-'}  ${c.files} 文件`);
+      }
+      console.log(`\n预览：sillyspec checkpoint --change ${cpChange} --diff <sha> [--path p]｜读档：--restore <sha> --path <p> --yes${list.length >= 200 ? '\nℹ️  列表显示截 200 档（仅展示面）——全量走 git：git log --format="%H %s" refs/sillyspec/checkpoints/' + cpChange : ''}`);
+      break;
+    }
+    case 'overlap': {
+      // 2026-10-28-overlap-route：target-file 声明重叠仓级查询（advisory 恒 exit 0）——
+      // 事前路由信号：检出重叠附 worktree 分流与落地序列指引（不是禁止是分流）。
+      const { detectDeclaredOverlaps } = await import('./overlap-detect.js');
+      let overlaps = [];
+      try { overlaps = detectDeclaredOverlaps({ cwd: dir, specBase: resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec') }); }
+      catch (e) { console.log(`ℹ️  重叠检测不可用（advisory 面静默退化）：${e && e.message ? e.message : e}`); break; }
+      if (!overlaps.length) {
+        console.log(`✅ 无 target-file 声明重叠——各活跃变更声明面互不相交（落地零冲突预期）`);
+        break;
+      }
+      console.log(`⚠️  ${overlaps.length} 个文件被多个活跃变更声明（并行改同一文件是冲突地带）：`);
+      for (const o of overlaps) {
+        console.log(`   ${o.file} ← ${o.changes.join('、')}`);
+      }
+      console.log(`\n🔀 分流建议：其一转 worktree 形态并行——sillyspec worktree apply <后到变更名>（隔离干活，互不可见互不干扰）。`);
+      console.log(`   落地序列（既有机器）：先落地者干净进主线；后落地者 apply --3way 三方合并（同文件不同区域自动过，同段冲突摆出裁决）；并发落地由 main-repo.lock 串行。`);
+      console.log(`   确认某方已死：归档后其声明自动退出重叠判定（归档件只读）。`);
+      break;
+    }
     case 'flow': {
       // R7 切片二：2-调用轻量协议命令族（start/done/amend-draft）——协议必需交互=2。
       // --json 全局透传（2026-10-06-flow-status-json）：该 flag 在上方全局解析段被剥出
@@ -5806,7 +5860,7 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'change-delete', 'knowledge', 'platform', 'pull', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime', 'watcher', 'commit', 'push'];
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'change-delete', 'checkpoint', 'overlap', 'knowledge', 'platform', 'pull', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime', 'watcher', 'commit', 'push'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
       if (command === '--status') {

package/src/knowledge-graph.js

@@ -20,7 +20,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
-import { parseKnowledgeIndex, parseDecisionEntries, anchorFilePaths } from './knowledge-match.js'
+import { parseKnowledgeIndex, parseDecisionEntries, anchorFilePaths, normalizeAnchorForCompare, matchKnowledge } from './knowledge-match.js'
 import { modulePathMatches, parseModuleMapSimple } from './modules.js'
 import { readHotCache, writeHotCache, dirStamp, fileDirStamp } from './hot-cache.js'
 
@@ -59,6 +59,47 @@ function extractFilePaths(text, cap = 15) {
   return out
 }
 
+/** section 切分：按 `## ` 标题切段（标题到文末；无子标题的整篇为一个无标题段）。 */
+function splitSections(text) {
+  const out = []
+  let cur = null
+  for (const line of text.split('\n')) {
+    const m = /^##\s+(.+)$/.exec(line)
+    if (m) {
+      cur = { title: m[1].trim(), body: '' }
+      out.push(cur)
+      continue
+    }
+    if (cur) cur.body += `${line}\n`
+  }
+  return out
+}
+
+/** section 级正文路径提取（2026-11-02-scope-recall FR-01）：用归一化锚点匹配 section 标题
+ *  （长度≥6 的双向前缀容忍，兼容 INDEX slug 与 heading 的 emoji/标点差异），只对命中 section
+ *  的文本跑路径提取——全文档粒度实测噪声不可接受（单路径最多挂 65 个条目）。
+ *  无锚点条目退化为整篇（保守）。文件读取按次缓存。 */
+function sectionFilePaths(knowledgeDir, ent, cache) {
+  const file = posix(ent.file)
+  if (!file.endsWith('.md')) return []
+  let text = cache.get(file)
+  if (text === undefined) {
+    try { text = readFileSync(join(knowledgeDir, file), 'utf8').replace(/\r\n?/g, '\n') } catch { text = null }
+    cache.set(file, text)
+  }
+  if (!text) return []
+  const key = normalizeAnchorForCompare(ent.anchor)
+  if (!key) return extractFilePaths(text, 15).filter((p) => p.includes('/')) // 无锚点整篇回退同样过滤裸名词
+  const hit = splitSections(text).find((s) => {
+    const hn = normalizeAnchorForCompare(s.title)
+    return hn === key || (hn.length >= 6 && key.length >= 6 && (hn.startsWith(key) || key.startsWith(hn)))
+  })
+  // 裸名词过滤（2026-11-02-knowledge-engine-tail FR-03）：section 正文常含 Next.js/Node.js/
+  // local.yaml/model.py 这类技术名 token——纯词法规则「必须含 /」才建边（存在性判断会让图依赖
+  // 构建时文件系统状态、破坏缓存确定性；只改 section 级，模块卡/scan 采集不动）
+  return hit ? extractFilePaths(hit.body, 15).filter((p) => p.includes('/')) : []
+}
+
 // ── 构建器 ──
 
 function buildKnowledgeGraphFresh(specRoot) {
@@ -94,11 +135,24 @@ function buildKnowledgeGraphFresh(specRoot) {
   let routeCount = 0
   if (existsSync(join(knowledgeDir, 'INDEX.md'))) {
     addNode('doc:INDEX', 'doc', 'knowledge/INDEX.md', { kind: 'manual-index' })
+    const docCache = new Map()
     for (const ent of indexEntries) {
       if (/^(decisions|fr|proposed)\//.test(posix(ent.file))) continue // 决策/FR 有自己的节点面
       const id = ent.anchor ? `entry:${ent.file}#${ent.anchor}` : `entry:${ent.file}`
-      addNode(id, 'entry', ent.display || ent.anchor || ent.file, { file: ent.file, keywords: ent.keywords })
+      addNode(id, 'entry', ent.display || ent.anchor || ent.file, {
+        file: ent.file,
+        keywords: ent.keywords,
+        category: ent.category || '',
+        anchor: ent.anchor || '',
+        display: ent.display || '',
+      })
       if (addEdge('doc:INDEX', id, 'route', ent.keywords[0] || '')) routeCount++
+      // section 级 doc-refs（FR-01，2026-11-02-scope-recall）：手工条目标题路径 → file 边
+      // （medium 强度——scope 层显式消费，graphPath/impact 不受影响）
+      for (const p of sectionFilePaths(knowledgeDir, ent, docCache)) {
+        addNode(p, 'file', p.split('/').pop())
+        addEdge(id, p, 'doc-refs', '手工条目 section 路径')
+      }
     }
   }
 
@@ -349,7 +403,7 @@ function buildKnowledgeGraphFresh(specRoot) {
 // 陈旧边界（有意接受）：指纹感知本目录文件级变化与目录增删，但 docs 树深层就地重写若
 // 未触及被 stat 的文件面则漏——TTL 10min 硬上限兜底，advisory 面有界陈旧可接受。
 
-const GRAPH_CACHE_VERSION = 1
+const GRAPH_CACHE_VERSION = 4
 const GRAPH_CACHE_TTL_MS = 10 * 60 * 1000
 
 function statSignature(p) {
@@ -375,6 +429,13 @@ function knowledgeGraphFingerprint(specRoot) {
   } catch { /* docs/ 缺席 = 无项目面（合法形态）*/ }
   return {
     index: statSignature(join(knowledgeDir, 'INDEX.md')),
+    // 手工文档 stat（FR-01）：section doc-refs 依赖 INDEX 引用的手工文档正文——编辑必须触发重建
+    manualDocs: existsSync(join(knowledgeDir, 'INDEX.md'))
+      ? parseKnowledgeIndex(knowledgeDir)
+        .filter((e) => !/^(decisions|fr|proposed)\//.test(posix(e.file)))
+        .map((e) => [e.file, statSignature(join(knowledgeDir, e.file))])
+        .sort((a, b) => String(a[0]).localeCompare(String(b[0])))
+      : null,
     decisions: fileDirStamp(join(knowledgeDir, 'decisions')),
     fr: fileDirStamp(join(knowledgeDir, 'fr')),
     projects,
@@ -832,18 +893,21 @@ export function graphNodesSearch(graph, search, limit = 20) {
 // ═══════════════════════════════════════════════════════════════
 
 /** scope 文件集 → 可达知识集（decisionHits 形态 + entries 素材）。
- *  遍历：file ←anchors← decision（+supersedes 链一跳）→ from-change/belongs-module 侧线；
- *  FR 侧：file ←deliverables（变更维）与 anchors 直连。rejected ∪ 死路 保底进场（防复潮）。 */
+ *  遍历：file ←anchors← decision/FR（直连，score=2）；supersedes 链一跳；
+ *  file ←doc-refs← 手工条目（section 级正文路径，medium 直证边 → entries）；
+ *  两跳防复潮：file ←deliverables← change ←from-change← rejected/deathPath 决策（score=1）。
+ *  排序：rejected/死路优先 → direct>two-hop → 变更名日期降序 → id。引擎 cap 20。 */
 export function scopeRecall(graph, scopeFiles) {
   const scopes = [...new Set((Array.isArray(scopeFiles) ? scopeFiles : [scopeFiles]).map(posix).filter(Boolean))]
   if (scopes.length === 0) return null
+  const scopeSet = new Set(scopes)
   const strong = graph.edges.filter((e) => EDGE_STRENGTH[e.type] === 'strong')
   const reachable = new Set()
   // 一跳：文件 ←anchors← 决策/FR
   for (const e of strong) {
-    if (e.type === 'anchors' && scopes.includes(e.t)) reachable.add(e.s)
+    if (e.type === 'anchors' && scopeSet.has(posix(e.t))) reachable.add(e.s)
     // 变更维：scope 命中变更交付面（scope 可能传变更名而非文件——调用方宽松契约）
-    if (e.type === 'deliverables' && scopes.includes(e.s)) reachable.add(e.t)
+    if (e.type === 'deliverables' && scopeSet.has(posix(e.s))) reachable.add(e.t)
   }
   // supersedes 链一跳（版本链追新/旧）
   for (const id of [...reachable]) {
@@ -853,37 +917,84 @@ export function scopeRecall(graph, scopeFiles) {
       else if (e.t === id && graph.nodes.has(e.s)) reachable.add(e.s)
     }
   }
+  // 手工条目 doc-refs（FR-01）：medium 边显式消费——不进 strong 集，graphPath/impact 语义不动
+  const entryReachable = new Set()
+  for (const e of graph.edges) {
+    if (e.type !== 'doc-refs' || !scopeSet.has(posix(e.t))) continue
+    const n = graph.nodes.get(e.s)
+    if (n && n.type === 'entry') entryReachable.add(e.s)
+  }
+  // 两跳防复潮（FR-02）：file ←deliverables← change ←from-change← 决策，只收 rejected/deathPath
+  const changesOf = new Set()
+  for (const e of graph.edges) {
+    if (e.type === 'deliverables' && scopeSet.has(posix(e.t))) changesOf.add(e.s)
+  }
+  const twoHop = new Set()
+  for (const e of graph.edges) {
+    if (e.type !== 'from-change' || !changesOf.has(e.t)) continue
+    const n = graph.nodes.get(e.s)
+    if (!n || n.type !== 'decision') continue
+    const h = n.attrs.hit || {}
+    if (h.status === 'rejected' || h.deathPath) twoHop.add(e.s)
+  }
   const decisions = []
-  const frs = []
   for (const id of reachable) {
     const n = graph.nodes.get(id)
     if (!n) continue
     if (n.type === 'decision') decisions.push(n)
-    else if (n.type === 'fr') frs.push(n)
+    // 注：FR 不参与 scope 两跳（图中无内部 anchors/deliverables 边指向 FR 节点；FR 召回由
+    // 域路由 digest（readActiveFrDigest + rankFrDigestForInjection）承载——
+    // 2026-11-02-knowledge-engine-tail 删除恒 0 的 frCount 字段）
+  }
+  // decisionHits：parseDecisionEntries 原生形态（attrs.hit 直出）+ score（direct=2/two-hop=1，
+  // 渲染面 h.status==='rejected' && score>0 过滤器依赖）
+  const changeDate = (c) => {
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(String(c || ''))
+    return m ? m[1] : ''
+  }
+  const hits = []
+  const seen = new Set()
+  const pushHit = (n, score, via) => {
+    const base = n.attrs.hit || {}
+    // 幽灵/畸形过滤（2026-11-02-knowledge-fusion FR-02）：supersedes 链上的 ghost 决策节点
+    // 无 attrs.hit——真实库已复现 {file:undefined,id:undefined} 的畸形 hit 扩散到消费面
+    if (n.attrs.ghost || !base.file || !base.id) return
+    // 去重键含 change（2026-11-02-scope-recall 评审 P2）：D-id 是变更内局部号，跨变更同号常见——
+    // 只按 file#id 去重会让 implemented 直连条目抢先占用键、吞掉 rejected 两跳（渲染面失效）
+    const key = `${base.file}#${base.id}#${base.change || ''}`
+    if (seen.has(key)) return
+    seen.add(key)
+    hits.push({ ...base, file: base.file, score, via })
+  }
+  for (const n of decisions) pushHit(n, 2, 'direct')
+  for (const id of twoHop) {
+    const n = graph.nodes.get(id)
+    if (n) pushHit(n, 1, 'two-hop')
   }
-  // decisionHits：parseDecisionEntries 原生形态（attrs.hit 直出——零重解析），rejected∪死路优先
-  const hits = decisions.map((n) => ({ ...n.attrs.hit, file: n.attrs.hit.file }))
   const death = (h) => h.status === 'rejected' || h.deathPath
-  hits.sort((a, b) => ((b.deathPath ? 1 : 0) - (a.deathPath ? 1 : 0)) || ((b.status === 'rejected' ? 1 : 0) - (a.status === 'rejected' ? 1 : 0)))
-  const rejectedFirst = [...hits.filter(death), ...hits.filter((h) => !death(h))]
-  if (rejectedFirst.length > 20) rejectedFirst.length = 20
-  const entries = rejectedFirst.slice(0, 3).map((h) => ({
-    category: 'Decisions',
-    keywords: ['scope'],
-    file: h.file,
-    anchor: h.id,
-    display: `${h.file}#${h.id}（scope 遍历召回）`,
-  }))
-  return { decisionHits: rejectedFirst, entries, frCount: frs.length, scopeSize: scopes.length }
+  hits.sort((a, b) => (Number(death(b)) - Number(death(a)))
+    || (b.score - a.score)
+    || (changeDate(b.change) > changeDate(a.change) ? 1 : changeDate(b.change) < changeDate(a.change) ? -1 : 0)
+    || String(a.id).localeCompare(String(b.id)))
+  if (hits.length > 20) hits.length = 20
+  // 手工条目（FR-01）：doc-refs 命中的 entry 节点，cap 3
+  const entries = [...entryReachable].map((id) => {
+    const n = graph.nodes.get(id)
+    const a = n.attrs || {}
+    const file = a.file || String(id).replace(/^entry:/, '').split('#')[0]
+    return { category: a.category || 'Scoped', keywords: ['scope'], file, anchor: a.anchor || '', display: a.display || n.label }
+  }).slice(0, 3)
+  return { decisionHits: hits, entries, scopeSize: scopes.length }
 }
 
-/** scopeRecall → matchKnowledge 同构四键返回（knowledge-vector 消费——策略面全本地解析）。 */
+/** scopeRecall → matchKnowledge 同构四键返回（knowledge-vector 消费——策略面全本地解析）。
+ *  entries-only 场景（只命中手工条目、无决策）也必须返回——不得因 decisionHits 空整层短路。 */
 export function buildScopeRecallResult(recall) {
-  if (!recall || recall.decisionHits.length === 0) return null
+  if (!recall || (recall.decisionHits.length === 0 && recall.entries.length === 0)) return null
   return {
     matched: true,
     entries: recall.entries,
-    report: `Status: scope-traversal matched (${recall.decisionHits.length} entries from ${recall.scopeSize} scope files)`,
+    report: `Status: scope-traversal matched (${recall.decisionHits.length} decisions, ${recall.entries.length} entries from ${recall.scopeSize} scope files)`,
     json: {
       matched: true, entry_count: recall.entries.length, scope: true,
       entries: recall.entries.map((e) => ({ file: e.file, anchor: e.anchor, keywords: e.keywords, category: e.category })),
@@ -892,6 +1003,113 @@ export function buildScopeRecallResult(recall) {
   }
 }
 
+// ═══════════════════════════════════════════════════════════════
+// 检索融合（2026-11-02-knowledge-fusion）
+// 路由命中原先 early-return，scope 层（热文件触达的 rejected/手工条目）永远不可达。
+// 契约（子代理审查修正版）：只追加不重排——base 的 decisionHits/entries 原对象原序不动，
+// scope 独有命中进 scopeDecisionHits/scopeEntries（带 via provenance）；不做跨通道 score
+// 排序（路由 Jaccard / scope 2/1 / 向量 / 词片尺度不可比）；空 scope/零命中返回 base 原对象。
+// ═══════════════════════════════════════════════════════════════
+
+/** 融合纯函数：base 路由结果 + recall（scopeRecall）→ 追加字段的新对象；无可追加时返回 base。 */
+export function fuseScopeRecall(base, recall) {
+  if (!base || !base.matched || !recall) return base
+  const dKey = (h) => `${h.file}#${h.id}#${h.change || ''}`
+  const eKey = (e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)
+  const seenD = new Set((base.decisionHits || []).map(dKey))
+  const seenE = new Set((base.entries || []).map(eKey))
+  const addD = []
+  for (const h of recall.decisionHits || []) {
+    if (!h || !h.file || !h.id) continue // 畸形命中过滤（ghost 已在 scopeRecall 侧滤）
+    const k = dKey(h)
+    if (seenD.has(k)) continue
+    seenD.add(k)
+    addD.push({ ...h, via: h.via || 'scope' })
+    if (addD.length >= 20) break
+  }
+  const addE = []
+  for (const e of recall.entries || []) {
+    if (!e || !e.file) continue
+    const k = eKey(e)
+    if (seenE.has(k)) continue
+    seenE.add(k)
+    addE.push({ ...e, via: 'scope' })
+    if (addE.length >= 3) break
+  }
+  if (addD.length === 0 && addE.length === 0) return base
+  return {
+    ...base,
+    ...(addD.length > 0 ? { scopeDecisionHits: addD } : {}),
+    ...(addE.length > 0 ? { scopeEntries: addE } : {}),
+    scopeFused: { decisions: addD.length, entries: addE.length },
+  }
+}
+
+/** 键规整：机器键（design 交付清单/allowed_paths/target_files）→ 图内精确文件路径。
+ *  过滤 glob、目录前缀（尾斜杠）、无扩展名形态；POSIX 归一去重。宁空不造（不猜前缀展开）。 */
+export function graphPathCandidates(files) {
+  const out = []
+  const seen = new Set()
+  for (const raw of Array.isArray(files) ? files : [files]) {
+    const p = String(raw || '').trim().replace(/\\/g, '/').replace(/^\.\//, '')
+    if (!p || /[?*[{\]]/.test(p)) continue
+    if (p.endsWith('/')) continue
+    if (!/\.[A-Za-z0-9]{1,10}$/.test(p)) continue
+    if (seen.has(p)) continue
+    seen.add(p)
+    out.push(p)
+  }
+  return out
+}
+
+/** 进程级图 memo（CLI 短进程生命周期）：路由命中后的融合每次多付 ~45ms 图读取，
+ *  同进程多次调用（多 Wave）复用同一图对象。
+ *  注（2026-11-02-knowledge-engine-tail FR-03）：本 memo 无失效机制——长驻消费方（daemon 等）
+ *  需自行调用 buildKnowledgeGraph 或注入失效；当前无长驻进程走此路径，standalone 分支也保持
+ *  buildKnowledgeGraph（指纹缓存）不统一到 memo（同进程陈旧图有实测）。 */
+const graphMemo = new Map()
+export function getKnowledgeGraph(specRoot) {
+  const key = String(specRoot || '')
+  if (graphMemo.has(key)) return graphMemo.get(key)
+  const g = buildKnowledgeGraph(specRoot)
+  graphMemo.set(key, g)
+  return g
+}
+
+/** 同步融合入口：matchKnowledge（路由+词片回退）→ scope 融合 → 失败原样返回路由结果。
+ *  execute step / Wave 的同步注入路径使用；不改 matchKnowledge 默认语义。 */
+export function matchKnowledgeWithScope(indexDir, query, opts = {}) {
+  const base = matchKnowledge(indexDir, query, { includeResolved: opts.includeResolved })
+  const scopeFiles = graphPathCandidates(opts.scopeFiles || [])
+  if (!base || !base.matched || scopeFiles.length === 0) return base
+  try {
+    const specRoot = String(indexDir).replace(/[\\/]knowledge[\\/]?$/, '')
+    const recall = scopeRecall(getKnowledgeGraph(specRoot), scopeFiles)
+    return fuseScopeRecall(base, recall) || base
+  } catch {
+    return base // fail-soft：scope 构建失败不掉词片回退（FR-05）
+  }
+}
+
+/** scope 展示面遥测引用（2026-11-02-knowledge-engine-tail FR-02）：三处注入点统一口径——
+ *  只记实际展示子集（scope 否决 rejected/deathPath top3 + scopeEntries top3），按 ref 去重。
+ *  独立字段 scopeMatchedFiles，不并入 matchedFiles（否则 knowledge-stats 的 neverHit 失真）。
+ *  includeRejected：flow 有否决独立小节 → true；prompt/execute 渲染器只展示 scopeEntries → false
+ *  （评审 P2-2：遥测必须与实际渲染面对齐，不得记录未展示的条目）。 */
+export function scopeTelemetryRefs(result, { includeRejected = true } = {}) {
+  const shown = [
+    ...(includeRejected
+      ? ((result && result.scopeDecisionHits) || []).filter((h) => h.deathPath || h.status === 'rejected').slice(0, 3)
+      : []),
+    ...((result && result.scopeEntries) || []).slice(0, 3),
+  ]
+  return [...new Set(shown.map((x) => {
+    if (!x) return ''
+    if (x.id) return `${x.file}#${x.id}`
+    return x.anchor ? `${x.file}#${x.anchor}` : x.file
+  }).filter(Boolean))]
+}
+
 /** 变更 decisions.md（九字段形态）「锚点：」字段 → scope 文件集（complete 门的需求期机器键，D-004）。
  *  兼容列表行（`- 锚点：src/x.js:12`）与裸行（`锚点：src/x.js`——归档蒸馏域文件形态）。 */
 export function scopeFromDecisionsMd(text) {