organic-teams (#50 B1): tune-aware team_generator (routes hard-breakers off tunes)

team_generator now reasons about tune-COMPATIBILITY, not just roles, using the
committed m5_synergy tune_compat tag:
- CADENCE_KEYSTONES = (unkillable, block_damage); _is_tune_reliant(skeleton,recs)
  = unified skeleton whose survival rests on a cadence keystone (double_survival
  stalls are NOT tune-reliant). tune_compat_summary -> {tune_reliant, breakers,
  manageable, tunable}; tunable=False only when a tune-reliant comp carries a
  hard_breaker (its flat Increase SPD desyncs the cadence, e.g. Teodor).
- Every CandidateComp now carries a tune_compat summary (so downstream shows WHY).
- _row_tunable wired as the PRIMARY ranking key in both sort sites: tune-broken
  comps sink below every tunable comp (NOT dropped — hard_breakers stay welcome in
  stall archetypes; only banned from tune-reliant ones). This is the piece the B1
  agent didn't reach before a session limit; completed here.

Test fix: test_poison_engine_does_not_credit_weaken_amplifier widened top=60->300
— the #49 amp-tag fix correctly credits more hit-amplifiers, so hit/wm_gs comps
outscore poison in the heuristic and pushed unified[poison] below the old window
(109 tunable poison comps exist at top=300). Channel-crediting check unchanged.

15 tests pass (incl. B1's new hard-breaker-in-tune-reliant + stall-welcome tests).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCKiWFsFcWRBkL4kWf1q6b

Author: SnoopLawg

tests/test_team_generator.py

@@ -166,8 +166,12 @@ def test_poison_engine_does_not_credit_weaken_amplifier(owned):
     """A poison engine carrying needs:def_break (m5_synergy_graph adds it to all
     attackers) must NOT be credited a Dec-DEF/Weaken edge — that amplifier is a
     HIT-channel multiplier, not a poison one.  Asserted via M2 resolve."""
+    # top=300: after the 2026-06-30 amp-tag fix more heroes are correctly credited
+    # as hit-amplifiers, so hit/wm_gs comps outscore poison comps in the heuristic
+    # and push unified[poison] below the old top-60 window. This test verifies
+    # channel CREDITING (not ranking), so widen the window to capture poison comps.
     res = tg.generate("clan_boss", owned,
-                      tg.GenOpts(rank_with="heuristic", top=60))
+                      tg.GenOpts(rank_with="heuristic", top=300))
     poison_comps = [c for c in res if c.skeleton == "unified[poison]"]
     assert poison_comps, "no poison-engine comps generated"
 
@@ -280,6 +284,99 @@ def test_double_survival_skeleton_is_abstract_and_valid():
     assert any(n.startswith("double_survival") for n in names)
 
 
+# --------------------------------------------------------------------------- #
+# 5c. Tune awareness — a hard_breaker (flat team Inc-SPD that desyncs a fixed
+#     speed-tune, e.g. Teodor the Savant) can't tune in a TUNE-RELIANT comp, but
+#     is fine in a buff-coverage STALL.  `manageable` (e.g. Ninja) is allowed
+#     everywhere.  Each emitted comp carries a tune_compat summary.
+# --------------------------------------------------------------------------- #
+# Tune-reliant comp = unified speed-tune skeleton whose survival rests on a
+# CADENCE keystone (unkillable). Hand-built (champion names live only in the
+# TEST, never in team_generator's source).
+TUNE_RELIANT_WITH_BREAKER = ["Maneater", "Demytha", "Teodor the Savant",
+                             "Venomage", "Geomancer"]   # Maneater=unkillable
+# A buff-coverage stall (double_survival) the same hard_breaker is welcome in.
+STALL_WITH_BREAKER = ["Demytha", "Cardiel", "Teodor the Savant",
+                      "Venomage", "Mithrala Lifebane"]
+
+
+def test_hard_breaker_is_disqualifying_in_tune_reliant_comp():
+    """Teodor (hard_breaker) inside an unkillable speed-tune comp -> the comp is
+    tune-reliant and therefore NOT tunable; _tune_ok prunes it."""
+    recs = [r for r in (tg.record_for(n) for n in TUNE_RELIANT_WITH_BREAKER)
+            if r is not None]
+    assert len(recs) == len(TUNE_RELIANT_WITH_BREAKER)
+    # the fixture really does contain a hard_breaker and a cadence keystone.
+    assert any(r.get("tune_compat") == "hard_breaker" for r in recs)
+    assert any(r.get("survival_currency") in tg.CADENCE_KEYSTONES for r in recs)
+
+    sk = tg.build_unified_skeleton("poison")
+    assert tg._is_tune_reliant(sk, recs) is True
+    summary = tg.tune_compat_summary(recs, sk)
+    assert summary["tune_reliant"] is True
+    assert "Teodor the Savant" in summary["breakers"]
+    assert summary["tunable"] is False
+    # the hard prune rejects it from a tune-reliant skeleton.
+    assert tg._tune_ok(recs, sk) is False
+
+
+def test_hard_breaker_is_allowed_in_stall_archetype():
+    """The SAME hard_breaker is fine in a double_survival (buff-coverage) stall:
+    the stall does not need a tight tune, so tunable is not required."""
+    recs = [r for r in (tg.record_for(n) for n in STALL_WITH_BREAKER)
+            if r is not None]
+    assert len(recs) == len(STALL_WITH_BREAKER)
+    assert any(r.get("tune_compat") == "hard_breaker" for r in recs)
+
+    sk = tg.build_double_survival_skeleton("poison")
+    assert tg._is_tune_reliant(sk, recs) is False     # stall -> never tune-reliant
+    summary = tg.tune_compat_summary(recs, sk)
+    assert summary["tune_reliant"] is False
+    assert "Teodor the Savant" in summary["breakers"]   # still REPORTED
+    assert summary["tunable"] is True                   # but not disqualifying
+    assert tg._tune_ok(recs, sk) is True
+
+
+def test_manageable_hero_allowed_in_tune_reliant_comp():
+    """A `manageable` hero (the tune is built AROUND it) is NOT a breaker — a
+    tune-reliant comp containing it stays tunable."""
+    comp = ["Maneater", "Demytha", "Ninja", "Geomancer", "Venomage"]
+    recs = [r for r in (tg.record_for(n) for n in comp) if r is not None]
+    sk = tg.build_unified_skeleton("hit")
+    summary = tg.tune_compat_summary(recs, sk)
+    assert summary["tune_reliant"] is True
+    assert "Ninja" in summary["manageable"]
+    assert summary["breakers"] == []
+    assert summary["tunable"] is True
+    assert tg._tune_ok(recs, sk) is True
+
+
+def test_generated_tune_reliant_comps_never_contain_a_hard_breaker(owned):
+    """End-to-end: no emitted TUNE-RELIANT comp (unified + cadence keystone)
+    places a hard_breaker; stall comps may, and every comp carries tune_compat
+    with a consistent `tunable`."""
+    res = tg.generate("clan_boss", owned,
+                      tg.GenOpts(rank_with="heuristic", top=200))
+    assert len(res) > 0
+    saw_tune_reliant = False
+    saw_stall_with_breaker = False
+    for c in res:
+        tc = c.tune_compat
+        assert tc is not None and "tunable" in tc
+        breakers = tc["breakers"]
+        # every emitted comp is tunable (non-tunable comps are pruned upstream).
+        assert tc["tunable"] is True, (sorted(c.team), tc)
+        if tc["tune_reliant"]:
+            saw_tune_reliant = True
+            assert breakers == [], (sorted(c.team), "breaker in tune-reliant comp")
+        elif c.skeleton.startswith("double_survival") and breakers:
+            saw_stall_with_breaker = True
+    assert saw_tune_reliant, "expected at least one tune-reliant comp"
+    # the owned roster has hard_breakers, so they MUST surface in stalls (routed
+    # there instead of being globally banned).
+    assert saw_stall_with_breaker, "hard_breakers were not routed to any stall"
+
+
 # --------------------------------------------------------------------------- #
 # 6. Tractability — pool=all under budget, max_candidates respected, deterministic
 # --------------------------------------------------------------------------- #

tools/team_generator.py

@@ -20,7 +20,10 @@
      team-rule pruning (branch-and-bound `can_add`) + cheap pre-score
      (cb_team_explorer.predict_score) ; dedup by frozenset(team)
   4. M2 resolve each comp; drop comps with unmet HARD edges (no survival /
-     broken keystone-enabler / no channel-consistent amplifier->engine)
+     broken keystone-enabler / no channel-consistent amplifier->engine) AND
+     tune-awareness: drop a `hard_breaker` (flat team Inc-SPD that desyncs a
+     fixed speed-tune) from a TUNE-RELIANT comp — routing it to a stall instead
+     (see tune_compat_summary); each emitted comp carries a tune_compat summary
   5. rank by M5 fitness (cb_sim for CB via rank_with=auto, heuristic elsewhere)
   6. novelty flag vs scraped DWJ templates
 
