docs: Project Memory Extraction (5 Layers: Constitution, Primer, Lessons, Hindsight, Audits)

.claude/CLAUDE.md

@@ -3,18 +3,8 @@
 ## 🛡️ Principes Fondamentaux (Audit & Architecture)
 
 1. **Atomicité Absolue** : Ne jamais envoyer de message WhatsApp (ou `scheduleMessage`) avant d'avoir validé la mise à jour de la base de données (Prisma). La donnée doit survivre à un crash du worker.
-2. **Détachement Gateway (Async-First)** : Le point d'entrée `/webhook` doit répondre `200 OK` immédiatement (< 100ms) sans attendre le traitement. Tout travail lourd est délégué au `whatsapp-worker`.
+2. **Détachement Gateway (Async-First)** : Le point d'entrée `/webhook` doit répondre `200 OK` immédiatement (< 100ms) sans attendre le traitement.
 3. **Idempotence Système** : Chaque job (Inbound, Feedback, Media) doit être verrouillé par Redis avec un TTL de 300s (5 min) pour absorber les temps de latence LLM sans créer de doublons.
-4. **UX d'Interception & "WOW"** : Le design et la validation visuelle (ex: Jour 11, Pitch Cards) sont prioritaires. Ne pas utiliser de placeholders ; générer des images réelles.
-
-## 🛠️ Workflows de Développement
-
-- **Évolution de Schéma** : Toute modification des types (ex: `BusinessProfile`) doit être répercutée dans Prisma et migrée immédiatement.
-- **Gestion des Erreurs** : En cas de timeout ou 429 (LLM), envoyer un message de fallback gracieux à l'utilisateur au lieu de laisser le job échouer silencieusement.
-- **Validation de Progression** : Toujours vérifier si une `Response` existe avant de bloquer un utilisateur avec le statut `PENDING`.
-
-## 🚦 Ordre de Session Stricte
-
-1. **LIRE** `tasks/lessons.md` au démarrage de chaque tâche.
-2. **METTRE À JOUR** `tasks/todo.md` après chaque succès.
-3. **AUTO-CORRIGER** `tasks/lessons.md` dès qu'un bug est identifié et résolu.
+4. **UX d'Interception & "WOW"** : Le design et la validation visuelle (ex: Jour 11) sont prioritaires. Ne pas utiliser de placeholders.
+5. **Instruction pour Agents (Flash/Large Context)** : Si tu es utilisé par Gemini Flash ou un agent à large fenêtre de contexte, lis prioritairement `tasks/hindsight.md` pour comprendre la philosophie des prompts de l'utilisateur avant de suggérer une modification structurelle.
+6. **Vérification Lesson-First** : Ne jamais modifier la logique de progression sans valider contre les échecs répertoriés dans `tasks/lessons.md`.

.claude/primer.md

@@ -1,18 +1,22 @@
 # 🧪 Primer Technique : Architecture XAMLÉ
 
+## 🏗️ Profil du Projet
+- **Nom du Secteur** : PWA Événementiel Sénégal (Mise en relation et Coaching de prestataires).
+- **Enjeux** : Digitalisation du secteur informel sénégalais par WhatsApp.
+- **Preuves de Confiance** : Lauréat **Blue Ocean Awards** (Expertise reconnue en innovation).
+
+## 💰 Business Model
+- **Commission Client** : 1% sur le montant de la prestation.
+- **Commission Prestataire** : 2% sur le montant encaissé.
+- **Validation** : Le coaching AI (XAMLÉ) assure la qualité des prestataires avant mise en relation.
+
 ## 🏗️ Flux de Données (Data Flow)
-1. **Meta Webhook** (Public) -> **API Fastify** (Gateway).
-2. **API Gate** -> Réponse 200 immédiate -> Queue **BullMQ** (Redis).
-3. **Worker** -> `whatsapp-logic.ts` -> **Gemini/OpenAI** -> **Prisma DB** -> **WhatsApp Cloud API**.
+1. **Meta Webhook** -> **API Fastify** -> Réponse 200 immédiate.
+2. **Queue BullMQ** -> **Worker** -> **whatsapp-logic.ts**.
+3. **IA (Gemini/OpenAI)** -> **Prisma DB** -> **WhatsApp Cloud API**.
 
 ## 🛠️ Stack Technologique
-- **Back** : Node.js (TypeScript), Fastify.
-- **Processing** : BullMQ (Jobs persistants), Redis.
-- **Persistance** : Prisma ORM (SQL).
-- **IA** : Gemini 2.0 Flash (Primary), OpenAI Whisper (STT) + GPT-4 (Fallback).
-- **Storage** : Cloudflare R2 / AWS S3 pour l'archivage audio/image.
-
-## 🚦 Sécurité & Performance
-- HMAC Signature (X-Hub-Signature-256) vérifiée sur l'API.
-- Logs Railway pour le monitoring du worker.
-- Locks distribués Redis pour l'idempotence.
+- **Back** : Node.js (TypeScript), Fastify, BullMQ, Redis.
+- **Persistance** : Prisma ORM (Azure Neon PostgreSQL).
+- **IA** : Gemini 2.0 Flash (Coaching), Gemini 1.5 Pro (Docs), OpenAI Whisper (STT).
+- **Storage** : Cloudflare R2 (Audio/Images persistants).

tasks/hindsight.md

