@skill-map/cli 0.35.0 → 0.36.0

package/dist/kernel/index.d.ts

@@ -1756,12 +1756,12 @@ interface IProviderKind {
      *     kinds (`agent`, `command`, `skill` per their schemas) typically
      *     declare this first.
      *   - `'filename-basename'`, `basename(path)` without the extension.
-     *     For Claude/Gemini/OpenAI agents and commands the filename IS the
+     *     For Claude/OpenAI agents and commands the filename IS the
      *     invocation handle when `name:` is absent.
-     *   - `'dirname'`, `basename(dirname(path))`. Anthropic skills + Gemini
-     *     skills + agent-skills resolve to the directory between the
-     *     skills root and the SKILL.md (e.g.
-     *     `.claude/skills/foo/SKILL.md` → `foo`).
+     *   - `'dirname'`, `basename(dirname(path))`. Anthropic skills +
+     *     agent-skills (open standard, also adopted by Antigravity)
+     *     resolve to the directory between the skills root and the
+     *     SKILL.md (e.g. `.claude/skills/foo/SKILL.md` → `foo`).
      *
      * Compare with `IProvider.resolution` (which declares which target
      * kinds resolve which link.kind): `identifiers` is a per-kind detail
@@ -1930,7 +1930,7 @@ interface IProvider extends IExtensionBase {
      * orchestrator drops the duplicate.
      *
      * Convention: a Provider's classify returns one of its own `kinds`
-     * map keys for paths in its territory (`.claude/`, `.gemini/`,
+     * map keys for paths in its territory (`.claude/`, `.codex/`,
      * `.agents/skills/`, etc.) and `null` elsewhere. External Providers
      * (Cursor, Obsidian, …) follow the same rule: claim what's yours,
      * disclaim everything else. The orchestrator does not validate the
@@ -1969,6 +1969,41 @@ interface IProvider extends IExtensionBase {
      * confidence-lift contract, which runs against the merged Link graph.
      */
     resolution?: Record<string, string[]>;
+    /**
+     * Reserved invocation names this Provider's runtime owns for each
+     * kind. Maps a `node.kind` to the set of normalised names the runtime
+     * uses for its built-in invocables (e.g. `claude` reserves
+     * `['help', 'clear', 'init', …]` under `command` because typing
+     * `/help` in the Claude CLI runs the built-in help screen, not a
+     * user-authored `.claude/commands/help.md`).
+     *
+     * Two consumers share the catalog:
+     *
+     *   1. The `core/reserved-name` analyzer scans every user node and
+     *      emits a `warn` issue when the node's normalised identifiers
+     *      (per `IProviderKind.identifiers`) intersect the reserved list
+     *      for its provider + kind. The user file is silently shadowed
+     *      by the runtime, the analyzer surfaces it so the operator can
+     *      rename.
+     *   2. The post-walk confidence-lift transform downgrades any link
+     *      that resolves to a reserved node (by path OR by name) to a
+     *      very low confidence floor (today `0.1`) instead of bumping
+     *      to `1.0`. The graph then reflects "this edge exists in disk
+     *      but the runtime ignores the target".
+     *
+     * Default `undefined` ≡ empty map ≡ no reserved names. Reserved
+     * lookup normalises both sides via the §Extractor · trigger
+     * normalization pipeline (lowercase, NFD, separator unification),
+     * so a literal `Init-Project` in the manifest still matches a user
+     * `name: init project` or filename `Init-Project.md`.
+     *
+     * The set is intentionally per-kind, not global: a name reserved for
+     * commands (`/help`) may legitimately appear as a skill (a "help"
+     * skill that triggers via something other than the command channel).
+     * Providers MUST scope each entry to the kind the runtime actually
+     * consumes.
+     */
+    reservedNames?: Record<string, readonly string[]>;
 }
 /**
  * Declarative read config a Provider declares via `IProvider.read`.
@@ -2234,6 +2269,21 @@ interface IAnalyzerContext {
      * adapter does not maintain the side index. Treat as read-only.
      */
     referenceablePaths?: ReadonlySet<string>;
+    /**
+     * Paths of nodes whose normalised identifier(s) intersect their
+     * Provider's `reservedNames[kind]` catalog (e.g. a user-authored
+     * `.claude/commands/help.md` whose name normalises to `help`,
+     * shadowed by Claude's built-in `/help` command). The set is
+     * computed once per scan by the orchestrator (mirroring the same
+     * set threaded to the post-walk confidence-lift transform), so
+     * analyzers consume it without re-deriving every node's
+     * identifiers. The single consumer today is `core/reserved-name`,
+     * which projects one warn issue per entry; future analyzers MAY
+     * read the set for cross-rule cohesion (e.g. an action that
+     * suggests rename targets). Absent for legacy callers (older
+     * `runScan` sites that never wired the field through).
+     */
+    reservedNodePaths?: ReadonlySet<string>;
     /**
      * Absolute path of the scan's project root (cwd of the invocation).
      * Threaded into the analyzer pass so an analyzer that needs to
@@ -3048,8 +3098,8 @@ interface RunScanOptions {
      *   - `null`: explicit "no lens". Provider-specific extractors are
      *     unconditionally skipped (spec-strict).
      *   - `undefined`: kernel auto-detects from `options.roots[0]` using
-     *     filesystem markers (`.claude/`, `.gemini/`, `.codex/`,
-     *     `AGENTS.md`). Convenient default for out-of-band callers
+     *     filesystem markers (`.claude/`, `.codex/`, `AGENTS.md`).
+     *     Convenient default for out-of-band callers
      *     (integration tests, embedders) that don't thread a settings
      *     reader. Production callers (scan-runner) resolve upstream and
      *     pass `string | null` explicitly, never `undefined`.

package/dist/kernel/index.js

@@ -94,14 +94,14 @@ var Registry = class {
 
 // kernel/orchestrator/index.ts
 import { existsSync as existsSync11, statSync as statSync4 } from "fs";
-import { isAbsolute as isAbsolute4, resolve as resolve10 } from "path";
+import { isAbsolute as isAbsolute4, resolve as resolve11 } from "path";
 import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
 import cl100k_base from "js-tiktoken/ranks/cl100k_base";
 
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.35.0",
+  version: "0.36.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -1051,7 +1051,13 @@ function loadConfigForScope(opts) {
 // core/config/active-provider.ts
 var DETECTION_RULES = [
   { providerId: "claude", marker: ".claude" },
-  { providerId: "gemini", marker: ".gemini" },
+  // `gemini` retired 2026-05-22: Google replaced the Gemini CLI with the
+  // Antigravity CLI (released 2026-05-19; Gemini CLI sunsets 2026-06-18).
+  // Antigravity adopted the open-standard `.agents/` instead of a
+  // vendor-specific directory, so detection of a Google CLI project
+  // falls through to the universal `agent-skills` lens (`.agents/`
+  // already classifies via that neutral provider). The lens can still
+  // be set manually via `sm config set activeProvider antigravity`.
   { providerId: "openai", marker: ".codex" },
   { providerId: "openai", marker: "AGENTS.md" },
   { providerId: "cursor", marker: ".cursor" }
@@ -1429,7 +1435,7 @@ function isExternalUrlLink(link) {
 }
 
 // kernel/orchestrator/analyzers.ts
-async function runAnalyzers(analyzers, nodes, internalLinks, orphanSidecars, sidecarRoots, annotationContributions, viewContributions, orphanJobFiles, referenceablePaths, cwd, registeredActionIds, emitter, hookDispatcher) {
+async function runAnalyzers(analyzers, nodes, internalLinks, orphanSidecars, sidecarRoots, annotationContributions, viewContributions, orphanJobFiles, referenceablePaths, cwd, registeredActionIds, emitter, hookDispatcher, reservedNodePaths) {
   const issues = [];
   const contributions = [];
   const validators = loadSchemaValidators();
@@ -1493,6 +1499,7 @@ async function runAnalyzers(analyzers, nodes, internalLinks, orphanSidecars, sid
       orphanJobFiles,
       ...referenceablePaths ? { referenceablePaths } : {},
       ...cwd ? { cwd } : {},
+      ...reservedNodePaths ? { reservedNodePaths } : {},
       emitContribution
     });
     for (const issue of emitted) {
@@ -1713,7 +1720,7 @@ function classifyLinkSource(source, shortIdToQualified, cachedQualifiedIds, appl
   return "obsolete";
 }
 
-// kernel/orchestrator/lift-resolved-link-confidence.ts
+// kernel/orchestrator/node-identifiers.ts
 import { posix as pathPosix } from "path";
 
 // kernel/trigger-normalize.ts
@@ -1726,14 +1733,53 @@ function normalizeTrigger(source) {
   return out.trim();
 }
 
+// kernel/orchestrator/node-identifiers.ts
+function deriveNodeIdentifiers(node, kindDescriptor) {
+  const sources = kindDescriptor?.identifiers;
+  if (!sources || sources.length === 0) return [];
+  const out = [];
+  for (const source of sources) {
+    const raw = readIdentifier(source, node);
+    if (!raw) continue;
+    const normalised = normalizeTrigger(raw);
+    if (normalised) out.push(normalised);
+  }
+  return out;
+}
+function readIdentifier(source, node) {
+  if (source === "frontmatter.name") return readFrontmatterName(node);
+  if (source === "filename-basename") return readFilenameBasename(node);
+  return readDirname(node);
+}
+function readFrontmatterName(node) {
+  const raw = node.frontmatter?.["name"];
+  if (typeof raw !== "string") return null;
+  return raw.length > 0 ? raw : null;
+}
+function readFilenameBasename(node) {
+  const base = pathPosix.basename(node.path);
+  if (!base) return null;
+  const ext = pathPosix.extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  return stem.length > 0 ? stem : null;
+}
+function readDirname(node) {
+  const dir = pathPosix.dirname(node.path);
+  if (!dir || dir === "." || dir === "/") return null;
+  const base = pathPosix.basename(dir);
+  return base.length > 0 ? base : null;
+}
+
 // kernel/orchestrator/lift-resolved-link-confidence.ts
+var RESERVED_TARGET_CONFIDENCE = 0.1;
 function liftResolvedLinkConfidence(links, nodes, ctx) {
   if (!links.some((l) => l.confidence < 1)) return;
   const indexes = buildIndexes(nodes, ctx);
   for (const link of links) {
-    if (link.confidence < 1 && resolves(link, indexes, ctx)) {
-      link.confidence = 1;
-    }
+    if (link.confidence >= 1) continue;
+    const resolution = resolve7(link, indexes, ctx);
+    if (resolution === "none") continue;
+    link.confidence = ctx.reservedNodePaths.has(resolution) ? RESERVED_TARGET_CONFIDENCE : 1;
   }
 }
 function buildIndexes(nodes, ctx) {
@@ -1747,18 +1793,19 @@ function buildIndexes(nodes, ctx) {
   }
   return { byPath: byPath2, byName, nodeByPath };
 }
-function resolves(link, indexes, ctx) {
-  if (indexes.byPath.has(link.target)) return true;
-  return resolvesByName(link, indexes, ctx);
+function resolve7(link, indexes, ctx) {
+  if (indexes.byPath.has(link.target)) return link.target;
+  return resolveByName(link, indexes, ctx);
 }
-function resolvesByName(link, indexes, ctx) {
+function resolveByName(link, indexes, ctx) {
   const stripped = stripTriggerSigil(link.trigger?.normalizedTrigger);
-  if (stripped === null) return false;
+  if (stripped === null) return "none";
   const candidates = indexes.byName.get(stripped);
-  if (!candidates?.length) return false;
+  if (!candidates?.length) return "none";
   const allowedKinds = lookupAllowedKinds(link, indexes, ctx);
-  if (!allowedKinds?.length) return false;
-  return candidates.some((c) => allowedKinds.includes(c.kind));
+  if (!allowedKinds?.length) return "none";
+  const winner = candidates.find((c) => allowedKinds.includes(c.kind));
+  return winner ? winner.path : "none";
 }
 function lookupAllowedKinds(link, indexes, ctx) {
   const sourceNode = indexes.nodeByPath.get(link.source);
@@ -1772,44 +1819,17 @@ function stripTriggerSigil(normalized) {
 }
 function indexNode(node, ctx, byName) {
   const kindDescriptor = ctx.kindRegistry.get(kindKey(node));
-  const sources = kindDescriptor?.identifiers;
-  if (!sources || sources.length === 0) return;
-  for (const source of sources) {
-    const raw = deriveIdentifier(source, node);
-    if (!raw) continue;
-    const normalized = normalizeTrigger(raw);
-    if (!normalized) continue;
-    const bucket = byName.get(normalized);
+  const normalised = deriveNodeIdentifiers(node, kindDescriptor);
+  for (const name of normalised) {
+    const entry = { kind: node.kind, path: node.path };
+    const bucket = byName.get(name);
     if (bucket) {
-      bucket.push({ kind: node.kind });
+      bucket.push(entry);
     } else {
-      byName.set(normalized, [{ kind: node.kind }]);
+      byName.set(name, [entry]);
     }
   }
 }
-function deriveIdentifier(source, node) {
-  if (source === "frontmatter.name") return readFrontmatterName(node);
-  if (source === "filename-basename") return readFilenameBasename(node);
-  return readDirname(node);
-}
-function readFrontmatterName(node) {
-  const raw = node.frontmatter?.["name"];
-  if (typeof raw !== "string") return null;
-  return raw.length > 0 ? raw : null;
-}
-function readFilenameBasename(node) {
-  const base = pathPosix.basename(node.path);
-  if (!base) return null;
-  const ext = pathPosix.extname(base);
-  const stem = ext ? base.slice(0, -ext.length) : base;
-  return stem.length > 0 ? stem : null;
-}
-function readDirname(node) {
-  const dir = pathPosix.dirname(node.path);
-  if (!dir || dir === "." || dir === "/") return null;
-  const base = pathPosix.basename(dir);
-  return base.length > 0 ? base : null;
-}
 function kindKey(node) {
   return `${node.provider}/${node.kind}`;
 }
@@ -1978,7 +1998,7 @@ import { join as join7, relative as relative2, sep } from "path";
 
 // kernel/scan/ignore.ts
 import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
-import { dirname as dirname4, resolve as resolve7 } from "path";
+import { dirname as dirname4, resolve as resolve8 } from "path";
 import { fileURLToPath } from "url";
 import ignoreFactory from "ignore";
 function buildIgnoreFilter(opts = {}) {
@@ -2012,11 +2032,11 @@ function loadDefaultsText() {
 function readDefaultsFromDisk() {
   const here = dirname4(fileURLToPath(import.meta.url));
   const candidates = [
-    resolve7(here, "../../config/defaults/skillmapignore"),
+    resolve8(here, "../../config/defaults/skillmapignore"),
     // src/kernel/scan/ → src/config/defaults/
-    resolve7(here, "../config/defaults/skillmapignore"),
+    resolve8(here, "../config/defaults/skillmapignore"),
     // dist/cli.js → dist/config/defaults/ (siblings)
-    resolve7(here, "config/defaults/skillmapignore")
+    resolve8(here, "config/defaults/skillmapignore")
   ];
   for (const candidate of candidates) {
     if (existsSync6(candidate)) {
@@ -2207,7 +2227,7 @@ function resolveProviderWalk(provider) {
 
 // kernel/sidecar/parse.ts
 import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
-import { dirname as dirname5, resolve as resolve8 } from "path";
+import { dirname as dirname5, resolve as resolve9 } from "path";
 import { createRequire as createRequire3 } from "module";
 import { Ajv2020 as Ajv20204 } from "ajv/dist/2020.js";
 import yaml2 from "js-yaml";
@@ -2286,10 +2306,10 @@ function getSidecarValidator() {
   applyAjvFormats(ajv);
   const specRoot = resolveSpecRoot2();
   const annotationsSchema = JSON.parse(
-    readFileSync8(resolve8(specRoot, "schemas/annotations.schema.json"), "utf8")
+    readFileSync8(resolve9(specRoot, "schemas/annotations.schema.json"), "utf8")
   );
   const sidecarSchema = JSON.parse(
-    readFileSync8(resolve8(specRoot, "schemas/sidecar.schema.json"), "utf8")
+    readFileSync8(resolve9(specRoot, "schemas/sidecar.schema.json"), "utf8")
   );
   ajv.addSchema(annotationsSchema);
   cachedSidecarValidator = ajv.compile(sidecarSchema);
@@ -2360,7 +2380,7 @@ function safeIsFile(path) {
 
 // kernel/sidecar/store.ts
 import { existsSync as existsSync9, readFileSync as readFileSync9 } from "fs";
-import { dirname as dirname6, resolve as resolve9 } from "path";
+import { dirname as dirname6, resolve as resolve10 } from "path";
 import { createRequire as createRequire4 } from "module";
 import { Ajv2020 as Ajv20205 } from "ajv/dist/2020.js";
 import yaml3 from "js-yaml";
@@ -2904,7 +2924,7 @@ async function runScanInternal(_kernel, options) {
     pluginStores: options.pluginStores,
     activeProvider: resolveActiveProviderOption(options.activeProvider, options.roots)
   });
-  const postWalkCtx = buildPostWalkTransformCtx(_kernel);
+  const postWalkCtx = buildPostWalkTransformCtx(_kernel, walked.nodes);
   walked.internalLinks = applyPostWalkTransforms(walked.internalLinks, walked.nodes, postWalkCtx);
   recomputeLinkCounts(walked.nodes, walked.internalLinks);
   recomputeExternalRefsCount(walked.nodes, walked.externalLinks, walked.cachedPaths);
@@ -2925,7 +2945,8 @@ async function runScanInternal(_kernel, options) {
     options.cwd,
     registeredActionIds,
     emitter,
-    hookDispatcher
+    hookDispatcher,
+    postWalkCtx.reservedNodePaths
   );
   mergeAnalyzerEmissions(walked, analyzerResult, exts.analyzers);
   const issues = analyzerResult.issues;
@@ -2938,9 +2959,19 @@ async function runScanInternal(_kernel, options) {
   await hookDispatcher.dispatch("scan.completed", scanCompletedEvent);
   return buildScanReturn(walked, issues, renameOps, stats, options, setup);
 }
-function buildPostWalkTransformCtx(kernel) {
+function buildPostWalkTransformCtx(kernel, nodes) {
+  const { kindRegistry, providerResolution, reservedNamesByProviderKind } = buildProviderIndexes(kernel);
+  const reservedNodePaths = buildReservedNodePaths(
+    nodes,
+    kindRegistry,
+    reservedNamesByProviderKind
+  );
+  return { kindRegistry, providerResolution, reservedNodePaths };
+}
+function buildProviderIndexes(kernel) {
   const kindRegistry = /* @__PURE__ */ new Map();
   const providerResolution = /* @__PURE__ */ new Map();
+  const reservedNamesByProviderKind = /* @__PURE__ */ new Map();
   const providers = kernel.registry.all("provider");
   for (const provider of providers) {
     if (provider.kinds) {
@@ -2951,8 +2982,32 @@ function buildPostWalkTransformCtx(kernel) {
     if (provider.resolution) {
       providerResolution.set(provider.id, provider.resolution);
     }
+    if (provider.reservedNames) {
+      indexReservedNames(provider, reservedNamesByProviderKind);
+    }
   }
-  return { kindRegistry, providerResolution };
+  return { kindRegistry, providerResolution, reservedNamesByProviderKind };
+}
+function indexReservedNames(provider, out) {
+  for (const [kindName, list] of Object.entries(provider.reservedNames ?? {})) {
+    const normalised = new Set(list.map((raw) => normalizeTrigger(raw)).filter(Boolean));
+    if (normalised.size > 0) {
+      out.set(`${provider.id}/${kindName}`, normalised);
+    }
+  }
+}
+function buildReservedNodePaths(nodes, kindRegistry, reservedNamesByProviderKind) {
+  const out = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    const key = `${node.provider}/${node.kind}`;
+    const reservedSet = reservedNamesByProviderKind.get(key);
+    if (!reservedSet || reservedSet.size === 0) continue;
+    const ids = deriveNodeIdentifiers(node, kindRegistry.get(key));
+    if (ids.some((id) => reservedSet.has(id))) {
+      out.add(node.path);
+    }
+  }
+  return out;
 }
 function buildScanSetup(options) {
   const start = Date.now();
@@ -3045,7 +3100,7 @@ function validateRoots(roots) {
 function resolveActiveProviderOption(optionValue, roots) {
   if (optionValue !== void 0) return optionValue;
   for (const root of roots) {
-    const absRoot = isAbsolute4(root) ? root : resolve10(root);
+    const absRoot = isAbsolute4(root) ? root : resolve11(root);
     if (!existsSync11(absRoot)) continue;
     const detected = resolveActiveProvider(absRoot).resolved;
     if (detected !== null) return detected;
@@ -3054,10 +3109,10 @@ function resolveActiveProviderOption(optionValue, roots) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve11, relative as relative4, sep as sep3 } from "path";
+import { resolve as resolve12, relative as relative4, sep as sep3 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve11(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve12(opts.cwd, r));
   const ignoreFilterOpt = opts.ignoreFilter;
   const getFilter = ignoreFilterOpt === void 0 ? void 0 : typeof ignoreFilterOpt === "function" ? ignoreFilterOpt : () => ignoreFilterOpt;
   const ignored = getFilter ? (path) => {