claude-flow 3.5.72 → 3.5.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.5.72",
+  "version": "3.5.73",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

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 };
 }

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

@@ -131,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);
@@ -238,6 +242,7 @@ export const neuralTools = [
             return {
                 success: true,
                 _realEmbedding: !!realEmbeddings,
+                _embeddingSource: embeddingServiceName,
                 embeddingProvider: embeddingServiceName,
                 modelId,
                 type: modelType,
@@ -307,6 +312,7 @@ export const neuralTools = [
             return {
                 success: true,
                 _realEmbedding: !!realEmbeddings,
+                _embeddingSource: embeddingServiceName,
                 embeddingProvider: embeddingServiceName,
                 _hasStoredPatterns: storedPatterns.length > 0,
                 modelId: model?.id || 'default',
@@ -397,6 +403,7 @@ export const neuralTools = [
                 return {
                     success: true,
                     _realEmbedding: !!realEmbeddings,
+                    _embeddingSource: embeddingServiceName,
                     embeddingProvider: embeddingServiceName,
                     patternId,
                     name: pattern.name,
@@ -420,6 +427,7 @@ export const neuralTools = [
                 return {
                     _realSimilarity: true,
                     _realEmbedding: !!realEmbeddings,
+                    _embeddingSource: embeddingServiceName,
                     embeddingProvider: embeddingServiceName,
                     query,
                     results: results.map(r => ({

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;
 /**

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

@@ -60,10 +60,20 @@ function cosineSimilarity(a, b) {
     const denom = Math.sqrt(normA) * Math.sqrt(normB);
     return denom === 0 ? 0 : dotProduct / denom;
 }
+/**
+ * Whether the hash-embedding one-time warning has been emitted
+ */
+let hashEmbeddingWarned = false;
 /**
  * Generate a simple hash-based embedding (fallback when ruvector not available)
+ * WARNING: Produces deterministic vectors with NO semantic meaning.
  */
 function generateHashEmbedding(text, dimensions = 768) {
+    if (!hashEmbeddingWarned) {
+        hashEmbeddingWarned = true;
+        console.warn('[vector-db] Using hash-based pseudo-embeddings (no semantic similarity). ' +
+            'Install ruvector or @claude-flow/embeddings for real ML embeddings.');
+    }
     const embedding = new Float32Array(dimensions);
     const normalized = text.toLowerCase().trim();
     // Simple hash function
@@ -196,6 +206,10 @@ export async function createVectorDB(dimensions = 768) {
 /**
  * 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 function generateEmbedding(text, dimensions = 768) {
     if (ruvectorModule && typeof ruvectorModule.generateEmbedding === 'function') {
@@ -206,7 +220,14 @@ export function generateEmbedding(text, dimensions = 768) {
             // Fall back to hash-based embedding
         }
     }
-    return generateHashEmbedding(text, dimensions);
+    const embedding = generateHashEmbedding(text, dimensions);
+    // Tag the result so consumers can detect it came from hash fallback
+    Object.defineProperty(embedding, '_warning', {
+        value: 'hash-based pseudo-embedding — no semantic similarity',
+        enumerable: false,
+        configurable: true,
+    });
+    return embedding;
 }
 /**
  * Compute cosine similarity between two vectors

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.5.72",
+  "version": "3.5.73",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",