@skill-map/spec 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Spec changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- 334c51a: Document `--all` as targeted fan-out, not a global flag, in `spec/cli-contract.md`.
+
+  `--all` is valid only on verbs whose contract explicitly lists it:
+
+  - `sm plugins enable <id> | --all` and `sm plugins disable <id> | --all`.
+  - `sm job cancel <job.id> | --all` (cancels every `queued` and `running` job).
+  - `sm job submit <action> --all` and `sm job run --all`.
+
+  Unsupported `--all` usage is an operational error (exit `2`), the same as any other unknown or invalid flag.
+
+  Classification: minor — targeted fan-out semantics are additive for the listed verbs, while avoiding a global flag contract.
+
+- 3e89d8f: Audit-driven alignment pass. Multiple normative additions and a casing cleanup:
+
+  - **Extension schemas**: add `spec/schemas/extensions/{base,adapter,detector,rule,action,audit,renderer}.schema.json` (7 new files). `architecture.md` §Extension kinds now points to them and mandates manifest validation at load time. Unblocks the "contract tests for the 6 kinds" invariant.
+  - **Adapter `defaultRefreshAction`**: normatively required on every `Adapter` extension. Maps node `kind` → `actionId` and drives the UI's `🧠 prob` button. Previously mentioned only in ROADMAP (Decision #45); now part of the schema.
+  - **Triple protection for mode B**: `db-schema.md` now specifies the exact order — parse → DDL validation → prefix injection → scoped connection. Validation runs **before** the rewrite so kernel-table references are caught under their authored names.
+  - **Automatic rename heuristic**: new `db-schema.md` §Rename detection. On scan, `body_hash` match → high-confidence auto-rename with `state_*` FK migration; `frontmatter_hash` match → medium-confidence, same migration + `auto-rename-medium` issue; no match → orphan with issue. Replaces the prior "scan emits orphans, user runs `sm orphans reconcile` manually" flow.
+  - **Skill agent envelope**: `job-events.md` now mandates a synthetic `r-ext-<ts>-<hex>` run envelope (`run.started mode=external` → `job.claimed` → `job.callback.received` → `job.completed|failed` → `run.summary`) around jobs claimed by a Skill agent without entering `sm job run`. Keeps the WebSocket broadcaster contract ("every job event inside a run envelope") intact across both runner paths.
+  - **"Skill runner" → "Skill agent"**: `architecture.md` and `job-lifecycle.md` clarify that the Skill path is a peer driving adapter (alongside CLI and Server), NOT a `RunnerPort` implementation. Only `ClaudeCliRunner` and its test fake implement the port. Name was misleading; structure unchanged.
+  - **Casing**: `db-schema.md` `auto_migrate` → `autoMigrate`; `README.md` prose mention `spec-compat` → `specCompat`. Brings prose into sync with the camelCase rule already enforced by the schemas.
+  - **Coverage matrix**: new `spec/conformance/coverage.md` tracks each schema (and each non-schema normative artifact) against its conformance case. 28 schemas + 11 artifact invariants catalogued; 19 schemas and 10 artifacts flagged as missing, each with a step-blocker note. Release gate: v1.0.0 requires every row 🟢 or explicitly deferred.
+
+  Classification: minor per §Pre-1.0 (`0.Y.Z`). The new required field `defaultRefreshAction` on the Adapter kind is technically breaking — no conforming Adapter ships in the reference impl yet, so the impact is zero. Post-1.0 the same change would be major.
+
+### Patch Changes
+
+- 93ffe34: Editorial pass: remove "MVP" terminology from four prose documents.
+
+  The project shipped two competing readings of "MVP" — sometimes "`v0.5.0`", sometimes "the whole product through `v1.0`". That drift produced contradictions in companion docs (e.g. the summarizer pattern: was `v0.8.0` or `v0.5.0` supposed to ship them?). To close the ambiguity once, `ROADMAP.md` and `AGENTS.md` standardised on explicit versioned releases and `post-v1.0` in the same audit window. This change brings the four spec prose touches that still said "MVP" into the same vocabulary.
+
+  - **`cli-contract.md` §Jobs**: `sm job run --all` description `(MVP: sequential)` → `(sequential through v1.0; in-runner parallelism deferred)`.
+  - **`job-events.md` §Event catalog**: `(post-MVP)` parallel-run note → `(deferred to post-v1.0)`.
+  - **`job-lifecycle.md` §Concurrency**: `MVP (v0.x): one job at a time.` → `Through v1.0 (spec v0.x): one job at a time.`
+  - **`plugin-kv-api.md` §Backup and retention**: `sm plugins forget <id> (post-MVP)` → `sm plugins forget <id> (deferred to post-v1.0)`.
+
+  Classification: patch. Editorial only — no schema, exit code, verb signature, or MUST/SHOULD statement changes meaning. All four replacements preserve the technical content; only the label changes from project-scoped ("MVP") to version-scoped (`v1.0`), which is the convention the rest of the spec already uses. Integrity block regenerated.
+
 ## 0.3.0
 
 ### Minor Changes
