@fenglimg/fabric-server 2.0.0-rc.10 → 2.0.0-rc.11

package/dist/{chunk-AR2HV5JT.js → chunk-MMGHD42I.js}

@@ -1381,6 +1381,7 @@ async function runDoctorReport(target) {
   const relevancePathsDrift = inspectRelevancePathsDrift(projectRoot);
   const narrowTooFew = inspectNarrowTooFew(projectRoot, lintNow);
   const sessionHintsStale = inspectSessionHintsStale(projectRoot, lintNow);
+  const relevanceFieldsMissing = inspectRelevanceFieldsMissing(projectRoot);
   const checks = [
     createBootstrapAnchorCheck(bootstrapAnchor),
     createKnowledgeDirMissingCheck(knowledgeDirMissing),
@@ -1436,6 +1437,10 @@ async function runDoctorReport(target) {
     createNarrowTooFewCheck(narrowTooFew),
     // rc.6 TASK-021 (E3): session-hints cache hygiene (lint #27). Info kind.
     createSessionHintsStaleCheck(sessionHintsStale),
+    // v2.0.0-rc.9 TASK-003 (A3): relevance fields back-fill (lint #28).
+    // Info kind — applies to pending entries only; canonical entries get
+    // the fields written verbatim by fab_review.approve/modify.
+    createRelevanceFieldsMissingCheck(relevanceFieldsMissing),
     createPreexistingRootFilesCheck(preexistingRootFiles)
     // v2.0 / rc.2: `createLegacyClientPathCheck` removed. The schema now
     // rejects retired clientPaths keys (windsurf/rooCode/geminiCLI) at Zod
@@ -1592,6 +1597,24 @@ async function runDoctorApplyLint(target) {
   for (const candidate of sessionHintsStale.candidates) {
     mutations.push(await applySessionHintsStaleCleanup(projectRoot, candidate));
   }
+  const relevanceFieldsMissing = inspectRelevanceFieldsMissing(projectRoot);
+  let relevanceTouchedCount = 0;
+  for (const candidate of relevanceFieldsMissing.candidates) {
+    const mutation = await applyRelevanceFieldsMissing(candidate);
+    mutations.push(mutation);
+    if (mutation.applied) {
+      relevanceTouchedCount += 1;
+    }
+  }
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "relevance_migration_run",
+      timestamp: new Date(now).toISOString(),
+      scanned_count: relevanceFieldsMissing.scanned_count,
+      touched_count: relevanceTouchedCount
+    });
+  } catch {
+  }
   const meta = await inspectMeta(projectRoot);
   const indexDrift = inspectIndexDrift(projectRoot, meta);
   if (indexDrift.drifts.length > 0) {
@@ -3458,6 +3481,167 @@ function createRelevancePathsDriftCheck(inspection) {
     "Review whether the entry is still relevant \u2014 use `fab_review.modify` to refresh the anchors or `fab_review.reject` to archive."
   );
 }
+function inspectRelevanceFieldsMissing(projectRoot) {
+  const candidates = [];
+  let scannedCount = 0;
+  const FM_PATTERN = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u;
+  const teamRoot = join5(projectRoot, ".fabric", "knowledge", "pending");
+  const personalRoot = join5(
+    resolvePersonalRootForPending(),
+    ".fabric",
+    "knowledge",
+    "pending"
+  );
+  for (const [root, displayPrefix] of [
+    [teamRoot, ".fabric/knowledge/pending"],
+    [personalRoot, "~/.fabric/knowledge/pending"]
+  ]) {
+    if (!existsSync4(root)) {
+      continue;
+    }
+    let typeDirs = [];
+    try {
+      typeDirs = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    } catch {
+      continue;
+    }
+    for (const typeDir of typeDirs) {
+      const dir = join5(root, typeDir);
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md")) {
+          continue;
+        }
+        const absPath = join5(dir, entry.name);
+        let source;
+        try {
+          source = readFileSync(absPath, "utf8");
+        } catch {
+          continue;
+        }
+        const fm = FM_PATTERN.exec(source);
+        if (fm === null) {
+          continue;
+        }
+        scannedCount += 1;
+        const block = fm[1];
+        const missingScope = !RELEVANCE_SCOPE_LINE_PATTERN.test(block);
+        const missingPaths = !RELEVANCE_PATHS_LINE_PATTERN.test(block);
+        if (!missingScope && !missingPaths) {
+          continue;
+        }
+        candidates.push({
+          pending_path: posix.join(displayPrefix, typeDir, entry.name),
+          pending_path_abs: absPath,
+          missing_scope: missingScope,
+          missing_paths: missingPaths
+        });
+      }
+    }
+  }
+  candidates.sort((a, b) => a.pending_path.localeCompare(b.pending_path));
+  return { candidates, scanned_count: scannedCount };
+}
+function appendRelevanceFieldsToFrontmatter(source, needsScope, needsPaths) {
+  const FM_PATTERN = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u;
+  const fm = FM_PATTERN.exec(source);
+  if (fm === null) {
+    return null;
+  }
+  const block = fm[1];
+  const actuallyNeedsScope = needsScope && !RELEVANCE_SCOPE_LINE_PATTERN.test(block);
+  const actuallyNeedsPaths = needsPaths && !RELEVANCE_PATHS_LINE_PATTERN.test(block);
+  if (!actuallyNeedsScope && !actuallyNeedsPaths) {
+    return source;
+  }
+  const additions = [];
+  if (actuallyNeedsScope) {
+    additions.push("relevance_scope: broad");
+  }
+  if (actuallyNeedsPaths) {
+    additions.push("relevance_paths: []");
+  }
+  const trailing = block.endsWith("\n") ? "" : "\n";
+  const replacedBlock = `${block}${trailing}${additions.join("\n")}`;
+  const blockStart = source.indexOf(block);
+  if (blockStart < 0) {
+    return null;
+  }
+  return source.slice(0, blockStart) + replacedBlock + source.slice(blockStart + block.length);
+}
+async function applyRelevanceFieldsMissing(candidate) {
+  const parts = [];
+  if (candidate.missing_scope) parts.push("relevance_scope: broad");
+  if (candidate.missing_paths) parts.push("relevance_paths: []");
+  const detail = `back-filled: ${parts.join(", ")}`;
+  try {
+    const source = await readFile5(candidate.pending_path_abs, "utf8");
+    const rewritten = appendRelevanceFieldsToFrontmatter(
+      source,
+      candidate.missing_scope,
+      candidate.missing_paths
+    );
+    if (rewritten === null) {
+      return {
+        kind: "knowledge_relevance_fields_missing",
+        path: candidate.pending_path,
+        detail,
+        applied: false,
+        error: "frontmatter not parseable; cannot back-fill"
+      };
+    }
+    if (rewritten === source) {
+      return {
+        kind: "knowledge_relevance_fields_missing",
+        path: candidate.pending_path,
+        detail,
+        applied: false,
+        error: "fields already present at write time (no diff)"
+      };
+    }
+    await atomicWriteText3(candidate.pending_path_abs, rewritten);
+    return {
+      kind: "knowledge_relevance_fields_missing",
+      path: candidate.pending_path,
+      detail,
+      applied: true
+    };
+  } catch (error) {
+    return {
+      kind: "knowledge_relevance_fields_missing",
+      path: candidate.pending_path,
+      detail,
+      applied: false,
+      error: truncateErrorMessage(error)
+    };
+  }
+}
+function createRelevanceFieldsMissingCheck(inspection) {
+  if (inspection.candidates.length === 0) {
+    return okCheck(
+      "Knowledge relevance fields missing",
+      "All pending entries declare both relevance_scope and relevance_paths."
+    );
+  }
+  const first = inspection.candidates[0];
+  const missingParts = [];
+  if (first.missing_scope) missingParts.push("relevance_scope");
+  if (first.missing_paths) missingParts.push("relevance_paths");
+  const detail = `${first.pending_path} (missing: ${missingParts.join(", ")})`;
+  return issueCheck(
+    "Knowledge relevance fields missing",
+    "ok",
+    "info",
+    "knowledge_relevance_fields_missing",
+    `${inspection.candidates.length} pending entr${inspection.candidates.length === 1 ? "y is" : "ies are"} missing relevance_scope and/or relevance_paths in frontmatter. First: ${detail}.`,
+    "Run `fab doctor --apply-lint` to back-fill the schema defaults (relevance_scope: broad, relevance_paths: [])."
+  );
+}
 function createNarrowTooFewCheck(inspection) {
   const { structural_flagged, telemetry_flagged } = inspection;
   if (!structural_flagged && !telemetry_flagged) {

package/dist/{http-7HJQGQSN.js → http-U5RL5Q6P.js}

@@ -14,7 +14,7 @@ import {
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-AR2HV5JT.js";
+} from "./chunk-MMGHD42I.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";

package/dist/index.d.ts

@@ -77,7 +77,7 @@ type DoctorFixReport = {
     message: string;
     report: DoctorReport;
 };
-type DoctorApplyLintMutationKind = "knowledge_orphan_demote_required" | "knowledge_stale_archive_required" | "knowledge_index_drift" | "knowledge_pending_auto_archive" | "knowledge_session_hints_stale_cleanup";
+type DoctorApplyLintMutationKind = "knowledge_orphan_demote_required" | "knowledge_stale_archive_required" | "knowledge_index_drift" | "knowledge_pending_auto_archive" | "knowledge_session_hints_stale_cleanup" | "knowledge_relevance_fields_missing";
 type DoctorApplyLintMutation = {
     kind: DoctorApplyLintMutationKind;
     path: string;

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   sha256,
   stableStringify,
   writeKnowledgeMeta
-} from "./chunk-AR2HV5JT.js";
+} from "./chunk-MMGHD42I.js";
 
 // src/index.ts
 import { existsSync as existsSync4 } from "fs";
@@ -149,6 +149,21 @@ async function extractKnowledge(projectRoot, input) {
     };
   }
   const layer = input.layer ?? "team";
