@skill-map/spec 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,239 @@
 # Spec changelog
 
+## 0.28.0
+
+### Minor Changes
+
+- e21216e: Simplify plugin manifest fields beyond the file-layout refactor. The
+  previous `structure-as-truth-plugins` changeset moved bundle / kind /
+  id discovery onto the filesystem; this one extends the same principle
+  into the manifest schemas themselves so the only fields that survive
+  are the ones the kernel cannot derive from disk.
+
+  **Plugin manifest (`plugin.json`):**
+
+  - Drop `id` (the directory name is the id; AJV rejects manifests that
+    declare it).
+  - `description` and `catalogCompat` are now required (were optional).
+  - `granularity` is now optional with a default of `'extension'` (was
+    required). Most plugins drop the field entirely.
+  - Drop `settings` at the plugin level; settings move to the extension
+    manifests that actually consume them.
+
+  **Extension base (every kind):**
+
+  - Drop `id`, `kind`, `stability`, `preconditions` (free-form). The
+    loader injects `id` / `kind` / `pluginId` from the folder layout;
+    the other two were display-only and free-form respectively, and
+    the kernel never consumed them.
+  - `description` is now required.
+  - Rename `annotationContributions` (map) to `annotation` (singular):
+    one extension contributes at most one annotation key, and the key
+    is the extension's folder name. Use multiple extensions to
+    contribute multiple keys.
+  - Rename `viewContributions` to `ui` on the manifest. The
+    runtime-aggregated catalog (`Kernel.getRegisteredViewContributions()`,
+    `IPluginRuntimeBundle.viewContributions`) keeps its name.
+  - Add `settings: Record<id, ISettingDeclaration>` (moved from the
+    plugin manifest).
+
+  **Provider:**
+
+  - Drop the inline `kinds` map. The kind catalog now lives under
+    `<plugin>/kinds/<kindName>/` with two files per kind:
+    `schema.json` (frontmatter schema) and `kind.json` carrying the
+    `{ ui }` block. The loader walks the directory and projects each
+    entry into the runtime `kinds` descriptor.
+  - New schema `extensions/provider-kind.schema.json` validates the
+    `kind.json` shape.
+  - Drop `defaultRefreshAction`. The UI's `🧠 prob` refresh button is
+    retired; a replacement UX is TBD.
+  - `roots` is enforcement-grade: a Provider with declared `roots`
+    only sees files matching at least one glob; a Provider without
+    `roots` acts as the fallback for files unmatched by any other
+    Provider. Supported patterns: `prefix/**` (deep), `prefix/*`
+    (shallow), exact path. Two Providers whose roots both match the
+    same file produce `provider-ambiguous` (already in spec) and the
+    file stays unclassified.
+
+  **Extractor:**
+
+  - Drop `emitsLinkKinds` (the global closed enum of link kinds is the
+    contract; off-enum emissions drop with `extension.error`).
+  - Drop `defaultConfidence` (declare confidence per-emit on
+    `ctx.emitLink({ ..., confidence })`).
+  - Drop `applicableKinds` (array). Use `precondition.kind` instead with
+    qualified ids like `'claude/agent'`. The same `precondition` shape
+    is shared with Analyzer and Action.
+
+  **Analyzer:**
+
+  - Drop `emitsAnalyzerIds` (the qualified extension id is the default
+    `analyzer_id`).
+  - Drop `defaultSeverity` (declare severity per-emit on
+    `ctx.emitIssue({ ..., severity })`).
+  - Drop `consumes`, `configurable`, `recommendedActions`. The
+    analyzer↔action relationship is now declared from the Action side
+    via `precondition.analyzerIds` (Modelo B): one Action says "I
+    resolve these analyzer findings", instead of one Analyzer saying
+    "these actions help".
+  - Add `precondition: { kind?, provider? }` (same shape as Extractor).
+
+  **Action:**
+
+  - Drop `reportSchemaRef` and `promptTemplateRef`. The kernel now
+    resolves these by convention from the action folder:
+    `<action-dir>/report.schema.json` (always required) and
+    `<action-dir>/prompt.md` (required when `mode='probabilistic'`,
+    forbidden when `mode='deterministic'`).
+  - Drop `expectedTools`, `fanOutPolicy`, `precondition.stability`,
+    `precondition.custom`.
+  - Add `precondition.analyzerIds` (Modelo B).
+  - Rename `expectedDurationSeconds` to `probExpectedDurationSeconds`
+    to mark it as probabilistic-only via the `prob*` prefix convention.
+  - `mode` is now optional with default `'deterministic'` (was
+    required).
+
+  **Formatter:**
+
+  - Drop `formatId` (comes from the folder name; the loader injects it
+    into the runtime instance).
+  - Drop `supportsFilter` (every formatter supports `--filter`).
+
+  **Hook:**
+
+  - Drop `mode`. Hooks are deterministic-only; LLM-dependent reactions
+    are modeled as a deterministic hook that enqueues a probabilistic
+    Action via `ctx.queue('<plugin>/<action>', payload)`.
+
+  **Loader changes (`src/kernel/adapters/plugin-loader/`):**
+
+  - The exported manifest is stripped of any `id` / `kind` / `pluginId`
+    / `kinds` / `formatId` keys before AJV validation; the loader
+    injects the canonical values from the folder layout. Legacy
+    manifests that still inline these fields load cleanly.
+  - New `discoverProviderKinds(...)` reads `<plugin>/kinds/<k>/{schema.json,
+kind.json}` and merges the result into the runtime Provider
+    instance. Failure modes: missing or unparseable `schema.json`
+    → `load-error`; missing, unparseable, or AJV-invalid `kind.json`
+    → `invalid-manifest`.
+  - New `validateActionFileConventions(...)` enforces the
+    `report.schema.json` / `prompt.md` conventions.
+  - New `matchesAnyRoot(...)` powers Provider `roots` enforcement
+    inside `processRawNode`.
+
+  **Spec docs:**
+
+  - `architecture.md` §Extension kinds table, §Provider · `kinds`
+    catalog, §View contribution system updated.
+  - `plugin-author-guide.md` §Manifest section rewritten (id from
+    folder; description/catalogCompat required), §Extractor section
+    reworked around `precondition.kind`, drop guidance for
+    `emitsLinkKinds` / `defaultConfidence`.
+  - `view-slots.md` references `ui` map.
+
+  **Built-ins migration:**
+
+  - `core/bump/report.schema.json` and `core/mark-superseded/report.schema.json`
+    added (file conventions).
+  - `core/tools-count` extractor uses
+    `precondition: { kind: ['claude/agent'] }`.
+  - All built-in extensions drop `stability`, `preconditions`,
+    `emitsLinkKinds`, `defaultConfidence`, `emitsAnalyzerIds`,
+    `defaultSeverity`, `consumes`, `configurable`, `recommendedActions`,
+    `defaultRefreshAction`, `formatId` (formatter), `supportsFilter`,
+    `mode` (hook).
+  - `scripts/generate-built-ins.js` updated: `id` from bundle folder,
+    `granularity ?? 'extension'`, `toExtensionRow` drops the retired
+    display fields.
+
+  **Testkit:**
+
+  - `makeExtractorContext` populates `settings: {}` so test fixtures
+    satisfy the new required field on `IExtractorContext`.
+
+  ## User-facing
+
+  **Plugin manifests are smaller.** `plugin.json` drops `id`; every extension declares only `version` + `description` plus kind-specific fields. View contributions move to `ui:`. Provider kinds live under `kinds/<kindName>/`. Run `sm plugins doctor` after upgrading.
+
+- 8b7abbf: Structure-as-truth refactor for plugin extensions. The filesystem
+  layout (rather than declarative manifest fields) is now the single
+  source of truth for bundle / kind / extension id.
+
+  **Schema changes:**
+
+  - `PluginManifest` drops the required `extensions: string[]` array;
+    the kernel now auto-discovers extensions by walking
+    `<plugin-dir>/<kind>s/<name>/index.{js,mjs,ts}` for each known
+    kind. `granularity` is now required (no implicit default).
+  - `ExtensionBase` drops the `entry` field (it was an override for
+    the now-gone `extensions[]` path; the loader computes the entry
+    path from the discovered file).
+  - `viewContributions` moves from `base.schema.json` to
+    `extractor.schema.json` and `analyzer.schema.json`. Runtime
+    `ctx.emitContribution` only exists for those two kinds; declaring
+    view contributions on other kinds used to be a silent no-op and
+    is now rejected at manifest load.
+
+  **Loader changes:**
+
+  - `<plugin-dir>/<kind>s/<name>/` is the unit of discovery; the
+    loader walks `providers`, `extractors`, `analyzers`, `actions`,
+    `formatters`, `hooks` in canonical order, looking for an
+    `index.{js,mjs,ts}` inside each name directory.
+  - A manifest whose `kind` disagrees with the folder it lives under
+    (e.g. an `extractor` placed under `analyzers/`) is rejected as
+    `invalid-manifest` with a directed reason.
+  - Containment is enforced by construction: the loader never reads
+    paths the manifest could redirect, so `..`-escape and
+    absolute-path lanes are closed without runtime checks.
+
+  **Built-ins reorganization:**
+
+  - Source tree renamed `src/built-in-plugins/` → `src/plugins/` and
+    reorganized to `src/plugins/<bundle>/<kind>s/<name>/index.ts`.
+    Each bundle (`core`, `claude`, `gemini`, `agent-skills`) gains a
+    `plugin.json` with its metadata.
+  - `src/plugins/built-ins.ts` is now generated by
+    `scripts/generate-built-ins.js` (runs as `prebuild`, checked for
+    drift by `built-ins:check` in CI). The generator walks the
+    filesystem, reads each bundle's `plugin.json`, and emits static
+    imports + the legacy API surface (`builtIns()`,
+    `listBuiltIns()`, `builtInBundles`).
+
+  **Scaffolder (`sm plugins create`):**
+
+  - Emits the new layout: `extractors/<plugin-id>-extractor/index.js`
+    plus a `plugin.json` without `extensions` and without
+    `pluginId` on the extension export (the loader injects it from
+    `plugin.json#/id`). The legacy `mode: 'deterministic'` field on
+    the extractor stub was a no-op holdover from when extractors had
+    a mode and has been removed.
+
+  **Per-extension co-located files convention:**
+
+  Files that share the extension's folder with `index.{js,mjs,ts}`
+  are author-owned siblings. Two blessed names so consumers know
+  where to look:
+
+  - `text.ts` for externalised user-facing strings (one per
+    extension, imported by `index.ts` as `./text.js`).
+  - `<extension-name>.test.{ts,mjs,js}` for the colocated test
+    suite (picked up by the workspace's `plugins/**/*.test.ts`
+    glob).
+
+  Both are optional; the loader ignores anything that is not
+  `index.{js,mjs,ts}`, so future schemas / fixtures / conformance
+  scopes can live next to the code without manifest plumbing. The
+  in-tree built-ins under `src/plugins/` were migrated to this
+  shape: each analyzer's user-facing strings now live at
+  `<bundle>/analyzers/<name>/text.ts` instead of a centralised
+  `i18n/` directory.
+
+  ## User-facing
+
+  **Plugin layout changed.** Extensions now live at `<kind>s/<name>/index.js` (e.g. `extractors/keyword-counter/index.js`); `plugin.json` no longer lists `extensions[]` and requires `granularity`. Run `sm plugins doctor` after migrating, or use `sm plugins create` for new plugins.
+
 ## 0.27.0
 
 ### Minor Changes

