@skill-map/spec 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Spec changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- 18d758a: Editorial pass across spec/ and src/ docs: convert relative-path text references (e.g. `plugin-kv-api.md`, `schemas/node.schema.json`) to proper markdown links, so they resolve on GitHub and in renderers. No normative or behavioural changes — prose, schemas, and CLI contract are unchanged.
+
 ## 0.5.0
 
 ### Minor Changes
@@ -123,7 +129,7 @@
   - `issue.*`: `issue.added`, `issue.resolved` — emitted after `scan.completed` when the new scan's issue set differs from the previous one. Diff key: `(ruleId, nodeIds sorted, message)`.
   - Synthetic run ids follow the existing `r-<mode>-YYYYMMDD-HHMMSS-XXXX` pattern (`r-scan-...`, `r-check-...`) alongside `r-ext-...` for external Skill claims.
 
-  These families ship at Step 12 of the reference impl alongside the WebSocket broadcaster. Marking them experimental keeps the shape mutable until real UI consumers exercise the stream; promotion to `stable` is a later minor bump.
+  These families ship at Step 13 of the reference impl alongside the WebSocket broadcaster. Marking them experimental keeps the shape mutable until real UI consumers exercise the stream; promotion to `stable` is a later minor bump.
 
   Classification: minor per §Pre-1.0. All additions are optional fields in a permissive config schema and new event types outside the stable job family — zero impact on existing implementations. Matching `ROADMAP.md` §Notable config keys and §Progress events updates land in the same change.
 
@@ -149,7 +155,7 @@
     - **Exempt** verbs (sub-millisecond, informational): `sm --version`, `sm --help`, `sm version`, `sm help`, `sm config get`, `sm config list`, `sm config show`.
     - Measurement spans from after arg-parsing to before terminal write.
   - **cli-contract.md** `sm history stats` entry: flags enumerated (`--since`, `--until`, `--period`, `--top`) and schema referenced.
-  - **Coverage matrix**: row `29` for `history-stats.schema.json` (blocked by Step 4); artifact row `L` for the elapsed-time reporting invariant (blocked by Step 3).
+  - **Coverage matrix**: row `29` for `history-stats.schema.json` (blocked by Step 5); artifact row `L` for the elapsed-time reporting invariant (blocked by Step 4).
 
   Classification: minor per §Pre-1.0. The elapsed-time contract introduces a SHOULD-emit line that didn't exist before — no existing consumer breaks, and the line goes to stderr where it doesn't clash with stdout JSON.
 
@@ -225,7 +231,7 @@
 
   **Breaking (pre-1.0 minor per `versioning.md` §Pre-1.0):**
 
-  - **Remove** `history.retentionDays`. The field promised execution-record GC, but `ROADMAP.md` §Step 6 and the job-retention section make it explicit that `state_executions` is append-only in `v0.1` and that the kernel does not use this key. Declaring a config key whose behaviour is "silently ignored" is worse than not declaring it — consumers would wire it in and never see an effect. The field will be re-introduced in a later minor bump when the GC path actually lands, with a concrete default and enforcement semantics.
+  - **Remove** `history.retentionDays`. The field promised execution-record GC, but `ROADMAP.md` §Step 7 and the job-retention section make it explicit that `state_executions` is append-only in `v0.1` and that the kernel does not use this key. Declaring a config key whose behaviour is "silently ignored" is worse than not declaring it — consumers would wire it in and never see an effect. The field will be re-introduced in a later minor bump when the GC path actually lands, with a concrete default and enforcement semantics.
 
   **Editorial:**
 
@@ -237,7 +243,7 @@
 
 - 93ffe34: Promote the trigger-normalization pipeline (Decision #21) from implicit to normative in `spec/architecture.md`.
 
-  Before this change, `link.trigger` carried `originalTrigger` and `normalizedTrigger` fields (defined in `schemas/link.schema.json`), and the `trigger-collision` rule keyed on the normalized value — but no spec prose documented **how** to normalize. The pipeline lived only in `AGENTS.md §Decisions already locked` and in `ROADMAP.md` as a one-line Step 6 bullet. That left implementations free to diverge, which silently breaks the `trigger-collision` rule across implementations (two conforming CLIs could disagree on whether `hacer-review` and `Hacer Review` collide).
+  Before this change, `link.trigger` carried `originalTrigger` and `normalizedTrigger` fields (defined in `schemas/link.schema.json`), and the `trigger-collision` rule keyed on the normalized value — but no spec prose documented **how** to normalize. The pipeline lived only in `AGENTS.md §Decisions already locked` and in `ROADMAP.md` as a one-line Step 7 bullet. That left implementations free to diverge, which silently breaks the `trigger-collision` rule across implementations (two conforming CLIs could disagree on whether `hacer-review` and `Hacer Review` collide).
 
   Added under `architecture.md §Extension kinds`, paralleling the existing `Adapter · defaultRefreshAction` subsection:
 
@@ -390,7 +396,7 @@
   - Referenced in `conformance/README.md` (§"Cases explicitly referenced elsewhere in the spec"). Entry moved from "pending" to "current" in the case inventory.
   - Registered in `spec/index.json` and the integrity block (SHA256 regenerated).
 
-  The second pending case, `preamble-bitwise-match`, is deferred to Step 9 (requires `sm job preview` from the job subsystem).
+  The second pending case, `preamble-bitwise-match`, is deferred to Step 10 (requires `sm job preview` from the job subsystem).
 
 - 4e0aec4: Initial public spec surface (`v0.1.0`):
 

package/README.md

@@ -24,15 +24,15 @@ This document is the **source of truth**. The reference implementation under `..
 - Logging format, telemetry, or distribution channels.
 - Plugin marketplace mechanics.
 
-These are implementation decisions. The reference impl picks them (see `../CLAUDE.md` and `../ROADMAP.md`); other implementations may pick differently and still conform.
+These are implementation decisions. The reference impl picks them (see [`../AGENTS.md`](../AGENTS.md) and [`../ROADMAP.md`](../ROADMAP.md)); other implementations may pick differently and still conform.
 
 ## Properties
 
 - **Machine-readable**: all domain shapes are JSON Schemas. Validate from any language that has a JSON Schema validator.
 - **Human-readable**: prose documents for each subsystem, with examples.
-- **Independently versioned**: spec `v1.0.0` can be implemented by CLI `v0.3.2`. See `versioning.md`.
+- **Independently versioned**: spec `v1.0.0` can be implemented by CLI `v0.3.2`. See [`versioning.md`](./versioning.md).
 - **Platform-neutral**: no platform (Claude Code, Obsidian, …) is privileged. Each is expressed as an adapter extension.
-- **Conformance-tested**: every conforming implementation passes the suite under `conformance/`. Pass/fail is binary.
+- **Conformance-tested**: every conforming implementation passes the suite under [`conformance/`](./conformance/README.md). Pass/fail is binary.
 
 ## Naming conventions
 
@@ -49,17 +49,17 @@ The SQL persistence layer is the sole exception: tables, columns, and migration
 spec/                              ← published as @skill-map/spec
 ├── README.md                      ← this file
 ├── CHANGELOG.md                   ← spec history (independent from CLI)
-├── versioning.md                  ← evolution policy
+├── [versioning.md](./versioning.md) ← evolution policy
 ├── package.json                   ← npm manifest for @skill-map/spec
 ├── index.json                     ← machine-readable manifest + per-file sha256 (generated)
 │
-├── architecture.md                ← hexagonal ports & adapters
-├── cli-contract.md                ← verbs, flags, exit codes, JSON introspection
-├── job-events.md                  ← canonical event stream schema
-├── prompt-preamble.md             ← canonical injection-mitigation preamble (verbatim normative)
-├── db-schema.md                   ← table catalog (kernel-owned)
-├── plugin-kv-api.md               ← ctx.store contract for storage mode A
-├── job-lifecycle.md               ← queued → running → completed | failed
+├── [architecture.md](./architecture.md)      ← hexagonal ports & adapters
+├── [cli-contract.md](./cli-contract.md)      ← verbs, flags, exit codes, JSON introspection
+├── [job-events.md](./job-events.md)          ← canonical event stream schema
+├── [prompt-preamble.md](./prompt-preamble.md) ← canonical injection-mitigation preamble (verbatim normative)
+├── [db-schema.md](./db-schema.md)            ← table catalog (kernel-owned)
+├── [plugin-kv-api.md](./plugin-kv-api.md)    ← ctx.store contract for storage mode A
+├── [job-lifecycle.md](./job-lifecycle.md)     ← queued → running → completed | failed
 │
 ├── schemas/                       ← 29 JSON Schemas, draft 2020-12, camelCase keys
 │   ├── node.schema.json                     ┐
@@ -99,26 +99,27 @@ spec/                              ← published as @skill-map/spec
 │       └── note.schema.json                 ┘
 │
 ├── interfaces/
-│   └── security-scanner.md        ← convention over the Action kind (NOT a 7th extension kind)
-└── conformance/
-    ├── fixtures/                  ← controlled MD corpora + preamble-v1.txt
-    └── cases/                     ← declarative test cases: basic-scan, kernel-empty-boot
-                                     (preamble-bitwise-match deferred to ../ROADMAP.md Step 9)
+│   └── [security-scanner.md](./interfaces/security-scanner.md) ← convention over the Action kind (NOT a 7th extension kind)
+├── [conformance/](./conformance/README.md)
+│   ├── [coverage.md](./conformance/coverage.md) ← schema-to-case coverage matrix
+│   ├── fixtures/                  ← controlled MD corpora + preamble-v1.txt
+│   └── cases/                     ← declarative test cases: basic-scan, kernel-empty-boot
+│                                    (preamble-bitwise-match deferred to ../ROADMAP.md Step 10)
 ```
 
 ## How to read this spec
 
-- **Building a tool or plugin that consumes skill-map output?** Start with `schemas/scan-result.schema.json` and `schemas/node.schema.json`.
-- **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`, `job-lifecycle.md`, `prompt-preamble.md`.
+- **Building a tool or plugin that consumes skill-map output?** Start with [`schemas/scan-result.schema.json`](./schemas/scan-result.schema.json) and [`schemas/node.schema.json`](./schemas/node.schema.json).
+- **Building a custom detector, rule, or renderer?** Read [`architecture.md`](./architecture.md), then the relevant schema under [`schemas/extensions/`](./schemas/extensions/).
+- **Building an alternative CLI implementation?** Read [`cli-contract.md`](./cli-contract.md) and run [`conformance/`](./conformance/README.md).
+- **Integrating a new platform (adapter)?** Read [`architecture.md`](./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`](./job-events.md), [`job-lifecycle.md`](./job-lifecycle.md), [`prompt-preamble.md`](./prompt-preamble.md).
 
 ## Relationship to the reference implementation
 
