sigmap 7.25.2 → 7.27.0

package/CHANGELOG.md

@@ -10,6 +10,26 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.27.0] — 2026-06-22
+
+Minor release — **v8.0 D3:** two new MCP tools, taking the server from 15 to 17 tools. Both are composed from data SigMap already computes — zero new runtime dependencies, no system-shell spawns.
+
+### Added
+- **`get_diff_context` MCP tool (#376):** for every changed file (working tree, staged via `staged`, or vs a base ref via `base`) returns its current **signatures** + **blast radius** (direct importers, transitive count, affected tests/routes) + a risk label — one call gives an agent everything a review or a safe edit needs. Lists changed files **shell-free** through `src/util/git.js` (no `/bin/sh`). Optional `depth` controls the blast-radius BFS.
+- **`get_architecture_overview` MCP tool (#376):** a one-call codebase map — module breakdown (files/tokens), the most depended-on **hub files**, the dependency-**cycle** count, and route totals. Extends `get_map` for orienting in an unfamiliar repo. Composed from `buildSigIndex`, `buildFromCwd`, and `detectCycles`.
+
+### Changed
+- MCP surface count is now **17 tools** across `--help`, README, `docs-vp/guide/mcp.md`, `version.json` (`mcp_tools`), and the generated `llms.txt`/`llms-full.txt`.
+
+## [7.26.0] — 2026-06-22
+
+Minor release — **v8.0 "The Evidence Pack & the Pivot" (E1):** the keystone artifact that makes SigMap consumable by machines instead of copy-paste.
+
+### Added
+- **Evidence Pack JSON v1 (#372):** new `sigmap evidence "<query>"` command emits a deterministic, machine-consumable signature-and-evidence map — a byte-stable JSON artifact (plus a `--markdown`/`--md` handoff rendering) that an agent or CI can ingest directly, every entry anchored to a real file, symbol, and line range. Schema v1: `{ schemaVersion, query, intent, files:[{ path, symbols, reason, confidence, sourceLines, relatedTests, riskLabel }], tokenBudget, droppedFiles, grounding:{ symbolCount, anchoredSymbols, anchorCoverage, contextHash, deterministic } }`. Composed entirely from shipped zero-dep modules (ranker, line-anchor parsing, security scanner, sha256 grounding hash). The pack carries **no wall-clock timestamp** — an unchanged repo yields byte-identical output and a stable `grounding.contextHash`, so the artifact is auditable. CLI flags: `--top`, `--budget`, `--out`; always writes `.context/evidence-pack.json`. `riskLabel` ∈ {generated, test, config, security, source} and `relatedTests` are best-effort v1 (measured test-discovery and richer labels land in v8.5).
+
+---
+
 ## [7.25.2] — 2026-06-22
 
 Patch release — **Trust Hygiene (H2):** reproducible bundle build. Completes the v7.25.x "Trust Hygiene" milestone (H1+H2+H3+H4 all shipped).

package/README.md

@@ -91,7 +91,7 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v7.25-main (21 repositories, including R language)
+Benchmark : sigmap-v7.27-main (21 repositories, including R language)
 Date      : 2026-06-22
 
 Hit@5          : 75.6%   (baseline 13.6%  — 5.6× lift)
@@ -191,13 +191,13 @@ 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** — 15 on-demand tools for Claude Code and Cursor:
+**MCP server** — 17 on-demand tools for Claude Code and Cursor:
 
 ```bash
 sigmap --mcp
 ```
 
-Tools: `read_context`, `search_signatures`, `get_map`, `create_checkpoint`, `get_routing`, `explain_file`, `list_modules`, `query_context`, `get_impact`, `get_lines`, `read_memory`, `get_callee_signatures`, plus the live-index notifications `sigmap_notify_file_created`, `sigmap_notify_symbol_added`, and `sigmap_notify_file_deleted`. Full reference: [llms-full.txt](llms-full.txt).
+Tools: `read_context`, `search_signatures`, `get_map`, `create_checkpoint`, `get_routing`, `explain_file`, `list_modules`, `query_context`, `get_impact`, `get_lines`, `read_memory`, `get_callee_signatures`, `get_diff_context` (changed files + signatures + blast radius), `get_architecture_overview` (modules, hub files, cycles), plus the live-index notifications `sigmap_notify_file_created`, `sigmap_notify_symbol_added`, and `sigmap_notify_file_deleted`. Full reference: [llms-full.txt](llms-full.txt).
 
 ---
 

package/gen-context.js

@@ -4385,6 +4385,277 @@ __factories["./src/eval/usefulness-scorer"] = function(module, exports) {
   
 };
 
+// ── ./src/evidence/pack ──
+__factories["./src/evidence/pack"] = function(module, exports) {
+  
+  /**
+   * Evidence Pack v1 (v8.0 E1).
+   *
+   * A deterministic, machine-consumable signature-and-evidence map. Replaces the
+   * "paste this into your prompt" workflow with a byte-stable JSON artifact that
+   * an agent or CI can ingest directly — every entry anchored to a real file,
+   * symbol, and line range.
+   *
+   * Composed entirely from shipped zero-dep modules:
+   *   - retrieval/ranker        → ranked files, scores, signals
+   *   - extractors/line-anchor  → `:start-end` suffix parsing (sourceLines)
+   *   - security/scanner        → secret redaction of symbols
+   *   - crypto (node builtin)    → sha256 grounding hash
+   *
+   * Determinism: the pack carries NO wall-clock timestamp. Given an unchanged
+   * repository, `buildEvidencePack` returns a byte-identical object, and
+   * `grounding.contextHash` is stable. This is the point — the pack is auditable.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+  const crypto = require('crypto');
+
+  const { buildSigIndex, rank, detectIntent } = __require('./src/retrieval/ranker');
+  const { scan } = __require('./src/security/scanner');
+
+  const SCHEMA_VERSION = '1.0';
+  const DEFAULT_BUDGET = 6000;
+  const DEFAULT_TOP = 12;
+
+  const GENERATED_RE = /(^|\/)(dist|build|out|vendor|node_modules)\/|\.(generated|min|bundle)\.|\.(pb|_pb)\.|\.pb\.go$|_pb2\.py$/;
+  const TEST_RE = /(^|\/)(tests?|__tests__|spec|specs)\/|\.(test|spec)\.[a-z]+$|(^|\/)test_[^/]+\.py$|_test\.(go|py|rb)$/;
+  const CONFIG_RE = /\.(json|ya?ml|toml|ini|conf|config|properties|env)$|(^|\/)(\.?[a-z]+rc)$|\.config\.[a-z]+$/i;
+  const SECURITY_RE = /(^|\/|[._-])(auth|authn|authz|login|password|passwd|secret|credential|token|session|crypto|cipher|payment|billing|checkout|oauth|jwt|permission|acl|rbac)([._-]|\/|$)/i;
+
+  /**
+   * Split a signature's `  :start-end` line anchor from its symbol text.
+   * @param {string} sig
+   * @returns {{ symbol: string, start: number|null, end: number|null }}
+   */
+  function parseAnchor(sig) {
+    const m = /\s*:(\d+)-(\d+)\s*$/.exec(sig);
+    if (!m) return { symbol: sig.trim(), start: null, end: null };
+    return {
+      symbol: sig.slice(0, m.index).trim(),
+      start: parseInt(m[1], 10),
+      end: parseInt(m[2], 10),
+    };
+  }
+
+  /**
+   * Classify a file into a coarse risk label. Path-based heuristic (v1) — the
+   * richer label set (C3) lands in v8.5.
+   * @param {string} relPath
+   * @returns {'generated'|'test'|'config'|'security'|'source'}
+   */
+  function riskLabelFor(relPath) {
+    const p = relPath.replace(/\\/g, '/');
+    if (GENERATED_RE.test(p)) return 'generated';
+    if (TEST_RE.test(p)) return 'test';
+    if (SECURITY_RE.test(p)) return 'security';
+    if (CONFIG_RE.test(p)) return 'config';
+    return 'source';
+  }
+
+  /** Filename stem (basename minus the first extension chain). */
+  function stemOf(relPath) {
+    const base = path.basename(relPath);
+    return base.replace(/\.[^.]+$/, '').replace(/\.(test|spec)$/i, '');
+  }
+
+  /**
+   * Best-effort impl→test discovery (v1). Matches test files whose stem equals
+   * the implementation file's stem, by common convention. Deterministic. The
+   * accuracy-measured discovery (C2) lands in v8.5.
+   * @param {string} relPath
+   * @param {string[]} allFiles  - universe of indexed files (relative paths)
+   * @returns {string[]}
+   */
+  function findRelatedTests(relPath, allFiles) {
+    if (riskLabelFor(relPath) === 'test') return [];
+    const stem = stemOf(relPath).toLowerCase();
+    if (!stem) return [];
+    const out = [];
+    for (const f of allFiles) {
+      if (f === relPath) continue;
+      if (riskLabelFor(f) !== 'test') continue;
+      if (stemOf(f).toLowerCase() === stem) out.push(f);
+    }
+    return out.sort();
+  }
+
+  /** Map a ranker `signals` object into a short human-readable reason string. */
+  function reasonFor(signals) {
+    if (!signals) return 'ranked match';
+    const parts = [];
+    if (signals.symbolMatch > 0) parts.push('symbol-name match');
+    if (signals.exactToken > 0) parts.push('exact token match');
+    if (signals.prefixMatch > 0) parts.push('prefix match');
+    if (signals.pathMatch > 0) parts.push('path match');
+    if (signals.graphBoost > 0) parts.push('dependency-graph neighbor');
+    if (signals.recencyBoost > 1) parts.push('recently changed');
+    if (signals.learnedWeights && signals.learnedWeights !== 1) parts.push('learned weight');
+    return parts.length ? parts.join('; ') : 'ranked match';
+  }
+
+  /** Token estimate for a signature block (matches the ranker's heuristic). */
+  function sigTokens(sigs) {
+    return Math.ceil(sigs.join('\n').length / 4);
+  }
+
+  /**
+   * Stable stringify with recursively sorted object keys, for hashing.
+   * @param {*} value
+   * @returns {string}
+   */
+  function canonicalize(value) {
+    return JSON.stringify(sortKeys(value));
+  }
+
+  function sortKeys(value) {
+    if (Array.isArray(value)) return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+      const out = {};
+      for (const k of Object.keys(value).sort()) out[k] = sortKeys(value[k]);
+      return out;
+    }
+    return value;
+  }
+
+  /**
+   * Build an Evidence Pack for a query.
+   *
+   * @param {string} query
+   * @param {string} cwd
+   * @param {object} [opts]
+   * @param {number} [opts.budget=6000]      - token budget for included files
+   * @param {number} [opts.top=12]           - max ranked files to consider
+   * @param {Map<string,string[]>} [opts.sigIndex] - pre-built index (else built from cwd)
+   * @returns {object} Evidence Pack v1
+   */
+  function buildEvidencePack(query, cwd, opts = {}) {
+    const budget = Number.isFinite(opts.budget) ? opts.budget : DEFAULT_BUDGET;
+    const top = Number.isFinite(opts.top) ? opts.top : DEFAULT_TOP;
+
+    const sigIndex = opts.sigIndex instanceof Map ? opts.sigIndex : buildSigIndex(cwd);
+    const intent = detectIntent(query);
+    const allFiles = Array.from(sigIndex.keys());
+
+    const ranked = rank(query, sigIndex, { topK: top, cwd })
+      .filter((r) => r.score > 0 || ranked0Empty(query));
+    const maxScore = ranked.reduce((m, r) => Math.max(m, r.score), 0);
+
+    // Greedy budget fill in rank order; the remainder is reported as dropped.
+    const files = [];
+    const droppedFiles = [];
+    let used = 0;
+
+    for (const r of ranked) {
+      const tokens = sigTokens(r.sigs);
+      if (files.length > 0 && used + tokens > budget) {
+        droppedFiles.push({ path: r.file, reason: `budget: would exceed ${budget}-token limit` });
+        continue;
+      }
+      used += tokens;
+
+      const safe = scan(r.sigs, r.file).safe;
+      const symbols = [];
+      const sourceLines = [];
+      for (const sig of safe) {
+        const { symbol, start, end } = parseAnchor(sig);
+        symbols.push(symbol);
+        if (start !== null) sourceLines.push({ symbol, start, end });
+      }
+
+      files.push({
+        path: r.file,
+        symbols,
+        reason: reasonFor(r.signals),
+        confidence: maxScore > 0 ? Math.round((r.score / maxScore) * 100) / 100 : 0,
+        sourceLines,
+        relatedTests: findRelatedTests(r.file, allFiles),
+        riskLabel: riskLabelFor(r.file),
+      });
+    }
+
+    const symbolCount = files.reduce((n, f) => n + f.symbols.length, 0);
+    const anchoredSymbols = files.reduce((n, f) => n + f.sourceLines.length, 0);
+
+    const pack = {
+      schemaVersion: SCHEMA_VERSION,
+      query,
+      intent,
+      files,
+      tokenBudget: { limit: budget, used, remaining: Math.max(0, budget - used) },
+      droppedFiles,
+      grounding: {
+        symbolCount,
+        anchoredSymbols,
+        anchorCoverage: symbolCount > 0 ? Math.round((anchoredSymbols / symbolCount) * 1000) / 1000 : 0,
+        contextHash: null,
+        deterministic: true,
+      },
+    };
+
+    // Hash everything except the hash field itself.
+    const forHash = Object.assign({}, pack, {
+      grounding: Object.assign({}, pack.grounding, { contextHash: undefined }),
+    });
+    pack.grounding.contextHash = 'sha256:' + crypto.createHash('sha256').update(canonicalize(forHash)).digest('hex');
+
+    return pack;
+  }
+
+  // rank() returns [] for an empty/whitespace query; keep the filter readable.
+  function ranked0Empty(query) {
+    return !query || !query.trim();
+  }
+
+  /** Pretty-printed canonical JSON rendering of a pack. */
+  function formatJSON(pack) {
+    return JSON.stringify(pack, null, 2);
+  }
+
+  /** Markdown handoff rendering of a pack. */
+  function formatMarkdown(pack) {
+    const L = [];
+    L.push(`# Evidence Pack — \`${pack.query}\``);
+    L.push('');
+    L.push(`- **Schema:** v${pack.schemaVersion}`);
+    L.push(`- **Intent:** ${pack.intent}`);
+    L.push(`- **Budget:** ${pack.tokenBudget.used} / ${pack.tokenBudget.limit} tokens used (${pack.tokenBudget.remaining} remaining)`);
+    L.push(`- **Grounding:** ${pack.grounding.anchoredSymbols}/${pack.grounding.symbolCount} symbols anchored (${Math.round(pack.grounding.anchorCoverage * 100)}%)`);
+    L.push(`- **Hash:** \`${pack.grounding.contextHash}\``);
+    L.push('');
+
+    for (const f of pack.files) {
+      L.push(`## \`${f.path}\`  _(${f.riskLabel}, confidence ${f.confidence})_`);
+      L.push(`_${f.reason}_`);
+      if (f.relatedTests.length) L.push(`Related tests: ${f.relatedTests.map((t) => `\`${t}\``).join(', ')}`);
+      L.push('');
+      L.push('```');
+      for (const s of f.symbols) L.push(s);
+      L.push('```');
+      L.push('');
+    }
+
+    if (pack.droppedFiles.length) {
+      L.push('## Dropped (over budget)');
+      for (const d of pack.droppedFiles) L.push(`- \`${d.path}\` — ${d.reason}`);
+      L.push('');
+    }
+
+    return L.join('\n');
+  }
+
+  module.exports = {
+    buildEvidencePack,
+    formatJSON,
+    formatMarkdown,
+    parseAnchor,
+    riskLabelFor,
+    findRelatedTests,
+    SCHEMA_VERSION,
+  };
+  
+};
+
 // ── ./src/extractors/coverage ──
 __factories["./src/extractors/coverage"] = function(module, exports) {
   
@@ -11838,7 +12109,182 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     }
   }
 
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted };
+  /**
+   * List the files changed in the working tree, staged area, or vs a base ref.
+   * Shell-free (routes through src/util/git.js). Returns relative paths.
+   */
+  function _changedFiles(cwd, args) {
+    const { tryGit } = __require('./src/util/git');
+    let out = '';
+    if (args.base) {
+      if (!/^[A-Za-z0-9._/\-~^]+$/.test(args.base)) return [];
+      out = tryGit(['diff', `${args.base}..HEAD`, '--name-only'], { cwd });
+    } else if (args.staged) {
+      out = tryGit(['diff', '--cached', '--name-only'], { cwd });
+    } else {
+      out = tryGit(['diff', 'HEAD', '--name-only'], { cwd });
+    }
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  }
+
+  /**
+   * get_diff_context({ base?, staged?, depth? }) → string
+   *
+   * For each changed file: its extracted signatures + blast radius (direct
+   * importers, transitive count, affected tests/routes) + a risk label.
+   * Hands an agent everything a review or a safe edit needs in one call.
+   */
+  function getDiffContext(args, cwd) {
+    try {
+      const a = args || {};
+      const files = _changedFiles(cwd, a);
+      if (files.length === 0) {
+        return '_No changed files detected._ (Outside a git repo, or the working tree / selected range is clean.)';
+      }
+
+      const { extractFile, langFor } = __require('./src/extractors/dispatch');
+      const { analyzeImpact } = __require('./src/graph/impact');
+      let riskLabelFor;
+      try { ({ riskLabelFor } = __require('./src/evidence/pack')); } catch (_) { riskLabelFor = () => 'source'; }
+
+      const depth = Math.max(0, parseInt(a.depth, 10) || 2);
+      const srcFiles = files.filter((f) => langFor(f));
+      let impactByFile = new Map();
+      try {
+        const impacts = analyzeImpact(srcFiles, cwd, { depth });
+        impactByFile = new Map(impacts.map((r) => [r.file, r.impact]));
+      } catch (_) { /* graph optional */ }
+
+      const scope = a.base ? `vs ${a.base}` : (a.staged ? 'staged' : 'working tree');
+      const out = [
+        `# Diff context (${scope})`,
+        '',
+        `**${files.length} changed file${files.length === 1 ? '' : 's'}** · ${srcFiles.length} with extractable signatures`,
+        '',
+      ];
+
+      for (const rel of files) {
+        out.push(`## \`${rel}\``);
+        if (!langFor(rel)) { out.push('_non-source file (no signatures)_', ''); continue; }
+
+        out.push(`_risk: ${riskLabelFor(rel)}_`);
+        const impact = impactByFile.get(rel);
+        if (impact) {
+          out.push(
+            `**Blast radius:** ${impact.totalImpact} file(s) impacted — ` +
+            `${impact.direct.length} direct importer(s), ${impact.transitive.length} transitive` +
+            (impact.tests.length ? `, ${impact.tests.length} test(s)` : '') +
+            (impact.routes.length ? `, ${impact.routes.length} route(s)` : '')
+          );
+          if (impact.direct.length) {
+            out.push(`Direct importers: ${impact.direct.slice(0, 8).map((f) => '`' + f + '`').join(', ')}` + (impact.direct.length > 8 ? ' …' : ''));
+          }
+          if (impact.tests.length) {
+            out.push(`Tests to run: ${impact.tests.slice(0, 8).map((f) => '`' + f + '`').join(', ')}`);
+          }
+        } else {
+          out.push('**Blast radius:** (not in dependency graph — new or leaf file)');
+        }
+        out.push('');
+
+        let src = '';
+        try { src = fs.readFileSync(path.resolve(cwd, rel), 'utf8'); } catch (_) {}
+        const sigs = src ? extractFile(rel, src) : [];
+        if (sigs.length) {
+          out.push('```');
+          for (const s of sigs.slice(0, 40)) out.push(s);
+          if (sigs.length > 40) out.push(`… +${sigs.length - 40} more`);
+          out.push('```');
+        } else {
+          out.push('_(no signatures extracted — file may be deleted or empty)_');
+        }
+        out.push('');
+      }
+
+      return out.join('\n');
+    } catch (err) {
+      return `_get_diff_context failed: ${err.message}_`;
+    }
+  }
+
+  /**
+   * get_architecture_overview({}) → string
+   *
+   * A high-level map of the codebase: module breakdown (files/tokens), the most
+   * depended-on "hub" files, dependency-cycle count, and route totals. Extends
+   * get_map — one call to orient in an unfamiliar repo.
+   */
+  function getArchitectureOverview(args, cwd) {
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      const out = ['# Architecture overview', ''];
+
+      if (index.size === 0) {
+        out.push('_No context file found. Run: node gen-context.js_', '');
+      } else {
+        const groups = {};
+        let totalTokens = 0;
+        let totalFiles = 0;
+        for (const [rel, sigs] of index.entries()) {
+          const parts = rel.replace(/\\/g, '/').split('/');
+          const mod = parts.length > 1 ? parts[0] : '.';
+          const tok = Math.ceil(sigs.join('\n').length / 4);
+          if (!groups[mod]) groups[mod] = { files: 0, tokens: 0 };
+          groups[mod].files++;
+          groups[mod].tokens += tok;
+          totalTokens += tok;
+          totalFiles++;
+        }
+        const sorted = Object.entries(groups)
+          .map(([mod, d]) => ({ mod, files: d.files, tokens: d.tokens }))
+          .sort((a, b) => b.tokens - a.tokens);
+
+        out.push(`**${totalFiles} indexed files · ${sorted.length} modules · ~${totalTokens} tokens**`, '');
+        out.push('## Modules', '| Module | Files | Tokens |', '|--------|-------|--------|');
+        for (const m of sorted.slice(0, 20)) out.push(`| ${m.mod} | ${m.files} | ~${m.tokens} |`);
+        out.push('');
+      }
+
+      // Hub files + cycle count from the dependency graph (optional).
+      try {
+        const { buildFromCwd } = __require('./src/graph/builder');
+        const { detectCycles } = __require('./src/map/import-graph');
+        const graph = buildFromCwd(cwd);
+        if (graph && graph.reverse && graph.reverse.size) {
+          const hubs = [...graph.reverse.entries()]
+            .map(([f, importers]) => ({ file: path.relative(cwd, f).replace(/\\/g, '/'), in: importers.length }))
+            .filter((h) => h.in > 0)
+            .sort((a, b) => b.in - a.in)
+            .slice(0, 10);
+          if (hubs.length) {
+            out.push('## Hub files (most depended-on)', '| File | Importers |', '|------|-----------|');
+            for (const h of hubs) out.push(`| \`${h.file}\` | ${h.in} |`);
+            out.push('');
+          }
+          let cycleCount = 0;
+          try { cycleCount = detectCycles(graph.forward).length; } catch (_) {}
+          out.push(`**Dependency cycles:** ${cycleCount}` + (cycleCount ? ' _(see import graph)_' : ' — none detected'), '');
+        }
+      } catch (_) { /* graph optional */ }
+
+      // Routes from PROJECT_MAP.md if present.
+      const mapPath = path.join(cwd, 'PROJECT_MAP.md');
+      if (fs.existsSync(mapPath)) {
+        const mc = fs.readFileSync(mapPath, 'utf8');
+        const routeCount = mc.split('\n').filter((l) => l.startsWith('| ') && !l.startsWith('| Method') && !l.startsWith('|---')).length;
+        out.push('## Project map', `Routes detected: ${routeCount} _(use get_map for imports/classes/routes detail)_`, '');
+      } else {
+        out.push('_Run `node gen-project-map.js` for routes / class-hierarchy detail (get_map)._');
+      }
+
+      return out.join('\n');
+    } catch (err) {
+      return `_get_architecture_overview failed: ${err.message}_`;
+    }
+  }
+
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview };
   
 };
 
