khadhroony-bot3/olddocs/archivekbot3/docs/DOCUMENTATION_REFACTOR_AUDIT.md

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 :

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 :

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.

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 :

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.