@skill-map/spec 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Spec changelog
 
+## 0.17.0
+
+### Minor Changes
+
+- 77579b3: Add a `sm db browser` sub-command that opens the project's SQLite DB in DB Browser for SQLite (sqlitebrowser GUI). Read-only by default; pass `--rw` to enable writes. Replaces the previous `scripts/open-sqlite-browser.js` standalone script.
+
+  The root `npm run sqlite` shortcut now invokes the project-built CLI binary (`node src/bin/sm.js db browser`) instead of the standalone script. This guarantees the locally compiled CLI is used, not whichever `sm` resolves on PATH (a globally installed `@skill-map/cli` would otherwise shadow the in-development version).
+
+  Spec: `cli-contract.md` documents the new sub-command in the verb table and the §Database section.
+
+- 696008a: Add a `--no-ui` flag to `sm serve`. With it, the BFF stops serving the Angular bundle (stale or otherwise) and the root `/` renders an inline dev-mode placeholder pointing the user at `npm run ui:dev` + `http://localhost:4200/`. Used by the root `bff:dev` shortcut so iterating on the BFF alongside the Angular dev server doesn't surface a stale UI by accident.
+
+  Mutually exclusive with `--ui-dist <path>` (rejected with exit 2). Combining `--no-ui` with the default `--open` emits a non-fatal stderr warning suggesting `--no-open` (the auto-opened tab would land on the placeholder rather than the live UI). `/api/*` and `/ws` remain fully functional; only the static SPA is suppressed.
+
+  Spec impact: `spec/cli-contract.md` documents the new flag in the `sm serve` signature and the §Server flags table, including the mutual-exclusion + warning rules.
+
+- bd5e360: Trim `frontmatter/base.schema.json` to the truly universal contract: `name` + `description` are the only required fields, every node on every Provider, and `additionalProperties: true` lets vendor-specific keys flow through silently.
+
+  The previous base inadvertently curated a Claude-flavored shape (`tools`, `allowedTools`, full `metadata` block with `version` required, etc.). skill-map AGGREGATES vendor specs, it does not curate them — so per-vendor frontmatter shapes belong in the Provider that emits the kind. The Anthropic-specific catalog now lives entirely under `src/built-in-plugins/providers/claude/schemas/` and absorbs Anthropic's documented frontmatter verbatim (see the matching `@skill-map/cli` changeset).
+
+  The future home for skill-map-only annotation fields (provenance, cross-vendor metadata, source URL, supersedes/supersededBy) is a deferred decision — sidecar file vs in-frontmatter block — tracked separately. Existing files that carry `metadata: { version, ... }` continue to validate without any change because of `additionalProperties: true`; nothing breaks at the consumer edge.
+
+  Decision #55 (full metadata block in the universal base) is superseded by this change.
+
+  Breaking but greenfield-permitted per `versioning.md` § Pre-1.0: ships as a minor bump because `@skill-map/spec` is still 0.x and Decision #55 had not reached any released consumer that mandates the prior shape. Stays minor; the first 1.0.0 is a deliberate stabilization moment, not a side-effect of this PR.
+
 ## 0.16.0
 
 ### Minor Changes

package/cli-contract.md

@@ -319,6 +319,7 @@ See `db-schema.md` for the table catalog.
 | `sm db backup [--out <path>]` | WAL checkpoint + file copy. |
 | `sm db restore <path> [-n / --dry-run]` | Swap the DB. Destructive. `--dry-run` validates the source file (existence, header, schema version) and reports what would be overwritten without touching the live DB. |
 | `sm db shell` | Interactive SQL shell (implementations backed by SQLite use `sqlite3`; others use equivalent). |
+| `sm db browser [<path>] [--rw]` | Open the DB in DB Browser for SQLite (`sqlitebrowser` GUI). Read-only by default (`-R`) so a concurrent `sm scan` writer is safe; pass `--rw` to enable writes. The `sqlitebrowser` binary MUST be on `PATH`. Non-destructive — no confirmation prompt. Detaches from the terminal so the shell stays usable. |
 | `sm db dump [--tables ...]` | SQL dump. |
 | `sm db migrate [--dry-run \| --status \| --to <n> \| --kernel-only \| --plugin <id> \| --no-backup]` | Migration controls. |
 