-The reference implementation (`../src/`) is one conforming consumer of this spec. It ships the CLI binary `sm`, a built-in SQLite storage adapter, and a bundle of default extensions.
+The reference implementation ([`../src/`](../src/README.md)) is one conforming consumer of this spec. It ships the CLI binary `sm`, a built-in SQLite storage adapter, and a bundle of default extensions.
 
-The reference impl has no privileged access to the spec. Breaking changes to the spec must follow `versioning.md` regardless of reference-impl convenience.
+The reference impl has no privileged access to the spec. Breaking changes to the spec must follow [`versioning.md`](./versioning.md) regardless of reference-impl convenience.
 
 When spec and reference impl disagree, the spec wins. File an issue; one of them is wrong.
 
@@ -162,7 +163,7 @@ 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).
+The schemas will be registered on JSON Schema Store once the canonical URLs under `skill-map.dev/spec/v0/` are stable (Step 14).
 
 ## License
 

package/architecture.md

@@ -2,7 +2,7 @@
 
 Normative description of skill-map's internal boundaries: the **kernel**, the **ports** it exposes, the **adapters** that drive and serve it, and the six **extension kinds** that live outside the kernel.
 
-Any conforming implementation — reference or third-party — MUST respect these boundaries. The conformance suite under `conformance/` enforces them.
+Any conforming implementation — reference or third-party — MUST respect these boundaries. The conformance suite under [`conformance/`](./conformance/README.md) enforces them.
 
 ---
 
@@ -47,11 +47,11 @@ 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 `job-lifecycle.md`).
+- Transactional semantics for atomic claim (see [`job-lifecycle.md`](./job-lifecycle.md)).
 - Migration application with `PRAGMA user_version`-equivalent tracking.
 - Read isolation sufficient to avoid phantom reads across a single scan write.
 
-The reference impl backs this with `node:sqlite` + Kysely + `CamelCasePlugin`.
+The reference impl backs this with `node:sqlite` + Kysely + `CamelCasePlugin`. See [`db-schema.md`](./db-schema.md) for the full table catalog.
 
 ### `FilesystemPort`
 
@@ -77,13 +77,13 @@ Two reference implementations:
 - `ClaudeCliRunner` — subprocess `claude -p < jobfile`.
 - `MockRunner` — deterministic fake for tests.
 
-The **Skill agent** does NOT implement this port: it is a peer driving adapter (alongside CLI and Server) that runs inside an LLM session and consumes `sm job claim` + `sm record` as a kernel client. The name "Skill runner" is descriptive, not structural — only the `ClaudeCliRunner` (and its test fake) implement `RunnerPort`. See `job-lifecycle.md`.
+The **Skill agent** does NOT implement this port: it is a peer driving adapter (alongside CLI and Server) that runs inside an LLM session and consumes `sm job claim` + `sm record` as a kernel client. The name "Skill runner" is descriptive, not structural — only the `ClaudeCliRunner` (and its test fake) implement `RunnerPort`. See [`job-lifecycle.md`](./job-lifecycle.md).
 
 ### `ProgressEmitterPort`
 
 Emits progress events during long operations (scans, job runs). Consumers: CLI pretty printer, `--json` ndjson, Server's WebSocket broadcaster.
 
-Operations: `emit(event)`, `subscribe(listener)`. Events are defined in `job-events.md`.
+Operations: `emit(event)`, `subscribe(listener)`. Events are defined in [`job-events.md`](./job-events.md).
 
 ---
 
