rpa_vision_v3/docs/plans/BACKLOG_HORIZON1_LEA_FIRST_2026-05-19.md

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

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