@skill-map/spec 0.26.0 → 0.28.0

package/plugin-author-guide.md

@@ -12,23 +12,53 @@ This guide is **descriptive prose**, not the normative contract. The normative p
 
 ```text
 my-plugin/
-├── plugin.json            ← manifest (required)
-└── extensions/
-    └── extractor.js      ← one file per declared extension
+├── plugin.json                          ← bundle metadata (required)
+└── extractors/                          ← one folder per extension kind
+    └── my-extractor/
+        ├── index.js                     ← extension entry (required)
+        ├── text.ts                      ← user-facing strings (optional, see below)
+        └── my-extractor.test.ts         ← tests live next to the code (optional)
 ```
 
+The kernel auto-discovers extensions by walking
+`<plugin-dir>/<kind>s/<name>/index.{js,mjs,ts}` for each known kind
+(`providers`, `extractors`, `analyzers`, `actions`, `formatters`,
+`hooks`). The folder layout IS the source of truth: bundle from the
+top-level dir, kind from the subfolder name, extension id from the
+extension folder name. The manifest no longer declares an
+`extensions[]` array.
+
+**Co-located files convention**: any siblings of `index.{js,mjs,ts}`
+that the kernel does NOT recognise as an entry point are author
+files (texts, tests, schemas, fixtures). Two names are blessed by
+convention so consumers know where to look without grepping:
+
+- **`text.ts`** holds the extension's externalised user-facing
+  strings (the `tx()`-fed templates, error messages, glyph labels).
+  One per extension; imported by `index.ts` as `./text.js`. Keeps
+  copy out of the code path and makes the surface review-friendly.
+  Plain TS module, no schema, no codegen.
+- **`<extension-name>.test.ts`** (or `.test.mjs` / `.test.js`) is
+  the colocated test suite. Picked up by the workspace's test glob
+  (`plugins/**/*.test.ts`); no separate test directory.
+
+Both files are optional. The kernel ignores everything that isn't
+`index.{js,mjs,ts}`, so future per-extension fixtures, schemas, or
+conformance scopes can live in the same folder without manifest
+plumbing.
+
 ```jsonc
 // my-plugin/plugin.json
 {
   "id": "my-plugin",
   "version": "1.0.0",
   "specCompat": "^1.0.0",
-  "extensions": ["./extensions/extractor.js"]
+  "granularity": "bundle"
 }
 ```
 
 ```javascript
-// my-plugin/extensions/extractor.js
+// my-plugin/extractors/my-extractor/index.js
 export default {
   id: 'my-extractor',
   kind: 'extractor',
@@ -50,18 +80,19 @@ export default {
 };
 ```
 
-Drop the directory under one of the discovery roots and `sm plugins list` will pick it up.
+Drop the directory under `<cwd>/.skill-map/plugins/` and
+`sm plugins list` will pick it up. The kernel injects `pluginId`
+from `plugin.json#/id` at load time; do NOT hardcode it in the
+extension export. A folder/kind mismatch (e.g. an extractor placed
+under `analyzers/`) surfaces as `invalid-manifest`.
 
 ---
 
 ## Discovery
 
-The kernel scans two roots, in this order:
-
-1. `<project>/.skill-map/plugins/`, committed-with-the-repo plugins.
-2. `~/.skill-map/plugins/`, user-level plugins available across every project.
+The kernel scans one root: `<cwd>/.skill-map/plugins/`, committed-with-the-repo plugins. There is no implicit user-level discovery (see `cli-contract.md` §Scope is always project-local for the broader principle): plugins live with the project that uses them.
 
