@skill-map/spec 0.16.0 → 0.18.0

package/plugin-author-guide.md

@@ -681,6 +681,131 @@ Full surface in `@skill-map/testkit/index.ts`.
 
 ---
 
+## Annotation contributions
+
+> **Status.** Ships with spec v0.18.0 (Step 9.6.6). Plugins that want to write first-class fields into a node's co-located `.sm` sidecar declare them in their extension manifest under `annotationContributions`. The kernel validates the contributions at load time, surfaces the runtime catalog via `kernel.getRegisteredAnnotationKeys()` (consumed by the BFF / UI for autocomplete), and treats two plugins claiming the same root-exclusive key as a fatal startup error.
+
+### Manifest shape
+
+`annotationContributions` is an object map keyed by the annotation key the extension wants to own. Each entry declares an inline JSON Schema for the value plus two policy fields:
+
+```js
+// my-plugin/extensions/extractor.js
+export default {
+  id: 'my-extractor',
+  kind: 'extractor',
+  version: '1.0.0',
+  // ...rest of the extractor manifest...
+  annotationContributions: {
+    lastReviewedAt: {
+      schema: { type: 'string', format: 'date-time' },
+      // location and ownership default to 'namespaced' / 'shared'
+    },
+  },
+};
+```
+
+Field-by-field:
+
+| Field        | Type                              | Default        | Meaning                                                                                              |
+|--------------|-----------------------------------|----------------|------------------------------------------------------------------------------------------------------|
+| `schema`     | inline JSON Schema (object)       | required       | Validates the value the extension writes under this key. Compiled with AJV at load time.            |
+| `location`   | `'namespaced'` \| `'root'`        | `'namespaced'` | Where the key lands inside the sidecar (see below).                                                  |
+| `ownership`  | `'shared'` \| `'exclusive'`       | `'shared'`     | Conflict policy. REQUIRED to be `'exclusive'` when `location: 'root'`.                              |
+
+The `schema` field is **inline** — an object literal in the manifest, not a `$ref` to a file. Aligns with how the extractor / rule / action schemas already declare other inline shapes; avoids an extra path-resolution step at load time.
+
+### Namespacing default vs root opt-in
+
+By default a contribution lands inside the plugin's `<plugin-id>:` block at the sidecar root. Two plugins can ship a contribution with the same key and never collide because the runtime path keeps them under separate namespaces:
+
+```yaml
+# .claude/agents/architect.sm
+for:
+  path: .claude/agents/architect.md
+  bodyHash: ...
+  frontmatterHash: ...
+annotations:
+  version: 3
+
+# Plugin 'reviewer' contributes 'lastReviewedAt'
+reviewer:
+  lastReviewedAt: 2026-05-06T10:00:00Z
+
+# Plugin 'auditor' also contributes 'lastReviewedAt' — different namespace, no conflict
+auditor:
+  lastReviewedAt: 2026-05-05T18:30:00Z
+```
+
+Opting into a top-level (root) key requires `location: 'root'` AND `ownership: 'exclusive'`. The pair travels together — a top-level reserved key cannot be silently shared between plugins, because `.sm` writes deep-merge per the `SidecarStore` contract and a shared root key would route non-deterministically. Use root sparingly: for every plugin that contributes a root key, the kernel reserves that name across the whole installed-plugin surface.
+
+```js
+// compliance-plugin/extensions/rule.js
+export default {
+  id: 'compliance-checker',
+  kind: 'rule',
+  // ...
+  annotationContributions: {
+    compliance: {
+      schema: {
+        type: 'object',
+        required: ['audit'],
+        properties: {
+          audit: { type: 'string' },
+          dueAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      location: 'root',
+      ownership: 'exclusive',
+    },
+  },
+};
+```
+
+The resulting sidecar block:
+
+```yaml
+# .claude/agents/architect.sm
+for: { path: ..., bodyHash: ..., frontmatterHash: ... }
+compliance:
+  audit: sox-2026
+  dueAt: 2026-12-31T23:59:59Z
+```
+
+### Ownership rules
+
+- `shared` (default) — multiple plugins MAY write the same key. Every plugin gets its own namespaced block; `last-write-wins` is per-`(plugin, key)` tuple inside `FilesystemSidecarStore.applyPatch`. Two plugins on the SAME namespaced key from the same plugin id is structurally impossible (one extension per kind per plugin id by spec), so the only collision surface is intra-extension.
+- `exclusive` — only this plugin may write the key. The kernel rejects any other plugin that tries to claim the same `(key, location: 'root')` tuple as `exclusive`. `exclusive` + `namespaced` is permitted but redundant in practice (the namespace already isolates by plugin id); use it as documentation when you want the manifest to scream "no other plugin should ever write this".
+
+### Collision behaviour — hard fail, no boot
+
+Two plugins claiming the same `(key, location: 'root', ownership: 'exclusive')` tuple is a **fatal startup error**. The kernel does NOT boot in this state — `loadPluginRuntime` throws `AnnotationContributionConflictError` and the host (CLI verb, BFF, watch mode) propagates the error and exits non-zero with a clear stderr message naming both offenders. Stricter than the default per-plugin `invalid-manifest` "disable just that plugin" path: annotation-namespace conflicts are non-recoverable because annotated `.sm` files would otherwise become non-deterministically routed.
+
+This is the only fatal path on the plugin-load surface. Every other failure mode (manifest invalid, schema invalid, dynamic-import failure, id collision) is per-plugin and the kernel keeps booting on the survivors.
+
+### Tier-1 typo guard (`core/unknown-field`)
+
+The built-in `core/unknown-field` Rule walks every parsed `.sm` and emits a `warn` issue per truly-unknown key. Three surfaces are checked:
+
+1. Inside `annotations:` — keys not in `annotations.schema.json`'s curated catalog (the ~25 conventional fields). Plugins do NOT contribute to `annotations:`; that block is skill-map-curated.
+2. At the sidecar root — keys outside the four reserved blocks (`for`, `annotations`, `settings`, `audit`) that are also NOT a registered plugin namespace `<plugin-id>:` AND NOT a registered `location: 'root'` contribution.
+3. Inside a registered `<plugin-id>:` namespace — values that fail the schema declared by the owning plugin's `annotationContributions[<key>].schema`.
+
+The rule never blocks a scan; advisories surface through the standard issue channel (CLI, UI, REST). When you ship a contribution, the loader compiles your inline schema, the runtime catalog publishes it, and `core/unknown-field` automatically validates user writes against your declaration.
+
+### Runtime catalog accessor
+
+Once every plugin has loaded, the runtime catalog is reachable via `kernel.getRegisteredAnnotationKeys()`:
+
+```ts
+// Each entry: { pluginId, key, location, ownership, schema }
+const keys = kernel.getRegisteredAnnotationKeys();
+```
+
+Pure read; no side effects. Built-in catalog fields from `annotations.schema.json` are NOT included — this catalog is plugin-only. The UI knows the built-in catalog separately via the schema bundle. The (future) BFF endpoint surfaces this through `GET /api/annotations/catalog` for autocomplete.
+
+---
+
 ## See also
 
 - [`architecture.md`](./architecture.md) — extension contract, ports, execution modes.

