npm - @skill-map/spec - Versions diffs - 0.5.0 → 0.6.0 - Mend

@skill-map/spec 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/CHANGELOG.md +115 -5
package/README.md +25 -24
package/architecture.md +23 -10
package/cli-contract.md +13 -2
package/conformance/README.md +12 -3
package/conformance/cases/orphan-detection.json +22 -0
package/conformance/cases/rename-high.json +21 -0
package/conformance/coverage.md +20 -20
package/conformance/fixtures/orphan-after/skills/keep.md +13 -0
package/conformance/fixtures/orphan-before/skills/keep.md +13 -0
package/conformance/fixtures/orphan-before/skills/lonely.md +13 -0
package/conformance/fixtures/rename-high-after/skills/bar.md +14 -0
package/conformance/fixtures/rename-high-before/skills/foo.md +14 -0
package/db-schema.md +42 -11
package/index.json +22 -15
package/interfaces/security-scanner.md +13 -4
package/job-events.md +12 -4
package/job-lifecycle.md +14 -4
package/package.json +1 -1
package/plugin-kv-api.md +12 -5
package/prompt-preamble.md +15 -6
package/schemas/conformance-case.schema.json +22 -2
package/versioning.md +3 -3

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,115 @@
 # Spec changelog
+## 0.6.0
+### Minor Changes
+- 9a89124: Step 5.1 — Persist scan-result metadata in a new `scan_meta` table so
+  `loadScanResult` returns real values for `scope` / `roots` / `scannedAt` /
+  `scannedBy` / `adapters` / `stats.filesWalked` / `stats.filesSkipped` /
+  `stats.durationMs` instead of the synthetic envelope shipped at Step 4.7.
+  **Spec change (additive, minor)**:
+  - New `scan_meta` table in zone `scan_*`, single-row (CHECK `id = 1`).
+    Columns: `scope`, `roots_json`, `scanned_at`, `scanned_by_name`,
+    `scanned_by_version`, `scanned_by_spec_version`, `adapters_json`,
+    `stats_files_walked`, `stats_files_skipped`, `stats_duration_ms`.
+    `nodesCount` / `linksCount` / `issuesCount` are not stored — they are
+    derived from `COUNT(*)` of the sibling tables.
+  - Replaced atomically with the rest of `scan_*` on every `sm scan`.
+  **Runtime change**:
+  - New kernel migration `002_scan_meta.sql`.
+  - `IScanMetaTable` added to `src/kernel/adapters/sqlite/schema.ts` and
+    bound in `IDatabase`.
+  - `persistScanResult` writes the row (and deletes prior rows in the same
+    transaction).
+  - `loadScanResult` reads from `scan_meta` when the row exists; degrades
+    to the previous synthetic envelope when it does not (DB freshly
+    migrated, never scanned, or pre-5.1 snapshot).
+  - The Step 4.7 follow-up notes in `scan-load.ts` documenting the
+    synthetic envelope are simplified to describe both branches.
+  Test count: 151 → 154 (+3 covering meta round-trip, replace-all
+  single-row invariant, and synthetic-fallback on empty DB).
+- 9a89124: Step 5.7 — Conformance coverage for the rename heuristic.
+  **Spec change (additive, minor)**:
+  - `spec/schemas/conformance-case.schema.json` gains
+    `setup.priorScans: Array<{ fixture, flags? }>` — an ordered list of
+    staging scans the runner executes BEFORE the main `invoke`. Each
+    step replaces every non-`.skill-map/` directory in the scope with
+    the named fixture and runs `sm scan` (with optional flags). The DB
+    persists across steps because `.skill-map/` is preserved between
+    swaps. After the last step, the runner copies the top-level
+    `fixture` and runs the case's `invoke`.
+    Required to express scenarios that need a prior snapshot (rename
+    heuristic, future incremental cases). The schema is purely
+    additive — every existing case keeps passing without modification.
+  - Two new conformance cases under `spec/conformance/cases/`:
+    - **`rename-high`** — moving a single file with identical body
+      triggers a high-confidence auto-rename. Asserts:
+      `stats.nodesCount === 1`, `stats.issuesCount === 0`,
+      `nodes[0].path === skills/bar.md`. Verifies the spec invariant
+      that high-confidence renames emit NO issue.
+    - **`orphan-detection`** — deleting a file with no replacement
+      emits exactly one `orphan` issue (severity `info`). Asserts the
+      `ruleId` and `severity` directly.
+  - Four new fixture directories under `spec/conformance/fixtures/`:
+    `rename-high-before/`, `rename-high-after/`,
+    `orphan-before/`, `orphan-after/`.
+  - `spec/conformance/coverage.md`: row I (Rename heuristic) flips
+    from `🔴 missing` to `🟢 covered`. Notes the medium / ambiguous
+    branches stay covered by `src/test/rename-heuristic.test.ts` for
+    now (assertion vocabulary in the schema is not rich enough to
+    express "the issues array contains an item with ruleId X and
+    data.confidence === 'medium'" — when the conformance schema gains
+    array-filter assertions, those branches can land here too).
+  **Runtime change**:
+  - `src/conformance/index.ts` runner: implements `setup.priorScans`.
+    Helper `replaceFixture(scope, specRoot, fixture)` clears every
+    top-level entry in the scope except `.skill-map/`, then copies the
+    named fixture on top. Used by both staging steps and the main
+    `fixture` phase.
+  - `src/test/conformance.test.ts`: includes the two new cases in the
+    Step-0b subset. Total conformance cases passing in CI: 1 → 3.
+  **`spec/index.json`** regenerated (50 → 57 files). `npm run spec:check`
+  green.
+  Test count: 201 → 203 (+2 conformance cases). The Step 5 totals close
+  at: 151 → 203 (+52 across 7 sub-steps).
+### Patch Changes
+- dacd4d9: Move the auto-generated CLI reference from `docs/cli-reference.md` to
+  `context/cli-reference.md`. Spec change is editorial: `cli-contract.md`
+  references the file path in three spots (`--format md` description, the
+  NORMATIVE introspection section, and the "Related" link list); all three
+  updated to the new location. No schema or behavioural change.
+  Reference impl: `scripts/build-cli-reference.mjs` writes to the new path,
+  the `cli:reference` / `cli:check` npm scripts point there, and `sm help`
+  output (which embeds the path in the `--format md` flag description) is
+  regenerated. The `docs/` folder is gone.
+## 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 +233,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 +259,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 +335,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 +347,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 +500,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -121,7 +121,7 @@ Exit: 0 if all green, 1 if warnings, 2 if any `error`-level problem.
 Self-describing introspection.
 - `human` (default): pretty terminal output.
