thumbgate 1.4.2 → 1.4.4

package/scripts/cli-schema.js

@@ -0,0 +1,285 @@
+'use strict';
+
+/**
+ * cli-schema.js — single source of truth for thumbgate CLI commands.
+ *
+ * Inspired by Cloudflare's schema-first CLI architecture: one definition
+ * drives both the CLI help text and the explore TUI command browser.
+ * MCP tool bindings are listed via `mcpTool` so the two surfaces stay in sync.
+ *
+ * Groups: capture | discovery | gates | export | ops | advanced
+ */
+
+const CLI_COMMANDS = [
+  // -------------------------------------------------------------------------
+  // Capture
+  // -------------------------------------------------------------------------
+  {
+    name: 'capture',
+    aliases: ['feedback'],
+    description: 'Capture an up/down signal — turns feedback into a stored lesson',
+    group: 'capture',
+    mcpTool: 'capture_feedback',
+    flags: [
+      { name: 'feedback',        type: 'string',  required: true,  description: 'Signal: up or down' },
+      { name: 'context',         type: 'string',  description: 'One-line reason' },
+      { name: 'what-went-wrong', type: 'string',  description: 'Root cause (negative feedback)' },
+      { name: 'what-to-change',  type: 'string',  description: 'Specific fix required' },
+      { name: 'what-worked',     type: 'string',  description: 'What succeeded (positive feedback)' },
+      { name: 'tags',            type: 'string',  description: 'Comma-separated tags' },
+      { name: 'json',            type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Discovery
+  // -------------------------------------------------------------------------
+  {
+    name: 'explore',
+    description: 'Interactive TUI — browse lessons, gates, stats, and rules keyboard-first',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON (non-interactive)' },
+      { name: 'limit', type: 'number', description: 'Max items (default 20)' },
+    ],
+  },
+  {
+    name: 'lessons',
+    aliases: ['search-lessons'],
+    description: 'Search promoted lessons and show linked corrective actions',
+    group: 'discovery',
+    mcpTool: 'search_lessons',
+    flags: [
+      { name: 'query',    type: 'string',  description: 'Search query (positional arg also works)' },
+      { name: 'limit',    type: 'number',  description: 'Max results (default 10)' },
+      { name: 'tags',     type: 'string',  description: 'Comma-separated tag filter' },
+      { name: 'category', type: 'string',  description: 'error | learning | preference' },
+      { name: 'json',     type: 'boolean', description: 'Output as JSON' },
+      { name: 'local',    type: 'boolean', description: 'Use local storage (default)' },
+      { name: 'remote',   type: 'boolean', description: 'Fetch from hosted Railway instance' },
+    ],
+  },
+  {
+    name: 'stats',
+    description: 'Feedback analytics — approval rate, Revenue-at-Risk, recent trend',
+    group: 'discovery',
+    mcpTool: 'feedback_stats',
+    flags: [
+      { name: 'json',   type: 'boolean', description: 'Output as JSON' },
+      { name: 'remote', type: 'boolean', description: 'Fetch from hosted Railway instance' },
+    ],
+  },
+  {
+    name: 'gate-stats',
+    description: 'Gate engine statistics — active gates, blocks, warns, time saved',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'summary',
+    description: 'Human-readable feedback summary',
+    group: 'discovery',
+    mcpTool: 'feedback_summary',
+    flags: [
+      { name: 'recent', type: 'number', description: 'Number of recent entries (default 20)' },
+      { name: 'json',   type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'doctor',
+    description: 'Audit runtime isolation, bootstrap context, and permission tier',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'lesson-health',
+    aliases: ['stale'],
+    description: 'Report on stale lessons (>60d inactive) with optional auto-archive',
+    group: 'discovery',
+    flags: [
+      { name: 'archive', type: 'boolean', description: 'Auto-archive lessons >90d inactive' },
+      { name: 'json',    type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Gates
+  // -------------------------------------------------------------------------
+  {
+    name: 'gate-check',
+    description: 'PreToolUse hook: pipe tool JSON via stdin, get ALLOW/BLOCK verdict',
+    group: 'gates',
+    flags: [],
+  },
+  {
+    name: 'force-gate',
+    description: 'Immediately create a blocking gate from a pattern string',
+    group: 'gates',
+    flags: [
+      { name: 'pattern', type: 'string', description: 'Pattern to block (positional)' },
+    ],
+  },
+  {
+    name: 'rules',
+    description: 'Generate prevention rules from repeated failure patterns',
+    group: 'gates',
+    mcpTool: 'prevention_rules',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Export
+  // -------------------------------------------------------------------------
+  {
+    name: 'export-dpo',
+    aliases: ['dpo'],
+    description: 'Export DPO training pairs (prompt/chosen/rejected JSONL)',
+    group: 'export',
+    flags: [
+      { name: 'output', type: 'string', description: 'Output file path' },
+    ],
+  },
+  {
+    name: 'export-databricks',
+    aliases: ['databricks'],
+    description: 'Export feedback + proof artifacts as a Databricks-ready analytics bundle',
+    group: 'export',
+    flags: [],
+  },
+  {
+    name: 'obsidian-export',
+    description: 'Export all feedback as interlinked Obsidian markdown notes',
+    group: 'export',
+    flags: [
+      { name: 'vault-path',  type: 'string', description: 'Obsidian vault path' },
+      { name: 'output-dir',  type: 'string', description: 'Output subdirectory (default: AI-Memories/thumbgate)' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Ops
+  // -------------------------------------------------------------------------
+  {
+    name: 'status',
+    description: 'Agent-friendly health check — gates, lessons, feedback, enforcement',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'demo',
+    description: 'Simulated walkthrough — see ThumbGate block a bad action in 10 seconds',
+    group: 'ops',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'init',
+    description: 'Scaffold .thumbgate/ config and wire agent hooks',
+    group: 'ops',
+    flags: [
+      { name: 'agent',      type: 'string',  description: 'Target agent: claude-code | cursor | codex | gemini | amp' },
+      { name: 'wire-hooks', type: 'boolean', description: 'Wire hooks only (skip scaffold)' },
+      { name: 'json',       type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'serve',
+    description: 'Start MCP server on stdio — connect any MCP-compatible agent',
+    group: 'ops',
+    flags: [],
+  },
+  {
+    name: 'dashboard',
+    description: 'Full ThumbGate dashboard — approval rate, gate stats, prevention impact',
+    group: 'ops',
+    flags: [],
+  },
+  {
+    name: 'self-heal',
+    description: 'Run self-healing check and auto-fix known issues',
+    group: 'ops',
+    flags: [
+      { name: 'check', type: 'boolean', description: 'Check only, no fixes' },
+    ],
+  },
+  {
+    name: 'import-doc',
+    aliases: ['import-document'],
+    description: 'Import a local policy/runbook and propose reviewable gate candidates',
+    group: 'ops',
+    flags: [
+      { name: 'file', type: 'string', description: 'Path to document' },
+    ],
+  },
+  {
+    name: 'meta-agent',
+    description: 'Run meta-agent loop: generate, evaluate, and promote prevention rules',
+    group: 'advanced',
+    flags: [
+      { name: 'dry-run', type: 'boolean', description: 'Preview rules without writing' },
+      { name: 'status',  type: 'boolean', description: 'Show last run summary' },
+    ],
+  },
+  {
+    name: 'pro',
+    description: `Solo dashboard + exports side lane (${'19'}/mo · ${'149'}/yr)`,
+    group: 'ops',
+    flags: [
+      { name: 'upgrade', type: 'boolean', description: 'Install Pro configs into .thumbgate/' },
+      { name: 'info',    type: 'boolean', description: 'Show Pro feature list' },
+    ],
+  },
+];
+
+/**
+ * Return the command definition for a given name or alias.
+ */
+function findCommand(name) {
+  return CLI_COMMANDS.find(
+    (cmd) => cmd.name === name || (cmd.aliases || []).includes(name),
+  );
+}
+
+/**
+ * Return commands grouped by their group field.
+ */
+function groupedCommands() {
+  const groups = {};
+  for (const cmd of CLI_COMMANDS) {
+    const g = cmd.group || 'other';
+    if (!groups[g]) groups[g] = [];
+    groups[g].push(cmd);
+  }
+  return groups;
+}
+
+/**
+ * Generate a compact help string for a single command.
+ * Format:  name [aliases]   description   [--flag ...]
+ */
+function commandHelpLine(cmd, opts = {}) {
+  const { showFlags = false } = opts;
+  const nameCol = 22;
+  const nameStr = [cmd.name, ...(cmd.aliases || []).slice(0, 1)].join(' | ');
+  const pad = ' '.repeat(Math.max(1, nameCol - nameStr.length));
+  let line = `  ${nameStr}${pad}${cmd.description}`;
+  if (cmd.mcpTool) line += ` [mcp:${cmd.mcpTool}]`;
+  if (showFlags && cmd.flags.length > 0) {
+    const flagStr = cmd.flags
+      .map((f) => `--${f.name}${f.required ? ' (required)' : ''}`)
+      .join('  ');
+    line += `\n    ${flagStr}`;
+  }
+  return line;
+}
+
+module.exports = { CLI_COMMANDS, findCommand, groupedCommands, commandHelpLine };

package/scripts/cli-status.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * cli-status.js — agent-friendly health check for ThumbGate.
+ *
+ * Combines feedback stats, gate stats, lesson count, and agent detection
+ * into a single JSON-friendly payload.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function detectAgent(projectDir) {
+  if (fs.existsSync(path.join(projectDir, '.claude'))) return 'claude-code';
+  if (fs.existsSync(path.join(projectDir, '.cursorrules'))) return 'cursor';
+  if (fs.existsSync(path.join(projectDir, '.cursor'))) return 'cursor';
+  if (fs.existsSync(path.join(projectDir, '.codex'))) return 'codex';
+  if (fs.existsSync(path.join(projectDir, '.gemini'))) return 'gemini';
+  if (fs.existsSync(path.join(projectDir, '.amp'))) return 'amp';
+  return null;
+}
+
+function generateAgentStatus(options = {}) {
+  const PKG_ROOT = options.pkgRoot || path.join(__dirname, '..');
+  const projectDir = options.projectDir || process.cwd();
+
+  // Feedback paths
+  const { getFeedbackPaths, readJSONL, analyzeFeedback } = require(path.join(PKG_ROOT, 'scripts', 'feedback-loop'));
+  const paths = getFeedbackPaths();
+
+  // Feedback entries
+  const feedbackEntries = readJSONL(paths.FEEDBACK_LOG_PATH);
+  const memoryEntries = readJSONL(paths.MEMORY_LOG_PATH);
+
+  // Gate stats
+  let gateData = { totalGates: 0, autoPromotedGates: 0, manualGates: 0, totalBlocked: 0 };
+  try {
+    const { calculateStats } = require(path.join(PKG_ROOT, 'scripts', 'gate-stats'));
+    gateData = calculateStats();
+  } catch { /* gate-stats not available */ }
+
+  // Prevention rules count
+  let preventionRuleCount = 0;
+  if (fs.existsSync(paths.PREVENTION_RULES_PATH)) {
+    const rulesContent = fs.readFileSync(paths.PREVENTION_RULES_PATH, 'utf-8');
+    const ruleHeaders = rulesContent.match(/^## /gm);
+    preventionRuleCount = ruleHeaders ? ruleHeaders.length : 0;
+  }
+
+  // Last feedback timestamp
+  const lastFeedback = feedbackEntries.length > 0
+    ? feedbackEntries[feedbackEntries.length - 1]
+    : null;
+  const lastFeedbackTimestamp = lastFeedback
+    ? (lastFeedback.timestamp || lastFeedback.createdAt || null)
+    : null;
+
+  // Agent detection
+  const agent = detectAgent(projectDir);
+
+  // Enforcement check: is there at least one blocking gate?
+  const hasBlockingGates = gateData.totalGates > 0;
+  const hasPreToolHook = (() => {
+    try {
+      const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      return Boolean(
+        settings.hooks &&
+        settings.hooks.PreToolUse &&
+        settings.hooks.PreToolUse.length > 0
+      );
+    } catch { return false; }
+  })();
+  const enforcementActive = hasBlockingGates || hasPreToolHook;
+
+  // Config
+  const configPath = path.join(projectDir, '.thumbgate', 'config.json');
+  let config = null;
+  try {
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+  } catch { /* ignore */ }
+
+  // Version
+  let version = 'unknown';
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+  } catch { /* ignore */ }
+
+  return {
+    version,
+    agent,
+    enforcementActive,
+    gates: {
+      total: gateData.totalGates,
+      manual: gateData.manualGates,
+      autoPromoted: gateData.autoPromotedGates,
+      blocking: gateData.blockGates || 0,
+      warning: gateData.warnGates || 0,
+    },
+    lessons: memoryEntries.length,
+    feedback: {
+      total: feedbackEntries.length,
+      positive: feedbackEntries.filter(e => e.signal === 'positive').length,
+      negative: feedbackEntries.filter(e => e.signal === 'negative').length,
+    },
+    preventionRules: preventionRuleCount,
+    lastFeedbackTimestamp,
+    feedbackDir: paths.FEEDBACK_DIR,
+    initialized: Boolean(config),
+  };
+}
+
+function formatStatus(data) {
+  const BD = '\x1b[1m';
+  const RST = '\x1b[0m';
+  const G = '\x1b[32m';
+  const R = '\x1b[31m';
+  const C = '\x1b[36m';
+  const Y = '\x1b[33m';
+  const D = '\x1b[90m';
+
+  const lines = [];
+  lines.push('');
+  lines.push(`${BD}thumbgate status${RST}  v${data.version}`);
+  lines.push('─'.repeat(50));
+
+  // Scope badge
+  const scope = '[LOCAL]';
+  lines.push(`  ${C}${scope}${RST} ${data.feedbackDir}`);
+  lines.push('');
+
+  // Core metrics
+  const enfBadge = data.enforcementActive
+    ? `${G}[ACTIVE]${RST}`
+    : `${Y}[LEARNING]${RST}`;
+  lines.push(`  Enforcement     : ${enfBadge}`);
+  lines.push(`  Agent           : ${data.agent || 'none detected'}`);
+  lines.push(`  Gates           : ${data.gates.total} (${data.gates.blocking} block, ${data.gates.warning} warn)`);
+  lines.push(`  Lessons         : ${data.lessons}`);
+  lines.push(`  Prevention Rules: ${data.preventionRules}`);
+  lines.push('');
+  lines.push(`  Feedback        : ${data.feedback.total} total (${G}${data.feedback.positive} up${RST}, ${R}${data.feedback.negative} down${RST})`);
+  if (data.lastFeedbackTimestamp) {
+    const ago = relativeTime(data.lastFeedbackTimestamp);
+    lines.push(`  Last Feedback   : ${ago} ${D}(${data.lastFeedbackTimestamp})${RST}`);
+  } else {
+    lines.push(`  Last Feedback   : ${D}none${RST}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function relativeTime(ts) {
+  if (!ts) return '';
+  const d = Math.floor((Date.now() - new Date(ts).getTime()) / 86400000);
+  if (d === 0) return 'today';
+  if (d === 1) return '1 day ago';
+  return `${d} days ago`;
+}
+
+module.exports = { generateAgentStatus, formatStatus };

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, callClaude, 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 raw = await callClaude({
+      systemPrompt: 'You are a relevance scoring engine. Return only JSON arrays of numbers.',
+      userPrompt: prompt,
+      model: MODELS.FAST,
+      maxTokens: 256,
+    });
+    const scores = JSON.parse(raw);
+    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,
+};