feat(09-03): structured keyword placement for hardcoded resume [R22]

place_keywords_structured() distributes keywords in the exact owner order:
summary 15-20 -> BYJU PSM 25-30 -> BYJU PS 25-30 -> ML Edutech 8-12 ->
Skills Other 15-20 -> projects 8-10 each (FDP..NIAT) -> NxtWave 15-20 ->
Skills Other overflow. Anchors on the literal \resumeItemListEnd within the
correct section. Append-only (tagged \resumeItem + fenced summary + Other row),
idempotent (extended _remove_injected_block). inject_keywords routes hardcoded
resume here; generic LaTeX keeps the original distribution.

tests/test_structured_placement.py: 9/9 pass (counts, anchor, append-only,
idempotency, dedupe).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.planning/phases/09-hardcoded-resume-keyword-placement/09-03-SUMMARY.md

@@ -0,0 +1,36 @@
+# 09-03 SUMMARY — Structured keyword placement [R22]
+
+Status: COMPLETE
+
+## What was built (src/latex_resume.py)
+- `_is_hardcoded_resume(src)` — detects the owner's bundled resume.
+- `place_keywords_structured(latex_src, terms)` — waterfall allocation in the
+  exact R22 order with per-slot max bounds:
+  1 Summary 20 → 2 BYJU'S PSM 30 → 3 BYJU'S PS 30 → 4 ML Edutech 12 →
+  5 Skills Other 20 → 6 Projects 10 each (FDP, Launchpad, OCR--OMR, Offline NAT,
+  AI Chatbot, NIAT Application Portal) → 7 NxtWave 20 → 8 Skills Other overflow
+  (merged into the single Other row). Never holds keywords back.
+- Anchoring uses literal `\resumeItemListEnd` (NOT `\end{itemize}` — the resume
+  has no bare itemize end). Experience/project anchors are searched within their
+  own section so duplicates (e.g. "NIAT Application Portal" appears in both an
+  experience bullet and a project) resolve correctly.
+- Append-only: inserts a tagged `\resumeItem{...} % ats-item` on the line before
+  each block's `\resumeItemListEnd`; a fenced summary block; one Skills `Other:`
+  row tagged `% ats-skills-other`. Original bullets/roles/dates untouched.
+- `inject_keywords` routes to this for the hardcoded resume; generic LaTeX keeps
+  the original recruiter-style distribution.
+- `_remove_injected_block` extended to strip the new `\resumeItem … % ats-item`
+  lines and the Skills `Other:` row (with its leading `\\` separator) → idempotent.
+
+## Verification (all passed)
+- `tests/test_structured_placement.py` — 9/9 pass: summary 15–20, PSM 25–30,
+  PS 25–30, ML 8–12, Skills Other ≥15, anchor-before-list-end, append-only
+  (4 original bullets intact), idempotent (o1==o2), dedupe skips present terms.
+- Generic non-hardcoded LaTeX still uses the original distribution (regression OK).
+- Routing: `_is_hardcoded_resume(DEFAULT_RESUME_LATEX) == True`.
+
+## Notes / deviations
+- Tectonic compile of the placed resume is verified on HF (engine not installed
+  locally); local checks cover structure + idempotency.
+- Skills-Other strip regex tolerates the leading `\\` separator + whitespace so
+  re-runs reproduce byte-identically (idempotency test proves it).

src/latex_resume.py

@@ -278,6 +278,136 @@ _EXPERIENCE_RE = (
 )
 
 