-- `md`: canonical markdown for documentation sites. Implementations MUST NOT hand-maintain equivalent markdown; `docs/cli-reference.md` (in the reference impl) is regenerated from this output in CI.
+- `md`: canonical markdown for documentation sites. Implementations MUST NOT hand-maintain equivalent markdown; `context/cli-reference.md` (in the reference impl) is regenerated from this output in CI.
 - `json`: structured surface dump. Shape:
 ```json
@@ -314,7 +314,7 @@ Destructive verbs (`reset --state`, `reset --hard`, `restore`) require interacti
 ### Introspection
 - `sm help --format json` — structured CLI surface dump.
-- `sm help --format md` — canonical markdown, CI-enforced for the reference impl's `docs/cli-reference.md`.
+- `sm help --format md` — canonical markdown, CI-enforced for the reference impl's `context/cli-reference.md`.
 These two formats are NORMATIVE: any change to verbs, flags, or exit codes MUST reflect in `--format json` output immediately. Third-party consumers rely on this.
@@ -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.
+- [`../context/cli-reference.md`](../context/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 CHANGED Viewed

@@ -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/cases/orphan-detection.json ADDED Viewed

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "orphan-detection",
+  "description": "Deleting a file with no replacement triggers the orphan branch of the rename heuristic: exactly one issue with ruleId `orphan` is emitted, severity `info`, naming the dead path. The remaining survivor node is reported normally.",
+  "fixture": "orphan-after",
+  "setup": {
+    "priorScans": [
+      { "fixture": "orphan-before" }
+    ]
+  },
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--changed", "--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.issues[0].ruleId", "equals": "orphan" },
+    { "type": "json-path", "path": "$.issues[0].severity", "equals": "info" }
+  ]
+}

package/conformance/cases/rename-high.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "rename-high",
+  "description": "Moving a single file with identical body across the rename triggers a high-confidence auto-rename: NO issue is emitted (per spec/db-schema.md §Rename detection), the new path is the only node in the result, and the rename heuristic operates silently.",
+  "fixture": "rename-high-after",
+  "setup": {
+    "priorScans": [
+      { "fixture": "rename-high-before" }
+    ]
+  },
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--changed", "--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 0 },
+    { "type": "json-path", "path": "$.nodes[0].path", "equals": "skills/bar.md" }
+  ]
+}

package/conformance/coverage.md CHANGED Viewed

@@ -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 | `rename-high`, `orphan-detection` | 🟢 covered | High-confidence rename emits no issue and the new path is the sole node. Orphan branch emits exactly one `orphan` issue (severity `info`) when a deleted node has no replacement. Medium / ambiguous branches are exercised by `src/test/rename-heuristic.test.ts` until the conformance schema grows richer assertions. |
+| 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/conformance/fixtures/orphan-after/skills/keep.md ADDED Viewed

@@ -0,0 +1,13 @@
+---
+name: orphan-keep
+description: Fixture node that survives across before/after, so the after-state still has at least one node.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+# Survivor
+Keeps the after-state graph non-empty so we can assert that the orphan
+issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/keep.md ADDED Viewed

@@ -0,0 +1,13 @@
+---
+name: orphan-keep
+description: Fixture node that survives across before/after, so the after-state still has at least one node.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+# Survivor
+Keeps the after-state graph non-empty so we can assert that the orphan
+issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/lonely.md ADDED Viewed

@@ -0,0 +1,13 @@
+---
+name: orphan-lonely
+description: Fixture node that gets deleted in the after-state to trigger the orphan path.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+# Orphan lonely body
+This file disappears in `orphan-after`. With no replacement matching
+its hashes, the rename heuristic emits an `orphan` issue.

package/conformance/fixtures/rename-high-after/skills/bar.md ADDED Viewed

@@ -0,0 +1,14 @@
+---
+name: rename-high-foo
+description: Fixture node for the high-confidence rename conformance case.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+# Rename high body
+Body content kept identical between the before and after fixtures so
+the body hash matches across the rename. Move it to `bar.md` to trigger
+a high-confidence auto-rename.

package/conformance/fixtures/rename-high-before/skills/foo.md ADDED Viewed

@@ -0,0 +1,14 @@
+---
+name: rename-high-foo
+description: Fixture node for the high-confidence rename conformance case.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+# Rename high body
+Body content kept identical between the before and after fixtures so
+the body hash matches across the rename. Move it to `bar.md` to trigger
+a high-confidence auto-rename.

package/db-schema.md CHANGED Viewed

@@ -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 |
 |---|---|---|---|
@@ -134,13 +134,35 @@ One row per rule-emitted issue, matching `schemas/issue.schema.json`.
 Indexes: `ix_scan_issues_rule_id`, `ix_scan_issues_severity`.
+### `scan_meta`
+Single-row table holding the metadata of the last persisted scan. Lets `loadScanResult` return the real `scope` / `roots` / `scannedAt` / `scannedBy` / `adapters` / `stats.filesWalked|filesSkipped|durationMs` instead of synthesising them. Replaced atomically with the rest of the `scan_*` zone on every `sm scan`.
+`nodesCount` / `linksCount` / `issuesCount` are not stored here — they derive from `COUNT(*)` of the sibling tables.
+| Column | Type | Constraint |
+|---|---|---|
+| `id` | INTEGER | PRIMARY KEY, CHECK `id = 1` |
+| `scope` | TEXT | NOT NULL, CHECK in (`project`, `global`) |
+| `roots_json` | TEXT | NOT NULL | JSON array of strings (filesystem roots walked). |
+| `scanned_at` | INTEGER | NOT NULL | Unix milliseconds. |
+| `scanned_by_name` | TEXT | NOT NULL |
+| `scanned_by_version` | TEXT | NOT NULL |
+| `scanned_by_spec_version` | TEXT | NOT NULL |
+| `adapters_json` | TEXT | NOT NULL | JSON array of adapter ids. |
+| `stats_files_walked` | INTEGER | NOT NULL |
+| `stats_files_skipped` | INTEGER | NOT NULL |
+| `stats_duration_ms` | INTEGER | NOT NULL |
+No indexes (single row).
 ---
 ## Table catalog: zone `state_`
 ### `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 +188,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 +214,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 +245,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 +316,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 +408,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 CHANGED Viewed

