sigmap 5.1.0 → 5.3.0

package/AGENTS.md

@@ -12,27 +12,62 @@ Use this marker block for all appendable context files:
 ## Auto-generated signatures
 <!-- Updated by gen-context.js -->
 You are a coding assistant with full knowledge of this codebase.
-Below are the code signatures extracted by SigMap v5.1.0 on 2026-04-16T21:33:38.411Z.
+Below are the code signatures extracted by SigMap v5.2.0 on 2026-04-16T23:13:56.540Z.
 
 Use these signatures to answer questions about the code accurately.
 
 ## Code Signatures
 
-<!-- Generated by SigMap gen-context.js v5.1.0 -->
+<!-- Generated by SigMap gen-context.js v5.2.0 -->
 <!-- DO NOT EDIT below the marker line — run gen-context.js to regenerate -->
 
 # Code signatures
 
-## changes (last 5 commits — 16 minutes ago)
+## changes (last 5 commits — 46 minutes ago)
 ```
 src/config/loader.js                          +loadBaseConfig  ~loadConfig  ~deepClone
 src/format/dashboard.js                       ~computeExtractorCoverage  ~readBenchmarkTrend
-src/judge/judge-engine.js                     +tokenize  +groundedness  +judge
-src/retrieval/ranker.js                       +detectIntent  ~formatRankJSON
+src/judge/judge-engine.js                     +tokenize  +groundedness  +extractContextFiles  +judge
+src/learning/weights.js                       +weightsPath  +clampMultiplier  +normalizeFile  +sanitizeWeights
+src/mcp/handlers.js                           ~queryContext  ~getImpact
+src/retrieval/ranker.js                       ~scoreFile  ~rank
+packages/core/index.js                        ~extract
 ```
 
 ## packages
 
+### packages/core/README.md
+```
+h1 sigmap-core
+h2 Installation
+h2 Quick start
+h2 API reference
+h3 `extract(src, language)` → `string[]`
+h3 `rank(query, sigIndex, opts?)` → `Result[]`
+h3 `buildSigIndex(cwd)` → `Map<string, string[]>`
+h3 `scan(sigs, filePath)` → `{ safe: string[], redacted: boolean }`
+h3 `score(cwd)` → `HealthResult`
+h2 Migration from v2.3 and earlier
+h2 v3.0 — Multi-Adapter Architecture (released)
+h2 Zero dependencies
+code-fence bash
+code-fence plain
+code-fence js
+code-fence ---
+```
+
+### packages/core/index.js
+```
+module.exports = { extract, rank, buildSigIndex, scan, score, adapt }
+function _resolveExtractor(language)
+function extract(src, language) → string[]
+function rank(query, sigIndex, opts) → { file: string, score: nu
+function buildSigIndex(cwd) → Map<string, string[]>
+function scan(sigs, filePath) → { safe: string[], redacte
+function score(cwd) → { * score: number, * grad
+function adapt(context, adapterName, opts = {}) → string
+```
+
 ### packages/adapters/claude.js
 ```
 module.exports = { name, format, outputPath, write }
@@ -115,38 +150,6 @@ module.exports = { CLI_ENTRY, run }
 function run(argv, cwd) → void
 ```
 
-### packages/core/README.md
-```
-h1 sigmap-core
-h2 Installation
-h2 Quick start
-h2 API reference
-h3 `extract(src, language)` → `string[]`
-h3 `rank(query, sigIndex, opts?)` → `Result[]`
-h3 `buildSigIndex(cwd)` → `Map<string, string[]>`
-h3 `scan(sigs, filePath)` → `{ safe: string[], redacted: boolean }`
-h3 `score(cwd)` → `HealthResult`
-h2 Migration from v2.3 and earlier
-h2 v3.0 — Multi-Adapter Architecture (released)
-h2 Zero dependencies
-code-fence bash
-code-fence plain
-code-fence js
-code-fence ---
-```
-
-### packages/core/index.js
-```
-module.exports = { extract, rank, buildSigIndex, scan, score, adapt }
-function _resolveExtractor(language)
-function extract(src, language) → string[]
-function rank(query, sigIndex, opts) → { file: string, score: nu
-function buildSigIndex(cwd) → Map<string, string[]>
-function scan(sigs, filePath) → { safe: string[], redacte
-function score(cwd) → { * score: number, * grad
-function adapt(context, adapterName, opts = {}) → string
-```
-
 ## src
 
 ### src/config/loader.js
