khadhroony-bot3/docs/rules/CRATE_DOCUMENTATION_RULES.md

Règles documentaires des crates

1. Objet

Ce document définit le contrat documentaire normatif applicable à chaque crate membre du workspace khadhroony-bot3.

Chaque crate doit posséder exactement les quatre fichiers suivants à sa racine :

README.md
TODO.md
USAGE.md
CHANGELOG.md

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.

2. Principes communs

Pour chaque document de crate :

• décrire uniquement des éléments vérifiés dans le code, les exports publics, les tests, les configurations actives ou les décisions acquises ;
• ne pas inventer d’API, de fonctionnalité, de validation ou de compatibilité ;
• distinguer clairement l’existant, le partiellement implémenté, le reporté et le hors périmètre ;
• employer les noms actuels des crates, modules publics, binaires et types ;
• ajouter des liens relatifs valides vers les autres documents de la crate et vers la documentation transversale pertinente ;
• ne pas recopier une matrice, une fixture ou un rapport déjà maintenu à son emplacement canonique ;
• préférer un lien vers test-fixtures/contract-matrices/, les tests ou un document transversal plutôt qu’une duplication ;
• conserver les détails historiques dans les changelogs et archives, non dans le README ou le guide d’utilisation ;
• mettre à jour le numéro de version documentaire placé dans l’en-tête du fichier lorsqu’un changement substantiel est effectué.

Les sections obligatoires ne doivent pas être laissées vides. Lorsqu’aucun élément n’est recensé, l’indiquer explicitement.

3. README.md

3.1 Rôle

Le README présente la crate à un lecteur qui doit comprendre rapidement sa place dans le workspace.

3.2 Contenu obligatoire

Le README contient au minimum :

1. objectif ;
2. périmètre fonctionnel ;
3. responsabilités ;
4. éléments explicitement hors périmètre ;
5. principales fonctionnalités déjà disponibles ;
6. principales façades ou catégories d’API publiques, sans catalogue exhaustif ;
7. relations avec les autres crates ;
8. binaires fournis, le cas échéant ;
9. statut de maturité et limites importantes ;
10. liens vers USAGE.md, TODO.md, CHANGELOG.md et les documents d’architecture pertinents.

3.3 Interdictions

Le README ne doit pas :

• servir de journal chronologique ;
• contenir une liste détaillée de toutes les prereleases ou corrections fix ;
• annoncer comme disponible une fonctionnalité seulement prévue ;
• recopier intégralement les APIs publiques ;
• recopier les matrices de contrats présentes dans test-fixtures/contract-matrices/ ;
• reprendre sans adaptation un README de bot2.

4. USAGE.md

4.1 Rôle

USAGE.md documente l’utilisation réelle de la crate depuis l’extérieur de celle-ci.

4.2 Frontière des APIs documentées

Le guide documente uniquement les APIs publiques exposées aux consommateurs de la crate :

• éléments pub effectivement accessibles depuis la racine publique ou un chemin public stable ;
• traits publics destinés à être implémentés ou appelés par d’autres crates ;
• fonctions, constructeurs, méthodes, types, constantes et façades publiques significatives ;
• commandes, événements, DTO ou contrats IPC publics d’une application ou d’une crate mixte ;
• arguments et comportement des binaires publics.

Il ne documente pas comme APIs d’utilisation :

• les éléments pub(crate) ;
• les sous-modules internes non réexportés ;
• les helpers de test ;
• les détails privés d’implémentation ;
• une dépendance simplement utilisée en interne ;
• une API historique bot2 qui n’existe plus dans bot3.

Une réexportation publique doit être vérifiée jusqu’à son chemin d’accès consommateur. La seule présence du mot-clé pub dans un fichier interne ne suffit pas.

4.3 Contenu obligatoire

USAGE.md contient au minimum :

1. objectif du guide ;
2. prérequis ;
3. dépendance Cargo et features utiles, lorsqu’applicable ;
4. configuration nécessaire ;
5. vue d’ensemble de la surface publique ;
6. description des APIs publiques significatives ;
7. types publics importants et invariants ;
8. erreurs publiques et conditions d’échec ;
9. exemples réalistes, préférablement compilables ;
10. utilisation des binaires ou commandes, lorsqu’applicable ;
11. limites connues ;
12. liens vers les tests, exemples, fixtures et matrices canoniques.

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.