+  let relevanceScope = input.relevance_scope;
+  let relevancePaths = input.relevance_paths;
+  const shouldAutoDegrade = layer === "personal" && relevanceScope === "narrow";
+  if (shouldAutoDegrade) {
+    relevanceScope = "broad";
+    relevancePaths = [];
+    await emitEventBestEffort(projectRoot, {
+      event_type: "knowledge_scope_degraded",
+      stable_id: `pending:${idempotencyKey}`,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      from_scope: "narrow",
+      to_scope: "broad",
+      reason: "personal-implies-broad"
+    });
+  }
   const baseDir = pendingBase(layer, projectRoot);
   const absolutePath = join2(baseDir, input.type, `${sanitizedSlug}.md`);
   const reportedPath = layer === "personal" ? `~/${relative(resolvePersonalRoot(), absolutePath)}` : relative(projectRoot, absolutePath);
@@ -190,7 +205,9 @@ async function extractKnowledge(projectRoot, input) {
     recentPaths: input.recent_paths,
     layer,
     proposedReason: input.proposed_reason,
-    sessionContext: input.session_context
+    sessionContext: input.session_context,
+    relevanceScope,
+    relevancePaths
   });
   await atomicWriteText(absolutePath, fresh);
   await emitEventBestEffort(projectRoot, {
@@ -216,7 +233,7 @@ function sanitizeSlug(raw) {
 }
 function renderFreshEntry(args) {
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
-  const frontmatter = [
+  const frontmatterLines = [
     "---",
     `type: ${args.type}`,
     "maturity: draft",
@@ -224,10 +241,20 @@ function renderFreshEntry(args) {
     `created_at: ${createdAt}`,
     `source_sessions: [${args.sourceSessions.map((s) => JSON.stringify(s)).join(", ")}]`,
     `proposed_reason: ${args.proposedReason}`,
-    "tags: []",
+    "tags: []"
+  ];
+  if (args.relevanceScope !== void 0) {
+    frontmatterLines.push(`relevance_scope: ${args.relevanceScope}`);
+  }
+  if (args.relevancePaths !== void 0) {
+    const pathsBody = args.relevancePaths.map((p) => quoteRelevancePath(p)).join(", ");
+    frontmatterLines.push(`relevance_paths: [${pathsBody}]`);
+  }
+  frontmatterLines.push(
     `x-fabric-idempotency-key: ${args.idempotencyKey}`,
     "---"
-  ].join("\n");
+  );
+  const frontmatter = frontmatterLines.join("\n");
   const reasonExplanation = PROPOSED_REASON_DESCRIPTIONS[args.proposedReason];
   const body = [
     "",
@@ -251,6 +278,9 @@ function renderFreshEntry(args) {
   return `${frontmatter}
 ${body}`;
 }
+function quoteRelevancePath(value) {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
 function renderEvidenceBlock(summary, recentPaths) {
   const pathLines = recentPaths.length === 0 ? "_(no recent paths reported)_" : recentPaths.map((p) => `- ${p}`).join("\n");
   return [
@@ -1860,7 +1890,7 @@ function formatPreexistingRootMessage(projectRoot) {
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.10"
+    version: "2.0.0-rc.11"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);
@@ -1960,7 +1990,7 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-7HJQGQSN.js");
+  const { createFabricHttpApp } = await import("./http-U5RL5Q6P.js");
   const { port, projectRoot, host = "127.0.0.1", authToken } = options;
   const app = createFabricHttpApp({ projectRoot, host, authToken });
   return await new Promise((resolveServer, rejectServer) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.0.0-rc.10",
+  "version": "2.0.0-rc.11",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
     "express": "^5.2.1",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.0.0-rc.10"
+    "@fenglimg/fabric-shared": "2.0.0-rc.11"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",