minovative-mind-cli 2.9.0 → 2.10.0

package/dist/services/orchestration/investigationCache.js

@@ -3,12 +3,144 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { readCache, writeCache } from '../../utils/projectStorage.js';
 import { debugLog } from '../../utils/logger.js';
+import { levenshteinSimilarity } from '../../utils/fuzzyMatch.js';
 const CACHE_FILE = 'investigation_cache.json';
-const MAX_CACHE_SIZE_BYTES = 5 * 1024 * 1024; // 5MB
+export const MAX_CACHE_SIZE_BYTES = 5 * 1024 * 1024; // 5MB cap
+export const DEFAULT_FUZZY_THRESHOLD = 0.85;
+export const DEFAULT_SEMANTIC_THRESHOLD = 0.7;
+const TOPIC_KEYWORDS = {
+    authentication: [
+        'auth',
+        'login',
+        'logout',
+        'signin',
+        'signup',
+        'token',
+        'jwt',
+        'session',
+        'oauth',
+        'password',
+        'credential',
+        'byok',
+    ],
+    billing: ['billing', 'stripe', 'subscription', 'payment', 'checkout', 'invoice', 'pricing', 'tier', 'credit'],
+    database: [
+        'database',
+        'db',
+        'firestore',
+        'sql',
+        'postgres',
+        'mongo',
+        'prisma',
+        'schema',
+        'query',
+        'migration',
+        'table',
+    ],
+    routing: ['routing', 'router', 'route', 'endpoint', 'api', 'controller', 'middleware', 'url', 'param'],
+    'state-management': ['state', 'store', 'slice', 'reducer', 'redux', 'zustand', 'context', 'observable'],
+    caching: ['cache', 'caching', 'lru', 'eviction', 'memoize', 'redis', 'ttl', 'store', 'fingerprint', 'memory bank'],
+    testing: ['test', 'testing', 'spec', 'unit', 'integration', 'mocha', 'jest', 'vitest', 'fuzz', 'mock', 'assert'],
+    'ui-layout': [
+        'ui',
+        'layout',
+        'css',
+        'style',
+        'tailwind',
+        'component',
+        'frontend',
+        'modal',
+        'navbar',
+        'view',
+        'animation',
+        'button',
+    ],
+    orchestration: [
+        'orchestrat',
+        'subagent',
+        'task',
+        'graph',
+        'agent',
+        'workflow',
+        'complexity',
+        'trace',
+        'parallel',
+        'dispatch',
+    ],
+    security: [
+        'security',
+        'sanitiz',
+        'guard',
+        'protect',
+        'permission',
+        'vulnerability',
+        'csrf',
+        'xss',
+        'injection',
+        'audit',
+    ],
+    performance: [
+        'performance',
+        'optimize',
+        'speed',
+        'memory',
+        'heap',
+        'leak',
+        'benchmark',
+        'latency',
+        'bottleneck',
+        'cpu',
+    ],
+    'cli-tooling': ['cli', 'command', 'terminal', 'flag', 'oclif', 'bin', 'prompt', 'interactive', 'console'],
+};
+const INTENT_KEYWORDS = {
+    bug_fix: [
+        'fix',
+        'bug',
+        'issue',
+        'error',
+        'crash',
+        'fail',
+        'broken',
+        'repair',
+        'patch',
+        'exception',
+        'regression',
+        'solve',
+    ],
+    feature_addition: ['add', 'create', 'new', 'implement', 'feature', 'support', 'build', 'extend', 'introduce'],
+    refactoring: ['refactor', 'clean', 'restructure', 'reorganize', 'optimize', 'simplify', 'extract', 'modernize'],
+    explanation: [
+        'explain',
+        'what',
+        'how',
+        'why',
+        'describe',
+        'understand',
+        'investigate',
+        'analyze',
+        'overview',
+        'summary',
+    ],
+    performance_optimization: ['speed up', 'optimize', 'leak', 'benchmark', 'reduce memory', 'faster', 'profiling'],
+    testing: ['test', 'unit test', 'coverage', 'spec', 'fuzz'],
+};
+/**
+ * Normalizes prompt by trimming, collapsing whitespace, and stripping common conversation prefixes.
+ */
 export function normalizePrompt(prompt) {
-    let normalized = prompt.toLowerCase().trim();
+    let normalized = (prompt || '').toLowerCase().trim();
     normalized = normalized.replace(/\s+/g, ' ');
-    const fillerWords = ['please ', 'can you ', 'could you ', 'help me ', 'i need '];
+    const fillerWords = [
+        'please ',
+        'can you ',
+        'could you ',
+        'help me ',
+        'i need ',
+        'i want to ',
+        'how do i ',
+        'tell me ',
+    ];
     for (const word of fillerWords) {
         if (normalized.startsWith(word)) {
             normalized = normalized.slice(word.length).trim();
@@ -16,16 +148,193 @@ export function normalizePrompt(prompt) {
     }
     return normalized;
 }
+/**
+ * Computes SHA-256 hash of a normalized prompt string.
+ */
 export function hashPrompt(normalized) {
     return crypto.createHash('sha256').update(normalized).digest('hex');
 }
+/**
+ * Generates a deterministic signature from topics, components, and intent.
+ */
+export function generateSemanticSignature(topics, components, intent) {
+    const normTopics = [...new Set(topics.map((t) => t.toLowerCase().trim()))].sort().join(',');
+    const normComponents = [...new Set(components.map((c) => c.toLowerCase().trim()))].sort().join(',');
+    const normIntent = (intent || 'investigation').toLowerCase().trim();
+    return `topics:${normTopics}|components:${normComponents}|intent:${normIntent}`;
+}
+/**
+ * Offline heuristic semantic metadata extractor.
+ */
+export function extractHeuristicSemanticMetadata(prompt, relevantFiles = []) {
+    const normPrompt = normalizePrompt(prompt);
+    const lowerPrompt = prompt.toLowerCase();
+    const detectedTopics = new Set();
+    const detectedComponents = new Set();
+    // 1. Topic detection via keyword patterns
+    for (const [topic, keywords] of Object.entries(TOPIC_KEYWORDS)) {
+        for (const kw of keywords) {
+            if (lowerPrompt.includes(kw)) {
+                detectedTopics.add(topic);
+                break;
+            }
+        }
+    }
+    // 2. Component extraction from prompt tokens and file paths
+    const fileExtensionRegex = /\b[\w\-./\\]+\.(?:ts|tsx|js|jsx|json|py|cpp|h|css|md|yaml|yml)\b/gi;
+    let match;
+    while ((match = fileExtensionRegex.exec(prompt)) !== null) {
+        const raw = match[0].trim();
+        const baseName = path.basename(raw).toLowerCase();
+        detectedComponents.add(baseName);
+    }
+    // Identifier extraction (camelCase, PascalCase, hyphenated identifiers)
+    const identifierRegex = /\b[a-zA-Z][a-zA-Z0-9_-]{3,30}\b/g;
+    const promptTokens = prompt.match(identifierRegex) || [];
+    for (const token of promptTokens) {
+        const lowerToken = token.toLowerCase();
+        if (/[A-Z]/.test(token) || token.includes('_') || token.includes('-')) {
+            if (token.length > 3 && !['const', 'function', 'import', 'export', 'return'].includes(lowerToken)) {
+                detectedComponents.add(lowerToken);
+            }
+        }
+    }
+    // Include relevantFiles base names if provided
+    for (const file of relevantFiles) {
+        const base = path.basename(file).toLowerCase();
+        detectedComponents.add(base);
+        const ext = path.extname(base);
+        if (ext) {
+            detectedComponents.add(base.slice(0, -ext.length));
+        }
+    }
+    // 3. Intent detection
+    let detectedIntent = 'investigation';
+    for (const [intentName, keywords] of Object.entries(INTENT_KEYWORDS)) {
+        for (const kw of keywords) {
+            if (lowerPrompt.includes(kw)) {
+                detectedIntent = intentName;
+                break;
+            }
+        }
+        if (detectedIntent !== 'investigation')
+            break;
+    }
+    if (detectedTopics.size === 0) {
+        detectedTopics.add('general');
+    }
+    return {
+        topics: Array.from(detectedTopics),
+        components: Array.from(detectedComponents),
+        intent: detectedIntent,
+    };
+}
+/**
+ * Classifies prompt semantic intent and entity tags using AI or offline heuristic fallback.
+ */
+export async function classifySemanticIntent(userPrompt, abortSignal, customSession, timeoutMs = 60000) {
+    if (abortSignal?.aborted) {
+        const err = new Error('Operation aborted');
+        err.name = 'AbortError';
+        throw err;
+    }
+    try {
+        let session = customSession;
+        if (!session) {
+            const { createInvestigationSemanticSession } = await import('../ai.js');
+            session = createInvestigationSemanticSession();
+        }
+        if (session && typeof session.sendMessage === 'function') {
+            const sendPromise = session.sendMessage(userPrompt, undefined, abortSignal);
+            let timeoutHandle;
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error('Semantic classification timeout')), timeoutMs);
+            });
+            const response = await Promise.race([sendPromise, timeoutPromise]).finally(() => {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+            });
+            let rawText = '';
+            if (typeof response === 'string') {
+                rawText = response;
+            }
+            else if (typeof response?.response?.text === 'function') {
+                rawText = response.response.text();
+            }
+            else if (typeof response?.text === 'function') {
+                rawText = response.text();
+            }
+            else if (typeof response?.text === 'string') {
+                rawText = response.text;
+            }
+            let parsed = null;
+            if (rawText) {
+                const cleaned = rawText
+                    .replace(/^```(?:json)?\s*/i, '')
+                    .replace(/\s*```$/i, '')
+                    .trim();
+                parsed = JSON.parse(cleaned);
+            }
+            else if (response && typeof response === 'object' && !response.response) {
+                parsed = response;
+            }
+            if (parsed && Array.isArray(parsed.topics)) {
+                const topics = parsed.topics.map((t) => String(t).toLowerCase().trim()).filter(Boolean);
+                const components = Array.isArray(parsed.components)
+                    ? parsed.components.map((c) => String(c).toLowerCase().trim()).filter(Boolean)
+                    : [];
+                const intent = typeof parsed.intent === 'string' ? parsed.intent.toLowerCase().trim() : 'investigation';
+                const reasoning = typeof parsed.reasoning === 'string' ? parsed.reasoning : undefined;
+                return {
+                    topics: topics.length > 0 ? topics : ['general'],
+                    components,
+                    intent,
+                    reasoning,
+                };
+            }
+        }
+    }
+    catch (err) {
+        if (err?.name === 'AbortError' || abortSignal?.aborted) {
+            throw err;
+        }
+        debugLog(`[InvestigationCache] Semantic AI classifier failed or offline, falling back to heuristics: ${err?.message || err}`);
+    }
+    return extractHeuristicSemanticMetadata(userPrompt);
+}
+/**
+ * Calculates word-level Jaccard similarity between two texts.
+ */
+function tokenJaccardSimilarity(a, b) {
+    const tokensA = new Set(a
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 2));
+    const tokensB = new Set(b
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 2));
+    if (tokensA.size === 0 && tokensB.size === 0)
+        return 1.0;
+    if (tokensA.size === 0 || tokensB.size === 0)
+        return 0.0;
+    let intersection = 0;
+    for (const t of tokensA) {
+        if (tokensB.has(t))
+            intersection++;
+    }
+    const union = tokensA.size + tokensB.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Computes a SHA-256 fingerprint of the relevant files' mtime and sizes.
+ */
 export async function generateWorkspaceFingerprint(workspaceRoot, relevantFiles) {
     const fileStats = [];
     for (const file of relevantFiles) {
         try {
             const fullPath = path.join(workspaceRoot, file);
             const stat = await fs.stat(fullPath);
-            // Use mtimeMs and size for a robust fingerprint
             fileStats.push(`${file}:${stat.mtimeMs}:${stat.size}`);
         }
         catch (e) {
@@ -33,11 +342,9 @@ export async function generateWorkspaceFingerprint(workspaceRoot, relevantFiles)
                 fileStats.push(`${file}:deleted`);
             }
             else if (e.code === 'EACCES' || e.code === 'EPERM') {
-                // Handle permission issues by marking as changed to force re-evaluation
                 fileStats.push(`${file}:inaccessible`);
             }
             else {
-                // For other errors, assume it's changed
                 fileStats.push(`${file}:error`);
             }
         }
@@ -45,65 +352,268 @@ export async function generateWorkspaceFingerprint(workspaceRoot, relevantFiles)
     fileStats.sort();
     return crypto.createHash('sha256').update(fileStats.join('\n')).digest('hex');
 }
