@skill-map/spec 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,228 @@
 # 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
+
+- 9a89124: Step 5.1 — Persist scan-result metadata in a new `scan_meta` table so
+  `loadScanResult` returns real values for `scope` / `roots` / `scannedAt` /
+  `scannedBy` / `adapters` / `stats.filesWalked` / `stats.filesSkipped` /
+  `stats.durationMs` instead of the synthetic envelope shipped at Step 4.7.
+
+  **Spec change (additive, minor)**:
+
+  - New `scan_meta` table in zone `scan_*`, single-row (CHECK `id = 1`).
+    Columns: `scope`, `roots_json`, `scanned_at`, `scanned_by_name`,
+    `scanned_by_version`, `scanned_by_spec_version`, `adapters_json`,
+    `stats_files_walked`, `stats_files_skipped`, `stats_duration_ms`.
+    `nodesCount` / `linksCount` / `issuesCount` are not stored — they are
+    derived from `COUNT(*)` of the sibling tables.
+  - Replaced atomically with the rest of `scan_*` on every `sm scan`.
+
+  **Runtime change**:
+
+  - New kernel migration `002_scan_meta.sql`.
+  - `IScanMetaTable` added to `src/kernel/adapters/sqlite/schema.ts` and
+    bound in `IDatabase`.
+  - `persistScanResult` writes the row (and deletes prior rows in the same
+    transaction).
+  - `loadScanResult` reads from `scan_meta` when the row exists; degrades
+    to the previous synthetic envelope when it does not (DB freshly
+    migrated, never scanned, or pre-5.1 snapshot).
+  - The Step 4.7 follow-up notes in `scan-load.ts` documenting the
+    synthetic envelope are simplified to describe both branches.
+
+  Test count: 151 → 154 (+3 covering meta round-trip, replace-all
+  single-row invariant, and synthetic-fallback on empty DB).
+
+- 9a89124: Step 5.7 — Conformance coverage for the rename heuristic.
+
+  **Spec change (additive, minor)**:
+
+  - `spec/schemas/conformance-case.schema.json` gains
+    `setup.priorScans: Array<{ fixture, flags? }>` — an ordered list of
+    staging scans the runner executes BEFORE the main `invoke`. Each
+    step replaces every non-`.skill-map/` directory in the scope with
+    the named fixture and runs `sm scan` (with optional flags). The DB
+    persists across steps because `.skill-map/` is preserved between
+    swaps. After the last step, the runner copies the top-level
+    `fixture` and runs the case's `invoke`.
+
+    Required to express scenarios that need a prior snapshot (rename
+    heuristic, future incremental cases). The schema is purely
+    additive — every existing case keeps passing without modification.
+
+  - Two new conformance cases under `spec/conformance/cases/`:
+
+    - **`rename-high`** — moving a single file with identical body
+      triggers a high-confidence auto-rename. Asserts:
+      `stats.nodesCount === 1`, `stats.issuesCount === 0`,
+      `nodes[0].path === skills/bar.md`. Verifies the spec invariant
+      that high-confidence renames emit NO issue.
+    - **`orphan-detection`** — deleting a file with no replacement
+      emits exactly one `orphan` issue (severity `info`). Asserts the
+      `ruleId` and `severity` directly.
+
+  - Four new fixture directories under `spec/conformance/fixtures/`:
+    `rename-high-before/`, `rename-high-after/`,
+    `orphan-before/`, `orphan-after/`.
+
+  - `spec/conformance/coverage.md`: row I (Rename heuristic) flips
+    from `🔴 missing` to `🟢 covered`. Notes the medium / ambiguous
+    branches stay covered by `src/test/rename-heuristic.test.ts` for
+    now (assertion vocabulary in the schema is not rich enough to
+    express "the issues array contains an item with ruleId X and
+    data.confidence === 'medium'" — when the conformance schema gains
+    array-filter assertions, those branches can land here too).
+
+  **Runtime change**:
+
+  - `src/conformance/index.ts` runner: implements `setup.priorScans`.
+    Helper `replaceFixture(scope, specRoot, fixture)` clears every
+    top-level entry in the scope except `.skill-map/`, then copies the
+    named fixture on top. Used by both staging steps and the main
+    `fixture` phase.
+  - `src/test/conformance.test.ts`: includes the two new cases in the
+    Step-0b subset. Total conformance cases passing in CI: 1 → 3.
+
+  **`spec/index.json`** regenerated (50 → 57 files). `npm run spec:check`
+  green.
+
+  Test count: 201 → 203 (+2 conformance cases). The Step 5 totals close
+  at: 151 → 203 (+52 across 7 sub-steps).
+
+### Patch Changes
+
+- dacd4d9: Move the auto-generated CLI reference from `docs/cli-reference.md` to
+  `context/cli-reference.md`. Spec change is editorial: `cli-contract.md`
+  references the file path in three spots (`--format md` description, the
+  NORMATIVE introspection section, and the "Related" link list); all three
+  updated to the new location. No schema or behavioural change.
+
+  Reference impl: `scripts/build-cli-reference.mjs` writes to the new path,
+  the `cli:reference` / `cli:check` npm scripts point there, and `sm help`
+  output (which embeds the path in the `--format md` flag description) is
+  regenerated. The `docs/` folder is gone.
+
 ## 0.5.1
 
 ### Patch Changes

