@getmikk/intent-engine 1.7.1 → 1.9.0

package/README.md

@@ -1,312 +1,125 @@
-# @getmikk/intent-engine
+# @getmikk/intent-engine
 
-> Architectural pre-flight — check if your idea is safe before writing a single line.
+> Parse developer intent, detect constraint conflicts, and find functions by meaning.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/intent-engine)](https://www.npmjs.com/package/@getmikk/intent-engine)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-`@getmikk/intent-engine` is the pre-flight check layer. You describe what you want to build in plain English — *"add a caching layer to the auth module"* — and before any code is written, the engine interprets your intent into structured objects, checks it against every architectural constraint in `mikk.json`, detects conflicts and layer violations, and generates a concrete implementation plan with which files to touch and what to create.
+Two capabilities in one package: a pre-flight pipeline that catches architectural conflicts before code is written, and a semantic search engine that finds functions by natural-language description using local vector embeddings.
 
-For AI coding agents, this is the guardrail that prevents architecturally unsafe code generation. For human developers, it's the equivalent of running your idea past a senior architect who knows every constraint in the codebase.
-
-> Part of [Mikk](../../README.md) — the codebase nervous system for AI-assisted development.
+> Part of [Mikk](../../README.md) — live architectural context for your AI agent.
 
 ---
 
-## Installation
-
-```bash
-npm install @getmikk/intent-engine
-# or
-bun add @getmikk/intent-engine
-```
-
-**Peer dependency:** `@getmikk/core`
+## Pre-flight Pipeline
 
----
+Takes a plain-English prompt describing a refactor or new feature, and returns a structured verdict before any code is written.
 
-## Quick Start
+### Usage
 
-```typescript
-import { PreflightPipeline } from '@getmikk/intent-engine'
-import { ContractReader, LockReader } from '@getmikk/core'
-
-const contract = await new ContractReader().read('./mikk.json')
-const lock = await new LockReader().read('./mikk.lock.json')
-
-const pipeline = new PreflightPipeline(contract, lock)
-const result = await pipeline.run('Add a Redis caching layer to the auth module')
-
-console.log(result.intents)       // Parsed intent objects
-console.log(result.conflicts)     // Constraint violations found
-console.log(result.suggestions)   // File-level implementation plan
-console.log(result.approved)      // true if no blocking conflicts
-```
-
----
-
-## Pipeline Architecture
-
-```
-Natural Language Prompt
-        │
-        ▼
-┌──────────────────┐
-│ IntentInterpreter │  → Intent[]
-└────────┬─────────┘
-         │
-         ▼
-┌──────────────────┐
-│ ConflictDetector  │  → ConflictResult
-└────────┬─────────┘
-         │
-         ▼
-┌──────────────────┐
-│    Suggester      │  → Suggestion[]
-└────────┬─────────┘
-         │
-         ▼
-   PreflightResult
+```bash
+mikk intent "Move user validation into a shared utils module"
+mikk intent "Extract auth logic into middleware" --json
 ```
 
----
-
-## API Reference
-
-### PreflightPipeline
-
-The main entry point — orchestrates the full interpret → detect → suggest flow.
+Or programmatically:
 
 ```typescript
 import { PreflightPipeline } from '@getmikk/intent-engine'
 
 const pipeline = new PreflightPipeline(contract, lock)
-const result = await pipeline.run('refactor the payment module to use Stripe')
-```
-
-**`PreflightResult`:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `intents` | `Intent[]` | Structured interpretation of the prompt |
-| `conflicts` | `ConflictResult` | Any constraint violations detected |
-| `suggestions` | `Suggestion[]` | Concrete implementation suggestions |
-| `approved` | `boolean` | `true` if no error-level conflicts |
-
----
-
-### IntentInterpreter
-
-Parses natural-language prompts into structured intent objects using heuristic keyword matching and fuzzy matching against the lock file's function/module inventory.
-
-```typescript
-import { IntentInterpreter } from '@getmikk/intent-engine'
+const result = await pipeline.run("Add rate limiting to all API routes")
 
-const interpreter = new IntentInterpreter(contract, lock)
-const intents = await interpreter.interpret('add input validation to the signup form')
+console.log(result.approved)     // true | false
+console.log(result.conflicts)    // constraint violations found
+console.log(result.suggestions)  // implementation suggestions with affected files
 ```
 
-**How it works:**
-
-1. **Action verb detection** — Scans for keywords like `create`, `add`, `modify`, `update`, `delete`, `remove`, `refactor`, `move`, `rename`
-2. **Target resolution** — Matches mentioned names against lock file functions, classes, modules, and files using fuzzy matching
-3. **Confidence scoring** — Higher confidence for exact matches, lower for fuzzy
-
-**`Intent`:**
-
-```typescript
-type Intent = {
-  action: 'create' | 'modify' | 'delete' | 'refactor' | 'move'
-  target: {
-    type: 'function' | 'class' | 'module' | 'file'
-    name: string
-    moduleId?: string    // Which module contains the target
-    filePath?: string    // Resolved file path
-  }
-  reason: string         // Why this intent was derived
-  confidence: number     // 0-1 confidence score
-}
-```
-
----
-
-### ConflictDetector
-
-Rule-based constraint checker that validates intents against the architectural rules in `mikk.json`.
+### What it returns
 
 ```typescript
-import { ConflictDetector } from '@getmikk/intent-engine'
-
-const detector = new ConflictDetector(contract, lock)
-const result = detector.detect(intents)
-
-if (result.hasConflicts) {
-  for (const conflict of result.conflicts) {
-    console.warn(`[${conflict.severity}] ${conflict.message}`)
-    if (conflict.suggestedFix) {
-      console.log(`  Fix: ${conflict.suggestedFix}`)
+{
+  intents: [
+    {
+      action: 'add' | 'move' | 'extract' | 'refactor' | 'remove' | ...,
+      target: { type: 'function' | 'module' | 'file', name: string, moduleId?: string },
+      confidence: number  // 0-1
+    }
+  ],
+  conflicts: {
+    hasConflicts: boolean,
+    conflicts: [
+      {
+        type: string,
+        severity: 'error' | 'warning',
+        message: string,
+        suggestedFix: string
+      }
+    ]
+  },
+  suggestions: [
+    {
+      intent: Intent,
+      implementation: string,
+      affectedFiles: string[],
+      newFiles: string[],
+      estimatedImpact: number
     }
-  }
+  ],
+  approved: boolean
 }
 ```
 
-**Constraint types checked:**
+### Constraint checks
 
-| Constraint | Description | Example |
-|-----------|-------------|---------|
-| `no-import` | Module A must not import from Module B | `"no-import": ["payments"]` in the auth module |
-| `must-use` | Module must use specified dependencies | `"must-use": ["@getmikk/core"]` |
-| `no-call` | Functions in module must not call specified targets | `"no-call": ["database.rawQuery"]` |
-| `layer` | Enforces layered architecture ordering | `"layer": 2` — can only import from lower layers |
-| `naming` | Enforces naming patterns for functions/files | `"naming": { "functions": "^handle|^use|^get" }` |
-| `max-files` | Limits the number of files in a module | `"max-files": 20` |
-
-**Additional checks:**
-- **Boundary crossing** — Detects when an intent would create a new cross-module dependency
-- **Missing dependencies** — Flags when a target module doesn't exist
-- **Ownership warnings** — Warns when modifying code owned by a different team/module
-
-**`Conflict`:**
-
-```typescript
-type Conflict = {
-  type: 'constraint-violation' | 'ownership-conflict' | 'boundary-crossing' | 'missing-dependency'
-  severity: 'error' | 'warning'
-  message: string
-  relatedIntent: Intent
-  suggestedFix?: string
-}
-```
+The pipeline checks against all 6 declared constraint types: `no-import`, `must-use`, `no-call`, `layer`, `naming`, `max-files`. If the proposed change would violate any of them, it surfaces as a conflict with a suggested fix.
 
 ---
 
-### Suggester
+## Semantic Search
 
-Generates concrete implementation suggestions based on intents and the current codebase state.
-
-```typescript
-import { Suggester } from '@getmikk/intent-engine'
+Find functions by natural-language description using local vector embeddings. No external API — runs entirely on-device.
 
-const suggester = new Suggester(contract, lock)
-const suggestions = suggester.suggest(intents)
+### Setup
 
-for (const s of suggestions) {
-  console.log(`Action: ${s.intent.action} ${s.intent.target.name}`)
-  console.log(`Affected files: ${s.affectedFiles.join(', ')}`)
-  console.log(`New files: ${s.newFiles.join(', ')}`)
-  console.log(`Impact: ${s.estimatedImpact}`)
-}
+```bash
+npm install @xenova/transformers
 ```
 
-**`Suggestion`:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `intent` | `Intent` | The original intent this suggestion addresses |
-| `affectedFiles` | `string[]` | Existing files that would need changes |
-| `newFiles` | `string[]` | Files that would need to be created |
-| `estimatedImpact` | `'low' \| 'medium' \| 'high'` | Blast radius estimate |
-| `implementation` | `string` | Natural-language implementation guidance |
-
----
-
-### SemanticSearcher
+The model (`Xenova/all-MiniLM-L6-v2`, ~22MB) downloads once to `~/.cache/huggingface`.
 
-Finds functions semantically similar to a natural-language query using local embeddings via [`@xenova/transformers`](https://github.com/xenova/transformers.js). No API key required — the model runs entirely offline.
+### Usage
 
-**Model:** `Xenova/all-MiniLM-L6-v2` (~22 MB, downloaded once to `~/.cache/huggingface` on first use)  
-**Optional peer dependency:** `@xenova/transformers >= 2`
-
-```bash
-bun add @xenova/transformers   # only needed if you use SemanticSearcher
-```
+Exposed via the MCP tool `mikk_semantic_search`, or directly:
 
 ```typescript
 import { SemanticSearcher } from '@getmikk/intent-engine'
 
-// Check if @xenova/transformers is installed before using
-if (await SemanticSearcher.isAvailable()) {
-  const searcher = new SemanticSearcher(projectRoot)
+const searcher = new SemanticSearcher(projectRoot)
 
-  // index() builds embeddings; subsequent calls are O(1) cache hits
-  await searcher.index(lock)
+// Build (or load from cache) embeddings for the lock
+await searcher.index(lock)
 
-  // search() returns the topK most relevant functions
-  const results = await searcher.search('validate JWT and return user payload', lock, 5)
-  for (const r of results) {
-    console.log(`${r.name} (${r.file}:${r.lines}) — score: ${r.score}`)
-    console.log(`  ${r.purpose}`)
-  }
-}
+// Find the 10 most semantically similar functions
+const results = await searcher.search('validate a JWT token', lock, 10)
+// Returns: [{ name, file, moduleId, purpose, lines, score }]
 ```
 
-**Cache behaviour:** Embeddings are persisted to `{projectRoot}/.mikk/embeddings.json` and fingerprinted by function count + first 20 sorted IDs. Re-indexing only re-embeds when the lock actually changes (e.g. after `mikk sync`). A cache hit costs a single disk read.
+### How it works
 
-**`SemanticMatch`:**
+1. For each function in the lock, concatenates: function name + purpose string (if present) + param names + return type
+2. Generates embeddings in batches of 64 using the pipeline
+3. Caches to `.mikk/embeddings.json` — fingerprinted by function count + first 20 sorted IDs
+4. Cache is valid until the lock changes; recomputes only what changed
+5. At search time, embeds the query and ranks all functions by cosine similarity
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Function ID (`fn:module:name`) |
-| `name` | `string` | Function name |
-| `file` | `string` | Source file path |
-| `moduleId` | `string` | Owning module |
-| `purpose` | `string` | One-line purpose from the lock |
-| `lines` | `string` | Line range, e.g. `"12-34"` |
-| `score` | `number` | Cosine similarity `[0, 1]` — higher is more relevant |
+All vectors are unit-normalized at generation time so similarity is a simple dot product.
 
-**API:**
-
-| Method | Description |
-|--------|-------------|
-| `SemanticSearcher.isAvailable()` | Returns `true` if `@xenova/transformers` is importable |
-| `new SemanticSearcher(projectRoot)` | Creates an instance scoped to a project root |
-| `.index(lock)` | Builds/loads embeddings for all functions in the lock |
-| `.search(query, lock, topK?)` | Returns top `topK` (default 10) semantically similar functions |
-
-> **Note:** Call `index()` before `search()`, otherwise `search()` throws `"Call index() before search()"`. The MCP server keeps a per-project singleton to avoid repeated model loads.
-
----
-
-## Usage with AI Agents
-
-The intent engine is designed to be called by AI coding agents as a pre-flight check:
-
-```typescript
-// In your AI agent's planning phase:
-const pipeline = new PreflightPipeline(contract, lock)
-const preflight = await pipeline.run(userPrompt)
-
-if (!preflight.approved) {
-  // Show conflicts to user, ask for confirmation
-  const errors = preflight.conflicts.conflicts.filter(c => c.severity === 'error')
-  throw new Error(`Blocked: ${errors.map(e => e.message).join('; ')}`)
-}
-
-// Use suggestions to guide implementation
-for (const suggestion of preflight.suggestions) {
-  // suggestion.affectedFiles — files to read/modify
-  // suggestion.newFiles — files to create
-  // suggestion.implementation — guidance text
-}
-```
-
----
-
-## Types
+### Check availability
 
 ```typescript
-import type {
-  Intent,
-  Conflict,
-  ConflictResult,
-  Suggestion,
-  PreflightResult,
-  AIProviderConfig,
-} from '@getmikk/intent-engine'
+const available = await SemanticSearcher.isAvailable()
+// true if @xenova/transformers is installed and importable
 ```
 
----
-
-## License
-
-[Apache-2.0](../../LICENSE)
+The MCP server calls `isAvailable()` before registering the tool — if the package is missing, the tool is not exposed and the response explains how to install it.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/intent-engine",
-    "version": "1.7.1",
+    "version": "1.9.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -21,16 +21,9 @@
         "dev": "tsc --watch"
     },
     "dependencies": {
-        "@getmikk/core": "^1.7.1",
-        "zod": "^3.22.0"
-    },
-    "peerDependencies": {
-        "@xenova/transformers": ""
-    },
-    "peerDependenciesMeta": {
-        "@xenova/transformers": {
-            "optional": true
-        }
+        "@getmikk/core": "^1.9.0",
+        "zod": "^3.22.0",
+        "@xenova/transformers": "^2.17.2"
     },
     "devDependencies": {
         "@types/bun": "^1.3.10",

package/src/conflict-detector.ts

@@ -106,7 +106,7 @@ export class ConflictDetector {
         }
     }
 
-    // ── Constraint Classification & Checking ─────────────────────
+    // --- Constraint Classification & Checking ---------------------
 
     private classifyConstraint(text: string): ConstraintType {
         const lower = text.toLowerCase()

package/src/decision-engine.ts

@@ -0,0 +1,69 @@
+import type { ImpactResult, MikkContract } from '@getmikk/core'
+import type { DecisionResult, DecisionStatus } from './types.js'
+
+/**
+ * DecisionEngine — the "Brain" of Mikk 2.0.
+ * Evaluates quantitative impact analysis against project policies.
+ */
+export class DecisionEngine {
+    constructor(private contract: MikkContract) {}
+
+    /**
+     * Evaluate an impact result against the defined policies.
+     */
+    evaluate(impact: ImpactResult): DecisionResult {
+        const policy = {
+            maxRiskScore: this.contract.policies?.maxRiskScore ?? 70,
+            maxImpactNodes: this.contract.policies?.maxImpactNodes ?? 10,
+            protectedModules: this.contract.policies?.protectedModules ?? [],
+            enforceStrictBoundaries: this.contract.policies?.enforceStrictBoundaries ?? false,
+        };
+        const reasons: string[] = [];
+        let status: DecisionStatus = 'APPROVED';
+
+        const maxRisk = impact.riskScore;
+        const impactCount = impact.impacted.length;
+
+        // 1. Check absolute risk threshold
+        if (maxRisk >= 90) {
+            status = 'BLOCKED';
+            reasons.push(`Critical risk detected (${maxRisk}/100). Policy strictly blocks changes exceeding 90 risk.`);
+        } else if (maxRisk > policy.maxRiskScore) {
+            status = 'WARNING';
+            reasons.push(`High risk (${maxRisk}) exceeds policy threshold of ${policy.maxRiskScore}.`);
+        }
+
+        // 2. Check impact scale
+        if (impactCount > policy.maxImpactNodes) {
+             status = status === 'BLOCKED' ? 'BLOCKED' : 'WARNING';
+             reasons.push(`Impact spread (${impactCount} symbols) exceeds propagation limit of ${policy.maxImpactNodes}.`);
+        }
+
+        // 3. Check protected modules
+        const touchedProtectedModules = impact.allImpacted
+            .filter(node => node.risk === 'CRITICAL' || node.risk === 'HIGH')
+            .map(node => {
+                return policy.protectedModules.find(pm => node.file.toLowerCase().includes(pm.toLowerCase()));
+            })
+            .filter((m): m is string => !!m);
+
+        const uniqueProtected = [...new Set(touchedProtectedModules)];
+        if (uniqueProtected.length > 0) {
+            status = status === 'BLOCKED' ? 'BLOCKED' : 'WARNING';
+            reasons.push(`Change affects protected modules: ${uniqueProtected.join(', ')}.`);
+        }
+
+        // 4. Force BLOCKED for critical cross-boundary impacts if enforcement is on
+        if (policy.enforceStrictBoundaries && impact.classified.critical.length > 0) {
+            status = 'BLOCKED';
+            reasons.push(`Strict boundary enforcement: ${impact.classified.critical.length} critical cross-module impact(s) detected.`);
+        }
+
+        return {
+            status,
+            reasons,
+            riskScore: maxRisk,
+            impactNodes: impactCount
+        };
+    }
+}

package/src/explanation-engine.ts

@@ -0,0 +1,80 @@
+import type { ImpactResult } from '@getmikk/core'
+import type { DecisionResult, Explanation } from './types.js'
+
+/**
+ * ExplanationEngine — generates human-readable reasoning for code modification decisions.
+ * Explains WHY a change is safe or risky based on the quantitative graph analysis.
+ */
+export class ExplanationEngine {
+    /**
+     * Generate an explanation for the decision and impact.
+     */
+    explain(impact: ImpactResult, decision: DecisionResult): Explanation {
+        const summary = this.getSummary(decision);
+        const details = this.getDetails(impact, decision);
+        const riskBreakdown = this.getRiskBreakdown(impact);
+
+        return {
+            summary,
+            details,
+            riskBreakdown
+        };
+    }
+
+    private getSummary(decision: DecisionResult): string {
+        switch (decision.status) {
+            case 'APPROVED': return 'This change is safe and conforms to project policies.';
+            case 'WARNING': return 'Change detected with non-trivial impact — proceed with caution.';
+            case 'BLOCKED': return 'MODIFICATION BLOCKED: This change violates safety or architectural policies.';
+        }
+    }
+
+    private getDetails(impact: ImpactResult, decision: DecisionResult): string[] {
+        const details: string[] = [];
+
+        if (impact.allImpacted.length === 0) {
+            details.push('No downstream symbols are affected by this change.');
+        } else {
+            details.push(`Affects ${impact.allImpacted.length} symbols across ${this.countModules(impact)} modules.`);
+            details.push(`Maximum risk score is ${impact.riskScore}/100.`);
+        }
+
+        if (impact.classified.critical.length > 0) {
+            details.push(`⚠ Critical: affects ${impact.classified.critical.length} symbols in separate modules.`);
+        }
+
+        if (decision.reasons.length > 0) {
+            decision.reasons.forEach(r => details.push(`Policy: ${r}`));
+        }
+
+        return details;
+    }
+
+    private getRiskBreakdown(impact: ImpactResult): { symbol: string; reason: string; score: number }[] {
+        // Return top 3 riskiest affected symbols
+        return impact.allImpacted
+            .sort((a, b) => b.riskScore - a.riskScore)
+            .slice(0, 3)
+            .map(node => ({
+                symbol: node.label,
+                score: node.riskScore,
+                reason: this.getRiskReason(node.riskScore)
+            }));
+    }
+
+    private getRiskReason(score: number): string {
+        if (score >= 90) return 'Direct critical dependency in protected module';
+        if (score >= 80) return 'Large downstream reach (potential side effects)';
+        if (score >= 60) return 'Cross-module propagation';
+        return 'Standard functional dependency';
+    }
+
+    private countModules(impact: ImpactResult): number {
+        const modules = new Set(impact.allImpacted.map(n => {
+            // Heuristic to extract module from file path if moduleId not present
+            const parts = n.file.split('/');
+            return parts.length > 1 ? parts[0] : 'root';
+        }));
+        return modules.size;
+    }
+}

package/src/preflight.ts

@@ -1,18 +1,23 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
+import { 
+    MikkContract, MikkLock, GraphBuilder, ImpactAnalyzer 
+} from '@getmikk/core'
 import { IntentInterpreter } from './interpreter.js'
 import { ConflictDetector } from './conflict-detector.js'
 import { Suggester } from './suggester.js'
-import type { PreflightResult } from './types.js'
+import { DecisionEngine } from './decision-engine.js'
+import { ExplanationEngine } from './explanation-engine.js'
+import type { PreflightResult, DecisionResult, Explanation } from './types.js'
 
 /**
  * PreflightPipeline — orchestrates the full intent pipeline:
- * interpret → conflict-detect → suggest.
- * Single function call for the CLI.
+ * interpret → analyze (impact/risk) → decide → explain → conflict-detect → suggest.
  */
 export class PreflightPipeline {
     private interpreter: IntentInterpreter
     private conflictDetector: ConflictDetector
     private suggester: Suggester
+    private decisionEngine: DecisionEngine
+    private explanationEngine: ExplanationEngine
 
     constructor(
         private contract: MikkContract,
@@ -21,6 +26,8 @@ export class PreflightPipeline {
         this.interpreter = new IntentInterpreter(contract, lock)
         this.conflictDetector = new ConflictDetector(contract, lock)
         this.suggester = new Suggester(contract, lock)
+        this.decisionEngine = new DecisionEngine(contract)
+        this.explanationEngine = new ExplanationEngine()
     }
 
     /** Run the full preflight pipeline */
@@ -28,11 +35,32 @@ export class PreflightPipeline {
         // 1. Interpret prompt into structured intents
         const intents = await this.interpreter.interpret(prompt)
 
-        // 2. Check for conflicts
+        // 2. Perform Quantitative Impact Analysis
+        const graph = new GraphBuilder().buildFromLock(this.lock)
+        const analyzer = new ImpactAnalyzer(graph)
+        
+        // Find node IDs for the intents
+        const targetIds: string[] = []
+        for (const intent of intents) {
+            // Find better match by checking both name and type
+            // In Mikk 2.0, we have IDs like fn:src/file.ts:name
+            const matchedNode = [...graph.nodes.values()].find(n => 
+                n.name.toLowerCase() === intent.target.name.toLowerCase() && 
+                (intent.target.type === 'function' ? n.type === 'function' : true)
+            )
+            if (matchedNode) targetIds.push(matchedNode.id)
+        }
+
+        const impact = analyzer.analyze(targetIds)
+
+        // 3. Decide and Explain
+        const decision = this.decisionEngine.evaluate(impact)
+        const explanation = this.explanationEngine.explain(impact, decision)
+
+        // 4. Check for Static Conflicts
         const conflicts = this.conflictDetector.detect(intents)
 
-        // 3. Low-confidence rejection: if the best intent has very low confidence,
-        //    add a warning so the AI doesn't blindly proceed
+        // 5. Low-confidence rejection / Supplemental warnings
         const maxConfidence = intents.length > 0
             ? Math.max(...intents.map(i => i.confidence))
             : 0
@@ -40,20 +68,22 @@ export class PreflightPipeline {
             conflicts.conflicts.push({
                 type: 'low-confidence',
                 severity: 'warning',
-                message: `Low confidence (${(maxConfidence * 100).toFixed(0)}%) — the intent could not be reliably matched to existing code. The suggestion may be inaccurate.`,
+                message: `Low confidence (${(maxConfidence * 100).toFixed(0)}%) — matching to existing code was ambiguous.`,
                 relatedIntent: intents[0],
-                suggestedFix: 'Be more specific about the function or module name in your prompt.',
+                suggestedFix: 'Be more specific about the function or module name.',
             })
         }
 
-        // 4. Generate suggestions
+        // 6. Generate implementation suggestions
         const suggestions = this.suggester.suggest(intents)
 
         return {
             intents,
             conflicts,
             suggestions,
-            approved: !conflicts.hasConflicts && maxConfidence >= 0.4,
+            decision,
+            explanation,
+            approved: !conflicts.hasConflicts && decision.status !== 'BLOCKED' && maxConfidence >= 0.4,
         }
     }
 }

package/src/semantic-searcher.ts

@@ -5,7 +5,7 @@ import type { MikkLock } from '@getmikk/core'
 interface EmbeddingCache {
     lockFingerprint: string
     model: string
-    embeddings: Record<string, number[]> // fnId → unit-normed vector
+    embeddings: Record<string, number[]> // fnId -> unit-normed vector
 }
 
 export interface SemanticMatch {
@@ -19,7 +19,7 @@ export interface SemanticMatch {
 }
 
 /**
- * SemanticSearcher — finds functions semantically similar to a natural-language
+ * SemanticSearcher -- finds functions semantically similar to a natural-language
  * query using local embeddings via @xenova/transformers.
  *
  * Model: Xenova/all-MiniLM-L6-v2 (~22 MB, downloads once to ~/.cache/huggingface).
@@ -57,12 +57,12 @@ export class SemanticSearcher {
 
     /**
      * Build (or load from cache) embeddings for every function in the lock.
-     * Safe to call on every MCP request — cache hit is O(1) disk read.
+     * Safe to call on every MCP request -- cache hit is O(1) disk read.
      */
     async index(lock: MikkLock): Promise<void> {
         const fingerprint = lockFingerprint(lock)
 
-        // ── Cache hit ──────────────────────────────────────────────────────
+        // -- Cache hit --------------------------------------------------------
         try {
             const raw = await fs.readFile(this.cachePath, 'utf-8')
             const cached: EmbeddingCache = JSON.parse(raw)
@@ -77,9 +77,9 @@ export class SemanticSearcher {
                 this.cache = cached
                 return
             }
-        } catch { /* miss or corrupt — rebuild */ }
+        } catch { /* miss or corrupt -- rebuild */ }
 
-        // ── Empty lock fast-path — nothing to embed ────────────────────────
+        // -- Empty lock fast-path -- nothing to embed ------------------------
         const fns = Object.values(lock.functions)
         if (fns.length === 0) {
             this.cache = { lockFingerprint: fingerprint, model: SemanticSearcher.MODEL, embeddings: {} }
@@ -154,7 +154,7 @@ export class SemanticSearcher {
     }
 }
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// --- Helpers -----------------------------------------------------------------
 
 /** Lightweight fingerprint: function count + first 20 sorted IDs */
 function lockFingerprint(lock: MikkLock): string {

package/src/types.ts

@@ -38,6 +38,25 @@ export interface Suggestion {
     implementation: string
 }
 
+export type DecisionStatus = 'APPROVED' | 'WARNING' | 'BLOCKED';
+
+export interface DecisionResult {
+    status: DecisionStatus
+    reasons: string[]
+    riskScore: number
+    impactNodes: number
+}
+
+export interface Explanation {
+    summary: string
+    details: string[]
+    riskBreakdown: {
+        symbol: string
+        reason: string
+        score: number
+    }[]
+}
+
 /** Configuration for the AI provider */
 export interface AIProviderConfig {
     provider: 'anthropic' | 'openai' | 'local'
@@ -50,5 +69,7 @@ export interface PreflightResult {
     intents: Intent[]
     conflicts: ConflictResult
     suggestions: Suggestion[]
+    decision: DecisionResult
+    explanation: Explanation
     approved: boolean
 }

package/src/xeno-transformers.d.ts

@@ -1,7 +1,7 @@
 /**
- * Ambient stub for the optional peer dependency @xenova/transformers.
- * The real types are only available when the package is installed.
- * We use dynamic import + `any` everywhere so this stub is sufficient.
+ * Ambient stub for the direct dependency @xenova/transformers.
+ * Provides basic types for the library and documents that SemanticSearcher.isAvailable() 
+ * is used to test runtime loadability (e.g. WASM support) for graceful error handling.
  */
 declare module '@xenova/transformers' {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/tests/semantic-searcher.test.ts

@@ -1,6 +1,9 @@
 import { describe, test, expect, beforeAll } from 'bun:test'
 import { SemanticSearcher } from '../src/semantic-searcher'
 import type { MikkLock } from '@getmikk/core'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as fs from 'node:fs/promises'
 
 // ── Minimal mock lock ─────────────────────────────────────────────────────────
 const mockLock: MikkLock = {
@@ -72,9 +75,10 @@ describe('SemanticSearcher', () => {
 
     describe('with indexed lock', () => {
         beforeAll(async () => {
-            searcher = new SemanticSearcher('/tmp/mikk-test-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-test-' + Math.random().toString(36).slice(2))
+            searcher = new SemanticSearcher(uniquePath)
             await searcher.index(mockLock)
-        }, 60_000) // model download can take time on first run
+        }, 120_000) // Increase timeout for CI model download
 
         test('returns results for any query', async () => {
             const results = await searcher.search('authenticate user', mockLock, 4)
@@ -154,25 +158,30 @@ describe('SemanticSearcher', () => {
                 ...mockLock,
                 functions: { ...mockLock.functions, 'fn:new:brandNewFn': newFn },
             }
-            const freshSearcher = new SemanticSearcher('/tmp/mikk-reindex-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-reindex-' + Math.random().toString(36).slice(2))
+            const freshSearcher = new SemanticSearcher(uniquePath)
             await freshSearcher.index(changedLock) // fingerprint differs → full recompute
             const results = await freshSearcher.search('unique purpose', changedLock, 5)
             expect(results.some(r => r.name === 'brandNewFn')).toBe(true)
-        }, 30_000)
+            await fs.rm(uniquePath, { recursive: true, force: true })
+        }, 120_000)
     })
 
     describe('edge cases', () => {
         test('search() before index() throws', async () => {
-            const fresh = new SemanticSearcher('/tmp/mikk-never-indexed-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-never-' + Math.random().toString(36).slice(2))
+            const fresh = new SemanticSearcher(uniquePath)
             await expect(fresh.search('query', mockLock)).rejects.toThrow('Call index() before search()')
         })
 
         test('empty lock: index() and search() succeed, return empty array', async () => {
             const emptyLock: MikkLock = { ...mockLock, functions: {} }
-            const s = new SemanticSearcher('/tmp/mikk-empty-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-empty-' + Math.random().toString(36).slice(2))
+            const s = new SemanticSearcher(uniquePath)
             await s.index(emptyLock)
             const results = await s.search('anything', emptyLock, 5)
             expect(results).toEqual([])
-        })
+            await fs.rm(uniquePath, { recursive: true, force: true })
+        }, 120_000)
     })
 })