@skill-map/spec 0.7.1 → 0.9.0

package/schemas/conformance-case.schema.json

@@ -31,12 +31,21 @@
       "description": "Pre-invocation toggles and ordered staging steps. All toggles default to `false`. `priorScans`, when present, run BEFORE the main `invoke` so a case can establish a prior snapshot the heuristic-driven verbs (e.g. `sm scan` rename detection) can react to.",
       "additionalProperties": false,
       "properties": {
-        "disableAllAdapters": { "type": "boolean" },
-        "disableAllDetectors": { "type": "boolean" },
-        "disableAllRules": { "type": "boolean" },
+        "disableAllProviders": {
+          "type": "boolean",
+          "description": "When true, the runner injects `SKILL_MAP_DISABLE_ALL_PROVIDERS=1` into the child process environment, dropping every Provider extension (built-in and user-plugin) before scan composition."
+        },
+        "disableAllExtractors": {
+          "type": "boolean",
+          "description": "When true, the runner injects `SKILL_MAP_DISABLE_ALL_EXTRACTORS=1` into the child process environment, dropping every Extractor extension before scan composition."
+        },
+        "disableAllRules": {
+          "type": "boolean",
+          "description": "When true, the runner injects `SKILL_MAP_DISABLE_ALL_RULES=1` into the child process environment, dropping every Rule extension before scan composition."
+        },
         "priorScans": {
           "type": "array",
-          "description": "Ordered staging scans, each running before the next. For step N, the runner first replaces the scope's adapter content with `priorScans[N].fixture`, then invokes `sm scan` with the supplied flags. After the last step, the runner copies the top-level `fixture` (overwriting again) and runs the main `invoke`. The DB persists across all steps because `.skill-map/` is preserved between fixture swaps.",
+          "description": "Ordered staging scans, each running before the next. For step N, the runner first replaces the scope's Provider content with `priorScans[N].fixture`, then invokes `sm scan` with the supplied flags. After the last step, the runner copies the top-level `fixture` (overwriting again) and runs the main `invoke`. The DB persists across all steps because `.skill-map/` is preserved between fixture swaps.",
           "items": {
             "type": "object",
             "required": ["fixture"],
@@ -63,7 +72,7 @@
       "properties": {
         "verb": {
           "type": "string",
-          "description": "First-level CLI verb (`scan`, `list`, `show`, `check`, `findings`, `graph`, `export`, `audit`, `job`, `record`, …)."
+          "description": "First-level CLI verb (`scan`, `list`, `show`, `check`, `findings`, `graph`, `export`, `job`, `record`, …)."
         },
         "sub": {
           "type": "string",

package/schemas/execution-record.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/execution-record.schema.json",
   "title": "ExecutionRecord",
-  "description": "A single row in the execution history (`state_executions`). One record per action or audit invocation — regardless of whether the runner was CLI, Skill, or in-process.",
+  "description": "A single row in the execution history (`state_executions`). One record per action invocation — regardless of whether the runner was CLI, Skill, or in-process.",
   "type": "object",
   "required": ["id", "kind", "extensionId", "extensionVersion", "status", "startedAt", "finishedAt"],
   "additionalProperties": false,
@@ -13,12 +13,12 @@
     },
     "kind": {
       "type": "string",
-      "enum": ["action", "audit"],
-      "description": "Which extension kind was executed."
+      "enum": ["action"],
+      "description": "Which extension kind was executed. The enum has a single value today (the audit kind was removed pre-1.0); the field is preserved as a forward-compatibility lever."
     },
     "extensionId": {
       "type": "string",
-      "description": "Id of the action or audit that ran (e.g. `skill-summarizer`, `validate-all`)."
+      "description": "Id of the action that ran (e.g. `skill-summarizer`)."
     },
     "extensionVersion": {
       "type": "string",
@@ -26,13 +26,13 @@
     },
     "nodeIds": {
       "type": "array",
-      "description": "Target `node.path` values. Empty for audits that evaluate the whole graph.",
+      "description": "Target `node.path` values. Empty for whole-graph actions.",
       "items": { "type": "string" }
     },
     "contentHash": {
       "type": ["string", "null"],
       "pattern": "^[a-f0-9]{64}$",
-      "description": "Duplicate-prevention hash used at submit time: sha256(actionId + actionVersion + bodyHash + frontmatterHash + promptTemplateHash). Null for audits."
+      "description": "Duplicate-prevention hash used at submit time: sha256(actionId + actionVersion + bodyHash + frontmatterHash + promptTemplateHash). May be null for in-process actions that don't memoize."
     },
     "status": {
       "type": "string",
@@ -51,7 +51,7 @@
     "runner": {
       "type": ["string", "null"],
       "enum": ["cli", "skill", "in-process", null],
-      "description": "Which runner executed this job. Null for audits."
+      "description": "Which runner executed this job. Null when the action runs synchronously without dispatching."
     },
     "startedAt": {
       "type": "integer",
@@ -82,7 +82,7 @@
     },
     "jobId": {
       "type": ["string", "null"],
-      "description": "Originating job id when applicable. Null for audits and in-process actions."
+      "description": "Originating job id when applicable. Null for in-process actions."
     }
   }
 }

package/schemas/extensions/action.schema.json

@@ -36,10 +36,10 @@
           "items": { "type": "string", "enum": ["skill", "agent", "command", "hook", "note"] },
           "description": "Node kinds this action accepts. Omitted → any kind."
         },
-        "adapter": {
+        "provider": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "Adapter ids whose nodes this action accepts. Omitted → any adapter."
+          "description": "Provider ids whose nodes this action accepts. Omitted → any Provider."
         },
         "stability": {
           "type": "array",

package/schemas/extensions/base.schema.json

@@ -2,23 +2,23 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/extensions/base.schema.json",
   "title": "ExtensionBase",
-  "description": "Base manifest shape common to every extension kind. Kind-specific schemas (`adapter`, `detector`, `rule`, `action`, `audit`, `renderer`) extend this via `allOf` and add a discriminant `kind` literal plus kind-specific fields. camelCase keys throughout. Closed-content enforcement (unknown keys = bug) lives on the kind schemas via `unevaluatedProperties: false`; those see base's evaluated keys through the `allOf` composition. Adding closure here too would force every kind schema to re-list every base key, which is the footgun the spec used to trip on before 2026-04-22.",
+  "description": "Base manifest shape common to every extension kind. Kind-specific schemas (`provider`, `extractor`, `rule`, `action`, `formatter`, `hook`) extend this via `allOf` and add a discriminant `kind` literal plus kind-specific fields. camelCase keys throughout. Closed-content enforcement (unknown keys = bug) lives on the kind schemas via `unevaluatedProperties: false`; those see base's evaluated keys through the `allOf` composition. Adding closure here too would force every kind schema to re-list every base key, which is the footgun the spec used to trip on before 2026-04-22.",
   "type": "object",
   "required": ["id", "kind", "version"],
   "properties": {
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
-      "description": "Kebab-case identifier unique within the extension's kind across all loaded plugins. The built-in default set uses bare ids (`claude`, `frontmatter`, `trigger-collision`). Third-party extensions SHOULD namespace with their plugin id (`my-plugin/foo-detector`) to avoid collisions."
+      "description": "Kebab-case identifier unique within the extension's kind across the same plugin. The kernel registers every extension under the **qualified** id `<plugin-id>/<id>` (e.g. `core/frontmatter`, `claude/slash`, `hello-world/greet`) — see `architecture.md` §Extension kinds and `plugin-author-guide.md` §Qualified extension ids. Authors declare only the short id here; the qualifier is composed by the loader from the manifest's `id` (or, for built-ins, from the bundle declaration in `built-ins.ts`). The pattern is intentionally constrained to a single kebab-case segment without the `/` separator: the qualifier always lives in the plugin id, never in the extension id."
     },
     "kind": {
       "type": "string",
-      "enum": ["adapter", "detector", "rule", "action", "audit", "renderer"],
+      "enum": ["provider", "extractor", "rule", "action", "formatter", "hook"],
       "description": "Discriminant. MUST match the file exporting this manifest; kind mismatch → load-error."
     },
     "version": {
       "type": "string",
-      "description": "Extension semver. Bumped independently from the plugin version; frozen into `state_executions.extension_version` on every run for audit reproducibility."
+      "description": "Extension semver. Bumped independently from the plugin version; frozen into `state_executions.extension_version` on every run for reproducibility."
     },
     "description": {
       "type": "string",
@@ -32,7 +32,7 @@
     },
     "preconditions": {
       "type": "array",
-      "description": "Free-form predicates the kernel evaluates before offering this extension. Canonical keys: `kind=<node-kind>`, `adapter=<adapter-id>`, `frontmatter.<path>=<value>`. Unknown keys are skipped with a warning, not rejected.",
+      "description": "Free-form predicates the kernel evaluates before offering this extension. Canonical keys: `kind=<node-kind>`, `provider=<provider-id>`, `frontmatter.<path>=<value>`. Unknown keys are skipped with a warning, not rejected.",
       "items": { "type": "string" }
     },
     "entry": {

package/schemas/extensions/extractor.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/extractor.schema.json",
+  "title": "ExtensionExtractor",
+  "description": "Manifest shape for an `Extractor` extension. An extractor consumes a parsed node (frontmatter + body) and emits output through three context-supplied callbacks rather than returning a value: `ctx.emitLink(link)` writes to the kernel's `links` table (validated against `emitsLinkKinds` before persistence), `ctx.enrichNode(partial)` merges author-canonical properties into the kernel's enrichment layer (separate from the author-supplied frontmatter), and `ctx.store` persists into the plugin's own KV namespace or dedicated tables. The runtime method is `extract(ctx) → void`. Extractors run in isolation: they MUST NOT read other nodes, the graph, or the DB. Cross-node reasoning lives in Rules. Extractors are dual-mode: `deterministic` extractors run synchronously inside `sm scan`; `probabilistic` extractors invoke an LLM through the kernel's `RunnerPort` (exposed as `ctx.runner`) and execute only as queued jobs (never during scan). See `architecture.md` §Execution modes for the full contract. Renamed from `detector` in spec 0.8.x — the FindBugs/SpotBugs lineage of \"detector\" connoted bug finding, while this kind extracts signals (relations, enrichments, custom data); ENRE (Entity Relationship Extractor) is the closer precedent.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "emitsLinkKinds", "defaultConfidence"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "kind": { "const": "extractor" },
+    "mode": {
+      "type": "string",
+      "enum": ["deterministic", "probabilistic"],
+      "default": "deterministic",
+      "description": "`deterministic` (default): pure code, runs synchronously during `sm scan`. Same input → same output, every run. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job (`sm job submit extractor:<id>`); never participates in `sm scan`. The kernel rejects probabilistic extractors that try to register scan-time hooks at load time. Omitting the field is equivalent to declaring `deterministic`."
+    },
+    "emitsLinkKinds": {
+      "type": "array",
+      "description": "Subset of `Link.kind` values this extractor is allowed to emit through `ctx.emitLink(...)`. Emitting an unlisted kind at runtime → kernel rejects the link and logs `extractor-kind-violation`.",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": ["invokes", "references", "mentions", "supersedes"]
+      }
+    },
+    "defaultConfidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "Confidence attached to emitted links by default. Extractors MAY override per-link at emission time."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["frontmatter", "body", "both"],
+      "default": "both",
+      "description": "Which part of the node this extractor consumes. The kernel passes only the declared scope to the extractor — a `frontmatter` extractor that tries to read `body` receives an empty string."
+    },
+    "applicableKinds": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+      "uniqueItems": true,
+      "description": "Optional opt-in filter. If declared, the extractor runs only on nodes whose kind is in this list. Absent = applies to all kinds (default). No wildcards — the absence of the field already means \"every kind\". Empty array is invalid (`minItems: 1`). Unknown kinds (not declared by any installed Provider) load OK but emit a warning in `sm plugins doctor` — the Provider may arrive later. The kernel filters fail-fast: nodes whose kind is excluded never see `extract()`, so a probabilistic extractor wastes zero LLM cost on inapplicable nodes."
+    }
+  }
+}

