sigmap 5.0.0 → 5.2.0

package/AGENTS.md

@@ -12,20 +12,23 @@ Use this marker block for all appendable context files:
 ## Auto-generated signatures
 <!-- Updated by gen-context.js -->
 You are a coding assistant with full knowledge of this codebase.
-Below are the code signatures extracted by SigMap v4.1.2 on 2026-04-16T17:45:07.132Z.
+Below are the code signatures extracted by SigMap v5.2.0 on 2026-04-16T22:22:03.099Z.
 
 Use these signatures to answer questions about the code accurately.
 
 ## Code Signatures
 
-<!-- Generated by SigMap gen-context.js v4.1.2 -->
+<!-- Generated by SigMap gen-context.js v5.2.0 -->
 <!-- DO NOT EDIT below the marker line — run gen-context.js to regenerate -->
 
 # Code signatures
 
-## changes (last 5 commits — 53 minutes ago)
+## changes (last 5 commits — 41 minutes ago)
 ```
-src/retrieval/ranker.js                       +_parseContextFile  +buildSigIndex  ~buildSigIndex  ~rank
+src/config/loader.js                          +loadBaseConfig  ~loadConfig  ~deepClone
+src/format/dashboard.js                       ~computeExtractorCoverage  ~readBenchmarkTrend
+src/judge/judge-engine.js                     +tokenize  +groundedness  +judge
+src/retrieval/ranker.js                       +detectIntent  ~formatRankJSON
 ```
 
 ## packages
@@ -146,9 +149,42 @@ function adapt(context, adapterName, opts = {}) → string
 
 ## src
 
-### src/config/defaults.js
+### src/config/loader.js
 ```
-module.exports = { DEFAULTS }
+module.exports = { loadConfig, loadBaseConfig }
+function loadBaseConfig(extendsVal, cwd)
+function detectAutoSrcDirs(cwd, excludeList) → string[]
+function loadConfig(cwd) → object
+function deepClone(obj)
+```
+
+### src/format/dashboard.js
+```
+module.exports = { generateDashboardHtml, renderHistoryCharts, computeExtractorCoverage, percentile, overBudgetStreak }
+function toNumber(v)
+function percentile(values, p)
+function overBudgetStreak(entries)
+function loadConfig(cwd)
+function shouldExclude(rel, excludeSet)
+function detectLanguage(filePath)
+function walkFiles(dir, maxDepth, depth, out, excludeSet)
+function computeExtractorCoverage(cwd)
+function readBenchmarkTrend(cwd)
+function lineChartSvg(values, title, ySuffix)
+function barChartSvg(perLanguage)
+function sparkline(values)
+function buildDashboardData(cwd, health)
+function generateDashboardHtml(cwd, health)
+function renderHistoryCharts(cwd, health)
+```
+
+### src/judge/judge-engine.js
+```
+module.exports = { groundedness, judge }
+function tokenize(text)
+function groundedness(response, context)
+function extractContextFiles(context, cwd)
+function judge(response, context, opts = {})
 ```
 
 ### src/mcp/server.js
@@ -162,13 +198,14 @@ function start(cwd)
 
 ### src/retrieval/ranker.js
 ```
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS }
+module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent }
 function scoreFile(filePath, sigs, queryTokens, weights) → number
 function rank(query, sigIndex, opts) → { file: string, score: nu
 function _parseContextFile(contextPath) → Map<string, string[]>
 function buildSigIndex(cwd, opts) → Map<string, string[]>
 function formatRankTable(results, query) → string
 function formatRankJSON(results, query) → object
+function detectIntent(query)
 ```
 
 ### src/analysis/coverage-score.js
