Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(hooks): route no longer reports its highest confidence when nothing matched (#3567)

ruv45a3b2ddd237
diff --git a/v3/@claude-flow/cli/__tests__/hooks-route-no-match-3567.test.ts b/v3/@claude-flow/cli/__tests__/hooks-route-no-match-3567.test.ts
new file mode 100644
index 0000000000..e850d7facb
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/hooks-route-no-match-3567.test.ts
@@ -0,0 +1,129 @@
+/**
+ * #3567 — hooks_route reported its highest confidence (0.7) exactly when
+ * nothing matched: blank, punctuation-only and non-English tasks all came back
+ * `coder` at 70%, above a correctly routed "deploy the release to production"
+ * (62%). A no-match result must rank below every real match and say so.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Keep hooks_route on the local path: the AgentDB pre-route answers "nothing".
+vi.mock('../src/memory/memory-bridge.js', () => ({ bridgeRouteTask: vi.fn(async () => null) }));
+
+import {
+ NO_MATCH_CONFIDENCE,
+ hooksExplain,
+ hooksRoute,
+ resetSemanticRouterForTests,
+ suggestAgentsForTask,
+} from '../src/mcp-tools/hooks-tools.js';
+import { clearRouterEmbedderCache } from '../src/ruvector/router-embedder.js';
+
+const DEPLOY_CONFIDENCE_OBSERVED = 0.62; // Martin's measurement for the correctly routed deploy task
+const NO_MATCH_TASKS = [' ', '...', '修复登录崩溃'];
+
+type RouteOut = {
+ matched?: boolean;
+ reason?: string;
+ note?: string;
+ matchedPattern: string;
+ primaryAgent: { type: string; confidence: number; reason: string };
+ alternativeAgents: Array<{ confidence: number }>;
+ estimatedMetrics: { successProbability: number | null };
+};
+const route = (task: string) => hooksRoute.handler({ task }) as Promise<RouteOut>;
+
+const ENV_KEYS = ['CLAUDE_FLOW_ROUTER_EMBEDDER', 'CLAUDE_FLOW_DISABLE_NATIVE_ROUTER', 'CLAUDE_FLOW_ROUTER_TYPESAFE'] as const;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+ for (const k of ENV_KEYS) savedEnv[k] = process.env[k];
+ process.env.CLAUDE_FLOW_DISABLE_NATIVE_ROUTER = '1';
+ process.env.CLAUDE_FLOW_ROUTER_EMBEDDER = 'hash';
+ delete process.env.CLAUDE_FLOW_ROUTER_TYPESAFE;
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+ clearRouterEmbedderCache();
+ resetSemanticRouterForTests();
+});
+
+afterEach(() => {
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] === undefined) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ vi.restoreAllMocks();
+});
+
+describe('#3567 suggestAgentsForTask no-match default', () => {
+ it.each(NO_MATCH_TASKS)('%j is an explicit no-match below every real match', (task) => {
+ const r = suggestAgentsForTask(task);
+ expect(r.matched).toBe(false);
+ expect(r.reason).toBe('no-match-default');
+ expect(r.confidence).toBe(NO_MATCH_CONFIDENCE);
+ expect(r.confidence).toBeLessThan(DEPLOY_CONFIDENCE_OBSERVED);
+ expect(r.agents.length).toBeGreaterThan(0); // callers keep a default list
+ });
+
+ it('says why a non-English task did not match', () => {
+ expect(suggestAgentsForTask('修复登录崩溃').note).toMatch(/English-only/);
+ });
+
+ it('says why a task with no words did not match', () => {
+ expect(suggestAgentsForTask(' ').note).toMatch(/no words/);
+ expect(suggestAgentsForTask('...').note).toMatch(/no words/);
+ });
+
+ it.each([
+ ['deploy the release to production', 'devops', 0.85],
+ ['fix the crash on startup', 'coder', 0.85],
+ ['write unit tests for the parser', 'tester', 0.95],
+ ])('real match %j is unchanged (%s @ %s)', (task, agent, confidence) => {
+ const r = suggestAgentsForTask(task);
+ expect(r.matched).toBe(true);
+ expect(r.agents[0]).toBe(agent);
+ expect(r.confidence).toBe(confidence);
+ expect(r.confidence).toBeGreaterThan(NO_MATCH_CONFIDENCE);
+ });
+});
+
+describe('#3567 hooks_route surfaces the no-match marker', () => {
+ it.each(NO_MATCH_TASKS)('%j routes as no-match with a low confidence', async (task) => {
+ const r = await route(task);
+ expect(r.matched).toBe(false);
+ expect(r.reason).toBe('no-match-default');
+ expect(r.matchedPattern).toBe('no-match-default');
+ expect(r.primaryAgent.confidence).toBeLessThan(DEPLOY_CONFIDENCE_OBSERVED);
+ expect(r.primaryAgent.reason).toMatch(/Nothing matched/);
+ expect(r.estimatedMetrics.successProbability).toBeNull();
+ for (const alt of r.alternativeAgents) expect(alt.confidence).toBeGreaterThanOrEqual(0);
+ });
+
+ it('a real task still routes as a match above the no-match confidence', async () => {
+ const r = await route('deploy the release to production');
+ expect(r.matched).toBe(true);
+ expect(r.reason).toBeUndefined();
+ expect(r.primaryAgent.confidence).toBeGreaterThan(NO_MATCH_CONFIDENCE);
+ expect(r.estimatedMetrics.successProbability).not.toBeNull();
+ });
+
+ it('a blank task outranks nothing: it scores below a correctly routed task', async () => {
+ const blank = await route(' ');
+ const deploy = await route('deploy the release to production');
+ expect(blank.primaryAgent.confidence).toBeLessThan(deploy.primaryAgent.confidence);
+ });
+});
+
+describe('#3567 hooks_explain does not explain a match that did not happen', () => {
+ it('reports no-match for a blank task', async () => {
+ const r = (await hooksExplain.handler({ task: ' ' })) as {
+ matched: boolean;
+ reason?: string;
+ explanation: string;
+ decision: { confidence: number; reasoning: string[] };
+ };
+ expect(r.matched).toBe(false);
+ expect(r.reason).toBe('no-match-default');
+ expect(r.explanation).not.toMatch(/contains keywords that match/);
+ expect(r.decision.reasoning.join(' ')).not.toMatch(/threshold met/);
+ expect(r.decision.confidence).toBe(NO_MATCH_CONFIDENCE);
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/router-wordboundary.test.ts b/v3/@claude-flow/cli/__tests__/router-wordboundary.test.ts
index 9b62488017..731c18e1dd 100644
--- a/v3/@claude-flow/cli/__tests__/router-wordboundary.test.ts
+++ b/v3/@claude-flow/cli/__tests__/router-wordboundary.test.ts
@@ -30,7 +30,7 @@ import { fileURLToPath } from 'url';
vi.spyOn(console, 'log').mockImplementation(() => {});
import { generateAgentRouter } from '../src/init/helpers-generator.js';
-import { suggestAgentsForTask } from '../src/mcp-tools/hooks-tools.js';
+import { NO_MATCH_CONFIDENCE, suggestAgentsForTask } from '../src/mcp-tools/hooks-tools.js';
const require = createRequire(import.meta.url);
const here = fileURLToPath(new URL('.', import.meta.url));
@@ -114,7 +114,9 @@ describe('hooks-tools suggestAgentsForTask word boundaries', () => {
])('"%s" falls through to the default instead of a substring hit', (task) => {
const r = suggestAgentsForTask(task);
expect(r.agents).toEqual(DEFAULT);
- expect(r.confidence).toBe(0.7);
+ // #3567: the fall-through is an explicit no-match, not a 0.7 "match".
+ expect(r.matched).toBe(false);
+ expect(r.confidence).toBe(NO_MATCH_CONFIDENCE);
});
it.each([
diff --git a/v3/@claude-flow/cli/src/commands/hooks.ts b/v3/@claude-flow/cli/src/commands/hooks.ts
index 302c4833f8..978e4cb8ae 100644
--- a/v3/@claude-flow/cli/src/commands/hooks.ts
+++ b/v3/@claude-flow/cli/src/commands/hooks.ts
@@ -827,7 +827,7 @@ const routeCommand: Command = {
const parallel = Math.max(2, parallelRaw);
const consensus = (ctx.flags.consensus as string) || 'majority-vote';
- if (!task) {
+ if (!task || !task.trim()) {
output.printError('Task description is required. Use --task or -t flag.');
return { success: false, exitCode: 1 };
}
@@ -845,6 +845,9 @@ const routeCommand: Command = {
throughput: string;
};
matchedPattern?: string;
+ /** #3567: false when nothing matched; the agent shown is only a default. */
+ matched?: boolean;
+ note?: string;
semanticMatches?: Array<{
pattern: string;
score: number;
@@ -860,7 +863,7 @@ const routeCommand: Command = {
reason: string;
}>;
estimatedMetrics: {
- successProbability: number;
+ successProbability: number | null;
estimatedDuration: string;
complexity: 'low' | 'medium' | 'high';
};
@@ -939,13 +942,14 @@ const routeCommand: Command = {
}
output.writeln();
+ const noMatch = result.matched === false;
output.printBox(
[
`Agent: ${output.highlight(result.primaryAgent.type)}`,
- `Confidence: ${(result.primaryAgent.confidence * 100).toFixed(1)}%`,
+ `Confidence: ${(result.primaryAgent.confidence * 100).toFixed(1)}%${noMatch ? ' (no match: default only)' : ''}`,
`Reason: ${result.primaryAgent.reason}`
].join('\n'),
- 'Primary Recommendation'
+ noMatch ? 'Default Suggestion (nothing matched)' : 'Primary Recommendation'
);
if (result.alternativeAgents.length > 0) {
@@ -965,7 +969,9 @@ const routeCommand: Command = {
output.writeln();
output.writeln(output.bold('Estimated Metrics'));
output.printList([
- `Success Probability: ${(result.estimatedMetrics.successProbability * 100).toFixed(1)}%`,
+ `Success Probability: ${result.estimatedMetrics.successProbability === null
+ ? 'unknown (nothing matched)'
+ : `${(result.estimatedMetrics.successProbability * 100).toFixed(1)}%`}`,
`Estimated Duration: ${result.estimatedMetrics.estimatedDuration}`,
`Complexity: ${result.estimatedMetrics.complexity.toUpperCase()}`
]);
diff --git a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
index 1e608ac6f6..c3ab3ba854 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
@@ -893,12 +893,53 @@ const KEYWORD_MATCHERS = Object.entries(KEYWORD_PATTERNS).map(([keyword, result]
return { regex: new RegExp(`\\b${body}\\b`, 'i'), result };
});
+/**
+ * Confidence for a task nothing matched (#3567). It must rank below every real
+ * signal: keyword hits are >= 0.8, learned outcomes >= 0.7, and a semantic
+ * match is only eligible above 0.4. Matches the helper router's 0.3 fall-through.
+ */
+export const NO_MATCH_CONFIDENCE = 0.3;
+
+export interface TaskAgentSuggestion {
+ agents: string[];
+ confidence: number;
+ /** false when no keyword or learned pattern matched; the agents are a default, not a decision. */
+ matched: boolean;
+ reason?: 'no-match-default';
+ note?: string;
+}
+
+/** True when the task has at least one letter or digit in any script. */
+export function hasRoutableText(task: string): boolean {
+ return /[\p{L}\p{N}]/u.test(task);
+}
+
+// Keyword matchers are English regexes; letters outside Latin script can never hit them.
+const NON_LATIN_LETTER = /(?![A-Za-zÀ-ɏ])\p{L}/u;
+
+function noMatchNote(task: string): string {
+ if (!hasRoutableText(task)) return 'Task has no words to match.';
+ if (NON_LATIN_LETTER.test(task)) {
+ return 'Keyword matchers are English-only, so non-English text cannot match them.';
+ }
+ return 'No keyword or learned pattern matched.';
+}
+
/** Exported for tests. */
-export function suggestAgentsForTask(task: string): { agents: string[]; confidence: number } {
+export function suggestAgentsForTask(task: string): TaskAgentSuggestion {
+ const noMatch = (): TaskAgentSuggestion => ({
+ agents: ['coder', 'researcher', 'tester'],
+ confidence: NO_MATCH_CONFIDENCE,
+ matched: false,
+ reason: 'no-match-default',
+ note: noMatchNote(task),
+ });
+ if (!hasRoutableText(task)) return noMatch();
+
// Check static keyword patterns first
for (const { regex, result } of KEYWORD_MATCHERS) {
if (regex.test(task)) {
- return result;
+ return { ...result, matched: true };
}
}
@@ -920,12 +961,11 @@ export function suggestAgentsForTask(task: string): { agents: string[]; confiden
// Require at least 2 keyword overlap to prevent false positives
if (bestAgent && bestOverlap >= 2) {
- return { agents: [bestAgent], confidence: Math.min(0.6 + bestOverlap * 0.05, 0.85) };
+ return { agents: [bestAgent], confidence: Math.min(0.6 + bestOverlap * 0.05, 0.85), matched: true };
}
}
- // Default fallback
- return { agents: ['coder', 'researcher', 'tester'], confidence: 0.7 };
+ return noMatch();
}
function assessCommandRisk(command: string): { risk: string; level: number; warnings: string[] } {
@@ -1387,6 +1427,7 @@ async function routeTaskLocal(
let agents: string[];
let confidence: number;
let matchedPattern = '';
+ let noMatchDetail: string | null = null;
// Both static and learned patterns are gated on the same similarity
// score. Learned patterns additionally require support/reliability as a
@@ -1395,7 +1436,9 @@ async function routeTaskLocal(
// (#2864: a 25pp higher threshold made a top-scoring learned-researcher
// match at 0.57 lose to a static match at 0.52, discarding the learned
// store's output on the majority of routes).
- const eligibleSemantic = semanticResult.find((match) => {
+ // A task with no letters or digits has nothing for the embedder to mean;
+ // any similarity it scores is noise, so it never becomes a semantic match.
+ const eligibleSemantic = !hasRoutableText(task) ? undefined : semanticResult.find((match) => {
if (match.score <= 0.4) return false;
const learned = match.intent.startsWith('learned-') || match.metadata.source === 'learned';
if (!learned) return true;
@@ -1412,9 +1455,15 @@ async function routeTaskLocal(
const suggestion = suggestAgentsForTask(task);
agents = suggestion.agents;
confidence = suggestion.confidence;
- matchedPattern = 'keyword-fallback';
routingMethod = 'keyword';
- backendInfo = 'keyword matching';
+ if (suggestion.matched) {
+ matchedPattern = 'keyword-fallback';
+ backendInfo = 'keyword matching';
+ } else {
+ matchedPattern = 'no-match-default';
+ backendInfo = 'keyword matching (no match)';
+ noMatchDetail = suggestion.note ?? 'No pattern matched.';
+ }
}
// Determine complexity
@@ -1434,6 +1483,9 @@ async function routeTaskLocal(
throughput: routingLatencyMs > 0 ? `${Math.round(1000 / routingLatencyMs)} routes/s` : 'N/A',
},
matchedPattern,
+ // #3567: callers branch on `matched`; a no-match result is a default, not a decision.
+ matched: noMatchDetail === null,
+ ...(noMatchDetail !== null ? { reason: 'no-match-default', note: noMatchDetail } : {}),
semanticMatches: semanticResult.slice(0, 3).map(r => ({
pattern: r.intent,
score: Math.round(r.score * 100) / 100,
@@ -1443,15 +1495,18 @@ async function routeTaskLocal(
confidence: Math.round(confidence * 100) / 100,
reason: routingMethod.startsWith('semantic')
? `Semantic similarity to "${matchedPattern}" pattern (${Math.round(confidence * 100)}%)`
- : `Task contains keywords matching ${agents[0]} specialization`,
+ : noMatchDetail !== null
+ ? `Nothing matched; default suggestion only. ${noMatchDetail}`
+ : `Task contains keywords matching ${agents[0]} specialization`,
},
alternativeAgents: agents.slice(1).map((agent, i) => ({
type: agent,
- confidence: Math.round((confidence - (0.1 * (i + 1))) * 100) / 100,
- reason: `Alternative agent for ${agent} capabilities`,
+ confidence: Math.max(0, Math.round((confidence - (0.1 * (i + 1))) * 100) / 100),
+ reason: noMatchDetail !== null ? 'Default suggestion (nothing matched)' : `Alternative agent for ${agent} capabilities`,
})),
estimatedMetrics: {
- successProbability: Math.round(confidence * 100) / 100,
+ // No pattern means no basis for a success estimate.
+ successProbability: noMatchDetail !== null ? null : Math.round(confidence * 100) / 100,
estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
complexity,
},
@@ -1710,12 +1765,15 @@ export const hooksPreTask: MCPTool = {
return {
taskId,
description,
+ agentsMatched: suggestion.matched,
suggestedAgents: suggestion.agents.map((agent, i) => ({
type: agent,
confidence: suggestion.confidence - (0.05 * i),
- reason: i === 0
- ? `Primary agent for ${agent} tasks based on learned patterns`
- : `Alternative agent with ${agent} capabilities`,
+ reason: !suggestion.matched
+ ? 'Default suggestion (nothing matched)'
+ : i === 0
+ ? `Primary agent for ${agent} tasks based on learned patterns`
+ : `Alternative agent with ${agent} capabilities`,
})),
complexity,
estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
@@ -2053,8 +2111,35 @@ export const hooksExplain: MCPTool = {
// File unreadable; leave as null
}
+ // #3567: when nothing matched, say so instead of explaining a match that did not happen.
+ if (!suggestion.matched) {
+ return {
+ task,
+ matched: false,
+ reason: 'no-match-default',
+ explanation: `No keyword or learned pattern matched this task. ${suggestion.note ?? ''} ` +
+ `"${suggestion.agents[0]}" is a default suggestion, not a routing decision.`.trim(),
+ factors: [
+ { factor: 'Keyword Match', weight: 0.4, value: null, impact: 'No keyword matched' },
+ { factor: 'Historical Success', weight: 0.3, value: historicalSuccess, impact: historicalNote },
+ { factor: 'Agent Availability', weight: 0.2, value: null, impact: 'Agent availability tracking not implemented' },
+ { factor: 'Task Complexity', weight: 0.1, value: task.length > 100 ? 0.8 : 0.3, impact: 'Complexity assessment' },
+ ],
+ patterns: matchedPatterns,
+ decision: {
+ agent: suggestion.agents[0],
+ confidence: suggestion.confidence,
+ reasoning: [
+ 'No pattern matched; the agent is a default suggestion',
+ `Confidence ${(suggestion.confidence * 100).toFixed(0)}% is below every real match`,
+ ],
+ },
+ };
+ }
+
return {
task,
+ matched: true,
explanation: `The routing decision was made based on keyword analysis of the task description. ` +
`The task contains keywords that match the "${suggestion.agents[0]}" specialization with ${(suggestion.confidence * 100).toFixed(0)}% confidence.`,
factors: [