v0.1.0-pre.067
This commit is contained in:
131
docs/README.md
131
docs/README.md
@@ -1,84 +1,77 @@
|
||||
<!-- file: docs/README.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Documentation de `khadhroony-bot3`
|
||||
# Documentation active de Khadhroony Bot3
|
||||
|
||||
## 1. Rôle
|
||||
## 1. Statut
|
||||
|
||||
Ce répertoire contient la documentation active, normative ou encore utilisée de `khadhroony-bot3`.
|
||||
Ce répertoire contient la documentation active, normative ou opérationnelle de `khadhroony-bot3`.
|
||||
|
||||
La documentation historique de `khadhroony-bot2` et les documents bot3 remplacés sont conservés séparément sous `olddocs/`. Un document archivé peut servir de source historique, mais il n’est pas normatif pour l’architecture bot3 actuelle.
|
||||
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. Documents de pilotage actifs
|
||||
## 2. Architecture
|
||||
|
||||
| Document | Rôle |
|
||||
|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
|
||||
| [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md) | inventaire et écarts documentaires de la base `v0.1.0-pre.062` |
|
||||
| [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md) | séquence contrôlée de reconstruction documentaire et d’alignement `0.4.6` |
|
||||
| [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md) | justification durable de la contrainte `wincode 0.5.x` et du contrôle du lockfile |
|
||||
| [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) | critères normatifs de conservation et d’exclusion dans les archives documentaires |
|
||||
- [`architecture/PROJECT_OBJECTIVES.md`](architecture/PROJECT_OBJECTIVES.md) : objectifs et limites du projet ;
|
||||
- [`architecture/ARCHITECTURE.md`](architecture/ARCHITECTURE.md) : couches et flux principaux ;
|
||||
- [`architecture/CRATE_MAP.md`](architecture/CRATE_MAP.md) : responsabilités des 11 crates ;
|
||||
- [`architecture/PIPELINE_ARCHITECTURE.md`](architecture/PIPELINE_ARCHITECTURE.md) : orchestration, replay et exécution ;
|
||||
- [`architecture/STORAGE_ARCHITECTURE.md`](architecture/STORAGE_ARCHITECTURE.md) : contrats de stockage et PostgreSQL ;
|
||||
- [`architecture/SURFACE_CRATE_MATRIX.md`](architecture/SURFACE_CRATE_MATRIX.md) : répartition des responsabilités par surface.
|
||||
|
||||
## 3. Documents existants à reclasser
|
||||
## 3. Règles
|
||||
|
||||
Les documents suivants restent temporairement à leur chemin actuel jusqu’au delta de réorganisation :
|
||||
Le point d’entrée normatif unique est [`../RULES.md`](../RULES.md).
|
||||
|
||||
Règles spécialisées :
|
||||
|
||||
- [`rules/RULES_GENERAL.md`](rules/RULES_GENERAL.md) ;
|
||||
- [`rules/RULES_RUST.md`](rules/RULES_RUST.md) ;
|
||||
- [`rules/RULES_SPECIFIC_KHADHROONY.md`](rules/RULES_SPECIFIC_KHADHROONY.md) ;
|
||||
- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md).
|
||||
|
||||
Modèles documentaires non génératifs :
|
||||
|
||||
- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ;
|
||||
- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ;
|
||||
- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ;
|
||||
- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md).
|
||||
|
||||
## 4. Audits et décisions en cours
|
||||
|
||||
- [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md) ;
|
||||
- [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md) ;
|
||||
- [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ;
|
||||
- [`decisions/WINCODE_COMPATIBILITY_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` ;
|
||||
- `OPERATION_NAMING_CONVENTION.md` ;
|
||||
- `IDL_AUDIT.md` ;
|
||||
- `IDL_TO_KB_LIB_NOMENCLATURE.md` ;
|
||||
- `MISSING_PROGRAM_IDLS.md` ;
|
||||
- `OPERATION_NAMING_CONVENTION.md` ;
|
||||
- `IDEA_REMINDERS.md`.
|
||||
|
||||
Leur présence à la racine de `docs/` est transitoire. Ils ne doivent pas être déplacés avant correction de leurs références.
|
||||
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.
|
||||
|
||||
## 4. Arborescence cible
|
||||
## 6. Matrices contractuelles
|
||||
|
||||
Les matrices canoniques sont conservées sous :
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── README.md
|
||||
├── architecture/
|
||||
├── audits/
|
||||
├── decisions/
|
||||
├── generated/
|
||||
├── guides/
|
||||
├── migrations/
|
||||
├── protocols/
|
||||
├── rules/
|
||||
└── validation/
|
||||
test-fixtures/contract-matrices/
|
||||
```
|
||||
|
||||
Les répertoires sont créés lorsqu’un document réel doit y être classé. Aucun fichier factice n’est requis.
|
||||
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.
|
||||
|
||||
## 5. Archives historiques
|
||||
## 7. Documentation par crate
|
||||
|
||||
### 5.1 Archive bot2
|
||||
|
||||
```text
|
||||
olddocs/archivekbot2/
|
||||
```
|
||||
|
||||
Cette archive reproduit les chemins relatifs des fichiers sélectionnés selon leur fonction documentaire dans l’archive complète bot2 fournie pour la session. La sélection ne dépend pas de l’extension et suit [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md). Elle comprend notamment :
|
||||
|
||||
- les documents racine historiques ;
|
||||
- `docs/` ;
|
||||
- `prompts/` ;
|
||||
- les README, changelogs et autres documents des anciennes crates ;
|
||||
- les matrices, schémas, exemples de configuration et IDL ayant une valeur documentaire démontrée.
|
||||
|
||||
Les fichiers sont conservés sans adaptation de fond. Les liens relatifs peuvent viser l’ancienne arborescence bot2 et ne garantissent pas une navigation fonctionnelle depuis bot3.
|
||||
|
||||
### 5.2 Archive bot3
|
||||
|
||||
```text
|
||||
olddocs/archivekbot3/
|
||||
```
|
||||
|
||||
Cette archive recevra progressivement les audits, plans, prompts et documents bot3 remplacés qui conservent une valeur historique, décisionnelle ou de traçabilité.
|
||||
|
||||
## 6. Contrat documentaire des crates
|
||||
|
||||
Chaque crate doit finalement posséder exactement :
|
||||
Chaque crate devra posséder :
|
||||
|
||||
```text
|
||||
README.md
|
||||
@@ -87,26 +80,4 @@ USAGE.md
|
||||
CHANGELOG.md
|
||||
```
|
||||
|
||||
`USAGE.md` est la convention retenue. La variante `USAGES.md` est obsolète.
|
||||
|
||||
Le contenu attendu de chaque fichier est défini par [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md). Les modèles de `docs/templates/` servent uniquement d’aide à la rédaction.
|
||||
|
||||
## 7. Règles de consultation
|
||||
|
||||
Ordre recommandé :
|
||||
|
||||
1. `RULES.md` à la racine du workspace ;
|
||||
2. les règles secondaires à leur emplacement normatif courant ;
|
||||
3. le présent index ;
|
||||
4. les documents d’architecture ou de validation liés à la tâche ;
|
||||
5. `olddocs/` uniquement pour l’historique ou la reprise contrôlée d’informations.
|
||||
|
||||
## Règles et modèles documentaires
|
||||
|
||||
- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md) : contrat normatif des quatre documents de chaque crate ;
|
||||
- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ;
|
||||
- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ;
|
||||
- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ;
|
||||
- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md).
|
||||
|
||||
Les modèles ne doivent jamais être remplis mécaniquement : la rédaction exige la lecture du code, des exports publics, des tests et des sources historiques pertinentes.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user