sigmap 6.11.0 → 6.12.0

package/CHANGELOG.md

@@ -10,6 +10,32 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [6.12.0] — 2026-06-05
+
+### Added
+
+- **Surgical Context Phase 2 — demand-driven retrieval (#219, PR #220):**
+  - **`get_lines` MCP tool** (10th tool) — fetch an exact `{ file, start, end }` line range on demand. Lines are clamped to the file bounds, secret-scanned via the existing redactor, and sandboxed to the project root. This is the demand-driven workhorse: agents read the lines behind a `:start-end` anchor instead of re-opening whole files.
+  - **`sigmap ask --mode index`** — two-tier output that emits only symbol-header pointers (`symbol  :start-end`), dropping parameter lists, return types, and bodies. Agents re-fetch bodies via `get_lines`.
+  - **`sigmap ask --since <ref>`** — delta context that restricts ranked output to files changed since a git ref.
+- **Token Reduction dashboard panel (Surface A)** — `sigmap --report` now renders a "Token Reduction" panel (whole-file baseline vs ranked signatures vs surgical, with per-repo rows), sourced from `benchmarks/reports/token-reduction.json` — numbers are never hand-typed.
+- New **Surgical Context** guide (`docs-vp/guide/surgical-context.md`) covering line anchors, `--mode index`, `--since`, and the `get_lines` MCP tool.
+
+### Changed
+
+- **Budget-aware progressive disclosure** — when generated context exceeds `maxTokens`, the token budget now collapses signature bodies to their line anchors (keeping `symbol  :start-end`) *before* dropping whole files, degrading gracefully.
+- **CI** — added `workflow_dispatch` to the develop→main sync workflow so it can be run on demand (PR #218).
+
+---
+
+## [6.11.1] — 2026-06-04
+
+### Fixed
+
+- **MCP hot-cold cold signatures in bundled server** — the bundled MCP server now includes the hot-cold "cold" signatures, so context lookups return complete results under the hot-cold strategy (closes #201, PR #216). Thanks @rudi193-cmd.
+
+---
+
 ## [6.11.0] — 2026-06-03
 
 ### Added

package/README.md

@@ -47,10 +47,10 @@ SigMap extracts function and class signatures from your codebase and feeds the r
 
 ## Why SigMap?
 
-- **78.9% hit@5** — right file found in top 5 results (vs 13.6% baseline)
-- **97.9% token reduction** — 278K instead of 13.5M tokens across 21 repos
-- **52.2% task success rate** — up from 10% without context
-- **1.66 prompts per task** — down from 2.84 (40.6% fewer retries)
+- **81.1% hit@5** — right file found in top 5 results (vs 13.6% baseline)
+- **96.5% token reduction** — average across 21 real repos
+- **53.3% task success rate** — up from 10% without context
+- **1.66 prompts per task** — down from 2.84 (41.8% fewer retries)
 - **31 languages supported** — TypeScript, Python, Go, Rust, Java, R, and 25 others
 - **No vendor lock-in** — works with any AI assistant or local LLM
 - **No API costs** — use local models (Ollama, llama.cpp, vLLM) with zero token fees
@@ -63,7 +63,7 @@ SigMap extracts function and class signatures from your codebase and feeds the r
 
 | Without SigMap | With SigMap |
 |---|---|
-| ❌ Guessing which files are relevant | ✅ Right file in context — 80% of the time |
+| ❌ Guessing which files are relevant | ✅ Right file in context — 81% of the time |
 | ❌ Sending the full repo to your AI | ✅ Minimal context — only what matters |
 | ❌ Embeddings / vector DB required | ✅ Grounded answers, no infra needed |
 
@@ -87,12 +87,12 @@ Ask → Rank → Context → Validate → Judge → Learn
 ## Benchmark
 
 ```
-Benchmark : sigmap-v6.10-main (21 repositories, including R language)
-Date      : 2026-05-22
+Benchmark : sigmap-v6.12-main (21 repositories, including R language)
+Date      : 2026-06-05
 
-Hit@5          : 80%   (baseline 13.6%  — 5.9× lift)
+Hit@5          : 81.1%   (baseline 13.6%  — 6.0× lift)
 Token reduction: 96.5%   (across 21 repos)
-Prompt reduction : 41.4% (2.84 → 1.67 prompts per task)
+Prompt reduction : 41.8% (2.84 → 1.66 prompts per task)
 Task success   : 53.3%   (baseline 10%)
 Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
 ```
@@ -183,7 +183,7 @@ Use SigMap with open-source tools and fully self-hosted setups:
 | **JetBrains** | [Marketplace](https://plugins.jetbrains.com/plugin/31109-sigmap--ai-context-engine/) | [github.com/manojmallick/sigmap-jetbrains](https://github.com/manojmallick/sigmap-jetbrains) | IntelliJ IDEA, WebStorm, PyCharm, GoLand — tool window + actions |
 | **Neovim** | lazy.nvim / packer / vim-plug | [github.com/manojmallick/sigmap.nvim](https://github.com/manojmallick/sigmap.nvim) | `:SigMap`, `:SigMapQuery` float window, statusline widget |
 
-**MCP server** — 9 on-demand tools for Claude Code and Cursor:
+**MCP server** — 10 on-demand tools for Claude Code and Cursor:
 
 ```bash
 sigmap --mcp

package/gen-context.js

@@ -1174,6 +1174,30 @@ __factories["./src/extractors/php"] = function(module, exports) {
   
 };
 
+// ── ./src/extractors/line-anchor ──
+__factories["./src/extractors/line-anchor"] = function(module, exports) {
+
+  function lineAt(src, idx) {
+    let line = 1;
+    const end = Math.min(idx, src.length);
+    for (let i = 0; i < end; i++) {
+      if (src.charCodeAt(i) === 10) line++;
+    }
+    return line;
+  }
+
+  function anchor(start, end) {
+    return `  :${start}-${end}`;
+  }
+
+  function withAnchor(sig, start, end) {
+    return `${sig}${anchor(start, end)}`;
+  }
+
+  module.exports = { lineAt, anchor, withAnchor };
+
+};
+
 // ── ./src/extractors/python ──
 __factories["./src/extractors/python"] = function(module, exports) {
   
@@ -4028,6 +4052,96 @@ __factories["./src/format/benchmark-report"] = function(module, exports) {
       }).join('');
     }
 
+    function escapeAttr(s) {
+      return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+      ));
+    }
+
+    function readTokenReduction(cwd) {
+      const p = path.join(cwd, 'benchmarks', 'reports', 'token-reduction.json');
+      let data;
+      try { data = JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+      const repos = Array.isArray(data.repos) ? data.repos : [];
+      if (repos.length === 0) return null;
+      let baseline = 0, signatures = 0, surgical = 0, hasSurgical = false;
+      for (const r of repos) {
+        baseline += toNumber(r.rawTokens) || 0;
+        signatures += toNumber(r.finalTokens) || 0;
+        const s = toNumber(r.surgicalTokens);
+        if (s !== null) { surgical += s; hasSurgical = true; }
+      }
+      const out = {
+        version: data.version || null,
+        repoCount: repos.length,
+        baseline,
+        signatures,
+        savedPct: baseline > 0 ? Math.round((1 - signatures / baseline) * 1000) / 10 : 0,
+        perRepo: repos.map((r) => ({
+          repo: r.repo, language: r.language,
+          rawTokens: toNumber(r.rawTokens) || 0,
+          finalTokens: toNumber(r.finalTokens) || 0,
+          reductionPct: toNumber(r.reductionPct) || 0,
+        })),
+      };
+      if (hasSurgical) {
+        out.surgical = surgical;
+        out.surgicalSavedPct = baseline > 0 ? Math.round((1 - surgical / baseline) * 1000) / 10 : 0;
+      }
+      return out;
+    }
+
+    function tokenReductionPanelHtml(tr) {
+      if (!tr) {
+        return '<div class="panel"><div class="label">Token Reduction</div>' +
+          '<div class="value" style="font-size:13px">No token-reduction benchmark found — run the token benchmark to populate this panel.</div></div>';
+      }
+      const fmt = (n) => Number(n).toLocaleString('en-US');
+      const tiers = [
+        { label: 'Whole-file baseline', value: fmt(tr.baseline) + ' tok' },
+        { label: 'Ranked signatures (ask)', value: fmt(tr.signatures) + ' tok' },
+      ];
+      if (tr.surgical != null) {
+        tiers.push({ label: 'Surgical (index + delta)', value: fmt(tr.surgical) + ' tok' });
+        tiers.push({ label: 'Saved (surgical)', value: tr.surgicalSavedPct + '%' });
+      } else {
+        tiers.push({ label: 'Saved', value: tr.savedPct + '%' });
+      }
+      const tierHtml = tiers.map((t) =>
+        `<div class="card"><div class="label">${escapeAttr(t.label)}</div><div class="value">${escapeAttr(t.value)}</div></div>`
+      ).join('');
+      const sigPct = tr.baseline > 0 ? Math.max(0.4, (tr.signatures / tr.baseline) * 100) : 0;
+      const surgPct = (tr.surgical != null && tr.baseline > 0) ? Math.max(0.4, (tr.surgical / tr.baseline) * 100) : null;
+      const barRow = (label, pct, color) =>
+        `<div style="margin:4px 0;font-size:11px;color:#8ea0d9">${escapeAttr(label)}</div>` +
+        `<div style="background:#0a0f1e;border:1px solid #223056;border-radius:6px;height:14px;overflow:hidden">` +
+        `<div style="width:${pct.toFixed(1)}%;height:100%;background:${color}"></div></div>`;
+      const bars = [
+        barRow('Whole-file baseline (100%)', 100, '#3a4a78'),
+        barRow(`Ranked signatures — ${tr.savedPct}% saved`, sigPct, '#2e7d6b'),
+        surgPct != null ? barRow(`Surgical — ${tr.surgicalSavedPct}% saved`, surgPct, '#5ad1a8') : '',
+      ].filter(Boolean).join('');
+      const rows = tr.perRepo.slice(0, 8).map((r) =>
+        `<tr><td>${escapeAttr(r.repo)}</td><td>${escapeAttr(r.language)}</td>` +
+        `<td style="text-align:right">${fmt(r.rawTokens)}</td>` +
+        `<td style="text-align:right">${fmt(r.finalTokens)}</td>` +
+        `<td style="text-align:right">${r.reductionPct}%</td></tr>`
+      ).join('');
+      return [
+        '<div class="panel">',
+        `<div class="label">Token Reduction — ${tr.repoCount} benchmark repos${tr.version ? ' · v' + escapeAttr(tr.version) : ''}</div>`,
+        `<div class="grid" style="margin:8px 0">${tierHtml}</div>`,
+        bars,
+        '<table style="width:100%;border-collapse:collapse;margin-top:10px;font-size:12px">',
+        '<thead><tr style="color:#8ea0d9;text-align:left">',
+        '<th>Repo</th><th>Lang</th><th style="text-align:right">Baseline</th><th style="text-align:right">Signatures</th><th style="text-align:right">Saved</th>',
+        '</tr></thead>',
+        `<tbody>${rows}</tbody>`,
+        '</table>',
+        '</div>',
+      ].join('');
+    }
+
     function buildDashboardData(cwd, health) {
       const entries = readLog(cwd);
       const recent = entries.slice(-30);
@@ -4046,15 +4160,18 @@ __factories["./src/format/benchmark-report"] = function(module, exports) {
         overBudgetStreak: overBudgetStreak(entries),
         extractorCoverage: coverage.pct,
       };
+      const tokenReduction = readTokenReduction(cwd);
       return {
         summary,
         tokenReductionTrend,
         hitAt5Trend,
         coverage,
+        tokenReduction,
         charts: {
           tokenReductionSvg: lineChartSvg(tokenReductionTrend, 'Token reduction trend (last 30 tracked runs)', '%'),
           hitAt5Svg: lineChartSvg(hitAt5Trend, 'hit@5 trend (last 30 benchmark runs)', ''),
           coverageSvg: barChartSvg(coverage.perLanguage),
+          tokenSavingsPanel: tokenReductionPanelHtml(tokenReduction),
         },
       };
     }
@@ -4088,6 +4205,7 @@ __factories["./src/format/benchmark-report"] = function(module, exports) {
         '<h1>SigMap v2.10 dashboard</h1>',
         '<div class="sub">Self-contained report. No external scripts, styles, or network calls.</div>',
         `<div class="grid">${cardHtml}</div>`,
+        data.charts.tokenSavingsPanel,
         `<div class="panel">${data.charts.tokenReductionSvg}</div>`,
         `<div class="panel">${data.charts.hitAt5Svg}</div>`,
         `<div class="panel">${data.charts.coverageSvg}</div>`,
@@ -5339,42 +5457,29 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
    */
   function searchSignatures(args, cwd) {
     if (!args || !args.query) return 'Missing required argument: query';
-  
-    const contextPath = path.join(cwd, CONTEXT_FILE);
-    if (!fs.existsSync(contextPath)) {
-      return 'No context file found. Run: node gen-context.js';
-    }
-  
-    const content = fs.readFileSync(contextPath, 'utf8');
     const query = args.query.toLowerCase();
-    const lines = content.split('\n');
-  
-    const result = [];
-    let currentFile = '';
-    let fileHeaderAdded = false;
-  
-    for (const line of lines) {
-      if (line.startsWith('### ')) {
-        currentFile = line.slice(4).trim();
-        fileHeaderAdded = false;
-        continue;
-      }
-      // Skip markdown fences and top-level headers
-      if (line.startsWith('```') || line.startsWith('## ') || line.startsWith('# ') || line.startsWith('<!--')) {
-        continue;
+
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) {
+        return 'No context file found. Run: node gen-context.js';
       }
-      if (line.toLowerCase().includes(query)) {
-        if (currentFile && !fileHeaderAdded) {
-          if (result.length > 0) result.push('');
-          result.push(`### ${currentFile}`);
-          fileHeaderAdded = true;
-        }
-        result.push(line);
+
+      const result = [];
+      for (const [file, sigs] of index.entries()) {
+        const hits = sigs.filter((s) => s.toLowerCase().includes(query));
+        if (hits.length === 0) continue;
+        if (result.length > 0) result.push('');
+        result.push(`### ${file}`);
+        result.push(...hits);
       }
+
+      if (result.length === 0) return `No signatures found matching: ${args.query}`;
+      return result.join('\n');
+    } catch (err) {
+      return `_search_signatures failed: ${err.message}_`;
     }
-  
-    if (result.length === 0) return `No signatures found matching: ${args.query}`;
-    return result.join('\n');
   }
   
   /**
@@ -5640,56 +5745,44 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
   }
   
   function listModules(args, cwd) {
-    const contextPath = path.join(cwd, CONTEXT_FILE);
-    if (!fs.existsSync(contextPath)) {
-      return 'No context file found. Run: node gen-context.js';
-    }
-  
-    const content = fs.readFileSync(contextPath, 'utf8');
-    const ctxLines = content.split('\n');
-    const groups = {};
-    let currentGroup = null;
-    let blockBuf = [];
-  
-    function flushBlock() {
-      if (currentGroup === null || blockBuf.length === 0) return;
-      if (!groups[currentGroup]) groups[currentGroup] = { fileCount: 0, tokenCount: 0 };
-      groups[currentGroup].fileCount++;
-      groups[currentGroup].tokenCount += Math.ceil(blockBuf.join('\n').length / 4);
-      blockBuf = [];
-    }
-  
-    for (const line of ctxLines) {
-      if (line.startsWith('### ')) {
-        flushBlock();
-        const rel = line.slice(4).trim().replace(/\\/g, '/');
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) {
+        return 'No context file found. Run: node gen-context.js';
+      }
+
+      const groups = {};
+      for (const [rel, sigs] of index.entries()) {
         const parts = rel.split('/');
-        currentGroup = parts.length > 1 ? parts[0] : '.';
-      } else if (currentGroup !== null) {
-        blockBuf.push(line);
+        const mod = parts.length > 1 ? parts[0] : '.';
+        if (!groups[mod]) groups[mod] = { fileCount: 0, tokenCount: 0 };
+        groups[mod].fileCount++;
+        groups[mod].tokenCount += Math.ceil(sigs.join('\n').length / 4);
       }
+
+      const sorted = Object.entries(groups)
+        .map(([mod, data]) => ({ module: mod, fileCount: data.fileCount, tokenCount: data.tokenCount }))
+        .sort((a, b) => b.tokenCount - a.tokenCount);
+
+      if (sorted.length === 0) return 'No modules found in context file.';
+
+      const total = sorted.reduce((s, m) => s + m.tokenCount, 0);
+
+      return [
+        '# Modules',
+        '',
+        '| Module | Files | Tokens |',
+        '|--------|-------|--------|',
+        ...sorted.map((m) => `| ${m.module} | ${m.fileCount} | ~${m.tokenCount} |`),
+        '',
+        `**Total context tokens: ~${total}**`,
+        '',
+        '_Use `read_context({ module: "name" })` to get signatures for a specific module._',
+      ].join('\n');
+    } catch (err) {
+      return `_list_modules failed: ${err.message}_`;
     }
-    flushBlock();
-  
-    const sorted = Object.entries(groups)
-      .map(([mod, data]) => ({ module: mod, fileCount: data.fileCount, tokenCount: data.tokenCount }))
-      .sort((a, b) => b.tokenCount - a.tokenCount);
-  
-    if (sorted.length === 0) return 'No modules found in context file.';
-  
-    const total = sorted.reduce((s, m) => s + m.tokenCount, 0);
-  
-    return [
-      '# Modules',
-      '',
-      '| Module | Files | Tokens |',
-      '|--------|-------|--------|',
-      ...sorted.map((m) => `| ${m.module} | ${m.fileCount} | ~${m.tokenCount} |`),
-      '',
-      `**Total context tokens: ~${total}**`,
-      '',
-      '_Use `read_context({ module: "name" })` to get signatures for a specific module._',
-    ].join('\n');
   }
   
   function queryContext(args, cwd) {
@@ -5720,7 +5813,56 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     }
   }
 
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
+  function getLines(args, cwd) {
+    if (!args || !args.file) return 'Missing required argument: file';
+
+    const rel = String(args.file).replace(/\\/g, '/').replace(/^\//, '');
+    const abs = path.resolve(cwd, rel);
+
+    // Sandbox: refuse paths that resolve outside the project root.
+    const root = path.resolve(cwd);
+    if (abs !== root && !abs.startsWith(root + path.sep)) {
+      return `Refused: ${rel} resolves outside the project root`;
+    }
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      return `File not found: ${rel}`;
+    }
+
+    const start = parseInt(args.start, 10);
+    const end = parseInt(args.end, 10);
+    if (!Number.isFinite(start) || !Number.isFinite(end)) {
+      return 'Arguments "start" and "end" must be numbers (1-based line numbers).';
+    }
+
+    let lines;
+    try {
+      lines = fs.readFileSync(abs, 'utf8').split('\n');
+    } catch (err) {
+      return `Could not read ${rel}: ${err.message}`;
+    }
+
+    const total = lines.length;
+    const from = Math.max(1, Math.min(start, end));
+    const to = Math.min(total, Math.max(start, end));
+    if (from > total) return `${rel} has only ${total} lines; requested ${start}-${end}`;
+
+    const slice = lines.slice(from - 1, to);
+
+    let safeLines = slice;
+    try {
+      const { scan } = __require('./src/security/scanner');
+      safeLines = scan(slice, rel).safe;
+    } catch (_) {}
+
+    return [
+      `# ${rel}:${from}-${to}`,
+      '```',
+      ...safeLines,
+      '```',
+    ].join('\n');
+  }
+
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines };
 };
 
 // ── ./src/learning/weights ──
@@ -5891,17 +6033,17 @@ __factories["./src/mcp/server"] = function(module, exports) {
    *
    * Supported methods:
    *   initialize        → serverInfo + capabilities
-   *   tools/list        → 3 tool definitions
+   *   tools/list        → 10 tool definitions
    *   tools/call        → dispatch to handler, return result
    */
-  
+
   const readline = require('readline');
   const { TOOLS } = __require('./src/mcp/tools');
-  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact } = __require('./src/mcp/handlers');
-  
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines } = __require('./src/mcp/handlers');
+
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '6.11.0',
+  version: '6.12.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -5958,6 +6100,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
         else if (name === 'list_modules') text = listModules(args, cwd);
         else if (name === 'query_context') text = queryContext(args, cwd);
         else if (name === 'get_impact') text = getImpact(args, cwd);
+        else if (name === 'get_lines') text = getLines(args, cwd);
         else {
           respondError(id, -32601, `Unknown tool: ${name}`);
           return;
@@ -6185,8 +6328,36 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         required: ['file'],
       },
     },
