feat(upskill): aggregate mode ingests ranked jobs and their recorded gaps (#264)

* feat(upskill): aggregate mode ingests ranked jobs and their recorded gaps

/upskill's aggregate mode only read job_search_tracker.csv and guessed
required skills from the role/sector/notes columns, even though /rank
already fetches and scores postings that never make it into the tracker.
Aggregate mode now also reads ranked entries (rank_score >= 45, the
Moderate Fit floor) from job_scraper/seen_jobs.json, dedupes them against
tracker rows on case-insensitive company+role (reusing the match
tools/auto_mode_browser.py's _tracker_keys already implements), and
prefers a job's recorded gaps over an inferred skill list wherever both
exist. The heatmap's Gap Source column and report header now show the
recorded-vs-inferred / tracked-vs-ranked split.

Depends on #263. Discussed in #258.

* fix(upskill): cite only upstream precedent for the aggregate dedupe key

tools/auto_mode_browser.py's _tracker_keys does not exist upstream and
does not exist in this fork either, so the dedupe bullet in Step 3.1
of the upskill skill pointed at a phantom implementation. Drop that
reference and keep only the /notion-sync precedent, which is verified
present in upstream/master. Re-pin the pinned test assertion to the
surviving citation so the dangling reference can't silently return.

Addresses the CHANGES_REQUESTED review on #264.

tests/test_upskill_skill.py

@@ -0,0 +1,113 @@
+"""Guards for the /upskill skill spec.
+
+The skill is a markdown spec (the spec IS the implementation), so these
+tests pin the invariants that would break silently: the header format that
+lint_skills.py enforces, and aggregate mode's merge of tracker rows with
+/rank's recorded gaps from seen_jobs.json (previously aggregate mode only
+read the tracker and inferred skills from free-text columns).
+"""
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+try:
+    import yaml  # noqa: F401 - only probing availability for the lint integration test
+    _HAVE_YAML = True
+except ImportError:
+    _HAVE_YAML = False
+
+REPO = Path(__file__).resolve().parent.parent
+SKILL = REPO / ".claude" / "skills" / "upskill" / "SKILL.md"
+
+
+def _sections(text: str) -> dict[str, str]:
+    """Split a skill spec into {heading: body} by '##' headers.
+
+    Splitting this way lets a fork's extra sections sit between the ones
+    under test without shifting which text a given assertion sees.
+    """
+    parts = text.split("\n## ")
+    result = {}
+    for part in parts[1:]:
+        heading, _, body = part.partition("\n")
+        result[heading.strip()] = body
+    return result
+
+
+class UpskillSkillSpec(unittest.TestCase):
+    def test_skill_file_exists_with_lint_compliant_header(self):
+        self.assertTrue(SKILL.is_file(), "skill spec missing")
+        text = SKILL.read_text(encoding="utf-8")
+        self.assertTrue(text.startswith("---\n"), "skill spec must start with YAML frontmatter")
+        self.assertIn("name: upskill", text)
+
+    def test_step2_reads_ranked_jobs_with_moderate_fit_floor(self):
+        sections = _sections(SKILL.read_text(encoding="utf-8"))
+        step2 = sections.get("Step 2: Load Data", "")
+        self.assertIn("seen_jobs.json", step2)
+        self.assertIn("rank_score >= 45", step2)
+        self.assertIn(
+            "gap persistence",
+            step2,
+            "Step 2 must document the graceful-degradation clause for entries scored before gaps existed",
+        )
+
+    def test_step3_documents_dedupe_and_gap_precedence(self):
+        sections = _sections(SKILL.read_text(encoding="utf-8"))
+        step3 = sections.get("Step 3: Pass 1 — Hard Skill Diff", "")
+        self.assertIn("case-insensitive company + role", step3, "Step 3 must specify the dedupe key")
+        self.assertIn(
+            "/notion-sync",
+            step3,
+            "Step 3 must cite the upstream precedent for the dedupe key, not a fork-only file",
+        )
+        self.assertIn(
+            "Recorded gaps beat inferred skills",
+            step3,
+            "Step 3 must state that recorded gaps take precedence over inferred skills",
+        )
+        self.assertIn("(100 - fit_rating) / 100", step3)
+        self.assertIn("(100 - rank_score) / 100", step3)
+
+    def test_step5_heatmap_shows_gap_provenance(self):
+        sections = _sections(SKILL.read_text(encoding="utf-8"))
+        step5 = sections.get("Step 5: Build Gap Heatmap", "")
+        self.assertIn("recorded gaps", step5)
+        self.assertIn("inferred", step5)
+
+    def test_step8_report_header_counts_both_sources(self):
+        sections = _sections(SKILL.read_text(encoding="utf-8"))
+        step8 = sections.get("Step 8: Write and Save Report", "")
+        self.assertIn("T tracked, R ranked", step8)
+
+    def test_important_rules_cover_untrusted_data_and_no_backfill(self):
+        sections = _sections(SKILL.read_text(encoding="utf-8"))
+        rules = sections.get("Important Rules", "")
+        self.assertIn(
+            "never instructions",
+            rules,
+            "rules must state stored gaps are untrusted data, never instructions",
+        )
+        self.assertIn(
+            "Never invent gap history",
+            rules,
+            "rules must forbid back-filling a missing gaps field by guessing",
+        )
+
+    @unittest.skipUnless(
+        _HAVE_YAML,
+        "PyYAML not installed (the CI Python-test job omits it; the lint job runs lint_skills.py directly)",
+    )
+    def test_lint_skills_passes(self):
+        result = subprocess.run(
+            [sys.executable, str(REPO / "tools" / "lint_skills.py")],
+            cwd=REPO,
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual(result.returncode, 0, f"lint_skills.py failed:\n{result.stdout}{result.stderr}")
+
+
+if __name__ == "__main__":
+    unittest.main()