@fenglimg/fabric-server 2.2.0-rc.1 → 2.2.0-rc.3

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile15 } from "fs/promises";
-import { join as join12, resolve as resolve5 } from "path";
+import { readFile as readFile16 } from "fs/promises";
+import { join as join14, resolve as resolve5 } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -162,7 +162,11 @@ import {
   eventLedgerEventSchema,
   redactSecrets
 } from "@fenglimg/fabric-shared";
-import { atomicWriteText as atomicWriteText2, createLedgerWriteQueue } from "@fenglimg/fabric-shared/node/atomic-write";
+import {
+  atomicWriteText as atomicWriteText2,
+  createLedgerWriteQueue,
+  withFileLock
+} from "@fenglimg/fabric-shared/node/atomic-write";
 
 // src/services/_shared.ts
 import { dirname, join as join2, resolve, sep } from "path";
@@ -214,6 +218,15 @@ function isNodeError(error) {
 
 // src/services/event-ledger.ts
 var ledgerQueue = createLedgerWriteQueue();
+function eventLedgerLockPath(eventPath) {
+  return `${eventPath}.lock`;
+}
+function exclusiveLedgerWrite(eventPath, fn) {
+  return withFileLock(
+    eventLedgerLockPath(eventPath),
+    () => ledgerQueue.runExclusive(eventPath, fn)
+  );
+}
 var __eventLedgerParseStats = { lineParses: 0 };
 var EVENT_LEDGER_DEFAULT_RETENTION_DAYS = 30;
 var EVENT_LEDGER_SIZE_WARN_BYTES = 50 * 1024 * 1024;
@@ -317,7 +330,10 @@ async function appendEventLedgerEvent(projectRoot, event) {
     schema_version: 1
   });
   await ensureParentDirectory(eventPath);
