@claude-flow/cli 3.10.20 → 3.10.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.10.20",
+  "version": "3.10.22",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",

package/scripts/benchmark-pretrained-retrieval.mjs

@@ -20,23 +20,86 @@ const CLI_ROOT = resolve(SCRIPT_DIR, '..');
 const REPO_ROOT = resolve(SCRIPT_DIR, '../../../..');
 const RUNS_DIR = join(REPO_ROOT, 'docs', 'benchmarks', 'runs');
 
-// Real ruflo-history-shaped queries. Each one targets a concept that should
-// have been seen during pretrain. `expect` is a regex matched against the
-// result's `name` field (commit subject or issue title) to score relevance.
-// A result is "relevant" if its name matches the expect regex (case-insensitive).
+// ADR-081 labelled held-out corpus. Each query has hand-curated
+// `expectedSubstrings` — case-insensitive substring matches against the
+// pattern's name. A result is "relevant" if its name contains ANY of the
+// substrings. Tighter than the regex proxy used in ADRs 077-080 (which
+// matched related-but-not-exact commits).
+//
+// `expect` (regex) is kept for backwards compatibility with the older
+// numbers in ADRs 077-080. New metrics use expectedSubstrings.
 const QUERIES = [
-  { q: 'how was the Opus model alias fixed', expect: /opus|2232|model.*alias|4\.8/i },
-  { q: 'self-learning wiring task-completed pretrain', expect: /self.?learning|task.?completed|pretrain|2245|074/i },
-  { q: 'deterministic codemod engine var-to-const', expect: /codemod|var.?to.?const|143|deterministic/i },
-  { q: 'MCP server orphan leak parent-death', expect: /mcp.*orphan|orphan.*mcp|parent.?death|leak/i },
-  { q: 'unified learning stats aggregator', expect: /unified|stats|aggregator|075/i },
-  { q: 'structured distillation 4-field schema', expect: /distillation|structured|076|4.?field/i },
-  { q: 'SQL injection migrate.ts table identifier', expect: /sql.?injection|migrate|table|identifier/i },
-  { q: 'recall@k HNSW benchmark harness', expect: /recall|hnsw|benchmark|harness/i },
-  { q: 'Q-learning encoder keyword block', expect: /q.?learning|encoder|keyword|2239/i },
-  { q: 'security hardening crypto random IDs', expect: /security|hardening|crypto|random/i },
+  {
+    q: 'how was the Opus model alias fixed',
+    expect: /opus|2232|model.*alias|4\.8/i,
+    expectedSubstrings: ['opus 4.8', 'opus alias', 'opus model alias', '#2232'],
+  },
+  {
+    q: 'self-learning wiring task-completed pretrain',
+    expect: /self.?learning|task.?completed|pretrain|2245|074/i,
+    expectedSubstrings: ['self-learning', 'adr-074', 'self learning', '#2245', 'task-completed'],
+  },
+  {
+    q: 'deterministic codemod engine var-to-const',
+    expect: /codemod|var.?to.?const|143|deterministic/i,
+    expectedSubstrings: ['deterministic tier-1 codemod', 'adr-143', 'codemod', 'var-to-const'],
+  },
+  {
+    q: 'MCP server orphan leak parent-death',
+    expect: /mcp.*orphan|orphan.*mcp|parent.?death|leak/i,
+    expectedSubstrings: ['mcp orphan', 'mcp servers orphan', 'parent-death', '#2234', 'orphan on every claude'],
+  },
+  {
+    q: 'unified learning stats aggregator',
+    expect: /unified|stats|aggregator|075/i,
+    expectedSubstrings: ['unified learning-stats', 'adr-075', 'unified learning stats'],
+  },
+  {
+    q: 'structured distillation 4-field schema',
+    expect: /distillation|structured|076|4.?field/i,
+    expectedSubstrings: ['structured distillation', 'adr-076', '4-field schema'],
+  },
+  {
+    q: 'SQL injection migrate.ts table identifier',
+    expect: /sql.?injection|migrate|table|identifier/i,
+    expectedSubstrings: ['sql injection', 'shell injection', 'migrate.ts', 'agentdb', 'cve'],
+  },
+  {
+    q: 'recall@k HNSW benchmark harness',
+    expect: /recall|hnsw|benchmark|harness/i,
+    expectedSubstrings: ['hnsw', 'memory-recall', 'benchmark suite', 'recall@k', 'benchmark intelligence'],
+  },
+  {
+    q: 'Q-learning encoder keyword block',
+    expect: /q.?learning|encoder|keyword|2239/i,
+    expectedSubstrings: ['q-state encoder', 'route q-state', 'keyword block', '#2239', 'q-encoder'],
+  },
+  {
+    q: 'security hardening crypto random IDs',
+    expect: /security|hardening|crypto|random/i,
+    expectedSubstrings: ['cwe-347', 'crypto.randomuuid', 'security fix', 'random id', 'crypto random'],
+  },
 ];
 
