@skill-map/spec 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Spec changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 69572fd: Align `spec/index.json` with the manifest changes declared in the `0.3.0` changelog (they had been documented but never written to the file), and fix two small referential drifts surfaced in the same audit pass.
+
+  **`spec/index.json`** — closes the gap between what `0.3.0` notes promised and what actually shipped:
+
+  - `specVersion` top-level field renamed to `indexPayloadVersion`. The old name collided semantically with `specPackageVersion` and with every other use of `specVersion` in the spec (compat logic, `scan-result.specVersion`, `sm help --format json`). `indexPayloadVersion` describes the shape of `index.json` itself and bumps only when this manifest's structure changes — pinned at `0.0.1` today. **This is the breaking rename already announced in the `0.3.0` release notes.**
+  - `schemas.topLevel` gains `history-stats` (shape for `sm history stats --json`, already referenced from `cli-contract.md` §History and hashed under `integrity.files`).
+  - New `schemas.extensions` subsection listing the 7 kind-manifest schemas (`base`, `adapter`, `detector`, `rule`, `action`, `audit`, `renderer`) — already required by `architecture.md` §Extension kinds for load-time manifest validation and already present under `schemas/extensions/`.
+
+  **`spec/versioning.md` §Change process step 4** — the parenthetical `(see CLAUDE.md: "Every feature: update spec/ first, then src/")` was stale. `CLAUDE.md` has been a bare `@AGENTS.md` pointer since the 18d0c20 dedup; the rule itself lives in `AGENTS.md`. Reference fixed.
+
+  **`spec/CHANGELOG.md` 0.3.0 entry** — text-only renumber of "decision #40a" → "decision #40". The sub-letter was a leftover from an unreleased draft; the roadmap Decision log uses `40` as the canonical anchor (see companion ROADMAP edit).
+
+  Classification: minor per §Pre-1.0 (`0.Y.Z`). The `specVersion → indexPayloadVersion` rename is breaking for any consumer that read the old field, but the old name never shipped alongside a file that spelled it `indexPayloadVersion` — the rename is being applied here for the first time, not re-applied. The `topLevel`/`extensions` additions are purely additive.
+
+### Patch Changes
+
+- 2699276: Fix the extension-kind schemas so they actually validate against real extension manifests.
+
+  The six kind schemas (`schemas/extensions/action.schema.json`, `adapter.schema.json`, `audit.schema.json`, `detector.schema.json`, `renderer.schema.json`, `rule.schema.json`) used `additionalProperties: false` together with `allOf: [{ $ref: "base.schema.json" }]` — a classic JSON Schema Draft 2020-12 footgun. `additionalProperties` is evaluated independently per schema in an `allOf`, so when a consumer validated `{ id, kind, version, emitsLinkKinds, defaultConfidence }` against `detector.schema.json`, detector's `additionalProperties: false` rejected `id` / `version` / `description` (defined only on `base`) and base's own `additionalProperties: false` would have rejected `emitsLinkKinds` / `defaultConfidence` — the union of both closures is empty. No real extension could ever pass validation.
+
+  Discovered during Step 1b while wiring the AJV validators in `skill-map` (kernel plugin loader). The right fix is `unevaluatedProperties: false` — it sees through `allOf` composition and only rejects keys that no sibling schema declared.
+
+  Changes:
+
+  - Every kind schema: `additionalProperties: false` → `unevaluatedProperties: false` at the manifest level. Nested `additionalProperties: false` declarations inside `$defs` / `properties` were likewise replaced with `unevaluatedProperties: false` where they participate in `allOf` composition (e.g. `action.schema.json#/$defs/Parameter`, `audit.schema.json` nested items).
+  - `extensions/base.schema.json`: closure removed entirely. Closed-content is now enforced only on the kind schemas, which see base's properties as "evaluated" through the `allOf` — adding closure to base too would force every kind to re-list every base key to stay valid.
+  - `base.schema.json` description updated to spell out the new composition rule so a future reader does not accidentally re-introduce the footgun.
+
+  Classification: patch. No normative shape changes — every manifest that was _supposed_ to pass under the old schemas still passes under the new ones, and the authored intent (closed content on kind manifests, additive base fields) is preserved. Consumers that never wired strict JSON Schema validation see zero behavioural change.
+
 ## 0.4.0
 
 ### Minor Changes