@@ -92,8 +92,8 @@ Operations: `emit(event)`, `subscribe(listener)`. Events are defined in `job-eve
 The kernel is the only component that:
 - Maintains the extension registry.
 - Runs the scan orchestrator.
-- Validates scan output against `scan-result.schema.json`.
-- Applies the canonical prompt preamble to job files (`prompt-preamble.md`).
+- Validates scan output against [`scan-result.schema.json`](./schemas/scan-result.schema.json).
+- Applies the canonical prompt preamble to job files ([`prompt-preamble.md`](./prompt-preamble.md)).
 - Enforces duplicate-prevention and atomic-claim invariants for jobs.
 - Persists execution records.
 
@@ -117,7 +117,7 @@ No extension is privileged. The Claude adapter ships bundled with the reference
 
 ## Extension kinds
 
-Six kinds, all first-class, all loaded through the same registry. Each kind has a JSON Schema describing its manifest shape under `spec/schemas/extensions/<kind>.schema.json`. Implementations MUST validate every extension manifest against the schema for its declared kind at load time; validation failure → the extension is skipped with status `invalid-manifest`.
+Six kinds, all first-class, all loaded through the same registry. Each kind has a JSON Schema describing its manifest shape under [`schemas/extensions/`](./schemas/extensions/). Implementations MUST validate every extension manifest against the schema for its declared kind at load time; validation failure → the extension is skipped with status `invalid-manifest`.
 
 | Kind | Role | Input | Output |
 |---|---|---|---|
@@ -134,7 +134,7 @@ Every `Adapter` extension MUST declare a map `defaultRefreshAction: { <kind>: <a
 
 ### Detector · trigger normalization
 
-Detectors that emit invocation-style links (slashes, at-directives, command names) populate the `link.trigger` block defined in `schemas/link.schema.json`:
+Detectors that emit invocation-style links (slashes, at-directives, command names) populate the `link.trigger` block defined in [`schemas/link.schema.json`](./schemas/link.schema.json):
 
 - `originalTrigger` — the exact source text the detector saw, byte-for-byte. Used only for display.
 - `normalizedTrigger` — the output of the pipeline below. Used for equality and collision detection — the built-in `trigger-collision` rule keys on this field.
@@ -171,7 +171,7 @@ Characters outside the separator set that are not letters or digits (e.g. `/`, `
 
 1. An extension declares its kind in its module export and its manifest. Kind mismatch → load-error.
 2. An extension MAY declare `preconditions` — predicates that must be satisfied for the extension to be offered (e.g., `action.requires: ["kind=skill"]`).
-3. An extension MUST NOT retain state across invocations. Scoped persistence goes through `ctx.store` (storage mode `kv`) or the plugin's dedicated tables (`dedicated`).
+3. An extension MUST NOT retain state across invocations. Scoped persistence goes through `ctx.store` (storage mode `kv`) or the plugin's dedicated tables (`dedicated`). See [`plugin-kv-api.md`](./plugin-kv-api.md).
 4. An extension MUST NOT import another extension directly. Cross-extension communication goes through the kernel's registry lookup.
 5. An extension MUST provide a sibling test file. The reference impl treats a missing test as a contract-check failure; other impls MAY relax this to a warning.
 
@@ -248,6 +248,19 @@ This is what makes "CLI-first" a coherent rule: every CLI verb is a kernel funct
 
 ---
 
+## See also
+
+- [`cli-contract.md`](./cli-contract.md) — verb surface of the CLI driving adapter.
+- [`db-schema.md`](./db-schema.md) — table catalog backing `StoragePort`.
+- [`job-lifecycle.md`](./job-lifecycle.md) — state machine for jobs, atomic claim, TTL/reap.
+- [`job-events.md`](./job-events.md) — event stream emitted through `ProgressEmitterPort`.
+- [`prompt-preamble.md`](./prompt-preamble.md) — canonical injection-mitigation preamble for job files.
+- [`plugin-kv-api.md`](./plugin-kv-api.md) — `ctx.store` contract for extension persistence.
+- [`versioning.md`](./versioning.md) — spec/impl version independence and semver policy.
+- [`interfaces/security-scanner.md`](./interfaces/security-scanner.md) — convention over the Action kind for security scanners.
+
+---
+
 ## Stability
 
 The **port list** is stable as of spec v1.0.0. Adding a sixth port is a major bump.

package/cli-contract.md

@@ -384,6 +384,17 @@ The `done in …` stderr line, its format grammar, and the `elapsedMs` field con
 
 ---
 
+## See also
+
+- [`architecture.md`](./architecture.md) — CLI as a driving adapter; kernel-first design; dependency rules.
+- [`job-lifecycle.md`](./job-lifecycle.md) — state machine behind `sm job` verbs.
+- [`job-events.md`](./job-events.md) — event stream emitted via `--json` and `--stream-output`.
+- [`db-schema.md`](./db-schema.md) — tables behind `sm db` verbs.
+- [`../docs/cli-reference.md`](../docs/cli-reference.md) — auto-generated reference from `sm help --format md`.
+- [`conformance/`](./conformance/README.md) — test suite exercising CLI behavior.
+
+---
+
 ## Stability
 
 The **verb list** is stable as of spec v1.0.0. Adding a verb is a minor bump. Removing a verb is a major bump.

package/conformance/README.md

@@ -2,7 +2,7 @@
 
 Language-neutral test suite the specification demands. A conforming implementation passes every case; failing any case is a conformance bug.
 
-This directory is **stub-level** as of spec v0.1.0. Two cases ship (`basic-scan`, `kernel-empty-boot`) with a single shared fixture (`minimal-claude`). The shape below is normative; the case count expands before spec-v1.0.0 (see `versioning.md`).
+This directory is **stub-level** as of spec v0.1.0. Two cases ship (`basic-scan`, `kernel-empty-boot`) with a single shared fixture (`minimal-claude`). The shape below is normative; the case count expands before spec-v1.0.0 (see [`../versioning.md`](../versioning.md)). See [`coverage.md`](./coverage.md) for the full schema-to-case matrix.
 
 ---
 
@@ -33,7 +33,7 @@ Fixtures are read-only inputs. Cases declare what to invoke and what to assert.
 
 ## Case format
 
-Cases are validated against [`schemas/conformance-case.schema.json`](../schemas/conformance-case.schema.json). That file is the normative shape; this section is the human-readable walkthrough. Include `"$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json"` in every case file for IDE support.
+Cases are validated against [`conformance-case.schema.json`](../schemas/conformance-case.schema.json). That file is the normative shape; this section is the human-readable walkthrough. Include `"$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json"` in every case file for IDE support.
 
 A case is a JSON document with this shape:
 
@@ -106,7 +106,7 @@ Cases explicitly referenced elsewhere in the spec (landing before v1.0):
 
 | Id | Source | Verifies |
 |---|---|---|
-| `preamble-bitwise-match` | `prompt-preamble.md` | Rendered job files contain `preamble-v1.txt` byte-for-byte. Deferred to Step 9 (requires `sm job preview`). |
+| `preamble-bitwise-match` | `prompt-preamble.md` | Rendered job files contain `preamble-v1.txt` byte-for-byte. Deferred to Step 10 (requires `sm job preview`). |
 
 ---
 
@@ -132,6 +132,15 @@ The reference implementation's runner will ship under `src/conformance/` during
 
 ---
 
+## See also
+
+- [`coverage.md`](./coverage.md) — schema-to-case coverage matrix and release gates.
+- [`../versioning.md`](../versioning.md) — what constitutes a major/minor/patch change to the suite.
+- [`../architecture.md`](../architecture.md) — kernel empty-boot invariant exercised by `kernel-empty-boot`.
+- [`../prompt-preamble.md`](../prompt-preamble.md) — verbatim text checked by `preamble-bitwise-match` (deferred).
+
+---
+
 ## Stability
 
 - The **case format** above is stable as of the first spec release that includes the suite. Adding an assertion type is a minor bump. Removing or changing one is a major bump.

package/conformance/coverage.md

@@ -1,6 +1,6 @@
 # Conformance coverage
 
-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/).
+Authoritative map of JSON Schemas in [`../schemas/`](../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`](../../AGENTS.md) §Rules for AI agents editing spec/).
 
 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.
 
@@ -12,10 +12,10 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 2 | `link.schema.json` | — | 🔴 missing | Needs fixture with at least one `invokes` + `references` + `mentions` link, both `high`/`medium`/`low` confidence. |
 | 3 | `issue.schema.json` | — | 🔴 missing | Needs fixture triggering `trigger-collision` + `broken-ref` + `superseded`. |
 | 4 | `scan-result.schema.json` | `basic-scan`, `kernel-empty-boot` | 🟢 covered | Zero-filled (empty-boot) + populated (minimal-claude) both asserted. |
-| 5 | `execution-record.schema.json` | — | 🔴 missing | Blocked by Step 4 (history). Needs a case that runs a `local` action and inspects `state_executions` via `sm history --json`. |
+| 5 | `execution-record.schema.json` | — | 🔴 missing | Blocked by Step 5 (history). Needs a case that runs a `local` action and inspects `state_executions` via `sm history --json`. |
 | 6 | `project-config.schema.json` | — | 🔴 missing | Case: init a scope, write a partial `.skill-map.json`, assert effective config after merge. |
 | 7 | `plugins-registry.schema.json` | — | 🔴 missing | Two sub-cases required: (a) `PluginManifest` validation via `sm plugins show --json`; (b) aggregate `PluginsRegistry` via `sm plugins list --json`. |