+    {
+      name: 'get_lines',
+      description:
+        'Fetch an exact line range from a source file on demand — the Surgical Context ' +
+        'workhorse. Signatures carry `path:start-end` anchors; call this to read just those ' +
+        'lines instead of re-opening the whole file. Lines are clamped to the file bounds and ' +
+        'secret-scanned (redacted) before return. Path is sandboxed to the project root.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description:
+              'Relative path from the project root (e.g. "src/config/loader.js"). ' +
+              'Use the path shown in a signature anchor. Use forward slashes.',
+          },
+          start: {
+            type: 'number',
+            description: '1-based start line (inclusive). Clamped to the file bounds.',
+          },
+          end: {
+            type: 'number',
+            description: '1-based end line (inclusive). Clamped to the file bounds.',
+          },
+        },
+        required: ['file', 'start', 'end'],
+      },
+    },
   ];
-  
+
   module.exports = { TOOLS };
   
 };
@@ -6968,9 +7139,50 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     if (currentFile !== null) index.set(currentFile, sigs);
     return index;
   }
+
+  function _mergeSigIndex(target, source) {
+    for (const [file, sigs] of source.entries()) {
+      if (!sigs || sigs.length === 0) continue;
+      if (!target.has(file) || target.get(file).length < sigs.length) {
+        target.set(file, sigs);
+      }
+    }
+    return target;
+  }
+
+  function _buildSigIndexFromCache(cwd) {
+    const fs = require('fs');
+    const path = require('path');
+    const index = new Map();
+    try {
+      const { loadCache } = require('../cache/sig-cache');
+      const pkgPath = path.join(cwd, 'package.json');
+      let version = '0.0.0';
+      if (fs.existsSync(pkgPath)) {
+        version = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version || version;
+      }
+      const cache = loadCache(cwd, version);
+      for (const [absPath, entry] of cache.entries()) {
+        if (!entry || !entry.sigs || entry.sigs.length === 0) continue;
+        const rel = path.relative(cwd, absPath).replace(/\\/g, '/');
+        if (!rel || rel.startsWith('..')) continue;
+        index.set(rel, entry.sigs);
+      }
+    } catch (_) {}
+    return index;
+  }
+
+  function _enrichSigIndexFromStrategy(cwd, index) {
+    const path = require('path');
+    const coldPath = path.join(cwd, '.github', 'context-cold.md');
+    _mergeSigIndex(index, _parseContextFile(coldPath));
+    _mergeSigIndex(index, _buildSigIndexFromCache(cwd));
+    return index;
+  }
+
   function buildSigIndex(cwd, opts) {
     const fs = require('fs'); const path = require('path');
-    if (opts && opts.contextPath) return _parseContextFile(opts.contextPath);
+    if (opts && opts.contextPath) return _enrichSigIndexFromStrategy(cwd, _parseContextFile(opts.contextPath));
     // Check gen-context.config.json for a persisted customOutput path.
     try {
       const cfgPath = path.join(cwd, 'gen-context.config.json');
@@ -6978,16 +7190,16 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
         const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
         if (cfg.customOutput) {
           const idx = _parseContextFile(path.resolve(cwd, cfg.customOutput));
-          if (idx.size > 0) return idx;
+          if (idx.size > 0) return _enrichSigIndexFromStrategy(cwd, idx);
         }
       }
     } catch (_) {}
     for (const parts of ADAPTER_OUTPUT_PATHS) {
       const contextPath = path.join(cwd, ...parts);
       const index = _parseContextFile(contextPath);
-      if (index.size > 0) return index;
+      if (index.size > 0) return _enrichSigIndexFromStrategy(cwd, index);
     }
