@skill-map/spec 0.16.0 → 0.18.0

package/schemas/frontmatter/base.schema.json

@@ -2,9 +2,9 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/frontmatter/base.schema.json",
   "title": "FrontmatterBase",
-  "description": "Base shape of the YAML frontmatter block on every node, across all kinds. Universal — common to every Provider's nodes regardless of platform. Per-kind schemas live in the Provider that emits the kind (declared via `provider.kinds[<kind>].schema`) and extend this base via `allOf` + `$ref` to its `$id`. camelCase keys throughout. `additionalProperties` is intentionally permissive; the deterministic `unknown-field` rule emits warnings for keys outside the catalog so that the JSON Schema remains shape-only and policy lives in rules.",
+  "description": "Truly universal frontmatter shape — `name` + `description` are the only fields every node, on every Provider, MUST carry. Per-vendor schemas (Anthropic Claude, Cursor, Obsidian, …) live in the Provider that emits the kind (declared via `provider.kinds[<kind>].schema`) and extend this base via `allOf` + `$ref` to its `$id`. `additionalProperties: true` is intentional: skill-map AGGREGATES vendor specs, it does not curate them. Vendor-specific fields (`tools`, `allowedTools`, `model`, `metadata`, etc.) flow through validation silently because the per-kind extension declares them. The future home for skill-map-only annotation fields (provenance, cross-vendor metadata) is a deferred decision — tracked separately, not in this schema.",
   "type": "object",
-  "required": ["name", "description", "metadata"],
+  "required": ["name", "description"],
   "additionalProperties": true,
   "properties": {
     "name": {
@@ -16,131 +16,6 @@
       "type": "string",
       "minLength": 1,
       "description": "One-to-three-sentence description. REQUIRED."
-    },
-    "type": {
-      "type": "string",
-      "description": "User-declared kind hint. Optional; the Provider may use it to tie-break classification. Free-form string so that new kinds introduced by Providers don't require a spec bump."
-    },
-    "author": {
-      "type": "string",
-      "description": "Primary author. Denormalized into `node.author` for query speed."
-    },
-    "authors": {
-      "type": "array",
-      "description": "Additional authors. MAY include the primary author; consumers dedupe on display.",
-      "items": { "type": "string" }
-    },
-    "license": {
-      "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.",
-      "required": ["version"],
-      "additionalProperties": true,
-      "properties": {
-        "github": { "type": "string", "description": "GitHub handle or profile URL." },
-        "homepage": { "type": "string", "format": "uri" },
-        "linkedin": { "type": "string" },
-        "twitter": { "type": "string" },
-
-        "version": {
-          "type": "string",
-          "description": "Semver of this node's content. REQUIRED. Denormalized into `node.version`."
-        },
-        "specCompat": {
-          "type": "string",
-          "description": "Semver range of spec versions this node targets."
-        },
-        "stability": {
-          "type": "string",
-          "enum": ["experimental", "stable", "deprecated"],
-          "description": "Maturity tag. Denormalized into `node.stability`."
-        },
-        "supersedes": {
-          "type": "array",
-          "description": "`node.path` values this node replaces. Feeds the `supersedes` link kind.",
-          "items": { "type": "string" }
-        },
-        "supersededBy": {
-          "type": "string",
-          "description": "`node.path` that replaces this one. Inverse of `supersedes`."
-        },
-
-        "source": {
-          "type": "string",
-          "format": "uri",
-          "description": "Canonical origin URL (e.g. GitHub blob). Consumed by enrichment plugins for hash verification."
-        },
-        "sourceVersion": {
-          "type": "string",
-          "description": "Tag, SHA, or branch at the source. Branches are resolved dynamically by enrichment."
-        },
-
-        "tags": {
-          "type": "array",
-          "items": { "type": "string" }
-        },
-        "category": { "type": "string" },
-        "keywords": {
-          "type": "array",
-          "items": { "type": "string" }
-        },
-
-        "created": { "$ref": "#/$defs/IsoDate", "description": "ISO 8601 date (`YYYY-MM-DD`) or date-time." },
-        "updated": { "$ref": "#/$defs/IsoDate", "description": "ISO 8601 date (`YYYY-MM-DD`) or date-time." },
-        "released": { "$ref": "#/$defs/IsoDate", "description": "ISO 8601 date (`YYYY-MM-DD`) or date-time." },
-
-        "requires": {
-          "type": "array",
-          "description": "`node.path` or plugin id values this node depends on.",
-          "items": { "type": "string" }
-        },
-        "conflictsWith": {
-          "type": "array",
-          "description": "Nodes or plugin ids that MUST NOT be co-enabled with this one.",
-          "items": { "type": "string" }
-        },
-        "provides": {
-          "type": "array",
-          "description": "Capability tokens this node advertises (free-form strings).",
-          "items": { "type": "string" }
-        },
-        "related": {
-          "type": "array",
-          "description": "`node.path` values for see-also navigation. No strict semantics.",
-          "items": { "type": "string" }
-        },
-
-        "icon": { "type": "string", "description": "Free-form icon hint (emoji, lucide name, URL)." },
-        "color": { "type": "string", "description": "CSS color or predefined palette token." },
-        "priority": { "type": "integer", "description": "Higher = surface earlier in UI listings." },
-        "hidden": { "type": "boolean", "description": "UI hint: hide from default lists." },
-
-        "docsUrl": { "type": "string", "format": "uri" },
-        "readme": { "type": "string", "description": "Relative or absolute path to an extended README for this node." },
-        "examplesUrl": { "type": "string", "format": "uri" }
-      }
-    }
-  },
-  "$defs": {
-    "IsoDate": {
-      "type": "string",
-      "anyOf": [
-        { "format": "date" },
-        { "format": "date-time" }
-      ]
     }
   }
 }

