0.0.5-alpha.1
This commit is contained in:
187
docs/studies/001-KSP_GAMES_RECONCILIATION.md
Normal file
187
docs/studies/001-KSP_GAMES_RECONCILIATION.md
Normal file
@@ -0,0 +1,187 @@
|
||||
<!-- file: docs/studies/001-KSP_GAMES_RECONCILIATION.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# É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`.
|
||||
|
||||
```text
|
||||
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`.
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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`.
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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.
|
||||
|
||||
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 plusieurs applications Desk Tauri, Games contient plusieurs hôtes Tauri. Les deux familles observées utilisent Tauri 2 avec un package Rust, `tauri-build`, un frontend privé, des hooks `beforeDevCommand` / `beforeBuildCommand`, un `frontendDist` dédié et une validation qui doit passer par la commande Tauri lorsque l'intégration complète est concernée.
|
||||
|
||||
Cette répétition indépendante justifie de classer Tauri `COMMON` et de rouvrir la famille framework `700` jusque-là différée. Une tranche dédiée de `0.0.5` peut créer un profil Tauri si elle reste limitée aux responsabilités réellement communes : ownership du build Tauri, relation avec Rust/Cargo, hooks frontend, version produit, generated outputs, secrets/resources et gates `cargo tauri dev/build`.
|
||||
|
||||
Le profil ne doit pas imposer les ports, fenêtres, bundles, assets, plugins, packages npm ni chemins de ressources propres aux applications observées.
|
||||
|
||||
Une skeleton specification Tauri peut être créée dans une tranche suivante seulement si le profil obtenu suffit à définir des décisions destinataire réutilisables 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 :
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user