+# ── Structured placement for the HARDCODED resume (R22) ──────────────────────
+_INJECT_SKILLS_OTHER = "% ats-skills-other"
+
+
+def _is_hardcoded_resume(src: str) -> bool:
+    """True when `src` is the owner's bundled resume (known structure → we can
+    place keywords in the exact owner-specified order/locations)."""
+    s = src or ""
+    return ("Saiteja Tirunagari" in s and "\\resumeSubheading" in s
+            and "Asst. Product Success Manager" in s)
+
+
+def place_keywords_structured(latex_src: str,
+                              terms: List[str]) -> Tuple[str, List[str]]:
+    """Place keywords into the hardcoded resume in the exact R22 waterfall:
+      1 Summary 15-20 -> 2 BYJU'S PSM 25-30 -> 3 BYJU'S PS 25-30 -> 4 ML Edutech
+      8-12 -> 5 Skills Other 15-20 -> 6 Projects 8-10 each (FDP, Launchpad,
+      OCR--OMR, Offline NAT, AI Chatbot, NIAT Application Portal) -> 7 NxtWave
+      15-20 -> 8 Skills Other overflow.
+    Append-only (never edits original bullets) and idempotent (strips prior
+    injected fragments first). Returns (new_source, placed_terms).
+    """
+    src = _remove_injected_block(latex_src or "")
+    src_low = src.lower()
+
+    # De-dupe + skip terms already present in the candidate's resume.
+    seen: set = set()
+    pool: List[str] = []
+    for t in terms or []:
+        tl = (t or "").strip().lower()
+        if not tl or tl in seen:
+            continue
+        seen.add(tl)
+        if tl in src_low:
+            continue
+        pool.append(t.strip())
+    if not pool:
+        return src, []
+
+    placed = list(pool)
+
+    def take(n: int) -> List[str]:
+        nonlocal pool
+        g = pool[:n]
+        pool = pool[n:]
+        return g
+
+    # Section bounds (so anchors resolve in the right section — e.g. "NIAT
+    # Application Portal" appears in BOTH an experience bullet and a project).
+    exp_start = src.find("\\section{EXPERIENCE}")
+    proj_start = src.find("\\section{SELECTED")
+    if proj_start == -1:
+        proj_start = src.find("SELECTED 0")
+    skills_start = src.find("\\section{SKILLS}")
+
+    # Waterfall allocation (max bounds; never hold keywords back).
+    summary_terms = take(20)
+    psm_terms = take(30)
+    ps_terms = take(30)
+    ml_terms = take(12)
+    skills_terms = take(20)
+    proj_order = ["FDP", "Launchpad", "OCR--OMR", "Offline NAT",
+                  "AI Chatbot", "NIAT Application Portal"]
+    proj_terms = {k: take(10) for k in proj_order}
+    nxtwave_terms = take(20)
+    skills_terms = skills_terms + pool   # slot 8 overflow merged into one row
+    pool = []
+
+    def esc_join(ts: List[str]) -> str:
+        return ", ".join(latex_escape(t) for t in ts)
+
+    insertions: List[Tuple[int, str]] = []   # (position, text) on ORIGINAL src
+
+    def add_item(anchor: str, ts: List[str], search_start: int) -> None:
+        """Queue a tagged \\resumeItem appended as the last item of the block that
+        `anchor` belongs to (inserted on the line before its \\resumeItemListEnd)."""
+        if not ts or search_start < 0:
+            return
+        a = src.find(anchor, search_start)
+        if a == -1:
+            return
+        e = src.find("\\resumeItemListEnd", a)
+        if e == -1:
+            return
+        p = src.rfind("\n", 0, e)   # newline before the (indented) list-end
+        if p == -1:
+            return
+        block = "\n      \\resumeItem{" + esc_join(ts) + "} " + _INJECT_ITEM
+        insertions.append((p, block))
+
+    # Experience slots (search within EXPERIENCE section).
+    add_item("Asst. Product Success Manager", psm_terms, exp_start)
+    add_item("Product Specialist", ps_terms, exp_start)
+    add_item("ML Edutech", ml_terms, exp_start)
+    add_item("Internal Product Manager", nxtwave_terms, exp_start)
+
+    # Project slots (search within PROJECTS section, in the owner's order).
+    for k in proj_order:
+        add_item(k, proj_terms[k], proj_start)
+
+    # Summary slot: fenced block at the END of the summary (before next \section).
+    if summary_terms:
+        sm = re.search(_SUMMARY_RE, src, re.I)
+        if sm:
+            nxt = src.find("\\section", sm.end())
+            pos = nxt if nxt != -1 else sm.end()
+            block = (
+                "\n" + _INJECT_MARKER + "\n"
+                "\\par\\noindent Additional areas: " + esc_join(summary_terms) + ".\n"
+                + _INJECT_END + "\n"
+            )
+            insertions.append((pos, block))
+
+    # Skills "Other:" row (slots 5 + 8): a single new row before the \item close.
+    if skills_terms and skills_start != -1:
+        se = src.find("\\end{itemize}", skills_start)
+        if se != -1:
+            close = src.rfind("}}", skills_start, se)
+            if close != -1:
+                row = (" \\\\\n     \\textbf{Other}{: " + esc_join(skills_terms)
+                       + "} " + _INJECT_SKILLS_OTHER + "\n    ")
+                insertions.append((close, row))
+
+    # Apply right-to-left so earlier offsets stay valid.
+    for pos, text in sorted(insertions, key=lambda x: x[0], reverse=True):
+        src = src[:pos] + text + src[pos:]
+
+    return src, placed
+
+
 def inject_keywords(latex_src: str, terms: List[str],
                     heading: str = "Core Competencies") -> Tuple[str, List[str]]:
     """Distribute honest keywords across the LaTeX source like a recruiter expects.
@@ -298,6 +428,12 @@ def inject_keywords(latex_src: str, terms: List[str],
     second pass reproduces the same output rather than stacking. Returns
     (new_source, injected_terms).
     """