@@ -11853,17 +12299,17 @@ __factories["./src/mcp/server"] = function(module, exports) {
    *
    * Supported methods:
    *   initialize        → serverInfo + capabilities
-   *   tools/list        → 11 tool definitions
+   *   tools/list        → 17 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, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted } = __require('./src/mcp/handlers');
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview } = __require('./src/mcp/handlers');
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.25.2',
+    version: '7.27.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -11926,6 +12372,8 @@ __factories["./src/mcp/server"] = function(module, exports) {
         else if (name === 'sigmap_notify_file_created') text = notifyFileCreated(args, cwd);
         else if (name === 'sigmap_notify_symbol_added') text = notifySymbolAdded(args, cwd);
         else if (name === 'sigmap_notify_file_deleted') text = notifyFileDeleted(args, cwd);
+        else if (name === 'get_diff_context') text = getDiffContext(args, cwd);
+        else if (name === 'get_architecture_overview') text = getArchitectureOverview(args, cwd);
         else {
           respondError(id, -32601, `Unknown tool: ${name}`);
           return;
@@ -11986,11 +12434,11 @@ __factories["./src/mcp/server"] = function(module, exports) {
 __factories["./src/mcp/tools"] = function(module, exports) {
   
   /**
-   * MCP tool definitions for SigMap (15 tools).
+   * MCP tool definitions for SigMap (17 tools).
    * read_context, search_signatures, get_map, create_checkpoint, get_routing,
    * explain_file, list_modules, query_context, get_impact, get_lines, read_memory,
    * get_callee_signatures, sigmap_notify_file_created, sigmap_notify_symbol_added,
-   * sigmap_notify_file_deleted.
+   * sigmap_notify_file_deleted, get_diff_context, get_architecture_overview.
    */
 
   const TOOLS = [
@@ -12263,6 +12711,44 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         required: ['path'],
       },
     },
+    {
+      name: 'get_diff_context',
+      description:
+        'For every changed file in the working tree (or staged, or vs a base ref), return its ' +
+        'current signatures plus blast radius — direct importers, transitive count, and affected ' +
+        'tests/routes — with a risk label. One call gives an agent everything a code review or a ' +
+        'safe edit needs. Lists changed files shell-free (git binary, never a shell).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          base: {
+            type: 'string',
+            description: 'Optional git ref to diff against (e.g. "main"). Returns files changed in `base..HEAD`. Omit for working-tree changes.',
+          },
+          staged: {
+            type: 'boolean',
+            description: 'When true (and no base), report only staged changes (`git diff --cached`).',
+          },
+          depth: {
+            type: 'number',
+            description: 'Blast-radius BFS depth limit (default: 2). Use 0 for unlimited.',
+          },
+        },
+        required: [],
+      },
+    },
+    {
+      name: 'get_architecture_overview',
+      description:
+        'A high-level map of the codebase in one call: module breakdown (files/tokens), the most ' +
+        'depended-on "hub" files, the dependency-cycle count, and route totals. Extends get_map — ' +
+        'use it to orient in an unfamiliar repo before drilling in with read_context / query_context.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+    },
   ];
 
   module.exports = { TOOLS };
