thumbgate 1.28.2 → 1.28.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "thumbgate",
   "description": "One 👎 becomes a hard rule the agent cannot bypass. Captures thumbs-down feedback, distills it into PreToolUse Pre-Action Checks, enforced across every future Claude Code session.",
-  "version": "1.28.2",
+  "version": "1.28.3",
   "author": {
     "name": "Igor Ganapolsky",
     "email": "ig5973700@gmail.com",

package/.well-known/mcp/server-card.json

@@ -1,6 +1,6 @@
 {
   "name": "thumbgate",
-  "version": "1.28.2",
+  "version": "1.28.3",
   "description": "ThumbGate — 👍👎 feedback that teaches your AI agent. Thumbs down a mistake, it never happens again.",
   "homepage": "https://thumbgate.ai",
   "transport": "stdio",

package/adapters/claude/.mcp.json

@@ -2,13 +2,13 @@
   "mcpServers": {
     "thumbgate": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.28.2", "thumbgate", "serve"]
+      "args": ["--yes", "--package", "thumbgate@1.28.3", "thumbgate", "serve"]
     }
   },
   "hooks": {
     "preToolUse": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.28.2", "thumbgate", "gate-check"]
+      "args": ["--yes", "--package", "thumbgate@1.28.3", "thumbgate", "gate-check"]
     }
   }
 }

package/adapters/mcp/server-stdio.js