@@ -183,9 +186,39 @@ function renderHistoryCharts(cwd, health)
 module.exports = { groundedness, judge }
 function tokenize(text)
 function groundedness(response, context)
+function extractContextFiles(context, cwd)
 function judge(response, context, opts = {})
 ```
 
+### src/learning/weights.js
+```
+module.exports = { BASELINE, DECAY, MAX_MULT, MIN_MULT, weightsPath, clampMultiplier, normalizeFile, loadWeights, saveWeights, updateWeights, boostFiles, penalizeFiles, resetWeights }
+function weightsPath(cwd)
+function clampMultiplier(value)
+function normalizeFile(cwd, filePath)
+function sanitizeWeights(cwd, weights)
+function loadWeights(cwd)
+function saveWeights(cwd, weights)
+function updateWeights(cwd, opts = {})
+function boostFiles(cwd, files, amount = 0.15)
+function penalizeFiles(cwd, files, amount = 0.10)
+function resetWeights(cwd)
+```
+
+### src/mcp/handlers.js
+```
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact }
+function readContext(args, cwd)
+function searchSignatures(args, cwd)
+function getMap(args, cwd)
+function createCheckpoint(args, cwd)
+function getRouting(args, cwd)
+function explainFile(args, cwd)
+function listModules(args, cwd)
+function queryContext(args, cwd)
+function getImpact(args, cwd)
+```
+
 ### src/mcp/server.js
 ```
 module.exports = { start }
@@ -625,20 +658,6 @@ function shouldSkipFile(rel)
 function analyze(files, cwd)
 ```
 
-### src/mcp/handlers.js
-```
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact }
-function readContext(args, cwd)
-function searchSignatures(args, cwd)
-function getMap(args, cwd)
-function createCheckpoint(args, cwd)
-function getRouting(args, cwd)
-function explainFile(args, cwd)
-function listModules(args, cwd)
-function queryContext(args, cwd)
-function getImpact(args, cwd)
-```
-
 ### src/mcp/tools.js
 ```
 module.exports = { TOOLS }

package/CHANGELOG.md

@@ -10,6 +10,34 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [5.3.0] — 2026-04-17
+
+### Added
+
+- **MCP auto-wire: Windsurf** — `sigmap --setup` now registers the MCP server in `.windsurf/mcp.json` (project-level) and `~/.codeium/windsurf/mcp_config.json` (global) using the standard `mcpServers` shape.
+- **MCP auto-wire: Zed** — `sigmap --setup` now registers a context server in `~/.config/zed/settings.json` using Zed's `context_servers` shape (`command.path` / `command.args`).
+- **Updated `--setup` snippet** — help output now prints manual config snippets for all four tools: Claude, Cursor, Windsurf, and Zed.
+
+### Changed
+
+- `registerMcp()` skips each target when the file does not exist and never overwrites an already-registered `sigmap` entry (idempotent).
+
+---
+
+## [5.2.0] — 2026-04-17
+
+### Added
+
+- **Learning engine** — new local-only weight store at `.context/weights.json` with path-normalized per-file multipliers, clamp safety (`0.30..3.00`), and decay on every non-reset mutation.
+- **`sigmap learn`** — manually boost or penalize ranked files with `--good <files...>`, `--bad <files...>`, and `--reset`. Invalid or out-of-repo paths are skipped with warnings; the command exits non-zero when no valid targets remain.
+- **`sigmap weights [--json]`** — explainability view for learned ranking multipliers. Human mode prints a compact table and reset hint; JSON mode emits the raw learned-weight object.
+- **Opt-in judge learning** — `sigmap judge --response <file> --context <file> --learn` now extracts file headings from query/generated context files and applies small boosts or penalties when groundedness is confidently high or low.
+
+### Changed
+
+- **Ranker learned weighting** — `rank(query, sigIndex, { cwd })` now loads `.context/weights.json` and multiplies non-empty-query scores by learned file multipliers. Empty-query fallback ordering is unchanged.
+- **Learning-aware rank call sites** — `sigmap ask`, `sigmap --query`, `sigmap validate --query`, and MCP `query_context` now pass `cwd` into the ranker so learned weights apply consistently across CLI and MCP flows.
+
 ## [5.1.0] — 2026-04-16
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@
 </div>
 
 <div align="center">
