sillyspec 3.33.8 → 3.33.9

package/src/knowledge-match.js

@@ -62,6 +62,10 @@ function isDecisionRoute(entry) {
 }
 
 const DECISION_HEADER_RE = /^##\s+(D-(?:[A-Za-z0-9_\-\u4e00-\u9fff]+-)?\d+@v\d+)\s*(.*)$/
+
+/** 底稿模板标题特征词（与 4A provenance 分类同源单一口径）：harvestSlot4Decision 产的
+ *  process 级流程取舍框架词——不是具体方案否决，deathPath 不应赋予（2026-11-02-series-final-cleanup）。 */
+const TEMPLATE_TITLE_RE = /设计期风险与放弃方案|风险与死路|design\s*槽\s*4\s*收割|底稿/
 const DECISION_FIELD_RE = /^(状态|文件|理由|否决理由|复潮条件|supersedes)\s*[：:]\s*(.*)$/
 // 「锚点：」单独标签精确匹配读入（仿 docs-check.js parseDecisionEntries 先例）——绝不并入
 // DECISION_FIELD_RE：其 else-if 链末尾的 reason 回填（else if (!cur.reason)）会把锚点值
@@ -130,7 +134,11 @@ function parseDecisionFile(filePath, file) {
       // 死路注记识别（2026-09-28-knowledge-inject-ranking）：「理由」含「死路：」字面标记的教训型
       // 条目——记录它的决策本体是 accepted/implemented（死路只是理由里的注记），按状态过滤会被
       // 压制到组外，恰丢最该防复潮的（实测：D-001@v1 枚举开放世界排 148/188 位永不回显）。
-      cur.deathPath = /死路[：:]/.test(cur.reason || '')
+      // 底稿资格门（2026-11-02-series-final-cleanup）：模板标题条目（设计期风险与放弃方案/风险
+      // 与死路/底稿——harvestSlot4Decision 产的 process 级流程取舍）不获 deathPath——它们不是真
+      // 否决，标 deathPath 会占防复潮席位且使停车场清零条件永不可满足（终审实证 4C/5/6 归档蒸馏
+      // 又产出 4 条底稿 D-485~488）
+      cur.deathPath = /死路[：:]/.test(cur.reason || '') && !TEMPLATE_TITLE_RE.test(cur.title || '')
       hits.push(cur)
     }
     cur = null
