sillyspec 3.30.0 → 3.32.0

package/src/knowledge-match.js

@@ -11,6 +11,7 @@
 
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
+import { frTitleOverlap } from './fr-index.js'
 
 /**
  * 从 INDEX.md 解析所有知识条目
@@ -115,7 +116,13 @@ function parseDecisionFile(filePath, file) {
   const hits = []
   let cur = null
   const flush = () => {
-    if (cur) hits.push(cur)
+    if (cur) {
+      // 死路注记识别（2026-09-28-knowledge-inject-ranking）：「理由」含「死路：」字面标记的教训型
+      // 条目——记录它的决策本体是 accepted/implemented（死路只是理由里的注记），按状态过滤会被
+      // 压制到组外，恰丢最该防复潮的（实测：D-001@v1 枚举开放世界排 148/188 位永不回显）。
+      cur.deathPath = /死路[：:]/.test(cur.reason || '')
+      hits.push(cur)
+    }
     cur = null
   }
   for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
@@ -209,6 +216,15 @@ export function matchDecisionsByFiles(indexDir, files) {
   return result
 }
 
+/** 死路注记短句提取（消费方渲染用）：理由里「死路：…」到首个句读为止；无标记时截前 60 字。
+ *  单一源供 flow 知识注入段与 complete.js knowledge-gate 回显共用（2026-09-28-knowledge-inject-ranking）。 */
+export function deathPathNote(reason) {
+  const r = String(reason || '')
+  const m = r.match(/死路[：:]\s*([^。；;，,\n]+)/)
+  if (m) return m[1].trim()
+  return r.slice(0, 60)
+}
+
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
@@ -226,17 +242,104 @@ function keywordMatchesContext(keyword, contextLower) {
   return new RegExp(`(^|[^a-z0-9])${escapeRegex(kw)}([^a-z0-9]|$)`).test(contextLower)
 }
 
+/** 查询词片抽取：CJK 连续段 bigram ＋ ≥4 字符 ASCII 词（小写；短词与标点数字不参与；
+ * 纯 ASCII 查询不产词片——中文知识库，英文查询维持既有零命中行为）。 */
+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 seg of raw.match(/[\u4e00-\u9fff]+/g) || []) {
+    for (let i = 0; i < seg.length - 1; i++) shingles.add(seg.slice(i, i + 2))
+  }
+  return [...shingles]
+}
+
+/** ASCII 词片词边界命中（CJK 词片 includes 即可）；转义防正则注入。 */
+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)
+}
+
+/**
+ * 零命中查询侧词片回退（2026-09-29-decision-route-vocab）：路由行零命中时，只测「查询自己的
+ * 词片」——逐 decisions 域文件数词片在条目文本（标题∪理由）的出现次数，落在「跨条目复现但
+ * 非泛在」窗（count ∈ [2, max(2, floor(5%·条目数))]）→ 文件级命中（合成路由条目进 entries，CLI
+ * search／digest 知识命中／门条目行三面共享）；条目级命中 = 该文件内含 ≥1 复现词片的条目
+ * （score=复现词片数，消费方 score>0 资格判定兼容）。
+ * 设计依据：入库侧词表派生死于「同窗词片按序截断=抽签」（unmapped n∈[2,3] 窗 1176 个、
+ * 目标词排 759）；查询侧只测自身几十词片，无挑选无 cap。机制词栖息在理由文本（模板标题不
+ * 含词形——Mouse B 实测四查全零的根因）。无可回退返回 null（保持既有零命中行为）。
+ */
+export function fallbackByQueryShingles(indexDir, taskContext) {
+  const shingles = queryShingles(taskContext)
+  if (shingles.length === 0) return null
+  const all = parseDecisionEntries(indexDir)
+  if (all.length === 0) return null
+  const byFile = new Map()
+  for (const h of all) {
+    let st = byFile.get(h.file)
+    if (!st) { st = { entries: [], texts: [] }; byFile.set(h.file, st) }
+    st.entries.push(h)
+    st.texts.push(`${h.title} ${h.reason || ''}`)
+  }
+  const corroborated = new Map()
+  for (const [file, st] of byFile) {
+    const text = st.texts.join('\n')
+    const ceil = Math.max(2, Math.floor(st.entries.length * 0.05))
+    const hits = new Set()
+    for (const sh of shingles) {
+      if (!asciiWordHit(sh, text)) continue
+      const n = text.split(sh).length - 1
+      if (n >= 2 && n <= ceil) hits.add(sh)
+    }
+    if (hits.size > 0) corroborated.set(file, hits)
+  }
+  if (corroborated.size === 0) return null
+  const fbEntries = [...corroborated.entries()].slice(0, 3).map(([file, hits]) => ({
+    category: 'Decisions',
+    keywords: [...hits].slice(0, 5),
+    file,
+    anchor: '',
+    display: `${file}（查询词片复现命中）`,
+  }))
+  const decisionHits = []
+  for (const [file, hits] of corroborated) {
+    for (const h of byFile.get(file).entries) {
+      const text = `${h.title} ${h.reason || ''}`
+      let mc = 0
+      for (const sh of hits) if (asciiWordHit(sh, text)) mc++
+      if (mc > 0) decisionHits.push({ ...h, score: mc })
+    }
+  }
+  decisionHits.sort((a, b) =>
+    (b.score - a.score) ||
+    (((b.status === 'rejected' || b.deathPath) ? 1 : 0) - ((a.status === 'rejected' || a.deathPath) ? 1 : 0))
+  )
+  return {
+    matched: true,
+    entries: fbEntries,
+    report: `Status: fallback matched (${[...corroborated.keys()].join(', ')} by query shingles)`,
+    json: {
+      matched: true, entry_count: fbEntries.length, fallback: true,
+      entries: fbEntries.map((e) => ({ file: e.file, anchor: e.anchor, keywords: e.keywords, category: e.category })),
+    },
+    decisionHits,
+  }
+}
+
 /**
  * 用任务上下文匹配知识条目
  * @param {string} indexDir - knowledge 目录路径
  * @param {string} taskContext - 任务上下文（task 名称 + 描述，用于关键词匹配）
  * @returns {{ matched: boolean, entries: Array, report: string, json: object,
- *   decisionHits: Array<{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }> }}
+ *   decisionHits: Array<{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string, deathPath?: boolean, score?: number }}> }}
  *   matched/entries/report/json 既有四字段结构与语义不变；decisionHits（task-04 新增）= 任务上下文
  *   命中的 Decisions 路由行所指向 decisions/<域>.md 内的全部 D-xxx@vN 条目，rejected 优先排序；
  *   无 decisions 库 / 路由行未命中 → decisionHits: []（其余字段行为与现状一致）。
  */
