Zul'Farrak: the plan carries the pyramid stairs event to the run leader (holds with a value, Velratha stands, exporter)

README.md

@@ -913,10 +913,18 @@ The terrace exemptions (`ragefireExemptions` in `ragefire_test.go`, settled with
 
 ### Zul'Farrak events: Gahz'rilla, the courtyard and Zum'rah
 
+**The pool stairs (`velratha` pull groups 5 and 6, 2026-10-20).** In the full observe run (`zf-full-19z16`, RUN-LESSONS) the run leader stopped at the pack of four at 1601-1610 1104-1111 and then stood at 1629.2 1099.0 z 9.7, a navmesh **island** at the foot of the stairs: a path from 1595.5 1092.4 to it is `partial` and ends 8.8 yd short at 1621.3 1102.9. Three followers and the healer reached the upper level instead (1629-1636 1070-1099, z 31-46.8, 46 yd from the lead, "reach spell" at a mob 37 yd below) and the gather took 6 min to summon them back. The two groups now carry `approach` rows — 1584 1050 and 1603 1043 for the five-mob pack (the last point moved from 1582 1070 on 2026-10-21 because that spot was 10.8 yd from the Witch Doctor and inside the patrol's reach), 1588 1080 and 1584 1088 for the four-mob pack (moved from 1593.6 1089.9, 16.6 yd from a Shadowhunter); the distances are in the plan note — so the run leader's party walks to a stand on the lower floor west of the stair mouth (path corners of the 209 mmaps; not live-run yet). The refused pullback of the same run (144 s) is the run leader's own retry, not the plan.
+
+**The pyramid phase in the plan (2026-10-21, feat/zf-full-module-plan).** The stairs event's phase is instance data **1** (`EVENT_PYRAMID`, 0-8 in `zulfarrak.h`: 3 = `PYRAMID_WAVE_1`, 7 = `PYRAMID_WAVE_3`). The agent's own driver still cannot read it: its `wait_for` holds on units, objects and hostiles, so `stairs_top` waits for the proxy (Nekrum 7796 seen at the foot). For the TortoiseBots run leader the waits carry a `hold` (`wait_for.hold`, the wait's run leader form: plan-export writes the hold row in place of the wait) with a `value` (`hold.value`: the instance data value that ends the event, written as a script value, flags 8 without the encounter flag 32): the cage leg's Weegli wait holds the stairs top to 3, `stairs_top`'s Nekrum wait to 7. The run leader compares for equality, so a value must last (3 and 7 last a whole wave; 2 lasts one instance update). A value is refused on a pull group's or a boss's hold and when it is 0.
+
+**Plan format compatibility (2026-10-21).** `wait_for.hold` and `hold.value` are new fields of plan format version 1; the version number is unchanged (every plan file would have to change with it). The plan reader refuses unknown fields (`DisallowUnknownFields`), so a turtle-agent binary built before feat/zf-full-module-plan (f11df6d) refuses `dungeons/zulfarrak.json` from that branch on (`unknown field "hold"` / `"value"`): run Zul'Farrak with a binary built from this branch or later. Other plan files do not use the fields and load in either build.
+
 **Gahz'rilla (PR A, stacked on PR B).** The optional `gahzrilla` leg sits between `velratha_b` and `courtyard`: it walks to the gong stand (1652.84 1168.99 10.67, 3.5 yd from the gong), pulls the eight packs on and near the walk Gahz'rilla takes out of his pool, then the `use_object` step with `via_item` rings the
 Gong of Zul'Farrak (141832, spawn row 27140 at 1650.91 1171.88 10.9, lock 459): a bot that carries the Mallet of Zul'Farrak (9240) gets `cmd use 9240 <bot> entry:141832@1650.9,1171.9,10.9` (the Mallet is used ON the gong: its on-use spell 11434 is an open-lock effect aimed at a game object; round 3 of the live test sent `cmd open` of the gong, which did nothing and answered nothing); a `wait_for` waits up to 30 s for a living Gahz'rilla (7273) in the bots' view, and the boss fight kills him at 1702.58 1224.19 8.88. Without a Mallet in the lead bot's or the carrier's bags the leg is skipped (see `optional` above); a test gives it with `give_items`.
-What the world database says (tortoise-wow-cbspin 4f133ab): the gong is a goober with lock 459 and event 2488, the client shows it usable, so the Mallet is checked on the server when it is used. Event 2488 respawns the other gong object (guid 209001) and 2 s later summons Gahz'rilla (7273, level 46, faction 107, no spawn row)
+What the world database says (tortoise-wow-cbspin 4f133ab): the gong is a goober with lock 459 and event 2488, the client shows it usable, so the Mallet is checked on the server when it is used. Event 2488 respawns the other gong object (guid 209001, entry 20901, a Turtle decoration copy with no lock and no event; the plan never targets it) and 2 s later summons Gahz'rilla (7273, level 46, faction 107, no spawn row)
 at 1664.65 1187.67 -2.89 for 3600 s: the pit under the pool, 22 yd from the stand. His AI casts spell 33007, which fires event 2489: six moves one second apart, 1672.66 1195.93, 1681.74 1204.13, 1686.09 1207.3, 1690.54 1211.53, 1692.57 1213.66 and, 6 s after the summon, 1702.58 1224.19 8.88, which is where he stands (event 2489 has no summon: the "six trolls" of the first draft were those six rows).
+**The Mallet's source (tw_world, 2026-10-20, SELECT only).** `Lock.dbc` row 459 is type 1 (item required) with 9240, so the gong needs item 9240 and no skill or key. Item 9240 is not a quest reward, vendor item, chest or loot row anywhere: it is created by using item **9241 Sacred Mallet** (bind on pickup), whose on-use spell 11435 "Create Mallet of Zul'Farrak" (Effect 24) puts 9240 in the bags. 9241's only source is `creature_loot_template` entry 7996 at 100 %: **Qiaga the Keeper**, level 50 elite, faction 37, one spawn on map 0 at -284.792 -3447.45 188.426 (The Hinterlands); 9239 (the mace of the same name) has no source either. A ZF plan starts inside map 209 with hired level 46 bots and has no step kind for leaving the instance, travelling to map 0, killing a level-50 elite and returning, so **no bot run can obtain the Mallet**: the leg is skipped honestly, and only a test's `give_items` (`additem 9240`) reaches it.
+
 The packs: the Velratha leg clears only the strip (and the pack of five at 1712-1720 1181-1190); eight groups remain within about 45 yd of his walk, each member checked against the export: [5649 5649 5650] at 1621-1625 1192-1197, [5650] 1643.6 1200.1, [7246 7246 8095] 1649-1654 1210-1215 (radius 30: the Sandcrawler patrols), [5649] 1652.1 1219.9, [5649] 1667 1233.6,
 [5649] 1699.8 1233.8, [5650 7246] at 1700.3 1248.3 and 1713.2 1247.8 and [5649] 1714.4 1218.6 (the one the tank found no firing position for twice in the Velratha leg's batch-2 runs). The four casters at 1662-1667 1254-1260 (47 yd from the walk) are left out; the design list had them as two Shadowhunters and a Witch Doctor, the export has three Shadowhunters (rows 81594, 81592, 81595) and the Witch Doctor 81590.
 The gong stand, every pack position and the boss position are on the navmesh and reachable (`TestZulfarrakOnNavmesh`, `TestZulfarrakPlanCheck`, `TestZulfarrakRouteHasNoUnplannedPack`). **Not yet run live with the Mallet.**

docs/PLANS.md

@@ -51,7 +51,7 @@ positions are the creatures' own, so one up to 4 yd off the floor or 2.5 yd to t
 | 189 | `scarlet_cathedral`: Scarlet Monastery: Cathedral | 37-42 | 3 | draft | yes | chapel door (GO_CHAPPEL_DOOR) before Mograine and Whitemane; Mograine and Whitemane are one event: Whitemane resurrects Mograine |
 | 70 | `uldaman`: Uldaman | 41-45 | 14 | live-checked | yes | Keystone (needs the Staff of Prehistoria, made from the Gni'kiv Medallion and the Shaft of Tsol) opens the Seal of Khaz'Mul for Ironaya; Altar of the Keepers and Altar of Archaedas: ritual of three bots |
 | 815 | `gilneas_city`: Gilneas City | 42-47 | 7 | draft | yes | Harlow family chest (GO_HARLOW_FAMILY_CHEST) after the Regent-Lord and Regent-Lady; Genn Greymane (61418) is script-driven (genn_greymane): his role (final fight or event) is unverified |
-| 209 | `zulfarrak`: Zul'Farrak | 44-48 | 18 | live-checked | yes | Zum'rah: area trigger 962 makes him hostile; stairs event with Sergeant Bly's crew, Nekrum and Sezz'ziz; Weegli's gossip (or Bly's) has him blow the End Door for Ukorz and Ruuzlu; Gahz'rilla: the optional gahzrilla leg (Gong with the Mallet of Zul'Farrak, 9240; skipped without it) |
+| 209 | `zulfarrak`: Zul'Farrak | 44-48 | 18 | live-checked | yes | Zum'rah: area trigger 962 makes him hostile; stairs event with Sergeant Bly's crew, Nekrum and Sezz'ziz (its phase is instance data 1 = 7; the plan waits on Nekrum seen, no phase step yet); Weegli's gossip (or Bly's) has him blow the End Door for Ukorz and Ruuzlu; Gahz'rilla: the optional gahzrilla leg (Gong with the Mallet of Zul'Farrak, 9240; it drops from Qiaga the Keeper 7996 outside the instance and 9241 must be used to make 9240, so no bot run can obtain it; skipped without give_items) |
 | 349 | `maraudon_purple`: Maraudon: Purple | 44-49 | 6 | draft | yes | Celebras the Cursed's Scepter of Celebras event is optional; Vylestem vines (GO_VYLESTEM_VINE, GO_HEALED_CELEBRIAN_VINE) round Celebras' room |
 | 349 | `maraudon_orange`: Maraudon: Orange | 45-50 | 6 | draft | yes | Celebras the Cursed's Scepter of Celebras event is optional and not on this route; Princess Theradras: the party enters her cave by the inner passage (join of the orange and purple routes unverified) |
 | 109 | `sunken_temple`: The Temple of Atal'Hakkar | 47-52 | 6 | draft | yes | six Atal'ai statues (GO_ATALAI_STATUE_1-6) lit in order summon Atal'alarion; the six troll mini-bosses (5712-5717) are the statues' guards; four Eternal Flames (GO_ETERNAL_FLAME_1-4) summon the Avatar of Hakkar (8443, no spawn row); Jammal'an's barrier (GO_JAMMALAN_BARRIER) and the Hakkar doors (GO_HAKKAR_DOOR_1-2); Shade of Eranikus needs the Essence of Eranikus path and the Altar of Hakkar |