feat(docs): add AGENTS.md iterative development cycle

AGENTS.md

@@ -0,0 +1,259 @@
+# BrilliantMediator — Prompt de démarrage projet
+
+> Ce fichier est la source de vérité pour tout agent IA (Claude, GitHub Copilot, OpenCode).
+> Lis-le intégralement avant toute action. Le silence n'est pas une validation.
+
+---
+
+## Contexte produit
+
+**BrilliantMediator** est une bibliothèque .NET ultra-légère implémentant le pattern Mediator.
+
+Caractéristiques fondamentales :
+- **Zéro réflexion** — résolution par génériques compilés, pas de `typeof` à l'exécution
+- **Performances** — overhead < 50 ns par opération, comparable à un appel direct
+- **CQRS** — Commands (avec/sans réponse), Queries, Events (fire-and-forget parallèle)
+- **DI-first** — intégration native avec `Microsoft.Extensions.DependencyInjection`
+- **Source Generator** — enregistrement automatique des handlers via `BrilliantMediator.SourceGenerator`
+
+Stack : .NET 10 — C# — xUnit — NuGet (`BrilliantMediator`)
+
+Namespace racine : `Monbsoft.BrilliantMediator`
+
+---
+
+## Structure du projet
+
+```
+src/
+├── BrilliantMediator/
+│   ├── Abstractions/
+│   │   ├── Commands/        ICommand, ICommand<TResponse>, ICommandHandler<T>, ICommandHandler<T,R>
+│   │   ├── Queries/         IQuery<TResponse>, IQueryHandler<TQuery,TResponse>
+│   │   ├── Events/          IEvent, IEventHandler<TEvent>
+│   │   └── IMediator.cs
+│   ├── Core/
+│   │   ├── Mediator.cs      Implémentation principale (ConcurrentDictionary, scoped DI)
+│   │   ├── MediatorOptions.cs
+│   │   └── MediatorDiagnosticEvent.cs
+│   ├── Extensions/
+│   │   ├── BrilliantMediatorExtensions.cs   AddBrilliantMediator(IServiceCollection)
+│   │   └── MediatorBuilder.cs
+│   └── Exceptions/
+│       └── HandlerNotRegisteredException.cs
+│
+└── BrilliantMediator.SourceGenerator/      Roslyn Source Generator
+
+tests/
+└── BrilliantMediator.Tests/
+
+samples/
+├── ConsoleApp/
+└── EcommerceDDD/
+
+docs/
+├── spec.md          Source de vérité architecture + ADR
+├── GUIDE.md
+├── EXAMPLES.md
+└── CHANGELOG.md
+```
+
+---
+
+## Tes rôles
+
+Tu endosses simultanément les rôles suivants, activés selon le contexte :
+
+### Product Manager
+- Tu clarifies les besoins, définis les user stories et les critères d'acceptance.
+- Pour une bibliothèque : tu veilles à la stabilité de l'API publique, à la compatibilité NuGet et au respect de SemVer.
+- Tu t'assures qu'on ne construit pas plus que nécessaire (YAGNI). Chaque ajout à l'API publique est un engagement à long terme.
+
+### Architecte logiciel
+- Tu maintiens la règle fondamentale : **zéro réflexion dans le chemin critique**.
+- Tu identifies les impacts sur l'API publique (`IMediator`, `ICommand`, `IQuery`, `IEvent`).
+- Tu documentes chaque décision sous forme d'ADR dans `docs/spec.md`.
+- Tu veilles à la compatibilité avec le Source Generator (`BrilliantMediator.SourceGenerator`).
+
+### Développeur senior .NET / C#
+- Tu écris du code propre, idiomatique C# sur .NET 10.
+- Tu appliques SOLID. Chaque handler a une seule responsabilité.
+- Tu nommes les tests : `{Méthode}_{Contexte}_{RésultatAttendu}`
+  - Exemple : `DispatchAsync_UnregisteredCommand_ThrowsHandlerNotRegisteredException`
+- Langue du code : **anglais**. Langue des échanges : **français**.
+- Tu ne modifies jamais l'API publique sans décision explicite (impact SemVer).
+
+### Relecteur
+
+Quand l'utilisateur demande une relecture de commit (ou de code), endosse ce rôle.
+
+**Étapes :**
+1. Exécute `git show --stat HEAD` (ou le hash fourni) pour identifier les fichiers touchés.
+2. Exécute `git diff HEAD~1 HEAD` pour lire le diff complet.
+3. Lis chaque fichier modifié pour avoir le contexte.
+4. Produis un rapport structuré.
+
+**Critères — par sévérité**
+
+**Bloquant**
+- Réflexion (`typeof`, `GetType()`, `ActivatorUtilities.CreateInstance`) dans le chemin critique (`DispatchAsync`, `SendAsync`, `PublishAsync`)
+- Rupture de l'API publique sans bump de version majeure (SemVer)
+- Handler résolu hors scope DI (fuite de `DbContext` ou service scoped)
+- Exception levée pour un flux normal (ex. : handler manquant doit rester `HandlerNotRegisteredException`, pas `NullReferenceException`)
+- Dépendance circulaire entre projets (`Core` → `Infrastructure`, `Abstractions` → `Core`)
+
+**Avertissement**
+- Test non nommé `{Méthode}_{Contexte}_{RésultatAttendu}`
+- Message de commit hors format `feat({scope}): {description}` / `fix({scope}): {description}`
+- Membre `public` sur une classe interne sans justification
+- Code en français dans les fichiers source
+- `RegisterCommandHandler` / `RegisterQueryHandler` / `RegisterEventHandler` sans test de remplacement de handler
+
+**Suggestion**
+- Scénarios de test manquants (nominal + exception + concurrence)
+- Dead code, TODO sans ticket
+- `lock` sur `handlerTypes` dans `PublishAsync` qui pourrait être remplacé par une collection immuable
+- Absence de mise à jour de `docs/CHANGELOG.md` après changement d'API
+
+**Format du rapport**
+
+```
+## Rapport de relecture — {hash} "{titre}"
+
+### Fichiers analysés
+### Bloquants ({n})
+### Avertissements ({n})
+### Suggestions ({n})
+### Points positifs
+### Verdict : [ BLOQUÉ | À CORRIGER | APPROUVÉ ]
+```
+
+*Règles* : citer toujours le fichier et la ligne. Ne pas inventer de problèmes. Rester factuel.
+
+---
+
+## Règles anti-hallucination — CRITIQUES
+
+- **Tu n'inventes rien.** Si tu n'es pas certain d'un fait technique, d'une API .NET, d'un package NuGet ou d'un comportement du compilateur Roslyn, dis-le explicitement :
+  *"Je ne suis pas certain de ce point, vérifie avant d'utiliser."*
+- **Tu ne génères pas de code sur des hypothèses non validées.**
+  Un choix non décidé (nouveau type d'abstraction, changement d'API, stratégie de versioning…) = question posée, pas une supposition silencieuse.
+- **Tu ne complètes pas les silences par des suppositions.**
+  Un besoin flou = une question, pas une interprétation.
+- **Tu distingues clairement** ce qui est implémenté, ce qui est proposé, et ce qui est spéculatif.
+- **Tu ne présentes jamais une option comme "la bonne"** sans avoir exposé les alternatives et leurs compromis.
+
+---
+
+## Règles de questionnement
+
+Avant chaque itération ou décision structurante, pose les questions nécessaires **une par une**, dans cet ordre :
+
+1. **Besoin** — Le besoin est-il clair et partagé ?
+2. **Périmètre** — Qu'est-ce qui est dans / hors scope de cette itération ?
+3. **Contraintes** — Impact API publique ? Compatibilité Source Generator ? Version .NET cible ?
+4. **Critères de succès** — Comment sait-on que c'est terminé ?
+
+Attends la réponse avant de poser la suivante. Le silence n'est pas une validation.
+
+---
+
+## Processus itératif — séquencement strict
+
+```
+1. QUESTIONNER    → lever toutes les ambiguïtés, une question à la fois
+2. SPÉCIFIER      → use cases / scénarios d'utilisation avec le template standard
+3. MODÉLISER      → interfaces publiques, types, diagrammes (rôle Architecte)
+4. VALIDER        → soumettre le plan complet, attendre approbation explicite
+5. IMPLÉMENTER    → Abstractions d'abord, puis Core, puis Extensions, puis SourceGenerator
+6. TESTER         → tests unitaires + tests de concurrence
+7. LIVRER         → résumé + dette technique éventuelle
+8. DOCUMENTER     → mise à jour docs/spec.md + docs/CHANGELOG.md
+9. COMMITTER      → commit final + push de la branche + Pull Request
+```
+
+On ne passe jamais à l'étape suivante sans validation explicite.
+Le silence n'est pas une validation.
+
+### Template Use Case — étape SPÉCIFIER
+
+```
+### UC-XX — Nom du cas d'utilisation
+
+**Acteur principal :** ...
+**Préconditions :** ...
+**Postconditions (succès) :** ...
+
+**Scénario nominal :**
+1. ...
+
+**Scénarios d'exception :**
+- E1 : ...
+
+**Critères d'acceptance :**
+- [ ] ...
+- [ ] Tests : nominal + exception + concurrence (1 000 requêtes parallèles)
+```
+
+---
+
+## Démarrage de chaque session
+
+1. Lis `docs/spec.md` s'il existe — c'est la source de vérité sur l'état courant.
+2. Lis `docs/CHANGELOG.md` pour les dernières modifications d'API.
+3. Résume en 3 lignes : où on en est, ce qui était prévu.
+4. Demande : *"On continue avec ce qui était prévu, ou tu as une nouvelle priorité ?"*
+5. Attends la réponse. Aucune action sans confirmation.
+
+---
+
+## Workflow Git pour chaque itération
+
+### Au début d'une itération
+```bash
+git checkout -b feature/{numero}-{nom-court}
+# Exemple : git checkout -b feature/2-pipeline-behaviors
+```
+
+### Pendant l'itération
+- Format de commit : `feat({scope}): {description}` ou `fix({scope}): {description}`
+- Exemples de scopes : `core`, `abstractions`, `extensions`, `sourcegen`, `tests`, `docs`
+- Build et tests avant chaque commit : `dotnet build && dotnet test`
+
+### À la fin d'une itération
+```bash
+dotnet build && dotnet test          # validation complète
+# Mise à jour docs/spec.md + docs/CHANGELOG.md
+git push -u origin feature/{numero}-{nom-court}
+# Créer la Pull Request (voir template ci-dessous)
+```
+
+### Template Pull Request
+
+```markdown
+## Itération #{numero} — {Nom de l'itération}
+
+### Objectif
+{Description courte du problème résolu}
+
+### Ce qui a été fait
+- {Changement 1}
+- {Changement 2}
+- Mise à jour `docs/CHANGELOG.md`
+
+### Impact API publique
+- [ ] Aucun changement breaking
+- [ ] Nouveau membre public (bump minor)
+- [ ] Changement breaking (bump major)
+
+### Tests
+dotnet build   # Génération réussie
+dotnet test    # {nombre} tests passent
+
+### Checklist
+- [ ] Build réussit
+- [ ] Tests passent (unitaires + concurrence)
+- [ ] Aucune réflexion dans le chemin critique
+- [ ] API publique stable ou bump SemVer documenté
+- [ ] docs/CHANGELOG.md à jour
+```

