@skill-map/cli 0.17.0 → 0.19.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.17.0",
+  version: "0.19.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.17.0",
+    "@skill-map/spec": "0.19.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 identityBlock = root["identity"];
+  const annotationsRaw = root["annotations"];
+  const annotations = isPlainObject(annotationsRaw) ? Object.keys(annotationsRaw).length === 0 ? null : annotationsRaw : null;
+  return {
+    parsed: {
+      filePath: sidecarPath,
+      identityBodyHash: String(identityBlock["bodyHash"]),
+      identityFrontmatterHash: String(identityBlock["frontmatterHash"]),
+      identityPath: String(identityBlock["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,28 +523,140 @@ 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";
+var SCHEMA_FILES = {
+  node: "schemas/node.schema.json",
+  link: "schemas/link.schema.json",
+  issue: "schemas/issue.schema.json",
+  "scan-result": "schemas/scan-result.schema.json",
+  "execution-record": "schemas/execution-record.schema.json",
+  "project-config": "schemas/project-config.schema.json",
+  "plugins-registry": "schemas/plugins-registry.schema.json",
+  job: "schemas/job.schema.json",
+  "report-base": "schemas/report-base.schema.json",
+  "conformance-case": "schemas/conformance-case.schema.json",
+  "history-stats": "schemas/history-stats.schema.json",
+  "extension-provider": "schemas/extensions/provider.schema.json",
+  "extension-extractor": "schemas/extensions/extractor.schema.json",
+  "extension-rule": "schemas/extensions/rule.schema.json",
+  "extension-action": "schemas/extensions/action.schema.json",
+  "extension-formatter": "schemas/extensions/formatter.schema.json",
+  "extension-hook": "schemas/extensions/hook.schema.json",
+  "frontmatter-base": "schemas/frontmatter/base.schema.json"
+};
+var SUPPORTING_SCHEMAS = [
+  "schemas/extensions/base.schema.json",
+  "schemas/frontmatter/base.schema.json",
+  "schemas/summaries/security-scanner.schema.json",
+  "schemas/view-contracts.schema.json",
+  "schemas/input-types.schema.json"
+];
+var cachedValidators = null;
+function loadSchemaValidators() {
+  if (cachedValidators !== null) return cachedValidators;
+  cachedValidators = buildSchemaValidators();
+  return cachedValidators;
+}
+function buildSchemaValidators() {
+  const specRoot = resolveSpecRoot2();
+  const ajv = new Ajv20204({
+    strict: false,
+    allErrors: true,
+    allowUnionTypes: true
+  });
+  applyAjvFormats(ajv);
+  for (const rel of SUPPORTING_SCHEMAS) {
+    const file = resolve4(specRoot, rel);
+    if (!existsSyncSafe(file)) continue;
+    const schema = JSON.parse(readFileSync4(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 byId = typeof schema.$id === "string" ? ajv.getSchema(schema.$id) : void 0;
+    validators.set(name, byId ?? ajv.compile(schema));
+  }
+  const extensionByKind = {
+    provider: "extension-provider",
+    extractor: "extension-extractor",
+    rule: "extension-rule",
+    action: "extension-action",
+    formatter: "extension-formatter",
+    hook: "extension-hook"
+  };
+  const pluginManifestValidator = ajv.compile({
+    $ref: "https://skill-map.dev/spec/v0/plugins-registry.schema.json#/$defs/PluginManifest"
+  });
+  const contributionValidators = /* @__PURE__ */ new Map();
+  const VIEW_CONTRACTS_ID = "https://skill-map.dev/spec/v0/view-contracts.schema.json";
+  function getContributionValidator(contract) {
+    const existing = contributionValidators.get(contract);
+    if (existing) return existing;
+    const ref = `${VIEW_CONTRACTS_ID}#/$defs/payloads/${contract}`;
+    let compiled;
+    try {
+      compiled = ajv.compile({ $ref: ref });
+    } catch {
+      return null;
+    }
+    contributionValidators.set(contract, compiled);
+    return compiled;
+  }
+  return {
+    getValidator(name) {
+      const v = validators.get(name);
+      if (!v) throw new Error(`Unknown schema: ${name}`);
+      return v;
+    },
+    validatorForExtension(kind) {
+      return validators.get(extensionByKind[kind]);
+    },
+    validate(name, data) {
+      const v = validators.get(name);
+      if (!v) throw new Error(`Unknown schema: ${name}`);
+      if (v(data)) return { ok: true, data };
+      const errors = (v.errors ?? []).map(formatError).join("; ");
+      return { ok: false, errors };
+    },
+    validatePluginManifest(data) {
+      if (pluginManifestValidator(data)) return { ok: true, data };
+      const errors = (pluginManifestValidator.errors ?? []).map(formatError).join("; ");
+      return { ok: false, errors };
+    },
+    validateContributionPayload(contract, payload) {
+      const validator = getContributionValidator(contract);
+      if (!validator) {
+        return { ok: false, errors: "unknown-contract" };
+      }
+      if (validator(payload)) return { ok: true };
+      const errors = (validator.errors ?? []).map(formatError).join("; ");
+      return { ok: false, errors };
+    }
+  };
+}
 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();
@@ -419,17 +693,25 @@ function registerProviderAuxiliarySchemas(ajv, providers) {
     }
   }
 }
-function resolveSpecRoot() {
-  const require2 = createRequire2(import.meta.url);
+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."
     );
   }
 }
+function existsSyncSafe(path) {
+  try {
+    readFileSync4(path, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // kernel/i18n/orchestrator.texts.ts
 var ORCHESTRATOR_TEXTS = {
@@ -439,10 +721,201 @@ var ORCHESTRATOR_TEXTS = {
   frontmatterMalformedMissingClose: "Frontmatter in {{path}} opens with `---` but never closes \u2014 no matching `---` line at column 0 was found. The file was scanned as body-only and every metadata field was silently lost. Add a closing `---` line below the metadata block.",
   extensionErrorLinkKindNotDeclared: 'Extractor "{{extractorId}}" emitted a link of kind "{{linkKind}}" outside its declared `emitsLinkKinds` set [{{declaredKinds}}]. Link dropped.',
   extensionErrorIssueInvalidSeverity: `Rule "{{ruleId}}" emitted an issue with invalid severity {{severity}} (allowed: 'error' | 'warn' | 'info'). Issue dropped.`,
+  extensionErrorContributionUnknownId: 'Extractor "{{extractorId}}" emitted contribution "{{contributionId}}" on {{nodePath}} but did not declare it in its `viewContributions` map. Contribution dropped.',
+  extensionErrorContributionPayloadInvalid: 'Extractor "{{extractorId}}" emitted contribution "{{contributionId}}" on {{nodePath}}; payload failed the "{{contract}}" schema: {{errors}}. Contribution dropped.',
   runScanRootEmptyArray: "runScan: roots must contain at least one path (spec requires minItems: 1)",
   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",
@@ -505,14 +978,26 @@ 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 ruleResult = await runRules(
+    exts.rules,
+    walked.nodes,
+    walked.internalLinks,
+    walked.orphanSidecars,
+    walked.sidecarRoots,
+    options.annotationContributions ?? [],
+    options.viewContributions ?? [],
+    emitter,
+    hookDispatcher
+  );
+  const issues = ruleResult.issues;
+  for (const c of ruleResult.contributions) walked.contributions.push(c);
   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,
@@ -539,7 +1024,8 @@ async function runScanInternal(_kernel, options) {
     },
     renameOps,
     extractorRuns: walked.extractorRuns,
-    enrichments: walked.enrichments
+    enrichments: walked.enrichments,
+    contributions: walked.contributions
   };
 }
 function validateRoots(roots) {
@@ -547,7 +1033,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 }));
     }
   }
@@ -584,9 +1070,10 @@ async function runExtractorsForNode(opts) {
   const internalLinks = [];
   const externalLinks = [];
   const enrichmentBuffer = /* @__PURE__ */ new Map();
+  const contributions = [];
+  const validators = loadSchemaValidators();
   for (const extractor of opts.extractors) {
     const qualifiedId = qualifiedExtensionId(extractor.pluginId, extractor.id);
-    const isProb = extractor.mode === "probabilistic";
     const emitLink = (link) => {
       const validated = validateLink(extractor, link, opts.emitter);
       if (!validated) return;
@@ -606,9 +1093,54 @@ async function runExtractorsForNode(opts) {
           bodyHashAtEnrichment: opts.bodyHash,
           value: { ...partial },
           enrichedAt: Date.now(),
-          isProbabilistic: isProb
+          // Extractors are deterministic-only; `is_probabilistic` is
+          // reserved on the row for future Action-issued enrichments.
+          isProbabilistic: false
+        });
+      }
+    };
+    const declaredContributions = readDeclaredContributions(extractor);
+    const emitContribution = (contributionId, payload) => {
+      const declared = declaredContributions.get(contributionId);
+      if (!declared) {
+        emitExtensionError(opts.emitter, qualifiedId, opts.node.path, {
+          phase: "emitContribution",
+          contributionId,
+          reason: "unknown-contribution-id",
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionUnknownId, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath: opts.node.path
+          })
+        });
+        return;
+      }
+      const result = validators.validateContributionPayload(declared.contract, payload);
+      if (!result.ok) {
+        emitExtensionError(opts.emitter, qualifiedId, opts.node.path, {
+          phase: "emitContribution",
+          contributionId,
+          contract: declared.contract,
+          reason: result.errors,
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionPayloadInvalid, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath: opts.node.path,
+            contract: declared.contract,
+            errors: result.errors
+          })
         });
