401 lines
14 KiB
Markdown
401 lines
14 KiB
Markdown
<!-- file: docs/DOCUMENTATION_REFACTOR_PLAN.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# Plan de refonte documentaire
|
||
|
||
## 1. Objectif
|
||
|
||
Ce plan transforme progressivement la documentation de `khadhroony-bot3 v0.1.0-pre.062` sans mélanger audit, déplacements, réécriture historique, documentation par crate et décision de réalignement vers `0.4.6`.
|
||
|
||
Aucune version Cargo ne doit être modifiée avant la conclusion de `docs/V0_4_6_ALIGNMENT_AUDIT.md`.
|
||
|
||
## 2. Principes d’exécution
|
||
|
||
- livrer des deltas courts et thématiques ;
|
||
- ne pas créer en masse des documents vides ;
|
||
- documenter une crate à partir de ses APIs publiques, binaires, tests et configurations réels ;
|
||
- ne jamais déplacer ni migrer automatiquement un document depuis `olddocs/archivekbot2/` ;
|
||
- créer des documents bot3 nouveaux après lecture, sélection, vérification et adaptation des sources historiques ;
|
||
- référencer les matrices canoniques de `test-fixtures/contract-matrices/` sans les dupliquer ;
|
||
- ne pas inventer d’API ou de validation ;
|
||
- archiver avant de retirer un document ayant une valeur historique ;
|
||
- corriger toutes les références avant chaque déplacement ;
|
||
- conserver séparément les archives bot2 et bot3 ;
|
||
- ne pas rouvrir les audits techniques Solana déjà validés sans écart concret ;
|
||
- exécuter uniquement les validations réellement nécessaires au delta.
|
||
|
||
## 3. Contrat documentaire à inscrire dans les règles
|
||
|
||
Chaque crate du workspace doit posséder les quatre fichiers suivants :
|
||
|
||
```text
|
||
README.md
|
||
TODO.md
|
||
USAGE.md
|
||
CHANGELOG.md
|
||
```
|
||
|
||
### 3.1 `README.md`
|
||
|
||
Contenu minimal :
|
||
|
||
- objectif et périmètre ;
|
||
- responsabilités et exclusions ;
|
||
- fonctionnalités principales ;
|
||
- principales APIs ou façades ;
|
||
- relations avec les autres crates ;
|
||
- liens vers `USAGE.md`, `TODO.md`, `CHANGELOG.md` et l’architecture pertinente.
|
||
|
||
Le README ne contient pas le journal détaillé des versions.
|
||
|
||
### 3.2 `TODO.md`
|
||
|
||
Sections minimales :
|
||
|
||
- fonctionnalités manquantes ;
|
||
- dette technique ;
|
||
- tests manquants ;
|
||
- validations Devnet/Mainnet manquantes ;
|
||
- documentation manquante ;
|
||
- dépendances externes ;
|
||
- éléments reportés ;
|
||
- hors périmètre.
|
||
|
||
Les sections sans élément doivent indiquer explicitement qu’aucun élément n’est actuellement recensé, plutôt que rester vides.
|
||
|
||
### 3.3 `USAGE.md`
|
||
|
||
Contenu minimal :
|
||
|
||
- objectif ;
|
||
- prérequis ;
|
||
- configuration ;
|
||
- APIs publiques significatives ;
|
||
- description des types importants ;
|
||
- erreurs et invariants ;
|
||
- exemples réalistes ou compilables ;
|
||
- au moins un exemple par API publique significative ;
|
||
- limites connues ;
|
||
- liens vers tests, fixtures et matrices.
|
||
|
||
Une API n’est documentée qu’après vérification dans le code et les exports publics.
|
||
|
||
### 3.4 `CHANGELOG.md`
|
||
|
||
Le changelog de crate distingue :
|
||
|
||
- non publié ;
|
||
- releases ;
|
||
- prereleases ;
|
||
- correctifs `fix` ;
|
||
- ajouts ;
|
||
- modifications ;
|
||
- corrections ;
|
||
- suppressions ;
|
||
- migrations ;
|
||
- compatibilité ;
|
||
- validations ;
|
||
- limitations connues.
|
||
|
||
Il est mis à jour pour tout changement fonctionnel de la crate. Les changements purement documentaires peuvent être regroupés dans une entrée documentaire explicite.
|
||
|
||
## 4. Arborescence cible
|
||
|
||
```text
|
||
docs/
|
||
├── README.md
|
||
├── architecture/
|
||
├── audits/
|
||
├── decisions/
|
||
├── generated/
|
||
├── guides/
|
||
├── migrations/
|
||
├── protocols/
|
||
├── rules/
|
||
└── validation/
|
||
|
||
olddocs/
|
||
├── archivekbot2/
|
||
│ ├── README.md
|
||
│ ├── CHANGELOG.md
|
||
│ ├── ROADMAP.md
|
||
│ ├── RULES.md
|
||
│ ├── docs/
|
||
│ ├── prompts/
|
||
│ └── <anciennes-crates>/...
|
||
└── archivekbot3/
|
||
```
|
||
|
||
Le premier déplacement structurel devra inclure un tableau de correspondance ancien chemin vers nouveau chemin dans `docs/README.md` ou dans un rapport de migration dédié.
|
||
|
||
## 5. Séquence de deltas
|
||
|
||
### Delta 1 — audit et plan
|
||
|
||
Fichiers ajoutés :
|
||
|
||
- `docs/DOCUMENTATION_REFACTOR_AUDIT.md` ;
|
||
- `docs/DOCUMENTATION_REFACTOR_PLAN.md`.
|
||
|
||
Aucun déplacement et aucune réécriture massive.
|
||
|
||
Validations :
|
||
|
||
```bash
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
```
|
||
|
||
### Delta 2 — archives et index documentaire
|
||
|
||
Travail :
|
||
|
||
1. créer `olddocs/archivekbot2/` ;
|
||
2. y reconstruire le miroir documentaire de bot2 en conservant les chemins relatifs : documents racine, `docs/`, `prompts/` et documents des anciennes crates ;
|
||
3. inclure les fichiers présentant une fonction documentaire démontrée, conformément à la politique de sélection, sans copier le code, les artefacts de build ou les données privées ;
|
||
4. appliquer [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) pour distinguer matrices, schémas, exemples et IDL documentaires des fixtures et configurations d’exécution ;
|
||
4. créer `olddocs/archivekbot3/` ;
|
||
5. créer `docs/README.md` ;
|
||
6. créer l’arborescence utile sans fichiers factices ;
|
||
7. documenter la provenance, la non-normativité et l’intégrité logique de l’archive bot2.
|
||
|
||
Aucun document bot3 actif ne doit encore être supprimé.
|
||
|
||
### Delta 3 — règles documentaires (`v0.1.0-pre.065`)
|
||
|
||
Travail :
|
||
|
||
1. corriger `docs/rules/RULES_GENERAL.md` pour imposer les quatre fichiers exacts par crate ;
|
||
2. interdire `USAGES.md`, retenir définitivement `USAGE.md` et encadrer l’exception `001.README.md` pour les index lexicaux ;
|
||
3. créer `docs/rules/CRATE_DOCUMENTATION_RULES.md` ;
|
||
4. définir la frontière entre README, TODO, USAGE, CHANGELOG général et changelogs de crates ;
|
||
5. imposer que `USAGE.md` documente uniquement les APIs publiques réellement accessibles ;
|
||
6. imposer dans chaque changelog de crate une base `0.1.0` décrivant la migration bot2, la consolidation bot3 et les nouvelles normes ;
|
||
7. définir la reprise contrôlée des idées confirmées de `docs/IDEA_REMINDERS.md` dans les TODO ;
|
||
8. interdire toute duplication des matrices canoniques de `test-fixtures/contract-matrices/` ;
|
||
9. préciser les statuts Metaplex Token Metadata, ElGamal et IDL ;
|
||
10. fournir quatre modèles documentaires non génératifs.
|
||
|
||
Les règles secondaires restent temporairement à la racine dans ce delta.
|
||
|
||
### Delta 4 — déplacement des règles secondaires
|
||
|
||
Travail :
|
||
|
||
1. créer `docs/rules/` ;
|
||
2. déplacer `docs/rules/RULES_GENERAL.md`, `docs/rules/RULES_RUST.md` et `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ;
|
||
3. mettre à jour `RULES.md` ;
|
||
4. corriger les liens internes ;
|
||
5. adapter `scripts/audit_khadhroony_workspace_rules.py` ;
|
||
6. corriger les références dans prompts, README et documents d’onboarding ;
|
||
7. vérifier qu’aucune référence active aux anciens chemins ne subsiste.
|
||
|
||
Validations obligatoires :
|
||
|
||
```bash
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
```
|
||
|
||
### Delta 5 — documentation générale bot3 (`v0.1.0-pre.067`)
|
||
|
||
Travail :
|
||
|
||
1. remplacer le README racine obsolète par une présentation stable ;
|
||
2. créer les objectifs et l’architecture générale ;
|
||
3. créer la carte des 11 crates ;
|
||
4. documenter les architectures pipeline et stockage ;
|
||
5. créer une matrice de responsabilités par surface sans dupliquer les matrices contractuelles ;
|
||
6. mettre à jour `docs/README.md`.
|
||
|
||
Ces documents sont réécrits pour bot3 à partir du workspace actuel et des sources historiques vérifiées.
|
||
|
||
### Delta 6 — changelog général de transition
|
||
|
||
Travail :
|
||
|
||
1. préserver une copie historique du changelog bot2 ;
|
||
2. reconstruire le changelog bot3 ;
|
||
3. reprendre l’historique fonctionnel pertinent de `0.0.1` à `0.4.6` ;
|
||
4. ajouter la transition bot2 vers bot3 ;
|
||
5. documenter consolidation, renommages et validations `0.1.0-pre.*` ;
|
||
6. conserver les limites, notamment ElGamal non validé Devnet ;
|
||
7. distinguer clairement version fonctionnelle et prereleases de migration.
|
||
|
||
Le changelog ne doit pas affirmer que bot3 est déjà officiellement `0.4.6`.
|
||
|
||
### Delta 7 — roadmap général
|
||
|
||
Reconstruire `ROADMAP.md` selon les séries suivantes :
|
||
|
||
- `0.4.6` : fermeture de l’alignement et écarts résiduels ;
|
||
- `0.4.7` : poursuite de Metaplex Token Metadata déjà partiellement migré, puis clôture `0.4.x` ;
|
||
- `0.5.x` : configuration, scénarios autonomes, CLI, fixtures et wallet ;
|
||
- `0.6.x` : infrastructure Anchor, reste SPL et Metaplex ;
|
||
- `0.7.x` : Meteora ;
|
||
- `0.8.x` : Raydium ;
|
||
- `0.9.x` : Pump ;
|
||
- `0.10.x` : Orca ;
|
||
- `0.11.x` : Jupiter ;
|
||
- `0.12.x` : OKX et autres routers ;
|
||
- `0.13.x` : transports temps réel ;
|
||
- `0.14.x` : trading, workers et orchestration ;
|
||
- `0.15.x+` : extensions futures.
|
||
|
||
Le roadmap ne contient ni prereleases, ni correctifs `fix`, ni journal détaillé du passé.
|
||
|
||
### Delta 8 — documentation des crates fondamentales
|
||
|
||
Ordre proposé :
|
||
|
||
1. `kb-core` ;
|
||
2. `kb-config` ;
|
||
3. `kb-logging` ;
|
||
4. `kb-program-ids` ;
|
||
5. `kb-store`.
|
||
|
||
Pour chaque crate : auditer les exports publics, tests, erreurs, exemples existants et dépendances avant de rédiger les quatre fichiers.
|
||
|
||
### Delta 9 — documentation du noyau fonctionnel
|
||
|
||
Ordre proposé :
|
||
|
||
1. `kb-lib` ;
|
||
2. `kb-pipeline` ;
|
||
3. `kb-onchain-transport`.
|
||
|
||
`kb-lib` devra être traité par sections cohérentes et liens vers les matrices, sans transformer son README en catalogue exhaustif de toutes les fonctions.
|
||
|
||
### Delta 10 — démonstrations et wallet
|
||
|
||
Ordre proposé :
|
||
|
||
1. `kb-pipeline-demo-scenarios` ;
|
||
2. `kb-app-demo-desktop` ;
|
||
3. `kb-wallet`.
|
||
|
||
Les TODO doivent expliciter :
|
||
|
||
- l’autonomie incomplète éventuelle des scénarios ;
|
||
- les contraintes de validation Tauri ;
|
||
- le statut d’ébauche de `kb-wallet` et son périmètre `0.5.x`.
|
||
|
||
### Delta 11 — réorganisation des documents actifs
|
||
|
||
Travail :
|
||
|
||
- déplacer les guides et rapports Devnet ;
|
||
- classer les documents IDL ;
|
||
- classer la convention de nommage ;
|
||
- ventiler `IDEA_REMINDERS.md` dans les TODO ou décisions ;
|
||
- mettre à jour toutes les références ;
|
||
- archiver sous `olddocs/archivekbot3/` les audits et plans remplacés qui conservent une valeur historique.
|
||
|
||
Aucun déplacement ne doit laisser de lien cassé.
|
||
|
||
### Delta 12 — refonte des prompts
|
||
|
||
Travail :
|
||
|
||
1. copier ou référencer les prompts bot2 historiques dans l’archive appropriée sans les rendre normatifs ;
|
||
2. créer `prompts/README.md` ;
|
||
3. créer un modèle bot3 contenant mission, base validée, périmètre, hors périmètre, règles, architecture, fichiers à lire, tests, critères de clôture, livraison, limites, décisions reportées et état Git ;
|
||
4. migrer les informations bot3 utiles ;
|
||
5. archiver les deux prompts de migration actuels lorsque leurs informations ont été reprises.
|
||
|
||
### Delta 13 — audit d’alignement `0.4.6`
|
||
|
||
Créer :
|
||
|
||
```text
|
||
docs/V0_4_6_ALIGNMENT_AUDIT.md
|
||
```
|
||
|
||
L’audit synthétise, sans réauditer intégralement les protocoles :
|
||
|
||
- composants migrés ;
|
||
- renommages ;
|
||
- consolidations ;
|
||
- versions Cargo ;
|
||
- noms de crates et binaires ;
|
||
- exports ;
|
||
- tests ;
|
||
- validations Devnet ;
|
||
- ElGamal ;
|
||
- transports ;
|
||
- documentation par crate ;
|
||
- prompts et archives ;
|
||
- `kb-wallet` ;
|
||
- futur split de `kb-config` ;
|
||
- autonomie de `kb-pipeline-demo-scenarios` ;
|
||
- écarts résiduels.
|
||
|
||
Conclusion obligatoire :
|
||
|
||
```text
|
||
READY_FOR_0_4_6
|
||
READY_WITH_DOCUMENTED_EXCEPTIONS
|
||
NOT_READY_FOR_0_4_6
|
||
```
|
||
|
||
### Delta 13 — décision de versionnement
|
||
|
||
Seulement après validation du delta 12 :
|
||
|
||
- décider du passage officiel à `0.4.6` ;
|
||
- modifier les versions Cargo si la conclusion le permet ;
|
||
- mettre à jour changelogs, documentation et prompt de session ;
|
||
- exécuter les validations workspace imposées pour les modifications de code ou de structure.
|
||
|
||
## 6. Matrice de validation
|
||
|
||
### Documentation pure
|
||
|
||
```bash
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
```
|
||
|
||
Les opérations Git et leurs contrôles sont réalisés séparément par l’opérateur et ne doivent pas être répétés dans les validations demandées à la session.
|
||
|
||
### Code, scripts d’audit ou structure utilisée par le code
|
||
|
||
```bash
|
||
cargo fmt --all
|
||
cargo check --workspace
|
||
cargo clippy --all-targets
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
```
|
||
|
||
Ajouter les tests des crates modifiées.
|
||
|
||
### Frontend desktop
|
||
|
||
La validation frontend ne doit jamais utiliser `npm --prefix kb-app-demo-desktop run build`.
|
||
|
||
La validation runtime se fait par :
|
||
|
||
```bash
|
||
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
|
||
```
|
||
|
||
## 7. Risques contrôlés
|
||
|
||
| Risque | Mesure |
|
||
|----------------------------------------------------|-----------------------------------------------------------------------------|
|
||
| perte d’historique bot2 | miroir documentaire hiérarchique dans `olddocs/archivekbot2/` avant reprise |
|
||
| règles introuvables après déplacement | correction préalable des scripts et références, delta dédié |
|
||
| documentation d’API inventée | lecture des exports et tests avant rédaction |
|
||
| changelog général trop détaillé | déléguer le détail fonctionnel aux changelogs de crates |
|
||
| roadmap redevenant une checklist | interdire prereleases et correctifs dans le roadmap général |
|
||
| confusion entre migration et version fonctionnelle | section de transition explicite et audit d’alignement séparé |
|
||
| fausse validation ElGamal | conserver le statut non validé Devnet |
|
||
| modification massive difficile à relire | un thème documentaire par delta |
|
||
|
||
## 8. Première décision attendue
|
||
|
||
Valider le présent audit et le séquençage des deltas avant :
|
||
|
||
- la copie de l’archive bot2 dans `olddocs/` ;
|
||
- le déplacement des règles ;
|
||
- la reconstruction du changelog et du roadmap ;
|
||
- la création des documents par crate ;
|
||
- la modification des versions Cargo.
|