khadhroony-bot3/docs/rules/CRATE_DOCUMENTATION_RULES.md

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

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

Les variantes `001.README.md`, `USAGES.md` ou tout autre nom concurrent sont interdites dans la documentation active.

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.

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

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

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

- version publiée ;
- prerelease ;
- correctif `fix` ;
- changement non publié.

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 :

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

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.