docs: add POC specs, handoffs, and research notes

docs/architecture/CARTOGRAPHIE_MICRO_APPRENTISSAGE_LEA_2026-05-27.md

@@ -0,0 +1,99 @@
+# Cartographie micro-apprentissage Lea - 2026-05-27
+
+## But
+
+Passer du replay metier fragile a une boucle courte ou Lea observe des gestes simples, les interprete, verifie leur effet, puis memorise ce qui marche.
+
+On reutilise l'existant. On ne fabrique pas une boite a clic.
+
+Premiere competence retenue: `ouvrir le menu Demarrer`. C'est plus atomique que "ouvrir Chrome" ou "ouvrir Word" et sert de base aux competences composees suivantes.
+
+## Briques a reutiliser maintenant
+
+| Besoin | Brique existante | Chemin |
+|---|---|---|
+| Demarrer une demonstration humaine | Bouton `Apprenez-moi` + `SharedState.start_recording()` | `agent_v0/agent_v1/ui/chat_window.py`, `agent_v0/agent_v1/ui/shared_state.py` |
+| Capturer clics/frappes/ecran | `AgentV1.start_session()` + `TraceStreamer` | `agent_v0/agent_v1/main.py`, `agent_v0/agent_v1/network/streamer.py` |
+| Recevoir les evenements | endpoint `/event` + `StreamProcessor.process_event()` | `agent_v0/server_v1/api_stream.py`, `agent_v0/server_v1/stream_processor.py` |
+| Construire une trace exploitable | `StreamProcessor.finalize_session()` + `GraphBuilder` | `agent_v0/server_v1/stream_processor.py`, `core/graph/graph_builder.py` |
+| Apprendre des corrections humaines | `ReplayLearner.record_human_correction()` | `agent_v0/server_v1/replay_learner.py` |
+| Memoriser les cibles fiables | `memory_record_success()` / `memory_lookup()` | `agent_v0/server_v1/replay_memory.py`, `core/learning/target_memory_store.py` |
+| Verifier qu'une action a eu un effet | `ReplayVerifier.verify_action()` | `agent_v0/server_v1/replay_verifier.py` |
+| Parler clairement a l'humain | contrat 4 champs | `agent_v0/agent_v1/ui/message_contract.py` |
+| Verifier le socle technique | preflight read-only | `tools/lea_micro_preflight.py` |
+
+## Briques a eviter pour la V1 micro-learning
+
+- Replay VWB/DAG comme moteur principal.
+- Coordonnees brutes comme verite finale.
+- Clipboard global Linux/Windows/NoMachine comme transport de donnees.
+- Scenarios metier longs.
+- Corrections injectees a la main dans un workflow pour faire passer une demo.
+
+## Flux minimal
+
+1. Observation
+   Dom lance `Apprenez-moi`, nomme une micro-tache, puis montre 1 geste court.
+
+2. Interpretation
+   Le serveur conserve les evenements, les screenshots, les titres de fenetre, les indices UIA/OCR/SoM disponibles.
+
+3. Generalisation prudente
+   Lea derive une competence courte: intention, contexte d'ecran attendu, signaux visuels, postcondition observable.
+
+4. Tentative encadree
+   Lea ne tente en autonomie que si la cible est suffisamment decrite et verifiable.
+
+5. Verification
+   Pixel diff seul ne suffit pas. Il faut verifier un effet observable: fenetre ouverte, champ rempli, titre change, application fermee, texte present.
+
+6. Memoire
+   Les succes repetes alimentent `TargetMemoryStore`. Les echecs et corrections humaines alimentent `ReplayLearner`.
+
+7. Demande humaine
+   Si Lea ne sait pas, elle doit afficher:
+
+   ```text
+   J'essaie de : <INTENTION>
+   J'attendais : <ATTENDU>
+   Je vois     : <VU>
+   Peux-tu     : <DEMANDE>
+   ```
+
+## Etats d'une competence
+
+| Etat | Sens |
+|---|---|
+| OBSERVATION | Lea a seulement vu le geste humain. |
+| COACHING | Lea peut proposer une tentative, mais demande confirmation/correction. |
+| AUTO_CANDIDATE | Lea a reussi plusieurs fois avec verification. |
+| AUTO | Lea peut executer seule avec garde-fous. |
+
+## Fichiers a lire/modifier ensuite
+
+Priorite 1:
+
+- `agent_v0/agent_v1/ui/chat_window.py` : texte de lancement/fin d'apprentissage.
+- `agent_v0/agent_v1/ui/shared_state.py` : metadata de session micro-learning.
+- `agent_v0/agent_v1/main.py` : nommage session + mode capture.
+- `agent_v0/server_v1/stream_processor.py` : sortie de finalisation orientee competence courte.
+- `agent_v0/server_v1/replay_learner.py` : persistance des corrections et resultats.
+
+Priorite 2:
+
+- `agent_v0/server_v1/replay_memory.py` : fiabilite et collisions sur boutons generiques.
+- `agent_v0/server_v1/replay_verifier.py` : verifier des postconditions simples.
+- `agent_v0/agent_v1/core/executor.py` : mode correction humaine et messages visibles.
+
+## Risques prioritaires
+
+1. Confondre trace de demonstration et competence generalisable.
+2. Valider une action seulement parce que les pixels bougent.
+3. Apprendre une coordonnee dependante DPI/ecran.
+4. Produire un message conforme au contrat mais pauvre en contexte.
+5. Recharger le VLM au mauvais moment et ajouter une latence cold start.
+6. Melanger session de capture et replay actif.
+
+## Regle de travail
+
+Chaque micro-tache doit tenir en moins de deux minutes, avec une postcondition observable. Si on ne peut pas formuler la postcondition, on ne l'apprend pas encore.