-| 8 | `job.schema.json` | — | 🔴 missing | Blocked by Step 9 (job system). Needs a case that submits a local action (no LLM), inspects `sm job show --json`. |
+| 8 | `job.schema.json` | — | 🔴 missing | Blocked by Step 10 (job system). Needs a case that submits a local action (no LLM), inspects `sm job show --json`. |
 | 9 | `report-base.schema.json` | — | 🔴 missing | Indirect coverage once any summarizer case lands. Direct contract case: validate a handcrafted minimal report ({confidence, safety}) against the base schema. |
 | 10 | `conformance-case.schema.json` | — | 🔴 missing | Self-referential: every `*.json` under `cases/` MUST validate against this schema. Add a meta-case that enumerates + validates all cases. |
 | 11 | `frontmatter/base.schema.json` | `basic-scan` (indirect) | 🟡 partial | Covered via every kind schema's `allOf`. Direct case: fixture with min-required frontmatter only. |
@@ -24,11 +24,11 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 14 | `frontmatter/command.schema.json` | `basic-scan` | 🟢 covered | One command in `minimal-claude`. |
 | 15 | `frontmatter/hook.schema.json` | `basic-scan` | 🟢 covered | One hook in `minimal-claude`. |
 | 16 | `frontmatter/note.schema.json` | `basic-scan` | 🟢 covered | One note in `minimal-claude`. |
-| 17 | `summaries/skill.schema.json` | — | 🔴 missing | Blocked by Step 9 (`skill-summarizer`). Case: submit summarizer, validate report. |
-| 18 | `summaries/agent.schema.json` | — | 🔴 missing | Blocked by Step 10. |
-| 19 | `summaries/command.schema.json` | — | 🔴 missing | Blocked by Step 10. |
-| 20 | `summaries/hook.schema.json` | — | 🔴 missing | Blocked by Step 10. |
-| 21 | `summaries/note.schema.json` | — | 🔴 missing | Blocked by Step 10. |
+| 17 | `summaries/skill.schema.json` | — | 🔴 missing | Blocked by Step 10 (`skill-summarizer`). Case: submit summarizer, validate report. |
+| 18 | `summaries/agent.schema.json` | — | 🔴 missing | Blocked by Step 11. |
+| 19 | `summaries/command.schema.json` | — | 🔴 missing | Blocked by Step 11. |
+| 20 | `summaries/hook.schema.json` | — | 🔴 missing | Blocked by Step 11. |
+| 21 | `summaries/note.schema.json` | — | 🔴 missing | Blocked by Step 11. |
 | 22 | `extensions/base.schema.json` | — | 🔴 missing | Meta-case: every manifest under `src/extensions/` validates against the appropriate kind schema (which extends base via `allOf`). |
 | 23 | `extensions/adapter.schema.json` | — | 🔴 missing | Case: the `claude` adapter manifest validates; a crafted invalid manifest (missing `defaultRefreshAction`) fails with `invalid-manifest`. |
 | 24 | `extensions/detector.schema.json` | — | 🔴 missing | Case: `frontmatter` + `slash` + `at-directive` detector manifests validate; a detector emitting a disallowed `emitsLinkKinds` value fails. |
@@ -36,7 +36,7 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 26 | `extensions/action.schema.json` | — | 🔴 missing | Case: a `local` action manifest validates; an `invocation-template` action WITHOUT `promptTemplateRef` fails. |
 | 27 | `extensions/audit.schema.json` | — | 🔴 missing | Case: `validate-all` audit manifest validates; an audit referencing a non-existent rule id in `composes` fails at load with `invalid-manifest`. |
 | 28 | `extensions/renderer.schema.json` | — | 🔴 missing | Case: `ascii` renderer manifest validates. |
-| 29 | `history-stats.schema.json` | — | 🔴 missing | Blocked by Step 4 (history). Case: seed `state_executions` with a deterministic fixture, run `sm history stats --json --since <T0> --until <T1> --period month --top 5`, assert the document validates and that `totals.executionsCount == sum(perAction.executionsCount)` and `errorRates.global == totals.failedCount / totals.executionsCount`. Percentiles (`p95`/`p99`) intentionally omitted in v1 — add later as a minor bump without breaking consumers. |
+| 29 | `history-stats.schema.json` | — | 🔴 missing | Blocked by Step 5 (history). Case: seed `state_executions` with a deterministic fixture, run `sm history stats --json --since <T0> --until <T1> --period month --top 5`, assert the document validates and that `totals.executionsCount == sum(perAction.executionsCount)` and `errorRates.global == totals.failedCount / totals.executionsCount`. Percentiles (`p95`/`p99`) intentionally omitted in v1 — add later as a minor bump without breaking consumers. |
 
 Status legend: 🟢 covered (at least one case asserts the schema end-to-end) · 🟡 partial (covered only indirectly or via a sub-shape) · 🔴 missing.
 
@@ -46,18 +46,18 @@ These have their own conformance cases even though they are not JSON Schemas.
 
 | # | Artifact | Case | Status | Notes |
 |---|---|---|---|---|
-| A | Preamble verbatim text | `preamble-bitwise-match` | 🟠 deferred | Deferred to Step 9 (needs `sm job preview` to render a job file). Fixture: `fixtures/preamble-v1.txt` (already present, byte-identical to `prompt-preamble.md` source). |
+| A | Preamble verbatim text | `preamble-bitwise-match` | 🟠 deferred | Deferred to Step 10 (needs `sm job preview` to render a job file). Fixture: `fixtures/preamble-v1.txt` (already present, byte-identical to `prompt-preamble.md` source). |
 | B | Kernel empty-boot invariant | `kernel-empty-boot` | 🟢 covered | All extensions disabled → empty ScanResult. |
-| C | Atomic-claim race safety | — | 🔴 missing | Blocked by Step 9. Two concurrent `sm job claim` invocations against a single queued row — exactly one MUST succeed. |
-| D | Duplicate detection | — | 🔴 missing | Blocked by Step 9. Two `sm job submit` with same `(action, version, node, contentHash)` — second exits 3. |
-| E | `--force` bypass | — | 🔴 missing | Blocked by Step 9. |
-| F | Nonce mismatch | — | 🔴 missing | Blocked by Step 9. `sm record` with wrong nonce → exit 4. |
-| G | Reap | — | 🔴 missing | Blocked by Step 9. Set TTL to 1s; claim; wait; next `sm job run` reaps with reason `abandoned`. |
-| H | `run.*` event envelope for Skill agent | — | 🔴 missing | Blocked by Step 9. Skill-agent flow emits synthetic `r-ext-*` run envelope around one job. |
-| I | Rename heuristic | — | 🔴 missing | Blocked by Step 4. Move a file; same-`body_hash` → high-confidence auto-rename; `state_*` FK rows migrated; no issue emitted. |
-| J | Plugin DDL rejection | — | 🔴 missing | Blocked by Step 8. Plugin migration referencing `state_jobs` → disabled with `invalid-manifest`. |
-| K | Plugin prefix injection | — | 🔴 missing | Blocked by Step 8. Plugin declares `CREATE TABLE foo` → kernel applies as `plugin_<id>_foo`. |
-| L | Elapsed-time reporting | — | 🔴 missing | Blocked by Step 3 (first real verb work). Run any in-scope verb; stderr last line MUST match `/^done in (\d+ms\|\d+\.\d+s\|\d+m \d+s)$/`. In-scope verb with `--json` returning an object MUST carry `elapsedMs`. Exempt verb (`sm version`) MUST NOT emit the line. |
+| C | Atomic-claim race safety | — | 🔴 missing | Blocked by Step 10. Two concurrent `sm job claim` invocations against a single queued row — exactly one MUST succeed. |
+| D | Duplicate detection | — | 🔴 missing | Blocked by Step 10. Two `sm job submit` with same `(action, version, node, contentHash)` — second exits 3. |
+| E | `--force` bypass | — | 🔴 missing | Blocked by Step 10. |
+| F | Nonce mismatch | — | 🔴 missing | Blocked by Step 10. `sm record` with wrong nonce → exit 4. |
+| G | Reap | — | 🔴 missing | Blocked by Step 10. Set TTL to 1s; claim; wait; next `sm job run` reaps with reason `abandoned`. |
+| H | `run.*` event envelope for Skill agent | — | 🔴 missing | Blocked by Step 10. Skill-agent flow emits synthetic `r-ext-*` run envelope around one job. |
+| I | Rename heuristic | — | 🔴 missing | Blocked by Step 5. Move a file; same-`body_hash` → high-confidence auto-rename; `state_*` FK rows migrated; no issue emitted. |
+| J | Plugin DDL rejection | — | 🔴 missing | Blocked by Step 9. Plugin migration referencing `state_jobs` → disabled with `invalid-manifest`. |
+| K | Plugin prefix injection | — | 🔴 missing | Blocked by Step 9. Plugin declares `CREATE TABLE foo` → kernel applies as `plugin_<id>_foo`. |
+| L | Elapsed-time reporting | — | 🔴 missing | Blocked by Step 4 (first real verb work). Run any in-scope verb; stderr last line MUST match `/^done in (\d+ms\|\d+\.\d+s\|\d+m \d+s)$/`. In-scope verb with `--json` returning an object MUST carry `elapsedMs`. Exempt verb (`sm version`) MUST NOT emit the line. |
 
 ## Release gates
 