package/schemas/extensions/formatter.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/formatter.schema.json",
+  "title": "ExtensionFormatter",
+  "description": "Manifest shape for a `Formatter` extension. A formatter serializes the graph (or a filtered subgraph) into a string in a declared format. Formatters are invoked by `sm graph --format <format>` and `sm export`. Formatters are deterministic-only — they sit at the graph-to-string boundary and their output MUST be byte-deterministic for the same input graph (the snapshot-test suite relies on this). The `mode` field MUST NOT appear in formatter manifests. Probabilistic narrators of the graph are a valid product but they live in jobs and emit Findings, not in formatters.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "formatId"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "kind": { "const": "formatter" },
+    "formatId": {
+      "type": "string",
+      "description": "Format identifier consumed by `sm graph --format <name>`. Built-in set: `ascii`, `mermaid`, `dot`, `json`. Third-party formatters MAY register new format ids; collisions are a load-time error. Distinct from the runtime method `format(ctx)` which produces the serialized output."
+    },
+    "contentType": {
+      "type": "string",
+      "description": "MIME-like hint used by the Server when streaming formatted output over HTTP (e.g. `text/plain`, `image/svg+xml`, `application/json`). Advisory.",
+      "default": "text/plain"
+    },
+    "supportsFilter": {
+      "type": "boolean",
+      "default": true,
+      "description": "If true, the formatter accepts the `--filter` expression used by `sm export`. If false, `sm export --format <this>` rejects `--filter` with exit 2."
+    }
+  }
+}

