docs: add POC specs, handoffs, and research notes

docs/handoffs/2026-05-19_handoff_post_demo_GHT.md

@@ -0,0 +1,113 @@
+# Handoff — Post-démo GHT 2026-05-19
+
+## TL;DR
+
+✅ **Démo vidéo enregistrée en bout en bout** après une session de 14h (18-19 mai) et **15 jours de bug-chasing** depuis le 5 mai.
+
+⚠️ **Retour d'expérience amer** : on est partis d'un système moins mature mais qui **fonctionnait** (état tag `demo-stable-2026-05-12`, branche `demo/ght-2026-05-08`) et on a dérivé via une cascade de modifs locales jusqu'à un système instable. La démo enregistrée a fonctionné **grâce à des contournements**, pas grâce à une vraie résolution des bugs.
+
+🎯 **Objectif post-démo** : consolider, identifier les vrais bugs racines, restaurer un état stable utilisable pour les prochaines démos sans devoir refaire 14h de bricolage.
+
+## État final livré
+
+- **Vidéo démo** : enregistrée et utilisable
+- **Workflow** : `Demo_urgence_3_db` (`wf_483910cdd851_1778750587`) — 46 steps
+- **Branche backup git** : `backup/post-demo-2026-05-19` → commit `5ea4960e6` (poussée sur gitea)
+- **Tarball complet** : `/home/dom/ai/_archives/rpa_vision_v3_post_demo_20260519_142940.tar.gz` (8.9 Go, sha256 `7ab84f22d5a45b7880cad4efb4466f9e320f3e1e33218ceee267fc93fe7631af`)
+
+## Chronologie résumée de la session (18-19 mai)
+
+### 18 mai
+1. Création **page AIVA-URGENCE** autonome (`docs/clients/ght_sud_95/aiva_urgence/`) — interface médicale pour la démo, design dark
+2. Intégration AIVA dans le workflow : 6 nouveaux steps insérés (ord 15-20) entre `llm_generate` et `Win+D`
+3. Bug **NPM Basic Auth** sur `urgence.labs.laurinebazin.design` → bypass via `location ^~ /aiva-urgence/ auth_basic off;` directement dans `proxy_host/10.conf` (modif hors git, sera écrasée si UI NPM touchée)
+4. Bug **`pause_for_human` skip silencieux en mode autonome** → fix `safety_checks` avec `required: false` sur step 1
+5. Bug **frontend cache** : Ctrl+Shift+R obligatoire après chaque modif DB pour que VWB envoie le workflow à jour
+6. Fix **`api_stream.py:3013`** — enrichir le payload `replay_paused/pause_message/replay_id` dès le premier polling `/replay/next` (sinon gap 1-2s)
+7. Création `scripts/cancel-replays.sh` — workaround pour purger les queues serveur (bug Stop VWB)
+
+### 19 mai
+8. **Merge workflow `linux_db`** dans Demo_urgence_3_db (suppression ord 36-46, insertion 9 steps de linux_db) via agent
+9. **Bypass LLM** : `_handle_t2a_decision_action` + `_handle_llm_generate_action` acceptent maintenant `static_result` / `static_text` → décision déterministe UHCD pour MOREL Catherine (court-circuit Ollama)
+10. **Bug `delay_before/delay_after` jamais lus** au runtime → ajout step `wait` explicite + lift `duration_ms` dans `dag_execute.py`
+11. **Bug coord côté Léa** : `actual_position Y` divisé par ~27 sur certains clics (mapping client utilise dim écran tronquée `2560×60` au lieu de `2560×1600`)
+12. **Bug VWB recapture anchor** : "Recapture" via UI ne régénère PAS le PNG (les 2 anchors `anchor_d467a5411722` et `anchor_bfbffbb47be7` sont **bit-à-bit identiques** alors que capturés à 8 jours d'intervalle)
+13. **Bug Léa état mémoire** : la bulle paused n'apparaît plus dans le chat après plusieurs replays consécutifs → résolu par restart Léa Windows
+14. Solution pour NoMachine : remplacé le double-clic auto par `pause_for_human` → Dom clique manuellement pendant l'enregistrement
+
+## Bugs racines identifiés (à traiter post-démo, par ordre de gravité)
+
+### 🔴 P0 — Bug "recapture anchor ne régénère pas le PNG" (VWB)
+**Symptôme** : à chaque modif, "régression mystérieuse". L'anchor recapturé pointe sur la mauvaise icône car le PNG reste l'ancien.
+**Audit** : `visual_workflow_builder/backend/api_v3/capture.py` — chercher si `image_path` est défini AVANT le screenshot, ou si la fonction réutilise un fichier existant.
+**Impact** : explique 80% des "ça marchait hier" et des régressions silencieuses entre démos.
+
+### 🔴 P0 — Bug "Stop VWB ne purge pas la queue serveur"
+**Symptôme** : relance d'un replay = celui-ci hérite des actions en attente du précédent → Léa reprend au milieu.
+**Workaround actuel** : `./scripts/cancel-replays.sh` manuel.
+**Vrai fix** : VWB doit appeler `POST /api/v1/traces/stream/replay/<id>/cancel` quand on clique Stop.
+
+### 🔴 P0 — Bug coord côté Léa client (mapping Y cassé sur capture tronquée)
+**Symptôme** : `actual_position Y = 0.0099` au lieu de `0.265` → clic en haut de l'écran au lieu de la cible.
+**Cause** : `mss.monitors[1]` retourne intermittemment `2560×60` au lieu de `2560×1600` → Léa map `y_pct * 60 = 16 px`.
+**Audit** : `agent_v0/agent_v1/core/executor.py:606-617` — ajouter fallback dim minimale (rejeter si `height < 200`).
+
+### ⚠️ P1 — Léa client accumule un état mémoire dégradé
+**Symptôme** : après plusieurs pauses consécutives, la bulle paused n'apparaît plus (chat vide alors que le serveur envoie bien `replay_paused: true`).
+**Workaround** : restart Léa Windows.
+**Vrai fix** : reset propre de `_last_pause_msg_shown`, `_chat_window_ref`, état Tkinter à chaque fin de replay (côté `main.py`).
+
+### ⚠️ P1 — `delay_before` / `delay_after` ignorés au runtime
+**Symptôme** : on peut configurer ces champs en DB mais Léa ne les lit pas.
+**Fix partiel appliqué** : `dag_execute.py` lift `duration_ms` pour les actions `wait`/`wait_for_anchor`.
+**Vrai fix** : faire de même pour `delay_before` et `delay_after` côté executor.py (généraliser).
+
+### ⚠️ P1 — Léa client interprète `action=null + replay_paused=true` comme "fin du replay"
+**Symptôme** : main.py désactive `_replay_active` à tort quand le replay est en pause → cleanup UI + bulle invisible.
+**Fix proposé** : `executor.py:1875` retourner `True` (au lieu de `False`) quand `replay_paused` est traité.
+**Status** : non appliqué (nécessite SCP + restart Léa Windows).
+
+### ⚠️ P2 — Bug VWB frontend cache
+**Symptôme** : après modif DB, le frontend continue à envoyer l'ancienne version. Ctrl+Shift+R obligatoire.
+**Vrai fix** : invalidation cache automatique côté React quand workflow modifié serveur-side.
+
+## Leçons de méthode (autocritique honnête)
+
+1. **15 jours de dérive** : on a accumulé des modifs locales sans valider à chaque étape qu'on ne dégradait pas l'existant. CLAUDE.md disait "chirurgie itérative supervisée", on a fait l'inverse à plusieurs reprises.
+2. **Pas de tests de non-régression entre démos** : à chaque "ça marchait hier", on découvrait par hasard qu'un truc avait changé. Manque de smoke-test reproductible.
+3. **Bug VWB recapture anchor non détecté pendant 15 jours** : la cause racine n°1 des régressions silencieuses était invisible. Aurait dû être trouvée plus tôt par un audit "diff PNG anchor avant/après recapture".
+4. **Workarounds empilés** : chaque bug a généré un workaround (script cancel-replays.sh, bypass LLM static, pause humaine NoMachine, etc.) au lieu de fixer la cause. Dette technique accumulée.
+5. **Recapture en aveugle** : Dom a recapturé plusieurs anchors en pensant fixer le bug, alors que le bug était VWB côté capture (pas Dom).
+
+## État technique en sortie de session
+
+- **Branche actuelle** : `feature/qw-suite-mai` (avec toutes les modifs uncommitted de la session)
+- **Branche backup** : `backup/post-demo-2026-05-19` (commit groupé, poussé sur gitea)
+- **Référence "ça marchait"** : tag `demo-stable-2026-05-12` (commit `2eeaa806b`), branche `demo/ght-2026-05-08` (commit `56e869c46`)
+- **Services actifs** : streaming (5005), VWB backend (5002), VWB frontend (3002), dashboard (5001), worker (5099), agent-chat (5004)
+- **Bypass LLM actif** dans `replay_engine.py` : les steps 12/13/14 du workflow utilisent `static_result`/`static_text` → décision UHCD MOREL hardcodée
+- **NPM bypass auth** actif dans `proxy_host/10.conf` (sera écrasé si UI NPM touchée)
+
+## Sauvegardes
+
+| Type | Localisation | Détails |
+|------|--------------|---------|
+| Tarball | `/home/dom/ai/_archives/rpa_vision_v3_post_demo_20260519_142940.tar.gz` | 8.9 Go, sha256 vérifié |
+| Branche git | `backup/post-demo-2026-05-19` sur gitea | commit `5ea4960e6`, 627 fichiers incluant 468 anchors |
+| Backups DB | `visual_workflow_builder/backend/instance/workflows.db.bak.*` | ~12 .bak DB de la session (chaque modif majeure) |
+
+## Prochaine session — priorités proposées
+
+1. **Comparer avec `demo/ght-2026-05-08`** : identifier ce qui a vraiment régressé depuis l'état "ça marchait" (mais qui était moins mature)
+2. **Fixer le bug VWB recapture anchor** (P0) — c'est le boss final, il explique la majorité des régressions silencieuses
+3. **Fixer le bug Stop VWB ne purge pas la queue** (P0) — supprime un workaround manuel
+4. **Réintégrer le fix `executor.py:1875` (return True sur replay_paused) côté Léa** + SCP + restart Léa Windows
+5. **Smoke-test reproductible** : script qui rejoue Demo_urgence_3_db de bout en bout et compare l'état attendu à chaque step (au lieu de tester manuellement)
+
+## Pointeurs utiles
+
+- Mémoire projet : `/home/dom/.claude/projects/-home-dom-ai-rpa-vision-v3/memory/MEMORY.md`
+- CLAUDE.md projet : `/home/dom/ai/rpa_vision_v3/CLAUDE.md` (règles de méthode)
+- Reset replays : `./scripts/cancel-replays.sh`
+- Mockup AIVA-URGENCE : `docs/clients/ght_sud_95/aiva_urgence/` (port 8765, exposé via `https://urgence.labs.laurinebazin.design/aiva-urgence/`)
+- Workflow ID démo : `wf_483910cdd851_1778750587`