-A plugin is any direct child directory containing a `plugin.json`. Nested directories are not searched recursively. Pass `--plugin-dir <path>` to override both roots (mostly for testing).
+A plugin is any direct child directory of that root containing a `plugin.json`. Nested directories are not searched recursively. Pass `--plugin-dir <path>` to replace the default root with a custom directory (mostly for testing, or for loading a user-level plugin set the operator explicitly opts into).
 
 After every change to the `plugins/` folder, run `sm plugins list` to see the load status of each. The six statuses are documented under [Diagnostics](#diagnostics) below.
 
@@ -113,7 +144,7 @@ The kernel guards against two foot-guns:
 - If the extension file injects a `pluginId` field that doesn't match `plugin.json#/id`, the loader emits `invalid-manifest` with a directed reason. The composed qualifier MUST come from `plugin.json`, there is no second source of truth.
 - The kebab-case pattern on the extension `id` deliberately forbids `/`. This keeps the analyzer "the qualifier always lives in the plugin id, never in the extension id" enforced by AJV.
 
-For built-ins, the reference impl's `src/extensions/built-ins.ts` declares each extension's `pluginId` (`core` or `claude`) explicitly, built-ins do not have a `plugin.json`, so the bundle declaration IS the source of truth for their namespace.
+For built-ins, the reference impl's `src/plugins/<bundle>/plugin.json` provides the bundle's `id` and the codegen at `scripts/generate-built-ins.js` inlines the `pluginId` injection at build time (the resulting `src/plugins/built-ins.ts` is auto-generated and committed). Authors never hardcode `pluginId` on the extension export.
 
 ### Granularity, bundle vs extension
 
@@ -142,48 +173,60 @@ Resolution order is the same as for plugin enabled-state: DB override (`config_p
 
 `sm plugins enable/disable --all` operates only on top-level bundle ids (the default-enabled set every user can see); it never expands to qualified `<bundle>/<ext>` keys. The "disable every kernel built-in at once" intent is served by `--no-built-ins` on `sm scan` and friends; `--all` is the macro on user-toggle-able units, not on every individual extension.
 
-In your own plugin's `plugin.json`, set `granularity` only when you opt into the per-extension form:
+Set `granularity` in your `plugin.json`. The folder layout supplies the extensions; the kernel discovers them automatically:
 
 ```jsonc
 {
   "id": "my-multi-tool",
   "version": "1.0.0",
   "specCompat": "^1.0.0",
-  "granularity": "extension",
-  "extensions": [
-    "./extensions/orphan-skill-analyzer.js",
-    "./extensions/csv-formatter.js"
-  ]
+  "granularity": "extension"
 }
 ```
 
+```text
+my-multi-tool/
+├── plugin.json
+├── analyzers/
+│   └── orphan-skill/
+│       └── index.js
+└── formatters/
+    └── csv/
+        └── index.js
+```
+
 The default (`'bundle'`) is the right answer for almost every plugin, keep the manifest minimal until the plugin actually ships several independent capabilities.
 
-### Extractor `applicableKinds`, narrow the pipeline
+### Extractor `precondition`, narrow the pipeline
+
+An `Extractor` extension MAY declare a `precondition` block on its manifest. When declared, the kernel runs the extractor **only** against nodes that satisfy every declared sub-filter, the filter is fail-fast (no extractor context, no method call) so the extractor wastes zero CPU on nodes it cannot meaningfully process. The same shape is shared by `Analyzer` and `Action`.
 
-An `Extractor` extension MAY declare an `applicableKinds` array on its manifest. When declared, the kernel runs the extractor **only** against nodes whose `kind` is in the list, the filter is fail-fast (no extractor context, no method call) so the extractor wastes zero CPU on nodes it cannot meaningfully process.
+```ts
+precondition?: {
+  kind?: string[];     // qualified `<plugin>/<kindName>` ids
+  provider?: string[]; // plugin ids
+};
+```
 
-| `applicableKinds` | Behaviour |
+| `precondition` | Behaviour |
 |---|---|
 | Absent (`undefined`) | **Default.** The extractor runs on every kind the loaded Providers emit. |
-| `['skill']` | Runs only on skill nodes. |
-| `['skill', 'agent']` | Runs on skills + agents. Hooks, commands, notes are skipped. |
-| `[]` | **Invalid.** AJV rejects the manifest at load time (`minItems: 1`). The absence of the field already means "every kind"; an empty array is reserved for "this is a typo". |
+| `{ kind: ['claude/skill'] }` | Runs only on skill nodes from the Claude provider. |
+| `{ kind: ['claude/skill', 'gemini/skill'] }` | Runs on skills from either provider. |
+| `{ provider: ['claude'] }` | Coarser: runs on every kind the `claude` plugin declares. |
+| `{ kind: ['claude/skill'], provider: ['claude'] }` | Both filters apply (AND). |
 
-There is no wildcard syntax (no `'*'`), omitting the field IS the wildcard. The pattern is intentional: a literal absence is unambiguous, a string sentinel would invite typos that silently disable the extractor.
+Use `precondition.kind` over `precondition.provider` when the filter is really about the kind, not the provider. There is no wildcard syntax, omitting the field IS the wildcard.
 
 Use case, a deterministic frontmatter-tag extractor that only makes sense for skills:
 
 ```javascript
 export default {
-  id: 'tag-extractor',
-  kind: 'extractor',
+  // id, kind, pluginId injected by the loader from the folder path
   version: '1.0.0',
   description: 'Lifts the `tags:` frontmatter array into `references` links for skill nodes.',
-  emitsLinkKinds: ['references'],
-  defaultConfidence: 'high',
   scope: 'frontmatter',
-  applicableKinds: ['skill'],
+  precondition: { kind: ['claude/skill'] },
   async extract(ctx) {
     // Never invoked for agents, commands, hooks, or notes, the kernel
     // skipped this node before reaching us.
@@ -203,7 +246,9 @@ export default {
 
 > **Why no `mode` field?** Extractors are deterministic-only, they sit on `sm scan`'s synchronous loop, and the loop must stay fast and reproducible. If you need an LLM to infer something about a node (tags, summaries, suspicious imports), write an `Action` instead and let the user dispatch it via `sm job submit action:<id>`. The Action's report flows back through the job lifecycle, not through the Extractor pipeline.
 
-**Unknown kinds are non-blocking.** An extractor that lists a kind no installed Provider declares (typo, missing Provider plugin) still loads with status `loaded`; `sm plugins doctor` surfaces an informational warning so the author sees the mismatch. The exit code of `doctor` is NOT promoted to 1 by this warning, the corresponding Provider may legitimately arrive later (e.g. when the user installs the matching plugin), and the load contract favours forward compatibility over rigid checks. The full set of "known kinds" is the union of every installed Provider's `defaultRefreshAction` keys.
+> **Why no `emitsLinkKinds` / `defaultConfidence`?** Both fields were retired with the structure-as-truth refactor. Link kinds are constrained by the global closed enum (`invokes`, `references`, `mentions`, `supersedes`); off-enum emissions drop with `extension.error`. Confidence is declared per-emit on every `ctx.emitLink({ ..., confidence })` call (default `'medium'` if omitted).
+
+**Unknown qualified kinds are non-blocking.** An extractor that lists a kind no installed Provider declares (typo, missing Provider plugin) still loads with status `enabled`; `sm plugins doctor` surfaces an informational warning so the author sees the mismatch. The exit code of `doctor` is NOT promoted to 1 by this warning, the corresponding Provider may legitimately arrive later (e.g. when the user installs the matching plugin), and the load contract favours forward compatibility over rigid checks.
 
 ### Module top-level side effects survive load timeouts
 
@@ -229,23 +274,26 @@ Required fields (see [`schemas/plugins-registry.schema.json#/$defs/PluginManifes
 
 | Field | Type | Notes |
 |---|---|---|
-| `id` | kebab-case string | Globally unique. Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`. |
 | `version` | semver | Plugin version, independent of `specCompat`. |
 | `specCompat` | semver range | Spec versions this plugin is compatible with. Checked via `semver.satisfies(specVersion, this)` at load time. |
-| `extensions` | string[] | Relative paths to extension files. Each file's default export is the extension's runtime instance. `minItems: 1`. |
+| `catalogCompat` | semver range | Semver range against the view-slots + input-types catalog. Independent from `specCompat` because the catalog evolves on its own cadence. Required as of the structure-as-truth refactor (was optional). |
+| `description` | string | Required short description shown in `sm plugins list` and the UI. |
 
 Optional fields:
 
 | Field | Type | Notes |
 |---|---|---|
-| `description` | string | One-line summary shown in `sm plugins list`. |
-| `granularity` | `'bundle' \| 'extension'` | Controls how `sm plugins enable / disable` operates on this plugin. Default `'bundle'`. See [Granularity, bundle vs extension](#granularity--bundle-vs-extension). |
+| `granularity` | `'bundle' \| 'extension'` | Default `'extension'` (each extension toggleable by qualified id). Set to `'bundle'` when the plugin's extensions form a coherent unit a user would never want to toggle piecemeal. |
 | `storage` | object | `{ "mode": "kv" }` or `{ "mode": "dedicated", "tables": [...], "migrations": [...] }`. Absent means the plugin does not persist state. |
 | `author` | string | Free-form. |
 | `license` | string | SPDX identifier. |
 | `homepage` | string | URL. |
 | `repository` | string | URL. |
 
+**Structure-as-truth**: the plugin id is the directory name (`<root>/<id>/plugin.json`); it is NOT a manifest field. Manifests carrying an `id` literal are rejected as `invalid-manifest`. Settings moved out of `plugin.json` into each extension's own manifest with the same refactor (see [Extension manifest](#extension-manifest)).
+
+The manifest does NOT list extensions. The kernel discovers each extension by walking `<plugin-dir>/<kind>s/<name>/index.{js,mjs,ts}`; the path is authoritative for both the kind and the local id. A Provider's kind catalog lives on disk at `<plugin>/kinds/<kindName>/{schema.json, kind.json}` (see [Providers](#providers--actions)).
+
 ### `specCompat` strategy
 
 Pre-`v1.0.0` of the spec, narrow ranges are the defensive default, minor bumps **MAY** carry breaking changes per [`versioning.md`](./versioning.md). A plugin that spans minor boundaries can load successfully and crash at first use against a changed schema.
@@ -663,7 +711,7 @@ import { test } from 'node:test';
 import { strictEqual } from 'node:assert';
 import { runExtractorOnFixture, node } from '@skill-map/testkit';
 
-import extractor from '../extensions/extractor.js';
+import extractor from '../extractors/my-extractor/index.js';
 
 test('emits one reference per [[ref:<name>]] token', async () => {
   const { links } = await runExtractorOnFixture(extractor, {
@@ -703,7 +751,7 @@ Full surface in `@skill-map/testkit/index.ts`.
 | `incompatible-spec` | manifest parsed but `semver.satisfies` failed against the installed spec. | Plugin built against an older / newer spec. |
 | `invalid-manifest` | `plugin.json` missing, unparseable, AJV-fails, OR the directory name does not equal the manifest id. | Typo, missing required field, wrong shape, mismatched directory name. |
 | `load-error` | manifest passed but an extension module failed to import or its default export failed schema validation. | Missing `kind` field, wrong `kind` for the file, runtime import error. |
-| `id-collision` | two plugins reachable from different roots declared the same `id`. Both collided plugins receive this status; no precedence analyzer applies. | Project-local plugin and a user-global plugin (or two `--plugin-dir` plugins) sharing an id. Rename one and rerun. |
+| `id-collision` | two plugins reachable from different roots declared the same `id`. Both collided plugins receive this status; no precedence analyzer applies. | A project-local plugin and a `--plugin-dir` plugin (or two `--plugin-dir` plugins) sharing an id. Rename one and rerun. |
 
 `sm plugins doctor` runs the full load pass and exits 1 if any plugin is in a non-`loaded` / non-`disabled` state (so any of `incompatible-spec` / `invalid-manifest` / `load-error` / `id-collision` trips it). Wire it into CI to catch breakage early.
 
@@ -718,7 +766,7 @@ Full surface in `@skill-map/testkit/index.ts`.
 `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
+// my-plugin/extractors/my-extractor/index.js
 export default {
   id: 'my-extractor',
   kind: 'extractor',
@@ -768,7 +816,7 @@ auditor:
 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/analyzer.js
+// compliance-plugin/analyzers/compliance-checker/index.js
 export default {
   id: 'compliance-checker',
   kind: 'analyzer',
@@ -1039,9 +1087,10 @@ Full plugin walkthrough:
 
 ```
 plugins/acme-keyword-finder/
-├── plugin.json           ← manifest with settings + catalogCompat
-└── extensions/
-    └── extractor.js       ← extract() with ctx.emitContribution
+├── plugin.json                          ← manifest with settings + catalogCompat
+└── extractors/
+    └── keyword-finder/
+        └── index.js                     ← extract() with ctx.emitContribution
 ```
 
 `plugin.json`:
@@ -1052,7 +1101,7 @@ plugins/acme-keyword-finder/
   "version": "1.0.0",
   "specCompat": "^0.20.0",
   "catalogCompat": "^1.0.0",
-  "extensions": ["./extensions/extractor.js"],
+  "granularity": "bundle",
   "settings": {
     "keywords": {
       "type": "string-list",
@@ -1064,17 +1113,15 @@ plugins/acme-keyword-finder/
 }
 ```
 
-`extensions/extractor.js`:
+`extractors/keyword-finder/index.js`:
 
 ```js
-export const extractor = {
+export default {
   id: 'keyword-finder',
-  pluginId: 'acme-keyword-finder',
   kind: 'extractor',
   version: '1.0.0',
   description: 'Counts configured keywords per node.',
   stability: 'stable',
-  mode: 'deterministic',
   emitsLinkKinds: [],
   defaultConfidence: 'high',
   scope: 'body',

package/schemas/extensions/action.schema.json

@@ -2,78 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/extensions/action.schema.json",
   "title": "ExtensionAction",
-  "description": "Manifest shape for an `Action` extension. An action operates on one or more nodes in one of two modes: `deterministic` (code runs in-process, returns a report JSON directly) or `probabilistic` (kernel renders a prompt, a runner executes it against an LLM, the callback closes the job). The `mode` discriminator drives which additional fields are required. See `architecture.md` §Execution modes for the cross-extension contract.",
+  "description": "Manifest shape for an `Action` extension. An action operates on one or more nodes in one of two modes: `deterministic` (code runs in-process, returns a report JSON directly) or `probabilistic` (kernel renders a prompt, a runner executes it against an LLM, the callback closes the job). **Structure-as-truth files**: every Action carries `<action-dir>/report.schema.json` (the JSON Schema for the report, MUST extend `report-base.schema.json`); probabilistic Actions additionally carry `<action-dir>/prompt.md` (the prompt template). The kernel resolves both by convention; missing or mis-placed files surface as `load-error`. A deterministic Action with a `prompt.md` in its folder is also `load-error` (config inconsistent). **`prob*` prefix convention**: manifest fields that only apply when `mode=probabilistic` start with `prob`; if a deterministic-only field ever appears, it starts with `det`.",
   "type": "object",
-  "required": ["id", "kind", "version", "mode", "reportSchemaRef"],
+  "required": ["version", "description"],
   "unevaluatedProperties": false,
   "properties": {
-    "kind": { "const": "action" },
     "mode": {
       "type": "string",
       "enum": ["deterministic", "probabilistic"],
-      "description": "`deterministic`: the plugin's code computes the report synchronously, no job file, no runner. `probabilistic`: the kernel renders a prompt + preamble into a job file; a runner executes it via `RunnerPort`; `sm record` closes the job."
+      "default": "deterministic",
+      "description": "`deterministic` (default): the plugin's code computes the report synchronously, no job file, no runner. `probabilistic`: the kernel renders `prompt.md` + preamble into a job file; a runner executes it via `RunnerPort`; `sm record` closes the job."
     },
-    "reportSchemaRef": {
-      "type": "string",
-      "description": "Absolute or relative reference to the JSON Schema the report MUST validate against. MUST extend `report-base.schema.json` (directly or transitively). Validation failure → job transitions to `failed` with reason `report-invalid`."
-    },
-    "expectedDurationSeconds": {
+    "probExpectedDurationSeconds": {
       "type": "integer",
       "minimum": 1,
-      "description": "Best-effort estimate of wall-clock duration. Drives TTL (`ttl = max(expectedDurationSeconds × graceMultiplier, minimumTtlSeconds)`). Required for `probabilistic`; advisory for `deterministic`."
-    },
-    "promptTemplateRef": {
-      "type": "string",
-      "description": "Path (relative to the extension file) to the prompt template the kernel renders at `sm job submit`. REQUIRED when `mode: probabilistic`; FORBIDDEN when `mode: deterministic`. The template MUST NOT interpolate user text outside `<user-content>` blocks (see `prompt-preamble.md`)."
+      "description": "Best-effort estimate of wall-clock duration when `mode=probabilistic`. Drives TTL (`ttl = max(probExpectedDurationSeconds × graceMultiplier, minimumTtlSeconds)`). Required for `probabilistic`; ignored otherwise. Renamed from `expectedDurationSeconds` with the structure-as-truth refactor, the `prob` prefix makes it clear at a glance which mode the field belongs to."
     },
     "precondition": {
       "type": "object",
-      "description": "Declarative filter that nodes must satisfy for this action to be applicable. Consumed by `--all` fan-out, UI button gating, `sm actions show`.",
-      "unevaluatedProperties": false,
+      "additionalProperties": false,
+      "description": "Declarative filter that nodes must satisfy for this action to be applicable. Consumed by `--all` fan-out, UI button gating, `sm actions show`. Also drives the inverse analyzer↔action relationship (Modelo B): `analyzerIds` declares which analyzers' findings this action is intended to resolve, replacing the deprecated `Analyzer.recommendedActions` map.",
       "properties": {
         "kind": {
           "type": "array",
-          "items": { "type": "string", "minLength": 1 },
-          "description": "Node kinds this action accepts. Open-by-design (matches `node.schema.json#/properties/kind`): an action declared with `kind: ['cursorRule']` is valid as long as some Provider classifies into `cursorRule`. Omitted → any kind."
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*/[a-z][a-zA-Z0-9]*$"
+          },
+          "description": "Qualified node kinds this action accepts (`<provider-plugin>/<kindName>`)."
         },
         "provider": {
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Provider ids whose nodes this action accepts. Omitted → any Provider."
-        },
-        "stability": {
-          "type": "array",
-          "items": { "type": "string", "enum": ["experimental", "stable", "deprecated"] },
-          "description": "Node stability filter."
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "description": "Provider ids whose nodes this action accepts."
         },
-        "custom": {
+        "analyzerIds": {
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Free-form precondition strings the kernel forwards to the action for runtime evaluation. Example: `frontmatter.metadata.source != null`."
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$"
+          },
+          "description": "Qualified analyzer ids whose findings this action is intended to resolve (Modelo B, replaces the deprecated `Analyzer.recommendedActions`). The UI surfaces matching actions in the node inspector under 'Resolve this issue' when the analyzer's id matches an entry here. Format `<plugin>/<analyzer>` or `<plugin>/<analyzer>:<sub-id>` when the analyzer emits sub-typed issues. Dangling references warn via `recommended-action-missing` in `sm plugins doctor` but do NOT block load."
         }
       }
-    },
-    "expectedTools": {
-      "type": "array",
-      "description": "Hint to a Skill agent / CLI runner about what tools the rendered prompt expects access to (`Bash`, `Read`, `WebSearch`, …). Host MAY filter or warn. No normative enforcement in v0.",
-      "items": { "type": "string" }
-    },
-    "fanOutPolicy": {
-      "type": "string",
-      "enum": ["per-node", "batch"],
-      "default": "per-node",
-      "description": "`per-node` (default): `sm job submit --all` produces one job per matching node. `batch`: produces one job whose prompt template receives the full list. Batch actions tend to hit context limits; use sparingly."
     }
   },
   "allOf": [
     { "$ref": "base.schema.json" },
     {
       "if": { "properties": { "mode": { "const": "probabilistic" } } },
-      "then": { "required": ["promptTemplateRef", "expectedDurationSeconds"] }
-    },
-    {
-      "if": { "properties": { "mode": { "const": "deterministic" } } },
-      "then": { "not": { "required": ["promptTemplateRef"] } }
+      "then": { "required": ["probExpectedDurationSeconds"] }
     }
   ]
 }

package/schemas/extensions/analyzer.schema.json

@@ -2,51 +2,53 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/extensions/analyzer.schema.json",
   "title": "ExtensionAnalyzer",
-  "description": "Manifest shape for an `Analyzer` extension. An analyzer consumes the full graph (nodes + links) after all extractors have run, emits `Issue[]`, and MAY emit view contributions to project findings into the UI. Analyzers are dual-mode: `deterministic` analyzers 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` analyzers invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (`sm job submit analyzer:<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 an `Analyzer` extension. An analyzer consumes the full graph (nodes + links) after all extractors have run, emits `Issue[]`, and MAY emit view contributions to project findings into the UI. Analyzers are dual-mode: `deterministic` analyzers 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` analyzers invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (`sm job submit analyzer:<id>`); their output MAY vary across runs and they NEVER participate in `sm scan`. Each issue emitted is tagged with `analyzer_id = <plugin-id>/<extension-id>` by default (the extension's qualified id, derived from structure); analyzers that need to discriminate sub-types append `:<sub-id>` at emit time. Severity is set per-emit (no manifest-level default).",
   "allOf": [
     { "$ref": "base.schema.json" }
   ],
   "type": "object",
-  "required": ["id", "kind", "version", "emitsAnalyzerIds", "defaultSeverity"],
+  "required": ["version", "description"],
   "unevaluatedProperties": false,
   "properties": {
-    "kind": { "const": "analyzer" },
     "mode": {
       "type": "string",
       "enum": ["deterministic", "probabilistic"],
       "default": "deterministic",
-      "description": "`deterministic` (default): pure code, byte-for-byte reproducible, runs during `sm check` and `sm scan`. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job; never participates in scan-time pipelines. The kernel rejects probabilistic analyzers that try to register scan-time hooks at load time. Omitting the field is equivalent to declaring `deterministic`."
+      "description": "`deterministic` (default): pure code, byte-for-byte reproducible, runs during `sm check` and `sm scan`. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job; never participates in scan-time pipelines. The kernel rejects probabilistic analyzers that try to register scan-time hooks at load time."
     },
-    "emitsAnalyzerIds": {
-      "type": "array",
-      "description": "List of `analyzer_id` values this analyzer may emit on issues. Typically a singleton (`trigger-collision` → emits `trigger-collision`). An analyzer emitting an `analyzer_id` not in this list → kernel logs `analyzer-id-violation` but keeps the issue (forward compatibility).",
-      "minItems": 1,
-      "items": { "type": "string" }
+    "precondition": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional declarative filter. The analyzer runs only when the graph contains at least one node matching every declared sub-filter. Same shape used by Extractor and Action.",
+      "properties": {
+        "kind": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*/[a-z][a-zA-Z0-9]*$"
+          },
+          "description": "Qualified node kinds the analyzer cares about (`<provider-plugin>/<kindName>`). Unknown qualified kinds load OK but emit a `precondition-kind-unknown` warning in `sm plugins doctor`."
+        },
+        "provider": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "description": "Provider ids whose nodes the analyzer cares about."
+        }
+      }
     },
-    "defaultSeverity": {
-      "type": "string",
-      "enum": ["error", "warn", "info"],
-      "description": "Severity attached by default to emitted issues. Analyzers MAY override per-issue."
-    },
-    "consumes": {
-      "type": "string",
-      "enum": ["nodes", "links", "both"],
-      "default": "both",
-      "description": "Which slices of the graph the analyzer reads. The kernel MAY pass a restricted view when this is a strict subset."
-    },
-    "configurable": {
-      "type": "boolean",
-      "default": false,
-      "description": "If true, the analyzer reads its own config from `config_preferences` under the key `analyzers.<id>.<field>`. Implementations MAY surface these in `sm config`."
-    },
-    "recommendedActions": {
-      "type": "array",
-      "description": "Qualified `<pluginId>/<id>` action ids the analyzer recommends running to address its findings. Per-node Actions only (Actions are per-node by design, see `IActionPrecondition`). Distinct from `Action.precondition`: the precondition declares 'this action applies to nodes matching X'; `recommendedActions` declares 'when this analyzer fires, these are the relevant actions to resolve the finding'. The UI surfaces matching Actions in the node inspector under 'Recommended for issues' alongside the always-applicable list driven by `Action.precondition`. Project-level cleanup operations (e.g. orphan file prune, contribution relink) are CLI verbs, not Actions, and therefore are NOT linked through this field. Each entry MUST be the qualified id of a registered Action; the kernel logs `recommended-action-missing` when a referenced action is not loaded but keeps the analyzer registered.",
-      "items": {
-        "type": "string",
-        "pattern": "^[a-z0-9-]+/[a-z0-9-]+$"
+    "ui": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "../view-slots.schema.json#/$defs/IViewContribution"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
       },
-      "uniqueItems": true
+      "description": "Plugin-contributed view contributions. Same contract as Extractor.ui (slot-driven, payload-validated). The analyzer emits per-node payloads via `ctx.emitContribution(<nodePath>, <contributionId>, payload)` during graph evaluation (signature differs from extractor: the nodePath is explicit because analyzers see the full graph, not a single node). Only `extractor` and `analyzer` kinds may declare this field. Renamed from `viewContributions` with the structure-as-truth refactor."
     }
   }
 }

package/schemas/extensions/base.schema.json

@@ -2,77 +2,48 @@
   "$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 (`provider`, `extractor`, `analyzer`, `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.",
+  "description": "Base manifest shape common to every extension kind. Kind-specific schemas (`provider`, `extractor`, `analyzer`, `action`, `formatter`, `hook`) extend this via `allOf` and add a kind-specific shape. Both `id` and `kind` are derived from the filesystem structure (`<plugin>/<kind-plural>/<id>/index.ts`, where the parent folder dictates the kind and the leaf folder dictates the id), so they are NOT manifest fields. Manifests carrying `id` or `kind` are rejected as `invalid-manifest`. Closed-content enforcement (unknown keys = bug) lives on the kind schemas via `unevaluatedProperties: false`; those see base's evaluated keys through the `allOf` composition.",
   "type": "object",
-  "required": ["id", "kind", "version"],
+  "required": ["version", "description"],
   "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
-      "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/annotations`, `core/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": ["provider", "extractor", "analyzer", "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 reproducibility."
     },
     "description": {
       "type": "string",
-      "description": "One-to-three sentences explaining what the extension does. Rendered by `sm <kind>s list`."
-    },
-    "stability": {
-      "type": "string",
-      "enum": ["experimental", "stable", "deprecated"],
-      "default": "stable",
-      "description": "Maturity tag. The kernel MAY warn when an `experimental` extension is used in CI (`--strict`)."
+      "minLength": 1,
+      "description": "Required short description (1-3 sentences) shown by `sm <kind>s list` and the UI inspector. English-only per AGENTS.md."
     },
-    "preconditions": {
-      "type": "array",
-      "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": {
-      "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": {
+    "annotation": {
       "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."
-          }
+      "required": ["schema"],
+      "additionalProperties": false,
+      "description": "Optional, opt-in declaration of a single sidecar annotation key contributed by this extension. The key is the extension's id (i.e. the leaf folder name). Extensions that need multiple annotation keys split into multiple extensions. The runtime exposes the registered catalog via `kernel.getRegisteredAnnotationKeys()` for UI autocomplete; the built-in `core/unknown-field` Analyzer emits a warning on truly unrecognized keys (typo guard). See `plugin-author-guide.md` §Annotation contribution.",
+      "properties": {
+        "schema": {
+          "type": "object",
+          "description": "Inline JSON Schema for this contribution's value. The value can be a scalar, an array, or a rich object; the schema is full JSON Schema. Validated when the kernel routes a sidecar write through this extension's namespace (or root key, see `location`). 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)."
         }
-      },
-      "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` Analyzer emits a warning on truly unrecognized keys (typo guard). See `plugin-author-guide.md` §Annotation contributions for the worked examples."
+      }
     },
-    "viewContributions": {
+    "settings": {
       "type": "object",
-      "additionalProperties": {
-        "$ref": "../view-slots.schema.json#/$defs/IViewContribution"
-      },
+      "additionalProperties": { "$ref": "../input-types.schema.json#/$defs/ISettingDeclaration" },
       "propertyNames": {
         "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
       },
-      "description": "Plugin-contributed view contributions. Each entry declares one rendering surface in the UI by picking a `slot` name from the closed catalog at `view-slots.schema.json#/$defs/SlotName`. The kernel validates the manifest at load (`invalid-manifest` on unknown slot); the plugin emits per-node payloads via `ctx.emitContribution(<contributionId>, payload)` during scan; the runtime validates payloads against the slot's payload schema in `view-slots.schema.json#/$defs/payloads/<slot>`; off-shape payloads emit `extension.error` and drop silently (mirror of `emitLink` off-contract drop). The kernel exposes the runtime catalog via `kernel.getRegisteredViewContributions()`; the BFF surfaces it at `GET /api/contributions/registered`. The plugin author picks ONE slot, that is the only choice; the slot fixes both the renderer and the payload shape. See `plugin-author-guide.md` §View contributions for worked examples."
+      "description": "Extension user-configurable settings. Each entry picks an `input-type` from the closed catalog at `input-types.schema.json#/$defs/InputTypeName`. The extension author NEVER writes JSON Schema for settings, they pick by `type` name and provide per-type parameters (label, default, min/max, options for enums, etc.). The kernel exposes the 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. Settings are read once at extension invocation; changing a setting requires `sm scan` to re-emit (per ROADMAP.md decision D4). Settings live per-extension (not per-plugin) since the structure-as-truth refactor."
     }
   }
 }