-export async function lookupInvestigation(workspaceRoot, userPrompt) {
-    const normalized = normalizePrompt(userPrompt);
-    const hash = hashPrompt(normalized);
+/**
+ * Enforces LRU eviction to keep cache store below MAX_CACHE_SIZE_BYTES (5MB).
+ */
+export function pruneCacheStore(store) {
+    let storeJson = JSON.stringify(store);
+    while (Buffer.byteLength(storeJson, 'utf8') > MAX_CACHE_SIZE_BYTES) {
+        const keys = Object.keys(store.entries);
+        if (keys.length === 0)
+            break;
+        let oldestKey = keys[0];
+        let oldestTime = store.entries[oldestKey].lastAccessedAt || store.entries[oldestKey].createdAt;
+        for (let i = 1; i < keys.length; i++) {
+            const entryTime = store.entries[keys[i]].lastAccessedAt || store.entries[keys[i]].createdAt;
+            if (entryTime < oldestTime) {
+                oldestKey = keys[i];
+                oldestTime = entryTime;
+            }
+        }
+        delete store.entries[oldestKey];
+        storeJson = JSON.stringify(store);
+    }
+}
+/**
+ * Looks up cached investigation results using a 2-Tier matching pipeline:
+ * - Tier 1A: Exact hash match
+ * - Tier 1B: Local fuzzy Levenshtein & token similarity match
+ * - Tier 2: AI semantic topic & component classification match
+ * All candidates validate the workspace fingerprint before returning.
+ */
+export async function lookupInvestigation(workspaceRoot, userPrompt, options = {}) {
+    const { abortSignal, allowSemanticFallback = true, semanticSession, onProgress, fuzzyThreshold = DEFAULT_FUZZY_THRESHOLD, semanticThreshold = DEFAULT_SEMANTIC_THRESHOLD, } = options;
+    if (abortSignal?.aborted) {
+        const err = new Error('Operation aborted');
+        err.name = 'AbortError';
+        throw err;
+    }
     const store = readCache(workspaceRoot, CACHE_FILE);
-    if (!store || !store.entries || !store.entries[hash]) {
+    if (!store || !store.entries || Object.keys(store.entries).length === 0) {
         return null;
     }
-    const entry = store.entries[hash];
-    const currentFingerprint = await generateWorkspaceFingerprint(workspaceRoot, entry.relevantFiles);
-    if (entry.workspaceFingerprint !== currentFingerprint) {
-        debugLog(`Investigation cache: relevant files modified, invalidating cache entry`);
-        delete store.entries[hash];
+    const normalized = normalizePrompt(userPrompt);
+    const hash = hashPrompt(normalized);
+    // ─── TIER 1A: Exact Hash Match ──────────────────────────────────────────
+    if (store.entries[hash]) {
+        const entry = store.entries[hash];
+        const currentFingerprint = await generateWorkspaceFingerprint(workspaceRoot, entry.relevantFiles);
+        if (entry.workspaceFingerprint !== currentFingerprint) {
+            debugLog(`Investigation cache: relevant files modified for exact hash ${hash}, invalidating entry`);
+            delete store.entries[hash];
+            writeCache(workspaceRoot, CACHE_FILE, store);
+            return null;
+        }
+        entry.lastAccessedAt = Date.now();
+        entry.hitCount = (entry.hitCount || 0) + 1;
+        store.totalHits = (store.totalHits || 0) + 1;
         writeCache(workspaceRoot, CACHE_FILE, store);
-        return null;
+        debugLog(`Investigation cache: Tier 1 Exact HIT for hash ${hash}`);
+        if (onProgress)
+            onProgress(`⚡ Memory Bank Exact HIT — loaded ${entry.relevantFiles.length} files`);
+        return {
+            entry,
+            bytesSaved: JSON.stringify(entry).length,
+            matchTier: 'exact',
+            similarityScore: 1.0,
+        };
+    }
+    // ─── TIER 1B: Local Fuzzy Levenshtein & Token Match ──────────────────────
+    let bestFuzzyEntry = null;
+    let bestFuzzyKey = null;
+    let bestFuzzyScore = 0;
+    const queryMeta = extractHeuristicSemanticMetadata(userPrompt);
+    for (const [key, entry] of Object.entries(store.entries)) {
+        const entryPrompt = entry.normalizedPrompt || normalizePrompt(entry.summary || '');
+        if (!entryPrompt)
+            continue;
+        const levSim = levenshteinSimilarity(normalized, entryPrompt);
+        const jaccardSim = tokenJaccardSimilarity(normalized, entryPrompt);
+        const combinedScore = 0.6 * levSim + 0.4 * jaccardSim;
+        // Prevent false fuzzy matches between distinct file/component targets
+        const entryComponents = entry.components || [];
+        const hasDisjointComponents = queryMeta.components.length > 0 &&
+            entryComponents.length > 0 &&
+            !queryMeta.components.some((qc) => entryComponents.includes(qc) ||
+                entry.relevantFiles.some((rf) => rf.toLowerCase().includes(qc) || path.basename(rf).toLowerCase().includes(qc)));
+        if (!hasDisjointComponents && levSim >= 0.8 && jaccardSim >= 0.55 && combinedScore >= fuzzyThreshold) {
+            if (combinedScore > bestFuzzyScore) {
+                bestFuzzyScore = combinedScore;
+                bestFuzzyEntry = entry;
+                bestFuzzyKey = key;
+            }
+        }
+    }
+    if (bestFuzzyEntry && bestFuzzyKey) {
+        const currentFingerprint = await generateWorkspaceFingerprint(workspaceRoot, bestFuzzyEntry.relevantFiles);
+        if (bestFuzzyEntry.workspaceFingerprint !== currentFingerprint) {
+            debugLog(`Investigation cache: relevant files modified for fuzzy match ${bestFuzzyKey}, invalidating entry`);
+            delete store.entries[bestFuzzyKey];
+            writeCache(workspaceRoot, CACHE_FILE, store);
+        }
+        else {
+            bestFuzzyEntry.lastAccessedAt = Date.now();
+            bestFuzzyEntry.hitCount = (bestFuzzyEntry.hitCount || 0) + 1;
+            store.totalHits = (store.totalHits || 0) + 1;
+            writeCache(workspaceRoot, CACHE_FILE, store);
+            debugLog(`Investigation cache: Tier 1 Fuzzy HIT (${(bestFuzzyScore * 100).toFixed(1)}%) for ${bestFuzzyKey}`);
+            if (onProgress)
+                onProgress(`⚡ Memory Bank Fuzzy HIT (${(bestFuzzyScore * 100).toFixed(0)}%) — loaded ${bestFuzzyEntry.relevantFiles.length} files`);
+            return {
+                entry: bestFuzzyEntry,
+                bytesSaved: JSON.stringify(bestFuzzyEntry).length,
+                matchTier: 'fuzzy',
+                similarityScore: bestFuzzyScore,
+            };
+        }
+    }
+    // ─── TIER 2: AI Semantic Classification Match ────────────────────────────
+    if (allowSemanticFallback) {
+        if (onProgress)
+            onProgress(`🔍 Checking Memory Bank semantic classification...`);
+        const querySemantic = await classifySemanticIntent(userPrompt, abortSignal, semanticSession);
+        if (querySemantic && (querySemantic.topics.length > 0 || querySemantic.components.length > 0)) {
+            let bestSemanticEntry = null;
+            let bestSemanticKey = null;
+            let bestSemanticScore = 0;
+            for (const [key, entry] of Object.entries(store.entries)) {
+                const entryTopics = entry.topics || [];
+                const entryComponents = entry.components || [];
+                // Calculate topic intersection over query topics (excluding generic fallback)
+                let topicMatches = 0;
+                const specificQueryTopics = querySemantic.topics.filter((t) => t !== 'general');
+                for (const t of specificQueryTopics) {
+                    if (entryTopics.includes(t))
+                        topicMatches++;
+                }
+                const topicScore = specificQueryTopics.length > 0 ? topicMatches / specificQueryTopics.length : 0;
+                // Calculate component intersection
+                let componentMatches = 0;
+                for (const c of querySemantic.components) {
+                    if (entryComponents.includes(c) ||
+                        entry.relevantFiles.some((f) => f.toLowerCase().includes(c) || path.basename(f).toLowerCase().includes(c))) {
+                        componentMatches++;
+                    }
+                }
+                const componentScore = querySemantic.components.length > 0 ? componentMatches / querySemantic.components.length : 0;
+                // If components were detected on both sides and there's 0 overlap, skip this candidate
+                if (querySemantic.components.length > 0 && entryComponents.length > 0 && componentMatches === 0) {
+                    continue;
+                }
+                // If no specific topics and no components match, skip
+                if (topicScore === 0 && componentScore === 0) {
+                    continue;
+                }
+                // Intent match bonus
+                const intentBonus = entry.intent && querySemantic.intent && entry.intent === querySemantic.intent ? 0.1 : 0.0;
+                let score = 0;
+                if (querySemantic.components.length > 0 && specificQueryTopics.length > 0) {
+                    score = 0.5 * componentScore + 0.4 * topicScore + intentBonus;
+                }
+                else if (querySemantic.components.length > 0) {
+                    score = 0.85 * componentScore + intentBonus;
+                }
+                else {
+                    score = 0.85 * topicScore + intentBonus;
+                }
+                if (score > bestSemanticScore && score >= semanticThreshold) {
+                    bestSemanticScore = score;
+                    bestSemanticEntry = entry;
+                    bestSemanticKey = key;
+                }
+            }
+            if (bestSemanticEntry && bestSemanticKey) {
+                const currentFingerprint = await generateWorkspaceFingerprint(workspaceRoot, bestSemanticEntry.relevantFiles);
+                if (bestSemanticEntry.workspaceFingerprint !== currentFingerprint) {
+                    debugLog(`Investigation cache: relevant files modified for semantic match ${bestSemanticKey}, invalidating entry`);
+                    delete store.entries[bestSemanticKey];
+                    writeCache(workspaceRoot, CACHE_FILE, store);
+                }
+                else {
+                    bestSemanticEntry.lastAccessedAt = Date.now();
+                    bestSemanticEntry.hitCount = (bestSemanticEntry.hitCount || 0) + 1;
+                    store.totalHits = (store.totalHits || 0) + 1;
+                    writeCache(workspaceRoot, CACHE_FILE, store);
+                    debugLog(`Investigation cache: Tier 2 Semantic HIT (${(bestSemanticScore * 100).toFixed(1)}%) for ${bestSemanticKey}`);
+                    if (onProgress)
+                        onProgress(`⚡ Memory Bank Semantic HIT (${(bestSemanticScore * 100).toFixed(0)}%) — loaded ${bestSemanticEntry.relevantFiles.length} files`);
+                    return {
+                        entry: bestSemanticEntry,
+                        bytesSaved: JSON.stringify(bestSemanticEntry).length,
+                        matchTier: 'semantic',
+                        similarityScore: bestSemanticScore,
+                    };
+                }
+            }
+        }
     }
-    debugLog(`Investigation cache: HIT for hash ${hash}`);
-    const bytesSaved = JSON.stringify(entry).length;
-    return { entry, bytesSaved };
+    store.totalMisses = (store.totalMisses || 0) + 1;
+    writeCache(workspaceRoot, CACHE_FILE, store);
+    return null;
 }
-export async function saveInvestigation(workspaceRoot, userPrompt, relevantFiles, summary) {
+/**
+ * Saves investigation context with semantic tagging, workspace fingerprint, and LRU pruning.
+ */
+export async function saveInvestigation(workspaceRoot, userPrompt, relevantFiles, summary, semanticMetadata, abortSignal) {
+    if (abortSignal?.aborted) {
+        const err = new Error('Operation aborted');
+        err.name = 'AbortError';
+        throw err;
+    }
     const store = readCache(workspaceRoot, CACHE_FILE) || { entries: {} };
+    if (!store.entries)
+        store.entries = {};
     const normalized = normalizePrompt(userPrompt);
     const hash = hashPrompt(normalized);
     const fingerprint = await generateWorkspaceFingerprint(workspaceRoot, relevantFiles);
+    // Use provided metadata or extract heuristic tags
+    let meta;
+    if (semanticMetadata && Array.isArray(semanticMetadata.topics) && semanticMetadata.topics.length > 0) {
+        meta = {
+            topics: semanticMetadata.topics.map((t) => t.toLowerCase().trim()),
+            components: (semanticMetadata.components || []).map((c) => c.toLowerCase().trim()),
+            intent: semanticMetadata.intent || 'investigation',
+            reasoning: semanticMetadata.reasoning,
+        };
+    }
+    else {
+        meta = extractHeuristicSemanticMetadata(userPrompt, relevantFiles);
+    }
+    const signature = generateSemanticSignature(meta.topics, meta.components, meta.intent);
     store.entries[hash] = {
         promptHash: hash,
+        normalizedPrompt: normalized,
+        topics: meta.topics,
+        components: meta.components,
+        intent: meta.intent,
+        semanticSignature: signature,
         relevantFiles,
         summary,
         workspaceFingerprint: fingerprint,
         createdAt: Date.now(),
+        lastAccessedAt: Date.now(),
+        hitCount: 0,
     };
-    // Enforce 5MB LRU limit
-    let storeJson = JSON.stringify(store);
-    while (Buffer.byteLength(storeJson, 'utf8') > MAX_CACHE_SIZE_BYTES) {
-        const keys = Object.keys(store.entries);
-        if (keys.length === 0)
-            break;
-        let oldestKey = keys[0];
-        let oldestTime = store.entries[oldestKey].createdAt;
-        for (let i = 1; i < keys.length; i++) {
-            if (store.entries[keys[i]].createdAt < oldestTime) {
-                oldestKey = keys[i];
-                oldestTime = store.entries[keys[i]].createdAt;
-            }
-        }
-        delete store.entries[oldestKey];
-        storeJson = JSON.stringify(store);
-    }
+    // Enforce LRU eviction under 5MB
+    pruneCacheStore(store);
     writeCache(workspaceRoot, CACHE_FILE, store);
-    debugLog(`💾 Investigation cached for future reuse`);
+    debugLog(`💾 Investigation cached with topics [${meta.topics.join(', ')}] and signature "${signature}"`);
 }
+/**
+ * Invalidates cache entries that reference any changed files.
+ */
 export async function invalidateFilesFromInvestigationCache(workspaceRoot, changedFiles) {
     const store = readCache(workspaceRoot, CACHE_FILE);
     if (!store || !store.entries)
         return;
+    const normalizedChanged = changedFiles.map((f) => f.replace(/\\/g, '/').toLowerCase());
     let invalidated = 0;
     for (const hash of Object.keys(store.entries)) {
         const entry = store.entries[hash];
-        const dependsOnChange = entry.relevantFiles.some((f) => changedFiles.includes(f));
+        const dependsOnChange = entry.relevantFiles.some((f) => {
+            const normF = f.replace(/\\/g, '/').toLowerCase();
+            return normalizedChanged.some((c) => normF === c || normF.endsWith('/' + c) || c.endsWith('/' + normF));
+        });
         if (dependsOnChange) {
             delete store.entries[hash];
             invalidated++;
@@ -114,6 +624,15 @@ export async function invalidateFilesFromInvestigationCache(workspaceRoot, chang
         debugLog(`[DEBUG] Investigation cache: invalidated ${invalidated} entries referencing changed files`);
     }
 }
+/**
+ * Clears all entries in the investigation cache.
+ */
+export function clearInvestigationCache(workspaceRoot) {
+    writeCache(workspaceRoot, CACHE_FILE, { entries: {}, totalHits: 0, totalMisses: 0 });
+}
+/**
+ * Returns cache statistics for inspection and telemetry.
+ */
 export function getInvestigationCacheStats(workspaceRoot) {
     const store = readCache(workspaceRoot, CACHE_FILE);
     const entriesCount = store?.entries ? Object.keys(store.entries).length : 0;
@@ -126,10 +645,20 @@ export function getInvestigationCacheStats(workspaceRoot) {
     catch (e) {
         // ignore
     }
+    const allTopics = new Set();
+    if (store?.entries) {
+        for (const entry of Object.values(store.entries)) {
+            if (Array.isArray(entry.topics)) {
+                for (const t of entry.topics)
+                    allTopics.add(t);
+            }
+        }
+    }
     return {
         entries: entriesCount,
         sizeBytes,
-        hitCount: 0,
-        missCount: 0,
+        hitCount: store?.totalHits || 0,
+        missCount: store?.totalMisses || 0,
+        topicsCount: allTopics.size,
     };
 }