Twin Emperors: add validation checklist, failure log targets, and AGENT.md guidance

[RovxBot]

Objective

Add a Twin Emperors validation checklist, hard failure-log targets, and AGENT.md guidance so the strategy rebuild can be implemented and verified without guesswork.

Why this exists

The current Twin issues now cover state management, tanking, healer routing, ranged/pet control, and event-driven scripting. This issue is the final hardening pass that makes those changes testable and documents the encounter rules that future agents should preserve.

Evidence from current logs

Local validation from the latest reviewed logs shows the current strategy is not close to stable yet:

tmp/Playerbots.log

• 493 split_risk entries
• 27 movement_failure entries
• 3 pickup_failed entries
• 40 unsupported_setup entries
• The first failure sequence includes:
  • 2026-05-07 17:00:00.403 [TwinEmps] movement_failure bot=jihulool role=healer side=left path=none
  • 2026-05-07 17:00:00.496 [TwinEmps] movement_failure bot=jihthu role=healer side=right path=none
  • 2026-05-07 17:00:00.499 [TwinEmps] pickup_failed bot=jihthu boss=Vek'nilash
  • 2026-05-07 17:00:00.501 [TwinEmps] split_risk bot=jihthu reason=tank_swap_failure separation=61
• After tank deaths the run degrades into unsupported state spam:
  • 2026-05-07 17:00:58.311 [TwinEmps] unsupported_setup reason=missing_warlocks_and_melee_tanks
  • repeated through the end of the attempt

tmp/WoWCombatLog.txt

• 68 Heal Brother
• 210 Blizzard
• 19 Arcane Burst
• 16 Uppercut
• 8 Unbalancing Strike
• Arcane Burst still hits non-tank raid members and pets during unstable states:
  • 17:00:15.153 hits Mumkew, Wolf, and Krovilzurl
  • 17:00:56.309 hits Roviden, Ahgir, and Rov

These numbers define the baseline that the rebuilt strategy must beat.

Required implementation

Create a repeatable Twin Emperors validation checklist and document it in code-adjacent form and in AGENT.md.

Validation checklist

Add a Twin-specific checklist that covers at least the following scenarios:

1. Supported comp baseline

• Two valid warlock tanks are present.
• Two valid melee tanks are present.
• Side healers are assigned.
• Pull proceeds through at least one full teleport cycle.

2. Multi-teleport stability run

• Run long enough to observe at least 3 teleports.
• Verify post-teleport reacquisition completes before DPS hold is released.
• Verify separation never falls into emergency or terminal bands in a supported run.

3. Hazard pressure run

• Confirm ranged stack reacts correctly to Blizzard.
• Confirm Arcane Burst only hits the active Vek'lor tank in stable states.
• Confirm pets stay suppressed during unsafe windows.

4. Bug handling run

• Confirm mutate/explode bug targeting still works.
• Confirm ranged and hunters do not violate Vek'lor safe-radius constraints while servicing bugs.
• Confirm pets do not chase bug targets through unsafe positions.

5. Degraded / death handling run

• Kill or remove one expected Twin tank and verify reserve takeover occurs deterministically.
• If no valid reserve exists, confirm the encounter enters explicit degraded behavior rather than thrashing.
• Confirm unsupported_setup is emitted only when the setup is truly unsupported, not as a substitute for recovery logic.

6. Reset / wipe cleanup run

• Wipe the encounter.
• Verify all Twin-local state is cleared for the next pull.
• Verify stale teleport, pickup, owner, and hazard state does not leak into the next attempt.

Required success metrics

A supported validation run is only considered successful if all of the following are true:

• zero pickup_failed
• zero movement_failure
• zero split_risk
• zero heal_brother_terminal
• zero stable-state Arcane Burst hits on non-tank players or pets
• no repeated unsupported_setup spam during otherwise supported runs
• no executor thrash after teleport

Required artifacts

Document where validation results should be captured so future work can be compared consistently:

• relevant Playerbots.log snippets
• relevant WoWCombatLog.txt snippets
• a short pass/fail summary by scenario
• any known caveats if a degraded behavior case is intentionally non-recoverable

AGENT.md updates required

Append a focused Twin Emperors section that future agents can follow without re-discovering the encounter model.

That section must document:

• the encounter phase model: PrePull, Stable, TeleportWindow, PickupRecovery, EmergencySplitRecovery, Degraded
• the distinction between transient aggro and stable ownership
• the rule that Twin state must be keyed by instanceId or otherwise kept instance-scoped
• that raid DPS holds stay active until both emperors are stable and separation is safe
• that emergency split recovery suppresses normal DPS, pet, follow, and assist behavior
• that spell-driven events are first-class inputs for Blizzard, Arcane Burst, Heal Brother, Uppercut, and Unbalancing Strike
• that supported validation must hit the zero-failure-log targets above

Code and docs hotspots

• AGENT.md
• Any Twin-specific validation or debug helpers introduced during the rebuild
• Existing AQ40 Twin utility and action files for comments or inline validation notes where helpful:
  • src/Ai/Raid/Aq40/Util/RaidAq40TwinEmperors.cpp
  • src/Ai/Raid/Aq40/Util/RaidAq40Helpers.cpp
  • src/Ai/Raid/Aq40/Action/RaidAq40Actions_TwinEmperors.cpp
  • src/Ai/Raid/Aq40/Multiplier/RaidAq40Multipliers.cpp
  • src/Ai/Raid/Aq40/Util/RaidAq40Scripts.cpp

References

• Gold standard: mod-playerbots/mod-playerbots#2363
• Supporting reference: mod-playerbots/mod-playerbots#2258
• Structural reference: brighton-chi/mod-playerbots Sunwell Eredar Twins encounter and scripts
• Structural reference: brighton-chi/mod-playerbots Black Temple helper/state patterns

Relationship to other issues

• Depends on #2 Twin Emperors: rebuild encounter state machine and stable ownership
• Depends on #6 Twin Emperors: add spell-driven encounter scripts and strict multiplier suppression
• Validates #3 tank swap/recovery, #4 healer routing, and #5 ranged/bug/pet control

Suggested execution order

1. #2 rebuild encounter state machine and stable ownership
2. #6 add spell-driven encounter scripts and strict multiplier suppression
3. #3 rewrite tank swap, pickup anchors, and emergency split recovery
4. #4 rewrite healer side support and recovery routing
5. #5 tighten ranged, bug, and pet control around Vek'lor
6. #7 finalize validation checklist, failure-log targets, and AGENT.md guidance

Acceptance criteria

• AGENT.md contains a focused Twin Emperors section matching the architecture above.
• The validation checklist is explicit enough that another agent can run it without additional interpretation.
• A supported validation run meets the zero-failure-log target.
• Degraded scenarios produce deterministic behavior and clear pass/fail expectations instead of ambiguous log spam.