docs: add POC specs, handoffs, and research notes

docs/POC/AUDIT_CHAINE_APPRENTISSAGE_2026-06-01.md

@@ -0,0 +1,268 @@
+# Audit chaîne apprentissage modèle IA — 2026-06-01
+
+> **DRAFT audit factuel — lecture seule, pas encore appliqué.**
+>
+> Date : 2026-06-01 22:00 Europe/Paris
+> Auteurs : agent Explore Claude (audit primaire) + Claude (synthèse + matérialisation fichier)
+> Statut : DRAFT — relecture Dom/Codex/Qwen attendue
+> Origine demande : Dom 2026-06-01 ~21:40 — « tu pourrais lancer un agent explorateur pour nous remonter la chaîne exact d'apprentissage du modèle d'IA sur lequel j'ai travaillé. Le code existe, mais je pense qu'il a été débranché... »
+
+## TL;DR — Constat fort
+
+**L'intuition de Dom était JUSTE.** La chaîne d'apprentissage est **partiellement débranchée** depuis plusieurs semaines/mois. Les composants nécessaires pour implémenter ce que Dom a explicité dans ses 5 messages du 2026-06-01 20:46-21:27 (auto-évaluation par répétition, fusion/regroupement compétences immuables, versioning adaptateurs UI, portabilité du modèle appris) **existent déjà** dans le repo :
+
+- `core/learning/continuous_learner.py` — **644 lignes**
+- `core/learning/feedback_processor.py` — **176 lignes**
+- `PrototypeVersionManager` (support de ContinuousLearner)
+- `TargetMemoryStore`, `VersionedStore` (supports)
+
+**Et ils sont tous orphelins** : ils ne sont pas importés par les points d'entrée actifs (`api_stream.py`, `run_worker.py`, `agent_chat/app.py`, `web_dashboard/app.py`, etc.).
+
+**En plus** : le **worker VLM** (le composant qui retraite les sessions finalisées avec ScreenAnalyzer/CLIP/FAISS/GraphBuilder) **n'a traité aucune session depuis 5 jours** (queue vide). Sessions accumulées non passées par le pipeline d'enrichissement profond.
+
+## Section meta — Constat de méthode (à dire franchement)
+
+> Dom 2026-06-01 ~21:55 : « on vient de passer presque 7 jours à refaire ce que j'avais déjà fait. Il faut arrêter de réinventer la roue. »
+
+C'est un constat factuel et juste. Cet audit (le seul à avoir cartographié l'existant) aurait dû être fait **avant** :
+- de spécifier P1-SEMANTIQUE comme une nouvelle Phase 2.5 ;
+- de proposer un `LoopDetector` proactif comme « bonus » alors que `ContinuousLearner` couvre ce besoin ;
+- de discuter de « désapprentissage » (notion que Dom a explicitement rejetée 21:27) alors que `PrototypeVersionManager` gère déjà le versioning des prototypes ;
+- de proposer de nouveaux mécanismes de fusion de compétences alors que `FeedbackProcessor` est conçu pour ça.
+
+**Pourquoi cet oubli ?** Trois facteurs cumulés :
+1. `docs/POC/` (5 docs Dom déposés du 28-29/05 et 01/06) a été lue **après** rédaction du plan POC Claude du jour (mémorisé comme erreur de méthode dans `feedback_lire_docs_poc_avant_depot.md`).
+2. **Aucun agent n'a été missionné en début de journée pour cartographier l'existant** dans `core/learning/`, `core/healing/`, `core/cognition/`. Mon audit Explore de 17:00 a flagué `ContinuousLearner` et `RecoveryLogger` comme orphelins mais sans alarmer sur le fait que ces orphelins **étaient précisément ce qui était demandé**.
+3. Codex a été en mode urgence patch (P0 régression, dashboard test, etc.) et Claude en mode livraison agressive (5 livraisons P1 dans la journée) **sans pause cartographie**.
+
+**Décision opérationnelle à acter** : **avant tout nouveau module Léa learning, lancer un agent Explore qui vérifie ce qui existe dans `core/learning/`, `core/cognition/`, `core/healing/`, `core/training/`**. Ne pas spec/coder un module avant d'avoir confirmé qu'il n'a pas déjà été codé et débranché par Dom dans une session antérieure.
+
+## §1 — Schéma de la chaîne attendue
+
+```
+[Phase 1 — Capture]
+  PC Windows agent_v1 → push frames + actions + events
+  ↓
+  data/training/live_sessions/<machine>/<session>/
+     ├ shots/*.png
+     ├ actions.jsonl
+     └ events.jsonl
+  ↓
+  finalize() côté api_stream.py
+  ↓
+  enqueue → data/training/_worker_queue.txt        ← ⚠️ EXISTE, vide depuis 5 jours
+
+[Phase 2 — Enrichissement post-session (worker VLM)]
+  run_worker.py poll _worker_queue.txt (10s interval)
+  ↓
+  StreamProcessor.reprocess_session()
+     ├ ScreenAnalyzer (VLM lecture sémantique)
+     ├ CLIPEmbedder (embeddings UI)
+     ├ FAISS index update
+     ├ _enrich_actions_with_intentions (Ollama gemma4 → intention/avant/après)
+     └ GraphBuilder (transitions états)
+  ↓
+  data/training/.../enriched_*.jsonl + index.faiss
+
+[Phase 3 — Construction WorkflowIR]
+  build_replay_from_raw_events() → WorkflowIR
+  ↓
+  data/workflows/<session_id>.json  OU  data/competences/candidate/<slug>.yaml
+     selon le chemin (legacy workflow vs nouveau cycle Léa-first 01/06)
+
+[Phase 4 — Apprentissage continu (CŒUR DU DÉBAT)]
+  ┌──────────────────────────────────────────────────────┐
+  │ ContinuousLearner (644 lignes, ORPHELIN)            │
+  │  ├ EMA online sur prototypes                         │
+  │  ├ Détection dérive UI (variance temporelle)         │
+  │  ├ Variantes de prototypes (clustering)              │
+  │  ├ TargetMemoryStore : mémoire des éléments cibles   │
+  │  └ PrototypeVersionManager : versioning rollback     │
+  │                                                       │
+  │ FeedbackProcessor (176 lignes, ORPHELIN)             │
+  │  ├ Boucle feedback humain → ajustement prototype    │
+  │  └ Fusion observations multiples → compétence       │
+  └──────────────────────────────────────────────────────┘
+        ↑
+        |  Doit être déclenché par : nouvelle session retraitée
+        |  Doit produire : score confiance, variantes, dérive
+        ↓
+  data/learning/prototypes_<state>.json (présent ? à vérifier disque)
+  data/learning/feedback_log.jsonl (présent ? à vérifier disque)
+
+[Phase 5 — Boucle retour healing]
+  ┌──────────────────────────────────────────────────────┐
+  │ RecoveryLogger (ORPHELIN runtime hors VWB)          │
+  │ SelfHealingIntegration (VWB seulement)              │
+  └──────────────────────────────────────────────────────┘
+
+[Phase 6 — Utilisation au replay (HOT PATH)]
+  resolve_engine.py :
+     cascade OCR → template matching → VLM grounding
+     (PAS de consultation des prototypes ContinuousLearner)  ← rupture
+     (PAS de consultation FAISS index appris)               ← rupture
+
+  Si compétence avec .semantic.yaml (Phase 2.5 nouveau 01/06) :
+     Phase25Analyzer.match_screen() → annotations sémantiques
+
+[Phase 7 — Fine-tuning VLM (HORS rpa_vision_v3)]
+  ~/ai/t2a-finetune/, ~/ai/t2a/, ~/ai/t2a_v2/
+  Modèle custom Dom : qwen2.5vl:7b-rpa
+  Dataset alimenté manuellement (probablement) ← non-vérifié
+```
+
+## §2 — État par phase
+
+| Phase | Code existe | Wired runtime | Dernière utilisation effective | Verdict |
+|---|---|---|---|---|
+| 1. Capture live | ✅ | ✅ | aujourd'hui (sessions live actives) | OK |
+| 1bis. Enqueue worker | ✅ (`finalize()` `api_stream.py:2253+`) | ⚠️ **à diagnostiquer** | Probablement débranché — queue vide 5j alors que sessions live continuent | ⚠️ R6 critique |
+| 2. Worker VLM post-session | ✅ (`run_worker.py`) | ✅ (réveillé aujourd'hui 18:54 PID 4054092) | **0 session traitée depuis 5 jours** | ⚠️ tourne à vide |
+| 2bis. Enrichissement actions | ✅ (`stream_processor.py:1643`) | ✅ (au build) | continu, mais perd valeur sans ContinuousLearner | OK partiel |
+| 3. Construction WorkflowIR | ✅ | ✅ (au moment du build) | aujourd'hui (P1-LEA-SHADOW livré) | OK nouveau cycle |
+| **4. ContinuousLearner** | ✅ **644 lignes** | ❌ **ORPHELIN** | Jamais appelé en runtime | 🔴 **DÉBRANCHÉ** |
+| **4bis. FeedbackProcessor** | ✅ **176 lignes** | ❌ **ORPHELIN** | Jamais appelé | 🔴 **DÉBRANCHÉ** |
+| **4ter. PrototypeVersionManager** | ✅ | ❌ ORPHELIN (dép ContinuousLearner) | Jamais | 🔴 DÉBRANCHÉ |
+| 5. RecoveryLogger | ✅ | ❌ ORPHELIN hors VWB | VWB seulement | 🔴 DÉBRANCHÉ runtime agent_v1 |
+| 6. Replay hot path | ✅ | ✅ | actif | OK fonctionnel mais déconnecté de Phase 4 |
+| 6bis. Phase 2.5 sémantique | ✅ (livré 20:15) | ✅ (endpoint dispo) | aujourd'hui | OK nouveau |
+| 7. Fine-tuning VLM | ✅ hors repo (siblings) | n/a (asynchrone manuel) | inconnu | hors scope audit interne |
+
+## §3 — Ruptures identifiées
+
+| ID | Rupture | Sévérité | Détail | Conséquence POC |
+|---|---|---|---|---|
+| **R1** | ContinuousLearner orphelin | 🟡 MOYENNE | EMA online, dérive UI, variantes prototypes : **tous existent mais non câblés**. Couvre exactement le besoin "auto-évaluation par répétition" exprimé par Dom 2026-06-01 20:46. | Pas d'apprentissage incrémental cross-session. Léa ne s'améliore pas avec l'usage. |
+| **R2** | PrototypeVersionManager orphelin | 🟡 MOYENNE | Dépend de R1. Versioning prototypes + rollback. Couvre "versioning des adaptateurs UI" demandé par Dom 21:27. | Pas de rollback prototype dégradé. Pas de gestion versions UI. |
+| **R3** | FeedbackProcessor orphelin | 🟠 LOURDE | Boucle feedback humain → ajustement prototype. **Cœur de la fusion/regroupement vers compétence immuable** demandée par Dom 21:27. | Léa Phase 4 humaine (corrections) ne nourrit pas le modèle. Apprentissage repart de zéro à chaque session. |
+| **R4** | RecoveryLogger orphelin runtime | 🟢 FAIBLE | Healing limité à VWB. Pas de retour boucle sur sessions agent_v1 ratées. | Workflows en échec récurrent ne génèrent pas d'insights actionnables. |
+| **R5** | Phase 2.5 sémantique (livrée aujourd'hui) → utilisation au replay incertaine | 🟢 FAIBLE | `.semantic.yaml` produit mais utilisé seulement si Phase25Analyzer.match_screen() est consultée. Wiring à confirmer. | Annotations sémantiques apprises peut-être pas exploitées au replay. |
+| **R6** | **Worker queue vide depuis 5 jours malgré sessions live actives** | 🔴 **CRITIQUE** | Le worker tourne (PID 4054092 actif) mais `data/training/_worker_queue.txt` est vide. **Soit `finalize()` n'enqueue plus, soit toutes les sessions échouent silencieusement à se finaliser, soit la queue est purgée ailleurs.** À diagnostiquer URGENT. | **0 enrichissement profond depuis 5 jours**. Toutes les sessions live actuelles sont stockées brutes sans ScreenAnalyzer/CLIP/FAISS/GraphBuilder. POC Wallerstein impossible en l'état. |
+
+## §4 — Modules orphelins inventaire
+
+### O1 — `core/learning/continuous_learner.py` (644 lignes)
+
+- **Rôle** : adaptation incrémentale des prototypes UI par EMA online, détection de dérive temporelle, génération de variantes par clustering
+- **Importé par** : 0 point d'entrée actif (vérifié par grep)
+- **Dernière modification git** : à confirmer
+- **Pourquoi débranché** : inconnu — pas de commit `disable` ou `remove` visible. Probablement n'a jamais été câblé en runtime depuis sa création (intention de wiring jamais finalisée).
+- **Effort rebranchement** : **MOYEN** (2-3 j-h). Nécessite :
+  - Hook dans `run_worker.py` après `reprocess_session()` pour appeler `learner.update(prototypes, new_observations)`
+  - Chargement initial des prototypes au démarrage worker
+  - Persistance prototypes mis à jour : `data/learning/prototypes_<state>.json`
+  - Tests intégration : sessions répétées sur même UI → vérification EMA progresse
+
+### O2 — `core/learning/feedback_processor.py` (176 lignes)
+
+- **Rôle** : intègre les feedbacks humains (validate/correct/undo Phase 4 Léa-first) dans le modèle prototype
+- **Importé par** : 0 point d'entrée actif
+- **Effort rebranchement** : **LOURD** (3-5 j-h). Nécessite :
+  - Hook dans `agent_chat/handlers/learn_action.py` (livré aujourd'hui) à chaque `POST /shadow/feedback`
+  - Routage : feedback → FeedbackProcessor → ContinuousLearner
+  - Persistance log : `data/learning/feedback_log.jsonl`
+  - Tests : validation step → prototype renforcé ; correction → prototype variante créée
+
+### O3 — `PrototypeVersionManager`
+
+- **Rôle** : versionner les prototypes successifs, permettre rollback si nouvelle version dégrade
+- **Dépendance** : ContinuousLearner (utilise pour stocker versions)
+- **Effort rebranchement** : **FAIBLE** (1 j-h) une fois O1 rebranché
+- **Couvre la décision Dom 21:27** : « Ce qu'il faut versionner/invalider, ce sont plutôt mappings UI propres à une application/version, sélecteurs/positions/labels OCR, hypothèses fragiles ou obsolètes, compétence mal validée »
+
+### O4 — `TargetMemoryStore`, `VersionedStore`
+
+- **Rôle** : supports de persistance pour les prototypes versionnés
+- **Effort** : couvert par O1+O3
+
+### O5 — `RecoveryLogger` / `SelfHealingIntegration`
+
+- **Statut** : utilisé par VWB seulement, pas par agent_v1 runtime
+- **Effort rebranchement runtime agent_v1** : MOYEN (2 j-h)
+- **Priorité** : P2 (post-MVP), pas critique POC
+
+## §5 — Worker queue R6 — diagnostic urgent
+
+**Constat** : worker actif PID 4054092 depuis 18:54, log indique poll toutes les 10s sur `_worker_queue.txt`. Mais **0 traitement** depuis le réveil.
+
+**Hypothèses à vérifier (par ordre de probabilité)** :
+
+1. **`finalize()` côté `api_stream.py:2253+` n'enqueue plus** (commit qui a cassé le pipeline)
+2. Les sessions live actuelles ne sont **jamais finalisées** (problème côté agent_v1 Windows qui ne push pas la fin de session)
+3. La queue est **purgée par un autre processus** (cron ? cleanup ?)
+4. Path resolution : worker poll un fichier inexistant ou un chemin différent de celui où `finalize()` écrit
+
+**Action recommandée** : lancer un agent Explore ciblé sur :
+- `git log -p agent_v0/server_v1/api_stream.py | grep -A 20 "finalize\|_worker_queue"` pour voir les commits récents touchant à la queue
+- Tester manuellement : finaliser une session test, vérifier que le fichier `_worker_queue.txt` est touché, vérifier que le worker la dépile
+- Identifier où la rupture est exacte
+
+## §6 — Effort global de rebranchement
+
+| Composant | Effort | Priorité POC Wallerstein |
+|---|---|---|
+| **R6 — Diagnostic worker queue** | Faible (1-2 j-h) | 🔴 **P0 ABSOLU** (sinon POC impossible) |
+| O1+O3+O4 — ContinuousLearner + Versioning | Moyen (2-3 j-h) | 🟠 P1 (apprentissage incrémental) |
+| O2 — FeedbackProcessor | Lourd (3-5 j-h) | 🟠 P1 (fusion compétences) |
+| O5 — RecoveryLogger runtime | Moyen (2 j-h) | 🟢 P2 (post-MVP) |
+| **Total rebranchement (P0+P1)** | **6-10 j-h** | À comparer aux ~15 j-h de spécifications/impl P1 d'aujourd'hui qui les reconstruisaient partiellement de zéro |
+
+## §7 — Conséquences POC Wallerstein
+
+### En l'état actuel (rien rebranché)
+
+- ❌ **Aucune session traitée par le pipeline d'enrichissement profond depuis 5 jours** (worker tourne à vide). Cumulé des sessions live brutes accumulées : ScreenAnalyzer, CLIP, FAISS, GraphBuilder pas appliqués.
+- ❌ **Pas d'apprentissage incrémental** : chaque démo Léa = repart de zéro. Pas d'auto-évaluation par répétition (alors que Dom le demande explicitement 20:46).
+- ❌ **Pas de versioning prototypes** : si Easily/DPI change d'interface, pas de mécanisme de rollback. (Alors que Dom le demande 21:27.)
+- ❌ **Pas de portabilité du modèle appris** : pas de paquet portable de réflexes/compétences/schémas/détecteurs/mappings, car ce paquet est produit par la chaîne d'apprentissage qui est débranchée. (Alors que Dom dit « point essentiel » 21:27.)
+- ✅ Restitution Option C livrée aujourd'hui (P1-LEA-SHADOW) mais **trop longue** pour sessions 1-2h (recadrage Dom 20:46)
+- ✅ Phase 2.5 sémantique livrée mais **ne produit pas encore les signaux de confiance/regroupement** demandés (recadrage Dom 20:46)
+
+### Avec rebranchement P0+P1 (6-10 j-h)
+
+- ✅ Worker pipeline actif → toutes les sessions live enrichies (ScreenAnalyzer/CLIP/FAISS/GraphBuilder)
+- ✅ ContinuousLearner alimenté → apprentissage par répétition automatique
+- ✅ FeedbackProcessor branché → fusion progressive vers compétences immuables
+- ✅ PrototypeVersionManager actif → versioning mappings UI, rollback si dégradation
+- ⚠️ Reste à ajouter : enrichir P1-LEA-SHADOW et P1-SEMANTIQUE avec champs `confidence`, `uncertainties[]`, `repetition_count`, distinctions `hypothesis`/`candidate`/`validated` (≈2-3 j-h additionnels)
+- ⚠️ Reste à concevoir : paquet portable séparé de la mémoire patient (décision Dom 21:27 — pas encore couvert par aucune impl, ni avant aujourd'hui ni dans mes livraisons P1) (≈3-5 j-h)
+
+## §8 — Plan d'action recommandé
+
+### Étape A — IMMÉDIAT (avant tout nouveau dev)
+
+1. **Diagnostic R6 worker queue** (1-2 j-h) : pourquoi vide depuis 5 jours malgré sessions live actives
+2. **Audit factuel modules orphelins** : confirmer le bon état du code de `ContinuousLearner`, `FeedbackProcessor`, `PrototypeVersionManager` (pas de bug bloquant, signatures à jour vis-à-vis du reste du codebase)
+3. **Lecture par Dom** des modules orphelins pour confirmer qu'ils correspondent bien à son intention historique
+
+### Étape B — REBRANCHEMENT (P0+P1)
+
+4. Rebrancher worker queue (R6) — code probablement minimal, action chirurgicale
+5. Rebrancher ContinuousLearner + supports (O1+O3+O4) avec tests intégration
+6. Rebrancher FeedbackProcessor (O2) + hook dans `agent_chat/handlers/learn_action.py` (livré aujourd'hui) à chaque `POST /shadow/feedback`
+
+### Étape C — AJUSTEMENTS LIVRAISONS P1
+
+7. Ajouter `confidence`, `uncertainties[]`, `repetition_count`, `hypothesis/candidate/validated` aux SessionState + payload persist
+8. Phase 2.5 sémantique : enrichir pour produire signaux confiance + regroupement (actions stables vs parasites, invariants vs variables, blocs récurrents)
+9. Option C restitution : raccourcir à « centré incertitudes uniquement », jamais relecture complète
+
+### Étape D — PORTABILITÉ (objectif Dom essentiel)
+
+10. Concevoir paquet portable : export réflexes/compétences/schémas/détecteurs/mappings/plans d'action/métriques, **sans** mémoire patient ni captures brutes
+11. Mécanisme d'import sur poste tiers
+12. Validation : aucune trace patient dans le paquet exporté
+
+## §9 — Sources de l'audit
+
+- Agent Explore Claude — 2026-06-01 21:50 (audit primaire)
+- Audit Claude antérieur 17:00 (`feedback_lea_principes_techniques.md`) qui avait flagué `ContinuousLearner` et `RecoveryLogger` comme orphelins (mais sans alarme suffisante)
+- Audit Explore worker VLM 17:30 (Claude) qui avait confirmé que worker traite sessions finalisées
+- 5 messages Codex 2026-06-01 20:46-21:37 relayant 5 décisions/clarifications Dom
+- Code source `core/learning/`, `core/healing/`, `agent_v0/server_v1/`, `agent_chat/`
+
+---
+
+*Fin DRAFT — relecture Dom/Codex/Qwen attendue avant action.*
+
+**Décision opérationnelle proposée à Dom** : suspendre tout nouveau dev de modules d'apprentissage Léa tant que (a) R6 worker queue n'est pas diagnostiqué + corrigé et (b) Dom n'a pas confirmé que les modules orphelins identifiés correspondent à son intention historique.