pgr/docs/studies/001-KSP_GAMES_RECONCILIATION.md

Étude de réconciliation PGR / KSP / sasedev-games

Objet et statut des corpus

Cette étude exécute l'inventaire demandé par prompts/005-V0_0_5_START_PROMPT.md avant toute modification normative importante de 0.0.5.

khadhroony-solana-project et sasedev-games sont ici des corpus de conception et de réconciliation. Ils n'ont pas encore adopté PGR comme référentiel de gouvernance. Une divergence observée dans leurs baselines ne constitue donc pas une non-conformité PGR et ne doit pas être « corrigée » rétroactivement dans ces projets pendant cette release.

La question utile est différente : quelles responsabilités déjà éprouvées doivent rester locales, lesquelles sont déjà correctement possédées par PGR, et lesquelles révèlent un besoin générique suffisamment réutilisable pour améliorer PGR avant une future adoption ?

Sources autoritaires contrôlées

PGR

Baseline : archive source pgr-v0.0.4.zip, annoncée comme téléchargement du tag Gitea v0.0.4, accompagnée du rapport externe pgr-0.0.4-publish.001-report.md avec statut PASS.

SHA-256  7137bb084f017362323a2043d13ba71490be15b8786adc8d645981bf455b80ae
entrées  167
fichiers 139
répertoires 28
racine   pgr/
CRC      clean
.git     absent

Aucun doublon ZIP, collision de casse, chemin dangereux ou lien symbolique n'a été détecté. Les 15 tests Python PGR passent ; les audits Markdown affichent 123 fichiers contrôlés, 3 tableaux propres et 116 liens locaux propres. Les cinq fichiers TOML du template Rust/Cargo se parsèrent correctement.

Le rapport post-tag donne le même hash et sépare explicitement la preuve de publication de l'état contenu dans l'archive.

khadhroony-solana-project

Baseline autoritaire fournie : khadhroony-solana-project-v0.3.16.zip.

SHA-256  db3cc1b3fc3fb07ee864b02e2a7346c673d4cf63b33e8e872aca6c6458856ca0
entrées  2229
fichiers 2017
répertoires 212
racine   khadhroony-solana-project/
CRC      clean
.git     absent

Aucun doublon ZIP, collision de casse, chemin dangereux ou lien symbolique n'a été détecté. Les audits Python fournis par la baseline passent :

General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (352 table(s), 962 file(s))

sasedev-games

Baseline autoritaire fournie : games-v0.3.5.zip.

SHA-256  5f5fdee1a271386766d059657d6eaa831acdc263b3e722fed738808335c0a105
entrées  664
fichiers 508
répertoires 156
racine   games/
CRC      clean
.git     absent

Aucun doublon ZIP, collision de casse, chemin dangereux ou lien symbolique n'a été détecté. Les audits Python fournis par la baseline passent :

General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
games.sasedev workspace audit: clean
Markdown table audit: clean (5 table(s), 304 file(s))
Distribution layout audit: clean (66 required path(s), 8 forbidden path(s) absent)

La toolchain cargo n'est pas disponible dans l'environnement utilisé pour cette étude ; aucun cargo metadata, build, test ou Clippy externe n'est donc présenté comme exécuté ici. Cette limite n'empêche pas l'inventaire documentaire et statique demandé à alpha.1 et ne transforme pas les audits Python en preuve de compilation.

Méthode de classification

Chaque propriété observée est classée selon l'un des états suivants :

OWNED       déjà correctement possédée par PGR ; l'usage local ne crée pas de nouvelle règle
COMMON      besoin générique réel insuffisamment matérialisé dans PGR ; candidat de 0.0.5
LOCAL       besoin spécifique au projet, à son architecture, son domaine ou sa plateforme
LEGACY      divergence historique ou duplication locale à considérer lors d'une future adoption, pas à corriger ici
DEFER       preuve insuffisante pour créer maintenant un owner PGR durable

La classification porte sur les responsabilités et contrats, pas sur la simple ressemblance des noms de fichiers.

Réconciliation de la gouvernance et de la documentation

