@skill-map/spec 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # Spec changelog
 
+## 0.6.1
+
+### Patch Changes
+
+- f41dbad: Step 6.1 — Spec migration: rename the canonical config file from
+  `.skill-map.json` (single project-root file) to `.skill-map/settings.json`
+  inside the `.skill-map/` scope folder, with a sibling `.skill-map/settings.local.json`
+  partner for machine-specific overrides. Aligns the spec with the layered
+  config hierarchy described in the roadmap (library defaults → user → user-local
+  → project → project-local → env / flags).
+
+  **Spec change (breaking, minor under pre-1.0 versioning policy)**:
+
+  - `spec/schemas/project-config.schema.json` description updated to point at
+    `.skill-map/settings.json` and explicitly mention the `.local.json` partner
+    and the layered-merge contract. The schema _shape_ (keys, types, validation
+    rules) is unchanged — only the on-disk filename moves. Consumers that read
+    values without caring about the source path are unaffected; consumers that
+    hard-code the filename must update.
+  - `spec/db-schema.md` §Scopes: `history.share: true` reference updated to
+    `.skill-map/settings.json`.
+  - `spec/conformance/coverage.md` row #6 description updated to reference the
+    new path and the optional `settings.local.json` overlay.
+
+  **Why minor (not major) at pre-1.0**: per `spec/versioning.md` §Pre-1.0,
+  breaking changes ARE allowed in minor bumps while the spec is `0.y.z`. The
+  shape of the data is unchanged; only the file name on disk moves.
+
+  **No backward-compat shim**: there is no real implementation of the loader
+  yet (lands in 6.2), so no live consumer reads `.skill-map.json` today. The
+  only known prior reference is the demo `mock-collection/.claude/commands/init*.md`
+  fixture, which is updated together with `sm init` in 6.5.
+
+  **Runtime change**: none in 6.1 — pure spec edit. The matching loader,
+  `sm init`, and `sm config` verbs land in subsequent sub-steps.
+
+  **Roadmap update**: `ROADMAP.md` §Configuration "Spec migration" call-out
+  flipped from "pending" to "landed Step 6.1, 2026-04-27".
+
+  Test count: unchanged (213 → 213 — spec-only edit).
+
+- 8a4667f: Step 6.6 — `sm plugins enable / disable` + the `config_plugins`
+  override layer they read from. The two stub verbs become real, and
+  the `PluginLoader` finally honours user intent: a disabled plugin
+  surfaces in `sm plugins list` with status `disabled`, but its
+  extensions are NOT imported and the kernel will not run them.
+
+  **Decision (recorded in spec)**: enable/disable resolution favours the
+  DB row over `settings.json` over the installed default. The DB
+  override is local-machine; `settings.json` is the team-shared baseline.
+  A developer can locally disable a misbehaving plugin without
+  committing the toggle to the team's config; conversely, a baseline
+  that explicitly enables a plugin is overridable per-machine. The rule
+  is documented in `spec/db-schema.md` §`config_plugins`.
+
+  **Spec change (additive, patch)**:
+
+  - `spec/db-schema.md` — appended an "Effective enable/disable
+    resolution" subsection under `config_plugins` documenting the
+    three-layer precedence (DB > `settings.json` > installed default).
+    No schema changes; the `config_plugins` table itself was already
+    defined in the initial migration.
+
+  **Runtime change**:
+
+  - `src/kernel/types/plugin.ts` — `TPluginLoadStatus` gains a `disabled`
+    variant. JSDoc explains all five states.
+  - `src/kernel/adapters/sqlite/plugins.ts` — new file. Storage helpers
+    over the `config_plugins` table: `setPluginEnabled` (upsert),
+    `getPluginEnabled` (single read), `loadPluginOverrideMap` (bulk
+    read for one round-trip per process), `deletePluginOverride`
+    (idempotent drop, used by future `sm config reset plugins.<id>`).
+  - `src/kernel/config/plugin-resolver.ts` — new file.
+    `resolvePluginEnabled` implements the precedence above;
+    `makeEnabledResolver` curries the layered config and DB map into
+    the `(id) => boolean` shape `IPluginLoaderOptions.resolveEnabled`
+    expects.
+  - `src/kernel/adapters/plugin-loader.ts` — new optional
+    `resolveEnabled` callback in `IPluginLoaderOptions`. When supplied,
+    the loader checks AFTER manifest + specCompat validation and
+    short-circuits with `status: 'disabled'` (manifest preserved,
+    extensions array omitted, reason `"disabled by config_plugins or
+settings.json"`). Omitting the callback keeps the legacy "always
+    load" behaviour for tests / kernel-empty-boot.
+  - `src/cli/commands/plugins.ts` — wires the loader to the resolver:
+    every read (`list / show / doctor`) loads `config_plugins` once and
+    feeds the resolver. Two new commands `PluginsEnableCommand` and
+    `PluginsDisableCommand` write to the DB. `--all` toggles every
+    discovered plugin; `<id>` and `--all` are mutually exclusive.
+    `sm plugins doctor` now treats `disabled` as intentional (does not
+    contribute to the issue list, does not flip exit code).
+  - `src/cli/commands/plugins.ts` — adds `off` to the status icon legend
+    in human output (`off  mock-a@0.1.0 · disabled by config_plugins or
+settings.json`).
+  - `src/cli/commands/stubs.ts` — `PluginsEnableCommand` and
+    `PluginsDisableCommand` removed; replaced-at-step comment kept.
+  - `context/cli-reference.md` — regenerated; the two new verbs appear
+    with their flag tables.
+
+  **Tests**:
+
+  - `src/test/plugin-overrides.test.ts` — 8 unit tests covering storage
+    round-trip (upsert + read), `loadPluginOverrideMap` bulk read,
+    `deletePluginOverride` idempotency, resolver precedence (default ⇒
+    true, `settings.json` overrides default, DB overrides
+    `settings.json`), `makeEnabledResolver` currying, and PluginLoader
+    surfacing `disabled` status with manifest preserved + no extensions
+    - omitting the resolver still loads.
+  - `src/test/plugins-cli.test.ts` — 9 end-to-end tests via the binary:
+    `disable <id>` writes a DB row + `sm plugins list` reflects `off`,
+    `enable <id>` flips back, `--all` covers every discovered plugin,
+    unknown id → exit 5, no-arg → exit 2, both `<id>` and `--all` →
+    exit 2, `settings.json` baseline overridden by DB `enable`,
+    `settings.json` baseline applies when DB has no row, and
+    `sm plugins doctor` exits 0 when the only non-loaded plugin is
+    intentionally disabled.
+
+  Test count: 273 → 291 (+18).
+
 ## 0.6.0
 
 ### Minor Changes

