@cachly-dev/mcp-server 0.10.49 → 0.10.51

package/src/bench/fixtures.ts

@@ -0,0 +1,226 @@
+/**
+ * Cachly-Bench fixture corpus.
+ *
+ * A small but realistic corpus of engineering "lessons" plus a set of labeled
+ * natural-language queries. Each query declares which lesson topics are *truly*
+ * relevant — the answer an agent actually wants.
+ *
+ * The corpus is deliberately adversarial in a fair way: for several queries there
+ * is a text-similar but LOW-QUALITY distractor (a failed attempt, an unverified
+ * note) competing with the proven success lesson. This is exactly the situation
+ * where raw text ranking (and a flat-file memory) goes wrong, and where Cachly's
+ * quality-aware reranking should win. The labels reward the lesson that solves the
+ * problem, not the one that merely shares vocabulary.
+ */
+
+export interface BenchLesson {
+  /** Stored under cachly:lesson:best:{topic} */
+  topic: string;
+  outcome: 'success' | 'partial' | 'failure';
+  what_worked: string;
+  what_failed?: string;
+  context?: string;
+  severity?: 'critical' | 'major' | 'minor';
+  confidence?: number;
+  recall_count?: number;
+  tags?: string[];
+  ts?: string;
+}
+
+export interface BenchQuery {
+  query: string;
+  /** Topics that genuinely answer the query (the gold set). */
+  relevant: string[];
+}
+
+const NOW = Date.now();
+const daysAgo = (d: number) => new Date(NOW - d * 86400_000).toISOString();
+
+export const BENCH_LESSONS: BenchLesson[] = [
+  // ── Deploy domain ──────────────────────────────────────────────────────────
+  {
+    topic: 'deploy:k8s:rollout-stuck',
+    outcome: 'success',
+    what_worked: 'Set a readinessProbe with a longer initialDelaySeconds and a higher failureThreshold so the liveness probe stopped terminating the container before startup completed. The pod then reached ready and traffic flowed.',
+    context: 'Production release never became healthy.',
+    severity: 'critical', confidence: 0.95, recall_count: 12,
+    tags: ['kubernetes', 'deploy', 'probe'], ts: daysAgo(8),
+  },
+  {
+    topic: 'deploy:k8s:rollout-attempt-restart',
+    outcome: 'failure',
+    what_worked: '',
+    what_failed: 'The kubernetes deploy was stuck, the rollout was not finishing, so I restarted the deploy. The kubernetes deploy stayed stuck and the rollout still was not finishing. Restarted the stuck rollout again, deploy still stuck.',
+    context: 'Kubernetes deploy stuck, rollout not finishing.',
+    severity: 'major', confidence: 0.3, recall_count: 0,
+    tags: ['kubernetes', 'deploy'], ts: daysAgo(9),
+  },
+  {
+    topic: 'deploy:docker:image-too-large',
+    outcome: 'success',
+    what_worked: 'Reduced Docker image size dramatically with a multi-stage build and a slim base image, moving build-only deps out of the final layer.',
+    context: 'CI pushes were slow due to a 1.8GB image.',
+    severity: 'minor', confidence: 0.9, recall_count: 6,
+    tags: ['docker', 'deploy', 'optimization'], ts: daysAgo(20),
+  },
+
+  // ── Database domain ────────────────────────────────────────────────────────
+  {
+    topic: 'db:postgres:connection-pool-exhausted',
+    outcome: 'success',
+    what_worked: 'Added PgBouncer in transaction pooling mode and lowered the per-service max pool size so backends were shared. Peak traffic stopped exhausting backends.',
+    context: 'API returned 500s at peak traffic.',
+    severity: 'critical', confidence: 0.92, recall_count: 9,
+    tags: ['postgres', 'database', 'pool'], ts: daysAgo(15),
+  },
+  {
+    topic: 'db:postgres:slow-query-missing-index',
+    outcome: 'success',
+    what_worked: 'A slow Postgres query was fixed by adding a composite index on (tenant_id, created_at); query dropped from 4s to 12ms.',
+    context: 'Dashboard timed out loading recent events.',
+    severity: 'major', confidence: 0.88, recall_count: 4,
+    tags: ['postgres', 'database', 'index', 'performance'], ts: daysAgo(30),
+  },
+  {
+    topic: 'db:postgres:pool-raise-limit-attempt',
+    outcome: 'failure',
+    what_worked: '',
+    what_failed: 'Postgres had too many connections under load, so I raised max_connections. Postgres still had too many connections under load and the load made it worse — too many connections again under load.',
+    context: 'Postgres too many connections under load.',
+    severity: 'major', confidence: 0.25, recall_count: 0,
+    tags: ['postgres', 'database', 'pool'], ts: daysAgo(16),
+  },
+
+  // ── Auth domain ────────────────────────────────────────────────────────────
+  {
+    topic: 'auth:jwt:expired-on-restart',
+    outcome: 'success',
+    what_worked: 'JWT was lost on server restart because it was only kept in memory; persisting the token to disk after the device flow fixed recall counts staying at zero.',
+    context: 'Telemetry showed zero authenticated calls after restarts.',
+    severity: 'critical', confidence: 0.93, recall_count: 7,
+    tags: ['jwt', 'auth', 'persistence'], ts: daysAgo(3),
+  },
+  {
+    topic: 'auth:pkce:keycloak-rejects-exchange',
+    outcome: 'success',
+    what_worked: 'Keycloak rejected the PKCE code exchange because the verifier used non-URL-safe Base64; switching to RFC 7636 Base64URL random bytes fixed the login.',
+    context: 'Mobile login failed at the token exchange step.',
+    severity: 'major', confidence: 0.9, recall_count: 3,
+    tags: ['pkce', 'auth', 'keycloak', 'oauth'], ts: daysAgo(2),
+  },
+
+  // ── Redis / cache domain ───────────────────────────────────────────────────
+  {
+    topic: 'redis:noauth-on-every-call',
+    outcome: 'success',
+    what_worked: 'The connection endpoint omitted the password field, so the client connected unauthenticated; returning the credential explicitly in the response let the client authenticate and the calls succeeded.',
+    context: 'Hosted Valkey requires a credential.',
+    severity: 'critical', confidence: 0.94, recall_count: 11,
+    tags: ['redis', 'valkey', 'auth'], ts: daysAgo(4),
+  },
+  {
+    topic: 'redis:noauth-disable-auth-attempt',
+    outcome: 'failure',
+    what_worked: '',
+    what_failed: 'Redis threw NOAUTH on every call, so I tried disabling auth on Redis. Redis still threw NOAUTH on every call. Tried again to stop the NOAUTH error on every Redis call — no luck.',
+    context: 'Redis NOAUTH error on every call.',
+    severity: 'major', confidence: 0.2, recall_count: 0,
+    tags: ['redis', 'auth'], ts: daysAgo(5),
+  },
+  {
+    topic: 'redis:keys-no-ttl-memory-leak',
+    outcome: 'success',
+    what_worked: 'Redis memory grew unbounded because dependency-index and history keys had no TTL; adding a 90-day expire and an ltrim bounded the memory.',
+    context: 'Instance memory crept up over weeks of use.',
+    severity: 'major', confidence: 0.85, recall_count: 2,
+    tags: ['redis', 'ttl', 'memory'], ts: daysAgo(1),
+  },
+
+  // ── CI / build domain ──────────────────────────────────────────────────────
+  {
+    topic: 'ci:npm-ci-lockfile-mismatch',
+    outcome: 'success',
+    what_worked: 'CI "npm ci" failed because a dependency was added to package.json but the lockfile was never regenerated; running npm install to update package-lock.json fixed the build.',
+    context: 'GitHub Actions install step failed after adding a dep.',
+    severity: 'major', confidence: 0.91, recall_count: 5,
+    tags: ['ci', 'npm', 'lockfile'], ts: daysAgo(0),
+  },
+  {
+    topic: 'ci:golangci-lint-errcheck',
+    outcome: 'success',
+    what_worked: 'golangci-lint failed on an unchecked recover() return value; assigning it to _ satisfied errcheck.',
+    context: 'Go lint job blocked the deploy pipeline.',
+    severity: 'minor', confidence: 0.8, recall_count: 1,
+    tags: ['ci', 'go', 'lint'], ts: daysAgo(1),
+  },
+
+  // ── Frontend domain ────────────────────────────────────────────────────────
+  {
+    topic: 'frontend:cors-preflight-blocked',
+    outcome: 'success',
+    what_worked: 'Dashboard mutations failed because the CORS middleware did not allow PUT/PATCH; adding them to AllowMethods fixed the preflight.',
+    context: 'BYOK and webhook settings could not be saved from the browser.',
+    severity: 'major', confidence: 0.87, recall_count: 4,
+    tags: ['cors', 'frontend', 'api'], ts: daysAgo(6),
+  },
+  {
+    topic: 'frontend:hydration-mismatch',
+    outcome: 'partial',
+    what_worked: 'A Next.js hydration mismatch was reduced by guarding a date render with a client-only effect, though the root cause (locale formatting) still needs work.',
+    context: 'Console hydration warnings on the landing page.',
+    severity: 'minor', confidence: 0.6, recall_count: 1,
+    tags: ['nextjs', 'frontend', 'hydration'], ts: daysAgo(25),
+  },
+];
+
+export const BENCH_QUERIES: BenchQuery[] = [
+  {
+    query: 'kubernetes deploy stuck rollout not finishing',
+    relevant: ['deploy:k8s:rollout-stuck'],
+  },
+  {
+    query: 'postgres too many connections under load',
+    relevant: ['db:postgres:connection-pool-exhausted'],
+  },
+  {
+    query: 'dashboard query is slow and times out',
+    relevant: ['db:postgres:slow-query-missing-index'],
+  },
+  {
+    query: 'jwt lost after restart recall count zero',
+    relevant: ['auth:jwt:expired-on-restart'],
+  },
+  {
+    query: 'keycloak rejects pkce token exchange on login',
+    relevant: ['auth:pkce:keycloak-rejects-exchange'],
+  },
+  {
+    query: 'redis noauth error on every call',
+    relevant: ['redis:noauth-on-every-call'],
+  },
+  {
+    query: 'redis memory keeps growing unbounded',
+    relevant: ['redis:keys-no-ttl-memory-leak'],
+  },
+  {
+    query: 'npm ci fails in github actions after adding dependency',
+    relevant: ['ci:npm-ci-lockfile-mismatch'],
+  },
+  {
+    query: 'cannot save settings cors preflight blocked',
+    relevant: ['frontend:cors-preflight-blocked'],
+  },
+  {
+    query: 'docker image too big slow ci push',
+    relevant: ['deploy:docker:image-too-large'],
+  },
+  {
+    query: 'go lint failing on unchecked return value',
+    relevant: ['ci:golangci-lint-errcheck'],
+  },
+  // Multi-relevant: both postgres performance lessons are reasonable answers.
+  {
+    query: 'postgres performance problem in production',
+    relevant: ['db:postgres:connection-pool-exhausted', 'db:postgres:slow-query-missing-index'],
+  },
+];