@@ -115,7 +115,11 @@ const {
 const {
   retrieveRelevantLessons,
 } = loadOptionalModule(path.join(__dirname, '../../scripts/lesson-retrieval'), () => ({
-  retrieveRelevantLessons: () => [],
+  retrieveRelevantLessons: () => {
+    const error = new Error('retrieve_lessons is unavailable because the packaged retrieval modules are missing.');
+    error.code = 'THUMBGATE_CAPABILITY_UNAVAILABLE';
+    throw error;
+  },
 }));
 const {
   searchThumbgate,
@@ -186,8 +190,13 @@ const PRIVATE_MCP_MODULES = Object.freeze({
   lessonInference: path.resolve(__dirname, '../../scripts/lesson-inference.js'),
   lessonSearch: path.resolve(__dirname, '../../scripts/lesson-search.js'),
 });
-
-const PRIVATE_MCP_TOOL_REQUIREMENTS = Object.freeze({
+const PUBLIC_MCP_MODULES = Object.freeze({
+  lessonRetrieval: path.resolve(__dirname, '../../scripts/lesson-retrieval.js'),
+  lessonReranker: path.resolve(__dirname, '../../scripts/lesson-reranker.js'),
+  crossEncoderReranker: path.resolve(__dirname, '../../scripts/cross-encoder-reranker.js'),
+  lessonEmbeddingIndex: path.resolve(__dirname, '../../scripts/lesson-embedding-index.js'),
+});
+const PRIVATE_TOOL_MODULE_KEYS = Object.freeze({
   search_lessons: ['lessonSearch'],
   reflect_on_feedback: ['reflectorAgent'],
   list_intents: ['intentRouter'],
@@ -204,6 +213,41 @@ const PRIVATE_MCP_TOOL_REQUIREMENTS = Object.freeze({
   managed_agent_status: ['managedLessonAgent'],
   context_stuff_lessons: ['lessonInference'],
 });
+const PUBLIC_TOOL_MODULE_KEYS = Object.freeze({
+  retrieve_lessons: [
+    'lessonRetrieval',
+    'lessonReranker',
+    'crossEncoderReranker',
+    'lessonEmbeddingIndex',
+  ],
+});
+
+function getToolCapability(toolName, options = {}) {
+  const privateKeys = PRIVATE_TOOL_MODULE_KEYS[toolName] || [];
+  const publicKeys = PUBLIC_TOOL_MODULE_KEYS[toolName] || [];
+  const privateModuleAvailable = options.existsSync
+    ? (key) => options.existsSync(PRIVATE_MCP_MODULES[key])
+    : (key) => Boolean(loadPrivateMcpModule(key));
+  const publicModuleAvailable = options.existsSync
+    ? (key) => options.existsSync(PUBLIC_MCP_MODULES[key])
+    : (key) => fs.existsSync(PUBLIC_MCP_MODULES[key]);
+  const missingPrivateModules = privateKeys.filter((key) => !privateModuleAvailable(key));
+  const missingPublicModules = publicKeys.filter((key) => !publicModuleAvailable(key));
+  if (missingPrivateModules.length > 0) {
+    return { available: false, availability: 'private_core', missingModules: missingPrivateModules };
+  }
+  if (missingPublicModules.length > 0) {
+    return { available: false, availability: 'package_incomplete', missingModules: missingPublicModules };
+  }
+  return { available: true, availability: privateKeys.length > 0 ? 'private_core' : 'public', missingModules: [] };
+}
+
+function getExposedTools(profileName = getActiveMcpProfile(), options = {}) {
+  const allowed = new Set(getAllowedTools(profileName));
+  return TOOLS.filter((tool) => allowed.has(tool.name) && getToolCapability(tool.name, options).available);
+}
+
+const PRIVATE_MCP_TOOL_REQUIREMENTS = PRIVATE_TOOL_MODULE_KEYS;
 
 function loadPrivateMcpModule(key) {
   const modulePath = PRIVATE_MCP_MODULES[key];
@@ -223,17 +267,15 @@ function loadPrivateMcpModule(key) {
 }
 
 function isToolAvailable(toolName) {
-  const requirements = PRIVATE_MCP_TOOL_REQUIREMENTS[toolName] || [];
   try {
-    return requirements.every((key) => Boolean(loadPrivateMcpModule(key)));
+    return getToolCapability(toolName).available;
   } catch {
     return false;
   }
 }
 
 function listAvailableTools(profileName = getActiveMcpProfile()) {
-  const allowedTools = new Set(getAllowedTools(profileName));
-  return TOOLS.filter((tool) => allowedTools.has(tool.name) && isToolAvailable(tool.name));
+  return getExposedTools(profileName);
 }
 
 function unavailablePrivateMcpFeature(toolName) {
@@ -263,7 +305,7 @@ const {
   finalizeSession: finalizeFeedbackSession,
 } = require('../../scripts/feedback-session');
 
-const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.28.2' };
+const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.28.3' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -705,7 +747,21 @@ function buildEstimateUncertaintyResponse(args = {}) {
 }
 
 async function callTool(name, args = {}) {
-  assertToolAllowed(name, getActiveMcpProfile());
+  const activeProfile = getActiveMcpProfile();
+  assertToolAllowed(name, activeProfile);
+  const capability = getToolCapability(name);
+  if (!capability.available) {
+    if (capability.availability === 'private_core') {
+      return unavailablePrivateMcpFeature(name);
+    }
+    const error = new Error(
+      `Tool '${name}' is unavailable (${capability.availability}): missing ${capability.missingModules.join(', ')}.`,
+    );
+    error.code = 'THUMBGATE_CAPABILITY_UNAVAILABLE';
+    error.errorCategory = 'capability';
+    error.isRetryable = false;
+    throw error;
+  }
 
   // Validate tool input contract against schema
   const { TOOLS } = require('../../scripts/tool-registry');
@@ -1389,7 +1445,7 @@ async function handleRequest(message) {
     };
   }
   if (message.method === 'ping') return {};
-  if (message.method === 'tools/list') return { tools: listAvailableTools() };
+  if (message.method === 'tools/list') return { tools: getExposedTools() };
   if (message.method === 'tools/call') return callTool(message.params.name, message.params.arguments);
   throw new Error(`Unsupported method: ${message.method}`);
 }
@@ -1581,6 +1637,8 @@ if (require.main === module) startStdioServer();
 
 module.exports = {
   TOOLS,
+  getExposedTools,
+  getToolCapability,
   SAFE_DATA_DIR,
   handleRequest,
   callTool,
@@ -1591,6 +1649,9 @@ module.exports = {
   buildSuggestFixResponse,
   __test__: {
     PRIVATE_MCP_MODULES,
+    PRIVATE_TOOL_MODULE_KEYS,
+    PUBLIC_MCP_MODULES,
+    PUBLIC_TOOL_MODULE_KEYS,
     PRIVATE_MCP_TOOL_REQUIREMENTS,
     loadPrivateMcpModule,
     isToolAvailable,

package/adapters/opencode/opencode.json

@@ -7,7 +7,7 @@
         "npx",
         "--yes",
         "--package",
-        "thumbgate@1.28.2",
+        "thumbgate@1.28.3",
         "thumbgate",
         "serve"
       ],

package/config/gates/default.json

@@ -210,7 +210,8 @@
     {
       "id": "deny-network-egress",
       "layer": "Cloud",
-      "pattern": "fetch\\(|https?://(?!(?:github\\.com|registry\\.npmjs\\.org|api\\.anthropic\\.com|localhost|127\\.0\\.0\\.1|\\[::1\\]|0\\.0\\.0\\.0)(?:[:/?#]|$))|(?:curl|wget)\\s+(?:-\\S+\\s+)*(?!https?://|(?:github\\.com|registry\\.npmjs\\.org|api\\.anthropic\\.com|localhost|127\\.0\\.0\\.1|\\[::1\\]|0\\.0\\.0\\.0)(?:[:/?#]|$))[\\w.-]+\\.[a-z]{2,}",
+      "toolNames": ["Bash"],
+      "pattern": "(?:\\b(?:curl|wget)\\b[^\\n]{0,600}https?://(?!(?:github\\.com|registry\\.npmjs\\.org|api\\.anthropic\\.com|localhost|127\\.0\\.0\\.1|\\[::1\\]|0\\.0\\.0\\.0)(?:[:/?#]|$))[\\w.-]+|\\b(?:curl|wget)\\b\\s+(?:-\\S+\\s+)*(?!(?:https?://)?(?:github\\.com|registry\\.npmjs\\.org|api\\.anthropic\\.com|localhost|127\\.0\\.0\\.1|\\[::1\\]|0\\.0\\.0\\.0)(?:[:/?#]|$))(?:[\\w.-]+\\.)+[a-z]{2,}(?:[:/?#]|\\s|$)|\\bopen\\b[^\\n]{0,240}https?://(?!(?:github\\.com|registry\\.npmjs\\.org|api\\.anthropic\\.com|localhost|127\\.0\\.0\\.1|\\[::1\\]|0\\.0\\.0\\.0)(?:[:/?#]|$))[\\w.-]+|\\bnode\\b[^\\n]{0,240}\\bfetch\\s*\\(|\\bpython3?\\b[^\\n]{0,240}\\b(?:requests\\.(?:get|post)|urllib\\.request))",
       "action": "warn",
       "unless": "egress_approved",
       "message": "Potential unauthorized network egress detected.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thumbgate",
-  "version": "1.28.2",
+  "version": "1.28.3",
   "description": "ThumbGate Pre-Action Checks derive rules from repeated failures, flag risky tool calls, hard-block detected secret leaks, and block matches in strict mode.",
   "homepage": "https://thumbgate.ai",
   "repository": {
@@ -50,6 +50,7 @@
     "scripts/bot-detection.js",
     "scripts/build-metadata.js",
     "scripts/classifier-routing.js",
+    "scripts/cross-encoder-reranker.js",
     "scripts/chatgpt-ads-readiness-pack.js",
     "scripts/claude-feedback-sync.js",
     "scripts/cli-demo.js",
@@ -125,7 +126,10 @@
     "scripts/judge-reward-function.js",
     "scripts/lesson-canonical.js",
     "scripts/lesson-db.js",
+    "scripts/lesson-embedding-index.js",
     "scripts/lesson-inference.js",
+    "scripts/lesson-reranker.js",
+    "scripts/lesson-retrieval.js",
     "scripts/lesson-rotation.js",
     "scripts/lesson-search.js",
     "scripts/lesson-synthesis.js",
@@ -449,7 +453,7 @@
     "test:memory-dedup": "node --test tests/memory-dedup.test.js",
     "test:lesson-db": "node --test tests/lesson-db.test.js",
     "test:lesson-rotation": "node --test tests/lesson-rotation.test.js",
-    "test:feedback-quality": "node --test tests/feedback-quality.test.js tests/feedback-event-idempotency.test.js",
+    "test:feedback-quality": "node --test tests/feedback-quality.test.js tests/feedback-event-idempotency.test.js tests/feedback-capture-e2e.test.js",
     "test:sync-version": "node --test tests/sync-version.test.js",
     "test:release-window": "node --test tests/release-window.test.js",
     "test:team-sync": "node --test tests/team-sync.test.js",
@@ -474,7 +478,7 @@
     "test:okara-money-promo-automation": "node --test tests/okara-money-promo-automation.test.js",
     "test:operator-key-auth": "node --test tests/api-operator-key-auth.test.js",
     "test:cloudflare-sandbox": "node --test tests/cloudflare-dynamic-sandbox.test.js tests/cloudflare-sandbox-api.test.js",
-    "test:mcp-config": "node --test tests/mcp-config.test.js",
+    "test:mcp-config": "node --test tests/mcp-config.test.js tests/mcp-capability-exposure.test.js",
     "test:mcp-tool-annotations": "node --test tests/mcp-tool-annotations.test.js",
     "test:mcp-oauth": "node --test tests/mcp-oauth.test.js",
     "test:mcp-oauth-flow": "node --test tests/mcp-oauth-flow.test.js",
@@ -515,7 +519,7 @@
     "test:quality": "node --test tests/validate-feedback.test.js tests/feedback-quality-eval-python.test.js tests/eval-gate-classifier.test.js",
     "test:intelligence": "node --test tests/intelligence.test.js",
     "test:training-export": "node --test tests/training-export.test.js tests/databricks-export.test.js",
-    "test:deployment": "node --test tests/deployment.test.js tests/deploy-policy.test.js tests/publish-decision.test.js tests/changeset-check.test.js tests/release-notes.test.js tests/sonarcloud-workflow.test.js tests/package-boundary.test.js tests/public-package-boundary.test.js",
+    "test:deployment": "node --test tests/deployment.test.js tests/deploy-policy.test.js tests/publish-decision.test.js tests/changeset-check.test.js tests/release-notes.test.js tests/sonarcloud-workflow.test.js tests/package-boundary.test.js tests/public-package-boundary.test.js tests/packed-feedback-retrieval-e2e.test.js",
     "test:operational-integrity": "node --test tests/operational-integrity.test.js tests/sync-branch-protection.test.js",
     "test:workflow": "node --test tests/parallel-workflow.test.js tests/workflow-contract.test.js tests/positioning-contract.test.js tests/docs-claim-hygiene.test.js tests/thumbgate-scope.test.js tests/workflow-runs.test.js tests/workflow-sprint-intake.test.js tests/revenue-pack-utils.test.js tests/apollo-acquisition.test.js tests/sales-pipeline.test.js tests/github-outreach.test.js tests/enterprise-story.test.js tests/guide-conversion-path.test.js tests/buyer-intent-revenue-assist.test.js",
     "test:sales-pipeline": "node --test tests/sales-pipeline.test.js",

package/public/index.html

@@ -20,7 +20,7 @@ __GOOGLE_SITE_VERIFICATION_META__
 <meta property="og:image" content="https://thumbgate.ai/og.png">
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:image" content="https://thumbgate.ai/og.png">
-<meta name="thumbgate-version" content="1.28.2">
+<meta name="thumbgate-version" content="1.28.3">
 <meta name="keywords" content="ThumbGate, thumbgate, AI agent orchestration, AI experience orchestration, agentic development cycle, AC/DC framework, Guide Generate Verify Solve, agent enforcement layer, pre-action checks, agent governance, Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode, workflow hardening, context engineering, AI authenticity, brand authenticity AI">
 <link rel="canonical" href="__APP_ORIGIN__/">
 <link rel="alternate" type="text/markdown" title="ThumbGate LLM context" href="__APP_ORIGIN__/llm-context.md">
@@ -1776,7 +1776,7 @@ __GA_BOOTSTRAP__
       <a href="https://www.linkedin.com/in/igorganapolsky" target="_blank" rel="noopener">LinkedIn</a>
       <a href="/blog">Blog</a>
     </div>
-    <span class="footer-copy">© 2026 ThumbGate · MIT License · npm v1.28.2</span>
+    <span class="footer-copy">© 2026 ThumbGate · MIT License · npm v1.28.3</span>
   </div>
 </footer>
 

package/public/numbers.html

@@ -25,7 +25,7 @@
   "alternateName": "thumbgate",
   "applicationCategory": "DeveloperApplication",
   "operatingSystem": "Cross-platform, Node.js >=18.18.0",
-  "softwareVersion": "1.28.2",
+  "softwareVersion": "1.28.3",
   "url": "https://thumbgate.ai/numbers",
   "dateModified": "2026-05-07",
   "creator": {
@@ -202,7 +202,7 @@
 <main class="container">
   <h1>The Numbers</h1>
   <p class="subtitle">Generated first-party operational snapshot from the ThumbGate runtime. This is not customer traction, install volume, revenue, or proof that a configured gate has fired.</p>
-  <div class="freshness">Updated: 2026-05-07 · Version 1.28.2</div>
+  <div class="freshness">Updated: 2026-05-07 · Version 1.28.3</div>
   <div class="truth-note"><strong>Read this first:</strong> configured checks are inventory. Recorded blocks and warnings are usage evidence. This snapshot currently reports 0 recorded hard-block event(s) and 0 recorded warning event(s).</div>
 
   <h2>Gate enforcement</h2>

package/scripts/claude-feedback-sync.js

@@ -20,7 +20,7 @@ const { refreshStatuslineCache } = require('./hook-thumbgate-cache-updater');
 const SYNC_STATE_FILE = 'claude-feedback-sync-state.json';
 const DEFAULT_RECENT_FEEDBACK_LIMIT = 250;
 const DEFAULT_PROCESSED_ID_LIMIT = 512;
-const DUPLICATE_WINDOW_MS = 30 * 1000;
+const DUPLICATE_WINDOW_MS = 5 * 60 * 1000;
 
 function getClaudeHistoryPath(options = {}) {
   if (options.historyPath) return options.historyPath;

package/scripts/cli-feedback.js

@@ -116,6 +116,10 @@ function formatCliOutput(result) {
       const capturedIds = memoryId ? `${feedbackId}, ${memoryId}` : feedbackId;
       process.stderr.write(`✅ Feedback captured (${capturedIds})\n`);
     }
+    if (feedbackResult.promoted === false || !memoryId) {
+      const clarification = feedbackResult.prompt || feedbackResult.message || feedbackResult.reason;
+      lines.push(`${D}  Reusable memory: not created${clarification ? ` — ${clarification}` : ''}${RST}`);
+    }
   } else {
     lines.push(`${R}Feedback not accepted: ${feedbackResult?.reason || 'unknown'}${RST}`);
   }

package/scripts/cross-encoder-reranker.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Cross-Encoder Reranker for ThumbGate lesson retrieval.
+ *
+ * Two-stage retrieval:
+ *   Stage 1: Fast candidate retrieval (existing bigram Jaccard + keyword matching)
+ *   Stage 2: Cross-encoder reranking scores query-document pairs jointly
+ *
+ * The cross-encoder evaluates the query AND each lesson together (not independently),
+ * catching false positives that keyword/vector search misses.
+ *
+ * Architecture reference: "Advanced RAG Retrieval: Cross-Encoders & Reranking"
+ * (Towards Data Science, April 2026)
+ *
+ * When LLM is available (ANTHROPIC_API_KEY), uses Claude as the cross-encoder.
+ * Falls back to enhanced heuristic scoring when LLM is unavailable.
+ */
+
+const { retrieveRelevantLessons, scoreRelevance, buildActionSignature } = require('./lesson-retrieval');
+
+/**
+ * Heuristic cross-encoder: scores a (query, document) pair jointly.
+ * Unlike bi-encoder (independent embeddings), this examines the pair together
+ * to find semantic relationships that keyword matching misses.
+ */
+function heuristicCrossEncode(query, document) {
+  const queryLower = (query || '').toLowerCase();
+  const docLower = (document || '').toLowerCase();
+
+  let score = 0;
+
+  // 1. Exact substring containment (strongest signal)
+  if (queryLower.length > 3 && docLower.length > 3 &&
+      (docLower.includes(queryLower) || queryLower.includes(docLower))) {
+    score += 0.9;
+    return Math.min(score, 1);
+  }
+
+  // 2. Shared noun phrases (not just tokens — consecutive word pairs)
+  const queryPhrases = extractPhrases(queryLower);
+  const docPhrases = extractPhrases(docLower);
+  const phraseOverlap = queryPhrases.filter((p) => docPhrases.includes(p));
+  score += Math.min(phraseOverlap.length * 0.15, 0.5);
+
+  // 3. Semantic category matching
+  const categories = {
+    destructive: ['delete', 'remove', 'drop', 'destroy', 'wipe', 'truncate', 'rm -rf', 'force-push', 'reset --hard'],
+    git: ['git', 'push', 'pull', 'merge', 'rebase', 'branch', 'commit', 'checkout', 'stash'],
+    database: ['sql', 'query', 'table', 'migration', 'schema', 'database', 'insert', 'update', 'select'],
+    deploy: ['deploy', 'release', 'publish', 'railway', 'vercel', 'heroku', 'npm publish'],
+    security: ['secret', 'token', 'api key', 'password', 'credential', 'env', '.env', 'pem'],
+    file: ['edit', 'write', 'create', 'modify', 'config', 'package.json', 'readme'],
+  };
+
+  for (const [, terms] of Object.entries(categories)) {
+    const queryHit = terms.some((t) => queryLower.includes(t));
+    const docHit = terms.some((t) => docLower.includes(t));
+    if (queryHit && docHit) {
+      score += 0.25;
+      break; // Only count strongest category match
+    }
+  }
+
+  // 4. Action-target alignment (e.g., "git push" in query matches "push to main" in doc)
+  const queryVerbs = extractVerbs(queryLower);
+  const docVerbs = extractVerbs(docLower);
+  const verbOverlap = queryVerbs.filter((v) => docVerbs.includes(v));
+  score += Math.min(verbOverlap.length * 0.1, 0.3);
+
+  // 5. Negation alignment (both about what NOT to do)
+  const queryNegated = /\b(don'?t|never|avoid|block|prevent|stop)\b/.test(queryLower);
+  const docNegated = /\b(don'?t|never|avoid|block|prevent|stop)\b/.test(docLower);
+  if (queryNegated && docNegated) score += 0.1;
+
+  return Math.min(score, 1);
+}
+
+/**
+ * LLM cross-encoder: uses Claude to score relevance of query-document pairs.
+ * More accurate but requires API key and costs tokens.
+ */
+async function llmCrossEncode(query, documents) {
+  const { isAvailable, callClaudeJson, MODELS } = require('./llm-client');
+  if (!isAvailable()) return null;
+
+  const docList = documents
+    .map((d, i) => `[${i}] ${(d.title || '').slice(0, 100)} | ${(d.content || '').slice(0, 200)}`)
+    .join('\n');
+
+  const prompt = `You are a relevance scoring engine. Given a query and a list of documents, score each document's relevance to the query from 0.0 (irrelevant) to 1.0 (highly relevant).
+
+Query: "${query.slice(0, 300)}"
+
+Documents:
+${docList}
+
+Return ONLY a JSON array of scores, one per document. Example: [0.9, 0.2, 0.7, 0.1, 0.5]
+No other text.`;
+
+  try {
+    const scores = await callClaudeJson({
+      systemPrompt: 'You are a relevance scoring engine. Return only JSON arrays of numbers.',
+      userPrompt: prompt,
+      model: MODELS.FAST,
+      maxTokens: 256,
+      cache: true,
+    });
+    if (Array.isArray(scores) && scores.length === documents.length) {
+      return scores.map((s) => Math.max(0, Math.min(1, Number(s) || 0)));
+    }
+  } catch { /* fall back to heuristic */ }
+  return null;
+}
+
+/**
+ * Two-stage retrieval with cross-encoder reranking.
+ *
+ * Stage 1: Retrieve top N candidates using existing keyword + bigram matching
+ * Stage 2: Rerank candidates using cross-encoder (LLM or heuristic)
+ * Return top K results by cross-encoder score
+ */
+async function retrieveWithReranking(toolName, actionContext, options = {}) {
+  const {
+    candidateCount = 20,
+    maxResults = 5,
+    useLLM = false,
+    feedbackDir,
+  } = options;
+
+  // Stage 1: Fast candidate retrieval (existing system)
+  const candidates = retrieveRelevantLessons(toolName, actionContext, {
+    maxResults: candidateCount,
+    feedbackDir,
+  });
+
+  if (candidates.length === 0) return [];
+  if (candidates.length <= maxResults) return candidates;
+
+  const query = `${toolName || ''} ${actionContext || ''}`.trim();
+
+  // Stage 2: Cross-encoder reranking
+  let rerankedScores;
+
+  if (useLLM) {
+    rerankedScores = await llmCrossEncode(query, candidates);
+  }
+
+  // Fall back to heuristic cross-encoder if LLM unavailable or failed
+  if (!rerankedScores) {
+    rerankedScores = candidates.map((c) => {
+      const docText = `${c.title || ''} ${c.content || ''}`;
+      return heuristicCrossEncode(query, docText);
+    });
+  }
+
+  // Combine original relevance score with cross-encoder score
+  // Weight: 40% original, 60% cross-encoder (cross-encoder is more precise)
+  const reranked = candidates.map((c, i) => ({
+    ...c,
+    crossEncoderScore: rerankedScores[i],
+    combinedScore: c.relevanceScore * 0.4 + rerankedScores[i] * 0.6,
+  }));
+
+  return reranked
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, maxResults);
+}
+
+/**
+ * Synchronous version for use in PreToolUse hooks (cannot be async).
+ */
+function retrieveWithRerankingSync(toolName, actionContext, options = {}) {
+  const {
+    candidateCount = 20,
+    maxResults = 5,
+    feedbackDir,
+  } = options;
+
+  const candidates = retrieveRelevantLessons(toolName, actionContext, {
+    maxResults: candidateCount,
+    feedbackDir,
+  });
+
+  if (candidates.length === 0) return [];
+  if (candidates.length <= maxResults) return candidates;
+
+  const query = `${toolName || ''} ${actionContext || ''}`.trim();
+
+  const rerankedScores = candidates.map((c) => {
+    const docText = `${c.title || ''} ${c.content || ''}`;
+    return heuristicCrossEncode(query, docText);
+  });
+
+  const reranked = candidates.map((c, i) => ({
+    ...c,
+    crossEncoderScore: rerankedScores[i],
+    combinedScore: c.relevanceScore * 0.4 + rerankedScores[i] * 0.6,
+  }));
+
+  return reranked
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, maxResults);
+}
+
+// --- Utility functions ---
+
+function extractPhrases(text) {
+  const words = text.split(/\s+/).filter((w) => w.length > 2);
+  const phrases = [];
+  for (let i = 0; i < words.length - 1; i++) {
+    phrases.push(`${words[i]} ${words[i + 1]}`);
+  }
+  return phrases;
+}
+
+function extractVerbs(text) {
+  const verbPatterns = [
+    'push', 'pull', 'merge', 'delete', 'create', 'edit', 'write', 'read',
+    'deploy', 'install', 'remove', 'run', 'execute', 'build', 'test',
+    'commit', 'rebase', 'reset', 'drop', 'truncate', 'migrate', 'publish',
+    'block', 'allow', 'approve', 'deny', 'warn', 'log',
+  ];
+  return verbPatterns.filter((v) => text.includes(v));
+}
+
+module.exports = {
+  heuristicCrossEncode,
+  llmCrossEncode,
+  retrieveWithReranking,
+  retrieveWithRerankingSync,
+  extractPhrases,
+  extractVerbs,
+};