@@ -15652,7 +16138,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.25.2';
+const VERSION = '7.27.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -17459,6 +17945,9 @@ Usage:
   ${cmd} ask "<query>" --squeeze           Auto-accept input minimization (no prompt; for scripts/CI)
   ${cmd} ask "<query>" --no-squeeze        Disable input minimization entirely
   ${cmd} ask "<query>" --squeeze-threshold N  Min reduction %% to prompt (default 30)
+  ${cmd} evidence "<query>"                Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json
+  ${cmd} evidence "<query>" --markdown     Emit the Markdown handoff rendering to stdout
+  ${cmd} evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
   ${cmd} note "<text>"                     Append a note to the cross-session decision log
   ${cmd} note                              List recent notes (also: note --list <N>)
   ${cmd} status                            Show repo state — branch, dirty files, index freshness, notes
@@ -18031,6 +18520,66 @@ function main() {
     process.exit(0);
   }
 
+  // `sigmap evidence "<query>"` — Evidence Pack v1 (v8.0 E1).
+  // Deterministic, machine-consumable signature+evidence map. Always writes the
+  // JSON artifact to .context/evidence-pack.json; stdout carries the requested
+  // mode (JSON default, or Markdown handoff with --markdown/--md).
+  if (args[0] === 'evidence') {
+    const query = args[1];
+    if (!query || query.startsWith('--')) {
+      console.error('[sigmap] Usage: sigmap evidence "<query>" [--markdown] [--top <n>] [--budget <n>] [--out <path>]');
+      console.error('  Example: sigmap evidence "how does auth work" --markdown');
+      process.exit(1);
+    }
+
+    const { buildEvidencePack, formatJSON, formatMarkdown } = requireSourceOrBundled('./src/evidence/pack');
+
+    const opts = {};
+    const topIdx = args.indexOf('--top');
+    if (topIdx !== -1 && args[topIdx + 1]) opts.top = parseInt(args[topIdx + 1], 10);
+    const budgetIdx = args.indexOf('--budget');
+    if (budgetIdx !== -1 && args[budgetIdx + 1]) opts.budget = parseInt(args[budgetIdx + 1], 10);
+    else opts.budget = (config && config.maxTokens) || 6000;
+
+    let pack;
+    try {
+      pack = buildEvidencePack(query, cwd, opts);
+    } catch (e) {
+      console.error('[sigmap] evidence: ' + e.message);
+      process.exit(1);
+    }
+
+    if (pack.files.length === 0) {
+      process.stderr.write('[sigmap] ⚠  no matching files indexed. Run: sigmap  (to generate context first)\n');
+    }
+
+    const jsonText = formatJSON(pack);
+    const artifactPath = path.join(cwd, '.context', 'evidence-pack.json');
+    try {
+      fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+      fs.writeFileSync(artifactPath, jsonText, 'utf8');
+      process.stderr.write(`[sigmap] evidence pack → ${path.relative(cwd, artifactPath)} (${pack.files.length} files, ${pack.grounding.symbolCount} symbols)\n`);
+    } catch (_) { /* artifact write is best-effort */ }
+
+    const markdown = args.includes('--markdown') || args.includes('--md');
+    const rendered = markdown ? formatMarkdown(pack) : jsonText;
+
+    const outIdx = args.indexOf('--out');
+    if (outIdx !== -1 && args[outIdx + 1]) {
+      const outPath = path.resolve(cwd, args[outIdx + 1]);
+      try {
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, rendered + '\n', 'utf8');
+      } catch (e) {
+        console.error('[sigmap] evidence: could not write --out ' + outPath + ': ' + e.message);
+        process.exit(1);
+      }
+    }
+
+    process.stdout.write(rendered + '\n');
+    process.exit(0);
+  }
+
   // `sigmap gain` — token-savings dashboard (totals, by-operation, trends).
   if (args[0] === 'gain') {
     const valOf = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i + 1] ? args[i + 1] : d; };