package/src/handlers/brain.ts

@@ -8,22 +8,34 @@ import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein,
          ZERO_RESULTS_LOG, zeroResultsTotal, indexVocab as _indexVocab } from '../search.js';
 import type { KeywordMatch } from '../search.js';
+import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider, embedProviderHint, EMBED_PROVIDER } from '../embeddings.js';
 import { detectNamespace } from '../namespace.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.49';
+const MCP_VERSION = '0.10.51';
 const WHATS_NEW: Record<string, string[]> = {
-  '0.10.49': [
+  '0.10.51': [
     `🆕 **What's new in v${MCP_VERSION}:**`,
+    `  ✅ \`team_confirm\` — endorse a lesson in code/knowledge review; reviewed knowledge ranks higher (🛡️ senior / ✔️ peer)`,
+    `  ✅ Governance-aware recall — human-confirmed lessons outrank unreviewed auto-learned entries`,
+    `  ✅ \`team_recall\` — shows reviewer badges and sorts confirmed lessons first`,
+    `  💡 Run \`team_confirm(topic, reviewer, level="senior")\` to bless the canonical solution`,
+  ],
+  '0.10.50': [
+    `  ✅ \`smart_recall\` — unified keyword + semantic hybrid list (one ranked result, not two sections)`,
+    `  ✅ \`smart_recall\` — "Brain saved you here" banner surfaces time saved inline per proven lesson`,
+    `  ✅ Quality reranking — proven successes outrank symptom-dense failures (+11% Precision@1)`,
+    `  ✅ Cachly-Bench — IR benchmark with CI regression guard (see BENCH.md for the proof)`,
+    `  🔧 Contradiction resolution now persisted to Redis (90-day TTL)`,
+    `  💡 Run \`smart_recall\` to see your Brain's recall quality in action`,
+  ],
+  '0.10.49': [
     `  ✅ \`brain_from_git\` — auto-seed your Brain from git history in seconds`,
     `  ✅ \`brain_predict_failures\` — predict CI/build failures before they happen`,
-    `  ✅ \`smart_recall\` — semantic + keyword hybrid recall, now in every CLAUDE.md`,
     `  ✅ VS Code extension — Brain status bar, ambient learning, CodeLens hints`,
     `  ✅ Team Brain — share lessons across your whole engineering team`,
-    `  ✅ 89 MCP tools — roadmap, A/B tests, cache, index, predict, syndicate`,
     `  🔧 Stability — auto-expiring memory keys, longer provisioning wait, robust recall`,
-    `  💡 Run \`brain_from_git\` to seed your Brain from existing commits instantly`,
   ],
 };
 
@@ -141,6 +153,18 @@ export async function handleBrainTool(
               const resId = ckgSlug(`resolution:${topic}`);
               await ckgUpdateEdge(redis, cId, 'contradicts', resId, false);
             } catch { /* non-critical */ }
+            // Persist a queryable resolution record — so contradiction history survives
+            // (CKG edges alone aren't easily auditable). Bounded + TTL'd like other history.
+            try {
+              const resolutionKey = `cachly:contradictions:${topic}`;
+              const direction = prev.outcome === 'success' && outcome === 'failure'
+                ? 'kept-success' : 'overwrote-failure';
+              await redis.rpush(resolutionKey, JSON.stringify({
+                ts, prev_outcome: prev.outcome, new_outcome: outcome, direction,
+              }));
+              await redis.ltrim(resolutionKey, -50, -1);
+              await redis.expire(resolutionKey, 180 * 86400);
+            } catch { /* non-critical */ }
             contradictionWarning.push(`🗳️ Run \`madc_deliberate(topic="${topic}")\` to resolve via expert agent voting.`);
           }
         } catch { /* ignore parse error */ }