@@ -330,7 +331,7 @@ Destructive verbs (`reset --state`, `reset --hard`, `restore`) require interacti
 
 | Command | Purpose |
 |---|---|
-| `sm serve [--port N] [--host ...] [--scope project\|global] [--db <path>] [--no-built-ins] [--no-plugins] [--open\|--no-open] [--dev-cors] [--ui-dist <path>] [--no-watcher]` | Start Hono + WebSocket for the Web UI. Single-port mandate: SPA + REST + WS under one listener. Default port 4242, default host 127.0.0.1 (loopback-only through v0.6.0; multi-host deferred — see §Server). The watcher is on by default (Decision #121: a server with stale DB is a footgun); pass `--no-watcher` for CI / read-only deployments. |
+| `sm serve [--port N] [--host ...] [--scope project\|global] [--db <path>] [--no-built-ins] [--no-plugins] [--open\|--no-open] [--dev-cors] [--ui-dist <path>] [--no-ui] [--no-watcher]` | Start Hono + WebSocket for the Web UI. Single-port mandate: SPA + REST + WS under one listener. Default port 4242, default host 127.0.0.1 (loopback-only through v0.6.0; multi-host deferred — see §Server). The watcher is on by default (Decision #121: a server with stale DB is a footgun); pass `--no-watcher` for CI / read-only deployments. `--no-ui` skips the SPA bundle (dev workflow alongside the Angular dev server); see §Server flags. |
 
 #### Server
 
@@ -402,7 +403,8 @@ Error code sources at v14.2:
 | `--no-plugins` | off | Skip drop-in plugin discovery. |
 | `--open` / `--no-open` | `--open` | Auto-open the SPA in the user's default browser after listen. |
 | `--dev-cors` | off | Enable permissive CORS for the Angular dev-server proxy workflow. Loopback-only when set. |
-| `--ui-dist <path>` | auto | Override the UI bundle directory. Hidden flag — used by the demo build pipeline + tests; everyday users never need it. |
+| `--ui-dist <path>` | auto | Override the UI bundle directory. Hidden flag — used by the demo build pipeline + tests; everyday users never need it. Mutually exclusive with `--no-ui` (rejected with exit 2). |
+| `--no-ui` | off | Skip serving the Angular SPA bundle. The root `/` (and any SPA fallback) responds with an inline dev-mode placeholder pointing the user at `npm run ui:dev` + `http://localhost:4200/`. Intended for local development alongside the Angular dev server with HMR; pairs with `--no-open` (default `--open` plus `--no-ui` would auto-open the placeholder, so a non-fatal stderr warning is emitted in that combination). Mutually exclusive with `--ui-dist <path>` (rejected with exit 2). The server keeps `/api/*` and `/ws` fully functional; only the static SPA is suppressed. |
 | `--no-watcher` | off | Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments — without the watcher, `/ws` stays open but no `scan.*` events ever fire. Combining with `--no-built-ins` is rejected (the watcher cannot run with an empty pipeline; would persist empty scans on every batch). |
 
 **WebSocket protocol** *(Stability: experimental — locks at v0.6.0)*:

package/conformance/coverage.md

@@ -18,7 +18,7 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 8 | `job.schema.json` | — | 🔴 missing | Blocked by Step 10 (job system). Needs a case that submits a local action (no LLM), inspects `sm job show --json`. |
 | 9 | `report-base.schema.json` | — | 🔴 missing | Indirect coverage once any summarizer case lands. Direct contract case: validate a handcrafted minimal report ({confidence, safety}) against the base schema. |
 | 10 | `conformance-case.schema.json` | — | 🔴 missing | Self-referential: every `*.json` under `cases/` MUST validate against this schema. Add a meta-case that enumerates + validates all cases. |
-| 11 | `frontmatter/base.schema.json` | — | 🔴 missing | Universal frontmatter shape. Per-kind schemas (`skill` / `agent` / `command` / `hook` / `note`) live with the Provider that emits them (the Claude Provider ships them under `src/extensions/providers/claude/schemas/`) and extend this base via `$ref`-by-`$id`. Direct spec-level case still pending: fixture with min-required frontmatter only, no Provider needed (Provider-disabled mode + a single `notes/<file>.md` with `name: ...` + `description: ...`). |
+| 11 | `frontmatter/base.schema.json` | — | 🔴 missing | Universal frontmatter shape — `name` + `description` only, `additionalProperties: true`. Per-kind schemas (`skill` / `agent` / `command` / `note`) live with the Provider that emits them (the Claude Provider ships them under `src/extensions/providers/claude/schemas/`) and extend this base via `$ref`-by-`$id`. Direct spec-level case still pending: fixture with min-required frontmatter only, no Provider needed (Provider-disabled mode + a single `notes/<file>.md` with `name: ...` + `description: ...`). |
 | 12 | `summaries/skill.schema.json` | — | 🔴 missing | Blocked by Step 10 (`skill-summarizer`). Case: submit summarizer, validate report. |
 | 13 | `summaries/agent.schema.json` | — | 🔴 missing | Blocked by Step 11. |
 | 14 | `summaries/command.schema.json` | — | 🔴 missing | Blocked by Step 11. |
@@ -34,7 +34,7 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 24 | `extensions/hook.schema.json` | — | 🔴 missing | Case: a `deterministic` hook manifest with `triggers: ['scan.completed']` validates; a hook declaring an unknown trigger (e.g. `scan.progress`) fails with `invalid-manifest` at load time. |
 | 25 | `api/rest-envelope.schema.json` | — | 🔴 missing | Step 14.2 BFF list-envelope shape (`{ schemaVersion, kind, items \| item \| value, filters, counts }`). Case: hit `GET /api/nodes` against a primed scope, validate the response against the schema; assert the `oneOf` rejects an envelope that carries both `items` and `item`. Implementation-side coverage exists today (`src/test/server-endpoints.test.ts`) but a kernel-agnostic conformance case is required before v1.0.0 ships. |
 
-> **Note on Provider-owned schemas.** Per-kind frontmatter schemas (`skill`, `agent`, `command`, `hook`, `note`) live with the Provider that emits them — for the built-in Claude Provider, under `src/extensions/providers/claude/schemas/`. Those schemas are NOT counted in the spec's coverage matrix above; they belong to the Provider's own conformance suite at `src/extensions/providers/claude/conformance/coverage.md`. The same split applies to the cases that exercise Provider-specific kinds (`basic-scan`, `rename-high`, `orphan-detection`) — they live in the Provider's `cases/` directory.
+> **Note on Provider-owned schemas.** Per-kind frontmatter schemas (`skill`, `agent`, `command`, `note` for the built-in Claude Provider; other Providers MAY declare different kinds) live with the Provider that emits them — for the built-in Claude Provider, under `src/extensions/providers/claude/schemas/`. Those schemas are NOT counted in the spec's coverage matrix above; they belong to the Provider's own conformance suite at `src/extensions/providers/claude/conformance/coverage.md`. The same split applies to the cases that exercise Provider-specific kinds (`basic-scan`, `rename-high`, `orphan-detection`) — they live in the Provider's `cases/` directory.
 
 Status legend: 🟢 covered (at least one case asserts the schema end-to-end) · 🟡 partial (covered only indirectly or via a sub-shape) · 🔴 missing.
 
@@ -61,7 +61,7 @@ These have their own conformance cases even though they are not JSON Schemas.
 
 - **spec v0.x**: partial coverage acceptable. Every case added as the reference impl lands the verb that makes it runnable.
 - **spec v1.0.0 release**: all rows above MUST be 🟢 covered or explicitly 🟠 deferred to v1.1 with a linked issue.
-- **CI check**: [`scripts/check-coverage.js`](../../scripts/check-coverage.js) compares `spec/schemas/**/*.schema.json` against the matrix above on every PR. A schema without a row here, or a row pointing at a missing schema, fails CI (exit 1 with a `::error::` annotation). Wired into `ci.yml` §validate and into `npm run spec:check`.
+- **CI check**: [`spec/scripts/check-coverage.js`](../scripts/check-coverage.js) compares `spec/schemas/**/*.schema.json` against the matrix above on every PR. A schema without a row here, or a row pointing at a missing schema, fails CI (exit 1 with a `::error::` annotation). Wired into the spec workspace's `spec:check` script (which is invoked by `npm run validate` from the repo root, picked up by CI).
 
 ## Stability
 

package/index.json

@@ -166,18 +166,18 @@
       }
     ]
   },