package/architecture.md

@@ -173,12 +173,12 @@ Six kinds, all first-class, all loaded through the same registry. Each kind has
 
 | Kind | Role | Input | Output |
 |---|---|---|---|
-| **Provider** | Recognizes a platform. Declares the catalog of node `kind`s it emits via the `kinds` map; each map entry pairs the kind's frontmatter schema (path relative to the Provider's package directory) with its `defaultRefreshAction` (a qualified action id that drives the probabilistic-refresh surface). The Provider's walker hardcodes the paths it scans within the project (e.g. `.claude/`, `.gemini/`); it does NOT extend the scan into the user's HOME. Deterministic-only. | Filesystem walk results, candidate path. | `{ kind, provider } \| null`. |
-| **Extractor** | Extracts signals from a node body. Deterministic-only: runs synchronously inside `sm scan`. Output flows through three context callbacks (no return value): `ctx.emitLink(link)` for the kernel's `links` table, `ctx.enrichNode(partial)` for the kernel's enrichment layer (separate from the author's frontmatter), `ctx.store` for the plugin's own KV / dedicated tables. | Parsed node (frontmatter + body) + callbacks. | `void` (output via callbacks). |
-| **Analyzer** | Evaluates the graph. Dual-mode: `deterministic` runs in `sm check`, `probabilistic` runs in jobs. | Full graph (nodes + links). | `Issue[]`. |
-| **Action** | Operates on one or more nodes. Dual-mode: `deterministic` (in-process code) or `probabilistic` (rendered prompt the runner executes). | Node(s), optional args. | Deterministic: report JSON. Probabilistic: rendered prompt that a runner executes. |
-| **Formatter** | Serializes the graph. Deterministic-only. | Graph + optional filter. | String (ASCII / Mermaid / DOT / JSON / user-defined). |
-| **Hook** | Reacts declaratively to one of ten curated lifecycle events, eight pipeline-driven (`scan.started`, `scan.completed`, `extractor.completed`, `analyzer.completed`, `action.completed`, `job.spawning`, `job.completed`, `job.failed`) plus two CLI-process-driven (`boot` before verb routing, `shutdown` after the verb's exit code resolves). Dual-mode: `deterministic` runs in-process during the dispatch, `probabilistic` is enqueued as a job. Hooks REACT to events; they cannot block, mutate, or steer the pipeline. | A curated event payload (run-scoped, scan-scoped, job-scoped, or process-scoped) plus an optional declarative `filter` map. | `void` (reactions are side effects). |
+| **Provider** | Recognizes a platform. The kind catalog lives on disk under `<plugin>/kinds/<kindName>/{schema.json, kind.json}` (structure-as-truth); the loader projects it onto the runtime descriptor. The Provider's walker hardcodes the paths it scans within the project (e.g. `.claude/`, `.gemini/`); it does NOT extend the scan into the user's HOME. `Provider.roots` is enforcement-grade: a Provider with declared roots only sees matching files; a Provider without `roots` acts as the fallback. Deterministic-only. | Filesystem walk results, candidate path. | `{ kind, provider } \| null`. |
+| **Extractor** | Extracts signals from a node body. Deterministic-only: runs synchronously inside `sm scan`. Output flows through context callbacks (no return value): `ctx.emitLink(link)` for the kernel's `links` table (validated against the global closed enum of link kinds; per-extractor allowlist was retired with the structure-as-truth refactor), `ctx.enrichNode(partial)` for the kernel's enrichment layer (separate from the author's frontmatter), `ctx.emitContribution(id, payload)` for view contributions, `ctx.store` for the plugin's own KV / dedicated tables. | Parsed node (frontmatter + body) + callbacks. | `void` (output via callbacks). |
+| **Analyzer** | Evaluates the graph. Dual-mode: `deterministic` runs in `sm check`, `probabilistic` runs in jobs. The analyzer↔action relationship is declared from the Action side via `precondition.analyzerIds` (Modelo B). | Full graph (nodes + links). | `Issue[]`. |
+| **Action** | Operates on one or more nodes. Dual-mode: `deterministic` (in-process code) or `probabilistic` (rendered prompt the runner executes). Files-by-convention: every Action carries `<action-dir>/report.schema.json`; probabilistic Actions additionally carry `<action-dir>/prompt.md`. The retired `reportSchemaRef` / `promptTemplateRef` / `expectedTools` / `fanOutPolicy` manifest fields were replaced by these conventions and the simplified `precondition` block. | Node(s), optional args. | Deterministic: report JSON. Probabilistic: rendered prompt that a runner executes. |
+| **Formatter** | Serializes the graph. Deterministic-only. The `formatId` consumed by `sm graph --format <name>` comes from the formatter's folder name. | Graph + optional filter. | String (ASCII / Mermaid / DOT / JSON / user-defined). |
+| **Hook** | Reacts declaratively to one of ten curated lifecycle events, eight pipeline-driven (`scan.started`, `scan.completed`, `extractor.completed`, `analyzer.completed`, `action.completed`, `job.spawning`, `job.completed`, `job.failed`) plus two CLI-process-driven (`boot` before verb routing, `shutdown` after the verb's exit code resolves). **Deterministic-only** since the structure-as-truth refactor: LLM-dependent reactions are modeled as a deterministic Hook that enqueues a probabilistic Action via `ctx.queue('<plugin>/<action>', payload)`. Hooks REACT to events; they cannot block, mutate, or steer the pipeline. | A curated event payload (run-scoped, scan-scoped, job-scoped, or process-scoped) plus an optional declarative `filter` map. | `void` (reactions are side effects). |
 
 ### IO discipline, extensions never write to the filesystem
 
@@ -194,13 +194,14 @@ This invariant is what makes the consent gate at the kernel boundary sufficient:
 
 ### Provider · `kinds` catalog
 
-Every `Provider` MUST declare a non-empty map `kinds: { <kind>: { schema, defaultRefreshAction, ui } }` covering every `kind` it classifies into. Each entry carries three required fields:
+Every `Provider` declares its kind catalog via the filesystem (structure-as-truth): each kind lives under `<plugin>/kinds/<kindName>/` and ships exactly two files:
 
-- **`schema`**, path (relative to the Provider package) to the kind's frontmatter JSON Schema. The schema MUST extend [`frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) via `allOf` + `$ref` to base's `$id`. The kernel registers it with AJV at boot and validates every node's frontmatter against the entry matching its classified kind.
-- **`defaultRefreshAction`**, 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; a dangling reference disables the Provider with status `invalid-manifest`. Plugins MAY override per-node via `metadata.refreshAction`; the Provider default is normative.
-- **`ui`**, presentation block: `{ label, color, colorDark?, emoji?, icon? }`. See §Provider · `ui` presentation below.
+- **`schema.json`**, the kind's frontmatter JSON Schema. MUST extend [`frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) via `allOf` + `$ref` to base's `$id`. The kernel reads it once at boot, registers it with AJV, and validates every node's frontmatter against the entry matching its classified kind.
+- **`kind.json`**, the per-kind metadata, today just `{ ui: { label, color, colorDark?, emoji?, icon? } }`. See §Provider · `ui` presentation below. Validated against [`schemas/extensions/provider-kind.schema.json`](./schemas/extensions/provider-kind.schema.json) at load time.
 
-The catalog is the single source of truth for "which kinds does this Provider emit", the `IProvider` runtime contract derives the kind set from `Object.keys(kinds)`.
+The loader's discovery (`discoverProviderKinds`) projects every `kinds/<kindName>/` directory into the runtime descriptor `instance.kinds[<kindName>] = { schema, schemaJson, ui }`. The `IProvider` runtime contract derives the kind set from `Object.keys(kinds)`; authors do not write the map by hand any more.
+
+The retired manifest field `defaultRefreshAction` (the qualified action id the UI's `🧠 prob` button dispatched) was removed alongside the button. A replacement UX is TBD; until then, the kernel does not surface a Provider-declared "default refresh" path.
 
 ### Provider · `ui` presentation
 
@@ -588,7 +589,7 @@ Two schemas describe the wire shape:
 
 ### Identity
 
-Each view contribution is identified by the qualified id `<pluginId>/<extensionId>/<contributionId>`. The plugin author declares contributions in the extension manifest under `viewContributions: Record<string, IViewContribution>`; the loader composes the qualified id from the plugin id, the extension id, and the Record key.
+Each view contribution is identified by the qualified id `<pluginId>/<extensionId>/<contributionId>`. The plugin author declares contributions in the extension manifest under `ui: Record<string, IViewContribution>` (renamed from `viewContributions` with the structure-as-truth refactor); the loader composes the qualified id from the plugin id, the extension id, and the Record key. The runtime catalog aggregated by `Kernel.getRegisteredViewContributions()` keeps the original `viewContributions` name, only the manifest-side field changed.
 
 ### Manifest
 
@@ -596,7 +597,7 @@ Each entry picks a `slot` name from the closed catalog and supplies presentation
 
 ```jsonc
 {
-  "viewContributions": {
+  "ui": {
     "breakdown": {
       "slot": "inspector.body.panel.breakdown",
       "label": "Keyword hits",
@@ -616,13 +617,13 @@ The plugin author picks ONE slot per contribution; that single decision determin
 
 ### Settings
 
-Plugin user-configurable settings live at the manifest root in `settings: Record<string, ISettingDeclaration>` (see [`schemas/plugins-registry.schema.json`](./schemas/plugins-registry.schema.json)). Each setting picks an input-type from the closed catalog at [`schemas/input-types.schema.json`](./schemas/input-types.schema.json) (`string-list`, `single-string`, `boolean-flag`, `integer`, `enum-pick`, `enum-multipick`, `path-glob`, `regex`, `secret`, `key-value-list`). The kernel exposes resolved settings to extractors via `ctx.settings.<settingId>`; the UI generates a form per declaration; the CLI's `sm plugins config <id>` exposes the same surface.
+Plugin user-configurable settings live **on each extension's manifest** (structure-as-truth) in `settings: Record<string, ISettingDeclaration>` (see [`schemas/extensions/base.schema.json`](./schemas/extensions/base.schema.json) and [`schemas/input-types.schema.json`](./schemas/input-types.schema.json)). Each setting picks an input-type from the closed catalog (`string-list`, `single-string`, `boolean-flag`, `integer`, `enum-pick`, `enum-multipick`, `path-glob`, `regex`, `secret`, `key-value-list`). The kernel exposes resolved settings via `ctx.settings.<settingId>` to the extension's runtime methods (`extract`, `evaluate`, `invoke`, etc.); the UI generates a form per declaration; the CLI's `sm plugins config <plugin>/<extension>` exposes the same surface. Plugin-level settings are no longer supported; the field was moved from `plugin.json` to each extension that consumes it.
 
-Settings are read once at extractor invocation; changing a setting requires `sm scan` to re-emit affected contributions. The UI surfaces a "settings changed, rescan needed" indicator when the manifest detects mismatch; live re-emission is explicitly out of scope (rescan-required is a stability decision per `ROADMAP.md` §UI contribution system D4).
+Settings are read once at extension invocation; changing a setting requires `sm scan` to re-emit affected contributions. The UI surfaces a "settings changed, rescan needed" indicator when the manifest detects mismatch; live re-emission is explicitly out of scope (rescan-required is a stability decision per `ROADMAP.md` §UI contribution system D4).
 
 ### Runtime catalog
 
-The kernel exposes a runtime catalog (`Kernel.getRegisteredViewContributions()`) listing every plugin-contributed view contribution with its `pluginId`, `extensionId`, `contributionId`, `slot`, and the manifest-declared `label` / `tooltip` / `icon` / `emptyText` / `emitWhenEmpty`. The catalog is built once at boot from every loaded extension's `viewContributions` map, AJV-validated, and frozen, same lifecycle as `getRegisteredAnnotationKeys()`.
+The kernel exposes a runtime catalog (`Kernel.getRegisteredViewContributions()`) listing every plugin-contributed view contribution with its `pluginId`, `extensionId`, `contributionId`, `slot`, and the manifest-declared `label` / `tooltip` / `icon` / `emptyText` / `emitWhenEmpty`. The catalog is built once at boot from every loaded extension's `ui` map (renamed from `viewContributions` with the structure-as-truth refactor), AJV-validated, and frozen, same lifecycle as `getRegisteredAnnotationKeys()`.
 
 Analyzers see the catalog through `IAnalyzerContext.viewContributions` so cross-cutting checks (`core/unknown-slot`, `core/contribution-orphan`) can reason about emissions.
 
@@ -712,7 +713,7 @@ Same honest-note posture as [`plugin-kv-api.md`](./plugin-kv-api.md): isolated a
 
 Two built-ins ship with the system to cover catalog evolution and rename edge cases:
 
-- **`core/unknown-slot`**, walks every loaded plugin's `viewContributions[*].slot`; emits an `Issue` of severity `warn` for any slot not in the current kernel catalog. Parallel to `core/unknown-field` for annotations. Note: AJV at manifest load already rejects unknown slots as `invalid-manifest`; this analyzer covers the soft-warning path when a plugin remains loaded across a catalog version bump.
+- **`core/unknown-slot`**, walks every loaded plugin's `ui[*].slot`; emits an `Issue` of severity `warn` for any slot not in the current kernel catalog. Parallel to `core/unknown-field` for annotations. Note: AJV at manifest load already rejects unknown slots as `invalid-manifest`; this analyzer covers the soft-warning path when a plugin remains loaded across a catalog version bump.
 - **`core/contribution-orphan`**, joins `scan_contributions` against the live `scan_nodes` set; emits an `Issue` of severity `warn` for emissions whose `node_path` no longer exists (post-rename heuristic miss).
 
 ### Catalog versioning

package/conformance/cases/sidecar-end-to-end.json

@@ -16,10 +16,10 @@
     { "type": "json-path", "path": "$.nodes[0].sidecar.status", "matches": "^stale-(body|frontmatter|both)$" },
     { "type": "json-path", "path": "$.nodes[0].sidecar.annotations.version", "equals": 7 },
     { "type": "json-path", "path": "$.stats.issuesCount", "equals": 2 },
-    { "type": "json-path", "path": "$.issues[0].analyzerId", "equals": "annotation-stale" },
+    { "type": "json-path", "path": "$.issues[0].analyzerId", "equals": "annotation-orphan" },
     { "type": "json-path", "path": "$.issues[0].severity", "equals": "warn" },
-    { "type": "json-path", "path": "$.issues[1].analyzerId", "equals": "annotation-orphan" },
-    { "type": "json-path", "path": "$.issues[1].severity", "equals": "warn" },
-    { "type": "json-path", "path": "$.issues[1].data.expectedMdPath", "equals": ".claude/agents/orphan.md" }
+    { "type": "json-path", "path": "$.issues[0].data.expectedMdPath", "equals": ".claude/agents/orphan.md" },
+    { "type": "json-path", "path": "$.issues[1].analyzerId", "equals": "annotation-stale" },
+    { "type": "json-path", "path": "$.issues[1].severity", "equals": "warn" }
   ]
 }

package/conformance/coverage.md

@@ -25,13 +25,14 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 15 | `summaries/hook.schema.json` |, | 🔴 missing | Blocked by Step 11. |
 | 16 | `summaries/markdown.schema.json` |, | 🔴 missing | Blocked by Step 11. |
 | 17 | `extensions/base.schema.json` |, | 🔴 missing | Meta-case: every manifest under `src/extensions/` validates against the appropriate kind schema (which extends base via `allOf`). |
-| 18 | `extensions/provider.schema.json` | `plugin-missing-ui-rejected` | 🟡 partial | A drop-in Provider whose `kinds[*]` entry omits the required `ui` block fails AJV validation with `invalid-manifest` while the rest of the pipeline keeps running (built-in Claude Provider, exit 0). The complementary positive case (canonical Claude Provider manifest validates) lives in `provider:claude` conformance. Direct case for missing `kinds` rejection still pending. |
-| 19 | `extensions/extractor.schema.json` |, | 🔴 missing | Case: `frontmatter` + `slash` + `at-directive` extractor manifests validate; an extractor emitting a disallowed `emitsLinkKinds` value fails. |
+| 18 | `extensions/provider.schema.json` | `plugin-missing-ui-rejected` | 🟡 partial | A Provider plugin whose `kinds/<kindName>/kind.json` omits the required `ui` block fails AJV validation with `invalid-manifest` while the rest of the pipeline keeps running (built-in Claude Provider, exit 0). Since the structure-as-truth refactor, Providers no longer carry a `kinds` map in the manifest; per-kind metadata lives under `kinds/<kindName>/kind.json` and frontmatter schemas under `kinds/<kindName>/schema.json`. The complementary positive case (canonical Claude Provider validates) lives in `provider:claude` conformance. Direct case for missing `kinds/` directory rejection still pending. |
+| 19 | `extensions/extractor.schema.json` |, | 🔴 missing | Case: `frontmatter` + `slash` + `at-directive` extractor manifests validate; an extractor declaring a `precondition.kind` against an unknown qualified kind emits `precondition-kind-unknown` in `sm plugins doctor`. |
 | 20 | `extensions/analyzer.schema.json` |, | 🔴 missing | Case: `trigger-collision`, `broken-ref`, `superseded` manifests validate. |
-| 21 | `extensions/action.schema.json` |, | 🔴 missing | Case: a `deterministic` action manifest validates; a `probabilistic` action WITHOUT `promptTemplateRef` fails. |
+| 21 | `extensions/action.schema.json` |, | 🔴 missing | Case: a `deterministic` action manifest validates; a `probabilistic` action without `<action-dir>/prompt.md` surfaces as `load-error` (structure-as-truth: prompt template lives on disk by convention, no `promptTemplateRef` field). |
 | 22 | `extensions/formatter.schema.json` |, | 🔴 missing | Case: `ascii` formatter manifest validates. |
 | 23 | `history-stats.schema.json` |, | 🔴 missing | Blocked by Step 5 (history). Case: seed `state_executions` with a deterministic fixture, run `sm history stats --json --since <T0> --until <T1> --period month --top 5`, assert the document validates and that `totals.executionsCount == sum(perAction.executionsCount)` and `errorRates.global == totals.failedCount / totals.executionsCount`. Percentiles (`p95`/`p99`) intentionally omitted in v1, add later as a minor bump without breaking consumers. |
-| 24 | `extensions/hook.schema.json` |, | 🔴 missing | Case: a `deterministic` hook manifest with `triggers: ['scan.completed']` validates; a hook declaring an unknown trigger (e.g. `scan.progress`) fails with `invalid-manifest` at load time. |
+| 24 | `extensions/hook.schema.json` |, | 🔴 missing | Case: a hook manifest with `triggers: ['scan.completed']` validates; a hook declaring an unknown trigger (e.g. `scan.progress`) fails with `invalid-manifest` at load time. Hooks are deterministic-only since structure-as-truth; manifests carrying a `mode` field are rejected. |
+| 36 | `extensions/provider-kind.schema.json` |, | 🔴 missing | Case: `<plugin>/kinds/<kindName>/kind.json` carrying a valid `{ ui }` block validates; a kind folder missing `kind.json` or `schema.json` surfaces as `invalid-manifest`; a `kind.json` whose `ui.color` is not `#RRGGBB` fails AJV. |
 | 25 | `api/rest-envelope.schema.json` |, | 🔴 missing | Step 14.2 BFF list-envelope shape (`{ schemaVersion, kind, items \| item \| value, filters, counts }`). Case: hit `GET /api/nodes` against a primed scope, validate the response against the schema; assert the `oneOf` rejects an envelope that carries both `items` and `item`. Implementation-side coverage exists today (`src/test/server-endpoints.test.ts`) but a kernel-agnostic conformance case is required before v1.0.0 ships. |
 | 26 | `sidecar.schema.json` | `sidecar-end-to-end` | 🟢 covered | Co-located YAML sidecar (`<basename>.sm`) root shape: reserved blocks `for` / `annotations` / `settings` / `audit` plus opt-in plugin namespacing. Step 9.6.2 (2026-05-05) shipped the kernel reader; Step 9.6.3 (2026-05-05) formalised the `audit:` sub-shape populated by the built-in `bump` Action; Step 9.6.6 (2026-05-06) flips this row 🟢 with the end-to-end `sidecar-end-to-end` case (fixture `sidecar-end-to-end/`): a scan over a stale-`.sm` + orphan-`.sm` corpus produces a populated `Node.sidecar` overlay with `present: true` and `status: stale-*`, denormalises `annotations.version` into the node row, and emits both `annotation-stale` and `annotation-orphan` issues from the built-in core analyzers. Structural sample (untouched) at `fixtures/sidecar-example/agent-example.sm`. |
 | 27 | `annotations.schema.json` | `sidecar-end-to-end` | 🟢 covered | Curated catalog of 15 conventional skill-map annotation fields (versioning, supersession, provenance, lifecycle, taxonomy, display, docs). `additionalProperties: true` so users / plugins extend without coordination; the `unknown-field` Tier-1 analyzer shipped in Step 9.6.6 emits warnings on truly unrecognized keys. Step 9.6.2 (2026-05-05) wired the kernel reader; Step 9.6.6 (2026-05-06) flips this row 🟢 via `sidecar-end-to-end`, which asserts that an `annotations.version: 7` value round-trips through `state_scan_nodes.annotations_json` and surfaces in the node's `sidecar.annotations` overlay AND in the denormalised `Node.version` column. Structural sample at `fixtures/sidecar-example/agent-example.sm`. Catalog trimmed from 31 to 15 fields on 2026-05-07 after UX review. |

package/conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/kinds/markdown/kind.json

@@ -0,0 +1,3 @@
+{
+  "_comment": "Conformance fixture: this kind.json deliberately omits the required `ui` block; the loader MUST reject the plugin as invalid-manifest."
+}

package/conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/kinds/markdown/schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:test:bad-provider/markdown",
+  "type": "object",
+  "additionalProperties": true
+}

package/conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json

@@ -1,6 +1,7 @@
 {
-  "id": "bad-provider",
   "version": "0.1.0",
   "specCompat": "*",
-  "extensions": ["provider.js"]
+  "catalogCompat": "*",
+  "description": "Conformance fixture: provider missing `ui` block.",
+  "granularity": "bundle"
 }

package/conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/providers/bad-provider/index.js

@@ -0,0 +1,17 @@
+// Conformance fixture: provider whose `kinds/markdown/kind.json`
+// deliberately omits the required `ui` block (structure-as-truth
+// refactor moved the kind catalog from the manifest map to per-kind
+// folders on disk). The plugin loader MUST reject this manifest with
+// a clear "missing required property 'ui'" diagnostic and the plugin
+// MUST end up in `invalid-manifest` status. The companion case
+// `plugin-missing-ui-rejected.json` asserts the stderr text and that
+// `sm scan` survives (the loader degrades the bad plugin and lets the
+// rest of the pipeline continue).
+export default {
+  version: '0.1.0',
+  description: 'provider whose markdown kind is missing the ui block',
+  async *walk() {},
+  classify() {
+    return 'markdown';
+  },
+};

package/index.json

@@ -174,25 +174,27 @@
       }
     ]
   },
-  "specPackageVersion": "0.27.0",
+  "specPackageVersion": "0.28.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "609e04963f4a7302161bc01718643fa60c358b62cf564cd683e68892be6a65de",
+      "CHANGELOG.md": "9d49970b380a997e8321ea9e7da326284c4b3bb2ac56bc26633e5108a96d8486",
       "README.md": "54c4649fa9742bf2f74423ea78788a7474ce09649cbe1e72a270b606cf16a0a5",
-      "architecture.md": "7c735b2d305798d610760d23b03a450361131927109d7271ef78257fbf36b1f4",
+      "architecture.md": "d40423d3df102c31744186f3b5e91446e57fb78839e67c010501fb210db6d545",
       "cli-contract.md": "c22f7c82d460714efaf34a04a2d2367d21eb04985100aef1291071e6726cbc64",
       "conformance/README.md": "6871dde25b5770ed945284c9e0f749e0768ec3f5ba4966bdb215985789e43887",
       "conformance/cases/kernel-empty-boot.json": "2a5be9c93143d07a16d998df09dcc8fa4ea2d2f9a0bff6417573ed5a770352c1",
       "conformance/cases/no-global-scope.json": "1284763988026d924c0bd78ba8a9f417dc88f5b7e9f4c2b642ae0c447758bfd4",
       "conformance/cases/orphan-markdown-fallback.json": "8ef6e49b7e6532bd845d9f54974a16e537cf98d355f0c5e4f4fb06abac3adcc5",
       "conformance/cases/plugin-missing-ui-rejected.json": "bdebee810436e6be88edf2fe38ddc6939fd3f53e6a12dc1d66da051c4922f1e9",
-      "conformance/cases/sidecar-end-to-end.json": "24a73e7c857709d001cf7013b8fe5ccad4027e064b39533dda33697d80b56e7a",
-      "conformance/coverage.md": "0d202baf257f6690c107e1e20aff0c7db0399a53fcd72536e2d87ab7641510ab",
+      "conformance/cases/sidecar-end-to-end.json": "dbb3640f95769a36b881855a261f918481edadea13a7eb0765c6090f2417a142",
+      "conformance/coverage.md": "7c02052750ee5fca711218cbf993313dd1ed7c68bcac000b2cb23b5f688a4a2c",
       "conformance/fixtures/orphan-markdown/.claude/agents/reviewer.md": "7f062731106f2d9811e4fffcf6ab44b8dfff4cfb16536a469514cc0664e832bf",
       "conformance/fixtures/orphan-markdown/ARCHITECTURE.md": "d6b6e18d4b963b26a292de73348c3396fd4710ab4c4bdd6cf094e581f99ec8d6",
-      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json": "4d78af6f12faa9d131e2a19f1dbb8f250baacc525978f3a8c858932b95da4ff6",
-      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/provider.js": "45843e8e1a679482a17e01dcd43e1800e1d3148f4ac2cd6ab8a29ef0430b6152",
+      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/kinds/markdown/kind.json": "6676a89bae5197e23cf50f1c11d596db558ac80f7334a7208fe57d8b92422251",
+      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/kinds/markdown/schema.json": "42795e7f1759fa25115a426edf5cd1b0c91b091b408aeee3f4f9fbc8f89f32bc",
+      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json": "fb3f52f82f1635d0e5de74788eb5f640d0e36b19464a46f0b2812f6aa9db435f",
+      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/providers/bad-provider/index.js": "6eac0555de4194c3266c2abef89e39d833159990e1822ae1d4895df67c31d18f",
       "conformance/fixtures/plugin-missing-ui/notes/example.md": "55767f0aa1b6774546a99f28c58e7b732aa9cfa5dfce8d0326470f7f622f577e",
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
       "conformance/fixtures/sidecar-end-to-end/.claude/agents/orphan.sm": "3102ff10a0f08f60c014f82409d45ad4faf2cefa04d652a87676d3557ad64944",
@@ -204,7 +206,7 @@
       "interfaces/security-scanner.md": "e8049712b9cf7a07c786bf19f8f775f8ef9638f063f7fba5c7a8b1431b92f38e",
       "job-events.md": "84206168ac12b536d34470d62f8c8cba95dab181fee66d23203c2cf5dfbee716",
       "job-lifecycle.md": "9c429121f98a07c8795f8979ed1abc5e5334e3f89db51585a8da55c527ef855b",
-      "plugin-author-guide.md": "03c2f666d7856eae76594484a1580968e1292f247fb10c8abcff5d99c9d38f01",
+      "plugin-author-guide.md": "02a040a873c51843a4c3c667a40eea3ad4c7f343e08396d7de666010ed833c88",
       "plugin-kv-api.md": "1acc69ed82433a74e35ada61d63a6d7379fb61046ff83de1e0facbe884c64704",
       "prompt-preamble.md": "9dd4f6d1bc6a425f8782fcee10cbe75909e8d64e28781fda56c2fae909b02f40",
       "schemas/annotations.schema.json": "e39990d47f53e25a1b3a5587a5714486d0b819b8eeaac10d42783a675296aee1",
@@ -213,13 +215,14 @@
       "schemas/conformance-case.schema.json": "f6d4c9fb92e79cb516eeeb9d042223572a3bd5ff8e7871a0becce13916f20cf6",
       "schemas/conformance-result.schema.json": "426998e4f5cb079778ca7d0233634667d4fbc5a7e399cc41211fabd768db8ee0",
       "schemas/execution-record.schema.json": "0d61e33f2dc1aaa4cc7337b5eac4ea8b9034022ce24bae9156c3c9f33204c250",
-      "schemas/extensions/action.schema.json": "262272175c06a2e33c08f819a45c3ef8260276c91a9d0542fdffc932aeb32db7",
-      "schemas/extensions/analyzer.schema.json": "c3c5fc7de89318c178d170629dc9aecd6bcce9418e9ce7cc2f8d4f5ea8db99a6",
-      "schemas/extensions/base.schema.json": "5a593f74678485b2e2dc5b92ba9a345d6290ef7381921758a852934e09db7a64",
-      "schemas/extensions/extractor.schema.json": "38000aea61c4d06cd136ccbcf740d3608b2c5586c7a0ff93a75e75f0df09f018",
-      "schemas/extensions/formatter.schema.json": "816136b9b933a93fde6859110d1d68dafe39099dea589786282b90627b464f7c",
-      "schemas/extensions/hook.schema.json": "abfa75881a4bd20c367f1eada29fb577b89752920c9f9351f8247e1340f5f2ca",
-      "schemas/extensions/provider.schema.json": "e9f026b7c6c3a167a55c581ebb92425e10563cc3b1864b18f48462b813d01ff3",
+      "schemas/extensions/action.schema.json": "9f6c2427ce3f0d6fa329adf0f13129821116ab79a1d2a53f96464513ff044ebe",
+      "schemas/extensions/analyzer.schema.json": "f9bed3ba1305b2b64da277dccfbe760f7c058c4bb62a2d845af9c75787f159f6",
+      "schemas/extensions/base.schema.json": "8aaf1f8f1693d401e32feb91d4e064ff80ec7d4b0e3f15eff4202c708febaef4",
+      "schemas/extensions/extractor.schema.json": "5994088bf669321d2a7b8262c07cc94e05e5e2f49a235ae5389b7c66ecc1b2e1",
+      "schemas/extensions/formatter.schema.json": "d6d417df20260e5ddfe71f104b11a45873869706f86372c3c3c78c583e06e8d5",
+      "schemas/extensions/hook.schema.json": "76bf2c07f9e689b3fd1c67cbad4516a4df10604f07103759e82670e5213ddcdf",
+      "schemas/extensions/provider-kind.schema.json": "add3c5648721e67887eb971a76b39319628effac6315cffd51f7dcf679810740",
+      "schemas/extensions/provider.schema.json": "ae528d6ce1e083a2b5e3e7c6c701fbfaa8d58c79fb1f71616dc2d00c1a841cb7",
       "schemas/frontmatter/base.schema.json": "df0056a9478514a0db7a705e59868fa4f67673ac1cc9c9da979de4237cdd62a1",
       "schemas/history-stats.schema.json": "5170dec0299f3d04382a38079a27b1f26300a6b95fdb1ea0fae11050ad9f0574",
       "schemas/input-types.schema.json": "c713b768d0b0e3d0c764afb401189f7fb624a82b4e988b73aab015cf9c67c01f",
@@ -228,7 +231,7 @@
       "schemas/link.schema.json": "7fc429d03aca7e4c0b9a28241712c1aa2a5275870cea5ed938c2f97e8cccb081",
       "schemas/node.schema.json": "e5da06c9262cc0f2f7584d5733ebc1c08acd75487952ed7b4d6035fb417aaa4b",
       "schemas/plugins-doctor.schema.json": "c1d92f30fdb0080e8cd8f7dc5d43e01aae02a16640bc5eb04811c337a275de58",
-      "schemas/plugins-registry.schema.json": "3d8a29aa045d46d70be127aabbc59831da0c71a54f18eae752676e452577ae3d",
+      "schemas/plugins-registry.schema.json": "cca7ae65f0c22510ea27ea5ae34e0074f5beb5871a57b005b6b831e6ceaff5c0",
       "schemas/project-config.schema.json": "7bb695476015b6b43026db78208aedf67350f4bc2c796c822fa87d0c9093b13f",
       "schemas/refresh-report.schema.json": "54519b8caf86ba84c182f9565be9b5084bc1631ae05e9217ee18f34c0039fff3",
       "schemas/report-base-deterministic.schema.json": "9d318d0181d121097c906ef3af1c52d71c782740bd04cf23418d7627ce2c3ed5",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",