@skill-map/spec 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,318 @@
 # Spec changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- 334c51a: Document `--all` as targeted fan-out, not a global flag, in `spec/cli-contract.md`.
+
+  `--all` is valid only on verbs whose contract explicitly lists it:
+
+  - `sm plugins enable <id> | --all` and `sm plugins disable <id> | --all`.
+  - `sm job cancel <job.id> | --all` (cancels every `queued` and `running` job).
+  - `sm job submit <action> --all` and `sm job run --all`.
+
+  Unsupported `--all` usage is an operational error (exit `2`), the same as any other unknown or invalid flag.
+
+  Classification: minor — targeted fan-out semantics are additive for the listed verbs, while avoiding a global flag contract.
+
+- 3e89d8f: Audit-driven alignment pass. Multiple normative additions and a casing cleanup:
+
+  - **Extension schemas**: add `spec/schemas/extensions/{base,adapter,detector,rule,action,audit,renderer}.schema.json` (7 new files). `architecture.md` §Extension kinds now points to them and mandates manifest validation at load time. Unblocks the "contract tests for the 6 kinds" invariant.
+  - **Adapter `defaultRefreshAction`**: normatively required on every `Adapter` extension. Maps node `kind` → `actionId` and drives the UI's `🧠 prob` button. Previously mentioned only in ROADMAP (Decision #45); now part of the schema.
+  - **Triple protection for mode B**: `db-schema.md` now specifies the exact order — parse → DDL validation → prefix injection → scoped connection. Validation runs **before** the rewrite so kernel-table references are caught under their authored names.
+  - **Automatic rename heuristic**: new `db-schema.md` §Rename detection. On scan, `body_hash` match → high-confidence auto-rename with `state_*` FK migration; `frontmatter_hash` match → medium-confidence, same migration + `auto-rename-medium` issue; no match → orphan with issue. Replaces the prior "scan emits orphans, user runs `sm orphans reconcile` manually" flow.
+  - **Skill agent envelope**: `job-events.md` now mandates a synthetic `r-ext-<ts>-<hex>` run envelope (`run.started mode=external` → `job.claimed` → `job.callback.received` → `job.completed|failed` → `run.summary`) around jobs claimed by a Skill agent without entering `sm job run`. Keeps the WebSocket broadcaster contract ("every job event inside a run envelope") intact across both runner paths.
+  - **"Skill runner" → "Skill agent"**: `architecture.md` and `job-lifecycle.md` clarify that the Skill path is a peer driving adapter (alongside CLI and Server), NOT a `RunnerPort` implementation. Only `ClaudeCliRunner` and its test fake implement the port. Name was misleading; structure unchanged.
+  - **Casing**: `db-schema.md` `auto_migrate` → `autoMigrate`; `README.md` prose mention `spec-compat` → `specCompat`. Brings prose into sync with the camelCase rule already enforced by the schemas.
+  - **Coverage matrix**: new `spec/conformance/coverage.md` tracks each schema (and each non-schema normative artifact) against its conformance case. 28 schemas + 11 artifact invariants catalogued; 19 schemas and 10 artifacts flagged as missing, each with a step-blocker note. Release gate: v1.0.0 requires every row 🟢 or explicitly deferred.
+
+  Classification: minor per §Pre-1.0 (`0.Y.Z`). The new required field `defaultRefreshAction` on the Adapter kind is technically breaking — no conforming Adapter ships in the reference impl yet, so the impact is zero. Post-1.0 the same change would be major.
+
+### Patch Changes
+
+- 93ffe34: Editorial pass: remove "MVP" terminology from four prose documents.
+
+  The project shipped two competing readings of "MVP" — sometimes "`v0.5.0`", sometimes "the whole product through `v1.0`". That drift produced contradictions in companion docs (e.g. the summarizer pattern: was `v0.8.0` or `v0.5.0` supposed to ship them?). To close the ambiguity once, `ROADMAP.md` and `AGENTS.md` standardised on explicit versioned releases and `post-v1.0` in the same audit window. This change brings the four spec prose touches that still said "MVP" into the same vocabulary.
+
+  - **`cli-contract.md` §Jobs**: `sm job run --all` description `(MVP: sequential)` → `(sequential through v1.0; in-runner parallelism deferred)`.
+  - **`job-events.md` §Event catalog**: `(post-MVP)` parallel-run note → `(deferred to post-v1.0)`.
+  - **`job-lifecycle.md` §Concurrency**: `MVP (v0.x): one job at a time.` → `Through v1.0 (spec v0.x): one job at a time.`
+  - **`plugin-kv-api.md` §Backup and retention**: `sm plugins forget <id> (post-MVP)` → `sm plugins forget <id> (deferred to post-v1.0)`.
+
+  Classification: patch. Editorial only — no schema, exit code, verb signature, or MUST/SHOULD statement changes meaning. All four replacements preserve the technical content; only the label changes from project-scoped ("MVP") to version-scoped (`v1.0`), which is the convention the rest of the spec already uses. Integrity block regenerated.
+
+## 0.3.0
+
+### Minor Changes
+
+- 334c51a: Promote `--all` to a normative universal flag in `spec/cli-contract.md §Global flags`.
+
+  Any verb that accepts a target identifier (`-n <node.path>`, `<job.id>`, `<plugin.id>`) MUST accept `--all` as "apply to every eligible target matching the verb's preconditions". Mutually exclusive with a positional target or `-n <path>` on the same invocation. Verbs that inherently target everything (`sm scan` without `-n`, `sm list`, `sm check`, `sm doctor`) accept the flag as a no-op for script-composition uniformity. Verbs where fan-out is nonsensical (`sm record`, `sm init`, `sm version`, `sm help`, `sm config get/set/reset/show`, `sm db *`, `sm serve`) MUST reject `--all` with exit `2`.
+
+  Concretely extended in this pass:
+
+  - `sm plugins enable <id> | --all` and `sm plugins disable <id> | --all`.
+  - `sm job cancel <job.id> | --all` (cancels every `queued` and `running` job).
+
+  Already normative before this change: `sm job submit <action> --all` and `sm job run --all`.
+
+  Classification: minor — new global flag semantics, backward compatible (existing invocations without `--all` behave identically). ROADMAP Decision #60 stays as the canonical narrative; this changeset brings the spec into line with it.
+
+- 3e89d8f: Audit-driven alignment pass. Multiple normative additions and a casing cleanup:
+
+  - **Extension schemas**: add `spec/schemas/extensions/{base,adapter,detector,rule,action,audit,renderer}.schema.json` (7 new files). `architecture.md` §Extension kinds now points to them and mandates manifest validation at load time. Unblocks the "contract tests for the 6 kinds" invariant.
+  - **Adapter `defaultRefreshAction`**: normatively required on every `Adapter` extension. Maps node `kind` → `actionId` and drives the UI's `🧠 prob` button. Previously mentioned only in ROADMAP (Decision #45); now part of the schema.
+  - **Triple protection for mode B**: `db-schema.md` now specifies the exact order — parse → DDL validation → prefix injection → scoped connection. Validation runs **before** the rewrite so kernel-table references are caught under their authored names.
+  - **Automatic rename heuristic**: new `db-schema.md` §Rename detection. On scan, `body_hash` match → high-confidence auto-rename with `state_*` FK migration; `frontmatter_hash` match → medium-confidence, same migration + `auto-rename-medium` issue; no match → orphan with issue. Replaces the prior "scan emits orphans, user runs `sm orphans reconcile` manually" flow.
+  - **Skill agent envelope**: `job-events.md` now mandates a synthetic `r-ext-<ts>-<hex>` run envelope (`run.started mode=external` → `job.claimed` → `job.callback.received` → `job.completed|failed` → `run.summary`) around jobs claimed by a Skill agent without entering `sm job run`. Keeps the WebSocket broadcaster contract ("every job event inside a run envelope") intact across both runner paths.
+  - **"Skill runner" → "Skill agent"**: `architecture.md` and `job-lifecycle.md` clarify that the Skill path is a peer driving adapter (alongside CLI and Server), NOT a `RunnerPort` implementation. Only `ClaudeCliRunner` and its test fake implement the port. Name was misleading; structure unchanged.
+  - **Casing**: `db-schema.md` `auto_migrate` → `autoMigrate`; `README.md` prose mention `spec-compat` → `specCompat`. Brings prose into sync with the camelCase rule already enforced by the schemas.
+  - **Coverage matrix**: new `spec/conformance/coverage.md` tracks each schema (and each non-schema normative artifact) against its conformance case. 28 schemas + 11 artifact invariants catalogued; 19 schemas and 10 artifacts flagged as missing, each with a step-blocker note. Release gate: v1.0.0 cut requires every row 🟢 or explicitly deferred.
+
+  Classification: minor per §Pre-1.0 (`0.Y.Z`). The new required field `defaultRefreshAction` on the Adapter kind is technically breaking — no conforming Adapter ships in the reference impl yet, so the impact is zero. Post-1.0 the same change would be major.
+
+- d41b9ae: Close two gaps surfaced in the audit pass: config keys that `ROADMAP.md` promised but `project-config.schema.json` did not declare, and WebSocket event families that `ROADMAP.md §UI` mentioned ("scan updates + issue changes") but `job-events.md` did not cover.
+
+  **`project-config.schema.json` — new optional fields, all non-breaking:**
+
+  - `autoMigrate: boolean` (default `true`) — auto-apply pending kernel + plugin migrations at startup after auto-backup. `false` → startup fails fast if migrations are pending.
+  - `tokenizer: string` (default `cl100k_base`) — name of the offline tokenizer; stored alongside counts so consumers know which encoder produced them.
+  - `scan.maxFileSizeBytes: integer` (default `1048576`) — files larger are skipped with an `info` log.
+  - `jobs.ttlSeconds: integer` (default `3600`) — global fallback TTL when an action manifest omits `expectedDurationSeconds` (typically `mode: local` actions where the field is advisory).
+  - `jobs.perActionPriority: { <actionId>: integer }` — per-action priority overrides. Frozen on `state_jobs.priority` at submit time; overrides action manifest `defaultPriority`; overridden by CLI `--priority`. Ratifies decision #40a in the schema.
+  - `jobs.retention: { completed, failed }` — GC policy for `state_jobs` rows. Defaults: `completed = 2592000` (30 days), `failed = null` (never auto-prune; keep for post-mortem). `sm job prune` reads these; no implicit pruning during normal verbs.
+
+  **`job-events.md` — new `Non-job events` section, Stability: experimental across v0.x:**
+
+  - `scan.*`: `scan.started`, `scan.progress` (throttled ≥250 ms), `scan.completed`.
+  - `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.
+
+  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.
+
+- d41b9ae: Align the frontmatter tools story with Claude Code's own conventions (the audit pass surfaced that the spec had `tools` on agent only and no equivalent for skills, while `ROADMAP.md` decision #55 referenced a non-existent `expected-tools` field).
+
+  **`spec/schemas/frontmatter/base.schema.json` — two new top-level optional fields:**
+
+  - `tools: string[]` — **allowlist**. When present, the host MUST restrict the node to exactly these tools. Matches Claude Code's subagent `tools` frontmatter. Kind-specific interpretation: an `agent` uses it to lock the spawned subagent; a `skill` uses it as a declarative hint (skills typically inherit their parent's tools, but the field is carried for parity and discovery); other kinds use it as information only.
+  - `allowedTools: string[]` — **pre-approval**. Tools the host MAY use without per-use permission prompts while the node is active. Distinct from `tools`: every other tool remains callable, governed by the host's normal permission settings. Matches Claude Code's skill `allowed-tools` frontmatter. Accepts argument-scoped patterns where the host supports them (e.g. `Bash(git add *)`).
+
+  **`spec/schemas/frontmatter/agent.schema.json`:** `tools` removed from the kind-specific body because it now lives on `base` and is inherited via `allOf`. The agent schema's title/description updated to reflect that only `model` remains kind-specific. Consumers reading `tools` from an agent frontmatter see no behavioural change — the field is still there, just sourced from `base`.
+
+  `expectedTools` on `extensions/action.schema.json` is unchanged. That field is a hint from an action template to the runner (which tools the rendered prompt expects access to) — a distinct semantics from the node-level `tools` / `allowedTools` pair, and the name difference preserves the distinction.
+
+  Classification: minor per §Pre-1.0. Additions to `base` are optional fields in a permissive schema (no break for existing frontmatter). Removing `tools` from the agent schema's own properties is compatible because `allOf: [base]` continues to supply it — any document that validated before still validates, any document that used `additionalProperties: true` is unaffected. Matching `ROADMAP.md` updates (§Frontmatter standard, decision #55) land in the same change.
+
+- 5935948: Add `sm history stats` schema and normative elapsed-time reporting.
+
+  - **New schema** `spec/schemas/history-stats.schema.json`. Shape for `sm history stats --json`: `range` (configurable via `--since` / `--until`), `totals`, `tokensPerAction[]`, `executionsPerPeriod[]` (granularity via `--period day|week|month`, default `month`), `topNodes[]` (length via `--top N`, default 10), `errorRates` (global + per-action + per failure reason — all failure-reason enum values always present with `0` when unseen for predictable dashboards), and top-level `elapsedMs`. Duration stats in `tokensPerAction[]`: `durationMsMean` + `durationMsMedian` for MVP; percentiles deferred to a later minor bump.
+  - **cli-contract.md §Elapsed time** (new normative section). Every verb that does non-trivial work MUST report its own wall-clock:
+    - **Pretty (stderr)**: last line `done in <formatted>` where `<formatted>` ∈ `{ <N>ms | <N.N>s | <M>m <S>s }`. Suppressed by `--quiet`.
+    - **JSON stdout**: top-level `elapsedMs` when the shape is an object; schemas whose shape is an array or ndjson don't carry it (stderr is the sole carrier).
+    - **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).
+
+  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.
+
+- 1455cb1: Normative `priority` for jobs.
+
+  The `state_jobs.priority` column (INTEGER, default `0`) existed in the schema and was used by the atomic-claim SQL (`ORDER BY priority DESC, createdAt ASC`), but no surface let the user set it. This release closes the gap:
+
+  - **`cli-contract.md` §Jobs**: new flag `sm job submit ... --priority <n>`. Integer; higher runs first; default `0`; negatives permitted (deprioritize).
+  - **`job-lifecycle.md` §Submit**: new step 6 resolving priority with precedence `action manifest defaultPriority → user config jobs.perActionPriority.<actionId> → flag`. The resolved value is frozen on submit and immutable for the life of the job. Ties in the claim order break by `createdAt ASC`.
+  - Configuration key `jobs.perActionPriority.<actionId>`: optional per-action integer override.
+  - Action manifest `defaultPriority`: optional integer; defaults to `0` when omitted.
+
+  Classification: minor per `cli-contract.md` §Stability ("adding a flag is a minor bump"). No existing consumer breaks: jobs submitted before this release default to `0`, which is the identity element of the ordering. The claim SQL already read `priority`, so the wire protocol is unchanged.
+
+- 1455cb1: Manifest alignment pass on `spec/index.json`: expose already-normative schemas, rename the payload-shape field, and add a stable version field consumers can rely on.
+
+  - **Rename `specVersion` → `indexPayloadVersion`** (breaking). The old name collided semantically with every other use of `specVersion` (compat logic in `versioning.md`, `scan-result.specVersion`, `sm help --format json`). The field describes the shape of `index.json` itself, not the spec a caller implements.
+  - **New `specPackageVersion`** top-level field, auto-populated by `scripts/build-spec-index.mjs` from `spec/package.json.version`. This is the source of truth for "which `@skill-map/spec` release is this", previously missing from the manifest — consumers had to read `package.json` separately, and `sm version` was incorrectly reporting the payload-shape version as the spec version.
+  - **`schemas.topLevel`** gains `history-stats` (shape for `sm history stats --json`, already referenced in `cli-contract.md` §History).
+  - **New `schemas.extensions` subsection** lists the 7 kind-manifest schemas (`base`, `adapter`, `detector`, `rule`, `action`, `audit`, `renderer`) already required by `architecture.md` §Extension kinds for load-time manifest validation.
+  - **CHANGELOG fix** on the `[Unreleased]` v0.1.0 line: "10 event types" → "11 canonical event types plus one synthetic `emitter.error`". Text-only correction on a shipped release.
+  - **README example** updated to show both fields side-by-side so the distinction is obvious to first-time consumers.
+  - **Integrity block** regenerated.
+
+  No schema contents change. The schema files and their normative status are unchanged since 0.1.0; the index now enumerates them all and uses unambiguous field names.
+
+  **Migration for consumers**: any caller that reads `specIndex.specVersion` MUST switch to `specIndex.specPackageVersion` (for the release) or `specIndex.indexPayloadVersion` (for the manifest shape). The rename is the source of the `minor` bump rather than `patch` — pre-1.0 minors MAY contain breaking changes per `versioning.md` §Pre-1.0.
+
+  Classification: minor per §Pre-1.0. One breaking rename + two additive fields + two additive schema subsections. The reference impl's `sm version` is updated in the same release to read `specPackageVersion`, so `sm version` now reports the actual npm package version (was the payload-shape version, a latent bug).
+
+- 1455cb1: New CLI verb `sm orphans undo-rename <new.path> [--force]` to reverse a medium-confidence auto-rename.
+
+  The scan's rename heuristic (added in the previous spec release) migrates `state_*` FKs automatically when a deleted path and a newly-seen path share the same `frontmatter_hash` ("medium" confidence, body differs) and emits an `auto-rename-medium` issue for the user to verify. Until now the spec said "revert via `sm orphans reconcile --to <old.path>`", but `sm orphans reconcile` is defined for the forward direction (orphan path → live node) and awkward for the reverse case where both paths exist.
+
+  This release closes the gap with a dedicated reverse verb:
+
+  - **`cli-contract.md` §Browse**: new row `sm orphans undo-rename <new.path> [--force]`. Requires an active `auto-rename-medium` or `auto-rename-ambiguous` issue targeting `<new.path>`. Reads the prior path from `issue.data_json.from`, migrates `state_*` FKs back, resolves the issue. Exit `5` if no matching active issue.
+  - **`db-schema.md` §Rename detection**: issue payload now normative.
+    - `auto-rename-medium.data_json` MUST include `{ from, to, confidence: "medium" }`.
+    - `auto-rename-ambiguous.data_json` MUST include `{ to, candidates: [from_a, from_b, ...] }`. `sm orphans undo-rename` requires `--from <old.path>` to pick one.
+  - **Destructive verb**: prompts for confirmation unless `--force`. After undo, the prior path becomes an `orphan` (file no longer exists), emitting the normal `orphan` issue on next scan.
+
+  Rationale: dedicated name makes intent clear (forward = reconcile, reverse = undo-rename), failure is early (no active issue → immediate exit 5 with a helpful message), and the user does not re-type paths the kernel already knows.
+
+  Classification: minor per `cli-contract.md` §Stability ("adding a verb is a minor bump"). No existing behavior changes; `sm orphans reconcile` semantics are unaffected.
+
+- 334c51a: **Breaking**: rename two state-zone tables to comply with the normative plural rule in `db-schema.md §Naming conventions`.
+
+  - `state_enrichment` → `state_enrichments`
+  - `state_plugin_kv` → `state_plugin_kvs`
+
+  Index names renamed in lockstep:
+
+  - `ix_state_enrichment_stale_after` → `ix_state_enrichments_stale_after`
+  - `ix_state_plugin_kv_plugin_id` → `ix_state_plugin_kvs_plugin_id`
+
+  The two tables were the only kernel-owned state-zone tables violating the rule "Tables: `snake_case`, plural" — every other catalog entry (`state_jobs`, `state_executions`, `state_summaries`, `config_plugins`, `config_preferences`, `config_schema_versions`, `scan_nodes`, `scan_links`, `scan_issues`) was already plural. The exceptions were historical drift, not intentional.
+
+  Updated spec artefacts:
+
+  - `spec/db-schema.md` — table section headings, column comments, primary-key footers, index names, and the cross-reference list in §Rename heuristic.
+  - `spec/cli-contract.md` — `sm db reset --state` row in §Database.
+  - `spec/plugin-kv-api.md` — §Overview opener and every downstream reference.
+  - `spec/schemas/plugins-registry.schema.json` — description of the `kv` mode `const`.
+
+  **Migration for implementations**: no reference implementation has shipped the SQLite adapter yet (Step 1a lands it), so this is a rename-on-paper change. Any future kernel migration that creates these tables MUST use the plural names. Any third-party implementation already experimenting with the spec against the old names MUST rename before targeting `@skill-map/spec ≥ 0.3.0`.
+
+  Classification: **minor with breaking change**, per `spec/versioning.md §Pre-1.0` which allows breaking changes on minor bumps while the spec is `0.y.z`. Reference-impl touch: `src/kernel/ports/plugin-loader.ts` comment updated; no code paths read these names at runtime yet.
+
+  Companion prose updates in `ROADMAP.md` (§Persistence, §Plugin system, §Enrichment, §Summarizer pattern, Decision #61) and `AGENTS.md` (§Persistence).
+
+- 93ffe34: Clean up `history.*` in `spec/schemas/project-config.schema.json`.
+
+  **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.
+
+  **Editorial:**
+
+  - `history.share.description` mentioned `./.skill-map/history.json` — an artefact of the pre-SQLite architecture. The actual DB is `./.skill-map/skill-map.db` (see `db-schema.md` §Scope and location). Description corrected; field itself unchanged.
+
+  Classification: minor per §Pre-1.0 (`0.Y.Z` may contain breaking changes in a minor bump). Integrity block regenerated via `npm run spec:index`. Companion prose in `ROADMAP.md §Notable config keys` updated in the same change.
+
+  **Migration for consumers**: any `.skill-map.json` that set `history.retentionDays` will now fail schema validation (`additionalProperties: false` on `history`). Remove the key; no kernel behaviour changes because nothing was consuming it.
+
+- 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).
+
+  Added under `architecture.md §Extension kinds`, paralleling the existing `Adapter · defaultRefreshAction` subsection:
+
+  - **Detector · trigger normalization** — field contract, normative 6-step pipeline, and 8 worked examples.
+
+  Pipeline (applied in exactly this order):
+
+  1. Unicode NFD.
+  2. Strip Unicode `Mn` (diacritics).
+  3. Lowercase (locale-independent).
+  4. Separator unification: hyphen / underscore / any whitespace run → single ASCII space.
+  5. Collapse whitespace (run of ≥2 spaces → 1 space).
+  6. Trim leading/trailing whitespace.
+
+  Non-letter / non-digit characters outside the separator set (`/`, `@`, `:`, `.`, etc.) are **preserved** — stripping them is the detector's concern, not the normalizer's. This keeps namespaced invocations (`/skill-map:explore`, `@my-plugin/foo`) comparable in their intended form.
+
+  §Stability in `architecture.md` updated: adding a new step at the end is a minor bump; reordering, removing, or changing any existing step (including the character classes in step 4) is a major bump. Implementations that produce different `normalizedTrigger` output for equivalent input are non-conforming.
+
+  Classification: minor. The pipeline was always the intent (Decision #21 existed since the 2026-04-19 session) and `schemas/link.schema.json` already carried the fields, but this is the first time the spec prose binds implementations to a specific algorithm. A strict v0 implementation that did not normalize (or normalized differently) would begin failing conformance at the next spec release; worth a minor bump so plugin authors and alternative impls see it in the changelog.
+
+  Companion prose in `ROADMAP.md §Trigger normalization` (Decision #21 now points here for full rationale + examples).
+
+### Patch Changes
+
+- 334c51a: Clarify `sm orphans undo-rename` signature in `spec/cli-contract.md §Browse` by surfacing the `[--from <old.path>]` flag in the command cell itself.
+
+  The flag was already documented prose-only in `spec/db-schema.md §Rename heuristic` ("`auto-rename-ambiguous` issues ... `sm orphans undo-rename` requires the user to pass `--from <old.path>` to disambiguate") but was absent from the signature in the `cli-contract.md` table. A reader consulting only the CLI contract would miss the flag and assume the command took `<new.path>` alone.
+
+  The row now:
+
+  - Shows `[--from <old.path>] [--force]` in the signature.
+  - Explicitly distinguishes the `auto-rename-medium` case (omit `--from`, previous path read from `issue.data_json`) from `auto-rename-ambiguous` (REQUIRES `--from` to pick from `data_json.candidates`).
+  - Adds an exit-`5` condition for `--from` referencing a path not in `candidates`.
+
+  No behavioural change — the flag was already normative and implementations were already expected to support it. Classification: patch (clarifying drift between two spec prose docs, not a new capability).
+
+- 93ffe34: Split `sm db reset` into three explicit levels of destruction, each with distinct semantics.
+
+  Before: `sm db reset` dropped BOTH `scan_*` and `state_*` in one command — so a user who wanted "please rescan from scratch" would wipe their job history, summaries, enrichment, and plugin KV data. The "reset" name suggested a soft operation; the behavior was aggressive.
+
+  After:
+
+  - `sm db reset` — drops `scan_*` only. Keeps `state_*` and `config_*`. Non-destructive, no prompt. Equivalent to asking for a fresh scan.
+  - `sm db reset --state` — also drops `state_*` and every `plugin_<normalized_id>_*` table (mode B) plus `state_plugin_kvs` (mode A). Keeps `config_*`. Destructive; requires confirmation unless `--yes` (or `--force`, kept as an alias).
+  - `sm db reset --hard` — deletes the DB file entirely. Keeps the plugins folder on disk. Destructive; requires confirmation unless `--yes`.
+
+  Updated files:
+
+  - `spec/cli-contract.md` §Database — new table rows and a rewritten confirmation paragraph.
+  - `spec/db-schema.md` §Zones — one-liner rewritten to list all three levels.
+  - `spec/plugin-kv-api.md` §Scope and lifecycle — three bullets replacing the single prior bullet, explicit about which reset level touches plugin storage.
+
+  Classification: patch in intent but **behavior-changing for `sm db reset` without modifier**. Implementations of `v0.x` that currently drop `state_*` on `sm db reset` MUST narrow the behavior; users relying on the old "reset = wipe everything below config" workflow must switch to `sm db reset --state`. Classified as patch because the spec is pre-1.0 and no implementation has shipped the CLI yet (Step 1a lands storage + the `sm db *` verbs together — this is the first time the boundary is normative in code).
+
+  Companion prose updates in `ROADMAP.md` §DB management commands and §Step 1a acceptance list.
+
+- 93ffe34: Editorial pass: remove "MVP" terminology from four prose documents.
+
+  The project shipped two competing readings of "MVP" — sometimes "CUT 1 / `v0.5.0`", sometimes "the whole product through `v1.0`". That drift produced contradictions in companion docs (e.g. the summarizer pattern: was `v0.8.0` or `v0.5.0` supposed to ship them?). To close the ambiguity once, `ROADMAP.md` and `AGENTS.md` standardised on `CUT 1` / `CUT 2` / `CUT 3` and `post-v1.0` in the same audit window. This change brings the four spec prose touches that still said "MVP" into the same vocabulary.
+
+  - **`cli-contract.md` §Jobs**: `sm job run --all` description `(MVP: sequential)` → `(sequential through v1.0; in-runner parallelism deferred)`.
+  - **`job-events.md` §Event catalog**: `(post-MVP)` parallel-run note → `(deferred to post-v1.0)`.
+  - **`job-lifecycle.md` §Concurrency**: `MVP (v0.x): one job at a time.` → `Through v1.0 (spec v0.x): one job at a time.`
+  - **`plugin-kv-api.md` §Backup and retention**: `sm plugins forget <id> (post-MVP)` → `sm plugins forget <id> (deferred to post-v1.0)`.
+
+  Classification: patch. Editorial only — no schema, exit code, verb signature, or MUST/SHOULD statement changes meaning. All four replacements preserve the technical content; only the label changes from project-scoped ("MVP") to version-scoped (`v1.0`), which is the convention the rest of the spec already uses. Integrity block regenerated.
+
+- 93ffe34: Refresh the `spec/README.md` §Repo layout tree so it matches reality.
+
+  The previous tree was frozen at the Step 0a snapshot and listed only 20 schemas (9 top-level + 6 frontmatter + 5 summaries) plus outdated `(Step 0a phase N)` annotations. The actual spec ships 29 schemas (11 top-level + 7 extension + 6 frontmatter + 5 summaries) and the package adds `index.json` and `package.json`.
+
+  Changes:
+
+  - Show the full set of 29 JSON Schemas with a brace grouping per bucket, making the counts and the `allOf` inheritance (frontmatter kinds → base; summaries → report-base) legible at a glance.
+  - Add the missing top-level schemas `conformance-case.schema.json` and `history-stats.schema.json`.
+  - Add the whole `schemas/extensions/` folder (base + one per extension kind) — validated at plugin load.
+  - List `package.json` and `index.json` explicitly so external readers know they are published assets.
+  - Drop `(Step 0a phase N)` annotations — Step 0a is complete, the marker is noise.
+  - Under `conformance/cases/`, note `basic-scan` and `kernel-empty-boot` as the two shipped cases and point at `../ROADMAP.md` for the deferred `preamble-bitwise-match` case.
+  - Under `interfaces/`, clarify that `security-scanner.md` is a convention over the Action kind, NOT a 7th extension kind — the six kinds remain locked.
+
+  Classification: patch. Editorial prose only — no normative schema, rule, or contract changes. Companion updates to `ROADMAP.md` (repo layout + package layout) ship alongside; they are outside the spec package and do not need a changeset.
+
+- d41b9ae: Promote the casing rule from implicit (stated only in `CHANGELOG.md` §Conventions locked and in individual schema descriptions) to explicit, with a new **Naming conventions** section in `spec/README.md`. Two rules, both normative:
+
+  - **Filesystem artefacts in kebab-case**: every file, directory, enum value, and `issue.ruleId` value. Values stay URL/filename/log-key safe without escaping.
+  - **JSON content in camelCase**: every key in schemas, frontmatter, configs, manifests, job records, reports, event payloads, API responses. The SQL layer (`snake_case`) is the sole exception, bridged by the storage adapter.
+
+  Companion alignment in `spec/db-schema.md` §Rename detection: the prose mixed column names (`body_hash`, `frontmatter_hash`, `rule_id`, `data_json`) with domain-object references. The heuristic is specified against the domain types (`bodyHash`, `frontmatterHash`, `ruleId`, `data`) as defined in `node.schema.json` / `issue.schema.json`; the SQLite columns are the storage shape, not the contract. Added a one-line casing note that points back to §Naming conventions so the bridge is explicit.
+
+  Classification: patch. The rule itself is unchanged — it was already enforced by every shipped schema and repeated in `CHANGELOG.md`. The additions are purely documentary so new implementers find the rule without digging through the changelog, and so the rename-detection prose stops looking like it references SQLite-specific identifiers when it means domain-object fields.
+
+- 93ffe34: Clarify the TTL resolution procedure in `spec/job-lifecycle.md`.
+
+  The previous text defined the formula as `ttlSeconds = max(expectedDurationSeconds × graceMultiplier, minimumTtlSeconds)` and said the precedence chain was `global default → manifest → user config → flag`. Two problems:
+
+  - When `expectedDurationSeconds` is absent from the manifest (typical for `mode: local` actions), the formula is undefined. The existing config key `jobs.ttlSeconds` was documented elsewhere as a "global fallback" but never tied into the formula.
+  - The word "precedence" collapsed three distinct mechanisms — base value selection, formula application, and full override — into one list, so `minimumTtlSeconds` (a floor, never a default) appeared as the first entry of a "later wins" chain.
+
+  This patch rewrites the §TTL precedence section as §TTL resolution, split into three explicit steps:
+
+  1. **Base duration**: manifest `expectedDurationSeconds` OR config `jobs.ttlSeconds` (default `3600`).
+  2. **Computed TTL**: `max(base × graceMultiplier, minimumTtlSeconds)`.
+  3. **Overrides** (later wins, skips formula): `jobs.perActionTtl.<actionId>`, then `--ttl` flag.
+
+  Five worked examples added. Negative / zero overrides are rejected at submit time (exit 2). A Stability note states the procedure is locked going forward — new override sources are minor, formula-shape changes are major. The §Submit checklist step 5 now references the new §TTL resolution section instead of inlining a broken one-liner.
+
+  Classification: patch. No field or schema changed. Every existing manifest and config combination resolves to the same TTL except for the previously-undefined case (manifest without `expectedDurationSeconds`), which was silently implementation-defined; the new text makes the `jobs.ttlSeconds` fallback normative. Companion prose updates land in `ROADMAP.md §TTL per action` and §Notable config keys.
+
 ## 0.2.1
 
 ### Patch Changes
@@ -74,6 +387,12 @@ Tag convention: `spec-vX.Y.Z` (distinct from CLI tags `cli-vX.Y.Z`).
 
 Initial public spec bootstrap (Step 0a phases 1–3).
 
+### Changed
+
+- `cli-contract.md`: `--all` is no longer a global flag. It is valid only on verbs that explicitly document fan-out semantics: `sm job submit`, `sm job run`, `sm job cancel`, and `sm plugins enable/disable`.
+- `job-events.md`: the common `runId` envelope now explicitly documents the optional mode segment (`r-<mode>-YYYYMMDD-HHMMSS-XXXX`) used by external Skill claims, scan runs, and standalone issue recomputations.
+- `versioning.md` and related prose: replace ambiguous milestone terminology with explicit versioned release language.
+
 ### Added
 
 - Foundation:
@@ -88,7 +407,7 @@ Initial public spec bootstrap (Step 0a phases 1–3).
   - `architecture.md` — hexagonal ports & adapters; 5 ports (`StoragePort`, `FilesystemPort`, `PluginLoaderPort`, `RunnerPort`, `ProgressEmitterPort`); 6 extension kinds (Adapter, Detector, Rule, Action, Audit, Renderer); kernel boundary + forbidden/permitted imports.
   - `cli-contract.md` — CLI surface: global flags, env vars, 30+ verbs (`sm init`, `sm scan`, `sm list`, `sm show`, `sm check`, `sm findings`, `sm graph`, `sm export`, `sm job *`, `sm record`, `sm history`, `sm plugins *`, `sm audit *`, `sm db *`, `sm serve`, `sm help`), exit codes (0–5 defined, 6–15 reserved), `--json` output rules, `--format json|md|human` introspection.
   - `dispatch-lifecycle.md` — job state machine (queued → running → completed | failed), atomic claim (`UPDATE ... RETURNING id`), duplicate prevention via `contentHash`, TTL with auto-reap, nonce authentication for `sm record`, sequential concurrency for MVP, retention and GC.
-  - `job-events.md` — canonical event stream: envelope (`type`, `timestamp`, `runId`, `jobId`, `data`), 10 event types (`run.started`, `run.reap.started`, `run.reap.completed`, `job.claimed`, `job.skipped`, `job.spawning`, `model.delta`, `job.callback.received`, `job.completed`, `job.failed`, `run.summary`), three output adapters (`pretty`, `stream-output`, `json`), ordering rules.
+  - `job-events.md` — canonical event stream: envelope (`type`, `timestamp`, `runId`, `jobId`, `data`), 11 canonical event types (`run.started`, `run.reap.started`, `run.reap.completed`, `job.claimed`, `job.skipped`, `job.spawning`, `model.delta`, `job.callback.received`, `job.completed`, `job.failed`, `run.summary`) plus one synthetic error event (`emitter.error`, emitted only on serialization failure), three output adapters (`pretty`, `stream-output`, `json`), ordering rules.
   - `prompt-preamble.md` — verbatim normative preamble text that the kernel prepends to every rendered job file; `<user-content id="...">` delimiter contract with zero-width-space escaping; `safety` + `confidence` contract on model output; conformance fixture at `conformance/fixtures/preamble-v1.txt`.
   - `db-schema.md` — engine-agnostic table catalog: three zones (`scan_*`, `state_*`, `config_*`), naming conventions (snake*case, zone prefix, `_at` / `_ms` / `_hash` / `_json` / `_count` suffixes, `is*`/`has\_` prefixes), kernel table list per zone, migration rules (`.sql`files,`NNN_snake_case.sql`, up-only, auto-backup), plugin storage modes.
   - `plugin-kv-api.md` — `ctx.store` contract for mode A (`KvStore.get/set/delete/list`, plugin-scoped, optional node-scoped), mode B dedicated-tables rules (prefix injection, DDL validation, scoped Database wrapper), typed errors (`KvKeyInvalidError`, `KvValueNotSerializableError`, `KvValueTooLargeError`, `KvOperationFailedError`, `ScopedDbViolationError`). Mixing modes in a plugin is forbidden.
@@ -99,7 +418,7 @@ Initial public spec bootstrap (Step 0a phases 1–3).
 
 - JSON Schema dialect: draft 2020-12.
 - Casing: camelCase for all JSON keys (domain, configs, manifests, reports); kebab-case for filenames.
-- `$id` scheme: `https://skill-map.dev/spec/v<major>/<path>.schema.json`. `v0` throughout pre-1.0; bumps to `v1` at the first stable cut.
+- `$id` scheme: `https://skill-map.dev/spec/v<major>/<path>.schema.json`. `v0` throughout pre-1.0; bumps to `v1` at the first stable release.
 - Identity: `node.path` (relative to scope root) is the canonical node identifier in v0. Future UUID-based `node.id` lands with write-back.
 - Required frontmatter: `name`, `description`, `metadata`, `metadata.version`.
 - Frontmatter: `additionalProperties: true` (rules handle unknown fields). Summaries: `additionalProperties: false` (strict).