package/schemas/annotations.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/annotations.schema.json",
+  "title": "Annotations",
+  "description": "Catalog of conventional annotation fields skill-map ships out of the box, written into the `annotations:` block of a sidecar (`<basename>.sm`). Every field is OPTIONAL — a sidecar with an empty `annotations: {}` is valid. Schema is `additionalProperties: true` so users / plugins can add custom keys without coordination; the built-in `unknown-field` rule emits a warning on unrecognized keys (typo guard). The curated catalog is the load-bearing 14 fields below — versioning + supersession (`version`, `stability`, `supersedes`, `supersededBy`, `requires`, `conflictsWith`, `related`), provenance (`authors`, `license`, `source`, `sourceVersion`), taxonomy (`tags`), display (`hidden`), docs (`docsUrl`). The activity timestamp lives in the reserved `audit:` block (`audit.lastBumpedAt`), not in `annotations:`. Plugins that want first-class custom keys with their own validation declare `annotationContributions` in their manifest (see Step 9.6.6).",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonic counter. Bumped via the built-in `bump` Action when the underlying node changes meaningfully. Orthogonal to `stability` — `stability` carries the lifecycle stage; `version` is just a counter. There is no major: a change so big it would justify a major bump uses the convention `create a new node, supersede the old one` instead. Default: missing == unversioned."
+    },
+    "stability": {
+      "type": "string",
+      "enum": ["experimental", "stable", "deprecated"],
+      "description": "Lifecycle stage. Denormalized into `scan_nodes.stability` for fast queries (see `node.schema.json` #/properties/stability). Default: missing == unspecified."
+    },
+    "supersedes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of nodes this node replaces. Consumed by the built-in `superseded` rule and surfaces in `sm list --superseded`."
+    },
+    "supersededBy": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path (relative to scope root) of the node that replaces this one. When set, the current node is end-of-life and consumers should migrate."
+    },
+    "requires": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of nodes this node depends on. Surfaces in the dependency graph; the `broken-ref` rule flags missing targets."
+    },
+    "conflictsWith": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of nodes that cannot be active alongside this one. Surfaces in conflict detection (post-v0.5.0)."
+    },
+    "related": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of conceptually related nodes. Soft link for navigation; no strong semantics, no rule enforcement."
+    },
+    "authors": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Multi-author list. Single-author files use a one-element array."
+    },
+    "license": {
+      "type": "string",
+      "minLength": 1,
+      "description": "SPDX identifier preferred (e.g. `MIT`, `Apache-2.0`); free-form accepted."
+    },
+    "source": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the canonical upstream (e.g. GitHub raw URL). Consumed by the `github-enrichment` Action for hash verification."
+    },
+    "sourceVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Tag, branch, or full commit SHA at the upstream. Drives `github-enrichment` SHA pin / tag resolution."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Free-form taxonomy tags. Consumed by `sm list --tag <name>` and UI faceted search."
+    },
+    "hidden": {
+      "type": "boolean",
+      "description": "When true, the node is excluded from default listings (still appears under `--all` / `--include-hidden`). Useful for in-progress nodes the author does not want surfaced yet."
+    },
+    "docsUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical docs URL for this node (separate from `source`, which points at the file's upstream)."
+    }
+  }
+}

