@klhapp/skillmux 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.2](https://github.com/klhq/skillmux/compare/v1.3.1...v1.3.2) (2026-07-31)
+
+
+### Added
+
+* **doctor:** flag uncalibrated or stale inference thresholds ([#99](https://github.com/klhq/skillmux/issues/99)) ([c8f684b](https://github.com/klhq/skillmux/commit/c8f684b6aedf6788def4cdc0fe49fff233569844))
+
+
+### Chores
+
+* pin next release to 1.3.2 instead of 1.4.0 (take 2) ([#102](https://github.com/klhq/skillmux/issues/102)) ([bbbb7dd](https://github.com/klhq/skillmux/commit/bbbb7dd838d691735e797f39de7d4277b95f5187))
+
 ## [1.3.1](https://github.com/klhq/skillmux/compare/v1.3.0...v1.3.1) (2026-07-31)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/adapters.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { applyCalibrationRun, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, summarizeDatasetProvenance, type CalibrationResult } from "./calibrate";
+import { applyCalibrationRun, computeCorpusFingerprint, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, summarizeDatasetProvenance, type CalibrationResult } from "./calibrate";
 import { createClients } from "./clients";
 import { DEFAULT_CONFIG_PATH, embeddingFingerprint, expandHome, loadConfig, rerankerFingerprint } from "./config";
 import { openIndex } from "./db";
@@ -141,10 +141,12 @@ export class LocalAdapter implements TargetAdapter {
     const datasetFile = opts?.datasetPath ?? join(expandHome(config.state_dir), "queries.json");
     const indexDb = openIndex(expandHome(config.state_dir));
     let indexedSkills: Array<{ skill_id: string; content_sha256: string }>;
+    let corpusFingerprint: string;
     try {
       indexedSkills = indexDb
         .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
         .all() as Array<{ skill_id: string; content_sha256: string }>;
+      corpusFingerprint = computeCorpusFingerprint(indexDb);
     } finally {
       indexDb.close();
     }
@@ -180,9 +182,6 @@ export class LocalAdapter implements TargetAdapter {
       throw new Error("A configured remote reranker is required to record calibration.");
     }
     const datasetText = await Bun.file(datasetFile).text();
-    const corpusFingerprint =
-      "vault:" +
-      createHash("sha256").update(JSON.stringify(indexedSkills)).digest("hex");
     const runId = `run_${crypto.randomUUID()}`;
     const db = openCalibrateDb(expandHome(config.state_dir));
     try {

package/src/calibrate.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
@@ -900,6 +901,18 @@ export interface CalibrationRunSummary {
   failed_reason?: CalibrationFailureReason;
 }
 
+/**
+ * Fingerprint the indexed vault content so calibration runs can detect
+ * corpus drift. Must match how `insertCalibrationRun` computes it at
+ * `calibrate run` time.
+ */
+export function computeCorpusFingerprint(indexDb: Database): string {
+  const indexedSkills = indexDb
+    .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
+    .all() as Array<{ skill_id: string; content_sha256: string }>;
+  return "vault:" + createHash("sha256").update(JSON.stringify(indexedSkills)).digest("hex");
+}
+
 /**
  * Open (or create) the calibration evidence database in `stateDir`.
  * Uses a separate `calibrate.sqlite3` file — never the index.sqlite3 used

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import packageJson from "../package.json" with { type: "json" };
 import { Database } from "bun:sqlite";
 import { existsSync, lstatSync, mkdirSync, rmSync } from "node:fs";
 import { hostname } from "node:os";
@@ -170,6 +171,11 @@ async function main() {
   const commandArgs = rawArgv.slice(2);
 
   const command = rawArgv[0];
+  if (command === "--version" || command === "-V") {
+    console.log(packageJson.version);
+    return;
+  }
+
   if (!command || command === "--help" || command === "-h") {
     printHelp();
     return;

package/src/doctor.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync } from "node:fs";
+import { computeCorpusFingerprint, getCalibrationRun, openCalibrateDb } from "./calibrate";
 import { createClients, RemoteInferenceError } from "./clients";
-import { embeddingDimension, expandHome } from "./config";
+import { embeddingDimension, embeddingFingerprint, expandHome, rerankerFingerprint } from "./config";
+import { openIndex } from "./db";
 import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
 import type { Config } from "./types";
@@ -19,6 +21,78 @@ export interface DoctorReport {
   checks: DoctorCheck[];
 }
 
+/**
+ * Warn when live `inference.thresholds` didn't come from an applied
+ * `skillmux calibrate` run — e.g. hand-copied from an example config.
+ * Reranker score scales are not portable across models/adapters/corpora,
+ * so uncalibrated thresholds routinely make automatic matching unreachable
+ * without any visible error.
+ */
+function checkCalibration(config: Config): DoctorCheck {
+  const inference = config.inference;
+  if (inference.mode !== "remote") throw new Error("checkCalibration requires remote inference mode");
+  const runId = inference.calibration?.run_id;
+  if (!runId) {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: "inference.thresholds are set but were never produced by `skillmux calibrate apply` — " +
+        "likely copied from an example config. Reranker scores are not portable across models, " +
+        "adapters, or corpora, so automatic matching may never trigger (or may trigger incorrectly). " +
+        "Run `skillmux calibrate`.",
+    };
+  }
+
+  const calibrateDb = openCalibrateDb(expandHome(config.state_dir));
+  let run;
+  try {
+    run = getCalibrationRun(calibrateDb, runId);
+  } finally {
+    calibrateDb.close();
+  }
+  if (!run) {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: `inference.calibration.run_id "${runId}" was not found in the local calibration ` +
+        "evidence store (state_dir may differ from where it was calibrated). Recalibrate.",
+    };
+  }
+  if (run.status !== "completed") {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: `inference.calibration.run_id "${runId}" has status "${run.status}" and should never ` +
+        "have been applied. Recalibrate.",
+    };
+  }
+
+  const indexDb = openIndex(expandHome(config.state_dir));
+  let currentCorpusFingerprint: string;
+  try {
+    currentCorpusFingerprint = computeCorpusFingerprint(indexDb);
+  } finally {
+    indexDb.close();
+  }
+
+  const stale = [
+    rerankerFingerprint(config) !== run.reranker_fingerprint ? "reranker" : null,
+    embeddingFingerprint(config) !== run.embedding_fingerprint ? "embedding" : null,
+    currentCorpusFingerprint !== run.corpus_fingerprint ? "vault contents" : null,
+  ].filter((part): part is string => part !== null);
+
+  if (stale.length > 0) {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: `applied calibration run "${runId}" is stale — ${stale.join(", ")} changed since it was ` +
+        "calibrated. Recalibrate.",
+    };
+  }
+
+  return { name: "calibration", ok: true, detail: `thresholds from applied calibration run "${runId}"` };
+}
+
 export async function diagnose(config: Config): Promise<DoctorReport> {
   const checks: DoctorCheck[] = [];
   checks.push({ name: "vault", ok: existsSync(expandHome(config.vault_path)), detail: expandHome(config.vault_path) });
@@ -129,6 +203,10 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
     }
   }
 
+  if (config.inference.mode === "remote" && config.inference.reranker && config.inference.thresholds) {
+    checks.push(checkCalibration(config));
+  }
+
   const inferenceReady = checks.some((check) => check.name === "embedding" && check.ok);
   const coreReady = checks.some((check) => check.name === "vault" && check.ok)
     && checks.some((check) => check.name === "state" && check.ok);

package/src/types.ts

@@ -73,6 +73,7 @@ export interface RemoteInferenceConfig {
   embedding: RemoteEmbeddingConfig;
   reranker?: RemoteRerankerConfig;
   thresholds?: Required<Omit<Thresholds, "candidate_limit">>;
+  calibration?: { run_id: string };
 }
 
 export type InferenceConfig = LocalInferenceConfig | RemoteInferenceConfig;