feat(phase-21): cont.7c — giant approach VALIDATED (func_80176D94 structurally matched) + recipe §27

- Drew chose GIANT SESSION. Validated the giant-matching approach end-to-end:
  hand-matched func_80176D94 (152 ins) to STRUCTURALLY-MATCHED (calls/constants/GPU-packet
  all byte-correct) via the recipe: cached Ghidra-C + call-matching callee decls (arg-arity:
  func_80177784 called 3-arg vs canonical 4-arg) + §17 register pins (regalloc-shift) +
  sibling func_80176FF4 idioms (coord strength-reduce, GPU linked-list pointer).
- Residual = pure regalloc-coalescing (2 extra callee regs vs target caller-saved/-reuse)
  -> saved .run/backlog_drafts/func_80176D94.c as grinder/wave fuel (permuter territory).
- cookbook §27: the Giant matching recipe (5 steps + the pin-reuse caveat + the
  accumulator-coalescing residual class). Giants reach structurally-matched FAST; the last
  mile is regalloc -> isolated-agent + permuter work, not main-loop serial grind.
- Giant pool is ~18 tractable (152-284 ins) + 2 monsters, bigger than the assess's 8.
- NEXT: worker_wave over the giants (§27-seeded) -> gate + propagate ×134. fleet 63.17%.

docs/matching-cookbook.md

@@ -1900,3 +1900,33 @@ a permutation the source doesn't capture. **RULE: before assuming a cheap source
 `match_one` its saved draft to get the SOURCE closeness** — if it's far-off, it's a permuter-class wall (grinder
 territory), not a pin target. The genuinely pin-crackable ones are source-close + a single coalescing/CSE residual
 (§25 func_80128ED8); the regalloc/save-schedule/cross-jump ones are the confirmed walls (§20/§25).
+
+## §27 — Giant matching recipe (Phase 21 cont.7b — validated on func_80176D94, 152 ins)
+
+Giants (reach-134 >150 ins) are the byte-weight lever. Validated approach (func_80176D94 → structurally matched,
+calls/constants/GPU-packet all byte-correct, residual = pure regalloc):
+1. **Start from the cached Ghidra-C** (`.run/ghidra_c/<fn>.c`) — giants are often CLEAN (straight-line + many
+   calls, no deep control flow), so the body structure comes nearly free. (cont.2's "stale+incomplete drafts"
+   were the OLD m2c drafts vs the grown header; the fresh Ghidra-C + canonical context is the fix.)
+2. **Arg-arity is the #1 giant blocker (the manifest's `MCOMPILE_arg-arity` bucket).** Giants call many helpers;
+   m2c/Ghidra miscount args. Declare each callee to match the ACTUAL call site — count the `$a0–$a3` (+ stack)
+   set before each `jal`, NOT the canonical sig. e.g. `func_80177784` canonical is 4-arg but called **3-arg**
+   here (`$a3` untouched) → declare `func_80177784(void*, s32, s32)`. (The shared-header canonical conflict is the
+   gate's job — `cast_call_sites`; it may bank ×1 if irreducible, §24.)
+3. **Sibling templates.** Giants cluster in families (GPU-packet builders, coord transforms). Find an
+   already-matched sibling `DEFINE_func_*` in `engine_core.h` with the same idiom and mirror its PROVEN C form —
+   e.g. the GPU-coord strength-reduce `((s32)(D * 10355) << 1) >> 16` (sibling func_80176FF4) and the GPU
+   linked-list pointer `((u32)addr & 0xFFFFFF) | 0x3000000`.
+4. **§17 register pins for the regalloc-SHIFT.** Giants use 5–7 callee regs; gcc's mapping often shifts whole-hog
+   (param→$s0 where target uses $s2, etc.). Pin the long-lived vars to their target regs
+   (`register T v __asm__("$NN")`). **CAVEAT (cont.7b, byte-proven): do NOT pin a var whose register the target
+   REUSES for a later spill** — pinning reserves the reg for that var's whole scope → blocks the reuse → gcc grabs
+   a FRESH callee reg (+1 reg, +2 prologue ins). (func_80176D94: pinning uVar5→$s0 blocked the accumulator from
+   reusing dead $s0.)
+5. **The giant residual class — accumulator-spill coalescing.** A value chained through `$v0→$a0` across calls,
+   then needing to survive a LATER call, must spill to a callee reg. The target reuses a now-DEAD callee reg; gcc
+   from natural C grabs a FRESH one (+1 reg). Hard to force from C (it's gcc's coalescing graph) → **permuter
+   fuel** (the grinder randomizes allocation and may find the reuse). func_80176D94's saved draft
+   (`.run/backlog_drafts/`) is exactly this — structurally done, 1–2 callee regs from byte-perfect.
+**Net:** giants reach STRUCTURALLY-MATCHED fast (steps 1-3); the last mile is regalloc-coalescing (step 5) — so
+giants are ISOLATED-AGENT + permuter work (per `breadth-isolated-agents-not-serial`), not main-loop serial grind.

phase-ends/CURRENT_PHASE.md

@@ -59,6 +59,22 @@ permuter-class (two R14 self-corrections; cookbook §26):**
   tail). Forward %-progress now needs a **token-heavy** investment: the **8 giants** (deep per-fn, byte-weight) or
   per-fn pin-cracking — both warrant Drew's ROI greenlight (R26/R27, §20). **→ surfaced to Drew as a fork below.**
 
+**★ UPDATE (cont.7c): Drew chose GIANT SESSION. Validated the giant approach end-to-end + distilled the recipe
+(cookbook §27):**
+- The giant pool is **~18 still-stubbed tractable giants** (152–284 ins) + 2 monsters (func_80132784=400,
+  func_80144B9C=770) — bigger than the assess's "8" (that was only the backlog-recorded ones).
+- **Hand-matched func_80176D94 (152 ins) to STRUCTURALLY-MATCHED:** all calls/constants/GPU-packet-build
+  byte-correct via the §27 recipe (cached Ghidra-C + **call-matching callee decls** for the arg-arity blocker —
+  func_80177784 is called 3-arg though canonical 4-arg — + **§17 register pins** for the regalloc-shift + the
+  **sibling func_80176FF4** coord-strength-reduce/GPU-pointer idioms). **Residual = pure regalloc-coalescing** (2
+  extra callee regs: $s5 temp + $s6 accumulator-spill vs target's caller-saved/$s0-reuse) → saved to
+  `.run/backlog_drafts/func_80176D94.c` as grinder/wave fuel (§27 step 5: permuter territory).
+- **VALIDATION (the de-risk):** giants reach structurally-matched FAST (recipe steps 1-3); the last mile is
+  regalloc-coalescing → ISOLATED-AGENT + permuter work, NOT main-loop serial grind (`breadth-isolated-agents-not-serial`).
+- **NEXT: the worker_wave over the giants** (the efficient finish) — isolated xHigh agents each draft a giant with
+  the §27 recipe seeded → I gate (`gate_stage`, flock-safe; `--src-file` for the `_a` giants) + propagate ×134.
+  Pending Drew's confirm to launch the multi-agent Workflow (the Phase-21 T4 mechanism).
+
 **★ NEXT — cont.6 option-3 is now CONFIRMED: the cached reach-134 cheap fuel is dry; the genuine levers are
 token-heavy (fresh-session work, Drew's ROI greenlight per R26/R27/§20):**
 1. **The GIANTS** (8 reach-134 >150 ins — the high-BYTE-WEIGHT lever, the one that moves the decomp.dev-comparable