@fenglimg/fabric-server 2.0.0-rc.15 → 2.0.0-rc.22

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

@@ -172,13 +172,18 @@ function isNodeError(error) {
 
 // src/services/event-ledger.ts
 import { randomUUID } from "crypto";
-import { existsSync, fsyncSync, openSync, closeSync } from "fs";
-import { readFile as readFile2, truncate, writeFile } from "fs/promises";
+import { existsSync, fsyncSync, openSync, closeSync, readFileSync, statSync } from "fs";
+import { appendFile, mkdir as mkdir2, readFile as readFile2, truncate, writeFile } from "fs/promises";
+import { join as join3 } from "path";
 import {
   eventLedgerEventSchema
 } from "@fenglimg/fabric-shared";
-import { createLedgerWriteQueue } from "@fenglimg/fabric-shared/node/atomic-write";
+import { atomicWriteText as atomicWriteText2, createLedgerWriteQueue } from "@fenglimg/fabric-shared/node/atomic-write";
 var ledgerQueue = createLedgerWriteQueue();
+var EVENT_LEDGER_DEFAULT_RETENTION_DAYS = 30;
+var EVENT_LEDGER_SIZE_WARN_BYTES = 50 * 1024 * 1024;
+var EVENT_LEDGER_ARCHIVE_DIR = ".fabric/events.archive";
+var warnedOversize = false;
 async function appendEventLedgerEvent(projectRoot, event) {
   const eventPath = getEventLedgerPath(projectRoot);
   const nextEvent = eventLedgerEventSchema.parse({
@@ -190,6 +195,18 @@ async function appendEventLedgerEvent(projectRoot, event) {
   });
   await ensureParentDirectory(eventPath);
   await ledgerQueue.append(eventPath, JSON.stringify(nextEvent));
+  if (!warnedOversize) {
+    try {
+      const size = statSync(eventPath).size;
+      if (size > EVENT_LEDGER_SIZE_WARN_BYTES) {
+        warnedOversize = true;
+        process.stderr.write(
+          'fabric: events.jsonl > 50MB, run "fab doctor --fix" to rotate\n'
+        );
+      }
+    } catch {
+    }
+  }
   return nextEvent;
 }
 async function readEventLedger(projectRoot, options = {}) {
@@ -265,6 +282,120 @@ function createDerivedId(index, line) {
 function isNodeError2(error) {
   return error instanceof Error;
 }
+async function rotateEventLedgerIfNeeded(projectRoot, opts = {}) {
+  const eventPath = getEventLedgerPath(projectRoot);
+  return ledgerQueue.runExclusive(eventPath, async () => {
+    const now = opts.now ?? /* @__PURE__ */ new Date();
+    const retentionDays = resolveRetentionDays(projectRoot, opts.retentionDays);
+    const cutoffMs = now.getTime() - retentionDays * 864e5;
+    let raw;
+    try {
+      raw = await readFile2(eventPath, "utf8");
+    } catch (error) {
+      if (isNodeError2(error) && error.code === "ENOENT") {
+        return { rotated: false, archivedCount: 0, keptCount: 0 };
+      }
+      throw error;
+    }
+    if (raw.length === 0) {
+      return { rotated: false, archivedCount: 0, keptCount: 0 };
+    }
+    const hasTrailingNewline = raw.endsWith("\n");
+    const segments = raw.split(/\r?\n/);
+    let keptTail = "";
+    if (!hasTrailingNewline && segments.length > 0) {
+      keptTail = segments.pop() ?? "";
+    }
+    const archived = [];
+    const kept = [];
+    for (const line of segments) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      let ts;
+      try {
+        const parsed = JSON.parse(trimmed);
+        const candidate = parsed["ts"];
+        if (typeof candidate === "number" && Number.isFinite(candidate)) {
+          ts = candidate;
+        }
+      } catch {
+      }
+      if (ts !== void 0 && ts < cutoffMs) {
+        archived.push(trimmed);
+      } else {
+        kept.push(trimmed);
+      }
+    }
+    if (archived.length === 0) {
+      return {
+        rotated: false,
+        archivedCount: 0,
+        keptCount: kept.length
+      };
+    }
+    const yyyymmdd = formatUtcDate(now);
+    const archiveDirAbsolute = join3(projectRoot, EVENT_LEDGER_ARCHIVE_DIR);
+    const archiveFilename = `events-rotated-${yyyymmdd}.jsonl`;
+    const archiveAbsolutePath = join3(archiveDirAbsolute, archiveFilename);
+    const archiveRelativePath = `${EVENT_LEDGER_ARCHIVE_DIR}/${archiveFilename}`;
+    await mkdir2(archiveDirAbsolute, { recursive: true });
+    await appendFile(
+      archiveAbsolutePath,
+      archived.map((line) => `${line}
+`).join(""),
+      "utf8"
+    );
+    const auditEvent = eventLedgerEventSchema.parse({
+      kind: "fabric-event",
+      id: `event:${randomUUID()}`,
+      ts: now.getTime(),
+      schema_version: 1,
+      event_type: "events_rotated",
+      cutoff_ts: new Date(cutoffMs).toISOString(),
+      archived_count: archived.length,
+      kept_count: kept.length,
+      archive_path: archiveRelativePath
+    });
+    const newMainLines = [JSON.stringify(auditEvent), ...kept];
+    let newMainContent = newMainLines.join("\n") + "\n";
+    if (keptTail.length > 0) {
+      newMainContent += keptTail;
+    }
+    await atomicWriteText2(eventPath, newMainContent);
+    return {
+      rotated: true,
+      archivedCount: archived.length,
+      keptCount: kept.length,
+      archivePath: archiveRelativePath
+    };
+  });
+}
+function resolveRetentionDays(projectRoot, override) {
+  if (typeof override === "number" && Number.isFinite(override) && override >= 0) {
+    return override;
+  }
+  const configPath = join3(projectRoot, ".fabric", "fabric-config.json");
+  try {
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const v = parsed.fabric_event_retention_days;
+        if (v === 7 || v === 30 || v === 90) {
+          return v;
+        }
+      }
+    }
+  } catch {
+  }
+  return EVENT_LEDGER_DEFAULT_RETENTION_DAYS;
+}
+function formatUtcDate(date) {
+  const yyyy = date.getUTCFullYear().toString().padStart(4, "0");
+  const mm = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+  const dd = date.getUTCDate().toString().padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}`;
+}
 function flushAndSyncEventLedger(projectRoot) {
   const ledgerPath = getEventLedgerPath(projectRoot);
   if (!existsSync(ledgerPath)) return;
@@ -277,10 +408,10 @@ function flushAndSyncEventLedger(projectRoot) {
 }
 
 // src/services/knowledge-meta-builder.ts
-import { mkdir as mkdir2, readdir, readFile as readFile3 } from "fs/promises";
-import { existsSync as existsSync2, statSync } from "fs";
+import { mkdir as mkdir3, readdir, readFile as readFile3 } from "fs/promises";
+import { existsSync as existsSync2, statSync as statSync2 } from "fs";
 import { homedir } from "os";
-import { isAbsolute, join as join3, relative, resolve as resolve2, sep as sep2 } from "path";
+import { isAbsolute, join as join4, relative, resolve as resolve2, sep as sep2 } from "path";
 import {
   KNOWLEDGE_TEST_INDEX_SCHEMA_VERSION,
   agentsMetaSchema as agentsMetaSchema3,
@@ -296,12 +427,12 @@ import {
   StableIdSchema,
   parseKnowledgeId
 } from "@fenglimg/fabric-shared";
-import { atomicWriteText as atomicWriteText2 } from "@fenglimg/fabric-shared/node/atomic-write";
+import { atomicWriteText as atomicWriteText3 } from "@fenglimg/fabric-shared/node/atomic-write";
 async function buildKnowledgeMeta(projectRootInput) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   assertExistingDirectory(projectRoot);
-  const metaPath = join3(projectRoot, ".fabric", "agents.meta.json");
-  const knowledgeTestIndexPath = join3(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
+  const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
+  const knowledgeTestIndexPath = join4(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
   const existingMeta = await readExistingMeta(metaPath);
   const existingKnowledgeTestIndex = await readExistingKnowledgeTestIndex(knowledgeTestIndexPath);
   const meta = await computeKnowledgeBasedAgentsMeta(projectRoot, existingMeta);
@@ -314,18 +445,18 @@ async function buildKnowledgeMeta(projectRootInput) {
 }
 async function writeKnowledgeMeta(projectRootInput, options) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
-  const metaPath = join3(projectRoot, ".fabric", "agents.meta.json");
-  const knowledgeTestIndexPath = join3(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
+  const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
+  const knowledgeTestIndexPath = join4(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
   const existingMeta = await readExistingMeta(metaPath);
   const result = await buildKnowledgeMeta(projectRoot);
   if (!result.changed) {
     return result;
   }
   await ensureParentDirectory(metaPath);
-  await atomicWriteText2(metaPath, `${JSON.stringify(result.meta, null, 2)}
+  await atomicWriteText3(metaPath, `${JSON.stringify(result.meta, null, 2)}
 `);
   await ensureParentDirectory(knowledgeTestIndexPath);
-  await atomicWriteText2(knowledgeTestIndexPath, `${JSON.stringify(result.knowledgeTestIndex, null, 2)}
+  await atomicWriteText3(knowledgeTestIndexPath, `${JSON.stringify(result.knowledgeTestIndex, null, 2)}
 `);
   if (existingMeta === void 0 || stableStringify(existingMeta) !== stableStringify(result.meta)) {
     await recordBaselineSynced(projectRoot, {
@@ -342,7 +473,7 @@ async function writeKnowledgeMeta(projectRootInput, options) {
 async function computeKnowledgeBasedAgentsMeta(projectRootInput, existingMeta) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   assertExistingDirectory(projectRoot);
-  const previousMeta = existingMeta ?? await readExistingMeta(join3(projectRoot, ".fabric", "agents.meta.json"));
+  const previousMeta = existingMeta ?? await readExistingMeta(join4(projectRoot, ".fabric", "agents.meta.json"));
   const existingByContentRef = indexExistingNodesByContentRef(previousMeta);
   const ruleFiles = await findKnowledgeFiles(projectRoot);
   const nodes = {};
@@ -433,7 +564,7 @@ function normalizeProjectRoot(projectRoot) {
   return isAbsolute(projectRoot) ? projectRoot : resolve2(process.cwd(), projectRoot);
 }
 function assertExistingDirectory(projectRoot) {
-  if (!existsSync2(projectRoot) || !statSync(projectRoot).isDirectory()) {
+  if (!existsSync2(projectRoot) || !statSync2(projectRoot).isDirectory()) {
     throw new Error(`Target directory does not exist: ${projectRoot}`);
   }
 }
@@ -477,17 +608,17 @@ function resolvePersonalRoot() {
 }
 function resolveContentRefPath(projectRoot, contentRef) {
   if (contentRef.startsWith(PERSONAL_CONTENT_REF_PREFIX)) {
-    return join3(resolvePersonalRoot(), ".fabric", "knowledge", contentRef.slice(PERSONAL_CONTENT_REF_PREFIX.length));
+    return join4(resolvePersonalRoot(), ".fabric", "knowledge", contentRef.slice(PERSONAL_CONTENT_REF_PREFIX.length));
   }
-  return join3(projectRoot, contentRef);
+  return join4(projectRoot, contentRef);
 }
 async function findKnowledgeFiles(projectRoot) {
-  const teamRoot = join3(projectRoot, ".fabric", "knowledge");
-  const personalRoot = join3(resolvePersonalRoot(), ".fabric", "knowledge");
+  const teamRoot = join4(projectRoot, ".fabric", "knowledge");
+  const personalRoot = join4(resolvePersonalRoot(), ".fabric", "knowledge");
   try {
-    await mkdir2(personalRoot, { recursive: true });
+    await mkdir3(personalRoot, { recursive: true });
     for (const sub of KNOWLEDGE_SUBDIRS) {
-      await mkdir2(join3(personalRoot, sub), { recursive: true });
+      await mkdir3(join4(personalRoot, sub), { recursive: true });
     }
   } catch {
   }
@@ -496,11 +627,11 @@ async function findKnowledgeFiles(projectRoot) {
     [teamRoot, TEAM_CONTENT_REF_PREFIX],
     [personalRoot, PERSONAL_CONTENT_REF_PREFIX]
   ]) {
-    if (!existsSync2(root) || !statSync(root).isDirectory()) {
+    if (!existsSync2(root) || !statSync2(root).isDirectory()) {
       continue;
     }
     for (const subdir of KNOWLEDGE_SUBDIRS) {
-      const dir = join3(root, subdir);
+      const dir = join4(root, subdir);
       let entries;
       try {
         entries = await readdir(dir, { withFileTypes: true });
@@ -524,7 +655,7 @@ async function findFabricVerifyAnnotations(projectRoot) {
   const annotations = [];
   const annotationPattern = /^\s*\/\/\s*@fabric-verify\s+([A-Za-z0-9][A-Za-z0-9/_-]*)\s*$/u;
   for (const testFile of files) {
-    const source = await readFile3(join3(projectRoot, testFile), "utf8");
+    const source = await readFile3(join4(projectRoot, testFile), "utf8");
     const testHash = sha256(source);
     const lines = source.split(/\r?\n/u);
     for (const [index, line] of lines.entries()) {
@@ -552,7 +683,7 @@ async function findTestFiles(projectRoot) {
       continue;
     }
     for (const entry of await readdir(current, { withFileTypes: true })) {
-      const absolutePath = join3(current, entry.name);
+      const absolutePath = join4(current, entry.name);
       const relativePath = toPosixPath(relative(projectRoot, absolutePath));
       const [rootSegment] = relativePath.split("/");
       if (entry.isDirectory()) {
@@ -802,23 +933,29 @@ function extractRuleDescription(source) {
   if (summary === void 0 || summary.length === 0) {
     return void 0;
   }
+  const knowledge = frontmatter !== null ? extractKnowledgeFieldsFromFrontmatter(frontmatter[1]) : void 0;
   return {
     summary,
     intent_clues: [],
     tech_stack: [],
     impact: [],
     must_read_if: summary,
-    // v2.0 knowledge fields are absent in heading-only fallback.
-    id: void 0,
-    knowledge_type: void 0,
-    maturity: void 0,
-    knowledge_layer: void 0,
-    layer_reason: void 0,
-    created_at: void 0,
-    tags: void 0,
-    // v2.0-rc.5 (C1): default-safe values when there is no frontmatter at all.
-    relevance_scope: "broad",
-    relevance_paths: []
+    // v2.0-rc.22: when frontmatter is present, merge its knowledge fields;
+    // when fully absent (no `---` block), all knowledge fields stay
+    // undefined, matching the original heading-only fallback contract.
+    id: knowledge?.id,
+    knowledge_type: knowledge?.knowledge_type,
+    maturity: knowledge?.maturity,
+    knowledge_layer: knowledge?.knowledge_layer,
+    layer_reason: knowledge?.layer_reason,
+    created_at: knowledge?.created_at,
+    tags: knowledge?.tags,
+    // v2.0-rc.5 (C1): default-safe values when there is no frontmatter at all;
+    // when frontmatter exists, honor its declared values (extractKnowledge
+    // FieldsFromFrontmatter already applies the broad-default for missing
+    // or malformed scopes).
+    relevance_scope: knowledge?.relevance_scope ?? "broad",
+    relevance_paths: knowledge?.relevance_paths ?? []
   };
 }
 function extractRuleSections(source) {
@@ -960,9 +1097,34 @@ function isNodeError3(error) {
 
 // src/services/knowledge-sync.ts
 import { readdir as readdir2, readFile as readFile4, stat } from "fs/promises";
-import { existsSync as existsSync3, statSync as statSync2 } from "fs";
-import { join as join4, relative as relative2, sep as sep3 } from "path";
+import { existsSync as existsSync3, statSync as statSync3 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join5 } from "path";
 import { RuleValidationError } from "@fenglimg/fabric-shared/errors";
+var PERSONAL_CONTENT_REF_PREFIX2 = "~/.fabric/knowledge/";
+var TEAM_CONTENT_REF_PREFIX2 = ".fabric/knowledge/";
+var KNOWLEDGE_SUBDIRS2 = [
+  "decisions",
+  "pitfalls",
+  "guidelines",
+  "models",
+  "processes",
+  "pending"
+];
+function resolvePersonalRoot2() {
+  return process.env.FABRIC_HOME ?? homedir2();
+}
+function resolveContentRefPath2(projectRoot, relPath) {
+  if (relPath.startsWith(PERSONAL_CONTENT_REF_PREFIX2)) {
+    return join5(
+      resolvePersonalRoot2(),
+      ".fabric",
+      "knowledge",
+      relPath.slice(PERSONAL_CONTENT_REF_PREFIX2.length)
+    );
+  }
+  return join5(projectRoot, relPath);
+}
 var lastSyncState = /* @__PURE__ */ new Map();
 var freshSyncCooldown = /* @__PURE__ */ new Map();
 var SYNC_COOLDOWN_MS = 500;
@@ -970,7 +1132,7 @@ function invalidateKnowledgeSyncCooldown(projectRoot) {
   freshSyncCooldown.delete(projectRoot);
 }
 async function readMetaEntries(projectRoot) {
-  const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join5(projectRoot, ".fabric", "agents.meta.json");
   const map = /* @__PURE__ */ new Map();
   let raw;
   try {
@@ -995,32 +1157,36 @@ async function readMetaEntries(projectRoot) {
   return map;
 }
 async function findRuleFiles(projectRoot) {
-  const knowledgeRoot = join4(projectRoot, ".fabric", "knowledge");
-  if (!existsSync3(knowledgeRoot) || !statSync2(knowledgeRoot).isDirectory()) {
-    return [];
-  }
+  const teamRoot = join5(projectRoot, ".fabric", "knowledge");
+  const personalRoot = join5(resolvePersonalRoot2(), ".fabric", "knowledge");
   const files = [];
-  const stack = [knowledgeRoot];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    if (current === void 0) {
+  for (const [root, prefix] of [
+    [teamRoot, TEAM_CONTENT_REF_PREFIX2],
+    [personalRoot, PERSONAL_CONTENT_REF_PREFIX2]
+  ]) {
+    if (!existsSync3(root) || !statSync3(root).isDirectory()) {
       continue;
     }
-    for (const entry of await readdir2(current, { withFileTypes: true })) {
-      const absolutePath = join4(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(absolutePath);
-      } else if (entry.isFile() && entry.name.endsWith(".md")) {
-        const rel = toPosixPath2(relative2(projectRoot, absolutePath));
-        files.push(rel);
+    for (const subdir of KNOWLEDGE_SUBDIRS2) {
+      const dir = join5(root, subdir);
+      if (!existsSync3(dir) || !statSync3(dir).isDirectory()) {
+        continue;
+      }
+      let entries;
+      try {
+        entries = await readdir2(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+          files.push(`${prefix}${subdir}/${entry.name}`);
+        }
       }
     }
   }
   return files.sort();
 }
-function toPosixPath2(p) {
-  return p.split(sep3).join("/");
-}
 function validateFrontmatter(source, filePath, throwOnInvalid) {
   if (!source.startsWith("---")) {
     return null;
@@ -1066,7 +1232,7 @@ function validateFrontmatter(source, filePath, throwOnInvalid) {
   return null;
 }
 async function processSingleFile(projectRoot, relPath, metaEntry, source, throwOnInvalidFrontmatter) {
-  const absPath = join4(projectRoot, relPath);
+  const absPath = resolveContentRefPath2(projectRoot, relPath);
   try {
     await stat(absPath);
   } catch {
@@ -1165,7 +1331,7 @@ async function ensureKnowledgeFresh(projectRoot, opts) {
   }
   for (const [relPath, entry] of metaEntries) {
     if (!ruleFiles.includes(relPath)) {
-      const absPath = join4(projectRoot, relPath);
+      const absPath = resolveContentRefPath2(projectRoot, relPath);
       if (!existsSync3(absPath)) {
         events.push({
           type: "rule_removed",
@@ -1217,7 +1383,7 @@ async function reconcileKnowledge(projectRoot, opts) {
   }
   for (const [relPath, entry] of metaEntries) {
     if (!ruleFiles.includes(relPath)) {
-      const absPath = join4(projectRoot, relPath);
+      const absPath = resolveContentRefPath2(projectRoot, relPath);
       if (!existsSync3(absPath)) {
         events.push({
           type: "rule_removed",
@@ -1231,14 +1397,27 @@ async function reconcileKnowledge(projectRoot, opts) {
       }
     }
   }
-  if (events.length > 0) {
+  let revisionDrift = false;
+  try {
+    const derived = await buildKnowledgeMeta(projectRoot);
+    const onDisk = await readAgentsMeta(projectRoot);
+    revisionDrift = onDisk.revision !== derived.meta.revision;
+  } catch (error) {
+    if (!(error instanceof AgentsMetaFileMissingError) && !(error instanceof AgentsMetaInvalidError)) {
+      throw error;
+    }
+  }
+  if (events.length > 0 || revisionDrift) {
     await writeKnowledgeMeta(projectRoot, { source: "sync_meta" });
-    await appendRuleSyncEvents(projectRoot, events);
+    if (events.length > 0) {
+      await appendRuleSyncEvents(projectRoot, events);
+    }
     contextCache.invalidate("file_watch", projectRoot);
+    contextCache.invalidate("meta_write", projectRoot);
   }
   const duration_ms = Date.now() - startTime;
   const reconciledFiles = events.map((e) => e.path);
-  if (trigger !== void 0 && events.length > 0) {
+  if (trigger !== void 0 && (events.length > 0 || revisionDrift)) {
     if (trigger === "startup") {
       await appendEventLedgerEvent(projectRoot, {
         event_type: "meta_reconciled_on_startup",
@@ -1252,11 +1431,12 @@ async function reconcileKnowledge(projectRoot, opts) {
         reconciled_files: reconciledFiles,
         duration_ms,
         trigger,
-        source: "reconcileKnowledge"
+        source: "reconcileKnowledge",
+        ...events.length === 0 && revisionDrift ? { force_write_reason: "revision_drift" } : {}
       });
     }
   }
-  if (events.length === 0 && warnings.length === 0) {
+  if (events.length === 0 && warnings.length === 0 && !revisionDrift) {
     return { status: "fresh", events: [], warnings: [] };
   }
   const status = warnings.length > 0 ? "errors" : "reconciled";
@@ -1270,21 +1450,26 @@ async function reconcileKnowledge(projectRoot, opts) {
 
 // src/services/doctor.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync4, readdirSync, readFileSync, statSync as statSync3 } from "fs";
-import { access, mkdir as mkdir3, readFile as readFile5, rename, writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync2, statSync as statSync4 } from "fs";
+import { access, mkdir as mkdir4, readFile as readFile5, rename, writeFile as writeFile2 } from "fs/promises";
 import { constants } from "fs";
-import { homedir as homedir2 } from "os";
-import { isAbsolute as isAbsolute2, join as join5, posix, relative as nodeRelative, resolve as resolve3, sep as sep4 } from "path";
+import { homedir as homedir3 } from "os";
+import { isAbsolute as isAbsolute2, join as join6, posix, relative as nodeRelative, resolve as resolve3, sep as sep3 } from "path";
 import { minimatch } from "minimatch";
 import {
   agentsMetaSchema as agentsMetaSchema4,
   AgentsMetaCountersSchema,
   forensicReportSchema,
   parseKnowledgeId as parseKnowledgeId2,
-  knowledgeTestIndexSchema as knowledgeTestIndexSchema2
+  knowledgeTestIndexSchema as knowledgeTestIndexSchema2,
+  LEGACY_KB_REGEX,
+  BOOTSTRAP_CANONICAL,
+  BOOTSTRAP_MARKER_BEGIN,
+  BOOTSTRAP_MARKER_END,
+  BOOTSTRAP_REGEX
 } from "@fenglimg/fabric-shared";
 import { detectFramework } from "@fenglimg/fabric-shared/node";
-import { atomicWriteJson as atomicWriteJson2, atomicWriteText as atomicWriteText3 } from "@fenglimg/fabric-shared/node/atomic-write";
+import { atomicWriteJson as atomicWriteJson2, atomicWriteText as atomicWriteText4 } from "@fenglimg/fabric-shared/node/atomic-write";
 var ORPHAN_DEMOTE_THRESHOLD_DAYS = {
   stable: 90,
   endorsed: 30,
@@ -1322,7 +1507,22 @@ var KNOWLEDGE_CANONICAL_TYPE_DIRS = [
   "processes"
 ];
 var CANONICAL_KNOWLEDGE_FILENAME_PATTERN = /^(K[PT]-(?:MOD|DEC|GLD|PIT|PRO)-\d{4,})--[a-z0-9][a-z0-9-]*\.md$/u;
-var KNOWLEDGE_SUBDIRS2 = ["decisions", "pitfalls", "guidelines", "models", "processes", "pending"];
+var KNOWLEDGE_SUBDIRS3 = ["decisions", "pitfalls", "guidelines", "models", "processes", "pending"];
+var BASELINE_FILENAME_LINT_BASELINE_IDS = /* @__PURE__ */ new Set([
+  "KT-MOD-0001",
+  // tech-stack
+  "KT-MOD-0002",
+  // module-structure
+  "KT-MOD-0003",
+  // readme-first-paragraph
+  "KT-PRO-0001",
+  // build-config
+  "KT-PRO-0002",
+  // ci-config
+  "KT-GLD-0001"
+  // code-style
+]);
+var BASELINE_ID_PREFIXED_FILENAME_PATTERN = /^KT-[A-Z]+-\d+--.+\.md$/u;
 var COUNTER_TYPE_CODES = ["MOD", "DEC", "GLD", "PIT", "PRO"];
 var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
 var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
@@ -1342,7 +1542,13 @@ var TARGET_FILE_PATHS = [
   ".fabric/agents.meta.json",
   ".fabric/.cache/knowledge-test.index.json",
   ".fabric/events.jsonl",
-  ".fabric/knowledge"
+  ".fabric/knowledge",
+  // v2.0.0-rc.19 bootstrap-consolidation TASK-005: L1 canonical snapshot
+  // (.fabric/AGENTS.md) and optional project-rules concat source
+  // (.fabric/project-rules.md). Surfaced in summary.targetFiles so --json
+  // consumers can confirm L1 presence at a glance.
+  ".fabric/AGENTS.md",
+  ".fabric/project-rules.md"
 ];
 async function runDoctorReport(target) {
   const projectRoot = normalizeTarget(target);
@@ -1352,17 +1558,30 @@ async function runDoctorReport(target) {
     forensic,
     meta,
     eventLedger,
-    knowledgeTestIndex
+    knowledgeTestIndex,
+    bootstrapMarkerMigration,
+    l1BootstrapSnapshotDrift,
+    l2ManagedBlockDrift
   ] = await Promise.all([
     inspectForensic(projectRoot),
     inspectMeta(projectRoot),
     inspectEventLedger(projectRoot),
-    inspectKnowledgeTestIndex(projectRoot)
+    inspectKnowledgeTestIndex(projectRoot),
+    // v2.0.0-rc.19 TASK-004: one-time fabric:knowledge-base → fabric:bootstrap
+    // marker migration scan. Inspect runs in this Promise.all block to keep
+    // performance parity with the other I/O-bound inspections.
+    inspectBootstrapMarkerMigration(projectRoot),
+    // v2.0.0-rc.19 TASK-005: L1 + L2 byte-level drift detection. Both are
+    // I/O-bound (small file reads + buffer compare) so they live in the same
+    // Promise.all block as the other bootstrap inspections.
+    inspectL1BootstrapSnapshotDrift(projectRoot),
+    inspectL2ManagedBlockDrift(projectRoot)
   ]);
   const mcpConfigInWrongFile = inspectMcpConfigInWrongFile(projectRoot);
   const metaManuallyDiverged = await inspectMetaManuallyDiverged(projectRoot);
   const knowledgeDirUnindexed = inspectKnowledgeDirUnindexed(projectRoot, meta);
   const knowledgeDirMissing = inspectKnowledgeDirMissing(projectRoot);
+  const baselineFilenameFormat = inspectBaselineFilenameFormat(projectRoot);
   const stableIdCollision = await inspectStableIdCollisions(projectRoot);
   const counterDesync = inspectCounterDesync(meta);
   const preexistingRootFiles = inspectPreexistingRootFiles(projectRoot);
@@ -1385,7 +1604,20 @@ async function runDoctorReport(target) {
   const skillMdYamlInvalid = inspectSkillMdYamlInvalid(projectRoot);
   const checks = [
     createBootstrapAnchorCheck(bootstrapAnchor),
+    // v2.0.0-rc.19 TASK-004: bootstrap marker migration check sits adjacent to
+    // the anchor check — both are bootstrap-file invariants. fixable_error
+    // when any of the four target paths still carries the legacy marker.
+    createBootstrapMarkerMigrationCheck(bootstrapMarkerMigration),
+    // v2.0.0-rc.19 TASK-005: L1 + L2 byte-level drift detection sit immediately
+    // after the marker migration check. Order: anchor existence → migration →
+    // L1 (canonical ↔ snapshot) → L2 (snapshot+rules ↔ three-end blocks).
+    createL1BootstrapSnapshotDriftCheck(l1BootstrapSnapshotDrift),
+    createL2ManagedBlockDriftCheck(l2ManagedBlockDrift),
     createKnowledgeDirMissingCheck(knowledgeDirMissing),
+    // v2.0.0-rc.22 TASK-006: baseline filename format. Sits adjacent to
+    // knowledge_dir_missing — both are knowledge-layout invariants. manual_error
+    // kind; resolution delegates to `fab scan` (no --fix path).
+    createBaselineFilenameFormatCheck(baselineFilenameFormat),
     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 install` CLI.
@@ -1485,7 +1717,7 @@ async function runDoctorReport(target) {
       warningCount: warnings.length,
       infoCount: infos.length,
       targetFiles: Object.fromEntries(
-        TARGET_FILE_PATHS.map((path) => [path, existsSync4(join5(projectRoot, path))])
+        TARGET_FILE_PATHS.map((path) => [path, existsSync4(join6(projectRoot, path))])
       )
     }
   };
@@ -1494,6 +1726,33 @@ async function runDoctorFix(target) {
   const projectRoot = normalizeTarget(target);
   const before = await runDoctorReport(projectRoot);
   const fixed = [];
+  if (before.fixable_errors.some(
+    (issue) => issue.code === "bootstrap_marker_migration_required"
+  )) {
+    const migrated = await migrateBootstrapMarkers(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "bootstrap_marker_migration_required"));
+    for (const path of migrated.paths) {
+      await appendEventLedgerEvent(projectRoot, {
+        event_type: "bootstrap_marker_migrated",
+        path,
+        migrated_count: migrated.countPerPath[path] ?? 1,
+        legacy_marker: "fabric:knowledge-base",
+        new_marker: "fabric:bootstrap",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }).catch(() => {
+      });
+    }
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "bootstrap_snapshot_drift")) {
+    const snapshotPath = join6(projectRoot, ".fabric", "AGENTS.md");
+    await ensureParentDirectory(snapshotPath);
+    await atomicWriteText4(snapshotPath, BOOTSTRAP_CANONICAL);
+    fixed.push(findIssue(before.fixable_errors, "bootstrap_snapshot_drift"));
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "managed_block_drift")) {
+    await rewriteThreeEndManagedBlocks(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "managed_block_drift"));
+  }
   if (before.fixable_errors.some((issue) => issue.code === "knowledge_dir_missing")) {
     await ensureKnowledgeSubdirs(projectRoot);
     fixed.push(findIssue(before.fixable_errors, "knowledge_dir_missing"));
@@ -1507,26 +1766,23 @@ async function runDoctorFix(target) {
     fixed.push(findIssue(before.fixable_errors, "counter_desync"));
     contextCache.invalidate("meta_write", projectRoot);
   }
-  if (before.fixable_errors.some(
-    (issue) => [
-      "agents_meta_missing",
-      "agents_meta_stale",
-      "knowledge_test_index_missing",
-      "knowledge_test_index_stale",
-      "content_ref_missing",
-      "knowledge_dir_unindexed"
-    ].includes(issue.code)
-  )) {
+  const reconcileCodes = [
+    "agents_meta_missing",
+    "agents_meta_stale",
+    "knowledge_test_index_missing",
+    "knowledge_test_index_stale",
+    "content_ref_missing",
+    "knowledge_dir_unindexed"
+  ];
+  if (before.fixable_errors.some((issue) => reconcileCodes.includes(issue.code)) || before.warnings.some((issue) => reconcileCodes.includes(issue.code))) {
     await reconcileKnowledge(projectRoot, { trigger: "doctor" });
     for (const issue of before.fixable_errors.filter(
-      (candidate) => [
-        "agents_meta_missing",
-        "agents_meta_stale",
-        "knowledge_test_index_missing",
-        "knowledge_test_index_stale",
-        "content_ref_missing",
-        "knowledge_dir_unindexed"
-      ].includes(candidate.code)
+      (candidate) => reconcileCodes.includes(candidate.code)
+    )) {
+      fixed.push(issue);
+    }
+    for (const issue of before.warnings.filter(
+      (candidate) => reconcileCodes.includes(candidate.code)
     )) {
       fixed.push(issue);
     }
@@ -1545,6 +1801,15 @@ async function runDoctorFix(target) {
     });
     fixed.push(findIssue(before.fixable_errors, "event_ledger_partial_write"));
   }
+  const rotateResult = await rotateEventLedgerIfNeeded(projectRoot);
+  if (rotateResult.rotated && rotateResult.archivedCount > 0) {
+    fixed.push({
+      code: "event_ledger_rotated",
+      name: "Event ledger rotated",
+      message: `Rotated ${rotateResult.archivedCount} event(s) older than retention window to ${rotateResult.archivePath ?? "archive"}`,
+      path: rotateResult.archivePath
+    });
+  }
   if (before.fixable_errors.some((issue) => issue.code === "mcp_config_in_wrong_file")) {
     await fixMcpConfigInWrongFile(projectRoot);
     fixed.push(findIssue(before.fixable_errors, "mcp_config_in_wrong_file"));
@@ -1684,7 +1949,7 @@ async function applyOrphanDemote(projectRoot, candidate, now) {
     };
   }
   const detail = `${candidate.maturity} -> ${next}`;
-  const absPath = join5(projectRoot, candidate.path);
+  const absPath = join6(projectRoot, candidate.path);
   try {
     const source = await readFile5(absPath, "utf8");
     const rewritten = rewriteFrontmatterMaturity(source, next);
@@ -1706,7 +1971,7 @@ async function applyOrphanDemote(projectRoot, candidate, now) {
         error: "rewrite produced byte-identical output"
       };
     }
-    await atomicWriteText3(absPath, rewritten);
+    await atomicWriteText4(absPath, rewritten);
     try {
       await appendEventLedgerEvent(projectRoot, {
         event_type: "knowledge_demoted",
@@ -1716,7 +1981,7 @@ async function applyOrphanDemote(projectRoot, candidate, now) {
       });
     } catch (ledgerError) {
       try {
-        await atomicWriteText3(absPath, source);
+        await atomicWriteText4(absPath, source);
       } catch (rollbackError) {
         return {
           kind: "knowledge_orphan_demote_required",
@@ -1751,11 +2016,11 @@ async function applyOrphanDemote(projectRoot, candidate, now) {
   }
 }
 async function applyStaleArchive(projectRoot, candidate, now) {
-  const sourceAbs = join5(projectRoot, candidate.path);
-  const destAbs = join5(projectRoot, candidate.archive_path);
+  const sourceAbs = join6(projectRoot, candidate.path);
+  const destAbs = join6(projectRoot, candidate.archive_path);
   const detail = `${candidate.path} -> ${candidate.archive_path}`;
   try {
-    await mkdir3(join5(destAbs, ".."), { recursive: true });
+    await mkdir4(join6(destAbs, ".."), { recursive: true });
     try {
       await rename(sourceAbs, destAbs);
     } catch (renameError) {
@@ -1814,7 +2079,7 @@ async function applyStaleArchive(projectRoot, candidate, now) {
 async function applyPendingAutoArchive(projectRoot, candidate, now) {
   const detail = `${candidate.pending_path} -> ${candidate.archived_to}`;
   try {
-    await mkdir3(join5(candidate.archived_to_abs, ".."), { recursive: true });
+    await mkdir4(join6(candidate.archived_to_abs, ".."), { recursive: true });
     let moved = false;
     if (candidate.layer === "team") {
       try {
@@ -1887,11 +2152,11 @@ async function applyPendingAutoArchive(projectRoot, candidate, now) {
 }
 function relativePosix(projectRoot, absolutePath) {
   const rel = nodeRelative(projectRoot, absolutePath);
-  return rel.split(sep4).join("/");
+  return rel.split(sep3).join("/");
 }
 async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   const detail = `deleted (${candidate.age_days}d old)`;
-  const absPath = join5(projectRoot, candidate.path);
+  const absPath = join6(projectRoot, candidate.path);
   try {
     const { unlink } = await import("fs/promises");
     await unlink(absPath);
@@ -1912,7 +2177,7 @@ async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   }
 }
 async function applyIndexDriftFix(projectRoot, inspection) {
-  const metaPath = join5(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join6(projectRoot, ".fabric", "agents.meta.json");
   const detailParts = [];
   try {
     const meta = agentsMetaSchema4.parse(JSON.parse(await readFile5(metaPath, "utf8")));
@@ -1948,7 +2213,7 @@ function truncateErrorMessage(error) {
   return raw.length > 240 ? `${raw.slice(0, 237)}...` : raw;
 }
 async function inspectForensic(projectRoot) {
-  const path = join5(projectRoot, ".fabric", "forensic.json");
+  const path = join6(projectRoot, ".fabric", "forensic.json");
   try {
     const parsed = forensicReportSchema.parse(JSON.parse(await readFile5(path, "utf8")));
     return { present: true, valid: true, report: parsed };
@@ -1960,12 +2225,12 @@ async function inspectForensic(projectRoot) {
   }
 }
 function inspectMcpConfigInWrongFile(projectRoot) {
-  const settingsPath = join5(projectRoot, ".claude", "settings.json");
+  const settingsPath = join6(projectRoot, ".claude", "settings.json");
   if (!existsSync4(settingsPath)) {
     return { hasWrongEntry: false, settingsPath };
   }
   try {
-    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync2(settingsPath, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return { hasWrongEntry: false, settingsPath };
     }
@@ -1981,7 +2246,7 @@ function inspectMcpConfigInWrongFile(projectRoot) {
   }
 }
 async function inspectMeta(projectRoot) {
-  const metaPath = join5(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join6(projectRoot, ".fabric", "agents.meta.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
     const raw = await readFile5(metaPath, "utf8");
@@ -2054,7 +2319,7 @@ function inspectContentRefs(projectRoot, meta) {
     if (isPersonalKnowledge) {
       continue;
     }
-    if (!existsSync4(join5(projectRoot, contentRef))) {
+    if (!existsSync4(join6(projectRoot, contentRef))) {
       missing.push(contentRef);
     }
   }
@@ -2096,7 +2361,7 @@ async function inspectEventLedger(projectRoot) {
   }
 }
 async function inspectKnowledgeTestIndex(projectRoot) {
-  const path = join5(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
+  const path = join6(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
     const index = knowledgeTestIndexSchema2.parse(JSON.parse(await readFile5(path, "utf8")));
@@ -2120,10 +2385,190 @@ async function inspectKnowledgeTestIndex(projectRoot) {
 }
 function inspectBootstrapAnchor(projectRoot) {
   return {
-    hasAgentsMd: existsSync4(join5(projectRoot, "AGENTS.md")),
-    hasClaudeMd: existsSync4(join5(projectRoot, "CLAUDE.md"))
+    hasAgentsMd: existsSync4(join6(projectRoot, "AGENTS.md")),
+    hasClaudeMd: existsSync4(join6(projectRoot, "CLAUDE.md"))
   };
 }
+var BOOTSTRAP_MARKER_MIGRATION_TARGETS = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".cursor/rules",
+  ".cursor/rules/fabric-bootstrap.mdc"
+];
+async function inspectBootstrapMarkerMigration(target) {
+  const filesNeedingMigration = [];
+  for (const rel of BOOTSTRAP_MARKER_MIGRATION_TARGETS) {
+    const abs = join6(target, rel);
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (LEGACY_KB_REGEX.test(content)) {
+      filesNeedingMigration.push(abs);
+    }
+  }
+  return { filesNeedingMigration };
+}
+function createBootstrapMarkerMigrationCheck(inspection) {
+  if (inspection.filesNeedingMigration.length === 0) {
+    return okCheck(
+      "Bootstrap marker migration",
+      "No legacy fabric:knowledge-base markers detected in bootstrap target files."
+    );
+  }
+  const list = inspection.filesNeedingMigration.join(", ");
+  return issueCheck(
+    "Bootstrap marker migration",
+    "error",
+    "fixable_error",
+    "bootstrap_marker_migration_required",
+    `${inspection.filesNeedingMigration.length} file${inspection.filesNeedingMigration.length === 1 ? "" : "s"} still carry the legacy fabric:knowledge-base bootstrap marker: ${list}.`,
+    "Run `fab doctor --fix` to migrate to fabric:bootstrap marker"
+  );
+}
+async function inspectL1BootstrapSnapshotDrift(target) {
+  const abs = join6(target, ".fabric", "AGENTS.md");
+  if (!existsSync4(abs)) {
+    return { status: "missing", canonical: BOOTSTRAP_CANONICAL, onDisk: null };
+  }
+  let onDisk;
+  try {
+    onDisk = await readFile5(abs, "utf8");
+  } catch {
+    return { status: "missing", canonical: BOOTSTRAP_CANONICAL, onDisk: null };
+  }
+  if (onDisk === BOOTSTRAP_CANONICAL) {
+    return { status: "ok", canonical: BOOTSTRAP_CANONICAL, onDisk };
+  }
+  return { status: "drift", canonical: BOOTSTRAP_CANONICAL, onDisk };
+}
+function createL1BootstrapSnapshotDriftCheck(inspection) {
+  if (inspection.status === "drift") {
+    return issueCheck(
+      "Bootstrap snapshot drift",
+      "error",
+      "fixable_error",
+      "bootstrap_snapshot_drift",
+      ".fabric/AGENTS.md content diverges byte-for-byte from BOOTSTRAP_CANONICAL.",
+      "Run `fab doctor --fix` to restore canonical bootstrap snapshot"
+    );
+  }
+  return okCheck(
+    "Bootstrap snapshot drift",
+    inspection.status === "ok" ? ".fabric/AGENTS.md byte-equals BOOTSTRAP_CANONICAL." : ".fabric/AGENTS.md absent \u2014 delegated to bootstrap_anchor_missing."
+  );
+}
+async function inspectL2ManagedBlockDrift(target) {
+  const snapshotPath = join6(target, ".fabric", "AGENTS.md");
+  if (!existsSync4(snapshotPath)) {
+    return { status: "ok", drifted: [] };
+  }
+  let snapshot;
+  try {
+    snapshot = await readFile5(snapshotPath, "utf8");
+  } catch {
+    return { status: "ok", drifted: [] };
+  }
+  const projectRulesPath = join6(target, ".fabric", "project-rules.md");
+  let expectedBody = snapshot;
+  if (existsSync4(projectRulesPath)) {
+    try {
+      const projectRules = await readFile5(projectRulesPath, "utf8");
+      expectedBody = `${snapshot}
+---
+${projectRules}`;
+    } catch {
+    }
+  }
+  const drifted = [];
+  let anyManagedBlockFound = false;
+  const blockTargets = [
+    join6(target, "AGENTS.md"),
+    join6(target, ".cursor", "rules", "fabric-bootstrap.mdc")
+  ];
+  for (const abs of blockTargets) {
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (!BOOTSTRAP_REGEX.test(content) && LEGACY_KB_REGEX.test(content)) {
+      continue;
+    }
+    const match = content.match(BOOTSTRAP_REGEX);
+    if (match === null) {
+      continue;
+    }
+    anyManagedBlockFound = true;
+    const region = match[0];
+    const beginIdx = region.indexOf(BOOTSTRAP_MARKER_BEGIN);
+    const bodyStart = beginIdx + BOOTSTRAP_MARKER_BEGIN.length;
+    const endIdx = region.indexOf(BOOTSTRAP_MARKER_END, bodyStart);
+    if (bodyStart < 0 || endIdx < 0) {
+      continue;
+    }
+    let body = region.slice(bodyStart, endIdx);
+    if (body.startsWith("\n")) body = body.slice(1);
+    if (body.endsWith("\n")) body = body.slice(0, -1);
+    if (body !== expectedBody) {
+      drifted.push({ path: abs, expected: expectedBody, actual: body });
+    }
+  }
+  const claudeMdPath = join6(target, "CLAUDE.md");
+  if (existsSync4(claudeMdPath)) {
+    let claudeContent;
+    try {
+      claudeContent = await readFile5(claudeMdPath, "utf8");
+      if (!BOOTSTRAP_REGEX.test(claudeContent) && LEGACY_KB_REGEX.test(claudeContent)) {
+      } else {
+        anyManagedBlockFound = true;
+        const lines = claudeContent.split(/\r?\n/u);
+        const hasAtImport = lines.some((line) => line.trim() === "@.fabric/AGENTS.md");
+        if (!hasAtImport) {
+          drifted.push({
+            path: claudeMdPath,
+            expected: "@.fabric/AGENTS.md",
+            actual: "(line missing)"
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  if (!anyManagedBlockFound) {
+    return { status: "no-managed-block", drifted: [] };
+  }
+  if (drifted.length === 0) {
+    return { status: "ok", drifted: [] };
+  }
+  return { status: "drift", drifted };
+}
+function createL2ManagedBlockDriftCheck(inspection) {
+  if (inspection.status === "drift") {
+    const list = inspection.drifted.map((d) => d.path).join(", ");
+    return issueCheck(
+      "Managed block drift",
+      "error",
+      "fixable_error",
+      "managed_block_drift",
+      `${inspection.drifted.length} three-end managed block${inspection.drifted.length === 1 ? "" : "s"} diverge from expected body (snapshot + optional project-rules concat): ${list}.`,
+      "Run `fab doctor --fix` to restore three-end managed blocks from canonical"
+    );
+  }
+  return okCheck(
+    "Managed block drift",
+    inspection.status === "ok" ? "Three-end managed blocks byte-equal expectedBody." : "No three-end managed blocks detected \u2014 propagation pending or legacy-marker state."
+  );
+}
 function createBootstrapAnchorCheck(inspection) {
   if (!inspection.hasAgentsMd && !inspection.hasClaudeMd) {
     return issueCheck(
@@ -2142,16 +2587,82 @@ function createBootstrapAnchorCheck(inspection) {
   return okCheck("Bootstrap anchor", `Bootstrap anchor present at repo root: ${present}.`);
 }
 function inspectKnowledgeDirMissing(projectRoot) {
-  const knowledgeRoot = join5(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
   const missingSubdirs = [];
-  for (const sub of KNOWLEDGE_SUBDIRS2) {
-    const path = join5(knowledgeRoot, sub);
+  for (const sub of KNOWLEDGE_SUBDIRS3) {
+    const path = join6(knowledgeRoot, sub);
     if (!existsSync4(path)) {
       missingSubdirs.push(`.fabric/knowledge/${sub}`);
     }
   }
   return { missingSubdirs };
 }
+function inspectBaselineFilenameFormat(projectRoot) {
+  const offenders = [];
+  const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
+  if (!existsSync4(knowledgeRoot)) {
+    return { offenders };
+  }
+  for (const sub of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
+    const dir = join6(knowledgeRoot, sub);
+    if (!existsSync4(dir)) {
+      continue;
+    }
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryName = entry.name;
+      if (!entry.isFile() || !entryName.endsWith(".md")) {
+        continue;
+      }
+      if (BASELINE_ID_PREFIXED_FILENAME_PATTERN.test(entryName)) {
+        continue;
+      }
+      const abs = join6(dir, entryName);
+      let source;
+      try {
+        source = readFileSync2(abs, "utf8");
+      } catch {
+        continue;
+      }
+      const id = extractKnowledgeFrontmatterId(source);
+      if (id === null) {
+        continue;
+      }
+      if (!BASELINE_FILENAME_LINT_BASELINE_IDS.has(id)) {
+        continue;
+      }
+      offenders.push({
+        path: posix.join(".fabric/knowledge", sub, entryName),
+        stable_id: id
+      });
+    }
+  }
+  offenders.sort((a, b) => a.path.localeCompare(b.path));
+  return { offenders };
+}
+function createBaselineFilenameFormatCheck(inspection) {
+  if (inspection.offenders.length === 0) {
+    return okCheck(
+      "Baseline filename format",
+      "All baseline knowledge files use the canonical `${id}--${slug}.md` filename format."
+    );
+  }
+  const first = inspection.offenders[0];
+  const detail = `${first.stable_id} at ${first.path}`;
+  return issueCheck(
+    "Baseline filename format",
+    "error",
+    "manual_error",
+    "lint-baseline-filename-format",
+    `${inspection.offenders.length} baseline knowledge file${inspection.offenders.length === 1 ? "" : "s"} use${inspection.offenders.length === 1 ? "s" : ""} the deprecated bare-slug filename format and must be migrated to \`\${id}--\${slug}.md\`. First: ${detail}.`,
+    "Run `fab scan` to auto-migrate baseline filenames to the canonical `${id}--${slug}.md` format."
+  );
+}
 function createKnowledgeDirMissingCheck(inspection) {
   if (inspection.missingSubdirs.length > 0) {
     const list = inspection.missingSubdirs.join(", ");
@@ -2166,7 +2677,7 @@ function createKnowledgeDirMissingCheck(inspection) {
   }
   return okCheck(
     "Knowledge layout",
-    `All ${KNOWLEDGE_SUBDIRS2.length} required .fabric/knowledge/* subdirectories exist.`
+    `All ${KNOWLEDGE_SUBDIRS3.length} required .fabric/knowledge/* subdirectories exist.`
   );
 }
 function createForensicCheck(forensic, frameworkKind, entryPointCount) {
@@ -2195,11 +2706,11 @@ function createMetaCheck(meta) {
   if (meta.stale) {
     return issueCheck(
       "Agents metadata",
-      "error",
-      "fixable_error",
+      "warn",
+      "warning",
       "agents_meta_stale",
       `.fabric/agents.meta.json revision ${meta.revision} does not match .fabric/knowledge derived revision ${meta.computedRevision ?? "<unknown>"}.`,
-      "Run `fab doctor --fix` to reconcile agents.meta.json with the current knowledge files."
+      "Benign \u2014 engine auto-heals on next plan-context/get-sections call. Run `fab doctor --fix` for explicit reconciliation."
     );
   }
   return okCheck("Agents metadata", `.fabric/agents.meta.json revision ${meta.revision} is aligned with .fabric/knowledge.`);
@@ -2312,7 +2823,7 @@ function findIssue(issues, code) {
   };
 }
 async function inspectMetaManuallyDiverged(projectRoot) {
-  const metaPath = join5(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join6(projectRoot, ".fabric", "agents.meta.json");
   if (!existsSync4(metaPath)) {
     return { extraMetaEntries: [], hashMismatchEntries: [], readable: false };
   }
@@ -2332,13 +2843,13 @@ async function inspectMetaManuallyDiverged(projectRoot) {
   const hashMismatchEntries = [];
   for (const node of Object.values(meta.nodes)) {
     const contentRef = node.content_ref ?? node.file;
-    const absPath = join5(projectRoot, contentRef);
+    const absPath = join6(projectRoot, contentRef);
     if (!existsSync4(absPath)) {
       extraMetaEntries.push(contentRef);
       continue;
     }
     try {
-      const content = readFileSync(absPath, "utf8");
+      const content = readFileSync2(absPath, "utf8");
       const diskHash = sha256(content);
       if (node.hash !== "" && node.hash !== diskHash) {
         hashMismatchEntries.push(contentRef);
@@ -2351,7 +2862,7 @@ async function inspectMetaManuallyDiverged(projectRoot) {
 }
 function inspectKnowledgeDirUnindexed(projectRoot, meta) {
   const physicalMdFiles = /* @__PURE__ */ new Set();
-  collectMdFilesUnder(physicalMdFiles, projectRoot, join5(projectRoot, ".fabric", "knowledge"), ".fabric/knowledge");
+  collectMdFilesUnder(physicalMdFiles, projectRoot, join6(projectRoot, ".fabric", "knowledge"), ".fabric/knowledge");
   if (physicalMdFiles.size === 0) {
     return { unindexedFiles: [] };
   }
@@ -2376,7 +2887,7 @@ function collectMdFilesUnder(out, projectRoot, rootDir, relPrefix) {
       continue;
     }
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const abs = join5(dir, entry.name);
+      const abs = join6(dir, entry.name);
       if (entry.isDirectory()) {
         stack.push(abs);
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -2401,7 +2912,7 @@ function createKnowledgeDirUnindexedCheck(inspection) {
 }
 async function inspectStableIdCollisions(projectRoot) {
   const found = [];
-  const knowledgeDir = join5(projectRoot, ".fabric", "knowledge");
+  const knowledgeDir = join6(projectRoot, ".fabric", "knowledge");
   if (existsSync4(knowledgeDir)) {
     const stack = [knowledgeDir];
     while (stack.length > 0) {
@@ -2410,7 +2921,7 @@ async function inspectStableIdCollisions(projectRoot) {
         continue;
       }
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const abs = join5(dir, entry.name);
+        const abs = join6(dir, entry.name);
         if (entry.isDirectory()) {
           stack.push(abs);
         } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -2566,17 +3077,17 @@ function createMetaManuallyDivergedCheck(inspection) {
 }
 function inspectPreexistingRootFiles(projectRoot) {
   const candidates = ["CLAUDE.md", "AGENTS.md"];
-  const detected = candidates.filter((name) => existsSync4(join5(projectRoot, name)));
+  const detected = candidates.filter((name) => existsSync4(join6(projectRoot, name)));
   return { detected };
 }
 async function inspectFilesystemEditFallback(projectRoot) {
-  const knowledgeRoot = join5(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
   if (!existsSync4(knowledgeRoot)) {
     return { synthesized: 0, synthesizedStableIds: [] };
   }
   const canonicalIds = /* @__PURE__ */ new Set();
   for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-    const dir = join5(knowledgeRoot, typeDir);
+    const dir = join6(knowledgeRoot, typeDir);
     if (!existsSync4(dir)) {
       continue;
     }
@@ -2778,12 +3289,12 @@ function extractKnowledgeFrontmatterCreatedAt(source) {
   return Number.isFinite(parsed) ? parsed : null;
 }
 function* iterateCanonicalEntries(projectRoot, lastActiveIndex) {
-  const knowledgeRoot = join5(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
   if (!existsSync4(knowledgeRoot)) {
     return;
   }
   for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-    const dir = join5(knowledgeRoot, typeDir);
+    const dir = join6(knowledgeRoot, typeDir);
     if (!existsSync4(dir)) {
       continue;
     }
@@ -2802,10 +3313,10 @@ function* iterateCanonicalEntries(projectRoot, lastActiveIndex) {
         continue;
       }
       const stableId = match[1];
-      const absPath = join5(dir, entry.name);
+      const absPath = join6(dir, entry.name);
       let source;
       try {
-        source = readFileSync(absPath, "utf8");
+        source = readFileSync2(absPath, "utf8");
       } catch {
         continue;
       }
@@ -2818,7 +3329,7 @@ function* iterateCanonicalEntries(projectRoot, lastActiveIndex) {
       let lastReferenceMs = Math.max(createdAt ?? 0, eventTs);
       if (lastReferenceMs === 0) {
         try {
-          lastReferenceMs = statSync3(absPath).mtimeMs;
+          lastReferenceMs = statSync4(absPath).mtimeMs;
         } catch {
           lastReferenceMs = 0;
         }
@@ -2878,8 +3389,8 @@ async function inspectStaleArchive(projectRoot, now) {
   return { candidates };
 }
 function* iteratePendingFiles(projectRoot, now) {
-  const teamRoot = join5(projectRoot, ".fabric", "knowledge", "pending");
-  const personalRoot = join5(resolvePersonalRootForPending(), ".fabric", "knowledge", "pending");
+  const teamRoot = join6(projectRoot, ".fabric", "knowledge", "pending");
+  const personalRoot = join6(resolvePersonalRootForPending(), ".fabric", "knowledge", "pending");
   for (const [layer, root, displayPrefix] of [
     ["team", teamRoot, ".fabric/knowledge/pending"],
     ["personal", personalRoot, "~/.fabric/knowledge/pending"]
@@ -2894,7 +3405,7 @@ function* iteratePendingFiles(projectRoot, now) {
       continue;
     }
     for (const typeDir of typeDirs) {
-      const dir = join5(root, typeDir);
+      const dir = join6(root, typeDir);
       let entries;
       try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -2905,17 +3416,17 @@ function* iteratePendingFiles(projectRoot, now) {
         if (!entry.isFile() || !entry.name.endsWith(".md")) {
           continue;
         }
-        const absPath = join5(dir, entry.name);
+        const absPath = join6(dir, entry.name);
         let source = "";
         try {
-          source = readFileSync(absPath, "utf8");
+          source = readFileSync2(absPath, "utf8");
         } catch {
           continue;
         }
         const createdAt = extractKnowledgeFrontmatterCreatedAt(source);
         let mtimeMs = 0;
         try {
-          mtimeMs = statSync3(absPath).mtimeMs;
+          mtimeMs = statSync4(absPath).mtimeMs;
         } catch {
           mtimeMs = 0;
         }
@@ -2949,7 +3460,7 @@ function* iteratePendingFiles(projectRoot, now) {
   }
 }
 function resolvePersonalRootForPending() {
-  return process.env.FABRIC_HOME ?? homedir2();
+  return process.env.FABRIC_HOME ?? homedir3();
 }
 function inspectPendingOverdue(projectRoot, now) {
   const candidates = [];
@@ -2980,7 +3491,7 @@ function inspectPendingAutoArchive(projectRoot, now) {
         pending_path: visit.pending_path,
         pending_path_abs: visit.pending_path_abs,
         archived_to: archivedToRel,
-        archived_to_abs: join5(projectRoot, archivedToRel),
+        archived_to_abs: join6(projectRoot, archivedToRel),
         age_days: visit.age_days
       });
     } else {
@@ -2989,7 +3500,7 @@ function inspectPendingAutoArchive(projectRoot, now) {
         visit.type,
         visit.filename
       );
-      const archivedToAbs = join5(
+      const archivedToAbs = join6(
         resolvePersonalRootForPending(),
         ".fabric",
         ".archive",
@@ -3013,11 +3524,11 @@ function inspectPendingAutoArchive(projectRoot, now) {
 }
 function inspectUnderseeded(projectRoot) {
   const threshold = readUnderseedThresholdFromConfig(projectRoot);
-  const knowledgeRoot = join5(projectRoot, ".fabric", "knowledge");
+  const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
   let nodeCount = 0;
   if (existsSync4(knowledgeRoot)) {
     for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-      const dir = join5(knowledgeRoot, typeDir);
+      const dir = join6(knowledgeRoot, typeDir);
       if (!existsSync4(dir)) continue;
       let entries;
       try {
@@ -3039,7 +3550,7 @@ function inspectUnderseeded(projectRoot) {
   };
 }
 function inspectSessionHintsStale(projectRoot, now) {
-  const cacheDir = join5(projectRoot, ".fabric", ".cache");
+  const cacheDir = join6(projectRoot, ".fabric", ".cache");
   if (!existsSync4(cacheDir)) {
     return { candidates: [] };
   }
@@ -3054,10 +3565,10 @@ function inspectSessionHintsStale(projectRoot, now) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith(SESSION_HINTS_FILE_PREFIX)) continue;
     if (!entry.name.endsWith(SESSION_HINTS_FILE_SUFFIX)) continue;
-    const absPath = join5(cacheDir, entry.name);
+    const absPath = join6(cacheDir, entry.name);
     let mtimeMs = 0;
     try {
-      mtimeMs = statSync3(absPath).mtimeMs;
+      mtimeMs = statSync4(absPath).mtimeMs;
     } catch {
       continue;
     }
@@ -3084,11 +3595,11 @@ function inspectNarrowTooFew(projectRoot, now) {
   const structuralFlagged = total >= NARROW_MIN_TOTAL && narrowRatio < NARROW_RATIO_THRESHOLD;
   const windowStartMs = now - SILENCE_WINDOW_DAYS * MS_PER_DAY;
   const editFires = readCounterTimestamps(
-    join5(projectRoot, EDIT_COUNTER_FILE_REL),
+    join6(projectRoot, EDIT_COUNTER_FILE_REL),
     windowStartMs
   );
   const silenceFires = readCounterTimestamps(
-    join5(projectRoot, HINT_SILENCE_COUNTER_FILE_REL),
+    join6(projectRoot, HINT_SILENCE_COUNTER_FILE_REL),
     windowStartMs
   );
   const telemetrySkipped = editFires === 0;
@@ -3110,7 +3621,7 @@ function readCounterTimestamps(absPath, windowStartMs) {
   if (!existsSync4(absPath)) return 0;
   let raw;
   try {
-    raw = readFileSync(absPath, "utf8");
+    raw = readFileSync2(absPath, "utf8");
   } catch {
     return 0;
   }
@@ -3126,10 +3637,10 @@ function readCounterTimestamps(absPath, windowStartMs) {
   return count;
 }
 function readUnderseedThresholdFromConfig(projectRoot) {
-  const configPath = join5(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join6(projectRoot, ".fabric", "fabric-config.json");
   if (!existsSync4(configPath)) return DEFAULT_UNDERSEED_NODE_THRESHOLD;
   try {
-    const raw = readFileSync(configPath, "utf8");
+    const raw = readFileSync2(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.underseed_node_threshold;
@@ -3259,11 +3770,11 @@ function extractKnowledgeFrontmatterRelevancePaths(source) {
 }
 function* iterateRelevanceFrontmatter(projectRoot) {
   for (const visit of iterateCanonicalFilenames(projectRoot)) {
-    const layerRoot = visit.layer === "team" ? join5(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
-    const absPath = join5(layerRoot, visit.type, visit.filename);
+    const layerRoot = visit.layer === "team" ? join6(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
+    const absPath = join6(layerRoot, visit.type, visit.filename);
     let source;
     try {
-      source = readFileSync(absPath, "utf8");
+      source = readFileSync2(absPath, "utf8");
     } catch {
       continue;
     }
@@ -3330,7 +3841,7 @@ function collectWorkspacePathsForGlobMatch(projectRoot) {
   }
   let rootStat;
   try {
-    rootStat = statSync3(projectRoot);
+    rootStat = statSync4(projectRoot);
   } catch {
     return [];
   }
@@ -3349,7 +3860,7 @@ function collectWorkspacePathsForGlobMatch(projectRoot) {
       continue;
     }
     for (const entry of entries) {
-      const abs = join5(current, entry.name);
+      const abs = join6(current, entry.name);
       const rel = normalizePath(abs.slice(projectRoot.length + 1));
       if (rel.length === 0) continue;
       if (entry.isDirectory()) {
@@ -3489,8 +4000,8 @@ 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(
+  const teamRoot = join6(projectRoot, ".fabric", "knowledge", "pending");
+  const personalRoot = join6(
     resolvePersonalRootForPending(),
     ".fabric",
     "knowledge",
@@ -3510,7 +4021,7 @@ function inspectRelevanceFieldsMissing(projectRoot) {
       continue;
     }
     for (const typeDir of typeDirs) {
-      const dir = join5(root, typeDir);
+      const dir = join6(root, typeDir);
       let entries;
       try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -3521,10 +4032,10 @@ function inspectRelevanceFieldsMissing(projectRoot) {
         if (!entry.isFile() || !entry.name.endsWith(".md")) {
           continue;
         }
-        const absPath = join5(dir, entry.name);
+        const absPath = join6(dir, entry.name);
         let source;
         try {
-          source = readFileSync(absPath, "utf8");
+          source = readFileSync2(absPath, "utf8");
         } catch {
           continue;
         }
@@ -3608,7 +4119,7 @@ async function applyRelevanceFieldsMissing(candidate) {
         error: "fields already present at write time (no diff)"
       };
     }
-    await atomicWriteText3(candidate.pending_path_abs, rewritten);
+    await atomicWriteText4(candidate.pending_path_abs, rewritten);
     return {
       kind: "knowledge_relevance_fields_missing",
       path: candidate.pending_path,
@@ -3652,7 +4163,7 @@ 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);
+    const rootAbs = join6(projectRoot, rootRel);
     if (!existsSync4(rootAbs)) continue;
     let dirEntries;
     try {
@@ -3662,11 +4173,11 @@ function inspectSkillMdYamlInvalid(projectRoot) {
     }
     for (const dirEntry of dirEntries) {
       if (!dirEntry.isDirectory()) continue;
-      const skillFile = join5(rootAbs, dirEntry.name, "SKILL.md");
+      const skillFile = join6(rootAbs, dirEntry.name, "SKILL.md");
       if (!existsSync4(skillFile)) continue;
       let raw;
       try {
-        raw = readFileSync(skillFile, "utf8");
+        raw = readFileSync2(skillFile, "utf8");
       } catch {
         continue;
       }
@@ -3766,8 +4277,8 @@ function createNarrowTooFewCheck(inspection) {
   );
 }
 function resolvePersonalKnowledgeRoot() {
-  const home = process.env.FABRIC_HOME ?? homedir2();
-  return join5(home, ".fabric", "knowledge");
+  const home = process.env.FABRIC_HOME ?? homedir3();
+  return join6(home, ".fabric", "knowledge");
 }
 function parseStableIdFromCanonicalFilename(filename) {
   const match = CANONICAL_KNOWLEDGE_FILENAME_PATTERN.exec(filename);
@@ -3787,7 +4298,7 @@ function parseStableIdFromCanonicalFilename(filename) {
   };
 }
 function* iterateCanonicalFilenames(projectRoot) {
-  const teamRoot = join5(projectRoot, ".fabric", "knowledge");
+  const teamRoot = join6(projectRoot, ".fabric", "knowledge");
   const personalRoot = resolvePersonalKnowledgeRoot();
   for (const [layer, root, displayPrefix] of [
     ["team", teamRoot, ".fabric/knowledge"],
@@ -3797,7 +4308,7 @@ function* iterateCanonicalFilenames(projectRoot) {
       continue;
     }
     for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS) {
-      const dir = join5(root, typeDir);
+      const dir = join6(root, typeDir);
       if (!existsSync4(dir)) {
         continue;
       }
@@ -3953,14 +4464,133 @@ function createIndexDriftCheck(inspection) {
     "Run `fab doctor --apply-lint` (rc.4 TASK-003) to bump agents.meta.json counters to max_observed + 1."
   );
 }
+async function migrateBootstrapMarkers(projectRoot) {
+  const paths = [];
+  const countPerPath = {};
+  for (const rel of BOOTSTRAP_MARKER_MIGRATION_TARGETS) {
+    const abs = join6(projectRoot, rel);
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let original;
+    try {
+      original = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    const beginMatches = original.match(/<!-- fabric:knowledge-base:begin -->/g);
+    const endMatches = original.match(/<!-- fabric:knowledge-base:end -->/g);
+    const replacedCount = (beginMatches?.length ?? 0) + (endMatches?.length ?? 0);
+    if (replacedCount === 0) {
+      continue;
+    }
+    const rewritten = original.replace(/<!-- fabric:knowledge-base:begin -->/g, BOOTSTRAP_MARKER_BEGIN).replace(/<!-- fabric:knowledge-base:end -->/g, BOOTSTRAP_MARKER_END);
+    if (rewritten === original) {
+      continue;
+    }
+    await atomicWriteText4(abs, rewritten);
+    paths.push(abs);
+    countPerPath[abs] = replacedCount;
+  }
+  return { paths, countPerPath };
+}
+async function rewriteThreeEndManagedBlocks(projectRoot) {
+  const snapshotPath = join6(projectRoot, ".fabric", "AGENTS.md");
+  if (!existsSync4(snapshotPath)) {
+    return;
+  }
+  let snapshot;
+  try {
+    snapshot = await readFile5(snapshotPath, "utf8");
+  } catch {
+    return;
+  }
+  const projectRulesPath = join6(projectRoot, ".fabric", "project-rules.md");
+  const hasProjectRules = existsSync4(projectRulesPath);
+  let expectedBody = snapshot;
+  if (hasProjectRules) {
+    try {
+      const projectRules = await readFile5(projectRulesPath, "utf8");
+      expectedBody = `${snapshot}
+---
+${projectRules}`;
+    } catch {
+    }
+  }
+  const managedBlock = `${BOOTSTRAP_MARKER_BEGIN}
+${expectedBody}
+${BOOTSTRAP_MARKER_END}`;
+  const blockTargets = [
+    join6(projectRoot, "AGENTS.md"),
+    join6(projectRoot, ".cursor", "rules", "fabric-bootstrap.mdc")
+  ];
+  for (const abs of blockTargets) {
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let existing;
+    try {
+      existing = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    let next;
+    const match = existing.match(BOOTSTRAP_REGEX);
+    if (match !== null) {
+      const before = existing.slice(0, match.index ?? 0);
+      const after = existing.slice((match.index ?? 0) + match[0].length);
+      const stripped = `${before}${after.replace(/^\r?\n/, "")}`;
+      const trailingNewline = stripped.length === 0 || stripped.endsWith("\n") ? "" : "\n";
+      next = `${stripped}${trailingNewline}
+${managedBlock}
+`;
+    } else {
+      const trailingNewline = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+      next = `${existing}${trailingNewline}
+${managedBlock}
+`;
+    }
+    if (next === existing) {
+      continue;
+    }
+    await atomicWriteText4(abs, next);
+  }
+  const claudeMdPath = join6(projectRoot, "CLAUDE.md");
+  if (existsSync4(claudeMdPath)) {
+    let claudeContent;
+    try {
+      claudeContent = await readFile5(claudeMdPath, "utf8");
+    } catch {
+      return;
+    }
+    const lines = claudeContent.split(/\r?\n/u);
+    let updated = claudeContent;
+    const ensureLine = (line) => {
+      if (lines.some((existingLine) => existingLine.trim() === line)) {
+        return;
+      }
+      const trailingNewline = updated.length === 0 || updated.endsWith("\n") ? "" : "\n";
+      updated = `${updated}${trailingNewline}${line}
+`;
+      lines.push(line);
+    };
+    ensureLine("@.fabric/AGENTS.md");
+    if (hasProjectRules) {
+      ensureLine("@.fabric/project-rules.md");
+    }
+    if (updated !== claudeContent) {
+      await atomicWriteText4(claudeMdPath, updated);
+    }
+  }
+}
 async function fixMcpConfigInWrongFile(projectRoot) {
-  const settingsPath = join5(projectRoot, ".claude", "settings.json");
+  const settingsPath = join6(projectRoot, ".claude", "settings.json");
   if (!existsSync4(settingsPath)) {
     return;
   }
   let settings;
   try {
-    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync2(settingsPath, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return;
     }
@@ -3987,12 +4617,12 @@ async function fixMcpConfigInWrongFile(projectRoot) {
   });
 }
 async function ensureKnowledgeSubdirs(projectRoot) {
-  for (const sub of KNOWLEDGE_SUBDIRS2) {
-    await mkdir3(join5(projectRoot, ".fabric", "knowledge", sub), { recursive: true });
+  for (const sub of KNOWLEDGE_SUBDIRS3) {
+    await mkdir4(join6(projectRoot, ".fabric", "knowledge", sub), { recursive: true });
   }
 }
 async function fixCounterDesync(projectRoot) {
-  const metaPath = join5(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join6(projectRoot, ".fabric", "agents.meta.json");
   if (!existsSync4(metaPath)) {
     return;
   }
@@ -4026,6 +4656,275 @@ async function ensureEventLedger(projectRoot) {
   await ensureParentDirectory(path);
   await writeFile2(path, "", { encoding: "utf8", flag: "a" });
 }
+var CITE_POLICY_VERSION = "2.0.0-rc.20";
+async function ensureCitePolicyActivatedMarker(projectRoot) {
+  let existing;
+  try {
+    const { events } = await readEventLedger(projectRoot, { event_type: "cite_policy_activated" });
+    if (events.length > 0) {
+      existing = events[0];
+    }
+  } catch {
+    return { marker_ts: 0, emitted_now: false };
+  }
+  if (existing !== void 0) {
+    return { marker_ts: existing.ts, emitted_now: false };
+  }
+  try {
+    const stored = await appendEventLedgerEvent(projectRoot, {
+      event_type: "cite_policy_activated",
+      policy_version: CITE_POLICY_VERSION,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return { marker_ts: stored.ts, emitted_now: true };
+  } catch {
+    return { marker_ts: 0, emitted_now: false };
+  }
+}
+function categorizeCiteTag(tag) {
+  if (tag === "planned" || tag === "recalled" || tag === "chained-from" || tag === "none") {
+    return { category: tag };
+  }
+  if (tag === "dismissed") {
+    return { category: "dismissed", reason: "unspecified" };
+  }
+  if (tag.startsWith("dismissed:")) {
+    const remainder = tag.slice("dismissed:".length);
+    if (remainder.startsWith("other:")) {
+      return { category: "dismissed", reason: remainder.slice("other:".length) || "other" };
+    }
+    return { category: "dismissed", reason: remainder || "unspecified" };
+  }
+  return { category: "none" };
+}
+function matchesRelevancePath(editPath, relevancePaths) {
+  if (relevancePaths.length === 0) {
+    return false;
+  }
+  const normalized = normalizePath(editPath);
+  for (const glob of relevancePaths) {
+    if (minimatch(normalized, glob, { dot: true, matchBase: false })) {
+      return true;
+    }
+  }
+  return false;
+}
+async function runDoctorCiteCoverage(projectRoot, options) {
+  const marker = await ensureCitePolicyActivatedMarker(projectRoot);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const zeroMetrics = {
+    edits_touched: 0,
+    qualifying_cites: 0,
+    recalled_unverified: 0,
+    expected_but_missed: 0,
+    total_turns: 0
+  };
+  if (marker.marker_ts === 0) {
+    return {
+      status: "skipped",
+      marker_ts: 0,
+      marker_emitted_now: false,
+      since_ts: options.since,
+      client_filter: options.client,
+      metrics: zeroMetrics,
+      generated_at: generatedAt
+    };
+  }
+  const effectiveSince = Math.max(marker.marker_ts, options.since);
+  let ledgerEvents = [];
+  try {
+    const result = await readEventLedger(projectRoot, { since: effectiveSince });
+    ledgerEvents = result.events;
+  } catch {
+    return {
+      status: "ok",
+      marker_ts: marker.marker_ts,
+      marker_emitted_now: marker.emitted_now,
+      since_ts: effectiveSince,
+      client_filter: options.client,
+      metrics: zeroMetrics,
+      generated_at: generatedAt
+    };
+  }
+  const assistantTurns = [];
+  const editEvents = [];
+  const fetchEvents = [];
+  for (const event of ledgerEvents) {
+    switch (event.event_type) {
+      case "assistant_turn_observed":
+        assistantTurns.push(event);
+        break;
+      case "edit_intent_checked":
+        editEvents.push(event);
+        break;
+      case "knowledge_sections_fetched":
+        fetchEvents.push(event);
+        break;
+      default:
+        break;
+    }
+  }
+  const filteredTurns = options.client === "all" ? assistantTurns : assistantTurns.filter((t) => t.client === options.client);
+  let clientSessionIds = null;
+  if (options.client !== "all") {
+    clientSessionIds = /* @__PURE__ */ new Set();
+    for (const turn of assistantTurns) {
+      if (turn.client === options.client) {
+        const sid = turn.session_id;
+        if (typeof sid === "string" && sid.length > 0) {
+          clientSessionIds.add(sid);
+        }
+      }
+    }
+  }
+  const kbIndex = /* @__PURE__ */ new Map();
+  try {
+    const meta = await readAgentsMeta(projectRoot);
+    for (const node of Object.values(meta.nodes)) {
+      const stableId = node.stable_id;
+      if (typeof stableId !== "string" || stableId.length === 0) continue;
+      const description = node.description;
+      if (description === void 0) continue;
+      const paths = description.relevance_paths ?? [];
+      const scope = description.relevance_scope ?? "broad";
+      kbIndex.set(stableId, {
+        relevance_paths: paths,
+        // A broad entry with no paths is the safe default. A narrow entry must
+        // carry at least one path; an empty-paths narrow is treated as broad.
+        relevance_scope: scope === "narrow" && paths.length > 0 ? "narrow" : "broad"
+      });
+    }
+  } catch {
+  }
+  const fetchesBySession = /* @__PURE__ */ new Map();
+  for (const fetch of fetchEvents) {
+    const sid = fetch.session_id;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const list = fetchesBySession.get(sid) ?? [];
+    list.push(fetch.ts);
+    fetchesBySession.set(sid, list);
+  }
+  for (const list of fetchesBySession.values()) {
+    list.sort((a, b) => a - b);
+  }
+  const RECALL_WINDOW_MS = 6e4;
+  const isRecallVerified = (turn) => {
+    const sid = turn.session_id;
+    if (typeof sid !== "string" || sid.length === 0) return false;
+    const fetches = fetchesBySession.get(sid);
+    if (fetches === void 0 || fetches.length === 0) return false;
+    for (const ft of fetches) {
+      if (Math.abs(ft - turn.ts) <= RECALL_WINDOW_MS) return true;
+    }
+    return false;
+  };
+  const dismissedHistogram = {};
+  const perClientAccum = /* @__PURE__ */ new Map();
+  const emptyMetrics = () => ({
+    edits_touched: 0,
+    qualifying_cites: 0,
+    recalled_unverified: 0,
+    expected_but_missed: 0,
+    total_turns: 0
+  });
+  const bumpClient = (client, mut) => {
+    if (typeof client !== "string" || client.length === 0) return;
+    const existing = perClientAccum.get(client) ?? emptyMetrics();
+    mut(existing);
+    perClientAccum.set(client, existing);
+  };
+  const sessionCitedKbs = /* @__PURE__ */ new Map();
+  let totalTurns = 0;
+  let qualifyingCites = 0;
+  let recalledUnverified = 0;
+  for (const turn of filteredTurns) {
+    totalTurns += 1;
+    bumpClient(turn.client, (m) => {
+      m.total_turns += 1;
+    });
+    const sid = turn.session_id;
+    if (typeof sid === "string" && sid.length > 0) {
+      const set = sessionCitedKbs.get(sid) ?? /* @__PURE__ */ new Set();
+      for (const id of turn.cite_ids) {
+        set.add(id);
+      }
+      sessionCitedKbs.set(sid, set);
+    }
+    let turnHadRecalled = false;
+    for (const tag of turn.cite_tags) {
+      const { category, reason } = categorizeCiteTag(tag);
+      switch (category) {
+        case "planned":
+        case "recalled":
+        case "chained-from":
+          qualifyingCites += 1;
+          bumpClient(turn.client, (m) => {
+            m.qualifying_cites += 1;
+          });
+          if (category === "recalled") turnHadRecalled = true;
+          break;
+        case "dismissed": {
+          const key = reason ?? "unspecified";
+          dismissedHistogram[key] = (dismissedHistogram[key] ?? 0) + 1;
+          break;
+        }
+        case "none":
+        default:
+          break;
+      }
+    }
+    if (turnHadRecalled && !isRecallVerified(turn)) {
+      recalledUnverified += 1;
+      bumpClient(turn.client, (m) => {
+        m.recalled_unverified += 1;
+      });
+    }
+  }
+  let editsTouched = 0;
+  let expectedButMissed = 0;
+  for (const edit of editEvents) {
+    const sid = edit.session_id;
+    if (clientSessionIds !== null) {
+      if (typeof sid !== "string" || sid.length === 0) continue;
+      if (!clientSessionIds.has(sid)) continue;
+    }
+    editsTouched += 1;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const citedSet = sessionCitedKbs.get(sid) ?? /* @__PURE__ */ new Set();
+    for (const [kbId, kb] of kbIndex) {
+      if (kb.relevance_scope !== "narrow") continue;
+      if (!matchesRelevancePath(edit.path, kb.relevance_paths)) continue;
+      if (!citedSet.has(kbId)) {
+        expectedButMissed += 1;
+      }
+    }
+  }
+  const metrics = {
+    edits_touched: editsTouched,
+    qualifying_cites: qualifyingCites,
+    recalled_unverified: recalledUnverified,
+    expected_but_missed: expectedButMissed,
+    total_turns: totalTurns
+  };
+  let perClient;
+  if (options.client === "all" && perClientAccum.size > 0) {
+    perClient = {};
+    for (const [client, m] of perClientAccum) {
+      perClient[client] = m;
+    }
+  }
+  return {
+    status: "ok",
+    marker_ts: marker.marker_ts,
+    marker_emitted_now: marker.emitted_now,
+    since_ts: effectiveSince,
+    client_filter: options.client,
+    metrics,
+    ...perClient !== void 0 ? { per_client: perClient } : {},
+    ...Object.keys(dismissedHistogram).length > 0 ? { dismissed_reason_histogram: dismissedHistogram } : {},
+    generated_at: generatedAt
+  };
+}
 function createFixMessage(fixed, report) {
   const fixedText = fixed.length === 0 ? "No deterministic doctor fixes were needed." : `Applied ${fixed.length} deterministic doctor fix${fixed.length === 1 ? "" : "es"}.`;
   const manualText = report.manual_errors.length === 0 ? "No manual errors remain." : `${report.manual_errors.length} manual error${report.manual_errors.length === 1 ? "" : "s"} remain.`;
@@ -4046,7 +4945,7 @@ function normalizePath(path) {
   return posix.normalize(path.split("\\").join("/"));
 }
 function collectEntryPoints(root) {
-  if (!existsSync4(root) || !statSync3(root).isDirectory()) {
+  if (!existsSync4(root) || !statSync4(root).isDirectory()) {
     return [];
   }
   const entries = [];
@@ -4057,7 +4956,7 @@ function collectEntryPoints(root) {
       continue;
     }
     for (const entry of readdirSync(current, { withFileTypes: true })) {
-      const absolutePath = join5(current, entry.name);
+      const absolutePath = join6(current, entry.name);
       const relativePath = normalizePath(absolutePath.slice(root.length + 1));
       if (relativePath.length === 0) {
         continue;
@@ -4114,9 +5013,109 @@ function isMissingFileError(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
+// src/services/load-active-meta.ts
+async function loadActiveMeta(projectRoot, opts = {}) {
+  const onDisk = await readAgentsMeta(projectRoot);
+  const previousRevisionHash = onDisk.revision;
+  const derived = await buildKnowledgeMeta(projectRoot);
+  if (derived.meta.revision === previousRevisionHash) {
+    return {
+      meta: onDisk,
+      auto_healed: false,
+      previous_revision_hash: previousRevisionHash,
+      revision_hash: previousRevisionHash
+    };
+  }
+  const written = await writeKnowledgeMeta(projectRoot, { source: "doctor_fix" });
+  contextCache.invalidate("meta_write", projectRoot);
+  await emitAutoHealEventBestEffort(projectRoot, {
+    previous_revision_hash: previousRevisionHash,
+    revision_hash: written.meta.revision,
+    caller: opts.caller
+  });
+  return {
+    meta: written.meta,
+    auto_healed: true,
+    previous_revision_hash: previousRevisionHash,
+    revision_hash: written.meta.revision
+  };
+}
+async function loadActiveMetaOrStale(projectRoot, opts = {}) {
+  let onDisk;
+  try {
+    onDisk = await readAgentsMeta(projectRoot);
+  } catch (error) {
+    if (error instanceof AgentsMetaFileMissingError || error instanceof AgentsMetaInvalidError) {
+      throw error;
+    }
+    throw error;
+  }
+  const previousRevisionHash = onDisk.revision;
+  let derived;
+  try {
+    derived = await buildKnowledgeMeta(projectRoot);
+  } catch (error) {
+    return {
+      meta: onDisk,
+      auto_healed: false,
+      previous_revision_hash: previousRevisionHash,
+      revision_hash: previousRevisionHash,
+      degraded: true,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  if (derived.meta.revision === previousRevisionHash) {
+    return {
+      meta: onDisk,
+      auto_healed: false,
+      previous_revision_hash: previousRevisionHash,
+      revision_hash: previousRevisionHash,
+      degraded: false
+    };
+  }
+  let written;
+  try {
+    written = await writeKnowledgeMeta(projectRoot, { source: "doctor_fix" });
+  } catch (error) {
+    return {
+      meta: onDisk,
+      auto_healed: false,
+      previous_revision_hash: previousRevisionHash,
+      revision_hash: previousRevisionHash,
+      degraded: true,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  contextCache.invalidate("meta_write", projectRoot);
+  await emitAutoHealEventBestEffort(projectRoot, {
+    previous_revision_hash: previousRevisionHash,
+    revision_hash: written.meta.revision,
+    caller: opts.caller
+  });
+  return {
+    meta: written.meta,
+    auto_healed: true,
+    previous_revision_hash: previousRevisionHash,
+    revision_hash: written.meta.revision,
+    degraded: false
+  };
+}
+async function emitAutoHealEventBestEffort(projectRoot, payload) {
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "knowledge_meta_auto_healed",
+      previous_revision_hash: payload.previous_revision_hash,
+      revision_hash: payload.revision_hash,
+      trigger: "read",
+      ...payload.caller !== void 0 ? { caller: payload.caller } : {}
+    });
+  } catch {
+  }
+}
+
 // src/services/get-knowledge.ts
 import { readFile as readFile6 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { minimatch as minimatch2 } from "minimatch";
 var PRIORITY_ORDER = {
   high: 0,
@@ -4124,6 +5123,10 @@ var PRIORITY_ORDER = {
   low: 2
 };
 async function getKnowledge(projectRoot, input) {
+  const metaResult = await loadActiveMeta(projectRoot, { caller: "getKnowledge" });
+  if (metaResult.auto_healed) {
+    contextCache.invalidate("file_watch", projectRoot);
+  }
   const context = await loadGetKnowledgeContext(projectRoot);
   const stale = input.client_hash !== void 0 && input.client_hash !== context.meta.revision;
   const matchedNodes = matchRuleNodes(context.meta, input.path);
@@ -4156,7 +5159,7 @@ async function loadGetKnowledgeContext(projectRoot) {
     return cached;
   }
   const meta = await readAgentsMeta(projectRoot);
-  const l0Content = await readFile6(join6(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
+  const l0Content = await readFile6(join7(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
   const context = {
     meta,
     l0Content,
@@ -4295,13 +5298,14 @@ async function readRuleContent(projectRoot, file, fileContentCache) {
   if (cached !== void 0) {
     return await cached;
   }
-  const pending = readFile6(join6(projectRoot, file), "utf8");
+  const pending = readFile6(join7(projectRoot, file), "utf8");
   fileContentCache.set(file, pending);
   return await pending;
 }
 
 export {
   contextCache,
+  AgentsMetaFileMissingError,
   resolveProjectRoot,
   readAgentsMeta,
   LEDGER_PATH,
@@ -4328,9 +5332,12 @@ export {
   invalidateKnowledgeSyncCooldown,
   ensureKnowledgeFresh,
   reconcileKnowledge,
+  loadActiveMeta,
+  loadActiveMetaOrStale,
   getKnowledge,
   normalizeKnowledgePath,
   runDoctorReport,
   runDoctorFix,
-  runDoctorApplyLint
+  runDoctorApplyLint,
+  runDoctorCiteCoverage
 };