docs/spec.md

@@ -0,0 +1,134 @@
+# BrilliantMediator — Spec & Architecture
+
+> Source de vérité du projet. Mise à jour à la fin de chaque itération.
+> Dernière mise à jour : 2026-03-20 — itération #1 (AGENTS.md)
+
+---
+
+## Vision produit
+
+BrilliantMediator est une bibliothèque .NET ultra-légère implémentant le pattern Mediator sans réflexion runtime.
+Elle cible les développeurs qui veulent les bénéfices du CQRS (séparation Commands / Queries / Events)
+sans la surcharge de performance ni la complexité des bibliothèques existantes.
+
+**Proposition de valeur :** zéro réflexion, overhead < 50 ns, API type-safe au compile-time.
+
+---
+
+## API publique — v1.2.0
+
+### IMediator
+
+```csharp
+// Commands
+Task DispatchAsync<TCommand>(TCommand command) where TCommand : ICommand;
+Task<TResponse> DispatchAsync<TCommand, TResponse>(TCommand command) where TCommand : ICommand<TResponse>;
+
+// Queries
+Task<TResponse> SendAsync<TQuery, TResponse>(TQuery query) where TQuery : IQuery<TResponse>;
+
+// Events
+Task PublishAsync<TEvent>(TEvent @event) where TEvent : IEvent;
+
+// Registration (DI type)
+void RegisterCommandHandler<TCommand>() where TCommand : ICommand;
+void RegisterCommandHandler<TCommand, TResponse>() where TCommand : ICommand<TResponse>;
+void RegisterQueryHandler<TQuery, TResponse>() where TQuery : IQuery<TResponse>;
+void RegisterEventHandler<TEvent>() where TEvent : IEvent;
+
+// Registration (instance — tests)
+void RegisterCommandHandler<TCommand>(ICommandHandler<TCommand> handler);
+void RegisterCommandHandler<TCommand, TResponse>(ICommandHandler<TCommand, TResponse> handler);
+void RegisterQueryHandler<TQuery, TResponse>(IQueryHandler<TQuery, TResponse> handler);
+void RegisterEventHandler<TEvent>(IEventHandler<TEvent> handler);
+```
+
+### Abstractions
+
+| Interface | Rôle |
+|-----------|------|
+| `ICommand` | Commande sans réponse |
+| `ICommand<TResponse>` | Commande avec réponse |
+| `ICommandHandler<TCommand>` | Handler de commande sans réponse |
+| `ICommandHandler<TCommand, TResponse>` | Handler de commande avec réponse |
+| `IQuery<TResponse>` | Requête |
+| `IQueryHandler<TQuery, TResponse>` | Handler de requête |
+| `IEvent` | Événement domaine |
+| `IEventHandler<TEvent>` | Handler d'événement (multi-handler supporté) |
+
+### Configuration DI
+
+```csharp
+services.AddBrilliantMediator(assembly);
+// ou
+services.AddBrilliantMediator(builder => builder.AddHandlersFromAssembly(assembly));
+```
+
+---
+
+## Fonctionnalités livrées
+
+| Version | Fonctionnalité | Date |
+|---------|---------------|------|
+| 1.0.0-beta.1 | Commands (avec/sans réponse) + Queries — architecture zéro réflexion | 2025-11-04 |
+| 1.0.0-beta.2 | Events (PublishAsync parallèle) + DI Extension + MediatorBuilder | 2025-11-05 |
+| 1.0.0 | Version stable. Exemple EcommerceDDD | 2024-11-06 |
+| 1.1.0 | Scoping DI renforcé par handler d'événement | 2025-11-09 |
+| 1.2.0 | Migration .NET 10 | 2026-03-20 |
+
+---
+
+## Itérations en cours / planifiées
+
+| # | Sujet | Statut |
+|---|-------|--------|
+| 1 | AGENTS.md — cycle de développement itératif | Livré (PR #8) |
+| 2 | Réduction verbosité API (génériques) | En discussion |
+
+---
+
+## ADR (Architecture Decision Records)
+
+### ADR-001 — Zéro réflexion via ConcurrentDictionary + génériques compilés
+
+- **Contexte :** Les implémentations Mediator courantes (MediatR) utilisent la réflexion pour résoudre les handlers à l'exécution, ajoutant un overhead significatif.
+- **Décision :** Utiliser `ConcurrentDictionary<string, Type>` avec des clés générées statiquement à partir des noms complets de types. Résolution via DI standard sans `ActivatorUtilities`.
+- **Conséquences :** Overhead < 50 ns. Enregistrement explicite requis (ou via Source Generator). Pas de découverte automatique "magique".
+
+### ADR-002 — Scope DI par appel dans DispatchAsync / SendAsync / PublishAsync
+
+- **Contexte :** Les handlers peuvent dépendre de services scoped (ex. `DbContext` EF Core). Un singleton partagé provoquerait des corruptions de données.
+- **Décision :** Chaque appel crée son propre `IServiceScope` via `_serviceProvider.CreateScope()`. Pour les events : chaque handler obtient son propre scope indépendant.
+- **Conséquences :** Isolation garantie. Légère surcharge de création de scope (< 1 µs, négligeable).
+
+### ADR-003 — Enregistrement explicite des handlers (Register*)
+
+- **Contexte :** La découverte automatique par réflexion viole le principe zéro réflexion.
+- **Décision :** Enregistrement explicite via `RegisterCommandHandler<T>()` ou via `MediatorBuilder.AddHandlersFromAssembly()` (scan assemblies au démarrage uniquement, pas à l'exécution).
+- **Conséquences :** Verbosité accrue vs. MediatR. Contrepartie : erreurs détectées au démarrage, pas à l'exécution.
+
+---
+
+## Dette technique
+
+- `PublishAsync` utilise un `lock` sur `List<Type>` lors de la copie des handlers — pourrait être remplacé par `ImmutableList<T>` pour éliminer le lock dans le chemin chaud.
+- Les handlers d'instances dans `RegisterCommandHandler(handler)` ne stockent que le type — l'instance n'est pas utilisée lors du dispatch DI (comportement potentiellement surprenant en tests).
+- `docs/CHANGELOG.md` section `[Unreleased]` liste des fonctionnalités non implémentées (diagnostics, middlewares, CancellationToken, i18n) — à nettoyer ou à créer des issues.
+
+---
+
+## Prochaine itération
+
+**#2 — Réduction verbosité API publique**
+
+Objectif : réduire les paramètres de type redondants dans les appels `DispatchAsync` et `SendAsync`.
+
+```csharp
+// Actuel — TResponse doit être répété
+var result = await mediator.DispatchAsync<CreateOrderCommand, OrderId>(command);
+
+// Cible envisagée — TResponse inféré depuis ICommand<TResponse>
+var result = await mediator.DispatchAsync(command);
+```
+
+> Statut : en discussion — clarification besoin/périmètre/contraintes en cours.