sillyspec 3.28.12 → 3.28.13

package/src/decision-distill.js

@@ -211,8 +211,9 @@ function parseModulePathsSubset(content) {
 /** 未注入 moduleIndex 时的尽力发现：knowledgeRoot 同级 docs/<项目>/modules/_module-map.yaml。
  * 多子项目仓（如本仓 sillyspec+dashboard）各项目有自己的 map——dogfood 实证（2026-08-24）：
  * 只取首个命中会把主项目条目全部误落 unmapped（dashboard 的 map 按字母序先命中）。
- * 改为合并全部项目的 map（同名模块合并 paths/core_files 去重），失败归 null → 全部 unmapped。 */
-function discoverModuleIndex(knowledgeRoot) {
+ * 改为合并全部项目的 map（同名模块合并 paths/core_files 去重），失败归 null → 全部 unmapped。
+ * 2026-09-18-fr-index-l1：导出供 fr-index 域解析复用。 */
+export function discoverModuleIndex(knowledgeRoot) {
   try {
     const docsDir = join(dirname(knowledgeRoot), 'docs')
     if (!existsSync(docsDir)) return null
@@ -319,15 +320,19 @@ function renderBlockLines(entry, headHash, supersedesNote, changeName) {
   return lines
 }
 
-/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头）。
+/** 知识文件切段：preamble 行 + 条目段（段边界 = 下一节头）。
  * 段的变更归属取段内 `变更：<name>` 行；无该行的历史条目 → change=null（legacy：
- * 升级前落库的条目，不参与新条目的同号匹配/supersede——只共存不误删）。 */
-function splitKnowledgeSections(content) {
+ * 升级前落库的条目，不参与新条目的同号匹配/supersede——只共存不误删）。
+ * 2026-09-18-fr-index-l1 参数化：sectionRegex/buildId 经参（decisions 缺省不变；fr 侧传 FR 节头
+ * 正则与恒等 id），decisions 调用点零改动。 */
+export function splitKnowledgeSections(content, opts = {}) {
+  const sectionRegex = opts.sectionRegex || /^## (D-\d+)@v(\d+)\s*(.*)$/
+  const buildId = opts.buildId || ((n, v) => `${n}@v${v}`)
   const sections = []
   const preamble = []
   let cur = null
   for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
-    const m = line.match(/^## (D-\d+)@v(\d+)\s*(.*)$/)
+    const m = line.match(sectionRegex)
     if (m) {
       if (cur) sections.push(cur)
       cur = { number: m[1], version: parseInt(m[2], 10), title: m[3].trim(), lines: [line] }
@@ -338,7 +343,7 @@ function splitKnowledgeSections(content) {
   }
   if (cur) sections.push(cur)
   for (const s of sections) {
-    s.id = `${s.number}@v${s.version}`
+    s.id = buildId(s.number, s.version)
     const cm = s.lines.find(l => /^变更[：:]/.test(l))
     s.change = cm ? cm.replace(/^变更[：:]\s*/, '').trim() || null : null
   }
@@ -346,7 +351,7 @@ function splitKnowledgeSections(content) {
 }
 
 /** 段落重组落盘文本（幂等归一：段间恰好一个空行 + 文件单一尾换行） */
-function joinKnowledgeFile(preamble, sections) {
+export function joinKnowledgeFile(preamble, sections) {
   const parts = []
   const pre = preamble.join('\n').replace(/\s+$/, '')
   if (pre) parts.push(pre)
@@ -394,19 +399,21 @@ function applyEntryToSections(sections, entry, headHash) {
 // INDEX.md decisions 路由行幂等维护（FR-05：写入责任在本模块；只动 ## Decisions 段内指向 decisions/ 的行）
 // ---------------------------------------------------------------------------
 
-/** INDEX 路由行格式与 knowledge-match 解析口径一致：`- <域>|decision|决策 → [decisions/<域>.md](decisions/<域>.md)` */
-function routingLine(domain) {
-  return `- ${domain}|decision|决策 → [decisions/${domain}.md](decisions/${domain}.md)`
-}
-
-const ROUTING_TARGET_RE = /^-\s+.*→\s*\[[^\]]*\]\(decisions\/([^)#]+?)(?:\.md)?(?:#[^)]*)?\)\s*$/
-
-/** 域文件实况 ↔ ## Decisions 段路由行对账：缺行补、失效行删、重复行去重；不动其他类别行 */
-function syncIndexRoutingLines(knowledgeRoot) {
-  const decisionsDir = join(knowledgeRoot, 'decisions')
+/**
+ * 域文件实况 ↔ INDEX 段路由行对账：缺行补、失效行删、重复行去重；不动其他类别行。
+ * 2026-09-18-fr-index-l1 参数化：section/subdir/makeLine/matchTarget 经参（decisions 缺省不变），
+ * fr 侧传 'FR 需求索引' 段与 fr/ 子目录——两类路由行各守各段互不干扰。
+ */
+export function syncIndexRoutingLines(knowledgeRoot, opts = {}) {
+  const sectionName = opts.section || 'Decisions'
+  const subdir = opts.subdir || 'decisions'
+  const makeLine = opts.makeLine || ((d) => `- ${d}|decision|决策 → [${subdir}/${d}.md](${subdir}/${d}.md)`)
+  const esc = subdir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const targetRe = opts.matchTarget || new RegExp(`^-\\s+.*→\\s*\\[[^\\]]*\\]\\(${esc}/([^)#]+?)(?:\\.md)?(?:#[^)]*)?\\)\\s*$`)
+  const domainDir = join(knowledgeRoot, subdir)
   let domains
   try {
-    domains = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
+    domains = readdirSync(domainDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
   } catch { return false }
   if (domains.length === 0) return false
 
@@ -417,29 +424,29 @@ function syncIndexRoutingLines(knowledgeRoot) {
   }
   const lines = original ? original.replace(/\r\n/g, '\n').split('\n') : ['# Knowledge Index', '']
 
-  // 定位 ## Decisions 段边界
+  // 定位段边界（参数化段名）
   let secStart = -1
   let secEnd = lines.length
   for (let i = 0; i < lines.length; i++) {
     const h = lines[i].match(/^##\s+(.+?)\s*$/)
     if (!h) continue
     if (secStart === -1) {
-      if (h[1] === 'Decisions') secStart = i + 1
+      if (h[1] === sectionName) secStart = i + 1
     } else { secEnd = i; break }
   }
 
-  const desired = domains.map(routingLine)
+  const desired = domains.map(makeLine)
   if (secStart === -1) {
     // 无段则追加（保留原文件其余内容）
     while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
-    lines.push('', '## Decisions', ...desired)
+    lines.push('', `## ${sectionName}`, ...desired)
   } else {
     const body = lines.slice(secStart, secEnd)
     const kept = []
     const seen = new Set()
     const domainSet = new Set(domains)
     for (const l of body) {
-      const m = l.match(ROUTING_TARGET_RE)
+      const m = l.match(targetRe)
       if (!m) { kept.push(l); continue } // 非路由行（注释/空行）原样保留
       // 目标域文件仍存在的路由行原样保留（关键词可能被人工扩充）；失效行（文件已不存在）与重复行删
       if (domainSet.has(m[1]) && !seen.has(m[1])) { seen.add(m[1]); kept.push(l) }
@@ -448,7 +455,7 @@ function syncIndexRoutingLines(knowledgeRoot) {
     const tail = []
     while (kept.length > 0 && kept[kept.length - 1].trim() === '') tail.unshift(kept.pop())
     for (const d of desired) {
-      const m = d.match(ROUTING_TARGET_RE)
+      const m = d.match(targetRe)
       if (m && !seen.has(m[1])) kept.push(d) // 缺行补
     }
     kept.push(...tail)

package/src/doctor-diagnostics.js

@@ -33,6 +33,9 @@ import { pruneTimestampedEntries } from './runtime-hygiene.js';
 import { CHECK_SEVERITY } from './constants.js';
 import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME, QUICK_SID_RE, resolveRuntimeRoot } from './run/shared.js';
 import { readFrictionLedger } from './friction-ledger.js';
+// FR 索引消费（2026-09-18-fr-index-l1 L1，D-007）：D14 第四检查——epoch 后归档的索引在场+取代完整。
+// fr-index 是纯 fs 叶子链（仅 decision-distill 底座），doctor 静态引入无环。
+import { FR_INDEX_EPOCH, scanFrIndex, parseChangeRequirements } from './fr-index.js';
 
 // db 角色标签
 const DB_ROLE = {
@@ -1162,6 +1165,10 @@ function detectArchiveIntegrity(cwd, authoritySpecDir) {
     return { ...base, pass: true, severity: null, findings: ['changes/archive 为空（无已归档变更）'], archive_count: 0, offenders: [] };
   }
   const offenders = [];
+  // FR 索引面（D14 第四检查数据源，循环外一次扫描复用；fr/ 不存在=仓未启用，全跳不误报）
+  const frKnowledgeRoot = join(authoritySpecDir, 'knowledge');
+  const frEnabled = existsSync(join(frKnowledgeRoot, 'fr'));
+  const frEntries = frEnabled ? scanFrIndex(frKnowledgeRoot) : [];
   for (const name of names) {
     const dir = join(archiveDir, name);
     const reasons = [];
@@ -1204,6 +1211,28 @@ function detectArchiveIntegrity(cwd, authoritySpecDir) {
         reasons.push(`任务注册表不可读（${relative(archiveDir, regPath)}：${e?.code || e?.message || e}）`);
       }
     }
+    // ── ④ FR 索引在场与取代完整（2026-09-18-fr-index-l1 L1，D-007：epoch 分界第四检查）──
+    // 豁免面：fr/ 目录不存在（仓未启用索引，全跳）；无日期前缀/epoch 前归档（存量不回填）；
+    // quick-* 与无 requirements.md（quick/scale:small 无索引义务）。违者并入 offenders（豁免走既有账本）。
+    if (frEnabled) {
+      const dm = name.match(/^(\d{4}-\d{2}-\d{2})-/);
+      if (dm && dm[1] >= FR_INDEX_EPOCH && existsSync(join(dir, 'requirements.md'))) {
+        if (!frEntries.some((e) => e.change === name)) {
+          reasons.push('FR 索引缺失（epoch 后归档应有索引条目——归档时 indexRequirements 未落，查 archive 步降级日志）');
+        } else {
+          try {
+            const reqParsed = parseChangeRequirements(dir);
+            const refIds = new Set();
+            for (const fr of reqParsed.frs) for (const r of fr.supersedes) refIds.add(r);
+            for (const refId of refIds) {
+              if (!frEntries.some((e) => e.id === refId && e.supersededBy)) {
+                reasons.push(`承接未翻取代（${refId} 被引用但索引中未标 superseded）`);
+              }
+            }
+          } catch { /* requirements 解析失败归任务注册表口径，此处不重复报 */ }
+        }
+      }
+    }
     if (reasons.length > 0) offenders.push({ name, reasons });
   }
 

package/src/fr-index.js

@@ -0,0 +1,359 @@
+/**
+ * fr-index.js — FR 稳定索引核心（L1：稳定 id + knowledge 索引 + 取代标记）
+ *
+ * 2026-09-18-fr-index-l1（三轮评审+战略定位定稿）：requirements.md 归档后首次被语义消费——
+ * 全局稳定 id（FR-<域>-NNN，archive 时 CLI 发号）+ knowledge/fr/<域>.md 索引 + 承接引用驱动的
+ * 取代链。定位=**L3 的证据发生器**：四类遥测事件（fr-inject/fr-supersede/fr-duplicate-warning/
+ * fr-unreferenced，由消费方经 knowledge-hits.js 落盘）供 20-30 change 后裁决活规格真源——
+ * 含证伪出口（design 实验裁决条款：承接引用率趋零/链无人跟/重复靠人眼 ⇒ 可杀可冻 L3，索引降级检索面）。
+ *
+ * 纪律：
+ *   - CLI 单一写入方：索引只在 indexRequirements 内部写（archive noAI 步调用）；
+ *   - 幂等键=全局 id（「来源变更」字段变更名命中即 no-op——同变更重跑零新增零漂移）；
+ *   - 承接 id 不存在 → warnings 收集不阻断（typo 不炸归档）；
+ *   - 未引用旧 FR 的删除/修改零判定（D-002 边界——undeclared deletion 是 L3 合并门禁领地，
+ *     L1 只经 unreferenced 计数采观察信号，显式「不算 L3 门禁」）；
+ *   - 域文件读写复用 decision-distill 参数化底座（splitKnowledgeSections/joinKnowledgeFile/
+ *     syncIndexRoutingLines/discoverModuleIndex），不复制实现。
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  splitKnowledgeSections,
+  joinKnowledgeFile,
+  syncIndexRoutingLines,
+  discoverModuleIndex,
+} from './decision-distill.js';
+
+/** epoch：此前归档不检查/不索引（存量 93 份不回填——不伪造历史，D-007）。 */
+export const FR_INDEX_EPOCH = '2026-09-18';
+
+const FR_DIR = 'fr';
+/** FR 节头：## FR-<域>-NNN 标题（域=[a-z0-9-] **含连字符**——真实模块 id 多为 cli-entry/core-engine 等连字符形态，
+ *  R1 审查阻断①实证：漏 - 会让连字符域的发号/幂等/解析/承接全断。第二组为非捕获可选占位，
+ *  三组结构与底座 splitKnowledgeSections 的 decisions 正则对齐（m[3]=标题，勿改组序）。 */
+const FR_SECTION_RE = /^## (FR-[a-z0-9-]+-\d+)(?:@v(\d+))?\s*(.*)$/;
+const FR_GLOBAL_ID_RE = /^FR-[a-z0-9-]+-\d+$/;
+
+/**
+ * 解析变更 requirements.md 的 FR 块。
+ * 形态（brainstorm step8 指引）：`### FR-NN: 标题` + 可选 `承接: FR-<域>-NNN[, ...]` 行 +
+ * Given/When/Then 块（场景名取 `#### 场景：X` 或 `**场景：X**` 行；无场景名的 GWT 块按序号占位）。
+ * @returns {{ missing: boolean, frs: Array<{local:string,title:string,supersedes:string[],scenarios:string[]}>, malformed: string[] }}
+ */
+export function parseChangeRequirements(changeDir) {
+  const p = join(changeDir, 'requirements.md');
+  if (!existsSync(p)) return { missing: true, frs: [], malformed: [] };
+  let content;
+  try {
+    content = readFileSync(p, 'utf8');
+  } catch {
+    return { missing: true, frs: [], malformed: [] };
+  }
+  const frs = [];
+  const malformed = [];
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+  let cur = null;
+  for (const line of lines) {
+    const h = line.match(/^###\s+(FR-\d+)\s*[:：]\s*(.*)$/);
+    if (h) {
+      if (cur) frs.push(cur);
+      cur = { local: h[1], title: (h[2] || '').trim(), supersedes: [], scenarios: [] };
+      continue;
+    }
+    if (!cur) continue;
+    const s = line.match(/^\s*承接\s*[:：]\s*(.+)$/);
+    if (s) {
+      for (const tok of s[1].split(/[,，、]/)) {
+        const id = tok.trim();
+        if (!id) continue;
+        if (FR_GLOBAL_ID_RE.test(id)) cur.supersedes.push(id);
+        else malformed.push(`${cur.local} 的承接行含非全局 id 形态「${id}」（应为 FR-<域>-NNN）`);
+      }
+      continue;
+    }
+    const sc = line.match(/^\s*(?:#{2,4}\s*场景\s*[:：]\s*(.+)|\*\*场景\s*[:：]\s*([^*]+)\*\*)\s*$/);
+    if (sc) {
+      const name = ((sc[1] || sc[2] || '')).trim();
+      cur.scenarios.push(name || `场景${cur.scenarios.length + 1}`);
+    }
+  }
+  if (cur) frs.push(cur);
+  return { missing: false, frs, malformed };
+}
+
+/** 域解析（导出供注入/软门消费）：变更自身 design.md 文件变更清单表行（剥 NEW: 前缀）× moduleIndex paths 前缀匹配；无匹配 → unmapped。 */
+export function resolveTouchedDomains(changeDir, moduleIndex) {
+  const domains = new Set();
+  const designPath = join(changeDir, 'design.md');
+  if (moduleIndex && existsSync(designPath)) {
+    let design;
+    try {
+      design = readFileSync(designPath, 'utf8');
+    } catch {
+      design = '';
+    }
+    for (const line of design.replace(/\r\n/g, '\n').split('\n')) {
+      const m = line.match(/^\|\s*(?:新增|修改|删除)\s*\|\s*(?:NEW:)?([^\s|]+)\s*\|/);
+      if (!m) continue;
+      const filePath = m[1].trim();
+      for (const [modId, mod] of Object.entries(moduleIndex)) {
+        const paths = (mod && Array.isArray(mod.paths)) ? mod.paths : [];
+        if (paths.some((pp) => filePath === pp || filePath.startsWith(pp.endsWith('/') ? pp : pp + '/'))) {
+          domains.add(modId);
+        }
+      }
+    }
+  }
+  if (domains.size === 0) domains.add('unmapped');
+  return [...domains];
+}
+
+/** 域文件路径与域索引读写（复用参数化底座；FR 节无版本段，id 恒等）。 */
+function frDirPath(knowledgeRoot) {
+  return join(knowledgeRoot, FR_DIR);
+}
+
+function loadDomainSections(knowledgeRoot, domain) {
+  const p = join(frDirPath(knowledgeRoot), `${domain}.md`);
+  if (!existsSync(p)) {
+    return {
+      preamble: [
+        '---',
+        `author: sillyspec-fr-index`,
+        `created_at: ${new Date().toISOString()}`,
+        '---',
+        '',
+        `# FR 索引 — ${domain}`,
+        '',
+        '> fr-index 从归档变更 requirements.md 幂等提炼（「最近确认」= 归档时 HEAD）。条目字段行为机械解析契约，勿手改。',
+        '> superseded 条目保留供取代链回溯；brainstorm 注入默认只给 active。',
+        '',
+      ],
+      sections: [],
+    };
+  }
+  try {
+    return splitKnowledgeSections(readFileSync(p, 'utf8'), {
+      sectionRegex: FR_SECTION_RE,
+      buildId: (n) => n,
+    });
+  } catch {
+    return { preamble: [], sections: [] };
+  }
+}
+
+function renderFrLines(entry, headHash) {
+  const lines = [`## ${entry.id} ${entry.title}`];
+  // 归属行键用「变更：」——与 decision-distill splitKnowledgeSections 的机械解析契约对齐
+  // （design 接口定义示例中的「来源变更」即本字段，语义等价，取解析器认的字面）
+  lines.push(`变更：${entry.change}`);
+  lines.push(`状态：${entry.supersededBy ? 'superseded' : 'active'}`);
+  if (entry.supersededBy) lines.push(`superseded_by：${entry.supersededBy}`);
+  if (entry.supersededOf) lines.push(`取代链：${entry.supersededOf} ← 本条目（${entry.change} 承接）`);
+  lines.push(`摘要：${(entry.scenarios || []).slice(0, 5).join('；') || '（无场景名）'}`);
+  lines.push(`最近确认：${headHash || ''}`);
+  return lines;
+}
+
+/** 全域条目扫描：domain → sections（供发号取 max、承接翻链、在场性检查）。 */
+function scanAllDomains(knowledgeRoot) {
+  const out = new Map();
+  try {
+    for (const f of readdirSync(frDirPath(knowledgeRoot))) {
+      if (!f.endsWith('.md')) continue;
+      const domain = f.replace(/\.md$/, '');
+      out.set(domain, loadDomainSections(knowledgeRoot, domain));
+    }
+  } catch { /* 目录不存在 → 空索引 */ }
+  return out;
+}
+
+function nextIdForDomain(domain, allSections) {
+  let max = 0;
+  const re = new RegExp(`^FR-${domain.replace(/[-]/g, '-')}-(\\d+)$`);
+  for (const st of allSections.values()) {
+    for (const s of st.sections) {
+      const m = (s.number || '').match(re);
+      if (m) max = Math.max(max, parseInt(m[1], 10));
+    }
+  }
+  return `FR-${domain}-${String(max + 1).padStart(3, '0')}`;
+}
+
+/**
+ * 归档索引主入口（幂等）：解析 → 域解析 → 发号 → 承接翻链 → 写域文件 → INDEX 路由。
+ * @param {{ changeDir: string, knowledgeRoot: string, headHash?: string, cwd?: string }} args
+ * @returns {{ skipped?: string, written: Array<{file,id,action}>, superseded: Array<{from,to,change}>, unreferenced: Array<{domain,count}>, warnings: string[] }}
+ */
+export function indexRequirements({ changeDir, knowledgeRoot, headHash = '' }) {
+  const changeName = changeDir.split(/[\\/]/).pop();
+  const parsed = parseChangeRequirements(changeDir);
+  if (parsed.missing) {
+    return { skipped: 'requirements.md 不存在（quick/scale:small 无索引义务）', written: [], superseded: [], unreferenced: [], warnings: [] };
+  }
+  if (parsed.frs.length === 0) {
+    return { skipped: 'requirements.md 无 FR 块', written: [], superseded: [], unreferenced: [], warnings: [] };
+  }
+
+  const warnings = [...parsed.malformed];
+  const moduleIndex = discoverModuleIndex(knowledgeRoot);
+  const domains = resolveTouchedDomains(changeDir, moduleIndex);
+  const all = scanAllDomains(knowledgeRoot);
+
+  // 幂等闸门：任一域文件已有本变更「来源变更」条目 → 全量 no-op（同变更重跑零新增零漂移）
+  for (const st of all.values()) {
+    if (st.sections.some((s) => s.change === changeName)) {
+      return { written: [], superseded: [], unreferenced: [], warnings };
+    }
+  }
+
+  // 承接校验：引用的全局 id 必须在现有索引中存在（typo → warn 不阻断）
+  const knownIds = new Set();
+  for (const st of all.values()) for (const s of st.sections) knownIds.add(s.number);
+  const refIds = new Set();
+  for (const fr of parsed.frs) for (const id of fr.supersedes) refIds.add(id);
+  for (const id of refIds) {
+    if (!knownIds.has(id)) warnings.push(`承接引用的 ${id} 不在索引中（域拼错或号不存在）——该引用不翻链，请核对`);
+  }
+
+  // 发号 + 写入（每 FR 落其首个触达域；多域变更按域去重逐条落）
+  const written = [];
+  const superseded = [];
+  const perDomainCounter = new Map();
+  const ensureDomain = (domain) => {
+    if (!all.has(domain)) all.set(domain, loadDomainSections(knowledgeRoot, domain));
+    return all.get(domain);
+  };
+  // 发号与翻链：每条 FR 落**首个触达域**（primary domain）取一个全局 id——幂等键=全局 id 单一身份
+  // （R1 审查缺口：per-domain × per-FR 会给同一 FR 发 N 个 id，违背 D-001 单一身份）；
+  // 承接翻链可跨全域命中目标条目（新条目在 primary 域，旧条目可在任何域）。
+  const dirtyDomains = new Set();
+  const primaryDomain = domains[0];
+  const st = ensureDomain(primaryDomain);
+  for (const fr of parsed.frs) {
+    const id = nextIdForDomain(primaryDomain, all);
+    perDomainCounter.set(primaryDomain, (perDomainCounter.get(primaryDomain) || 0) + 1);
+    st.sections.push({
+      number: id,
+      version: NaN,
+      id,
+      title: fr.title,
+      change: changeName,
+      lines: renderFrLines({ id, title: fr.title, change: changeName, scenarios: fr.scenarios }, headHash),
+    });
+    dirtyDomains.add(primaryDomain);
+    written.push({ file: `${FR_DIR}/${primaryDomain}.md`, id, action: 'added' });
+    // 本 FR 的承接引用 → 翻旧条目（跨全域扫描目标段；就地补丁不动原摘要——R1 审查缺口：整段重写会抹掉摘要）
+    for (const refId of fr.supersedes) {
+      if (!knownIds.has(refId)) continue;
+      for (const [st2Domain, st2] of all.entries()) {
+        const target = st2.sections.find((s) => s.number === refId && !s.lines.some((l) => l.startsWith('superseded_by：')));
+        if (!target) continue;
+        // 就地补丁：状态翻 superseded + 插 superseded_by + 追取代链注记 + 刷新最近确认（摘要/标题保留）
+        target.lines = target.lines
+          .map((l) => (l.startsWith('状态：') ? `状态：superseded` : l.startsWith('最近确认：') ? `最近确认：${headHash || ''}` : l))
+          .filter((l) => !l.startsWith('superseded_by：') && !l.startsWith('取代链：'));
+        const stateIdx = target.lines.findIndex((l) => l.startsWith('状态：'));
+        target.lines.splice(stateIdx + 1, 0, `superseded_by：${id}`, `取代链：${refId} ← ${id}（${changeName} 承接）`);
+        dirtyDomains.add(st2Domain);
+        superseded.push({ from: refId, to: id, change: changeName });
+      }
+    }
+  }
+
+  // unreferenced 探针（D-008 护栏③）：触达域 active 条目未被本次承接引用的计数——观察信号，不算 L3 门禁
+  const unreferenced = [];
+  for (const domain of domains) {
+    const stx = all.get(domain);
+    if (!stx) continue;
+    const activeIds = stx.sections
+      .filter((s) => !s.lines.some((l) => l.startsWith('superseded_by：')))
+      .map((s) => s.number)
+      .filter((n) => n && !written.some((w) => w.id === n));
+    const count = activeIds.filter((id) => !refIds.has(id)).length;
+    if (count > 0) unreferenced.push({ domain, count });
+  }
+
+  // 落盘（dirty 集=新条目域 ∪ 翻链命中域——R1 审查阻断②：漏翻链域会返回值谎报成功但盘上丢失）
+  mkdirSync(frDirPath(knowledgeRoot), { recursive: true });
+  for (const d of dirtyDomains) {
+    const stx = all.get(d);
+    writeFileSync(join(frDirPath(knowledgeRoot), `${d}.md`), joinKnowledgeFile(stx.preamble, stx.sections));
+  }
+  if (written.length > 0 || superseded.length > 0) {
+    syncIndexRoutingLines(knowledgeRoot, {
+      section: 'FR 需求索引',
+      subdir: FR_DIR,
+      makeLine: (d) => `- ${d}|FR|需求|承接 → [${FR_DIR}/${d}.md](${FR_DIR}/${d}.md)`,
+    });
+  }
+
+  return { written, superseded, unreferenced, warnings };
+}
+
+/**
+ * 全量索引扫描（doctor D14 第四检查消费）：全部域的全部条目（含 superseded）拍平。
+ * @returns {Array<{domain,id,title,change,supersededBy:string|null}>} fr/ 目录不存在 → []
+ */
+export function scanFrIndex(knowledgeRoot) {
+  const out = [];
+  let files = [];
+  try {
+    files = readdirSync(frDirPath(knowledgeRoot)).filter((f) => f.endsWith('.md'));
+  } catch {
+    return out;
+  }
+  for (const f of files) {
+    const domain = f.replace(/\.md$/, '');
+    const st = loadDomainSections(knowledgeRoot, domain);
+    for (const s of st.sections) {
+      const sup = s.lines.find((l) => l.startsWith('superseded_by：'));
+      out.push({
+        domain,
+        id: s.number,
+        title: s.title || '',
+        change: s.change || '',
+        supersededBy: sup ? sup.replace(/^superseded_by：\s*/, '').trim() : null,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 注入源：触达域的 active 条目（superseded 默认藏——D-004）。
+ * @returns {Array<{domain,id,title,change,scenarios:string[]}>}
+ */
+export function readActiveFrDigest(knowledgeRoot, domains) {
+  const out = [];
+  for (const domain of domains || []) {
+    const st = loadDomainSections(knowledgeRoot, domain);
+    for (const s of st.sections) {
+      if (s.lines.some((l) => l.startsWith('superseded_by：'))) continue;
+      const scenarioLine = s.lines.find((l) => l.startsWith('摘要：'));
+      const scenarios = scenarioLine ? scenarioLine.replace(/^摘要：\s*/, '').split('；').map((x) => x.trim()).filter(Boolean) : [];
+      out.push({ domain, id: s.number, title: s.title || '', change: s.change || '', scenarios });
+    }
+  }
+  return out;
+}
+
+/**
+ * 标题 bigram 重叠率（中英混排零依赖）：字符 bigram 集合 |A∩B| / |A∪B|。
+ */
+export function frTitleOverlap(a, b) {
+  const grams = (s) => {
+    const t = String(s || '').replace(/\s+/g, '');
+    const set = new Set();
+    for (let i = 0; i < t.length - 1; i++) set.add(t.slice(i, i + 2));
+    return set;
+  };
+  const A = grams(a);
+  const B = grams(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const g of A) if (B.has(g)) inter++;
+  return inter / (A.size + B.size - inter);
+}

package/src/knowledge-stats.js

@@ -23,10 +23,11 @@
  * 「窗口内无命中」两种空矩阵——后者死重对照无意义，人类可读模式同样略过 neverHit 段）。
  */
 
-import { existsSync } from 'fs'
+import { existsSync, readdirSync } from 'fs'
 import { join } from 'path'
 import { readKnowledgeHits } from './knowledge-hits.js'
 import { parseKnowledgeIndex } from './knowledge-match.js'
+import { scanFrIndex } from './fr-index.js'
 
 // ── 聚合核心 ──
 
@@ -95,6 +96,85 @@ export function buildHitMatrix(knowledgeDir, runtimeDir, { sinceDays = 30 } = {}
   return { matrix, neverHit, totalInjects, totalClassifies }
 }
 
+// ── FR 索引实验聚合（2026-09-18-fr-index-l1 后续钩子·L3 裁决仪表盘）──
+
+/**
+ * 聚合 L1 四类 fr-* 遥测事件 + knowledge/fr/ 索引面统计——L3 裁决（design 实验证伪条款）
+ * 的出数面：观察期满一眼读出 注入命中/取代链跟随/重复拦截/删除缺口信号 与 承接引用率。
+ *
+ * 口径：
+ * - 事件面（jsonl，sinceDays 窗口）：fr-inject 计数+涉及变更数；fr-supersede 计数+涉及变更数；
+ *   fr-duplicate-warning 计数+命中候选数；fr-unreferenced 按域聚合 count 总和；
+ * - 索引面（knowledge/fr/*.md，全量——索引是累积账本非窗口流）：条目/active/superseded 计数、
+ *   来源变更数（承接引用率分母——事件流无 fr-added 事件，分母从索引读，不加归档管线事件）；
+ * - 承接引用率 = fr-supersede 涉及变更数 / 索引来源变更数（分母 0 → null）。
+ *   注意分子是 sinceDays 窗口内、分母是全量——窗口≠全量时比率偏低是口径事实，
+ *   裁决时用大窗口（--since-days 9999）读全口径。
+ *
+ * @returns {{ present: boolean, events: {...}, index: {...}, supersedeRate: number|null }}
+ *   present=false（无 fr/ 目录且零 fr-* 事件）→ 其余字段零值，消费方可整体略过。
+ */
+export function buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays = 30 } = {}) {
+  const records = readKnowledgeHits(runtimeDir, { sinceDays })
+  const frEvents = records.filter((r) => typeof r.type === 'string' && r.type.startsWith('fr-'))
+
+  const injectChanges = new Set()
+  const supersedeChanges = new Set()
+  const duplicateCandidates = new Set()
+  const unreferencedByDomain = new Map()
+  let frInject = 0
+  let frSupersede = 0
+  let frDuplicateWarning = 0
+  for (const r of frEvents) {
+    if (r.type === 'fr-inject') {
+      frInject += 1
+      if (r.change) injectChanges.add(r.change)
+    } else if (r.type === 'fr-supersede') {
+      frSupersede += 1
+      if (r.change) supersedeChanges.add(r.change)
+    } else if (r.type === 'fr-duplicate-warning') {
+      frDuplicateWarning += 1
+      if (r.candidate) duplicateCandidates.add(r.candidate)
+    } else if (r.type === 'fr-unreferenced') {
+      const domain = r.domain || 'unknown'
+      const row = unreferencedByDomain.get(domain) || { domain, events: 0, count: 0 }
+      row.events += 1
+      row.count += Number.isFinite(Number(r.count)) ? Number(r.count) : 0
+      unreferencedByDomain.set(domain, row)
+    }
+  }
+
+  const frDir = join(knowledgeDir, 'fr')
+  const frDirExists = existsSync(frDir)
+  const entries = frDirExists ? scanFrIndex(knowledgeDir) : []
+  const sourceChanges = new Set(entries.map((e) => e.change).filter(Boolean))
+  const supersededCount = entries.filter((e) => e.supersededBy).length
+
+  const denominator = sourceChanges.size
+  const supersedeRate = denominator > 0 ? supersedeChanges.size / denominator : null
+
+  return {
+    present: frDirExists || frEvents.length > 0,
+    events: {
+      frInject,
+      frInjectChanges: injectChanges.size,
+      frSupersede,
+      frSupersedeChanges: supersedeChanges.size,
+      frDuplicateWarning,
+      frDuplicateCandidates: duplicateCandidates.size,
+      frUnreferenced: [...unreferencedByDomain.values()].sort((a, b) => b.count - a.count),
+    },
+    index: {
+      entries: entries.length,
+      active: entries.length - supersededCount,
+      superseded: supersededCount,
+      sourceChanges: denominator,
+      domains: frDirExists ? readdirSync(frDir).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')) : [],
+    },
+    supersedeRate,
+  }
+}
+
 // ── CLI 入口（形态对齐 src/stages/knowledge.js cmdSearch / src/knowledge-classify.js cmdKnowledgeClassify）──
 
 function outputJson(ok, data, error) {
@@ -139,9 +219,10 @@ export async function cmdKnowledgeStats(dir, args, opts = {}) {
   // 遥测在场判定用全量读取（不加窗口）：文件缺失/只有坏行 → 无遥测
   const hasTelemetry = readKnowledgeHits(runtimeDir).length > 0
   const result = buildHitMatrix(knowledgeDir, runtimeDir, { sinceDays })
+  const frIndex = buildFrIndexStats(knowledgeDir, runtimeDir, { sinceDays })
 
   if (asJson) {
-    outputJson(true, { sinceDays, hasTelemetry, ...result })
+    outputJson(true, { sinceDays, hasTelemetry, ...result, frIndex })
     return
   }
 
@@ -176,5 +257,21 @@ export async function cmdKnowledgeStats(dir, args, opts = {}) {
   }
 
   lines.push(`遥测计数（窗口内）：注入 ${result.totalInjects} 次 | 归类 ${result.totalClassifies} 次`)
+
+  // FR 索引实验（L3 裁决仪表盘——证伪条款出数面；裁决时建议 --since-days 大窗口读全口径）
+  if (frIndex.present) {
+    const e = frIndex.events
+    const i = frIndex.index
+    lines.push('')
+    lines.push(`🔬 FR 索引实验（窗口内事件 / 索引面全量——L3 裁决指标，证伪条款见 2026-09-18-fr-index-l1 design）`)
+    lines.push(`  注入 fr-inject ${e.frInject} 次（${e.frInjectChanges} 变更） | 取代链 fr-supersede ${e.frSupersede} 次（${e.frSupersedeChanges} 变更） | 重复拦截 fr-duplicate-warning ${e.frDuplicateWarning} 次（${e.frDuplicateCandidates} 候选）`)
+    if (e.frUnreferenced.length > 0) {
+      const top = e.frUnreferenced.slice(0, 5).map((u) => `${u.domain}×${u.count}`).join('，')
+      lines.push(`  删除缺口信号 fr-unreferenced：${top}${e.frUnreferenced.length > 5 ? ' …' : ''}（观察信号·不算 L3 门禁）`)
+    }
+    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}，分子窗口内/分母全量——裁决用大窗口）`}`)
+  }
+
   console.log(lines.join('\n'))
 }