-export function matchKnowledge(indexDir, taskContext) {
+export function matchByRouting(indexDir, taskContext) {
   const indexPath = join(indexDir, 'INDEX.md')
 
   // INDEX.md 不存在
@@ -302,14 +405,39 @@ export function matchKnowledge(indexDir, taskContext) {
   }
 
   // decisionHits（task-04）：任务上下文命中的 Decisions 路由行 → 解析其指向的
-  // decisions/<域>.md 内全部条目；rejected 优先排序（防复潮信息最先可见，组内保持文件序）。
+  // decisions/<域>.md 内全部条目；防复潮优先（rejected ∪ 死路注记）＋组内按查询×标题
+  // bigram 重叠率降序（2026-09-28-knowledge-inject-ranking：此前 rejected 优先＋文件序，
+  // 空标题无关条目以文件序霸占回显前 N、相关条目沉底——实测 枚举/开放世界 查询下
+  // D-001@v1 排 148/188 位）。重叠判据复用 fr-index frTitleOverlap（字符 bigram，
+  // 封闭面非语义判定）。
   // 不引入新顶层 hits 字段，不改 matched/entries/report/json 四个既有键。
   const decisionRoutes = matched.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 即
+  // 反超死路条目——数字噪音在无内容词场景主导排序；只计内容字符后该场景全零分 → 平局 →
+  // 死路先验接管）。近义措辞（查询词只在理由不在标题）同样由零分平局裁决兜底。
+  // 刻意不把理由并进评分文本：Jaccard 比率偏爱短文本——短理由无关条目（「与需求直接冲突」共享
+  // 一个 bigram 即得高比率）会压过长理由被稀释的相关条目，实测复现；宁用零分平局先验。
+  const contentChars = (s) => String(s || '').replace(/[\d\p{P}\s_]+/gu, ' ')
+  const relScore = (h) => frTitleOverlap(contentChars(taskContext), contentChars(`${h.id} ${h.title}`))
+  const byOverlapDesc = (a, b) => (relScore(b) - relScore(a)) || ((b.deathPath ? 1 : 0) - (a.deathPath ? 1 : 0))
   const decisionHits = [
-    ...allDecisionHits.filter(h => h.status === 'rejected'),
-    ...allDecisionHits.filter(h => h.status !== 'rejected')
-  ]
+    ...allDecisionHits.filter((h) => h.status === 'rejected' || h.deathPath).sort(byOverlapDesc),
+    ...allDecisionHits.filter((h) => h.status !== 'rejected' && !h.deathPath).sort(byOverlapDesc),
+  ].map((h) => ({ ...h, score: relScore(h) }))
 
   return { matched: true, entries: matched, report, json, decisionHits }
 }