@@ -88,6 +91,15 @@
 STRONG_KEYSTONES = ("unkillable", "block_damage", "shield",
                     "ally_protect", "revive_on_death")
 
+# CADENCE keystones: survival that must be RE-CAST on an exact SPD beat (the
+# Unkillable / Block-Damage recast has to land *before* the next boss AoE, which
+# is the whole point of a CB speed-tune). These are the keystones whose survival
+# is bound to a precise SPD cadence — so a flat team Increase SPD (a
+# `hard_breaker` hero) desyncs them and the comp can never tune.
+# The OTHER strong keystones (shield / ally_protect / revive_on_death) are
+# always-on covers a buff-coverage STALL refreshes without a tight cadence.
+CADENCE_KEYSTONES = ("unkillable", "block_damage")
+
 
 # ============================================================ options / output
 @dataclass
@@ -123,6 +135,11 @@ class CandidateComp:
     fitness_kind: str               # "cb_sim" | "heuristic"
     constraint_report: dict
     novelty: bool
+    # tune-compatibility summary (see tune_compat_summary): why a comp can or
+    # can't be speed-tuned. {tune_reliant: bool, breakers: [names],
+    # manageable: [names], tunable: bool}. Downstream (recommender / team_tune)
+    # surfaces this so the user sees WHY a role-valid comp is/ isn't tunable.
+    tune_compat: Optional[dict] = None
 
     def as_dict(self) -> dict:
         return {
@@ -131,6 +148,7 @@ def as_dict(self) -> dict:
             "fitness": self.fitness,
             "fitness_kind": self.fitness_kind,
             "novelty": self.novelty,
+            "tune_compat": self.tune_compat,
             "constraint_report": self.constraint_report,
         }
 
