💡 [REQUEST] - Documenter les règles agent récurrentes dans AGENTS.md

[shikanime]

Description

Les mêmes règles sont répétées oralement à chaque session d'agent travaillant dans ce dépôt ; elles ne sont consignées nulle part. AGENTS.md est le point d'entrée des agents (créé par #1937) mais décrit seulement la structure et les commandes : chaque nouvelle session réapprend ces règles — ou les viole avant correction.

Règles concernées (chacune trace à une correction réelle en revue ou en CI) :

• Pas de cast as (ni as any) pour resserrer un type inconnu ou optionnel : utiliser un type guard par if, et inclure l'identifiant fautif dans le message d'erreur.
• La configuration des services passe par l'injection (@Inject(xxxConfigFactory.KEY) + ConfigType), jamais process.env dans un service.
• Les helpers retournent de nouveaux objets, sans muter leurs entrées.
• apps/server est gelé : référence de lecture uniquement ; apps/server-nestjs est la seule cible modifiable.
• Parité de migration : chaque eventEmitter.emitAsync('<entity>.<verb>') doit avoir un consommateur @OnEvent → capturePluginResult, sinon les synchronisations Keycloak/GitLab s'arrêtent silencieusement à la bascule.
• Prisma : deleteMany/updateMany avec un filtre indéfini touche toutes les lignes — toujours filtrer par identifiant concret ; les clés étrangères ProjectRole/Repository ne cascadent pas.
• Tests déterministes : un tirage faker ne doit jamais pouvoir traverser un seuil de branche (fenêtre épinglée), sinon CI instable.
• Specs unitaires avec mockDeep pour Prisma/config, pas d'appels au niveau describe ; specs e2e dans test/*.e2e-spec.ts gated sur describe.runIf(Boolean(process.env.E2E)).
• Corriger à la source partagée où passent tous les appelants, pas un guard dupliqué chez chaque appelant.
• Ne pas déclarer terminé sans avoir exécuté les gates (pnpm lint, vitest ciblé).

PRs liées

Exemples simples

• Revue de PR : casts as any retirés dans sonarqube.service.spec.ts conformément à la règle.
• CI instable : faker.date.past({ years: 2 }) tirait parfois sous le seuil de rotation de 250 jours — le test échouait environ une fois sur trois.
• e2e : une spec exécutée hors gate échoue faute de Postgres/Keycloak locaux.

Spécifications techniques

Ajouter à AGENTS.md une section « Agent rules » (anglais, comme le reste du fichier) regroupant les règles ci-dessus, placée après « Conventions ».

Définition du fini

• La section règles est présente dans AGENTS.md
• Chaque règle trace à une correction réelle documentée
• La documentation liée a été ajoutée