@skill-map/spec 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Spec changelog
 
+## 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 +254,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.
-
-     `--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.
+      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.
 
   **Spec changes (patch)**:
 

package/index.json

@@ -190,11 +190,11 @@
       }
     ]
   },
-  "specPackageVersion": "0.7.0",
+  "specPackageVersion": "0.7.1",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "a6a7a44f05e2344c2a5eb3a3369bc615b86fe0d1825c72309a93bf8fa090f1ce",
+      "CHANGELOG.md": "11a026e881126ac96703de9e3e4e3ddd9ebf7b776ba4d2197ed8c68dce5e6d98",
       "README.md": "8bd57e02d9a9d3f0a4efd18c0f0bd1f4bbe13eb206add0317659e48eab435e7e",
       "architecture.md": "0ebaacef9e57206bc0dde27ff44a02e0a7def9ae9ceba2f27053b31ff708708b",
       "cli-contract.md": "12ca455496d48a61fc83888808433acf1470f09c261cf1161375b01f0f3f85c4",

package/package.json

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