claude-mem-lite 2.5.4 → 2.9.2

package/dispatch.mjs

@@ -1,18 +1,17 @@
-// claude-mem-lite: Dispatch orchestration — 3-tier intelligent resource dispatch
+// claude-mem-lite: Dispatch orchestration — 2-tier intelligent resource dispatch
 // Tier 0: Local fast filter (<1ms)
 // Tier 1: Context signal extraction (<1ms)
 // Tier 2: Enhanced FTS5 retrieval (<5ms)
-// Tier 3: Haiku semantic dispatch (~500ms, only when needed)
 
 import { basename, join } from 'path';
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { retrieveResources, buildEnhancedQuery, buildQueryFromText, DISPATCH_SYNONYMS } from './registry-retriever.mjs';
-import { renderInjection } from './dispatch-inject.mjs';
+import { renderInjection, renderHint } from './dispatch-inject.mjs';
 import { updateResourceStats, recordInvocation } from './registry.mjs';
-import { callHaikuJSON } from './haiku-client.mjs';
-import { debugCatch, truncate } from './utils.mjs';
-import { peekToolEvents, RUNTIME_DIR } from './hook-shared.mjs';
+import { debugCatch } from './utils.mjs';
+import { peekToolEvents } from './hook-shared.mjs';
 import { detectActiveSuite, shouldRecommendForStage, detectExplicitRequest, inferCurrentStage } from './dispatch-workflow.mjs';
+import { detectFailurePattern } from './dispatch-patterns.mjs';
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
@@ -29,74 +28,6 @@ export const SESSION_RECOMMEND_CAP = 3;
 // this filters only near-zero noise matches from incidental text overlap.
 export const BM25_MIN_THRESHOLD = 1.5;
 
-// Minimum confidence from Haiku semantic dispatch to replace FTS5 results.
-// Prevents low-confidence Haiku queries (e.g. 0.2) from overriding good FTS5 matches.
-export const HAIKU_CONFIDENCE_THRESHOLD = 0.6;
-
-// ─── Haiku Circuit Breaker ──────────────────────────────────────────────────
-// Prevents cascading latency when Haiku API is down or slow.
-// After BREAKER_THRESHOLD consecutive failures, disable for BREAKER_RESET_MS.
-// KNOWN LIMITATION: File-based state has a TOCTOU race under concurrent hook
-// processes. Worst case: breaker trips on failure N+1 instead of N. This is
-// acceptable — the breaker is a latency guard, not a correctness mechanism.
-
-const BREAKER_THRESHOLD = 3;
-const BREAKER_RESET_MS = 5 * 60 * 1000; // 5 minutes
-let breakerFile = join(RUNTIME_DIR, 'haiku-breaker.json');
-
-function _readBreakerState() {
-  try {
-    if (!existsSync(breakerFile)) return { failures: 0, openUntil: 0 };
-    return JSON.parse(readFileSync(breakerFile, 'utf8'));
-  } catch { return { failures: 0, openUntil: 0 }; }
-}
-
-function _writeBreakerState(state) {
-  try { writeFileSync(breakerFile, JSON.stringify(state)); } catch {}
-}
-
-/** Override breaker file path (for testing isolation). */
-export function _setBreakerFile(path) { breakerFile = path; }
-
-function isHaikuCircuitOpen() {
-  const state = _readBreakerState();
-  if (state.openUntil > 0 && Date.now() < state.openUntil) return true;
-  if (state.openUntil > 0 && Date.now() >= state.openUntil) {
-    // Half-open: single probe failure re-trips immediately
-    _writeBreakerState({ failures: BREAKER_THRESHOLD - 1, openUntil: 0 });
-  }
-  return false;
-}
-
-function recordHaikuSuccess() {
-  _writeBreakerState({ failures: 0, openUntil: 0 });
-}
-
-// NOTE: read-modify-write without file locking — concurrent hook processes may lose
-// one increment. Acceptable: threshold is 3, worst case trips on 4th failure instead.
-function recordHaikuFailure() {
-  const state = _readBreakerState();
-  state.failures++;
-  if (state.failures >= BREAKER_THRESHOLD) {
-    state.openUntil = Date.now() + BREAKER_RESET_MS;
-  }
-  _writeBreakerState(state);
-}
-
-/** Reset circuit breaker state (for testing). */
-export function _resetCircuitBreaker() {
-  _writeBreakerState({ failures: 0, openUntil: 0 });
-}
-
-/** Simulate Haiku failure (for testing). */
-export function _recordHaikuFailure() { recordHaikuFailure(); }
-
-/** Simulate Haiku success (for testing). */
-export function _recordHaikuSuccess() { recordHaikuSuccess(); }
-
-/** Check if circuit is open (for testing). */
-export function _isHaikuCircuitOpen() { return isHaikuCircuitOpen(); }
-
 // ─── Project Domain Detection ─────────────────────────────────────────────────
 
 // Module-level cache — project dir doesn't change during a session
@@ -214,6 +145,7 @@ export function extractContextSignals(event, sessionCtx = {}) {
     techStack: '',
     action: '',
     errorDomain: '',
+    failurePattern: null, // detected failure pattern from session events (repeated-test-fail, etc.)
   };
 
   // Extract weighted intent from user prompt (primary intent is first element)
@@ -258,6 +190,23 @@ export function extractContextSignals(event, sessionCtx = {}) {
     }
   }
 
