@claude-flow/cli 3.23.0 → 3.24.0

package/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/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/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

package/dist/src/services/evolve-proof.d.ts

@@ -0,0 +1,247 @@
+import { type PromotionVerdict, type AcceptResult } from './harness-benchmark.js';
+import { type ProvenConfigManifest } from '../config/proven-config.js';
+/**
+ * The promotion rule is versioned so a receipt pins exactly which semantics
+ * decided it. v1+sig = the accept() conjunction AND a statistical-significance
+ * term: the per-held-out-task deltas must have a positive one-sided 95% bootstrap
+ * lower bound, so a small-N mean gain can't ride on noise. The canary term is a
+ * SEPARATE deployment-safety signal (a distinct slice), not held-out dominance.
+ */
+export declare const PROMOTION_RULE_VERSION = "accept/v1+sig";
+export declare const PROOF_LABEL = "single-round proof-of-mechanism";
+export declare const NOT_CLAIMS: readonly ["not flywheel proof", "not compounding learning", "not production learning"];
+export interface HoldoutTask {
+    taskId: string;
+    baselineScore: number;
+    candidateScore: number;
+}
+export interface DecisionReceipt {
+    promotionRuleVersion: string;
+    verdictInputs: PromotionVerdict;
+    result: AcceptResult;
+    significant: boolean;
+    deltaCILow: number;
+    promoted: boolean;
+    reason: string;
+}
+export interface ShadowRegistration {
+    registrationId: string;
+    state: 'shadow';
+    served: false;
+    candidateManifestHash: string;
+    registeredAt: number;
+}
+export interface CostReceipt {
+    usd: number;
+    llmCalls: number;
+    tier: string;
+    notes: string;
+}
+/** Multi-dimensional deltas vs the parent — distinguishes *why* a change is (un)safe. */
+export interface ChangeDeltas {
+    benchmark: number;
+    security: number;
+    cost: number;
+}
+/**
+ * Causal promotion record (not just provenance). Answers *why* a candidate won —
+ * and, aggregated across the lineage, *which mutation classes* reliably pay off.
+ * This is what turns the lineage from an audit trail into a knowledge base.
+ */
+export interface PromotionRecord {
+    parentManifestHash: string | null;
+    candidateManifestHash: string;
+    mutationClass: string;
+    mutationSummary: string;
+    deltas: ChangeDeltas;
+    decisionReceipt: DecisionReceipt;
+}
+/** Regression ancestry — a rejected candidate records the gate that killed it + its ancestor. */
+export interface RegressionRecord {
+    candidateManifestHash: string;
+    ancestor: string | null;
+    mutationClass: string;
+    failureCause: 'holdout' | 'security' | 'drift' | 'replay' | 'governance' | 'canary' | 'significance';
+    failedTerms: string[];
+}
+export interface EvolveReceiptBundle {
+    label: typeof PROOF_LABEL;
+    disclaimers: typeof NOT_CLAIMS;
+    generation: number;
+    parent: string | null;
+    branch: string;
+    kind: 'synthetic' | 'real';
+    createdAt: number;
+    inputHoldoutHash: string;
+    baselineManifestHash: string;
+    candidateManifestHash: string;
+    meetsPromotionRule: {
+        version: string;
+        result: boolean;
+    };
+    decisionReceipt: DecisionReceipt;
+    shadow: ShadowRegistration | null;
+    costReceipt: CostReceipt;
+    mutationClass: string;
+    mutationSummary: string;
+    deltas: ChangeDeltas;
+    promotion: PromotionRecord | null;
+    regression: RegressionRecord | null;
+    holdout: HoldoutTask[];
+    baselineManifest: ProvenConfigManifest;
+    candidateManifest: ProvenConfigManifest;
+}
+/** Classify a policy mutation by which fields changed → a repeatable mutation CLASS + a diff summary. */
+export declare function classifyMutation(baseline: Record<string, number>, candidate: Record<string, number>): {
+    mutationClass: string;
+    mutationSummary: string;
+};
+export interface AssembleOpts {
+    generation: number;
+    parent: string | null;
+    branch: string;
+    now: number;
+    kind: 'synthetic' | 'real';
+    cost: {
+        tier: string;
+        notes: string;
+    };
+    redblue?: 'PASS' | 'FAIL' | 'SKIPPED';
+    drift?: number;
+    canaryRollbackRate?: number;
+    layer?: string;
+    corpus?: string;
+}
+/**
+ * Assemble a receipt bundle from a holdout + configs. This is the SHARED core:
+ * the synthetic proof and a REAL measured round produce byte-identical bundle
+ * structure and run the SAME versioned accept() — so `verifyReceiptBundle`
+ * replays a real bundle exactly as it replays the synthetic fixture.
+ */
+export declare function assembleBundle(baseline: Record<string, number>, candidate: Record<string, number>, holdout: HoldoutTask[], o: AssembleOpts): EvolveReceiptBundle;
+/**
+ * Build a REAL evolve-round receipt bundle from MEASURED holdout scores (live
+ * retrieval over a frozen anchor). Same gate, same replayability as the
+ * synthetic proof — but `kind: 'real'` and the scores come from actual runs.
+ * `redblue` should be 'FAIL' if the candidate regressed a frozen security/anchor
+ * slice; drift from real distribution shift. $0 (no LLM/network on this path).
+ */
+export declare function runRealEvolveRound(opts: {
+    baseline: Record<string, number>;
+    candidate: Record<string, number>;
+    holdout: HoldoutTask[];
+    generation: number;
+    parent: string | null;
+    branch?: string;
+    now: number;
+    redblue?: 'PASS' | 'FAIL' | 'SKIPPED';
+    drift?: number;
+    canaryRollbackRate?: number;
+    corpus: string;
+}): EvolveReceiptBundle;
+/**
+ * Run ONE deterministic synthetic evolve round and produce the receipt bundle.
+ * `now` is injected (no Date in the pure path) for reproducible fixtures.
+ * The default scenario is a strict Pareto improvement (candidate ≥ baseline on
+ * every task, > on the mean) so the full PROMOTE→SHADOW path is exercised; pass
+ * `regress: true` to exercise the REJECT path instead.
+ */
+export declare function runSyntheticProofRound(opts?: {
+    now: number;
+    generation?: number;
+    regress?: boolean;
+    parent?: string | null;
+    branch?: string;
+    baseline?: Record<string, number>;
+    candidate?: Record<string, number>;
+}): EvolveReceiptBundle;
+export interface VerifyReport {
+    valid: boolean;
+    hashChecks: {
+        inputHoldout: boolean;
+        baselineManifest: boolean;
+        candidateManifest: boolean;
+    };
+    recomputed: {
+        baselineHeldOut: number;
+        candidateHeldOut: number;
+        canaryRollbackRate: number;
+        decision: AcceptResult;
+    };
+    decisionMatches: boolean;
+    ruleVersionMatches: boolean;
+    noAutoServe: boolean;
+    causalConsistent: boolean;
+    explanation: string;
+    mismatches: string[];
+}
+/**
+ * Independently verify a receipt bundle WITHOUT trusting any service log: rehash
+ * the embedded holdout + manifests, recompute the held-out means + canary rate
+ * from the embedded per-task scores, RE-RUN the same versioned accept(), and
+ * confirm the recomputed decision equals the recorded one. Also confirms the
+ * SHADOW registration is not served (no auto-serve). Pure; never throws.
+ */
+export declare function verifyReceiptBundle(bundle: EvolveReceiptBundle): VerifyReport;
+export interface LineageTelemetry {
+    generations: number;
+    candidatesEvaluated: number;
+    promotions: number;
+    rejections: number;
+    cumulativeHeldOutImprovement: number;
+    rootHash: string | null;
+    branches: string[];
+    lineageIntact: boolean;
+    allReplayable: boolean;
+    nodes: Array<{
+        generation: number;
+        branch: string;
+        promoted: boolean;
+        parent: string | null;
+        candidateManifestHash: string;
+        mutationClass: string;
+        delta: number;
+        replayable: boolean;
+    }>;
+    problems: string[];
+}
+/**
+ * Reconstruct + audit a lineage DAG. Independently replays every bundle and
+ * checks the graph invariants back to the immutable root. Pure; never throws.
+ */
+export declare function reconstructLineage(bundles: EvolveReceiptBundle[]): LineageTelemetry;
+export interface MutationStat {
+    mutationClass: string;
+    attempts: number;
+    promotions: number;
+    meanDelta: number;
+}
+/**
+ * Aggregate per-mutation-class effectiveness across a lineage. After enough
+ * generations the optimizer can bias toward classes with higher historical
+ * payoff — meta-learning grounded in evidence, not intuition.
+ */
+export declare function mutationEffectiveness(bundles: EvolveReceiptBundle[]): MutationStat[];
+export type PlateauStatus = 'insufficient-data' | 'active' | 'local-optimum' | 'noisy-benchmark' | 'optimizer-failure';
+export interface PlateauReport {
+    status: PlateauStatus;
+    window: number;
+    medianImprovement: number;
+    promotionRate: number;
+    varianceShrinking: boolean;
+    candidateVariance: number;
+    rationale: string;
+}
+/**
+ * Distinguish local optimum vs noisy benchmark vs optimizer failure — rigorously,
+ * not by intuition. Over a rolling window: near-zero median improvement AND low
+ * promotion rate is a plateau; shrinking candidate variance ⇒ converged
+ * (local optimum); high, non-shrinking variance ⇒ the benchmark is noisy; low
+ * variance with no promotions ⇒ the optimizer stopped exploring (failure).
+ */
+export declare function detectPlateau(bundles: EvolveReceiptBundle[], opts?: {
+    window?: number;
+    epsilon?: number;
+    maxPromotionRate?: number;
+}): PlateauReport;
+//# sourceMappingURL=evolve-proof.d.ts.map