@@ -345,6 +387,12 @@ Tag convention: `spec-vX.Y.Z` (distinct from CLI tags `cli-vX.Y.Z`).
 
 Initial public spec bootstrap (Step 0a phases 1–3).
 
+### 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`.
+- `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.
+
 ### Added
 
 - Foundation:
@@ -370,7 +418,7 @@ Initial public spec bootstrap (Step 0a phases 1–3).
 
 - JSON Schema dialect: draft 2020-12.
 - Casing: camelCase for all JSON keys (domain, configs, manifests, reports); kebab-case for filenames.
-- `$id` scheme: `https://skill-map.dev/spec/v<major>/<path>.schema.json`. `v0` throughout pre-1.0; bumps to `v1` at the first stable cut.
+- `$id` scheme: `https://skill-map.dev/spec/v<major>/<path>.schema.json`. `v0` throughout pre-1.0; bumps to `v1` at the first stable release.
 - Identity: `node.path` (relative to scope root) is the canonical node identifier in v0. Future UUID-based `node.id` lands with write-back.
 - Required frontmatter: `name`, `description`, `metadata`, `metadata.version`.
 - Frontmatter: `additionalProperties: true` (rules handle unknown fields). Summaries: `additionalProperties: false` (strict).

package/cli-contract.md

@@ -25,7 +25,6 @@ These flags apply to every verb unless marked otherwise.
 | `--no-color` | boolean | Disable ANSI color codes. Implementations MUST also auto-disable color when stdout is not a TTY. |
 | `-h` / `--help` | boolean | Print verb-specific or top-level help, exit 0. |
 | `--db <path>` | string | Override the database file location (escape hatch; primarily for debugging). |
-| `--all` | boolean | Universal fan-out. Any verb that accepts a target identifier (node path, job id, plugin id, etc.) MUST accept `--all` as "apply to every eligible target matching the verb's preconditions". Mutually exclusive with a positional target or `-n <path>` on the same invocation. Verbs that inherently target everything (`sm scan` without `-n`, `sm list`, `sm check`, `sm doctor`) accept the flag for script-composition uniformity but treat it as a no-op. Verbs where fan-out is nonsensical (`sm record`, `sm init`, `sm version`, `sm help`, `sm config get/set/reset/show`, `sm db *`, `sm serve`) MUST reject `--all` with exit `2`. |
 
 Env-var equivalents are normative:
 
@@ -40,6 +39,22 @@ CLI flag wins over env var. Env var wins over config file.
 
 ---
 