package/schemas/api/rest-envelope.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/api/rest-envelope.schema.json",
   "title": "RestEnvelope",
-  "description": "Wrapper shape for REST responses under `/api/*` (Step 14.2). Three variants distinguished by the `kind` discriminator and which payload field is present (`items` for list kinds, `item` for single-resource kinds, `value` for `kind: 'config'`). The `/api/scan` and `/api/health` responses are exempt — they carry the underlying `ScanResult` / `IHealthResponse` shape directly. The `/api/graph` response is also exempt — it returns the formatter's native textual output (text/plain or text/markdown). Step 14.5.d adds the required `kindRegistry` field on every payload-bearing variant so the UI can render Provider-declared kinds (label, color, icon) without hardcoding visuals; sentinel kinds (`health`, `scan`, `graph`) stay exempt because they don't carry an envelope payload. The change keeps `schemaVersion` at `'1'` — the BFF is greenfield (no released consumers run against `'1'` without `kindRegistry`), so a versioned migration buys nothing.",
+  "description": "Wrapper shape for REST responses under `/api/*` (Step 14.2). Five variants distinguished by the `kind` discriminator and which payload field is present (`items` for list kinds AND `'annotations.registered'`, `item` for single-resource kinds, `value` for `kind: 'config'` and `'sidecar.bumped'`). The `/api/scan` and `/api/health` responses are exempt — they carry the underlying `ScanResult` / `IHealthResponse` shape directly. The `/api/graph` response is also exempt — it returns the formatter's native textual output (text/plain or text/markdown). Step 14.5.d adds the required `kindRegistry` field on every payload-bearing list / single / config variant so the UI can render Provider-declared kinds (label, color, icon) without hardcoding visuals; sentinel kinds (`health`, `scan`, `graph`) stay exempt because they don't carry an envelope payload. Step 9.6 closes the `'sidecar.bumped'` (R7) and `'annotations.registered'` (R7) gaps — both are payload-bearing but carry their own variant shapes (sidecar.bumped: `value` + `elapsedMs`, no `filters`/`counts`/`kindRegistry`; annotations.registered: `items` + `counts.total`, no `filters`/`kindRegistry`) because they project read-only kernel surfaces orthogonal to the kindRegistry. The change keeps `schemaVersion` at `'1'` — the BFF is greenfield (no released consumers depend on the prior shape), so a versioned migration buys nothing.",
   "type": "object",
   "required": ["schemaVersion", "kind"],
   "properties": {
@@ -13,8 +13,20 @@
     },
     "kind": {
       "type": "string",
-      "enum": ["nodes", "links", "issues", "plugins", "config", "graph", "node", "health", "scan"],
-      "description": "Discriminator. List kinds (`nodes`, `links`, `issues`, `plugins`) carry `items`. The `node` kind carries `item`. The `config` kind carries `value`. The `health` / `scan` / `graph` values are reserved for documentation parity with the routes that DON'T use this envelope."
+      "enum": [
+        "nodes",
+        "links",
+        "issues",
+        "plugins",
+        "config",
+        "graph",
+        "node",
+        "health",
+        "scan",
+        "sidecar.bumped",
+        "annotations.registered"
+      ],
+      "description": "Discriminator. List kinds (`nodes`, `links`, `issues`, `plugins`) carry `items` + `filters` + `counts` + `kindRegistry`. The `node` kind carries `item` + `kindRegistry`. The `config` kind carries `value` + `kindRegistry`. The `sidecar.bumped` kind (Step 9.6.5, BFF half) carries `value` + `elapsedMs` (no `filters` / `counts` / `kindRegistry` — it's an action-result projection orthogonal to the kindRegistry surface). The `annotations.registered` kind (Step 9.6.6, BFF half) carries `items` + `counts.total` (no `filters` / `kindRegistry` — pure read-only catalog projection). The `health` / `scan` / `graph` values are reserved for documentation parity with the routes that DON'T use this envelope."
     },
     "items": {
       "type": "array",
@@ -26,7 +38,12 @@
     },
     "value": {
       "type": "object",
-      "description": "Present when `kind` is `'config'`. Carries the merged effective config object."
+      "description": "Present when `kind` is `'config'` or `'sidecar.bumped'`. For `'config'`, carries the merged effective config object. For `'sidecar.bumped'`, carries `{ nodePath, version, status }` (the Action-result payload from `POST /api/sidecar/bump`)."
+    },
+    "elapsedMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Wall-clock milliseconds the BFF spent serving the request. Present on action-result envelopes (`kind: 'sidecar.bumped'`); absent elsewhere."
     },
     "filters": {
       "type": "object",
@@ -34,49 +51,61 @@
     },
     "kindRegistry": {
       "type": "object",
-      "description": "Catalog of node kinds active in the current scope, keyed by kind name. Built once per server boot from every enabled Provider's `kinds` map and embedded into every payload-bearing envelope so the UI can render kind tags / palette swatches / graph nodes against Provider-declared visuals (label, color, icon) without ever hardcoding a closed kind enum. Sentinel envelopes (`health`, `scan`, `graph`) are exempt.",
+      "description": "Catalog of node kinds active in the current scope, keyed by kind name. Built once per server boot from every enabled Provider's `kinds` map and embedded into every payload-bearing envelope so the UI can render kind tags / palette swatches / graph nodes against Provider-declared visuals (label, color, icon) without ever hardcoding a closed kind enum. Sentinel envelopes (`health`, `scan`, `graph`) are exempt. Each entry MAY carry contributions from multiple Providers when several declare the same kind name (e.g. Claude `agent` and Gemini `agent`); the `providers` map keeps every contribution and `primaryProviderId` points at the one whose visuals drive the kind's primary CSS var. The kernel separately surfaces `provider-ambiguous` issues for files matched by more than one Provider; the UI may still receive the merged registry during the conflict window.",
       "additionalProperties": {
         "type": "object",
-        "required": ["providerId", "label", "color"],
+        "required": ["primaryProviderId", "providers"],
         "additionalProperties": false,
         "properties": {
-          "providerId": {
+          "primaryProviderId": {
             "type": "string",
             "minLength": 1,
-            "description": "Id of the Provider that contributed this kind. Lets the UI scope kind ownership and disambiguate when two Providers happen to declare the same kind name (kernel surfaces this as `provider-ambiguous` but the UI may still receive the merged registry during the conflict window)."
+            "description": "Id of the Provider whose visuals drive the kind's primary CSS var (`--sm-kind-<kind>`). Set on first registration (first Provider in iteration order); subsequent contributors append to `providers` without overwriting the primary."
           },
-          "label": { "type": "string", "minLength": 1 },
-          "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
-          "colorDark": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
-          "emoji": { "type": "string", "minLength": 1, "maxLength": 8 },
-          "icon": {
-            "oneOf": [
-              {
-                "type": "object",
-                "required": ["kind", "id"],
-                "additionalProperties": false,
-                "properties": {
-                  "kind": { "const": "pi" },
-                  "id": { "type": "string", "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$" }
-                }
-              },
-              {
-                "type": "object",
-                "required": ["kind", "path"],
-                "additionalProperties": false,
-                "properties": {
-                  "kind": { "const": "svg" },
-                  "path": { "type": "string", "minLength": 1 }
+          "providers": {
+            "type": "object",
+            "minProperties": 1,
+            "description": "Per-provider visuals for this kind name. Keyed by Provider id (e.g. `'claude'`, `'gemini'`). Lets the UI render a node painted with its own Provider's color via `entry.providers[node.provider]` when the kind name is shared across Providers.",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["label", "color"],
+              "additionalProperties": false,
+              "properties": {
+                "label": { "type": "string", "minLength": 1 },
+                "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                "colorDark": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                "emoji": { "type": "string", "minLength": 1, "maxLength": 8 },
+                "icon": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "required": ["kind", "id"],
+                      "additionalProperties": false,
+                      "properties": {
+                        "kind": { "const": "pi" },
+                        "id": { "type": "string", "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$" }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "required": ["kind", "path"],
+                      "additionalProperties": false,
+                      "properties": {
+                        "kind": { "const": "svg" },
+                        "path": { "type": "string", "minLength": 1 }
+                      }
+                    }
+                  ]
                 }
               }
-            ]
+            }
           }
         }
       }
     },
     "counts": {
       "type": "object",
-      "required": ["total", "returned"],
+      "required": ["total"],
       "properties": {
         "total": {
           "type": "integer",
@@ -86,7 +115,7 @@
         "returned": {
           "type": "integer",
           "minimum": 0,
-          "description": "Rows actually carried in `items` (≤ `limit`)."
+          "description": "Rows actually carried in `items` (≤ `limit`). Present on list-kind envelopes (`nodes`, `links`, `issues`, `plugins`); absent on `'annotations.registered'` (no pagination, no filters — the catalog ships in its entirety in every response)."
         },
         "page": {
           "type": "object",
@@ -108,25 +137,27 @@
         }
       },
       "additionalProperties": false,
-      "description": "Tally + paging info. Present on every list / single envelope; absent on `health` / `scan` / `graph` responses (which don't use this envelope)."
+      "description": "Tally + paging info. Present on every list / single envelope; absent on `health` / `scan` / `graph` responses (which don't use this envelope). The list variants additionally require `returned`; the `'annotations.registered'` variant only requires `total`."
     }
   },
   "oneOf": [
     {
-      "description": "List envelope — `items` payload + `counts` + `kindRegistry`.",
+      "description": "List envelope — `items` payload + `filters` + `counts` (with `returned`) + `kindRegistry`. Used by `/api/nodes`, `/api/links`, `/api/issues`, `/api/plugins`.",
       "required": ["items", "counts", "filters", "kindRegistry"],
       "properties": {
-        "kind": { "enum": ["nodes", "links", "issues", "plugins"] }
+        "kind": { "enum": ["nodes", "links", "issues", "plugins"] },
+        "counts": { "required": ["total", "returned"] }
       },
       "not": {
         "anyOf": [
           { "required": ["item"] },
-          { "required": ["value"] }
+          { "required": ["value"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     },
     {
-      "description": "Single-resource envelope — `item` payload + `kindRegistry`, no `counts` / `filters`.",
+      "description": "Single-resource envelope — `item` payload + `kindRegistry`, no `counts` / `filters`. Used by `/api/nodes/:pathB64`.",
       "required": ["item", "kindRegistry"],
       "properties": {
         "kind": { "const": "node" }
@@ -134,12 +165,13 @@
       "not": {
         "anyOf": [
           { "required": ["items"] },
-          { "required": ["value"] }
+          { "required": ["value"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     },
     {
-      "description": "Value envelope — `value` payload + `kindRegistry`, no `counts` / `filters`.",
+      "description": "Value envelope — `value` payload + `kindRegistry`, no `counts` / `filters`. Used by `/api/config`.",
       "required": ["value", "kindRegistry"],
       "properties": {
         "kind": { "const": "config" }
@@ -147,7 +179,43 @@
       "not": {
         "anyOf": [
           { "required": ["items"] },
-          { "required": ["item"] }
+          { "required": ["item"] },
+          { "required": ["elapsedMs"] }
+        ]
+      }
+    },
+    {
+      "description": "Action-result envelope — `value` + `elapsedMs` siblings, no `filters` / `counts` / `kindRegistry`. Used by `POST /api/sidecar/bump` (Step 9.6.5, BFF half) where the response carries the bump report (`{ nodePath, version, status }`) plus the wall-clock duration. The kindRegistry is intentionally absent — the action result is orthogonal to the kind catalog and the SPA already has it cached from a prior list call.",
+      "required": ["value", "elapsedMs"],
+      "properties": {
+        "kind": { "const": "sidecar.bumped" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["item"] },
+          { "required": ["filters"] },
+          { "required": ["counts"] },
+          { "required": ["kindRegistry"] }
+        ]
+      }
+    },
+    {
+      "description": "Catalog envelope — `items` + `counts.total` only, no `filters` / `kindRegistry` / `returned`. Used by `GET /api/annotations/registered` (Step 9.6.6, BFF half). The catalog is small (typically 0–50 entries), ships in its entirety on every response, and does not paginate; `counts.total` doubles as `items.length`.",
+      "required": ["items", "counts"],
+      "properties": {
+        "kind": { "const": "annotations.registered" },
+        "counts": {
+          "not": { "required": ["returned"] }
+        }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["item"] },
+          { "required": ["value"] },
+          { "required": ["filters"] },
+          { "required": ["kindRegistry"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     },
@@ -161,7 +229,8 @@
           { "required": ["items"] },
           { "required": ["item"] },
           { "required": ["value"] },
-          { "required": ["kindRegistry"] }
+          { "required": ["kindRegistry"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     }

package/schemas/bump-report.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/bump-report.schema.json",
+  "title": "BumpReport",
+  "description": "Report shape produced by the built-in deterministic `bump` Action (Step 9.6.3, Decision #125). Extends `report-base-deterministic.schema.json` (the deterministic counterpart to `report-base.schema.json`, which carries the LLM-only `confidence` + `safety` fields). The bump Action returns one of three concrete shapes, distinguished by `ok` / `noop` / `reason`: success-with-write (`{ ok: true, version }`), silent-no-op under `force` (`{ ok: true, noop: true }`), or refusal (`{ ok: false, reason: 'fresh' }`).",
+  "allOf": [{ "$ref": "report-base-deterministic.schema.json" }],
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "noop": {
+      "type": "boolean",
+      "description": "True when the Action accepted the request but did not produce a write (the node was already fresh and `force: true` opted into the silent no-op path). Mutually exclusive with `version`."
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["fresh"],
+      "description": "Refusal reason, present only when `ok: false`. `fresh` = the node has no drift versus its sidecar and the caller did not pass `force: true`."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The new `annotations.version` value the Action wrote. Present only when `ok: true` and `noop` is absent."
+    },
+    "createdSidecar": {
+      "type": "boolean",
+      "description": "True when this bump created the `.sm` file (no sidecar existed on disk before). Triggers the `audit.createdAt` / `audit.createdBy` fill-in."
+    }
+  }
+}

package/schemas/extensions/base.schema.json

@@ -38,6 +38,31 @@
     "entry": {
       "type": "string",
       "description": "Optional path to the module exporting this extension (relative to the plugin root). Absent → the kernel uses the path listed in the plugin manifest's `extensions[]` array."
+    },
+    "annotationContributions": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["schema"],
+        "additionalProperties": false,
+        "properties": {
+          "schema": {
+            "type": "object",
+            "description": "Inline JSON Schema for this contribution's value. Validated when the kernel routes a sidecar write through the extension's namespace (or root key, see `location`). Must be a valid JSON Schema document; an invalid `schema` rejects the extension at load with `invalid-manifest`."
+          },
+          "ownership": {
+            "enum": ["exclusive", "shared"],
+            "default": "shared",
+            "description": "Conflict policy for this key. `shared` (default) — the key is namespaced by default; multiple plugins MAY contribute to the same key, last-write-wins per the SidecarStore's deep-merge semantics. `exclusive` — only this plugin may write the key. REQUIRED when `location: 'root'` (a top-level reserved key cannot be silently shared between plugins)."
+          },
+          "location": {
+            "enum": ["namespaced", "root"],
+            "default": "namespaced",
+            "description": "Where the key lands inside the sidecar. `namespaced` (default) — written under the plugin's `<plugin-id>:` block at the sidecar root. `root` — written as a top-level key alongside the reserved blocks (`for`, `annotations`, `settings`, `audit`); requires `ownership: 'exclusive'` and is treated as elevated trust (two plugins claiming the same root key with `exclusive` is a hard-fail at orchestrator init). See `plugin-author-guide.md` §Annotation contributions."
+          }
+        }
+      },
+      "description": "Plugin-contributed annotation keys. Each entry declares an inline JSON Schema for the value the extension writes into a sidecar. Keys default to the plugin's `<plugin-id>:` namespace; opt-in to top-level via `location: 'root'` (requires `ownership: 'exclusive'`). The kernel exposes the runtime catalog via `kernel.getRegisteredAnnotationKeys()` for UI autocomplete; the built-in `core/unknown-field` Rule emits a warning on truly unrecognized keys (typo guard). See `plugin-author-guide.md` §Annotation contributions for the worked examples."
     }
   }
 }

package/schemas/extensions/provider.schema.json

@@ -21,6 +21,28 @@
       "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" }
     },
+    "read": {
+      "type": "object",
+      "required": ["extensions", "parser"],
+      "additionalProperties": false,
+      "description": "Declarative file-discovery config consumed by the kernel walker. When present, the kernel walks every root, includes files whose extension matches `extensions`, parses each with the parser registered as `parser`, and yields raw nodes the orchestrator consumes. When absent, the kernel applies the default `{ extensions: ['.md'], parser: 'frontmatter-yaml' }` so the most common Provider shape needs no configuration. When a Provider also declares the runtime `walk()` method (TypeScript-only — never appears in this manifest), `walk()` wins and `read` is ignored: the runtime field is the escape hatch for Providers with non-standard discovery requirements. Built-in parsers ship with the kernel (`frontmatter-yaml`, `plain`); the set is closed by design and user plugins cannot register their own.",
+      "properties": {
+        "extensions": {
+          "type": "array",
+          "minItems": 1,
+          "description": "File extensions the walker yields. Strings include the leading dot. Lowercase-only by convention — match is case-sensitive and Providers MUST list every casing they want recognised.",
+          "items": {
+            "type": "string",
+            "pattern": "^\\.[a-z0-9]+$"
+          }
+        },
+        "parser": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identifier of a parser registered in the kernel-internal registry. Built-ins: `frontmatter-yaml` (markdown with `--- … ---` YAML frontmatter, prototype-pollution-safe, `js-yaml` JSON_SCHEMA-pinned), `plain` (entire body, empty frontmatter — for files carrying no frontmatter convention; the Provider derives `name` from the path inside `classify()`). Unknown ids surface as `UnknownParserError` from the walker; the orchestrator translates the error into a Provider issue with status `invalid-manifest`."
+        }
+      }
+    },
     "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`).",