@skill-map/cli 0.20.1 → 0.21.0

package/dist/index.js

@@ -94,8 +94,8 @@ var Registry = class {
 
 // kernel/orchestrator.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync6, statSync as statSync2 } from "fs";
-import { isAbsolute as isAbsolute2, resolve as resolvePath } from "path";
+import { existsSync as existsSync8, statSync as statSync2 } from "fs";
+import { isAbsolute as isAbsolute3, resolve as resolvePath } from "path";
 import { Tiktoken } from "js-tiktoken/lite";
 import cl100k_base from "js-tiktoken/ranks/cl100k_base";
 import yaml4 from "js-yaml";
@@ -103,7 +103,7 @@ import yaml4 from "js-yaml";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.20.1",
+  version: "0.21.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -169,7 +169,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.20.0",
+    "@skill-map/spec": "0.21.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -368,175 +368,23 @@ function safeIsFile(path) {
 }
 
 // kernel/sidecar/store.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, renameSync, writeFileSync, unlinkSync } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
-import { createRequire as createRequire2 } from "module";
-import { Ajv2020 as Ajv20202 } from "ajv/dist/2020.js";
-import yaml2 from "js-yaml";
-
-// kernel/adapters/in-memory-progress.ts
-var InMemoryProgressEmitter = class {
-  #listeners = /* @__PURE__ */ new Set();
-  emit(event) {
-    for (const listener of this.#listeners) listener(event);
-  }
-  subscribe(listener) {
-    this.#listeners.add(listener);
-    return () => {
-      this.#listeners.delete(listener);
-    };
-  }
-};
-
-// kernel/adapters/silent-logger.ts
-var SilentLogger = class {
-  trace() {
-  }
-  debug() {
-  }
-  info() {
-  }
-  warn() {
-  }
-  error() {
-  }
-};
-
-// kernel/util/logger.ts
-var active = new SilentLogger();
-var log = {
-  trace: (message, context) => active.trace(message, context),
-  debug: (message, context) => active.debug(message, context),
-  info: (message, context) => active.info(message, context),
-  warn: (message, context) => active.warn(message, context),
-  error: (message, context) => active.error(message, context)
-};
-function configureLogger(impl) {
-  active = impl;
-}
-function resetLogger() {
-  active = new SilentLogger();
-}
-function getActiveLogger() {
-  return active;
-}
-
-// kernel/adapters/plugin-loader.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5, renameSync as renameSync2, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
+import { dirname as dirname4, resolve as resolve5 } from "path";
 import { createRequire as createRequire3 } from "module";
-import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
-import { isAbsolute, join as join2, relative as relative2, resolve as resolve3 } from "path";
-import { pathToFileURL } from "url";
 import { Ajv2020 as Ajv20203 } from "ajv/dist/2020.js";
-import semver from "semver";
-
-// kernel/i18n/plugin-store.texts.ts
-var PLUGIN_STORE_TEXTS = {
-  kvValidationFailed: "plugin '{{pluginId}}' ctx.store.set('{{key}}', value): value violates declared schema ({{schemaPath}}) \u2014 {{errors}}",
-  dedicatedValidationFailed: "plugin '{{pluginId}}' ctx.store.write('{{table}}', row): row violates declared schema ({{schemaPath}}) \u2014 {{errors}}"
-};
-
-// kernel/adapters/plugin-store.ts
-var KV_SCHEMA_KEY = "__kv__";
-function makeKvStoreWrapper(opts) {
-  const { pluginId, schema, persist } = opts;
-  return {
-    async set(key, value) {
-      if (schema) {
-        if (!schema.validate(value)) {
-          throw new Error(
-            tx(PLUGIN_STORE_TEXTS.kvValidationFailed, {
-              pluginId,
-              schemaPath: schema.schemaPath,
-              key,
-              errors: formatAjvErrors(schema.validate.errors ?? null)
-            })
-          );
-        }
-      }
-      await persist(key, value);
-    }
-  };
-}
-function makeDedicatedStoreWrapper(opts) {
-  const { pluginId, schemas, persist } = opts;
-  return {
-    async write(table, row) {
-      const schema = schemas?.[table];
-      if (schema) {
-        if (!schema.validate(row)) {
-          throw new Error(
-            tx(PLUGIN_STORE_TEXTS.dedicatedValidationFailed, {
-              pluginId,
-              table,
-              schemaPath: schema.schemaPath,
-              errors: formatAjvErrors(schema.validate.errors ?? null)
-            })
-          );
-        }
-      }
-      await persist(table, row);
-    }
-  };
-}
-function makePluginStore(opts) {
-  const manifest = opts.plugin.manifest;
-  if (!manifest?.storage) return void 0;
-  const storageSchemas = opts.plugin.storageSchemas;
-  if (manifest.storage.mode === "kv") {
-    if (!opts.persistKv) return void 0;
-    const schema = storageSchemas?.[KV_SCHEMA_KEY];
-    return makeKvStoreWrapper({
-      pluginId: manifest.id,
-      schema,
-      persist: opts.persistKv
-    });
-  }
-  if (manifest.storage.mode === "dedicated") {
-    if (!opts.persistDedicated) return void 0;
-    return makeDedicatedStoreWrapper({
-      pluginId: manifest.id,
-      schemas: storageSchemas,
-      persist: opts.persistDedicated
-    });
-  }
-  return void 0;
-}
-function formatAjvErrors(errors) {
-  if (!errors || errors.length === 0) return "(no AJV details)";
-  return errors.map((e) => `${e.instancePath || "(root)"} ${e.message ?? e.keyword}`).join("; ");
-}
+import yaml2 from "js-yaml";
 
-// kernel/extensions/hook.ts
-var HOOK_TRIGGERS = Object.freeze([
-  "boot",
-  "scan.started",
-  "scan.completed",
-  "extractor.completed",
-  "analyzer.completed",
-  "action.completed",
-  "job.spawning",
-  "job.completed",
-  "job.failed",
-  "shutdown"
-]);
+// core/config/helper.ts
+import { isAbsolute, resolve as resolve4 } from "path";
 
-// kernel/adapters/plugin-loader.ts
-var KNOWN_KINDS = /* @__PURE__ */ new Set(["provider", "extractor", "analyzer", "action", "formatter", "hook"]);
-var KNOWN_KINDS_LIST = [...KNOWN_KINDS].join(" / ");
-var HOOKABLE_TRIGGERS_LIST = HOOK_TRIGGERS.join(", ");
-function installedSpecVersion() {
-  const require2 = createRequire3(import.meta.url);
-  const indexPath = require2.resolve("@skill-map/spec/index.json");
-  const pkgPath = resolve3(indexPath, "..", "package.json");
-  const pkg = JSON.parse(readFileSync3(pkgPath, "utf8"));
-  return pkg.version;
-}
+// kernel/config/loader.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 
 // kernel/adapters/schema-validators.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { dirname as dirname3, resolve as resolve4 } from "path";
-import { createRequire as createRequire4 } from "module";
-import { Ajv2020 as Ajv20204 } from "ajv/dist/2020.js";
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { createRequire as createRequire2 } from "module";
+import { Ajv2020 as Ajv20202 } from "ajv/dist/2020.js";
 var SCHEMA_FILES = {
   node: "schemas/node.schema.json",
   link: "schemas/link.schema.json",
@@ -572,22 +420,22 @@ function loadSchemaValidators() {
 }
 function buildSchemaValidators() {
   const specRoot = resolveSpecRoot2();
-  const ajv = new Ajv20204({
+  const ajv = new Ajv20202({
     strict: false,
     allErrors: true,
     allowUnionTypes: true
   });
   applyAjvFormats(ajv);
   for (const rel of SUPPORTING_SCHEMAS) {
-    const file = resolve4(specRoot, rel);
+    const file = resolve2(specRoot, rel);
     if (!existsSyncSafe(file)) continue;
-    const schema = JSON.parse(readFileSync4(file, "utf8"));
+    const schema = JSON.parse(readFileSync2(file, "utf8"));
     ajv.addSchema(schema);
   }
   const validators = /* @__PURE__ */ new Map();
   for (const [name, rel] of Object.entries(SCHEMA_FILES)) {
-    const file = resolve4(specRoot, rel);
-    const schema = JSON.parse(readFileSync4(file, "utf8"));
+    const file = resolve2(specRoot, rel);
+    const schema = JSON.parse(readFileSync2(file, "utf8"));
     const byId = typeof schema.$id === "string" ? ajv.getSchema(schema.$id) : void 0;
     validators.set(name, byId ?? ajv.compile(schema));
   }
@@ -607,7 +455,7 @@ function buildSchemaValidators() {
   const KNOWN_SLOTS = /* @__PURE__ */ new Set([
     "card.title.right",
     "card.subtitle.left",
-    "card.footer.left.counter",
+    "card.footer.left",
     "card.footer.right",
     "graph.node.alert",
     "inspector.header.badge.counter",
@@ -618,7 +466,7 @@ function buildSchemaValidators() {
     "inspector.body.panel.key-values",
     "inspector.body.panel.link-list",
     "inspector.body.panel.markdown",
-    "topbar.actions.indicator"
+    "topbar.nav.start"
   ]);
   function getContributionValidator(slot) {
     if (!KNOWN_SLOTS.has(slot)) return null;
@@ -668,14 +516,14 @@ function buildSchemaValidators() {
 }
 function buildProviderFrontmatterValidator(providers) {
   const specRoot = resolveSpecRoot2();
-  const ajv = new Ajv20204({
+  const ajv = new Ajv20202({
     strict: false,
     allErrors: true,
     allowUnionTypes: true
   });
   applyAjvFormats(ajv);
-  const baseFile = resolve4(specRoot, "schemas/frontmatter/base.schema.json");
-  const baseSchema = JSON.parse(readFileSync4(baseFile, "utf8"));
+  const baseFile = resolve2(specRoot, "schemas/frontmatter/base.schema.json");
+  const baseSchema = JSON.parse(readFileSync2(baseFile, "utf8"));
   ajv.addSchema(baseSchema);
   registerProviderAuxiliarySchemas(ajv, providers);
   const compiled = /* @__PURE__ */ new Map();
@@ -713,10 +561,10 @@ function registerProviderAuxiliarySchemas(ajv, providers) {
   }
 }
 function resolveSpecRoot2() {
-  const require2 = createRequire4(import.meta.url);
+  const require2 = createRequire2(import.meta.url);
   try {
     const indexPath = require2.resolve("@skill-map/spec/index.json");
-    return dirname3(indexPath);
+    return dirname2(indexPath);
   } catch {
     throw new Error(
       "@skill-map/spec not resolvable \u2014 ensure the workspace is linked or the package is installed."
@@ -725,13 +573,201 @@ function resolveSpecRoot2() {
 }
 function existsSyncSafe(path) {
   try {
-    readFileSync4(path, "utf8");
+    readFileSync2(path, "utf8");
     return true;
   } catch {
     return false;
   }
 }
 
+// kernel/util/format-error.ts
+function formatErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// kernel/util/skill-map-paths.ts
+import { join as join3 } from "path";
+
+// core/paths/db-path.ts
+import { join as join2, resolve as resolve3 } from "path";
+var SKILL_MAP_DIR = ".skill-map";
+var DB_FILENAME = "skill-map.db";
+var LOCAL_SETTINGS_FILENAME = "settings.local.json";
+var DEFAULT_DB_REL = `${SKILL_MAP_DIR}/${DB_FILENAME}`;
+var GITIGNORE_ENTRIES = [
+  `${SKILL_MAP_DIR}/${LOCAL_SETTINGS_FILENAME}`,
+  `${SKILL_MAP_DIR}/${DB_FILENAME}`
+];
+
+// core/config/atomic-write.ts
+import {
+  existsSync as existsSync4,
+  mkdirSync,
+  readFileSync as readFileSync4,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname as dirname3 } from "path";
+
+// kernel/adapters/in-memory-progress.ts
+var InMemoryProgressEmitter = class {
+  #listeners = /* @__PURE__ */ new Set();
+  emit(event) {
+    for (const listener of this.#listeners) listener(event);
+  }
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+};
+
+// kernel/adapters/silent-logger.ts
+var SilentLogger = class {
+  trace() {
+  }
+  debug() {
+  }
+  info() {
+  }
+  warn() {
+  }
+  error() {
+  }
+};
+
+// kernel/util/logger.ts
+var active = new SilentLogger();
+var log = {
+  trace: (message, context) => active.trace(message, context),
+  debug: (message, context) => active.debug(message, context),
+  info: (message, context) => active.info(message, context),
+  warn: (message, context) => active.warn(message, context),
+  error: (message, context) => active.error(message, context)
+};
+function configureLogger(impl) {
+  active = impl;
+}
+function resetLogger() {
+  active = new SilentLogger();
+}
+function getActiveLogger() {
+  return active;
+}
+
+// kernel/adapters/plugin-loader.ts
+import { createRequire as createRequire4 } from "module";
+import { existsSync as existsSync6, readFileSync as readFileSync6, readdirSync as readdirSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join4, relative as relative2, resolve as resolve6 } from "path";
+import { pathToFileURL } from "url";
+import { Ajv2020 as Ajv20204 } from "ajv/dist/2020.js";
+import semver from "semver";
+
+// kernel/i18n/plugin-store.texts.ts
+var PLUGIN_STORE_TEXTS = {
+  kvValidationFailed: "plugin '{{pluginId}}' ctx.store.set('{{key}}', value): value violates declared schema ({{schemaPath}}) \u2014 {{errors}}",
+  dedicatedValidationFailed: "plugin '{{pluginId}}' ctx.store.write('{{table}}', row): row violates declared schema ({{schemaPath}}) \u2014 {{errors}}"
+};
+
+// kernel/adapters/plugin-store.ts
+var KV_SCHEMA_KEY = "__kv__";
+function makeKvStoreWrapper(opts) {
+  const { pluginId, schema, persist } = opts;
+  return {
+    async set(key, value) {
+      if (schema) {
+        if (!schema.validate(value)) {
+          throw new Error(
+            tx(PLUGIN_STORE_TEXTS.kvValidationFailed, {
+              pluginId,
+              schemaPath: schema.schemaPath,
+              key,
+              errors: formatAjvErrors(schema.validate.errors ?? null)
+            })
+          );
+        }
+      }
+      await persist(key, value);
+    }
+  };
+}
+function makeDedicatedStoreWrapper(opts) {
+  const { pluginId, schemas, persist } = opts;
+  return {
+    async write(table, row) {
+      const schema = schemas?.[table];
+      if (schema) {
+        if (!schema.validate(row)) {
+          throw new Error(
+            tx(PLUGIN_STORE_TEXTS.dedicatedValidationFailed, {
+              pluginId,
+              table,
+              schemaPath: schema.schemaPath,
+              errors: formatAjvErrors(schema.validate.errors ?? null)
+            })
+          );
+        }
+      }
+      await persist(table, row);
+    }
+  };
+}
+function makePluginStore(opts) {
+  const manifest = opts.plugin.manifest;
+  if (!manifest?.storage) return void 0;
+  const storageSchemas = opts.plugin.storageSchemas;
+  if (manifest.storage.mode === "kv") {
+    if (!opts.persistKv) return void 0;
+    const schema = storageSchemas?.[KV_SCHEMA_KEY];
+    return makeKvStoreWrapper({
+      pluginId: manifest.id,
+      schema,
+      persist: opts.persistKv
+    });
+  }
+  if (manifest.storage.mode === "dedicated") {
+    if (!opts.persistDedicated) return void 0;
+    return makeDedicatedStoreWrapper({
+      pluginId: manifest.id,
+      schemas: storageSchemas,
+      persist: opts.persistDedicated
+    });
+  }
+  return void 0;
+}
+function formatAjvErrors(errors) {
+  if (!errors || errors.length === 0) return "(no AJV details)";
+  return errors.map((e) => `${e.instancePath || "(root)"} ${e.message ?? e.keyword}`).join("; ");
+}
+
+// kernel/extensions/hook.ts
+var HOOK_TRIGGERS = Object.freeze([
+  "boot",
+  "scan.started",
+  "scan.completed",
+  "extractor.completed",
+  "analyzer.completed",
+  "action.completed",
+  "job.spawning",
+  "job.completed",
+  "job.failed",
+  "shutdown"
+]);
+
+// kernel/adapters/plugin-loader.ts
+var KNOWN_KINDS = /* @__PURE__ */ new Set(["provider", "extractor", "analyzer", "action", "formatter", "hook"]);
+var KNOWN_KINDS_LIST = [...KNOWN_KINDS].join(" / ");
+var HOOKABLE_TRIGGERS_LIST = HOOK_TRIGGERS.join(", ");
+function installedSpecVersion() {
+  const require2 = createRequire4(import.meta.url);
+  const indexPath = require2.resolve("@skill-map/spec/index.json");
+  const pkgPath = resolve6(indexPath, "..", "package.json");
+  const pkg = JSON.parse(readFileSync6(pkgPath, "utf8"));
+  return pkg.version;
+}
+
 // kernel/i18n/orchestrator.texts.ts
 var ORCHESTRATOR_TEXTS = {
   frontmatterInvalid: "Frontmatter for {{path}} ({{kind}}) failed schema validation: {{errors}}",
@@ -746,18 +782,13 @@ var ORCHESTRATOR_TEXTS = {
   runScanRootMissing: "runScan: root path '{{root}}' does not exist or is not a directory"
 };
 
-// kernel/util/format-error.ts
-function formatErrorMessage(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-
 // kernel/scan/walk-content.ts
 import { readFile, readdir, stat } from "fs/promises";
-import { join as join3, relative as relative3, sep as sep2 } from "path";
+import { join as join5, relative as relative3, sep as sep2 } from "path";
 
 // kernel/scan/ignore.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname4, resolve as resolve5 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { dirname as dirname5, resolve as resolve7 } from "path";
 import { fileURLToPath } from "url";
 import ignoreFactory from "ignore";
 function buildIgnoreFilter(opts = {}) {
@@ -789,18 +820,18 @@ function loadDefaultsText() {
   return cachedDefaults;
 }
 function readDefaultsFromDisk() {
-  const here = dirname4(fileURLToPath(import.meta.url));
+  const here = dirname5(fileURLToPath(import.meta.url));
   const candidates = [
-    resolve5(here, "../../config/defaults/skillmapignore"),
+    resolve7(here, "../../config/defaults/skillmapignore"),
     // src/kernel/scan/ → src/config/defaults/
-    resolve5(here, "../config/defaults/skillmapignore"),
+    resolve7(here, "../config/defaults/skillmapignore"),
     // dist/cli.js → dist/config/defaults/ (siblings)
-    resolve5(here, "config/defaults/skillmapignore")
+    resolve7(here, "config/defaults/skillmapignore")
   ];
   for (const candidate of candidates) {
-    if (existsSync5(candidate)) {
+    if (existsSync7(candidate)) {
       try {
-        return readFileSync5(candidate, "utf8");
+        return readFileSync7(candidate, "utf8");
       } catch {
       }
     }
@@ -892,7 +923,7 @@ async function* walkRoot(root, current, filter, extensions) {
   }
   for (const entry of entries) {
     const name = entry.name;
-    const full = join3(current, name);
+    const full = join5(current, name);
     const rel = relative3(root, full).split(sep2).join("/");
     if (filter.ignores(rel)) continue;
     if (entry.isSymbolicLink()) continue;
@@ -1095,7 +1126,7 @@ async function runScanInternal(_kernel, options) {
   for (const analyzer of exts.analyzers ?? []) {
     if (analyzer.viewContributions === void 0) continue;
     for (const node of walked.nodes) {
-      walked.freshlyRunTuples.add(`${analyzer.pluginId}/${analyzer.id}/${node.path}`);
+      walked.freshlyRunTuples.add(`${analyzer.pluginId}\0${analyzer.id}\0${node.path}`);
     }
   }
   for (const issue of walked.frontmatterIssues) issues.push(issue);
@@ -1141,7 +1172,7 @@ function validateRoots(roots) {
     throw new Error(ORCHESTRATOR_TEXTS.runScanRootEmptyArray);
   }
   for (const root of roots) {
-    if (!existsSync6(root) || !statSync2(root).isDirectory()) {
+    if (!existsSync8(root) || !statSync2(root).isDirectory()) {
       throw new Error(tx(ORCHESTRATOR_TEXTS.runScanRootMissing, { root }));
     }
   }
@@ -1311,8 +1342,10 @@ function computeCacheDecision(opts) {
     const priorRunsForNode = opts.priorExtractorRuns.get(opts.nodePath) ?? /* @__PURE__ */ new Map();
     for (const ex of applicableExtractors) {
       const qualified = qualifiedExtensionId(ex.pluginId, ex.id);
-      const priorBody = priorRunsForNode.get(qualified);
-      if (opts.nodeHashCacheEligible && priorBody === opts.bodyHash) {
+      const prior = priorRunsForNode.get(qualified);
+      const bodyMatch = prior !== void 0 && prior.bodyHash === opts.bodyHash;
+      const sidecarOk = prior !== void 0 && prior.sidecarAnnotationsHash === opts.sidecarAnnotationsHash;
+      if (opts.nodeHashCacheEligible && bodyMatch && sidecarOk) {
         cachedQualifiedIds.add(qualified);
       } else {
         missingExtractors.push(ex);
@@ -1357,7 +1390,8 @@ function reusePriorNode(opts) {
       nodePath: opts.priorNode.path,
       extractorId: qualified,
       bodyHashAtRun: opts.bodyHash,
-      ranAt
+      ranAt,
+      sidecarAnnotationsHashAtRun: opts.sidecarAnnotationsHash
     });
   }
   return { ...base, extractorRuns };
@@ -1443,11 +1477,22 @@ async function walkAndExtract(opts) {
       }
       claimedPaths.add(raw.path);
       index += 1;
+      const sidecarResolution = resolveSidecarOverlay(
+        raw.path,
+        raw.path,
+        roots,
+        bodyHash,
+        frontmatterHash
+      );
+      const sidecarAnnotationsHash = sha256(
+        canonicalSidecarAnnotations(sidecarResolution.overlay.annotations)
+      );
       const cacheDecision = computeCacheDecision({
         extractors,
         kind,
         nodePath: raw.path,
         bodyHash,
+        sidecarAnnotationsHash,
         nodeHashCacheEligible,
         priorExtractorRuns
       });
@@ -1458,10 +1503,20 @@ async function walkAndExtract(opts) {
         missingExtractors,
         fullCacheHit
       } = cacheDecision;
+      const attachSidecar = (node2) => {
+        node2.sidecar = sidecarResolution.overlay;
+        if (sidecarResolution.parsedRoot !== null) {
+          sidecarRoots.set(node2.path, sidecarResolution.parsedRoot);
+        }
+        return sidecarResolution.issues.map(
+          (i) => i.nodeIds.length > 0 ? i : { ...i, nodeIds: [node2.path] }
+        );
+      };
       if (fullCacheHit && priorNode) {
         const reused = reusePriorNode({
           priorNode,
           bodyHash,
+          sidecarAnnotationsHash,
           strict,
           cachedQualifiedIds,
           applicableQualifiedIds,
@@ -1469,14 +1524,7 @@ async function walkAndExtract(opts) {
           priorLinksByOriginating,
           priorFrontmatterIssuesByNode
         });
-        const reusedSidecarIssues = resolveAndApplySidecar(
-          reused.node,
-          raw.path,
-          roots,
-          bodyHash,
-          frontmatterHash,
-          sidecarRoots
-        );
+        const reusedSidecarIssues = attachSidecar(reused.node);
         nodes.push(reused.node);
         cachedPaths.add(reused.node.path);
         for (const link of reused.internalLinks) internalLinks.push(link);
@@ -1517,14 +1565,7 @@ async function walkAndExtract(opts) {
         nodes.push(node);
         for (const issue of fresh.frontmatterIssues) frontmatterIssues.push(issue);
       }
-      const sidecarIssues = resolveAndApplySidecar(
-        node,
-        raw.path,
-        roots,
-        bodyHash,
-        frontmatterHash,
-        sidecarRoots
-      );
+      const sidecarIssues = attachSidecar(node);
       for (const issue of sidecarIssues) frontmatterIssues.push(issue);
       emitter.emit(makeEvent("scan.progress", {
         index,
@@ -1535,7 +1576,7 @@ async function walkAndExtract(opts) {
       }));
       const extractorsToRun = partialCacheHit ? missingExtractors : applicableExtractors;
       for (const ex of extractorsToRun) {
-        freshlyRunTuples.add(`${ex.pluginId}/${ex.id}/${node.path}`);
+        freshlyRunTuples.add(`${ex.pluginId}\0${ex.id}\0${node.path}`);
       }
       const extractResult = await runExtractorsForNode({
         extractors: extractorsToRun,
@@ -1559,7 +1600,8 @@ async function walkAndExtract(opts) {
           nodePath: node.path,
           extractorId: qualified,
           bodyHashAtRun: bodyHash,
-          ranAt
+          ranAt,
+          sidecarAnnotationsHashAtRun: sidecarAnnotationsHash
         });
       }
     }
@@ -1860,30 +1902,42 @@ function canonicalFrontmatter(parsed, raw) {
     noCompatMode: true
   });
 }
-function resolveAndApplySidecar(node, relativePath, roots, liveBodyHash, liveFrontmatterHash, sidecarRoots) {
+function canonicalSidecarAnnotations(annotations) {
+  if (!annotations || typeof annotations !== "object" || Array.isArray(annotations)) {
+    return yaml4.dump({}, { sortKeys: true, lineWidth: -1, noRefs: true, noCompatMode: true });
+  }
+  return yaml4.dump(annotations, {
+    sortKeys: true,
+    lineWidth: -1,
+    noRefs: true,
+    noCompatMode: true
+  });
+}
+function resolveSidecarOverlay(relativePath, nodePathForIssue, roots, liveBodyHash, liveFrontmatterHash) {
   const issues = [];
   const mdAbs = resolveAbsoluteMdPath(relativePath, roots);
   if (mdAbs === null) {
-    node.sidecar = { present: false };
-    return issues;
+    return { overlay: { present: false }, issues, parsedRoot: null };
   }
   const result = readSidecarFor(mdAbs);
   if (!result.present) {
-    node.sidecar = { present: false };
-    return issues;
+    return { overlay: { present: false }, issues, parsedRoot: null };
   }
   if (result.parsed === null) {
-    node.sidecar = { present: true, status: null, annotations: null, root: null };
     for (const parseIssue of result.issues) {
       issues.push({
         analyzerId: "invalid-sidecar",
         severity: "warn",
-        nodeIds: [node.path],
+        nodeIds: [nodePathForIssue],
         message: parseIssue.message,
         data: { sidecarPath: relativePathFromRoots(mdAbs, roots) }
       });
     }
-    return issues;
+    return {
+      overlay: { present: true, status: null, annotations: null, root: null },
+      issues,
+      parsedRoot: null
+    };
   }
   const status = computeDriftStatus({
     storedBodyHash: result.parsed.identityBodyHash,
@@ -1891,22 +1945,30 @@ function resolveAndApplySidecar(node, relativePath, roots, liveBodyHash, liveFro
     liveBodyHash,
     liveFrontmatterHash
   });
-  node.sidecar = {
-    present: true,
-    status,
-    annotations: result.parsed.annotations,
-    root: result.parsed.raw
+  return {
+    // R15 closure (2026-05-07) — surface the full parsed root on the
+    // overlay so BFF consumers (UI inspector audit / plugin-contributions
+    // / debug panels) can read `for.*`, `audit.*`, `settings.*`, and
+    // plugin-namespaced sub-keys without re-reading the file. The
+    // `annotations` field above stays — it duplicates `root.annotations`
+    // by design so existing consumers keep working unchanged.
+    overlay: {
+      present: true,
+      status,
+      annotations: result.parsed.annotations,
+      root: result.parsed.raw
+    },
+    issues,
+    parsedRoot: result.parsed.raw
   };
-  sidecarRoots.set(node.path, result.parsed.raw);
-  return issues;
 }
 function resolveAbsoluteMdPath(relativePath, roots) {
-  if (isAbsolute2(relativePath)) {
-    return existsSync6(relativePath) ? relativePath : null;
+  if (isAbsolute3(relativePath)) {
+    return existsSync8(relativePath) ? relativePath : null;
   }
   for (const root of roots) {
     const candidate = resolvePath(root, relativePath);
-    if (existsSync6(candidate)) return candidate;
+    if (existsSync8(candidate)) return candidate;
   }
   return null;
 }
@@ -2066,10 +2128,10 @@ function assignSafe(target, source) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve6, relative as relative4, sep as sep3 } from "path";
+import { resolve as resolve8, relative as relative4, sep as sep3 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve6(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve8(opts.cwd, r));
   const ignoreFilterOpt = opts.ignoreFilter;
   const getFilter = ignoreFilterOpt === void 0 ? void 0 : typeof ignoreFilterOpt === "function" ? ignoreFilterOpt : () => ignoreFilterOpt;
   const ignored = getFilter ? (path) => {