+## Targeted fan-out flags
+
+`--all` is not global. It is only valid on verbs whose contract explicitly lists it:
+
+- `sm job submit <action> --all`
+- `sm job run --all`
+- `sm job cancel --all`
+- `sm plugins enable --all`
+- `sm plugins disable --all`
+
+For those verbs, `--all` means "apply to every eligible target matching the verb's preconditions" and is mutually exclusive with a positional target or `-n <path>` on the same invocation.
+
+Implementations MUST NOT silently accept `--all` on unrelated verbs. Unsupported `--all` usage is an operational error (exit `2`), the same as any other unknown or invalid flag.
+
+---
+
 ## Exit codes
 
 All verbs use this shared table. Additional codes MAY be defined per-verb (documented under the verb).

package/conformance/coverage.md

@@ -2,7 +2,7 @@
 
 Authoritative map of JSON Schemas in `spec/schemas/` to the conformance cases that exercise them. Every schema MUST have at least one case before spec v1.0.0 ships — missing case → missing release (AGENTS.md §Rules for AI agents editing spec/).
 
-This file is hand-maintained. A CI check at spec cut-time compares the schema inventory against this table and fails if any schema lacks a case.
+This file is hand-maintained. A CI check before spec release compares the schema inventory against this table and fails if any schema lacks a case.
 
 ## Coverage matrix
 
@@ -62,5 +62,5 @@ These have their own conformance cases even though they are not JSON Schemas.
 ## Release gates
 
 - **spec v0.x**: partial coverage acceptable. Every case added as the reference impl lands the verb that makes it runnable.
-- **spec v1.0.0 cut**: all rows above MUST be 🟢 covered or explicitly 🟠 deferred to v1.1 with a linked issue.
+- **spec v1.0.0 release**: all rows above MUST be 🟢 covered or explicitly 🟠 deferred to v1.1 with a linked issue.
 - **CI check**: [`scripts/check-coverage.mjs`](../../scripts/check-coverage.mjs) compares `spec/schemas/**/*.schema.json` against the matrix above on every PR. A schema without a row here, or a row pointing at a missing schema, fails CI (exit 1 with a `::error::` annotation). Wired into `ci.yml` §validate and into `npm run spec:check`.

package/index.json

@@ -156,18 +156,18 @@
       }
     ]
   },
-  "specPackageVersion": "0.3.0",
+  "specPackageVersion": "0.4.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "a9777384c89405fd2ccf16758f8973fd3f55ce5a78ea76f6f859ff86d5d37f1f",
+      "CHANGELOG.md": "38364d4ca30475e3e1eb35019037532547c1e5bdc245ecfcc60eb5e1570985d0",
       "README.md": "a233e6b5ab1c41c13cb4790485f0514f7c111880eb70165e77e1253999069120",
       "architecture.md": "be4085b7bbb3476f8a9d6df940b5794839b936ac5dd1921203a91558b008c7bc",
-      "cli-contract.md": "4368f2cdf6884f792607a369b43ed6a8a9674cb2d2f790eb086fc961eb29689c",
+      "cli-contract.md": "7657b6e60089afdd3644e7e38d96593158349259ab105d76199ce5eb65993cae",
       "conformance/README.md": "4e41ff823b55ce3c274a033c5152ae0b2759fc714a714d7815593d8be84c8a4c",
       "conformance/cases/basic-scan.json": "24623da0cad8c8c54b3ff9b09820ea1276fe8b8f0fc680bf6e8abeb4edb8e424",
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
-      "conformance/coverage.md": "f46b5b20649c169c4f15c721a2a9cd7f7be11566a64f8fbeb8a6b171eb420762",
+      "conformance/coverage.md": "405a7ee093d6e54993ec5d9e061489f8b924829c7688fe56951bebf87abb2fae",
       "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",
@@ -176,9 +176,9 @@
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
       "db-schema.md": "17de515904b8869ea0fe8d3cd608423376396bed6281b784ee1670f184d29f2c",
       "interfaces/security-scanner.md": "468f8ee412594b14b389c36cefa9ca75a5dec652adbf03ab8bbc7f57ca980253",
