khadhroony-bot3/docs/README.md

Documentation active de Khadhroony Bot3

1. Statut

Ce répertoire contient la documentation active, normative ou opérationnelle de khadhroony-bot3.

La documentation historique de khadhroony-bot2 est conservée sous olddocs/archivekbot2/. Elle ne doit être ni déplacée vers docs/, ni considérée comme normative. Tout nouveau document bot3 est réécrit après lecture du code, des tests, des matrices et des sources historiques pertinentes.

2. Architecture

• architecture/PROJECT_OBJECTIVES.md : objectifs et limites du projet ;
• architecture/ARCHITECTURE.md : couches et flux principaux ;
• architecture/CRATE_MAP.md : responsabilités des 11 crates ;
• architecture/PIPELINE_ARCHITECTURE.md : orchestration, replay et exécution ;
• architecture/STORAGE_ARCHITECTURE.md : contrats de stockage et PostgreSQL ;
• architecture/SURFACE_CRATE_MATRIX.md : répartition des responsabilités par surface.

3. Règles

Le point d’entrée normatif unique est ../RULES.md.

Règles spécialisées :

• rules/RULES_GENERAL.md ;
• rules/RULES_RUST.md ;
• rules/RULES_SPECIFIC_KHADHROONY.md ;
• rules/CRATE_DOCUMENTATION_RULES.md.

Modèles documentaires non génératifs :

• templates/CRATE_README_TEMPLATE.md ;
• templates/CRATE_TODO_TEMPLATE.md ;
• templates/CRATE_USAGE_TEMPLATE.md ;
• templates/CRATE_CHANGELOG_TEMPLATE.md.

4. Audits et décisions en cours

• DOCUMENTATION_REFACTOR_AUDIT.md ;
• DOCUMENTATION_REFACTOR_PLAN.md ;
• decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md ;
• decisions/WINCODE_COMPATIBILITY_POLICY.md.

Ces audits seront archivés sous olddocs/archivekbot3/ lorsqu’ils auront été remplacés par des documents normatifs ou des rapports de clôture.

5. Documents techniques actifs à reclasser

Les documents suivants restent actifs mais seront reclassés progressivement après correction de leurs références :

• DEVNET_EXECUTION_GUIDE.md ;
• PRE_062_DEVNET_VALIDATION_REPORT.md ;
• IDL_AUDIT.md ;
• IDL_TO_KB_LIB_NOMENCLATURE.md ;
• MISSING_PROGRAM_IDLS.md ;
• OPERATION_NAMING_CONVENTION.md ;
• IDEA_REMINDERS.md.

Les idées de IDEA_REMINDERS.md ne doivent rejoindre un TODO.md de crate qu’après confirmation, attribution et reformulation en tâche vérifiable.

6. Matrices contractuelles

Les matrices canoniques sont conservées sous :

test-fixtures/contract-matrices/

Elles peuvent être chargées directement par les tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées sous docs/. Les documents actifs peuvent les référencer et expliquer leur rôle.

7. Documentation par crate

Chaque crate devra posséder :

README.md
TODO.md
USAGE.md
CHANGELOG.md

Leur création commencera après stabilisation des documents transversaux, par lots de crates. USAGE.md documentera les APIs publiques réelles et pourra signaler les tests particulièrement instructifs.

Documentation des crates

Le premier lot documenté comprend :

• kb-lib ;
• kb-store ;
• kb-config ;
• kb-logging.