From ee8da61113b467254d88bf1f4c60cb664337d345 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Fri, 29 May 2026 14:38:04 -0700
Subject: [PATCH] feat: self-improvement eval harness + upstream findings
 (decoupled from blocked statusline panel)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lands the completed, standalone parts of the self-improvement investigation as new
files only (no shell/statusline/resync changes): the in-process route Q-learner proof
harness (ruflo-improvement-eval), the retired version-gated route-learning shim, the
findings writeup, and the historical plan/spec.

The findings doc is reconciled to truth-of-record: F3 and F4 are filed as two separate,
independently-reproduced upstream issues (ruvnet/ruflo#2239, ruvnet/ruvector#519), F4's
framing corrected against actual ruvector source (learn_from_feedback no-op + single-step
REINFORCE Δ=0 + up-only adaptation, not 'apply() inert'). The live RL statusline panel
carry-forward is tracked in #8, gated on both upstream fixes.

Supersedes PR #2 (closed unmerged): same artifacts, conflict-free as new files, with the
blocked statusline-coupled work left to #8.
---
 CLAUDE.md                                     |  50 ++
 bin/ruflo-improvement-eval                    | 218 ++++++
 bin/ruflo-patch-route-learning                | 118 ++++
 .../plans/2026-05-28-self-improvement-eval.md | 638 ++++++++++++++++++
 ...2026-05-28-self-improvement-eval-design.md | 283 ++++++++
 .../ruflo-self-improvement-findings.md        | 164 +++++
 6 files changed, 1471 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100755 bin/ruflo-improvement-eval
 create mode 100755 bin/ruflo-patch-route-learning
 create mode 100644 docs/superpowers/plans/2026-05-28-self-improvement-eval.md
 create mode 100644 docs/superpowers/specs/2026-05-28-self-improvement-eval-design.md
 create mode 100644 docs/upstream/ruflo-self-improvement-findings.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..b567c4b6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,50 @@
+<!-- Project-scoped config for the ruflo-machine-ref kit. The machine-wide ruflo + agentic-qe
+     reference (operating rules, agent coordination, swarm/routing, the full ruflo CLI surface)
+     lives in the global ~/.claude/CLAUDE.md — do NOT duplicate it here; defer to it. -->
+
+# ruflo-machine-ref — project notes
+
+This repo **is** the kit that installs/repairs ruflo + agentic-qe machine-wide. It is not a
+typical app — it's a set of Bash + Node (ESM) helpers plus a managed block that gets merged
+into the global `~/.claude/CLAUDE.md`. Anything generic (rules, SendMessage coordination,
+swarm defaults, the ruflo CLI reference) is in the **global** `~/.claude/CLAUDE.md`; this file
+holds only what's specific to developing *this* repo.
+
+## Layout
+
+| Path | What it is |
+|------|------------|
+| `bin/` | Standalone helpers (`ruflo-enable-learning`, `ruflo-patch-native`, `ruflo-improvement-eval`, …). Each sources `ruflo-lib.sh` and supports `--help`. |
+| `shell/ruflo-functions.sh` | Shell functions sourced into the user's rc (`ruflo-resync`, `ruflo-onboard`, `ruflo-reference-refresh`, …). |
+| `shell/ruflo-lib.sh` | Shared helpers (colors, `run`/`have`, daemon parser, native-better-sqlite3 primitives). Deployed to `~/.config/ruflo/` so `bin/` scripts can source it from a stable path. |
+| `claude/ruflo-reference.md` | The machine-wide reference block. `install.sh` stages it to `~/.config/ruflo/claude-md-template.md` and merges it into `~/.claude/CLAUDE.md` between `<!-- BEGIN/END ruflo-reference -->` sentinels. |
+| `install.sh` / `uninstall.sh` | Entry points (idempotent; honor `DRY=1`). |
+| `docs/` | `BACKGROUND.md`, `TROUBLESHOOTING.md`, `upstream/` (findings filed upstream), `superpowers/{plans,specs}/` (dated design records — keep as history). |
+
+## Build & test (there is no build system)
+
+No `package.json`, no Makefile, no CI. Validate changes with:
+
+```bash
+bash -n shell/*.sh bin/<script>          # syntax-check shell
+node --check bin/<node-script>           # syntax-check node (ESM) helpers
+bin/<script> --help                      # smoke-test the help/usage path
+bin/ruflo-parity-test                    # cross-shell/native parity checks
+```
+
+Run the relevant helper end-to-end against a scratch dir when it mutates state (most write to
+`/tmp` or take a target path). `ruflo --version`-gate anything that patches the global install.
+
+## Conventions
+
+- **Defer to global, don't duplicate.** If guidance is generic ruflo/agentic-qe behavior, it
+  belongs in `claude/ruflo-reference.md` (→ global), not here.
+- **Dogfooding artifacts are not source.** Running `ruflo init`/`aqe init`/`ruflo-onboard`
+  against this repo writes `.agentic-qe/`, `.claude/`, `*.db`, and `CLAUDE.md.{backup,pre-ruflo}`
+  — all gitignored. Never commit them.
+- **Patches to the global ruflo/agentic-qe dist must be version-gated and idempotent**, with a
+  clear no-op + message once the fix is upstream (see `bin/ruflo-patch-route-learning`).
+- **Commit attribution:** no `Co-Authored-By` trailer unless `.claude/settings.json` sets
+  `attribution.commit` (per the global rule).
+- Design work lands as a dated plan + spec under `docs/superpowers/`; supersede rather than
+  delete, so the history of *where we've been* stays legible.
diff --git a/bin/ruflo-improvement-eval b/bin/ruflo-improvement-eval
new file mode 100755
index 00000000..6f1db8b2
--- /dev/null
+++ b/bin/ruflo-improvement-eval
@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+//
+// ruflo-improvement-eval — prove (or honestly refute) that ruflo's route Q-learner self-improves.
+//
+// Runs IN ONE PROCESS against ruflo's real createQLearningRouter (the CLI `route feedback`
+// path can't accumulate without ruflo-patch-route-learning — finding F2). Synthetic-reward
+// environment: each task has a known-best agent; reward = match. Measures cold-baseline vs
+// trained held-out accuracy (greedy, no updates) with a no-learning ablation control and N
+// seeds, then computes an academically-grounded verdict (one-sided permutation test p +
+// Cohen's d + above-chance). Writes .claude-flow/improvement.json and prints the result.
+//
+// Usage:
+//   ruflo-improvement-eval                 # default: 300 episodes, 5 seeds
+//   ruflo-improvement-eval --smoke         # fast: 120 episodes, 3 seeds (mechanism check)
+//   ruflo-improvement-eval --episodes N --seeds M --checkpoints 0,25,50,...
+//   ruflo-improvement-eval --json          # machine-readable result to stdout
+//   ruflo-improvement-eval --check         # print last cached improvement.json, no run
+//   ruflo-improvement-eval --cli-check     # verify CLI feedback persists (F2 fix applied?)
+//   ruflo-improvement-eval --probe-states  # assert each task maps to a distinct Q-state
+//   ruflo-improvement-eval --inspect-decision   # print one raw router decision (shape)
+//   ruflo-improvement-eval --help
+//
+// Exit: 0 self-improvement demonstrated / 1 not demonstrated / 2 environment error
+import { createRequire } from 'node:module';
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+const has = (f) => args.includes(f);
+const val = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i + 1] ? args[i + 1] : d; };
+
+if (has('-h') || has('--help')) {
+  console.log(readFileSync(new URL(import.meta.url), 'utf8').split('\n').slice(2, 27).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
+  process.exit(0);
+}
+
+const C = process.stdout.isTTY
+  ? { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', dim: '\x1b[2m', cyan: '\x1b[1;36m', r: '\x1b[0m' }
+  : { ok: '', warn: '', fail: '', dim: '', cyan: '', r: '' };
+const ok = (s) => console.log(`${C.ok}✓${C.r} ${s}`);
+const fail = (s) => console.log(`${C.fail}✗${C.r} ${s}`);
+
+// ── Resolve ruflo's real Q-learning router from the global install ──────────
+function resolveRouterIdx() {
+  let groot;
+  try { groot = execSync('npm root -g', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch { return null; }
+  const cliPkg = join(groot, 'ruflo', 'node_modules', '@claude-flow', 'cli', 'package.json');
+  if (!existsSync(cliPkg)) return null;
+  try { return createRequire(cliPkg).resolve('./dist/src/ruvector/index.js'); } catch { return null; }
+}
+
+// ── --cli-check: does CLI `route feedback` persist? ─────────────────────────
+// F2 (route feedback never saveModel()'d) is FIXED UPSTREAM in ruflo 3.10.6 (#2222):
+// feedbackCommand now calls `await router.saveModel()`. So persistence holds on >=3.10.6
+// regardless of autoSaveInterval. On <3.10.6 it holds only if the legacy stopgap
+// (autoSaveInterval:1, via ruflo-patch-route-learning) has been applied.
+if (has('--cli-check')) {
+  let groot; try { groot = execSync('npm root -g', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch { groot = ''; }
+  let ver = ''; try { ver = (execSync('ruflo --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().match(/\d+\.\d+\.\d+/) || [''])[0]; } catch { /* unknown */ }
+  const ge = (v, a, b, c) => { const [x, y, z] = (v || '0.0.0').split('.').map(Number); return x > a || (x === a && (y > b || (y === b && z >= c))); };
+  const upstreamFixed = ver && ge(ver, 3, 10, 6);
+  const route = join(groot, 'ruflo', 'node_modules', '@claude-flow', 'cli', 'dist', 'src', 'commands', 'route.js');
+  const hasSaveModel = existsSync(route) && /feedbackCommand[\s\S]{0,2000}saveModel\(\)/.test(readFileSync(route, 'utf8'));
+  const ql = join(groot, 'ruflo', 'node_modules', '@claude-flow', 'cli', 'dist', 'src', 'ruvector', 'q-learning-router.js');
+  const legacyStopgap = existsSync(ql) && /autoSaveInterval: 1,/.test(readFileSync(ql, 'utf8'));
+  const persists = upstreamFixed || hasSaveModel || legacyStopgap;
+  if (upstreamFixed || hasSaveModel) {
+    console.log(`${C.ok}✓${C.r} CLI 'route feedback' persists — fixed upstream in ruflo 3.10.6 (#2222), saveModel() after feedback (ruflo ${ver || '>=3.10.6'}). The kit's autoSaveInterval stopgap is retired.`);
+  } else if (legacyStopgap) {
+    console.log(`${C.ok}✓${C.r} CLI 'route feedback' persists via the legacy stopgap (autoSaveInterval:1) on ruflo ${ver || '<3.10.6'}. Upgrade to >=3.10.6 to retire it.`);
+  } else {
+    console.log(`${C.warn}⚠${C.r}  CLI 'route feedback' does NOT persist on ruflo ${ver || '<3.10.6'}. Upgrade to >=3.10.6 (recommended) or run ruflo-patch-route-learning (legacy stopgap).`);
+  }
+  process.exit(persists ? 0 : 1);
+}
+
+const routerIdx = resolveRouterIdx();
+if (!routerIdx) { fail("Could not resolve ruflo's Q-learning router. Install ruflo globally (npm i -g ruflo)."); process.exit(2); }
+const { createQLearningRouter } = await import(routerIdx);
+
+// ── Synthetic-reward environment ────────────────────────────────────────────
+// ruflo's state encoder (q-learning-router.js extractFeatures) keys on the FIRST 32
+// FEATURE_KEYWORDS (6 clean categories: code/test/review/architect/research/optimize) plus
+// length/word-count buckets. Debug/document keywords (index ≥32) are NOT encoded, so we use
+// the 6 encodable categories. Each task uses distinct in-category keywords → a distinct
+// Q-state; `evalq` is the same keyword-bag reordered (identical state, different surface
+// string) — evaluated GREEDILY with no updates. This proves the router learns the optimal
+// action per state and exploits it after training (vs a no-learning ablation), on a fixed
+// task distribution. It does NOT claim generalization to unseen states (tabular Q — see spec F3).
+// FINDING (verified): ruflo's encoder (featureVectorToKey) keys largely on length/word-count
+// buckets — semantically-distinct keyword tasks collapse to ONE Q-state. So we engineer each
+// task to occupy a DISTINCT Q-state (distinct word count → distinct bucket) with a fixed
+// optimal agent. evalq = the same word-bag reversed (identical state, different surface
+// string), evaluated greedily. The proof — the learner discovers the optimal action per state
+// and exploits it (vs a no-learning ablation) — is valid regardless of what drives the state.
+const AGENTS6 = ['tester', 'coder', 'reviewer', 'architect', 'researcher', 'optimizer'];
+const ENV = AGENTS6.map((agent, i) => {
+  const n = 4 + i * 5;                                   // 4,9,14,19,24,29 words → distinct buckets
+  const words = Array.from({ length: n }, (_, j) => `t${i}w${j}`);
+  return { agent, train: words.join(' '), evalq: words.slice().reverse().join(' ') };
+});
+const HIT = 1, MISS = -1;
+
+// Extract the chosen agent id from a router decision (shape confirmed via --inspect-decision).
+function decide(router, task, explore) {
+  const d = router.route ? router.route(task, explore) : router.selectAction(task, explore);
+  return (d && (d.agent || d.action || d.route || d.selectedAgent || d.recommendedAgent)) || (typeof d === 'string' ? d : null);
+}
+function newRouter() { const r = createQLearningRouter({ modelPath: '/tmp/.ruflo-eval-' + process.pid + '.json', autoSaveInterval: 1e9 }); return r; }
+
+if (has('--inspect-decision')) {
+  const r = newRouter(); await r.initialize();
+  console.log('raw decision:', JSON.stringify(r.route ? r.route(ENV[0].train, false) : r.selectAction(ENV[0].train, false)));
+  process.exit(0);
+}
+if (has('--probe-states')) {
+  const r = newRouter(); await r.initialize(); if (r.reset) r.reset();
+  for (const e of ENV) r.update(e.train, e.agent, HIT);
+  const n = r.getStats().qTableSize;
+  console.log(`distinct Q-states for ${ENV.length} train tasks: ${n}`);
+  process.exit(n >= ENV.length ? 0 : 1);
+}
+
+// ── Protocol ────────────────────────────────────────────────────────────────
+function evalAccuracy(router) { let h = 0; for (const e of ENV) if (decide(router, e.evalq, false) === e.agent) h++; return h / ENV.length; }
+async function runOnce({ episodes, checkpoints, ablation }) {
+  const router = newRouter(); await router.initialize(); if (router.reset) router.reset();
+  const curve = [{ k: 0, acc: evalAccuracy(router) }];
+  const cps = new Set(checkpoints);
+  for (let k = 1; k <= episodes; k++) {
+    const e = ENV[(k - 1) % ENV.length];
+    const chosen = decide(router, e.train, true);
+    if (!ablation) router.update(e.train, chosen, chosen === e.agent ? HIT : MISS);
+    if (cps.has(k)) curve.push({ k, acc: evalAccuracy(router) });
+  }
+  if (!cps.has(episodes)) curve.push({ k: episodes, acc: evalAccuracy(router) });
+  const s = router.getStats();
+  return { curve, stats: { epsilon: s.epsilon, tdError: s.avgTDError, qSize: s.qTableSize, updates: s.updateCount } };
+}
+
+// ── Statistics (no external deps) ───────────────────────────────────────────
+const mean = (a) => a.reduce((x, y) => x + y, 0) / a.length;
+const ci95 = (a) => { if (a.length < 2) return 0; const m = mean(a), v = a.reduce((s, x) => s + (x - m) ** 2, 0) / (a.length - 1); return 1.96 * Math.sqrt(v / a.length); };
+const spark = (xs) => { const b = '▁▂▃▄▅▆▇█'; return xs.map(x => b[Math.min(7, Math.max(0, Math.round(x * 7)))]).join(''); };
+const sampVar = (a) => a.length < 2 ? 0 : a.reduce((s, x) => s + (x - mean(a)) ** 2, 0) / (a.length - 1);
+function cohensD(a, b) { const sp = Math.sqrt(((a.length - 1) * sampVar(a) + (b.length - 1) * sampVar(b)) / Math.max(1, a.length + b.length - 2)); return sp === 0 ? (mean(a) > mean(b) ? Infinity : 0) : (mean(a) - mean(b)) / sp; }
+function* combos(arr, k, start = 0, acc = []) { if (acc.length === k) { yield acc; return; } for (let i = start; i < arr.length; i++) yield* combos(arr, k, i + 1, acc.concat(arr[i])); }
+function permP(learn, abl) {
+  const obs = mean(learn) - mean(abl), pool = learn.concat(abl), n = learn.length, idx = [...pool.keys()];
+  let ge = 0, total = 0;
+  if (pool.length <= 14) { for (const c of combos(idx, n)) { const set = new Set(c); const A = pool.filter((_, i) => set.has(i)), B = pool.filter((_, i) => !set.has(i)); if (mean(A) - mean(B) >= obs - 1e-12) ge++; total++; } }
+  else { total = 10000; for (let s = 0; s < total; s++) { const sh = [...pool]; for (let i = sh.length - 1; i > 0; i--) { const j = Math.floor(Math.random() * (i + 1));[sh[i], sh[j]] = [sh[j], sh[i]]; } if (mean(sh.slice(0, n)) - mean(sh.slice(n)) >= obs - 1e-12) ge++; } }
+  return ge / total;
+}
+function spearman(curve) {
+  const n = curve.length; if (n < 3) return 0;
+  const rank = (xs) => { const s = xs.map((v, i) => [v, i]).sort((a, b) => a[0] - b[0]); const r = Array(xs.length); s.forEach(([, i], j) => r[i] = j + 1); return r; };
+  const rk = rank(curve.map(c => c.k)), ra = rank(curve.map(c => c.acc)), mr = (n + 1) / 2;
+  let num = 0, dk = 0, da = 0; for (let i = 0; i < n; i++) { num += (rk[i] - mr) * (ra[i] - mr); dk += (rk[i] - mr) ** 2; da += (ra[i] - mr) ** 2; }
+  return (dk && da) ? num / Math.sqrt(dk * da) : 0;
+}
+
+// ── --check: print last cached result ───────────────────────────────────────
+if (has('--check')) {
+  const p = join('.claude-flow', 'improvement.json');
+  if (!existsSync(p)) { console.log('No .claude-flow/improvement.json — run ruflo-improvement-eval first.'); process.exit(2); }
+  const r = JSON.parse(readFileSync(p, 'utf8'));
+  console.log(`${r.verdict}  ${spark(r.curve.map(c => c.acc))}  cold ${Math.round(r.coldAcc * 100)}%→warm ${Math.round(r.warmAcc * 100)}%  Δ${r.deltaPP}pp  p${r.pValue < 0.001 ? '<.001' : '=' + r.pValue}  d=${r.cohensD}  ε→${r.epsilonF.toFixed(2)}  δ̄${r.tdError.toFixed(3)}  |Q|${r.qSize}`);
+  process.exit(r.verdict === 'PASS' ? 0 : 1);
+}
+
+// ── Run the experiment ───────────────────────────────────────────────────────
+// Note: with a one-sided permutation test the minimum achievable p is 1/C(2N,N), so N≥5
+// seeds are needed to reach p<0.05 (N=5 → min p≈0.004). --smoke keeps 5 seeds, fewer episodes.
+const EPISODES = has('--smoke') ? 90 : parseInt(val('--episodes', '300'), 10);
+const SEEDS = parseInt(val('--seeds', '5'), 10);
+const CHECKPOINTS = (val('--checkpoints', has('--smoke') ? '0,30,60,90' : '0,25,50,100,200,300')).split(',').map(n => parseInt(n, 10)).filter(n => n <= EPISODES);
+
+const learnRuns = [], ablRuns = [];
+for (let s = 0; s < SEEDS; s++) learnRuns.push(await runOnce({ episodes: EPISODES, checkpoints: CHECKPOINTS, ablation: false }));
+for (let s = 0; s < SEEDS; s++) ablRuns.push(await runOnce({ episodes: EPISODES, checkpoints: CHECKPOINTS, ablation: true }));
+
+const curveMean = learnRuns[0].curve.map((p, i) => ({ k: p.k, acc: mean(learnRuns.map(r => r.curve[i].acc)) }));
+const warmSeeds = learnRuns.map(r => r.curve[r.curve.length - 1].acc);
+const ablSeeds = ablRuns.map(r => r.curve[r.curve.length - 1].acc);
+const coldAcc = curveMean[0].acc, warmAcc = mean(warmSeeds), warmCI = ci95(warmSeeds), ablAcc = mean(ablSeeds);
+const chance = 1 / ENV.length, st = learnRuns[learnRuns.length - 1].stats, deltaPP = Math.round((warmAcc - coldAcc) * 100);
+const pValue = permP(warmSeeds, ablSeeds), d = cohensD(warmSeeds, ablSeeds), rho = spearman(curveMean);
+const aboveChance = (warmAcc - warmCI) > chance;
+
+// Pre-registered, academically-grounded PASS: causal significance + effect size + above chance.
+const ALPHA = 0.05, D_MIN = 0.8;
+const verdict = (pValue < ALPHA && d >= D_MIN && aboveChance) ? 'PASS' : 'FAIL';
+
+const result = {
+  curve: curveMean, coldAcc, warmAcc, deltaPP, ci95: Math.round(warmCI * 100), ablationAcc: ablAcc, chance,
+  pValue: +pValue.toFixed(4), cohensD: (d === Infinity ? 999 : +d.toFixed(2)), spearman: +rho.toFixed(2), aboveChance,
+  alpha: ALPHA, dMin: D_MIN, epsilon0: 1.0, epsilonF: st.epsilon, tdError: st.tdError, qSize: st.qSize,
+  episodes: EPISODES, seeds: SEEDS, verdict, ts: Math.floor(Date.now() / 1000),
+};
+mkdirSync('.claude-flow', { recursive: true });
+writeFileSync(join('.claude-flow', 'improvement.json'), JSON.stringify(result, null, 2));
+
+if (has('--json')) { console.log(JSON.stringify(result)); process.exit(verdict === 'PASS' ? 0 : 1); }
+
+console.log('');
+console.log(`${C.cyan}Self-improvement eval${C.r}  (route Q-learner · ${SEEDS} seeds × ${EPISODES} episodes · learning vs no-learning ablation)`);
+console.log(`  learning curve  ${spark(curveMean.map(p => p.acc))}  ${curveMean.map(p => `${p.k}:${Math.round(p.acc * 100)}%`).join('  ')}`);
+console.log(`  held-out acc    cold ${Math.round(coldAcc * 100)}% → warm ${Math.round(warmAcc * 100)}%   Δ${deltaPP >= 0 ? '+' : ''}${deltaPP}pp (95% CI ±${Math.round(warmCI * 100)})`);
+console.log(`  ablation        ${Math.round(ablAcc * 100)}%   ·   chance ${Math.round(chance * 100)}%   ·   above-chance: ${aboveChance ? 'yes' : 'no'}`);
+console.log(`  significance    permutation p ${pValue < 0.001 ? '<0.001' : '=' + pValue.toFixed(3)}   ·   Cohen's d ${d === Infinity ? '∞' : d.toFixed(2)}   ·   Spearman ρ(K,acc) ${rho.toFixed(2)}`);
+console.log(`  convergence     ε ${result.epsilon0}→${st.epsilon.toFixed(2)}   δ̄ ${st.tdError.toFixed(3)}   |Q| ${st.qSize}`);
+console.log('');
+verdict === 'PASS'
+  ? ok(`SELF-IMPROVEMENT DEMONSTRATED — learning beat the no-learning ablation (p<${ALPHA}, d=${d === Infinity ? '∞' : d.toFixed(2)}), held-out +${deltaPP}pp, above chance. → .claude-flow/improvement.json`)
+  : fail(`NOT demonstrated — fails the pre-registered test (p=${pValue.toFixed(3)}, d=${d === Infinity ? '∞' : d.toFixed(2)}, above-chance=${aboveChance}). Honest negative result → .claude-flow/improvement.json`);
+process.exit(verdict === 'PASS' ? 0 : 1);
diff --git a/bin/ruflo-patch-route-learning b/bin/ruflo-patch-route-learning
new file mode 100755
index 00000000..cbd10af8
--- /dev/null
+++ b/bin/ruflo-patch-route-learning
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+#
+# ruflo-patch-route-learning — RETIRED on ruflo >= 3.10.6 (fix is upstream).
+#
+# HISTORY (bug F2): `route feedback` (route.js feedbackCommand) called the learner's
+# update() but never saveModel(), and q-learning-router.js defaulted `autoSaveInterval: 100`.
+# Each CLI call is a fresh process that loads the model, applies ONE update, and exits before
+# the %100 auto-save fires — so the persisted model never advanced and `ruflo route stats`
+# stayed at `Update Count 0 / Epsilon 1.0`. This kit shipped a stopgap that set
+# `autoSaveInterval: 1`. We reported it upstream; @pacphi is credited in the 3.10.6 notes.
+#
+# FIXED UPSTREAM:
+#   • ruflo 3.10.6 (#2222) — feedbackCommand now calls `await router.saveModel()` after the
+#     update, so CLI feedback persists. The autoSaveInterval stopgap is no longer needed.
+#   • ruflo 3.10.7        — follow-up: `route feedback -r -1.0` had been parsed as +1.0 (the
+#     flag parser dropped '-'-prefixed values), so NEGATIVE feedback reinforced the bad agent.
+#     Fixed in parser.ts. (Our in-process eval bypassed the CLI parser, so we never hit it.)
+#   • ruflo 3.10.8        — stale route-cache (Bug B) + `--explore false` ignored (Bug C).
+#
+# Therefore on ruflo >= 3.10.6 this script is a NO-OP and simply confirms the upstream fix.
+# It still applies the legacy `autoSaveInterval: 1` stopgap on installs < 3.10.6 (with an
+# upgrade nudge). Carry-forward scope for the route learner now lives in F3 (state-encoder
+# collapse) and F4 (LoRA/SONA not consumed) — see docs/upstream/ruflo-self-improvement-findings.md.
+#
+# Usage:
+#   ruflo-patch-route-learning           # report upstream status; legacy stopgap only on <3.10.6
+#   ruflo-patch-route-learning --check    # report only, change nothing
+#   ruflo-patch-route-learning --help
+#
+# Exit: 0 fixed upstream / patched (legacy) · 1 verify failed · 2 environment error
+set -u
+MODE="apply"
+case "${1:-}" in
+	--check) MODE="check" ;;
+	-h|--help) sed -n '3,29p' "$0" | sed 's|^# \{0,1\}||'; exit 0 ;;
+	"") ;;
+	*) echo "Unknown flag: $1 (try --help)" >&2; exit 2 ;;
+esac
+
+if [[ -t 1 ]]; then C_OK=$'\033[32m'; C_WARN=$'\033[33m'; C_FAIL=$'\033[31m'; C_DIM=$'\033[2m'; C_R=$'\033[0m'
+else C_OK=""; C_WARN=""; C_FAIL=""; C_DIM=""; C_R=""; fi
+ok()   { printf '%s✓%s %s\n' "$C_OK" "$C_R" "$*"; }
+warn() { printf '%s⚠%s  %s\n' "$C_WARN" "$C_R" "$*"; }
+fail() { printf '%s✗%s %s\n' "$C_FAIL" "$C_R" "$*"; }
+
+command -v npm >/dev/null 2>&1 && command -v node >/dev/null 2>&1 && command -v ruflo >/dev/null 2>&1 \
+	|| { fail "npm/node/ruflo must be on PATH"; exit 2; }
+
+# ── Version gate: >= 3.10.6 means the #2222 fix is upstream → this patch is retired ──
+ver="$(ruflo --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+ge_3_10_6=0
+if [ -n "$ver" ]; then
+	IFS=. read -r vmaj vmin vpat <<<"$ver"
+	if [ "${vmaj:-0}" -gt 3 ] 2>/dev/null; then ge_3_10_6=1
+	elif [ "${vmaj:-0}" -eq 3 ] 2>/dev/null; then
+		if [ "${vmin:-0}" -gt 10 ] 2>/dev/null; then ge_3_10_6=1
+		elif [ "${vmin:-0}" -eq 10 ] 2>/dev/null && [ "${vpat:-0}" -ge 6 ] 2>/dev/null; then ge_3_10_6=1
+		fi
+	fi
+fi
+
+if [ "$ge_3_10_6" -eq 1 ]; then
+	ok "RETIRED: route-feedback persistence is fixed upstream in ruflo 3.10.6 (#2222) — you are on ${ver}."
+	printf '%s   feedbackCommand now calls await router.saveModel(); no kit patch needed.%s\n' "$C_DIM" "$C_R"
+	printf '%s   Carry-forward (still open): F3 state-encoder collapse, F4 LoRA/SONA not consumed.%s\n' "$C_DIM" "$C_R"
+	printf '%s   See docs/upstream/ruflo-self-improvement-findings.md%s\n' "$C_DIM" "$C_R"
+	exit 0
+fi
+
+# ── Legacy path: ruflo < 3.10.6 (or version undetectable) — apply the autoSaveInterval stopgap ──
+warn "ruflo ${ver:-<unknown>} predates the 3.10.6 (#2222) upstream fix — applying the legacy stopgap."
+printf '%s   Recommended: npm install -g ruflo@latest (>=3.10.6) and this script becomes a no-op.%s\n' "$C_DIM" "$C_R"
+
+QL="$(npm root -g)/ruflo/node_modules/@claude-flow/cli/dist/src/ruvector/q-learning-router.js"
+[ -f "$QL" ] || { fail "route Q-learner not found: $QL"; exit 2; }
+
+echo "router: ${QL#"$(npm root -g)"/}"
+
+if grep -qE "autoSaveInterval: 1," "$QL"; then
+	ok "route learner already persists every update (autoSaveInterval: 1) — legacy stopgap in place."
+	exit 0
+fi
+if ! grep -qE "autoSaveInterval: 100," "$QL"; then
+	warn "unexpected autoSaveInterval value in $QL — review manually (not the known F2 shape)."
+	exit 1
+fi
+if [ "$MODE" = "check" ]; then
+	warn "F2 present (autoSaveInterval: 100): CLI 'route feedback' will NOT persist. Re-run without --check to fix."
+	exit 1
+fi
+
+if node -e "const fs=require('fs');let s=fs.readFileSync('$QL','utf8');s=s.replace(/autoSaveInterval: 100,/,'autoSaveInterval: 1,');fs.writeFileSync('$QL',s);"; then
+	ok "patched autoSaveInterval → 1"
+else
+	fail "patch write failed"; exit 1
+fi
+
+# Verify: separate CLI processes must now accumulate into the persisted model.
+echo "verifying CLI feedback accumulation (3 separate processes)…"
+T=$(mktemp -d)
+(
+	cd "$T" || exit 0
+	export CLAUDE_FLOW_DB_PATH="$T/.swarm/memory.db"
+	ruflo init --minimal --force >/dev/null 2>&1
+	for i in 1 2 3; do ruflo route feedback -t "implement feature $i" -a coder -r 0.9 >/dev/null 2>&1; done
+)
+uc="$(cd "$T" && CLAUDE_FLOW_DB_PATH="$T/.swarm/memory.db" ruflo route stats 2>/dev/null \
+	| sed 's/\x1b\[[0-9;]*m//g' | grep -iE "Update Count" | grep -oE '[0-9]+' | head -1)"
+rm -rf "$T"
+
+if [ "${uc:-0}" -ge 1 ] 2>/dev/null; then
+	ok "verified: CLI route feedback now accumulates (Update Count=$uc across separate calls)."
+	printf '%s   Upgrade to ruflo >=3.10.6 to retire this stopgap entirely.%s\n' "$C_DIM" "$C_R"
+	exit 0
+else
+	fail "patched, but CLI feedback still not accumulating (Update Count=${uc:-0}). Investigate route.js."
+	exit 1
+fi
diff --git a/docs/superpowers/plans/2026-05-28-self-improvement-eval.md b/docs/superpowers/plans/2026-05-28-self-improvement-eval.md
new file mode 100644
index 00000000..6b3008bb
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-28-self-improvement-eval.md
@@ -0,0 +1,638 @@
+# Self-Improvement Eval + RL Status-Line Telemetry — Implementation Plan
+
+> ### 🕰️ HISTORICAL — superseded by upstream (updated 2026‑05‑29)
+> This plan is preserved as the record of *where we've been*. Since it was written, upstream
+> ruflo shipped 3.10.6→3.10.9, which **resolved the centerpiece of this plan**:
+> - **F2 (route feedback persistence)** → fixed upstream in **3.10.6 (#2222)** via `saveModel()`
+>   (@pacphi credited). Task 0 here (`ruflo-patch-route-learning`) is therefore **retired** — the
+>   script is now a version-gated no-op on ≥3.10.6 (legacy stopgap only on <3.10.6) and is no
+>   longer wired into `ruflo-resync`.
+> - A deeper follow-up (negative-reward inversion) was fixed in **3.10.7**; route-cache staleness
+>   + `--explore false` in **3.10.8**.
+> - **Carry-forward (still valid):** `ruflo-improvement-eval` (the proof harness) and the F3/F4
+>   findings, which remain unaddressed/deferred upstream.
+>
+> Current truth-of-record: [`docs/upstream/ruflo-self-improvement-findings.md`](../../upstream/ruflo-self-improvement-findings.md).
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+> **SCOPE REVISED after the Tier-2 spike (see spec "Revised scope"):** Tier-2 (LoRA
+> consumption) is infeasible as a patch → upstream issue only. This branch now ships
+> **(1) the F2 fix** (route Q-learner CLI persistence — validated), **(2) a minimal
+> in-process proof eval**, and **(3) docs + an upstream issue**. The `📈 RL` status-line
+> telemetry is **dropped** (Task 5 below is replaced; there is no statusline change).
+
+**Goal:** Fix F2 so ruflo's route Q-learner actually learns from real CLI feedback across invocations; prove the route Q-learner self-improves with a minimal in-process held-out/ablated experiment; and document the findings + file an upstream issue (F2 + the Tier-2 inference-seam gap).
+
+**Architecture:** `bin/ruflo-patch-route-learning` idempotently patches the global ruflo dist (`q-learning-router.js` `autoSaveInterval: 100 → 1`) so single-update CLI `route feedback` calls persist (validated: 6 calls → updateCount 6, ε decayed). `bin/ruflo-improvement-eval` drives ruflo's *real* `createQLearningRouter` in **one process** over a synthetic-reward environment (task → known-best agent), measures cold→trained held-out accuracy with a no-learning ablation and academic stats (permutation p, Cohen's d), and separately verifies CLI feedback accumulates post-patch. No status-line changes.
+
+**Tech Stack:** Node 20–26 (ESM), ruflo 3.10.5 (`@claude-flow/cli` → `dist/src/ruvector/index.js`), bash 3.2 (statusline patcher), `sqlite3` (existing footer reads). No new dependencies.
+
+**Reference spec:** `docs/superpowers/specs/2026-05-28-self-improvement-eval-design.md`
+
+**Conventions (match the kit):**
+- Color/`ok()/warn()/fail()` helpers with TTY guard; `--help` via the `sed -n` idiom; exit codes `0` ok / `1` not-proven / `2` env error.
+- **No `Co-Authored-By`** trailer (kit rule; `.claude/settings.json` has no `attribution.commit`).
+- Resolve the router from the **global** install via `createRequire(npm root -g/...)`.
+- Statusline edits go in the existing `ruflo-fix-statusline-version` heredoc (marker-guarded, upgrade-safe, shebang-safe insertion) — never rewrite ruflo's native lines.
+
+---
+
+## File Structure
+
+| File | Responsibility | Action |
+|---|---|---|
+| `bin/ruflo-patch-route-learning` | Idempotent global-dist patch for F2 (`autoSaveInterval → 1`); verify CLI feedback accumulates | Create |
+| `bin/ruflo-improvement-eval` | Node ESM harness: synthetic env + protocol + academic stats + writes `improvement.json`; `--cli-check` verifies F2 accumulation | Create |
+| `shell/ruflo-functions.sh` | Wire `ruflo-patch-route-learning` into `ruflo-resync` (no statusline change) | Modify (`ruflo-resync`) |
+| `install.sh` / `uninstall.sh` | Already derive bins from `bin/*` — **no change needed** (auto-picks up the new bins) | none |
+| `docs/upstream/ruflo-self-improvement-findings.md` | Findings writeup + ready-to-file upstream issue (F2 + Tier-2 inference-seam gap) | Create |
+| `claude/ruflo-reference.md` | Document `ruflo-improvement-eval` + `ruflo-patch-route-learning` + route-stats/F2 note | Modify |
+| `README.md` | Add commands + the plain-language "three learning systems" primer | Modify |
+| `docs/BACKGROUND.md` | Add the primer + finding F2 + the Tier-2 inference-seam finding | Modify |
+| `docs/TROUBLESHOOTING.md` | "route stats stuck at 0 → ruflo-patch-route-learning" entry | Modify |
+
+---
+
+## Task 0: F2 fix — `bin/ruflo-patch-route-learning` (do this first)
+
+**Files:** Create `bin/ruflo-patch-route-learning`
+
+- [ ] **Step 1: Write the patch bin** (idempotent; sets `autoSaveInterval: 1` in the global router dist so CLI `route feedback` persists; verifies accumulation):
+
+```bash
+#!/usr/bin/env bash
+# ruflo-patch-route-learning — make ruflo's route Q-learner persist CLI feedback.
+# BUG (F2): route.js feedbackCommand calls update() but never saveModel(), and
+# q-learning-router.js defaults autoSaveInterval:100 — so single-update CLI processes
+# exit without saving and `route stats` is permanently 0/ε1.0. Setting autoSaveInterval:1
+# makes every update persist (validated: 6 CLI feedback calls → updateCount 6, ε decayed).
+# Idempotent; RE-RUN AFTER EVERY `npm install -g ruflo` upgrade (the upgrade restores 100).
+#   ruflo-patch-route-learning [--check]
+# Exit: 0 patched/already / 1 verify failed / 2 env error
+set -u
+MODE="apply"; [ "${1:-}" = "--check" ] && MODE="check"
+[ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ] && { sed -n '2,12p' "$0" | sed 's|^# \{0,1\}||'; exit 0; }
+if [[ -t 1 ]]; then C_OK=$'\033[32m'; C_WARN=$'\033[33m'; C_FAIL=$'\033[31m'; C_R=$'\033[0m'; else C_OK=""; C_WARN=""; C_FAIL=""; C_R=""; fi
+ok(){ printf '%s✓%s %s\n' "$C_OK" "$C_R" "$*"; }; warn(){ printf '%s⚠%s  %s\n' "$C_WARN" "$C_R" "$*"; }; fail(){ printf '%s✗%s %s\n' "$C_FAIL" "$C_R" "$*"; }
+command -v npm >/dev/null 2>&1 && command -v node >/dev/null 2>&1 || { fail "npm/node not on PATH"; exit 2; }
+QL="$(npm root -g)/ruflo/node_modules/@claude-flow/cli/dist/src/ruvector/q-learning-router.js"
+[ -f "$QL" ] || { fail "router not found: $QL"; exit 2; }
+if grep -qE "autoSaveInterval: 1," "$QL"; then ok "route learner already persists every update (autoSaveInterval:1)"; exit 0; fi
+if ! grep -qE "autoSaveInterval: 100," "$QL"; then warn "unexpected autoSaveInterval in $QL — review manually"; exit 1; fi
+if [ "$MODE" = "check" ]; then warn "F2 present: autoSaveInterval:100 — CLI route feedback will not persist. Run without --check to fix."; exit 1; fi
+node -e "const fs=require('fs');let s=fs.readFileSync('$QL','utf8');s=s.replace(/autoSaveInterval: 100,/,'autoSaveInterval: 1,');fs.writeFileSync('$QL',s);" \
+  && ok "patched autoSaveInterval → 1 ($QL)" || { fail "patch failed"; exit 1; }
+# verify accumulation across separate CLI processes
+T=$(mktemp -d); ( cd "$T"; export CLAUDE_FLOW_DB_PATH="$T/.swarm/memory.db"; ruflo init --minimal --force >/dev/null 2>&1
+  for i in 1 2 3; do ruflo route feedback -t "implement feature $i" -a coder -r 0.9 >/dev/null 2>&1; done )
+uc=$( cd "$T"; CLAUDE_FLOW_DB_PATH="$T/.swarm/memory.db" ruflo route stats 2>/dev/null | sed 's/\x1b\[[0-9;]*m//g' | grep -iE "Update Count" | grep -oE '[0-9]+' | head -1 )
+rm -rf "$T"
+if [ "${uc:-0}" -ge 1 ] 2>/dev/null; then ok "verified: CLI route feedback now accumulates (Update Count=$uc). Re-run after every ruflo upgrade."; exit 0
+else fail "patch applied but CLI feedback still not accumulating (Update Count=${uc:-0})"; exit 1; fi
+```
+
+- [ ] **Step 2: Make executable, check, apply, confirm idempotent**
+
+```bash
+chmod +x bin/ruflo-patch-route-learning
+./bin/ruflo-patch-route-learning --check   # reports F2 (or already-fixed)
+./bin/ruflo-patch-route-learning           # patches + verifies accumulation
+./bin/ruflo-patch-route-learning           # second run: "already persists" (idempotent)
+```
+Expected: applies the patch, verifies Update Count ≥ 1 across CLI calls; second run is a no-op.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/ruflo-patch-route-learning
+git commit -m "feat: ruflo-patch-route-learning — fix F2 so route Q-learner persists CLI feedback (autoSaveInterval:1)"
+```
+
+---
+
+## Task 1: Harness skeleton — resolve ruflo's router, fail loudly if absent
+
+**Files:**
+- Create: `bin/ruflo-improvement-eval`
+
+- [ ] **Step 1: Write the skeleton with router resolution + `--help`**
+
+```javascript
+#!/usr/bin/env node
+//
+// ruflo-improvement-eval — prove (or refute) that ruflo's route Q-learner self-improves.
+//
+// Runs IN ONE PROCESS against ruflo's real createQLearningRouter. (The CLI `route feedback`
+// path cannot accumulate: autoSaveInterval=100 and feedback never calls saveModel — see
+// docs/BACKGROUND.md.) Synthetic-reward env: each task has a known-best agent; reward = match.
+// Measures cold-baseline vs trained held-out accuracy (greedy), with a no-update ablation and
+// N seeds + CI. Writes .claude-flow/improvement.json and prints an ASCII learning curve.
+//
+// Usage:
+//   ruflo-improvement-eval                 # default: 300 episodes, 5 seeds
+//   ruflo-improvement-eval --episodes 300 --seeds 5 --checkpoints 0,25,50,100,200,300
+//   ruflo-improvement-eval --smoke         # fast: 60 episodes, 3 seeds (mechanism check)
+//   ruflo-improvement-eval --json          # machine-readable result to stdout
+//   ruflo-improvement-eval --check         # print last cached improvement.json, no run
+//   ruflo-improvement-eval --help
+//
+// Exit: 0 self-improvement demonstrated / 1 not demonstrated / 2 environment error
+import { createRequire } from 'node:module';
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+const has = (f) => args.includes(f);
+const val = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i+1] ? args[i+1] : d; };
+
+if (has('-h') || has('--help')) {
+  const src = readFileSync(new URL(import.meta.url), 'utf8').split('\n');
+  console.log(src.slice(2, 20).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
+  process.exit(0);
+}
+
+const C = process.stdout.isTTY
+  ? { ok:'\x1b[32m', warn:'\x1b[33m', fail:'\x1b[31m', dim:'\x1b[2m', cyan:'\x1b[1;36m', r:'\x1b[0m' }
+  : { ok:'', warn:'', fail:'', dim:'', cyan:'', r:'' };
+const ok = (s) => console.log(`${C.ok}✓${C.r} ${s}`);
+const fail = (s) => console.log(`${C.fail}✗${C.r} ${s}`);
+
+function resolveRouterFactory() {
+  let groot;
+  try { groot = execSync('npm root -g', {stdio:['ignore','pipe','ignore']}).toString().trim(); }
+  catch { return null; }
+  const cliPkg = join(groot, 'ruflo', 'node_modules', '@claude-flow', 'cli', 'package.json');
+  if (!existsSync(cliPkg)) return null;
+  try {
+    const req = createRequire(cliPkg);
+    return req.resolve('./dist/src/ruvector/index.js');
+  } catch { return null; }
+}
+
+const routerIdx = resolveRouterFactory();
+if (!routerIdx) {
+  fail('Could not resolve ruflo\'s Q-learning router (@claude-flow/cli/dist/src/ruvector/index.js).');
+  console.log('  Ensure ruflo is installed globally (npm i -g ruflo) and run from any directory.');
+  process.exit(2);
+}
+
+const { createQLearningRouter } = await import(routerIdx);
+ok(`router module resolved: ${routerIdx.replace(/.*node_modules\//, 'node_modules/')}`);
+// (env + protocol added in later tasks)
+```
+
+- [ ] **Step 2: Make executable and verify resolution + failure path**
+
+```bash
+chmod +x bin/ruflo-improvement-eval
+./bin/ruflo-improvement-eval --help          # prints usage block, exit 0
+./bin/ruflo-improvement-eval                 # should print "router module resolved: ..."; exit 0 for now
+echo "exit=$?"
+```
+Expected: `--help` shows usage; bare run prints the resolved module path. (If ruflo absent, exit 2 with guidance.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/ruflo-improvement-eval
+git commit -m "feat(eval): harness skeleton — resolve ruflo's Q-learning router in-process"
+```
+
+---
+
+## Task 2: Synthetic environment + verify distinct states
+
+**Files:**
+- Modify: `bin/ruflo-improvement-eval` (append the environment + a state-distinctness check)
+
+- [ ] **Step 1: Add the env and a `--probe-states` mode**
+
+Append before the `// (env + protocol ...)` comment:
+
+```javascript
+// ── Synthetic-reward environment ───────────────────────────────────────────
+// Each entry: a task phrasing + its known-best agent (must be one of ruflo's ROUTE_NAMES:
+// coder, tester, reviewer, architect, researcher, optimizer, debugger, documenter).
+// TRAIN and EVAL phrasings are DISJOINT strings that map to the SAME keyword-states, so a
+// pass proves the router learned the state→agent mapping, not memorized exact strings.
+const ENV = [
+  { agent: 'tester',     train: 'write unit tests for the payment module',     evalq: 'create integration test coverage for billing' },
+  { agent: 'coder',      train: 'implement the user authentication feature',   evalq: 'build the login signup code path' },
+  { agent: 'reviewer',   train: 'review this pull request for issues',         evalq: 'audit and inspect the merge request' },
+  { agent: 'architect',  train: 'design the system architecture and structure',evalq: 'plan the service design patterns' },
+  { agent: 'debugger',   train: 'debug the failing error in checkout',         evalq: 'fix the bug causing the crash' },
+  { agent: 'optimizer',  train: 'optimize the slow query performance',         evalq: 'improve memory and speed bottlenecks' },
+  { agent: 'documenter', train: 'document the public API in the readme',       evalq: 'write docs and comments explaining usage' },
+  { agent: 'researcher', train: 'research and investigate the best approach',  evalq: 'explore and find prior patterns' },
+];
+const REWARD_HIT = 1, REWARD_MISS = -1;
+
+function probeStates() {
+  const router = createQLearningRouter({ modelPath: '/tmp/.ruflo-eval-probe.json', autoSaveInterval: 1e9 });
+  return router.initialize().then(() => {
+    const states = new Set();
+    for (const e of ENV) {
+      // route returns the decision; we only need that distinct tasks → distinct internal states.
+      // Train each once so a Q-entry is created, then read qTableSize growth per insert.
+      const before = router.getStats().qTableSize;
+      router.update(e.train, e.agent, REWARD_HIT);
+      states.add(router.getStats().qTableSize);
+    }
+    return router.getStats().qTableSize;
+  });
+}
+
+if (has('--probe-states')) {
+  const n = await probeStates();
+  console.log(`distinct Q-states for ${ENV.length} train tasks: ${n}`);
+  process.exit(n >= ENV.length ? 0 : 1);
+}
+```
+
+- [ ] **Step 2: Run the state probe — confirm each task is a distinct state (Q1 risk)**
+
+```bash
+./bin/ruflo-improvement-eval --probe-states
+echo "exit=$?"
+```
+Expected: `distinct Q-states for 8 train tasks: 8` (exit 0). **If fewer than 8** (keyword collisions, spec Q1), edit the `train`/`evalq` phrasings to use more distinct `FEATURE_KEYWORDS` (see spec F3 list: implement/test/review/design/research/optimize/debug/document) until each task occupies its own state, then re-run. Do not proceed until this passes.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/ruflo-improvement-eval
+git commit -m "feat(eval): synthetic-reward environment (task→known-best agent) + state-distinctness probe"
+```
+
+---
+
+## Task 3: Core protocol — cold baseline, train, greedy held-out eval, ablation
+
+**Files:**
+- Modify: `bin/ruflo-improvement-eval`
+
+- [ ] **Step 1: Add the experiment functions**
+
+Append:
+
+```javascript
+// ── Decision helper: pick the router's greedy action for a task ─────────────
+// route() returns a decision object; we extract the chosen agent id robustly across shapes.
+function decide(router, task, explore) {
+  const d = router.route ? router.route(task, explore) : router.selectAction(task, explore);
+  return (d && (d.agent || d.action || d.route || d.selectedAgent)) || (typeof d === 'string' ? d : null);
+}
+
+// Greedy held-out accuracy: exploration OFF, NO updates. Returns fraction matching known-best.
+function evalAccuracy(router) {
+  let hit = 0;
+  for (const e of ENV) if (decide(router, e.evalq, false) === e.agent) hit++;
+  return hit / ENV.length;
+}
+
+// One training+measurement run for a given mode. Returns { curve:[{k,acc}], stats }.
+async function runOnce({ episodes, checkpoints, ablation }) {
+  const router = createQLearningRouter({ modelPath: '/tmp/.ruflo-eval-run.json', autoSaveInterval: 1e9 });
+  await router.initialize();
+  if (router.reset) router.reset();             // ensure cold start (ε=1, |Q|=0)
+  const curve = [{ k: 0, acc: evalAccuracy(router) }];
+  const cps = new Set(checkpoints);
+  for (let k = 1; k <= episodes; k++) {
+    const e = ENV[(k - 1) % ENV.length];
+    const chosen = decide(router, e.train, true);          // explore during training
+    if (!ablation) {                                       // ablation = decisions but NO learning
+      const reward = chosen === e.agent ? REWARD_HIT : REWARD_MISS;
+      router.update(e.train, chosen, reward);
+    }
+    if (cps.has(k)) curve.push({ k, acc: evalAccuracy(router) });
+  }
+  if (!cps.has(episodes)) curve.push({ k: episodes, acc: evalAccuracy(router) });
+  const s = router.getStats();
+  return { curve, stats: { epsilon: s.epsilon, tdError: s.avgTDError, qSize: s.qTableSize, updates: s.updateCount } };
+}
+```
+
+> Note on `decide()`: the exact return shape of `router.route()` is confirmed during implementation — Step 2 prints one decision so you can adjust the property extraction if needed (the spec only guarantees a chosen agent is returned).
+
+- [ ] **Step 2: Add a `--smoke` single-seed run and inspect a decision shape**
+
+Append:
+
+```javascript
+const EPISODES = has('--smoke') ? 60 : parseInt(val('--episodes', '300'), 10);
+const SEEDS = has('--smoke') ? 3 : parseInt(val('--seeds', '5'), 10);
+const CHECKPOINTS = (val('--checkpoints', has('--smoke') ? '0,20,40,60' : '0,25,50,100,200,300'))
+  .split(',').map(n => parseInt(n, 10)).filter(n => n <= EPISODES);
+
+if (has('--inspect-decision')) {
+  const r = createQLearningRouter({ modelPath: '/tmp/.ruflo-eval-x.json', autoSaveInterval: 1e9 });
+  await r.initialize();
+  console.log('raw decision:', JSON.stringify(r.route ? r.route(ENV[0].train, false) : r.selectAction(ENV[0].train, false)));
+  process.exit(0);
+}
+```
+
+```bash
+./bin/ruflo-improvement-eval --inspect-decision
+```
+Expected: prints the router's raw decision object. **Confirm `decide()` extracts the agent id from this shape**; if the agent is under a different key, fix `decide()` accordingly, then continue.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/ruflo-improvement-eval
+git commit -m "feat(eval): protocol — cold baseline, exploratory training, greedy held-out eval, ablation"
+```
+
+---
+
+## Task 4: Multi-seed aggregation, CI, verdict, ASCII curve, result file
+
+**Files:**
+- Modify: `bin/ruflo-improvement-eval`
+
+- [ ] **Step 1: Add aggregation + report + `improvement.json` writer**
+
+Append:
+
+```javascript
+// ── Aggregate N seeds (router uses unseedable Math.random → average + 95% CI) ─
+function mean(a) { return a.reduce((x, y) => x + y, 0) / a.length; }
+function ci95(a) {                                  // half-width of 95% CI of the mean
+  if (a.length < 2) return 0;
+  const m = mean(a), v = mean(a.map(x => (x - m) ** 2)) * a.length / (a.length - 1);
+  return 1.96 * Math.sqrt(v / a.length);
+}
+const spark = (xs) => { const b='▁▂▃▄▅▆▇█'; return xs.map(x => b[Math.min(7, Math.max(0, Math.round(x*7)))]).join(''); };
+
+// ── Academically-grounded statistics (no external deps) ─────────────────────
+function sampVar(a){ if(a.length<2) return 0; const m=mean(a); return a.reduce((s,x)=>s+(x-m)**2,0)/(a.length-1); }
+function cohensD(a, b){                                  // standardized mean difference (pooled SD), Cohen 1988
+  const sp = Math.sqrt(((a.length-1)*sampVar(a) + (b.length-1)*sampVar(b)) / Math.max(1, a.length+b.length-2));
+  return sp === 0 ? (mean(a) > mean(b) ? Infinity : 0) : (mean(a) - mean(b)) / sp;
+}
+function* combos(arr, k, start=0, acc=[]){ if(acc.length===k){ yield acc; return; } for(let i=start;i<arr.length;i++) yield* combos(arr,k,i+1,acc.concat(arr[i])); }
+function permP(learn, abl){                              // one-sided permutation test: H0 = learning ≤ ablation
+  const obs = mean(learn) - mean(abl), pool = learn.concat(abl), n = learn.length, idx=[...pool.keys()];
+  let ge = 0, total = 0;
+  if (pool.length <= 14) {                              // exact enumeration (≤3432 splits)
+    for (const c of combos(idx, n)) { const set=new Set(c);
+      const A=pool.filter((_,i)=>set.has(i)), B=pool.filter((_,i)=>!set.has(i));
+      if (mean(A)-mean(B) >= obs - 1e-12) ge++; total++; }
+  } else {                                              // Monte-Carlo (10k shuffles)
+    total = 10000;
+    for (let s=0;s<total;s++){ const sh=[...pool]; for(let i=sh.length-1;i>0;i--){const j=Math.floor(Math.random()*(i+1));[sh[i],sh[j]]=[sh[j],sh[i]];}
+      if (mean(sh.slice(0,n))-mean(sh.slice(n)) >= obs - 1e-12) ge++; }
+  }
+  return ge/total;
+}
+function spearman(curve){                               // monotone-trend corroboration ρ(K, acc)
+  const n=curve.length; if(n<3) return 0;
+  const rank=(xs)=>{const s=xs.map((v,i)=>[v,i]).sort((a,b)=>a[0]-b[0]); const r=Array(xs.length); s.forEach(([,i],j)=>r[i]=j+1); return r;};
+  const rk=rank(curve.map(c=>c.k)), ra=rank(curve.map(c=>c.acc)), mr=(n+1)/2;
+  let num=0,dk=0,da=0; for(let i=0;i<n;i++){num+=(rk[i]-mr)*(ra[i]-mr); dk+=(rk[i]-mr)**2; da+=(ra[i]-mr)**2;}
+  return (dk&&da) ? num/Math.sqrt(dk*da) : 0;
+}
+
+if (!has('--check')) {
+  const learnRuns = [], ablRuns = [];
+  for (let s = 0; s < SEEDS; s++) learnRuns.push(await runOnce({ episodes: EPISODES, checkpoints: CHECKPOINTS, ablation: false }));
+  for (let s = 0; s < SEEDS; s++) ablRuns.push(await runOnce({ episodes: EPISODES, checkpoints: CHECKPOINTS, ablation: true }));
+
+  const ks = learnRuns[0].curve.map(p => p.k);
+  const curveMean = ks.map((k, i) => ({ k, acc: mean(learnRuns.map(r => r.curve[i].acc)) }));
+  const warmSeeds = learnRuns.map(r => r.curve[r.curve.length - 1].acc);
+  const ablSeeds  = ablRuns.map(r => r.curve[r.curve.length - 1].acc);
+  const coldAcc = curveMean[0].acc;
+  const warmAcc = mean(warmSeeds);
+  const warmCI  = ci95(warmSeeds);
+  const ablAcc  = mean(ablSeeds);
+  const chance  = 1 / ENV.length;
+  const st = learnRuns[learnRuns.length - 1].stats;
+  const deltaPP = Math.round((warmAcc - coldAcc) * 100);
+
+  // ── Pre-registered, academically-grounded PASS criteria (this is an A/B experiment) ──
+  //   1. Causal significance:  one-sided permutation test, learning vs no-learning ablation, p < 0.05
+  //   2. Effect size:          Cohen's d ≥ 0.8 ("large", Cohen 1988)
+  //   3. Above chance:         warm 95%-CI lower bound > 1/numActions
+  //   Corroboration (reported, NOT gating): ε↓, δ̄↓, Spearman ρ(K,acc) > 0.
+  const pValue = permP(warmSeeds, ablSeeds);
+  const d = cohensD(warmSeeds, ablSeeds);
+  const rho = spearman(curveMean);
+  const aboveChance = (warmAcc - warmCI) > chance;
+  const ALPHA = 0.05, D_MIN = 0.8;
+  const verdict = (pValue < ALPHA && d >= D_MIN && aboveChance) ? 'PASS' : 'FAIL';
+
+  const result = {
+    curve: curveMean, coldAcc, warmAcc, deltaPP, ci95: Math.round(warmCI * 100),
+    ablationAcc: ablAcc, chance, pValue: +pValue.toFixed(4), cohensD: (d===Infinity?999:+d.toFixed(2)),
+    spearman: +rho.toFixed(2), aboveChance, alpha: ALPHA, dMin: D_MIN,
+    epsilon0: 1.0, epsilonF: st.epsilon, tdError: st.tdError, qSize: st.qSize,
+    episodes: EPISODES, seeds: SEEDS, verdict, ts: Math.floor(Date.now() / 1000),
+  };
+
+  mkdirSync('.claude-flow', { recursive: true });
+  writeFileSync(join('.claude-flow', 'improvement.json'), JSON.stringify(result, null, 2));
+
+  if (has('--json')) { console.log(JSON.stringify(result)); process.exit(verdict === 'PASS' ? 0 : 1); }
+
+  console.log('');
+  console.log(`${C.cyan}Self-improvement eval${C.r}  (route Q-learner · ${SEEDS} seeds × ${EPISODES} episodes · learning vs no-learning ablation)`);
+  console.log(`  learning curve  ${spark(curveMean.map(p => p.acc))}  ${curveMean.map(p => `${p.k}:${Math.round(p.acc*100)}%`).join('  ')}`);
+  console.log(`  held-out acc    cold ${Math.round(coldAcc*100)}% → warm ${Math.round(warmAcc*100)}%   Δ${deltaPP>=0?'+':''}${deltaPP}pp (95% CI ±${Math.round(warmCI*100)})`);
+  console.log(`  ablation        ${Math.round(ablAcc*100)}%   ·   chance ${Math.round(chance*100)}%   ·   above-chance: ${aboveChance ? 'yes' : 'no'}`);
+  console.log(`  significance    permutation p ${pValue < 0.001 ? '<0.001' : '='+pValue.toFixed(3)}   ·   Cohen's d ${d===Infinity?'∞':d.toFixed(2)}   ·   Spearman ρ(K,acc) ${rho.toFixed(2)}`);
+  console.log(`  convergence     ε ${result.epsilon0}→${st.epsilon.toFixed(2)}   δ̄ ${st.tdError.toFixed(3)}   |Q| ${st.qSize}`);
+  console.log('');
+  verdict === 'PASS'
+    ? ok(`SELF-IMPROVEMENT DEMONSTRATED — learning beat the no-learning ablation (p<${ALPHA}, d=${d===Infinity?'∞':d.toFixed(2)}), held-out +${deltaPP}pp, above chance. → .claude-flow/improvement.json`)
+    : fail(`NOT demonstrated — fails the pre-registered test (p=${pValue.toFixed(3)}, d=${d===Infinity?'∞':d.toFixed(2)}, above-chance=${aboveChance}). Honest negative result → .claude-flow/improvement.json`);
+  process.exit(verdict === 'PASS' ? 0 : 1);
+}
+
+// --check: print the last cached result
+const p = join('.claude-flow', 'improvement.json');
+if (!existsSync(p)) { console.log('No .claude-flow/improvement.json — run ruflo-improvement-eval first.'); process.exit(2); }
+const r = JSON.parse(readFileSync(p, 'utf8'));
+console.log(`${r.verdict}  ${spark(r.curve.map(c => c.acc))}  cold ${Math.round(r.coldAcc*100)}%→warm ${Math.round(r.warmAcc*100)}%  Δ${r.deltaPP}pp  p${r.pValue<0.001?'<.001':'='+r.pValue}  d=${r.cohensD}  ε→${r.epsilonF.toFixed(2)}  δ̄${r.tdError.toFixed(3)}  |Q|${r.qSize}`);
+process.exit(r.verdict === 'PASS' ? 0 : 1);
+```
+
+- [ ] **Step 2: Run the smoke experiment end-to-end**
+
+```bash
+cd /tmp && rm -rf si-eval && mkdir si-eval && cd si-eval
+"$OLDPWD/bin/ruflo-improvement-eval" --smoke ; echo "exit=$?"
+cat .claude-flow/improvement.json | head -40
+cd "$OLDPWD"
+```
+Expected: a printed learning curve, cold→warm accuracy, ablation %, convergence stats, a PASS/FAIL verdict, and a written `improvement.json`. If the curve does not rise (e.g., ε decays too slowly at K=60), bump `--episodes` and re-run; record the working smoke parameters. A FAIL with an honest negative result is an acceptable Step outcome — the mechanism (curve + ablation + file) must work, even if 60-episode smoke doesn't clear the PASS bar.
+
+- [ ] **Step 3: Run the fuller experiment to get a real PASS (if smoke was short)**
+
+```bash
+cd /tmp/si-eval && "$OLDPWD/bin/ruflo-improvement-eval" --episodes 600 --seeds 5 ; echo "exit=$?" ; cd "$OLDPWD"
+```
+Expected: with enough episodes the warm held-out accuracy clears the PASS bar and beats the ablation. Capture the numbers for the docs. (If even 600 episodes can't clear +20pp/0.60, lower nothing silently — instead record the achieved delta honestly and note it in the docs; the proof is the *gap vs ablation*, not a fixed threshold.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add bin/ruflo-improvement-eval
+git commit -m "feat(eval): multi-seed aggregation + CI + verdict + ASCII learning curve + improvement.json"
+```
+
+---
+
+## Task 5: Status-line `📈 RL` telemetry segment
+
+**Files:**
+- Modify: `shell/ruflo-functions.sh` (the `rufloActivationSegments` helper inside the `ruflo-fix-statusline-version` heredoc)
+
+- [ ] **Step 1: Add the RL line to the footer helper**
+
+In `shell/ruflo-functions.sh`, inside the heredoc helper (after the agentic-qe `qe` block, before the `// ── assemble` block), insert a new segment that reads `improvement.json`:
+
+```javascript
+    // ── self-improvement (📈 RL): rendered from .claude-flow/improvement.json (written by
+    // ruflo-improvement-eval). NEVER sourced from `route stats` (CLI persistence is broken).
+    var rl = "";
+    try {
+      var ip = path.join(cwd, ".claude-flow", "improvement.json");
+      if (fs.existsSync(ip)) {
+        var m = JSON.parse(fs.readFileSync(ip, "utf8"));
+        var spk = (m.curve || []).map(function(c){ var b="▁▂▃▄▅▆▇█"; return b[Math.min(7, Math.max(0, Math.round((c.acc||0)*7)))]; }).join("");
+        var tag = m.verdict === "PASS" ? (G + "📈 RL" + R) : (DIM + "◷ RL" + R);
+        var parts = [];
+        if (spk) parts.push(spk);
+        if (typeof m.coldAcc === "number") parts.push("acc " + Math.round(m.coldAcc*100) + "%→" + Math.round(m.warmAcc*100) + "%");
+        if (typeof m.deltaPP === "number") parts.push("Δ" + (m.deltaPP>=0?"+":"") + m.deltaPP + "pp" + (typeof m.ci95==="number" ? " (CI±" + m.ci95 + ")" : ""));
+        if (typeof m.pValue === "number") parts.push("p" + (m.pValue<0.001 ? "<.001" : "=" + m.pValue));
+        if (typeof m.cohensD === "number") parts.push("d=" + (m.cohensD>=999?"∞":m.cohensD));
+        if (typeof m.epsilonF === "number") parts.push("ε" + m.epsilonF.toFixed(2) + "↓");
+        if (typeof m.tdError === "number") parts.push("δ̄" + m.tdError.toFixed(2) + "↓");
+        if (typeof m.qSize === "number") parts.push("|Q|" + m.qSize);
+        rl = tag + "  " + parts.join(DIM + " · " + R);
+      }
+    } catch(e){}
+```
+
+Then in the `// ── assemble` block, add `rl` as its own line. Change the assembly to:
+
+```javascript
+    var l1 = []; if (learn) l1.push(learn); if (sec) l1.push(sec);
+    var out = [];
+    if (l1.length) out.push(l1.join("      "));
+    if (qe) out.push(qe);
+    if (rl) out.push(rl);
+    if (!out.length) return "";
+    return "\n" + DIM + "─".repeat(44) + R + "\n" + out.join("\n");
+```
+
+- [ ] **Step 2: Verify the RL line renders from a synthetic result file**
+
+```bash
+cd /tmp && rm -rf rl-sl && mkdir -p rl-sl/.claude-flow rl-sl/.claude/helpers && cd rl-sl
+cat > .claude-flow/improvement.json <<'JSON'
+{"curve":[{"k":0,"acc":0.12},{"k":50,"acc":0.4},{"k":100,"acc":0.62},{"k":300,"acc":0.78}],
+ "coldAcc":0.12,"warmAcc":0.78,"deltaPP":66,"ci95":7,"pValue":0.0009,"cohensD":2.1,
+ "epsilonF":0.12,"tdError":0.01,"qSize":8,"verdict":"PASS"}
+JSON
+cp "$OLDPWD/.claude/helpers/statusline.cjs" .claude/helpers/ 2>/dev/null || ruflo init --minimal --force >/dev/null 2>&1
+source "$OLDPWD/shell/ruflo-functions.sh"
+ruflo-fix-statusline-version .claude/helpers/statusline.cjs >/dev/null 2>&1
+node .claude/helpers/statusline.cjs <<<'{}' 2>/dev/null | sed -E 's/\x1b\[[0-9;]*m//g' | tail -3
+cd "$OLDPWD" && rm -rf /tmp/rl-sl
+```
+Expected last line resembles: `📈 RL  ▁▃▅▇  acc 12%→78%  Δ+66pp (CI±7) · p<.001 · d=2.1 · ε0.12↓ · δ̄0.01↓ · |Q|8` (add `"pValue":0.0009,"cohensD":2.1` to the synthetic JSON to see `p`/`d`). With no `improvement.json`, the line must be absent (verify by removing the file and re-rendering).
+
+- [ ] **Step 3: Verify idempotency (re-apply twice, one block)**
+
+```bash
+cd /tmp && rm -rf rl-idem && mkdir -p rl-idem/.claude/helpers && cd rl-idem
+ruflo init --minimal --force >/dev/null 2>&1
+source "$OLDPWD/shell/ruflo-functions.sh"
+ruflo-fix-statusline-version .claude/helpers/statusline.cjs >/dev/null 2>&1
+ruflo-fix-statusline-version .claude/helpers/statusline.cjs >/dev/null 2>&1
+echo "seg blocks: $(grep -c 'ruflo-seg:BEGIN' .claude/helpers/statusline.cjs)  wraps: $(grep -c 'rufloActivationSegments(process.cwd())' .claude/helpers/statusline.cjs)"
+cd "$OLDPWD" && rm -rf /tmp/rl-idem
+```
+Expected: `seg blocks: 1  wraps: 1`.
+
+- [ ] **Step 4: Apply to this session's live statusline + run the real eval here**
+
+```bash
+cd /Users/cphillipson/Development/active/ai/ruflo-machine-ref
+source shell/ruflo-functions.sh
+./bin/ruflo-improvement-eval --smoke         # writes ./.claude-flow/improvement.json for THIS repo
+ruflo-fix-statusline-version .claude/helpers/statusline.cjs >/dev/null 2>&1
+node .claude/helpers/statusline.cjs <<<'{}' 2>/dev/null | sed -E 's/\x1b\[[0-9;]*m//g' | tail -4
+```
+Expected: the live footer now includes the `📈 RL` (or `◷ RL` if smoke didn't clear the bar) line.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add shell/ruflo-functions.sh
+git commit -m "feat(statusline): 📈 RL telemetry line — learning-curve sparkline + held-out acc + Δpp/CI + ε/δ̄/|Q| from improvement.json"
+```
+
+---
+
+## Task 6: Documentation — primer, command, finding F2, Tier-2, troubleshooting
+
+**Files:**
+- Modify: `README.md`, `claude/ruflo-reference.md`, `docs/BACKGROUND.md`, `docs/TROUBLESHOOTING.md`
+
+- [ ] **Step 1: README — add the command, the `📈 RL` mockup, and the plain-language primer**
+
+In the commands table add:
+```
+| 📈 `ruflo-improvement-eval [--smoke\|--json\|--check]` | In-process held-out/ablated/multi-seed proof that the route Q-learner self-improves; writes `.claude-flow/improvement.json` and drives the status line's `📈 RL` line. |
+```
+Add a new section `## 🧠 Is it actually learning *and* improving?` containing the plain-language primer copied from the spec's §0 (the delivery-company analogy, the three systems with ε/TD/|Q|/Δ-LoRA, the two-loops table, and the "why it's worth it without Tier-2" paragraph). Add the `📈 RL` line to the status-line mockup.
+
+- [ ] **Step 2: BACKGROUND.md — add the primer + finding F2 + Tier-2**
+
+Append a section `## Proving self-improvement (and what it doesn't cover)` that: (a) includes the §0 primer; (b) documents **F2** — the CLI `route feedback` non-persistence bug (`q-learning-router.js` `autoSaveInterval:100`; `route.js` `feedbackCommand` never calls `saveModel()`), with the one-line fix (call `saveModel()` after `update()` or set `autoSaveInterval:1`), and that this is why `route stats` reads `0/ε1.0` and why the eval runs in-process; (c) states Tier-2 (consume the LoRA `B` at inference) is required to prove the SONA/LoRA path and is an upstream change.
+
+- [ ] **Step 3: ruflo-reference.md — command + route-stats correction**
+
+In the self-learning section, add `ruflo-improvement-eval` to the workflow and the decision tree (`Prove self-improvement → ruflo-improvement-eval`). Add one line: "The status line's `📈 RL` data comes from the in-process eval, **not** `route stats` (its CLI path can't persist — always shows `0/ε1.0`)."
+
+- [ ] **Step 4: TROUBLESHOOTING.md — two entries**
+
+Add:
+```
+### `📈 RL` line missing or shows `◷ RL unproven`
+The eval hasn't run, or didn't clear the PASS bar. Run `ruflo-improvement-eval` (or
+`--smoke`); it writes `.claude-flow/improvement.json` which the footer renders. A `◷`
+verdict is an honest negative result, not a bug.
+
+### `ruflo route stats` is stuck at `Update Count 0 / Epsilon 1.0`
+Known ruflo bug: `route feedback` applies one update per process but never persists it
+(`autoSaveInterval:100`, no `saveModel()`), so CLI-driven route learning can't accumulate.
+This is why the kit measures self-improvement in-process (`ruflo-improvement-eval`) and
+never sources status-line signals from `route stats`.
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md claude/ruflo-reference.md docs/BACKGROUND.md docs/TROUBLESHOOTING.md
+git commit -m "docs: self-improvement primer, ruflo-improvement-eval, finding F2 (route feedback bug), Tier-2 + 📈 RL"
+```
+
+---
+
+## Self-Review (completed during planning)
+
+**Spec coverage:** R1–R8 (harness) → Tasks 1–4; R9–R10 (📈 RL line) → Task 5; R11 (no route-stats source) → Task 5 Step 1 comment + Task 6 Steps 3–4; R12 (scope honesty) → Task 6 primer/Tier-2; R13 (F2 bug) → Task 6 Step 2 + TROUBLESHOOTING; R14 (bash 3.2 / graceful Node failure) → Task 1 exit-2 path + Task 5 fs-only segment; G4 (academic telemetry) → Task 4 report + Task 5 line. §0 primer → Task 6. No uncovered requirement.
+
+**Placeholder scan:** No "TBD"/"handle edge cases". The two `--inspect-decision`/`--probe-states` steps are concrete de-risking probes with explicit pass conditions and fix instructions, not deferrals. The one genuine runtime unknown — `router.route()`'s exact return shape — is handled by a defensive `decide()` extractor plus an inspection step that prints the real shape before relying on it.
+
+**Type/name consistency:** `createQLearningRouter`, `router.initialize()/route()/update()/getStats()/reset()`, stat fields (`epsilon`, `avgTDError`, `qTableSize`, `updateCount`), and `improvement.json` keys (`curve`, `coldAcc`, `warmAcc`, `deltaPP`, `ci95`, `epsilonF`, `tdError`, `qSize`, `verdict`) are used identically across the harness (Tasks 1–4) and the statusline renderer (Task 5). `--smoke/--episodes/--seeds/--checkpoints/--json/--check` flags consistent.
+
+**Known runtime risks (flagged in-task, not placeholders):** (Q1) state collisions → Task 2 Step 2 gate; (Q2) slow ε decay needing more episodes → Task 4 Steps 2–3; decision-shape → Task 3 Step 2 inspection.
diff --git a/docs/superpowers/specs/2026-05-28-self-improvement-eval-design.md b/docs/superpowers/specs/2026-05-28-self-improvement-eval-design.md
new file mode 100644
index 00000000..6f46dd43
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-28-self-improvement-eval-design.md
@@ -0,0 +1,283 @@
+# Design: Proving (and surfacing) self-improvement — `ruflo-improvement-eval` + RL status-line telemetry
+
+- **Status:** 🕰️ HISTORICAL — partially superseded by upstream ruflo 3.10.6→3.10.9 (see banner below)
+- **Branch:** `feat/self-improvement-eval`
+- **Date:** 2026-05-28 (design); 2026-05-29 (upstream reconciliation)
+- **Author:** Chris Phillipson (with Claude)
+- **Builds on:** the merged self-learning/agentic-qe/security work (PR #1)
+
+> ### Upstream reconciliation (added 2026‑05‑29)
+> Preserved as the record of where we've been. The F2 fix this design relies on **landed
+> upstream** in ruflo **3.10.6 (#2222)** (`saveModel()` after feedback; @pacphi credited), so the
+> `ruflo-patch-route-learning` patch is **retired** (version-gated no-op on ≥3.10.6). The Tier-2
+> / F4 verdict below was **independently confirmed upstream in 3.10.9** (`apply()` empirically
+> inert; upstream deliberately won't fake a gradient). **F3** (state-encoder collapse) remains
+> open and is the primary carry-forward item. Current truth-of-record:
+> [`docs/upstream/ruflo-self-improvement-findings.md`](../../upstream/ruflo-self-improvement-findings.md).
+
+## ⚠️ Revised scope (after the Tier-2 feasibility spike — supersedes §2–§4 framing)
+
+A time-boxed spike into ruflo source produced a decisive verdict that **changed this
+work's scope**:
+
+- **Tier-2 (make a decision consume the trained LoRA) is NOT feasible as a patch.** Every
+  `SonaCoordinator` call in ruflo is training/recording (`recordSignal`,
+  `recordTrajectory`, `addTrajectoryStep`, `endTrajectory`, `distillLearning`); the
+  coordinator exposes **no inference method** (`predict`/`forward`/`infer`); and the
+  matrix-LoRA `forward_array` has **zero callers** outside its own training file. It's not
+  a disconnected wire — *there is no socket*. Consuming the LoRA would require adding an
+  inference path to a native/WASM package — upstream R&D, not a kit patch. → **filed as an
+  upstream issue, not built here.**
+- **F2 (route Q-learner CLI persistence) IS a feasible, real fix — validated.** `route.js`
+  `feedbackCommand` calls `update()` but never `saveModel()`, and
+  `q-learning-router.js` defaults `autoSaveInterval: 100`, so single-update CLI processes
+  never persist. Patching `autoSaveInterval → 1` made six separate CLI `route feedback`
+  calls accumulate (Update Count 0→6, ε 1.0→0.9973, model persisted). This makes ruflo's
+  route learner actually **learn from real CLI use across invocations**.
+
+**Revised deliverables (a mix of "fix it" + "document it"):**
+1. **`bin/ruflo-patch-route-learning`** — idempotent, re-appliable global-dist patch for F2
+   (sets `autoSaveInterval: 1`; verifies CLI feedback accumulates). Wired into
+   `ruflo-resync`. Re-run after each ruflo upgrade (like `ruflo-patch-native`).
+2. **`bin/ruflo-improvement-eval`** — **minimal** in-process proof that the route Q-learner
+   self-improves (cold→warm held-out accuracy, no-learning ablation, permutation p +
+   Cohen's d), **plus** a check that after the F2 patch CLI-driven feedback persists. Writes
+   `.claude-flow/improvement.json` and prints the result. **No status-line telemetry** (the
+   `📈 RL` line is dropped — it was thin without live value).
+3. **Docs + upstream issue** — a findings writeup (decision-path map, what's wired vs not,
+   the §0 primer) and a ready-to-file upstream issue covering F2 + the Tier-2 inference-seam
+   gap.
+
+The §2–§8 sections below describe the *original* (full Tier-1 + telemetry) design and are
+retained for context; where they conflict with this revised scope, **this section wins**
+(notably: no `📈 RL` status-line line; add the F2 patch + upstream issue).
+
+## 0. Plain-language primer (read this first — no ML background needed)
+
+Use a **delivery company** as the analogy. ruflo has *three different* learning systems
+that people often conflate:
+
+1. **The Q-learner = the dispatcher.** Its job: "which specialist should handle this
+   task?" (coder, tester, reviewer…). It keeps a scorecard of which agent tends to do
+   well on which kind of task and updates it from results. "Q-learning" is just the
+   textbook name for *try → see if it worked → nudge the preference*.
+   - **ε (epsilon)** — how often it gambles on a random pick vs. its current favorite.
+     Starts at **1.0 (100% random)**; should **shrink** as it learns to trust itself.
+     Stuck at 1.0 = "still guessing, hasn't committed to anything learned."
+   - **TD error (δ)** — "how surprised it was": the gap between expectation and outcome.
+     Shrinking toward 0 = its expectations now match reality (it has converged).
+   - **|Q| (Q-table size)** — how many distinct task-types it has opinions about.
+
+2. **SONA = a driver's real-time muscle memory.** A fast engine that nudges itself after
+   each action based on whether it went well. It banks **trajectories** (sequences of
+   what it did) and **patterns** (distilled "this worked" recipes) — the counts in the
+   status line.
+
+3. **LoRA = the *format* SONA stores its tweaks in.** "Low-Rank Adaptation" — instead of
+   rewriting the whole brain, it keeps a small **diff sheet of sticky-note corrections**
+   on a frozen base. **Δ LoRA** = "how big was the *last* tweak" (≈0 = barely adjusted).
+
+**The crux (the Tier-2 gap):** the LoRA sticky-notes *are being written* (they pile up),
+**but when ruflo decides which agent to use it never *reads* them** — it reads a simpler
+"confidence" number instead. So the notes accumulate yet change no decision. Wiring the
+decision to read them is a change *inside ruflo* (Tier 2), which we don't own.
+
+**Why this work is worth doing now, without the Tier-2 fix** — there are two learning
+loops, in very different shape:
+
+| Loop | Learns? | Does its learning change decisions today? |
+|---|---|---|
+| **Q-learner (dispatcher)** | Yes | **Yes — wired end-to-end** |
+| **SONA/LoRA (driver notes)** | Yes | **No — not consumed (Tier-2 gap)** |
+
+This work proves the **Q-learner loop** self-improves — a loop that genuinely drives
+behavior today. It (1) answers "is it self-improving?" with measured evidence instead of
+a hand-wave, (2) shows that proof on the status line in credible terms, (3) documents the
+two real bugs (CLI feedback never saves; LoRA never read), and (4) builds the exact
+measuring stick Tier-2 will need (re-run the same A/B once LoRA-consumption is fixed
+upstream). We prove what's true (the dispatcher improves) and clearly label what isn't yet
+(the driver-notes path). That honesty *is* the value.
+
+## 1. Problem
+
+The kit proved the system is **self-learning** (experience accumulates and persists). It
+did **not** prove **self-improving** — that accumulated experience measurably changes
+behavior for the better. A peer review (Ciprian Melian) reached the same verdict:
+*self-improving is not proven* — routing confidence is flat, the trained LoRA isn't
+consumed at inference, and there is no held-out/A-B instrument showing quality trending
+up. This work builds that instrument for the loop that *is* consumed, and surfaces the
+result on the status line in terms an AI/ML audience recognizes.
+
+### 1.1 Source-validated findings (ruflo 3.10.5)
+
+Verified by reading ruflo source and probing in isolation:
+
+| # | Finding | Evidence | Consequence for design |
+|---|---|---|---|
+| F1 | The route Q-learner genuinely learns **in-process** | 200 in-process `update()`s → `updateCount 200`, `qTableSize 4`, `epsilon 1.0→0.913`, `avgTDError 0.125` | Drive the eval **in one Node process** using ruflo's real `createQLearningRouter`. |
+| F2 | **CLI `route feedback` cannot accumulate** (a genuine bug) | `q-learning-router.js`: `autoSaveInterval: 100`; `route.js` `feedbackCommand` calls `update()` but never `saveModel()` → each one-update process exits without persisting → `route stats` permanently `updateCount 0 / ε 1.0` | Do **not** drive via repeated CLI calls; do **not** source any status-line signal from `route stats`. File/document upstream. |
+| F3 | The router is **tabular** Q-learning over discrete keyword-hash states (`FEATURE_KEYWORDS` → state; 8 `ROUTE_NAMES` actions) | `q-learning-router.js:42-72` | "Held-out" = held-out task *instances/phrasings from the same state distribution*, evaluated greedily — not novel unseen states. Frame the proof honestly. |
+| F4 | `routing_outcomes` records `quality_score`, `success`, `followed_recommendation` per decision | `.schema routing_outcomes` | Available as a secondary, ruflo-native metric (AQE path); the primary metric is in-process accuracy vs known-best. |
+| F5 | The trained LoRA `B` matrix is **not consumed at inference** for routing | `forward_array` (B path) only in `ruvector-training.js`; routing consumes pattern-confidence scalars (`intelligence.js:188`) | Proving the LoRA path self-improves is **out of scope (Tier 2)** — documented, not built. |
+
+## 2. Goals / Non-goals
+
+**Goals**
+- G1. Build `ruflo-improvement-eval`: an in-process, held-out, ablated experiment that
+  proves (or refutes) that ruflo's route Q-learner self-improves from experience.
+- G2. Use a falsifiable, pre-registered proof: held-out greedy accuracy rises with
+  training and ≫ cold baseline; a no-update ablation stays flat; corroborated by ε decay
+  and TD-error convergence; multi-seed to beat noise.
+- G3. Emit a machine-readable result (`.claude-flow/improvement.json`) and a human ASCII
+  learning curve + PASS/FAIL verdict.
+- G4. Add an academically-literate **`📈 RL` telemetry line** to the status-line footer
+  that renders the eval result (learning-curve sparkline, held-out accuracy, effect size
+  + CI, ε decay, mean TD error, |Q|).
+- G5. Document Tier 2 (proving the LoRA/SONA path) — what it requires and the expected
+  outcomes — and document finding F2 as an upstream bug.
+
+**Non-goals**
+- N1. Do **not** patch ruflo source to consume the LoRA `B` at inference (Tier 2).
+- N2. Do **not** run real LLM agents — the environment is synthetic-reward (deterministic,
+  free, reproducible-in-aggregate).
+- N3. Do **not** source any status-line signal from `route stats` (F2: broken).
+- N4. No claim of generalization to *unseen states* (F3: tabular).
+
+## 3. Architecture
+
+```
+ruflo-improvement-eval  (Node .mjs — in-process, per F1/F2)
+  ├─ Environment      fixed task suite; each task → known-best agent; reward = match
+  ├─ Protocol         cold baseline → train K → checkpoint eval (greedy) → ablation → N seeds
+  ├─ Metrics          held-out accuracy, mean reward, ε, avgTDError, |Q|; effect size + CI
+  ├─ Report           ASCII learning curve + PASS/FAIL to stdout
+  └─ Result file      .claude-flow/improvement.json {curve[], coldAcc, warmAcc, deltaPP, ci,
+                          epsilon0, epsilonF, tdError, qSize, seeds, verdict, ts}
+                                   │
+                                   ▼
+shell/ruflo-functions.sh  (statusline footer helper — append-only, fs-only)
+  └─ 📈 RL line: render improvement.json → sparkline · acc cold→warm · Δpp (CI) · ε↓ · δ̄↓ · |Q|
+```
+
+### 3.1 Component contracts
+
+**`bin/ruflo-improvement-eval`** (new; Node, `#!/usr/bin/env node`)
+- *Does:* runs the full experiment in one process against ruflo's real
+  `createQLearningRouter` (resolved from the global `@claude-flow/cli`); prints the curve
+  + verdict; writes `improvement.json` into `./.claude-flow/`.
+- *Input:* flags `--episodes K` (default 300), `--seeds N` (default 5), `--checkpoints`
+  (default `0,25,50,100,200,300`), `--json`, `--quiet`. `--check` to only print the last
+  cached result.
+- *Output:* exit 0 if self-improvement is demonstrated (PASS criteria in R4), 1 if not
+  (flat/ablation-indistinguishable), 2 on env error.
+- *Depends on:* global ruflo (`@claude-flow/cli` → `ruvector/index.js`), node.
+
+**Synthetic environment** (inline in the harness)
+- A fixed list of `{task, bestAgent}` where `bestAgent ∈ ROUTE_NAMES` and `task` contains
+  the `FEATURE_KEYWORDS` that map to a distinct state (e.g. "write unit tests for the
+  payment module" → tester). Split into TRAIN and EVAL instances (EVAL includes reworded
+  phrasings mapping to trained states, to show it learned the state→agent map, not strings).
+- Reward: `+1` if the router's chosen action == `bestAgent`, else `-1` (clamped to router's
+  [-1,1]).
+
+**Statusline `📈 RL` segment** (extends the existing footer helper in `ruflo-functions.sh`)
+- *Does:* if `.claude-flow/improvement.json` exists, append one line:
+  `📈 RL  <sparkline>  acc <cold%>→<warm%>  Δ<+pp> (95% CI ±<x>)  ·  ε <e0>→<ef>↓  ·  δ̄ <td>↓  ·  |Q| <n>`.
+  Renders nothing if the file is absent.
+- *Depends on:* `fs` only (cheap; no subprocess) — the heavy computation already happened
+  in the eval.
+- *Idempotent / upgrade-safe:* same marker-guarded injector as the existing footer.
+
+## 4. Requirements
+
+### Eval harness
+- **R1.** MUST run entirely in one Node process using ruflo's shipped
+  `createQLearningRouter` (not a reimplementation, not repeated CLI calls).
+- **R2.** MUST measure **cold baseline** (fresh router, exploration off, greedy) accuracy on
+  the EVAL split before any training.
+- **R3.** MUST train K episodes on the TRAIN split (decide-with-exploration → reward →
+  `update`), evaluating EVAL **greedily (exploration off, no updates)** at each checkpoint.
+- **R4.** PASS criteria MUST be pre-registered and **statistically grounded** (this is an
+  A/B experiment — learning arm vs no-learning ablation), NOT arbitrary thresholds. All
+  must hold: (a) **causal significance** — a one-sided **permutation test** of the learning
+  arm's held-out accuracy vs the ablation arm's (exact C(2N,N) enumeration for small N,
+  Monte-Carlo fallback) yields **p < 0.05**; (b) **effect size** — **Cohen's d ≥ 0.8**
+  ("large", Cohen 1988) on that difference; (c) **above chance** — warm accuracy's 95%-CI
+  lower bound > `1/numActions`. Corroborating signals MUST be reported but are NOT gating:
+  ε decreased, mean TD error decreased, and **Spearman ρ(K, accuracy) > 0** (monotone
+  learning curve). A permutation test (not a t-test) is used because N is small and
+  accuracies are bounded (no normality assumption).
+- **R5.** MUST run a **no-update ablation** (same decisions, rewards withheld / `update`
+  skipped) and assert it does **not** improve — proving gains are *caused* by learning.
+- **R6.** MUST aggregate over N seeds (router uses unseedable `Math.random`) and report
+  mean ± CI; MUST NOT claim improvement from a single run.
+- **R7.** MUST write `.claude-flow/improvement.json` with: the curve, cold/warm accuracy,
+  Δpp + 95% CI, ablation accuracy, **permutation p-value**, **Cohen's d**, **Spearman ρ**,
+  above-chance flag, ε (initial/final), avgTDError, |Q|, seed count, verdict, timestamp.
+- **R8.** MUST print an ASCII learning curve and a clear PASS/FAIL verdict; honor `--json`.
+
+### Status line
+- **R9.** The footer MUST gain a **full** `📈 RL` line rendered **only** when
+  `.claude-flow/improvement.json` exists, showing: learning-curve sparkline, held-out
+  accuracy cold→warm, effect size Δpp with CI, **permutation p**, **Cohen's d**, ε decay,
+  mean TD error, and |Q|. A FAIL verdict renders as `◷ RL` (same fields).
+- **R10.** The `📈 RL` line MUST be fs-only (no subprocess), marker-guarded, and injected by
+  the existing upgrade-safe statusline patcher (so `ruflo-resync` maintains it).
+- **R11.** The kit MUST NOT render any learning/improvement signal sourced from
+  `route stats` (F2: permanently `0 / ε 1.0`); a code comment + docs MUST state why.
+
+### Honesty / scope
+- **R12.** Docs MUST state the proof covers the **route Q-learning loop only** (tabular,
+  same-distribution held-out instances), not the LoRA/SONA path (Tier 2) and not unseen
+  states (F3).
+- **R13.** Docs MUST capture finding F2 (CLI `route feedback` non-persistence) as an
+  upstream bug, with the one-line fix (call `saveModel()` after `update()`, or
+  `autoSaveInterval: 1`).
+- **R14.** All new shell remains bash 3.2-compatible; the harness is Node and degrades
+  gracefully if the global ruflo router module can't be resolved (exit 2 with guidance).
+
+## 5. Behavioral scenarios
+
+- **S1 (proof passes):** cold acc ≈ 1/8 (~12%); after training over N seeds, held-out greedy
+  acc ≈ 75–90%; ablation stays ≈ 12%; permutation p<0.05, Cohen's d≥0.8, above chance,
+  ε decayed, δ̄ shrunk → verdict PASS; footer shows
+  `📈 RL ▁▂▄▆▇ acc 12%→78% Δ+66pp (CI±7) · p<.001 · d=2.1 · ε0.12↓ · δ̄0.01↓ · |Q|24`.
+- **S2 (honest failure):** if held-out acc does **not** beat the ablation beyond CI, verdict
+  FAIL and the footer reads `◷ RL unproven` — we report the negative result truthfully.
+- **S3 (no eval run yet):** `improvement.json` absent → footer omits the `📈 RL` line
+  entirely (no false signal).
+- **S4 (smoke run, this session):** a bounded run (small K, few seeds) demonstrates the
+  mechanism end-to-end and writes a real `improvement.json` on this machine.
+- **S5 (upgrade):** after `ruflo init`/upgrade regenerates the statusline, `ruflo-resync`
+  re-injects the `📈 RL` segment (marker-guarded).
+
+## 6. Testing
+
+- The harness is largely self-testing (it *is* an experiment): the ablation (R5) is the
+  internal control; the seed CI (R6) is the noise guard.
+- Add a fast self-check mode (tiny K/seeds) used as the smoke test (S4).
+- Manual acceptance on this machine: capture the before/after `improvement.json` + the
+  rendered footer line in the branch.
+
+## 7. Tier 2 (documented, not built): proving the LoRA/SONA path
+
+To prove the *neural* self-improvement arm (Ciprian's open item), a future effort would:
+1. **Close the integration gap (F5):** patch ruflo so the trained MicroLoRA `B` matrix is
+   consumed at inference (the `forward_array` path feeds the routing/decision scalars),
+   not just trained and stored.
+2. **Re-run this same held-out A/B** with LoRA-consumption ON vs OFF — proof = the
+   LoRA-on arm beats LoRA-off beyond CI on held-out tasks.
+3. **Expected outcome if it works:** a measurable held-out lift attributable specifically
+   to the consumed LoRA delta (today `Δ LoRA` grows but alters no decision).
+This is an upstream source change (a ruflo PR), hence out of scope here.
+
+## 8. Open questions / risks
+
+- **Q1.** State granularity (F3): `qTableSize` was 4 for 5 tasks — some tasks share a
+  keyword-hash state. The suite MUST be designed so each intended state is distinct and its
+  best agent unambiguous; verify `|Q|` matches the number of intended states during
+  implementation.
+- **Q2.** Epsilon decay was slow (0.913 after 200). K and the decay schedule must be large
+  enough that greedy eval actually exploits; tune during the smoke run.
+- **Q3.** Determinism: unseedable `Math.random` → rely on multi-seed aggregation + CI, not
+  exact reproducibility.
diff --git a/docs/upstream/ruflo-self-improvement-findings.md b/docs/upstream/ruflo-self-improvement-findings.md
new file mode 100644
index 00000000..b39fe147
--- /dev/null
+++ b/docs/upstream/ruflo-self-improvement-findings.md
@@ -0,0 +1,164 @@
+# ruflo self-improvement: findings, upstream reconciliation & carry-forward
+
+This documents what we learned investigating whether ruflo is *self-improving* (not just
+self-learning), **which of our findings have since landed upstream (ruflo 3.10.6–3.10.9)**,
+and **what remains as the carry-forward scope for this branch/PR**. Plain-language primer
+first; findings, the upstream reconciliation, and the remaining-issue text follow.
+
+> **Status (2026‑05‑29):** original investigation ran against ruflo **3.10.5**; latest is
+> **3.10.10**. Upstream shipped four releases in one day that absorb most of this — **F1/F2
+> are fixed (#2222, 3.10.6; @pacphi credited)**, a deeper follow-up bug (negative‑reward
+> inversion) was fixed in 3.10.7, route cache + `--explore false` in 3.10.8, and ADR‑142's
+> model-router bandit in 3.10.9. **F3 and F4 remain open and are now filed as two separate,
+> independently-reproduced upstream issues:**
+>
+> - **F3** (route Q-state encoder collapse) → **[ruvnet/ruflo#2239](https://github.com/ruvnet/ruflo/issues/2239)**
+> - **F4** (SONA learn→inference loop unwired at the JS/WASM boundary) → **[ruvnet/ruvector#519](https://github.com/ruvnet/RuVector/issues/519)**
+> - Kit carry-forward (the live RL statusline panel, gated on both) → tracking issue **[pacphi/ruflo-machine-ref#8](https://github.com/pacphi/ruflo-machine-ref/issues/8)**
+>
+> The filed issues are the authoritative write-ups; **F4's framing was corrected during that
+> verification** (see F4 below). Details in the reconciliation table.
+
+## Plain-language primer (no ML background needed)
+
+Picture a **delivery company**. ruflo has *three different* learning systems people conflate:
+
+1. **The Q-learner = the dispatcher** — "which specialist handles this task?" It keeps a
+   scorecard of which agent does well on which task and updates it from results.
+   - **ε (epsilon)**: how often it gambles on a random pick vs its favorite (1.0 = all
+     guessing; should shrink as it learns).
+   - **TD error (δ)**: "how surprised it was" — shrinks toward 0 as it converges.
+   - **|Q|**: how many task-types it has opinions about.
+2. **SONA = a driver's muscle memory** — nudges itself after each action; banks
+   *trajectories* and *patterns*.
+3. **LoRA = the *format* SONA stores tweaks in** — a small "diff sheet" of corrections on a
+   frozen base. **Δ LoRA** = how big the last tweak was.
+
+**Self-learning** (banking experience) vs **self-improving** (using it to get measurably
+better) are different claims. ruflo is clearly self-learning. Whether it's self-improving
+required digging.
+
+## Findings (verified against ruflo 3.10.5 source + experiment)
+
+### F1 — The route Q-learner *does* learn (in-process)
+ruflo's `createQLearningRouter` genuinely learns: 200 in-process updates → Q-table grows,
+ε decays (1.0→0.91), TD error nonzero. The algorithm works. **[Still true on 3.10.9.]**
+
+### F2 — CLI `route feedback` could not persist (BUG) → **FIXED UPSTREAM (3.10.6 #2222)**
+`route.js` `feedbackCommand` called `update()` but **never `saveModel()`**, and
+`q-learning-router.js` defaulted `autoSaveInterval: 100`. Each CLI call is a fresh process
+that loads the model, applies **one** update, and exits before the %100 auto-save triggers —
+so the persisted model never advanced and `route stats` stayed `Update Count 0 / ε 1.0`.
+We reported this; **ruflo 3.10.6 (#2222) fixed it with an explicit `await router.saveModel()`
+after feedback** (verified in installed source: `commands/route.js`). The kit's stopgap
+(`autoSaveInterval: 1`, `ruflo-patch-route-learning`) is therefore **retired on ≥3.10.6** —
+the script is now a version-gated no-op that only applies the legacy patch on installs <3.10.6.
+
+### F2b — Negative-reward inversion → **FIXED UPSTREAM (3.10.7)**, we did *not* catch this
+A deeper bug in the same area: `route feedback -r -1.0` was parsed as **+1.0** — the shared
+flag parser dropped any `-`-prefixed value, so giving **negative** feedback actively
+*reinforced* the bad agent. Fixed in `parser.ts` (3.10.7). We missed it because our
+`ruflo-improvement-eval` drives the router **in-process** and bypasses the CLI flag parser.
+Worth recording: any workflow doing `route feedback -r -<n>` before 3.10.7 trained backwards.
+
+### F3 — The state encoder collapses semantically-distinct tasks → **STILL OPEN**
+`featureVectorToKey`/`extractFeatures` key features 1–32 on keyword *presence* and 33–48 on
+length/word-count buckets; tasks with different routing keywords but similar shape hash to the
+**same** Q-state (verified: six keyword-distinct tasks → 1 state). **Confirmed still open in
+3.10.9 (latest):** the entire `ruvector/q-learning-router.js` is **byte-identical** between the
+installed 3.10.8 and the published 3.10.9 — `extractFeatures`, `featureVectorToKey`, and
+`FEATURE_KEYWORDS` are all unchanged. Note: 3.10.9's ADR‑142 "per-task bandit priors" is a
+**separate subsystem** — `ruvector/model-router.js`, a Thompson‑sampling bandit that selects the
+*LLM model* (Haiku/Sonnet/Opus) by complexity bucket — and has **zero references** to the
+agent-route encoder. So even with F2 fixed, task-specific routing is limited because distinct
+tasks share a policy slot. **This is the carry-forward finding most worth a PR.**
+
+### F4 — SONA learn→inference loop is unwired at the JS/WASM boundary → **FILED: [ruvnet/ruvector#519](https://github.com/ruvnet/RuVector/issues/519)**
+The ruflo-bundled view was: every `SonaCoordinator` call is training/recording, the coordinator
+exposes no `predict`/`forward`, and the trained `Δ LoRA` changes no decision (written, never
+read); 3.10.9 documented the WASM MicroLoRA `apply()` as *"empirically inert (Δ=0 after 200
+adapts)"* and refused to fake a gradient.
+
+**Corrected against actual `ruvnet/ruvector` source (`c2089c4`), before filing** — the bundled
+wording was imprecise and was *not* carried over verbatim:
+- Inference seams **do exist and work**: `applyLora`, `MicroLoRA::forward`, `LoraAdapter.forward`.
+  So this is **not** "no forward path."
+- The real gap is the **learn→adapt loop is unwired through the bindings consumers actually call**:
+  - `WasmSonaEngine::learn_from_feedback` is a **no-op** — it `console.log`s a reward and returns
+    (`crates/sona/src/wasm.rs:183-192`).
+  - The JS `@ruvector/ruvllm` `SonaCoordinator.processInstantLearning` is an **empty stub**
+    (`sona.js:449-452`, "In full implementation, this updates LoRA weights").
+  - The Rust trajectory path adapts **only on multi-step, varying-reward trajectories** — a
+    single-step "one outcome per task" feedback has REINFORCE advantage 0 → **Δ=0 exactly**
+    (reproduced over 200 adapts).
+  - `accumulate_gradient` only writes `up_proj`; `down_proj` is **never** updated (rank-deficient).
+  - Bonus smell: `estimate_gradient` L2-normalizes a near-zero gradient → **amplifies f32 residue
+    into a unit-norm update** for a no-information signal.
+- Reproduced with a `cargo test` against the real crate (`crates/sona/tests/repro_delta_zero.rs`,
+  included verbatim in #519). Consuming a *working* adapter downstream in ruflo is a follow-up
+  gated on ruvector exposing a non-inert seam — not a kit patch. **[Open — filed at ruvector.]**
+
+### F5 — With F2 fixed, the route learner self-improves — significantly but modestly
+Our held-out, ablated, multi-seed experiment (`ruflo-improvement-eval`) over a synthetic
+environment engineered to occupy distinct Q-states (per F3) shows the learner beats a
+no-learning ablation with a **statistically significant, monotone** gain — but a **modest**
+one (it learns the optimal action for only part of the state space within practical episode
+counts, plateauing well below 100%). Honest verdict: **self-improving = yes (proven for the
+consumed loop), but weak.** This result is independent of the F2 fix mechanism and remains the
+kit's reusable proof harness.
+
+```
+route Q-learner · 5 seeds · learning vs no-learning ablation
+  cold 17% → warm 33%   Δ+16pp   permutation p=0.004   Cohen's d=∞   above-chance: yes
+  (modest ceiling — partial learning; see F3 encoder collapse + slow ε decay)
+```
+
+## Upstream reconciliation (ruflo 3.10.6 → 3.10.9)
+
+| Our finding / kit artifact | Upstream status | Verdict for this kit |
+|---|---|---|
+| **F2** route feedback never persists | **Fixed 3.10.6 (#2222)** — `await router.saveModel()`; @pacphi credited | `ruflo-patch-route-learning` **retired** (no-op ≥3.10.6) |
+| **F2b** negative-reward inversion (we missed) | **Fixed 3.10.7** — parser accepts `-`-prefixed values | n/a (our eval is in-process) |
+| Bug B — stale route cache hid learning | **Fixed 3.10.8** — per-state cache invalidation in `update()` | aligns with the "no effect" symptom |
+| Bug C — `--explore false` ignored | **Fixed 3.10.8** — parser honors explicit boolean values | exploration knob now controllable |
+| **F3** state encoder collapses tasks | **Still open in 3.10.9** (`q-learning-router.js` byte-identical 3.10.8→3.10.9; ADR‑142 is the separate `model-router.js`) | **carry-forward — offer a PR** |
+| **F4** LoRA/SONA not consumed at inference | **Confirmed + deferred** (3.10.9: `apply()` inert, won't fake it) | upstream R&D in `@ruvector/ruvllm` |
+| Fabricated Flash-Attention metric (RNG) | **Removed 3.10.7**; "150×–12,500× / 2.49–7.47×" marked unverified | update any kit docs that still quote those |
+
+The most striking takeaway is **methodological convergence**: this kit, Ciprian Melian's
+`ruflo-aqe-kit`, and upstream ruflo all adopted the same integrity discipline on the same day
+— falsifiable verdicts, "self-learns but self-improvement unproven," and a refusal to fabricate
+signals (the Flash RNG metric removed; the inert LoRA Δ not faked).
+
+## Carry-forward scope for this branch / PR
+
+What this PR still contributes, now that F1/F2 are upstream:
+
+- **`ruflo-improvement-eval`** — the held-out, ablated, multi-seed proof harness (permutation
+  p + Cohen's d). Still unique; complements upstream's `benchmark-intelligence.mjs`. The
+  measuring stick for any future F4/Tier-2 work. `--cli-check` is now version-aware (recognizes
+  the 3.10.6 `saveModel()` fix).
+- **F3 (state-encoder collapse)** — the one finding entirely unaddressed upstream. Carry forward
+  as a proposed encoder tweak / upstream PR.
+- **F4 (LoRA/SONA inference gap)** — keep as a tracked upstream item; aligned with ruflo's own
+  deferred punch-list (`docs/reviews/intelligence-system-audit-2026-05-29.md`).
+- **`ruflo-patch-route-learning`** — retained only as a **version-gated legacy shim** for
+  installs <3.10.6; no longer part of `ruflo-resync`.
+
+## Upstream issues (filed 2026‑05‑29)
+
+F3 and F4 were each filed as a **separate, independently-reproduced** issue in the repo that
+owns the code (not an omnibus), keeping #2222's evidence-first, reproducible tone:
+
+| Finding | Repo (owns the code) | Issue | Reproduction |
+|---|---|---|---|
+| **F3** — route Q-state encoder discards the keyword block (31-bit hash-fold truncation); keyword-distinct tasks collapse to one Q-state | `ruvnet/ruflo` (`q-learning-router.js`) | [#2239](https://github.com/ruvnet/ruflo/issues/2239) | `ruflo-improvement-eval --probe-states`; group-survival + zero-keyword-groups probe |
+| **F4** — SONA learn→inference loop unwired at the JS/WASM boundary (`learn_from_feedback` no-op; single-step REINFORCE Δ=0; up-only adaptation) | `ruvnet/ruvector` (`crates/sona`, `@ruvector/ruvllm`) | [#519](https://github.com/ruvnet/RuVector/issues/519) | `cargo test -p ruvector-sona --test repro_delta_zero` (4 cases, included in the issue) |
+
+The downstream kit carry-forward — a **live RL statusline panel** (route ε/δ̄/|Q| from the
+persisted Q-model, eval verdict, SONA signal gated on F4) — is tracked separately in
+[pacphi/ruflo-machine-ref#8](https://github.com/pacphi/ruflo-machine-ref/issues/8) and is gated
+on both upstream fixes landing.
+
+Environment: ruflo 3.10.10, Node 26, `ruvnet/ruvector@c2089c4`. Repro tool:
+`ruflo-improvement-eval` (https://github.com/pacphi/ruflo-machine-ref).