@@ -80,7 +114,7 @@
   - `tokenizer: string` (default `cl100k_base`) — name of the offline tokenizer; stored alongside counts so consumers know which encoder produced them.
   - `scan.maxFileSizeBytes: integer` (default `1048576`) — files larger are skipped with an `info` log.
   - `jobs.ttlSeconds: integer` (default `3600`) — global fallback TTL when an action manifest omits `expectedDurationSeconds` (typically `mode: local` actions where the field is advisory).
-  - `jobs.perActionPriority: { <actionId>: integer }` — per-action priority overrides. Frozen on `state_jobs.priority` at submit time; overrides action manifest `defaultPriority`; overridden by CLI `--priority`. Ratifies decision #40a in the schema.
+  - `jobs.perActionPriority: { <actionId>: integer }` — per-action priority overrides. Frozen on `state_jobs.priority` at submit time; overrides action manifest `defaultPriority`; overridden by CLI `--priority`. Ratifies decision #40 in the schema.
   - `jobs.retention: { completed, failed }` — GC policy for `state_jobs` rows. Defaults: `completed = 2592000` (30 days), `failed = null` (never auto-prune; keep for post-mortem). `sm job prune` reads these; no implicit pruning during normal verbs.
 
   **`job-events.md` — new `Non-job events` section, Stability: experimental across v0.x:**

package/index.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.0.1",
+  "indexPayloadVersion": "0.0.1",
   "dialect": "https://json-schema.org/draft/2020-12/schema",
   "canonicalUrlPrefix": "https://skill-map.dev/spec/v0",
   "schemas": {
@@ -43,6 +43,40 @@
       {
         "id": "conformance-case",
         "path": "schemas/conformance-case.schema.json"
+      },
+      {
+        "id": "history-stats",
+        "path": "schemas/history-stats.schema.json"
+      }
+    ],
+    "extensions": [
+      {
+        "id": "extensions/base",
+        "path": "schemas/extensions/base.schema.json"
+      },
+      {
+        "id": "extensions/adapter",
+        "path": "schemas/extensions/adapter.schema.json"
+      },
+      {
+        "id": "extensions/detector",
+        "path": "schemas/extensions/detector.schema.json"
+      },
+      {
+        "id": "extensions/rule",
+        "path": "schemas/extensions/rule.schema.json"
+      },
+      {
+        "id": "extensions/action",
+        "path": "schemas/extensions/action.schema.json"
+      },
+      {
+        "id": "extensions/audit",
+        "path": "schemas/extensions/audit.schema.json"
+      },
+      {
+        "id": "extensions/renderer",
+        "path": "schemas/extensions/renderer.schema.json"
       }
     ],
     "frontmatter": [
@@ -156,11 +190,11 @@
       }
     ]
   },
-  "specPackageVersion": "0.4.0",
+  "specPackageVersion": "0.5.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "38364d4ca30475e3e1eb35019037532547c1e5bdc245ecfcc60eb5e1570985d0",
+      "CHANGELOG.md": "adf0e49a213a8996cc2689749c47f2ed27cb9d31b40c18cece07b6d6ef94cd28",
       "README.md": "a233e6b5ab1c41c13cb4790485f0514f7c111880eb70165e77e1253999069120",
       "architecture.md": "be4085b7bbb3476f8a9d6df940b5794839b936ac5dd1921203a91558b008c7bc",
       "cli-contract.md": "7657b6e60089afdd3644e7e38d96593158349259ab105d76199ce5eb65993cae",