@@ -178,12 +215,9 @@ function coverageScore(cwd, fileEntries, config) → { * score: number, * grad
 function _walk(dir, excludeSet, out)
 ```
 
-### src/config/loader.js
+### src/config/defaults.js
 ```
-module.exports = { loadConfig }
-function detectAutoSrcDirs(cwd, excludeList) → string[]
-function loadConfig(cwd) → object
-function deepClone(obj)
+module.exports = { DEFAULTS }
 ```
 
 ### src/eval/analyzer.js
@@ -527,26 +561,6 @@ function formatCache(content) → string
 function formatCachePayload(content, model) → string
 ```
 
-### src/format/dashboard.js
-```
-module.exports = { generateDashboardHtml, renderHistoryCharts, computeExtractorCoverage, percentile, overBudgetStreak }
-function toNumber(v)
-function percentile(values, p)
-function overBudgetStreak(entries)
-function loadConfig(cwd)
-function shouldExclude(rel, excludeSet)
-function detectLanguage(filePath)
-function walkFiles(dir, maxDepth, depth, out, excludeSet)
-function computeExtractorCoverage(cwd)
-function readBenchmarkTrend(cwd)
-function lineChartSvg(values, title, ySuffix)
-function barChartSvg(perLanguage)
-function sparkline(values)
-function buildDashboardData(cwd, health)
-function generateDashboardHtml(cwd, health)
-function renderHistoryCharts(cwd, health)
-```
-
 ### src/format/llm-txt.js
 ```
 module.exports = { format, outputPath }
@@ -590,6 +604,21 @@ module.exports = { score }
 function score(cwd) → { * score: number, * grad
 ```
 
+### src/learning/weights.js
+```
+module.exports = { BASELINE, DECAY, MAX_MULT, MIN_MULT, weightsPath, clampMultiplier, normalizeFile, loadWeights, saveWeights, updateWeights, boostFiles, penalizeFiles, resetWeights }
+function weightsPath(cwd)
+function clampMultiplier(value)
+function normalizeFile(cwd, filePath)
+function sanitizeWeights(cwd, weights)
+function loadWeights(cwd)
+function saveWeights(cwd, weights)
+function updateWeights(cwd, opts = {})
+function boostFiles(cwd, files, amount = 0.15)
+function penalizeFiles(cwd, files, amount = 0.10)
+function resetWeights(cwd)
+```
+
 ### src/map/class-hierarchy.js
 ```
 module.exports = { analyze }

package/CHANGELOG.md

@@ -10,6 +10,30 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [5.2.0] — 2026-04-17
+
+### Added
+
+- **Learning engine** — new local-only weight store at `.context/weights.json` with path-normalized per-file multipliers, clamp safety (`0.30..3.00`), and decay on every non-reset mutation.
+- **`sigmap learn`** — manually boost or penalize ranked files with `--good <files...>`, `--bad <files...>`, and `--reset`. Invalid or out-of-repo paths are skipped with warnings; the command exits non-zero when no valid targets remain.
+- **`sigmap weights [--json]`** — explainability view for learned ranking multipliers. Human mode prints a compact table and reset hint; JSON mode emits the raw learned-weight object.
+- **Opt-in judge learning** — `sigmap judge --response <file> --context <file> --learn` now extracts file headings from query/generated context files and applies small boosts or penalties when groundedness is confidently high or low.
+
+### Changed
+
+- **Ranker learned weighting** — `rank(query, sigIndex, { cwd })` now loads `.context/weights.json` and multiplies non-empty-query scores by learned file multipliers. Empty-query fallback ordering is unchanged.
+- **Learning-aware rank call sites** — `sigmap ask`, `sigmap --query`, `sigmap validate --query`, and MCP `query_context` now pass `cwd` into the ranker so learned weights apply consistently across CLI and MCP flows.
+
+## [5.1.0] — 2026-04-16
+
+### Added
+
+- **Benchmark history tracking** — all three benchmark scripts (`run-retrieval-benchmark.mjs`, `run-benchmark.mjs`, `run-task-benchmark.mjs`) now append a structured NDJSON entry to `.context/benchmark-history.ndjson` after each run (`type: "retrieval" | "token-reduction" | "task"`).
+- **`sigmap history` benchmark trend rows** — when `.context/benchmark-history.ndjson` exists, `sigmap history` prints a retrieval `hit@5` sparkline row and a token-reduction sparkline row below the usage table. The command no longer exits early when the usage log is empty.
+- **Dashboard `readBenchmarkTrend` uses local history** — `src/format/dashboard.js` now prefers `.context/benchmark-history.ndjson` over the CI-only `benchmarks/results/` directory, so the dashboard hit@5 trend chart populates for all users after running any benchmark locally.
+
+---
+
 ## [5.0.0] — 2026-04-16
 
 ### Added

package/gen-context.js

@@ -3152,6 +3152,25 @@ __factories["./src/format/cache"] = function(module, exports) {
     }
 
     function readBenchmarkTrend(cwd) {
+      // Prefer per-user history file written by benchmark scripts
+      const histPath = path.join(cwd, '.context', 'benchmark-history.ndjson');
+      if (fs.existsSync(histPath)) {
+        const histValues = [];
+        try {
+          for (const line of fs.readFileSync(histPath, 'utf8').trim().split('\n').filter(Boolean)) {
+            try {
+              const obj = JSON.parse(line);
+              if (obj.type === 'retrieval') {
+                const v = toNumber(obj.hitAt5Pct);
+                if (v !== null) histValues.push(v);
+              }
+            } catch (_) {}
+          }
+        } catch (_) {}
+        if (histValues.length > 0) return histValues.slice(-30);
+      }
+
+      // Fallback: legacy benchmarks/results directory (CI artifacts)
       const resultDir = path.join(cwd, 'benchmarks', 'results');
       if (!fs.existsSync(resultDir)) return [];
       const files = [];
@@ -4665,7 +4684,7 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
       const index = buildSigIndex(cwd);
       if (index.size === 0) return 'No signatures indexed. Run: node gen-context.js';
       const topK = Math.min(Math.max(1, parseInt(args.topK, 10) || 10), 25);
-      const results = rank(args.query, index, { topK });
+      const results = rank(args.query, index, { topK, cwd });
       return formatRankTable(results, args.query);
     } catch (err) {
       return `_query_context failed: ${err.message}_`;
@@ -4687,6 +4706,132 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
   module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
 };
 
+// ── ./src/learning/weights ──
+__factories["./src/learning/weights"] = function(module, exports) {
+  'use strict';
+
+  const fs = require('fs');
+  const path = require('path');
+
+  const DECAY = 0.95;
+  const MAX_MULT = 3.0;
+  const MIN_MULT = 0.30;
+  const BASELINE = 1.0;
+
+  function weightsPath(cwd) {
+    return path.join(cwd, '.context', 'weights.json');
+  }
+
+  function clampMultiplier(value) {
+    if (!Number.isFinite(value)) return BASELINE;
+    if (value > MAX_MULT) return MAX_MULT;
+    if (value < MIN_MULT) return MIN_MULT;
+    return parseFloat(value.toFixed(6));
+  }
+
+  function normalizeFile(cwd, filePath) {
+    if (!cwd || !filePath || typeof filePath !== 'string') return null;
+    const cleaned = filePath.trim().replace(/\\/g, '/');
+    if (!cleaned) return null;
+    const abs = path.resolve(cwd, cleaned);
+    const rel = path.relative(cwd, abs);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+    return rel.split(path.sep).join('/');
+  }
+
+  function sanitizeWeights(cwd, weights) {
+    const out = {};
+    const entries = weights && typeof weights === 'object' ? Object.entries(weights) : [];
+    for (const [filePath, raw] of entries) {
+      const normalized = normalizeFile(cwd, filePath);
+      if (!normalized) continue;
+      const mult = clampMultiplier(Number(raw));
+      if (Math.abs(mult - BASELINE) < 1e-9) continue;
+      out[normalized] = mult;
+    }
+    return out;
+  }
+
+  function loadWeights(cwd) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(weightsPath(cwd), 'utf8'));
+      return sanitizeWeights(cwd, parsed);
+    } catch (_) {
+      return {};
+    }
+  }
+
+  function saveWeights(cwd, weights) {
+    const cleaned = sanitizeWeights(cwd, weights);
+    const outPath = weightsPath(cwd);
+    if (Object.keys(cleaned).length === 0) {
+      try {
+        if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+      } catch (_) {}
+      return;
+    }
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const sorted = Object.keys(cleaned).sort().reduce((acc, key) => {
+      acc[key] = cleaned[key];
+      return acc;
+    }, {});
+    fs.writeFileSync(outPath, JSON.stringify(sorted, null, 2) + '\n', 'utf8');
+  }
+
+  function updateWeights(cwd, opts) {
+    opts = opts || {};
+    const goodAmount = Number.isFinite(opts.goodAmount) ? opts.goodAmount : 0.15;
+    const badAmount = Number.isFinite(opts.badAmount) ? opts.badAmount : 0.10;
+    const goodFiles = Array.isArray(opts.goodFiles) ? opts.goodFiles : [];
+    const badFiles = Array.isArray(opts.badFiles) ? opts.badFiles : [];
+    const weights = loadWeights(cwd);
+
+    for (const key of Object.keys(weights)) {
+      weights[key] = clampMultiplier(weights[key] * DECAY);
+    }
+
+    const good = [];
+    const bad = [];
+
+    for (const filePath of goodFiles) {
+      const normalized = normalizeFile(cwd, filePath);
+      if (!normalized) continue;
+      weights[normalized] = clampMultiplier((weights[normalized] || BASELINE) + goodAmount);
+      good.push(normalized);
+    }
+
+    for (const filePath of badFiles) {
+      const normalized = normalizeFile(cwd, filePath);
+      if (!normalized) continue;
+      weights[normalized] = clampMultiplier((weights[normalized] || BASELINE) - badAmount);
+      bad.push(normalized);
+    }
+
+    saveWeights(cwd, weights);
+    return { good, bad, weights: loadWeights(cwd) };
+  }
+
+  function boostFiles(cwd, files, amount) {
+    return updateWeights(cwd, { goodFiles: files, goodAmount: amount });
+  }
+
+  function penalizeFiles(cwd, files, amount) {
+    return updateWeights(cwd, { badFiles: files, badAmount: amount });
+  }
+
+  function resetWeights(cwd) {
+    const outPath = weightsPath(cwd);
+    if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+  }
+
+  module.exports = {
+    BASELINE, DECAY, MAX_MULT, MIN_MULT,
+    weightsPath, clampMultiplier, normalizeFile,
+    loadWeights, saveWeights, updateWeights,
+    boostFiles, penalizeFiles, resetWeights,
+  };
+};
+
 // ── ./src/mcp/server ──
 __factories["./src/mcp/server"] = function(module, exports) {
   
@@ -4708,7 +4853,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '5.0.0',
+  version: '5.2.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -5310,6 +5455,10 @@ __factories["./src/security/scanner"] = function(module, exports) {
 __factories["./src/judge/judge-engine"] = function(module, exports) {
   'use strict';
 
+  const fs = require('fs');
+  const path = require('path');
+  const { boostFiles, normalizeFile, penalizeFiles } = __require('./src/learning/weights');
+
   const STOP = new Set([
     'the','a','an','in','on','at','to','of','for','and','or','but',
     'is','are','was','were','be','been','being','have','has','had',
@@ -5340,6 +5489,24 @@ __factories["./src/judge/judge-engine"] = function(module, exports) {
     'as a general rule',
   ];
 
+  function extractContextFiles(context, cwd) {
+    if (!context || !cwd) return [];
+    const seen = new Set();
+    const files = [];
+    const lines = context.split('\n');
+    for (const line of lines) {
+      const match = line.match(/^#{2,3}\s+(.+?)\s*$/);
+      if (!match) continue;
+      const normalized = normalizeFile(cwd, match[1]);
+      if (!normalized) continue;
+      const abs = path.join(cwd, normalized);
+      if (!fs.existsSync(abs) || seen.has(normalized)) continue;
+      seen.add(normalized);
+      files.push(normalized);
+    }
+    return files;
+  }
+
   function judge(response, context, opts) {
     opts = opts || {};
     const score = groundedness(response, context);
@@ -5355,7 +5522,37 @@ __factories["./src/judge/judge-engine"] = function(module, exports) {
       }
     }
     const verdict = score >= threshold && reasons.length === 0 ? 'pass' : 'fail';
-    return { score, verdict, reasons };
+    const result = { score, verdict, reasons };
+
+    if (opts.learn) {
+      const learning = { applied: false, action: 'none', files: [] };
+      if (!opts.cwd) {
+        learning.reason = 'cwd is required for learning';
+        result.learning = learning;
+        return result;
+      }
+      const contextFiles = extractContextFiles(context, opts.cwd);
+      learning.files = contextFiles;
+      if (contextFiles.length === 0) {
+        learning.reason = 'no context files found in context headings';
+        result.learning = learning;
+        return result;
+      }
+      if (score > 0.75) {
+        boostFiles(opts.cwd, contextFiles, 0.05);
+        learning.applied = true;
+        learning.action = 'boost';
+      } else if (score < 0.40) {
+        penalizeFiles(opts.cwd, contextFiles, 0.03);
+        learning.applied = true;
+        learning.action = 'penalize';
+      } else {
+        learning.reason = 'groundedness in no-op band (0.40-0.75)';
+      }
+      result.learning = learning;
+    }
+
+    return result;
   }
 
   module.exports = { groundedness, judge };
@@ -5510,6 +5707,7 @@ __factories["./src/retrieval/tokenizer"] = function(module, exports) {
 // ── ./src/retrieval/ranker ──
 __factories["./src/retrieval/ranker"] = function(module, exports) {
   'use strict';
+  const { loadWeights } = __require('./src/learning/weights');
   const { tokenize, STOP_WORDS } = __require('./src/retrieval/tokenizer');
   const DEFAULT_WEIGHTS = {
     exactToken: 1.0, symbolMatch: 0.5, prefixMatch: 0.3, pathMatch: 0.8, recencyBoost: 1.5,
@@ -5542,6 +5740,7 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     const recencyMultiplier = (opts && opts.recencyBoost) || DEFAULT_WEIGHTS.recencyBoost;
     const recencySet = (opts && opts.recencySet) || null;
     const weights = (opts && opts.weights) ? Object.assign({}, DEFAULT_WEIGHTS, opts.weights) : DEFAULT_WEIGHTS;
+    const learnedWeights = opts && opts.cwd ? loadWeights(opts.cwd) : null;
     const queryTokens = tokenize(query);
     if (queryTokens.length === 0) {
       const all = [];
@@ -5553,6 +5752,7 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     for (const [file, sigs] of sigIndex.entries()) {
       let score = scoreFile(file, sigs, queryTokens, weights);
       if (recencySet && recencySet.has(file) && score > 0) score *= recencyMultiplier;
+      if (learnedWeights && score > 0) score *= learnedWeights[file] || 1.0;
       scored.push({ file, score, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
     }
     scored.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
@@ -6371,7 +6571,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '5.0.0';
+const VERSION = '5.2.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -8002,6 +8202,11 @@ Usage:
   ${cmd} --query "<text>"                  Rank files by relevance to a query
   ${cmd} --query "<text>" --json           Ranked results as JSON
   ${cmd} --query "<text>" --top <n>        Limit results to top N files (default 10)
+  ${cmd} learn --good <files...>           Boost files in .context/weights.json
+  ${cmd} learn --bad <files...>            Penalize files in .context/weights.json
+  ${cmd} learn --reset                     Delete learned file weights
+  ${cmd} weights                           Show learned file multipliers
+  ${cmd} weights --json                    Learned weights as JSON
   ${cmd} --impact <file>                   Show every file impacted by changing <file>
   ${cmd} --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
   ${cmd} --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
@@ -8117,6 +8322,38 @@ function extractQuerySymbols(query) {
   return (query.match(/\b[A-Z][a-zA-Z]+|[a-z]+(?:[A-Z][a-z]+)+\b/g) || []);
 }
 
+function collectLearnFiles(args, flag, cwd) {
+  const idx = args.indexOf(flag);
+  if (idx < 0) return { rawCount: 0, files: [], warnings: [] };
+
+  const { normalizeFile } = requireSourceOrBundled('./src/learning/weights');
+  const seen = new Set();
+  const files = [];
+  const warnings = [];
+  let rawCount = 0;
+
+  for (let i = idx + 1; i < args.length; i++) {
+    const value = args[i];
+    if (!value || value.startsWith('--')) break;
+    rawCount++;
+    const normalized = normalizeFile(cwd, value);
+    if (!normalized) {
+      warnings.push(`${value} is outside the repo`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(cwd, normalized))) {
+      warnings.push(`${normalized} does not exist`);
+      continue;
+    }
+    if (!seen.has(normalized)) {
+      seen.add(normalized);
+      files.push(normalized);
+    }
+  }
+
+  return { rawCount, files, warnings };
+}
+
 function main() {
   const args = process.argv.slice(2);
 
@@ -8217,7 +8454,7 @@ function main() {
       process.exit(1);
     }
 
-    const ranked = rank(query, sigIndex, { topK: 5, weights: intentWeights });
+    const ranked = rank(query, sigIndex, { topK: 5, weights: intentWeights, cwd });
     const miniCtx = buildMiniContext(ranked, cwd);
     const outPath = path.join(cwd, '.context', 'query-context.md');
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
@@ -8363,6 +8600,75 @@ function main() {
     process.exit(0);
   }
 
+  // v5.2: `sigmap learn` — manual learning controls for ranking
+  if (args[0] === 'learn') {
+    const doReset = args.includes('--reset');
+    const good = collectLearnFiles(args, '--good', cwd);
+    const bad = collectLearnFiles(args, '--bad', cwd);
+
+    if (doReset && (good.rawCount > 0 || bad.rawCount > 0)) {
+      console.error('[sigmap] --reset cannot be combined with --good or --bad');
+      process.exit(1);
+    }
+
+    if (doReset) {
+      const { resetWeights } = requireSourceOrBundled('./src/learning/weights');
+      resetWeights(cwd);
+      console.log('[sigmap] weights reset — all files back to baseline');
+      process.exit(0);
+    }
+
+    if (good.rawCount === 0 && bad.rawCount === 0) {
+      console.error('[sigmap] Usage: sigmap learn --good <files...> [--bad <files...>] | sigmap learn --reset');
+      process.exit(1);
+    }
+
+    for (const warning of [...good.warnings, ...bad.warnings]) {
+      console.warn(`[sigmap] warning: ${warning}`);
+    }
+
+    if (good.files.length === 0 && bad.files.length === 0) {
+      console.error('[sigmap] No valid files to learn from.');
+      process.exit(1);
+    }
+
+    const { updateWeights } = requireSourceOrBundled('./src/learning/weights');
+    const result = updateWeights(cwd, { goodFiles: good.files, badFiles: bad.files });
+    const parts = [];
+    if (result.good.length) parts.push(`boosted ${result.good.length} file(s)`);
+    if (result.bad.length) parts.push(`penalized ${result.bad.length} file(s)`);
+    console.log(`[sigmap] learned: ${parts.join(', ')}`);
+    process.exit(0);
+  }
+
+  // v5.2: `sigmap weights` — explain learned ranking multipliers
+  if (args[0] === 'weights') {
+    const { loadWeights } = requireSourceOrBundled('./src/learning/weights');
+    const weights = loadWeights(cwd);
+    const entries = Object.entries(weights).sort(([, a], [, b]) => b - a || 0);
+
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify(weights, null, 2) + '\n');
+      process.exit(0);
+    }
+
+    if (entries.length === 0) {
+      console.log('[sigmap] No learned weights yet. Run: sigmap learn --good <file>');
+      process.exit(0);
+    }
+
+    console.log('[sigmap] Learned file weights (xmultiplier vs baseline):');
+    for (const [file, mult] of entries) {
+      const bar = mult >= 1
+        ? `+${'█'.repeat(Math.max(1, Math.round((mult - 1) * 10)))}`
+        : `-${'░'.repeat(Math.max(1, Math.round((1 - mult) * 10)))}`;
+      console.log(`  ${file.padEnd(50)} x${mult.toFixed(2)}  ${bar}`);
+    }
+    console.log(`\n  Total files with learned weights: ${entries.length}`);
+    console.log('  To reset: sigmap learn --reset');
+    process.exit(0);
+  }
+
   // v4.3: `sigmap validate` — config + coverage + optional query symbol check
   if (args[0] === 'validate') {
     const issues   = [];
@@ -8395,7 +8701,7 @@ function main() {
       if (q && !q.startsWith('--')) {
         try {
           const { rank, buildSigIndex } = requireSourceOrBundled('./src/retrieval/ranker');
-          const ranked = rank(q, buildSigIndex(cwd), { topK: 5 });
+          const ranked = rank(q, buildSigIndex(cwd), { topK: 5, cwd });
           const symbols = extractQuerySymbols(q);
           const missing = symbols.filter((sym) =>
             !ranked.some((r) => r.sigs && r.sigs.some((s) => s.toLowerCase().includes(sym.toLowerCase())))
@@ -8428,7 +8734,7 @@ function main() {
     const ctxIdx  = args.indexOf('--context');
 
     if (respIdx < 0 || ctxIdx < 0) {
-      console.error('[sigmap] Usage: sigmap judge --response <file> --context <file> [--json] [--threshold 0.25]');
+      console.error('[sigmap] Usage: sigmap judge --response <file> --context <file> [--json] [--threshold 0.25] [--learn]');
       process.exit(1);
     }
 
@@ -8448,6 +8754,10 @@ function main() {
 
     const thrIdx = args.indexOf('--threshold');
     const judgeOpts = thrIdx >= 0 ? { threshold: parseFloat(args[thrIdx + 1]) || 0.25 } : {};
+    if (args.includes('--learn')) {
+      judgeOpts.learn = true;
+      judgeOpts.cwd = cwd;
+    }
 
     const { judge: runJudge } = requireSourceOrBundled('./src/judge/judge-engine');
     const result = runJudge(responseText, contextText, judgeOpts);
@@ -8462,8 +8772,11 @@ function main() {
         ` Score     : ${result.score}`,
         ` Verdict   : ${result.verdict}`,
         result.reasons.length ? ` Reasons   :\n   ${result.reasons.join('\n   ')}` : ` Reasons   : none`,
+        result.learning
+          ? ` Learning  : ${result.learning.applied ? result.learning.action : 'skipped'}${result.learning.files.length ? ` (${result.learning.files.join(', ')})` : ''}${result.learning.reason ? ` — ${result.learning.reason}` : ''}`
+          : null,
         bar,
-      ].join('\n'));
+      ].filter(Boolean).join('\n'));
     }
     process.exit(result.verdict === 'pass' ? 0 : 1);
   }
@@ -8482,11 +8795,6 @@ function main() {
       process.exit(0);
     }
 
-    if (last.length === 0) {
-      console.log('[sigmap] No history found. Run sigmap to generate entries (enable tracking: true in config).');
-      process.exit(0);
-    }
-
     const SPARK_CHARS = '▁▂▃▄▅▆▇█';
     function sparkline(values) {
       if (values.length === 0) return '';
@@ -8499,25 +8807,48 @@ function main() {
       }).join('');
     }
 
-    const tokens = last.map((e) => e.finalTokens || 0);
-    const spark  = sparkline(tokens);
-
     const bar = '─'.repeat(62);
     console.log(bar);
-    console.log(` sigmap history  (last ${last.length} runs)`);
+    console.log(` sigmap history  (last ${Math.max(last.length, 1)} runs)`);
     console.log(bar);
-    console.log(` ${'Date'.padEnd(24)} ${'Files'.padStart(5)} ${'Tokens'.padStart(7)} ${'Reduction'.padStart(9)} ${'Budget?'.padStart(7)}`);
-    console.log(` ${'─'.repeat(24)} ${'─'.repeat(5)} ${'─'.repeat(7)} ${'─'.repeat(9)} ${'─'.repeat(7)}`);
-    for (const e of last) {
-      const date = (e.ts || '').slice(0, 19).replace('T', ' ');
-      const files = String(e.fileCount || 0).padStart(5);
-      const tok   = String(e.finalTokens || 0).padStart(7);
-      const red   = `${e.reductionPct || 0}%`.padStart(9);
-      const over  = (e.overBudget ? '  ⚠ yes' : '     no').padStart(7);
-      console.log(` ${date.padEnd(24)} ${files} ${tok} ${red} ${over}`);
+
+    if (last.length === 0) {
+      console.log(' No usage log entries. Enable tracking: true in config to start recording runs.');
+    } else {
+      console.log(` ${'Date'.padEnd(24)} ${'Files'.padStart(5)} ${'Tokens'.padStart(7)} ${'Reduction'.padStart(9)} ${'Budget?'.padStart(7)}`);
+      console.log(` ${'─'.repeat(24)} ${'─'.repeat(5)} ${'─'.repeat(7)} ${'─'.repeat(9)} ${'─'.repeat(7)}`);
+      for (const e of last) {
+        const date = (e.ts || '').slice(0, 19).replace('T', ' ');
+        const files = String(e.fileCount || 0).padStart(5);
+        const tok   = String(e.finalTokens || 0).padStart(7);
+        const red   = `${e.reductionPct || 0}%`.padStart(9);
+        const over  = (e.overBudget ? '  ⚠ yes' : '     no').padStart(7);
+        console.log(` ${date.padEnd(24)} ${files} ${tok} ${red} ${over}`);
+      }
+      console.log(bar);
+      const tokens = last.map((e) => e.finalTokens || 0);
+      console.log(` Token trend: ${sparkline(tokens)}`);
+    }
+
+    // Show benchmark trend row if .context/benchmark-history.ndjson exists
+    const benchHistPath = path.join(cwd, '.context', 'benchmark-history.ndjson');
+    if (fs.existsSync(benchHistPath)) {
+      try {
+        const benchEntries = fs.readFileSync(benchHistPath, 'utf8').trim().split('\n')
+          .map((l) => { try { return JSON.parse(l); } catch (_) { return null; } }).filter(Boolean);
+        const retrieval = benchEntries.filter((e) => e.type === 'retrieval').slice(-n);
+        if (retrieval.length > 0) {
+          const hits = retrieval.map((e) => e.hitAt5Pct || 0);
+          console.log(` hit@5 trend: ${sparkline(hits)}  ${hits.at(-1)}% (latest)`);
+        }
+        const tokenBench = benchEntries.filter((e) => e.type === 'token-reduction').slice(-n);
+        if (tokenBench.length > 0) {
+          const reds = tokenBench.map((e) => e.reduction || e.avgReductionPct || 0);
+          console.log(` tok reduce : ${sparkline(reds)}  ${reds.at(-1)}% (latest)`);
+        }
+      } catch (_) {}
     }
-    console.log(bar);
-    console.log(` Token trend: ${spark}`);
+
     console.log(bar);
     process.exit(0);
   }
@@ -8972,7 +9303,7 @@ function main() {
       const topK = topIdx >= 0 ? Math.min(Math.max(1, parseInt(args[topIdx + 1], 10) || 10), 25)
                                : ((config && config.retrieval && config.retrieval.topK) || 10);
       const recencyBoost = (config && config.retrieval && config.retrieval.recencyBoost) || 1.5;
-      const results = rank(query, index, { topK, recencyBoost });
+      const results = rank(query, index, { topK, recencyBoost, cwd });
       if (args.includes('--context')) {
         const miniCtx  = buildMiniContext(results, cwd);
         const ctxOut   = path.join(cwd, '.context', 'query-context.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/README.md

@@ -71,6 +71,7 @@ Rank all files in a signature index against a natural-language query.
 | `opts.topK` | `number` | Max files to return (default: `10`) |
 | `opts.weights` | `object` | Override default scoring weights |
 | `opts.recencySet` | `Set<string>` | Files to boost with `recencyBoost` multiplier |
+| `opts.cwd` | `string` | Project root used to load learned ranking weights from `.context/weights.json` |
 
 Each result: `{ file: string, score: number, sigs: string[], tokens: number }`
 

package/packages/core/index.js

@@ -130,6 +130,7 @@ function extract(src, language) {
  * @param {number} [opts.recencyBoost]   - Score multiplier for recent files
  * @param {Set<string>} [opts.recencySet] - Set of file paths considered recent
  * @param {object} [opts.weights]        - Override default scoring weights
+ * @param {string} [opts.cwd]            - Project root for learned ranking weights
  * @returns {{ file: string, score: number, sigs: string[], tokens: number }[]}
  *
  * @example

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/format/dashboard.js

@@ -140,6 +140,26 @@ function computeExtractorCoverage(cwd) {
 }
 
 function readBenchmarkTrend(cwd) {
+  // Prefer per-user history file written by benchmark scripts
+  const histPath = path.join(cwd, '.context', 'benchmark-history.ndjson');
+  if (fs.existsSync(histPath)) {
+    const values = [];
+    try {
+      const lines = fs.readFileSync(histPath, 'utf8').trim().split('\n').filter(Boolean);
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line);
+          if (obj.type === 'retrieval') {
+            const v = toNumber(obj.hitAt5Pct);
+            if (v !== null) values.push(v);
+          }
+        } catch (_) {}
+      }
+    } catch (_) {}
+    if (values.length > 0) return values.slice(-30);
+  }
+
+  // Fallback: legacy benchmarks/results directory (CI artifacts)
   const resultDir = path.join(cwd, 'benchmarks', 'results');
   if (!fs.existsSync(resultDir)) return [];
 

package/src/judge/judge-engine.js

@@ -1,5 +1,9 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
+const { boostFiles, normalizeFile, penalizeFiles } = require('../learning/weights');
+
 const STOP = new Set([
   'the','a','an','in','on','at','to','of','for','and','or','but',
   'is','are','was','were','be','been','being','have','has','had',
@@ -30,6 +34,30 @@ const GENERIC_MARKERS = [
   'as a general rule',
 ];
 
+function extractContextFiles(context, cwd) {
+  if (!context || !cwd) return [];
+
+  const seen = new Set();
+  const files = [];
+  const lines = context.split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/^#{2,3}\s+(.+?)\s*$/);
+    if (!match) continue;
+
+    const normalized = normalizeFile(cwd, match[1]);
+    if (!normalized) continue;
+
+    const abs = path.join(cwd, normalized);
+    if (!fs.existsSync(abs) || seen.has(normalized)) continue;
+
+    seen.add(normalized);
+    files.push(normalized);
+  }
+
+  return files;
+}
+
 function judge(response, context, opts = {}) {
   const score = groundedness(response, context);
   const threshold = opts.threshold !== undefined ? opts.threshold : 0.25;
@@ -49,7 +77,46 @@ function judge(response, context, opts = {}) {
   }
 
   const verdict = score >= threshold && reasons.length === 0 ? 'pass' : 'fail';
-  return { score, verdict, reasons };
+  const result = { score, verdict, reasons };
+
+  if (opts.learn) {
+    const learning = {
+      applied: false,
+      action: 'none',
+      files: [],
+    };
+
+    if (!opts.cwd) {
+      learning.reason = 'cwd is required for learning';
+      result.learning = learning;
+      return result;
+    }
+
+    const contextFiles = extractContextFiles(context, opts.cwd);
+    learning.files = contextFiles;
+
+    if (contextFiles.length === 0) {
+      learning.reason = 'no context files found in context headings';
+      result.learning = learning;
+      return result;
+    }
+
+    if (score > 0.75) {
+      boostFiles(opts.cwd, contextFiles, 0.05);
+      learning.applied = true;
+      learning.action = 'boost';
+    } else if (score < 0.40) {
+      penalizeFiles(opts.cwd, contextFiles, 0.03);
+      learning.applied = true;
+      learning.action = 'penalize';
+    } else {
+      learning.reason = 'groundedness in no-op band (0.40-0.75)';
+    }
+
+    result.learning = learning;
+  }
+
+  return result;
 }
 
 module.exports = { groundedness, judge };

package/src/learning/weights.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DECAY = 0.95;
+const MAX_MULT = 3.0;
+const MIN_MULT = 0.30;
+const BASELINE = 1.0;
+
+function weightsPath(cwd) {
+  return path.join(cwd, '.context', 'weights.json');
+}
+
+function clampMultiplier(value) {
+  if (!Number.isFinite(value)) return BASELINE;
+  if (value > MAX_MULT) return MAX_MULT;
+  if (value < MIN_MULT) return MIN_MULT;
+  return parseFloat(value.toFixed(6));
+}
+
+function normalizeFile(cwd, filePath) {
+  if (!cwd || !filePath || typeof filePath !== 'string') return null;
+  const cleaned = filePath.trim().replace(/\\/g, '/');
+  if (!cleaned) return null;
+
+  const abs = path.resolve(cwd, cleaned);
+  const rel = path.relative(cwd, abs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join('/');
+}
+
+function sanitizeWeights(cwd, weights) {
+  const out = {};
+  const entries = weights && typeof weights === 'object' ? Object.entries(weights) : [];
+
+  for (const [filePath, raw] of entries) {
+    const normalized = normalizeFile(cwd, filePath);
+    if (!normalized) continue;
+    const mult = clampMultiplier(Number(raw));
+    if (Math.abs(mult - BASELINE) < 1e-9) continue;
+    out[normalized] = mult;
+  }
+
+  return out;
+}
+
+function loadWeights(cwd) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(weightsPath(cwd), 'utf8'));
+    return sanitizeWeights(cwd, parsed);
+  } catch (_) {
+    return {};
+  }
+}
+
+function saveWeights(cwd, weights) {
+  const cleaned = sanitizeWeights(cwd, weights);
+  const outPath = weightsPath(cwd);
+
+  if (Object.keys(cleaned).length === 0) {
+    try {
+      if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+    } catch (_) {}
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  const sorted = Object.keys(cleaned)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = cleaned[key];
+      return acc;
+    }, {});
+  fs.writeFileSync(outPath, JSON.stringify(sorted, null, 2) + '\n', 'utf8');
+}
+
+function updateWeights(cwd, opts = {}) {
+  const goodAmount = Number.isFinite(opts.goodAmount) ? opts.goodAmount : 0.15;
+  const badAmount = Number.isFinite(opts.badAmount) ? opts.badAmount : 0.10;
+  const goodFiles = Array.isArray(opts.goodFiles) ? opts.goodFiles : [];
+  const badFiles = Array.isArray(opts.badFiles) ? opts.badFiles : [];
+
+  const weights = loadWeights(cwd);
+
+  for (const key of Object.keys(weights)) {
+    weights[key] = clampMultiplier(weights[key] * DECAY);
+  }
+
+  const good = [];
+  const bad = [];
+
+  for (const filePath of goodFiles) {
+    const normalized = normalizeFile(cwd, filePath);
+    if (!normalized) continue;
+    weights[normalized] = clampMultiplier((weights[normalized] || BASELINE) + goodAmount);
+    good.push(normalized);
+  }
+
+  for (const filePath of badFiles) {
+    const normalized = normalizeFile(cwd, filePath);
+    if (!normalized) continue;
+    weights[normalized] = clampMultiplier((weights[normalized] || BASELINE) - badAmount);
+    bad.push(normalized);
+  }
+
+  saveWeights(cwd, weights);
+  return { good, bad, weights: loadWeights(cwd) };
+}
+
+function boostFiles(cwd, files, amount = 0.15) {
+  return updateWeights(cwd, { goodFiles: files, goodAmount: amount });
+}
+
+function penalizeFiles(cwd, files, amount = 0.10) {
+  return updateWeights(cwd, { badFiles: files, badAmount: amount });
+}
+
+function resetWeights(cwd) {
+  const outPath = weightsPath(cwd);
+  if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+}
+
+module.exports = {
+  BASELINE,
+  DECAY,
+  MAX_MULT,
+  MIN_MULT,
+  weightsPath,
+  clampMultiplier,
+  normalizeFile,
+  loadWeights,
+  saveWeights,
+  updateWeights,
+  boostFiles,
+  penalizeFiles,
+  resetWeights,
+};

package/src/mcp/handlers.js

@@ -450,7 +450,7 @@ function queryContext(args, cwd) {
     if (index.size === 0) return 'No signatures indexed. Run: node gen-context.js';
 
     const topK = Math.min(Math.max(1, parseInt(args.topK, 10) || 10), 25);
-    const results = rank(args.query, index, { topK });
+    const results = rank(args.query, index, { topK, cwd });
     return formatRankTable(results, args.query);
   } catch (err) {
     return `_query_context failed: ${err.message}_`;
@@ -477,4 +477,4 @@ function getImpact(args, cwd) {
   }
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '5.0.0',
+  version: '5.2.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/retrieval/ranker.js

@@ -17,6 +17,7 @@
  *   // results: [{ file, score, sigs, tokens }]
  */
 
+const { loadWeights } = require('../learning/weights');
 const { tokenize, STOP_WORDS } = require('./tokenizer');
 
 // ---------------------------------------------------------------------------
@@ -97,6 +98,7 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
  * @param {number}  [opts.recencyBoost=1.5]       - multiplier for recent files
  * @param {Set<string>} [opts.recencySet]         - set of recently-changed file paths
  * @param {object}  [opts.weights]               - override scoring weights
+ * @param {string}  [opts.cwd]                   - project root for learned ranking weights
  * @returns {{ file: string, score: number, sigs: string[], tokens: number }[]}
  */
 function rank(query, sigIndex, opts) {
@@ -107,6 +109,7 @@ function rank(query, sigIndex, opts) {
   const recencyMultiplier = (opts && opts.recencyBoost) || DEFAULT_WEIGHTS.recencyBoost;
   const recencySet = (opts && opts.recencySet) || null;
   const weights = (opts && opts.weights) ? Object.assign({}, DEFAULT_WEIGHTS, opts.weights) : DEFAULT_WEIGHTS;
+  const learnedWeights = opts && opts.cwd ? loadWeights(opts.cwd) : null;
 
   const queryTokens = tokenize(query);
   if (queryTokens.length === 0) {
@@ -128,6 +131,10 @@ function rank(query, sigIndex, opts) {
       score *= recencyMultiplier;
     }
 
+    if (learnedWeights && score > 0) {
+      score *= learnedWeights[file] || 1.0;
+    }
+
     scored.push({
       file,
       score,