-    return new Map();
+    return _enrichSigIndexFromStrategy(cwd, new Map());
   }
   function formatRankTable(results, query) {
     if (!results || results.length === 0) return `No matching files found for query: "${query}"\n`;
@@ -8655,7 +8867,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '6.11.0';
+const VERSION = '6.12.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -8947,8 +9159,28 @@ function applyTokenBudget(fileEntries, maxTokens) {
   let total = fileEntries.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')), 0);
   if (total <= effectiveBudget) return fileEntries;
 
+  // v6.12 Surgical Context — progressive disclosure: before dropping whole files,
+  // collapse signature BODIES to their line-anchor pointers (keep `symbol :start-end`).
+  // Only sigs that actually carry an anchor shrink; the agent can re-fetch bodies via
+  // the get_lines MCP tool. This degrades gracefully instead of losing files outright.
+  let working = fileEntries;
+  const collapsed = fileEntries.map((e) => {
+    const slim = (e.sigs || []).map((s) => {
+      const line = toIndexLine(s);
+      return line && /:\d+-\d+/.test(line) ? line : s; // replace only when it yields an anchor
+    });
+    return { ...e, sigs: slim };
+  });
+  const collapsedTotal = collapsed.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')), 0);
+  if (collapsedTotal < total) {
+    console.warn(`[sigmap] budget: collapsed bodies to anchors, reclaimed ~${total - collapsedTotal} tokens`);
+    working = collapsed;
+    total = collapsedTotal;
+    if (total <= effectiveBudget) return working; // anchor collapse alone fit the budget
+  }
+
   // Sort by drop priority (drop first = index 0)
-  const withPriority = fileEntries.map((e) => {
+  const withPriority = working.map((e) => {
     let priority = 0;
     let dropReason = 'budget: low recency';
     if (isGeneratedFile(e.filePath)) { priority = 10; dropReason = 'budget: generated file'; }
@@ -10536,6 +10768,40 @@ function buildMiniContext(ranked, cwd) {
   return lines.join('\n');
 }
 
+// Surgical Context Phase 2 (v6.12.0): collapse one signature to a symbol-header
+// pointer — `<declaration head>  :start-end` — dropping param lists, return types,
+// and any body so the agent fetches the real lines on demand via the get_lines MCP tool.
+function toIndexLine(sig) {
+  if (typeof sig !== 'string') return '';
+  // Anchor is `:start-end`, optionally followed by a `# doc hint` (Python extractor).
+  const m = sig.match(/\s*:(\d+)-(\d+)(?:\s*#.*)?\s*$/);
+  if (!m) {
+    // No anchor (e.g. an indented member) — keep a trimmed head so it stays listed.
+    return sig.trim().slice(0, 60);
+  }
+  const range = `:${m[1]}-${m[2]}`;
+  let head = sig.slice(0, m.index).trim();
+  const paren = head.indexOf('(');
+  if (paren > 0) head = head.slice(0, paren).trim();      // drop params
+  head = head.replace(/\s*[=→].*$/, '').trim();           // drop return type / assignment tail
+  return head ? `${head}  ${range}` : range;
+}
+
+// Two-tier index output: emit only `file → [symbol:start-end]` headers (no bodies).
+function buildIndexContext(ranked, cwd) {
+  const lines = [
+    '# SigMap Query Context (index mode)',
+    `Generated: ${new Date().toISOString()}`,
+    '> Symbol index only — fetch exact lines on demand via the `get_lines` MCP tool.',
+    '',
+  ];
+  for (const { file, sigs } of ranked) {
+    const idx = sigs.slice(0, 40).map(toIndexLine).filter(Boolean);
+    lines.push(`## ${file}`, '```', ...idx, '```', '');
+  }
+  return lines.join('\n');
+}
+
 function computeCurrentRisk(cwd) {
   try {
     const { execSync } = require('child_process');
@@ -10706,7 +10972,7 @@ function main() {
   const mode = modeIdx !== -1
     ? args[modeIdx + 1]
     : (config.mode || 'default');
-  const VALID_MODES = ['default', 'fast', 'full', 'both'];
+  const VALID_MODES = ['default', 'fast', 'full', 'both', 'index'];
   if (mode && !VALID_MODES.includes(mode)) {
     console.error(`[sigmap] unknown --mode "${mode}". Valid: ${VALID_MODES.join(', ')}`);
     process.exit(1);
@@ -10785,9 +11051,23 @@ function main() {
       }
     }
 
+    // v6.12: Delta context — restrict to files changed since a git ref (--since <ref>).
+    const sinceIdx = args.indexOf('--since');
+    if (sinceIdx !== -1 && args[sinceIdx + 1]) {
+      const baseRef = args[sinceIdx + 1];
+      const changed = getFilesChangedSinceBase(cwd, baseRef);
+      const before = ranked.length;
+      ranked = ranked.filter((r) => changed.has(path.resolve(cwd, r.file)));
+      if (!args.includes('--json')) {
+        process.stderr.write(`[sigmap] Δ since ${baseRef}: ${ranked.length}/${before} ranked files changed\n`);
+      }
+    }
+
     // v6.8: Save session for future --followup calls
     saveSession(cwd, { intent, topFiles: ranked.slice(0, 5).map(r => ({ file: r.file, score: r.score })), query });
-    const miniCtx = buildMiniContext(ranked, cwd);
+    // v6.12: Two-tier output — `--mode index` emits symbol pointers only (bodies via get_lines).
+    const indexMode = mode === 'index' || args.includes('--index');
+    const miniCtx = indexMode ? buildIndexContext(ranked, cwd) : buildMiniContext(ranked, cwd);
     const outPath = path.join(cwd, '.context', 'query-context.md');
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, miniCtx, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "6.11.0",
+  "version": "6.12.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": "6.11.0",
+  "version": "6.12.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

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

package/src/format/dashboard.js

@@ -304,6 +304,106 @@ function sparkline(values) {
   }).join('');
 }
 
+function escapeAttr(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}
+
+// Surgical Context (v6.12.0): read the published token-reduction benchmark and
+// aggregate it for the dashboard panel. Numbers are never hand-typed — they come
+// straight from benchmarks/reports/token-reduction.json.
+function readTokenReduction(cwd) {
+  const p = path.join(cwd, 'benchmarks', 'reports', 'token-reduction.json');
+  let data;
+  try { data = JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+  const repos = Array.isArray(data.repos) ? data.repos : [];
+  if (repos.length === 0) return null;
+
+  let baseline = 0, signatures = 0, surgical = 0, hasSurgical = false;
+  for (const r of repos) {
+    baseline += toNumber(r.rawTokens) || 0;
+    signatures += toNumber(r.finalTokens) || 0;
+    const s = toNumber(r.surgicalTokens);
+    if (s !== null) { surgical += s; hasSurgical = true; }
+  }
+
+  const out = {
+    version: data.version || null,
+    repoCount: repos.length,
+    baseline,
+    signatures,
+    savedPct: baseline > 0 ? Math.round((1 - signatures / baseline) * 1000) / 10 : 0,
+    perRepo: repos.map((r) => ({
+      repo: r.repo,
+      language: r.language,
+      rawTokens: toNumber(r.rawTokens) || 0,
+      finalTokens: toNumber(r.finalTokens) || 0,
+      reductionPct: toNumber(r.reductionPct) || 0,
+    })),
+  };
+  if (hasSurgical) {
+    out.surgical = surgical;
+    out.surgicalSavedPct = baseline > 0 ? Math.round((1 - surgical / baseline) * 1000) / 10 : 0;
+  }
+  return out;
+}
+
+function tokenReductionPanelHtml(tr) {
+  if (!tr) {
+    return '<div class="panel"><div class="label">Token Reduction</div>' +
+      '<div class="value" style="font-size:13px">No token-reduction benchmark found — run the token benchmark to populate this panel.</div></div>';
+  }
+  const fmt = (n) => Number(n).toLocaleString('en-US');
+  const tiers = [
+    { label: 'Whole-file baseline', value: fmt(tr.baseline) + ' tok' },
+    { label: 'Ranked signatures (ask)', value: fmt(tr.signatures) + ' tok' },
+  ];
+  if (tr.surgical != null) {
+    tiers.push({ label: 'Surgical (index + delta)', value: fmt(tr.surgical) + ' tok' });
+    tiers.push({ label: 'Saved (surgical)', value: tr.surgicalSavedPct + '%' });
+  } else {
+    tiers.push({ label: 'Saved', value: tr.savedPct + '%' });
+  }
+  const tierHtml = tiers.map((t) =>
+    `<div class="card"><div class="label">${escapeAttr(t.label)}</div><div class="value">${escapeAttr(t.value)}</div></div>`
+  ).join('');
+
+  // Proportional comparison bar (baseline = full width).
+  const sigPct = tr.baseline > 0 ? Math.max(0.4, (tr.signatures / tr.baseline) * 100) : 0;
+  const surgPct = (tr.surgical != null && tr.baseline > 0) ? Math.max(0.4, (tr.surgical / tr.baseline) * 100) : null;
+  const barRow = (label, pct, color) =>
+    `<div style="margin:4px 0;font-size:11px;color:#8ea0d9">${escapeAttr(label)}</div>` +
+    `<div style="background:#0a0f1e;border:1px solid #223056;border-radius:6px;height:14px;overflow:hidden">` +
+    `<div style="width:${pct.toFixed(1)}%;height:100%;background:${color}"></div></div>`;
+  const bars = [
+    barRow('Whole-file baseline (100%)', 100, '#3a4a78'),
+    barRow(`Ranked signatures — ${tr.savedPct}% saved`, sigPct, '#2e7d6b'),
+    surgPct != null ? barRow(`Surgical — ${tr.surgicalSavedPct}% saved`, surgPct, '#5ad1a8') : '',
+  ].filter(Boolean).join('');
+
+  const rows = tr.perRepo.slice(0, 8).map((r) =>
+    `<tr><td>${escapeAttr(r.repo)}</td><td>${escapeAttr(r.language)}</td>` +
+    `<td style="text-align:right">${fmt(r.rawTokens)}</td>` +
+    `<td style="text-align:right">${fmt(r.finalTokens)}</td>` +
+    `<td style="text-align:right">${r.reductionPct}%</td></tr>`
+  ).join('');
+
+  return [
+    '<div class="panel">',
+    `<div class="label">Token Reduction — ${tr.repoCount} benchmark repos${tr.version ? ' · v' + escapeAttr(tr.version) : ''}</div>`,
+    `<div class="grid" style="margin:8px 0">${tierHtml}</div>`,
+    bars,
+    '<table style="width:100%;border-collapse:collapse;margin-top:10px;font-size:12px">',
+    '<thead><tr style="color:#8ea0d9;text-align:left">',
+    '<th>Repo</th><th>Lang</th><th style="text-align:right">Baseline</th><th style="text-align:right">Signatures</th><th style="text-align:right">Saved</th>',
+    '</tr></thead>',
+    `<tbody>${rows}</tbody>`,
+    '</table>',
+    '</div>',
+  ].join('');
+}
+
 function buildDashboardData(cwd, health) {
   const entries = readLog(cwd);
   const recent = entries.slice(-30);
@@ -326,15 +426,19 @@ function buildDashboardData(cwd, health) {
     extractorCoverage: coverage.pct,
   };
 
+  const tokenReduction = readTokenReduction(cwd);
+
   return {
     summary,
     tokenReductionTrend,
     hitAt5Trend,
     coverage,
+    tokenReduction,
     charts: {
       tokenReductionSvg: lineChartSvg(tokenReductionTrend, 'Token reduction trend (last 30 tracked runs)', '%'),
       hitAt5Svg: lineChartSvg(hitAt5Trend, 'hit@5 trend (last 30 benchmark runs)', ''),
       coverageSvg: barChartSvg(coverage.perLanguage),
+      tokenSavingsPanel: tokenReductionPanelHtml(tokenReduction),
     },
   };
 }
@@ -379,6 +483,7 @@ function generateDashboardHtml(cwd, health) {
     '<h1>SigMap v2.10 dashboard</h1>',
     '<div class="sub">Self-contained report. No external scripts, styles, or network calls.</div>',
     `<div class="grid">${cardHtml}</div>`,
+    data.charts.tokenSavingsPanel,
     `<div class="panel">${data.charts.tokenReductionSvg}</div>`,
     `<div class="panel">${data.charts.hitAt5Svg}</div>`,
     `<div class="panel">${data.charts.coverageSvg}</div>`,

package/src/mcp/handlers.js

@@ -448,4 +448,61 @@ function getImpact(args, cwd) {
   }
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
+/**
+ * get_lines({ file, start, end }) → string
+ *
+ * Surgical Context demand-driven fetch: returns an exact, clamped line range from a
+ * source file. The path is resolved inside the project root (no traversal escape) and
+ * the returned lines are secret-scanned via the same redactor used for signatures.
+ */
+function getLines(args, cwd) {
+  if (!args || !args.file) return 'Missing required argument: file';
+
+  const rel = String(args.file).replace(/\\/g, '/').replace(/^\//, '');
+  const abs = path.resolve(cwd, rel);
+
+  // Sandbox: refuse paths that resolve outside the project root.
+  const root = path.resolve(cwd);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    return `Refused: ${rel} resolves outside the project root`;
+  }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    return `File not found: ${rel}`;
+  }
+
+  const start = parseInt(args.start, 10);
+  const end = parseInt(args.end, 10);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    return 'Arguments "start" and "end" must be numbers (1-based line numbers).';
+  }
+
+  let lines;
+  try {
+    lines = fs.readFileSync(abs, 'utf8').split('\n');
+  } catch (err) {
+    return `Could not read ${rel}: ${err.message}`;
+  }
+
+  const total = lines.length;
+  const from = Math.max(1, Math.min(start, end));
+  const to = Math.min(total, Math.max(start, end));
+  if (from > total) return `${rel} has only ${total} lines; requested ${start}-${end}`;
+
+  const slice = lines.slice(from - 1, to);
+
+  // Redaction scan: reuse the signature secret scanner line-by-line.
+  let safeLines = slice;
+  try {
+    const { scan } = require('../security/scanner');
+    safeLines = scan(slice, rel).safe;
+  } catch (_) {} // non-fatal: fall back to raw slice
+
+  return [
+    `# ${rel}:${from}-${to}`,
+    '```',
+    ...safeLines,
+    '```',
+  ].join('\n');
+}
+
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines };

package/src/mcp/server.js

@@ -8,17 +8,17 @@
  *
  * Supported methods:
  *   initialize        → serverInfo + capabilities
- *   tools/list        → 3 tool definitions
+ *   tools/list        → 10 tool definitions
  *   tools/call        → dispatch to handler, return result
  */
 
 const readline = require('readline');
 const { TOOLS } = require('./tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '6.11.0',
+  version: '6.12.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -75,6 +75,7 @@ function dispatch(msg, cwd) {
       else if (name === 'list_modules') text = listModules(args, cwd);
       else if (name === 'query_context') text = queryContext(args, cwd);
       else if (name === 'get_impact') text = getImpact(args, cwd);
+      else if (name === 'get_lines') text = getLines(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -1,8 +1,9 @@
 'use strict';
 
 /**
- * MCP tool definitions for SigMap.
- * Three tools: read_context, search_signatures, get_map.
+ * MCP tool definitions for SigMap (10 tools).
+ * read_context, search_signatures, get_map, create_checkpoint, get_routing,
+ * explain_file, list_modules, query_context, get_impact, get_lines.
  */
 
 const TOOLS = [
@@ -168,6 +169,34 @@ const TOOLS = [
       required: ['file'],
     },
   },
+  {
+    name: 'get_lines',
+    description:
+      'Fetch an exact line range from a source file on demand — the Surgical Context ' +
+      'workhorse. Signatures carry `path:start-end` anchors; call this to read just those ' +
+      'lines instead of re-opening the whole file. Lines are clamped to the file bounds and ' +
+      'secret-scanned (redacted) before return. Path is sandboxed to the project root.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          description:
+            'Relative path from the project root (e.g. "src/config/loader.js"). ' +
+            'Use the path shown in a signature anchor. Use forward slashes.',
+        },
+        start: {
+          type: 'number',
+          description: '1-based start line (inclusive). Clamped to the file bounds.',
+        },
+        end: {
+          type: 'number',
+          description: '1-based end line (inclusive). Clamped to the file bounds.',
+        },
+      },
+      required: ['file', 'start', 'end'],
+    },
+  },
 ];
 
 module.exports = { TOOLS };