@@ -264,21 +272,31 @@ function escapeRegex(s) {
  * - 过短关键词（<2 字符）视为噪音，不参与匹配
  * - 非 ASCII（中文等）用子串匹配
  * - ASCII 关键词用词边界匹配，避免子串误命中（如 "DB" 不命中 "dashboard"）
+ * 词边界口径（2026-11-02-knowledge-rank-denoise FR-02）：`_` 是词字符、`-` 是边界——
+ * node 不命中 node_modules，但 worktree 仍命中 kebab-case 变更名（2026-05-29-worktree-*）。
+ * 导出供评测适配层（eval/knowledge）复用同一判定——零行为变化。
  */
-function keywordMatchesContext(keyword, contextLower) {
+export function keywordMatchesContext(keyword, contextLower) {
   const kw = keyword.toLowerCase().trim()
   if (kw.length < 2) return false
   if (/[^\x00-\x7f]/.test(kw)) return contextLower.includes(kw)
-  return new RegExp(`(^|[^a-z0-9])${escapeRegex(kw)}([^a-z0-9]|$)`).test(contextLower)
+  return new RegExp(`(^|[^a-z0-9_])${escapeRegex(kw)}([^a-z0-9_]|$)`).test(contextLower)
 }
 
 /** 查询词片抽取：CJK 连续段 bigram ＋ ≥4 字符 ASCII 词（小写；短词与标点数字不参与；
- * 纯 ASCII 查询不产词片——中文知识库，英文查询维持既有零命中行为）。 */
-function queryShingles(taskContext) {
+ *  纯 ASCII 查询不产词片——中文知识库，英文查询维持既有零命中行为）。
+ *  snake/kebab 复合词保留整词并额外产出 ≥4 字符拆分片段（FR-02：查询 worktree_apply 时
+ *  worktree、apply 仍可命中正文只写 worktree 的条目）。导出供评测与单测（零行为变化）。 */
+export function queryShingles(taskContext) {
   const raw = String(taskContext || '')
   const shingles = new Set()
   if (/[\u4e00-\u9fff]/.test(raw)) {
-    for (const w of raw.toLowerCase().match(/[a-z][a-z0-9-]{3,}/g) || []) shingles.add(w)
+    for (const w of raw.toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) || []) {
+      shingles.add(w)
+      if (/[_-]/.test(w)) {
+        for (const part of w.split(/[_-]/)) if (part.length >= 4) shingles.add(part)
+      }
+    }
   }
   for (const seg of raw.match(/[\u4e00-\u9fff]+/g) || []) {
     for (let i = 0; i < seg.length - 1; i++) shingles.add(seg.slice(i, i + 2))
@@ -286,10 +304,11 @@ function queryShingles(taskContext) {
   return [...shingles]
 }
 
-/** ASCII 词片词边界命中（CJK 词片 includes 即可）；转义防正则注入。 */
+/** ASCII 词片词边界命中（CJK 词片 includes 即可）；转义防正则注入。
+ *  边界口径与 keywordMatchesContext 统一：`_` 词字符、`-` 边界（FR-02）。 */
 function asciiWordHit(sh, text) {
   if (!/^[a-z]/.test(sh)) return text.includes(sh)
-  return new RegExp(`(^|[^a-z0-9-])${sh.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')}([^a-z0-9-]|$)`, 'i').test(text)
+  return new RegExp(`(^|[^a-z0-9_])${sh.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z0-9_]|$)`, 'i').test(text)
 }
 
 /** 停车场文件（未归类 unmapped 域——decisions 与 fr 两面）：检索核心零返回，文件本身
@@ -302,6 +321,44 @@ export function isParkingFile(file) {
   return PARKING_FILES.has(String(file || '').replace(/\\/g, '/'))
 }
 
+/** 已修复条目显式词（FR-03，2026-11-02-knowledge-rank-denoise）：只认 INDEX display/anchor
+ *  的显式词，不读正文 heading（锚点→heading 归一脆弱）；绿色标记不作唯一键（平台实测
+ *  6 条绿色非词条目中 4 条是现行事实/债务，误杀代价高于漏 2 条已解决项）。 */
+const RESOLVED_WORDS = /已修复|已解决|已退役/
+
+/** 锚点/标题容错归一（坑 knowledge-hits-anchor-drift T4）：锚点三代规则并存（CLI slug /
+ *  INDEX 手写 / 平台 slugify_anchor）对 emoji 前缀、点号、斜杠、首尾中划线的处理互不一致
+ *  ——归一到「仅字母数字 + 小写」后比对，三代产物归一相等；截断（60 字符）由调用方前缀
+ *  容忍处理。单一源：knowledge 命令校验与图谱 section 匹配（2026-11-02-scope-recall）共用。 */
+export function normalizeAnchorForCompare(s) {
+  return String(s || '').replace(/[^\p{L}\p{N}]+/gu, '').toLowerCase()
+}
+
+/** 条目是否「已知问题-已修复」类（默认注入/检索排除；--include-resolved 才返回）。
+ *  双源判定（2026-11-03 接线）：① INDEX display/anchor 标题词（既有——覆盖未迁移到状态行格式的条目）
+ *  ② 目标文件正文状态行（`- 状态：已修复/已解决/已退役`——4C 落盘后主判据）。任一命中即 resolved。 */
+function isResolvedRoute(entry, knowledgeRoot) {
+  const file = String(entry.file || '').replace(/\\/g, '/')
+  const isKnownIssues = entry.category === 'Known Issues' || /(^|\/)known-issues\.md$/.test(file)
+  if (!isKnownIssues) return false
+  if (RESOLVED_WORDS.test(`${entry.display || ''} ${entry.anchor || ''}`)) return true
+  // 正文状态行判据：读目标文件，按 anchor 匹配 heading 后查段内状态行
+  if (knowledgeRoot && entry.anchor) {
+    try {
+      const content = readFileSync(join(knowledgeRoot, file), 'utf8')
+      const key = normalizeAnchorForCompare(entry.anchor)
+      const blocks = content.replace(/\r\n?/g, '\n').split(/^## /m).slice(1)
+      for (const b of blocks) {
+        const hn = normalizeAnchorForCompare(b.split('\n')[0])
+        if (hn === key || (hn.length >= 6 && key.length >= 6 && (hn.startsWith(key) || key.startsWith(hn)))) {
+          return /^\s*-\s*状态[：:]\s*(已修复|已解决|已退役)/m.test(b)
+        }
+      }
+    } catch { /* 文件不可读回退标题词 */ }
+  }
+  return false
+}
+
 /**
  * 零命中查询侧词片回退（2026-09-29-decision-route-vocab）：路由行零命中时，只测「查询自己的
  * 词片」——逐 decisions 域文件数词片在条目文本（标题∪理由）的出现次数，落在「跨条目复现但
@@ -380,7 +437,7 @@ export function fallbackByQueryShingles(indexDir, taskContext) {
  *   命中的 Decisions 路由行所指向 decisions/<域>.md 内的全部 D-xxx@vN 条目，rejected 优先排序；
  *   无 decisions 库 / 路由行未命中 → decisionHits: []（其余字段行为与现状一致）。
  */
-export function matchByRouting(indexDir, taskContext) {
+export function matchByRouting(indexDir, taskContext, opts = {}) {
   const indexPath = join(indexDir, 'INDEX.md')
 
   // INDEX.md 不存在
@@ -413,19 +470,59 @@ export function matchByRouting(indexDir, taskContext) {
   // 只命中停车场行 → 按零命中处理（hybrid 链继续走向量/图/词片层），json.parkingFiltered
   // 披露被滤文件供 search 面提示人工直查（可见性不因去噪丢失）。
   const parkingFiltered = [...new Set(matchedRaw.filter((e) => isParkingFile(e.file)).map((e) => e.file))]
-  const matched = matchedRaw.filter((e) => !isParkingFile(e.file))
+  const parkingExcluded = matchedRaw.filter((e) => !isParkingFile(e.file))
+  // 已修复过滤（FR-03，2026-11-02-knowledge-rank-denoise）：known-issues 显式词条目默认排除，
+  // includeResolved 才返回；json.resolvedFiltered 披露（仿 parkingFiltered）。
+  const resolvedFiltered = opts.includeResolved ? [] : parkingExcluded.filter((e) => isResolvedRoute(e, indexDir))
+  const resolvedFiles = [...new Set(resolvedFiltered.map((e) => e.file))]
+  const resolvedNote = resolvedFiles.length > 0
+    ? { resolvedFiltered: resolvedFiles, resolvedNote: '已修复条目已过滤——需查看加 --include-resolved' }
+    : {}
+  const matchedAll = parkingExcluded.filter((e) => !resolvedFiltered.includes(e))
+
+  // 路由行分离（FR-04，2026-11-02-knowledge-rank-denoise）：fr/decisions 路由行不进面向人的
+  // entries（各有 decisionHits / readActiveFrDigest 专用通道），改走条件式 routeHits——
+  // 消费面据此出指针行，避免静默丢失 implemented 决策与 FR 的可见性；顶层键仅在非空时出现
+  // （无路由行命中的场景保持旧四键+decisionHits 结构不变）。
+  const isRouteRow = (e) => isDecisionRoute(e) || /^fr\//.test(String(e.file || '').replace(/\\/g, '/'))
+  const humanEntries = matchedAll.filter((e) => !isRouteRow(e))
+  const routeHits = matchedAll.filter(isRouteRow)
+
+  // DF 相关度排序（FR-05，2026-11-02-knowledge-rank-denoise）：分母 = entries 可展示语料
+  // （排除 fr/decisions 路由行、停车场、已修复条目）；命中数优先 → Σ(1/DF) 破平 → INDEX 行序兜底。
+  // 泛词（出现在大量路由行的流程词）权重被压缩，长尾具体词上浮；同分顺序确定（重复运行一致）。
+  const humanCorpus = allEntries.filter((e) => !isRouteRow(e) && !isParkingFile(e.file) && !isResolvedRoute(e, indexDir))
+  const dfMap = new Map()
+  for (const e of humanCorpus) {
+    const seenKw = new Set()
+    for (const kw of e.keywords) {
+      const k = String(kw).toLowerCase()
+      if (seenKw.has(k)) continue
+      seenKw.add(k)
+      dfMap.set(k, (dfMap.get(k) || 0) + 1)
+    }
+  }
+  const scoredHuman = humanEntries.map((e, i) => {
+    const matchedKws = [...new Set(e.keywords.map((k) => String(k).toLowerCase()))]
+      .filter((k) => keywordMatchesContext(k, contextLower))
+    const hits = matchedKws.length
+    const rarity = matchedKws.reduce((s, k) => s + 1 / Math.max(1, dfMap.get(k) || 1), 0)
+    return { e, i, hits, rarity }
+  })
+  scoredHuman.sort((a, b) => (b.hits - a.hits) || (b.rarity - a.rarity) || (a.i - b.i))
+  const rankedHuman = scoredHuman.map((x) => x.e)
 
-  if (matched.length === 0) {
+  if (rankedHuman.length === 0 && routeHits.length === 0) {
     return {
       matched: false,
       entries: [],
       report: 'Status: no matches',
-      json: { matched: false, entry_count: 0, entries: [], ...(parkingFiltered.length > 0 ? { parkingFiltered } : {}) },
+      json: { matched: false, entry_count: 0, entries: [], ...(parkingFiltered.length > 0 ? { parkingFiltered } : {}), ...resolvedNote },
       decisionHits: []
     }
   }
 
-  const sources = matched.map(e => {
+  const sources = [...rankedHuman, ...routeHits].map(e => {
     const base = e.anchor ? `${e.file}#${e.anchor}` : e.file
     return ` - ${base}`
   }).join('\n')
@@ -434,20 +531,25 @@ export function matchByRouting(indexDir, taskContext) {
     'Knowledge Context',
     '─────────────────',
     `Status: matched`,
-    `Entries: ${matched.length}`,
+    `Entries: ${rankedHuman.length}`,
+    ...(routeHits.length > 0 ? [`Route hits: ${routeHits.length}`] : []),
     'Sources:',
     sources
   ].join('\n')
 
   const json = {
     matched: true,
-    entry_count: matched.length,
-    entries: matched.map(e => ({
+    entry_count: rankedHuman.length,
+    entries: rankedHuman.map(e => ({
       file: e.file,
       anchor: e.anchor,
       keywords: e.keywords,
       category: e.category
-    }))
+    })),
+    ...(routeHits.length > 0 ? {
+      routeHits: routeHits.map(e => ({ file: e.file, anchor: e.anchor, keywords: e.keywords, category: e.category })),
+    } : {}),
+    ...resolvedNote
   }
 
   // decisionHits（task-04）：任务上下文命中的 Decisions 路由行 → 解析其指向的
@@ -457,7 +559,7 @@ export function matchByRouting(indexDir, taskContext) {
   // D-001@v1 排 148/188 位）。重叠判据复用 fr-index frTitleOverlap（字符 bigram，
   // 封闭面非语义判定）。
   // 不引入新顶层 hits 字段，不改 matched/entries/report/json 四个既有键。
-  const decisionRoutes = matched.filter(isDecisionRoute)
+  const decisionRoutes = routeHits.filter(isDecisionRoute)
   const allDecisionHits = decisionRoutes.length > 0 ? parseDecisionEntries(indexDir, decisionRoutes) : []
   // 评分文本 = id＋标题；评分前剥除数字与标点（2026-09-28-knowledge-score-denoise：{DECISION_HITS}
   // 场景 taskContext=ASCII 变更名，日期「2026-09-28」与 id「D-009@v1」共享 -0/09 数字 bigram 即
@@ -473,7 +575,14 @@ export function matchByRouting(indexDir, taskContext) {
     ...allDecisionHits.filter((h) => h.status !== 'rejected' && !h.deathPath).sort(byOverlapDesc),
   ].map((h) => ({ ...h, score: relScore(h) }))
 
-  return { matched: true, entries: matched, report, json, decisionHits }
+  return {
+    matched: true,
+    entries: rankedHuman,
+    ...(routeHits.length > 0 ? { routeHits } : {}),
+    report,
+    json,
+    decisionHits,
+  }
 }
 
 /**
@@ -481,8 +590,8 @@ export function matchByRouting(indexDir, taskContext) {
  * 异步三层入口（平台向量优先于本地回退）见 knowledge-vector.js matchKnowledgeHybrid
  * （2026-09-29-knowledge-vector-recall）——同步调用方与既有测试全部走本函数。
  */
-export function matchKnowledge(indexDir, taskContext) {
-  const r = matchByRouting(indexDir, taskContext)
+export function matchKnowledge(indexDir, taskContext, opts = {}) {
+  const r = matchByRouting(indexDir, taskContext, opts)
   if (r.matched) return r
   const fb = fallbackByQueryShingles(indexDir, taskContext)
   return fb || r

package/src/knowledge-stats.js

@@ -4,6 +4,9 @@
  * 职责：聚合 .runtime/knowledge-hits.jsonl 遥测事件流（task-01 KnowledgeHitsAPI 写入：
  * task-04 注入点写 type:inject、task-02 classify 写 type:classify），输出近 N 天命中矩阵
  * （文件 × 次数 × 最近命中时间）与从未命中清单（对照 INDEX.md 全集标注疑似死重）。
+ * 注（2026-11-02-knowledge-engine-tail FR-02）：scope 展示面走独立字段 `scopeMatchedFiles`
+ * （top3+3 展示子集）——命中矩阵/neverHit 只按 `matchedFiles`（查询通道）统计，scope 通道
+ * 不参与 neverHit 判定（防同一决策域文件反复计命中原决定死重）。
  * 纯只读：不写 hits/INDEX/知识文件任何输入；死重清单只报告，不自动删除/合并（非目标）。
  *
  * 计数口径：

package/src/knowledge-vector.js

@@ -236,6 +236,24 @@ export function buildResultFromPlatform(indexDir, pvResults) {
   }
 }
 
+/**
+ * base（路由/向量结果）+ scopeFiles → 融合结果（2026-11-02-knowledge-engine-tail FR-01）。
+ * 路由命中与向量命中两条路径共用本实现（消除「同一 early-return 病只修一半」）：
+ * scopeFiles 经 graphPathCandidates 规整；scope 构建/遍历失败返回 base 原对象（fail-soft）。
+ */
+async function fuseBaseWithScope(base, indexDir, scopeFiles) {
+  if (!base || !base.matched) return base
+  const raw = Array.isArray(scopeFiles) ? scopeFiles.filter(Boolean) : []
+  if (raw.length === 0) return base
+  try {
+    const { graphPathCandidates, getKnowledgeGraph, scopeRecall, fuseScopeRecall } = await import('./knowledge-graph.js')
+    const files = graphPathCandidates(raw)
+    if (files.length === 0) return base
+    const specRoot = String(indexDir).replace(/[\\/]knowledge[\\/]?$/, '')
+    return fuseScopeRecall(base, scopeRecall(getKnowledgeGraph(specRoot), files)) || base
+  } catch { return base }
+}
+
 /**
  * 异步三层检索入口（四消费方使用：flow 注入段／complete 门／prompt {DECISION_HITS}／
  * knowledge search CLI）：路由 → 平台向量（已连接且开关开）→ scope 遍历 → 本地词片 → 空。
@@ -245,16 +263,23 @@ export function buildResultFromPlatform(indexDir, pvResults) {
  * 缺省/空数组 → 遍历层整体跳过，行为与不携带该参数的旧行为逐字段一致（回归钉死）。
  */
 export async function matchKnowledgeHybrid(indexDir, taskContext, opts = {}) {
-  const r = matchByRouting(indexDir, taskContext)
-  if (r.matched) return r
+  const r = matchByRouting(indexDir, taskContext, opts)
+  const scopeFiles = Array.isArray(opts.scopeFiles) ? opts.scopeFiles.filter(Boolean) : []
+  if (r.matched) {
+    // 融合（2026-11-02-knowledge-fusion）：路由命中后仍跑 scope——热文件触达的 rejected/手工条目
+    // 原先被 early-return 永久遮住。只追加 scopeDecisionHits/scopeEntries（不重排路由结果）；
+    // scope 构建失败原样返回路由结果；仍不跑平台向量（路由命中零网络）。
+    return fuseBaseWithScope(r, indexDir, scopeFiles)
+  }
   const cwd = opts.cwd || dirname(dirname(String(indexDir)))
   if (vectorEnabled(cwd)) {
     const pv = await platformVectorRecall({ cwd, query: taskContext, limit: opts.limit || 10 })
     const built = pv ? buildResultFromPlatform(indexDir, pv.results) : null
-    if (built) return built
+    // 向量命中路径同样融合（FR-01 对称性）：平台向量自动探测开启、词面弱、路由零命中时，
+    // scope 增量不应因向量 early-return 丢失。
+    if (built) return fuseBaseWithScope(built, indexDir, scopeFiles)
   }
   // scope 遍历层（第三层）：只在 scope 非空且向量零命中后接管；fail-soft（图构建异常静默降级词片）
-  const scopeFiles = Array.isArray(opts.scopeFiles) ? opts.scopeFiles.filter(Boolean) : []
   if (scopeFiles.length > 0) {
     try {
       const { buildKnowledgeGraph, scopeRecall, buildScopeRecallResult } = await import('./knowledge-graph.js')

package/src/redomain-unmapped.js

@@ -10,9 +10,10 @@
  * 目标域同 id 同变更冲突跳过、幂等；INDEX 路由行随原语内 sync 维护（FR-02 泛词已退役）。
  * 只动 knowledge 活库，不回写归档件（D-unmapped-152 死路：归档是冻结审计面）。
  */
-import { existsSync, readFileSync } from 'fs'
+import { existsSync, readFileSync, unlinkSync } from 'fs'
 import { join } from 'path'
-import { splitKnowledgeSections, discoverModuleIndex } from './decision-distill.js'
+import { splitKnowledgeSections, discoverModuleIndex, joinKnowledgeFile, syncIndexRoutingLines, DECISIONS_ROUTE_STRIP_TOKENS, FR_ROUTE_STRIP_TOKENS } from './decision-distill.js'
+import { writeAtomicSync } from './fs-atomic.js'
 import { matchedModuleIds, frCoverageFiles, FR_SECTION_RE } from './fr-index.js'
 import { anchorFilePaths } from './knowledge-match.js'
 import { redomainDecisionEntries, sectionMeta } from './decision-redomain.js'
@@ -181,12 +182,46 @@ export async function cmdRedomainUnmapped(dir, args, opts = {}) {
     ? (args[args.indexOf('--face') + 1] === 'decisions' ? 'decisions' : args[args.indexOf('--face') + 1] === 'fr' ? 'fr' : 'all')
     : 'all'
   const apply = args.includes('--apply')
+  const mapIdx = args.indexOf('--map')
+  const mapFile = mapIdx >= 0 ? args[mapIdx + 1] : null
   const emit = (ok, data, error) => console.log(JSON.stringify({ ok, ...data, ...(error ? { error } : {}) }, null, 2))
 
+  // --map 缺值显式拒绝（评审 P2：静默回落启发式通道 = 显式契约被切到投票且带写盘）
+  if (mapIdx >= 0 && (!mapFile || mapFile.startsWith('--'))) {
+    emit(false, {}, { code: 'map_value_required', usage: '--map <file.json>（[{id, domain}]，domain 可为 __prune__）' })
+    return
+  }
+
   if (!existsSync(join(knowledgeRoot, 'INDEX.md'))) {
     emit(false, {}, { code: 'knowledge_dir_missing', path: knowledgeRoot })
     return
   }
+  // --map 显式映射模式（2026-11-02-knowledge-redomain-map FR-01）：旁路投票；apply fail-fast
+  if (mapFile) {
+    let map = null
+    try { map = JSON.parse(readFileSync(mapFile, 'utf8')) } catch (e) {
+      emit(false, {}, { code: 'map_file_invalid', file: mapFile, detail: e && e.message })
+      return
+    }
+    if (!Array.isArray(map) || map.some((e) => !e || typeof e.id !== 'string' || typeof e.domain !== 'string')) {
+      emit(false, {}, { code: 'map_entries_invalid', expected: '[{id, domain}]' })
+      return
+    }
+    const faces = face === 'all' ? ['decisions', 'fr'] : [face]
+    try {
+      if (apply) {
+        const results = faces.map((f) => applyFromMap({ knowledgeRoot, archiveRoot, face: f, map }))
+        emit(true, { mode: 'apply-map', face, results })
+        return
+      }
+      const plans = faces.map((f) => planFromMap({ knowledgeRoot, face: f, map }))
+      emit(true, { mode: 'dry-run-map', face, plans })
+      return
+    } catch (e) {
+      emit(false, {}, { code: 'map_apply_failed', detail: e && e.message ? e.message : String(e) })
+      return
+    }
+  }
   if (apply) {
     const faces = face === 'all' ? ['decisions', 'fr'] : [face]
     const { results, plan } = applyUnmappedRedomain({ knowledgeRoot, archiveRoot, faces })
@@ -202,3 +237,129 @@ export async function cmdRedomainUnmapped(dir, args, opts = {}) {
   const plan = planUnmappedRedomain({ knowledgeRoot, archiveRoot })
   emit(true, { mode: 'dry-run', face, decisions: plan.decisions, fr: plan.fr })
 }
+
+// ═══ 2026-11-02-knowledge-redomain-map：--map 显式映射模式（FR-01）═══
+// 显式契约 [{id, domain}]（domain 可为 __prune__ 删段）——旁路启发式投票；apply fail-fast
+// （显式契约不容半途容错）；守恒/幂等断言以 apply 时刻文件为准；supersedes 留源作警告。
+
+export const PRUNE_DOMAIN = '__prune__'
+
+/** unmapped 文件段解析（face 决定契约）。 */
+function parseUnmappedFace(knowledgeRoot, face) {
+  const fromPath = face === 'fr' ? join(knowledgeRoot, 'fr', 'unmapped.md') : join(knowledgeRoot, 'decisions', 'unmapped.md')
+  if (!existsSync(fromPath)) return null
+  const parsed = face === 'fr'
+    ? splitKnowledgeSections(readFileSync(fromPath, 'utf8'), { sectionRegex: FR_SECTION_RE, buildId: (n) => n })
+    : splitKnowledgeSections(readFileSync(fromPath, 'utf8'))
+  const metas = parsed.sections.map((s) => (face === 'fr' ? frMeta(s) : sectionMeta(s))).filter(Boolean)
+  return { fromPath, parsed, metas, total: metas.length }
+}
+
+function frMeta(s) {
+  const h = FR_HEADER_RE.exec(s.lines[0] || '')
+  return h ? { id: h[1], title: (h[2] || '').trim() } : null
+}
+
+/** 显式映射 → 计划：迁移 groups + prunes + unknownIds（部分未知=报错；全部未知=已全部处理）。 */
+export function planFromMap({ knowledgeRoot, face, map }) {
+  const src = parseUnmappedFace(knowledgeRoot, face)
+  if (!src) throw new Error(`源文件不存在（face=${face}: unmapped.md）`)
+  const byId = new Map(src.metas.map((m) => [m.id, m]))
+  const unknownIds = map.map((e) => e.id).filter((id) => !byId.has(id))
+  const groups = new Map()
+  const prunes = []
+  for (const e of map) {
+    if (!byId.has(e.id)) continue
+    if (e.domain === PRUNE_DOMAIN) { prunes.push(e.id); continue }
+    if (!groups.has(e.domain)) groups.set(e.domain, [])
+    groups.get(e.domain).push(e.id)
+  }
+  return {
+    face,
+    total: src.total,
+    groups: [...groups.entries()].map(([domain, ids]) => ({ domain, ids })).sort((a, b) => a.domain.localeCompare(b.domain)),
+    prunes,
+    unknownIds,
+    alreadyApplied: unknownIds.length === map.length && map.length > 0,
+  }
+}
+
+/** __prune__ 原语：从源文件删段——精确计数断言、裁空删文件 + INDEX 同步（prune-only 也调）。 */
+export function pruneUnmappedEntries({ knowledgeRoot, face, anchors }) {
+  const src = parseUnmappedFace(knowledgeRoot, face)
+  if (!src) throw new Error(`源文件不存在（face=${face}: unmapped.md）`)
+  const anchorSet = new Set(anchors)
+  const staying = []
+  const pruned = []
+  for (const s of src.parsed.sections) {
+    const meta = face === 'fr' ? frMeta(s) : sectionMeta(s)
+    if (!meta) { staying.push(s); continue }
+    if (anchorSet.has(meta.id)) pruned.push(meta.id)
+    else staying.push(s)
+  }
+  if (pruned.length !== anchors.length) {
+    const got = new Set(pruned)
+    throw new Error(`prune 精确计数断言失败：未命中 ${anchors.filter((a) => !got.has(a)).join('、')}`)
+  }
+  const sourceDeleted = staying.length === 0
+  if (sourceDeleted) unlinkSync(src.fromPath)
+  else writeAtomicSync(src.fromPath, joinKnowledgeFile(src.parsed.preamble, staying))
+  try {
+    // fr 面必须传 FR_ROUTE_STRIP_TOKENS（评审 P2：传 {} 落默认 Decisions 段——fr 裁空后 INDEX 残留幽灵路由行）
+    syncIndexRoutingLines(knowledgeRoot, face === 'fr' ? { stripTokens: FR_ROUTE_STRIP_TOKENS } : { stripTokens: DECISIONS_ROUTE_STRIP_TOKENS })
+  } catch { /* INDEX 缺席/同步失败不拦裁剪（幂等可重跑） */ }
+  return { pruned, sourceDeleted }
+}
+
+/** supersedes 留源警告：被处理段的 supersedes 引用（基号）与留守段 id 基号相同 → 警告。 */
+function supersedesLeftBehind(knowledgeRoot, face, processedIds) {
+  const src = parseUnmappedFace(knowledgeRoot, face)
+  if (!src) return []
+  const baseOf = (s) => String(s || '').replace(/@v\d+$/, '')
+  const processedBases = new Set(processedIds.map(baseOf))
+  const stayingBases = new Set(src.metas.map((m) => m.id).filter((id) => !processedBases.has(baseOf(id))).map(baseOf))
+  const warnings = []
+  for (const s of src.parsed.sections) {
+    const meta = face === 'fr' ? frMeta(s) : sectionMeta(s)
+    if (!meta || !processedBases.has(baseOf(meta.id))) continue
+    const sup = (s.lines.join('\n').match(/^supersedes[：:]\s*(\S+)/m) || [])[1]
+    if (sup && stayingBases.has(baseOf(sup))) warnings.push(`${meta.id} 的 supersedes 目标 ${sup} 留在源文件`)
+  }
+  return warnings
+}
+
+/**
+ * --map apply（fail-fast）：迁移组 + 裁剪顺序执行，任何失败整体上抛（已写部分靠幂等复跑收敛）。
+ * 守恒断言（apply 后重算段头 = 原段头 − moved − pruned）与幂等（全部已处理 → alreadyApplied）内嵌。
+ */
+export function applyFromMap({ knowledgeRoot, archiveRoot, face, map }) {
+  const plan = planFromMap({ knowledgeRoot, face, map })
+  if (plan.alreadyApplied) return { face, alreadyApplied: true, moved: 0, pruned: 0, conservation: 'ok', warnings: [] }
+  if (plan.unknownIds.length > 0) throw new Error(`映射表含源文件不存在的 id：${plan.unknownIds.join('、')}`)
+  const processed = [...plan.groups.flatMap((g) => g.ids), ...plan.prunes]
+  const warnings = supersedesLeftBehind(knowledgeRoot, face, processed)
+  let moved = 0
+  const movedByDomain = {}
+  for (const g of plan.groups) {
+    const res = face === 'fr'
+      ? redomainFrEntries({ knowledgeRoot, from: 'unmapped', to: g.domain, anchors: g.ids })
+      : redomainDecisionEntries({ knowledgeRoot, from: 'unmapped', to: g.domain, anchors: g.ids })
+    moved += res.moved.length
+    movedByDomain[g.domain] = res.moved.length
+    if (Array.isArray(res.skippedConflicts) && res.skippedConflicts.length > 0) {
+      warnings.push(`目标域 ${g.domain} 冲突跳过：${res.skippedConflicts.join('、')}`)
+    }
+  }
+  let pruned = 0
+  if (plan.prunes.length > 0) {
+    pruned = pruneUnmappedEntries({ knowledgeRoot, face, anchors: plan.prunes }).pruned.length
+  }
+  // 守恒断言：apply 后源段头 = 原 − moved − pruned（skippedConflicts 留守 → moved 不含）
+  const after = parseUnmappedFace(knowledgeRoot, face)
+  const afterTotal = after ? after.total : 0
+  const expected = plan.total - moved - pruned
+  if (afterTotal !== expected) {
+    throw new Error(`守恒断言失败：apply 后段头 ${afterTotal} ≠ 原段头 ${plan.total} − moved ${moved} − pruned ${pruned}`)
+  }
+  return { face, alreadyApplied: false, moved, movedByDomain, pruned, conservation: `ok（${plan.total} − ${moved} − ${pruned} = ${afterTotal}）`, warnings }
+}

package/src/run/complete.js

@@ -532,7 +532,10 @@ async function _completeStepInner(pm, progress, stageName, cwd, outputText, inpu
             : () => false
           const _echoHits = _hits.filter((h) => !_answered(h))
           const _entries = km.matched ? (km.entries || []) : []
-          if (_echoHits.length > 0 || _entries.length > 0) {
+          const _routeHits = km.matched ? (km.routeHits || []) : []
+          const _scopeHitsAll = km.matched ? (km.scopeDecisionHits || []) : []
+          const _scopeHits = _scopeHitsAll.filter((h) => h.deathPath || h.status === 'rejected').slice(0, 3)
+          if (_echoHits.length > 0 || _entries.length > 0 || _routeHits.length > 0 || _scopeHits.length > 0) {
             const { deathPathNote, decisionChangeQualifier } = await import('../knowledge-match.js')
             console.warn(`\n⚠️ [knowledge-gate] 方案/决策知识命中（设计时点防复潮提示，warn 不阻断）：`)
             for (const h of _echoHits.slice(0, 5)) {
@@ -546,7 +549,23 @@ async function _completeStepInner(pm, progress, stageName, cwd, outputText, inpu
               const _base = e.anchor ? `${e.file}#${e.anchor}` : e.file
               console.warn(`   - 知识条目 ${_base}${e.display ? `（${e.display}）` : ''}`)
             }
+            for (const e of _routeHits.slice(0, 3)) {
+              const _base = e.anchor ? `${e.file}#${e.anchor}` : e.file
+              console.warn(`   - 路由命中 ${_base}（按需 Read）`)
+            }
+            // 融合增量（2026-11-02-knowledge-fusion FR-03）：scope 否决独立小节（≤3，已回应过滤同源）
+            for (const h of _scopeHits.filter((h) => !_answered(h))) {
+              const _via = h.via === 'two-hop' ? '两跳' : '直连'
+              console.warn(`   - 触达文件关联否决 ${h.id} ${h.title}（${h.file}｜${decisionChangeQualifier(h.change)}｜${_via}）${h.status === 'rejected' ? `否决理由：${h.reason || '（未记录）'}` : `⚰️死路：${deathPathNote(h.reason)}`}`)
+            }
             console.warn(`   须在对应决策的 evidence 回应或说明不复潮（v1 提示级；local.yaml commands.knowledge-gate: false 可关本回显）`)
+            // 用户纠正转写自检（2026-11-02-constraint-mechanize FR-02）：本变更 decisions.md 有
+            // 「用户原话保留」事故类条目时提示转写层——点火器转写纪律（用户纠正是生成时刻约束力
+            // 最强的力量，跨会话零存续，最强用法是当场转写进测试/门/接口/规约）
+            const _hasUserCorrection = _dm && /用户原话保留|落地层[：:]/.test(_dm)
+            if (_hasUserCorrection) {
+              console.warn(`   🔥 用户纠正转写自检：本变更记录了用户纠正——原话转写进了哪一层（测试/门/接口/规约）？未转写则在对应决策补「落地层：」字段（D-002 先例）`)
+            }
           }
         }
       }

package/src/run/gate-snapshot.js

@@ -999,7 +999,9 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
       }
     } catch { /* 文档复制失败不连坐快照（test_strategy 降级 module 集仍可跑） */ }
 
-    return { ...snap, changeFileCount: changeFiles.length, sourceRoot }
+    // changeFiles 透出（2026-10-29-open-metrics-gate task-03）：厚道 verify 质量扫描的 metrics
+    // 增量门注入（SILLYSPEC_CHANGE_FILES）需要本快照自算的变更文件集——additive，既有消费方零感知。
+    return { ...snap, changeFileCount: changeFiles.length, changeFiles, sourceRoot }
   } catch (e) {
     // 任一链路异常 → 回退主仓现行为。异常细节不再静默（坑 snapshot-fallback-reason-blind）：
     // failRef 带原因 + warn 落日志，排查不再靠 stdout 考古。