docs: add POC specs, handoffs, and research notes

docs/demo/test-humain-batch1.md

@@ -0,0 +1,164 @@
+# Guide de test humain — Compétences batch 1
+
+**Date** : 2026-06-01
+**Auteur** : Qwen
+**Objectif** : tester en direct que Léa peut rejouer une compétence apprise, et que l'humain peut valider le résultat.
+
+---
+
+## Prérequis généraux
+
+| Élément | Vérification |
+|---------|-------------|
+| Dashboard web actif | `http://<ip>:3000` → page Knowledge Base visible |
+| Streaming server actif | `http://<ip>:5005` (le dashboard s'y connecte) |
+| Agent Windows connecté | La machine `DESKTOP-58D5CAC_windows` apparaît dans le dashboard |
+| Compétences visibles | 3 compétences `candidate` dans la Knowledge Base |
+
+---
+
+## Test 1 — `key_win_r_wait_explorer_exe` (Win+R → Exécuter)
+
+### Ce que Léa va faire
+Appuyer sur `Win+R` et attendre que la fenêtre **Exécuter** apparaisse.
+
+### État initial requis
+- ✅ Bureau Windows visible
+- ✅ **Aucun** dialogue Exécuter ouvert (ferme-le s'il est ouvert)
+- ✅ `explorer.exe` tourne (toujours le cas sur Windows)
+
+### Procédure
+1. Ouvre le dashboard → onglet **Knowledge Base**
+2. Trouve la ligne `key_win_r_wait_explorer_exe`
+3. Clique **Tester**
+4. Une modale s'ouvre, le replay se lance
+5. **Pause before** : la modale dit "Prépare le test supervisé..." → clique **Continuer le test**
+6. Léa envoie `Win+R` automatiquement
+7. La fenêtre Exécuter doit apparaître en ~1-2 secondes
+8. **Pause after** : la modale dit "Valide le résultat..." → 3 boutons apparaissent
+
+### Ce que tu dois voir
+- La fenêtre Exécuter s'ouvre et passe au premier plan
+- La modale affiche "Valide le résultat de la compétence..."
+
+### Comment juger
+
+| Verdict | Quand |
+|---------|-------|
+| **Valide** ✅ | La fenêtre Exécuter apparaît et est au premier plan |
+| **Invalide** ❌ | Rien ne se passe, ou une autre fenêtre s'ouvre |
+| **Incertain** ⚠️ | La fenêtre Exécuter apparaît mais n'est pas au premier plan (une autre app la cache) |
+
+### Gap connu
+> Si le dialogue Exécuter était **déjà ouvert** avant le test, le succès est un faux positif. Le YAML a un `t2_known_gap` documenté : `run_dialog_preexisting_false_positive`. **Vérifie l'absence du dialogue avant de cliquer Continuer.**
+
+---
+
+## Test 2 — `key_ctrl_s_wait_notepad_exe` (Ctrl+S → Enregistrer sous)
+
+### Ce que Léa va faire
+Appuyer sur `Ctrl+S` et attendre que le dialogue **Enregistrer sous** apparaisse.
+
+### État initial requis
+- ✅ **Bloc-notes (Notepad) ouvert** avec un document
+- ✅ Document **non enregistré** et **modifié** (le titre doit contenir un astérisque `*`, ex: `Sans titre * – Bloc-notes`)
+- ✅ Aucun dialogue "Enregistrer sous" déjà ouvert
+
+### Comment préparer
+1. Ouvre Bloc-notes (`notepad.exe`)
+2. Tape du texte au hasard
+3. **Ne sauvegarde pas** → le titre doit montrer `*` (document modifié non sauvegardé)
+
+### Procédure
+1. Dashboard → Knowledge Base → `key_ctrl_s_wait_notepad_exe`
+2. Clique **Tester**
+3. Modale : "Prépare le test supervisé..." → clique **Continuer le test**
+4. Léa envoie `Ctrl+S` automatiquement
+5. Le dialogue "Enregistrer sous" doit apparaître en ~1-2 secondes
+6. **Pause after** : clique Valide / Invalide / Incertain
+
+### Ce que tu dois voir
+- Le dialogue "Enregistrer sous" de Notepad apparaît au premier plan
+- Bloc-notes reste ouvert en arrière-plan
+
+### Comment juger
+
+| Verdict | Quand |
+|---------|-------|
+| **Valide** ✅ | Le dialogue "Enregistrer sous" apparaît |
+| **Invalide** ❌ | Rien ne se passe (document déjà enregistré = sauvegarde silencieuse), ou Notepad se ferme |
+| **Incertain** ⚠️ | Le dialogue apparaît mais Notepad n'est pas en arrière-plan |
+
+### Gap connu
+> `save_as_requires_unsaved_notepad_document` : si le document a déjà un chemin de sauvegarde, `Ctrl+S` sauvegarde silencieusement sans ouvrir le dialogue. **Le document doit être non enregistré.**
+
+---
+
+## Test 3 — `key_alt_f4_wait_windowsterminal_exe` (Alt+F4 → fermer fenêtre)
+
+### Ce que Léa va faire
+Appuyer sur `Alt+F4` pour fermer la fenêtre Bloc-notes courante.
+
+### État initial requis
+- ✅ **Bloc-notes ouvert** avec un fichier (peut être enregistré ou non)
+- ✅ Bloc-notes au **premier plan**
+- ⚠️ Si le document est modifié et non sauvegardé, un **dialogue de confirmation** peut apparaître ("Voulez-vous enregistrer ?")
+
+### Procédure
+1. Ouvre Bloc-notes avec un fichier
+2. Mets Bloc-notes au premier plan
+3. Dashboard → Knowledge Base → `key_alt_f4_wait_windowsterminal_exe`
+4. Clique **Tester**
+5. Modale : "Prépare le test supervisé..." → clique **Continuer le test**
+6. Léa envoie `Alt+F4` automatiquement
+7. Bloc-notes doit se fermer (ou afficher le dialogue de confirmation)
+8. **Pause after** : clique Valide / Invalide / Incertain
+
+### Ce que tu dois voir
+- Bloc-notes se ferme
+- La fenêtre derrière (ex: explorateur, bureau, terminal) passe au premier plan
+
+### Comment juger
+
+| Verdict | Quand |
+|---------|-------|
+| **Valide** ✅ | Bloc-notes se ferme, une autre fenêtre prend le focus |
+| **Invalide** ❌ | Bloc-notes ne se ferme pas, ou une erreur système apparaît |
+| **Incertain** ⚠️ | Le dialogue "Enregistrer les modifications ?" apparaît — la fermeture n'est pas complète |
+
+### Gap connu — ⚠️ IMPORTANT
+> `alt_f4_confirmation_dialog_not_covered` : le `success_marker` actuel attend `C:\Windows\system32\cmd.exe` / `WindowsTerminal.exe` après fermeture. C'est un artefact de la session d'observation (c'était le Terminal qui était derrière). **Ce n'est pas le bon marqueur de succès général.** Si une autre fenêtre que le Terminal est derrière, le wait_state peut échouer même si la fermeture a réussi.
+
+**Conséquence** : ce test est le moins fiable des 3. Si Alt+F4 ferme bien Bloc-notes mais que le wait_state timeout (parce que la fenêtre derrière n'est pas Terminal), clique **Incertain** — ce n'est pas un bug de Léa, c'est le marqueur de succès qui est trop spécifique.
+
+---
+
+## Résumé des verdicts
+
+Après chaque test, le dashboard enregistre le verdict dans `data/competence_verdicts/verdicts.jsonl`. Tu ne verras pas de changement immédiat dans les fichiers YAML — la promotion en `stable` nécessite 3 succès indépendants.
+
+| Compétence | Verdict | Observations |
+|-----------|---------|-------------|
+| `key_win_r_wait_explorer_exe` | | |
+| `key_ctrl_s_wait_notepad_exe` | | |
+| `key_alt_f4_wait_windowsterminal_exe` | | |
+
+---
+
+## Questions fréquentes
+
+**Q : Et si la modale reste bloquée sur "Lancement du replay..." ?**
+R : Vérifie que l'agent Windows est connecté et que le streaming server (`:5005`) tourne. Ferme la modale et recommence.
+
+**Q : Et si le replay envoie les touches mais que rien ne se passe ?**
+R : Vérifie que la fenêtre cible est au premier plan. Si tu testes Ctrl+S mais que Notepad n'est pas actif, le Ctrl+S ira à une autre application.
+
+**Q : Puis-je tester plusieurs fois la même compétence ?**
+R : Oui. Chaque test génère un nouveau verdict. Pour la promotion `candidate → stable`, il faut 3 succès avec 3 contextes distincts.
+
+**Q : Que se passe-t-il si je clique "Invalide" ?**
+R : Le verdict est enregistré comme `invalid`. Le replay se termine normalement. Le YAML n'est pas modifié. Si 3 invalid consécutifs surviennent, un flag `regression_suspected` sera activé.
+
+---
+
+*Auteur : Qwen*

docs/demo/test-humain-e2e-poc.md

@@ -0,0 +1,554 @@
+# Protocole de test humain E2E — POC Aiva-vision
+
+**Date** : 2026-06-01
+**Version** : 1.0
+**Objet** : valider le POC en conditions réelles — apprentissage → restitution → correction → persistance → replay supervisé → verdict
+**Durée estimée** : 45-60 minutes
+
+---
+
+## 1. Checklist pré-test
+
+### 1.1 Services à vérifier
+
+| Service | Port | Comment vérifier | GO/NO-GO |
+|---------|------|------------------|----------|
+| Ollama | 11434 | `curl http://localhost:11434/api/tags` — doit retourner la liste des modèles | ☐ |
+| Streaming server | 5005 | `curl http://localhost:5005/health` ou `./svc.sh status` | ☐ |
+| Web Dashboard | 5001 | `curl http://localhost:5001/health` ou ouvrir `http://localhost:5001` | ☐ |
+| Agent Chat | 5004 | `curl http://localhost:5004/health` ou ouvrir `http://localhost:5004` | ☐ |
+| VWB Backend | 5002 | `./svc.sh status` (optionnel si on ne teste pas via VWB) | ☐ |
+| VWB Frontend | 3002 | `curl http://localhost:3002` (optionnel) | ☐ |
+
+Commande rapide pour tout vérifier d'un coup :
+```bash
+./svc.sh status
+```
+
+### 1.2 Modèles Ollama requis
+
+```bash
+ollama list
+```
+
+Vérifier la présence de :
+- `qwen2.5vl:7b` (ou `qwen2.5vl:7b-rpa`) — grounding visuel
+- `qwen2.5:7b` — raisonnement texte
+- `qwen2.5:0.5b` — intent recognition léger (fallback)
+
+**Si un modèle manque** : `ollama pull <nom>` avant de continuer.
+
+### 1.3 Compétences existantes dans le catalogue
+
+Ouvrir le dashboard → onglet **Knowledge Base**. Vérifier la présence de :
+
+| Compétence | État attendu |
+|------------|-------------|
+| `key_win_r_wait_explorer_exe` | `candidate` |
+| `key_ctrl_s_wait_notepad_exe` | `candidate` |
+| `key_alt_f4_wait_windowsterminal_exe` | `candidate` |
+
+**Si le catalogue est vide** : les fichiers YAML doivent exister dans `data/competences/candidate/`. Vérifier :
+```bash
+ls -la data/competences/candidate/
+```
+Si les fichiers existent mais n'apparaissent pas dans le dashboard, redémarrer le streaming server (`./svc.sh restart streaming`).
+
+### 1.4 Agent Windows connecté
+
+- Dans le dashboard, vérifier que la machine cible apparaît (ex: `DESKTOP-XXXXX_windows`).
+- Si l'agent n'est pas connecté : le lancer depuis le poste Windows (`Lea_v*.zip` → `lea_agent.exe`).
+- **Machine cible** : noter le `machine_id` exact (affiché dans le dashboard ou dans `data/agents/`).
+
+### 1.5 État initial de la machine Windows
+
+Avant toute manipulation :
+
+- [ ] **Fermer tous les dialogues parasites** : boîtes de dialogue "Enregistrer", "Exécuter", confirmations, pop-up Windows Update
+- [ ] **Fermer les applications non nécessaires** : tout garder minimal (bureau + applications de test uniquement)
+- [ ] **Vérifier que le bureau est visible** : pas d'application plein écran
+- [ ] **Couper les notifications Windows** : mode "Ne pas déranger" activé (Win+A → activer)
+- [ ] **Noter la résolution écran** : `Win+I → Système → Écran` (utile si un problème de positionnement survient)
+
+### 1.6 Dossier de collecte des preuves
+
+Créer un dossier de travail pour cette session de test :
+```bash
+mkdir -p /home/dom/ai/rpa_vision_v3/docs/demo/e2e-poc-$(date +%Y%m%d)
+```
+
+Ce dossier recevra les screenshots, logs, et verdicts collectés pendant le test.
+
+---
+
+## 2. Protocole pas-à-pas
+
+### Phase 1 — Démarrer Léa / agent Windows
+
+**Ce que l'opérateur fait** :
+1. Vérifier que l'agent Windows est connecté (dashboard → page principale)
+2. Noter le `machine_id` affiché
+3. Ouvrir l'agent chat (`http://localhost:5004`) dans un navigateur
+
+**Ce que Léa fait** : Rien (état IDLE)
+
+**Ce qu'on doit voir** :
+- Dashboard : machine connectée, statut "online"
+- Agent chat : interface de conversation vide, bouton "Apprendre" visible
+
+**Critère GO/NO-GO** :
+- GO : agent chat accessible, machine connectée
+- NO-GO : relancer l'agent Windows, vérifier le réseau, vérifier que le streaming server tourne
+
+**Preuve à collecter** :
+- Screenshot du dashboard montrant la machine connectée
+- Copier le `machine_id` dans un fichier `preuves/machine_id.txt`
+
+---
+
+### Phase 2 — Déclencher l'apprentissage depuis agent-chat
+
+**Ce que l'opérateur fait** :
+1. Dans l'agent chat, taper : `lea apprends-moi` ou cliquer le bouton "Apprendre" si disponible
+2. Observer la réponse de Léa
+
+**Ce que Léa fait** :
+- Transition IDLE → LISTENING → WAITING_USER_STOP
+- Répond : *"Je te regarde. Fais ce que tu veux m'apprendre, et dis-moi « stop » ou « j'ai fini » quand c'est terminé."*
+- Appelle `shadow_start` côté streaming server
+
+**Ce qu'on doit voir** :
+- Message de Léa confirmant qu'elle observe
+- Side shadow actif côté streaming server (vérifiable via `curl http://localhost:5005/api/v1/shadow/sessions` si endpoint existe)
+
+**Critère GO/NO-GO** :
+- GO : Léa a répondu avec le message d'observation
+- NO-GO : si `shadow_start` échoue → vérifier streaming server, token API (`RPA_API_TOKEN`), relancer
+
+**Preuve à collecter** :
+- Screenshot de la conversation agent-chat
+- Copier le `session_id` (affiché dans la réponse ou dans les logs `agent_chat/state/`)
+
+---
+
+### Phase 3 — Observer une tâche courte
+
+**Tâche cible** : `Win+R` → ouverture de la boîte "Exécuter"
+
+**Ce que l'opérateur fait** (sur le poste Windows) :
+1. **Basculer sur la session Windows** (via RDP ou directement)
+2. Appuyer sur `Win+R`
+3. Vérifier que la boîte "Exécuter" s'ouvre
+4. **Ne pas fermer** la boîte "Exécuter" (elle servira de preuve visuelle)
+5. Revenir à l'agent chat
+
+**Ce que Léa fait** :
+- Capture les événements clavier (`key_press` pour `win` + `r`)
+- Capture les screenshots avant/après
+- Enregistre la session brute
+
+**Ce qu'on doit voir** :
+- La boîte "Exécuter" apparaît à l'écran Windows
+- Dans les logs du streaming server, des événements `key_press` et des screenshots sont reçus
+
+**Critère GO/NO-GO** :
+- GO : la boîte "Exécuter" est visible à l'écran
+- NO-GO : si `Win+R` ne fonctionne pas → vérifier que le clavier Windows n'est pas bloqué, que RDP ne capture pas les touches
+
+**Preuve à collecter** :
+- Screenshot de la boîte "Exécuter" ouverte (depuis le poste Windows)
+- Noter l'heure exacte de l'action
+
+---
+
+### Phase 4 — Arrêter l'observation
+
+**Ce que l'opérateur fait** :
+1. Dans l'agent chat, taper : `stop` ou `j'ai fini`
+
+**Ce que Léa fait** :
+- Reconnaît l'intent `USER_STOP_OBSERVE` (regex, confiance > 0.9)
+- Transition WAITING_USER_STOP → ANALYZING → PRESENTING
+- Appelle `shadow_stop` + `shadow_understanding` côté streaming server
+- Formate la restitution Option C
+
+**Ce qu'on doit voir** :
+- Léa répond avec un résumé de ce qu'elle a compris, par exemple :
+  ```
+  Voilà ce que j'ai compris :
+
+  1. Touche → raccourci utilisé : « win + r »
+  2. Fenêtre « Exécuter » → ouverte
+
+  C'est bien ça ou je me suis trompée quelque part ?
+  ```
+
+**Critère GO/NO-GO** :
+- GO : Léa a restitué au moins 1 étape correcte
+- NO-GO : si Léa dit "aucune étape comprise" → vérifier que les screenshots ont bien été capturés, que le shadow était actif
+
+**Preuve à collecter** :
+- Screenshot de la restitution Léa dans l'agent chat
+- Copier le contenu JSON de `understanding` depuis `curl http://localhost:5005/api/v1/shadow/<session_id>/understanding`
+
+---
+
+### Phase 5 — Restitution et correction (Option C — formateur)
+
+**Ce que l'opérateur fait** :
+1. **Lire attentivement** la restitution de Léa
+2. Si c'est correct : taper `oui` ou `c'est bon` ou `parfait`
+3. Si c'est incorrect : taper `corrige l'étape 1 : [description correcte]`
+
+**Ce que Léa fait** :
+- Si validation : transition ITERATING_FEEDBACK → NAMING
+- Si correction : envoie le feedback au streaming server (`shadow_feedback`), reçoit la nouvelle compréhension, reformule
+- Compte les corrections par étape (max 3 → sortie d'urgence)
+
+**Ce qu'on doit voir** :
+- Si corrigée : Léa reformule avec la correction appliquée
+- Si validée : Léa demande le nom de la compétence
+
+**Critère GO/NO-GO** :
+- GO : Léa a soit validé soit corrigé avec reformulation
+- NO-GO : si Léa ne comprend pas la correction → vérifier l'intent parser (logs), le regex, le fallback Ollama
+
+**Preuve à collecter** :
+- Screenshot de l'échange de correction (si applicable)
+- Noter le nombre de corrections apportées
+
+---
+
+### Phase 6 — Nommer la compétence et marquer les paramètres
+
+**Ce que l'opérateur fait** :
+1. Donner un nom : `ouverture executer` ou `lancer executer`
+2. Si Léa demande si une valeur est un paramètre : répondre "toujours" ou "c'est l'exemple du jour"
+3. Pour `Win+R`, il n'y a pas de valeur saisie → aucun paramètre à marquer
+
+**Ce que Léa fait** :
+- Enregistre le nom de la compétence
+- Cherche les steps avec des valeurs saisies → demande si ce sont des paramètres
+- Transition NAMING → PERSISTING quand tout est marqué
+
+**Ce qu'on doit voir** :
+- Léa confirme : *"C'est enregistré sous « ouverture executer » (slug `ouverture_executer`). Paramètres : aucun."*
+
+**Critère GO/NO-GO** :
+- GO : Léa a confirmé la persistance
+- NO-GO : si `shadow_build` ou `competence_persist` échoue → vérifier logs streaming server, endpoint `/api/v1/lea/competences/candidate/persist`
+
+**Preuve à collecter** :
+- Screenshot du message de confirmation
+- Vérifier que le YAML a été créé : `ls -la data/competences/candidate/`
+- Copier le contenu du YAML dans `preuves/competence_<slug>.yaml`
+
+---
+
+### Phase 7 — Tester via le dashboard (replay supervisé)
+
+**Ce que l'opérateur fait** :
+1. Ouvrir le dashboard → onglet **Knowledge Base**
+2. Trouver la compétence fraîchement créée
+3. Cliquer **Tester**
+4. Une modale s'ouvre : "Prépare le test supervisé..."
+5. **Avant de cliquer "Continuer le test"** :
+   - Fermer la boîte "Exécuter" si elle est encore ouverte (étape critique — voir section 5 sur les faux succès)
+   - Vérifier que le bureau Windows est visible, aucune application parasite
+6. Cliquer **Continuer le test**
+
+**Ce que Léa fait** :
+- Envoie `Win+R` automatiquement sur le poste Windows via l'agent
+- Attend que la boîte "Exécuter" apparaisse (wait_state)
+- Se met en pause après l'action
+
+**Ce qu'on doit voir** :
+- La boîte "Exécuter" s'ouvre sur le poste Windows (~1-2 secondes après le clic "Continuer")
+- La modale affiche "Valide le résultat de la compétence..." avec 3 boutons : **Valide**, **Invalide**, **Incertain**
+
+**Critère GO/NO-GO** :
+- GO : la boîte "Exécuter" apparaît et la modale de verdict est affichée
+- NO-GO : si rien ne se passe → vérifier que l'agent Windows est connecté, que le replay a bien été lancé (logs streaming server)
+
+**Preuve à collecter** :
+- Screenshot de la boîte "Exécuter" ouverte (depuis Windows)
+- Screenshot de la modale de verdict dans le dashboard
+
+---
+
+### Phase 8 — Enregistrer le verdict
+
+**Ce que l'opérateur fait** :
+1. Évaluer le résultat selon les critères :
+   - **Valide** ✅ : la boîte "Exécuter" apparaît, au premier plan, correcte
+   - **Invalide** ❌ : rien ne se passe, ou une autre fenêtre s'ouvre
+   - **Incertain** ⚠️ : la boîte apparaît mais n'est pas au premier plan
+2. Cliquer le bouton correspondant
+3. La modale se ferme, le dashboard se rafraîchit
+
+**Ce que Léa fait** :
+- Persiste le verdict dans `data/competence_verdicts/verdicts.jsonl`
+- Le replay reprend puis se termine
+
+**Ce qu'on doit voir** :
+- Le dashboard revient à la liste Knowledge Base
+- Un nouveau verdict est enregistré (vérifiable dans le fichier JSONL)
+
+**Critère GO/NO-GO** :
+- GO : le verdict est enregistré, le fichier JSONL contient une nouvelle entrée
+- NO-GO : si le verdict n'est pas persisté → vérifier logs dashboard, endpoint `/api/v1/lea/competences/<id>/verdict`
+
+**Preuve à collecter** :
+- Copier la dernière ligne du fichier `data/competence_verdicts/verdicts.jsonl` dans `preuves/verdict.jsonl`
+- Screenshot du dashboard après verdict
+
+---
+
+### Phase 9 — Nettoyer et recommencer (itération)
+
+Pour un test robuste, **répéter les phases 3-8 au moins 3 fois** avec des contextes différents :
+
+| Itération | Contexte | Tâche |
+|-----------|----------|-------|
+| 1 | Bureau propre | `Win+R` → Exécuter |
+| 2 | Avec Notepad ouvert + texte non sauvegardé | `Ctrl+S` → Enregistrer sous |
+| 3 | Avec Notepad ouvert au premier plan | `Alt+F4` → Fermer |
+
+**Ou** répéter 3 fois la même tâche avec des contextes légèrement différents (fenêtres ouvertes différentes, résolution modifiée, etc.) pour valider la robustesse.
+
+---
+
+## 3. Critères GO/NO-GO globaux
+
+### 3.1 Qu'est-ce qui valide le POC ?
+
+| Critère | Seuil |
+|---------|-------|
+| **Apprentissage par observation** | ✅ Léa doit restituer correctement au moins **1 tâche sur 3** tentées |
+| **Restitution compréhensible** | ✅ Le texte Option C doit être lisible par un humain non-technique (phrases françaises, pas JSON) |
+| **Correction acceptée** | ✅ Léa doit accepter et appliquer au moins **1 correction** |
+| **Persistance** | ✅ Le YAML doit être créé dans `data/competences/candidate/` |
+| **Replay supervisé** | ✅ Au moins **2 replays réussis sur 3** (la tâche est rejouée automatiquement) |
+| **Verdict humain** | ✅ Les verdicts doivent être persistés dans le JSONL |
+
+**Le POC est validé si** : au moins **2 des 3 compétences** du batch 1 passent le cycle complet (apprentissage → restitution → persistance → replay → verdict) avec un verdict **Valide**.
+
+### 3.2 Échecs acceptables
+
+| Échec | Acceptable ? | Condition |
+|-------|-------------|-----------|
+| `Alt+F4` → verdict Incertain | ✅ Oui | Le gap `alt_f4_confirmation_dialog_not_covered` est documenté |
+| Ollama fallback timeout | ✅ Oui | Si les regex passent quand même (confiance > 0.9) |
+| 1 correction sur 3 nécessaires | ✅ Oui | C'est dans le design (max 3 corrections/step) |
+| Wait_state timeout sur Alt+F4 | ✅ Oui | Le success_marker est trop spécifique (artefact de session) |
+
+### 3.3 Échecs bloquants
+
+| Échec | Bloquant ? | Action |
+|-------|-----------|--------|
+| `shadow_start` échoue systématiquement | 🔴 BLOQUANT | L'agent Windows ne communique pas avec le streaming server |
+| Aucune restitution (understanding vide) | 🔴 BLOQUANT | Le pipeline shadow ne reconstruit pas les étapes |
+| `competence_persist` échoue | 🔴 BLOQUANT | La persistance ne fonctionne pas |
+| Replay ne déclenche aucune action | 🔴 BLOQUANT | L'agent Windows ne reçoit pas les ordres |
+| Verdict non persisté | 🔴 BLOQUANT | Le contrat de verdict n'est pas implémenté |
+
+---
+
+## 4. Preuves à collecter
+
+### 4.1 Fichiers à vérifier après le test
+
+| Fichier | Contenu | Comment vérifier |
+|---------|---------|------------------|
+| `data/competences/candidate/*.yaml` | Compétences persistées | `ls -la` + `cat` pour vérifier le contenu |
+| `data/competence_verdicts/verdicts.jsonl` | Verdicts humains | `tail -n 5` pour voir les derniers verdicts |
+| `agent_chat/state/learn_*.json` | États des sessions d'apprentissage | `ls -la agent_chat/state/` |
+| `data/raw_sessions/<session_id>/` | Sessions brutes (screenshots + événements) | Vérifier la présence de screenshots |
+| Logs streaming server | `journalctl -u rpa-streaming` ou stdout du process | Chercher les erreurs HTTP 5xx |
+| Logs agent chat | stdout du process ou `logs/agent_chat.log` | Vérifier les transitions d'état |
+| Logs dashboard | stdout du process ou `logs/dashboard.log` | Vérifier les appels replay/verdict |
+
+### 4.2 Comment documenter un succès
+
+Créer un fichier `preuves/succes_<competence_slug>.md` avec :
+
+```markdown
+# Succès — <nom de la compétence>
+
+**Date** : 2026-06-01
+**Session ID** : learn_xxx
+**Machine** : DESKTOP-XXXXX_windows
+
+## Preuves
+- Screenshot restitution : `preuves/screenshot_restitution_<slug>.png`
+- Screenshot replay : `preuves/screenshot_replay_<slug>.png`
+- YAML : `data/competences/candidate/<slug>.yaml`
+- Verdict : dernière ligne de `data/competence_verdicts/verdicts.jsonl`
+
+## Observations
+- Nombre de corrections : X
+- Temps d'apprentissage : ~X minutes
+- Temps de replay : ~X secondes
+```
+
+### 4.3 Comment documenter un échec
+
+Créer un fichier `preuces/echec_<competence_slug>.md` avec :
+
+```markdown
+# Échec — <nom de la compétence>
+
+**Date** : 2026-06-01
+**Session ID** : learn_xxx
+**Phase d'échec** : apprentissage / restitution / persistance / replay / verdict
+
+## Symptôme
+<description de ce qui s'est passé>
+
+## Logs pertinents
+<extraits de logs>
+
+## Cause probable
+<hypothèse>
+
+## Reproduire
+<étapes pour reproduire>
+```
+
+---
+
+## 5. Risques de faux succès
+
+### 5.1 Comment distinguer un vrai succès d'un faux positif
+
+| Risque | Comment le détecter | Mitigation |
+|--------|-------------------|------------|
+| **Dialogue déjà ouvert** avant le replay | Vérifier visuellement **avant** de cliquer "Continuer le test" | Fermer tous les dialogues parasites (checklist phase 1.5) |
+| **machine_id spoofé** ou wrong target | Vérifier que le `machine_id` dans le verdict correspond à la machine de test | Noter le `machine_id` en phase 1, le comparer dans le verdict JSONL |
+| **Léa envoie les touches mais une autre app les reçoit** | Vérifier que la fenêtre cible est **au premier plan** avant le replay | Mettre la fenêtre cible au premier plan avant de cliquer "Continuer" |
+| **Wait_state passe par chance** (la fenêtre était déjà là) | Le wait_state doit détecter un **changement d'état**, pas un état statique | Vérifier que le wait_state est bien un "appear" et pas un "already present" |
+| **Verdict enregistré mais replay non exécuté** | Vérifier que `step_results[]` dans le verdict contient des steps avec `status: success` | Lire le JSONL et vérifier le contenu de `step_results` |
+
+### 5.2 Pièges spécifiques à éviter
+
+1. **RDP et les touches Windows** : en session RDP, `Win+R` peut être capturé par la machine locale au lieu de la machine distante.
+   - **Solution** : dans le client RDP, options → Clavier local → "Appliquer les combinaisons de touches Windows : Sur le serveur distant"
+
+2. **Notifications Windows** : une notification pop-up peut voler le focus pendant le replay.
+   - **Solution** : activer le mode "Ne pas distrub" avant le test
+
+3. **Windows Update** : un redémarrage intempestif pendant le test.
+   - **Solution** : suspendre Windows Update temporairement
+
+4. **Agent Windows déconnecté** : le replay est envoyé mais l'agent ne le reçoit pas.
+   - **Solution** : vérifier la connexion avant chaque replay (dashboard → statut machine)
+
+5. **Session shadow non fermée** : si `shadow_stop` n'a pas été appelé correctement, la session reste ouverte et peut interférer.
+   - **Solution** : vérifier `agent_chat/state/` — aucune session ne doit être dans un état non-terminal avant de recommencer
+
+---
+
+## 6. Bonus — Learning pack portable
+
+### 6.1 Structurer les artefacts POC
+
+Le risque : se retrouver avec des milliers de fichiers éparpillés entre `data/raw_sessions/`, `data/competences/`, `data/competence_verdicts/`, `agent_chat/state/`, et les screenshots.
+
+**Structure recommandée** pour un POC exportable :
+
+```
+learning-poc-<date>/
+├── manifest.json              # Métadonnées : date, machine, opérateur, version du code
+├── competences/
+│   ├── <slug_1>.yaml          # Compétences persistées
+│   └── <slug_2>.yaml
+├── verdicts/
+│   └── verdicts.jsonl         # Verdicts humains (copie du JSONL)
+├── sessions/
+│   ├── <session_id>/
+│   │   ├── events.jsonl       # Événements bruts
+│   │   └── screenshots/       # Screenshots (compressés)
+│   └── <session_id>/
+├── audit/
+│   ├── promotions.jsonl       # Audit de promotion (si applicable)
+│   └── test-log.md            # Journal du test humain
+└── proofs/
+    ├── screenshot_restitution_*.png
+    ├── screenshot_replay_*.png
+    └── succes_*.md / echec_*.md
+```
+
+### 6.2 Script d'export rapide
+
+```bash
+#!/bin/bash
+# export_learning_poc.sh — créer un zip portable du POC
+DATE=$(date +%Y%m%d)
+DEST="learning-poc-${DATE}"
+
+mkdir -p "$DEST"/{competences,verdicts,sessions,audit,proofs}
+
+# Compétences candidate
+cp data/competences/candidate/*.yaml "$DEST/competences/" 2>/dev/null
+
+# Verdicts
+cp data/competence_verdicts/verdicts.jsonl "$DEST/verdicts/" 2>/dev/null
+
+# Audit
+cp data/competences/promotions.jsonl "$DEST/audit/" 2>/dev/null
+
+# Sessions récentes (dernières 24h)
+find data/raw_sessions/ -maxdepth 1 -mtime -1 -type d -exec cp -r {} "$DEST/sessions/" \; 2>/dev/null
+
+# States agent chat
+cp agent_chat/state/learn_*.json "$DEST/audit/" 2>/dev/null
+
+# Manifest
+cat > "$DEST/manifest.json" <<EOF
+{
+  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "machine": "$(hostname)",
+  "operator": "${OPERATOR:-dom}",
+  "code_version": "$(git rev-parse --short HEAD 2>/dev/null || echo 'unknown')",
+  "competences_count": $(ls "$DEST/competences/"*.yaml 2>/dev/null | wc -l),
+  "verdicts_count": $(wc -l < "$DEST/verdicts/verdicts.jsonl" 2>/dev/null || echo 0)
+}
+EOF
+
+# Zip
+zip -r "${DEST}.zip" "$DEST/"
+echo "Pack créé : ${DEST}.zip"
+```
+
+### 6.3 Export vers DGX Spark
+
+Le learning pack ainsi structuré est **autonome** :
+
+1. Transférer le zip vers le DGX Spark : `scp learning-poc-*.zip user@dgx-spark:/path/to/imports/`
+2. Importer côté DGX : le script d'import lit le `manifest.json`, place les YAML dans `data/competences/candidate/`, les verdicts dans `data/competence_verdicts/`, et les sessions dans `data/raw_sessions/`
+3. Vérifier l'import : `ls data/competences/candidate/` + `tail data/competence_verdicts/verdicts.jsonl`
+
+**Invariant** : le learning pack ne contient **pas** de modèles Ollama, pas de dépendances Python, pas de fichiers système. Uniquement des artefacts métier (YAML, JSONL, screenshots, events).
+
+---
+
+## Annexe — Résumé visuel du flux
+
+```
+[IDLE] ──(apprends-moi)──> [LISTENING] ──> [WAITING_USER_STOP]
+                                                      │
+                                               (stop / j'ai fini)
+                                                      │
+                                                      v
+[DONE] <── [PERSISTING] <── [NAMING] <── [ITERATING_FEEDBACK] <── [ANALYZING]
+  │                                                      │
+  │                                          (oui / corrige étape N)
+  │                                                      │
+  +──> YAML + verdict JSONL <── Dashboard: Tester ──> Replay supervisé
+                                                        │
+                                                    Valide/Invalide/Incertain
+```
+
+---
+
+*Document créé le 2026-06-01. À suivre pas-à-pas pendant la démo.*