package/conformance/coverage.md

@@ -13,7 +13,7 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 3 | `issue.schema.json` | — | 🔴 missing | Needs fixture triggering `trigger-collision` + `broken-ref` + `superseded`. |
 | 4 | `scan-result.schema.json` | `basic-scan`, `kernel-empty-boot` | 🟢 covered | Zero-filled (empty-boot) + populated (minimal-claude) both asserted. |
 | 5 | `execution-record.schema.json` | — | 🔴 missing | Blocked by Step 5 (history). Needs a case that runs a `local` action and inspects `state_executions` via `sm history --json`. |
-| 6 | `project-config.schema.json` | — | 🔴 missing | Case: init a scope, write a partial `.skill-map.json`, assert effective config after merge. |
+| 6 | `project-config.schema.json` | — | 🔴 missing | Case: init a scope, write a partial `.skill-map/settings.json` (optionally with a `.skill-map/settings.local.json` overlay), assert effective config after the layered merge. |
 | 7 | `plugins-registry.schema.json` | — | 🔴 missing | Two sub-cases required: (a) `PluginManifest` validation via `sm plugins show --json`; (b) aggregate `PluginsRegistry` via `sm plugins list --json`. |
 | 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. |

package/db-schema.md

@@ -19,7 +19,7 @@ Two scopes. Each has its own database file and its own migration ledger.
 | `project` (default) | `./.skill-map/skill-map.db` | The current repository. |
 | `global` (`-g`) | `~/.skill-map/skill-map.db` | User-level skill directories (e.g. `~/.claude/`). |
 
-The project DB is gitignored by default. Teams MAY opt in to sharing it by setting `history.share: true` in `.skill-map.json` — the file is then committed and the execution log becomes a team artifact. Both zones use the same schema.
+The project DB is gitignored by default. Teams MAY opt in to sharing it by setting `history.share: true` in `.skill-map/settings.json` — the file is then committed and the execution log becomes a team artifact. Both zones use the same schema.
 
 The `--db <path>` CLI flag overrides location for both scopes as an escape hatch.
 
@@ -272,6 +272,14 @@ Persists user-toggled enable/disable overrides. Discovery is still filesystem-ba
 | `config_json` | TEXT | NULL |
 | `updated_at` | INTEGER | NOT NULL |
 
+**Effective enable/disable resolution.** A plugin is enabled iff the highest-precedence layer that mentions it says so. Order from highest to lowest:
+
+1. `config_plugins.enabled` for the row whose `plugin_id` matches — written by `sm plugins enable/disable`. Local-machine user override; never committed (the DB is gitignored unless `history.share: true`).
+2. `.skill-map/settings.json#/plugins/<id>/enabled` — committed team-shared baseline.
+3. Installed default — every discovered plugin is enabled until told otherwise.
+
+The DB intentionally takes precedence over `settings.json` so a developer can locally disable a misbehaving plugin without committing the toggle to the team's config. Conversely, a team baseline that explicitly enables a plugin is overridable per-machine — no agreement is required to experiment.
+
 ### `config_preferences`
 
 General-purpose key-value for user preferences (`sm config set`).

