Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.5-alpha.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-24 20:43:57 +02:00
parent bd9aadf0cf
commit 3ca2518c5c
8 changed files with 625 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Documentation PGR
@@ -10,6 +10,7 @@ Ce fichier est l'index d'entrée de la documentation structurée de Project Gove
- [`objectives/`](objectives/) — mission, objectifs durables, non-objectifs et contraintes globales ;
- [`architecture/`](architecture/) — état architectural courant de PGR et profils applicables ;
- [`plans/`](plans/) — plans vivants des releases en cours, puis références historiques après fermeture ;
- [`studies/`](studies/) — études bornées utilisées pour comparer des corpus, instruire une décision ou conserver une analyse avant normalisation ;
- [`rules/`](rules/) — règles normatives détaillées, organisées progressivement par scope ;
- [`skeletons/`](skeletons/) — spécifications Markdown de composition et d'initialisation de projets ;
- [`templates/`](templates/) — instructions d'adaptation des templates techniques et spécification du message manuel de reprise ;
@@ -19,6 +20,11 @@ D'autres collections telles que `ideas/`, `studies/`, `reference/` ou `formats/`
Les templates techniques copiables sous `templates/` restent séparés des instructions documentaires sous `docs/templates/`. Les répertoires workflow de racine (`deltas/`, `history/`, `handoffs/`, `manifests/`, `prompts/`, `scripts/`) restent séparés de `docs/` parce qu'ils portent le processus de développement et de livraison lui-même.
## Points d'entrée de 0.0.5
- [`plans/005-V0_0_5_RECONCILIATION_PLAN.md`](plans/005-V0_0_5_RECONCILIATION_PLAN.md) — cadrage, classification et trajectoire active de la réconciliation `0.0.5` ;
- [`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é.
## Points d'entrée de 0.0.4
- [`plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md`](plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md) — périmètre et décisions de la release `0.0.3` ;

106
docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md Normal file
View File

@@ -0,0 +1,106 @@
<!-- file: docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md -->
<!-- version: 1 -->
# Plan 0.0.5 — réconciliation réelle avec KSP et sasedev-games
## Statut et sources
Plan actif créé pendant `0.0.5-alpha.1` conformément à `prompts/005-V0_0_5_START_PROMPT.md`. La release confronte PGR à deux baselines autoritaires fournies sans présumer qu'elles ont déjà adopté PGR.
Sources contrôlées :
```text
pgr-v0.0.4.zip 7137bb084f017362323a2043d13ba71490be15b8786adc8d645981bf455b80ae
khadhroony-solana-project-v0.3.16.zip db3cc1b3fc3fb07ee864b02e2a7346c673d4cf63b33e8e872aca6c6458856ca0
games-v0.3.5.zip 5f5fdee1a271386766d059657d6eaa831acdc263b3e722fed738808335c0a105
```
Le rapport externe `pgr-0.0.4-publish.001-report.md` est `PASS` et annonce le même hash pour la stable PGR. L'étude détaillée et les limites de l'environnement sont consignées dans [`../studies/001-KSP_GAMES_RECONCILIATION.md`](../studies/001-KSP_GAMES_RECONCILIATION.md).
## Mission et garde-fous
`0.0.5` doit améliorer PGR à partir des besoins réellement répétés dans KSP et Games sans transformer leurs conventions historiques en règles universelles.
Les deux projets ne sont pas encore gouvernés par PGR. Par conséquent :
- aucune divergence de leurs archives n'est qualifiée de défaut PGR par défaut ;
- aucune migration de KSP ou Games n'appartient au scope de cette release ;
- aucune ancienne tranche, nomenclature ou chaîne history n'est reconstruite rétroactivement ;
- tout nouvel owner PGR doit correspondre à un besoin réutilisable et non à un simple copier-coller de projet ;
- les règles métier, architecture, protocoles, distribution et infrastructure spécifiques restent locales.
## Résultat du cadrage alpha.1
L'audit classe la majorité des mécanismes de gouvernance, documentation, validation et Rust/Cargo comme déjà `OWNED` par PGR. Les améliorations candidates réellement communes sont bornées à quatre axes :
1. **prompt de démarrage de projet** : le contrat actuel de `210-WORKFLOW.md` est plus minimal que les prompts opératoires éprouvés dans les deux corpus ;
2. **contrats documentaires locaux** : les deux projets utilisent un registre de responsabilités de fichiers/familles qui peut devenir un pattern facultatif de la fondation ;
3. **façade Rust et export completeness** : les deux projets partagent pratiquement le même audit spécialisé, alors que PGR n'en fournit pas encore de version réutilisable ;
4. **Tauri** : le framework est utilisé indépendamment et de manière répétée dans les deux corpus, ce qui fournit enfin une base réelle pour activer la famille framework `700` sans généraliser Vite/Web/JNI au-delà des preuves disponibles.
Les audits composites, le Web autonome, WASM, JNI, règles serveur, distribution Games et frontières métier KSP restent différés ou locaux.
## Trajectoire prévisionnelle
### alpha.1 — audit indépendant, étude et plan
Vérifier la stable PGR, son rapport post-tag et les deux archives externes ; exécuter les audits statiques disponibles ; classifier les écarts ; créer l'étude et le présent plan. Aucun changement normatif, script réutilisable, profil framework ou skeleton nouveau dans cette tranche.
### alpha.2 — contrat générique des prompts de démarrage
Renforcer l'owner `210-WORKFLOW.md` pour les prompts versionnés sans recopier les règles locales KSP/Games. Fournir une spécification réutilisable couvrant au minimum : baseline autoritaire, ordre de lecture, état déjà validé, mission/résultat, scope/hors-scope, décisions gelées/ouvertes, première gate, trajectoire prévisionnelle et validations.
Le template manuel `003-NEW_SESSION_PROMPT.md` reste distinct : il sert au court message remis après publication, alors que cette tranche porte le prompt versionné du projet.
### alpha.3 — pattern de contrats de fichiers/familles
Étendre `300-DOCUMENTATION.md` et la fondation `001` uniquement si nécessaire pour décrire un registre local facultatif des fichiers ou familles dont le rôle et les règles de modification méritent d'être explicites. Fournir une spécification/template documentaire courte plutôt qu'un catalogue universel.
Le pattern ne doit pas imposer `FILE_CONTRACTS.md` à un petit projet, ni recopier les rôles déjà possédés par PGR.
### alpha.4 — audit Rust de façade/export completeness
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.
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.5 — premier profil framework : Tauri
Si la revue de `alpha.1` reste confirmée, activer la famille `700 — frameworks` et créer un profil Tauri fondé uniquement sur les invariants communs aux deux corpus : composition avec Rust/Cargo, ownership du build Tauri, hooks frontend, version produit, artefacts générés, configuration sensible et gates de développement/build.
Les versions exactes de dépendances, ports, fenêtres, plugins, bundles et chemins applicatifs restent des décisions destinataire. Vite/Web/WASM n'entrent pas automatiquement dans ce profil.
### alpha.6 — décision de skeleton Tauri
Vérifier si le profil Tauri obtenu permet une skeleton specification utile sans créer de `tauri.conf.json` universel. Si oui, ajouter une specialization composable au-dessus de `001 + 002 + 700/710`. Sinon, consigner explicitement le report et ne pas matérialiser un skeleton décoratif.
### beta.1 — réconciliation intégrée
Rejouer la matrice de l'étude sur l'état PGR obtenu. Vérifier : owner unique, navigation, absence de règles KSP/Games aspirées par accident, caractère facultatif des patterns/audits concernés, cohérence des skeletons et domaines encore différés.
### rc.1 — scope gelé et gate candidate
Geler le scope de `0.0.5`, préparer l'entrée candidate du changelog et le prompt `006` de la release suivante si sa mission est suffisamment connue. Rejouer les tests/audits PGR et les validations ciblées des nouveaux scripts/templates/profils réellement livrés.
### stable — 0.0.5
Promouvoir mécaniquement la RC validée : synchroniser `VERSION`, README/index, ROADMAP, CHANGELOG et statut du plan sans ajouter de nouveau besoin commun. Après history PASS, commit et tag `v0.0.5`, vérifier séparément l'archive publiée.
## Points de décision
Un REPLAN est requis si :
- le contrat de prompt devient une copie exhaustive des règles plutôt qu'un artefact de reprise ;
- le pattern de contrats de fichiers ajoute plus de cérémonie qu'il n'en retire ;
- l'audit de façade Rust ne peut pas être séparé proprement des conventions strictes KSP/Games ;
- le profil Tauri exige de choisir arbitrairement Vite, WASM, des plugins ou un layout d'application ;
- le skeleton Tauri n'apporte pas de décisions réutilisables au-delà du profil framework ;
- une autre divergence des corpus apparaît comme un besoin commun critique non couvert par ce plan.
## Stratégie de validation
Les tranches documentaires rejouent les trois audits Markdown et la suite Python PGR. Toute modification d'un script ajoute ou adapte des tests ciblés avant la suite globale. Les templates/configurations structurées sont parsés ou exercés avec l'outil le plus fiable disponible.
PGR ne compile pas KSP ou Games comme gate de sa propre release : ces projets servent de corpus de pression. Une validation croisée MAY exécuter leurs audits statiques sur leurs archives fournies lorsque cela vérifie une propriété précise, mais ne remplace jamais leurs propres gates opérateur.
La toolchain Cargo n'étant pas disponible dans l'environnement de préparation de `alpha.1`, aucune preuve Cargo externe n'est revendiquée pour cette tranche. La gate PGR reste documentaire et structurelle.

12
docs/studies/000-README.md Normal file
View File

@@ -0,0 +1,12 @@
<!-- file: docs/studies/000-README.md -->
<!-- version: 1 -->
# Index des études PGR
Les études PGR enregistrent une analyse bornée nécessaire à une décision, une réconciliation ou une future normalisation sans transformer prématurément leurs conclusions en règles.
Une étude peut comparer des projets sources, des technologies ou plusieurs options. Elle doit distinguer les faits observés, les conclusions déjà suffisamment étayées, les décisions encore ouvertes et les éléments qui doivent rester spécifiques à leur contexte.
## Études actives
- [`001-KSP_GAMES_RECONCILIATION.md`](001-KSP_GAMES_RECONCILIATION.md) — première réconciliation explicite de PGR avec les baselines autoritaires fournies de `khadhroony-solana-project` et `sasedev-games`.

187
docs/studies/001-KSP_GAMES_RECONCILIATION.md Normal file
View 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.