rpa_vision_v3/docs/DETTE_TECHNIQUE.md

# Registre de dette technique

Registre central des dettes techniques identifiées sur le projet.
Règle : toute désactivation de contrôle ou contournement assumé fait l'objet d'une entrée. Revue par défaut à création + 14 jours.

## Statuts
- OPEN : à traiter
- IN_PROGRESS : en cours de résolution
- RESOLVED : résolu (date résolution + commit ref)
- ACCEPTED : assumé définitivement, pas de résolution prévue

## Sévérités
P0 / P1 / P2 / P3 (alignées sur convention handoffs)

## Entrées

| ID | Date création | Date revue | Sévérité | Statut | Description | Origine |
|----|---------------|------------|----------|--------|-------------|---------|
| DETTE-001 | 2026-05-08 | 2026-05-22 | P1 | OPEN | Pré-check OCR spatialement aveugle | docs/BUG_PRECHECK_SPATIAL_BLINDNESS_2026-05-08.md |
| DETTE-002 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Exemption drift > 0.20 si template_matching ≥ 0.95 ou hybrid_text_direct ≥ 0.80 (resolve_engine.py:2367-2390) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F2.2.1) |
| DETTE-003 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Self-healing Win+D au retry 1 retiré (revert 22c0a2ba6, replay_engine.py) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F2.2.3) |
| DETTE-004 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Cascade OmniParser/YOLO neutralisée — `_resolve_by_yolo` défini, importé, jamais appelé (resolve_engine.py:293) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F2.4.1) |
| DETTE-005 | 2026-05-08 | 2026-05-22 | P2 | OPEN | Sous-système mémoire visuelle orphelin — `VisualEmbeddingManager` + `ScreenshotValidationManager` (core/visual/*) définis mais jamais instanciés en runtime | docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md |
| DETTE-006 | 2026-05-08 | 2026-05-23 | P0 | IN_PROGRESS | Bug échelle pixel grounding Ollama smart_resize non-déterministe | docs/MIGRATION_VLM_PLAN_2026-05-09.md |
| DETTE-007 | 2026-05-09 | 2026-05-23 | P3 | OPEN | Trois implémentations smart_resize coexistent (server.py, infigui_worker.py, nouveau module officiel). Unification post-démo Kerella. | commit feat(grounding): module smart_resize officiel |
| DETTE-008 | 2026-05-09 | 2026-05-23 | P2 | OPEN | Pre-check VLM par-clic désactivé via `if False:` (observe_reason_act.py:1704-1713) | docs/AUDIT_CONTROLES_DEBRANCHES_2026-05-08.md (F6.1.1) |
| DETTE-009 | 2026-05-09 | 2026-05-23 | P3 | OPEN | `ShadowLearningHook` (core/grounding/shadow_learning_hook.py) défini mais jamais instancié — Phase 6 du pipeline FAST→SMART→THINK non câblée à l'observation Shadow | docs/INVESTIGATION_MEMOIRE_VISUELLE_ORPHELINE_2026-05-09.md |
| DETTE-010 | 2026-05-09 | 2026-05-10 | P1 | IN_PROGRESS | preprocessor_config.json du checkpoint Qwen3-VL-8B-Instruct lu (snapshot 0c351dd01ed87...) : `image_processor_type=Qwen2VLImageProcessorFast` (variant différent de Qwen2VLImageProcessor lue ce matin), `patch_size=16` (vs 14 hypothèse matin → factor probable 32 au lieu de 28), `size={longest_edge: 16_777_216, shortest_edge: 65_536}` (convention différente de min_pixels/max_pixels), `min_pixels`/`max_pixels` absents du config. Investigation requise demain matin : lire transformers.models.qwen2_vl.image_processing_qwen2_vl_fast pour comprendre défauts effectifs et sémantique. Conséquence pour module smart_resize.py : peut nécessiter ajustement (factor, bornes, sémantique). Étape 2 (validation grounding isolée) DOIT être précédée de cette investigation. | docs/MIGRATION_VLM_PLAN_2026-05-09.md + commit 0d7bcd18a (smart_resize) + investigation 2026-05-09 |
| DETTE-011 | 2026-05-09 | 2026-05-23 | P2 | OPEN | Bug `cv2.gapi.wip.draw.Text` manquant en Python 3.12 (déclenché par import `agent_v0.server_v1` dans tests/unit/conftest.py:26). Bloque pytest-cov sur tous les tests qui importent la chaîne. Contournement actuel : stub cv2 + coverage API directe. Investigation : version cv2 vs Python 3.12 compat, ou import conditionnel dans conftest. | session 2026-05-09 (découvert pendant TDD smart_resize) |
| DETTE-012 | 2026-05-09 | 2026-05-23 | P3 | OPEN | Migration backend grounding vers vLLM (option mentionnée dans plan migration mais infra absente : pas d'install vLLM, pas de service systemd dédié). Choix Transformers direct retenu pour fix DETTE-006. Migration vLLM à instruire séparément si bénéfice mesuré post-démo Kerella. | docs/MIGRATION_VLM_PLAN_2026-05-09.md + investigation infra session 2026-05-09 |
| DETTE-013 | 2026-05-09 | 2026-05-23 | P2 | OPEN | Environnement de tests dev local cassé : pytest tests/unit/ déclenche sys.exit(1) via import api_stream sans RPA_API_TOKEN/RPA_AUTH_DISABLED définis (api_stream.py:135, fail-closed sécurité commit 93ef93e56). Combiné avec DETTE-011 (cv2 dans conftest), la batterie de tests unitaires complète n'est pas exécutable en dev local sans configuration environnement spécifique. À documenter (env vars requises) ou refactor (découpler tests purs des tests chargeant api_stream). | session 2026-05-09 (découvert pendant validation refactor bbox_parser) |
| DETTE-014 | 2026-05-09 | 2026-05-10 | P1 | OPEN | Module core/grounding/smart_resize.py commité ce matin (commit 0d7bcd18a) calé sur la référence transformers.qwen2_vl.image_processing_qwen2_vl (factor=28, max_pixels=1_003_520). Le checkpoint Qwen3-VL-8B-Instruct utilise en réalité Qwen2VLImageProcessorFast avec patch_size=16 (factor probable 32) et convention size.longest_edge/shortest_edge. À réaligner après investigation DETTE-010 demain. Module pur, testé à 100% sur la convention actuelle — la convention reste valide en référence, mais ne s'applique pas à ce checkpoint. | commit 0d7bcd18a + investigation DETTE-010 du 2026-05-09 |
| DETTE-015 | 2026-06-09 | 2026-06-23 | P1 | OPEN | Double stockage des workflows incohérent. La route API VWB `/api/workflows/` lit des fichiers JSON via `WorkflowDatabase("data/workflows")` (api/workflows.py:53, chemin **relatif au cwd**), alors qu'une DB SQLAlchemy propre coexiste (`visual_workflow_builder/backend/instance/workflows.db`, table `workflows` + migrations Alembic). Le worker DGX persiste les workflows appris dans `data/training/workflows/{machine_id}/` en JSON, mais ne les écrit pas dans la DB VWB : l'assimilation Léa fonctionne, mais le workflow appris reste hors source SQLAlchemy/VWB (`2026-06-12`, session M2). Deux sources de vérité non synchronisées → la divergence de `WorkingDirectory` dev (cwd=backend) vs DGX (cwd=racine) a causé le bug « 0 workflows servis » (P0-1, 2026-06-09). Contournement POC en place : symlink `data/workflows` → `backend/data/workflows` (sans sudo, réversible). Fragilités : dépendance au cwd, pas d'écriture atomique/validation schéma, 3e store legacy `data/training/workflows`, pont VWB/Léa existant mais non branché automatiquement post-finalize. Cible consolidation : unifier la persistance workflows sur la DB SQLAlchemy existante (source unique, transactions, review/édition VWB, fin des bugs de cwd), avec bascule progressive sous flag pour ne pas casser le POC DGX. | docs/PLAN_MIGRATION_WORKFLOWS_STORE_2026-06-09.md + RESULTAT-P0-DASHBOARD-CORRECTIONS (2026-06-09) + M2 assimilation DGX 2026-06-12 |
| DETTE-016 | 2026-06-10 | 2026-06-24 | P2 | ACCEPTED | Auth agents POC avec `RPA_API_TOKEN` global partagé et `machine_id` auto-déclaré : `_verify_token()` valide le Bearer global et `_guard_agent_registry_access()` vérifie que le `machine_id` déclaré est actif, mais ne prouve pas cryptographiquement que le client est bien ce poste. Risque accepté pour POC contrôlé LAN/non exposé internet ; à reconsidérer avant distribution multi-TIM élargie, exposition réseau non maîtrisée ou exigence de révocation non contournable par poste. WP-C token par poste Patch 1-3 reste local/inerte, Patch 4 runtime annulé pour le POC. | docs/coordination/inbox_codex/2026-06-10_1450_qwen-to-codex-claude-dom_DECISION-WPC-ABANDON-DETTE.md + docs/coordination/active/2026-06-10_1440_anti-doublon-wpc-verdict.md |
| DETTE-017 | 2026-06-12 | 2026-06-12 | P0 | OPEN | Auth Bearer **désactivée** (`RPA_AUTH_DISABLED=true`) sur streaming `5005` ET agent-chat `5004` du DGX, appliquée comme « fix » heartbeat B3 (rustine). Démontré inutile : les 3 tokens (DGX proc, DGX `.env.local`, Windows `.env`) sont identiques (SHA256 `43749362b1`, len 43) → l'auth peut être réactivée sans casser le heartbeat. Exposition `0.0.0.0:5004/5005` restreinte par iptables au seul poste `192.168.1.11` ; dashboard `5001` conserve son auth. **Exception temporaire validée par Dom (2026-06-12 09:35) pour test M2 local sur données factices.** ROLLBACK OBLIGATOIRE avant toute sortie clinique / données patient : `RPA_AUTH_DISABLED=false` dans `.env.local` DGX + `sudo systemctl restart rpa-streaming.service rpa-agent-chat.service` puis vérif (401 sans token / 200 avec / heartbeat maintenu). | docs/coordination/active/2026-06-12_0935_decision-dom-auth-off-exception-m2.md + alerte 2026-06-11_1535 |
| DETTE-018 | 2026-06-13 | 2026-06-27 | P2 | OPEN | Garde-seuil inopérant sur le chemin grounding **legacy** : `_resolve_by_grounding` retourne `method="grounding_vlm"` (resolve_engine.py:1121, mode `RPA_GROUNDING_ENGINE` OFF), clé absente de `_RESOLUTION_MIN_SCORES` qui ne traite en **préfixe** que `memory_` (toutes les autres clés = match exact) → le Check-1 du validateur (seuil min de confiance) ne s'applique jamais à ce chemin. Le mode `qwen3vl_vllm` est lui correctement gardé (`method="grounding"`, clé exacte, seuil 0.60). Aligner le legacy (clé gardée ou renommage) tant que le mode legacy reste activable. | Découvert au câblage qwen3vl (commit 5c5ce747b) + validation E2E 2026-06-13 |
| DETTE-019 | 2026-06-13 | 2026-06-27 | P2 | OPEN | Confiance grounding **figée à `0.85` en dur** dans le `return` de `_resolve_by_grounding` (resolve_engine.py:1128-1130 : `matched_element.confidence` et `score`), pour les DEUX modes (legacy et qwen3vl). Le garde-seuil (0.60) reçoit donc toujours 0.85 quel que soit le grounding réel → le filtre ne discrimine jamais la vraie qualité de localisation. Propager une confiance réelle (signal modèle/cascade) pour rendre le seuil opérant. | Découvert au câblage qwen3vl (commit 5c5ce747b) + validation E2E 2026-06-13 |
| DETTE-020 | 2026-06-25 | 2026-07-09 | P1 | OPEN | **Incidents silencieux — aucune détection/alerte des composants critiques d'inférence.** Un composant critique peut tomber sans alerte : `rpa-vllm-grounder.service` (grounder Qwen3-VL/vLLM) trouvé en **crash-loop (auto-restart, restart counter ×3960)** → le runtime a basculé **silencieusement** sur le fallback `qwen2.5vl:7b-rpa` (Ollama, ~×7 plus lent), avec une latence/contention accrue mais **aucune remontée visible** (ni dashboard, ni log d'alerte). Découvert uniquement par vérif manuelle au runtime (session 2026-06-25). La cause de CE crash (SSL HuggingFace au boot vs cache local — manque `HF_HUB_OFFLINE`) se corrige à part ; la dette ici = **le mode dégradé est silencieux**. Cible : health-check + supervision des composants critiques (grounder vLLM, Ollama, services `rpa-*`) avec **remontée VISIBLE** (dashboard 5001 / log d'alerte / notification) → une bascule en mode dégradé ne doit jamais passer inaperçue. ⚠️ Vérifier d'abord l'existant (module monitoring `:5003`) avant de construire. | session vérif runtime DGX clinique 2026-06-25 |
| DETTE-021 | 2026-06-25 | 2026-07-09 | P1 | OPEN | **Journalisation client Léa non effective.** `LOG_FILE` (`agent_v0/agent_v1/config.py:88` → `<install>/logs/agent_v1.log`) est défini mais **jamais branché** : aucun `FileHandler`/`addHandler` dans tout le client. Seul logging actif = `basicConfig` (`main.py:46`) → **stderr**, perdu car Léa tourne en `pythonw.exe` (sans console). Dossier `logs/` vide. Conséquences : (1) **diagnostic terrain aveugle** — impossible de tracer pourquoi Léa « disparaît » côté poste ; (2) **non-conformité Règlement IA Art. 12** (journalisation + conservation 180 j — citée dans le code mais non effective ; `LOG_RETENTION_DAYS` ne couvre que les *sessions*). Cible : brancher un `RotatingFileHandler`/`TimedRotating` vers `LOG_FILE` (rotation + purge 180 j, niveau INFO). ⚠️ modif client → **redéploiement** (cf. DETTE-022). Pendant client du DETTE-020 (observabilité serveur). | session diagnostic « disparition » Léa poste Émilie 2026-06-25 |
| DETTE-022 | 2026-06-25 | 2026-07-09 | P1 | OPEN | **Pas de mise à jour automatique du client Léa.** Toute modif du client (`agent_v0/agent_v1/**`) impose un **redéploiement manuel poste par poste** (Léa « gelée »). En clinique (5 postes, croissant), intervenir sur chaque poste à chaque correctif (ex. fix logging DETTE-021) **dérange les TIM et décourage l'adoption** (constat Dom). Cible : mécanisme de **MAJ auto / en tâche de fond** (auto-update silencieux, versionné, piloté serveur/dashboard, avec rollback), **zéro intervention sur le poste**. ⚠️ Vérifier d'abord l'existant côté enrôlement Fleet (dashboard build ZIP + token) avant de construire. | décision Dom 2026-06-25 (« on ne peut pas intervenir constamment sur les postes, on va décourager ») |

## Convention de référencement

- Dans les messages de commit : `refs DETTE-NNN` en pied
- Dans le code : `# DETTE-NNN` en commentaire au-dessus de la ligne concernée (pour les contournements localisables)