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

package/dist/{chunk-AR2HV5JT.js → chunk-3ZBYYPXQ.js}

@@ -88,7 +88,7 @@ import { agentsMetaNodeSchema, agentsMetaSchema as agentsMetaSchema2 } from "@fe
 var AgentsMetaFileMissingError = class extends IOFabricError {
   constructor(metaPath, opts) {
     super(`Fabric agents metadata file is missing: ${metaPath}`, {
-      actionHint: opts?.actionHint ?? "Run `fab init` to scaffold the .fabric/agents.meta.json file"
+      actionHint: opts?.actionHint ?? "Run `fab install` to scaffold the .fabric/agents.meta.json file"
     });
     this.metaPath = metaPath;
   }
@@ -1381,12 +1381,14 @@ async function runDoctorReport(target) {
   const relevancePathsDrift = inspectRelevancePathsDrift(projectRoot);
   const narrowTooFew = inspectNarrowTooFew(projectRoot, lintNow);
   const sessionHintsStale = inspectSessionHintsStale(projectRoot, lintNow);
+  const relevanceFieldsMissing = inspectRelevanceFieldsMissing(projectRoot);
+  const skillMdYamlInvalid = inspectSkillMdYamlInvalid(projectRoot);
   const checks = [
     createBootstrapAnchorCheck(bootstrapAnchor),
     createKnowledgeDirMissingCheck(knowledgeDirMissing),
     createForensicCheck(forensic, framework.kind, entryPoints.length),
     // v2.0: removed `createInitContextCheck` — `.fabric/init-context.json`
-    // is owned by the AI-side client init skill, not by `fabric init` CLI.
+    // is owned by the AI-side client init skill, not by `fabric install` CLI.
     // The file's absence is a legitimate post-init state when the skill has
     // not yet run, so flagging it as a doctor manual_error misrepresents
     // ownership.
@@ -1436,6 +1438,13 @@ 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),
+    // rc.12 lint #29: skill_md_yaml_invalid. Warning kind — surfaces
+    // SKILL.md frontmatter that Codex CLI silently drops at load.
+    createSkillMdYamlInvalidCheck(skillMdYamlInvalid),
     createPreexistingRootFilesCheck(preexistingRootFiles)
     // v2.0 / rc.2: `createLegacyClientPathCheck` removed. The schema now
     // rejects retired clientPaths keys (windsurf/rooCode/geminiCLI) at Zod
@@ -1592,6 +1601,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) {
@@ -2105,7 +2132,7 @@ function createBootstrapAnchorCheck(inspection) {
       "fixable_error",
       "bootstrap_anchor_missing",
       "Neither AGENTS.md nor CLAUDE.md exists at the repo root. Fabric requires a bootstrap anchor file at the project root.",
-      "Run `fabric init` to generate the AGENTS.md / CLAUDE.md bootstrap anchor at the repo root."
+      "Run `fabric install` to generate the AGENTS.md / CLAUDE.md bootstrap anchor at the repo root."
     );
   }
   const present = [
@@ -2150,11 +2177,11 @@ function createForensicCheck(forensic, frameworkKind, entryPointCount) {
       "manual_error",
       "forensic_missing",
       `${forensic.error ?? ".fabric/forensic.json is missing."} Live scan detects ${frameworkKind} with ${entryPointCount} entry point${entryPointCount === 1 ? "" : "s"}.`,
-      "Run `fab init` to regenerate .fabric/forensic.json."
+      "Run `fab install` to regenerate .fabric/forensic.json."
     );
   }
   if (!forensic.valid) {
-    return issueCheck("Scan evidence", "error", "manual_error", "forensic_invalid", forensic.error ?? ".fabric/forensic.json is invalid.", "Run `fab init` to regenerate .fabric/forensic.json.");
+    return issueCheck("Scan evidence", "error", "manual_error", "forensic_invalid", forensic.error ?? ".fabric/forensic.json is invalid.", "Run `fab install` to regenerate .fabric/forensic.json.");
   }
   return okCheck("Scan evidence", `.fabric/forensic.json is valid for ${forensic.report?.framework.kind ?? "unknown"}.`);
 }
@@ -2234,8 +2261,8 @@ function createMcpConfigInWrongFileCheck(inspection) {
       "error",
       "fixable_error",
       "mcp_config_in_wrong_file",
-      `.claude/settings.json contains mcpServers.fabric \u2014 this file is for hooks/permissions only. Run --fix to remove it, then re-run fab init to write .mcp.json.`,
-      "Run `fab doctor --fix` to remove mcpServers.fabric from .claude/settings.json, then run `fab init` to write .mcp.json."
+      `.claude/settings.json contains mcpServers.fabric \u2014 this file is for hooks/permissions only. Run --fix to remove it, then re-run fab install to write .mcp.json.`,
+      "Run `fab doctor --fix` to remove mcpServers.fabric from .claude/settings.json, then run `fab install` to write .mcp.json."
     );
   }
   return okCheck("Claude MCP config location", "mcpServers.fabric is not in .claude/settings.json.");
