thumbgate 1.28.1 → 1.28.3

package/scripts/feedback-loop.js

@@ -57,11 +57,15 @@ const {
 }));
 
 const AUDIT_TRAIL_TAG = 'audit-trail';
-const FEEDBACK_EVENT_DEDUPE_WINDOW_MS = 30 * 1000;
+const FEEDBACK_EVENT_DEDUPE_WINDOW_MS = 5 * 60 * 1000;
 const FEEDBACK_EVENT_CLAIM_STALE_MS = 60 * 1000;
 const FEEDBACK_EVENT_CLAIM_WAIT_MS = 15 * 1000;
 const FEEDBACK_EVENT_CLAIM_POLL_MS = 25;
 
+function isSelfHarnessOptimizerEnabled(env = process.env) {
+  return /^(?:1|true)$/i.test(String(env.THUMBGATE_SELF_HARNESS_OPTIMIZER || '').trim());
+}
+
 /**
  * Anonymous fire-and-forget CLI feedback telemetry.
  *
@@ -666,8 +670,11 @@ function parseFeedbackSourceTimestamp(value) {
  */
 function buildFeedbackSourceIdentity(input = {}) {
   const signal = normalizeSignal(input.signal);
-  const normalizedText = normalizeFeedbackText(input.promptText || input.context);
-  if (!signal || !normalizedText) return null;
+  if (!signal) return null;
+  // Emoji-only prompts normalize to no alphanumeric text. Preserve a stable,
+  // non-sensitive canonical value so duplicate 👍/👎 hook deliveries still
+  // share one source identity and cannot create duplicate feedback rows.
+  const normalizedText = normalizeFeedbackText(input.promptText || input.context) || `thumbs-${signal}`;
 
   const sessionHash = hashFeedbackSourcePart(input.sessionId);
   const promptIdHash = hashFeedbackSourcePart(input.promptId);
@@ -696,10 +703,10 @@ function buildFeedbackSourceIdentity(input = {}) {
 function normalizeFeedbackSourceIdentity(identity, params = {}) {
   if (!identity || typeof identity !== 'object' || typeof identity.key !== 'string') return null;
   const signal = normalizeSignal(params.signal || identity.signal);
+  if (!signal) return null;
   const normalizedText = normalizeFeedbackText(
     identity.normalizedText || params.context || params.whatWentWrong || params.whatWorked,
-  );
-  if (!signal || !normalizedText) return null;
+  ) || `thumbs-${signal}`;
 
   return {
     key: `fev_${hashFeedbackSourcePart(identity.key)}`,
@@ -781,6 +788,9 @@ function duplicateCaptureResult(receipt, paths, options = {}) {
   const memoryRecord = findRecordById(paths.MEMORY_LOG_PATH, receipt?.memoryId);
   return {
     accepted: Boolean(receipt?.accepted),
+    captured: Boolean(receipt?.signalLogged),
+    promoted: Boolean(receipt?.promoted),
+    promotionAccepted: Boolean(receipt?.promoted),
     signalLogged: Boolean(receipt?.signalLogged),
     duplicate: true,
     pending: Boolean(options.pending),
@@ -820,7 +830,8 @@ function receiptFromFeedbackEntry(entry, paths) {
     status: 'complete',
     feedbackId: entry.id,
     memoryId: memory?.id,
-    accepted: entry.actionType !== 'no-action'
+    accepted: !Array.isArray(entry.validationIssues) || entry.validationIssues.length === 0,
+    promoted: entry.actionType !== 'no-action'
       && (!Array.isArray(entry.validationIssues) || entry.validationIssues.length === 0),
     signalLogged: true,
     completedAtMs: Date.parse(entry.timestamp || '') || Date.now(),
@@ -888,6 +899,7 @@ function finalizeFeedbackEventClaim(claim, result) {
     startedAtMs: Date.now(),
     completedAtMs: Date.now(),
     accepted: Boolean(result?.accepted),
+    promoted: Boolean(result?.promoted || result?.memoryRecord),
     signalLogged: Boolean(result?.signalLogged || result?.feedbackEvent),
     feedbackId: result?.feedbackEvent?.id || null,
     memoryId: result?.memoryRecord?.id || null,
@@ -1481,12 +1493,15 @@ function captureFeedback(params) {
       trainAndPersistInterventionPolicy(FEEDBACK_DIR);
     } catch { /* non-critical */ }
     updateStatuslineWithLesson({
-      accepted: false,
+      accepted: true,
       signal,
       feedbackId: feedbackEvent.id,
     });
     return {
-      accepted: false,
+      accepted: true,
+      captured: true,
+      promoted: false,
+      promotionAccepted: false,
       signalLogged: true,
       status: clarification ? 'clarification_required' : 'rejected',
       reason: action.reason,
@@ -1692,6 +1707,9 @@ function captureFeedback(params) {
   // Build result immediately — all remaining side-effects are deferred
   const result = {
     accepted: true,
+    captured: true,
+    promoted: true,
+    promotionAccepted: true,
     status: 'promoted',
     message: 'Feedback promoted to reusable memory.',
     feedbackEvent,
@@ -1770,19 +1788,23 @@ function captureFeedback(params) {
           });
         } catch { /* activation telemetry is non-critical */ }
 
-        // Trigger Self-Harness Optimizer to propagate the new rules to prompt files & validate
-        try {
-          const { fork } = require('child_process');
-          const localOptimizerPath = path.join(process.cwd(), 'scripts', 'self-harness-optimizer.js');
-          const packageOptimizerPath = path.join(__dirname, 'self-harness-optimizer.js');
-          
-          if (fs.existsSync(localOptimizerPath)) {
-            fork(localOptimizerPath, [], { stdio: 'ignore', detached: true }).unref();
-          } else if (fs.existsSync(packageOptimizerPath)) {
-            fork(packageOptimizerPath, [], { stdio: 'ignore', detached: true }).unref();
+        // Prompt-file mutation and git commits are explicit opt-in side effects.
+        // Feedback capture must never detach an unrequested process that edits
+        // AGENTS.md/GEMINI.md merely because a negative rule was promoted.
+        if (isSelfHarnessOptimizerEnabled()) {
+          try {
+            const { fork } = require('child_process');
+            const localOptimizerPath = path.join(process.cwd(), 'scripts', 'self-harness-optimizer.js');
+            const packageOptimizerPath = path.join(__dirname, 'self-harness-optimizer.js');
+
+            if (fs.existsSync(localOptimizerPath)) {
+              fork(localOptimizerPath, [], { stdio: 'ignore', detached: true }).unref();
+            } else if (fs.existsSync(packageOptimizerPath)) {
+              fork(packageOptimizerPath, [], { stdio: 'ignore', detached: true }).unref();
+            }
+          } catch (err) {
+            console.error('Failed to trigger self-harness optimizer:', err);
           }
-        } catch (err) {
-          console.error('Failed to trigger self-harness optimizer:', err);
         }
       }
     } catch { /* Gate promotion is non-critical */ }
@@ -2416,10 +2438,10 @@ function runTests() {
       budgetCompliant: true,
     }),
   });
-  assert(!blocked.accepted, 'captureFeedback blocks unsafe positive promotion via rubric gate');
+  assert(blocked.accepted && blocked.promoted === false, 'captureFeedback stores but does not promote unsafe positive feedback');
 
   const bad = captureFeedback({ signal: 'down' });
-  assert(!bad.accepted, 'captureFeedback rejects vague negative feedback');
+  assert(bad.accepted && bad.promoted === false, 'captureFeedback stores vague negative feedback without promotion');
   assert(bad.needsClarification === true, 'captureFeedback requests clarification for vague negative feedback');
 
   const summary = feedbackSummary(5);
@@ -2508,6 +2530,7 @@ module.exports = {
   updateStatuslineWithLesson,
   waitForBackgroundSideEffects,
   getPendingBackgroundSideEffectCount,
+  isSelfHarnessOptimizerEnabled,
   getFeedbackPaths,
   get FEEDBACK_LOG_PATH() {
     return getFeedbackPaths().FEEDBACK_LOG_PATH;

package/scripts/gates-engine.js

@@ -2003,7 +2003,12 @@ function evaluateMemoryGuard(toolName, toolInput = {}) {
   } else {
     guard = hybrid.evaluatePretool(toolName, serializedInput);
   }
-  if (!guard || guard.mode === 'allow') {
+  if (!guard || guard.mode !== 'block') {
+    return null;
+  }
+  const guardReason = String(guard.reason || '');
+  const contextualMatch = /^(?:Matched guard pattern|Recurring negative pattern)\b/i.test(guardReason);
+  if (!contextualMatch) {
     return null;
   }
 

package/scripts/lesson-embedding-index.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Lesson Embedding Index — maintained dense index over the lesson corpus.
+ *
+ * Powers the dense half of hybrid retrieval in the per-action gating hot path.
+ * The gating path reads memory-log lessons and must surface past mistakes that
+ * are semantically related to the current action even when they share no
+ * keywords (paraphrase, synonym, different file path). Pure lexical scoring
+ * misses those; dense embeddings catch them.
+ *
+ * Design constraints:
+ *   - Embedding the whole corpus on every tool call is too expensive. We cache
+ *     document vectors keyed by `id + sha1(text)` in <feedbackDir>/lesson-embeddings.json.
+ *     Only the query is embedded per call; only new/changed lessons re-embed.
+ *   - The embedder is reused from vector-store.embed (Gemini -> local transformers
+ *     -> stub). No new embedding dependency.
+ *   - HONESTY: when no real embedder is available, callers must degrade to lexical.
+ *     We never synthesize fake (e.g. hash-based) vectors — that would be overclaiming.
+ *
+ * Zero hard dependency on LanceDB: this module only needs the embed() function.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const CACHE_FILE = 'lesson-embeddings.json';
+
+function resolveFeedbackDir(explicit) {
+  if (explicit) return explicit;
+  try {
+    const { resolveFeedbackDir: resolve } = require('./feedback-paths');
+    return resolve();
+  } catch {
+    return process.env.THUMBGATE_FEEDBACK_DIR || process.cwd();
+  }
+}
+
+function getCachePath(feedbackDir) {
+  return path.join(resolveFeedbackDir(feedbackDir), CACHE_FILE);
+}
+
+/** Canonical text for a lesson record (title + content + tags). */
+function lessonText(lesson) {
+  if (!lesson) return '';
+  return [
+    lesson.title || '',
+    lesson.content || '',
+    Array.isArray(lesson.tags) ? lesson.tags.join(' ') : '',
+  ].filter(Boolean).join(' ').trim();
+}
+
+/**
+ * Truncate a vector to a specific dimension (Matryoshka Embedding Truncation).
+ * Assumes the model supports MRL (like text-embedding-3 or modern transformers).
+ */
+function truncateVector(vector, dimension) {
+  if (!Array.isArray(vector) || !dimension || vector.length <= dimension) {
+    return vector;
+  }
+  return vector.slice(0, dimension);
+}
+
+function hashText(text) {
+  // Content-change key for the embedding cache (not a security context). sha256
+  // matches the repo's standard non-security hashing and avoids the weak-hash flag.
+  return crypto.createHash('sha256').update(String(text || '')).digest('hex');
+}
+
+function cosineSimilarity(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length) {
+    return 0;
+  }
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = Number(a[i]) || 0;
+    const y = Number(b[i]) || 0;
+    dot += x * y;
+    normA += x * x;
+    normB += y * y;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+/**
+ * Is a real embedder available? Used so callers can decide hybrid vs lexical-only
+ * WITHOUT loading a model. Returns true for the deterministic stub (test/CI safe).
+ */
+function isEmbedderAvailable() {
+  if (process.env.THUMBGATE_VECTOR_STUB_EMBED === 'true') return true;
+  // Managed Gemini path
+  try {
+    const { resolveGeminiEmbeddingConfig } = require('./gemini-embedding-policy');
+    const cfg = resolveGeminiEmbeddingConfig();
+    if (cfg && cfg.enabled && cfg.apiKey) return true;
+  } catch { /* policy module unavailable */ }
+  // Local transformers path
+  try {
+    require.resolve('@huggingface/transformers');
+    return true;
+  } catch { /* not installed */ }
+  return false;
+}
+
+function defaultEmbedder() {
+  // Lazy: do not pull in LanceDB/transformers at module require time.
+  const { embed } = require('./vector-store');
+  return embed;
+}
+
+function readCache(cachePath) {
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeCache(cachePath, cache) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify(cache));
+  } catch {
+    /* cache is best-effort; never throw into the hot path */
+  }
+}
+
+/**
+ * Rank lessons by dense (embedding) similarity to the query.
+ * Returns [{ id, score }] sorted descending. Embeds the query once; reuses cached
+ * document vectors and only embeds new/changed lessons.
+ *
+ * @returns {Promise<Array<{id:string, score:number}>>}
+ */
+async function semanticRank(queryText, lessons = [], options = {}) {
+  const { feedbackDir, embedder = defaultEmbedder(), persist = true, truncateDimension = null } = options;
+  if (!queryText || !Array.isArray(lessons) || lessons.length === 0) return [];
+
+  const cachePath = getCachePath(feedbackDir);
+  const cache = readCache(cachePath);
+  let cacheDirty = false;
+
+  let queryVector = await embedder(queryText, { kind: 'query', task: 'code retrieval' });
+  if (!Array.isArray(queryVector) || queryVector.length === 0) return [];
+  
+  if (truncateDimension) {
+    queryVector = truncateVector(queryVector, truncateDimension);
+  }
+
+  const scored = [];
+  for (const lesson of lessons) {
+    if (!lesson || !lesson.id) continue;
+    const text = lessonText(lesson);
+    if (!text) continue;
+    const hash = hashText(text);
+
+    let entry = cache[lesson.id];
+    if (!entry || entry.hash !== hash || !Array.isArray(entry.vector)) {
+      const vector = await embedder(text, {
+        kind: 'document',
+        task: 'code retrieval',
+        title: lesson.title || undefined,
+      });
+      if (!Array.isArray(vector) || vector.length === 0) continue;
+      entry = { hash, vector };
+      cache[lesson.id] = entry;
+      cacheDirty = true;
+    }
+
+    const docVector = truncateDimension ? truncateVector(entry.vector, truncateDimension) : entry.vector;
+    scored.push({ id: lesson.id, score: cosineSimilarity(queryVector, docVector) });
+  }
+
+  // Prune cache entries for lessons no longer present (bounded growth).
+  const liveIds = new Set(lessons.map((l) => l && l.id).filter(Boolean));
+  for (const id of Object.keys(cache)) {
+    if (!liveIds.has(id)) {
+      delete cache[id];
+      cacheDirty = true;
+    }
+  }
+
+  if (persist && cacheDirty) writeCache(cachePath, cache);
+
+  return scored.sort((a, b) => b.score - a.score);
+}
+
+module.exports = {
+  semanticRank,
+  isEmbedderAvailable,
+  cosineSimilarity,
+  truncateVector,
+  lessonText,
+  hashText,
+  getCachePath,
+};

package/scripts/lesson-reranker.js

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * Cross-encoder reranker for lesson retrieval.
+ *
+ * Unlike the bi-encoders already in use (Jaccard + bigram Jaccard), a
+ * cross-encoder processes the (query, lesson) pair jointly — so it can
+ * catch relevance signals that independent scoring misses:
+ *
+ *   - Field-weighted BM25: a query term in `whatWentWrong` is worth more
+ *     than the same term in `tags`
+ *   - Synonym/alias expansion: "force-push" ↔ "push --force", "deploy" ↔
+ *     "deployment", etc.
+ *   - Signal coherence: failure-sounding queries boost negative-signal lessons
+ *   - Tool name joint scoring: query toolName × lesson toolsUsed
+ *   - Score blending: reranked score is blended with the original retrieval
+ *     score so we never fully discard the bi-encoder's signal
+ *
+ * Usage:
+ *   const { rerankLessons } = require('./lesson-reranker');
+ *   const reranked = rerankLessons(query, candidates, { topK: 5, toolName });
+ */
+
+// BM25 hyper-parameters
+const BM25_K1 = 1.5;   // term saturation
+const BM25_B  = 0.75;  // length normalisation
+
+// Weight given to each lesson field when scoring a (query, lesson) pair.
+// Higher weight = query terms appearing in that field contribute more to score.
+const FIELD_WEIGHTS = {
+  whatWentWrong:  3.0,
+  whatToChange:   2.5,
+  howToAvoid:     2.0,
+  whatWorked:     2.0,
+  summary:        1.5,
+  content:        1.5,
+  context:        1.2,
+  title:          1.0,
+  rootCause:      1.0,
+  reasoning:      0.8,
+  tags:           0.5,
+  category:       0.4,
+};
+
+// Synonym clusters: any term in a group matches all others.
+const SYNONYM_GROUPS = [
+  ['force-push', 'force push', 'push --force', 'git push --force', 'force_push'],
+  ['main', 'main branch', 'master', 'trunk', 'protected branch'],
+  ['env', '.env', 'environment variable', 'env var', 'dotenv', 'secret'],
+  ['deploy', 'deployment', 'ship', 'release', 'publish', 'rollout'],
+  ['db', 'database', 'sqlite', 'postgres', 'postgresql', 'migration', 'migrate'],
+  ['test', 'tests', 'test suite', 'spec', 'failing test', 'test failure'],
+  ['ci', 'ci/cd', 'pipeline', 'github actions', 'workflow', 'build'],
+  ['lint', 'linter', 'eslint', 'prettier', 'format'],
+  ['auth', 'authentication', 'authorization', 'token', 'api key', 'credential'],
+  ['delete', 'remove', 'rm', 'drop', 'destroy', 'wipe'],
+  ['merge', 'pull request', 'pr', 'rebase', 'squash'],
+];
+
+// Regex patterns that indicate the query is about a failure/mistake.
+const FAILURE_PATTERN = /fail|error|wrong|broken|mistake|bad|incorrect|problem|issue|bug|crash|broke|exception/i;
+
+/**
+ * Tokenise text into lowercase word-like tokens of length >= 2.
+ * Hyphens and underscores are treated as delimiters so "force-push"
+ * becomes ["force", "push"].
+ * Exported so tests can verify expansion behaviour.
+ */
+function tokenize(text) {
+  if (!text) return [];
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')   // replace all non-word, non-space chars (incl. hyphens, dots) with space
+    .split(/[\s_]+/)             // split on whitespace and underscores
+    .filter((t) => t.length >= 2);
+}
+
+/**
+ * Expand a set of query tokens with synonyms from SYNONYM_GROUPS.
+ * Returns a deduplicated array of all terms (originals + expansions).
+ */
+function expandTerms(terms) {
+  const expanded = new Set(terms);
+  for (const term of terms) {
+    for (const group of SYNONYM_GROUPS) {
+      if (group.some((syn) => syn.split(/\s+/).some((w) => w === term || term.includes(w)))) {
+        group.forEach((syn) => tokenize(syn).forEach((t) => expanded.add(t)));
+      }
+    }
+  }
+  return [...expanded];
+}
+
+/**
+ * Extract the text value of a named field from a lesson candidate.
+ * Handles both the flat structure from lesson-retrieval.js and the nested
+ * { lesson: { whatWentWrong, ... } } structure from lesson-search.js.
+ */
+function getField(candidate, field) {
+  const nested = candidate.lesson;
+  const val = (nested && nested[field]) || candidate[field] || '';
+  if (Array.isArray(val)) return val.join(' ');
+  return String(val);
+}
+
+/**
+ * Compute field-weighted BM25 scores for a list of candidates (BM25F variant).
+ *
+ * BM25F processes the (query, lesson) pair jointly: query terms are weighted
+ * differently depending on which lesson field they appear in (via FIELD_WEIGHTS).
+ * IDF is computed at document level (how many docs contain the term across any
+ * field) so it stays positive regardless of field weights.
+ *
+ * Returns an array of { candidate, bm25Score } objects in the same order
+ * as the input.
+ */
+function fieldWeightedBM25(queryTerms, candidates) {
+  const N = candidates.length;
+  if (N === 0) return [];
+
+  const fieldEntries = Object.entries(FIELD_WEIGHTS);
+  const fieldKeys = Object.keys(FIELD_WEIGHTS);
+
+  // Precompute per-document, per-field token arrays (avoid re-tokenising)
+  const docFieldTokens = candidates.map((candidate) => {
+    const fieldMap = {};
+    for (const field of fieldKeys) {
+      fieldMap[field] = tokenize(getField(candidate, field));
+    }
+    return fieldMap;
+  });
+
+  // Per-field average token lengths across all documents
+  const avgFieldLen = {};
+  for (const field of fieldKeys) {
+    const total = docFieldTokens.reduce((sum, d) => sum + d[field].length, 0);
+    avgFieldLen[field] = total / N || 1;   // fallback to 1 to avoid /0
+  }
+
+  // Document-level df: count of documents that contain each term (any field).
+  // Keeping df as a plain count (not field-weighted) ensures IDF is always positive.
+  const df = new Map();
+  for (let i = 0; i < N; i++) {
+    const seenInDoc = new Set();
+    for (const field of fieldKeys) {
+      for (const tok of docFieldTokens[i][field]) {
+        if (!seenInDoc.has(tok)) {
+          df.set(tok, (df.get(tok) || 0) + 1);
+          seenInDoc.add(tok);
+        }
+      }
+    }
+  }
+
+  return candidates.map((candidate, i) => {
+    let score = 0;
+
+    for (const qTerm of queryTerms) {
+      const termDf = df.get(qTerm) || 0;
+      if (termDf === 0) continue;
+
+      // IDF is always positive because df ≤ N
+      const idf = Math.log((N - termDf + 0.5) / (termDf + 0.5) + 1);
+      if (idf <= 0) continue;
+
+      // BM25F: compute weighted sum of per-field normalised TF, then scale by IDF
+      let weightedTF = 0;
+      for (const [field, fieldWeight] of fieldEntries) {
+        const tokens = docFieldTokens[i][field];
+        const fieldLen = tokens.length;
+        if (fieldLen === 0) continue;
+
+        let tf = 0;
+        for (const t of tokens) {
+          if (t === qTerm) tf++;
+        }
+        if (tf === 0) continue;
+
+        const avgLen = avgFieldLen[field];
+        const normTF = tf / (tf + BM25_K1 * (1 - BM25_B + BM25_B * fieldLen / avgLen));
+        weightedTF += fieldWeight * normTF;
+      }
+
+      score += idf * weightedTF;
+    }
+
+    return { candidate, bm25Score: score };
+  });
+}
+
+/**
+ * Rerank a list of lesson candidates using a cross-encoder approach.
+ *
+ * @param {string} query          - The original retrieval query / action context
+ * @param {Array}  candidates     - Lesson objects from the bi-encoder stage
+ * @param {object} options
+ * @param {number} [options.topK=5]         - How many results to return
+ * @param {string} [options.toolName]       - Tool name from the triggering hook call
+ * @param {number} [options.blendWeight=0.7] - Weight given to BM25 score vs original
+ *                                            retrieval score (0 = all original, 1 = all BM25)
+ * @returns {Array} Reranked candidates with `rerankedScore` field added
+ */
+function rerankLessons(query, candidates, options = {}) {
+  const {
+    topK        = 5,
+    toolName    = '',
+    blendWeight = 0.7,
+  } = options;
+
+  if (!candidates || candidates.length === 0) return [];
+  if (candidates.length === 1) return candidates.slice(0, topK);
+
+  // Build expanded query term set
+  const rawTerms = tokenize((query || '') + (toolName ? ' ' + toolName : ''));
+  const queryTerms = expandTerms(rawTerms);
+
+  const isFailureQuery = FAILURE_PATTERN.test(query || '');
+
+  // Compute BM25 scores for all candidates
+  const bm25Results = fieldWeightedBM25(queryTerms, candidates);
+
+  // Normalise BM25 scores to [0, 1]
+  const maxBm25 = Math.max(...bm25Results.map((r) => r.bm25Score), 1e-9);
+
+  const reranked = bm25Results.map(({ candidate, bm25Score }) => {
+    const normBm25 = bm25Score / maxBm25;
+
+    // Original bi-encoder score (field name differs between retrieval paths)
+    const origScore = candidate.relevanceScore ?? candidate.score ?? 0;
+
+    // Blend BM25 with original score
+    let finalScore = blendWeight * normBm25 + (1 - blendWeight) * origScore;
+
+    // Signal coherence bonus: failure queries → negative lessons rank higher
+    const candidateSignal =
+      candidate.signal ||
+      (candidate.tags && candidate.tags.includes('negative') ? 'negative' : null);
+    if (isFailureQuery && candidateSignal === 'negative') {
+      finalScore *= 1.2;
+    }
+
+    // Tool name joint bonus: exact tool match between query context and lesson
+    if (toolName) {
+      const lessonTools = [
+        ...(candidate.metadata?.toolsUsed || []),
+        getField(candidate, 'toolUsed'),
+        getField(candidate, 'toolName'),
+      ].map((t) => (t || '').toLowerCase());
+
+      if (lessonTools.some((t) => t && t.includes(toolName.toLowerCase()))) {
+        finalScore *= 1.3;
+      }
+    }
+
+    return { ...candidate, rerankedScore: Number(finalScore.toFixed(6)) };
+  });
+
+  return reranked
+    .sort((a, b) => b.rerankedScore - a.rerankedScore)
+    .slice(0, topK);
+}
+
+module.exports = { rerankLessons, fieldWeightedBM25, tokenize, expandTerms };