@@ -469,6 +487,63 @@ def team_rules_report(recs: list, skeleton: Skeleton, location: str,
     return all_pass, rep
 
 
+# ------------------------------------------------------------ tune awareness
+# WHY: the generator proposes role-valid comps but is blind to whether a comp
+# can actually be SPEED-TUNED. A `hard_breaker` hero (m5_synergy `tune_compat`)
+# emits a flat team Increase SPD that desyncs any fixed speed-tune cadence —
+# POISON in a tune-reliant comp, but FINE in a buff-coverage stall.
+# `manageable` (conditional/self TM the tune is built AROUND) is allowed
+# everywhere — the sim/tune verifies it. `ok` has no tune issue.
+#
+# HEURISTIC for "is this comp tune-reliant?" (kept deliberately simple, per the
+# task brief — infer from skeleton type + survival_currency):
+#   - The `double_survival` skeleton is a buff-COVERAGE stall: it survives via
+#     multiple always-on keystones refreshed over the 50-turn fight, NOT a tight
+#     SPD cadence -> NOT tune-reliant (a hard_breaker is welcome here).
+#   - The `unified` skeleton is the MEN-style speed-tune skeleton. It is
+#     tune-reliant when a CADENCE keystone (unkillable / block_damage, which must
+#     be recast on an exact SPD beat) carries survival. A unified comp surviving
+#     purely on an always-on cover (shield only) is not cadence-bound.
+def _is_tune_reliant(skeleton: "Skeleton", recs: list) -> bool:
+    """True iff this comp's SURVIVAL rests on a precise SPD cadence (see note)."""
+    if skeleton.name.startswith("double_survival"):
+        return False
+    return any(r.get("survival_currency") in CADENCE_KEYSTONES for r in recs)
+
+
+def tune_compat_summary(recs: list, skeleton: "Skeleton") -> dict:
+    """Per-comp tune-compatibility summary carried on each CandidateComp.
+
+    `tunable` is False only when a tune-reliant comp contains a `hard_breaker`
+    (its flat Increase SPD desyncs the cadence the comp's survival depends on).
+    """
+    tune_reliant = _is_tune_reliant(skeleton, recs)
+    breakers = [r["name"] for r in recs
+                if r.get("tune_compat") == "hard_breaker"]
+    manageable = [r["name"] for r in recs
+                  if r.get("tune_compat") == "manageable"]
+    return {"tune_reliant": tune_reliant, "breakers": breakers,
+            "manageable": manageable,
+            "tunable": not (tune_reliant and breakers)}
+
+
+def _tune_ok(recs: list, skeleton: "Skeleton") -> bool:
+    """A `hard_breaker` is disqualifying ONLY in a tune-reliant comp (it can't
+    tune); in a stall it is allowed. Used as a HARD ranking PENALTY (not a drop):
+    non-tunable comps sink BELOW every tunable comp, so the recommended top is
+    breaker-free tune-reliant comps + stalls, and hard_breakers are routed toward
+    the `double_survival` stall archetype rather than blanket-banned. Comps stay
+    in the output (marked tune_compat.tunable=False) so downstream sees WHY."""
+    return tune_compat_summary(recs, skeleton)["tunable"]
+
+
+def _row_tunable(row: list) -> bool:
+    """Tunability of a scored row ([0]=team names, [1]=skeleton). Primary rank
+    key so the recommended top is always tunable; non-tunable comps sink last."""
+    recs = [r for r in (record_for(n) for n in row[0]) if r is not None]
+    return _tune_ok(recs, row[1])
+
+
 def can_add(partial_recs: list, rec: dict, location: str,
             faction_lock: bool) -> bool:
     """Incremental branch-and-bound prune (only HARD, monotone constraints).
@@ -1032,8 +1107,11 @@ def _cb_rank(scored: list, survivors: list, roster_recs: list,
                 rep[4], rep[5], rep[6] = val, "cb_sim", bd
 
     all_rows = scored + extra_rows
-    # simmed comps (kind cb_sim) outrank heuristic ones; tie-break by value.
-    all_rows.sort(key=lambda x: (0 if x[5] == "cb_sim" else 1, -x[4]))
+    # tunable comps first (a tune-reliant comp carrying a hard_breaker can't hold
+    # its cadence — sink it below every tunable comp); then simmed (cb_sim) over
+    # heuristic; then by value.
+    all_rows.sort(key=lambda x: (0 if _row_tunable(x) else 1,
+                                 0 if x[5] == "cb_sim" else 1, -x[4]))
     return all_rows, n1, n2
 
 
@@ -1133,7 +1211,8 @@ def generate(location: str, roster: list, opts: Optional[GenOpts] = None
         pre = skeleton_prescore(recs, sk, roles_by_hero)
         scored.append([team, sk, rr, rule_rep, h["fitness"], "heuristic",
                        h.get("breakdown", {}), pre, core])
-    scored.sort(key=lambda x: -x[4])
+    # tunable comps first (tune-reliant + hard_breaker can't tune -> sinks last).
+    scored.sort(key=lambda x: (0 if _row_tunable(x) else 1, -x[4]))
 
     if rank_with == "cb_sim" and is_cb:
         scored, n_phase1, n_phase2 = _cb_rank(
@@ -1147,10 +1226,12 @@ def generate(location: str, roster: list, opts: Optional[GenOpts] = None
     for team, sk, rr, rule_rep, fit, kind, bd, _pre, _core in scored[:opts.top]:
         rep = dict(rule_rep)
         rep["fitness_breakdown"] = bd
+        recs = [r for r in (record_for(n) for n in team) if r is not None]
         out.append(CandidateComp(
             team=team, skeleton=sk.name, resolve=rr, fitness=fit,
             fitness_kind=kind, constraint_report=rep,
-            novelty=_is_novel(team)))
+            novelty=_is_novel(team),
+            tune_compat=tune_compat_summary(recs, sk)))
     report["candidates_evaluated"] = len(survivors)
     report["candidates_returned"] = len(out)
     return _Result(out, report)