sigmap 6.7.0 → 6.9.0

package/AGENTS.md

@@ -56,13 +56,6 @@ Use this marker block for all appendable context files:
 | To query by topic | `sigmap --query "<topic>"` |
 
 Always run `sigmap ask` or `sigmap --query` before searching for files relevant to a task.
-## changes (last 5 commits — 8 minutes ago)
-```
-src/plan/planner.js                           +createPlan
-src/retrieval/ranker.js                       +_computePenalty  +_computeHubs  +_isHub  ~scoreFile
-src/session/memory.js                         +sessionPath  +loadSession  +saveSession  +mergeSessionContext
-```
-
 ## packages
 
 ### packages/cli/index.js
@@ -580,11 +573,6 @@ function exportWeights(cwd, outputPath)
 function importWeights(cwd, importPath, replace)
 ```
 
-### src/config/defaults.js
-```
-module.exports = { DEFAULTS }
-```
-
 ### src/config/loader.js
 ```
 module.exports = { loadConfig, loadBaseConfig }
@@ -595,37 +583,6 @@ function loadConfig(cwd) → object
 function deepClone(obj)
 ```
 
-### src/discovery/source-root-registry.js
-```
-module.exports = { REGISTRY }
-```
-
-### src/discovery/source-root-resolver.js
-```
-module.exports = { resolveSourceRoots }
-function resolveSourceRoots(cwd, opts = {})
-function _detectMonorepo(cwd)
-function _enumerateCandidates(cwd, isMonorepo, ignorePatterns, excludeList)
-function _applySpecialRules(scored, cwd, primaryFw, fwEntry, frameworks)
-function _dedupeNested(scored)
-function _computeConfidence(frameworks, languages, scoredCount)
-```
-
-### src/discovery/language-detector.js
-```
-module.exports = { detectLanguages }
-function detectLanguages(cwd)
-function _walkDepth(dir, depth, extCount)
-```
-
-### src/discovery/source-root-scorer.js
-```
-module.exports = { scoreCandidate, getRecentlyChangedDirs, ROOT_ENTRYPOINTS }
-function getRecentlyChangedDirs(cwd)
-function scoreCandidate(dirName, fullPath, context)
-function _countSourceFiles(dir, depth)
-```
-
 ### src/discovery/framework-detector.js
 ```
 module.exports = { detectFrameworks }
@@ -636,6 +593,13 @@ function _existsAnywhere(cwd, filename, maxDepth)
 function _walkFind(dir, name, depth)
 ```
 
+### src/discovery/language-detector.js
+```
+module.exports = { detectLanguages }
+function detectLanguages(cwd)
+function _walkDepth(dir, depth, extCount)
+```
+
 ### src/discovery/sigmapignore.js
 ```
 module.exports = { loadIgnorePatterns, matchesIgnorePattern }
@@ -643,19 +607,9 @@ function loadIgnorePatterns(cwd)
 function matchesIgnorePattern(dirName, patterns)
 ```
 
-### src/plan/planner.js
-```
-module.exports = { createPlan }
-function createPlan(goal, cwd, config)
-```
-
-### src/mcp/server.js
+### src/discovery/source-root-registry.js
 ```
-module.exports = { start }
-function respond(id, result)
-function respondError(id, code, message)
-function dispatch(msg, cwd)
-function start(cwd)
+module.exports = { REGISTRY }
 ```
 
 ### src/retrieval/ranker.js
@@ -673,6 +627,12 @@ function formatRankJSON(results, query) → object
 function detectIntent(query)
 ```
 
+### src/plan/planner.js
+```
+module.exports = { createPlan }
+function createPlan(goal, cwd, config)
+```
+
 ### src/session/memory.js
 ```
 module.exports = { loadSession, saveSession, mergeSessionContext, clearSession }
@@ -682,3 +642,36 @@ function saveSession(cwd, { intent, topFiles, query })
 function mergeSessionContext(scores, session, currentIntent)
 function clearSession(cwd)
 ```
+
+### src/config/defaults.js
+```
+module.exports = { DEFAULTS }
+```
+
+### src/discovery/source-root-scorer.js
+```
+module.exports = { scoreCandidate, getRecentlyChangedDirs, ROOT_ENTRYPOINTS, JVM_PATH_PATTERN }
+function getRecentlyChangedDirs(cwd)
+function scoreCandidate(dirName, fullPath, context)
+function _countSourceFiles(dir, depth)
+```
+
+### src/discovery/source-root-resolver.js
+```
+module.exports = { resolveSourceRoots }
+function resolveSourceRoots(cwd, opts = {})
+function _detectMonorepo(cwd)
+function _enumerateCandidates(cwd, isMonorepo, ignorePatterns, excludeList)
+function _applySpecialRules(scored, cwd, primaryFw, fwEntry, frameworks)
+function _dedupeNested(scored)
+function _computeConfidence(frameworks, languages, scoredCount)
+```
+
+### src/mcp/server.js
+```
+module.exports = { start }
+function respond(id, result)
+function respondError(id, code, message)
+function dispatch(msg, cwd)
+function start(cwd)
+```

package/CHANGELOG.md