Sujet observé	KSP / Games	Classification	Décision PGR
hiérarchie normative et exceptions bornées	présente dans les deux corpus	OWNED	RULES.md et le modèle de profils possèdent déjà ce contrat ; ne pas recopier les règles locales
langue code/chemins anglais, documentation interne française	commune	OWNED	déjà possédée par RULES.md et 300-DOCUMENTATION.md
rôles de README, RULES, ROADMAP, CHANGELOG, plans et documents durables	largement communs	OWNED	300-DOCUMENTATION.md couvre déjà les rôles génériques
headers internes file / version	communs	OWNED	déjà possédés et audités par PGR ; les règles locales plus strictes restent locales tant qu'elles ajoutent une sémantique propre
FILE_CONTRACTS.md local décrivant responsabilité et règle de modification des familles importantes	présent dans les deux corpus	COMMON	fournir un pattern/template documentaire facultatif et l'intégrer à la fondation seulement lorsque la complexité du projet le justifie
prompt de démarrage autonome avec baseline, ordre de lecture, état validé, mission, hors-scope, première gate et validation	présent dans les deux corpus	COMMON	renforcer le contrat générique des prompts PGR et fournir une spécification réutilisable ; ne pas copier les commandes KSP/Games
règle « une version complète par session »	explicitement forte dans Games, structurante dans certaines pratiques locales	LOCAL	PGR conserve sa règle actuelle : une session ne force pas artificiellement une version ; un projet peut ajouter une contrainte locale plus forte
couloirs exacts de fermeture et numérotation de prereleases	plus détaillés dans KSP/Games	DEFER	conserver le principe PGR de consolidation/RC/stable ; ne pas généraliser des numéros ou un nombre fixe de tranches
absence de history/ dans KSP v0.3.16 et historique partiel dans Games	divergence de workflow antérieure à l'adoption de PGR	LEGACY	ne pas créer de dette rétroactive ; une future adoption décide son point de départ et ne réécrit pas l'historique

Réconciliation de la validation

PGR possède déjà le besoin générique le plus important : sélectionner les preuves à partir du scope, des risques invalidés et de la maturité, avec une matrice canonique facultative pour les projets suffisamment structurés.

Les matrices et documents de validation de Games et KSP confirment plusieurs pratiques déjà couvertes : tests ciblés pendant le développement, gates plus larges aux frontières de maturité, contrôles de dépendances seulement lorsqu'ils apportent une preuve, et distinction entre audit statique, build, smoke et diagnostic. Ces éléments restent OWNED.

Les audits spécialisés restent locaux :

• audit_ksp_workspace_rules.py contrôle des frontières, dépendances et conventions propres à KSP ;
• audit_distribution_layout.py contrôle le layout et plusieurs intégrations Web/Android/Gradle propres à Games ;
• ces scripts ne doivent pas être copiés dans PGR ni transformés en audits universels.

Réconciliation Rust/Cargo

Les travaux 0.0.3 et 0.0.4 ont déjà absorbé les parties génériques évidentes des deux corpus : workspace Cargo, héritage des métadonnées et lints, templates rustfmt.toml/clippy.toml/.cargo/config.toml, manifests, safety/FFI bornée et audits de style ciblés. Ces propriétés restent OWNED.

Un besoin commun reste cependant suffisamment net pour être repris : les deux projets contiennent audit_rust_export_completeness.py avec le même contrat et le même corps fonctionnel à l'exception de la révision de fichier. Il contrôle la complétude de façade crate-root et les chemins canoniques associés, propriété que Rustfmt et Clippy ne possèdent pas. Le profil 510 décrit déjà cette architecture comme convention recommandée.

Décision : classer ce contrôle COMMON, mais ne pas copier le script tel quel en alpha.1. Une tranche dédiée doit d'abord :

1. séparer ce qui dépend du profil Rust général de ce qui dépend d'un style KSP/Games plus strict ;
2. conserver l'audit facultatif tant que la façade crate-root n'est qu'un SHOULD du profil ;
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 d'abord la découverte récursive. La revue opérateur de alpha.5 montre ensuite que limiter la canonicalisation à crate::module::Item est insuffisant : les corpus contiennent de nombreuses références nues à des items pourtant réexportés, notamment dans leur module propriétaire, et ni rustc ni Clippy ne possèdent la convention « référence partagée = crate::Item partout dans la crate ». alpha.5 est donc conservé FAIL et alpha.5.fix.1 étend RUST-IMPORT-201 à ce contrat réel.

La mesure corrigée, avec découverte récursive et séparation des cibles Cargo, donne 1525 lignes candidates RUST-IMPORT-201 dans KSP sur 22 packages et 181 lignes candidates dans Games sur 23 packages (2 RUST-API-201, 179 RUST-IMPORT-201). Ces volumes ne sont pas interprétés comme des défauts rétroactifs : ils montrent précisément pourquoi une adoption PGR d'un projet existant doit commencer en --report-only, puis migrer progressivement la convention avant d'en faire une gate bloquante.

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.

Réconciliation des frameworks et plateformes

