sillyspec 3.33.8 → 3.34.0

package/src/run/prompt.js

@@ -96,9 +96,9 @@ import { REVIEW_SCHEMA_VERSION, isValidExecuteRunId } from '../task-review.js'
 // 静态 import 不引入环（stages/* 反向引用本文件会撞 index.js 顶层 stageRegistry TDZ——见
 // buildKnowledgeInjection docstring）。
 import { matchKnowledge } from '../knowledge-match.js'
-import { matchQuicklogContext } from '../knowledge-quicklog.js'
 import { appendKnowledgeHit } from '../knowledge-hits.js'
-import { readActiveFrDigest } from '../fr-index.js'
+import { readActiveFrDigest, deliverableFilesFromDesignText } from '../fr-index.js'
+import { matchKnowledgeWithScope, graphPathCandidates, scopeTelemetryRefs } from '../knowledge-graph.js'
 // 前置失败清单 validator 面（2026-09-18-preflight-slimming task-01）：design-facts /
 // stage-contract-engine 均为 src/ 叶子方向（不反向 import 本模块），静态 import 不引入环。
 import { validateDesignFileList } from '../design-facts.js'
@@ -524,33 +524,49 @@ function pickTopKnowledgeEntries(entries, maxFiles) {
   return picked
 }
 
-/** 命中正文段渲染（段头 + Status/Sources 命中报告语义 + top-3 文件截断正文）。 */
+/** 命中正文段渲染（段头 + Status/Sources 命中报告语义 + top-3 文件截断正文）。
+ *  路由行分离（FR-04，2026-11-02-knowledge-rank-denoise）：entries 仅手工条目注入正文；
+ *  routeHits（fr/decisions 路由行）以指针行呈现，保 implemented 决策可见性；空 entries 且
+ *  无 routeHits 时返回空串（不出段头空段）。 */
 function renderKnowledgeInjectSection(knowledgeResult, { knowledgeDir, maxFiles, maxLines }) {
   const ref = e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)
+  const humanEntries = knowledgeResult.entries || []
+  const routeHits = knowledgeResult.routeHits || []
+  const scopeEntriesPreview = knowledgeResult.scopeEntries || []
+  if (humanEntries.length === 0 && routeHits.length === 0 && scopeEntriesPreview.length === 0) return ''
   const lines = []
   lines.push(`📚 命中知识（CLI 按任务描述机械匹配，top-${maxFiles}）`)
