@skill-map/cli 0.21.0 → 0.23.0

package/dist/kernel/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Domain types — byte-aligned with `spec/schemas/{node,link,issue,scan-result}.schema.json`.
+ * Domain types, byte-aligned with `spec/schemas/{node,link,issue,scan-result}.schema.json`.
  *
  * The kernel is the reference consumer of the spec; these types are therefore
  * derived from the schemas, not invented. When a schema changes, this file
@@ -11,27 +11,27 @@
  * Five categories with distinct prefix rules; the rules are deliberate
  * even though they look mixed at first read:
  *
- *   1. **Domain types** — every shape that mirrors a `spec/schemas/*.json`
+ *   1. **Domain types**, every shape that mirrors a `spec/schemas/*.json`
  *      file: `Node`, `Link`, `Issue`, `ScanResult`, `ScanStats`,
  *      `ExecutionRecord`, `HistoryStats`, …. **No prefix.** Names track
  *      the spec verbatim because the spec is the source of truth.
  *      Renaming any of these is a spec change.
  *
- *   2. **Hexagonal ports** — the abstract boundaries the kernel calls
+ *   2. **Hexagonal ports**, the abstract boundaries the kernel calls
  *      out to (`StoragePort`, `RunnerPort`, `ProgressEmitterPort`,
  *      `FilesystemPort`, `PluginLoaderPort`). **`Port` suffix.** The
  *      suffix calls out the architectural role and avoids name clashes
  *      with the concrete adapter classes (`SqliteStorageAdapter`
  *      implements `StoragePort`).
  *
- *   3. **Runtime extension contracts** — what a plugin author
+ *   3. **Runtime extension contracts**, what a plugin author
  *      implements: `IProvider`, `IExtractor`, `IAnalyzer`, `IFormatter`,
  *      `IExtensionBase`. **`I` prefix.** The prefix flags "this is a
- *      contract you supply, not a value the kernel hands you" — same
+ *      contract you supply, not a value the kernel hands you", same
  *      reading as the rest of TypeScript's plugin ecosystems where a
  *      shape is implementable.
  *
- *   4. **Internal interfaces** — option bags, result records, config
+ *   4. **Internal interfaces**, option bags, result records, config
  *      slices, anything declared as `interface` and passed across
  *      function boundaries inside the kernel / CLI but not part of the
  *      spec: `IPluginRuntimeBundle`, `IPruneResult`, `IMigrationFile`,
@@ -39,7 +39,7 @@
  *      category 3 because both are "shapes that live in TypeScript
  *      only, never in JSON".
  *
