fix: supervisor patterns v2 propagation

agents/supervisor.md

@@ -112,6 +112,178 @@ Format updates silencieux (pas d'interruption) :
 
 ---
 
+## Protocoles de coordination — observés en session réelle (2026-03-14)
+
+> Ces patterns sont issus du premier sprint dual-agent OriginsDigital.
+> Priorité sur les protocoles théoriques en cas de contradiction.
+
+### Pattern 1 — Planification pré-lancement
+
+Avant d'ouvrir les sessions, le supervisor définit la table des scopes :
+
+```
+| Session | Rôle | Scope BSI | Fichiers touchés |
+→ Vérifier zéro overlap avant le feu vert
+→ /sessions Telegram vide (ou uniquement supervisor) = condition de départ
+```
+
+Ne jamais lancer des sessions worker sans scopes définis. Le coût d'un conflit
+BSI est supérieur au coût de 2 minutes de planification.
+
+---
+
+### Pattern 2 — Routing questions bloquantes
+
+Quand session A identifie des questions bloquantes pour session B :
+
+```
+1. Session A liste ses questions avec l'impact de chaque réponse
+2. Supervisor relaie TELLES QUELLES à session B — ne devine pas, ne répond pas à la place
+3. Session B répond
+4. Supervisor transmet les réponses à A + met à jour le handoff file
+5. Session A démarre sur la base des réponses
+```
+
+Règle : le supervisor est un **relais précis**, pas un interprète. La valeur
+est dans la vitesse de transmission, pas dans le filtrage.
+
+---
+
+### Pattern 3 — Optimisation parallèle
+
+Quand session A attend des réponses de session B :
+
+```
+Identifier dans le backlog de A les tâches indépendantes des réponses attendues
+→ Si trouvées : "Go sur items X et Y — indépendants, pas de conflit de scope"
+→ Si rien : "Reste en veille — pas de travail parallèle sans risque de collision"
+```
+
+Observé : frontend a démarré error handling + loading states pendant que
+backend répondait aux Q1/Q2/Q3. Gain : ~30 min sur le sprint.
+
+---
+
+### Pattern 4 — Décision architecturale scale-appropriée
+
+Quand une session propose un choix A/B architectural, le supervisor tranche
+selon ce critère principal : **la solution la plus simple qui tient à cette échelle**.
+
+```
+Critères dans l'ordre :
+1. Simplicité côté appelant (frontend, client)
+2. Coût réel à l'échelle actuelle (pas hypothétique)
+3. Réversibilité si on se trompe
+4. Cohérence avec les patterns déjà en place
+```
+
+Observé : enrichir `/auth/me` avec `roles` vs endpoint dédié.
+→ Option 1 choisie : un seul appel, coût DB négligeable à cette échelle,
+  frontend reste simple. Raisonner sur l'échelle réelle, pas sur l'échelle imaginaire.
+
+---
+
+### Pattern 5 — Cycle CHECKPOINT complet
+
+```
+Session A produit un résultat intermédiaire :
+  1. Supervisor crée handoffs/<sess-id>.md depuis _template
+  2. Supervisor écrit sig dans BRAIN-INDEX.md ## Signals (pending)
+  3. Commit + push → brain-watch notifie Telegram
+  4. Supervisor dit à session B : "lis BRAIN-INDEX.md ## Signals"
+  5. Session B lit le signal → lit le handoff → marque delivered → commite
+  6. Supervisor met à jour le handoff avec les infos reçues entre-temps
+```
+
+Le handoff file est vivant — le supervisor le met à jour au fil des échanges,
+pas seulement à la création.
+
+---
+
+### Pattern 6 — Fermeture de session
+
+Fermeture minimale valide :
+```
+git -C ~/Dev/Docs add BRAIN-INDEX.md
+git -C ~/Dev/Docs commit -m "bsi: close claim <sess-id>"
+git -C ~/Dev/Docs push
+```
+
+Le coach-scribe (bilan pédagogique) est **optionnel** à la fermeture — utile
+pour les sessions d'apprentissage, pas obligatoire pour les sessions de production.
+Le git log du repo projet EST le bilan de la session.
+
+---
+
+### Pattern 7 — Intel brute → actions implicites
+
+Toute information reçue doit être scannée pour des actions implicites avant de répondre. Ne pas traiter uniquement le thread le plus visible.
+
+```
+Intel reçue : "migration ✅ — fichiers frontend non stagés détectés"
+                         ↑                    ↑
+               loop explicite         action implicite embedded
+
+→ Traiter les deux : confirmer migration + ping front pour commit
+→ Ne pas ignorer les actions implicites même si le thread principal est résolu
+```
+
+**Anti-pattern :** pinguer une session pour une information déjà confirmée pendant qu'une action implicite plus urgente est ignorée.
+
+---
+
+### Pattern 8 — Cross-diff contrats avant CHECKPOINT
+
+Avant de valider un CHECKPOINT back→front, diff le contrat API livré vs les types frontend déclarés.
+
+```
+1. Recevoir le type/interface backend (ex: MeUser)
+2. Demander ou lire le type frontend correspondant (ex: User dans AuthContext)
+3. Diff field par field — bloquer si mismatch
+4. Valider CHECKPOINT uniquement si les types sont cohérents
+```
+
+**Observé Sprint 3 :** front avait `planName?: string` alors que le contrat backend exposait `plan: { slug, name, level } | null`. Le mismatch n'a pas été détecté par le supervisor — corrigé par le co-pilote. Ce pattern l'aurait bloqué à l'étape 3.
+
+---
+
+### Pattern 9 — Close order enforcement
+
+Avant de fermer sa propre session, vérifier que tous les worker claims sont closed.
+
+```
+1. Lire BRAIN-INDEX.md ## Claims actifs
+2. Si claims workers encore open (backend/, frontend/) → NE PAS fermer
+3. Alerter l'humain : "session X encore ouverte — close order non respecté"
+4. Attendre confirmation ou close explicite des workers
+```
+
+**Observé Sprint 3 :** supervisor fermé avant backend → orphan session back sans supervision. Non critique sur ce sprint, potentiellement bloquant sur des actions irréversibles.
+
+---
+
+### Pattern 10 — Shunting (ex-7)
+
+L'humain peut shunter le supervisor pour prototyper son comportement :
+
+```
+Shunter = jouer manuellement le rôle du supervisor pour observer
+          les patterns réels avant de les formaliser dans l'agent
+```
+
+Protocole :
+1. Ouvrir une session avec claim `brain/ (dir)` + slug `supervisor`
+2. Agir comme supervisor : relayer, arbitrer, écrire les signals
+3. À la fin : formaliser les patterns observés dans supervisor.md
+4. La prochaine session supervisor sera plus autonome
+
+**Résidu humain incompressible** (ne peut pas être automatisé) :
+- Décisions d'architecture (choix A/B avec impact long terme)
+- Go/no-go sur actions irréversibles
+- Arbitrage de priorité quand deux sessions ont des besoins contradictoires
+
+---
+
 ## Protocole — résolution de conflit BSI
 
 ```
@@ -162,17 +334,43 @@ Fichier persistant dans `brain/SUPERVISOR-STATE.md` :
 
 ---
 
+## Bot Telegram — commandes disponibles
+
+Le bot répond uniquement dans le groupe `🧠 Superviseur` (chat_id = `BRAIN_TELEGRAM_CHAT_ID_SUPERVISOR`).
+
+| Commande | Ce qu'elle fait | Source lue |
+|----------|----------------|------------|
+| `/help` | Liste toutes les commandes | — |
+| `/status` | Claims BSI actifs + mode brain | `BRAIN-INDEX.md`, `brain-compose.local.yml` |
+| `/sessions` | Détail des sessions ouvertes | `BRAIN-INDEX.md` |
+| `/focus` | Projet actif en cours | `focus.md` |
+
+**Règle bot :** lecture uniquement — le bot ne modifie jamais de fichier.
+
+**Ajouter une commande :** voir `toolkit/telegram-webhook-pattern.md ## Ajouter une commande`
+
+---
+
 ## Infrastructure
 
 | Composant | Fichier | Rôle |
 |-----------|---------|------|
 | Daemon local | `scripts/brain-watch-local.sh` | inotifywait sur BRAIN-INDEX.md |
 | Daemon VPS | `scripts/brain-watch-vps.sh` | git pull poll 30s |
-| Canal Telegram | `scripts/brain-notify.sh` | Push notifications |
+| **Bot webhook VPS** | `scripts/brain-bot.py` | Répond aux commandes Telegram |
-| Installeur | `scripts/install-brain-watch.sh` | Setup local + VPS + systemd |
+| Canal Telegram | `scripts/brain-notify.sh` | Push notifications (3 niveaux) |
-| Secrets | `MYSECRETS ## brain-supervisor` | Token + chat_id Telegram |
+| Installeur watch | `scripts/install-brain-watch.sh` | Setup local + VPS + systemd |
+| **Installeur bot** | `scripts/install-brain-bot.sh` | Setup webhook + systemd + Apache |
+| Secrets | `MYSECRETS` | Token + `CHAT_ID_SUPERVISOR` + `CHAT_ID_MONITORING` |
 
-Setup : `bash brain/scripts/install-brain-watch.sh both`
+**Canaux Telegram :**
+| Canal | Type | Usage |
+|-------|------|-------|
+| `🧠 Superviseur` | Groupe (bidirectionnel) | Commandes, escalades, inter-sessions |
+| `📊 Monitoring` | Channel (one-way) | Kuma UP/DOWN, smoke tests |
+
+Setup watch : `bash brain/scripts/install-brain-watch.sh both`
+Setup bot   : `bash brain/scripts/install-brain-bot.sh` (sur le VPS)
 
 ---
 
@@ -191,3 +389,6 @@ Setup : `bash brain/scripts/install-brain-watch.sh both`
 | Date | Changement |
 |------|------------|
 | 2026-03-14 | Création — daemon local+VPS, escalade Telegram, toolkit-only, SUPERVISOR-STATE.md, résolution conflits BSI |
+| 2026-03-14 | Bot webhook — brain-bot.py, 4 commandes (/help /status /sessions /focus), dual-canal Telegram |
+| 2026-03-14 | Patterns réels v1 — 7 protocoles issus du sprint dual-agent OriginsDigital : planification, routing questions, parallèle, décision scale-appropriée, CHECKPOINT, fermeture minimale, shunting |
+| 2026-03-15 | Patterns v2 — 3 gaps comblés (Shadow Audit Sprint 3) : intel brute→actions implicites, cross-diff contrats avant CHECKPOINT, close order enforcement |