-      "job-events.md": "2641ef72863a24f590e2ffdb94a352e5ed5ab7123a9f04f42696f96da793bb91",
+      "job-events.md": "090733b47dc0bbe62d790a87a29f2a13fe1dbcb9d6a89ea16e1ecff2293e3972",
       "job-lifecycle.md": "793d34de0793596be17d2ed9042eeb4d532e805bceee25d9f9da0c3cb0b34b1c",
-      "plugin-kv-api.md": "8079d8b4304ba3d112b5daa40c49e38e8186949b5d4166dadf5a225087b88ce7",
+      "plugin-kv-api.md": "fe0c02dcc7eaee0ad711f16247df076fa62348710ee1088e1234764dd3cec82e",
       "prompt-preamble.md": "9b7478ddce0a77043983f35932677d702319348048fe5d6b1c60257bd1c9f605",
       "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
@@ -209,7 +209,7 @@
       "schemas/summaries/hook.schema.json": "36f876f3b1a60d45be97a0848c79fd18744b434dfdcefc366f033b253d56268c",
       "schemas/summaries/note.schema.json": "ae510f3ee1b6092c1061625e425c9bb7de9c9caa3f3774770c148f658d505753",
       "schemas/summaries/skill.schema.json": "f01bab92c51d64ee23e61587e42cf0dc5b37a2f518f5b12b3d1d456390338aa8",
-      "versioning.md": "37e42e323d0bfed647b72a3bd4ffc1ddd3f71b74dda1ba56025762518f070ccb"
+      "versioning.md": "e35d4a492f4cba7ff7c9168802fe11a17daa92c60fc3333ed04e2dbb8b3b6795"
     }
   }
 }

package/job-events.md

@@ -38,7 +38,7 @@ Every event is a JSON object with this envelope:
 |---|---|---|
 | `type` | always | One of the canonical event types below. |
 | `timestamp` | always | Unix milliseconds when the event was emitted. |
-| `runId` | always | Identifier of the `sm job run` invocation. One run emits many events. Format: `r-YYYYMMDD-HHMMSS-XXXX`. |
+| `runId` | always | Identifier of the invocation that emitted the event. CLI runner loops use `r-YYYYMMDD-HHMMSS-XXXX`; synthetic or non-job runs use one optional mode segment: `r-<mode>-YYYYMMDD-HHMMSS-XXXX`. Canonical modes are `ext` (external Skill claims), `scan` (scan runs), and `check` (standalone issue recomputations). |
 | `jobId` | when job-scoped | The job the event refers to. Null for run-level events (`run.*`). |
 | `data` | per-event | Event-specific payload, shape defined below. |
 

package/package.json

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

package/plugin-kv-api.md

@@ -197,7 +197,7 @@ Mode A is perfectly isolated at the row level: the accessor physically cannot se
 
 Mode B is **isolated against accidents, not hostile code**. The scoped `Database` wrapper rejects cross-namespace queries at runtime. But a malicious plugin running in the same JavaScript process can bypass the wrapper by importing raw engine bindings directly. Plugins are user-placed code; the kernel trusts the user's judgement at install time.
 
-Post-v1.0 work: signed manifest, sandboxed worker-thread isolation, per-plugin DB file. None of these land before cut 1.
+Post-v1.0 work: signed manifest, sandboxed worker-thread isolation, per-plugin DB file. None of these land before `v0.5.0`.
 
 ---
 

package/versioning.md

@@ -66,7 +66,7 @@ While the spec is `0.Y.Z`:
 - Conformance is advisory — failing a conformance case is a bug report, not a spec violation.
 - `specCompat` in plugins should pin a minor range (`"^0.3.0"` means `>=0.3.0 <0.4.0`), not a major range.
 
-The first stable commitment is `spec-v1.0.0`. That tag ships with CUT 3 / `cli-v1.0.0`.
+The first stable commitment is `spec-v1.0.0`. In the current reference roadmap, that tag ships with `cli-v1.0.0`.
 
 ## Independence in practice