chore(hole): neteja de comentaris obsolets i notes sobre riscos latents

source/game/entities/player.hpp

@@ -250,6 +250,14 @@ class Player : public AnimatedSprite {
     // visual a partir de `floor_y` (Y de la base del tile del forat,
     // canvas píxels). Desactiva input direccional reusant la branca
     // AIRBORNE existent. No-op si el jugador no està a GROUNDED.
+    //
+    // CONTRACTE: `floor_y` ha de correspondre a la vora inferior de
+    // l'AABB del decal trigger (`hole.y + hole.h`). Els dos callers
+    // actuals — `Hole::onPlayerContact` i `Player::integrateJump` —
+    // passen exactament aquest valor. Qualsevol caller futur ha de
+    // respectar la convenció: el clip rect del render es calcula com
+    // `floor_y - SPRITE_FLOOR_OFFSET`, i un valor incorrecte desplaçaria
+    // visualment el "sòl" sobre el qual el sprite del jugador desapareix.
     void enterHoleFall(float center_x, float center_y, float floor_y);
 
     // Despawn lògic: el jugador acaba de creuar la porta de sortida.