Tauri

Tauri est réellement présent dans les deux corpus et n'est plus un exemple isolé : KSP contient 6 applications Desk Tauri et Games 2 hôtes Tauri. Les 8 applications observées utilisent Tauri 2, un package Rust avec tauri-build, une configuration tauri.conf.json, des capability files, des hooks frontend et un frontendDist dédié.

Les différences sont tout aussi importantes que les points communs : KSP possède deux fenêtres par Desk, active le bundling et utilise des hooks npm simples ; Games utilise une fenêtre, désactive le bundling dans les POC observés et l'un de ses hooks construit d'abord un frontend WASM via un script Python. Les CSP, ports, identifiants, ressources et plugins ne sont pas uniformes.

Toutes les configurations observées omettent une version Tauri explicite tandis que leur package Cargo hérite de la version workspace. Cette pratique est compatible avec le mécanisme Tauri 2 qui peut utiliser la version du package Cargo lorsque tauri.conf n'en fournit pas ; elle donne une base commune utile pour éviter une duplication de version dans un projet à release train unique.

Les deux corpus versionnent leurs capability files et ignorent les dépendances/sorties frontend reproductibles. Ils ignorent également gen/, mais ce dernier point n'est pas généralisé : les projets mobiles Tauri peuvent contenir sous leur projet généré des personnalisations de plateforme intentionnelles qui doivent être classifiées avant toute politique Git.

Décision alpha.6 : classer Tauri COMMON, activer 700-FRAMEWORKS.md et créer 710-TAURI.md. Le profil possède l'orchestration Tauri : host Rust, configuration/capabilities, hooks frontend, version produit et gates d'intégration. Il ne possède pas Vite, WASM, npm, les ports, fenêtres, CSP, bundles ou plugins particuliers.

La règle de validation commune est également confirmée : lorsqu'une propriété dépend de beforeDevCommand, beforeBuildCommand, frontendDist, des capabilities ou du bundling, une sous-commande directe telle que npm run build ou cargo build ne prouve pas l'intégration Tauri complète. La gate doit passer par le CLI Tauri ou une forme officiellement équivalente ; les sous-commandes restent pertinentes pour leurs preuves ciblées.

Une skeleton specification Tauri reste reportée à alpha.7, où elle doit démontrer une valeur de composition réelle sans fabriquer un tauri.conf.json universel.

Web / Vite / WASM

Les deux corpus utilisent Vite dans leurs applications Tauri, mais le Web autonome et la chaîne WASM sont beaucoup plus développés dans Games. Cette preuve suffit à renseigner un futur profil, pas à créer maintenant une règle Web universelle. Classification : DEFER.

Android / JNI

Android possède déjà un owner PGR 610. Le JNI/Rust natif réellement observé est surtout propre à Games dans les baselines présentes. Les exceptions unsafe, ABI, exports JNI et génération Gradle doivent rester locales ou différées jusqu'à une étude composite Rust + Android/JNI suffisante. Classification : DEFER.

Éléments qui doivent rester spécifiques

Les responsabilités suivantes sont utiles dans leurs projets mais ne fournissent pas un owner PGR générique :

• firewall de dépendances, protocoles Solana, transports, Store, workers/jobs, tracing targets et materialization de KSP ;
• générations de moteur, assets de jeux, Uroburas, serveurs temps réel, distribution Android/Web et politiques de hosting de Games ;
• choix de noms de crates, répertoires de config, schémas, routes, plugins et ressources propres à chaque application ;
• seuils Clippy, identifiants courts autorisés, ports de développement et paramètres de fenêtres lorsqu'ils n'expriment aucun invariant réutilisable.

Ces éléments servent à tester que PGR permet des règles locales spécifiques ; ils ne doivent pas être aspirés dans le référentiel central.

Conséquences pour une future adoption de PGR

La future application de PGR à KSP et Games doit être une migration explicitement planifiée dans chacun des projets, après stabilisation de la release PGR retenue. Elle ne doit pas reconstruire artificiellement leurs anciens deltas/histories ni renommer rétroactivement toutes les conventions historiques.

Le point de départ attendu sera plutôt :

prendre la stable réelle du projet
+ sélectionner les owners PGR applicables
+ comparer les règles locales actuelles
+ conserver les contraintes projet spécifiques
+ remplacer seulement les duplications devenues inutiles
+ introduire les nouveaux audits/templates de manière proportionnée
+ valider la migration comme une release du projet lui-même

0.0.5 améliore donc le référentiel et ses points d'adoption ; il ne migre ni KSP ni Games.