kritmatta-lead-scorer 1.2.0 → 1.2.2

package/README.md

@@ -5,16 +5,34 @@ app (`hire-chat-next-app`) and the enrichment worker (`enrichment-worker`) so th
 scoring logic can never drift between them.
 
 ## What's in it
-- `scorer.js` - weight-profile scorer with per-ICP `signal_overrides` (the app UI
-  and the worker score identically). Hiring intent is read from either the website
-  scrape (`tier2.hiring_signals.hiring_velocity`) or a native LinkedIn-jobs signal
-  (`enrichment_data.hiring_signal`, from the app's hiringSignalService) - so a
-  company hiring a relevant role scores even before any website enrichment.
+- `scorer.js` - the LIVE (v1) weight-profile scorer with per-ICP `signal_overrides`
+  (the app UI and the worker score identically). Hiring intent is read from either
+  the website scrape (`tier2.hiring_signals.hiring_velocity`) or a native
+  LinkedIn-jobs signal (`enrichment_data.hiring_signal`, from the app's
+  hiringSignalService) - so a company hiring a relevant role scores even before
+  any website enrichment. Also exports the weight-profile key allowlists
+  (`VALID_SIGNAL_OVERRIDE_KEYS`, `VALID_CATEGORY_MULTIPLIER_KEYS`,
+  `VALID_V2_CONFIG_KEYS`) - writers must validate against them because the
+  scorer silently ignores unknown keys.
+- `scorerV2.js` - the SHADOW (v2) fit-gated scorer:
+  `score = 100 * fit^strictness * (floor + (1-floor) * quality) + capped intent`.
+  Fit is earned/evidenced over the ICP's defined core criteria (bonus criteria
+  only lift), disqualifiers hard-cap the score, and category multipliers act as
+  normalized intra-axis weights. `scoreLeadsMultiIcp` computes it alongside v1
+  on every rescore and persists `qualification.shadow_v2` - observability only,
+  nothing live reads it until cutover. A v2 load failure disables the shadow;
+  it can never break live v1 scoring. Per-ICP tunables: `weight_profile.v2`.
+- `contextMatch.js` - stemmed token-overlap matching for ICP fit/bad-fit phrases
+  (used by v2; v1 still uses verbatim substring matching).
 - `decay.js` - intent-signal time decay.
 - `reasoningRewriter.js` - optional LLM rephrasing of the deterministic reasoning.
   The AI call is **dependency-injected** so this package has no app/worker-specific
   requires.
 
+Consumer shims in both repos re-export the package ROOT (not the `/scorer`
+subpath) so v1 and v2 entry points are reachable everywhere. Run `npm test`
+(no server or credentials needed) before publishing.
+
 ## Install
 Public package on npmjs.com - no auth or `.npmrc` needed:
 

package/contextMatch.js

@@ -39,20 +39,27 @@ function stem(word) {
   return w;
 }
 
-/** Two stems match when one is a prefix of the other and both are >= 4 chars
- *  (or exactly equal for short stems). Absorbs stemmer roughness (hir/hire). */
+/** Two stems match when equal, or when one is a prefix of the other with at
+ *  most ONE trailing char of difference (absorbs stemmer roughness like
+ *  hir/hire, plann/plan). A looser prefix rule produced semantic false
+ *  positives (firm/firmware, care/career, part/partner) that are unacceptable
+ *  because a single bad-fit phrase match hard-caps the score. */
 function stemsMatch(a, b) {
   if (a === b) return true;
   if (a.length < 4 || b.length < 4) return false;
+  if (Math.abs(a.length - b.length) > 1) return false;
   return a.startsWith(b) || b.startsWith(a);
 }
 