+
+/**
+ * 同步检索入口（既有行为不变）：路由 tag 命中 →（零命中）本地词片复现回退 → 空。
+ * 异步三层入口（平台向量优先于本地回退）见 knowledge-vector.js matchKnowledgeHybrid
+ * （2026-09-29-knowledge-vector-recall）——同步调用方与既有测试全部走本函数。
+ */
+export function matchKnowledge(indexDir, taskContext) {
+  const r = matchByRouting(indexDir, taskContext)
+  if (r.matched) return r
+  const fb = fallbackByQueryShingles(indexDir, taskContext)
+  return fb || r
+}

package/src/knowledge-stats.js

@@ -12,6 +12,8 @@
  * - lastHitAt = 引用该文件的记录 at 最大值（ISO 原样保留；sinceDays 窗口启时时幸存记录
  *   必有可解析 at——readKnowledgeHits 契约滤掉 at 缺失/坏值，'' 兜底仅防御性）；
  * - totalInjects / totalClassifies = 窗口内两类记录条数（按记录计，与 matrix 按条目计独立）；
+ * - lastEventAt = 全量流（不加窗口）最新可解析 at 的原样 ISO（resolveLastEventAt，与
+ *   matrix 的窗口内 lastHitAt 口径分离——「数据截至」不随窗口缩小回退）；无有效记录 null；
  * - 未知 type 不进矩阵不进计数（前向兼容：新事件类型不炸聚合）。
  *
  * neverHit：parseKnowledgeIndex（src/knowledge-match.js 同款解析）得 INDEX.md 唯一 file 全集
@@ -128,6 +130,15 @@ export function buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays = 30 } =
   const frInjectBySource = new Map()
   const rotSuspectByDomain = new Map()
   const rotSuspectChanges = new Set()
+  // 条目级聚合（2026-10-03-fr-governance-telemetry）：frIds/ids 事件 → id → {suspect, unreferenced}
+  // ——L3 裁决候选视图数据面；存量无字段事件自然跳过（向后兼容零破坏）。
+  const adjudicationById = new Map()
+  const bumpId = (id, key) => {
+    if (typeof id !== 'string' || !id) return
+    const row = adjudicationById.get(id) || { id, suspect: 0, unreferenced: 0 }
+    row[key] += 1
+    adjudicationById.set(id, row)
+  }
   let frInject = 0
   let frSupersede = 0
   let frDuplicateWarning = 0
@@ -155,6 +166,7 @@ export function buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays = 30 } =
         row.count += Number.isFinite(Number(r.count)) ? Number(r.count) : 0
         rotSuspectByDomain.set(domain, row)
       }
+      for (const id of Array.isArray(r.frIds) ? r.frIds : []) bumpId(id, 'suspect')
       if (r.change) rotSuspectChanges.add(r.change)
     } else if (r.type === 'fr-unreferenced') {
       const domain = r.domain || 'unknown'
@@ -162,6 +174,7 @@ export function buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays = 30 } =
       row.events += 1
       row.count += Number.isFinite(Number(r.count)) ? Number(r.count) : 0
       unreferencedByDomain.set(domain, row)
+      for (const id of Array.isArray(r.ids) ? r.ids : []) bumpId(id, 'unreferenced')
     }
   }
 
@@ -174,8 +187,18 @@ export function buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays = 30 } =
   const denominator = sourceChanges.size
   const supersedeRate = denominator > 0 ? supersedeChanges.size / denominator : null
 
+  // 裁决候选（2026-10-03-fr-governance-telemetry）：id 级聚合 → 候选清单（附来源变更名——
+  // scanFrIndex entries 的 id→change join）。候选非裁决：高 suspect 天然来自热文件高频触达，
+  // 处置出口在渲染指引（承接翻链/人工退休）。存量无 id 事件不进聚合（视图零噪音）。
+  const changeById = new Map()
+  for (const e of entries) if (e.id && e.change) changeById.set(e.id, e.change)
+  const adjudicationCandidates = [...adjudicationById.values()]
+    .map((row) => ({ ...row, change: changeById.get(row.id) || null }))
+    .sort((a, b) => ((b.suspect + b.unreferenced) - (a.suspect + a.unreferenced)) || a.id.localeCompare(b.id))
+
   return {
     present: frDirExists || frEvents.length > 0,
+    adjudicationCandidates,
     events: {
       frInject,
       frInjectBySource: Object.fromEntries(frInjectBySource),
@@ -200,6 +223,33 @@ export function buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays = 30 } =
   }
 }
 