@@ -182,13 +216,13 @@
       "prompt-preamble.md": "9b7478ddce0a77043983f35932677d702319348048fe5d6b1c60257bd1c9f605",
       "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
-      "schemas/extensions/action.schema.json": "d22a98aca9ad3d7bee475b370135372913e5756ad5987084c77e91e04c8472e8",
-      "schemas/extensions/adapter.schema.json": "882c23b0c914eb37af5d50704268e028eb94e1601ceb5fc61aaf932f1ab82eb2",
-      "schemas/extensions/audit.schema.json": "a871f96d340a9b72fc4cd3ce6f56a553bb6b56636e342501dcb5d3b724475502",
-      "schemas/extensions/base.schema.json": "845f0abe723f1916354f05f6c1cd134c4b8da25fd612976f5ca1e205bf0d0fdb",
-      "schemas/extensions/detector.schema.json": "58957bf96ca58218eadd1fceecfb0203bcc11d93eb8cef6bba90e89deca3e195",
-      "schemas/extensions/renderer.schema.json": "a8cfc40c8be525fb69e62d53bd98f622b82599bb95e3fac66ec324d4298e46f5",
-      "schemas/extensions/rule.schema.json": "eca5a877f3eb6d52cbe62e97bbd2ca3ccd2724bbc760e16e63d7473dfb4fa61a",
+      "schemas/extensions/action.schema.json": "c7520d3cefecf75d27d3e04473821fd6e5dc5a7924eede147f74275ba6caccad",
+      "schemas/extensions/adapter.schema.json": "429b865e738664bb437ac62690a2d7282ce992339fbb300417c73625f5cdb7c8",
+      "schemas/extensions/audit.schema.json": "9ec2c68584707696423a1d617bc1e003cf8ee96a2c67b2f008f6647b2927c86c",
+      "schemas/extensions/base.schema.json": "c832a8c9976a7ddc70b8f9226a54de14aa3e85d71bc77ed7a8671a77d599c0e4",
+      "schemas/extensions/detector.schema.json": "077b9cccb0bd3d58ca53d61d59c609aa42709225d187e341412a857ab341462f",
+      "schemas/extensions/renderer.schema.json": "2ec52545c85bb5e36d0f4f67c155b0e1656468b62a1045d2eb268255202306f0",
+      "schemas/extensions/rule.schema.json": "dd957deaafd41699309cb073a4620e4e8e45d3ba15541adba0e693e6d85cdf76",
       "schemas/frontmatter/agent.schema.json": "0e63d7692efb29facccc69472fff48a25f44934618346bfc09738864c6917787",
       "schemas/frontmatter/base.schema.json": "e68fbb85d3e873c4897af776eaf873860bd6e86b5abc1799e801d35c4f7937cf",
       "schemas/frontmatter/command.schema.json": "7b8463ce9c83edd2e3073dd4cd1bbeec4b42e53b03b48bc9a59e540136c2de89",
@@ -209,7 +243,7 @@
       "schemas/summaries/hook.schema.json": "36f876f3b1a60d45be97a0848c79fd18744b434dfdcefc366f033b253d56268c",
       "schemas/summaries/note.schema.json": "ae510f3ee1b6092c1061625e425c9bb7de9c9caa3f3774770c148f658d505753",
       "schemas/summaries/skill.schema.json": "f01bab92c51d64ee23e61587e42cf0dc5b37a2f518f5b12b3d1d456390338aa8",
-      "versioning.md": "e35d4a492f4cba7ff7c9168802fe11a17daa92c60fc3333ed04e2dbb8b3b6795"
+      "versioning.md": "76a38d6b7e245a80274173a3cef791a04432e6ae3017ea3f66d7a37eb550fccf"
     }
   }
 }

package/package.json

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

package/schemas/extensions/action.schema.json

