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(learning): report SONA trajectory scope and live count honestly

Rudy Celekli11e04bfc52ca
diff --git a/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts b/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts
index a1717294a4..1097dfee7b 100644
--- a/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts
+++ b/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts
@@ -44,7 +44,8 @@ describe('UnifiedLearningStats shape (ADR-075)', () => {
expect(stats.consistency).toBeDefined();
expect(Array.isArray(stats.consistency.notes)).toBe(true);
- expect(typeof stats.consistency.sonaTracksGlobal).toBe('boolean');
+ expect(stats.consistency.sonaTracksGlobal).toBeNull();
+ expect(stats.consistency.sonaTracksGlobalDelta).toBeNull();
expect(typeof stats.generatedAt).toBe('string');
});
});
diff --git a/v3/@claude-flow/cli/__tests__/unified-stats-scope-3198.test.ts b/v3/@claude-flow/cli/__tests__/unified-stats-scope-3198.test.ts
new file mode 100644
index 0000000000..728353d18c
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/unified-stats-scope-3198.test.ts
@@ -0,0 +1,49 @@
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const originalCwd = process.cwd();
+const project = mkdtempSync(join(tmpdir(), 'ruflo-sona-scope-3198-'));
+const statsDir = join(project, '.claude-flow', 'neural');
+mkdirSync(statsDir, { recursive: true });
+writeFileSync(join(statsDir, 'stats.json'), JSON.stringify({
+ trajectoriesRecorded: 30_622,
+ patternsLearned: 0,
+ signalsProcessed: 0,
+ lastAdaptation: null,
+}));
+
+afterAll(() => {
+ process.chdir(originalCwd);
+ rmSync(project, { recursive: true, force: true });
+});
+
+describe('#3198 unified learning counters have different lifetimes', () => {
+ it('does not call a fresh process-local SONA count drift from persisted history', async () => {
+ process.chdir(project);
+ vi.resetModules();
+ const intel = await import('../src/memory/intelligence.js');
+ const init = await intel.initializeIntelligence();
+ expect(init.success).toBe(true);
+
+ const stats = await intel.getUnifiedLearningStats();
+ expect(stats.global.trajectoriesRecorded).toBe(30_622);
+ expect(stats.sona.trajectoriesTotal).toBe(0);
+ expect(stats.global.scope).toBe('project-persisted');
+ expect(stats.sona.scope).toBe('process-local');
+ expect(stats.sona.metric).toBe('recent-buffered-trajectories');
+ expect(stats.consistency.sonaTracksGlobal).toBeNull();
+ expect(stats.consistency.sonaTracksGlobalDelta).toBeNull();
+ expect(stats.consistency.notes.join(' ')).toMatch(/different (scopes|lifetimes)|not comparable/i);
+ expect(stats.consistency.notes.join(' ')).not.toMatch(/expected to track within/i);
+
+ // The coordinator's actual stats() key is trajectoryCount. The old
+ // aggregator read nonexistent trajectoriesTotal/trajectoriesProcessed keys,
+ // so this stayed 0 even after a trajectory completed in this process.
+ expect(await intel.recordTrajectory([], 'failure')).toBe(true);
+ const after = await intel.getUnifiedLearningStats();
+ expect(after.global.trajectoriesRecorded).toBe(30_623);
+ expect(after.sona.trajectoriesTotal).toBeGreaterThan(0);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/memory/intelligence.ts b/v3/@claude-flow/cli/src/memory/intelligence.ts
index 6b9af189db..7b86efef14 100644
--- a/v3/@claude-flow/cli/src/memory/intelligence.ts
+++ b/v3/@claude-flow/cli/src/memory/intelligence.ts
@@ -869,6 +869,7 @@ export interface UnifiedLearningStats {
signalsProcessed: number;
lastAdaptation: number | null;
source: string;
+ scope: 'project-persisted';
};
sona: {
trajectoriesTotal: number;
@@ -877,6 +878,8 @@ export interface UnifiedLearningStats {
avgAdaptationTimeMs: number;
source: string;
available: boolean;
+ scope: 'process-local';
+ metric: 'recent-buffered-trajectories';
};
memoryBridge: {
totalEntries: number;
@@ -891,8 +894,9 @@ export interface UnifiedLearningStats {
source: string;
};
consistency: {
- sonaTracksGlobal: boolean;
- sonaTracksGlobalDelta: number;
+ /** These counters measure different lifetimes and cannot be compared. */
+ sonaTracksGlobal: null;
+ sonaTracksGlobalDelta: null;
notes: string[];
};
generatedAt: string;
@@ -908,12 +912,15 @@ export async function getUnifiedLearningStats(): Promise<UnifiedLearningStats> {
let sonaStats = { trajectoriesTotal: 0, patternsLearned: 0, reasoningBankSize: 0, avgAdaptationTimeMs: 0 };
if (sonaCoord) {
try {
- const s = (sonaCoord as unknown as { stats?: () => Record<string, number> }).stats?.() ?? {};
+ const s = sonaCoord.stats();
sonaStats = {
- trajectoriesTotal: Number(s.trajectoriesTotal ?? s.trajectoriesProcessed ?? 0),
- patternsLearned: Number(s.totalPatterns ?? s.patternsLearned ?? 0),
- reasoningBankSize: (bank as unknown as { stats?: () => { patternCount?: number } })?.stats?.()?.patternCount ?? 0,
- avgAdaptationTimeMs: (sonaCoord as unknown as { getAvgAdaptationTime?: () => number }).getAvgAdaptationTime?.() ?? 0,
+ // LocalSonaCoordinator.stats() reports trajectoryCount, a bounded
+ // recent buffer. Reading nonexistent trajectoriesTotal / processed
+ // fields made this metric permanently 0, even after learning.
+ trajectoriesTotal: s.trajectoryCount,
+ patternsLearned: 0,
+ reasoningBankSize: bank?.stats().patternCount ?? 0,
+ avgAdaptationTimeMs: s.avgAdaptationMs,
};
} catch { /* SONA not yet initialised */ }
}
@@ -936,11 +943,12 @@ export async function getUnifiedLearningStats(): Promise<UnifiedLearningStats> {
neuralStats = nt.getNeuralStoreStats();
} catch { /* neural module not loadable */ }
- // Consistency notes — describe (don't enforce) the cross-store relationships
- const sonaTracksGlobalDelta = sonaStats.trajectoriesTotal - intel.trajectoriesRecorded;
+ // SONA's coordinator is recreated on each process start, while globalStats
+ // is restored from disk. Their counts can differ by thousands after a
+ // restart even when both learning paths work correctly (#3198).
const notes: string[] = [];
- if (sonaAvailable && Math.abs(sonaTracksGlobalDelta) > 2) {
- notes.push(`sona.trajectoriesTotal (${sonaStats.trajectoriesTotal}) drifts from globalStats.trajectoriesRecorded (${intel.trajectoriesRecorded}) by ${sonaTracksGlobalDelta} — expected to track within ±1`);
+ if (sonaAvailable && sonaStats.trajectoriesTotal !== intel.trajectoriesRecorded) {
+ notes.push('sona.trajectoriesTotal is a process-local, bounded recent trajectory buffer; global.trajectoriesRecorded is project-persisted. These counters have different lifetimes and are not comparable.');
}
if (intel.patternsLearned > 0 && neuralStats.patternCount === 0) {
notes.push(`globalStats reports ${intel.patternsLearned} patterns learned but neural_patterns store is empty — pretrain has not written here, or trajectory-end isn't promoting patterns to the neural store yet`);
@@ -956,17 +964,20 @@ export async function getUnifiedLearningStats(): Promise<UnifiedLearningStats> {
signalsProcessed: intel.signalsProcessed,
lastAdaptation: intel.lastAdaptation,
source: '.claude-flow/neural/stats.json (globalStats)',
+ scope: 'project-persisted',
},
sona: {
...sonaStats,
source: 'sonaCoordinator (in-memory, resets per process)',
available: sonaAvailable,
+ scope: 'process-local',
+ metric: 'recent-buffered-trajectories',
},
memoryBridge: bridgeStats,
neuralPatterns: neuralStats,
consistency: {
- sonaTracksGlobal: sonaAvailable ? Math.abs(sonaTracksGlobalDelta) <= 1 : true,
- sonaTracksGlobalDelta,
+ sonaTracksGlobal: null,
+ sonaTracksGlobalDelta: null,
notes,
},
generatedAt: new Date().toISOString(),
diff --git a/v3/docs/adr/ADR-075-unified-learning-stats.md b/v3/docs/adr/ADR-075-unified-learning-stats.md
index 80110b3157..49d250464b 100644
--- a/v3/docs/adr/ADR-075-unified-learning-stats.md
+++ b/v3/docs/adr/ADR-075-unified-learning-stats.md
@@ -32,15 +32,21 @@ Add a **read-only aggregator** that calls all four stores and returns them in on
```ts
interface UnifiedLearningStats {
- global: { patternsLearned, trajectoriesRecorded, signalsProcessed, lastAdaptation, source };
- sona: { trajectoriesTotal, patternsLearned, reasoningBankSize, avgAdaptationTimeMs, source, available };
+ global: { patternsLearned, trajectoriesRecorded, signalsProcessed, lastAdaptation, source, scope: 'project-persisted' };
+ sona: { trajectoriesTotal, patternsLearned, reasoningBankSize, avgAdaptationTimeMs, source, available, scope: 'process-local', metric: 'recent-buffered-trajectories' };
memoryBridge: { totalEntries, perNamespace, source, reachable };
neuralPatterns:{ patternCount, byType, modelCount, source };
- consistency: { sonaTracksGlobal, sonaTracksGlobalDelta, notes };
+ consistency: { sonaTracksGlobal: null, sonaTracksGlobalDelta: null, notes };
generatedAt: string;
}
```
+The two trajectory counters are not an equality check: SONA coordinator
+state resets with each process and retains only a bounded recent buffer,
+while globalStats is restored from disk.
+The historical comparison fields are `null` because a numeric delta or
+pass/fail verdict would misreport normal restarts as drift.
+
### MCP surface
`hooks_intelligence_unified-stats` exposes the aggregator to MCP clients. Description names every sub-view's store and the kind of question each answers, so an LLM agent can choose between this (one coherent dashboard) and the original narrow aggregators (one specific slice).
diff --git a/v3/docs/learning/self-learning-usage.md b/v3/docs/learning/self-learning-usage.md
index 09a75616a1..9cebda4698 100644
--- a/v3/docs/learning/self-learning-usage.md
+++ b/v3/docs/learning/self-learning-usage.md
@@ -160,14 +160,20 @@ node v3/@claude-flow/cli/scripts/benchmark-pretrained-retrieval.mjs
## How to read the consistency block
-When `hooks_intelligence_unified-stats` returns a non-empty `consistency.notes`,
-that's a real cross-store drift you should look at:
+`hooks_intelligence_unified-stats` reports two trajectory counters with different
+lifetimes. `global.trajectoriesRecorded` is persisted for the project;
+`sona.trajectoriesTotal` counts the bounded recent trajectory buffer in this
+process.
+A fresh process can therefore report SONA 0 beside thousands of persisted
+trajectories without a learning failure. The counters cannot be compared.
+Other `consistency.notes` can still identify actionable cross-store gaps:
```jsonc
"consistency": {
- "sonaTracksGlobal": true, // SONA matches globalStats within ±1
- "sonaTracksGlobalDelta": 0,
+ "sonaTracksGlobal": null, // different lifetimes; no valid comparison
+ "sonaTracksGlobalDelta": null,
"notes": [
+ "sona.trajectoriesTotal is a process-local, bounded recent trajectory buffer; global.trajectoriesRecorded is project-persisted. These counters have different lifetimes and are not comparable.",
"globalStats reports 47 patterns learned but neural_patterns store is empty — pretrain has not written here, or trajectory-end isn't promoting patterns to the neural store yet"
]
}