@skill-map/spec 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Spec changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 79aed4d: **Breaking**: rename `dispatch-lifecycle.md` → `job-lifecycle.md`.
+
+  ROADMAP decision #30 renamed the domain term "dispatch" to "job" (tables `state_jobs`, artifact "job file"). The spec prose filename had lagged behind; this change closes that gap.
+
+  All internal references updated: `architecture.md`, `cli-contract.md`, `db-schema.md`, `prompt-preamble.md`, `versioning.md`, `schemas/job.schema.json`, `README.md`, and `package.json` `files` list. `index.json` regenerated.
+
+  **Migration**: any external consumer that links to `spec/dispatch-lifecycle.md` (by URL or filename) MUST update to `spec/job-lifecycle.md`. The canonical URL becomes `https://skill-map.dev/spec/v0/job-lifecycle.md`.
+
+  Classification: breaking change on a normative prose doc. Per `versioning.md` §Pre-1.0, minor bumps MAY contain breaking changes while the spec is `0.Y.Z`.
+
+## 0.1.2
+
+### Patch Changes
+
+- f4214fe: Expand `spec/README.md` §Distribution with concrete install and usage snippets now that `@skill-map/spec` is live on npm: install command, loading a schema via `exports`, and a small integrity-verification example using the `index.json` sha256 block.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -10,7 +10,7 @@ This document is the **source of truth**. The reference implementation under `..
 - The **extension contract**: six extension kinds (detector, adapter, rule, action, audit, renderer) with their input/output shapes.
 - The **CLI contract**: verb set, flags, exit codes, JSON introspection.
 - The **persistence contract**: table catalog owned by the kernel, plugin key-value API.
-- The **job contract**: lifecycle states, event stream, prompt preamble, dispatch semantics.
+- The **job contract**: lifecycle states, event stream, prompt preamble, submit/claim/record semantics.
 - The **frontmatter standard**: base fields and per-kind extensions.
 - The **summary standard**: shape of action-produced summaries per kind.
 - The **plugin manifest**: metadata, spec-compat range, storage mode, security declarations.
@@ -47,7 +47,7 @@ spec/
 ├── prompt-preamble.md          ← canonical injection-mitigation preamble      (Step 0a phase 3)
 ├── db-schema.md                ← table catalog (kernel-owned)                  (Step 0a phase 3)
 ├── plugin-kv-api.md            ← ctx.store contract for storage mode A        (Step 0a phase 3)
-├── dispatch-lifecycle.md       ← queued → running → completed | failed        (Step 0a phase 3)
+├── job-lifecycle.md       ← queued → running → completed | failed        (Step 0a phase 3)
 ├── schemas/                    ← JSON Schemas (Step 0a phase 2)
 │   ├── node.schema.json
 │   ├── link.schema.json
@@ -84,7 +84,7 @@ spec/
 - **Building a custom detector, rule, or renderer?** Read `architecture.md`, then the relevant schema.
 - **Building an alternative CLI implementation?** Read `cli-contract.md` and run `conformance/`.
 - **Integrating a new platform (adapter)?** Read `architecture.md` §adapters, then the Claude adapter source in `../src/extensions/adapters/claude/` as a worked example.
-- **Shipping a job-running runner?** Read `job-events.md`, `dispatch-lifecycle.md`, `prompt-preamble.md`.
+- **Shipping a job-running runner?** Read `job-events.md`, `job-lifecycle.md`, `prompt-preamble.md`.
 
 ## Relationship to the reference implementation
 
@@ -96,9 +96,44 @@ When spec and reference impl disagree, the spec wins. File an issue; one of them
 
 ## Distribution
 
-- This directory is published to npm as `@skill-map/spec`.
-- Schemas are also published to JSON Schema Store when the domain is live.
-- Canonical URLs (stable across versions) land with Step 13.
+Published to npm as [`@skill-map/spec`](https://www.npmjs.com/package/@skill-map/spec).
+
+### Install
+
+```bash
+npm i @skill-map/spec
+```
+
+### Use — load a schema
+
+```js
+import specIndex from '@skill-map/spec';
+import nodeSchema from '@skill-map/spec/schemas/node.schema.json' with { type: 'json' };
+
+console.log(specIndex.specVersion);        // → "0.0.1" (payload version, tracks file shape)
+console.log(specIndex.integrity.algorithm); // → "sha256"
+console.log(nodeSchema.$id);                // → "https://skill-map.dev/spec/v0/node.schema.json"
+```
+
+Every JSON Schema is exported individually via `@skill-map/spec/schemas/*.json`. Prose documents ship in the tarball for reference but are not `exports`-surfaced.
+
+### Verify integrity
+
+The package ships `index.json` with a sha256 per file. To verify a local installation matches what was published:
+
+```js
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import index from '@skill-map/spec';
+
+const file = 'schemas/node.schema.json';
+const actual = createHash('sha256').update(readFileSync(`node_modules/@skill-map/spec/${file}`)).digest('hex');
+console.log(actual === index.integrity.files[file] ? 'ok' : 'drift');
+```
+
+### JSON Schema Store
+
+The schemas will be registered on JSON Schema Store once the canonical URLs under `skill-map.dev/spec/v0/` are stable (Step 13).
 
 ## License
 

package/architecture.md

@@ -47,7 +47,7 @@ An implementation MUST expose these five ports. Each is an interface (TypeScript
 
 Persistence for all kernel tables in all three zones (`scan_*`, `state_*`, `config_*`). Exposes typed repositories, not raw SQL. Implementations MAY back this with SQLite, Postgres, in-memory, or anything else, as long as:
 
-- Transactional semantics for atomic claim (see `dispatch-lifecycle.md`).
+- Transactional semantics for atomic claim (see `job-lifecycle.md`).
 - Migration application with `PRAGMA user_version`-equivalent tracking.
 - Read isolation sufficient to avoid phantom reads across a single scan write.
 
@@ -77,7 +77,7 @@ Two reference implementations:
 - `ClaudeCliRunner` — subprocess `claude -p < jobfile`.
 - `MockRunner` — deterministic fake for tests.
 
-The Skill runner does NOT implement this port: it runs inside an agent session and closes jobs via `sm record` callback. See `dispatch-lifecycle.md`.
+The Skill runner does NOT implement this port: it runs inside an agent session and closes jobs via `sm record` callback. See `job-lifecycle.md`.
 
 ### `ProgressEmitterPort`
 

package/cli-contract.md

@@ -186,7 +186,7 @@ Actions are not invoked via `sm actions`; invocation is via `sm job submit` (see
 
 ### Jobs
 
-See `dispatch-lifecycle.md` for the state machine; this table is the CLI surface.
+See `job-lifecycle.md` for the state machine; this table is the CLI surface.
 
 | Command | Purpose |
 |---|---|

package/db-schema.md

@@ -4,7 +4,7 @@ Normative catalog of tables owned by the kernel. Plugins MAY add their own table
 
 The spec assumes a relational, SQL-like store but is **engine-agnostic**. The reference implementation uses SQLite (`node:sqlite`) + Kysely + `CamelCasePlugin`. Alternative backends (Postgres, DuckDB, in-memory) are permitted as long as:
 
-- Atomic single-statement transitions are available for the job claim (see `dispatch-lifecycle.md`).
+- Atomic single-statement transitions are available for the job claim (see `job-lifecycle.md`).
 - Migrations track applied versions per scope.
 - Read isolation avoids phantom reads inside a single scan write.
 

package/index.json

@@ -116,8 +116,8 @@
       "title": "CLI contract"
     },
     {
-      "file": "dispatch-lifecycle.md",
-      "title": "Dispatch lifecycle"
+      "file": "job-lifecycle.md",
+      "title": "Job lifecycle"
     },
     {
       "file": "job-events.md",
@@ -159,10 +159,10 @@
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "d545e5baffe09ddcb454f8dde36ad9226a6dca05ed8108a1ea2231935d7489f1",
-      "README.md": "d2b4c6debb9b7c4fdd34488e237672d8aff7687715744cf2c455977d5bc9813d",
-      "architecture.md": "fdb1ed50f12bf7b7fb89663c651277b7ba5ed729bd3dc02f3963c51e4d480b12",
-      "cli-contract.md": "ddb7d62f45398866dba2f25da544f8376d76582170712cb5a0010bb826ffb46a",
+      "CHANGELOG.md": "88908b684eabb5f508d6fe65a49e0786d1789ca9c8d2eb4195103c837ece1160",
+      "README.md": "7737242efe28e82b7ba4e2324e0ff6917a42e84c5bde9b940e409c8282d573eb",
+      "architecture.md": "6c25d25eabee7473fa25aa7884f1d3e3e8bed70eda3d688f7755ae9d5d4b0fd1",
+      "cli-contract.md": "321f625a9fbfdccf16f226dc76ca158bfb3392da5f96fc7b8faab4aa952a284a",
       "conformance/README.md": "4e41ff823b55ce3c274a033c5152ae0b2759fc714a714d7815593d8be84c8a4c",
       "conformance/cases/basic-scan.json": "24623da0cad8c8c54b3ff9b09820ea1276fe8b8f0fc680bf6e8abeb4edb8e424",
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
@@ -172,12 +172,12 @@
       "conformance/fixtures/minimal-claude/notes/architecture.md": "5a7e6fdbb1556733dacebad63758057dc1e19090b5a983292c0c65e90b98bcf1",
       "conformance/fixtures/minimal-claude/skills/hello.md": "8598074020430f294ff1eac39876302448f004b6c48446d453092159319bcbee",
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
-      "db-schema.md": "490e539f771fb9781fc97afef4f16d86b19eb9ecd9080eca9fcb8bc9605ae0a4",
-      "dispatch-lifecycle.md": "e2367bb51c638a9fbb20eec35c0603b2c4adb3668add50fec7be676521798f16",
+      "db-schema.md": "d2dfd52c2bc2a6b00ec6c89acc09240b409a6cfe29a06394351e6de5bc1de651",
       "interfaces/security-scanner.md": "468f8ee412594b14b389c36cefa9ca75a5dec652adbf03ab8bbc7f57ca980253",
       "job-events.md": "947d2124acc29f78df8f493549f0d1bdff8159caf621fe8307423c90d7d05f58",
+      "job-lifecycle.md": "ef3e96357784088e253c5b47ea4e1d4b04a5fdd1b3efb7ab55d70d006ed7e09f",
       "plugin-kv-api.md": "fb7cbaea6e18ad696e108fd6ec7a118dc9be6ffef4cf08cc92e511feafa9be30",
-      "prompt-preamble.md": "12f7489b5d9886070cfa43cf1f3871b46f2b478f3ead0db292f13e46239b417b",
+      "prompt-preamble.md": "9b7478ddce0a77043983f35932677d702319348048fe5d6b1c60257bd1c9f605",
       "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
       "schemas/frontmatter/agent.schema.json": "3c7ff5e485c1edd40d643ba0e0669fb920a511dfc174b91caff63473585b993d",
@@ -187,7 +187,7 @@
       "schemas/frontmatter/note.schema.json": "9806b371193c802803638682f9a625f8277152ad3ef68939eb5f05fff2ef65f4",
       "schemas/frontmatter/skill.schema.json": "b99b8ab23bee01333b4a04946cd9fc13d373d827ef6ddfc7d058daf637f2f80b",
       "schemas/issue.schema.json": "40f6f8abadcce0fd8eac9df27ffcc20b2fc9fda6970142ddb8e7e56b1760b9b1",
-      "schemas/job.schema.json": "6e6e791b63cf72591a5a9c72f469b803a69d9bdb6687d780d797ee1f47f8b9f4",
+      "schemas/job.schema.json": "582999899f8846f70c4d745d2813e53b97a4f5ccd3d8d163eeb68b201e7124e4",
       "schemas/link.schema.json": "3e92f5c9def61a857a2c7b22846d82b988157de083463615144ddc92403a489e",
       "schemas/node.schema.json": "14f345fac450f5728c895d1b878e0015eabb9d72ba9da4a8d2236c82933d3fcf",
       "schemas/plugins-registry.schema.json": "69388548a51496f2597145154911a208bef12d5c805ed71901e236525dccadf9",
@@ -199,7 +199,7 @@
       "schemas/summaries/hook.schema.json": "36f876f3b1a60d45be97a0848c79fd18744b434dfdcefc366f033b253d56268c",
       "schemas/summaries/note.schema.json": "ae510f3ee1b6092c1061625e425c9bb7de9c9caa3f3774770c148f658d505753",
       "schemas/summaries/skill.schema.json": "f01bab92c51d64ee23e61587e42cf0dc5b37a2f518f5b12b3d1d456390338aa8",
-      "versioning.md": "c526fb0068672016411a6660fe4a0ec5ef78086da96ba5e8277ce4e6adfec4bc"
+      "versioning.md": "37e42e323d0bfed647b72a3bd4ffc1ddd3f71b74dda1ba56025762518f070ccb"
     }
   }
 }

package/{dispatch-lifecycle.md → job-lifecycle.md}

@@ -1,4 +1,4 @@
-# Dispatch lifecycle
+# Job lifecycle
 
 Normative state machine for jobs. A `Job` (see `schemas/job.schema.json`) is the runtime instance of an `Action` applied to one or more `Node`s. Every job moves through this lifecycle exactly once.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "versioning.md",
     "architecture.md",
     "cli-contract.md",
-    "dispatch-lifecycle.md",
+    "job-lifecycle.md",
     "job-events.md",
     "prompt-preamble.md",
     "db-schema.md",

package/prompt-preamble.md

@@ -102,7 +102,7 @@ The preamble establishes a promise from the model:
 - `safety` MUST conform to `schemas/report-base.schema.json#/properties/safety`.
 - `confidence` MUST be a number in `[0.0, 1.0]`.
 
-The kernel validates every report against the action's declared schema (which MUST extend `report-base.schema.json`). A report that lacks `safety` or `confidence`, or whose values are of the wrong shape, is rejected; the job transitions to `failed` with reason `report-invalid` (see `dispatch-lifecycle.md`).
+The kernel validates every report against the action's declared schema (which MUST extend `report-base.schema.json`). A report that lacks `safety` or `confidence`, or whose values are of the wrong shape, is rejected; the job transitions to `failed` with reason `report-invalid` (see `job-lifecycle.md`).
 
 Implementations MUST NOT tolerate the absence of `safety`. If a model returns a report without it, the failure is the runner's problem to surface, not the kernel's to tolerate.
 

package/schemas/job.schema.json

@@ -40,7 +40,7 @@
     "status": {
       "type": "string",
       "enum": ["queued", "running", "completed", "failed"],
-      "description": "Lifecycle state. See `dispatch-lifecycle.md` for allowed transitions."
+      "description": "Lifecycle state. See `job-lifecycle.md` for allowed transitions."
     },
     "failureReason": {
       "type": ["string", "null"],

package/versioning.md

@@ -28,7 +28,7 @@ Rule of thumb: if a strict v1 implementation could fail a v1.X conformance run,
 All of the following are normative and governed by this policy:
 
 - Every JSON Schema in `schemas/` (fields, types, required, enums, defaults, `additionalProperties`).
-- Every MUST / SHOULD / MAY statement in prose documents (`architecture.md`, `cli-contract.md`, `job-events.md`, `prompt-preamble.md`, `db-schema.md`, `plugin-kv-api.md`, `dispatch-lifecycle.md`).
+- Every MUST / SHOULD / MAY statement in prose documents (`architecture.md`, `cli-contract.md`, `job-events.md`, `prompt-preamble.md`, `db-schema.md`, `plugin-kv-api.md`, `job-lifecycle.md`).
 - Exit codes, verb names, required flags, canonical error messages marked "normative".
 - Conformance fixtures and cases — removing or tightening a case is major.