package/README.md

@@ -13,7 +13,7 @@ This document is the **source of truth**. The reference implementation under `..
 - The **job contract**: lifecycle states, event stream, prompt preamble, submit/claim/record semantics.
 - The **frontmatter standard**: base fields and per-kind extensions.
 - The **summary standard**: shape of action-produced summaries per kind.
-- The **plugin manifest**: metadata, spec-compat range, storage mode, security declarations.
+- The **plugin manifest**: metadata, `specCompat` range, storage mode, security declarations.
 
 ## What this spec does not define
 
@@ -34,48 +34,76 @@ These are implementation decisions. The reference impl picks them (see `../CLAUD
 - **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.
 
+## Naming conventions
+
+Two rules govern every identifier in the spec. They are **normative**.
+
+- **Filesystem artefacts use kebab-case.** Every file and directory in `spec/` (and in any conforming implementation) — `scan-result.schema.json`, `job-lifecycle.md`, `report-base.schema.json`, `auto-rename-medium` (as an `issue.ruleId` value), `direct-override` (as a `safety.injectionType` enum value), and so on — is kebab-case lowercase. Enum values and issue rule ids follow the same convention so they can be echoed back into URLs, filenames, and log keys without escaping.
+- **JSON content uses camelCase.** Every key inside a JSON Schema, frontmatter block, config file, plugin manifest, action manifest, job record, report, event payload, or API response is camelCase: `whatItDoes`, `injectionDetected`, `expectedTools`, `conflictsWith`, `docsUrl`, `examplesUrl`, `ttlSeconds`, `runId`, `jobId`. This matches the JS/TS ecosystem the reference impl ships in and the Kysely `CamelCasePlugin` that bridges to the `snake_case` SQL layer — but the rule is spec-level, not implementation-level: an alternative implementation in any language still exposes camelCase JSON keys.
+
+The SQL persistence layer is the sole exception: tables, columns, and migration filenames use `snake_case` (see `db-schema.md`). That boundary is crossed only inside a storage adapter; nothing that leaves the kernel should ever be `snake_case`.
+
 ## Repo layout
 
 ```
-spec/
-├── README.md                   ← this file
-├── CHANGELOG.md                ← spec history (independent from CLI)
-├── versioning.md               ← evolution policy
-├── architecture.md             ← hexagonal ports & adapters                    (Step 0a phase 3)
-├── cli-contract.md             ← verbs, flags, exit codes, JSON introspection  (Step 0a phase 3)
-├── job-events.md               ← canonical event stream schema                 (Step 0a phase 3)
-├── prompt-preamble.md          ← canonical injection-mitigation preamble      (Step 0a phase 3)
-├── db-schema.md                ← table catalog (kernel-owned)                  (Step 0a phase 3)
-├── plugin-kv-api.md            ← ctx.store contract for storage mode A        (Step 0a phase 3)
-├── job-lifecycle.md       ← queued → running → completed | failed        (Step 0a phase 3)
-├── schemas/                    ← JSON Schemas (Step 0a phase 2)
-│   ├── node.schema.json
-│   ├── link.schema.json
-│   ├── issue.schema.json
-│   ├── scan-result.schema.json
-│   ├── execution-record.schema.json
-│   ├── project-config.schema.json
-│   ├── plugins-registry.schema.json
-│   ├── job.schema.json
-│   ├── report-base.schema.json
-│   ├── frontmatter/
-│   │   ├── base.schema.json
-│   │   ├── skill.schema.json
-│   │   ├── agent.schema.json
-│   │   ├── command.schema.json
-│   │   ├── hook.schema.json
-│   │   └── note.schema.json
-│   └── summaries/
-│       ├── skill.schema.json
-│       ├── agent.schema.json
-│       ├── command.schema.json
-│       ├── hook.schema.json
-│       └── note.schema.json
+spec/                              ← published as @skill-map/spec
+├── README.md                      ← this file
+├── CHANGELOG.md                   ← spec history (independent from CLI)
+├── 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
+│
+├── schemas/                       ← 29 JSON Schemas, draft 2020-12, camelCase keys
+│   ├── node.schema.json                     ┐
+│   ├── link.schema.json                     │
+│   ├── issue.schema.json                    │
+│   ├── scan-result.schema.json              │
+│   ├── execution-record.schema.json         │ 11 top-level
+│   ├── project-config.schema.json           │
+│   ├── plugins-registry.schema.json         │
+│   ├── job.schema.json                      │
+│   ├── report-base.schema.json              │
+│   ├── conformance-case.schema.json         │
+│   ├── history-stats.schema.json            ┘
+│   │
+│   ├── extensions/                          ← one per extension kind; validated at plugin load
+│   │   ├── base.schema.json                 ┐
+│   │   ├── adapter.schema.json              │
+│   │   ├── detector.schema.json             │ 7 extension schemas
+│   │   ├── rule.schema.json                 │ (base + 6 kinds)
+│   │   ├── action.schema.json               │
+│   │   ├── audit.schema.json                │
+│   │   └── renderer.schema.json             ┘
+│   │
+│   ├── frontmatter/                         ← user-authored; additionalProperties: true
+│   │   ├── base.schema.json                 ┐
+│   │   ├── skill.schema.json                │
+│   │   ├── agent.schema.json                │ 6 frontmatter schemas
+│   │   ├── command.schema.json              │ (base + 5 kinds; each kind
+│   │   ├── hook.schema.json                 │ extends base via allOf)
+│   │   └── note.schema.json                 ┘
+│   │
+│   └── summaries/                           ← kernel-controlled; additionalProperties: false
+│       ├── skill.schema.json                ┐
+│       ├── agent.schema.json                │ 5 summaries (each extends
+│       ├── command.schema.json              │ report-base via allOf)
+│       ├── hook.schema.json                 │
+│       └── note.schema.json                 ┘
+│
 ├── interfaces/
-│   └── security-scanner.md     ← contract for third-party security plugins
+│   └── security-scanner.md        ← convention over the Action kind (NOT a 7th extension kind)
 └── conformance/
-    ├── fixtures/               ← controlled MD corpora
-    └── cases/                  ← declarative test cases (JSON)
+    ├── 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)
 ```
 
 ## How to read this spec