-  "specPackageVersion": "0.16.0",
+  "specPackageVersion": "0.17.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "f2dce379783e8e786304c559f0b109226e587543c31cfb25df4ca63e65e2860f",
+      "CHANGELOG.md": "42e2764e2d41a660f0edcf5e421527de63821ff14d121170afdced78ef1dd219",
       "README.md": "97fd3079092182c677669c25f44e08b0f6579faaa3406d8cb5a884e37e9eef97",
       "architecture.md": "c14e69faa7ce7f657d6a2790762daaea8a5ff350375de8c254cd870b5494b896",
-      "cli-contract.md": "e94340f25e781a1131d0902cf368a3675795bf71ffb419e1af789ff8992897aa",
+      "cli-contract.md": "6e41881be39618f74166288508a6b28b431529cc13d18b20d5e367dea23ae0c3",
       "conformance/README.md": "5f94a6ac637b7c992fcd7e53d32eed1b8887eeef05eb6ca3b5ec8a0b5045cd21",
       "conformance/cases/kernel-empty-boot.json": "ad4bbe9d637537625025c8bdb61285b1433568a2544b1ce0248f304ccff8c350",
       "conformance/cases/plugin-missing-ui-rejected.json": "c6ce8f62a430d662aea33dec8ebf6493be6455037be3114e0d93d0eb57777287",