package/schemas/extensions/hook.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/hook.schema.json",
+  "title": "ExtensionHook",
+  "description": "Manifest shape for a `Hook` extension. Subscribes declaratively to a curated set of kernel lifecycle events. Dual-mode (deterministic / probabilistic). Hooks react to events; they cannot block or alter the main pipeline. Probabilistic hooks are deferred to the job subsystem and never run in-scan. The set of hookable triggers is intentionally small — eight events out of the full job-events catalog. Other events (per-node `scan.progress`, `model.delta`, `run.*`, internal job lifecycle) are deliberately not hookable: too verbose for a reactive surface, internal to the runner, or covered elsewhere. Declaring a trigger outside the hookable set yields `invalid-manifest` at load time. See `architecture.md` §Hook · curated trigger set for the per-trigger payload contracts.",
+  "type": "object",
+  "required": ["id", "kind", "version", "triggers"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "kind": { "const": "hook" },
+    "mode": {
+      "type": "string",
+      "enum": ["deterministic", "probabilistic"],
+      "default": "deterministic",
+      "description": "`deterministic`: the hook's `on(ctx)` runs in-process during the dispatch of the matching event, synchronously between the event's emission and the next pipeline step. `probabilistic`: the hook is enqueued as a job (handled by the job subsystem; lands at Step 10). A probabilistic hook is loaded but not dispatched in-scan — the kernel surfaces a stderr advisory and skips it until the job subsystem ships."
+    },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "List of lifecycle events this hook subscribes to. Each entry MUST be one of the hookable triggers below. Declaring an unknown event (e.g. `scan.progress`, `model.delta`) is rejected at load time with `invalid-manifest` — the curated set is the contract.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "scan.started",
+          "scan.completed",
+          "extractor.completed",
+          "rule.completed",
+          "action.completed",
+          "job.spawning",
+          "job.completed",
+          "job.failed"
+        ]
+      }
+    },
+    "filter": {
+      "type": "object",
+      "description": "Optional declarative filter applied to the event payload before invoking `on(ctx)`. Keys are payload field paths (e.g. `extractorId`, `ruleId`, `actionId`); values are the literal expected match. Cross-field validation against the declared `triggers` is performed at load time when the host implementation supports it; an unknown field for every declared trigger yields `invalid-manifest`. Absence of `filter` means \"invoke on every event of every declared trigger\"."
+    }
+  },
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ]
+}

