@getmikk/ai-context 1.7.1 → 1.9.0

package/src/claude-md-generator.ts

@@ -1,15 +1,11 @@
 import type { MikkContract, MikkLock, MikkLockFunction } from '@getmikk/core'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { countTokens, estimateFileTokens } from './token-counter.js'
 
 /** Default token budget for claude.md — generous but still bounded */
 const DEFAULT_TOKEN_BUDGET = 12000
 
-/** Rough token estimation: ~4 chars per token */
-function estimateTokens(text: string): number {
-    return Math.ceil(text.length / 4)
-}
-
 /** Metadata from package.json that enriches the AI context */
 export interface ProjectMeta {
     description?: string
@@ -46,26 +42,26 @@ export class ClaudeMdGenerator {
         const sections: string[] = []
         let usedTokens = 0
 
-        // ── Tier 1: Summary (always included) ──────────────────────
+        // --- Tier 1: Summary (always included) ----------------------
         const summary = this.generateSummary()
         sections.push(summary)
-        usedTokens += estimateTokens(summary)
+        usedTokens += countTokens(summary)
 
-        // ── Tech stack & conventions (always included if detectable) ──
+        // --- Tech stack & conventions (always included if detectable) ---
         const techSection = this.generateTechStackSection()
         if (techSection) {
             sections.push(techSection)
-            usedTokens += estimateTokens(techSection)
+            usedTokens += countTokens(techSection)
         }
 
-        // ── Build / test / run commands ─────────────────────────────
+        // --- Build / test / run commands -----------------------------
         const commandsSection = this.generateCommandsSection()
         if (commandsSection) {
             sections.push(commandsSection)
-            usedTokens += estimateTokens(commandsSection)
+            usedTokens += countTokens(commandsSection)
         }
 
-        // ── Tier 2: Module details (if budget allows) ──────────────
+        // --- Tier 2: Module details (if budget allows) --------------
         // Skip modules with zero functions — they waste AI tokens
         const modules = this.getModulesSortedByDependencyOrder()
             .filter(m => {
@@ -76,55 +72,57 @@ export class ClaudeMdGenerator {
 
         for (const module of modules) {
             const moduleSection = this.generateModuleSection(module.id)
-            const tokens = estimateTokens(moduleSection)
+            const tokens = countTokens(moduleSection)
             if (usedTokens + tokens > this.tokenBudget) {
-                sections.push('\n> Full details available in `mikk.lock.json`\n')
+                sections.push('\n  <!-- Full details truncated due to context budget -->\n')
                 break
             }
             sections.push(moduleSection)
             usedTokens += tokens
         }
 
-        // ── Context files: schemas, data models, config ─────────
+        sections.push('</modules>\n')
+
+        // --- Context files: schemas, data models, config ---------
         const contextSection = this.generateContextFilesSection()
         if (contextSection) {
-            const ctxTokens = estimateTokens(contextSection)
+            const ctxTokens = countTokens(contextSection)
             if (usedTokens + ctxTokens <= this.tokenBudget) {
                 sections.push(contextSection)
                 usedTokens += ctxTokens
             }
         }
 
-        // ── File import graph per module ────────────────────────────
+        // --- File import graph per module ----------------------------
         const importSection = this.generateImportGraphSection()
         if (importSection) {
-            const impTokens = estimateTokens(importSection)
+            const impTokens = countTokens(importSection)
             if (usedTokens + impTokens <= this.tokenBudget) {
                 sections.push(importSection)
                 usedTokens += impTokens
             }
         }
 
-        // ── HTTP Routes (Express + Next.js) ─────────────────────────
+        // --- HTTP Routes (Express + Next.js) -------------------------
         const routesSection = this.generateRoutesSection()
         if (routesSection) {
-            const routeTokens = estimateTokens(routesSection)
+            const routeTokens = countTokens(routesSection)
             if (usedTokens + routeTokens <= this.tokenBudget) {
                 sections.push(routesSection)
                 usedTokens += routeTokens
             }
         }
 
-        // ── Tier 3: Constraints & decisions ────────────────────────
+        // --- Tier 3: Constraints & decisions ------------------------
         const constraintsSection = this.generateConstraintsSection()
-        const constraintTokens = estimateTokens(constraintsSection)
+        const constraintTokens = countTokens(constraintsSection)
         if (usedTokens + constraintTokens <= this.tokenBudget) {
             sections.push(constraintsSection)
             usedTokens += constraintTokens
         }
 
         const decisionsSection = this.generateDecisionsSection()
-        const decisionTokens = estimateTokens(decisionsSection)
+        const decisionTokens = countTokens(decisionsSection)
         if (usedTokens + decisionTokens <= this.tokenBudget) {
             sections.push(decisionsSection)
             usedTokens += decisionTokens
@@ -141,15 +139,13 @@ export class ClaudeMdGenerator {
         const functionCount = Object.keys(this.lock.functions).length
         const fileCount = Object.keys(this.lock.files).length
 
-        lines.push(`# ${this.contract.project.name} — Architecture Overview`)
-        lines.push('')
+        lines.push('<repository_context>')
+        lines.push(`  <name>${this.contract.project.name}</name>`)
 
         // Project description: prefer contract, fall back to package.json
         const description = this.contract.project.description || this.meta.description
         if (description) {
-            lines.push('## What this project does')
-            lines.push(description)
-            lines.push('')
+            lines.push(`  <description>${description}</description>`)
         }
 
         // Only list modules that have functions (skip empty ones)
@@ -159,32 +155,26 @@ export class ClaudeMdGenerator {
             return fnCount > 0
         })
 
-        lines.push('## Modules')
-        for (const module of nonEmptyModules) {
-            const fnCount = Object.values(this.lock.functions)
-                .filter(f => f.moduleId === module.id).length
-            const desc = module.intent || module.description || ''
-            // Strip leading "N functions — " from auto-generated descriptions to avoid double-counting
-            const cleanDesc = desc.replace(/^\d+ functions\s*—\s*/, '')
-            const descStr = cleanDesc ? ` — ${cleanDesc}` : ''
-            lines.push(`- **${module.name}** (\`${module.id}\`): ${fnCount} functions${descStr}`)
-        }
-        lines.push('')
-
-        lines.push(`## Stats`)
-        lines.push(`- ${fileCount} files, ${functionCount} functions, ${nonEmptyModules.length} modules`)
-        lines.push(`- Language: ${this.contract.project.language}`)
-        lines.push('')
+        lines.push(`  <stats>`)
+        lines.push(`    <files>${fileCount}</files>`)
+        lines.push(`    <functions>${functionCount}</functions>`)
+        lines.push(`    <modules>${nonEmptyModules.length}</modules>`)
+        lines.push(`    <language>${this.contract.project.language}</language>`)
+        lines.push(`  </stats>`)
 
         // Critical constraints summary
         if (this.contract.declared.constraints.length > 0) {
-            lines.push('## Critical Constraints')
+            lines.push('  <critical_constraints>')
             for (const c of this.contract.declared.constraints) {
-                lines.push(`- ${c}`)
+                lines.push(`    <constraint>${c}</constraint>`)
             }
-            lines.push('')
+            lines.push('  </critical_constraints>')
         }
 
+        lines.push('</repository_context>')
+        lines.push('')
+        lines.push('<modules>')
+
         return lines.join('\n')
     }
 
@@ -198,23 +188,22 @@ export class ClaudeMdGenerator {
         const moduleFunctions = Object.values(this.lock.functions)
             .filter(f => f.moduleId === moduleId)
 
-        lines.push(`## ${module.name} module`)
+        lines.push(`  <module id="${moduleId}">`)
+        lines.push(`    <name>${module.name}</name>`)
 
         // Location — collapse to common prefix when many paths share a root
         if (module.paths.length > 0) {
             const collapsed = this.collapsePaths(module.paths)
-            lines.push(`**Location:** ${collapsed}`)
+            lines.push(`    <location>${collapsed}</location>`)
         }
 
         // Intent
         if (module.intent) {
-            lines.push(`**Purpose:** ${module.intent}`)
+            lines.push(`    <purpose>${module.intent}</purpose>`)
         } else if (module.description) {
-            lines.push(`**Purpose:** ${module.description}`)
+            lines.push(`    <purpose>${module.description}</purpose>`)
         }
 
-        lines.push('')
-
         // Entry points: functions with no calledBy (likely public API surface)
         const entryPoints = moduleFunctions
             .filter(fn => fn.calledBy.length === 0)
@@ -222,29 +211,32 @@ export class ClaudeMdGenerator {
             .slice(0, 5)
 
         if (entryPoints.length > 0) {
-            lines.push('**Entry points:**')
+            lines.push('    <entry_points>')
             for (const fn of entryPoints) {
                 const sig = this.formatSignature(fn)
-                const purpose = fn.purpose ? ` — ${this.oneLine(fn.purpose)}` : ''
-                lines.push(`  - \`${sig}\`${purpose}`)
+                const purpose = fn.purpose ? `${this.oneLine(fn.purpose)}` : ''
+                lines.push(`      <function signature="${sig.replace(/"/g, '&quot;')}" purpose="${purpose.replace(/"/g, '&quot;')}" />`)
             }
-            lines.push('')
+            lines.push('    </entry_points>')
         }
 
         // Key functions: top 5 by calledBy count (most depended upon)
+        // Exclude functions already in entry points to avoid duplicates
+        const entryPointIds = new Set(entryPoints.map(fn => fn.id))
         const keyFunctions = [...moduleFunctions]
+            .filter(fn => !entryPointIds.has(fn.id)) // Exclude duplicates
             .sort((a, b) => b.calledBy.length - a.calledBy.length)
             .filter(fn => fn.calledBy.length > 0)
             .slice(0, 5)
 
         if (keyFunctions.length > 0) {
-            lines.push('**Key internal functions:**')
+            lines.push('    <key_internal_functions>')
             for (const fn of keyFunctions) {
                 const callerCount = fn.calledBy.length
-                const purpose = fn.purpose ? ` — ${this.oneLine(fn.purpose)}` : ''
-                lines.push(`  - \`${fn.name}\` (called by ${callerCount})${purpose}`)
+                const purpose = fn.purpose ? `${this.oneLine(fn.purpose)}` : ''
+                lines.push(`      <function name="${fn.name.replace(/"/g, '&quot;')}" callers="${callerCount}" purpose="${purpose.replace(/"/g, '&quot;')}" />`)
             }
-            lines.push('')
+            lines.push('    </key_internal_functions>')
         }
 
         // Dependencies: other modules this module imports from
@@ -263,8 +255,7 @@ export class ClaudeMdGenerator {
                 const mod = this.contract.declared.modules.find(m => m.id === id)
                 return mod?.name || id
             })
-            lines.push(`**Depends on:** ${depNames.join(', ')}`)
-            lines.push('')
+            lines.push(`    <depends_on>${depNames.join(', ')}</depends_on>`)
         }
 
         // Module-specific constraints
@@ -273,13 +264,14 @@ export class ClaudeMdGenerator {
             c.toLowerCase().includes(module.name.toLowerCase())
         )
         if (moduleConstraints.length > 0) {
-            lines.push('**Constraints:**')
+            lines.push('    <module_constraints>')
             for (const c of moduleConstraints) {
-                lines.push(`  - ${c}`)
+                lines.push(`      <constraint>${c}</constraint>`)
             }
-            lines.push('')
+            lines.push('    </module_constraints>')
         }
 
+        lines.push(`  </module>`)
         return lines.join('\n')
     }
 
@@ -520,9 +512,11 @@ export class ClaudeMdGenerator {
         if (detected.length === 0) return null
 
         const lines: string[] = []
-        lines.push('## Tech Stack')
-        lines.push(detected.join(' · '))
-        lines.push('')
+        lines.push('<tech_stack>')
+        for (const d of detected) {
+            lines.push(`  <technology>${d}</technology>`)
+        }
+        lines.push('</tech_stack>')
         return lines.join('\n')
     }
 
@@ -554,12 +548,14 @@ export class ClaudeMdGenerator {
         if (useful.length === 0) return null
 
         const lines: string[] = []
-        lines.push('## Commands')
+        lines.push('<commands>')
         for (const [key, cmd] of useful) {
-            lines.push(`- \`${pm} ${key}\` \u2014 \`${cmd}\``)
+            lines.push(`  <command>`)
+            lines.push(`    <run>${pm} ${key}</run>`)
+            lines.push(`    <executes>${cmd.replace(/"/g, '&quot;')}</executes>`)
+            lines.push(`  </command>`)
         }
-
-        lines.push('')
+        lines.push('</commands>')
         return lines.join('\n')
     }
 

package/src/context-builder.ts

@@ -107,31 +107,92 @@ const STOP_WORDS = new Set([
     'want', 'like', 'just', 'also', 'some', 'all', 'any', 'my', 'your',
 ])
 
-function extractKeywords(task: string): string[] {
-    return task
+const SHORT_TECH_WORDS = new Set([
+    'ai', 'ml', 'ui', 'ux', 'ts', 'js', 'db', 'io', 'id', 'ip',
+    'ci', 'cd', 'qa', 'api', 'mcp', 'jwt', 'sql',
+])
+
+function normalizeKeyword(value: string): string {
+    return value.toLowerCase().trim().replace(/[^a-z0-9_-]/g, '')
+}
+
+function extractKeywords(task: string, requiredKeywords: string[] = []): string[] {
+    const out: string[] = []
+    const seen = new Set<string>()
+
+    for (const match of task.matchAll(/"([^"]+)"|'([^']+)'/g)) {
+        const phrase = (match[1] ?? match[2] ?? '').toLowerCase().trim()
+        if (!phrase || seen.has(phrase)) continue
+        seen.add(phrase)
+        out.push(phrase)
+    }
+
+    const words = task
         .toLowerCase()
         .replace(/[^a-z0-9\s_-]/g, ' ')
         .split(/\s+/)
-        .filter(w => w.length > 2 && !STOP_WORDS.has(w))
+        .map(normalizeKeyword)
+        .filter(w => {
+            if (!w || STOP_WORDS.has(w)) return false
+            if (w.length > 2) return true
+            return SHORT_TECH_WORDS.has(w)
+        })
+
+    for (const w of words) {
+        if (seen.has(w)) continue
+        seen.add(w)
+        out.push(w)
+    }
+
+    const expandedRequired = requiredKeywords
+        .flatMap(item => item.split(/[,\s]+/))
+        .map(normalizeKeyword)
+        .filter(Boolean)
+
+    for (const kw of expandedRequired) {
+        if (seen.has(kw)) continue
+        seen.add(kw)
+        out.push(kw)
+    }
+
+    return out
 }
 
 /**
  * Keyword score for a function: exact match > partial match
  */
-function keywordScore(fn: MikkLockFunction, keywords: string[]): number {
-    if (keywords.length === 0) return 0
+function keywordScore(
+    fn: MikkLockFunction,
+    keywords: string[]
+): { score: number; matchedKeywords: string[] } {
+    if (keywords.length === 0) return { score: 0, matchedKeywords: [] }
     const nameLower = fn.name.toLowerCase()
     const fileLower = fn.file.toLowerCase()
+    const fileNoExt = fileLower.replace(/\.(d\.ts|ts|tsx|js|jsx|mjs|cjs|mts|cts)\b/g, ' ')
+    const purposeLower = (fn.purpose ?? '').toLowerCase()
+    const tokenSet = new Set<string>([
+        ...(nameLower.match(/[a-z0-9]+/g) ?? []),
+        ...(fileNoExt.match(/[a-z0-9]+/g) ?? []),
+        ...(purposeLower.match(/[a-z0-9]+/g) ?? []),
+    ])
     let score = 0
+    const matched: string[] = []
 
     for (const kw of keywords) {
-        if (nameLower === kw) {
+        const shortKw = kw.length <= 2
+        const exactName = nameLower === kw
+        const partial = shortKw
+            ? tokenSet.has(kw)
+            : (nameLower.includes(kw) || fileLower.includes(kw) || purposeLower.includes(kw))
+        if (exactName) {
             score = Math.max(score, WEIGHT.KEYWORD_EXACT)
-        } else if (nameLower.includes(kw) || fileLower.includes(kw)) {
+            matched.push(kw)
+        } else if (partial) {
             score = Math.max(score, WEIGHT.KEYWORD_PARTIAL)
+            matched.push(kw)
         }
     }
-    return score
+    return { score, matchedKeywords: matched }
 }
 
 // ---------------------------------------------------------------------------
@@ -145,8 +206,10 @@ function keywordScore(fn: MikkLockFunction, keywords: string[]): number {
 function resolveSeeds(
     query: ContextQuery,
     contract: MikkContract,
-    lock: MikkLock
+    lock: MikkLock,
+    keywords: string[]
 ): string[] {
+    const strictMode = query.relevanceMode === 'strict'
     const seeds = new Set<string>()
 
     // 1. Explicit focus files → all functions in those files
@@ -171,16 +234,15 @@ function resolveSeeds(
 
     // 3. Keyword match against function names and file paths
     if (seeds.size === 0) {
-        const keywords = extractKeywords(query.task)
         for (const fn of Object.values(lock.functions)) {
-            if (keywordScore(fn, keywords) >= WEIGHT.KEYWORD_PARTIAL) {
+            if (keywordScore(fn, keywords).score >= WEIGHT.KEYWORD_PARTIAL) {
                 seeds.add(fn.id)
             }
         }
     }
 
     // 4. Module name match against task
-    if (seeds.size === 0) {
+    if (!strictMode && seeds.size === 0) {
         const taskLower = query.task.toLowerCase()
         for (const mod of contract.declared.modules) {
             if (
@@ -219,11 +281,22 @@ export class ContextBuilder {
      * 6. Group survivors by module, emit structured context
      */
     build(query: ContextQuery): AIContext {
+        const relevanceMode = query.relevanceMode ?? 'balanced'
+        const strictMode = relevanceMode === 'strict'
         const tokenBudget = query.tokenBudget ?? DEFAULT_TOKEN_BUDGET
         const maxHops = query.maxHops ?? 4
+        const requiredKeywords = query.requiredKeywords ?? []
+        const keywords = extractKeywords(query.task, requiredKeywords)
+        const requiredKeywordSet = new Set(
+            requiredKeywords
+                .flatMap(item => item.split(/[,\s]+/))
+                .map(normalizeKeyword)
+                .filter(Boolean)
+        )
 
         // ── Step 1: Resolve seeds ──────────────────────────────────────────
-        const seeds = resolveSeeds(query, this.contract, this.lock)
+        const seeds = resolveSeeds(query, this.contract, this.lock, keywords)
+        const seedSet = new Set(seeds)
 
         // ── Step 2: BFS proximity scores ──────────────────────────────────
         const proximityMap = seeds.length > 0
@@ -231,8 +304,15 @@ export class ContextBuilder {
             : new Map<string, number>()
 
         // ── Step 3: Score every function ──────────────────────────────────
-        const keywords = extractKeywords(query.task)
         const allFunctions = Object.values(this.lock.functions)
+        const focusFiles = query.focusFiles ?? []
+        const focusModules = new Set(query.focusModules ?? [])
+        const requireAllKeywords = query.requireAllKeywords ?? false
+        const minKeywordMatches = query.minKeywordMatches ?? 1
+        const strictPassIds = new Set<string>()
+        const reasons: string[] = []
+        const suggestions: string[] = []
+        const nearMissSuggestions: string[] = []
 
         const scored: { fn: MikkLockFunction; score: number }[] = allFunctions.map(fn => {
             let score = 0
@@ -244,19 +324,55 @@ export class ContextBuilder {
             }
 
             // Keyword match
-            score += keywordScore(fn, keywords)
+            const kwInfo = keywordScore(fn, keywords)
+            score += kwInfo.score
+
+            const matchedSet = new Set(kwInfo.matchedKeywords)
+            const inFocusFile = focusFiles.some(filePath => fn.file.includes(filePath) || filePath.includes(fn.file))
+            const inFocusModule = focusModules.has(fn.moduleId)
+            const inFocus = inFocusFile || inFocusModule
+
+            const requiredPass = requiredKeywordSet.size === 0
+                ? true
+                : [...requiredKeywordSet].every(kw => matchedSet.has(kw))
+            const generalPass = requireAllKeywords
+                ? (keywords.length > 0 && matchedSet.size >= keywords.length)
+                : (keywords.length === 0 ? false : matchedSet.size >= minKeywordMatches)
+            const keywordPass = requiredPass && generalPass
+            if (keywordPass) strictPassIds.add(fn.id)
+
+            if (strictMode) {
+                const isSeed = seedSet.has(fn.id)
+                const seedFromFocus = isSeed && (inFocus || focusFiles.length > 0 || focusModules.size > 0)
+                if (!(inFocus || keywordPass || seedFromFocus)) {
+                    if (kwInfo.score > 0) {
+                        nearMissSuggestions.push(`${fn.name} (${fn.file}:${fn.startLine})`)
+                    }
+                    return { fn, score: -1 }
+                }
+            }
 
             // Entry-point bonus
-            if (fn.calledBy.length === 0) score += WEIGHT.ENTRY_POINT
+            if (!strictMode && fn.calledBy.length === 0) score += WEIGHT.ENTRY_POINT
 
             return { fn, score }
         })
 
         // ── Step 4: Sort by score descending ──────────────────────────────
         scored.sort((a, b) => b.score - a.score)
+        for (const { fn, score } of scored) {
+            if (score <= 0) continue
+            suggestions.push(`${fn.name} (${fn.file}:${fn.startLine})`)
+            if (suggestions.length >= 5) break
+        }
+        for (const s of nearMissSuggestions) {
+            if (suggestions.includes(s)) continue
+            suggestions.push(s)
+            if (suggestions.length >= 5) break
+        }
 
         // ── Step 5: Fill token budget ──────────────────────────────────────
-        const selected: MikkLockFunction[] = []
+        let selected: MikkLockFunction[] = []
         let usedTokens = 0
 
         for (const { fn, score } of scored) {
@@ -271,6 +387,57 @@ export class ContextBuilder {
             usedTokens += tokens
         }
 
+        if (strictMode) {
+            if (requiredKeywordSet.size > 0) {
+                reasons.push(`required terms: ${[...requiredKeywordSet].join(', ')}`)
+            }
+            if (strictPassIds.size === 0) {
+                reasons.push('no functions matched strict keyword filters')
+            }
+        }
+
+        if (strictMode && query.exactOnly) {
+            selected = selected.filter(fn => strictPassIds.has(fn.id))
+            usedTokens = selected.reduce(
+                (sum, fn) => sum + estimateTokens(this.buildFunctionSnippet(fn, query)),
+                0
+            )
+            if (selected.length === 0 && strictPassIds.size > 0) {
+                reasons.push('exact matches exist but did not fit token budget or max function limit')
+            }
+        }
+
+        if (strictMode && query.failFast && selected.length === 0) {
+            reasons.push('fail-fast enabled: returning no context when exact match set is empty')
+            return {
+                project: {
+                    name: this.contract.project.name,
+                    language: this.contract.project.language,
+                    description: this.contract.project.description,
+                    moduleCount: this.contract.declared.modules.length,
+                    functionCount: Object.keys(this.lock.functions).length,
+                },
+                modules: [],
+                constraints: this.contract.declared.constraints,
+                decisions: this.contract.declared.decisions.map(d => ({
+                    title: d.title,
+                    reason: d.reason,
+                })),
+                contextFiles: [],
+                routes: [],
+                prompt: '',
+                meta: {
+                    seedCount: seeds.length,
+                    totalFunctionsConsidered: allFunctions.length,
+                    selectedFunctions: 0,
+                    estimatedTokens: 0,
+                    keywords,
+                    reasons,
+                    suggestions: suggestions.length > 0 ? suggestions : undefined,
+                },
+            }
+        }
+
         // ── Step 6: Group by module ────────────────────────────────────────
         const byModule = new Map<string, MikkLockFunction[]>()
         for (const fn of selected) {
@@ -298,6 +465,10 @@ export class ContextBuilder {
         // Sort modules: ones with more selected functions first
         contextModules.sort((a, b) => b.functions.length - a.functions.length)
 
+        // Strict mode favors precision and token efficiency: keep only function graph context.
+        const contextFiles = strictMode ? [] : this.lock.contextFiles
+        const routes = strictMode ? [] : this.lock.routes
+
         return {
             project: {
                 name: this.contract.project.name,
@@ -312,12 +483,12 @@ export class ContextBuilder {
                 title: d.title,
                 reason: d.reason,
             })),
-            contextFiles: this.lock.contextFiles?.map(cf => ({
+            contextFiles: contextFiles?.map(cf => ({
                 path: cf.path,
                 content: readContextFile(cf.path, query.projectRoot),
                 type: cf.type,
             })),
-            routes: this.lock.routes?.map(r => ({
+            routes: routes?.map(r => ({
                 method: r.method,
                 path: r.path,
                 handler: r.handler,
@@ -332,6 +503,8 @@ export class ContextBuilder {
                 selectedFunctions: selected.length,
                 estimatedTokens: usedTokens,
                 keywords,
+                reasons: reasons.length > 0 ? reasons : undefined,
+                suggestions: (selected.length === 0 && suggestions.length > 0) ? suggestions : undefined,
             },
         }
     }
@@ -414,6 +587,7 @@ export class ContextBuilder {
     /** Generate the natural-language prompt section */
     private generatePrompt(query: ContextQuery, modules: ContextModule[]): string {
         const lines: string[] = []
+        const strictMode = query.relevanceMode === 'strict'
 
         lines.push('=== ARCHITECTURAL CONTEXT ===')
         lines.push(`Project: ${this.contract.project.name} (${this.contract.project.language})`)
@@ -425,7 +599,7 @@ export class ContextBuilder {
 
         // Include routes (API endpoints) — critical for understanding how the app works
         const routes = this.lock.routes
-        if (routes && routes.length > 0) {
+        if (!strictMode && routes && routes.length > 0) {
             lines.push('=== HTTP ROUTES ===')
             for (const r of routes) {
                 const mw = r.middlewares.length > 0 ? ` [${r.middlewares.join(', ')}]` : ''
@@ -436,7 +610,7 @@ export class ContextBuilder {
 
         // Include context files (schemas, data models) first — they define the shape
         const ctxFiles = this.lock.contextFiles
-        if (ctxFiles && ctxFiles.length > 0) {
+        if (!strictMode && ctxFiles && ctxFiles.length > 0) {
             lines.push('=== DATA MODELS & SCHEMAS ===')
             for (const cf of ctxFiles) {
                 lines.push(`--- ${cf.path} (${cf.type}) ---`)
@@ -746,4 +920,4 @@ function dedent(lines: string[]): string[] {
         const spaces = l.length - l.trimStart().length
         return l.substring(Math.min(min, spaces))
     })
-}
+}