docs(handoff): clôture session 2026-05-09

Session de 6h consacrée au fix DETTE-006 (bug d'échelle pixel
grounding). Bilan : 2/5 commits fix faits (smart_resize + refactor
parser bbox_2d), 3/5 bloqués par découverte DETTE-010 (divergence
factor 28 vs 32 sur checkpoint Qwen3-VL-8B-Instruct, à instruire
demain matin).

Effets de bord positifs : registre dette technique créé
(14 entrées P1/P2/P3), investigation mémoire visuelle orpheline
documentée, infra clarifiée (vLLM absent, Transformers direct retenu,
checkpoint Qwen3-VL-8B fp16 téléchargé 17 GB).

Voir docs/handoffs/2026-05-09_session_audit.md pour détail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/handoffs/2026-05-09_session_audit.md

@@ -0,0 +1,168 @@
+# HANDOFF — Session 2026-05-09 (clôture)
+
+Rédigé le 2026-05-09 15:46 CEST.
+
+## 1. ÉTAT FACTUEL DU REPO
+
+- Branche : `feature/qw-suite-mai`
+- 10 commits du jour (les plus récents en HEAD) :
+  - `df5ad5933` docs(dette): MAJ DETTE-010 (config trouvé, divergences) + création DETTE-014 (smart_resize calé sur mauvaise référence)
+  - `bfbf0f9c3` refactor(grounding): centralise parser bbox_2d
+  - `ecc5a233a` docs(dette): création DETTE-013 env tests dev local
+  - `4df1ba577` docs(dette): création DETTE-011 bug cv2 Python 3.12
+  - `0d7bcd18a` feat(grounding): module smart_resize officiel Qwen3-VL
+  - `e9702b4df` docs(dette): création DETTE-010 vérif preprocessor_config Qwen3-VL
+  - `293e54b4e` docs(dette): création DETTE-012 (vLLM hors scope) + maj DETTE-010 (cible Transformers + AWQ)
+  - `e0b47e451` docs(refs): commit groupé docs de référence session 2026-05-08
+  - `5dc20cc85` docs(dette): rectif mapping DETTE-005 + DETTE-008/009 + investigation mémoire visuelle orpheline
+  - `88ed103de` docs(dette): création registre dette technique + 7 entrées rétroactives
+- Pas de push (tous commits locaux)
+- Working directory : modifications antérieures intactes
+  (héritées du handoff 2026-05-08, hors scope cette session)
+- Checkpoint Qwen3-VL-8B-Instruct fp16 téléchargé localement
+  (`~/.cache/huggingface/hub/models--Qwen--Qwen3-VL-8B-Instruct/`,
+  17 GB, 16/16 fichiers, 0 `.incomplete`)
+- Total : 2 modules purs créés (smart_resize, bbox_parser) + 100%
+  coverage (58 tests unitaires) + registre dette créé avec 14
+  entrées + −96 lignes nettes sur resolve_engine.py.
+
+## 2. DÉCISIONS PRISES CETTE SESSION
+
+- **Cible backend grounding** : Transformers direct (pas vLLM —
+  vLLM absent de la machine, infra inexistante, cf. DETTE-012).
+  Cohérent avec `core/grounding/server.py` déjà câblé en
+  Transformers et service systemd `rpa-grounding.service`.
+- **Modèle cible** : `Qwen/Qwen3-VL-8B-Instruct` fp16 (16 GB safetensors)
+  + chargement Transformers avec `BitsAndBytesConfig(load_in_4bit=True,
+  bnb_4bit_quant_type="nf4")` à la volée (~5-6 GB VRAM runtime).
+  Pas d'AWQ officiel disponible pour Qwen3-VL-8B
+  (`Qwen/Qwen3-VL-8B-Instruct-AWQ` → 404 HF, repo inexistant).
+- **T2A v2 désactivé** durant la session pour libérer la VRAM
+  partagée du RTX 5070 (12 GB).
+- **Strict no-op sémantique sur le refactor parser bbox_2d**
+  (commit 2/5 `bfbf0f9c3`) : préservation des contrats sémantiques
+  des 3 sites d'appel via paramètre `formats=` (pas seulement
+  préservation comportementale).
+- **Investigation DETTE-010 en fin de journée a révélé une
+  divergence majeure** : `factor` effectif probable 32 (vs 28
+  hypothèse matin) car `patch_size=16` dans le `preprocessor_config.json`
+  du checkpoint Qwen3-VL-8B-Instruct ; convention
+  `size.longest_edge`/`shortest_edge` différente de `min_pixels`/`max_pixels`.
+  → Arrêt avant commit 3/5 du fix DETTE-006 pour reprendre demain
+  matin frais avec investigation propre, plutôt que coder à
+  l'aveugle sur fin de journée.
+
+## 3. PROBLÈMES OUVERTS (par criticité)
+
+- **[P0] DETTE-006 — Bug d'échelle pixel grounding**
+  fix en cours, 2/5 commits faits (smart_resize + refactor parser),
+  3/5 bloqués par DETTE-010 + DETTE-014 (alignement convention
+  Qwen3-VL effective).
+- **[P1] DETTE-010 IN_PROGRESS** — investigation
+  `Qwen2VLImageProcessorFast` + sémantique `longest_edge`/`shortest_edge`
+  + `patch_size=16` requise demain matin. Bloquant Étape 2
+  (validation grounding isolée). Date revue : 2026-05-10.
+- **[P1] DETTE-014 OPEN** — module `core/grounding/smart_resize.py`
+  calé sur `Qwen2VLImageProcessor` (factor=28, max=1_003_520) alors
+  que le checkpoint utilise `Qwen2VLImageProcessorFast` avec
+  `patch_size=16` (factor probable 32). À réaligner après DETTE-010.
+- **[P2] Autres dettes (P2/P3)** listées dans
+  `docs/DETTE_TECHNIQUE.md` (DETTE-001 à 014) — pas urgent, revues
+  par défaut +14 jours sauf P1 listées ci-dessus.
+
+## 4. PROCHAINE ACTION CONCRÈTE (demain matin)
+
+- **Étape A** : lire
+  `transformers.models.qwen2_vl.image_processing_qwen2_vl_fast`
+  pour comprendre les défauts effectifs (`min_pixels`, `max_pixels`,
+  interaction `patch_size × merge_size` → `factor`) et la sémantique
+  de `size.longest_edge`/`shortest_edge` (côté max ou produit total ?).
+- **Étape B** : tester le chargement runtime via
+  `AutoProcessor.from_pretrained('Qwen/Qwen3-VL-8B-Instruct')` puis
+  inspecter ses attributs (`processor.image_processor.size`,
+  `processor.image_processor.patch_size`, etc.) pour confirmer la
+  convention réelle au runtime.
+- **Étape C** : tirer la convention validée et décider de
+  l'ajustement de `core/grounding/smart_resize.py` :
+  - soit ajuster `FACTOR_DEFAULT` / bornes du module existant
+    (et adapter les tests),
+  - soit créer un nouveau module dédié Qwen3-VL si la sémantique
+    diverge trop (ex: `core/grounding/smart_resize_qwen3.py`).
+- **Étape D** : commit 3/5 du fix DETTE-006 avec convention validée
+  (les 4 sites de `resolve_engine.py` parseront enfin par
+  `resized_w/h` au lieu de `small_w/h`).
+- **Critère de succès Étape 2** (validation grounding isolée) :
+  sur fixture `data/training/live_sessions/bg_DESKTOP-58D5CAC_windows/shots/heartbeat_1773792436.png`
+  (2560×1600), bouton OK localisé à `cx ≈ 0.45-0.55` (vs 0.17 le 8 mai).
+- **Critère de succès Étape 3** (replay e2e) : workflow rpa complet
+  sur 1 dossier MOREL sans clic aberrant, latence acceptable.
+
+## 5. CE QUE LE PROCHAIN CLAUDE DOIT LIRE (ordre)
+
+- @docs/handoffs/2026-05-09_session_audit.md (ce fichier)
+- @docs/DETTE_TECHNIQUE.md (en particulier DETTE-010 et DETTE-014, P1 bloquants)
+- @/home/dom/.cache/huggingface/hub/models--Qwen--Qwen3-VL-8B-Instruct/snapshots/0c351dd01ed87e9c1b53cbc748cba10e6187ff3b/preprocessor_config.json
+  (config réel du checkpoint, pivot pour DETTE-010)
+- @core/grounding/smart_resize.py (module à éventuellement réaligner)
+- @core/grounding/bbox_parser.py (commit 2/5 OK strict no-op, à conserver)
+- @docs/MIGRATION_VLM_PLAN_2026-05-09.md (plan original toujours
+  valide pour la suite, mais cible backend ajustée :
+  Transformers direct, pas vLLM)
+- @docs/handoffs/2026-05-08_session_audit.md (handoff veille,
+  pour contexte si besoin)
+
+## 6. RÈGLES DE LA JOURNÉE À RESPECTER DEMAIN
+
+- Maximes Dom : « il faut prendre le temps d'aller vite »,
+  « rustine interdite », « on lit la doc avant de faire quoi que ce soit ».
+- **Investigation infra** : ne jamais conclure à l'absence d'un
+  composant sans avoir vérifié N endroits possibles
+  (PATH, autres venvs, conda, Docker, système, autres caches).
+  Leçon DETTE-012 vLLM : conclusion hâtive « stack vLLM absente »
+  sur fouille partielle, rectifié par Dom. Présenter les
+  vérifications négatives comme partielles et demander
+  confirmation, pas comme une absence définitive.
+- **Refactor de code mature** : préserver les contrats sémantiques
+  en plus des comportements techniques. Leçon refactor parser
+  Occ 3 + Occ 4 : strict no-op via paramètre `formats=` plutôt
+  que centralisation laxe qui élargit silencieusement les formats
+  acceptés.
+- **Validation explicite par étape**, stop pour relecture diff
+  sur tout code prod. Pas d'enchaînement A→B→C sans GO entre les
+  étapes structurantes.
+- **Datage** : forcer `date '+%Y-%m-%d %H:%M %Z'` avant tout
+  commentaire daté.
+- **Désactivation contrôle** : flag env + log WARNING + entrée
+  dette + revue +14j (et registre central
+  `docs/DETTE_TECHNIQUE.md`).
+- **Git destructeur** : jamais en combo, atomique, validation
+  explicite.
+- **Un commit = une intention** (respecté sur les 10 commits du jour).
+
+## 7. NOTES POUR LA PROCHAINE SESSION
+
+- **Action pré-prochaine session — hygiène git** : commit
+  `chore(docs): déplacement business_docs vers archive/`
+  pour consolider en 1 commit la suppression à la racine
+  (ANALYSE_MOAT_RPA_VISION_V3.md, PITCH_INVESTISSEURS_RPA_VISION_V3.md
+  → `D` dans `git status`) et l'ajout dans `archive/business_docs/`
+  (encore en `?? archive/`). Pas de DETTE associée, juste hygiène.
+- **Mécanisme de délestage VRAM rpa_v3** : à documenter dans le
+  module concerné (path à retrouver), trace de fonctionnalité
+  transversale.
+- **Bug cv2 (DETTE-011) + env tests (DETTE-013)** : la batterie
+  `pytest tests/unit/` entière n'est pas exécutable en dev local
+  sans configuration spécifique (`RPA_API_TOKEN` ou
+  `RPA_AUTH_DISABLED` + version cv2 compatible Python 3.12).
+  Prévoir une session dédiée pour rétablir l'exécution complète
+  ou découpler les tests purs des tests qui chargent
+  `agent_v0.server_v1.api_stream`.
+- **Audit exhaustif modules orphelins** (au-delà périmètre AUDIT
+  serveur) : mentionné dans
+  `docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md` §6,
+  dette identifiée sans numéro réservé. À instruire post-démo
+  Kerella.
+- **DETTE-010 + DETTE-014 sont la première chose à débloquer
+  demain matin**. Sans cet alignement, le commit 3/5 du fix
+  DETTE-006 et l'Étape 2 (validation grounding isolée) sont
+  impossibles à instruire correctement.