@skill-map/cli 0.16.6 → 0.18.0

package/dist/index.js

@@ -94,15 +94,16 @@ var Registry = class {
 
 // kernel/orchestrator.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync2, statSync } from "fs";
+import { existsSync as existsSync6, statSync as statSync2 } from "fs";
+import { isAbsolute as isAbsolute2, resolve as resolvePath } from "path";
 import { Tiktoken } from "js-tiktoken/lite";
 import cl100k_base from "js-tiktoken/ranks/cl100k_base";
-import yaml from "js-yaml";
+import yaml4 from "js-yaml";
 
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.16.6",
+  version: "0.18.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -160,15 +161,15 @@ var package_default = {
     "pretest:ci": "tsup",
     "pretest:coverage": "tsup",
     "pretest:coverage:html": "tsup",
-    test: "tsc --noEmit && node --import tsx --test --test-reporter=spec 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts'",
-    "test:ci": "tsc --noEmit && node --import tsx --test 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts'",
-    "test:coverage": "tsc --noEmit && SKILL_MAP_SKIP_BENCHMARK=1 node --experimental-default-config-file --import tsx --test --experimental-test-coverage 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts'",
-    "test:coverage:html": "tsc --noEmit && SKILL_MAP_SKIP_BENCHMARK=1 c8 node --import tsx --test 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts'",
+    test: "tsc --noEmit && node --import tsx --test --test-reporter=spec 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts' 'server/**/*.test.ts'",
+    "test:ci": "tsc --noEmit && node --import tsx --test 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts' 'server/**/*.test.ts'",
+    "test:coverage": "tsc --noEmit && SKILL_MAP_SKIP_BENCHMARK=1 node --experimental-default-config-file --import tsx --test --experimental-test-coverage 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts' 'server/**/*.test.ts'",
+    "test:coverage:html": "tsc --noEmit && SKILL_MAP_SKIP_BENCHMARK=1 c8 node --import tsx --test 'test/**/*.test.ts' 'built-in-plugins/**/*.test.ts' 'kernel/**/*.test.ts' 'server/**/*.test.ts'",
     clean: "rm -rf dist coverage"
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.16.0",
+    "@skill-map/spec": "0.18.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -205,6 +206,174 @@ var package_default = {
   }
 };
 
