# 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` ; - `RULES_GENERAL.md` ; - `RULES_RUST.md` ; - `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//README.md olddocs/archivekbot2//CHANGELOG.md olddocs/archivekbot2//.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`. Une contradiction normative existe dans `RULES_GENERAL.md` : le fichier exige encore un `README.md` ou `001.README.md` et, à terme, un `USAGES.md`. La convention retenue est `USAGE.md`, nom singulier couramment utilisé pour un guide d’utilisation. La règle doit imposer exactement `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md`. ### 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 ; - `RULES_GENERAL.md` cite leurs chemins racine et le contrat documentaire obsolète `USAGES.md` ; - `RULES_SPECIFIC_KHADHROONY.md` lie `RULES_GENERAL.md` et `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.