0.0.5-alpha.5

docs/000-README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/000-README.md -->
-<!-- version: 12 -->
+<!-- version: 13 -->
 
 # Documentation PGR
 
@@ -26,6 +26,7 @@ Les templates techniques copiables sous `templates/` restent séparés des instr
 - [`studies/001-KSP_GAMES_RECONCILIATION.md`](studies/001-KSP_GAMES_RECONCILIATION.md) — inventaire comparatif des baselines KSP/Games et décisions de généralisation, maintien local ou différé.
 - [`templates/004-FILE_FAMILY_CONTRACTS.md`](templates/004-FILE_FAMILY_CONTRACTS.md) — pattern facultatif pour expliciter les responsabilités et règles de modification de familles de fichiers locales lorsque la complexité le justifie.
 - [`templates/005-RELEASE_PLAN.md`](templates/005-RELEASE_PLAN.md) — pattern de plan de release avec clôture/transition explicites et revue d'horizon proportionnée.
+- [`validation/003-RUST_EXPORT_COMPLETENESS.md`](validation/003-RUST_EXPORT_COMPLETENESS.md) — contrat, provenance et limites de l'audit Rust facultatif de façade crate-root.
 
 ## Points d'entrée de 0.0.4
 
@@ -36,4 +37,4 @@ Les templates techniques copiables sous `templates/` restent séparés des instr
 - [`skeletons/002-RUST_CARGO_WORKSPACE.md`](skeletons/002-RUST_CARGO_WORKSPACE.md) — specialization Rust/Cargo workspace composable avec la fondation et les cinq templates existants ;
 - [`templates/001-RUST_CARGO_TOOLING.md`](templates/001-RUST_CARGO_TOOLING.md) et [`templates/002-CARGO_MANIFESTS.md`](templates/002-CARGO_MANIFESTS.md) — adaptation des cinq fichiers Rust/Cargo copiables ;
 - [`templates/003-NEW_SESSION_PROMPT.md`](templates/003-NEW_SESSION_PROMPT.md) — spécification du message manuel après une stable publiée ;
-- [`validation/001-VALIDATION_MATRIX.md`](validation/001-VALIDATION_MATRIX.md) et [`validation/002-RUST_STYLE_AUDITS.md`](validation/002-RUST_STYLE_AUDITS.md) — gates PGR et limites des audits de style Rust facultatifs.
+- [`validation/001-VALIDATION_MATRIX.md`](validation/001-VALIDATION_MATRIX.md), [`validation/002-RUST_STYLE_AUDITS.md`](validation/002-RUST_STYLE_AUDITS.md) et [`validation/003-RUST_EXPORT_COMPLETENESS.md`](validation/003-RUST_EXPORT_COMPLETENESS.md) — gates PGR et limites des audits Rust facultatifs.

docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Plan 0.0.5 — réconciliation réelle avec KSP et sasedev-games
 
@@ -84,6 +84,10 @@ Cette tranche ne commence pas l'audit Rust ni le profil Tauri.
 
 Extraire le noyau réellement commun de `audit_rust_export_completeness.py`, l'aligner avec `510-RUST_CARGO.md`, documenter son caractère facultatif et ses limites, et ajouter des tests positifs/négatifs.
 
+La réconciliation a révélé que le script historique ne découvrait que `crates/*/Cargo.toml` : il couvrait les `22` crates KSP mais aucune des `23` crates Games imbriquées sous des sous-familles. La variante PGR doit donc corriger la découverte récursive avant toute généralisation. Elle doit également abandonner les sous-règles historiques de tests séparés et la duplication de résolution de noms déjà possédée par le compilateur.
+
+Mesure de référence avec le scope PGR retenu : `KSP = 0 candidate(s) / 22 crates`, `Games = 2 candidate(s) / 23 crates`. Les deux signaux Games sont une observation de réconciliation, pas une non-conformité rétroactive.
+
 Cette tranche ne réimporte pas `audit_rust_general_rules.py` en bloc. Toute règle déjà possédée par Rustfmt, Clippy, le compilateur ou les audits PGR existants reste chez son owner actuel.
 
 ### alpha.6 — premier profil framework : Tauri

