# QW Suite Mai 2026 — Synthèse de livraison

Sprint d'amélioration RPA Vision V3, branche `feature/qw-suite-mai`,
inspiré par exploration comparative de 5 frameworks computer-use
(Simular Agent-S, browser-use, OpenAI CUA, Coasty, Showlab OOTB).

## Trois quick wins livrés

- **QW1 — Multi-écrans** : capture/grounding par `monitor_index` avec fallbacks
  focus actif puis composite. Backward 100% sur workflows existants.
  Ajoute `screeninfo>=0.8` aux dépendances Agent V1.
- **QW2 — LoopDetector composite** : détection passive de stagnation via
  3 signaux (CLIP screen_static + action_repeat + retry_threshold).
  Bascule en `paused_need_help` automatique.
- **QW4 — Safety checks hybrides** : `pause_for_human` enrichi de checks
  déclaratifs (workflow) + LLM contextuels (`medgemma:4b` local, timeout 5s,
  fallback safe). UX VWB avec ChecklistPanel acquittable + audit trail.

## Kill-switches en cas de problème

```bash
sudo systemctl edit rpa-streaming
# Ajouter sous [Service] :
Environment=RPA_LOOP_DETECTOR_ENABLED=0
Environment=RPA_SAFETY_CHECKS_LLM_ENABLED=0
sudo systemctl restart rpa-streaming
```

Rollback complet : `git checkout backup/pre-qw-suite-mai-2026-05-05`.

## Variables d'environnement utiles

| Variable | Défaut | Effet |
|---|---|---|
| `RPA_LOOP_DETECTOR_ENABLED` | `1` | Kill-switch QW2 (composite) |
| `RPA_LOOP_SCREEN_STATIC_THRESHOLD` | `0.99` | Seuil similarité CLIP |
| `RPA_LOOP_SCREEN_STATIC_N` | `4` | Nb captures consécutives |
| `RPA_LOOP_ACTION_REPEAT_N` | `3` | Nb actions identiques |
| `RPA_LOOP_RETRY_THRESHOLD` | `3` | Nb retries cumulés |
| `RPA_SAFETY_CHECKS_LLM_ENABLED` | `1` | Kill-switch QW4 LLM contextuel |
| `RPA_SAFETY_CHECKS_LLM_MODEL` | `medgemma:4b` | Modèle Ollama |
| `RPA_SAFETY_CHECKS_LLM_TIMEOUT_S` | `5` | Timeout dur (secondes) |
| `RPA_SAFETY_CHECKS_LLM_MAX_CHECKS` | `3` | Max checks LLM ajoutés |

## Smoke tests manuels à effectuer avant la démo GHT

Ces tests demandent une interaction VWB et un Agent V1 actif — non automatisables.

1. **QW1 multi-écrans** : rejouer un workflow Easily Assure validé. Vérifier
   logs `[BUS] lea:monitor_routed` dans `journalctl -u rpa-streaming`. Le clic
   doit atterrir au bon endroit même sur un poste à 2 écrans.
2. **QW2 LoopDetector** : optionnel, difficile à reproduire fiable. Si tu
   constates un bouclage en démo, vérifier que `paused_need_help` se déclenche
   automatiquement avec `pause_reason="loop_detected"`.
3. **QW4 safety_checks** :
   - Workflow ancien sans `safety_checks` → bulle simple legacy s'affiche
   - Workflow avec `safety_checks` déclaratifs → ChecklistPanel s'affiche,
     bouton Continuer désactivé tant que required non cochés
   - Workflow `safety_level: medical_critical` → checks LLM ajoutés en
     plus (badge `[Léa]`), apparaissent dans les 5s
   - POST `/api/v3/replay/resume` sans required acquitté → 400 toast UI

## Tests automatisés (référence)

```
.venv/bin/pytest tests/unit/test_monitor_router.py \
                 tests/integration/test_grounding_offset.py \
                 tests/unit/test_loop_detector.py \
                 tests/integration/test_loop_detector_replay.py \
                 tests/unit/test_safety_checks_provider.py \
                 tests/integration/test_replay_resume_acknowledgments.py \
                 -v
```

Référence : 24 tests QW + 89 baseline = 113 passed.

## Référence design

`docs/superpowers/specs/2026-05-05-qw-suite-mai-design.md`

## Référence plan d'exécution

`docs/superpowers/plans/2026-05-05-qw-suite-mai.md`

## Backup

Branche backup poussée Gitea avant le sprint :
`backup/pre-qw-suite-mai-2026-05-05` + tag `backup-pre-qw-suite-mai-2026-05-05`.

## Statut au 2026-05-05

| Composant | État | Smoke démo nécessaire |
|---|---|---|
| QW1 monitor_router + offsets | Livré, tests verts | Oui (multi-écran physique) |
| QW1 enrichissement Agent V1 | Livré, fallback gracieux si screeninfo absent | Oui (Windows réel) |
| QW1 hook serveur + cablage executor | Livré (commit fix fc01afa59) | Oui |
| QW2 LoopDetector module | Livré, tests verts | Non (impossible à reproduire fiable) |
| QW2 hook api_stream | Livré, tests verts | Non |
| QW4 SafetyChecksProvider | Livré, tests verts | Oui (avec workflow `medical_critical`) |
| QW4 endpoint /replay/resume + proxy VWB | Livré, tests verts | Oui (POST avec acknowledged_check_ids) |
| QW4 PauseDialog + PropertiesPanel | Livré, 0 nouvelle erreur TS | Oui (rendre la bulle dans VWB) |