@rigour-labs/mcp 5.2.9 → 5.3.1

package/dist/index.js

@@ -29,6 +29,9 @@ import { handleReview } from './tools/review-handler.js';
 import { handleHooksCheck, handleHooksInit } from './tools/hooks-handler.js';
 import { handleCheckDeep, handleDeepStats } from './tools/deep-handlers.js';
 import { handleMcpGetSettings, handleMcpSetSettings } from './tools/mcp-settings-handler.js';
+import { handleContextStats, handleTaskCost, handleCacheStats, handleContextExplain, handleContextScope } from './tools/context-handlers.js';
+import { handleIndex } from './tools/index-handlers.js';
+import { recordContextEvent, estimateTokenCount } from '@rigour-labs/core';
 // ─── Server Setup ─────────────────────────────────────────────────
 const server = new Server({ name: "rigour-mcp", version: "3.0.1" }, { capabilities: { tools: {}, prompts: {}, logging: {}, resources: {} } });
 // Bind server for logging notifications from handlers
@@ -38,15 +41,21 @@ bindServer(server);
 // Research shows agents degrade at 30+ tools (wrong picks, hallucinated args).
 // Power-user tools are still callable — they just aren't advertised in the tool list.
 const ESSENTIAL_TOOLS = new Set([
-    'rigour_check', // Run quality gates (BEFORE declaring done)
-    'rigour_check_pattern', // Check if code exists (BEFORE creating new code)
     'rigour_recall', // Load project memory (START of every task)
+    'rigour_index', // Build/refresh pattern index (if stale)
+    'rigour_context_scope', // Scoped file retrieval BEFORE reading files
+    'rigour_check_pattern', // Check if code exists (BEFORE creating new code)
+    'rigour_check', // Run quality gates (BEFORE declaring done)
     'rigour_remember', // Store conventions/decisions
     'rigour_explain', // Explain gate failures
     'rigour_get_fix_packet', // Get structured fix instructions on FAIL
     'rigour_review', // Review diffs
     'rigour_security_audit', // CVE check
     'rigour_forget', // Remove stored memory
+    'rigour_context_stats', // Context retrieval efficiency & avoided tokens
+    'rigour_task_cost', // Verified vs estimated avoided costs
+    'rigour_cache_stats', // 4-layer cache statistics
+    'rigour_context_explain', // Explain context inclusion/exclusion audit
 ]);
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOL_DEFINITIONS.filter(t => ESSENTIAL_TOOLS.has(t.name)),
@@ -154,13 +163,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 result = await handleAgentRegister(cwd, args.agentId, args.taskScope, requestId);
                 break;
             case "rigour_checkpoint": {
-                const { progressPct, filesChanged = [], summary, qualityScore } = args;
-                result = await handleCheckpoint(cwd, progressPct, filesChanged, summary, qualityScore, requestId);
+                const { progressPct, filesChanged = [], summary, qualityScore, agentId, taskId } = args;
+                result = await handleCheckpoint(cwd, progressPct, filesChanged, summary, qualityScore, requestId, agentId, taskId);
                 break;
             }
             case "rigour_handoff": {
-                const { fromAgentId, toAgentId, taskDescription, filesInScope = [], context = '' } = args;
-                result = await handleHandoff(cwd, fromAgentId, toAgentId, taskDescription, filesInScope, context, requestId);
+                const { fromAgentId, toAgentId, taskDescription, filesInScope = [], context = '', taskId } = args;
+                result = await handleHandoff(cwd, fromAgentId, toAgentId, taskDescription, filesInScope, context, requestId, taskId);
                 break;
             }
             case "rigour_agent_deregister":
@@ -189,9 +198,51 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "rigour_review":
                 result = await handleReview(runner, cwd, args.diff, args.files);
                 break;
