sigmap 8.9.0 → 8.10.0

package/src/health/scorer.js

@@ -1,152 +1,227 @@
 'use strict';
 
 /**
- * SigMap health scorer.
+ * SigMap health scorer (v8.11 — auditable composite).
  *
- * Computes a composite 0-100 health score for the current project by combining:
- *   1. Days since context file was last regenerated  (staleness penalty ≤ 30 pts)
- *   2. Average token reduction percentage             (low-reduction penalty 20 pts)
- *   3. Over-budget run rate                           (budget penalty 20 pts)
+ * Computes a 0-100 health score for a project. Every deduction is recorded in a
+ * `components[]` breakdown so the number is auditable (which signal cost what),
+ * and purely-informational metrics live under `diagnostics` rather than being
+ * dressed up as if they affect the grade.
  *
- * Strategy-aware: thresholds adjust based on the active strategy so that
- * hot-cold (90% reduction intentional) is not penalized as 'low reduction'.
+ * Scored signals (each appears in `components` only when it fires):
+ *   1. context never generated  — no adapter output exists though source does  (45 pts)
+ *   2. staleness                — freshest adapter output older than 7 days     (≤30 pts)
+ *   3. low token reduction      — avg reduction under threshold (full strategy) (20 pts)
+ *   4. cold-context staleness   — hot-cold context-cold.md older than 1 day     (≤10 pts)
+ *   5. over-budget rate         — >20% of runs exceeded the token budget        (20 pts)
+ *   6. sustained over-budget    — ≥3 consecutive over-budget runs               (5 pts)
  *
- * Grade scale:  A ≥ 90  |  B ≥ 75  |  C ≥ 60  |  D < 60
+ * Diagnostics (informational, NOT scored): p50/p95 token count, and
+ * languageCoverage (share of SigMap's supported languages present in the repo —
+ * this is language diversity, not extractor quality, and was previously
+ * mislabeled "extractorCoverage").
  *
- * Never throws — returns graceful result with nulls for unavailable metrics.
+ * Freshness looks at the freshest of ANY adapter output (not just Copilot), so a
+ * Claude/Codex/Cursor user is not falsely flagged as "never generated".
  *
- * @param {string} cwd - Working directory (root of the project)
- * @returns {{
- *   score: number,
- *   grade: 'A'|'B'|'C'|'D',
- *   strategy: string,
- *   tokenReductionPct: number|null,
- *   daysSinceRegen: number|null,
- *   strategyFreshnessDays: number|null,
- *   totalRuns: number,
- *   overBudgetRuns: number,
- * }}
+ * Grade scale:  A ≥ 90 | B ≥ 75 | C ≥ 60 | D < 60. Never throws.
+ *
+ * @param {string} cwd
+ * @returns {object} { score, grade, components, strategy, tokenReductionPct,
+ *   daysSinceRegen, strategyFreshnessDays, totalRuns, overBudgetRuns,
+ *   overBudgetStreak, languageCoverage, extractorCoverage, diagnostics }
  */