-  lines.push(`Status: matched | Entries: ${knowledgeResult.entries.length} | Sources:`)
-  for (const e of knowledgeResult.entries) lines.push(` - ${ref(e)}`)
-  lines.push(`（命中清单如上；正文按 INDEX 行序注入前 ${maxFiles} 个不同文件，单文件首 ${maxLines} 行截断——未注入条目需要时按 Sources 路径自行读取）`)
-  for (const e of pickTopKnowledgeEntries(knowledgeResult.entries, maxFiles)) {
-    lines.push('')
-    lines.push(`── ${ref(e)}${e.display ? `（${e.display}）` : ''} ──`)
-    let body = ''
-    try {
-      // CRLF/CR 归一（Windows 知识文件 + 行数截断按 \n 切分）
-      body = readFileSync(join(knowledgeDir, e.file), 'utf8').replace(/\r\n?/g, '\n')
-    } catch (err) {
-      lines.push(`（文件不可读：${err && err.message ? err.message : err}）`)
-      continue
-    }
-    const bodyLines = body.split('\n')
-    if (bodyLines.length > maxLines) {
-      lines.push(bodyLines.slice(0, maxLines).join('\n'))
-      lines.push('…（截断）')
-    } else {
-      lines.push(body.replace(/\n+$/, ''))
+  if (humanEntries.length > 0) {
+    lines.push(`Status: matched | Entries: ${humanEntries.length} | Sources:`)
+    for (const e of humanEntries) lines.push(` - ${ref(e)}`)
+    lines.push(`（命中清单如上；正文按相关度注入前 ${maxFiles} 个不同文件，单文件首 ${maxLines} 行截断——未注入条目需要时按 Sources 路径自行读取）`)
+    for (const e of pickTopKnowledgeEntries(humanEntries, maxFiles)) {
+      lines.push('')
+      lines.push(`── ${ref(e)}${e.display ? `（${e.display}）` : ''} ──`)
+      let body = ''
+      try {
+        // CRLF/CR 归一（Windows 知识文件 + 行数截断按 \n 切分）
+        body = readFileSync(join(knowledgeDir, e.file), 'utf8').replace(/\r\n?/g, '\n')
+      } catch (err) {
+        lines.push(`（文件不可读：${err && err.message ? err.message : err}）`)
+        continue
+      }
+      const bodyLines = body.split('\n')
+      if (bodyLines.length > maxLines) {
+        lines.push(bodyLines.slice(0, maxLines).join('\n'))
+        lines.push('…（截断）')
+      } else {
+        lines.push(body.replace(/\n+$/, ''))
+      }
     }
   }
+  if (routeHits.length > 0) {
+    lines.push(`🧭 决策/FR 路由命中（专用通道，按需 Read）：${routeHits.slice(0, 3).map(ref).join('；')}`)
+  }
+  const scopeEntries = knowledgeResult.scopeEntries || []
+  if (scopeEntries.length > 0) {
+    lines.push(`📚 触达文件关联手工条目（scope，按需 Read）：${scopeEntries.slice(0, 3).map(ref).join('；')}`)
+  }
   return lines.join('\n')
 }
 
@@ -567,30 +583,28 @@ function renderKnowledgeInjectSection(knowledgeResult, { knowledgeDir, maxFiles,
  *   report/json：matchKnowledge 原样透传（execute 调用方沿用旧 report.json 落盘与未命中替换口径）。
  *   遥测 append 单独 fail-soft（hits 写失败不影响注入本体）；匹配/渲染异常向上抛由调用方降级。
  */
-export function buildKnowledgeInjection({ knowledgeDir, runtimeDir, change, query, maxFiles = KNOWLEDGE_INJECT_MAX_FILES, maxLines = KNOWLEDGE_INJECT_MAX_LINES } = {}) {
-  const knowledgeResult = matchKnowledge(knowledgeDir, String(query || ''))
-  // quicklog 检索面（知识可见性导线）：与 INDEX 知识面独立——INDEX 未命中时 quicklog 照常
-  // 注入（两 retrieval 面互为补充）；fail-open（无 quicklog/异常 → 空 hits 零注入）。
-  // specBase 由 knowledgeDir 上溯（两个注入点传的都是 <specBase>/knowledge）。
-  const quick = knowledgeDir
-    ? matchQuicklogContext(dirname(knowledgeDir), String(query || ''))
-    : { hits: [], report: '' }
-  if (!knowledgeResult.matched && quick.hits.length === 0) {
+export function buildKnowledgeInjection({ knowledgeDir, runtimeDir, change, query, scopeFiles = [], maxFiles = KNOWLEDGE_INJECT_MAX_FILES, maxLines = KNOWLEDGE_INJECT_MAX_LINES } = {}) {
+  // 融合（2026-11-02-knowledge-fusion）：同步入口 = matchKnowledge（路由/词片）+ scope 融合；
+  // scopeFiles 为机器键（design 交付清单/quick allowedFiles），键规整在 graphPathCandidates 内做
+  const knowledgeResult = matchKnowledgeWithScope(knowledgeDir, String(query || ''), { scopeFiles })
+  if (!knowledgeResult.matched) {
     return { matched: false, section: '', report: knowledgeResult.report, json: knowledgeResult.json }
   }
   const kSection = knowledgeResult.matched ? renderKnowledgeInjectSection(knowledgeResult, { knowledgeDir, maxFiles, maxLines }) : ''
-  const qSection = quick.report || ''
-  const section = [kSection, qSection].filter(Boolean).join('\n\n')
+  const section = kSection
+  const routeFiles = (knowledgeResult.routeHits || []).map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file))
+  const scopeMatchedFiles = scopeTelemetryRefs(knowledgeResult, { includeRejected: false })
   try {
     appendKnowledgeHit(runtimeDir, {
       type: 'inject',
       change: change || '',
       query: String(query || ''),
-      matchedFiles: knowledgeResult.entries.map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)),
-      quicklogIds: quick.hits.map(h => h.qlId),
+      matchedFiles: [...knowledgeResult.entries.map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)), ...routeFiles],
+      // scope 展示面独立字段（2026-11-02-knowledge-engine-tail FR-02）：不并入 matchedFiles
+      ...(scopeMatchedFiles.length > 0 ? { scopeMatchedFiles } : {}),
     })
   } catch { /* 遥测 fail-soft（R-04）：hits 落盘失败不阻断注入本体 */ }
-  return { matched: true, section, report: knowledgeResult.report, json: knowledgeResult.json, quickHits: quick.hits }
+  return { matched: true, section, report: knowledgeResult.report, json: knowledgeResult.json}
 }
 
 // parseModuleMapSimple 复用 modules.js 的 canonical 实现（合并历史 copy-paste 副本，2026-08-07；
@@ -1492,11 +1506,20 @@ async function outputStepImpl(stageName, stepIndex, steps, cwd, changeName, dbPr
         } catch {}
       }
       const runtimeDir = join(effectiveSpecBase, '.runtime')
