khadhroony-bot3/docs/rules/CRATE_DOCUMENTATION_RULES.md

<!-- file: docs/rules/CRATE_DOCUMENTATION_RULES.md -->
<!-- version: 3 -->

# 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 :

```text
README.md
TODO.md
USAGE.md
CHANGELOG.md
```

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.

## 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 documents ne doivent pas contenir de sections vides ni de constats sans action. Une section sans contenu utile est omise.

## 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. contraintes et limites durables de l’API actuelle ;
12. liens vers les tests, exemples, fixtures et matrices canoniques.

Les travaux planifiés pour supprimer une limite temporaire appartiennent au TODO et ne sont pas répétés dans `USAGE.md`.

Les exemples Rust doivent respecter les règles du workspace, y compris les conventions de propagation d’erreurs.

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.
Un `USAGE.md` doit fournir plusieurs exemples lorsque la crate expose plusieurs familles d’API ou plusieurs étapes d’un parcours public. Un unique exemple global n’est suffisant que pour une surface publique réellement minimale. Les exemples doivent couvrir en priorité la construction des requêtes, leur validation, l’exécution principale, l’interprétation du résultat et les invariants opérateur pertinents.

### 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 uniquement les travaux futurs confirmés propres à la crate. Il ne sert ni de roadmap général, ni de changelog, ni de fiche descriptive.

### 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. 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 :

- commencer par une action à réaliser ;
- être vérifiable et supprimable une fois terminée ;
- préciser sa version cible, sa priorité, sa dépendance ou son critère de clôture lorsque cette information est connue ;
- rester dans le TODO uniquement tant qu’elle n’est pas achevée.

Une contrainte externe ne figure dans le TODO que si elle bloque ou conditionne une tâche explicite. Une absence de validation Devnet/Mainnet n’est mentionnée que lorsqu’une validation réseau doit réellement être exécutée pour cette crate.

### 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 selon un ordre cohérent ;
6. ajout de ses dépendances ou critères de clôture.

Une idée encore exploratoire reste dans `docs/IDEA_REMINDERS.md` ou dans un document de décision.

### 5.4 Interdictions

Le TODO ne doit pas :

- conserver une tâche terminée ;
- contenir des phrases telles que « aucune tâche », « aucune validation » ou « hors périmètre » ;
- décrire le comportement actuel de la crate ;
- contenir l’historique des corrections ;
- recopier le ROADMAP général ;
- transformer une hypothèse en obligation.

## 6. `CHANGELOG.md`

### 6.1 Rôle

Le changelog de crate retrace chronologiquement les changements effectivement intégrés à cette crate. Il conserve le détail des releases, prereleases et correctifs `fix` qui l’ont affectée.

Il ne contient ni section `Non publié`, ni tâches futures, ni roadmap, ni liste de limitations sans changement associé.

### 6.2 Numérotation

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.

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

Utiliser uniquement les catégories pertinentes parmi :

- Ajouté ;
- Modifié ;
- Corrigé ;
- Supprimé ;
- Migré ;
- Compatibilité ;
- Validation ;
- Documentation.

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, prereleases et correctifs

Le changelog général du workspace ne liste que les versions fonctionnelles `X.Y.Z`.

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`.

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

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 :

```text
test-fixtures/contract-matrices/
```

restent les références canoniques. 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.

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 exacte ;
- 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. 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.