+  // Failure pattern detection: override signals when Claude is struggling
+  const failurePattern = sessionCtx?.sessionEvents
+    ? detectFailurePattern(sessionCtx.sessionEvents)
+    : null;
+
+  if (failurePattern) {
+    if (!signals.primaryIntent || failurePattern.confidence > 0.7) {
+      signals.primaryIntent = failurePattern.resource_intent;
+      if (!signals.intent.includes(failurePattern.resource_intent)) {
+        signals.intent = signals.intent
+          ? `${failurePattern.resource_intent},${signals.intent}`
+          : failurePattern.resource_intent;
+      }
+    }
+    signals.failurePattern = failurePattern;
+  }
+
   return signals;
 }
 
@@ -267,7 +216,7 @@ const NEGATION_CJK = /(?:不要|别|不用|先别|暂时不|不需要|跳过|停
 
 // Test-run vs test-write disambiguation (module-scoped for performance)
 const _RUN_TEST = /\b(run\w*\s+(?:the\s+)?tests?|npm\s+test|npx\s+(?:vitest|jest|mocha|pytest)|yarn\s+test|pnpm\s+test|make\s+test|cargo\s+test|go\s+test|check\s+(?:if\s+)?tests?\s+pass|execute\s+(?:the\s+)?tests?)\b/i;
-const _RUN_TEST_CJK = /(?:运行测试|跑测试|跑一下测试|跑单测|执行测试|测试跑|看测试)/;
+const _RUN_TEST_CJK = /(?:运行测试|跑测试|跑一下测试|跑单测|跑一下单测|执行测试|执行单测|测试跑|看测试|看单测)/;
 const _WRITE_TEST = /\b(write\s+tests?|add\s+tests?|create\s+tests?|need\s+tests?|missing\s+tests?|tdd|test.?driven|red.?green|increase\s+coverage|improve\s+coverage)\b/i;
 const _WRITE_TEST_CJK = /(?:写测试|加测试|补测试|补单测|缺测试|测试覆盖)/;
 
@@ -310,7 +259,7 @@ const _INTENT_PATTERNS = (() => {
     // ── Chinese patterns ──
     [/(测试|写测试|单测|单元测试|用例|覆盖率)/, 'test'],
     [/(修复|修bug|改bug|找bug|有bug|调试|排错|报错|出错|有问题|不工作|跑不起来|不能用|挂了|崩溃)/, 'fix'],
-    [/(审查|审核|代码审查|评审|代码审核|看看代码|review)/, 'review'],
+    [/(审查|审核|审计|代码审查|评审|代码审核|看看代码|review)/, 'review'],
     [/(提交|推送|上传)/, 'commit'],
     [/(部署|上线|发布|回滚)/, 'deploy'],
     [/(规划|架构|方案|设计方案)/, 'plan'],
@@ -324,6 +273,10 @@ const _INTENT_PATTERNS = (() => {
     [/(优化|性能|卡顿|耗时|太慢|慢死了|好慢|缓存)/, 'fast'],
     [/(格式化|代码风格|代码规范|类型检查)/, 'lint'],
     [/(界面|前端|样式|页面|组件|布局)/, 'design'],
+    // search: only unambiguous web/info search indicators — NOT code search (grep/find).
+    // "搜索" alone is ambiguous (code search vs web search), so require context modifiers.
+    [/(联网搜索|网上搜索|在线搜索|上网查|搜索.{0,2}最新|搜一下.{0,2}最新|查.{0,2}最新|查资料|找资料|搜索资料|搜索文档)/, 'search'],
+    [/\b(google|search\s+online|web\s+search|look\s+up\s+(?:the\s+)?(?:latest|newest|recent|docs?|documentation))\b/i, 'search'],
   ];
   // Pre-compile global variants for matchAll — avoids creating new RegExp on every extractIntent call
   return raw.map(([p, tag]) => [p, new RegExp(p.source, p.flags.includes('g') ? p.flags : p.flags + 'g'), tag]);
@@ -362,15 +315,19 @@ function extractIntent(prompt) {
   }
 
   const found = [];
+  const suppressed = [];
   for (const tag of tagMatched) {
     if (tagHasAffirmative.get(tag) && !found.includes(tag)) {
       found.push(tag);
+    } else if (!tagHasAffirmative.get(tag)) {
+      // Tag was matched but ALL instances were negated → suppress it.
+      // This feeds the text-fallback filter to prevent recommending negated resources.
+      suppressed.push(tag);
     }
   }
 
   // Distinguish test-running from test-writing: "run tests" / "npm test" / "运行测试" should NOT
   // trigger TDD recommendations. Only keep 'test' intent when the prompt implies *writing* tests.
-  const suppressed = [];
   if (found.includes('test')) {
     const isRunning = _RUN_TEST.test(prompt) || _RUN_TEST_CJK.test(prompt);
     const isWriting = _WRITE_TEST.test(prompt) || _WRITE_TEST_CJK.test(prompt);
@@ -384,7 +341,7 @@ function extractIntent(prompt) {
 }
 
 /** Exported for testing. */
-export { NEGATION_EN as _NEGATION_EN, NEGATION_CJK as _NEGATION_CJK, reRankByKeywords as _reRankByKeywords, applyAdoptionDecay as _applyAdoptionDecay, passesConfidenceGate as _passesConfidenceGate };
+export { NEGATION_EN as _NEGATION_EN, NEGATION_CJK as _NEGATION_CJK, reRankByKeywords as _reRankByKeywords, applyAdoptionDecay as _applyAdoptionDecay, passesConfidenceGate as _passesConfidenceGate, filterAutoLoadedSkills as _filterAutoLoadedSkills, filterGarbageMetadata as _filterGarbageMetadata, decideTier as _decideTier };
 
 // Stop words for raw keyword extraction.
 // Includes common English stop words + action verbs already covered by intent patterns.
@@ -405,7 +362,7 @@ const RAW_KW_STOP = new Set([
   'review', 'deploy', 'commit', 'push', 'plan', 'clean', 'refactor',
   'find', 'get', 'set', 'show', 'list', 'change', 'move', 'copy', 'send',
   'start', 'stop', 'open', 'close', 'save', 'load', 'install', 'setup',
-  'implement', 'configure', 'code', 'file', 'function', 'module', 'app',
+  'implement', 'configure', 'code', 'file', 'function', 'module', 'app', 'system',
 ]);
 
 /**
@@ -528,6 +485,59 @@ function inferTechFromPrompt(prompt) {
   return [...tags].join(',');
 }
 
+// ─── Phase Transition Detection ─────────────────────────────────────────────
+
+const PHASE_TOOL_MAP = {
+  Read: 'EXPLORE', Glob: 'EXPLORE', Grep: 'EXPLORE', LSP: 'EXPLORE',
+  Edit: 'IMPLEMENT', Write: 'IMPLEMENT', NotebookEdit: 'IMPLEMENT',
+};
+
+/**
+ * Infer current session phase from recent tool events.
+ * @param {object[]} events Recent tool events
+ * @returns {string} Phase: EXPLORE | IMPLEMENT | DEBUG | TEST | COMMIT
+ */
+export function inferSessionPhase(events) {
+  if (!events || events.length === 0) return 'EXPLORE';
+
+  // Look at last 5 events, filter to significant ones (skip Read-only)
+  const recent = events.slice(-5);
+  const lastSignificant = recent.filter(e =>
+    e.tool_name !== 'Read' && e.tool_name !== 'Glob' && e.tool_name !== 'Grep'
+  ).slice(-3);
+
+  if (lastSignificant.length === 0) return 'EXPLORE';
+
+  const last = lastSignificant[lastSignificant.length - 1];
+
+  if (last.tool_name === 'Bash') {
+    const cmd = (last.tool_input?.command || '').toLowerCase();
+    const resp = (last.tool_response || '');
+    if (/\bgit\s+(commit|push|merge|tag)\b/.test(cmd)) return 'COMMIT';
+    if (/\b(test|jest|vitest|pytest|mocha)\b/.test(cmd)) return 'TEST';
+    if (/error|fail|exception/i.test(resp) && resp.length > 30) return 'DEBUG';
+    return 'IMPLEMENT';
+  }
+
+  return PHASE_TOOL_MAP[last.tool_name] || 'IMPLEMENT';
+}
+
+/**
+ * Check if a phase transition occurred.
+ * @param {string|null} prev Previous phase
+ * @param {string} current Current phase
+ * @returns {boolean}
+ */
+export function isPhaseTransition(prev, current) {
+  return prev !== null && prev !== current;
+}
+
+// Module-level phase state for dispatchOnPreToolUse
+let _lastPhase = null;
+
+/** Reset phase state (for testing). */
+export function _resetPhaseState() { _lastPhase = null; }
+
 /**
  * Infer action type from tool name and input.
  * @param {string} toolName Claude Code tool name (e.g. "Bash", "Edit")
@@ -575,76 +585,6 @@ function extractErrorDomain(cmd, response) {
   return 'error';
 }
 
-// ─── Tier 3: Haiku Semantic Dispatch ─────────────────────────────────────────
-
-/**
- * Check if Haiku dispatch is needed based on FTS5 results.
- * Uses relative confidence: top result must be strong enough relative to result set,
- * and gap between top two must be decisive.
- * @param {object[]} results FTS5 results with relevance scores
- * @returns {boolean} true if Haiku should be called
- */
-export function needsHaikuDispatch(results) {
-  // Circuit breaker: if Haiku is tripped, never escalate (regardless of result quality)
-  if (isHaikuCircuitOpen()) return false;
-
-  if (results.length === 0) return true;
-
-  // Prefer composite_score (includes behavioral signals) over raw BM25 relevance.
-  // Both are negative (more negative = better). Use absolute values for comparison.
-  const scoreOf = r => Math.abs(r.composite_score ?? r.relevance);
-  const topScore = scoreOf(results[0]);
-
-  // Relative threshold: if only one result or few results, use absolute minimum
-  // For larger result sets, use mean-relative threshold
-  if (results.length === 1) {
-    // Single result: needs at least moderate relevance
-    return topScore < 2.0;
-  }
-
-  // Compute mean relevance across results
-  const meanScore = results.reduce((sum, r) => sum + scoreOf(r), 0) / results.length;
-
-  // Top result should be significantly above mean (at least 1.5x)
-  if (topScore < meanScore * 1.5 && topScore < 3.0) return true;
-
-  // Top two results too close → ambiguous, need Haiku to disambiguate
-  if (results.length > 1) {
-    const gap = topScore - scoreOf(results[1]);
-    // Gap should be at least 10% of top score, or at least 0.5 absolute
-    if (gap < Math.max(topScore * 0.1, 0.5)) return true;
-  }
-
-  return false;
-}
-
-/**
- * Call Haiku LLM to semantically resolve the best resource query.
- * @param {string} userPrompt User's prompt text
- * @param {string} toolContext Current tool action context
- * @returns {Promise<{query: string, type: string, confidence: number}|null>} Haiku result or null
- */
-async function haikuDispatch(userPrompt, toolContext) {
-  // Circuit breaker: skip if Haiku is tripped
-  if (isHaikuCircuitOpen()) return null;
-
-  const prompt = `Given this coding context, which resource (skill or agent) would be most helpful?
-Return ONLY valid JSON.
-
-User intent: ${truncate(userPrompt || '', 200)}
-Current action: ${truncate(toolContext || '', 200)}
-
-JSON: {"query":"search keywords for finding the right skill or agent","type":"skill|agent|either","confidence":0.0-1.0}`;
-
-  const result = await callHaikuJSON(prompt, { timeout: 3000, maxTokens: 100 });
-  if (result) {
-    recordHaikuSuccess();
-  } else {
-    recordHaikuFailure();
-  }
-  return result;
-}
-
 // ─── Cooldown & Dedup (DB-persisted, survives process restarts) ─────────────
 
 /**
@@ -686,31 +626,93 @@ function getAdaptiveCooldown(db) {
   } catch { return COOLDOWN_MINUTES; }
 }
 
-const CONSECUTIVE_REJECT_THRESHOLD = 5;
+/**
+ * Compute per-resource cooldown based on its individual adoption rate.
+ * High-adoption resources (like code-review-expert at 90%) get shorter cooldown,
+ * ensuring valuable resources are recommended more frequently.
+ * @param {Database} db Registry database
+ * @param {number} resourceId Resource ID
+ * @param {number} globalCd Global adaptive cooldown (fallback)
+ * @returns {number} Cooldown in minutes for this specific resource
+ */
+function getPerResourceCooldown(db, resourceId, globalCd) {
+  try {
+    const stats = db.prepare(
+      'SELECT recommend_count, adopt_count FROM resources WHERE id = ?'
+    ).get(resourceId);
+    if (!stats || stats.recommend_count < 5) return globalCd; // Not enough data
+    const rate = (stats.adopt_count + 1) / (stats.recommend_count + 2); // Laplace smoothed
+    if (rate > 0.5) return Math.min(globalCd, 15);   // Very high adoption: 15 min
+    if (rate > 0.3) return Math.min(globalCd, 30);   // High adoption: 30 min
+    return globalCd; // Default: use global cooldown
+  } catch { return globalCd; }
+}
+
+const CONSECUTIVE_REJECT_THRESHOLD = 8;
 const CONSECUTIVE_REJECT_WINDOW_DAYS = 7;
+const BASE_COOLDOWN_HOURS = 1;
+const MAX_COOLDOWN_HOURS = 256; // ~10.7 days cap
+const COOLDOWN_RESET_DAYS = 7;  // Reset backoff if no recommendation in 7 days
 
 /**
  * Check if a resource has been consecutively rejected (not adopted) in recent history.
+ * Uses exponential backoff instead of binary 30-day silence:
+ *   1h → 2h → 4h → 8h → ... → 256h (cap)
+ * Backoff resets after COOLDOWN_RESET_DAYS of no recommendations.
+ *
  * @param {Database} db Registry database
  * @param {number} resourceId Resource ID
  * @returns {boolean} true if resource should be silenced
  */
 function isConsecutivelyRejected(db, resourceId) {
   try {
+    // Check active silence first (most efficient)
+    const res = db.prepare(
+      `SELECT silenced_until, cooldown_hours FROM resources WHERE id = ?`
+    ).get(resourceId);
+    if (!res) return false;
+    if (res.silenced_until && new Date(res.silenced_until) > new Date()) return true;
+
+    // Reset backoff if no recommendation in COOLDOWN_RESET_DAYS
+    const lastRec = db.prepare(
+      `SELECT created_at FROM invocations WHERE resource_id = ? AND recommended = 1 ORDER BY created_at DESC LIMIT 1`
+    ).get(resourceId);
+    if (lastRec) {
+      const daysSince = (Date.now() - new Date(lastRec.created_at).getTime()) / 86400000;
+      if (daysSince > COOLDOWN_RESET_DAYS && (res.cooldown_hours || 0) > 0) {
+        db.prepare('UPDATE resources SET cooldown_hours = 0, silenced_until = NULL WHERE id = ?').run(resourceId);
+        return false;
+      }
+    }
+
     const recent = db.prepare(`
       SELECT adopted FROM invocations
-      WHERE resource_id = ? AND recommended = 1 AND outcome IS NOT NULL
+      WHERE resource_id = ? AND recommended = 1
         AND created_at > datetime('now', ?)
       ORDER BY created_at DESC
       LIMIT ?
     `).all(resourceId, `-${CONSECUTIVE_REJECT_WINDOW_DAYS} days`, CONSECUTIVE_REJECT_THRESHOLD);
 
     if (recent.length < CONSECUTIVE_REJECT_THRESHOLD) return false;
-    return recent.every(r => r.adopted === 0);
+    if (!recent.every(r => r.adopted === 0)) return false;
+
+    // Exponential backoff: double cooldown each cycle (or start at base)
+    const currentHours = res.cooldown_hours || 0;
+    const nextHours = Math.min(
+      currentHours === 0 ? BASE_COOLDOWN_HOURS : currentHours * 2,
+      MAX_COOLDOWN_HOURS
+    );
+
+    try {
+      db.prepare(
+        `UPDATE resources SET silenced_until = datetime('now', '+${nextHours} hours'), cooldown_hours = ? WHERE id = ?`
+      ).run(nextHours, resourceId);
+    } catch { /* best-effort */ }
+    return true;
   } catch { return false; }
 }
 
-export function isRecentlyRecommended(db, resourceId, sessionId, { skipCapCheck = false } = {}) {
+export function isRecentlyRecommended(db, resourceId, sessionId, { skipCapCheck = false, cooldown } = {}) {
   // Check 1: Session cap (loop-invariant — callers should hoist isSessionCapped and pass skipCapCheck: true)
   if (sessionId && !skipCapCheck) {
     if (isSessionCapped(db, sessionId)) return true;
@@ -726,10 +728,12 @@ export function isRecentlyRecommended(db, resourceId, sessionId, { skipCapCheck
   if (isConsecutivelyRejected(db, resourceId)) return true;
 
   // Check 4: Recommended within adaptive cooldown window (cross-session cooldown)
-  const cooldown = getAdaptiveCooldown(db);
+  // Per-resource cooldown: high-adoption resources get shorter cooldown
+  const globalCd = cooldown ?? getAdaptiveCooldown(db);
+  const resourceCd = getPerResourceCooldown(db, resourceId, globalCd);
   const cooldownHit = db.prepare(
     `SELECT 1 FROM invocations WHERE resource_id = ? AND created_at > datetime('now', ?) LIMIT 1`
-  ).get(resourceId, `-${cooldown} minutes`);
+  ).get(resourceId, `-${resourceCd} minutes`);
   return !!cooldownHit;
 }
 
@@ -814,14 +818,39 @@ function applyAdoptionDecay(results, db) {
  */
 function passesConfidenceGate(results, signals) {
   // BM25 absolute minimum: filter weak text matches.
-  // Stricter threshold for 3+ results (reliable IDF); gentler floor for 1-2 results.
-  const minThreshold = results.length >= 3 ? BM25_MIN_THRESHOLD : 0.5;
+  // Threshold is relative to the top result's score to handle varying corpus sizes:
+  // small corpora (< 50 resources) naturally produce lower BM25 IDF values,
+  // so an absolute threshold would over-filter genuine matches.
+  const baseThreshold = results.length >= 3 ? BM25_MIN_THRESHOLD : 0.5;
+  const topScore = results.length > 0 ? Math.abs(results[0].composite_score ?? results[0].relevance ?? 0) : 0;
+  // Use the lower of: absolute threshold OR 30% of top score (corpus-size-adaptive floor)
+  const minThreshold = topScore > 0 ? Math.min(baseThreshold, topScore * 0.3) : baseThreshold;
   results = results.filter(r => {
     const raw = r.composite_score ?? r.relevance;
     if (raw === null || raw === undefined) return true; // no score → pass (pre-scored or synthetic result)
     return Math.abs(raw) >= minThreshold;
   });
 
+  // Gap check: if top-2 results are too close in score, the query is ambiguous.
+  // This prevents recommending when multiple resources match equally well,
+  // which usually means the match is incidental rather than precise.
+  // Skip the gap check when rawKeywords promoted #1 (keyword re-ranking changes order,
+  // so the BM25 gap no longer reflects true relevance — the keyword match is extra signal).
+  if (results.length >= 2) {
+    const top1 = Math.abs(results[0].composite_score ?? results[0].relevance ?? 0);
+    const top2 = Math.abs(results[1].composite_score ?? results[1].relevance ?? 0);
+    // After keyword re-ranking, #1 may have lower raw BM25 than #2.
+    // The keyword match provides additional confidence, so skip the gap check.
+    const wasReRanked = signals?.rawKeywords?.length > 0 && top1 < top2;
+    if (!wasReRanked && top1 > 0) {
+      const gapRatio = (top1 - top2) / top1;
+      if (gapRatio < 0.2) {
+        // Top-1 has no clear lead — ambiguous match, suppress recommendation
+        return [];
+      }
+    }
+  }
+
   // signals.intent is a comma-separated string (e.g. "test,fix"), not an array
   const intentTokens = typeof signals?.intent === 'string'
     ? signals.intent.split(',').filter(Boolean)
@@ -830,38 +859,165 @@ function passesConfidenceGate(results, signals) {
   // No structured intent → skip gate (rawKeywords match FTS5 text columns, not intent_tags)
   if (intentTokens.length === 0) return results;
 
-  // Expand intent tokens through DISPATCH_SYNONYMS so "fast" also matches "performance", etc.
-  const rawKw = signals?.rawKeywords || [];
-  const intentSet = new Set([...intentTokens, ...rawKw]);
+  // Expand ALL intent tokens through DISPATCH_SYNONYMS.
+  // rawKeywords are excluded from intentSet — they contribute to FTS5 scoring
+  // but must NOT bypass the intent gate. Including them caused false positives
+  // (e.g. "debug the dispatch system" → llm-router matched on "dispatch" tag).
+  const intentSet = new Set(intentTokens);
   for (const token of intentTokens) {
     const syns = DISPATCH_SYNONYMS[token];
     if (syns) for (const s of syns) intentSet.add(s);
   }
 
-  return results.filter(r => {
+  // Filter: resource must match at least one intent
+  const passing = results.filter(r => {
     const tags = (r.intent_tags || '').toLowerCase().split(/[\s,]+/).filter(Boolean);
     return tags.some(t => intentSet.has(t));
   });
+
+  // Primary intent preference: when multiple intents extracted (e.g. "fix,commit"),
+  // prefer resources matching the primary intent to avoid false positives from
+  // incidental context (e.g. recommending git-workflow when user primarily wants to debug).
+  if (intentTokens.length > 1 && passing.length > 1) {
+    const primaryIntent = signals?.primaryIntent || intentTokens[0] || '';
+    const primarySet = new Set([primaryIntent]);
+    const primarySyns = DISPATCH_SYNONYMS[primaryIntent];
+    if (primarySyns) for (const s of primarySyns) primarySet.add(s);
+
+    const primaryMatches = passing.filter(r => {
+      const tags = (r.intent_tags || '').toLowerCase().split(/[\s,]+/).filter(Boolean);
+      return tags.some(t => primarySet.has(t));
+    });
+    if (primaryMatches.length > 0) return primaryMatches;
+  }
+
+  return passing;
+}
+
+// ─── Auto-loaded Skill Filter ────────────────────────────────────────────────
+
+/**
+ * Filter out skills that are auto-loaded via plugin hooks (listed in system-reminder).
+ * These skills don't need dispatch recommendations because the plugin's own hooks
+ * already surface them to Claude at the right moment.
+ *
+ * User-installed standalone skills (non-namespaced invocation_name like "build-error-resolver")
+ * are KEPT — users may not remember to invoke them at the right time, so contextual
+ * recommendations still add value (installed skills have 11.5% adoption vs 6.1% community).
+ *
+ * @param {object[]} results FTS5 results
+ * @returns {object[]} Filtered results — community + standalone installed skills
+ */
+function filterAutoLoadedSkills(results) {
+  return results.filter(r => {
+    if (r.type !== 'skill') return true;
+    const inv = (r.invocation_name || '').trim();
+    if (inv === '') return true; // Community resource — always recommend
+    // Plugin-namespaced skills (e.g. "superpowers:systematic-debugging") are auto-loaded
+    // via the plugin's own hooks in system-reminder — dispatch recommendation is redundant
+    if (inv.includes(':')) return false;
+    // Standalone installed skills (e.g. "build-error-resolver") — keep for contextual recommendations
+    return true;
+  });
+}
+
+// ─── Metadata Quality Gate ──────────────────────────────────────────────────
+
+const GARBAGE_METADATA_OVERLAP_THRESHOLD = 0.8;
+const MIN_TOKEN_LENGTH = 2;
+
+/**
+ * Filter out resources with auto-generated garbage metadata.
+ * Auto-generated metadata restates the resource name as capability_summary
+ * (e.g., "agent: error debugging/error detective"), causing overly broad FTS5 matches.
+ * @param {object[]} results FTS5 results
+ * @returns {object[]} Filtered results (garbage metadata removed)
+ */
+function filterGarbageMetadata(results) {
+  return results.filter(r => {
+    const cap = (r.capability_summary || '').toLowerCase().trim();
+    if (!cap) return false; // No metadata at all — filter
+    const name = (r.name || '').toLowerCase();
+    // Garbage pattern: capability_summary is just "type: name" (restated name)
+    const nameTokens = name.replace(/[/-]/g, ' ').split(/\s+/).filter(t => t.length >= MIN_TOKEN_LENGTH);
+    if (nameTokens.length === 0) return true;
+    const capTokens = cap.replace(/[/-:]/g, ' ').split(/\s+/).filter(t => t.length >= MIN_TOKEN_LENGTH);
+    if (capTokens.length === 0) return true;
+    const overlap = capTokens.filter(t => nameTokens.includes(t)).length;
+    return overlap / capTokens.length < GARBAGE_METADATA_OVERLAP_THRESHOLD;
+  });
 }
 
 // ─── Shared Post-Processing Pipeline ────────────────────────────────────────
 
 /**
  * Standard post-processing pipeline for dispatch results.
- * Applies keyword re-ranking, adoption decay, confidence gating, and limit.
+ * Applies auto-loaded filter, metadata quality gate, keyword re-ranking,
+ * adoption decay, confidence gating, and limit.
  * @param {object[]} results FTS5 results
  * @param {object} signals Context signals
  * @param {object} db Registry database
  * @param {number} [limit=3] Maximum results to return
  * @returns {object[]} Post-processed results
  */
-function postProcessResults(results, signals, db, limit = 3) {
+function postProcessResults(results, signals, db, limit = 3, { allowOnRequest = false } = {}) {
+  // Filter on_request resources from proactive dispatch (they're only for explicit user requests)
+  if (!allowOnRequest) {
+    results = results.filter(r => (r.recommendation_mode || 'proactive') === 'proactive');
+  }
+  results = filterAutoLoadedSkills(results);
+  results = filterGarbageMetadata(results);
   results = reRankByKeywords(results, signals.rawKeywords);
   results = applyAdoptionDecay(results, db);
   results = passesConfidenceGate(results, signals);
   return results.slice(0, limit);
 }
 
+// ─── Tiered Rendering ────────────────────────────────────────────────────────
+
+/**
+ * Decide rendering tier based on composite score.
+ * High confidence → full injection (~500 tokens)
+ * Medium confidence → one-line hint (~30 tokens)
+ * Low confidence → silent (no injection)
+ *
+ * @param {object} resource Best resource from post-processing
+ * @param {object} signals Context signals (may include failurePattern)
+ * @returns {'full'|'hint'|'silent'}
+ */
+function decideTier(resource, signals) {
+  const raw = Math.abs(resource.composite_score ?? resource.relevance ?? 0);
+
+  // Pattern-detected pain point: boost confidence
+  const patternBoost = signals?.failurePattern?.confidence ?? 0;
+
+  // Normalize: typical good matches score 5-50, great matches 20+
+  // Sigmoid-like mapping to 0-1 range
+  const normalized = raw / (raw + 5.0); // 5→0.5, 10→0.67, 20→0.8, 50→0.91
+
+  // Signal-based confidence floor: if the result passed structured intent matching
+  // + keyword re-ranking, BM25 score alone shouldn't downgrade to 'silent'.
+  // Small corpora produce low BM25 scores even for strong matches.
+  let signalBoost = 0;
+  if (signals?.primaryIntent) {
+    const tags = (resource.intent_tags || '').toLowerCase().split(/[\s,]+/);
+    // Direct intent match: resource's intent_tags contain the detected primary intent.
+    // Strong boost (0.3) ensures small-corpus matches still reach 'hint' tier.
+    if (tags.includes(signals.primaryIntent)) signalBoost += 0.3;
+    else signalBoost += 0.1;
+  }
+  if (signals?.rawKeywords?.length > 0) {
+    const tags = (resource.intent_tags || '').toLowerCase();
+    if (signals.rawKeywords.some(kw => tags.includes(kw))) signalBoost += 0.2;
+  }
+
+  const confidence = Math.min(1.0, normalized + patternBoost * 0.3 + signalBoost);
+
+  if (confidence >= 0.55) return 'full';
+  if (confidence >= 0.3) return 'hint';
+  return 'silent';
+}
+
 // ─── Recommendation Reason ──────────────────────────────────────────────────
 
 const INTENT_LABELS = {
@@ -895,97 +1051,13 @@ function buildRecommendReason(signals, { explicit = false } = {}) {
 // ─── Main Dispatch Functions ─────────────────────────────────────────────────
 
 /**
- * Dispatch on SessionStart: analyze user prompt, return best resource suggestion.
- * Only dispatches when continuing from a previous session (handoff).
- * Cold starts (no previous session) showed 0% adoption — skip dispatch entirely.
- * @param {Database} db Registry database
- * @param {string} userPrompt User's prompt text
- * @param {string} [sessionId] Session identifier for dedup
- * @param {Object} [options]
- * @param {boolean} [options.hasHandoff=false] Whether a previous session handoff exists
- * @returns {Promise<string|null>} Injection text or null
+ * Dispatch on SessionStart — permanently disabled.
+ * Data: 0/122 adoption across all session_start recommendations.
+ * Session-start context injection (Last Session, Key Context) remains active via hook.mjs.
+ * Resource dispatch at session-start adds no value — user_prompt and pre_tool_use cover all needs.
  */
-export async function dispatchOnSessionStart(db, userPrompt, sessionId, { hasHandoff = false } = {}) {
-  if (!db) return null;
-  if (!hasHandoff) return null;  // Only dispatch when continuing from a previous session
-  if (!userPrompt) return null;  // Prompt still required for FTS query
-
-  try {
-    const projectDomains = detectProjectDomains();
-
-    // Primary: intent-aware enhanced query (column-targeted, better for mixed-domain prompts)
-    const signals = extractContextSignals({ tool_name: '_session_start' }, { userPrompt });
-    const enhancedQuery = buildEnhancedQuery(signals);
-
-    // Fetch extra results when rawKeywords present — BM25 may rank intent-matching
-    // resources above domain-specific ones; extra headroom lets reRankByKeywords promote them.
-    const fetchLimit = signals.rawKeywords.length > 0 ? 8 : 3;
-    let results = enhancedQuery ? retrieveResources(db, enhancedQuery, { limit: fetchLimit, projectDomains }) : [];
-
-    // Fallback: broad text query (catches prompts without clear intent patterns)
-    if (results.length === 0) {
-      const textQuery = buildQueryFromText(userPrompt);
-      if (!textQuery) return null;
-      results = retrieveResources(db, textQuery, { limit: 3, projectDomains });
-      // Filter out resources matching suppressed intents (e.g. TDD for test-running prompts)
-      if (signals.suppressedIntents.length > 0) {
-        results = results.filter(r => {
-          const tags = (r.intent_tags || '').toLowerCase().split(/[\s,]+/);
-          return !signals.suppressedIntents.some(s => tags.includes(s));
-        });
-      }
-    }
-
-    results = postProcessResults(results, signals, db);
-
-    let tier = 2;
-
-    // Tier 3: Haiku semantic fallback (SessionStart has 10s budget)
-    if (needsHaikuDispatch(results)) {
-      tier = 3;
-      const haikuResult = await haikuDispatch(userPrompt, '');
-      if (haikuResult?.query && (haikuResult.confidence ?? 0) >= HAIKU_CONFIDENCE_THRESHOLD) {
-        const haikuQuery = buildQueryFromText(haikuResult.query);
-        if (haikuQuery) {
-          let haikuResults = retrieveResources(db, haikuQuery, {
-            type: haikuResult.type === 'either' ? undefined : haikuResult.type,
-            limit: 3,
-            projectDomains,
-          });
-          if (haikuResults.length > 0) {
-            haikuResults = postProcessResults(haikuResults, signals, db);
-            if (haikuResults.length > 0) results = haikuResults;
-          }
-        }
-      }
-    }
-
-    if (results.length === 0) return null;
-
-    // Filter by DB-persisted cooldown + session dedup (hoisted cap check avoids N queries)
-    if (sessionId && isSessionCapped(db, sessionId)) return null;
-    const viable = sessionId
-      ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId, { skipCapCheck: true }))
-      : results;
-    if (viable.length === 0) return null;
-
-    const best = viable[0];
-
-    // Record invocation (also serves as cooldown/dedup marker for future checks)
-    recordInvocation(db, {
-      resource_id: best.id,
-      session_id: sessionId || null,
-      trigger: 'session_start',
-      tier,
-      recommended: 1,
-    });
-    updateResourceStats(db, best.id, 'recommend_count');
-
-    return renderInjection(best, buildRecommendReason(signals));
-  } catch (e) {
-    debugCatch(e, 'dispatchOnSessionStart');
-    return null;
-  }
+export async function dispatchOnSessionStart() {
+  return null;
 }
 
 /**
@@ -997,7 +1069,7 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId, { hasHan
  * @param {string} [sessionId] Session identifier for dedup
  * @returns {Promise<string|null>} Injection text or null
  */
-export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionEvents } = {}) {
+export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionEvents, prevContext } = {}) {
   if (!userPrompt || !db) return null;
 
   try {
@@ -1007,6 +1079,8 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
       const textQuery = buildQueryFromText(explicit.searchTerm);
       if (textQuery) {
         let explicitResults = retrieveResources(db, textQuery, { limit: 3, projectDomains: detectProjectDomains() });
+        explicitResults = filterAutoLoadedSkills(explicitResults);
+        explicitResults = filterGarbageMetadata(explicitResults);
         explicitResults = applyAdoptionDecay(explicitResults, db);
         if (explicitResults.length > 0) {
           const best = explicitResults[0];
@@ -1025,8 +1099,14 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
 
     const projectDomains = detectProjectDomains();
 
+    // Enrich prompt with previous session context (cached at session-start).
+    // Combines project history (next_steps) with user intent for richer signal.
+    const enrichedPrompt = prevContext
+      ? `${userPrompt}\n[Previous session: ${prevContext}]`
+      : userPrompt;
+
     // Intent-aware enhanced query (column-targeted)
-    const signals = extractContextSignals({ tool_name: '_user_prompt' }, { userPrompt });
+    const signals = extractContextSignals({ tool_name: '_user_prompt' }, { userPrompt: enrichedPrompt });
 
     // Check if active suite covers the current stage
     if (activeSuite) {
@@ -1064,13 +1144,11 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
 
     if (results.length === 0) return null;
 
-    // Low confidence → skip (no Haiku in user_prompt path — stay fast)
-    if (needsHaikuDispatch(results)) return null;
-
-    // Filter by cooldown + session dedup (hoisted cap check avoids N queries)
+    // Filter by cooldown + session dedup (hoisted cap + cooldown avoids N queries)
     if (sessionId && isSessionCapped(db, sessionId)) return null;
+    const cooldown = getAdaptiveCooldown(db);
     const viable = sessionId
-      ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId, { skipCapCheck: true }))
+      ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId, { skipCapCheck: true, cooldown }))
       : results;
     if (viable.length === 0) return null;
 
@@ -1085,6 +1163,9 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
     });
     updateResourceStats(db, best.id, 'recommend_count');
 
+    const tier = decideTier(best, signals);
+    if (tier === 'silent') return null;
+    if (tier === 'hint') return renderHint(best);
     return renderInjection(best, buildRecommendReason(signals));
   } catch (e) {
     debugCatch(e, 'dispatchOnUserPrompt');
@@ -1107,13 +1188,21 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
     const { skip } = shouldSkipDispatch(event);
     if (skip) return null;
 
+    // Phase transition gate: only dispatch on phase transitions to reduce noise.
+    // The first few events (≤3) always pass to allow initial recommendations.
+    const allEvents = peekToolEvents();
+    const currentPhase = inferSessionPhase(allEvents);
+    const phaseChanged = isPhaseTransition(_lastPhase, currentPhase);
+    _lastPhase = currentPhase;
+
+    if (!phaseChanged && allEvents.length > 3) return null;
+
     // Tier 1: Extract context signals
     const signals = extractContextSignals(event, sessionCtx);
 
     // Suite protection: if a suite auto-flow is active, suppress recommendations
     // for stages the suite already covers
-    const events = peekToolEvents();
-    const activeSuite = detectActiveSuite(events);
+    const activeSuite = detectActiveSuite(allEvents);
     if (activeSuite) {
       const stage = inferCurrentStage(signals.primaryIntent, activeSuite, signals.suppressedIntents);
       if (stage) {
@@ -1135,16 +1224,12 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
     results = postProcessResults(results, signals, db);
     if (results.length === 0) return null;
 
-    const tier = 2; // Tier 3 disabled for PreToolUse — 2s hook timeout insufficient
-
-    // Low-confidence results: skip recommendation rather than suggest unreliable match
-    if (needsHaikuDispatch(results)) return null;
-
-    // Apply DB-persisted cooldown and session dedup (hoisted cap check avoids N queries)
+    // Apply DB-persisted cooldown and session dedup (hoisted cap + cooldown avoids N queries)
     const sid = sessionCtx.sessionId || null;
     if (sid && isSessionCapped(db, sid)) return null;
+    const cooldown = getAdaptiveCooldown(db);
     const viable = sid
-      ? results.filter(r => !isRecentlyRecommended(db, r.id, sid, { skipCapCheck: true }))
+      ? results.filter(r => !isRecentlyRecommended(db, r.id, sid, { skipCapCheck: true, cooldown }))
       : results;
     if (viable.length === 0) return null;
     const best = viable[0];
@@ -1154,11 +1239,14 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
       resource_id: best.id,
       session_id: sid,
       trigger: 'pre_tool_use',
-      tier,
+      tier: 2,
       recommended: 1,
     });
     updateResourceStats(db, best.id, 'recommend_count');
 
+    const tier = decideTier(best, signals);
+    if (tier === 'silent') return null;
+    if (tier === 'hint') return renderHint(best);
     return renderInjection(best, buildRecommendReason(signals));
   } catch (e) {
     debugCatch(e, 'dispatchOnPreToolUse');