sillyspec 3.33.8 → 3.33.9

package/src/flow-parity.js

@@ -305,60 +305,20 @@ export function renderVerifyReceipt({ change, baseline, head, gateSummary, revie
 }
 
 /**
- * design 槽4（风险与死路）实质作答收割 → decisions.md（已有不覆盖）。
- * @returns {{harvested: boolean, reason?: string}}
+ * design 槽4（风险与死路）收割——已下线（2026-11-02-slot4-harvest-retire）。
+ *
+ * 历史动机（2026-09-25-thin-parity-assets）：轻量变更决策产出从零到一，合成底稿条目随蒸馏
+ * 链进 knowledge。4A 数据对账实证产物全是模板底稿（本仓 47 条、平台 173 条），标题模板化、
+ * 无真否决语义——底稿资格门（series-final-cleanup）已解决行为面（不占防复潮席位），本变更
+ * 根治数据面：不再合成伪决策条目。风险分析内容保留在 design.md 归档冻结件（信息零丢失）。
+ *
+ * 函数保留签名与导出（flow.js 调用点已摘除，anchorBackfillCandidate 同文件导出不能删）。
+ * @returns {{harvested: boolean, reason: string}} 恒 {harvested:false}
  */
 export function harvestSlot4Decision({ changeDir, change }) {
   const decPath = join(changeDir, 'decisions.md')
   if (existsSync(decPath)) return { harvested: false, reason: 'decisions.md 已在场（不覆盖）' }
-  let dText
-  try { dText = readFileSync(join(changeDir, 'design.md'), 'utf8') } catch { return { harvested: false, reason: '无 design.md' } }
-  const lines = dText.replace(/\r\n/g, '\n').split('\n')
-  let inSlot = false
-  const buf = []
-  for (const line of lines) {
-    if (/^<!--\s*AGENT:槽4/.test(line)) { inSlot = true; continue }
-    if (inSlot && (/^<!--/.test(line) || /^#{1,6}\s/.test(line))) break
-    if (inSlot) buf.push(line)
-  }
-  let answer = buf.join('\n').trim()
-  // v2 纯 markdown（2026-10-04-thin-docs-v2）：无槽标记时改读「风险与死路」节正文（复用
-  // flow-review 的 v2 节读取——剥离问题原文行；单一源 DESIGN_QUESTIONS 防镜像漂移）
-  if (!inSlot) {
-    const risksSec = DESIGN_QUESTIONS.sections.find((s) => s.key === 'risks')
-    answer = readV2SectionAnswer(dText, risksSec.heading, DESIGN_QUESTIONS)
-  }
-  if (!answer || /^不适用/.test(answer)) return { harvested: false, reason: '槽4 空/不适用' }
-  // 锚点自动回填（2026-10-15-decision-anchor-backfill 收割端）：风险段作答文本恰含一个
-  // 路径 token → 写入 - 锚点：行（源 decisions.md 是真相源，蒸馏自然带上、人可改）；
-  // 0/多候选不写（蒸馏端渲染时还会再兜底一次同款判定）。单一源 anchorBackfillCandidate。
-  const anchorCand = anchorBackfillCandidate(answer)
-  const anchorLine = anchorCand ? [`- 锚点：${anchorCand}`] : []
-  const text = [
-    '---',
-    `author: flow-machine-draft`,
-    `created_at: ${new Date().toISOString()}`,
-    '---',
-    `# 决策记录（Decisions）— ${change}`,
-    '',
-    // 标题自解释（2026-10-15-harvest-title-clarify）：读者面是 decisions 文档与 knowledge，
-    // 机制出处（槽4 收割）由 frontmatter author: flow-machine-draft 承载，标题只说内容与性质。
-    `## D-001@v1: 设计期风险与放弃方案（底稿）`,
-    `- 类型：process`,
-    `- 状态：confirmed`,
-    ...anchorLine,
-    // 类型/状态字段（2026-09-26-slot4-distill-fix）：蒸馏链入选要 status∈{confirmed|accepted|rejected}
-    // 且 type∈七类白名单，字段解析只认 `- 字段：值` 列表行形态——此前收割条目零字段致永不入选，
-    // 「随蒸馏链进 knowledge」断链（thin-agent-tasks 教训留档归档而 knowledge 零落地的实证）。
-    // 槽4 是定案的流程/方法论取舍，process+confirmed 语义成立。
-    `- 答案：${answer.replace(/\s*\n+\s*/g, ' ')}`,
-    // 正文用「答案」标签（同修）：distill 落盘「理由：」行取 entry.answer——此前「- 决策：」非白名单
-    // 字段，正文不随条目进 knowledge（骨架落盘内容丢失）。一行展平（评审 P1 清偿）：字段解析是
-    // 单行契约，多行槽4 作答经 \n 续行会静默丢后续行——收割端压平为单行（空格分隔）保全文。
-    '',
-  ].join('\n')
-  writeAtomicSync(decPath, text)
-  return { harvested: true }
+  return { harvested: false, reason: '底稿收割已下线（2026-11-02-slot4-harvest-retire）——风险分析保留在 design.md 归档件，不再合成伪决策条目' }
 }
 
 export default { reconcileModuleDocs, renderVerifyReceipt, harvestSlot4Decision, collectFreezeFiles, backfillGateSummary, motiveFromInput }

package/src/flow-review.js

@@ -303,6 +303,10 @@ export function renderReviewerTaskbook({ change, changeDir, head = null, probeLi
     `     没有任何声明边界时写「无声明边界」。未裁决=未审。`,
     `  4. 作答中的防护声明（如有）：声称的防护机制在代码里真实存在且生效？`,
     `  5. 生成物同步（如涉及）：类型/契约文件与实现对齐？`,
+    // 测试有效性与根因性（2026-10-29-open-metrics-gate task-04，ub-mode「Test Behavior, Not
+    // Implementation」/「Fix Root Causes」转写）：从「测试存在且绿」升级到「测试有效」——空实现
+    // 判据给评审员可操作的假测试检验法，根因判据拦「吞崩溃 guard 冒充修复」。
+    `  6. 测试有效性与根因性（假测试判据两问）：空实现判据——把绑定测试所测的实现改成全部返回空的空操作，若测试仍可能全绿则测试无效（断言须测可观察行为，mock 一切零断言的摆设测试按无效报）；根因判据——diff 中的修复是否只是吞崩溃/藏失败的 guard（兜底掩盖≠根因消除，须指出并按严重度裁决）。`,
     // 项目评审探针（2026-10-12-review-probe-injection）：local.yaml review_probes 数据驱动注入——
     // 检查单生产权收归 CLI 的项目特有面（dogfood 实证：主代理手写清单没想到的面无人查）。
     // 未配置零注入——本段缺省时任务书与历史形态逐字一致（零回归）。

package/src/flow.js

@@ -31,6 +31,7 @@ import { join, relative, dirname } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
 import yaml from 'js-yaml'
 import { git, gitQuiet } from './git-helper.js'
+import { scopeTelemetryRefs } from './knowledge-graph.js'
 import { writeAtomicSync } from './fs-atomic.js'
 import { resolveRuntimeRoot, triggerSync, triggerSyncTerminalStrict, assertDatedChangeName } from './run/shared.js'
 import { detectUiTouch, buildUiGuidanceLines, runUiVisualProbe, readUiVisualGate, UI_EVIDENCE_FILENAME } from './ui-visual.js'
@@ -308,6 +309,7 @@ export async function flowKnowledgeDigest({ specBase, change, changeDir, input,
       const alwaysRepo = [...scoped.always, ...scoped.repo]
       summary.scopedEntries = alwaysRepo.length
       scopedLines.push('   🧭 工具中立性（内置规约 00，每变更恒注入）：不枚举定义开放世界、不锁死开发语言/框架——配置与机制用 CLI 自有分类（批类别/路径集合），新增语言只加探测适配。')
+      scopedLines.push('   🧭 反例（任务词汇——违规现场词面相似即命中）：评测工具缺省写死两个仓的路径即违规——每条路径必须来自 --repo 参数或缺省当前仓；出现具体项目名/项目特定 env/硬编码仓表即违规（2026-11-02 用户原话纠正实证）。')
       for (const e of alwaysRepo.slice(0, 5)) {
         scopedLines.push(`   📌 [${e.scope}] ${e.id}：${e.summary}`)
       }
@@ -366,13 +368,42 @@ export async function flowKnowledgeDigest({ specBase, change, changeDir, input,
       const src = km.entries.slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)).join('；')
       lines.push(`   📚 知识命中（INDEX 关键词，按需 Read）：${src}`)
     }
+    // routeHits 指针行（FR-04，2026-11-02-knowledge-rank-denoise）：entries 移出 fr/decisions
+    // 路由行后，implemented 决策与 FR 的可见性由这里承载（只指路不注入正文）。
+    if (km.matched && (km.routeHits || []).length > 0) {
+      const src = km.routeHits.slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)).join('；')
+      lines.push(`   🧭 决策/FR 路由命中（专用通道，按需 Read）：${src}`)
+    }
+    // 融合增量（2026-11-02-knowledge-fusion FR-03）：scope 否决独立小节——路由 rejected top-5
+    // 不被热文件历史否决挤占（独立语义：触碰过的文件曾被否决/记死路）
+    const scopeRejected = (km.scopeDecisionHits || []).filter((h) => h.deathPath || h.status === 'rejected').slice(0, 3)
+    if (scopeRejected.length > 0) {
+      lines.push(`   🧭 触达文件关联否决（scope 视角——触碰过的文件曾被否决/记死路，防复潮——除非复潮条件满足勿重提）：`)
+      for (const h of scopeRejected) {
+        const note = h.status === 'rejected' ? (h.reason || '（未记录）') : `死路——${deathPathNote(h.reason)}`
+        lines.push(`   - ${h.id} ${h.title}（${h.file}｜${decisionChangeQualifier(h.change)}｜${h.via === 'two-hop' ? '两跳' : '直连'}）${h.status === 'rejected' ? '否决理由' : '⚰️'}：${note}`)
+      }
+    }
+    const scopeEntries = km.scopeEntries || []
+    if (scopeEntries.length > 0) {
+      const src = scopeEntries.slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)).join('；')
+      lines.push(`   📚 触达文件关联手工条目（按需 Read）：${src}`)
+    }
     // 遥测导线（2026-10-15-thin-inject-telemetry）：轻量道注入此前不落 hits.jsonl——thin 常态化后
     // inject 事件流断流（本仓 10-09 后归零实证），knowledge stats 从未命中判定被盲区污染。
     // 分级字段（A2-lite）：injectedFiles=正文实际注入（thin 面恒空——只出按需 Read 行）、
     // mentionedFiles=显式展示给 agent 的锚点（📚 行 top-3）。既有 matchedFiles 口径不变
     // （knowledge-stats 消费面零回归）。仅命中面非空才落盘；fail-soft（R-04）不阻断注入。
-    const thinMatchedFiles = km.matched ? (km.entries || []).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : []
-    if (thinMatchedFiles.length > 0 || rejected.length > 0) {
+    const thinMatchedFiles = km.matched ? [...(km.entries || []), ...(km.routeHits || [])].map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : []
+    // scope 展示面遥测（FR-02）：独立字段 scopeMatchedFiles（不并入 matchedFiles——防 neverHit 失真）；
+    // mentionedFiles 按实际展示集合（📚 top3 + 🧭 top3 + scope top3+3，去重）
+    const scopeMatchedFiles = km.matched ? scopeTelemetryRefs(km) : []
+    const mentionedFiles = [...new Set([
+      ...(km.entries || []).slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)),
+      ...(km.routeHits || []).slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)),
+      ...scopeMatchedFiles,
+    ])].slice(0, 12)
+    if (thinMatchedFiles.length > 0 || rejected.length > 0 || scopeMatchedFiles.length > 0) {
       try {
         const { appendKnowledgeHit } = await import('./knowledge-hits.js')
         appendKnowledgeHit(join(specBase, '.runtime'), {
@@ -381,7 +412,8 @@ export async function flowKnowledgeDigest({ specBase, change, changeDir, input,
           query: kmQuery,
           matchedFiles: thinMatchedFiles,
           injectedFiles: [],
-          mentionedFiles: thinMatchedFiles.slice(0, 3),
+          mentionedFiles,
+          ...(scopeMatchedFiles.length > 0 ? { scopeMatchedFiles } : {}),
           rejectedCount: rejected.length,
           source: 'thin-start',
         })
@@ -2710,13 +2742,8 @@ export async function cmdFlowDone({ change, cwd, specBase, runtimeRootOpt = null
   // requirements 永不进 knowledge/fr，知识复利在新默认道断流；轻量变更无 design.md，域路由
   // 以基线以来交付 diff 供 deliverableFiles，伪域回退同口径）
   if (st.substeps?.distill === 'done') { skip('distill') } else {
-    // 槽4收割（2026-09-25-thin-parity-assets：design「风险与死路」实质作答合成 decisions.md——
-    // 轻量变更决策产出从零到一；已有 decisions 不覆盖）
-    try {
-      const { harvestSlot4Decision } = await import('./flow-parity.js')
-      const h = harvestSlot4Decision({ changeDir, change })
-      if (h.harvested) console.log(`🌱 槽4（风险与死路）收割 → decisions.md（底稿——作答里的放弃方案请拆成 rejected 条目再收口；随蒸馏链进 knowledge）`)
-    } catch { /* 收割 best-effort */ }
+    // 槽4收割已下线（2026-11-02-slot4-harvest-retire）：design 风险段不再合成伪决策条目——
+    // 风险分析保留在 design.md 归档件（信息零丢失），底稿条目 4A 实证为纯模板噪声
     // 模块变更索引机械回写（2026-10-12-thin-module-gate-and-feed 二档）：命中模块的卡/sidecar
     // 追加一行本变更条目——零语义判断（日期/变更名/动机首行全已知），split-changelog 契约 sidecar
     // 优先、卡内「## 变更索引」节次之、变更名在场即跳过（断点续跑幂等）。moduleScope 由上方

package/src/index.js

@@ -153,7 +153,7 @@ SillySpec CLI — 规范驱动开发工具包
                                       影子存档面：列出 task tick 自动落的存档链，预览/按路径读档
   sillyspec overlap                  查询活跃变更 target-file 声明重叠（advisory——检出即附
                                       worktree 分流与落地序列指引）
-  sillyspec knowledge <search --query "..." --limit N
+  sillyspec knowledge <search --query "..." --limit N [--include-resolved]
                         | inspect --id "..."
                         | validate | refresh
                         | propose --title "..." --category <name>
@@ -3624,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');

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) {