docs/rules/510-RUST_CARGO.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/510-RUST_CARGO.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Profil Rust / Cargo
 
@@ -192,4 +192,8 @@ Lorsqu'une règle Rust devient objectivement automatisable dans un projet ou ske
 
 Un éventuel wrapper d'orchestration MAY appeler plusieurs audits, mais chaque audit propriétaire doit conserver une responsabilité identifiable et rester read-only.
 
-Les deux audits de style disponibles sont documentés dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md). Ils restent optionnels et prennent un corpus Rust explicitement sélectionné ; le dépôt PGR lui-même ne contient pas de workspace Rust sur lequel une telle gate fournirait une preuve réelle.
+Les deux audits de style disponibles sont documentés dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md). Ils restent optionnels et prennent un corpus Rust explicitement sélectionné.
+
+[`../validation/003-RUST_EXPORT_COMPLETENESS.md`](../validation/003-RUST_EXPORT_COMPLETENESS.md) documente séparément un audit facultatif de façade crate-root. Lorsqu'un projet choisit ce contrat strict, les éléments `pub` des modules fichiers et les éléments `pub(crate)` clairement partagés hors de leur module SHOULD être réexportés explicitement au crate-root ; lorsqu'un tel réexport existe, les chemins internes SHOULD employer `crate::Item` plutôt que `crate::module::Item`.
+
+Cet audit de façade ne rend pas la règle obligatoire pour tous les projets Rust et ne remplace pas le compilateur. Le dépôt PGR lui-même ne contient pas de workspace Rust sur lequel une telle gate fournirait une preuve runtime ou Cargo réelle.

docs/skeletons/002-RUST_CARGO_WORKSPACE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/skeletons/002-RUST_CARGO_WORKSPACE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Skeleton — Rust/Cargo workspace
 