@@ -3458,6 +3485,254 @@ 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: [])."
+  );
+}
+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(['"', "'", "[", "{", ">", "|"]);
+function inspectSkillMdYamlInvalid(projectRoot) {
+  const candidates = [];
+  for (const rootRel of SKILL_MD_FRONTMATTER_ROOTS) {
+    const rootAbs = join5(projectRoot, rootRel);
+    if (!existsSync4(rootAbs)) continue;
+    let dirEntries;
+    try {
+      dirEntries = readdirSync(rootAbs, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const dirEntry of dirEntries) {
+      if (!dirEntry.isDirectory()) continue;
+      const skillFile = join5(rootAbs, dirEntry.name, "SKILL.md");
+      if (!existsSync4(skillFile)) continue;
+      let raw;
+      try {
+        raw = readFileSync(skillFile, "utf8");
+      } catch {
+        continue;
+      }
+      const frontmatter = extractSkillFrontmatterLines(raw);
+      if (frontmatter === null) continue;
+      for (const { line, lineNumber } of frontmatter) {
+        const match = SKILL_FRONTMATTER_KEY_PATTERN.exec(line);
+        if (!match) continue;
+        const [, key, value] = match;
+        if (value.length === 0) continue;
+        if (SKILL_QUOTED_VALUE_LEADS.has(value[0])) continue;
+        const colonSpaceIdx = value.indexOf(": ");
+        const trailingColon = value.endsWith(":");
+        if (colonSpaceIdx < 0 && !trailingColon) continue;
+        const anchor = colonSpaceIdx >= 0 ? colonSpaceIdx : value.length - 1;
+        const previewStart = Math.max(0, anchor - 25);
+        const previewEnd = Math.min(value.length, anchor + 30);
+        const preview = `${previewStart > 0 ? "\u2026" : ""}${value.slice(previewStart, previewEnd)}${previewEnd < value.length ? "\u2026" : ""}`;
+        candidates.push({
+          path: posix.join(rootRel, dirEntry.name, "SKILL.md"),
+          line: lineNumber,
+          key,
+          preview
+        });
+      }
+    }
+  }
+  candidates.sort((a, b) => {
+    const byPath = a.path.localeCompare(b.path);
+    return byPath !== 0 ? byPath : a.line - b.line;
+  });
+  return { candidates };
+}
+function extractSkillFrontmatterLines(raw) {
+  const rawLines = raw.split(/\r?\n/u);
+  if (rawLines.length < 2) return null;
+  if (rawLines[0]?.trim() !== "---") return null;
+  const out = [];
+  for (let i = 1; i < rawLines.length; i++) {
+    const line = rawLines[i];
+    if (line.trim() === "---") {
+      return out;
+    }
+    out.push({ line, lineNumber: i + 1 });
+  }
+  return null;
+}
+function createSkillMdYamlInvalidCheck(inspection) {
+  if (inspection.candidates.length === 0) {
+    return okCheck(
+      "Skill markdown YAML",
+      "All .claude/.codex SKILL.md frontmatter values parse as strict YAML."
+    );
+  }
+  const first = inspection.candidates[0];
+  const detail = `${first.path}:${first.line} (key \`${first.key}\` value contains an unquoted ': ' \u2014 preview: \`${first.preview}\`)`;
+  const plural = inspection.candidates.length === 1;
+  return issueCheck(
+    "Skill markdown YAML",
+    "warn",
+    "warning",
+    "skill_md_yaml_invalid",
+    `${inspection.candidates.length} SKILL.md frontmatter ${plural ? "value contains" : "values contain"} an unquoted ': ' that strict YAML parsers reject (Claude Code tolerates it; Codex CLI drops the skill at load). First: ${detail}.`,
+    'Quote the value with double quotes (`description: "\u2026"`) or rewrite the inner `key: value` token to `key=value`.'
+  );
+}
 function createNarrowTooFewCheck(inspection) {
   const { structural_flagged, telemetry_flagged } = inspection;
   if (!structural_flagged && !telemetry_flagged) {

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

@@ -14,7 +14,7 @@ import {
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-AR2HV5JT.js";
+} from "./chunk-3ZBYYPXQ.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -942,7 +942,7 @@ function toPosixPath(path) {
 function buildRecommendations(input) {
   const recommendations = [];
   if (!input.hasExistingFabric) {
-    recommendations.push("L0: Run `fab init` to scaffold the .fabric/ knowledge layout (decisions, pitfalls, guidelines, models, processes).");
+    recommendations.push("L0: Run `fab install` to scaffold the .fabric/ knowledge layout (decisions, pitfalls, guidelines, models, processes).");
   }
   if (input.readmeQuality === "stub") {
     recommendations.push("L0: Expand README.md before promoting project facts into Fabric knowledge entries.");

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-3ZBYYPXQ.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.13"
   });
   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-B3UKRP5Y.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.13",
   "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.13"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",