-<img src="docs/impact-banner.svg" alt="SigMap — 6× better answers, 97% fewer tokens, 2× fewer prompts" width="760" />
+<img src="docs/impact-banner.svg" alt="SigMap — grounded AI coding context with fewer prompts and smaller context windows" width="760" />
 </div>
 
 ```sh
@@ -21,11 +21,28 @@ npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again
 
 **What you get in ~10 seconds**
 - A compact signature map of your codebase
-- The right file in context far more often (84.4% hit@5 vs 13.6% random)
-- Fewer retries (1.59 vs 2.84 prompts per task)
+- The right file in context far more often (78.9% hit@5 vs 13.6% random)
+- Fewer retries (1.69 vs 2.84 prompts per task)
 - Far smaller context (~2K–4K tokens instead of ~80K)
 
-> Latest: **v4.1.0** — Smart Budget. Token budget now auto-scales to your repo size, targeting 80% source-file coverage by default. No config change needed — it just works.
+> Latest: **v5.3.0** — Learning engine + workflow-first release. Use `ask`, `validate`, `judge`, `learn`, `weights`, `compare`, and `share` on top of the core signature pipeline.
+
+**What is new in v5.2**
+- `sigmap ask` creates task-focused context in one step
+- `sigmap validate` checks config health and query coverage
+- `sigmap judge` scores groundedness against the supplied context
+- `sigmap learn` and `sigmap weights` add safe local-only ranking feedback
+- `node scripts/run-benchmark-matrix.mjs --save --skip-clone` now writes an HTML benchmark dashboard
+
+**Daily workflow**
+
+```bash
+npx sigmap
+sigmap ask "explain the auth flow"
+sigmap validate --query "auth login token"
+sigmap judge --response response.txt --context .context/query-context.md
+sigmap weights
+```
 
 <div align="center">
 <img src="demo.gif" alt="SigMap demo — reducing 80K tokens to 4K in under 10 seconds" width="760" />
@@ -61,11 +78,11 @@ npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again
 
 | | Without SigMap | With SigMap |
 |---|:---:|:---:|
-| Task success | 10% | **59%** |
-| Prompts per task | 2.84 | **1.59** |
+| Task success | 10% | **52.2%** |
+| Prompts per task | 2.84 | **1.69** |
 | Tokens per session | ~80,000 | **~2,000** |
-| Right file found | 13.6% | **84.4%** |
-| Hallucination risk | 92% | **0%** |
+| Right file found | 13.6% | **78.9%** |
+| Hidden-symbol risk | 74.7% | **context surfaced locally** |
 
 Measured on 90 coding tasks across 18 real public repos. Full methodology and raw benchmark pages are linked below.
 
@@ -82,7 +99,7 @@ Measured on 90 coding tasks across 18 real public repos. Full methodology and ra
 | [Standalone binaries](docs/readmes/binaries.md) | macOS, Linux, Windows — no Node required |
 | [VS Code extension](#-vs-code-extension) | Status bar, stale alerts, commands |
 | [JetBrains plugin](#-jetbrains-plugin) | IntelliJ IDEA, WebStorm, PyCharm support |
-| [Languages supported](#-languages-supported) | 25 languages |
+| [Languages supported](#-languages-supported) | 29 languages |
 | [Context strategies](#-context-strategies) | full / per-module / hot-cold |
 | [MCP server](#-mcp-server) | 8 on-demand tools |
 | [CLI reference](#-cli-reference) | All flags |
@@ -105,7 +122,7 @@ SigMap scans your source files and extracts only the **function and class signat
 Your codebase
     │
     ▼
-sigmap ─────────► extracts signatures from 25 languages
+sigmap ─────────► extracts signatures from 29 languages
     │
     ▼
 .github/copilot-instructions.md   ◄── auto-read by Copilot / Claude / Cursor
@@ -126,7 +143,7 @@ AI agent session starts with full context
 | **SigMap signatures** | **~4,000** | **95%** |
 | SigMap + MCP (`hot-cold`) | ~200 | **99.75%** |
 
-> **97% fewer tokens. The same codebase understanding.**
+> **98.1% fewer tokens in the latest saved benchmark snapshot.**
 
 ### Benchmark: real-world repos
 
@@ -153,7 +170,7 @@ Reproduced with `node scripts/run-benchmark.mjs` on public repos:
 | fastify | JavaScript | 54.4K | 2.6K | **95.3%** |
 | fastapi | Python | 178.4K | 5.2K | **97.1%** |
 
-**Average: 97.6% reduction across 18 repos (16 languages).** See [`benchmarks/reports/token-reduction.md`](benchmarks/reports/token-reduction.md) or reproduce with `node scripts/run-benchmark.mjs`.
+**Average: 97.6% reduction across 18 repos (16 languages).** See [`benchmarks/reports/token-reduction.md`](benchmarks/reports/token-reduction.md), open `benchmarks/reports/benchmark-report.html` after a matrix run, or reproduce with `node scripts/run-benchmark.mjs`.
 
 ---
 
@@ -503,12 +520,12 @@ Compatible with **IntelliJ IDEA 2024.1+** (Community & Ultimate), **WebStorm**,
 
 ## 🌐 Languages supported
 
-> 25 languages. All implemented with zero external dependencies — pure regex + Node built-ins.
+> 29 languages and formats. All implemented with zero external dependencies — pure regex + Node built-ins.
 >
 > Also includes lightweight config/doc extraction for `.toml`, `.properties`, `.xml`, and `.md` to improve real-repo coverage beyond source-code files.
 
 <details>
-<summary><strong>Show all 25 languages</strong></summary>
+<summary><strong>Show all 29 languages</strong></summary>
 
 | Language | Extensions | Extracts |
 |---|---|---|
@@ -737,7 +754,7 @@ Copy `gen-context.config.json.example` to `gen-context.config.json`:
 - **`secretScan`** — redact secrets (AWS keys, tokens, etc.) from output
 - **`strategy`** — output mode: `full` (default) | `per-module` | `hot-cold`
 
-**Token budget (v4.1.0 — auto-scaling):**
+**Token budget (auto-scaling):**
 
 | Key | Default | Description |
 |---|---|---|
@@ -788,13 +805,13 @@ If `output` is omitted, the default `.github/copilot-instructions.md` is used.
 
 ## 📊 Observability
 
-### Coverage score (v4.0)
+### Coverage score
 
 Every run now prints a coverage line alongside token reduction:
 
 ```
 ───────────────────────────────────────────
- SigMap v4.1.0
+ SigMap v5.3.0
  Files scanned  : 76
  Symbols found  : 332
  Token reduction: 94%  (65,227 → 4,103)
@@ -813,7 +830,7 @@ sigmap --report
 
 ```
 [sigmap] report:
-  version         : 4.1.0
+  version         : 5.3.0
   files processed : 76
   reduction       : 93.7%
   coverage        : A (97%)  — 76 of 78 source files included
@@ -857,7 +874,7 @@ sigmap --health --json
 Every output file now carries a metadata line so you can inspect freshness at a glance:
 
 ```
-<!-- sigmap: version=4.0.0 confidence=HIGH coverage=97% dropped=2 commit=8540612 -->
+<!-- sigmap: version=5.3.0 confidence=HIGH coverage=97% dropped=2 commit=8540612 -->
 ```
 
 ### Diff risk score