# 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