v0.1.0-pre.074
This commit is contained in:
400
olddocs/archivekbot3/docs/DOCUMENTATION_REFACTOR_PLAN.md
Normal file
400
olddocs/archivekbot3/docs/DOCUMENTATION_REFACTOR_PLAN.md
Normal file
@@ -0,0 +1,400 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user