@skill-map/spec 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,756 @@
 # Spec changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- 6dad772: v0.8.0 — Pre-1.0 stabilization pass.
+
+  This release combines two coherent pre-1.0 cleanup pieces that
+  both push the project closer to v1.0 stability: the cli-architect
+  audit review pass and the plugin model overhaul.
+
+  Pre-1.0 minor bumps per `versioning.md` § Pre-1.0; breaking
+  changes allowed within minor while in `0.Y.Z`. No real downstream
+  ecosystem exists yet, so the breaking surface costs nothing
+  today.
+
+  ## Part 1 — Pre-1.0 audit review pass
+
+  Pre-1.0 review pass — `cli-architect` audit findings.
+
+  Internal audit run by the `cli-architect` agent in REVIEW mode
+  produced a Critical / High / Medium / Low / Nit catalog. This
+  pass bundles the implementation of every actionable finding into
+  one unit so the review can be read end-to-end. **Pre-1.0 minor
+  bump**: a few breaking surface changes ride along (CLI sub-verb
+  split, exit-code enum exposed, plugin loader option). No
+  published downstream consumers exist yet.
+
+  ### Spec changes (`@skill-map/spec`)
+
+  - **`cli-contract.md`** — `sm scan compare-with <dump> [roots...]`
+    is now a sub-verb instead of a `--compare-with <path>` flag on
+    `sm scan`. Read-only delta report against a saved `ScanResult`
+    JSON dump. Read-only — does not modify the DB. Same exit codes
+    (`0` empty delta / `1` drift / `2` operational error). Old flag
+    form removed.
+  - **`cli-contract.md`** — exit-code `2` "Operational error" row
+    clarified to mention environment / runtime mismatches (wrong
+    Node version, missing native dependency) explicitly. The
+    "unhandled exception" catch-all already covered the case; this
+    just removes ambiguity for future implementers.
+  - **`cli-contract.md`** — new normative section **§Dry-run**
+    between §Exit codes and §Verb catalog defining the contract for
+    any verb exposing `-n` / `--dry-run`: no observable side effects
+    (DB / FS / config / network / spawns), no auto-provisioning of
+    scope directories, output mirrors the live mode with explicit
+    "would …" framing, exit codes mirror the live mode, dry-run
+    MUST short-circuit `--yes` / `--force` confirmation prompts.
+    Per-verb opt-in: the flag is not global, verbs that don't
+    declare it MUST reject it as an unknown option. Verb catalog
+    rows for `sm init`, `sm db reset` (default + `--state` +
+    `--hard`), and `sm db restore` amended to declare and describe
+    their `--dry-run` previews.
+
+  ### CLI changes (`@skill-map/cli`)
+
+  #### Critical — kernel & adapter hygiene
+
+  - **C1 — `runScanInternal` decomposed.** The 290-line monolith in
+    `kernel/orchestrator.ts` split into a thin composer + four pure
+    functions: `validateRoots`, `indexPriorSnapshot`,
+    `walkAndDetect`, `runRules`. Composer is now 89 lines reading
+    top-to-bottom through the pipeline phases. Zero behavioural
+    change.
+  - **C2 — `withSqlite(options, fn)` helper.** Single utility at
+    `cli/util/with-sqlite.ts` standardises the open / use / close
+    idiom every read-side command was open-coding. Eliminates four
+    classes of boilerplate bugs (forgotten close, `autoBackup`
+    drift, double-close, missing `try/finally`). Migrated 20 call
+    sites across `check`, `export`, `graph`, `history`, `init`,
+    `jobs`, `list`, `orphans`, `plugins`, `scan`, `show`, `watch`,
+    plus `cli/util/plugin-runtime.ts`. Companion `tryWithSqlite`
+    short-circuits when the DB file does not exist, replacing the
+    `if (existsSync) { withSqlite(...) }` chain. In `scan.ts` the
+    read-prior + persist double-open consolidated into a single
+    `withSqlite` callback that brackets read prior → run scan →
+    guard → persist when `willPersist`. Saves one migration
+    discovery pass + one WAL setup per normal scan (~50–100ms).
+
+  #### High — UX & contract integrity
+
+  - **H3 — `--dry-run` semantics unified across `init` / `db reset`
+    / `db restore`.** The new spec §Dry-run codifies the "no
+    writes, reads OK" contract; three verbs that did not previously
+    expose a preview now do:
+    - `sm init --dry-run` — previews the would-create lines for
+      `.skill-map/`, `settings.json`, `settings.local.json`,
+      `.skill-mapignore`, the `.gitignore` entries that would be
+      appended (deduped against the existing file), the DB
+      provisioning, and the first-scan trigger. Honours `--force`
+      for the would-overwrite preview. Re-init over an existing
+      scope without `--force` still exits 2 (same gate as live).
+    - `sm db reset --dry-run` (default + `--state`) — opens the DB
+      read-only, computes the row count per `scan_*` (and `state_*`
+      when `--state`) table, and prints them. No `DELETE`
+      statements issued. Bypasses the `--state` confirmation prompt
+      entirely.
+    - `sm db reset --hard --dry-run` — reports the DB file path and
+      size that would be unlinked; missing-file case prints a clear
+      no-op line instead of an error.
+    - `sm db restore <src> --dry-run` — validates the source exists
+      (still exits 5 if missing), reports the source size and
+      whether the target would be created or overwritten, plus the
+      WAL / SHM sidecars that would be dropped. Bypasses the
+      confirmation prompt.
+      Implementation: new helper `previewGitignoreEntries(scopeRoot,
+entries)` in `init.ts` mirrors `ensureGitignoreEntries` parsing
+      so the preview tracks the live outcome exactly. Texts moved
+      into `cli/i18n/init.texts.ts` and `cli/i18n/db.texts.ts` per
+      the N4 pattern. **9 new tests** under `init-cli.test.ts` (5
+      cases) and `db-cli.test.ts` (9 cases) cover the previews + the
+      spec invariants ("DB file checksum unchanged after dry-run",
+      "scope directory absent after dry-run", "source-not-found
+      still exits 5", "confirmation prompt skipped under dry-run").
+  - **H1 — Centralised exit codes.** New `cli/util/exit-codes.ts`
+    exporting `ExitCode` (`Ok` / `Issues` / `Error` / `Duplicate` /
+    `NonceMismatch` / `NotFound`) and the type alias `TExitCode`.
+    Every `Command#execute()` migrated from numeric literals (123
+    sites across 17 files) to the enum. Single source of truth
+    aligned with `spec/cli-contract.md` §Exit codes. **Bug fix
+    surfaced en passant:** `sm job prune` returned `2` for "DB
+    missing" while every other read-side verb returned `5` via
+    `assertDbExists`; corrected to use the shared helper and return
+    `NotFound`. Companion test updated to expect `5`.
+  - **H2 — Plugin loader timeout.** `IPluginLoaderOptions.loadTimeoutMs`
+    (default `5000`, exported as `DEFAULT_PLUGIN_IMPORT_TIMEOUT_MS`).
+    Each dynamic `import()` now races against a timer; on timeout
+    the plugin is reported as `load-error` with a message naming
+    the elapsed budget and pointing at top-level side effects as
+    the likely cause (network call, infinite loop, large blocking
+    work). Without this a plugin with a hanging top-level `await`
+    blocks every host CLI command indefinitely.
+  - **H4 — `--strict` self-validates `--json` output.** When
+    `sm scan --strict --json` is invoked, the produced `ScanResult`
+    is validated against `scan-result.schema.json` before stdout.
+    Catches the case where a custom detector emits a Link that
+    passes the shallow `validateLink` guard but fails the full
+    schema, which would silently land in stdout and break a
+    downstream `sm scan compare-with -`.
+  - **H5 — External-link discrimination uses URL-shape regex.**
+    `isExternalUrlLink` was string-matching `http://` / `https://`
+    only; any other URL scheme (`mailto:`, `data:`, `file:///`,
+    `ftp://`) was silently classified as internal and polluted the
+    graph as a fake internal link with `byPath` lookups that always
+    missed. Replaced with the RFC 3986 scheme regex
+    (`/^[a-z][a-z0-9+\-.]+:/i`), guarding against Windows-style
+    absolute paths via the ≥ 2-char scheme constraint.
+  - **H6 — Prior snapshot validated under `--strict`.** Both
+    `sm scan` and `sm watch`, when run with `--strict`, validate
+    the DB-resident `ScanResult` against the spec schema before
+    handing it to the orchestrator. A DB corrupted manually or
+    mid-rollback used to slip nodes with malformed `bodyHash` /
+    `frontmatterHash` into the rename heuristic, where the
+    dereference would silently produce spurious matches.
+
+  #### Medium — surface & extensibility
+
+  - **M1 — `sm scan compare-with` sub-verb.** New
+    `ScanCompareCommand` in `cli/commands/scan-compare.ts`; the
+    `--compare-with` flag is removed from `ScanCommand`. The
+    sub-verb form structurally rejects flag combos that used to
+    require runtime guards (`--changed`, `--no-built-ins`,
+    `--allow-empty`, `--watch`): Clipanion rejects them at parse
+    time as unknown options.
+  - **M2 — `kernel/index.ts` enumerated exports.** Replaced the two
+    `export type *` wildcards (from `./types.js` and
+    `./ports/index.js`) with explicit named exports. Same set of
+    public types — the DTS size and tests confirm parity. Going
+    forward, any new domain type or port change requires an
+    explicit edit to the barrel, preventing silent surface drift.
+  - **M3 — Build hack documented (workaround retained).** Tried to
+    replace the post-build `restoreNodeSqliteImports` pass with
+    `external: ['node:sqlite']` in `tsup.config.ts`. Esbuild marks
+    the specifier as external but still strips the `node:` prefix;
+    same outcome with `[/^node:/]` regex and `packages: 'external'`
+    (which also externalises real npm deps). Reverted to the
+    post-build `replaceAll` pass, with a docstring documenting
+    every workaround attempted so the next agent does not repeat
+    the spike.
+  - **M4 — `tryWithSqlite` helper.** See C2.
+  - **M5 — `CamelCasePlugin` trap documented.** Added a
+    trap-warning block to `SqliteStorageAdapter`'s docstring:
+    `sql.raw` / `sql\`...\``template literals do NOT pass through
+the`CamelCasePlugin`; raw SQL fragments must use snake_case to
+    match the migrations.
+  - **M6 — Per-extension error reporting.** When the orchestrator
+    drops a link emitted with an undeclared kind or an issue with
+    an invalid severity, it now emits a `type: 'extension.error'`
+    `ProgressEvent` instead of silently swallowing. The CLI
+    subscribes via the new `createCliProgressEmitter(stderr)`
+    helper and renders those events as `extension.error: <message>`
+    on stderr. Plugin authors finally see WHY their link / issue
+    disappears from the result. Wired in `scan` (normal +
+    compare-with), `watch`, and `init`.
+  - **M7 — Type naming convention documented (no rename).** Top-of-
+    file docstring in `kernel/types.ts` and a new section in
+    `AGENTS.md` describe the four-bucket convention the codebase
+    has always implicitly followed: domain types (no prefix,
+    mirrors spec schemas), hexagonal ports (`Port` suffix), runtime
+    extension contracts (`I` prefix), internal shapes (`I`
+    prefix). Mass rename was rejected after a cost-benefit pass —
+    naming changes are cheap to write but expensive to review;
+    existing names are mostly coherent. The agent base
+    (`_plugins/minions/shared/architect.md`) gained a "Naming
+    conventions check" sub-section in REVIEW mode so future audits
+    reach the same conclusion.
+
+  #### Low / nit — cleanup
+
+  - **L1 — `omitModule` JSON replacer precision.** Identifies the
+    ESM namespace by `[Symbol.toStringTag] === 'Module'` instead of
+    matching every `module` key blindly. A plugin manifest that
+    legitimately ships an unrelated `module` field (e.g. a string
+    property in `metadata`) is no longer silently dropped from
+    `sm plugins list --json` output.
+  - **L2 — Stub verbs flagged in `--help`.** Every
+    `not-yet-implemented` verb in `cli/commands/stubs.ts` carries a
+    `(planned)` suffix on its `description`, surfaced in
+    `sm --help`. The `notImplemented` helper now writes
+    `<verb>: not yet implemented (planned).` on stderr instead of
+    promising a specific Step number — roadmap step numbers shift
+    mid-flight, stale promises in `--help` are worse than no
+    promise.
+  - **L3 — Dead `eslint-disable` removed** from
+    `cli/util/plugin-runtime.ts`.
+  - **N1 — `Link.source` vs `Link.sources` doc clarified.** Both
+    fields now carry inline doc-comments calling out the singular /
+    plural naming trap. Spec-frozen, but the ambiguity is the
+    easiest way to misread the type for new contributors.
+  - **N2 — `sm check` Usage examples expanded.** The `-g/--global`
+    and `--db <path>` flags were declared but missing from the
+    `Usage.examples` block — asymmetry with `sm scan` and the rest
+    of the read-side verbs that ship the same flags. Two examples
+    added: `sm check --global` and `sm check --db
+/path/to/skill-map.db`.
+  - **N4 — Error / hint strings extracted to `*.texts.ts` modules
+    with `{{name}}` template interpolation.** Pre-1.0 is the
+    natural moment to seed the pattern before the string set grows.
+    The workspace `ui/` already has a sibling layout at
+    `ui/src/i18n/` (functions returning template literals); CLI
+    takes a deliberately different shape — flat string templates
+    with `{{name}}` placeholders, interpolated by a tiny
+    `tx(template, vars)` helper. Rationale: the template form is
+    **drop-in compatible with Transloco / Mustache / Handlebars**
+    (the syntax they all share) so the day this project migrates to
+    a real i18n library, the strings move as-is. Functions would
+    have to be re-shaped first.
+
+    Helper at `kernel/util/tx.ts`. Contract:
+
+    - Every `{{name}}` token MUST have a matching key in the vars
+      object — missing key throws (silent fallback hides
+      forgotten args in production).
+    - `null` / `undefined` values throw — caller coerces
+      upstream.
+    - Whitespace inside the braces tolerated (`{{ name }}`) so
+      long templates wrap cleanly across `+`-joined lines.
+    - Plural / conditional logic does NOT live in the template;
+      the caller picks `*_singular` vs `*_plural` keys.
+
+    Files created:
+
+    - `kernel/util/tx.ts` — the helper itself, with 13 tests in
+      `test/tx.test.ts` (single / multi token, whitespace,
+      missing / null / undefined keys, identifier shapes, error
+      truncation).
+    - `kernel/i18n/orchestrator.texts.ts` — frontmatter
+      malformed/invalid templates, `extension.error` payloads,
+      root validation errors.
+    - `kernel/i18n/plugin-loader.texts.ts` — every `load-error` /
+      `invalid-manifest` / `incompatible-spec` reason, plus the
+      import timeout message.
+    - `cli/i18n/scan.texts.ts` — `sm scan` flag-clash / scan
+      failure / guard / summary templates, plus the `sm scan
+compare-with` dump-load errors.
+    - `cli/i18n/watch.texts.ts` — `sm watch` lifecycle templates.
+    - `cli/i18n/init.texts.ts` — `sm init` templates including
+      the `--dry-run` previews and the singular/plural pair for
+      gitignore updates.
+    - `cli/i18n/db.texts.ts` — `sm db reset` / `sm db restore`
+      templates including their `--dry-run` previews.
+    - `cli/i18n/cli-progress-emitter.texts.ts` — the
+      `extension.error: ...` stderr line.
+
+    String content moved verbatim — every existing test that
+    matches on stderr / stdout content keeps passing. Trivial
+    single-token strings (`'No issues.\n'`) and rare per-handler
+    bespoke phrases stay inline; the pattern is now established
+    for whoever wants to migrate them in a follow-up.
+
+    Note on `ui/` divergence: today the two workspaces use
+    different shapes for their text tables (functions in `ui/`,
+    templates in `cli/`). Aligning them is a follow-up — the day a
+    real i18n library lands, both converge on its native shape.
+    The CLI shape is closer to the eventual destination.
+
+  - **N6 — `TIssueSeverity` aliased to `Severity`.** SQLite schema
+    type now reads `type TIssueSeverity = Severity` instead of
+    duplicating the union literal. Keeps DB and runtime in
+    lock-step if the union ever evolves.
+
+  ### Migrations consolidation (kernel DB)
+
+  - **`src/migrations/001_initial.sql` + `002_scan_meta.sql`**
+    consolidated into a single `001_initial.sql`. Pre-1.0 with no
+    released DBs to forward-migrate, the two-file split was a
+    historical accident from an incremental shipment. After
+    consolidation: same 12 tables, same constraints, same indexes;
+    `PRAGMA user_version` of a freshly-initialised DB is now `1`
+    instead of `2`. Migration runner is unchanged (it tolerates any
+    count of `NNN_*.sql` files).
+
+  ### Test coverage (Part 1)
+
+  - New tests for H2 (plugin loader timeout — 2 cases),
+    M6 (orchestrator `extension.error` emission — 3 cases),
+    CLI progress emitter wiring (4 cases). The compare-with suite
+    (`scan-compare.test.ts`, 9 cases) was migrated to
+    `ScanCompareCommand` and the three flag-clash tests dropped
+    (the flags are now structurally absent on the sub-verb). Test
+    totals: 479 (start of pass) → 488 (after H2/M6 tests) → 485
+    (after the three flag-clash deletions).
+
+  ### Deferred / out of scope
+
+  The findings below were reviewed but did not warrant code
+  changes; each has its own resolution noted alongside.
+
+  - **L4 — `runScan` / `runScanWithRenames` unification.** Already
+    resolved by C1 (both are thin wrappers around
+    `runScanInternal`).
+  - **L5 — Node-version-guard exit code.** Reviewed against the
+    updated exit-code table; existing `2` is correct under
+    "operational error / unhandled exception". Spec table got the
+    environment-mismatch clarification (above).
+  - **L6 — `loadSchemaValidators()` cache.** Already cached at
+    module level since Step 5.12.
+  - **L7 — `pkg with { type: 'json' }` portability.** Stable in
+    Node ≥ 22; `engines.node": ">=24.0"` covers it. No fallback
+    needed.
+  - **N3 — `compare-with` "dump not found" exit code.** The error
+    paths in `ScanCompareCommand` already use the `ExitCode.Error`
+    enum (= 2) for dump load failures, matching the spec clause for
+    operational errors.
+  - **N5 — Exit-code list completeness.** Verified the comment in
+    `cli/entry.ts` against `spec/cli-contract.md` §Exit codes —
+    identical, no edit needed.
+
+  ## Part 2 — Plugin model overhaul (5-phase implementation)
+
+  ### Summary
+
+  The plugin model received a comprehensive overhaul before
+  stabilizing at v1.0. Plugin kinds total after this bump: **6**
+  (Provider, Extractor, Rule, Action, Formatter, Hook). All
+  breakings are pre-1.0 minor per `versioning.md` § Pre-1.0.
+
+  ### Phase 1 (commit 7354c26) — Foundation
+
+  Five sub-phases, additive or pre-1.0 minor breakings:
+
+  - **A.4** — three-tier frontmatter validation model documented in
+    `plugin-author-guide.md` (default permissive + `unknown-field`
+    rule + `scan.strict` promote-to-error). Behavior unchanged.
+  - **A.5** — plugin id global uniqueness: `directory ==
+manifest.id` rule, new status `id-collision` (sixth),
+    validation in boot/scan/doctor. Cross-root collisions block
+    both involved plugins; user resolves by renaming.
+  - **A.6** — extension ids qualified `<plugin-id>/<ext-id>` in
+    registry. Built-ins classified into `claude/*` (4 Claude-
+    specific) and `core/*` (7 kernel built-ins) bundles. New
+    `Registry.get/find` APIs; `defaultRefreshAction` schema
+    requires the qualified pattern; `extension.error` events emit
+    qualified ids.
+  - **A.10** — optional `applicableKinds` filter on Detector
+    manifest; fail-fast skip for non-matching kinds (zero CPU/LLM
+    cost); doctor warning for kinds not declared by any installed
+    Provider. Empty array invalid; absence preserves apply-to-all
+    default.
+  - **Granularity** — Built-ins now respect `config_plugins`
+    enable/disable via granularity-aware filtering. New
+    `IBuiltInBundle` shape with `granularity: 'bundle' |
+'extension'`; `claude` ships as bundle (all-or-nothing), `core`
+    as extension (each toggleable). User plugins default to bundle;
+    opt in via `granularity` in `plugin.json`. Both plugin ids and
+    qualified extension ids accepted as keys in `config_plugins`
+    and `settings.json#/plugins` (no schema change needed).
+
+  550/550 tests pass (+33 vs baseline 517).
+
+  ### Phase 2 (commit ae3eaa6) — Renames
+
+  Four sub-phases, all breaking but allowed in minor pre-1.0:
+
+  - **2a (Renderer → Formatter)** — Kind, types, files renamed.
+    Method `render(ctx)` → `format(ctx)`; manifest field `format`
+    → `formatId` (TS clash resolution). Same contract: graph →
+    string, deterministic-only.
+  - **2b (Adapter → Provider)** — New required field
+    `explorationDir` on the manifest (e.g. `~/.claude` for the
+    Claude Provider). DB schema migrated in-place (column
+    `nodes.adapter` → `nodes.provider`, etc.). The
+    hexagonal-architecture `RunnerPort.adapter` /
+    `StoragePort.adapter` is unchanged.
+  - **2c (Audit removed)** — Audit kind removed. The single
+    built-in `validate-all` migrated to a Rule (qualified id
+    `core/validate-all`, `evaluate(ctx) → Issue[]`). CLI verbs
+    `sm audit *` removed; users invoke via `sm check --rules
+core/validate-all`.
+  - **2d (Detector → Extractor)** — Method signature changes from
+    `detect(ctx) → Link[]` to `extract(ctx) → void` — output flows
+    through three ctx callbacks: `emitLink`, `enrichNode`, `store`.
+    Built-ins migrated maintain functional parity using `emitLink`.
+    Persistence of `enrichNode` deferred to Phase 4 (A.8 stale
+    layer); orchestrator buffers in memory today.
+
+  554/554 cli + 32/32 testkit pass.
+
+  ### Phase 3 (commit 34f993e) — Schema relocation
+
+  **A.2** — Per-kind frontmatter schemas relocate from spec to the
+  Provider that declares them. Spec keeps only `frontmatter/base`
+  (universal).
+
+  - 5 schemas moved (`git mv`):
+    `spec/schemas/frontmatter/{skill,agent,command,hook,note}.schema.json`
+    → built-in Claude Provider's `schemas/` directory. New `$id`:
+    `https://skill-map.dev/providers/claude/v1/frontmatter/<kind>`.
+    Cross-package `$ref` resolves via the spec base's `$id`
+    (`https://skill-map.dev/spec/v0/frontmatter/base.schema.json`);
+    AJV resolves by `$id` when both schemas register on the same
+    instance.
+  - Provider manifest gains a required `kinds` map subsuming three
+    former fields: `emits` (now derives from
+    `Object.keys(kinds)`), the flat `defaultRefreshAction` map (now
+    per-entry inside `kinds[<kind>].defaultRefreshAction`), and the
+    new `schema` (path to the per-kind schema relative to the
+    provider directory).
+  - Built-in Claude Provider migrated: 5 kind entries (skill,
+    agent, command, hook, note), each with `schema`, `schemaJson`
+    (runtime field, AJV-compiled at load), and qualified
+    `defaultRefreshAction` (`claude/summarize-<kind>`).
+  - Kernel orchestrator parse phase asks the Provider for the
+    schema via `IProviderFrontmatterValidator` (composed by scan
+    via `buildProviderFrontmatterValidator`) instead of reading
+    from spec/. Flow: validate base → look up provider → validate
+    per-kind schema from Provider.
+  - `schema-validators.ts` catalog loses the 5 per-kind frontmatter
+    entries; only `frontmatter-base` remains kernel-known.
+    `plugin-loader`'s `stripFunctionsAndPluginId` now also strips
+    `schemaJson` (runtime-only) from each `kinds` entry before
+    AJV-validating the manifest.
+  - Coverage matrix: 28 → 23 schemas (the 5 per-kind frontmatter
+    schemas are now Provider-owned and ship with their own
+    conformance suite in Phase 5 / A.13).
+
+  556/556 cli + 32/32 testkit pass.
+
+  ### Phase 4 (commit e62695f) — Probabilistic infra
+
+  Five sub-phases, all breaking but allowed in minor pre-1.0:
+
+  - **4a (A.9)** — fine-grained Extractor cache via new
+    `scan_extractor_runs` table. Resolves gap where newly
+    registered Extractors silently skipped cached nodes; cache hit
+    logic now per-(node, extractor). Uninstalled Extractors cleaned
+    (rows + orphan links). Migration in-place.
+  - **4b (A.12)** — opt-in `outputSchema` for plugin custom
+    storage. Manifest gains `storage.schema` (Mode A) and
+    `storage.schemas` (Mode B) for AJV validation of
+    `ctx.store.write/.set` calls. Throws on shape violation;
+    default absent = permissive.
+  - **4c (A.8)** — enrichment layer + stale tracking. New
+    `node_enrichments` table persists per-(node, extractor)
+    partials separately from author's frontmatter (immutable).
+    Probabilistic enrichments track `body_hash_at_enrichment`; scan
+    flags `stale=1` on body change (NOT deleted, preserves LLM
+    cost). Helper `mergeNodeWithEnrichments` filters stale +
+    last-write-wins. New verbs `sm refresh <node>` and
+    `sm refresh --stale` (stubs awaiting Step 10).
+  - **4d (A.11)** — sixth plugin kind `hook`. Declarative
+    subscriber to a curated set of 8 lifecycle events (`scan.*`,
+    extractor/rule/action.completed,
+    job.spawning/completed/failed). Other events deliberately not
+    hookable. Manifest declares `triggers[]` (load-time validated)
+    and optional `filter`. Three new kernel events added to
+    catalog. Dual-mode (det dispatched in-process; prob deferred to
+    Step 10).
+  - **4e (A.7)** — `sm check --include-prob` opt-in flag (stub).
+    Default `sm check` unchanged: det only, CI-safe. With flag:
+    detects prob rules, emits stderr advisory; full dispatch awaits
+    Step 10. Combines with `--rules`, `-n`, `--no-plugins`.
+
+  591/591 cli + 32/32 testkit pass.
+
+  ### Phase 5 (commit 03b5a65) — Conformance + cleanup
+
+  **A.13** — Conformance fixture relocation:
+
+  - 3 cases moved (`git mv`): `basic-scan`, `orphan-detection`,
+    `rename-high` →
+    `src/extensions/providers/claude/conformance/cases/`. 11
+    fixture files (`minimal-claude/`, `orphan-{before,after}/`,
+    `rename-high-{before,after}/`) moved alongside.
+  - New `coverage.md` per-Provider listing the 5 frontmatter
+    schemas (skill, agent, command, hook, note) and their cases.
+  - New verb `sm conformance run [--scope spec|provider:<id>|all]`.
+    Discovery by convention at `<plugin-dir>/conformance/`. The
+    existing runner gains optional `fixturesRoot` (default
+    `<specRoot>/conformance/fixtures` for compat); tooling using
+    the public API of `@skill-map/cli/conformance` keeps working.
+    `--json` deferred — reporter shape not yet frozen.
+  - Spec keeps only the kernel-agnostic case (`kernel-empty-boot`)
+    and the universal preamble fixture. Coverage matrix downgrades
+    conservatively (rows that depended on `basic-scan` are now
+    partial or missing, with cross-link to the Provider's matrix).
+
+  ROADMAP cleanup:
+
+  - The three "Status: target state for v0.8.0 — spec catch-up
+    pending" banners on §Plugin system / §Frontmatter standard /
+    §Enrichment are removed; prose shifts from future to present
+    ("kinds from v0.7.0 are renamed" → "were renamed in spec
+    0.8.0"; Model B enrichment now describes the shipped
+    `node_enrichments` table with `body_hash_at_enrichment` rather
+    than "table or column set decided in PR").
+  - Decision-log entry for the working session rewritten to
+    reflect "shipped" rather than "pending".
+  - Last-updated header gains an "implementation" paragraph
+    listing the four prior phase commits.
+
+  593/593 cli + 32/32 testkit pass (+2 vs Phase 4 baseline).
+  spec:check green (40 files hashed — down from 53 because the
+  Claude-specific cases and fixtures left the spec's hash set).
+
+  ### Breaking changes for plugin authors (Part 2)
+
+  Manifest renames:
+
+  - `kind: 'adapter'` → `kind: 'provider'`
+  - `kind: 'detector'` → `kind: 'extractor'`
+  - `kind: 'renderer'` → `kind: 'formatter'`
+  - `kind: 'audit'` removed (migrate to `kind: 'rule'`).
+
+  Method signatures:
+
+  - Detector `detect(ctx) → Link[]` → Extractor `extract(ctx) →
+void` (output via `ctx.emitLink` / `ctx.enrichNode` /
+    `ctx.store`).
+  - Renderer `render(ctx) → string` → Formatter `format(ctx) →
+string`.
+
+  Manifest fields:
+
+  - Provider gains required `explorationDir`.
+  - Provider's flat `defaultRefreshAction` map replaced by per-kind
+    entries inside `kinds[<kind>].defaultRefreshAction` (must
+    follow qualified pattern `<plugin-id>/<ext-id>`).
+  - Provider's `emits` derives from `Object.keys(kinds)` (the
+    manifest field is gone).
+  - Provider's per-kind schemas declared via `kinds[<kind>].schema`
+    (path relative to provider dir).
+  - Renderer's `format` field renamed to `formatId` on the
+    Formatter manifest (TS clash resolution).
+  - New plugin kind `hook` with `triggers[]` + optional `filter`.
+  - Optional `outputSchema` (`storage.schema` / `storage.schemas`)
+    for Mode A / Mode B plugin custom storage.
+  - Optional `applicableKinds` filter on Extractor manifest.
+
+  Extension ids:
+
+  - All extension ids must be qualified
+    `<plugin-id>/<extension-id>` (built-ins classified into
+    `claude/*` and `core/*`).
+
+  DB schema:
+
+  - Two new tables added in-place to `001_initial.sql` (pre-1.0
+    consolidation, no production DBs to migrate):
+    `scan_extractor_runs` and `node_enrichments`.
+  - Column rename `nodes.adapter` → `nodes.provider` (and parallel
+    in `result.adapters` → `result.providers`).
+
+  ## Test stats
+
+  593/593 cli + 32/32 testkit pass (post-Phase 5).
+  Two new DB tables (`scan_extractor_runs`, `node_enrichments`)
+  added in-place to `001_initial.sql` (pre-1.0 consolidation, no
+  production DBs to migrate). The 5 per-kind frontmatter schemas
+  relocated from spec/ to the Claude Provider package.
+
+## [Unreleased]
+
+### Minor Changes
+
+- Conformance fixture relocation (Phase 5 / A.13). The conformance suite splits along ownership lines: spec-owned cases (kernel-agnostic, today only `kernel-empty-boot` plus the deferred `preamble-bitwise-match`) keep living under `spec/conformance/`; Provider-owned cases that exercise a Provider's own kind catalog move next to that Provider's manifest, under `<plugin-dir>/conformance/`. The reference impl's Claude Provider now hosts `basic-scan`, `rename-high`, and `orphan-detection` together with their `minimal-claude` / `orphan-{before,after}` / `rename-high-{before,after}` fixtures at `src/extensions/providers/claude/conformance/`. The split mirrors the spec 0.8.0 Phase 3 schema relocation: cases that depend on Claude-specific kinds (`skill`) belong with the Provider that declares the kind, not in the spec. New CLI verb `sm conformance run [--scope spec|provider:<id>|all]` (default `all`) drives both buckets in one invocation; `--scope spec` and `--scope provider:claude` narrow to a single suite for targeted runs and CI matrices. The reference runner gains an optional `fixturesRoot` parameter so cases can resolve their fixtures against the Provider's directory instead of the spec's. `spec/conformance/README.md` updated for the dual-ownership layout (spec-owned + Provider-owned tables, `sm conformance run` documented, runner pseudocode amended). `spec/conformance/coverage.md` retargeted: rows that used to credit `basic-scan` (now Provider-owned) downgrade to `kernel-empty-boot`-only or `🔴 missing` and point to the Provider's coverage file (`src/extensions/providers/claude/conformance/coverage.md`); the rename-heuristic non-schema row notes the Provider ownership. `spec/cli-contract.md` adds a §Conformance subsection under §Verb catalog and adds `sm conformance run` to the elapsed-time §Scope. `spec/architecture.md` opening sentence credits both buckets. Pre-1.0 minor per `versioning.md` § Pre-1.0; breaking only for tooling that hard-codes the previous case paths under `spec/conformance/cases/{basic-scan,rename-high,orphan-detection}.json` — no real ecosystem affected today (the reference impl's runner already migrates).
+
+- `sm check` gains `--include-prob` opt-in flag for probabilistic Rule dispatch (Phase 4 / A.7). Default unchanged: deterministic only, CI-safe — same status quo behaviour. With the flag, the verb loads the plugin runtime, finds Rules with `mode === 'probabilistic'` (filtered by `--rules` if set), and emits a stderr advisory naming the skipped rule ids. Full dispatch lands when the job subsystem ships at Step 10; until then the flag is a stub — prob rules never produce issues, never alter the exit code. New companion flag `--async` is reserved for the future encoding (returns job ids without waiting once jobs land); today it is a no-op the advisory mentions. Companion filters `-n <node.path>` and `--rules <ids>` (comma-separated qualified or short ids) added to `sm check` for granular reads — they restrict the persisted-issue list AND filter which prob rules surface in the advisory. Does NOT extend to `sm scan` or `sm list`. Documented in `cli-contract.md` §Browse and `plugin-author-guide.md` §Rules. Pre-1.0 minor per `versioning.md` § Pre-1.0; additive — no consumer breakage.
+
+- Sixth plugin kind `hook` added (Phase 4 / A.11). Reacts declaratively to a curated set of 8 lifecycle events — `scan.started`, `scan.completed`, `extractor.completed`, `rule.completed`, `action.completed`, `job.spawning`, `job.completed`, `job.failed`. Other events (per-node `scan.progress`, `model.delta`, `run.*`, `job.claimed`, `job.callback.received`) are deliberately NOT hookable: too verbose, internal to the runner, or covered elsewhere. Manifest declares `triggers[]` (validated against the hookable set; an unknown trigger yields `invalid-manifest` at load time with a directed reason naming the offending trigger and the full hookable list) and an optional `filter` object (top-level field equality match against the event payload; cross-field validation is best-effort in v0.x). Dual-mode: `deterministic` (default) runs `on(ctx)` in-process during the dispatch of the matching event, synchronously between emission and the next pipeline step; `probabilistic` is enqueued as a job (deferred to the job subsystem at Step 10 — probabilistic hooks load but skip dispatch with a stderr advisory until then). Hooks REACT to events; they cannot mutate the pipeline, block emission, or alter outputs. Errors are caught by the dispatcher (logged through `extension.error` with `kind: 'hook-error'`) and never block the main flow. Three new event types added to the catalog so the aggregated Extractor / Rule / Action triggers have a normative shape: `extractor.completed` (one per Extractor, after the full walk), `rule.completed` (one per Rule, after issue validation), `action.completed` (one per Action invocation, after report recording — lands alongside the job subsystem at Step 10). New schema `schemas/extensions/hook.schema.json` (`$id` `https://skill-map.dev/spec/v0/extensions/hook.schema.json`); `schemas/extensions/base.schema.json#/properties/kind/enum` extended with `hook`. Documented in `architecture.md` §Extension kinds (table extended from 5 to 6 rows), §Mode capability matrix (Hook dual-mode), §Hook · curated trigger set (new dedicated section); `plugin-author-guide.md` retitled "## The six extension kinds" with a new Hooks subsection (worked example: Slack notifier on `scan.completed`); `job-events.md` cross-links Hook from each of the 8 hookable triggers, adds the three new aggregated event entries, and updates the experimental tag scope. Coverage matrix grows from 23 to 24 rows. Pre-1.0 minor per `versioning.md` § Pre-1.0; additive — no consumer breakage. Existing extension kinds (`provider`, `extractor`, `rule`, `action`, `formatter`) are untouched.
+
+- Enrichment layer formalized (Phase 4 / A.8). New kernel table `node_enrichments(node_path, extractor_id, body_hash_at_enrichment, value_json, stale, enriched_at, is_probabilistic)` stores `ctx.enrichNode(partial)` outputs separately from the author's frontmatter (which remains IMMUTABLE from any Extractor — both deterministic and probabilistic). Per-Extractor attribution is preserved (one row per `(node, extractor)` pair). Probabilistic enrichments track `body_hash_at_enrichment`; when the scan loop sees a body change, those rows are flagged `stale = 1` (NOT deleted, so the LLM cost is preserved). Deterministic enrichments regenerate via the A.9 fine-grained cache and pisar via PRIMARY KEY conflict on the next re-extract — they are never stale-flagged. Read-side helper `mergeNodeWithEnrichments(node, enrichments)` produces a "merged view" by filtering stale rows, sorting by `enriched_at` ASC, and spread-merging onto the author frontmatter (last-write-wins per field). Stale visibility is opt-in (`includeStale: true`). Rules / `sm check` / `sm export` consume `node.frontmatter` directly (deterministic CI-safe baseline); enrichment consumption is opt-in by the caller. New verbs `sm refresh <node>` (granular) and `sm refresh --stale` (batch) re-run Extractors and upsert fresh enrichment rows — STUBBED until the job subsystem ships at Step 10: deterministic Extractors persist for real, probabilistic Extractors emit a stderr advisory and skip without touching their stale rows. Migration `001_initial.sql` updated in place per the pre-1.0 consolidation precedent (no released DBs to forward-migrate). Documented in `db-schema.md` §`node_enrichments`, `architecture.md` §Extractor · enrichment layer, `cli-contract.md` §Scan, and `plugin-author-guide.md` §Extractors. Pre-1.0 minor per `versioning.md` § Pre-1.0; additive — no consumer breakage.
+
+- Plugin manifest gains optional `storage.schemas` map (Mode B / dedicated) and `storage.schema` (Mode A / KV) for opt-in JSON Schema validation of custom storage writes. AJV-validates `ctx.store.write(table, row)` and `ctx.store.set(key, value)` before persisting; throws on shape violation. Default absent = permissive (status quo). `emitLink` and `enrichNode` keep their universal kernel validation regardless. A schema file missing on disk or failing AJV compile at load time surfaces as `load-error` with a directed reason naming the plugin, the table (Mode B), and the schema path. Pre-1.0 minor per `versioning.md` § Pre-1.0; additive — no consumer breakage. Documented in `plugin-author-guide.md` §Storage and referenced from `architecture.md` §Extractor · output callbacks.
+
+- New kernel table `scan_extractor_runs(node_path, extractor_id, body_hash_at_run, ran_at)` — fine-grained Extractor cache breadcrumbs (Phase 4 / A.9). Replaces the previous "trust the node-level body+frontmatter hash" model that silently bypassed any Extractor newly registered between scans. Cache decision per `(node, extractor)` pair: a new Extractor registered between scans yields a partial cache hit (only the newcomer runs over the cached node); an uninstalled Extractor's rows disappear via replace-all, and links whose sources are exclusively that Extractor disappear with them. Documented in `db-schema.md` §`scan_extractor_runs`. Migration `001_initial.sql` updated in place per the pre-1.0 consolidation precedent (no released DBs to forward-migrate). Pre-1.0 minor per `versioning.md` § Pre-1.0; additive — no consumer breakage.
+
+- Per-kind frontmatter schemas relocate from spec to the Provider that declares them. Spec keeps only `frontmatter/base.schema.json` (universal — fields common to every node across every Provider). The Claude Provider gains a `kinds` map declaring its catalog (`skill` / `agent` / `command` / `hook` / `note`) with per-kind `schema` + `defaultRefreshAction`. The pre-0.8 flat fields `emits: string[]` and `defaultRefreshAction: { <kind>: actionId }` collapse into the new map: `emits` is removed (derived from `Object.keys(kinds)`); each `defaultRefreshAction[<kind>]` value moves into `kinds[<kind>].defaultRefreshAction`. The kernel parse phase asks the Provider for the schema instead of reading from `spec/schemas/frontmatter/<kind>.schema.json`. Schema files moved: `spec/schemas/frontmatter/{skill,agent,command,hook,note}.schema.json` → `src/extensions/providers/claude/schemas/{skill,agent,command,hook,note}.schema.json`; their `$id` updates from `https://skill-map.dev/spec/v0/frontmatter/<kind>.schema.json` to `https://skill-map.dev/providers/claude/v1/frontmatter/<kind>.schema.json`; their `$ref: 'base.schema.json'` updates to `$ref: 'https://skill-map.dev/spec/v0/frontmatter/base.schema.json'` (absolute `$ref`-by-`$id` so AJV resolves cross-package against the spec base registered into the same instance). `spec/schemas/extensions/provider.schema.json` updated: `kinds` is required, `emits` and the old shape of `defaultRefreshAction` removed. `spec/conformance/coverage.md` matrix shrinks from 28 to 23 rows (the five per-kind frontmatter rows belong to the Provider's own conformance suite, planned in Phase 5). `spec/index.json` no longer lists the per-kind schemas. `architecture.md` §Provider section retitled `Provider · kinds catalog and explorationDir`; `plugin-author-guide.md` Provider example updated; `README.md` directory tree updated to reflect spec/frontmatter/ now holds only `base.schema.json`. Pre-1.0 minor per `versioning.md` § Pre-1.0; breaking for any plugin or test referencing `spec/schemas/frontmatter/<kind>.schema.json` paths or `$id`s, the old `provider.emits` field, or the flat `provider.defaultRefreshAction` map — no real ecosystem affected today.
+
+- Plugin kind `renderer` renamed to `formatter`. Method renamed `render(ctx) → format(ctx)`. Manifest field `format` (the identifier consumed by `--format`) renamed to `formatId` to avoid clashing with the new method name. Same contract otherwise: graph → string, deterministic-only. Aligns with industry tooling (ESLint formatter, Mocha reporter, Pandoc writer). `schemas/extensions/renderer.schema.json` renamed to `formatter.schema.json`; the `kind` const flips from `"renderer"` to `"formatter"`; `base.schema.json#/properties/kind/enum` updated. `architecture.md`, `cli-contract.md`, `plugin-author-guide.md`, `README.md` updated to match (Extension kinds table, Execution modes table, testkit helper names, worked CSV example). `conformance/coverage.md` row 28 retargeted at the new schema filename. Pre-1.0 minor per `versioning.md` § Pre-1.0; breaking for any plugin or test referencing `kind: "renderer"`, `IRenderer`, `r.format`, or `render(ctx)` — no real ecosystem affected today.
+
+- Plugin kind `'detector'` renamed to `'extractor'`. Method signature
+  changes from `detect(ctx) → Link[]` to `extract(ctx) → void` — output
+  flows through three new ctx callbacks: `emitLink(link)` (kernel `links`
+  table), `enrichNode(partial)` (kernel enrichment layer, persisted into
+  `node_enrichments` per A.8), and the existing `ctx.store` (plugin's
+  own table). The Extractor absorbs what would have been a separate
+  `Enricher` kind via `enrichNode`. Built-ins migrated:
+  `claude/frontmatter`, `claude/slash`, `claude/at-directive`,
+  `core/external-url-counter` — all use `emitLink` to maintain
+  functional parity with their Detector ancestors. Schema files
+  renamed: `schemas/extensions/detector.schema.json` →
+  `schemas/extensions/extractor.schema.json`. Persisted DB rows are
+  unaffected (link `sources` carry extractor ids verbatim — the field
+  was always free-form). Pre-1.0 minor per `versioning.md` § Pre-1.0;
+  breaking for any plugin or test referencing `'detector'` as the
+  kind, `IDetector`, or the old `Link[]` return signature — no real
+  ecosystem affected today.
+
+- Plugin kind `'audit'` removed. The single built-in `'validate-all'`
+  migrated to a Rule (qualified id `'core/validate-all'`, method
+  `evaluate(ctx) → Issue[]`). The kind had dual personality (composer +
+  standalone reporter); the standalone reporter case is naturally a Rule,
+  and the composer case is deferred to post-1.0 if a real use case
+  appears. CLI verbs `'sm audit run'` and `'sm audit show'` removed;
+  users invoke the rule via `sm check --rules core/validate-all`.
+  `state_executions.kind` enum narrowed to `['action']` (audit was the
+  only other value); the column is preserved as a forward-compatibility
+  lever. Schema files removed: `schemas/extensions/audit.schema.json`.
+  Coverage matrix shrinks from 29 to 28 rows. Pre-1.0 minor per
+  `versioning.md` § Pre-1.0; breaking for any plugin or test referencing
+  the audit kind, `IAudit`, `TAuditReport`, or `sm audit` verbs — no
+  real ecosystem affected today.
+
+- Plugin kind `'adapter'` renamed to `'provider'`. Manifest gains required
+  field `'explorationDir'` (filesystem directory where the Provider's
+  content lives, e.g. `'~/.claude'` for the Claude Provider). Built-in
+  `claudeAdapter` renamed to `claudeProvider`. The hexagonal-architecture
+  `'adapter'` (`RunnerPort.adapter`, `StoragePort.adapter`,
+  `FilesystemPort.adapter`, `PluginLoaderPort.adapter`) is unchanged —
+  distinct concept, distinct namespace.
+  Persisted schema fields renamed: `node.adapter` → `node.provider`,
+  `scan-result.adapters` → `scan-result.providers` (pre-1.0 minor — no
+  production DBs to migrate; `001_initial.sql` was edited in place per
+  the consolidation precedent already established for pre-1.0).
+  Project config field renamed: `project-config.adapters` →
+  `project-config.providers`. Schema files renamed:
+  `schemas/extensions/adapter.schema.json` →
+  `schemas/extensions/provider.schema.json`. Pre-1.0 minor per
+  `versioning.md` § Pre-1.0; breaking for any plugin or test referencing
+  `'adapter'` as the kind, `IAdapter`, or any persisted/config schema
+  field renamed above — no real ecosystem affected today.
+
+## 0.7.1
+
+### Patch Changes
+
+- 0463a0f: Step 9.4 — plugin author guide + reference plugin + diagnostics polish.
+  **Step 9 fully closed** with this changeset.
+
+  ### Spec — plugin author guide (additive prose)
+
+  New document at `spec/plugin-author-guide.md` covering:
+
+  - Discovery roots (`<project>/.skill-map/plugins/`,
+    `~/.skill-map/plugins/`, `--plugin-dir <path>`).
+  - Manifest fields with the normative schema reference.
+  - `specCompat` strategy — narrow ranges pre-`v1.0.0`, `^1.0.0`
+    recommendation post-`v1.0.0`.
+  - The six extension kinds with one minimal worked example each
+    (detector, rule, renderer in full; adapter / audit / action flagged
+    for later expansion alongside Step 10).
+  - Storage choice (KV vs Dedicated) cross-linking `plugin-kv-api.md`
+    and the Step 9.2 triple-protection rule.
+  - Execution modes (deterministic / probabilistic) cross-linking
+    `architecture.md`.
+  - Testkit usage with `runDetectorOnFixture`, `runRuleOnGraph`,
+    `runRendererOnGraph`, `makeFakeRunner`.
+  - The five plugin statuses (`loaded` / `disabled` / `incompatible-spec`
+    / `invalid-manifest` / `load-error`) and how to read them.
+  - Stability section (document is stable; widening additions are minor
+    bumps; breaking edits are major).
+
+  `spec/package.json#files` updated to ship the new doc; `spec/index.json`
+  regenerated (57 → 58 hashed files). `coverage.md` unchanged because the
+  guide is prose, not a schema.
+
+  ### Reference plugin — `examples/hello-world/`
+
+  Smallest viable plugin in the principal repo (Arquitecto's pick: in
+  the main repo, not separate). One detector (`hello-world-greet`)
+  emitting `references` links per `@greet:<name>` token in node bodies.
+  Includes:
+
+  - `plugin.json` declaring one extension and pinning `specCompat: ^1.0.0`.
+  - `extensions/greet-detector.mjs` — runtime instance with both
+    manifest fields and the `detect` method.
+  - `README.md` — what it does, file layout, three-step "try it
+    locally" recipe, what's intentionally missing (storage,
+    multi-extension, probabilistic mode), pointers for production-grade
+    patterns.
+  - `test/greet-detector.test.mjs` — four-assertion test using
+    `@skill-map/testkit`, runnable via `node --test` with no build step.
+
+  Verified end-to-end: the example plugin loads cleanly under
+  `sm plugins list`, scans contribute its links to the persisted graph,
+  and the testkit-based test passes. The example is **not** registered
+  as a workspace — it's intentionally standalone so users can copy it.
+
+  ### CLI — diagnostics polish on `PluginLoader.reason`
+
+  Each failure-mode reason string now carries an actionable hint:
+
+  - `invalid-manifest` (JSON parse): names the manifest path, suggests
+    validating the JSON.
+  - `invalid-manifest` (AJV): names the manifest path AND points at
+    `spec/schemas/plugins-registry.schema.json#/$defs/PluginManifest`.
+  - `invalid-manifest` (specCompat not a valid range): suggests a range
+    shape (`"^1.0.0"`).
+  - `incompatible-spec`: suggests two remediations (update the plugin's
+    `specCompat`, or pin sm to a compatible spec version).
+  - `load-error` (extension file not found): includes the absolute
+    resolved path, pointer to `plugin.json#/extensions`.
+  - `load-error` (default export missing kind): lists the valid kinds.
+  - `load-error` (unknown kind): lists the valid kinds.
+  - `load-error` (extension manifest schema fails): names the
+    per-kind schema (`spec/schemas/extensions/<kind>.schema.json`).
+
+  6 new tests under `test/plugin-loader.test.ts` (`Step 9.4 diagnostics
+polish` describe block) assert each hint shape is present without
+  pinning the full text. Test count 437 → **443 cli + 30 testkit = 473**.
+
+  ### Step 9 closed
+
+  The four sub-steps — 9.1 (plugin runtime wiring), 9.2 (plugin
+  migrations + triple protection), 9.3 (`@skill-map/testkit` workspace),
+  9.4 (author guide + reference plugin + diagnostics polish) — together
+  turn `skill-map` plugins from "discovered but inert" into a
+  first-class authoring surface with documentation, tests, and a
+  working reference. Next step: **Step 10 — job subsystem + first
+  probabilistic extension** (wave 2 begins).
+
 ## 0.7.0
 
 ### Minor Changes
@@ -165,34 +916,34 @@ job prune` + retention enforcement.
 
   Two pieces:
 
-  1. **New built-in rule `link-conflict`** (`src/extensions/rules/link-conflict/`).
-     Surfaces detector disagreement. Groups links by `(source, target)` and
-     emits one `warn` Issue per pair where the set of distinct `kind` values
-     has size ≥ 2. Agreement (single kind across multiple detectors) is
-     silent — by design, to avoid massive noise on real graphs.
-     Issue payload (`data`) carries `{ source, target, variants }` where
-     each `variant` is `{ kind, sources: detectorId[], confidence }`. Variant
-     sources are deduped + sorted; confidence is the highest across rows
-     of the same kind (`high` > `medium` > `low`).
-
-     This is the kernel piece of Decision #90 read-time "consumers that
-     need uniqueness aggregate at read time" — the rule is one such
-     consumer, on the alarming side. Storage stays untouched (one row
-     per detector, no merge, no dedup). Severity is `warn`, not `error`:
-     the rule cannot pick which kind is correct, so per `cli-contract.md`
-     §Exit codes the verb stays exit 0.
-
-  2. **`sm show` pretty link aggregation** (`src/cli/commands/show.ts`).
-     The human renderer now groups `linksOut` / `linksIn` by `(endpoint,
+  1.  **New built-in rule `link-conflict`** (`src/extensions/rules/link-conflict/`).
+      Surfaces detector disagreement. Groups links by `(source, target)` and
+      emits one `warn` Issue per pair where the set of distinct `kind` values
+      has size ≥ 2. Agreement (single kind across multiple detectors) is
+      silent — by design, to avoid massive noise on real graphs.
+      Issue payload (`data`) carries `{ source, target, variants }` where
+      each `variant` is `{ kind, sources: detectorId[], confidence }`. Variant
+      sources are deduped + sorted; confidence is the highest across rows
+      of the same kind (`high` > `medium` > `low`).
+
+      This is the kernel piece of Decision #90 read-time "consumers that
+      need uniqueness aggregate at read time" — the rule is one such
+      consumer, on the alarming side. Storage stays untouched (one row
+      per detector, no merge, no dedup). Severity is `warn`, not `error`:
+      the rule cannot pick which kind is correct, so per `cli-contract.md`
+      §Exit codes the verb stays exit 0.
+
+  2.  **`sm show` pretty link aggregation** (`src/cli/commands/show.ts`).
+      The human renderer now groups `linksOut` / `linksIn` by `(endpoint,
 kind, normalizedTrigger)` and prints one row per group with the
-     union of detector ids in a `sources:` field. The section header
-     reports both the raw row count and the unique-after-grouping count
-     (`Links out (12, 9 unique)`). When N > 1 detector emits the same
-     logical link, the row also gets a `(×N)` suffix.
+      union of detector ids in a `sources:` field. The section header
+      reports both the raw row count and the unique-after-grouping count
+      (`Links out (12, 9 unique)`). When N > 1 detector emits the same
+      logical link, the row also gets a `(×N)` suffix.
 
-     `--json` output is byte-identical to before — raw rows, no merge.
-     Storage is byte-identical to before. The grouping is purely a
-     read-time presentation choice for human eyes.
+                 `--json` output is byte-identical to before — raw rows, no merge.
+                 Storage is byte-identical to before. The grouping is purely a
+                 read-time presentation choice for human eyes.
 
   **Spec changes (patch)**:
 
@@ -874,9 +1625,20 @@ Tag convention: `spec-vX.Y.Z` (distinct from CLI tags `cli-vX.Y.Z`).
 
 Initial public spec bootstrap (Step 0a phases 1–3).
 
+### Added
+
+- `cli-contract.md` — new normative section **§Dry-run** between §Exit codes and §Verb catalog. Codifies the contract every verb that exposes `-n` / `--dry-run` MUST honour: no observable side effects (DB / FS / config / network / spawns), no auto-provisioning of scope directories, output mirrors live mode with explicit "would …" framing, exit codes mirror live mode, dry-run MUST short-circuit `--yes` / `--force` confirmation prompts. Per-verb opt-in: the flag is not global and verbs that don't declare it MUST reject it as an unknown option (exit `2`). Verb catalog rows for `sm init`, `sm db reset` (default + `--state` + `--hard`), and `sm db restore` amended to declare and describe their `--dry-run` previews. Pre-1.0 minor (additive normative).
+- `plugin-author-guide.md` — consolidated section on the three-tier frontmatter validation model (default permissive `additionalProperties: true` + always-active `unknown-field` rule emitting `warn` + `scan.strict` / `--strict` promoting warnings to `error`). Includes a worked example through all three tiers and an explicit note on why no "schema-extender" plugin kind exists (the path for custom validation is a deterministic Rule, not a new plugin kind). Editorial only. No normative change — the model already exists implicitly via `base.schema.json`'s permissive `additionalProperties` and `project-config.schema.json#/properties/scan/properties/strict`. Patch.
+- `PluginManifest` gains optional `granularity` field (enum `bundle` / `extension`, default `bundle`). Built-in `claude` bundle is `granularity: bundle` (toggle the whole bundle); built-in `core` bundle is `granularity: extension` (each built-in toggle-able individually under `core/<ext-id>`). `sm plugins enable / disable` validates the supplied id against the bundle's declared granularity (bundle granularity rejects qualified ids; extension granularity rejects bare bundle ids) and persists in `config_plugins` with the appropriate key. `--all` operates only on bundle-granularity plugin ids; the "disable every kernel built-in" intent is served by `--no-built-ins`. `plugin-author-guide.md` adds a §Granularity — bundle vs extension section with the per-verb behaviour table and the built-in mapping; `architecture.md` §`PluginLoaderPort` documents the runtime split (loader's pre-import resolveEnabled is coarse / bundle-level; the CLI's runtime composer drops per-extension disabled extensions before they reach the orchestrator). Closes the spec-vs-impl drift between the spec promise that "no extension is privileged, removable" and the prior implementation where built-ins were always-on. Pre-1.0 minor per `versioning.md` § Pre-1.0; additive on the manifest schema, breaking only for users who relied on the `claude` adapter loading without an explicit `config_plugins` row (none today, since the row had no effect on built-ins before).
+- Detector manifest gains optional `applicableKinds` filter (array, `minItems: 1`, kebab-case strings, `uniqueItems: true`). When declared, the kernel skips invocation for nodes whose `kind` is not in the list — fail-fast, before the detect context is built, so a probabilistic detector wastes zero LLM cost (and a deterministic detector zero CPU) on inapplicable nodes. Absent = applies to every kind (the default); no wildcard syntax. Empty array `[]` is rejected at load time. Unknown kinds (no installed Adapter declares them via `defaultRefreshAction`) load OK with a `sm plugins doctor` warning — the Provider may arrive later — and the doctor exit code is NOT promoted by the warning. `plugin-author-guide.md` adds a §Detector `applicableKinds` — narrow the pipeline section under Granularity with the per-shape behaviour table and a worked example; `architecture.md` adds a §Detector · `applicableKinds` filter subsection above trigger normalization; `schemas/extensions/detector.schema.json` declares the new property. Pre-1.0 minor per `versioning.md` § Pre-1.0; additive, non-breaking for existing detectors (they all behave as if `applicableKinds: undefined`).
+
 ### Changed
 
 - `cli-contract.md`: `--all` is no longer a global flag. It is valid only on verbs that explicitly document fan-out semantics: `sm job submit`, `sm job run`, `sm job cancel`, and `sm plugins enable/disable`.
+- `cli-contract.md`: `sm scan compare-with <dump> [roots...]` is now a sub-verb instead of a `--compare-with <path>` flag on `sm scan`. Read-only delta report against a saved `ScanResult` JSON dump. Same exit codes (`0` empty delta / `1` drift / `2` operational error). Old flag form removed. Pre-1.0 breaking change shipped as minor per `versioning.md` § Pre-1.0.
+- Plugin discovery — directory name MUST equal manifest id (else `invalid-manifest`); cross-root id collisions yield new `id-collision` status (sixth status, both collided plugins blocked, no precedence). `plugin-author-guide.md` Diagnostics table grows from five to six rows; `architecture.md` §`PluginLoaderPort` documents the two enforcement points; `schemas/plugins-registry.schema.json#/$defs/DiscoveredPlugin/status` adds `id-collision` to the enum. Pre-1.0 minor per `versioning.md` § Pre-1.0; breaking for any plugin whose directory name does not match its manifest id, but no real ecosystem affected today.
+- Plugin extensions are now identified by qualified ids `<plugin-id>/<extension-id>`. Built-in extensions adopt the `core/` namespace; the Claude adapter and its kind-aware detectors (frontmatter, slash, at-directive) live under `claude/`. The loader injects `pluginId` from `plugin.json#/id` into every extension at load time; an explicit `pluginId` field on an extension that disagrees with the manifest id is `invalid-manifest`. `architecture.md` §`PluginLoaderPort` documents the qualifier composition; `plugin-author-guide.md` adds a §Qualified extension ids section with the built-in mapping table; `schemas/extensions/base.schema.json` clarifies that extension `id` stays unqualified (single kebab-case segment, no `/`); `schemas/extensions/adapter.schema.json#/properties/defaultRefreshAction` now requires qualified action ids (pattern `^<plugin-id>/<action-id>$`). Pre-1.0 minor per `versioning.md` § Pre-1.0; breaking for any plugin or test that referenced an extension by short id.
+- `cli-contract.md`: exit-code `2` "Operational error" row clarified to mention runtime / environment mismatches (wrong Node version, missing native dependency) explicitly. The "unhandled exception" catch-all already covered the case; this just removes ambiguity for future implementers.
 - `job-events.md`: the common `runId` envelope now explicitly documents the optional mode segment (`r-<mode>-YYYYMMDD-HHMMSS-XXXX`) used by external Skill claims, scan runs, and standalone issue recomputations.
 - `versioning.md` and related prose: replace ambiguous milestone terminology with explicit versioned release language.