Grenade/blitz tactical evaluation upgrade

[hummat]

Problem

BetterBots grenade and blitz support works, but the decision model is still too flat.

Current logic mostly reduces grenade use to:

• coarse per-tick context from heuristics.lua
• one shared target resolver
• execution-time revalidation inside grenade_fallback.lua

That is enough for "use grenade or do not use grenade", but not enough for:

• choosing between direct-impact, AoE, defensive, placeable, and companion-command tools
• choosing a placement point instead of blindly following one unit target
• distinguishing "detonate at the dog's position" from "retask the dog to a better enemy"
• preserving the original tactical reason through the full wield/aim/release sequence

The result is usable but shallow grenade logic. Bots still leave value on the table and can make bad target or placement choices.

Goals

• Improve grenade/blitz effectiveness, not just frequency
• Improve tactical intelligence across all grenade/blitz families
• Keep the work compatible with the current BetterBots settings surface
• Reuse as much current infrastructure as possible
• Add enough logging and event data to validate decisions in one run

Non-goals

• Replace all BetterBots ability heuristics with a full repo-wide utility system
• Absorb Arbites companion-command tagging work tracked in #49
• Build a heavy map-wide planner with long-lived tactical state

This issue is intentionally narrower than #22. Treat it as a grenade/blitz-scoped tactical-evaluation upgrade, not a global heuristic rewrite.

Existing overlap and constraints

• Planning artifacts in-repo:
  • docs/superpowers/specs/2026-04-08-grenade-blitz-tactical-evaluator-design.md
  • docs/superpowers/plans/2026-04-08-grenade-blitz-tactical-evaluator.md
• #49 remains the Arbites companion-command smart-tag lane. Reference it; do not duplicate it here.
• #22 is the broader architectural north star. This issue is a scoped step in the same direction.
• Recent hadrons-blessing Arbites build data shows both adamant_whistle and adamant_shock_mine are relevant in real builds, and some mine builds run Lone Wolf, which disables the companion entirely. The design must therefore split Arbites grenade logic into:
  • dog-present paths
  • no-dog / Lone Wolf paths

Proposed design

Introduce a shared grenade/blitz tactical evaluator that produces a structured decision object instead of only returning a boolean.

Suggested decision shape:

• template
• intent_score
• reason
• target_unit
• placement_mode
• placement_position
• commit_policy
• confidence

This becomes the contract between tactical evaluation and grenade execution.

Decision pipeline

1. Situation scan

   • Extend current grenade context with richer but bounded tactical summaries:
     • top candidate units by role
     • local cluster density around those units
     • ally-pressure state
     • bot-local danger state
     • short-lived memory for failed/recent uses

2. Opportunity generation

   • Generate scored tactical opportunities rather than a single yes/no:
     • horde_clear
     • priority_pick
     • interrupt_special
     • defensive_breathing_room
     • boss_or_elite_punish
     • hold_point_denial
     • companion_retask

3. Template-family matching

   • Match grenade/blitz templates against the opportunity types they are actually good at:
     • direct-impact
     • AoE lethal
     • AoE control / defensive
     • placeable denial
     • companion command

4. Execution contract

   • Carry the chosen tactical decision into grenade_fallback.lua
   • Revalidate against the original reason, not just a generic "should still throw?"
   • Allow family-specific commit behavior:
     • direct-impact can abort on target loss
     • AoE can continue if the cluster still exists
     • defensive tools can continue if pressure remains
     • whistle can continue only if companion assumptions still hold

Template-family doctrine

Direct-impact

Examples:

• veteran_krak_grenade
• ogryn_grenade_friend_rock
• zealot_throwing_knives
• psyker_throwing_knives
• broker_missile_launcher

Needs:

• single-target scoring
• armor/threat/distance weighting
• target persistence checks
• clutter/melee-pressure penalties where appropriate

AoE lethal

Examples:

• frag
• fire
• tox
• ogryn explosive grenades
• adamant_grenade

Needs:

• cluster-anchor selection
• density + elite-mix scoring
• self/team safety checks
• placement-aware commit logic

AoE control / defensive

Examples:

• smoke
• shock
• flash
• smite
• chain lightning

Needs:

• ally-pressure and breathing-room scoring
• self-centered and ally-centered placement options
• timing logic biased toward pre-collapse use

Placeable denial

Examples:

• adamant_shock_mine

Needs:

• feet / near-path / ally-defense-zone placement doctrine
• persistence-value scoring rather than immediate hit-count scoring
• short memory to avoid duplicate low-value drops

Companion command

Examples:

• adamant_whistle

Needs:

• dog-state-aware scoring
• distinction between:
  • detonate current engagement
  • retask dog to a better target
  • hold because current dog assignment is already acceptable
• explicit link to #49 for smart-tag command integration

Arbites split

Dog present

• whistle logic enabled
• companion-aware reasoning enabled
• reference #49 for smart-tag dog direction

Lone Wolf / no dog

• whistle path disabled
• grenade and mine logic still active
• no companion assumptions in scoring or context

Settings integration

Keep the existing settings surface, but reinterpret it at the tactical-evaluation layer:

• aggressiveness modulates tactical score thresholds
• reserve policy modulates charge conservation
• family-level doctrine controls whether a bot spends freely or keeps a charge in reserve

Observability

Add logging/event fields for:

• chosen opportunity type
• chosen target / placement mode
• cluster or pressure score
• retask reason
• abort reason
• commit reason

Without this, in-game validation will be guesswork.

Phased tasks

• Define grenade/blitz decision object and shared evaluator entry point
• Extend grenade context with richer tactical summaries
• Replace the single shared grenade target resolver with family-specific candidate resolvers
• Implement placement-aware scoring for direct-impact, AoE, defensive, and mine families
• Carry decision objects into grenade_fallback.lua and revalidate against original intent
• Split Arbites logic into dog-present and no-dog / Lone Wolf paths
• Integrate reserve-policy handling with the existing settings surface
• Add debug/event instrumentation for opportunity choice, placement mode, and abort/commit reasons
• Add unit tests for scoring, placement selection, and execution revalidation paths
• Validate in-game with focused grenade/blitz scenarios, especially Arbites whistle and shock mine

Acceptance criteria

• Bots choose different tactical targets for direct-impact, AoE, defensive, mine, and whistle templates
• AoE grenades use cluster-aware placement instead of always following target_enemy
• Mines use deliberate placement doctrine rather than enemy-target mimicry
• Arbites logic behaves correctly with and without a live companion
• The implementation references #49 and #22 instead of duplicating them
• Logs make grenade/blitz reason and placement mode visible in a single validation session

Related

• #49 Arbites bot directs Cyber-Mastiff via companion-command smart tag
• #22 Utility-based ability scoring (architectural upgrade)

[hummat]

Cross-reference: team coordination for blitzes

#14 (ability cooldown staggering) deliberately excludes grenades/blitzes. The time-window suppression model fits cooldown-based ults (taunt, shout, dash) but not charge-based consumables:

• Ult waste = same-purpose ability fired redundantly (time-correlated, same-category)
• Blitz waste = AoE overkill on the same target cluster (spatially-correlated, needs target awareness)

Blitz coordination should live here in #80's tactical evaluator — specifically in the opportunity generation and scoring phases. The evaluator already plans to carry target_unit and placement_position through the decision object, which gives the right primitives for "don't throw a second frag at a cluster that's already being fragged."

This is not a blocker for #14 (ult staggering ships independently) or #80 (the evaluator design already covers this implicitly via scored opportunities).