@@ -190,31 +190,38 @@
       }
     ]
   },
-  "specPackageVersion": "0.5.0",
+  "specPackageVersion": "0.6.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "adf0e49a213a8996cc2689749c47f2ed27cb9d31b40c18cece07b6d6ef94cd28",
-      "README.md": "a233e6b5ab1c41c13cb4790485f0514f7c111880eb70165e77e1253999069120",
-      "architecture.md": "be4085b7bbb3476f8a9d6df940b5794839b936ac5dd1921203a91558b008c7bc",
-      "cli-contract.md": "7657b6e60089afdd3644e7e38d96593158349259ab105d76199ce5eb65993cae",
-      "conformance/README.md": "4e41ff823b55ce3c274a033c5152ae0b2759fc714a714d7815593d8be84c8a4c",
+      "CHANGELOG.md": "e74921b61ca835c4ebc8f2a4814d2c9513a59ce47c8c719b4d17865b39d93cba",
+      "README.md": "8bd57e02d9a9d3f0a4efd18c0f0bd1f4bbe13eb206add0317659e48eab435e7e",
+      "architecture.md": "99f9d6a1a90e6c96d3c8a6f36c2650da4a1af0a1bc21173ea8eb2c492008539a",
+      "cli-contract.md": "bab14bb72ddd8a57e00808f7f12741c63a33da99055b278e4407ab9b4bb7e2c1",
+      "conformance/README.md": "79c5e63f18a368951dc9f3e31e9bf9574de3f8b97150b2d75365d4febd8eb6dc",
       "conformance/cases/basic-scan.json": "24623da0cad8c8c54b3ff9b09820ea1276fe8b8f0fc680bf6e8abeb4edb8e424",
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
-      "conformance/coverage.md": "405a7ee093d6e54993ec5d9e061489f8b924829c7688fe56951bebf87abb2fae",
+      "conformance/cases/orphan-detection.json": "7fea6e866d775d09cadb70ccd764f6c8317ca61316c6d187a97cb2466db4e19e",
+      "conformance/cases/rename-high.json": "f23513893e25fc4259db06a497906137de981da775d8ab2ef262554d54af5f27",
+      "conformance/coverage.md": "a67fb38c69765bb3cafb78c75e211c530ab00a88d8ccf0254335d3b6d4f69b8d",
       "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/orphan-after/skills/keep.md": "a6fdc33104cb2e8092f386a427784685eee1c8d7cb8fddb934cf65984143c7fd",