-      "conformance/coverage.md": "35bac01af3a922ce580deb1f83fc890c668d3d3cf93747f5097340a09303eb43",
+      "conformance/coverage.md": "f3e2d8ce53f78487ba197be7a0727bf4d99ca9ca7419a65887e130a5debce738",
       "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json": "4d78af6f12faa9d131e2a19f1dbb8f250baacc525978f3a8c858932b95da4ff6",
       "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/provider.js": "da40b134d70f8bc8175cfa9c380ecb55d26b2240c8b467f22f3fcfab750c8747",
       "conformance/fixtures/plugin-missing-ui/notes/example.md": "55767f0aa1b6774546a99f28c58e7b732aa9cfa5dfce8d0326470f7f622f577e",
@@ -199,7 +199,7 @@
       "schemas/extensions/hook.schema.json": "7465c38e0765edf23e49d4f96c539d04323f1cf564af1c60ee637c79a6d39239",
       "schemas/extensions/provider.schema.json": "518d7666841cfef8eb28aab788a6e6dfabf9e12f3f06de1c81be915cbe6c1088",
       "schemas/extensions/rule.schema.json": "8ff420bde498f50db114c352305d487c71aef2dd746fd0c24976ff6a09865c22",
-      "schemas/frontmatter/base.schema.json": "dfee192458765b8cb872ef9e7145ec31b9e07ceb19ee44be48af2172329e7a38",
+      "schemas/frontmatter/base.schema.json": "88d906ec15e94543b919dd22b4ea4053e40024dc14068e6c7df09662db2f3350",
       "schemas/history-stats.schema.json": "23f472d1de06d23fc775aabba821f8375f347af4dc8d89ba567980d61a11f9de",
       "schemas/issue.schema.json": "40f6f8abadcce0fd8eac9df27ffcc20b2fc9fda6970142ddb8e7e56b1760b9b1",
       "schemas/job.schema.json": "ffbdd51c54b487c44eb57fabd07f624ac1030c14ef69b46933c154092853a84c",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",
@@ -44,6 +44,13 @@
     "conformance/",
     "index.json"
   ],
+  "scripts": {
+    "spec": "node scripts/build-index.js",
+    "spec:check": "node scripts/build-index.js --check && node scripts/check-coverage.js",
+    "pin": "node scripts/sync-pin.js",
+    "pin:check": "node scripts/sync-pin.js --check",
+    "validate": "npm run spec:check && npm run pin:check"
+  },
   "publishConfig": {
     "access": "public"
   }

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" }
-      ]
     }
   }
 }