@skill-map/spec 0.2.1 → 0.4.0

package/job-lifecycle.md

@@ -53,11 +53,12 @@ Any other transition attempt MUST be rejected and MUST NOT mutate state. Impleme
 2. Resolve the target node (`bodyHash`, `frontmatterHash`). Fail with exit 5 if the node does not exist.
 3. Compute `contentHash = sha256(actionId + actionVersion + bodyHash + frontmatterHash + promptTemplateHash)`.
 4. **Duplicate check**: query `state_jobs` for any row with `(actionId, actionVersion, nodeId, contentHash)` AND `status IN ('queued', 'running')`. If found, refuse with exit 3 and print the existing job id (unless `--force`).
-5. Compute `ttlSeconds = max(action.expectedDurationSeconds × graceMultiplier, minimumTtlSeconds)`. Frozen for the life of this job. User overrides via `--ttl`.
-6. Generate `nonce` (implementation-chosen; MUST be cryptographically random, ≥ 128 bits of entropy).
-7. Render the job file at `.skill-map/jobs/<id>.md`, applying the canonical preamble (see `prompt-preamble.md`).
-8. Insert a row in `state_jobs` with `status = 'queued'`, `createdAt = now`.
-9. Return the job id.
+5. Compute `ttlSeconds` per §TTL resolution below. Frozen on `state_jobs.ttlSeconds` for the life of this job.
+6. Resolve `priority` (integer, default `0`). Precedence (lowest → highest): action manifest `defaultPriority` → user config `jobs.perActionPriority.<actionId>` → flag `--priority <n>`. Higher runs first; ties broken by `createdAt ASC`. Negative values are permitted and run after the default bucket. The resolved value is frozen on `state_jobs.priority` at submit time and is immutable for the life of the job.
+7. Generate `nonce` (implementation-chosen; MUST be cryptographically random, ≥ 128 bits of entropy).
+8. Render the job file at `.skill-map/jobs/<id>.md`, applying the canonical preamble (see `prompt-preamble.md`).
+9. Insert a row in `state_jobs` with `status = 'queued'`, `createdAt = now`.
+10. Return the job id.
 
 `--all` fans out one job per node matching the action's `preconditions`. Each fan-out job is independent: some may be duplicates and be refused, others succeed. The CLI reports a summary.
 
@@ -88,7 +89,7 @@ The second `AND status = 'queued'` guards against a race where two runners selec
 
 **Non-SQLite implementations**: MUST provide an equivalent single-statement atomic transition. A two-step `SELECT then UPDATE` is NOT acceptable — it is observable as a double-claim bug.
 
-`sm job claim` exposes this primitive to Skill runners: returns the id on stdout (exit 0) or exits 1 if the queue is empty.
+`sm job claim` exposes this primitive to Skill agents (and any driving adapter that wants to drain from outside a CLI-runner loop): returns the id on stdout (exit 0) or exits 1 if the queue is empty.
 
 ---
 
@@ -113,16 +114,47 @@ Number of rows affected is reported as `run.reap.completed.reapedCount` in the e
 
 Implementations MAY expose `sm job reap` as an explicit verb for diagnostics, but MUST perform reaping automatically inside `sm job run`.
 
-### TTL precedence
+### TTL resolution
 
-When computing the TTL at submit time (in order):
+The kernel resolves the effective TTL for a new job in three conceptual steps. The resolved value is written to `state_jobs.ttlSeconds` at submit time and is immutable for the life of the job.
 
-1. Global default (`minimumTtlSeconds` from config).
-2. Action manifest (`expectedDurationSeconds`).
-3. User config override (`jobs.perActionTtl.<actionId>`).
-4. Flag (`sm job submit --ttl <seconds>`).
+#### Step 1 — Base duration
 
