sillyspec 3.33.7 → 3.33.9

package/src/stages/knowledge.js

@@ -19,7 +19,7 @@
 import { existsSync, readFileSync, readdirSync, mkdirSync, statSync } from 'fs'
 import { join, basename } from 'path'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { parseKnowledgeIndex } from '../knowledge-match.js'
+import { parseKnowledgeIndex, keywordMatchesContext, normalizeAnchorForCompare } from '../knowledge-match.js'
 import { matchKnowledgeHybrid } from '../knowledge-vector.js'
 
 // ── 工具函数 ──
@@ -29,16 +29,6 @@ function resolveKnowledgeDir(dir, specDir) {
   return join(base, 'knowledge')
 }
 
-/**
- * 锚点/标题容错归一（坑 knowledge-hits-anchor-drift T4）：锚点三代规则并存（CLI slug /
- * INDEX 手写 / 平台 slugify_anchor）对 emoji 前缀、点号、斜杠、首尾中划线的处理互不一致
- * ——归一到「仅字母数字 + 小写」后比对，三代产物归一相等；截断（60 字符）由调用方前缀
- * 容忍处理。仅用于 validate 告警，不参与命中判定（单一源方向见 T2）。
- */
-function normalizeAnchorForCompare(s) {
-  return String(s || '').replace(/[^\p{L}\p{N}]+/gu, '').toLowerCase()
-}
-
 function output(ok, data, error) {
   const result = { ok, ...data }
   if (error) result.error = error
@@ -107,8 +97,11 @@ export async function cmdSearch(dir, args, opts = {}) {
     return
   }
 
+  // 已修复条目显式包含（FR-03，2026-11-02-knowledge-rank-denoise）——默认排除
+  const includeResolved = args.includes('--include-resolved')
+
   // 复用 knowledge-match 引擎（三层 hybrid：路由→平台向量→本地词片，2026-09-29-knowledge-vector-recall）
-  const result = await matchKnowledgeHybrid(knowledgeDir, query, { cwd: dir })
+  const result = await matchKnowledgeHybrid(knowledgeDir, query, { cwd: dir, includeResolved })
 
   // 向量开关发现性提示（2026-10-15-vector-switch-discoverability）：平台已连接+开关未开
   // （缺省关）→ hint 键（vectorSwitchHint 单源，flow 注入零命中行同款文案）；其余空串零输出。
@@ -122,24 +115,60 @@ export async function cmdSearch(dir, args, opts = {}) {
   // 文件但被检索核心滤除且最终零结果时，披露被滤文件——去噪不丢可见性，人工按需直查。
   const parkingFiltered = !result.matched && Array.isArray(result.json && result.json.parkingFiltered)
     ? result.json.parkingFiltered : []
+  const payload = buildSearchPayload(result, knowledgeDir, limit, query)
 
-  if (!result.matched) {
-    output(true, {
-      query, matches: [],
-      ...(vectorHint ? { hint: vectorHint } : {}),
-      ...(parkingFiltered.length > 0
-        ? { parkingFiltered, parkingNote: `停车场文件已过滤（${parkingFiltered.join('、')}）——按需直查文件` }
-        : {}),
-    })
-    return
+  output(true, {
+    query,
+    ...payload,
+    ...(vectorHint ? { hint: vectorHint } : {}),
+    ...(parkingFiltered.length > 0
+      ? { parkingFiltered, parkingNote: `停车场文件已过滤（${parkingFiltered.join('、')}）——按需直查文件` }
+      : {}),
+  })
+}
+
+/**
+ * search 面输出载荷（matches + routeHits + 已修复披露）——生产与评测共用单一构造。
+ * routeHits 承载 fr/decisions 路由行指针：FR-04 要求 search 消费面不静默丢失 implemented
+ * 决策/FR 可见性（entries 已移出路由行，只命中路由行的查询不能返回空 matches 了事）。
+ */
+export function buildSearchPayload(result, knowledgeDir, limit, query) {
+  const matches = result && result.matched ? buildSearchMatches(result, knowledgeDir, limit, query) : []
+  const routeHits = ((result && result.routeHits) || []).map(e => ({
+    file: e.file,
+    anchor: e.anchor || '',
+    category: e.category || '',
+  }))
+  const resolvedFiltered = Array.isArray(result && result.json && result.json.resolvedFiltered)
+    ? result.json.resolvedFiltered : []
+  return {
+    matches,
+    ...(routeHits.length > 0
+      ? { routeHits, routeNote: '决策/FR 路由命中（专用通道，按需 Read）' }
+      : {}),
+    ...(resolvedFiltered.length > 0
+      ? { resolvedFiltered, resolvedNote: `已修复条目已过滤（${resolvedFiltered.join('、')}）——需查看加 --include-resolved` }
+      : {}),
   }
+}
 
-  // 增强：为每个匹配项补充 path、title、summary、score
-  const matches = result.entries.slice(0, limit).map(entry => {
+/**
+ * 检索结果 → search 面展示行（title/summary 增强 + 命中数评分）。
+ * 导出为单一源：cmdSearch 与评测适配层（eval/knowledge）共用同一构造。
+ * score = tags 中实际命中 query 的标签数（keywordMatchesContext 同一判定）——关键词表长
+ * 不再冒充命中数（2026-11-02-knowledge-rank-denoise FR-01）。
+ * channel 标明命中通道：routing（INDEX 路由）/ fallback（词片回退）/ vector / scope。
+ */
+export function buildSearchMatches(result, knowledgeDir, limit, query) {
+  const ctx = String(query || '').toLowerCase()
+  const channel = result && result.json && result.json.fallback ? 'fallback'
+    : result && result.json && result.json.vector ? 'vector'
+      : result && result.json && result.json.scope ? 'scope'
+        : 'routing'
+  return result.entries.slice(0, limit).map(entry => {
     const filePath = join(knowledgeDir, entry.file)
     let title = entry.display
     let summary = ''
-    let score = entry.keywords.length // 简单评分：匹配关键词数量
 
     if (existsSync(filePath)) {
       const content = readFileSync(filePath, 'utf8')
@@ -147,18 +176,18 @@ export async function cmdSearch(dir, args, opts = {}) {
       summary = extractSummary(content)
     }
 
+    const tags = entry.keywords
     return {
       id: pathToId(entry.file, knowledgeDir),
       path: join('knowledge', entry.file),
       title,
       summary,
-      score,
-      tags: entry.keywords,
+      score: tags.filter(k => keywordMatchesContext(k, ctx)).length,
+      tags,
+      channel,
       category: entry.category,
     }
   })
-
-  output(true, { query, matches, ...(vectorHint ? { hint: vectorHint } : {}) })
 }
 
 // ── inspect ──

package/src/task-tick.js

@@ -158,6 +158,22 @@ export async function runTaskTick({ changeName, cwd, taskId, specBase, evidence
     } catch (e) {
       console.warn(`⚠️ 勾选留痕写失败（task-ticks.jsonl：${e && e.code ? e.code : e}）——翻格不受影响，timeline 勾选时刻退事件流推断`)
     }
+    // 影子存档（2026-10-28-shadow-checkpoint）：勾选即快照——tasks.md 翻格+侧车落盘后落一个
+    // git 影子提交到 refs/sillyspec/checkpoints/<change>，断点恢复从进度级升到内容级。
+    // best-effort fail-open（模块内零抛出，此处再兜一层）：任何失败只回显一行，绝不影响翻格。
+    try {
+      const { createCheckpoint } = await import('./checkpoint.js')
+      const cp = await createCheckpoint({
+        repoRoot: cwd, changeName,
+        session: process.env.SILLYSPEC_SESSION_ID,
+        taskId: normalizeTaskId(taskId) || taskId,
+      })
+      if (cp.kind === 'created') console.log(`🗂️  影子存档 ${String(cp.sha).slice(0, 8)}（${cp.files} 文件变更）→ refs/sillyspec/checkpoints/${changeName}`)
+      else if (cp.kind === 'noop') console.log(`🗂️  影子存档 noop（工作区无变化，零对象）`)
+      else console.log(`🗂️  影子存档跳过：${cp.reason}${cp.detail ? `（${cp.detail}）` : ''}`)
+    } catch (e) {
+      console.warn(`⚠️ 影子存档失败（不阻断勾选）：${e && e.message ? e.message : e}`)
+    }
     // 工件即时重推（2026-10-07-allticked-gate-docs-resync）：翻格即任务面变更——顺带触发
     // spec-sync，平台不再停留 start 时点快照（真实会话实证：改写后平台恒显初稿）。best-effort。
     try {

package/src/verify-postcheck.js

@@ -344,6 +344,328 @@ export function runVerifyLintCheck({ cwd, specBase, timeoutMs } = {}) {
   }
 }
 
+/**
+ * 从 local.yaml 文本提取 commands.metrics（2026-10-29-open-metrics-gate，task-02）。
+ * 与 extractLintCommand 同风格同容错（带引号/不带引号/unavailable）。
+ * 模块内私有（runVerifyMetricsCheck 消费）。
+ */
+function extractMetricsCommand(yamlText) {
+  if (!yamlText) return null
+  const doubleQuoted = yamlText.match(/^\s*metrics:\s*"([^"]+)"\s*(?:#.*)?$/m)
+  const singleQuoted = yamlText.match(/^\s*metrics:\s*'([^']+)'\s*(?:#.*)?$/m)
+  const quoted = doubleQuoted || singleQuoted
+  if (quoted && quoted[1]) {
+    return quoted[1].toLowerCase() === 'unavailable' ? null : quoted[1].trim()
+  }
+  const bare = yamlText.match(/^\s*metrics:[ \t]*([^\n#]+?)[ \t]*(?:#.*)?$/m)
+  if (bare && bare[1]) {
+    const cmd = bare[1].trim()
+    return cmd.toLowerCase() === 'unavailable' ? null : cmd
+  }
+  return null
+}
+
+/**
+ * 收口指标门实测：跑 local.yaml commands.metrics（2026-10-29-open-metrics-gate，task-02——
+ * ub-mode「确定性质量门」采纳件）。与 runVerifyLintCheck 同构（fail-open 缺省/超时链/CNF 降档/
+ * 输出尾部），刻意差异（design.md 风险节声明的边界）：
+ * - 非 zero/超时即 failed：通过标准由命令自身定义（用户写 crap-check --fail-over 10 src 就是
+ *   他的标准），首版即硬门，无 lint 式观察期
+ * - 无 tally（lint 的 verify-lint-tally 是共享写面，指标门无观察期升级消费方）
+ * - 无 failureFiles/归属鉴定（指标输出无标准路径形态——分数表/JSON/正文，误判比不判更糟，
+ *   扫描范围控制责任交给命令本身）
+ * - CNF 环境缺件降档无「输出含路径」护栏（lint 有 extractLintFailureFiles 非空维持硬拦的
+ *   护栏；指标输出形态开放无从提取——CNF 签名即环境信号）
+ * - 可选 changeFiles → 注入 SILLYSPEC_CHANGE_FILES（POSIX 相对路径换行分隔）：大仓增量门
+ *   只扫变更面（与测试面动态子集同哲学，存量债不拦新变更）；不读该变量的命令零感知
+ * 信任边界与 runVerifyLintCheck 一致：命令只来源于主仓 .sillyspec/local.yaml。
+ */
+export function runVerifyMetricsCheck({ cwd, specBase, timeoutMs, changeFiles } = {}) {
+  const localYamlPath = join(specBase, 'local.yaml')
+  const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
+  const command = extractMetricsCommand(yamlText)
+
+  if (!command) {
+    return {
+      status: 'skipped',
+      command: null,
+      exitCode: null,
+      durationMs: null,
+      outputTail: null,
+      // skipped reason 自带配置引导（引导面③，FR-01）：收口输出与证据文件即引导面，不另设说教输出
+      reason: yamlText
+        ? 'local.yaml 未配置 commands.metrics（或标记 unavailable）——可选指标门：配置后收口实测该命令，非零退出阻断（适合复杂度/重复率/死代码/覆盖率阈值类秒级检查；执行时注入 SILLYSPEC_CHANGE_FILES 变更清单可只扫变更面；变异测试等慢工具建议 pre-push/CI 层）'
+        : `local.yaml 不存在（${localYamlPath}）`,
+    }
+  }
+
+  // 超时链同 lint：显式参 > local.yaml metrics_timeout_sec > env SILLYSPEC_METRICS_TIMEOUT_MS（毫秒）> 缺省 180s
+  const yamlMetricsTimeoutMs = (() => {
+    const m = String(yamlText || '').match(/^\s*metrics_timeout_sec:\s*([0-9]+)\s*(?:#.*)?$/m)
+    return m && Number(m[1]) > 0 ? Number(m[1]) * 1000 : 0
+  })()
+  const METRICS_TIMEOUT_MS = timeoutMs || yamlMetricsTimeoutMs || Number(process.env.SILLYSPEC_METRICS_TIMEOUT_MS) || 3 * 60 * 1000
+  const startedAt = Date.now()
+  let exitCode = 0
+  let output = ''
+  let reason = null
+  // 增量门注入（FR-01）：changeFiles 非空时随子进程环境注入——命令侧按需消费，跨平台 POSIX 路径
+  const envExtra = Array.isArray(changeFiles) && changeFiles.length > 0
+    ? { SILLYSPEC_CHANGE_FILES: changeFiles.map((f) => String(f).replace(/\\/g, '/')).join('\n') }
+    : null
+  try {
+    output = decodeShellOutput(execSync(command, {
+      cwd,
+      encoding: 'buffer',
+      timeout: METRICS_TIMEOUT_MS,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      ...(envExtra ? { env: { ...process.env, ...envExtra } } : null),
+    }))
+  } catch (e) {
+    exitCode = typeof e.status === 'number' ? e.status : 1
+    output = [decodeShellOutput(e.stdout), decodeShellOutput(e.stderr)].filter(Boolean).join('\n') || e.message
+    reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= METRICS_TIMEOUT_MS
+      ? `metrics 命令超时（>${METRICS_TIMEOUT_MS / 1000}s）`
+      : `metrics 命令退出码 ${exitCode}`
+  }
+  const durationMs = Date.now() - startedAt
+  const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
+  let status = exitCode === 0 ? 'passed' : 'failed'
+  let finalReason = exitCode === 0 ? null : reason
+  // 环境缺件降档（复用 lint 语义，2026-09-23 实证先例）：CNF 是环境信号非代码失败，硬拦只会逼
+  // 逃生口；指标输出形态开放，无从做 lint 的「输出含路径维持硬拦」护栏——CNF 签名即降档依据。
+  if (status === 'failed') {
+    const cnf = detectCommandMissingFailure(output)
+    if (cnf.matched) {
+      status = 'skipped'
+      finalReason = `环境缺件：${cnf.binary ? `二进制「${cnf.binary}」` : '命令二进制'}不存在（${cnf.evidence}）——非代码失败不拦门；安装对应工具后 metrics 恢复实测`
+      console.warn(`⚠️ metrics 实测环境缺件降档为跳过：${cnf.evidence}——修复环境（安装工具）而非改代码`)
+    }
+  }
+
+  return {
+    status,
+    command,
+    exitCode,
+    durationMs,
+    outputTail,
+    reason: finalReason,
+  }
+}
+
+/**
+ * metrics_routes 的 paths 值解析：`["a/", "b/"]` 引号数组 / `a/, b/` 逗分裸串 / `"a/"` 单值
+ * 均归一为 string[]（2026-10-29-metrics-routes task-01）。模块内私有。
+ */
+function parseMetricsPathsValue(raw) {
+  if (!raw) return null
+  let s = String(raw).trim()
+  const arrM = s.match(/^\[(.*)\]$/s)
+  if (arrM) s = arrM[1]
+  const parts = s.split(',').map((p) => p.trim().replace(/^["']|["']$/g, '').trim()).filter(Boolean)
+  return parts.length > 0 ? parts : null
+}
+
+/**
+ * 路径段全等前缀匹配（2026-10-29-metrics-routes task-01）：file 归一 POSIX 后判断
+ * `file === base || file.startsWith(base + '/')`——`frontend/` 不命中 `frontend-v2/x`
+ * （段全等，防字符级误蹭），深路径子目录命中。双侧反斜杠归一（Windows 变更文件/配置同口径）。
+ * 模块内私有。
+ */
+function matchesPathPrefix(file, prefix) {
+  const f = String(file || '').replace(/\\/g, '/')
+  const base = String(prefix || '').replace(/\\/g, '/').replace(/\/+$/, '')
+  if (!f || !base) return false
+  return f === base || f.startsWith(base + '/')
+}
+
+/**
+ * 从 local.yaml 文本提取 metrics_routes 段（2026-10-29-metrics-routes task-01）。
+ * 形态随 modules 块先例（extractModules 同风格，坑史同源：任意非零缩进、inline flow 与
+ * 子块展开双形态）。每条目需 paths（前缀集合）与 command（缺一跳过该条目——路由无 paths
+ * 无从匹配）；timeout_sec 可选。轻量行扫描，不引 yaml 依赖。
+ *
+ *   metrics_routes:
+ *     web:
+ *       paths: ["frontend/", "packages/web/"]
+ *       command: "npx --prefix frontend eslint . --max-warnings 0"
+ *       timeout_sec: 300
+ *     web-inline: { paths: "frontend/, packages/web/", command: "make web-check" }
+ *
+ * @param {string} yamlText
+ * @returns {Record<string, {paths: string[], command: string, timeoutSec: number|null}>|null}
+ *   无段或无有效条目 → null（调用方按未配置处理，缺省零回归）
+ */
+export function extractMetricsRoutes(yamlText) {
+  if (!yamlText) return null
+  const lines = normalizeLineEndings(yamlText).split('\n')
+  let startIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (/^metrics_routes:\s*(?:#.*)?$/.test(lines[i])) { startIdx = i; break }
+  }
+  if (startIdx === -1) return null
+
+  const routes = {}
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i]
+    const entry = line.match(/^([ \t]+)([A-Za-z0-9_.\-]+):\s*(.*)$/)
+    if (!entry) {
+      // 新顶层 key（行首非空格非注释非空）→ 块结束
+      if (line.length > 0 && !line.startsWith(' ') && !line.startsWith('#') && line.trim() !== '') break
+      continue
+    }
+    const name = entry[2]
+    const rest = (entry[3] || '').trim()
+    if (rest === '' || rest.startsWith('#')) {
+      // 子块展开式：paths / command / timeout_sec 子行（缩进须深于条目行）
+      let paths = null
+      let command = null
+      let timeoutSec = null
+      for (let j = i + 1; j < lines.length; j++) {
+        const sub = lines[j]
+        if (sub.trim() === '' || sub.trim().startsWith('#')) continue
+        const subM = sub.match(/^([ \t]+)([A-Za-z0-9_.\-]+):\s*(.*)$/)
+        if (!subM || subM[1].length <= entry[1].length) break
+        const key = subM[2]
+        const raw = (subM[3] || '').trim()
+        if (key === 'paths') paths = parseMetricsPathsValue(raw)
+        if (key === 'command') command = raw.replace(/^["']|["']$/g, '') || null
+        if (key === 'timeout_sec') { const n = Number(raw); if (Number.isFinite(n) && n > 0) timeoutSec = n }
+      }
+      if (paths && command) routes[name] = { paths, command, timeoutSec }
+      continue
+    }
+    // inline flow mapping: { paths: [...], command: "...", timeout_sec: N }
+    const pathsRaw = parseFlowValue(rest, 'paths')
+    const command = parseFlowValue(rest, 'command')
+    const tRaw = parseFlowValue(rest, 'timeout_sec')
+    if (command) {
+      const paths = parseMetricsPathsValue(pathsRaw)
+      if (paths) {
+        const n = Number(tRaw)
+        routes[name] = { paths, command, timeoutSec: tRaw && Number.isFinite(n) && n > 0 ? n : null }
+      }
+    }
+  }
+  return Object.keys(routes).length > 0 ? routes : null
+}
+
+/**
+ * 路由指标门实测（2026-10-29-metrics-routes task-01——多语言/monorepo 的路径集合路由）。
+ * 变更文件面 ∩ gate.paths 段全等前缀 → 仅执行命中 gate（未触域不跑——与测试面动态子集同
+ * 哲学）；每 gate 子进程注入 SILLYSPEC_CHANGE_FILES=该 gate 命中子集；串行执行（放弃并行：
+ * 秒级 gate 串行总时长可控，并行放大资源峰值且输出交错难归因——design 风险节声明）。
+ * 语义逐条复用单命令门（runVerifyMetricsCheck）：非零/超时=failed、CNF 环境缺件降档、
+ * 输出尾部。gate 级超时链（特异者胜）：gate.timeout_sec > 显式调用参 > metrics_timeout_sec
+ * > env SILLYSPEC_METRICS_TIMEOUT_MS（毫秒）> 缺省 180s——per-gate 显式值不被调用侧快照
+ * 通用帽（5min）反向压低。
+ * 聚合形态：任一 gate failed → failed；全部命中 gate CNF 降档 → skipped（CNF 不掩盖亦不被
+ * 掩盖）；其余 → passed。顶层字段与单命令结果同构（printQuickTestLintGate 通用循环直读），
+ * gates 数组逐 gate 带 name/status/exitCode/outputTail/matchedFiles。
+ */
+export function runVerifyMetricsRoutesCheck({ cwd, specBase, timeoutMs, changeFiles } = {}) {
+  const localYamlPath = join(specBase, 'local.yaml')
+  const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
+  const routes = extractMetricsRoutes(yamlText)
+
+  if (!routes) {
+    return {
+      status: 'skipped', kind: 'routes', gates: [],
+      command: null, exitCode: null, durationMs: null, outputTail: null,
+      reason: yamlText
+        ? 'local.yaml 未配置 metrics_routes 段——多语言/monorepo 仓可按路径集合路由多个指标门（与 commands.metrics 单命令可共存，执行只跑变更命中的 gate；见 config schema desc）'
+        : `local.yaml 不存在（${localYamlPath}）`,
+    }
+  }
+
+  const files = (Array.isArray(changeFiles) ? changeFiles : []).map((f) => String(f).replace(/\\/g, '/')).filter(Boolean)
+  const hitGates = []
+  for (const [name, gate] of Object.entries(routes)) {
+    const matched = files.filter((f) => gate.paths.some((p) => matchesPathPrefix(f, p)))
+    if (matched.length > 0) hitGates.push({ name, gate, matched })
+  }
+  if (hitGates.length === 0) {
+    return {
+      status: 'skipped', kind: 'routes', gates: [],
+      command: null, exitCode: null, durationMs: null, outputTail: null,
+      reason: `metrics_routes 零命中（变更文件面与 ${Object.keys(routes).length} 个 gate 的 paths 均无交集——未触域不跑，增量语义）gates：${Object.keys(routes).join('、')}`,
+    }
+  }
+
+  const yamlGlobalTimeoutMs = (() => {
+    const m = String(yamlText || '').match(/^\s*metrics_timeout_sec:\s*([0-9]+)\s*(?:#.*)?$/m)
+    return m && Number(m[1]) > 0 ? Number(m[1]) * 1000 : 0
+  })()
+  const startedAt = Date.now()
+  const gates = []
+  for (const { name, gate, matched } of hitGates) {
+    const capMs = (gate.timeoutSec ? gate.timeoutSec * 1000 : 0)
+      || timeoutMs
+      || yamlGlobalTimeoutMs
+      || Number(process.env.SILLYSPEC_METRICS_TIMEOUT_MS)
+      || 3 * 60 * 1000
+    const gateStartedAt = Date.now()
+    let exitCode = 0
+    let output = ''
+    let gateReason = null
+    try {
+      output = decodeShellOutput(execSync(gate.command, {
+        cwd,
+        encoding: 'buffer',
+        timeout: capMs,
+        maxBuffer: 32 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        env: { ...process.env, SILLYSPEC_CHANGE_FILES: matched.join('\n') },
+      }))
+    } catch (e) {
+      exitCode = typeof e.status === 'number' ? e.status : 1
+      output = [decodeShellOutput(e.stdout), decodeShellOutput(e.stderr)].filter(Boolean).join('\n') || e.message
+      gateReason = e.signal === 'SIGTERM' && Date.now() - gateStartedAt >= capMs
+        ? `gate「${name}」超时（>${capMs / 1000}s）`
+        : `gate「${name}」退出码 ${exitCode}`
+    }
+    const durationMs = Date.now() - gateStartedAt
+    const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
+    let status = exitCode === 0 ? 'passed' : 'failed'
+    let finalReason = exitCode === 0 ? null : gateReason
+    if (status === 'failed') {
+      const cnf = detectCommandMissingFailure(output)
+      if (cnf.matched) {
+        status = 'skipped'
+        finalReason = `gate「${name}」环境缺件：${cnf.binary ? `二进制「${cnf.binary}」` : '命令二进制'}不存在（${cnf.evidence}）——非代码失败不拦门；安装对应工具后恢复实测`
+        console.warn(`⚠️ metrics gate「${name}」环境缺件降档为跳过：${cnf.evidence}——修复环境（安装工具）而非改代码`)
+      }
+    }
+    gates.push({ name, status, command: gate.command, exitCode, durationMs, outputTail, reason: finalReason, matchedFiles: matched })
+  }
+
+  const failedGates = gates.filter((g) => g.status === 'failed')
+  const skippedGates = gates.filter((g) => g.status === 'skipped')
+  const status = failedGates.length > 0 ? 'failed' : (skippedGates.length === gates.length ? 'skipped' : 'passed')
+  const reason = failedGates.length > 0
+    ? `路由门 ${failedGates.length}/${gates.length} 个 gate 失败：${failedGates.map((g) => g.name).join('、')}`
+    : (status === 'skipped'
+      ? `路由门全部命中 gate 环境缺件降档（${skippedGates.map((g) => g.name).join('、')}）——安装工具后恢复实测`
+      : `路由门 ${gates.length} 个 gate 全过（${gates.map((g) => g.name).join('、')}）`)
+  // 聚合 outputTail：失败 gate 的 name+尾部拼接（打印/定位面）；无失败为 null
+  const outputTail = failedGates.length > 0
+    ? failedGates.map((g) => `── gate「${g.name}」──\n${g.outputTail || g.reason || ''}`).join('\n')
+    : null
+  return {
+    status,
+    kind: 'routes',
+    gates,
+    command: null,
+    exitCode: failedGates.length > 0 ? failedGates[0].exitCode : 0,
+    durationMs: Date.now() - startedAt,
+    outputTail,
+    reason,
+  }
+}
+
 /**
  * lint 硬门决策（2026-09-09 升硬，外部数据驱动）：观察期 tally 14 次 5 败全真阳性零误伤，
  * 且 pre-push 钩子本就硬拦——verify 侧硬门只是同一标准 fail-fast 前移。
@@ -3669,8 +3991,10 @@ export function runModuleSubset({ cwd, specBase, changeName, hits, knownFailures
  * 优先并入 test 的 test-result.json（modules 并列一节 `lint` 字段，读改写）；test 无
  * 结果文件（skipped/未跑）而 lint 实跑时，用 writeRunResult 形状独立落一份（kind: 'lint'
  * 标识）。返回落盘路径，失败返回 null（best-effort，不阻断门禁）。
+ * section 参数（2026-10-29-open-metrics-gate task-02）：并入字段名与独立件 kind 的泛化
+ * ——metrics 结果走同款落盘语义（section: 'metrics'），缺省 'lint' 零变化。
  */
-export function persistLintResult({ specBase, changeName, testResultPath, lint }) {
+export function persistLintResult({ specBase, changeName, testResultPath, lint, section = 'lint' }) {
   if (!lint || (lint.status !== 'passed' && lint.status !== 'failed')) return null
   if (testResultPath && existsSync(testResultPath)) {
     try {
@@ -3678,7 +4002,7 @@ export function persistLintResult({ specBase, changeName, testResultPath, lint }
       // 并入节自带 resultPath（收编评审 P3：调用方在 persistLintResult 返回后才给 lint.resultPath
       // 赋值——只变异对象不重写盘，并入节会永远缺 resultPath。这里预先补齐，调用方赋同值幂等）
       lint.resultPath = testResultPath
-      j.lint = lint
+      j[section] = lint
       writeFileSync(testResultPath, JSON.stringify(j, null, 2) + '\n')
       return testResultPath
     } catch { /* 结果文件损坏 → 退独立落盘 */ }
@@ -3691,13 +4015,16 @@ export function persistLintResult({ specBase, changeName, testResultPath, lint }
     holder.resultPath = join(runDir, 'test-result.json')
     writeFileSync(holder.resultPath, JSON.stringify({
       change: changeName || null,
-      kind: 'lint',
+      kind: section,
       command: lint.command,
       exit_code: lint.exitCode,
       status: lint.status,
       duration_ms: lint.durationMs,
       output_tail: lint.outputTail,
       reason: lint.reason || null,
+      // gates 透传（2026-10-29-metrics-routes task-01）：路由门独立件带逐 gate 明细；
+      // 单命令/lint 无该数组零影响（additive）。
+      ...(Array.isArray(lint.gates) ? { gates: lint.gates } : {}),
       ran_at: new Date().toISOString(),
     }, null, 2) + '\n')
     return holder.resultPath

package/templates/agents-instruction.md

@@ -32,7 +32,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md（如有））或现有代码依据，无依据不改。
 3. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档（轻量道即：FR 绑定+design 四节+用户批准先于动码，读代码探究不算动码）。测试按层适用：纯逻辑先写测试，行为契约断言用户可见行为，视觉样式与纯配置/文档不写测试（记「不适用：理由」，验收靠规范与人工）。
-4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`（未配置/标 `unavailable` → 收口跳过并留痕理由，归 pre-push/CI 门——pre-push 已跑同款 lint 的仓可标 unavailable 免重复）。以落盘文件与测试结果为准，不信口头"已完成"。自验口径＝变更测试面（新增测试+受影响既有面）即收口证据（lint 已配置时一并实测；标 `unavailable` 的仓归 git 钩子/CI 门）——全量套件归 pre-push 门，勿每变更重复手跑（共享仓全量红先做归属判别，非本变更引入如实留痕不阻断）；跑批输出落 `.sillyspec/.runtime/logs/` 日志回看尾部，勿整段吞掉。
+4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`（未配置/标 `unavailable` → 收口跳过并留痕理由，归 pre-push/CI 门——pre-push 已跑同款 lint 的仓可标 unavailable 免重复）；指标门同款可选：`commands.metrics` 配置后收口实测该命令（非零退出阻断；未配置/`unavailable` 跳过留痕）——适合复杂度/重复率/死代码/覆盖率阈值类秒级检查（命令开放不绑定工具，`npx` 工具或 mvn/gradle 检查目标均可；执行时注入 `SILLYSPEC_CHANGE_FILES` 变更文件清单，大仓可只扫变更面），变异测试等慢工具建议 pre-push/CI；多语言/monorepo 仓可用 `metrics_routes` 路由门按路径集合配多个 gate（仅跑变更命中的 gate，gate 子进程注入 `SILLYSPEC_CHANGE_FILES`=该 gate 命中子集）。以落盘文件与测试结果为准，不信口头"已完成"。自验口径＝变更测试面（新增测试+受影响既有面）即收口证据（lint 已配置时一并实测；标 `unavailable` 的仓归 git 钩子/CI 门）——全量套件归 pre-push 门，勿每变更重复手跑（共享仓全量红先做归属判别，非本变更引入如实留痕不阻断）；跑批输出落 `.sillyspec/.runtime/logs/` 日志回看尾部，勿整段吞掉。
 5. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
 6. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
 7. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。