@fenglimg/fabric-server 2.2.0-rc.9 → 2.3.0-rc.1

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
-import { existsSync as existsSync8 } from "fs";
-import { readFile as readFile16 } from "fs/promises";
-import { join as join20, resolve as resolve4 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { readFile as readFile19 } from "fs/promises";
+import { join as join23, resolve as resolve4 } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -675,12 +675,14 @@ function createInFlightTracker() {
 
 // src/tools/extract-knowledge.ts
 import { randomUUID as randomUUID2 } from "crypto";
+import { ZodError } from "zod";
 import {
   FabExtractKnowledgeInputShape,
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeOutputSchema,
   fabExtractKnowledgeAnnotations
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
+import { SCOPE_COORDINATE_HINT } from "@fenglimg/fabric-shared";
 import { enforcePayloadLimit } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
 
 // src/tools/payload-warning.ts
@@ -782,6 +784,18 @@ function readRecallRelevanceRatio(projectRoot) {
     return RECALL_RELEVANCE_RATIO_DEFAULT;
   }
 }
+var BROAD_REVIEW_RECHECK_DAYS_DEFAULT = 180;
+function readBroadReviewRecheckThresholdDays(projectRoot) {
+  try {
+    const raw = readFabricConfig(projectRoot).broad_review_recheck_days;
+    if (typeof raw === "number" && Number.isFinite(raw) && Number.isInteger(raw) && raw >= 1 && raw <= 3650) {
+      return raw;
+    }
+    return BROAD_REVIEW_RECHECK_DAYS_DEFAULT;
+  } catch {
+    return BROAD_REVIEW_RECHECK_DAYS_DEFAULT;
+  }
+}
 function readOrphanDemoteThresholdDays(projectRoot) {
   try {
     const cfg = readFabricConfig(projectRoot);
@@ -870,8 +884,8 @@ async function awaitFirstReconcileGate(timeoutMs = 5e3) {
 
 // src/services/extract-knowledge.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile3 } from "fs/promises";
-import { join as join6 } from "path";
+import { readFile as readFile4 } from "fs/promises";
+import { join as join7 } from "path";
 import {
   PROPOSED_REASON_DESCRIPTIONS_BY_LOCALE
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
@@ -894,7 +908,7 @@ import {
   StoreWriteTargetUnresolvedError
 } from "@fenglimg/fabric-shared/errors";
 function writeTargetUnresolved(scope, layer) {
-  const actionHint = layer === "personal" ? "run `fabric install --global` to mint your personal store, then retry" : `mount + bind a shared store, then set an explicit route: \`fabric store route-write ${scope} <alias>\``;
+  const actionHint = layer === "personal" ? "run `fabric install --global` to mint your personal store, then retry" : `mount + bind a shared store, then set an explicit route: \`fabric store switch-write <alias> --scope ${scope}\``;
   return new StoreWriteTargetUnresolvedError(
     `no write-target store resolved for scope '${scope}' \u2014 knowledge writes are store-only (dual-root co-location removed)`,
     { actionHint, fixable: true, details: { layer, scope } }
@@ -954,1169 +968,1443 @@ function resolveWriteScopeMeta(layer, projectRoot, semanticScope) {
   return { semantic_scope, visibility_store: target.alias };
 }
 
-// src/services/extract-knowledge.ts
-var SLUG_MAX_LENGTH = 40;
-var INJECTION_PATTERNS = [
-  {
-    name: "ignore-prior-instructions",
-    pattern: /\b(?:ignore|forget|disregard)\s+(?:all\s+)?(?:previous|prior|above|earlier)\s+(?:instructions?|messages?|prompts?|rules?)\b/giu
-  },
-  {
-    name: "forget-your-role",
-    pattern: /\b(?:forget|disregard|ignore)\s+(?:your|the)\s+(?:role|identity|system\s+prompt)\b/giu
-  },
-  {
-    name: "you-are-now",
-    pattern: /\byou\s+are\s+now\s+(?:a|an)\s+\w+\s+(?:assistant|agent|model|bot|persona)\b/giu
-  },
-  {
-    name: "rm-rf-root",
-    pattern: /\brm\s+-rf?\s+(?:--no-preserve-root\s+)?[/~][^\s`'")>}]*?\s*(?:\/[*]?|;|$|\n|\|)/giu
-  },
-  {
-    name: "shell-eval-curl",
-    pattern: /\b(?:eval|sh|bash|zsh)\s+(?:-\w+\s+)?["'`]?\$\(\s*curl\s+[^)]+\)/giu
-  },
-  {
-    name: "chatml-envelope",
-    pattern: /<\|(?:im_start|im_end|system|user|assistant|endoftext|fim_prefix|fim_suffix|fim_middle)\|>/giu
-  },
-  {
-    name: "claude-envelope",
-    pattern: /\b(?:Human:|Assistant:)\s*<.*?>/giu
+// src/services/cross-store-recall.ts
+import { readFile as readFile3, stat } from "fs/promises";
+import { join as join6 } from "path";
+import {
+  buildStoreResolveInput as buildStoreResolveInput2,
+  createStoreResolver as createStoreResolver2,
+  loadProjectConfig as loadProjectConfig2,
+  readKnowledgeAcrossStores,
+  resolveGlobalRoot as resolveGlobalRoot2,
+  scopeRoot,
+  storeRelativePathForMount as storeRelativePathForMount2
+} from "@fenglimg/fabric-shared";
+
+// src/services/knowledge-meta-builder.ts
+import {
+  deriveAgentsMetaStableId,
+  isKnowledgeStableId,
+  KnowledgeTypeSchema,
+  LayerSchema,
+  MaturitySchema,
+  parseKnowledgeId,
+  StableIdSchema
+} from "@fenglimg/fabric-shared";
+function toAgentsCompatiblePath(contentRef) {
+  return contentRef.replace(/^~\/\.fabric\/knowledge\//u, ".fabric/agents/").replace(/^\.fabric\/knowledge\//u, ".fabric/agents/");
+}
+function deriveRuleIdentity(file, source, existing) {
+  const declaredKnowledgeId = extractDeclaredKnowledgeId(source);
+  if (declaredKnowledgeId !== void 0) {
+    return {
+      stableId: declaredKnowledgeId,
+      identitySource: "declared"
+    };
   }
-];
-var INJECTION_REDACTION_MARKER = "[REDACTED: prompt-injection pattern stripped by fab_extract_knowledge \u2014 NEW-31]";
-function sanitizeInjectionPatterns(input) {
-  let sanitized = input;
-  const redactions = [];
-  for (const { name, pattern } of INJECTION_PATTERNS) {
-    const matches = sanitized.match(pattern);
-    if (matches === null || matches.length === 0) continue;
-    redactions.push({ name, matches: matches.length });
-    sanitized = sanitized.replace(pattern, INJECTION_REDACTION_MARKER);
+  if (existing?.stable_id !== void 0 && isKnowledgeStableId(existing.stable_id)) {
+    return {
+      stableId: existing.stable_id,
+      identitySource: "declared"
+    };
   }
-  return { sanitized, redactions };
-}
-function sanitizeInjectionFields(fields) {
-  const out = { ...fields };
-  const allRedactions = [];
-  for (const [key, value] of Object.entries(fields)) {
-    if (typeof value === "string") {
-      const { sanitized, redactions } = sanitizeInjectionPatterns(value);
-      out[key] = sanitized;
-      for (const r of redactions) {
-        allRedactions.push({ field: key, ...r });
-      }
-    } else if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
-      const cleaned = [];
-      for (const entry of value) {
-        const { sanitized, redactions } = sanitizeInjectionPatterns(entry);
-        cleaned.push(sanitized);
-        for (const r of redactions) {
-          allRedactions.push({ field: key, ...r });
-        }
-      }
-      out[key] = cleaned;
-    }
+  const declaredStableId = extractDeclaredStableId(source);
+  const derivedStableId = deriveAgentsMetaStableId(toAgentsCompatiblePath(file));
+  if (declaredStableId !== void 0) {
+    return {
+      stableId: declaredStableId,
+      identitySource: "declared"
+    };
   }
-  return { sanitized: out, allRedactions };
-}
-function redactPiiFields(fields) {
-  const out = { ...fields };
-  const redactedFields = /* @__PURE__ */ new Set();
-  for (const [key, value] of Object.entries(fields)) {
-    if (typeof value === "string") {
-      const cleaned = redactPii(value);
-      out[key] = cleaned;
-      if (cleaned !== value) redactedFields.add(key);
-    } else if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
-      const cleaned = value.map((entry) => redactPii(entry));
-      out[key] = cleaned;
-      if (cleaned.some((entry, index) => entry !== value[index])) {
-        redactedFields.add(key);
-      }
-    }
+  if (existing?.identity_source === "declared" && existing.stable_id !== void 0 && existing.stable_id !== derivedStableId) {
+    return {
+      stableId: existing.stable_id,
+      identitySource: "declared"
+    };
   }
-  return { redacted: out, redactedFields: [...redactedFields].sort() };
+  return {
+    stableId: derivedStableId,
+    identitySource: "derived"
+  };
 }
-function pendingBase(layer, projectRoot, semanticScope) {
-  return resolveStorePendingBase(layer, projectRoot, semanticScope);
+function extractDeclaredStableId(source) {
+  const match = /^(?:\uFEFF)?(?:---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$))?<!--\s*fab:rule-id\s+([A-Za-z0-9][A-Za-z0-9/_-]*)\s*-->\s*(?:\r?\n|$)/u.exec(source);
+  return match?.[1];
 }
-function toPosixPath(path) {
-  return path.replace(/\\/gu, "/");
+function extractDeclaredKnowledgeId(source) {
+  const frontmatter = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/u.exec(source);
+  if (frontmatter === null) {
+    return void 0;
+  }
+  const idMatch = /^id:\s*(.+?)\s*$/mu.exec(frontmatter[1]);
+  if (idMatch === null) {
+    return void 0;
+  }
+  const candidate = idMatch[1].replace(/^["'](.*)["']$/u, "$1").trim();
+  return isKnowledgeStableId(candidate) ? candidate : void 0;
 }
-async function extractKnowledge(projectRoot, input) {
-  const sanitizedInputFields = sanitizeInjectionFields({
-    slug: input.slug ?? "",
-    user_messages_summary: input.user_messages_summary ?? "",
-    session_context: input.session_context ?? "",
-    must_read_if: input.must_read_if ?? "",
-    intent_clues: input.intent_clues ?? []
-  });
-  input = {
-    ...input,
-    slug: sanitizedInputFields.sanitized.slug,
-    user_messages_summary: sanitizedInputFields.sanitized.user_messages_summary || void 0,
-    session_context: sanitizedInputFields.sanitized.session_context || void 0,
-    must_read_if: sanitizedInputFields.sanitized.must_read_if || void 0,
-    intent_clues: sanitizedInputFields.sanitized.intent_clues.length > 0 ? sanitizedInputFields.sanitized.intent_clues : void 0
-  };
-  if (sanitizedInputFields.allRedactions.length > 0) {
-    const summary2 = sanitizedInputFields.allRedactions.map((r) => `${r.field}:${r.name}x${r.matches}`).join(",");
-    const primarySessionForLog = (input.source_sessions ?? [])[0] ?? "";
-    await emitEventBestEffort(projectRoot, {
-      event_type: "knowledge_archive_attempted",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      correlation_id: primarySessionForLog,
-      session_id: primarySessionForLog,
-      reason: `extract_knowledge:injection-redacted:${summary2}`
-    });
+function extractRuleDescription(source) {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/u.exec(source);
+  const description = frontmatter === null ? void 0 : extractDescriptionFromFrontmatter(frontmatter[1]);
+  if (description !== void 0) {
+    return description;
   }
-  const piiRedactedInputFields = redactPiiFields({
-    slug: input.slug ?? "",
-    user_messages_summary: input.user_messages_summary ?? "",
-    session_context: input.session_context ?? "",
-    must_read_if: input.must_read_if ?? "",
-    intent_clues: input.intent_clues ?? [],
-    tags: input.tags ?? [],
-    evidence_paths: input.evidence_paths ?? []
-  });
-  input = {
-    ...input,
-    slug: piiRedactedInputFields.redacted.slug,
-    user_messages_summary: piiRedactedInputFields.redacted.user_messages_summary || void 0,
-    session_context: piiRedactedInputFields.redacted.session_context || void 0,
-    must_read_if: piiRedactedInputFields.redacted.must_read_if || void 0,
-    intent_clues: piiRedactedInputFields.redacted.intent_clues.length > 0 ? piiRedactedInputFields.redacted.intent_clues : void 0,
-    tags: piiRedactedInputFields.redacted.tags.length > 0 ? piiRedactedInputFields.redacted.tags : void 0,
-    evidence_paths: piiRedactedInputFields.redacted.evidence_paths.length > 0 ? piiRedactedInputFields.redacted.evidence_paths : void 0
+  const heading = /^#\s+(.+?)\s*$/mu.exec(source);
+  const summary = heading?.[1]?.trim();
+  const knowledge = frontmatter !== null ? extractKnowledgeFieldsFromFrontmatter(frontmatter[1]) : void 0;
+  const isStructurallyAKnowledgeEntry = summary !== void 0 && summary.length > 0 ? true : knowledge !== void 0 && (knowledge.id !== void 0 || knowledge.knowledge_type !== void 0 || knowledge.tags !== void 0 && knowledge.tags.length > 0);
+  if (!isStructurallyAKnowledgeEntry) {
+    return void 0;
+  }
+  const synthesizedSummary = summary !== void 0 && summary.length > 0 ? summary : knowledge?.id ?? (knowledge?.tags !== void 0 && knowledge.tags.length > 0 ? `(unnamed; tags: ${knowledge.tags.join(", ")})` : "(unnamed knowledge entry)");
+  return {
+    summary: synthesizedSummary,
+    intent_clues: [],
+    tech_stack: [],
+    impact: [],
+    must_read_if: synthesizedSummary,
+    // v2.0-rc.22: when frontmatter is present, merge its knowledge fields;
+    // when fully absent (no `---` block), all knowledge fields stay
+    // undefined, matching the original heading-only fallback contract.
+    id: knowledge?.id,
+    knowledge_type: knowledge?.knowledge_type,
+    maturity: knowledge?.maturity,
+    knowledge_layer: knowledge?.knowledge_layer,
+    layer_reason: knowledge?.layer_reason,
+    created_at: knowledge?.created_at,
+    tags: knowledge?.tags,
+    // v2.0-rc.5 (C1): default-safe values when there is no frontmatter at all;
+    // when frontmatter exists, honor its declared values (extractKnowledge
+    // FieldsFromFrontmatter already applies the broad-default for missing
+    // or malformed scopes).
+    relevance_scope: knowledge?.relevance_scope ?? "broad",
+    relevance_paths: knowledge?.relevance_paths ?? [],
+    // v2.2 H2-related (W1-T7): graph edges, undefined when absent.
+    related: knowledge?.related
   };
-  if (piiRedactedInputFields.redactedFields.length > 0) {
-    const primarySessionForLog = (input.source_sessions ?? [])[0] ?? "";
-    await emitEventBestEffort(projectRoot, {
-      event_type: "knowledge_archive_attempted",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      correlation_id: primarySessionForLog,
-      session_id: primarySessionForLog,
-      reason: `extract_knowledge:pii-redacted:${piiRedactedInputFields.redactedFields.join(",")}`
-    });
+}
+function extractDescriptionFromFrontmatter(frontmatter) {
+  const summary = extractScalar(frontmatter, "summary") ?? extractScalar(frontmatter, "description");
+  if (summary === void 0) {
+    return void 0;
   }
-  const sanitizedSlug = sanitizeSlug(input.slug);
-  const sourceSessions = input.source_sessions ?? [];
-  const primarySession = sourceSessions[0] ?? "";
-  const idempotencyKey = sha256(
-    JSON.stringify({
-      source_session: primarySession,
-      type: input.type,
-      slug: sanitizedSlug
-    })
-  );
-  const summary = input.user_messages_summary ?? "";
-  const summaryTrimmed = summary.trim();
-  const summaryIsEmpty = summaryTrimmed.length === 0;
-  const slugIsEmpty = sanitizedSlug.length === 0;
-  const summaryTooShort = !summaryIsEmpty && summaryTrimmed.length < 15;
-  const summaryEqualsSlug = !summaryIsEmpty && summaryTrimmed.toLowerCase() === sanitizedSlug.toLowerCase();
-  const summaryLooksLikeStableId = !summaryIsEmpty && /^K[TP]-[A-Z]{3}-\d{4}$/.test(summaryTrimmed);
-  const summaryIsOpaque = summaryTooShort || summaryEqualsSlug || summaryLooksLikeStableId;
-  if (summaryIsEmpty || slugIsEmpty || summaryIsOpaque) {
-    const reason = summaryIsEmpty ? "empty_summary" : slugIsEmpty ? "empty_slug" : summaryTooShort ? "summary_too_short" : summaryEqualsSlug ? "summary_equals_slug" : "summary_looks_like_stable_id";
-    await emitEventBestEffort(projectRoot, {
-      event_type: "knowledge_archive_attempted",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      correlation_id: primarySession,
-      session_id: primarySession,
-      reason: `extract_knowledge:${sanitizedSlug || input.slug}:${reason}`
-    });
-    return {
-      pending_path: "",
-      idempotency_key: idempotencyKey
-    };
-  }
-  const secretScanTarget = [
-    input.slug ?? "",
-    input.user_messages_summary ?? "",
-    input.session_context ?? "",
-    input.must_read_if ?? "",
-    ...input.intent_clues ?? [],
-    ...input.tags ?? [],
-    ...input.evidence_paths ?? []
-  ].join("\n");
-  if (hasSecrets(secretScanTarget)) {
-    await emitEventBestEffort(projectRoot, {
-      event_type: "knowledge_archive_attempted",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      correlation_id: primarySession,
-      session_id: primarySession,
-      reason: `extract_knowledge:${sanitizedSlug || input.slug}:secret_detected`
-    });
-    return {
-      pending_path: "",
-      idempotency_key: idempotencyKey
-    };
+  const knowledge = extractKnowledgeFieldsFromFrontmatter(frontmatter);
+  return {
+    summary,
+    intent_clues: extractInlineArray(frontmatter, "intent_clues"),
+    tech_stack: extractInlineArray(frontmatter, "tech_stack"),
+    impact: extractInlineArray(frontmatter, "impact"),
+    must_read_if: extractScalar(frontmatter, "must_read_if") ?? summary,
+    entities: extractInlineArray(frontmatter, "entities"),
+    id: knowledge.id,
+    knowledge_type: knowledge.knowledge_type,
+    maturity: knowledge.maturity,
+    knowledge_layer: knowledge.knowledge_layer,
+    layer_reason: knowledge.layer_reason,
+    created_at: knowledge.created_at,
+    tags: knowledge.tags,
+    relevance_scope: knowledge.relevance_scope,
+    relevance_paths: knowledge.relevance_paths,
+    // v2.2 H2-related (W1-T7): graph edges parsed from frontmatter.
+    related: knowledge.related
+  };
+}
+function isForbiddenCrossLayerEdge(sourceLayer, targetId) {
+  if (sourceLayer !== "team") {
+    return false;
   }
-  const semanticScope = input.semantic_scope;
-  const scopeIsPersonal = semanticScope !== void 0 && isPersonalScope(semanticScope);
-  if (semanticScope !== void 0 && input.layer !== void 0 && scopeIsPersonal !== (input.layer === "personal")) {
-    throw new Error(
-      `semantic_scope '${semanticScope}' conflicts with compatibility layer '${input.layer}'`
-    );
+  const decoded = parseKnowledgeId(localKnowledgeIdFromReference(targetId));
+  if (decoded === null) {
+    return false;
   }
-  const layer = scopeIsPersonal ? "personal" : input.layer ?? "team";
-  let relevanceScope = input.relevance_scope;
-  let relevancePaths = input.relevance_paths;
-  const shouldAutoDegrade = layer === "personal" && relevanceScope === "narrow";
-  if (shouldAutoDegrade) {
-    relevanceScope = "broad";
-    relevancePaths = [];
-    await emitEventBestEffort(projectRoot, {
-      event_type: "knowledge_scope_degraded",
-      stable_id: `pending:${idempotencyKey}`,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      from_scope: "narrow",
-      to_scope: "broad",
-      reason: "personal-implies-broad"
-    });
+  return decoded.layer === "personal";
+}
+function localKnowledgeIdFromReference(ref) {
+  const direct = parseKnowledgeId(ref);
+  if (direct !== null) {
+    return ref;
   }
-  const baseDir = pendingBase(layer, projectRoot, semanticScope);
-  const { absolutePath, sanitizedSlug: chosenSlug, idempotencyKey: chosenKey } = await resolveDisambiguatedSlugPath({
-    baseDir,
-    type: input.type,
-    slug: sanitizedSlug,
-    primarySession,
-    baseIdempotencyKey: idempotencyKey
-  });
-  const reportedPath = toPosixPath(absolutePath);
-  const effectiveSanitizedSlug = chosenSlug;
-  const effectiveIdempotencyKey = chosenKey;
-  const writeScopeMeta = resolveWriteScopeMeta(layer, projectRoot, semanticScope);
-  await ensureParentDirectory(absolutePath);
-  if (existsSync3(absolutePath)) {
-    const existing = await readFile3(absolutePath, "utf8");
-    const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
-    if (existingKey === effectiveIdempotencyKey) {
-      const fresh2 = renderFreshEntry({
-        type: input.type,
-        sourceSessions,
-        idempotencyKey: effectiveIdempotencyKey,
-        summary,
-        recentPaths: input.recent_paths,
-        layer,
-        semanticScope: writeScopeMeta.semantic_scope,
-        visibilityStore: writeScopeMeta.visibility_store,
-        proposedReason: input.proposed_reason,
-        sessionContext: input.session_context,
-        relevanceScope,
-        relevancePaths,
-        intentClues: input.intent_clues,
-        techStack: input.tech_stack,
-        impact: input.impact,
-        mustReadIf: input.must_read_if,
-        onboardSlot: input.onboard_slot,
-        // v2.0.0-rc.37 NEW-37: pass-through topic tags.
-        tags: input.tags,
-        // v2.0.0-rc.37 NEW-7: pass-through evidence_paths to frontmatter.
-        evidencePaths: input.evidence_paths
-      });
-      const augmented = mergeEvidenceNotes(existing, fresh2);
-      await atomicWriteText(absolutePath, augmented);
-      await emitEventBestEffort(projectRoot, {
-        event_type: "knowledge_proposed",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        correlation_id: primarySession,
-        session_id: primarySession,
-        reason: `extract_knowledge:${effectiveSanitizedSlug}`
-      });
-      return {
-        pending_path: reportedPath,
-        idempotency_key: effectiveIdempotencyKey
-      };
+  const tail = ref.split(":").at(-1);
+  return tail ?? ref;
+}
+function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
+  const rawId = extractScalar(frontmatter, "id");
+  const rawType = extractScalar(frontmatter, "type");
+  const rawMaturity = extractScalar(frontmatter, "maturity");
+  const rawLayer = extractScalar(frontmatter, "layer");
+  const rawLayerReason = extractScalar(frontmatter, "layer_reason");
+  const rawCreatedAt = extractScalar(frontmatter, "created_at");
+  let id;
+  if (rawId !== void 0) {
+    const parsed = StableIdSchema.safeParse(rawId);
+    if (parsed.success) {
+      id = parsed.data;
+    } else {
+      process.stderr.write(`[fabric] frontmatter: invalid knowledge id format ${JSON.stringify(rawId)}; skipping
+`);
     }
-    throw new Error(
-      `slug collision (unreachable after rc.37 NEW-6): pending file ${reportedPath} already exists with key ${existingKey ?? "<missing>"} != ${effectiveIdempotencyKey}`
-    );
   }
-  const fresh = renderFreshEntry({
-    type: input.type,
-    sourceSessions,
-    idempotencyKey: effectiveIdempotencyKey,
-    summary,
-    recentPaths: input.recent_paths,
-    layer,
-    semanticScope: writeScopeMeta.semantic_scope,
-    visibilityStore: writeScopeMeta.visibility_store,
-    proposedReason: input.proposed_reason,
-    sessionContext: input.session_context,
-    relevanceScope,
-    relevancePaths,
-    intentClues: input.intent_clues,
-    techStack: input.tech_stack,
-    impact: input.impact,
-    mustReadIf: input.must_read_if,
-    onboardSlot: input.onboard_slot,
-    tags: input.tags,
-    // v2.0.0-rc.37 NEW-7: pass-through evidence_paths to frontmatter.
-    evidencePaths: input.evidence_paths
-  });
-  await atomicWriteText(absolutePath, fresh);
-  await emitEventBestEffort(projectRoot, {
-    event_type: "knowledge_proposed",
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    correlation_id: primarySession,
-    session_id: primarySession,
-    reason: `extract_knowledge:${effectiveSanitizedSlug}`
-  });
-  return {
-    pending_path: reportedPath,
-    idempotency_key: effectiveIdempotencyKey
+  const SINGULAR_TO_PLURAL = {
+    model: "models",
+    decision: "decisions",
+    guideline: "guidelines",
+    pitfall: "pitfalls",
+    process: "processes"
   };
-}
-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 = join6(args.baseDir, args.type, `${candidateSlug}.md`);
-    const candidateKey = n === 1 ? args.baseIdempotencyKey : sha256(
-      JSON.stringify({
-        source_session: args.primarySession,
-        type: args.type,
-        slug: candidateSlug
-      })
-    );
-    if (!existsSync3(candidatePath)) {
-      return {
-        absolutePath: candidatePath,
-        sanitizedSlug: candidateSlug,
-        idempotencyKey: candidateKey
-      };
+  let knowledge_type;
+  if (rawType !== void 0) {
+    const normalized = SINGULAR_TO_PLURAL[rawType] ?? rawType;
+    const parsed = KnowledgeTypeSchema.safeParse(normalized);
+    if (parsed.success) {
+      knowledge_type = parsed.data;
+    } else {
+      process.stderr.write(`[fabric] frontmatter: unknown knowledge type ${JSON.stringify(rawType)}; skipping
+`);
     }
-    const existing = await readFile3(candidatePath, "utf8");
-    const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
-    if (existingKey === candidateKey) {
-      return {
-        absolutePath: candidatePath,
-        sanitizedSlug: candidateSlug,
-        idempotencyKey: candidateKey
-      };
+  }
+  let maturity;
+  if (rawMaturity !== void 0) {
+    const parsed = MaturitySchema.safeParse(rawMaturity);
+    if (parsed.success) {
+      maturity = parsed.data;
+    } else {
+      process.stderr.write(`[fabric] frontmatter: unknown maturity ${JSON.stringify(rawMaturity)}; skipping
+`);
     }
   }
-  throw new Error(
-    `slug exhaustion: tried ${args.slug}.md plus -2..-${SLUG_DISAMBIGUATE_MAX_VARIANTS} suffix variants and all slots are taken by entries with different idempotency_keys; rename slug at the caller and retry`
-  );
-}
-function sanitizeSlug(raw) {
-  const lower = raw.toLowerCase();
-  const collapsed = lower.replace(/[^a-z0-9]+/g, "-");
-  const trimmed = collapsed.replace(/^-+|-+$/g, "");
-  if (trimmed.length === 0) {
-    return "";
-  }
-  return trimmed.slice(0, SLUG_MAX_LENGTH).replace(/-+$/g, "");
-}
-function renderFreshEntry(args) {
-  const createdAt = (/* @__PURE__ */ new Date()).toISOString();
-  const frontmatterLines = [
-    "---",
-    `type: ${args.type}`,
-    "maturity: draft",
-    `layer: ${args.layer}`,
-    // v2.1 global-refactor (W1/A1): scope coordinate (resolution axis) + the
-    // physical store this entry lives in. `layer` is retained for back-compat
-    // during the co-location retirement; `semantic_scope`/`visibility_store` are
-    // the v2.1 source of truth (scope ⊥ store).
-    `semantic_scope: ${args.semanticScope}`,
-    `visibility_store: ${quoteRelevancePath(args.visibilityStore)}`,
-    `created_at: ${createdAt}`,
-    `source_sessions: [${args.sourceSessions.map((s) => JSON.stringify(s)).join(", ")}]`,
-    `proposed_reason: ${args.proposedReason}`,
-    // rc.31 BUG-2.9/2.1: persist the caller-supplied summary in frontmatter so
-    // knowledge-meta-builder.extractDescriptionFromFrontmatter picks it up
-    // directly. Without this, the meta-builder fell back to extractRule
-    // Description's h1-or-stable-id-or-placeholder synthesis (line ~944),
-    // which made user-visible description.summary == stable_id for any
-    // pending file whose body started with h2-only sections (`## Summary` is
-    // the canonical pending shape). The frontmatter `summary:` line is the
-    // canonical source-of-truth: `extractDescriptionFromFrontmatter` reads it
-    // before extractRuleDescription's fallback kicks in.
-    `summary: ${quoteRelevancePath(args.summary)}`,
-    // v2.0.0-rc.37 NEW-37: render caller-supplied tags or fall back to empty
-    // array. Empty array still legal but doctor's knowledge_tags_empty_ratio
-    // lint will warn at the corpus level. Encourages 2-4 kebab-case topic
-    // strings per entry for cross-entry retrieval signal.
-    args.tags !== void 0 && args.tags.length > 0 ? `tags: [${args.tags.map((t) => quoteRelevancePath(t)).join(", ")}]` : "tags: []"
-  ];
-  if (args.relevanceScope !== void 0) {
-    frontmatterLines.push(`relevance_scope: ${args.relevanceScope}`);
-  }
-  if (args.relevancePaths !== void 0) {
-    const pathsBody = args.relevancePaths.map((p) => quoteRelevancePath(p)).join(", ");
-    frontmatterLines.push(`relevance_paths: [${pathsBody}]`);
-  }
-  if (args.intentClues !== void 0) {
-    const body2 = args.intentClues.map((s) => quoteRelevancePath(s)).join(", ");
-    frontmatterLines.push(`intent_clues: [${body2}]`);
-  }
-  if (args.techStack !== void 0) {
-    const body2 = args.techStack.map((s) => quoteRelevancePath(s)).join(", ");
-    frontmatterLines.push(`tech_stack: [${body2}]`);
+  let knowledge_layer;
+  if (rawLayer !== void 0) {
+    const parsed = LayerSchema.safeParse(rawLayer);
+    if (parsed.success) {
+      knowledge_layer = parsed.data;
+    } else {
+      process.stderr.write(`[fabric] frontmatter: unknown layer ${JSON.stringify(rawLayer)}; skipping
+`);
+    }
   }
-  if (args.impact !== void 0) {
-    const body2 = args.impact.map((s) => quoteRelevancePath(s)).join(", ");
-    frontmatterLines.push(`impact: [${body2}]`);
+  let created_at;
+  if (rawCreatedAt !== void 0) {
+    if (!Number.isNaN(Date.parse(rawCreatedAt))) {
+      created_at = rawCreatedAt;
+    } else {
+      process.stderr.write(`[fabric] frontmatter: malformed created_at ${JSON.stringify(rawCreatedAt)}; skipping
+`);
+    }
   }
-  if (args.mustReadIf !== void 0) {
-    frontmatterLines.push(`must_read_if: ${quoteRelevancePath(args.mustReadIf)}`);
+  if (id !== void 0 && knowledge_layer !== void 0) {
+    const decoded = parseKnowledgeId(id);
+    if (decoded !== null && decoded.layer !== knowledge_layer) {
+      process.stderr.write(
+        `[fabric] frontmatter: id ${id} encodes layer ${decoded.layer} but layer field says ${knowledge_layer}; dropping both
+`
+      );
+      id = void 0;
+      knowledge_layer = void 0;
+    }
   }
-  if (args.onboardSlot !== void 0) {
-    frontmatterLines.push(`onboard_slot: ${args.onboardSlot}`);
+  const tags = extractInlineArray(frontmatter, "tags");
+  const rawRelevanceScope = extractScalar(frontmatter, "relevance_scope");
+  const relevance_scope = rawRelevanceScope === "narrow" || rawRelevanceScope === "broad" ? rawRelevanceScope : "broad";
+  const relevance_paths = extractInlineArray(frontmatter, "relevance_paths");
+  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,
+    maturity,
+    knowledge_layer,
+    layer_reason: rawLayerReason,
+    created_at,
+    tags: tags.length > 0 ? tags : void 0,
+    relevance_scope,
+    relevance_paths,
+    related: related.length > 0 ? related : void 0
+  };
+}
+function extractScalar(frontmatter, key) {
+  const pattern = new RegExp(`^${escapeRegExp(key)}:\\s*(.+?)\\s*$`, "mu");
+  const match = pattern.exec(frontmatter);
+  if (match === null) {
+    return void 0;
   }
-  if (args.evidencePaths !== void 0 && args.evidencePaths.length > 0) {
-    const body2 = args.evidencePaths.map((p) => quoteRelevancePath(p)).join(", ");
-    frontmatterLines.push(`evidence_paths: [${body2}]`);
+  return unquote(match[1].trim());
+}
+function extractInlineArray(frontmatter, key) {
+  const pattern = new RegExp(`^${escapeRegExp(key)}:\\s*\\[(.*?)\\]\\s*$`, "mu");
+  const match = pattern.exec(frontmatter);
+  if (match === null) {
+    return [];
   }
-  frontmatterLines.push(
-    `x-fabric-idempotency-key: ${args.idempotencyKey}`,
-    "---"
-  );
-  const frontmatter = frontmatterLines.join("\n");
-  const reasonExplanation = PROPOSED_REASON_DESCRIPTIONS_BY_LOCALE[resolveGlobalLocale()][args.proposedReason];
-  const body = [
-    "",
-    "## Summary",
-    "",
-    args.summary,
-    "",
-    "## Why proposed",
-    "",
-    `${args.proposedReason} \u2014 ${reasonExplanation}`,
-    "",
-    "## Session context",
-    "",
-    args.sessionContext,
-    "",
-    "## Evidence",
-    "",
-    renderEvidenceBlock(args.summary, args.recentPaths),
-    ""
-  ].join("\n");
-  return `${frontmatter}
-${body}`;
+  return match[1].split(",").map((item) => unquote(item.trim())).filter((item) => item.length > 0);
 }
-function quoteRelevancePath(value) {
-  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
-  return `"${escaped}"`;
+function unquote(value) {
+  return value.replace(/^["'](.*)["']$/u, "$1");
 }
-function renderEvidenceBlock(summary, recentPaths) {
-  const pathLines = recentPaths.length === 0 ? "_(no recent paths reported)_" : recentPaths.map((p) => `- ${p}`).join("\n");
-  return [
-    "Recent paths:",
-    "",
-    pathLines,
-    "",
-    "Notes:",
-    "",
-    `- ${summary.trim()}`
-  ].join("\n");
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
-function mergeEvidenceNotes(existing, fresh) {
-  const freshSplit = splitAtEvidence(fresh);
-  if (freshSplit === null) {
-    return fresh.endsWith("\n") ? fresh : `${fresh}
-`;
-  }
-  const freshHead = freshSplit.head;
-  const oldEvidence = collectEvidenceItems(existing);
-  const freshEvidence = collectEvidenceItems(fresh);
-  const mergedNotes = [];
-  const seenNotes = /* @__PURE__ */ new Set();
-  for (const note of [...oldEvidence.notes, ...freshEvidence.notes]) {
-    const key = note.replace(/\s+/gu, " ").trim();
-    if (key.length === 0) continue;
-    if (seenNotes.has(key)) continue;
-    seenNotes.add(key);
-    mergedNotes.push(note);
-  }
-  const mergedPaths = [];
-  const seenPaths = /* @__PURE__ */ new Set();
-  for (const p of [...oldEvidence.paths, ...freshEvidence.paths]) {
-    const key = p.trim();
-    if (key.length === 0) continue;
-    if (seenPaths.has(key)) continue;
-    seenPaths.add(key);
-    mergedPaths.push(key);
-  }
-  const pathLines = mergedPaths.length === 0 ? "_(no recent paths reported)_" : mergedPaths.map((p) => `- ${p}`).join("\n");
-  const noteLines = mergedNotes.length === 0 ? "_(no notes recorded)_" : mergedNotes.map((n) => `- ${n}`).join("\n");
-  const evidenceBody = [
-    "Recent paths:",
-    "",
-    pathLines,
-    "",
-    "Notes:",
-    "",
-    noteLines
-  ].join("\n");
-  return `${freshHead}
-## Evidence
 
-${evidenceBody}
-`;
+// src/services/cross-store-recall.ts
+var readSetWalkCache = /* @__PURE__ */ new Map();
+var readSetWalkCount = 0;
+function readSetWalkCacheKey(projectRoot) {
+  return `${projectRoot}\0${process.env.FABRIC_HOME ?? ""}`;
 }
-function splitAtEvidence(content) {
-  const tail = content.endsWith("\n") ? content : `${content}
-`;
-  const match = /^([\s\S]*?)(\n## Evidence(?:\s*\(call \d+\))?\s*\n)/u.exec(tail);
-  if (match === null) return null;
-  return { head: match[1] ?? "" };
+async function readSetFingerprint(refs) {
+  const parts = await Promise.all(
+    refs.map(async (ref) => {
+      try {
+        const fileStat = await stat(ref.file);
+        return `${ref.store_uuid}|${ref.alias}|${ref.file}|${fileStat.size}|${fileStat.mtimeMs}`;
+      } catch {
+        return `${ref.store_uuid}|${ref.alias}|${ref.file}|missing`;
+      }
+    })
+  );
+  return parts.sort().join("\n");
 }
-function collectEvidenceItems(content) {
-  const notes = [];
-  const paths = [];
-  const evidenceBlockRe = /\n## Evidence(?:\s*\(call \d+\))?\s*\n([\s\S]*?)(?=\n## |$)/gu;
-  let m;
-  while ((m = evidenceBlockRe.exec(`${content}
-`)) !== null) {
-    const block = m[1] ?? "";
-    const pathSection = /Recent paths:\s*\n([\s\S]*?)(?:\n\s*Notes:|$)/u.exec(block);
-    if (pathSection !== null) {
-      for (const rawLine of (pathSection[1] ?? "").split(/\r?\n/u)) {
-        const t = rawLine.trim();
-        if (t.startsWith("- ")) {
-          paths.push(t.slice(2).trim());
+var SEMANTIC_SCOPE_LINE = /^semantic_scope:\s*"?([^"\n]+?)"?\s*$/mu;
+function readSemanticScope(source, layer) {
+  const match = SEMANTIC_SCOPE_LINE.exec(source);
+  return match?.[1] ?? layer;
+}
+function filterByActiveProject(entries, activeProject) {
+  if (activeProject === void 0 || activeProject.length === 0) {
+    return entries;
+  }
+  const current = `project:${activeProject}`;
+  return entries.filter(
+    (e) => scopeRoot(e.semanticScope) !== "project" || e.semanticScope === current
+  );
+}
+function activeProjectOf(projectRoot) {
+  const ap = loadProjectConfig2(projectRoot)?.active_project;
+  return ap !== void 0 && ap.length > 0 ? ap : void 0;
+}
+async function resolveReadSetSnapshot(projectRoot) {
+  const resolveInput = buildStoreResolveInput2(projectRoot);
+  if (resolveInput === null) {
+    return null;
+  }
+  const readSet = createStoreResolver2().resolveReadSet(resolveInput);
+  if (readSet.stores.length === 0) {
+    return null;
+  }
+  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: join6(
+      globalRoot,
+      storeRelativePathForMount2(
+        resolveInput.mountedStores.find((s) => s.store_uuid === entry.store_uuid) ?? {
+          store_uuid: entry.store_uuid
         }
+      )
+    )
+  }));
+  return {
+    refs: await readKnowledgeAcrossStores(dirs),
+    personalUuids
+  };
+}
+async function walkReadSetStores(projectRoot) {
+  const snapshot = await resolveReadSetSnapshot(projectRoot);
+  if (snapshot === null) {
+    return [];
+  }
+  const key = readSetWalkCacheKey(projectRoot);
+  const fingerprint = await readSetFingerprint(snapshot.refs);
+  const cached = readSetWalkCache.get(key);
+  if (cached !== void 0 && cached.fingerprint === fingerprint) {
+    return cached.entries.slice();
+  }
+  const entries = await walkReadSetStoresUncached(snapshot);
+  readSetWalkCache.set(key, { fingerprint, entries });
+  return entries.slice();
+}
+async function walkReadSetStoresUncached(snapshot) {
+  readSetWalkCount += 1;
+  const entries = await Promise.all(snapshot.refs.map(async (ref) => {
+    let source;
+    try {
+      source = await readFile3(ref.file, "utf8");
+    } catch {
+      return null;
+    }
+    const stableId = deriveRuleIdentity(ref.file, source, void 0).stableId;
+    const layer = snapshot.personalUuids.has(ref.store_uuid) ? "personal" : "team";
+    return {
+      qualifiedId: `${ref.alias}:${stableId}`,
+      file: ref.file,
+      type: ref.type,
+      alias: ref.alias,
+      layer,
+      semanticScope: readSemanticScope(source, layer),
+      source
+    };
+  }));
+  return entries.filter((entry) => entry !== null);
+}
+async function buildCrossStoreRawItems(projectRoot) {
+  const items = [];
+  const activeProject = activeProjectOf(projectRoot);
+  for (const entry of filterByActiveProject(await walkReadSetStores(projectRoot), activeProject)) {
+    const baseDescription = extractRuleDescription(entry.source);
+    if (baseDescription === void 0) {
+      continue;
+    }
+    items.push({
+      stable_id: entry.qualifiedId,
+      description: {
+        ...baseDescription,
+        knowledge_layer: entry.layer,
+        semantic_scope: entry.semanticScope
       }
+    });
+  }
+  return items;
+}
+async function buildCrossStoreBodyIndex(projectRoot) {
+  const index = /* @__PURE__ */ new Map();
+  const activeProject = activeProjectOf(projectRoot);
+  for (const entry of filterByActiveProject(await walkReadSetStores(projectRoot), activeProject)) {
+    if (!index.has(entry.qualifiedId)) {
+      index.set(entry.qualifiedId, { file: entry.file, layer: entry.layer });
     }
-    const notesSection = /Notes:\s*\n([\s\S]*?)$/u.exec(block);
-    const noteBody = (notesSection !== null ? notesSection[1] : block) ?? "";
-    const bulletLines = [];
-    let prose = [];
-    for (const rawLine of noteBody.split(/\r?\n/u)) {
-      const t = rawLine.trim();
-      if (t.length === 0) continue;
-      if (t.startsWith("- ")) {
-        if (prose.length > 0) {
-          notes.push(prose.join(" ").trim());
-          prose = [];
+  }
+  return index;
+}
+var ALWAYS_ACTIVE_TYPES = /* @__PURE__ */ new Set(["guidelines", "models"]);
+async function buildKnowledgeCensus(projectRoot) {
+  const census = {
+    by_type: {},
+    by_layer: { team: 0, personal: 0, project: 0 },
+    broad_by_type: {},
+    narrow_total: 0,
+    dropped_other_project: 0,
+    total: 0
+  };
+  try {
+    const activeProject = activeProjectOf(projectRoot);
+    const all = await walkReadSetStores(projectRoot);
+    const kept = filterByActiveProject(all, activeProject);
+    census.dropped_other_project = all.length - kept.length;
+    for (const entry of kept) {
+      const desc = extractRuleDescription(entry.source);
+      const type = desc?.knowledge_type;
+      const isNarrow = desc?.relevance_scope === "narrow";
+      if (typeof type === "string") {
+        census.by_type[type] = (census.by_type[type] ?? 0) + 1;
+        if (!isNarrow) {
+          census.broad_by_type[type] = (census.broad_by_type[type] ?? 0) + 1;
         }
-        bulletLines.push(t.slice(2).trim());
+      }
+      if (isNarrow) census.narrow_total += 1;
+      if (scopeRoot(entry.semanticScope) === "project") {
+        census.by_layer.project += 1;
       } else {
-        prose.push(t);
+        census.by_layer[entry.layer] += 1;
       }
+      census.total += 1;
     }
-    if (prose.length > 0) notes.push(prose.join(" ").trim());
-    for (const n of bulletLines) notes.push(n);
+  } catch {
   }
-  return { notes, paths };
+  return census;
 }
-function readFrontmatterKey(content, key) {
-  const match = /^---\n([\s\S]*?)\n---/u.exec(content);
-  if (match === null) {
-    return void 0;
-  }
-  const block = match[1];
-  if (block === void 0) {
-    return void 0;
+async function buildAlwaysActiveBodies(projectRoot) {
+  const out = [];
+  try {
+    const activeProject = activeProjectOf(projectRoot);
+    for (const entry of filterByActiveProject(
+      await walkReadSetStores(projectRoot),
+      activeProject
+    )) {
+      const desc = extractRuleDescription(entry.source);
+      if (desc === void 0) continue;
+      const type = desc.knowledge_type;
+      if (typeof type !== "string" || !ALWAYS_ACTIVE_TYPES.has(type)) continue;
+      if (desc.relevance_scope === "narrow") continue;
+      out.push({
+        stable_id: entry.qualifiedId,
+        type,
+        layer: entry.layer,
+        summary: typeof desc.summary === "string" ? desc.summary : "",
+        body: extractBody(entry.source)
+      });
+    }
+  } catch {
+    return [];
   }
-  for (const rawLine of block.split(/\r?\n/u)) {
-    const line = rawLine.trim();
-    const sep5 = line.indexOf(":");
-    if (sep5 === -1) continue;
-    const k = line.slice(0, sep5).trim();
-    if (k === key) {
-      return line.slice(sep5 + 1).trim();
+  return out;
+}
+async function computeReadSetRevision(projectRoot) {
+  const revisionSource = (await walkReadSetStores(projectRoot)).filter((entry) => !entry.file.includes("/knowledge/pending/")).map((entry) => `${entry.qualifiedId}|${sha256(entry.source)}`).sort().join("\n");
+  return sha256(revisionSource);
+}
+async function collectStoreCanonicalEntries(projectRoot) {
+  const out = [];
+  for (const entry of await walkReadSetStores(projectRoot)) {
+    if (entry.file.includes("/knowledge/pending/")) {
+      continue;
+    }
+    const description = extractRuleDescription(entry.source);
+    if (description === void 0) {
+      continue;
     }
+    out.push({
+      stableId: entry.qualifiedId.slice(entry.alias.length + 1),
+      qualifiedId: entry.qualifiedId,
+      file: entry.file,
+      type: entry.type,
+      layer: entry.layer,
+      body: entry.source,
+      description
+    });
   }
-  return void 0;
+  return out;
 }
-async function emitEventBestEffort(projectRoot, event) {
-  try {
-    await appendEventLedgerEvent(projectRoot, event);
-  } catch {
+async function collectStoreKnowledgeSummaries(projectRoot) {
+  const out = [];
+  for (const entry of await 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/tools/extract-knowledge.ts
-function registerExtractKnowledge(server, tracker) {
-  server.registerTool(
-    "fab_extract_knowledge",
-    {
-      description: "Persist a proposed pending knowledge entry into the resolved write-target store under knowledge/pending/<type>/<slug>.md. Idempotent on (source_sessions[0], type, slug); repeat calls append evidence rather than overwrite. Skill-side tool \u2014 invoked at session-stop.",
-      inputSchema: FabExtractKnowledgeInputShape,
-      outputSchema: FabExtractKnowledgeOutputSchema.shape,
-      annotations: fabExtractKnowledgeAnnotations
-    },
-    async (input) => {
-      const requestId = randomUUID2();
-      tracker?.enter(requestId);
-      try {
-        const gateResult = await awaitFirstReconcileGate();
-        const gateWarn = gateWarning(gateResult);
-        const validated = FabExtractKnowledgeInputSchema.parse(input);
-        const projectRoot = resolveProjectRoot();
-        const result = await extractKnowledge(projectRoot, validated);
-        const response = { ...result };
-        if (gateWarn) {
-          response.warnings = [gateWarn];
-        }
-        const payloadLimits = readPayloadLimits(projectRoot);
-        const serialized = JSON.stringify(response);
-        const guardResult = enforcePayloadLimit(serialized, payloadLimits);
-        response.warnings = appendPayloadWarning(
-          response.warnings,
-          guardResult,
-          "fab_extract_knowledge produced an unexpectedly large response \u2014 extract from a smaller span of text."
-        );
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }],
-          structuredContent: response
-        };
-      } finally {
-        tracker?.exit(requestId);
+// src/services/bm25.ts
+import { tokenize } from "@fenglimg/fabric-shared";
+var K1 = 1.5;
+var BM25_FIELDS = ["title", "summary", "tags", "body"];
+var FIELD_CONFIGS = {
+  title: { boost: 3, b: 0.3 },
+  tags: { boost: 2, b: 0 },
+  summary: { boost: 1.5, b: 0.75 },
+  body: { boost: 1, b: 0.75 }
+};
+function emptyFieldRecord(make) {
+  return { title: make(), summary: make(), tags: make(), body: make() };
+}
+function buildBm25Model(docs) {
+  const totalDocs = docs.length;
+  const documentFrequency = /* @__PURE__ */ new Map();
+  const perDoc = /* @__PURE__ */ new Map();
+  const totalFieldLength = emptyFieldRecord(() => 0);
+  for (const doc of docs) {
+    const fieldTermFreq = emptyFieldRecord(() => /* @__PURE__ */ new Map());
+    const fieldLength = emptyFieldRecord(() => 0);
+    const docTerms = /* @__PURE__ */ new Set();
+    for (const field of BM25_FIELDS) {
+      const tokens = doc.fields[field] ?? [];
+      fieldLength[field] = tokens.length;
+      totalFieldLength[field] += tokens.length;
+      const tf = fieldTermFreq[field];
+      for (const term of tokens) {
+        tf.set(term, (tf.get(term) ?? 0) + 1);
+        docTerms.add(term);
       }
     }
-  );
+    for (const term of docTerms) {
+      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+    }
+    perDoc.set(doc.id, { fieldTermFreq, fieldLength });
+  }
+  const avgFieldLength = emptyFieldRecord(() => 0);
+  for (const field of BM25_FIELDS) {
+    avgFieldLength[field] = totalDocs > 0 ? totalFieldLength[field] / totalDocs : 0;
+  }
+  const idf = (term) => {
+    const n = documentFrequency.get(term) ?? 0;
+    return Math.log(1 + (totalDocs - n + 0.5) / (n + 0.5));
+  };
+  return {
+    scoreDoc(id, queryTerms) {
+      const data = perDoc.get(id);
+      if (data === void 0 || queryTerms.length === 0) {
+        return 0;
+      }
+      let score = 0;
+      const scoredTerms = /* @__PURE__ */ new Set();
+      for (const term of queryTerms) {
+        if (scoredTerms.has(term)) {
+          continue;
+        }
+        scoredTerms.add(term);
+        let pseudoTermFreq = 0;
+        for (const field of BM25_FIELDS) {
+          const config = FIELD_CONFIGS[field];
+          if (config.boost === 0) {
+            continue;
+          }
+          const freq = data.fieldTermFreq[field].get(term);
+          if (freq === void 0 || freq === 0) {
+            continue;
+          }
+          const avg = avgFieldLength[field] || 1;
+          const norm = 1 - config.b + config.b * (data.fieldLength[field] / avg);
+          pseudoTermFreq += config.boost * (freq / (norm || 1));
+        }
+        if (pseudoTermFreq === 0) {
+          continue;
+        }
+        score += idf(term) * (pseudoTermFreq * (K1 + 1) / (pseudoTermFreq + K1));
+      }
+      return score;
+    }
+  };
 }
-
-// src/tools/recall.ts
-import { randomUUID as randomUUID3 } from "crypto";
-import {
-  recallAnnotations,
-  recallInputSchema,
-  recallOutputSchema
-} from "@fenglimg/fabric-shared/schemas/api-contracts";
-import { enforcePayloadLimit as enforcePayloadLimit2 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
-
-// src/services/plan-context.ts
-import {
-  buildStoreResolveInput as buildStoreResolveInput3,
-  createStoreResolver as createStoreResolver3,
-  resolveCandidates,
-  tokenize as tokenize2
-} from "@fenglimg/fabric-shared";
-import {
-  trimToPayloadBudget
-} from "@fenglimg/fabric-shared/node/mcp-payload-guard";
-
-// src/services/get-knowledge.ts
-function normalizeKnowledgePath(value) {
-  return value.replaceAll("\\", "/");
+function buildQueryTerms(text) {
+  return tokenize(text);
 }
 
-// src/services/cross-store-recall.ts
-import { readFile as readFile4, stat } from "fs/promises";
-import { join as join7 } from "path";
-import {
-  buildStoreResolveInput as buildStoreResolveInput2,
-  createStoreResolver as createStoreResolver2,
-  loadProjectConfig as loadProjectConfig2,
-  readKnowledgeAcrossStores,
-  resolveGlobalRoot as resolveGlobalRoot2,
-  scopeRoot,
-  storeRelativePathForMount as storeRelativePathForMount2
-} from "@fenglimg/fabric-shared";
-
-// src/services/knowledge-meta-builder.ts
-import {
-  deriveAgentsMetaStableId,
-  isKnowledgeStableId,
-  KnowledgeTypeSchema,
-  LayerSchema,
-  MaturitySchema,
-  parseKnowledgeId,
-  StableIdSchema
-} from "@fenglimg/fabric-shared";
-function toAgentsCompatiblePath(contentRef) {
-  return contentRef.replace(/^~\/\.fabric\/knowledge\//u, ".fabric/agents/").replace(/^\.fabric\/knowledge\//u, ".fabric/agents/");
+// src/services/conflict-lint.ts
+function buildSimilarityModel(docs) {
+  const tokenized = docs.map((d) => ({ id: d.id, tokens: buildQueryTerms(d.text) }));
+  const tokensById = new Map(tokenized.map((d) => [d.id, d.tokens]));
+  const model = buildBm25Model(
+    tokenized.map((d) => ({ id: d.id, fields: { title: [], summary: [], tags: [], body: d.tokens } }))
+  );
+  return { model, tokensById };
 }
-function deriveRuleIdentity(file, source, existing) {
-  const declaredKnowledgeId = extractDeclaredKnowledgeId(source);
-  if (declaredKnowledgeId !== void 0) {
-    return {
-      stableId: declaredKnowledgeId,
-      identitySource: "declared"
-    };
-  }
-  if (existing?.stable_id !== void 0 && isKnowledgeStableId(existing.stable_id)) {
-    return {
-      stableId: existing.stable_id,
-      identitySource: "declared"
-    };
-  }
-  const declaredStableId = extractDeclaredStableId(source);
-  const derivedStableId = deriveAgentsMetaStableId(toAgentsCompatiblePath(file));
-  if (declaredStableId !== void 0) {
-    return {
-      stableId: declaredStableId,
-      identitySource: "declared"
-    };
+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);
   }
-  if (existing?.identity_source === "declared" && existing.stable_id !== void 0 && existing.stable_id !== derivedStableId) {
-    return {
-      stableId: existing.stable_id,
-      identitySource: "declared"
-    };
+  const pairs = [];
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const { model, tokensById } = buildSimilarityModel(
+      group.map((e) => ({ id: e.stable_id, text: e.text }))
+    );
+    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"
+        });
+      }
+    }
   }
-  return {
-    stableId: derivedStableId,
-    identitySource: "derived"
-  };
-}
-function extractDeclaredStableId(source) {
-  const match = /^(?:\uFEFF)?(?:---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$))?<!--\s*fab:rule-id\s+([A-Za-z0-9][A-Za-z0-9/_-]*)\s*-->\s*(?:\r?\n|$)/u.exec(source);
-  return match?.[1];
+  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;
 }
-function extractDeclaredKnowledgeId(source) {
-  const frontmatter = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/u.exec(source);
-  if (frontmatter === null) {
-    return void 0;
+async function lintConflicts(entries, opts = {}) {
+  const candidates = findConflictCandidates(entries, { threshold: opts.threshold });
+  if (opts.judge === void 0 || candidates.length === 0) {
+    return candidates;
   }
-  const idMatch = /^id:\s*(.+?)\s*$/mu.exec(frontmatter[1]);
-  if (idMatch === null) {
-    return void 0;
+  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);
+    }
   }
-  const candidate = idMatch[1].replace(/^["'](.*)["']$/u, "$1").trim();
-  return isKnowledgeStableId(candidate) ? candidate : void 0;
+  return judged;
 }
-function extractRuleDescription(source) {
-  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/u.exec(source);
-  const description = frontmatter === null ? void 0 : extractDescriptionFromFrontmatter(frontmatter[1]);
-  if (description !== void 0) {
-    return description;
+
+// src/services/archive-dedup-gate.ts
+var DEDUP_NEAR_DUPLICATE_THRESHOLD = 0.85;
+var DEDUP_CONFLICT_THRESHOLD = 0.5;
+var CANDIDATE_ID = "__candidate__";
+function classifyArchiveCandidate(candidate, corpus, opts = {}) {
+  const nearDuplicate = opts.nearDuplicateThreshold ?? DEDUP_NEAR_DUPLICATE_THRESHOLD;
+  const conflict = opts.conflictThreshold ?? DEDUP_CONFLICT_THRESHOLD;
+  const bucket = corpus.filter(
+    (e) => e.knowledge_type === candidate.knowledge_type && e.layer === candidate.layer
+  );
+  if (bucket.length === 0) {
+    return { verdict: "unique", matches: [] };
   }
-  const heading = /^#\s+(.+?)\s*$/mu.exec(source);
-  const summary = heading?.[1]?.trim();
-  const knowledge = frontmatter !== null ? extractKnowledgeFieldsFromFrontmatter(frontmatter[1]) : void 0;
-  const isStructurallyAKnowledgeEntry = summary !== void 0 && summary.length > 0 ? true : knowledge !== void 0 && (knowledge.id !== void 0 || knowledge.knowledge_type !== void 0 || knowledge.tags !== void 0 && knowledge.tags.length > 0);
-  if (!isStructurallyAKnowledgeEntry) {
+  const { model, tokensById } = buildSimilarityModel([
+    { id: CANDIDATE_ID, text: candidate.text },
+    ...bucket.map((e) => ({ id: e.stable_id, text: e.text }))
+  ]);
+  const candidateTokens = tokensById.get(CANDIDATE_ID) ?? [];
+  const matches = bucket.map((e) => ({
+    stable_id: e.stable_id,
+    similarity: pairSimilarity(
+      model,
+      { id: CANDIDATE_ID, tokens: candidateTokens },
+      { id: e.stable_id, tokens: tokensById.get(e.stable_id) ?? [] }
+    )
+  })).filter((m) => m.similarity >= conflict).sort((a, b) => b.similarity - a.similarity || a.stable_id.localeCompare(b.stable_id));
+  const top = matches[0]?.similarity ?? 0;
+  const verdict = top >= nearDuplicate ? "near-duplicate" : top >= conflict ? "conflict" : "unique";
+  return { verdict, matches };
+}
+function formatDedupMarker(result) {
+  if (result.verdict === "unique" || result.matches.length === 0) {
     return void 0;
   }
-  const synthesizedSummary = summary !== void 0 && summary.length > 0 ? summary : knowledge?.id ?? (knowledge?.tags !== void 0 && knowledge.tags.length > 0 ? `(unnamed; tags: ${knowledge.tags.join(", ")})` : "(unnamed knowledge entry)");
-  return {
-    summary: synthesizedSummary,
-    intent_clues: [],
-    tech_stack: [],
-    impact: [],
-    must_read_if: synthesizedSummary,
-    // v2.0-rc.22: when frontmatter is present, merge its knowledge fields;
-    // when fully absent (no `---` block), all knowledge fields stay
-    // undefined, matching the original heading-only fallback contract.
-    id: knowledge?.id,
-    knowledge_type: knowledge?.knowledge_type,
-    maturity: knowledge?.maturity,
-    knowledge_layer: knowledge?.knowledge_layer,
-    layer_reason: knowledge?.layer_reason,
-    created_at: knowledge?.created_at,
-    tags: knowledge?.tags,
-    // v2.0-rc.5 (C1): default-safe values when there is no frontmatter at all;
-    // when frontmatter exists, honor its declared values (extractKnowledge
-    // FieldsFromFrontmatter already applies the broad-default for missing
-    // or malformed scopes).
-    relevance_scope: knowledge?.relevance_scope ?? "broad",
-    relevance_paths: knowledge?.relevance_paths ?? [],
-    // v2.2 H2-related (W1-T7): graph edges, undefined when absent.
-    related: knowledge?.related
-  };
+  const top = result.matches[0];
+  return `${result.verdict} of ${top.stable_id} (${top.similarity.toFixed(2)})`;
 }
-function extractDescriptionFromFrontmatter(frontmatter) {
-  const summary = extractScalar(frontmatter, "summary") ?? extractScalar(frontmatter, "description");
-  if (summary === void 0) {
-    return void 0;
-  }
-  const knowledge = extractKnowledgeFieldsFromFrontmatter(frontmatter);
-  return {
-    summary,
-    intent_clues: extractInlineArray(frontmatter, "intent_clues"),
-    tech_stack: extractInlineArray(frontmatter, "tech_stack"),
-    impact: extractInlineArray(frontmatter, "impact"),
-    must_read_if: extractScalar(frontmatter, "must_read_if") ?? summary,
-    entities: extractInlineArray(frontmatter, "entities"),
-    id: knowledge.id,
-    knowledge_type: knowledge.knowledge_type,
-    maturity: knowledge.maturity,
-    knowledge_layer: knowledge.knowledge_layer,
-    layer_reason: knowledge.layer_reason,
-    created_at: knowledge.created_at,
-    tags: knowledge.tags,
-    relevance_scope: knowledge.relevance_scope,
-    relevance_paths: knowledge.relevance_paths,
-    // v2.2 H2-related (W1-T7): graph edges parsed from frontmatter.
-    related: knowledge.related
-  };
-}
-function isForbiddenCrossLayerEdge(sourceLayer, targetId) {
-  if (sourceLayer !== "team") {
-    return false;
+
+// src/services/extract-knowledge.ts
+var SLUG_MAX_LENGTH = 40;
+var INJECTION_PATTERNS = [
+  {
+    name: "ignore-prior-instructions",
+    pattern: /\b(?:ignore|forget|disregard)\s+(?:all\s+)?(?:previous|prior|above|earlier)\s+(?:instructions?|messages?|prompts?|rules?)\b/giu
+  },
+  {
+    name: "forget-your-role",
+    pattern: /\b(?:forget|disregard|ignore)\s+(?:your|the)\s+(?:role|identity|system\s+prompt)\b/giu
+  },
+  {
+    name: "you-are-now",
+    pattern: /\byou\s+are\s+now\s+(?:a|an)\s+\w+\s+(?:assistant|agent|model|bot|persona)\b/giu
+  },
+  {
+    name: "rm-rf-root",
+    pattern: /\brm\s+-rf?\s+(?:--no-preserve-root\s+)?[/~][^\s`'")>}]*?\s*(?:\/[*]?|;|$|\n|\|)/giu
+  },
+  {
+    name: "shell-eval-curl",
+    pattern: /\b(?:eval|sh|bash|zsh)\s+(?:-\w+\s+)?["'`]?\$\(\s*curl\s+[^)]+\)/giu
+  },
+  {
+    name: "chatml-envelope",
+    pattern: /<\|(?:im_start|im_end|system|user|assistant|endoftext|fim_prefix|fim_suffix|fim_middle)\|>/giu
+  },
+  {
+    name: "claude-envelope",
+    pattern: /\b(?:Human:|Assistant:)\s*<.*?>/giu
   }
-  const decoded = parseKnowledgeId(localKnowledgeIdFromReference(targetId));
-  if (decoded === null) {
-    return false;
+];
+var INJECTION_REDACTION_MARKER = "[REDACTED: prompt-injection pattern stripped by fab_propose \u2014 NEW-31]";
+function sanitizeInjectionPatterns(input) {
+  let sanitized = input;
+  const redactions = [];
+  for (const { name, pattern } of INJECTION_PATTERNS) {
+    const matches = sanitized.match(pattern);
+    if (matches === null || matches.length === 0) continue;
+    redactions.push({ name, matches: matches.length });
+    sanitized = sanitized.replace(pattern, INJECTION_REDACTION_MARKER);
   }
-  return decoded.layer === "personal";
+  return { sanitized, redactions };
 }
-function localKnowledgeIdFromReference(ref) {
-  const direct = parseKnowledgeId(ref);
-  if (direct !== null) {
-    return ref;
+function sanitizeInjectionFields(fields) {
+  const out = { ...fields };
+  const allRedactions = [];
+  for (const [key, value] of Object.entries(fields)) {
+    if (typeof value === "string") {
+      const { sanitized, redactions } = sanitizeInjectionPatterns(value);
+      out[key] = sanitized;
+      for (const r of redactions) {
+        allRedactions.push({ field: key, ...r });
+      }
+    } else if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+      const cleaned = [];
+      for (const entry of value) {
+        const { sanitized, redactions } = sanitizeInjectionPatterns(entry);
+        cleaned.push(sanitized);
+        for (const r of redactions) {
+          allRedactions.push({ field: key, ...r });
+        }
+      }
+      out[key] = cleaned;
+    }
   }
-  const tail = ref.split(":").at(-1);
-  return tail ?? ref;
+  return { sanitized: out, allRedactions };
 }
-function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
-  const rawId = extractScalar(frontmatter, "id");
-  const rawType = extractScalar(frontmatter, "type");
-  const rawMaturity = extractScalar(frontmatter, "maturity");
-  const rawLayer = extractScalar(frontmatter, "layer");
-  const rawLayerReason = extractScalar(frontmatter, "layer_reason");
-  const rawCreatedAt = extractScalar(frontmatter, "created_at");
-  let id;
-  if (rawId !== void 0) {
-    const parsed = StableIdSchema.safeParse(rawId);
-    if (parsed.success) {
-      id = parsed.data;
-    } else {
-      process.stderr.write(`[fabric] frontmatter: invalid knowledge id format ${JSON.stringify(rawId)}; skipping
-`);
+function redactPiiFields(fields) {
+  const out = { ...fields };
+  const redactedFields = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(fields)) {
+    if (typeof value === "string") {
+      const cleaned = redactPii(value);
+      out[key] = cleaned;
+      if (cleaned !== value) redactedFields.add(key);
+    } else if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+      const cleaned = value.map((entry) => redactPii(entry));
+      out[key] = cleaned;
+      if (cleaned.some((entry, index) => entry !== value[index])) {
+        redactedFields.add(key);
+      }
     }
   }
-  const SINGULAR_TO_PLURAL = {
-    model: "models",
-    decision: "decisions",
-    guideline: "guidelines",
-    pitfall: "pitfalls",
-    process: "processes"
+  return { redacted: out, redactedFields: [...redactedFields].sort() };
+}
+function pendingBase(layer, projectRoot, semanticScope) {
+  return resolveStorePendingBase(layer, projectRoot, semanticScope);
+}
+function toPosixPath(path) {
+  return path.replace(/\\/gu, "/");
+}
+async function extractKnowledge(projectRoot, input) {
+  const sanitizedInputFields = sanitizeInjectionFields({
+    slug: input.slug ?? "",
+    user_messages_summary: input.user_messages_summary ?? "",
+    session_context: input.session_context ?? "",
+    must_read_if: input.must_read_if ?? "",
+    intent_clues: input.intent_clues ?? []
+  });
+  input = {
+    ...input,
+    slug: sanitizedInputFields.sanitized.slug,
+    user_messages_summary: sanitizedInputFields.sanitized.user_messages_summary || void 0,
+    session_context: sanitizedInputFields.sanitized.session_context || void 0,
+    must_read_if: sanitizedInputFields.sanitized.must_read_if || void 0,
+    intent_clues: sanitizedInputFields.sanitized.intent_clues.length > 0 ? sanitizedInputFields.sanitized.intent_clues : void 0
   };
-  let knowledge_type;
-  if (rawType !== void 0) {
-    const normalized = SINGULAR_TO_PLURAL[rawType] ?? rawType;
-    const parsed = KnowledgeTypeSchema.safeParse(normalized);
-    if (parsed.success) {
-      knowledge_type = parsed.data;
-    } else {
-      process.stderr.write(`[fabric] frontmatter: unknown knowledge type ${JSON.stringify(rawType)}; skipping
-`);
-    }
+  if (sanitizedInputFields.allRedactions.length > 0) {
+    const summary2 = sanitizedInputFields.allRedactions.map((r) => `${r.field}:${r.name}x${r.matches}`).join(",");
+    const primarySessionForLog = (input.source_sessions ?? [])[0] ?? "";
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_archive_attempted",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      correlation_id: primarySessionForLog,
+      session_id: primarySessionForLog,
+      reason: `extract_knowledge:injection-redacted:${summary2}`
+    });
   }
-  let maturity;
-  if (rawMaturity !== void 0) {
-    const parsed = MaturitySchema.safeParse(rawMaturity);
-    if (parsed.success) {
-      maturity = parsed.data;
-    } else {
-      process.stderr.write(`[fabric] frontmatter: unknown maturity ${JSON.stringify(rawMaturity)}; skipping
-`);
-    }
+  const piiRedactedInputFields = redactPiiFields({
+    slug: input.slug ?? "",
+    user_messages_summary: input.user_messages_summary ?? "",
+    session_context: input.session_context ?? "",
+    must_read_if: input.must_read_if ?? "",
+    intent_clues: input.intent_clues ?? [],
+    tags: input.tags ?? [],
+    evidence_paths: input.evidence_paths ?? []
+  });
+  input = {
+    ...input,
+    slug: piiRedactedInputFields.redacted.slug,
+    user_messages_summary: piiRedactedInputFields.redacted.user_messages_summary || void 0,
+    session_context: piiRedactedInputFields.redacted.session_context || void 0,
+    must_read_if: piiRedactedInputFields.redacted.must_read_if || void 0,
+    intent_clues: piiRedactedInputFields.redacted.intent_clues.length > 0 ? piiRedactedInputFields.redacted.intent_clues : void 0,
+    tags: piiRedactedInputFields.redacted.tags.length > 0 ? piiRedactedInputFields.redacted.tags : void 0,
+    evidence_paths: piiRedactedInputFields.redacted.evidence_paths.length > 0 ? piiRedactedInputFields.redacted.evidence_paths : void 0
+  };
+  if (piiRedactedInputFields.redactedFields.length > 0) {
+    const primarySessionForLog = (input.source_sessions ?? [])[0] ?? "";
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_archive_attempted",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      correlation_id: primarySessionForLog,
+      session_id: primarySessionForLog,
+      reason: `extract_knowledge:pii-redacted:${piiRedactedInputFields.redactedFields.join(",")}`
+    });
   }
-  let knowledge_layer;
-  if (rawLayer !== void 0) {
-    const parsed = LayerSchema.safeParse(rawLayer);
-    if (parsed.success) {
-      knowledge_layer = parsed.data;
-    } else {
-      process.stderr.write(`[fabric] frontmatter: unknown layer ${JSON.stringify(rawLayer)}; skipping
-`);
-    }
+  const sanitizedSlug = sanitizeSlug(input.slug);
+  const sourceSessions = input.source_sessions ?? [];
+  const primarySession = sourceSessions[0] ?? "";
+  const idempotencyKey = sha256(
+    JSON.stringify({
+      source_session: primarySession,
+      type: input.type,
+      slug: sanitizedSlug
+    })
+  );
+  const summary = input.user_messages_summary ?? "";
+  const summaryTrimmed = summary.trim();
+  const summaryIsEmpty = summaryTrimmed.length === 0;
+  const slugIsEmpty = sanitizedSlug.length === 0;
+  const summaryTooShort = !summaryIsEmpty && summaryTrimmed.length < 15;
+  const summaryEqualsSlug = !summaryIsEmpty && summaryTrimmed.toLowerCase() === sanitizedSlug.toLowerCase();
+  const summaryLooksLikeStableId = !summaryIsEmpty && /^K[TP]-[A-Z]{3}-\d{4}$/.test(summaryTrimmed);
+  const summaryIsOpaque = summaryTooShort || summaryEqualsSlug || summaryLooksLikeStableId;
+  if (summaryIsEmpty || slugIsEmpty || summaryIsOpaque) {
+    const reason = summaryIsEmpty ? "empty_summary" : slugIsEmpty ? "empty_slug" : summaryTooShort ? "summary_too_short" : summaryEqualsSlug ? "summary_equals_slug" : "summary_looks_like_stable_id";
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_archive_attempted",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      correlation_id: primarySession,
+      session_id: primarySession,
+      reason: `extract_knowledge:${sanitizedSlug || input.slug}:${reason}`
+    });
+    return {
+      pending_path: "",
+      idempotency_key: idempotencyKey
+    };
   }
-  let created_at;
-  if (rawCreatedAt !== void 0) {
-    if (!Number.isNaN(Date.parse(rawCreatedAt))) {
-      created_at = rawCreatedAt;
-    } else {
-      process.stderr.write(`[fabric] frontmatter: malformed created_at ${JSON.stringify(rawCreatedAt)}; skipping
-`);
-    }
+  const secretScanTarget = [
+    input.slug ?? "",
+    input.user_messages_summary ?? "",
+    input.session_context ?? "",
+    input.must_read_if ?? "",
+    ...input.intent_clues ?? [],
+    ...input.tags ?? [],
+    ...input.evidence_paths ?? []
+  ].join("\n");
+  if (hasSecrets(secretScanTarget)) {
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_archive_attempted",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      correlation_id: primarySession,
+      session_id: primarySession,
+      reason: `extract_knowledge:${sanitizedSlug || input.slug}:secret_detected`
+    });
+    return {
+      pending_path: "",
+      idempotency_key: idempotencyKey
+    };
   }
-  if (id !== void 0 && knowledge_layer !== void 0) {
-    const decoded = parseKnowledgeId(id);
-    if (decoded !== null && decoded.layer !== knowledge_layer) {
-      process.stderr.write(
-        `[fabric] frontmatter: id ${id} encodes layer ${decoded.layer} but layer field says ${knowledge_layer}; dropping both
-`
-      );
-      id = void 0;
-      knowledge_layer = void 0;
-    }
+  const semanticScope = input.audience;
+  const scopeIsPersonal = semanticScope !== void 0 && isPersonalScope(semanticScope);
+  const layer = scopeIsPersonal ? "personal" : "team";
+  let relevancePaths = input.paths;
+  let relevanceScope = relevancePaths === void 0 ? void 0 : relevancePaths.length > 0 ? "narrow" : "broad";
+  const shouldAutoDegrade = layer === "personal" && relevanceScope === "narrow";
+  if (shouldAutoDegrade) {
+    relevanceScope = "broad";
+    relevancePaths = [];
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_scope_degraded",
+      stable_id: `pending:${idempotencyKey}`,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      from_scope: "narrow",
+      to_scope: "broad",
+      reason: "personal-implies-broad"
+    });
   }
-  const tags = extractInlineArray(frontmatter, "tags");
-  const rawRelevanceScope = extractScalar(frontmatter, "relevance_scope");
-  const relevance_scope = rawRelevanceScope === "narrow" || rawRelevanceScope === "broad" ? rawRelevanceScope : "broad";
-  const relevance_paths = extractInlineArray(frontmatter, "relevance_paths");
-  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;
+  const baseDir = pendingBase(layer, projectRoot, semanticScope);
+  const { absolutePath, sanitizedSlug: chosenSlug, idempotencyKey: chosenKey } = await resolveDisambiguatedSlugPath({
+    baseDir,
+    type: input.type,
+    slug: sanitizedSlug,
+    primarySession,
+    baseIdempotencyKey: idempotencyKey
+  });
+  const reportedPath = toPosixPath(absolutePath);
+  const effectiveSanitizedSlug = chosenSlug;
+  const effectiveIdempotencyKey = chosenKey;
+  const writeScopeMeta = resolveWriteScopeMeta(layer, projectRoot, semanticScope);
+  await ensureParentDirectory(absolutePath);
+  if (existsSync3(absolutePath)) {
+    const existing = await readFile4(absolutePath, "utf8");
+    const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
+    if (existingKey === effectiveIdempotencyKey) {
+      const fresh2 = renderFreshEntry({
+        type: input.type,
+        sourceSessions,
+        idempotencyKey: effectiveIdempotencyKey,
+        summary,
+        recentPaths: input.recent_paths,
+        layer,
+        semanticScope: writeScopeMeta.semantic_scope,
+        visibilityStore: writeScopeMeta.visibility_store,
+        proposedReason: input.proposed_reason,
+        sessionContext: input.session_context,
+        relevanceScope,
+        relevancePaths,
+        intentClues: input.intent_clues,
+        techStack: input.tech_stack,
+        impact: input.impact,
+        mustReadIf: input.must_read_if,
+        onboardSlot: input.onboard_slot,
+        // v2.0.0-rc.37 NEW-37: pass-through topic tags.
+        tags: input.tags,
+        // v2.0.0-rc.37 NEW-7: pass-through evidence_paths to frontmatter.
+        evidencePaths: input.evidence_paths
+      });
+      const augmented = mergeEvidenceNotes(existing, fresh2);
+      await atomicWriteText(absolutePath, augmented);
+      await emitEventBestEffort(projectRoot, {
+        event_type: "knowledge_proposed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        correlation_id: primarySession,
+        session_id: primarySession,
+        reason: `extract_knowledge:${effectiveSanitizedSlug}`
+      });
+      return {
+        pending_path: reportedPath,
+        idempotency_key: effectiveIdempotencyKey
+      };
     }
-    return true;
+    throw new Error(
+      `slug collision (unreachable after rc.37 NEW-6): pending file ${reportedPath} already exists with key ${existingKey ?? "<missing>"} != ${effectiveIdempotencyKey}`
+    );
+  }
+  const dedupMarker = await computeDedupMarker(projectRoot, {
+    text: [
+      summary,
+      input.must_read_if ?? "",
+      ...input.intent_clues ?? [],
+      ...input.impact ?? [],
+      ...input.tags ?? []
+    ].join(" "),
+    knowledge_type: input.type,
+    layer
+  });
+  const fresh = renderFreshEntry({
+    type: input.type,
+    sourceSessions,
+    idempotencyKey: effectiveIdempotencyKey,
+    summary,
+    recentPaths: input.recent_paths,
+    layer,
+    semanticScope: writeScopeMeta.semantic_scope,
+    visibilityStore: writeScopeMeta.visibility_store,
+    proposedReason: input.proposed_reason,
+    sessionContext: input.session_context,
+    relevanceScope,
+    relevancePaths,
+    intentClues: input.intent_clues,
+    techStack: input.tech_stack,
+    impact: input.impact,
+    mustReadIf: input.must_read_if,
+    onboardSlot: input.onboard_slot,
+    tags: input.tags,
+    // v2.0.0-rc.37 NEW-7: pass-through evidence_paths to frontmatter.
+    evidencePaths: input.evidence_paths,
+    dedupMarker
+  });
+  await atomicWriteText(absolutePath, fresh);
+  await emitEventBestEffort(projectRoot, {
+    event_type: "knowledge_proposed",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    correlation_id: primarySession,
+    session_id: primarySession,
+    reason: `extract_knowledge:${effectiveSanitizedSlug}`
   });
   return {
-    id,
-    knowledge_type,
-    maturity,
-    knowledge_layer,
-    layer_reason: rawLayerReason,
-    created_at,
-    tags: tags.length > 0 ? tags : void 0,
-    relevance_scope,
-    relevance_paths,
-    related: related.length > 0 ? related : void 0
+    pending_path: reportedPath,
+    idempotency_key: effectiveIdempotencyKey
   };
 }
-function extractScalar(frontmatter, key) {
-  const pattern = new RegExp(`^${escapeRegExp(key)}:\\s*(.+?)\\s*$`, "mu");
-  const match = pattern.exec(frontmatter);
-  if (match === null) {
+async function computeDedupMarker(projectRoot, candidate) {
+  try {
+    const corpus = await collectStoreCanonicalEntries(projectRoot);
+    const result = classifyArchiveCandidate(
+      candidate,
+      corpus.map((e) => ({
+        stable_id: e.qualifiedId,
+        knowledge_type: typeof e.description.knowledge_type === "string" && e.description.knowledge_type.length > 0 ? e.description.knowledge_type : e.type,
+        layer: e.layer,
+        text: [
+          e.description.summary ?? "",
+          e.description.must_read_if ?? "",
+          ...e.description.intent_clues ?? [],
+          ...e.description.impact ?? [],
+          ...e.description.tags ?? []
+        ].join(" ")
+      }))
+    );
+    return formatDedupMarker(result);
+  } catch {
     return void 0;
   }
-  return unquote(match[1].trim());
 }
-function extractInlineArray(frontmatter, key) {
-  const pattern = new RegExp(`^${escapeRegExp(key)}:\\s*\\[(.*?)\\]\\s*$`, "mu");
-  const match = pattern.exec(frontmatter);
-  if (match === null) {
-    return [];
+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 candidateKey = n === 1 ? args.baseIdempotencyKey : sha256(
+      JSON.stringify({
+        source_session: args.primarySession,
+        type: args.type,
+        slug: candidateSlug
+      })
+    );
+    if (!existsSync3(candidatePath)) {
+      return {
+        absolutePath: candidatePath,
+        sanitizedSlug: candidateSlug,
+        idempotencyKey: candidateKey
+      };
+    }
+    const existing = await readFile4(candidatePath, "utf8");
+    const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
+    if (existingKey === candidateKey) {
+      return {
+        absolutePath: candidatePath,
+        sanitizedSlug: candidateSlug,
+        idempotencyKey: candidateKey
+      };
+    }
   }
-  return match[1].split(",").map((item) => unquote(item.trim())).filter((item) => item.length > 0);
-}
-function unquote(value) {
-  return value.replace(/^["'](.*)["']$/u, "$1");
-}
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-}
-
-// src/services/cross-store-recall.ts
-var readSetWalkCache = /* @__PURE__ */ new Map();
-var readSetWalkCount = 0;
-function readSetWalkCacheKey(projectRoot) {
-  return `${projectRoot}\0${process.env.FABRIC_HOME ?? ""}`;
-}
-async function readSetFingerprint(refs) {
-  const parts = await Promise.all(
-    refs.map(async (ref) => {
-      try {
-        const fileStat = await stat(ref.file);
-        return `${ref.store_uuid}|${ref.alias}|${ref.file}|${fileStat.size}|${fileStat.mtimeMs}`;
-      } catch {
-        return `${ref.store_uuid}|${ref.alias}|${ref.file}|missing`;
-      }
-    })
+  throw new Error(
+    `slug exhaustion: tried ${args.slug}.md plus -2..-${SLUG_DISAMBIGUATE_MAX_VARIANTS} suffix variants and all slots are taken by entries with different idempotency_keys; rename slug at the caller and retry`
   );
-  return parts.sort().join("\n");
-}
-var SEMANTIC_SCOPE_LINE = /^semantic_scope:\s*"?([^"\n]+?)"?\s*$/mu;
-function readSemanticScope(source, layer) {
-  const match = SEMANTIC_SCOPE_LINE.exec(source);
-  return match?.[1] ?? layer;
 }
-function filterByActiveProject(entries, activeProject) {
-  if (activeProject === void 0 || activeProject.length === 0) {
-    return entries;
+function sanitizeSlug(raw) {
+  const lower = raw.toLowerCase();
+  const collapsed = lower.replace(/[^a-z0-9]+/g, "-");
+  const trimmed = collapsed.replace(/^-+|-+$/g, "");
+  if (trimmed.length === 0) {
+    return "";
   }
-  const current = `project:${activeProject}`;
-  return entries.filter(
-    (e) => scopeRoot(e.semanticScope) !== "project" || e.semanticScope === current
-  );
-}
-function activeProjectOf(projectRoot) {
-  const ap = loadProjectConfig2(projectRoot)?.active_project;
-  return ap !== void 0 && ap.length > 0 ? ap : void 0;
+  return trimmed.slice(0, SLUG_MAX_LENGTH).replace(/-+$/g, "");
 }
-async function resolveReadSetSnapshot(projectRoot) {
-  const resolveInput = buildStoreResolveInput2(projectRoot);
-  if (resolveInput === null) {
-    return null;
+function renderFreshEntry(args) {
+  const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  const frontmatterLines = [
+    "---",
+    `type: ${args.type}`,
+    "maturity: draft",
+    `layer: ${args.layer}`,
+    // v2.1 global-refactor (W1/A1): scope coordinate (resolution axis) + the
+    // physical store this entry lives in. `layer` is retained for back-compat
+    // during the co-location retirement; `semantic_scope`/`visibility_store` are
+    // the v2.1 source of truth (scope ⊥ store).
+    `semantic_scope: ${args.semanticScope}`,
+    `visibility_store: ${quoteRelevancePath(args.visibilityStore)}`,
+    `created_at: ${createdAt}`,
+    `source_sessions: [${args.sourceSessions.map((s) => JSON.stringify(s)).join(", ")}]`,
+    `proposed_reason: ${args.proposedReason}`,
+    // rc.31 BUG-2.9/2.1: persist the caller-supplied summary in frontmatter so
+    // knowledge-meta-builder.extractDescriptionFromFrontmatter picks it up
+    // directly. Without this, the meta-builder fell back to extractRule
+    // Description's h1-or-stable-id-or-placeholder synthesis (line ~944),
+    // which made user-visible description.summary == stable_id for any
+    // pending file whose body started with h2-only sections (`## Summary` is
+    // the canonical pending shape). The frontmatter `summary:` line is the
+    // canonical source-of-truth: `extractDescriptionFromFrontmatter` reads it
+    // before extractRuleDescription's fallback kicks in.
+    `summary: ${quoteRelevancePath(args.summary)}`,
+    // v2.0.0-rc.37 NEW-37: render caller-supplied tags or fall back to empty
+    // array. Empty array still legal but doctor's knowledge_tags_empty_ratio
+    // lint will warn at the corpus level. Encourages 2-4 kebab-case topic
+    // strings per entry for cross-entry retrieval signal.
+    args.tags !== void 0 && args.tags.length > 0 ? `tags: [${args.tags.map((t) => quoteRelevancePath(t)).join(", ")}]` : "tags: []"
+  ];
+  if (args.relevanceScope !== void 0) {
+    frontmatterLines.push(`relevance_scope: ${args.relevanceScope}`);
   }
-  const readSet = createStoreResolver2().resolveReadSet(resolveInput);
-  if (readSet.stores.length === 0) {
-    return null;
+  if (args.relevancePaths !== void 0) {
+    const pathsBody = args.relevancePaths.map((p) => quoteRelevancePath(p)).join(", ");
+    frontmatterLines.push(`relevance_paths: [${pathsBody}]`);
   }
-  const personalUuids = new Set(
-    resolveInput.mountedStores.filter((s) => s.personal).map((s) => s.store_uuid)
+  if (args.intentClues !== void 0) {
+    const body2 = args.intentClues.map((s) => quoteRelevancePath(s)).join(", ");
+    frontmatterLines.push(`intent_clues: [${body2}]`);
+  }
+  if (args.techStack !== void 0) {
+    const body2 = args.techStack.map((s) => quoteRelevancePath(s)).join(", ");
+    frontmatterLines.push(`tech_stack: [${body2}]`);
+  }
+  if (args.impact !== void 0) {
+    const body2 = args.impact.map((s) => quoteRelevancePath(s)).join(", ");
+    frontmatterLines.push(`impact: [${body2}]`);
+  }
+  if (args.mustReadIf !== void 0) {
+    frontmatterLines.push(`must_read_if: ${quoteRelevancePath(args.mustReadIf)}`);
+  }
+  if (args.onboardSlot !== void 0) {
+    frontmatterLines.push(`onboard_slot: ${args.onboardSlot}`);
+  }
+  if (args.evidencePaths !== void 0 && args.evidencePaths.length > 0) {
+    const body2 = args.evidencePaths.map((p) => quoteRelevancePath(p)).join(", ");
+    frontmatterLines.push(`evidence_paths: [${body2}]`);
+  }
+  if (args.dedupMarker !== void 0) {
+    frontmatterLines.push(`x-fabric-dedup: ${quoteRelevancePath(args.dedupMarker)}`);
+  }
+  frontmatterLines.push(
+    `x-fabric-idempotency-key: ${args.idempotencyKey}`,
+    "---"
   );
-  const globalRoot = resolveGlobalRoot2();
-  const dirs = readSet.stores.map((entry) => ({
-    store_uuid: entry.store_uuid,
-    alias: entry.alias,
-    dir: join7(
-      globalRoot,
-      storeRelativePathForMount2(
-        resolveInput.mountedStores.find((s) => s.store_uuid === entry.store_uuid) ?? {
-          store_uuid: entry.store_uuid
-        }
-      )
-    )
-  }));
-  return {
-    refs: await readKnowledgeAcrossStores(dirs),
-    personalUuids
-  };
+  const frontmatter = frontmatterLines.join("\n");
+  const reasonExplanation = PROPOSED_REASON_DESCRIPTIONS_BY_LOCALE[resolveGlobalLocale()][args.proposedReason];
+  const body = [
+    "",
+    "## Summary",
+    "",
+    args.summary,
+    "",
+    "## Why proposed",
+    "",
+    `${args.proposedReason} \u2014 ${reasonExplanation}`,
+    "",
+    "## Session context",
+    "",
+    args.sessionContext,
+    "",
+    "## Evidence",
+    "",
+    renderEvidenceBlock(args.summary, args.recentPaths),
+    ""
+  ].join("\n");
+  return `${frontmatter}
+${body}`;
 }
-async function walkReadSetStores(projectRoot) {
-  const snapshot = await resolveReadSetSnapshot(projectRoot);
-  if (snapshot === null) {
-    return [];
+function quoteRelevancePath(value) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+  return `"${escaped}"`;
+}
+function renderEvidenceBlock(summary, recentPaths) {
+  const pathLines = recentPaths.length === 0 ? "_(no recent paths reported)_" : recentPaths.map((p) => `- ${p}`).join("\n");
+  return [
+    "Recent paths:",
+    "",
+    pathLines,
+    "",
+    "Notes:",
+    "",
+    `- ${summary.trim()}`
+  ].join("\n");
+}
+function mergeEvidenceNotes(existing, fresh) {
+  const freshSplit = splitAtEvidence(fresh);
+  if (freshSplit === null) {
+    return fresh.endsWith("\n") ? fresh : `${fresh}
+`;
   }
-  const key = readSetWalkCacheKey(projectRoot);
-  const fingerprint = await readSetFingerprint(snapshot.refs);
-  const cached = readSetWalkCache.get(key);
-  if (cached !== void 0 && cached.fingerprint === fingerprint) {
-    return cached.entries.slice();
+  const freshHead = freshSplit.head;
+  const oldEvidence = collectEvidenceItems(existing);
+  const freshEvidence = collectEvidenceItems(fresh);
+  const mergedNotes = [];
+  const seenNotes = /* @__PURE__ */ new Set();
+  for (const note of [...oldEvidence.notes, ...freshEvidence.notes]) {
+    const key = note.replace(/\s+/gu, " ").trim();
+    if (key.length === 0) continue;
+    if (seenNotes.has(key)) continue;
+    seenNotes.add(key);
+    mergedNotes.push(note);
   }
-  const entries = await walkReadSetStoresUncached(snapshot);
-  readSetWalkCache.set(key, { fingerprint, entries });
-  return entries.slice();
+  const mergedPaths = [];
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (const p of [...oldEvidence.paths, ...freshEvidence.paths]) {
+    const key = p.trim();
+    if (key.length === 0) continue;
+    if (seenPaths.has(key)) continue;
+    seenPaths.add(key);
+    mergedPaths.push(key);
+  }
+  const pathLines = mergedPaths.length === 0 ? "_(no recent paths reported)_" : mergedPaths.map((p) => `- ${p}`).join("\n");
+  const noteLines = mergedNotes.length === 0 ? "_(no notes recorded)_" : mergedNotes.map((n) => `- ${n}`).join("\n");
+  const evidenceBody = [
+    "Recent paths:",
+    "",
+    pathLines,
+    "",
+    "Notes:",
+    "",
+    noteLines
+  ].join("\n");
+  return `${freshHead}
+## Evidence
+
+${evidenceBody}
+`;
 }
-async function walkReadSetStoresUncached(snapshot) {
-  readSetWalkCount += 1;
-  const entries = await Promise.all(snapshot.refs.map(async (ref) => {
-    let source;
-    try {
-      source = await readFile4(ref.file, "utf8");
-    } catch {
-      return null;
-    }
-    const stableId = deriveRuleIdentity(ref.file, source, void 0).stableId;
-    const layer = snapshot.personalUuids.has(ref.store_uuid) ? "personal" : "team";
-    return {
-      qualifiedId: `${ref.alias}:${stableId}`,
-      file: ref.file,
-      type: ref.type,
-      alias: ref.alias,
-      layer,
-      semanticScope: readSemanticScope(source, layer),
-      source
-    };
-  }));
-  return entries.filter((entry) => entry !== null);
+function splitAtEvidence(content) {
+  const tail = content.endsWith("\n") ? content : `${content}
+`;
+  const match = /^([\s\S]*?)(\n## Evidence(?:\s*\(call \d+\))?\s*\n)/u.exec(tail);
+  if (match === null) return null;
+  return { head: match[1] ?? "" };
 }
-async function buildCrossStoreRawItems(projectRoot) {
-  const items = [];
-  const activeProject = activeProjectOf(projectRoot);
-  for (const entry of filterByActiveProject(await walkReadSetStores(projectRoot), activeProject)) {
-    const baseDescription = extractRuleDescription(entry.source);
-    if (baseDescription === void 0) {
-      continue;
+function collectEvidenceItems(content) {
+  const notes = [];
+  const paths = [];
+  const evidenceBlockRe = /\n## Evidence(?:\s*\(call \d+\))?\s*\n([\s\S]*?)(?=\n## |$)/gu;
+  let m;
+  while ((m = evidenceBlockRe.exec(`${content}
+`)) !== null) {
+    const block = m[1] ?? "";
+    const pathSection = /Recent paths:\s*\n([\s\S]*?)(?:\n\s*Notes:|$)/u.exec(block);
+    if (pathSection !== null) {
+      for (const rawLine of (pathSection[1] ?? "").split(/\r?\n/u)) {
+        const t = rawLine.trim();
+        if (t.startsWith("- ")) {
+          paths.push(t.slice(2).trim());
+        }
+      }
     }
-    items.push({
-      stable_id: entry.qualifiedId,
-      description: {
-        ...baseDescription,
-        knowledge_layer: entry.layer,
-        semantic_scope: entry.semanticScope
+    const notesSection = /Notes:\s*\n([\s\S]*?)$/u.exec(block);
+    const noteBody = (notesSection !== null ? notesSection[1] : block) ?? "";
+    const bulletLines = [];
+    let prose = [];
+    for (const rawLine of noteBody.split(/\r?\n/u)) {
+      const t = rawLine.trim();
+      if (t.length === 0) continue;
+      if (t.startsWith("- ")) {
+        if (prose.length > 0) {
+          notes.push(prose.join(" ").trim());
+          prose = [];
+        }
+        bulletLines.push(t.slice(2).trim());
+      } else {
+        prose.push(t);
       }
-    });
-  }
-  return items;
-}
-async function buildCrossStoreBodyIndex(projectRoot) {
-  const index = /* @__PURE__ */ new Map();
-  const activeProject = activeProjectOf(projectRoot);
-  for (const entry of filterByActiveProject(await walkReadSetStores(projectRoot), activeProject)) {
-    if (!index.has(entry.qualifiedId)) {
-      index.set(entry.qualifiedId, { file: entry.file, layer: entry.layer });
     }
+    if (prose.length > 0) notes.push(prose.join(" ").trim());
+    for (const n of bulletLines) notes.push(n);
   }
-  return index;
+  return { notes, paths };
 }
-var ALWAYS_ACTIVE_TYPES = /* @__PURE__ */ new Set(["guidelines", "models"]);
-async function buildKnowledgeCensus(projectRoot) {
-  const census = {
-    by_type: {},
-    by_layer: { team: 0, personal: 0, project: 0 },
-    dropped_other_project: 0,
-    total: 0
-  };
-  try {
-    const activeProject = activeProjectOf(projectRoot);
-    const all = await walkReadSetStores(projectRoot);
-    const kept = filterByActiveProject(all, activeProject);
-    census.dropped_other_project = all.length - kept.length;
-    for (const entry of kept) {
-      const type = extractRuleDescription(entry.source)?.knowledge_type;
-      if (typeof type === "string") {
-        census.by_type[type] = (census.by_type[type] ?? 0) + 1;
-      }
-      if (scopeRoot(entry.semanticScope) === "project") {
-        census.by_layer.project += 1;
-      } else {
-        census.by_layer[entry.layer] += 1;
-      }
-      census.total += 1;
+function readFrontmatterKey(content, key) {
+  const match = /^---\n([\s\S]*?)\n---/u.exec(content);
+  if (match === null) {
+    return void 0;
+  }
+  const block = match[1];
+  if (block === void 0) {
+    return void 0;
+  }
+  for (const rawLine of block.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    const sep5 = line.indexOf(":");
+    if (sep5 === -1) continue;
+    const k = line.slice(0, sep5).trim();
+    if (k === key) {
+      return line.slice(sep5 + 1).trim();
     }
-  } catch {
   }
-  return census;
+  return void 0;
 }
-async function buildAlwaysActiveBodies(projectRoot) {
-  const out = [];
+async function emitEventBestEffort(projectRoot, event) {
   try {
-    const activeProject = activeProjectOf(projectRoot);
-    for (const entry of filterByActiveProject(
-      await walkReadSetStores(projectRoot),
-      activeProject
-    )) {
-      const desc = extractRuleDescription(entry.source);
-      if (desc === void 0) continue;
-      const type = desc.knowledge_type;
-      if (typeof type !== "string" || !ALWAYS_ACTIVE_TYPES.has(type)) continue;
-      out.push({
-        stable_id: entry.qualifiedId,
-        type,
-        layer: entry.layer,
-        summary: typeof desc.summary === "string" ? desc.summary : "",
-        body: extractBody(entry.source)
-      });
-    }
+    await appendEventLedgerEvent(projectRoot, event);
   } catch {
-    return [];
   }
-  return out;
-}
-async function computeReadSetRevision(projectRoot) {
-  const revisionSource = (await walkReadSetStores(projectRoot)).filter((entry) => !entry.file.includes("/knowledge/pending/")).map((entry) => `${entry.qualifiedId}|${sha256(entry.source)}`).sort().join("\n");
-  return sha256(revisionSource);
 }
-async function collectStoreCanonicalEntries(projectRoot) {
-  const out = [];
-  for (const entry of await walkReadSetStores(projectRoot)) {
-    if (entry.file.includes("/knowledge/pending/")) {
-      continue;
-    }
-    const description = extractRuleDescription(entry.source);
-    if (description === void 0) {
-      continue;
+
+// src/tools/extract-knowledge.ts
+function registerExtractKnowledge(server, tracker) {
+  server.registerTool(
+    "fab_propose",
+    {
+      description: "Persist a proposed pending knowledge entry into the resolved write-target store under knowledge/pending/<type>/<slug>.md. Idempotent on (source_sessions[0], type, slug); repeat calls append evidence rather than overwrite. Skill-side tool \u2014 invoked at session-stop.",
+      inputSchema: FabExtractKnowledgeInputShape,
+      outputSchema: FabExtractKnowledgeOutputSchema.shape,
+      annotations: fabExtractKnowledgeAnnotations
+    },
+    async (input) => {
+      const requestId = randomUUID2();
+      tracker?.enter(requestId);
+      try {
+        const gateResult = await awaitFirstReconcileGate();
+        const gateWarn = gateWarning(gateResult);
+        let validated;
+        try {
+          validated = FabExtractKnowledgeInputSchema.parse(input);
+        } catch (parseErr) {
+          if (parseErr instanceof ZodError) {
+            const audienceIssue = parseErr.issues.find((issue) => issue.path.includes("audience"));
+            if (audienceIssue !== void 0) {
+              const hinted = new Error(audienceIssue.message);
+              hinted.code = "scope_coordinate_invalid";
+              hinted.action_hint = SCOPE_COORDINATE_HINT;
+              throw hinted;
+            }
+          }
+          throw parseErr;
+        }
+        const projectRoot = resolveProjectRoot();
+        const result = await extractKnowledge(projectRoot, validated);
+        const response = { ...result };
+        if (gateWarn) {
+          response.warnings = [gateWarn];
+        }
+        const payloadLimits = readPayloadLimits(projectRoot);
+        const serialized = JSON.stringify(response);
+        const guardResult = enforcePayloadLimit(serialized, payloadLimits);
+        response.warnings = appendPayloadWarning(
+          response.warnings,
+          guardResult,
+          "fab_propose produced an unexpectedly large response \u2014 extract from a smaller span of text."
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Fabric propose: ${response.pending_path} (see structuredContent)`
+            }
+          ],
+          structuredContent: response
+        };
+      } finally {
+        tracker?.exit(requestId);
+      }
     }
-    out.push({
-      stableId: entry.qualifiedId.slice(entry.alias.length + 1),
-      qualifiedId: entry.qualifiedId,
-      file: entry.file,
-      type: entry.type,
-      layer: entry.layer,
-      body: entry.source,
-      description
-    });
-  }
-  return out;
+  );
 }
-async function collectStoreKnowledgeSummaries(projectRoot) {
-  const out = [];
-  for (const entry of await 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/tools/recall.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import {
+  recallAnnotations,
+  recallInputSchema,
+  recallOutputSchema
+} from "@fenglimg/fabric-shared/schemas/api-contracts";
+import { enforcePayloadLimit as enforcePayloadLimit2 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+
+// src/services/plan-context.ts
+import {
+  buildStoreResolveInput as buildStoreResolveInput3,
+  createStoreResolver as createStoreResolver3,
+  resolveCandidates,
+  tokenize as tokenize2
+} from "@fenglimg/fabric-shared";
+import {
+  trimToPayloadBudget
+} from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+
+// src/services/get-knowledge.ts
+function normalizeKnowledgePath(value) {
+  return value.replaceAll("\\", "/");
 }
 
 // src/services/id-redirect.ts
@@ -2382,61 +2670,6 @@ var LEDGER_DUAL_WRITE_METRIC_NAMES = {
   edit_intent_checked: METRIC_COUNTER_NAMES.edit_intent_checked
 };
 
-// src/services/bm25.ts
-import { tokenize } from "@fenglimg/fabric-shared";
-var K1 = 1.5;
-var B = 0.75;
-function buildBm25Model(docs) {
-  const totalDocs = docs.length;
-  const documentFrequency = /* @__PURE__ */ new Map();
-  const perDoc = /* @__PURE__ */ new Map();
-  let totalLength = 0;
-  for (const doc of docs) {
-    const termFreq = /* @__PURE__ */ new Map();
-    for (const term of doc.tokens) {
-      termFreq.set(term, (termFreq.get(term) ?? 0) + 1);
-    }
-    for (const term of termFreq.keys()) {
-      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
-    }
-    totalLength += doc.tokens.length;
-    perDoc.set(doc.id, { termFreq, length: doc.tokens.length });
-  }
-  const avgDocLength = totalDocs > 0 ? totalLength / totalDocs : 0;
-  const idf = (term) => {
-    const n = documentFrequency.get(term) ?? 0;
-    return Math.log(1 + (totalDocs - n + 0.5) / (n + 0.5));
-  };
-  return {
-    scoreDoc(id, queryTerms) {
-      const data = perDoc.get(id);
-      if (data === void 0 || data.length === 0 || queryTerms.length === 0) {
-        return 0;
-      }
-      const normalizer = avgDocLength > 0 ? data.length / avgDocLength : 1;
-      let score = 0;
-      const scoredTerms = /* @__PURE__ */ new Set();
-      for (const term of queryTerms) {
-        if (scoredTerms.has(term)) {
-          continue;
-        }
-        scoredTerms.add(term);
-        const freq = data.termFreq.get(term);
-        if (freq === void 0) {
-          continue;
-        }
-        const numerator = freq * (K1 + 1);
-        const denominator = freq + K1 * (1 - B + B * normalizer);
-        score += idf(term) * (numerator / denominator);
-      }
-      return score;
-    }
-  };
-}
-function buildQueryTerms(text) {
-  return tokenize(text);
-}
-
 // src/services/vector-retrieval.ts
 var embedderLoad;
 var OPTIONAL_EMBED_PACKAGE = "fastembed";
@@ -2654,7 +2887,9 @@ async function planContext(projectRoot, input) {
   const relevanceFloor = maxScore * relevanceRatio;
   const survivingScored = hasQuery && maxScore > 0 && relevanceRatio > 0 ? cappedScored.filter((entry) => entry.score >= relevanceFloor) : cappedScored;
   const topKCandidates = survivingScored.map((entry) => entry.item);
-  const omittedCandidateCount = Math.max(0, rankedCandidates.length - topKCandidates.length);
+  const topKIds = new Set(topKCandidates.map((item) => item.stable_id));
+  const retrievalDropped = rankedCandidates.filter((item) => !topKIds.has(item.stable_id)).map((item) => ({ id: item.stable_id, reason: "retrieval_budget" }));
+  const omittedCandidateCount = retrievalDropped.length;
   let candidates = topKCandidates;
   const relatedAppended = {};
   if (input.include_related === true) {
@@ -2694,8 +2929,10 @@ async function planContext(projectRoot, input) {
   const basePreflightDiagnostics = buildPreflightDiagnostics(suppressedStableIds);
   let payloadTrimDropped = 0;
   let payloadOverBudget = false;
+  let payloadDropped = [];
   if (input.payload_budget !== void 0) {
     const fullCandidateCount = candidates.length;
+    const preTrimIds = candidates.map((item) => item.stable_id);
     const serialize = (candidateSlice) => {
       const dropped = fullCandidateCount - candidateSlice.length;
       const totalOmitted = omittedCandidateCount + dropped;
@@ -2706,7 +2943,7 @@ async function planContext(projectRoot, input) {
         entries,
         ...input.intent !== void 0 ? { intent: input.intent } : {},
         candidates: candidateSlice,
-        ...totalOmitted > 0 ? { omitted_candidate_count: totalOmitted } : {},
+        ...totalOmitted > 0 ? { dropped_count: totalOmitted } : {},
         preflight_diagnostics: basePreflightDiagnostics,
         warnings: dropped > 0 && input.payload_budget?.trim_warning !== void 0 ? [...input.payload_budget.warnings ?? [], input.payload_budget.trim_warning] : input.payload_budget?.warnings,
         ...Object.keys(relatedAppended).length > 0 ? { related_appended: relatedAppended } : {}
@@ -2714,6 +2951,8 @@ async function planContext(projectRoot, input) {
     };
     const trim = trimToPayloadBudget(candidates, serialize, input.payload_budget.limits);
     if (trim.dropped > 0) {
+      const survivingIds = new Set(trim.items.map((item) => item.stable_id));
+      payloadDropped = preTrimIds.filter((id) => !survivingIds.has(id)).map((id) => ({ id, reason: "payload_budget" }));
       candidates = trim.items;
       payloadTrimDropped = trim.dropped;
     }
@@ -2737,7 +2976,11 @@ async function planContext(projectRoot, input) {
     entries,
     ...input.intent !== void 0 ? { intent: input.intent } : {},
     candidates,
-    ...omittedCandidateCount + payloadTrimDropped > 0 ? { omitted_candidate_count: omittedCandidateCount + payloadTrimDropped } : {},
+    // K6 (W3-K): assemble the structured dropped[] ONCE, here at final result
+    // assembly — the CONSTANT retrieval_budget set (computed pre-trim) followed
+    // by the payload_budget set (computed after the trim settled). Omitted when
+    // nothing was dropped, keeping the steady-state wire shape unchanged.
+    ...retrievalDropped.length + payloadDropped.length > 0 ? { dropped: [...retrievalDropped, ...payloadDropped] } : {},
     preflight_diagnostics: basePreflightDiagnostics,
     // v2.2 W5 R1: the auto_healed / previous_revision_hash pair was tied to the
     // co-location loadActiveMetaOrStale read-path auto-heal, which is retired.
@@ -2845,7 +3088,7 @@ function getOrBuildBm25Model(revision, rawItems, docTexts) {
   const model = buildBm25Model(
     rawItems.map((item) => ({
       id: item.stable_id,
-      tokens: tokenize2(docTexts.get(item.stable_id) ?? documentTextForItem(item.description))
+      fields: documentFieldsForItem(item.description)
     }))
   );
   bm25ModelCache = { revision, model };
@@ -2919,6 +3162,16 @@ function documentTextForItem(description) {
     ...description.tags ?? []
   ].join(" ");
 }
+function documentFieldsForItem(description) {
+  return {
+    title: tokenize2(description.summary),
+    tags: tokenize2(
+      [...description.tags ?? [], ...description.tech_stack, ...description.entities ?? []].join(" ")
+    ),
+    summary: tokenize2([description.must_read_if, ...description.intent_clues].join(" ")),
+    body: tokenize2(description.impact.join(" "))
+  };
+}
 function isEmptyShellDescription(description, stableId) {
   return description.summary === stableId && description.intent_clues.length === 0 && description.tech_stack.length === 0 && description.impact.length === 0;
 }
@@ -3018,7 +3271,7 @@ function relatedLookupKeys(stableId) {
 }
 
 // src/services/recall.ts
-var RECALL_DIRECTIVE = "Before you edit or commit to a decision, cite the KB id you apply or dismiss (first reply line: `KB: <id> [applied|dismissed:<reason>]`).";
+var RECALL_DIRECTIVE = "These entries are auto-accounted as citations for edits whose paths overlap this recall \u2014 no first-line cite needed. Speak up only to dismiss one you judge inapplicable: `dismissed: <id> (<reason>)`.";
 async function recall(projectRoot, input) {
   const planResult = await planContext(projectRoot, input);
   const { selection_token: _token, payload_trimmed: _pt, payload_over_budget: _pob, ...planRest } = planResult;
@@ -3067,13 +3320,22 @@ async function recall(projectRoot, input) {
     paths.push(attachPathStore({ stable_id: candidate.stable_id, path: ref.file }));
   }
   const nextSteps = buildNextSteps(planResult, paths, candidateById, candidateLookup);
-  const markedCandidates = planRest.candidates.map(
-    (c) => isAlwaysActive(c) ? { ...c, always_active: true } : c
-  );
+  const pathByStableId = new Map(paths.map((p) => [p.stable_id, p]));
+  const entries = planRest.candidates.map((c, index) => {
+    const readPath = pathByStableId.get(c.stable_id);
+    return {
+      stable_id: c.stable_id,
+      rank: index + 1,
+      description: c.description,
+      ...readPath ? { read_path: readPath.path } : {},
+      ...readPath?.store ? { store: readPath.store } : {},
+      ...isAlwaysActive(c) ? { body_in_context: true } : {}
+    };
+  });
+  const { entries: _reqProfiles, candidates: _candidates, ...planRestNoLists } = planRest;
   return {
-    ...planRest,
-    candidates: markedCandidates,
-    paths,
+    ...planRestNoLists,
+    entries,
     directive: RECALL_DIRECTIVE,
     ...nextSteps.length > 0 ? { next_steps: nextSteps } : {}
   };
@@ -3085,7 +3347,7 @@ function isAlwaysActive(candidate) {
 }
 function buildNextSteps(planResult, paths, candidateById, candidateLookup) {
   const nextSteps = [];
-  const omitted = planResult.omitted_candidate_count ?? 0;
+  const omitted = (planResult.dropped ?? []).filter((d) => d.reason === "retrieval_budget").length;
   if (omitted > 0) {
     nextSteps.push(
       `${omitted} lower-ranked candidate(s) were omitted by the retrieval budget \u2014 pass a narrower intent (or raise plan_context_top_k) to surface them.`
@@ -3121,7 +3383,7 @@ function registerRecall(server, tracker) {
   server.registerTool(
     "fab_recall",
     {
-      description: "Recall the Fabric knowledge relevant to the files you are about to touch. Pass candidate `paths` (+ optional `intent`) and receive a DESCRIPTION index (`candidates[]`: summary / intent_clues / must_read_if / related) plus a READ-PATH index (`paths[]`: one on-disk knowledge file per surfaced candidate). It does NOT return bodies \u2014 Read a `paths[].path` to load the full entry on demand (cheap, and recoverable), instead of paying a permanent per-recall context tax for bodies you may not use. Pass `ids` to scope which read paths are surfaced when you already know which entries you want; `include_related:true` to also surface one-hop `related` neighbours' descriptions + read paths.",
+      description: "Recall the Fabric knowledge relevant to the files you are about to touch. Pass candidate `paths` (+ optional `intent`) and receive a single ranked `entries[]` list \u2014 each entry carries its DESCRIPTION (summary / intent_clues / must_read_if / related), a `read_path` (the on-disk knowledge file to Read for the body), `rank` (1 = most relevant), and `body_in_context:true` when the body is already injected at SessionStart. It does NOT return bodies \u2014 Read an entry's `read_path` on demand (cheap, recoverable) instead of paying a permanent per-recall context tax for bodies you may not use. Pass `ids` to scope which entries surface a read_path when you already know which you want; `include_related:true` to also surface one-hop `related` neighbours.",
       inputSchema: recallInputSchema,
       outputSchema: recallOutputSchema,
       annotations: recallAnnotations
@@ -3176,11 +3438,16 @@ function registerRecall(server, tracker) {
         response.warnings = appendPayloadWarning(
           response.warnings,
           guardResult,
-          "Pass an explicit `ids` array (or a narrower `intent`) to scope fab_recall's read-path index \u2014 recall returns descriptions + read paths, so Read a `paths[].path` to load any body on demand."
+          "Pass an explicit `ids` array (or a narrower `intent`) to scope fab_recall's entries \u2014 each entry carries a `read_path`, so Read it to load any body on demand."
         );
         payloadBytesOut = Buffer.byteLength(serialized, "utf8");
         return {
-          content: [{ type: "text", text: JSON.stringify(response) }],
+          content: [
+            {
+              type: "text",
+              text: `Fabric recall: ${result.entries.length} entries (see structuredContent)`
+            }
+          ],
           structuredContent: response
         };
       } catch (error) {
@@ -3384,7 +3651,12 @@ function registerArchiveScan(server, tracker) {
           "fab_archive_scan returned a large candidate set \u2014 pass an explicit `range` of session_ids to narrow the scan."
         );
         return {
-          content: [{ type: "text", text: JSON.stringify(result) }],
+          content: [
+            {
+              type: "text",
+              text: `Fabric archive scan: ${result.session_ids.length} sessions, ${result.dropped.length} dropped (see structuredContent)`
+            }
+          ],
           structuredContent: result
         };
       } finally {
@@ -3406,11 +3678,190 @@ import { enforcePayloadLimit as enforcePayloadLimit4 } from "@fenglimg/fabric-sh
 
 // src/services/review.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile5, readdir, stat as stat2, unlink } from "fs/promises";
+import { existsSync as existsSync5 } from "fs";
+import { readFile as readFile6, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
 import { homedir } from "os";
-import { basename, isAbsolute, join as join9, relative, resolve as resolve2, sep as sep2 } from "path";
+import { basename, isAbsolute, join as join10, relative, resolve as resolve2, sep as sep2 } from "path";
+
+// src/services/promotion-gate.ts
+function toLocalId(id) {
+  const sep5 = id.indexOf(":");
+  return sep5 === -1 ? id : id.slice(sep5 + 1);
+}
+async function hasUnresolvedDismissal(projectRoot, id) {
+  const target = toLocalId(id);
+  let events;
+  try {
+    ({ events } = await readEventLedger(projectRoot, { event_type: "assistant_turn_observed" }));
+  } catch {
+    return false;
+  }
+  let latestTs = -1;
+  let latestTag;
+  for (const event of events) {
+    if (event.event_type !== "assistant_turn_observed") continue;
+    const ids = event.cite_ids;
+    const tags = event.cite_tags;
+    for (let i = 0; i < ids.length; i += 1) {
+      const cited = ids[i];
+      if (cited === void 0 || toLocalId(cited) !== target) continue;
+      const tag = tags[i];
+      if (tag === void 0) continue;
+      if (event.ts >= latestTs) {
+        latestTs = event.ts;
+        latestTag = tag;
+      }
+    }
+  }
+  return latestTag === "dismissed";
+}
+
+// src/services/review.ts
 import { allocateStoreKnowledgeId, isPersonalScope as isPersonalScope2 } from "@fenglimg/fabric-shared";
+
+// src/services/pending-dedupe.ts
+import { existsSync as existsSync4 } from "fs";
+import { readdir, readFile as readFile5, unlink } from "fs/promises";
+import { join as join9 } from "path";
+var PENDING_TYPES = ["decisions", "pitfalls", "guidelines", "models", "processes"];
+var DISAMBIGUATION_SUFFIX = /^(.+)-([2-9])\.md$/u;
+var SOURCE_SESSIONS_LINE = /^source_sessions:\s*\[(.*)\]\s*$/mu;
+var CREATED_AT_LINE = /^created_at:\s*(.+)$/mu;
+function parseSourceSessions(content) {
+  const m = SOURCE_SESSIONS_LINE.exec(content);
+  if (!m) return [];
+  try {
+    const arr = JSON.parse(`[${m[1]}]`);
+    return Array.isArray(arr) ? arr.filter((s) => typeof s === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function parseCreatedAt(content) {
+  const m = CREATED_AT_LINE.exec(content);
+  return m ? m[1].trim() : "";
+}
+function resolveBaseSlug(name, present) {
+  const m = DISAMBIGUATION_SUFFIX.exec(name);
+  if (m && present.has(`${m[1]}.md`)) return m[1];
+  return name.replace(/\.md$/u, "");
+}
+function unionSessions(survivor, twins) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const s of [survivor, ...twins]) {
+    for (const sid of s.sourceSessions) {
+      if (sid.length > 0 && !seen.has(sid)) {
+        seen.add(sid);
+        out.push(sid);
+      }
+    }
+  }
+  return out;
+}
+function buildMergedContent(survivor, twins) {
+  const union = unionSessions(survivor, twins);
+  let merged = survivor.content.replace(
+    SOURCE_SESSIONS_LINE,
+    `source_sessions: [${union.map((s) => JSON.stringify(s)).join(", ")}]`
+  );
+  if (!merged.endsWith("\n")) merged += "\n";
+  for (const twin of twins) {
+    const body = extractBody(twin.content).trim();
+    if (body.length === 0) continue;
+    merged += `
+## Evidence (merged from session ${twin.primarySession || "unknown"})
+
+${body}
+`;
+  }
+  return merged;
+}
+function chooseSurvivor(baseSlug, group) {
+  const exact = group.find((p) => p.name === `${baseSlug}.md`);
+  if (exact) return exact;
+  return [...group].sort((a, b) => {
+    if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? -1 : 1;
+    return a.name < b.name ? -1 : 1;
+  })[0];
+}
+async function mergePendingTwins(projectRoot) {
+  const merged = [];
+  for (const layer of ["team", "personal"]) {
+    let pendingBase2;
+    try {
+      pendingBase2 = resolveStorePendingBase(layer, projectRoot);
+    } catch {
+      continue;
+    }
+    for (const type of PENDING_TYPES) {
+      const dir = join9(pendingBase2, type);
+      if (!existsSync4(dir)) continue;
+      let names;
+      try {
+        names = (await readdir(dir)).filter((n) => n.endsWith(".md"));
+      } catch {
+        continue;
+      }
+      if (names.length < 2) continue;
+      const present = new Set(names);
+      const groups = /* @__PURE__ */ new Map();
+      for (const name of names) {
+        const base = resolveBaseSlug(name, present);
+        const arr = groups.get(base);
+        if (arr) arr.push(name);
+        else groups.set(base, [name]);
+      }
+      for (const [baseSlug, groupNames] of groups) {
+        if (groupNames.length < 2) continue;
+        const parsed = [];
+        for (const name of groupNames) {
+          const abs = join9(dir, name);
+          let content;
+          try {
+            content = await readFile5(abs, "utf8");
+          } catch {
+            continue;
+          }
+          const sourceSessions = parseSourceSessions(content);
+          parsed.push({
+            name,
+            abs,
+            content,
+            sourceSessions,
+            primarySession: sourceSessions[0] ?? "",
+            createdAt: parseCreatedAt(content)
+          });
+        }
+        if (parsed.length < 2) continue;
+        const distinctPrimaries = new Set(parsed.map((p) => p.primarySession).filter((s) => s.length > 0));
+        if (distinctPrimaries.size < 2) continue;
+        const survivor = chooseSurvivor(baseSlug, parsed);
+        const twins = parsed.filter((p) => p.abs !== survivor.abs);
+        const mergedContent = buildMergedContent(survivor, twins);
+        try {
+          await atomicWriteText(survivor.abs, mergedContent);
+          for (const twin of twins) {
+            await unlink(twin.abs);
+          }
+        } catch {
+          continue;
+        }
+        merged.push({
+          layer,
+          type,
+          base_slug: baseSlug,
+          survivor: survivor.abs,
+          removed: twins.map((t) => t.abs),
+          source_sessions: unionSessions(survivor, twins)
+        });
+      }
+    }
+  }
+  return { merged };
+}
+
+// src/services/review.ts
 var PLURAL_TYPES = [
   "decisions",
   "pitfalls",
@@ -3420,11 +3871,6 @@ var PLURAL_TYPES = [
 ];
 async function reviewKnowledge(projectRoot, input) {
   switch (input.action) {
-    case "list":
-      return {
-        action: "list",
-        items: await listPending(projectRoot, input.filters)
-      };
     case "approve":
       return {
         action: "approve",
@@ -3447,11 +3893,6 @@ async function reviewKnowledge(projectRoot, input) {
     }
     case "modify-layer":
       return await modifyEntry(projectRoot, input.pending_path, input.changes);
-    case "search":
-      return {
-        action: "search",
-        items: await searchEntries(projectRoot, input.query, input.filters)
-      };
     case "defer":
       return {
         action: "defer",
@@ -3468,6 +3909,24 @@ async function reviewKnowledge(projectRoot, input) {
     }
   }
 }
+async function reviewPending(projectRoot, input) {
+  switch (input.action) {
+    case "list":
+      return {
+        action: "list",
+        items: await listPending(projectRoot, input.filters)
+      };
+    case "search":
+      return {
+        action: "search",
+        items: await searchEntries(projectRoot, input.query, input.filters)
+      };
+    default: {
+      const exhaustive = input;
+      throw new Error(`unsupported action: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
 function storeKnowledgeRoots(projectRoot) {
   const roots = [];
   for (const layer of ["team", "personal"]) {
@@ -3517,6 +3976,10 @@ function isVisibleByLifecycle(fm, filters) {
   return true;
 }
 async function listPending(projectRoot, filters) {
+  try {
+    await mergePendingTwins(projectRoot);
+  } catch {
+  }
   const items = [];
   const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
   const sources = [];
@@ -3536,22 +3999,22 @@ async function listPending(projectRoot, filters) {
   }
   for (const source of sources) {
     for (const type of typesToScan) {
-      const dir = join9(source.root, type);
-      if (!existsSync4(dir)) {
+      const dir = join10(source.root, type);
+      if (!existsSync5(dir)) {
         continue;
       }
       let entries;
       try {
-        entries = await readdir(dir);
+        entries = await readdir2(dir);
       } catch {
         continue;
       }
       for (const name of entries) {
         if (!name.endsWith(".md")) continue;
-        const absolutePath = join9(dir, name);
+        const absolutePath = join10(dir, name);
         let content;
         try {
-          content = await readFile5(absolutePath, "utf8");
+          content = await readFile6(absolutePath, "utf8");
         } catch {
           continue;
         }
@@ -3661,7 +4124,7 @@ async function approveOne(projectRoot, pendingPath) {
   let targetAbs;
   let writtenTarget = false;
   try {
-    const content = await readFile5(sourceAbs, "utf8");
+    const content = await readFile6(sourceAbs, "utf8");
     const fm = parseFrontmatter(content);
     const pluralType = fm.type;
     if (pluralType === void 0 || !PLURAL_TYPES.includes(pluralType)) {
@@ -3675,14 +4138,17 @@ async function approveOne(projectRoot, pendingPath) {
     );
     allocatedId = stableId;
     const newFilename = `${stableId}--${slug}.md`;
-    targetAbs = join9(resolveStoreCanonicalBase(layer, projectRoot), pluralType, newFilename);
+    targetAbs = join10(resolveStoreCanonicalBase(layer, projectRoot), pluralType, newFilename);
     await ensureParentDirectory(targetAbs);
-    const rewritten = rewriteFrontmatterForPromote(content, stableId);
+    const rewritten = rewriteFrontmatterMerge(
+      rewriteFrontmatterForPromote(content, stableId),
+      { last_review_confirmed_at: (/* @__PURE__ */ new Date()).toISOString() }
+    );
     await atomicWriteText(targetAbs, rewritten);
     writtenTarget = true;
     if (sourceIsStore) {
-      if (existsSync4(sourceAbs)) {
-        await unlink(sourceAbs);
+      if (existsSync5(sourceAbs)) {
+        await unlink2(sourceAbs);
       }
     } else if (sourceOrigin === "team") {
       try {
@@ -3691,13 +4157,13 @@ async function approveOne(projectRoot, pendingPath) {
           stdio: ["ignore", "pipe", "pipe"]
         });
       } catch {
-        if (existsSync4(sourceAbs)) {
-          await unlink(sourceAbs);
+        if (existsSync5(sourceAbs)) {
+          await unlink2(sourceAbs);
         }
       }
     } else {
-      if (existsSync4(sourceAbs)) {
-        await unlink(sourceAbs);
+      if (existsSync5(sourceAbs)) {
+        await unlink2(sourceAbs);
       }
     }
     await emitEventBestEffort2(projectRoot, {
@@ -3708,9 +4174,9 @@ async function approveOne(projectRoot, pendingPath) {
     });
     return { pending_path: pendingPath, stable_id: stableId };
   } catch (err) {
-    if (writtenTarget && targetAbs !== void 0 && existsSync4(targetAbs)) {
+    if (writtenTarget && targetAbs !== void 0 && existsSync5(targetAbs)) {
       try {
-        await unlink(targetAbs);
+        await unlink2(targetAbs);
       } catch {
       }
     }
@@ -3729,14 +4195,14 @@ async function rejectAll(projectRoot, pendingPaths, reason) {
   for (const pendingPath of pendingPaths) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
-      if (existsSync4(sandboxed.abs)) {
-        const content = await readFile5(sandboxed.abs, "utf8");
+      if (existsSync5(sandboxed.abs)) {
+        const content = await readFile6(sandboxed.abs, "utf8");
         const merged = rewriteFrontmatterMerge(content, { status: "rejected" });
         const rejectedAbs = sandboxed.abs.includes(`${sep2}pending${sep2}`) ? sandboxed.abs.replace(`${sep2}pending${sep2}`, `${sep2}rejected${sep2}`) : null;
         if (rejectedAbs !== null) {
           await ensureParentDirectory(rejectedAbs);
           await atomicWriteText(rejectedAbs, merged);
-          await unlink(sandboxed.abs);
+          await unlink2(sandboxed.abs);
         } else if (merged !== content) {
           await atomicWriteText(sandboxed.abs, merged);
         }
@@ -3757,9 +4223,16 @@ async function modifyEntry(projectRoot, pendingPath, changes) {
   if (target === null) {
     throw new Error(`modify target not found: ${pendingPath}`);
   }
-  const content = await readFile5(target.absPath, "utf8");
+  const content = await readFile6(target.absPath, "utf8");
   const fm = parseFrontmatter(content);
   const currentLayer = fm.layer ?? "team";
+  if (fm.maturity === "verified" && changes.maturity === "proven" && fm.id !== void 0) {
+    if (await hasUnresolvedDismissal(projectRoot, fm.id)) {
+      throw new Error(
+        `verified\u2192proven promotion blocked for ${fm.id}: an unresolved dismissed cite is on record (rubric necessary gate "0 dismiss"). Re-affirm the entry with an applied cite or address the objection, then retry.`
+      );
+    }
+  }
   if (changes.semantic_scope !== void 0 && isPersonalScope2(changes.semantic_scope)) {
     throw new Error(
       `cannot re-scope to personal coordinate '${changes.semantic_scope}' via modify; use action 'modify-layer' with layer 'personal' to move the entry into the personal store (R5#3)`
@@ -3768,7 +4241,10 @@ async function modifyEntry(projectRoot, pendingPath, changes) {
   if (changes.layer !== void 0 && changes.layer !== currentLayer) {
     return await modifyLayerFlip(projectRoot, target, content, fm, changes);
   }
-  const merged = rewriteFrontmatterMerge(content, changes);
+  const merged = rewriteFrontmatterMerge(content, {
+    ...changes,
+    last_review_confirmed_at: (/* @__PURE__ */ new Date()).toISOString()
+  });
   await atomicWriteText(target.absPath, merged);
   const changedFields = Object.keys(changes).filter(
     (field) => changes[field] !== void 0
@@ -3802,7 +4278,7 @@ function resolveModifyTarget(projectRoot, pendingPath) {
   } catch {
     return null;
   }
-  if (existsSync4(sandboxed.abs)) {
+  if (existsSync5(sandboxed.abs)) {
     return {
       absPath: sandboxed.abs,
       isInProjectTree: sandboxed.isInProjectTree,
@@ -3849,7 +4325,7 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
     pluralType,
     resolveWriteTargetStoreDir(toLayer, projectRoot)
   );
-  const toAbs = join9(
+  const toAbs = join10(
     resolveStoreCanonicalBase(toLayer, projectRoot),
     pluralType,
     `${newStableId}--${slug}.md`
@@ -3867,7 +4343,11 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
     relevance_scope: "broad",
     relevance_paths: []
   } : { ...changes, layer: toLayer };
-  const rewritten = rewriteFrontmatterMerge(content, effectivePatch, { id: newStableId });
+  const rewritten = rewriteFrontmatterMerge(
+    content,
+    { ...effectivePatch, last_review_confirmed_at: (/* @__PURE__ */ new Date()).toISOString() },
+    { id: newStableId }
+  );
   await atomicWriteText(toAbs, rewritten);
   if (target.isInProjectTree) {
     const relSource = relative(projectRoot, target.absPath);
@@ -3877,12 +4357,12 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
         stdio: ["ignore", "pipe", "pipe"]
       });
     } catch {
-      if (existsSync4(target.absPath)) {
-        await unlink(target.absPath);
+      if (existsSync5(target.absPath)) {
+        await unlink2(target.absPath);
       }
     }
-  } else if (existsSync4(target.absPath)) {
-    await unlink(target.absPath);
+  } else if (existsSync5(target.absPath)) {
+    await unlink2(target.absPath);
   }
   const flipReason = `layer_flip:${priorStableId ?? "<unassigned>"}->${newStableId}`;
   const flipTimestamp = (/* @__PURE__ */ new Date()).toISOString();
@@ -3945,10 +4425,10 @@ function getSearchDirectoryCache(cacheKey) {
   return created;
 }
 async function listIndexedSearchEntries(source, type) {
-  const dir = join9(source.root, type);
+  const dir = join10(source.root, type);
   let entries;
   try {
-    entries = await readdir(dir);
+    entries = await readdir2(dir);
   } catch {
     return [];
   }
@@ -3958,7 +4438,7 @@ async function listIndexedSearchEntries(source, type) {
   const indexed = [];
   for (const name of entries) {
     if (!name.endsWith(".md")) continue;
-    const absolutePath = join9(dir, name);
+    const absolutePath = join10(dir, name);
     let fingerprint;
     try {
       const st = await stat2(absolutePath);
@@ -3975,7 +4455,7 @@ async function listIndexedSearchEntries(source, type) {
     }
     let content;
     try {
-      content = await readFile5(absolutePath, "utf8");
+      content = await readFile6(absolutePath, "utf8");
       searchEntryIndexContentReads += 1;
     } catch {
       directoryCache.files.delete(absolutePath);
@@ -4095,8 +4575,8 @@ async function deferAll(projectRoot, pendingPaths, until, reason) {
     let stableId;
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
-      if (existsSync4(sandboxed.abs)) {
-        const content = await readFile5(sandboxed.abs, "utf8");
+      if (existsSync5(sandboxed.abs)) {
+        const content = await readFile6(sandboxed.abs, "utf8");
         stableId = parseFrontmatter(content).id;
         const patch = {
           status: "deferred",
@@ -4191,6 +4671,9 @@ function parseFrontmatter(content) {
       case "deferred_until":
         out.deferred_until = stripQuotes(value);
         break;
+      case "last_review_confirmed_at":
+        out.last_review_confirmed_at = stripQuotes(value);
+        break;
       default:
         break;
     }
@@ -4256,6 +4739,7 @@ ${content}`;
   if (patch.related !== void 0) updates.related = `related: ${flowArray(patch.related)}`;
   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)}`;
+  if (patch.last_review_confirmed_at !== void 0) updates.last_review_confirmed_at = `last_review_confirmed_at: ${quoteIfNeeded(patch.last_review_confirmed_at)}`;
   const lines = block.split(/\r?\n/u);
   const seen = /* @__PURE__ */ new Set();
   const newLines = [];
@@ -4292,6 +4776,7 @@ function appendPatchLines(lines, patch) {
   if (patch.related !== void 0) lines.push(`related: ${flowArray(patch.related)}`);
   if (patch.status !== void 0) lines.push(`status: ${patch.status}`);
   if (patch.deferred_until !== void 0) lines.push(`deferred_until: ${quoteIfNeeded(patch.deferred_until)}`);
+  if (patch.last_review_confirmed_at !== void 0) lines.push(`last_review_confirmed_at: ${quoteIfNeeded(patch.last_review_confirmed_at)}`);
 }
 function flowArrayElement(value) {
   if (/[\n\r,\[\]{}"#:]/u.test(value) || /^\s|\s$/u.test(value)) {
@@ -4326,7 +4811,7 @@ function registerReview(server, tracker) {
   server.registerTool(
     "fab_review",
     {
-      description: "Review pending knowledge entries in resolved store-backed knowledge/pending/. Discriminated by `action`: list (enumerate), approve (allocate stable_id and promote to canonical store knowledge path), reject/modify/search/defer (TASK-002). Skill-side tool \u2014 invoked by fabric-review.",
+      description: "Review pending knowledge entries in resolved store-backed knowledge/pending/. Discriminated by `action`; required fields per action: list \u2192 (filters optional); approve \u2192 pending_paths[\u22651]; reject \u2192 pending_paths[\u22651] + reason; modify / modify-content \u2192 pending_path + changes; modify-layer \u2192 pending_path + changes.layer(team|personal); search \u2192 query; defer \u2192 pending_paths[\u22651] (until/reason optional). approve allocates a stable_id and promotes to the canonical store knowledge path. Skill-side tool \u2014 invoked by fabric-review.",
       // Flat ZodRawShape required by MCP SDK 1.29.0 registerTool. The
       // authoritative cross-field contract still lives in FabReviewInputSchema
       // (discriminatedUnion) and is enforced inside the handler via
@@ -4357,7 +4842,71 @@ function registerReview(server, tracker) {
           "fab_review returned a large result set \u2014 pass a narrower filter (topic / status / id) to reduce response size."
         );
         return {
-          content: [{ type: "text", text: JSON.stringify(response) }],
+          content: [
+            {
+              type: "text",
+              text: `Fabric review: ${response.action} (see structuredContent)`
+            }
+          ],
+          structuredContent: response
+        };
+      } finally {
+        tracker?.exit(requestId);
+      }
+    }
+  );
+}
+
+// src/tools/pending.ts
+import { randomUUID as randomUUID6 } from "crypto";
+import {
+  FabPendingInputSchema,
+  FabPendingInputShape,
+  FabPendingOutputShape,
+  fabPendingAnnotations
+} from "@fenglimg/fabric-shared/schemas/api-contracts";
+import { enforcePayloadLimit as enforcePayloadLimit5 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+function registerPending(server, tracker) {
+  server.registerTool(
+    "fab_pending",
+    {
+      description: "Browse and search store-backed pending + canonical knowledge (read-only). Discriminated by `action`; required fields per action: list \u2192 (filters optional, returns pending entries with `pending_path`); search \u2192 query (filters optional, ranges over pending + canonical with `area`+`path`). Never mutates state \u2014 pair with the write-only fab_review tool for approve/reject/modify/defer. Skill-side read tool \u2014 invoked by fabric-review / fabric-archive.",
+      // Flat ZodRawShape required by MCP SDK 1.29.0 registerTool. The
+      // authoritative cross-field contract still lives in FabPendingInputSchema
+      // (discriminatedUnion) and is enforced inside the handler via
+      // `FabPendingInputSchema.parse(input)`.
+      inputSchema: FabPendingInputShape,
+      outputSchema: FabPendingOutputShape,
+      annotations: fabPendingAnnotations
+    },
+    async (input) => {
+      const requestId = randomUUID6();
+      tracker?.enter(requestId);
+      try {
+        const gateResult = await awaitFirstReconcileGate();
+        const gateWarn = gateWarning(gateResult);
+        const narrowed = FabPendingInputSchema.parse(input);
+        const projectRoot = resolveProjectRoot();
+        const result = await reviewPending(projectRoot, narrowed);
+        const response = { ...result };
+        if (gateWarn) {
+          response.warnings = [gateWarn];
+        }
+        const payloadLimits = readPayloadLimits(projectRoot);
+        const serialized = JSON.stringify(response);
+        const guardResult = enforcePayloadLimit5(serialized, payloadLimits);
+        response.warnings = appendPayloadWarning(
+          response.warnings,
+          guardResult,
+          "fab_pending returned a large result set \u2014 pass a narrower filter (topic / status / id) to reduce response size."
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Fabric pending: ${response.action} (see structuredContent)`
+            }
+          ],
           structuredContent: response
         };
       } finally {
@@ -4368,9 +4917,9 @@ function registerReview(server, tracker) {
 }
 
 // src/services/doctor.ts
-import { access as access4, readFile as readFile14, readdir as readdirAsync, stat as statAsync, unlink as unlink3, writeFile as writeFile3 } from "fs/promises";
+import { access as access4, readFile as readFile16, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile3 } from "fs/promises";
 import { constants as constants2 } from "fs";
-import { isAbsolute as isAbsolute2, join as join19, posix as posix4, resolve as resolve3 } from "path";
+import { isAbsolute as isAbsolute2, join as join21, posix as posix5, resolve as resolve3 } from "path";
 import {
   createTranslator,
   forensicReportSchema,
@@ -4584,8 +5133,8 @@ function createKnowledgeSummaryOpaqueCheck(t, inspection) {
 }
 
 // src/services/doctor-stable-id-collision.ts
-import { readFile as readFile6 } from "fs/promises";
-import { basename as basename2, join as join10 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { basename as basename2, join as join11 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput4,
   createStoreResolver as createStoreResolver4,
@@ -4612,7 +5161,7 @@ function resolveIntegrityStores(projectRoot) {
     return {
       store_uuid: entry.store_uuid,
       alias: entry.alias,
-      dir: join10(globalRoot, storeRelativePathForMount3(mounted ?? { store_uuid: entry.store_uuid }))
+      dir: join11(globalRoot, storeRelativePathForMount3(mounted ?? { store_uuid: entry.store_uuid }))
     };
   });
   return { dirs, personalUuids };
@@ -4631,7 +5180,7 @@ async function inspectStoreStableIdIntegrity(projectRoot) {
   for (const ref of await readKnowledgeAcrossStores2(resolved.dirs)) {
     let source;
     try {
-      source = await readFile6(ref.file, "utf8");
+      source = await readFile7(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -4715,8 +5264,8 @@ function createLayerMismatchCheck(t, inspection) {
 
 // src/services/doctor-relevance-paths.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync5, readdirSync, statSync as statSync3 } from "fs";
-import { join as join11, sep as sep3 } from "path";
+import { existsSync as existsSync6, readdirSync, statSync as statSync3 } from "fs";
+import { join as join12, sep as sep3 } from "path";
 import { minimatch } from "minimatch";
 var MS_PER_DAY = 24 * 60 * 60 * 1e3;
 var RELEVANCE_PATHS_DRIFT_WINDOW_DAYS = 90;
@@ -4737,7 +5286,7 @@ function expandGlob(rawGlob) {
   return rawGlob.endsWith("/") ? `${rawGlob}**` : rawGlob;
 }
 function collectWorkspacePaths(projectRoot) {
-  if (!existsSync5(projectRoot)) {
+  if (!existsSync6(projectRoot)) {
     return [];
   }
   try {
@@ -4759,7 +5308,7 @@ function collectWorkspacePaths(projectRoot) {
       continue;
     }
     for (const entry of entries) {
-      const abs = join11(current, entry.name);
+      const abs = join12(current, entry.name);
       const rel = toPosix(abs.slice(projectRoot.length + 1));
       if (rel.length === 0) continue;
       if (entry.isDirectory()) {
@@ -4952,16 +5501,16 @@ function createNarrowNoPathsCheck(t, inspection) {
 }
 
 // src/services/doctor-broad-index.ts
-import { readFile as readFile7 } from "fs/promises";
-import { join as join12 } from "path";
+import { readFile as readFile8 } from "fs/promises";
+import { join as join13 } from "path";
 var DEFAULT_BROAD_INDEX_BACKSTOP = 50;
 var BROAD_INDEX_BACKSTOP_MIN = 20;
 var BROAD_INDEX_BACKSTOP_MAX = 500;
 var BROAD_INDEX_DRIFT_RATIO = 0.8;
 async function readBroadIndexBackstop(projectRoot) {
-  const configPath = join12(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join13(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile7(configPath, "utf8");
+    const raw = await readFile8(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.broad_index_backstop;
@@ -5057,6 +5606,9 @@ async function inspectStoreKnowledgeAge(projectRoot, now, lastActiveIndex) {
     if (maturity === void 0) {
       continue;
     }
+    if (entry.description.relevance_scope === "broad") {
+      continue;
+    }
     const lastActive = lastActiveIndex.get(entry.stableId);
     if (lastActive === void 0) {
       continue;
@@ -5141,9 +5693,142 @@ function createStaleArchiveCheck(t, inspection) {
   };
 }
 
+// src/services/doctor-knowledge-promotion.ts
+var PROVEN_RELATED_INDEGREE_THRESHOLD = 3;
+function toLocalId2(id) {
+  const sep5 = id.indexOf(":");
+  return sep5 === -1 ? id : id.slice(sep5 + 1);
+}
+function computeRelatedInDegree(entries) {
+  const indegree = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    for (const target of entry.description.related ?? []) {
+      const key = toLocalId2(target);
+      indegree.set(key, (indegree.get(key) ?? 0) + 1);
+    }
+  }
+  return indegree;
+}
+async function inspectStoreKnowledgePromotion(projectRoot, indegreeThreshold = PROVEN_RELATED_INDEGREE_THRESHOLD) {
+  const entries = await collectStoreCanonicalEntries(projectRoot);
+  const indegree = computeRelatedInDegree(entries);
+  const candidates = [];
+  for (const entry of entries) {
+    if (entry.description.maturity !== "verified") {
+      continue;
+    }
+    const deg = indegree.get(entry.stableId) ?? 0;
+    if (deg >= indegreeThreshold) {
+      candidates.push({
+        stable_id: entry.qualifiedId,
+        path: `store:${entry.qualifiedId}`,
+        related_indegree: deg
+      });
+    }
+  }
+  candidates.sort((a, b) => a.path.localeCompare(b.path));
+  return { candidates, indegree_threshold: indegreeThreshold };
+}
+function createPromotionCandidateCheck(t, inspection) {
+  if (inspection.candidates.length === 0) {
+    return {
+      name: t("doctor.check.promotion_candidate.name"),
+      status: "ok",
+      message: t("doctor.check.promotion_candidate.ok")
+    };
+  }
+  const first = inspection.candidates[0];
+  const detail = `${first.stable_id} (verified, ${first.related_indegree} inbound related \u2192 proven candidate)`;
+  const count = inspection.candidates.length;
+  return {
+    name: t("doctor.check.promotion_candidate.name"),
+    // An opportunity, not a defect — info kind keeps doctor health "ok".
+    status: "ok",
+    kind: "info",
+    code: "knowledge_promotion_candidate",
+    fixable: false,
+    message: t(`doctor.check.promotion_candidate.message.${count === 1 ? "singular" : "plural"}`, {
+      count: String(count),
+      threshold: String(inspection.indegree_threshold),
+      detail
+    }),
+    actionHint: t("doctor.check.promotion_candidate.remediation")
+  };
+}
+
+// src/services/doctor-knowledge-review-recheck.ts
+var MS_PER_DAY3 = 24 * 60 * 60 * 1e3;
+var LAST_REVIEW_CONFIRMED_LINE = /^last_review_confirmed_at:\s*"?([^"\n]+?)"?\s*$/mu;
+var CREATED_AT_LINE2 = /^created_at:\s*"?([^"\n]+?)"?\s*$/mu;
+function resolveClock(source) {
+  const review = LAST_REVIEW_CONFIRMED_LINE.exec(source)?.[1];
+  if (review !== void 0) {
+    const ms = Date.parse(review);
+    if (!Number.isNaN(ms)) return { ms, source: "review" };
+  }
+  const created = CREATED_AT_LINE2.exec(source)?.[1];
+  if (created !== void 0) {
+    const ms = Date.parse(created);
+    if (!Number.isNaN(ms)) return { ms, source: "created" };
+  }
+  return void 0;
+}
+async function inspectStoreBroadReviewRecheck(projectRoot, now, thresholdDays = readBroadReviewRecheckThresholdDays(projectRoot)) {
+  const entries = await collectStoreCanonicalEntries(projectRoot);
+  const candidates = [];
+  for (const entry of entries) {
+    if (entry.description.relevance_scope !== "broad") {
+      continue;
+    }
+    const clock = resolveClock(entry.body);
+    if (clock === void 0) {
+      continue;
+    }
+    const ageDays = Math.floor((now - clock.ms) / MS_PER_DAY3);
+    if (ageDays > thresholdDays) {
+      candidates.push({
+        stable_id: entry.qualifiedId,
+        path: `store:${entry.qualifiedId}`,
+        age_days: ageDays,
+        clock_source: clock.source
+      });
+    }
+  }
+  candidates.sort((a, b) => a.path.localeCompare(b.path));
+  return { candidates, threshold_days: thresholdDays };
+}
+function createBroadReviewRecheckCheck(t, inspection) {
+  if (inspection.candidates.length === 0) {
+    return {
+      name: t("doctor.check.broad_review_recheck.name"),
+      status: "ok",
+      message: t("doctor.check.broad_review_recheck.ok")
+    };
+  }
+  const first = inspection.candidates[0];
+  const clockLabel = first.clock_source === "review" ? "last reviewed" : "never re-confirmed since creation,";
+  const detail = `${first.stable_id} (broad, ${clockLabel} ${first.age_days}d ago \u2192 recheck)`;
+  const count = inspection.candidates.length;
+  return {
+    name: t("doctor.check.broad_review_recheck.name"),
+    // A re-confirm nudge, not a defect — info kind keeps doctor health "ok"
+    // (broad is exempt from decay warnings; this is the gentler review clock).
+    status: "ok",
+    kind: "info",
+    code: "knowledge_broad_review_recheck",
+    fixable: false,
+    message: t(`doctor.check.broad_review_recheck.message.${count === 1 ? "singular" : "plural"}`, {
+      count: String(count),
+      thresholdDays: String(inspection.threshold_days),
+      detail
+    }),
+    actionHint: t("doctor.check.broad_review_recheck.remediation")
+  };
+}
+
 // src/services/doctor-scope-lint.ts
-import { readFile as readFile8 } from "fs/promises";
-import { join as join13 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join14 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput5,
   createStoreResolver as createStoreResolver5,
@@ -5178,7 +5863,7 @@ async function resolveLintStores(projectRoot) {
   const globalRoot = resolveGlobalRoot4();
   return Promise.all(readSet.stores.map(async (entry) => {
     const mounted = input.mountedStores.find((s) => s.store_uuid === entry.store_uuid);
-    const dir = join13(
+    const dir = join14(
       globalRoot,
       storeRelativePathForMount4(mounted ?? { store_uuid: entry.store_uuid })
     );
@@ -5210,7 +5895,7 @@ async function lintStoreScopes(projectRoot) {
     }
     let source;
     try {
-      source = await readFile8(ref.file, "utf8");
+      source = await readFile9(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -5332,8 +6017,8 @@ function createUnboundProjectCheck(t, violation) {
 }
 
 // src/services/doctor-store-counters.ts
-import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
-import { join as join14 } from "path";
+import { existsSync as existsSync7, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
+import { join as join15 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput6,
   createStoreResolver as createStoreResolver6,
@@ -5360,7 +6045,7 @@ function resolveCounterStores(projectRoot) {
   return readSet.stores.map((entry) => ({
     uuid: entry.store_uuid,
     alias: entry.alias,
-    dir: join14(
+    dir: join15(
       globalRoot,
       storeRelativePathForMount5(
         input.mountedStores.find((s) => s.store_uuid === entry.store_uuid) ?? {
@@ -5388,8 +6073,8 @@ function readEntryId(file) {
 function computeStoreDiskMax(storeDir) {
   const max = defaultAgentsMetaCounters();
   for (const type of STORE_KNOWLEDGE_TYPE_DIRS) {
-    const dir = join14(storeDir, STORE_LAYOUT2.knowledgeDir, type);
-    if (!existsSync6(dir)) {
+    const dir = join15(storeDir, STORE_LAYOUT2.knowledgeDir, type);
+    if (!existsSync7(dir)) {
       continue;
     }
     let names;
@@ -5402,7 +6087,7 @@ function computeStoreDiskMax(storeDir) {
       if (!name.endsWith(".md")) {
         continue;
       }
-      const parsed = parseKnowledgeId2(readEntryId(join14(dir, name)) ?? "");
+      const parsed = parseKnowledgeId2(readEntryId(join15(dir, name)) ?? "");
       if (parsed === null) {
         continue;
       }
@@ -5485,7 +6170,7 @@ function createStoreCounterCheck(t, drifts) {
 
 // src/services/doctor-store-orphan.ts
 import { readdirSync as readdirSync3 } from "fs";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 import {
   STORES_ROOT_DIR,
   addMountedStore,
@@ -5509,15 +6194,15 @@ function inspectStoreOrphans(globalRoot = resolveGlobalRoot6()) {
     return [];
   }
   const registered = new Set(config.stores.map((s) => s.store_uuid));
-  const storesRoot = join15(globalRoot, STORES_ROOT_DIR);
+  const storesRoot = join16(globalRoot, STORES_ROOT_DIR);
   const orphans = [];
   for (const group of listDir(storesRoot)) {
     if (group === STORE_BY_ALIAS_DIR) {
       continue;
     }
-    const groupDir = join15(storesRoot, group);
+    const groupDir = join16(storesRoot, group);
     for (const mount of listDir(groupDir)) {
-      const dir = join15(groupDir, mount);
+      const dir = join16(groupDir, mount);
       const identity = readStoreIdentity(dir);
       if (identity === null || registered.has(identity.store_uuid)) {
         continue;
@@ -5590,7 +6275,7 @@ import {
 
 // src/services/events-jsonl-gates.ts
 import { promises as fs } from "fs";
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 var EVENTS_JSONL_SIZE_WARN_BYTES = 10 * 1024 * 1024;
 var METRICS_STALE_WARN_MS = 10 * 60 * 1e3;
 var ROTATION_OVERDUE_WARN_MS = 90 * 24 * 60 * 60 * 1e3;
@@ -5605,17 +6290,17 @@ async function inspectEventsJsonlGates(projectRoot, options = {}) {
   let ledgerSizeBytes = 0;
   let ledgerStalenessMs = null;
   try {
-    const stat4 = await fs.stat(eventsPath);
-    ledgerSizeBytes = stat4.size;
-    ledgerStalenessMs = Math.max(0, now.getTime() - stat4.mtimeMs);
+    const stat5 = await fs.stat(eventsPath);
+    ledgerSizeBytes = stat5.size;
+    ledgerStalenessMs = Math.max(0, now.getTime() - stat5.mtimeMs);
   } catch (error) {
     if (!(isNodeError(error) && error.code === "ENOENT")) throw error;
   }
   let metricsStalenessMs = null;
-  if (existsSync7(metricsPath)) {
+  if (existsSync8(metricsPath)) {
     try {
-      const stat4 = await fs.stat(metricsPath);
-      metricsStalenessMs = Math.max(0, now.getTime() - stat4.mtimeMs);
+      const stat5 = await fs.stat(metricsPath);
+      metricsStalenessMs = Math.max(0, now.getTime() - stat5.mtimeMs);
     } catch {
     }
   }
@@ -5654,18 +6339,9 @@ async function inspectEventsJsonlGates(projectRoot, options = {}) {
 }
 
 // src/services/doctor-skill-lints.ts
-import { readdir as readdir2, readFile as readFile9 } from "fs/promises";
-import { join as join16, posix as posix2 } from "path";
-var FABRIC_SKILL_SLUGS = ["fabric-archive", "fabric-review", "fabric-import"];
-var ROUTER_VALID_LEAF_SLUGS = /* @__PURE__ */ new Set([
-  "fabric-archive",
-  "fabric-review",
-  "fabric-import",
-  "fabric-sync",
-  "fabric-store",
-  "fabric-audit",
-  "fabric-connect"
-]);
+import { readdir as readdir3, readFile as readFile10 } from "fs/promises";
+import { join as join17, posix as posix2 } from "path";
+var FABRIC_SKILL_SLUGS = ["fabric-archive", "fabric-review"];
 var SKILL_MD_FRONTMATTER_ROOTS = [".claude/skills", ".codex/skills"];
 var SKILL_FRONTMATTER_KEY_PATTERN = /^([A-Za-z_][A-Za-z0-9_-]*):[ \t]+(.+?)[ \t]*$/u;
 var SKILL_QUOTED_VALUE_LEADS = /* @__PURE__ */ new Set(['"', "'", "[", "{", ">", "|"]);
@@ -5686,7 +6362,7 @@ function issueCheck(name, status, kind, code, message, actionHint, audience) {
 }
 async function listMarkdownFiles(dir) {
   try {
-    return (await readdir2(dir)).filter((name) => name.endsWith(".md"));
+    return (await readdir3(dir)).filter((name) => name.endsWith(".md"));
   } catch {
     return null;
   }
@@ -5694,8 +6370,8 @@ async function listMarkdownFiles(dir) {
 async function inspectSkillRefMirror(projectRoot) {
   const driftedPaths = [];
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const claudeRef = join16(projectRoot, ".claude", "skills", slug, "ref");
-    const codexRef = join16(projectRoot, ".codex", "skills", slug, "ref");
+    const claudeRef = join17(projectRoot, ".claude", "skills", slug, "ref");
+    const codexRef = join17(projectRoot, ".codex", "skills", slug, "ref");
     const [claudeFiles, codexFiles] = await Promise.all([listMarkdownFiles(claudeRef), listMarkdownFiles(codexRef)]);
     if (claudeFiles === null || codexFiles === null) continue;
     const claudeSet = new Set(claudeFiles);
@@ -5712,8 +6388,8 @@ async function inspectSkillRefMirror(projectRoot) {
       let codexBody;
       try {
         [claudeBody, codexBody] = await Promise.all([
-          readFile9(join16(claudeRef, fname), "utf8"),
-          readFile9(join16(codexRef, fname), "utf8")
+          readFile10(join17(claudeRef, fname), "utf8"),
+          readFile10(join17(codexRef, fname), "utf8")
         ]);
       } catch {
         continue;
@@ -5732,10 +6408,10 @@ async function inspectSkillTokenBudget(projectRoot) {
   const overSize = [];
   let highestSeverity = "ok";
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const skillMdPath = join16(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join17(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile9(skillMdPath, "utf8");
+      body = await readFile10(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -5756,10 +6432,10 @@ async function inspectSkillDescription(projectRoot) {
   const CJK_PATTERN = /[\u3400-\u4dbf\u4e00-\u9fff]/u;
   const ASCII_PATTERN = /[a-zA-Z]{2,}/u;
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const skillMdPath = join16(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join17(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile9(skillMdPath, "utf8");
+      body = await readFile10(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -5790,19 +6466,19 @@ async function inspectSkillDescription(projectRoot) {
 async function inspectSkillMdYamlInvalid(projectRoot) {
   const candidates = [];
   for (const rootRel of SKILL_MD_FRONTMATTER_ROOTS) {
-    const rootAbs = join16(projectRoot, rootRel);
+    const rootAbs = join17(projectRoot, rootRel);
     let dirEntries;
     try {
-      dirEntries = await readdir2(rootAbs, { withFileTypes: true });
+      dirEntries = await readdir3(rootAbs, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const dirEntry of dirEntries) {
       if (!dirEntry.isDirectory()) continue;
-      const skillFile = join16(rootAbs, dirEntry.name, "SKILL.md");
+      const skillFile = join17(rootAbs, dirEntry.name, "SKILL.md");
       let raw;
       try {
-        raw = await readFile9(skillFile, "utf8");
+        raw = await readFile10(skillFile, "utf8");
       } catch {
         continue;
       }
@@ -5850,68 +6526,6 @@ function extractSkillFrontmatterLines(raw) {
   }
   return null;
 }
-function extractMarkdownSectionBody(markdown, sectionName) {
-  const lines = markdown.split(/\r?\n/u);
-  const headingRe = /^(#{2,3})\s+(.+?)\s*$/u;
-  let start = -1;
-  for (let i = 0; i < lines.length; i++) {
-    const h = headingRe.exec(lines[i]);
-    if (h && h[2] === sectionName) {
-      start = i + 1;
-      break;
-    }
-  }
-  if (start === -1) return null;
-  const out = [];
-  for (let i = start; i < lines.length; i++) {
-    if (headingRe.test(lines[i])) break;
-    out.push(lines[i]);
-  }
-  return out.join("\n");
-}
-async function inspectRouterChainRef(projectRoot) {
-  const candidatePaths = [
-    join16(projectRoot, ".claude", "skills", "fabric", "SKILL.md"),
-    join16(projectRoot, ".codex", "skills", "fabric", "SKILL.md")
-  ];
-  let body = null;
-  for (const candidate of candidatePaths) {
-    try {
-      body = await readFile9(candidate, "utf8");
-      break;
-    } catch {
-    }
-  }
-  if (body === null) return { status: "ok", unknownRefs: [] };
-  const chainSection = extractMarkdownSectionBody(body, "S_CHAIN");
-  if (chainSection === null) return { status: "ok", unknownRefs: [] };
-  const refs = /* @__PURE__ */ new Set();
-  const tokenRe = /`(fabric-[a-z]+)`/gu;
-  let match;
-  while ((match = tokenRe.exec(chainSection)) !== null) {
-    refs.add(match[1]);
-  }
-  const unknownRefs = [...refs].filter((slug) => !ROUTER_VALID_LEAF_SLUGS.has(slug)).sort();
-  return unknownRefs.length === 0 ? { status: "ok", unknownRefs: [] } : { status: "drift", unknownRefs };
-}
-function createRouterChainRefCheck(t, inspection) {
-  if (inspection.status === "ok") {
-    return okCheck(t("doctor.check.router_chain_ref.name"), t("doctor.check.router_chain_ref.ok"));
-  }
-  const count = inspection.unknownRefs.length;
-  return issueCheck(
-    t("doctor.check.router_chain_ref.name"),
-    "warn",
-    "warning",
-    "router_chain_ref_drift",
-    t(`doctor.check.router_chain_ref.message.${count === 1 ? "singular" : "plural"}`, {
-      count: String(count),
-      list: inspection.unknownRefs.join(", ")
-    }),
-    t("doctor.check.router_chain_ref.remediation"),
-    "maintainer"
-  );
-}
 function createSkillRefMirrorCheck(t, inspection) {
   if (inspection.status === "ok") {
     return okCheck(t("doctor.check.skill_ref_mirror.name"), t("doctor.check.skill_ref_mirror.ok"));
@@ -5986,10 +6600,130 @@ function createSkillMdYamlInvalidCheck(t, inspection) {
   );
 }
 
+// src/services/doctor-retired-references-lint.ts
+import { readdir as readdir4, readFile as readFile11, stat as stat3 } from "fs/promises";
+import { join as join18, posix as posix3, relative as relative2 } from "path";
+var RETIRED_TOKENS = [
+  { token: "fab_plan_context", replacement: "fab_recall", reason: "retrieval collapsed to one lean fab_recall (KT-DEC-0026)" },
+  { token: "fab_get_knowledge_sections", replacement: "fab_recall", reason: "two-step fetch retired (KT-DEC-0026)" },
+  { token: "fab_extract_knowledge", replacement: "fab_propose", reason: "tool renamed to match propose/write semantics (ux-w1-1)" },
+  { token: "hint_broad_budget_chars", replacement: null, reason: "index-only SessionStart sink has no body budget (ux-w1-5)" },
+  { token: "cite_evict_interval", replacement: "cite_recall_nudge", reason: "turn-counter superseded by recall-aware nudge (ux-w1-5)" },
+  { token: "reverse_unarchive_enabled", replacement: null, reason: "never-wired opt-in flag deleted (ux-w1-5)" },
+  { token: "reverse_unarchive_dry_run", replacement: null, reason: "unarchive dryRun comes from the caller, not config (ux-w1-5)" },
+  { token: "doctor --cite-coverage", replacement: "audit cite", reason: "cite audit moved to the audit group (W3-D)" },
+  { token: "doctor --fix-knowledge", replacement: "doctor --fix", reason: "fix-knowledge merged into a single --fix (W3-D)" },
+  { token: "store add", replacement: "store mount", reason: "de-synonymised: add \u2192 mount (W3-E)" },
+  { token: "store route-write", replacement: "store switch-write --scope", reason: "route-write folded into switch-write --scope (W3-E)" },
+  { token: "store re-scope", replacement: "store migrate scope", reason: "scope-rewrite ops grouped under `store migrate` (W3-E)" },
+  { token: "store backfill-scope", replacement: "store migrate backfill", reason: "scope-rewrite ops grouped under `store migrate` (W3-E)" },
+  { token: "store promote", replacement: "store migrate promote", reason: "scope-rewrite ops grouped under `store migrate` (W3-E)" },
+  { token: "fabric scope-explain", replacement: "fabric info scope", reason: "scope-explain command merged into the `info scope` subcommand (W3-F)" },
+  { token: "fabric context", replacement: "fabric inspect", reason: "renamed: `context` of what? \u2192 `inspect` the injection (W3-F / NS-01 \xA71)" },
+  { token: "fabric metrics", replacement: "fabric audit metrics", reason: "top-level metrics retired; reachable as `audit metrics` (W3-F)" },
+  { token: "hint_broad_top_k", replacement: null, reason: "W2-1 retired the broad hard cap; broad_index_backstop is the sole guard (W3-J)" }
+];
+var HOOK_DIRS = [".claude/hooks", ".codex/hooks"];
+var SKILL_DIRS = [".claude/skills", ".codex/skills"];
+var BOOTSTRAP_FILES = ["AGENTS.md", "CLAUDE.md", join18(".fabric", "AGENTS.md")];
+function isCommentLine(line) {
+  const t = line.trim();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+}
+async function walkFiles(dir, exts) {
+  let entries;
+  try {
+    entries = await readdir4(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = join18(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...await walkFiles(full, exts));
+    } else if (exts.some((ext) => e.name.endsWith(ext))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+function scanText(rel, text, skipComments, hits) {
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (skipComments && isCommentLine(line)) continue;
+    for (const { token, replacement } of RETIRED_TOKENS) {
+      if (line.includes(token)) {
+        hits.push({ path: rel, token, line: i + 1, replacement });
+      }
+    }
+  }
+}
+async function inspectRetiredReferences(projectRoot) {
+  const hits = [];
+  let scannedFiles = 0;
+  const toRel = (p) => posix3.normalize(relative2(projectRoot, p).split("\\").join("/"));
+  for (const rel of BOOTSTRAP_FILES) {
+    const abs = join18(projectRoot, rel);
+    try {
+      if ((await stat3(abs)).isFile()) {
+        scannedFiles += 1;
+        scanText(toRel(abs), await readFile11(abs, "utf8"), false, hits);
+      }
+    } catch {
+    }
+  }
+  for (const dir of SKILL_DIRS) {
+    for (const file of await walkFiles(join18(projectRoot, dir), [".md"])) {
+      scannedFiles += 1;
+      try {
+        scanText(toRel(file), await readFile11(file, "utf8"), false, hits);
+      } catch {
+      }
+    }
+  }
+  for (const dir of HOOK_DIRS) {
+    for (const file of await walkFiles(join18(projectRoot, dir), [".cjs"])) {
+      scannedFiles += 1;
+      try {
+        scanText(toRel(file), await readFile11(file, "utf8"), true, hits);
+      } catch {
+      }
+    }
+  }
+  if (scannedFiles === 0) {
+    return { status: "skipped", scannedFiles, hits: [] };
+  }
+  hits.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line);
+  return { status: hits.length > 0 ? "warn" : "ok", scannedFiles, hits };
+}
+function createRetiredReferenceCheck(t, inspection) {
+  const name = t("doctor.check.retired_reference.name");
+  if (inspection.status !== "warn") {
+    return { name, status: "ok", message: t("doctor.check.retired_reference.ok") };
+  }
+  const sample = inspection.hits.slice(0, 5).map(
+    (h) => h.replacement ? `${h.path}:${h.line} \`${h.token}\` \u2192 \`${h.replacement}\`` : `${h.path}:${h.line} \`${h.token}\` (removed)`
+  ).join("; ");
+  return {
+    name,
+    status: "warn",
+    kind: "warning",
+    code: "retired_reference",
+    audience: "maintainer",
+    message: t("doctor.check.retired_reference.message", {
+      count: String(inspection.hits.length),
+      sample
+    }),
+    actionHint: t("doctor.check.retired_reference.remediation")
+  };
+}
+
 // src/services/doctor-hooks-lints.ts
 import { constants } from "fs";
-import { access, readdir as readdir3, readFile as readFile10, stat as stat3 } from "fs/promises";
-import { join as join17, posix as posix3 } from "path";
+import { access, readdir as readdir5, readFile as readFile12, stat as stat4 } from "fs/promises";
+import { join as join19, posix as posix4 } from "path";
 import { Script } from "vm";
 var HOOKS_RUNTIME_CLIENT_DIRS = [
   { client: "claude", dir: ".claude/hooks" },
@@ -6013,7 +6747,7 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizePath(path) {
-  return posix3.normalize(path.split("\\").join("/"));
+  return posix4.normalize(path.split("\\").join("/"));
 }
 function isNodeMissingPathError(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
@@ -6038,27 +6772,27 @@ function isHookWiredForEvent(hooks, event, hookFile) {
 }
 async function readDirectoryFileNames(dir) {
   try {
-    return await readdir3(dir);
+    return await readdir5(dir);
   } catch {
     return null;
   }
 }
 async function isFile(absPath) {
   try {
-    return (await stat3(absPath)).isFile();
+    return (await stat4(absPath)).isFile();
   } catch {
     return false;
   }
 }
 async function inspectHooksWired(projectRoot) {
-  const claudeEntries = await readDirectoryFileNames(join17(projectRoot, ".claude"));
+  const claudeEntries = await readDirectoryFileNames(join19(projectRoot, ".claude"));
   if (claudeEntries === null) {
     return { status: "skipped", missingHooks: [] };
   }
-  const settingsPath = join17(projectRoot, ".claude", "settings.json");
+  const settingsPath = join19(projectRoot, ".claude", "settings.json");
   let parsed;
   try {
-    parsed = JSON.parse(await readFile10(settingsPath, "utf8"));
+    parsed = JSON.parse(await readFile12(settingsPath, "utf8"));
   } catch {
     return { status: "missing-settings", missingHooks: [] };
   }
@@ -6080,12 +6814,12 @@ async function inspectHooksWired(projectRoot) {
   return { status: "incomplete", missingHooks: missing };
 }
 async function inspectHookCacheWritability(projectRoot) {
-  const relPath = posix3.join(".fabric", ".cache");
-  const fabricDir = join17(projectRoot, ".fabric");
-  const cacheDir = join17(projectRoot, ".fabric", ".cache");
+  const relPath = posix4.join(".fabric", ".cache");
+  const fabricDir = join19(projectRoot, ".fabric");
+  const cacheDir = join19(projectRoot, ".fabric", ".cache");
   try {
     try {
-      const cacheStats = await stat3(cacheDir);
+      const cacheStats = await stat4(cacheDir);
       if (!cacheStats.isDirectory()) {
         return {
           writable: false,
@@ -6102,14 +6836,14 @@ async function inspectHookCacheWritability(projectRoot) {
     }
     let parent = fabricDir;
     try {
-      await stat3(fabricDir);
+      await stat4(fabricDir);
     } catch (error) {
       if (!isNodeMissingPathError(error)) {
         throw error;
       }
       parent = projectRoot;
     }
-    const parentStats = await stat3(parent);
+    const parentStats = await stat4(parent);
     if (!parentStats.isDirectory()) {
       return {
         writable: false,
@@ -6131,12 +6865,12 @@ async function inspectHookCacheWritability(projectRoot) {
 async function inspectHooksContentDrift(projectRoot) {
   const hookFilesByBasename = /* @__PURE__ */ new Map();
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join17(projectRoot, dir);
+    const absDir = join19(projectRoot, dir);
     const entries = await readDirectoryFileNames(absDir);
     if (entries === null) continue;
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join17(absDir, name);
+      const abs = join19(absDir, name);
       if (!await isFile(abs)) continue;
       const arr = hookFilesByBasename.get(name) ?? [];
       arr.push({ client, abs });
@@ -6145,13 +6879,13 @@ async function inspectHooksContentDrift(projectRoot) {
   }
   const drifts = [];
   let scanned = 0;
-  for (const [basename3, copies] of hookFilesByBasename) {
+  for (const [basename4, copies] of hookFilesByBasename) {
     if (copies.length < 2) continue;
     scanned += copies.length;
     const hashes = [];
     for (const { client, abs } of copies) {
       try {
-        const body = await readFile10(abs, "utf8");
+        const body = await readFile12(abs, "utf8");
         hashes.push({ client, sha: sha256(body) });
       } catch {
       }
@@ -6160,7 +6894,7 @@ async function inspectHooksContentDrift(projectRoot) {
     const first = hashes[0].sha;
     if (hashes.some((h) => h.sha !== first)) {
       drifts.push({
-        basename: basename3,
+        basename: basename4,
         clients: copies.map((copy) => copy.client),
         hashes
       });
@@ -6173,18 +6907,18 @@ async function inspectHooksRuntime(projectRoot) {
   const issues = [];
   let scanned = 0;
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join17(projectRoot, dir);
+    const absDir = join19(projectRoot, dir);
     const entries = await readDirectoryFileNames(absDir);
     if (entries === null) continue;
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join17(absDir, name);
+      const abs = join19(absDir, name);
       const displayPath = `${dir}/${name}`;
       if (!await isFile(abs)) continue;
       scanned += 1;
       let body;
       try {
-        body = await readFile10(abs, "utf8");
+        body = await readFile12(abs, "utf8");
       } catch (err) {
         issues.push({
           path: displayPath,
@@ -6321,8 +7055,8 @@ function createHookCacheWritabilityCheck(t, inspection) {
 }
 
 // src/services/doctor-bootstrap-lints.ts
-import { access as access2, readFile as readFile11 } from "fs/promises";
-import { join as join18 } from "path";
+import { access as access2, readFile as readFile13 } from "fs/promises";
+import { join as join20 } from "path";
 import {
   BOOTSTRAP_MARKER_BEGIN,
   BOOTSTRAP_MARKER_END,
@@ -6354,17 +7088,17 @@ async function fileExists(path) {
 }
 async function inspectBootstrapAnchor(projectRoot) {
   const [hasAgentsMd, hasClaudeMd] = await Promise.all([
-    fileExists(join18(projectRoot, "AGENTS.md")),
-    fileExists(join18(projectRoot, "CLAUDE.md"))
+    fileExists(join20(projectRoot, "AGENTS.md")),
+    fileExists(join20(projectRoot, "CLAUDE.md"))
   ]);
   return { hasAgentsMd, hasClaudeMd };
 }
 async function inspectL1BootstrapSnapshotDrift(target) {
-  const abs = join18(target, ".fabric", "AGENTS.md");
+  const abs = join20(target, ".fabric", "AGENTS.md");
   const canonical = resolveBootstrapCanonical();
   let onDisk;
   try {
-    onDisk = await readFile11(abs, "utf8");
+    onDisk = await readFile13(abs, "utf8");
   } catch {
     return { status: "missing", canonical, onDisk: null };
   }
@@ -6390,17 +7124,17 @@ function createL1BootstrapSnapshotDriftCheck(t, inspection) {
   );
 }
 async function inspectL2ManagedBlockDrift(target) {
-  const snapshotPath = join18(target, ".fabric", "AGENTS.md");
+  const snapshotPath = join20(target, ".fabric", "AGENTS.md");
   let snapshot;
   try {
-    snapshot = await readFile11(snapshotPath, "utf8");
+    snapshot = await readFile13(snapshotPath, "utf8");
   } catch {
     return { status: "ok", drifted: [] };
   }
-  const projectRulesPath = join18(target, ".fabric", "project-rules.md");
+  const projectRulesPath = join20(target, ".fabric", "project-rules.md");
   let expectedBody = snapshot;
   try {
-    const projectRules = await readFile11(projectRulesPath, "utf8");
+    const projectRules = await readFile13(projectRulesPath, "utf8");
     expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -6409,12 +7143,12 @@ ${projectRules}`;
   const drifted = [];
   let anyManagedBlockFound = false;
   const blockTargets = [
-    join18(target, "AGENTS.md")
+    join20(target, "AGENTS.md")
   ];
   for (const abs of blockTargets) {
     let content;
     try {
-      content = await readFile11(abs, "utf8");
+      content = await readFile13(abs, "utf8");
     } catch {
       continue;
     }
@@ -6437,9 +7171,9 @@ ${projectRules}`;
       drifted.push({ path: abs, expected: expectedBody, actual: body });
     }
   }
-  const claudeMdPath = join18(target, "CLAUDE.md");
+  const claudeMdPath = join20(target, "CLAUDE.md");
   try {
-    const claudeContent = await readFile11(claudeMdPath, "utf8");
+    const claudeContent = await readFile13(claudeMdPath, "utf8");
     anyManagedBlockFound = true;
     const lines = claudeContent.split(/\r?\n/u);
     const hasAtImport = lines.some((line) => line.trim() === "@.fabric/AGENTS.md");
@@ -6507,7 +7241,7 @@ import { appendFile as appendFile3 } from "fs/promises";
 import { minimatch as minimatch2 } from "minimatch";
 
 // src/services/cite-rollup.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile14 } from "fs/promises";
 import { createLedgerWriteQueue as createLedgerWriteQueue3 } from "@fenglimg/fabric-shared/node/atomic-write";
 var citeRollupQueue = createLedgerWriteQueue3();
 async function appendCiteRollupRow(projectRoot, row) {
@@ -6519,7 +7253,7 @@ async function readCiteRollup(projectRoot) {
   const path = getCiteRollupPath(projectRoot);
   let raw;
   try {
-    raw = await readFile12(path, "utf8");
+    raw = await readFile14(path, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") return [];
     throw error;
@@ -7527,13 +8261,13 @@ var DEFAULT_UNDERSEED_NODE_THRESHOLD = 10;
 var SESSION_HINTS_STALE_DAYS = 7;
 var SESSION_HINTS_FILE_PREFIX = "session-hints-";
 var SESSION_HINTS_FILE_SUFFIX = ".json";
-var EDIT_COUNTER_FILE_REL = posix4.join(".fabric", ".cache", "edit-counter");
-var HINT_SILENCE_COUNTER_FILE_REL = posix4.join(
+var EDIT_COUNTER_FILE_REL = posix5.join(".fabric", ".cache", "edit-counter");
+var HINT_SILENCE_COUNTER_FILE_REL = posix5.join(
   ".fabric",
   ".cache",
   "hint-silence-counter"
 );
-var MS_PER_DAY3 = 24 * 60 * 60 * 1e3;
+var MS_PER_DAY4 = 24 * 60 * 60 * 1e3;
 var KNOWLEDGE_CANONICAL_TYPE_DIRS = [
   "decisions",
   "pitfalls",
@@ -7581,7 +8315,8 @@ async function runDoctorReport(target) {
     l2ManagedBlockDrift,
     skillRefMirror,
     skillTokenBudget,
-    skillDescription
+    skillDescription,
+    retiredReferences
   ] = await Promise.all([
     inspectForensic(projectRoot),
     // v2.2 W5 R4 (agents.meta decolo): `inspectMeta` (read co-location
@@ -7601,7 +8336,10 @@ async function runDoctorReport(target) {
     inspectL2ManagedBlockDrift(projectRoot),
     inspectSkillRefMirror(projectRoot),
     inspectSkillTokenBudget(projectRoot),
-    inspectSkillDescription(projectRoot)
+    inspectSkillDescription(projectRoot),
+    // ux-w2-2: registry-driven stale-pointer scan over the agent-consumed
+    // surface (bootstrap + SKILL.md + installed hooks).
+    inspectRetiredReferences(projectRoot)
   ]);
   const citeGoodhart = await inspectCiteGoodhart(projectRoot);
   const storeKnowledgeSummaries = await collectStoreKnowledgeSummaries(projectRoot);
@@ -7622,6 +8360,8 @@ async function runDoctorReport(target) {
   const lintNow = Date.now();
   const lastActiveIndex = await buildLastActiveIndex(projectRoot);
   const knowledgeAge = await inspectStoreKnowledgeAge(projectRoot, lintNow, lastActiveIndex);
+  const knowledgePromotion = await inspectStoreKnowledgePromotion(projectRoot);
+  const broadReviewRecheck = await inspectStoreBroadReviewRecheck(projectRoot, lintNow);
   const preexistingRootFiles = await inspectPreexistingRootFiles(projectRoot);
   const underseedThreshold = await readUnderseedThresholdFromConfig(projectRoot);
   const underseeded = {
@@ -7633,7 +8373,6 @@ async function runDoctorReport(target) {
   const hookCacheWritability = await inspectHookCacheWritability(projectRoot);
   const staleServeLock = inspectStaleServeLock(projectRoot, lintNow);
   const skillMdYamlInvalid = await inspectSkillMdYamlInvalid(projectRoot);
-  const routerChainRef = await inspectRouterChainRef(projectRoot);
   const onboardCoverage = await inspectOnboardCoverage(projectRoot);
   const [hooksWired, hooksRuntime, hooksContentDrift] = await Promise.all([
     inspectHooksWired(projectRoot),
@@ -7644,7 +8383,7 @@ async function runDoctorReport(target) {
   const globalCliVersion = process.env.VITEST === "true" ? { status: "ok", version: "test-skipped" } : inspectGlobalCliVersion();
   const targetFiles = Object.fromEntries(
     await Promise.all(
-      TARGET_FILE_PATHS.map(async (path) => [path, await pathExists(join19(projectRoot, path))])
+      TARGET_FILE_PATHS.map(async (path) => [path, await pathExists(join21(projectRoot, path))])
     )
   );
   const checks = [
@@ -7683,6 +8422,8 @@ async function runDoctorReport(target) {
     createSkillRefMirrorCheck(t, skillRefMirror),
     createSkillTokenBudgetCheck(t, skillTokenBudget),
     createSkillDescriptionCheck(t, skillDescription),
+    // ux-w2-2: retired-reference (stale-pointer) lint — registry-driven.
+    createRetiredReferenceCheck(t, retiredReferences),
     createCiteGoodhartCheck(t, citeGoodhart),
     createDraftBacklogCheck(t, draftBacklog),
     createKnowledgeTagsEmptyCheck(t, knowledgeTagsEmpty),
@@ -7710,9 +8451,6 @@ async function runDoctorReport(target) {
     // rc.12 lint #29: skill_md_yaml_invalid. Warning kind — surfaces
     // SKILL.md frontmatter that Codex CLI silently drops at load.
     createSkillMdYamlInvalidCheck(t, skillMdYamlInvalid),
-    // B2 skill-router (A4): S_CHAIN reference backstop. Warning kind — flags an
-    // S_CHAIN `fabric-*` reference to a leaf no longer in the install set.
-    createRouterChainRefCheck(t, routerChainRef),
     // v2.0.0-rc.23 TASK-014 (F8c): Onboard coverage advisory. Info kind.
     // Surfaces uncovered S5 onboard slots and recommends /fabric-archive
     // first-run phase. Sits adjacent to Skill markdown YAML — both are
@@ -7764,6 +8502,11 @@ async function runDoctorReport(target) {
     // thresholds 90/30/14d per maturity tier (KT-DEC-0008).
     createOrphanDemoteCheck(t, knowledgeAge.orphanDemote),
     createStaleArchiveCheck(t, knowledgeAge.staleArchive),
+    // v2.2 C1: knowledge promotion candidate (info kind — opportunity, not defect).
+    createPromotionCandidateCheck(t, knowledgePromotion),
+    // v2.2 C1: broad review-recheck nudge (info kind — broad's review-clock
+    // counterpart to the usage-age decay it is exempt from).
+    createBroadReviewRecheckCheck(t, broadReviewRecheck),
     // project-scope binding backfill lint — a store bound as the write target
     // but with no project_id / active_project parks the project axis. The
     // fresh-install hole is sealed in store.stage.ts; this covers existing repos
@@ -7844,7 +8587,7 @@ async function runDoctorFix(target) {
   const fixed = [];
   const ledgerWarnings = [];
   if (before.fixable_errors.some((issue) => issue.code === "bootstrap_snapshot_drift")) {
-    const snapshotPath = join19(projectRoot, ".fabric", "AGENTS.md");
+    const snapshotPath = join21(projectRoot, ".fabric", "AGENTS.md");
     await ensureParentDirectory(snapshotPath);
     await atomicWriteText4(snapshotPath, resolveBootstrapCanonical2());
     fixed.push(findIssue(before.fixable_errors, "bootstrap_snapshot_drift"));
@@ -7917,9 +8660,9 @@ 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 = join19(projectRoot, ".fabric", ".serve.lock");
+      const lockFilePath = join21(projectRoot, ".fabric", ".serve.lock");
       try {
-        await unlink3(lockFilePath);
+        await unlink4(lockFilePath);
       } catch (err) {
         const errno = err;
         if (errno.code !== "ENOENT") throw err;
@@ -8034,10 +8777,10 @@ function createApplyLintMessage(succeeded, failed, manualErrorCount) {
 }
 async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   const detail = `deleted (${candidate.age_days}d old)`;
-  const absPath = join19(projectRoot, candidate.path);
+  const absPath = join21(projectRoot, candidate.path);
   try {
-    const { unlink: unlink4 } = await import("fs/promises");
-    await unlink4(absPath);
+    const { unlink: unlink5 } = await import("fs/promises");
+    await unlink5(absPath);
     return {
       kind: "knowledge_session_hints_stale_cleanup",
       path: candidate.path,
@@ -8059,9 +8802,9 @@ function truncateErrorMessage(error) {
   return raw.length > 240 ? `${raw.slice(0, 237)}...` : raw;
 }
 async function inspectForensic(projectRoot) {
-  const path = join19(projectRoot, ".fabric", "forensic.json");
+  const path = join21(projectRoot, ".fabric", "forensic.json");
   try {
-    const parsed = forensicReportSchema.parse(JSON.parse(await readFile14(path, "utf8")));
+    const parsed = forensicReportSchema.parse(JSON.parse(await readFile16(path, "utf8")));
     return { present: true, valid: true, report: parsed };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -8091,7 +8834,7 @@ async function inspectEventLedger(projectRoot) {
   try {
     await access4(path, constants2.W_OK);
     const { warnings } = await readEventLedger(projectRoot);
-    const raw = await readFile14(path, "utf8");
+    const raw = await readFile16(path, "utf8");
     const invalidLine = raw.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).find((line) => !isValidJsonLine(line));
     const partialWarning = warnings.find((w) => w.kind === "partial_write_at_tail");
     const schemaVersionSamples = [];
@@ -8636,7 +9379,7 @@ async function inspectPreexistingRootFiles(projectRoot) {
   const candidates = ["CLAUDE.md", "AGENTS.md"];
   const detected = [];
   for (const name of candidates) {
-    if (await pathExists(join19(projectRoot, name))) {
+    if (await pathExists(join21(projectRoot, name))) {
       detected.push(name);
     }
   }
@@ -8721,7 +9464,7 @@ async function buildLastActiveIndex(projectRoot) {
   return map;
 }
 async function inspectSessionHintsStale(projectRoot, now) {
-  const cacheDir = join19(projectRoot, ".fabric", ".cache");
+  const cacheDir = join21(projectRoot, ".fabric", ".cache");
   let entries;
   try {
     entries = await readdirAsync(cacheDir, { withFileTypes: true });
@@ -8733,17 +9476,17 @@ async 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 = join19(cacheDir, entry.name);
+    const absPath = join21(cacheDir, entry.name);
     let mtimeMs = 0;
     try {
       mtimeMs = (await statAsync(absPath)).mtimeMs;
     } catch {
       continue;
     }
-    const ageDays = Math.floor((now - mtimeMs) / MS_PER_DAY3);
+    const ageDays = Math.floor((now - mtimeMs) / MS_PER_DAY4);
     if (ageDays < SESSION_HINTS_STALE_DAYS) continue;
     candidates.push({
-      path: posix4.join(".fabric", ".cache", entry.name),
+      path: posix5.join(".fabric", ".cache", entry.name),
       age_days: ageDays
     });
   }
@@ -8765,9 +9508,9 @@ function inspectStaleServeLock(projectRoot, now) {
   };
 }
 async function readUnderseedThresholdFromConfig(projectRoot) {
-  const configPath = join19(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join21(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile14(configPath, "utf8");
+    const raw = await readFile16(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.underseed_node_threshold;
@@ -8841,7 +9584,7 @@ function createStaleServeLockCheck(t, inspection) {
       })
     );
   }
-  const days = Math.floor(inspection.ageMs / MS_PER_DAY3);
+  const days = Math.floor(inspection.ageMs / MS_PER_DAY4);
   const hours = Math.floor(inspection.ageMs / (60 * 60 * 1e3));
   const acquiredAgo = days >= 1 ? t(`doctor.check.stale_serve_lock.age.day.${days === 1 ? "singular" : "plural"}`, {
     count: String(days)
@@ -8883,10 +9626,10 @@ async function inspectOnboardCoverage(projectRoot) {
   return { filled, missing, opted_out: optedOut };
 }
 async function readOnboardOptedOut(projectRoot) {
-  const path = join19(projectRoot, ".fabric", "fabric-config.json");
+  const path = join21(projectRoot, ".fabric", "fabric-config.json");
   let raw;
   try {
-    raw = await readFile14(path, "utf8");
+    raw = await readFile16(path, "utf8");
   } catch {
     return [];
   }
@@ -8971,7 +9714,7 @@ async function* iterateCanonicalFilenames(projectRoot) {
     if (!KNOWLEDGE_CANONICAL_TYPE_DIRS.includes(entry.type)) {
       continue;
     }
-    const filename = posix4.basename(normalizePath2(entry.file));
+    const filename = posix5.basename(normalizePath2(entry.file));
     const parsed = parseStableIdFromCanonicalFilename(filename);
     if (parsed === null) {
       continue;
@@ -8988,22 +9731,22 @@ async function* iterateCanonicalFilenames(projectRoot) {
   }
 }
 async function rewriteThreeEndManagedBlocks(projectRoot) {
-  const snapshotPath = join19(projectRoot, ".fabric", "AGENTS.md");
+  const snapshotPath = join21(projectRoot, ".fabric", "AGENTS.md");
   if (!await pathExists(snapshotPath)) {
     return;
   }
   let snapshot;
   try {
-    snapshot = await readFile14(snapshotPath, "utf8");
+    snapshot = await readFile16(snapshotPath, "utf8");
   } catch {
     return;
   }
-  const projectRulesPath = join19(projectRoot, ".fabric", "project-rules.md");
+  const projectRulesPath = join21(projectRoot, ".fabric", "project-rules.md");
   const hasProjectRules = await pathExists(projectRulesPath);
   let expectedBody = snapshot;
   if (hasProjectRules) {
     try {
-      const projectRules = await readFile14(projectRulesPath, "utf8");
+      const projectRules = await readFile16(projectRulesPath, "utf8");
       expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -9014,7 +9757,7 @@ ${projectRules}`;
 ${expectedBody}
 ${BOOTSTRAP_MARKER_END2}`;
   const blockTargets = [
-    join19(projectRoot, "AGENTS.md")
+    join21(projectRoot, "AGENTS.md")
   ];
   for (const abs of blockTargets) {
     if (!await pathExists(abs)) {
@@ -9022,7 +9765,7 @@ ${BOOTSTRAP_MARKER_END2}`;
     }
     let existing;
     try {
-      existing = await readFile14(abs, "utf8");
+      existing = await readFile16(abs, "utf8");
     } catch {
       continue;
     }
@@ -9047,11 +9790,11 @@ ${managedBlock}
     }
     await atomicWriteText4(abs, next);
   }
-  const claudeMdPath = join19(projectRoot, "CLAUDE.md");
+  const claudeMdPath = join21(projectRoot, "CLAUDE.md");
   if (await pathExists(claudeMdPath)) {
     let claudeContent;
     try {
-      claudeContent = await readFile14(claudeMdPath, "utf8");
+      claudeContent = await readFile16(claudeMdPath, "utf8");
     } catch {
       return;
     }
@@ -9097,7 +9840,7 @@ function normalizeTarget(targetInput) {
   return isAbsolute2(targetInput) ? targetInput : resolve3(process.cwd(), targetInput);
 }
 function normalizePath2(path) {
-  return posix4.normalize(path.split("\\").join("/"));
+  return posix5.normalize(path.split("\\").join("/"));
 }
 async function collectEntryPoints(root) {
   let rootStat;
@@ -9117,7 +9860,7 @@ async function collectEntryPoints(root) {
       continue;
     }
     for (const entry of await readdirAsync(current, { withFileTypes: true })) {
-      const absolutePath = join19(current, entry.name);
+      const absolutePath = join21(current, entry.name);
       const relativePath = normalizePath2(absolutePath.slice(root.length + 1));
       if (relativePath.length === 0) {
         continue;
@@ -9144,8 +9887,8 @@ function getEntryPointReason(relativePath) {
   if (!SCRIPT_EXTENSIONS.has(extension)) {
     return null;
   }
-  const directory = posix4.dirname(relativePath);
-  const fileName = posix4.basename(relativePath);
+  const directory = posix5.dirname(relativePath);
+  const fileName = posix5.basename(relativePath);
   const fileBase = fileName.slice(0, Math.max(fileName.lastIndexOf("."), 0));
   if (directory === "assets/scripts" || directory === "scripts") {
     return "top-level script";
@@ -9193,7 +9936,7 @@ async function enrichDescriptions(projectRoot, opts = {}) {
     scanned += 1;
     let source;
     try {
-      source = await readFile14(absPath, "utf8");
+      source = await readFile16(absPath, "utf8");
     } catch {
       continue;
     }
@@ -9290,88 +10033,6 @@ function yamlQuoteIfNeeded(value) {
   return value;
 }
 
-// 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;
@@ -9412,6 +10073,91 @@ async function runDoctorConflictLint(projectRoot, opts = {}) {
   };
 }
 
+// src/services/why-not-surfaced.ts
+import { readFile as readFile17 } from "fs/promises";
+import { basename as basename3, join as join22 } from "path";
+import {
+  buildStoreResolveInput as buildStoreResolveInput7,
+  createStoreResolver as createStoreResolver7,
+  loadProjectConfig as loadProjectConfig4,
+  readKnowledgeAcrossStores as readKnowledgeAcrossStores4,
+  resolveGlobalRoot as resolveGlobalRoot7,
+  scopeRoot as scopeRoot3,
+  storeRelativePathForMount as storeRelativePathForMount6
+} from "@fenglimg/fabric-shared";
+var SEMANTIC_SCOPE_LINE3 = /^semantic_scope:\s*"?([^"\n]+?)"?\s*$/mu;
+var RELEVANCE_SCOPE_LINE = /^relevance_scope:\s*"?(broad|narrow)"?\s*$/mu;
+function toLocalId3(query) {
+  const i = query.indexOf(":");
+  return i === -1 ? query : query.slice(i + 1);
+}
+function fileMatchesId(file, localId) {
+  const base = basename3(file);
+  return base === `${localId}.md` || base.startsWith(`${localId}--`);
+}
+async function explainWhyNotSurfaced(projectRoot, query) {
+  const localId = toLocalId3(query.trim());
+  const base = {
+    query,
+    localId,
+    verdict: "not_found",
+    storeAlias: null,
+    storeBound: null,
+    semanticScope: null,
+    activeProject: null,
+    relevanceScope: null
+  };
+  const input = buildStoreResolveInput7(projectRoot);
+  if (input === null) {
+    return base;
+  }
+  const globalRoot = resolveGlobalRoot7();
+  const allStores = input.mountedStores.map((s) => ({
+    store_uuid: s.store_uuid,
+    alias: s.alias,
+    dir: join22(globalRoot, storeRelativePathForMount6(s))
+  }));
+  const refs = await readKnowledgeAcrossStores4(allStores);
+  const candidate = refs.find((ref) => fileMatchesId(ref.file, localId));
+  if (candidate === void 0) {
+    return base;
+  }
+  let source;
+  try {
+    source = await readFile17(candidate.file, "utf8");
+  } catch {
+    return base;
+  }
+  if (deriveRuleIdentity(candidate.file, source, void 0).stableId !== localId) {
+    return base;
+  }
+  const semanticScope = SEMANTIC_SCOPE_LINE3.exec(source)?.[1] ?? null;
+  const relevanceScope = RELEVANCE_SCOPE_LINE.exec(source)?.[1] ?? "broad";
+  const activeProject = loadProjectConfig4(projectRoot)?.active_project ?? null;
+  const boundUuids = new Set(
+    createStoreResolver7().resolveReadSet(input).stores.map((s) => s.store_uuid)
+  );
+  const storeBound = boundUuids.has(candidate.store_uuid);
+  const found = {
+    ...base,
+    storeAlias: candidate.alias,
+    storeBound,
+    semanticScope,
+    activeProject,
+    relevanceScope
+  };
+  if (!storeBound) {
+    return { ...found, verdict: "store_unbound" };
+  }
+  if (semanticScope !== null && scopeRoot3(semanticScope) === "project" && activeProject !== null && semanticScope !== `project:${activeProject}`) {
+    return { ...found, verdict: "project_mismatch" };
+  }
+  if (relevanceScope === "narrow") {
+    return { ...found, verdict: "narrow_timing" };
+  }
+  return { ...found, verdict: "should_surface" };
+}
+
 // src/services/summary-cold-eval.ts
 var COLD_EVAL_RUBRIC = [
   "You are a ZERO-CONTEXT judge. You are shown ONLY a one-line knowledge summary \u2014",
@@ -9465,8 +10211,8 @@ import { agentsMetaSchema as agentsMetaSchema3 } from "@fenglimg/fabric-shared";
 import { IOFabricError as IOFabricError2, RuleError } from "@fenglimg/fabric-shared/errors";
 
 // src/services/read-ledger.ts
-import { randomUUID as randomUUID6 } from "crypto";
-import { access as access5, copyFile, readFile as readFile15, rm } from "fs/promises";
+import { randomUUID as randomUUID7 } from "crypto";
+import { access as access5, copyFile, readFile as readFile18, rm } from "fs/promises";
 import { ledgerEntrySchema } from "@fenglimg/fabric-shared";
 async function resolveLedgerPaths(projectRoot) {
   const primaryPath = getLedgerPath(projectRoot);
@@ -9494,7 +10240,7 @@ async function readLegacyLedger(projectRoot) {
   const { readPath } = await resolveLedgerPaths(projectRoot);
   let raw;
   try {
-    raw = await readFile15(readPath, "utf8");
+    raw = await readFile18(readPath, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") {
       return [];
@@ -9749,26 +10495,27 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync8(join20(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync8(join20(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync9(join23(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync9(join23(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 mounted stores via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
 }
 var FABRIC_SERVER_INSTRUCTIONS = [
   "Fabric is a cross-client knowledge layer: durable team/personal decisions, pitfalls, guidelines, models, and processes this server surfaces so you do not re-learn them each session.",
   "",
+  "AGENT-DIRECT tools \u2014 call these yourself, inline, as you work:",
   "Retrieval \u2014 do this BEFORE you edit code or commit to a decision:",
-  "- Call `fab_recall(paths)` with the files you are about to touch. It returns the relevant KB DESCRIPTIONS (`candidates[]`) plus a READ-PATH index (`paths[]`: one on-disk knowledge file per surfaced candidate).",
-  "- It does NOT return bodies. To load an entry's full content, Read the file at its `paths[].path` (native file read) \u2014 that is observed as a `knowledge_body_read`. Reading on demand keeps the description index lean; a needed body is one cheap Read away.",
+  "- `fab_recall(paths)` \u2014 one-shot KB recall for the files you are about to touch. Returns a single ranked `entries[]` \u2014 each entry carries its DESCRIPTION, a `read_path` (the on-disk knowledge file), `rank` (1 = most relevant), and `body_in_context:true` when the body is already in context from SessionStart.",
+  "- It does NOT return bodies. To load an entry's full content, Read its `read_path` (native file read) \u2014 that is observed as a `knowledge_body_read`. Reading on demand keeps the index lean; a needed body is one cheap Read away.",
   "",
-  "Tools:",
-  "- `fab_recall` \u2014 one-shot KB recall: descriptions + read paths for the given files.",
-  "- `fab_extract_knowledge` \u2014 extract structured knowledge from text you supply.",
+  "SKILL-DRIVEN tools \u2014 invoked by the Fabric skills (fabric-archive / fabric-review) at the right lifecycle moment, not called ad-hoc:",
+  "- `fab_propose` \u2014 propose/persist a pending knowledge entry into the write-target store for later review.",
   "- `fab_archive_scan` \u2014 scan recent work for archive-worthy knowledge candidates.",
-  "- `fab_review` \u2014 review and triage pending knowledge entries.",
+  "- `fab_pending` \u2014 read-only browse/search of pending + canonical knowledge (list / search).",
+  "- `fab_review` \u2014 write-only triage of pending knowledge entries (approve / reject / modify / defer).",
   "",
   "Conventions:",
-  "- Candidate lists are ranked best-first (content relevance) and bounded; `omitted_candidate_count > 0` means more exist \u2014 narrow your intent to surface them.",
+  "- Candidate lists are ranked best-first (content relevance) and bounded; a non-empty `dropped[]` (each entry `{ id, reason }`, reason `retrieval_budget` | `payload_budget`) means more exist \u2014 narrow your intent to surface them.",
   "- Pass the client `session_id` to `fab_recall` so cross-session knowledge-debt tracking stays accurate.",
   "- Cite the KB id you applied or dismissed before edits, per the project's cite policy."
 ].join("\n");
@@ -9776,7 +10523,7 @@ function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.2.0-rc.9"
+      version: "2.3.0-rc.1"
     },
     {
       instructions: FABRIC_SERVER_INSTRUCTIONS
@@ -9786,6 +10533,7 @@ function createFabricServer(tracker) {
   registerArchiveScan(server, tracker);
   registerExtractKnowledge(server, tracker);
   registerReview(server, tracker);
+  registerPending(server, tracker);
   server.registerResource(
     "bootstrap README",
     AGENTS_MD_RESOURCE_URI,
@@ -9795,10 +10543,10 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path = join20(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path = join23(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
-      if (existsSync8(path)) {
-        text = await readFile16(path, "utf8");
+      if (existsSync9(path)) {
+        text = await readFile19(path, "utf8");
       }
       return {
         contents: [
@@ -9896,6 +10644,7 @@ export {
   LEGACY_LEDGER_PATH,
   METRICS_LEDGER_PATH,
   METRIC_COUNTER_NAMES,
+  RETIRED_TOKENS,
   appendEventLedgerEvent,
   buildAlwaysActiveBodies,
   buildColdEvalBatch,
@@ -9908,6 +10657,7 @@ export {
   detectUnboundProject,
   drainCounters,
   enrichDescriptions,
+  explainWhyNotSurfaced,
   extractKnowledge,
   findConflictCandidates,
   flushAndSyncEventLedger,
@@ -9917,6 +10667,7 @@ export {
   getLedgerPath,
   getLegacyLedgerPath,
   getMetricsLedgerPath,
+  inspectRetiredReferences,
   lintConflicts,
   loadConflictEntries,
   pairSimilarity,
@@ -9929,6 +10680,7 @@ export {
   rehydrateAgentsMetaAt,
   resolveLedgerPaths,
   reviewKnowledge,
+  reviewPending,
   runDoctorApplyLint,
   runDoctorArchiveHistory,
   runDoctorCiteCoverage,