sillyspec 3.33.3 → 3.33.4

package/src/git-helper.js

@@ -15,6 +15,7 @@
 import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
+import { createHash } from 'node:crypto'
 
 /**
  * git C 风格引号路径解码：`\\` `\"` `\n` `\t` 与 `\NNN` 八进制**原始字节**。
@@ -146,6 +147,87 @@ export function git(cwd, args, opts = {}) {
   return trim ? value.trim() : value
 }
 
+/**
+ * 批量对象存在性判定（2026-10-21-protocol-tax task-07 / FR-07）。
+ *
+ * 单次 `git cat-file --batch-check`（SHA 列表走 stdin）替代逐 SHA `cat-file -e`——
+ * Windows 单次 git spawn ~100-150ms，归档锚点校验在 681 归档仓实测串行 25s+，批量化后
+ * 一次 spawn 判完全部。探针形态 `<sha>^{commit}` 与旧逐查同构（tag/tree 对象不算 commit）。
+ *
+ * @param {string} cwd
+ * @param {string[]} shas 40-hex SHA 列表（大小写不敏感，返回键统一小写）
+ * @returns {Map<string, boolean>} sha → 是否为可解析 commit；整批失败返回空 Map
+ *   （调用方查表 miss = false = 不可解析 = 悬空——与逐查失败同向 fail，不静默洗白）
+ */
+export function batchCatFileExists(cwd, shas) {
+  const map = new Map()
+  if (!Array.isArray(shas) || shas.length === 0) return map
+  const probes = shas.map((s) => `${s}^{commit}`)
+  try {
+    const out = execFileSync('git', buildFullArgs(cwd, ['cat-file', '--batch-check']), {
+      encoding: 'utf8', timeout: 30000, maxBuffer: GIT_MAX_BUFFER,
+      input: probes.join('\n') + '\n',
+      env: gitChildEnv(), windowsHide: true,
+    })
+    for (const line of String(out).split('\n')) {
+      // 行形态：可解析 → git 回显**解析后裸 SHA**（不回显输入串）`<sha> commit <size>`；
+      // 不可解析 → 回显输入串 `<sha>^{commit} missing`。统一剥后缀取裸 SHA 作键。
+      const m = line.match(/^([0-9a-f]{40})(?:\^\{commit\})?\s+(\S+)/i)
+      if (m) map.set(m[1].toLowerCase(), m[2] === 'commit')
+    }
+  } catch { /* 整批失败：空表全 miss=悬空（同逐查失败语义） */ }
+  return map
+}
+
+/**
+ * 批量暂存区 blob 内容哈希（2026-10-21-protocol-tax task-07 / FR-07 配套）。
+ *
+ * 单次 `git cat-file --batch`（stdin 逐行 `:path`）替代逐文件 `git show :path`——apply
+ * 交付指纹漂移维度对最近 5 份 manifest × 全部文件逐个起进程，Windows spawn 税可观。
+ * 响应按输入顺序回流：成功 `<oid> blob <size>\n<content>\n`、缺失 `<ref> missing\n`；
+ * 内容与写侧同基（staged blob 即 LF 规范态），sha256 直算 content 字节。
+ *
+ * @param {string} cwd
+ * @param {string[]} paths 仓库相对路径列表
+ * @returns {Map<string, string|null>} path → staged 内容 sha256（null=未暂存/不可解析）；
+ *   整批失败返回空 Map（调用方查表 miss=null=未暂存，与逐查 gitQuiet null 同语义）
+ */
+export function batchStageBlobSha256(cwd, paths) {
+  const map = new Map()
+  if (!Array.isArray(paths) || paths.length === 0) return map
+  let out
+  try {
+    out = execFileSync('git', buildFullArgs(cwd, ['cat-file', '--batch']), {
+      encoding: 'buffer', timeout: 30000, maxBuffer: GIT_MAX_BUFFER,
+      input: paths.map((p) => `:${p}`).join('\n') + '\n',
+      env: gitChildEnv(), windowsHide: true,
+    })
+  } catch { return map }
+  const buf = Buffer.isBuffer(out) ? out : Buffer.from(String(out), 'binary')
+  let pos = 0
+  let idx = 0
+  while (pos < buf.length && idx < paths.length) {
+    const nl = buf.indexOf(0x0a, pos)
+    if (nl === -1) break
+    const header = buf.toString('utf8', pos, nl).trim()
+    pos = nl + 1
+    const parts = header.split(/\s+/)
+    if (parts[parts.length - 1] === 'missing') {
+      map.set(paths[idx], null)
+      idx++
+      continue
+    }
+    const size = Number.parseInt(parts[parts.length - 1], 10)
+    if (!Number.isFinite(size) || pos + size > buf.length) break // 形态意外：截断防错读
+    map.set(paths[idx], createHash('sha256').update(buf.subarray(pos, pos + size)).digest('hex'))
+    pos += size + 1 // 内容 + 尾随换行
+    idx++
+  }
+  // 尾部未覆盖的路径（流截断等）按未暂存处理——与逐查失败同向
+  for (; idx < paths.length; idx++) map.set(paths[idx], null)
+  return map
+}
+
 /**
  * 静默版 git：内部调 git，失败 catch 返回 null（对齐 worktree 本地 gitQuiet() 语义）。
  * ENOBUFS（输出超 GIT_MAX_BUFFER 上限）不是"无输出"，静默成 null 会让调用方把大输出误当空清单——

package/src/handoff.js

@@ -164,6 +164,10 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
   } else {
     lines.push('# （流程终态，无续跑命令）');
   }
+  // 所有权接缝预告（2026-10-21-p0-p1-hardening FR-05 / dsh z2 实证：新会话自拟新 SESSION_ID
+  // 而非沿用交接块导出的旧 ID 时，首个写操作必撞 15 分钟活跃窗被迫 --takeover）：粘贴块内显式
+  // 给出出路，消「交接块没预告接管」的设计缺口。
+  lines.push('# ⚠️ 若换用新的 SILLYSPEC_SESSION_ID（不推荐，保持上方导出值即可）：首个写操作（--done/--answer 等）会撞所有权活跃窗——等窗过期自动接管，或首写带 --takeover 显式接管留痕');
   lines.push('# ── 交接块结束 ──');
   lines.push('');
   lines.push(`📋 ${target}：当前 ${STAGE_LABELS[currentStage] || currentStage}${steps.length > 0 ? `（步骤 ${doneSteps}/${steps.length}）` : ''}${stageCompleted ? ' ✅ 已完成' : ''}`);

package/src/hooks/worktree-guard.js

@@ -67,11 +67,14 @@ const STAGE_HINTS = {
     '  - <可验证标准>"',
     '  逻辑变更(skill sillyspec-brainstorm)：sillyspec run brainstorm → plan → execute → verify → archive',
     '  全自动模式(skill sillyspec-auto)：sillyspec run auto "任务描述"',
+    '',
+    '若在头脑风暴阶段做真原型（变更 key 已出）：sillyspec worktree create <变更名> 进隔离树写原型，',
+    '已在 worktree 内则复用当前目录不重复创建；文档照常主树（worktree 内运行 sillyspec 自动锚回主仓根）。',
   ],
   'brainstorm': [
-    '当前在 brainstorm（需求分析）阶段，这个阶段只写文档，不写代码。',
-    '完成 brainstorm 后，流程会自动推进到 plan → execute。',
-    'execute 阶段才允许写代码。',
+    '当前在 brainstorm（需求分析）阶段：spec 文档写主树；做真原型须先进隔离 worktree——变更 key 已出，运行 sillyspec worktree create <变更名>（已在 worktree 内则复用当前目录，不重复创建），原型代码写 worktree 内。',
+    '文档不受影响：worktree 内运行 sillyspec 会自动锚回主仓根，文档照常落主树。',
+    '完成 brainstorm 后，流程会自动推进到 plan → execute；execute 会复用已建的 worktree。',
   ],
   'plan': [
     '当前在 plan（计划制定）阶段，这个阶段只写计划文档和任务蓝图，不写代码。',
@@ -805,6 +808,12 @@ export function shouldBlockWrite(filePath, cwd) {
   // 2. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
   if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
 
+  // 2.5 位置豁免（2026-10-21-brainstorm-proto-worktree）：已注册 worktree（meta.json 登记）
+  // 是隔离区——路径落在其内即放行，不问阶段，与 Bash 侧 worktree-cwd 全放行对称。
+  // 头脑风暴期做真原型的协议出口：变更 key 已出 → sillyspec worktree create → 进树写原型。
+  // 未登记的 worktrees 存储区子目录不沾此豁免（下方阶段门照拦）。
+  if (isInsideRegisteredWorktree(absPath, projectRoot)) return { blocked: false }
+
   if (!['execute', 'quick'].includes(stage)) {
     return {
       blocked: true,

package/src/hot-cache.js

@@ -0,0 +1,60 @@
+/**
+ * hot-cache.js — 跨进程热路径缓存小工具（2026-10-21-knowledge-tier-denoise FR-03）
+ *
+ * 服务对象：纯读派生面（quicklog flow 归档伪条目扫描、knowledge-graph 构建）——输入是
+ * 冻结/低频变更面（归档目录、知识库、模块图），派生结果跨进程可复用。落点
+ * .sillyspec/.runtime/cache/（gitignored 且被平台 spec 上传排除——与 vector-capability
+ * 同款纪律；writeAtomicSync 自建父目录）。
+ *
+ * 契约：
+ *   - 读：SILLYSPEC_HOT_CACHE=off 逃生阀直 null；version/fingerprint 任一不匹配 → null；
+ *     ttlMs>0 且 savedAt 超窗 → null；坏 JSON/缺文件 → null（fail-open，缓存非真相源）
+ *   - 写：原子；写失败 fail-soft 返回 false（加速面失败不阻断本体）
+ *   - fingerprint 须可 JSON 稳定序列化且键序/元素序确定（数组按序构造，dirStamp 已排序）
+ */
+import { readFileSync, readdirSync, statSync } from 'fs'
+import { join } from 'path'
+import { writeAtomicSync } from './fs-atomic.js'
+
+/** 读缓存：命中返回 payload，任何不匹配/损坏/关闭 → null。 */
+export function readHotCache(cachePath, { version, fingerprint, ttlMs = 0, now = Date.now() }) {
+  if (process.env.SILLYSPEC_HOT_CACHE === 'off') return null
+  try {
+    const obj = JSON.parse(readFileSync(cachePath, 'utf-8'))
+    if (!obj || obj.version !== version) return null
+    if (JSON.stringify(obj.fingerprint) !== JSON.stringify(fingerprint)) return null
+    if (ttlMs > 0 && !(typeof obj.savedAt === 'number' && now - obj.savedAt <= ttlMs)) return null
+    return obj.payload
+  } catch { return null }
+}
+
+/** 写缓存：原子落盘 {version, fingerprint, savedAt, payload}；失败 fail-soft。 */
+export function writeHotCache(cachePath, { version, fingerprint, payload, now = Date.now() }) {
+  try {
+    writeAtomicSync(cachePath, JSON.stringify({ version, fingerprint, savedAt: now, payload }))
+    return true
+  } catch { return false }
+}
+
+/** 目录级指纹：子项名全集 + 目录 mtimeMs——子项增删/改名必变；不感知深层内容变化
+ *  （配冻结输入面用：归档目录、或配 TTL 硬上限）。目录缺席 → null。 */
+export function dirStamp(dir) {
+  try {
+    return { names: readdirSync(dir).sort(), mtimeMs: statSync(dir).mtimeMs }
+  } catch { return null }
+}
+
+/** 文件级指纹：目录内全部文件（含 _module-map.yaml 等非 md）名 → mtimeMs:size，按名排序。
+ *  感知本目录文件的新增/删除/就地重写（模块卡归档重写、知识文件蒸馏都在此列）；
+ *  不递归子目录（子目录增删由上层逐目录 fileDirStamp 覆盖）。目录缺席 → null。 */
+export function fileDirStamp(dir) {
+  try {
+    const out = []
+    for (const f of readdirSync(dir).sort()) {
+      const st = statSync(join(dir, f))
+      if (st.isDirectory()) continue
+      out.push([f, `${st.mtimeMs}:${st.size}`])
+    }
+    return out
+  } catch { return null }
+}

