Shader CHAMPION converged: 28 t/s (4.8x), correctness-gated; f16acc refused; ~15% left is quantize-dispatch (profile, not tile)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/shader-tuning.md

@@ -80,3 +80,23 @@ L-path 28 t/s WITHOUT the M regression. Shippable champion. Progression (L): 5.8
 BK_STEP=2 is the occupancy sweet spot; reverted to iter5 champion (28 t/s). Shared-based occupancy
 exhausted. Next lever: **f16 accumulators** (register-based occupancy, no extra barriers) to break
 the 33–64 reg band toward 2048 resident threads.
+
+## Iteration 7 — f16acc REFUSED (Fable), campaign CONVERGED
+Fable declined to build f16acc, with proof: (1) q8_1 MMQ is f32acc-only upstream by design
+("integer dot mmq performs better with f32 accumulators"); (2) we're SHARED-limited not
+register-limited at the champion (shared caps 4 wg=1024 threads before the thread cap), so shrinking
+acc registers can't lift occupancy; (3) f16 accumulation over K≈2560 risks overflow/NaN.
+
+## FINAL CHAMPION (iter5) — correctness-gated
+- **ub128 = 28.1 t/s, ub256 = 28.5 t/s** (was 5.8/7.4 broken; ub64/M control 20.6, untouched).
+- **Progression: 5.8 → 23.4 → 26.2 → 28.1 t/s = 4.8×**, ~35% of roofline on a GPU with NO matrix cores.
+- **Correctness ✓**: llama-server GPU completion coherent+correct ("...Tokyo. Tokyo is the capital
+  of Japan."). Champion changes are exact-math GEMM reblocking (tile + BK_STEP, f32 acc unchanged) —
+  correctness preserved by construction; the gate confirms it.
+- Patch: `patches/llama.cpp-0005-mali-shader-CHAMPION.patch` (Mali warptile branch + BK_STEP spec
+  constant #11, L-scoped).
+
+## Remaining ~15% (separate problem, NOT this shader)
+50% occupancy but 35% roofline ⇒ the gap is outside mul_mmq: the q8_1 activation-quantize dispatch
+(separate kernel per matmul), dequant ALU cost, or barrier stalls. Next lever = a per-dispatch
+PROFILE of the ub128 breakdown (quantize vs matmul vs non-GEMM), not tile tuning.