@@ -500,114 +524,173 @@ export async function handleBrainTool(
       const redis = await getConnection(instance_id);
 
       // ── Layer 1: Keyword search across ALL brain data (always works, no embedding) ──
-      const kwMatches = await keywordSearch(
+      const rawMatches = await keywordSearch(
         redis,
         ['cachly:ctx:*', 'cachly:lesson:best:*', 'cachly:idx:*'],
         query,
         10,
       );
 
-      // Increment recall_count on matched lessons (fire-and-forget — same as recall_best_solution).
-      // This ensures the dashboard metric, Proven Laws, and trust badges reflect real smart_recall usage.
+      // ── Layer 1.5: Quality-aware rerank — proven success lessons outrank
+      // text-similar failed attempts (the moat; see src/rerank.ts + Cachly-Bench). ──
+      const kwMatches = rerankByQuality(rawMatches);
+
+      // Increment recall_count on matched lessons (fire-and-forget) + collect "Brain saved you here" signal.
+      type RecalledLesson = { topic: string; severity: string; recall_count: number; savedMins: number };
+      const savedHere: RecalledLesson[] = [];
       const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
       for (const m of lessonMatches.slice(0, 5)) {
         const existing = await redis.get(m.key).catch(() => null);
         if (existing) {
-          const lesson = safeJsonParse(existing, null as null | { recall_count?: number; [k: string]: unknown });
+          const lesson = safeJsonParse(existing, null as null | { recall_count?: number; outcome?: string; severity?: string; [k: string]: unknown });
           if (lesson) {
             const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: new Date().toISOString() };
             redis.set(m.key, JSON.stringify(updated)).catch(() => {});
-            const savedMins = (lesson.severity as string) === 'critical' ? 240 : (lesson.severity as string) === 'major' ? 60 : 30;
+            const sev = lesson.severity as string;
+            const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
             redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => {});
+            // Surface banner for proven successes (recall_count >= 1 means it's been validated)
+            if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
+              savedHere.push({
+                topic: m.key.replace('cachly:lesson:best:', ''),
+                severity: sev ?? 'major',
+                recall_count: (lesson.recall_count ?? 0) + 1,
+                savedMins,
+              });
+            }
+          }
+        }
+      }
+
+      // ── Layer 2: Semantic search (parallel, optional) ────────────────────────
+      const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
+      type SemHit = { key: string; similarity: number; content: string };
+      const semHits: SemHit[] = [];
+      if (inst.vector_token && hasEmbedProvider()) {
+        try {
+          const embedding = await computeEmbedding(query);
+          const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
+          const searchRes = await fetch(`${vectorUrl}/search`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ embedding, namespace: 'cachly:ctx', threshold, top_k: 5 }),
+          });
+          if (searchRes.ok) {
+            const results = (await searchRes.json()) as SemanticSearchResponse[];
+            for (const hit of results.filter(r => r.found && r.id)) {
+              const parts = hit.id!.replace('ctx:', '').split(':');
+              const category = parts[0];
+              const key = parts.slice(1).join(':');
+              const redisKey = `cachly:ctx:${category}:${key}`;
+              const content = await redis.get(redisKey).catch(() => null);
+              semHits.push({ key: redisKey, similarity: hit.similarity ?? 0, content: content ?? '(evicted)' });
+            }
           }