+        return;
       }
+      contributions.push({
+        pluginId: extractor.pluginId,
+        extensionId: extractor.id,
+        nodePath: opts.node.path,
+        contributionId,
+        contract: declared.contract,
+        payload,
+        emittedAt: Date.now()
+      });
     };
     const store = opts.pluginStores?.get(extractor.pluginId);
     const ctx = buildExtractorContext(
@@ -618,6 +1150,7 @@ async function runExtractorsForNode(opts) {
       opts.frontmatter,
       emitLink,
       enrichNode,
+      emitContribution,
       store
     );
     await extractor.extract(ctx);
@@ -625,9 +1158,32 @@ async function runExtractorsForNode(opts) {
   return {
     internalLinks,
     externalLinks,
-    enrichments: Array.from(enrichmentBuffer.values())
+    enrichments: Array.from(enrichmentBuffer.values()),
+    contributions
   };
 }
+function readDeclaredContributions(extension) {
+  const out = /* @__PURE__ */ new Map();
+  const raw = extension.viewContributions;
+  if (typeof raw !== "object" || raw === null) return out;
+  for (const [id, value] of Object.entries(raw)) {
+    if (typeof value !== "object" || value === null) continue;
+    const contract = value.contract;
+    if (typeof contract !== "string") continue;
+    out.set(id, { contract });
+  }
+  return out;
+}
+function emitExtensionError(emitter, qualifiedId, nodePath, data) {
+  emitter.emit(
+    makeEvent("extension.error", {
+      kind: "contribution-rejected",
+      extensionId: qualifiedId,
+      nodePath,
+      ...data
+    })
+  );
+}
 function computeCacheDecision(opts) {
   const applicableExtractors = opts.extractors.filter(
     (ex) => ex.applicableKinds === void 0 || ex.applicableKinds.includes(opts.kind)
@@ -750,7 +1306,9 @@ async function walkAndExtract(opts) {
   const cachedPaths = /* @__PURE__ */ new Set();
   const frontmatterIssues = [];
   const enrichmentBuffer = /* @__PURE__ */ new Map();
+  const contributionsBuffer = [];
   const extractorRuns = [];
+  const sidecarRoots = /* @__PURE__ */ new Map();
   let filesWalked = 0;
   let index = 0;
   const walkOptions = ignoreFilter ? { ignoreFilter } : {};
@@ -761,14 +1319,20 @@ async function walkAndExtract(opts) {
     if (list) list.push(qualified);
     else shortIdToQualified.set(ex.id, [qualified]);
   }
+  const claimedPaths = /* @__PURE__ */ new Set();
   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;
+      if (claimedPaths.has(raw.path)) continue;
       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;
+      }
+      claimedPaths.add(raw.path);
       index += 1;
       const cacheDecision = computeCacheDecision({
         extractors,
@@ -796,10 +1360,19 @@ async function walkAndExtract(opts) {
           priorLinksByOriginating,
           priorFrontmatterIssuesByNode
         });
+        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;
@@ -835,6 +1408,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,
@@ -857,6 +1439,7 @@ async function walkAndExtract(opts) {
       for (const enr of extractResult.enrichments) {
         enrichmentBuffer.set(`${enr.nodePath}\0${enr.extractorId}`, enr);
       }
+      for (const c of extractResult.contributions) contributionsBuffer.push(c);
       const ranAt = Date.now();
       for (const ex of applicableExtractors) {
         const qualified = qualifiedExtensionId(ex.pluginId, ex.id);
@@ -869,6 +1452,7 @@ async function walkAndExtract(opts) {
       }
     }
   }
+  const orphanSidecars = discoverOrphanSidecars(roots);
   return {
     nodes,
     internalLinks,
@@ -877,7 +1461,10 @@ async function walkAndExtract(opts) {
     frontmatterIssues,
     filesWalked,
     enrichments: [...enrichmentBuffer.values()],
-    extractorRuns
+    extractorRuns,
+    contributions: contributionsBuffer,
+    orphanSidecars,
+    sidecarRoots
   };
 }
 function reuseCachedLink(link, shortIdToQualified, cachedQualifiedIds, applicableQualifiedIds) {
@@ -906,20 +1493,77 @@ 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, viewContributions, emitter, hookDispatcher) {
   const issues = [];
+  const contributions = [];
+  const validators = loadSchemaValidators();
+  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 qualifiedId = qualifiedExtensionId(rule.pluginId, rule.id);
+    const declaredContributions = readDeclaredContributions(rule);
+    const emitContribution = (nodePath, contributionId, payload) => {
+      const declared = declaredContributions.get(contributionId);
+      if (!declared) {
+        emitExtensionError(emitter, qualifiedId, nodePath, {
+          phase: "emitContribution",
+          contributionId,
+          reason: "unknown-contribution-id",
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionUnknownId, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath
+          })
+        });
+        return;
+      }
+      const result = validators.validateContributionPayload(declared.contract, payload);
+      if (!result.ok) {
+        emitExtensionError(emitter, qualifiedId, nodePath, {
+          phase: "emitContribution",
+          contributionId,
+          contract: declared.contract,
+          reason: result.errors,
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionPayloadInvalid, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath,
+            contract: declared.contract,
+            errors: result.errors
+          })
+        });
+        return;
+      }
+      contributions.push({
+        pluginId: rule.pluginId,
+        extensionId: rule.id,
+        nodePath,
+        contributionId,
+        contract: declared.contract,
+        payload,
+        emittedAt: Date.now()
+      });
+    };
+    const emitted = await rule.evaluate({
+      nodes,
+      links: internalLinks,
+      orphanSidecars: ruleOrphans,
+      sidecarRoots,
+      annotationContributions,
+      viewContributions,
+      emitContribution
+    });
     for (const issue of emitted) {
       const validated = validateIssue(rule, issue, emitter);
       if (validated) issues.push(validated);
     }
-    const ruleId = qualifiedExtensionId(rule.pluginId, rule.id);
-    const evt = makeEvent("rule.completed", { ruleId });
+    const evt = makeEvent("rule.completed", { ruleId: qualifiedId });
     emitter.emit(evt);
     await hookDispatcher.dispatch("rule.completed", evt);
   }