+    # Phase 9 (R22): the owner's bundled resume has a known structure, so place
+    # keywords in the exact owner-specified order/locations. Arbitrary LaTeX still
+    # uses the generic recruiter-style distribution below.
+    if _is_hardcoded_resume(latex_src):
+        return place_keywords_structured(latex_src, terms)
+
     src = latex_src or ""
     # Remove any previously injected fragments so repeated runs don't stack.
     src = _remove_injected_block(src)
@@ -440,6 +576,16 @@ def _remove_injected_block(src: str) -> str:
     # Strip APPENDED experience items (R17): "\n\item <term> % ats-item\n".
     item_pat = r"\n\\item [^\n]*?%\s*ats-item[^\n]*\n?"
     s = re.sub(item_pat, "", s)
+    # Phase 9 (R22): strip appended \resumeItem lines from structured placement.
+    # Consume the leading newline+indent + the item; do NOT consume the trailing
+    # newline (so the following \resumeItemListEnd keeps its own line → idempotent).
+    s = re.sub(r"\n[ \t]*\\resumeItem\{[^\n]*?%\s*ats-item", "", s)
+    # Phase 9 (R22): strip the Skills "Other:" injected row WITH its leading "\\"
+    # separator and trailing indent so re-injection reproduces byte-identically.
+    s = re.sub(
+        r" \\\\\n\s*\\textbf\{Other\}\{:.*?%\s*ats-skills-other[^\n]*\n[ \t]*",
+        "", s,
+    )
     # Legacy: strip inline woven clauses from older outputs.
     weave_pat = r" \(applying [^\n]*?\)" + re.escape(_INJECT_WEAVE)
     s = re.sub(weave_pat, "", s)

tests/test_structured_placement.py

