@fenglimg/fabric-server 2.2.0-rc.8 → 2.2.0-rc.9

package/dist/index.d.ts

@@ -538,6 +538,37 @@ declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledg
  */
 declare function reviewKnowledge(projectRoot: string, input: FabReviewInput): Promise<FabReviewOutput>;
 
+/** A summary to be cold-judged, keyed by its stable_id. */
+interface ColdEvalCandidate {
+    stable_id: string;
+    summary: string;
+}
+/** The verdict the external cold-eval judge returns per candidate. */
+interface ColdEvalVerdict {
+    stable_id: string;
+    /** true when the summary alone is act-on sufficient without the body. */
+    self_sufficient: boolean;
+    /** When not self-sufficient, the judge's suggested act-on rewrite. */
+    suggested_summary?: string;
+    /** Short rationale (pointer-vs-thesis) for the verdict. */
+    reason?: string;
+}
+/** The batch request handed to the external (maestro delegate) cold-eval judge. */
+interface ColdEvalBatch {
+    rubric: string;
+    candidates: ColdEvalCandidate[];
+}
+declare const COLD_EVAL_RUBRIC: string;
+/**
+ * Build the cold-eval batch request for the external judge. Pure + deterministic:
+ * drops blank summaries (nothing to judge) and pairs the candidates with the
+ * zero-context rubric. The fabric-review skill hands the result to
+ * `maestro delegate` and applies the returned {@link ColdEvalVerdict}[] via
+ * fab_review modify. Returns a batch with an empty candidate list when nothing is
+ * judgeable, so callers can short-circuit without a delegate round-trip.
+ */
+declare function buildColdEvalBatch(candidates: ColdEvalCandidate[]): ColdEvalBatch;
+
 type StoredEventLedgerEvent = EventLedgerEvent;
 type ReadEventLedgerOptions = {
     event_type?: EventLedgerEvent["event_type"];
@@ -823,4 +854,4 @@ interface ShutdownHandlerDeps {
  */
 declare function createShutdownHandler(deps: ShutdownHandlerDeps): () => void;
 
-export { AGENTS_MD_RESOURCE_URI, type AlwaysActiveBody, type ArchiveHistoryEntry, type ArchiveHistoryReport, type CiteCoverageReport, type ConflictEntry, type ConflictJudge, type ConflictLintReport, type ConflictPair, type ConflictVerdict, DEFAULT_CONFLICT_SIMILARITY_THRESHOLD, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, FABRIC_SERVER_INSTRUCTIONS, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, type KnowledgeCensus, LEDGER_PATH, LEGACY_LEDGER_PATH, METRICS_LEDGER_PATH, METRIC_COUNTER_NAMES, type MetricCounterName, type MetricsRow, type PlanContextInput, type PlanContextResult, type RecallInput, type RecallResult, type RequirementProfile, type SelectionTokenState, type ShutdownHandlerDeps, type UnboundProjectViolation, appendEventLedgerEvent, buildAlwaysActiveBodies, buildKnowledgeCensus, bumpCounter, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, detectUnboundProject, drainCounters, enrichDescriptions, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, lintConflicts, loadConflictEntries, pairSimilarity, planContext, readEventLedger, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, resolveLedgerPaths, reviewKnowledge, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };
+export { AGENTS_MD_RESOURCE_URI, type AlwaysActiveBody, type ArchiveHistoryEntry, type ArchiveHistoryReport, COLD_EVAL_RUBRIC, type CiteCoverageReport, type ColdEvalBatch, type ColdEvalCandidate, type ColdEvalVerdict, type ConflictEntry, type ConflictJudge, type ConflictLintReport, type ConflictPair, type ConflictVerdict, DEFAULT_CONFLICT_SIMILARITY_THRESHOLD, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, FABRIC_SERVER_INSTRUCTIONS, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, type KnowledgeCensus, LEDGER_PATH, LEGACY_LEDGER_PATH, METRICS_LEDGER_PATH, METRIC_COUNTER_NAMES, type MetricCounterName, type MetricsRow, type PlanContextInput, type PlanContextResult, type RecallInput, type RecallResult, type RequirementProfile, type SelectionTokenState, type ShutdownHandlerDeps, type UnboundProjectViolation, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, bumpCounter, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, detectUnboundProject, drainCounters, enrichDescriptions, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, lintConflicts, loadConflictEntries, pairSimilarity, planContext, readEventLedger, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, resolveLedgerPaths, reviewKnowledge, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };

package/dist/index.js

@@ -700,13 +700,9 @@ function appendPayloadWarning(warnings, guardResult, actionHint) {
 // src/config-loader.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { join as join4 } from "path";
-import { selectionTokenTtlMsSchema, planContextTopKSchema, resolveRetrievalBudget } from "@fenglimg/fabric-shared";
-var RETRIEVAL_BUDGET_PROFILES = ["conservative", "balanced", "generous"];
-function readRetrievalBudgetProfile(config) {
-  const raw = config.retrieval_budget_profile;
-  return typeof raw === "string" && RETRIEVAL_BUDGET_PROFILES.includes(raw) ? raw : void 0;
-}
+import { selectionTokenTtlMsSchema, planContextTopKSchema } from "@fenglimg/fabric-shared";
 var PLAN_CONTEXT_TOP_K_DEFAULT = 24;
+var RECALL_RELEVANCE_RATIO_DEFAULT = 0.25;
 function readFabricConfig(projectRoot) {
   const configPath = join4(projectRoot, ".fabric", "fabric-config.json");
   if (!existsSync2(configPath)) {
@@ -719,18 +715,7 @@ function readFabricConfig(projectRoot) {
   return parsed;
 }
 function readPayloadLimits(projectRoot) {
-  const config = readFabricConfig(projectRoot);
-  const explicit = config.mcpPayloadLimits;
-  const profile = readRetrievalBudgetProfile(config);
-  if (profile === void 0 && explicit === void 0) {
-    return void 0;
-  }
-  const resolved = resolveRetrievalBudget({
-    profile,
-    payloadWarnBytes: explicit?.warnBytes,
-    payloadHardBytes: explicit?.hardBytes
-  });
-  return { warnBytes: resolved.payloadWarnBytes, hardBytes: resolved.payloadHardBytes };
+  return readFabricConfig(projectRoot).mcpPayloadLimits;
 }
 function readSelectionTokenTtlMs(projectRoot) {
   try {
@@ -776,17 +761,27 @@ function readDefaultLayerFilter(projectRoot) {
 }
 function readPlanContextTopK(projectRoot) {
   try {
-    const config = readFabricConfig(projectRoot);
-    const raw = config.plan_context_top_k;
+    const raw = readFabricConfig(projectRoot).plan_context_top_k;
     if (raw !== void 0) {
       const parsed = planContextTopKSchema.safeParse(raw);
       if (parsed.success) return parsed.data;
     }
-    return resolveRetrievalBudget({ profile: readRetrievalBudgetProfile(config) }).topK;
+    return PLAN_CONTEXT_TOP_K_DEFAULT;
   } catch {
     return PLAN_CONTEXT_TOP_K_DEFAULT;
   }
 }
+function readRecallRelevanceRatio(projectRoot) {
+  try {
+    const raw = readFabricConfig(projectRoot).recall_relevance_ratio;
+    if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0 && raw <= 1) {
+      return raw;
+    }
+    return RECALL_RELEVANCE_RATIO_DEFAULT;
+  } catch {
+    return RECALL_RELEVANCE_RATIO_DEFAULT;
+  }
+}
 function readOrphanDemoteThresholdDays(projectRoot) {
   try {
     const cfg = readFabricConfig(projectRoot);
@@ -2643,11 +2638,23 @@ async function planContext(projectRoot, input) {
       scoringContext.vectorWeight = embedConfig.weight;
     }
   }
-  const builtItems = sortDescriptionItems(rawItems, scoringContext);
-  const rankedCandidates = dedupeDescriptionIndex(builtItems);
+  const scoredSorted = sortDescriptionItems(rawItems, scoringContext);
+  const seenStableIds = /* @__PURE__ */ new Set();
+  const rankedScored = scoredSorted.filter(({ item }) => {
+    if (seenStableIds.has(item.stable_id)) return false;
+    seenStableIds.add(item.stable_id);
+    return true;
+  });
+  const rankedCandidates = rankedScored.map((entry) => entry.item);
   const topK = readPlanContextTopK(projectRoot);
-  const omittedCandidateCount = Math.max(0, rankedCandidates.length - topK);
-  const topKCandidates = omittedCandidateCount > 0 ? rankedCandidates.slice(0, topK) : rankedCandidates;
+  const cappedScored = rankedScored.slice(0, topK);
+  const relevanceRatio = readRecallRelevanceRatio(projectRoot);
+  const hasQuery = scoringContext.queryTerms.length > 0;
+  const maxScore = rankedScored.length > 0 ? rankedScored[0].score : 0;
+  const relevanceFloor = maxScore * relevanceRatio;
+  const survivingScored = hasQuery && maxScore > 0 && relevanceRatio > 0 ? cappedScored.filter((entry) => entry.score >= relevanceFloor) : cappedScored;
+  const topKCandidates = survivingScored.map((entry) => entry.item);
+  const omittedCandidateCount = Math.max(0, rankedCandidates.length - topKCandidates.length);
   let candidates = topKCandidates;
   const relatedAppended = {};
   if (input.include_related === true) {
@@ -2889,7 +2896,7 @@ function compareScopeThenId(left, right, scopeRank) {
 }
 function sortDescriptionItems(rawItems, scoringContext) {
   if (scoringContext === void 0) {
-    return [...rawItems].sort((left, right) => compareStableIds(left.stable_id, right.stable_id));
+    return [...rawItems].sort((left, right) => compareStableIds(left.stable_id, right.stable_id)).map((item) => ({ item, score: 0 }));
   }
   const scored = rawItems.map((item) => ({
     item,
@@ -2899,7 +2906,7 @@ function sortDescriptionItems(rawItems, scoringContext) {
     (left, right) => left.score !== right.score ? right.score - left.score : compareScopeThenId(left.item, right.item, scoringContext.scopeRank)
     // W2/A4 scope tie-break
   );
-  return scored.map((entry) => entry.item);
+  return scored;
 }
 function documentTextForItem(description) {
   return [
@@ -2930,16 +2937,6 @@ function buildPreflightDiagnostics(suppressedStableIds) {
 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;
-  });
-}
 var RECENCY_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
 var RECENCY_BOOST = 25;
 var LOCALITY_SAME_FILE = 100;
@@ -3091,7 +3088,7 @@ function buildNextSteps(planResult, paths, candidateById, candidateLookup) {
   const omitted = planResult.omitted_candidate_count ?? 0;
   if (omitted > 0) {
     nextSteps.push(
-      `${omitted} lower-ranked candidate(s) were omitted by the retrieval budget \u2014 pass a narrower intent (or raise plan_context_top_k / the retrieval_budget_profile) to surface them.`
+      `${omitted} lower-ranked candidate(s) were omitted by the retrieval budget \u2014 pass a narrower intent (or raise plan_context_top_k) to surface them.`
     );
   }
   const surfacedPaths = new Set(paths.map((p) => p.stable_id));
@@ -5660,6 +5657,15 @@ async function inspectEventsJsonlGates(projectRoot, options = {}) {
 import { readdir as readdir2, readFile as readFile9 } from "fs/promises";
 import { join as join16, posix as posix2 } from "path";
 var FABRIC_SKILL_SLUGS = ["fabric-archive", "fabric-review", "fabric-import"];
+var ROUTER_VALID_LEAF_SLUGS = /* @__PURE__ */ new Set([
+  "fabric-archive",
+  "fabric-review",
+  "fabric-import",
+  "fabric-sync",
+  "fabric-store",
+  "fabric-audit",
+  "fabric-connect"
+]);
 var SKILL_MD_FRONTMATTER_ROOTS = [".claude/skills", ".codex/skills"];
 var SKILL_FRONTMATTER_KEY_PATTERN = /^([A-Za-z_][A-Za-z0-9_-]*):[ \t]+(.+?)[ \t]*$/u;
 var SKILL_QUOTED_VALUE_LEADS = /* @__PURE__ */ new Set(['"', "'", "[", "{", ">", "|"]);
@@ -5844,6 +5850,68 @@ function extractSkillFrontmatterLines(raw) {
   }
   return null;
 }
+function extractMarkdownSectionBody(markdown, sectionName) {
+  const lines = markdown.split(/\r?\n/u);
+  const headingRe = /^(#{2,3})\s+(.+?)\s*$/u;
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const h = headingRe.exec(lines[i]);
+    if (h && h[2] === sectionName) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start; i < lines.length; i++) {
+    if (headingRe.test(lines[i])) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+async function inspectRouterChainRef(projectRoot) {
+  const candidatePaths = [
+    join16(projectRoot, ".claude", "skills", "fabric", "SKILL.md"),
+    join16(projectRoot, ".codex", "skills", "fabric", "SKILL.md")
+  ];
+  let body = null;
+  for (const candidate of candidatePaths) {
+    try {
+      body = await readFile9(candidate, "utf8");
+      break;
+    } catch {
+    }
+  }
+  if (body === null) return { status: "ok", unknownRefs: [] };
+  const chainSection = extractMarkdownSectionBody(body, "S_CHAIN");
+  if (chainSection === null) return { status: "ok", unknownRefs: [] };
+  const refs = /* @__PURE__ */ new Set();
+  const tokenRe = /`(fabric-[a-z]+)`/gu;
+  let match;
+  while ((match = tokenRe.exec(chainSection)) !== null) {
+    refs.add(match[1]);
+  }
+  const unknownRefs = [...refs].filter((slug) => !ROUTER_VALID_LEAF_SLUGS.has(slug)).sort();
+  return unknownRefs.length === 0 ? { status: "ok", unknownRefs: [] } : { status: "drift", unknownRefs };
+}
+function createRouterChainRefCheck(t, inspection) {
+  if (inspection.status === "ok") {
+    return okCheck(t("doctor.check.router_chain_ref.name"), t("doctor.check.router_chain_ref.ok"));
+  }
+  const count = inspection.unknownRefs.length;
+  return issueCheck(
+    t("doctor.check.router_chain_ref.name"),
+    "warn",
+    "warning",
+    "router_chain_ref_drift",
+    t(`doctor.check.router_chain_ref.message.${count === 1 ? "singular" : "plural"}`, {
+      count: String(count),
+      list: inspection.unknownRefs.join(", ")
+    }),
+    t("doctor.check.router_chain_ref.remediation"),
+    "maintainer"
+  );
+}
 function createSkillRefMirrorCheck(t, inspection) {
   if (inspection.status === "ok") {
     return okCheck(t("doctor.check.skill_ref_mirror.name"), t("doctor.check.skill_ref_mirror.ok"));
@@ -7565,6 +7633,7 @@ async function runDoctorReport(target) {
   const hookCacheWritability = await inspectHookCacheWritability(projectRoot);
   const staleServeLock = inspectStaleServeLock(projectRoot, lintNow);
   const skillMdYamlInvalid = await inspectSkillMdYamlInvalid(projectRoot);
+  const routerChainRef = await inspectRouterChainRef(projectRoot);
   const onboardCoverage = await inspectOnboardCoverage(projectRoot);
   const [hooksWired, hooksRuntime, hooksContentDrift] = await Promise.all([
     inspectHooksWired(projectRoot),
@@ -7641,6 +7710,9 @@ async function runDoctorReport(target) {
     // rc.12 lint #29: skill_md_yaml_invalid. Warning kind — surfaces
     // SKILL.md frontmatter that Codex CLI silently drops at load.
     createSkillMdYamlInvalidCheck(t, skillMdYamlInvalid),
+    // B2 skill-router (A4): S_CHAIN reference backstop. Warning kind — flags an
+    // S_CHAIN `fabric-*` reference to a leaf no longer in the install set.
+    createRouterChainRefCheck(t, routerChainRef),
     // v2.0.0-rc.23 TASK-014 (F8c): Onboard coverage advisory. Info kind.
     // Surfaces uncovered S5 onboard slots and recommends /fabric-archive
     // first-run phase. Sits adjacent to Skill markdown YAML — both are
@@ -9340,6 +9412,25 @@ async function runDoctorConflictLint(projectRoot, opts = {}) {
   };
 }
 
+// src/services/summary-cold-eval.ts
+var COLD_EVAL_RUBRIC = [
+  "You are a ZERO-CONTEXT judge. You are shown ONLY a one-line knowledge summary \u2014",
+  "never the full entry body. For each summary decide: could a reader who has NOT",
+  "seen the body ACT on this line alone (apply the decision / avoid the pitfall /",
+  "follow the rule)?",
+  "",
+  "PASS (self_sufficient=true): the line states the thesis \u2014 the what + the",
+  "operative so-what. FAIL (self_sufficient=false): the line only POINTS at the",
+  "body ('explains the approach', 'covers the edge cases') without stating it.",
+  "When you FAIL one, return a suggested_summary that states the thesis in one line."
+].join("\n");
+function buildColdEvalBatch(candidates) {
+  const judgeable = candidates.filter(
+    (c) => typeof c.summary === "string" && c.summary.trim().length > 0
+  );
+  return { rubric: COLD_EVAL_RUBRIC, candidates: judgeable };
+}
+
 // src/services/rotation-tick.ts
 var DEFAULT_TICK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
 var tickTimers = /* @__PURE__ */ new Map();
@@ -9685,7 +9776,7 @@ function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.2.0-rc.8"
+      version: "2.2.0-rc.9"
     },
     {
       instructions: FABRIC_SERVER_INSTRUCTIONS
@@ -9797,6 +9888,7 @@ if (isMainModule) {
 }
 export {
   AGENTS_MD_RESOURCE_URI,
+  COLD_EVAL_RUBRIC,
   DEFAULT_CONFLICT_SIMILARITY_THRESHOLD,
   EVENT_LEDGER_PATH,
   FABRIC_SERVER_INSTRUCTIONS,
@@ -9806,6 +9898,7 @@ export {
   METRIC_COUNTER_NAMES,
   appendEventLedgerEvent,
   buildAlwaysActiveBodies,
+  buildColdEvalBatch,
   buildKnowledgeCensus,
   bumpCounter,
   contextCache,

package/package.json

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