-Later wins. The resolved value is written to `state_jobs.ttlSeconds` and is immutable for the life of the job.
+A seconds integer that represents how long the action is expected to run before the grace multiplier kicks in:
+
+1. Action manifest `expectedDurationSeconds`, if declared.
+2. Otherwise, config `jobs.ttlSeconds` (default: `3600`).
+
+The base duration exists even for actions that cannot estimate their own runtime (typically `mode: local`); the global config value ensures the formula below is always well-defined.
+
+#### Step 2 — Computed TTL
+
+```
+computed = max(base × jobs.graceMultiplier, jobs.minimumTtlSeconds)
+```
+
+Config defaults: `jobs.graceMultiplier = 3`, `jobs.minimumTtlSeconds = 60`.
+
+`minimumTtlSeconds` is a **floor**, not a default. It guarantees no job is claimed with a sub-minute deadline regardless of how small the base duration is. It never participates as an initial value.
+
+#### Step 3 — User overrides
+
+Two optional overrides, evaluated in order; the later one wins and replaces everything above it:
+
+1. Config `jobs.perActionTtl.<actionId>` — integer seconds. Replaces the computed TTL entirely; the formula is skipped for that action id.
+2. Flag `sm job submit --ttl <seconds>` — integer seconds. Highest precedence. Replaces anything.
+
+Negative or zero values MUST be rejected with exit 2 at submit time.
+
+#### Worked examples
+
+| Action manifest | Config | Flag | Result |
+|---|---|---|---|
+| `expectedDurationSeconds: 120` | defaults | — | `max(120 × 3, 60) = 360` |
+| none | defaults | — | `max(3600 × 3, 60) = 10800` |
+| `expectedDurationSeconds: 10` | defaults | — | `max(10 × 3, 60) = 60` (floor bites) |
+| `expectedDurationSeconds: 120` | `jobs.perActionTtl.foo: 900` | — | `900` (override skips formula) |
+| any | any | `--ttl 45` | `45` (flag wins outright) |
 
 ---
 
@@ -158,7 +190,7 @@ Post-completion, the check is NOT performed: resubmitting a completed job is alw
 
 ## Concurrency
 
-MVP (v0.x): **one job at a time**. `sm job run --all` drains sequentially. Enforced by the claim semantics above — there is no pool or scheduler.
+Through `v1.0` (spec `v0.x`): **one job at a time**. `sm job run --all` drains sequentially. Enforced by the claim semantics above — there is no pool or scheduler.
 
 The event schema carries a `jobId` on every event specifically so that parallel execution becomes a non-breaking extension. A future implementation MAY spawn multiple claim/run loops concurrently and interleave events; consumers identify which job an event belongs to by `jobId`.
 
@@ -211,3 +243,5 @@ The state machine diagram above is **stable** as of spec v1.0.0. Adding a new st
 The `contentHash` formula is **stable**. Changing what goes into the hash breaks duplicate detection across versions and is a major bump.
 
 The atomic-claim semantics are **stable**. A double-claim would be a silent correctness bug observable through event-stream anomalies.
+
+The TTL resolution procedure (§TTL resolution) is **stable** as of the next spec release. The three-step structure (base → computed → overrides) and the four config keys (`jobs.ttlSeconds`, `jobs.graceMultiplier`, `jobs.minimumTtlSeconds`, `jobs.perActionTtl`) are locked; adding a new override source is a minor bump, changing the formula shape is a major bump.

package/package.json

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

package/plugin-kv-api.md

@@ -2,7 +2,7 @@
 
 Normative contract for plugin-accessible persistence. Two modes exist (see `db-schema.md` for the catalog entries):
 
-- **Mode A — KV**: plugin uses the kernel-provided `ctx.store.*` accessor. Backed by the shared `state_plugin_kv` table.
+- **Mode A — KV**: plugin uses the kernel-provided `ctx.store.*` accessor. Backed by the shared `state_plugin_kvs` table.
 - **Mode B — Dedicated**: plugin owns its own tables with the `plugin_<normalizedId>_` prefix, migrated by the kernel.
 
 This document defines mode A in full and clarifies the boundary with mode B. Implementations MUST expose this API to every plugin that declares `"storage": { "mode": "kv" }` in its manifest.