package/llms-full.txt

@@ -9,13 +9,13 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.25.2 | Benchmark: sigmap-v7.25-main (2026-06-22)
+# Version: 7.27.0 | Benchmark: sigmap-v7.27-main (2026-06-22)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v7.25-main, 2026-06-22)
+## Core metrics (benchmark: sigmap-v7.27-main, 2026-06-22)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -24,7 +24,7 @@ Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 | Task success proxy | 10% | 52.2% |
 | Prompts per task | 2.84 | 1.72 (39.4% fewer) |
 | Supported languages | — | 33 |
-| MCP tools | — | 15 |
+| MCP tools | — | 17 |
 | npm runtime dependencies | — | 0 |
 
 ---
@@ -109,6 +109,9 @@ sigmap squeeze <file|->                  Minimize a pasted stacktrace/CI-log/JSO
 sigmap ask "<query>" --squeeze           Auto-accept input minimization (no prompt; for scripts/CI)
 sigmap ask "<query>" --no-squeeze        Disable input minimization entirely
 sigmap ask "<query>" --squeeze-threshold N  Min reduction %% to prompt (default 30)
+sigmap evidence "<query>"                Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json
+sigmap evidence "<query>" --markdown     Emit the Markdown handoff rendering to stdout
+sigmap evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes
@@ -119,7 +122,7 @@ sigmap --version                         Show version
 
 ---
 
