v0.1.0-pre.069+

docs/rules/CRATE_DOCUMENTATION_RULES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/CRATE_DOCUMENTATION_RULES.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Règles documentaires des crates
 
@@ -16,7 +16,7 @@ USAGE.md
 CHANGELOG.md
 ```
 
-Les variantes `001.README.md`, `USAGES.md` ou tout autre nom concurrent sont interdites dans la documentation active.
+La variante `USAGES.md` et tout autre nom concurrent de `USAGE.md` sont interdits dans la documentation active. Un fichier `001.README.md` est autorisé comme index lexical dans un répertoire contenant un grand nombre de fichiers, par exemple `idls/`, afin d’apparaître au début d’un listing. Il ne remplace jamais le `README.md` obligatoire à la racine d’une crate.
 
 Ces fichiers doivent être écrits pour l’architecture actuelle de `khadhroony-bot3`. Les documents de `olddocs/archivekbot2/` sont des sources historiques : leur contenu peut être étudié, vérifié, réinterprété et adapté, mais ne doit jamais être déplacé, copié automatiquement ou rendu normatif sans réécriture explicite.
 
@@ -130,7 +130,7 @@ Le TODO maintient uniquement les travaux futurs confirmés propres à la crate.
 
 ### 5.2 Organisation
 
-Le fichier est organisé en tâches et, lorsque nécessaire, en sous-tâches. Les sections sont choisies selon le travail réellement recensé : version cible, fonctionnalité, dette technique, tests, validation réseau, documentation, migration ou dépendance externe.
+Le fichier est organisé en tâches et, lorsque nécessaire, en sous-tâches. Les sections sont choisies selon le travail réellement recensé : version cible, fonctionnalité, dette technique, tests, validation réseau, documentation, migration ou dépendance externe. Une tâche peut aussi porter un préfixe explicite lorsque cela améliore sa lecture, par exemple `Dette technique -`, `Test -`, `Documentation -`, `Validation Devnet -` ou `Dépendance externe -`.
 
 Chaque entrée doit :
 
@@ -175,16 +175,11 @@ Le changelog de crate retrace chronologiquement les changements effectivement in
 
 Il ne contient ni section `Non publié`, ni tâches futures, ni roadmap, ni liste de limitations sans changement associé.
 
-### 6.2 Base historique minimale
+### 6.2 Numérotation
 
-Chaque changelog de crate doit contenir au minimum une section `0.1.0` décrivant :
+Le changelog suit les versions réellement attribuées au workspace ou à la crate ; il ne crée ni n’impose une version. Une section n’est ajoutée que lorsqu’une release, une prerelease ou, exceptionnellement, un correctif significatif a effectivement affecté la crate.
 
-- la migration depuis les composants correspondants de `khadhroony-bot2` ;
-- les consolidations, renommages ou suppressions de frontières de crates intervenues dans bot3 ;
-- l’adoption des nouvelles règles Rust et Khadhroony applicables ;
-- les validations réellement exécutées pendant cette version.
-
-Les prereleases et correctifs ultérieurs sont ajoutés au moment où leurs changements sont intégrés à la crate.
+Lorsqu’une version de migration doit être retracée, son entrée décrit les responsabilités venues de `khadhroony-bot2`, les consolidations ou renommages, les nouvelles règles applicables et les validations réellement exécutées pendant cette version. Le numéro utilisé est celui de la livraison concernée, pas une valeur minimale imposée par la documentation.
 
 ### 6.3 Catégories
 
@@ -199,17 +194,17 @@ Utiliser uniquement les catégories pertinentes parmi :
 - Validation ;
 - Documentation.
 
-Ne pas créer de section vide. Une limitation n’est mentionnée que si elle résulte directement du changement décrit dans l’entrée considérée ; les travaux nécessaires à sa suppression appartiennent au TODO.
+Ne pas créer de section vide. Une limitation connue peut être intégrée au texte explicatif d’un changement lorsqu’elle est nécessaire pour comprendre sa portée. Elle ne constitue pas une catégorie autonome du changelog. Les travaux nécessaires à sa suppression appartiennent au TODO.
 
-### 6.4 Versions et corrections
+### 6.4 Versions, prereleases et correctifs
 
-Le changelog distingue clairement :
+Le changelog général du workspace ne liste que les versions fonctionnelles `X.Y.Z`.
 
-- versions fonctionnelles ;
-- prereleases ;
-- correctifs `fix`.
+Le changelog d’une crate peut détailler les versions `X.Y.Z`, les prereleases `X.Y.Z-pre.abc` et, lorsqu’un correctif publié est suffisamment important pour mériter une trace autonome, les correctifs `X.Y.Z-pre.abc-fix-def`.
 
-Une modification fonctionnelle ou documentaire de la crate impose une entrée sous l’identifiant exact de la livraison qui l’intègre. Les informations pertinentes de `delta.md` concernant la crate sont reprises et reformulées dans son changelog.
+Les corrections mineures d’une prerelease ou d’une release ne créent pas automatiquement une section dédiée : elles sont repliées dans l’entrée de la version ou prerelease concernée. Un correctif reçoit une section propre seulement lorsqu’il modifie substantiellement ce qui a déjà été livré ou commité et qu’une explication séparée améliore la traçabilité.
+
+Les informations pertinentes de `delta.md` concernant la crate sont reprises et reformulées dans son changelog selon cette granularité.
 
 ### 6.5 Provenance bot2
 
@@ -243,11 +238,13 @@ Les IDL archivées ou maintenues dans le workspace servent de références de co
 
 L’inventaire et la classification des IDL sont des travaux documentaires actifs dès maintenant, notamment parce que bot3 a déjà subi un renommage massif des IDL. Ils ne sont pas reportés à l’implémentation future du décodeur Anchor.
 
+Un inventaire actif des programmes Solana et des IDL disponibles doit être reconstruit pour bot3. Il indique notamment les Program IDs connus, la présence ou l’absence d’une IDL récupérable, et la provenance de celle-ci. Une IDL peut provenir de Solscan, de l’explorateur Solana, d’un dépôt Git officiel ou d’une autre source vérifiée.
+
 Pour chaque IDL ajoutée, documenter lorsque possible :
 
 - protocole et programme ;
 - Program ID ;
-- source ;
+- source exacte ;
 - version, tag ou commit ;
 - nom de fichier normalisé ;
 - surface actuelle ou future qui l’utilise ;
@@ -257,27 +254,7 @@ Pour chaque IDL ajoutée, documenter lorsque possible :
 
 Les rapports bot2 sont des preuves historiques. Les documents bot3 doivent synthétiser leurs conclusions utiles et les confronter à l’architecture actuelle, sans les déplacer depuis `olddocs/archivekbot2/` ni les recopier intégralement.
 
-## 8. Statuts particuliers connus
-
-### 8.1 Registre ElGamal
-
-La documentation doit distinguer les niveaux suivants :
-
-- implémentation du registre dans `kb-lib` ;
-- éventuelle intégration dans `kb-pipeline` et `kb-pipeline-demo-scenarios`, à vérifier précisément ;
-- présentation non fonctionnelle dans `kb-app-demo-desktop` ;
-- absence de validation réelle Devnet ;
-- déploiement Devnet/Mainnet non tenu pour acquis et à vérifier avant toute affirmation.
-
-Le registre ElGamal reste mis de côté tant que son déploiement, ses prérequis de preuve et son intégration applicative ne sont pas établis.
-
-### 8.2 Metaplex Token Metadata
-
-La migration bot2 vers bot3 a commencé en cours de développement de `0.4.7`.
-
-Le décodeur Metaplex Token Metadata déjà réalisé dans bot2 a été migré dans bot3. La documentation ne doit donc ni reporter le décodeur comme entièrement futur, ni considérer toute la surface `0.4.7` comme achevée. Les exécuteurs, matérialisateurs, préflights, validations et autres éléments doivent être décrits selon leur état réel.
-
-## 9. Processus de création des documents de crate
+## 8. Processus de création des documents de crate
 
 Pour chaque crate :