+        } catch {
+          // Semantic search failed silently — keyword results are enough
         }
       }
 
+      // ── Layer 3: Hybrid merge — one unified ranked list ──────────────────────
+      // BM25 quality scores (already reranked) are re-normalized to [0,1] for merging.
+      type HybridResult = {
+        key: string; content: string; hybridScore: number;
+        bm25Score?: number; semScore?: number; matchedWords?: string[];
+        matchType: 'keyword' | 'semantic' | 'hybrid'; subQuery?: string;
+      };
+
+      const bm25Scores = kwMatches.map(m => m.score);
+      const bm25Min = bm25Scores.length ? Math.min(...bm25Scores) : 0;
+      const bm25Range = bm25Scores.length ? (Math.max(...bm25Scores) - bm25Min) || 1 : 1;
+      const bm25Norm = (s: number) => (s - bm25Min) / bm25Range;
+
+      const hybridMap = new Map<string, HybridResult>();
+      for (const m of kwMatches) {
+        const n = bm25Norm(m.score);
+        hybridMap.set(m.key, {
+          key: m.key, content: m.content, bm25Score: n,
+          hybridScore: n * (semHits.length > 0 ? 0.7 : 1.0),
+          matchedWords: m.matchedWords, matchType: 'keyword', subQuery: m.subQuery,
+        });
+      }
+      for (const hit of semHits) {
+        const existing = hybridMap.get(hit.key);
+        if (existing) {
+          existing.semScore = hit.similarity;
+          existing.hybridScore = (existing.bm25Score ?? 0) * 0.6 + hit.similarity * 0.4;
+          existing.matchType = 'hybrid';
+        } else {
+          hybridMap.set(hit.key, {
+            key: hit.key, content: hit.content, semScore: hit.similarity,
+            hybridScore: hit.similarity * 0.5, matchType: 'semantic',
+          });
+        }
+      }
+      const hybridResults = [...hybridMap.values()].sort((a, b) => b.hybridScore - a.hybridScore);
+
+      // ── Build output ──────────────────────────────────────────────────────────
       const lines: string[] = [`🧠 **Smart Recall** for: _"${query}"_\n`];
 