5. TODO.md

5.1 Rôle

Le TODO maintient l’état futur propre à la crate. Il ne sert ni de roadmap général ni de changelog.

5.2 Sections obligatoires

Le fichier distingue au minimum :

• fonctionnalités manquantes ;
• dette technique ;
• tests manquants ;
• validations Devnet/Mainnet manquantes ;
• documentation manquante ;
• dépendances ou contraintes externes ;
• éléments confirmés mais reportés ;
• hors périmètre.

Chaque entrée doit préciser, lorsque connu :

• son statut ;
• sa priorité ou son ordre relatif ;
• sa dépendance ;
• son critère de clôture ;
• la version ou série cible si elle est déjà décidée.

5.3 Relation avec docs/IDEA_REMINDERS.md

Les idées de docs/IDEA_REMINDERS.md ne sont pas copiées automatiquement dans les TODO de crates.

Une idée peut être intégrée au TODO d’une crate uniquement après :

1. confirmation qu’elle est toujours souhaitée ;
2. identification de la crate réellement responsable ;
3. vérification qu’elle n’est pas déjà implémentée ou remplacée ;
4. reformulation en tâche vérifiable ;
5. classement dans la bonne section et selon un ordre cohérent ;
6. ajout des dépendances et limites connues.

Une idée encore exploratoire reste dans docs/IDEA_REMINDERS.md ou dans un document de décision ; elle ne doit pas être présentée comme engagement de crate.

5.4 Interdictions

Le TODO ne doit pas :

• 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 ;
• masquer une fonctionnalité partiellement implémentée sous un statut binaire terminé/non terminé.

6. CHANGELOG.md

6.1 Rôle

Le changelog de crate retrace l’évolution fonctionnelle, structurelle et contractuelle de cette crate.

6.2 Base historique minimale

Chaque changelog de crate doit contenir au minimum :

• une section Non publié ;
• une section 0.1.0 décrivant 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 et les limitations encore connues.

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

Utiliser uniquement les catégories pertinentes parmi :

• Ajouté ;
• Modifié ;
• Corrigé ;
• Supprimé ;
• Migré ;
• Compatibilité ;
• Validation ;
• Limitations connues ;
• Documentation.

Ne pas créer des sections vides.

6.4 Versions et corrections

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

La reprise historique depuis bot2 doit être synthétique et traçable. Elle s’appuie sur les changelogs, README, rapports et code historiques, mais est réécrite pour refléter la responsabilité actuelle de la crate bot3.

Il est interdit de copier un changelog d’ancienne crate sans analyser :

• la destination de ses responsabilités dans bot3 ;
• les APIs supprimées ou consolidées ;
• les changements de noms ;
• les nouvelles contraintes ;
• les validations réellement conservées.

7. Matrices, fixtures, IDL et rapports

7.1 Matrices de contrats

Les matrices actives maintenues sous :

test-fixtures/contract-matrices/

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.

7.2 IDL

Les IDL archivées ou maintenues dans le workspace servent de références de conception et d’audit. Elles ne sont pas chargées dynamiquement par le code de production.

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.

Pour chaque IDL ajoutée, documenter lorsque possible :

• protocole et programme ;
• Program ID ;
• source ;
• version, tag ou commit ;
• nom de fichier normalisé ;
• surface actuelle ou future qui l’utilise ;
• statut de vérification.

7.3 Rapports historiques

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

Pour chaque crate :

1. lire son Cargo.toml, ses features et ses cibles ;
2. inventorier les exports accessibles depuis la racine publique ;
3. identifier les binaires et commandes ;
4. lire les tests et exemples ;
5. rechercher les anciennes responsabilités bot2 correspondantes ;
6. confronter les idées confirmées et le ROADMAP ;
7. rédiger les quatre documents ;
8. vérifier les liens et exemples ;
9. exécuter les audits documentaires prescrits ;
10. exécuter les tests de la crate uniquement si le travail révèle ou corrige une incohérence de code.

La création des documents ne doit jamais être une génération mécanique fondée seulement sur les noms de fichiers ou les anciens documents.