@@ -8,7 +8,7 @@
   ],
   "type": "object",
   "required": ["id", "kind", "version", "mode", "reportSchemaRef"],
-  "additionalProperties": false,
+  "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "action" },
     "mode": {
@@ -32,7 +32,7 @@
     "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,
+      "unevaluatedProperties": false,
       "properties": {
         "kind": {
           "type": "array",

package/schemas/extensions/adapter.schema.json

@@ -8,7 +8,7 @@
   ],
   "type": "object",
   "required": ["id", "kind", "version", "emits", "defaultRefreshAction"],
-  "additionalProperties": false,
+  "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "adapter" },
     "emits": {

package/schemas/extensions/audit.schema.json

@@ -8,7 +8,7 @@
   ],
   "type": "object",
   "required": ["id", "kind", "version", "composes", "reportSchemaRef"],
-  "additionalProperties": false,
+  "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "audit" },
     "composes": {
@@ -18,7 +18,7 @@
       "items": {
         "type": "object",
         "required": ["kind", "id"],
-        "additionalProperties": false,
+        "unevaluatedProperties": false,
         "properties": {
           "kind": { "type": "string", "enum": ["rule", "action"] },
           "id": { "type": "string" },
@@ -37,7 +37,7 @@
     "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,
+      "unevaluatedProperties": false,
       "properties": {
         "pass": { "type": "integer", "default": 0 },
         "fail": { "type": "integer", "default": 1 }

package/schemas/extensions/base.schema.json

@@ -2,10 +2,9 @@
   "$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.",
+  "description": "Base manifest shape common to every extension kind. Kind-specific schemas (`adapter`, `detector`, `rule`, `action`, `audit`, `renderer`) extend this via `allOf` and add a discriminant `kind` literal plus kind-specific fields. camelCase keys throughout. Closed-content enforcement (unknown keys = bug) lives on the kind schemas via `unevaluatedProperties: false`; those see base's evaluated keys through the `allOf` composition. Adding closure here too would force every kind schema to re-list every base key, which is the footgun the spec used to trip on before 2026-04-22.",
   "type": "object",
   "required": ["id", "kind", "version"],
-  "additionalProperties": false,
   "properties": {
     "id": {
       "type": "string",

package/schemas/extensions/detector.schema.json

@@ -8,7 +8,7 @@
   ],
   "type": "object",
   "required": ["id", "kind", "version", "emitsLinkKinds", "defaultConfidence"],
-  "additionalProperties": false,
+  "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "detector" },
     "emitsLinkKinds": {

package/schemas/extensions/renderer.schema.json

@@ -8,7 +8,7 @@
   ],
   "type": "object",
   "required": ["id", "kind", "version", "format"],
-  "additionalProperties": false,
+  "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "renderer" },
     "format": {

package/schemas/extensions/rule.schema.json

@@ -8,7 +8,7 @@
   ],
   "type": "object",
   "required": ["id", "kind", "version", "emitsRuleIds", "defaultSeverity"],
-  "additionalProperties": false,
+  "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "rule" },
     "emitsRuleIds": {

package/versioning.md

@@ -79,7 +79,7 @@ The first stable commitment is `spec-v1.0.0`. In the current reference roadmap,
 1. PR proposes a spec change. Include rationale and classification (patch/minor/major).
 2. If major, PR includes a migration note draft for `CHANGELOG.md`.
 3. If the change affects reference-impl behavior, a companion PR in `src/` lands the implementation behind the bumped `specCompat`.
-4. Merge order: spec change first, implementation second. An implementation MUST NOT ship a feature that is not yet in the spec (see `CLAUDE.md`: "Every feature: update spec/ first, then src/").
+4. Merge order: spec change first, implementation second. An implementation MUST NOT ship a feature that is not yet in the spec (see `AGENTS.md`: "Every feature: update spec/ first, then src/").
 5. Tag spec release (`spec-vX.Y.Z`) independent from any CLI tag.
 
 ## Canonical URLs