-## MCP server — 15 tools
+## MCP server — 17 tools
 
 Start with `sigmap --mcp` (stdio JSON-RPC). Configure once:
 
@@ -247,6 +250,22 @@ Tell SigMap a file was deleted so its symbols are dropped from the live index.
 Input:  { path: string }
 ```
 
+### get_diff_context
+
+For every changed file in the working tree (or staged, or vs a base ref), return its current signatures plus blast radius — direct importers, transitive count, and affected tests/routes — with a risk label. One call gives an agent everything a code review or a safe edit needs. Lists changed files shell-free (git binary, never a shell).
+
+```
+Input:  { base?: string, staged?: boolean, depth?: number }
+```
+
+### get_architecture_overview
+
+A high-level map of the codebase in one call: module breakdown (files/tokens), the most depended-on "hub" files, the dependency-cycle count, and route totals. Extends get_map — use it to orient in an unfamiliar repo before drilling in with read_context / query_context.
+
+```
+Input:  { } (no arguments)
+```
+
 ---
 
 ## Configuration (gen-context.config.json)

package/llms.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.25.2 | Benchmark: sigmap-v7.25-main (2026-06-22)
+# Version: 7.27.0 | Benchmark: sigmap-v7.27-main (2026-06-22)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -21,13 +21,13 @@ Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v7.25-main, 2026-06-22)
+## Core metrics (benchmark: sigmap-v7.27-main, 2026-06-22)
 
 - hit@5 retrieval: 75.6% vs 13.6% random baseline (5.6× lift)
 - Token reduction: 97.0% average across benchmark repos
 - Task success: 52.2% vs 10% without SigMap
 - Prompts per task: 1.72 vs 2.84 baseline (39.4% fewer)
-- Languages: 33 supported · MCP tools: 15
+- Languages: 33 supported · MCP tools: 17
 - Dependencies: zero npm runtime dependencies · fully offline
 
 ## Quick start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "7.25.2",
+  "version": "7.27.0",
   "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "7.25.2",
+  "version": "7.27.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": "7.25.2",
+  "version": "7.27.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/evidence/pack.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Evidence Pack v1 (v8.0 E1).
+ *
+ * A deterministic, machine-consumable signature-and-evidence map. Replaces the
+ * "paste this into your prompt" workflow with a byte-stable JSON artifact that
+ * an agent or CI can ingest directly — every entry anchored to a real file,
+ * symbol, and line range.
+ *
+ * Composed entirely from shipped zero-dep modules:
+ *   - retrieval/ranker        → ranked files, scores, signals
+ *   - extractors/line-anchor  → `:start-end` suffix parsing (sourceLines)
+ *   - security/scanner        → secret redaction of symbols
+ *   - crypto (node builtin)    → sha256 grounding hash
+ *
+ * Determinism: the pack carries NO wall-clock timestamp. Given an unchanged
+ * repository, `buildEvidencePack` returns a byte-identical object, and
+ * `grounding.contextHash` is stable. This is the point — the pack is auditable.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { buildSigIndex, rank, detectIntent } = require('../retrieval/ranker');
+const { scan } = require('../security/scanner');
+
+const SCHEMA_VERSION = '1.0';
+const DEFAULT_BUDGET = 6000;
+const DEFAULT_TOP = 12;
+
+const GENERATED_RE = /(^|\/)(dist|build|out|vendor|node_modules)\/|\.(generated|min|bundle)\.|\.(pb|_pb)\.|\.pb\.go$|_pb2\.py$/;
+const TEST_RE = /(^|\/)(tests?|__tests__|spec|specs)\/|\.(test|spec)\.[a-z]+$|(^|\/)test_[^/]+\.py$|_test\.(go|py|rb)$/;
+const CONFIG_RE = /\.(json|ya?ml|toml|ini|conf|config|properties|env)$|(^|\/)(\.?[a-z]+rc)$|\.config\.[a-z]+$/i;
+const SECURITY_RE = /(^|\/|[._-])(auth|authn|authz|login|password|passwd|secret|credential|token|session|crypto|cipher|payment|billing|checkout|oauth|jwt|permission|acl|rbac)([._-]|\/|$)/i;
+
+/**
+ * Split a signature's `  :start-end` line anchor from its symbol text.
+ * @param {string} sig
+ * @returns {{ symbol: string, start: number|null, end: number|null }}
+ */
+function parseAnchor(sig) {
+  const m = /\s*:(\d+)-(\d+)\s*$/.exec(sig);
+  if (!m) return { symbol: sig.trim(), start: null, end: null };
+  return {
+    symbol: sig.slice(0, m.index).trim(),
+    start: parseInt(m[1], 10),
+    end: parseInt(m[2], 10),
+  };
+}
+
+/**
+ * Classify a file into a coarse risk label. Path-based heuristic (v1) — the
+ * richer label set (C3) lands in v8.5.
+ * @param {string} relPath
+ * @returns {'generated'|'test'|'config'|'security'|'source'}
+ */
+function riskLabelFor(relPath) {
+  const p = relPath.replace(/\\/g, '/');
+  if (GENERATED_RE.test(p)) return 'generated';
+  if (TEST_RE.test(p)) return 'test';
+  if (SECURITY_RE.test(p)) return 'security';
+  if (CONFIG_RE.test(p)) return 'config';
+  return 'source';
+}
+
+/** Filename stem (basename minus the first extension chain). */
+function stemOf(relPath) {
+  const base = path.basename(relPath);
+  return base.replace(/\.[^.]+$/, '').replace(/\.(test|spec)$/i, '');
+}
+
+/**
+ * Best-effort impl→test discovery (v1). Matches test files whose stem equals
+ * the implementation file's stem, by common convention. Deterministic. The
+ * accuracy-measured discovery (C2) lands in v8.5.
+ * @param {string} relPath
+ * @param {string[]} allFiles  - universe of indexed files (relative paths)
+ * @returns {string[]}
+ */
+function findRelatedTests(relPath, allFiles) {
+  if (riskLabelFor(relPath) === 'test') return [];
+  const stem = stemOf(relPath).toLowerCase();
+  if (!stem) return [];
+  const out = [];
+  for (const f of allFiles) {
+    if (f === relPath) continue;
+    if (riskLabelFor(f) !== 'test') continue;
+    if (stemOf(f).toLowerCase() === stem) out.push(f);
+  }
+  return out.sort();
+}
+
+/** Map a ranker `signals` object into a short human-readable reason string. */
+function reasonFor(signals) {
+  if (!signals) return 'ranked match';
+  const parts = [];
+  if (signals.symbolMatch > 0) parts.push('symbol-name match');
+  if (signals.exactToken > 0) parts.push('exact token match');
+  if (signals.prefixMatch > 0) parts.push('prefix match');
+  if (signals.pathMatch > 0) parts.push('path match');
+  if (signals.graphBoost > 0) parts.push('dependency-graph neighbor');
+  if (signals.recencyBoost > 1) parts.push('recently changed');
+  if (signals.learnedWeights && signals.learnedWeights !== 1) parts.push('learned weight');
+  return parts.length ? parts.join('; ') : 'ranked match';
+}
+
+/** Token estimate for a signature block (matches the ranker's heuristic). */
+function sigTokens(sigs) {
+  return Math.ceil(sigs.join('\n').length / 4);
+}
+
+/**
+ * Stable stringify with recursively sorted object keys, for hashing.
+ * @param {*} value
+ * @returns {string}
+ */
+function canonicalize(value) {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = sortKeys(value[k]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Build an Evidence Pack for a query.
+ *
+ * @param {string} query
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {number} [opts.budget=6000]      - token budget for included files
+ * @param {number} [opts.top=12]           - max ranked files to consider
+ * @param {Map<string,string[]>} [opts.sigIndex] - pre-built index (else built from cwd)
+ * @returns {object} Evidence Pack v1
+ */
+function buildEvidencePack(query, cwd, opts = {}) {
+  const budget = Number.isFinite(opts.budget) ? opts.budget : DEFAULT_BUDGET;
+  const top = Number.isFinite(opts.top) ? opts.top : DEFAULT_TOP;
+
+  const sigIndex = opts.sigIndex instanceof Map ? opts.sigIndex : buildSigIndex(cwd);
+  const intent = detectIntent(query);
+  const allFiles = Array.from(sigIndex.keys());
+
+  const ranked = rank(query, sigIndex, { topK: top, cwd })
+    .filter((r) => r.score > 0 || ranked0Empty(query));
+  const maxScore = ranked.reduce((m, r) => Math.max(m, r.score), 0);
+
+  // Greedy budget fill in rank order; the remainder is reported as dropped.
+  const files = [];
+  const droppedFiles = [];
+  let used = 0;
+
+  for (const r of ranked) {
+    const tokens = sigTokens(r.sigs);
+    if (files.length > 0 && used + tokens > budget) {
+      droppedFiles.push({ path: r.file, reason: `budget: would exceed ${budget}-token limit` });
+      continue;
+    }
+    used += tokens;
+
+    const safe = scan(r.sigs, r.file).safe;
+    const symbols = [];
+    const sourceLines = [];
+    for (const sig of safe) {
+      const { symbol, start, end } = parseAnchor(sig);
+      symbols.push(symbol);
+      if (start !== null) sourceLines.push({ symbol, start, end });
+    }
+
+    files.push({
+      path: r.file,
+      symbols,
+      reason: reasonFor(r.signals),
+      confidence: maxScore > 0 ? Math.round((r.score / maxScore) * 100) / 100 : 0,
+      sourceLines,
+      relatedTests: findRelatedTests(r.file, allFiles),
+      riskLabel: riskLabelFor(r.file),
+    });
+  }
+
+  const symbolCount = files.reduce((n, f) => n + f.symbols.length, 0);
+  const anchoredSymbols = files.reduce((n, f) => n + f.sourceLines.length, 0);
+
+  const pack = {
+    schemaVersion: SCHEMA_VERSION,
+    query,
+    intent,
+    files,
+    tokenBudget: { limit: budget, used, remaining: Math.max(0, budget - used) },
+    droppedFiles,
+    grounding: {
+      symbolCount,
+      anchoredSymbols,
+      anchorCoverage: symbolCount > 0 ? Math.round((anchoredSymbols / symbolCount) * 1000) / 1000 : 0,
+      contextHash: null,
+      deterministic: true,
+    },
+  };
+
+  // Hash everything except the hash field itself.
+  const forHash = Object.assign({}, pack, {
+    grounding: Object.assign({}, pack.grounding, { contextHash: undefined }),
+  });
+  pack.grounding.contextHash = 'sha256:' + crypto.createHash('sha256').update(canonicalize(forHash)).digest('hex');
+
+  return pack;
+}
+
+// rank() returns [] for an empty/whitespace query; keep the filter readable.
+function ranked0Empty(query) {
+  return !query || !query.trim();
+}
+
+/** Pretty-printed canonical JSON rendering of a pack. */
+function formatJSON(pack) {
+  return JSON.stringify(pack, null, 2);
+}
+
+/** Markdown handoff rendering of a pack. */
+function formatMarkdown(pack) {
+  const L = [];
+  L.push(`# Evidence Pack — \`${pack.query}\``);
+  L.push('');
+  L.push(`- **Schema:** v${pack.schemaVersion}`);
+  L.push(`- **Intent:** ${pack.intent}`);
+  L.push(`- **Budget:** ${pack.tokenBudget.used} / ${pack.tokenBudget.limit} tokens used (${pack.tokenBudget.remaining} remaining)`);
+  L.push(`- **Grounding:** ${pack.grounding.anchoredSymbols}/${pack.grounding.symbolCount} symbols anchored (${Math.round(pack.grounding.anchorCoverage * 100)}%)`);
+  L.push(`- **Hash:** \`${pack.grounding.contextHash}\``);
+  L.push('');
+
+  for (const f of pack.files) {
+    L.push(`## \`${f.path}\`  _(${f.riskLabel}, confidence ${f.confidence})_`);
+    L.push(`_${f.reason}_`);
+    if (f.relatedTests.length) L.push(`Related tests: ${f.relatedTests.map((t) => `\`${t}\``).join(', ')}`);
+    L.push('');
+    L.push('```');
+    for (const s of f.symbols) L.push(s);
+    L.push('```');
+    L.push('');
+  }
+
+  if (pack.droppedFiles.length) {
+    L.push('## Dropped (over budget)');
+    for (const d of pack.droppedFiles) L.push(`- \`${d.path}\` — ${d.reason}`);
+    L.push('');
+  }
+
+  return L.join('\n');
+}
+
+module.exports = {
+  buildEvidencePack,
+  formatJSON,
+  formatMarkdown,
+  parseAnchor,
+  riskLabelFor,
+  findRelatedTests,
+  SCHEMA_VERSION,
+};

