@fenglimg/fabric-cli 2.2.0-rc.8 → 2.2.0-rc.9

package/dist/{chunk-FEOPLBGA.js → chunk-3D7B2UAZ.js}

@@ -22,9 +22,8 @@ var ROOT_AUTHORITATIVE_KEYS = /* @__PURE__ */ new Set([
   "embed_model",
   "embed_weight",
   "plan_context_top_k",
+  "recall_relevance_ratio",
   "mcpPayloadLimits",
-  "retrieval_budget_profile",
-  "recall_body_budget_bytes",
   "selection_token_ttl_ms",
   "orphan_demote_proven_days",
   "orphan_demote_verified_days",

package/dist/{chunk-CMDW3PYK.js → chunk-7ZDXBOOU.js}

@@ -52,6 +52,11 @@ import {
   BOOTSTRAP_MARKER_END,
   BOOTSTRAP_REGEX
 } from "@fenglimg/fabric-shared/templates/bootstrap-canonical";
+var SKILL_ROUTER_TEMPLATE_REL = "skills/fabric/SKILL.md";
+var ROUTER_INTENT_MARKER_BEGIN = "<!-- fabric:router-intent:begin -->";
+var ROUTER_INTENT_MARKER_END = "<!-- fabric:router-intent:end -->";
+var ROUTER_INTENT_GENERATED_NOTE = "<!-- \u672C\u5757\u7531 `fabric install` \u4ECE 7 \u4E2A leaf skill \u7684 description Triggers \u5B50\u53E5\u751F\u6210\u3002\u4E25\u7981\u624B\u7F16;\u6539 leaf description \u540E\u91CD\u8DD1 `fabric install`\u3002 -->";
+var ROUTER_INTENT_REGEX = /<!-- fabric:router-intent:begin -->[\s\S]*?<!-- fabric:router-intent:end -->/u;
 var SKILL_TEMPLATE_REL = "skills/fabric-archive/SKILL.md";
 var SKILL_REVIEW_TEMPLATE_REL = "skills/fabric-review/SKILL.md";
 var SKILL_IMPORT_TEMPLATE_REL = "skills/fabric-import/SKILL.md";
@@ -69,6 +74,12 @@ var HOOK_LIB_TEMPLATE_DIR_REL = "hooks/lib";
 var CLAUDE_HOOK_CONFIG_TEMPLATE_REL = "hooks/configs/claude-code.json";
 var CODEX_HOOK_CONFIG_TEMPLATE_REL = "hooks/configs/codex-hooks.json";
 var SKILL_DESTINATIONS = {
+  // B2 skill-router: the fabric/ router skill — single-file (no ref/), installed
+  // alongside the 7 leaf skills as the human-facing dispatch entry point.
+  fabricRouter: [
+    ".claude/skills/fabric/SKILL.md",
+    ".codex/skills/fabric/SKILL.md"
+  ],
   fabricArchive: [
     ".claude/skills/fabric-archive/SKILL.md",
     ".codex/skills/fabric-archive/SKILL.md"
@@ -106,6 +117,12 @@ var SKILL_DESTINATIONS = {
   ]
 };
 var FABRIC_SKILL_INSTALL_SPECS = {
+  fabricRouter: {
+    slug: "fabric",
+    templateRel: SKILL_ROUTER_TEMPLATE_REL,
+    destinations: SKILL_DESTINATIONS.fabricRouter,
+    step: "skill-router"
+  },
   fabricArchive: {
     slug: "fabric-archive",
     templateRel: SKILL_TEMPLATE_REL,
@@ -306,6 +323,66 @@ async function installFabricAuditSkill(projectRoot, _options = {}) {
 async function installFabricConnectSkill(projectRoot, _options = {}) {
   return installFabricSkill(projectRoot, FABRIC_SKILL_INSTALL_SPECS.fabricConnect);
 }
+function extractSkillMdDescription(skillMd) {
+  const fm = skillMd.match(/^---\n([\s\S]*?)\n---/u);
+  if (!fm) return "";
+  const desc = fm[1].match(/^description:\s*(.+?)\s*$/mu);
+  if (!desc) return "";
+  return desc[1].replace(/^["'](.+)["']$/u, "$1").trim();
+}
+function extractTriggersClause(description) {
+  const m = description.match(/Triggers?\s+([\s\S]+)$/u);
+  if (!m) return "";
+  return m[1].trim().replace(/[.。]\s*$/u, "").replace(/\|/gu, "\\|");
+}
+function renderRouterIntentBlock(leaves) {
+  const rows = leaves.map((l) => `| ${l.triggers} | \`${l.slug}\` |`).join("\n");
+  const enumVals = leaves.map((l) => l.slug.replace(/^fabric-/u, "")).join(" | ");
+  return [
+    ROUTER_INTENT_MARKER_BEGIN,
+    ROUTER_INTENT_GENERATED_NOTE,
+    "",
+    "| \u7528\u6237\u610F\u56FE(leaf description Triggers) | \u4E0B\u6E38 skill |",
+    "| --- | --- |",
+    rows,
+    "",
+    `\`S_CLASSIFY\` \u7684 \`task_type\` \u679A\u4E3E:\`${enumVals}\``,
+    ROUTER_INTENT_MARKER_END
+  ].join("\n");
+}
+async function buildRouterSkillSource() {
+  const template = await readTemplate(SKILL_ROUTER_TEMPLATE_REL);
+  if (!ROUTER_INTENT_REGEX.test(template)) {
+    throw new Error(
+      `fabric/SKILL.md is missing the ${ROUTER_INTENT_MARKER_BEGIN} \u2026 ${ROUTER_INTENT_MARKER_END} marker pair \u2014 cannot regenerate the Intent Map. This is a Fabric release bug (router template was hand-edited away from the managed-block contract).`
+    );
+  }
+  const leafSpecs = Object.values(FABRIC_SKILL_INSTALL_SPECS).filter(
+    (spec) => spec.slug !== "fabric"
+  );
+  const leaves = [];
+  for (const spec of leafSpecs) {
+    const leafMd = await readTemplate(spec.templateRel);
+    leaves.push({ slug: spec.slug, triggers: extractTriggersClause(extractSkillMdDescription(leafMd)) });
+  }
+  return template.replace(ROUTER_INTENT_REGEX, renderRouterIntentBlock(leaves));
+}
+async function installFabricRouterSkill(projectRoot, _options = {}) {
+  const source = await buildRouterSkillSource();
+  validateSkillCanonicalSize(source, "fabric");
+  const spec = FABRIC_SKILL_INSTALL_SPECS.fabricRouter;
+  const targets = spec.destinations.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent(spec.step, source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
+  }
+  return results;
+}
 async function cleanupDeprecatedSkills(projectRoot) {
   const results = [];
   for (const rel of DEPRECATED_SKILL_DIRS) {
@@ -914,6 +991,7 @@ export {
   installFabricStoreSkill,
   installFabricAuditSkill,
   installFabricConnectSkill,
+  installFabricRouterSkill,
   cleanupDeprecatedSkills,
   installSharedSkillLib,
   installArchiveHintHook,

package/dist/{chunk-JTHWLUD3.js → chunk-E7HJUU34.js}

@@ -2,7 +2,7 @@
 import {
   ensureStoreProjectBinding,
   migrateRootConfig
-} from "./chunk-FEOPLBGA.js";
+} from "./chunk-3D7B2UAZ.js";
 import {
   resolveDevMode
 } from "./chunk-WA3DYGSY.js";

package/dist/{doctor-REZDNH4A.js → doctor-MDTZWKBK.js}

@@ -5,8 +5,8 @@ import {
   parseSinceDuration,
   renderDoctorFilteredHelp,
   renderTldrHeader
-} from "./chunk-JTHWLUD3.js";
-import "./chunk-FEOPLBGA.js";
+} from "./chunk-E7HJUU34.js";
+import "./chunk-3D7B2UAZ.js";
 import "./chunk-WA3DYGSY.js";
 import "./chunk-NLNH64A3.js";
 import "./chunk-PTGQAZEW.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   renderDoctorFilteredHelp
-} from "./chunk-JTHWLUD3.js";
-import "./chunk-FEOPLBGA.js";
+} from "./chunk-E7HJUU34.js";
+import "./chunk-3D7B2UAZ.js";
 import "./chunk-WA3DYGSY.js";
 import "./chunk-NLNH64A3.js";
 import "./chunk-PTGQAZEW.js";
@@ -23,7 +23,7 @@ import { defineCommand, renderUsage, runCommand, runMain } from "citty";
 // src/commands/index.ts
 var allCommands = {
   // v2.2.0-rc.5: pipeline-based install with TUI renderer (EPIC-005/006/007/008)
-  install: () => import("./install-v2-2COC3DO3.js").then((module) => module.installCommand),
+  install: () => import("./install-v2-I6PJ6IFT.js").then((module) => module.installCommand),
   // v2.1.0-rc.1 P3: multi-store lifecycle command group (list/add/remove/explain).
   store: () => import("./store-HOCORVL3.js").then((module) => module.default),
   // v2.1.0-rc.1 P3 (S9/S17/S37): multi-store pull --rebase + push, conflict resume.
@@ -35,8 +35,8 @@ var allCommands = {
   whoami: () => import("./whoami-ITGEFWH4.js").then((module) => module.default),
   status: () => import("./status-4R3TM4FJ.js").then((module) => module.default),
   "scope-explain": () => import("./scope-explain-HLJZ2M33.js").then((module) => module.default),
-  doctor: () => import("./doctor-REZDNH4A.js").then((module) => module.default),
-  uninstall: () => import("./uninstall-62F4LNKI.js").then((module) => module.default),
+  doctor: () => import("./doctor-MDTZWKBK.js").then((module) => module.default),
+  uninstall: () => import("./uninstall-IFN2KYBK.js").then((module) => module.default),
   config: () => import("./config-A3LTECAY.js").then((module) => module.default),
   "plan-context-hint": () => import("./plan-context-hint-G75R4P4J.js").then((module) => module.default),
   // v2.0.0-rc.23 TASK-014 (F8c): S5 onboard-slot coverage. Used by the
@@ -153,7 +153,7 @@ async function customShowUsageGrouped(cmd, parent, version) {
 var main = defineCommand({
   meta: {
     name: "fabric",
-    version: "2.2.0-rc.8",
+    version: "2.2.0-rc.9",
     description: t("cli.main.description")
   },
   subCommands: allCommands
@@ -165,7 +165,7 @@ async function customShowUsage(cmd, parent) {
     return;
   }
   if (cmdMeta?.name === "fabric" && parent === void 0) {
-    await customShowUsageGrouped(cmd, parent, "2.2.0-rc.8");
+    await customShowUsageGrouped(cmd, parent, "2.2.0-rc.9");
     return;
   }
   console.log(await renderUsage(cmd, parent) + "\n");

package/dist/{install-v2-2COC3DO3.js → install-v2-I6PJ6IFT.js}

@@ -8,6 +8,7 @@ import {
   installFabricConnectSkill,
   installFabricImportSkill,
   installFabricReviewSkill,
+  installFabricRouterSkill,
   installFabricStoreSkill,
   installFabricSyncSkill,
   installHookLibs,
@@ -21,13 +22,13 @@ import {
   writeClaudeBootstrapThinShell,
   writeCodexBootstrapManagedBlock,
   writeFabricAgentsSnapshot
-} from "./chunk-CMDW3PYK.js";
+} from "./chunk-7ZDXBOOU.js";
 import {
   ensureStoreProjectBinding,
   migrateRootConfig,
   normalizeStoreProjectId,
   suggestStoreProjectId
-} from "./chunk-FEOPLBGA.js";
+} from "./chunk-3D7B2UAZ.js";
 import {
   createDebugLogger,
   resolveDevMode
@@ -1737,7 +1738,7 @@ function readProjectName(target) {
   return basename(target);
 }
 function getCliVersion() {
-  return true ? "2.2.0-rc.8" : "unknown";
+  return true ? "2.2.0-rc.9" : "unknown";
 }
 function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
@@ -2356,6 +2357,7 @@ var HooksStage = class {
       const target = context.target;
       const installResults = [];
       installResults.push(...await this.runBestEffort("skill-deprecated-cleanup", () => cleanupDeprecatedSkills(target)));
+      installResults.push(...await this.runBestEffort("skill-router-install", () => installFabricRouterSkill(target)));
       installResults.push(...await this.runBestEffort("skill-install", () => installFabricArchiveSkill(target)));
       installResults.push(...await this.runBestEffort("skill-review-install", () => installFabricReviewSkill(target)));
       installResults.push(...await this.runBestEffort("skill-import-install", () => installFabricImportSkill(target)));

package/dist/{uninstall-62F4LNKI.js → uninstall-IFN2KYBK.js}

@@ -7,7 +7,7 @@ import {
   HOOK_SCRIPT_DESTINATIONS,
   SKILL_DESTINATIONS,
   fabricAgentsSnapshotPath
-} from "./chunk-CMDW3PYK.js";
+} from "./chunk-7ZDXBOOU.js";
 import {
   createDebugLogger,
   resolveDevMode
@@ -37,6 +37,9 @@ import { readdir, readFile, rm, rmdir } from "fs/promises";
 import { dirname, join } from "path";
 import { atomicWriteJson, atomicWriteText } from "@fenglimg/fabric-shared/node/atomic-write";
 import { BOOTSTRAP_REGEX } from "@fenglimg/fabric-shared/templates/bootstrap-canonical";
+async function uninstallFabricRouterSkill(projectRoot) {
+  return removeSkill("skill-router", SKILL_DESTINATIONS.fabricRouter, projectRoot);
+}
 async function uninstallFabricArchiveSkill(projectRoot) {
   return removeSkill("skill", SKILL_DESTINATIONS.fabricArchive, projectRoot);
 }
@@ -345,6 +348,12 @@ async function uninstallBootstrapStage(projectRoot, _opts = {}) {
     projectRoot,
     () => uninstallFabricArchiveSkill(projectRoot)
   );
+  await runAndCollect(
+    results,
+    "skill-router",
+    projectRoot,
+    () => uninstallFabricRouterSkill(projectRoot)
+  );
   return results;
 }
 async function runAndCollect(results, step, projectRoot, fn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "2.2.0-rc.8",
+  "version": "2.2.0-rc.9",
   "description": "Fabric CLI — installs the MCP server + skills + hooks for Claude Code and Codex CLI; runs doctor / knowledge maintenance.",
   "license": "MIT",
   "author": "wangzhichao <fenglimg90@gmail.com>",
@@ -46,8 +46,8 @@
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-shared": "2.2.0-rc.8",
-    "@fenglimg/fabric-server": "2.2.0-rc.8"
+    "@fenglimg/fabric-server": "2.2.0-rc.9",
+    "@fenglimg/fabric-shared": "2.2.0-rc.9"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/templates/hooks/fabric-hint.cjs

@@ -117,6 +117,10 @@ function readSnapshotKnowledgeStats(projectRoot, now) {
   }
   try {
     const snapshot = bindingsSnapshotReader.readBindingsSnapshot(bindingId);
+    // No snapshot file → empty corpus (KT-DEC-0007), preserving prior behavior.
+    if (!snapshot) {
+      return empty;
+    }
     // LIVE recount off the snapshot's resolved store dirs. The cached
     // knowledge_stats projection is frozen at snapshot-write time, so once the
     // pending queue is reviewed (or store content syncs out-of-band) it goes
@@ -124,8 +128,16 @@ function readSnapshotKnowledgeStats(projectRoot, now) {
     // (KT-PIT-0017). The authoritative count is the live *.md walk under the
     // resolved store dirs.
     const live = bindingsSnapshotReader.liveKnowledgeStats(snapshot);
-    if (!live || typeof live !== "object") {
-      return empty;
+    // #3: a snapshot predating knowledge_store_dirs makes liveKnowledgeStats
+    // return null — counts are undeterminable and the cached projection is
+    // unreliable. Return `undefined` (a marker distinct from the `null` that
+    // lib/binding-absent returns, which readPendingStats uses as its legacy-
+    // fallback signal) so countCanonicalNodes maps it to "unknown" and the
+    // underseed signal SKIPS rather than false-firing on a stale corpus (snapshot
+    // self-heals on the next install/sync). Distinguished from the missing-
+    // snapshot case above, which stays `empty` (genuine fresh-project zero).
+    if (live === null) {
+      return undefined;
     }
     const pendingCount =
       Number.isFinite(live.pendingCount) && live.pendingCount > 0 ? Math.floor(live.pendingCount) : 0;
@@ -412,7 +424,10 @@ function readLedger(projectRoot) {
  */
 function readPendingStats(projectRoot, now) {
   const stats = readSnapshotKnowledgeStats(projectRoot, now);
-  if (stats !== null) {
+  // `!= null` (loose) also catches the `undefined` old-snapshot marker (#3) →
+  // fall through to the legacy reader (which degrades to 0 → no phantom review
+  // nudge), rather than dereferencing pendingCount on a non-object.
+  if (stats != null) {
     return { count: stats.pendingCount, oldestAgeMs: stats.oldestPendingAgeMs };
   }
   return readLegacyPendingStats(projectRoot, now);
@@ -425,6 +440,12 @@ function readPendingStats(projectRoot, now) {
  */
 function countCanonicalNodes(projectRoot) {
   const stats = readSnapshotKnowledgeStats(projectRoot);
+  // #3: `undefined` = snapshot EXISTS but predates knowledge_store_dirs →
+  // undeterminable → return null so decide()'s underseed signal SKIPS rather than
+  // false-firing on a stale corpus. `null` = no reader / not bound → degrade to 0
+  // (KT-DEC-0007, preserved). The `empty` object (missing snapshot) → canonical 0,
+  // still firing correctly for a genuinely fresh corpus.
+  if (stats === undefined) return null;
   return stats === null ? 0 : stats.canonicalCount;
 }
 
@@ -1010,6 +1031,10 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
     lastInitScanTs === null ? null : (nowMs - lastInitScanTs) / MS_PER_HOUR;
   const hoursSinceProposed = hoursElapsed; // reuse archive-signal calc above
   const triggerUnderseed =
+    // #3: null = undeterminable canonical count (old snapshot) → skip. Guard
+    // first because `null < threshold` coerces to true in JS and would else
+    // false-fire the underseed nudge on a stale corpus.
+    underseed.nodeCount != null &&
     underseed.nodeCount < underseed.threshold &&
     hoursSinceInit !== null &&
     hoursSinceInit >= UNDERSEED_POST_INIT_QUIET_HOURS &&

package/templates/hooks/knowledge-hint-broad.cjs

@@ -16,9 +16,8 @@
  *
  *   AI sink (additionalContext) — the dynamically generated "MEMORY.md":
  *     [fabric:SessionStart] <store>
- *     ALWAYS-ACTIVE RULES (no recall needed):    # guideline/model — full BODY
- *       [guideline] team:KT-GLD-0001
- *       <full body>                              # over budget → degrade to index line
+ *     ALWAYS-ACTIVE RULES (no recall needed):    # guideline/model — INDEX line only
+ *       [guideline] team:KT-GLD-0001 · <summary> # KT-DEC-0036: no eager body
  *     REFERENCE (read on demand / fab_recall):   # decision/pitfall/process — title + hook
  *       [decision] team:KT-DEC-0001 — <must_read_if>
  *       … N more folded (broad index > backstop 50; run fabric-audit)
@@ -54,7 +53,6 @@ const { appendLockedLine } = require("./lib/injection-log.cjs");
 // (TASK-002). Variant is resolved ONCE per main() invocation via
 // readFabricLanguage(cwd) and threaded into renderBanner — no fs in render path.
 const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
-const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
 // v2.0.0-rc.37 NEW-19: shared fabric-config reader + sidecar I/O. Replaces the
 // five per-key readFileSync+parse config readers (one parse per fire now) and
 // the bespoke last-emit sidecar helpers. The L78 "refactor into lib/ if a
@@ -112,15 +110,23 @@ function readWorkspaceBindingId(cwd) {
 }
 
 function readSnapshotCanonicalCount(projectRoot) {
+  // No reader / not bound → degrade to an empty corpus (0), the documented
+  // store-only behavior (KT-DEC-0007). Only the "snapshot EXISTS but predates
+  // knowledge_store_dirs" case below is undeterminable → null (skip).
   if (bindingsSnapshotReader === null) {
-    return null;
+    return 0;
   }
   const bindingId = readWorkspaceBindingId(projectRoot);
   if (bindingId === null) {
-    return null;
+    return 0;
   }
   try {
     const snapshot = bindingsSnapshotReader.readBindingsSnapshot(bindingId);
+    // No snapshot file at all → treat as an empty corpus (KT-DEC-0007),
+    // preserving the fresh-project underseed nudge.
+    if (!snapshot) {
+      return 0;
+    }
     // LIVE recount off the snapshot's resolved store dirs. The cached
     // knowledge_stats.canonical_count is frozen at snapshot-write time and goes
     // stale when store content syncs in out-of-band (e.g. the store grew from 1
@@ -128,13 +134,21 @@ function readSnapshotCanonicalCount(projectRoot) {
     // THIS workspace's snapshot), which mis-fired the "knowledge sparse"
     // underseed nudge (KT-PIT-0017, same stale-projection root cause).
     const live = bindingsSnapshotReader.liveKnowledgeStats(snapshot);
-    if (live && Number.isFinite(live.canonicalCount) && live.canonicalCount > 0) {
-      return Math.floor(live.canonicalCount);
+    // #3: a snapshot that predates knowledge_store_dirs makes liveKnowledgeStats
+    // return null — the count is undeterminable and the cached projection is
+    // unreliable. Return null (not 0) so countCanonicalNodes / shouldRecommendImport
+    // SKIP the nudge instead of false-firing on stale data; the snapshot
+    // self-heals on the next install/sync. A genuine live 0 (dirs present, no
+    // *.md) still returns 0 and fires correctly.
+    if (live === null) {
+      return null;
     }
+    return Number.isFinite(live.canonicalCount) ? Math.floor(live.canonicalCount) : 0;
   } catch {
-    // best-effort hint stats only
+    // Read/parse fault → degrade to empty (0), preserving prior behavior. The
+    // only undeterminable→skip path is the explicit live===null above.
+    return 0;
   }
-  return 0;
 }
 
 
@@ -205,8 +219,10 @@ const DEFAULT_HINT_REMINDER_TO_CONTEXT = true;
  * trees — a missing snapshot degrades to zero (KT-DEC-0007).
  */
 function countCanonicalNodes(projectRoot) {
-  const snapshotCount = readSnapshotCanonicalCount(projectRoot);
-  return snapshotCount === null ? 0 : snapshotCount;
+  // #3: null = undeterminable (old snapshot lacking store dirs, or no binding
+  // context). Propagate it — shouldRecommendImport SKIPS on null rather than
+  // treating it as zero and false-firing the underseed nudge on a stale corpus.
+  return readSnapshotCanonicalCount(projectRoot);
 }
 
 /**
@@ -338,6 +354,10 @@ function shouldRecommendImport(projectRoot) {
 
     const threshold = readUnderseedThreshold(projectRoot);
     const nodeCount = countCanonicalNodes(projectRoot);
+    // #3: undeterminable count (old snapshot predating knowledge_store_dirs) →
+    // skip. `null < threshold` coerces to true in JS, so an explicit guard is
+    // required — otherwise the stale-snapshot case would still false-fire.
+    if (nodeCount === null) return false;
     if (nodeCount >= threshold) return false;
 
     if (isImportTouched(projectRoot) !== "absent") return false;
@@ -374,65 +394,6 @@ const CLI_TIMEOUT_MS = 2000;
 // `hint_summary_max_len` in fabric-config overrides this default (range 40..240).
 const DEFAULT_SUMMARY_MAX_LEN = 80;
 
-// v2.2 HK2-degrade (W2-T2): char budget for the rendered broad-menu BODY. The
-// hook already degrades by COUNT (hint_broad_top_k slice + TRUNCATION_THRESHOLD
-// grouped mode), but nothing bounded the total rendered SIZE — a corpus with
-// many types or long (near-maxLen) summaries could still emit a wall of text
-// that displaces the agent's working memory. Borrowing the maestro
-// context-budget idea, this is the final rung of the degradation ladder: once
-// the body exceeds the budget, the tail collapses to a single "N more omitted"
-// marker. Default 2000 chars ≈ one screenful. Overridable via
-// fabric-config.json#hint_broad_budget_chars (range 200..20000); 0 disables.
-const DEFAULT_HINT_BROAD_BUDGET_CHARS = 2000;
-
-// v2.2 C5-budget (W2-T3): bind the injection char budget to the layered retrieval
-// budget profile. Mirrors the injectionChars column of shared/retrieval-budget.ts
-// PROFILES (kept in sync — the hook cannot require the TS resolver). The explicit
-// `hint_broad_budget_chars` knob still wins; the profile only supplies the
-// default. `balanced` (and an absent/unknown profile) keeps the historical 2000.
-const RETRIEVAL_BUDGET_INJECTION_CHARS = {
-  conservative: 1000,
-  balanced: 2000,
-  generous: 4000,
-};
-
-function readBroadBudgetChars(projectRoot) {
-  const profile = readConfigString(projectRoot, "retrieval_budget_profile", "balanced");
-  const profileDefault =
-    RETRIEVAL_BUDGET_INJECTION_CHARS[profile] ?? DEFAULT_HINT_BROAD_BUDGET_CHARS;
-  return readConfigNumber(projectRoot, "hint_broad_budget_chars", profileDefault, {
-    min: 0,
-    max: 20000,
-    floor: true,
-  });
-}
-
-// v2.2 HK2-degrade (W2-T2): cap the rendered body to `budgetChars`, collapsing
-// the overflow tail into one marker line. Structural lines (banner, revision_hash,
-// footer) are appended by renderSummary AFTER this pass, so they always survive —
-// only entry/group body lines are subject to the budget. `budgetChars` of 0 or
-// undefined is a no-op (preserves the pre-HK2 unbounded behavior and all
-// existing snapshot tests).
-function capBodyToBudget(body, budgetChars) {
-  if (!budgetChars || budgetChars <= 0) return body;
-  const kept = [];
-  let total = 0;
-  for (let i = 0; i < body.length; i += 1) {
-    const line = body[i];
-    // +1 for the newline each line costs once joined.
-    if (kept.length > 0 && total + line.length + 1 > budgetChars) {
-      const remaining = body.length - i;
-      kept.push(
-        `  … ${remaining} more entr${remaining === 1 ? "y" : "ies"} omitted (injection budget ${budgetChars} chars; raise hint_broad_budget_chars or narrow scope)`,
-      );
-      return kept;
-    }
-    kept.push(line);
-    total += line.length + 1;
-  }
-  return kept;
-}
-
 function readSummaryMaxLen(projectRoot) {
   return readConfigNumber(projectRoot, "hint_summary_max_len", DEFAULT_SUMMARY_MAX_LEN, {
     min: 40,
@@ -682,7 +643,7 @@ function renderTruncated(narrow, maxLen) {
  * after writing exactly one stderr breadcrumb so operators grepping a stuck-
  * banner report can diagnose the version drift without source-diving.
  */
-function renderSummary(payload, maxLen, budgetChars) {
+function renderSummary(payload, maxLen) {
   if (!payload || payload.version !== 2) {
     if (payload && payload.version !== undefined) {
       try {
@@ -705,9 +666,9 @@ function renderSummary(payload, maxLen, budgetChars) {
     ? `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available (truncated):`
     : `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available:`;
 
-  const renderedBody = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
-  // v2.2 HK2-degrade (W2-T2): final budget rung — cap the body's rendered size.
-  const body = capBodyToBudget(renderedBody, budgetChars);
+  // KT-DEC-0028 completeness: the rendered census is bounded by the per-line
+  // maxLen + TRUNCATION_THRESHOLD grouped mode, not by a body char budget.
+  const body = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
 
   const lines = [banner, ...body];
   const revHash = typeof payload.revision_hash === "string" ? payload.revision_hash : null;
@@ -861,10 +822,10 @@ function renderHumanCensus(census, opts) {
 // generated "MEMORY.md" spine injected into the SessionStart context. Two
 // type-tiered sections over the BROAD knowledge (narrow stays silent — D0029):
 //
-//   ALWAYS-ACTIVE RULES (guideline/model): full BODIES injected, bounded by
-//     budgetChars. On overflow each entry degrades to an INDEX LINE (title +
-//     summary), NOT a folded count (D0028) — the entry stays individually
-//     visible and fetchable.
+//   ALWAYS-ACTIVE RULES (guideline/model): INDEX LINE only (title + summary) —
+//     never the eager body (KT-DEC-0036). The body is one cheap on-demand fetch
+//     away, so injecting it on every SessionStart is a permanent context tax
+//     (KT-GLD-0005) we no longer pay; each entry stays individually visible.
 //   REFERENCE (decision/pitfall/process): TITLE + must_read_if hook only
 //     (situational; the agent Reads the body on demand) — never the body.
 //
@@ -876,7 +837,7 @@ function renderHumanCensus(census, opts) {
 const REFERENCE_TYPES = new Set(["decision", "pitfall", "process"]);
 
 function renderAiSink(opts) {
-  const { entries, alwaysBodies, storeLabel, budgetChars, broadIndexBackstop, summaryMaxLen, lang } =
+  const { entries, alwaysBodies, storeLabel, broadIndexBackstop, summaryMaxLen, lang } =
     opts || {};
   const zh = lang === "zh-CN";
   const bodies = Array.isArray(alwaysBodies) ? alwaysBodies : [];
@@ -895,30 +856,19 @@ function renderAiSink(opts) {
   const lines = [];
   lines.push(`[fabric:SessionStart] ${storeLabel || "store"}`);
 
-  // ALWAYS-ACTIVE RULES — inject bodies up to the budget, degrade to index line.
+  // ALWAYS-ACTIVE RULES — index-only (title + summary), never the eager body.
   lines.push(zh ? "ALWAYS-ACTIVE RULES (无需再 recall):" : "ALWAYS-ACTIVE RULES (no recall needed):");
   if (bodies.length === 0) {
     lines.push(zh ? "  (无 always-active 条目)" : "  (none)");
   } else {
-    const budget = typeof budgetChars === "number" && budgetChars > 0 ? budgetChars : 0;
-    let used = 0;
-    let degraded = false;
+    // KT-DEC-0036: render each always-active entry as a single index line
+    // (title + summary). The body is one cheap on-demand fetch away (see footer),
+    // so injecting it on every SessionStart is a permanent context tax
+    // (KT-GLD-0005) we no longer pay.
     for (const b of bodies) {
       const label = `[${TYPE_SINGULAR[b.type] || b.type}] ${b.id}`;
-      const body = typeof b.body === "string" ? b.body.trim() : "";
-      const summary = typeof b.summary === "string" ? b.summary : "";
-      const fullCost = label.length + body.length + 2;
-      if (!degraded && (budget === 0 || used + fullCost <= budget)) {
-        lines.push(`  ${label}`);
-        if (body.length > 0) lines.push(body);
-        used += fullCost;
-      } else {
-        // D0028: degrade to an INDEX LINE (title + summary), never a folded count.
-        degraded = true;
-        lines.push(
-          `  ${label} · ${summary}${zh ? " (超预算; fab_recall 取正文)" : " (over budget; fab_recall for body)"}`,
-        );
-      }
+      const summary = typeof b.summary === "string" ? b.summary.trim() : "";
+      lines.push(summary.length > 0 ? `  ${label} · ${summary}` : `  ${label}`);
       indexCount += 1;
     }
   }
@@ -977,29 +927,20 @@ function renderAiSink(opts) {
 // Returns:
 //   human               — gated final human text (null when gated off / empty)
 //   ai                  — gated final AI text (null when reminder-to-context off / empty)
-//   resolvedPayload     — payload with opaque summaries resolved (for telemetry / --explain)
+//   resolvedPayload     — the plan-context payload, passed through unchanged (for telemetry / --explain)
 //   hasRenderedContent  — true when ANY sink rendered content (main's silent-exit gate)
 //   reminderToContext   — readReminderToContext(cwd) (telemetry target-channel)
 function buildSessionStartSinks(cwd, payload, env) {
-  // rc.35 TASK-06: opaque-summary substitution (best-effort; failure leaves
-  // the original summary untouched).
-  let resolvedPayload = payload;
-  try {
-    if (payload && Array.isArray(payload.entries)) {
-      const resolvedEntries = resolveOpaqueSummaries(
-        payload.entries,
-        cwd,
-        typeof payload.revision_hash === "string" ? payload.revision_hash : "",
-      );
-      resolvedPayload = { ...payload, entries: resolvedEntries };
-    }
-  } catch {
-    // resolveOpaqueSummaries swallows its own errors; belt + suspenders.
-  }
+  // KT-GLD-0006: the rc.35 opaque-summary runtime substitution
+  // (resolveOpaqueSummaries) is retired. The write-time mechanical floor in
+  // extractKnowledge (summary !== stable_id/slug + length floor) prevents
+  // degenerate summaries at the source, so SessionStart no longer band-aids them
+  // at render time; surviving legacy opaque summaries are fixed by the
+  // review-time cold-eval audit pass.
+  const resolvedPayload = payload;
 
   const recommendImport = shouldRecommendImport(cwd);
   const summaryMaxLen = readSummaryMaxLen(cwd);
-  const broadBudgetChars = readBroadBudgetChars(cwd);
   const fabricLanguageForEmit = readFabricLanguage(cwd);
 
   const census =
@@ -1023,7 +964,7 @@ function buildSessionStartSinks(cwd, payload, env) {
   // ---- HUMAN sink: §3 grouped census (+ verbose per-entry detail). ----
   const humanLines = renderHumanCensus(census, { lang: fabricLanguageForEmit });
   if (humanLines.length > 0 && humanGate.verbosity === "verbose") {
-    const detail = renderSummary(resolvedPayload, summaryMaxLen, broadBudgetChars);
+    const detail = renderSummary(resolvedPayload, summaryMaxLen);
     humanLines.push(...detail);
   }
   if (bindingsSnapshotReader !== null && humanLines.length > 0) {
@@ -1056,12 +997,12 @@ function buildSessionStartSinks(cwd, payload, env) {
     );
   }
 
-  // ---- AI sink: spine — always-active bodies + reference, bounded. ----
+  // ---- AI sink: spine — always-active INDEX lines (no eager body, KT-DEC-0036)
+  // + reference, bounded by the broad_index_backstop fold. ----
   const broadIndexBackstop = readBroadIndexBackstop(cwd);
   const aiText = renderAiSink({
     entries: resolvedPayload && Array.isArray(resolvedPayload.entries) ? resolvedPayload.entries : [],
     alwaysBodies,
-    budgetChars: broadBudgetChars,
     broadIndexBackstop,
     summaryMaxLen,
     lang: fabricLanguageForEmit,

package/templates/hooks/knowledge-hint-narrow.cjs

@@ -75,11 +75,9 @@ const {
 } = require("node:fs");
 const { dirname, join } = require("node:path");
 
-// rc.35 TASK-06 (P0-10.b): summary-fallback. Substitutes opaque entries
-// (where description.summary === stable_id) with a snippet read from the
-// entry's .md `## Summary` section. Caches results in
-// `.fabric/.cache/summary-fallback.json` keyed by revision_hash.
-const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
+// KT-GLD-0006: the rc.35 opaque-summary substitution (resolveOpaqueSummaries) is
+// retired — the write-time mechanical floor in extractKnowledge prevents
+// degenerate summaries at the source, so the narrow hook no longer band-aids them.
 // v2.0.0-rc.37 NEW-17: shared sidecar I/O for the plan-context-hint result
 // cache (skips a redundant CLI cold-start spawn when the same path-set is
 // re-edited within a session and the knowledge graph hasn't changed).
@@ -1492,21 +1490,10 @@ async function main(env, stdio) {
     }
 
     const summaryMaxLen = readSummaryMaxLen(cwd);
-    // rc.35 TASK-06 (P0-10.b): substitute opaque summaries before render.
-    // Same lib used by the broad hook — opaque entries seen from both call
-    // sites share a single .fabric/.cache/summary-fallback.json file.
-    // Best-effort — any failure leaves the original opaque summary intact.
-    let resolvedEntries = dedupDecision.filtered;
-    try {
-      resolvedEntries = resolveOpaqueSummaries(
-        dedupDecision.filtered,
-        cwd,
-        currentRevisionHash,
-      );
-    } catch {
-      // resolveOpaqueSummaries swallows its own errors; defensive catch.
-    }
-    const lines = renderSummary({ ...cliPayload, entries: resolvedEntries }, summaryMaxLen);
+    // KT-GLD-0006: the rc.35 opaque-summary runtime substitution is retired — the
+    // write-time mechanical floor in extractKnowledge prevents degenerate summaries
+    // at the source, so the narrow hook renders the description summary as-is.
+    const lines = renderSummary({ ...cliPayload, entries: dedupDecision.filtered }, summaryMaxLen);
     if (lines.length === 0) return;
 
     // v2.1.0-rc.1 P4 (F4/S63): store-aware hint — append the write-target store
@@ -1564,7 +1551,7 @@ async function main(env, stdio) {
       const surfaceClient = detectClient();
       const fabricDir = join(cwd, FABRIC_DIR_REL);
       if (surfaceClient !== undefined && existsSync(fabricDir)) {
-        const renderedIds = resolvedEntries
+        const renderedIds = dedupDecision.filtered
           .map((e) => (e && typeof e.id === "string" ? e.id : null))
           .filter((x) => x !== null);
         const realSessionId =

package/templates/hooks/lib/bindings-snapshot-reader.cjs

@@ -148,18 +148,19 @@ function liveKnowledgeStats(snapshot) {
     }
     return { pendingCount, canonicalCount, oldestPendingMtimeMs };
   }
-  // Backward-compatible fallback: snapshot predates knowledge_store_dirs.
-  const stats = snapshot.knowledge_stats;
-  if (stats && typeof stats === "object") {
-    return {
-      pendingCount: Number.isFinite(stats.pending_count) ? Math.floor(stats.pending_count) : 0,
-      canonicalCount: Number.isFinite(stats.canonical_count) ? Math.floor(stats.canonical_count) : 0,
-      oldestPendingMtimeMs:
-        Number.isFinite(stats.oldest_pending_mtime_ms) && stats.oldest_pending_mtime_ms > 0
-          ? stats.oldest_pending_mtime_ms
-          : null,
-    };
-  }
+  // #3 (GH issue): snapshot predates knowledge_store_dirs. The cached
+  // `knowledge_stats` projection is frozen at snapshot-write time and goes stale
+  // out-of-band (store grew via git pull / cross-workspace sync), so trusting it
+  // re-introduced exactly the false-nudge this whole field cures — observed a
+  // store with 61 live canonical entries whose cached count was frozen at 1,
+  // mis-firing the "knowledge sparse → /fabric-import" underseed nudge AND
+  // defeating the fabric-import `canonical > 50 → SKIP` guard. read_set carries
+  // no resolved store root either (alias/uuid only), so a live recount is
+  // impossible without re-resolution (which hooks must not do). Return null
+  // ("undeterminable") so callers SKIP the nudge rather than act on a stale
+  // count — old snapshots self-heal on the next install/sync/store-op (which
+  // regenerates the snapshot WITH knowledge_store_dirs). 宁可不弹也别误弹
+  // (KT-DEC-0007: hook = nudge, never a false-positive gate).
   return null;
 }
 

package/templates/skills/fabric/SKILL.md

@@ -17,15 +17,21 @@ description: Fabric 入口层路由 — 参考 maestro 的顺序协调方式，
 
 ## Intent Map
 
-| 用户意图 | 下游 skill |
+<!-- fabric:router-intent:begin -->
+<!-- 本块由 `fabric install` 从 7 个 leaf skill 的 description Triggers 子句生成。严禁手编;改 leaf description 后重跑 `fabric install`。 -->
+
+| 用户意图(leaf description Triggers) | 下游 skill |
 | --- | --- |
-| 记录/归档/以后记住/always/never/下次注意 | `fabric-archive` |
-| 审批 pending、批量 approve/reject/modify/revisit/defer | `fabric-review` |
-| 从 git log、docs 或历史材料冷启动导入知识 | `fabric-import` |
-| 创建、挂载、绑定、列出、切换 write store | `fabric-store` |
-| 多 store pull --rebase + push、同步冲突处理 | `fabric-sync` |
-| 知识库体检、淘汰陈旧条目、deprecate、rescue-before-delete | `fabric-audit` |
-| 发现 KB 条目关联、补 `related` 边、知识图谱连通性 | `fabric-connect` |
+| 以后/always/never/下次/记一下;wrong-turn-revert;decision-confirm;dismissal-reason;/fabric-archive | `fabric-archive` |
+| 审批/驳回/复审/重审/approve/reject/review pending | `fabric-review` |
+| 导入历史/bootstrap fabric/mine changelog/挖掘 commit | `fabric-import` |
+| 同步知识库/sync stores/fabric-sync/解决 store 冲突/rebase 冲突 | `fabric-sync` |
+| 创建 store/挂载 store/绑定知识库/store 列表/切换写库/set up knowledge store | `fabric-store` |
+| 审计知识库/清理陈旧知识/知识库体检/deprecate 条目/prune stale knowledge/知识库瘦身/淘汰旧决策 | `fabric-audit` |
+| 连接知识/找关联条目/建知识图谱/link related entries/补 related 边/知识库连通性 | `fabric-connect` |
+
+`S_CLASSIFY` 的 `task_type` 枚举:`archive | review | import | sync | store | audit | connect`
+<!-- fabric:router-intent:end -->
 
 ## State Machine
 
@@ -35,7 +41,7 @@ description: Fabric 入口层路由 — 参考 maestro 的顺序协调方式，
 
 ```json
 {
-  "task_type": "archive|review|import|store|sync|audit|connect",
+  "task_type": "<Intent Map task_type 枚举之一>",
   "scope": "project|store|entry|paths|null",
   "write_intent": true,
   "confidence": "high|medium|low"

package/templates/hooks/lib/summary-fallback.cjs

@@ -1,273 +0,0 @@
-/**
- * rc.35 TASK-06 (P0-10.b) — summary-fallback library.
- *
- * Resolves opaque hint entries (where `entry.summary === entry.id` so the
- * AI sees no information beyond the id) by reading the entry's markdown file
- * from mounted store `knowledge/<type>/<id>--<slug>.md`, extracting the first
- * paragraph under `## Summary`, and substituting that text into the entry
- * before the hook renders it.
- *
- * Caching: results are stored in `.fabric/.cache/summary-fallback.json`
- * keyed by the current `revision_hash` returned by plan-context-hint. The
- * cache is wiped wholesale when the revision changes (cheap invariant —
- * any meta rev bump implies entry text MAY have moved). Per-process call
- * also benefits from in-memory dedup since the same opaque id may appear
- * across narrow + broad paths.
- *
- * Design contract:
- *   - Never throw. ANY failure (cache read, fs scan, file read) degrades
- *     to a no-op — the original opaque summary is left untouched. Hooks
- *     must remain best-effort.
- *   - Idempotent over identical inputs. Two calls in succession with the
- *     same revision_hash + entries set produce zero disk reads on the
- *     second call.
- *
- * Public API (module.exports):
- *   resolveOpaqueSummaries(entries, projectRoot, revisionHash) — returns
- *     a NEW array of entries with `summary` substituted for opaque cases.
- *     Original `entry.id` is preserved verbatim.
- *
- *   _extractFirstSummaryParagraph(md) — pure helper, exposed for testing.
- *
- *   _readCache / _writeCache — exposed for testing.
- */
-
-const { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } = require("node:fs");
-const { homedir } = require("node:os");
-const { join } = require("node:path");
-
-const CACHE_DIR_REL = ".fabric/.cache";
-const CACHE_FILE_REL = ".fabric/.cache/summary-fallback.json";
-const GLOBAL_CONFIG_FILE = "fabric-global.json";
-const PROJECT_CONFIG_REL = ".fabric/fabric-config.json";
-const SUMMARY_MAX_LEN = 80;
-const KNOWLEDGE_TYPE_DIRS = ["decisions", "pitfalls", "guidelines", "models", "processes"];
-
-function _isOpaque(entry) {
-  if (!entry || typeof entry.id !== "string" || typeof entry.summary !== "string") {
-    return false;
-  }
-  return entry.summary.trim() === entry.id.trim();
-}
-
-/**
- * Pure helper: extract the first paragraph under a `## Summary` heading.
- *
- *   - `## Summary` is case-insensitive but level-sensitive (only H2).
- *   - First paragraph = lines until blank line or next heading.
- *   - Collapses whitespace + trims; returns `""` if no summary section or
- *     the section is empty.
- */
-function _extractFirstSummaryParagraph(md) {
-  if (typeof md !== "string" || md.length === 0) return "";
-  const lines = md.split(/\r?\n/);
-  let i = 0;
-  while (i < lines.length) {
-    if (/^##\s+summary\s*$/i.test(lines[i].trim())) {
-      i += 1;
-      break;
-    }
-    i += 1;
-  }
-  if (i >= lines.length) return "";
-  // Skip blank lines after the heading
-  while (i < lines.length && lines[i].trim().length === 0) i += 1;
-  // Collect until the next blank line or next heading
-  const buf = [];
-  while (i < lines.length) {
-    const line = lines[i];
-    if (line.trim().length === 0) break;
-    if (/^#{1,6}\s/.test(line.trim())) break;
-    buf.push(line.trim());
-    i += 1;
-  }
-  const flat = buf.join(" ").replace(/\s+/g, " ").trim();
-  if (flat.length === 0) return "";
-  if (flat.length <= SUMMARY_MAX_LEN) return flat;
-  return `${flat.slice(0, SUMMARY_MAX_LEN - 1)}…`;
-}
-
-function _readCache(projectRoot) {
-  const cachePath = join(projectRoot, CACHE_FILE_REL);
-  if (!existsSync(cachePath)) return null;
-  try {
-    const raw = readFileSync(cachePath, "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === "object" && typeof parsed.revision === "string" && parsed.summaries && typeof parsed.summaries === "object") {
-      return parsed;
-    }
-  } catch {
-    // ignore — caller treats null as no-cache
-  }
-  return null;
-}
-
-function _writeCache(projectRoot, payload) {
-  try {
-    const cacheDir = join(projectRoot, CACHE_DIR_REL);
-    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
-    const cachePath = join(projectRoot, CACHE_FILE_REL);
-    writeFileSync(cachePath, JSON.stringify(payload), "utf8");
-  } catch {
-    // Best-effort — failing to persist cache is not an error
-  }
-}
-
-/**
- * Return mounted store directories in the project's read-set
- * (`required_stores` plus implicit personal). This hook helper is deliberately
- * tiny and best-effort: malformed config degrades to an empty read-set rather
- * than throwing during a shell hook.
- */
-function _readJson(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function _globalRoot() {
-  return join(process.env.FABRIC_HOME || homedir(), ".fabric");
-}
-
-function _storeDir(globalRoot, store) {
-  return join(globalRoot, "stores", store.mount_name || store.store_uuid);
-}
-
-function _readSetStoreDirs(projectRoot) {
-  const globalRoot = _globalRoot();
-  const global = _readJson(join(globalRoot, GLOBAL_CONFIG_FILE));
-  if (!global || !Array.isArray(global.stores)) return [];
-  const project = _readJson(join(projectRoot, PROJECT_CONFIG_REL)) || {};
-  const required = Array.isArray(project.required_stores) ? project.required_stores : [];
-  const stores = [];
-
-  for (const req of required) {
-    if (!req || typeof req.id !== "string") continue;
-    const matched = global.stores.find(
-      (store) => store && !store.personal && (store.alias === req.id || store.store_uuid === req.id),
-    );
-    if (matched) stores.push(matched);
-  }
-
-  const personal = global.stores.find((store) => store && store.personal);
-  if (personal) stores.push(personal);
-
-  return stores.map((store) => ({
-    alias: typeof store.alias === "string" ? store.alias : "",
-    dir: _storeDir(globalRoot, store),
-  }));
-}
-
-function _splitQualifiedId(id) {
-  const idx = typeof id === "string" ? id.indexOf(":") : -1;
-  if (idx <= 0) return { alias: "", stableId: id };
-  return { alias: id.slice(0, idx), stableId: id.slice(idx + 1) };
-}
-
-/**
- * Scan mounted store `knowledge/<type>/` for the canonical `<id>--<slug>.md`
- * matching `stableId`. Tries the most likely type-dir first based on the
- * entry's `type` hint, then falls back to scanning all canonical type
- * directories. Returns the absolute path or null.
- *
- * The id→file mapping is unique by construction (stable_id is allocated
- * once per file), so the first match wins.
- */
-function _findEntryFile(projectRoot, stableId, typeHint) {
-  const parsedId = _splitQualifiedId(stableId);
-  const storeDirs = _readSetStoreDirs(projectRoot).filter(
-    (store) => parsedId.alias.length === 0 || store.alias === parsedId.alias,
-  );
-  if (storeDirs.length === 0) return null;
-  const tryOrder = [];
-  if (typeof typeHint === "string" && typeHint.length > 0) {
-    // Accept both singular and plural hints — find the plural form.
-    const lower = typeHint.toLowerCase();
-    const plural = KNOWLEDGE_TYPE_DIRS.find((d) => d === lower || d.startsWith(lower));
-    if (plural) tryOrder.push(plural);
-  }
-  for (const t of KNOWLEDGE_TYPE_DIRS) {
-    if (!tryOrder.includes(t)) tryOrder.push(t);
-  }
-  const prefix = `${parsedId.stableId}--`;
-  for (const store of storeDirs) {
-    const baseDir = join(store.dir, "knowledge");
-    if (!existsSync(baseDir)) continue;
-    for (const t of tryOrder) {
-      const typeDir = join(baseDir, t);
-      if (!existsSync(typeDir)) continue;
-      let files;
-      try {
-        files = readdirSync(typeDir);
-      } catch {
-        continue;
-      }
-      for (const f of files) {
-        if (f.startsWith(prefix) && f.endsWith(".md")) {
-          return join(typeDir, f);
-        }
-      }
-    }
-  }
-  return null;
-}
-
-function _resolveOne(projectRoot, entry) {
-  const filePath = _findEntryFile(projectRoot, entry.id, entry.type);
-  if (filePath === null) return "";
-  let md;
-  try {
-    md = readFileSync(filePath, "utf8");
-  } catch {
-    return "";
-  }
-  return _extractFirstSummaryParagraph(md);
-}
-
-/**
- * Main API. Returns a new array of entries with `summary` swapped for
- * the extracted fallback wherever the original summary was opaque AND
- * the fallback extraction yielded a non-empty string. Non-opaque entries
- * pass through unchanged.
- */
-function resolveOpaqueSummaries(entries, projectRoot, revisionHash) {
-  if (!Array.isArray(entries) || entries.length === 0) return entries;
-  const cache = _readCache(projectRoot);
-  const cachedSummaries = cache && cache.revision === revisionHash && cache.summaries ? cache.summaries : {};
-  const nextCacheSummaries = { ...cachedSummaries };
-  let cacheChanged = cache === null || cache.revision !== revisionHash;
-  const result = entries.map((entry) => {
-    if (!_isOpaque(entry)) return entry;
-    const id = entry.id;
-    let fallback;
-    if (Object.prototype.hasOwnProperty.call(cachedSummaries, id)) {
-      fallback = cachedSummaries[id];
-    } else {
-      fallback = _resolveOne(projectRoot, entry);
-      nextCacheSummaries[id] = fallback;
-      cacheChanged = true;
-    }
-    if (typeof fallback === "string" && fallback.length > 0) {
-      return { ...entry, summary: fallback };
-    }
-    return entry;
-  });
-  if (cacheChanged) {
-    _writeCache(projectRoot, { revision: revisionHash, summaries: nextCacheSummaries });
-  }
-  return result;
-}
-
-module.exports = {
-  resolveOpaqueSummaries,
-  _extractFirstSummaryParagraph,
-  _readCache,
-  _writeCache,
-  _findEntryFile,
-  _readSetStoreDirs,
-  _isOpaque,
-  SUMMARY_MAX_LEN,
-  KNOWLEDGE_TYPE_DIRS,
-};