@skill-map/cli 0.55.0 → 0.57.0

package/dist/kernel/index.d.ts

@@ -7,7 +7,7 @@ type TSlotName = 'card.title.right' | 'card.subtitle.left' | 'card.footer.left'
  * Closed enum of input-type names for plugin settings. Mirror of
  * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
  */
-type TInputTypeName = 'string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list';
+type TInputTypeName = 'string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'number' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list';
 /**
  * Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>` severities. Used by counter, tag, alert, and icon slots for color/contrast hints. The UI maps each severity to a theme-aware tint; plugins do not pick raw colors.
  */
@@ -115,7 +115,7 @@ interface ActionPrompt {
     /**
      * Input-type id from the closed catalog. The UI renders the matching control before dispatch (`single-string`, `enum-pick` and `string-list` today; other types degrade to a graceful 'unsupported' notice).
      */
-    inputType: ('string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list') & string;
+    inputType: ('string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'number' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list') & string;
     /**
      * Key under which the collected value is placed in the dispatch `input` body.
      */
@@ -390,6 +390,13 @@ interface ISetting_Integer extends ISettingCommon {
     max?: number;
     step?: number;
 }
+interface ISetting_Number extends ISettingCommon {
+    type: 'number';
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
 interface ISetting_EnumOption {
     value: string;
     label: string;
@@ -446,7 +453,7 @@ interface ISetting_KeyValueList extends ISettingCommon {
  *
  * Mirror of `input-types.schema.json#/$defs/ISettingDeclaration`.
  */
-type TSettingDeclaration = ISetting_StringList | ISetting_SingleString | ISetting_BooleanFlag | ISetting_Integer | ISetting_EnumPick | ISetting_EnumMultipick | ISetting_PathGlob | ISetting_Regex | ISetting_Secret | ISetting_KeyValueList;
+type TSettingDeclaration = ISetting_StringList | ISetting_SingleString | ISetting_BooleanFlag | ISetting_Integer | ISetting_Number | ISetting_EnumPick | ISetting_EnumMultipick | ISetting_PathGlob | ISetting_Regex | ISetting_Secret | ISetting_KeyValueList;
 /**
  * Runtime value type for a setting, derived from its declaration. The
  * kernel exposes settings to extractors as `Record<string, TSettingValue>`
@@ -809,6 +816,29 @@ type LinkKind = 'invokes' | 'references' | 'mentions' | 'supersedes' | 'points';
  * enum check. Missing confidence defaults to `ConfidenceTier.MEDIUM`.
  */
 type Confidence = number;
+/**
+ * A single confidence-scoring operation a `score`-phase analyzer
+ * contributes via `ctx.adjustConfidence(link, op)`. The orchestrator
+ * folds every op on a link into the final `confidence` (see
+ * `orchestrator/confidence-score.ts` for the algebra):
+ *   - `set`   hard override (resolved → 1.0, reserved → 0.1)
+ *   - `delta` additive, may be negative (third-party heuristics)
+ *   - `ceil`  upper cap, lowers only (broken → 0.5)
+ *   - `floor` lower bound, raises only
+ */
+type TConfidenceOp = {
+    readonly kind: 'set';
+    readonly value: number;
+} | {
+    readonly kind: 'delta';
+    readonly value: number;
+} | {
+    readonly kind: 'ceil';
+    readonly value: number;
+} | {
+    readonly kind: 'floor';
+    readonly value: number;
+};
 type Severity = 'error' | 'warn' | 'info';
 type Stability = 'experimental' | 'stable' | 'deprecated';
 /**
@@ -1125,11 +1155,10 @@ interface Signal {
      * raw extractor emissions (before the resolver runs). When
      * `outcome === 'materialised'`, `winnerIndex` points into `candidates[]`
      * of the candidate the resolver chose; a corresponding `Link` was added
-     * to the graph. When `outcome === 'rejected'`, one of `rejectedBy` /
-     * `extractorDisabled` / `belowFloor` is set and no Link materialised.
-     * Both materialised and rejected Signals remain on
-     * `IAnalyzerContext.signals` so the `core/signal-collision` analyzer can
-     * surface losers as `warn` issues. Mirrors
+     * to the graph. When `outcome === 'rejected'`, `rejectedBy` is set and
+     * no Link materialised. Both materialised and rejected Signals remain on
+     * `IAnalyzerContext.signals` so the `core/extractor-collision` analyzer
+     * can surface losers as `warn` issues. Mirrors
      * `signal.schema.json#/properties/resolution`.
      */
     resolution?: ISignalResolution;
@@ -1155,24 +1184,6 @@ interface ISignalResolution {
         extractorId: string;
         reason: 'kind-priority' | 'higher-confidence' | 'longer-range' | 'earlier-declaration';
     };
-    /**
-     * Phase 4+ stub: populated when every candidate of this Signal came from
-     * an extractor the operator disabled via
-     * `plugins.<id>.extensions.<extId>.enabled`. Today the resolver never
-     * sets this; documented so analyzer surfaces can be built when the filter
-     * lands.
-     */
-    extractorDisabled?: {
-        extractorId: string;
-    };
-    /**
-     * Phase 4+ stub: populated when every candidate's `confidence` fell below
-     * the configured floor. Today the resolver materialises every Signal that
-     * survives overlap regardless of confidence.
-     */
-    belowFloor?: {
-        threshold: number;
-    };
 }
 interface IssueFix {
     summary?: string;
@@ -1672,6 +1683,55 @@ declare function makePluginStore(opts: {
     persistDedicated?: IDedicatedStorePersist;
 }): TPluginStore | undefined;
 
+/**
+ * Combination algebra for plugin-contributed link-confidence adjustments.
+ *
+ * Confidence ([0,1]) starts at the kernel's 1.0 baseline (seeded on every
+ * link by `liftResolvedLinkConfidence`). `score`-phase analyzers then
+ * contribute attributed operations via `ctx.adjustConfidence(link, op)`;
+ * the orchestrator buffers them and folds all ops for a link into a final
+ * value with `foldConfidence`. The kernel dogfoods this exact API through
+ * two built-in score-phase detectors, each co-locating its penalty op
+ * with the finding it reports: `core/name-reserved`
+ * (reserved → `delta -0.9` → 0.1), `core/reference-broken`
+ * (broken → `delta -0.5` → 0.5). A clean-resolved or untouched link folds
+ * to `clamp(base)` and keeps the 1.0 baseline.
+ *
+ * The fold is deterministic and order-independent across the four
+ * buckets (set / delta / floor / ceil are each commutative):
+ *   1. base = the extractor-emitted confidence.
+ *   2. `set`: a hard override. When more than one `set` lands on a link
+ *      the LAST in the caller's canonical order wins (the caller pre-
+ *      sorts ops by `(pluginId, extensionId)` so the winner is stable);
+ *      a single `set` simply replaces the base.
+ *   3. `delta`: additive (may be negative), summed.
+ *   4. `floor`: raise to at least the value (`max`).
+ *   5. `ceil`: lower to at most the value (`min`) — today's broken cap.
+ *      Applied AFTER floor so a cap dominates a floor/ceil collision.
+ *   6. clamp to [0,1] ONCE at the end, so opposing deltas round-trip
+ *      (e.g. `-0.4` then `+0.4` returns to base, never clipped midway).
+ *
+ * A link no scorer touches folds to `clamp(base)` (the kernel's 1.0
+ * baseline), identical to a clean-resolved link. With only the built-in
+ * detectors active a link is at most reserved OR broken (mutually
+ * exclusive), so it gets at most one penalty delta and folds to 0.1 / 0.5
+ * respectively; a clean link keeps the 1.0 base. Third-party scorers layer
+ * additional ops on top, summed deterministically before the single clamp.
+ */
+
+/**
+ * One attributed adjustment, buffered by the orchestrator as a scorer
+ * calls `adjustConfidence`. `link` is held by object identity (the same
+ * link objects flow through the post-walk pipeline). Persisted to
+ * `scan_link_scores` for the "why is this link at X?" audit trail.
+ */
+interface IConfidenceAdjustment {
+    readonly link: Link;
+    readonly pluginId: string;
+    readonly extensionId: string;
+    readonly op: TConfidenceOp;
+}
+
 /**
  * Row-level filter for `port.scans.findNodes(...)` (driven by
  * `sm list`'s flags). All fields are optional, an empty filter
@@ -1720,11 +1780,11 @@ interface INodeCounts {
     issues: number;
 }
 /**
- * Lightweight option bag for `port.scans.persist`. Mirrors the trailing
- * arguments of the legacy `persistScanResult(db, result, renameOps,
- * extractorRuns, enrichments)` free function so the adapter
- * implementation is a one-line delegation today; the named-bag shape
- * tomorrow lets new optional inputs land without breaking callers.
+ * Lightweight option bag for `port.scans.persist`. Mirrors the optional
+ * inputs of the `persistScanResult(db, result, inputs)` free function
+ * (`IPersistScanInputs` in `kernel/adapters/sqlite/scan-persistence.ts`),
+ * so the adapter implementation is a one-line delegation; the named-bag
+ * shape lets new optional inputs land without breaking callers.
  */
 interface IPersistOptions {
     renameOps?: RenameOp[];
@@ -1740,6 +1800,18 @@ interface IPersistOptions {
      * scan clears any stale rows). Surfaced by `sm plugins doctor`.
      */
     contributionErrors?: IContributionErrorRecord[];
+    /**
+     * Per-op confidence-attribution audit trail for `scan_link_scores`.
+     * One entry per attributed `ctx.adjustConfidence(link, op)` call a
+     * `score`-phase analyzer buffered this scan; the orchestrator already
+     * folded them into `link.confidence`, so these rows are the attribution
+     * (which plugin / extension / op moved a given link, plus the folded
+     * `result_confidence`). Plain REPLACE-ALL into `scan_link_scores`
+     * (delete all, then insert), the same posture as `scan_issues`. Empty /
+     * absent wipes the table (a scan whose scorers touched nothing clears
+     * any stale rows).
+     */
+    linkScores?: IConfidenceAdjustment[];
     /**
      * Phase 3 / View contribution system, active runtime catalog of
      * registered view contributions, keyed by qualified id
@@ -2933,6 +3005,12 @@ interface IAnalyzerOrphanSidecar {
 interface IAnalyzerContext {
     nodes: Node[];
     links: Link[];
+    /**
+     * Resolved values of the analyzer's declared `settings`, populated
+     * from project config + user overrides. Empty object when no settings
+     * are declared.
+     */
+    settings: Record<string, unknown>;
     /**
      * Step 9.6.2, orphaned sidecars discovered during the scan walk.
      * Empty when sidecar discovery did not run (legacy callers) or
@@ -2970,18 +3048,6 @@ interface IAnalyzerContext {
      * 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
-     * built-in `core/job-file-orphan` analyzer projects each as a `warn`
-     * issue. Pre-computed by the driving adapter (CLI / BFF) inside its
-     * already-open storage transaction (mirrors the `orphanSidecars`
-     * pattern: detection lives outside the analyzer, the analyzer only
-     * projects). Absent (or empty) when the caller does not maintain a
-     * jobs directory, when the storage path is unavailable, or when no
-     * orphan files exist. Treat as read-only.
-     */
-    orphanJobFiles?: readonly string[];
     /**
      * Issues emitted by analyzers that already ran in the current pass.
      * Lets a late-phase analyzer (`core/issue-counter`) compute
@@ -3024,6 +3090,37 @@ interface IAnalyzerContext {
      * `runScan` sites that never wired the field through).
      */
     reservedNodePaths?: ReadonlySet<string>;
+    /**
+     * Links the post-walk lift judged genuinely broken: target matches no
+     * node `path` AND the stripped trigger matches no entry in the cross-
+     * kind name index (`spec/architecture.md` §Provider · resolution
+     * rules). Computed once per scan by the orchestrator from the same
+     * `deriveNodeIdentifiers`-backed index the confidence-lift transform
+     * uses, so a link that resolves only via a filename / dirname
+     * identifier is NOT in the set. Membership is by object identity (the
+     * orchestrator threads the SAME link objects). The single consumer is
+     * `core/reference-broken`, which projects one issue per member (after
+     * its `referenceablePaths` escape hatch). Absent for legacy callers
+     * that never wired the field through, the rule then emits nothing.
+     */
+    brokenLinks?: ReadonlySet<Link>;
+    /**
+     * Names claimed by two or more distinct nodes, keyed by the normalised
+     * name. A node contributes only when its kind declares `frontmatter.name`
+     * as a resolution identifier (so plain `core/markdown` nodes, addressed
+     * by path, never collide) and it carries a non-empty `name`. Names that
+     * normalise to the same value (e.g. `Deploy` / `deploy`) collide, mirroring
+     * how the resolver keys on the normalised identifier. Computed once per
+     * scan by the orchestrator from the same kind registry the resolver uses,
+     * so analyzers project it without re-deriving (the `brokenLinks` /
+     * `reservedNodePaths` precompute-and-project pattern). The single consumer
+     * is `core/name-collision`, which emits one `error` per entry. Absent for
+     * legacy callers that never wired the field through.
+     */
+    nameCollisions?: ReadonlyMap<string, readonly {
+        readonly path: string;
+        readonly kind: string;
+    }[]>;
     /**
      * Absolute path of the scan's project root (cwd of the invocation).
      * Threaded into the analyzer pass so an analyzer that needs to
@@ -3068,6 +3165,17 @@ interface IAnalyzerContext {
      * emissions (`scan_contributions`).
      */
     emitContribution<C extends IViewContribution>(nodePath: string, ref: C, payload: SlotPayload<C['slot']>): void;
+    /**
+     * Contribute a confidence adjustment to a link. Usable ONLY from a
+     * `score`-phase analyzer; the orchestrator records it attributed to
+     * the calling extension (`pluginId` / `extensionId`, like
+     * `emitContribution`) and folds every op on a link into the final
+     * `link.confidence` before the `detect` phase. `link` must be one of
+     * `ctx.links` (matched by object identity). Present ONLY in the
+     * `score` phase (absent for `detect` / `aggregate` and legacy
+     * callers), mirroring the other orchestrator-injected ctx fields.
+     */
+    adjustConfidence?(link: Link, op: TConfidenceOp): void;
 }
 interface IAnalyzer extends IExtensionBase {
     /** Discriminant injected by the loader from the folder structure. */
@@ -3094,22 +3202,31 @@ interface IAnalyzer extends IExtensionBase {
      * Execution phase. Drives the order the orchestrator schedules
      * analyzers in:
      *
+     *   - `'score'`, runs strictly BEFORE every `detect`-phase analyzer.
+     *     The ONLY phase permitted to write: it adjusts link confidence
+     *     via `ctx.adjustConfidence(link, op)`. The orchestrator folds
+     *     every score-phase op into `link.confidence` before the read-
+     *     only `detect` phase runs, so the `detect` analyzers see the
+     *     final value. The kernel seeds the 1.0 confidence baseline on
+     *     every link, then dogfoods this phase via two built-in score-phase
+     *     detectors (`core/name-reserved`, `core/reference-broken`), each
+     *     co-locating its penalty `delta` with the finding it reports.
      *   - `'detect'` (default), the main pass. Walks nodes / links and
-     *     emits its own findings. Most analyzers live here.
+     *     emits its own findings. Most analyzers live here. Read-only.
      *   - `'aggregate'`, runs strictly AFTER every `detect`-phase
      *     analyzer has finished. The orchestrator passes the full
      *     issue accumulator on `ctx.accumulatedIssues`, so an
      *     aggregator can compute cross-analyzer summaries (per-node
      *     severity totals, etc.) without re-reading the persisted DB.
      *     Aggregators emit contributions; emitting issues is allowed
-     *     but uncommon.
+     *     but uncommon. Read-only.
      *
-     * Two-phase scheduling is the clean alternative to ordering
-     * analyzers by hand in the built-ins registry: filesystem-sorted
-     * generators can keep their alphabetical output, the orchestrator
-     * applies the phase sort at run-time.
+     * Phase scheduling is the clean alternative to ordering analyzers by
+     * hand in the built-ins registry: filesystem-sorted generators can
+     * keep their alphabetical output, the orchestrator applies the phase
+     * sort (`score` < `detect` < `aggregate`) at run-time.
      */
-    phase?: 'detect' | 'aggregate';
+    phase?: 'score' | 'detect' | 'aggregate';
     evaluate(ctx: IAnalyzerContext): Issue[] | Promise<Issue[]>;
 }
 
@@ -3285,6 +3402,12 @@ interface IFormatterContext {
     nodes: Node[];
     links: Link[];
     issues: Issue[];
+    /**
+     * Resolved values of the formatter's declared `settings`, populated
+     * from project config + user overrides. Empty object when no settings
+     * are declared.
+     */
+    settings: Record<string, unknown>;
     /**
      * Full persisted scan, when the caller has it on hand. Optional so
      * formatters that only consume (nodes, links, issues) keep working
@@ -3388,6 +3511,12 @@ declare const HOOK_TRIGGERS: readonly THookTrigger[];
  * Deterministic hooks SHOULD ignore the field.
  */
 interface IHookContext {
+    /**
+     * Resolved values of the hook's declared `settings`, populated from
+     * project config + user overrides. Empty object when no settings are
+     * declared.
+     */
+    settings: Record<string, unknown>;
     /** The raw event the dispatcher matched. */
     event: {
         type: THookTrigger;
@@ -3882,21 +4011,6 @@ interface RunScanOptions {
      * mock without spinning up a DB.
      */
     pluginStores?: ReadonlyMap<string, TPluginStore>;
-    /**
-     * Pre-computed absolute paths of orphan job MD files (files under
-     * `.skill-map/jobs/` whose absolute path appears nowhere in
-     * `state_jobs.filePath`). Threaded into the rule pass so the
-     * built-in `core/job-file-orphan` rule can project each as a `warn`
-     * issue without the kernel reaching for the storage port or doing
-     * 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
-     * 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`).
-     */
-    orphanJobFiles?: readonly string[];
     /**
      * Side set of absolute file paths the operator opted into for
      * link-validation purposes via `scan.referencePaths`. Threaded
@@ -3980,6 +4094,7 @@ declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): P
     enrichments: IEnrichmentRecord[];
     contributions: IContributionRecord[];
     contributionErrors: IContributionErrorRecord[];
+    linkScores: IConfidenceAdjustment[];
     freshlyRunTuples: ReadonlySet<string>;
 }>;
 declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
@@ -4178,7 +4293,7 @@ declare function createChokidarWatcher(opts: ICreateFsWatcherOptions): IFsWatche
  *     a reason narrowing what diverged.
  *
  *   - **Link**: `(source, target, kind, normalizedTrigger ?? '')`. This
- *     mirrors the link-conflict rule and `sm show` aggregation,
+ *     mirrors the link-kind-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