package/db-schema.md

@@ -1,10 +1,10 @@
 # Database schema
 
-Normative catalog of tables owned by the kernel. Plugins MAY add their own tables under a strict prefix (see `plugin-kv-api.md`). An implementation MUST provision every kernel table described here and MUST reject writes that violate the stated constraints.
+Normative catalog of tables owned by the kernel. Plugins MAY add their own tables under a strict prefix (see [`plugin-kv-api.md`](./plugin-kv-api.md)). An implementation MUST provision every kernel table described here and MUST reject writes that violate the stated constraints.
 
 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 `job-lifecycle.md`).
+- Atomic single-statement transitions are available for the job claim (see [`job-lifecycle.md`](./job-lifecycle.md)).
 - Migrations track applied versions per scope.
 - Read isolation avoids phantom reads inside a single scan write.
 
@@ -67,7 +67,7 @@ Domain types exposed to driving adapters use `camelCase`. The SQLite reference i
 
 ### `scan_nodes`
 
-One row per detected node, matching `schemas/node.schema.json`.
+One row per detected node, matching [`schemas/node.schema.json`](./schemas/node.schema.json).
 
 | Column | Type | Constraint | Notes |
 |---|---|---|---|
@@ -97,7 +97,7 @@ Indexes: `ix_scan_nodes_kind`, `ix_scan_nodes_adapter`, `ix_scan_nodes_body_hash
 
 ### `scan_links`
 
-One row per detected link, matching `schemas/link.schema.json`.
+One row per detected link, matching [`schemas/link.schema.json`](./schemas/link.schema.json).
 
 | Column | Type | Constraint | Notes |
 |---|---|---|---|
@@ -118,7 +118,7 @@ Indexes: `ix_scan_links_source_path`, `ix_scan_links_target_path`, `ix_scan_link
 
 ### `scan_issues`
 
-One row per rule-emitted issue, matching `schemas/issue.schema.json`.
+One row per rule-emitted issue, matching [`schemas/issue.schema.json`](./schemas/issue.schema.json).
 
 | Column | Type | Constraint | Notes |
 |---|---|---|---|
@@ -140,7 +140,7 @@ Indexes: `ix_scan_issues_rule_id`, `ix_scan_issues_severity`.
 
 ### `state_jobs`
 
-Matching `schemas/job.schema.json`.
+Matching [`schemas/job.schema.json`](./schemas/job.schema.json). See [`job-lifecycle.md`](./job-lifecycle.md) for the state machine and transitions.
 
 | Column | Type | Constraint |
 |---|---|---|
@@ -166,7 +166,7 @@ Indexes: `ix_state_jobs_status`, `ix_state_jobs_action_node_hash` (unique partia
 
 ### `state_executions`
 
-Matching `schemas/execution-record.schema.json`.
+Matching [`schemas/execution-record.schema.json`](./schemas/execution-record.schema.json).
 
 | Column | Type | Constraint |
 |---|---|---|
@@ -192,7 +192,7 @@ Indexes: `ix_state_executions_extension_id`, `ix_state_executions_started_at`, `
 
 ### `state_summaries`
 
-One row per `(node_id, summarizer_action_id)`. See `schemas/summaries/`.
+One row per `(node_id, summarizer_action_id)`. See [`schemas/summaries/`](./schemas/summaries/).
 
 | Column | Type | Constraint |
 |---|---|---|
@@ -223,7 +223,7 @@ Primary key: `(node_id, provider_id)`. Indexes: `ix_state_enrichments_stale_afte
 
 ### `state_plugin_kvs`
 
-Shared key-value store for plugins that declared storage mode `kv`. See `plugin-kv-api.md` for the accessor contract.
+Shared key-value store for plugins that declared storage mode `kv`. See [`plugin-kv-api.md`](./plugin-kv-api.md) for the accessor contract.
 
 | Column | Type | Constraint |
 |---|---|---|
@@ -294,11 +294,11 @@ The kernel ALSO maintains `PRAGMA user_version` (or the engine equivalent) as a
 
 ## Plugin storage
 
-Two modes declared in `plugin.json` (see `schemas/plugins-registry.schema.json`).
+Two modes declared in `plugin.json` (see [`schemas/plugins-registry.schema.json`](./schemas/plugins-registry.schema.json)).
 
 | Mode | Manifest | Backing |
 |---|---|---|
-| **KV** (mode A) | `"storage": { "mode": "kv" }` | Shared `state_plugin_kvs`. See `plugin-kv-api.md`. |
+| **KV** (mode A) | `"storage": { "mode": "kv" }` | Shared `state_plugin_kvs`. See [`plugin-kv-api.md`](./plugin-kv-api.md). |
 | **Dedicated** (mode B) | `"storage": { "mode": "dedicated", "tables": [...], "migrations": [...] }` | Plugin-owned tables, prefixed `plugin_<normalized_id>_`. |
 
 Normalization of `plugin_id` for the prefix:
@@ -386,6 +386,15 @@ Failures are reported with suggested remediation (e.g., "run `sm db migrate`", "
 
 ---
 
+## See also
+
+- [`architecture.md`](./architecture.md) — `StoragePort` interface definition and dependency rules.
+- [`plugin-kv-api.md`](./plugin-kv-api.md) — `ctx.store` accessor for mode A / mode B persistence.
+- [`job-lifecycle.md`](./job-lifecycle.md) — atomic claim and TTL/reap semantics that drive `state_jobs`.
+- [`cli-contract.md`](./cli-contract.md) — `sm db` verb surface (reset, backup, restore, migrate).
+
+---
+
 ## Stability
 
 The **three-zone model** and the **naming conventions** are stable as of spec v1.0.0. Adding a fourth zone is a major bump.

package/index.json

@@ -190,30 +190,30 @@
       }
     ]
   },
