` block survives; replicating CommonMark's full HTML-block algorithm is out of scope. **Relative file paths are the documented exception.** The Agent Skills open standard mandates that a skill references its bundled resources by relative path and that "agents load these on demand"; prose like ``Read `references/rules.md` `` is an instruction the consuming LLM runtime follows. The `core/backtick-path` extractor surfaces exactly that class of references, ONLY inside code regions, the precise complement of the code-strip policy, so it can never collide with the prose-side extractors. The HTML strip is a separate, prose-side transform and never feeds the code-region inverse mask: HTML is not a code region, so a path inside an HTML tag is not a `points` target.
The contract:
- **Domain**: the extractor matches exclusively inside fenced code blocks and inline code spans, over the *inverse mask* of the code-strip transform: same-length text where code-region characters survive and everything else is blanked. Same-length masking keeps byte offsets and line numbers valid against the original body.
- **Token grammar** (pinned; implementations MUST match it exactly): `/(?/` pointing anywhere else in the repo (`../../ui/context/theme.md`). Capped, such a token matched at NO start position (the second `../` falls outside the prefix group, and the lookbehind refuses a later start because the preceding character is always `/` or `.`), so the reference produced neither a link nor a `reference-broken` issue. Emitting nothing at all is the worst of the available failures: a broken link is visible and actionable, an unparsed one is indistinguishable from an author who never wrote it. The `@`-token grammar had already been widened to a multi-level prefix for exactly this reason and this grammar was left behind, so the two are now pinned to the same prefix construct on purpose: two path grammars that differ without cause is how one gets fixed and the other does not. The FIRST SEGMENT accepts a leading dot as of 2026-08-08, the same failure mode one segment later: `` `.claude/minions.md` `` matched at no start position (the first-segment anchor demanded a word character, and the lookbehind refused the retry at `claude/…` because the preceding character was the dot itself), so the single most common target class in this product's domain, a path under a hidden vendor directory (`.claude/`, `.codex/`, `.agents/`, `.opencode/`), produced neither a link nor an issue, while a MID-path hidden segment (`docs/.hidden/x.md`) already matched. Exactly ONE leading dot: `..claude/x.md` and ellipsis interiors (`...x.md`) still match nowhere, because the candidate's own leading dot is preceded by another dot and the lookbehind refuses it. The `@`-token grammar (its single owner is the shared kernel util) gains the identical first-segment allowance in the same revision, keeping the two path grammars pinned to one shape. A bare filename (`algo4.md`) matches, as the consuming runtime follows it: a skill body's `lee el archivo: ` + "`algo4.md`" is an instruction the LLM resolves against the skill directory (verified empirically, every tested model reads the bare-referenced sibling), so the graph models the edge; a bare HIDDEN filename (`.env.md`) now matches by the same rule. The character classes and guards still reject, by construction: URL interiors (`https://example.com/docs/x.md` cannot match at any start position due to the lookbehind, whose refusal of a preceding word character, `/`, `:` or `.` is unchanged), template placeholders and globs (`{PROJECT}-x.md`, `*-S.md`: the leading `{` / `*` is outside the segment class AND the word-character anchor refuses the `-x.md` tail that would leak once the `/` separator became optional), near-miss suffixes (`.mdx`, `.md_var`), and absolute paths (a leading `/` fails the lookbehind). Slashless convention filenames (`SKILL.md`, `README.md`) now match too: a self-referential `SKILL.md` resolves to the node's own sibling and surfaces as a self-loop (excluded from card chips by `core/link-self-loop`), and any other unresolved bare filename is flagged by `core/reference-broken`, so the relaxed recall does not corrupt the graph.
- **Targets**: `.md` only. Markdown files are the one class with a guaranteed node on the scan side (the `core/markdown` fallback), so every resolvable token has a target to land on.
- **Resolution**: dual-base. The emitted `target` is POSIX-normalised against `dirname(node.path)` exactly like `core/markdown-link`, and the authored token rides `trigger.originalTrigger` verbatim (prefix included); the post-walk lift then applies the root fallback of §Provider · resolution rules rule 1, trying the token normalised against the scan root, when the file-relative candidate matches no node, UNLESS the token carries an explicit `./` / `../` prefix (declared file-relative intent, never falls back). Per-node dedup on the file-relative resolved target, first occurrence wins.
- **Emission**: one single-candidate Signal per distinct resolved target, `kind: 'points'` (the code-region path pointer kind, distinct from `references` so the two surfaces stay separable), confidence `0.85` (same value and rationale as a path-style at-directive: a strong file signal with one degree of inference, the author wrote a path but not explicit link syntax), with the Signal's `context` field set to `'inline-code'` (span) or `'code-block'` (fence) exactly like the trigger siblings (§code-region triggers). The stamp is what lets `core/link-self-loop`'s usage-example exemption see a backticked self-reference (a `SKILL.md` naming its own sibling) as code-region provenance; it does NOT feed the trigger resolution gate, which stays kind-gated to `mentions` / `invokes`, so an unresolved `points` path keeps flagging `core/reference-broken`. The candidate's `normalizedTrigger` is the resolved target so resolution and the confidence lift behave exactly like `markdown-link`. A prose `[x](references/a.md)` (`references`) and a backticked `` `references/a.md` `` (`points`) targeting the same file COEXIST as two Link rows: post-resolver dedup keys on `kind` so the rows never merge, and `core/link-kind-conflict` excludes `points` from disagreement detection (two complementary authoring surfaces, not two detectors disputing one meaning).
- **Unresolved targets are NOT suppressed.** The extractor emits unconditionally, mirroring `markdown-link`; `core/reference-broken` flags targets that resolve to no node AND no on-disk file (§Provider · resolution rules, rule 3). Deliberate: a backticked path pointing at a deleted or misspelled bundled doc is a real authoring bug (the standard's progressive disclosure breaks at runtime). Out-of-scope paths the consuming runtime resolves against a different root (a target workspace, a generated tree) are silenced through the existing `scan.referencePaths` escape hatch, not by weakening the extractor.
A path written in prose without any wrapping (neither backticks nor markdown-link syntax) stays invisible in this revision; the code-region domain is the verified, bounded surface.
### Extractor · code-region triggers (`claude/backtick-mention`, `core/backtick-slash`, `codex/backtick-dollar`)
The second sanctioned inversion of the code-strip policy, and a narrower one. Skill and agent authors routinely wrap an invocation in backticks as stylistic highlighting, not as quotation: prose like ``use `@reviewer` for the final pass`` or ``run `/deploy` before shipping`` is an instruction the consuming LLM follows exactly like its unwrapped form. The base rate inside code regions is, however, the opposite of the file-path case: most trigger-shaped tokens in spans and fences are code payload (npm scopes like `@changesets/cli`, decorators like `@Injectable`, shell paths like `/tmp`, CSS at-rules like `@media`), not invocations. The contract therefore pairs the extraction with a resolution gate: a code-region trigger is a HYPOTHESIS that only becomes an edge when it resolves.
Three extractors share the contract, one per trigger grammar, each the code-region sibling of an existing prose extractor:
- **`claude/backtick-mention`**: bare `@handle` mentions, `kind: 'mentions'`, confidence `0.5` (the same genuine-ambiguity value as a prose bare handle). Token grammar identical to `claude/at-directive` (the shared `@`-token grammar), including the file-shape deferral: a file-shaped token (`@foo.md`, `@./x`, `@../x`) is NOT a mention (for `.md` targets its path half already surfaces as a `points` edge via `core/backtick-path`), and an absolute `@/abs/x` is skipped entirely. The same `@` token never doubles as a mention AND a reference. The shared grammar also requires at least one letter somewhere in the token: a purely numeric `@10` / `@10/20` is prose (a score, a date), never a handle or a path, while file-shaped numerics keep matching through their extension's letters (`@10.md`). The `/`, `@`, and `$` sigil grammars carry this numeric guard as a set (the `$` grammar's lowercase-first-letter rule subsumes it). Lens-gated `claude`-only, exactly like `claude/at-directive`: a bare `@handle` is a mention grammar only under Claude; the file-picker runtimes (codex, antigravity) get no code-region mention surface.
- **`core/backtick-slash`**: `/` invocations, `kind: 'invokes'`, confidence `0.8` (the same value as the prose slash). Token grammar identical to `core/slash-command` (the shared `/`-token grammar, including the post-match path-suffix guard that rejects `/api/v1/items`-style path segments, and the at-least-one-letter identifier rule that rejects purely numeric tokens: prose like `total /10` is a fraction / denominator, not an invocation, and no real command name is all digits; digit-leading names like `/2fa-setup` keep matching). Lens-gated `claude` / `antigravity` / `opencode`, exactly like its prose sibling; codex reserves `/` for its own built-ins and gets no code-region slash surface.
- **`codex/backtick-dollar`**: `$` invocations, `kind: 'invokes'`, confidence `0.8` (the same value as the prose dollar). Token grammar identical to `codex/dollar-skill` (the shared `$`-token grammar: lowercase first letter, so uppercase env vars `$PATH` / `$HOME` and currency `$5` never match; lowercase shell variables DO match and rely on the gate). Lens-gated `codex`-only, exactly like its prose sibling.
The shared contract:
- **Domain**: exclusively inside fenced code blocks and inline code spans, over the same inverse mask `core/backtick-path` uses.
- **Emission**: one single-candidate Signal per distinct normalized trigger, with the Signal's `context` field set to `'inline-code'` (span) or `'code-block'` (fence). The materialised Link's `occurrences[]` entries carry that `context` verbatim, which is what the resolution gate keys on. Because kind and normalized trigger match the prose sibling's, a prose token and its backticked twin from the same body dedupe into ONE Link with unioned `sources`.
- **Resolution gate (normative)**: after link dedup and target resolution, a post-walk transform REMOVES every trigger-style Link (`mentions` / `invokes`) that (a) resolved to no node and (b) whose every occurrence carries a code-region `context` (`'inline-code'` or `'code-block'`). A pruned link never reaches the analyzer phase: it does not flag `core/reference-broken`, it is not persisted, it never renders. A trigger link with at least one prose occurrence (no `context`) keeps the standing behaviour: unresolved means broken, because a prose trigger is authored intent whose dangling is an authoring bug, while an unresolved code-region token is simply code payload the extractor over-read. Links with no occurrence data (synthetic emissions) are never pruned, and path-style kinds (`references`, `points`) are outside the gate entirely.
Two consumers of the same occurrence provenance soften adjacent analyzers: the resolution gate above, and `core/link-self-loop`, which SKIPS its warn on a self-loop whose every occurrence is code-region (a backticked `` `/status` `` inside the very doc that defines `/status` is the canonical usage-example authoring shape, not a loop risk; the link itself still exists and follows the standing self-loop chip / layout handling).
The known cost, accepted deliberately: a typo'd backticked trigger (`@reviewr`, `/deply`) vanishes silently instead of flagging. The post-strip discard-feedback analyzer that would close this remains deferred (`context/runtime-quirks.md` §7).
### Kernel check · frontmatter diagnostics
Three analyzer ids form the closed kernel-stamped frontmatter vocabulary: `frontmatter-parse-error` (the declared block failed to parse), `frontmatter-malformed` (the author plainly meant frontmatter but the block is structurally unusable), and `frontmatter-invalid` (the block parsed but fails the per-kind schema, §Provider · `kinds` catalog). The kernel stamps them during the walk (in `node-build`, where the raw text is still in memory), before any analyzer runs; like the backtick check below, each issue is persisted and reused per node across an incremental scan, so an unchanged file keeps its warning on a clean re-scan without touching disk. Severity is `warn`, lifted to `error` under `--strict`. The three-id set doubles as the "the kernel already validated this node's frontmatter shape" signal: `core/schema-violation` suppresses its redundant base-field check (missing `name` / `description`) when one of these already landed for the node.
Routing is normative: each node takes exactly ONE of four lanes, so a single authoring defect never stacks multiple frontmatter diagnostics.
1. **Parse error.** A parser MUST NOT throw on malformed input: it returns a usable `{ frontmatter: {}, frontmatterRaw, body }` triple so the scan keeps progressing, plus a parse issue (`code`, sanitised `message`) the orchestrator maps verbatim to a kernel Issue (`analyzerId: 'frontmatter-parse-error'`). The message interpolates only the parser-error string, never the raw input (hostile YAML could embed multi-line garbage), with control bytes stripped; the reference impl appends an actionable quoting hint when the failure matches the unquoted-colon class (`description: use when: something`), the single most common authored mistake. A parse error short-circuits every other lane: a declared block that FAILED to parse is unknown, not incomplete, so validating the `{}` fallback would report fields that ARE present in the source as "missing required property", and the fence heuristics are equally moot (a fence was found; its content is what broke). One deliberate exception: a declared but content-free block (empty, whitespace-only, comments-only) is NOT a parse error; it is legitimate YAML-nothing and routes through lane 2 so the per-kind schema pass supplies the meaningful verdict.
2. **Declared block.** Signalled by the parser's declared-block flag (`frontmatterDeclared` in the reference impl, set whenever the input declared a fence, even an empty one), with non-empty raw frontmatter text as the fallback for custom-walk Providers that never set the flag. The early-close detector runs first: a column-0 `---` line INSIDE the intended block ends it prematurely (the close is lazy, the first `---` wins), silently leaking every field below it into the body. The signature requires all of: the first body line is `key: value`-shaped; a column-0 `---` follows within a bounded scan window; the leaked segment parses as a YAML mapping; and at least one leaked top-level key is a property declared in the kind's frontmatter schema, the load-bearing false-positive gate (prose like `Note: caveats` above a horizontal rule parses as YAML too, but `Note` is not a schema property while a leaked `tools:` or `description:` is). A hit emits `frontmatter-malformed` with `data: { hint: 'early-close', leakedKeys }` and SUPPRESSES the schema pass, whose "missing required property" would point the author away from the real defect. Otherwise the per-kind schema validation runs and a failure emits `frontmatter-invalid` carrying the validator's error string. A declared-but-EMPTY block (`---`, blank line, `---`) validates exactly like a whitespace-only one; the declared flag beats the length check so it is never conflated with "no frontmatter at all".
3. **No block, fence-shaped accident.** When no block was declared, heuristics recognise the cases where the author clearly meant frontmatter but the fence could not anchor, and the verdict names the exact authoring accident rather than its downstream symptom. Hint vocabulary (closed set, carried in `data.hint`): `paste-with-indent` (indented opening fence, the terminal-heredoc accident), `byte-order-mark` (a UTF-8 BOM before the fence; blank lines and fence indent after the BOM are tolerated so the combined accident still classifies here), `leading-blank-line` (blank lines push the fence off byte 0; tolerates an indented fence), and `missing-close` (column-0 open fence with no column-0 close, so the intended metadata parses as body). Every heuristic requires a YAML-looking `key:` line after the fence, so a horizontal rule or prose under a `---` never false-positives. `early-close` (lane 2) completes the five-hint set.
4. **Absent block.** With no block and no heuristic hit, the per-kind schema pass STILL runs, against the empty object. A kind whose schema requires fields flags the absent block as `frontmatter-invalid`, closing the asymmetry where a partial block warned about a missing `description` but a fully absent one said nothing; every all-optional kind validates `{}` clean and stays silent. This lane also covers a fence pushed off byte 0 by preceding prose no heuristic recognises: the required fields surface instead of the metadata silently parsing as body.
### Kernel check · body backtick balance
The code-strip policy (§Extractor · code-region file references) assumes every fence and every inline code span in a `.md` body is BALANCED. An unbalanced backtick breaks that assumption at the source: an opening fence with no closer makes `stripCodeBlocks` treat the entire remainder of the file as code, so every prose-side extractor (`markdown-link`, `at-directive`, `slash-command`, `external-url-counter`) sees a blank body past the dangling fence and stops emitting real edges; the code-region extractors (`backtick-path`, `backtick-mention`, `backtick-slash`, `backtick-dollar`) see the inverse corruption, the whole remainder resurrects as matchable code (over-matching bounded by the pinned grammars, the broken-target flag, and the trigger resolution gate). This is a body-syntax defect, not a frontmatter-shape one, so it is not expressible as a JSON Schema constraint.
Because the check reads the BODY, the kernel stamps it during the walk (in `node-build`), where the body is still in memory, NOT in the analyzer pass (which sees only the merged graph, the body byte size on `node.bytes.body`, not the text). The verdict is derived from the SAME fence and inline scanners `stripCodeBlocks` is built on (the shared `findBacktickImbalance` helper), so the warning can never drift from the policy it protects. Computing it where the body lives also means the file is never re-read: the issue is persisted and reused per node across an incremental scan, exactly like the kernel-stamped frontmatter diagnostics (§Kernel check · frontmatter diagnostics above), so an unchanged file keeps its warning on a clean re-scan without touching disk.
The check emits a single issue with `analyzerId: 'backtick-unbalanced'`, `nodeIds: [path]`, `data: { kind, line }` and a `detail` carrying the offending source line. The line is relative to the analysed BODY, not the file: a Provider MAY carry the body inside a frontmatter field (`bodyField`), so a file-absolute line is not universally defined; the `detail` is the concrete locator. Severity is `warn`, lifted to `error` under `--strict`, consistent with the frontmatter diagnostics it ships beside.
Two checks run in order over the body:
1. **Fenced block balance.** A line opening with three or more backticks or tildes (CommonMark fence, up to three leading spaces of indent) toggles fence state; a closer MUST use the same fence character and be at least as long as the opener. If the body ends with a fence still open, the check reports the unclosed fenced block (`kind: 'fence'`, the opening fence line) and **stops**: a dangling fence has already corrupted the mask, so the inline pass below would only produce noise.
2. **Inline span balance.** Only when every fence is balanced. After the fenced lines are blanked (line numbers preserved) and backslash-escaped characters are masked (a literal `` \` `` is text in CommonMark and never opens a span), any backtick that survives the inline-span pass has no equal-length closer per the CommonMark rule. The first survivor is reported as an unclosed inline backtick (`kind: 'inline'`).
A body with balanced fences and balanced inline spans yields no issue.
### Extractor · enrichment layer
`ctx.enrichNode(partial)` is the only writable surface the Extractor pipeline has on a node. The author's frontmatter on `scan_nodes.frontmatter_json` is read-only from any Extractor. Implementations MUST:
- Persist enrichments into a per-`(node, extractor)` table (the reference impl uses [`node_enrichments`](./db-schema.md#node_enrichments)) so attribution survives across scans.
- Preserve the author frontmatter byte-for-byte through every scan and refresh; the enrichment overlay is a SEPARATE store.
- Regenerate enrichments through the §Extractor · fine-grained scan cache contract: an unchanged body hash + same registered Extractor reuses the prior row; a changed body re-runs `extract()` and overwrites the row via the PRIMARY KEY conflict. Extractors are deterministic, so a stale-flag is unnecessary: re-running is free and reproducible.
> **Reserved columns**, `node_enrichments.is_probabilistic`, `body_hash_at_enrichment`, and `stale` are persisted but inert in this revision: every Extractor write sets `is_probabilistic = 0` and `stale = 0`, with `body_hash_at_enrichment` always equal to the current body hash. They are reserved for a future revision where Action-issued enrichments (queued probabilistic jobs writing back through the enrichment layer) need stale tracking to preserve LLM cost across body changes. Until then, readers MAY assume `stale = 0` and the merge helper's `includeStale: true` flag is a no-op.
Read-side merge (`mergeNodeWithEnrichments` in the reference impl):
1. Filter to non-stale enrichments for the target node.
2. Sort by `enriched_at` ASC.
3. Spread-merge each `value` over the author frontmatter (last-write-wins per field).
Analyzers / `sm check` / `sm export` consume `node.frontmatter` directly (deterministic CI-safe baseline); enrichment consumption is opt-in by the caller.
Refresh verbs (`sm enrich ` and `sm enrich --stale`) re-run the Extractor pipeline against a node or the stale set and upsert fresh enrichment rows, see [`cli-contract.md` §Scan](./cli-contract.md#scan). With Extractors deterministic-only, `--stale` is a no-op today (no rows are stale-flagged); it remains in the contract for the future Action-prob enrichment revision noted above.
### Extractor · `precondition` filter
Extractors MAY declare an optional `precondition` block (`{ kind?: string[]; provider?: string[] }`, the shape Analyzers and Actions share). When declared, the kernel filters fail-fast: `extract()` is invoked **only** for nodes satisfying every declared sub-filter (`kind` lists qualified `/` ids; `provider` lists plugin ids; both apply as AND). The skip happens BEFORE the extractor context is built, so the extractor wastes zero CPU on inapplicable nodes. Absent (`undefined`) is the default, meaning "applies to every kind"; there is no wildcard syntax. Unknown qualified kinds (no installed Provider declares them) are non-blocking: the extractor keeps `loaded` status and `sm plugins doctor` surfaces an informational `precondition-kind-unknown` warning so the author sees typos and missing-Provider cases, but the doctor's exit code is NOT promoted by this warning. See [`plugin-author-guide.md` §`precondition`](./plugin-author-guide.md#extractor--analyzer--action-precondition-narrow-the-pipeline).
### Extractor · fine-grained scan cache
Implementations MAY maintain a per-`(node, extractor)` cache so that on `sm scan --changed` the orchestrator can skip rerunning an Extractor against an unchanged body when that specific Extractor already ran against the same body hash. The reference impl persists the cache in [`scan_extractor_runs`](./db-schema.md#scan_extractor_runs).
The contract the cache MUST satisfy (engine-agnostic):
- A node-level cache hit (body+frontmatter unchanged) is upgraded to a full skip ONLY when every currently-registered Extractor that applies to the node's kind has a recorded run against the prior body hash.
- A new Extractor registered between scans MUST run on the cached node, its absence from the cache is the canonical signal. The rest of the cache (existing Extractors against the same body) is preserved.
- An Extractor uninstalled between scans MUST have its cache rows removed and its sole-source links dropped. Links whose `sources` mix the uninstalled Extractor's short id with a still-cached Extractor's short id MUST be reshaped: the obsolete short id is stripped from the array and the link survives with the cached attribution intact. The persisted audit trail therefore never references a removed contributor.
- The cache key includes the canonical hash of `node.sidecar.annotations` alongside the body hash. A sidecar-only edit (`.sm` change without a `.md` change) invalidates the cached run for every Extractor that ran against that node. Universal invalidation is deliberate: an opt-in flag was rejected because forgetting it produces a silent stale-data bug, while re-running every Extractor on a `.sm` edit costs little (sidecars change rarely, Extractors are pure-CPU). The hash uses a deterministic canonical form so a YAML re-format that does not change annotation values does not invalidate the cache.
- The cache is otherwise transparent to plugin authors. An Extractor cannot opt out and cannot inspect the cache; its only obligation is to be deterministic for a given input (structural: every Extractor is deterministic-only, by spec).
The invariant keeps `sm scan --changed` cheap on real corpora: re-parsing an unchanged body for an unchanged Extractor is wasted work; the cache turns it into a one-row reuse. The same machinery will let a future Action-prob enrichment revision (see §Extractor · enrichment layer) reuse paid LLM output across unchanged bodies.
### Extractor · trigger normalization
Extractors 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 extractor saw, byte-for-byte. Used only for display.
- `normalizedTrigger`, the output of the pipeline below. Used for equality and resolution: the post-walk resolver keys on this field to match a trigger-style link against node identifiers. The same normalization (applied to `frontmatter.name`) backs the built-in `name-collision` analyzer's verdict.
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 extractor's concern, not the normalizer's; the normalizer operates on whatever the extractor classifies as "the trigger text". This keeps namespaced invocations like `/skill-map:explore` or `@my-plugin/foo` comparable in 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` |
| `@FooExtractor` | `@fooextractor` |
| `skill-map:explore` | `skill map:explore` |
### Analyzer ↔ Action relationship (Modelo B)
The "which Action resolves this analyzer's findings?" relationship is declared from the **Action** side, not the Analyzer side (the `Analyzer.recommendedActions` map was retired with the structure-as-truth refactor). An Action's `precondition.analyzerIds: string[]` lists the qualified ids of the analyzers whose findings it resolves. The UI joins on this field: when an analyzer emitted against the focused node, the inspector surfaces every Action whose `precondition.analyzerIds` includes that analyzer, under "Recommended for issues", alongside the always-applicable list driven by the rest of the Action's `precondition`.
The two surfaces stay distinct: `kind` / `provider` sub-filters answer "which nodes does this Action apply to?" (evaluated continuously against the focused node); `analyzerIds` answers "when which analyzer fires is this Action the natural fix?" (surfaces only on nodes the named analyzer emitted against). Project-level cleanup verbs (orphan file prune, contribution relink) are CLI commands, not Actions, and are NOT linked through this field. Actions that resolve deliberate user declarations rather than fixable problems omit `analyzerIds`.
The join covers both analyzer modes. For a deterministic analyzer the trigger is its `Issue` rows (`scan_issues.analyzer_id`); for a probabilistic finder it is its `state_findings` rows (`extension_id`), so a fixer Action surfaces on nodes the finder judged. The built-in `core/ai-reference-action` is the reference deterministic-side fixer: its `precondition.analyzerIds: ['core/reference-broken']` name a deterministic rule, so at submit the kernel injects that rule's `scan_issues` rows into a `## Issues to resolve` section (keyed on the broken `target`, no finding id to stamp; the fix's evidence is the next scan clearing the Issue), and the processing agent repoints each broken link, but ONLY when the intended target lives INSIDE the project scan roots (a target that resolves only OUTSIDE the project is recorded `human-decision` asking the operator's permission, never searched on skill-map's initiative, honoring the project-local-only invariant, [`cli-contract.md` §Scope is always project-local](./cli-contract.md#scope-is-always-project-local)). See [`job-lifecycle.md` §Findings injection for fixers](./job-lifecycle.md#findings-injection-for-fixers) for the full deterministic-side contract. A **probabilistic fixer** composes with the pull-only execution model with no new write surface: the fix is itself a queued job whose rendered prompt instructs the PROCESSING AGENT to edit the file in its own session with its own tools, then `sm record` the outcome; skill-map never writes node bodies (§IO discipline holds), the next scan picks the edit up deterministically, and the finding goes stale via the body-hash rule. So the fix acts on exactly what the finder reported (not a re-derivation), the kernel injects the node's findings for those `analyzerIds` into the fixer's rendered job content at submit, stale rows included and flagged for the agent to verify against the current body ([`job-lifecycle.md` §Findings injection for fixers](./job-lifecycle.md#findings-injection-for-fixers)); a fixer submitted over a node with no such findings at all is refused. Deterministic fixers keep their existing channels (e.g. `writes: ['sidecar']`). **Auto-fix (opt-in)**: the finder -> fixer chain runs automatically via the PER-JOB `auto_fix` flag frozen at submit ([`job-lifecycle.md` §Auto-fix chain (per-job)](./job-lifecycle.md), the inspector's automatic toggle / `sm jobs submit --auto-fix`): on the flagged finder's completion the record path resolves the INVERSE of Modelo B (the Actions whose `precondition.analyzerIds` include the just-run finder) and submits each matching fixer through the normal fixer path. It composes with pull-only, the chain fires inside `sm record`, so the processing agent's own loop continues into the fix in one session; no findings means no queue; several matching fixers all queue; the `human-decision` state stays the safety net. A drop-in `job.completed` hook MAY additionally chain fixers via `ctx.queue` for a global always-on policy (the `core/auto-fix` built-in shipped exactly that until 2026-07-21, when it was removed as redundant with the per-job flag; the hook dispatch remains available).
The pairing also drives the **enable axis**: the toggle surface (CLI `sm plugins enable / disable` and the `PATCH /api/plugins*` routes) applies a symmetric **pair toggle** over the `analyzerIds` edges, enabling companions eagerly and disabling them under an edge reference count, so a pair never ends up half-armed (a fixer without the analyzer that feeds it, or an analyzer whose fix affordance silently vanished). Both analyzer modes participate identically; only direct edges are followed. Contract details in [`plugin-author-guide.md` §Paired extensions (pair toggle)](./plugin-author-guide.md#paired-extensions-pair-toggle).
### Hook · curated trigger set
Hooks subscribe declaratively to a curated set of kernel lifecycle events and react. Reaction-only by design: a hook cannot mutate the pipeline, block emission, or alter outputs. The hookable trigger set is intentionally small, nine events out of the full [`job-events.md`](./job-events.md) catalog. Seven are pipeline-driven (emitted from inside `runScan`); two (`boot`, `shutdown`) are CLI-process-driven (emitted by the driving binary before / after the verb runs, fire-and-forget so `process.exit` is never blocked). Other events (per-node `scan.progress`, `run.*`, `job.claimed`, `job.callback.received`) are deliberately NOT hookable: too verbose for a reactive surface, or covered elsewhere. A trigger outside the curated set yields `invalid-manifest` at load time. EVERY dispatch path honours the enabled toggle: the pipeline-driven triggers because the composed hook catalog already filters disabled extensions, and the CLI-process-driven `boot` / `shutdown` dispatcher by filtering the bundled built-in hooks against the project's layered config before dispatching; a disabled hook (e.g. `plugins.core.extensions.update-check.enabled: false`) never fires on any trigger.
| Trigger | When it fires | Payload (key fields) | Hook scope |
|---|---|---|---|
| `boot` | Once per CLI process invocation, BEFORE the verb routes. The dispatcher AWAITS subscribed hooks so anything they print lands above the verb's output (the `core/update-check` banner relies on this); a slow hook delays the first verb paint. Errors are caught so a buggy hook never prevents the verb from running, only delays it. Use sparingly. | `argv: string[]` (the routed argv slice the CLI is about to parse). | Boot-time output that must appear above the verb (the `core/update-check` banner), pre-flight checks, telemetry warm-up. |
| `scan.started` | Once at the start of every `sm scan` invocation. | `roots: string[]`. | Pre-scan setup (cache warm-up, telemetry init). |
| `scan.completed` | Once at the end of every `sm scan` invocation. | `stats: { filesWalked, nodesCount, linksCount, issuesCount, durationMs }`. | Post-scan reaction (Slack notification, CI gate, summary). |
| `extractor.completed` | Once per registered Extractor, after the full walk. Aggregated, NOT per-node. | `extractorId: string` (qualified). | Per-Extractor metrics, audit. |
| `analyzer.completed` | Once per Analyzer, after every issue is validated. | `analyzerId: string` (qualified). | Per-Analyzer alerting, downstream tooling. |
| `action.completed` | Once per Action invocation, after the report is recorded. | `actionId: string` (qualified), `node`, `jobResult`. | Per-Action notification, integration glue. |
| `job.completed` | Once per job that finishes successfully (job subsystem; Step 10). Same payload shape as the [`job-events.md`](./job-events.md) entry of the same name. | See [`job-events.md` §Event catalog](./job-events.md#event-catalog). | Most common Hook surface (notifications, retries, billing). |
| `job.failed` | Once per job that fails (job subsystem; Step 10). Same payload shape as the [`job-events.md`](./job-events.md) entry of the same name. | See [`job-events.md` §Event catalog](./job-events.md#event-catalog). | Alerting, retry triggers. |
| `shutdown` | Once per CLI process invocation, AFTER the verb returns its exit code and BEFORE `process.exit`. The dispatcher awaits subscribed hooks so they finish before the process terminates, but every hook MUST be fast (the user already saw the verb's output and waits for the prompt back). Errors are caught so a buggy hook never alters the verb's exit code, only delays the exit. | `exitCode: number` (the verb's resolved exit code, `0..5`). | Cleanup, post-run telemetry. |
A hook MAY narrow further with an optional declarative `filter` map: keys are payload field paths (top-level only in v0.x); values are the literal expected match. The dispatcher walks `event.data` for each declared key and short-circuits the invocation when any value disagrees. Examples:
- `filter: { extractorId: 'core/external-url-counter' }`, invoke only when THIS extractor finishes.
- `filter: { actionId: 'claude/skill-summarizer' }`, invoke only for one Action.
- `filter: { reason: 'runner-error' }` (on `job.failed`), invoke only when the runner crashed.
#### Dispatch semantics
Hooks are **deterministic-only**: the kind has no `mode` axis, and a manifest declaring one is rejected (see the mode-capability matrix above). The hook's `on(ctx)` runs in-process during dispatch of the matching event, synchronously between the event's emission and the next pipeline step. Errors are caught by the dispatcher (logged through a synthetic `extension.error` event with kind `hook-error`) and NEVER block the main pipeline. A buggy hook degrades gracefully and the scan continues.
A probabilistic hook would mean enqueuing a job from inside the dispatch path, which inverts the queue's pull-only contract: work is submitted by an operator or a verb, never by a pipeline step reacting to itself. An extension that needs model work in response to an event is an Analyzer or an Action, both of which have a probabilistic mode.
#### Cross-extension impact
Hooks introduce no new persisted state and do NOT participate in the deterministic scan cache (A.9). A re-scan against an unchanged corpus dispatches `scan.started` / `scan.completed` as before; subscribed hooks fire on every scan regardless of cache hit / miss. `IHookContext` exposes no `store`, so a hook that needs cache-aware behaviour has to derive it from the payload it receives rather than from persisted state of its own.
### Contract analyzers
1. An extension declares its kind in its module export and its manifest. Kind mismatch → load-error.
2. An Action MAY declare a `precondition` block, the declarative filter a node must satisfy for the action to be offered (see [`schemas/extensions/action.schema.json`](./schemas/extensions/action.schema.json#/properties/precondition)).
3. An extension MUST NOT retain state across invocations. Scoped persistence goes through `ctx.store`, which a plugin gets by declaring `"storage": { "mode": "kv" }`. 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.
### Locality
- **Drop-in**: extensions live inside plugins, discovered at boot from `/.skill-map/plugins//` only. The `--plugin-dir ` escape hatch on the `sm plugins …` verb family loads a custom directory per invocation when the user explicitly opts in.
- **Plugin enable vs import trust (security boundary, two orthogonal axes).** A drop-in plugin discovered under the project-local `/.skill-map/plugins/` is parsed (manifest read + surfaced in `sm plugins list`) but its extension CODE is imported and executed only when BOTH axes allow it:
- **Enabled (operational, shareable).** Whether the plugin / extension is part of the project. Lives in the config layers (`plugins..enabled`, `plugins..extensions..enabled`), `settings.json` (committed team baseline) overlaid by `settings.local.json` (per-checkout override). Written by `sm plugins enable / disable` (defaults to the shared `settings.json`; `--local` targets `settings.local.json`) and the Settings toggle. Default: the installed default (`true` for `stable` / `beta`, `false` for `experimental` / `deprecated`).
- **A toggle persists only what the default does not already say (redundant-key pruning).** Every enable-toggle surface (`sm plugins enable / disable`, `PATCH /api/plugins/...` in all three shapes) MUST NOT leave a per-extension `enabled` key in the target layer when removing that key would resolve to the same effective state. Concretely, the write is skipped (and any pre-existing key removed) when the value the toggle would store equals what the id resolves to WITHOUT it: the other layer's per-extension value if it has one, else the merged plugin-level `enabled`, else the installed default. The condition is "the key is redundant", NOT "the value equals the installed default": with `settings.json` carrying `false`, a `--local` toggle back to `true` still persists, because dropping it would resolve to `false`. An id whose installed default cannot be determined (a drop-in plugin discovered but not loaded, so no manifest `stability` / `defaultEnabled` is readable) is always persisted, never pruned. The same pass ALSO prunes redundant per-extension `enabled` keys the layer already carried, so a config that accumulated them under the previous always-write behaviour cleans itself up on the next toggle. Plugin-level `plugins..enabled` keys are never pruned (no toggle surface writes them; they are an operator-authored default for the whole plugin). Rationale: a config file should record decisions that differ from the shipped defaults, not restate them, and an `enabled: true` written only because the operator flipped a toggle twice should not silently pin the extension against a future change to its installed default.
- **Trusted (security, LOCAL, per-machine).** Whether THIS machine's operator consents to importing the plugin's code. A per-plugin grant in the **scope lock** (`/.skill-map/scope.lock.json`), written by `sm plugins trust / untrust ` and the per-plugin Trust control in the UI. Being gitignored is NOT what keeps trust local (the ignore list lives in the repo, so a hostile author force-adds the file); each grant is derived from the `.skill-map/` directory's filesystem identity, which git does not transport, so a grant made on another machine never verifies here. A committed `settings.json` does NOT and CANNOT grant import trust either: honouring a shared file would let a hostile repo auto-execute its plugins on the victim's first `sm scan`.
An extension's code is imported iff its plugin carries a local **trust** grant AND the extension itself resolves to **enabled**, both decided BEFORE the import (2026-07-29). Per-extension enable used to be applied AFTER the import, at registration, which meant an extension the operator had disabled, and one shipping `stability: 'experimental'` that nobody opted into, still had its module body evaluated on every scan; the interface said off while the code ran. The enable decision is now possible pre-import because `stability` / `defaultEnabled` live in `extension.json` on disk (see [§Extension kinds](#extension-kinds)). An extension that is declared but not imported is still enumerated, with its id, kind, version and stability read from that file. Because a skipped extension's entry module is never evaluated, extension entries MUST be independently importable: shared setup belongs in a module both entries import, not in one entry's top-level code. A long-lived host (`sm serve`) MUST rebuild its plugin runtime when an extension is enabled at runtime, since there is no loaded instance to un-filter; disabling needs no rebuild. A fresh clone carries no grant that verifies here, so its project-local plugins are discovered-but-unexecuted (`status: 'disabled'`, `untrusted: true`); the runtime emits a one-time notice naming how many were found and pointing at `sm plugins trust `. To trust many at once, `sm plugins trust --all` writes a per-plugin scope-lock grant for every discovered drop-in in one command (still local, still per-machine, still unable to travel), the code-review-vetted-team shortcut; there is no committed or config-file way to grant import trust, honouring one would let a cloned repo auto-execute its own plugins on the victim's first scan. The loader keeps the two not-loaded reasons distinct: `disabledByConfig` (the operator turned it off) vs `untrustedNotLoaded` (no local trust grant), so an explicit disable never re-reads as untrusted across a restart. Built-in extensions (compiled into the CLI) and an explicit `--plugin-dir ` (the operator pointed the loader at the code on purpose) are NOT trust-gated; `--no-plugins` skips discovery entirely. The `sm plugins` management family (`list` / `show` / `enable` / `disable` / `trust` / `untrust` / `doctor` / `config`) is trust-gated on the SAME terms as the runtime verbs (2026-07-28): reviewing a plugin means reading its source and its manifest, neither of which requires importing it, so an untrusted drop-in is enumerated from its manifests and never executed. Its per-extension `version` / `description` / `stability` come from each `extension.json`, so the inventory an operator reviews before granting trust is complete without running anything. This family was formerly exempt, on the reasoning that running an `sm plugins` verb is itself the operator's choice to work with the project's plugins; that made `sm plugins list` the shortest clone-and-scan path to executing a hostile repo's code, reached by an operator doing the responsible thing, and made `sm plugins trust` run the very code it was about to ask consent for.
- **Built-in**: the reference impl bundles a default extension set spanning every kind: one Provider per supported platform plus a universal `core/markdown` fallback, the body extractors those platforms need, the deterministic and probabilistic analyzers, the Actions (deterministic mutators and probabilistic finders/fixers), the output formatters, and the lifecycle hooks. The authoritative inventory is the code itself (`src/plugins//s//`, aggregated into `src/plugins/built-ins.ts`) and the live surface is `sm plugins list`; this document deliberately does not restate a count that changes every release. Two entries are worth naming because they close kernel-level invariants: `core/schema-violation` replays every scanned node and link through the authoritative spec schemas via AJV, the guard against persisting non-conforming graph rows, and `core/update-check` subscribes to `boot` to run the once-per-day "update available" probe + banner that lived on the CLI entry path before the Hook kind had concrete consumers. Loaded from `src/plugins/`, these are indistinguishable from plugin-supplied extensions to the kernel.
---
## Skill-actions catalog
A PARALLEL catalog next to the extension system, full contract in [`skill-actions.md`](./skill-actions.md). Operator-installed `SKILL.md` skills under the private folder `/.skill-map/.agents/skills//` are discovered once at `sm serve` boot (same posture as `PluginLoaderPort` discovery: no per-request re-walk, restart to pick up an install) and offered as per-node probabilistic work through the `skills` bucket of `GET /api/nodes/:pathB64/prob-extensions`, submitting into the ordinary job queue under the `skill:` id with `extension_kind` frozen as `action`.
What keeps it OUTSIDE the extension system, deliberately:
- **No code, no import trust.** A skill is TEXT that becomes part of a rendered prompt (inlined under a kernel-authored skill-instructions section, outside ``), never an imported module, so the §Locality trust axes do not apply; the trust anchor is the operator's explicit install into gitignored `.skill-map/` state, the same anchor as a drop-in plugin's `prompt.md`.
- **No manifest, canonical substitutes instead.** Identity from the directory name (`skill:`), version from frontmatter with a `0.0.0` fallback, prompt from the spec-pinned wrapper template (a normative artifact loaded like the canonical preamble), report contract from the single canonical [`schemas/skill-actions/report.schema.json`](./schemas/skill-actions/report.schema.json), resolved as a constant at record time.
- **No registry membership.** Skill actions never enter the extension registry, claim no view slots, contribute no annotations, and have no enable toggles; the §Boot invariant is untouched (an empty catalog is the default, and the kernel boots identically without one).
- **Not nodes.** The catalog lives under `.skill-map/`, which the default scan ignore excludes; a skill committed into the project tree is a node and NOT a skill action, the two surfaces are disjoint.
The execution posture is unchanged from §Execution handover: the kernel renders and queues, an external agent claims and records.
---
## Dependency analyzers
The following imports are NORMATIVELY FORBIDDEN:
- `kernel/*` → any `adapters/*` module.
- `kernel/*` → `node:fs`, `node:sqlite`, `node:child_process`, or equivalent IO libraries.
- Any extension → another extension.
- Any extension → `adapters/*`.
- `cli/*` or `server/*` → `adapters/*`. Driving adapters wire adapters into the kernel at startup; they do not import adapters directly in their command code.
The following imports are permitted:
- `kernel/*` → `spec/schemas/*` (type imports, JSON Schema files at runtime).
- `adapters/*` → `kernel/*` (ports are declared in the kernel and implemented in adapters).
- `cli/*`, `server/*`, extensions → `kernel/*` (consuming kernel APIs).
---
## Testability consequences
Because the kernel depends only on ports:
- Unit tests inject `InMemoryStorageAdapter`, `FixtureFilesystemAdapter`, and in-memory progress fakes.
- Integration tests wire real adapters.
- Conformance tests exercise the kernel directly, bypassing the CLI entirely.
- A driving adapter (CLI/Server/Skill) can be tested by asserting the kernel calls it makes, with all ports mocked.
This collapses cleanly onto the test pyramid mandated by `CLAUDE.md`: contract tests exercise kind schemas; unit tests exercise the kernel in isolation; integration tests exercise adapter pairs; CLI tests spawn the binary.
---
## Package layout (reference impl)
The spec does not prescribe package layout. The reference impl uses a single npm package with multiple `exports` entries:
```
src/
├── kernel/ Registry, Orchestrator, domain types, use cases, port interfaces
├── cli/ Clipanion commands, thin wrappers over kernel
├── server/ Hono + WebSocket, thin wrapper over kernel
└── adapters/
├── sqlite/ node:sqlite + Kysely + CamelCasePlugin (StoragePort)
├── filesystem/ real fs (FilesystemPort)
├── plugin-loader/ drop-in discovery (PluginLoaderPort)
```
Alternative implementations MAY use workspaces, separate packages, or a compiled monolith. The spec has no opinion.
---
## Driving-adapter peer analyzer
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 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.
This makes "CLI-first" coherent: every CLI verb is a kernel function call. The UI does not reimplement business logic; it calls the same functions.
---
## Config layering
`.skill-map/settings.json` (and its `.local.json` partner) are loaded through a layered hierarchy. Implementations MUST evaluate the four layers in order (low → high precedence) and deep-merge per key:
| # | Layer | Source | Audience |
|---|---|---|---|
| 1 | `defaults` | Bundled `defaults.json` (ships in the CLI binary). | Every install. |
| 2 | `project` | `/.skill-map/settings.json` | **Committed to the repo**, values are shared with every collaborator and CI. |
| 3 | `project-local` | `/.skill-map/settings.local.json` | **Gitignored**, values are per-checkout, never travel via the repo. |
| 4 | `override` | Caller-supplied (env vars, CLI flags). | Process-scoped, ephemeral. |
The merge is per dot-path: a value at a higher layer replaces the value at lower layers; objects recurse, arrays replace. The loader records which layer last wrote each key in a `sources` map so `sm config show --source` can attribute every effective value.
Only layer 2 (`project`) travels via the shared repo, so values landing in `project` are part of the contract every collaborator inherits. Layers 1, 3, 4 carry **per-machine / per-checkout state** that never leaves the project.
Skill-map deliberately has **no user-scope config layer**: no `$HOME` state merges on top of the project. The CLI honours "never read `$HOME` by default" (see `cli-contract.md` §Scope is always project-local). The narrow exception, `~/.skill-map/settings.json`, holds genuinely per-machine preferences (the update-check toggle + its throttle bookkeeping today; future locale / theme) but is **NOT** part of the config layer system: it is read directly by the module that owns the feature, never merged into the project layers. See `cli-contract.md` §User-settings file.
### Per-key locality
One locality class constrains which layers a given key MAY live in. Enforced in code (reference impl: `core/config/helper.ts`), not in the JSON Schema; the schema stays additive so older settings files keep validating even when a key is reclassified.
- **`PROJECT_LOCAL_ONLY_KEYS`**, keys describing per-user-per-project preferences. Valid in layers 1, 3, 4. **Stripped (with a warning) from layer 2 (`project`)** because the value is inherently per-user and must not be shared via the committed repo. **Also stripped from layer 3 (`project-local`) unless the key carries a scope-lock grant** (2026-07-28, audit H1): the layer being gitignored describes the default behaviour, not a boundary, since the ignore list lives in the repo and `git add -f` ships the file, so a cloned project could otherwise hand a victim `scan.followExternalSymlinks: true` or `scan.referencePaths: ["~/"]`. A grant covers one key at one value, so an ordinary write (a UI toggle, a plugin secret) mints nothing for a key it did not touch and cannot launder a shipped one. Writes target `project-local` (`/.skill-map/settings.local.json`); `sm config set` rejects writes to `project` for these keys with a directed error.
Members (keep in lock-step with `PROJECT_LOCAL_ONLY_KEYS` in the reference impl, `kernel/config/loader.ts`):
- `allowEditSmFiles`, per-project consent to create / modify `.sm` sidecars.
- `allowNetworkActions`, per-project consent for Actions declaring `io: ['network']` to execute. Reclassified 2026-08-01 (audit): it shipped as a committed team-shared policy while promising that "a cloned repo must not be able to make skill-map fetch remote content without the operator's explicit consent", a promise the committed layer cannot keep, since that file is the cloned repo's own. A hostile project shipped `true` beside an enabled network action and the victim's first `sm enrich` reached out unasked.
- `scan.referencePaths`, additional link-validation paths.
- `scan.followExternalSymlinks`, opt-in to follow symlinks whose real target escapes every scan root (the realpath-containment gate's escape hatch).
- `activity.captureConversations`, the consent gate for retaining inter-agent conversation content in the serve process (`provider-activity.md` §Conversation capture).
- `tutorialReminderStep`, the web UI's tutorial-reminder sequence position (0-2).
- `ui.liveUpdates`, `ui.realtimeActivity` and `ui.showRuntimeAgents`, per-developer web-UI rendering choices (live map sync, real-time activity, ephemeral agent capsules), written by Settings > Project through `PATCH /api/project-preferences`.
- `mcp.server.enabled`, whether `sm serve` mounts the local MCP surface at `/mcp`.
- `plugins.github.extensions.enrichment.settings.apiBaseUrl` and `plugins.github.extensions.enrichment.settings.rawBaseUrl`, the `github/enrichment` base-URL overrides. The extension's `token` setting rides the Authorization header to whatever host `apiBaseUrl` names, so a committed override in a cloned repo would exfiltrate the operator's token on the first `sm enrich`; the loader strips both from the committed layer with a warning (see `cli-contract.md` §Project-local-only config).
The consent-shaped entries describe surfaces only the local operator may opt into: `allowEditSmFiles`, `scan.referencePaths`, and `scan.followExternalSymlinks` govern disk access, `activity.captureConversations` the retention of conversation content, and the `github/enrichment` base-URL overrides where the operator's token is sent. Sharing any of them via the repo would silently expand every collaborator's surface in a way only the original author consented to. `mcp.server.enabled` exposes a local control surface. (Plugin import trust is the same per-machine shape but is NOT a config key at all: it lives per-plugin in the scope lock, never in a config layer, so no committed file can grant it, the exact supply-chain attack the trust gate prevents.) The remaining entries (`tutorialReminderStep`, `ui.liveUpdates`, `ui.realtimeActivity`, `ui.showRuntimeAgents`) carry no security weight; they are inherently per-developer preferences, and a committed value would override every other collaborator's choice on each pull.
Adding a new entry is a behaviour change for older installs that wrote the key into a committed file: the value gets stripped at read time. The changeset adding the entry MUST document the migration.
### Extension settings resolution
Plugin extensions declare user-configurable `settings` in their manifest (per-extension, see `plugin-author-guide.md` §Settings); the operator's values live in the config tree under `plugins..extensions..settings.` and flow through the same four-layer merge as any other key. The kernel's settings resolver runs once per scan while composing the enabled extensions: for each declared setting it takes the manifest `default`, overlays the merged config value, then, for a `secret` declaring `envVar`, lets a NON-EMPTY process-environment value under that name win over the stored one (the environment is threaded in by the caller; the resolver itself never reads process state), and validates the result against the input-type's value schema (`input-types.schema.json#/$defs/ISettingDeclaration`); a value that fails falls back to the default with a warning, so the scan never aborts on a bad setting. The resolved object reaches the extension's runtime methods as `ctx.settings.`. `project-config.schema.json` keeps the `settings` object permissive (`additionalProperties: true`) on purpose: the static schema cannot know which input-type a given `settingId` picked, so per-value validation is the resolver's responsibility, not AJV's. `secret`-typed settings are config-layer values, but the kernel forces them into the project-local layer (`settings.local.json`, gitignored), never the committed `settings.json`, the dynamic equivalent of `PROJECT_LOCAL_ONLY_KEYS` (destination follows the declared type, not a fixed key list). No encryption in v1: the protection is the value never travels via the shared repo (see `input-types.schema.json#/$defs/Setting_Secret`).
---
## Annotation system
Skill-map's own metadata layer (versioning, supersession, provenance, taxonomy, docs) lives in **co-located YAML sidecars** with extension `.sm`, in the same directory as the markdown node they annotate. Vendor files (`.claude/agents/foo.md`, `.cursor/analyzers/bar.mdc`, …) stay untouched; the sidecar (`foo.sm` / `bar.sm`) IS skill-map's "annotations file" for that node, every key under it conceptually an annotation. The YAML root organizes them into structural blocks (identity, the curated annotations catalog, audit timestamps, settings, plugin namespaces); the file as a whole is the annotation surface.
Two schemas describe the wire shape:
- [`schemas/sidecar.schema.json`](./schemas/sidecar.schema.json), root shape with reserved blocks `identity` (anchor + drift hashes), `annotations` (the conventional catalog), `settings` (reserved), `audit` (write trail), plus opt-in `:` namespacing.
- [`schemas/annotations.schema.json`](./schemas/annotations.schema.json), curated 10-field catalog: versioning (`version`, `stability`), provenance (`authors`, `license`, `source`, `sourceVersion`), taxonomy (`tags`), docs (`docsUrl`), and the two dismissal surfaces, `suppressions` (probabilistic finding classes, per (extension, type)) and `issueSuppressions` (deterministic analyzer issues, per (analyzer, value)). The activity timestamp lives in the reserved `audit:` block (`audit.lastBumpedAt`), not in `annotations:`. `additionalProperties: true` so plugins or users add custom keys without coordination; the built-in `unknown-field` analyzer warns on truly unrecognized keys (typo guard).
### Identity and drift
`identity` carries `path` (scope-root-relative, matches the canonical Node identifier in [`schemas/node.schema.json`](./schemas/node.schema.json)) plus `bodyHash` and `frontmatterHash`. Both hashes are sha256 over the kernel's canonical form of the markdown body (post-frontmatter bytes) and frontmatter (YAML re-emitted via `js-yaml dump` with `sortKeys: true`, `lineWidth: -1`, `noRefs: true`, `schema: CORE_SCHEMA`, js-yaml 5's modern YAML 1.2 output; the js-yaml 4 recipe used `noCompatMode: true`, which v5 removed, and `CORE_SCHEMA` reproduces its dumps byte-for-byte, so hashes are stable across the upgrade); each sidecar captures the values the kernel saw when last written.
At scan time the kernel re-computes the live hashes and compares against the stored ones. Mismatch in either is **drift**, surfaced via the built-in `annotation-stale` analyzer through icon-only card contributions (the footer clock chip plus the stale badge; since 2026-07-20 it emits NO issue, soft mode by design: drift is informational and stays out of the findings list). A `.sm` whose `identity.path` no longer points at an existing `.md` is **orphan**, surfaced via the built-in `annotation-orphan` analyzer (a `warning` issue). Drift state is **derived**, never stored, a pure function over existing data, so no flag can diverge from reality.
### Storage rule
Where a persisted surface lives follows ONE question (decision 2026-07-21): **did a human decide this?**
- **Machine output** (generated without human judgment, regenerable by re-running the producer): the project DB. Findings, summaries, executions, jobs, enrichments. Deleting it loses nothing a re-run cannot recreate.
- **Human curation** (an operator's decision or authorship): the node's `.sm` companion, committed and portable. Tags, stability, version bumps, audit stamps, dismiss suppressions (finding classes AND issue values). The `scan_issues` delete that accompanies an issue dismiss is not a violation of the split: the suppression itself (the human decision) lives in the `.sm`, and the row delete only converges regenerable machine state toward what the next scan produces anyway.
- **Machine-local authorization** (a human decision that must NEVER be portable): the scope lock, `/.skill-map/scope.lock.json`, gitignored and never committed. Plugin import trust and consent for the privileged `PROJECT_LOCAL_ONLY_KEYS` live here. This is a THIRD category, added 2026-07-28, because the first two do not fit: it carries human judgment, so it is not machine output, but it authorizes code execution and privileged settings on ONE machine, so it must not travel the way `.sm` curation deliberately does. Being gitignored is not what protects it (the ignore list lives in the repo, so a hostile author simply force-adds the file); each record carries a grant derived from the `.skill-map/` directory's filesystem identity, which git does not transport, so a record made elsewhere cannot verify here.
- **Project-level shared curation** (a human decision that spans nodes and must travel with the repo): `/.skill-map/views/`, the named map views ([`map-views.md`](./map-views.md)). This is a FOURTH category, added 2026-08-10, the "explicit new decision" the closing rule below demanded: a map view is human-authored curation, but it annotates the WORKSPACE topology rather than any single node, so the per-node `.sm` cannot host it; it is not regenerable, so the DB must not; and it carries no machine authority, so the scope lock must not. One file per view, committed by default through the scope ignore allowlist, portable by design. The no-carve-out clause applies with full force: a machine may PROPOSE a view edit (the reserved `view-ref-broken` analyzer) but never author or rewrite one.
- **Per-session machine journal** (machine output whose natural grain is one FILE per session, not DB rows): `/.skill-map/sessions/`, one JSON file per recorded runtime session ([`session-recording.schema.json`](./schemas/session-recording.schema.json), written by the serve process per [`provider-activity.md` §Session journal](./provider-activity.md#session-journal)). This is a FIFTH category, added 2026-08-16 by explicit decision: it answers the first question as machine output (generated without human judgment, regenerable by running new sessions, disposable), but it deliberately lives as gitignored session files rather than DB rows because the file IS the future export/import artifact and the operator's unit of inspection and curation-by-deletion (delete a file, its session leaves the evidence base; delete the directory, the journal resets). Content-free by construction, so deletion is always safe and no consent gate applies.
New persisted surfaces MUST pick their home among these five by this rule; mixing categories inside one feature requires an explicit new decision. When a surface carries human judgment, ask the follow-up question too: *may this decision travel to another machine?* If not, it belongs in the scope lock, not the `.sm`. The rule admits no carve-out for CURATION: a machine may PROPOSE curation data but never author it. The tagger is the worked example ([`job-lifecycle.md` §Tags proposal](./job-lifecycle.md)): it surfaces inferred tags on its completion event and writes nothing, and the operator saves them through the ordinary consent-gated editor. (Fixers editing MARKDOWN BODIES are not curation and stay unaffected: a body is the vendor's and the author's content, not skill-map's curation store.)
### Bump model
The deterministic built-in `core/node-bump` Action produces a sidecar patch:
- Increments `annotations.version` by 1 (or sets to `1` if missing, single integer monotonic, orthogonal to `stability`; major bumps are not a concept, the convention for breaking changes is "create a new node and retire the old"). A FRESH sidecar refuses the bump only while it already carries a version (nothing to bump); a fresh sidecar with NO `annotations.version` accepts it and stamps the first version (2026-07-21).
- Refreshes `identity.bodyHash` and `identity.frontmatterHash` to the live values.
- Stamps `audit.lastBumpedAt` (ISO 8601 datetime) and `audit.lastBumpedBy` (the Git author name from `git config user.name` when the project is a Git repo; otherwise the channel literal `'cli'`, `'ui'`, or `'plugin:'`).
- On first-time creation also stamps `audit.createdAt` and `audit.createdBy` (set once, stable thereafter).
The Action stays pure (no IO). The kernel materializes the patch through the `SidecarStore` port, a path-keyed read-modify-write critical section that deep-merges the patch into the on-disk file (arrays REPLACE, objects RECURSE, `null` DELETES) and writes atomically via `.tmp` + POSIX rename. Concurrent bumps on the same path serialize through the lock; both patches' effects survive (no lost write).
### Triggers
- **Manual**, single-node: `sm bump ` (CLI) or `POST /api/actions/core/node-bump` (BFF, drives the same Action / Store).
- **Manual**, batch: `sm bump --pending [--staged]` walks every node whose sidecar reports drift (or whose `.sm` is missing) and bumps each in `node.path` ASC order. `--staged` runs `git add` on each updated `.sm` so the new content lands in the same commit.
- **Opt-in pre-commit hook**: `sm hooks install pre-commit-bump` writes a `.git/hooks/pre-commit` block that calls `sm bump --pending --staged --force` on commit. Idempotent reinstall via sentinel markers.
- **Watch mode**: never auto-bumps. Computes "stale" state on demand from hash comparison.
### Write consent
Every `.sm` write, scaffold (`sm sidecars annotate`), hash-only update (`sm sidecars refresh`), bump (`sm bump`, or the BFF dispatching `core/node-bump`), action dispatch (`POST /api/actions/:pluginId/:actionId` for any `.sm`-writing Action), or any future write surface, passes through `SidecarStore.applyPatch` (or, where the verb writes a fresh sidecar, the equivalent kernel-managed entry point).
**Project policy gate (evaluated first).** Before the consent ladder, the chokepoint consults the committed `allowSidecarWriters` policy (see [`project-config.schema.json`](./schemas/project-config.schema.json#/properties/allowSidecarWriters); default `true`, lives in the team-shared `project` layer). When `allowSidecarWriters === false` the kernel raises `ESidecarWritersForbiddenError` and refuses the write outright, regardless of `allowEditSmFiles` or any `confirm` / `always` signal: a team policy forbidding sidecar writers is a HARD gate a per-machine consent cannot override, and `--yes` does not bypass it. The same policy drops every Action declaring `writes: ['sidecar']` from the scan composer, so those Actions never project their `inspector.action.button` and the chokepoint deny is only a backstop. The CLI surfaces the error as a terminal message naming the policy; the BFF maps it to `403 sidecar-writers-forbidden`. The consent ladder below applies only when the policy permits writers (`allowSidecarWriters !== false`).
That single chokepoint MUST consult `allowEditSmFiles` (see §Config layering) before touching disk. Every write asks unless `allowEditSmFiles === true`; the dispatch / bump body carries two orthogonal consent fields, `confirm` (one-shot grant) and `always` (persist the grant):
- `allowEditSmFiles === true` → write proceeds, no prompt (consent already persisted).
- `allowEditSmFiles === false` AND the caller passes `always: true` → the kernel persists `allowEditSmFiles: true` to `/.skill-map/settings.local.json` (layer `project-local`), then performs the write. `always` **implies** `confirm`: the grant authorises this write too, so a body with `always: true` need not also set `confirm`.
- `allowEditSmFiles === false` AND `confirm: true` (without `always`) → a **one-shot** grant. The kernel performs this write but persists **nothing**; the next write re-asks. For "yes, just this once".
- `allowEditSmFiles === false` AND both `confirm` and `always` missing / false → the kernel raises `EConsentRequiredError`. The driving adapter MUST translate it into a surface-appropriate prompt:
- **CLI on a TTY**: interactive `confirm()` prompt offering "just this once" (re-invokes with `confirm: true`) vs. "always for this project" (re-invokes with `always: true`). Decline aborts without persisting the rejection.
- **CLI without a TTY** (CI, scripts): exit with the standard "user input required" code and a message hinting `--yes`.
- **BFF**: 412 `confirm-required` envelope (`{ ok: false, error: { code: 'confirm-required', message, details: { key: 'allowEditSmFiles' } } }`). The UI catches it, opens a confirm dialog with the same two choices, and on accept retries the original request with `{ confirm: true }` or `{ always: true }`.
Declining persists **nothing**, neither a grant nor a rejection. It aborts the current operation but the next attempt re-asks. Deliberate: a "no" today should not foreclose a "yes" tomorrow without hand-editing the settings file, and a one-shot `confirm` never silently enrols the project into unconditional writes.
The flag lives in `project-local` (gitignored) so each collaborator consents independently; a single contributor's `always` never enrols teammates without their knowledge.
### Plugin contributions
Plugins extend the annotation surface via the optional `annotation` block on an extension manifest (`{ schema, ownership?, location? }`, inline JSON Schema, no `$ref` to external files). It is a **single** declaration per extension and **the contributed key is the extension's id** (its folder name); an extension needing several keys splits into several extensions, one per key. Two location modes:
- `location: 'namespaced'` (default), writes go to the plugin's `:` block at the sidecar root. Default `ownership: 'shared'`. Plugins write to their own namespace without coordination; AJV validates the contributed value against the extension's declared schema.
- `location: 'root'`, writes go to a top-level key (alongside `identity` / `annotations` / `settings` / `audit`). Requires `ownership: 'exclusive'` (claiming a root key is elevated trust). Two plugins claiming the same root key with `exclusive` is a **hard fatal** at orchestrator startup; the kernel refuses to boot rather than route writes ambiguously.
The kernel exposes a runtime catalog (`Kernel.getRegisteredAnnotationKeys()`) listing every plugin-contributed key with its `pluginId`, `location`, `ownership`, and `schema`, consumed by the BFF (`GET /api/annotations/registered`) for UI autocomplete.
### Read path (denormalization)
Two columns on `scan_nodes` source from the sidecar's `annotations:` block when present (hard cut, no fallback to the legacy `frontmatter.metadata.*` shape):
- `scan_nodes.stability` ← `annotations.stability`
- `scan_nodes.version` ← `annotations.version` (integer)
A `scan_nodes.annotations_json` column carries the full parsed `annotations:` block; `sidecar_present` and `sidecar_status` carry the drift-detection state. The full sidecar overlay (parsed `annotations`, `status`, `present`) is exposed on `Node.sidecar` as part of the canonical wire shape.
### Tags
Tags are a **skill-map concept**, not a vendor field: no agent format (Claude, Cursor, Obsidian, the Agent Skills open standard, …) carries `tags` in frontmatter, so skill-map keeps them where it owns the surface, the `.sm` sidecar.
- **Tags** live in `sidecar.annotations.tags` (in the `.sm`). Curated annotation field declared on [`schemas/annotations.schema.json`](./schemas/annotations.schema.json). These are the tags whoever curates the project assigned to the node from their sidecar.
Search and listings (`sm list --tag `, UI faceted search) match this field: a hit returns the node. The UI renders them as chips on the node card and in the inspector.
Persistence projects rows into a normalized [`scan_node_tags`](./db-schema.md#scan_node_tags) table at write time, one row per `(node_path, tag)` pair, so SQL queries index on `(tag)` for `O(log n)` lookup. Replace-all per scan keeps the table in sync with the live sidecar state; deleting a tag from a sidecar removes its row on the next scan.
The wire shape (`/api/nodes` and `/api/nodes/:pathB64`) projects `node.tags = string[]`. The kernel `Node` interface (TypeScript) does NOT carry `tags`; consumers walking the canonical source read `node.sidecar.annotations.tags` directly (consistent with the post-decision-#2 posture of "no Node-level denormalisations").
### Stability
The **layout decision** (co-located `.sm`, not mirror tree under `.skill-map/`) is stable as of spec v1.0.0. Moving the home is a major bump.
The **format** (YAML, extension `.sm`, not `.md.sm`) is stable as of spec v1.0.0. Switching format or extension is a major bump.
The **reserved block names** (`identity`, `annotations`, `settings`, `audit`) are stable as of spec v1.0.0. Adding a new reserved block is a minor bump; renaming or removing one is a major bump.
The **identity contract** (`identity.path` + `identity.bodyHash` + `identity.frontmatterHash`, with `resolvedAs` optional) is stable as of spec v1.0.0. Changing the hash algorithm or canonicalization analyzer is a major bump.
The **bump field set** (the four `audit` fields `lastBumpedAt` / `lastBumpedBy` / `createdAt` / `createdBy`) is stable as of spec v1.0.0. Adding new audit fields is a minor bump; removing or renaming is a major bump. The audit block is `additionalProperties: true` so plugins or future Actions MAY ride additional keys opaquely.
The **annotations catalog** is stable as of spec v1.0.0 *for the listed conventional keys*. Adding a new conventional key (with documentation) is a minor bump; removing or renaming a conventional key is a major bump. Plugin-contributed keys ride on `additionalProperties: true` and are NOT covered by this clause, their stability is the contributing plugin's responsibility.
The **`null`-as-delete sentinel** in `SidecarStore.applyPatch` is an internal contract between the kernel and Action authors that return sidecar writes; it is not user-visible (persisted sidecars never carry literal `null`s on schema-typed properties). Documented here so future Action authors can rely on it.
---
## View contribution system
Sibling system to the annotation contributions above. Both let plugins extend the surface the kernel exposes; the difference is **where the data lives and what it drives**:
| | Annotation contributions | View contributions |
|---|---|---|
| **Data lives in** | the user-facing sidecar `.sm` file | the kernel-managed `scan_contributions` table |
| **Author intent** | extend the metadata catalog | surface per-node data in the UI |
| **Plugin author writes** | inline JSON Schema for the value | `slot` name from a closed catalog |
| **Validation** | AJV at sidecar-write time | AJV at `ctx.emitContribution(...)` time |
| **Lifecycle** | persists across scans (file-on-disk) | re-emitted on every scan (table cleared per node) |
| **Surfaces in** | sidecar consumers + `` panel | fixed renderer per slot, mounted at exactly the slot the author declared |
Two schemas describe the wire shape:
- [`schemas/view-slots.schema.json`](./schemas/view-slots.schema.json), closed catalog: 19 slot names + the `IViewContribution` manifest declaration shape + per-slot payload schemas (in `$defs/payloads`) the kernel uses to validate emit-time payloads.
- [`schemas/input-types.schema.json`](./schemas/input-types.schema.json), closed catalog: 12 input-type names + the `ISettingDeclaration` manifest declaration shape (discriminated by `type`).
### Identity
Each view contribution is identified by the qualified id `//`. The plugin author declares contributions in the extension manifest under `ui: Record` (renamed from `viewContributions` with the structure-as-truth refactor); the loader composes the qualified id from the plugin id, extension id, and Record key. The runtime catalog aggregated by `Kernel.getRegisteredViewContributions()` keeps the original `viewContributions` name; only the manifest-side field changed.
### Manifest
Each entry picks a `slot` name from the closed catalog and supplies presentation tuning. The slot fixes both the renderer and the payload shape; there is no separate "contract" abstraction:
```jsonc
{
"ui": {
"breakdown": {
"slot": "inspector.body.panel.breakdown",
"label": "Keyword hits",
"emptyText": "No matches."
},
"total": {
"slot": "card.footer.left",
"icon": "🔍",
"label": "kw",
"emitWhenEmpty": false
}
}
}
```
The plugin author picks ONE slot per contribution; that single decision determines where the data renders, what payload shape `ctx.emitContribution(...)` must produce, and which Angular component draws it. Seven manifest fields per contribution (`slot`, `label?`, `tooltip?`, `icon?`, `emptyText?`, `emitWhenEmpty?`, `priority?`) plus the slot catalog page is the entire mental model. See [`plugin-author-guide.md`](./plugin-author-guide.md) §View contributions for worked examples.
The six `inspector.body.panel.*` slots render grouped **one collapsible section per plugin** in the inspector body (titled by the trusted `pluginId`, collapsed by default); a plugin's bricks never land in another plugin's section. Two optional inspector-only ordering hints drive layout: a plugin-level `order` in `plugin.json` sorts sections, an extension-level `order` (base extension manifest) sorts bricks within a section. Both default to 100 and never affect execution order. They are denormalised onto each `contributionsRegistry` entry (`pluginOrder` / `extensionOrder`) so the UI applies them without a second round-trip.
### Settings
Plugin user-configurable settings live **on each extension's manifest** (structure-as-truth) in `settings: Record` (see [`schemas/extensions/base.schema.json`](./schemas/extensions/base.schema.json) and [`schemas/input-types.schema.json`](./schemas/input-types.schema.json)). Each setting picks an input-type from the closed catalog (`string-list`, `single-string`, `boolean-flag`, `integer`, `number`, `enum-pick`, `enum-multipick`, `path-glob`, `regex`, `secret`, `key-value-list`). The kernel exposes resolved settings via `ctx.settings.` to the extension's runtime methods (`extract`, `evaluate`, `invoke`, etc.); the UI generates a form per declaration; the CLI's `sm plugins config /` exposes the same surface. Plugin-level settings are no longer supported; the field moved from `plugin.json` to each extension that consumes it.
Settings are read once at extension invocation; changing one requires `sm scan` to re-emit affected contributions. The UI surfaces a "settings changed, rescan needed" indicator on mismatch; live re-emission is explicitly out of scope (a stability decision per `ROADMAP.md` §UI contribution system D4).
### Runtime catalog
The kernel exposes a runtime catalog (`Kernel.getRegisteredViewContributions()`) listing every plugin-contributed view contribution with its `pluginId`, `extensionId`, `contributionId`, `slot`, and the manifest-declared `label` / `tooltip` / `icon` / `emptyText` / `emitWhenEmpty`. Built once at boot from every loaded extension's `ui` map, AJV-validated, and frozen, same lifecycle as `getRegisteredAnnotationKeys()`.
Analyzers see the catalog through `IAnalyzerContext.viewContributions` so cross-cutting checks can reason about emissions (a generic context surface; the two original built-in consumers retired: `core/unknown-slot` moved to `sm plugins doctor`, `core/contribution-orphan` was deleted 2026-07-22 as a never-implemented stub).
### Emit path
Extensions emit per-node payloads via context callbacks:
```ts
// Extractors (per-node walk)
ctx.emitContribution(contributionId, payload);
// Analyzers (post-merge graph), same payload contract, explicit nodePath
// because the analyzer sees every node at once
ctx.emitContribution(nodePath, contributionId, payload);
```
Parallel to `ctx.emitLink(link)`. The kernel buffers the emission, validates the payload against the slot's payload schema in `$defs/payloads/` (AJV-compiled at boot), and persists the row to `scan_contributions` during `persistScanResult`. Off-shape payloads emit an `extension.error` event and drop silently, same posture as `emitLink` rejecting off-enum link kinds. Both Extractor and Analyzer emissions land in the same `scan_contributions` rows; the row's `extension_id` records which kind produced it.
The Extractor-emit signature binds `nodePath` implicitly (the extractor runs per-node, `ctx.node.path` the only sensible target). The Analyzer-emit signature requires the analyzer to declare the target node explicitly because Analyzers see the full graph and may emit for any subset of nodes; the canonical use case is an analyzer deriving per-node values from cross-graph aggregations (`core/link-counter` projects `linksOutCount` / `linksInCount` this way).
Analyzers MAY also emit scope-level contributions via `IAnalyzerContext.emitScopeContribution(contributionId, payload)` (only slots whose schema permits scope-level emission, today only `topbar.nav.start`). That signature is reserved in the spec; the runtime callback lands when the first scope-level adopter arrives.
### Persistence
A new table `scan_contributions` (see [`db-schema.md`](./db-schema.md) §scan_contributions when shipped) carries per-node emissions:
| Column | Type | Notes |
|---|---|---|
| `plugin_id` | TEXT | qualified plugin id |
| `extension_id` | TEXT | extension id within the plugin |
| `node_path` | TEXT | scope-relative path |
| `contribution_id` | TEXT | manifest Record key |
| `slot` | TEXT | denormalized slot name (`view-slots.schema.json#/$defs/SlotName`) |
| `payload_json` | TEXT | JSON-serialized payload (already validated against the slot's payload schema) |
| `emitted_at` | INTEGER | unix epoch ms |
PK `(plugin_id, extension_id, node_path, contribution_id)` so re-emission upserts. Index on `node_path` (inspector lazy-fetch + orphan sweep) and on `plugin_id` (catalog sweep + `purgeByPlugin`).
**NOT pure replace-all** (the way `scan_links` / `scan_issues` are). The watcher's cached pass leaves the contributions buffer empty for cached nodes: the orchestrator skips `extract()` on a per-(node, extractor) cache hit, so no `emitContribution` fires. A naive wipe-all would silently drop the prior valid rows on every watcher boot. The persist runs four passes inside the same transaction:
1. **Orphan sweep**, drops every row whose `node_path` is NOT in the current live node set. Disappeared nodes lose their contributions.
2. **Catalog sweep**, drops every row whose qualified id `(pluginId, extensionId, contributionId)` is NOT in the registered runtime catalog (uninstalled-on-disk plugins, removed contributions). Disabled plugins are normally purged eagerly by `sm plugins disable` (see `StoragePort.contributions.purgeByPlugin`); this sweep is the fallback for the rare "config flipped between scans without going through the CLI" case.
3. **Per-tuple sweep**, for every `(pluginId, extensionId, nodePath)` tuple where the extension actually RAN against that node this scan (extractor cache miss, OR analyzer, analyzers always run), drop any row carrying that triple whose `contribution_id` is NOT in the buffer for that triple. This catches the "extractor used to emit, now does not" case (e.g. a body change that removes the trigger). Cached-extractor tuples are NOT in the set, so their rows survive untouched.
4. **Upsert**, `INSERT ... ON CONFLICT DO UPDATE SET payload_json = excluded.payload_json, slot = excluded.slot` for every row in the buffer. PK conflict refreshes payload + `slot` + `emitted_at`.
Cached nodes' rows survive untouched (still in the live set and catalog, the (plugin, extension, node) tuple not in the freshly-run set, no buffer hit). When the body next changes, the orchestrator re-runs the extractor, the tuple lands in the freshly-run set, and either the upsert refreshes the row OR the per-tuple sweep drops it (when the extractor no longer emits for that node).
Empty buffer + non-empty live set = cached-pass (no-op). Empty buffer + empty live set = legacy wipe-all (cold start). Three `IPersistOptions` fields control which sweeps activate; absent values fall back to legacy behaviour (sweep skipped) so older callers keep working:
- `livePaths?: ReadonlySet`, gates the orphan sweep (1).
- `registeredContributionKeys?: ReadonlySet`, gates the catalog sweep (2). Element format: qualified id `//`.
- `freshlyRunTuples?: ReadonlySet`, gates the per-tuple sweep (3). Element format: `//` (no contribution-id segment, the sweep operates at the (plugin, extension, node) level and inspects the buffer to decide which contribution-ids survive).
Cold-start posture: the BFF endpoints below return empty arrays when the table is missing (mirror of the `tryWithSqlite` graceful-null pattern used by `routes/nodes.ts`); never a 500.
### BFF surface
Endpoints under `/api/contributions/*`:
- `GET /api/contributions/registered`, runtime catalog. Mirror of `/api/annotations/registered`. Envelope variant `kind: 'contributions.registered'` (see [`schemas/api/rest-envelope.schema.json`](./schemas/api/rest-envelope.schema.json)).
- `GET /api/contributions/:pluginId/:extensionId/:contributionId?path=...`, lazy per-node fetch for inspector slots. **Three URL segments** mirror the qualified id `//`. Filters by qualified id + node path; the BFF enforces `pluginId` ↔ namespace at the route level, no cross-plugin reads via this endpoint.
The `inspector.action.button` contribution is **self-projected by the dispatching Action's own `project(ctx)`** (scan-time, deterministic), not by a separate projector Analyzer. The Action computes the per-node `enabled` / `disabledReason` and the prompt `options` / `defaultValue` from the live graph it receives, emits the button, and is itself the dispatch target. (This reverses the earlier "an Analyzer projects the button" shape; the projector Analyzer `core/tags` was removed and `core/annotation-stale` keeps only its badge surfaces.) The slot dispatches to a generic Action endpoint:
- `POST /api/actions/:pluginId/:actionId`, dispatch a kernel Action by qualified id (the two segments recompose into the `/` from the button payload's `actionId`; Hono's `:param` never matches a `/`, so the id cannot travel as one segment). Body carries the target `nodePath`, the optional reserved `input` object (Steps 2+), and the consent fields `confirm` / `always` (see §Annotation system → Write consent) for `.sm`-writing Actions. The kernel resolves the Action (unknown OR disabled id → 404; the route re-derives the enabled state from the live layered config on every dispatch, so a mid-session disable is honoured and a disabled Action can never be invoked by qualified id), runs it against the node, and answers the action-result envelope `kind: 'action.applied'` (`{ value: { actionId, nodePath, report }, elapsedMs }`, see [`schemas/api/rest-envelope.schema.json`](./schemas/api/rest-envelope.schema.json)). `core/node-bump` dispatches through this same route; it has no dedicated endpoint of its own.
Plus catalog embedding into every payload-bearing envelope:
- `kindRegistry`, `providerRegistry`, and `contributionsRegistry` are siblings on the envelope (see schema). Built once per server boot, embedded into list (`nodes` / `links` / `issues` / `plugins`), single (`node`), and value (`config`) envelopes. Sentinel envelopes (`health` / `scan` / `graph`), action-result envelopes (`action.applied` / `job.submitted`), and the catalog envelopes themselves (`annotations.registered` / `contributions.registered`) carry none. `providerRegistry` is the static boot catalog of registered Providers' identity; the dynamic active lens (current value + filesystem-detected candidates + the enabled `selectable` set) is served separately by `GET /api/active-provider`.
Plus per-node embedding on node responses:
- `GET /api/nodes/:pathB64`, single-node `item.contributions[]` carries every emission for that node, regardless of `bff.maxBulkContributions`.
- `GET /api/nodes` (bulk list), `items[].contributions[]` carries emissions for the page slice **only when** `limit ≤ bff.maxBulkContributions` (default and hard upper bound 200). When the page exceeds the cap, `items[].contributions` is omitted and `meta.contributionsOmitted: true` is set so the UI can lazy-fetch per node. The cap is documented but not promoted; tuning above 200 is unsupported.
- `GET /api/scan`, the SPA's `CollectionLoaderService` hydrates from this endpoint on F5 / cold boot (single-fetch ScanResult); it MUST embed `contributions[]` per node alongside the standard fields, else the inspector / card slot hosts have nothing to render until the next per-node fetch. Decoration is a single bulk `port.contributions.listForPaths(...)` round-trip after `scans.load()`, sibling of the per-node `isFavorite` decoration on the same route.
### Isolation
View contributions extend the existing plugin-isolation model (see [`plugin-kv-api.md`](./plugin-kv-api.md) §Honest note on isolation) with six analyzers specific to UI rendering:
1. **No raw DOM from plugin**, contributions are typed data only; the UI renders them via a closed catalog of Angular components mapped from slot id.
2. **CSS scoping by Angular view encapsulation**, plugin does not write CSS; per-plugin tinting is sourced from a kernel-managed palette derived from `pluginId`.
3. **Data path namespaced and BFF-enforced**, `GET /api/contributions/:pluginId/:extensionId/:contributionId?path=...` rejects cross-plugin reads at the route level (the qualified id triple is the URL shape).
4. **Click actions are typed kernel verb dispatches**, a button rendered from a contribution invokes a kernel verb by qualified id; no arbitrary URLs / effects.
5. **AJV at three layers**, manifest at load (rejects unknown `slot` names with `invalid-manifest`), payload at emit (rejects off-shape payloads with `extension.error`), envelope at BFF response.
6. **Renderer attr-sanitization**, the UI's renderer components MUST NOT bind contribution data to `[innerHTML]`, `[style]`, `[src]`, `[href]`, or any DomSanitizer DANGEROUS_ATTR. Lint-enforced in the UI workspace; documented in [`context/view-slots.md`](../context/view-slots.md).
Same honest-note posture as [`plugin-kv-api.md`](./plugin-kv-api.md): isolated against accidents, not hostile code. That is a standing limitation of the current model, an extension runs in the host process; a worker-thread or iframe sandbox would raise the ceiling to hostile code, and none is promised here.
### Soft-warning path for catalog drift
No built-in analyzer covers catalog evolution: the check lives in `sm plugins doctor`, which walks every loaded extension's `ui[*].slot` (built-in and drop-in alike) and reports one `unknown-slot` warning per slot absent from the current kernel catalog, pointing the operator at `sm plugins upgrade `. It is a diagnostic verb warning, NOT an `Issue`: it never reaches the scan output, the aggregated stats, or the exit code. AJV at manifest load already rejects unknown slots as `invalid-manifest`; the doctor pass is the defence-in-depth path for a plugin that stays loaded across a catalog version bump (its `catalogCompat` satisfies the current major syntactically while a slot id it uses was renamed or removed).
### Catalog versioning
The catalog of slots and input-types evolves on its own cadence, independent of the spec version. Plugin manifests carry a required `catalogCompat: string` (semver range) field at the root, parallel to `specCompat`. The kernel checks `semver.satisfies(catalogVersion, plugin.catalogCompat)` at load. Mismatch surfaces as `incompatible-catalog` plugin status (new entry in the load-status enum). Resolution: `sm plugins upgrade ` runs registered migrations from a closed kernel-side registry of `{ from, to, transform }` triples; auto-migration impossible → CLI exit ≠ 0 + UI dialog naming the offending slot / input-type.
Pre-1.0 versioning analyzer (per [`AGENTS.md`](../AGENTS.md)): catalog breaking changes ship as minor bumps while in `0.y.z`; the first `1.0.0` is a deliberate stabilization moment, not a side effect.
### Stability
The **closed catalog of view slots** is stable as of the v1 of this system: adding a new slot is a minor bump; renaming or removing one is a catalog-major bump and triggers `sm plugins upgrade` migration of every dependent plugin.
The **`IViewContribution` manifest shape** (seven fields: `slot`, `label?`, `tooltip?`, `icon?`, `emptyText?`, `emitWhenEmpty?`, `priority?`) is stable. Adding a new optional field is a minor bump; making a field required or removing one is a catalog-major bump.
The **closed catalog of input-types** is stable on the same model: adding minor, renaming/removing major.
The **`ctx.emitContribution(id, payload)` signature** is stable. Adding new context callbacks (e.g. `ctx.emitScopeContribution`) is additive and minor.
The **persistence shape** (`scan_contributions` columns) is stable; column additions are minor bumps. Renames or removals trigger a kernel migration.
The **slot catalog ownership** is spec-level (kernel + spec own it jointly); the UI may rearrange visual placement WITHOUT renaming a slot, the slot id being the public handle while the visual surface beneath evolves. Different driving adapters (UI, future TUI, `sm show --json`) MUST honour the same slot vocabulary; surface-level rendering policy stays adapter-specific (e.g. a TUI may render `card.title.right` as a prefix glyph instead of a right-side marker).
The **isolation honest-note** (accidents, not hostile code) is the same posture as [`plugin-kv-api.md`](./plugin-kv-api.md) and moves together with it if a stronger sandbox (worker thread, iframe) ever lands.
---
## See also
- [`cli-contract.md`](./cli-contract.md), verb surface of the CLI driving adapter.
- [`mcp-server.md`](./mcp-server.md), optional Model Context Protocol server exposed by the Server adapter (`/mcp`): read-only map tools/resources plus the operable queue + findings-lifecycle tools (one toggle, off by default).
- [`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 for security scanners: finder Analyzers over the canonical findings envelope.
---
## Stability
The **port list** is stable as of spec v1.0.0. Adding a sixth port is a major bump.
The **extension kind list** (6 kinds: Provider, Extractor, Analyzer, Action, Formatter, Hook) is stable as of spec v1.0.0. Adding a seventh kind is a major bump. Removing or renaming a kind is a major bump.
The **Hook curated trigger set** (nine events: `boot`, `scan.started`, `scan.completed`, `extractor.completed`, `analyzer.completed`, `action.completed`, `job.completed`, `job.failed`, `shutdown`) is stable as of spec v1.0.0. Adding a tenth trigger is a minor bump; removing or renaming any of the nine is a major bump.
The **execution modes** (`deterministic` / `probabilistic`) and the per-kind mode capability matrix above are stable as of spec v1.0.0. Adding a third mode is a major bump. Renaming or repurposing the mode enum values is a major bump. Pre-1.0, narrowing a kind from dual-mode to single-mode is permitted as a minor bump (Extractor went from `deterministic / probabilistic` to `deterministic-only` in 0.X.0); post-1.0 the same change would be major.
The **dependency analyzers** 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 **Extractor · 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.