claude-flow 3.22.0 → 3.24.0

package/v3/@claude-flow/cli/dist/src/config/proven-config.js

@@ -0,0 +1,176 @@
+/**
+ * Proven Configuration Manifest (ADR-176 proof #3 + ADR-177 core).
+ *
+ * The signed, constraint-carrying artifact that the self-optimizing harness loop
+ * (ADR-176) emits and the propagation channel (ADR-177) ships to installs. Two
+ * independent gates decide adoption, and BOTH must pass (fail-closed):
+ *
+ *   1. Authenticity  — Ed25519 signature over the canonical manifest bytes,
+ *                      verified against a baked public key. Proves it came from
+ *                      ruflo, unmodified. (native node:crypto, zero deps —
+ *                      same primitive as helper-signing.ts / rvfa-signing.ts.)
+ *   2. Suitability   — the constraint contract (host/platform/compatibility/
+ *                      layer) checked against THIS install. A perfectly-signed
+ *                      manifest that doesn't fit the local environment is a safe
+ *                      NON-adoption, not an error. "signed != suitable."
+ *
+ * This is a DISTINCT Ed25519 trust root from helper-signing (ADR-177): the
+ * config channel gets its own key so rotating it never touches the hook-code
+ * channel that older CLIs verify.
+ */
+import { createHash, verify as edVerify, sign as edSign } from 'crypto';
+/** Ruflo config-signing PUBLIC key (safe to commit). Private half in GCP Secret Manager (ruflo-config-signing-key). */
+export const RUFLO_CONFIG_PUBKEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA3zr3BLCFKyrjvjZg9BXxchXIuGYwYwq21FYCjTpQO6A=
+-----END PUBLIC KEY-----`;
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Deterministic canonical bytes — recursively sorted object keys so signer and
+ * verifier agree byte-for-byte regardless of insertion order.
+ */
+export function canonicalManifestBytes(m) {
+    const canon = (v) => {
+        if (Array.isArray(v))
+            return v.map(canon);
+        if (v && typeof v === 'object') {
+            const out = {};
+            for (const k of Object.keys(v).sort())
+                out[k] = canon(v[k]);
+            return out;
+        }
+        return v;
+    };
+    return Buffer.from(JSON.stringify(canon(m)), 'utf-8');
+}
+/** Sign a manifest (publish-time; key from GCP via scripts). */
+export function signProvenConfig(manifest, privateKeyPem) {
+    const signature = edSign(null, canonicalManifestBytes(manifest), privateKeyPem).toString('base64');
+    return { manifest, signature, algorithm: 'ed25519' };
+}
+/**
+ * Verify a signed manifest against ruflo's config public key. Returns the
+ * manifest on success, or null on ANY failure (bad signature, malformed JSON,
+ * wrong algorithm, missing fields). Fail-closed.
+ */
+export function verifyProvenConfig(signedJson, pubkeyPem = RUFLO_CONFIG_PUBKEY) {
+    try {
+        const signed = typeof signedJson === 'string' ? JSON.parse(signedJson) : signedJson;
+        if (!signed || signed.algorithm !== 'ed25519' || !signed.signature || !signed.manifest)
+            return null;
+        if (!signed.manifest.schema || !signed.manifest.policy?.ref)
+            return null;
+        const ok = edVerify(null, canonicalManifestBytes(signed.manifest), pubkeyPem, Buffer.from(signed.signature, 'base64'));
+        return ok ? signed.manifest : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Suitability gate ────────────────────────────────────────────────────────
+/** Normalize platform aliases so process.platform matches manifest names. */
+function platformMatches(installed, allowed) {
+    const norm = (p) => {
+        const l = p.toLowerCase();
+        if (l === 'darwin' || l === 'macos' || l === 'mac')
+            return 'macos';
+        if (l === 'win32' || l === 'windows')
+            return 'windows';
+        return l; // linux, etc.
+    };
+    const want = norm(installed);
+    return allowed.some(a => norm(a) === want);
+}
+function parseVer(v) {
+    // Tolerant: accepts X, X.Y, or X.Y.Z (a range like '>=1.9' has no patch).
+    const m = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(v);
+    if (!m)
+        return [0, 0, 0];
+    return [Number(m[1] || 0), Number(m[2] || 0), Number(m[3] || 0)];
+}
+function cmpVer(a, b) {
+    const [a1, a2, a3] = parseVer(a);
+    const [b1, b2, b3] = parseVer(b);
+    return a1 - b1 || a2 - b2 || a3 - b3;
+}
+/**
+ * Minimal semver-range satisfier for the compat contract. Supports `>=X`, `>X`,
+ * `<=X`, `<X`, `=X`, and a bare version `X` (treated as `>=X`). Deliberately
+ * small — the manifest contract only uses min-version bounds.
+ */
+export function satisfiesRange(installed, range) {
+    const r = range.trim();
+    const m = /^(>=|<=|>|<|=)?\s*(.+)$/.exec(r);
+    if (!m)
+        return false;
+    const op = m[1] ?? '>=';
+    const target = m[2].trim();
+    const c = cmpVer(installed, target);
+    switch (op) {
+        case '>=': return c >= 0;
+        case '>': return c > 0;
+        case '<=': return c <= 0;
+        case '<': return c < 0;
+        case '=': return c === 0;
+        default: return false;
+    }
+}
+/**
+ * Check a manifest's constraint contract against the local environment.
+ * Fail-closed: a missing/unsatisfiable constraint => not suitable (safe skip).
+ * A constraint the manifest doesn't declare is not required.
+ */
+export function isSuitable(manifest, env) {
+    // platform
+    if (manifest.platform && manifest.platform.length > 0) {
+        if (!platformMatches(env.platform, manifest.platform)) {
+            return { suitable: false, reason: `platform ${env.platform} not in [${manifest.platform.join(', ')}]` };
+        }
+    }
+    // host presence + version
+    if (manifest.host) {
+        for (const [name, range] of Object.entries(manifest.host)) {
+            const installed = env.hosts?.[name];
+            if (!installed)
+                return { suitable: false, reason: `required host '${name}' not present` };
+            if (!satisfiesRange(installed, range)) {
+                return { suitable: false, reason: `host '${name}' ${installed} does not satisfy ${range}` };
+            }
+        }
+    }
+    // package compatibility ranges (ruflo, metaharness, …)
+    if (manifest.compatibility) {
+        for (const [pkg, range] of Object.entries(manifest.compatibility)) {
+            const installed = env.versions?.[pkg];
+            if (!installed)
+                return { suitable: false, reason: `required package '${pkg}' version unknown` };
+            if (!satisfiesRange(installed, range)) {
+                return { suitable: false, reason: `${pkg} ${installed} does not satisfy ${range}` };
+            }
+        }
+    }
+    // hierarchy layer — an install only adopts a manifest for its own (or an ancestor) layer
+    if (manifest.layer && env.layer && manifest.layer !== env.layer) {
+        // allow ancestor layers: manifest 'framework/node-cli' is adoptable by env layer that startsWith it or vice-versa
+        const a = manifest.layer, b = env.layer;
+        if (!(b.startsWith(a) || a.startsWith(b))) {
+            return { suitable: false, reason: `layer '${a}' not applicable to install layer '${b}'` };
+        }
+    }
+    return { suitable: true };
+}
+/**
+ * The combined adoption decision (ADR-177): a manifest is adoptable iff it is
+ * both authentic (signature verifies) AND suitable (constraints satisfied).
+ */
+export function evaluateForAdoption(signedJson, env, pubkeyPem = RUFLO_CONFIG_PUBKEY) {
+    const manifest = verifyProvenConfig(signedJson, pubkeyPem);
+    if (!manifest)
+        return { adopt: false, reason: 'signature invalid — refusing (authenticity gate)' };
+    const suit = isSuitable(manifest, env);
+    if (!suit.suitable)
+        return { adopt: false, manifest, reason: `not suitable — ${suit.reason} (safe skip)` };
+    return { adopt: true, manifest, reason: 'authentic + suitable' };
+}
+//# sourceMappingURL=proven-config.js.map

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

@@ -133,6 +133,41 @@ export class CLI {
                     }
                 }
                 catch { /* silent */ }
+                // ADR-177: adopt a signed proven-configuration champion if the package
+                // ships one newer than this project's stamp AND it is authentic +
+                // suitable for this environment. Sibling of the helper channel above —
+                // its own stamp + trust root; additive no-op when no champion ships.
+                try {
+                    const { autoAdoptProvenConfigIfStale } = await import('./config/proven-config-refresh.js');
+                    const a = await autoAdoptProvenConfigIfStale(process.cwd());
+                    if (a.adopted && this.output.isVerbose()) {
+                        this.output.printDebug(`Adopted proven config (${a.from} → ${a.to})`);
+                    }
+                    // Close the loop (ADR-176 phase 9): promote the adopted champion to the
+                    // ACTIVE policy that consumers (neural_patterns retrieval, …) read. A
+                    // no-op if nothing is adopted or it is already active; reversible.
+                    const { applyChampion } = await import('./config/harness-feedback-applier.js');
+                    const ap = applyChampion(process.cwd());
+                    if (ap.applied && this.output.isVerbose()) {
+                        this.output.printDebug(`Applied proven config to active policy (${ap.from ?? '(none)'} → ${ap.to})`);
+                    }
+                }
+                catch { /* silent */ }
+                // Self-running daemon: ensure the background workers (distillation,
+                // backup, …) are actually firing without a manual `daemon start`.
+                // Single-instance (only spawns when none is alive; the spawned daemon
+                // re-checks its own lock), bounded (TTL/idle self-shutdown), opt-out via
+                // RUFLO_DAEMON_AUTOSTART=0. Skipped for `daemon` (no recursion). Detached
+                // + fire-and-forget, so it never blocks the command.
+                if (commandPath[0] !== 'daemon') {
+                    try {
+                        const { ensureDaemonRunning } = await import('./services/daemon-autostart.js');
+                        const d = ensureDaemonRunning(process.cwd());
+                        if (d.started && this.output.isVerbose())
+                            this.output.printDebug('Started background daemon (auto)');
+                    }
+                    catch { /* silent */ }
+                }
             }
             // Handle lazy-loaded commands that weren't recognized by the parser
             // If commandPath is empty but positional has a command name, check if it's lazy-loadable

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

@@ -12,6 +12,16 @@
  * Note: For production neural features, use @claude-flow/neural module
  */
 import { type MCPTool } from './types.js';
+/**
+ * ADR-176 flywheel: expose the stored patterns (id/name/content) so the
+ * self-optimizing loop can harvest a benchmark corpus from real usage. Additive,
+ * read-only, never throws.
+ */
+export declare function getStorePatterns(): Array<{
+    id: string;
+    name: string;
+    content?: string;
+}>;
 /**
  * Public helper: read-only stats about the neural store, for the unified
  * learning-stats aggregator. Returns total pattern count + per-type breakdown

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

@@ -15,6 +15,55 @@ import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText } from './validate-input.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+let _corpusStatsCache = null;
+// (query, store) → embedding + cosine cache. Small LRU (not size-1): the flywheel
+// scores many configs across several queries in interleaved order, so a size-1
+// cache would thrash. Cap keeps memory bounded; eviction is oldest-first.
+const _cosineCache = new Map();
+const _COSINE_CACHE_MAX = 128;
+function _cosineCacheGet(key) {
+    const v = _cosineCache.get(key);
+    if (v) {
+        _cosineCache.delete(key);
+        _cosineCache.set(key, v);
+    } // LRU touch
+    return v;
+}
+function _cosineCacheSet(key, v) {
+    _cosineCache.set(key, v);
+    if (_cosineCache.size > _COSINE_CACHE_MAX)
+        _cosineCache.delete(_cosineCache.keys().next().value);
+}
+function corpusFingerprint(patterns) {
+    let h = 2166136261 >>> 0;
+    for (const p of patterns) {
+        const s = `${p.id}|${p.name?.length ?? 0}|${p.content?.length ?? 0}`;
+        for (let i = 0; i < s.length; i++) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 16777619) >>> 0;
+        }
+    }
+    return `${patterns.length}:${h.toString(16)}`;
+}
+let _champCache = null;
+function activeChampionParams() {
+    try {
+        if (_champCache && Date.now() - _champCache.at < 30_000)
+            return _champCache.params;
+        const p = join(getProjectCwd(), '.claude-flow', 'harness-active-policy.json');
+        let params = {};
+        if (existsSync(p)) {
+            const active = JSON.parse(readFileSync(p, 'utf-8'));
+            if (active && !active.rolledBack && active.params && typeof active.params === 'object')
+                params = active.params;
+        }
+        _champCache = { at: Date.now(), params };
+        return params;
+    }
+    catch {
+        return {};
+    }
+}
 // Real embeddings — resolved LAZILY on first use.
 // Perf (measured 2026-07): the previous top-level-await version of this block
 // ran `await import('ruvector')` + `initOnnxEmbedder()` + a probe embed at
@@ -159,6 +208,19 @@ function loadNeuralStore() {
     }
     return { models: {}, patterns: {}, version: '3.0.0' };
 }
+/**
+ * ADR-176 flywheel: expose the stored patterns (id/name/content) so the
+ * self-optimizing loop can harvest a benchmark corpus from real usage. Additive,
+ * read-only, never throws.
+ */
+export function getStorePatterns() {
+    try {
+        return Object.values(loadNeuralStore().patterns ?? {}).map((p) => ({ id: p.id, name: p.name, content: p.content }));
+    }
+    catch {
+        return [];
+    }
+}
 function saveNeuralStore(store) {
     ensureNeuralDir();
     writeFileSync(getNeuralPath(), JSON.stringify(store, null, 2), 'utf-8');
@@ -604,13 +666,28 @@ export const neuralTools = [
                 // sub-params than non-rerank (the cross-encoder adds semantic depth,
                 // so the hybrid stage can be more keyword-focused). nDCG@3 0.900 →
                 // 0.963 on rerank just by switching sw 2.0 → 3.0 in the hybrid stage.
-                const alpha = Number(input.alpha ?? 0.5);
-                const mmrLambda = Number(input.mmrLambda ?? 0.7);
+                // Champion-provided defaults (ADR-176/177): explicit input wins, then the
+                // adopted proven-config champion, then the hardcoded ADR-082 defaults.
+                const champ = activeChampionParams();
+                const alpha = Number(input.alpha ?? champ.alpha ?? 0.5);
+                const mmrLambda = Number(input.mmrLambda ?? champ.mmrLambda ?? 0.7);
                 const { tokenize, buildCorpusStats, hybridScores, mmrRerank, multiFieldBM25, typePenalty } = await import('../memory/hybrid-retrieval.js');
-                const queryEmbedding = await generateEmbedding(query, 384);
                 const patterns = Object.values(store.patterns);
-                // Compute cosine for every pattern (this is what the old path did).
-                const cosineArr = patterns.map((p) => cosineSimilarity(queryEmbedding, p.embedding));
+                // Query embedding + cosine array depend only on (query, store) — NOT the
+                // retrieval config. Cache them so scoring many configs for one query
+                // (the flywheel's access pattern) embeds + cosines once, not per config.
+                const _cosKey = `${corpusFingerprint(patterns)}::${query}`;
+                let queryEmbedding, cosineArr;
+                const _hit = _cosineCacheGet(_cosKey);
+                if (_hit) {
+                    queryEmbedding = _hit.queryEmbedding;
+                    cosineArr = _hit.cosineArr;
+                }
+                else {
+                    queryEmbedding = await generateEmbedding(query, 384);
+                    cosineArr = patterns.map((p) => cosineSimilarity(queryEmbedding, p.embedding));
+                    _cosineCacheSet(_cosKey, { queryEmbedding, cosineArr });
+                }
                 if (mode === 'cosine') {
                     const ranked = patterns
                         .map((p, i) => ({ ...p, similarity: cosineArr[i] }))
@@ -630,23 +707,35 @@ export const neuralTools = [
                 // Hybrid path — multi-field BM25 (subject 3×, body 1×) + type penalty
                 // for meta-commits (release bumps / merges) per ADR-079. Falls back
                 // to single-field BM25 when no content is stored.
-                const subjectDocs = patterns.map((p) => tokenize(p.name ?? ''));
-                const bodyDocs = patterns.map((p) => {
-                    // Body is content minus the subject — if content starts with name,
-                    // strip it; otherwise use full content (with name removed if duplicated).
-                    const c = p.content ?? '';
-                    const n = p.name ?? '';
-                    return tokenize(c.startsWith(n) ? c.slice(n.length) : c);
-                });
-                const subjectStats = buildCorpusStats(subjectDocs);
-                const bodyStats = buildCorpusStats(bodyDocs);
+                // Cache the (config-independent) tokenized docs + BM25 stats by store fingerprint.
+                const _fp = corpusFingerprint(patterns);
+                let subjectDocs, bodyDocs, subjectStats, bodyStats;
+                if (_corpusStatsCache && _corpusStatsCache.fp === _fp) {
+                    subjectDocs = _corpusStatsCache.subjectDocs;
+                    bodyDocs = _corpusStatsCache.bodyDocs;
+                    subjectStats = _corpusStatsCache.subjectStats;
+                    bodyStats = _corpusStatsCache.bodyStats;
+                }
+                else {
+                    subjectDocs = patterns.map((p) => tokenize(p.name ?? ''));
+                    bodyDocs = patterns.map((p) => {
+                        // Body is content minus the subject — if content starts with name,
+                        // strip it; otherwise use full content (with name removed if duplicated).
+                        const c = p.content ?? '';
+                        const n = p.name ?? '';
+                        return tokenize(c.startsWith(n) ? c.slice(n.length) : c);
+                    });
+                    subjectStats = buildCorpusStats(subjectDocs);
+                    bodyStats = buildCorpusStats(bodyDocs);
+                    _corpusStatsCache = { fp: _fp, subjectDocs, bodyDocs, subjectStats, bodyStats };
+                }
                 const queryTokens = tokenize(query);
                 // ADR-082: subjectWeight 3.0 → 2.0 from grid (sw=2 dominates at hybrid-only).
                 // ADR-083 joint grid: when rerank is on, the cross-encoder handles
                 // semantic understanding, so the hybrid stage can be MORE
                 // subject-focused (sw=3) — recovers nDCG@3 0.963.
-                const subjectWeight = Number(input.subjectWeight ?? (useRerank ? 3.0 : 2.0));
-                const bodyWeight = Number(input.bodyWeight ?? 1.0);
+                const subjectWeight = Number(input.subjectWeight ?? champ.subjectWeight ?? (useRerank ? 3.0 : 2.0));
+                const bodyWeight = Number(input.bodyWeight ?? champ.bodyWeight ?? 1.0);
                 const bm25Arr = patterns.map((_, i) => multiFieldBM25(queryTokens, subjectDocs[i], bodyDocs[i], subjectStats, bodyStats, subjectWeight, bodyWeight));
                 const baseHybrid = hybridScores(cosineArr, bm25Arr, alpha);
                 // Type penalty — opt-in (default 1.0 = disabled). Ablation in ADR-079
@@ -654,7 +743,7 @@ export const neuralTools = [
                 // penalty enabled) because some relevant work commits also match the
                 // Merge/release regex. Callers wanting aggressive meta-commit
                 // suppression can set {typePenaltyFactor: 0.5}.
-                const typeFactor = Number(input.typePenaltyFactor ?? 1.0);
+                const typeFactor = Number(input.typePenaltyFactor ?? champ.typePenaltyFactor ?? 1.0);
                 const hybridArr = typeFactor === 1.0
                     ? baseHybrid
                     : baseHybrid.map((s, i) => s * typePenalty(patterns[i].name, typeFactor));

package/v3/@claude-flow/cli/dist/src/services/daemon-autostart.d.ts

@@ -0,0 +1,17 @@
+/** True if a live daemon already holds the project's pidfile. */
+export declare function isDaemonAlive(projectRoot: string): boolean;
+export interface EnsureResult {
+    started: boolean;
+    reason?: string;
+}
+/** Spawn `daemon start` detached, reusing all its lock/TTL machinery. Injectable for tests. */
+export type SpawnDaemonFn = (projectRoot: string) => void;
+/**
+ * Ensure a daemon is running for `projectRoot`. No-op when disabled or when one
+ * is already alive. Best-effort; never throws.
+ */
+export declare function ensureDaemonRunning(projectRoot: string, opts?: {
+    spawnFn?: SpawnDaemonFn;
+    isAlive?: (root: string) => boolean;
+}): EnsureResult;
+//# sourceMappingURL=daemon-autostart.d.ts.map

package/v3/@claude-flow/cli/dist/src/services/daemon-autostart.js

@@ -0,0 +1,79 @@
+/**
+ * Self-running daemon (auto-start).
+ *
+ * The self-optimizing loop's workers (distillation, backup, and the future
+ * evolve worker) are inert unless the daemon runs — but it required a manual
+ * `ruflo daemon start`. This ensures a daemon is running on CLI use, SAFELY:
+ *
+ *   - single-instance: only starts when no live daemon holds the pidfile, and
+ *     the spawned `daemon start` independently enforces single-instance via its
+ *     own lock + checkExistingDaemon() — so a race spawns at most one survivor,
+ *   - bounded lifetime: the daemon self-terminates on TTL/idle (12h default,
+ *     RUFLO_DAEMON_TTL_SECS) — auto-start never means "runs forever",
+ *   - opt-out: RUFLO_DAEMON_AUTOSTART=0|false|no disables it entirely,
+ *   - cheap: a pidfile read + a signal-0 liveness check on the fast path,
+ *   - best-effort + silent: never blocks or fails a command.
+ *
+ * Reuses `daemon start` verbatim (all its lock/TTL/worker machinery) — this
+ * module only decides WHETHER to spawn, never reimplements the daemon.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+/** True if a live daemon already holds the project's pidfile. */
+export function isDaemonAlive(projectRoot) {
+    const pidFile = path.join(projectRoot, '.claude-flow', 'daemon.pid');
+    try {
+        if (!fs.existsSync(pidFile))
+            return false;
+        const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+        if (Number.isNaN(pid) || pid === process.pid)
+            return false;
+        process.kill(pid, 0); // signal 0 = existence check
+        return true;
+    }
+    catch {
+        // Dead process → stale pidfile. Clean it so `daemon start` proceeds cleanly.
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { /* ignore */ }
+        return false;
+    }
+}
+function autostartDisabled() {
+    return /^(0|false|no|off)$/i.test(process.env.RUFLO_DAEMON_AUTOSTART ?? '');
+}
+const defaultSpawn = (projectRoot) => {
+    const cliBin = process.argv[1]; // the running bin/cli.js
+    const child = spawn(process.execPath, [cliBin, 'daemon', 'start', '--quiet'], {
+        cwd: projectRoot,
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env },
+    });
+    child.unref();
+};
+/**
+ * Ensure a daemon is running for `projectRoot`. No-op when disabled or when one
+ * is already alive. Best-effort; never throws.
+ */
+export function ensureDaemonRunning(projectRoot, opts = {}) {
+    try {
+        if (autostartDisabled())
+            return { started: false, reason: 'disabled (RUFLO_DAEMON_AUTOSTART=0)' };
+        // Only in an initialized project (avoid scaffolding a daemon in a random dir).
+        if (!fs.existsSync(path.join(projectRoot, '.claude-flow')) && !fs.existsSync(path.join(projectRoot, '.claude'))) {
+            return { started: false, reason: 'not a ruflo project' };
+        }
+        const alive = (opts.isAlive ?? isDaemonAlive)(projectRoot);
+        if (alive)
+            return { started: false, reason: 'already running' };
+        (opts.spawnFn ?? defaultSpawn)(projectRoot);
+        return { started: true };
+    }
+    catch (e) {
+        return { started: false, reason: `error: ${e?.message ?? e}` };
+    }
+}
+//# sourceMappingURL=daemon-autostart.js.map