@@ -57,7 +57,7 @@ templates/rust-cargo/Cargo.toml
 templates/rust-cargo/crates/project-core-lib/Cargo.toml
 ```
 
-[`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md) est seulement une option supplémentaire. Les scripts `audit_rust_blank_lines.py`, `audit_rust_const_blocks.py` et `_rust_audit_common.py` ne sont copiés que si le projet choisit explicitement les conventions correspondantes et sait quels fichiers Rust doivent être audités.
+[`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md) et [`../validation/003-RUST_EXPORT_COMPLETENESS.md`](../validation/003-RUST_EXPORT_COMPLETENESS.md) sont seulement des options supplémentaires. Les scripts Rust PGR ne sont copiés que si le projet choisit explicitement les conventions correspondantes. Le helper `_rust_audit_common.py` peut être partagé entre ces audits.
 
 ## Décisions destinataire avant copie
 
@@ -72,7 +72,7 @@ Avant de considérer la specialization comme instanciée, résoudre explicitemen
 7. les niveaux de lints hérités, les éventuelles exceptions locales et tout besoin réel d'`unsafe` dans un scope étroit ;
 8. les paramètres `rustfmt.toml` et `clippy.toml` à conserver ou adapter ;
 9. l'emplacement des artefacts Cargo et l'identifiant unique utilisé dans `.cargo/config.toml` si cette politique externe au dépôt est retenue ;
-10. les audits de style Rust facultatifs réellement adoptés et leur corpus exact ;
+10. les audits Rust facultatifs réellement adoptés, dont éventuellement le contrat de façade crate-root, et leur scope exact ;
 11. les validations Cargo réellement nécessaires au code et aux manifests créés.
 
 Les valeurs `0.1.0`, `2024`, `project-name`, `project-core-lib`, les seuils Clippy et les chemins de build présents dans les templates sont des exemples ou baselines à revoir. Ils ne deviennent jamais des valeurs universelles par simple copie.
@@ -127,11 +127,11 @@ L'édition de `rustfmt.toml` doit rester cohérente avec le workspace. Les seuil
 
 Décider explicitement si `Cargo.lock` est versionné selon le type de produit, le mode de publication et le besoin de reproductibilité. La présence ou l'absence du lockfile dans un projet source historique ne constitue pas une règle suffisante pour le nouveau workspace.
 
-### Audits de style facultatifs
+### Audits Rust facultatifs
 
-Si le projet adopte les conventions documentées dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md), copier les trois scripts concernés et adapter leurs headers à leurs chemins locaux.
+Si le projet adopte les conventions documentées dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md), copier les scripts de style concernés et adapter leurs headers à leurs chemins locaux. La sélection des fichiers doit rester explicite. En particulier, l'audit des blocs de constantes ne doit jamais réordonner une table de protocole, une séquence de migrations ou toute autre structure dont l'ordre possède une sémantique propre.
 
-La sélection des fichiers doit rester explicite. En particulier, l'audit des blocs de constantes ne doit jamais réordonner une table de protocole, une séquence de migrations ou toute autre structure dont l'ordre possède une sémantique propre.
+Si le projet adopte le contrat de façade décrit dans [`../validation/003-RUST_EXPORT_COMPLETENESS.md`](../validation/003-RUST_EXPORT_COMPLETENESS.md), copier `audit_rust_export_completeness.py` avec `_rust_audit_common.py`. Une adoption d'un projet existant SHOULD commencer en `--report-only`, résoudre les écarts ou exceptions locales, puis seulement rendre l'audit bloquant.
 
 Ne pas copier ces scripts uniquement parce qu'ils existent dans PGR.
 
@@ -150,7 +150,7 @@ cargo clippy --workspace --all-targets --all-features -- -D warnings
 
 Ajouter des tests ciblés pour les crates qui possèdent déjà un comportement à vérifier. Un `cargo build` n'est nécessaire que lorsqu'un artefact de build doit réellement être produit.
 
-Si les audits de style facultatifs ont été sélectionnés, les exécuter après le formatage sur les seuls chemins concernés.
+Si des audits Rust facultatifs ont été sélectionnés, exécuter les audits de style après formatage sur les seuls chemins concernés et l'audit de façade sur la racine du projet une fois son contrat explicitement adopté.
 
 La validation doit aussi confirmer :
 

docs/studies/001-KSP_GAMES_RECONCILIATION.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/001-KSP_GAMES_RECONCILIATION.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Étude de réconciliation PGR / KSP / sasedev-games
 
@@ -133,6 +133,12 @@ Décision : classer ce contrôle `COMMON`, mais ne pas copier le script tel quel
 3. fournir des tests positifs/négatifs ciblés et documenter les limites du parsing lexical ;
 4. éviter de réintroduire les règles déjà possédées par Rustfmt, Clippy ou les deux audits de style PGR existants.
 
+#### Mesure alpha.5
+
+La relecture du script historique révèle une limite importante : sa découverte `crates/*/Cargo.toml` couvre les `22` crates KSP placées directement sous `crates/`, mais aucune des `23` crates Games imbriquées sous `crates/apps`, `crates/common`, `crates/engines`, etc. Le code des deux scripts est bien commun, mais le résultat historique Games `0 candidate(s)` n'était pas une preuve d'audit des crates réelles.
+
+La variante PGR corrige la découverte récursive et réduit le scope aux deux propriétés effectivement possédées par `510-RUST_CARGO.md` : complétude de la façade crate-root et canonicalisation d'un chemin interne lorsqu'un réexport explicite existe. Avec cette variante, KSP donne `0 candidate(s)` sur `22` crates et Games `2 candidate(s)` sur `23` crates. Ces deux signaux Games ne sont pas des non-conformités rétroactives ; ils deviennent des points de décision lors d'une future adoption PGR.
+
 Le grand `audit_rust_general_rules.py` des deux corpus reste `DEFER` comme source d'extraction, pas comme script à importer. Il mélange plusieurs responsabilités : headers, rustdoc, imports, structure de façade, blancs, constantes et règles locales ; Games y ajoute une exception FFI Android étroite. PGR doit continuer à extraire des audits monotâches seulement lorsqu'une propriété commune apporte une preuve non redondante.
 
 L'orchestrateur `audit_rust_workspace_rules.py` est un pattern d'ergonomie utile mais ne possède aucune règle. PGR peut documenter comment composer des audits sélectionnés dans un projet destinataire sans fournir un lanceur universel qui supposerait les mêmes scripts partout.

docs/validation/001-VALIDATION_MATRIX.md

@@ -1,5 +1,5 @@
 <!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
-<!-- version: 10 -->
+<!-- version: 11 -->
 
 # Matrice de validation PGR
 
@@ -41,6 +41,8 @@ PGR préfère plusieurs audits simples avec une responsabilité identifiable à
 
 Leur disponibilité ne transforme pas PGR en workspace Rust et ne rend pas automatiquement l'ordre alphabétique applicable à chaque fichier d'un projet. Lors d'une adoption, le projet propriétaire sélectionne ses chemins après `cargo fmt` et applique sa propre gate ; Rustfmt et Clippy conservent les contrôles qu'ils possèdent.
 
+[`003-RUST_EXPORT_COMPLETENESS.md`](003-RUST_EXPORT_COMPLETENESS.md) décrit séparément `audit_rust_export_completeness.py`, audit facultatif de façade crate-root. Sa validation ciblée dans PGR est `python3 -B -m unittest discover -s tests -p test_rust_export_completeness.py -v`. L'audit est destiné aux projets Rust qui choisissent explicitement ce contrat ; PGR n'exécute pas ce script sur son propre dépôt comme gate, car il ne constitue pas lui-même un workspace Rust.
+
 ## Politique Eclipse actuelle
 
 Les métadonnées Eclipse spécifiques à une machine restent ignorées, notamment `.project`, `.classpath` et les préférences non partagées.

docs/validation/003-RUST_EXPORT_COMPLETENESS.md

@@ -0,0 +1,83 @@
+<!-- file: docs/validation/003-RUST_EXPORT_COMPLETENESS.md -->
+<!-- version: 1 -->
+
+# Audit facultatif de façade Rust et export completeness
+
+## Responsabilité
+
+`scripts/audit_rust_export_completeness.py` contrôle un contrat Rust optionnel plus strict que les garanties du compilateur : les éléments publics durables d'un module fichier doivent être exposés par une façade explicite au crate-root, et le code de la même crate doit employer cette façade lorsqu'un réexport correspondant existe.
+
+Le propriétaire normatif reste [`../rules/510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). Le script ne définit pas une architecture à lui seul et ne doit être adopté que par un projet qui choisit ce contrat de façade.
+
+L'audit émet seulement deux familles de diagnostics :
+
+```text
+RUST-API-201
+    élément `pub`, ou élément `pub(crate)` clairement consommé hors de son module fichier,
+    sans réexport explicite correspondant au crate-root
+
+RUST-IMPORT-201
+    chemin interne long `crate::module::Item` alors que le crate-root expose déjà `crate::Item`
+```
+
+Il ne vérifie pas les règles générales de style, les lignes vides, l'ordre des constantes, la rustdoc, les lints Cargo/Clippy, la sûreté FFI ou le contenu métier.
+
+## Provenance et correction du corpus
+
+KSP `0.3.16` et Games `0.3.5` contiennent un `audit_rust_export_completeness.py` dont le corps est identique à l'exception de sa révision de fichier. Cette convergence justifie l'extraction du concept, mais pas une copie littérale.
+
+Le script historique découvre uniquement `crates/*/Cargo.toml`. Cette hypothèse couvre les `22` crates KSP situées directement sous `crates/`, mais elle ne couvre aucune des `23` crates Games organisées sous des sous-familles telles que `crates/apps/`, `crates/common/` ou `crates/engines/`. Un résultat historique `0 candidate(s)` dans Games ne constitue donc pas une preuve que ses crates avaient réellement été inspectées par cet audit.
+
+La variante PGR corrige ce point en découvrant récursivement les packages Cargo possédant `src/lib.rs` ou `src/main.rs`, tout en ignorant les arbres générés usuels. Elle gère également correctement un module fichier `mod.rs` et les réexports explicites simples, groupés ou aliasés.
+
+La réconciliation générateur réalisée pendant `0.0.5-alpha.5` donne avec la nouvelle découverte :
+
+```text
+KSP 0.3.16   22 crate(s)   0 candidate(s)
+Games 0.3.5  23 crate(s)   2 candidate(s)
+```
+
+Les deux candidats Games sont des constantes `pub(crate)` du smoke WebTransport navigateur consommées depuis d'autres modules sans façade crate-root. Games n'étant pas encore gouverné par PGR, ces signaux ne sont pas qualifiés de défauts rétroactifs ; ils montrent simplement ce qu'une adoption future de ce contrat devrait décider ou corriger.
+
+## Ce qui n'est pas repris du script historique
+
+PGR n'importe pas les diagnostics historiques liés aux tests unitaires séparés (`super::...`, références non qualifiées) : leur validité dépend du layout et du contrat local des modules de test, et la baseline Games ne prouve pas une convergence opérationnelle sur ce point.
+
+PGR n'importe pas non plus le contrôle d'un `crate::Symbol` non résolu. Le compilateur Rust est déjà propriétaire de la résolution de noms ; dupliquer cette erreur dans un audit Python n'apporte pas une preuve supplémentaire proportionnée.
+
+L'audit PGR reste donc monotâche : façade crate-root et canonicalisation des chemins pour les seuls symboles qu'il sait relier explicitement.
+
+## Adoption
+
+Pour adopter cette convention dans un projet Rust, copier :
+
+```text
+scripts/_rust_audit_common.py
+scripts/audit_rust_export_completeness.py
+```
+
+puis adapter les headers de fichiers au dépôt destinataire.
+
+Commande canonique :
+
+```bash
+python3 -B scripts/audit_rust_export_completeness.py --root .
+```
+
+Le code de sortie est `0` lorsque le corpus est propre, `1` lorsqu'au moins un candidat est trouvé et `2` lorsque la racine est invalide, illisible ou ne contient aucune crate Rust détectable. `--report-only` permet une phase d'inventaire sans bloquer la gate ; `--summary-only` réduit la sortie aux comptes.
+
+Une adoption progressive peut donc commencer par :
+
+```bash
+python3 -B scripts/audit_rust_export_completeness.py --root . --report-only
+```
+
+puis devenir bloquante une fois les exceptions ou écarts locaux explicitement résolus.
+
+## Limites
+
+L'analyse est lexicale et non un parseur Rust complet. Elle vise les déclarations `pub`/`pub(crate)` au niveau racine de modules fichiers et les réexports explicites du crate-root. Les macros générant des items, attributs élaborés, modules inline complexes, `#[path]` non standard et formes de réexport imbriquées au-delà du contrat testé peuvent nécessiter une revue humaine ou les outils Rust du projet.
+
+Un élément `pub(crate)` n'est exigé à la façade que lorsqu'une consommation externe au fichier est clairement détectée par un chemin `crate::module::Item` ou `crate::Item`. L'absence de diagnostic ne prouve donc pas toute la sémantique de visibilité de la crate.
+
+L'audit ne remplace ni `cargo check`, ni Clippy, ni rustdoc. Il complète uniquement une convention architecturale explicitement choisie.