Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e0028b323e5e1fcd3c9f4411b7f4a40b4a0b1220
khadhroony-bot3/docs/DOCUMENTATION_REFACTOR_AUDIT.md
SinuS Von SifriduS e0028b323e v0.1.0-pre.063
2026-07-30 14:32:30 +02:00

13 KiB
Raw Blame History

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/

Le répertoire olddocs/ n’existe pas dans l’archive bot3 fournie. Il n’y a donc aucun contenu bot3 à préserver sous ce chemin dans cette base précise.

La reconstruction devra créer deux archives séparées :

olddocs/archivekbot2/
olddocs/archivekbot3/

La totalité de khadhroony-bot2/docs/ devra être copiée dans olddocs/archivekbot2/ sans réécriture de fond. L’archive source fournie ne doit évidemment pas être modifiée. 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 retenu pour la suite doit être une copie depuis l’archive bot2, et non un déplacement destructif.

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. Cette formulation doit être remplacée par le contrat acquis utilisant exactement README.md, TODO.md, USAGE.md et CHANGELOG.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 et git diff --check avant livraison.

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 de olddocs/ dans la base bot3 fournie ;
  2. absence de docs/README.md ;
  3. contrat documentaire incomplet pour les 11 crates ;
  4. contradiction USAGES.md contre 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 doivent être validés avant les deltas de déplacement, mais peuvent être traités par propositions réversibles :

  • 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.

Reference in New Issue View Git Blame Copy Permalink