@@ -110,7 +138,8 @@ npm i @skill-map/spec
 import specIndex from '@skill-map/spec';
 import nodeSchema from '@skill-map/spec/schemas/node.schema.json' with { type: 'json' };
 
-console.log(specIndex.specVersion);        // → "0.0.1" (payload shape version; distinct from the npm package version)
+console.log(specIndex.specPackageVersion);  // → "0.2.0" (npm package version; source of truth for `spec` in `sm version`)
+console.log(specIndex.indexPayloadVersion); // → "0.0.1" (payload shape of `index.json` itself; bumps only when this manifest's structure changes)
 console.log(specIndex.integrity.algorithm); // → "sha256"
 console.log(nodeSchema.$id);                // → "https://skill-map.dev/spec/v0/node.schema.json"
 ```

package/architecture.md

@@ -77,7 +77,7 @@ Two reference implementations:
 - `ClaudeCliRunner` — subprocess `claude -p < jobfile`.
 - `MockRunner` — deterministic fake for tests.
 
-The Skill runner does NOT implement this port: it runs inside an agent session and closes jobs via `sm record` callback. See `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`.
 
 ### `ProgressEmitterPort`
 
@@ -117,17 +117,56 @@ 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 (`spec/schemas/extensions/<kind>.schema.json`, landing with step 3 of the spec bootstrap).
+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`.
 
 | Kind | Role | Input | Output |
 |---|---|---|---|