package/cli-contract.md

@@ -121,7 +121,7 @@ Exit: 0 if all green, 1 if warnings, 2 if any `error`-level problem.
 Self-describing introspection.
 
 - `human` (default): pretty terminal output.
-- `md`: canonical markdown for documentation sites. Implementations MUST NOT hand-maintain equivalent markdown; `docs/cli-reference.md` (in the reference impl) is regenerated from this output in CI.
+- `md`: canonical markdown for documentation sites. Implementations MUST NOT hand-maintain equivalent markdown; `context/cli-reference.md` (in the reference impl) is regenerated from this output in CI.
 - `json`: structured surface dump. Shape:
 
 ```json
@@ -314,7 +314,7 @@ Destructive verbs (`reset --state`, `reset --hard`, `restore`) require interacti
 ### Introspection
 
 - `sm help --format json` — structured CLI surface dump.
-- `sm help --format md` — canonical markdown, CI-enforced for the reference impl's `docs/cli-reference.md`.
+- `sm help --format md` — canonical markdown, CI-enforced for the reference impl's `context/cli-reference.md`.
 
 These two formats are NORMATIVE: any change to verbs, flags, or exit codes MUST reflect in `--format json` output immediately. Third-party consumers rely on this.
 
@@ -390,7 +390,7 @@ The `done in …` stderr line, its format grammar, and the `elapsedMs` field con
 - [`job-lifecycle.md`](./job-lifecycle.md) — state machine behind `sm job` verbs.
 - [`job-events.md`](./job-events.md) — event stream emitted via `--json` and `--stream-output`.
 - [`db-schema.md`](./db-schema.md) — tables behind `sm db` verbs.
-- [`../docs/cli-reference.md`](../docs/cli-reference.md) — auto-generated reference from `sm help --format md`.
+- [`../context/cli-reference.md`](../context/cli-reference.md) — auto-generated reference from `sm help --format md`.
 - [`conformance/`](./conformance/README.md) — test suite exercising CLI behavior.
 
 ---

package/conformance/cases/orphan-detection.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "orphan-detection",
+  "description": "Deleting a file with no replacement triggers the orphan branch of the rename heuristic: exactly one issue with ruleId `orphan` is emitted, severity `info`, naming the dead path. The remaining survivor node is reported normally.",
+  "fixture": "orphan-after",
+  "setup": {
+    "priorScans": [
+      { "fixture": "orphan-before" }
+    ]
+  },
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--changed", "--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.issues[0].ruleId", "equals": "orphan" },
+    { "type": "json-path", "path": "$.issues[0].severity", "equals": "info" }
+  ]
+}

package/conformance/cases/rename-high.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "rename-high",
+  "description": "Moving a single file with identical body across the rename triggers a high-confidence auto-rename: NO issue is emitted (per spec/db-schema.md §Rename detection), the new path is the only node in the result, and the rename heuristic operates silently.",
+  "fixture": "rename-high-after",
+  "setup": {
+    "priorScans": [
+      { "fixture": "rename-high-before" }
+    ]
+  },
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--changed", "--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 0 },
+    { "type": "json-path", "path": "$.nodes[0].path", "equals": "skills/bar.md" }
+  ]
+}

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. |
@@ -54,7 +54,7 @@ These have their own conformance cases even though they are not JSON Schemas.
 | F | Nonce mismatch | — | 🔴 missing | Blocked by Step 10. `sm record` with wrong nonce → exit 4. |
 | G | Reap | — | 🔴 missing | Blocked by Step 10. Set TTL to 1s; claim; wait; next `sm job run` reaps with reason `abandoned`. |
 | H | `run.*` event envelope for Skill agent | — | 🔴 missing | Blocked by Step 10. Skill-agent flow emits synthetic `r-ext-*` run envelope around one job. |
-| I | Rename heuristic | — | 🔴 missing | Blocked by Step 5. Move a file; same-`body_hash` → high-confidence auto-rename; `state_*` FK rows migrated; no issue emitted. |
+| I | Rename heuristic | `rename-high`, `orphan-detection` | 🟢 covered | High-confidence rename emits no issue and the new path is the sole node. Orphan branch emits exactly one `orphan` issue (severity `info`) when a deleted node has no replacement. Medium / ambiguous branches are exercised by `src/test/rename-heuristic.test.ts` until the conformance schema grows richer assertions. |
 | J | Plugin DDL rejection | — | 🔴 missing | Blocked by Step 9. Plugin migration referencing `state_jobs` → disabled with `invalid-manifest`. |
 | K | Plugin prefix injection | — | 🔴 missing | Blocked by Step 9. Plugin declares `CREATE TABLE foo` → kernel applies as `plugin_<id>_foo`. |
 | L | Elapsed-time reporting | — | 🔴 missing | Blocked by Step 4 (first real verb work). Run any in-scope verb; stderr last line MUST match `/^done in (\d+ms\|\d+\.\d+s\|\d+m \d+s)$/`. In-scope verb with `--json` returning an object MUST carry `elapsedMs`. Exempt verb (`sm version`) MUST NOT emit the line. |

package/conformance/fixtures/orphan-after/skills/keep.md

@@ -0,0 +1,13 @@
+---
+name: orphan-keep
+description: Fixture node that survives across before/after, so the after-state still has at least one node.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Survivor
+
+Keeps the after-state graph non-empty so we can assert that the orphan
+issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/keep.md

@@ -0,0 +1,13 @@
+---
+name: orphan-keep
+description: Fixture node that survives across before/after, so the after-state still has at least one node.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Survivor
+
+Keeps the after-state graph non-empty so we can assert that the orphan
+issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/lonely.md

@@ -0,0 +1,13 @@
+---
+name: orphan-lonely
+description: Fixture node that gets deleted in the after-state to trigger the orphan path.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Orphan lonely body
+
+This file disappears in `orphan-after`. With no replacement matching
+its hashes, the rename heuristic emits an `orphan` issue.

package/conformance/fixtures/rename-high-after/skills/bar.md

@@ -0,0 +1,14 @@
+---
+name: rename-high-foo
+description: Fixture node for the high-confidence rename conformance case.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Rename high body
+
+Body content kept identical between the before and after fixtures so
+the body hash matches across the rename. Move it to `bar.md` to trigger
+a high-confidence auto-rename.

package/conformance/fixtures/rename-high-before/skills/foo.md

@@ -0,0 +1,14 @@
+---
+name: rename-high-foo
+description: Fixture node for the high-confidence rename conformance case.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Rename high body
+
+Body content kept identical between the before and after fixtures so
+the body hash matches across the rename. Move it to `bar.md` to trigger
+a high-confidence auto-rename.

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.
 
@@ -134,6 +134,28 @@ One row per rule-emitted issue, matching [`schemas/issue.schema.json`](./schemas
 
 Indexes: `ix_scan_issues_rule_id`, `ix_scan_issues_severity`.
 
+### `scan_meta`
+
+Single-row table holding the metadata of the last persisted scan. Lets `loadScanResult` return the real `scope` / `roots` / `scannedAt` / `scannedBy` / `adapters` / `stats.filesWalked|filesSkipped|durationMs` instead of synthesising them. Replaced atomically with the rest of the `scan_*` zone on every `sm scan`.
+
+`nodesCount` / `linksCount` / `issuesCount` are not stored here — they derive from `COUNT(*)` of the sibling tables.
+
+| Column | Type | Constraint |
+|---|---|---|
+| `id` | INTEGER | PRIMARY KEY, CHECK `id = 1` |
+| `scope` | TEXT | NOT NULL, CHECK in (`project`, `global`) |
+| `roots_json` | TEXT | NOT NULL | JSON array of strings (filesystem roots walked). |
+| `scanned_at` | INTEGER | NOT NULL | Unix milliseconds. |
+| `scanned_by_name` | TEXT | NOT NULL |
+| `scanned_by_version` | TEXT | NOT NULL |
+| `scanned_by_spec_version` | TEXT | NOT NULL |
+| `adapters_json` | TEXT | NOT NULL | JSON array of adapter ids. |
+| `stats_files_walked` | INTEGER | NOT NULL |
+| `stats_files_skipped` | INTEGER | NOT NULL |
+| `stats_duration_ms` | INTEGER | NOT NULL |
+
+No indexes (single row).
+
 ---
 
 ## Table catalog: zone `state_`
@@ -250,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,31 +190,38 @@
       }
     ]
   },
-  "specPackageVersion": "0.5.1",
+  "specPackageVersion": "0.6.1",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "b810067bdba655d066242db3159a157880250257c6cff03e96acc614758b8d1d",
+      "CHANGELOG.md": "73e7db22a362dfe6b1d7aa8f456d57d2106936b831c7de6fc9b44c9f7f9642a2",
       "README.md": "8bd57e02d9a9d3f0a4efd18c0f0bd1f4bbe13eb206add0317659e48eab435e7e",
       "architecture.md": "99f9d6a1a90e6c96d3c8a6f36c2650da4a1af0a1bc21173ea8eb2c492008539a",
-      "cli-contract.md": "4f01df640f39eacbb2192d543288e670de9ce2b89bf3931bc09f8488eb3baaea",
+      "cli-contract.md": "bab14bb72ddd8a57e00808f7f12741c63a33da99055b278e4407ab9b4bb7e2c1",
       "conformance/README.md": "79c5e63f18a368951dc9f3e31e9bf9574de3f8b97150b2d75365d4febd8eb6dc",
       "conformance/cases/basic-scan.json": "24623da0cad8c8c54b3ff9b09820ea1276fe8b8f0fc680bf6e8abeb4edb8e424",
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
-      "conformance/coverage.md": "db9518f5a560b3df01093107de5c09ff38d478ae07c0476eea92644677fb1d83",
+      "conformance/cases/orphan-detection.json": "7fea6e866d775d09cadb70ccd764f6c8317ca61316c6d187a97cb2466db4e19e",
+      "conformance/cases/rename-high.json": "f23513893e25fc4259db06a497906137de981da775d8ab2ef262554d54af5f27",
+      "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",
       "conformance/fixtures/minimal-claude/notes/architecture.md": "5a7e6fdbb1556733dacebad63758057dc1e19090b5a983292c0c65e90b98bcf1",
       "conformance/fixtures/minimal-claude/skills/hello.md": "8598074020430f294ff1eac39876302448f004b6c48446d453092159319bcbee",
+      "conformance/fixtures/orphan-after/skills/keep.md": "a6fdc33104cb2e8092f386a427784685eee1c8d7cb8fddb934cf65984143c7fd",
+      "conformance/fixtures/orphan-before/skills/keep.md": "a6fdc33104cb2e8092f386a427784685eee1c8d7cb8fddb934cf65984143c7fd",
+      "conformance/fixtures/orphan-before/skills/lonely.md": "4ba2bb336fa46644d2b0dfef4c3b97879ecbf693b825a5348f032d1af049d80a",
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
-      "db-schema.md": "ce4f9ddf84fa2aad746b44d6d9142b29b23c339e4915f97928489e035100fa55",
+      "conformance/fixtures/rename-high-after/skills/bar.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
+      "conformance/fixtures/rename-high-before/skills/foo.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
+      "db-schema.md": "002224f629403a247c0243d4b242c1e35e28bd93073ea53137ec1d30084d9bd7",
       "interfaces/security-scanner.md": "81dc3dc2c439a75f4603b6d52e714f44ac564032c8aa424385ebbf4502adae3e",
       "job-events.md": "08796b7fbeb55e5b03cf3bc394224e70a23438a4d15a46ad1d70121c2c68b967",
       "job-lifecycle.md": "1fe88b1a2ed204e41bb41ac172fbb3e912dccd0dd8a1f8ea8e21a681b336d6ee",
       "plugin-kv-api.md": "04b2178f46fb88adeae9240df9c9e1761b660396072001dac32cd402e11a2d7d",
       "prompt-preamble.md": "23a8eff0477fbbc46192a27781bc781bda4202bb9c669b7a7a002b0d668146b0",
-      "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
+      "schemas/conformance-case.schema.json": "d69c501bbca079da0ca87685eb4cbdbc2e405334469fc937929ca9134e01a2b3",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
       "schemas/extensions/action.schema.json": "c7520d3cefecf75d27d3e04473821fd6e5dc5a7924eede147f74275ba6caccad",
       "schemas/extensions/adapter.schema.json": "429b865e738664bb437ac62690a2d7282ce992339fbb300417c73625f5cdb7c8",
@@ -235,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.5.1",
+  "version": "0.6.1",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",

package/schemas/conformance-case.schema.json

@@ -28,12 +28,32 @@
     },
     "setup": {
       "type": "object",
-      "description": "Pre-invocation toggles. All default to `false`.",
+      "description": "Pre-invocation toggles and ordered staging steps. All toggles default to `false`. `priorScans`, when present, run BEFORE the main `invoke` so a case can establish a prior snapshot the heuristic-driven verbs (e.g. `sm scan` rename detection) can react to.",
       "additionalProperties": false,
       "properties": {
         "disableAllAdapters": { "type": "boolean" },
         "disableAllDetectors": { "type": "boolean" },
-        "disableAllRules": { "type": "boolean" }
+        "disableAllRules": { "type": "boolean" },
+        "priorScans": {
+          "type": "array",
+          "description": "Ordered staging scans, each running before the next. For step N, the runner first replaces the scope's adapter content with `priorScans[N].fixture`, then invokes `sm scan` with the supplied flags. After the last step, the runner copies the top-level `fixture` (overwriting again) and runs the main `invoke`. The DB persists across all steps because `.skill-map/` is preserved between fixture swaps.",
+          "items": {
+            "type": "object",
+            "required": ["fixture"],
+            "additionalProperties": false,
+            "properties": {
+              "fixture": {
+                "type": "string",
+                "description": "Folder under `conformance/fixtures/` to copy into the scope, replacing every non-`.skill-map/` directory."
+              },
+              "flags": {
+                "type": "array",
+                "description": "Flags passed to `sm scan`. Default: empty (full scan).",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
       }
     },
     "invoke": {

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": {