v0.1.0-pre.066

docs/rules/CRATE_DOCUMENTATION_RULES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/CRATE_DOCUMENTATION_RULES.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # 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.
+`USAGES.md` et les autres noms concurrents sont interdits. `001.README.md` reste autorisé comme index de répertoire lorsque le tri lexical au début d’un répertoire très fourni est utile, par exemple sous `idls/`; 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.
 
@@ -114,6 +114,8 @@ Une réexportation publique doit être vérifiée jusqu’à son chemin d’acc
 
 Chaque API publique significative doit disposer d’au moins un exemple ou être couverte par un exemple de scénario explicitement identifié. Les APIs triviales ou regroupées peuvent partager un exemple lorsqu’il démontre réellement leur usage.
 
+Les tests unitaires peuvent être documentés lorsqu’ils illustrent un contrat public, un invariant, un format canonique ou une régression importante. `USAGE.md` doit alors les référencer et expliquer ce qu’ils démontrent, sans transformer les helpers internes en API publique.
+
 ### 4.4 Crates sans API bibliothèque publique
 
 Une crate principalement binaire ou interne conserve un `USAGE.md`. Le document décrit alors ses commandes, entrées, sorties, configuration, contrats d’intégration et limites, sans inventer une API Rust publique.
@@ -164,7 +166,7 @@ Une idée encore exploratoire reste dans `docs/IDEA_REMINDERS.md` ou dans un doc
 
 Le TODO ne doit pas :
 
-- répéter les travaux déjà terminés ;
+- conserver ou répéter les travaux déjà terminés ;
 - contenir l’historique des corrections ;
 - recopier le ROADMAP général ;
 - transformer une hypothèse en obligation ;
@@ -186,7 +188,7 @@ Chaque changelog de crate doit contenir au minimum :
 - l’adoption des nouvelles règles Rust et Khadhroony applicables ;
 - les validations réellement exécutées et les limitations encore connues.
 
-La section `0.1.0` peut regrouper les prereleases de migration lorsque leur détail exhaustif n’apporte pas de valeur. Les prereleases ou correctifs importants peuvent être conservés lorsqu’ils expliquent une rupture, une correction notable ou une validation structurante.
+La section `0.1.0` synthétise la migration initiale. À partir de cette base, le changelog de crate conserve le détail des prereleases et correctifs `fix` qui ont touché la crate, afin de reprendre durablement les informations pertinentes de chaque `delta.md`.
 
 ### 6.3 Catégories
 
@@ -206,13 +208,15 @@ Ne pas créer des sections vides.
 
 ### 6.4 Versions et corrections
 
-Le changelog distingue clairement :
+Le changelog de crate distingue clairement :
 
 - version publiée ;
 - prerelease ;
 - correctif `fix` ;
 - changement non publié.
 
+Le changelog général suit une granularité différente : il décrit les changements entre versions fonctionnelles, par exemple de `0.4.6` à `0.4.7`, sans détailler les prereleases ni les correctifs `fix`. Les détails de livraison restent dans les changelogs des crates concernées.
+
 Une modification fonctionnelle de la crate impose une mise à jour de son changelog. Une modification documentaire pure peut être regroupée sous `Non publié / Documentation`.
 
 ### 6.5 Provenance bot2
@@ -237,7 +241,7 @@ Les matrices actives maintenues sous :
 test-fixtures/contract-matrices/
 ```
 
-restent les références canoniques. Elles ne doivent pas être dupliquées dans `docs/`.
+restent les références canoniques. Elles servent à la fois de contrats documentaires et de fixtures exécutées par des tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées dans `docs/`.
 
 Les documents de crate et de protocole doivent les référencer par lien et expliquer leur rôle, leur portée et leur statut de validation.