+/** Returns true if name contains ANY of the labelled substrings (case-insensitive). */
+function isRelevant(name, expectedSubstrings) {
+  if (!name || !expectedSubstrings?.length) return false;
+  const lower = String(name).toLowerCase();
+  return expectedSubstrings.some((s) => lower.includes(s.toLowerCase()));
+}
+
+/** nDCG@k with binary relevance (each relevant item contributes 1 / log2(i+1)). */
+function ndcgAtK(rankedRelevance, k) {
+  const arr = rankedRelevance.slice(0, k);
+  const dcg = arr.reduce((acc, rel, i) => acc + (rel ? 1 / Math.log2(i + 2) : 0), 0);
+  const numRelevant = arr.filter(Boolean).length;
+  if (numRelevant === 0) return 0;
+  // Ideal: all relevant items packed at positions 1..numRelevant
+  let idcg = 0;
+  for (let i = 0; i < numRelevant; i++) idcg += 1 / Math.log2(i + 2);
+  return idcg > 0 ? dcg / idcg : 0;
+}
+
 const TOP_K = 5;
 
 async function main() {
@@ -66,32 +129,45 @@ async function main() {
 
   const tQuery0 = performance.now();
   const results = [];
-  for (const { q, expect } of QUERIES) {
+  for (const { q, expect, expectedSubstrings } of QUERIES) {
     const r = await listTool.handler({ action: 'search', query: q, mode, limit: TOP_K, rerank: useRerank });
     const matches = (r.patterns || r.results || r.matches || []).slice(0, TOP_K);
     if (matches.length > 0) {
       const top1 = matches[0].id;
       top1Ids.set(top1, (top1Ids.get(top1) ?? 0) + 1);
     }
-    // ADR-078 relevance: does the top-1/top-3 name match the expect regex?
-    const top1Name = matches[0]?.name ?? '';
-    const top1Relevant = expect.test(top1Name);
-    let top3Relevant = false;
-    let firstRelevantRank = -1;
-    for (let i = 0; i < Math.min(matches.length, 3); i++) {
-      if (expect.test(matches[i]?.name ?? '')) {
-        top3Relevant = true;
-        if (firstRelevantRank === -1) firstRelevantRank = i + 1;
-        break;
-      }
+
+    // Two relevance signals per result:
+    //   regexRel — old proxy (kept for back-compat with ADR-077-080 numbers)
+    //   labelRel — ADR-081 hand-curated label match
+    const regexRel = matches.map((m) => expect.test(m?.name ?? ''));
+    const labelRel = matches.map((m) => isRelevant(m?.name, expectedSubstrings));
+
+    // First rank where a labelled-relevant doc appears.
+    let firstLabelRank = -1;
+    for (let i = 0; i < matches.length; i++) {
+      if (labelRel[i]) { firstLabelRank = i + 1; break; }
     }
+    let firstRegexRank = -1;
+    for (let i = 0; i < matches.length; i++) {
+      if (regexRel[i]) { firstRegexRank = i + 1; break; }
+    }
+
     results.push({
       query: q,
       matched: matches.length > 0,
-      top1Relevant,
-      top3Relevant,
-      firstRelevantRank,
-      topK: matches.map((m) => ({
+      // Regex-proxy metrics (back-compat with ADR-077-080)
+      top1Relevant: regexRel[0] || false,
+      top3Relevant: regexRel.slice(0, 3).some(Boolean),
+      firstRelevantRank: firstRegexRank,
+      // ADR-081 labelled metrics
+      label_top1: labelRel[0] || false,
+      label_top3_count: labelRel.slice(0, 3).filter(Boolean).length,
+      label_top5_count: labelRel.slice(0, 5).filter(Boolean).length,
+      label_firstRank: firstLabelRank,
+      label_ndcg3: ndcgAtK(labelRel, 3),
+      label_ndcg5: ndcgAtK(labelRel, 5),
+      topK: matches.map((m, i) => ({
         id: m.id,
         name: m.name?.slice(0, 100),
         type: m.type,
@@ -99,20 +175,38 @@ async function main() {
         cosineScore: m.cosineScore,
         bm25Score: m.bm25Score,
         mmrScore: m.mmrScore,
+        labelRelevant: labelRel[i],
       })),
     });
   }
   const queryMs = performance.now() - tQuery0;
 
   const matchedQueries = results.filter((r) => r.matched).length;
+  // Regex-proxy metrics (back-compat)
   const top1Hits = results.filter((r) => r.top1Relevant).length;
   const top3Hits = results.filter((r) => r.top3Relevant).length;
   const ranks = results.filter((r) => r.firstRelevantRank > 0).map((r) => r.firstRelevantRank);
-  // MRR over the top-3 window (rank-of-first-relevant). Queries with no
-  // relevant result in top-3 contribute 0 to the mean.
   const mrr3 = QUERIES.length > 0
     ? Number((ranks.reduce((s, r) => s + 1 / r, 0) / QUERIES.length).toFixed(4))
     : 0;
+
+  // ADR-081 labelled metrics — tighter ground truth than regex proxy.
+  const label_top1Hits = results.filter((r) => r.label_top1).length;
+  const label_top3HitsBinary = results.filter((r) => r.label_top3_count > 0).length;
+  const label_ranks = results.filter((r) => r.label_firstRank > 0).map((r) => r.label_firstRank);
+  const label_mrr3 = QUERIES.length > 0
+    ? Number((label_ranks.reduce((s, r) => s + 1 / r, 0) / QUERIES.length).toFixed(4))
+    : 0;
+  const label_ndcg3_mean = QUERIES.length > 0
+    ? Number((results.reduce((s, r) => s + r.label_ndcg3, 0) / QUERIES.length).toFixed(4))
+    : 0;
+  const label_ndcg5_mean = QUERIES.length > 0
+    ? Number((results.reduce((s, r) => s + r.label_ndcg5, 0) / QUERIES.length).toFixed(4))
+    : 0;
+  // Mean precision@3 — fraction of top-3 that's relevant per query, averaged.
+  const label_precision3 = QUERIES.length > 0
+    ? Number((results.reduce((s, r) => s + r.label_top3_count / 3, 0) / QUERIES.length).toFixed(4))
+    : 0;
   // top-1 collision: number of distinct top-1 IDs over the query count.
   const uniqueTop1 = top1Ids.size;
   const top1Diversity = Number((uniqueTop1 / QUERIES.length).toFixed(4));
@@ -141,9 +235,17 @@ async function main() {
     queries: QUERIES.length,
     matchedQueries,
     matchRate: Number((matchedQueries / QUERIES.length).toFixed(4)),
-    top1HitRate: Number((top1Hits / QUERIES.length).toFixed(4)),  // ADR-078: relevance, not just any-match
+    // Regex-proxy metrics (ADR-077-080 back-compat)
+    top1HitRate: Number((top1Hits / QUERIES.length).toFixed(4)),
     top3HitRate: Number((top3Hits / QUERIES.length).toFixed(4)),
-    mrr3,                              // mean reciprocal rank over top-3
+    mrr3,
+    // ADR-081 labelled metrics — tighter ground truth
+    label_top1HitRate: Number((label_top1Hits / QUERIES.length).toFixed(4)),
+    label_top3HitRate: Number((label_top3HitsBinary / QUERIES.length).toFixed(4)),
+    label_mrr3,
+    label_precision3,
+    label_ndcg3: label_ndcg3_mean,
+    label_ndcg5: label_ndcg5_mean,
     top1Diversity,                     // 1.0 = every query gets a distinct top-1
     top3DupRate,                       // 0.0 = no duplicate IDs inside any top-3
     avgQueryLatencyMs: Number((queryMs / QUERIES.length).toFixed(2)),
@@ -160,9 +262,16 @@ async function main() {
     console.log(`Store size: ${total} patterns`);
     console.log(`Queries: ${QUERIES.length}`);
     console.log(`Match rate: ${(summary.matchRate * 100).toFixed(0)}% (${matchedQueries}/${QUERIES.length})`);
-    console.log(`Top-1 hit rate (RELEVANCE): ${(summary.top1HitRate * 100).toFixed(0)}% (${top1Hits}/${QUERIES.length})`);
-    console.log(`Top-3 hit rate (RELEVANCE): ${(summary.top3HitRate * 100).toFixed(0)}% (${top3Hits}/${QUERIES.length})`);
-    console.log(`MRR@3: ${summary.mrr3}`);
+    console.log(`Top-1 hit rate (regex proxy): ${(summary.top1HitRate * 100).toFixed(0)}% (${top1Hits}/${QUERIES.length})`);
+    console.log(`Top-3 hit rate (regex proxy): ${(summary.top3HitRate * 100).toFixed(0)}% (${top3Hits}/${QUERIES.length})`);
+    console.log(`MRR@3 (regex proxy):          ${summary.mrr3}`);
+    console.log('');
+    console.log(`Top-1 hit rate (ADR-081 labelled): ${(summary.label_top1HitRate * 100).toFixed(0)}% (${label_top1Hits}/${QUERIES.length})`);
+    console.log(`Top-3 hit rate (ADR-081 labelled): ${(summary.label_top3HitRate * 100).toFixed(0)}% (${label_top3HitsBinary}/${QUERIES.length})`);
+    console.log(`MRR@3 (labelled):                  ${summary.label_mrr3}`);
+    console.log(`Precision@3 (labelled, mean):      ${summary.label_precision3}`);
+    console.log(`nDCG@3 (labelled, mean):           ${summary.label_ndcg3}`);
+    console.log(`nDCG@5 (labelled, mean):           ${summary.label_ndcg5}`);
     console.log(`Top-1 diversity: ${(summary.top1Diversity * 100).toFixed(0)}% (${uniqueTop1} distinct top-1 IDs across ${QUERIES.length} queries)`);
     console.log(`Top-3 dup rate: ${(summary.top3DupRate * 100).toFixed(0)}%`);
     console.log(`Avg query latency: ${summary.avgQueryLatencyMs} ms`);

package/scripts/grid-search-retrieval.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// grid-search-retrieval.mjs — sweep retrieval hyperparameters against the
+// ADR-081 labelled corpus. Reports label nDCG@3, top-1, top-3, precision@3,
+// MRR@3 per configuration. Identifies the best non-rerank and best rerank
+// configs by nDCG@3.
+//
+// Run prerequisites: scripts/pretrain-from-github.mjs first.
+//
+// Usage:
+//   node scripts/grid-search-retrieval.mjs                 # default grid
+//   node scripts/grid-search-retrieval.mjs --quick         # smaller grid
+//   BENCH_JSON=1 node scripts/grid-search-retrieval.mjs    # machine-readable
+//
+// Output also goes to docs/benchmarks/runs/grid-search-retrieval-<ts>.json
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const CLI_ROOT = resolve(SCRIPT_DIR, '..');
+const REPO_ROOT = resolve(SCRIPT_DIR, '../../../..');
+const RUNS_DIR = join(REPO_ROOT, 'docs', 'benchmarks', 'runs');
+
+// Same labelled corpus as benchmark-pretrained-retrieval.mjs (ADR-081).
+const QUERIES = [
+  { q: 'how was the Opus model alias fixed',
+    labels: ['opus 4.8', 'opus alias', 'opus model alias', '#2232'] },
+  { q: 'self-learning wiring task-completed pretrain',
+    labels: ['self-learning', 'adr-074', 'self learning', '#2245', 'task-completed'] },
+  { q: 'deterministic codemod engine var-to-const',
+    labels: ['deterministic tier-1 codemod', 'adr-143', 'codemod', 'var-to-const'] },
+  { q: 'MCP server orphan leak parent-death',
+    labels: ['mcp orphan', 'mcp servers orphan', 'parent-death', '#2234', 'orphan on every claude'] },
+  { q: 'unified learning stats aggregator',
+    labels: ['unified learning-stats', 'adr-075', 'unified learning stats'] },
+  { q: 'structured distillation 4-field schema',
+    labels: ['structured distillation', 'adr-076', '4-field schema'] },
+  { q: 'SQL injection migrate.ts table identifier',
+    labels: ['sql injection', 'shell injection', 'migrate.ts', 'agentdb', 'cve'] },
+  { q: 'recall@k HNSW benchmark harness',
+    labels: ['hnsw', 'memory-recall', 'benchmark suite', 'recall@k', 'benchmark intelligence'] },
+  { q: 'Q-learning encoder keyword block',
+    labels: ['q-state encoder', 'route q-state', 'keyword block', '#2239', 'q-encoder'] },
+  { q: 'security hardening crypto random IDs',
+    labels: ['cwe-347', 'crypto.randomuuid', 'security fix', 'random id', 'crypto random'] },
+];
+
+function isRelevant(name, labels) {
+  if (!name || !labels?.length) return false;
+  const lower = String(name).toLowerCase();
+  return labels.some((s) => lower.includes(s.toLowerCase()));
+}
+
+function ndcgAtK(rankedRel, k) {
+  const arr = rankedRel.slice(0, k);
+  const dcg = arr.reduce((acc, rel, i) => acc + (rel ? 1 / Math.log2(i + 2) : 0), 0);
+  const numRelevant = arr.filter(Boolean).length;
+  if (numRelevant === 0) return 0;
+  let idcg = 0;
+  for (let i = 0; i < numRelevant; i++) idcg += 1 / Math.log2(i + 2);
+  return idcg > 0 ? dcg / idcg : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Grid definitions
+// ---------------------------------------------------------------------------
+
+const QUICK = process.argv.includes('--quick');
+
+// Non-rerank grid: alpha × subjectWeight × mmrLambda
+const ALPHA_GRID = QUICK ? [0.5, 0.7] : [0.3, 0.5, 0.7];
+const SUBJ_GRID = QUICK ? [3.0, 5.0] : [2.0, 3.0, 5.0];
+const MMR_GRID = QUICK ? [0.5] : [0.3, 0.5, 0.7];
+
+// Rerank grid: hybridWeight × ceWeight (mutually constrained — they sum to 1)
+const RERANK_GRID = QUICK
+  ? [[0.5, 0.5]]
+  : [[0.3, 0.7], [0.4, 0.6], [0.5, 0.5], [0.6, 0.4], [0.7, 0.3]];
+
+// ---------------------------------------------------------------------------
+// Eval
+// ---------------------------------------------------------------------------
+
+async function evalConfig(tool, params) {
+  let top1Hits = 0, top3HitsBin = 0, ranks = [], ndcg3Sum = 0, prec3Sum = 0;
+  const tStart = performance.now();
+  for (const { q, labels } of QUERIES) {
+    const r = await tool.handler({ action: 'search', query: q, mode: 'hybrid', limit: 5, ...params });
+    const matches = (r.results || []).slice(0, 5);
+    const rel = matches.map((m) => isRelevant(m?.name, labels));
+    if (rel[0]) top1Hits++;
+    if (rel.slice(0, 3).some(Boolean)) top3HitsBin++;
+    const firstRank = rel.findIndex(Boolean);
+    if (firstRank >= 0) ranks.push(firstRank + 1);
+    ndcg3Sum += ndcgAtK(rel, 3);
+    prec3Sum += rel.slice(0, 3).filter(Boolean).length / 3;
+  }
+  const elapsed = performance.now() - tStart;
+  return {
+    label_top1HitRate: top1Hits / QUERIES.length,
+    label_top3HitRate: top3HitsBin / QUERIES.length,
+    label_mrr3: ranks.reduce((s, r) => s + 1 / r, 0) / QUERIES.length,
+    label_precision3: prec3Sum / QUERIES.length,
+    label_ndcg3: ndcg3Sum / QUERIES.length,
+    avgLatencyMs: elapsed / QUERIES.length,
+  };
+}
+
+async function main() {
+  const neural = await import(join(CLI_ROOT, 'dist/src/mcp-tools/neural-tools.js'));
+  const tool = neural.neuralTools.find((t) => t.name === 'neural_patterns');
+  if (!tool) throw new Error('neural_patterns tool not found');
+
+  const configs = [];
+
+  // §A — non-rerank grid (fast, ~3*3*3 = 27 configs at default)
+  for (const alpha of ALPHA_GRID) {
+    for (const subjectWeight of SUBJ_GRID) {
+      for (const mmrLambda of MMR_GRID) {
+        configs.push({
+          name: `hybrid α=${alpha} sw=${subjectWeight} mmr=${mmrLambda}`,
+          rerank: false,
+          params: { rerank: false, alpha, subjectWeight, mmrLambda, bodyWeight: 1.0, typePenaltyFactor: 1.0 },
+        });
+      }
+    }
+  }
+
+  // §B — rerank grid (slow, ~5 configs — each query takes ~1s with CE)
+  for (const [hybridWeight, ceWeight] of RERANK_GRID) {
+    configs.push({
+      name: `rerank hw=${hybridWeight} cw=${ceWeight}`,
+      rerank: true,
+      params: { rerank: true, alpha: 0.6, subjectWeight: 3.0, hybridWeight, ceWeight },
+    });
+  }
+
+  console.log(`Grid-search: ${configs.length} configs across ${QUERIES.length} queries\n`);
+  const results = [];
+  for (const cfg of configs) {
+    process.stdout.write(`  ${cfg.name.padEnd(40)} … `);
+    const m = await evalConfig(tool, cfg.params);
+    results.push({ ...cfg, metrics: m });
+    console.log(`top1=${(m.label_top1HitRate * 100).toFixed(0)}% top3=${(m.label_top3HitRate * 100).toFixed(0)}% nDCG3=${m.label_ndcg3.toFixed(3)} P3=${m.label_precision3.toFixed(3)} MRR3=${m.label_mrr3.toFixed(3)} ${m.avgLatencyMs.toFixed(0)}ms`);
+  }
+
+  // Rank by label nDCG@3 (the canonical relevance metric).
+  const byNdcg = [...results].sort((a, b) => b.metrics.label_ndcg3 - a.metrics.label_ndcg3);
+  const byTop1 = [...results].sort((a, b) => b.metrics.label_top1HitRate - a.metrics.label_top1HitRate || b.metrics.label_ndcg3 - a.metrics.label_ndcg3);
+  const byPrec3 = [...results].sort((a, b) => b.metrics.label_precision3 - a.metrics.label_precision3 || b.metrics.label_ndcg3 - a.metrics.label_ndcg3);
+
+  const bestNonRerankByNdcg = byNdcg.find((r) => !r.rerank);
+  const bestRerankByNdcg = byNdcg.find((r) => r.rerank);
+
+  console.log('\n=== Top 5 by label nDCG@3 ===');
+  for (const r of byNdcg.slice(0, 5)) {
+    console.log(`  nDCG=${r.metrics.label_ndcg3.toFixed(3)}  top1=${(r.metrics.label_top1HitRate * 100).toFixed(0)}%  P3=${r.metrics.label_precision3.toFixed(3)}  ${r.name}`);
+  }
+
+  console.log('\n=== Top 5 by label top-1 (ties broken by nDCG) ===');
+  for (const r of byTop1.slice(0, 5)) {
+    console.log(`  top1=${(r.metrics.label_top1HitRate * 100).toFixed(0)}%  nDCG=${r.metrics.label_ndcg3.toFixed(3)}  P3=${r.metrics.label_precision3.toFixed(3)}  ${r.name}`);
+  }
+
+  console.log('\n=== Top 5 by label precision@3 ===');
+  for (const r of byPrec3.slice(0, 5)) {
+    console.log(`  P3=${r.metrics.label_precision3.toFixed(3)}  top1=${(r.metrics.label_top1HitRate * 100).toFixed(0)}%  nDCG=${r.metrics.label_ndcg3.toFixed(3)}  ${r.name}`);
+  }
+
+  console.log(`\n=== WINNERS ===`);
+  console.log(`Best non-rerank (by nDCG@3):   ${bestNonRerankByNdcg.name}  → top1=${(bestNonRerankByNdcg.metrics.label_top1HitRate * 100).toFixed(0)}% nDCG=${bestNonRerankByNdcg.metrics.label_ndcg3.toFixed(3)}`);
+  console.log(`Best rerank (by nDCG@3):       ${bestRerankByNdcg.name}  → top1=${(bestRerankByNdcg.metrics.label_top1HitRate * 100).toFixed(0)}% nDCG=${bestRerankByNdcg.metrics.label_ndcg3.toFixed(3)}`);
+
+  const summary = {
+    runAt: new Date().toISOString(),
+    benchmark: 'grid-search-retrieval',
+    queries: QUERIES.length,
+    configsEvaluated: configs.length,
+    grid: { ALPHA_GRID, SUBJ_GRID, MMR_GRID, RERANK_GRID },
+    results: results.map((r) => ({ name: r.name, rerank: r.rerank, params: r.params, metrics: r.metrics })),
+    winners: {
+      nDcg3: byNdcg[0].name,
+      top1: byTop1[0].name,
+      precision3: byPrec3[0].name,
+      bestNonRerank: bestNonRerankByNdcg.name,
+      bestRerank: bestRerankByNdcg.name,
+    },
+  };
+
+  if (process.env.BENCH_JSON) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    mkdirSync(RUNS_DIR, { recursive: true });
+    const stamp = summary.runAt.replace(/[:.]/g, '-');
+    writeFileSync(join(RUNS_DIR, `grid-search-retrieval-${stamp}.json`), JSON.stringify(summary, null, 2));
+    writeFileSync(join(RUNS_DIR, 'grid-search-retrieval-latest.json'), JSON.stringify(summary, null, 2));
+    console.log(`\nWrote ${join(RUNS_DIR, `grid-search-retrieval-${stamp}.json`)}`);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });