claude-flow 3.5.71 → 3.5.73

package/v3/@claude-flow/cli/dist/src/init/claudemd-generator.js

@@ -52,9 +52,8 @@ function concurrencyRules() {
     return `## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS
 
 - All operations MUST be concurrent/parallel in a single message
-- Use Claude Code's Task tool for spawning agents, not just MCP
-- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
-- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
+- Use Claude Code's Agent tool for spawning agents, not just MCP
+- ALWAYS spawn ALL agents in ONE message with full instructions via Agent tool
 - ALWAYS batch ALL file reads/writes/edits in ONE message
 - ALWAYS batch ALL Bash commands in ONE message`;
 }
@@ -62,9 +61,9 @@ function swarmOrchestration() {
     return `## Swarm Orchestration
 
 - MUST initialize the swarm using CLI tools when starting complex tasks
-- MUST spawn concurrent agents using Claude Code's Task tool
-- Never use CLI tools alone for execution — Task tool agents do the actual work
-- MUST call CLI tools AND Task tool in ONE message for complex work
+- MUST spawn concurrent agents using Claude Code's Agent tool
+- Never use CLI tools alone for execution — Agent tool agents do the actual work
+- MUST call CLI tools AND Agent tool in ONE message for complex work
 
 ### 3-Tier Model Routing (ADR-026)
 
@@ -74,8 +73,7 @@ function swarmOrchestration() {
 | **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) |
 | **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) |
 
-- Always check for \`[AGENT_BOOSTER_AVAILABLE]\` or \`[TASK_MODEL_RECOMMENDATION]\` before spawning agents
-- Use Edit tool directly when \`[AGENT_BOOSTER_AVAILABLE]\``;
+- For Tier 1 simple transforms, use Edit tool directly — no LLM agent needed`;
 }
 function antiDriftConfig() {
     return `## Swarm Configuration & Anti-Drift
@@ -103,11 +101,11 @@ When the user requests a complex task, spawn agents in background and WAIT:
 Bash("npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized")
 
 // STEP 2: Spawn ALL agents IN BACKGROUND in a SINGLE message
-Task({prompt: "Research requirements...", subagent_type: "researcher", run_in_background: true})
-Task({prompt: "Design architecture...", subagent_type: "system-architect", run_in_background: true})
-Task({prompt: "Implement solution...", subagent_type: "coder", run_in_background: true})
-Task({prompt: "Write tests...", subagent_type: "tester", run_in_background: true})
-Task({prompt: "Review code quality...", subagent_type: "reviewer", run_in_background: true})
+Agent("Research requirements", "Analyze codebase patterns and store findings in memory", {subagent_type: "researcher", run_in_background: true})
+Agent("Design architecture", "Design architecture based on research", {subagent_type: "system-architect", run_in_background: true})
+Agent("Implement solution", "Implement the solution following the design", {subagent_type: "coder", run_in_background: true})
+Agent("Write tests", "Write comprehensive tests for the implementation", {subagent_type: "tester", run_in_background: true})
+Agent("Review code quality", "Review code quality, security, and best practices", {subagent_type: "reviewer", run_in_background: true})
 \`\`\`
 
 ### Agent Routing
@@ -128,10 +126,10 @@ Task({prompt: "Review code quality...", subagent_type: "reviewer", run_in_backgr
 function executionRules() {
     return `## Swarm Execution Rules
 
-- ALWAYS use \`run_in_background: true\` for all agent Task calls
-- ALWAYS put ALL agent Task calls in ONE message for parallel execution
+- ALWAYS use \`run_in_background: true\` for all Agent tool calls
+- ALWAYS put ALL Agent calls in ONE message for parallel execution
 - After spawning, STOP — do NOT add more tool calls or check status
-- Never poll TaskOutput or check swarm status — trust agents to return
+- Never poll agent status repeatedly — trust agents to return
 - When agent results arrive, review ALL results before proceeding`;
 }
 function cliCommandsTable() {
@@ -407,7 +405,7 @@ npx @claude-flow/cli@latest doctor --fix
 
 ## Claude Code vs MCP Tools
 
-- **Claude Code Task tool** handles execution: agents, file ops, code generation, git
+- **Claude Code Agent tool** handles execution: agents, file ops, code generation, git
 - **MCP tools** (via ToolSearch) handle coordination: swarm, memory, hooks, routing, hive-mind
 - **CLI commands** (via Bash) are the same tools with terminal output
 - Use \`ToolSearch("keyword")\` to discover available MCP tools

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js

@@ -291,6 +291,7 @@ async function getSemanticRouter() {
             }
             nativeVectorDb = db;
             routerBackend = 'native';
+            console.log('[hooks] Semantic router initialized: native VectorDb (HNSW, 16k+ routes/s)');
             return { router: null, backend: routerBackend, native: nativeVectorDb };
         }
     }
@@ -312,10 +313,12 @@ async function getSemanticRouter() {
             });
         }
         routerBackend = 'pure-js';
+        console.log('[hooks] Semantic router initialized: pure JS (cosine, 47k routes/s)');
     }
     catch {
         semanticRouter = null;
         routerBackend = 'none';
+        console.log('[hooks] Semantic router initialized: none (no backend available)');
     }
     return { router: semanticRouter, backend: routerBackend, native: nativeVectorDb };
 }
@@ -2801,18 +2804,59 @@ export const hooksIntelligenceAttention = {
                 return { success: false, error: v.error };
         }
         let implementation = 'placeholder';
+        let embeddingSource = 'none';
         const results = [];
+        // Helper: generate query embedding, preferring real ONNX embeddings over hash fallback
+        async function getQueryEmbedding(text, dims) {
+            // Try ONNX via @claude-flow/embeddings
+            try {
+                const embeddingsModule = await import('@claude-flow/embeddings').catch(() => null);
+                if (embeddingsModule?.createEmbeddingService) {
+                    const service = embeddingsModule.createEmbeddingService({ provider: 'onnx' });
+                    const result = await service.embed(text);
+                    const arr = new Float32Array(dims);
+                    for (let i = 0; i < Math.min(dims, result.embedding.length); i++) {
+                        arr[i] = result.embedding[i];
+                    }
+                    return { embedding: arr, source: 'onnx' };
+                }
+            }
+            catch {
+                // ONNX not available, try agentic-flow
+            }
+            // Try agentic-flow embeddings
+            try {
+                const embeddingsModule = await import('@claude-flow/embeddings').catch(() => null);
+                if (embeddingsModule?.createEmbeddingService) {
+                    const service = embeddingsModule.createEmbeddingService({ provider: 'agentic-flow' });
+                    const result = await service.embed(text);
+                    const arr = new Float32Array(dims);
+                    for (let i = 0; i < Math.min(dims, result.embedding.length); i++) {
+                        arr[i] = result.embedding[i];
+                    }
+                    return { embedding: arr, source: 'onnx' };
+                }
+            }
+            catch {
+                // agentic-flow not available
+            }
+            // Hash-based fallback (deterministic but not semantic)
+            const arr = new Float32Array(dims);
+            let seed = text.split('').reduce((acc, char, i) => acc + char.charCodeAt(0) * (i + 1), 0);
+            for (let i = 0; i < dims; i++) {
+                seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+                arr[i] = (seed / 0x7fffffff) * 2 - 1;
+            }
+            return { embedding: arr, source: 'hash-fallback' };
+        }
         if (mode === 'moe') {
             // Try MoE routing
             const moe = await getMoERouter();
             if (moe) {
                 try {
-                    // Generate a simple embedding from query (hash-based for demo)
-                    const embedding = new Float32Array(384);
-                    for (let i = 0; i < 384; i++) {
-                        embedding[i] = Math.sin(query.charCodeAt(i % query.length) * (i + 1) * 0.01);
-                    }
-                    const routingResult = moe.route(embedding);
+                    const embResult = await getQueryEmbedding(query, 384);
+                    embeddingSource = embResult.source;
+                    const routingResult = moe.route(embResult.embedding);
                     for (let i = 0; i < Math.min(topK, routingResult.experts.length); i++) {
                         const expert = routingResult.experts[i];
                         results.push({
@@ -2834,13 +2878,11 @@ export const hooksIntelligenceAttention = {
             const flash = await getFlashAttention();
             if (flash) {
                 try {
-                    // Generate query/key/value embeddings
-                    const q = new Float32Array(384);
+                    const embResult = await getQueryEmbedding(query, 384);
+                    embeddingSource = embResult.source;
+                    const q = embResult.embedding;
                     const keys = [];
                     const values = [];
-                    for (let i = 0; i < 384; i++) {
-                        q[i] = Math.sin(query.charCodeAt(i % query.length) * (i + 1) * 0.01);
-                    }
                     // Generate some keys/values
                     for (let k = 0; k < topK; k++) {
                         const key = new Float32Array(384);
@@ -2883,10 +2925,13 @@ export const hooksIntelligenceAttention = {
             results,
             stats: {
                 computeTimeMs,
-                speedup: implementation.startsWith('real-') ? (mode === 'flash' ? '2.49x-7.47x' : '1.5x-3x') : null,
-                memoryReduction: implementation.startsWith('real-') ? (mode === 'flash' ? '50-75%' : '25-40%') : null,
+                implementation,
+                _embeddingSource: embeddingSource,
                 _stub: implementation === 'none',
                 _note: implementation === 'none' ? 'No attention backend available. Install @ruvector/attention for real computation.' : undefined,
+                ...(embeddingSource === 'hash-fallback' && implementation !== 'none'
+                    ? { _embeddingNote: 'Query embeddings are hash-based (not semantic). Install @claude-flow/embeddings for real ONNX embeddings.' }
+                    : {}),
             },
             implementation,
         };

package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js

@@ -25,7 +25,7 @@ try {
         realEmbeddings = { embed: (text) => rb.computeEmbedding(text) };
         embeddingServiceName = 'agentic-flow/reasoningbank';
     }
-    // Tier 2: @claude-flow/embeddings
+    // Tier 2: @claude-flow/embeddings with agentic-flow provider
     if (!realEmbeddings) {
         const embeddingsModule = await import('@claude-flow/embeddings').catch(() => null);
         if (embeddingsModule?.createEmbeddingService) {
@@ -40,6 +40,34 @@ try {
                 embeddingServiceName = 'agentic-flow';
             }
             catch {
+                // agentic-flow provider not available, try ONNX
+            }
+        }
+    }
+    // Tier 3: @claude-flow/embeddings with ONNX provider
+    if (!realEmbeddings) {
+        const embeddingsModule = await import('@claude-flow/embeddings').catch(() => null);
+        if (embeddingsModule?.createEmbeddingService) {
+            try {
+                const service = embeddingsModule.createEmbeddingService({ provider: 'onnx' });
+                realEmbeddings = {
+                    embed: async (text) => {
+                        const result = await service.embed(text);
+                        return Array.from(result.embedding);
+                    },
+                };
+                embeddingServiceName = 'onnx';
+            }
+            catch {
+                // ONNX provider not available, fall through to mock
+            }
+        }
+    }
+    // Tier 4: mock fallback (last resort — embeddings are not semantic)
+    if (!realEmbeddings) {
+        const embeddingsModule = await import('@claude-flow/embeddings').catch(() => null);
+        if (embeddingsModule?.createEmbeddingService) {
+            try {
                 const service = embeddingsModule.createEmbeddingService({ provider: 'mock' });
                 realEmbeddings = {
                     embed: async (text) => {
@@ -47,7 +75,10 @@ try {
                         return Array.from(result.embedding);
                     },
                 };
-                embeddingServiceName = 'mock';
+                embeddingServiceName = 'mock-fallback';
+            }
+            catch {
+                // No embedding service available at all
             }
         }
     }
@@ -100,7 +131,11 @@ async function generateEmbedding(text, dims = 384) {
         }
     }
     // Hash-based deterministic embedding (better than pure random for consistency)
+    // NOTE: No semantic meaning — only useful for consistent deduplication, not similarity search
     if (text) {
+        if (embeddingServiceName === 'none') {
+            embeddingServiceName = 'hash-fallback';
+        }
         const hash = text.split('').reduce((acc, char, i) => {
             return acc + char.charCodeAt(0) * (i + 1);
         }, 0);
@@ -207,6 +242,8 @@ export const neuralTools = [
             return {
                 success: true,
                 _realEmbedding: !!realEmbeddings,
+                _embeddingSource: embeddingServiceName,
+                embeddingProvider: embeddingServiceName,
                 modelId,
                 type: modelType,
                 status: model.status,
@@ -275,6 +312,8 @@ export const neuralTools = [
             return {
                 success: true,
                 _realEmbedding: !!realEmbeddings,
+                _embeddingSource: embeddingServiceName,
+                embeddingProvider: embeddingServiceName,
                 _hasStoredPatterns: storedPatterns.length > 0,
                 modelId: model?.id || 'default',
                 input: inputText,
@@ -364,6 +403,8 @@ export const neuralTools = [
                 return {
                     success: true,
                     _realEmbedding: !!realEmbeddings,
+                    _embeddingSource: embeddingServiceName,
+                    embeddingProvider: embeddingServiceName,
                     patternId,
                     name: pattern.name,
                     type: pattern.type,
@@ -386,6 +427,8 @@ export const neuralTools = [
                 return {
                     _realSimilarity: true,
                     _realEmbedding: !!realEmbeddings,
+                    _embeddingSource: embeddingServiceName,
+                    embeddingProvider: embeddingServiceName,
                     query,
                     results: results.map(r => ({
                         id: r.id,
@@ -455,6 +498,7 @@ export const neuralTools = [
                     saveNeuralStore(store);
                     return {
                         success: true, _real: true, method,
+                        embeddingProvider: embeddingServiceName,
                         patternsCompressed: totalCompressed,
                         compressionRatio: '3.92x (Int8)',
                         beforeBytes: beforeSize,
@@ -478,6 +522,7 @@ export const neuralTools = [
                 saveNeuralStore(store);
                 return {
                     success: true, _real: true, method,
+                    embeddingProvider: embeddingServiceName,
                     threshold,
                     patternsRemoved: toRemove.length,
                     patternsBefore: beforeCount,
@@ -511,6 +556,7 @@ export const neuralTools = [
                 saveNeuralStore(store);
                 return {
                     success: true, _real: true, method,
+                    embeddingProvider: embeddingServiceName,
                     patternsMerged: merged.length,
                     patternsBefore: beforeCount,
                     patternsAfter: Object.keys(store.patterns).length,
@@ -670,6 +716,7 @@ export const neuralTools = [
             const elapsed = Math.round(performance.now() - startTime);
             return {
                 success: true, _real: true, target,
+                embeddingProvider: embeddingServiceName,
                 actions,
                 patternsBefore: beforeCount,
                 patternsAfter: Object.keys(store.patterns).length,

package/v3/@claude-flow/cli/dist/src/mcp-tools/performance-tools.js

@@ -233,15 +233,15 @@ export const performanceTools = [
             const suite = input.suite || 'all';
             const iterations = input.iterations || 100;
             const warmup = input.warmup !== false;
-            // REAL benchmark functions
+            // Synthetic data benchmarks — measures actual CPU/memory throughput
             const benchmarkFunctions = {
                 memory: () => {
-                    // Real memory allocation benchmark
+                    // Synthetic data benchmark — measures actual allocation + sort throughput
                     const arr = new Array(1000).fill(0).map(() => Math.random());
                     arr.sort();
                 },
                 neural: () => {
-                    // Real computation benchmark (matrix-like operations)
+                    // Synthetic data benchmark — measures actual matrix multiplication throughput
                     const size = 64;
                     const a = Array.from({ length: size }, () => Array.from({ length: size }, () => Math.random()));
                     const b = Array.from({ length: size }, () => Array.from({ length: size }, () => Math.random()));
@@ -255,14 +255,14 @@ export const performanceTools = [
                     }
                 },
                 swarm: () => {
-                    // Real object creation and manipulation
+                    // Synthetic data benchmark — measures actual object creation + manipulation throughput
                     const agents = Array.from({ length: 10 }, (_, i) => ({ id: i, status: 'active', tasks: [] }));
                     agents.forEach(a => { for (let i = 0; i < 100; i++)
                         a.tasks.push(i); });
                     agents.sort((a, b) => a.tasks.length - b.tasks.length);
                 },
                 io: () => {
-                    // Real JSON serialization benchmark
+                    // Synthetic data benchmark — measures actual JSON serialization throughput
                     const data = { agents: Array.from({ length: 50 }, (_, i) => ({ id: i, name: `agent-${i}` })) };
                     const json = JSON.stringify(data);
                     JSON.parse(json);
@@ -313,6 +313,7 @@ export const performanceTools = [
                         avgLatency: `${avgLatencyMs.toFixed(3)}ms`,
                         memoryUsage: `${Math.abs(memoryDelta)}KB`,
                         _real: true,
+                        _dataSource: 'synthetic',
                     });
                 }
             }
@@ -330,6 +331,7 @@ export const performanceTools = [
                 : { note: 'First benchmark run - no comparison available', totalBenchmarks: allBenchmarks.length };
             return {
                 _real: true,
+                _note: 'Benchmarks use synthetic workloads to measure throughput. Results reflect actual CPU/memory performance.',
                 suite,
                 iterations,
                 warmup,

package/v3/@claude-flow/cli/dist/src/mcp-tools/system-tools.js

@@ -10,10 +10,11 @@
  */
 import { getProjectCwd } from './types.js';
 import { validateIdentifier } from './validate-input.js';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statfsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as os from 'node:os';
+import * as dns from 'node:dns';
 // Read version dynamically from package.json
 function getPackageVersion() {
     try {
@@ -332,26 +333,60 @@ export const systemTools = [
                 message: 'Neural network health not monitored',
             });
             if (input.deep) {
-                // Disk check — real free space check via os module
+                // Disk check — real free space via statfsSync (Node 18.15+)
                 {
                     const t0 = performance.now();
-                    const freeMem = os.freemem();
-                    const totalMem = os.totalmem();
-                    const elapsed = performance.now() - t0;
-                    // Use memory as a proxy; real disk check would need statvfs
-                    checks.push({
-                        name: 'disk',
-                        status: 'unknown',
-                        latency: Math.round(elapsed * 100) / 100,
-                        message: 'Disk space check not implemented — use os-level tools',
-                    });
+                    try {
+                        const stats = statfsSync(projectCwd);
+                        const totalBytes = stats.blocks * stats.bsize;
+                        const freeBytes = stats.bfree * stats.bsize;
+                        const totalGB = Math.round((totalBytes / (1024 ** 3)) * 10) / 10;
+                        const freeGB = Math.round((freeBytes / (1024 ** 3)) * 10) / 10;
+                        const freePercent = Math.round((freeBytes / totalBytes) * 100);
+                        const elapsed = performance.now() - t0;
+                        checks.push({
+                            name: 'disk',
+                            status: freePercent > 10 ? 'healthy' : 'warning',
+                            latency: Math.round(elapsed * 100) / 100,
+                            message: `${freeGB}GB free of ${totalGB}GB (${freePercent}%)`,
+                        });
+                    }
+                    catch {
+                        const elapsed = performance.now() - t0;
+                        checks.push({
+                            name: 'disk',
+                            status: 'unknown',
+                            latency: Math.round(elapsed * 100) / 100,
+                            message: 'Disk space check failed — statfsSync unavailable',
+                        });
+                    }
+                }
+                // Network — DNS resolution check with timeout
+                {
+                    const t0 = performance.now();
+                    try {
+                        await Promise.race([
+                            dns.promises.lookup('registry.npmjs.org'),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+                        ]);
+                        const elapsed = performance.now() - t0;
+                        checks.push({
+                            name: 'network',
+                            status: 'healthy',
+                            latency: Math.round(elapsed * 100) / 100,
+                            message: 'DNS resolution working',
+                        });
+                    }
+                    catch {
+                        const elapsed = performance.now() - t0;
+                        checks.push({
+                            name: 'network',
+                            status: 'warning',
+                            latency: Math.round(elapsed * 100) / 100,
+                            message: 'DNS resolution failed — check network',
+                        });
+                    }
                 }
-                // Network — cannot verify without making a request
-                checks.push({
-                    name: 'network',
-                    status: 'unknown',
-                    message: 'Network connectivity not monitored',
-                });
                 // Database — check if coordination store exists
                 {
                     const t0 = performance.now();

package/v3/@claude-flow/cli/dist/src/memory/sona-optimizer.d.ts

@@ -60,7 +60,7 @@ export interface RoutingSuggestion {
     /** Whether Q-learning was used */
     usedQLearning: boolean;
     /** Source of recommendation */
-    source: 'sona-pattern' | 'q-learning' | 'keyword-match' | 'default';
+    source: 'sona-native' | 'sona-pattern' | 'q-learning' | 'sona-keyword' | 'default';
     /** Alternative agents with scores */
     alternatives: Array<{
         agent: string;
@@ -103,9 +103,20 @@ export declare class SONAOptimizer {
     private persistencePath;
     private qLearningRouter;
     private qLearningEnabled;
+    /** Real @ruvector/sona engine — null if native not available, undefined if not yet tried */
+    private sonaEngine;
     constructor(options?: {
         persistencePath?: string;
     });
+    /**
+     * Attempt to load the native @ruvector/sona engine (once).
+     * Sets `sonaEngine` to the engine instance or null if unavailable.
+     */
+    private loadSonaEngine;
+    /**
+     * Infer an agent type string from a SONA pattern result object.
+     */
+    private inferAgentFromPattern;
     /**
      * Initialize the optimizer and load persisted state
      */
@@ -124,9 +135,16 @@ export declare class SONAOptimizer {
         keywordsExtracted: string[];
     };
     /**
-     * Get routing suggestion based on learned patterns
+     * Get routing suggestion based on learned patterns.
+     *
+     * Priority order:
+     * 1. Real @ruvector/sona native engine (if available and has matches)
+     * 2. SONA learned pattern matching (keyword overlap + confidence)
+     * 3. Q-learning router (if enabled)
+     * 4. Keyword heuristic
+     * 5. Default fallback
      */
-    getRoutingSuggestion(task: string): RoutingSuggestion;
+    getRoutingSuggestion(task: string): Promise<RoutingSuggestion>;
     /**
      * Get optimizer statistics
      */

package/v3/@claude-flow/cli/dist/src/memory/sona-optimizer.js

@@ -104,9 +104,44 @@ export class SONAOptimizer {
     persistencePath;
     qLearningRouter = null;
     qLearningEnabled = false;
+    /** Real @ruvector/sona engine — null if native not available, undefined if not yet tried */
+    sonaEngine = undefined;
     constructor(options) {
         this.persistencePath = options?.persistencePath || DEFAULT_PERSISTENCE_PATH;
     }
+    /**
+     * Attempt to load the native @ruvector/sona engine (once).
+     * Sets `sonaEngine` to the engine instance or null if unavailable.
+     */
+    async loadSonaEngine() {
+        if (this.sonaEngine !== undefined)
+            return; // already attempted
+        try {
+            const sona = await import('@ruvector/sona');
+            const EngineCtor = sona.SonaEngine || sona.default?.SonaEngine;
+            if (EngineCtor) {
+                this.sonaEngine = new EngineCtor({ mode: 'real-time' });
+            }
+            else {
+                this.sonaEngine = null;
+            }
+        }
+        catch {
+            this.sonaEngine = null; // native not available
+        }
+    }
+    /**
+     * Infer an agent type string from a SONA pattern result object.
+     */
+    inferAgentFromPattern(pattern) {
+        if (typeof pattern.agent === 'string')
+            return pattern.agent;
+        if (typeof pattern.route === 'string')
+            return pattern.route;
+        if (typeof pattern.label === 'string')
+            return pattern.label;
+        return 'coder';
+    }
     /**
      * Initialize the optimizer and load persisted state
      */
@@ -193,11 +228,43 @@ export class SONAOptimizer {
         };
     }
     /**
-     * Get routing suggestion based on learned patterns
+     * Get routing suggestion based on learned patterns.
+     *
+     * Priority order:
+     * 1. Real @ruvector/sona native engine (if available and has matches)
+     * 2. SONA learned pattern matching (keyword overlap + confidence)
+     * 3. Q-learning router (if enabled)
+     * 4. Keyword heuristic
+     * 5. Default fallback
      */
-    getRoutingSuggestion(task) {
+    async getRoutingSuggestion(task) {
+        // Priority 1: Try real @ruvector/sona native engine
+        await this.loadSonaEngine();
+        if (this.sonaEngine) {
+            try {
+                const patterns = this.sonaEngine.findPatterns(task, 3);
+                if (patterns && patterns.length > 0) {
+                    const best = patterns[0];
+                    const agent = best.route || best.agent || this.inferAgentFromPattern(best);
+                    return {
+                        agent,
+                        confidence: best.quality || 0.8,
+                        usedQLearning: false,
+                        source: 'sona-native',
+                        alternatives: patterns.slice(1).map((p) => ({
+                            agent: p.route || p.agent || this.inferAgentFromPattern(p),
+                            score: p.quality || 0.5,
+                        })),
+                        matchedKeywords: best.keywords || [],
+                    };
+                }
+            }
+            catch {
+                // Native SONA failed on this query — fall through to keyword matching
+            }
+        }
         const keywords = this.extractKeywords(task);
-        // Try SONA pattern matching first
+        // Priority 2: Try SONA learned pattern matching
         const sonaResult = this.findBestPatternMatch(keywords);
         if (sonaResult && sonaResult.confidence >= 0.6) {
             return {
@@ -209,7 +276,7 @@ export class SONAOptimizer {
                 matchedKeywords: sonaResult.matchedKeywords,
             };
         }
-        // Try Q-learning router if available
+        // Priority 3: Try Q-learning router if available
         if (this.qLearningRouter && this.qLearningEnabled) {
             try {
                 const decision = this.qLearningRouter.route(task, false);
@@ -227,19 +294,19 @@ export class SONAOptimizer {
                 // Q-learning failed, continue to fallback
             }
         }
-        // Fallback to keyword-based heuristic
+        // Priority 4: Keyword-based heuristic
         const keywordMatch = this.matchKeywordsToAgent(keywords);
         if (keywordMatch) {
             return {
                 agent: keywordMatch.agent,
                 confidence: keywordMatch.confidence,
                 usedQLearning: false,
-                source: 'keyword-match',
+                source: 'sona-keyword',
                 alternatives: this.getAlternatives(keywords, keywordMatch.agent),
                 matchedKeywords: keywordMatch.matchedKeywords,
             };
         }
-        // Default fallback
+        // Priority 5: Default fallback
         return {
             agent: 'coder',
             confidence: 0.3,

package/v3/@claude-flow/cli/dist/src/ruvector/vector-db.d.ts

@@ -52,6 +52,10 @@ export declare function createVectorDB(dimensions?: number): Promise<VectorDB>;
 /**
  * Generate an embedding for text
  * Uses ruvector if available, falls back to hash-based embedding
+ *
+ * @returns The embedding vector. When using hash fallback, the returned
+ *          Float32Array will have a `_warning` property (non-enumerable)
+ *          indicating it lacks semantic meaning.
  */
 export declare function generateEmbedding(text: string, dimensions?: number): Float32Array;
 /**