@@ -54,7 +54,7 @@ Operations MAY be additionally scoped by `nodePath`:
 - **Global KV (no `nodePath`)**: `{pluginId, nodePath: null, key}`. One row per plugin + key.
 - **Node-scoped KV (with `nodePath`)**: `{pluginId, nodePath: "<path>", key}`. One row per plugin + node + key.
 
-Both scopes share the same underlying `state_plugin_kv` table (see `db-schema.md`). The `nodePath` column is nullable; implementations MUST use a sentinel empty string internally when the backing engine rejects NULL in composite primary keys.
+Both scopes share the same underlying `state_plugin_kvs` table (see `db-schema.md`). The `nodePath` column is nullable; implementations MUST use a sentinel empty string internally when the backing engine rejects NULL in composite primary keys.
 
 ### Semantics
 
@@ -182,10 +182,12 @@ A plugin MUST declare **exactly one** storage mode. Mixing modes in the same plu
 
 ## Backup and retention
 
-- Mode A rows are stored in `state_plugin_kv` and are backed up with `sm db backup`.
+- Mode A rows are stored in `state_plugin_kvs` and are backed up with `sm db backup`.
 - Mode B rows live in the plugin's dedicated tables, prefixed `plugin_<id>_`, and are likewise backed up.
-- `sm plugins disable <id>` does NOT drop the plugin's data — disabled plugins keep their KV rows and dedicated tables. `sm plugins forget <id>` (post-MVP) is the verb that wipes.
-- `sm db reset` drops `scan_*` + `state_*`. This includes `state_plugin_kv` (mode A) AND every `plugin_<id>_*` table (mode B). Users MUST be warned by the CLI before `reset` proceeds.
+- `sm plugins disable <id>` does NOT drop the plugin's data — disabled plugins keep their KV rows and dedicated tables. `sm plugins forget <id>` (deferred to post-`v1.0`) is the verb that wipes.
+- `sm db reset` (no modifier) drops only `scan_*`. Plugin KV rows (mode A) and plugin-dedicated tables (mode B) are **preserved** — the reset is non-destructive to plugin storage.
+- `sm db reset --state` drops `state_*` AND every `plugin_<normalized_id>_*` table, which includes `state_plugin_kvs` (mode A) AND the plugin-dedicated tables (mode B). The CLI MUST require interactive confirmation unless `--yes` is passed.
+- `sm db reset --hard` deletes the DB file entirely, destroying all plugin storage regardless of mode.
 
 ---
 
@@ -195,7 +197,7 @@ Mode A is perfectly isolated at the row level: the accessor physically cannot se
 
 Mode B is **isolated against accidents, not hostile code**. The scoped `Database` wrapper rejects cross-namespace queries at runtime. But a malicious plugin running in the same JavaScript process can bypass the wrapper by importing raw engine bindings directly. Plugins are user-placed code; the kernel trusts the user's judgement at install time.
 
-Post-v1.0 work: signed manifest, sandboxed worker-thread isolation, per-plugin DB file. None of these land before cut 1.
+Post-v1.0 work: signed manifest, sandboxed worker-thread isolation, per-plugin DB file. None of these land before `v0.5.0`.
 
 ---
 

package/schemas/extensions/action.schema.json

