sigmap 8.5.0 → 8.6.0

package/CHANGELOG.md

@@ -10,6 +10,17 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.6.0] — 2026-07-05
+
+Minor release — **Phase 1 "bank the A": the grounding moat's supporting surface.** Three master-plan items land together: a self-contained, third-party-runnable benchmark harness (G1), installed dependency version pins in the generated context header (D8), and `verify` promoted to a documented flagship command (G2). All zero-dependency, deterministic, and in-boundary.
+
+### Added
+- **Public benchmark harness (#425, PR #426):** new `public-benchmarks/` — a self-contained, third-party-runnable retrieval harness. `repos.csv` (18 real repos pinned to exact commits), `queries.json` (90 natural-language query → expected-file tasks), `run.sh` (shallow-clones the pinned repos, then scores), `score.mjs` (maps each repo with `gen-context.js`, ranks with the **shipped** identifier-aware BM25 ranker `src/retrieval/bm25.js`, reports hit@1/hit@5/MRR), and a methodology `README.md`. Deterministic — pinned commits + a byte-stable map + rank-only math → the same numbers on any machine; no LLM, no API keys, no external deps. Dev-only (excluded from the npm package). Turns the published retrieval numbers from a claim into a third-party-verifiable fact (v9.0 G1).
+- **Version pins in the context header (#425, PR #426):** the generated header now carries a `## versions (installed direct deps)` block of sorted `name@version` pins for installed JS + Python direct dependencies, so agents reading `CLAUDE.md`/`AGENTS.md` ground against what is **actually installed here** (compounds with the G5/D5 verify moat). New `collectVersionPins(cwd)` in `src/verify/lib-index.js` (versions only — no symbol parsing, cheap enough to run per-build); gated by a new `versionPins` config key (default on). Byte-stable given a fixed installed tree (D8).
+
+### Changed
+- **`sigmap verify` — the grounding flagship (#425, PR #426):** `verify` is now a first-class alias of `verify-ai-output` (identical flags, output, and exit codes), with a dedicated flagship section near the top of the README and a `--help` entry. Positions the deterministic grounding guard — the one capability no agentic-grep loop or competitor offers — as the headline (v9.0 G2).
+
 ## [8.5.0] — 2026-07-05
 
 Minor release — **deterministic query expansion (a vocabulary-mismatch recall aid).** The BM25 ranker now bridges common code-domain synonyms/abbreviations so a query for `authentication` can still surface a file whose signatures only say `auth`. Zero-dependency, deterministic. **Honest framing:** measured on the retrieval benchmark, this is **benchmark-neutral** (hit@5 unchanged within the harness's 86.7–87.8% noise band at the shipped weight) — not a hit@5 improvement. The benefit is for real users whose query vocabulary differs from the code, a case the curated benchmark doesn't exercise.

package/README.md

@@ -52,15 +52,15 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 
 **Deterministic and verifiable — the two things an agentic-grep loop can't give you:**
 - **Deterministic** — no LLM calls, no agent loop; the same repo always produces a byte-identical map you can diff, cache, and gate in CI.
-- **Auditable & grounded** — every file and symbol traces to a real line anchor; `sigmap verify-ai-output` flags any AI claim that isn't.
+- **Auditable & grounded** — every file and symbol traces to a real line anchor; `sigmap verify` flags any AI claim that isn't.
 - **Zero dependencies** — `npx sigmap` on any machine; no embeddings, no vector DB, no hosted service, fully offline.
 
 **Proof it pays off** (full benchmark below):
 <!--SM:whyMetrics-->
 - **86.7% hit@5** — right file found in top 5 results (vs 13.6% baseline)
 - **97.0% token reduction** — average across 21 real repos
-- **67.8% task success rate** — up from 10% without context
-- **1.46 prompts per task** — down from 2.84 (48.8% fewer retries)
+- **66.7% task success rate** — up from 10% without context
+- **1.47 prompts per task** — down from 2.84 (48.4% fewer retries)
 <!--/SM:whyMetrics-->
 - **<!--SM:languages-->33<!--/SM:languages--> languages supported** — TypeScript, Python, Go, Rust, Java, R, and more
 - **No vendor lock-in** — works with any AI assistant or local LLM
@@ -69,6 +69,28 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 
 ---
 
+## 🔒 `sigmap verify` — the grounding flagship
+
+The one thing no agentic-grep loop, and no competitor, gives you: **prove an AI answer is anchored to real signatures and line numbers before you trust it.** Deterministic, offline, no LLM — SigMap indexes your repo *plus the libraries actually installed here* and flags every fabricated file, import, symbol, test, or npm script.
+
+```bash
+sigmap verify answer.md                 # ✓ grounded, or a line-by-line list of fabrications
+sigmap verify answer.md --json          # machine-readable report; exits 1 if any issue (CI gate)
+sigmap verify answer.md --report        # standalone red/amber/green HTML report
+```
+
+```text
+[sigmap] ✗ answer.md — 2 issues found
+  fake-file: 1  fake-test-file: 0  fake-import: 0  fake-symbol: 1  fake-npm-script: 0
+
+  L12  [Fake file]    src/auth/session-store.js does not exist
+  L27  [Fake symbol]  authorize() — did you mean authenticate()?
+```
+
+`verify` is the flagship; `verify-ai-output` remains as the full command name. Pair it with `sigmap verify-plan` (check a plan before execution) and the `verify_suggestion` MCP tool (verify AI code against repo + private + installed-library symbols mid-session).
+
+---
+
 ## Replace this with SigMap
 
 | Without SigMap | With SigMap |
@@ -98,13 +120,13 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.5-main (21 repositories, including R language)
-Date      : 2026-07-04
+Benchmark : sigmap-v8.6-main (21 repositories, including R language)
+Date      : 2026-07-05
 
 Hit@5          : 86.7%   (baseline 13.6%  — 6.4× lift)
 Token reduction: 97.0%   (across 21 repos)
-Prompt reduction : 48.8% (2.84 → 1.46 prompts per task)
-Task success   : 67.8%   (baseline 10%)
+Prompt reduction : 48.4% (2.84 → 1.47 prompts per task)
+Task success   : 66.7%   (baseline 10%)
 Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
 ```
 <!--/SM:benchmarkBlock-->

package/gen-context.js

@@ -1498,6 +1498,9 @@ __factories["./src/config/defaults"] = function(module, exports) {
     // Include a compact import dependency map at top of output
     depMap: true,
 
+    // Include a compact `name@version` list of installed direct deps (D8)
+    versionPins: true,
+
     // Include TODO/FIXME/HACK/XXX comments as compact section
     todos: true,
 
@@ -13108,7 +13111,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.5.0',
+    version: '8.6.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -17311,8 +17314,37 @@ __factories["./src/verify/lib-index"] = function(module, exports) {
       .map((l) => `${l.name}@${l.version}`);
   }
 
+  /**
+   * D8: collect `name@version` pins for direct dependencies — versions only, no
+   * symbol extraction, no cache. Cheap enough to run on every context build so
+   * the generated header can ground against what is actually installed (JS +
+   * Python). Deterministic: sorted, then capped.
+   * @param {string} cwd
+   * @param {object} [opts]
+   * @param {number} [opts.limit=40] max pins returned (after sort)
+   * @returns {{ pins: string[], total: number }} pins capped to limit; total = all resolved
+   */
+  function collectVersionPins(cwd, opts = {}) {
+    const limit = Number.isInteger(opts.limit) && opts.limit >= 0 ? opts.limit : 40;
+    const pins = [];
+    for (const dep of directDeps(cwd).slice(0, MAX_DEPS)) {
+      const r = resolveEntry(cwd, dep);
+      if (r && r.version) pins.push(`${dep}@${r.version}`);
+    }
+    const sitePkgs = findSitePackages(cwd);
+    if (sitePkgs.length) {
+      for (const dep of pythonDirectDeps(cwd).slice(0, MAX_DEPS)) {
+        const r = resolvePyEntry(sitePkgs, dep);
+        if (r && r.version) pins.push(`${dep}@${r.version}`);
+      }
+    }
+    pins.sort();
+    return { pins: limit ? pins.slice(0, limit) : pins, total: pins.length };
+  }
+
   module.exports = {
     buildLibraryIndex, extractDtsExports, directDeps, resolveEntry, formatVersionPins,
+    collectVersionPins,
     extractPyExports, pythonDirectDeps, findSitePackages, resolvePyEntry,
   };
   
@@ -17647,7 +17679,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.5.0';
+const VERSION = '8.6.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -18250,6 +18282,23 @@ function formatOutput(fileEntries, cwd, routingEnabled, config, extras) {
     lines.push('');
   }
 
+  // D8: installed direct-dependency version pins — grounds agents against what
+  // is actually installed here (byte-stable given a fixed installed tree).
+  if (!config || config.versionPins !== false) {
+    try {
+      const { collectVersionPins } = requireSourceOrBundled('./src/verify/lib-index');
+      const { pins, total } = collectVersionPins(cwd);
+      if (pins.length) {
+        lines.push('## versions (installed direct deps)');
+        lines.push('```');
+        lines.push(...pins);
+        if (total > pins.length) lines.push(`… +${total - pins.length} more`);
+        lines.push('```');
+        lines.push('');
+      }
+    } catch (_) { /* no/uninstalled deps → skip */ }
+  }
+
   const todoLines = buildTodoSection(fileEntries, cwd, config || {});
   if (todoLines.length) {
     lines.push('## todos');
@@ -19442,9 +19491,10 @@ Usage:
   ${cmd} --impact <file>                   Show every file impacted by changing <file>
   ${cmd} --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
   ${cmd} --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
-  ${cmd} verify-ai-output <answer.md>      Flag fake files/tests/imports/symbols/npm-scripts in an AI answer
-  ${cmd} verify-ai-output <answer.md> --json    Hallucination report as JSON (exits 1 if issues)
-  ${cmd} verify-ai-output <answer.md> --report  Write a standalone HTML report (red/amber/green)
+  ${cmd} verify <answer.md>                Flagship grounding guard — flag fake files/tests/imports/symbols/npm-scripts in an AI answer (alias of verify-ai-output)
+  ${cmd} verify <answer.md> --json         Grounding report as JSON (exits 1 if issues)
+  ${cmd} verify <answer.md> --report       Write a standalone HTML report (red/amber/green)
+  ${cmd} verify-ai-output <answer.md>      Full command name for ${cmd} verify
   ${cmd} conventions                       Extract repo file-naming/export/test conventions (--conflicts, --inject, --report, --fix)
   ${cmd} scaffold "<name>"                 Propose a convention-matched file/dir scaffold (--ext, --threshold, --force, --json)
   ${cmd} verify-plan <plan.md|->           Check a plan vs the live index — files/symbols exist, blast radius, scope (--json)
@@ -21304,7 +21354,10 @@ function main() {
     process.exit(s.ok ? 0 : 1);
   }
 
-  if (args[0] === 'verify-ai-output') {
+  // `sigmap verify` is the flagship alias for `verify-ai-output` — the grounding
+  // guard that proves an AI answer is anchored to real signatures + line anchors.
+  if (args[0] === 'verify-ai-output' || args[0] === 'verify') {
+    const cmdName = args[0];
     const target = args[1];
     const jsonOut = args.includes('--json');
     const reportIdx = args.indexOf('--report');
@@ -21312,7 +21365,7 @@ function main() {
       ? (args[reportIdx + 1] && !args[reportIdx + 1].startsWith('--') ? args[reportIdx + 1] : 'sigmap-verify-report.html')
       : null;
     if (!target || target.startsWith('--')) {
-      console.error('[sigmap] Usage: sigmap verify-ai-output <answer.md> [--json] [--report [out.html]]');
+      console.error(`[sigmap] Usage: sigmap ${cmdName} <answer.md> [--json] [--report [out.html]]`);
       process.exit(1);
     }
     const absTarget = path.resolve(cwd, target);

package/llms-full.txt

@@ -11,20 +11,20 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.5.0 | Benchmark: sigmap-v8.5-main (2026-07-04)
+# Version: 8.6.0 | Benchmark: sigmap-v8.6-main (2026-07-05)
 # 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-v8.5-main, 2026-07-04)
+## Core metrics (benchmark: sigmap-v8.6-main, 2026-07-05)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
 | Retrieval hit@5 | 13.6% (random) | 86.7% (6.4× lift) |
 | Token reduction | — | 97.0% average |
-| Task success proxy | 10% | 67.8% |
-| Prompts per task | 2.84 | 1.46 (48.8% fewer) |
+| Task success proxy | 10% | 66.7% |
+| Prompts per task | 2.84 | 1.47 (48.4% fewer) |
 | Supported languages | — | 33 |
 | MCP tools | — | 18 |
 | npm runtime dependencies | — | 0 |
@@ -99,9 +99,10 @@ sigmap weights --json                    Learned weights as JSON
 sigmap --impact <file>                   Show every file impacted by changing <file>
 sigmap --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
 sigmap --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
-sigmap verify-ai-output <answer.md>      Flag fake files/tests/imports/symbols/npm-scripts in an AI answer
-sigmap verify-ai-output <answer.md> --json    Hallucination report as JSON (exits 1 if issues)
-sigmap verify-ai-output <answer.md> --report  Write a standalone HTML report (red/amber/green)
+sigmap verify <answer.md>                Flagship grounding guard — flag fake files/tests/imports/symbols/npm-scripts in an AI answer (alias of verify-ai-output)
+sigmap verify <answer.md> --json         Grounding report as JSON (exits 1 if issues)
+sigmap verify <answer.md> --report       Write a standalone HTML report (red/amber/green)
+sigmap verify-ai-output <answer.md>      Full command name for gen-context verify
 sigmap conventions                       Extract repo file-naming/export/test conventions (--conflicts, --inject, --report, --fix)
 sigmap scaffold "<name>"                 Propose a convention-matched file/dir scaffold (--ext, --threshold, --force, --json)
 sigmap verify-plan <plan.md|->           Check a plan vs the live index — files/symbols exist, blast radius, scope (--json)
@@ -310,6 +311,7 @@ format = default
 tracking = false
 mcp = {"autoRegister":true}
 depMap = true
+versionPins = true
 todos = true
 changes = true
 changesCommits = 10

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.5.0 | Benchmark: sigmap-v8.5-main (2026-07-04)
+# Version: 8.6.0 | Benchmark: sigmap-v8.6-main (2026-07-05)
 # 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
 
@@ -23,12 +23,12 @@ 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-v8.5-main, 2026-07-04)
+## Core metrics (benchmark: sigmap-v8.6-main, 2026-07-05)
 
 - hit@5 retrieval: 86.7% vs 13.6% random baseline (6.4× lift)
 - Token reduction: 97.0% average across benchmark repos
-- Task success: 67.8% vs 10% without SigMap
-- Prompts per task: 1.46 vs 2.84 baseline (48.8% fewer)
+- Task success: 66.7% vs 10% without SigMap
+- Prompts per task: 1.47 vs 2.84 baseline (48.4% fewer)
 - Languages: 33 supported · MCP tools: 18
 - Dependencies: zero npm runtime dependencies · fully offline
 

package/package.json

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

package/src/config/defaults.js

@@ -114,6 +114,9 @@ const DEFAULTS = {
   // Include a compact import dependency map at top of output
   depMap: true,
 
+  // Include a compact `name@version` list of installed direct deps (D8)
+  versionPins: true,
+
   // Include TODO/FIXME/HACK/XXX comments as compact section
   todos: true,
 

package/src/mcp/server.js

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

package/src/verify/lib-index.js

@@ -298,7 +298,36 @@ function formatVersionPins(libraries) {
     .map((l) => `${l.name}@${l.version}`);
 }
 
+/**
+ * D8: collect `name@version` pins for direct dependencies — versions only, no
+ * symbol extraction, no cache. Cheap enough to run on every context build so
+ * the generated header can ground against what is actually installed (JS +
+ * Python). Deterministic: sorted, then capped.
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {number} [opts.limit=40] max pins returned (after sort)
+ * @returns {{ pins: string[], total: number }} pins capped to limit; total = all resolved
+ */
+function collectVersionPins(cwd, opts = {}) {
+  const limit = Number.isInteger(opts.limit) && opts.limit >= 0 ? opts.limit : 40;
+  const pins = [];
+  for (const dep of directDeps(cwd).slice(0, MAX_DEPS)) {
+    const r = resolveEntry(cwd, dep);
+    if (r && r.version) pins.push(`${dep}@${r.version}`);
+  }
+  const sitePkgs = findSitePackages(cwd);
+  if (sitePkgs.length) {
+    for (const dep of pythonDirectDeps(cwd).slice(0, MAX_DEPS)) {
+      const r = resolvePyEntry(sitePkgs, dep);
+      if (r && r.version) pins.push(`${dep}@${r.version}`);
+    }
+  }
+  pins.sort();
+  return { pins: limit ? pins.slice(0, limit) : pins, total: pins.length };
+}
+
 module.exports = {
   buildLibraryIndex, extractDtsExports, directDeps, resolveEntry, formatVersionPins,
+  collectVersionPins,
   extractPyExports, pythonDirectDeps, findSitePackages, resolvePyEntry,
 };