-function score(cwd) {
-  const fs = require('fs');
-  const path = require('path');
 
-  let tokenReductionPct = null;
-  let daysSinceRegen = null;
-  let strategyFreshnessDays = null;
-  let overBudgetRuns = 0;
-  let totalRuns = 0;
-  let p50TokenCount = 0;
-  let p95TokenCount = 0;
-  let overBudgetStreak = 0;
-  let extractorCoverage = 0;
+const fs = require('fs');
+const path = require('path');
+
+// Every path a SigMap adapter may write context to (freshness looks at the
+// freshest existing one). Mirrors the ranker's adapter-output probe order.
+const CONTEXT_FILES = [
+  ['.github', 'copilot-instructions.md'],
+  ['CLAUDE.md'],
+  ['AGENTS.md'],
+  ['.cursorrules'],
+  ['.windsurfrules'],
+  ['.github', 'openai-context.md'],
+  ['.github', 'gemini-context.md'],
+  ['llm-full.txt'],
+  ['llm.txt'],
+];
+
+function gradeFor(points) {
+  if (points >= 90) return 'A';
+  if (points >= 75) return 'B';
+  if (points >= 60) return 'C';
+  return 'D';
+}
+
+/**
+ * Pure scoring core. Given gathered signals, return the score, grade, and the
+ * labeled list of deductions. No IO — unit-testable in isolation.
+ *
+ * @param {object} s gathered signals
+ * @returns {{ score:number, grade:'A'|'B'|'C'|'D', components:Array }}
+ */
+function composeHealth(s) {
+  const components = [];
+  const add = (id, label, penalty, detail) => {
+    const p = Math.round(penalty);
+    if (p > 0) components.push({ id, label, penalty: p, detail });
+  };
 
-  // ── Detect active strategy ────────────────────────────────────────────────
+  // 1. Context never generated — a project with source files but no context of
+  //    any kind is not "healthy"; it hasn't been set up. Gated on hasSource so
+  //    an empty/new directory is not penalised for having nothing to index.
+  if (s.daysSinceRegen === null && s.hasSource) {
+    add('not-generated', 'context never generated', 45,
+      'no adapter output found — run `sigmap` to generate context');
+  }
+
+  // 2. Staleness — freshest adapter output older than the 7-day window.
+  if (s.daysSinceRegen !== null && s.daysSinceRegen > 7) {
+    add('staleness', 'context stale', Math.min(30, Math.floor((s.daysSinceRegen - 7) * 4)),
+      `${s.daysSinceRegen}d since last regen (>7d)`);
+  }
+
+  // 3. Low token reduction — only meaningful for the 'full' strategy; hot-cold
+  //    and per-module intentionally produce small/partial outputs.
+  const reductionThreshold = s.strategy === 'full' ? 60 : 0;
+  if (s.tokenReductionPct !== null && s.tokenReductionPct < reductionThreshold) {
+    add('low-reduction', 'low token reduction', 20,
+      `${s.tokenReductionPct}% avg reduction (<${reductionThreshold}%)`);
+  }
+
+  // 4. Cold-context staleness (hot-cold only).
+  if (s.strategy === 'hot-cold' && s.strategyFreshnessDays !== null && s.strategyFreshnessDays > 1) {
+    add('cold-freshness', 'cold context stale', Math.min(10, Math.floor(s.strategyFreshnessDays - 1) * 3),
+      `context-cold.md ${s.strategyFreshnessDays}d old`);
+  }
+
+  // 5. Over-budget rate.
+  if (s.overBudgetRuns > 0 && s.totalRuns > 0) {
+    const rate = (s.overBudgetRuns / s.totalRuns) * 100;
+    if (rate > 20) add('over-budget', 'runs over budget', 20,
+      `${Math.round(rate)}% of runs exceeded budget (>20%)`);
+  }
+
+  // 6. Sustained over-budget streak — previously computed but never scored.
+  if (s.overBudgetStreak >= 3) {
+    add('over-budget-streak', 'sustained over-budget', 5,
+      `${s.overBudgetStreak} consecutive over-budget runs`);
+  }
+
+  const penalty = components.reduce((sum, c) => sum + c.penalty, 0);
+  const score = Math.max(0, Math.min(100, 100 - penalty));
+  return { score, grade: gradeFor(score), components };
+}
+
+/**
+ * Gather health signals from disk and score them. Never throws.
+ * @param {string} cwd
+ */
+function score(cwd) {
   let strategy = 'full';
   try {
     const cfgPath = path.join(cwd, 'gen-context.config.json');
     if (fs.existsSync(cfgPath)) {
-      const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-      strategy = cfg.strategy || 'full';
+      strategy = JSON.parse(fs.readFileSync(cfgPath, 'utf8')).strategy || 'full';
     }
   } catch (_) {}
 
-  // ── Read usage log via tracking logger ──────────────────────────────────
+  // ── Usage-log signals (only present when tracking has recorded runs) ────────
+  let tokenReductionPct = null;
+  let overBudgetRuns = 0;
+  let totalRuns = 0;
+  let p50TokenCount = 0;
+  let p95TokenCount = 0;
+  let overBudgetStreak = 0;
   try {
     const { readLog, summarize } = require('../tracking/logger');
-    const { percentile, overBudgetStreak: calcOverBudgetStreak } = require('../format/dashboard');
+    const { percentile, overBudgetStreak: calcStreak } = require('../format/dashboard');
     const entries = readLog(cwd);
-    const s = summarize(entries);
-    // Only set tokenReductionPct when there is actual history; a brand-new/
-    // untracked project should not be penalised for "0% reduction".
-    if (s.totalRuns > 0) tokenReductionPct = s.avgReductionPct;
-    overBudgetRuns = s.overBudgetRuns;
-    totalRuns = s.totalRuns;
+    const sum = summarize(entries);
+    if (sum.totalRuns > 0) tokenReductionPct = sum.avgReductionPct;
+    overBudgetRuns = sum.overBudgetRuns;
+    totalRuns = sum.totalRuns;
     const finals = entries.map((e) => Number(e.finalTokens)).filter(Number.isFinite);
     p50TokenCount = Math.round(percentile(finals, 50));
     p95TokenCount = Math.round(percentile(finals, 95));
-    overBudgetStreak = calcOverBudgetStreak(entries);
-  } catch (_) {
-    // No usage log yet — proceed with nulls
-  }
+    overBudgetStreak = calcStreak(entries);
+  } catch (_) {}
 
+  // ── Language coverage (DIAGNOSTIC — share of supported languages present,
+  //    i.e. diversity, not extractor quality). Also yields hasSource. ──────────
+  let languageCoverage = null;
+  let hasSource = false;
   try {
     const { computeExtractorCoverage } = require('../format/dashboard');
-    extractorCoverage = computeExtractorCoverage(cwd).pct;
-  } catch (_) {
-    extractorCoverage = 0;
-  }
+    const cov = computeExtractorCoverage(cwd);
+    languageCoverage = { covered: cov.covered, supported: cov.supported, pct: cov.pct };
+    hasSource = Object.values(cov.perLanguage || {}).some((n) => n > 0);
+  } catch (_) {}
 
