claude-flow 3.20.0 → 3.21.1

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

@@ -3983,11 +3983,319 @@ const routerCommand = {
         return { success: true };
     },
 };
+// ============================================================================
+// ADR-150 weight-eft slice — `neural distill export | plan | eval | train`
+//
+// Turns ruflo's captured run transcripts into AUDITED TRAINING DATA + a
+// COST-PARETO measurement + a GPU TRAINING PLAN via the optional
+// `@metaharness/weight-eft` dependency. HARD honesty rule: this ships training
+// DATA + a cost audit + a GPU plan — it does NOT train a model and does NOT
+// "reduce escalation". weight-eft's own `train` never spawns; `resolved` in the
+// captured archive is a PROXY (no SWE-bench gold oracle). Every path degrades
+// gracefully ({degraded:true}) when the optional dep is absent (ADR-150).
+// ============================================================================
+const distillExportCommand = {
+    name: 'export',
+    description: 'Export captured run transcripts → SFT (OpenAI chat) + DPO (TRL preference) JSONL + a guard report (contamination / reward-hack / long-context). $0, offline. Does NOT train.',
+    options: [
+        { name: 'archive', short: 'a', type: 'string', description: 'Run-transcript JSONL to read (default: $CLAUDE_FLOW_RUN_TRANSCRIPTS_PATH or .swarm/run-transcripts.jsonl)' },
+        { name: 'out-dir', short: 'o', type: 'string', description: 'Output dir for sft.jsonl / dpo.jsonl / export-report.json', default: '.claude-flow/neural/weft-export' },
+        { name: 'eval-holdout', type: 'string', description: 'Comma-separated instance_ids reserved for eval (contamination guard). Excluded + asserted-disjoint.' },
+        { name: 'max-tokens', type: 'number', description: 'Per-trajectory token budget (default weight-eft 28000)' },
+        { name: 'truncate', type: 'boolean', description: 'Truncate over-length trajectories instead of dropping', default: 'false' },
+        { name: 'keep-reward-hacked', type: 'boolean', description: 'Disable the reward-hacking filter (debug only; NOT recommended)', default: 'false' },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill export', description: 'Export from the default captured .swarm/run-transcripts.jsonl' },
+        { command: 'claude-flow neural distill export -a runs.jsonl -o ./out --eval-holdout astropy__astropy-1', description: 'Export a specific archive, holding out one instance' },
+    ],
+    action: async (ctx) => {
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const { readRunTranscripts } = await import('../ruvector/run-transcript-recorder.js');
+        const { buildArchiveFromRecords, runExport } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const archivePath = ctx.flags.archive
+            ?? process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS_PATH
+            ?? path.resolve(process.cwd(), '.swarm', 'run-transcripts.jsonl');
+        const { records, malformed } = readRunTranscripts(archivePath);
+        if (records.length === 0) {
+            const msg = `No run transcripts at ${archivePath}. Enable capture with CLAUDE_FLOW_RUN_TRANSCRIPTS=1, or pass --archive <file>.`;
+            if (fmt === 'json')
+                output.writeln(JSON.stringify({ ok: false, archivePath, records: 0, malformed, error: msg }, null, 2));
+            else
+                output.printError(msg);
+            return { success: false, exitCode: 1, data: { archivePath, records: 0 } };
+        }
+        const { trajectories, stats, proxyNote } = buildArchiveFromRecords(records);
+        const holdout = (ctx.flags['eval-holdout'] ?? ctx.flags.evalHoldout)?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+        const maxTokens = (ctx.flags['max-tokens'] ?? ctx.flags.maxTokens) != null ? parseInt(String((ctx.flags['max-tokens'] ?? ctx.flags.maxTokens)), 10) : undefined;
+        const res = await runExport({
+            archive: trajectories,
+            evalHoldout: holdout,
+            maxTokens,
+            truncateOverLength: ctx.flags.truncate === true,
+            dropRewardHacked: (ctx.flags['keep-reward-hacked'] ?? ctx.flags.keepRewardHacked) === true ? false : undefined,
+        });
+        if (res.degraded) {
+            // ADR-150 graceful degradation: dep absent → not a runtime failure.
+            const payload = { degraded: true, reason: res.reason, archiveTrajectories: trajectories.length };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else {
+                output.writeln(output.warning(`weight-eft unavailable (${res.reason}).`));
+                output.writeln(output.dim('Install the optional dep: npm i @metaharness/weight-eft. Archive was built (' + trajectories.length + ' trajectories) but not exported.'));
+            }
+            return { success: true, exitCode: 0, data: payload };
+        }
+        const outDir = path.resolve(process.cwd(), (ctx.flags['out-dir'] ?? ctx.flags.outDir) || '.claude-flow/neural/weft-export');
+        fs.mkdirSync(outDir, { recursive: true });
+        const sftPath = path.join(outDir, 'sft.jsonl');
+        const dpoPath = path.join(outDir, 'dpo.jsonl');
+        const reportPath = path.join(outDir, 'export-report.json');
+        fs.writeFileSync(sftPath, res.sftJsonl);
+        fs.writeFileSync(dpoPath, res.dpoJsonl);
+        fs.writeFileSync(reportPath, JSON.stringify({ report: res.report, archiveStats: stats, proxyNote }, null, 2));
+        const payload = {
+            ok: true, archivePath, outDir, sftPath, dpoPath, reportPath,
+            sftRows: res.sftRows, dpoRows: res.dpoRows, malformed,
+            archiveStats: stats, report: res.report, proxyNote,
+        };
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify(payload, null, 2));
+            return { success: true, data: payload };
+        }
+        output.writeln();
+        output.writeln(output.bold('weight-eft export — audited training data ($0, no model trained)'));
+        output.writeln(`  archive:      ${archivePath} (${records.length} records, ${malformed} malformed skipped)`);
+        output.writeln(`  trajectories: ${stats.total} (cheap ${stats.byTier.cheap} / frontier ${stats.byTier.frontier}), resolved ${stats.resolved}`);
+        output.writeln(`  SFT rows:     ${res.sftRows}  → ${sftPath}`);
+        output.writeln(`  DPO rows:     ${res.dpoRows}  → ${dpoPath}`);
+        output.writeln(`  guards:       holdout=${res.report.excludedByHoldout} reward-hacked=${res.report.droppedRewardHacked} over-length=${res.report.droppedOverLength} truncated=${res.report.truncatedOverLength}`);
+        output.writeln(`  report:       ${reportPath}`);
+        output.writeln();
+        output.writeln(output.warning('resolved provenance: ' + JSON.stringify(stats.byResolvedSource)));
+        output.writeln(output.dim(proxyNote));
+        return { success: true, data: payload };
+    },
+};
+const distillPlanCommand = {
+    name: 'plan',
+    description: 'Print the two-stage (SFT → on-policy DPO) GPU training plan + the exact `ruvllm microlora` commands a GPU host would run. $0 dry-run — NEVER spawns a tune.',
+    options: [
+        { name: 'sft', type: 'string', description: 'Path to sft.jsonl (default: .claude-flow/neural/weft-export/sft.jsonl)' },
+        { name: 'dpo', type: 'string', description: 'Path to dpo.jsonl (default: .claude-flow/neural/weft-export/dpo.jsonl)' },
+        { name: 'base', short: 'b', type: 'string', description: 'Base model id to tune (7-14B band). Default Qwen2.5-Coder-7B-Instruct' },
+        { name: 'params-b', type: 'number', description: 'Base model param count in billions (gate [1,14]). Default 7' },
+        { name: 'adapter-prefix', type: 'string', description: 'Adapter output prefix', default: 'ruflo-weft' },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill plan', description: 'Print the GPU plan for the last export ($0 dry-run)' },
+        { command: 'claude-flow neural distill plan --base Qwen/Qwen2.5-Coder-7B-Instruct --params-b 7', description: 'Plan for a specific base model' },
+    ],
+    action: async (ctx) => {
+        const path = await import('node:path');
+        const { runPlan, DEFAULT_BASE_MODEL } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const sftPath = ctx.flags.sft || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/sft.jsonl');
+        const dpoPath = ctx.flags.dpo || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/dpo.jsonl');
+        const base = ctx.flags.base
+            ? { id: String(ctx.flags.base), paramsB: (ctx.flags['params-b'] ?? ctx.flags.paramsB) != null ? parseInt(String((ctx.flags['params-b'] ?? ctx.flags.paramsB)), 10) : 7 }
+            : DEFAULT_BASE_MODEL;
+        const res = await runPlan({ base, sftPath, dpoPath, adapterPrefix: String((ctx.flags['adapter-prefix'] ?? ctx.flags.adapterPrefix) || 'ruflo-weft') });
+        if (res.degraded) {
+            const payload = { degraded: true, reason: res.reason };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else {
+                output.writeln(output.warning(`weight-eft unavailable (${res.reason}).`));
+                output.writeln(output.dim('Install: npm i @metaharness/weight-eft'));
+            }
+            return { success: true, exitCode: 0, data: payload };
+        }
+        const payload = { ok: true, base: res.base, sft: res.sft, dpo: res.dpo, dryRun: true };
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify(payload, null, 2));
+            return { success: true, data: payload };
+        }
+        output.writeln();
+        output.writeln(output.bold(`weight-eft GPU training plan ($0 dry-run — no tune runs from ruflo)`));
+        output.writeln(`  base model: ${res.base.id} (${res.base.paramsB}B)`);
+        output.writeln(output.dim('  SFT stage:'));
+        output.writeln(`    ${res.sft.summary}`);
+        output.writeln(`    $ ${res.sft.command}`);
+        output.writeln(output.dim('  DPO stage (on-policy, init from SFT adapter):'));
+        output.writeln(`    ${res.dpo.summary}`);
+        output.writeln(`    $ ${res.dpo.command}`);
+        output.writeln();
+        output.writeln(output.dim('These commands run on a GPU host; ruflo does not execute them. See `neural distill train --remote` for a spend-gated remote path.'));
+        return { success: true, data: payload };
+    },
+};
+const distillEvalCommand = {
+    name: 'eval',
+    description: 'Fold two CascadeOutcome[] JSON files (base vs adapter) into the cost-Pareto delta — escalation-rate reduction + $/resolved. $0. Measures cost, does NOT claim a tune ran.',
+    options: [
+        { name: 'base-outcomes', type: 'string', description: 'JSON file: CascadeOutcome[] for the BASE cascade run', required: true },
+        { name: 'adapter-outcomes', type: 'string', description: 'JSON file: CascadeOutcome[] for the ADAPTER cascade run', required: true },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill eval --base-outcomes base.json --adapter-outcomes adapter.json', description: 'Cost-Pareto delta between base and adapter cascade runs' },
+    ],
+    action: async (ctx) => {
+        const fs = await import('node:fs');
+        const { runEval } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const basePath = (ctx.flags['base-outcomes'] ?? ctx.flags.baseOutcomes);
+        const adapterPath = (ctx.flags['adapter-outcomes'] ?? ctx.flags.adapterOutcomes);
+        if (!basePath || !adapterPath) {
+            output.printError('Both --base-outcomes and --adapter-outcomes are required.');
+            return { success: false, exitCode: 2 };
+        }
+        let baseOutcomes;
+        let adapterOutcomes;
+        try {
+            baseOutcomes = JSON.parse(fs.readFileSync(basePath, 'utf8'));
+            adapterOutcomes = JSON.parse(fs.readFileSync(adapterPath, 'utf8'));
+        }
+        catch (e) {
+            output.printError(`Failed to read outcome files: ${e.message}`);
+            return { success: false, exitCode: 1 };
+        }
+        if (!Array.isArray(baseOutcomes) || !Array.isArray(adapterOutcomes)) {
+            output.printError('Both files must contain a JSON array of CascadeOutcome objects.');
+            return { success: false, exitCode: 1 };
+        }
+        const res = await runEval({ baseOutcomes: baseOutcomes, adapterOutcomes: adapterOutcomes });
+        if (res.degraded) {
+            const payload = { degraded: true, reason: res.reason };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else {
+                output.writeln(output.warning(`weight-eft unavailable (${res.reason}).`));
+                output.writeln(output.dim('Install: npm i @metaharness/weight-eft'));
+            }
+            return { success: true, exitCode: 0, data: payload };
+        }
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify({ ok: true, delta: res.delta }, null, 2));
+            return { success: true, data: res.delta };
+        }
+        output.writeln();
+        output.writeln(output.bold('weight-eft cost-Pareto delta (measurement only)'));
+        output.writeln(`  cheap-resolve lift:       ${res.delta.cheapResolveLift.toFixed(4)}`);
+        output.writeln(`  escalation-rate reduction: ${res.delta.escalationRateReduction.toFixed(4)}`);
+        output.writeln(`  $/resolved reduction:      ${res.delta.costPerResolvedReduction.toFixed(6)}`);
+        output.writeln(`  resolve-rate delta:        ${res.delta.resolveRateDelta.toFixed(4)} (expected ≈ 0 — ceiling unmoved)`);
+        output.writeln(`  verdict: ${res.delta.verdict}`);
+        return { success: true, data: res.delta };
+    },
+};
+const distillTrainCommand = {
+    name: 'train',
+    description: 'Remote-GPU LoRA tune over SSH — DRY-RUN by default (prints ssh/rsync/ruvllm commands + read-only preflight). Real compute ONLY with --execute --yes (spends GPU time on YOUR host). Not a $0/local tune.',
+    options: [
+        { name: 'remote', short: 'r', type: 'string', description: 'SSH host or tailscale name (default: $RUFLO_DISTILL_REMOTE). Never hard-coded.' },
+        { name: 'base', short: 'b', type: 'string', description: 'Base model id to tune. Default Qwen2.5-Coder-7B-Instruct' },
+        { name: 'sft', type: 'string', description: 'Local sft.jsonl (default: .claude-flow/neural/weft-export/sft.jsonl)' },
+        { name: 'dpo', type: 'string', description: 'Local dpo.jsonl (default: .claude-flow/neural/weft-export/dpo.jsonl)' },
+        { name: 'adapter-dir', type: 'string', description: 'Local dir to fetch the trained adapter into', default: '.claude-flow/neural' },
+        { name: 'ssh-user', type: 'string', description: 'SSH user (default: current user)' },
+        { name: 'ssh-port', type: 'number', description: 'SSH port', default: '22' },
+        { name: 'remote-workdir', type: 'string', description: 'Remote working dir (default: ~/.ruflo-weft/<runId>)' },
+        { name: 'execute', type: 'boolean', description: 'Opt in to REAL GPU compute on the remote host (still needs --yes)', default: 'false' },
+        { name: 'yes', type: 'boolean', description: 'Second confirmation gate; required with --execute to actually spend', default: 'false' },
+        { name: 'preflight', type: 'boolean', description: 'Opt in to read-only reachability/GPU probes against the host (bare dry-run is fully offline and contacts nothing)', default: 'false' },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill train --remote gpu-box', description: 'OFFLINE DRY-RUN: print the ssh/rsync/ruvllm commands only (no host contact)' },
+        { command: 'claude-flow neural distill train --remote gpu-box --preflight', description: 'DRY-RUN + read-only reachability/GPU probes against the host' },
+        { command: 'RUFLO_DISTILL_REMOTE=gpu-box claude-flow neural distill train --execute --yes', description: 'Run the real remote tune (spends GPU time on your host)' },
+    ],
+    action: async (ctx) => {
+        const path = await import('node:path');
+        const { runRemoteTrain } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const host = ctx.flags.remote || process.env.RUFLO_DISTILL_REMOTE;
+        if (!host) {
+            output.printError('No remote host. Pass --remote <host> or set RUFLO_DISTILL_REMOTE.');
+            return { success: false, exitCode: 2 };
+        }
+        const res = await runRemoteTrain({
+            host,
+            base: ctx.flags.base ? String(ctx.flags.base) : undefined,
+            sftPath: ctx.flags.sft || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/sft.jsonl'),
+            dpoPath: ctx.flags.dpo || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/dpo.jsonl'),
+            adapterDir: (ctx.flags['adapter-dir'] ?? ctx.flags.adapterDir) || '.claude-flow/neural',
+            sshUser: (ctx.flags['ssh-user'] ?? ctx.flags.sshUser) ? String((ctx.flags['ssh-user'] ?? ctx.flags.sshUser)) : undefined,
+            sshPort: (ctx.flags['ssh-port'] ?? ctx.flags.sshPort) != null ? parseInt(String((ctx.flags['ssh-port'] ?? ctx.flags.sshPort)), 10) : undefined,
+            remoteWorkdir: (ctx.flags['remote-workdir'] ?? ctx.flags.remoteWorkdir) ? String((ctx.flags['remote-workdir'] ?? ctx.flags.remoteWorkdir)) : undefined,
+            execute: ctx.flags.execute === true,
+            yes: ctx.flags.yes === true,
+            preflight: ctx.flags.preflight === true,
+        });
+        if ('degraded' in res && res.degraded) {
+            const payload = { degraded: true, reason: res.reason };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else
+                output.writeln(output.warning(`remote-train unavailable (${res.reason}).`));
+            return { success: true, exitCode: 0, data: payload };
+        }
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify(res, null, 2));
+            return { success: res.mode !== 'preflight-failed', data: res };
+        }
+        output.writeln();
+        output.writeln(output.bold(`weight-eft remote-GPU tune [${res.mode}] on ${res.plan.host}`));
+        if (res.mode === 'dry-run')
+            output.writeln(output.dim('DRY-RUN — no data transferred, no training. Re-run with --execute --yes to spend GPU time on your host.'));
+        if (res.reason)
+            output.writeln(output.warning(res.reason));
+        output.writeln(`  base: ${res.plan.base}   remote workdir: ${res.plan.remoteWorkdir}   adapter → ${res.plan.adapterDir}/${res.plan.dpoAdapter}`);
+        if (res.preflight) {
+            output.writeln(output.dim('  preflight (read-only probes):'));
+            for (const p of res.preflight)
+                output.writeln(`    [${p.ok ? 'ok ' : 'FAIL'}] ${p.label}: ${p.detail}`);
+        }
+        output.writeln(output.dim('  commands that ' + (res.mode === 'executed' ? 'ran' : 'WOULD run') + ':'));
+        for (const c of res.plan.humanCommands)
+            output.writeln(`    $ ${c}`);
+        if (res.steps) {
+            output.writeln(output.dim('  execution:'));
+            for (const s of res.steps)
+                output.writeln(`    [${s.ok ? 'ok ' : 'FAIL'}] ${s.label}: ${s.detail}`);
+        }
+        output.writeln();
+        output.writeln(output.dim('Honesty: ruflo does not train locally or at $0. This is an explicit, user-triggered remote-GPU spend. resolved-gold in the SFT data is still a proxy.'));
+        return { success: res.mode !== 'preflight-failed', data: res };
+    },
+};
+const distillCommand = {
+    name: 'distill',
+    description: 'weight-eft training-data + cost-audit slice (ADR-150): export | plan | eval | train. Ships audited SFT/DPO data + a cost-Pareto measurement + a GPU plan. Does NOT train a model or reduce escalation.',
+    subcommands: [distillExportCommand, distillPlanCommand, distillEvalCommand, distillTrainCommand],
+    examples: [
+        { command: 'claude-flow neural distill export', description: 'Captured transcripts → audited SFT/DPO JSONL + guard report ($0)' },
+        { command: 'claude-flow neural distill plan', description: 'Print the GPU training plan + ruvllm commands ($0 dry-run)' },
+        { command: 'claude-flow neural distill eval --base-outcomes b.json --adapter-outcomes a.json', description: 'Cost-Pareto delta ($0)' },
+        { command: 'claude-flow neural distill train --remote gpu-box', description: 'Remote-GPU tune DRY-RUN (spend-gated behind --execute --yes)' },
+    ],
+    action: async () => {
+        output.writeln('Use a subcommand: export | plan | eval | train');
+        output.writeln(output.dim('Ships audited training DATA + a cost audit + a GPU plan. It does NOT train a model or reduce escalation (weight-eft train never spawns; resolved is a proxy).'));
+        return { success: true };
+    },
+};
 // Main neural command
 export const neuralCommand = {
     name: 'neural',
     description: 'Neural pattern training, MoE, Flash Attention, pattern learning',
-    subcommands: [trainCommand, statusCommand, patternsCommand, predictCommand, optimizeCommand, benchmarkCommand, listCommand, exportCommand, importCommand, routerCommand],
+    subcommands: [trainCommand, statusCommand, patternsCommand, predictCommand, optimizeCommand, benchmarkCommand, listCommand, exportCommand, importCommand, routerCommand, distillCommand],
     examples: [
         { command: 'claude-flow neural status', description: 'Check neural system status' },
         { command: 'claude-flow neural train -p coordination', description: 'Train coordination patterns' },

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

@@ -16,6 +16,7 @@ import { generateMCPJson } from './mcp-generator.js';
 import { generateStatuslineScript } from './statusline-generator.js';
 import { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHookHandler, generateIntelligenceStub, generateAutoMemoryHook, generateRufloHookCjs, } from './helpers-generator.js';
 import { generateClaudeMd } from './claudemd-generator.js';
+import { recordMemoryPackagePath } from './memory-package-resolver.js';
 /**
  * Skills to copy based on configuration
  */
@@ -196,6 +197,16 @@ export async function executeInit(options) {
         // Generate helpers
         if (options.components.helpers) {
             await writeHelpers(targetDir, options, result);
+            // #2545: The auto-memory hook needs @claude-flow/memory, which is an
+            // optionalDependency of the CLI and lands in the npx cache — unreachable
+            // by a node_modules walk-up from the user's project. Resolve it from the
+            // CLI's own context now (where it IS present) and record the absolute
+            // path in a machine-local sidecar the hook reads first. Best-effort:
+            // when the optional dep is absent the hook fails loud and doctor flags it.
+            const memRecord = recordMemoryPackagePath(targetDir, 'init');
+            if (memRecord) {
+                result.created.files.push('.claude-flow/memory-package.json');
+            }
         }
         // Generate statusline
         if (options.components.statusline) {
@@ -472,6 +483,12 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 catch { }
             }
         }
+        // #2545: (re)record the resolved @claude-flow/memory path so the auto-memory
+        // hook can find it on the npx install path. Best-effort — see executeInit.
+        const memRecord = recordMemoryPackagePath(targetDir, 'upgrade');
+        if (memRecord) {
+            result.updated.push('.claude-flow/memory-package.json');
+        }
         // 1. ALWAYS update statusline helper (force overwrite)
         const statuslinePath = path.join(targetDir, '.claude', 'helpers', 'statusline.cjs');
         // Use default options with statusline config

package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js

@@ -863,13 +863,37 @@ const DATA_DIR = join(PROJECT_ROOT, '.claude-flow', 'data');
 const STORE_PATH = join(DATA_DIR, 'auto-memory-store.json');
 
 const DIM = '\\x1b[2m';
+const YELLOW = '\\x1b[0;33m';
 const RESET = '\\x1b[0m';
 const dim = (msg) => console.log(\`  \${DIM}\${msg}\${RESET}\`);
 
+// #2545: fail LOUD instead of a silent dim skip when @claude-flow/memory is
+// unresolvable — self-learning imports are a no-op and the user must be told.
+function warnMemoryUnavailable() {
+  const l1 = \`[AutoMemory] @claude-flow/memory not resolvable from \${PROJECT_ROOT} — self-learning imports are DISABLED.\`;
+  const l2 = '             Fix: npm i -D @claude-flow/memory   (or re-run: npx ruflo@latest init, then npx ruflo@latest doctor --fix)';
+  console.log(\`\${YELLOW}\${l1}\${RESET}\`);
+  console.log(\`\${YELLOW}\${l2}\${RESET}\`);
+  process.stderr.write(\`\${l1}\\n\${l2}\\n\`);
+}
+
 // Ensure data dir
 if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
 
 async function loadMemoryPackage() {
+  // Strategy 0 (#2545): sidecar recorded by \`init\` / \`doctor --fix\`. On the npx
+  // path @claude-flow/memory lands in the npx cache (unreachable by walk-up), so
+  // init records its absolute path here — the only strategy that works there.
+  try {
+    const sidecar = join(PROJECT_ROOT, '.claude-flow', 'memory-package.json');
+    if (existsSync(sidecar)) {
+      const rec = JSON.parse(readFileSync(sidecar, 'utf-8'));
+      if (rec && rec.distPath && existsSync(rec.distPath)) {
+        return await import(\`file://\${rec.distPath}\`);
+      }
+    }
+  } catch { /* fall through */ }
+
   // Strategy 1: Use createRequire for CJS-style resolution (handles nested node_modules
   // when installed as a transitive dependency via npx ruflo / npx claude-flow)
   try {
@@ -899,7 +923,7 @@ async function doImport() {
   const memPkg = await loadMemoryPackage();
 
   if (!memPkg || !memPkg.AutoMemoryBridge) {
-    dim('Memory package not available — auto memory import skipped (non-critical)');
+    warnMemoryUnavailable();
     return;
   }
 
@@ -916,7 +940,7 @@ async function doSync() {
   const memPkg = await loadMemoryPackage();
 
   if (!memPkg || !memPkg.AutoMemoryBridge) {
-    dim('Memory package not available — sync skipped (non-critical)');
+    warnMemoryUnavailable();
     return;
   }
 

package/v3/@claude-flow/cli/dist/src/init/memory-package-resolver.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Memory Package Resolver (#2545)
+ *
+ * `@claude-flow/memory` is an *optionalDependency* of `@claude-flow/cli`. On the
+ * documented `npx ruflo` install path it lands in the npx cache
+ * (`~/.npm/_npx/<hash>/node_modules`), which is NOT on the node_modules walk-up
+ * path from the user's project. The SessionStart auto-memory hook therefore
+ * could never resolve it and self-learning silently no-op'd.
+ *
+ * At init time, however, the CLI *can* resolve the package from its own module
+ * context (it is installed alongside the CLI in that same npx cache). We resolve
+ * it once and record the absolute path in a machine-local project sidecar
+ * (`.claude-flow/memory-package.json`). The hook reads this sidecar first, so it
+ * reuses the copy npx already downloaded — no second install, no vendoring.
+ *
+ * This module is deliberately dependency-free and best-effort: nothing here ever
+ * throws into the init/doctor flow.
+ */
+export declare const MEMORY_PACKAGE = "@claude-flow/memory";
+/** Project-relative path of the resolver sidecar written by init / doctor --fix. */
+export declare const MEMORY_SIDECAR_REL: string;
+export interface MemoryPackageRecord {
+    /** Absolute path to the package's main entry (dist/index.js). */
+    distPath: string;
+    /** Resolved package version, if readable. */
+    version: string | null;
+    /** What produced this record ("init" | "doctor" | "upgrade"). */
+    resolvedBy: string;
+    /** ISO timestamp of resolution. */
+    resolvedAt: string;
+}
+/**
+ * Resolve `@claude-flow/memory`'s main entry from the CLI's own module context.
+ * Returns the absolute dist path, or null when the optional dependency is absent
+ * (e.g. installed with `--omit=optional`).
+ */
+export declare function resolveMemoryPackageFromCli(): string | null;
+/**
+ * Resolve `@claude-flow/memory` the same way the runtime hook does, from a target
+ * project directory: sidecar → project package.json → node_modules walk-up.
+ * Used by `doctor` so its verdict matches what the hook will actually experience.
+ */
+export declare function resolveMemoryPackageFromProject(targetDir: string): string | null;
+/** Read the version of the resolved memory package (dist/index.js → ../package.json). */
+export declare function readMemoryPackageVersion(distPath: string): string | null;
+/**
+ * Best-effort: resolve `@claude-flow/memory` from the CLI and record its path in
+ * the project sidecar so the runtime hook can find it on the npx install path.
+ * Returns the written record, or null when the package is not resolvable from the
+ * CLI (in which case the hook fails loud and `doctor` flags it).
+ */
+export declare function recordMemoryPackagePath(targetDir: string, resolvedBy?: string): MemoryPackageRecord | null;
+//# sourceMappingURL=memory-package-resolver.d.ts.map

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

@@ -0,0 +1,118 @@
+/**
+ * Memory Package Resolver (#2545)
+ *
+ * `@claude-flow/memory` is an *optionalDependency* of `@claude-flow/cli`. On the
+ * documented `npx ruflo` install path it lands in the npx cache
+ * (`~/.npm/_npx/<hash>/node_modules`), which is NOT on the node_modules walk-up
+ * path from the user's project. The SessionStart auto-memory hook therefore
+ * could never resolve it and self-learning silently no-op'd.
+ *
+ * At init time, however, the CLI *can* resolve the package from its own module
+ * context (it is installed alongside the CLI in that same npx cache). We resolve
+ * it once and record the absolute path in a machine-local project sidecar
+ * (`.claude-flow/memory-package.json`). The hook reads this sidecar first, so it
+ * reuses the copy npx already downloaded — no second install, no vendoring.
+ *
+ * This module is deliberately dependency-free and best-effort: nothing here ever
+ * throws into the init/doctor flow.
+ */
+import { createRequire } from 'module';
+import * as fs from 'fs';
+import * as path from 'path';
+export const MEMORY_PACKAGE = '@claude-flow/memory';
+/** Project-relative path of the resolver sidecar written by init / doctor --fix. */
+export const MEMORY_SIDECAR_REL = path.join('.claude-flow', 'memory-package.json');
+/**
+ * Resolve `@claude-flow/memory`'s main entry from the CLI's own module context.
+ * Returns the absolute dist path, or null when the optional dependency is absent
+ * (e.g. installed with `--omit=optional`).
+ */
+export function resolveMemoryPackageFromCli() {
+    try {
+        const require = createRequire(import.meta.url);
+        return require.resolve(MEMORY_PACKAGE);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve `@claude-flow/memory` the same way the runtime hook does, from a target
+ * project directory: sidecar → project package.json → node_modules walk-up.
+ * Used by `doctor` so its verdict matches what the hook will actually experience.
+ */
+export function resolveMemoryPackageFromProject(targetDir) {
+    // 1. Sidecar written by a previous init / doctor --fix
+    try {
+        const sidecar = path.join(targetDir, MEMORY_SIDECAR_REL);
+        if (fs.existsSync(sidecar)) {
+            const rec = JSON.parse(fs.readFileSync(sidecar, 'utf-8'));
+            if (rec?.distPath && fs.existsSync(rec.distPath))
+                return rec.distPath;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    // 2. createRequire from the project's package.json (direct/transitive dep)
+    try {
+        const require = createRequire(path.join(targetDir, 'package.json'));
+        return require.resolve(MEMORY_PACKAGE);
+    }
+    catch {
+        /* fall through */
+    }
+    // 3. node_modules walk-up from the project root
+    let dir = path.resolve(targetDir);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const candidate = path.join(dir, 'node_modules', '@claude-flow', 'memory', 'dist', 'index.js');
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Read the version of the resolved memory package (dist/index.js → ../package.json). */
+export function readMemoryPackageVersion(distPath) {
+    try {
+        const pkgJson = path.resolve(path.dirname(distPath), '..', 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            const parsed = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+            return parsed.version ?? null;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+/**
+ * Best-effort: resolve `@claude-flow/memory` from the CLI and record its path in
+ * the project sidecar so the runtime hook can find it on the npx install path.
+ * Returns the written record, or null when the package is not resolvable from the
+ * CLI (in which case the hook fails loud and `doctor` flags it).
+ */
+export function recordMemoryPackagePath(targetDir, resolvedBy = 'init') {
+    const distPath = resolveMemoryPackageFromCli();
+    if (!distPath)
+        return null;
+    const record = {
+        distPath,
+        version: readMemoryPackageVersion(distPath),
+        resolvedBy,
+        resolvedAt: new Date().toISOString(),
+    };
+    try {
+        fs.mkdirSync(path.join(targetDir, '.claude-flow'), { recursive: true });
+        fs.writeFileSync(path.join(targetDir, MEMORY_SIDECAR_REL), JSON.stringify(record, null, 2), 'utf-8');
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=memory-package-resolver.js.map

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

@@ -50,6 +50,9 @@ import { metaharnessTools } from './mcp-tools/metaharness-tools.js';
 // agenticow@~0.2.3 — Copy-On-Write memory branching tools (162-byte branches);
 // optional runtime dep, every handler returns `{degraded: true}` when missing.
 import { agenticowTools } from './mcp-tools/agenticow-tools.js';
+// agenticow step 4 — speculative branch-and-promote (A/B memory exploration).
+// Optional runtime dep, degrades to `{degraded: true}` when agenticow is missing.
+import { agenticowSpeculateTools } from './mcp-tools/agenticow-speculate-tools.js';
 // ADR-164 — AgentBBS federated business-domain BBS rooms (Phase 1).
 // Optional runtime dep, every handler returns `{degraded: true}` when missing.
 import { agentbbsTools } from './mcp-tools/agentbbs-tools.js';
@@ -139,8 +142,10 @@ registerTools([
     ...coverageRouterTools,
     // ADR-150 — MetaHarness static-analysis tools (5)
     ...metaharnessTools,
-    // agenticow@~0.2.3 — COW memory branching (4 tools, graceful-degraded when missing)
+    // agenticow@~0.2.4 — COW memory branching (9 tools: branch/checkpoint/rollback/promote + ingest/query/diff/lineage/status, graceful-degraded when missing)
     ...agenticowTools,
+    // agenticow step 4 — speculative branch-and-promote (1 tool, graceful-degraded when missing)
+    ...agenticowSpeculateTools,
     // ADR-164 — AgentBBS federated business-domain BBS rooms (4 tools, Phase 1, graceful-degraded)
     ...agentbbsTools,
     // ADR-164 Phase 2 + Phase 3 — business_pod_validate + business_pod_route_backend

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js

@@ -512,6 +512,39 @@ export async function executeAgentTask(input) {
             }
             catch { /* never break execution */ }
         }
+        // ADR-150 weight-eft capture seam — the ONLY place a run's full outcome is
+        // known here: prompt (issue), assistant transcript, model, tier, and a
+        // resolved PROXY. Gated behind CLAUDE_FLOW_RUN_TRANSCRIPTS=1 (off by
+        // default; PII/retention surface, mirrors the router trajectory recorder).
+        // HONESTY: `resolved` here is the WEAKEST proxy — 'api-success' means only
+        // that the model returned without an API error, NOT that the output is
+        // correct (ruflo has no SWE-bench gold oracle). model_patch is '' because
+        // this single-shot execute path produces no unified diff. Both facts are
+        // stamped so no downstream weight-eft export mistakes this for gold data.
+        if (process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS === '1') {
+            try {
+                const { recordRunTranscript, tierForModel } = await import('../ruvector/run-transcript-recorder.js');
+                const modelId = agent.modelId ?? String(agent.model ?? 'unknown');
+                const messages = [];
+                if (systemPrompt)
+                    messages.push({ role: 'system', content: systemPrompt });
+                messages.push({ role: 'user', content: input.prompt });
+                if (result.success && typeof result.output === 'string') {
+                    messages.push({ role: 'assistant', content: result.output });
+                }
+                recordRunTranscript({
+                    task: input.prompt,
+                    model: modelId,
+                    tier: tierForModel(modelId),
+                    resolved: outcome === 'success',
+                    resolvedSource: 'api-success',
+                    messages,
+                    source: 'agent-execute',
+                    tokens: result.usage ? { input: result.usage.inputTokens, output: result.usage.outputTokens } : undefined,
+                });
+            }
+            catch { /* never break execution */ }
+        }
     }
     catch {
         // Silent — bandit feedback must never block routing.