package/schemas/node.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/node.schema.json",
   "title": "Node",
-  "description": "A single markdown file in the graph. Identified by its relative path from the scope root. The `kind` is whatever the classifying Provider declares — open by design; the **built-in Claude Provider** emits `skill` / `agent` / `command` / `hook` / `note` today, but external Providers (Cursor, Obsidian, …) MAY emit their own.",
+  "description": "A single markdown file in the graph. Identified by its relative path from the scope root. The `kind` is whatever the classifying Provider declares — open by design; the **built-in Claude Provider** emits `skill` / `agent` / `command` / `markdown` today, but external Providers (Cursor, Obsidian, …) MAY emit their own. Format-named kinds (`markdown`, future `toml`, future `json`) are reserved for the generic fallback only — when a file matches a specific role (agent / command / skill) that classification prevails over format naming.",
   "type": "object",
   "required": ["path", "kind", "provider", "bodyHash", "frontmatterHash", "bytes", "linksOutCount", "linksInCount", "externalRefsCount"],
   "additionalProperties": false,
@@ -14,7 +14,7 @@
     "kind": {
       "type": "string",
       "minLength": 1,
-      "description": "Category assigned by the Provider. Open-by-design — any non-empty string an enabled Provider declares is valid (built-in Claude Provider catalog: `skill` / `agent` / `command` / `hook` / `note`; external Providers MAY declare their own). Per-kind frontmatter schemas live with the Provider that emits the kind. Stability: stable."
+      "description": "Category assigned by the Provider. Open-by-design — any non-empty string an enabled Provider declares is valid (built-in Claude Provider catalog: `skill` / `agent` / `command` / `markdown`; external Providers MAY declare their own). Per-kind frontmatter schemas live with the Provider that emits the kind. Stability: stable."
     },
     "provider": {
       "type": "string",
@@ -34,12 +34,9 @@
       "description": "Denormalized from `metadata.stability` for fast queries."
     },
     "version": {
-      "type": ["string", "null"],
-      "description": "Denormalized from `metadata.version` for fast queries. Must be a valid semver if present."
-    },
-    "author": {
-      "type": ["string", "null"],
-      "description": "Denormalized from `metadata.author` for fast queries."
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "Monotonic version counter denormalised from sidecar `annotations.version` (Step 9.6.2). Pre-9.6.2 this field was a semver string sourced from `frontmatter.metadata.version`; the new shape is a single integer monotonic counter, orthogonal to `stability`. Major bumps mean `create a new node, supersede the old one`, not increment. See Decision #125 and `annotations.schema.json#/properties/version`."
     },
     "frontmatter": {
       "type": "object",
@@ -78,6 +75,14 @@
       "type": "integer",
       "minimum": 0,
       "description": "http/https URLs in the body after normalization and exact-match dedup."
+    },
+    "sidecar": {
+      "$ref": "#/$defs/sidecarOverlay",
+      "description": "Step 9.6.2 — co-located `.sm` sidecar overlay. Carries presence flag, drift status (null when no sidecar), and the parsed `annotations:` block (null when absent or empty). The kernel re-derives `status` on every scan from the live hashes; clients should treat it as authoritative for the snapshot but never persist it across scans."
+    },
+    "isFavorite": {
+      "type": "boolean",
+      "description": "Per-node favorite flag set by the local user from the UI. Sourced from `state_node_favorites` (zone `state_`, persistent across scans). Decorated by the BFF on every `/api/nodes` response via in-memory Set lookup against the favorites table — no SQL JOIN against `scan_nodes`. Absent on emissions that don't carry per-user state (e.g. `sm export --json`); consumers that don't recognise the field MUST ignore it."
     }
   },
   "$defs": {
@@ -90,6 +95,32 @@
         "body": { "type": "integer", "minimum": 0 },
         "total": { "type": "integer", "minimum": 0 }
       }
