WC3 ability refactor: centralize lifecycles and expand save coverage

AGENTS.md

@@ -124,7 +124,7 @@ This codebase is inspired by **Quake 2** (id Software). The developer is deeply
 | WC3 inventory, world-item lifecycle, item UI presentation | [docs/games/warcraft-3/inventory-and-items.md](docs/games/warcraft-3/inventory-and-items.md) |
 | WC3 Goblin Land Mines `AIpm`/`Amin`/`Amnx`, delayed death AOE, targeted-item charge completion | [docs/games/warcraft-3/land-mines.md](docs/games/warcraft-3/land-mines.md) |
 | WC3 ability/item presentation art, effect edict lifetimes, JASS effect handles, consumable charge semantics | [docs/games/warcraft-3/ability-and-item-effects.md](docs/games/warcraft-3/ability-and-item-effects.md) |
-| WC3 ability implementation from data, behavior, and focused evidence | [docs/games/warcraft-3/ability-implementation-plan.md](docs/games/warcraft-3/ability-implementation-plan.md) |
+| WC3 ability implementation from data, behavior, and focused evidence | [docs/games/warcraft-3/ability-implementation.md](docs/games/warcraft-3/ability-implementation.md) |
 | WC3 creep ability aliases, `code=` mapping, parent-owned registry rows | [docs/games/warcraft-3/creep-ability-aliases.md](docs/games/warcraft-3/creep-ability-aliases.md) |
 <| WC3 item orb damage via `CAbilityAttackBonus` and `S_OrbOnHit` BuffID state | [docs/games/warcraft-3/item-orbs.md](docs/games/warcraft-3/item-orbs.md) |
 | WC3 poison on-hit buff state (`Aven`/`Apoi`/`Apo2`), data-driven periodic DPS | [docs/games/warcraft-3/poison-attacks.md](docs/games/warcraft-3/poison-attacks.md) |
@@ -186,7 +186,7 @@ This codebase is inspired by **Quake 2** (id Software). The developer is deeply
 - Use the same patterns for module organization, data structures, and naming conventions as in Quake 2.
 - Prefer simple, flat, and data-oriented design over complex object-oriented abstractions.
 - Keep the code readable, compact, and close to the metal — minimize unnecessary indirection.
