v0.1.0-pre.074
This commit is contained in:
284
olddocs/archivekbot3/docs/DOCUMENTATION_REFACTOR_AUDIT.md
Normal file
284
olddocs/archivekbot3/docs/DOCUMENTATION_REFACTOR_AUDIT.md
Normal file
@@ -0,0 +1,284 @@
|
||||
<!-- file: docs/DOCUMENTATION_REFACTOR_AUDIT.md -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Audit de refonte documentaire
|
||||
|
||||
## 1. Objet
|
||||
|
||||
Cet audit établit l’état documentaire de `khadhroony-bot3` à partir de la base `v0.1.0-pre.062`, en comparaison avec l’archive complète fournie de `khadhroony-bot2 v0.4.7-pre.035-tofix07`.
|
||||
|
||||
Il précède toute refonte massive, tout déplacement des règles secondaires et tout réalignement du versionnement vers `0.4.6+`. Il ne constitue pas un nouvel audit technique des surfaces Solana déjà validées.
|
||||
|
||||
## 2. Sources inspectées
|
||||
|
||||
### 2.1 Racine bot3
|
||||
|
||||
Les fichiers suivants existent à la racine :
|
||||
|
||||
- `README.md` ;
|
||||
- `CHANGELOG.md` ;
|
||||
- `ROADMAP.md` ;
|
||||
- `RULES.md` ;
|
||||
- `docs/rules/RULES_GENERAL.md` ;
|
||||
- `docs/rules/RULES_RUST.md` ;
|
||||
- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ;
|
||||
- `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md`.
|
||||
|
||||
### 2.2 Documentation active bot3
|
||||
|
||||
Le répertoire `docs/` contient sept documents :
|
||||
|
||||
| Document | Statut initial | Classe proposée |
|
||||
|---------------------------------------|---------------------------------------------------------|----------------------------------------------|
|
||||
| `DEVNET_EXECUTION_GUIDE.md` | actif, volumineux, utilisé pour la validation opérateur | `docs/validation/` ou `docs/guides/` |
|
||||
| `PRE_062_DEVNET_VALIDATION_REPORT.md` | rapport de validation daté | `docs/validation/` |
|
||||
| `OPERATION_NAMING_CONVENTION.md` | normatif | `docs/architecture/` ou `docs/rules/` |
|
||||
| `IDL_AUDIT.md` | audit de migration | `docs/audits/` ou archive bot3 après reprise |
|
||||
| `IDL_TO_KB_LIB_NOMENCLATURE.md` | document de correspondance encore utile | `docs/migrations/` |
|
||||
| `MISSING_PROGRAM_IDLS.md` | état ciblé pouvant évoluer | `docs/audits/` ou `docs/protocols/` |
|
||||
| `IDEA_REMINDERS.md` | liste de rappels non normative | `docs/decisions/` ou TODO généraux ciblés |
|
||||
|
||||
Il n’existe pas encore de `docs/README.md` servant d’index.
|
||||
|
||||
### 2.3 Prompts bot3
|
||||
|
||||
Deux prompts sont présents :
|
||||
|
||||
- `prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md` ;
|
||||
- `prompts/khadhroony-bot3_next-session_after-v0.1.0-pre.062.md`.
|
||||
|
||||
Le premier est un prompt de migration très détaillé et historiquement utile, mais il ne doit pas rester le modèle normatif des futures sessions. Le second correspond au prompt de reprise courant et doit être conservé comme source jusqu’à la production du modèle bot3 et à l’archivage contrôlé des prompts antérieurs.
|
||||
|
||||
### 2.4 Documentation et prompts bot2
|
||||
|
||||
L’archive bot2 fournit :
|
||||
|
||||
- 61 fichiers sous `docs/`, comprenant architecture, stockage, pipeline, transports, exécution, matrices SPL/Core, audits de fermeture et validation `0.4.6` ;
|
||||
- 27 fichiers sous `prompts/`, dont un modèle de session, un index et les prompts historiques jusqu’à `0.4.7` Metaplex Token Metadata ;
|
||||
- un `CHANGELOG.md` structuré de `0.0.1` à `0.4.6` ;
|
||||
- un `ROADMAP.md` contenant l’historique détaillé, les prereleases et les validations opérateur.
|
||||
|
||||
Ces documents sont une source historique et technique. Ils ne sont pas normatifs pour bot3 tant qu’ils n’ont pas été adaptés à sa nouvelle architecture.
|
||||
|
||||
## 3. État de `olddocs/`
|
||||
|
||||
L’absence de `olddocs/` dans l’archive bot3 fournie est volontaire : conserver une copie partielle de bot2 dans chaque archive complète bot3 aurait dupliqué la source historique alors que l’archive complète bot2 est fournie au démarrage de la session documentaire. Ce point n’est donc pas un défaut de la base `pre.062`.
|
||||
|
||||
La reconstruction crée deux archives séparées :
|
||||
|
||||
```text
|
||||
olddocs/archivekbot2/
|
||||
olddocs/archivekbot3/
|
||||
```
|
||||
|
||||
`olddocs/archivekbot2/` doit reproduire l’arborescence documentaire utile de bot2, et pas uniquement son ancien répertoire `docs/`. La structure attendue comprend notamment :
|
||||
|
||||
```text
|
||||
olddocs/archivekbot2/README.md
|
||||
olddocs/archivekbot2/CHANGELOG.md
|
||||
olddocs/archivekbot2/ROADMAP.md
|
||||
olddocs/archivekbot2/RULES.md
|
||||
olddocs/archivekbot2/docs/...
|
||||
olddocs/archivekbot2/prompts/...
|
||||
olddocs/archivekbot2/<ancienne-crate>/README.md
|
||||
olddocs/archivekbot2/<ancienne-crate>/CHANGELOG.md
|
||||
olddocs/archivekbot2/<ancienne-crate>/<autres-documents>.md|json
|
||||
```
|
||||
|
||||
Cette archive est reconstruite depuis l’archive complète bot2 fournie, en conservant les chemins relatifs et sans modifier les fichiers historiques. Les documents bot3 devenus temporaires ou remplacés seront déplacés ultérieurement vers `olddocs/archivekbot3/`, après correction de leurs références.
|
||||
|
||||
Le choix opérationnel est une copie documentaire depuis l’archive bot2, et non un déplacement destructif ni une copie complète du code bot2.
|
||||
|
||||
## 4. Contrat documentaire des crates
|
||||
|
||||
Le workspace déclare 11 crates :
|
||||
|
||||
- `kb-core` ;
|
||||
- `kb-config` ;
|
||||
- `kb-lib` ;
|
||||
- `kb-logging` ;
|
||||
- `kb-program-ids` ;
|
||||
- `kb-pipeline` ;
|
||||
- `kb-pipeline-demo-scenarios` ;
|
||||
- `kb-onchain-transport` ;
|
||||
- `kb-store` ;
|
||||
- `kb-wallet` ;
|
||||
- `kb-app-demo-desktop`.
|
||||
|
||||
État actuel :
|
||||
|
||||
| Crate | README | TODO | USAGE | CHANGELOG |
|
||||
|------------------------------|--------:|-------:|-------:|----------:|
|
||||
| `kb-app-demo-desktop` | absent | absent | absent | absent |
|
||||
| `kb-config` | présent | absent | absent | absent |
|
||||
| `kb-core` | présent | absent | absent | absent |
|
||||
| `kb-lib` | présent | absent | absent | absent |
|
||||
| `kb-logging` | présent | absent | absent | absent |
|
||||
| `kb-onchain-transport` | absent | absent | absent | absent |
|
||||
| `kb-pipeline` | absent | absent | absent | absent |
|
||||
| `kb-pipeline-demo-scenarios` | présent | absent | absent | absent |
|
||||
| `kb-program-ids` | présent | absent | absent | absent |
|
||||
| `kb-store` | présent | absent | absent | absent |
|
||||
| `kb-wallet` | présent | absent | absent | absent |
|
||||
|
||||
Aucune crate ne satisfait donc le contrat complet `README.md`, `TODO.md`, `USAGE.md`, `CHANGELOG.md`.
|
||||
|
||||
La contradiction `USAGES.md` contre `USAGE.md` est résolue en faveur de `USAGE.md`. `001.README.md` reste autorisé uniquement comme index lexical de répertoire très fourni, notamment sous `idls/`, et ne remplace jamais le `README.md` obligatoire d’une crate.
|
||||
|
||||
### 4.4 Frontière de l’archive documentaire
|
||||
|
||||
La première sélection fondée sur toutes les extensions Markdown et JSON était trop large. La sélection doit désormais reposer sur la fonction documentaire autonome du fichier.
|
||||
|
||||
Sont notamment exclus les configurations de build et d’exécution Tauri/npm/TypeScript, les capabilities, les fixtures RPC et les fichiers internes sous `kb_store_core/src/` ou `kb_store_pg/src/`.
|
||||
|
||||
Restent conservés les matrices documentaires, les IDL archivées, `config/example.config.json` et `config/schema.config.json`, conformément à [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md).
|
||||
|
||||
## 5. Évaluation des documents racine
|
||||
|
||||
### 5.1 `README.md`
|
||||
|
||||
Le README racine doit être réécrit comme point d’entrée de bot3 : objectif, architecture consolidée, crates, démarrage, validations et liens documentaires. Il ne doit pas reprendre le journal détaillé de migration.
|
||||
|
||||
### 5.2 `CHANGELOG.md`
|
||||
|
||||
Le changelog bot3 actuel est centré sur les prereleases `0.1.0-pre.*`. Il doit être reconstruit sans perdre cette traçabilité, puis enrichi par l’historique pertinent de bot2 de `0.0.1` à `0.4.6` et par une section explicite de transition bot2 vers bot3.
|
||||
|
||||
Le changelog bot2 ne doit pas être supprimé de la source historique avant reprise complète. Sa copie archivée constituera la référence de contrôle.
|
||||
|
||||
### 5.3 `ROADMAP.md`
|
||||
|
||||
Le roadmap bot3 actuel est encore largement une checklist de migration et de prereleases. Le roadmap bot2 contient lui aussi un historique détaillé et des prereleases. Aucun des deux ne satisfait le nouveau contrat général.
|
||||
|
||||
Le futur `ROADMAP.md` doit être reconstruit par versions mineures et grands lots, sans prerelease ni correctif `fix`, avec dépendances, critères de sortie et liens vers les TODO/changelogs des crates.
|
||||
|
||||
### 5.4 `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md`
|
||||
|
||||
Ce document conserve une forte valeur de traçabilité, mais il ne doit pas rester un document actif permanent après clôture de la migration. Il doit alimenter l’audit d’alignement `0.4.6`, les TODO ciblés et la section de transition du changelog, puis être archivé sous `olddocs/archivekbot3/`.
|
||||
|
||||
## 6. Règles et références à corriger
|
||||
|
||||
Le déplacement des règles secondaires vers `docs/rules/` ne doit pas être effectué dans le premier delta.
|
||||
|
||||
Références actives identifiées :
|
||||
|
||||
- `RULES.md` lie directement les trois fichiers secondaires à la racine ;
|
||||
- les scripts, prompts et documents actifs doivent employer les chemins `docs/rules/...` ;
|
||||
- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` lie `docs/rules/RULES_GENERAL.md` et `docs/rules/RULES_RUST.md` par chemins relatifs racine ;
|
||||
- `scripts/audit_khadhroony_workspace_rules.py` vérifie explicitement les quatre chemins racine à deux endroits ;
|
||||
- les deux prompts bot3 citent les chemins racine ;
|
||||
- `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md` décrit l’organisation actuelle.
|
||||
|
||||
Avant déplacement, il faudra :
|
||||
|
||||
1. modifier `RULES.md` pour pointer vers `docs/rules/` ;
|
||||
2. corriger les liens relatifs internes aux règles ;
|
||||
3. adapter les chemins attendus par `scripts/audit_khadhroony_workspace_rules.py` ;
|
||||
4. vérifier le lanceur `scripts/audit_rust_workspace_rules.py` ;
|
||||
5. corriger README, prompts, documents d’onboarding et checklist de migration ;
|
||||
6. exécuter l’audit workspace et les validations adaptées aux fichiers modifiés avant livraison. Les commandes Git restent sous la responsabilité de l’opérateur et ne font pas partie des validations demandées à la session.
|
||||
|
||||
## 7. Analyse des prompts
|
||||
|
||||
### 7.1 Modèles bot2 à reprendre
|
||||
|
||||
Les meilleurs modèles structurels sont :
|
||||
|
||||
- `prompts/001_version_session_template.md` pour le squelette minimal ;
|
||||
- `prompts/020_v0_4_1_native_solana_programs.md` pour les sources de vérité, le phasage et les critères de sortie ;
|
||||
- `prompts/022_v0_4_3_spl_memo.md` à `026_v0_4_7_metaplex_token_metadata.md` pour la structure numérotée, les frontières, matrices, validations et livraisons.
|
||||
|
||||
### 7.2 Informations bot3 à conserver
|
||||
|
||||
Le futur modèle bot3 doit préserver :
|
||||
|
||||
- l’architecture consolidée autour de `kb-lib`, `kb-store`, `kb-pipeline`, `kb-onchain-transport` et des crates de démonstration ;
|
||||
- les décisions de nommage des crates et binaires ;
|
||||
- les règles Tauri et TS-RS ;
|
||||
- l’état Git et la base d’archive de départ ;
|
||||
- les validations réellement exécutées ;
|
||||
- le statut explicite des surfaces reportées, notamment ElGamal ;
|
||||
- les conventions de delta sans SHA-256 ;
|
||||
- les fichiers normatifs et documents d’architecture à lire.
|
||||
|
||||
### 7.3 Traitement proposé
|
||||
|
||||
Les prompts bot3 existants restent temporairement en place. Après création d’un modèle bot3 et d’un index :
|
||||
|
||||
- le prompt de reprise `pre.062` sera archivé comme preuve de transition ;
|
||||
- le prompt de migration réordonné sera archivé après extraction des décisions encore utiles ;
|
||||
- les futurs prompts actifs seront courts, versionnés par mission et séparés des archives historiques.
|
||||
|
||||
## 8. Classement documentaire proposé
|
||||
|
||||
Arborescence cible à valider progressivement :
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── README.md
|
||||
├── architecture/
|
||||
├── audits/
|
||||
├── decisions/
|
||||
├── generated/
|
||||
├── guides/
|
||||
├── migrations/
|
||||
├── protocols/
|
||||
├── rules/
|
||||
└── validation/
|
||||
```
|
||||
|
||||
Principes de classement :
|
||||
|
||||
- `architecture/` : contrats transversaux et conventions structurelles ;
|
||||
- `audits/` : audits actifs servant une décision non encore clôturée ;
|
||||
- `decisions/` : décisions d’architecture ou de périmètre durables ;
|
||||
- `generated/` : index ou artefacts régénérables explicitement suivis ;
|
||||
- `guides/` : procédures d’utilisation et d’exploitation ;
|
||||
- `migrations/` : correspondances bot2/bot3 et rapports de migration actifs ;
|
||||
- `protocols/` : documents techniques par programme ou famille Solana ;
|
||||
- `rules/` : règles normatives secondaires ;
|
||||
- `validation/` : guides, campagnes et rapports de validation.
|
||||
|
||||
Les déplacements ne doivent commencer qu’après création de `docs/README.md` et correction planifiée de toutes les références.
|
||||
|
||||
## 9. Écarts et contradictions déjà démontrés
|
||||
|
||||
Les écarts suivants sont établis sans nouvel audit fonctionnel des protocoles :
|
||||
|
||||
1. absence volontaire de `olddocs/` dans la base bot3 fournie, à reconstruire depuis l’archive complète bot2 ;
|
||||
2. absence de `docs/README.md` ;
|
||||
3. contrat documentaire incomplet pour les 11 crates ;
|
||||
4. contradiction `USAGES.md` contre `USAGE.md`, résolue en faveur de `USAGE.md` ;
|
||||
5. règles secondaires encore liées à la racine par le code d’audit et les prompts ;
|
||||
6. changelog bot3 ne reprenant pas encore l’historique bot2 ;
|
||||
7. roadmap général encore mélangé à la checklist de migration et aux prereleases ;
|
||||
8. prompts bot3 non encore reconstruits depuis les modèles bot2 ;
|
||||
9. statut documentaire de `kb-wallet` insuffisant au regard de son état d’ébauche ;
|
||||
10. absence de l’audit ciblé `docs/V0_4_6_ALIGNMENT_AUDIT.md`.
|
||||
|
||||
## 10. Ambiguïtés bloquantes
|
||||
|
||||
Aucune ambiguïté ne bloque la première livraison d’audit.
|
||||
|
||||
Les choix suivants restent à trancher avant les deltas de déplacement, mais ne bloquent pas l’archivage documentaire ni la correction des règles :
|
||||
|
||||
- emplacement final de `OPERATION_NAMING_CONVENTION.md` entre `architecture/` et `rules/` ;
|
||||
- maintien temporaire ou archivage immédiat de `IDEA_REMINDERS.md` après ventilation dans les TODO ;
|
||||
- convention de nommage des prompts bot3 actifs et archivés ;
|
||||
- niveau de détail historique conservé dans le changelog général par rapport aux changelogs de crates.
|
||||
|
||||
## 11. Conclusion
|
||||
|
||||
La base technique peut servir à la refonte documentaire, mais elle n’est pas encore démontrée comme officiellement alignée sur `0.4.6`.
|
||||
|
||||
La prochaine étape contrôlée est l’application du plan décrit dans `docs/DOCUMENTATION_REFACTOR_PLAN.md`, par deltas séparés, avant la création de `docs/V0_4_6_ALIGNMENT_AUDIT.md` et avant toute modification des versions Cargo.
|
||||
|
||||
## 12. Précisions acquises après le premier audit
|
||||
|
||||
- L’absence initiale de `olddocs/` dans bot3 était volontaire ; l’archive bot2 fournie séparément évitait une duplication pendant la migration.
|
||||
- Les documents actifs ne seront jamais déplacés ni générés automatiquement depuis `olddocs/archivekbot2/`. Chaque document bot3 sera créé après lecture et adaptation des sources pertinentes.
|
||||
- Les matrices de contrats actives sont déjà centralisées sous `test-fixtures/contract-matrices/` et ne doivent pas être recopiées dans `docs/`.
|
||||
- Le registre ElGamal est implémenté dans `kb-lib`; son intégration pipeline reste à vérifier précisément, son panneau desktop n’est qu’une présentation et son déploiement Devnet/Mainnet ne doit pas être supposé.
|
||||
- La migration bot3 a commencé en cours de `0.4.7` après réalisation du décodeur Metaplex Token Metadata dans bot2 ; ce décodeur existe déjà dans bot3, tandis que le reste de la surface doit être évalué.
|
||||
- La classification des IDL est un besoin actif immédiat à cause du renommage massif déjà effectué. Elle n’est pas reportée à `0.6.x`; seules les infrastructures Anchor supplémentaires relèvent de cette série.
|
||||
- Chaque changelog de crate devra contenir au minimum une section `0.1.0` retraçant sa migration depuis bot2, sa consolidation dans bot3 et l’adoption des nouvelles normes Rust et Khadhroony.
|
||||
- Les TODO pourront intégrer des idées de `docs/IDEA_REMINDERS.md` uniquement après confirmation, attribution, vérification et réordonnancement.
|
||||
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.
|
||||
@@ -0,0 +1,88 @@
|
||||
<!-- file: docs/audits/CRATE_TODO_VERSION_ALIGNMENT_AUDIT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Audit d’alignement des TODO par crate
|
||||
|
||||
## Objectif
|
||||
|
||||
Classer les tâches restantes des onze crates selon leur rapport à l’alignement fonctionnel de `khadhroony-bot3` sur `khadhroony-bot2 0.4.6`, à la reprise de l’objectif `0.4.7` et aux versions ultérieures.
|
||||
|
||||
Cet audit ne constitue pas encore `V0_4_6_ALIGNMENT_AUDIT.md`. Il prépare cet audit en supprimant les ambiguïtés de calendrier dans les TODO.
|
||||
|
||||
## Règles de classement
|
||||
|
||||
### Bloquant avant `0.4.6`
|
||||
|
||||
Une tâche appartient à cette catégorie lorsqu’elle doit démontrer ou rétablir une capacité attendue de bot2 `0.4.6`, ou lorsqu’elle est nécessaire à la clôture documentaire de la migration.
|
||||
|
||||
### Entre `0.4.6` et `0.4.7`
|
||||
|
||||
Cette catégorie contient les travaux nécessaires pour reprendre et achever l’objectif Metaplex Token Metadata interrompu dans bot2.
|
||||
|
||||
### Version ultérieure
|
||||
|
||||
Cette catégorie contient les travaux explicitement planifiés après `0.4.7`, notamment `0.5.x`, `0.6.x`, `0.9.x` et `0.13.x`.
|
||||
|
||||
### Report conditionnel
|
||||
|
||||
Une tâche dépendante d’un déploiement, d’une preuve ou d’une source externe non confirmée n’est pas un blocant de version tant que cette dépendance n’est pas établie.
|
||||
|
||||
## Blocants identifiés avant `0.4.6`
|
||||
|
||||
### `kb-app-demo-desktop`
|
||||
|
||||
- synchronisation complète Tauri/TS-RS ;
|
||||
- couverture explicite des cycles de fenêtres ;
|
||||
- maintien de la session WebSocket après fermeture de `demo_ws` ;
|
||||
- restauration de l’état WebSocket lors de la réouverture.
|
||||
|
||||
Ces points sont des preuves de migration attendues, même lorsque leur comportement paraît déjà implicitement couvert.
|
||||
|
||||
### `kb-pipeline`
|
||||
|
||||
- traitement des écarts concrets révélés par l’audit final ;
|
||||
- guide transversal replay, extraction Core et matérialisation.
|
||||
|
||||
### `kb-onchain-transport`
|
||||
|
||||
- guide transversal RPC, backfill et WebSocket.
|
||||
|
||||
### `kb-store`
|
||||
|
||||
- guide transversal PostgreSQL et contrats de stockage.
|
||||
|
||||
## Travaux entre `0.4.6` et `0.4.7`
|
||||
|
||||
- exécuteur Metaplex Token Metadata dans `kb-lib` ;
|
||||
- vérification et complément de la matérialisation migrée ;
|
||||
- intégration replay et orchestration dans `kb-pipeline` ;
|
||||
- scénarios et validations dans `kb-pipeline-demo-scenarios` ;
|
||||
- panneaux applicatifs dans `kb-app-demo-desktop`.
|
||||
|
||||
## Exceptions documentées
|
||||
|
||||
### Registre ElGamal
|
||||
|
||||
Le registre reste implémenté dans certaines couches, mais sa validation réseau dépend :
|
||||
|
||||
- de la confirmation de son déploiement ;
|
||||
- d’une preuve `PubkeyValidity` ;
|
||||
- d’un compte `Proof Context State` valide.
|
||||
|
||||
Ces tâches restent conditionnelles et ne bloquent pas l’alignement `0.4.6`, à condition que la documentation ne déclare jamais une validation réseau inexistante.
|
||||
|
||||
### `kb-wallet`
|
||||
|
||||
Les capacités avancées sont affectées à `0.5.x`. Le wallet temporaire migré suffit au périmètre historique attendu avant l’alignement.
|
||||
|
||||
### Configuration et logging
|
||||
|
||||
Le split de configuration appartient à `0.5.x` et ne bloque pas `0.4.6`.
|
||||
|
||||
### Transports avancés
|
||||
|
||||
Helius étendu, LaserStream, Yellowstone et la résilience streaming appartiennent à `0.13.x`.
|
||||
|
||||
## Résultat
|
||||
|
||||
Les TODO sont désormais classés par version ou dépendance. Le classement ne prouve pas encore que les blocants `0.4.6` sont satisfaits ; il définit les vérifications à exécuter dans les correctifs de `pre.072` et dans `V0_4_6_ALIGNMENT_AUDIT.md`.
|
||||
Reference in New Issue
Block a user