+// ── 新鲜度读数（2026-10-05-knowledge-stats-freshness）──
+
+/**
+ * 全量遥测流最后写入时间（数据新鲜度读数）。
+ *
+ * 独立于 sinceDays 窗口口径：窗口问「近 N 天统计了多少」，本函数问「这条流最后一次写入
+ * 是什么时候」——窗口缩小不该让「数据截至」跟着回退，故只收 runtimeDir 不收窗口参数。
+ * at 缺失/不可解析的记录不参与取最大（与 readKnowledgeHits 窗口过滤跳过同类）；全部无效
+ * 或零记录 → null（消费方以此区分「有遥测」与「无遥测」两个展示分支）。
+ *
+ * @param {string} runtimeDir - .runtime 目录（knowledge-hits.jsonl 落点）
+ * @returns {string|null} 最新记录 at 的原样 ISO 字符串；无有效记录 null
+ */
+export function resolveLastEventAt(runtimeDir) {
+  let best = null
+  let bestTs = -Infinity
+  for (const record of readKnowledgeHits(runtimeDir)) {
+    const ts = Date.parse(record.at)
+    // >= 同刻取落盘更后者，与 buildHitMatrix touch 的 lastTs 口径一致
+    if (Number.isFinite(ts) && ts >= bestTs) {
+      bestTs = ts
+      best = String(record.at)
+    }
+  }
+  return best
+}
+
 // ── CLI 入口（形态对齐 src/stages/knowledge.js cmdSearch / src/knowledge-classify.js cmdKnowledgeClassify）──
 
 function outputJson(ok, data, error) {
@@ -213,7 +263,7 @@ function outputJson(ok, data, error) {
  *
  * 用法：stats [--since-days N] [--json]
  * 默认人类可读输出（命中矩阵表 + 从未命中清单 + 遥测计数）；--json 输出结构化结果
- * （{ ok, sinceDays, hasTelemetry, matrix, neverHit, totalInjects, totalClassifies }）。
+ * （{ ok, sinceDays, hasTelemetry, lastEventAt, matrix, neverHit, totalInjects, totalClassifies }）。
  * 纯只读。
  *
  * @param {string} dir - 项目根目录
@@ -239,15 +289,18 @@ export async function cmdKnowledgeStats(dir, args, opts = {}) {
     }
     sinceDays = n
   }
-  const asJson = args.includes('--json')
+  // --json 双路判定（对齐 stages/knowledge.js digest 惯例）：全局旗标被 index.js 顶层吞进
+  // opts.json（filteredArgs 不含 --json），args.includes 仅兜底直调/测试场景
+  const asJson = args.includes('--json') || opts.json === true
 
   // 遥测在场判定用全量读取（不加窗口）：文件缺失/只有坏行 → 无遥测
   const hasTelemetry = readKnowledgeHits(runtimeDir).length > 0
+  const lastEventAt = resolveLastEventAt(runtimeDir)
   const result = buildHitMatrix(knowledgeDir, runtimeDir, { sinceDays })
   const frIndex = buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays })
 
   if (asJson) {
-    outputJson(true, { sinceDays, hasTelemetry, ...result, frIndex })
+    outputJson(true, { sinceDays, hasTelemetry, lastEventAt, ...result, frIndex })
     return
   }
 
@@ -281,7 +334,7 @@ export async function cmdKnowledgeStats(dir, args, opts = {}) {
     lines.push('')
   }
 
-  lines.push(`遥测计数（窗口内）：注入 ${result.totalInjects} 次 | 归类 ${result.totalClassifies} 次`)
+  lines.push(`遥测计数（窗口内）：注入 ${result.totalInjects} 次 | 归类 ${result.totalClassifies} 次${lastEventAt ? ` | 数据截至 ${lastEventAt.slice(0, 10)}` : ''}`)
 
   // FR 索引实验（L3 裁决仪表盘——证伪条款出数面；裁决时建议 --since-days 大窗口读全口径）
   if (frIndex.present) {
@@ -296,6 +349,15 @@ export async function cmdKnowledgeStats(dir, args, opts = {}) {
     }
     lines.push(`  索引面：${i.entries} 条（active ${i.active} / superseded ${i.superseded}）| 来源变更 ${i.sourceChanges} 个 | 域 ${i.domains.join(', ') || '—'}`)
     lines.push(`  承接引用率：${frIndex.supersedeRate === null ? '—（索引空）' : `${(frIndex.supersedeRate * 100).toFixed(0)}%（${e.frSupersedeChanges}/${i.sourceChanges}，分子窗口内/分母全量——裁决用大窗口）`}`)
+    // 裁决候选视图（2026-10-03-fr-governance-telemetry）：条目级 id 聚合（事件 frIds/ids，帽 20 抽样
+    // 为下界）。候选非裁决——高 suspect 天然来自热文件；处置出口：确认无人承接 → 承接翻链或人工退休。
+    const cand = frIndex.adjudicationCandidates || []
+    if (cand.length > 0) {
+      lines.push('  裁决候选 Top-10（suspect×unref 条目级聚合——候选非裁决，确认无人承接→承接翻链或人工退休）：')
+      for (const c of cand.slice(0, 10)) {
+        lines.push(`    - ${c.id} suspect×${c.suspect} unref×${c.unreferenced}${c.change ? `（来源 ${c.change}）` : ''}`)
+      }
+    }
   }
 
   console.log(lines.join('\n'))

