sigmap 8.28.1 → 8.30.0

package/src/retrieval/ranker.js

@@ -19,7 +19,7 @@
 
 const { loadWeights } = require('../learning/weights');
 const { tokenize, STOP_WORDS } = require('./tokenizer');
-const { bm25rank } = require('./bm25');
+const { bm25rank, MODULE_DOC_RE } = require('./bm25');
 
 // ---------------------------------------------------------------------------
 // Default weights
@@ -43,17 +43,28 @@ const GRAPH_BOOST_AMOUNTS = {
 // Max additive prior for import-graph centrality (opt-in retrieval.centralityBlend)
 const CENTRALITY_BLEND_WEIGHT = 0.3;
 
-// Intent-specific weight adjustments
-const INTENT_WEIGHTS = {
-  search:     DEFAULT_WEIGHTS,
-  debug:      { ...DEFAULT_WEIGHTS, exactToken: 1.2, pathMatch: 0.6 },
-  explain:    { ...DEFAULT_WEIGHTS, symbolMatch: 0.8, pathMatch: 0.9 },
-  refactor:   { ...DEFAULT_WEIGHTS, symbolMatch: 0.9, exactToken: 0.8 },
-  review:     { ...DEFAULT_WEIGHTS, pathMatch: 1.0, exactToken: 0.9 },
-  test:       { ...DEFAULT_WEIGHTS, exactToken: 0.7, symbolMatch: 0.4 },
-  integrate:  { ...DEFAULT_WEIGHTS, graphBoost: 0.7, pathMatch: 1.1 },
-  navigate:   { ...DEFAULT_WEIGHTS, pathMatch: 1.2, exactToken: 0.9 },
-};
+// Per-intent weight profiles were removed in favour of a single weight set.
+// They were provably inert: scoreFile's score was discarded by rank(), so the
+// profiles only ever reached the explain table. Once the signal WAS wired into
+// the score (see SIGNAL_BLEND below), a sweep over the leak-free hard corpus
+// showed intent-specific profiles produced byte-identical metrics to the flat
+// DEFAULT_WEIGHTS at every blend value — so they earn nothing and are gone.
+// `detectIntent` is retained: it is still reported to the user and is the right
+// hook for shaping OUTPUT depth later.
+
+// How much the weighted keyword/symbol/path signal modulates the BM25 base.
+// Multiplicative and bounded, so it can only reorder files that already match —
+// it can never lift a zero-BM25 file into the results. Tuned on the leak-free
+// corpus: 0.5 gave hit@5 50.0% -> 56.7% and MRR 0.419 -> 0.447; higher values
+// held hit@5 but degraded MRR.
+const SIGNAL_BLEND = 0.5;
+
+// TRIED AND REJECTED: a same-line co-occurrence bonus, on the theory that a file
+// declaring `parseAuthToken` should outrank one mentioning `parseAuth` and
+// `token` on separate lines. Swept 0.15-1.0: hit@5 did not move on either the
+// 90-task authored corpus or the 32-task mined one, and MRR degraded
+// monotonically as the weight rose. Signatures are short and dense enough that
+// BM25's bag already captures this. Not reinstated without new evidence.
 
 // Penalty multipliers for negative signals
 const PENALTY_SIGNALS = {
@@ -61,14 +72,69 @@ const PENALTY_SIGNALS = {
   generatedCode: 0.3,    // dist/build/.next in path
   docsFile:      0.2,    // docs/doc/README in path
   nodeModules:   0.0,    // node_modules (zero score)
+  dataHolder:    0.3,    // generated POJO/entity: almost entirely accessors
 };
 
-function _computePenalty(filePath) {
+// A file whose members are overwhelmingly trivial accessors is a data holder,
+// not logic. Path-based detection cannot see these: generated JPA/MyBatis
+// entities live in ordinary source trees. They match a query on any column
+// name they happen to carry (`getNote`/`setNote` matches "note" as strongly as
+// the service that actually implements order notes), so on an entity-heavy
+// repo they crowd real code out of the top results.
+const ACCESSOR_RE = /^\s*(get|set|is)[A-Z]\w*\s*\(/;
+const DATA_HOLDER_RATIO = 0.8;
+const DATA_HOLDER_MIN_MEMBERS = 6;
+
+// Query terms that mean the penalised category IS the target. Read from the
+// query tokens directly, NOT via detectIntent: that classifier is first-match-
+// wins over its pattern object, and `debug` precedes `test`, so "fix the failing
+// test" classifies as debug and never reaches the test branch.
+const WANTS_TESTS = new Set(['test', 'tests', 'spec', 'specs', 'unit', 'integration', 'e2e', 'assertion', 'assert', 'mock', 'fixture', 'coverage', 'testing']);
+const WANTS_DOCS = new Set(['doc', 'docs', 'documentation', 'readme', 'changelog', 'guide', 'tutorial']);
+const WANTS_MODELS = new Set(['entity', 'entities', 'model', 'models', 'pojo', 'dto', 'bean', 'getter', 'getters', 'setter', 'setters', 'accessor', 'accessors', 'field', 'fields', 'column', 'columns', 'schema']);
+
+/** Which penalised categories the query is explicitly asking for. */
+function _queryWants(queryTokens) {
+  const wants = { tests: false, docs: false, models: false };
+  for (const t of queryTokens || []) {
+    if (WANTS_TESTS.has(t)) wants.tests = true;
+    if (WANTS_DOCS.has(t)) wants.docs = true;
+    if (WANTS_MODELS.has(t)) wants.models = true;
+  }
+  return wants;
+}
+
+/**
+ * True when a file's members are overwhelmingly trivial accessors — a generated
+ * entity or POJO rather than logic. Type declarations are excluded from the
+ * ratio so a small class is not misjudged by its own `class X` line.
+ */
+function _isDataHolder(sigs) {
+  if (!Array.isArray(sigs)) return false;
+  const members = sigs.filter((line) => /^\s/.test(line) || !/^(class|interface|enum|struct|function|module\.exports)\b/.test(line));
+  if (members.length < DATA_HOLDER_MIN_MEMBERS) return false;
+  const accessors = members.filter((line) => ACCESSOR_RE.test(line)).length;
+  return accessors / members.length >= DATA_HOLDER_RATIO;
+}
+
+function _computePenalty(filePath, wants, sigs) {
   const pathLower = filePath.toLowerCase();
   if (pathLower.includes('node_modules')) return PENALTY_SIGNALS.nodeModules;
-  if (/(^|\/)(test|tests|spec|__tests__|e2e)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.testFile;
+  // A penalty must never fire on the very thing the user asked for. Before
+  // this, "write tests for the ranker" multiplied every test file by 0.4 —
+  // the query and the penalty were pulling in opposite directions.
+  if (/(^|\/)(test|tests|spec|__tests__|e2e)($|\/)/.test(pathLower) || /\.(test|spec)\./.test(pathLower)) {
+    return (wants && wants.tests) ? 1.0 : PENALTY_SIGNALS.testFile;
+  }
   if (/(^|\/)(dist|build|\.next|\.nuxt|out|\.venv|venv)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.generatedCode;
-  if (/(^|\/)(docs|doc|readme|changelog)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.docsFile;
+  if (/(^|\/)(docs|doc|readme|changelog)($|\/)/.test(pathLower)) {
+    return (wants && wants.docs) ? 1.0 : PENALTY_SIGNALS.docsFile;
+  }
+  // Content-based, and last: a data holder is still a real source file, so it
+  // is only demoted once the path-based categories have had their say.
+  if (_isDataHolder(sigs)) {
+    return (wants && wants.models) ? 1.0 : PENALTY_SIGNALS.dataHolder;
+  }
   return 1.0;
 }
 
@@ -87,6 +153,26 @@ function _computeHubs(graph) {
 }
 
 // Common utility paths that should be treated as hubs regardless of fanout
+// The graph builders disagree on key case: src/graph/builder.js lowercases every
+// node (normalizePath), while src/graph/call-graph.js keys by a case-preserving
+// path.resolve. Assuming either one breaks the other, so every graph lookup in
+// this file probes both forms — the same thing the centrality blend already does.
+function _graphKeys(p) {
+  const norm = require('path').normalize(p);
+  const lower = norm.toLowerCase();
+  return lower === norm ? [norm] : [norm, lower];
+}
+function _graphGet(map, absPath) {
+  for (const k of _graphKeys(absPath)) {
+    const hit = map.get(k);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+function _registerKeys(map, absPath, value) {
+  for (const k of _graphKeys(absPath)) if (!map.has(k)) map.set(k, value);
+}
+
 function _isHub(filePath) {
   return /\/(utils|helpers|shared|common|constants|types|interfaces|index|zzz|globals)\.(ts|tsx|js|jsx|r|R)$/.test(filePath)
       || filePath.endsWith('/index.ts') || filePath.endsWith('/index.js')
@@ -102,14 +188,18 @@ function _isHub(filePath) {
  * @param {object}   weights
  * @returns {{ score: number, signals: { exactToken: number, symbolMatch: number, prefixMatch: number, pathMatch: number, penalty: number } }}
  */
-function scoreFile(filePath, sigs, queryTokens, weights) {
+function scoreFile(filePath, sigs, queryTokens, weights, wants) {
   if (!sigs || sigs.length === 0) return { score: 0, signals: { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: 1.0 } };
 
   const w = weights || DEFAULT_WEIGHTS;
-  const signals = { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: _computePenalty(filePath) };
-
-  // Build token set from all signatures
-  const sigText = sigs.join(' ');
+  const signals = { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: _computePenalty(filePath, wants, sigs) };
+
+  // Module-doc prose is excluded here on purpose. This signal measures overlap
+  // with DECLARED IDENTIFIERS; prose relevance is BM25's job, where it is scored
+  // as its own weighted field. Letting descriptive text inflate the identifier
+  // signal double-counts it and measurably degraded MRR.
+  const codeSigs = sigs.filter((line) => !MODULE_DOC_RE.test(line));
+  const sigText = codeSigs.join(' ');
   const sigTokenSet = new Set(tokenize(sigText));
 
   // Build token set from the file path
@@ -127,7 +217,7 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
       signals.exactToken += bonus;
 
       // Bonus: appears directly in a function/class/method name line
-      const nameLineMatch = sigs.some((sig) => {
+      const nameLineMatch = codeSigs.some((sig) => {
         const nt = tokenize(sig.replace(/[^a-zA-Z0-9_\s]/g, ' '));
         return nt.includes(qt);
       });
@@ -189,13 +279,18 @@ function rank(query, sigIndex, opts) {
   const graph = (opts && opts.graph && opts.graph.forward instanceof Map) ? opts.graph : null;
   const cwd = (opts && opts.cwd) || null;
 
-  // Detect query intent and get appropriate weights
+  // Intent is reported to the user and shapes output depth; it no longer
+  // selects scoring weights (see SIGNAL_BLEND).
   const intent = detectIntent(query);
-  const intentWeights = INTENT_WEIGHTS[intent] || DEFAULT_WEIGHTS;
-  const weights = (opts && opts.weights) ? Object.assign({}, intentWeights, opts.weights) : intentWeights;
-  const learnedWeights = opts && opts.cwd ? loadWeights(opts.cwd) : null;
+  const weights = (opts && opts.weights) ? Object.assign({}, DEFAULT_WEIGHTS, opts.weights) : DEFAULT_WEIGHTS;
+  // Learned per-file multipliers are a LOCAL, evolving signal (.context/weights.json).
+  // Benchmarks and CI gates must opt out via { learned: false }, or a developer's
+  // local learned state silently changes the score and CI stops being reproducible.
+  const useLearned = !(opts && opts.learned === false);
+  const learnedWeights = opts && opts.cwd && useLearned ? loadWeights(opts.cwd) : null;
 
   const queryTokens = tokenize(query);
+  const queryWants = _queryWants(queryTokens);
   if (queryTokens.length === 0) {
     // Empty query: return top-K by file count (most signatures = most useful)
     const all = [];
@@ -212,18 +307,32 @@ function rank(query, sigIndex, opts) {
   // are matched. The existing negative-signal penalty and recency/graph/learned
   // boosts are layered on top; the per-token signals stay for the explain table.
   const bm25Scores = new Map();
-  for (const c of bm25rank(query, [...sigIndex.entries()].map(([file, sigs]) => ({ file, sigs })))) {
+  for (const c of bm25rank(query, [...sigIndex.entries()].map(([file, sigs]) => ({ file, sigs })), opts)) {
     bm25Scores.set(c.file, c.score);
   }
 
-  const scored = [];
+  // Two passes: scoreFile's weighted signal needs the max across the corpus to
+  // normalise against, so collect first, then combine.
+  const prescored = [];
+  let maxSignal = 0;
   for (const [file, sigs] of sigIndex.entries()) {
-    const result = scoreFile(file, sigs, queryTokens, weights);
+    const result = scoreFile(file, sigs, queryTokens, weights, queryWants);
+    if (result.score > maxSignal) maxSignal = result.score;
+    prescored.push({ file, sigs, result });
+  }
+
+  const scored = [];
+  for (const { file, sigs, result } of prescored) {
     const penalty = result.signals.penalty;
     const base = bm25Scores.get(file) || 0;
-    let score = base * penalty;
+    // Blend the weighted keyword/symbol/path signal into the BM25 base. This
+    // was previously computed and thrown away — `result.score` was never read,
+    // which silently made DEFAULT_WEIGHTS and every intent profile dead config.
+    const signalNorm = maxSignal > 0 ? result.score / maxSignal : 0;
+    let score = base * penalty * (1 + SIGNAL_BLEND * signalNorm);
     const signals = result.signals;
     signals.bm25 = base;
+    signals.signalBlend = signalNorm;
 
     // Recency boost
     if (recencySet && recencySet.has(file) && score > 0) {
@@ -253,44 +362,46 @@ function rank(query, sigIndex, opts) {
   // Hub suppression: files with high fanout (>20%) are not boosted
   if (graph && cwd) {
     const path = require('path');
-    // Build maps for relative ↔ absolute path conversion and index lookup
-    const relToIdx = new Map();
-    const absToRel = new Map();
+    // Every graph node is keyed by `path.normalize(p).toLowerCase()` (see
+    // normalizePath in src/graph/builder.js and src/graph/call-graph.js).
+    // Lookups MUST use the same key space: a bare path.resolve() preserves
+    // case, so on any repo whose absolute path contains an uppercase letter
+    // every .get() missed and this entire block was silently inert.
+    const keyToIdx = new Map();
     for (let i = 0; i < scored.length; i++) {
-      relToIdx.set(scored[i].file, i);
-      const abs = path.resolve(cwd, scored[i].file);
-      absToRel.set(abs, scored[i].file);
+      _registerKeys(keyToIdx, path.resolve(cwd, scored[i].file), i);
     }
 
     const hubs = _computeHubs(graph);
-    const hop1Files = new Set(); // track which files received hop1 boost
+    const hop1Files = new Set(); // normalised keys that received a hop1 boost
+    const hop1Seeds = [];        // original (un-normalised) paths, for hop-2 lookup
 
     // Hop 1: direct neighbors of scored files
     for (const entry of scored) {
       if (entry.score <= 0) continue;
-      const abs = path.resolve(cwd, entry.file);
-      const neighbors = graph.forward.get(abs) || [];
+      const neighbors = _graphGet(graph.forward, path.resolve(cwd, entry.file)) || [];
       for (const neighborAbs of neighbors) {
-        if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
-        const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
-        const idx = relToIdx.get(neighborRel);
+        const nk = path.normalize(neighborAbs);
+        if (_isHub(nk) || hubs.has(nk) || hubs.has(nk.toLowerCase())) continue;
+        const idx = _graphGet(keyToIdx, nk);
         if (idx !== undefined) {
           scored[idx].score += GRAPH_BOOST_AMOUNTS.hop1;
           scored[idx].signals.graphBoost = (scored[idx].signals.graphBoost || 0) + GRAPH_BOOST_AMOUNTS.hop1;
-          hop1Files.add(neighborAbs);
+          hop1Files.add(nk);
+          hop1Seeds.push(neighborAbs);
         }
       }
     }
 
     // Hop 2: neighbors of hop1 files (only if they didn't get a direct score)
-    for (const hop1File of hop1Files) {
-      if (!absToRel.has(hop1File)) continue; // skip files not in index
-      const neighbors = graph.forward.get(hop1File) || [];
+    for (const hop1Key of hop1Seeds) {
+      if (_graphGet(keyToIdx, hop1Key) === undefined) continue; // skip files not in index
+      const neighbors = _graphGet(graph.forward, hop1Key) || [];
       for (const neighborAbs of neighbors) {
-        if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
-        if (hop1Files.has(neighborAbs)) continue; // skip already hop1-boosted
-        const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
-        const idx = relToIdx.get(neighborRel);
+        const nk = path.normalize(neighborAbs);
+        if (_isHub(nk) || hubs.has(nk) || hubs.has(nk.toLowerCase())) continue;
+        if (hop1Files.has(nk)) continue; // skip already hop1-boosted
+        const idx = _graphGet(keyToIdx, nk);
         if (idx !== undefined && scored[idx].score > 0) {
           // Only boost files that have some baseline score (not noise)
           scored[idx].score += GRAPH_BOOST_AMOUNTS.hop2;
@@ -307,16 +418,17 @@ function rank(query, sigIndex, opts) {
   const callGraph = (opts && opts.callGraph && opts.callGraph.forward instanceof Map) ? opts.callGraph : null;
   if (callGraph && cwd) {
     const path = require('path');
-    const relToIdx = new Map();
-    for (let i = 0; i < scored.length; i++) relToIdx.set(scored[i].file, i);
+    // buildCallFileGraph keys by a CASE-PRESERVING path.resolve, unlike the
+    // import graph builder which lowercases — hence the dual-form probe.
+    const keyToIdx = new Map();
+    for (let i = 0; i < scored.length; i++) _registerKeys(keyToIdx, path.resolve(cwd, scored[i].file), i);
     const hubs = _computeHubs(callGraph);
     const seeds = scored.filter((e) => e.score > 0).map((e) => e.file);
     for (const file of seeds) {
-      const abs = path.resolve(cwd, file);
-      for (const neighborAbs of (callGraph.forward.get(abs) || [])) {
-        if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
-        const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
-        const idx = relToIdx.get(neighborRel);
+      for (const neighborAbs of (_graphGet(callGraph.forward, path.resolve(cwd, file)) || [])) {
+        const nk = path.normalize(neighborAbs);
+        if (_isHub(nk) || hubs.has(nk) || hubs.has(nk.toLowerCase())) continue;
+        const idx = _graphGet(keyToIdx, nk);
         if (idx !== undefined && scored[idx].file !== file) {
           scored[idx].score += GRAPH_BOOST_AMOUNTS.callHop;
           scored[idx].signals.callGraphBoost = (scored[idx].signals.callGraphBoost || 0) + GRAPH_BOOST_AMOUNTS.callHop;
@@ -490,6 +602,18 @@ function _enrichSigIndexFromStrategy(cwd, index) {
     }
   } catch (_) {}
   _mergeSigIndex(index, _buildSigIndexFromCache(cwd));
+
+  // The complete retrieval index (written by generate before applyTokenBudget)
+  // takes precedence: it is the only source containing files the budget dropped,
+  // and full signatures for files the budget collapsed to line anchors. It is
+  // merged as the BASE rather than on top because _mergeSigIndex only replaces
+  // when the source has MORE signatures — a collapsed entry has the same count
+  // as its full form, so merging the other way would keep the anchors.
+  try {
+    const full = require('./sig-index-store').readFullIndex(cwd);
+    if (full.size > 0) return _mergeSigIndex(full, index);
+  } catch (_) { /* absent → budgeted view is still served */ }
+
   return index;
 }
 
@@ -615,22 +739,53 @@ function formatRankJSON(results, query) {
 // ---------------------------------------------------------------------------
 // Intent detection — 7 intents
 // ---------------------------------------------------------------------------
+// Nouns carry an optional plural: `\btest\b` does not match "tests", so
+// "write unit tests for the ranker" matched NO intent at all and fell through
+// to the 'search' default.
 const INTENT_PATTERNS = {
-  debug:    /\b(bug|fix|error|crash|exception|broken|failing|issue|problem|regression)\b/i,
+  debug:    /\b(bugs?|fix(es|ed)?|errors?|crash(es)?|exceptions?|broken|failing|failures?|issues?|problems?|regressions?)\b/i,
   explain:  /\b(explain|how does|what is|understand|overview|architecture|describe|walk me|teach)\b/i,
-  refactor: /\b(refactor|restructure|redesign|clean up|extract|move|rename|simplify|optimize)\b/i,
+  refactor: /\b(refactor|restructure|redesign|clean up|extract|move|rename|simplify|optimi[sz]e)\b/i,
   review:   /\b(review|check|audit|security|pr|pull request|assess|validate)\b/i,
-  test:     /\b(test|unit test|integration test|testing|spec|assert|mock)\b/i,
-  integrate:/\b(import|integrate|connect|wire|bind|require|export|depend|graph)\b|require[ds]\b/i,
+  test:     /\b(tests?|unit tests?|integration tests?|testing|specs?|assert(ion)?s?|mocks?|fixtures?)\b/i,
+  integrate:/\b(imports?|integrate|connect|wire|bind|requires?|exports?|depends?|dependenc(y|ies)|graph)\b/i,
   navigate: /\b(find|locate|where|search|look for|show me|navigate|browse|list)\b/i,
 };
 
-function detectIntent(query) {
-  if (!query || typeof query !== 'string') return 'search';
+/**
+ * Every intent whose pattern matches, strongest first.
+ *
+ * A real request is routinely multi-intent — "fix the failing test" is both a
+ * debug task and a test task — and reporting one label discards that. Worse,
+ * the single-label version returned the FIRST key in INTENT_PATTERNS order, so
+ * `debug` permanently shadowed `test`: no query containing "fix" or "failing"
+ * could ever be labelled a test, no matter how test-shaped it was.
+ *
+ * Ranked by how many distinct terms each pattern matched, so the dominant
+ * intent leads; ties fall back to declaration order for determinism.
+ *
+ * @param {string} query
+ * @returns {string[]} matched intents, never empty (defaults to ['search'])
+ */
+function detectIntents(query) {
+  if (!query || typeof query !== 'string') return ['search'];
+  const scored = [];
+  let order = 0;
   for (const [intent, re] of Object.entries(INTENT_PATTERNS)) {
-    if (re.test(query)) return intent;
+    const hits = query.match(new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g'));
+    if (hits && hits.length) {
+      scored.push({ intent, hits: new Set(hits.map((h) => h.toLowerCase())).size, order: order });
+    }
+    order++;
   }
-  return 'search';
+  if (scored.length === 0) return ['search'];
+  scored.sort((a, b) => (b.hits - a.hits) || (a.order - b.order));
+  return scored.map((s) => s.intent);
+}
+
+/** Primary intent. Kept for callers that want a single label. */
+function detectIntent(query) {
+  return detectIntents(query)[0];
 }
 
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, CENTRALITY_BLEND_WEIGHT, detectIntent };
+module.exports = { rank, buildSigIndex, scoreFile, _queryWants, _isDataHolder, detectIntents, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, CENTRALITY_BLEND_WEIGHT, detectIntent };

package/src/retrieval/sig-index-store.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Complete, unbudgeted signature index for retrieval.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The generated context file (CLAUDE.md / AGENTS.md / copilot-instructions.md)
+ * is a BUDGETED VIEW: `applyTokenBudget` drops and collapses files so the
+ * artifact stays under `maxTokens`, because it is injected into every prompt.
+ *
+ * `buildSigIndex` used to parse that same artifact to build the ranker's index,
+ * so retrieval inherited the prompt budget. Every file the budget dropped became
+ * permanently unreachable by `sigmap ask` — no ranking change can surface a file
+ * that is not in the index. On this repo that was 53 of 155 source files (34%),
+ * and restoring them moved hit@5 from 50% to 90% on the retrieval corpus.
+ *
+ * The two artifacts have opposite requirements — the prompt file wants to be
+ * small, the index wants to be complete — so they are now separate. This store
+ * is written by `generate` BEFORE the budget is applied, and lives under
+ * `.context/` (gitignored, never injected into a prompt).
+ *
+ * Zero-dependency, bundle-safe (fs + path only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const INDEX_DIR = '.context';
+const INDEX_FILE = 'sig-index.json';
+const SCHEMA = 1;
+
+/** Absolute path to the retrieval index artifact. */
+function indexPath(cwd) {
+  return path.join(cwd, INDEX_DIR, INDEX_FILE);
+}
+
+/**
+ * Persist the complete signature index.
+ *
+ * @param {string} cwd
+ * @param {Array<{filePath: string, sigs: string[]}>} fileEntries - every
+ *        extracted entry, BEFORE applyTokenBudget has dropped or collapsed any.
+ * @param {{ version?: string }} [opts]
+ * @returns {{ path: string, files: number }}
+ */
+function writeFullIndex(cwd, fileEntries, opts = {}) {
+  const files = {};
+  let count = 0;
+  for (const e of fileEntries || []) {
+    if (!e || !e.filePath || !Array.isArray(e.sigs) || e.sigs.length === 0) continue;
+    const rel = path.relative(cwd, e.filePath).replace(/\\/g, '/');
+    if (!rel || rel.startsWith('..')) continue;
+    files[rel] = e.sigs;
+    count++;
+  }
+
+  const out = indexPath(cwd);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  // Write-then-rename so a concurrent `ask` never observes a half-written index.
+  const tmp = `${out}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({
+    schema: SCHEMA,
+    sigmapVersion: opts.version || null,
+    generated: new Date().toISOString(),
+    files,
+  }), 'utf8');
+  fs.renameSync(tmp, out);
+  return { path: out, files: count };
+}
+
+/**
+ * Load the complete signature index, or an empty Map when absent/unreadable.
+ *
+ * Deliberately NOT version-busted (unlike .sigmap-cache.json): a stale but
+ * complete index still retrieves the right files, whereas discarding it drops
+ * retrieval back to the budgeted view — the exact failure this store exists to
+ * prevent. Staleness is handled by re-running generate or by cache/freshen.
+ *
+ * @param {string} cwd
+ * @returns {Map<string, string[]>}
+ */
+function readFullIndex(cwd) {
+  const index = new Map();
+  try {
+    const data = JSON.parse(fs.readFileSync(indexPath(cwd), 'utf8'));
+    if (!data || data.schema !== SCHEMA || !data.files) return index;
+    for (const [rel, sigs] of Object.entries(data.files)) {
+      if (Array.isArray(sigs) && sigs.length > 0) index.set(rel, sigs);
+    }
+  } catch (_) { /* absent or corrupt → caller falls back to the context file */ }
+  return index;
+}
+
+module.exports = { writeFullIndex, readFullIndex, indexPath, SCHEMA, INDEX_FILE };

package/src/skills/skills.js

@@ -34,6 +34,24 @@ const SKILLS = {
       '6. **Watch the budget.** Check the `get_budget` MCP tool or `sigmap budget` (estimates from SigMap\'s local ledger — no LLM calls). Near the budget: summarize-then-drop older context instead of accumulating, and prefer terse output.',
     ].join('\n'),
   },
+  'sigmap-task': {
+    title: 'SigMap task loop',
+    kind: 'prompt',
+    description: 'Do a coding task grounded in SigMap: look up before reading, edit by line anchor, verify before reporting.',
+    argumentHint: 'the change you want, in plain words',
+    body: [
+      'Work through these steps **in order**. Do not open any file before step 2.',
+      'Every command runs from the integrated terminal — do not ask the user to run them for you.',
+      '',
+      '1. **Look up, do not search.** `npx sigmap ask "<the task>"` — this writes `.context/query-context.md`.',
+      '2. **Read the map.** `cat .context/query-context.md`. It ranks the relevant files and lists their signatures with `:start-end` line anchors — a few hundred tokens where the same files read whole are tens of thousands. Say which files it surfaced before continuing. If nothing relevant appears, re-run step 1 with different wording; fall back to search only after two attempts, and say so.',
+      '3. **Open only the anchored ranges.** A signature ending `:425-425` means read line 425, not the whole file. Never read a file in full when you hold an anchor for it.',
+      '4. **Make the change.** Follow the conventions visible in the signatures — same layering, same response wrapper, same annotation style. Add no dependencies.',
+      '5. **Verify before reporting.** Write what you changed to `.sigmap-notes.md`, naming every file by its **full repository-relative path** (a bare filename is reported as fake), then run `npx sigmap verify-ai-output .sigmap-notes.md`. It checks every name against the real index, offline, with no model call. Fix anything it flags and re-run before you reply.',
+      '6. **Refresh the map.** `npx sigmap` — your edits made it stale.',
+      '7. **Report.** The files you changed, the ranges you actually read, the step-1 token count, and the step-5 verify result. Say so if you fell back to searching or if verify flagged something.',
+    ].join('\n'),
+  },
   'sigmap-config-optimizer': {
     title: 'SigMap config optimizer',
     description: 'Playbook for getting a correct SigMap config on any repo: detect with sigmap tune, review the per-change reasons, apply, validate.',
@@ -58,7 +76,9 @@ const SKILL_CLIENTS = {
   windsurf: { label: 'Windsurf',       parent: ['.windsurf'],
               target: (cwd, skill) => path.join(cwd, '.windsurf', 'rules', `${skill}.md`) },
   copilot:  { label: 'GitHub Copilot', parent: ['.github'],
-              target: (cwd, skill) => path.join(cwd, '.github', 'instructions', `${skill}.instructions.md`) },
+              target: (cwd, skill) => (SKILLS[skill] && SKILLS[skill].kind === 'prompt'
+                ? path.join(cwd, '.github', 'prompts', `${skill}.prompt.md`)
+                : path.join(cwd, '.github', 'instructions', `${skill}.instructions.md`)) },
   codex:    { label: 'Codex CLI (AGENTS.md)', parent: ['AGENTS.md'],
               target: (cwd) => path.join(cwd, 'AGENTS.md'), inject: true },
 };
@@ -79,6 +99,10 @@ function renderSkill(client, skillName, version) {
     return `---\ndescription: ${skill.description}\nalwaysApply: false\n---\n\n${body}`;
   }
   if (client === 'copilot') {
+    if (skill.kind === 'prompt') {
+      return `---\nname: ${skillName}\nagent: 'agent'\ndescription: ${skill.description}\n`
+        + `argument-hint: ${skill.argumentHint}\n---\n\n${body}`;
+    }
     return `---\napplyTo: "**"\n---\n\n${body}`;
   }
   return body; // windsurf: plain markdown