docs: add POC specs, handoffs, and research notes

docs/plans/BACKLOG_HORIZON1_LEA_FIRST_2026-05-19.md

@@ -0,0 +1,257 @@
+# Backlog Horizon 1 Lea-first -- 2026-05-19
+
+**Objet**
+- Transformer `Horizon 1` en backlog d'execution concret.
+- Se limiter au coeur produit `Lea-first`.
+- Ne pas reintroduire `VWB` ou la demo comme reference produit.
+
+## 1. Definition de done
+
+Horizon 1 est termine quand les conditions suivantes sont vraies :
+
+- un workflow Lea-first canonique peut etre capture puis rejoue sans passer par `VWB`
+- `pause -> intervention humaine -> resume` est fiable et comprehensible
+- les succes, echecs et corrections humaines alimentent vraiment la memoire persistante
+- on dispose d'un gate minimal reproductible avant toute session terrain
+- on dispose d'un runbook operatoire court pour lancer, observer et reprendre un replay
+
+## 2. Baseline technique au 2026-05-19
+
+### Pipeline reel retenu
+
+Le chemin nominal reste :
+
+`capture Lea -> stream serveur -> replay direct -> verification -> memory`
+
+Fichiers pivots :
+
+- `agent_v0/agent_v1/main.py`
+- `agent_v0/agent_v1/core/executor.py`
+- `agent_v0/server_v1/api_stream.py`
+- `agent_v0/server_v1/stream_processor.py`
+- `agent_v0/server_v1/resolve_engine.py`
+- `agent_v0/server_v1/replay_learner.py`
+- `agent_v0/server_v1/replay_memory.py`
+- `core/learning/target_memory_store.py`
+
+### Gate minimal deja vert
+
+Tests executes localement le 2026-05-19 :
+
+- `pytest -q tests/integration/test_replay_resume_acknowledgments.py tests/integration/test_loop_detector_replay.py tests/unit/test_target_memory_store.py`
+- `pytest -q tests/integration/test_stream_processor.py tests/smoke/test_smoke_e2e_minimal.py`
+- `pytest -q tests/integration/test_pause_for_human.py tests/unit/test_replay_critic.py`
+
+Conclusion :
+
+- les briques `resume`, `loop detector`, `target memory`, `stream processor` et le smoke critique offline sont deja exploitables comme premier garde-fou
+- `pause_for_human` et `replay_critic` peuvent rejoindre ce garde-fou immediatement
+- il reste un warning `pytest-asyncio` de configuration de boucle, non bloquant pour Horizon 1
+- `tests/unit/test_policy_grounding_recovery_learning.py` n'est pas encore un gate portable : 4 tests `RecoveryEngine` tombent localement sur `ModuleNotFoundError: pynput`
+- ce gate ne prouve pas encore le replay Windows reel de bout en bout
+
+## 3. Ordre d'attaque
+
+### Chantier H1-A -- Stabiliser le replay nominal
+
+**But**
+- faire du replay direct le chemin assume et observable
+
+**Fichiers cibles**
+- `agent_v0/server_v1/stream_processor.py`
+- `agent_v0/server_v1/api_stream.py`
+- `agent_v0/agent_v1/main.py`
+- `agent_v0/agent_v1/core/executor.py`
+
+**Taches**
+- figer un workflow Lea-first canonique de reference
+- verifier que `build_replay_from_raw_events(...)` produit des actions propres sur ce workflow
+- verifier le couplage `session_id / machine_id / replay queue` pour eviter les confusions inter-machines
+- tracer explicitement le passage `capture finalisee -> replay injecte -> action poll -> resultat recu`
+
+**Acceptation**
+- a partir d'une capture Lea, le serveur injecte une queue de replay exploitable sans bridge VWB
+- l'agent recupere les actions avec le bon `machine_id`
+- l'index courant du replay et le nombre d'actions restantes restent coherents jusqu'a completion ou pause
+
+**Gate associe**
+- `tests/integration/test_stream_processor.py`
+- `tests/smoke/test_smoke_e2e_minimal.py`
+
+### Chantier H1-B -- Fiabiliser la pause supervisee
+
+**But**
+- rendre deterministe et lisible la boucle `pause / aide humaine / reprise`
+
+**Fichiers cibles**
+- `agent_v0/server_v1/api_stream.py`
+- `agent_v0/server_v1/loop_detector.py`
+- `agent_v0/agent_v1/network/feedback_bus.py`
+- `agent_v0/agent_v1/ui/chat_window.py`
+
+**Taches**
+- formaliser la matrice des causes de `paused_need_help`
+- distinguer les pauses qui doivent reinjecter l'action de celles qui ne doivent pas la reinjecter
+- verifier l'alignement entre payload serveur, bulle Lea et endpoint `/replay/{id}/resume`
+- verifier que les acquittements de `safety_checks` restent obligatoires quand requis
+
+**Causes a couvrir explicitement**
+- `pause_for_human`
+- `target_not_found`
+- `wrong_window`
+- `no_screen_change_strict`
+- `system_dialog`
+- `loop_detected`
+
+**Acceptation**
+- chaque pause expose une raison, un message et un comportement de reprise clairs
+- `resume` ne relance pas une action qui etait une pause intentionnelle
+- `cancel` vide proprement la queue
+- aucun cas de pause ne laisse le replay dans un etat ambigu
+
+**Gate associe**
+- `tests/integration/test_replay_resume_acknowledgments.py`
+- `tests/integration/test_loop_detector_replay.py`
+- `tests/integration/test_pause_for_human.py`
+
+### Chantier H1-C -- Faire apprendre la memoire de replay
+
+**But**
+- s'assurer que la boucle d'apprentissage est branchee sur le runtime reel, pas seulement documentee
+
+**Fichiers cibles**
+- `agent_v0/server_v1/api_stream.py`
+- `agent_v0/server_v1/replay_learner.py`
+- `agent_v0/server_v1/replay_memory.py`
+- `agent_v0/server_v1/resolve_engine.py`
+- `core/learning/target_memory_store.py`
+
+**Taches**
+- verifier le contrat `actual_position` entre agent et serveur
+- verifier que `memory_record_success()` ne se declenche qu'apres succes verifie
+- verifier que `memory_record_failure()` decremente bien la fiabilite utile
+- verifier que `record_human_correction()` nourrit bien `target_memory.db`
+- tracer un cas de `memory_lookup HIT` jusqu'a la resolution suivante
+
+**Acceptation**
+- au moins un cas reel montre la sequence :
+  `target_not_found ou no_screen_change_strict -> correction humaine -> stockage -> hit memoire sur replay suivant`
+- les fichiers `data/learning/replay_results/*.jsonl` et `data/learning/events/*/resolution_events.jsonl` sont utiles et lisibles
+- `target_memory.db` contient des entrees correspondant a des cibles reelles du workflow canonique
+
+**Gate associe**
+- `tests/unit/test_target_memory_store.py`
+- `tests/unit/test_policy_grounding_recovery_learning.py`
+- `tests/unit/test_replay_critic.py`
+
+### Chantier H1-D -- Runbook et gate terrain
+
+**But**
+- disposer d'un protocole d'execution simple avant toute session reelle
+
+**Fichiers cibles**
+- `agent_v0/deploy/test_replay_diag.py`
+- `tests/smoke/test_smoke_e2e_minimal.py`
+- nouvelle doc de runbook Lea-first
+
+**Taches**
+- definir un gate local minimum avant session terrain
+- definir un workflow canonique a jouer a blanc avant toute session utilisateur
+- ecrire une checklist courte `avant capture / avant replay / pendant pause / apres correction`
+- rendre explicites les artefacts a conserver apres un incident
+
+**Acceptation**
+- on sait dire en moins de 5 minutes si la machine est "prete a rejouer"
+- on sait quoi collecter en cas d'echec sans improviser
+- on sait faire une reprise propre apres une pause supervisee
+
+**Gate associe**
+- `python agent_v0/deploy/test_replay_diag.py`
+- `pytest -q tests/smoke/test_smoke_e2e_minimal.py`
+
+## 4. Sequence immediate
+
+### Etape 1 -- Geler le gate Horizon 1
+
+- conserver les 5 fichiers de test deja verts comme premier noyau
+- ajouter maintenant `tests/integration/test_pause_for_human.py`
+- ajouter maintenant `tests/unit/test_replay_critic.py`
+- garder `tests/unit/test_policy_grounding_recovery_learning.py` en seconde couronne tant que la dependance `pynput` n'est pas geree proprement pour le contexte de test
+
+### Etape 2 -- Choisir le workflow canonique
+
+- un seul workflow Lea-first
+- court
+- peu de fenetres
+- au moins un clic, une saisie, une verification, une pause possible
+
+### Etape 3 -- Prioriser les corrections
+
+Ordre de traitement :
+
+1. ambiguite de replay `session_id / machine_id / queue`
+2. cas de pause/reprise incoherents
+3. apprentissage non persiste ou non reutilise
+4. runbook et collecte d'artefacts
+
+## 5. Integration de l'audit Claude
+
+Reference :
+
+- [AUDIT_LEA_FIRST_RUNTIME_2026-05-19.md](/home/dom/ai/rpa_vision_v3/docs/AUDIT_LEA_FIRST_RUNTIME_2026-05-19.md)
+
+Important :
+
+- dans ce repo, `agent_v0/` reste le **conteneur de chemin** du code courant
+- l'audit qui parle de `agent_v0/agent_v1` et `agent_v0/server_v1` parle donc bien du runtime actuel
+
+### Points valides
+
+- `record_human_correction()` est reellement casse
+- la capture via `mss.monitors[1]` n'a pas de garde contre des dimensions aberrantes
+- `_replay_active` est mal gere cote client pendant `replay_paused=true`
+
+### Points a corriger dans la formulation
+
+- le replay direct **existe bien** via `POST /api/v1/traces/stream/replay-session`
+- ce endpoint charge `live_events.jsonl`, appelle `build_replay_from_raw_events(...)`, puis injecte la queue de replay
+- en revanche, `finalize` n'enchaine pas ce chemin automatiquement et la surface produit reste morcelee
+- `build_workflow_replay()` est bien orphelin, mais cela ne prouve pas que le replay direct n'existe pas
+
+- le gating memoire sur `window_title` est reel
+- mais sur le flux Lea-first natif, `build_replay_from_raw_events(...)` propage deja `window_title` dans les clics enrichis
+- le risque est donc surtout : actions non enrichies, cas degradés, et workflows non Lea-first ou incompletés
+
+- `core/learning/*` non branche au runtime serveur est un constat juste
+- mais pour Horizon 1, ce n'est pas un blocage du coeur produit si on assume que `TargetMemoryStore` est la seule boucle d'apprentissage necessaire court terme
+
+### Reclassement pratique pour Horizon 1
+
+- `P0 reel` : correction humaine cassee
+- `P0 reel` : corruption possible des captures moniteur
+- `P1 reel` : pause/reprise desynchronisee cote client
+- `P1 structurant` : absence de chainage produit propre `finalize -> replay-session`
+- `P1 risque` : memoire trop dependante de `window_title`
+- `P2 assume` : branches `core/learning/*` hors chemin nominal court terme
+
+## 6. Ce que je retiens pour la suite immediate
+
+Ordre de traitement mis a jour :
+
+1. corriger `record_human_correction()` pour rouvrir l'apprentissage supervise
+2. blinder la capture moniteur contre les dimensions aberrantes
+3. corriger `_replay_active` sur `action=null + replay_paused=true`
+4. definir si `finalize` doit proposer ou lancer explicitement `replay-session`
+5. renforcer le fallback `window_title` pour le record / lookup memoire
+
+## 7. Premier ticket d'execution
+
+Le premier ticket que je lancerais sans attendre est :
+
+**"Corriger `record_human_correction()` et valider un vrai cycle correction -> target_memory.db -> hit memoire."**
+
+Pourquoi :
+
+- c'est le bug le plus net et le plus rentable de l'audit
+- il touche directement la promesse produit Lea-first
+- il fournit ensuite un cas de validation concret pour Horizon 1