package/src/knowledge-vector.js

@@ -0,0 +1,160 @@
+/**
+ * knowledge-vector.js — 平台向量召回层（CLI 侧，2026-09-29-knowledge-vector-recall）
+ *
+ * 检索三层：路由 tag 命中 →（零命中）平台向量召回（本模块，已连接平台时）→ 本地词片
+ * 复现窗口（knowledge-match.js fallbackByQueryShingles）→ 空。
+ *
+ * 原则（用户裁决 2026-09-29）：平台只做语义召回——返回「哪个文件哪个条目」的候选
+ * （spec_path＋anchor＋score）；条目 status/deathPath/回显资格等全部策略面在本地解析
+ * （本地文件是真相源，向量结果不携带策略语义）。CLI 本地零模型约束不变。
+ *
+ * 端点契约（SillyHub 侧实现规格，测试夹具按此 mock）：
+ *   POST {platform.url}/api/spec/knowledge/vector-search
+ *   Headers: Authorization: Bearer <token>; Content-Type: application/json
+ *   Body:    { "query": "<检索文本>", "limit": 10 }
+ *   200 →    { "ok": true, "results": [
+ *              { "spec_path": "knowledge/decisions/unmapped.md", "anchor": "D-001@v1",
+ *                "change": "2026-09-26-thin-agent-tasks", "score": 0.83 } ] }
+ *   anchor = 决策条目 id（## D-xxx@vN）；change = 条目「变更：」字段——同号条目跨变更常见
+ *   （runtime.md 七个 D-001@v1 先例），change 在场时消歧；缺省时同号条目全量带回（候选诚实）。
+ *
+ * 降级纪律：任何失败（未连接/开关关闭/网络/404/5xx/超时/响应形态不符）静默降级本地层
+ * ——检索是 advisory 面且高频（每方案步 --done），失败刷屏即狼来了；debug 排障可设
+ * SILLYSPEC_KNOWLEDGE_VECTOR_DEBUG=1 打单行stderr。
+ */
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { readPlatformConfig } from './sync.js'
+import { matchByRouting, fallbackByQueryShingles, parseDecisionEntries } from './knowledge-match.js'
+
+const VECTOR_TIMEOUT_MS = 3000
+const ENDPOINT_PATH = '/api/spec/knowledge/vector-search'
+
+/** local.yaml knowledge.vector_search 开关（行级扫描 knowledge: 段下 vector_search: off）。 */
+function vectorSwitchFromLocalYaml(cwd) {
+  try {
+    const lines = readFileSync(join(cwd, '.sillyspec', 'local.yaml'), 'utf-8').split(/\r?\n/)
+    let inKnowledge = false
+    for (const line of lines) {
+      const top = line.match(/^([A-Za-z_][\w-]*):\s*$/)
+      if (top) { inKnowledge = top[1] === 'knowledge'; continue }
+      if (!inKnowledge) continue
+      const kv = line.match(/^\s+vector_search\s*:\s*(\S+)/)
+      if (kv) return kv[1].toLowerCase()
+    }
+  } catch { /* 无 local.yaml = 缺省 auto */ }
+  return 'auto'
+}
+
+function vectorEnabled(cwd) {
+  const env = String(process.env.SILLYSPEC_KNOWLEDGE_VECTOR || '').toLowerCase()
+  if (env === 'off' || env === 'auto') return env === 'auto'
+  return vectorSwitchFromLocalYaml(cwd) !== 'off'
+}
+
+/**
+ * 平台向量召回（纯 HTTP 层）。未连接/失败/形态不符 → null（调用方降级）。
+ * @returns {Promise<{results: Array<{spec_path: string, anchor: string, score: number}>}|null>}
+ */
+export async function platformVectorRecall({ cwd, query, limit = 10, timeoutMs = VECTOR_TIMEOUT_MS }) {
+  const cfg = readPlatformConfig(cwd)
+  if (!cfg || !cfg.url || !cfg.token) return null
+  const q = String(query || '').trim().slice(0, 4000)
+  if (!q) return null
+  try {
+    const res = await fetch(`${String(cfg.url).replace(/\/+$/, '')}${ENDPOINT_PATH}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${cfg.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query: q, limit }),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!res.ok) {
+      if (process.env.SILLYSPEC_KNOWLEDGE_VECTOR_DEBUG) console.error(`[knowledge-vector] ${res.status} ${ENDPOINT_PATH}——降级本地`)
+      return null
+    }
+    const body = await res.json().catch(() => null)
+    const results = body && Array.isArray(body.results)
+      ? body.results.filter((r) => r && typeof r.spec_path === 'string' && typeof r.anchor === 'string')
+      : []
+    return results.length > 0 ? { results } : null
+  } catch {
+    if (process.env.SILLYSPEC_KNOWLEDGE_VECTOR_DEBUG) console.error(`[knowledge-vector] 请求失败/超时——降级本地`)
+    return null
+  }
+}
+
+/** spec_path（knowledge/decisions/x.md）→ INDEX 相对 file（decisions/x.md）。 */
+function specPathToFile(specPath) {
+  return String(specPath).replace(/^knowledge\//, '').replace(/\\/g, '/')
+}
+
+/** 平台候选 → matchKnowledge 同构结果（策略面全本地解析）。 */
+function buildResultFromPlatform(indexDir, pvResults) {
+  const byFile = new Map()
+  for (const r of pvResults) {
+    const file = specPathToFile(r.spec_path)
+    if (!file.startsWith('decisions/')) continue
+    if (!byFile.has(file)) byFile.set(file, [])
+    byFile.get(file).push(r)
+  }
+  if (byFile.size === 0) return null
+  const all = parseDecisionEntries(indexDir)
+  const entries = []
+  const decisionHits = []
+  for (const [file, rs] of byFile) {
+    const wanted = new Set(rs.map((r) => r.anchor))
+    const fileEntries = all.filter((h) => h.file === file && wanted.has(h.id))
+    if (fileEntries.length === 0) continue
+    for (const r of rs) {
+      // 同号消歧：change 在场取精确条目；缺省同号全量带回（跨变更同号是已知形态）
+      const matched = r.change
+        ? fileEntries.filter((e) => e.id === r.anchor && e.change === r.change)
+        : fileEntries.filter((e) => e.id === r.anchor)
+      for (const h of matched.length > 0 ? matched : []) {
+        decisionHits.push({ ...h, score: typeof r.score === 'number' ? r.score : 1 })
+      }
+    }
+    entries.push({
+      category: 'Decisions',
+      keywords: ['vector'],
+      file,
+      anchor: rs[0].anchor,
+      display: `${file}（平台向量召回）`,
+    })
+  }
+  if (decisionHits.length === 0) return null
+  decisionHits.sort((a, b) =>
+    (b.score - a.score) ||
+    (((b.status === 'rejected' || b.deathPath) ? 1 : 0) - ((a.status === 'rejected' || a.deathPath) ? 1 : 0))
+  )
+  // 缺 change 的同号锚点全量带回可放大（unmapped 实测 65 个 D-001@v1）——score 序封顶 20
+  if (decisionHits.length > 20) decisionHits.length = 20
+  return {
+    matched: true,
+    entries: entries.slice(0, 3),
+    report: `Status: platform-vector matched (${decisionHits.length} entries)`,
+    json: {
+      matched: true, entry_count: Math.min(entries.length, 3), vector: true,
+      entries: entries.slice(0, 3).map((e) => ({ file: e.file, anchor: e.anchor, keywords: e.keywords, category: e.category })),
+    },
+    decisionHits,
+  }
+}
+
+/**
+ * 异步三层检索入口（四消费方使用：flow 注入段／complete 门／prompt {DECISION_HITS}／
+ * knowledge search CLI）：路由 → 平台向量（已连接且开关开）→ 本地词片 → 空。
+ * opts.cwd = 仓根（平台配置与 local.yaml 定位用）；缺省由 indexDir 上推两级。
+ */
+export async function matchKnowledgeHybrid(indexDir, taskContext, opts = {}) {
+  const r = matchByRouting(indexDir, taskContext)
+  if (r.matched) return r
+  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
+  }
+  const fb = fallbackByQueryShingles(indexDir, taskContext)
+  return fb || r
+}

package/src/machine-interface.js

@@ -141,7 +141,7 @@ function greenCachedCheck({ kind, greenRoot, cwd, specBase, changeName }, runRea
   return result;
 }
 
-export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null, full = false } = {}) {
+export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null, full = false, docsOnly = false } = {}) {
   const specRoot = specBase || resolveSpecDir(cwd);
   // A4：pm 用 specRoot（而非默认 resolveSpecDir(cwd)）——--spec-dir/平台模式下 specBase 是真实
   // specDir，默认解析会指向本地孤儿库，与下方 planContent/changeDir 的 specRoot 两套事实源混拼。
@@ -312,7 +312,28 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
     }
 
     // ── d. verify 阶段追加 verify-test（CLI 实测 local.yaml commands.test）──
-    if (stage === 'verify') {
+    // docsOnly 预检档（2026-10-06-verify-docs-prefill task-01）：纯文档契约缺项（visual-evidence/
+    // 结论槽/移交项等）毫秒级可查，却因 gate verify 含测试执行而整体变贵（postmortem 实证
+    // --json 超时转后台）——本档跳过 test/lint 执行（informational 占位明示），其余检查照跑；
+    // 测试客观核验仍以完整 gate verify / verify --done 为准。
+    if (stage === 'verify' && docsOnly) {
+      checks.push({
+        id: 'verify-test',
+        code: checkCode('verify-test'),
+        ok: true,
+        informational: true,
+        warnings: ['verify-test 跳过（--docs-only 预检档）——本档只核文档/契约面不执行测试；测试客观核验以完整 gate verify（不带 --docs-only）或 verify --done 为准'],
+        data: { status: 'docs-only-skip' },
+      });
+      checks.push({
+        id: 'verify-lint',
+        code: checkCode('verify-lint'),
+        ok: true,
+        informational: true,
+        warnings: ['verify-lint 跳过（--docs-only 预检档）——同上，lint 客观核验以完整 gate 或 verify --done 为准'],
+        data: { status: 'docs-only-skip' },
+      });
+    } else if (stage === 'verify') {
       // 绿缓存根：与 runtimeRoot 解析同源（drift 锚主仓口径）；解析失败 null → 不缓存不命中
       let greenRoot = null;
       try { greenRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot); } catch { greenRoot = null; }
@@ -473,6 +494,32 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
       }
     }
 
+    // ── e3. stage-review 默认档提示（2026-10-07-flow-friction-batch3 task-01）── postmortem
+    //    （provider-model-list）：gate execute 默认档不含 Stage Review 检查（在 --full 档），
+    //    agent 跑 gate 见 ok、--done 却被 Stage Review Gate 拦。默认档补 informational 探测
+    //    （同一 getLatestStageReviewRunId 只读 marker 存在性，秒级）：缺 review → warning 带
+    //    register 指引；在场 → 静默 ok。独立 check id 不与 --full 的 full-stage-review 碰撞，
+    //    error 语义（--done 拦）仍归 --full 档与 --done 本体。
+    if (!full && (stage === 'verify' || stage === 'execute')) {
+      try {
+        const { getLatestStageReviewRunId } = await import('./stage-review.js');
+        const rrRoot = runtimeRoot || join(specRoot, '.runtime');
+        const runId = getLatestStageReviewRunId(rrRoot, stage, changeName);
+        checks.push({
+          id: 'stage-review-hint',
+          code: 'stage_review_hint',
+          ok: true,
+          informational: true,
+          warnings: runId ? [] : [
+            `缺 ${stage} 阶段的 stage review.json——verify/execute --done 的 Stage Review Gate 会拦（本提示不改变 gate 结论）。先产出评审再注册：sillyspec register-stage-review --change ${changeName} --stage ${stage}（骨架生成后填，或 --from review.json 过继独立评审产出）`,
+          ],
+          data: { runId: runId || null },
+        });
+      } catch (e) {
+        // fail-open：探测装配失败不留痕（默认档零行为变化承诺）
+      }
+    }
+
     // ── 综合结论：所有非 informational check 均 ok ──
     const ok = checks.filter((c) => !c.informational).every((c) => c.ok);
     const exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
@@ -854,3 +901,44 @@ export function writeGateResultArtifact({ specBase, stage, changeName, envelope
     return null // fail-soft：落盘是审计附件，失败只缺附件不误门
   }
 }
+
+/**
+ * gate last 的读取面（2026-10-06-verify-friction-fix task-02）：writeVerifyGatePointer（gates.js
+ * quick-D）只写不读——看上轮 verify --done blocked 原因只能重跑全量 gate（超时转后台）或手翻
+ * 两层 JSON。本函数读稳定指针并带上其指向取证目录里的 reconcile/probe-consistency 明细。
+ * run 目录用指针内 latest_run_dir 的 basename 在当前根下重推导（指针里的绝对路径可能来自
+ * 另一机器/根，跨环境直接拼会静默指空）。fail-soft：指针缺失 → found:false；损坏 → unreadable。
+ * @param {{ specBase: string, changeName: string }} opts
+ * @returns {{ found: boolean, pointerPath: string, unreadable?: boolean, error?: string } &
+ *   Partial<{ blocked: boolean, note: string, latest_run_dir: string, run_dir_resolved: string,
+ *     written_at: string, reconcile: object, probeConsistency: object }>}
+ */
+export function summarizeVerifyGatePointer({ specBase, changeName }) {
+  const runsDir = join(specBase, '.runtime', 'verify-runs')
+  const pointerPath = join(runsDir, `gate-last-${changeName || 'change'}.json`)
+  if (!existsSync(pointerPath)) return { found: false, pointerPath }
+  let pointer
+  try {
+    pointer = JSON.parse(readFileSync(pointerPath, 'utf8'))
+  } catch (e) {
+    return { found: true, unreadable: true, pointerPath, error: e.message }
+  }
+  const out = { found: true, pointerPath, ...pointer }
+  const runDirName = pointer.latest_run_dir
+    ? String(pointer.latest_run_dir).split(/[\\/]/).filter(Boolean).pop()
+    : null
+  if (runDirName) {
+    const runDir = join(runsDir, runDirName)
+    out.run_dir_resolved = runDir
+    for (const [key, file] of [['reconcile', 'reconcile-result.json'], ['probeConsistency', 'probe-consistency-result.json']]) {
+      const p = join(runDir, file)
+      if (!existsSync(p)) continue
+      try {
+        out[key] = JSON.parse(readFileSync(p, 'utf8'))
+      } catch (e) {
+        out[key] = { unreadable: true, error: e.message }
+      }
+    }
+  }
+  return out
+}

package/src/module-impact.js

@@ -26,9 +26,12 @@ import { resolveSpecDir } from './run/shared.js'
 export function parseModuleMapPaths(yamlText) {
   const map = new Map()
   if (!yamlText) return map
+  // CRLF 归一（Windows 生成的 map：块式行靠 \s*$/.trim() 蒙混，内联数组正则恒失配——
+  // sillyhub-daemon 整图内联 CRLF 实证漏 343 条）
+  const text = String(yamlText).replace(/\r\n/g, '\n')
   let currentModule = null
   let inPaths = false
-  for (const line of yamlText.split('\n')) {
+  for (const line of text.split('\n')) {
     if (!line.trim() || line.trim().startsWith('#')) continue
     if (!/^\s/.test(line)) {
       inPaths = line.startsWith('modules:')
@@ -41,6 +44,18 @@ export function parseModuleMapPaths(yamlText) {
       inPaths = false
       continue
     }
+    // 内联 paths 数组（ground truth 审计实证：sillyhub-daemon 整图内联写法，本解析器此前
+    // 恒漏 343 条 paths＝归属全盲——对齐 parseModulePathsSubset / parseModuleMapSimple 的既有内联支持）
+    const inlinePaths = currentModule && line.match(/^    paths: \[(.*)\]$/)
+    if (inlinePaths) {
+      if (!map.has(currentModule)) map.set(currentModule, [])
+      for (const v of inlinePaths[1].split(',').map(s => s.trim()).filter(Boolean)) {
+        const unquoted = v.replace(/^(['"])([\s\S]*)\1$/, '$2')
+        map.get(currentModule).push(unquoted.replace(/\\/g, '/'))
+      }
+      inPaths = false
+      continue
+    }
     if (currentModule && /^    paths:\s*$/.test(line)) {
       inPaths = true
       if (!map.has(currentModule)) map.set(currentModule, [])
@@ -56,8 +71,14 @@ export function parseModuleMapPaths(yamlText) {
         const raw = item[1].trim()
         const unquoted = raw.replace(/^(['"])([\s\S]*)\1$/, '$2')
         map.get(currentModule).push(unquoted.replace(/\\/g, '/'))
+        continue
       }
     }
+    // 结构守卫（坑 module-map-list-leak，2026-10-06-wallclock-entry 实测发现）：paths 收集只在
+    // 「6 缩进项行 / 空行 / 注释」上存活，其余任何行——字段头（字段名开放集不枚举）、顶层段
+    // （span_risk:/blast:）、异缩进项（2 缩进 "- prefixes:"）——终结收集，防 tags/aliases/
+    // depends_on 字段项与顶层 blast prefixes 漏进 paths 污染 classifyFile 归属分类。
+    inPaths = false
   }
   return map
 }