-  await ledgerQueue.append(eventPath, JSON.stringify(nextEvent));
+  await withFileLock(
+    eventLedgerLockPath(eventPath),
+    () => ledgerQueue.append(eventPath, JSON.stringify(nextEvent))
+  );
   try {
     const size = statSync(eventPath).size;
     if (size > EVENT_LEDGER_SIZE_WARN_BYTES) {
@@ -385,24 +401,26 @@ async function readEventLedger(projectRoot, options = {}) {
   return { events: filtered, warnings };
 }
 async function truncateLedgerToLastNewline(path2) {
-  const raw = await readFile2(path2);
-  const content = raw.toString("utf8");
-  if (content.endsWith("\n") || content.length === 0) {
-    return { truncated_bytes: 0, corrupted_path: "" };
-  }
-  const lastNewlineIndex = content.lastIndexOf("\n");
-  if (lastNewlineIndex === -1) {
-    const corruptedPath2 = `${path2}.corrupted.${Date.now()}`;
-    await writeFile(corruptedPath2, raw);
-    await truncate(path2, 0);
-    return { truncated_bytes: raw.length, corrupted_path: corruptedPath2 };
-  }
-  const keepByteLength = Buffer.byteLength(content.slice(0, lastNewlineIndex + 1), "utf8");
-  const corruptedBytes = raw.slice(keepByteLength);
-  const corruptedPath = `${path2}.corrupted.${Date.now()}`;
-  await writeFile(corruptedPath, corruptedBytes);
-  await truncate(path2, keepByteLength);
-  return { truncated_bytes: corruptedBytes.length, corrupted_path: corruptedPath };
+  return withFileLock(eventLedgerLockPath(path2), async () => {
+    const raw = await readFile2(path2);
+    const content = raw.toString("utf8");
+    if (content.endsWith("\n") || content.length === 0) {
+      return { truncated_bytes: 0, corrupted_path: "" };
+    }
+    const lastNewlineIndex = content.lastIndexOf("\n");
+    if (lastNewlineIndex === -1) {
+      const corruptedPath2 = `${path2}.corrupted.${Date.now()}`;
+      await writeFile(corruptedPath2, raw);
+      await truncate(path2, 0);
+      return { truncated_bytes: raw.length, corrupted_path: corruptedPath2 };
+    }
+    const keepByteLength = Buffer.byteLength(content.slice(0, lastNewlineIndex + 1), "utf8");
+    const corruptedBytes = raw.slice(keepByteLength);
+    const corruptedPath = `${path2}.corrupted.${Date.now()}`;
+    await writeFile(corruptedPath, corruptedBytes);
+    await truncate(path2, keepByteLength);
+    return { truncated_bytes: corruptedBytes.length, corrupted_path: corruptedPath };
+  });
 }
 function parseEventLedgerLine(line, index) {
   try {
@@ -427,7 +445,7 @@ function isNodeError2(error) {
 }
 async function rotateEventLedgerIfNeeded(projectRoot, opts = {}) {
   const eventPath = getEventLedgerPath(projectRoot);
-  return ledgerQueue.runExclusive(eventPath, async () => {
+  return exclusiveLedgerWrite(eventPath, async () => {
     const now = opts.now ?? /* @__PURE__ */ new Date();
     const retentionDays = resolveRetentionDays(projectRoot, opts.retentionDays);
     const cutoffMs = now.getTime() - retentionDays * 864e5;
@@ -523,7 +541,7 @@ async function rotateEventLedgerIfNeeded(projectRoot, opts = {}) {
 }
 async function dropEventsFromLedger(projectRoot, opts) {
   const eventPath = getEventLedgerPath(projectRoot);
-  return ledgerQueue.runExclusive(eventPath, async () => {
+  return exclusiveLedgerWrite(eventPath, async () => {
     const now = opts.now ?? /* @__PURE__ */ new Date();
     let raw;
     try {
@@ -741,7 +759,7 @@ import { join as join5 } from "path";
 import { RuleValidationError } from "@fenglimg/fabric-shared/errors";
 
 // src/services/knowledge-meta-builder.ts
-import { mkdir as mkdir3, readdir, readFile as readFile3, stat } from "fs/promises";
+import { readdir, readFile as readFile3, stat } from "fs/promises";
 import { existsSync as existsSync2, statSync as statSync2 } from "fs";
 import { homedir } from "os";
 import { isAbsolute, join as join4, relative, resolve as resolve2, sep as sep2 } from "path";
@@ -760,7 +778,7 @@ import {
   StableIdSchema,
   parseKnowledgeId
 } from "@fenglimg/fabric-shared";
-import { atomicWriteText as atomicWriteText3 } from "@fenglimg/fabric-shared/node/atomic-write";
+import { atomicWriteText as atomicWriteText3, withFileLock as withFileLock2 } from "@fenglimg/fabric-shared/node/atomic-write";
 async function loadKbIdTypeMap(projectRootInput) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
@@ -801,28 +819,30 @@ async function writeKnowledgeMeta(projectRootInput, options) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
   const knowledgeTestIndexPath = join4(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
-  const existingMeta = await readExistingMeta(metaPath);
-  const result = await buildKnowledgeMeta(projectRoot);
-  if (!result.changed) {
-    return result;
-  }
-  await ensureParentDirectory(metaPath);
-  await atomicWriteText3(metaPath, `${JSON.stringify(result.meta, null, 2)}
+  return withFileLock2(`${metaPath}.lock`, async () => {
+    const existingMeta = await readExistingMeta(metaPath);
+    const result = await buildKnowledgeMeta(projectRoot);
+    if (!result.changed) {
+      return result;
+    }
+    await ensureParentDirectory(metaPath);
+    await atomicWriteText3(metaPath, `${JSON.stringify(result.meta, null, 2)}
 `);
-  await ensureParentDirectory(knowledgeTestIndexPath);
-  await atomicWriteText3(knowledgeTestIndexPath, `${JSON.stringify(result.knowledgeTestIndex, null, 2)}
+    await ensureParentDirectory(knowledgeTestIndexPath);
+    await atomicWriteText3(knowledgeTestIndexPath, `${JSON.stringify(result.knowledgeTestIndex, null, 2)}
 `);
-  if (existingMeta === void 0 || stableStringify(existingMeta) !== stableStringify(result.meta)) {
-    await recordBaselineSynced(projectRoot, {
-      previousRevision: existingMeta?.revision,
-      revision: result.meta.revision,
-      syncedFiles: collectSyncedFiles(existingMeta, result.meta),
-      acceptedStableIds: collectStableIds(result.meta),
-      driftDetails: collectDriftDetails(existingMeta, result.meta),
-      source: options.source
-    });
-  }
-  return result;
+    if (existingMeta === void 0 || stableStringify(existingMeta) !== stableStringify(result.meta)) {
+      await recordBaselineSynced(projectRoot, {
+        previousRevision: existingMeta?.revision,
+        revision: result.meta.revision,
+        syncedFiles: collectSyncedFiles(existingMeta, result.meta),
+        acceptedStableIds: collectStableIds(result.meta),
+        driftDetails: collectDriftDetails(existingMeta, result.meta),
+        source: options.source
+      });
+    }
+    return result;
+  });
 }
 var knowledgeMetaCache = /* @__PURE__ */ new Map();
 var __knowledgeMetaCacheStats = { fileReads: 0 };
@@ -992,13 +1012,6 @@ function resolveContentRefPath(projectRoot, contentRef) {
 async function findKnowledgeFiles(projectRoot) {
   const teamRoot = join4(projectRoot, ".fabric", "knowledge");
   const personalRoot = join4(resolvePersonalRoot(), ".fabric", "knowledge");
-  try {
-    await mkdir3(personalRoot, { recursive: true });
-    for (const sub of KNOWLEDGE_SUBDIRS) {
-      await mkdir3(join4(personalRoot, sub), { recursive: true });
-    }
-  } catch {
-  }
   const files = [];
   for (const [root, prefix] of [
     [teamRoot, TEAM_CONTENT_REF_PREFIX],
@@ -1390,6 +1403,16 @@ function extractDescriptionFromFrontmatter(frontmatter) {
     related: knowledge.related
   };
 }
+function isForbiddenCrossLayerEdge(sourceLayer, targetId) {
+  if (sourceLayer !== "team") {
+    return false;
+  }
+  const decoded = parseKnowledgeId(targetId);
+  if (decoded === null) {
+    return false;
+  }
+  return decoded.layer === "personal";
+}
 function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
   const rawId = extractScalar(frontmatter, "id");
   const rawType = extractScalar(frontmatter, "type");
@@ -1469,7 +1492,18 @@ function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
   const rawRelevanceScope = extractScalar(frontmatter, "relevance_scope");
   const relevance_scope = rawRelevanceScope === "narrow" || rawRelevanceScope === "broad" ? rawRelevanceScope : "broad";
   const relevance_paths = extractInlineArray(frontmatter, "relevance_paths");
-  const related = extractInlineArray(frontmatter, "related");
+  const rawRelated = extractInlineArray(frontmatter, "related");
+  const sourceLayer = knowledge_layer ?? (id !== void 0 ? parseKnowledgeId(id)?.layer ?? "team" : "team");
+  const related = rawRelated.filter((targetId) => {
+    if (isForbiddenCrossLayerEdge(sourceLayer, targetId)) {
+      process.stderr.write(
+        `[fabric] frontmatter: stripping forbidden cross-layer related edge ${id ?? "(team entry)"} \u2192 ${targetId} (KT\u2192KP topology leak; \xA74 privacy iron law)
+`
+      );
+      return false;
+    }
+    return true;
+  });
   return {
     id,
     knowledge_type,
@@ -1934,15 +1968,36 @@ function readSelectionTokenTtlMs(projectRoot) {
     return void 0;
   }
 }
+var DEFAULT_EMBED_MODEL = "fast-bge-small-zh-v1.5";
+var SUPPORTED_EMBED_MODELS = /* @__PURE__ */ new Set([
+  "fast-bge-small-zh-v1.5",
+  "fast-multilingual-e5-large",
+  "fast-bge-small-en-v1.5",
+  "fast-bge-small-en",
+  "fast-bge-base-en-v1.5",
+  "fast-bge-base-en",
+  "fast-all-MiniLM-L6-v2"
+]);
 function readEmbedConfig(projectRoot) {
   try {
     const config = readFabricConfig(projectRoot);
     const enabled = config.embed_enabled === true;
     const rawWeight = config.embed_weight;
     const weight = typeof rawWeight === "number" && Number.isInteger(rawWeight) && rawWeight >= 0 && rawWeight <= 49 ? rawWeight : 30;
-    return { enabled, weight };
+    const rawModel = config.embed_model;
+    const model = typeof rawModel === "string" && SUPPORTED_EMBED_MODELS.has(rawModel) ? rawModel : DEFAULT_EMBED_MODEL;
+    return { enabled, weight, model };
+  } catch {
+    return { enabled: false, weight: 30, model: DEFAULT_EMBED_MODEL };
+  }
+}
+function readDefaultLayerFilter(projectRoot) {
+  try {
+    const config = readFabricConfig(projectRoot);
+    const raw = config.default_layer_filter;
+    return raw === "team" || raw === "personal" ? raw : "both";
   } catch {
-    return { enabled: false, weight: 30 };
+    return "both";
   }
 }
 function readPlanContextTopK(projectRoot) {
@@ -1968,10 +2023,10 @@ function readOrphanDemoteThresholdDays(projectRoot) {
       }
       return v;
     };
-    const s = validate(cfg.orphan_demote_stable_days);
-    if (s !== void 0) out.stable = s;
-    const e = validate(cfg.orphan_demote_endorsed_days);
-    if (e !== void 0) out.endorsed = e;
+    const proven = validate(cfg.orphan_demote_proven_days) ?? validate(cfg.orphan_demote_stable_days);
+    if (proven !== void 0) out.stable = proven;
+    const verified = validate(cfg.orphan_demote_verified_days) ?? validate(cfg.orphan_demote_endorsed_days);
+    if (verified !== void 0) out.endorsed = verified;
     const d = validate(cfg.orphan_demote_draft_days);
     if (d !== void 0) out.draft = d;
     return out;
@@ -1979,12 +2034,27 @@ function readOrphanDemoteThresholdDays(projectRoot) {
     return {};
   }
 }
+function readConflictLintThreshold(projectRoot) {
+  try {
+    const cfgPath = join6(projectRoot, ".fabric", "fabric-config.json");
+    if (!existsSync4(cfgPath)) return void 0;
+    const parsed = JSON.parse(readFileSync2(cfgPath, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+    const v = parsed.conflict_lint_similarity_threshold;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1) {
+      return v;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
 
 // src/services/extract-knowledge.ts
 import { existsSync as existsSync5 } from "fs";
 import { readFile as readFile5 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { join as join7, relative as relative2 } from "path";
+import { join as join8, relative as relative2 } from "path";
 import {
   PROPOSED_REASON_DESCRIPTIONS
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
@@ -2090,8 +2160,44 @@ async function emitAutoHealEventBestEffort(projectRoot, payload) {
   }
 }
 
+// src/services/cross-store-write.ts
+import { join as join7 } from "path";
+import {
+  STORE_LAYOUT,
+  STORE_PENDING_DIR,
+  buildStoreResolveInput,
+  createStoreResolver,
+  resolveGlobalRoot,
+  storeRelativePath
+} from "@fenglimg/fabric-shared";
+import { StoreWriteTargetUnresolvedError } from "@fenglimg/fabric-shared/errors";
+function writeTargetUnresolved(layer) {
+  const actionHint = layer === "personal" ? "run `fabric install --global` to mint your personal store, then retry" : "mount + select a team store: `fabric install --global` then `fabric store bind <alias>` and `fabric store switch-write <alias>`, then retry";
+  return new StoreWriteTargetUnresolvedError(
+    `no ${layer} write-target store resolved \u2014 knowledge writes are store-only (dual-root co-location removed)`,
+    { actionHint, fixable: true, details: { layer } }
+  );
+}
+function resolveWriteTargetStoreDir(layer, projectRoot) {
+  const input = buildStoreResolveInput(projectRoot);
+  if (input === null) {
+    throw writeTargetUnresolved(layer);
+  }
+  const scope = layer === "personal" ? "personal" : "team";
+  const { target } = createStoreResolver().resolveWriteTarget(input, scope);
+  if (target === null) {
+    throw writeTargetUnresolved(layer);
+  }
+  return join7(resolveGlobalRoot(), storeRelativePath(target.store_uuid));
+}
+function resolveStorePendingBase(layer, projectRoot) {
+  return join7(resolveWriteTargetStoreDir(layer, projectRoot), STORE_LAYOUT.knowledgeDir, STORE_PENDING_DIR);
+}
+function resolveStoreCanonicalBase(layer, projectRoot) {
+  return join7(resolveWriteTargetStoreDir(layer, projectRoot), STORE_LAYOUT.knowledgeDir);
+}
+
 // src/services/extract-knowledge.ts
-var TEAM_PENDING_REL = ".fabric/knowledge/pending";
 var SLUG_MAX_LENGTH = 40;
 var INJECTION_PATTERNS = [
   {
@@ -2160,10 +2266,7 @@ function sanitizeInjectionFields(fields) {
   return { sanitized: out, allRedactions };
 }
 function pendingBase(layer, projectRoot) {
-  if (layer === "personal") {
-    return join7(resolvePersonalRoot3(), ".fabric", "knowledge", "pending");
-  }
-  return join7(projectRoot, TEAM_PENDING_REL);
+  return resolveStorePendingBase(layer, projectRoot);
 }
 function resolvePersonalRoot3() {
   return process.env.FABRIC_HOME ?? homedir3();
@@ -2277,7 +2380,7 @@ async function extractKnowledge(projectRoot, input) {
     primarySession,
     baseIdempotencyKey: idempotencyKey
   });
-  const reportedPath = layer === "personal" ? `~/${relative2(resolvePersonalRoot3(), absolutePath)}` : relative2(projectRoot, absolutePath);
+  const reportedPath = `~/${relative2(resolvePersonalRoot3(), absolutePath)}`;
   const effectiveSanitizedSlug = chosenSlug;
   const effectiveIdempotencyKey = chosenKey;
   await ensureParentDirectory(absolutePath);
@@ -2361,7 +2464,7 @@ var SLUG_DISAMBIGUATE_MAX_VARIANTS = 9;
 async function resolveDisambiguatedSlugPath(args) {
   for (let n = 1; n <= SLUG_DISAMBIGUATE_MAX_VARIANTS; n += 1) {
     const candidateSlug = n === 1 ? args.slug : `${args.slug}-${n}`;
-    const candidatePath = join7(args.baseDir, args.type, `${candidateSlug}.md`);
+    const candidatePath = join8(args.baseDir, args.type, `${candidateSlug}.md`);
     const candidateKey = n === 1 ? args.baseIdempotencyKey : sha256(
       JSON.stringify({
         source_session: args.primarySession,
@@ -2599,11 +2702,11 @@ function readFrontmatterKey(content, key) {
   }
   for (const rawLine of block.split(/\r?\n/u)) {
     const line = rawLine.trim();
-    const sep4 = line.indexOf(":");
-    if (sep4 === -1) continue;
-    const k = line.slice(0, sep4).trim();
+    const sep5 = line.indexOf(":");
+    if (sep5 === -1) continue;
+    const k = line.slice(0, sep5).trim();
     if (k === key) {
-      return line.slice(sep4 + 1).trim();
+      return line.slice(sep5 + 1).trim();
     }
   }
   return void 0;
@@ -2674,7 +2777,7 @@ import { tokenize as tokenize2 } from "@fenglimg/fabric-shared";
 
 // src/services/get-knowledge.ts
 import { readFile as readFile6 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { deriveAgentsMetaLayer as deriveAgentsMetaLayer2 } from "@fenglimg/fabric-shared";
 import { minimatch } from "minimatch";
 async function getKnowledge(projectRoot, input) {
@@ -2714,7 +2817,7 @@ async function loadGetKnowledgeContext(projectRoot) {
     return cached;
   }
   const meta = await readAgentsMeta(projectRoot);
-  const l0Content = await readFile6(join8(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
+  const l0Content = await readFile6(join9(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
   const context = {
     meta,
     l0Content,
@@ -2849,11 +2952,98 @@ async function readRuleContent(projectRoot, file, fileContentCache) {
   if (cached !== void 0) {
     return await cached;
   }
-  const pending = readFile6(join8(projectRoot, file), "utf8");
+  const pending = readFile6(join9(projectRoot, file), "utf8");
   fileContentCache.set(file, pending);
   return await pending;
 }
 
+// src/services/cross-store-recall.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join10 } from "path";
+import {
+  buildStoreResolveInput as buildStoreResolveInput2,
+  createStoreResolver as createStoreResolver2,
+  readKnowledgeAcrossStores,
+  resolveGlobalRoot as resolveGlobalRoot2,
+  storeRelativePath as storeRelativePath2
+} from "@fenglimg/fabric-shared";
+function walkReadSetStores(projectRoot) {
+  const resolveInput = buildStoreResolveInput2(projectRoot);
+  if (resolveInput === null) {
+    return [];
+  }
+  const readSet = createStoreResolver2().resolveReadSet(resolveInput);
+  if (readSet.stores.length === 0) {
+    return [];
+  }
+  const personalUuids = new Set(
+    resolveInput.mountedStores.filter((s) => s.personal).map((s) => s.store_uuid)
+  );
+  const globalRoot = resolveGlobalRoot2();
+  const dirs = readSet.stores.map((entry) => ({
+    store_uuid: entry.store_uuid,
+    alias: entry.alias,
+    dir: join10(globalRoot, storeRelativePath2(entry.store_uuid))
+  }));
+  const entries = [];
+  for (const ref of readKnowledgeAcrossStores(dirs)) {
+    let source;
+    try {
+      source = readFileSync3(ref.file, "utf8");
+    } catch {
+      continue;
+    }
+    const stableId = deriveRuleIdentity(ref.file, source, void 0).stableId;
+    const layer = personalUuids.has(ref.store_uuid) ? "personal" : "team";
+    entries.push({
+      qualifiedId: `${ref.alias}:${stableId}`,
+      file: ref.file,
+      alias: ref.alias,
+      layer,
+      source
+    });
+  }
+  return entries;
+}
+async function buildCrossStoreRawItems(projectRoot) {
+  const items = [];
+  for (const entry of walkReadSetStores(projectRoot)) {
+    const baseDescription = extractRuleDescription(entry.source);
+    if (baseDescription === void 0) {
+      continue;
+    }
+    items.push({
+      stable_id: entry.qualifiedId,
+      description: { ...baseDescription, knowledge_layer: entry.layer }
+    });
+  }
+  return items;
+}
+function buildCrossStoreBodyIndex(projectRoot) {
+  const index = /* @__PURE__ */ new Map();
+  for (const entry of walkReadSetStores(projectRoot)) {
+    if (!index.has(entry.qualifiedId)) {
+      index.set(entry.qualifiedId, { file: entry.file, layer: entry.layer });
+    }
+  }
+  return index;
+}
+function collectStoreKnowledgeSummaries(projectRoot) {
+  const out = [];
+  for (const entry of walkReadSetStores(projectRoot)) {
+    const description = extractRuleDescription(entry.source);
+    if (description === void 0) {
+      continue;
+    }
+    out.push({
+      stableId: entry.qualifiedId,
+      summary: description.summary ?? "",
+      layer: entry.layer
+    });
+  }
+  return out;
+}
+
 // src/services/id-redirect.ts
 var DEFAULT_REDIRECT_WINDOW_MS = 30 * 24 * 60 * 60 * 1e3;
 async function loadIdRedirectMap(projectRoot, options = {}) {
@@ -3066,7 +3256,14 @@ function buildQueryTerms(text) {
 // src/services/vector-retrieval.ts
 var embedderLoad;
 var OPTIONAL_EMBED_PACKAGE = "fastembed";
-async function loadEmbedder() {
+function buildEmbedInitOptions(modelName) {
+  return {
+    maxLength: 512,
+    cacheDir: process.env.FABRIC_EMBED_CACHE_DIR,
+    ...typeof modelName === "string" && modelName.length > 0 ? { model: modelName } : {}
+  };
+}
+async function loadEmbedder(modelName) {
   if (embedderLoad === void 0) {
     embedderLoad = (async () => {
       try {
@@ -3075,10 +3272,7 @@ async function loadEmbedder() {
         if (mod?.FlagEmbedding?.init === void 0) {
           return null;
         }
-        const model = await mod.FlagEmbedding.init({
-          maxLength: 512,
-          cacheDir: process.env.FABRIC_EMBED_CACHE_DIR
-        });
+        const model = await mod.FlagEmbedding.init(buildEmbedInitOptions(modelName));
         return {
           async embed(texts) {
             const out = [];
@@ -3245,7 +3439,11 @@ async function planContext(projectRoot, input) {
     targetPaths: input.target_paths ?? dedupePaths(input.paths),
     queryTerms: buildQueryTerms(queryText)
   };
-  const { rawItems, suppressedStableIds } = buildRawDescriptionItems(meta);
+  const { rawItems: projectRawItems, suppressedStableIds } = buildRawDescriptionItems(meta);
+  const storeRawItems = await buildCrossStoreRawItems(projectRoot).catch(() => []);
+  const allRawItems = [...projectRawItems, ...storeRawItems];
+  const effectiveLayerFilter = input.layer_filter ?? readDefaultLayerFilter(projectRoot);
+  const rawItems = effectiveLayerFilter === "both" ? allRawItems : allRawItems.filter((item) => item.description.knowledge_layer === effectiveLayerFilter);
   const docTexts = /* @__PURE__ */ new Map();
   for (const item of rawItems) {
     docTexts.set(item.stable_id, documentTextForItem(item.description));
@@ -3256,7 +3454,7 @@ async function planContext(projectRoot, input) {
   }
   const embedConfig = readEmbedConfig(projectRoot);
   if (embedConfig.enabled && queryText.trim().length > 0 && rawItems.length > 0) {
-    const embedder = await loadEmbedder();
+    const embedder = await loadEmbedder(embedConfig.model);
     const vectorScores = await buildVectorScores(
       embedder,
       queryText,
@@ -3274,7 +3472,27 @@ async function planContext(projectRoot, input) {
   const rankedCandidates = dedupeDescriptionIndex(builtItems);
   const topK = readPlanContextTopK(projectRoot);
   const omittedCandidateCount = Math.max(0, rankedCandidates.length - topK);
-  const candidates = omittedCandidateCount > 0 ? rankedCandidates.slice(0, topK) : rankedCandidates;
+  const topKCandidates = omittedCandidateCount > 0 ? rankedCandidates.slice(0, topK) : rankedCandidates;
+  let candidates = topKCandidates;
+  const relatedAppended = {};
+  if (input.include_related === true) {
+    const inTopK = new Set(topKCandidates.map((item) => item.stable_id));
+    const rankedById = new Map(rankedCandidates.map((item) => [item.stable_id, item]));
+    const appended = [];
+    for (const surfaced of topKCandidates) {
+      for (const rel of surfaced.description.related ?? []) {
+        if (inTopK.has(rel)) continue;
+        if (relatedAppended[rel] !== void 0) continue;
+        const neighbour = rankedById.get(rel);
+        if (neighbour === void 0) continue;
+        relatedAppended[rel] = surfaced.stable_id;
+        appended.push(neighbour);
+      }
+    }
+    if (appended.length > 0) {
+      candidates = [...topKCandidates, ...appended];
+    }
+  }
   const entries = uniquePaths.map((path2) => ({
     path: path2,
     requirement_profile: buildRequirementProfile(path2, input)
@@ -3308,7 +3526,11 @@ async function planContext(projectRoot, input) {
       auto_healed: true,
       previous_revision_hash: firstSeenPreviousRevision
     } : {},
-    ...redirects !== void 0 ? { redirects } : {}
+    ...redirects !== void 0 ? { redirects } : {},
+    // lifecycle-refactor W3-T2 (§7): surface the related-expansion provenance map
+    // ONLY when at least one neighbour was actually appended. Empty (graph-empty
+    // no-op) → field omitted, steady-state wire shape unchanged.
+    ...Object.keys(relatedAppended).length > 0 ? { related_appended: relatedAppended } : {}
   };
   bumpCounter(projectRoot, METRIC_COUNTER_NAMES.knowledge_context_planned);
   try {
@@ -3594,7 +3816,7 @@ function registerPlanContext(server, tracker) {
       outputSchema: planContextOutputSchema,
       annotations: planContextAnnotations
     },
-    async ({ paths, intent, known_tech, detected_entities, client_hash, correlation_id, session_id }) => {
+    async ({ paths, intent, known_tech, detected_entities, client_hash, correlation_id, session_id, target_paths, layer_filter }) => {
       const requestId = randomUUID3();
       tracker?.enter(requestId);
       try {
@@ -3609,7 +3831,12 @@ function registerPlanContext(server, tracker) {
           detected_entities,
           client_hash,
           correlation_id,
-          session_id
+          session_id,
+          // F54 (ISS-20260531-090): these were declared in
+          // planContextInputSchema but never forwarded to the service, so any
+          // client/LLM-supplied value was silently discarded.
+          target_paths,
+          layer_filter
         });
         let response = {
           ...result,
@@ -3687,7 +3914,7 @@ import { enforcePayloadLimit as enforcePayloadLimit3 } from "@fenglimg/fabric-sh
 // src/services/knowledge-sections.ts
 import { readFile as readFile8 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { join as join9 } from "path";
+import { join as join11 } from "path";
 import { deriveAgentsMetaLayer as deriveAgentsMetaLayer3 } from "@fenglimg/fabric-shared";
 import { McpToolError } from "@fenglimg/fabric-shared/errors";
 var PRIORITY_ORDER = {
@@ -3729,13 +3956,25 @@ async function getKnowledgeSections(projectRoot, input) {
   const { meta } = await loadActiveMeta(projectRoot, { caller: "getKnowledgeSections" });
   const selectedStableIds = [...token.required_stable_ids, ...rewrittenAiSelected];
   const ruleNodeIndex = buildRuleNodeIndex(meta);
+  const storeBodyIndex = buildCrossStoreBodyIndex(projectRoot);
+  const unresolvedSelectedIds = [];
+  const storeSelected = [];
   const selectedRules = sortRuleNodes(
-    selectedStableIds.map((stableId) => {
+    selectedStableIds.flatMap((stableId) => {
       const entry = ruleNodeIndex.get(stableId);
       if (entry === void 0) {
+        if (stableId.includes(":")) {
+          const ref = storeBodyIndex.get(stableId);
+          if (ref !== void 0) {
+            storeSelected.push({ stableId, ref });
+          } else {
+            unresolvedSelectedIds.push(stableId);
+          }
+          return [];
+        }
         throw new Error(`Selected rule is not present in agents.meta.json: ${stableId}`);
       }
-      return entry;
+      return [entry];
     })
   );
   const diagnostics = [];
@@ -3759,6 +3998,29 @@ async function getKnowledgeSections(projectRoot, input) {
       body
     });
   }
+  for (const { stableId, ref } of storeSelected) {
+    let content;
+    try {
+      content = await readFile8(ref.file, "utf8");
+    } catch {
+      unresolvedSelectedIds.push(stableId);
+      continue;
+    }
+    rules.push({
+      stable_id: stableId,
+      level: "L1",
+      path: ref.file,
+      body: extractBody(content)
+    });
+  }
+  for (const stableId of unresolvedSelectedIds) {
+    diagnostics.push({
+      code: "unresolved_selected_id",
+      severity: "warn",
+      stable_id: stableId,
+      message: `Selected rule '${stableId}' is not present in the project's agents.meta.json or any read-set store \u2014 skipped (deleted, layer-flipped, or its store is not bound).`
+    });
+  }
   const result = {
     revision_hash: meta.revision,
     selected_stable_ids: rules.map((rule) => rule.stable_id),
@@ -3835,12 +4097,6 @@ function validateAiSelections(aiSelectableStableIds, aiSelectedStableIds, aiSele
         `Invalid rule selection "${stableId}": not in this token's plan-context candidates. Pass only stable_ids from fab_plan_context candidates[].stable_id.`
       );
     }
-    if (aiSelectionReasons[stableId]?.trim() === "") {
-      throw new Error(`Missing AI selection reason for ${stableId}`);
-    }
-    if (aiSelectionReasons[stableId] === void 0) {
-      throw new Error(`Missing AI selection reason for ${stableId}`);
-    }
   }
 }
 function buildRuleNodeIndex(meta) {
@@ -3887,9 +4143,9 @@ function outputLevelOrder(level) {
 function resolveRuleSourcePath(projectRoot, contentRef) {
   if (contentRef.startsWith("~/.fabric/knowledge/")) {
     const home = process.env.FABRIC_HOME ?? homedir4();
-    return join9(home, ".fabric", "knowledge", contentRef.slice("~/.fabric/knowledge/".length));
+    return join11(home, ".fabric", "knowledge", contentRef.slice("~/.fabric/knowledge/".length));
   }
-  return join9(projectRoot, contentRef);
+  return join11(projectRoot, contentRef);
 }
 function pickSelectionReasons(selectedStableIds, reasons) {
   return Object.fromEntries(selectedStableIds.map((stableId) => [stableId, reasons[stableId] ?? ""]));
@@ -3964,12 +4220,20 @@ async function recall(projectRoot, input) {
   });
   return {
     ...planResult,
-    rules: sectionsResult.rules,
+    rules: sectionsResult.rules.map(attachStoreProvenance),
     selected_stable_ids: sectionsResult.selected_stable_ids,
     diagnostics: sectionsResult.diagnostics,
     ...packaging
   };
 }
+function attachStoreProvenance(rule) {
+  const colon = rule.stable_id.indexOf(":");
+  if (colon <= 0) {
+    return rule;
+  }
+  const alias = rule.stable_id.slice(0, colon);
+  return { ...rule, store: { alias } };
+}
 function buildRecallPackaging(planResult, relatedAvailableNotIncluded) {
   const omitted = planResult.omitted_candidate_count ?? 0;
   const nextSteps = [];
@@ -4009,6 +4273,7 @@ function registerRecall(server, tracker) {
       correlation_id,
       session_id,
       target_paths,
+      layer_filter,
       ids,
       include_related
     }) => {
@@ -4031,6 +4296,9 @@ function registerRecall(server, tracker) {
           correlation_id,
           session_id,
           target_paths,
+          // F54 (ISS-20260531-090): forwarded so recall→planContext honors the
+          // declared layer restriction instead of silently discarding it.
+          layer_filter,
           ids,
           include_related
         };
@@ -4286,19 +4554,19 @@ import { execFileSync } from "child_process";
 import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile10, readdir as readdir3, unlink } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { basename, join as join10, relative as relative3, resolve as resolve3 } from "path";
+import { basename, join as join12, relative as relative3, resolve as resolve3, sep as sep3 } from "path";
 
 // src/services/knowledge-id-allocator.ts
 import { readFile as readFile9, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname2 } from "path";
-import { mkdir as mkdir4 } from "fs/promises";
+import { mkdir as mkdir3 } from "fs/promises";
 import {
   AgentsMetaCountersSchema,
   agentsMetaSchema as agentsMetaSchema4,
   allocateKnowledgeId,
   defaultAgentsMetaCounters as defaultAgentsMetaCounters2
 } from "@fenglimg/fabric-shared";
-import { atomicWriteJson as atomicWriteJson2, withFileLock } from "@fenglimg/fabric-shared/node/atomic-write";
+import { atomicWriteJson as atomicWriteJson2, withFileLock as withFileLock3 } from "@fenglimg/fabric-shared/node/atomic-write";
 import { GenericIOError } from "@fenglimg/fabric-shared/errors";
 var KnowledgeIdAllocator = class {
   constructor(metaPath) {
@@ -4310,7 +4578,7 @@ var KnowledgeIdAllocator = class {
    * the advanced counter to `agents.meta.json`.
    */
   async allocate(layer, type) {
-    return withFileLock(`${this.metaPath}.lock`, async () => {
+    return withFileLock3(`${this.metaPath}.lock`, async () => {
       const meta = await this.readMeta();
       const counters2 = this.normalizeCounters(meta.counters);
       const { id, nextCounters } = allocateKnowledgeId(layer, type, counters2);
@@ -4373,20 +4641,13 @@ var KnowledgeIdAllocator = class {
   }
 };
 async function ensureParentDirectory2(filePath) {
-  await mkdir4(dirname2(filePath), { recursive: true });
+  await mkdir3(dirname2(filePath), { recursive: true });
 }
 function isNodeError4(err) {
   return err instanceof Error && typeof err.code === "string";
 }
 
 // src/services/review.ts
-var PENDING_BASE_TEAM_REL = ".fabric/knowledge/pending";
-function pendingBaseAbs(layer, projectRoot) {
-  if (layer === "personal") {
-    return join10(resolvePersonalRoot4(), ".fabric", "knowledge", "pending");
-  }
-  return join10(projectRoot, PENDING_BASE_TEAM_REL);
-}
 var PLURAL_TYPES = [
   "decisions",
   "pitfalls",
@@ -4444,29 +4705,50 @@ async function reviewKnowledge(projectRoot, input) {
     }
   }
 }
+function storeKnowledgeRoots(projectRoot) {
+  const roots = [];
+  for (const layer of ["team", "personal"]) {
+    try {
+      roots.push(resolve3(resolveStoreCanonicalBase(layer, projectRoot)));
+    } catch {
+    }
+  }
+  return roots;
+}
+function isUnder(abs, root) {
+  return abs === root || abs.startsWith(root + "/");
+}
 function resolveSandboxedPath(projectRoot, candidate, options = {}) {
   if (candidate.length === 0) {
     throw new Error("path is empty");
   }
   const projectKnowledgeRoot = resolve3(projectRoot, ".fabric", "knowledge");
   const personalKnowledgeRoot = resolve3(resolvePersonalRoot4(), ".fabric", "knowledge");
+  const storeRoots = storeKnowledgeRoots(projectRoot);
   if (candidate.startsWith("~/")) {
     if (options.allowPersonal !== true) {
       throw new Error(`personal-root path not allowed for this action: ${candidate}`);
     }
     const abs = resolve3(resolvePersonalRoot4(), candidate.slice(2));
-    if (abs !== personalKnowledgeRoot && !abs.startsWith(personalKnowledgeRoot + "/")) {
+    if (!isUnder(abs, personalKnowledgeRoot)) {
       throw new Error(`path escapes personal knowledge root: ${candidate}`);
     }
     return { abs, isInProjectTree: false };
   }
+  if (candidate.startsWith("/")) {
+    const abs = resolve3(candidate);
+    if (storeRoots.some((root) => isUnder(abs, root))) {
+      return { abs, isInProjectTree: false };
+    }
+    throw new Error(`path escapes knowledge root: ${candidate}`);
+  }
   const projectAbs = resolve3(projectRoot, candidate);
-  if (projectAbs === projectKnowledgeRoot || projectAbs.startsWith(projectKnowledgeRoot + "/")) {
+  if (isUnder(projectAbs, projectKnowledgeRoot)) {
     return { abs: projectAbs, isInProjectTree: true };
   }
   if (options.allowPersonal === true) {
     const personalAbs = resolve3(resolvePersonalRoot4(), candidate);
-    if (personalAbs === personalKnowledgeRoot || personalAbs.startsWith(personalKnowledgeRoot + "/")) {
+    if (isUnder(personalAbs, personalKnowledgeRoot)) {
       return { abs: personalAbs, isInProjectTree: false };
     }
   }
@@ -4488,13 +4770,24 @@ function isVisibleByLifecycle(fm, filters) {
 async function listPending(projectRoot, filters) {
   const items = [];
   const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
-  const sources = [
-    { origin: "team", root: pendingBaseAbs("team", projectRoot) },
-    { origin: "personal", root: pendingBaseAbs("personal", projectRoot) }
-  ];
+  const sources = [];
+  for (const origin of ["team", "personal"]) {
+    try {
+      const pendingRoot = resolveStorePendingBase(origin, projectRoot);
+      sources.push({ origin, root: pendingRoot, isStore: true });
+      if (filters?.include_rejected === true) {
+        sources.push({
+          origin,
+          root: pendingRoot.replace(`${sep3}pending`, `${sep3}rejected`),
+          isStore: true
+        });
+      }
+    } catch {
+    }
+  }
   for (const source of sources) {
     for (const type of typesToScan) {
-      const dir = join10(source.root, type);
+      const dir = join12(source.root, type);
       if (!existsSync6(dir)) {
         continue;
       }
@@ -4506,7 +4799,7 @@ async function listPending(projectRoot, filters) {
       }
       for (const name of entries) {
         if (!name.endsWith(".md")) continue;
-        const absolutePath = join10(dir, name);
+        const absolutePath = join12(dir, name);
         let content;
         try {
           content = await readFile10(absolutePath, "utf8");
@@ -4536,13 +4829,15 @@ async function listPending(projectRoot, filters) {
         if (!isVisibleByLifecycle(fm, filters)) {
           continue;
         }
-        const reportedPath = source.origin === "personal" ? `~/${relative3(resolvePersonalRoot4(), absolutePath)}` : relative3(projectRoot, absolutePath);
+        const reportedPath = source.isStore ? absolutePath : source.origin === "personal" ? `~/${relative3(resolvePersonalRoot4(), absolutePath)}` : relative3(projectRoot, absolutePath);
         items.push({
           pending_path: reportedPath,
           // v2.0.0-rc.27 TASK-001 (§2.12): absolute path companion for
           // personal entries so programmatic consumers (Read, fs.readFile)
-          // don't need to shell-expand the `~` themselves.
-          ...source.origin === "personal" ? { pending_path_absolute: absolutePath } : {},
+          // don't need to shell-expand the `~` themselves. Store entries
+          // already report an absolute pending_path, so the companion is
+          // emitted for non-store personal entries only.
+          ...source.origin === "personal" && !source.isStore ? { pending_path_absolute: absolutePath } : {},
           type,
           layer,
           maturity,
@@ -4562,7 +4857,7 @@ async function listPending(projectRoot, filters) {
 }
 async function approveAll(projectRoot, pendingPaths) {
   const allocator = new KnowledgeIdAllocator(
-    join10(projectRoot, ".fabric", "agents.meta.json")
+    join12(projectRoot, ".fabric", "agents.meta.json")
   );
   const approved = [];
   for (const pendingPath of pendingPaths) {
@@ -4576,17 +4871,26 @@ async function approveAll(projectRoot, pendingPaths) {
 async function approveOne(projectRoot, pendingPath, allocator) {
   let sourceAbs;
   let sourceOrigin;
+  let sourceIsStore = false;
   try {
     const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
-    const teamPendingAbs = pendingBaseAbs("team", projectRoot);
-    const personalPendingAbs = pendingBaseAbs("personal", projectRoot);
-    const inTeamPending = sandboxed.abs === teamPendingAbs || sandboxed.abs.startsWith(teamPendingAbs + "/");
-    const inPersonalPending = sandboxed.abs === personalPendingAbs || sandboxed.abs.startsWith(personalPendingAbs + "/");
+    const resolvePendingBaseOrNull = (layer) => {
+      try {
+        return resolveStorePendingBase(layer, projectRoot);
+      } catch {
+        return null;
+      }
+    };
+    const teamPendingAbs = resolvePendingBaseOrNull("team");
+    const personalPendingAbs = resolvePendingBaseOrNull("personal");
+    const inTeamPending = teamPendingAbs !== null && (sandboxed.abs === teamPendingAbs || sandboxed.abs.startsWith(teamPendingAbs + "/"));
+    const inPersonalPending = personalPendingAbs !== null && (sandboxed.abs === personalPendingAbs || sandboxed.abs.startsWith(personalPendingAbs + "/"));
     if (!inTeamPending && !inPersonalPending) {
       throw new Error(`approve path is outside .fabric/knowledge/pending/: ${pendingPath}`);
     }
     sourceAbs = sandboxed.abs;
     sourceOrigin = inPersonalPending ? "personal" : "team";
+    sourceIsStore = true;
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     await emitEventBestEffort2(projectRoot, {
@@ -4621,13 +4925,16 @@ async function approveOne(projectRoot, pendingPath, allocator) {
     const stableId = await allocator.allocate(layer, pluralType);
     allocatedId = stableId;
     const newFilename = `${stableId}--${slug}.md`;
-    const layerRoot = layer === "personal" ? join10(resolvePersonalRoot4(), ".fabric") : join10(projectRoot, ".fabric");
-    targetAbs = join10(layerRoot, "knowledge", pluralType, newFilename);
+    targetAbs = join12(resolveStoreCanonicalBase(layer, projectRoot), pluralType, newFilename);
     await ensureParentDirectory(targetAbs);
     const rewritten = rewriteFrontmatterForPromote(content, stableId);
     await atomicWriteText(targetAbs, rewritten);
     writtenTarget = true;
-    if (sourceOrigin === "team") {
+    if (sourceIsStore) {
+      if (existsSync6(sourceAbs)) {
+        await unlink(sourceAbs);
+      }
+    } else if (sourceOrigin === "team") {
       try {
         execFileSync("git", ["rm", "--quiet", "-f", pendingPath], {
           cwd: projectRoot,
@@ -4679,7 +4986,12 @@ async function rejectAll(projectRoot, pendingPaths, reason) {
       if (existsSync6(sandboxed.abs)) {
         const content = await readFile10(sandboxed.abs, "utf8");
         const merged = rewriteFrontmatterMerge(content, { status: "rejected" });
-        if (merged !== content) {
+        const rejectedAbs = sandboxed.abs.includes(`${sep3}pending${sep3}`) ? sandboxed.abs.replace(`${sep3}pending${sep3}`, `${sep3}rejected${sep3}`) : null;
+        if (rejectedAbs !== null) {
+          await ensureParentDirectory(rejectedAbs);
+          await atomicWriteText(rejectedAbs, merged);
+          await unlink(sandboxed.abs);
+        } else if (merged !== content) {
           await atomicWriteText(sandboxed.abs, merged);
         }
       }
@@ -4759,11 +5071,14 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
   const fromScope = fm.relevance_scope ?? "broad";
   const shouldAutoDegrade = fromScope === "narrow" && fromLayer === "team" && toLayer === "personal";
   const allocator = new KnowledgeIdAllocator(
-    join10(projectRoot, ".fabric", "agents.meta.json")
+    join12(projectRoot, ".fabric", "agents.meta.json")
   );
   const newStableId = await allocator.allocate(toLayer, pluralType);
-  const toRoot = toLayer === "personal" ? join10(resolvePersonalRoot4(), ".fabric") : join10(projectRoot, ".fabric");
-  const toAbs = join10(toRoot, "knowledge", pluralType, `${newStableId}--${slug}.md`);
+  const toAbs = join12(
+    resolveStoreCanonicalBase(toLayer, projectRoot),
+    pluralType,
+    `${newStableId}--${slug}.md`
+  );
   await ensureParentDirectory(toAbs);
   await emitEventBestEffort2(projectRoot, {
     event_type: "knowledge_promote_started",
@@ -4842,16 +5157,22 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
 async function searchEntries(projectRoot, query, filters) {
   const lowerQuery = query.toLowerCase();
   const items = [];
-  const sources = [
-    { root: pendingBaseAbs("team", projectRoot), isPending: true, isPersonal: false },
-    { root: pendingBaseAbs("personal", projectRoot), isPending: true, isPersonal: true },
-    { root: join10(projectRoot, ".fabric", "knowledge"), isPending: false, isPersonal: false },
-    { root: join10(resolvePersonalRoot4(), ".fabric", "knowledge"), isPending: false, isPersonal: true }
-  ];
+  const sources = [];
+  for (const layer of ["team", "personal"]) {
+    const isPersonal = layer === "personal";
+    try {
+      sources.push({ root: resolveStorePendingBase(layer, projectRoot), isPending: true, isPersonal, isStore: true });
+    } catch {
+    }
+    try {
+      sources.push({ root: resolveStoreCanonicalBase(layer, projectRoot), isPending: false, isPersonal, isStore: true });
+    } catch {
+    }
+  }
   const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
   for (const source of sources) {
     for (const type of typesToScan) {
-      const dir = join10(source.root, type);
+      const dir = join12(source.root, type);
       if (!existsSync6(dir)) continue;
       let entries;
       try {
@@ -4861,7 +5182,7 @@ async function searchEntries(projectRoot, query, filters) {
       }
       for (const name of entries) {
         if (!name.endsWith(".md")) continue;
-        const absolutePath = join10(dir, name);
+        const absolutePath = join12(dir, name);
         let content;
         try {
           content = await readFile10(absolutePath, "utf8");
@@ -4901,7 +5222,7 @@ async function searchEntries(projectRoot, query, filters) {
         ].map((s) => s.toLowerCase());
         const matches = haystacks.some((h) => h.includes(lowerQuery));
         if (!matches) continue;
-        const reportedPath = source.isPersonal ? `~/${relative3(resolvePersonalRoot4(), absolutePath)}` : relative3(projectRoot, absolutePath);
+        const reportedPath = source.isStore ? absolutePath : source.isPersonal ? `~/${relative3(resolvePersonalRoot4(), absolutePath)}` : relative3(projectRoot, absolutePath);
         items.push({
           area: source.isPending ? "pending" : "canonical",
           path: reportedPath,
@@ -4970,10 +5291,10 @@ function parseFrontmatter(content) {
   for (const rawLine of block.split(/\r?\n/u)) {
     const line = rawLine.trim();
     if (line.length === 0) continue;
-    const sep4 = line.indexOf(":");
-    if (sep4 === -1) continue;
-    const key = line.slice(0, sep4).trim();
-    const value = line.slice(sep4 + 1).trim();
+    const sep5 = line.indexOf(":");
+    if (sep5 === -1) continue;
+    const key = line.slice(0, sep5).trim();
+    const value = line.slice(sep5 + 1).trim();
     switch (key) {
       case "id":
         out.id = stripQuotes(value);
@@ -5082,17 +5403,17 @@ ${content}`;
   if (patch.summary !== void 0) updates.summary = `summary: ${quoteIfNeeded(patch.summary)}`;
   if (patch.layer !== void 0) updates.layer = `layer: ${patch.layer}`;
   if (patch.maturity !== void 0) updates.maturity = `maturity: ${patch.maturity}`;
-  if (patch.tags !== void 0) updates.tags = `tags: [${patch.tags.join(", ")}]`;
+  if (patch.tags !== void 0) updates.tags = `tags: ${flowArray(patch.tags)}`;
   if (patch.relevance_scope !== void 0) updates.relevance_scope = `relevance_scope: ${patch.relevance_scope}`;
-  if (patch.relevance_paths !== void 0) updates.relevance_paths = `relevance_paths: [${patch.relevance_paths.join(", ")}]`;
+  if (patch.relevance_paths !== void 0) updates.relevance_paths = `relevance_paths: ${flowArray(patch.relevance_paths)}`;
   if (patch.status !== void 0) updates.status = `status: ${patch.status}`;
   if (patch.deferred_until !== void 0) updates.deferred_until = `deferred_until: ${quoteIfNeeded(patch.deferred_until)}`;
   const lines = block.split(/\r?\n/u);
   const seen = /* @__PURE__ */ new Set();
   const newLines = [];
   for (const line of lines) {
-    const sep4 = line.indexOf(":");
-    const key = sep4 === -1 ? "" : line.slice(0, sep4).trim();
+    const sep5 = line.indexOf(":");
+    const key = sep5 === -1 ? "" : line.slice(0, sep5).trim();
     if (key in updates) {
       newLines.push(updates[key]);
       seen.add(key);
@@ -5117,18 +5438,27 @@ function appendPatchLines(lines, patch) {
   if (patch.summary !== void 0) lines.push(`summary: ${quoteIfNeeded(patch.summary)}`);
   if (patch.layer !== void 0) lines.push(`layer: ${patch.layer}`);
   if (patch.maturity !== void 0) lines.push(`maturity: ${patch.maturity}`);
-  if (patch.tags !== void 0) lines.push(`tags: [${patch.tags.join(", ")}]`);
+  if (patch.tags !== void 0) lines.push(`tags: ${flowArray(patch.tags)}`);
   if (patch.relevance_scope !== void 0) lines.push(`relevance_scope: ${patch.relevance_scope}`);
-  if (patch.relevance_paths !== void 0) lines.push(`relevance_paths: [${patch.relevance_paths.join(", ")}]`);
+  if (patch.relevance_paths !== void 0) lines.push(`relevance_paths: ${flowArray(patch.relevance_paths)}`);
   if (patch.status !== void 0) lines.push(`status: ${patch.status}`);
   if (patch.deferred_until !== void 0) lines.push(`deferred_until: ${quoteIfNeeded(patch.deferred_until)}`);
 }
+function flowArrayElement(value) {
+  if (/[\n\r,\[\]{}"#:]/u.test(value) || /^\s|\s$/u.test(value)) {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+function flowArray(values) {
+  return `[${values.map(flowArrayElement).join(", ")}]`;
+}
 function quoteIfNeeded(value) {
   if (/[\n\r]/u.test(value)) {
     return JSON.stringify(value);
   }
-  if (/[:#\[\]{}&*!|>'"%@`,]|^\s|\s$/u.test(value)) {
-    return `"${value.replace(/"/gu, '\\"')}"`;
+  if (/[\\:#\[\]{}&*!|>'"%@`,]|^\s|\s$/u.test(value)) {
+    return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"')}"`;
   }
   return value;
 }
@@ -5242,11 +5572,11 @@ function registerKnowledgeSections(server, tracker) {
 
 // src/services/doctor.ts
 import { execFileSync as execFileSync2, spawnSync } from "child_process";
-import { existsSync as existsSync8, readdirSync, readFileSync as readFileSync3, statSync as statSync4 } from "fs";
-import { access as access2, mkdir as mkdir6, readFile as readFile13, rename as rename2, unlink as unlink3, writeFile as writeFile4 } from "fs/promises";
+import { existsSync as existsSync8, readdirSync, readFileSync as readFileSync4, statSync as statSync4 } from "fs";
+import { access as access2, mkdir as mkdir5, readFile as readFile13, rename as rename2, unlink as unlink3, writeFile as writeFile4 } from "fs/promises";
 import { constants } from "fs";
 import { homedir as homedir6 } from "os";
-import { isAbsolute as isAbsolute2, join as join11, posix, relative as nodeRelative, resolve as resolve4, sep as sep3 } from "path";
+import { isAbsolute as isAbsolute2, join as join13, posix, relative as nodeRelative, resolve as resolve4, sep as sep4 } from "path";
 import { Script } from "vm";
 import { minimatch as minimatch3 } from "minimatch";
 import { ZodError } from "zod";
@@ -5271,7 +5601,7 @@ import {
   PAYLOAD_LIMIT_DEFAULT_HARD_BYTES,
   PAYLOAD_LIMIT_DEFAULT_WARN_BYTES
 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
-import { atomicWriteJson as atomicWriteJson3, atomicWriteText as atomicWriteText4 } from "@fenglimg/fabric-shared/node/atomic-write";
+import { atomicWriteJson as atomicWriteJson3, atomicWriteText as atomicWriteText4, withFileLock as withFileLock4 } from "@fenglimg/fabric-shared/node/atomic-write";
 
 // src/services/legacy-serve-lock-probe.ts
 import fs from "fs";
@@ -5502,6 +5832,54 @@ function matchesRelevancePath(editPath, relevancePaths) {
   }
   return false;
 }
+function recallPathOverlaps(editPath, recallPaths) {
+  if (recallPaths.length === 0) return false;
+  const e = normalizePath(editPath);
+  if (e.length === 0) return false;
+  for (const rp of recallPaths) {
+    const r = normalizePath(rp);
+    if (r.length === 0) continue;
+    if (e === r) return true;
+    if (e.endsWith("/" + r) || r.endsWith("/" + e)) return true;
+    if (e.startsWith(r + "/") || r.startsWith(e + "/")) return true;
+  }
+  return false;
+}
+function isSpecificGlob(glob) {
+  const g = glob.trim();
+  if (g.length === 0) return false;
+  return g !== "**/*" && g !== "**" && g !== "*";
+}
+function computeExposedAndMutated(args) {
+  const { narrowSurfacedBySession, dismissedBySession, editPathsBySession, kbIndex, idTypeMap } = args;
+  const qualifiedIds = /* @__PURE__ */ new Set();
+  let count = 0;
+  for (const [sessionId, surfacedIds] of narrowSurfacedBySession) {
+    const editPaths = editPathsBySession.get(sessionId);
+    if (editPaths === void 0 || editPaths.length === 0) continue;
+    const dismissed = dismissedBySession.get(sessionId);
+    for (const id of surfacedIds) {
+      if (dismissed !== void 0 && dismissed.has(id)) continue;
+      const kb = kbIndex.get(id);
+      if (kb === void 0 || kb.relevance_scope !== "narrow") continue;
+      const specificGlobs = kb.relevance_paths.filter(isSpecificGlob);
+      if (specificGlobs.length === 0) continue;
+      const type = idTypeMap.get(id);
+      if (type === "guidelines" || type === "processes") continue;
+      let mutated = false;
+      for (const p of editPaths) {
+        if (matchesRelevancePath(p, specificGlobs)) {
+          mutated = true;
+          break;
+        }
+      }
+      if (!mutated) continue;
+      count += 1;
+      qualifiedIds.add(id);
+    }
+  }
+  return { count, ids: [...qualifiedIds].sort() };
+}
 var ASSISTANT_TURN_COUNTER_PREFIX = "assistant_turn_observed";
 function sumFoldedTurnCounters(rows, options) {
   let sum = 0;
@@ -5525,6 +5903,7 @@ function sumFoldedTurnCounters(rows, options) {
 }
 async function runDoctorCiteCoverage(projectRoot, options) {
   const layerFilter = options.layer ?? "all";
+  const recallWindowMs = typeof options.recallWindowMs === "number" && options.recallWindowMs >= 0 ? options.recallWindowMs : 30 * 6e4;
   const marker = await ensureCitePolicyActivatedMarker(projectRoot);
   const contractMarker = await ensureCiteContractPolicyActivatedMarker(projectRoot);
   const idTypeMap = await loadKbIdTypeMap(projectRoot);
@@ -5591,6 +5970,10 @@ async function runDoctorCiteCoverage(projectRoot, options) {
   const assistantTurns = [];
   const editEvents = [];
   const fetchEvents = [];
+  const plannedEvents = [];
+  const hookSurfaceEvents = [];
+  const fileMutatedEvents = [];
+  const sessionEndedEvents = [];
   for (const event of ledgerEvents) {
     switch (event.event_type) {
       case "assistant_turn_observed":
@@ -5602,10 +5985,33 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       case "knowledge_sections_fetched":
         fetchEvents.push(event);
         break;
+      case "knowledge_context_planned":
+        plannedEvents.push(event);
+        break;
+      case "hook_surface_emitted":
+        hookSurfaceEvents.push(event);
+        break;
+      case "file_mutated":
+        fileMutatedEvents.push(event);
+        break;
+      case "session_ended":
+        sessionEndedEvents.push(event);
+        break;
       default:
         break;
     }
   }
+  const plannedBySession = /* @__PURE__ */ new Map();
+  for (const planned of plannedEvents) {
+    const sid = planned.session_id;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const list = plannedBySession.get(sid) ?? [];
+    list.push({ ts: planned.ts, target_paths: planned.target_paths ?? [] });
+    plannedBySession.set(sid, list);
+  }
+  for (const list of plannedBySession.values()) {
+    list.sort((a, b) => a.ts - b.ts);
+  }
   const filteredTurns = options.client === "all" ? assistantTurns : assistantTurns.filter((t) => t.client === options.client);
   let clientSessionIds = null;
   if (options.client !== "all") {
@@ -5677,6 +6083,7 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     perClientAccum.set(client, existing);
   };
   const sessionCitedKbs = /* @__PURE__ */ new Map();
+  const dismissedBySession = /* @__PURE__ */ new Map();
   const sessionEditPaths = /* @__PURE__ */ new Map();
   for (const edit of editEvents) {
     const sid = edit.session_id;
@@ -5754,6 +6161,8 @@ async function runDoctorCiteCoverage(projectRoot, options) {
   let totalTurns = 0;
   let qualifyingCites = 0;
   let recalledUnverified = 0;
+  const STORE_LOCAL_KEY = "local";
+  const byStoreQualifying = {};
   for (const turn of filteredTurns) {
     totalTurns += 1;
     bumpClient(turn.client, (m) => {
@@ -5766,6 +6175,15 @@ async function runDoctorCiteCoverage(projectRoot, options) {
         set.add(id);
       }
       sessionCitedKbs.set(sid, set);
+      for (let i = 0; i < turn.cite_tags.length; i += 1) {
+        const id = turn.cite_ids[i];
+        if (typeof id !== "string" || id.length === 0) continue;
+        if (categorizeCiteTag(turn.cite_tags[i]).category === "dismissed") {
+          const dset = dismissedBySession.get(sid) ?? /* @__PURE__ */ new Set();
+          dset.add(id);
+          dismissedBySession.set(sid, dset);
+        }
+      }
     }
     let turnHadApplied = false;
     for (const tag of turn.cite_tags) {
@@ -5792,6 +6210,14 @@ async function runDoctorCiteCoverage(projectRoot, options) {
           break;
       }
     }
+    const turnCiteStores = turn.cite_stores ?? [];
+    for (let i = 0; i < turn.cite_ids.length; i += 1) {
+      const tag = turn.cite_tags[i];
+      if (categorizeCiteTag(typeof tag === "string" ? tag : "none").category !== "applied") continue;
+      const rawStore = turnCiteStores[i];
+      const storeKey = typeof rawStore === "string" && rawStore.length > 0 ? rawStore : STORE_LOCAL_KEY;
+      byStoreQualifying[storeKey] = (byStoreQualifying[storeKey] ?? 0) + 1;
+    }
     if (turnHadApplied && !isRecallVerified(turn)) {
       recalledUnverified += 1;
       bumpClient(turn.client, (m) => {
@@ -5836,6 +6262,7 @@ async function runDoctorCiteCoverage(projectRoot, options) {
   let editsTouched = 0;
   let expectedButMissed = 0;
   let uncorrelatableEdits = 0;
+  let recallBackedEdits = 0;
   for (const edit of editEvents) {
     const sid = edit.session_id;
     const hasSid = typeof sid === "string" && sid.length > 0;
@@ -5846,6 +6273,17 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     }
     editsTouched += 1;
     if (!hasSid) continue;
+    const recalls = plannedBySession.get(sid);
+    if (recalls !== void 0) {
+      for (const recall2 of recalls) {
+        if (recall2.ts > edit.ts) break;
+        if (recallWindowMs > 0 && edit.ts - recall2.ts > recallWindowMs) continue;
+        if (recallPathOverlaps(edit.path, recall2.target_paths)) {
+          recallBackedEdits += 1;
+          break;
+        }
+      }
+    }
     const citedSet = sessionCitedKbs.get(sid) ?? /* @__PURE__ */ new Set();
     for (const [kbId, kb] of kbIndex) {
       if (kb.relevance_scope !== "narrow") continue;
@@ -5860,6 +6298,56 @@ async function runDoctorCiteCoverage(projectRoot, options) {
   const noncompliantCites = expectedButMissed;
   const complianceDenom = compliantCites + noncompliantCites;
   const citeComplianceRate = complianceDenom > 0 ? compliantCites / complianceDenom : null;
+  const recallCoverageRate = editsTouched > 0 ? recallBackedEdits / editsTouched : null;
+  const narrowSurfacedBySession = /* @__PURE__ */ new Map();
+  for (const surface of hookSurfaceEvents) {
+    if (surface.hook_name !== "knowledge-hint-narrow") continue;
+    if (surface.delivery_status !== "delivered") continue;
+    const sid = surface.session_id;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const set = narrowSurfacedBySession.get(sid) ?? /* @__PURE__ */ new Set();
+    for (const id of surface.rendered_ids) {
+      if (typeof id === "string" && id.length > 0) set.add(id);
+    }
+    narrowSurfacedBySession.set(sid, set);
+  }
+  const exposedAndMutated = computeExposedAndMutated({
+    narrowSurfacedBySession,
+    dismissedBySession,
+    editPathsBySession: sessionEditPaths,
+    kbIndex,
+    idTypeMap
+  });
+  const surfacedIdsByEvent = /* @__PURE__ */ new Map();
+  for (const surface of hookSurfaceEvents) {
+    surfacedIdsByEvent.set(surface.id, surface.rendered_ids);
+  }
+  const seenMutationKeys = /* @__PURE__ */ new Set();
+  const attributionKeys = /* @__PURE__ */ new Set();
+  let mutationsObserved = 0;
+  let unattributedWorkspaceDirty = 0;
+  for (const mutation of fileMutatedEvents) {
+    if (seenMutationKeys.has(mutation.tool_call_id)) continue;
+    seenMutationKeys.add(mutation.tool_call_id);
+    mutationsObserved += 1;
+    const sourceEventId = mutation.source_event_id;
+    const surfacedRenderedIds = typeof sourceEventId === "string" && sourceEventId.length > 0 ? surfacedIdsByEvent.get(sourceEventId) : void 0;
+    if (surfacedRenderedIds === void 0 || surfacedRenderedIds.length === 0) {
+      unattributedWorkspaceDirty += 1;
+      continue;
+    }
+    const storeId = mutation.store_id ?? "";
+    for (const stableId of surfacedRenderedIds) {
+      if (typeof stableId !== "string" || stableId.length === 0) continue;
+      attributionKeys.add(`${storeId}|${stableId}|${sourceEventId}`);
+    }
+  }
+  const mutationPoolAttributed = attributionKeys.size;
+  const closedSessions = /* @__PURE__ */ new Set();
+  for (const ended of sessionEndedEvents) {
+    const sid = typeof ended.session_id === "string" && ended.session_id.length > 0 ? ended.session_id : ended.id;
+    closedSessions.add(sid);
+  }
   const metrics = {
     edits_touched: editsTouched,
     qualifying_cites: qualifyingCites,
@@ -5869,7 +6357,29 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     cite_compliance_rate: citeComplianceRate,
     compliant_cites: compliantCites,
     noncompliant_cites: noncompliantCites,
-    uncorrelatable_edits: uncorrelatableEdits
+    uncorrelatable_edits: uncorrelatableEdits,
+    recall_backed_edits: recallBackedEdits,
+    recall_coverage_rate: recallCoverageRate,
+    exposed_and_mutated: {
+      count: exposedAndMutated.count,
+      ...exposedAndMutated.ids.length > 0 ? { ids: exposedAndMutated.ids } : {}
+    },
+    // lifecycle-refactor W2-T4: PostToolUse mutation funnel (own fields, NEVER
+    // folded into cite_compliance_rate — honesty 铁律).
+    mutations_observed: { count: mutationsObserved },
+    mutation_pool: {
+      attributed: mutationPoolAttributed,
+      unattributed_workspace_dirty: unattributedWorkspaceDirty
+    },
+    sessions_closed: { count: closedSessions.size },
+    // lifecycle-refactor W3-T4 (§2 store 轴): per-store qualifying-cite breakdown.
+    // Diagnostic split of qualifying_cites only — never touches compliance.
+    // Omitted when no cite was observed (empty map → no field).
+    ...Object.keys(byStoreQualifying).length > 0 ? {
+      by_store: Object.fromEntries(
+        Object.entries(byStoreQualifying).map(([store, count]) => [store, { qualifying_cites: count }])
+      )
+    } : {}
   };
   let rollupDaysMerged = 0;
   let rollupTrend;
@@ -5893,9 +6403,11 @@ async function runDoctorCiteCoverage(projectRoot, options) {
         metrics.compliant_cites = (metrics.compliant_cites ?? 0) + (r.metrics.compliant_cites ?? 0);
         metrics.noncompliant_cites = (metrics.noncompliant_cites ?? 0) + (r.metrics.noncompliant_cites ?? 0);
         metrics.uncorrelatable_edits = (metrics.uncorrelatable_edits ?? 0) + (r.metrics.uncorrelatable_edits ?? 0);
+        metrics.recall_backed_edits = (metrics.recall_backed_edits ?? 0) + (r.metrics.recall_backed_edits ?? 0);
       }
       const mergedDenom = (metrics.compliant_cites ?? 0) + (metrics.noncompliant_cites ?? 0);
       metrics.cite_compliance_rate = mergedDenom > 0 ? (metrics.compliant_cites ?? 0) / mergedDenom : null;
+      metrics.recall_coverage_rate = metrics.edits_touched > 0 ? (metrics.recall_backed_edits ?? 0) / metrics.edits_touched : null;
     }
     try {
       const metricsRows = await readMetrics(projectRoot);
@@ -6223,7 +6735,15 @@ var HINT_SILENCE_COUNTER_FILE_REL = posix.join(
   "hint-silence-counter"
 );
 var MS_PER_DAY = 24 * 60 * 60 * 1e3;
-var MATURITY_LINE_PATTERN = /^maturity:\s*("?)(stable|endorsed|draft)\1\s*$/mu;
+var MATURITY_LINE_PATTERN = /^maturity:\s*("?)(stable|endorsed|draft|verified|proven)\1\s*$/mu;
+var CANONICAL_TO_LINT_MATURITY = {
+  proven: "stable",
+  verified: "endorsed",
+  draft: "draft",
+  // legacy values pass through unchanged.
+  stable: "stable",
+  endorsed: "endorsed"
+};
 var CREATED_AT_LINE_PATTERN = /^created_at:\s*("?)([^"\n]+)\1\s*$/mu;
 var TAGS_LINE_PATTERN = /^tags:\s*\[(.*)\]\s*$/mu;
 var RELEVANCE_SCOPE_LINE_PATTERN = /^relevance_scope:\s*("?)(narrow|broad)\1\s*$/mu;
@@ -6479,7 +6999,13 @@ async function runDoctorReport(target) {
     // werewolf-eval failure mode where description.summary == stable_id so
     // hint output is "KT-PIT-0001 · KT-PIT-0001" (AI skips fetch). Built
     // from the same MetaInspection so no extra disk reads.
-    createKnowledgeSummaryOpaqueCheck(t, inspectKnowledgeSummaryOpaque(meta)),
+    createKnowledgeSummaryOpaqueCheck(
+      t,
+      // v2.2 全砍 F10: also scan the read-set stores (team + personal) so opaque
+      // store summaries — the personal layer the dogfood flagged — are caught,
+      // not just the project agents.meta entries.
+      inspectKnowledgeSummaryOpaque(meta, collectStoreKnowledgeSummaries(target))
+    ),
     // rc.31 BUG-G2/G5: promote-ledger invariant. Sits adjacent to onboard
     // coverage — both are observability advisories built off events.jsonl.
     ...promoteLedgerInvariant === null ? [] : [createPromoteLedgerInvariantCheck(t, promoteLedgerInvariant)],
@@ -6523,7 +7049,7 @@ async function runDoctorReport(target) {
       warningCount: warnings.length,
       infoCount: infos.length,
       targetFiles: Object.fromEntries(
-        TARGET_FILE_PATHS.map((path2) => [path2, existsSync8(join11(projectRoot, path2))])
+        TARGET_FILE_PATHS.map((path2) => [path2, existsSync8(join13(projectRoot, path2))])
       ),
       // v2.0.0-rc.29 TASK-008 (BUG-F2): resolve and surface payload thresholds.
       // Best-effort: a corrupt fabric.config.json should not fail doctor; on
@@ -6568,7 +7094,7 @@ async function runDoctorFix(target) {
     }
   }
   if (before.fixable_errors.some((issue) => issue.code === "bootstrap_snapshot_drift")) {
-    const snapshotPath = join11(projectRoot, ".fabric", "AGENTS.md");
+    const snapshotPath = join13(projectRoot, ".fabric", "AGENTS.md");
     await ensureParentDirectory(snapshotPath);
     await atomicWriteText4(snapshotPath, BOOTSTRAP_CANONICAL);
     fixed.push(findIssue(before.fixable_errors, "bootstrap_snapshot_drift"));
@@ -6663,6 +7189,10 @@ async function runDoctorFix(target) {
       path: rotateResult.archivePath
     });
   }
+  try {
+    await flushMetrics(projectRoot);
+  } catch {
+  }
   if (before.fixable_errors.some((issue) => issue.code === "mcp_config_in_wrong_file")) {
     await fixMcpConfigInWrongFile(projectRoot);
     fixed.push(findIssue(before.fixable_errors, "mcp_config_in_wrong_file"));
@@ -6670,7 +7200,7 @@ async function runDoctorFix(target) {
   if (before.infos.some((issue) => issue.code === "stale_serve_lock")) {
     const lockInspection = inspectStaleServeLock(projectRoot, Date.now());
     if (lockInspection.present && !lockInspection.pidAlive) {
-      const lockFilePath = join11(projectRoot, ".fabric", ".serve.lock");
+      const lockFilePath = join13(projectRoot, ".fabric", ".serve.lock");
       try {
         await unlink3(lockFilePath);
       } catch (err) {
@@ -6812,6 +7342,10 @@ function createApplyLintMessage(succeeded, failed, manualErrorCount) {
   );
   return parts.join(" ");
 }
+var LINT_TO_CANONICAL_MATURITY = {
+  endorsed: "verified",
+  draft: "draft"
+};
 function rewriteFrontmatterMaturity(source, newMaturity) {
   const FM_PATTERN = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u;
   const fm = FM_PATTERN.exec(source);
@@ -6819,12 +7353,16 @@ function rewriteFrontmatterMaturity(source, newMaturity) {
     return null;
   }
   const block = fm[1];
-  if (!MATURITY_LINE_PATTERN.test(block)) {
+  const matMatch = MATURITY_LINE_PATTERN.exec(block);
+  if (matMatch === null) {
     return null;
   }
+  const currentValue = matMatch[2];
+  const isCanonicalVocab = currentValue === "proven" || currentValue === "verified" || currentValue === "draft";
+  const replacement = isCanonicalVocab ? LINT_TO_CANONICAL_MATURITY[newMaturity] : newMaturity;
   const replacedBlock = block.replace(
     MATURITY_LINE_PATTERN,
-    (line) => line.replace(/(stable|endorsed|draft)/u, newMaturity)
+    (line) => line.replace(/(stable|endorsed|draft|verified|proven)/u, replacement)
   );
   const blockStart = source.indexOf(block);
   if (blockStart < 0) {
@@ -6862,7 +7400,7 @@ async function applyOrphanDemote(projectRoot, candidate, now) {
     };
   }
   const detail = `${candidate.maturity} -> ${next}`;
-  const absPath = join11(projectRoot, candidate.path);
+  const absPath = join13(projectRoot, candidate.path);
   try {
     const source = await readFile13(absPath, "utf8");
     const rewritten = rewriteFrontmatterMaturity(source, next);
@@ -6929,11 +7467,11 @@ async function applyOrphanDemote(projectRoot, candidate, now) {
   }
 }
 async function applyStaleArchive(projectRoot, candidate, now) {
-  const sourceAbs = join11(projectRoot, candidate.path);
-  const destAbs = join11(projectRoot, candidate.archive_path);
+  const sourceAbs = join13(projectRoot, candidate.path);
+  const destAbs = join13(projectRoot, candidate.archive_path);
   const detail = `${candidate.path} -> ${candidate.archive_path}`;
   try {
-    await mkdir6(join11(destAbs, ".."), { recursive: true });
+    await mkdir5(join13(destAbs, ".."), { recursive: true });
     try {
       await rename2(sourceAbs, destAbs);
     } catch (renameError) {
@@ -6992,7 +7530,7 @@ async function applyStaleArchive(projectRoot, candidate, now) {
 async function applyPendingAutoArchive(projectRoot, candidate, now) {
   const detail = `${candidate.pending_path} -> ${candidate.archived_to}`;
   try {
-    await mkdir6(join11(candidate.archived_to_abs, ".."), { recursive: true });
+    await mkdir5(join13(candidate.archived_to_abs, ".."), { recursive: true });
     let moved = false;
     if (candidate.layer === "team") {
       try {
@@ -7065,11 +7603,11 @@ async function applyPendingAutoArchive(projectRoot, candidate, now) {
 }
 function relativePosix(projectRoot, absolutePath) {
   const rel = nodeRelative(projectRoot, absolutePath);
-  return rel.split(sep3).join("/");
+  return rel.split(sep4).join("/");
 }
 async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   const detail = `deleted (${candidate.age_days}d old)`;
-  const absPath = join11(projectRoot, candidate.path);
+  const absPath = join13(projectRoot, candidate.path);
   try {
     const { unlink: unlink4 } = await import("fs/promises");
     await unlink4(absPath);
@@ -7090,21 +7628,23 @@ async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   }
 }
 async function applyIndexDriftFix(projectRoot, inspection) {
-  const metaPath = join11(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join13(projectRoot, ".fabric", "agents.meta.json");
   const detailParts = [];
   try {
-    const meta = agentsMetaSchema5.parse(JSON.parse(await readFile13(metaPath, "utf8")));
-    const baseCounters = AgentsMetaCountersSchema2.parse(meta.counters ?? void 0);
-    const updatedCounters = {
-      KP: { ...baseCounters.KP },
-      KT: { ...baseCounters.KT }
-    };
-    for (const drift of inspection.drifts) {
-      updatedCounters[drift.layer][drift.type] = drift.proposed_after;
-      detailParts.push(`${drift.layer}.${drift.type}: ${drift.counter} -> ${drift.proposed_after}`);
-    }
-    const updated = { ...meta, counters: updatedCounters };
-    await atomicWriteJson3(metaPath, updated, { indent: 2 });
+    await withFileLock4(`${metaPath}.lock`, async () => {
+      const meta = agentsMetaSchema5.parse(JSON.parse(await readFile13(metaPath, "utf8")));
+      const baseCounters = AgentsMetaCountersSchema2.parse(meta.counters ?? void 0);
+      const updatedCounters = {
+        KP: { ...baseCounters.KP },
+        KT: { ...baseCounters.KT }
+      };
+      for (const drift of inspection.drifts) {
+        updatedCounters[drift.layer][drift.type] = drift.proposed_after;
+        detailParts.push(`${drift.layer}.${drift.type}: ${drift.counter} -> ${drift.proposed_after}`);
+      }
+      const updated = { ...meta, counters: updatedCounters };
+      await atomicWriteJson3(metaPath, updated, { indent: 2 });
+    });
     return {
       kind: "knowledge_index_drift",
       path: "agents.meta.json#counters",
@@ -7126,7 +7666,7 @@ function truncateErrorMessage(error) {
   return raw.length > 240 ? `${raw.slice(0, 237)}...` : raw;
 }
 async function inspectForensic(projectRoot) {
-  const path2 = join11(projectRoot, ".fabric", "forensic.json");
+  const path2 = join13(projectRoot, ".fabric", "forensic.json");
   try {
     const parsed = forensicReportSchema.parse(JSON.parse(await readFile13(path2, "utf8")));
     return { present: true, valid: true, report: parsed };
@@ -7138,12 +7678,12 @@ async function inspectForensic(projectRoot) {
   }
 }
 function inspectMcpConfigInWrongFile(projectRoot) {
-  const settingsPath = join11(projectRoot, ".claude", "settings.json");
+  const settingsPath = join13(projectRoot, ".claude", "settings.json");
   if (!existsSync8(settingsPath)) {
     return { hasWrongEntry: false, settingsPath };
   }
   try {
-    const parsed = JSON.parse(readFileSync3(settingsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync4(settingsPath, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return { hasWrongEntry: false, settingsPath };
     }
@@ -7159,7 +7699,7 @@ function inspectMcpConfigInWrongFile(projectRoot) {
   }
 }
 async function inspectMeta(projectRoot) {
-  const metaPath = join11(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join13(projectRoot, ".fabric", "agents.meta.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
     const raw = await readFile13(metaPath, "utf8");
@@ -7245,7 +7785,7 @@ function inspectContentRefs(projectRoot, meta) {
     if (isPersonalKnowledge) {
       continue;
     }
-    if (!existsSync8(join11(projectRoot, contentRef))) {
+    if (!existsSync8(join13(projectRoot, contentRef))) {
       missing.push(contentRef);
     }
   }
@@ -7329,8 +7869,8 @@ function inspectSkillRefMirror(projectRoot) {
   const skillSlugs = ["fabric-archive", "fabric-review", "fabric-import"];
   const driftedPaths = [];
   for (const slug of skillSlugs) {
-    const claudeRef = join11(projectRoot, ".claude", "skills", slug, "ref");
-    const codexRef = join11(projectRoot, ".codex", "skills", slug, "ref");
+    const claudeRef = join13(projectRoot, ".claude", "skills", slug, "ref");
+    const codexRef = join13(projectRoot, ".codex", "skills", slug, "ref");
     let claudeFiles = null;
     let codexFiles = null;
     try {
@@ -7355,12 +7895,12 @@ function inspectSkillRefMirror(projectRoot) {
       let claudeBody;
       let codexBody;
       try {
-        claudeBody = readFileSync3(join11(claudeRef, fname), "utf8");
+        claudeBody = readFileSync4(join13(claudeRef, fname), "utf8");
       } catch {
         continue;
       }
       try {
-        codexBody = readFileSync3(join11(codexRef, fname), "utf8");
+        codexBody = readFileSync4(join13(codexRef, fname), "utf8");
       } catch {
         continue;
       }
@@ -7379,10 +7919,10 @@ function inspectSkillTokenBudget(projectRoot) {
   const overSize = [];
   let highestSeverity = "ok";
   for (const slug of skillSlugs) {
-    const skillMdPath = join11(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join13(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = readFileSync3(skillMdPath, "utf8");
+      body = readFileSync4(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -7404,10 +7944,10 @@ function inspectSkillDescription(projectRoot) {
   const CJK_PATTERN = /[㐀-䶿一-鿿]/;
   const ASCII_PATTERN = /[a-zA-Z]{2,}/;
   for (const slug of skillSlugs) {
-    const skillMdPath = join11(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join13(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = readFileSync3(skillMdPath, "utf8");
+      body = readFileSync4(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -7522,9 +8062,9 @@ function inspectDraftBacklog(projectRoot) {
   const MIN_TOTAL_FOR_RATIO = 10;
   let draftCount = 0;
   let totalCount = 0;
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-    const dir = join11(knowledgeRoot, typeDir);
+    const dir = join13(knowledgeRoot, typeDir);
     if (!existsSync8(dir)) continue;
     let entries;
     try {
@@ -7537,7 +8077,7 @@ function inspectDraftBacklog(projectRoot) {
       if (CANONICAL_KNOWLEDGE_FILENAME_PATTERN.exec(entry.name) === null) continue;
       let maturity;
       try {
-        maturity = extractMaturityFull(readFileSync3(join11(dir, entry.name), "utf8"));
+        maturity = extractMaturityFull(readFileSync4(join13(dir, entry.name), "utf8"));
       } catch {
         continue;
       }
@@ -7581,7 +8121,7 @@ async function inspectDraftAutoPromote(projectRoot, now = Date.now()) {
     if (drifted.has(entry.stable_id)) continue;
     let createdAt;
     try {
-      createdAt = extractKnowledgeFrontmatterCreatedAt(readFileSync3(entry.absPath, "utf8"));
+      createdAt = extractKnowledgeFrontmatterCreatedAt(readFileSync4(entry.absPath, "utf8"));
     } catch {
       continue;
     }
@@ -7624,7 +8164,7 @@ async function applyDraftAutoPromote(projectRoot, candidates) {
   for (const candidate of candidates) {
     let source;
     try {
-      source = readFileSync3(candidate.absPath, "utf8");
+      source = readFileSync4(candidate.absPath, "utf8");
     } catch {
       continue;
     }
@@ -7654,7 +8194,7 @@ function inspectKnowledgeTagsEmpty(projectRoot) {
   for (const entry of iterateCanonicalEntries(projectRoot, /* @__PURE__ */ new Map())) {
     let source;
     try {
-      source = readFileSync3(entry.absPath, "utf8");
+      source = readFileSync4(entry.absPath, "utf8");
     } catch {
       continue;
     }
@@ -7676,7 +8216,7 @@ function inspectKnowledgeTagsEmpty(projectRoot) {
   };
 }
 async function inspectKnowledgeTestIndex(projectRoot) {
-  const path2 = join11(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
+  const path2 = join13(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
     const index = knowledgeTestIndexSchema2.parse(JSON.parse(await readFile13(path2, "utf8")));
@@ -7700,8 +8240,8 @@ async function inspectKnowledgeTestIndex(projectRoot) {
 }
 function inspectBootstrapAnchor(projectRoot) {
   return {
-    hasAgentsMd: existsSync8(join11(projectRoot, "AGENTS.md")),
-    hasClaudeMd: existsSync8(join11(projectRoot, "CLAUDE.md"))
+    hasAgentsMd: existsSync8(join13(projectRoot, "AGENTS.md")),
+    hasClaudeMd: existsSync8(join13(projectRoot, "CLAUDE.md"))
   };
 }
 var BOOTSTRAP_MARKER_MIGRATION_TARGETS = [
@@ -7713,7 +8253,7 @@ var BOOTSTRAP_MARKER_MIGRATION_TARGETS = [
 async function inspectBootstrapMarkerMigration(target) {
   const filesNeedingMigration = [];
   for (const rel of BOOTSTRAP_MARKER_MIGRATION_TARGETS) {
-    const abs = join11(target, rel);
+    const abs = join13(target, rel);
     if (!existsSync8(abs)) {
       continue;
     }
@@ -7751,7 +8291,7 @@ function createBootstrapMarkerMigrationCheck(t, inspection) {
   );
 }
 async function inspectL1BootstrapSnapshotDrift(target) {
-  const abs = join11(target, ".fabric", "AGENTS.md");
+  const abs = join13(target, ".fabric", "AGENTS.md");
   if (!existsSync8(abs)) {
     return { status: "missing", canonical: BOOTSTRAP_CANONICAL, onDisk: null };
   }
@@ -7783,7 +8323,7 @@ function createL1BootstrapSnapshotDriftCheck(t, inspection) {
   );
 }
 async function inspectL2ManagedBlockDrift(target) {
-  const snapshotPath = join11(target, ".fabric", "AGENTS.md");
+  const snapshotPath = join13(target, ".fabric", "AGENTS.md");
   if (!existsSync8(snapshotPath)) {
     return { status: "ok", drifted: [] };
   }
@@ -7793,7 +8333,7 @@ async function inspectL2ManagedBlockDrift(target) {
   } catch {
     return { status: "ok", drifted: [] };
   }
-  const projectRulesPath = join11(target, ".fabric", "project-rules.md");
+  const projectRulesPath = join13(target, ".fabric", "project-rules.md");
   let expectedBody = snapshot;
   if (existsSync8(projectRulesPath)) {
     try {
@@ -7807,8 +8347,8 @@ ${projectRules}`;
   const drifted = [];
   let anyManagedBlockFound = false;
   const blockTargets = [
-    join11(target, "AGENTS.md"),
-    join11(target, ".cursor", "rules", "fabric-bootstrap.mdc")
+    join13(target, "AGENTS.md"),
+    join13(target, ".cursor", "rules", "fabric-bootstrap.mdc")
   ];
   for (const abs of blockTargets) {
     if (!existsSync8(abs)) {
@@ -7842,7 +8382,7 @@ ${projectRules}`;
       drifted.push({ path: abs, expected: expectedBody, actual: body });
     }
   }
-  const claudeMdPath = join11(target, "CLAUDE.md");
+  const claudeMdPath = join13(target, "CLAUDE.md");
   if (existsSync8(claudeMdPath)) {
     let claudeContent;
     try {
@@ -7913,10 +8453,10 @@ function createBootstrapAnchorCheck(t, inspection) {
   );
 }
 function inspectKnowledgeDirMissing(projectRoot) {
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   const missingSubdirs = [];
   for (const sub of KNOWLEDGE_SUBDIRS3) {
-    const path2 = join11(knowledgeRoot, sub);
+    const path2 = join13(knowledgeRoot, sub);
     if (!existsSync8(path2)) {
       missingSubdirs.push(`.fabric/knowledge/${sub}`);
     }
@@ -7925,12 +8465,12 @@ function inspectKnowledgeDirMissing(projectRoot) {
 }
 function inspectBaselineFilenameFormat(projectRoot) {
   const offenders = [];
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   if (!existsSync8(knowledgeRoot)) {
     return { offenders };
   }
   for (const sub of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-    const dir = join11(knowledgeRoot, sub);
+    const dir = join13(knowledgeRoot, sub);
     if (!existsSync8(dir)) {
       continue;
     }
@@ -7948,10 +8488,10 @@ function inspectBaselineFilenameFormat(projectRoot) {
       if (BASELINE_ID_PREFIXED_FILENAME_PATTERN.test(entryName)) {
         continue;
       }
-      const abs = join11(dir, entryName);
+      const abs = join13(dir, entryName);
       let source;
       try {
-        source = readFileSync3(abs, "utf8");
+        source = readFileSync4(abs, "utf8");
       } catch {
         continue;
       }
@@ -8529,17 +9069,17 @@ function okCheck(name, message) {
   return { name, status: "ok", message };
 }
 function inspectHooksWired(projectRoot) {
-  const claudeDir = join11(projectRoot, ".claude");
+  const claudeDir = join13(projectRoot, ".claude");
   if (!existsSync8(claudeDir)) {
     return { status: "skipped", missingHooks: [] };
   }
-  const settingsPath = join11(projectRoot, ".claude", "settings.json");
+  const settingsPath = join13(projectRoot, ".claude", "settings.json");
   if (!existsSync8(settingsPath)) {
     return { status: "missing-settings", missingHooks: [] };
   }
   let raw;
   try {
-    raw = readFileSync3(settingsPath, "utf8");
+    raw = readFileSync4(settingsPath, "utf8");
   } catch {
     return { status: "missing-settings", missingHooks: [] };
   }
@@ -8624,7 +9164,7 @@ function createHooksWiredCheck(t, inspection) {
 function inspectHooksContentDrift(projectRoot) {
   const hookFilesByBasename = /* @__PURE__ */ new Map();
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join11(projectRoot, dir);
+    const absDir = join13(projectRoot, dir);
     if (!existsSync8(absDir)) continue;
     let entries;
     try {
@@ -8634,7 +9174,7 @@ function inspectHooksContentDrift(projectRoot) {
     }
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join11(absDir, name);
+      const abs = join13(absDir, name);
       let stat3;
       try {
         stat3 = statSync4(abs);
@@ -8655,7 +9195,7 @@ function inspectHooksContentDrift(projectRoot) {
     const hashes = [];
     for (const { client, abs } of copies) {
       try {
-        const body = readFileSync3(abs);
+        const body = readFileSync4(abs);
         hashes.push({ client, sha: sha256(body.toString("utf8")) });
       } catch {
       }
@@ -8711,7 +9251,7 @@ function inspectHooksRuntime(projectRoot) {
   const issues = [];
   let scanned = 0;
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join11(projectRoot, dir);
+    const absDir = join13(projectRoot, dir);
     if (!existsSync8(absDir)) continue;
     let entries;
     try {
@@ -8721,7 +9261,7 @@ function inspectHooksRuntime(projectRoot) {
     }
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join11(absDir, name);
+      const abs = join13(absDir, name);
       const displayPath = `${dir}/${name}`;
       let stat3;
       try {
@@ -8733,7 +9273,7 @@ function inspectHooksRuntime(projectRoot) {
       scanned += 1;
       let body;
       try {
-        body = readFileSync3(abs, "utf8");
+        body = readFileSync4(abs, "utf8");
       } catch (err) {
         issues.push({
           path: displayPath,
@@ -8887,15 +9427,17 @@ function inspectGlobalCliVersion(spawn = defaultGlobalCliSpawn) {
     return { status: "unparseable", detail: `exit ${res.status ?? "?"}` };
   }
   const raw = (res.stdout ?? "").trim();
-  const m = /(\d+)\.(\d+)\.(\d+)-rc\.(\d+)/.exec(raw);
+  const m = /(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?/.exec(raw);
   if (!m) {
     return { status: "unparseable", detail: raw.slice(0, 80) };
   }
-  const version = `${m[1]}.${m[2]}.${m[3]}-rc.${m[4]}`;
-  const observedRc = Number(m[4]);
-  const minMatch = /-rc\.(\d+)/.exec(MIN_SUPPORTED_GLOBAL_CLI_VERSION);
-  const minRc = minMatch ? Number(minMatch[1]) : 0;
-  if (observedRc < minRc) {
+  const hasRc = m[4] !== void 0;
+  const version = hasRc ? `${m[1]}.${m[2]}.${m[3]}-rc.${m[4]}` : `${m[1]}.${m[2]}.${m[3]}`;
+  const minM = /(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?/.exec(MIN_SUPPORTED_GLOBAL_CLI_VERSION);
+  const observed = [Number(m[1]), Number(m[2]), Number(m[3]), hasRc ? Number(m[4]) : Infinity];
+  const min = minM ? [Number(minM[1]), Number(minM[2]), Number(minM[3]), minM[4] !== void 0 ? Number(minM[4]) : Infinity] : [0, 0, 0, 0];
+  const diffAt = observed.findIndex((v, i) => v !== min[i]);
+  if (diffAt !== -1 && observed[diffAt] < min[diffAt]) {
     return { status: "outdated", version, minVersion: MIN_SUPPORTED_GLOBAL_CLI_VERSION };
   }
   return { status: "ok", version };
@@ -8940,7 +9482,7 @@ function createGlobalCliVersionCheck(t, inspection) {
   );
 }
 var KNOWLEDGE_SUMMARY_OPAQUE_THRESHOLD = 0.3;
-function inspectKnowledgeSummaryOpaque(meta) {
+function inspectKnowledgeSummaryOpaque(meta, storeSummaries = []) {
   const baseline = {
     totalWithDescription: 0,
     opaqueCount: 0,
@@ -8965,6 +9507,14 @@ function inspectKnowledgeSummaryOpaque(meta) {
       opaqueIds.push(stableId);
     }
   }
+  for (const entry of storeSummaries) {
+    total += 1;
+    const summary = entry.summary.trim();
+    const localId = entry.stableId.includes(":") ? entry.stableId.slice(entry.stableId.indexOf(":") + 1) : entry.stableId;
+    if (summary.length === 0 || summary === entry.stableId.trim() || summary === localId.trim()) {
+      opaqueIds.push(entry.stableId);
+    }
+  }
   if (total === 0) {
     return { status: "ok", ...baseline };
   }
@@ -9040,7 +9590,7 @@ function findIssue(issues, code) {
   };
 }
 async function inspectMetaManuallyDiverged(projectRoot) {
-  const metaPath = join11(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join13(projectRoot, ".fabric", "agents.meta.json");
   if (!existsSync8(metaPath)) {
     return { extraMetaEntries: [], hashMismatchEntries: [], readable: false };
   }
@@ -9066,7 +9616,7 @@ async function inspectMetaManuallyDiverged(projectRoot) {
       continue;
     }
     try {
-      const content = readFileSync3(absPath, "utf8");
+      const content = readFileSync4(absPath, "utf8");
       const diskHash = sha256(content);
       if (node.hash !== "" && node.hash !== diskHash) {
         hashMismatchEntries.push(contentRef);
@@ -9079,7 +9629,7 @@ async function inspectMetaManuallyDiverged(projectRoot) {
 }
 function inspectKnowledgeDirUnindexed(projectRoot, meta) {
   const physicalMdFiles = /* @__PURE__ */ new Set();
-  collectMdFilesUnder(physicalMdFiles, projectRoot, join11(projectRoot, ".fabric", "knowledge"), ".fabric/knowledge");
+  collectMdFilesUnder(physicalMdFiles, projectRoot, join13(projectRoot, ".fabric", "knowledge"), ".fabric/knowledge");
   if (physicalMdFiles.size === 0) {
     return { unindexedFiles: [] };
   }
@@ -9104,7 +9654,7 @@ function collectMdFilesUnder(out, projectRoot, rootDir, relPrefix) {
       continue;
     }
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const abs = join11(dir, entry.name);
+      const abs = join13(dir, entry.name);
       if (entry.isDirectory()) {
         if (entry.name !== "pending" && entry.name !== "archive") {
           stack.push(abs);
@@ -9137,7 +9687,7 @@ function createKnowledgeDirUnindexedCheck(t, inspection) {
 }
 async function inspectStableIdCollisions(projectRoot) {
   const found = [];
-  const knowledgeDir = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeDir = join13(projectRoot, ".fabric", "knowledge");
   if (existsSync8(knowledgeDir)) {
     const stack = [knowledgeDir];
     while (stack.length > 0) {
@@ -9146,7 +9696,7 @@ async function inspectStableIdCollisions(projectRoot) {
         continue;
       }
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const abs = join11(dir, entry.name);
+        const abs = join13(dir, entry.name);
         if (entry.isDirectory()) {
           stack.push(abs);
         } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -9325,17 +9875,17 @@ function createMetaManuallyDivergedCheck(t, inspection) {
 }
 function inspectPreexistingRootFiles(projectRoot) {
   const candidates = ["CLAUDE.md", "AGENTS.md"];
-  const detected = candidates.filter((name) => existsSync8(join11(projectRoot, name)));
+  const detected = candidates.filter((name) => existsSync8(join13(projectRoot, name)));
   return { detected };
 }
 async function inspectFilesystemEditFallback(projectRoot) {
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   if (!existsSync8(knowledgeRoot)) {
     return { synthesized: 0, synthesizedStableIds: [] };
   }
   const canonicalIds = /* @__PURE__ */ new Set();
   for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-    const dir = join11(knowledgeRoot, typeDir);
+    const dir = join13(knowledgeRoot, typeDir);
     if (!existsSync8(dir)) {
       continue;
     }
@@ -9571,7 +10121,10 @@ function extractKnowledgeFrontmatterMaturity(source) {
     return null;
   }
   const match = MATURITY_LINE_PATTERN.exec(fm[1]);
-  return match === null ? null : match[2];
+  if (match === null) {
+    return null;
+  }
+  return CANONICAL_TO_LINT_MATURITY[match[2]] ?? null;
 }
 function isKnowledgeFrontmatterTagsEmpty(source) {
   const FM_PATTERN = /^(?:)?---\r?\n([\s\S]*?)\r?\n---/u;
@@ -9600,12 +10153,12 @@ function extractKnowledgeFrontmatterCreatedAt(source) {
   return Number.isFinite(parsed) ? parsed : null;
 }
 function* iterateCanonicalEntries(projectRoot, lastActiveIndex) {
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   if (!existsSync8(knowledgeRoot)) {
     return;
   }
   for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-    const dir = join11(knowledgeRoot, typeDir);
+    const dir = join13(knowledgeRoot, typeDir);
     if (!existsSync8(dir)) {
       continue;
     }
@@ -9624,10 +10177,10 @@ function* iterateCanonicalEntries(projectRoot, lastActiveIndex) {
         continue;
       }
       const stableId = match[1];
-      const absPath = join11(dir, entry.name);
+      const absPath = join13(dir, entry.name);
       let source;
       try {
-        source = readFileSync3(absPath, "utf8");
+        source = readFileSync4(absPath, "utf8");
       } catch {
         continue;
       }
@@ -9701,8 +10254,8 @@ async function inspectStaleArchive(projectRoot, now) {
   return { candidates };
 }
 function* iteratePendingFiles(projectRoot, now) {
-  const teamRoot = join11(projectRoot, ".fabric", "knowledge", "pending");
-  const personalRoot = join11(resolvePersonalRootForPending(), ".fabric", "knowledge", "pending");
+  const teamRoot = join13(projectRoot, ".fabric", "knowledge", "pending");
+  const personalRoot = join13(resolvePersonalRootForPending(), ".fabric", "knowledge", "pending");
   for (const [layer, root, displayPrefix] of [
     ["team", teamRoot, ".fabric/knowledge/pending"],
     ["personal", personalRoot, "~/.fabric/knowledge/pending"]
@@ -9717,7 +10270,7 @@ function* iteratePendingFiles(projectRoot, now) {
       continue;
     }
     for (const typeDir of typeDirs) {
-      const dir = join11(root, typeDir);
+      const dir = join13(root, typeDir);
       let entries;
       try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -9728,10 +10281,10 @@ function* iteratePendingFiles(projectRoot, now) {
         if (!entry.isFile() || !entry.name.endsWith(".md")) {
           continue;
         }
-        const absPath = join11(dir, entry.name);
+        const absPath = join13(dir, entry.name);
         let source = "";
         try {
-          source = readFileSync3(absPath, "utf8");
+          source = readFileSync4(absPath, "utf8");
         } catch {
           continue;
         }
@@ -9803,7 +10356,7 @@ function inspectPendingAutoArchive(projectRoot, now) {
         pending_path: visit.pending_path,
         pending_path_abs: visit.pending_path_abs,
         archived_to: archivedToRel,
-        archived_to_abs: join11(projectRoot, archivedToRel),
+        archived_to_abs: join13(projectRoot, archivedToRel),
         age_days: visit.age_days
       });
     } else {
@@ -9812,7 +10365,7 @@ function inspectPendingAutoArchive(projectRoot, now) {
         visit.type,
         visit.filename
       );
-      const archivedToAbs = join11(
+      const archivedToAbs = join13(
         resolvePersonalRootForPending(),
         ".fabric",
         ".archive",
@@ -9836,11 +10389,11 @@ function inspectPendingAutoArchive(projectRoot, now) {
 }
 function inspectUnderseeded(projectRoot) {
   const threshold = readUnderseedThresholdFromConfig(projectRoot);
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   let nodeCount = 0;
   if (existsSync8(knowledgeRoot)) {
     for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-      const dir = join11(knowledgeRoot, typeDir);
+      const dir = join13(knowledgeRoot, typeDir);
       if (!existsSync8(dir)) continue;
       let entries;
       try {
@@ -9862,7 +10415,7 @@ function inspectUnderseeded(projectRoot) {
   };
 }
 function inspectSessionHintsStale(projectRoot, now) {
-  const cacheDir = join11(projectRoot, ".fabric", ".cache");
+  const cacheDir = join13(projectRoot, ".fabric", ".cache");
   if (!existsSync8(cacheDir)) {
     return { candidates: [] };
   }
@@ -9877,7 +10430,7 @@ function inspectSessionHintsStale(projectRoot, now) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith(SESSION_HINTS_FILE_PREFIX)) continue;
     if (!entry.name.endsWith(SESSION_HINTS_FILE_SUFFIX)) continue;
-    const absPath = join11(cacheDir, entry.name);
+    const absPath = join13(cacheDir, entry.name);
     let mtimeMs = 0;
     try {
       mtimeMs = statSync4(absPath).mtimeMs;
@@ -9921,11 +10474,11 @@ function inspectNarrowTooFew(projectRoot, now) {
   const structuralFlagged = total >= NARROW_MIN_TOTAL && narrowRatio < NARROW_RATIO_THRESHOLD;
   const windowStartMs = now - SILENCE_WINDOW_DAYS * MS_PER_DAY;
   const editFires = readCounterTimestamps(
-    join11(projectRoot, EDIT_COUNTER_FILE_REL),
+    join13(projectRoot, EDIT_COUNTER_FILE_REL),
     windowStartMs
   );
   const silenceFires = readCounterTimestamps(
-    join11(projectRoot, HINT_SILENCE_COUNTER_FILE_REL),
+    join13(projectRoot, HINT_SILENCE_COUNTER_FILE_REL),
     windowStartMs
   );
   const telemetrySkipped = editFires === 0;
@@ -9947,7 +10500,7 @@ function readCounterTimestamps(absPath, windowStartMs) {
   if (!existsSync8(absPath)) return 0;
   let raw;
   try {
-    raw = readFileSync3(absPath, "utf8");
+    raw = readFileSync4(absPath, "utf8");
   } catch {
     return 0;
   }
@@ -9963,10 +10516,10 @@ function readCounterTimestamps(absPath, windowStartMs) {
   return count;
 }
 function readUnderseedThresholdFromConfig(projectRoot) {
-  const configPath = join11(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join13(projectRoot, ".fabric", "fabric-config.json");
   if (!existsSync8(configPath)) return DEFAULT_UNDERSEED_NODE_THRESHOLD;
   try {
-    const raw = readFileSync3(configPath, "utf8");
+    const raw = readFileSync4(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.underseed_node_threshold;
@@ -10160,11 +10713,11 @@ function extractKnowledgeFrontmatterRelevancePaths(source) {
 }
 function* iterateRelevanceFrontmatter(projectRoot) {
   for (const visit of iterateCanonicalFilenames(projectRoot)) {
-    const layerRoot = visit.layer === "team" ? join11(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
-    const absPath = join11(layerRoot, visit.type, visit.filename);
+    const layerRoot = visit.layer === "team" ? join13(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
+    const absPath = join13(layerRoot, visit.type, visit.filename);
     let source;
     try {
-      source = readFileSync3(absPath, "utf8");
+      source = readFileSync4(absPath, "utf8");
     } catch {
       continue;
     }
@@ -10250,7 +10803,7 @@ function collectWorkspacePathsForGlobMatch(projectRoot) {
       continue;
     }
     for (const entry of entries) {
-      const abs = join11(current, entry.name);
+      const abs = join13(current, entry.name);
       const rel = normalizePath(abs.slice(projectRoot.length + 1));
       if (rel.length === 0) continue;
       if (entry.isDirectory()) {
@@ -10466,11 +11019,11 @@ function createPersonalLayerPathMisclassifyCheck(t, inspection) {
 function inspectSuspiciousKb(projectRoot) {
   const candidates = [];
   for (const visit of iterateCanonicalFilenames(projectRoot)) {
-    const layerRoot = visit.layer === "team" ? join11(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
-    const absPath = join11(layerRoot, visit.type, visit.filename);
+    const layerRoot = visit.layer === "team" ? join13(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
+    const absPath = join13(layerRoot, visit.type, visit.filename);
     let body;
     try {
-      body = readFileSync3(absPath, "utf8");
+      body = readFileSync4(absPath, "utf8");
     } catch {
       continue;
     }
@@ -10519,8 +11072,8 @@ function inspectRelevanceFieldsMissing(projectRoot) {
   const candidates = [];
   let scannedCount = 0;
   const FM_PATTERN = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u;
-  const teamRoot = join11(projectRoot, ".fabric", "knowledge", "pending");
-  const personalRoot = join11(
+  const teamRoot = join13(projectRoot, ".fabric", "knowledge", "pending");
+  const personalRoot = join13(
     resolvePersonalRootForPending(),
     ".fabric",
     "knowledge",
@@ -10540,7 +11093,7 @@ function inspectRelevanceFieldsMissing(projectRoot) {
       continue;
     }
     for (const typeDir of typeDirs) {
-      const dir = join11(root, typeDir);
+      const dir = join13(root, typeDir);
       let entries;
       try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -10551,10 +11104,10 @@ function inspectRelevanceFieldsMissing(projectRoot) {
         if (!entry.isFile() || !entry.name.endsWith(".md")) {
           continue;
         }
-        const absPath = join11(dir, entry.name);
+        const absPath = join13(dir, entry.name);
         let source;
         try {
-          source = readFileSync3(absPath, "utf8");
+          source = readFileSync4(absPath, "utf8");
         } catch {
           continue;
         }
@@ -10686,7 +11239,7 @@ var SKILL_QUOTED_VALUE_LEADS = /* @__PURE__ */ new Set(['"', "'", "[", "{", ">",
 function inspectSkillMdYamlInvalid(projectRoot) {
   const candidates = [];
   for (const rootRel of SKILL_MD_FRONTMATTER_ROOTS) {
-    const rootAbs = join11(projectRoot, rootRel);
+    const rootAbs = join13(projectRoot, rootRel);
     if (!existsSync8(rootAbs)) continue;
     let dirEntries;
     try {
@@ -10696,11 +11249,11 @@ function inspectSkillMdYamlInvalid(projectRoot) {
     }
     for (const dirEntry of dirEntries) {
       if (!dirEntry.isDirectory()) continue;
-      const skillFile = join11(rootAbs, dirEntry.name, "SKILL.md");
+      const skillFile = join13(rootAbs, dirEntry.name, "SKILL.md");
       if (!existsSync8(skillFile)) continue;
       let raw;
       try {
-        raw = readFileSync3(skillFile, "utf8");
+        raw = readFileSync4(skillFile, "utf8");
       } catch {
         continue;
       }
@@ -10782,10 +11335,10 @@ function inspectOnboardCoverage(projectRoot) {
   for (const slot of ONBOARD_SLOT_NAMES) {
     filled[slot] = [];
   }
-  const knowledgeRoot = join11(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join13(projectRoot, ".fabric", "knowledge");
   if (existsSync8(knowledgeRoot)) {
     for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS_FOR_ONBOARD) {
-      const dir = join11(knowledgeRoot, typeDir);
+      const dir = join13(knowledgeRoot, typeDir);
       if (!existsSync8(dir)) continue;
       let entries;
       try {
@@ -10796,10 +11349,10 @@ function inspectOnboardCoverage(projectRoot) {
       for (const entry of entries) {
         if (!entry.isFile()) continue;
         if (!entry.name.endsWith(".md")) continue;
-        const filePath = join11(dir, entry.name);
+        const filePath = join13(dir, entry.name);
         let content;
         try {
-          content = readFileSync3(filePath, "utf8");
+          content = readFileSync4(filePath, "utf8");
         } catch {
           continue;
         }
@@ -10823,11 +11376,11 @@ function inspectOnboardCoverage(projectRoot) {
   return { filled, missing, opted_out: optedOut };
 }
 function readOnboardOptedOut(projectRoot) {
-  const path2 = join11(projectRoot, ".fabric", "fabric-config.json");
+  const path2 = join13(projectRoot, ".fabric", "fabric-config.json");
   if (!existsSync8(path2)) return [];
   let raw;
   try {
-    raw = readFileSync3(path2, "utf8");
+    raw = readFileSync4(path2, "utf8");
   } catch {
     return [];
   }
@@ -10851,10 +11404,10 @@ function readFrontmatterScalar(content, key) {
   if (block === void 0) return void 0;
   for (const rawLine of block.split(/\r?\n/u)) {
     const line = rawLine.trim();
-    const sep4 = line.indexOf(":");
-    if (sep4 === -1) continue;
-    if (line.slice(0, sep4).trim() !== key) continue;
-    let value = line.slice(sep4 + 1).trim();
+    const sep5 = line.indexOf(":");
+    if (sep5 === -1) continue;
+    if (line.slice(0, sep5).trim() !== key) continue;
+    let value = line.slice(sep5 + 1).trim();
     if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
       value = value.slice(1, -1);
     }
@@ -10943,7 +11496,7 @@ function createNarrowTooFewCheck(t, inspection) {
 }
 function resolvePersonalKnowledgeRoot() {
   const home = process.env.FABRIC_HOME ?? homedir6();
-  return join11(home, ".fabric", "knowledge");
+  return join13(home, ".fabric", "knowledge");
 }
 function parseStableIdFromCanonicalFilename(filename) {
   const match = CANONICAL_KNOWLEDGE_FILENAME_PATTERN.exec(filename);
@@ -10963,7 +11516,7 @@ function parseStableIdFromCanonicalFilename(filename) {
   };
 }
 function* iterateCanonicalFilenames(projectRoot) {
-  const teamRoot = join11(projectRoot, ".fabric", "knowledge");
+  const teamRoot = join13(projectRoot, ".fabric", "knowledge");
   const personalRoot = resolvePersonalKnowledgeRoot();
   for (const [layer, root, displayPrefix] of [
     ["team", teamRoot, ".fabric/knowledge"],
@@ -10973,7 +11526,7 @@ function* iterateCanonicalFilenames(projectRoot) {
       continue;
     }
     for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-      const dir = join11(root, typeDir);
+      const dir = join13(root, typeDir);
       if (!existsSync8(dir)) {
         continue;
       }
@@ -11145,7 +11698,7 @@ async function migrateBootstrapMarkers(projectRoot) {
   const paths = [];
   const countPerPath = {};
   for (const rel of BOOTSTRAP_MARKER_MIGRATION_TARGETS) {
-    const abs = join11(projectRoot, rel);
+    const abs = join13(projectRoot, rel);
     if (!existsSync8(abs)) {
       continue;
     }
@@ -11172,7 +11725,7 @@ async function migrateBootstrapMarkers(projectRoot) {
   return { paths, countPerPath };
 }
 async function rewriteThreeEndManagedBlocks(projectRoot) {
-  const snapshotPath = join11(projectRoot, ".fabric", "AGENTS.md");
+  const snapshotPath = join13(projectRoot, ".fabric", "AGENTS.md");
   if (!existsSync8(snapshotPath)) {
     return;
   }
@@ -11182,7 +11735,7 @@ async function rewriteThreeEndManagedBlocks(projectRoot) {
   } catch {
     return;
   }
-  const projectRulesPath = join11(projectRoot, ".fabric", "project-rules.md");
+  const projectRulesPath = join13(projectRoot, ".fabric", "project-rules.md");
   const hasProjectRules = existsSync8(projectRulesPath);
   let expectedBody = snapshot;
   if (hasProjectRules) {
@@ -11198,8 +11751,8 @@ ${projectRules}`;
 ${expectedBody}
 ${BOOTSTRAP_MARKER_END}`;
   const blockTargets = [
-    join11(projectRoot, "AGENTS.md"),
-    join11(projectRoot, ".cursor", "rules", "fabric-bootstrap.mdc")
+    join13(projectRoot, "AGENTS.md"),
+    join13(projectRoot, ".cursor", "rules", "fabric-bootstrap.mdc")
   ];
   for (const abs of blockTargets) {
     if (!existsSync8(abs)) {
@@ -11232,7 +11785,7 @@ ${managedBlock}
     }
     await atomicWriteText4(abs, next);
   }
-  const claudeMdPath = join11(projectRoot, "CLAUDE.md");
+  const claudeMdPath = join13(projectRoot, "CLAUDE.md");
   if (existsSync8(claudeMdPath)) {
     let claudeContent;
     try {
@@ -11261,13 +11814,13 @@ ${managedBlock}
   }
 }
 async function fixMcpConfigInWrongFile(projectRoot) {
-  const settingsPath = join11(projectRoot, ".claude", "settings.json");
+  const settingsPath = join13(projectRoot, ".claude", "settings.json");
   if (!existsSync8(settingsPath)) {
     return;
   }
   let settings;
   try {
-    const parsed = JSON.parse(readFileSync3(settingsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync4(settingsPath, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return;
     }
@@ -11295,38 +11848,40 @@ async function fixMcpConfigInWrongFile(projectRoot) {
 }
 async function ensureKnowledgeSubdirs(projectRoot) {
   for (const sub of KNOWLEDGE_SUBDIRS3) {
-    await mkdir6(join11(projectRoot, ".fabric", "knowledge", sub), { recursive: true });
+    await mkdir5(join13(projectRoot, ".fabric", "knowledge", sub), { recursive: true });
   }
 }
 async function fixCounterDesync(projectRoot) {
-  const metaPath = join11(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join13(projectRoot, ".fabric", "agents.meta.json");
   if (!existsSync8(metaPath)) {
     return;
   }
-  let meta;
-  try {
-    meta = agentsMetaSchema5.parse(JSON.parse(await readFile13(metaPath, "utf8")));
-  } catch {
-    return;
-  }
-  const synthetic = {
-    present: true,
-    valid: true,
-    meta,
-    revision: meta.revision,
-    computedRevision: null,
-    ruleCount: 0,
-    missingContentRefs: [],
-    invalidContentRefs: [],
-    stale: false,
-    changed: false
-  };
-  const desync = inspectCounterDesync(synthetic);
-  if (desync.desyncs.length === 0 || desync.correctedCounters === null) {
-    return;
-  }
-  const updated = { ...meta, counters: desync.correctedCounters };
-  await atomicWriteJson3(metaPath, updated, { indent: 2 });
+  await withFileLock4(`${metaPath}.lock`, async () => {
+    let meta;
+    try {
+      meta = agentsMetaSchema5.parse(JSON.parse(await readFile13(metaPath, "utf8")));
+    } catch {
+      return;
+    }
+    const synthetic = {
+      present: true,
+      valid: true,
+      meta,
+      revision: meta.revision,
+      computedRevision: null,
+      ruleCount: 0,
+      missingContentRefs: [],
+      invalidContentRefs: [],
+      stale: false,
+      changed: false
+    };
+    const desync = inspectCounterDesync(synthetic);
+    if (desync.desyncs.length === 0 || desync.correctedCounters === null) {
+      return;
+    }
+    const updated = { ...meta, counters: desync.correctedCounters };
+    await atomicWriteJson3(metaPath, updated, { indent: 2 });
+  });
 }
 async function ensureEventLedger(projectRoot) {
   const path2 = getEventLedgerPath(projectRoot);
@@ -11364,7 +11919,7 @@ function collectEntryPoints(root) {
       continue;
     }
     for (const entry of readdirSync(current, { withFileTypes: true })) {
-      const absolutePath = join11(current, entry.name);
+      const absolutePath = join13(current, entry.name);
       const relativePath = normalizePath(absolutePath.slice(root.length + 1));
       if (relativePath.length === 0) {
         continue;
@@ -11436,8 +11991,8 @@ async function enrichDescriptions(projectRoot, opts = {}) {
   let modified = 0;
   let skipped = 0;
   for (const visit of iterateCanonicalFilenames(projectRoot)) {
-    const layerRoot = visit.layer === "team" ? join11(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
-    const absPath = join11(layerRoot, visit.type, visit.filename);
+    const layerRoot = visit.layer === "team" ? join13(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
+    const absPath = join13(layerRoot, visit.type, visit.filename);
     scanned += 1;
     let source;
     try {
@@ -11538,6 +12093,144 @@ function yamlQuoteIfNeeded(value) {
   return value;
 }
 
+// src/services/doctor-conflict.ts
+import { readFile as readFile14 } from "fs/promises";
+
+// src/services/conflict-lint.ts
+var DEFAULT_CONFLICT_SIMILARITY_THRESHOLD = 0.5;
+function groupKey(entry) {
+  return `${entry.layer}\0${entry.knowledge_type}`;
+}
+function pairSimilarity(model, a, b) {
+  const selfA = model.scoreDoc(a.id, a.tokens);
+  const selfB = model.scoreDoc(b.id, b.tokens);
+  if (selfA <= 0 || selfB <= 0) return 0;
+  const aToB = model.scoreDoc(b.id, a.tokens) / selfB;
+  const bToA = model.scoreDoc(a.id, b.tokens) / selfA;
+  const sim = Math.min(aToB, bToA);
+  return sim < 0 ? 0 : sim > 1 ? 1 : sim;
+}
+function findConflictCandidates(entries, opts = {}) {
+  const threshold = typeof opts.threshold === "number" && opts.threshold >= 0 && opts.threshold <= 1 ? opts.threshold : DEFAULT_CONFLICT_SIMILARITY_THRESHOLD;
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (typeof entry.stable_id !== "string" || entry.stable_id.length === 0) continue;
+    const list = groups.get(groupKey(entry)) ?? [];
+    list.push(entry);
+    groups.set(groupKey(entry), list);
+  }
+  const pairs = [];
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const docs = group.map((e) => ({ id: e.stable_id, tokens: buildQueryTerms(e.text) }));
+    const tokensById = new Map(docs.map((d) => [d.id, d.tokens]));
+    const model = buildBm25Model(docs);
+    for (let i = 0; i < group.length; i += 1) {
+      for (let j = i + 1; j < group.length; j += 1) {
+        const ea = group[i];
+        const eb = group[j];
+        const sim = pairSimilarity(
+          model,
+          { id: ea.stable_id, tokens: tokensById.get(ea.stable_id) ?? [] },
+          { id: eb.stable_id, tokens: tokensById.get(eb.stable_id) ?? [] }
+        );
+        if (sim < threshold) continue;
+        const [a, b] = ea.stable_id <= eb.stable_id ? [ea.stable_id, eb.stable_id] : [eb.stable_id, ea.stable_id];
+        pairs.push({
+          a,
+          b,
+          knowledge_type: ea.knowledge_type,
+          layer: ea.layer,
+          similarity: sim,
+          verdict: "unknown"
+        });
+      }
+    }
+  }
+  pairs.sort((x, y) => y.similarity - x.similarity || (x.a < y.a ? -1 : x.a > y.a ? 1 : x.b < y.b ? -1 : 1));
+  return pairs;
+}
+async function lintConflicts(entries, opts = {}) {
+  const candidates = findConflictCandidates(entries, { threshold: opts.threshold });
+  if (opts.judge === void 0 || candidates.length === 0) {
+    return candidates;
+  }
+  const byId = new Map(entries.map((e) => [e.stable_id, e]));
+  const judged = [];
+  for (const pair of candidates) {
+    const ea = byId.get(pair.a);
+    const eb = byId.get(pair.b);
+    if (ea === void 0 || eb === void 0) {
+      judged.push(pair);
+      continue;
+    }
+    try {
+      const verdict = await opts.judge(ea, eb);
+      judged.push({
+        ...pair,
+        verdict: verdict.isConflict ? "conflict" : "similar",
+        rationale: verdict.rationale
+      });
+    } catch {
+      judged.push(pair);
+    }
+  }
+  return judged;
+}
+
+// src/services/doctor-conflict.ts
+function stripFrontmatter(content) {
+  if (!content.startsWith("---")) return content;
+  const end = content.indexOf("\n---", 3);
+  if (end === -1) return content;
+  const after = content.indexOf("\n", end + 1);
+  return after === -1 ? "" : content.slice(after + 1);
+}
+async function loadConflictEntries(projectRoot) {
+  let meta;
+  try {
+    meta = await readAgentsMeta(projectRoot);
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const node of Object.values(meta.nodes)) {
+    const stableId = node.stable_id;
+    if (typeof stableId !== "string" || stableId.length === 0) continue;
+    const contentRef = node.content_ref;
+    if (typeof contentRef !== "string" || contentRef.length === 0) continue;
+    if (contentRef.includes("/pending/")) continue;
+    const knowledgeType = node.description?.knowledge_type;
+    if (typeof knowledgeType !== "string" || knowledgeType.length === 0) continue;
+    const layer = stableId.startsWith("KP-") ? "personal" : "team";
+    let body;
+    try {
+      body = await readFile14(resolveContentRefPath2(projectRoot, contentRef), "utf8");
+    } catch {
+      continue;
+    }
+    entries.push({ stable_id: stableId, knowledge_type: knowledgeType, layer, text: stripFrontmatter(body) });
+  }
+  return entries;
+}
+async function runDoctorConflictLint(projectRoot, opts = {}) {
+  const threshold = typeof opts.threshold === "number" ? opts.threshold : readConflictLintThreshold(projectRoot) ?? DEFAULT_CONFLICT_SIMILARITY_THRESHOLD;
+  const deep = opts.deep === true && opts.judge !== void 0;
+  const entries = await loadConflictEntries(projectRoot);
+  const pairs = await lintConflicts(entries, {
+    threshold,
+    judge: deep ? opts.judge : void 0
+  });
+  return {
+    status: "ok",
+    threshold,
+    deep,
+    candidate_count: pairs.length,
+    conflict_count: pairs.filter((p) => p.verdict === "conflict").length,
+    pairs
+  };
+}
+
 // src/services/rotation-tick.ts
 var DEFAULT_TICK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
 var tickTimers = /* @__PURE__ */ new Map();
@@ -11573,7 +12266,7 @@ import { IOFabricError as IOFabricError2, RuleError } from "@fenglimg/fabric-sha
 
 // src/services/read-ledger.ts
 import { randomUUID as randomUUID8 } from "crypto";
-import { access as access3, copyFile, readFile as readFile14, rm } from "fs/promises";
+import { access as access3, copyFile, readFile as readFile15, rm } from "fs/promises";
 import { ledgerEntrySchema } from "@fenglimg/fabric-shared";
 async function resolveLedgerPaths(projectRoot) {
   const primaryPath = getLedgerPath(projectRoot);
@@ -11601,7 +12294,7 @@ async function readLegacyLedger(projectRoot) {
   const { readPath } = await resolveLedgerPaths(projectRoot);
   let raw;
   try {
-    raw = await readFile14(readPath, "utf8");
+    raw = await readFile15(readPath, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") {
       return [];
@@ -11858,8 +12551,8 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync9(join12(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync9(join12(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync9(join14(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync9(join14(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
   if (preexisting.length === 0) return null;
   return `[startup] info: detected ${preexisting.join(", ")} at project root. Note: Fabric serves knowledge from .fabric/knowledge/ via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
 }
@@ -11887,7 +12580,7 @@ function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.2.0-rc.1"
+      version: "2.2.0-rc.3"
     },
     {
       instructions: FABRIC_SERVER_INSTRUCTIONS
@@ -11908,10 +12601,10 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path2 = join12(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path2 = join14(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
       if (existsSync9(path2)) {
-        text = await readFile15(path2, "utf8");
+        text = await readFile16(path2, "utf8");
       }
       return {
         contents: [
@@ -12016,6 +12709,7 @@ if (isMainModule) {
 }
 export {
   AGENTS_MD_RESOURCE_URI,
+  DEFAULT_CONFLICT_SIMILARITY_THRESHOLD,
   EVENT_LEDGER_PATH,
   FABRIC_SERVER_INSTRUCTIONS,
   KnowledgeIdAllocator,
@@ -12038,6 +12732,7 @@ export {
   enrichDescriptions,
   ensureKnowledgeFresh,
   extractKnowledge,
+  findConflictCandidates,
   flushAndSyncEventLedger,
   flushMetrics,
   formatPreexistingRootMessage,
@@ -12048,7 +12743,10 @@ export {
   getMetricsLedgerPath,
   invalidateKnowledgeSyncCooldown,
   isSameKnowledgeTestIndex,
+  lintConflicts,
+  loadConflictEntries,
   loadKbIdTypeMap,
+  pairSimilarity,
   planContext,
   readAgentsMeta,
   readEventLedger,
@@ -12063,6 +12761,7 @@ export {
   runDoctorApplyLint,
   runDoctorArchiveHistory,
   runDoctorCiteCoverage,
+  runDoctorConflictLint,
   runDoctorFix,
   runDoctorHistoryAll,
   runDoctorReport,