package/src/mcp/handlers.js

@@ -674,4 +674,179 @@ function notifyFileDeleted(args, cwd) {
   }
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted };
+/**
+ * List the files changed in the working tree, staged area, or vs a base ref.
+ * Shell-free (routes through src/util/git.js). Returns relative paths.
+ */
+function _changedFiles(cwd, args) {
+  const { tryGit } = require('../util/git');
+  let out = '';
+  if (args.base) {
+    if (!/^[A-Za-z0-9._/\-~^]+$/.test(args.base)) return [];
+    out = tryGit(['diff', `${args.base}..HEAD`, '--name-only'], { cwd });
+  } else if (args.staged) {
+    out = tryGit(['diff', '--cached', '--name-only'], { cwd });
+  } else {
+    out = tryGit(['diff', 'HEAD', '--name-only'], { cwd });
+  }
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * get_diff_context({ base?, staged?, depth? }) → string
+ *
+ * For each changed file: its extracted signatures + blast radius (direct
+ * importers, transitive count, affected tests/routes) + a risk label.
+ * Hands an agent everything a review or a safe edit needs in one call.
+ */
+function getDiffContext(args, cwd) {
+  try {
+    const a = args || {};
+    const files = _changedFiles(cwd, a);
+    if (files.length === 0) {
+      return '_No changed files detected._ (Outside a git repo, or the working tree / selected range is clean.)';
+    }
+
+    const { extractFile, langFor } = require('../extractors/dispatch');
+    const { analyzeImpact } = require('../graph/impact');
+    let riskLabelFor;
+    try { ({ riskLabelFor } = require('../evidence/pack')); } catch (_) { riskLabelFor = () => 'source'; }
+
+    const depth = Math.max(0, parseInt(a.depth, 10) || 2);
+    const srcFiles = files.filter((f) => langFor(f));
+    let impactByFile = new Map();
+    try {
+      const impacts = analyzeImpact(srcFiles, cwd, { depth });
+      impactByFile = new Map(impacts.map((r) => [r.file, r.impact]));
+    } catch (_) { /* graph optional */ }
+
+    const scope = a.base ? `vs ${a.base}` : (a.staged ? 'staged' : 'working tree');
+    const out = [
+      `# Diff context (${scope})`,
+      '',
+      `**${files.length} changed file${files.length === 1 ? '' : 's'}** · ${srcFiles.length} with extractable signatures`,
+      '',
+    ];
+
+    for (const rel of files) {
+      out.push(`## \`${rel}\``);
+      if (!langFor(rel)) { out.push('_non-source file (no signatures)_', ''); continue; }
+
+      out.push(`_risk: ${riskLabelFor(rel)}_`);
+      const impact = impactByFile.get(rel);
+      if (impact) {
+        out.push(
+          `**Blast radius:** ${impact.totalImpact} file(s) impacted — ` +
+          `${impact.direct.length} direct importer(s), ${impact.transitive.length} transitive` +
+          (impact.tests.length ? `, ${impact.tests.length} test(s)` : '') +
+          (impact.routes.length ? `, ${impact.routes.length} route(s)` : '')
+        );
+        if (impact.direct.length) {
+          out.push(`Direct importers: ${impact.direct.slice(0, 8).map((f) => '`' + f + '`').join(', ')}` + (impact.direct.length > 8 ? ' …' : ''));
+        }
+        if (impact.tests.length) {
+          out.push(`Tests to run: ${impact.tests.slice(0, 8).map((f) => '`' + f + '`').join(', ')}`);
+        }
+      } else {
+        out.push('**Blast radius:** (not in dependency graph — new or leaf file)');
+      }
+      out.push('');
+
+      let src = '';
+      try { src = fs.readFileSync(path.resolve(cwd, rel), 'utf8'); } catch (_) {}
+      const sigs = src ? extractFile(rel, src) : [];
+      if (sigs.length) {
+        out.push('```');
+        for (const s of sigs.slice(0, 40)) out.push(s);
+        if (sigs.length > 40) out.push(`… +${sigs.length - 40} more`);
+        out.push('```');
+      } else {
+        out.push('_(no signatures extracted — file may be deleted or empty)_');
+      }
+      out.push('');
+    }
+
+    return out.join('\n');
+  } catch (err) {
+    return `_get_diff_context failed: ${err.message}_`;
+  }
+}
+
+/**
+ * get_architecture_overview({}) → string
+ *
+ * A high-level map of the codebase: module breakdown (files/tokens), the most
+ * depended-on "hub" files, dependency-cycle count, and route totals. Extends
+ * get_map — one call to orient in an unfamiliar repo.
+ */
+function getArchitectureOverview(args, cwd) {
+  try {
+    const { buildSigIndex } = require('../retrieval/ranker');
+    const index = buildSigIndex(cwd);
+    const out = ['# Architecture overview', ''];
+
+    if (index.size === 0) {
+      out.push('_No context file found. Run: node gen-context.js_', '');
+    } else {
+      const groups = {};
+      let totalTokens = 0;
+      let totalFiles = 0;
+      for (const [rel, sigs] of index.entries()) {
+        const parts = rel.replace(/\\/g, '/').split('/');
+        const mod = parts.length > 1 ? parts[0] : '.';
+        const tok = Math.ceil(sigs.join('\n').length / 4);
+        if (!groups[mod]) groups[mod] = { files: 0, tokens: 0 };
+        groups[mod].files++;
+        groups[mod].tokens += tok;
+        totalTokens += tok;
+        totalFiles++;
+      }
+      const sorted = Object.entries(groups)
+        .map(([mod, d]) => ({ mod, files: d.files, tokens: d.tokens }))
+        .sort((a, b) => b.tokens - a.tokens);
+
+      out.push(`**${totalFiles} indexed files · ${sorted.length} modules · ~${totalTokens} tokens**`, '');
+      out.push('## Modules', '| Module | Files | Tokens |', '|--------|-------|--------|');
+      for (const m of sorted.slice(0, 20)) out.push(`| ${m.mod} | ${m.files} | ~${m.tokens} |`);
+      out.push('');
+    }
+
+    // Hub files + cycle count from the dependency graph (optional).
+    try {
+      const { buildFromCwd } = require('../graph/builder');
+      const { detectCycles } = require('../map/import-graph');
+      const graph = buildFromCwd(cwd);
+      if (graph && graph.reverse && graph.reverse.size) {
+        const hubs = [...graph.reverse.entries()]
+          .map(([f, importers]) => ({ file: path.relative(cwd, f).replace(/\\/g, '/'), in: importers.length }))
+          .filter((h) => h.in > 0)
+          .sort((a, b) => b.in - a.in)
+          .slice(0, 10);
+        if (hubs.length) {
+          out.push('## Hub files (most depended-on)', '| File | Importers |', '|------|-----------|');
+          for (const h of hubs) out.push(`| \`${h.file}\` | ${h.in} |`);
+          out.push('');
+        }
+        let cycleCount = 0;
+        try { cycleCount = detectCycles(graph.forward).length; } catch (_) {}
+        out.push(`**Dependency cycles:** ${cycleCount}` + (cycleCount ? ' _(see import graph)_' : ' — none detected'), '');
+      }
+    } catch (_) { /* graph optional */ }
+
+    // Routes from PROJECT_MAP.md if present.
+    const mapPath = path.join(cwd, 'PROJECT_MAP.md');
+    if (fs.existsSync(mapPath)) {
+      const mc = fs.readFileSync(mapPath, 'utf8');
+      const routeCount = mc.split('\n').filter((l) => l.startsWith('| ') && !l.startsWith('| Method') && !l.startsWith('|---')).length;
+      out.push('## Project map', `Routes detected: ${routeCount} _(use get_map for imports/classes/routes detail)_`, '');
+    } else {
+      out.push('_Run `node gen-project-map.js` for routes / class-hierarchy detail (get_map)._');
+    }
+
+    return out.join('\n');
+  } catch (err) {
+    return `_get_architecture_overview failed: ${err.message}_`;
+  }
+}
+
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview };

package/src/mcp/server.js

@@ -8,17 +8,17 @@
  *
  * Supported methods:
  *   initialize        → serverInfo + capabilities
- *   tools/list        → 11 tool definitions
+ *   tools/list        → 17 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, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '7.25.2',
+  version: '7.27.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -81,6 +81,8 @@ function dispatch(msg, cwd) {
       else if (name === 'sigmap_notify_file_created') text = notifyFileCreated(args, cwd);
       else if (name === 'sigmap_notify_symbol_added') text = notifySymbolAdded(args, cwd);
       else if (name === 'sigmap_notify_file_deleted') text = notifyFileDeleted(args, cwd);
+      else if (name === 'get_diff_context') text = getDiffContext(args, cwd);
+      else if (name === 'get_architecture_overview') text = getArchitectureOverview(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -1,11 +1,11 @@
 'use strict';
 
 /**
- * MCP tool definitions for SigMap (15 tools).
+ * MCP tool definitions for SigMap (17 tools).
  * read_context, search_signatures, get_map, create_checkpoint, get_routing,
  * explain_file, list_modules, query_context, get_impact, get_lines, read_memory,
  * get_callee_signatures, sigmap_notify_file_created, sigmap_notify_symbol_added,
- * sigmap_notify_file_deleted.
+ * sigmap_notify_file_deleted, get_diff_context, get_architecture_overview.
  */
 
 const TOOLS = [
@@ -278,6 +278,44 @@ const TOOLS = [
       required: ['path'],
     },
   },
+  {
+    name: 'get_diff_context',
+    description:
+      'For every changed file in the working tree (or staged, or vs a base ref), return its ' +
+      'current signatures plus blast radius — direct importers, transitive count, and affected ' +
+      'tests/routes — with a risk label. One call gives an agent everything a code review or a ' +
+      'safe edit needs. Lists changed files shell-free (git binary, never a shell).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        base: {
+          type: 'string',
+          description: 'Optional git ref to diff against (e.g. "main"). Returns files changed in `base..HEAD`. Omit for working-tree changes.',
+        },
+        staged: {
+          type: 'boolean',
+          description: 'When true (and no base), report only staged changes (`git diff --cached`).',
+        },
+        depth: {
+          type: 'number',
+          description: 'Blast-radius BFS depth limit (default: 2). Use 0 for unlimited.',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_architecture_overview',
+    description:
+      'A high-level map of the codebase in one call: module breakdown (files/tokens), the most ' +
+      'depended-on "hub" files, the dependency-cycle count, and route totals. Extends get_map — ' +
+      'use it to orient in an unfamiliar repo before drilling in with read_context / query_context.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
 ];
 
 module.exports = { TOOLS };