@fenglimg/fabric-server 1.8.0-rc.3 → 2.0.0-rc.8

package/dist/index.js

@@ -1,37 +1,44 @@
 import {
-  AGENTS_MD_RESOURCE_URI,
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
-  buildRuleMeta,
-  computeRuleTestIndex,
-  computeRulesBasedAgentsMeta,
-  deriveRuleMetaLayer,
-  deriveRuleMetaTopologyType,
-  ensureRulesFresh,
+  appendEventLedgerEvent,
+  atomicWriteText,
+  buildKnowledgeMeta,
+  computeKnowledgeBasedAgentsMeta,
+  computeKnowledgeTestIndex,
+  deriveKnowledgeMetaLayer,
+  deriveKnowledgeMetaTopologyType,
+  ensureKnowledgeFresh,
+  ensureParentDirectory,
   flushAndSyncEventLedger,
   getEventLedgerPath,
   getLedgerPath,
   getLegacyLedgerPath,
-  getRuleSections,
-  isSameRuleTestIndex,
-  planContext,
-  reconcileRules,
+  isSameKnowledgeTestIndex,
+  normalizeKnowledgePath,
+  readAgentsMeta,
+  reconcileKnowledge,
   resolveProjectRoot,
+  runDoctorApplyLint,
   runDoctorFix,
   runDoctorReport,
+  sha256,
   stableStringify,
-  writeRuleMeta
-} from "./chunk-ZZGARZL5.js";
+  writeKnowledgeMeta
+} from "./chunk-AR2HV5JT.js";
 
 // src/index.ts