-  "specPackageVersion": "0.5.0",
+  "specPackageVersion": "0.5.1",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "adf0e49a213a8996cc2689749c47f2ed27cb9d31b40c18cece07b6d6ef94cd28",
-      "README.md": "a233e6b5ab1c41c13cb4790485f0514f7c111880eb70165e77e1253999069120",
-      "architecture.md": "be4085b7bbb3476f8a9d6df940b5794839b936ac5dd1921203a91558b008c7bc",
-      "cli-contract.md": "7657b6e60089afdd3644e7e38d96593158349259ab105d76199ce5eb65993cae",
-      "conformance/README.md": "4e41ff823b55ce3c274a033c5152ae0b2759fc714a714d7815593d8be84c8a4c",
+      "CHANGELOG.md": "b810067bdba655d066242db3159a157880250257c6cff03e96acc614758b8d1d",
+      "README.md": "8bd57e02d9a9d3f0a4efd18c0f0bd1f4bbe13eb206add0317659e48eab435e7e",
+      "architecture.md": "99f9d6a1a90e6c96d3c8a6f36c2650da4a1af0a1bc21173ea8eb2c492008539a",
+      "cli-contract.md": "4f01df640f39eacbb2192d543288e670de9ce2b89bf3931bc09f8488eb3baaea",
+      "conformance/README.md": "79c5e63f18a368951dc9f3e31e9bf9574de3f8b97150b2d75365d4febd8eb6dc",
       "conformance/cases/basic-scan.json": "24623da0cad8c8c54b3ff9b09820ea1276fe8b8f0fc680bf6e8abeb4edb8e424",
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
-      "conformance/coverage.md": "405a7ee093d6e54993ec5d9e061489f8b924829c7688fe56951bebf87abb2fae",
+      "conformance/coverage.md": "db9518f5a560b3df01093107de5c09ff38d478ae07c0476eea92644677fb1d83",
       "conformance/fixtures/minimal-claude/agents/reviewer.md": "d0dd681ba63838301e480116aa09825329f01832b0116de5c5476fdd8a5dcf54",
       "conformance/fixtures/minimal-claude/commands/status.md": "3f36e053fd1c059ffd902f84a55be8a458c26072f97cb37dd7e97314ae2a9bf5",
       "conformance/fixtures/minimal-claude/hooks/pre-commit.md": "ec9cec8ac4ce34d40ec055ffd90e8f06ea3e5764d6ec3ee84e0d97de71b930c7",
       "conformance/fixtures/minimal-claude/notes/architecture.md": "5a7e6fdbb1556733dacebad63758057dc1e19090b5a983292c0c65e90b98bcf1",
       "conformance/fixtures/minimal-claude/skills/hello.md": "8598074020430f294ff1eac39876302448f004b6c48446d453092159319bcbee",
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
-      "db-schema.md": "17de515904b8869ea0fe8d3cd608423376396bed6281b784ee1670f184d29f2c",
-      "interfaces/security-scanner.md": "468f8ee412594b14b389c36cefa9ca75a5dec652adbf03ab8bbc7f57ca980253",
-      "job-events.md": "090733b47dc0bbe62d790a87a29f2a13fe1dbcb9d6a89ea16e1ecff2293e3972",
-      "job-lifecycle.md": "793d34de0793596be17d2ed9042eeb4d532e805bceee25d9f9da0c3cb0b34b1c",
-      "plugin-kv-api.md": "fe0c02dcc7eaee0ad711f16247df076fa62348710ee1088e1234764dd3cec82e",
-      "prompt-preamble.md": "9b7478ddce0a77043983f35932677d702319348048fe5d6b1c60257bd1c9f605",
+      "db-schema.md": "ce4f9ddf84fa2aad746b44d6d9142b29b23c339e4915f97928489e035100fa55",
+      "interfaces/security-scanner.md": "81dc3dc2c439a75f4603b6d52e714f44ac564032c8aa424385ebbf4502adae3e",
+      "job-events.md": "08796b7fbeb55e5b03cf3bc394224e70a23438a4d15a46ad1d70121c2c68b967",
+      "job-lifecycle.md": "1fe88b1a2ed204e41bb41ac172fbb3e912dccd0dd8a1f8ea8e21a681b336d6ee",
+      "plugin-kv-api.md": "04b2178f46fb88adeae9240df9c9e1761b660396072001dac32cd402e11a2d7d",
+      "prompt-preamble.md": "23a8eff0477fbbc46192a27781bc781bda4202bb9c669b7a7a002b0d668146b0",
       "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
       "schemas/extensions/action.schema.json": "c7520d3cefecf75d27d3e04473821fd6e5dc5a7924eede147f74275ba6caccad",
@@ -243,7 +243,7 @@
       "schemas/summaries/hook.schema.json": "36f876f3b1a60d45be97a0848c79fd18744b434dfdcefc366f033b253d56268c",
       "schemas/summaries/note.schema.json": "ae510f3ee1b6092c1061625e425c9bb7de9c9caa3f3774770c148f658d505753",
       "schemas/summaries/skill.schema.json": "f01bab92c51d64ee23e61587e42cf0dc5b37a2f518f5b12b3d1d456390338aa8",
-      "versioning.md": "76a38d6b7e245a80274173a3cef791a04432e6ae3017ea3f66d7a37eb550fccf"
+      "versioning.md": "996e62006423edc01151a6f7869605f76c5e1454cc30b38d9f616925b5bcfb64"
     }
   }
 }

package/interfaces/security-scanner.md

@@ -10,7 +10,7 @@ Normative contract for third-party security-scanning plugins (Snyk, Socket, cust
 
 ## Why a convention, not a new kind
 
-The six extension kinds are locked (`architecture.md`). Adding a seventh for "security" would conflate concerns: scanners are really actions that produce a specialized report. A convention lets any Action opt into the scanner surface without kernel changes.
+The six extension kinds are locked ([`architecture.md`](../architecture.md)). Adding a seventh for "security" would conflate concerns: scanners are really actions that produce a specialized report. A convention lets any Action opt into the scanner surface without kernel changes.
 
 ---
 
@@ -55,7 +55,7 @@ Scanners are **local-mode** Actions by default: no LLM involvement. The Action r
 
 ## Output: the `SecurityReport` shape
 
-Every scanner MUST produce a report conforming to this shape. It extends `report-base.schema.json` with scanner-specific fields.
+Every scanner MUST produce a report conforming to this shape. It extends [`report-base.schema.json`](../schemas/report-base.schema.json) with scanner-specific fields.
 
 ```jsonc
 {
@@ -156,7 +156,7 @@ Vendors MAY introduce their own category with the prefix `vendor:<slug>` (e.g. `
 ## Runtime model
 
 - Scanners are invoked through the standard job system: `sm job submit security-snyk -n <node.path>` or `sm job submit security-snyk --all`.
-- The report is persisted through the normal action report mechanism (`state_executions.report_path` points to the JSON file).
+- The report is persisted through the normal action report mechanism ([`state_executions`](../db-schema.md)`.report_path` points to the JSON file).
 - `sm findings --security` aggregates findings from reports whose action id starts with `security-`, merging across scanners, deduplicating by `finding.id`.
 - Implementations MAY also surface findings at scan time via a companion Rule (e.g. `security-findings-stale` flags nodes whose last security scan is older than a threshold). This is recommended but not normative.
 
@@ -202,7 +202,7 @@ The Web UI's Security panel:
 
 ## Schema file location
 
-The JSON Schema for `SecurityReport` lives at `spec/schemas/summaries/security.schema.json` once Step 3 of the spec bootstrap completes. Until then, this document is the normative source and vendors SHOULD derive their own validator from it.
+The JSON Schema for `SecurityReport` lives at `spec/schemas/summaries/security.schema.json` once Step 4 of the spec bootstrap completes. Until then, this document is the normative source and vendors SHOULD derive their own validator from it.
 
 This is the only `summaries/*` schema that does NOT correspond to a node kind; it corresponds to an action category instead.
 
@@ -216,6 +216,15 @@ A scanner that produces a report NOT conforming to `SecurityReport` is still a v
 
 ---
 
+## See also
+
+- [`../architecture.md`](../architecture.md) — extension kinds (Action) and the kernel contract.
+- [`../job-lifecycle.md`](../job-lifecycle.md) — job submit/claim/record flow for scanner invocations.
+- [`../prompt-preamble.md`](../prompt-preamble.md) — `report-base` shape (safety + confidence) that scanner reports extend.
+- [`../db-schema.md`](../db-schema.md) — `state_executions` where scanner reports are persisted.
+
+---
+
 ## Stability
 
 **Stability: experimental** as of spec v0.x. Field names and conventions MAY tighten before v1.0 once real scanner implementations (Snyk, Socket, custom) ship and reveal shape needs.

package/job-events.md

@@ -8,7 +8,7 @@ This document is **normative**. The set of event types, their payload shapes, an
 
 ## Transport
 
-Events are records produced by the kernel through `ProgressEmitterPort` (see `architecture.md`). An implementation MUST provide three output adapters:
+Events are records produced by the kernel through `ProgressEmitterPort` (see [`architecture.md`](./architecture.md)). An implementation MUST provide three output adapters:
 
 | Adapter | Purpose | Format |
 |---|---|---|
@@ -254,7 +254,7 @@ Emitted when a job transitions to `failed` by any path.
 }
 ```
 
-`reason` enum matches `execution-record.failureReason`. `message` is human-readable free-form; MAY be truncated for display.
+`reason` enum matches [`execution-record.schema.json`](./schemas/execution-record.schema.json) `failureReason`. `message` is human-readable free-form; MAY be truncated for display.
 
 ### `run.summary`
 
@@ -308,7 +308,7 @@ A parallel implementation MAY interleave per-job sequences across different `job
 
 These event families cover kernel activity other than job execution. They share the common envelope (`type`, `timestamp`, `runId`, `jobId`, `data`). For non-job events `jobId` is always `null`; `runId` identifies the invocation that produced the event — a scan gets an `r-scan-YYYYMMDD-HHMMSS-XXXX` id, an issue recomputation outside a scan gets an `r-check-...` id, following the same `r-<mode>-...` shape as the external-Skill synthetic envelope (`r-ext-...`).
 