- *   5. **Internal type aliases** — anything declared as `type` (string-
+ *   5. **Internal type aliases**, anything declared as `type` (string-
  *      literal unions, function types, mapped/derived types) that lives
  *      only in TS: `TLogLevel`, `TLogMethodLevel`, `TProgressListener`,
  *      `TLogFormatter`, `TActionWrite`, `TExecutionMode`, `TGranularity`,
@@ -67,7 +67,7 @@
  * for `interface`, `T` prefix for `type` aliases.
  */
 /**
- * The four node kinds the **built-in Claude Provider** declares — `skill`,
+ * The four node kinds the **built-in Claude Provider** declares, `skill`,
  * `agent`, `command`, `note`. **NOT** the kernel-wide kind type.
  *
  * `Node.kind` is `string`. An external Provider (Cursor, Obsidian, …)
@@ -78,13 +78,13 @@
  * (matches `IProvider.kinds` "open by design" docstring).
  *
  * Step 9.5 dropped `hook` from the catalog: `.claude/hooks/*.md` is NOT
- * an Anthropic-defined node type — hooks live in `settings.json` or as
+ * an Anthropic-defined node type, hooks live in `settings.json` or as
  * sub-objects of agent / skill frontmatter (see
  * https://code.claude.com/docs/en/hooks.md). Files at the old path
  * classify as `markdown` via the Provider's fallback. The fallback is
  * named after the *format* because the file is generic markdown with
  * no specific role; format-named kinds apply only as the generic
- * fallback — a file that matches a specific role (agent / command /
+ * fallback, a file that matches a specific role (agent / command /
  * skill) classifies under that role, not under `markdown`.
  *
  * This alias survives because:
@@ -108,9 +108,9 @@ type Stability = 'experimental' | 'stable' | 'deprecated';
  * Execution mode of an analytical extension. Mirrors the per-kind capability
  * matrix in `spec/architecture.md` §Execution modes:
  *
- *   - `deterministic` — pure code, runs synchronously inside `sm scan` /
+ *   - `deterministic`, pure code, runs synchronously inside `sm scan` /
  *     `sm check`. Same input → same output, every run.
- *   - `probabilistic` — calls an LLM through `RunnerPort`, dispatches only
+ *   - `probabilistic`, calls an LLM through `RunnerPort`, dispatches only
  *     as a queued job (`sm job submit <kind>:<id>`); never participates in
  *     scan-time pipelines.
  *
@@ -154,7 +154,7 @@ interface Node {
     frontmatter?: Record<string, unknown>;
     tokens?: TripleSplit;
     /**
-     * Step 9.6.2 — sidecar denormalisation surface. Populated by the
+     * Step 9.6.2, sidecar denormalisation surface. Populated by the
      * orchestrator at scan time; absent when the orchestrator did not
      * inspect sidecars (legacy code paths) or when no sidecar accompanies
      * the node. Read by `annotation-stale` rule and the persistence layer.
@@ -165,7 +165,7 @@ interface Node {
      * `/api/nodes/:pathB64` responses via in-memory `Set` lookup against
      * `state_node_favorites`. Absent on emissions that don't carry per-user
      * state (e.g. `sm export --json`); consumers that don't recognise the
-     * field MUST treat the absence as "unknown" rather than "false" — a
+     * field MUST treat the absence as "unknown" rather than "false", a
      * truthy `isFavorite` only ever lands when the BFF set it.
      */
     isFavorite?: boolean;
@@ -187,25 +187,25 @@ interface ISidecarOverlay {
     present: boolean;
     status?: SidecarStatus | null;
     /**
-     * Parsed `annotations:` block. Untyped object — schema lives in
+     * Parsed `annotations:` block. Untyped object, schema lives in
      * `spec/schemas/annotations.schema.json`. Null when no sidecar or
      * the block is empty/absent.
      */
     annotations?: Record<string, unknown> | null;
     /**
-     * R15 closure (2026-05-07) — full parsed YAML root of the sidecar
+     * R15 closure (2026-05-07), full parsed YAML root of the sidecar
      * (the entire `.sm` payload, mirroring `sidecar.schema.json`). Surfaced
      * so the UI inspector can render `for:`, `audit:`, `settings:`, and
      * `<plugin-id>:` namespace blocks without re-reading the file. NULL
      * when no sidecar is present, or when the sidecar exists but failed
-     * to parse / validate. The `annotations` field above stays — it
+     * to parse / validate. The `annotations` field above stays, it
      * duplicates `root.annotations` intentionally so existing consumers
      * keep working unchanged.
      */
     root?: Record<string, unknown> | null;
 }
 interface Link {
-    /** The originating node — the path of the file the extractor was reading
+    /** The originating node, the path of the file the extractor was reading
      *  when it emitted this link. Singular, NOT to be confused with
      *  `sources` (plural) below. */
     source: string;
@@ -353,7 +353,7 @@ interface ScanResult {
     scope: 'project' | 'global';
     /**
      * Filesystem roots that were walked during this scan. Spec requires
-     * `minItems: 1` — `runScan` throws if `roots: []` is supplied.
+     * `minItems: 1`, `runScan` throws if `roots: []` is supplied.
      */
     roots: string[];
     /** Provider ids that participated in classification. Empty if no Provider matched. */
@@ -367,14 +367,14 @@ interface ScanResult {
 }
 
 /**
- * Extension registry — six kinds, first-class, loaded through a single API.
+ * Extension registry, six kinds, first-class, loaded through a single API.
  *
  * The `Extension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
  * Kind-specific manifests (provider / extractor / analyzer / action / formatter /
  * hook) extend this base structurally; the registry stores the base view
  * and each kind's code carries its own fuller type where needed.
  *
- * **Spec § A.6 — qualified ids.** Every extension is keyed in the registry
+ * **Spec § A.6, qualified ids.** Every extension is keyed in the registry
  * by `<pluginId>/<id>` (e.g. `core/annotations`, `core/slash`,
  * `hello-world/greet`). `Extension.id` carries the **short** id as authored;
  * `Extension.pluginId` carries the namespace; the registry composes the
@@ -429,18 +429,18 @@ declare class Registry {
 }
 
 /**
- * Step 9.6.6 — runtime annotation-contribution catalog types.
+ * Step 9.6.6, runtime annotation-contribution catalog types.
  *
  * Lives in its own module (rather than `kernel/index.ts`) so consumers
- * deep inside the kernel — `IAnalyzerContext`, the BFF route factories,
- * future Action contexts — can depend on the catalog shape without
+ * deep inside the kernel, `IAnalyzerContext`, the BFF route factories,
+ * future Action contexts, can depend on the catalog shape without
  * dragging the whole kernel barrel and risking a cycle.
  */
 /**
  * Single row of the runtime annotation-contribution catalog surfaced by
  * `kernel.getRegisteredAnnotationKeys()`. One row per (plugin × key)
  * tuple. Built-in catalog keys from `annotations.schema.json` are NOT
- * included — this catalog is plugin-only; the UI knows the built-in
+ * included, this catalog is plugin-only; the UI knows the built-in
  * catalog via the schema bundle.
  */
 interface IRegisteredAnnotationKey {
@@ -453,17 +453,17 @@ interface IRegisteredAnnotationKey {
 }
 
 /**
- * Step 11.x — runtime view-contribution catalog types.
+ * Step 11.x, runtime view-contribution catalog types.
  *
  * Lives in its own module (rather than `kernel/index.ts`) so consumers
- * deep inside the kernel — `IAnalyzerContext`, the BFF route factories,
- * future Action contexts — can depend on the catalog shape without
+ * deep inside the kernel, `IAnalyzerContext`, the BFF route factories,
+ * future Action contexts, can depend on the catalog shape without
  * dragging the whole kernel barrel and risking a cycle.
  *
  * Mirrors `annotation-catalog.ts` for the annotation contribution side
  * (Step 9.6.6). The two systems share the "plugin contributes data,
  * kernel exposes catalog, UI renders" pattern but never overlap in
- * storage or routing — see `architecture.md` §View contribution system
+ * storage or routing, see `architecture.md` §View contribution system
  * for the comparison table.
  *
  * **Closed catalog by design.** Both `TSlotName` and `TInputTypeName`
@@ -545,7 +545,7 @@ interface IViewContribution {
      * `order: 'priority'` sort contributions ASC by this value, with
      * alphabetical tie-break by qualified id. The plugin uses this to
      * suggest where its contribution belongs relative to others sharing
-     * the same slot — the slot has the final say.
+     * the same slot, the slot has the final say.
      */
     priority?: number;
 }
@@ -556,7 +556,7 @@ interface IViewContribution {
  * by `loadPluginRuntime` from every loaded extension's
  * `viewContributions` map.
  *
- * The qualified id is `<pluginId>/<extensionId>/<contributionId>` —
+ * The qualified id is `<pluginId>/<extensionId>/<contributionId>`,
  * matches the qualified id pattern used elsewhere in the kernel
  * (`<pluginId>/<extensionId>` for extensions; this adds the third
  * segment for per-contribution identity).
@@ -662,7 +662,7 @@ interface ISetting_KeyValueList extends ISettingCommon {
 }
 /**
  * Discriminated union of every setting declaration shape. The plugin
- * author NEVER writes JSON Schema for settings — they pick one of
+ * author NEVER writes JSON Schema for settings, they pick one of
  * these `type` values and supply per-type parameters.
  *
  * Mirror of `input-types.schema.json#/$defs/ISettingDeclaration`.
@@ -680,7 +680,7 @@ type TSettingValue = string | string[] | boolean | number | ISetting_KeyValueLis
  * Base manifest shape shared by every extension kind. Mirrors
  * `spec/schemas/extensions/base.schema.json` at the TypeScript level.
  *
- * Spec § A.6 — every extension is identified in the registry by the
+ * Spec § A.6, every extension is identified in the registry by the
  * qualified id `<pluginId>/<id>`. The `pluginId` field is required at the
  * runtime / TS level: built-ins declare it directly in
  * `src/extensions/built-ins.ts`; user plugins have it injected by the
@@ -688,7 +688,7 @@ type TSettingValue = string | string[] | boolean | number | ISetting_KeyValueLis
  * registry. A plugin author who hand-codes a `pluginId` that disagrees
  * with the manifest's `id` is rejected as `invalid-manifest`.
  *
- * The JSON Schema deliberately does NOT model `pluginId` — the qualifier
+ * The JSON Schema deliberately does NOT model `pluginId`, the qualifier
  * is a runtime concern composed by the loader, not a manifest field
  * authors are expected to set. Stripping it before AJV validation in
  * the loader keeps the spec contract clean ("authors declare only the
@@ -696,7 +696,7 @@ type TSettingValue = string | string[] | boolean | number | ISetting_KeyValueLis
  */
 
 /**
- * Step 9.6.6 — single entry of an extension's `annotationContributions`
+ * Step 9.6.6, single entry of an extension's `annotationContributions`
  * map. Mirrors `spec/schemas/extensions/base.schema.json#/properties/annotationContributions/additionalProperties`.
  *
  * `schema` is an INLINE JSON Schema (object literal in the manifest),
@@ -707,14 +707,14 @@ interface IAnnotationContribution {
     /** Inline JSON Schema describing the value written under this key. */
     schema: Record<string, unknown>;
     /**
-     * Conflict policy. `shared` (default) — multiple plugins MAY write
-     * the key; `exclusive` — only this plugin may. REQUIRED to be
+     * Conflict policy. `shared` (default), multiple plugins MAY write
+     * the key; `exclusive`, only this plugin may. REQUIRED to be
      * `'exclusive'` when `location: 'root'`.
      */
     ownership?: 'exclusive' | 'shared';
     /**
-     * Where the key lands. `namespaced` (default) — under the plugin's
-     * `<plugin-id>:` block; `root` — top-level, alongside `for` /
+     * Where the key lands. `namespaced` (default), under the plugin's
+     * `<plugin-id>:` block; `root`, top-level, alongside `for` /
      * `annotations` / `settings` / `audit`. Cross-plugin root-key
      * collisions on `exclusive` are a fatal startup error.
      */
@@ -735,7 +735,7 @@ interface IExtensionBase {
     preconditions?: string[];
     entry?: string;
     /**
-     * Step 9.6.6 — plugin-contributed annotation keys. Each entry maps a
+     * Step 9.6.6, plugin-contributed annotation keys. Each entry maps a
      * key name to an inline JSON Schema + ownership + location triple.
      * The kernel surfaces the aggregate via `kernel.getRegisteredAnnotationKeys()`.
      * See `IAnnotationContribution` for the field semantics and
@@ -747,7 +747,7 @@ interface IExtensionBase {
      * contribution id (kebab-case, unique within the extension) to a
      * `IViewContribution` declaration that picks a view slot by name
      * from the closed kernel catalog (`view-catalog.ts#TSlotName`).
-     * The slot fixes both the renderer and the payload shape — there
+     * The slot fixes both the renderer and the payload shape, there
      * is no separate "contract" abstraction. The kernel validates each
      * `slot` pick at load time (`invalid-manifest` on miss); the plugin
      * emits per-node payloads via `ctx.emitContribution(<contributionId>,
@@ -759,55 +759,6 @@ interface IExtensionBase {
     viewContributions?: Record<string, IViewContribution>;
 }
 
-/**
- * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
- * with the project-local layering: bundled defaults → `config.ignore`
- * (from `.skill-map/settings.json`) → `.skillmapignore` file content.
- *
- * Why a wrapper instead of exposing `ignore` directly:
- *
- * 1. Single-source defaults — `src/config/defaults/skillmapignore` is
- *    the canonical default list, loaded once at module init (or at
- *    explicit build time, depending on bundling). The runtime never
- *    re-reads it per scan.
- * 2. Stable interface — Providers and the orchestrator depend on a
- *    minimal `IIgnoreFilter` shape, so the underlying library can be
- *    swapped without touching every consumer.
- * 3. Path normalization — every consumer passes the path RELATIVE to
- *    the scan root (POSIX separators); the wrapper guarantees that
- *    contract before delegating to `ignore`.
- */
-interface IIgnoreFilter {
-    /**
-     * Returns `true` when `relativePath` should be skipped. The caller
-     * MUST pass paths relative to the scan root, with POSIX separators
-     * (forward slashes), no leading `/`. Directories MAY be passed with
-     * or without trailing `/`; the wrapper does not require it.
-     */
-    ignores(relativePath: string): boolean;
-}
-
-/**
- * `ProgressEmitterPort` — emits progress events during long operations.
- *
- * Shape-only today. The full event catalog (`run.started`,
- * `job.claimed`, `model.delta`, etc.) is normative in
- * `spec/job-events.md`; this port carries an open `data` payload so
- * adapters can emit any documented event without type churn.
- */
-interface ProgressEvent {
-    type: string;
-    timestamp: string;
-    runId?: string;
-    jobId?: string;
-    data?: unknown;
-}
-type TProgressListener = (event: ProgressEvent) => void;
-interface ProgressEmitterPort {
-    emit(event: ProgressEvent): void;
-    subscribe(listener: TProgressListener): () => void;
-}
-
 /**
  * Plugin-surface types, hand-written to mirror
  * `spec/schemas/plugins-registry.schema.json#/$defs/PluginManifest` and the
@@ -817,7 +768,7 @@ interface ProgressEmitterPort {
  * typed DTOs from `@skill-map/spec` is deferred to a future iteration when a
  * third consumer (real providers / extractors / rules) forces a single
  * source of truth. Until then, both `ui/src/models/` and `src/kernel/types/`
- * hand-curate their own local mirror — the risk of drift is accepted at
+ * hand-curate their own local mirror, the risk of drift is accepted at
  * this scale (17 schemas) and flagged in the roadmap.
  */
 
@@ -827,7 +778,7 @@ interface ProgressEmitterPort {
  * tables with explicit migrations (mode `dedicated`). Absent = the plugin
  * does not persist state at all.
  *
- * Optional output-schema declarations (spec § A.12 — opt-in correctness
+ * Optional output-schema declarations (spec § A.12, opt-in correctness
  * for plugin custom storage):
  *   - Mode `kv` → `schema` (single relative path). Validates the value
  *     written by `ctx.store.set(key, value)`.
@@ -851,13 +802,13 @@ type TPluginStorage = {
 /**
  * Toggle granularity for a plugin / built-in bundle.
  *
- * - `'bundle'`  — the plugin id is the only enable/disable key. The whole
+ * - `'bundle'` , the plugin id is the only enable/disable key. The whole
  *                 bundle of extensions follows the toggle; the user cannot
  *                 enable some extensions of the bundle and disable others.
  *                 Default for plugins (and for the built-in `claude`
  *                 bundle, where the provider and its kind-aware extractors
  *                 form a coherent provider).
- * - `'extension'` — each extension is independently toggle-able under its
+ * - `'extension'`, each extension is independently toggle-able under its
  *                   qualified id `<plugin-id>/<extension-id>`. Used for
  *                   the built-in `core` bundle (every kernel built-in
  *                   rule / formatter is removable per spec
@@ -894,7 +845,7 @@ interface IPluginManifest {
      * Plugin user-configurable settings. Each entry picks an `input-type`
      * from the closed catalog at
      * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
-     * The plugin author NEVER writes JSON Schema — they pick `type` by
+     * The plugin author NEVER writes JSON Schema, they pick `type` by
      * name and supply per-type parameters. The kernel exposes resolved
      * settings to extractors via `ctx.settings.<settingId>`; settings
      * are read once at extractor invocation; changing a setting requires
@@ -913,29 +864,31 @@ interface IPluginManifest {
  *
  * - `incompatible-spec`: manifest parsed fine but `semver.satisfies` failed
  *   against the installed `@skill-map/spec` version.
- * - `invalid-manifest`: `plugin.json` missing, unparseable, or failing AJV.
- * - `load-error`: manifest passed but an extension module failed to import
- *   or the imported manifest failed its extension-kind schema.
+ * - `invalid-manifest`: `plugin.json` missing, unparseable, failing AJV on
+ *   the base manifest schema, OR the exported extension shape failed its
+ *   kind-specific schema (per spec/architecture.md §Plugin discovery,
+ *   "AJV rejects unknown `slot` names with `invalid-manifest`").
+ * - `load-error`: manifest parsed but an extension module failed to import.
  */
 /**
  * Possible outcomes after the loader sees a plugin.json. Mirrors the
  * `status` enum in `spec/schemas/plugins-registry.schema.json`.
  *
- * - `enabled`             — manifest valid, specCompat satisfied, every
+ * - `enabled`            , manifest valid, specCompat satisfied, every
  *                           extension imported and validated.
- * - `disabled`            — user-toggled off via `sm plugins disable` or
+ * - `disabled`           , user-toggled off via `sm plugins disable` or
  *                           `settings.json#/plugins/<id>/enabled`. Manifest
  *                           is parsed and surfaced (so `sm plugins list`
  *                           shows it), but extensions are not imported.
- * - `incompatible-spec`   — manifest parsed but `semver.satisfies` failed.
- * - `invalid-manifest`    — `plugin.json` missing, unparseable, AJV-fails,
+ * - `incompatible-spec`  , manifest parsed but `semver.satisfies` failed.
+ * - `invalid-manifest`   , `plugin.json` missing, unparseable, AJV-fails,
  *                           OR the directory name does not equal the
  *                           manifest id (a cheap structural rule that
  *                           rules out same-root collisions by construction:
  *                           a filesystem cannot contain two siblings with
  *                           the same name).
- * - `load-error`          — manifest passed, an extension module failed.
- * - `id-collision`        — two plugins reachable from different roots
+ * - `load-error`         , manifest passed, an extension module failed.
+ * - `id-collision`       , two plugins reachable from different roots
  *                           (project + global, or any `--plugin-dir`
  *                           combination) declared the same `id`. Both
  *                           collided plugins receive this status; no
@@ -947,7 +900,7 @@ interface ILoadedExtension {
     kind: ExtensionKind;
     id: string;
     /**
-     * Owning plugin namespace — `manifest.id` of the `plugin.json` that
+     * Owning plugin namespace, `manifest.id` of the `plugin.json` that
      * declared this extension. Composed with `id` to form the qualified
      * registry key `<pluginId>/<id>`. Per spec § A.6 the loader injects
      * this from the manifest; an extension that hand-declares a
@@ -959,7 +912,7 @@ interface ILoadedExtension {
     /** Raw module namespace as returned by the dynamic `import()`. */
     module: unknown;
     /**
-     * Runtime extension instance ready for the registry / orchestrator —
+     * Runtime extension instance ready for the registry / orchestrator,
      * the `default` export of `module` (or the module itself when no
      * default), shallow-cloned with `pluginId` injected per spec § A.6.
      *
@@ -973,7 +926,7 @@ interface ILoadedExtension {
 interface IDiscoveredPlugin {
     /** Absolute path to the plugin directory. */
     path: string;
-    /** Plugin id — populated from the manifest if it parsed, else a path hint. */
+    /** Plugin id, populated from the manifest if it parsed, else a path hint. */
     id: string;
     status: TPluginLoadStatus;
     /** Only present when status === 'enabled' or 'incompatible-spec'. */
@@ -987,20 +940,20 @@ interface IDiscoveredPlugin {
      */
     granularity?: TGranularity;
     /**
-     * Runtime-only — never persisted, never spec-modeled.
+     * Runtime-only, never persisted, never spec-modeled.
      *
-     * Spec § A.12 — opt-in JSON Schema validation for plugin custom storage.
+     * Spec § A.12, opt-in JSON Schema validation for plugin custom storage.
      * Populated by the loader when `manifest.storage.schemas` (Mode B) or
      * `manifest.storage.schema` (Mode A) declares schema paths the loader
      * successfully read and AJV-compiled. Consumed by the runtime store
      * wrapper to validate `ctx.store.write(table, row)` (Mode B) and
      * `ctx.store.set(key, value)` (Mode A) before persisting.
      *
-     * Mode B layout — keyed by logical table name (without the
+     * Mode B layout, keyed by logical table name (without the
      * `plugin_<normalizedId>_` prefix), matching the manifest's `schemas`
      * map. Tables not present in the map accept any shape (permissive).
      *
-     * Mode A layout — uses the sentinel key `__kv__` for the single
+     * Mode A layout, uses the sentinel key `__kv__` for the single
      * value-shape schema. The sentinel survives the runtime contract change
      * if Mode A ever grows multiple namespaces.
      *
@@ -1013,7 +966,7 @@ interface IDiscoveredPlugin {
     reason?: string;
 }
 /**
- * Runtime-only — a single AJV-compiled storage schema attached to a
+ * Runtime-only, a single AJV-compiled storage schema attached to a
  * loaded plugin. The schema path (relative to the plugin directory) is
  * preserved so error messages can name the offending file. `validate`
  * is the AJV `ValidateFunction` itself: it returns `true` on shape
@@ -1035,20 +988,20 @@ interface IPluginStorageSchema {
 }
 
 /**
- * Plugin store wrappers — runtime injection for `ctx.store` per spec
+ * Plugin store wrappers, runtime injection for `ctx.store` per spec
  * § A.12 (opt-in `outputSchema` for plugin custom storage).
  *
  * Two shapes, mirroring the manifest's storage modes documented in
  * `spec/plugin-kv-api.md`:
  *
- *   - Mode A — `KvStore.set(key, value)`. AJV-validates `value` against
+ *   - Mode A, `KvStore.set(key, value)`. AJV-validates `value` against
  *     the schema declared by `manifest.storage.schema` (single
  *     value-shape) when present. Absent = permissive.
- *   - Mode B — `DedicatedStore.write(table, row)`. AJV-validates `row`
+ *   - Mode B, `DedicatedStore.write(table, row)`. AJV-validates `row`
  *     against the per-table schema declared in `manifest.storage.schemas`
  *     when present. Tables absent from the map accept any shape.
  *
- * Both wrappers are storage-engine agnostic — they accept a `persist`
+ * Both wrappers are storage-engine agnostic, they accept a `persist`
  * callback the caller supplies. The persistence side (SQLite, in-memory,
  * mock) is the caller's concern; this wrapper's only job is the
  * AJV gate. That separation lets the test suite exercise the validator
@@ -1057,7 +1010,7 @@ interface IPluginStorageSchema {
  * unchanged.
  *
  * Universal validation (`emitLink` against `link.schema.json`,
- * `enrichNode` against `node.schema.json`) is unaffected — it lives on
+ * `enrichNode` against `node.schema.json`) is unaffected, it lives on
  * the orchestrator side and runs regardless of the plugin's
  * `outputSchema` opt-in.
  */
@@ -1083,7 +1036,7 @@ interface IDedicatedStorePersist {
  * schema path and AJV errors; persistence is skipped on failure.
  *
  * `pluginId` is captured for diagnostics (the throw message names the
- * plugin). The wrapper does NOT itself scope by plugin id — that is
+ * plugin). The wrapper does NOT itself scope by plugin id, that is
  * the persistence layer's job (the spec's `state_plugin_kvs` PK includes
  * `pluginId` and the kernel-side adapter prepends it before write).
  */
@@ -1091,7 +1044,7 @@ interface IKvStoreWrapper {
     set(key: string, value: unknown): Promise<void>;
 }
 /**
- * Union shape exposed to extractors via `ctx.store`. Spec § A.12 — Mode A
+ * Union shape exposed to extractors via `ctx.store`. Spec § A.12, Mode A
  * (`kv`) returns a `set(key, value)` surface; Mode B (`dedicated`) returns
  * `write(table, row)`. Plugin authors narrow at the call site based on
  * the storage mode declared in their `plugin.json`.
@@ -1105,7 +1058,7 @@ declare function makeKvStoreWrapper(opts: {
 /**
  * Mode B wrapper. `write(table, row)` AJV-validates `row` against
  * `storageSchemas[table]` when declared, then forwards to `persist`.
- * Tables absent from the map are permissive — the wrapper forwards
+ * Tables absent from the map are permissive, the wrapper forwards
  * straight to `persist` without validation.
  *
  * The wrapper accepts the full `storageSchemas` map (rather than a
@@ -1135,7 +1088,7 @@ declare function makePluginStore(opts: {
 }): IPluginStore | undefined;
 
 /**
- * `scan_contributions` adapter — replace-all writer used by
+ * `scan_contributions` adapter, replace-all writer used by
  * `persistScanResult`, plus read helpers consumed by the BFF
  * (`/api/contributions/...`) and rules (`core/contribution-orphan`).
  *
@@ -1148,7 +1101,7 @@ declare function makePluginStore(opts: {
  * scan is a fresh snapshot, so prior rows are deleted before insert.
  * Wrapped in the same transaction `persistScanResult` opens.
  *
- * The rename heuristic does NOT need to migrate `node_path` here —
+ * The rename heuristic does NOT need to migrate `node_path` here,
  * because of replace-all, every contribution is re-emitted on the new
  * path automatically. Keeping the rename path lighter than `state_*`
  * (which IS rename-migrated because state survives across scans).
@@ -1168,7 +1121,7 @@ interface IContributionRecord {
     contributionId: string;
     /**
      * Closed enum value mirroring `view-slots.schema.json#/$defs/SlotName`.
-     * Persisted as TEXT (no SQL CHECK by design — see migration comment).
+     * Persisted as TEXT (no SQL CHECK by design, see migration comment).
      */
     slot: string;
     /** Already-validated payload. Serialised via `JSON.stringify` at write. */
@@ -1192,7 +1145,7 @@ interface IPersistedContribution {
 }
 
 /**
- * `loadScanResult` — driving inverse of `persistScanResult`. Reads the
+ * `loadScanResult`, driving inverse of `persistScanResult`. Reads the
  * `scan_*` tables and reconstructs a `ScanResult` shape so the
  * orchestrator can run an incremental scan (`sm scan --changed`) on
  * top of a prior snapshot.
@@ -1205,7 +1158,7 @@ interface IPersistedContribution {
  *
  * **Documented omission**: external pseudo-links (those whose target is
  * an `http://` / `https://` URL emitted by the external-url-counter
- * extractor) are NEVER persisted to `scan_links` — only their per-node
+ * extractor) are NEVER persisted to `scan_links`, only their per-node
  * count survives in `scan_nodes.external_refs_count`. Therefore the
  * `result.links` returned by `loadScanResult` contains only internal
  * graph links, and `node.externalRefsCount` is the authoritative count
@@ -1232,11 +1185,11 @@ interface IPersistedContribution {
  *     `durationMs`; the three count fields derive from row counts.
  *
  * Both branches keep `nodesCount` / `linksCount` / `issuesCount` derived
- * from `COUNT(*)` of the loaded rows — never persisted, always recomputed.
+ * from `COUNT(*)` of the loaded rows, never persisted, always recomputed.
  */
 
 /**
- * Spec § A.9 — load the fine-grained Extractor cache as a per-node map
+ * Spec § A.9, load the fine-grained Extractor cache as a per-node map
  * from qualified extractor id (`<pluginId>/<id>`) to the run-time
  * hashes the extractor recorded on its last run. Empty map is the
  * default when the table is empty (fresh DB, never-scanned scope, or
@@ -1252,6 +1205,61 @@ interface IPriorExtractorRun {
     sidecarAnnotationsHash: string;
 }
 
+/**
+ * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
+ * with the project-local layering: bundled defaults → `config.ignore`
+ * (from `.skill-map/settings.json`) → `.skillmapignore` file content.
+ *
+ * Why a wrapper instead of exposing `ignore` directly:
+ *
+ * 1. Single-source defaults, `src/config/defaults/skillmapignore` is
+ *    the canonical default list, loaded once at module init (or at
+ *    explicit build time, depending on bundling). The runtime never
+ *    re-reads it per scan.
+ * 2. Stable interface, Providers and the orchestrator depend on a
+ *    minimal `IIgnoreFilter` shape, so the underlying library can be
+ *    swapped without touching every consumer.
+ * 3. Path normalization, every consumer passes the path RELATIVE to
+ *    the scan root (POSIX separators); the wrapper guarantees that
+ *    contract before delegating to `ignore`.
+ */
+interface IIgnoreFilter {
+    /**
+     * Returns `true` when `relativePath` should be skipped. The caller
+     * MUST pass paths relative to the scan root, with POSIX separators
+     * (forward slashes), no leading `/`. Directories MAY be passed with
+     * or without trailing `/`; the wrapper does not require it.
+     */
+    ignores(relativePath: string): boolean;
+}
+
+/**
+ * Diagnostic surfaced by a parser when the raw input was structurally
+ * malformed (e.g. YAML parse error). The parser MUST still return a
+ * usable `{ frontmatter, frontmatterRaw, body }` triple (defaults are
+ * fine) so the scan keeps making progress; this carries the message
+ * the orchestrator translates into a kernel `Issue` with severity
+ * `warn` (and `error` under `--strict`).
+ *
+ * Pure data: parsers never log or throw; they describe the failure
+ * here and let the orchestrator decide how to surface it.
+ */
+interface IParseIssue {
+    /**
+     * Stable tag describing the failure class. The only emitter today
+     * is `frontmatter-yaml` reporting a YAML parse error
+     * (`'frontmatter-parse-error'`); the set may grow as new parsers
+     * land.
+     */
+    code: string;
+    /**
+     * Human-readable message, sanitised. Never includes the raw input
+     * (a hostile YAML could embed multi-line garbage); only the
+     * parser-error string is interpolated.
+     */
+    message: string;
+}
+
 /**
  * Provider runtime contract. Walks filesystem roots and emits raw node
  * records; classification maps path conventions to a node kind.
@@ -1286,6 +1294,14 @@ interface IRawNode {
     frontmatterRaw: string;
     /** Parsed frontmatter, or `{}` when absent / unparseable. */
     frontmatter: Record<string, unknown>;
+    /**
+     * Parser diagnostics (audit L1). Populated by the walker when the
+     * parser surfaced `IParseIssue` entries (e.g. malformed YAML).
+     * Carried through `processRawNode` and converted into warn-level
+     * kernel `Issue` rows inside `buildFreshNodeAndValidateFrontmatter`.
+     * Empty / undefined on the happy path.
+     */
+    parseIssues?: readonly IParseIssue[];
 }
 /**
  * One entry in a Provider's `kinds` map. Declares both the per-kind
@@ -1341,7 +1357,7 @@ interface IProviderKind {
  * intent (label + base color, optional dark variant + emoji + icon);
  * the UI derives `bg`/`fg` tints per theme via a deterministic helper
  * and reads the registry from the `kindRegistry` field embedded in REST
- * envelopes. Single source of truth for what a kind looks like — the
+ * envelopes. Single source of truth for what a kind looks like, the
  * UI never hardcodes presentation for a built-in kind.
  */
 interface IProviderKindUi {
@@ -1395,15 +1411,6 @@ type TProviderKindIcon = {
 };
 interface IProvider extends IExtensionBase {
     kind: 'provider';
-    /**
-     * Filesystem directory (relative to user home or project root) where this
-     * Provider's content lives. Required. Examples: `'~/.claude'` for the
-     * Claude Provider, `'~/.cursor'` for a hypothetical Cursor Provider.
-     * The kernel walks this directory during boot/scan to discover nodes;
-     * `sm doctor` validates the directory exists and emits a non-blocking
-     * warning when it does not.
-     */
-    explorationDir: string;
     /**
      * Catalog of node kinds this Provider emits. Keyed by kind name. Every
      * kind the Provider can `classify()` MUST have an entry; an entry is
@@ -1426,12 +1433,12 @@ interface IProvider extends IExtensionBase {
      * per-kind schemas compile, so cross-file `$ref` resolution succeeds.
      *
      * Use case: when several kinds share a common base (e.g. Anthropic's
-     * merged skill / command frontmatter — both extend a shared
+     * merged skill / command frontmatter, both extend a shared
      * `skill-base.schema.json`), the Provider declares the base here so
      * `skill.schema.json` and `command.schema.json` can `$ref` it without
      * duplicating fields.
      *
-     * Runtime-only — does NOT appear in the spec's `provider.schema.json`
+     * Runtime-only, does NOT appear in the spec's `provider.schema.json`
      * manifest. Manifest-validated schemas remain the per-kind ones in
      * `kinds[<kind>].schema`; auxiliary schemas are an implementation
      * concern of how the runtime composes those.
@@ -1449,7 +1456,7 @@ interface IProvider extends IExtensionBase {
      * so the most common Provider shape needs zero configuration.
      *
      * Precedence: when both `walk()` (runtime field) and `read` are
-     * declared, `walk()` wins — `read` is ignored. The escape-hatch
+     * declared, `walk()` wins, `read` is ignored. The escape-hatch
      * relationship is intentional: most Providers should use `read`;
      * Providers with non-standard discovery requirements (custom file
      * naming, multi-pass walks, dynamic ignore logic) implement `walk()`
@@ -1466,7 +1473,7 @@ interface IProvider extends IExtensionBase {
      * Non-matching files are silently skipped. Unreadable files produce
      * a diagnostic via the emitter but do not abort the walk.
      *
-     * `options.ignoreFilter` — when supplied, the Provider MUST
+     * `options.ignoreFilter`, when supplied, the Provider MUST
      * skip every directory and file whose path-relative-to-root the
      * filter reports as ignored. Providers MAY also keep their own
      * hard-coded skip list (e.g. `.git`) as a defensive measure, but the
@@ -1474,14 +1481,14 @@ interface IProvider extends IExtensionBase {
      *
      * Optional. When omitted, the Provider MUST declare `read` (or rely
      * on the default config). The orchestrator never calls `walk()`
-     * directly — it goes through `resolveProviderWalk(provider)` which
+     * directly, it goes through `resolveProviderWalk(provider)` which
      * picks `walk` over `read`.
      */
     walk?(roots: string[], options?: {
         ignoreFilter?: IIgnoreFilter;
     }): AsyncIterable<IRawNode>;
     /**
-     * Given a path and its parsed frontmatter, decide the node kind — or
+     * Given a path and its parsed frontmatter, decide the node kind, or
      * `null` to disclaim the file. The classifier is called after walk()
      * yields; with multiple Providers active, every Provider walks every
      * file matching its `read.extensions`, so each Provider MUST disclaim
@@ -1528,18 +1535,18 @@ interface IProviderReadConfig {
  * Extractors are deterministic-only. They run synchronously inside the
  * scan loop; LLM-driven enrichment of a node is an Action concern, not
  * an Extractor concern. The Extractor context therefore exposes no
- * `RunnerPort` — see spec `architecture.md` §Execution modes.
+ * `RunnerPort`, see spec `architecture.md` §Execution modes.
  *
  * Output channels (all on the context):
  *
- *   - `ctx.emitLink(link)` — persist a link in the kernel's `links` table.
+ *   - `ctx.emitLink(link)`, persist a link in the kernel's `links` table.
  *     Validated against `emitsLinkKinds` before insertion; an off-contract
  *     kind drops the link and surfaces an `extension.error` event.
- *   - `ctx.enrichNode(partial)` — merge canonical, kernel-curated properties
+ *   - `ctx.enrichNode(partial)`, merge canonical, kernel-curated properties
  *     onto the node. Strictly separate from the author-supplied frontmatter
  *     (the latter remains immutable and survives verbatim). Persistence
  *     is spec'd in § A.8.
- *   - `ctx.store` — plugin-scoped persistence. Present only when the
+ *   - `ctx.store`, plugin-scoped persistence. Present only when the
  *     plugin declares `storage.mode` in `plugin.json`; shape depends on the
  *     mode (`KvStore` for mode A, scoped `Database` for mode B). See
  *     `plugin-kv-api.md` for the contract.
@@ -1578,7 +1585,7 @@ interface IExtractorCallbacks {
      * extension-local Record key declared under
      * `extension.viewContributions[<contributionId>]`; the second is a
      * payload that conforms to the slot's payload schema in
-     * `spec/schemas/view-slots.schema.json#/$defs/payloads/<slot>` —
+     * `spec/schemas/view-slots.schema.json#/$defs/payloads/<slot>`,
      * where `<slot>` is the slot the manifest declared for this
      * contribution. The orchestrator validates the payload against the
      * slot's schema before persisting to `scan_contributions`; off-shape
@@ -1601,7 +1608,7 @@ interface IExtractorContext extends IExtractorCallbacks {
      * (`write(table, row)`). See `spec/plugin-kv-api.md`.
      *
      * Typed as `unknown` so this contract module stays free of any
-     * adapter-side imports — the concrete `IPluginStore` lives in
+     * adapter-side imports, the concrete `IPluginStore` lives in
      * `kernel/adapters/plugin-store.js`. Plugin authors narrow at the
      * call site based on the storage mode declared in their manifest.
      * The orchestrator looks up the wrapper per-extractor in
@@ -1618,11 +1625,11 @@ interface IExtractor extends IExtensionBase {
     /**
      * Optional opt-in filter on `node.kind`. When declared, the orchestrator
      * skips invocation of `extract()` for any node whose `kind` is NOT in
-     * this list — fail-fast, before context construction, so the extractor
+     * this list, fail-fast, before context construction, so the extractor
      * wastes zero CPU on inapplicable nodes.
      *
      * Absent (`undefined`) is the default: the extractor applies to every
-     * kind. There are no wildcards — the absence of the field already
+     * kind. There are no wildcards, the absence of the field already
      * encodes "every kind". An empty array (`[]`) is rejected at load
      * time by AJV (`minItems: 1` in the schema).
      *
@@ -1647,13 +1654,13 @@ interface IExtractor extends IExtensionBase {
  * findings into the UI via view contributions. Deterministic analyzers
  * are pure (same graph in → same issues out) and run synchronously
  * inside `sm scan` / `sm check`. Probabilistic analyzers invoke an LLM
- * through the kernel's `RunnerPort` and dispatch only as queued jobs —
+ * through the kernel's `RunnerPort` and dispatch only as queued jobs,
  * they never participate in scan-time pipelines. Mode is declared in
  * the manifest (default `deterministic`).
  */
 
 /**
- * Step 9.6.2 — orphan sidecar entry surfaced to analyzers. A `.sm` file
+ * Step 9.6.2, orphan sidecar entry surfaced to analyzers. A `.sm` file
  * whose sibling `.md` does not exist on disk; the `annotation-orphan`
  * built-in analyzer emits one warning per entry. Other analyzers that
  * care about orphan sidecars MAY consume the list too.
@@ -1668,13 +1675,13 @@ interface IAnalyzerContext {
     nodes: Node[];
     links: Link[];
     /**
-     * Step 9.6.2 — orphaned sidecars discovered during the scan walk.
+     * Step 9.6.2, orphaned sidecars discovered during the scan walk.
      * Empty when sidecar discovery did not run (legacy callers) or
      * when no orphans exist.
      */
     orphanSidecars?: IAnalyzerOrphanSidecar[];
     /**
-     * Step 9.6.6 — raw parsed sidecar root keyed by `node.path`. Populated
+     * Step 9.6.6, raw parsed sidecar root keyed by `node.path`. Populated
      * by the orchestrator alongside the public `Node.sidecar` overlay so
      * analyzers that inspect plugin namespaces (e.g. the built-in
      * `core/unknown-field` Analyzer) can walk the full tree without
@@ -1684,7 +1691,7 @@ interface IAnalyzerContext {
      */
     sidecarRoots?: ReadonlyMap<string, Record<string, unknown>>;
     /**
-     * Step 9.6.6 — runtime catalog of plugin-contributed annotation keys,
+     * Step 9.6.6, runtime catalog of plugin-contributed annotation keys,
      * as exposed by `kernel.getRegisteredAnnotationKeys()`. Threaded
      * through so analyzers can reason about the registered-vs-unknown
      * split without reaching back into the kernel. Empty array when no
@@ -1693,20 +1700,20 @@ interface IAnalyzerContext {
      */
     annotationContributions?: readonly IRegisteredAnnotationKey[];
     /**
-     * Step 11.x — runtime catalog of plugin-contributed view contributions,
+     * Step 11.x, runtime catalog of plugin-contributed view contributions,
      * as exposed by `kernel.getRegisteredViewContributions()`. Threaded
      * through so analyzers can reason about emissions without reaching
-     * back into the kernel: built-in `core/unknown-slot` walks this list
-     * to detect deprecated slots in use, and `core/contribution-orphan`
-     * joins it with the live node set to flag dangling emissions. Empty
-     * array when no extension declares view contributions; absent for
-     * legacy callers (older runScan sites that never wired the catalog
-     * through).
+     * back into the kernel (built-in `core/contribution-orphan` joins it
+     * with the live node set to flag dangling emissions). Slot catalog
+     * drift detection is NOT a scan concern, it lives at load time and
+     * surfaces via `sm plugins doctor`. Empty array when no extension
+     * declares view contributions; absent for legacy callers (older
+     * runScan sites that never wired the catalog through).
      */
     viewContributions?: readonly IRegisteredViewContribution[];
     /**
      * Absolute paths of `*.md` files under the project's
-     * `.skill-map/jobs/` that no `state_jobs.filePath` references — the
+     * `.skill-map/jobs/` that no `state_jobs.filePath` references, the
      * built-in `core/job-orphan-file` analyzer projects each as a `warn`
      * issue. Pre-computed by the driving adapter (CLI / BFF) inside its
      * already-open storage transaction (mirrors the `orphanSidecars`
@@ -1721,7 +1728,7 @@ interface IAnalyzerContext {
      * link-validation purposes via `scan.referencePaths`. The driving
      * adapter walks each configured path before the scan and collects
      * every existing file's absolute path here. Files in this set are
-     * NOT indexed as graph nodes — the only consumer is
+     * NOT indexed as graph nodes, the only consumer is
      * `core/broken-ref`, which suppresses its `warn` issue when a
      * path-style link target falls into the set. Absent / empty when
      * the operator left `scan.referencePaths` empty or when the
@@ -1766,6 +1773,20 @@ interface IAnalyzer extends IExtensionBase {
      * `deterministic` per `spec/schemas/extensions/analyzer.schema.json`.
      */
     mode?: TExecutionMode;
+    /**
+     * Qualified `<pluginId>/<id>` Action ids the analyzer recommends to
+     * resolve its findings. Distinct from `Action.precondition` (which
+     * declares which nodes an Action applies to from the Action side);
+     * this field declares which Actions are relevant when this
+     * Analyzer fires from the Analyzer side. Actions are per-node by
+     * design (project-level cleanup verbs like orphan file prune or
+     * contribution relink are CLI verbs, not Actions) and are NOT
+     * surfaced through this field. The UI consumes it in the node
+     * inspector under "Recommended for issues". Optional; omit when no
+     * Action resolves the finding (e.g. `core/superseded` surfaces
+     * deliberate user declarations, not problems).
+     */
+    recommendedActions?: readonly string[];
     evaluate(ctx: IAnalyzerContext): Issue[] | Promise<Issue[]>;
 }
 
@@ -1775,9 +1796,9 @@ interface IAnalyzer extends IExtensionBase {
  *
  * Actions operate on one or more nodes in one of two execution modes:
  *
- *   - `deterministic` — code runs in-process; the action computes the
+ *   - `deterministic`, code runs in-process; the action computes the
  *     report synchronously and returns it. No job file, no runner.
- *   - `probabilistic` — the kernel renders a prompt + preamble into a
+ *   - `probabilistic`, the kernel renders a prompt + preamble into a
  *     job file; a runner executes it via `RunnerPort` against an LLM;
  *     `sm record` closes the job and validates the report against
  *     `reportSchemaRef`.
@@ -1787,7 +1808,7 @@ interface IAnalyzer extends IExtensionBase {
  * probabilistic) lands with the job subsystem (Decision #114 in
  * `ROADMAP.md`). Today the loader still validates `kind: 'action'`
  * manifests against `extension-action.schema.json` and the registry
- * holds them — `sm actions show` and the precondition gating UI consume
+ * holds them, `sm actions show` and the precondition gating UI consume
  * the manifest data. The runtime entry point is intentionally absent
  * from `IAction` so plugin authors don't ship a method the kernel will
  * not call until the job subsystem is in place; when it ships, the
@@ -1795,21 +1816,21 @@ interface IAnalyzer extends IExtensionBase {
  *
  * Mirrors `extensions/action.schema.json`:
  *
- *   - `mode` (required) — discriminator between the two modes.
- *   - `reportSchemaRef` (required) — JSON Schema reference the report
+ *   - `mode` (required), discriminator between the two modes.
+ *   - `reportSchemaRef` (required), JSON Schema reference the report
  *     MUST validate against. MUST extend `report-base.schema.json`.
- *   - `promptTemplateRef` — REQUIRED when `mode: 'probabilistic'`,
+ *   - `promptTemplateRef`, REQUIRED when `mode: 'probabilistic'`,
  *     FORBIDDEN when `mode: 'deterministic'`. The schema's conditional
  *     `allOf` enforces both directions; the runtime contract simply
  *     surfaces the field as optional and lets the loader catch shape
  *     violations at AJV time.
- *   - `expectedDurationSeconds` — REQUIRED for probabilistic (drives
+ *   - `expectedDurationSeconds`, REQUIRED for probabilistic (drives
  *     TTL); advisory for deterministic.
- *   - `precondition` — declarative filter consumed by `--all` fan-out,
+ *   - `precondition`, declarative filter consumed by `--all` fan-out,
  *     UI button gating, `sm actions show`.
- *   - `expectedTools` — hint to Skill / CLI runners about expected
+ *   - `expectedTools`, hint to Skill / CLI runners about expected
  *     tools (no normative enforcement in v0).
- *   - `fanOutPolicy` — `'per-node'` (default) vs `'batch'`.
+ *   - `fanOutPolicy`, `'per-node'` (default) vs `'batch'`.
  */
 
 /**
@@ -1817,10 +1838,10 @@ interface IAnalyzer extends IExtensionBase {
  * future write kinds (storage rows, plugin KV, etc.) can land additively
  * without breaking consumers that only handle `kind: 'sidecar'`.
  *
- *   - `path` — absolute path to the `.sm` file the kernel must materialise
+ *   - `path`, absolute path to the `.sm` file the kernel must materialise
  *     the change into. Resolved by the Action from the node's absolute
  *     path via `sidecarPathFor()`.
- *   - `changes` — partial sidecar root used as a deep-merge patch (NOT a
+ *   - `changes`, partial sidecar root used as a deep-merge patch (NOT a
  *     full replacement). Arrays REPLACE; objects RECURSE. Reason:
  *     sidecars are shared-write between skill-map core and plugins;
  *     a full replace would clobber `<plugin-id>:` namespaced blocks.
@@ -1833,7 +1854,7 @@ type TActionWrite = {
 /**
  * Result envelope returned by deterministic Actions. The `report` field
  * carries the typed report payload (each Action declares its shape via
- * `reportSchemaRef`); `writes` is opt-in — Actions that do not mutate
+ * `reportSchemaRef`); `writes` is opt-in, Actions that do not mutate
  * persistent state simply omit it.
  */
 interface IActionResult<TReport = unknown> {
@@ -1842,20 +1863,20 @@ interface IActionResult<TReport = unknown> {
 }
 /**
  * Runtime context passed to a deterministic Action's `invoke()` method.
- * Minimal surface — Actions stay pure (no IO inside `invoke`); the kernel
+ * Minimal surface, Actions stay pure (no IO inside `invoke`); the kernel
  * materialises any returned `writes` after the call.
  *
- *   - `node` — the target `Node` the Action operates on. Open-by-design;
+ *   - `node`, the target `Node` the Action operates on. Open-by-design;
  *     batch / fan-out flows pick the matching nodes upstream.
- *   - `nodeAbsolutePath` — absolute path to the node's `.md` file on
+ *   - `nodeAbsolutePath`, absolute path to the node's `.md` file on
  *     disk. The Action uses this to compute the sidecar path it returns
  *     in a `TActionWrite`. Surfaced separately from `node.path` (which is
  *     the relative scope-root form) so Actions never compose absolute
  *     paths from `node.path` themselves.
- *   - `invoker` — identity of the caller; written into the sidecar's
+ *   - `invoker`, identity of the caller; written into the sidecar's
  *     `audit.lastBumpedBy` when the Action chooses to. CLI invocations
  *     pass `'cli'`; plugin-driven invocations pass `'plugin:<plugin-id>'`.
- *   - `now` — clock function; tests inject a deterministic source.
+ *   - `now`, clock function; tests inject a deterministic source.
  *     Defaults to `() => new Date()` at the composition root.
  */
 interface IActionContext {
@@ -1866,7 +1887,7 @@ interface IActionContext {
 }
 /**
  * Declarative filter applied by `--all` fan-out, UI button gating, and
- * `sm actions show`. All fields optional — an empty precondition matches
+ * `sm actions show`. All fields optional, an empty precondition matches
  * every node.
  */
 interface IActionPrecondition {
@@ -1936,14 +1957,14 @@ interface IAction extends IExtensionBase {
     /**
      * Deterministic invocation entry point. OPTIONAL on the runtime
      * contract for backward compatibility with the manifest-only era
-     * (Decision #114) — actions that ship for the future probabilistic
+     * (Decision #114), actions that ship for the future probabilistic
      * runner / record path leave it absent and the kernel never calls it.
      * Step 9.6.3 (Decision #125) introduces the first concrete consumer:
      * the built-in `bump` Action implements `invoke()` and returns a
      * `writes: [{ kind: 'sidecar', ... }]` payload that the kernel
      * materialises through `ISidecarStore`.
      *
-     * Implementations MUST stay pure — no IO inside `invoke()`. The Action
+     * Implementations MUST stay pure, no IO inside `invoke()`. The Action
      * computes the patch and returns it; the kernel reads the on-disk
      * sidecar, deep-merges, validates, and writes back inside its critical
      * section.
@@ -1961,10 +1982,10 @@ interface IAction extends IExtensionBase {
  *
  * Two adjacent names live on the same instance:
  *
- *   - `formatId: string` — the manifest field consumed by the
+ *   - `formatId: string`, the manifest field consumed by the
  *     `--format <name>` CLI flag. The kernel's lookup is
  *     `formatters.find((f) => f.formatId === flag)`.
- *   - `format(ctx) → string` — the runtime method. Receives the full
+ *   - `format(ctx) → string`, the runtime method. Receives the full
  *     graph and returns the serialized output. Output MUST be
  *     byte-deterministic for the same input (the snapshot-test suite
  *     relies on this).
@@ -1978,6 +1999,16 @@ interface IFormatterContext {
     nodes: Node[];
     links: Link[];
     issues: Issue[];
+    /**
+     * Full persisted scan, when the caller has it on hand. Optional so
+     * existing formatters that only consume (nodes, links, issues) keep
+     * working unchanged; formatters whose output mirrors a `ScanResult`
+     * envelope (today: the built-in `json` formatter under
+     * `built-in-plugins/formatters/json/`) read this to project the
+     * canonical document verbatim. `undefined` when the caller has only
+     * the three primary arrays (back-compat with older drivers).
+     */
+    scanResult?: ScanResult;
 }
 interface IFormatter extends IExtensionBase {
     kind: 'formatter';
@@ -1996,7 +2027,7 @@ interface IFormatter extends IExtensionBase {
  * are notification (Slack on `job.completed`), integration glue (CI
  * webhook on `job.failed`), and bookkeeping (per-extractor metrics).
  *
- * The hookable trigger set is INTENTIONALLY SMALL — ten events. Eight
+ * The hookable trigger set is INTENTIONALLY SMALL, ten events. Eight
  * 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
@@ -2020,16 +2051,16 @@ interface IFormatter extends IExtensionBase {
  *
  * Curated trigger set (per spec § A.11):
  *
- *   0. `boot`                 — once per CLI process, before verb routing.
- *   1. `scan.started`         — pre-scan setup (one per scan).
- *   2. `scan.completed`       — post-scan reaction (one per scan).
- *   3. `extractor.completed`  — aggregated per-Extractor outputs.
- *   4. `analyzer.completed`       — aggregated per-Rule outputs.
- *   5. `action.completed`     — Action executed on a node.
- *   6. `job.spawning`         — pre-spawn of runner subprocess.
- *   7. `job.completed`        — most common trigger.
- *   8. `job.failed`           — alerts, retry triggers.
- *   9. `shutdown`             — once per CLI process, after the verb's
+ *   0. `boot`                , once per CLI process, before verb routing.
+ *   1. `scan.started`        , pre-scan setup (one per scan).
+ *   2. `scan.completed`      , post-scan reaction (one per scan).
+ *   3. `extractor.completed` , aggregated per-Extractor outputs.
+ *   4. `analyzer.completed`      , aggregated per-Rule outputs.
+ *   5. `action.completed`    , Action executed on a node.
+ *   6. `job.spawning`        , pre-spawn of runner subprocess.
+ *   7. `job.completed`       , most common trigger.
+ *   8. `job.failed`          , alerts, retry triggers.
+ *   9. `shutdown`            , once per CLI process, after the verb's
  *                                exit code resolves and before
  *                                `process.exit`.
  */
@@ -2117,7 +2148,7 @@ interface IHookContext {
  * at load time: when none of the declared triggers carries a given
  * filter field, the loader surfaces `invalid-manifest`. The current
  * impl performs the basic enum check but defers full payload-shape
- * cross-validation to a follow-up — the dispatcher is permissive at
+ * cross-validation to a follow-up, the dispatcher is permissive at
  * runtime (an unknown field never matches → the hook simply never
  * fires for that event, which is a correct interpretation of "filter
  * by a field that doesn't exist").
@@ -2148,29 +2179,205 @@ interface IHook extends IExtensionBase {
      * Hook entry point. Returns nothing; reactions are side effects.
      * Errors are caught by the dispatcher (logged as `extension.error`,
      * surfaced via `hook.failed` meta-event) and NEVER block the main
-     * pipeline — a buggy hook degrades gracefully.
+     * pipeline, a buggy hook degrades gracefully.
      */
     on(ctx: IHookContext): void | Promise<void>;
 }
 
 /**
- * Scan orchestrator — runs the Provider → extractor → analyzer pipeline across
+ * `ProgressEmitterPort`, emits progress events during long operations.
+ *
+ * Shape-only today. The full event catalog (`run.started`,
+ * `job.claimed`, `model.delta`, etc.) is normative in
+ * `spec/job-events.md`; this port carries an open `data` payload so
+ * adapters can emit any documented event without type churn.
+ */
+interface ProgressEvent {
+    type: string;
+    timestamp: string;
+    runId?: string;
+    jobId?: string;
+    data?: unknown;
+}
+type TProgressListener = (event: ProgressEvent) => void;
+interface ProgressEmitterPort {
+    emit(event: ProgressEvent): void;
+    subscribe(listener: TProgressListener): () => void;
+}
+
+/**
+ * Per-node extractor invocation: build a fresh `IExtractorContext` for
+ * each extractor, validate every emitted link / contribution against
+ * the declared catalog, fold enrichment partials into per-`(node,
+ * extractor)` records, and surface emit-time drops as
+ * `extension.error` events.
+ *
+ * Also hosts the post-walk recompute helpers that re-derive
+ * `linksOutCount` / `linksInCount` / `externalRefsCount` on every node
+ * from the final merged link buffer, plus the `IExtractorRunRecord`
+ * and `IEnrichmentRecord` types those records eventually persist as.
+ */
+
+/**
+ * Spec § A.9, runs to persist into `scan_extractor_runs`. One entry
+ * per `(nodePath, qualifiedExtractorId)` pair the orchestrator decided
+ * "this extractor is current for this body". Includes both freshly-run
+ * pairs (extractor invoked this scan) and reused pairs (cached node, the
+ * extractor's prior run still applies to the same body hash). Excludes
+ * obsolete pairs, extractors that ran in the prior but are no longer
+ * registered, so a replace-all persist drops them automatically.
+ */
+interface IExtractorRunRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtRun: string;
+    ranAt: number;
+    /**
+     * sha256 of the canonical-form sidecar annotations the Extractor saw
+     * at run time. Always populated (an absent sidecar canonicalises to
+     * `{}` so the hash is stable). Used unconditionally by the cache
+     * decision alongside `bodyHashAtRun`: a sidecar-only edit invalidates
+     * the cached run for every applicable Extractor on that node.
+     */
+    sidecarAnnotationsHashAtRun: string;
+}
+/**
+ * Spec § A.8, universal enrichment layer.
+ *
+ * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
+ * produced via `ctx.enrichNode(...)` during the walk. Attribution is
+ * preserved per-Extractor (rather than merged client-side as B.1 did)
+ * so the persistence layer can:
+ *
+ *   - upsert a single row per pair (stable PRIMARY KEY conflict on
+ *     re-extract);
+ *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
+ *     for last-write-wins per field at read time.
+ *
+ * `value` is the cumulative merge across every `enrichNode` call that
+ * Extractor made for this node within this scan, multiple
+ * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
+ * fold into a single row, but two different Extractors hitting the
+ * same node yield two distinct rows.
+ *
+ * `isProbabilistic` is reserved: Extractors are deterministic-only, so
+ * every record produced by the orchestrator sets it to `false`. The
+ * field is kept on the record (and the row in `node_enrichments`) so a
+ * future Action-issued enrichment can populate it without reshaping
+ * the persistence contract, see spec `architecture.md`
+ * §Extractor · enrichment layer.
+ */
+interface IEnrichmentRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtEnrichment: string;
+    value: Partial<Node>;
+    enrichedAt: number;
+    isProbabilistic: boolean;
+}
+/**
+ * Run a set of extractors against a single node, collecting their link
+ * emissions and node-enrichment partials. Each extractor is invoked
+ * exactly once with a fresh `IExtractorContext`. Caller decides what
+ * to do with the returned arrays (push into per-scan buffers, write to
+ * a focused refresh result, etc.).
+ *
+ * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
+ * needs for re-running a single extractor against a single node, the
+ * pre-extraction code in `refresh.ts` was hand-duplicating this loop
+ * (audit item V4).
+ *
+ * Within this call, multiple `enrichNode(partial)` calls from the same
+ * extractor against the same node fold into one record (last-write-wins
+ * per field), same contract as the in-scan path.
+ */
+declare function runExtractorsForNode(opts: {
+    extractors: IExtractor[];
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    bodyHash: string;
+    emitter: ProgressEmitterPort;
+    /**
+     * Spec § A.12, per-plugin `ctx.store` wrappers keyed by `pluginId`.
+     * The map's lookup is per-extractor inside the loop, so callers that
+     * don't track plugin storage can omit it; the resulting `ctx.store`
+     * stays `undefined` (the existing contract).
+     */
+    pluginStores?: ReadonlyMap<string, IPluginStore>;
+}): Promise<{
+    internalLinks: Link[];
+    externalLinks: Link[];
+    enrichments: IEnrichmentRecord[];
+    contributions: IContributionRecord[];
+}>;
+
+/**
+ * Rename + orphan classification per `spec/db-schema.md` §Rename
+ * detection. Pure: takes the prior `ScanResult` and the current node
+ * set, mutates the supplied `issues` array in place, and returns the
+ * `RenameOp[]` the persistence layer must apply inside the same tx as
+ * the scan zone replace-all.
+ */
+
+/**
+ * Confidence-tagged plan to repoint `state_*` references from one node
+ * path to another. Emitted by the rename heuristic during `runScan` and
+ * consumed by `persistScanResult` so the FK migration runs inside the
+ * same transaction as the scan zone replace-all.
+ */
+interface RenameOp {
+    from: string;
+    to: string;
+    confidence: 'high' | 'medium';
+}
+/**
+ * Pure rename / orphan classification per `spec/db-schema.md` §Rename
+ * detection. Mutates `issues` in place, caller passes the in-progress
+ * issue list; returns the `RenameOp[]` for the persistence layer to
+ * apply inside its tx.
+ *
+ * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
+ * by another):
+ *
+ *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
+ *      that has the same `bodyHash`. No issue, no prompt.
+ *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
+ *      each with the *unique* unclaimed `newPath` that shares its
+ *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
+ *      with `data: { from, to, confidence: 'medium' }`.
+ *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
+ *      remaining frontmatter-matching candidate, emit ONE
+ *      `auto-rename-ambiguous` issue per `newPath`, listing all
+ *      candidates in `data.candidates`. NO migration.
+ *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
+ *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
+ *
+ * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
+ * order so the same input always produces the same matches,
+ * required for reproducible tests and conformance fixtures (the spec
+ * does not prescribe an order, but stability is the obvious contract).
+ */
+declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+
+/**
+ * Scan orchestrator, runs the Provider → extractor → analyzer pipeline across
  * every registered extension and emits `ProgressEmitterPort` events in
  * canonical order. The callable extension set is injected via
- * `RunScanOptions.extensions` — the Registry holds manifest metadata, the
+ * `RunScanOptions.extensions`, the Registry holds manifest metadata, the
  * callable set holds the runtime instances the orchestrator actually
  * invokes. Separating the two lets `sm plugins` and `sm help` introspect
  * the graph without loading code.
  *
  * With zero registered extensions (or a callable set that carries none)
- * the pipeline still produces a valid zero-filled `ScanResult` — the
+ * the pipeline still produces a valid zero-filled `ScanResult`, the
  * kernel-empty-boot invariant.
  *
  * Roots are validated up front: each entry of `RunScanOptions.roots`
  * must exist on disk as a directory. The first failure throws a clear
  * `Error` naming the offending path. This guards every caller (CLI,
  * server, skill-agent) against silently producing a zero-filled
- * `ScanResult` when a Provider walks a non-existent path — the bug
+ * `ScanResult` when a Provider walks a non-existent path, the bug
  * that wiped a populated DB via `sm scan -- --dry-run` (clipanion's
  * `--` made `--dry-run` a positional root that did not exist).
  *
@@ -2180,7 +2387,7 @@ interface IHook extends IExtensionBase {
  * `bodyHash` and `frontmatterHash` match. New / modified files run
  * through the full extractor pipeline (including the external-url-counter
  * which produces ephemeral pseudo-links). Rules ALWAYS run over the
- * fully merged graph — issue state can change even for an unchanged node
+ * fully merged graph, issue state can change even for an unchanged node
  * (e.g. a previously broken `references` link now resolves because a new
  * node was added). For unchanged nodes the prior `externalRefsCount` is
  * preserved as-is (the external pseudo-links were never persisted, so
@@ -2194,7 +2401,7 @@ interface IHook extends IExtensionBase {
  *     entry per `(node, extractor)` so attribution survives into the DB.
  *     Persisted into `node_enrichments` (A.8). The author-supplied
  *     frontmatter on `node.frontmatter` stays immutable from any Extractor
- *     — the enrichment layer is the only writable surface, and rules /
+ *    , the enrichment layer is the only writable surface, and rules /
  *     formatters consume it via `mergeNodeWithEnrichments`.
  *   - `ctx.store` → plugin's own KV / dedicated tables (spec § A.12).
  *     Wired by the driving adapter via `RunScanOptions.pluginStores`,
@@ -2219,17 +2426,6 @@ interface IScanExtensions {
      */
     hooks?: IHook[];
 }
-/**
- * Confidence-tagged plan to repoint `state_*` references from one node
- * path to another. Emitted by the rename heuristic during `runScan` and
- * consumed by `persistScanResult` so the FK migration runs inside the
- * same transaction as the scan zone replace-all.
- */
-interface RenameOp {
-    from: string;
-    to: string;
-    confidence: 'high' | 'medium';
-}
 interface RunScanOptions {
     /**
      * Filesystem roots to walk. Spec requires `minItems: 1`; passing an
@@ -2240,13 +2436,13 @@ interface RunScanOptions {
     /** Runtime extension instances. Absent → empty pipeline. */
     extensions?: IScanExtensions;
     /**
-     * Step 9.6.6 — runtime catalog of plugin-contributed annotation keys
+     * Step 9.6.6, runtime catalog of plugin-contributed annotation keys
      * (the same shape `kernel.getRegisteredAnnotationKeys()` returns).
      * Threaded into the rule pass so `core/unknown-field` can
      * legitimise registered plugin namespaces / root keys without
      * re-walking the manifests. Absent → empty catalog (every plugin
      * key is treated as unknown). Built-in catalog from
-     * `annotations.schema.json` is NOT included — that is hard-coded
+     * `annotations.schema.json` is NOT included, that is hard-coded
      * inside the rule.
      */
     annotationContributions?: readonly IRegisteredAnnotationKey[];
@@ -2254,8 +2450,12 @@ interface RunScanOptions {
      * Runtime catalog of plugin-contributed view contributions (the same
      * shape `kernel.getRegisteredViewContributions()` returns). Threaded
      * into the rule pass so:
-     *   - `core/unknown-slot` and `core/contribution-orphan` can
-     *     introspect the catalog (read-only).
+     *   - `core/contribution-orphan` can introspect the catalog
+     *     (read-only) and join it with the live node set to flag
+     *     dangling emissions. Slot catalog drift is NOT a scan concern,
+     *     it lives at load time and surfaces via `sm plugins doctor`
+     *     (the kernel rejects unknown slots as `invalid-manifest` first,
+     *     doctor catches the catalog-version-skew tail).
      *   - The orchestrator's per-rule emit closure can look up each
      *     declared `(contributionId → slot)` pairing for AJV
      *     payload validation.
@@ -2326,7 +2526,7 @@ interface RunScanOptions {
      */
     strict?: boolean;
     /**
-     * Spec § A.9 — fine-grained Extractor cache breadcrumbs from the
+     * Spec § A.9, fine-grained Extractor cache breadcrumbs from the
      * prior scan. Shape: `Map<nodePath, Map<qualifiedExtractorId, IPriorExtractorRun>>`.
      * Loaded from the `scan_extractor_runs` table by the CLI before
      * invoking `runScan`; absent / empty for a fresh DB or an out-of-band
@@ -2346,11 +2546,11 @@ interface RunScanOptions {
      */
     priorExtractorRuns?: Map<string, Map<string, IPriorExtractorRun>>;
     /**
-     * Spec § A.12 — per-plugin storage wrappers exposed to extractors via
+     * Spec § A.12, per-plugin storage wrappers exposed to extractors via
      * `ctx.store`. Keyed by `pluginId`; absent / missing entry leaves
      * `ctx.store` undefined for that extractor (the existing contract).
      *
-     * The kernel does not construct these — the driving adapter (CLI,
+     * The kernel does not construct these, the driving adapter (CLI,
      * future server) builds them with `makePluginStore` from
      * `kernel/adapters/plugin-store.js` and threads them through. This
      * keeps the orchestrator persistence-agnostic (the wrapper supplies
@@ -2367,7 +2567,7 @@ interface RunScanOptions {
      * its own FS walk. The driving adapter (CLI, BFF) computes this
      * inside its already-open storage transaction via
      * `findOrphanJobFiles(jobsDir, await port.jobs.listReferencedFilePaths())`
-     * — mirrors the `orphanSidecars` model where detection lives
+     * mirrors the `orphanSidecars` model where detection lives
      * outside the rule and the rule only projects. Absent / empty when
      * the caller has no jobs context (out-of-band tests, fresh DB,
      * `--no-built-ins`).
@@ -2379,7 +2579,7 @@ interface RunScanOptions {
      * through to `IAnalyzerContext.referenceablePaths` so the built-in
      * `core/broken-ref` rule can suppress its `warn` for path-style
      * links whose target lands in the set. Files are NOT walked by
-     * the kernel — the driving adapter populates the set before
+     * the kernel, the driving adapter populates the set before
      * calling `runScan`. Absent / empty when the operator left
      * `scan.referencePaths` unconfigured.
      */
@@ -2393,72 +2593,15 @@ interface RunScanOptions {
      */
     cwd?: string;
 }
-/**
- * Spec § A.9 — runs to persist into `scan_extractor_runs`. One entry
- * per `(nodePath, qualifiedExtractorId)` pair the orchestrator decided
- * "this extractor is current for this body". Includes both freshly-run
- * pairs (extractor invoked this scan) and reused pairs (cached node, the
- * extractor's prior run still applies to the same body hash). Excludes
- * obsolete pairs — extractors that ran in the prior but are no longer
- * registered — so a replace-all persist drops them automatically.
- */
-interface IExtractorRunRecord {
-    nodePath: string;
-    extractorId: string;
-    bodyHashAtRun: string;
-    ranAt: number;
-    /**
-     * sha256 of the canonical-form sidecar annotations the Extractor saw
-     * at run time. Always populated (an absent sidecar canonicalises to
-     * `{}` so the hash is stable). Used unconditionally by the cache
-     * decision alongside `bodyHashAtRun`: a sidecar-only edit invalidates
-     * the cached run for every applicable Extractor on that node.
-     */
-    sidecarAnnotationsHashAtRun: string;
-}
-/**
- * Spec § A.8 — universal enrichment layer.
- *
- * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
- * produced via `ctx.enrichNode(...)` during the walk. Attribution is
- * preserved per-Extractor (rather than merged client-side as B.1 did)
- * so the persistence layer can:
- *
- *   - upsert a single row per pair (stable PRIMARY KEY conflict on
- *     re-extract);
- *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
- *     for last-write-wins per field at read time.
- *
- * `value` is the cumulative merge across every `enrichNode` call that
- * Extractor made for this node within this scan — multiple
- * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
- * fold into a single row, but two different Extractors hitting the
- * same node yield two distinct rows.
- *
- * `isProbabilistic` is reserved: Extractors are deterministic-only, so
- * every record produced by the orchestrator sets it to `false`. The
- * field is kept on the record (and the row in `node_enrichments`) so a
- * future Action-issued enrichment can populate it without reshaping
- * the persistence contract — see spec `architecture.md`
- * §Extractor · enrichment layer.
- */
-interface IEnrichmentRecord {
-    nodePath: string;
-    extractorId: string;
-    bodyHashAtEnrichment: string;
-    value: Partial<Node>;
-    enrichedAt: number;
-    isProbabilistic: boolean;
-}
 /**
  * Same as `runScan` but also returns the rename heuristic's `RenameOp[]`
- * — the high- and medium-confidence renames the persistence layer must
+ * the high- and medium-confidence renames the persistence layer must
  * apply to `state_*` rows inside the same tx as the scan zone replace-
  * all (per `spec/db-schema.md` §Rename detection). Most callers want
  * `runScan` (which returns just `ScanResult`); the CLI's `sm scan`
  * uses this variant so it can hand the ops off to `persistScanResult`.
  *
- * Also returns `extractorRuns` — the Spec § A.9 fine-grained cache
+ * Also returns `extractorRuns`, the Spec § A.9 fine-grained cache
  * breadcrumbs the CLI persists into `scan_extractor_runs` so the next
  * incremental scan can decide per-(node, extractor) whether re-running
  * is required.
@@ -2472,75 +2615,21 @@ declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): P
     freshlyRunTuples: ReadonlySet<string>;
 }>;
 declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
+
 /**
- * Run a set of extractors against a single node, collecting their link
- * emissions and node-enrichment partials. Each extractor is invoked
- * exactly once with a fresh `IExtractorContext`. Caller decides what
- * to do with the returned arrays (push into per-scan buffers, write to
- * a focused refresh result, etc.).
- *
- * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
- * needs for re-running a single extractor against a single node — the
- * pre-extraction code in `refresh.ts` was hand-duplicating this loop
- * (audit item V4).
- *
- * Within this call, multiple `enrichNode(partial)` calls from the same
- * extractor against the same node fold into one record (last-write-wins
- * per field) — same contract as the in-scan path.
- */
-declare function runExtractorsForNode(opts: {
-    extractors: IExtractor[];
-    node: Node;
-    body: string;
-    frontmatter: Record<string, unknown>;
-    bodyHash: string;
-    emitter: ProgressEmitterPort;
-    /**
-     * Spec § A.12 — per-plugin `ctx.store` wrappers keyed by `pluginId`.
-     * The map's lookup is per-extractor inside the loop, so callers that
-     * don't track plugin storage can omit it; the resulting `ctx.store`
-     * stays `undefined` (the existing contract).
-     */
-    pluginStores?: ReadonlyMap<string, IPluginStore>;
-}): Promise<{
-    internalLinks: Link[];
-    externalLinks: Link[];
-    enrichments: IEnrichmentRecord[];
-    contributions: IContributionRecord[];
-}>;
-/**
- * Pure rename / orphan classification per `spec/db-schema.md` §Rename
- * detection. Mutates `issues` in place — caller passes the in-progress
- * issue list; returns the `RenameOp[]` for the persistence layer to
- * apply inside its tx.
- *
- * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
- * by another):
- *
- *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
- *      that has the same `bodyHash`. No issue, no prompt.
- *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
- *      each with the *unique* unclaimed `newPath` that shares its
- *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
- *      with `data: { from, to, confidence: 'medium' }`.
- *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
- *      remaining frontmatter-matching candidate, emit ONE
- *      `auto-rename-ambiguous` issue per `newPath`, listing all
- *      candidates in `data.candidates`. NO migration.
- *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
- *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
- *
- * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
- * order so the same input always produces the same matches —
- * required for reproducible tests and conformance fixtures (the spec
- * does not prescribe an order, but stability is the obvious contract).
+ * Node-construction helpers: hash a body, canonicalise frontmatter /
+ * sidecar annotations, resolve the sidecar overlay for a given relative
+ * path, and produce a fresh `Node` (validating its frontmatter on the
+ * way out). Also hosts `mergeNodeWithEnrichments` + `IPersistedEnrichment`
+ * the read-time merge of author frontmatter with the A.8 enrichment
+ * layer.
  */
-declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+
 /**
- * Spec § A.8 — produce the merged read-time view of a Node.
+ * Spec § A.8, produce the merged read-time view of a Node.
  *
  * Rules / `sm check` / `sm export` consume `node.frontmatter` directly
- * (deterministic CI-safe baseline — author intent, byte-stable). UI / future
+ * (deterministic CI-safe baseline, author intent, byte-stable). UI / future
  * rules that opt into enrichment context call this helper to merge the
  * author frontmatter with the live enrichment layer.
  *
@@ -2554,18 +2643,18 @@ declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], iss
  *      belongs to the UI layer next to the value.
  *   2. Sort the survivors by `enrichedAt` ASC so iteration order is
  *      "oldest first". This makes the spread merge below
- *      last-write-wins per field — the freshest Extractor's value
+ *      last-write-wins per field, the freshest Extractor's value
  *      pisar the older one for any conflicting key.
  *   3. Spread-merge each row's `value` over `node.frontmatter`. The
  *      author's keys are the base; enrichment keys overlay them.
  *
- * The returned object is a fresh shallow copy — mutating it does not
+ * The returned object is a fresh shallow copy, mutating it does not
  * touch the caller's node. The original `node.frontmatter` reference
  * remains accessible via `node.frontmatter` for callers that want the
  * pristine author baseline.
  *
  * @param node          Node to merge against; `node.frontmatter` is the base.
- * @param enrichments   Per-(node, extractor) enrichment records — typically
+ * @param enrichments   Per-(node, extractor) enrichment records, typically
  *                      loaded via `loadNodeEnrichments(db, node.path)` or
  *                      pre-filtered to this node by the caller.
  * @param opts.includeStale  When true, include rows flagged stale. Defaults
@@ -2595,7 +2684,7 @@ interface IPersistedEnrichment {
 }
 
 /**
- * In-memory `ProgressEmitterPort` adapter. No network, no DB — just a
+ * In-memory `ProgressEmitterPort` adapter. No network, no DB, just a
  * synchronous fan-out to registered listeners. Used by the default scan
  * orchestrator; the WebSocket-backed emitter that streams to
  * the Web UI lands.
@@ -2612,7 +2701,7 @@ declare class InMemoryProgressEmitter implements ProgressEmitterPort {
  *
  * Wraps `chokidar` behind a small `IFsWatcher` interface so:
  *
- *   1. The CLI command is impl-agnostic — swapping chokidar for a
+ *   1. The CLI command is impl-agnostic, swapping chokidar for a
  *      different watcher later (Java? Rust port? a future `WatchPort`?)
  *      doesn't ripple into the command.
  *   2. Debouncing, batching, and ignore-filter integration live in one
@@ -2661,28 +2750,37 @@ interface ICreateFsWatcherOptions {
     /** Debounce window in milliseconds. `0` triggers `onBatch` synchronously per event. */
     debounceMs: number;
     /**
-     * Optional ignore filter — same instance the scan walker uses.
+     * Optional ignore filter, same instance the scan walker uses.
      *
      * Two shapes are accepted:
      *
-     *   - **`IIgnoreFilter`** (the static one) — captured by reference at
+     *   - **`IIgnoreFilter`** (the static one), captured by reference at
      *     construction. Use this when the filter never changes for the
      *     lifetime of the watcher (the typical CLI `sm watch` flow).
      *
-     *   - **`() => IIgnoreFilter | undefined`** (a getter) — re-evaluated
+     *   - **`() => IIgnoreFilter | undefined`** (a getter), re-evaluated
      *     on EVERY chokidar `ignored` predicate call. Use this when the
-     *     filter can change at runtime — e.g. the BFF rebuilds it after
+     *     filter can change at runtime, e.g. the BFF rebuilds it after
      *     a `.skillmapignore` or `.skill-map/settings.json` edit and
      *     wants chokidar to immediately respect the new patterns without
      *     tearing down and rebuilding the watcher. A getter that returns
      *     `undefined` disables ignore filtering for that call.
      */
     ignoreFilter?: IIgnoreFilter | (() => IIgnoreFilter | undefined) | undefined;
+    /**
+     * Maximum directory traversal depth. `undefined` (default) walks the
+     * tree recursively without bound; `0` limits the watch to the
+     * literal `roots` entries (no descent), which is the right setting
+     * when watching a directory only to catch changes to specific
+     * top-level files (see `subscribeMeta` in `core/watcher/runtime.ts`).
+     * Forwarded verbatim to chokidar's `depth` option.
+     */
+    depth?: number;
     /** Called once per debounced batch. Awaited; concurrent batches are serialised. */
     onBatch: (batch: IWatchBatch) => void | Promise<void>;
     /**
      * Called when the underlying watcher surfaces an error. The watcher
-     * stays open — callers decide whether to log, keep going, or close.
+     * stays open, callers decide whether to log, keep going, or close.
      */
     onError?: (err: Error) => void;
 }
@@ -2691,7 +2789,7 @@ interface ICreateFsWatcherOptions {
  * returned `ready` promise resolves once chokidar's initial directory
  * walk completes, at which point only NEW events fire `onBatch`.
  *
- * The initial directory walk is deliberately silent — we set
+ * The initial directory walk is deliberately silent, we set
  * `ignoreInitial: true`. The CLI runs a one-shot scan before flipping
  * the watcher on, so re-emitting an `add` for every existing file
  * would be redundant churn.
@@ -2699,20 +2797,20 @@ interface ICreateFsWatcherOptions {
 declare function createChokidarWatcher(opts: ICreateFsWatcherOptions): IFsWatcher;
 
 /**
- * Scan delta — pure comparison of two `ScanResult` snapshots. Drives
+ * Scan delta, pure comparison of two `ScanResult` snapshots. Drives
  * `sm scan --compare-with <path>` and is the single place the kernel
  * knows how to identify "the same" entity across two scans.
  *
  * **Identity contract** (mirrors decisions made at earlier sub-steps):
  *
  *   - **Node**: `node.path`. The path is the only field stable across
- *     edits — every other Node field is content-derived (hashes, counts,
+ *     edits, every other Node field is content-derived (hashes, counts,
  *     denormalised frontmatter). Two nodes with the same path are the
  *     "same" node; differences are reported as a `changed` entry with
  *     a reason narrowing what diverged.
  *
  *   - **Link**: `(source, target, kind, normalizedTrigger ?? '')`. This
- *     mirrors the link-conflict rule and `sm show` aggregation —
+ *     mirrors the link-conflict rule and `sm show` aggregation,
  *     two links with identical endpoints, kind, and (optional) trigger
  *     are the same link, even if emitted by different extractors. The
  *     `sources[]` union and confidence are NOT part of identity; they
@@ -2720,13 +2818,13 @@ declare function createChokidarWatcher(opts: ICreateFsWatcherOptions): IFsWatche
  *     "different" for delta purposes.
  *
  *   - **Issue**: `(analyzerId, sorted nodeIds, message)`. Mirrors
- *     `spec/job-events.md` §issue.* — same key → same issue, even when
+ *     `spec/job-events.md` §issue.*, same key → same issue, even when
  *     `data` / `severity` / `linkIndices` shift. A meaningful change in
  *     `message` (or a different set of node ids) is a different issue.
  *     This is the same key future job events will use; keep it aligned
  *     so consumers can reuse logic.
  *
- * No "changed" bucket for links / issues — identity already captures
+ * No "changed" bucket for links / issues, identity already captures
  * everything that matters there. Nodes get a "changed" bucket because
  * the path stays stable while the body / frontmatter rewrite, and that
  * change is meaningful (formatters, summarisers, downstream consumers
@@ -2772,7 +2870,7 @@ declare function computeScanDelta(prior: ScanResult, current: ScanResult, compar
 declare function isEmptyDelta(delta: IScanDelta): boolean;
 
 /**
- * Export query — minimal filter language for `sm export <query>` (Step 8.3).
+ * Export query, minimal filter language for `sm export <query>` (Step 8.3).
  *
  * Spec contract: `spec/cli-contract.md` line 190 says "Query syntax is
  * implementation-defined pre-1.0". This module defines the v0.5.0 syntax.
@@ -2790,12 +2888,12 @@ declare function isEmptyDelta(delta: IScanDelta): boolean;
  *
  * **Filters**:
  *
- *   - `kind=skill` / `kind=skill,agent` — node kind whitelist.
- *   - `has=issues` — node must appear in some issue's `nodeIds`. (Future
+ *   - `kind=skill` / `kind=skill,agent`, node kind whitelist.
+ *   - `has=issues`, node must appear in some issue's `nodeIds`. (Future
  *     expansion: `has=findings` / `has=summary` once Step 10 / 11 land.
  *     Unknown values are a parse error today; we'll ratchet up the
  *     accepted set additively.)
- *   - `path=foo/*` / `path=.claude/agents/**` — POSIX glob over `node.path`.
+ *   - `path=foo/*` / `path=.claude/agents/**`, POSIX glob over `node.path`.
  *     Supports `*` (any chars except `/`) and `**` (any chars including `/`).
  *
  * **Subset semantics** (`applyExportQuery`):
@@ -2804,7 +2902,7 @@ declare function isEmptyDelta(delta: IScanDelta): boolean;
  *     OR within values).
  *   - Links survive only when BOTH endpoints (`source` + `target`) belong
  *     to the filtered node set. A subset that includes "edges out to
- *     unfiltered nodes" would be confusing — the user asked for a focused
+ *     unfiltered nodes" would be confusing, the user asked for a focused
  *     subgraph, not its boundary. External-URL pseudo-links are already
  *     stripped by the orchestrator and never reach this layer.
  *   - Issues survive when ANY of the issue's `nodeIds` is in the filtered
@@ -2819,7 +2917,7 @@ interface IExportQuery {
     /** Original query string echoed back so consumers can render the header. */
     raw: string;
     /**
-     * Whitelist of node kinds (`node.kind` is open string — built-in
+     * Whitelist of node kinds (`node.kind` is open string, built-in
      * Claude catalog `skill` / `agent` / `command` / `hook` / `note`,
      * plus whatever external Providers declare). The query parser does
      * not validate values against a closed enum; an unknown kind simply
@@ -2846,16 +2944,16 @@ declare function applyExportQuery(scan: {
 }, query: IExportQuery): IExportSubset;
 
 /**
- * `scan_node_tags` adapter — tags · dual-source persistence layer.
+ * `scan_node_tags` adapter, tags · dual-source persistence layer.
  *
  * One row per `(node_path, tag, source)` triple. Projected at persist
  * time from BOTH `frontmatter.tags` (with `source='author'`) and
  * `sidecar.annotations.tags` (with `source='user'`). The same tag
- * string MAY appear under both sources for the same node — the PK
+ * string MAY appear under both sources for the same node, the PK
  * accepts the pair; search returns the node once via DISTINCT, the
  * UI renders both chips with their attribution.
  *
- * Belongs to the `scan_*` family — replaced wholesale per scan.
+ * Belongs to the `scan_*` family, replaced wholesale per scan.
  * Cached nodes' tag rows are projected from the cached
  * `node.frontmatter.tags` / `node.sidecar.annotations.tags` (both
  * already in memory at persist time), so the rebuild is cheap
@@ -2880,17 +2978,17 @@ interface ITagRecord {
  * Pure helpers for the "update available" notification feature.
  *
  * Three responsibilities:
- *   - `fetchLatestVersion`  — query `https://registry.npmjs.org/<pkg>/latest`
+ *   - `fetchLatestVersion` , query `https://registry.npmjs.org/<pkg>/latest`
  *                             with `AbortController` + timeout. Throws on
  *                             non-200 / parse failure / abort.
- *   - `compareVersions`     — semver compare (-1 / 0 / 1). Pre-1.0 aware:
+ *   - `compareVersions`    , semver compare (-1 / 0 / 1). Pre-1.0 aware:
  *                             treats prereleases via the standard rules
  *                             (release > prerelease at the same triple).
- *   - `isOutdated`          — sugar over `compareVersions` for the common
+ *   - `isOutdated`         , sugar over `compareVersions` for the common
  *                             "is `latest` strictly greater than `current`"
  *                             check the banner runs against.
  *
- * Pure kernel module — NO `process.env` reads, NO Node globals beyond the
+ * Pure kernel module, NO `process.env` reads, NO Node globals beyond the
  * built-in `fetch` / `AbortController` (Node 22+). Every env / settings
  * lookup happens in `src/cli/util/update-check-banner.ts`, the CLI-side
  * adapter that owns side effects.
@@ -2898,21 +2996,21 @@ interface ITagRecord {
  * The shared cache type (`IUpdateCheckCache`) is used by the storage
  * helpers under `kernel/storage/update-check.ts` and by the BFF's
  * `GET /api/update-status` projection. A second type
- * (`IUpdateStatus`) shapes the BFF response — it merges `current`
+ * (`IUpdateStatus`) shapes the BFF response, it merges `current`
  * (from `VERSION`) into the cache so the UI can render without a
- * second lookup. Both stay flat — no nested objects — so JSON
+ * second lookup. Both stay flat, no nested objects, so JSON
  * serialization is trivial.
  */
 interface IUpdateCheckCache {
     latestVersion: string;
-    /** Epoch ms — when the registry was last successfully probed. */
+    /** Epoch ms, when the registry was last successfully probed. */
     checkedAt: number;
-    /** Epoch ms — when the banner was last printed; null = never shown yet. */
+    /** Epoch ms, when the banner was last printed; null = never shown yet. */
     shownAt: number | null;
 }
 
 /**
- * `PluginLoaderPort` — discovers plugin directories and loads their
+ * `PluginLoaderPort`, discovers plugin directories and loads their
  * extensions. The shape mirrors what the concrete loader actually
  * exposes (see `kernel/adapters/plugin-loader.ts`); the port exists so
  * the CLI consumes the abstract contract via `createPluginLoader(...)`
@@ -2935,12 +3033,12 @@ interface PluginLoaderPort {
     discoverPaths(): string[];
     /**
      * Discover every plugin, attempt to load each, then apply the
-     * cross-root id-collision pass. Never throws — failures are reported
+     * cross-root id-collision pass. Never throws, failures are reported
      * via `IDiscoveredPlugin.status`.
      */
     discoverAndLoadAll(): Promise<IDiscoveredPlugin[]>;
     /**
-     * Load a single plugin from its directory. Never throws — failure is
+     * Load a single plugin from its directory. Never throws, failure is
      * reported via the returned `status`.
      */
     loadOne(pluginPath: string): Promise<IDiscoveredPlugin>;
@@ -2948,7 +3046,7 @@ interface PluginLoaderPort {
 
 /**
  * Row-level filter for `port.scans.findNodes(...)` (driven by
- * `sm list`'s flags). All fields are optional — an empty filter
+ * `sm list`'s flags). All fields are optional, an empty filter
  * returns every node sorted by `path` asc.
  */
 interface INodeFilter {
@@ -2972,7 +3070,7 @@ interface INodeFilter {
     limit?: number;
 }
 /**
- * Bundled fetch for `port.scans.findNode(path)` — one node and
+ * Bundled fetch for `port.scans.findNode(path)`, one node and
  * everything `sm show <path>` displays alongside it. Every field is
  * computed from `scan_*` zone reads only; per-domain data (history,
  * jobs, plugin enrichments) ships through other namespaces.
@@ -3006,7 +3104,7 @@ interface IPersistOptions {
     enrichments?: IEnrichmentRecord[];
     contributions?: IContributionRecord[];
     /**
-     * Phase 3 / View contribution system — active runtime catalog of
+     * Phase 3 / View contribution system, active runtime catalog of
      * registered view contributions, keyed by qualified id
      * `<pluginId>/<extensionId>/<contributionId>`. Passed to the
      * `scan_contributions` upsert so the catalog sweep can drop rows
@@ -3018,10 +3116,10 @@ interface IPersistOptions {
      */
     registeredContributionKeys?: ReadonlySet<string>;
     /**
-     * Phase 3 / View contribution system — set of `(plugin, extension,
+     * Phase 3 / View contribution system, set of `(plugin, extension,
      * node)` tuples where the extension actually RAN against that node
      * in this scan. Format: `<pluginId>/<extensionId>/<nodePath>` (no
-     * contribution-id segment — the sweep operates at the (plugin,
+     * contribution-id segment, the sweep operates at the (plugin,
      * extension, node) level and inspects the buffer to decide which
      * contribution-ids survive).
      *
@@ -3044,7 +3142,7 @@ interface IPersistOptions {
     freshlyRunTuples?: ReadonlySet<string>;
 }
 /**
- * Issue row as the storage layer sees it — paired with its DB-assigned
+ * Issue row as the storage layer sees it, paired with its DB-assigned
  * id so `port.issues.deleteById(id)` can target it inside a
  * transaction. The runtime `Issue` shape (per `issue.schema.json`) does
  * not carry `id` because the spec models issues as ephemeral findings
@@ -3055,6 +3153,54 @@ interface IIssueRow {
     id: number;
     issue: Issue;
 }
+/**
+ * Filter + pagination shape for `port.issues.list(...)`, driven by the
+ * BFF's `/api/issues` route. Every field is optional, an empty filter
+ * returns every issue ordered by `id` ASC (insertion order, stable
+ * across pages so `offset` / `limit` paging is deterministic).
+ *
+ * The three semantic filters mirror `/api/issues`'s query params:
+ *
+ *   - `severities`, narrowed list of `Severity` values. Empty / absent
+ *     matches every severity.
+ *   - `analyzerIds`, accepts qualified (`<plugin>/<id>`) AND short
+ *     (`<id>`) forms; the suffix-match semantics live in
+ *     `matchesAnalyzerFilter`. Each entry generates two SQL clauses
+ *     (`= ?` and `LIKE '%/' || ?`) ORed together so the filter remains
+ *     a single SQL pass with parameterised values, no string
+ *     interpolation. Empty / absent matches every analyzer id.
+ *   - `nodePath`, keeps issues whose `nodeIds` JSON array contains the
+ *     given path (correlated EXISTS over `json_each`). Absent / null
+ *     skips the filter.
+ *
+ * Pagination is mandatory; the route layer fills the defaults via
+ * `parsePagination`. `total` in `IIssueListResult` reports the total
+ * MATCHING the filters (not just the page slice) so the SPA can
+ * surface a correct page-count without a second round-trip.
+ */
+interface IIssueListFilter {
+    /**
+     * Severity tokens to match. Typed as open `string` (not the
+     * `Severity` union) so an unknown value from a URL query string
+     * surfaces as a zero-match SQL query, not a kernel validation
+     * error. The adapter parameterises each entry into the `IN(...)`
+     * clause; unrecognised severities simply match no rows.
+     */
+    severities?: readonly string[];
+    analyzerIds?: readonly string[];
+    nodePath?: string | null;
+    offset: number;
+    limit: number;
+}
+/**
+ * Output of `port.issues.list(...)`. `items` is the page slice (length
+ * ≤ `filter.limit`); `total` is the count of rows matching the filters
+ * before pagination was applied.
+ */
+interface IIssueListResult {
+    items: Issue[];
+    total: number;
+}
 /** Output of `port.jobs.pruneTerminal` / `listTerminalCandidates`. */
 interface IPruneResult {
     /** How many `state_jobs` rows were deleted (or would be, in dry-run). */
@@ -3101,7 +3247,7 @@ interface IMigrateNodeFksReport {
     /**
      * Collisions encountered when migrating any of the keyed-by-node
      * `state_*` tables because a row already existed at the destination
-     * PK. The pre-existing rows are preserved — the migrating rows are
+     * PK. The pre-existing rows are preserved, the migrating rows are
      * dropped (deleted from `fromPath` without a corresponding INSERT).
      * One entry per dropped row, with the affected PK fields included
      * for diagnostic output. `state_node_favorites` has no composite key
@@ -3184,7 +3330,7 @@ interface IPluginApplyResult {
 
 /**
  * Subset of `StoragePort` exposed inside a `transaction(fn)` callback.
- * Lifecycle methods are intentionally omitted — a transaction that
+ * Lifecycle methods are intentionally omitted, a transaction that
  * tries to `init()` the adapter mid-flight is a category error.
  *
  * Every callable in the subset MUST run on the same underlying
@@ -3205,7 +3351,7 @@ interface ITransactionalStorage {
          * Upsert a batch of fresh enrichment records produced by an
          * extractor pass. Composite PK is `(nodePath, extractorId)`;
          * conflict → replace. Every row lands with `stale = 0` (the
-         * caller just refreshed it; ROADMAP §B.10 — staleness is
+         * caller just refreshed it; ROADMAP §B.10, staleness is
          * computed downstream when the body hash changes again).
          */
         upsertMany(records: IEnrichmentRecord[]): Promise<void>;
@@ -3229,23 +3375,23 @@ interface StoragePort {
          * Persist a fresh `ScanResult` (replace-all on the scan zone).
          * Called by `sm scan` after the orchestrator returns. The renames /
          * extractor-runs / enrichments side bags ride along inside the
-         * same transaction — the call is atomic from the caller's view.
+         * same transaction, the call is atomic from the caller's view.
          */
         persist(result: ScanResult, opts?: IPersistOptions): Promise<void>;
         /**
          * Hydrate the persisted `ScanResult`. Returns the snapshot the
-         * scan zone holds today (including external-Provider kinds —
+         * scan zone holds today (including external-Provider kinds,
          * `node.kind` is open string per `node.schema.json`).
          */
         load(): Promise<ScanResult>;
         /**
-         * Spec § A.9 — fine-grained extractor-runs cache breadcrumbs.
+         * Spec § A.9, fine-grained extractor-runs cache breadcrumbs.
          * Returns `Map<nodePath, Map<qualifiedExtractorId, IPriorExtractorRun>>`.
          * Inner value carries `bodyHash` AND `sidecarAnnotationsHash`; both
          * participate in the cache hit condition for every Extractor.
          */
         loadExtractorRuns(): Promise<Map<string, Map<string, IPriorExtractorRun>>>;
-        /** Universal enrichment layer — every persisted `(node, extractor)` pair. */
+        /** Universal enrichment layer, every persisted `(node, extractor)` pair. */
         loadNodeEnrichments(): Promise<IPersistedEnrichment[]>;
         /**
          * Row counts for `scan_nodes` / `scan_links` / `scan_issues`.
@@ -3261,7 +3407,7 @@ interface StoragePort {
         findNode(path: string): Promise<INodeBundle | null>;
     };
     /**
-     * Phase 3 / View contribution system — read access to
+     * Phase 3 / View contribution system, read access to
      * `scan_contributions`, plus the targeted purge used by
      * `sm plugins disable` to clear stale rows immediately at toggle time.
      * Bulk writes still happen exclusively via
@@ -3315,6 +3461,22 @@ interface StoragePort {
     issues: {
         /** Every issue from the latest scan, in insertion order. */
         listAll(): Promise<Issue[]>;
+        /**
+         * Paginated, filtered issue read. Drives `/api/issues` (the BFF
+         * route used to call `listAll()` and filter in JS, which loaded
+         * every persisted issue into memory before paging; the audit
+         * L6 fix pushes both filtering AND pagination into SQL).
+         *
+         * `total` in the result is the count matching the filters BEFORE
+         * pagination is applied; `items` is the page slice (length ≤
+         * `filter.limit`). Order is `id` ASC (insertion order, stable
+         * across pages so the route's `offset` / `limit` is deterministic).
+         *
+         * Empty filters match every row (the route still passes
+         * `offset` + `limit` so pagination always applies). See
+         * `IIssueListFilter` for the per-field semantics.
+         */
+        list(filter: IIssueListFilter): Promise<IIssueListResult>;
         /**
          * Issue rows whose runtime `Issue` shape passes `predicate`.
          * `port.issues.findActive((i) => i.analyzerId === 'orphan')` is the
@@ -3364,19 +3526,19 @@ interface StoragePort {
          * `path.resolve()`. The CLI's `sm job prune --orphan-files` flow
          * pairs this set with `kernel/jobs/orphan-files.ts:findOrphanJobFiles`
          * (which walks the directory) to compute the MD files on disk that
-         * no row references — keeps the storage layer FS-free.
+         * no row references, keeps the storage layer FS-free.
          */
         listReferencedFilePaths(): Promise<Set<string>>;
     };
     /**
      * Generic key/value preferences keyed by a stable string. Backs the
-     * `config_preferences` table — one row per `key`, `value_json` is a
+     * `config_preferences` table, one row per `key`, `value_json` is a
      * single JSON blob the caller serialises. Keys with the `_kernel.`
      * prefix are reserved for kernel-managed entries (today: the
      * update-check cache); user-set preferences land under unprefixed
      * keys when those ship.
      *
-     * Read-only by design at the port level — the only writer is the
+     * Read-only by design at the port level, the only writer is the
      * CLI's post-run hook (`cli/util/update-check-banner.ts`), which
      * reaches the persistence helpers directly. The port surfaces the
      * read so the BFF's `GET /api/update-status` projection can stay
@@ -3386,31 +3548,31 @@ interface StoragePort {
         /**
          * Load the update-check cache row. Returns `null` when the row
          * is absent, malformed JSON, or fails the shape guard. Never
-         * throws — read failures degrade silently because the banner is
+         * throws, read failures degrade silently because the banner is
          * a non-essential surface.
          */
         loadUpdateCheckCache(): Promise<IUpdateCheckCache | null>;
         /**
          * Upsert the update-check cache row. Always overwrites the
          * existing JSON blob in place. `updated_at` tracks wall-clock
-         * now — separate from the embedded `checkedAt` field, which
+         * now, separate from the embedded `checkedAt` field, which
          * the caller controls.
          */
         saveUpdateCheckCache(cache: IUpdateCheckCache): Promise<void>;
     };
     favorites: {
         /**
-         * Mark `path` as favorited. Idempotent — a second call refreshes
+         * Mark `path` as favorited. Idempotent, a second call refreshes
          * `favoritedAt` but does not error. The path is FK-semantic to
          * `scan_nodes.path`; the route layer is responsible for confirming
          * the path exists in the live scan before calling.
          */
         set(path: string): Promise<void>;
-        /** Drop the favorite row for `path`. Idempotent — no-op when absent. */
+        /** Drop the favorite row for `path`. Idempotent, no-op when absent. */
         unset(path: string): Promise<void>;
         /**
          * Load every favorited path as a `Set<string>` ready for `O(1)`
-         * membership checks. Used by the BFF's `/api/nodes` decorator —
+         * membership checks. Used by the BFF's `/api/nodes` decorator,
          * one query per request, no SQL JOIN against `scan_nodes`.
          */
         listPaths(): Promise<Set<string>>;
@@ -3484,7 +3646,7 @@ interface StoragePort {
 }
 
 /**
- * `FilesystemPort` — walks roots, reads nodes, writes job files.
+ * `FilesystemPort`, walks roots, reads nodes, writes job files.
  *
  * Shape-only. The real adapter ships with the scan end-to-end pipeline.
  */
@@ -3505,7 +3667,7 @@ interface FilesystemPort {
 }
 
 /**
- * `RunnerPort` — executes an action against a rendered job file.
+ * `RunnerPort`, executes an action against a rendered job file.
  *
  * Shape-only. `ClaudeCliRunner` + `MockRunner` land with the job subsystem
  * (job subsystem + first summarizer).
@@ -3526,7 +3688,7 @@ interface RunnerPort {
 }
 
 /**
- * `LoggerPort` — structured logging port for the kernel.
+ * `LoggerPort`, structured logging port for the kernel.
  *
  * The kernel must NOT write to stdout/stderr directly. Anything that
  * would historically have been a `console.log` / `console.error` goes
@@ -3537,7 +3699,7 @@ interface RunnerPort {
  *
  *   trace < debug < info < warn < error < silent
  *
- * `silent` is a sentinel for filtering only — it never appears as a
+ * `silent` is a sentinel for filtering only, it never appears as a
  * `LogRecord.level`. Setting an adapter to `silent` disables every
  * method.
  */
@@ -3574,7 +3736,7 @@ interface LoggerPort {
  * `InMemoryProgressEmitter`: callers that don't care get a working
  * implementation that does nothing.
  *
- * Every method is intentionally empty — that IS the contract of this
+ * Every method is intentionally empty, that IS the contract of this
  * class. We disable `no-empty-function` for the whole file because
  * adding `// eslint-disable-next-line` to each method would be noise.
  */
@@ -3599,7 +3761,7 @@ declare class SilentLogger implements LoggerPort {
  *     side-channel concern.
  *   - The active impl is a pointer; the exported `log` is a stable
  *     proxy. Imports made before `configureLogger` runs still see the
- *     new impl on every call — no "captured stale logger" bugs.
+ *     new impl on every call, no "captured stale logger" bugs.
  *
  * Tradeoffs accepted:
  *   - Tests must call `resetLogger()` (or replace the active impl) in
@@ -3614,7 +3776,7 @@ declare const log: LoggerPort;
 declare function configureLogger(impl: LoggerPort): void;
 /** Restore the default `SilentLogger`. Call from test teardown. */
 declare function resetLogger(): void;
-/** Inspect the active logger. Test-only — production code uses `log`. */
+/** Inspect the active logger. Test-only, production code uses `log`. */
 declare function getActiveLogger(): LoggerPort;
 
 /**
@@ -3633,7 +3795,7 @@ declare function getActiveLogger(): LoggerPort;
  * Error policy: a hook that throws is caught here, logged through a
  * synthetic `extension.error` event with kind `hook-error`, and the
  * caller continues. A buggy hook MUST NOT block the main pipeline (or
- * the CLI exit path) — that would invert the design intent (hooks
+ * the CLI exit path), that would invert the design intent (hooks
  * REACT to events, they never steer them).
  *
  * The module lives under `kernel/extensions/` (alongside the `IHook`
@@ -3642,7 +3804,7 @@ declare function getActiveLogger(): LoggerPort;
  * `analyzer.completed`, `action.completed`, `job.*`) and the CLI entry
  * for the two CLI-process-driven triggers (`boot`, `shutdown`).
  * Pulling the dispatcher out of the orchestrator keeps both consumers
- * symmetric — same indexing, same filter semantics, same error
+ * symmetric, same indexing, same filter semantics, same error
  * policy.
  */
 
@@ -3671,20 +3833,20 @@ declare function makeEvent(type: string, data: unknown): ProgressEvent;
 interface Kernel {
     registry: Registry;
     /**
-     * Step 9.6.6 — read-only catalog of plugin-contributed annotation
+     * Step 9.6.6, read-only catalog of plugin-contributed annotation
      * keys, keyed by `(pluginId, key)`. Populated at plugin-load time;
      * pure read with no side effects. Built-in catalog (from
      * `annotations.schema.json`) is NOT included here.
      */
     getRegisteredAnnotationKeys: () => readonly IRegisteredAnnotationKey[];
     /**
-     * Internal — replace the frozen catalog. Called once by the
+     * Internal, replace the frozen catalog. Called once by the
      * plugin runtime composer after every plugin has loaded; consumers
      * MUST treat the resulting array as immutable.
      */
     setRegisteredAnnotationKeys: (entries: readonly IRegisteredAnnotationKey[]) => void;
     /**
-     * Step 11.x — read-only catalog of plugin-contributed view
+     * Step 11.x, read-only catalog of plugin-contributed view
      * contributions, keyed by `(pluginId, extensionId, contributionId)`.
      * Populated at plugin-load time; pure read with no side effects.
      * Mirror of `getRegisteredAnnotationKeys` for the view contribution
@@ -3693,7 +3855,7 @@ interface Kernel {
      */
     getRegisteredViewContributions: () => readonly IRegisteredViewContribution[];
     /**
-     * Internal — replace the frozen view-contribution catalog. Called
+     * Internal, replace the frozen view-contribution catalog. Called
      * once by the plugin runtime composer after every plugin has loaded;
      * consumers MUST treat the resulting array as immutable.
      */