+      // "Brain saved you here" banner — surfaces value inline for proven recalled lessons
+      const SORDER: Record<string, number> = { critical: 0, major: 1, minor: 2 };
+      const topLesson = savedHere.sort((a, b) => (SORDER[a.severity] ?? 1) - (SORDER[b.severity] ?? 1))[0];
+      if (topLesson) {
+        lines.push(`> 💡 **Brain saved you ~${topLesson.savedMins}m here** — ${topLesson.severity} issue from \`${topLesson.topic}\` recalled ${topLesson.recall_count}× proven\n`);
+      }
+
       // Show sub-query info if multi-topic was detected
       const subQueries = splitMultiQuery(query);
       if (subQueries.length > 1) {
         lines.push(`_Detected ${subQueries.length} sub-topics:_ ${subQueries.map((s, i) => `${i + 1}. "${s}"`).join(', ')}\n`);
       }
 
-      if (kwMatches.length > 0) {
-        lines.push(`### 🔍 BM25 Matches (${kwMatches.length})\n`);
+      if (hybridResults.length > 0) {
+        const modeLabel = semHits.length > 0
+          ? `keyword + semantic hybrid`
+          : `keyword`;
+        lines.push(`### 🔍 Results (${hybridResults.length} — ${modeLabel})\n`);
 
-        // Group by sub-query if multi-topic
+        // Group by sub-query for multi-topic queries
         if (subQueries.length > 1) {
-          const grouped = new Map<string, KeywordMatch[]>();
-          for (const m of kwMatches.slice(0, 12)) {
-            const sq = m.subQuery ?? query;
+          const grouped = new Map<string, HybridResult[]>();
+          for (const r of hybridResults.slice(0, 12)) {
+            const sq = r.subQuery ?? query;
             if (!grouped.has(sq)) grouped.set(sq, []);
-            grouped.get(sq)!.push(m);
+            grouped.get(sq)!.push(r);
           }
-          for (const [sq, matches] of grouped) {
-            lines.push(`**Topic: "${sq}"** (${matches.length} results)\n`);
-            for (const m of matches.slice(0, 4)) {
-              const label = m.key
-                .replace('cachly:ctx:', '📝 ')
-                .replace('cachly:lesson:best:', '💡 ')
-                .replace('cachly:idx:', '📂 ');
-              const preview = m.content.slice(0, 300).replace(/\n/g, ' ');
-              lines.push(`  **${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
-              lines.push(`  > ${preview}${m.content.length > 300 ? '…' : ''}\n`);
+          for (const [sq, results] of grouped) {
+            lines.push(`**Topic: "${sq}"** (${results.length} results)\n`);
+            for (const r of results.slice(0, 4)) {
+              const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+              const scorePart = r.matchType === 'hybrid'
+                ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
+                : r.matchType === 'semantic'
+                ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
+                : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
+              const preview = r.content.slice(0, 300).replace(/\n/g, ' ');
+              lines.push(`  **${label}** _(${scorePart})_`);
+              lines.push(`  > ${preview}${r.content.length > 300 ? '…' : ''}\n`);
             }
           }
-          // Summary: which sub-queries had matches
           const matched = [...grouped.keys()];
           const unmatched = subQueries.filter(sq => !matched.includes(sq));
           if (unmatched.length > 0) {
             lines.push(`\n⚠️ **No results for:** ${unmatched.map(s => `"${s}"`).join(', ')}`);
           }
         } else {
-          for (const m of kwMatches.slice(0, 8)) {
-            const label = m.key
-              .replace('cachly:ctx:', '📝 ')
-              .replace('cachly:lesson:best:', '💡 ')
-              .replace('cachly:idx:', '📂 ');
-            const preview = m.content.slice(0, 400).replace(/\n/g, ' ');
-            lines.push(`**${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
-            lines.push(`> ${preview}${m.content.length > 400 ? '…' : ''}\n`);
+          for (const r of hybridResults.slice(0, 8)) {
+            const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+            const scorePart = r.matchType === 'hybrid'
+              ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
+              : r.matchType === 'semantic'
+              ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
+              : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
+            const preview = r.content.slice(0, 400).replace(/\n/g, ' ');
+            lines.push(`**${label}** _(${scorePart})_`);
+            lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
           }
         }
-      }
-
-      // ── Layer 2: Semantic search (optional, only if embedding provider + vector_token available) ──
-      const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
-      if (inst.vector_token && hasEmbedProvider()) {
-        try {
-          const embedding = await computeEmbedding(query);
-          const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
-          const searchRes = await fetch(`${vectorUrl}/search`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ embedding, namespace: 'cachly:ctx', threshold, top_k: 5 }),
-          });
-
-          if (searchRes.ok) {
-            const results = (await searchRes.json()) as SemanticSearchResponse[];
-            const semHits = results.filter(r => r.found && r.id);
-            if (semHits.length > 0) {
-              lines.push(`\n### 🎯 Semantic Matches (${semHits.length})\n`);
-              for (const hit of semHits) {
-                const parts = hit.id!.replace('ctx:', '').split(':');
-                const category = parts[0];
-                const key = parts.slice(1).join(':');
-                const content = await redis.get(`cachly:ctx:${category}:${key}`);
-                lines.push(
-                  `**${key}** _(${((hit.similarity ?? 0) * 100).toFixed(0)}% similar)_`,
-                  `> ${content?.slice(0, 300) ?? '(evicted)'}${(content?.length ?? 0) > 300 ? '…' : ''}\n`,
-                );
-              }
-            }
-          }
-        } catch {
-          // Semantic search failed silently — keyword results are enough
-        }
-      }
-
-      if (kwMatches.length === 0) {
+      } else {
         lines.push(`⚠️ No matches found for: "${query}"`);
 
         // Did-You-Mean: find nearest token in index vocab

package/src/handlers/team.ts

@@ -11,7 +11,7 @@ type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
 
 export const TEAM_TOOL_NAMES = new Set([
-  'sync_file_changes', 'team_learn', 'team_recall', 'team_synthesize', 'memory_crystalize',
+  'sync_file_changes', 'team_learn', 'team_confirm', 'team_recall', 'team_synthesize', 'memory_crystalize',
   'brain_doctor', 'recall_at', 'trace_dependency', 'global_learn', 'global_recall',
   'publish_lesson', 'import_public_brain', 'setup_ai_memory',
 ]);
@@ -124,6 +124,59 @@ export async function handleTeamTool(
       return `✅ Team lesson stored by **${author}**: \`${topic}\` (${outcome})\n💡 ${what_worked.slice(0, 120)}`;
     }
 
+    // ── team_confirm — knowledge governance (Phase 3) ─────────────────────────
+    // A human reviewer endorses a stored lesson. The endorsement raises the
+    // lesson's recall ranking (see src/rerank.ts), so trusted, reviewed knowledge
+    // surfaces above unreviewed auto-learned entries.
+    case 'team_confirm': {
+      const { instance_id, topic, reviewer, level = 'peer', note = '' } = args as {
+        instance_id: string; topic: string; reviewer: string;
+        level?: 'senior' | 'peer'; note?: string;
+      };
+      if (!instance_id) return '❌ instance_id required';
+      if (!topic || !reviewer) return '❌ Required: topic, reviewer';
+      const reviewLevel = level === 'senior' ? 'senior' : 'peer';
+
+      const redis = await getConnection(instance_id);
+      const key = `cachly:lesson:best:${topic}`;
+      const raw = await redis.get(key);
+      const lesson = safeJsonParse<Record<string, unknown> | null>(raw, null);
+      if (!lesson) {
+        return `📭 No best-solution lesson found for \`${topic}\`.\n\nA lesson must exist (store one with \`team_learn\` / \`learn_from_attempts\`) before it can be confirmed.`;
+      }
+
+      // Track distinct reviewers so endorsements can't be inflated by one person.
+      const endorsersKey = `cachly:lesson:endorsers:${topic}`;
+      const added = await redis.sadd(endorsersKey, reviewer);
+      await redis.expire(endorsersKey, 365 * 86400);
+      const endorsements = await redis.scard(endorsersKey);
+
+      // Senior beats peer; never downgrade an existing senior review to peer.
+      const prevLevel = (lesson.review_level as string) ?? '';
+      const effectiveLevel = prevLevel === 'senior' ? 'senior' : reviewLevel;
+
+      const updated = {
+        ...lesson,
+        reviewed_by: reviewer,
+        review_level: effectiveLevel,
+        endorsements,
+        reviewed_at: new Date().toISOString(),
+      };
+      await redis.set(key, JSON.stringify(updated));
+
+      // Append an immutable review record for the audit trail.
+      const reviewLog = {
+        reviewer, level: reviewLevel, note: note.slice(0, 280), ts: new Date().toISOString(),
+      };
+      const logKey = `cachly:lesson:reviews:${topic}`;
+      await redis.rpush(logKey, JSON.stringify(reviewLog));
+      await redis.ltrim(logKey, -50, -1);
+      await redis.expire(logKey, 365 * 86400);
+
+      const badge = effectiveLevel === 'senior' ? '🛡️ senior-reviewed' : '✔️ peer-reviewed';
+      return `${badge} — \`${topic}\` confirmed by **${reviewer}** (${endorsements} distinct endorsement${endorsements === 1 ? '' : 's'}).\n📈 This lesson now ranks higher in \`smart_recall\` / \`team_recall\`.${note ? `\n📝 ${note.slice(0, 200)}` : ''}`;
+    }
+
     // ── team_recall ───────────────────────────────────────────────────────────
     case 'team_recall': {
       const { instance_id, topic, author, limit = 10 } = args as {
@@ -146,6 +199,7 @@ export async function handleTeamTool(
         topic: string; outcome: string; what_worked: string;
         ts: string; severity?: string; recall_count?: number;
         author?: string; tags?: string[];
+        reviewed_by?: string; review_level?: string; endorsements?: number;
       };
       let lessons: TeamLesson[] = [];
       if (lessonKeys.length > 0) {
@@ -169,8 +223,10 @@ export async function handleTeamTool(
         lessons = lessons.filter(l => l.author?.toLowerCase().includes(a));
       }
 
-      // Sort by recall_count desc
-      lessons.sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
+      // Sort: reviewed lessons first (senior > peer), then by recall_count desc.
+      const reviewRank = (l: TeamLesson) => l.reviewed_by ? (l.review_level === 'senior' ? 2 : 1) : 0;
+      lessons.sort((a, b) =>
+        (reviewRank(b) - reviewRank(a)) || ((b.recall_count ?? 0) - (a.recall_count ?? 0)));
       lessons = lessons.slice(0, limit);
 
       if (lessons.length === 0) {
@@ -183,11 +239,17 @@ export async function handleTeamTool(
       for (const l of lessons) {
         const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
         const sev = l.severity === 'critical' ? '🔴 ' : l.severity === 'major' ? '🟡 ' : '';
+        const reviewBadge = l.reviewed_by
+          ? (l.review_level === 'senior' ? ' 🛡️' : ' ✔️')
+          : '';
         const authorStr = l.author ? ` · _by ${l.author}_` : '';
+        const reviewStr = l.reviewed_by
+          ? ` · reviewed by ${l.reviewed_by}${(l.endorsements ?? 0) > 1 ? ` +${(l.endorsements ?? 0) - 1}` : ''}`
+          : '';
         const recallStr = (l.recall_count ?? 0) > 0 ? ` · recalled ${l.recall_count}×` : '';
         const ago = Math.round((Date.now() - new Date(l.ts).getTime()) / 86400000);
         const agoStr = ago === 0 ? 'today' : ago === 1 ? 'yesterday' : `${ago}d ago`;
-        lines.push(`${emoji} ${sev}**\`${l.topic}\`**${authorStr}${recallStr} · ${agoStr}`);
+        lines.push(`${emoji} ${sev}**\`${l.topic}\`**${reviewBadge}${authorStr}${reviewStr}${recallStr} · ${agoStr}`);
         lines.push(`   ${l.what_worked.slice(0, 120)}`);
         lines.push('');
       }