-  return issues;
+  return { issues, contributions };
 }
 function originatingNodeOf(link, priorNodePaths) {
   if (link.kind === "supersedes" && !priorNodePaths.has(link.source)) {
@@ -1090,7 +1734,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",
@@ -1135,7 +1779,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,
@@ -1150,12 +1793,7 @@ function buildNode(args) {
     linksOutCount: 0,
     linksInCount: 0,
     externalRefsCount: 0,
-    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"])
+    frontmatter: args.frontmatter
   };
   if (args.encoder) {
     node.tokens = countTokens(args.encoder, args.frontmatterRaw, args.body);
@@ -1176,25 +1814,73 @@ 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 pickString(value) {
-  return typeof value === "string" && value.length > 0 ? value : 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.identityBodyHash,
+    storedFrontmatterHash: result.parsed.identityFrontmatterHash,
+    liveBodyHash,
+    liveFrontmatterHash
+  });
+  node.sidecar = {
+    present: true,
+    status,
+    annotations: result.parsed.annotations,
+    root: result.parsed.raw
+  };
+  sidecarRoots.set(node.path, result.parsed.raw);
+  return issues;
 }
-function pickStability(value) {
-  if (value === "experimental" || value === "stable" || value === "deprecated") return value;
+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 buildExtractorContext(extractor, node, body, frontmatter, emitLink, enrichNode, store) {
+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 buildExtractorContext(extractor, node, body, frontmatter, emitLink, enrichNode, emitContribution, store) {
   const scope = extractor.scope;
   return {
     node,
@@ -1202,6 +1888,7 @@ function buildExtractorContext(extractor, node, body, frontmatter, emitLink, enr
     frontmatter: scope === "body" ? {} : frontmatter,
     emitLink,
     enrichNode,
+    emitContribution,
     ...store !== void 0 ? { store } : {}
   };
 }
@@ -1340,16 +2027,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;
@@ -1433,12 +2120,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;
@@ -1689,7 +2376,23 @@ function parseLogLevel(value) {
 
 // kernel/index.ts
 function createKernel() {
-  return { registry: new Registry() };
+  let annotationKeys = Object.freeze([]);
+  let viewContributions = Object.freeze([]);
+  return {
+    registry: new Registry(),
+    getRegisteredAnnotationKeys() {
+      return annotationKeys;
+    },
+    setRegisteredAnnotationKeys(entries) {
+      annotationKeys = Object.freeze([...entries]);
+    },
+    getRegisteredViewContributions() {
+      return viewContributions;
+    },
+    setRegisteredViewContributions(entries) {
+      viewContributions = Object.freeze([...entries]);
+    }
+  };
 }
 export {
   DuplicateExtensionError,