-import { existsSync as existsSync2 } from "fs";
-import { readFile } from "fs/promises";
-import { join as join2, resolve } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { readFile as readFile5 } from "fs/promises";
+import { join as join5, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/constants.ts
+var AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
+
 // src/services/in-flight-tracker.ts
 function createInFlightTracker() {
   const active = /* @__PURE__ */ new Map();
@@ -50,15 +57,15 @@ function createInFlightTracker() {
     drain(deadlineMs) {
       const startedWith = active.size;
       if (startedWith === 0) return Promise.resolve({ drained: 0, timed_out: 0 });
-      return new Promise((resolve2) => {
+      return new Promise((resolve3) => {
         const timer = setTimeout(() => {
           const drainedCount = startedWith - active.size;
           resolveDrained = null;
-          resolve2({ drained: drainedCount, timed_out: active.size });
+          resolve3({ drained: drainedCount, timed_out: active.size });
         }, deadlineMs);
         resolveDrained = () => {
           clearTimeout(timer);
-          resolve2({ drained: startedWith, timed_out: 0 });
+          resolve3({ drained: startedWith, timed_out: 0 });
         };
       });
     },
@@ -68,12 +75,12 @@ function createInFlightTracker() {
   };
 }
 
-// src/tools/plan-context.ts
+// src/tools/extract-knowledge.ts
 import { randomUUID } from "crypto";
 import {
-  planContextAnnotations,
-  planContextInputSchema,
-  planContextOutputSchema
+  FabExtractKnowledgeInputShape,
+  FabExtractKnowledgeOutputSchema,
+  fabExtractKnowledgeAnnotations
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
 import { enforcePayloadLimit } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
 
@@ -95,6 +102,532 @@ function readPayloadLimits(projectRoot) {
   return readFabricConfig(projectRoot).mcpPayloadLimits;
 }
 
+// src/services/extract-knowledge.ts
+import { existsSync as existsSync2 } from "fs";
+import { readFile } from "fs/promises";
+import { homedir } from "os";
+import { join as join2, relative } from "path";
+import {
+  PROPOSED_REASON_DESCRIPTIONS
+} from "@fenglimg/fabric-shared/schemas/api-contracts";
+var TEAM_PENDING_REL = ".fabric/knowledge/pending";
+var SLUG_MAX_LENGTH = 40;
+function pendingBase(layer, projectRoot) {
+  if (layer === "personal") {
+    return join2(resolvePersonalRoot(), ".fabric", "knowledge", "pending");
+  }
+  return join2(projectRoot, TEAM_PENDING_REL);
+}
+function resolvePersonalRoot() {
+  return process.env.FABRIC_HOME ?? homedir();
+}
+async function extractKnowledge(projectRoot, input) {
+  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 primarySession = sourceSessions[0] ?? "";
+  const idempotencyKey = sha256(
+    JSON.stringify({
+      source_session: primarySession,
+      type: input.type,
+      slug: sanitizedSlug
+    })
+  );
+  const summary = input.user_messages_summary ?? "";
+  const summaryIsEmpty = summary.trim().length === 0;
+  const slugIsEmpty = sanitizedSlug.length === 0;
+  if (summaryIsEmpty || slugIsEmpty) {
+    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}`
+    });
+    return {
+      pending_path: "",
+      idempotency_key: idempotencyKey
+    };
+  }
+  const layer = input.layer ?? "team";
+  const baseDir = pendingBase(layer, projectRoot);
+  const absolutePath = join2(baseDir, input.type, `${sanitizedSlug}.md`);
+  const reportedPath = layer === "personal" ? `~/${relative(resolvePersonalRoot(), absolutePath)}` : relative(projectRoot, absolutePath);
+  await ensureParentDirectory(absolutePath);
+  if (existsSync2(absolutePath)) {
+    const existing = await readFile(absolutePath, "utf8");
+    const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
+    if (existingKey === idempotencyKey) {
+      const augmented = mergeEvidenceNotes(existing, summary, input.recent_paths);
+      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:${sanitizedSlug}`
+      });
+      return {
+        pending_path: reportedPath,
+        idempotency_key: idempotencyKey
+      };
+    }
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_archive_attempted",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      correlation_id: primarySession,
+      session_id: primarySession,
+      reason: `extract_knowledge:${sanitizedSlug}: slug-collision (existing key ${existingKey ?? "<none>"} != incoming ${idempotencyKey})`
+    });
+    throw new Error(
+      `slug collision: pending file ${reportedPath} already exists with a different idempotency_key (existing=${existingKey ?? "<missing>"}, incoming=${idempotencyKey}); rename slug or resolve upstream`
+    );
+  }
+  const fresh = renderFreshEntry({
+    type: input.type,
+    sourceSessions,
+    idempotencyKey,
+    summary,
+    recentPaths: input.recent_paths,
+    layer,
+    proposedReason: input.proposed_reason,
+    sessionContext: input.session_context
+  });
+  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:${sanitizedSlug}`
+  });
+  return {
+    pending_path: reportedPath,
+    idempotency_key: idempotencyKey
+  };
+}
+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 frontmatter = [
+    "---",
+    `type: ${args.type}`,
+    "maturity: draft",
+    `layer: ${args.layer}`,
+    `created_at: ${createdAt}`,
+    `source_sessions: [${args.sourceSessions.map((s) => JSON.stringify(s)).join(", ")}]`,
+    `proposed_reason: ${args.proposedReason}`,
+    "tags: []",
+    `x-fabric-idempotency-key: ${args.idempotencyKey}`,
+    "---"
+  ].join("\n");
+  const reasonExplanation = PROPOSED_REASON_DESCRIPTIONS[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}`;
+}
+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, newSummary, newRecentPaths) {
+  const beforeMatch = /^([\s\S]*?)(\n## Evidence(?:\s*\(call \d+\))?\s*\n)/u.exec(
+    existing.endsWith("\n") ? existing : `${existing}
+`
+  );
+  if (beforeMatch === null) {
+    const trimmed = existing.endsWith("\n") ? existing : `${existing}
+`;
+    return `${trimmed}
+## Evidence
+
+${renderEvidenceBlock(newSummary, newRecentPaths)}
+`;
+  }
+  const head = beforeMatch[1] ?? "";
+  const existingNotes = [];
+  const existingPaths = [];
+  const evidenceBlockRe = /\n## Evidence(?:\s*\(call \d+\))?\s*\n([\s\S]*?)(?=\n## |$)/gu;
+  let m;
+  while ((m = evidenceBlockRe.exec(`${existing}
+`)) !== 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("- ")) {
+          existingPaths.push(t.slice(2).trim());
+        }
+      }
+    }
+    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) {
+          existingNotes.push(prose.join(" ").trim());
+          prose = [];
+        }
+        bulletLines.push(t.slice(2).trim());
+      } else {
+        prose.push(t);
+      }
+    }
+    if (prose.length > 0) existingNotes.push(prose.join(" ").trim());
+    for (const n of bulletLines) existingNotes.push(n);
+  }
+  const mergedNotes = [];
+  const seenNotes = /* @__PURE__ */ new Set();
+  const incomingNote = newSummary.trim();
+  const candidates = [...existingNotes, incomingNote];
+  for (const note of candidates) {
+    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 [...existingPaths, ...newRecentPaths]) {
+    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 `${head}
+## Evidence
+
+${evidenceBody}
+`;
+}
+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 sep = line.indexOf(":");
+    if (sep === -1) continue;
+    const k = line.slice(0, sep).trim();
+    if (k === key) {
+      return line.slice(sep + 1).trim();
+    }
+  }
+  return void 0;
+}
+async function emitEventBestEffort(projectRoot, event) {
+  try {
+    await appendEventLedgerEvent(projectRoot, event);
+  } catch {
+  }
+}
+
+// src/tools/extract-knowledge.ts
+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.",
+      inputSchema: FabExtractKnowledgeInputShape,
+      outputSchema: FabExtractKnowledgeOutputSchema.shape,
+      annotations: fabExtractKnowledgeAnnotations
+    },
+    async (input) => {
+      const requestId = randomUUID();
+      tracker?.enter(requestId);
+      try {
+        const projectRoot = resolveProjectRoot();
+        const result = await extractKnowledge(projectRoot, input);
+        const response = { ...result };
+        const payloadLimits = readPayloadLimits(projectRoot);
+        const serialized = JSON.stringify(response);
+        enforcePayloadLimit(serialized, payloadLimits);
+        return {
+          content: [{ type: "text", text: JSON.stringify(response) }],
+          structuredContent: response
+        };
+      } finally {
+        tracker?.exit(requestId);
+      }
+    }
+  );
+}
+
+// src/tools/plan-context.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  planContextAnnotations,
+  planContextInputSchema,
+  planContextOutputSchema
+} 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 } from "minimatch";
+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;
+  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));
+    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 selectionToken = createSelectionToken(meta.revision, uniquePaths, [], sharedStableIds);
+  const result = {
+    revision_hash: meta.revision,
+    stale,
+    selection_token: selectionToken,
+    entries,
+    shared: {
+      description_index: sharedDescriptionIndex,
+      preflight_diagnostics: buildPreflightDiagnostics(meta)
+    }
+  };
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "knowledge_context_planned",
+      target_paths: uniquePaths,
+      required_stable_ids: [],
+      ai_selectable_stable_ids: sharedDescriptionIndex.map((item) => item.stable_id),
+      final_stable_ids: [],
+      selection_token: selectionToken,
+      client_hash: input.client_hash,
+      intent: input.intent,
+      known_tech: input.known_tech,
+      diagnostics: result.shared.preflight_diagnostics,
+      correlation_id: input.correlation_id,
+      session_id: input.session_id
+    });
+  } catch {
+  }
+  return result;
+}
+function readSelectionToken(token, now = Date.now()) {
+  const state = selectionTokenCache.get(token);
+  if (state === void 0) {
+    return void 0;
+  }
+  if (state.expires_at <= now) {
+    selectionTokenCache.delete(token);
+    return void 0;
+  }
+  return state;
+}
+function createSelectionToken(revisionHash, targetPaths, requiredStableIds, aiSelectableStableIds, now = Date.now()) {
+  const token = `selection:${revisionHash}:${now.toString(36)}:${Math.random().toString(36).slice(2)}`;
+  selectionTokenCache.set(token, {
+    token,
+    revision_hash: revisionHash,
+    target_paths: targetPaths,
+    required_stable_ids: requiredStableIds,
+    ai_selectable_stable_ids: aiSelectableStableIds,
+    created_at: now,
+    expires_at: now + SELECTION_TOKEN_TTL_MS
+  });
+  return token;
+}
+function dedupePaths(paths) {
+  const seenPaths = /* @__PURE__ */ new Set();
+  return paths.flatMap((path2) => {
+    const normalizedPath = normalizeKnowledgePath(path2);
+    if (seenPaths.has(normalizedPath)) {
+      return [];
+    }
+    seenPaths.add(normalizedPath);
+    return [normalizedPath];
+  });
+}
+function buildRequirementProfile(path2, input) {
+  const normalizedPath = normalizeKnowledgePath(path2);
+  const extensionMatch = /(\.[^./\\]+)$/u.exec(normalizedPath);
+  const knownTech = dedupeStableIds([
+    ...input.known_tech ?? [],
+    ...extensionMatch?.[1] === ".ts" ? ["TypeScript"] : []
+  ]);
+  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) {
+  return Object.entries(meta.nodes).flatMap(([nodeId, node]) => {
+    const level = deriveAgentsMetaLayer(node.file);
+    const description = node.description ?? descriptionFromLegacyActivation(node.activation?.description);
+    if (description === void 0) {
+      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
+    }];
+  }).sort(compareDescriptionIndexItems);
+}
+function matchesAnyPath(globs, targetPaths) {
+  if (globs.length === 0) {
+    return false;
+  }
+  for (const rawGlob of globs) {
+    const glob = rawGlob.endsWith("/") ? `${rawGlob}**` : rawGlob;
+    for (const target of targetPaths) {
+      if (minimatch(target, glob, { dot: true, matchBase: false })) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function shouldIncludeByRelevance(item, targetPaths) {
+  const scope = item.relevance_scope ?? "broad";
+  if (scope === "broad") {
+    return true;
+  }
+  if (targetPaths.length === 0) {
+    return true;
+  }
+  return matchesAnyPath(item.relevance_paths ?? [], targetPaths);
+}
+function inferKnowledgeLayerFromContentRef(contentRef) {
+  if (contentRef === void 0) {
+    return void 0;
+  }
+  if (contentRef.startsWith("~/.fabric/knowledge/")) {
+    return "personal";
+  }
+  if (contentRef.startsWith(".fabric/knowledge/")) {
+    return "team";
+  }
+  return void 0;
+}
+function descriptionFromLegacyActivation(summary) {
+  if (summary === void 0) {
+    return void 0;
+  }
+  return {
+    summary,
+    intent_clues: [],
+    tech_stack: [],
+    impact: [],
+    must_read_if: summary
+  };
+}
+function shouldIncludeIndexItemForPath(_item, _meta, _path) {
+  return true;
+}
+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) {
+    return [];
+  }
+  return [{
+    code: "missing_description",
+    severity: "warn",
+    stable_ids: missingDescriptionStableIds,
+    message: `Resolved registry includes ${missingDescriptionStableIds.length} node(s) without structured descriptions.`
+  }];
+}
+function dedupeStableIds(stableIds) {
+  return Array.from(new Set(stableIds));
+}
+function dedupeDescriptionIndex(items) {
+  const seenStableIds = /* @__PURE__ */ new Set();
+  return items.filter((item) => {
+    if (seenStableIds.has(item.stable_id)) {
+      return false;
+    }
+    seenStableIds.add(item.stable_id);
+    return true;
+  });
+}
+function compareDescriptionIndexItems(left, right) {
+  return left.stable_id.localeCompare(right.stable_id);
+}
+
 // src/tools/plan-context.ts
 function registerPlanContext(server, tracker) {
   server.registerTool(
@@ -106,11 +639,11 @@ function registerPlanContext(server, tracker) {
       annotations: planContextAnnotations
     },
     async ({ paths, intent, known_tech, detected_entities, client_hash, correlation_id, session_id }) => {
-      const requestId = randomUUID();
+      const requestId = randomUUID2();
       tracker?.enter(requestId);
       try {
         const projectRoot = resolveProjectRoot();
-        const syncReport = await ensureRulesFresh(projectRoot);
+        const syncReport = await ensureKnowledgeFresh(projectRoot);
         const result = await planContext(projectRoot, {
           paths,
           intent,
@@ -126,7 +659,7 @@ function registerPlanContext(server, tracker) {
         };
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
-        const guardResult = enforcePayloadLimit(serialized, payloadLimits);
+        const guardResult = enforcePayloadLimit2(serialized, payloadLimits);
         if (guardResult.warning) {
           response.warnings = [
             ...response.warnings,
@@ -148,37 +681,1049 @@ function registerPlanContext(server, tracker) {
   );
 }
 
-// src/tools/rule-sections.ts
-import { randomUUID as randomUUID2 } from "crypto";
+// src/tools/review.ts
+import { randomUUID as randomUUID3 } from "crypto";
 import {
-  ruleSectionsAnnotations,
-  ruleSectionsInputSchema,
-  ruleSectionsOutputSchema
+  FabReviewInputSchema,
+  FabReviewOutputSchema,
+  fabReviewAnnotations
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
-import { enforcePayloadLimit as enforcePayloadLimit2 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
-function registerRuleSections(server, tracker) {
+import { enforcePayloadLimit as enforcePayloadLimit3 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+
+// src/services/review.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { readFile as readFile3, readdir, unlink } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { basename, join as join3, relative as relative2, resolve } from "path";
+
+// src/services/knowledge-id-allocator.ts
+import { readFile as readFile2 } from "fs/promises";
+import { dirname } from "path";
+import { mkdir } from "fs/promises";
+import {
+  AgentsMetaCountersSchema,
+  agentsMetaSchema,
+  allocateKnowledgeId,
+  defaultAgentsMetaCounters
+} from "@fenglimg/fabric-shared";
+import { atomicWriteJson } from "@fenglimg/fabric-shared/node/atomic-write";
+var KnowledgeIdAllocator = class {
+  constructor(metaPath) {
+    this.metaPath = metaPath;
+  }
+  metaPath;
+  /**
+   * Allocate the next stable_id for the given (layer, type) pair and persist
+   * the advanced counter to `agents.meta.json`.
+   */
+  async allocate(layer, type) {
+    const meta = await this.readMeta();
+    const counters = this.normalizeCounters(meta.counters);
+    const { id, nextCounters } = allocateKnowledgeId(layer, type, counters);
+    await this.writeMetaAtomic({ ...meta, counters: nextCounters });
+    return id;
+  }
+  /**
+   * Returns the current counters envelope, defaulting to all-zero slots when
+   * the meta file is absent or pre-v2.0 (counters key missing).
+   */
+  async getCounters() {
+    const meta = await this.readMeta();
+    return this.normalizeCounters(meta.counters);
+  }
+  // ---- internal helpers ------------------------------------------------
+  async readMeta() {
+    let raw;
+    try {
+      raw = await readFile2(this.metaPath, "utf8");
+    } catch (err) {
+      if (isNodeError(err) && err.code === "ENOENT") {
+        return { revision: "", nodes: {} };
+      }
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return { revision: "", nodes: {} };
+    }
+    const validation = agentsMetaSchema.safeParse(parsed);
+    if (validation.success) {
+      return validation.data;
+    }
+    return parsed && typeof parsed === "object" ? parsed : {};
+  }
+  normalizeCounters(input) {
+    if (input === void 0 || input === null) {
+      return defaultAgentsMetaCounters();
+    }
+    const parsed = AgentsMetaCountersSchema.safeParse(input);
+    return parsed.success ? parsed.data : defaultAgentsMetaCounters();
+  }
+  async writeMetaAtomic(meta) {
+    await ensureParentDirectory2(this.metaPath);
+    await atomicWriteJson(this.metaPath, meta, { indent: 2 });
+  }
+};
+async function ensureParentDirectory2(filePath) {
+  await mkdir(dirname(filePath), { recursive: true });
+}
+function isNodeError(err) {
+  return err instanceof Error && typeof err.code === "string";
+}
+
+// src/services/review.ts
+var PENDING_BASE_TEAM_REL = ".fabric/knowledge/pending";
+function pendingBaseAbs(layer, projectRoot) {
+  if (layer === "personal") {
+    return join3(resolvePersonalRoot2(), ".fabric", "knowledge", "pending");
+  }
+  return join3(projectRoot, PENDING_BASE_TEAM_REL);
+}
+var PLURAL_TYPES = [
+  "decisions",
+  "pitfalls",
+  "guidelines",
+  "models",
+  "processes"
+];
+var PLURAL_TO_SINGULAR = {
+  decisions: "decision",
+  pitfalls: "pitfall",
+  guidelines: "guideline",
+  models: "model",
+  processes: "process"
+};
+async function reviewKnowledge(projectRoot, input) {
+  switch (input.action) {
+    case "list":
+      return {
+        action: "list",
+        items: await listPending(projectRoot, input.filters)
+      };
+    case "approve":
+      return {
+        action: "approve",
+        approved: await approveAll(projectRoot, input.pending_paths)
+      };
+    case "reject":
+      return {
+        action: "reject",
+        rejected: await rejectAll(projectRoot, input.pending_paths, input.reason)
+      };
+    case "modify":
+      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",
+        deferred: await deferAll(
+          projectRoot,
+          input.pending_paths,
+          input.until,
+          input.reason
+        )
+      };
+    default: {
+      const exhaustive = input;
+      throw new Error(`unsupported action: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+function resolveSandboxedPath(projectRoot, candidate, options = {}) {
+  if (candidate.length === 0) {
+    throw new Error("path is empty");
+  }
+  const projectKnowledgeRoot = resolve(projectRoot, ".fabric", "knowledge");
+  const personalKnowledgeRoot = resolve(resolvePersonalRoot2(), ".fabric", "knowledge");
+  if (candidate.startsWith("~/")) {
+    if (options.allowPersonal !== true) {
+      throw new Error(`personal-root path not allowed for this action: ${candidate}`);
+    }
+    const abs = resolve(resolvePersonalRoot2(), candidate.slice(2));
+    if (abs !== personalKnowledgeRoot && !abs.startsWith(personalKnowledgeRoot + "/")) {
+      throw new Error(`path escapes personal knowledge root: ${candidate}`);
+    }
+    return { abs, isInProjectTree: false };
+  }
+  const projectAbs = resolve(projectRoot, candidate);
+  if (projectAbs === projectKnowledgeRoot || projectAbs.startsWith(projectKnowledgeRoot + "/")) {
+    return { abs: projectAbs, isInProjectTree: true };
+  }
+  if (options.allowPersonal === true) {
+    const personalAbs = resolve(resolvePersonalRoot2(), candidate);
+    if (personalAbs === personalKnowledgeRoot || personalAbs.startsWith(personalKnowledgeRoot + "/")) {
+      return { abs: personalAbs, isInProjectTree: false };
+    }
+  }
+  throw new Error(`path escapes knowledge root: ${candidate}`);
+}
+async function listPending(projectRoot, filters) {
+  const items = [];
+  const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
+  const sources = [
+    { origin: "team", root: pendingBaseAbs("team", projectRoot) },
+    { origin: "personal", root: pendingBaseAbs("personal", projectRoot) }
+  ];
+  for (const source of sources) {
+    for (const type of typesToScan) {
+      const dir = join3(source.root, type);
+      if (!existsSync3(dir)) {
+        continue;
+      }
+      let entries;
+      try {
+        entries = await readdir(dir);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        if (!name.endsWith(".md")) continue;
+        const absolutePath = join3(dir, name);
+        let content;
+        try {
+          content = await readFile3(absolutePath, "utf8");
+        } catch {
+          continue;
+        }
+        const fm = parseFrontmatter(content);
+        const layer = fm.layer ?? (source.origin === "personal" ? "personal" : "team");
+        const maturity = fm.maturity ?? "draft";
+        if (filters?.layer !== void 0 && filters.layer !== "both" && filters.layer !== layer) {
+          continue;
+        }
+        if (filters?.maturity !== void 0 && filters.maturity !== maturity) {
+          continue;
+        }
+        if (filters?.tags !== void 0 && filters.tags.length > 0) {
+          const itemTags = fm.tags ?? [];
+          const hasAll = filters.tags.every((t) => itemTags.includes(t));
+          if (!hasAll) continue;
+        }
+        if (filters?.created_after !== void 0) {
+          const createdAt = fm.created_at;
+          if (createdAt === void 0 || createdAt < filters.created_after) {
+            continue;
+          }
+        }
+        const reportedPath = source.origin === "personal" ? `~/${relative2(resolvePersonalRoot2(), absolutePath)}` : relative2(projectRoot, absolutePath);
+        items.push({
+          pending_path: reportedPath,
+          type,
+          layer,
+          maturity,
+          origin: source.origin,
+          ...fm.tags !== void 0 && fm.tags.length > 0 ? { tags: fm.tags } : {}
+        });
+      }
+    }
+  }
+  return items;
+}
+async function approveAll(projectRoot, pendingPaths) {
+  const allocator = new KnowledgeIdAllocator(
+    join3(projectRoot, ".fabric", "agents.meta.json")
+  );
+  const approved = [];
+  for (const pendingPath of pendingPaths) {
+    const result = await approveOne(projectRoot, pendingPath, allocator);
+    if (result !== null) {
+      approved.push(result);
+    }
+  }
+  return approved;
+}
+async function approveOne(projectRoot, pendingPath, allocator) {
+  let sourceAbs;
+  let sourceOrigin;
+  try {
+    const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
+    const teamPendingAbs = pendingBaseAbs("team", projectRoot);
+    const personalPendingAbs = pendingBaseAbs("personal", projectRoot);
+    const inTeamPending = sandboxed.abs === teamPendingAbs || sandboxed.abs.startsWith(teamPendingAbs + "/");
+    const inPersonalPending = sandboxed.abs === personalPendingAbs || sandboxed.abs.startsWith(personalPendingAbs + "/");
+    if (!inTeamPending && !inPersonalPending) {
+      throw new Error(`approve path is outside .fabric/knowledge/pending/: ${pendingPath}`);
+    }
+    sourceAbs = sandboxed.abs;
+    sourceOrigin = inPersonalPending ? "personal" : "team";
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    await emitEventBestEffort2(projectRoot, {
+      event_type: "knowledge_promote_failed",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      reason: `approve:${pendingPath}: ${reason}`
+    });
+    return null;
+  }
+  const slug = basename(pendingPath).replace(/\.md$/u, "");
+  await emitEventBestEffort2(projectRoot, {
+    event_type: "knowledge_promote_started",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    reason: `approve:${slug}`
+  });
+  let allocatedId;
+  let targetAbs;
+  let writtenTarget = false;
+  try {
+    const content = await readFile3(sourceAbs, "utf8");
+    const fm = parseFrontmatter(content);
+    const pluralType = fm.type;
+    if (pluralType === void 0 || !PLURAL_TYPES.includes(pluralType)) {
+      throw new Error(`pending file missing or invalid 'type' frontmatter: ${pendingPath}`);
+    }
+    const layer = fm.layer ?? "team";
+    const singularType = PLURAL_TO_SINGULAR[pluralType];
+    const stableId = await allocator.allocate(layer, singularType);
+    allocatedId = stableId;
+    const newFilename = `${stableId}--${slug}.md`;
+    const layerRoot = layer === "personal" ? join3(resolvePersonalRoot2(), ".fabric") : join3(projectRoot, ".fabric");
+    targetAbs = join3(layerRoot, "knowledge", pluralType, newFilename);
+    await ensureParentDirectory(targetAbs);
+    const rewritten = rewriteFrontmatterForPromote(content, stableId);
+    await atomicWriteText(targetAbs, rewritten);
+    writtenTarget = true;
+    if (sourceOrigin === "team") {
+      try {
+        execFileSync("git", ["rm", "--quiet", "-f", pendingPath], {
+          cwd: projectRoot,
+          stdio: ["ignore", "pipe", "pipe"]
+        });
+      } catch {
+        if (existsSync3(sourceAbs)) {
+          await unlink(sourceAbs);
+        }
+      }
+    } else {
+      if (existsSync3(sourceAbs)) {
+        await unlink(sourceAbs);
+      }
+    }
+    await emitEventBestEffort2(projectRoot, {
+      event_type: "knowledge_promoted",
+      stable_id: stableId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      reason: `approve:${slug}`
+    });
+    return { pending_path: pendingPath, stable_id: stableId };
+  } catch (err) {
+    if (writtenTarget && targetAbs !== void 0 && existsSync3(targetAbs)) {
+      try {
+        await unlink(targetAbs);
+      } catch {
+      }
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    await emitEventBestEffort2(projectRoot, {
+      event_type: "knowledge_promote_failed",
+      ...allocatedId !== void 0 ? { stable_id: allocatedId } : {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      reason: `approve:${slug}: ${reason}`
+    });
+    return null;
+  }
+}
+async function rejectAll(projectRoot, pendingPaths, reason) {
+  const rejected = [];
+  for (const pendingPath of pendingPaths) {
+    await emitEventBestEffort2(projectRoot, {
+      event_type: "knowledge_rejected",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      reason: `reject:${pendingPath}: ${reason}`
+    });
+    rejected.push(pendingPath);
+  }
+  return rejected;
+}
+async function modifyEntry(projectRoot, pendingPath, changes) {
+  const target = resolveModifyTarget(projectRoot, pendingPath);
+  if (target === null) {
+    throw new Error(`modify target not found: ${pendingPath}`);
+  }
+  const content = await readFile3(target.absPath, "utf8");
+  const fm = parseFrontmatter(content);
+  const currentLayer = fm.layer ?? "team";
+  if (changes.layer !== void 0 && changes.layer !== currentLayer) {
+    return await modifyLayerFlip(projectRoot, target, content, fm, changes);
+  }
+  const merged = rewriteFrontmatterMerge(content, changes);
+  await atomicWriteText(target.absPath, merged);
+  return {
+    action: "modify",
+    pending_path: pendingPath
+  };
+}
+function resolveModifyTarget(projectRoot, pendingPath) {
+  let sandboxed;
+  try {
+    sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
+  } catch {
+    return null;
+  }
+  if (existsSync3(sandboxed.abs)) {
+    return {
+      absPath: sandboxed.abs,
+      isInProjectTree: sandboxed.isInProjectTree,
+      inferredType: inferTypeFromPath(pendingPath),
+      slug: extractSlug(pendingPath)
+    };
+  }
+  return null;
+}
+function inferTypeFromPath(path2) {
+  const match = /knowledge\/(?:pending\/)?([^/]+)\/[^/]+\.md$/u.exec(path2);
+  if (match === null) return null;
+  const seg = match[1];
+  if (seg !== void 0 && PLURAL_TYPES.includes(seg)) {
+    return seg;
+  }
+  return null;
+}
+function extractSlug(path2) {
+  const file = basename(path2).replace(/\.md$/u, "");
+  return file.replace(/^K[PT]-(MOD|DEC|GLD|PIT|PRO)-\d+--/u, "");
+}
+async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
+  const fromLayer = fm.layer ?? "team";
+  const toLayer = changes.layer;
+  const pluralType = fm.type ?? target.inferredType;
+  if (pluralType === null || pluralType === void 0) {
+    throw new Error(`layer-flip requires a known type; could not infer for ${target.absPath}`);
+  }
+  const slug = target.slug;
+  const priorStableId = fm.id;
+  const fromScope = fm.relevance_scope ?? "broad";
+  const shouldAutoDegrade = fromScope === "narrow" && fromLayer === "team" && toLayer === "personal";
+  const allocator = new KnowledgeIdAllocator(
+    join3(projectRoot, ".fabric", "agents.meta.json")
+  );
+  const singularType = PLURAL_TO_SINGULAR[pluralType];
+  const newStableId = await allocator.allocate(toLayer, singularType);
+  const toRoot = toLayer === "personal" ? join3(resolvePersonalRoot2(), ".fabric") : join3(projectRoot, ".fabric");
+  const toAbs = join3(toRoot, "knowledge", pluralType, `${newStableId}--${slug}.md`);
+  await ensureParentDirectory(toAbs);
+  await emitEventBestEffort2(projectRoot, {
+    event_type: "knowledge_promote_started",
+    ...priorStableId !== void 0 ? { stable_id: priorStableId } : {},
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    reason: `layer_flip:${priorStableId ?? "<unassigned>"}->${newStableId}`
+  });
+  const effectivePatch = shouldAutoDegrade ? {
+    ...changes,
+    layer: toLayer,
+    relevance_scope: "broad",
+    relevance_paths: []
+  } : { ...changes, layer: toLayer };
+  const rewritten = rewriteFrontmatterMerge(content, effectivePatch, { id: newStableId });
+  await atomicWriteText(toAbs, rewritten);
+  if (target.isInProjectTree) {
+    const relSource = relative2(projectRoot, target.absPath);
+    try {
+      execFileSync("git", ["rm", "--quiet", "-f", relSource], {
+        cwd: projectRoot,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch {
+      if (existsSync3(target.absPath)) {
+        await unlink(target.absPath);
+      }
+    }
+  } else if (existsSync3(target.absPath)) {
+    await unlink(target.absPath);
+  }
+  await emitEventBestEffort2(projectRoot, {
+    event_type: "knowledge_layer_changed",
+    stable_id: newStableId,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    from_layer: fromLayer,
+    to_layer: toLayer,
+    reason: `layer_flip:${priorStableId ?? "<unassigned>"}->${newStableId}`
+  });
+  if (shouldAutoDegrade) {
+    await emitEventBestEffort2(projectRoot, {
+      event_type: "knowledge_scope_degraded",
+      stable_id: newStableId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      from_scope: "narrow",
+      to_scope: "broad",
+      reason: "personal-implies-broad"
+    });
+  }
+  const responsePath = toLayer === "team" ? relative2(projectRoot, toAbs) : `~/${relative2(resolvePersonalRoot2(), toAbs)}`;
+  return {
+    action: "modify",
+    pending_path: responsePath,
+    ...priorStableId !== void 0 ? { prior_stable_id: priorStableId } : {},
+    new_stable_id: newStableId
+  };
+}
+async function searchEntries(projectRoot, query, filters) {
+  const lowerQuery = query.toLowerCase();
+  const items = [];
+  const sources = [
+    { root: pendingBaseAbs("team", projectRoot), isPending: true, isPersonal: false },
+    { root: pendingBaseAbs("personal", projectRoot), isPending: true, isPersonal: true },
+    { root: join3(projectRoot, ".fabric", "knowledge"), isPending: false, isPersonal: false },
+    { root: join3(resolvePersonalRoot2(), ".fabric", "knowledge"), isPending: false, isPersonal: true }
+  ];
+  const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
+  for (const source of sources) {
+    for (const type of typesToScan) {
+      const dir = join3(source.root, type);
+      if (!existsSync3(dir)) continue;
+      let entries;
+      try {
+        entries = await readdir(dir);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        if (!name.endsWith(".md")) continue;
+        const absolutePath = join3(dir, name);
+        let content;
+        try {
+          content = await readFile3(absolutePath, "utf8");
+        } catch {
+          continue;
+        }
+        const fm = parseFrontmatter(content);
+        const layer = fm.layer ?? (source.isPersonal ? "personal" : "team");
+        const maturity = fm.maturity ?? "draft";
+        if (filters?.layer !== void 0 && filters.layer !== "both" && filters.layer !== layer) {
+          continue;
+        }
+        if (filters?.maturity !== void 0 && filters.maturity !== maturity) {
+          continue;
+        }
+        if (filters?.tags !== void 0 && filters.tags.length > 0) {
+          const itemTags = fm.tags ?? [];
+          const hasAll = filters.tags.every((t) => itemTags.includes(t));
+          if (!hasAll) continue;
+        }
+        if (filters?.created_after !== void 0) {
+          const createdAt = fm.created_at;
+          if (createdAt === void 0 || createdAt < filters.created_after) {
+            continue;
+          }
+        }
+        const haystacks = [
+          fm.title ?? "",
+          fm.summary ?? "",
+          ...fm.tags ?? [],
+          name
+        ].map((s) => s.toLowerCase());
+        const matches = haystacks.some((h) => h.includes(lowerQuery));
+        if (!matches) continue;
+        const reportedPath = source.isPersonal ? `~/${relative2(resolvePersonalRoot2(), absolutePath)}` : relative2(projectRoot, absolutePath);
+        items.push({
+          pending_path: reportedPath,
+          type,
+          layer,
+          maturity,
+          // Only pending entries carry an origin tag (search results that are
+          // canonical entries don't have a pending root to point back to).
+          ...source.isPending ? { origin: source.isPersonal ? "personal" : "team" } : {},
+          ...fm.tags !== void 0 && fm.tags.length > 0 ? { tags: fm.tags } : {},
+          ...fm.title !== void 0 ? { title: fm.title } : {},
+          ...fm.summary !== void 0 ? { summary: fm.summary } : {}
+        });
+      }
+    }
+  }
+  return items;
+}
+async function deferAll(projectRoot, pendingPaths, until, reason) {
+  const deferred = [];
+  for (const pendingPath of pendingPaths) {
+    await emitEventBestEffort2(projectRoot, {
+      event_type: "knowledge_deferred",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...until !== void 0 ? { until } : {},
+      ...reason !== void 0 ? { reason } : {}
+    });
+    deferred.push(pendingPath);
+  }
+  return deferred;
+}
+function parseFrontmatter(content) {
+  const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/u.exec(content);
+  if (match === null) {
+    return {};
+  }
+  const block = match[1];
+  if (block === void 0) {
+    return {};
+  }
+  const out = {};
+  for (const rawLine of block.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    const sep = line.indexOf(":");
+    if (sep === -1) continue;
+    const key = line.slice(0, sep).trim();
+    const value = line.slice(sep + 1).trim();
+    switch (key) {
+      case "id":
+        out.id = stripQuotes(value);
+        break;
+      case "type":
+        if (PLURAL_TYPES.includes(value)) {
+          out.type = value;
+        }
+        break;
+      case "layer":
+        if (value === "team" || value === "personal") {
+          out.layer = value;
+        }
+        break;
+      case "maturity":
+        if (value === "draft" || value === "verified" || value === "proven") {
+          out.maturity = value;
+        }
+        break;
+      case "source_session":
+        out.source_session = stripQuotes(value);
+        break;
+      case "created_at":
+        out.created_at = stripQuotes(value);
+        break;
+      case "tags":
+        out.tags = parseFlowArray(value);
+        break;
+      case "title":
+        out.title = stripQuotes(value);
+        break;
+      case "summary":
+        out.summary = stripQuotes(value);
+        break;
+      case "relevance_scope":
+        if (value === "narrow" || value === "broad") {
+          out.relevance_scope = value;
+        }
+        break;
+      case "relevance_paths":
+        out.relevance_paths = parseFlowArray(value);
+        break;
+      default:
+        break;
+    }
+  }
+  return out;
+}
+function stripQuotes(value) {
+  return value.replace(/^["'](.*)["']$/u, "$1");
+}
+function parseFlowArray(value) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+    return [];
+  }
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner.length === 0) {
+    return [];
+  }
+  return inner.split(",").map((item) => stripQuotes(item.trim())).filter((item) => item.length > 0);
+}
+function rewriteFrontmatterForPromote(content, stableId) {
+  const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u.exec(content);
+  if (match === null) {
+    return `---
+id: ${stableId}
+---
+
+${content}`;
+  }
+  const block = match[1] ?? "";
+  const filteredLines = block.split(/\r?\n/u).filter((line) => !/^x-fabric-idempotency-key\s*:/u.test(line));
+  filteredLines.unshift(`id: ${stableId}`);
+  const newBlock = filteredLines.join("\n");
+  const before = content.slice(0, match.index);
+  const after = content.slice(match.index + match[0].length);
+  return `${before}---
+${newBlock}
+---${after}`;
+}
+function rewriteFrontmatterMerge(content, patch, forced) {
+  const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u.exec(content);
+  if (match === null) {
+    const synthLines = [];
+    if (forced?.id !== void 0) synthLines.push(`id: ${forced.id}`);
+    appendPatchLines(synthLines, patch);
+    return `---
+${synthLines.join("\n")}
+---
+
+${content}`;
+  }
+  const block = match[1] ?? "";
+  const updates = {};
+  if (forced?.id !== void 0) updates.id = `id: ${forced.id}`;
+  if (patch.title !== void 0) updates.title = `title: ${quoteIfNeeded(patch.title)}`;
+  if (patch.summary !== void 0) updates.summary = `summary: ${quoteIfNeeded(patch.summary)}`;
+  if (patch.layer !== void 0) updates.layer = `layer: ${patch.layer}`;
+  if (patch.maturity !== void 0) updates.maturity = `maturity: ${patch.maturity}`;
+  if (patch.tags !== void 0) updates.tags = `tags: [${patch.tags.join(", ")}]`;
+  if (patch.relevance_scope !== void 0) updates.relevance_scope = `relevance_scope: ${patch.relevance_scope}`;
+  if (patch.relevance_paths !== void 0) updates.relevance_paths = `relevance_paths: [${patch.relevance_paths.join(", ")}]`;
+  const lines = block.split(/\r?\n/u);
+  const seen = /* @__PURE__ */ new Set();
+  const newLines = [];
+  for (const line of lines) {
+    const sep = line.indexOf(":");
+    const key = sep === -1 ? "" : line.slice(0, sep).trim();
+    if (key in updates) {
+      newLines.push(updates[key]);
+      seen.add(key);
+    } else {
+      newLines.push(line);
+    }
+  }
+  for (const key of Object.keys(updates)) {
+    if (!seen.has(key)) {
+      newLines.push(updates[key]);
+    }
+  }
+  const newBlock = newLines.join("\n");
+  const before = content.slice(0, match.index);
+  const after = content.slice(match.index + match[0].length);
+  return `${before}---
+${newBlock}
+---${after}`;
+}
+function appendPatchLines(lines, patch) {
+  if (patch.title !== void 0) lines.push(`title: ${quoteIfNeeded(patch.title)}`);
+  if (patch.summary !== void 0) lines.push(`summary: ${quoteIfNeeded(patch.summary)}`);
+  if (patch.layer !== void 0) lines.push(`layer: ${patch.layer}`);
+  if (patch.maturity !== void 0) lines.push(`maturity: ${patch.maturity}`);
+  if (patch.tags !== void 0) lines.push(`tags: [${patch.tags.join(", ")}]`);
+  if (patch.relevance_scope !== void 0) lines.push(`relevance_scope: ${patch.relevance_scope}`);
+  if (patch.relevance_paths !== void 0) lines.push(`relevance_paths: [${patch.relevance_paths.join(", ")}]`);
+}
+function quoteIfNeeded(value) {
+  if (/[\n\r]/u.test(value)) {
+    return JSON.stringify(value);
+  }
+  if (/[:#\[\]{}&*!|>'"%@`,]|^\s|\s$/u.test(value)) {
+    return `"${value.replace(/"/gu, '\\"')}"`;
+  }
+  return value;
+}
+function resolvePersonalRoot2() {
+  return process.env.FABRIC_HOME ?? homedir2();
+}
+async function emitEventBestEffort2(projectRoot, event) {
+  try {
+    await appendEventLedgerEvent(projectRoot, event);
+  } catch {
+  }
+}
+
+// src/tools/review.ts
+function registerReview(server, tracker) {
   server.registerTool(
-    "fab_get_rule_sections",
+    "fab_review",
+    {
+      description: "Review pending knowledge entries under .fabric/knowledge/pending/. Discriminated by `action`: list (enumerate), approve (allocate stable_id and promote to canonical layer/type path), reject/modify/search/defer (TASK-002). Skill-side tool \u2014 invoked by fabric-review.",
+      // Discriminated union schemas — passed whole (registerTool accepts
+      // `AnySchema` in addition to `ZodRawShape`; see @modelcontextprotocol/sdk
+      // mcp.d.ts:150).
+      inputSchema: FabReviewInputSchema,
+      outputSchema: FabReviewOutputSchema,
+      annotations: fabReviewAnnotations
+    },
+    async (input) => {
+      const requestId = randomUUID3();
+      tracker?.enter(requestId);
+      try {
+        const projectRoot = resolveProjectRoot();
+        const result = await reviewKnowledge(projectRoot, input);
+        const response = result;
+        const payloadLimits = readPayloadLimits(projectRoot);
+        const serialized = JSON.stringify(response);
+        enforcePayloadLimit3(serialized, payloadLimits);
+        return {
+          content: [{ type: "text", text: JSON.stringify(response) }],
+          structuredContent: response
+        };
+      } finally {
+        tracker?.exit(requestId);
+      }
+    }
+  );
+}
+
+// src/tools/knowledge-sections.ts
+import { randomUUID as randomUUID4 } from "crypto";
+import {
+  knowledgeSectionsAnnotations,
+  knowledgeSectionsInputSchema,
+  knowledgeSectionsOutputSchema
+} from "@fenglimg/fabric-shared/schemas/api-contracts";
+import { enforcePayloadLimit as enforcePayloadLimit4 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+
+// src/services/knowledge-sections.ts
+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);
+    }
+  }
+  flush();
+  return new Map(
+    Array.from(sections.entries()).map(([section, values]) => [section, values.join("\n\n")])
+  );
+}
+async function getKnowledgeSections(projectRoot, input) {
+  const token = readSelectionToken(input.selection_token);
+  if (token === void 0) {
+    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 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 description = rule.node.description;
+    if (description !== void 0 && description.knowledge_type === void 0 && description.knowledge_layer === void 0) {
+      diagnostics.push({
+        code: "missing_knowledge_metadata",
+        severity: "warn",
+        stable_id: rule.stable_id,
+        message: `Rule ${rule.stable_id} has no knowledge metadata (type/layer) \u2014 likely an un-migrated v1.x entry.`
+      });
+    }
+    rules.push({
+      stable_id: rule.stable_id,
+      level: rule.level,
+      path: rule.path,
+      sections
+    });
+  }
+  const result = {
+    revision_hash: meta.revision,
+    precedence: ["L2", "L1", "L0"],
+    selected_stable_ids: rules.map((rule) => rule.stable_id),
+    rules,
+    diagnostics
+  };
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "knowledge_selection",
+      selection_token: input.selection_token,
+      target_paths: token.target_paths,
+      required_stable_ids: token.required_stable_ids,
+      ai_selectable_stable_ids: token.ai_selectable_stable_ids,
+      ai_selected_stable_ids: input.ai_selected_stable_ids,
+      final_stable_ids: result.selected_stable_ids,
+      ai_selection_reasons: pickSelectionReasons(input.ai_selected_stable_ids, input.ai_selection_reasons),
+      rejected_stable_ids: [],
+      ignored_stable_ids: [],
+      correlation_id: input.correlation_id,
+      session_id: input.session_id
+    });
+  } catch {
+  }
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "knowledge_sections_fetched",
+      selection_token: input.selection_token,
+      target_paths: token.target_paths,
+      requested_sections: input.sections,
+      final_stable_ids: result.selected_stable_ids,
+      ai_selected_stable_ids: input.ai_selected_stable_ids,
+      diagnostics,
+      correlation_id: input.correlation_id,
+      session_id: input.session_id
+    });
+  } catch {
+  }
+  const consumedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const consumedClientHash = input.client_hash ?? "";
+  const emittedConsumed = /* @__PURE__ */ new Set();
+  for (const stableId of result.selected_stable_ids) {
+    if (emittedConsumed.has(stableId)) {
+      continue;
+    }
+    emittedConsumed.add(stableId);
+    try {
+      await appendEventLedgerEvent(projectRoot, {
+        event_type: "knowledge_consumed",
+        stable_id: stableId,
+        consumed_at: consumedAt,
+        client_hash: consumedClientHash,
+        correlation_id: input.correlation_id,
+        session_id: input.session_id
+      });
+    } catch {
+    }
+  }
+  return result;
+}
+function validateAiSelections(aiSelectableStableIds, aiSelectedStableIds, aiSelectionReasons) {
+  const selectable = new Set(aiSelectableStableIds);
+  for (const stableId of aiSelectedStableIds) {
+    if (!selectable.has(stableId)) {
+      throw new Error(`Invalid L1 rule selection: ${stableId}`);
+    }
+    if (aiSelectionReasons[stableId]?.trim() === "") {
+      throw new Error(`Missing AI selection reason for ${stableId}`);
+    }
+    if (aiSelectionReasons[stableId] === void 0) {
+      throw new Error(`Missing AI selection reason for ${stableId}`);
+    }
+  }
+}
+function findRuleNode(meta, stableId) {
+  for (const [nodeId, node] of Object.entries(meta.nodes)) {
+    const nodeStableId = node.stable_id ?? nodeId;
+    if (nodeStableId !== stableId) {
+      continue;
+    }
+    const level = node.level ?? node.layer ?? "L2";
+    return {
+      stable_id: nodeStableId,
+      level,
+      path: normalizeKnowledgePath(node.content_ref ?? node.file),
+      priority: node.priority ?? "medium",
+      node
+    };
+  }
+  throw new Error(`Selected rule is not present in agents.meta.json: ${stableId}`);
+}
+function sortRuleNodes(rules) {
+  return [...rules].sort((left, right) => {
+    const levelDelta = outputLevelOrder(left.level) - outputLevelOrder(right.level);
+    if (levelDelta !== 0) {
+      return levelDelta;
+    }
+    const priorityDelta = PRIORITY_ORDER[left.priority] - PRIORITY_ORDER[right.priority];
+    if (priorityDelta !== 0) {
+      return priorityDelta;
+    }
+    return left.stable_id.localeCompare(right.stable_id);
+  });
+}
+function outputLevelOrder(level) {
+  switch (level) {
+    case "L0":
+      return 0;
+    case "L1":
+      return 1;
+    case "L2":
+      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();
+    return join4(home, ".fabric", "knowledge", contentRef.slice("~/.fabric/knowledge/".length));
+  }
+  return join4(projectRoot, contentRef);
+}
+function pickSelectionReasons(selectedStableIds, reasons) {
+  return Object.fromEntries(selectedStableIds.map((stableId) => [stableId, reasons[stableId] ?? ""]));
+}
+
+// src/tools/knowledge-sections.ts
+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.",
-      inputSchema: ruleSectionsInputSchema,
-      outputSchema: ruleSectionsOutputSchema,
-      annotations: ruleSectionsAnnotations
+      inputSchema: knowledgeSectionsInputSchema,
+      outputSchema: knowledgeSectionsOutputSchema,
+      annotations: knowledgeSectionsAnnotations
     },
     async (input) => {
-      const requestId = randomUUID2();
+      const requestId = randomUUID4();
       tracker?.enter(requestId);
       try {
         const projectRoot = resolveProjectRoot();
-        const syncReport = await ensureRulesFresh(projectRoot);
-        const result = await getRuleSections(projectRoot, input);
+        const syncReport = await ensureKnowledgeFresh(projectRoot);
+        const result = await getKnowledgeSections(projectRoot, input);
         const response = {
           ...result,
           warnings: [...syncReport.warnings]
         };
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
-        const guardResult = enforcePayloadLimit2(serialized, payloadLimits);
+        const guardResult = enforcePayloadLimit4(serialized, payloadLimits);
         if (guardResult.warning) {
           response.warnings = [
             ...response.warnings,
@@ -304,34 +1849,40 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync2(join2(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync2(join2(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync4(join5(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync4(join5(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 rules from .fabric/rules/ via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
+  return `[startup] info: detected ${preexisting.join(", ")} at project root. Note: Fabric serves knowledge from .fabric/knowledge/ via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
 }
 function createFabricServer(tracker) {
   const server = new McpServer({
-    name: "fabric-context-server",
-    version: "1.8.0-rc.3"
+    name: "fabric-knowledge-server",
+    version: "2.0.0-rc.8"
   });
   registerPlanContext(server, tracker);
-  registerRuleSections(server, tracker);
+  registerKnowledgeSections(server, tracker);
+  registerExtractKnowledge(server, tracker);
+  registerReview(server, tracker);
   server.registerResource(
     "bootstrap README",
     AGENTS_MD_RESOURCE_URI,
     {
-      description: "L0 fabric bootstrap file \u2014 global agent instructions for this project",
+      description: "Legacy v1.x bootstrap anchor (deprecated in v2.0; kept as MCP contract shim)",
       mimeType: "text/markdown"
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const content = await readFile(join2(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
+      const path2 = join5(projectRoot, ".fabric", "bootstrap", "README.md");
+      let text = "";
+      if (existsSync4(path2)) {
+        text = await readFile5(path2, "utf8");
+      }
       return {
         contents: [
           {
             uri: AGENTS_MD_RESOURCE_URI,
             mimeType: "text/markdown",
-            text: content
+            text
           }
         ]
       };
@@ -343,7 +1894,7 @@ async function startStdioServer() {
   const tracker = createInFlightTracker();
   const projectRoot = resolveProjectRoot();
   const syncStart = Date.now();
-  const reconcileResult = await reconcileRules(projectRoot, { trigger: "startup" });
+  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
@@ -406,9 +1957,9 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-PXFWUKCA.js");
-  const { port, projectRoot, host = "127.0.0.1", authToken, dashboardDistPath, dev } = options;
-  const app = createFabricHttpApp({ projectRoot, host, authToken, dashboardDistPath, dev });
+  const { createFabricHttpApp } = await import("./http-AR26GYEV.js");
+  const { port, projectRoot, host = "127.0.0.1", authToken } = options;
+  const app = createFabricHttpApp({ projectRoot, host, authToken });
   return await new Promise((resolveServer, rejectServer) => {
     const server = app.listen(port, host);
     server.once("close", () => {
@@ -424,7 +1975,7 @@ async function startHttpServer(options) {
 }
 var entrypoint = process.argv[1];
 var currentFilePath = fileURLToPath(import.meta.url);
-var isMainModule = entrypoint !== void 0 && resolve(entrypoint) === currentFilePath;
+var isMainModule = entrypoint !== void 0 && resolve2(entrypoint) === currentFilePath;
 if (isMainModule) {
   void startStdioServer().catch((error) => {
     writeStderr(formatError(error));
@@ -434,33 +1985,40 @@ if (isMainModule) {
 export {
   AGENTS_MD_RESOURCE_URI,
   EVENT_LEDGER_PATH,
+  KnowledgeIdAllocator,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
   ServeLockHeldError,
   acquireLock,
-  buildRuleMeta,
+  appendEventLedgerEvent,
+  buildKnowledgeMeta,
   checkLockOrThrow,
-  computeRuleTestIndex,
-  computeRulesBasedAgentsMeta,
+  computeKnowledgeBasedAgentsMeta,
+  computeKnowledgeTestIndex,
   createFabricServer,
   createInFlightTracker,
   createShutdownHandler,
-  deriveRuleMetaLayer,
-  deriveRuleMetaTopologyType,
-  ensureRulesFresh,
+  deriveKnowledgeMetaLayer,
+  deriveKnowledgeMetaTopologyType,
+  ensureKnowledgeFresh,
+  extractKnowledge,
   flushAndSyncEventLedger,
   formatPreexistingRootMessage,
   getEventLedgerPath,
   getLedgerPath,
   getLegacyLedgerPath,
-  isSameRuleTestIndex,
+  isSameKnowledgeTestIndex,
+  planContext,
   readLockState,
-  reconcileRules,
+  readSelectionToken,
+  reconcileKnowledge,
   releaseLock,
+  reviewKnowledge,
+  runDoctorApplyLint,
   runDoctorFix,
   runDoctorReport,
   stableStringify,
   startHttpServer,
   startStdioServer,
-  writeRuleMeta
+  writeKnowledgeMeta
 };