fix(ats): drive Maximum ATS Mode by EXTERNAL coverage (internal 96 vs Jobalytics 54)

Live bug: a PM/AI JD scored internal 96% but Jobalytics 54% (26/46). Root cause:
generate+repair optimised against our narrow internal taxonomy; the broad ~46-term
set external checkers extract (influence, backlog, business development, corporate
travel, expense management, payments, ...) was never extracted or placed, and
_build_skill_pool sorted non-taxonomy terms last and capped them at 44/50.

- external_ats.py (NEW): extract_external_keywords() broad Jobalytics-style
expected set + external_coverage() measured from the re-parsed export.
- resume_customizer._maximize_external_coverage() (NEW): in Max ATS, honesty-gate
each broad/pasted term via candidate_fit, then GUARANTEE includable ones into the
exported DOCX (Skills verbatim + woven bullets), re-render, re-measure; emits a
per-term debug report (keyword/found/section/why-missing).
- caps relaxed in Max ATS (_build_skill_pool 44/50 -> 200; stop dropping domain terms).
- status driven by external coverage: READY_MAX_ATS_95_PLUS / READY_90_PLUS_
EXTERNAL_ALIGNED / BELOW_TARGET_REPAIRABLE (never accept internal-high/external-low).
- config.MAXIMUM_ATS_SAFE_TERMS expanded with cross-functional PM craft terms.
- api_server: /api/generate returns external_coverage + coverage_report +
external_coverage_pct; both endpoints log maximum_ats_mode + status + coverage.
- extension v1.2.0: shows External ATS % + coverage count; failure panel states
"External ATS below target - internal score is not enough" + exact missing terms.

Tests: scripts/verify_max_ats_coverage.py (NEW) locks the failure -> exported DOCX
covers 25/26=96% of includable PM terms, CISSP/fake-seniority excluded, status
BELOW_TARGET_REPAIRABLE. verify_maximum_ats coverage 39% -> 89%. Anti-cheat,
feedback-repair, 90-pipeline, scoring-v2, API parity+health all still green.
Honesty intact: placement gated by candidate_fit; no fabricated creds/seniority.

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENT_CONTEXT.md