-  // ── Days since primary context file was last regenerated ─────────────────
+  // ── Freshness across ALL adapter outputs (freshest wins) ───────────────────
+  let daysSinceRegen = null;
   try {
-    const ctxFile = path.join(cwd, '.github', 'copilot-instructions.md');
-    if (fs.existsSync(ctxFile)) {
-      const mtime = fs.statSync(ctxFile).mtimeMs;
-      daysSinceRegen = parseFloat(((Date.now() - mtime) / (1000 * 60 * 60 * 24)).toFixed(1));
+    let newest = null;
+    for (const parts of CONTEXT_FILES) {
+      const p = path.join(cwd, ...parts);
+      try {
+        if (fs.existsSync(p)) {
+          const m = fs.statSync(p).mtimeMs;
+          if (newest === null || m > newest) newest = m;
+        }
+      } catch (_) {}
+    }
+    if (newest !== null) {
+      daysSinceRegen = parseFloat(((Date.now() - newest) / (1000 * 60 * 60 * 24)).toFixed(1));
     }
   } catch (_) {}
 
-  // ── Strategy freshness: context-cold.md age (hot-cold only) ─────────────
+  // ── Cold-context freshness (hot-cold strategy only) ────────────────────────
+  let strategyFreshnessDays = null;
   if (strategy === 'hot-cold') {
     try {
       const coldFile = path.join(cwd, '.github', 'context-cold.md');
       if (fs.existsSync(coldFile)) {
-        const mtime = fs.statSync(coldFile).mtimeMs;
-        strategyFreshnessDays = parseFloat(((Date.now() - mtime) / (1000 * 60 * 60 * 24)).toFixed(1));
+        const m = fs.statSync(coldFile).mtimeMs;
+        strategyFreshnessDays = parseFloat(((Date.now() - m) / (1000 * 60 * 60 * 24)).toFixed(1));
       }
     } catch (_) {}
   }
 
-  // ── Compute composite score ───────────────────────────────────────────────
-  let points = 100;
-
-  // Staleness penalty: -4 pts per day over the 7-day freshness window (max -30)
-  if (daysSinceRegen !== null && daysSinceRegen > 7) {
-    points -= Math.min(30, Math.floor((daysSinceRegen - 7) * 4));
-  }
-
-  // Low-reduction penalty — threshold depends on strategy:
-  // - hot-cold: primary output is intentionally tiny; measure cold freshness instead
-  // - per-module: per-file budgets; global reduction < 60% expected, no penalty
-  // - full: standard 60% threshold
-  const reductionThreshold = (strategy === 'full') ? 60 : 0; // disable for hot-cold/per-module
-  if (tokenReductionPct !== null && tokenReductionPct < reductionThreshold) {
-    points -= 20;
-  }
-
-  // hot-cold strategy freshness penalty: context-cold.md older than 1 day (-10 pts)
-  if (strategy === 'hot-cold' && strategyFreshnessDays !== null && strategyFreshnessDays > 1) {
-    points -= Math.min(10, Math.floor(strategyFreshnessDays - 1) * 3);
-  }
-
-  // Over-budget penalty: more than 20% of runs exceeded the token budget (-20)
-  if (overBudgetRuns > 0 && totalRuns > 0) {
-    const overBudgetRate = (overBudgetRuns / totalRuns) * 100;
-    if (overBudgetRate > 20) points -= 20;
-  }
-
-  points = Math.max(0, Math.min(100, Math.round(points)));
-
-  let grade;
-  if (points >= 90) grade = 'A';
-  else if (points >= 75) grade = 'B';
-  else if (points >= 60) grade = 'C';
-  else grade = 'D';
+  const { score: points, grade, components } = composeHealth({
+    strategy,
+    daysSinceRegen,
+    strategyFreshnessDays,
+    tokenReductionPct,
+    overBudgetRuns,
+    totalRuns,
+    overBudgetStreak,
+    hasSource,
+  });
 
   return {
     score: points,
     grade,
+    components,
     strategy,
     tokenReductionPct,
     daysSinceRegen,
     strategyFreshnessDays,
     totalRuns,
     overBudgetRuns,
+    overBudgetStreak,
+    languageCoverage,
+    // Back-compat top-level fields (also surfaced, honestly grouped, under
+    // `diagnostics`). `extractorCoverage` keeps its old name but its value is
+    // language-diversity pct (never extractor quality) — prefer `languageCoverage`.
     p50TokenCount,
     p95TokenCount,
-    overBudgetStreak,
-    extractorCoverage,
+    extractorCoverage: languageCoverage ? languageCoverage.pct : 0,
+    diagnostics: { p50TokenCount, p95TokenCount, languageCoverage },
   };
 }
 