@@ -0,0 +1,117 @@
+"""Phase 9 (R22): structured keyword placement into the hardcoded resume.
+
+Asserts the owner's exact order/word-count waterfall, append-only behaviour, and
+idempotency. No LaTeX compilation required.
+"""
+import os
+import re
+
+import pytest
+
+from src.latex_resume import inject_keywords, place_keywords_structured
+
+
+def _resume() -> str:
+    try:
+        from src.default_resume import DEFAULT_RESUME_LATEX
+        if DEFAULT_RESUME_LATEX.strip():
+            return DEFAULT_RESUME_LATEX
+    except Exception:
+        pass
+    p = os.path.join(
+        ".planning", "phases", "09-hardcoded-resume-keyword-placement",
+        "resume-source.tex",
+    )
+    if os.path.exists(p):
+        with open(p, encoding="utf-8") as f:
+            txt = f.read()
+        if txt.strip():
+            return txt
+    pytest.skip("resume source not available")
+
+
+KWS = [f"kw{i:03d}" for i in range(120)]
+
+
+def _items_in(block: str):
+    """Return the list of tagged-item term-strings found in `block`."""
+    return re.findall(r"\\resumeItem\{([^\n]*?)\}\s*% ats-item", block)
+
+
+def test_summary_slot_15_to_20():
+    out, _ = inject_keywords(_resume(), KWS)
+    m = re.search(r"Additional areas: (.+?)\.\s*% ===== end", out, re.S)
+    assert m, "summary injection block missing"
+    n = len([t for t in m.group(1).split(",") if t.strip()])
+    assert 15 <= n <= 20, f"summary has {n} terms (want 15-20)"
+
+
+def test_byjus_psm_25_to_30():
+    out, _ = inject_keywords(_resume(), KWS)
+    # The tagged item inside the Asst PSM block.
+    seg = out[out.find("Asst. Product Success Manager"):]
+    seg = seg[: seg.find("\\resumeItemListEnd") + 20]
+    items = _items_in(seg)
+    assert items, "no tagged item in PSM block"
+    n = len([t for t in items[-1].split(",") if t.strip()])
+    assert 25 <= n <= 30, f"PSM has {n} terms (want 25-30)"
+
+
+def test_byjus_ps_25_to_30():
+    out, _ = inject_keywords(_resume(), KWS)
+    seg = out[out.find("Product Specialist -- User Experience"):]
+    seg = seg[: seg.find("\\resumeItemListEnd") + 20]
+    items = _items_in(seg)
+    assert items, "no tagged item in Product Specialist block"
+    n = len([t for t in items[-1].split(",") if t.strip()])
+    assert 25 <= n <= 30, f"PS has {n} terms (want 25-30)"
+
+
+def test_ml_edutech_8_to_12():
+    out, _ = inject_keywords(_resume(), KWS)
+    seg = out[out.find("ML Edutech"):]
+    seg = seg[: seg.find("\\resumeItemListEnd") + 20]
+    items = _items_in(seg)
+    assert items, "no tagged item in ML Edutech block"
+    n = len([t for t in items[-1].split(",") if t.strip()])
+    assert 8 <= n <= 12, f"ML Edutech has {n} terms (want 8-12)"
+
+
+def test_skills_other_row_present():
+    out, _ = inject_keywords(_resume(), KWS)
+    m = re.search(r"\\textbf\{Other\}\{: (.+?)\}\s*% ats-skills-other", out)
+    assert m, "Skills Other row missing"
+    n = len([t for t in m.group(1).split(",") if t.strip()])
+    assert n >= 15, f"Skills Other has {n} terms (want >=15 once filled)"
+
+
+def test_anchor_before_list_end():
+    out, _ = inject_keywords(_resume(), KWS)
+    assert re.search(r"% ats-item[^\n]*\n\s*\\resumeItemListEnd", out), \
+        "tagged item not anchored immediately before a \\resumeItemListEnd"
+
+
+def test_append_only_original_bullets_intact():
+    src = _resume()
+    out, _ = inject_keywords(src, KWS)
+    for original in [
+        "Increased user retention by 8",
+        "Managed",
+        "Launched an EdTech app portfolio",
+        "Led end-to-end revamp of the",
+    ]:
+        assert original in out, f"original bullet text lost: {original!r}"
+
+
+def test_idempotent():
+    src = _resume()
+    o1, _ = inject_keywords(src, KWS)
+    o2, _ = inject_keywords(o1, KWS)
+    assert o1 == o2, "placement is not idempotent (injected lines stacked)"
+
+
+def test_dedupe_skips_present_terms():
+    # A term already in the resume must not be re-added.
+    out, placed = place_keywords_structured(_resume(), ["Roadmap Planning", "kwX1", "kwX2"])
+    assert "Roadmap Planning" not in placed
+    assert "kwX1" in placed