package/schemas/extensions/provider.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/provider.schema.json",
+  "title": "ExtensionProvider",
+  "description": "Manifest shape for a `Provider` extension. A Provider declares its own universe: the platform it recognises (Claude Code, Codex, Gemini, Obsidian vault, generic MD), the catalog of node `kind`s it emits, the per-kind frontmatter schema each kind follows, and the filesystem directory (`explorationDir`) where its content lives. The catalog lives in the `kinds` map, keyed by kind name. Each map entry declares the relative path to the kind's frontmatter schema (resolved against the Provider's directory) and the qualified `defaultRefreshAction` id the UI's probabilistic-refresh surface dispatches for that kind. Spec only ships `frontmatter/base.schema.json` (universal); per-kind schemas live with their owning Provider so that adding a new platform is purely additive — no spec bump needed to introduce kinds. Exactly zero or one Provider MUST match any given file; multiple matches → the kernel emits an issue `provider-ambiguous` and the file is left unclassified. Providers are deterministic-only — they sit at the filesystem boundary and run during boot; probabilistic classification would make boot slow, costly, and non-reproducible. The `mode` field MUST NOT appear in Provider manifests. If you need LLM-assisted classification, write a probabilistic Extractor that emits classification hints via `ctx.emitLink`. Distinct from the **hexagonal-architecture** 'adapter' (`RunnerPort.adapter`, `StoragePort.adapter`, etc.), which is an internal driven-adapter implementing a port — Providers live in the extension surface, hexagonal adapters live in `src/kernel/adapters/`. Stability: stable as of spec v1.0.0 except where noted.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "kinds", "explorationDir"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "kind": { "const": "provider" },
+    "explorationDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Filesystem directory (relative to user home or project root) where this Provider's content lives. Required. Examples: '~/.claude' for the Claude Provider; '~/.cursor' for a hypothetical Cursor Provider. The kernel walks this directory during boot/scan to discover nodes; the Provider's `globs` (if declared) refines what to match inside. `sm doctor` validates the directory exists; missing directory yields a non-blocking warning."
+    },
+    "roots": {
+      "type": "array",
+      "description": "Path globs (relative to scope root) that this Provider SHOULD be consulted for. Advisory — the kernel walks all roots and consults every Provider regardless, but this field lets `sm doctor` warn when no file matched a specific Provider (i.e. the Provider was loaded for a platform that isn't in this scope).",
+      "items": { "type": "string" }
+    },
+    "kinds": {
+      "type": "object",
+      "description": "Catalog of node kinds this Provider emits. Keyed by kind name (e.g. `skill`, `agent`, `note`). Each entry declares the relative path to the kind's frontmatter schema (the kernel resolves it against the Provider's package directory) and the qualified `defaultRefreshAction` id the UI dispatches when the user requests a probabilistic refresh on a node of that kind. The map MUST be non-empty: a Provider that emits no kinds is meaningless. Kind names follow camelCase / lowerCase convention; the spec does not constrain the value space (a Cursor Provider could declare `rule`, an Obsidian Provider could declare `daily`).",
+      "minProperties": 1,
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z][a-zA-Z0-9]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["schema", "defaultRefreshAction"],
+        "additionalProperties": false,
+        "properties": {
+          "schema": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Path to the kind's frontmatter JSON Schema, relative to the Provider's package directory. The schema MUST extend `frontmatter/base.schema.json` (declared in spec) via `allOf` + `$ref` to base's `$id`. The kernel resolves the path at boot time and registers the schema with AJV for validation during scan."
+          },
+          "defaultRefreshAction": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*/[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+            "description": "Qualified action id (`<plugin-id>/<action-id>`) the UI's probabilistic-refresh surface (`🧠 prob`) dispatches for nodes of this kind. The action MUST exist in the registry by the time the graph is queried; a dangling reference disables the Provider with status `invalid-manifest`."
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/extensions/rule.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/extensions/rule.schema.json",
   "title": "ExtensionRule",
-  "description": "Manifest shape for a `Rule` extension. A rule consumes the full graph (nodes + links) after all detectors have run and emits `Issue[]`. Rules are dual-mode: `deterministic` rules MUST be byte-for-byte reproducible (same graph in → same issues out; time, random, and network are forbidden) and run synchronously inside `sm check` / `sm scan`. `probabilistic` rules invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (`sm job submit rule:<id>`); their output MAY vary across runs and they NEVER participate in `sm scan`. See `architecture.md` §Execution modes for the full contract.",
+  "description": "Manifest shape for a `Rule` extension. A rule consumes the full graph (nodes + links) after all extractors have run and emits `Issue[]`. Rules are dual-mode: `deterministic` rules MUST be byte-for-byte reproducible (same graph in → same issues out; time, random, and network are forbidden) and run synchronously inside `sm check` / `sm scan`. `probabilistic` rules invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (`sm job submit rule:<id>`); their output MAY vary across runs and they NEVER participate in `sm scan`. See `architecture.md` §Execution modes for the full contract.",
   "allOf": [
     { "$ref": "base.schema.json" }
   ],

package/schemas/frontmatter/base.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/frontmatter/base.schema.json",
   "title": "FrontmatterBase",
-  "description": "Base shape of the YAML frontmatter block on every node, across all kinds. Kind-specific schemas (`skill`, `agent`, `command`, `hook`, `note`) extend this via `allOf`. camelCase keys throughout. `additionalProperties` is intentionally permissive; the deterministic `unknown-field` rule emits warnings for keys outside the catalog so that the JSON Schema remains shape-only and policy lives in rules.",
+  "description": "Base shape of the YAML frontmatter block on every node, across all kinds. Universal — common to every Provider's nodes regardless of platform. Per-kind schemas live in the Provider that emits the kind (declared via `provider.kinds[<kind>].schema`) and extend this base via `allOf` + `$ref` to its `$id`. camelCase keys throughout. `additionalProperties` is intentionally permissive; the deterministic `unknown-field` rule emits warnings for keys outside the catalog so that the JSON Schema remains shape-only and policy lives in rules.",
   "type": "object",
   "required": ["name", "description", "metadata"],
   "additionalProperties": true,
@@ -19,7 +19,7 @@
     },
     "type": {
       "type": "string",
-      "description": "User-declared kind hint. Optional; the adapter may use it to tie-break classification. Free-form string so that new kinds introduced by adapters don't require a spec bump."
+      "description": "User-declared kind hint. Optional; the Provider may use it to tie-break classification. Free-form string so that new kinds introduced by Providers don't require a spec bump."
     },
     "author": {
       "type": "string",

package/schemas/link.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/link.schema.json",
   "title": "Link",
-  "description": "Directed relation between two nodes, produced by one or more detectors during a scan.",
+  "description": "Directed relation between two nodes, produced by one or more extractors during a scan.",
   "type": "object",
   "required": ["source", "target", "kind", "confidence", "sources"],
   "additionalProperties": false,
@@ -23,11 +23,11 @@
     "confidence": {
       "type": "string",
       "enum": ["high", "medium", "low"],
-      "description": "Detector's self-assessed confidence. Rules MAY filter by confidence."
+      "description": "Extractor's self-assessed confidence. Rules MAY filter by confidence."
     },
     "sources": {
       "type": "array",
-      "description": "Detector ids that produced this link. At least one. Multiple detectors may converge on the same link; kernel merges them.",
+      "description": "Extractor ids that produced this link. At least one. Multiple extractors may converge on the same link; kernel merges them.",
       "minItems": 1,
       "items": { "type": "string" }
     },
@@ -49,7 +49,7 @@
     },
     "location": {
       "type": ["object", "null"],
-      "description": "Where in the source body the link was found. Null if the detector didn't track location.",
+      "description": "Where in the source body the link was found. Null if the extractor didn't track location.",
       "required": ["line"],
       "additionalProperties": false,
       "properties": {

package/schemas/node.schema.json

@@ -4,7 +4,7 @@
   "title": "Node",
   "description": "A single markdown file in the graph (skill, agent, command, hook, note). Identified by its relative path from the scope root.",
   "type": "object",
-  "required": ["path", "kind", "adapter", "bodyHash", "frontmatterHash", "bytes", "linksOutCount", "linksInCount", "externalRefsCount"],
+  "required": ["path", "kind", "provider", "bodyHash", "frontmatterHash", "bytes", "linksOutCount", "linksInCount", "externalRefsCount"],
   "additionalProperties": false,
   "properties": {
     "path": {
@@ -14,11 +14,11 @@
     "kind": {
       "type": "string",
       "enum": ["skill", "agent", "command", "hook", "note"],
-      "description": "Category assigned by the adapter. Stability: stable. New kinds may be added in a minor bump."
+      "description": "Category assigned by the Provider. Stability: stable. New kinds may be added in a minor bump."
     },
-    "adapter": {
+    "provider": {
       "type": "string",
-      "description": "Identifier of the adapter extension that classified this node (e.g. `claude`)."
+      "description": "Identifier of the Provider extension that classified this node (e.g. `claude`)."
     },
     "title": {
       "type": ["string", "null"],

package/schemas/plugins-registry.schema.json

@@ -36,6 +36,12 @@
           "minItems": 1,
           "items": { "type": "string" }
         },
+        "granularity": {
+          "type": "string",
+          "enum": ["bundle", "extension"],
+          "default": "bundle",
+          "description": "Toggle granularity for this plugin. `bundle` (default) — the plugin id is the only enable/disable key; the whole set of extensions follows the toggle. `extension` — each extension is independently toggle-able under its qualified id `<plugin-id>/<extension-id>`. Built-in bundles use the same field: the `claude` bundle is `bundle` (the Provider and its kind-aware extractors form a coherent provider); the `core` bundle is `extension` (every kernel built-in is removable per the spec promise that no extension is privileged). Plugin authors should keep the default unless their plugin ships several orthogonal capabilities a user might reasonably want piecemeal."
+        },
         "storage": {
           "type": "object",
           "description": "Persistence mode for this plugin. Absent = plugin does not persist state.",
@@ -44,7 +50,11 @@
               "required": ["mode"],
               "additionalProperties": false,
               "properties": {
-                "mode": { "const": "kv", "description": "Shared `state_plugin_kvs` table, scoped by plugin id." }
+                "mode": { "const": "kv", "description": "Shared `state_plugin_kvs` table, scoped by plugin id." },
+                "schema": {
+                  "type": "string",
+                  "description": "Optional. JSON Schema (path relative to plugin root) that validates the value on every `ctx.store.set(key, value)`. Absent = permissive (no validation, status quo). The kernel AJV-compiles the schema at load time; a missing or unparseable schema file surfaces as `load-error`."
+                }
               }
             },
             {
@@ -53,7 +63,12 @@
               "properties": {
                 "mode": { "const": "dedicated", "description": "Plugin-owned tables, prefixed `plugin_<normalizedId>_`." },
                 "tables": { "type": "array", "minItems": 1, "items": { "type": "string" } },
-                "migrations": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Relative paths to `.sql` migration files." }
+                "migrations": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Relative paths to `.sql` migration files." },
+                "schemas": {
+                  "type": "object",
+                  "description": "Optional. Maps each declared table to a JSON Schema (path relative to plugin root) that validates rows on write. Tables not present here accept any shape (permissive, status quo). The kernel AJV-validates `ctx.store.write(table, row)` against the declared schema and throws on shape violation. A missing or unparseable schema file surfaces as `load-error`.",
+                  "additionalProperties": { "type": "string" }
+                }
               }
             }
           ]
@@ -86,8 +101,8 @@
         "manifest": { "$ref": "#/$defs/PluginManifest" },
         "status": {
           "type": "string",
-          "enum": ["enabled", "disabled", "incompatible-spec", "invalid-manifest", "load-error"],
-          "description": "Resolved state after discovery. `disabled` = user-disabled via config; others = automatic."
+          "enum": ["enabled", "disabled", "incompatible-spec", "invalid-manifest", "load-error", "id-collision"],
+          "description": "Resolved state after discovery. `disabled` = user-disabled via config; `id-collision` = two plugins (any combination of project / global / --plugin-dir) declared the same `id`, both blocked, no precedence; others = automatic."
         },
         "statusReason": {
           "type": ["string", "null"],

package/schemas/project-config.schema.json

@@ -19,9 +19,9 @@
       "type": "string",
       "description": "Name of the offline tokenizer used to compute per-node token counts during scan. Default `cl100k_base`. Stored alongside each token count in `scan_nodes` so consumers know which encoder produced the numbers. Changing this invalidates prior counts on next scan."
     },
-    "adapters": {
+    "providers": {
       "type": "array",
-      "description": "Adapter ids to enable, in priority order when multiple match. Empty/absent = use all registered.",
+      "description": "Provider ids to enable, in priority order when multiple match. Empty/absent = use all registered.",
       "items": { "type": "string" }
     },
     "roots": {

package/schemas/scan-result.schema.json

@@ -37,9 +37,9 @@
       "minItems": 1,
       "items": { "type": "string" }
     },
-    "adapters": {
+    "providers": {
       "type": "array",
-      "description": "Adapter ids that participated in classification. Empty if no adapter matched.",
+      "description": "Provider ids that participated in classification. Empty if no Provider matched.",
       "items": { "type": "string" }
     },
     "nodes": {
@@ -60,7 +60,7 @@
       "additionalProperties": false,
       "properties": {
         "filesWalked": { "type": "integer", "minimum": 0 },
-        "filesSkipped": { "type": "integer", "minimum": 0, "description": "Files walked but not classified by any adapter." },
+        "filesSkipped": { "type": "integer", "minimum": 0, "description": "Files walked but not classified by any Provider." },
         "nodesCount": { "type": "integer", "minimum": 0 },
         "linksCount": { "type": "integer", "minimum": 0 },
         "issuesCount": { "type": "integer", "minimum": 0 },

package/conformance/cases/basic-scan.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
-  "id": "basic-scan",
-  "description": "Scanning the minimal-claude fixture detects exactly five nodes, one per kind, with no issues.",
-  "fixture": "minimal-claude",
-  "invoke": {
-    "verb": "scan",
-    "flags": ["--json"]
-  },
-  "assertions": [
-    { "type": "exit-code", "value": 0 },
-    { "type": "json-path", "path": "$.schemaVersion", "equals": 1 },
-    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 5 },
-    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 0 },
-    { "type": "json-path", "path": "$.nodes.length", "equals": 5 }
-  ]
-}

package/conformance/cases/orphan-detection.json

@@ -1,22 +0,0 @@
-{
-  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
-  "id": "orphan-detection",
-  "description": "Deleting a file with no replacement triggers the orphan branch of the rename heuristic: exactly one issue with ruleId `orphan` is emitted, severity `info`, naming the dead path. The remaining survivor node is reported normally.",
-  "fixture": "orphan-after",
-  "setup": {
-    "priorScans": [
-      { "fixture": "orphan-before" }
-    ]
-  },
-  "invoke": {
-    "verb": "scan",
-    "flags": ["--changed", "--json"]
-  },
-  "assertions": [
-    { "type": "exit-code", "value": 0 },
-    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
-    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 1 },
-    { "type": "json-path", "path": "$.issues[0].ruleId", "equals": "orphan" },
-    { "type": "json-path", "path": "$.issues[0].severity", "equals": "info" }
-  ]
-}

package/conformance/cases/rename-high.json

@@ -1,21 +0,0 @@
-{
-  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
-  "id": "rename-high",
-  "description": "Moving a single file with identical body across the rename triggers a high-confidence auto-rename: NO issue is emitted (per spec/db-schema.md §Rename detection), the new path is the only node in the result, and the rename heuristic operates silently.",
-  "fixture": "rename-high-after",
-  "setup": {
-    "priorScans": [
-      { "fixture": "rename-high-before" }
-    ]
-  },
-  "invoke": {
-    "verb": "scan",
-    "flags": ["--changed", "--json"]
-  },
-  "assertions": [
-    { "type": "exit-code", "value": 0 },
-    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
-    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 0 },
-    { "type": "json-path", "path": "$.nodes[0].path", "equals": "skills/bar.md" }
-  ]
-}

package/conformance/fixtures/minimal-claude/agents/reviewer.md

@@ -1,16 +0,0 @@
----
-name: reviewer-agent
-description: A minimal agent that reviews supplied text for tone, clarity, and grammar.
-model: sonnet
-tools:
-  - Read
-  - Edit
-metadata:
-  version: 1.0.0
-  stability: stable
-  color: blue
----
-
-# Reviewer agent
-
-Reviews supplied text and suggests edits. Does not modify files automatically; returns proposed diffs only.

package/conformance/fixtures/minimal-claude/commands/status.md

@@ -1,17 +0,0 @@
----
-name: status
-description: Prints a one-line project status (branch, dirty flag, ahead/behind).
-args:
-  - name: verbose
-    type: boolean
-    required: false
-    description: Include extra git details.
-metadata:
-  version: 1.0.0
----
-
-# /status command
-
-Prints a concise status line for the current project. Shows the branch name, whether the tree is dirty, and the commit distance from upstream.
-
-With `--verbose`, also lists modified paths.