@@ -0,0 +1,81 @@
+{
+  "$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: `local` (code runs in-process, returns a report JSON directly) or `invocation-template` (kernel renders a prompt, a runner executes it, the callback closes the job). The `mode` discriminator drives which additional fields are required.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "mode", "reportSchemaRef"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "action" },
+    "mode": {
+      "type": "string",
+      "enum": ["local", "invocation-template"],
+      "description": "`local`: the plugin's code computes the report synchronously, no job file, no runner. `invocation-template`: the kernel renders a prompt + preamble into a job file; a runner executes it; `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": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Best-effort estimate of wall-clock duration. Drives TTL (`ttl = max(expectedDurationSeconds × graceMultiplier, minimumTtlSeconds)`). Required for `invocation-template`; advisory for `local`."
+    },
+    "promptTemplateRef": {
+      "type": "string",
+      "description": "Path (relative to the extension file) to the prompt template the kernel renders at `sm job submit`. REQUIRED when `mode: invocation-template`; FORBIDDEN when `mode: local`. The template MUST NOT interpolate user text outside `<user-content>` blocks (see `prompt-preamble.md`)."
+    },
+    "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`.",
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["skill", "agent", "command", "hook", "note"] },
+          "description": "Node kinds this action accepts. Omitted → any kind."
+        },
+        "adapter": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Adapter ids whose nodes this action accepts. Omitted → any adapter."
+        },
+        "stability": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["experimental", "stable", "deprecated"] },
+          "description": "Node stability filter."
+        },
+        "custom": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Free-form precondition strings the kernel forwards to the action for runtime evaluation. Example: `frontmatter.metadata.source != null`."
+        }
+      }
+    },
+    "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": [
+    {
+      "if": { "properties": { "mode": { "const": "invocation-template" } } },
+      "then": { "required": ["promptTemplateRef", "expectedDurationSeconds"] }
+    },
+    {
+      "if": { "properties": { "mode": { "const": "local" } } },
+      "then": { "not": { "required": ["promptTemplateRef"] } }
+    }
+  ]
+}

package/schemas/extensions/adapter.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/adapter.schema.json",
+  "title": "ExtensionAdapter",
+  "description": "Manifest shape for an `Adapter` extension. An adapter recognizes a platform (Claude Code, Codex, Gemini, Obsidian vault, generic MD) and classifies each candidate file into a node `kind`. Exactly zero or one adapter MUST match any given file; multiple matches → the kernel emits an issue `adapter-ambiguous` and the file is left unclassified. Stability: stable as of spec v1.0.0 except where noted.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "emits", "defaultRefreshAction"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "adapter" },
+    "emits": {
+      "type": "array",
+      "description": "Node kinds this adapter may classify files into.",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": ["skill", "agent", "command", "hook", "note"]
+      }
+    },
+    "roots": {
+      "type": "array",
+      "description": "Path globs (relative to scope root) that this adapter SHOULD be consulted for. Advisory — the kernel walks all roots and consults every adapter regardless, but this field lets `sm doctor` warn when no file matched a specific adapter (i.e. the adapter was loaded for a platform that isn't in this scope).",
+      "items": { "type": "string" }
+    },
+    "defaultRefreshAction": {
+      "type": "object",
+      "description": "Map from node `kind` to the action id the UI's probabilistic-refresh surface (`🧠 prob`) submits for that kind. MUST cover every kind listed in `emits`. Referenced action ids MUST resolve at load time; a dangling reference disables the adapter with status `invalid-manifest`.",
+      "propertyNames": {
+        "enum": ["skill", "agent", "command", "hook", "note"]
+      },
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+      }
+    }
+  }
+}

package/schemas/extensions/audit.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/audit.schema.json",
+  "title": "ExtensionAudit",
+  "description": "Manifest shape for an `Audit` extension. An audit is a hardcoded, deterministic workflow that composes rules and/or local actions into a single report. Audits MUST NOT submit LLM-backed actions — their defining property is reproducibility. An audit that needs probabilistic signal is the wrong shape; emit a `Findings` surface via LLM verbs instead.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "composes", "reportSchemaRef"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "audit" },
+    "composes": {
+      "type": "array",
+      "description": "Ordered list of rule ids and/or local action ids the audit executes in sequence. The kernel resolves each id in the registry at load time; a dangling reference disables the audit with status `invalid-manifest`.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["kind", "id"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "type": "string", "enum": ["rule", "action"] },
+          "id": { "type": "string" },
+          "failFast": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, the audit stops at the first error-severity issue this step emits. Default: collect everything and continue."
+          }
+        }
+      }
+    },
+    "reportSchemaRef": {
+      "type": "string",
+      "description": "Reference to the JSON Schema of the audit's report shape. Audits do NOT extend `report-base.schema.json` — they are deterministic and therefore carry no `safety` / `confidence`. Their shape is kind-specific."
+    },
+    "exitCodeMap": {
+      "type": "object",
+      "description": "How the audit report maps to CLI exit codes. Absent → standard behaviour: exit 0 on pass, 1 on any error-severity issue, 2 on operational error.",
+      "additionalProperties": false,
+      "properties": {
+        "pass": { "type": "integer", "default": 0 },
+        "fail": { "type": "integer", "default": 1 }
+      }
+    }
+  }
+}