package/src/index.js

@@ -6,7 +6,7 @@
  * 只负责两件事：init（安装命令模板）和 setup（安装 MCP 工具）。
  * 状态管理通过 sillyspec.db（SQLite）完成，使用 `sillyspec progress` 命令。
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, writeSync, unlinkSync } from 'fs';
 import { runtimeStatePath } from './runtime-paths.js'
 import { writeAtomicSync } from './fs-atomic.js';
 import { basename, dirname, extname, join, resolve, isAbsolute, sep, relative } from 'path';
@@ -237,6 +237,47 @@ function refuseRetiredQuickFreshStart(stageArgs) {
   process.exit(1)
 }
 
+/**
+ * 全局输出收集器（2026-10-21-protocol-tax FR-03）。
+ *
+ * 收编会话考古（z1）发现的 agent 自发模式：44/48 次把 CLI 输出重定向进日志再 tail 尾部——
+ * 工具精心生成的规则大半没进上下文，且 shell 包装会掩蔽真实退出码。内建后：全文落
+ * --out-file 文件、stdout 只回提示行+尾 N 行（--tail，默认 40），退出码零拦截（失败信息
+ * 进尾行或全文件，不丢）。
+ *
+ * 实现要点：
+ * - 拦截点选 process.stdout.write/process.stderr.write（console.log/error 底层同路，
+ *   JSON envelope 直写 process.stdout 的命令也被覆盖；stdio:'inherit' 的子进程直写 fd
+ *   不经此层——已知豁免面，退出码不受影响）。
+ * - exit 钩子同步落盘+尾行输出用 fs.writeSync 直写 fd（exit 期 pipe 异步写会丢）。
+ * - 观测面优先、绝不改变命令成败：写文件失败退化为全量打印；收集器任何异常不影响退出码。
+ */
+function installOutFileRedirect(outFile, tailN) {
+  const entries = [];
+  const push = (chunk) => { entries.push(typeof chunk === 'string' ? chunk : chunk.toString()); return true; };
+  process.stdout.write = push;
+  process.stderr.write = push;
+  process.on('exit', () => {
+    const full = entries.join('');
+    let wrote = true;
+    try { writeFileSync(outFile, full); } catch { wrote = false; }
+    if (!wrote) {
+      try {
+        writeSync(2, `⚠️ --out-file 写入失败（${outFile}）——改为全量打印：\n`);
+        writeSync(1, full);
+      } catch { /* exit 期 best-effort */ }
+      return;
+    }
+    const lines = full.split('\n');
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    const tail = lines.slice(-tailN);
+    try {
+      writeSync(1, `📄 全文已写 ${outFile}（${lines.length} 行，尾 ${tail.length} 行）：\n`);
+      if (tail.length) writeSync(1, tail.join('\n') + '\n');
+    } catch { /* exit 期 best-effort */ }
+  });
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -269,6 +310,9 @@ async function main() {
   // 平台模式 flag（init 落平台指针用；非 init 命令时忽略——runCommand 自行解析 filteredArgs）
   let platformWorkspaceId = null;
   let platformRuntimeRoot = null;
+  // 全局输出收集器（2026-10-21-protocol-tax FR-03）：--out-file <路径> / --tail N
+  let outFileRedirect = null;
+  let outFileTailLines = null;
   const filteredArgs = [];
 
   for (let i = 0; i < args.length; i++) {
@@ -305,6 +349,13 @@ async function main() {
       platformRuntimeRoot = resolve(args[i + 1]);
       filteredArgs.push(args[i], args[i + 1]);
       i++;
+    } else if (args[i] === '--out-file' && args[i + 1] && !args[i + 1].startsWith('--')) {
+      // 全局输出收集器（2026-10-21-protocol-tax FR-03）：全文落文件、stdout 只回尾 N 行
+      outFileRedirect = resolve(args[i + 1]);
+      i++;
+    } else if (args[i] === '--tail' && args[i + 1] && /^\d+$/.test(args[i + 1]) && parseInt(args[i + 1], 10) > 0) {
+      outFileTailLines = parseInt(args[i + 1], 10);
+      i++;
     } else if (args[i] === '--interactive' || args[i] === '-i') {
       interactive = true;
     } else if (args[i] === '--allow-worktree-cwd') {
@@ -324,6 +375,13 @@ async function main() {
     process.exit(2);
   }
 
+  // --out-file/--tail 校验与安装（2026-10-21-protocol-tax FR-03）：必须在任何命令输出之前装好
+  if (outFileTailLines !== null && outFileRedirect === null) {
+    console.error('❌ --tail 需与 --out-file 同用（控制 --out-file 模式下 stdout 尾部行数，默认 40）。');
+    process.exit(2);
+  }
+  if (outFileRedirect) installOutFileRedirect(outFileRedirect, outFileTailLines ?? 40);
+
   // ── 旧布局迁移（2026-10-18 runtime-relayout）：per-change 散文件入 state/、可删产物入 temp/。
   // 每次入口跑一遍（幂等：已收敛后 readdir 一轮零写入）；fail-open 绝不阻断命令。
   // init 除外——目标仓尚无 .sillyspec 可迁。resolveEffectiveDir 是函数声明（提升后可调）。
@@ -1683,12 +1741,18 @@ task done 四合一（r5l 方案1）：review write（落 review.json+自动勾
       const rdStage = rdStageIdx >= 0 && args[rdStageIdx + 1] && !String(args[rdStageIdx + 1]).startsWith("--") ? args[rdStageIdx + 1] : null;
       const rdStatus = args.includes('--status');
       const rdKill = args.includes('--kill');
+      const rdSalvage = args.includes('--salvage');
       const rdMode = rdKill ? 'kill' : rdStatus ? 'status' : 'create';
-      const rdUsage = '用法: sillyspec review-dispatch --change <名> --stage <brainstorm|plan|execute> [--status] [--kill]\n' +
+      const rdUsage = '用法: sillyspec review-dispatch --change <名> --stage <brainstorm|plan|execute> [--status] [--kill] [--status --salvage]\n' +
         '  缺省=派发（probe 前置→create_mission(external)→dispatch_worker(read_only)，异步返回 missionId）\n' +
         '  --status=轮询状态+停滞提示；worker completed 自动回收落盘 review.json（reviewer.channel=platform）\n' +
+        '  --status --salvage=终态原文兜底：worker-answer.md 落盘 + register-stage-review --from 回收指引（提取失败时用）\n' +
         '  --kill=清本地在途记录+平台处置指引（不自动 kill，处置权在人）';
       if (!rdChange) { console.error(rdUsage); process.exit(2); }
+      if (rdSalvage && !rdStatus) {
+        console.error(`❌ --salvage 仅与 --status 组合使用（completed 提取失败后的终态原文兜底回收）\n${rdUsage}`);
+        process.exit(2);
+      }
       assertSafeChangeName(rdChange, '--change 变更名');
       if (rdMode === 'create' && !['brainstorm', 'plan', 'execute'].includes(rdStage)) {
         console.error(`❌ create 形态必须 --stage ∈ brainstorm|plan|execute（实际：${rdStage || '缺'}）\n${rdUsage}`);
@@ -1706,7 +1770,7 @@ task done 四合一（r5l 方案1）：review write（落 review.json+自动勾
       const rdSpecBase = resolvePlatformSpecDir(dir, specDir);
       const r = await runReviewDispatch({
         mode: rdMode, cwd: dir, specBase: rdSpecBase, changeName: rdChange, stage: rdStage,
-        client: rdClient, budgetUsd: rdCfg.budget_usd, stallMs: rdCfg.stall_ms,
+        client: rdClient, budgetUsd: rdCfg.budget_usd, stallMs: rdCfg.stall_ms, salvage: rdSalvage,
       });
       if (r.ok) {
         if (r.statusLine) console.log(`🛰️ ${r.statusLine}`);
@@ -1721,6 +1785,7 @@ task done 四合一（r5l 方案1）：review write（落 review.json+自动勾
       } else {
         console.error(`❌ review-dispatch（${rdMode}）: ${r.reason}`);
         if (r.statusLine) console.error(`   ${r.statusLine}`);
+        if (r.salvagePath) console.error(`   📄 worker 终态原文：${r.salvagePath}`);
         if (r.errors) for (const e of r.errors) console.error(`   - ${e}`);
         if (r.guidance) console.error(`   下一步：\n${r.guidance}`);
         process.exitCode = 1;
@@ -3264,8 +3329,13 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
       // 下行 pull：stage 命令（run/--done，含 archive）启动时拉一次（task-10 / D-009 / FR-04）
       // 不在每步 pull，仅低频边界点；未连接平台静默跳过
-      const { triggerPullActiveChange } = await import('./run/shared.js')
-      await triggerPullActiveChange(effectiveDir)
+      // 例外（2026-10-21-protocol-tax task-06 / FR-06）：status 只读查看不 pull——消费仓实测
+      // pull 占 status 6.3s 的大头（profile 71% idle 等网络）；本地 DB 是查看态事实源
+      //（progress show 同款语义——它从不 pull），新鲜度交给写命令与 daemon/bg-sync。
+      if (command !== 'status') {
+        const { triggerPullActiveChange } = await import('./run/shared.js')
+        await triggerPullActiveChange(effectiveDir)
+      }
       await runCommand(stageArgs, effectiveDir, specDir, { json })
       break
     }
@@ -5322,6 +5392,9 @@ SillySpec config — local.yaml 配置键速查
                                   git common-dir 主仓根；worktree 内 .sillyspec 是 checkout
                                   副本无此文件，cat 自动解析到主仓）
   sillyspec config cat --json     机读 JSON（dir/path/source/content；未找到退出 1）
+  sillyspec config known-failures list           列 known_failures 豁免键
+  sillyspec config known-failures add <key…>     增豁免键（行级手术保注释、原子写；坏 YAML 拒改）
+  sillyspec config known-failures remove <key…>  删豁免键（未命中静默忽略）
 
 说明:
   - 数据源：src/config-schema.js（唯一真相；reader 见各键「读取点」）
@@ -5363,11 +5436,30 @@ SillySpec config — local.yaml 配置键速查
         if (!content.endsWith('\n')) process.stdout.write('\n')
         break;
       }
+      // config known-failures（2026-10-21-p0-p1-hardening FR-07 / dsh z2 实证：known_failures
+      // 无 CLI 管理面 → agent 手改 local.yaml，PS5.1 编码把 50KB 文件写成 mojibake 等用户
+      // 2h13m）。行级增删查：保注释、原子写、坏 YAML 拒改——消灭手改场景。
+      if (configSub === 'known-failures') {
+        let specBase = null
+        try { specBase = resolvePlatformSpecDir(dir, specDir) } catch { /* 同 cat：pointer 异常走祖先链 */ }
+        const { resolveLocalYaml } = await import('./config-cat.js')
+        const located = resolveLocalYaml(dir, { specBase })
+        const { runKnownFailuresCommand } = await import('./config-known-failures.js')
+        const verb = filteredArgs[2];
+        const keys = filteredArgs.slice(3).filter((a) => a && !a.startsWith('--'));
+        const exitCode = runKnownFailuresCommand({
+          yamlPath: located.exists ? located.path : join(dir, '.sillyspec', 'local.yaml'),
+          exists: located.exists,
+          verb, keys, json,
+        });
+        process.exitCode = exitCode;
+        break;
+      }
       if (!isSchema) {
-        const sug = didYouMean(configSub, ['schema', 'cat']);
+        const sug = didYouMean(configSub, ['schema', 'cat', 'known-failures']);
         console.error(`❌ 未知子命令: config ${configSub}`);
         if (sug) console.error(`   你是想输入「config ${sug}」吗？`);
-        console.error('用法: sillyspec config [schema|cat] [--json]   打印 local.yaml 配置键 / 读取实际内容');
+        console.error('用法: sillyspec config [schema|cat|known-failures] [--json]   打印配置键 / 读内容 / 管理 known_failures 键');
         process.exit(2);
       }
       const { renderSchemaHuman, renderSchemaJson } = await import('./config-schema.js');

package/src/knowledge-graph.js

@@ -18,10 +18,11 @@
  * 模块域内解析（沿 fr-index renderFrLines / module-changelog 行形态的机械契约）。
  */
 
-import { existsSync, readFileSync, readdirSync } from 'fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
 import { parseKnowledgeIndex, parseDecisionEntries, anchorFilePaths } from './knowledge-match.js'
 import { modulePathMatches, parseModuleMapSimple } from './modules.js'
+import { readHotCache, writeHotCache, dirStamp, fileDirStamp } from './hot-cache.js'
 
 // ── 本体常量（design.md 总体方案 §1 的代码化） ──
 
@@ -60,7 +61,7 @@ function extractFilePaths(text, cap = 15) {
 
 // ── 构建器 ──
 
-export function buildKnowledgeGraph(specRoot) {
+function buildKnowledgeGraphFresh(specRoot) {
   const nodes = new Map()
   const edges = []
   const byEdgeType = new Map()
@@ -340,6 +341,85 @@ export function buildKnowledgeGraph(specRoot) {
   return { root: specRoot, nodes, edges, byEdgeType, stats }
 }
 
+// ── 跨进程缓存（FR-03，2026-10-21-knowledge-tier-denoise）──
+// 图召回是四层检索的第三层 advisory 保底（fail-soft）；构建成本随归档线性（逐变更读
+// design.md+change-patch.json），flow start/知识门/doctor 热路径上无缓存重付。D-003 墓碑
+// 切割原则不变：md/yaml 仍是唯一真相源——缓存只存派生图、键在输入指纹上，不构成第二
+// 真相源；任何失配全量重建。
+// 陈旧边界（有意接受）：指纹感知本目录文件级变化与目录增删，但 docs 树深层就地重写若
+// 未触及被 stat 的文件面则漏——TTL 10min 硬上限兜底，advisory 面有界陈旧可接受。
+
+const GRAPH_CACHE_VERSION = 1
+const GRAPH_CACHE_TTL_MS = 10 * 60 * 1000
+
+function statSignature(p) {
+  try { const s = statSync(p); return `${s.mtimeMs}:${s.size}` } catch { return null }
+}
+
+/** 输入面指纹：knowledge（INDEX+decisions+fr）＋ docs 各项目（modules+scan 文件级）＋
+ *  归档根（dirStamp）＋ quicklog test-bindings。键序固定、数组排序——JSON 稳定比较。
+ *  各面缺席记 null（合法形态：无 docs/ 的小仓、无 fr 库）——缺席本身是指纹的一部分。 */
+function knowledgeGraphFingerprint(specRoot) {
+  const knowledgeDir = join(specRoot, 'knowledge')
+  const docsDir = join(specRoot, 'docs')
+  let projects = []
+  try {
+    projects = readdirSync(docsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((d) => [
+        d.name,
+        fileDirStamp(join(docsDir, d.name, 'modules')),
+        fileDirStamp(join(docsDir, d.name, 'scan')),
+      ])
+  } catch { /* docs/ 缺席 = 无项目面（合法形态）*/ }
+  return {
+    index: statSignature(join(knowledgeDir, 'INDEX.md')),
+    decisions: fileDirStamp(join(knowledgeDir, 'decisions')),
+    fr: fileDirStamp(join(knowledgeDir, 'fr')),
+    projects,
+    archive: dirStamp(join(specRoot, 'changes', 'archive')),
+    testBindings: statSignature(join(specRoot, 'quicklog', 'test-bindings.json')),
+  }
+}
+
+/** 缓存载荷 → 图对象（nodes Map 按 payload 序重建保迭代序一致；byEdgeType/stats 复算）。 */
+function reviveGraph(payload, specRoot) {
+  const nodes = new Map(payload.nodes.map((n) => [String(n.id), n]))
+  const edges = payload.edges.map((e) => ({ s: String(e.s), t: String(e.t), type: e.type, note: String(e.note || '') }))
+  const byEdgeType = new Map()
+  for (const e of edges) {
+    if (!byEdgeType.has(e.type)) byEdgeType.set(e.type, [])
+    byEdgeType.get(e.type).push(e)
+  }
+  const stats = {
+    nodeCount: nodes.size,
+    edgeCount: edges.length,
+    byNodeType: [...nodes.values()].reduce((a, n) => (a[n.type] = (a[n.type] || 0) + 1, a), {}),
+    byEdgeType: edges.reduce((a, e) => (a[e.type] = (a[e.type] || 0) + 1, a), {}),
+  }
+  return { root: payload.root || specRoot, nodes, edges, byEdgeType, stats }
+}
+
+/** 构建入口（缓存包装，签名与返回结构不变）：指纹+TTL+版本键三闸，命中零全量重扫。 */
+export function buildKnowledgeGraph(specRoot) {
+  const fingerprint = knowledgeGraphFingerprint(specRoot)
+  const cachePath = join(specRoot, '.runtime', 'cache', 'knowledge-graph.json')
+  if (fingerprint) {
+    const cached = readHotCache(cachePath, { version: GRAPH_CACHE_VERSION, fingerprint, ttlMs: GRAPH_CACHE_TTL_MS })
+    if (cached && Array.isArray(cached.nodes) && Array.isArray(cached.edges)) return reviveGraph(cached, specRoot)
+  }
+  const graph = buildKnowledgeGraphFresh(specRoot)
+  if (fingerprint) {
+    writeHotCache(cachePath, {
+      version: GRAPH_CACHE_VERSION,
+      fingerprint,
+      payload: { root: graph.root, nodes: [...graph.nodes.values()], edges: graph.edges },
+    })
+  }
+  return graph
+}
+
 /** changelog 三态行解析（表格行 ∪ 列表行 ∪ 标题态——backend 侧主形态；坏行跳过 fail-soft）。 */
 export function parseChangelogEntries(content) {
   const out = []

package/src/knowledge-match.js

@@ -292,6 +292,16 @@ function asciiWordHit(sh, text) {
   return new RegExp(`(^|[^a-z0-9-])${sh.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')}([^a-z0-9-]|$)`, 'i').test(text)
 }
 
+/** 停车场文件（未归类 unmapped 域——decisions 与 fr 两面）：检索核心零返回，文件本身
+ *  保留在盘上供人工直查（search 面以 parkingFiltered 披露指路）。2026-10-21-knowledge-tier-denoise
+ *  FR-01，对齐 FR 注入面 2026-09-29-rot-retire-inject-cap 的 unmapped 过滤口径（停车场非行为域）。 */
+const PARKING_FILES = new Set(['decisions/unmapped.md', 'fr/unmapped.md'])
+
+/** file 是否停车场文件（decisions/fr unmapped；Windows 反斜杠归一后判等）。 */
+export function isParkingFile(file) {
+  return PARKING_FILES.has(String(file || '').replace(/\\/g, '/'))
+}
+
 /**
  * 零命中查询侧词片回退（2026-09-29-decision-route-vocab）：路由行零命中时，只测「查询自己的
  * 词片」——逐 decisions 域文件数词片在条目文本（标题∪理由）的出现次数，落在「跨条目复现但
@@ -309,6 +319,7 @@ export function fallbackByQueryShingles(indexDir, taskContext) {
   if (all.length === 0) return null
   const byFile = new Map()
   for (const h of all) {
+    if (isParkingFile(h.file)) continue // 停车场文件不参与词片回退（FR-01）
     let st = byFile.get(h.file)
     if (!st) { st = { entries: [], texts: [] }; byFile.set(h.file, st) }
     st.entries.push(h)
@@ -395,16 +406,21 @@ export function matchByRouting(indexDir, taskContext) {
   }
 
   const contextLower = taskContext.toLowerCase()
-  const matched = allEntries.filter(entry => {
+  const matchedRaw = allEntries.filter(entry => {
     return entry.keywords.some(kw => keywordMatchesContext(kw, contextLower))
   })
+  // 停车场过滤（FR-01，2026-10-21-knowledge-tier-denoise）：unmapped 路由行不进命中集；
+  // 只命中停车场行 → 按零命中处理（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))
 
   if (matched.length === 0) {
     return {
       matched: false,
       entries: [],
       report: 'Status: no matches',
-      json: { matched: false, entry_count: 0, entries: [] },
+      json: { matched: false, entry_count: 0, entries: [], ...(parkingFiltered.length > 0 ? { parkingFiltered } : {}) },
       decisionHits: []
     }
   }

package/src/knowledge-quicklog.js

@@ -19,6 +19,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
+import { readHotCache, writeHotCache, dirStamp } from './hot-cache.js'
 
 const QUICKLOG_ENTRY_RE = /^##\s+(ql-[\w-]+)\s*\|\s*([^|]+)\s*\|\s*(.+)$/
 // 文件注记行：`- path（中文括注）` / `- path(ascii)` / 裸 `- path`（allocateQuicklogEntry
@@ -95,10 +96,23 @@ function parseQuicklogFileEntries(specBase) {
   return entries
 }
 
+/** 伪条目扫描缓存版本（解析契约变化时 bump 即全量失效）。 */
+const FLOW_ARCHIVE_CACHE_VERSION = 1
+
 /** 源②：flow 归档变更伪条目——目录内 flow-state.yaml 在场即认（不校验 yaml 内容：伪条目
- * 只需「这曾是一个 flow 变更」的存在信号，字段全来自目录名与 proposal.md，缺件逐项降级）。 */
-function parseFlowArchiveEntries(specBase) {
+ * 只需「这曾是一个 flow 变更」的存在信号，字段全来自目录名与 proposal.md，缺件逐项降级）。
+ * 跨进程缓存（FR-03，2026-10-21-knowledge-tier-denoise）：指纹=归档根子项名全集+根 mtimeMs
+ * （一次 readdir+一次 stat，廉价每次重算）——命中即免逐目录列举与逐变更 proposal.md 读。
+ * 归档件是冻结审计面（无就地编辑形态），指纹对增删/改名完备；坏缓存/失配 fail-open 全量重建。
+ * 导出供测试断言缓存三态（命中/失效/坏缓存）。 */
+export function parseFlowArchiveEntries(specBase) {
   const archiveDir = join(specBase, 'changes', 'archive')
+  const fingerprint = dirStamp(archiveDir)
+  if (fingerprint === null) return []
+  const cachePath = join(specBase, '.runtime', 'cache', 'quicklog-archive-entries.json')
+  const cached = readHotCache(cachePath, { version: FLOW_ARCHIVE_CACHE_VERSION, fingerprint })
+  if (Array.isArray(cached)) return cached
+
   let dirs
   try {
     dirs = readdirSync(archiveDir, { withFileTypes: true })
@@ -125,6 +139,7 @@ function parseFlowArchiveEntries(specBase) {
       out.push({ qlId: d.name, date, title: title || d.name, solution: '', files: [], source: 'flow' })
     } catch { /* 单目录读取异常 → 跳过该目录（fail-open，不影响其余源） */ }
   }
+  writeHotCache(cachePath, { version: FLOW_ARCHIVE_CACHE_VERSION, fingerprint, payload: out })
   return out
 }
 

package/src/knowledge-vector.js

@@ -38,7 +38,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { runtimeStatePath } from './runtime-paths.js'
 import { join, dirname } from 'path'
 import { readPlatformConfig } from './sync.js'
-import { matchByRouting, fallbackByQueryShingles, parseDecisionEntries } from './knowledge-match.js'
+import { matchByRouting, fallbackByQueryShingles, parseDecisionEntries, isParkingFile } from './knowledge-match.js'
 
 const VECTOR_TIMEOUT_MS = 3000
 const ENDPOINT_PATH = '/api/spec/knowledge/vector-search'
@@ -181,12 +181,14 @@ function specPathToFile(specPath) {
   return String(specPath).replace(/^knowledge\//, '').replace(/\\/g, '/')
 }
 
-/** 平台候选 → matchKnowledge 同构结果（策略面全本地解析）。 */
-function buildResultFromPlatform(indexDir, pvResults) {
+/** 平台候选 → matchKnowledge 同构结果（策略面全本地解析）。导出供测试（FR-01 停车场
+ *  候选丢弃断言；策略面全在本地解析的契约不变）。 */
+export 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 (isParkingFile(file)) continue // 停车场候选丢弃（FR-01）——平台向量语料含 unmapped，策略面本地滤
     if (!byFile.has(file)) byFile.set(file, [])
     byFile.get(file).push(r)
   }