@@ -107,6 +107,17 @@ block or ask first. Flows via the job dict (`_maximum_ats_mode`,
 repair loop iterates while LOW/MEDIUM gaps remain. Confirmed terms persist to the
 vault (`confirm_expansion_terms`). The boundaries in §2 are NEVER relaxed by it.
 
+**⚠ The internal score is NOT a valid external signal.** Internal taxonomy
+coverage can be 96% while Jobalytics is 54% (it extracts a broader 40-46 term
+set). So Maximum ATS Mode is driven by EXTERNAL coverage: `src/external_ats.py`
+builds a broad Jobalytics-style expected set; `resume_customizer.
+_maximize_external_coverage()` honesty-gates each term then **physically
+guarantees** the includable ones into the exported DOCX (Skills verbatim + woven
+bullets) and measures coverage from the **re-parsed export**. Status becomes
+`READY_MAX_ATS_95_PLUS` / `READY_90_PLUS_EXTERNAL_ALIGNED` / `BELOW_TARGET_REPAIRABLE`.
+`_build_skill_pool` no longer caps off includable terms in max mode (cap → 200).
+Regression: `scripts/verify_max_ats_coverage.py` (the internal-96/external-54 bug).
+
 **Status system** (`src/fit_gate.py`): `READY_90_PLUS` /
 `READY_90_PLUS_REVIEW_RECOMMENDED` / `READY_95_EXTERNAL_ALIGNED` (feedback repair
 only: internal AND independent ≥ 90, pasted gaps mostly resolved, no review flags —
@@ -259,6 +270,7 @@ for resume header address/location ATS compliance.
 | `scripts/verify_anticheat.py` | **Anti-circular suite — keep green.** |
 | `scripts/verify_feedback_repair.py` | External feedback repair: parse + honest weave; CISSP blocked, SIEM unresolved-high. |
 | `scripts/verify_maximum_ats.py` | Maximum ATS Mode: PM/AI→user-confirmed; certs/seniority/eng still gated; coverage improves; 65%→repairable. |
+| `scripts/verify_max_ats_coverage.py` | Internal-96/external-54 regression: exported DOCX covers ≥90% includable PM terms; creds/seniority excluded; status by external coverage. |
 | `scripts/verify_90_pipeline.py` | Full fit→repair→status pipeline (stub floor). |
 | `scripts/verify_scoring_v2.py` | jd_analyzer + evidence + scoring + report + feedback loop. |
 | `scripts/evaluate_model_providers.py` | Run same jobs through each provider (Kimi/NVIDIA) — ready rate, avg independent, schema errors. **Needs real keys.** |

HISTORY.md

@@ -4,6 +4,57 @@ A running log of everything built, fixed, and changed. Most recent first.
 
 ---
 
+## 2026-06-20 (PM) — FIX: internal 96% but Jobalytics 54% (external-coverage bug)
+
+Live failure: a PM/AI JD generated in Maximum ATS Mode scored internal **96%** /
+independent 86% but **Jobalytics 54% (26/46, Hard Skills 24/43)**. Root cause:
+the entire generate + repair loop optimised against our **narrow internal
+taxonomy** (~25-30 terms → 96%), while Jobalytics extracts a **broad 46-term set**.
+Terms it wants that aren't in our taxonomy (`influence`, `backlog`, `business
+development`, `corporate travel`, `expense management`, `payments`, …) were never
+extracted, never placed — and `_build_skill_pool` even **sorted non-taxonomy terms
+last and capped them at 44/50**. So internal was blind to ~20 external terms.
+
+Fix — external coverage is now the success signal (internal score is NOT):
+- **`src/external_ats.py` (NEW)**: `extract_external_keywords()` (broad,
+  Jobalytics-style expected set: taxonomy floor ∪ safe-vocab-in-JD ∪ filtered
+  JD bi/tri-grams ∪ pasted terms) + `external_coverage()` (found/expected/pct/
+  missing, measured from the **re-parsed exported text**).
+- **`resume_customizer._maximize_external_coverage()` (NEW)**: in Maximum ATS
+  Mode, every includable broad/pasted term is honesty-gated through
+  `candidate_fit` (HIGH/BLOCKED excluded) then **physically guaranteed** into the
+  exported DOCX — Skills (verbatim) + woven into Experience bullets — then
+  re-rendered and re-measured. Produces a per-term debug report
+  (keyword / found_in_export / section / why-missing).
+- **Caps relaxed in Max ATS**: `_build_skill_pool` no longer caps off includable
+  terms (cap 44/50 → 200) and stops dropping non-taxonomy domain terms.
+- **Status driven by external coverage**: `READY_MAX_ATS_95_PLUS` (cov ≥ 95 +
+  gates), `READY_90_PLUS_EXTERNAL_ALIGNED` (cov ≥ 90), else
+  `BELOW_TARGET_REPAIRABLE` — never silently accept internal-high/external-low.
+- **`config.MAXIMUM_ATS_SAFE_TERMS`** expanded (influence, program/product
+  management, product marketing, business development, global teams, diverse
+  partners, data-driven decisions, etc.).
+- **`api_server.py`**: `/api/generate` returns `external_coverage` +
+  `coverage_report` + `external_coverage_pct`; both endpoints log
+  `maximum_ats_mode` + status + coverage (task: confirm the flag reaches backend).
+- **Extension v1.2.0**: shows External ATS % + estimated coverage count on
+  generate; failure panel now states "External ATS below target — internal score
+  is not enough" with the exact missing terms.
+
+### Verified (deterministic, no keys)
+- `scripts/verify_max_ats_coverage.py` (NEW, locks the live failure): on a 26/46
+  Amazon-PM-style case, the **exported DOCX covers 25/26 = 96%** of includable PM
+  terms; CISSP + fake "12+ years" stay out; status `BELOW_TARGET_REPAIRABLE` (not
+  stuck NEEDS_REPAIR); per-term section report present.
+- `scripts/verify_maximum_ats.py`: pasted-feedback coverage **17%→89%** (was 39%).
+- All prior suites green: anti-cheat, feedback-repair, 90-pipeline, scoring-v2,
+  API parity + health.
+
+> Honesty intact: placement is gated by `candidate_fit`; credentials, fake
+> seniority, employers, and specialized eng/security terms are never forced.
+
+---
+
 ## 2026-06-20 — Maximum ATS Mode (User-Confirmed Skill Expansion)
 
 Goal: for the candidate's target role family (Product / Product Manager / AI

README.md

@@ -324,9 +324,24 @@ confirmation"**, with a one-click **Confirm & regenerate**).
 `BELOW_TARGET_REPAIRABLE` (below target, remaining gaps LOW/MEDIUM → keep
 repairing) · `NEEDS_USER_CONFIRMATION` (only high-risk-but-supportable terms left).
 
-Verify: `PYTHONPATH=. python scripts/verify_maximum_ats.py` (deterministic;
-proves PM/AI terms become user-confirmed while certs/seniority/engineering stay
-gated, coverage improves, and a 65%-style case is repaired not accepted).
+**External-coverage is the success signal (not the internal score).** Our internal
+scorer uses a narrow taxonomy (→ 90%+ easily); external checkers extract a broad
+40-46 term set (→ can be ~54% on the same resume). So in Maximum ATS Mode the
+system builds a broad Jobalytics-style **expected** set (`src/external_ats.py`),
+**physically guarantees** every *includable* term into the exported DOCX (Skills
+verbatim + woven into Experience bullets; HIGH/BLOCKED stay gated), re-parses the
+file, and **measures coverage from the export**. Status is then `READY_MAX_ATS_95_PLUS`
+(≥95) / `READY_90_PLUS_EXTERNAL_ALIGNED` (≥90) / `BELOW_TARGET_REPAIRABLE` — an
+internal-96 / external-54 result is treated as a bug, never "done". Both endpoints
+return `external_coverage` + a per-term `coverage_report` (keyword / found in export
+/ section / why-missing) and log `maximum_ats_mode`.
+
+Verify (deterministic, no keys):
+- `PYTHONPATH=. python scripts/verify_maximum_ats.py` — PM/AI terms become
+  user-confirmed; certs/seniority/engineering stay gated; coverage improves.
+- `PYTHONPATH=. python scripts/verify_max_ats_coverage.py` — the 26/46 live-failure
+  regression: exported DOCX covers ≥90% of includable PM terms; credentials/fake
+  seniority excluded; status driven by external coverage.
 
 ---
 

api_server.py

@@ -240,12 +240,19 @@ async def generate(
             },
             "quality_flag": v2_report.get("quality_flag", ""),
             "review_terms": v2_report.get("review_terms", []),
-            "high_risk_terms": v2_report.get("high_risk_terms", []),
+            "high_risk_terms": v2_report.get("high_risk_terms",
+                                            v2_report.get("high_risk_terms_for_confirmation", [])),
             "maximum_ats_mode": max_ats,
+            "external_coverage": v2_report.get("external_coverage", {}),
+            "external_coverage_pct": v2_report.get("external_coverage_pct"),
+            "coverage_report": v2_report.get("coverage_report", {}),
             "keyword_coverage": v2_report.get("keyword_coverage", {}),
             "docx_b64": docx_b64,
             "pdf_b64": pdf_b64,
         }
+        print(f"[api/generate] maximum_ats_mode={max_ats} status={response_payload['status']} "
+              f"internal={response_payload['scores'].get('jd_match')} "
+              f"external_cov={response_payload.get('external_coverage_pct')}")
         return JSONResponse(response_payload)
 
     except HTTPException:
@@ -368,6 +375,9 @@ async def repair_with_feedback(
             None, repair_resume_for_api, pdf_bytes, jd_text, job_title, company,
             feedback, mk, ext, max_ats, conf_terms, tgt,
         )
+        print(f"[api/repair] maximum_ats_mode={max_ats} status={result.get('status')} "
+              f"after_cov={result.get('after_coverage', {}).get('pct')} "
+              f"added={len(result.get('added_terms', []))}")
         if result.get("error"):
             return JSONResponse(
                 {"error": result["error"], "detail": result.get("detail", "")},

config.py

@@ -63,6 +63,15 @@ MAXIMUM_ATS_SAFE_TERMS = {
     "startup environment", "startup", "customer value", "adoption",
     "retention", "growth", "engagement", "conversion", "monetization",
     "revenue", "customer success", "onboarding",
+    # Cross-functional PM responsibilities & leadership craft (interview-supportable)
+    "influence", "influencing", "program management", "product management",
+    "product marketing", "business development", "global teams",
+    "diverse partners", "customer results", "customer outcomes", "technology",
+    "data-driven decisions", "data driven decisions", "decision making",
+    "strategic planning", "execution", "delivery", "collaboration",
+    "communication", "leadership", "mentoring", "negotiation", "presentation",
+    "stakeholders", "roadmaps", "feature definition", "release management",
+    "product launch", "market research", "voice of customer",
 }
 
 # Primary key — GLM 5.1 (most reliable, used for resume parsing + customization)

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "ATS Resume Generator",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Tailors your resume to any job posting using the ATS pipeline.",
   "permissions": [
     "storage",

extension/popup/popup.js

@@ -298,10 +298,14 @@ function applyResult(result) {
     document.getElementById('score-ats').textContent = (result.scores.ats_readability ?? '—') + '%';
     document.getElementById('score-ind').textContent = (result.scores.independent_jd_match ?? '—') + '%';
     const extEl = document.getElementById('score-ext');
-    if (extEl) extEl.textContent = result.external_score != null ? result.external_score + '%' : '—';
+    const extPct = result.external_score != null ? result.external_score
+                 : (result.external_coverage_pct != null ? result.external_coverage_pct : null);
+    if (extEl) extEl.textContent = extPct != null ? extPct + '%' : '—';
     const covEl = document.getElementById('score-cov');
     const cov = result.coverage_report || {};
-    if (covEl) covEl.textContent = cov.coverage_count || '—';
+    const ec = result.external_coverage || {};
+    if (covEl) covEl.textContent = cov.coverage_count
+      || (ec.found != null ? `${ec.found}/${ec.expected}` : '—');
     scoresEl.style.display = 'block';
   }
 
@@ -334,11 +338,14 @@ function renderCoverage(result) {
   const panel = document.getElementById('coverage-panel');
   if (!panel) return;
   const cov = result.coverage_report;
+  const ec  = result.external_coverage || {};
   const added   = result.added_terms || [];
-  const missing = result.still_missing_repairable || [];
+  // generate-path missing comes from external_coverage.missing
+  const missing = (result.still_missing_repairable && result.still_missing_repairable.length)
+    ? result.still_missing_repairable : (ec.missing || []);
   const confirm = result.unresolved_high_risk_terms || [];
   const blocked = result.blocked_terms || [];
-  if (!cov && !added.length && !confirm.length && !blocked.length) {
+  if (!cov && !ec.found && !added.length && !confirm.length && !blocked.length) {
     panel.innerHTML = '';
     return;
   }
@@ -347,6 +354,10 @@ function renderCoverage(result) {
     const pct = cov.after.pct ?? 0;
     parts.push(`<div class="cov-line"><b>Keyword coverage:</b> ${cov.coverage_count} (${pct}%)</div>`);
     parts.push(`<div class="cov-bar"><div style="width:${Math.min(100, pct)}%"></div></div>`);
+  } else if (ec.found != null) {
+    const pct = ec.pct ?? 0;
+    parts.push(`<div class="cov-line"><b>External coverage (estimated):</b> ${ec.found}/${ec.expected} (${pct}%)</div>`);
+    parts.push(`<div class="cov-bar"><div style="width:${Math.min(100, pct)}%"></div></div>`);
   }
   if (added.length)
     parts.push(`<div class="cov-line tag-added">✓ Added (${added.length}): ${added.slice(0,12).join(', ')}</div>`);
@@ -366,13 +377,21 @@ function renderExplanation(result) {
   const readyStatuses = ['READY_90_PLUS', 'READY_95_EXTERNAL_ALIGNED',
     'READY_MAX_ATS_95_PLUS', 'READY_90_PLUS_EXTERNAL_ALIGNED'];
   const isReady = readyStatuses.includes(result.status);
+  const ec = result.external_coverage || {};
+  const extPct = result.external_score != null ? result.external_score
+               : (result.external_coverage_pct != null ? result.external_coverage_pct : ec.pct);
   if (isReady) {
     panel.innerHTML = '';
   } else {
     const why = result.below_target_explanation
-      || `Below target (${result.status}). Improve with pasted ATS feedback to close the gap.`;
+      || `Below target (${result.status}). Paste your Jobalytics output below and Improve to close the gap.`;
     const cls = result.status === 'BELOW_TARGET_REPAIRABLE' ? 'explain-yellow' : 'explain-red';
-    panel.innerHTML = `<div class="explain-panel ${cls}"><b>Why below 90:</b> ${why}</div>`;
+    const head = (extPct != null && extPct < 90)
+      ? `External ATS below target (${extPct}%). Internal score is not enough.`
+      : 'External ATS below target. Internal score is not enough.';
+    panel.innerHTML =
+      `<div class="explain-panel ${cls}"><b>${head}</b><br>` +
+      `Paste Jobalytics feedback and Improve.<br><span style="opacity:.85">${why}</span></div>`;
   }
   // Show "confirm these terms" only when high-risk-but-supportable terms remain.
   const confirmTerms = result.unresolved_high_risk_terms || [];

scripts/verify_max_ats_coverage.py

@@ -0,0 +1,109 @@
+"""
+Hard regression for the LIVE FAILURE: internal 96% but Jobalytics 54% (26/46,
+Hard Skills 24/43) on an Amazon/Product-Manager-type JD.
+
+This locks in the fix: in Maximum ATS Mode the EXPORTED DOCX must physically
+contain 90%+ of the INCLUDABLE external keywords (Skills + Experience), driven by
+external coverage — NOT by the internal score — while credentials / fake
+seniority stay blocked. Deterministic (StubProvider, no API keys).
+"""
+import os, sys, io, shutil
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
+sys.path.insert(0, os.path.abspath("."))
+
+import src.candidate_vault as _cv
+_cv._VAULT_PATH = "data/_test_vault_maxcov.json"
+if os.path.exists(_cv._VAULT_PATH):
+    os.remove(_cv._VAULT_PATH)
+
+import shutil as _sh
+src_pdf = r"C:\Users\Nxtwave\Desktop\resume\Saiteja_Tirunagari_Resume A 26 - Copy.pdf"
+dst = "data/resume/resume.pdf"
+os.makedirs("data/resume", exist_ok=True)
+if not os.path.exists(dst) and os.path.exists(src_pdf):
+    _sh.copyfile(src_pdf, dst)
+
+from src.resume_parser_v2 import parse_resume_pdf
+from src.providers import StubProvider
+from src.jobalytics_repair import repair_with_external_feedback
+from src.resume_customizer import _read_docx_text
+from src.ats_scorer import _kw_in_text
+from src.fit_gate import (READY, READY_REVIEW, READY_MAX_ATS_95_PLUS,
+                          READY_90_PLUS_EXTERNAL_ALIGNED, BELOW_TARGET_REPAIRABLE,
+                          NEEDS_USER_CONFIRMATION)
+
+ok = True
+def check(name, cond, detail=""):
+    global ok; ok = ok and cond
+    print(f"  [{'PASS' if cond else 'FAIL'}] {name}  {detail}")
+
+# Normal PM/Product terms a real AI/PM JD wants (from the live screenshot) — all
+# interview-supportable, none are credentials.
+INCLUDABLE = [
+    "product strategy", "ai", "influence", "acceptance criteria", "backlog",
+    "program management", "product management", "product marketing",
+    "business development", "global teams", "diverse partners",
+    "corporate travel", "expense management", "payments", "roadmap",
+    "stakeholder management", "requirements", "user stories", "prioritization",
+    "data-driven decisions", "metrics", "experimentation", "product discovery",
+    "go-to-market", "saas", "b2b",
+]
+# Must NEVER be fabricated.
+BLOCKED = ["CISSP", "12+ years"]
+
+jd = open("tests/fixtures/jds/generic_pm_3_7yrs.txt", encoding="utf-8").read()
+jd += ("\n\nResponsibilities: product strategy, roadmap, backlog, user stories, "
+       "acceptance criteria, prioritization, stakeholder management, requirements, "
+       "program management, product marketing, business development, global teams, "
+       "diverse partners, corporate travel, expense management, payments, metrics, "
+       "experimentation, data-driven decisions, go-to-market, product discovery. "
+       "Hard skills: AI, SaaS, B2B, influence. 12+ years required. CISSP preferred.")
+
+base = parse_resume_pdf(dst)
+job = {"title": "Product Manager", "company": "Amazon", "description": jd, "_raw_assessment": {}}
+
+fb = ("Match score 54%. Resume has 26 out of 46 keywords. Hard Skills 24 of 43. "
+      "Missing keywords: " + ", ".join(INCLUDABLE + BLOCKED) + ".")
+
+res = repair_with_external_feedback(job, feedback_text=fb, provider=StubProvider(),
+                                    base_resume=base, maximum_ats_mode=True,
+                                    output_dir="data/output/resumes/_maxcov_test")
+print("repair status:", res.get("status"), "scores:", res.get("scores"),
+      "after_cov:", res.get("after_coverage", {}).get("pct"))
+check("no error", "error" not in res, res.get("error", ""))
+
+# THE core assertion: the EXPORTED DOCX physically contains 90%+ of includable terms.
+txt = _read_docx_text(res["resume_path"]).lower()
+found = [t for t in INCLUDABLE if _kw_in_text(t, txt)]
+missing = [t for t in INCLUDABLE if t not in found]
+pct = int(round(100 * len(found) / len(INCLUDABLE)))
+check("exported DOCX covers >=90% of includable PM terms", pct >= 90,
+      f"{len(found)}/{len(INCLUDABLE)} = {pct}%  missing={missing}")
+
+# Honesty: credentials / fake seniority never fabricated.
+check("CISSP NOT in exported DOCX", "cissp" not in txt)
+check("no fabricated '12+ years'", "12+ years" not in txt and "12 years" not in txt)
+check("CISSP surfaced as blocked", "CISSP" in res.get("blocked_terms", []))
+
+# Status must NOT be a stuck NEEDS_REPAIR — external coverage drives it.
+good_status = {READY, READY_REVIEW, READY_MAX_ATS_95_PLUS,
+               READY_90_PLUS_EXTERNAL_ALIGNED, BELOW_TARGET_REPAIRABLE,
+               NEEDS_USER_CONFIRMATION}
+check("status driven by external coverage (not stuck NEEDS_REPAIR)",
+      res.get("status") in good_status, res.get("status"))
+
+# Coverage report shows where each term landed.
+cov = res.get("coverage_report", {})
+kw = cov.get("keywords", [])
+check("coverage_report lists per-term sections", bool(kw),
+      f"{len(kw)} terms reported")
+secs = {k.get("section") for k in kw if k.get("placed_in_resume") or k.get("found_in_export")}
+check("terms placed in Skills AND Experience (multi-section)",
+      ("Skills" in secs and any("Experience" in s for s in secs)) or len(secs) >= 2,
+      f"sections={secs}")
+
+print("\n" + ("\u2713 LIVE-FAILURE REGRESSION PASSES" if ok else "\u2717 SOME FAILED"))
+shutil.rmtree("data/output/resumes/_maxcov_test", ignore_errors=True)
+if os.path.exists(_cv._VAULT_PATH):
+    os.remove(_cv._VAULT_PATH)
+sys.exit(0 if ok else 1)

src/external_ats.py

@@ -0,0 +1,163 @@
+"""
+External-ATS coverage simulator (Jobalytics/Simplify-style breadth).
+
+WHY THIS EXISTS
+───────────────
+Our internal scorer extracts keywords from a NARROW PM taxonomy and scores the
+resume against that same narrow set → it easily reports 90%+. External checkers
+(Jobalytics/Simplify) extract a MUCH broader set (40-46 terms incl. domain words,
+JD-specific responsibilities, soft skills) → the same resume scores ~54%. The
+internal number is therefore NOT a valid success signal for the external goal.
+
+This module computes a broad, Jobalytics-style EXPECTED keyword set from the JD,
+and measures coverage against the *re-parsed exported resume text* (the only
+truth). Used to (a) decide what to physically place in Maximum ATS Mode and
+(b) gate/report readiness on real external-style coverage, not internal score.
+
+It is intentionally broader than `extract_jd_keywords` (which stays skills-only
+to keep the honest default pipeline clean). The broad set is only used in
+Maximum ATS Mode / external-feedback repair, where the user has explicitly opted
+into aggressive coverage.
+"""
+from __future__ import annotations
+
+import re
+from typing import Dict, List
+
+from .ats_scorer import _kw_in_text, extract_jd_keywords
+
+# Words that are never standalone keywords (checkers penalise/ignore them).
+_STOP = {
+    "the", "and", "for", "with", "you", "your", "our", "are", "will", "have",
+    "has", "had", "this", "that", "these", "those", "from", "into", "out", "off",
+    "who", "what", "when", "where", "why", "how", "all", "any", "can", "may",
+    "should", "would", "could", "must", "able", "etc", "per", "via", "not",
+    "but", "they", "them", "their", "his", "her", "its", "she", "him", "was",
+    "were", "been", "being", "more", "most", "such", "than", "then", "also",
+    "about", "across", "within", "while", "each", "other", "some", "many",
+    "well", "very", "much", "like", "just", "only", "even", "both", "over",
+    "under", "between", "during", "including", "include", "includes",
+    "looking", "join", "join us", "work", "working", "team", "teams", "role",
+    "job", "company", "candidate", "candidates", "ideal", "great", "good",
+    "strong", "years", "year", "experience", "experiences", "plus", "preferred",
+    "required", "requirement", "responsibilities", "qualifications", "skills",
+    "ability", "knowledge", "understanding", "familiarity", "proficiency",
+    "we", "us", "is", "in", "on", "of", "to", "at", "as", "an", "or", "be",
+    "it", "by", "a", "i",
+}
+# Vague filler — never a keyword (mirrors jd_analyzer._BUZZWORDS intent).
+_FILLER = {
+    "innovation", "innovative", "solution", "solutions", "tools", "tool",
+    "ownership", "synergy", "dynamic", "passionate", "motivated", "self-starter",
+    "results-driven", "detail-oriented", "team player", "track record",
+    "expertise", "best practices", "thought leadership", "fast-paced",
+    "cutting-edge", "world-class", "robust", "seamless", "holistic", "leverage",
+    "excellence", "proven", "successful", "goals", "productivity", "reinvent",
+    "reinvention", "mission", "vision", "culture", "value", "values", "impact",
+    "environment", "opportunity", "opportunities", "responsibility",
+}
+
+
+def _clean(term: str) -> str:
+    return re.sub(r"[^\w\s/+.\-]", "", term or "").strip().lower()
+
+
+def _is_term_like(t: str) -> bool:
+    """A token/phrase that reads like a real skill/responsibility/domain term."""
+    t = t.strip()
+    if not t or t in _STOP or t in _FILLER:
+        return False
+    words = t.split()
+    if len(words) > 4:
+        return False
+    if len(t) < 3:
+        return False
+    if t.isdigit():
+        return False
+    # All words must be non-stop and not lemmatizer artifacts.
+    for w in words:
+        if w in _STOP:
+            return False
+    if len(t) >= 5 and t.endswith(("at", "iz", "ic")) and len(words) == 1:
+        return False  # "integrat", "automat", "operat"
+    return True
+
+
+def extract_external_keywords(jd_text: str, extra: List[str] = None) -> List[str]:
+    """Broad, Jobalytics-style expected keyword set for a JD.
+
+    Union of: the reliable taxonomy floor (`extract_jd_keywords`), curated
+    Maximum-ATS safe terms present in the JD, and term-like 1-3 word phrases
+    pulled from the JD body (filtered against stopwords/filler). De-duplicated,
+    lowercase. `extra` (e.g. pasted external missing/matched terms) is unioned in.
+    """
+    jd_text = jd_text or ""
+    jd_low = jd_text.lower()
+    out: List[str] = []
+    seen = set()
+
+    def _add(term: str):
+        t = _clean(term)
+        if t and t not in seen and _is_term_like(t):
+            seen.add(t)
+            out.append(t)
+
+    # 1. Reliable taxonomy floor.
+    for k in extract_jd_keywords(jd_text):
+        _add(k)
+
+    # 2. Curated safe vocabulary that actually appears in this JD.
+    try:
+        from config import MAXIMUM_ATS_SAFE_TERMS as _SAFE
+    except Exception:
+        _SAFE = set()
+    for t in _SAFE:
+        if t in jd_low:
+            _add(t)
+
+    # 3. Term-like phrases from the JD body. Pull capitalised/section phrases and
+    #    notable bigrams/trigrams. Conservative: only multiword phrases whose
+    #    words are all alphabetic and non-stop, plus known-good single nouns.
+    #    (Single-noun garbage is filtered by _is_term_like + the dedup below.)
+    # Bi/tri-grams of alphabetic words.
+    words = re.findall(r"[a-zA-Z][a-zA-Z\-/+.]{1,}", jd_low)
+    for n in (3, 2):
+        for i in range(len(words) - n + 1):
+            gram = " ".join(words[i:i + n])
+            if all(w not in _STOP and w not in _FILLER for w in words[i:i + n]):
+                # Only keep grams that recur or look like a skill phrase.
+                if jd_low.count(gram) >= 1 and len(gram) <= 34:
+                    # Skip grams that are mostly filler-ish single words joined.
+                    _add(gram)
+
+    # 4. Pasted external terms (ground truth from a checker).
+    for t in (extra or []):
+        _add(t)
+
+    return out
+
+
+def external_coverage(expected: List[str], exported_text: str) -> Dict:
+    """Measure coverage of `expected` terms against the exported resume text.
+
+    Returns {expected, found, pct, present, missing}. Matching uses the same
+    word-boundary/phrase logic as scoring (`_kw_in_text`).
+    """
+    text = (exported_text or "").lower()
+    exp = []
+    seen = set()
+    for t in expected:
+        tl = _clean(t)
+        if tl and tl not in seen:
+            seen.add(tl)
+            exp.append(tl)
+    present = [t for t in exp if _kw_in_text(t, text)]
+    missing = [t for t in exp if t not in present]
+    total = len(exp)
+    return {
+        "expected": total,
+        "found": len(present),
+        "pct": int(round(100 * len(present) / max(1, total))),
+        "present": present,
+        "missing": missing,
+    }

src/resume_customizer.py

@@ -948,6 +948,103 @@ class ResumeCustomizer:
         pBdr.append(bottom)
         pPr.append(pBdr)
 
+    def _maximize_external_coverage(self, resume, filepath: str, jd_text: str,
+                                    base_text: str, include_pool=None,
+                                    excluded_kw=None, pasted_terms=None,
+                                    confirmed_terms=None) -> dict:
+        """Maximum ATS Mode: GUARANTEE includable external-style keywords appear
+        in the exported DOCX, then re-render.
+
+        The internal score is not a valid external signal, so we drive placement
+        off a broad Jobalytics-style EXPECTED set (+ any pasted external terms).
+        Every term is honesty-gated through `candidate_fit` (max mode): only
+        action=="include" terms are placed; HIGH/BLOCKED (certs, seniority,
+        employers, engineering, specialized) are NEVER forced. Includable terms
+        are placed in Skills (reliable verbatim vehicle) AND woven into bullets
+        for evidence. Returns the expected set + a per-term debug report.
+        """
+        from .external_ats import extract_external_keywords, external_coverage
+        from .candidate_fit import classify_fit
+        from .jd_analyzer import Requirement, _categorize
+        from .resume_renderer import render_resume_docx
+        from .ats_scorer import _kw_in_text
+
+        include_pool = include_pool or []
+        excluded_kw = {e.lower() for e in (excluded_kw or set())}
+        pasted_terms = pasted_terms or []
+        confirmed = {t.lower().strip() for t in (confirmed_terms or [])}
+        jd_low = jd_text.lower()
+
+        # Broad expected set = Jobalytics-style extraction ∪ our LOW/MEDIUM JD
+        # terms ∪ pasted external terms (ground truth from a checker).
+        expected = extract_external_keywords(
+            jd_text, extra=list(include_pool) + list(pasted_terms))
+        expected = list(dict.fromkeys([e.lower() for e in expected]))
+
+        cur_text = _read_docx_text(filepath).lower()
+        missing = [t for t in expected if not _kw_in_text(t, cur_text)]
+
+        # Honesty gate every missing term (max mode). Only include the safe ones.
+        includable, gated = [], {}
+        for t in missing:
+            if t in excluded_kw:
+                gated[t] = "high-risk/blocked (gated by fit classifier)"
+                continue
+            if t in self._BUZZWORDS or t in self._KEYWORD_BLOCKLIST:
+                gated[t] = "buzzword/blocklisted (checkers penalise)"
+                continue
+            r = Requirement(term=t, category=_categorize(t))
+            v = classify_fit(r, base_text, maximum_ats_mode=True, confirmed=confirmed)
+            if v.action == "include":
+                includable.append(t)
+            else:
+                gated[t] = f"{v.action}: {v.reason}"
+
+        # Place: weave the JD-relevant ones into bullets (evidence) + GUARANTEE
+        # all includable terms in Skills (verbatim → external checkers count them).
+        weave = [t for t in includable if t in jd_low][:28]
+        if weave:
+            try:
+                self._weave_keywords_into_bullets(resume, weave, jd_text)
+            except Exception:
+                pass
+        cur_skills = {s.lower() for s in resume.skills}
+        add_skills = [t for t in includable if t.lower() not in cur_skills]
+        resume.skills = self._dedup_keywords_by_lemma(list(resume.skills) + add_skills)
+
+        render_resume_docx(resume, filepath)
+
+        # Measure from the re-parsed export (the only truth) + per-term report.
+        final_text = _read_docx_text(filepath)
+        cov = external_coverage(expected, final_text)
+        present_set = {p.lower() for p in cov["present"]}
+        exp_low = "\n".join(b for r in resume.roles for b in r.bullets).lower()
+        skills_low = " ".join(resume.skills).lower()
+        keywords = []
+        for t in expected:
+            found = t in present_set
+            if found:
+                if _kw_in_text(t, exp_low):
+                    section = "Experience bullets"
+                elif _kw_in_text(t, skills_low):
+                    section = "Skills"
+                else:
+                    section = "Summary/other"
+            else:
+                section = "(not placed)"
+            keywords.append({
+                "keyword": t,
+                "found_in_export": found,
+                "section": section,
+                "reason": "" if found else gated.get(t, "could not place cleanly"),
+            })
+        cov["expected_terms"] = expected
+        cov["includable"] = includable
+        cov["gated"] = gated
+        cov["keywords"] = keywords
+        cov["coverage_count"] = f"{cov['found']}/{cov['expected']}"
+        return cov
+
     def _weave_keywords_into_bullets(self, resume, missing_keywords: list,
                                        jd_text: str) -> None:
         """
@@ -1491,7 +1588,12 @@ class ResumeCustomizer:
                             and sl not in [x.lower() for x in include_pool]):
                         include_pool.append(sl)
 
-            def _build_skill_pool(terms, cap=44):
+            def _build_skill_pool(terms, cap=None):
+                # Maximum ATS Mode: do NOT cap off includable JD/external terms —
+                # external checkers count every term, and dropping domain terms
+                # (sorted last) is exactly what caused internal-high/external-low.
+                if cap is None:
+                    cap = 200 if _max_ats else 44
                 pool = []
                 for k in terms:
                     kl = k.lower()
@@ -1596,7 +1698,8 @@ class ResumeCustomizer:
                     except Exception:
                         pass
                 tailored.skills = _build_skill_pool(
-                    list(tailored.skills) + add, cap=50)
+                    list(tailored.skills) + add,
+                    cap=(200 if locals().get("_max_ats") else 50))
                 parsed, report, valid, missing_parts, val = _render_score()
             else:
                 # Loop exhausted. Re-check the FINAL render (the last repair may
@@ -1629,6 +1732,39 @@ class ResumeCustomizer:
             except Exception:
                 pass
 
+        # ── Maximum ATS Mode: guarantee external-style keyword coverage ──────
+        # The internal score is NOT a valid external signal (internal 96 vs
+        # Jobalytics 54). Force every INCLUDABLE broad/pasted term physically
+        # into the exported DOCX, re-render, and measure coverage from the
+        # re-parsed file. HIGH/BLOCKED stay gated (no fabrication).
+        ext_cov = None
+        if job.get("_maximum_ats_mode") and report:
+            try:
+                ext_cov = self._maximize_external_coverage(
+                    tailored, filepath, jd_text,
+                    locals().get("base_text", base_resume.to_flat_text()),
+                    include_pool=locals().get("include_pool", []),
+                    excluded_kw=locals().get("_excluded_kw", set()),
+                    pasted_terms=job.get("_jobalytics_keywords") or [],
+                    confirmed_terms=job.get("_confirmed_terms") or [],
+                )
+                # Re-score the re-rendered file so the report reflects the export.
+                parsed, report2, valid, missing_parts, val = _render_score()
+                # Preserve fields the status block expects, then merge.
+                for k, v in report2.items():
+                    report[k] = v
+                report["external_coverage"] = ext_cov
+                report["coverage_report"] = {
+                    "external_keywords_total": ext_cov.get("expected"),
+                    "coverage_count": ext_cov.get("coverage_count"),
+                    "found": ext_cov.get("found"),
+                    "missing": ext_cov.get("missing", [])[:40],
+                    "keywords": ext_cov.get("keywords", []),
+                    "gated": ext_cov.get("gated", {}),
+                }
+            except Exception as _me:
+                print(f"[max-ats] {_me}")
+
         # Postcondition + attach the v2 report/status to the job (for UI/Sheets)
         try:
             self._assert_no_dump_footer(filepath)
@@ -1704,10 +1840,41 @@ class ResumeCustomizer:
             # (not auto-claimed). Always surfaced for transparency.
             report.setdefault("high_risk_terms_for_confirmation",
                               locals().get("high_pool", []))
+            # ── Maximum ATS Mode: status is driven by EXTERNAL coverage, not the
+            # internal score. Don't accept internal-96/external-low as done.
+            if job.get("_maximum_ats_mode") and ext_cov is not None:
+                from .fit_gate import (READY_MAX_ATS_95_PLUS,
+                                       READY_90_PLUS_EXTERNAL_ALIGNED,
+                                       BELOW_TARGET_REPAIRABLE)
+                try:
+                    from config import MAXIMUM_ATS as _MAXCFG
+                    _tgt = _MAXCFG.get("target_external_score", 95)
+                    _min = _MAXCFG.get("min_external_score", 90)
+                except Exception:
+                    _tgt, _min = 95, 90
+                ext_pct = ext_cov.get("pct", 0)
+                gates_ok = (internal_jm >= 90 and independent_jm >= 90
+                            and report.get("estimated_scores", {}).get("ats_readability", 0) >= 90)
+                if ext_pct >= _tgt and gates_ok:
+                    status = READY_MAX_ATS_95_PLUS
+                elif ext_pct >= _min:
+                    status = READY_90_PLUS_EXTERNAL_ALIGNED
+                elif status not in (READY, READY_REVIEW):
+                    # Below external target but resume is downloadable for review
+                    # and the loop should keep going on the remaining LOW/MEDIUM
+                    # gaps — never silently accept a low external score.
+                    if ext_cov.get("includable") or ext_cov.get("missing"):
+                        status = BELOW_TARGET_REPAIRABLE
+                report["status"] = status
+                report["external_coverage_pct"] = ext_pct
+                # Always offer the download in max mode (review), per spec.
+                report["download_allowed"] = download_allowed or status in (
+                    READY_MAX_ATS_95_PLUS, READY_90_PLUS_EXTERNAL_ALIGNED)
+
             job["_v2_report"] = report
             job["_v2_status"] = status
             job["quality_flag"] = quality
-            job["download_allowed"] = download_allowed
+            job["download_allowed"] = report.get("download_allowed", download_allowed)
             job["independent_jd_match"] = independent_jm
 
         try:
@@ -2224,3 +2391,4 @@ class ResumeCustomizer:
 
         doc.save(filepath)
         return filepath
+