package/schemas/extensions/base.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/base.schema.json",
+  "title": "ExtensionBase",
+  "description": "Base manifest shape common to every extension kind. Kind-specific schemas (`adapter`, `detector`, `rule`, `action`, `audit`, `renderer`) extend this via `allOf` and add a discriminant `kind` literal plus kind-specific fields. camelCase keys throughout. `additionalProperties: false` — the extension manifest shape is kernel-controlled and unknown keys are a bug.",
+  "type": "object",
+  "required": ["id", "kind", "version"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Kebab-case identifier unique within the extension's kind across all loaded plugins. The built-in default set uses bare ids (`claude`, `frontmatter`, `trigger-collision`). Third-party extensions SHOULD namespace with their plugin id (`my-plugin/foo-detector`) to avoid collisions."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["adapter", "detector", "rule", "action", "audit", "renderer"],
+      "description": "Discriminant. MUST match the file exporting this manifest; kind mismatch → load-error."
+    },
+    "version": {
+      "type": "string",
+      "description": "Extension semver. Bumped independently from the plugin version; frozen into `state_executions.extension_version` on every run for audit reproducibility."
+    },
+    "description": {
+      "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`)."
+    },
+    "preconditions": {
+      "type": "array",
+      "description": "Free-form predicates the kernel evaluates before offering this extension. Canonical keys: `kind=<node-kind>`, `adapter=<adapter-id>`, `frontmatter.<path>=<value>`. Unknown keys are skipped with a warning, not rejected.",
+      "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."
+    }
+  }
+}

package/schemas/extensions/detector.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/detector.schema.json",
+  "title": "ExtensionDetector",
+  "description": "Manifest shape for a `Detector` extension. A detector consumes a parsed node (frontmatter + body) and emits `Link[]` pointing to other nodes or to external URLs (the latter only if it is the designated URL-counter detector). Detectors run in isolation: they MUST NOT read other nodes, the graph, or the DB. Cross-node reasoning lives in Rules.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "emitsLinkKinds", "defaultConfidence"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "detector" },
+    "emitsLinkKinds": {
+      "type": "array",
+      "description": "Subset of `Link.kind` values this detector is allowed to emit. Emitting an unlisted kind at runtime → kernel rejects the link and logs `detector-kind-violation`.",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": ["invokes", "references", "mentions", "supersedes"]
+      }
+    },
+    "defaultConfidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "Confidence attached to emitted links by default. Detectors MAY override per-link at emission time."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["frontmatter", "body", "both"],
+      "default": "both",
+      "description": "Which part of the node this detector consumes. The kernel passes only the declared scope to the detector — a `frontmatter` detector that tries to read `body` receives an empty string."
+    }
+  }
+}

package/schemas/extensions/renderer.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/renderer.schema.json",
+  "title": "ExtensionRenderer",
+  "description": "Manifest shape for a `Renderer` extension. A renderer serializes the graph (or a filtered subgraph) into a string in a declared format. Renderers are invoked by `sm graph --format <format>` and `sm export`. Output MUST be byte-deterministic for the same input graph — the snapshot-test suite relies on this.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "format"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "renderer" },
+    "format": {
+      "type": "string",
+      "description": "Format identifier consumed by `--format`. Built-in set: `ascii`, `mermaid`, `dot`, `json`. Third-party renderers MAY register new format ids; collisions are a load-time error."
+    },
+    "contentType": {
+      "type": "string",
+      "description": "MIME-like hint used by the Server when streaming rendered output over HTTP (e.g. `text/plain`, `image/svg+xml`, `application/json`). Advisory.",
+      "default": "text/plain"
+    },
+    "supportsFilter": {
+      "type": "boolean",
+      "default": true,
+      "description": "If true, the renderer accepts the `--filter` expression used by `sm export`. If false, `sm export --format <this>` rejects `--filter` with exit 2."
+    }
+  }
+}