-/** Tokenize free text into deduplicated stemmed content words. */
+/** Tokenize free text into deduplicated stemmed content words. Two-char
+ *  tokens are KEPT - domain acronyms (HR, AI, VC, UK, ML) carry the meaning
+ *  of many ICP phrases, and dropping them degraded phrases like "no HR team"
+ *  to a single generic word that matched everything. */
 function contentStems(text) {
   if (!text || typeof text !== 'string') return [];
   const out = new Set();
   for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
-    if (raw.length < 3) continue;
+    if (raw.length < 2) continue;
     if (STOPWORDS.has(raw)) continue;
     out.add(stem(raw));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritmatta-lead-scorer",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Lead qualification scorer - weight-profile scoring with per-ICP signal overrides and provenance-scoped multi-product candidacy. Single source of truth shared by the Vega app and the enrichment worker.",
   "main": "index.js",
   "files": [

package/scorer.js

@@ -17,13 +17,19 @@
 const { decayScore } = require('./decay');
 
 // Lazy require: scorerV2 requires this module for shared helpers, so a
-// top-level require here would be circular. Resolved on first use instead.
+// top-level require here would be circular. Guarded so a v2 load failure can
+// never take down live v1 scoring - shadow scoring just switches off.
 let _scorerV2 = null;
 function getScorerV2() {
   if (_scorerV2 === null) {
-    _scorerV2 = require('./scorerV2');
+    try {
+      _scorerV2 = require('./scorerV2');
+    } catch (err) {
+      console.error('[scorer] scorerV2 failed to load - shadow scoring disabled:', err.message);
+      _scorerV2 = false;
+    }
   }
-  return _scorerV2;
+  return _scorerV2 || null;
 }
 
 // Lazy require so the rewriter is only loaded when actually used; keeps the
@@ -1089,8 +1095,9 @@ async function scoreLeadsMultiIcp(leads, job, supabase, options = {}) {
     // Shadow v2 (fit-gated model): computed alongside v1 for observability,
     // never drives live scores. Tracks v2's own best ICP plus the v2 score for
     // whichever ICP v1 picks, so distribution and best-ICP drift are both
-    // measurable from persisted data.
-    const { scoreLeadV2, toShadowSummary } = getScorerV2();
+    // measurable from persisted data. v2mod is null if scorerV2 failed to
+    // load - live v1 scoring proceeds without the shadow.
+    const v2mod = getScorerV2();
     const v2ByIcp = {};
     let v2Best = null;
     const icpRows = [];
@@ -1115,17 +1122,19 @@ async function scoreLeadsMultiIcp(leads, job, supabase, options = {}) {
         _icp_context: icp.context,
       }, globalConfig);
 
-      try {
-        const v2 = scoreLeadV2(lead, {
-          ...icp.criteria,
-          _icp_name: icp.name,
-          _icp_context: icp.context,
-        }, globalConfig);
-        v2ByIcp[icp.id] = v2;
-        if (!v2Best || v2.score > v2Best.result.score) v2Best = { icpId: icp.id, result: v2 };
-      } catch (v2Err) {
-        // Shadow scoring must never break live scoring
-        console.error(`[scorer] shadow v2 failed for lead ${lead.id} icp ${icp.id}:`, v2Err.message);
+      if (v2mod) {
+        try {
+          const v2 = v2mod.scoreLeadV2(lead, {
+            ...icp.criteria,
+            _icp_name: icp.name,
+            _icp_context: icp.context,
+          }, globalConfig);
+          v2ByIcp[icp.id] = v2;
+          if (!v2Best || v2.score > v2Best.result.score) v2Best = { icpId: icp.id, result: v2 };
+        } catch (v2Err) {
+          // Shadow scoring must never break live scoring
+          console.error(`[scorer] shadow v2 failed for lead ${lead.id} icp ${icp.id}:`, v2Err.message);
+        }
       }
 
       icpRows.push({
@@ -1152,9 +1161,11 @@ async function scoreLeadsMultiIcp(leads, job, supabase, options = {}) {
     if (icps.length === 0) {
       bestResult = scoreLeadFromEnrichment(lead, null, globalConfig);
       bestScore = bestResult.score;
-      try {
-        v2Best = { icpId: null, result: scoreLeadV2(lead, null, globalConfig) };
-      } catch { /* shadow only */ }
+      if (v2mod) {
+        try {
+          v2Best = { icpId: null, result: v2mod.scoreLeadV2(lead, null, globalConfig) };
+        } catch { /* shadow only */ }
+      }
     }
 
     // For meaningful scores, ask the rewriter to rephrase reasoning in the
@@ -1194,9 +1205,9 @@ async function scoreLeadsMultiIcp(leads, job, supabase, options = {}) {
       // Shadow v2 fit-gated score - additive, observability only. `icp_id`
       // inside is v1's best ICP (same lead-level comparison basis as `score`);
       // v2_best records which ICP v2 itself would pick.
-      shadow_v2: v2ForV1Best
+      shadow_v2: v2mod && v2ForV1Best
         ? {
-            ...toShadowSummary(v2ForV1Best, bestIcpId),
+            ...v2mod.toShadowSummary(v2ForV1Best, bestIcpId),
             v2_best: v2Best ? { icp_id: v2Best.icpId, score: v2Best.result.score } : null,
           }
         : null,

package/scorerV2.js

@@ -31,7 +31,7 @@
  */
 
 const { decayScore } = require('./decay');
-const { buildCorpusMatcher } = require('./contextMatch');
+const { buildCorpusMatcher, contentStems } = require('./contextMatch');
 const {
   normalizeIcpCriteria,
   _internal: {
@@ -127,18 +127,21 @@ function round2(x) {
 function resolveV2Config(icp) {
   const v2 = icp?.weight_profile?.v2 || {};
   const ov = icp?.weight_profile?.signal_overrides || {};
+  const num = (x) => (typeof x === 'number' ? x : undefined);
   const cfg = { ...V2_DEFAULTS };
   for (const key of Object.keys(V2_DEFAULTS)) {
-    if (typeof v2[key] === 'number') cfg[key] = v2[key];
+    if (num(v2[key]) !== undefined) cfg[key] = v2[key];
   }
-  // Honor the v1 overrides that translate cleanly into v2 semantics.
-  if (typeof ov.fit_signal_cap === 'number' && v2.fit_signal_cap === undefined) {
+  // Honor the v1 overrides that translate cleanly into v2 semantics. Guards
+  // use the same numeric check as the v2 loop, so a malformed (non-numeric)
+  // v2 value falls through to the legacy override rather than to defaults.
+  if (num(ov.fit_signal_cap) !== undefined && num(v2.fit_signal_cap) === undefined) {
     cfg.fit_signal_cap = ov.fit_signal_cap;
   }
-  if (typeof ov.bad_signal_cap === 'number' && v2.bad_signal_cap === undefined) {
+  if (num(ov.bad_signal_cap) !== undefined && num(v2.bad_signal_cap) === undefined) {
     cfg.bad_signal_cap = ov.bad_signal_cap;
   }
-  if (typeof ov.industry_mismatch === 'number' && v2.mismatch_fraction === undefined) {
+  if (num(ov.industry_mismatch) !== undefined && num(v2.mismatch_fraction) === undefined) {
     // v1 default penalty is -25 against a +25-weight criterion; scale linearly
     // (override of 0 = mismatch costs nothing, -50 = subtracts 1.44x weight).
     cfg.mismatch_fraction = Math.abs(ov.industry_mismatch) / 25 * V2_DEFAULTS.mismatch_fraction;
@@ -185,6 +188,32 @@ function resolveAxisWeights(icp) {
   return { fit, quality, intentMultiplier: m.intent };
 }
 
+// ---------------------------------------------------------------------------
+// Context phrase eligibility
+// ---------------------------------------------------------------------------
+
+const NEGATION_LEAD = /^(no|not|without|non|never|zero|lacks?|lacking|doesn'?t|don'?t|isn'?t|aren'?t)\b/i;
+const NUMERIC_COMPARISON = /\b(under|over|below|above|less than|fewer than|more than|at least|at most|maximum|minimum|min|max|<|>)\s*\d/i;
+
+/**
+ * A phrase participates in context matching only when presence-in-corpus is a
+ * meaningful test of it. Three classes are NOT and are skipped entirely
+ * (numerator AND denominator, so ratios stay fair):
+ *  - single-content-word phrases ("investment", "carbon") - one generic word
+ *    matches nearly any corpus, and on the bad-fit side one match hard-caps;
+ *  - negation-led phrases ("no sustainability focus") - matching the words'
+ *    PRESENCE inverts the author's intent;
+ *  - numeric comparisons ("headcount under 10") - substring/token matching
+ *    cannot evaluate a threshold.
+ * All three classes were exactly the false bad-fit caps observed in the
+ * 2026-09-08 full-population audit (94.8k leads).
+ */
+function presenceCheckable(phrase) {
+  if (NEGATION_LEAD.test(phrase)) return false;
+  if (NUMERIC_COMPARISON.test(phrase)) return false;
+  return contentStems(phrase).length >= 2;
+}
+
 // ---------------------------------------------------------------------------
 // Fit axis
 // ---------------------------------------------------------------------------
@@ -296,14 +325,15 @@ function scoreFitAxis(lead, icp, weights, cfg, matcher) {
     add('geography', true, evidence, match ? 1 : 0, match ? 'Geography matches' : null);
   }
 
-  // Funding stage
+  // Funding stage - check ALL observed stages (tier4 signal AND tier2), same
+  // as v1: a stale tier4 stage must not mask a matching tier2.funding_stage
   const fundingDefined = (icp.funding_stages?.length || 0) > 0;
   if (fundingDefined) {
     const fundingSignal = tier4?.signals?.find?.((s) => s.type === 'recent_funding');
-    const observed = fundingSignal?.data?.stage || tier2?.funding_stage || null;
-    const evidence = !!observed;
-    const match = evidence && icp.funding_stages.some(
-      (f) => f.toLowerCase() === observed.toLowerCase()
+    const observedStages = [fundingSignal?.data?.stage, tier2?.funding_stage].filter(Boolean);
+    const evidence = observedStages.length > 0;
+    const match = evidence && observedStages.some((o) =>
+      icp.funding_stages.some((f) => f.toLowerCase() === o.toLowerCase())
     );
     if (match) signals.push('icp_funding_match');
     add('funding', true, evidence, match ? 1 : 0, match ? 'Funding stage matches' : null);
@@ -326,23 +356,24 @@ function scoreFitAxis(lead, icp, weights, cfg, matcher) {
     add('tech_stack', true, evidence, ratio, ratio > 0 ? 'Tech stack matches' : null);
   }
 
-  // Context fit signals (great_fit_signals + pain_solved), token-overlap matched
+  // Context fit signals (great_fit_signals + pain_solved), token-overlap
+  // matched. Deduplicate BEFORE the denominator - a phrase repeated across
+  // both fields can only ever match once, so counting it twice in the
+  // denominator structurally depresses the ratio. Phrases that presence
+  // matching cannot evaluate are excluded entirely (see presenceCheckable).
   const context = icp._icp_context;
   const fitPhrases = context
-    ? [
+    ? [...new Set([
         ...tokenizeContextSignals(context.great_fit_signals),
         ...tokenizeContextSignals(context.pain_solved),
-      ]
+      ])].filter(presenceCheckable)
     : [];
   if (fitPhrases.length > 0) {
     const evidence = !!matcher;
     let matches = 0;
     if (evidence) {
-      const seen = new Set();
       for (const phrase of fitPhrases) {
         if (matches >= cfg.fit_signal_cap) break;
-        if (seen.has(phrase)) continue;
-        seen.add(phrase);
         if (matcher.phraseMatches(phrase)) {
           matches++;
           signals.push(`context_fit:${phrase}`);
@@ -354,8 +385,13 @@ function scoreFitAxis(lead, icp, weights, cfg, matcher) {
       matches > 0 ? `${matches} fit signal match${matches > 1 ? 'es' : ''}` : null);
   }
 
-  // Bad-fit signals - hard cap, not subtraction
-  const badPhrases = context ? tokenizeContextSignals(context.bad_fit_signals) : [];
+  // Bad-fit signals - hard cap, not subtraction. The presenceCheckable filter
+  // matters most here: the 2026-09-08 full-population audit showed every
+  // false bad-fit cap came from an un-checkable phrase (single generic word,
+  // negation, or numeric comparison).
+  const badPhrases = context
+    ? tokenizeContextSignals(context.bad_fit_signals).filter(presenceCheckable)
+    : [];
   if (badPhrases.length > 0 && matcher) {
     let badMatches = 0;
     const seenBad = new Set();
@@ -509,7 +545,9 @@ function scoreIntentBonus(lead, cfg, intentMultiplier) {
       }
     }
   }
-  return { bonus: Math.min(points * (intentMultiplier || 1), cfg.intent_cap), raw: points, signals };
+  // 0 is a valid multiplier (tenant disabled intent) - only default when unset
+  const mult = typeof intentMultiplier === 'number' ? intentMultiplier : 1;
+  return { bonus: Math.min(points * mult, cfg.intent_cap), raw: points, signals };
 }
 
 // ---------------------------------------------------------------------------