-module.exports = { score };
+module.exports = { score, composeHealth };

package/src/judge/judge-engine.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { boostFiles, normalizeFile, penalizeFiles } = require('../learning/weights');
+const parsers = require('../verify/parsers');
 
 const STOP = new Set([
   'the','a','an','in','on','at','to','of','for','and','or','but',
@@ -25,6 +26,57 @@ function groundedness(response, context) {
   return parseFloat((matched.length / respTokens.length).toFixed(3));
 }
 
+/**
+ * Claim-level grounding (v8.10) — the structural half of the judge.
+ *
+ * `groundedness` above measures lexical *word* overlap: "does the answer reuse
+ * context vocabulary?" That is a weak proxy — an answer can echo context words
+ * while asserting a symbol, file, or import the context never mentions (a
+ * hallucination), and still score high. This function extracts the answer's
+ * *concrete, checkable claims* — the same high-precision claims the hallucination
+ * guard checks (backtick-wrapped `foo()` calls, `path/to/file.ext` references,
+ * and `import … from 'mod'` statements) — and verifies each one appears in the
+ * provided context. A claim the context never grounds is a hallucination signal
+ * that pure word-overlap cannot see.
+ *
+ * Deterministic, offline, zero-dependency. Reuses `src/verify/parsers`.
+ *
+ * @param {string} response
+ * @param {string} context
+ * @returns {{ total: number, grounded: number, ungrounded: Array<{kind:string, value:string}> }}
+ */
+function claimGrounding(response, context) {
+  if (!response || !context) return { total: 0, grounded: 0, ungrounded: [] };
+  const ctxLower = context.toLowerCase();
+
+  const raw = [];
+  for (const s of parsers.extractSymbols(response)) raw.push({ kind: 'symbol', value: s.name });
+  for (const f of parsers.extractFilePaths(response)) raw.push({ kind: 'file', value: f.path });
+  for (const i of parsers.extractImports(response)) raw.push({ kind: 'import', value: i.module });
+
+  const seen = new Set();
+  const claims = raw.filter((c) => {
+    const key = `${c.kind}::${c.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  const ungrounded = [];
+  let grounded = 0;
+  for (const c of claims) {
+    // A file claim is grounded if its basename appears in context (the answer
+    // may cite a different directory than the map records). Symbols and modules
+    // are matched on the token itself.
+    const needle = c.value.toLowerCase();
+    const base = c.kind === 'file' ? (c.value.split('/').pop() || c.value).toLowerCase() : needle;
+    if (ctxLower.includes(base) || ctxLower.includes(needle)) grounded++;
+    else ungrounded.push({ kind: c.kind, value: c.value });
+  }
+
+  return { total: claims.length, grounded, ungrounded };
+}
+
 const GENERIC_MARKERS = [
   'however, based on my knowledge',
   'generally speaking',
@@ -76,8 +128,16 @@ function judge(response, context, opts = {}) {
     }
   }
 
+  // Structural claim grounding: any concrete symbol/file/import the answer
+  // states that the context never mentions is a hallucination the lexical
+  // score above cannot detect. Each ungrounded claim fails the verdict.
+  const claims = claimGrounding(response, context);
+  for (const c of claims.ungrounded) {
+    reasons.push(`${c.kind} claim not grounded in context: ${c.value}${c.kind === 'symbol' ? '()' : ''}`);
+  }
+
   const verdict = score >= threshold && reasons.length === 0 ? 'pass' : 'fail';
-  const result = { score, verdict, reasons };
+  const result = { score, verdict, reasons, claims };
 
   if (opts.learn) {
     const learning = {
@@ -119,4 +179,4 @@ function judge(response, context, opts = {}) {
   return result;
 }
 
-module.exports = { groundedness, judge };
+module.exports = { groundedness, claimGrounding, judge };

package/src/mcp/server.js

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

package/src/plan/planner.js

@@ -9,7 +9,7 @@ const { buildTestIndex, isTested } = require('../extractors/coverage');
 
 module.exports = { createPlan };
 
-function createPlan(goal, cwd, config) {
+function createPlan(goal, cwd, config = {}) {
   // Step 1: Detect intent and rank files for the goal
   const intent = detectIntent(goal);
   const sigIndex = buildSigIndex(cwd);
@@ -23,30 +23,59 @@ function createPlan(goal, cwd, config) {
   const highConf = ranked.filter(r => r.confidence === 'high').slice(0, 5);
   const medConf = ranked.filter(r => r.confidence === 'medium').slice(0, 5);
 
-  // Step 3: Compute impact radius for highest-confidence file
+  // Step 3: Impact radius — union the reverse-dependency blast radius of EVERY
+  // high-confidence file (not just the top one), bounded to 3 hops. Note the
+  // dependency graph resolves relative imports only, so this is a *lower bound*
+  // on real coupling (aliased/bare/dynamic imports are invisible). Previously
+  // this passed `{ maxDepth: 3 }`, which getImpact ignores — it reads `depth`,
+  // so the traversal silently ran unbounded (depth 0). Fixed to `depth: 3`.
   let impact = null;
   if (highConf.length > 0) {
-    const entryFile = highConf[0].file;
     try {
       const graph = buildFromCwd(cwd);
-      impact = getImpact(entryFile, graph, { maxDepth: 3, cwd });
+      // getImpact normalizes graph paths to lowercase, so on a case-varying
+      // filesystem (e.g. macOS `/Users`) its returned paths climb out of cwd.
+      // Re-anchor every impacted path to a clean, case-insensitive repo-relative
+      // form so dedup against the entry set works and output is readable.
+      const clean = (f) => {
+        const abs = path.resolve(cwd, f);
+        return abs.toLowerCase().startsWith(cwd.toLowerCase())
+          ? abs.slice(cwd.length).replace(/^[/\\]/, '')
+          : path.relative(cwd, abs);
+      };
+      const entrySet = new Set(highConf.map(r => r.file));
+      const direct = new Set();
+      const transitive = new Set();
+      for (const r of highConf) {
+        const imp = getImpact(r.file, graph, { depth: 3, cwd });
+        for (const f of (imp.direct || [])) direct.add(clean(f));
+        for (const f of (imp.transitive || [])) transitive.add(clean(f));
+      }
+      // The files we plan to change are not their own blast radius; and a file
+      // reached directly from one entry outranks a transitive reach from another.
+      for (const e of entrySet) { direct.delete(e); transitive.delete(e); }
+      for (const f of direct) transitive.delete(f);
+      impact = { direct: [...direct], transitive: [...transitive] };
     } catch (_) {
       // Graph build failed, continue without impact
     }
   }
 
-  // Step 4: Identify likely-affected tests
-  let testedFiles = [];
+  // Step 4: Flag which files-to-inspect have detectable test coverage. The test
+  // index maps test-*name tokens*, not test files, so `isTested` can only tell
+  // us a source file is covered — it cannot name the test file. We therefore
+  // report the covered SOURCE files honestly rather than pretending to list the
+  // tests to run.
+  let coveredFiles = [];
   try {
     const testIndex = buildTestIndex(cwd, config.testDirs || ['test', 'tests', '__tests__', 'spec']);
-    testedFiles = highConf.filter(r => {
-      const sigs = r.sigs || [];
-      const fnNames = sigs.map(s => {
+    coveredFiles = highConf.filter(r => {
+      const fnNames = (r.sigs || []).map(s => {
         const m = s.match(/(?:function|def|fn)\s+(\w+)/);
         return m ? m[1] : null;
       }).filter(Boolean);
       return fnNames.some(fn => isTested(fn, testIndex));
-    });
+    }).map(r => r.file);
   } catch (_) {
     // Coverage index failed, continue without test info
   }
@@ -56,10 +85,10 @@ function createPlan(goal, cwd, config) {
     intent,
     inspectFirst: highConf.map(r => r.file),
     likelyToChange: medConf.map(r => r.file),
-    impactRadius: impact ? {
-      direct: [...(impact.direct || [])],
-      transitive: [...(impact.transitive || [])],
-    } : null,
-    testsAffected: testedFiles.map(r => r.file),
+    impactRadius: impact,
+    coveredFiles,
+    // `testsAffected` retained for backward compatibility; it is the set of
+    // covered source files, NOT the test files (which the index cannot name).
+    testsAffected: coveredFiles,
   };
 }

package/src/review/pr-evidence.js

@@ -97,7 +97,8 @@ function formatPrEvidenceMarkdown(evidence, opts = {}) {
     L.push('### Review findings');
     for (const f of evidence.review.findings) {
       if (f.type === 'missing-tests') L.push(`- ⚠️ **missing tests** — \`${f.file}\` changed with no matching test`);
-      else if (f.type === 'security-file') L.push(`- ⚠️ **security-sensitive file** — \`${f.file}\``);
+      else if (f.type === 'security-file') L.push(`- ⚠️ **sensitive path touched** (path heuristic, not a content scan) — \`${f.file}\``);
+      else if (f.type === 'secret-detected') L.push(`- 🔑 **secret detected** (${f.secret}) — \`${f.file}\``);
       else if (f.type === 'god-node') L.push(`- ⚠️ **god node** — \`${f.file}\` → ${f.count} dependents (high blast radius)`);
       else if (f.type === 'scope-drift') L.push(`- ⚠️ **scope drift** — ${f.count} top-level dirs touched (${f.dirs.join(', ')})`);
     }

package/src/review/review-pr.js

@@ -9,8 +9,10 @@
  * zero-dependency, bundle-safe; reuses the impact graph for blast radius.
  */
 
+const fs = require('fs');
 const path = require('path');
 const { analyzeImpact } = require('../graph/impact');
+const { PATTERNS } = require('../security/patterns');
 
 const SECURITY_PATTERNS = [
   /(^|\/)\.env(\.|$)/i,
@@ -61,10 +63,30 @@ function reviewPr(changedFiles, cwd, opts = {}) {
     if (!covered) findings.push({ type: 'missing-tests', file: s, severity: 'warn' });
   }
 
-  // 2. Security-sensitive files.
+  // 2a. Sensitive-path heuristic — flags files whose PATH looks security-relevant
+  // (.env, auth/, lockfiles, workflows, key material). This is a path heuristic,
+  // NOT a content scan: it flags touching the path regardless of what changed,
+  // and cannot see a secret hidden in an innocently-named file. `basis` records
+  // that honestly so consumers don't mistake it for a content check.
   for (const f of live) {
     if (SECURITY_PATTERNS.some((re) => re.test(f.path))) {
-      findings.push({ type: 'security-file', file: f.path, severity: 'warn' });
+      findings.push({ type: 'security-file', file: f.path, severity: 'warn', basis: 'path-heuristic' });
+    }
+  }
+
+  // 2b. Real secret scan — read each changed file's CONTENT and match known
+  // secret patterns. This is the actual security check (content, not filename):
+  // it catches a hardcoded key in a file the path heuristic would never flag.
+  const readFile = opts.readFile || ((p) => fs.readFileSync(path.resolve(cwd, p), 'utf8'));
+  for (const f of live) {
+    let content;
+    try { content = readFile(f.path); } catch (_) { continue; } // absent/unreadable → skip
+    if (typeof content !== 'string' || content.length > 2_000_000) continue; // skip huge/binary
+    for (const pat of PATTERNS) {
+      if (pat.regex.test(content)) {
+        findings.push({ type: 'secret-detected', file: f.path, secret: pat.name, severity: 'high', basis: 'content-scan' });
+        break; // one hit is enough to flag the file
+      }
     }
   }
 

package/src/util/truncate.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * Visible truncation for extractor caps (v8.11).
+ *
+ * Extractors cap per-file signatures and per-class members to protect the token
+ * budget. Historically that truncation was SILENT — the tail of a large file
+ * simply vanished with no trace, so "5 of 40 methods extracted" looked identical
+ * to "fully extracted". These helpers keep the cap but append a visible marker
+ * so the loss is always disclosed.
+ *
+ * Zero-dependency, bundle-safe.
+ */
+
+/**
+ * Cap a string array, appending a `… +N more <label>` marker when items drop.
+ * @param {string[]} items
+ * @param {number} limit
+ * @param {string} label e.g. 'signatures'
+ * @returns {string[]}
+ */
+function capWithNotice(items, limit, label) {
+  if (!Array.isArray(items) || items.length <= limit) return items;
+  const dropped = items.length - limit;
+  return items.slice(0, limit).concat(`… +${dropped} more ${label}`);
+}
+
+/**
+ * Cap an array of member objects ({ text, ... }), appending a marker member
+ * when items drop so the class block discloses the omission.
+ * @param {Array<{text:string}>} members
+ * @param {number} limit
+ * @param {string} [label='methods']
+ * @returns {Array<{text:string}>}
+ */
+function capMembersWithNotice(members, limit, label = 'methods') {
+  if (!Array.isArray(members) || members.length <= limit) return members;
+  const dropped = members.length - limit;
+  return members.slice(0, limit).concat({ text: `… +${dropped} more ${label}`, start: 0, end: 0 });
+}
+
+module.exports = { capWithNotice, capMembersWithNotice };