-The **shapes below are experimental through spec v0.x**. The reference impl starts emitting them at Step 12 alongside the WebSocket broadcaster; once real consumers exercise the stream, the fields lock. Bumping them to `stable` is a minor spec bump; changes to field shapes before `stable` are allowed without a major bump (per `versioning.md` §Pre-1.0).
+The **shapes below are experimental through spec v0.x**. The reference impl starts emitting them at Step 13 alongside the WebSocket broadcaster; once real consumers exercise the stream, the fields lock. Bumping them to `stable` is a minor spec bump; changes to field shapes before `stable` are allowed without a major bump (per [`versioning.md`](./versioning.md) §Pre-1.0).
 
 ### Scan events
 
@@ -429,6 +429,14 @@ Consumers MAY treat `emitter.error` as a soft failure (log and continue). Implem
 
 ---
 
+## See also
+
+- [`architecture.md`](./architecture.md) — `ProgressEmitterPort` definition.
+- [`job-lifecycle.md`](./job-lifecycle.md) — state machine that drives these events.
+- [`cli-contract.md`](./cli-contract.md) — `--json` and `--stream-output` flag semantics.
+
+---
+
 ## Stability
 
 The **job event type list** (`run.*`, `job.*`, `model.delta`, `emitter.error`) is stable as of spec v1.0.0. Adding a new event type is a minor bump. Removing or renaming one is a major bump.
@@ -439,4 +447,4 @@ Consumers MUST ignore unknown fields (forward compatibility).
 
 The envelope (`type`, `timestamp`, `runId`, `jobId`, `data`) is stable. Adding an envelope field is a major bump because every consumer would need to handle it.
 
-The **non-job event families** (`scan.*`, `issue.*`) are marked **experimental** across spec v0.x. They ship alongside the WebSocket broadcaster at Step 12 of the reference impl; shapes may tighten before a stable tag lands. Once promoted to `stable` (a minor spec bump), the same add/remove/rename semantics as the job events apply.
+The **non-job event families** (`scan.*`, `issue.*`) are marked **experimental** across spec v0.x. They ship alongside the WebSocket broadcaster at Step 13 of the reference impl; shapes may tighten before a stable tag lands. Once promoted to `stable` (a minor spec bump), the same add/remove/rename semantics as the job events apply.

package/job-lifecycle.md

@@ -1,6 +1,6 @@
 # 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.