+    },
+    "sidecarOverlay": {
+      "type": "object",
+      "required": ["present"],
+      "additionalProperties": false,
+      "properties": {
+        "present": {
+          "type": "boolean",
+          "description": "True when a `<basename>.sm` file accompanies the node on disk; false otherwise."
+        },
+        "status": {
+          "type": ["string", "null"],
+          "enum": ["fresh", "stale-body", "stale-frontmatter", "stale-both", null],
+          "description": "Drift status. NULL when no sidecar is present, or when the sidecar exists but failed to parse / validate (the row still records `present: true` so clients can distinguish absent from broken)."
+        },
+        "annotations": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "Parsed `annotations:` block from the sidecar. NULL when no sidecar is present, when the block is absent / empty, or when the sidecar failed to parse / validate."
+        },
+        "root": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "Parsed YAML root of the matching `.sm` sidecar. Mirrors the shape of `sidecar.schema.json` (top-level reserved blocks `for` / `annotations` / `settings` / `audit` plus opt-in `<plugin-id>:` namespaces). Surfaced for the UI inspector's audit panel, plugin-contributions panel, and debug panel; NULL when the sidecar is absent or failed to parse. Note the duplication with `annotations` at this overlay level — existing consumers read from `annotations`, new consumers read structured sub-fields off `root` (`root.for.*`, `root.audit.*`, etc.). The duplication is intentional and documented; do NOT remove the top-level `annotations` field."
+        }
+      }
     }
   }
 }

package/schemas/report-base-deterministic.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/report-base-deterministic.schema.json",
+  "title": "ReportBaseDeterministic",
+  "description": "Universal base for deterministic Action reports. Every deterministic Action's report MUST extend this base via `allOf` + `$ref`. Symmetric with `report-base.schema.json` (the probabilistic / LLM base, which carries `confidence` + `safety`); deterministic vs probabilistic is the orthogonal axis declared by the Action manifest's `mode` field. Fields: `ok` (boolean — did the Action complete its logical work?), plus action-specific keys via `additionalProperties: true`. Action-specific shapes (e.g. bump's `version` / `noop` / `reason`) ride on the open extension.",
+  "type": "object",
+  "required": ["ok"],
+  "additionalProperties": true,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "description": "True when the Action completed its logical work; false when it refused / errored. Silent no-ops (e.g. `force: true` against an already-fresh node) still report `ok: true` with an action-specific marker (e.g. bump's `noop: true`)."
+    }
+  }
+}