@@ -10,6 +10,26 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [6.9.0] — 2026-05-03
+
+### Added
+
+- **Task metadata for segmentation** — All 18 benchmark repositories now tagged with language, repo type (framework/library/tool/application), and size class (small/medium/large) to enable segmented benchmark analysis.
+- **Benchmark methodology documentation** — Comprehensive guide explaining what SigMap measures (retrieval accuracy, task success, prompt reduction, token reduction), why these metrics matter, and how the 90-task test set was selected and evaluated.
+- **Answer usefulness evaluation** — New metric tracking whether retrieved context actually enabled correct answers, scored in three tiers: fully-useful (rank 1), partially-useful (ranks 2-5), not-useful (not retrieved). Complements task success proxy with granular answer quality assessment.
+
+---
+
+## [6.8.0] — 2026-05-03
+
+### Added
+
+- **Session memory with 4-hour TTL** — Store intent, top-ranked files, and last query in `.context/session.json` to enable context carry-forward across multiple `sigmap ask` calls. Session expires after 4 hours, preventing stale context fixation.
+- **`sigmap ask --followup` flag** — Carry context from previous session with intent-aware boosting: +0.2 score for same intent, +0.1 for topic switch (different intent). Never reduces scores, only adds contextual signals.
+- **`sigmap plan "<goal>"` command** — Analyze change impact before editing: rank files by confidence level (inspect first vs. likely to change), compute impact radius using dependency graph, identify affected tests. Outputs human-readable table or JSON.
+
+---
+
 ## [6.7.0] — 2026-05-03
 
 ### Added

package/README.md

@@ -52,7 +52,7 @@ Works with Copilot, Claude, Cursor, Windsurf, and any LLM.
 
 | Without SigMap | With SigMap |
 |---|---|
-| ❌ Guessing which files are relevant | ✅ Right file in context — 81% of the time |
+| ❌ Guessing which files are relevant | ✅ Right file in context — 80% of the time |
 | ❌ Sending the full repo to your AI | ✅ Minimal context — only what matters |
 | ❌ Embeddings / vector DB required | ✅ Grounded answers, no infra needed |
 
@@ -76,7 +76,7 @@ Ask → Rank → Context → Validate → Judge → Learn
 ## Benchmark
 
 ```
-Benchmark : sigmap-v6.6-main
+Benchmark : sigmap-v6.8-main
 Date      : 2026-04-30
 
 Hit@5          : 80.0%   (baseline 13.6%  — 5.9× lift)

package/gen-context.js

@@ -5387,7 +5387,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '6.7.0',
+  version: '6.9.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -7855,7 +7855,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '6.7.0';
+const VERSION = '6.9.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -9900,10 +9900,19 @@ function main() {
 
   // v4.2: `sigmap ask "<query>"` — unified pipeline
   if (args[0] === 'ask') {
-    const query = args[1];
+    // v6.8: Handle --followup flag which may appear before or after query
+    let query = args[1];
+    if (query === '--followup' && args[2]) {
+      query = args[2];
+    } else if (query && query.startsWith('--') && query !== '--json' && query !== '--model') {
+      // Allow --json and --model but not other flags as query
+      console.error('[sigmap] Usage: sigmap ask "<query>" [--followup] [--json] [--model <name>]');
+      console.error('  Example: sigmap ask "fix the login bug" --followup');
+      process.exit(1);
+    }
     if (!query || query.startsWith('--')) {
-      console.error('[sigmap] Usage: sigmap ask "<query>"');
-      console.error('  Example: sigmap ask "fix the login bug"');
+      console.error('[sigmap] Usage: sigmap ask "<query>" [--followup] [--json] [--model <name>]');
+      console.error('  Example: sigmap ask "fix the login bug" --followup');
       process.exit(1);
     }
 

package/package.json

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

package/packages/cli/package.json

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

package/packages/core/package.json

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

package/src/eval/usefulness-scorer.js

@@ -0,0 +1,66 @@
+'use strict';
+
+module.exports = { scoreUsefulness, computeUsefulnessStats };
+
+/**
+ * Score answer usefulness based on:
+ * 1. Whether right file was retrieved (retrieval hit)
+ * 2. Whether retrieved context covered the answer (coverage)
+ * 3. Confidence in answer quality (from ranking score)
+ */
+function scoreUsefulness(taskResult, rankingScore) {
+  const { hitRank } = taskResult;
+
+  // Tier 1: File not retrieved — context cannot be useful
+  if (hitRank === -1 || hitRank > 5) {
+    return {
+      tier: 'not-useful',
+      score: 0.0,
+      reason: 'expected file not in top 5'
+    };
+  }
+
+  // Tier 2: File retrieved but not top ranking — partially useful
+  if (hitRank > 1) {
+    return {
+      tier: 'partially-useful',
+      score: rankingScore * 0.5,  // Partial usefulness
+      reason: `file ranked #${hitRank}`
+    };
+  }
+
+  // Tier 3: File at top of ranking — fully useful
+  return {
+    tier: 'fully-useful',
+    score: rankingScore,  // Full usefulness
+    reason: 'file ranked first'
+  };
+}
+
+function computeUsefulnessStats(taskResults) {
+  const tiers = {
+    'fully-useful': 0,
+    'partially-useful': 0,
+    'not-useful': 0
+  };
+
+  let totalScore = 0;
+  let count = 0;
+
+  taskResults.forEach(result => {
+    const usefulness = scoreUsefulness(result, result.rankingScore || 1.0);
+    tiers[usefulness.tier]++;
+    totalScore += usefulness.score;
+    count++;
+  });
+
+  return {
+    fully_useful: tiers['fully-useful'],
+    partially_useful: tiers['partially-useful'],
+    not_useful: tiers['not-useful'],
+    fully_useful_pct: count > 0 ? (tiers['fully-useful'] / count * 100).toFixed(1) : 0,
+    partially_useful_pct: count > 0 ? (tiers['partially-useful'] / count * 100).toFixed(1) : 0,
+    not_useful_pct: count > 0 ? (tiers['not-useful'] / count * 100).toFixed(1) : 0,
+    average_usefulness_score: count > 0 ? (totalScore / count).toFixed(3) : 0
+  };
+}

package/src/mcp/server.js

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