+Normative state machine for jobs. A `Job` (see [`schemas/job.schema.json`](./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.
 
 ---
 
@@ -56,7 +56,7 @@ Any other transition attempt MUST be rejected and MUST NOT mutate state. Impleme
 5. Compute `ttlSeconds` per §TTL resolution below. Frozen on `state_jobs.ttlSeconds` for the life of this job.
 6. Resolve `priority` (integer, default `0`). Precedence (lowest → highest): action manifest `defaultPriority` → user config `jobs.perActionPriority.<actionId>` → flag `--priority <n>`. Higher runs first; ties broken by `createdAt ASC`. Negative values are permitted and run after the default bucket. The resolved value is frozen on `state_jobs.priority` at submit time and is immutable for the life of the job.
 7. Generate `nonce` (implementation-chosen; MUST be cryptographically random, ≥ 128 bits of entropy).
-8. Render the job file at `.skill-map/jobs/<id>.md`, applying the canonical preamble (see `prompt-preamble.md`).
+8. Render the job file at `.skill-map/jobs/<id>.md`, applying the canonical preamble (see [`prompt-preamble.md`](./prompt-preamble.md)).
 9. Insert a row in `state_jobs` with `status = 'queued'`, `createdAt = now`.
 10. Return the job id.
 
@@ -166,9 +166,9 @@ Negative or zero values MUST be rejected with exit 2 at submit time.
 2. Compare the supplied nonce against `state_jobs.nonce`. Mismatch → exit 4 without mutation.
 3. If `state_jobs.status != 'running'` → exit 2 with message "job not in running state". This catches late callbacks after a reap.
 4. If `--status completed`: validate the report file against the action's declared report schema. On validation failure → transition to `failed` with reason `report-invalid`; DO NOT stay `running`.
-5. Write the execution record (see `schemas/execution-record.schema.json`) with the full metrics.
+5. Write the execution record (see [`schemas/execution-record.schema.json`](./schemas/execution-record.schema.json)) with the full metrics.
 6. Transition the job to the terminal state.
-7. Emit `job.callback.received` followed by `job.completed` or `job.failed`.
+7. Emit `job.callback.received` followed by `job.completed` or `job.failed` (see [`job-events.md`](./job-events.md)).
 
 The nonce is the sole authentication factor. A compromised nonce allows forged callbacks for that single job. Nonces MUST be generated per-job; never reused; never logged at info level or above.
 
@@ -236,6 +236,16 @@ Config controls (`jobs.retention.completed`, `jobs.retention.failed`):
 
 ---
 
+## See also
+
+- [`architecture.md`](./architecture.md) — `RunnerPort` definition; driving-adapter peer rule for Skill agents.
+- [`job-events.md`](./job-events.md) — canonical event stream emitted during job execution.
+- [`prompt-preamble.md`](./prompt-preamble.md) — verbatim preamble prepended to every rendered job file.
+- [`db-schema.md`](./db-schema.md) — `state_jobs` and `state_executions` table catalogs.
+- [`cli-contract.md`](./cli-contract.md) — `sm job` verb surface and exit codes.
+
+---
+
 ## Stability
 
 The state machine diagram above is **stable** as of spec v1.0.0. Adding a new state is a major bump. Adding a new terminal reason (`failureReason` enum value) is a minor bump.

package/package.json

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

package/plugin-kv-api.md

@@ -1,6 +1,6 @@
 # Plugin KV API
 
-Normative contract for plugin-accessible persistence. Two modes exist (see `db-schema.md` for the catalog entries):
+Normative contract for plugin-accessible persistence. Two modes exist (see [`db-schema.md`](./db-schema.md) for the catalog entries):
 
 - **Mode A — KV**: plugin uses the kernel-provided `ctx.store.*` accessor. Backed by the shared `state_plugin_kvs` table.
 - **Mode B — Dedicated**: plugin owns its own tables with the `plugin_<normalizedId>_` prefix, migrated by the kernel.
@@ -54,7 +54,7 @@ Operations MAY be additionally scoped by `nodePath`:
 - **Global KV (no `nodePath`)**: `{pluginId, nodePath: null, key}`. One row per plugin + key.
 - **Node-scoped KV (with `nodePath`)**: `{pluginId, nodePath: "<path>", key}`. One row per plugin + node + key.
 
-Both scopes share the same underlying `state_plugin_kvs` table (see `db-schema.md`). The `nodePath` column is nullable; implementations MUST use a sentinel empty string internally when the backing engine rejects NULL in composite primary keys.
+Both scopes share the same underlying `state_plugin_kvs` table (see [`db-schema.md`](./db-schema.md)). The `nodePath` column is nullable; implementations MUST use a sentinel empty string internally when the backing engine rejects NULL in composite primary keys.
 
 ### Semantics
 
@@ -102,7 +102,7 @@ Errors MUST NOT leak backend-specific details (SQL strings, file paths) to plugi
 
 ## Mode B: dedicated tables
 
-Mode B is governed by `db-schema.md` (catalog rules + triple protection). This section restates the API surface.
+Mode B is governed by [`db-schema.md`](./db-schema.md) (catalog rules + triple protection). This section restates the API surface.
 
 ### Declaration
 
@@ -147,7 +147,7 @@ Mode B plugins MAY call `db.transaction(async (tx) => { ... })`. The kernel prov
 - Index and constraint prefixes are similarly injected.
 - A failing plugin migration disables only that plugin (`status: load-error`); other plugins and the kernel continue.
 
-See `db-schema.md` for the normative migration rules.
+See [`db-schema.md`](./db-schema.md) for the normative migration rules.
 
 ---
 
@@ -168,7 +168,7 @@ Non-normative; descriptive guidance for plugin authors.
 - Your data model is actually tabular (cache with TTL, observation log, provider registry).
 - You are willing to own migrations forever.
 
-A plugin MUST declare **exactly one** storage mode. Mixing modes in the same plugin is forbidden. The `plugins-registry.schema.json` enforces this at the manifest level (`storage` is a `oneOf` between `kv` and `dedicated`), and at runtime `ctx.store` exposes either the `KvStore` or the `DedicatedStore` shape — never both. A plugin that needs both KV-like and relational access MUST use mode B and implement KV-style rows as a dedicated table.
+A plugin MUST declare **exactly one** storage mode. Mixing modes in the same plugin is forbidden. The [`plugins-registry.schema.json`](./schemas/plugins-registry.schema.json) enforces this at the manifest level (`storage` is a `oneOf` between `kv` and `dedicated`), and at runtime `ctx.store` exposes either the `KvStore` or the `DedicatedStore` shape — never both. A plugin that needs both KV-like and relational access MUST use mode B and implement KV-style rows as a dedicated table.
 
 ---
 
@@ -201,6 +201,13 @@ Post-v1.0 work: signed manifest, sandboxed worker-thread isolation, per-plugin D
 
 ---
 
+## See also
+
+- [`db-schema.md`](./db-schema.md) — table catalog, migration rules, triple protection for mode B.
+- [`architecture.md`](./architecture.md) — extension contract rules and `ctx.store` injection via the kernel.
+
+---
+
 ## Stability
 
 - The `KvStore` interface (method names, options, return shapes) is **stable** as of spec v1.0.0.

package/prompt-preamble.md

@@ -99,10 +99,10 @@ The preamble establishes a promise from the model:
 
 - Every report MUST be valid JSON.
 - Every report MUST contain `safety` and `confidence` at the top level.
-- `safety` MUST conform to `schemas/report-base.schema.json#/properties/safety`.
+- `safety` MUST conform to [`schemas/report-base.schema.json`](./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 `job-lifecycle.md`).
+The kernel validates every report against the action's declared schema (which MUST extend [`report-base.schema.json`](./schemas/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`](./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.
 
@@ -125,13 +125,13 @@ Implementations MUST NOT modify the preamble text at runtime (e.g., based on loc
 
 ## Versioning the preamble
 
-The preamble text is a **normative artifact** of the spec. Any change follows `versioning.md`:
+The preamble text is a **normative artifact** of the spec. Any change follows [`versioning.md`](./versioning.md):
 
 - Editorial fixes to examples (none exist today, keep it that way) — patch bump.
 - Tightening the instructions (e.g., adding a new refusal clause) — minor bump.
-- Changing the shape the model must emit (`safety` structure) — major bump, because it propagates to `report-base.schema.json`.
+- Changing the shape the model must emit (`safety` structure) — major bump, because it propagates to [`report-base.schema.json`](./schemas/report-base.schema.json).
 
-Every spec release that modifies the preamble MUST record the rationale in `CHANGELOG.md`.
+Every spec release that modifies the preamble MUST record the rationale in [`CHANGELOG.md`](./CHANGELOG.md).
 
 ---
 
@@ -147,6 +147,15 @@ Defense-in-depth: the deterministic rule `injection-pattern` (shipped as a built
 
 ---
 
+## See also
+
+- [`job-lifecycle.md`](./job-lifecycle.md) — submit flow that renders job files with the preamble.
+- [`architecture.md`](./architecture.md) — kernel's role in applying the preamble.
+- [`interfaces/security-scanner.md`](./interfaces/security-scanner.md) — `SecurityReport` convention that extends `report-base`.
+- [`conformance/`](./conformance/README.md) — `preamble-bitwise-match` case (deferred to Step 10).
+
+---
+
 ## Stability
 
-The verbatim text above is **stable** as of spec v1.0.0. It is reproduced in the conformance suite as `conformance/fixtures/preamble-v1.txt`. Any implementation whose rendered job files do not contain this text verbatim fails the conformance check `preamble-bitwise-match`.
+The verbatim text above is **stable** as of spec v1.0.0. It is reproduced in the conformance suite as [`conformance/fixtures/preamble-v1.txt`](./conformance/fixtures/preamble-v1.txt). Any implementation whose rendered job files do not contain this text verbatim fails the conformance check `preamble-bitwise-match`.

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`, `job-lifecycle.md`).
+- Every MUST / SHOULD / MAY statement in prose documents ([`architecture.md`](./architecture.md), [`cli-contract.md`](./cli-contract.md), [`job-events.md`](./job-events.md), [`prompt-preamble.md`](./prompt-preamble.md), [`db-schema.md`](./db-schema.md), [`plugin-kv-api.md`](./plugin-kv-api.md), [`job-lifecycle.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.
 
@@ -77,9 +77,9 @@ The first stable commitment is `spec-v1.0.0`. In the current reference roadmap,
 ## Change process
 
 1. PR proposes a spec change. Include rationale and classification (patch/minor/major).
-2. If major, PR includes a migration note draft for `CHANGELOG.md`.
+2. If major, PR includes a migration note draft for [`CHANGELOG.md`](./CHANGELOG.md).
 3. If the change affects reference-impl behavior, a companion PR in `src/` lands the implementation behind the bumped `specCompat`.
-4. Merge order: spec change first, implementation second. An implementation MUST NOT ship a feature that is not yet in the spec (see `AGENTS.md`: "Every feature: update spec/ first, then src/").
+4. Merge order: spec change first, implementation second. An implementation MUST NOT ship a feature that is not yet in the spec (see [`../AGENTS.md`](../AGENTS.md): "Every feature: update spec/ first, then src/").
 5. Tag spec release (`spec-vX.Y.Z`) independent from any CLI tag.
 
 ## Canonical URLs