package/schemas/extensions/rule.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/extensions/rule.schema.json",
+  "title": "ExtensionRule",
+  "description": "Manifest shape for a `Rule` extension. A rule consumes the full graph (nodes + links) after all detectors have run and emits `Issue[]`. Rules MUST be deterministic: same graph in → same issues out, byte-for-byte. Any source of non-determinism (time, random, network) is forbidden and is a conformance violation.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["id", "kind", "version", "emitsRuleIds", "defaultSeverity"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "rule" },
+    "emitsRuleIds": {
+      "type": "array",
+      "description": "List of `rule_id` values this rule may emit on issues. Typically a singleton (`trigger-collision` → emits `trigger-collision`). A rule emitting a `rule_id` not in this list → kernel logs `rule-id-violation` but keeps the issue (forward compatibility).",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "defaultSeverity": {
+      "type": "string",
+      "enum": ["error", "warn", "info"],
+      "description": "Severity attached by default to emitted issues. Rules MAY override per-issue."
+    },
+    "consumes": {
+      "type": "string",
+      "enum": ["nodes", "links", "both"],
+      "default": "both",
+      "description": "Which slices of the graph the rule reads. The kernel MAY pass a restricted view when this is a strict subset."
+    },
+    "configurable": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, the rule reads its own config from `config_preferences` under the key `rules.<id>.<field>`. Implementations MAY surface these in `sm config`."
+    }
+  }
+}

package/schemas/frontmatter/agent.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/frontmatter/agent.schema.json",
   "title": "FrontmatterAgent",
-  "description": "Frontmatter shape for nodes classified as `agent`. Extends `base.schema.json`. Kind-specific fields: `model`, `tools`. Color, when needed, lives in `metadata.color` (inherited from base).",
+  "description": "Frontmatter shape for nodes classified as `agent`. Extends `base.schema.json`. Kind-specific field: `model`. The `tools` and `allowedTools` fields live on `base` and apply here unchanged (see `base.schema.json`). Color, when needed, lives in `metadata.color` (inherited from base).",
   "allOf": [
     { "$ref": "base.schema.json" }
   ],
@@ -12,11 +12,6 @@
     "model": {
       "type": "string",
       "description": "Model identifier for this agent (e.g. `sonnet`, `opus`, `haiku`, or a full `claude-*` id). Free-form string; adapters MAY validate against a platform-specific enum."
-    },
-    "tools": {
-      "type": "array",
-      "description": "Tools available to this agent. Tokens are platform-specific.",
-      "items": { "type": "string" }
     }
   }
 }

package/schemas/frontmatter/base.schema.json

@@ -34,6 +34,16 @@
       "type": "string",
       "description": "SPDX license identifier (e.g. `MIT`, `Apache-2.0`)."
     },
+    "tools": {
+      "type": "array",
+      "description": "Tools this node requires when executed by a host. Allowlist semantics: if present, the host MUST restrict the node to exactly these tools (matching Claude Code subagent `tools` frontmatter). Free-form strings — token vocabulary is platform-specific (e.g. `Read`, `Grep`, `Bash`, `Bash(git add *)`). Kind-specific interpretation: an `agent` node's allowlist constrains the spawned subagent; a `skill` node's allowlist is a hint for the host since skills typically inherit their parent's tools. Omit to inherit the host's default. Denormalized into `node.tools_json` for query.",
+      "items": { "type": "string" }
+    },
+    "allowedTools": {
+      "type": "array",
+      "description": "Tools the host MAY use without triggering a per-use permission prompt while this node is active (matching Claude Code skill `allowed-tools` frontmatter). Pre-approval semantics, distinct from `tools` (allowlist): every tool not listed remains callable, but governed by the host's normal permission settings. Accepts argument-scoped patterns where the host supports them (`Bash(git add *)`). Free-form strings. Omit to defer to host defaults.",
+      "items": { "type": "string" }
+    },
     "metadata": {
       "type": "object",
       "description": "Structured metadata. REQUIRED. `version` inside is REQUIRED; all other fields are optional.",