+// kernel/sidecar/parse.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { createRequire } from "module";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import yaml from "js-yaml";
+
+// kernel/util/ajv-interop.ts
+import addFormatsModule from "ajv-formats";
+var addFormats = addFormatsModule.default ?? addFormatsModule;
+function applyAjvFormats(ajv) {
+  addFormats(ajv);
+}
+
+// kernel/sidecar/parse.ts
+function readSidecarFor(mdAbsolutePath) {
+  const sidecarPath = sidecarPathFor(mdAbsolutePath);
+  if (!existsSync(sidecarPath)) {
+    return { parsed: null, present: false, issues: [] };
+  }
+  let raw;
+  try {
+    raw = readFileSync(sidecarPath, "utf8");
+  } catch (err) {
+    return {
+      parsed: null,
+      present: true,
+      issues: [{ message: `cannot read ${sidecarPath}: ${err.message}` }]
+    };
+  }
+  let parsedYaml;
+  try {
+    parsedYaml = yaml.load(raw);
+  } catch (err) {
+    return {
+      parsed: null,
+      present: true,
+      issues: [{ message: `malformed YAML in ${sidecarPath}: ${err.message}` }]
+    };
+  }
+  if (!isPlainObject(parsedYaml)) {
+    return {
+      parsed: null,
+      present: true,
+      issues: [{ message: `sidecar root must be a YAML mapping at ${sidecarPath}` }]
+    };
+  }
+  const sidecarValidator = getSidecarValidator();
+  if (!sidecarValidator(parsedYaml)) {
+    const errors = (sidecarValidator.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? e.keyword}`).join("; ");
+    return {
+      parsed: null,
+      present: true,
+      issues: [{ message: `sidecar schema validation failed at ${sidecarPath}: ${errors}` }]
+    };
+  }
+  const root = parsedYaml;
+  const forBlock = root["for"];
+  const annotationsRaw = root["annotations"];
+  const annotations = isPlainObject(annotationsRaw) ? Object.keys(annotationsRaw).length === 0 ? null : annotationsRaw : null;
+  return {
+    parsed: {
+      filePath: sidecarPath,
+      forBodyHash: String(forBlock["bodyHash"]),
+      forFrontmatterHash: String(forBlock["frontmatterHash"]),
+      forPath: String(forBlock["path"]),
+      annotations,
+      raw: root
+    },
+    present: true,
+    issues: []
+  };
+}
+function sidecarPathFor(mdAbsolutePath) {
+  if (mdAbsolutePath.endsWith(".md")) {
+    return `${mdAbsolutePath.slice(0, -".md".length)}.sm`;
+  }
+  return `${mdAbsolutePath}.sm`;
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+var cachedSidecarValidator = null;
+function getSidecarValidator() {
+  if (cachedSidecarValidator) return cachedSidecarValidator;
+  const ajv = new Ajv2020({ strict: false, allErrors: true, allowUnionTypes: true });
+  applyAjvFormats(ajv);
+  const specRoot = resolveSpecRoot();
+  const annotationsSchema = JSON.parse(
+    readFileSync(resolve(specRoot, "schemas/annotations.schema.json"), "utf8")
+  );
+  const sidecarSchema = JSON.parse(
+    readFileSync(resolve(specRoot, "schemas/sidecar.schema.json"), "utf8")
+  );
+  ajv.addSchema(annotationsSchema);
+  cachedSidecarValidator = ajv.compile(sidecarSchema);
+  return cachedSidecarValidator;
+}
+function resolveSpecRoot() {
+  const require2 = createRequire(import.meta.url);
+  try {
+    const indexPath = require2.resolve("@skill-map/spec/index.json");
+    return dirname(indexPath);
+  } catch {
+    throw new Error(
+      "@skill-map/spec not resolvable \u2014 sidecar reader cannot load schemas."
+    );
+  }
+}
+
+// kernel/sidecar/drift.ts
+function computeDriftStatus(args) {
+  const bodyDrift = args.storedBodyHash !== args.liveBodyHash;
+  const fmDrift = args.storedFrontmatterHash !== args.liveFrontmatterHash;
+  if (bodyDrift && fmDrift) return "stale-both";
+  if (bodyDrift) return "stale-body";
+  if (fmDrift) return "stale-frontmatter";
+  return "fresh";
+}
+
+// kernel/sidecar/discover-orphans.ts
+import { existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+function discoverOrphanSidecars(roots, shouldSkip) {
+  const out = [];
+  for (const root of roots) {
+    walk(root, root, shouldSkip ?? (() => false), out);
+  }
+  return out;
+}
+function walk(root, current, shouldSkip, out) {
+  let entries;
+  try {
+    entries = readdirSync(current, { withFileTypes: true, encoding: "utf8" });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(current, entry.name);
+    const rel = relative(root, full).split(sep).join("/");
+    if (shouldSkip(rel)) continue;
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      walk(root, full, shouldSkip, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith(".sm")) continue;
+    const expectedMd = `${full.slice(0, -".sm".length)}.md`;
+    if (existsSync2(expectedMd) && safeIsFile(expectedMd)) continue;
+    out.push({ sidecarPath: full, relativePath: rel, expectedMdPath: expectedMd });
+  }
+}
+function safeIsFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// 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();
@@ -253,20 +422,13 @@ function getActiveLogger() {
 }
 
 // kernel/adapters/plugin-loader.ts
-import { createRequire } from "module";
-import { existsSync, readFileSync, readdirSync } from "fs";
-import { isAbsolute, join, relative, resolve } 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 } from "ajv/dist/2020.js";
+import { Ajv2020 as Ajv20203 } from "ajv/dist/2020.js";
 import semver from "semver";
 
-// kernel/util/ajv-interop.ts
-import addFormatsModule from "ajv-formats";
-var addFormats = addFormatsModule.default ?? addFormatsModule;
-function applyAjvFormats(ajv) {
-  addFormats(ajv);
-}
-
 // 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}}",
@@ -361,29 +523,30 @@ var KNOWN_KINDS = /* @__PURE__ */ new Set(["provider", "extractor", "rule", "act
 var KNOWN_KINDS_LIST = [...KNOWN_KINDS].join(" / ");
 var HOOKABLE_TRIGGERS_LIST = HOOK_TRIGGERS.join(", ");
 function installedSpecVersion() {
-  const require2 = createRequire(import.meta.url);
+  const require2 = createRequire3(import.meta.url);
   const indexPath = require2.resolve("@skill-map/spec/index.json");
-  const pkgPath = resolve(indexPath, "..", "package.json");
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const pkgPath = resolve3(indexPath, "..", "package.json");
+  const pkg = JSON.parse(readFileSync3(pkgPath, "utf8"));
   return pkg.version;
 }
 
 // kernel/adapters/schema-validators.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { dirname, resolve as resolve2 } from "path";
-import { createRequire as createRequire2 } from "module";
-import { Ajv2020 as Ajv20202 } from "ajv/dist/2020.js";
+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";
 function buildProviderFrontmatterValidator(providers) {
-  const specRoot = resolveSpecRoot();
-  const ajv = new Ajv20202({
+  const specRoot = resolveSpecRoot2();
+  const ajv = new Ajv20204({
     strict: false,
     allErrors: true,
     allowUnionTypes: true
   });
   applyAjvFormats(ajv);
-  const baseFile = resolve2(specRoot, "schemas/frontmatter/base.schema.json");
-  const baseSchema = JSON.parse(readFileSync2(baseFile, "utf8"));
+  const baseFile = resolve4(specRoot, "schemas/frontmatter/base.schema.json");
+  const baseSchema = JSON.parse(readFileSync4(baseFile, "utf8"));
   ajv.addSchema(baseSchema);
+  registerProviderAuxiliarySchemas(ajv, providers);
   const compiled = /* @__PURE__ */ new Map();
   for (const provider of providers) {
     for (const [kind, entry] of Object.entries(provider.kinds)) {
@@ -408,11 +571,21 @@ function formatError(err) {
   const path = err.instancePath || "(root)";
   return `${path} ${err.message ?? err.keyword}`;
 }
-function resolveSpecRoot() {
-  const require2 = createRequire2(import.meta.url);
+function registerProviderAuxiliarySchemas(ajv, providers) {
+  for (const provider of providers) {
+    if (!provider.schemas) continue;
+    for (const aux of provider.schemas) {
+      const auxJson = aux;
+      if (typeof auxJson.$id === "string" && ajv.getSchema(auxJson.$id)) continue;
+      ajv.addSchema(aux);
+    }
+  }
+}
+function resolveSpecRoot2() {
+  const require2 = createRequire4(import.meta.url);
   try {
     const indexPath = require2.resolve("@skill-map/spec/index.json");
-    return dirname(indexPath);
+    return dirname3(indexPath);
   } catch {
     throw new Error(
       "@skill-map/spec not resolvable \u2014 ensure the workspace is linked or the package is installed."
@@ -432,6 +605,195 @@ 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";
+
+// kernel/scan/ignore.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname4, resolve as resolve5 } from "path";
+import { fileURLToPath } from "url";
+import ignoreFactory from "ignore";
+function buildIgnoreFilter(opts = {}) {
+  const ig = ignoreFactory();
+  if (opts.includeDefaults !== false) {
+    ig.add(loadDefaultsText());
+  }
+  if (opts.configIgnore && opts.configIgnore.length > 0) {
+    ig.add(opts.configIgnore);
+  }
+  if (opts.ignoreFileText && opts.ignoreFileText.length > 0) {
+    ig.add(opts.ignoreFileText);
+  }
+  return {
+    ignores(relativePath) {
+      if (relativePath === "" || relativePath === "." || relativePath === "./") {
+        return false;
+      }
+      const normalised = relativePath.replace(/^\.\//, "").replace(/\\/g, "/").replace(/^\//, "");
+      if (normalised === "") return false;
+      return ig.ignores(normalised);
+    }
+  };
+}
+var cachedDefaults = null;
+function loadDefaultsText() {
+  if (cachedDefaults !== null) return cachedDefaults;
+  cachedDefaults = readDefaultsFromDisk();
+  return cachedDefaults;
+}
+function readDefaultsFromDisk() {
+  const here = dirname4(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve5(here, "../../config/defaults/skillmapignore"),
+    // src/kernel/scan/ → src/config/defaults/
+    resolve5(here, "../config/defaults/skillmapignore"),
+    // dist/cli.js → dist/config/defaults/ (siblings)
+    resolve5(here, "config/defaults/skillmapignore")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync5(candidate)) {
+      try {
+        return readFileSync5(candidate, "utf8");
+      } catch {
+      }
+    }
+  }
+  return "";
+}
+
+// kernel/scan/parsers/frontmatter-yaml.ts
+import yaml3 from "js-yaml";
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+var FORBIDDEN_FRONTMATTER_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var frontmatterYamlParser = {
+  id: "frontmatter-yaml",
+  parse(raw, _path) {
+    const match = FRONTMATTER_RE.exec(raw);
+    if (!match) return { frontmatterRaw: "", frontmatter: {}, body: raw };
+    const frontmatterRaw = match[1];
+    const body = match[2];
+    const parsed = {};
+    try {
+      const doc = yaml3.load(frontmatterRaw, { schema: yaml3.JSON_SCHEMA });
+      if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+        for (const [k, v] of Object.entries(doc)) {
+          if (FORBIDDEN_FRONTMATTER_KEYS.has(k)) continue;
+          parsed[k] = v;
+        }
+      }
+    } catch {
+    }
+    return { frontmatterRaw, frontmatter: parsed, body };
+  }
+};
+
+// kernel/scan/parsers/plain.ts
+var plainParser = {
+  id: "plain",
+  parse(raw, _path) {
+    return { frontmatter: {}, frontmatterRaw: "", body: raw };
+  }
+};
+
+// kernel/scan/parsers/index.ts
+var REGISTRY = /* @__PURE__ */ new Map([
+  [frontmatterYamlParser.id, frontmatterYamlParser],
+  [plainParser.id, plainParser]
+]);
+var FROZEN_IDS = new Set(REGISTRY.keys());
+function getParser(id) {
+  return REGISTRY.get(id);
+}
+
+// kernel/scan/walk-content.ts
+var UnknownParserError = class extends Error {
+  constructor(parserId) {
+    super(`Unknown parser id '${parserId}'. Built-in parsers: 'frontmatter-yaml', 'plain'.`);
+    this.name = "UnknownParserError";
+  }
+};
+async function* walkContent(roots, options) {
+  const parser = getParser(options.parser);
+  if (!parser) throw new UnknownParserError(options.parser);
+  const filter = options.ignoreFilter ?? buildIgnoreFilter();
+  const extensions = options.extensions;
+  for (const root of roots) {
+    for await (const file of walkRoot(root, root, filter, extensions)) {
+      const relPath = relative3(root, file).split(sep2).join("/");
+      let raw;
+      try {
+        raw = await readFile(file, "utf8");
+      } catch {
+        continue;
+      }
+      const parsed = parser.parse(raw, relPath);
+      yield {
+        path: relPath,
+        body: parsed.body,
+        frontmatterRaw: parsed.frontmatterRaw,
+        frontmatter: parsed.frontmatter
+      };
+    }
+  }
+}
+async function* walkRoot(root, current, filter, extensions) {
+  let entries;
+  try {
+    entries = await readdir(current, { withFileTypes: true, encoding: "utf8" });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    const full = join3(current, name);
+    const rel = relative3(root, full).split(sep2).join("/");
+    if (filter.ignores(rel)) continue;
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      yield* walkRoot(root, full, filter, extensions);
+    } else if (entry.isFile() && hasMatchingExtension(name, extensions)) {
+      try {
+        const s = await stat(full);
+        if (s.isFile()) yield full;
+      } catch {
+      }
+    }
+  }
+}
+function hasMatchingExtension(name, extensions) {
+  for (const ext of extensions) {
+    if (name.endsWith(ext)) return true;
+  }
+  return false;
+}
+
+// kernel/extensions/provider.ts
+var DEFAULT_READ_CONFIG = Object.freeze({
+  extensions: Object.freeze([".md"]),
+  parser: "frontmatter-yaml"
+});
+function resolveProviderWalk(provider) {
+  if (provider.walk) {
+    const walk2 = provider.walk.bind(provider);
+    return walk2;
+  }
+  const read = provider.read ?? DEFAULT_READ_CONFIG;
+  return (roots, options) => {
+    const walkOptions = {
+      extensions: read.extensions,
+      parser: read.parser
+    };
+    if (options?.ignoreFilter) walkOptions.ignoreFilter = options.ignoreFilter;
+    return walkContent(roots, walkOptions);
+  };
+}
+
 // kernel/orchestrator.ts
 var SCANNED_BY = {
   name: "skill-map",
@@ -494,14 +856,23 @@ async function runScanInternal(_kernel, options) {
     emitter.emit(evt);
     await hookDispatcher.dispatch("extractor.completed", evt);
   }
-  const issues = await runRules(exts.rules, walked.nodes, walked.internalLinks, emitter, hookDispatcher);
+  const issues = await runRules(
+    exts.rules,
+    walked.nodes,
+    walked.internalLinks,
+    walked.orphanSidecars,
+    walked.sidecarRoots,
+    options.annotationContributions ?? [],
+    emitter,
+    hookDispatcher
+  );
   for (const issue of walked.frontmatterIssues) issues.push(issue);
   const renameOps = prior ? detectRenamesAndOrphans(prior, walked.nodes, issues) : [];
   const stats = {
     // `filesSkipped` is "files walked but not classified by any Provider".
     // Today every walked file IS classified by its Provider (the `claude`
     // Provider's `classify()` always returns a kind, falling back to
-    // `'note'`), so this is always 0. Wired now so the field shape is
+    // `'markdown'`), so this is always 0. Wired now so the field shape is
     // spec-conformant; meaningful once multiple Providers compete.
     filesWalked: walked.filesWalked,
     filesSkipped: 0,
@@ -536,7 +907,7 @@ function validateRoots(roots) {
     throw new Error(ORCHESTRATOR_TEXTS.runScanRootEmptyArray);
   }
   for (const root of roots) {
-    if (!existsSync2(root) || !statSync(root).isDirectory()) {
+    if (!existsSync6(root) || !statSync2(root).isDirectory()) {
       throw new Error(tx(ORCHESTRATOR_TEXTS.runScanRootMissing, { root }));
     }
   }
@@ -740,6 +1111,7 @@ async function walkAndExtract(opts) {
   const frontmatterIssues = [];
   const enrichmentBuffer = /* @__PURE__ */ new Map();
   const extractorRuns = [];
+  const sidecarRoots = /* @__PURE__ */ new Map();
   let filesWalked = 0;
   let index = 0;
   const walkOptions = ignoreFilter ? { ignoreFilter } : {};
@@ -751,13 +1123,16 @@ async function walkAndExtract(opts) {
     else shortIdToQualified.set(ex.id, [qualified]);
   }
   for (const provider of providers) {
-    for await (const raw of provider.walk(roots, walkOptions)) {
+    for await (const raw of resolveProviderWalk(provider)(roots, walkOptions)) {
       filesWalked += 1;
       const bodyHash = sha256(raw.body);
       const frontmatterHash = sha256(canonicalFrontmatter(raw.frontmatter, raw.frontmatterRaw));
       const priorNode = priorNodesByPath.get(raw.path);
       const nodeHashCacheEligible = enableCache && prior !== null && priorNode !== void 0 && priorNode.bodyHash === bodyHash && priorNode.frontmatterHash === frontmatterHash;
       const kind = provider.classify(raw.path, raw.frontmatter);
+      if (kind === null) {
+        continue;
+      }
       index += 1;
       const cacheDecision = computeCacheDecision({
         extractors,
@@ -785,10 +1160,21 @@ async function walkAndExtract(opts) {
           priorLinksByOriginating,
           priorFrontmatterIssuesByNode
         });
+        reused.node.stability = null;
+        reused.node.version = null;
+        const reusedSidecarIssues = resolveAndApplySidecar(
+          reused.node,
+          raw.path,
+          roots,
+          bodyHash,
+          frontmatterHash,
+          sidecarRoots
+        );
         nodes.push(reused.node);
         cachedPaths.add(reused.node.path);
         for (const link of reused.internalLinks) internalLinks.push(link);
         for (const issue of reused.frontmatterIssues) frontmatterIssues.push(issue);
+        for (const issue of reusedSidecarIssues) frontmatterIssues.push(issue);
         for (const run of reused.extractorRuns) extractorRuns.push(run);
         emitter.emit(makeEvent("scan.progress", { index, path: raw.path, kind, cached: true }));
         continue;
@@ -824,6 +1210,15 @@ 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
+      );
+      for (const issue of sidecarIssues) frontmatterIssues.push(issue);
       emitter.emit(makeEvent("scan.progress", {
         index,
         path: raw.path,
@@ -858,6 +1253,7 @@ async function walkAndExtract(opts) {
       }
     }
   }
+  const orphanSidecars = discoverOrphanSidecars(roots);
   return {
     nodes,
     internalLinks,
@@ -866,7 +1262,9 @@ async function walkAndExtract(opts) {
     frontmatterIssues,
     filesWalked,
     enrichments: [...enrichmentBuffer.values()],
-    extractorRuns
+    extractorRuns,
+    orphanSidecars,
+    sidecarRoots
   };
 }
 function reuseCachedLink(link, shortIdToQualified, cachedQualifiedIds, applicableQualifiedIds) {
@@ -895,10 +1293,20 @@ function reuseCachedLink(link, shortIdToQualified, cachedQualifiedIds, applicabl
   if (obsoleteSources.length === 0) return link;
   return { ...link, sources: cachedSources };
 }
-async function runRules(rules, nodes, internalLinks, emitter, hookDispatcher) {
+async function runRules(rules, nodes, internalLinks, orphanSidecars, sidecarRoots, annotationContributions, emitter, hookDispatcher) {
   const issues = [];
+  const ruleOrphans = orphanSidecars.map((o) => ({
+    relativePath: o.relativePath,
+    expectedMdPath: o.expectedMdPath
+  }));
   for (const rule of rules) {
-    const emitted = await rule.evaluate({ nodes, links: internalLinks });
+    const emitted = await rule.evaluate({
+      nodes,
+      links: internalLinks,
+      orphanSidecars: ruleOrphans,
+      sidecarRoots,
+      annotationContributions
+    });
     for (const issue of emitted) {
       const validated = validateIssue(rule, issue, emitter);
       if (validated) issues.push(validated);
@@ -1079,7 +1487,7 @@ function makeHookDispatcher(hooks, emitter) {
           await hook.on(ctx);
         } catch (err) {
           const qualifiedId = qualifiedExtensionId(hook.pluginId, hook.id);
-          const message = err instanceof Error ? err.message : String(err);
+          const message = formatErrorMessage(err);
           emitter.emit(
             makeEvent("extension.error", {
               kind: "hook-error",
@@ -1124,7 +1532,6 @@ function buildHookContext(_hook, trigger, event) {
 function buildNode(args) {
   const bytesFrontmatter = Buffer.byteLength(args.frontmatterRaw, "utf8");
   const bytesBody = Buffer.byteLength(args.body, "utf8");
-  const metadata = pickMetadata(args.frontmatter);
   const node = {
     path: args.path,
     kind: args.kind,
@@ -1142,9 +1549,8 @@ function buildNode(args) {
     frontmatter: args.frontmatter,
     title: pickString(args.frontmatter["name"]),
     description: pickString(args.frontmatter["description"]),
-    stability: pickStability(metadata?.["stability"]),
-    version: pickString(metadata?.["version"]),
-    author: pickString(args.frontmatter["author"])
+    stability: null,
+    version: null
   };
   if (args.encoder) {
     node.tokens = countTokens(args.encoder, args.frontmatterRaw, args.body);
@@ -1165,24 +1571,88 @@ function canonicalFrontmatter(parsed, raw) {
   if (!hasParsedKeys && hasRawText) {
     return raw;
   }
-  return yaml.dump(parsed, {
+  return yaml4.dump(parsed, {
     sortKeys: true,
     lineWidth: -1,
     noRefs: true,
     noCompatMode: true
   });
 }
-function pickMetadata(fm) {
-  const m = fm["metadata"];
-  return m && typeof m === "object" && !Array.isArray(m) ? m : null;
+function resolveAndApplySidecar(node, relativePath, roots, liveBodyHash, liveFrontmatterHash, sidecarRoots) {
+  const issues = [];
+  const mdAbs = resolveAbsoluteMdPath(relativePath, roots);
+  if (mdAbs === null) {
+    node.sidecar = { present: false };
+    return issues;
+  }
+  const result = readSidecarFor(mdAbs);
+  if (!result.present) {
+    node.sidecar = { present: false };
+    return issues;
+  }
+  if (result.parsed === null) {
+    node.sidecar = { present: true, status: null, annotations: null, root: null };
+    for (const parseIssue of result.issues) {
+      issues.push({
+        ruleId: "invalid-sidecar",
+        severity: "warn",
+        nodeIds: [node.path],
+        message: parseIssue.message,
+        data: { sidecarPath: relativePathFromRoots(mdAbs, roots) }
+      });
+    }
+    return issues;
+  }
+  const status = computeDriftStatus({
+    storedBodyHash: result.parsed.forBodyHash,
+    storedFrontmatterHash: result.parsed.forFrontmatterHash,
+    liveBodyHash,
+    liveFrontmatterHash
+  });
+  applyAnnotationsOverlay(node, result.parsed);
+  node.sidecar = {
+    present: true,
+    status,
+    annotations: result.parsed.annotations,
+    root: result.parsed.raw
+  };
+  sidecarRoots.set(node.path, result.parsed.raw);
+  return issues;
+}
+function applyAnnotationsOverlay(node, parsed) {
+  const annotations = parsed.annotations;
+  if (annotations === null) return;
+  const stability = annotations["stability"];
+  if (stability === "experimental" || stability === "stable" || stability === "deprecated") {
+    node.stability = stability;
+  }
+  const version = annotations["version"];
+  if (typeof version === "number" && Number.isInteger(version) && version >= 1) {
+    node.version = version;
+  }
+}
+function resolveAbsoluteMdPath(relativePath, roots) {
+  if (isAbsolute2(relativePath)) {
+    return existsSync6(relativePath) ? relativePath : null;
+  }
+  for (const root of roots) {
+    const candidate = resolvePath(root, relativePath);
+    if (existsSync6(candidate)) return candidate;
+  }
+  return null;
+}
+function relativePathFromRoots(absolutePath, roots) {
+  for (const root of roots) {
+    const abs = resolvePath(root);
+    if (absolutePath.startsWith(`${abs}/`) || absolutePath.startsWith(`${abs}\\`)) {
+      return absolutePath.slice(abs.length + 1).split(/[\\/]/).join("/");
+    }
+  }
+  return absolutePath;
 }
 function pickString(value) {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
-function pickStability(value) {
-  if (value === "experimental" || value === "stable" || value === "deprecated") return value;
-  return null;
-}
 function buildExtractorContext(extractor, node, body, frontmatter, emitLink, enrichNode, store) {
   const scope = extractor.scope;
   return {
@@ -1329,16 +1799,16 @@ function assignSafe(target, source) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve3, relative as relative2, sep } from "path";
+import { resolve as resolve6, relative as relative4, sep as sep3 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve3(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve6(opts.cwd, r));
   const ignoreFilterOpt = opts.ignoreFilter;
   const getFilter = ignoreFilterOpt === void 0 ? void 0 : typeof ignoreFilterOpt === "function" ? ignoreFilterOpt : () => ignoreFilterOpt;
   const ignored = getFilter ? (path) => {
     const filter = getFilter();
     if (!filter) return false;
-    const rel = relativePathFromRoots(path, absRoots);
+    const rel = relativePathFromRoots2(path, absRoots);
     if (rel === null) return false;
     return filter.ignores(rel);
   } : void 0;
@@ -1422,12 +1892,12 @@ function createChokidarWatcher(opts) {
   };
   return { ready, close };
 }
-function relativePathFromRoots(absolute, absRoots) {
+function relativePathFromRoots2(absolute, absRoots) {
   for (const root of absRoots) {
-    const rel = relative2(root, absolute);
+    const rel = relative4(root, absolute);
     if (rel === "" || rel === ".") return "";
-    if (!rel.startsWith("..") && !rel.startsWith(`..${sep}`)) {
-      return rel.split(sep).join("/");
+    if (!rel.startsWith("..") && !rel.startsWith(`..${sep3}`)) {
+      return rel.split(sep3).join("/");
     }
   }
   return null;
@@ -1678,7 +2148,16 @@ function parseLogLevel(value) {
 
 // kernel/index.ts
 function createKernel() {
-  return { registry: new Registry() };
+  let annotationKeys = Object.freeze([]);
+  return {
+    registry: new Registry(),
+    getRegisteredAnnotationKeys() {
+      return annotationKeys;
+    },
+    setRegisteredAnnotationKeys(entries) {
+      annotationKeys = Object.freeze([...entries]);
+    }
+  };
 }
 export {
   DuplicateExtensionError,