@fenglimg/fabric-server 2.0.0-rc.21 → 2.0.0-rc.23

package/dist/index.js

@@ -1,14 +1,19 @@
 import {
+  AgentsMetaFileMissingError,
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
+  ServeLockHeldError,
+  acquireLock,
   appendEventLedgerEvent,
   atomicWriteText,
   buildKnowledgeMeta,
+  checkLockOrThrow,
   computeKnowledgeBasedAgentsMeta,
   computeKnowledgeTestIndex,
   deriveKnowledgeMetaLayer,
   deriveKnowledgeMetaTopologyType,
+  enrichDescriptions,
   ensureKnowledgeFresh,
   ensureParentDirectory,
   flushAndSyncEventLedger,
@@ -16,9 +21,12 @@ import {
   getLedgerPath,
   getLegacyLedgerPath,
   isSameKnowledgeTestIndex,
+  loadActiveMeta,
+  loadActiveMetaOrStale,
   normalizeKnowledgePath,
-  readAgentsMeta,
+  readLockState,
   reconcileKnowledge,
+  releaseLock,
   resolveProjectRoot,
   runDoctorApplyLint,
   runDoctorCiteCoverage,
@@ -27,7 +35,7 @@ import {
   sha256,
   stableStringify,
   writeKnowledgeMeta
-} from "./chunk-7R6MFA7Y.js";
+} from "./chunk-IRB77C6E.js";
 
 // src/index.ts
 import { existsSync as existsSync4 } from "fs";
@@ -40,6 +48,66 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/constants.ts
 var AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
 
+// src/services/first-reconcile-gate.ts
+function gateWarning(result) {
+  if (result.status === "ready") return null;
+  if (result.status === "stale") {
+    return {
+      code: "meta_stale",
+      file: "<response>",
+      action_hint: "Initial reconcile still pending; results may use cached meta. Retry shortly or run `fab doctor --fix`."
+    };
+  }
+  return {
+    code: "reconcile_failed",
+    file: "<response>",
+    action_hint: "Reconcile failed at startup; run `fab doctor --fix` and restart the MCP server."
+  };
+}
+var state = {
+  firstReconcilePromise: null,
+  reconcileFailure: null,
+  settled: false
+};
+function setFirstReconcile(reconcilePromise) {
+  state.firstReconcilePromise = reconcilePromise.then(
+    () => {
+      state.settled = true;
+    },
+    (error) => {
+      state.reconcileFailure = error;
+      state.settled = true;
+    }
+  );
+}
+async function awaitFirstReconcileGate(timeoutMs = 5e3) {
+  if (state.reconcileFailure !== null) {
+    return { status: "failed", error: state.reconcileFailure };
+  }
+  if (state.firstReconcilePromise === null || state.settled) {
+    return { status: "ready" };
+  }
+  let timer = null;
+  const timeoutPromise = new Promise((resolveTimeout) => {
+    timer = setTimeout(() => resolveTimeout("timeout"), timeoutMs);
+  });
+  try {
+    const winner = await Promise.race([
+      state.firstReconcilePromise.then(() => "reconcile"),
+      timeoutPromise
+    ]);
+    if (winner === "timeout") {
+      return { status: "stale" };
+    }
+    if (state.reconcileFailure !== null) {
+      return { status: "failed", error: state.reconcileFailure };
+    }
+    return { status: "ready" };
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+  }
+}
+
 // src/services/in-flight-tracker.ts
 function createInFlightTracker() {
   const active = /* @__PURE__ */ new Map();
@@ -123,8 +191,15 @@ function resolvePersonalRoot() {
   return process.env.FABRIC_HOME ?? homedir();
 }
 async function extractKnowledge(projectRoot, input) {
+  try {
+    await loadActiveMeta(projectRoot, { caller: "extractKnowledge" });
+  } catch (error) {
+    if (!(error instanceof AgentsMetaFileMissingError)) {
+      throw error;
+    }
+  }
   const sanitizedSlug = sanitizeSlug(input.slug);
-  const sourceSessions = Array.isArray(input.source_sessions) && input.source_sessions.length > 0 ? input.source_sessions : input.source_session !== void 0 && input.source_session.length > 0 ? [input.source_session] : [];
+  const sourceSessions = input.source_sessions ?? [];
   const primarySession = sourceSessions[0] ?? "";
   const idempotencyKey = sha256(
     JSON.stringify({
@@ -208,7 +283,20 @@ async function extractKnowledge(projectRoot, input) {
     proposedReason: input.proposed_reason,
     sessionContext: input.session_context,
     relevanceScope,
-    relevancePaths
+    relevancePaths,
+    // v2.0.0-rc.23 TASK-006 (a-C1): optional structured triage fields. Each is
+    // emitted as a YAML line only when caller-supplied; omitted lines preserve
+    // the historical pending-file shape.
+    intentClues: input.intent_clues,
+    techStack: input.tech_stack,
+    impact: input.impact,
+    mustReadIf: input.must_read_if,
+    // v2.0.0-rc.23 TASK-014 (F8c): optional S5 onboard-slot tag. Same emit
+    // discipline as the four a-C1 fields — bare YAML line iff caller-supplied,
+    // never in the idempotency_key hash. fabric-archive's first-run phase is
+    // the only producer; downstream `fab onboard-coverage` walks frontmatter
+    // looking for this exact key.
+    onboardSlot: input.onboard_slot
   });
   await atomicWriteText(absolutePath, fresh);
   await emitEventBestEffort(projectRoot, {
@@ -251,6 +339,24 @@ function renderFreshEntry(args) {
     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}]`);
+  }
+  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}`);
+  }
   frontmatterLines.push(
     `x-fabric-idempotency-key: ${args.idempotencyKey}`,
     "---"
@@ -319,9 +425,9 @@ ${renderEvidenceBlock(newSummary, newRecentPaths)}
     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 t2 = rawLine.trim();
-        if (t2.startsWith("- ")) {
-          existingPaths.push(t2.slice(2).trim());
+        const t = rawLine.trim();
+        if (t.startsWith("- ")) {
+          existingPaths.push(t.slice(2).trim());
         }
       }
     }
@@ -330,16 +436,16 @@ ${renderEvidenceBlock(newSummary, newRecentPaths)}
     const bulletLines = [];
     let prose = [];
     for (const rawLine of noteBody.split(/\r?\n/u)) {
-      const t2 = rawLine.trim();
-      if (t2.length === 0) continue;
-      if (t2.startsWith("- ")) {
+      const t = rawLine.trim();
+      if (t.length === 0) continue;
+      if (t.startsWith("- ")) {
         if (prose.length > 0) {
           existingNotes.push(prose.join(" ").trim());
           prose = [];
         }
-        bulletLines.push(t2.slice(2).trim());
+        bulletLines.push(t.slice(2).trim());
       } else {
-        prose.push(t2);
+        prose.push(t);
       }
     }
     if (prose.length > 0) existingNotes.push(prose.join(" ").trim());
@@ -414,7 +520,7 @@ function registerExtractKnowledge(server, tracker) {
   server.registerTool(
     "fab_extract_knowledge",
     {
-      description: "Persist a proposed pending knowledge entry under .fabric/knowledge/pending/<type>/<slug>.md. Idempotent on (source_session, type, slug); repeat calls append evidence rather than overwrite. Skill-side tool \u2014 invoked at session-stop.",
+      description: "Persist a proposed pending knowledge entry under .fabric/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
@@ -423,9 +529,14 @@ function registerExtractKnowledge(server, tracker) {
       const requestId = randomUUID();
       tracker?.enter(requestId);
       try {
+        const gateResult = await awaitFirstReconcileGate();
+        const gateWarn = gateWarning(gateResult);
         const projectRoot = resolveProjectRoot();
         const result = await extractKnowledge(projectRoot, input);
         const response = { ...result };
+        if (gateWarn) {
+          response.warnings = [gateWarn];
+        }
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
         enforcePayloadLimit(serialized, payloadLimits);
@@ -455,16 +566,30 @@ import { deriveAgentsMetaLayer } from "@fenglimg/fabric-shared";
 var SELECTION_TOKEN_TTL_MS = 5 * 60 * 1e3;
 var selectionTokenCache = /* @__PURE__ */ new Map();
 async function planContext(projectRoot, input) {
-  const meta = await readAgentsMeta(projectRoot);
-  const stale = input.client_hash !== void 0 && input.client_hash !== meta.revision;
+  let metaResult = await loadActiveMetaOrStale(projectRoot, { caller: "planContext" });
+  let meta = metaResult.meta;
+  let firstSeenPreviousRevision = metaResult.previous_revision_hash;
+  let autoHealedAccumulated = metaResult.auto_healed;
+  if (metaResult.auto_healed !== true && hasUndefinedDescription(meta)) {
+    try {
+      await reconcileKnowledge(projectRoot, { trigger: "auto-heal-description" });
+      const healedResult = await loadActiveMetaOrStale(projectRoot, { caller: "planContext" });
+      meta = healedResult.meta;
+      autoHealedAccumulated = true;
+      firstSeenPreviousRevision = metaResult.previous_revision_hash;
+      metaResult = healedResult;
+    } catch {
+    }
+  }
+  const stale = metaResult.degraded === true || input.client_hash !== void 0 && input.client_hash !== meta.revision;
   const uniquePaths = dedupePaths(input.paths);
   const allDescriptions = buildDescriptionIndex(meta);
   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));
+  const entries = uniquePaths.map((path) => {
+    const profile = buildRequirementProfile(path, input);
+    const descriptionIndex = allDescriptions.filter((item) => shouldIncludeIndexItemForPath(item, meta, path)).filter((item) => shouldIncludeByRelevance(item, relevanceTargetPaths));
     return {
-      path: path2,
+      path,
       requirement_profile: profile,
       description_index: descriptionIndex
     };
@@ -480,7 +605,16 @@ async function planContext(projectRoot, input) {
     shared: {
       description_index: sharedDescriptionIndex,
       preflight_diagnostics: buildPreflightDiagnostics(meta)
-    }
+    },
+    // 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).
+    // Keeping these fields absent on the steady-state path means existing
+    // consumers see the same wire shape they always have.
+    ...autoHealedAccumulated ? {
+      auto_healed: true,
+      previous_revision_hash: firstSeenPreviousRevision
+    } : {}
   };
   try {
     await appendEventLedgerEvent(projectRoot, {
@@ -502,15 +636,15 @@ async function planContext(projectRoot, input) {
   return result;
 }
 function readSelectionToken(token, now = Date.now()) {
-  const state = selectionTokenCache.get(token);
-  if (state === void 0) {
+  const state2 = selectionTokenCache.get(token);
+  if (state2 === void 0) {
     return void 0;
   }
-  if (state.expires_at <= now) {
+  if (state2.expires_at <= now) {
     selectionTokenCache.delete(token);
     return void 0;
   }
-  return state;
+  return state2;
 }
 function createSelectionToken(revisionHash, targetPaths, requiredStableIds, aiSelectableStableIds, now = Date.now()) {
   const token = `selection:${revisionHash}:${now.toString(36)}:${Math.random().toString(36).slice(2)}`;
@@ -527,8 +661,8 @@ function createSelectionToken(revisionHash, targetPaths, requiredStableIds, aiSe
 }
 function dedupePaths(paths) {
   const seenPaths = /* @__PURE__ */ new Set();
-  return paths.flatMap((path2) => {
-    const normalizedPath = normalizeKnowledgePath(path2);
+  return paths.flatMap((path) => {
+    const normalizedPath = normalizeKnowledgePath(path);
     if (seenPaths.has(normalizedPath)) {
       return [];
     }
@@ -536,8 +670,8 @@ function dedupePaths(paths) {
     return [normalizedPath];
   });
 }
-function buildRequirementProfile(path2, input) {
-  const normalizedPath = normalizeKnowledgePath(path2);
+function buildRequirementProfile(path, input) {
+  const normalizedPath = normalizeKnowledgePath(path);
   const extensionMatch = /(\.[^./\\]+)$/u.exec(normalizedPath);
   const knownTech = dedupeStableIds([
     ...input.known_tech ?? [],
@@ -549,7 +683,7 @@ function buildRequirementProfile(path2, input) {
     extension: extensionMatch?.[1] ?? "",
     known_tech: knownTech,
     user_intent: input.intent ?? "",
-    detected_entities: input.detected_entities?.[normalizedPath] ?? input.detected_entities?.[path2] ?? []
+    detected_entities: input.detected_entities?.[normalizedPath] ?? input.detected_entities?.[path] ?? []
   };
 }
 function buildDescriptionIndex(meta) {
@@ -630,6 +764,11 @@ function descriptionFromLegacyActivation(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) {
   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) {
@@ -673,6 +812,8 @@ function registerPlanContext(server, tracker) {
       const requestId = randomUUID2();
       tracker?.enter(requestId);
       try {
+        const gateResult = await awaitFirstReconcileGate();
+        const gateWarn = gateWarning(gateResult);
         const projectRoot = resolveProjectRoot();
         const syncReport = await ensureKnowledgeFresh(projectRoot);
         const result = await planContext(projectRoot, {
@@ -686,7 +827,10 @@ function registerPlanContext(server, tracker) {
         });
         const response = {
           ...result,
-          warnings: [...syncReport.warnings]
+          warnings: [
+            ...gateWarn ? [gateWarn] : [],
+            ...syncReport.warnings
+          ]
         };
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
@@ -935,7 +1079,7 @@ async function listPending(projectRoot, filters) {
         }
         if (filters?.tags !== void 0 && filters.tags.length > 0) {
           const itemTags = fm.tags ?? [];
-          const hasAll = filters.tags.every((t2) => itemTags.includes(t2));
+          const hasAll = filters.tags.every((t) => itemTags.includes(t));
           if (!hasAll) continue;
         }
         if (filters?.created_after !== void 0) {
@@ -1108,8 +1252,8 @@ function resolveModifyTarget(projectRoot, pendingPath) {
   }
   return null;
 }
-function inferTypeFromPath(path2) {
-  const match = /knowledge\/(?:pending\/)?([^/]+)\/[^/]+\.md$/u.exec(path2);
+function inferTypeFromPath(path) {
+  const match = /knowledge\/(?:pending\/)?([^/]+)\/[^/]+\.md$/u.exec(path);
   if (match === null) return null;
   const seg = match[1];
   if (seg !== void 0 && PLURAL_TYPES.includes(seg)) {
@@ -1117,8 +1261,8 @@ function inferTypeFromPath(path2) {
   }
   return null;
 }
-function extractSlug(path2) {
-  const file = basename(path2).replace(/\.md$/u, "");
+function extractSlug(path) {
+  const file = basename(path).replace(/\.md$/u, "");
   return file.replace(/^K[PT]-(MOD|DEC|GLD|PIT|PRO)-\d+--/u, "");
 }
 async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
@@ -1235,7 +1379,7 @@ async function searchEntries(projectRoot, query, filters) {
         }
         if (filters?.tags !== void 0 && filters.tags.length > 0) {
           const itemTags = fm.tags ?? [];
-          const hasAll = filters.tags.every((t2) => itemTags.includes(t2));
+          const hasAll = filters.tags.every((t) => itemTags.includes(t));
           if (!hasAll) continue;
         }
         if (filters?.created_after !== void 0) {
@@ -1474,10 +1618,15 @@ function registerReview(server, tracker) {
       const requestId = randomUUID3();
       tracker?.enter(requestId);
       try {
+        const gateResult = await awaitFirstReconcileGate();
+        const gateWarn = gateWarning(gateResult);
         const narrowed = FabReviewInputSchema.parse(input);
         const projectRoot = resolveProjectRoot();
         const result = await reviewKnowledge(projectRoot, narrowed);
-        const response = result;
+        const response = { ...result };
+        if (gateWarn) {
+          response.warnings = [gateWarn];
+        }
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
         enforcePayloadLimit3(serialized, payloadLimits);
@@ -1505,62 +1654,17 @@ import { enforcePayloadLimit as enforcePayloadLimit4 } from "@fenglimg/fabric-sh
 import { readFile as readFile4 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { join as join4 } from "path";
-var KNOWLEDGE_SECTION_NAMES = [
-  "MISSION_STATEMENT",
-  "MANDATORY_INJECTION",
-  "BUSINESS_LOGIC_CHUNKS",
-  "CONTEXT_INFO"
-];
 var PRIORITY_ORDER = {
   high: 0,
   medium: 1,
   low: 2
 };
-function parseKnowledgeSections(content) {
-  const sections = /* @__PURE__ */ new Map();
-  const lines = content.split(/\r?\n/u);
-  let activeSection;
-  let activeSectionDepth = 0;
-  let buffer = [];
-  const flush = () => {
-    if (activeSection === void 0) {
-      return;
-    }
-    const text = buffer.join("\n").trim();
-    if (text.length === 0) {
-      buffer = [];
-      return;
-    }
-    sections.set(activeSection, [...sections.get(activeSection) ?? [], text]);
-    buffer = [];
-  };
-  for (const line of lines) {
-    const heading = /^(#{2,6})\s+\[([A-Z_]+)\]\s*$/u.exec(line.trim());
-    if (heading !== null) {
-      flush();
-      activeSection = isKnowledgeSectionName(heading[2]) ? heading[2] : void 0;
-      activeSectionDepth = activeSection === void 0 ? 0 : heading[1].length;
-      continue;
-    }
-    const ordinaryHeading = /^(#{1,6})\s+/u.exec(line.trim());
-    if (ordinaryHeading !== null) {
-      if (activeSection !== void 0 && ordinaryHeading[1].length > activeSectionDepth) {
-        buffer.push(line);
-        continue;
-      }
-      flush();
-      activeSection = void 0;
-      activeSectionDepth = 0;
-      continue;
-    }
-    if (activeSection !== void 0) {
-      buffer.push(line);
-    }
+function extractBody(content) {
+  const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/u.exec(content);
+  if (match === null) {
+    return content.replace(/^\uFEFF/u, "");
   }
-  flush();
-  return new Map(
-    Array.from(sections.entries()).map(([section, values]) => [section, values.join("\n\n")])
-  );
+  return content.slice(match[0].length);
 }
 async function getKnowledgeSections(projectRoot, input) {
   const token = readSelectionToken(input.selection_token);
@@ -1568,28 +1672,14 @@ async function getKnowledgeSections(projectRoot, input) {
     throw new Error("selection_token is missing or expired");
   }
   validateAiSelections(token.ai_selectable_stable_ids, input.ai_selected_stable_ids, input.ai_selection_reasons);
-  const meta = await readAgentsMeta(projectRoot);
+  const { meta } = await loadActiveMeta(projectRoot, { caller: "getKnowledgeSections" });
   const selectedStableIds = [...token.required_stable_ids, ...input.ai_selected_stable_ids];
   const selectedRules = sortRuleNodes(selectedStableIds.map((stableId) => findRuleNode(meta, stableId)));
   const diagnostics = [];
   const rules = [];
   for (const rule of selectedRules) {
     const content = await readFile4(resolveRuleSourcePath(projectRoot, rule.path), "utf8");
-    const parsedSections = parseKnowledgeSections(content);
-    const sections = {};
-    for (const section of input.sections) {
-      const sectionContent = parsedSections.get(section);
-      sections[section] = sectionContent ?? "";
-      if (sectionContent === void 0) {
-        diagnostics.push({
-          code: "missing_section",
-          severity: "warn",
-          stable_id: rule.stable_id,
-          section,
-          message: `Rule ${rule.stable_id} does not define section ${section}.`
-        });
-      }
-    }
+    const body = extractBody(content);
     const description = rule.node.description;
     if (description !== void 0 && description.knowledge_type === void 0 && description.knowledge_layer === void 0) {
       diagnostics.push({
@@ -1603,7 +1693,7 @@ async function getKnowledgeSections(projectRoot, input) {
       stable_id: rule.stable_id,
       level: rule.level,
       path: rule.path,
-      sections
+      body
     });
   }
   const result = {
@@ -1635,7 +1725,7 @@ async function getKnowledgeSections(projectRoot, input) {
       event_type: "knowledge_sections_fetched",
       selection_token: input.selection_token,
       target_paths: token.target_paths,
-      requested_sections: input.sections,
+      requested_sections: [],
       final_stable_ids: result.selected_stable_ids,
       ai_selected_stable_ids: input.ai_selected_stable_ids,
       diagnostics,
@@ -1720,9 +1810,6 @@ function outputLevelOrder(level) {
       return 2;
   }
 }
-function isKnowledgeSectionName(value) {
-  return KNOWLEDGE_SECTION_NAMES.includes(value);
-}
 function resolveRuleSourcePath(projectRoot, contentRef) {
   if (contentRef.startsWith("~/.fabric/knowledge/")) {
     const home = process.env.FABRIC_HOME ?? homedir3();
@@ -1739,7 +1826,7 @@ function registerKnowledgeSections(server, tracker) {
   server.registerTool(
     "fab_get_knowledge_sections",
     {
-      description: "Fetch structured Fabric rule sections after fab_plan_context. Required L0/L2 rules are merged with AI-selected L1 rules server-side.",
+      description: "Fetch the full markdown body of one or more Fabric rules picked from fab_plan_context. Returns body strings keyed by stable_id (frontmatter stripped). Use after fab_plan_context returned selectable entries to load full rule content for LLM context injection \u2014 scan the body for whatever headings the rule defines (Summary / Why proposed / Session context / Evidence, etc.).",
       inputSchema: knowledgeSectionsInputSchema,
       outputSchema: knowledgeSectionsOutputSchema,
       annotations: knowledgeSectionsAnnotations
@@ -1748,12 +1835,17 @@ function registerKnowledgeSections(server, tracker) {
       const requestId = randomUUID4();
       tracker?.enter(requestId);
       try {
+        const gateResult = await awaitFirstReconcileGate();
+        const gateWarn = gateWarning(gateResult);
         const projectRoot = resolveProjectRoot();
         const syncReport = await ensureKnowledgeFresh(projectRoot);
         const result = await getKnowledgeSections(projectRoot, input);
         const response = {
           ...result,
-          warnings: [...syncReport.warnings]
+          warnings: [
+            ...gateWarn ? [gateWarn] : [],
+            ...syncReport.warnings
+          ]
         };
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
@@ -1779,99 +1871,6 @@ function registerKnowledgeSections(server, tracker) {
   );
 }
 
-// src/services/serve-lock.ts
-import fs from "fs";
-import path from "path";
-import { createTranslator, detectNodeLocale } from "@fenglimg/fabric-shared";
-import { IOFabricError } from "@fenglimg/fabric-shared/errors";
-var LOCK_FILENAME = ".serve.lock";
-var t = createTranslator(detectNodeLocale());
-var ServeLockHeldError = class extends IOFabricError {
-  code = "SERVE_LOCK_HELD";
-  httpStatus = 423;
-};
-function lockPath(projectRoot) {
-  return path.join(projectRoot, ".fabric", LOCK_FILENAME);
-}
-function isAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    const err = e;
-    if (err.code === "ESRCH") return false;
-    if (err.code === "EPERM") return true;
-    throw e;
-  }
-}
-function acquireLock(projectRoot, opts) {
-  const p = lockPath(projectRoot);
-  if (fs.existsSync(p)) {
-    let state = null;
-    try {
-      state = JSON.parse(fs.readFileSync(p, "utf8"));
-    } catch {
-    }
-    if (state && state.pid && state.pid !== process.pid && isAlive(state.pid) && !opts?.force) {
-      throw new ServeLockHeldError(
-        `serve lock held by live PID ${state.pid}`,
-        {
-          actionHint: t("cli.serve.lock-held.action-hint", { pid: String(state.pid) }),
-          details: state
-        }
-      );
-    }
-    if (state && state.pid && !isAlive(state.pid)) {
-      process.stderr.write(`[serve-lock] stale lock from PID ${state.pid} \u2014 overwriting
-`);
-    }
-  }
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.writeFileSync(
-    p,
-    JSON.stringify({ pid: process.pid, acquiredAt: Date.now(), host: process.env.HOSTNAME })
-  );
-}
-function releaseLock(projectRoot) {
-  const p = lockPath(projectRoot);
-  try {
-    if (fs.existsSync(p)) {
-      const state = JSON.parse(fs.readFileSync(p, "utf8"));
-      if (state.pid === process.pid) {
-        fs.unlinkSync(p);
-      }
-    }
-  } catch {
-  }
-}
-function readLockState(projectRoot) {
-  const p = lockPath(projectRoot);
-  if (!fs.existsSync(p)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(p, "utf8"));
-  } catch {
-    return null;
-  }
-}
-function checkLockOrThrow(projectRoot, opts) {
-  const state = readLockState(projectRoot);
-  if (state === null) return;
-  if (state.pid === process.pid) return;
-  if (!isAlive(state.pid)) {
-    process.stderr.write(`[serve-lock] stale lock from PID ${state.pid} \u2014 ignoring
-`);
-    return;
-  }
-  if (opts?.force) return;
-  throw new ServeLockHeldError(
-    `serve lock held by live PID ${state.pid}`,
-    {
-      actionHint: t("cli.serve.lock-held.action-hint", { pid: String(state.pid) }),
-      details: state
-    }
-  );
-}
-
 // src/index.ts
 function writeStderr(message) {
   process.stderr.write(`${message}
@@ -1893,7 +1892,7 @@ function formatPreexistingRootMessage(projectRoot) {
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.21"
+    version: "2.0.0-rc.23"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);
@@ -1908,10 +1907,10 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path2 = join5(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path = join5(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
-      if (existsSync4(path2)) {
-        text = await readFile5(path2, "utf8");
+      if (existsSync4(path)) {
+        text = await readFile5(path, "utf8");
       }
       return {
         contents: [
@@ -1929,13 +1928,6 @@ function createFabricServer(tracker) {
 async function startStdioServer() {
   const tracker = createInFlightTracker();
   const projectRoot = resolveProjectRoot();
-  const syncStart = Date.now();
-  const reconcileResult = await reconcileKnowledge(projectRoot, { trigger: "startup" });
-  const syncDurationMs = Date.now() - syncStart;
-  process.stderr.write(
-    `[startup] rule sync: status=${reconcileResult.status}, events=${reconcileResult.events.length}, ${syncDurationMs}ms
-`
-  );
   const rootMsg = formatPreexistingRootMessage(projectRoot);
   if (rootMsg !== null) {
     process.stderr.write(`${rootMsg}
@@ -1944,6 +1936,21 @@ async function startStdioServer() {
   const server = createFabricServer(tracker);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  const syncStart = Date.now();
+  const backgroundReconcile = (async () => {
+    const reconcileResult = await reconcileKnowledge(projectRoot, { trigger: "startup" });
+    const syncDurationMs = Date.now() - syncStart;
+    process.stderr.write(
+      `[startup] rule sync: status=${reconcileResult.status}, events=${reconcileResult.events.length}, ${syncDurationMs}ms
+`
+    );
+  })().catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    process.stderr.write(`[startup] rule sync FAILED: ${message}
+`);
+    throw error;
+  });
+  setFirstReconcile(backgroundReconcile);
   const closeServer = async () => {
     await server.close();
   };
@@ -1993,7 +2000,7 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-JGWQGUZS.js");
+  const { createFabricHttpApp } = await import("./http-ZBV6YUHD.js");
   const { port, projectRoot, host = "127.0.0.1", authToken } = options;
   const app = createFabricHttpApp({ projectRoot, host, authToken });
   return await new Promise((resolveServer, rejectServer) => {
@@ -2036,6 +2043,7 @@ export {
   createShutdownHandler,
   deriveKnowledgeMetaLayer,
   deriveKnowledgeMetaTopologyType,
+  enrichDescriptions,
   ensureKnowledgeFresh,
   extractKnowledge,
   flushAndSyncEventLedger,