-| **Adapter** | Recognizes a platform. Decides which files are nodes and what kind they are. | Filesystem walk results, candidate path. | `{ kind, adapter } \| null`. |
+| **Adapter** | Recognizes a platform. Decides which files are nodes and what kind they are. Declares per-kind `defaultRefreshAction` (an action id that drives the probabilistic-refresh surface). | Filesystem walk results, candidate path. | `{ kind, adapter } \| null`. |
 | **Detector** | Extracts signals from a node body. | Parsed node (frontmatter + body). | `Link[]`. |
 | **Rule** | Evaluates the graph. | Full graph (nodes + links). | `Issue[]`. |
 | **Action** | Operates on one or more nodes. Two modes: `local` (code) or `invocation-template` (LLM prompt). | Node(s), optional args. | Local: report JSON. Template: rendered prompt that a runner executes. |
 | **Audit** | Deterministic workflow that composes rules and actions. Produces a structured report. | Graph + optional scope filter. | Audit report (hardcoded shape, kind-specific). |
 | **Renderer** | Serializes the graph. | Graph + optional filter. | String (ASCII / Mermaid / DOT / JSON / user-defined). |
 
+### Adapter · `defaultRefreshAction`
+
+Every `Adapter` extension MUST declare a map `defaultRefreshAction: { <kind>: <actionId> }` covering every `kind` it emits. The referenced action MUST exist in the registry by the time the graph is queried; a dangling reference is a load-time error for the adapter. Consumers (CLI `🧠 prob` buttons in `sm show`, Web UI inspector) dispatch `sm job submit <defaultRefreshAction[kind]> -n <nodePath>` when the user asks for a probabilistic refresh on a node. Implementations MAY allow plugins to override the default per-node via `metadata.refreshAction`, but the adapter default is normative.
+
+### 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`:
+
+- `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.
+
+Both fields MUST be present whenever `link.trigger` is non-null. Implementations MUST produce byte-identical `normalizedTrigger` output for byte-identical input across platforms and locales.
+
+#### Normalization pipeline (normative)
+
+Applied in exactly this order:
+
+1. **Unicode NFD** — canonical decomposition (`String.prototype.normalize('NFD')` in JS).
+2. **Strip diacritics** — remove every code point in Unicode category `Mn` (Nonspacing_Mark).
+3. **Lowercase** — locale-independent Unicode lowercase.
+4. **Separator unification** — replace every hyphen (`-`), underscore (`_`), and run of whitespace (space, tab, newline, NBSP, …) with a single ASCII space.
+5. **Collapse whitespace** — runs of two or more spaces become one.
+6. **Trim** — strip leading and trailing whitespace.
+
+Characters outside the separator set that are not letters or digits (e.g. `/`, `@`, `:`, `.`) are **preserved**. Stripping them is the detector's concern, not the normalizer's — the normalizer operates on whatever the detector classifies as "the trigger text". This keeps namespaced invocations like `/skill-map:explore` or `@my-plugin/foo` comparable in their intended form.
+
+#### Examples
+
+| `originalTrigger` | `normalizedTrigger` |
+|---|---|
+| `Hacer Review` | `hacer review` |
+| `hacer-review` | `hacer review` |
+| `hacer_review` | `hacer review` |
+| `  hacer   review  ` | `hacer review` |
+| `Clúster` | `cluster` |
+| `/MyCommand` | `/mycommand` |
+| `@FooDetector` | `@foodetector` |
+| `skill-map:explore` | `skill map:explore` |
+
 ### Contract rules
 
 1. An extension declares its kind in its module export and its manifest. Kind mismatch → load-error.
@@ -200,7 +239,7 @@ Alternative implementations MAY use workspaces, separate packages, or a compiled
 The CLI, Server, and Skill driving adapters are **peers**. None depends on another.
 
 - The Server MUST NOT call the CLI (no `child_process.spawn('sm', ...)`).
-- The Skill runner MUST NOT depend on the Server (it can be used offline).
+- The Skill agent MUST NOT depend on the Server (it can be used offline).
 - The CLI MUST NOT embed HTTP logic.
 
 All three consume the same kernel API. Any use case a driving adapter needs MUST be available as a kernel function — if it isn't, the gap is a kernel bug, not a driving-adapter workaround.
@@ -216,3 +255,5 @@ The **port list** is stable as of spec v1.0.0. Adding a sixth port is a major bu
 The **extension kind list** (6 kinds) is stable as of spec v1.0.0. Adding a seventh kind is a major bump.
 
 The **dependency rules** above are stable as of spec v1.0.0. Relaxing any is a major bump; tightening (forbidding an allowed import) is a minor bump.
+
+The **Detector · trigger normalization** pipeline (six steps, in order) is stable from the next spec release. Adding a new step at the end is a minor bump; reordering, removing, or changing any existing step (including the character classes in step 4) is a major bump. Implementations that produce different `normalizedTrigger` output for equivalent input are non-conforming.