@fenglimg/fabric-server 2.0.0-rc.37 → 2.0.0-rc.38

package/dist/index.d.ts

@@ -132,6 +132,10 @@ type CiteCoverageReport = {
         recalled_unverified: number;
         expected_but_missed: number;
         total_turns: number;
+        cite_compliance_rate?: number | null;
+        compliant_cites?: number;
+        noncompliant_cites?: number;
+        uncorrelatable_edits?: number;
     };
     per_client?: Record<string, Partial<CiteCoverageReport["metrics"]>>;
     dismissed_reason_histogram?: Record<string, number>;
@@ -341,8 +345,6 @@ type PlanContextInput = {
 };
 type RequirementProfile = {
     target_path: string;
-    path_segments: string[];
-    extension: string;
     known_tech: string[];
     user_intent: string;
     detected_entities: string[];
@@ -350,23 +352,21 @@ type RequirementProfile = {
 type PlanContextEntry = {
     path: string;
     requirement_profile: RequirementProfile;
-    description_index: RuleDescriptionIndexItem[];
+};
+type PreflightDiagnostic = {
+    code: "missing_description" | "empty_shell_suppressed";
+    severity: "warn";
+    message: string;
+    stable_ids?: string[];
+    path?: string;
 };
 type PlanContextResult = {
     revision_hash: string;
     stale: boolean;
     selection_token: string;
     entries: PlanContextEntry[];
-    shared: {
-        description_index: RuleDescriptionIndexItem[];
-        preflight_diagnostics: Array<{
-            code: "missing_description";
-            severity: "warn";
-            message: string;
-            stable_ids?: string[];
-            path?: string;
-        }>;
-    };
+    candidates: RuleDescriptionIndexItem[];
+    preflight_diagnostics: PreflightDiagnostic[];
     auto_healed?: boolean;
     previous_revision_hash?: string;
     redirects?: Record<string, string>;

package/dist/index.js

@@ -2395,10 +2395,6 @@ import {
 } 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 { minimatch as minimatch2 } from "minimatch";
-import { deriveAgentsMetaLayer as deriveAgentsMetaLayer3 } from "@fenglimg/fabric-shared";
-
 // src/services/get-knowledge.ts
 import { readFile as readFile6 } from "fs/promises";
 import { join as join8 } from "path";
@@ -2613,19 +2609,13 @@ async function planContext(projectRoot, input) {
     nowMs: Date.now(),
     targetPaths: input.target_paths ?? dedupePaths(input.paths)
   };
-  const allDescriptions = buildDescriptionIndex(meta, scoringContext);
-  const relevanceTargetPaths = input.target_paths ?? uniquePaths;
-  const entries = uniquePaths.map((path2) => {
-    const profile = buildRequirementProfile(path2, input);
-    const descriptionIndex = allDescriptions.filter((item) => shouldIncludeIndexItemForPath(item, meta, path2)).filter((item) => shouldIncludeByRelevance(item, relevanceTargetPaths));
-    return {
-      path: path2,
-      requirement_profile: profile,
-      description_index: descriptionIndex
-    };
-  });
-  const sharedDescriptionIndex = dedupeDescriptionIndex(entries.flatMap((entry) => entry.description_index));
-  const sharedStableIds = sharedDescriptionIndex.map((item) => item.stable_id);
+  const { items: builtItems, suppressedStableIds } = buildDescriptionIndex(meta, scoringContext);
+  const candidates = dedupeDescriptionIndex(builtItems);
+  const entries = uniquePaths.map((path2) => ({
+    path: path2,
+    requirement_profile: buildRequirementProfile(path2, input)
+  }));
+  const sharedStableIds = candidates.map((item) => item.stable_id);
   const ttlMs = readSelectionTokenTtlMs(projectRoot) ?? SELECTION_TOKEN_TTL_DEFAULT_MS;
   const selectionToken = createSelectionToken(meta.revision, uniquePaths, [], sharedStableIds, Date.now(), ttlMs);
   let redirects;
@@ -2642,10 +2632,8 @@ async function planContext(projectRoot, input) {
     stale,
     selection_token: selectionToken,
     entries,
-    shared: {
-      description_index: sharedDescriptionIndex,
-      preflight_diagnostics: buildPreflightDiagnostics(meta)
-    },
+    candidates,
+    preflight_diagnostics: buildPreflightDiagnostics(meta, suppressedStableIds),
     // v2.0.0-rc.22 Scope D T-D2 + rc.23 TASK-005 (a-B): surface auto-heal pair
     // only when a heal actually fired (either revision-drift heal in
     // loadActiveMetaOrStale or description-undefined heal driven from here).
@@ -2663,13 +2651,13 @@ async function planContext(projectRoot, input) {
       event_type: "knowledge_context_planned",
       target_paths: uniquePaths,
       required_stable_ids: [],
-      ai_selectable_stable_ids: sharedDescriptionIndex.map((item) => item.stable_id),
+      ai_selectable_stable_ids: sharedStableIds,
       final_stable_ids: [],
       selection_token: selectionToken,
       client_hash: input.client_hash,
       intent: input.intent,
       known_tech: input.known_tech,
-      diagnostics: result.shared.preflight_diagnostics,
+      diagnostics: result.preflight_diagnostics,
       correlation_id: input.correlation_id,
       session_id: input.session_id
     });
@@ -2721,42 +2709,31 @@ function buildRequirementProfile(path2, input) {
   ]);
   return {
     target_path: normalizedPath,
-    path_segments: normalizedPath.split("/").filter(Boolean),
-    extension: extensionMatch?.[1] ?? "",
     known_tech: knownTech,
     user_intent: input.intent ?? "",
     detected_entities: input.detected_entities?.[normalizedPath] ?? input.detected_entities?.[path2] ?? []
   };
 }
 function buildDescriptionIndex(meta, scoringContext) {
-  return Object.entries(meta.nodes).flatMap(([nodeId, node]) => {
-    const level = deriveAgentsMetaLayer3(node.file);
-    const description = node.description ?? descriptionFromLegacyActivation(node.activation?.description);
-    if (description === void 0) {
+  const suppressedStableIds = [];
+  const items = Object.entries(meta.nodes).flatMap(([nodeId, node]) => {
+    const baseDescription = node.description ?? descriptionFromLegacyActivation(node.activation?.description);
+    if (baseDescription === void 0) {
+      return [];
+    }
+    const stableId = node.stable_id ?? nodeId;
+    if (isEmptyShellDescription(baseDescription, stableId)) {
+      suppressedStableIds.push(stableId);
       return [];
     }
     const inferredLayer = inferKnowledgeLayerFromContentRef(node.content_ref ?? node.file);
-    return [{
-      stable_id: node.stable_id ?? nodeId,
-      level,
-      required: false,
-      selectable: false,
-      description,
-      type: description.knowledge_type,
-      maturity: description.maturity,
-      layer: description.knowledge_layer ?? inferredLayer,
-      layer_reason: description.layer_reason,
-      // v2.0-rc.5 C3 (TASK-012): surface relevance fields at the top level
-      // so the per-entry filter + downstream MCP clients can read them
-      // without reaching into description.*. Defaults (broad + []) are
-      // applied at the meta-builder layer; we just pass them through here.
-      relevance_scope: description.relevance_scope,
-      relevance_paths: description.relevance_paths
-    }];
+    const description = baseDescription.knowledge_layer === void 0 && inferredLayer !== void 0 ? { ...baseDescription, knowledge_layer: inferredLayer } : baseDescription;
+    return [{ stable_id: stableId, description }];
   }).sort((left, right) => compareDescriptionIndexItems(left, right, scoringContext));
+  return { items, suppressedStableIds };
 }
-function shouldIncludeByRelevance(_item, _targetPaths) {
-  return true;
+function isEmptyShellDescription(description, stableId) {
+  return description.summary === stableId && description.intent_clues.length === 0 && description.tech_stack.length === 0 && description.impact.length === 0;
 }
 function inferKnowledgeLayerFromContentRef(contentRef) {
   if (contentRef === void 0) {
@@ -2782,25 +2759,31 @@ function descriptionFromLegacyActivation(summary) {
     must_read_if: summary
   };
 }
-function shouldIncludeIndexItemForPath(_item, _meta, _path) {
-  return true;
-}
 function hasUndefinedDescription(meta) {
   return Object.values(meta.nodes).some(
     (node) => node.description === void 0 && node.activation?.description === void 0
   );
 }
-function buildPreflightDiagnostics(meta) {
+function buildPreflightDiagnostics(meta, suppressedStableIds) {
+  const diagnostics = [];
   const missingDescriptionStableIds = Object.entries(meta.nodes).filter(([, node]) => node.description === void 0 && node.activation?.description === void 0).map(([nodeId, node]) => node.stable_id ?? nodeId).sort();
-  if (missingDescriptionStableIds.length === 0) {
-    return [];
+  if (missingDescriptionStableIds.length > 0) {
+    diagnostics.push({
+      code: "missing_description",
+      severity: "warn",
+      stable_ids: missingDescriptionStableIds,
+      message: `Resolved registry includes ${missingDescriptionStableIds.length} node(s) without structured descriptions.`
+    });
   }
-  return [{
-    code: "missing_description",
-    severity: "warn",
-    stable_ids: missingDescriptionStableIds,
-    message: `Resolved registry includes ${missingDescriptionStableIds.length} node(s) without structured descriptions.`
-  }];
+  if (suppressedStableIds.length > 0) {
+    diagnostics.push({
+      code: "empty_shell_suppressed",
+      severity: "warn",
+      stable_ids: [...suppressedStableIds].sort(),
+      message: `${suppressedStableIds.length} draft entr${suppressedStableIds.length === 1 ? "y" : "ies"} hidden from candidates (summary === stable_id, no signal). Run \`fabric doctor --enrich-descriptions\` to populate them.`
+    });
+  }
+  return diagnostics;
 }
 function dedupeStableIds(stableIds) {
   return Array.from(new Set(stableIds));
@@ -2840,7 +2823,7 @@ function scoreDescriptionItem(item, nowMs, targetPaths) {
     }
   }
   if (targetPaths.length > 0) {
-    const relevancePaths = item.relevance_paths ?? item.description?.relevance_paths ?? [];
+    const relevancePaths = item.description?.relevance_paths ?? [];
     let best = 0;
     for (const rp of relevancePaths) {
       for (const tp of targetPaths) {
@@ -2949,7 +2932,7 @@ import { enforcePayloadLimit as enforcePayloadLimit3 } from "@fenglimg/fabric-sh
 import { readFile as readFile8 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 import { join as join9 } from "path";
-import { deriveAgentsMetaLayer as deriveAgentsMetaLayer4 } from "@fenglimg/fabric-shared";
+import { deriveAgentsMetaLayer as deriveAgentsMetaLayer3 } from "@fenglimg/fabric-shared";
 var PRIORITY_ORDER = {
   high: 0,
   medium: 1,
@@ -3014,7 +2997,6 @@ async function getKnowledgeSections(projectRoot, input) {
   }
   const result = {
     revision_hash: meta.revision,
-    precedence: ["L2", "L1", "L0"],
     selected_stable_ids: rules.map((rule) => rule.stable_id),
     rules,
     diagnostics,
@@ -3085,7 +3067,9 @@ function validateAiSelections(aiSelectableStableIds, aiSelectedStableIds, aiSele
   const selectable = new Set(aiSelectableStableIds);
   for (const stableId of aiSelectedStableIds) {
     if (!selectable.has(stableId)) {
-      throw new Error(`Invalid L1 rule selection: ${stableId}`);
+      throw new Error(
+        `Invalid rule selection "${stableId}": not in this token's plan-context candidates. Pass only stable_ids from fab_plan_context candidates[].stable_id.`
+      );
     }
     if (aiSelectionReasons[stableId]?.trim() === "") {
       throw new Error(`Missing AI selection reason for ${stableId}`);
@@ -3101,7 +3085,7 @@ function findRuleNode(meta, stableId) {
     if (nodeStableId !== stableId) {
       continue;
     }
-    const level = node.level ?? deriveAgentsMetaLayer4(node.file);
+    const level = node.level ?? deriveAgentsMetaLayer3(node.file);
     return {
       stable_id: nodeStableId,
       level,
@@ -3150,7 +3134,7 @@ function pickSelectionReasons(selectedStableIds, reasons) {
 var RECALL_REASON_MARKER = "fab_recall: combined-call auto-selection";
 async function recall(projectRoot, input) {
   const planResult = await planContext(projectRoot, input);
-  const candidateIds = planResult.shared.description_index.map((item) => item.stable_id);
+  const candidateIds = planResult.candidates.map((item) => item.stable_id);
   let rewrittenIds;
   if (input.ids !== void 0) {
     try {
@@ -4423,7 +4407,7 @@ import { constants } from "fs";
 import { homedir as homedir6 } from "os";
 import { isAbsolute as isAbsolute2, join as join11, posix, relative as nodeRelative, resolve as resolve4, sep as sep3 } from "path";
 import { Script } from "vm";
-import { minimatch as minimatch3 } from "minimatch";
+import { minimatch as minimatch2 } from "minimatch";
 import { ZodError } from "zod";
 import {
   agentsMetaSchema as agentsMetaSchema5,
@@ -8542,7 +8526,7 @@ function inspectRelevancePathsDangling(projectRoot) {
       const glob = rawGlob.endsWith("/") ? `${rawGlob}**` : rawGlob;
       let matched = false;
       for (const target of workspacePaths) {
-        if (minimatch3(target, glob, { dot: true, matchBase: false })) {
+        if (minimatch2(target, glob, { dot: true, matchBase: false })) {
           matched = true;
           break;
         }
@@ -8626,7 +8610,7 @@ function inspectRelevancePathsDrift(projectRoot) {
     for (const rawGlob of paths) {
       const glob = rawGlob.endsWith("/") ? `${rawGlob}**` : rawGlob;
       for (const target of recentPaths) {
-        if (minimatch3(target, glob, { dot: true, matchBase: false })) {
+        if (minimatch2(target, glob, { dot: true, matchBase: false })) {
           anyMatch = true;
           break;
         }
@@ -8761,7 +8745,7 @@ function inspectPersonalLayerPathMisclassify(projectRoot) {
       }
       const glob = rawGlob.endsWith("/") ? `${rawGlob}**` : rawGlob;
       for (const target of workspacePaths) {
-        if (minimatch3(target, glob, { dot: true, matchBase: false })) {
+        if (minimatch2(target, glob, { dot: true, matchBase: false })) {
           matched.push(rawGlob);
           break;
         }
@@ -9760,7 +9744,7 @@ function matchesRelevancePath(editPath, relevancePaths) {
   }
   const normalized = normalizePath(editPath);
   for (const glob of relevancePaths) {
-    if (minimatch3(normalized, glob, { dot: true, matchBase: false })) {
+    if (minimatch2(normalized, glob, { dot: true, matchBase: false })) {
       return true;
     }
   }
@@ -9953,7 +9937,7 @@ async function runDoctorCiteCoverage(projectRoot, options) {
         case "edit": {
           let matched = false;
           for (const p of editPaths) {
-            if (minimatch3(p, op.target, { dot: true, matchBase: false })) {
+            if (minimatch2(p, op.target, { dot: true, matchBase: false })) {
               matched = true;
               break;
             }
@@ -9963,7 +9947,7 @@ async function runDoctorCiteCoverage(projectRoot, options) {
         }
         case "not_edit": {
           for (const p of editPaths) {
-            if (minimatch3(p, op.target, { dot: true, matchBase: false })) {
+            if (minimatch2(p, op.target, { dot: true, matchBase: false })) {
               return true;
             }
           }
@@ -10080,14 +10064,17 @@ async function runDoctorCiteCoverage(projectRoot, options) {
   }
   let editsTouched = 0;
   let expectedButMissed = 0;
+  let uncorrelatableEdits = 0;
   for (const edit of editEvents) {
     const sid = edit.session_id;
+    const hasSid = typeof sid === "string" && sid.length > 0;
+    if (!hasSid) uncorrelatableEdits += 1;
     if (clientSessionIds !== null) {
-      if (typeof sid !== "string" || sid.length === 0) continue;
+      if (!hasSid) continue;
       if (!clientSessionIds.has(sid)) continue;
     }
     editsTouched += 1;
-    if (typeof sid !== "string" || sid.length === 0) continue;
+    if (!hasSid) continue;
     const citedSet = sessionCitedKbs.get(sid) ?? /* @__PURE__ */ new Set();
     for (const [kbId, kb] of kbIndex) {
       if (kb.relevance_scope !== "narrow") continue;
@@ -10097,12 +10084,21 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       }
     }
   }
+  const noneTotal = Object.values(noneHistogram).reduce((a, b) => a + b, 0);
+  const compliantCites = qualifyingCites + noneTotal;
+  const noncompliantCites = expectedButMissed;
+  const complianceDenom = compliantCites + noncompliantCites;
+  const citeComplianceRate = complianceDenom > 0 ? compliantCites / complianceDenom : null;
   const metrics = {
     edits_touched: editsTouched,
     qualifying_cites: qualifyingCites,
     recalled_unverified: recalledUnverified,
     expected_but_missed: expectedButMissed,
-    total_turns: totalTurns
+    total_turns: totalTurns,
+    cite_compliance_rate: citeComplianceRate,
+    compliant_cites: compliantCites,
+    noncompliant_cites: noncompliantCites,
+    uncorrelatable_edits: uncorrelatableEdits
   };
   let perClient;
   if (options.client === "all" && perClientAccum.size > 0) {
@@ -10512,7 +10508,7 @@ function formatPreexistingRootMessage(projectRoot) {
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.37"
+    version: "2.0.0-rc.38"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.0.0-rc.37",
+  "version": "2.0.0-rc.38",
   "description": "Fabric MCP knowledge server — stdio transport for Claude Code / Cursor / Codex CLI, manages .fabric/ knowledge base + agents.meta.json + event ledger.",
   "license": "MIT",
   "author": "wangzhichao <fenglimg90@gmail.com>",
@@ -38,7 +38,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.0.0-rc.37"
+    "@fenglimg/fabric-shared": "2.0.0-rc.38"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",