@gafj/gafj 0.1.1

package/core/scoring.js

@@ -0,0 +1,586 @@
+"use strict";
+
+/**
+ * Requirement Scoring Engine (Update Spec Part K).
+ *
+ * Turns the loop from "build -> send -> rejected -> diagnose" into
+ * "build -> score -> fix weak category -> send". The Quince rejection cost a
+ * real opportunity before anyone learned what was wrong with the document.
+ *
+ * DIVISION OF LABOUR. These helpers do the deterministic half and leave the
+ * judgement to the model that called the MCP tool. That split is deliberate:
+ *
+ *   - K6 names self-grading as the core hazard: a generator scoring its own
+ *     output against its own rubric will flatter itself. The mitigation that
+ *     actually bites is structural, so the rubric is pinned to the posting's
+ *     verbatim text and the mechanical checks below run on the document rather
+ *     than on anyone's opinion of the candidate.
+ *   - exports.mcp is public and token authed, unlike generateResume which is
+ *     locked to an allow listed Google account. Calling Claude from inside it
+ *     would turn a shared token into a spend proxy for arbitrary input.
+ *
+ * So: the server extracts evidence, runs the mechanical gates, and hands back a
+ * rubric. The caller reasons. Nothing here needs an API key.
+ *
+ * The pre-send gate near the bottom of this file sits on the deterministic side
+ * of that line, and only just: it does no judging of its own. The caller still
+ * supplies every weight and every score. Arithmetic on numbers the caller chose
+ * is not judgement, and it is the one part of Part K that a caller must not be
+ * able to decline.
+ */
+
+// G1 detection triggers, verbatim from the spec.
+const AI_TRIGGERS = [
+  "artificial intelligence", "machine learning", "agent orchestration",
+  "prompt engineering", "context engineering", "responsible ai", "ai governance",
+  "agentic", "automation", "emerging technolog", "llm", "agent", "ai", "ml",
+];
+// Matched whole-word so "ai" does not fire on "email" and "ml" not on "html".
+const WORD_TRIGGERS = new Set(["ai", "ml", "llm", "agent", "agentic", "automation"]);
+
+const HARD_GATE_CUES = [
+  "required", "must have", "must be", "minimum", "at least", "years of experience",
+  "years experience", "bachelor", "degree in", "certification",
+];
+
+// A4 retired phrasings that must never reach a document.
+const RETIRED = [
+  { pattern: /\$?~?\s*8M\s+annual\s+book/i, use: "Grew new business 70%+, from $5.68M (2024) to $9.7M annualized (2025), or the $1.44M monthly run rate" },
+  { pattern: /havenly/i, use: "Onboarded 30+ furniture retail clients in 9 months" },
+  { pattern: /15\+?\s*years\s+selling/i, use: "15+ years across operations, distribution, and fulfillment, including 3+ years in dedicated 3PL and logistics business development" },
+];
+
+// G2 protected bullets for operations, process improvement, and supply chain
+// roles. Trimming one of these is a regression, not a length decision.
+const PROTECTED = [
+  { id: "acc-062", label: "Damage 12% to 4%, roughly $120K per year, root cause" },
+  { id: "acc-046", label: "$430K to $75K aged returns liability" },
+  { id: "acc-054", label: "$100K+ carrier misbillings recovered in 60 days" },
+  { id: "acc-038", label: "Freight down 29.3%" },
+  { id: "acc-051", label: "Shipment cost $178 to $138" },
+  { id: "acc-052", label: "Freight 11.3% to 8.9% of revenue" },
+  { id: "acc-073", label: "50+ person organization" },
+  { id: "acc-011", label: "30+ client onboardings in 9 months" },
+  { id: "acc-034", label: "Open tickets down 87%" },
+  { id: "acc-037", label: "Zero untouched cases" },
+  { id: "acc-064", label: "Internal theft discovery, $70K, conviction, controls" },
+];
+
+const STOP = new Set(("a an the and or of to in on for with by at from into as is are was were that which " +
+  "through while over under across all any not no more than its their our this these those it be been being " +
+  "have has had do does did will would can could should you your we they i he she them his her ability " +
+  "experience work working role team teams years year new other including include includes such etc via per " +
+  "using use used strong excellent ensure ensuring support supporting manage managing management").split(" "));
+
+/**
+ * Conservative suffix stemmer. Without it "organizations" misses
+ * "organization" and "mentoring" misses "mentorship", which is most of why a
+ * leadership requirement failed to find the one leadership accomplishment.
+ * Deliberately shallow: over stemming invents matches, which is worse here than
+ * missing one, because a false Strong sends a bullet to a posting it does not
+ * answer.
+ */
+function stem(w) {
+  if (w.length > 4 && w.endsWith("ies")) return w.slice(0, -3) + "y";
+  if (w.length > 6 && (w.endsWith("ship") || w.endsWith("ment"))) return w.slice(0, -4);
+  if (w.length > 5 && w.endsWith("ing")) return w.slice(0, -3);
+  if (w.length > 5 && w.endsWith("ed")) return w.slice(0, -2);
+  if (w.length > 4 && w.endsWith("ly")) return w.slice(0, -2);
+  if (w.length > 3 && w.endsWith("s") && !w.endsWith("ss")) return w.slice(0, -1);
+  return w;
+}
+
+function words(text) {
+  return (String(text).toLowerCase().match(/[a-z][a-z+&.]{2,}/g) || [])
+    .filter((w) => !STOP.has(w))
+    .map(stem)
+    .filter((w) => w.length > 2 && !STOP.has(w));
+}
+
+/**
+ * Concept bridges from a posting's vocabulary to the knowledge base's curated
+ * tags. Lexical overlap alone cannot connect "influencing partners,
+ * organizations, successful mentoring" to a bullet whose words are "de facto
+ * leadership", "directing", "BPO", and "temporary staff", and that specific
+ * failure is the one K2 exists to prevent: a leadership requirement answered
+ * with revenue bullets because they happened to share the word "growth".
+ * Tags are curated, so bridging to them is the honest fix.
+ */
+const CONCEPT_TAGS = [
+  { cue: /\b(leader|leadership|mentor|coach|influenc|supervis|direct report|people manage|growing teams?|develop(ing)? (people|others|talent))/i,
+    tags: ["people leadership", "leading leaders", "direct reports", "leadership"] },
+  { cue: /\b(root cause|corrective action|discrepanc|defect|quality review|damage)/i,
+    tags: ["process improvement", "analytics"] },
+  { cue: /\b(ai\b|artificial intelligence|machine learning|agent|prompt|automation)/i,
+    tags: ["ai and automation", "technology"] },
+  { cue: /\b(return|reverse logistic|rma|refund|claim)/i, tags: ["reverse logistics"] },
+  { cue: /\b(freight|carrier|parcel|transportation|shipping cost)/i, tags: ["transportation"] },
+  { cue: /\b(vendor|supplier|3pl|outsourc|partner performance)/i, tags: ["vendor management"] },
+  { cue: /\b(forecast|inventory|stock|replenish)/i, tags: ["inventory", "forecasting", "supply chain"] },
+  { cue: /\b(p&l|budget|cost control|margin|financial)/i, tags: ["financial impact"] },
+];
+
+function conceptTags(requirementText) {
+  const hit = new Set();
+  for (const c of CONCEPT_TAGS) {
+    if (c.cue.test(requirementText)) for (const t of c.tags) hit.add(t);
+  }
+  return hit;
+}
+
+function lines(text) {
+  return String(text).split(/\r?\n|(?<=[.;])\s{2,}/).map((l) => l.trim()).filter(Boolean);
+}
+
+/** Every figure in a document: money, percents, counts, durations. */
+function metrics(text) {
+  const out = new Set();
+  const re = /\$\s?\d[\d,]*(?:\.\d+)?\s?[MK]?\+?|\d[\d,]*(?:\.\d+)?\s?%\+?|\b\d[\d,]{2,}\+?\b|\b\d+\+\s*(?:person|member|people|clients?|employees?|years?|days?|months?|weeks?)\b|\b\d+\s*(?:days?|months?|weeks?|years?)\b/gi;
+  let m;
+  while ((m = re.exec(text))) out.add(m[0].replace(/\s+/g, " ").trim());
+  return out;
+}
+
+/** $430,000 and $430K are the same claim; compare on digits alone. */
+function metricKey(s) {
+  const digits = String(s).replace(/[^0-9.]/g, "");
+  const scale = /k\b/i.test(s) ? 1e3 : /m\b/i.test(s) ? 1e6 : 1;
+  const n = parseFloat(digits);
+  if (!isFinite(n)) return String(s).toLowerCase();
+  const unit = /%/.test(s) ? "%" : /\$/.test(s) ? "$" : "";
+  return unit + String(Math.round(n * scale));
+}
+
+/**
+ * PASS 1 (K1) — deterministic reconnaissance on the posting.
+ * Produces the scaffolding a category extraction needs, never the categories
+ * themselves: weighting has to come from the employer's emphasis, and that is
+ * a judgement the caller makes against the quoted text.
+ */
+function scanJobDescription(jdText) {
+  const text = String(jdText || "");
+  const ls = lines(text);
+  const lower = text.toLowerCase();
+
+  const aiHits = [];
+  for (const t of AI_TRIGGERS) {
+    const re = WORD_TRIGGERS.has(t)
+      ? new RegExp("(^|[^a-z])" + t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "([^a-z]|$)", "i")
+      : new RegExp(t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i");
+    const line = ls.find((l) => re.test(l));
+    if (line) aiHits.push({ term: t, line });
+  }
+
+  const hardGateLines = ls.filter((l) => HARD_GATE_CUES.some((c) => l.toLowerCase().includes(c)));
+
+  // Minimum vs preferred matters for weighting: a requirement in the minimum
+  // block outranks the same words in preferred.
+  const sections = {};
+  let current = "body";
+  for (const l of ls) {
+    const h = l.toLowerCase();
+    if (/^(minimum|basic|required)\b.*qualification|^requirements\b/.test(h)) current = "minimum";
+    else if (/^(preferred|nice to have|bonus)\b/.test(h)) current = "preferred";
+    else if (/^(responsibilities|what you.?ll do|the role)\b/.test(h)) current = "responsibilities";
+    (sections[current] = sections[current] || []).push(l);
+  }
+
+  const excluded = ["uline", "estes forwarding", "efw"].filter((e) => lower.includes(e));
+
+  return {
+    aiTriggerFired: aiHits.length > 0,
+    aiTriggers: aiHits,
+    hardGateLines,
+    sections: Object.fromEntries(Object.entries(sections).map(([k, v]) => [k, v.length])),
+    sectionText: sections,
+    excludedEmployerDetected: excluded,
+    lineCount: ls.length,
+  };
+}
+
+/**
+ * PASS 1b (K2) — evidence ranking, the highest value part of Part K. It has to
+ * make the JobDox miss structurally impossible: a Leadership category surfaces
+ * the 50+ person organization whether or not anyone remembered it existed.
+ *
+ * Plain term overlap does NOT do that, which the first cut proved. A leadership
+ * requirement mentions "growth", "partners", and "organizations", and those
+ * words are everywhere in a logistics record, so revenue bullets outranked the
+ * one accomplishment that exists to answer leadership. Three corrections:
+ *
+ *   - IDF. A term that appears in half the knowledge base carries almost no
+ *     signal; one that appears twice carries most of it. "mentoring" should
+ *     outweigh "experience" by an order of magnitude, and it now does.
+ *   - Bigrams. "root cause" and "agent orchestration" are single concepts, and
+ *     scoring their halves separately is what let an LTL rate discrepancy win a
+ *     root cause query on the word "discrepancy".
+ *   - Tag weighting. Tags are curated rather than incidental, so a hit there is
+ *     worth more than the same word buried in prose.
+ */
+let IDF_CACHE = null;
+function idf(KB) {
+  if (IDF_CACHE && IDF_CACHE.kb === KB) return IDF_CACHE.map;
+  const df = new Map();
+  for (const a of KB) {
+    for (const w of new Set(terms(accomplishmentText(a)))) df.set(w, (df.get(w) || 0) + 1);
+  }
+  const N = KB.length;
+  const map = new Map();
+  for (const [w, n] of df) map.set(w, Math.log((N + 1) / (n + 0.5)));
+  IDF_CACHE = { kb: KB, map };
+  return map;
+}
+
+function accomplishmentText(a) {
+  return [a.title, a.summary, (a.wordings || []).map((w) => w.text).join(" "),
+    (a.tags || []).join(" "), (a.skills || []).join(" "), (a.industries || []).join(" ")].join(" ");
+}
+
+/** Unigrams plus adjacent bigrams, so multi word concepts survive. */
+function terms(text) {
+  const w = words(text);
+  const out = w.slice();
+  for (let i = 0; i < w.length - 1; i += 1) out.push(w[i] + " " + w[i + 1]);
+  return out;
+}
+
+function rankEvidence(requirementText, KB, limit) {
+  const want = new Map();
+  for (const t of terms(requirementText)) want.set(t, (want.get(t) || 0) + 1);
+  if (!want.size) return [];
+  const weights = idf(KB);
+  // An unseen term is rare by definition, so give it the ceiling rather than
+  // dropping it: a posting saying "dock scheduler" should not score as silence.
+  const MAX_IDF = Math.log((KB.length + 1) / 0.5);
+  let total = 0;
+  for (const t of want.keys()) total += weights.get(t) || MAX_IDF;
+
+  const concepts = conceptTags(requirementText);
+  const scored = KB.map((a) => {
+    const have = new Set(terms(accomplishmentText(a)));
+    const tagged = new Set(terms([(a.tags || []).join(" "), (a.skills || []).join(" ")].join(" ")));
+    let earned = 0;
+    let hits = 0;
+    for (const t of want.keys()) {
+      if (!have.has(t)) continue;
+      hits += 1;
+      earned += (weights.get(t) || MAX_IDF) * (tagged.has(t) ? 1.6 : 1);
+    }
+    // A curated tag the requirement's concept maps to is stronger evidence than
+    // any single shared word, so it is scored against the same denominator
+    // rather than as a tiebreak.
+    let conceptHits = 0;
+    if (concepts.size) {
+      const own = new Set((a.tags || []).map((t) => t.toLowerCase()));
+      for (const c of concepts) if (own.has(c)) conceptHits += 1;
+      earned += conceptHits * MAX_IDF * 0.9;
+      hits += conceptHits;
+    }
+    const coverage = total ? earned / total : 0;
+    return { id: a.id, title: a.title, company: a.company, hits, conceptHits, coverage,
+      score: coverage * 100 + (a.strengthScore || 0) / 1000 };
+  }).filter((r) => r.hits > 0).sort((x, y) => y.score - x.score);
+
+  return scored.slice(0, limit || 5).map((r) => ({
+    accomplishmentId: r.id,
+    title: r.title,
+    company: r.company,
+    termsMatched: r.hits,
+    weightedCoverage: Number(r.coverage.toFixed(3)),
+    // Coarse on purpose. The caller assigns final strength after reading the
+    // text; this is a shortlist, not a verdict.
+    evidence_strength: r.coverage >= 0.20 ? "Strong" : r.coverage >= 0.08 ? "Moderate" : "Weak",
+  }));
+}
+
+/**
+ * PASS 2 mechanical gates (F2, F3, A4, B7, C3).
+ * F2 says the substantiation check "is a mechanical check. Automate it if
+ * possible." This is that automation, plus the style and traceability rules
+ * that never needed a model in the first place.
+ */
+function auditResume(resumeText, KB) {
+  const raw = String(resumeText || "");
+  // The phone number is digits that are not a metric. Strip it before any
+  // figure extraction or 847, 302, and 2310 get audited as career claims.
+  const text = raw.replace(/\b\d{3}[-.\s]?\d{3}[-.\s]?\d{4}\b/g, " ");
+  const findings = [];
+
+  /**
+   * A highlight metric is substantiated when the body carries it, OR when the
+   * body carries a different metric from the same accomplishment. "Recovered
+   * inside 60 days" in a highlight and "within the first two months in role" in
+   * the body are one claim in two units, and F2 exists to catch missing
+   * evidence, not to police unit choice.
+   */
+  const sameEvidenceInBody = (metricKeyValue, bodyKeys) =>
+    KB.some((a) => {
+      const own = new Set([...metrics([a.summary, (a.metrics || []).join(" "),
+        (a.wordings || []).map((w) => w.text).join(" ")].join(" "))].map(metricKey));
+      if (!own.has(metricKeyValue)) return false;
+      for (const k of own) if (k !== metricKeyValue && bodyKeys.has(k)) return true;
+      return false;
+    });
+
+  // F2: every metric claimed in Career Highlights must appear in a body bullet.
+  const hi = text.search(/career\s+highlights/i);
+  const body = text.search(/\b(experience|logistics\s*&?\s*operations\s+experience|process\s+improvement)\b/i);
+  if (hi !== -1 && body > hi) {
+    const highlightMetrics = metrics(text.slice(hi, body));
+    const bodyKeys = new Set([...metrics(text.slice(body))].map(metricKey));
+    const unsubstantiated = [...highlightMetrics].filter((m) => {
+      const k = metricKey(m);
+      return !bodyKeys.has(k) && !sameEvidenceInBody(k, bodyKeys);
+    });
+    if (unsubstantiated.length) {
+      findings.push({
+        rule: "F2", severity: "blocker",
+        detail: "Career Highlights claim metrics with no supporting body bullet: " + unsubstantiated.join(", "),
+        action: "Restore the body bullet, or drop the claim from the highlight. Never cut the evidence to keep the summary.",
+      });
+    }
+  } else if (hi === -1) {
+    findings.push({ rule: "B1", severity: "blocker", detail: "No Career Highlights block found.", action: "Add five highlights immediately after the header." });
+  }
+
+  // A4: retired phrasings.
+  for (const r of RETIRED) {
+    if (r.pattern.test(text)) {
+      findings.push({ rule: "A4", severity: "blocker", detail: "Retired phrasing present: " + (text.match(r.pattern) || [])[0], action: "Use instead: " + r.use });
+    }
+  }
+
+  // B7 house style.
+  const dashes = (text.match(/[‐-―]/g) || []).length;
+  const hyphens = (text.replace(/\b\d{3}-\d{3}-\d{4}\b/g, "").match(/-/g) || []).length;
+  if (dashes + hyphens > 0) {
+    findings.push({ rule: "B7", severity: "blocker", detail: `${dashes} en/em dashes and ${hyphens} hyphens outside the phone number.`, action: "Remove every dash. Compound modifiers are written as separate words." });
+  }
+  if (/e-commerce/i.test(text)) findings.push({ rule: "B7", severity: "blocker", detail: 'Spelled "e-commerce".', action: 'Write "ecommerce".' });
+  if (/\bP and L\b/i.test(text)) findings.push({ rule: "B7", severity: "blocker", detail: 'Spelled "P and L".', action: 'Write "P&L".' });
+  if (/\bpercent\b/i.test(text)) findings.push({ rule: "B7", severity: "warning", detail: 'Uses the word "percent".', action: "Use the % symbol." });
+
+  // C3: every figure in the document must be traceable to the knowledge base.
+  const kbKeys = new Set();
+  for (const a of KB) {
+    for (const m of metrics([a.summary, (a.metrics || []).join(" "), (a.wordings || []).map((w) => w.text).join(" ")].join(" "))) kbKeys.add(metricKey(m));
+  }
+  const YEARS = /^(19|20)\d\d$/;
+  const untraceable = [...metrics(text)].filter((m) => !kbKeys.has(metricKey(m)) && !YEARS.test(m.replace(/[^0-9]/g, "")));
+  if (untraceable.length) {
+    findings.push({
+      rule: "C3", severity: "review",
+      detail: "Figures with no exact knowledge base match: " + untraceable.slice(0, 12).join(", "),
+      action: "Confirm each is a compact rendering of a KB value ($430K for $430,000) and not a calculation, rounding, or combination. Anything else must come out.",
+    });
+  }
+
+  // F3 bullet floors, counted per employer entry.
+  const entries = [...text.matchAll(/^(.+?)\s*\|\s*(.+?)\s+((?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec|\d{4}).*)$/gim)];
+  if (entries.length) {
+    const counts = entries.map((m, i) => {
+      const start = m.index + m[0].length;
+      const end = i + 1 < entries.length ? entries[i + 1].index : text.length;
+      const seg = text.slice(start, end);
+      return { entry: (m[1] + " | " + m[2]).trim(), bullets: lines(seg).filter((l) => l.length > 40).length };
+    });
+    const thin = counts.slice(0, 4).filter((c) => c.bullets < 2);
+    if (thin.length) {
+      findings.push({ rule: "F3", severity: "warning", detail: "Entries among the four most recent with fewer than two bullets: " + thin.map((t) => t.entry).join("; "), action: "Minimum 2, target 3. A one bullet entry reads as a thin role." });
+    }
+  }
+
+  // H1: Civil Air Patrol survives section moves.
+  if (!/civil air patrol/i.test(text)) {
+    findings.push({ rule: "H1", severity: "warning", detail: "Civil Air Patrol is absent.", action: "Mandatory whenever the posting states a leadership requirement. It is one of only two places in the record showing leadership at 50+ scale." });
+  }
+
+  return findings;
+}
+
+/**
+ * PASS 2 pre-send gate (Part K).
+ *
+ * "If any category with weight >= 8 scores below 7, regenerate before sending.
+ * Do not treat the score as advisory." That rule lived only as prose inside the
+ * rubric, which made it a request rather than a gate: a caller could read it,
+ * agree with it, and send anyway. Below it is arithmetic.
+ *
+ * Note the deliberate asymmetry with the rest of this file. The caller still
+ * does the judgement — it assigns every weight and every score, and nothing here
+ * second guesses either number. What it no longer does is decide whether its own
+ * numbers mean "sendable". That decision is mechanical, so it belongs on this
+ * side of the line, next to the F2 substantiation check.
+ */
+const GATE_WEIGHT_THRESHOLD = 8;
+const GATE_SCORE_FLOOR = 7;
+
+/**
+ * Verdict from the caller's Pass 2 scores plus the mechanical findings.
+ *
+ * A blocker severity finding blocks on its own, with or without scores. F2 in
+ * particular exists to stop a summary outrunning its evidence, so a highlight
+ * claiming a metric no body bullet supports is not sendable at any score: the
+ * document is making a claim it cannot back, and a 9.4 overall does not make
+ * that true.
+ */
+function evaluateGate(findings, scores) {
+  const suppliedScores = Array.isArray(scores);
+  // This endpoint is public and token authed, so treat every field as hostile:
+  // a malformed row is dropped, never thrown. Dropping one silently is safe in
+  // one direction only, and it is this one — a row that cannot be read cannot
+  // clear the gate, it just stops counting toward the average.
+  const rows = (suppliedScores ? scores : [])
+    .filter((s) => s && typeof s === "object")
+    .map((s) => ({
+      category: String(s.category || "(unnamed category)"),
+      weight: Number(s.weight),
+      score: Number(s.score),
+    }))
+    .filter((r) => isFinite(r.score));
+
+  // Weighted, never a plain mean. A 9 weight scoring 8 and a 1 weight scoring 2
+  // is a 7.4 document, not a 5.0 one, and averaging them flat would both
+  // understate it here and, in the mirror case, let a heavy category's failure
+  // hide behind light categories that scored well.
+  let totalWeight = 0;
+  let earned = 0;
+  for (const r of rows) {
+    if (!isFinite(r.weight) || r.weight <= 0) continue;
+    totalWeight += r.weight;
+    earned += r.weight * r.score;
+  }
+  const overall = totalWeight > 0 ? Number((earned / totalWeight).toFixed(1)) : null;
+
+  const blocking = rows
+    .filter((r) => isFinite(r.weight) && r.weight >= GATE_WEIGHT_THRESHOLD && r.score < GATE_SCORE_FLOOR)
+    .map((r) => ({ category: r.category, weight: r.weight, score: r.score }));
+
+  const blockingFindings = (Array.isArray(findings) ? findings : [])
+    .filter((f) => f && f.severity === "blocker");
+
+  return {
+    suppliedScores,
+    categoriesScored: rows.length,
+    overall,
+    gate: blocking.length || blockingFindings.length ? "BLOCKED" : "PASS",
+    blocking,
+    blockingFindings,
+  };
+}
+
+/**
+ * The opening statement, when blocked. It leads the payload because a verdict
+ * buried under four sections of rubric is the same as no verdict: by the time a
+ * caller reaches it, it has already read the rubric telling it to reason for
+ * itself.
+ */
+function renderGateBanner(g) {
+  if (g.gate !== "BLOCKED") return "";
+  const out = [
+    "!!! GATE: BLOCKED. THIS RESUME IS NOT SENDABLE. REGENERATE IT BEFORE SENDING. !!!",
+    "",
+    "This is an enforced verdict, not a suggestion and not a score to weigh against",
+    "anything else. Do not send, export, attach, or paste this document anywhere until",
+    "every item below is fixed and score_resume returns PASS.",
+    "",
+  ];
+  if (g.blocking.length) {
+    out.push(`BLOCKING CATEGORIES (weight >= ${GATE_WEIGHT_THRESHOLD} scoring below ${GATE_SCORE_FLOOR}):`);
+    for (const b of g.blocking) out.push(`  - ${b.category}: weight ${b.weight}, scored ${b.score}`);
+    out.push("");
+  }
+  if (g.blockingFindings.length) {
+    out.push("BLOCKING MECHANICAL FINDINGS (severity blocker):");
+    for (const f of g.blockingFindings) out.push(`  - ${f.rule}: ${f.detail}`);
+    out.push("");
+  }
+  if (g.overall !== null) out.push(`Weighted overall: ${g.overall.toFixed(1)}`, "");
+  out.push(
+    "Regenerate the resume so each item above is answered by the document, then call",
+    "score_resume again. The gap is in the resume, never in the evidence: fix it by",
+    "restoring the bullet that proves the claim, not by deleting the claim's metric.",
+  );
+  return out.join("\n") + "\n\n" + "=".repeat(78) + "\n\n";
+}
+
+/**
+ * The whole score_resume payload. It lives here rather than in the request
+ * handler so the gate can be exercised without standing up a Cloud Function,
+ * and so index.js keeps doing routing rather than analysis.
+ *
+ * BACKWARD COMPATIBILITY: with no "scores" and nothing blocking, this returns
+ * byte for byte what it returned before the gate existed. A PASS is only
+ * announced when scores were actually supplied, because "PASS" on a call that
+ * never sent the weighted half would read as sendable on evidence nobody
+ * checked.
+ */
+function buildScoreResumeReport(args, KB, rubric) {
+  const a = args || {};
+  const findings = auditResume(a.resume_text, KB);
+  const missingProtected = protectedBulletsMissing(a.resume_text, KB);
+  const cats = Array.isArray(a.categories) ? a.categories : [];
+  const unused = cats.map((c) => ({
+    category: c.category,
+    weight: c.weight,
+    missing_evidence: missingEvidence([c.category, c.jd_evidence || ""].join(" "), a.resume_text, KB, 4),
+  }));
+
+  const g = evaluateGate(findings, a.scores);
+  const gateSection = g.suppliedScores || g.gate === "BLOCKED"
+    ? "\n\n## PRE-SEND GATE (enforced, computed by the server)\n\n" + JSON.stringify({
+        gate: g.gate,
+        overall: g.overall,
+        blocking: g.blocking,
+        blocking_findings: g.blockingFindings,
+        categories_scored: g.categoriesScored,
+        rule: `A category with weight >= ${GATE_WEIGHT_THRESHOLD} scoring below ${GATE_SCORE_FLOOR} blocks. ` +
+          "Any blocker severity mechanical finding blocks on its own, scores or no scores. " +
+          "BLOCKED is a verdict on the document, not advice about it.",
+      }, null, 1)
+    : "";
+
+  return renderGateBanner(g) +
+    rubric +
+    gateSection +
+    "\n\n## MECHANICAL FINDINGS\n\n" + JSON.stringify(findings, null, 1) +
+    "\n\n## PROTECTED BULLETS NOT PRESENT (G2)\n\n" + JSON.stringify(missingProtected, null, 1) +
+    "\n\n## UNUSED KNOWLEDGE BASE MATERIAL BY CATEGORY\n\n" + JSON.stringify(unused, null, 1) +
+    (a.export_for_recruiter
+      ? "\n\n## EXPORT MODE\n\nOmit the gap list entirely. Present categories, weights, scores, rationale, and strengths as a requirement to evidence map. Do not brand it as an automated score."
+      : "\n\n## OUTPUT HANDLING\n\nInternal diagnostic. Do not write a shareable file and do not produce a candidate facing match report.");
+}
+
+/** G2: which protected bullets did not make it into the document. */
+function protectedBulletsMissing(resumeText, KB) {
+  const text = String(resumeText || "").toLowerCase();
+  const byPrefix = {};
+  for (const a of KB) byPrefix[a.id.slice(0, 7)] = a;
+  return PROTECTED.filter((p) => {
+    const a = byPrefix[p.id];
+    if (!a) return false;
+    const ms = [...metrics(a.summary)].map(metricKey);
+    const textKeys = new Set([...metrics(text)].map(metricKey));
+    return !ms.some((k) => textKeys.has(k));
+  }).map((p) => ({ accomplishmentId: p.id, label: p.label }));
+}
+
+/** K3: KB material that beat what was selected. The money field. */
+function missingEvidence(categoryText, resumeText, KB, limit) {
+  const inResume = new Set([...metrics(resumeText)].map(metricKey));
+  const rt = String(resumeText || "").toLowerCase();
+  return rankEvidence(categoryText, KB, 12).filter((r) => {
+    const a = KB.find((x) => x.id === r.accomplishmentId);
+    if (!a) return false;
+    if (rt.includes((a.title || "").toLowerCase().slice(0, 28))) return false;
+    const ms = [...metrics(a.summary)].map(metricKey);
+    return ms.length ? !ms.some((k) => inResume.has(k)) : true;
+  }).slice(0, limit || 4);
+}
+
+module.exports = {
+  scanJobDescription, rankEvidence, auditResume, protectedBulletsMissing,
+  missingEvidence, metrics, metricKey, PROTECTED, words, stem, lines,
+  evaluateGate, renderGateBanner, buildScoreResumeReport,
+  GATE_WEIGHT_THRESHOLD, GATE_SCORE_FLOOR,
+};