+            // Context Telemetry & Cost Tools
+            case "rigour_context_stats":
+                result = await handleContextStats(cwd, args.taskId);
+                break;
+            case "rigour_task_cost":
+                result = await handleTaskCost(cwd, args.taskId);
+                break;
+            case "rigour_cache_stats":
+                result = await handleCacheStats(cwd);
+                break;
+            case "rigour_context_explain":
+                result = await handleContextExplain(cwd, args.target, args.taskId);
+                break;
+            // Pattern index & scoped context
+            case "rigour_index": {
+                const { semantic, force, output } = args;
+                result = await handleIndex(cwd, { semantic, force, output });
+                break;
+            }
+            case "rigour_context_scope": {
+                const { query, limit } = args;
+                result = await handleContextScope(cwd, query, limit);
+                break;
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
+        // ── Context Telemetry Recording (honest — from handler _telemetry metadata) ──
+        try {
+            const telemetry = result?._telemetry;
+            const resultText = Array.isArray(result?.content) ? result.content.map((c) => c.text || '').join('\n') : '';
+            const returnedTokens = telemetry?.returnedTokens ?? estimateTokenCount(resultText);
+            await recordContextEvent({
+                taskId: args?.taskId || args?.task_id,
+                agentId: args?.agentId || args?.agent_id,
+                toolName: name,
+                cacheStatus: telemetry?.cacheStatus ?? 'none',
+                candidateTokens: telemetry?.candidateTokens ?? returnedTokens,
+                returnedTokens,
+                deduplicatedTokens: telemetry?.deduplicatedTokens ?? 0,
+            }, cwd);
+        }
+        catch {
+            // non-blocking context telemetry logging
+        }
         // ── Prepend image DLP warning if image content was detected ──
         if (hasImageContent && Array.isArray(result.content)) {
             result.content.unshift({

package/dist/tools/agent-handlers.d.ts

@@ -1,14 +1,6 @@
-type ToolResult = {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: boolean;
-    _shouldContinue?: boolean;
-};
+import { type ToolResult } from '../utils/context-telemetry.js';
 export declare function handleAgentRegister(cwd: string, agentId: string, taskScope: string[], requestId: string): Promise<ToolResult>;
-export declare function handleCheckpoint(cwd: string, progressPct: number, filesChanged: string[], summary: string, qualityScore: number, requestId: string): Promise<ToolResult>;
-export declare function handleHandoff(cwd: string, fromAgentId: string, toAgentId: string, taskDescription: string, filesInScope: string[], context: string, requestId: string): Promise<ToolResult>;
+export declare function handleCheckpoint(cwd: string, progressPct: number, filesChanged: string[], summary: string, qualityScore: number, requestId: string, agentId?: string, taskId?: string): Promise<ToolResult>;
+export declare function handleHandoff(cwd: string, fromAgentId: string, toAgentId: string, taskDescription: string, filesInScope: string[], context: string, requestId: string, taskId?: string): Promise<ToolResult>;
 export declare function handleAgentDeregister(cwd: string, agentId: string, requestId: string): Promise<ToolResult>;
 export declare function handleHandoffAccept(cwd: string, handoffId: string, agentId: string, requestId: string): Promise<ToolResult>;
-export {};

package/dist/tools/agent-handlers.js

@@ -9,6 +9,11 @@
 import fs from "fs-extra";
 import path from "path";
 import { logStudioEvent } from '../utils/config.js';
+import { setTaskCheckpointCache, getTaskCheckpointCache, estimateTokenCount, } from '@rigour-labs/core';
+import { PatternIndexer, savePatternIndex, loadPatternIndex, getDefaultIndexPath, } from '@rigour-labs/core/pattern-index';
+import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
+import { appendContextFooter } from '../utils/context-footer.js';
+const HANDOFF_CONTEXT_TOKEN_LIMIT = 2000;
 function parseJsonOrNull(raw) {
     try {
         return JSON.parse(raw);
@@ -17,6 +22,64 @@ function parseJsonOrNull(raw) {
         return null;
     }
 }
+function globMatchesFile(filePath, glob) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const pattern = glob
+        .replace(/\\/g, '/')
+        .replace(/\./g, '\\.')
+        .replace(/\*\*/g, '§§')
+        .replace(/\*/g, '[^/]*')
+        .replace(/§§/g, '.*');
+    if (new RegExp(`^${pattern}$`).test(normalized))
+        return true;
+    const prefix = glob.replace('/**', '').replace('/*', '').replace(/\*/g, '');
+    return normalized.startsWith(prefix);
+}
+async function refreshIndexForFiles(cwd, filesChanged) {
+    if (filesChanged.length === 0)
+        return null;
+    const indexPath = getDefaultIndexPath(cwd);
+    const existingIndex = await loadPatternIndex(indexPath);
+    if (!existingIndex) {
+        return 'Index not found — run rigour_index to enable incremental updates.';
+    }
+    try {
+        const indexer = new PatternIndexer(cwd, { useEmbeddings: existingIndex.patterns.some(p => p.embedding?.length) });
+        const updated = await indexer.updateIndex(existingIndex);
+        await savePatternIndex(updated, indexPath);
+        return `Index refreshed for ${filesChanged.length} changed file(s) — ${updated.stats.totalPatterns} patterns total.`;
+    }
+    catch (error) {
+        return `Index refresh failed: ${error.message}`;
+    }
+}
+async function validateTaskScopeAgainstIndex(cwd, taskScope) {
+    const index = await loadPatternIndex(getDefaultIndexPath(cwd));
+    if (!index) {
+        return { matchedFiles: [], unmatchedGlobs: taskScope, suggestions: ['Run rigour_index first to bind scope to indexed files.'] };
+    }
+    const indexedFiles = index.files.map(f => f.path);
+    const matchedFiles = [];
+    const unmatchedGlobs = [];
+    for (const glob of taskScope) {
+        const matches = indexedFiles.filter(f => globMatchesFile(f, glob));
+        if (matches.length > 0) {
+            matchedFiles.push(...matches);
+        }
+        else {
+            unmatchedGlobs.push(glob);
+        }
+    }
+    const uniqueMatched = Array.from(new Set(matchedFiles));
+    const suggestions = [];
+    if (uniqueMatched.length > 0 && uniqueMatched.length <= 8) {
+        suggestions.push(`Minimal scope: ${uniqueMatched.slice(0, 8).join(', ')}`);
+    }
+    if (unmatchedGlobs.length > 0) {
+        suggestions.push(`Unmatched globs (not in index): ${unmatchedGlobs.join(', ')}`);
+    }
+    return { matchedFiles: uniqueMatched, unmatchedGlobs, suggestions };
+}
 // ─── Agent Register ───────────────────────────────────────────────
 export async function handleAgentRegister(cwd, agentId, taskScope, requestId) {
     const sessionPath = path.join(cwd, '.rigour', 'agent-session.json');
@@ -27,12 +90,17 @@ export async function handleAgentRegister(cwd, agentId, taskScope, requestId) {
             session = parsed;
         }
     }
+    const indexBinding = await validateTaskScopeAgainstIndex(cwd, taskScope);
     const existingIdx = session.agents.findIndex((a) => a.agentId === agentId);
     if (existingIdx >= 0) {
         session.agents[existingIdx] = {
             agentId, taskScope,
             registeredAt: session.agents[existingIdx].registeredAt,
             lastCheckpoint: new Date().toISOString(),
+            indexBinding: {
+                matchedFiles: indexBinding.matchedFiles.length,
+                unmatchedGlobs: indexBinding.unmatchedGlobs,
+            },
         };
     }
     else {
@@ -40,6 +108,10 @@ export async function handleAgentRegister(cwd, agentId, taskScope, requestId) {
             agentId, taskScope,
             registeredAt: new Date().toISOString(),
             lastCheckpoint: new Date().toISOString(),
+            indexBinding: {
+                matchedFiles: indexBinding.matchedFiles.length,
+                unmatchedGlobs: indexBinding.unmatchedGlobs,
+            },
         });
     }
     // Scope conflict detection
@@ -55,17 +127,34 @@ export async function handleAgentRegister(cwd, agentId, taskScope, requestId) {
     }
     await fs.ensureDir(path.join(cwd, '.rigour'));
     await fs.writeFile(sessionPath, JSON.stringify(session, null, 2));
-    await logStudioEvent(cwd, { type: "agent_registered", requestId, agentId, taskScope, conflicts });
+    await logStudioEvent(cwd, { type: "agent_registered", requestId, agentId, taskScope, conflicts, indexBinding });
     let text = `✅ AGENT REGISTERED: "${agentId}" claimed scope: ${taskScope.join(', ')}\n\n`;
     text += `Active agents in session: ${session.agents.length}\n`;
+    if (indexBinding.matchedFiles.length > 0) {
+        text += `\n📎 Index binding: ${indexBinding.matchedFiles.length} indexed file(s) matched.\n`;
+        if (indexBinding.suggestions.length > 0) {
+            text += indexBinding.suggestions.map(s => `  - ${s}`).join('\n') + '\n';
+        }
+    }
+    else if (indexBinding.suggestions.length > 0) {
+        text += `\n⚠️ ${indexBinding.suggestions.join(' ')}\n`;
+    }
     if (conflicts.length > 0) {
         text += `\n⚠️ SCOPE CONFLICTS DETECTED:\n${conflicts.map(c => `  - ${c}`).join('\n')}\n`;
         text += `\nConsider coordinating with other agents or narrowing your scope.`;
     }
-    return { content: [{ type: "text", text }] };
+    const telemetry = buildTelemetryMeta({
+        candidateText: taskScope.join(' '),
+        returnedText: text,
+        cacheStatus: 'none',
+    });
+    return {
+        content: [{ type: "text", text: appendContextFooter(text, telemetry, 'rigour_recall then rigour_context_scope') }],
+        _telemetry: telemetry,
+    };
 }
 // ─── Checkpoint ───────────────────────────────────────────────────
-export async function handleCheckpoint(cwd, progressPct, filesChanged, summary, qualityScore, requestId) {
+export async function handleCheckpoint(cwd, progressPct, filesChanged, summary, qualityScore, requestId, agentId = 'default-agent', taskId = 'default-task') {
     const checkpointPath = path.join(cwd, '.rigour', 'checkpoint-session.json');
     let session = {
         sessionId: `chk-session-${Date.now()}`,
@@ -92,6 +181,8 @@ export async function handleCheckpoint(cwd, progressPct, filesChanged, summary,
             warnings.push(`Drift detected: quality dropped from avg ${avgRecent.toFixed(0)}% to ${qualityScore}%`);
         }
     }
+    const rawStateText = JSON.stringify(session);
+    const phase = `progress-${progressPct}`;
     session.checkpoints.push({
         checkpointId,
         timestamp: new Date().toISOString(),
@@ -99,42 +190,111 @@ export async function handleCheckpoint(cwd, progressPct, filesChanged, summary,
     });
     await fs.ensureDir(path.join(cwd, '.rigour'));
     await fs.writeFile(checkpointPath, JSON.stringify(session, null, 2));
-    await logStudioEvent(cwd, { type: "checkpoint_recorded", requestId, checkpointId, progressPct, qualityScore, warnings });
+    await setTaskCheckpointCache({
+        taskId,
+        agentId,
+        phase,
+        component: filesChanged[0] ? path.dirname(filesChanged[0]) : 'workspace',
+        changedFiles: filesChanged,
+        decisions: [summary],
+        validation: ['rigour_check'],
+        remainingWork: [`Continue from ${progressPct}%`],
+        risks: warnings,
+    }, estimateTokenCount(rawStateText), cwd);
+    let indexNote = null;
+    if (filesChanged.length > 0) {
+        indexNote = await refreshIndexForFiles(cwd, filesChanged);
+    }
+    await logStudioEvent(cwd, { type: "checkpoint_recorded", requestId, checkpointId, progressPct, qualityScore, warnings, filesChanged });
     let text = `📍 CHECKPOINT RECORDED: ${checkpointId}\n\n`;
     text += `Progress: ${progressPct}% | Quality: ${qualityScore}%\n`;
     text += `Summary: ${summary}\n`;
     text += `Total checkpoints: ${session.checkpoints.length}\n`;
+    if (indexNote)
+        text += `\n${indexNote}\n`;
     if (warnings.length > 0) {
         text += `\n⚠️ WARNINGS:\n${warnings.map(w => `  - ${w}`).join('\n')}\n`;
         if (qualityScore < 80)
             text += `\n⛔ QUALITY BELOW THRESHOLD: Consider pausing and reviewing recent work.`;
     }
-    const result = { content: [{ type: "text", text }] };
+    const packet = await getTaskCheckpointCache(taskId, agentId, phase, cwd);
+    const returnedText = packet ? JSON.stringify(packet) : text;
+    const telemetry = buildTelemetryMeta({
+        candidateText: rawStateText,
+        returnedText,
+        cacheStatus: 'miss',
+        deduplicatedTokens: Math.max(0, estimateTokenCount(rawStateText) - estimateTokenCount(returnedText)),
+    });
+    const result = {
+        content: [{ type: "text", text: appendContextFooter(text, telemetry, 'rigour_handoff with compact context') }],
+        _telemetry: telemetry,
+    };
     result._shouldContinue = qualityScore >= 80;
     return result;
 }
 // ─── Handoff ──────────────────────────────────────────────────────
-export async function handleHandoff(cwd, fromAgentId, toAgentId, taskDescription, filesInScope, context, requestId) {
+export async function handleHandoff(cwd, fromAgentId, toAgentId, taskDescription, filesInScope, context, requestId, taskId = 'default-task') {
+    const contextTokens = estimateTokenCount(context);
+    if (contextTokens > HANDOFF_CONTEXT_TOKEN_LIMIT) {
+        const text = `🛑 HANDOFF REJECTED: context is ~${contextTokens} tokens (limit: ${HANDOFF_CONTEXT_TOKEN_LIMIT}).\n\n`
+            + `Call rigour_checkpoint first to compress state into a checkpoint packet, then hand off with a brief summary only.\n`
+            + `Subagents should receive checkpoint packets — not parent transcripts.`;
+        return {
+            content: [{ type: 'text', text }],
+            isError: true,
+            _telemetry: buildTelemetryMeta({
+                candidateText: context,
+                returnedText: text,
+                cacheStatus: 'none',
+            }),
+        };
+    }
     const handoffId = `handoff-${Date.now()}`;
     const handoffPath = path.join(cwd, '.rigour', 'handoffs.jsonl');
+    const commitSha = await getWorkspaceCommitSha(cwd);
+    const checkpointPacket = await getTaskCheckpointCache(taskId, fromAgentId, `progress-100`, cwd)
+        ?? await getTaskCheckpointCache(taskId, fromAgentId, `progress-75`, cwd);
+    const compactContext = checkpointPacket
+        ? JSON.stringify({
+            decisions: checkpointPacket.decisions,
+            changedFiles: checkpointPacket.changedFiles,
+            remainingWork: checkpointPacket.remainingWork,
+            risks: checkpointPacket.risks,
+            brief: context.slice(0, 500),
+        })
+        : context;
     const handoff = {
         handoffId,
         timestamp: new Date().toISOString(),
-        fromAgentId, toAgentId, taskDescription, filesInScope, context,
+        fromAgentId, toAgentId, taskDescription, filesInScope,
+        context: compactContext,
+        checkpointBound: !!checkpointPacket,
+        commitSha,
         status: 'pending',
     };
     await fs.ensureDir(path.join(cwd, '.rigour'));
     await fs.appendFile(handoffPath, JSON.stringify(handoff) + '\n');
-    await logStudioEvent(cwd, { type: "handoff_initiated", requestId, handoffId, fromAgentId, toAgentId, taskDescription });
+    await logStudioEvent(cwd, { type: "handoff_initiated", requestId, handoffId, fromAgentId, toAgentId, taskDescription, contextTokens });
     let text = `🤝 HANDOFF INITIATED: ${handoffId}\n\n`;
     text += `From: ${fromAgentId} → To: ${toAgentId}\n`;
     text += `Task: ${taskDescription}\n`;
     if (filesInScope.length > 0)
         text += `Files in scope: ${filesInScope.join(', ')}\n`;
-    if (context)
-        text += `Context: ${context}\n`;
+    if (compactContext)
+        text += `Context: ${compactContext}\n`;
+    if (checkpointPacket)
+        text += `\n✅ Checkpoint packet attached (compressed handoff).\n`;
     text += `\nThe receiving agent should call rigour_agent_register to claim this scope.`;
-    return { content: [{ type: "text", text }] };
+    const telemetry = buildTelemetryMeta({
+        candidateText: context || taskDescription,
+        returnedText: compactContext || text,
+        cacheStatus: checkpointPacket ? 'partial-hit' : 'miss',
+        deduplicatedTokens: Math.max(0, contextTokens - estimateTokenCount(compactContext)),
+    });
+    return {
+        content: [{ type: "text", text: appendContextFooter(text, telemetry, 'rigour_handoff_accept') }],
+        _telemetry: telemetry,
+    };
 }
 // ─── Agent Deregister ─────────────────────────────────────────────
 export async function handleAgentDeregister(cwd, agentId, requestId) {

package/dist/tools/context-handlers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Handlers for Context Telemetry & Cost Efficiency MCP Tools
+ *
+ * Handlers for:
+ * - rigour_context_stats
+ * - rigour_task_cost
+ * - rigour_cache_stats
+ * - rigour_context_explain
+ * - rigour_context_scope
+ */
+import { type ToolResult } from '../utils/context-telemetry.js';
+export declare function handleContextStats(cwd: string, taskId?: string): Promise<ToolResult>;
+export declare function handleTaskCost(cwd: string, taskId?: string): Promise<ToolResult>;
+export declare function handleCacheStats(cwd: string): Promise<ToolResult>;
+export declare function handleContextExplain(cwd: string, target: string, taskId?: string): Promise<ToolResult>;
+export declare function handleContextScope(cwd: string, query: string, limit?: number): Promise<ToolResult>;

package/dist/tools/context-handlers.js

@@ -0,0 +1,217 @@
+/**
+ * Handlers for Context Telemetry & Cost Efficiency MCP Tools
+ *
+ * Handlers for:
+ * - rigour_context_stats
+ * - rigour_task_cost
+ * - rigour_cache_stats
+ * - rigour_context_explain
+ * - rigour_context_scope
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { getTaskContextStats, getTaskCostStats, getCacheStats, explainContext, getSemanticQueryCache, setSemanticQueryCache, estimateTokenCount, } from '@rigour-labs/core';
+import { loadPatternIndex, getDefaultIndexPath, generateEmbedding, semanticSearch, } from '@rigour-labs/core/pattern-index';
+import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
+import { appendContextFooter } from '../utils/context-footer.js';
+export async function handleContextStats(cwd, taskId) {
+    try {
+        const stats = await getTaskContextStats(taskId, cwd);
+        const jsonText = JSON.stringify(stats, null, 2);
+        return {
+            content: [{ type: "text", text: jsonText }],
+            _telemetry: buildTelemetryMeta({
+                candidateText: jsonText,
+                returnedText: jsonText,
+                cacheStatus: 'none',
+            }),
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `RIGOUR ERROR: ${e.message}` }],
+            isError: true,
+        };
+    }
+}
+export async function handleTaskCost(cwd, taskId) {
+    try {
+        const costStats = await getTaskCostStats(taskId, cwd);
+        const jsonText = JSON.stringify(costStats, null, 2);
+        return {
+            content: [{ type: "text", text: jsonText }],
+            _telemetry: buildTelemetryMeta({
+                candidateText: jsonText,
+                returnedText: jsonText,
+                cacheStatus: 'none',
+            }),
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `RIGOUR ERROR: ${e.message}` }],
+            isError: true,
+        };
+    }
+}
+export async function handleCacheStats(cwd) {
+    try {
+        const stats = await getCacheStats(cwd);
+        const jsonText = JSON.stringify(stats, null, 2);
+        return {
+            content: [{ type: "text", text: jsonText }],
+            _telemetry: buildTelemetryMeta({
+                candidateText: jsonText,
+                returnedText: jsonText,
+                cacheStatus: 'none',
+            }),
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `RIGOUR ERROR: ${e.message}` }],
+            isError: true,
+        };
+    }
+}
+export async function handleContextExplain(cwd, target, taskId) {
+    try {
+        const explanation = await explainContext(target, taskId, cwd);
+        const jsonText = JSON.stringify(explanation, null, 2);
+        return {
+            content: [{ type: "text", text: jsonText }],
+            _telemetry: buildTelemetryMeta({
+                candidateText: jsonText,
+                returnedText: jsonText,
+                cacheStatus: explanation.servedFromCache ? explanation.cacheStatus : 'miss',
+            }),
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `RIGOUR ERROR: ${e.message}` }],
+            isError: true,
+        };
+    }
+}
+function textMatchPatterns(query, patterns, limit) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const scored = patterns.map(p => {
+        const haystack = `${p.name} ${p.type} ${p.description} ${p.file} ${p.keywords?.join(' ') ?? ''}`.toLowerCase();
+        const score = terms.reduce((acc, term) => acc + (haystack.includes(term) ? 1 : 0), 0);
+        return { pattern: p, score };
+    });
+    return scored
+        .filter(s => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(s => s.pattern);
+}
+export async function handleContextScope(cwd, query, limit = 10) {
+    const commitSha = await getWorkspaceCommitSha(cwd);
+    const indexPath = getDefaultIndexPath(cwd);
+    const fullIndexCandidate = `Full repository scan for: ${query}`;
+    const cached = await getSemanticQueryCache(query, commitSha, cwd);
+    if (cached) {
+        const cachedText = JSON.stringify(cached, null, 2);
+        const telemetry = buildTelemetryMeta({
+            candidateText: fullIndexCandidate,
+            returnedText: cachedText,
+            cacheStatus: 'semantic-hit',
+        });
+        const text = `CONTEXT SCOPE (cached)\n\n${cachedText}`;
+        return {
+            content: [{ type: 'text', text: appendContextFooter(text, telemetry, 'rigour_check_pattern before creating code') }],
+            _telemetry: telemetry,
+        };
+    }
+    const index = await loadPatternIndex(indexPath);
+    if (!index) {
+        const text = '⚠️ Pattern index not found. Call rigour_index first to enable scoped context retrieval.\n\n'
+            + 'Without an index, agents tend to read entire directories — wasting tokens.';
+        return {
+            content: [{ type: 'text', text }],
+            _telemetry: buildTelemetryMeta({
+                candidateText: fullIndexCandidate,
+                returnedText: text,
+                cacheStatus: 'miss',
+            }),
+        };
+    }
+    let matched = [];
+    const hasEmbeddings = index.patterns.some(p => p.embedding && p.embedding.length > 0);
+    if (hasEmbeddings) {
+        try {
+            const queryVector = await generateEmbedding(query);
+            const similarities = semanticSearch(queryVector, index.patterns);
+            matched = index.patterns
+                .map((p, i) => ({ pattern: p, similarity: similarities[i] ?? 0 }))
+                .filter(r => r.similarity > 0.3)
+                .sort((a, b) => b.similarity - a.similarity)
+                .slice(0, limit)
+                .map(r => r.pattern);
+        }
+        catch {
+            matched = textMatchPatterns(query, index.patterns, limit);
+        }
+    }
+    else {
+        matched = textMatchPatterns(query, index.patterns, limit);
+    }
+    const editScope = Array.from(new Set(matched.map(p => p.file)));
+    const allFiles = Array.from(new Set(index.patterns.map(p => p.file)));
+    const skipScope = allFiles
+        .filter(f => !editScope.includes(f))
+        .slice(0, Math.max(0, 20 - editScope.length))
+        .map(f => ({ file: f, reason: 'Outside semantic match for query' }));
+    const signatures = matched.map(p => `- ${p.file}:${p.line} ${p.type} ${p.name} — ${p.signature || p.description || '(no signature)'}`);
+    let fullFileTokens = 0;
+    for (const file of editScope) {
+        try {
+            const content = await fs.readFile(path.join(cwd, file), 'utf-8');
+            fullFileTokens += estimateTokenCount(content);
+        }
+        catch {
+            fullFileTokens += 500;
+        }
+    }
+    const scopePayload = {
+        query,
+        editScope,
+        skipScope,
+        signatures,
+        indexHealth: {
+            totalPatterns: index.stats.totalPatterns,
+            totalFiles: index.stats.totalFiles,
+            lastUpdated: index.lastUpdated,
+            semanticEnabled: hasEmbeddings,
+        },
+        estimatedTokensSaved: Math.max(0, fullFileTokens - estimateTokenCount(signatures.join('\n'))),
+        recommendation: editScope.length > 0
+            ? `Read ONLY these ${editScope.length} file(s). Do NOT scan the whole repo.`
+            : 'No strong matches — refine query or run rigour_index --semantic',
+    };
+    await setSemanticQueryCache(query, commitSha, {
+        query,
+        resolvedOwner: editScope[0] ? path.dirname(editScope[0]) : 'unknown',
+        editScope,
+        validationScope: editScope.map(f => `review ${f}`),
+        evidence: signatures.slice(0, 5),
+        commitSha,
+        confidence: matched.length > 0 ? 0.85 : 0.3,
+    }, cwd);
+    const resultText = JSON.stringify(scopePayload, null, 2);
+    const telemetry = buildTelemetryMeta({
+        candidateText: fullIndexCandidate,
+        returnedText: resultText,
+        cacheStatus: 'miss',
+        deduplicatedTokens: scopePayload.estimatedTokensSaved,
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: appendContextFooter(`CONTEXT SCOPE\n\n${resultText}`, telemetry, 'rigour_check_pattern before creating code'),
+            }],
+        _telemetry: telemetry,
+    };
+}