package/index.json

@@ -190,11 +190,11 @@
       }
     ]
   },
-  "specPackageVersion": "0.6.0",
+  "specPackageVersion": "0.6.1",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "e74921b61ca835c4ebc8f2a4814d2c9513a59ce47c8c719b4d17865b39d93cba",
+      "CHANGELOG.md": "73e7db22a362dfe6b1d7aa8f456d57d2106936b831c7de6fc9b44c9f7f9642a2",
       "README.md": "8bd57e02d9a9d3f0a4efd18c0f0bd1f4bbe13eb206add0317659e48eab435e7e",
       "architecture.md": "99f9d6a1a90e6c96d3c8a6f36c2650da4a1af0a1bc21173ea8eb2c492008539a",
       "cli-contract.md": "bab14bb72ddd8a57e00808f7f12741c63a33da99055b278e4407ab9b4bb7e2c1",
@@ -203,7 +203,7 @@
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
       "conformance/cases/orphan-detection.json": "7fea6e866d775d09cadb70ccd764f6c8317ca61316c6d187a97cb2466db4e19e",
       "conformance/cases/rename-high.json": "f23513893e25fc4259db06a497906137de981da775d8ab2ef262554d54af5f27",
-      "conformance/coverage.md": "a67fb38c69765bb3cafb78c75e211c530ab00a88d8ccf0254335d3b6d4f69b8d",
+      "conformance/coverage.md": "ef98b87b70c46d7deb9853a8015c3e366a296088a70e13e4ffe223d91b9b4622",
       "conformance/fixtures/minimal-claude/agents/reviewer.md": "d0dd681ba63838301e480116aa09825329f01832b0116de5c5476fdd8a5dcf54",
       "conformance/fixtures/minimal-claude/commands/status.md": "3f36e053fd1c059ffd902f84a55be8a458c26072f97cb37dd7e97314ae2a9bf5",
       "conformance/fixtures/minimal-claude/hooks/pre-commit.md": "ec9cec8ac4ce34d40ec055ffd90e8f06ea3e5764d6ec3ee84e0d97de71b930c7",
@@ -215,7 +215,7 @@
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
       "conformance/fixtures/rename-high-after/skills/bar.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
       "conformance/fixtures/rename-high-before/skills/foo.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
-      "db-schema.md": "e9b436b143e2e56985c69498c7d48527bde0baa441be586e2740a4051b366c2d",
+      "db-schema.md": "002224f629403a247c0243d4b242c1e35e28bd93073ea53137ec1d30084d9bd7",
       "interfaces/security-scanner.md": "81dc3dc2c439a75f4603b6d52e714f44ac564032c8aa424385ebbf4502adae3e",
       "job-events.md": "08796b7fbeb55e5b03cf3bc394224e70a23438a4d15a46ad1d70121c2c68b967",
       "job-lifecycle.md": "1fe88b1a2ed204e41bb41ac172fbb3e912dccd0dd8a1f8ea8e21a681b336d6ee",
@@ -242,7 +242,7 @@
       "schemas/link.schema.json": "3e92f5c9def61a857a2c7b22846d82b988157de083463615144ddc92403a489e",
       "schemas/node.schema.json": "14f345fac450f5728c895d1b878e0015eabb9d72ba9da4a8d2236c82933d3fcf",
       "schemas/plugins-registry.schema.json": "92b2052bd06e366709dd6e1449d99408999e33707c4007afc7662980e73c3ef1",
-      "schemas/project-config.schema.json": "286895996eb8cfb8054eb53a9042ea89fbaa36c1eb9e38fdcfbe08440ae692e3",
+      "schemas/project-config.schema.json": "a37acdd6198e38dfc429161d92988170ddac91c6e98969e0aaaa8d717f5b9ba3",
       "schemas/report-base.schema.json": "a1021e9a59b4df9f99cd92454d797e88469766e7d49f52d231c4645ffdfdad8f",
       "schemas/scan-result.schema.json": "5efe9b1954c5e729c4b55dbc4dd51263d97967d16c0b3cea398877ace74d37b7",
       "schemas/summaries/agent.schema.json": "3d22558eeb170e00c4fc32018a810d27333cc632c9e528ff386100cfdfded087",

package/package.json

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

package/schemas/project-config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/project-config.schema.json",
   "title": "ProjectConfig",
-  "description": "Shape of `.skill-map.json` at the project root. All fields optional; defaults apply when absent. camelCase keys throughout — consistent with the rest of the spec.",
+  "description": "Shape of `.skill-map/settings.json` (and its `.skill-map/settings.local.json` partner) inside a scope. Loaded by the layered config hierarchy (library defaults → user → user-local → project → project-local → env/flags) and deep-merged per key. All fields optional; defaults apply when absent. camelCase keys throughout — consistent with the rest of the spec.",
   "type": "object",
   "additionalProperties": false,
   "properties": {