+      // scope 键（FR-04）：execute step 用 design 交付清单（机器键，图内精确路径由 graphPathCandidates 规整）
+      let scopeFiles = []
+      if (changeName) {
+        try {
+          const designText = readFileSync(join(effectiveSpecBase, 'changes', changeName, 'design.md'), 'utf8')
+          scopeFiles = graphPathCandidates(deliverableFilesFromDesignText(designText))
+        } catch { /* 无 design.md = 无键（不编造） */ }
+      }
       const knowledgeInjection = buildKnowledgeInjection({
         knowledgeDir,
         runtimeDir,
         change: changeName || '',
         query: taskContext,
+        scopeFiles,
       })
       substitute(
         /\{KNOWLEDGE_HIT_REPORT\}/g,
@@ -2012,11 +2035,18 @@ async function outputStepImpl(stageName, stepIndex, steps, cwd, changeName, dbPr
       const kiSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const kiQuery = String(readQuickGuardField(changeName, kiSpecBase, 'taskDescription') || '')
       if (kiQuery.trim() !== '') {
+        // scope 键（FR-04）：quick 仅 guard.allowedFiles（--files 声明）存在时传，缺失不编造
+        let kiScope = []
+        try {
+          const declared = readQuickGuardField(changeName, kiSpecBase, 'allowedFiles')
+          if (declared) kiScope = graphPathCandidates(String(declared).split(/[,，\s]+/))
+        } catch { /* 无声明 = 无键 */ }
         const ki = buildKnowledgeInjection({
           knowledgeDir: join(kiSpecBase, 'knowledge'),
           runtimeDir: join(kiSpecBase, '.runtime'),
           change: changeName || '',
           query: kiQuery,
+          scopeFiles: kiScope,
         })
         if (ki.section) {
           promptText = promptText + '\n\n' + ki.section

package/src/run/quick-audit.js

@@ -401,7 +401,7 @@ export function buildTestSurfaceAdvisory(files) {
     if (CODE_PATH_SEGMENT_RE.test(f) || CODE_EXTENSION_RE.test(f)) srcCount++
   }
   if (srcCount < MIN_SRC_FILES_FOR_TEST_ADVISORY || testCount > 0) return null
-  return `⚠️ 测试面厚度 advisory：交付面 ${srcCount} 个 src 类文件但测试面为空（0 个测试文件改动，P2 账本测试面无增量可对账），确认无需测试增量？（advisory 不阻断——轻量变更/burst 实证测试量仅为旧流程 40%）`
+  return `⚠️ 测试面厚度 advisory：交付面 ${srcCount} 个 src 类文件但测试面为空（0 个测试文件改动，P2 账本测试面无增量可对账），确认无需测试增量？（advisory 不阻断——轻量变更/burst 实证测试量仅为旧流程 40%）另空实现判据：若把实现改成全部返回空测试仍全绿，则测试是摆设——要补就补断言可观察行为的真测试（2026-10-29-open-metrics-gate task-04）`
 }
 
 /**
@@ -477,7 +477,7 @@ export function mergeGateFiles(audited, declared) {
 
 export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], declaredFiles = [], changeName = null, skipSentinel = false }) {
   if (process.env.SILLYSPEC_QUICK_TEST_GATE === 'skip') {
-    return { action: 'skip', failed: [], reason: 'SILLYSPEC_QUICK_TEST_GATE=skip 显式跳过（审计留痕）', test: null, lint: null }
+    return { action: 'skip', failed: [], reason: 'SILLYSPEC_QUICK_TEST_GATE=skip 显式跳过（审计留痕）', test: null, lint: null, metrics: null, metricsRoutes: null }
   }
   const audited = Array.isArray(changedFiles) ? changedFiles : []
   // 门禁文件集 = 审计 ∪ 声明边界（并集，2026-09-23 ql-018 修复）：旧口径二选一（审计非空时
@@ -499,10 +499,10 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
     (f) => typeof f === 'string' && (CODE_PATH_SEGMENT_RE.test(f) || CODE_EXTENSION_RE.test(f)),
   )
   if (files.length === 0) {
-    return { action: 'skip', failed: [], reason: `无变更文件清单（${fileSource}口径均空——brownfield 无 guard 或空审计），跳过`, test: null, lint: null }
+    return { action: 'skip', failed: [], reason: `无变更文件清单（${fileSource}口径均空——brownfield 无 guard 或空审计），跳过`, test: null, lint: null, metrics: null, metricsRoutes: null }
   }
   if (codeFiles.length === 0) {
-    return { action: 'skip', failed: [], reason: `纯 doc/配置改动（${files.length} 个文件均未触及 src/test，规则 8 语义跳过 test+lint）`, test: null, lint: null }
+    return { action: 'skip', failed: [], reason: `纯 doc/配置改动（${files.length} 个文件均未触及 src/test，规则 8 语义跳过 test+lint）`, test: null, lint: null, metrics: null, metricsRoutes: null }
   }
 
   // ── 测试最低面 advisory（资产三小件②）：放在两条早退之后——纯 doc/env skip/空清单
@@ -517,7 +517,7 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
   // （Grill X-001 附注）。specBase 同理用主仓的（快照副本 local.yaml 不参与开关判定）。
   const semanticGuard = buildSemanticGuardHits({ cwd, specBase, files, changeName })
 
-  const { runVerifyTestCheck, runVerifyLintCheck } = await import('../verify-postcheck.js')
+  const { runVerifyTestCheck, runVerifyLintCheck, runVerifyMetricsCheck, runVerifyMetricsRoutesCheck } = await import('../verify-postcheck.js')
 
   // ── 隔离快照执行（2026-09-10 驾驭小结第六批②，用户实证「lint 实测对账在主仓跑被并行
   // 会话脏文件拦门」）：HEAD 干净快照 + 本会话文件 overlay 后在快照内跑 test+lint——并行
@@ -565,6 +565,8 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
   const failed = []
   let test = null
   let lint = null
+  let metrics = null
+  let metricsRoutes = null
   try {
     // ── P2 三键账本（D-001@v1，batch3 task-01）：同码同环境免重跑（fail-closed——无记录/
     //    键不等/分量不可得=真跑，行为不变）。quick 会话名 per-change 天然隔离账本文件。──
@@ -621,6 +623,30 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
       console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
       lint = runVerifyLintCheck({ cwd, specBase })
     }
+    // ── 收口指标门（2026-10-29-open-metrics-gate task-03，ub-mode「确定性质量门」采纳）：
+    //    commands.metrics 配置才执行，lint 同款隔离快照口径 + 超时回退主仓；非零退出计入
+    //    failed 阻断收口（通过标准由命令自身定义——design 风险节声明的边界）。files 透传注入
+    //    SILLYSPEC_CHANGE_FILES（审计∪声明口径，大仓增量门只扫变更面，存量债不拦新变更）。──
+    metrics = runVerifyMetricsCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: snapshot ? 5 * 60 * 1000 : undefined, changeFiles: files })
+    if (snapshot && metrics.status === 'failed' && /超时/.test(String(metrics.reason || ''))) {
+      console.warn('⚠️ 快照 metrics 超时（junction I/O 慢）→ 主仓复跑 metrics（并行噪声可能混入——失败先做归属鉴定）')
+      metrics = runVerifyMetricsCheck({ cwd, specBase, changeFiles: files })
+    }
+    if (metrics.status === 'failed') {
+      failed.push('metrics')
+    }
+    // ── 路由指标门（2026-10-29-metrics-routes task-02——多语言/monorepo 路径集合路由）：
+    //    单命令门之后执行；failed 归并（同计 'metrics' 一次——两形态是同一道门的两种配置
+    //    形态，重复计会让 failed 数组出现同名项）。files 同源注入路由（gate 命中子集）。──
+    metricsRoutes = runVerifyMetricsRoutesCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: snapshot ? 5 * 60 * 1000 : undefined, changeFiles: files })
+    const routeTimeoutHit = (metricsRoutes.gates || []).some((g) => g && g.status === 'failed' && /超时/.test(String(g.reason || '')))
+    if (snapshot && metricsRoutes.status === 'failed' && routeTimeoutHit) {
+      console.warn('⚠️ 快照 metrics 路由 gate 超时（junction I/O 慢）→ 主仓复跑路由门（并行噪声可能混入——失败先做归属鉴定）')
+      metricsRoutes = runVerifyMetricsRoutesCheck({ cwd, specBase, changeFiles: files })
+    }
+    if (metricsRoutes.status === 'failed' && !failed.includes('metrics')) {
+      failed.push('metrics')
+    }
     // 哨兵断言（2026-09-25-sentinel-wiring，与 flow done 同判）：tasks.md 全勾但零完成
     // 证据（区间提交消息标题与正文均无 task-NN token 且无对应 review.json）→ 计入 failed 拒收。
     // 证据面=整条提交消息（2026-09-25-thin-done-gate-calibration 坑2，同 flow 侧 %B%x1e 口径）。
@@ -700,14 +726,32 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
         lint.resultPath = persistLintResult({ specBase, changeName: typeof changeName === 'string' ? changeName : null, testResultPath: test && test.resultPath, lint }) || lint.resultPath || null
       }
     } catch { /* 持久化 best-effort，不影响门禁语义 */ }
+    // metrics 结果持久化（2026-10-29-open-metrics-gate task-03）：同 lint 语义——并入 test 的
+    // test-result.json（metrics 节）或独立落盘（kind: 'metrics'），证据面供收口评审与排障直读。
+    try {
+      if (metrics && (metrics.status === 'passed' || metrics.status === 'failed')) {
+        const { persistLintResult } = await import('../verify-postcheck.js')
+        metrics.resultPath = persistLintResult({ specBase, changeName: typeof changeName === 'string' ? changeName : null, testResultPath: test && test.resultPath, lint: metrics, section: 'metrics' }) || metrics.resultPath || null
+      }
+    } catch { /* 持久化 best-effort，不影响门禁语义 */ }
+    // 路由门证据（2026-10-29-metrics-routes task-02）：section 'routes'——并入 test-result.json
+    // 的 routes 节或独立件 kind: 'routes'（带 gates 数组），与单命令 metrics 节并存互不覆盖。
+    try {
+      if (metricsRoutes && (metricsRoutes.status === 'passed' || metricsRoutes.status === 'failed')) {
+        const { persistLintResult } = await import('../verify-postcheck.js')
+        metricsRoutes.resultPath = persistLintResult({ specBase, changeName: typeof changeName === 'string' ? changeName : null, testResultPath: test && test.resultPath, lint: metricsRoutes, section: 'routes' }) || metricsRoutes.resultPath || null
+      }
+    } catch { /* 持久化 best-effort，不影响门禁语义 */ }
     return {
       action: failed.length > 0 ? 'fail' : 'pass',
       failed,
       reason: failed.length > 0
         ? `实测失败：${failed.join(' + ')}（命令与输出尾部见上；修复后重跑 --done 不丢进度）`
-        : `触及 src/test 共 ${codeFiles.length} 个文件，test+lint 实测通过（或未配置命令自动跳过）${snapshot ? '（隔离快照口径：并行会话脏文件不计入）' : ''}`,
+        : `触及 src/test 共 ${codeFiles.length} 个文件，test+lint 实测通过（或未配置命令自动跳过）${metrics && metrics.status === 'passed' ? '；metrics 指标门实测通过' : ''}${metricsRoutes && metricsRoutes.status === 'passed' ? '；metrics 路由门全过' : ''}${snapshot ? '（隔离快照口径：并行会话脏文件不计入）' : ''}`,
       test,
       lint,
+      metrics,
+      metricsRoutes,
       // 语义护栏 WARNING（task-06）：只增可选字段，action/failed 判定与调用方读取面均不受影响
       semanticGuard,
     }
@@ -721,7 +765,7 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
           // 结果路径重映射（评审 P1 清偿）：快照内写下的 resultPath 指向快照临时目录——清理后
           // existsSync 恒 false，flow done 的 FAIL 三件套会静默失效。回拷后把 test/lint 的
           // resultPath 改写为主仓路径（对象即返回值，finally 在 return 落地前变异生效）。
-          for (const r of [test, lint]) {
+          for (const r of [test, lint, metrics, metricsRoutes]) {
             if (r && typeof r.resultPath === 'string' && r.resultPath.startsWith(gateSpecBase)) {
               r.resultPath = specBase + r.resultPath.slice(gateSpecBase.length)
             }
@@ -764,16 +808,20 @@ export function printQuickTestLintGate(gate) {
     console.log(`\n🧪 quick test+lint 门禁 — SKIP：${gate.reason}`)
     return
   }
-  for (const [label, r] of [['test', gate.test], ['lint', gate.lint]]) {
+  for (const [label, r] of [['test', gate.test], ['lint', gate.lint], ['metrics', gate.metrics], ['metrics-routes', gate.metricsRoutes]]) {
     if (!r) continue
     const icon = r.status === 'failed' ? '❌' : r.status === 'passed' ? '✅' : '⏭️'
     const dur = typeof r.durationMs === 'number' ? ` (${(r.durationMs / 1000).toFixed(1)}s)` : ''
-    console.log(`${icon} ${label}: ${r.status}${r.command ? ` ← ${r.command}${dur}` : ''}${r.status === 'skipped' && r.reason ? ` — ${r.reason}` : ''}`)
+    const gatesNote = Array.isArray(r.gates) && r.gates.length > 0 ? ` [gates: ${r.gates.map((g) => `${g.name}=${g.status}`).join(', ')}]` : ''
+    console.log(`${icon} ${label}: ${r.status}${r.command ? ` ← ${r.command}${dur}` : ''}${gatesNote}${r.status === 'skipped' && r.reason ? ` — ${r.reason}` : ''}`)
   }
   if (gate.action === 'fail') {
     console.error(`\n🚫 quick test+lint 门禁 — BLOCKED：${gate.reason}`)
     for (const key of gate.failed) {
-      const r = gate[key]
+      // 'metrics' 归并键：单命令门与路由门共用——取有输出尾部者（单命令绿而路由红时尾部挂
+      // metricsRoutes；两者均红时先单命令，路由尾部在其 resultPath 证据件可读）
+      let r = gate[key]
+      if (key === 'metrics' && !(r && r.outputTail) && gate.metricsRoutes && gate.metricsRoutes.outputTail) r = gate.metricsRoutes
       if (r && r.outputTail) console.error(`   ── ${key} 输出尾部 ──\n${r.outputTail}`)
     }
     console.error(`   quick 已停止：修复后重跑 --done（进度不丢）；确认要跳过实测请设 SILLYSPEC_QUICK_TEST_GATE=skip（审计留痕）。`)

package/src/run/verify-quality-scan.js

@@ -105,7 +105,7 @@ export function computeQualityScanFingerprint({ cwd, specBase }) {
  * 保持 1——存量记录无 smoke 段照常读回（smokeResult 兜底 null）；未配置 smoke 时段形态为
  * configured=false（记录仍写，供 --done PASS 封顶判 not-configured）。
  */
-export function storeQualityScan({ specBase, cwd, changeName, testResult, lintResult, smokeResult, usedSnapshot = false, missReason = null, scopeDecision = null }) {
+export function storeQualityScan({ specBase, cwd, changeName, testResult, lintResult, smokeResult, metricsResult = null, metricsRoutesResult = null, usedSnapshot = false, missReason = null, scopeDecision = null }) {
   const path = qualityScanRecordPath(specBase, changeName)
   if (!path) return null
   const fingerprint = computeQualityScanFingerprint({ cwd, specBase })
@@ -137,6 +137,10 @@ export function storeQualityScan({ specBase, cwd, changeName, testResult, lintRe
       testResult,
       lintResult: lintResult || null,
       smokeResult: smokeResult || null,
+      // metrics 指标门结果（2026-10-29-open-metrics-gate，additive——存量记录无键读侧兼容）
+      metricsResult: metricsResult || null,
+      // 路由门结果（2026-10-29-metrics-routes，additive 同上）
+      metricsRoutesResult: metricsRoutesResult || null,
     }, null, 2) + '\n')
     return { path, fingerprint }
   } catch (e) {
@@ -653,7 +657,7 @@ function warnIfMainRepoDirtyForGate(cwd) {
  * `run verify` 复入本步重新实测（指纹随代码修复失配，--done 不会复用旧失败结果）。
  */
 export async function executeVerifyQualityScan({ cwd, specBase, changeName, platformOpts }) {
-  const { runVerifyTestCheck, printVerifyTestCheck, runVerifyLintCheck, printVerifyLintCheck, shouldBlockVerifyLint, classifyTestFailureArtifact } = await import('../verify-postcheck.js')
+  const { runVerifyTestCheck, printVerifyTestCheck, runVerifyLintCheck, printVerifyLintCheck, shouldBlockVerifyLint, classifyTestFailureArtifact, runVerifyMetricsCheck, runVerifyMetricsRoutesCheck } = await import('../verify-postcheck.js')
   // ── RERUN 失败签名闸（r5l-forensic-verdict.md 方案 4 / 评审护栏#6 五态）──
   // R5-L 实证：RERUN=1 两次强制重扫各烧 ~8M 重发 + 10m/6.8m 等待，而失败签名未变——重跑
   // 结果注定相同。故 RERUN=1 生效前先对账失败签名（dedupKey 已含代码指纹×豁免面，再叠测试
@@ -807,6 +811,8 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
   console.log(`\n⏳ noAI 质量扫描：CLI 亲自实测 commands.test（同步，长套件 2~10 分钟无输出属正常）——结果按代码指纹落盘，最终 --done 对账直接复用免重跑。`)
   let testCheck
   let lintCheck
+  let metricsCheck = null
+  let metricsRoutesCheck = null
   let coverageCheck = null
   let smokeResult = null
   try {
@@ -827,6 +833,40 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
       console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
       lintCheck = runVerifyLintCheck({ cwd, specBase })
     }
+    // ── 收口指标门（2026-10-29-open-metrics-gate task-03）：commands.metrics 配置才执行，
+    //    与 quick 道同款语义（隔离快照 + 超时回退主仓 + 非零阻断）；snap.changeFiles 是厚道
+    //    快照自算的变更文件集（gate-snapshot 透出），透传注入 SILLYSPEC_CHANGE_FILES 增量门。──
+    metricsCheck = runVerifyMetricsCheck({
+      cwd: gateCwd, specBase: gateSpecBase,
+      timeoutMs: snap ? 5 * 60 * 1000 : undefined,
+      changeFiles: snap && Array.isArray(snap.changeFiles) ? snap.changeFiles : null,
+    })
+    if (snap && metricsCheck.status === 'failed' && /超时/.test(String(metricsCheck.reason || ''))) {
+      console.warn('⚠️ 快照 metrics 超时（junction I/O 慢）→ 主仓复跑 metrics（并行噪声可能混入——失败先做归属鉴定）')
+      metricsCheck = runVerifyMetricsCheck({ cwd, specBase, changeFiles: snap && Array.isArray(snap.changeFiles) ? snap.changeFiles : null })
+    }
+    if (metricsCheck.status !== 'skipped') {
+      const mIcon = metricsCheck.status === 'failed' ? '❌' : '✅'
+      console.log(`${mIcon} metrics 指标门实测 ${metricsCheck.status}${metricsCheck.command ? ` ← ${metricsCheck.command}` : ''}${metricsCheck.status === 'failed' && metricsCheck.reason ? ` — ${String(metricsCheck.reason).split('\n')[0]}` : ''}`)
+    }
+    // ── 路由指标门（2026-10-29-metrics-routes task-02）：与 quick 道同款——变更文件面 ∩
+    //    gate.paths 段全等前缀路由，仅命中 gate 执行；failed 与单命令门归并阻断。──
+    metricsRoutesCheck = runVerifyMetricsRoutesCheck({
+      cwd: gateCwd, specBase: gateSpecBase,
+      timeoutMs: snap ? 5 * 60 * 1000 : undefined,
+      changeFiles: snap && Array.isArray(snap.changeFiles) ? snap.changeFiles : null,
+    })
+    const routeTimeoutHit = (metricsRoutesCheck.gates || []).some((g) => g && g.status === 'failed' && /超时/.test(String(g.reason || '')))
+    if (snap && metricsRoutesCheck.status === 'failed' && routeTimeoutHit) {
+      console.warn('⚠️ 快照 metrics 路由 gate 超时（junction I/O 慢）→ 主仓复跑路由门（并行噪声可能混入）')
+      metricsRoutesCheck = runVerifyMetricsRoutesCheck({ cwd, specBase, changeFiles: snap && Array.isArray(snap.changeFiles) ? snap.changeFiles : null })
+    }
+    if (metricsRoutesCheck.status !== 'skipped') {
+      for (const g of metricsRoutesCheck.gates || []) {
+        const icon = g.status === 'failed' ? '❌' : g.status === 'passed' ? '✅' : '⏭️'
+        console.log(`${icon} metrics gate「${g.name}」 ${g.status} ← ${g.command}${g.status === 'failed' && g.reason ? ` — ${String(g.reason).split('\n')[0]}` : ''}`)
+      }
+    }
   if (lintCheck.status !== 'skipped') {
     console.log(`\n⏳ noAI 质量扫描：CLI 亲自实测 commands.lint…`)
   }
@@ -852,9 +892,14 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
   } finally {
     if (snap) { try { snap.cleanup() } catch {} }
   }
-  storeQualityScan({ specBase, cwd, changeName, testResult: testCheck, lintResult: lintCheck, smokeResult, coverageCheck, usedSnapshot: Boolean(snap), missReason: _missReasonParts.join('；') || null, scopeDecision: { planned: !process.env.SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF, actual: Boolean(snap) } })
+  storeQualityScan({ specBase, cwd, changeName, testResult: testCheck, lintResult: lintCheck, smokeResult, coverageCheck, metricsResult: metricsCheck, metricsRoutesResult: metricsRoutesCheck, usedSnapshot: Boolean(snap), missReason: _missReasonParts.join('；') || null, scopeDecision: { planned: !process.env.SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF, actual: Boolean(snap) } })
   const testFailed = testCheck.status === 'failed'
   const lintBlocked = shouldBlockVerifyLint(lintCheck)
+  // metrics 指标门阻断（2026-10-29-open-metrics-gate task-03）：非零/超时即 failed——通过标准
+  // 由命令自身定义（无 lint 式归属鉴定，design 风险节声明边界）；skipped（未配置/环境缺件）不拦。
+  const metricsFailed = Boolean(metricsCheck && metricsCheck.status === 'failed')
+  // 路由门阻断（2026-10-29-metrics-routes task-02）：任一命中 gate 失败即拦——与单命令门同一道门
+  const metricsRoutesFailed = Boolean(metricsRoutesCheck && metricsRoutesCheck.status === 'failed')
   // 2026-10-15-lint-triage-path-unify：lint 归属鉴定降档接线（与 gates --done 路径同源共享
   // helper）——零交集存量债降档 advisory 不 throw；owned/unattributable/鉴定异常维持硬拦
   // （保守）。仅在「lint 单独失败」时降档（testFailed 优先 throw——测试失败不作 lint 降档
@@ -867,17 +912,17 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
   // 摩擦计数（friction-signal-hint task-03）：记录条件与 throw 条件**刻意解耦**——advisory 档
   // lint 失败（SILLYSPEC_VERIFY_LINT_GATE=advisory 时不 throw）同样是摩擦信号，计数不应随
   // 逃生阀漂移。recordFrictionEvent 自带静默降级，不影响本步推进/throw 语义。
-  if (testFailed || lintCheck.status === 'failed') {
-    await recordFrictionEvent({ cwd, changeName, platformOpts, type: 'verify_run_failed', detail: testFailed ? 'test' : 'lint' })
+  if (testFailed || lintCheck.status === 'failed' || metricsFailed || metricsRoutesFailed) {
+    await recordFrictionEvent({ cwd, changeName, platformOpts, type: 'verify_run_failed', detail: testFailed ? 'test' : (metricsFailed || metricsRoutesFailed) ? 'metrics' : 'lint' })
   }
-  if (testFailed || (lintBlocked && !lintAdvisoryDowngraded)) {
+  if (testFailed || (lintBlocked && !lintAdvisoryDowngraded) || metricsFailed || metricsRoutesFailed) {
     if (snap) {
       try { const { printSnapshotFailureHint } = await import('./gate-snapshot.js')
         printSnapshotFailureHint(snap) } catch { /* 提示失败不影响阻断 */ }
     }
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
     await renderVerifyTestAttribution({ cwd, changeName, specBase, runtimeRoot })
-    const which = testFailed ? '测试' : 'lint'
+    const which = testFailed ? '测试' : (metricsFailed || metricsRoutesFailed) ? '指标门（metrics）' : 'lint'
     throw new Error(`noAI 质量扫描实测${which}失败——本步骤未完成（进度不推进）。输出与归因提示见上方；修复后重跑 sillyspec run verify${changeName ? ` --change ${changeName}` : ''} 复入本步重新实测。`)
   }
   console.log(`\n✅ noAI 质量扫描全绿——本步骤自动完成；--done 对账将复用本次实测（代码变更即失配重测）。机械事实持续全绿时，verify-probes --init 会预填 PASS 结论草稿（草稿待确认，复核后可改写）。`)

package/src/stages/execute.js

@@ -22,13 +22,45 @@ import { collectExecuteChangedFiles, computeDecisionTouches, renderDecisionTouch
 // const 的 TDZ 求值（ESM 环实证 2026-09-14）。此处为同格式本地孪生，漂移由
 // test/knowledge-inject.test.mjs 格式等价断言锁定——改 prompt.js 版必同步改此处。
 import { matchKnowledge } from '../knowledge-match.js'
-import { matchQuicklogContext, renderQuicklogSection } from '../knowledge-quicklog.js'
+import { matchKnowledgeWithScope, graphPathCandidates, scopeTelemetryRefs } from '../knowledge-graph.js'
 import { appendKnowledgeHit } from '../knowledge-hits.js'
 
 // 机械知识注入限额（与 run/prompt.js KNOWLEDGE_INJECT_MAX_FILES/MAX_LINES 同值孪生，R-02 膨胀控制）
 const KNOWLEDGE_INJECT_MAX_FILES = 3
 const KNOWLEDGE_INJECT_MAX_LINES = 40
 
+/**
+ * task 卡机器键解析（2026-11-02-knowledge-fusion 评审 P1）：target_files / allowed_paths
+ * 三形态——内联列表 `[a, b]`、inline `a, b`、块列表（字段行后 `- item` 行）；剥 NEW: 前缀
+ * 与反引号/引号。旧实现用单行正则 + \s* 跨行，块列表只捕获首项且带 `- ` 前缀。
+ */
+export function parseTaskCardPaths(text) {
+  const out = []
+  const lines = String(text || '').replace(/\r\n?/g, '\n').split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(?:target_files|allowed_paths)\s*[：:]\s*(.*)$/.exec(lines[i])
+    if (!m) continue
+    const inline = m[1].trim()
+    if (inline) {
+      const cleaned = inline.replace(/^\[|\]$/g, '')
+      for (const part of cleaned.split(/[,，\s]+/)) if (part) out.push(part)
+      continue
+    }
+    // 块列表：后续 `- item`（缩进可选），遇到非列表行停止
+    for (let j = i + 1; j < lines.length; j++) {
+      const lm = /^\s*-\s+(.+)$/.exec(lines[j])
+      if (!lm) break
+      out.push(lm[1].trim())
+    }
+  }
+  return out.map((p) => String(p)
+    .replace(/^NEW:\s*/i, '')
+    .replace(/^`+|`+$/g, '')
+    .replace(/^['"]|['"]$/g, '')
+    .trim())
+    .filter(Boolean)
+}
+
 /**
  * Wave 粒度机械知识注入段（task-04，FR-04 / D-002@v1 总体方案 D）：用本 Wave 各 task 标题拼接
  * 串跑 matchKnowledge，命中文件正文以纯文本段注入 buildWavePrompt 输出（**禁止 {{include:}} 形式**
@@ -46,21 +78,32 @@ function buildWaveKnowledgeSection(changeDir, wave) {
     const query = (Array.isArray(wave && wave.tasks) ? wave.tasks : [])
       .map(t => String((t && t.name) || '')).filter(Boolean).join(' ')
     if (!query.trim()) return ''
-    const result = matchKnowledge(knowledgeDir, query)
-    // quicklog 检索面（知识可见性导线）：与 INDEX 知识面独立，INDEX 未命中时照常注入
-    const quick = matchQuicklogContext(specBase, query)
-    if (!result.matched && quick.hits.length === 0) return ''
+    // scope 键（2026-11-02-knowledge-fusion FR-04）：Wave 用 task 卡 target_files/allowed_paths
+    // （机器键）→ graphPathCandidates 规整为图内精确文件路径；无卡/无声明不编造
+    const scopeFiles = graphPathCandidates((wave.tasks || []).flatMap((t) => {
+      const file = t && (t.file || (t.index ? path.join('tasks', `task-${String(t.index).padStart(2, '0')}.md`) : ''))
+      if (!file) return []
+      try {
+        return parseTaskCardPaths(readFileSync(path.join(changeDir, file), 'utf8'))
+      } catch { return [] }
+    }))
+    const result = matchKnowledgeWithScope(knowledgeDir, query, { scopeFiles })
+    const humanEntries = result.entries || []
+    const routeHits = result.routeHits || []
+    const scopeEntries = result.scopeEntries || []
+    if (humanEntries.length === 0 && routeHits.length === 0 && scopeEntries.length === 0) return ''
     const lines = []
-    if (result.matched) {
+    if (humanEntries.length > 0 || routeHits.length > 0 || scopeEntries.length > 0) {
     // ── 以下与 run/prompt.js renderKnowledgeInjectSection 同格式孪生（含段头文案/截断标记）──
     const ref = e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)
     lines.push(`### 📚 命中知识（CLI 按 Wave 任务名机械匹配，top-${KNOWLEDGE_INJECT_MAX_FILES}——勿自行重跑 INDEX 匹配）`)
-    lines.push(`Status: matched | Entries: ${result.entries.length} | Sources:`)
-    for (const e of result.entries) lines.push(` - ${ref(e)}`)
-    lines.push(`（命中清单如上；正文按 INDEX 行序注入前 ${KNOWLEDGE_INJECT_MAX_FILES} 个不同文件，单文件首 ${KNOWLEDGE_INJECT_MAX_LINES} 行截断——未注入条目需要时按 Sources 路径自行读取）`)
+    if (humanEntries.length > 0) {
+    lines.push(`Status: matched | Entries: ${humanEntries.length} | Sources:`)
+    for (const e of humanEntries) lines.push(` - ${ref(e)}`)
+    lines.push(`（命中清单如上；正文按相关度注入前 ${KNOWLEDGE_INJECT_MAX_FILES} 个不同文件，单文件首 ${KNOWLEDGE_INJECT_MAX_LINES} 行截断——未注入条目需要时按 Sources 路径自行读取）`)
     const seen = new Set()
     const picked = []
-    for (const e of result.entries) {
+    for (const e of humanEntries) {
       if (seen.has(e.file)) continue
       seen.add(e.file)
       picked.push(e)
@@ -85,18 +128,23 @@ function buildWaveKnowledgeSection(changeDir, wave) {
       }
     }
     }
-    // quicklog 段与知识段之间空一行（run/prompt.js buildKnowledgeInjection 同款拼接口径）
-    if (quick.hits.length > 0) {
-      if (lines.length > 0) lines.push('')
-      lines.push(renderQuicklogSection(quick.hits, { h3: true }))
+    if (routeHits.length > 0) {
+      lines.push(`🧭 决策/FR 路由命中（专用通道，按需 Read）：${routeHits.slice(0, 3).map(ref).join('；')}`)
+    }
+    if (scopeEntries.length > 0) {
+      lines.push(`📚 触达文件关联手工条目（scope，按需 Read）：${scopeEntries.slice(0, 3).map(ref).join('；')}`)
+    }
     }
     try {
       appendKnowledgeHit(path.join(specBase, '.runtime'), {
         type: 'inject',
         change: path.basename(changeDir),
         query,
-        matchedFiles: result.matched ? result.entries.map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : [],
-        quicklogIds: quick.hits.map(h => h.qlId),
+        matchedFiles: result.matched ? [...humanEntries, ...routeHits].map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : [],
+        ...(result.matched ? (() => {
+          const scopeMatchedFiles = scopeTelemetryRefs(result, { includeRejected: false })
+          return scopeMatchedFiles.length > 0 ? { scopeMatchedFiles } : {}
+        })() : {}),
       })
     } catch { /* 遥测 fail-soft（R-04） */ }
     return lines.join('\n') + '\n'