+      "conformance/fixtures/orphan-before/skills/keep.md": "a6fdc33104cb2e8092f386a427784685eee1c8d7cb8fddb934cf65984143c7fd",
+      "conformance/fixtures/orphan-before/skills/lonely.md": "4ba2bb336fa46644d2b0dfef4c3b97879ecbf693b825a5348f032d1af049d80a",
       "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",
-      "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
+      "conformance/fixtures/rename-high-after/skills/bar.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
+      "conformance/fixtures/rename-high-before/skills/foo.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
+      "db-schema.md": "e9b436b143e2e56985c69498c7d48527bde0baa441be586e2740a4051b366c2d",
+      "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": "d69c501bbca079da0ca87685eb4cbdbc2e405334469fc937929ca9134e01a2b3",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
       "schemas/extensions/action.schema.json": "c7520d3cefecf75d27d3e04473821fd6e5dc5a7924eede147f74275ba6caccad",
       "schemas/extensions/adapter.schema.json": "429b865e738664bb437ac62690a2d7282ce992339fbb300417c73625f5cdb7c8",
@@ -243,7 +250,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/plugin-kv-api.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/schemas/conformance-case.schema.json CHANGED Viewed

@@ -28,12 +28,32 @@
     },
     "setup": {
       "type": "object",
-      "description": "Pre-invocation toggles. All default to `false`.",
+      "description": "Pre-invocation toggles and ordered staging steps. All toggles default to `false`. `priorScans`, when present, run BEFORE the main `invoke` so a case can establish a prior snapshot the heuristic-driven verbs (e.g. `sm scan` rename detection) can react to.",
       "additionalProperties": false,
       "properties": {
         "disableAllAdapters": { "type": "boolean" },
         "disableAllDetectors": { "type": "boolean" },
-        "disableAllRules": { "type": "boolean" }
+        "disableAllRules": { "type": "boolean" },
+        "priorScans": {
+          "type": "array",
+          "description": "Ordered staging scans, each running before the next. For step N, the runner first replaces the scope's adapter content with `priorScans[N].fixture`, then invokes `sm scan` with the supplied flags. After the last step, the runner copies the top-level `fixture` (overwriting again) and runs the main `invoke`. The DB persists across all steps because `.skill-map/` is preserved between fixture swaps.",
+          "items": {
+            "type": "object",
+            "required": ["fixture"],
+            "additionalProperties": false,
+            "properties": {
+              "fixture": {
+                "type": "string",
+                "description": "Folder under `conformance/fixtures/` to copy into the scope, replacing every non-`.skill-map/` directory."
+              },
+              "flags": {
+                "type": "array",
+                "description": "Flags passed to `sm scan`. Default: empty (full scan).",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
       }
     },
     "invoke": {

package/versioning.md CHANGED Viewed

@@ -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