-- **Split gameplay behaviors into their owning abilities.** An ability owns its orders, validation, state transitions, animation moves, timers, interruption/inverse paths, and cleanup. Movement is an ability too: reusable steering, stepping, routing, and support-height behavior belong to Move. Keep `g_monster.c`, `m_unit.c`, `g_ai.c`, and equivalent general-purpose machinery focused on lifecycle, dispatch, and shared mechanisms; do not grow them with individual ability rules or direct spell-specific update calls. Reuse or extend generic function-table hooks so the implementation stays in `skills/s_*.c`, following `s_raven.c` and `s_move.c`. Existing misplaced behavior is precedent to refactor, not a pattern to copy. See [ability ownership](docs/games/warcraft-3/ability-implementation-plan.md#ability-owned-orders-and-persistent-behavior).
+- **Split gameplay behaviors into their owning abilities.** An ability owns its orders, validation, state transitions, animation moves, timers, interruption/inverse paths, and cleanup. Movement is an ability too: reusable steering, stepping, routing, and support-height behavior belong to Move. Keep `g_monster.c`, `m_unit.c`, `g_ai.c`, and equivalent general-purpose machinery focused on lifecycle, dispatch, and shared mechanisms; do not grow them with individual ability rules or direct spell-specific update calls. Reuse or extend generic function-table hooks so the implementation stays in `skills/s_*.c`, following `s_raven.c` and `s_move.c`. Existing misplaced behavior is precedent to refactor, not a pattern to copy. See [ability ownership](docs/games/warcraft-3/ability-implementation.md#ability-owned-orders-and-persistent-behavior).
 - **Flat ability procedures.** Keep classname, procedure, behavior flags, target shape and optional order names directly in each `ability_t` registry row. `CAbility*` names are functions using `abilityProc_t`, not descriptor globals. Pass `abilityitem_t` (actual rawcode plus registry row) through typed `abilityCall_t` messages and read authored data/profile text by that rawcode. A concrete procedure handles its own switch cases and delegates unhandled messages by directly calling its TFT parent procedure, as a Win32 window procedure calls its default procedure; do not add runtime parents, inherited callback tables, descriptor objects, or compatibility bridges. `AB_SPELL` selects the shared cast processor; combine independent policies such as `AB_CHANNEL`, `AB_TOGGLE`, and `AB_AUTOCAST`. Register concrete AbilityData row IDs or implementation codes and necessary internal commands; never register abstract retail classes. Runtime indices are rebuilt with the registry. Run `python3 tools/wc3_ability_class_audit.py --format=coverage` to audit registration against the TFT registry; registration alone does not prove implemented behavior.
 - **No hacks. No silent fallbacks. No hiding errors.** Every implementation must have a solid reasoning. If a shortcut is taken, mark it with `/* HACK: */` or `/* TODO: */` and explain *why* the proper fix is not yet possible. Never demote, drop, or silently skip unresolved data — instead, log it with `fprintf(stderr, ...)` so future debugging reveals the gap. Demotion (e.g. `FT_TEXTURE → FT_FRAME` for unresolved resources) hides the real problem; the resource should be found and resolved, not discarded. This rule extends to every stage of the rendering pipeline: when a resolved path fails to load (`R_LoadModel` returns NULL), loads the wrong type (not `ID_43DM`, missing `.m3`), or is dropped for any other reason, log it to `stderr` before the `continue`/`return` — do not silently discard. The same applies to map-load resolution failures (CTile, cliff, object models): log each unresolved item by name so the gap is visible in a bounded run without requiring a manual dump call.
 - **Keep one representation for one shader concept.** Do not add zero-count modes, parallel fallback uniforms, or per-game exception branches when the normal array/struct path can represent the value. Add an exception only when the common representation is demonstrably impossible, and document that constraint at the branch.
@@ -300,7 +300,7 @@ Key flags: `-prefix <Name>` sets the struct and function prefix; `-root <FrameNa
 - **Fixtures must not hide the authored contract.** Use a non-stock Data cell so the test cannot pass on a hardcoded
   retail constant, *and* a stock-shaped case from the brief (`ability_audit -raw`): omitted ROC columns, sentinel zeros,
   and the actual BuffID/`targs` tokens. Injecting the fourcc or scale the consumer already hardcodes is not coverage.
-  See [ability tests](docs/games/warcraft-3/ability-implementation-plan.md#4-tests-first-from-the-brief).
+  See [ability tests](docs/games/warcraft-3/ability-implementation.md#4-tests-first-from-the-brief).
 - **Assert the gameplay lock, not a proxy.** Expiry, cancel, and inverse tests check the observable a player would
   notice (channel code, movement flags, current order), not only the buff or helper execute already set. If another
   ability can strip that status, that path is in scope.

ARCHITECTURE.md

@@ -273,7 +273,7 @@ For in-depth details on specific engine subsystems, consult the following dedica
   other behaviors reuse its locomotion operations while retaining their own goals and arrival conditions. General-purpose
   machinery such as `g_monster.c`, `m_unit.c`, and `g_ai.c` provides lifecycle, dispatch, and shared mechanisms; it must not
   accumulate individual spell rules or direct spell update calls. Use flat callback/function-table contracts, not a new
-  class hierarchy. See [WC3 ability ownership](docs/games/warcraft-3/ability-implementation-plan.md#ability-owned-orders-and-persistent-behavior).
+  class hierarchy. See [WC3 ability ownership](docs/games/warcraft-3/ability-implementation.md#ability-owned-orders-and-persistent-behavior).
 - **Test-First Verification**: Recreate gameplay situations through production entry points in automated tests, including
   timing and callback order. Extend fixtures and harnesses before resorting to a game launch. See
   [verification workflow](CONTRIBUTING.md#test-first-behavior-verification) for the limited visual/platform exceptions.

CONTRIBUTING.md

@@ -35,7 +35,7 @@ The Raven Form refactor provides concrete examples in `games/warcraft-3/game/tes
 by Move before animation completion and checks that ascent continues without replacing Move; it also covers pause and
 reversal. `t_combat.c` tests an animation end callback installing another sequence, `t_slk.c` covers ROC rawcode columns,
 and `t_game.c` checks persistence. The generated `mdxgen morph` model supplies the required sequences without retail assets.
-See [ability implementation](docs/games/warcraft-3/ability-implementation-plan.md) for ownership and test design.
+See [ability implementation](docs/games/warcraft-3/ability-implementation.md) for ownership and test design.
 
 Launch the game only for a specific property that remains untestable after considering these options, such as framebuffer
 output or OS input integration. State that coverage gap before launching, keep the run bounded with `+com_frame_limit N`,

docs/cheat-commands.md

@@ -98,6 +98,17 @@ hero mana <amount>
 
 Without an amount, `hero health` fills current health to the Hero's current maximum and `hero mana` fills current mana to its current maximum. With an amount, the command sets the current value to that non-negative integer, clamped to the current maximum; it never changes maximum health or maximum mana. Health uses the ordinary runtime health setter, while mana updates the current mana pool directly. These commands require `sv_cheats 1` and a selected controllable Hero.
 
+The equivalent selected-unit family applies the same current-stat behavior across the full selected controllable group, including ordinary units, structures, Heroes, and shared-control units:
+
+```
+unit health
+unit health <amount>
+unit mana
+unit mana <amount>
+```
+
+With no amount, the requested current pool is filled independently to each selected unit's current maximum. With an amount, each selected unit is set to that non-negative integer clamped independently to its own current maximum. The commands do not change maximum health/mana. `unit health` affects every selected controllable unit. `unit mana` affects only selected controllable units whose maximum mana is greater than zero; units with no mana pool are skipped without changing their current mana value. Missing or enemy-only selections are rejected.
+
 For map-start resource testing, `wc3_cheat_starting_resources` is a session-only CVar. Set it before loading the map:
 
 ```
@@ -223,20 +234,25 @@ The commands use the active map's authored `Dawn`, `Dusk`, and `DayHours` values
 The obsolete `wc3_cheat_timeofday_scale` registration was removed: current `G_UpdateTimeOfDay` never read it.
 Use `day`/`night` for phase testing; there is no independent clock-speed cheat.
 
-Unit-oriented commands target the first selected unit:
+Most unit-oriented commands target the first selected unit; the health/mana cheats below apply to the full selected controllable group:
 
 ```
 give item <rawcode>
 give ability <rawcode>
 give xp <amount>       # hero only
+unit health [amount]
+unit mana [amount]
 god                    # toggle selected player unit invulnerability
 kill                   # kill the selected controllable unit
 ```
 
-`god` and `kill` resolve the primary controllable selection (including shared-control units). Missing/enemy-only
-selections are rejected. `god` changes that actor's invulnerability; `kill` clears it and invokes the actor's normal
-`die` callback, preserving death events, food cleanup, corpse/revival state, and deselection. The invisible controller
-is never the target. Previously both commands mutated the controller, and `kill` only changed its health.
+`unit health` and `unit mana` operate on the full selected controllable group (including shared-control units), while
+`god` and `kill` continue to resolve the primary controllable selection. Missing/enemy-only selections are rejected.
+The stat commands fill or set only the current pool, clamped independently to each unit's current maximum; `unit mana`
+skips units whose maximum mana is zero. `god` changes that actor's invulnerability; `kill` clears it and invokes the
+actor's normal `die` callback, preserving death events, food cleanup, corpse/revival state, and deselection. The
+invisible controller is never the target. Previously both commands mutated the controller, and `kill` only changed its
+health.
 
 `give item` uses the normal item spawn and pickup path, so inventory capacity and passive item effects remain authoritative. `research <rawcode>` remains available for the existing non-cheat research/debug path.
 

docs/diagnostic-tools.md

@@ -28,7 +28,7 @@ map, save, load, and compare origin/abilities/inventory. Parser tests are
 
 Poll one Warcraft III ability from the installed MPQs without parsing SLK by
 hand. This is the first command when implementing or finishing an ability.
-See [Mechanical Workflow](games/warcraft-3/ability-implementation-plan.md#mechanical-workflow).
+See [Mechanical Workflow](games/warcraft-3/ability-implementation.md#mechanical-workflow).
 
 ```sh
 make build/bin/ability_audit