package/schemas/sidecar.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/sidecar.schema.json",
+  "title": "Sidecar",
+  "description": "Root shape of a co-located YAML sidecar (`<basename>.sm` next to `<basename>.md`). Carries skill-map's annotations, settings, audit, and plugin contributions about the markdown node it accompanies. Vendor file (`<basename>.md`) stays untouched. Top-level reserved blocks are `for`, `annotations`, `settings`, `audit`; everything else is treated as a plugin namespace (`<plugin-id>:`). Schema is `additionalProperties: true` so plugins can add namespaces without coordination; the built-in `unknown-field` rule warns on truly unrecognized root keys (typo guard). Format is YAML — comments via `#`, multiline strings via `|` / `>`, permissive types per the YAML 1.2 spec. See `architecture.md` §Annotation system and ROADMAP §Step 9.6 for the design rationale.",
+  "type": "object",
+  "required": ["for"],
+  "additionalProperties": true,
+  "properties": {
+    "for": {
+      "$ref": "#/$defs/identity",
+      "description": "Identity link to the markdown node this sidecar annotates. Drift detection compares stored hashes against the current file at scan time; mismatch emits the built-in `annotation-stale` warning (soft mode, never blocking)."
+    },
+    "annotations": {
+      "$ref": "annotations.schema.json",
+      "description": "Skill-map annotation catalog. See `annotations.schema.json` for the curated 15-field surface; users / plugins MAY add custom keys (rides on `additionalProperties: true`)."
+    },
+    "settings": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Reserved for skill-map's per-node settings. v0.18.0 ships the block empty; consumers ride on `additionalProperties: true`. Concrete fields land in later sub-steps as the runtime grows."
+    },
+    "audit": {
+      "$ref": "#/$defs/audit",
+      "description": "Skill-map's audit trail. Populated by the built-in `bump` Action starting in Step 9.6.3 (Decision #125). All fields are optional at the property level — the Action atomically fills `lastBumpedAt` + `lastBumpedBy` on every bump and `createdAt` + `createdBy` on first creation. `additionalProperties: true` so future fields land additively."
+    }
+  },
+  "$defs": {
+    "audit": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "lastBumpedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 datetime of the last `bump` Action invocation that materialised a write to this sidecar. Atomically set together with `lastBumpedBy` on every bump."
+        },
+        "lastBumpedBy": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identity of the bump invoker. Literal `'cli'` for `sm bump` (we are not threading user identity yet); `'plugin:<plugin-id>'` when a plugin's deterministic Action triggered the bump. Tests / future invokers MAY pass any non-empty string."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 datetime of the first `bump` invocation that ever wrote this sidecar. Set exactly once (when the `.sm` file did not previously exist on disk); stable across subsequent bumps."
+        },
+        "createdBy": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identity of the invoker that created the sidecar (same value form as `lastBumpedBy`). Set exactly once at creation time and stable thereafter."
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "required": ["path", "bodyHash", "frontmatterHash"],
+      "additionalProperties": true,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path from the scope root to the `.md` file this sidecar annotates. Matches the canonical Node identifier (see `node.schema.json` #/properties/path). Survives content edits; breaks on file moves — `sm refresh` re-points the sidecar after a move."
+        },
+        "bodyHash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "sha256 of the body content (post-frontmatter), hex-encoded lowercase, captured at the moment this sidecar was last bumped. Compared against the current body hash to detect drift."
+        },
+        "frontmatterHash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "sha256 of the canonical frontmatter (per the kernel's `canonicalFrontmatter` rule), hex-encoded lowercase, captured at the moment this sidecar was last bumped. Compared against the current frontmatter hash to detect drift."
+        },
+        "resolvedAs": {
+          "type": "object",
+          "required": ["provider", "kind"],
+          "additionalProperties": false,
+          "properties": {
+            "provider": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Provider id that classifies this node (e.g. `claude`)."
+            },
+            "kind": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Kind within the Provider (e.g. `agent`, `skill`)."
+            }
+          },
+          "description": "Optional override of the Provider/kind classification. Set when path-based + content-based matching are ambiguous (a single `.md` matched by multiple Providers). When present, locks the classification to (`provider`, `kind`); when absent, the kernel uses its normal classification pipeline."
+        }
+      }
+    }
+  }
+}

package/schemas/summaries/{note.schema.json → markdown.schema.json}

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/summaries/note.schema.json",
-  "title": "SummaryNote",
-  "description": "Report produced by `note-summarizer` for a single `note` node. Extends `report-base.schema.json`. Stability: experimental.",
+  "$id": "https://skill-map.dev/spec/v0/summaries/markdown.schema.json",
+  "title": "SummaryMarkdown",
+  "description": "Report produced by `markdown-summarizer` for a single `markdown` node (the format-named generic fallback in the Claude Provider catalog). Extends `report-base.schema.json`. Stability: experimental.",
   "allOf": [
     { "$ref": "../report-base.schema.json" }
   ],
@@ -14,7 +14,7 @@
     "safety": true,
     "whatItCovers": {
       "type": "string",
-      "description": "One-sentence summary of the note's subject matter. REQUIRED. Named distinctly from `whatItDoes` since notes describe, not act."
+      "description": "One-sentence summary of the file's subject matter. REQUIRED. Named distinctly from `whatItDoes` since markdown notes describe, not act."
     },
     "topics": {
       "type": "array",
@@ -23,7 +23,7 @@
     },
     "keyFacts": {
       "type": "array",
-      "description": "Discrete claims or data points the note asserts. Useful for search and diffing over time.",
+      "description": "Discrete claims or data points the file asserts. Useful for search and diffing over time.",
       "items": { "type": "string" }
     },
     "relatedNodes": {