claude-flow 3.24.0 → 3.25.1

package/.claude/.proven-config-version

@@ -0,0 +1 @@
+sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1783265769778,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.24.0",
+  "version": "3.25.1",
   "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/mcp-tools/neural-tools.js

@@ -89,14 +89,34 @@ function ensureEmbeddings() {
         return embeddingsPromise;
     embeddingsPromise = (async () => {
         try {
+            // Tier -1 (PRIMARY): optional WASM embedder — a pluggable real embedder
+            // ahead of everything. OPT-IN (RUFLO_EMBED_WASM_PKG) + FAIL-CLOSED: unset
+            // or absent/init-fail ⇒ fall straight through to the existing
+            // ruvector-ONNX → hash tiers with zero regression.
+            try {
+                const we = await import('../ruvector/wasm-embedder.js').catch(() => null);
+                if (we && await we.wasmEmbedderAvailable()) {
+                    const model = we.DEFAULT_EMBED_MODEL;
+                    realEmbeddings = {
+                        embed: async (text) => {
+                            const v = await we.wasmEmbed(text, model);
+                            if (!v || !v.length)
+                                throw new Error('wasm embed failed'); // → generateEmbedding falls to next tier
+                            return v;
+                        },
+                    };
+                    embeddingServiceName = `wasm-embedder/${model} (${we.wasmEmbedderModels().length} model${we.wasmEmbedderModels().length === 1 ? '' : 's'})`;
+                }
+            }
+            catch { /* not configured — fall through */ }
             // Tier 0: ruvector@0.2.27 — bundled all-MiniLM-L6-v2 + parallel worker pool.
             // Probe with isOnnxAvailable() and verify an actual embed succeeds (avoids
             // the type-load-success-but-runtime-fails trap from ADR-086). The probe now
             // runs on first embed request instead of at import time.
             // NOTE: ruvector's embed() returns `{embedding, dimension, timeMs}` — we
             // unwrap to plain number[] for the shared interface.
-            const rv = await import('ruvector').catch(() => null);
-            if (rv?.embed && typeof rv.embed === 'function' && rv.isOnnxAvailable?.()) {
+            const rv = !realEmbeddings ? await import('ruvector').catch(() => null) : null;
+            if (!realEmbeddings && rv?.embed && typeof rv.embed === 'function' && rv.isOnnxAvailable?.()) {
                 try {
                     if (typeof rv.initOnnxEmbedder === 'function')
                         await rv.initOnnxEmbedder();
@@ -300,6 +320,7 @@ 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) {
+        (await import('../memory/embedding-policy.js')).enforceNoStub('neural-tools.generateEmbedding'); // "no stubs" strict mode
         if (embeddingServiceName === 'none') {
             embeddingServiceName = 'hash-fallback';
         }

package/v3/@claude-flow/cli/dist/src/memory/embedding-policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Embedding policy — "no more stubs" enforcement.
+ *
+ * Every embedder in the codebase tries REAL models first (Lattice WASM →
+ * ruvector ONNX → AgentDB bridge → transformers.js) and only falls back to a
+ * deterministic HASH embedding when none loads. A hash embedding has no semantic
+ * meaning — it silently degrades similarity search into noise.
+ *
+ * This module makes that failure mode a POLICY choice instead of a silent
+ * default. With RUFLO_REQUIRE_REAL_EMBEDDINGS truthy, any hash last-resort throws
+ * loudly ("no stubs") rather than returning a meaningless vector — fail-closed,
+ * so a broken embedding substrate is a hard error, not corrupt retrieval.
+ *
+ * Default (unset): unchanged behavior (warn + degrade), so nothing breaks for
+ * installs where a real embedder genuinely can't load. Set the flag in any
+ * environment that must never serve pseudo-embeddings.
+ */
+export declare function requireRealEmbeddings(): boolean;
+/** Throw the canonical "no stubs" error if strict mode is on; else no-op. */
+export declare function enforceNoStub(where: string): void;
+//# sourceMappingURL=embedding-policy.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/embedding-policy.js

@@ -0,0 +1,30 @@
+/**
+ * Embedding policy — "no more stubs" enforcement.
+ *
+ * Every embedder in the codebase tries REAL models first (Lattice WASM →
+ * ruvector ONNX → AgentDB bridge → transformers.js) and only falls back to a
+ * deterministic HASH embedding when none loads. A hash embedding has no semantic
+ * meaning — it silently degrades similarity search into noise.
+ *
+ * This module makes that failure mode a POLICY choice instead of a silent
+ * default. With RUFLO_REQUIRE_REAL_EMBEDDINGS truthy, any hash last-resort throws
+ * loudly ("no stubs") rather than returning a meaningless vector — fail-closed,
+ * so a broken embedding substrate is a hard error, not corrupt retrieval.
+ *
+ * Default (unset): unchanged behavior (warn + degrade), so nothing breaks for
+ * installs where a real embedder genuinely can't load. Set the flag in any
+ * environment that must never serve pseudo-embeddings.
+ */
+export function requireRealEmbeddings() {
+    return /^(1|true|yes|on|strict)$/i.test(process.env.RUFLO_REQUIRE_REAL_EMBEDDINGS ?? '');
+}
+/** Throw the canonical "no stubs" error if strict mode is on; else no-op. */
+export function enforceNoStub(where) {
+    if (requireRealEmbeddings()) {
+        throw new Error(`[no-stub] real embeddings required but only a hash fallback was available at ${where}. ` +
+            `RUFLO_REQUIRE_REAL_EMBEDDINGS is set — install a real embedder ` +
+            `(ruvector, or @claude-flow/embeddings with "embeddings init --download") ` +
+            `or unset the flag to allow degraded hash embeddings.`);
+    }
+}
+//# sourceMappingURL=embedding-policy.js.map

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

@@ -2011,6 +2011,7 @@ export async function generateLocalEmbedding(text) {
     }
     // Deterministic hash-based fallback (for testing/demo without ONNX).
     // AUDIT #3: backend='mock' — these vectors do NOT carry real semantics.
+    (await import('./embedding-policy.js')).enforceNoStub('memory-initializer.generateLocalEmbedding'); // "no stubs" strict mode
     const embedding = generateHashEmbedding(text, state.dimensions);
     return {
         embedding,

package/v3/@claude-flow/cli/dist/src/ruvector/lattice-wasm.d.ts

@@ -0,0 +1,14 @@
+/** Default package name (ruvnet WASM convention); override with RUFLO_LATTICE_WASM_PKG. */
+export declare const LATTICE_WASM_PKG: string;
+export type LatticeModel = 'minilm' | 'bge' | 'paraphrase-minilm' | 'qwen3-0.6b' | string;
+export declare const DEFAULT_LATTICE_MODEL: LatticeModel;
+/** Is the Lattice WASM embedder installed + initializable? Cached; never throws. */
+export declare function latticeAvailable(): Promise<boolean>;
+/** The models Lattice reports (empty until availability is probed). */
+export declare function latticeModels(): LatticeModel[];
+/**
+ * Embed `text` with `model` via Lattice WASM. Returns null on any failure so the
+ * caller can fall through to the next tier. Never throws.
+ */
+export declare function latticeEmbed(text: string, model?: LatticeModel): Promise<number[] | null>;
+//# sourceMappingURL=lattice-wasm.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/lattice-wasm.js

@@ -0,0 +1,144 @@
+/**
+ * Lattice WASM embedder adapter — the primary embedding tier (ADR: embedding
+ * substrate upgrade). Replaces hash placeholders with real semantic embeddings
+ * and adds multiple models (miniLM, bge, multi-paraphrase-miniLM, GPU qwen3-0.6B).
+ *
+ * Built on the proven `@ruvector/ruvllm-wasm` optional-dependency convention:
+ *   - dynamically imported (never a hard dependency),
+ *   - WASM initialized from bundled bytes,
+ *   - fully FAIL-CLOSED: if the package is absent, the WASM fails to init, or the
+ *     embed API differs, `latticeAvailable()` returns false and callers fall
+ *     through to the existing ruvector-ONNX → hash tiers with ZERO regression.
+ *
+ * The package specifier is configurable (`RUFLO_LATTICE_WASM_PKG`) so the exact
+ * published name can be set without a code change; the API is probed tolerantly.
+ * Opt-in for the GPU model: qwen3 is only selected when explicitly requested.
+ */
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+const require_ = createRequire(import.meta.url);
+/** Default package name (ruvnet WASM convention); override with RUFLO_LATTICE_WASM_PKG. */
+export const LATTICE_WASM_PKG = process.env.RUFLO_LATTICE_WASM_PKG || '@ruvector/lattice-wasm';
+export const DEFAULT_LATTICE_MODEL = process.env.RUFLO_EMBED_MODEL || 'minilm';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let _mod = null;
+let _ready = false;
+let _probed = false;
+let _available = false;
+let _models = [];
+async function loadModule() {
+    if (_mod)
+        return _mod;
+    const spec = LATTICE_WASM_PKG;
+    _mod = await import(spec).catch(() => null); // optional — absent ⇒ null ⇒ unavailable
+    return _mod;
+}
+async function ensureInit() {
+    if (_ready)
+        return true;
+    const mod = await loadModule();
+    if (!mod)
+        return false;
+    try {
+        // ruvnet WASM convention: initSync({ module: <wasm bytes> }); tolerate variants.
+        if (!_ready && typeof mod.initSync === 'function') {
+            let wasmBytes;
+            for (const cand of ['lattice_wasm_bg.wasm', 'lattice_bg.wasm', 'index_bg.wasm']) {
+                try {
+                    wasmBytes = readFileSync(require_.resolve(`${LATTICE_WASM_PKG}/${cand}`));
+                    break;
+                }
+                catch { /* try next */ }
+            }
+            mod.initSync(wasmBytes ? { module: wasmBytes } : undefined);
+        }
+        else if (typeof mod.default === 'function') {
+            await mod.default(); // some wasm-bindgen builds export an async default init
+        }
+        _ready = true;
+        return true;
+    }
+    catch {
+        return false; // init failed ⇒ fail closed
+    }
+}
+/** Extract a plain number[] from whatever shape the module's embed returns. */
+function toVec(r) {
+    const v = (r && typeof r === 'object' && 'embedding' in r) ? r.embedding : r;
+    if (!v)
+        return null;
+    if (Array.isArray(v))
+        return v;
+    if (v.length !== undefined)
+        return Array.from(v);
+    return null;
+}
+/** Is the Lattice WASM embedder installed + initializable? Cached; never throws. */
+export async function latticeAvailable() {
+    if (_probed)
+        return _available;
+    _probed = true;
+    try {
+        if (!(await ensureInit())) {
+            _available = false;
+            return false;
+        }
+        const mod = _mod;
+        // discover models (tolerant): listModels() / models / MODELS
+        try {
+            const list = typeof mod.listModels === 'function' ? mod.listModels() : (mod.models ?? mod.MODELS);
+            if (Array.isArray(list) && list.length)
+                _models = list;
+        }
+        catch { /* leave default */ }
+        if (!_models.length)
+            _models = [DEFAULT_LATTICE_MODEL];
+        // verify an actual embed succeeds (the ADR-086 "loads but runtime-fails" trap).
+        const probe = await latticeEmbedRaw('probe', DEFAULT_LATTICE_MODEL);
+        _available = !!probe && probe.length > 0;
+        return _available;
+    }
+    catch {
+        _available = false;
+        return false;
+    }
+}
+/** The models Lattice reports (empty until availability is probed). */
+export function latticeModels() { return [..._models]; }
+async function latticeEmbedRaw(text, model) {
+    const mod = _mod;
+    if (!mod)
+        return null;
+    // tolerant API probing across plausible wasm-bindgen surfaces.
+    const attempts = [
+        () => typeof mod.embed === 'function' ? mod.embed(text, model) : undefined,
+        () => typeof mod.embed === 'function' ? mod.embed(text) : undefined,
+        () => typeof mod.embedText === 'function' ? mod.embedText(text, model) : undefined,
+        () => typeof mod.Embedder === 'function' ? new mod.Embedder(model).embed(text) : undefined,
+    ];
+    for (const a of attempts) {
+        try {
+            const r = await a();
+            const v = toVec(r);
+            if (v)
+                return v;
+        }
+        catch { /* try next surface */ }
+    }
+    return null;
+}
+/**
+ * Embed `text` with `model` via Lattice WASM. Returns null on any failure so the
+ * caller can fall through to the next tier. Never throws.
+ */
+export async function latticeEmbed(text, model = DEFAULT_LATTICE_MODEL) {
+    try {
+        if (!(await latticeAvailable()))
+            return null;
+        return await latticeEmbedRaw(text, model);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=lattice-wasm.js.map

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

@@ -13,6 +13,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { enforceNoStub } from '../memory/embedding-policy.js';
 // ============================================================================
 // Fallback Implementation (when ruvector not available)
 // ============================================================================
@@ -248,6 +249,7 @@ export function generateEmbedding(text, dimensions = 768) {
             // Fall back to hash-based embedding
         }
     }
+    enforceNoStub('vector-db.generateEmbedding'); // "no stubs" strict mode → throw instead of hash
     const embedding = generateHashEmbedding(text, dimensions);
     // Tag the result so consumers can detect it came from hash fallback
     Object.defineProperty(embedding, '_warning', {

package/v3/@claude-flow/cli/dist/src/ruvector/wasm-embedder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export declare const EMBED_WASM_PKG: string;
+export declare const DEFAULT_EMBED_MODEL: string;
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export declare function wasmEmbedderAvailable(): Promise<boolean>;
+/** Models the configured WASM embedder reports (empty until available). */
+export declare function wasmEmbedderModels(): string[];
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export declare function wasmEmbed(text: string, model?: string): Promise<number[] | null>;
+//# sourceMappingURL=wasm-embedder.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/wasm-embedder.js

@@ -0,0 +1,143 @@
+/**
+ * Optional WASM embedder tier — a pluggable PRIMARY embedding tier ahead of
+ * ruvector-ONNX → hash.
+ *
+ * OPT-IN by design: there is NO default package (an earlier iteration defaulted
+ * to `@ruvector/lattice-wasm`, which does not exist — npm 404). Point
+ * `RUFLO_EMBED_WASM_PKG` at any real WASM embedder that follows the ruvnet
+ * wasm-bindgen convention (a text→vector embed export). With the env unset, this
+ * tier is INERT and everything resolves exactly as before (ruvector ONNX). Fully
+ * fail-closed; never throws.
+ *
+ * The adapter probes the module's API tolerantly and verifies a real embed
+ * succeeds before accepting the tier (guards the ADR-086 loads-but-runtime-fails
+ * trap), so an incompatible package simply reports unavailable.
+ */
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+const require_ = createRequire(import.meta.url);
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export const EMBED_WASM_PKG = process.env.RUFLO_EMBED_WASM_PKG || process.env.RUFLO_LATTICE_WASM_PKG || '';
+export const DEFAULT_EMBED_MODEL = process.env.RUFLO_EMBED_MODEL || 'default';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let _mod = null;
+let _ready = false;
+let _probed = false;
+let _available = false;
+let _models = [];
+async function loadModule() {
+    if (!EMBED_WASM_PKG)
+        return null; // opt-in: no package configured ⇒ inert
+    if (_mod)
+        return _mod;
+    _mod = await import(EMBED_WASM_PKG).catch(() => null); // optional — absent ⇒ null ⇒ unavailable
+    return _mod;
+}
+async function ensureInit() {
+    if (_ready)
+        return true;
+    const mod = await loadModule();
+    if (!mod)
+        return false;
+    try {
+        if (typeof mod.initSync === 'function') {
+            let wasmBytes;
+            for (const cand of ['index_bg.wasm', 'embedder_bg.wasm', 'wasm_bg.wasm']) {
+                try {
+                    wasmBytes = readFileSync(require_.resolve(`${EMBED_WASM_PKG}/${cand}`));
+                    break;
+                }
+                catch { /* try next */ }
+            }
+            mod.initSync(wasmBytes ? { module: wasmBytes } : undefined);
+        }
+        else if (typeof mod.default === 'function') {
+            await mod.default();
+        }
+        _ready = true;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toVec(r) {
+    const v = (r && typeof r === 'object' && 'embedding' in r) ? r.embedding : r;
+    if (!v)
+        return null;
+    if (Array.isArray(v))
+        return v;
+    if (v.length !== undefined)
+        return Array.from(v);
+    return null;
+}
+async function embedRaw(text, model) {
+    const mod = _mod;
+    if (!mod)
+        return null;
+    const attempts = [
+        () => typeof mod.embed === 'function' ? mod.embed(text, model) : undefined,
+        () => typeof mod.embed === 'function' ? mod.embed(text) : undefined,
+        () => typeof mod.embedText === 'function' ? mod.embedText(text, model) : undefined,
+        () => typeof mod.Embedder === 'function' ? new mod.Embedder(model).embed(text) : undefined,
+    ];
+    for (const a of attempts) {
+        try {
+            const r = await a();
+            const v = toVec(r);
+            if (v)
+                return v;
+        }
+        catch { /* try next surface */ }
+    }
+    return null;
+}
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export async function wasmEmbedderAvailable() {
+    if (_probed)
+        return _available;
+    _probed = true;
+    try {
+        if (!EMBED_WASM_PKG) {
+            _available = false;
+            return false;
+        } // opt-in; not configured
+        if (!(await ensureInit())) {
+            _available = false;
+            return false;
+        }
+        const mod = _mod;
+        try {
+            const list = typeof mod.listModels === 'function' ? mod.listModels() : (mod.models ?? mod.MODELS);
+            if (Array.isArray(list) && list.length)
+                _models = list;
+        }
+        catch { /* leave default */ }
+        if (!_models.length)
+            _models = [DEFAULT_EMBED_MODEL];
+        const probe = await embedRaw('probe', DEFAULT_EMBED_MODEL);
+        _available = !!probe && probe.length > 0;
+        return _available;
+    }
+    catch {
+        _available = false;
+        return false;
+    }
+}
+/** Models the configured WASM embedder reports (empty until available). */
+export function wasmEmbedderModels() { return [..._models]; }
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export async function wasmEmbed(text, model = DEFAULT_EMBED_MODEL) {
+    try {
+        if (!(await wasmEmbedderAvailable()))
+            return null;
+        return await embedRaw(text, model);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=wasm-embedder.js.map

package/v3/@claude-flow/cli/dist/src/services/evolve-proof.d.ts

@@ -42,6 +42,7 @@ export interface ChangeDeltas {
     benchmark: number;
     security: number;
     cost: number;
+    humanRelevance?: number;
 }
 /**
  * Causal promotion record (not just provenance). Answers *why* a candidate won —
@@ -85,6 +86,7 @@ export interface EvolveReceiptBundle {
     mutationClass: string;
     mutationSummary: string;
     deltas: ChangeDeltas;
+    humanEvalHash?: string;
     promotion: PromotionRecord | null;
     regression: RegressionRecord | null;
     holdout: HoldoutTask[];
@@ -109,6 +111,8 @@ export interface AssembleOpts {
     redblue?: 'PASS' | 'FAIL' | 'SKIPPED';
     drift?: number;
     canaryRollbackRate?: number;
+    humanRelevanceDelta?: number;
+    humanEvalHash?: string;
     layer?: string;
     corpus?: string;
 }
@@ -137,6 +141,8 @@ export declare function runRealEvolveRound(opts: {
     redblue?: 'PASS' | 'FAIL' | 'SKIPPED';
     drift?: number;
     canaryRollbackRate?: number;
+    humanRelevanceDelta?: number;
+    humanEvalHash?: string;
     corpus: string;
 }): EvolveReceiptBundle;
 /**

package/v3/@claude-flow/cli/dist/src/services/evolve-proof.js

@@ -95,7 +95,7 @@ export function assembleBundle(baseline, candidate, holdout, o) {
         state: 'shadow', served: false, candidateManifestHash, registeredAt: o.now,
     } : null;
     const { mutationClass, mutationSummary } = classifyMutation(baseline, candidate);
-    const deltas = { benchmark: candidateHeldOut - baselineHeldOut, security: o.redblue === 'FAIL' ? -1 : 0, cost: 0 };
+    const deltas = { benchmark: candidateHeldOut - baselineHeldOut, security: o.redblue === 'FAIL' ? -1 : 0, cost: 0, humanRelevance: o.humanRelevanceDelta };
     const promotion = promoted ? { parentManifestHash: o.parent, candidateManifestHash, mutationClass, mutationSummary, deltas, decisionReceipt } : null;
     const regression = promoted ? null : {
         candidateManifestHash, ancestor: o.parent ?? baselineManifestHash, mutationClass,
@@ -107,7 +107,7 @@ export function assembleBundle(baseline, candidate, holdout, o) {
         meetsPromotionRule: { version: PROMOTION_RULE_VERSION, result: promoted },
         decisionReceipt, shadow,
         costReceipt: { usd: 0, llmCalls: 0, tier: o.cost.tier, notes: o.cost.notes },
-        mutationClass, mutationSummary, deltas, promotion, regression,
+        mutationClass, mutationSummary, deltas, humanEvalHash: o.humanEvalHash, promotion, regression,
         holdout, baselineManifest, candidateManifest,
     };
 }
@@ -122,7 +122,9 @@ export function runRealEvolveRound(opts) {
     return assembleBundle(opts.baseline, opts.candidate, opts.holdout, {
         generation: opts.generation, parent: opts.parent, branch: opts.branch ?? 'main', now: opts.now, kind: 'real',
         cost: { tier: 'real-local', notes: 'measured on the frozen anchor via live retrieval — no LLM, no network' },
-        redblue: opts.redblue, drift: opts.drift, canaryRollbackRate: opts.canaryRollbackRate, layer: 'real/retrieval', corpus: opts.corpus,
+        redblue: opts.redblue, drift: opts.drift, canaryRollbackRate: opts.canaryRollbackRate,
+        humanRelevanceDelta: opts.humanRelevanceDelta, humanEvalHash: opts.humanEvalHash,
+        layer: 'real/retrieval', corpus: opts.corpus,
     });
 }
 /**

package/v3/@claude-flow/cli/dist/src/services/harness-flywheel-generations.d.ts

@@ -12,6 +12,7 @@ export interface GenerationDeps {
     getPatterns: () => HarvestPattern[] | Promise<HarvestPattern[]>;
     search: (q: string, cfg: RetrievalConfig) => Promise<RankedItem[]> | RankedItem[];
     anchorTasks: AnchorTask[];
+    humanEvalHash?: string;
     sample?: number;
     now: number;
     applyFn?: (cfg: Record<string, number>, hash: string, generation: number) => void;
@@ -100,6 +101,9 @@ export interface FlywheelStatus {
     plateau: PlateauReport;
     mutation: MutationStat[];
     axisEffectiveness: AxisStat[];
+    cumulativeBenchmarkDelta: number;
+    cumulativeHumanRelevanceDelta: number;
+    humanEvalHash: string | null;
     served: ServedState;
     champion: {
         config: Record<string, number>;

package/v3/@claude-flow/cli/dist/src/services/harness-flywheel-generations.js

@@ -267,7 +267,10 @@ export async function runFlywheelGeneration(root, deps) {
         const canaryRollbackRate = CANARY.length ? cRoll / CANARY.length : 0;
         const candAnchor = await anchorMean(cand);
         const redblue = candAnchor >= baseAnchor - ANCHOR_TOL ? 'PASS' : 'FAIL';
-        const bundle = runRealEvolveRound({ baseline: baseline, candidate: cand, holdout, generation, parent, branch: 'main', now: deps.now, redblue, canaryRollbackRate, corpus: FROZEN_CORPUS });
+        // per-generation HUMAN-RELEVANCE delta on the frozen eval set (anti-overfitting
+        // visibility): if this stays ~0 while benchmark Δ > 0, the loop is overfitting.
+        const humanRelevanceDelta = candAnchor - baseAnchor;
+        const bundle = runRealEvolveRound({ baseline: baseline, candidate: cand, holdout, generation, parent, branch: 'main', now: deps.now, redblue, canaryRollbackRate, humanRelevanceDelta, humanEvalHash: deps.humanEvalHash, corpus: FROZEN_CORPUS });
         appendAttempt(root, bundle);
         if (bundle.decisionReceipt.promoted)
             appendPromotion(root, bundle);
@@ -347,6 +350,9 @@ export function flywheelStatus(root) {
         plateau: detectPlateau(attempts.length ? attempts : promotions, { window: 5 }),
         mutation: mutationEffectiveness(attempts.length ? attempts : promotions),
         axisEffectiveness: axisEffectiveness(promotions),
+        cumulativeBenchmarkDelta: promotions.reduce((s, b) => s + (b.deltas.benchmark ?? 0), 0),
+        cumulativeHumanRelevanceDelta: promotions.reduce((s, b) => s + (b.deltas.humanRelevance ?? 0), 0),
+        humanEvalHash: promotions.length ? (promotions[promotions.length - 1].humanEvalHash ?? null) : null,
         served: servedChampion(root),
         champion: { config: champ.config, hash: champ.hash },
     };

package/v3/@claude-flow/cli/dist/src/services/harness-flywheel-runtime.js

@@ -7,19 +7,7 @@
 import { harnessLoopOptedIn } from './harness-worker.js';
 import { runFlywheelTick } from './harness-flywheel.js';
 import { runFlywheelGeneration, checkServedChampionDrift } from './harness-flywheel-generations.js';
-/** The frozen ADR-081 human-relevance anchor in the generation runner's shape. */
-const GEN_ANCHOR = [
-    ['how was the Opus model alias fixed', ['opus 4.8', 'opus alias', 'opus model alias', '#2232']],
-    ['self-learning wiring task-completed pretrain', ['self-learning', 'adr-074', '#2245', 'task-completed']],
-    ['deterministic codemod engine var-to-const', ['deterministic tier-1 codemod', 'adr-143', 'codemod', 'var-to-const']],
-    ['MCP server orphan leak parent-death', ['mcp orphan', 'parent-death', '#2234', 'orphan on every claude']],
-    ['unified learning stats aggregator', ['unified learning-stats', 'adr-075']],
-    ['structured distillation 4-field schema', ['structured distillation', 'adr-076', '4-field schema']],
-    ['SQL injection migrate.ts table identifier', ['sql injection', 'migrate.ts', 'agentdb', 'cve']],
-    ['recall@k HNSW benchmark harness', ['hnsw', 'recall@k', 'benchmark intelligence']],
-    ['Q-learning encoder keyword block', ['q-state encoder', 'keyword block', '#2239', 'q-encoder']],
-    ['security hardening crypto random IDs', ['cwe-347', 'crypto.randomuuid', 'random id', 'crypto random']],
-].map(([q, labels], i) => ({ id: `anchor-${i}`, q: q, labels: labels }));
+import { loadFrozenHumanEval } from './harness-frozen-eval.js';
 /** The human-labeled ADR-081 anchor — the never-regress relevance set. */
 const ANCHOR = [
     ['how was the Opus model alias fixed', ['opus 4.8', 'opus alias', 'opus model alias', '#2232']],
@@ -79,13 +67,16 @@ export async function runFlywheelGenerationWorker(projectRoot, opts = {}) {
         const tool = neural.neuralTools.find((t) => t.name === 'neural_patterns');
         if (!tool)
             return { ran: false, reason: 'neural_patterns tool unavailable', generation: 0 };
+        // Load the FROZEN, hashed, public human eval set (throws if it has drifted).
+        const frozen = loadFrozenHumanEval();
         const deps = {
             getPatterns: () => neural.getStorePatterns(),
             search: async (query, cfg) => {
                 const r = await tool.handler({ action: 'search', query, mode: 'hybrid', limit: 5, rerank: false, ...cfg });
                 return (r.results || []).slice(0, 5).map((m) => ({ id: m?.id ?? '', name: m?.name ?? '' }));
             },
-            anchorTasks: GEN_ANCHOR,
+            anchorTasks: frozen.tasks,
+            humanEvalHash: frozen.corpusHash,
             sample: opts.sample ?? 120,
             now: opts.now ?? Date.now(),
         };

package/v3/@claude-flow/cli/dist/src/services/harness-frozen-eval.d.ts

@@ -0,0 +1,22 @@
+export declare const FROZEN_HUMAN_EVAL_VERSION = "human-relevance-frozen-v1";
+export declare const FROZEN_HUMAN_EVAL_FILE: string;
+/** Pinned canonical hash of the frozen eval tasks — the tamper-evidence anchor. */
+export declare const FROZEN_HUMAN_EVAL_HASH = "sha256:6096e48ef8f2182e0f00348a953f0f00fe0415575b300234fe2316f37b768200";
+export interface HumanEvalTask {
+    id: string;
+    q: string;
+    labels: string[];
+}
+export interface FrozenHumanEval {
+    version: string;
+    tasks: HumanEvalTask[];
+    corpusHash: string;
+}
+/** Canonical content hash over the tasks — order-independent (tasks sorted by id). */
+export declare function humanEvalHash(tasks: HumanEvalTask[]): string;
+/**
+ * Load + verify the frozen human eval set. Throws if missing or if its content
+ * hash != the pinned FROZEN_HUMAN_EVAL_HASH (the "frozen" guarantee).
+ */
+export declare function loadFrozenHumanEval(): FrozenHumanEval;
+//# sourceMappingURL=harness-frozen-eval.d.ts.map

package/v3/@claude-flow/cli/dist/src/services/harness-frozen-eval.js

@@ -0,0 +1,66 @@
+/**
+ * Frozen public human-labeled eval set (ADR-176 — anti-overfitting).
+ *
+ * The flywheel's compounding gains are measured on a self-supervised retrieval
+ * benchmark, which could overfit — improving self-retrieval while human
+ * relevance stays merely *preserved*, not improved. The defense is a SINGLE,
+ * FROZEN, PUBLIC, hashed human-labeled eval set (`.claude/eval/…-v1.json`):
+ *   - it is the red/blue anchor the flywheel must never regress, AND
+ *   - the set against which a per-generation HUMAN-RELEVANCE DELTA is recorded
+ *     in every receipt — so "self-retrieval up, human relevance flat" is
+ *     observable in the lineage, not hidden.
+ *
+ * `loadFrozenHumanEval()` verifies the file's content hash against a PINNED
+ * constant and throws on mismatch — the set cannot silently drift; changing it
+ * means shipping a new versioned file, not editing this one.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { createHash } from 'node:crypto';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const FROZEN_HUMAN_EVAL_VERSION = 'human-relevance-frozen-v1';
+export const FROZEN_HUMAN_EVAL_FILE = path.join('.claude', 'eval', `${FROZEN_HUMAN_EVAL_VERSION}.json`);
+/** Pinned canonical hash of the frozen eval tasks — the tamper-evidence anchor. */
+export const FROZEN_HUMAN_EVAL_HASH = 'sha256:6096e48ef8f2182e0f00348a953f0f00fe0415575b300234fe2316f37b768200';
+function canon(v) {
+    return Array.isArray(v) ? v.map(canon)
+        : (v && typeof v === 'object') ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])])) : v;
+}
+/** Canonical content hash over the tasks — order-independent (tasks sorted by id). */
+export function humanEvalHash(tasks) {
+    const sorted = [...tasks].sort((a, b) => a.id.localeCompare(b.id));
+    return 'sha256:' + createHash('sha256').update(JSON.stringify(canon(sorted))).digest('hex');
+}
+function locate() {
+    const candidates = [];
+    try {
+        const req = createRequire(import.meta.url);
+        candidates.push(path.join(path.dirname(req.resolve('@claude-flow/cli/package.json')), FROZEN_HUMAN_EVAL_FILE));
+    }
+    catch { /* not resolvable in this context */ }
+    candidates.push(path.resolve(__dirname, '..', '..', '..', FROZEN_HUMAN_EVAL_FILE)); // dist/src/services → pkg root
+    candidates.push(path.resolve(__dirname, '..', '..', FROZEN_HUMAN_EVAL_FILE)); // src/services → pkg root
+    for (const c of candidates)
+        if (fs.existsSync(c))
+            return c;
+    return null;
+}
+/**
+ * Load + verify the frozen human eval set. Throws if missing or if its content
+ * hash != the pinned FROZEN_HUMAN_EVAL_HASH (the "frozen" guarantee).
+ */
+export function loadFrozenHumanEval() {
+    const p = locate();
+    if (!p)
+        throw new Error(`frozen human eval set not found (${FROZEN_HUMAN_EVAL_FILE})`);
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    const tasks = parsed.tasks ?? [];
+    const corpusHash = humanEvalHash(tasks);
+    if (corpusHash !== FROZEN_HUMAN_EVAL_HASH) {
+        throw new Error(`frozen human eval hash mismatch — set has drifted (got ${corpusHash}, pinned ${FROZEN_HUMAN_EVAL_HASH}); supersede with a new versioned file, do not edit`);
+    }
+    return { version: parsed.version ?? FROZEN_HUMAN_EVAL_VERSION, tasks, corpusHash };
+}
+//# sourceMappingURL=harness-frozen-eval.js.map

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

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.24.0",
+  "version": "3.25.1",
   "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",