@@ -0,0 +1,19 @@
+# 🧠 Hindsight : Trace des Mandats Structurels
+
+Ce fichier archive les prompts "Directeurs" qui ont forgé l'architecture actuelle. Ils servent de référence pour comprendre la philosophie de l'utilisateur.
+
+## 1. Mandat : "Vision & Data Diversity" (23 Mars 2026)
+> "Tu agis en tant que Lead QA. Nous avons une régression majeure : l'IA répète les mêmes conseils sur la publicité. Tu dois dynamiser la recherche web (Browsing) selon le jour du programme et activer la vision multimodale pour analyser les preuves envoyées par les utilisateurs."
+- **Résultat** : Implémentation du `SearchService` adaptatif et du `GeminiProvider` multimodal.
+
+## 2. Mandat : "Intelligence de Dialogue" (24 Mars 2026)
+> "Tu es un consultant pragmatique, pas un professeur pointilleux. Rédige un feedback d'au minimum 15 lignes de haute densité. Interdiction de demander à l'utilisateur de s'expliquer davantage si l'idée est claire. Apporte le savoir."
+- **Résultat** : Injection de la règle "Anti-Remediation Loop" dans `AIService`.
+
+## 3. Mandat : "Asynchronisme Total & Détachement" (24 Mars 2026)
+> "Le problème n'est pas l'IA, mais le Timeout de la Gateway Hugging Face. Détache-toi immédiatement en répondant 200 OK. Délègue tout au worker."
+- **Résultat** : Architecture Async-First, suppression de `WhatsAppService` synchrone, création de `whatsapp-logic.ts`.
+
+## 4. Mandat : "Constitution & Mémoire du Projet" (24 Mars 2026)
+> "Tu agis en tant que Lead DevOps & Knowledge Manager. Transforme l'historique de tes interventions en une base de connaissances pérenne. Archive le processus de réparation."
+- **Résultat** : Création de `.claude/CLAUDE.md`, `tasks/lessons.md`, `tasks/hindsight.md` et `docs/audits/`.

tasks/lessons.md

@@ -1,7 +1,21 @@
-# 🎓 Leçons Apprises (Post-Mortem & Best Practices)
+# 🎓 Leçons Apprises (Historique des Crashs & Fixes)
 
-- **[ARCHI] Détachement Gateway** : Ne JAMAIS laisser Hugging Face (ou toute gateway) attendre > 20s. Répondre `200 OK` immédiatement et déléguer au worker.
-- **[DB] Séquençage des Opérations** : Ne JAMAIS envoyer de message WhatsApp avant d'avoir persisté la progression dans Prisma. La DB est la seule source de vérité.
-- **[CACHING] Verrous d'Idempotence** : Utiliser des locks Redis avec un TTL minimal de 300s (5 min) pour protéger les appels LLM longs et éviter les retries en boucle.
-- **[STT] Normalisation** : La transcription audio (Whisper) nécessite une phase de normalisation Wolof pour assurer la qualité du feedback pédagogique.
-- **[MEDIA] Non-bloquant** : FFMPEG (conversion MP3) doit tourner dans un sous-processus asynchrone pour ne pas saturer l'event loop du worker.
+## 1. Race Condition : Atomicité DB First
+- **Crash** : L'utilisateur recevait un message de félicitations "Bravo Jour 1" mais restait bloqué à cause d'un crash du worker survenu *après* l'envoi WhatsApp mais *avant* le `prisma.update`.
+- **Leçon** : L'ordre des opérations est vital. Toujours effectuer les écritures DB (`UserProgress`, `Response`) **AVANT** d'appeler un service tiers (WhatsApp API).
+- **Audit de preuve** : [audit_persistance_validation.md](../docs/audits/audit_persistance_validation.md)
+
+## 2. Gemini 404 : Mapping des Modèles
+- **Crash** : Plusieurs appels échouaient avec une erreur 404 car le modèle `gemini-1.5-pro-latest` ou `gemini-2.0-flash-exp` n'était pas supporté ou changeait d'alias.
+- **Leçon** : Utiliser des constantes de mapping explicites. Actuellement : `gemini-2.0-flash` pour le coaching rapide et `gemini-1.5-pro` pour le rendu de documents complexes.
+- **Audit de preuve** : [rapport_audit_vision_data.md](../docs/audits/rapport_audit_vision_data.md)
+
+## 3. Timeout Gateway Hugging Face : Async-First
+- **Crash** : Hugging Face (Gateway) coupe la connexion si le serveur ne répond pas en < 30s. Les LLMs (STT + Feedback) mettent souvent 35s. Résultat : retries infinis de Meta et doublons.
+- **Leçon** : Répondre `200 OK` immédiatement à la Gateway (< 100ms). Utiliser `setImmediate` ou une Queue (BullMQ) pour détacher le traitement long du cycle de vie HTTP.
+- **Audit de preuve** : [audit_progression_idempotence.md](../docs/audits/audit_progression_idempotence.md)
+
+## 4. Multimodal : Vision par Base64
+- **Crash** : Gemini échouait à "voir" les images si on passait seulement l'URL (problèmes de permissions ou d'expiration).
+- **Leçon** : Toujours télécharger le média sur le serveur, le convertir en **Base64** et l'injecter en `inlineData` dans le prompt multimodal.
+- **Audit de preuve** : [audit_team_visual_persistence.md](../docs/audits/audit_team_visual_persistence.md)