docs: add POC specs, handoffs, and research notes

docs/architecture/CARTOGRAPHIE_BRIQUES_MANDAT_PROTOCOLS_2026-05-25.md

@@ -0,0 +1,474 @@
+# Cartographie des briques existantes — modèle Mandat / Protocoles
+
+Date : 2026-05-25
+Statut : lecture structurelle, pas une spec d'implémentation
+
+## Synthèse
+
+Le projet contient déjà la plupart des briques nécessaires au modèle :
+
+```text
+intention / mandat        -> agent_chat + working_memory + ORA
+protocoles / gestes       -> gesture_catalog + autonomous_planner + workflows VWB
+observation visuelle      -> capturers + grounding + SomEngine + OCR/VLM
+scènes / dialogues        -> DialogResolver + window guards + UI patterns
+action                    -> agent_v1 executor + replay engine
+vérification retour       -> ReplayVerifier + Validator V2 + shadow validator
+apprentissage             -> replay_learner + target_memory + correction packs + coaching
+évaluation                -> LeaBench + tests replay + démo DPI
+supervision               -> pause supervisée + UI Léa + confirmation loop
+```
+
+La faiblesse principale n'est pas l'absence de composants. C'est leur absence de **contrat unificateur** autour de :
+
+```text
+mandat -> intention -> scène -> affordance -> geste -> retour -> preuve apprenable
+```
+
+## Briques runtime live
+
+### Agent Windows live
+
+Fichiers :
+
+```text
+agent_v0/agent_v1/core/executor.py
+agent_v0/agent_v1/core/grounding.py
+agent_v0/agent_v1/core/policy.py
+agent_v0/agent_v1/core/recovery.py
+agent_v0/agent_v1/core/system_dialog_guard.py
+agent_v0/agent_v1/ui/*
+```
+
+Rôle actuel :
+
+```text
+exécuter les actions ;
+résoudre les cibles visuelles ;
+faire les fallbacks ;
+pauser/demander de l'aide ;
+gérer certains dialogues ;
+remonter les résultats au serveur.
+```
+
+Lien avec le modèle :
+
+```text
+geste
+observation locale
+doute de localisation
+doute de scène
+retour action
+pause supervisée
+```
+
+Manque conceptuel :
+
+```text
+pas encore de trace causale complète ;
+pas de mandat/intention actif porté explicitement ;
+fallbacks encore trop locaux si non encadrés par le contrat ;
+pas de typage explicite du doute dans l'API résultat.
+```
+
+### Serveur replay / coordination
+
+Fichiers :
+
+```text
+agent_v0/server_v1/api_stream.py
+agent_v0/server_v1/stream_processor.py
+agent_v0/server_v1/replay_engine.py
+agent_v0/server_v1/replay_watchdog.py
+agent_v0/server_v1/replay_verifier.py
+agent_v0/server_v1/replay_learner.py
+agent_v0/server_v1/replay_memory.py
+agent_v0/server_v1/resolve_engine.py
+```
+
+Rôle actuel :
+
+```text
+construire/rejouer les actions ;
+distribuer les actions à l'agent ;
+résoudre les cibles côté serveur ;
+vérifier les retours ;
+planifier retries ou pauses ;
+enregistrer résultats et apprentissages.
+```
+
+Lien avec le modèle :
+
+```text
+protocole candidat sous forme workflow/replay ;
+résolution scène/affordance via resolve_engine ;
+retour via ReplayVerifier ;
+preuve potentielle via replay_learner/replay_memory ;
+pause supervisée ;
+temporalité via watchdog/retry.
+```
+
+Manque conceptuel :
+
+```text
+le workflow reste la structure dominante ;
+les expected_result existent mais ne forment pas encore une trace causale ;
+la vérification ne sait pas toujours quelle intention elle valide ;
+les retries ne sont pas encore arbitrés par doute typé.
+```
+
+## Briques cognitives déjà présentes
+
+### Mémoire de travail
+
+Fichier :
+
+```text
+core/cognition/working_memory.py
+```
+
+Points forts :
+
+```text
+objective ;
+current_step ;
+observation courante ;
+historique d'actions ;
+faits appris ;
+expected_screen ;
+confidence ;
+needs_help ;
+timing.
+```
+
+Correspondance modèle :
+
+```text
+mandat/intention embryonnaire ;
+trace courte ;
+précondition attendue via expected_screen ;
+temporalité ;
+doute via confidence/needs_help.
+```
+
+Manque :
+
+```text
+pas encore de scène d'intention typée ;
+pas de trace causale formelle geste/scène/intention/hypothèse/retour ;
+pas de distinction correction/démonstration/validation.
+```
+
+### Boucle ORA
+
+Fichier :
+
+```text
+core/execution/observe_reason_act.py
+```
+
+Points forts :
+
+```text
+observe -> reason -> act -> verify ;
+Decision avec expected_after ;
+VerificationResult ;
+mode instruction via VLM ;
+erreurs typées de base.
+```
+
+Correspondance modèle :
+
+```text
+base naturelle pour le contrat d'action ;
+hypothèse de retour via expected_after ;
+vérification post-geste.
+```
+
+Manque :
+
+```text
+encore orienté step/workflow ;
+pas de protocole ouvert ;
+pas de preuve apprenable structurée ;
+pas d'opérateur d'extension de grammaire.
+```
+
+## Briques intention / gestes / risque
+
+### Agent chat et planification autonome
+
+Fichiers :
+
+```text
+agent_chat/intent_parser.py
+agent_chat/autonomous_planner.py
+agent_chat/gesture_catalog.py
+agent_chat/confirmation.py
+agent_chat/urgences_orchestrator.py
+```
+
+Points forts :
+
+```text
+parseur d'intentions utilisateur ;
+planner libre sans workflow pré-enregistré ;
+catalogue de gestes universels Windows/navigateur/édition ;
+évaluation de risque ;
+confirmation utilisateur ;
+orchestrateur urgence avec intentions nommées.
+```
+
+Correspondance modèle :
+
+```text
+mandat ;
+protocoles universels ;
+gestes types ;
+niveau de risque ;
+protocole métier urgence.
+```
+
+Manque :
+
+```text
+cette couche semble parallèle au runtime live, pas intégrée au replay agent_v1 ;
+le risque est lexical et statique, pas encore tutoré par niveau de délégation ;
+les gestes ne sont pas encore reliés à scènes/affordances/retours qualifiés.
+```
+
+## Briques scènes / dialogues
+
+### DialogResolver
+
+Fichiers :
+
+```text
+agent_v0/server_v1/core/dialog/catalog.py
+agent_v0/server_v1/core/dialog/resolver.py
+tests/unit/test_dialog_resolver.py
+tests/integration/test_dialog_resolver_endpoint.py
+```
+
+Points forts :
+
+```text
+catalogue de dialogues connus ;
+policy auto/pause/skip ;
+protection modaux système ;
+pause conservative sans match ;
+evidence title + OCR/UIA.
+```
+
+Correspondance modèle :
+
+```text
+scènes d'intention simples ;
+affordances compatibles par dialogue ;
+affordances anti-intention potentielles ;
+rupture de scène.
+```
+
+Manque :
+
+```text
+pas encore branché sur une intention active ;
+un dialogue est connu en absolu, pas encore "compatible avec ce mandat" ;
+les scènes composées métier restent hors catalogue.
+```
+
+## Briques vérification / preuve
+
+### ReplayVerifier et Validator V2
+
+Fichiers :
+
+```text
+agent_v0/server_v1/replay_verifier.py
+core/validation/orchestrator.py
+core/workflow/shadow_validator.py
+tests/unit/test_replay_critic.py
+tests/integration/test_validator_step10.py
+```
+
+Points forts :
+
+```text
+vérification pixel ;
+critic sémantique avec expected_result ;
+verdicts agrégés ;
+shadow validation.
+```
+
+Correspondance modèle :
+
+```text
+qualification du retour ;
+preuve apprenable potentielle ;
+doute d'effet ;
+temporalité post-action.
+```
+
+Manque :
+
+```text
+le retour n'est pas toujours rattaché à intention/scène/affordance ;
+le "rien ne change" n'est pas encore qualifié par protocole ;
+la preuve apprenable n'est pas encore un objet explicite.
+```
+
+## Briques apprentissage / correction
+
+### Mémoire et corrections
+
+Fichiers :
+
+```text
+core/learning/target_memory_store.py
+agent_v0/server_v1/replay_learner.py
+agent_v0/server_v1/replay_memory.py
+core/corrections/*
+core/coaching/*
+```
+
+Points forts :
+
+```text
+mémoire de cible persistante JSONL + SQLite ;
+résultats replay enregistrés ;
+correction packs versionnés ;
+statistiques succès/échec ;
+sessions de coaching avec accept/reject/correct/manual/skip.
+```
+
+Correspondance modèle :
+
+```text
+preuve apprenable ;
+correction ;
+démonstration ;
+validation ;
+désapprentissage par baisse confiance / failure_count ;
+niveau de délégation tutoré.
+```
+
+Manque :
+
+```text
+les preuves actuelles sont très orientées cible UI ;
+il manque intention/scène/affordance/retour dans la clé d'apprentissage ;
+correction et démonstration sont proches mais pas encore distinguées au niveau modèle ;
+le niveau de délégation par protocole/environnement n'est pas centralisé.
+```
+
+## Briques évaluation / terrains d'essai
+
+### LeaBench
+
+Fichiers :
+
+```text
+core/evaluation/computer_use_bench.py
+core/evaluation/ollama_lea_bench_adapter.py
+tools/lea_bench.py
+tools/lea_bench_ollama.py
+benchmarks/computer_use/cases/*.jsonl
+```
+
+Rôle :
+
+```text
+mesurer décisions computer-use ;
+cas Bloc-notes/replay ;
+adapter modèles locaux ;
+scorer abstention/danger.
+```
+
+Usage modèle :
+
+```text
+tester scène/intention/affordance ;
+mesurer action fiable vs abstention ;
+convertir échecs réels en cas reproductibles.
+```
+
+### Maquette DPI / urgence
+
+Fichiers :
+
+```text
+demo/facturation_urgences/*
+tests/e2e/test_urgence_aiva_demo.py
+tests/e2e/fixtures/urgence_aiva_demo/*
+```
+
+Rôle :
+
+```text
+terrain métier ;
+cas urgences synthétiques ;
+workflow démo existant ;
+stress test scènes composées et protocole métier.
+```
+
+Usage modèle :
+
+```text
+protocole métier générique ;
+adaptateur applicatif ;
+apprentissage sans contenu sensible réel ;
+validation de la généralisation hors Bloc-notes.
+```
+
+## Diagnostic structurel
+
+Le projet a déjà presque toutes les pièces, mais elles ne sont pas au même étage :
+
+```text
+agent_chat sait raisonner intention/risque mais n'est pas le runtime live principal ;
+agent_v1 sait exécuter live mais raisonne encore action/cible ;
+server_v1 sait vérifier/apprendre mais pas sous trace causale complète ;
+core/cognition a la mémoire de travail mais elle n'est pas encore le fil commun ;
+core/learning sait mémoriser mais pas encore apprendre une grammaire d'action ;
+LeaBench sait mesurer mais doit recevoir des cas "mandat/protocole/scène".
+```
+
+## Assemblage conceptuel recommandé
+
+Sans parler encore de code, la bonne direction est d'utiliser :
+
+```text
+core/cognition/working_memory.py
+comme fil de mandat/intention/trace causale ;
+
+agent_chat/gesture_catalog.py
+comme base des protocoles universels ;
+
+agent_v0/server_v1/core/dialog/*
+comme catalogue initial de scènes/dialogues ;
+
+agent_v0/server_v1/replay_verifier.py + core/validation/*
+comme qualification du retour ;
+
+core/learning + core/corrections + core/coaching
+comme apprentissage tutoré et désapprentissage ;
+
+LeaBench + Bloc-notes + maquette DPI
+comme banc de validation progressif.
+```
+
+## Point d'attention immédiat
+
+Une correction technique est déjà en attente dans :
+
+```text
+agent_v0/agent_v1/core/grounding.py
+```
+
+Elle bloque le fallback texte local après rejet sémantique serveur. Elle correspond directement à la règle :
+
+```text
+un rejet sémantique doit dominer les fallbacks opportunistes.
+```
+
+Elle devra être testée et intégrée quand on repassera en exécution.