commit 429a8123c6bc12de4f16c4f691516a21b680cf10 Author: SinuS Von SifriduS Date: Wed Sep 23 07:36:11 2026 +0200 0.0.1-alpha.1 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..770c208 --- /dev/null +++ b/.gitignore @@ -0,0 +1,42 @@ +# file: .gitignore +# version: 1 + +# Logs +/logs/ +*.log + +# Editor and IDE files +.vscode/ +.idea/ +.settings/ +.project +.classpath +.factorypath +.pydevproject +*.suo +*.ntvs* +*.njsproj +*.sln +*.swp +*.swo +*~ + +# Operating system files +.DS_Store +Thumbs.db + +# Environment and local secrets +.env +.env.* +!.env.example + +# Python helper artifacts +__pycache__/ +*.py[cod] +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ + +# Local/runtime scratch data +/var/ +/tmp/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..cedcad5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,10 @@ + + + +# Changelog Project Governance Rules + +Ce fichier décrit les changements utiles aux utilisateurs ou intégrateurs des releases publiées de PGR. + +Les tranches `alpha`, `beta`, `rc`, fixes, validations, audits et détails de développement appartiennent aux plans, deltas et historiques. Ils ne sont pas recopiés ici par défaut. + +Aucune release stable PGR n'est encore publiée. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7b8a07e --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ + + + +# Project Governance Rules + +Project Governance Rules (`PGR`) est un référentiel réutilisable de gouvernance, développement, validation et structuration de projets logiciels. + +Son objectif est de normaliser ce qui mérite de l'être, de simplifier les workflows récurrents, d'automatiser les contrôles fiables et de conserver une traçabilité utile sans transformer la gouvernance en bureaucratie. + +Le dépôt officiel est `https://git.sasedev.com/Sasedev/pgr`. + +## Statut + +PGR est actuellement en phase de fondation `0.0.x`. + +La version courante est définie par [`VERSION`](VERSION). La première release `0.0.1` doit établir la gouvernance normative et documentaire de PGR lui-même avant l'introduction des profils technologiques, templates techniques et spécifications de skeletons. + +## Entrées principales + +- [`RULES.md`](RULES.md) — point d'entrée normatif ; +- [`ROADMAP.md`](ROADMAP.md) — découpage macro des releases PGR ; +- [`CHANGELOG.md`](CHANGELOG.md) — changements des releases publiées ; +- [`docs/000-README.md`](docs/000-README.md) — index documentaire ; +- [`docs/objectives/001-PROJECT_OBJECTIVES.md`](docs/objectives/001-PROJECT_OBJECTIVES.md) — mission, objectifs et non-objectifs ; +- [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md) — profil applicable au dépôt PGR ; +- [`docs/architecture/002-GOVERNANCE_ARCHITECTURE.md`](docs/architecture/002-GOVERNANCE_ARCHITECTURE.md) — architecture du référentiel ; +- [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan actif de `0.0.1` ; +- [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation initiale. + +## Langue et nomenclature + +Les noms de fichiers, répertoires, identifiants, code et configurations utilisent l'anglais. Les explications et la documentation normative du dépôt principal utilisent le français. + +Une éventuelle traduction complète de PGR doit vivre dans un dépôt séparé, par exemple `pgr-en`, `pgr-de` ou `pgr-ar`, et non dans une arborescence multilingue du dépôt principal. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..ec4dc18 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,22 @@ + + + +# Roadmap Project Governance Rules + +Le roadmap décrit le découpage macro des releases PGR. Il ne remplace ni les objectifs globaux du projet ni les plans détaillés de version. + +Statuts : `( )` planifié, `(x)` terminé, `(d)` différé, `(c)` annulé. + +## Fondation `0.0.x` + +- `( ) 0.0.1` — fondation normative et documentaire : gouvernance, lifecycle des releases, rôles documentaires, workflow delta/history/handoff et validation proportionnée ; +- `( ) 0.0.2` — profils de règles par langage, plateforme, framework et type de projet ; +- `( ) 0.0.3` — templates techniques initiaux et premiers patterns d'audit réutilisables issus de besoins réels ; +- `( ) 0.0.4` — spécifications Markdown de skeletons et règles de composition des profils/templates ; +- `( ) 0.0.5` — réconciliation réelle de PGR avec `khadhroony-solana-project` et `sasedev-games`. + +## Première baseline réutilisable + +- `( ) 0.1.0` — première baseline PGR destinée à initialiser de nouveaux projets à partir de règles, templates et skeleton specifications éprouvés. + +Le contenu détaillé et le nombre de tranches de chaque release sont définis par son plan actif, créé ou consolidé pendant `alpha.1`. diff --git a/RULES.md b/RULES.md new file mode 100644 index 0000000..040a2f6 --- /dev/null +++ b/RULES.md @@ -0,0 +1,79 @@ + + + +# Index normatif Project Governance Rules + +`RULES.md` est le point d'entrée obligatoire des règles de PGR. + +La présente baseline ne cherche pas à figer immédiatement toutes les règles conçues pour le futur référentiel. `0.0.1` établit d'abord leur gouvernance, leur hiérarchie et les contrats documentaires nécessaires pour pouvoir les intégrer proprement dans les versions suivantes. + +## Finalité + +PGR existe pour normaliser, simplifier, sécuriser et accélérer le développement de projets logiciels. + +Une règle, un document, un audit, un test ou un outil doit apporter une utilité identifiable. PGR ne crée pas de règle pour satisfaire un quota ou ajouter une étape cérémonielle. + +La gouvernance doit rester proportionnée au risque, à la portée du changement et à la preuve réellement nécessaire. + +## Force normative + +PGR utilise les termes suivants : + +- `MUST` / `MUST NOT` : obligation ou interdiction dans le scope de la règle, sauf override ou exception explicitement documenté ; +- `SHOULD` / `SHOULD NOT` : comportement attendu par défaut, avec dérogation possible lorsqu'une solution différente est mieux adaptée et justifiée ; +- `MAY` : possibilité reconnue, sans obligation implicite. + +Une règle qualitative ne doit pas être artificiellement transformée en `MUST` lorsqu'elle n'est ni objectivement vérifiable ni raisonnablement révisable. + +## Hiérarchie normative + +Les règles applicables se composent du plus général au plus spécifique : + +```text +GENERAL + ↓ +ecosystem / language + ↓ +platform + ↓ +framework + ↓ +project type / subsystem + ↓ +project-specific + ↓ +explicit exception +``` + +Une règle plus spécifique MAY raffiner, renforcer ou remplacer localement une règle générale dans son scope. Une contradiction intentionnelle MUST être déclarée comme override ou exception, avec scope et raison. Une contrainte locale ne se propage jamais automatiquement aux autres projets ou profils. + +## Principes fondamentaux + +- Les projets instanciés depuis PGR MUST rester autonomes et posséder leurs propres copies des règles et configurations applicables. +- PGR MUST NOT devenir une dépendance runtime ou build des projets qu'il aide à initialiser. +- Les skeletons PGR sont des spécifications Markdown et MUST NOT devenir un générateur qui fige l'architecture d'un projet. +- Les audits `audit_*.py` MUST être read-only, déterministes autant que raisonnablement possible et sans effets de bord sur le dépôt inspecté. +- Une propriété déjà correctement contrôlée par le compilateur, le linter ou le build system SHOULD NOT être dupliquée par un test ou audit maison sans besoin réel. +- Les tests MUST viser des comportements ou contrats utiles. PGR MUST NOT imposer un pourcentage global de code coverage ni des tests redondants uniquement pour augmenter une métrique. +- Les décisions architecturales non automatisables restent des décisions de revue ; elles MUST NOT être remplacées par des regex fragiles simplement pour les automatiser. +- Les secrets MUST NOT être versionnés, distribués dans les artefacts de gouvernance ou écrits dans les logs. +- Lorsqu'un fichier local de configuration est nécessaire, sa valeur réelle MUST être ignorée par Git et un fichier `example` correspondant MUST documenter sa structure, sauf fichier entièrement généré par un outil sans préparation utilisateur. + +## Langue + +Dans le dépôt principal PGR : + +- code, identifiants, chemins, noms de fichiers et nomenclature technique : anglais ; +- explications et documentation normative : français. + +Les traductions complètes éventuelles vivent dans des dépôts distincts (`pgr-en`, `pgr-de`, `pgr-ar`, etc.). + +## Documents normatifs détaillés + +Les règles détaillées seront structurées progressivement sous [`docs/rules/`](docs/rules/). Une famille de règles n'est créée que lorsqu'elle possède un contenu réel ; aucun répertoire vide n'est requis pour anticiper une future technologie. + +## Modification des règles + +Une règle MUST NOT être affaiblie uniquement pour faire passer un changement de code ou de documentation. + +Lorsqu'une règle paraît inadaptée, il faut déterminer si le défaut appartient au changement, à la règle, à son scope ou à une exception légitime. Une modification normative constitue une décision de gouvernance à documenter comme telle. diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..457ec10 --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.0.1-alpha.1 diff --git a/deltas/0.0.1/alpha.1.md b/deltas/0.0.1/alpha.1.md new file mode 100644 index 0000000..b83d4cb --- /dev/null +++ b/deltas/0.0.1/alpha.1.md @@ -0,0 +1,116 @@ + + + +# Delta 0.0.1-alpha.1 — bootstrap et cadrage PGR + +## Base requise + +Dépôt Gitea `Sasedev/pgr` nouvellement créé et projet local Eclipse vide. + +Aucune release PGR antérieure n'existe. L'absence de `VERSION`, règles, historique ou tag antérieur est normale pour ce bootstrap unique. + +Les fichiers locaux Eclipse éventuellement déjà présents (`.project`, `.classpath`, `.settings/`) ne font pas partie de la livraison et sont ignorés par la nouvelle politique Git. + +## Objet + +Créer la première tranche réelle de Project Governance Rules et cadrer intégralement la release `0.0.1` avant toute consolidation massive des règles conçues pendant la phase de brainstorming. + +La version devient : + +```text +0.0.1-alpha.1 +``` + +`alpha.1` reste un gate de framing : cette tranche établit la structure et les responsabilités nécessaires à la suite, sans essayer de livrer déjà tous les profils technologiques, templates ou audits. + +## Fichiers ajoutés + +```text +.gitignore +VERSION +README.md +RULES.md +ROADMAP.md +CHANGELOG.md +docs/000-README.md +docs/objectives/001-PROJECT_OBJECTIVES.md +docs/architecture/001-PROJECT_PROFILE.md +docs/architecture/002-GOVERNANCE_ARCHITECTURE.md +docs/plans/001-V0_0_1_FOUNDATION_PLAN.md +docs/rules/000-README.md +docs/validation/001-VALIDATION_MATRIX.md +deltas/0.0.1/alpha.1.md +prompts/001-V0_0_1_START_PROMPT.md +``` + +Aucun fichier n'est remplacé ou supprimé par le delta. + +Aucun manifest de suppression n'est nécessaire. + +## Décisions de cadrage + +La tranche fixe notamment : + +- le nom `Project Governance Rules` / `PGR` ; +- le dépôt canonique `https://git.sasedev.com/Sasedev/pgr` ; +- PGR comme référentiel de règles, templates, skeleton specifications Markdown et audits read-only ; +- l'absence de générateur de projet PGR ; +- la croissance incrémentale des audits à partir de besoins réels ; +- la langue française pour les explications et l'anglais pour la nomenclature/code ; +- les traductions complètes dans des dépôts séparés et non dans `pgr/fr`, `pgr/en`, etc. ; +- le principe de proportionnalité comme objectif central de la gouvernance ; +- le plan initial de `0.0.1` et la trajectoire macro jusqu'à `0.1.0`. + +## `.gitignore` + +Le fichier suit le style commenté déjà utilisé dans les dépôts de référence : header `file/version`, sections lisibles et politique explicite pour IDE, système, secrets et artefacts Python. + +Il reste volontairement spécifique aux besoins actuels de PGR. Les ignores Cargo, Node, Android, CMake ou Composer ne sont pas ajoutés au dépôt racine uniquement parce que PGR documentera ces technologies plus tard. + +## Hors périmètre + +Cette tranche n'introduit pas : + +- de scripts d'audit ; +- de templates techniques ; +- de profiles technologiques détaillés ; +- de skeletons par type de projet ; +- de générateur ; +- de dépendance Python ou autre toolchain applicative ; +- de répertoire `history/`, `handoffs/`, `manifests/`, `templates/` ou `scripts/` vide. + +## Validation attendue + +```bash +git status --short + +test "$(cat VERSION)" = "0.0.1-alpha.1" + +find . -type f -not -path './.git/*' -print + +git add . +git diff --cached --check + +git status --short +``` + +Revue opérateur complémentaire : + +- vérifier que les seuls fichiers PGR introduits sont ceux de la section `Fichiers ajoutés` ; +- vérifier que `.project`, `.classpath` et `.settings/` restent locaux/ignorés ; +- vérifier les headers `file/version` de tous les fichiers textuels qui les supportent ; +- vérifier que `VERSION` contient uniquement `0.0.1-alpha.1` ; +- vérifier que les liens principaux du README et de `docs/000-README.md` sont cohérents ; +- vérifier l'absence de secret ou chemin machine absolu. + +## Transition + +### PASS + +Créer `history/0.0.1/alpha.1.md` dans une archive history séparée, puis ouvrir `0.0.1-alpha.2` consacré aux règles fondamentales de versioning et lifecycle conformément au plan actif. + +Le cycle opérateur attendu est : appliquer ce delta → exécuter la gate → transmettre les résultats → appliquer l'archive history `alpha.1` → commit de la tranche validée → appliquer le delta `alpha.2`. + +### FAIL + +Rester dans le scope `alpha.1` et produire `0.0.1-alpha.1.fix.1` uniquement pour corriger les défauts de cette tranche. Aucun scope `alpha.2` ne doit être introduit dans le fix. diff --git a/docs/000-README.md b/docs/000-README.md new file mode 100644 index 0000000..13d007a --- /dev/null +++ b/docs/000-README.md @@ -0,0 +1,18 @@ + + + +# Documentation PGR + +Ce fichier est l'index d'entrée de la documentation structurée de Project Governance Rules. + +## Collections actives + +- [`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 ; +- [`rules/`](rules/) — règles normatives détaillées, organisées progressivement par scope ; +- [`validation/`](validation/) — matrices de validation et contrats de preuve. + +D'autres collections telles que `ideas/`, `studies/`, `reference/`, `formats/` ou `templates/` ne sont créées que lorsqu'un premier artefact réel les justifie. + +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. diff --git a/docs/architecture/001-PROJECT_PROFILE.md b/docs/architecture/001-PROJECT_PROFILE.md new file mode 100644 index 0000000..7dd88e5 --- /dev/null +++ b/docs/architecture/001-PROJECT_PROFILE.md @@ -0,0 +1,47 @@ + + + +# Profil du projet PGR + +## Rôle + +Le dépôt `pgr` est un référentiel de gouvernance et de documentation technique. Il n'est actuellement ni une application, ni une bibliothèque runtime, ni un projet Python applicatif. + +## Profils applicables + +```text +GENERAL GOVERNANCE +DOCUMENTATION +VALIDATION GOVERNANCE +GIT / RELEASE WORKFLOW +MARKDOWN +PYTHON 3 UTILITY SCRIPTS (uniquement lorsque des audits/outils apparaissent) +``` + +La présence future de scripts `audit_*.py` ne transforme pas PGR en package ou application Python. + +## Profils actuellement non applicables + +La première release de fondation n'applique pas encore les profils suivants au dépôt lui-même : + +```text +RUST / CARGO +JAVA / MAVEN / GRADLE +ANDROID +TAURI +WEB APPLICATION +WASM +PHP / COMPOSER +PYTHON APPLICATION/PACKAGE +C / C++ / CMAKE +``` + +Ces technologies peuvent être documentées ultérieurement comme règles/templates/skeletons sans devenir des dépendances techniques du dépôt PGR. + +## Nomenclature et langue + +Les chemins, noms de fichiers, identifiants et éléments techniques sont en anglais. La documentation normative et explicative du dépôt principal est en français. + +## Baseline de gouvernance + +PGR se gouverne lui-même à partir de `0.0.1-alpha.1`. Le bootstrap initial part d'un dépôt vide ; il n'existe aucun faux tag, aucune fausse release `0.0.0` et aucune archive stable antérieure à simuler. diff --git a/docs/architecture/002-GOVERNANCE_ARCHITECTURE.md b/docs/architecture/002-GOVERNANCE_ARCHITECTURE.md new file mode 100644 index 0000000..7776d87 --- /dev/null +++ b/docs/architecture/002-GOVERNANCE_ARCHITECTURE.md @@ -0,0 +1,82 @@ + + + +# Architecture de gouvernance PGR + +## Principe général + +PGR sépare quatre familles d'artefacts qui ne doivent pas être confondues. + +### Rule + +Une règle définit un contrat normatif. Elle explique ce qui est obligatoire, interdit, attendu ou autorisé dans un scope donné. + +La règle est la source normative ; un template ou un audit ne crée pas une règle par sa seule existence. + +### Template + +Un template fournit une baseline technique réutilisable, par exemple une configuration de formatter, linter, compilateur ou build tool. + +Un template implémente des règles déjà documentées. Il peut être copié tel quel ou adapté selon les instructions du skeleton applicable. + +Après instanciation, le projet possède sa copie et ne dépend plus de PGR. + +### Skeleton specification + +Un skeleton est une recette Markdown décrivant comment initialiser un type de projet ou composer plusieurs profils. + +Il décrit notamment les profils applicables, la structure requise ou optionnelle, les templates à utiliser, les points de décision, la politique de version et la validation de base. + +Un skeleton n'est pas un générateur et ne doit pas figer l'évolution future du projet. + +### Audit + +Un audit contrôle une propriété structurelle réellement automatisable. + +Les scripts `audit_*.py` sont read-only : ils ne modifient, ne formatent, ne génèrent, n'installent, ne téléchargent et ne lancent pas les toolchains du projet inspecté. + +Les audits PGR sont ajoutés progressivement à partir de besoins réels et de contrôles éprouvés. PGR ne cherche pas à anticiper un catalogue exhaustif d'audits. + +## Instanciation d'un projet + +Le flux conceptuel est : + +```text +PGR rules + templates + skeleton specifications + ↓ + sélection humaine / IA + ↓ + nouveau projet + ↓ + copies et règles locales + ↓ + projet autonome et gouverné +``` + +Une évolution ultérieure de PGR ne modifie jamais automatiquement les projets déjà créés. + +## Hiérarchie + +Les règles générales sont raffinées par les scopes plus spécifiques. Un choix spécialisé, par exemple une contrainte Tauri Android, ne devient pas automatiquement une règle Android ou Java générale. + +Les règles project-specific restent dans le dépôt qui les possède. + +## Structure de croissance + +PGR crée ses collections et familles de règles lorsque leur premier contenu réel apparaît. Les répertoires vides et les documents placeholders sont évités. + +Les futures familles pourront notamment couvrir : + +```text +general +governance +documentation +validation +languages +platforms +frameworks +architecture +project-specific rules +``` + +sans exiger leur matérialisation complète pendant `0.0.1-alpha.1`. diff --git a/docs/objectives/001-PROJECT_OBJECTIVES.md b/docs/objectives/001-PROJECT_OBJECTIVES.md new file mode 100644 index 0000000..53fd7e0 --- /dev/null +++ b/docs/objectives/001-PROJECT_OBJECTIVES.md @@ -0,0 +1,65 @@ + + + +# Objectifs de Project Governance Rules + +## Mission + +PGR fournit une gouvernance réutilisable permettant de démarrer, développer, valider, reprendre et publier des projets logiciels plus rapidement, avec des responsabilités explicites et une qualité proportionnée aux risques réels. + +## Objectifs + +PGR doit permettre de : + +- normaliser les pratiques récurrentes qui bénéficient réellement d'une convention commune ; +- réduire le temps de bootstrap d'un nouveau projet ; +- rendre explicites les responsabilités des fichiers, composants, couches et outils ; +- standardiser SemVer, lifecycle de release, deltas, validations, historiques et handoffs ; +- favoriser des validations ciblées pendant le développement et des gates plus larges aux jalons appropriés ; +- automatiser les contrôles déterministes et fiables sans automatiser artificiellement les décisions nécessitant du jugement ; +- fournir des templates techniques éprouvés sans créer de dépendance vers PGR après instanciation ; +- décrire des skeletons de projets sous forme de recettes Markdown composables plutôt que de générateurs rigides ; +- supporter plusieurs langages, plateformes et frameworks sans chercher une uniformité artificielle ; +- conserver une traçabilité historique utile tout en gardant les documents vivants lisibles ; +- permettre des règles project-specific et des exceptions explicites sans contaminer les règles générales ; +- privilégier la sécurité, l'explicité, la maintenabilité et la proportionnalité. + +## Principe de proportionnalité + +PGR doit servir les objectifs du projet et réduire son coût total de développement, compréhension, validation, diagnostic et maintenance. + +Une pratique qui ajoute principalement de la bureaucratie, de la duplication, des tests sans gain de preuve, des validations répétitives ou une complexité artificielle doit être simplifiée, rendue optionnelle ou supprimée. + +La rigueur porte sur ce qui est important ; elle ne consiste pas à rendre chaque opération lourde. + +## Non-objectifs + +PGR n'a pas pour objectif de : + +- devenir un build system ou remplacer Cargo, Gradle, Maven, CMake, npm, Composer ou les outils natifs des écosystèmes ; +- fournir un générateur universel de projets ; +- imposer toutes les technologies à tous les dépôts ; +- figer une architecture une fois un projet démarré ; +- maximiser le nombre de règles, documents, tests ou audits ; +- imposer un pourcentage arbitraire de code coverage ; +- créer des audits regex pour remplacer le jugement architectural ; +- réimplémenter les fonctionnalités des toolchains officielles sans bénéfice réel ; +- maintenir automatiquement les projets créés à partir de PGR ; +- imposer une stratégie Git complexe ou une topologie universelle de branches. + +## Critères de succès à terme + +PGR est utile si un nouveau projet peut rapidement identifier : + +```text +quoi créer +pourquoi +où le placer +quelles règles s'appliquent +quelles décisions restent ouvertes +comment valider les changements +comment reprendre le travail plus tard +comment publier proprement +``` + +sans importer des règles ou technologies sans rapport avec son besoin. diff --git a/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md b/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md new file mode 100644 index 0000000..6f0ee0f --- /dev/null +++ b/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md @@ -0,0 +1,92 @@ + + + +# Plan 0.0.1 — fondation de PGR + +## Statut + +Plan actif créé pendant `0.0.1-alpha.1` à partir du bootstrap initial du dépôt PGR. + +Aucune stable PGR antérieure n'existe. Cette version doit rendre le dépôt capable de se gouverner lui-même avant d'introduire les profils technologiques et templates prévus dans les releases suivantes. + +## Mission + +`0.0.1` doit établir la fondation normative, documentaire et opératoire de Project Governance Rules. + +La release doit notamment fixer : + +- la finalité et les non-objectifs de PGR ; +- la hiérarchie `MUST` / `SHOULD` / `MAY` et les règles de scope/override/exception ; +- le modèle SemVer et le rôle de `VERSION` ; +- le lifecycle `alpha` → `beta` → `rc` → stable et les `.fix.N` ; +- le cadrage obligatoire de `alpha.1`, le replan et l'abandon/supersession ; +- les rôles de `README`, `RULES`, `ROADMAP`, `CHANGELOG` et des collections documentaires ; +- les contrats des plans, deltas, historiques, prompts, handoffs et manifests ; +- la séparation TEST / AUDIT / DIAGNOSTIC ; +- la validation proportionnée et l'autorité du gate opérateur ; +- les règles de reprise de session et de baseline ZIP taggée ; +- la préparation du prompt de démarrage de `0.0.2`. + +## Hors périmètre + +`0.0.1` ne doit pas encore : + +- formaliser en détail tous les profils Rust, Java, Android, Tauri, Web, PHP, Python, C/C++ ; +- produire le catalogue final des templates techniques ; +- fournir des skeleton specifications complets par type de projet ; +- créer un générateur PGR ; +- anticiper des audits spécialisés sans besoin concret ; +- réappliquer PGR à KSP ou games, travail réservé à une release ultérieure. + +## Principes de dimensionnement + +Une tranche doit rester cohérente et validable indépendamment. La cible de 15 à 30 minutes de travail effectif reste une heuristique de dimensionnement, pas une deadline. + +Si le plan devient manifestement faux, un `alpha.N` peut jouer le rôle de REPLAN. Une version n'est jamais forcée vers stable uniquement pour respecter une session de conversation. + +## Prévision + +### alpha.1 — Bootstrap and framing + +Créer la baseline minimale : identité, `.gitignore`, `VERSION`, documents racine, objectifs, profil du dépôt, architecture de gouvernance, index des règles, matrice de validation, plan actif, delta et prompt initial. + +Aucune implémentation massive des règles détaillées n'est réalisée dans cette tranche. + +### alpha.2 — Core governance rules + +Formaliser les règles communes de versioning et lifecycle : SemVer, `VERSION`, maturité, fixes, cadrage `alpha.1`, replan, abandon/supersession, stable promotion et publication. + +### alpha.3 — Workflow artifacts + +Formaliser plans, deltas, history, prompts, handoffs, manifests de suppression, workflow PASS/FAIL et reprise après interruption. + +### alpha.4 — Documentation governance + +Formaliser les rôles des documents, taxonomie documentaire, headers, révisions internes, déplacement/split/fusion, conservation historique, objectifs, ideas/studies/architecture/reference et politique de langue. + +### alpha.5 — Validation governance + +Formaliser la matrice de validation, sélection proportionnelle, TEST/AUDIT/DIAGNOSTIC, opérateur autoritaire, tests utiles/non redondants, mocks lorsque pertinents et transitions de gate. + +### beta.1 — Foundation reconciliation + +Réconcilier les documents de fondation, éliminer duplications et contradictions, vérifier navigation, rôles, scopes et complétude de `0.0.1`. + +### rc.1 — Foundation release candidate + +Geler le scope, préparer l'entrée candidate de changelog et le prompt `0.0.2`, puis exécuter la gate documentaire complète applicable. + +### stable — 0.0.1 + +Promouvoir mécaniquement la RC validée, finaliser les métadonnées de release, enregistrer `rel.001`, commit/tag `v0.0.1`, puis utiliser l'archive ZIP taggée comme baseline autoritaire de `0.0.2`. + +## Critères de fermeture + +`0.0.1` est fermée lorsque : + +- PGR peut expliquer et appliquer son propre cycle de version ; +- les responsabilités des principaux artefacts de gouvernance sont non ambiguës ; +- la validation d'une tranche peut être sélectionnée proportionnellement ; +- une interruption ou reprise de session est gouvernée ; +- le passage RC → stable → tag → archive suivante est défini ; +- aucune règle technologique détaillée hors fondation n'est nécessaire pour comprendre le workflow PGR. diff --git a/docs/rules/000-README.md b/docs/rules/000-README.md new file mode 100644 index 0000000..15f6adb --- /dev/null +++ b/docs/rules/000-README.md @@ -0,0 +1,46 @@ + + + +# Index des règles PGR + +Les règles détaillées de Project Governance Rules sont organisées ici progressivement par scope. + +`RULES.md` reste le point d'entrée normatif du dépôt et définit les principes fondamentaux, la force normative et la hiérarchie générale. + +## Organisation prévue + +Les familles seront créées uniquement lorsqu'elles disposent d'un contenu réel. La trajectoire actuelle prévoit conceptuellement : + +```text +100 — general +200 — governance +300 — documentation +400 — validation +500 — languages +600 — platforms +700 — frameworks +800 — architecture +900 — project-specific +``` + +Les numéros réservent des familles de navigation ; ils ne constituent pas des identifiants de règles individuelles. + +Les règles issues d'un langage, framework ou projet particulier ne doivent pas être élevées au niveau général sans justification réellement transversale. + +## Enforcement + +Une règle doit s'appuyer d'abord sur le mécanisme officiel le plus fiable disponible : + +```text +compiler / language + ↓ +official linter or tool + ↓ +manifest / build system + ↓ +read-only structural audit + ↓ +test, uniquement pour une propriété comportementale +``` + +Les décisions architecturales qui ne peuvent pas être automatisées de manière fiable restent des points de revue. diff --git a/docs/validation/001-VALIDATION_MATRIX.md b/docs/validation/001-VALIDATION_MATRIX.md new file mode 100644 index 0000000..de9bb46 --- /dev/null +++ b/docs/validation/001-VALIDATION_MATRIX.md @@ -0,0 +1,54 @@ + + + +# Matrice de validation PGR + +## Rôle + +Cette matrice décrit les validations canoniques du dépôt PGR. Elle évoluera avec le projet et ne doit pas inventer des scripts uniquement pour remplir une case. + +`0.0.1-alpha.1` est une tranche documentaire de bootstrap sans toolchain applicative. Les premiers contrôles sont donc volontairement simples. + +## Commandes initiales + +| ID | Catégorie | Commande / contrôle | Trigger | Phase | +|-------------------------|-----------|------------------------------------------------------------------------------------------|--------------------------------------------|----------------------| +| `PGR-GIT-001` | CHECK | `git diff --check` | toute modification suivie par Git | alpha/beta/RC/stable | +| `PGR-GIT-BOOTSTRAP-001` | CHECK | `git add .` puis `git diff --cached --check` | bootstrap ou fichiers entièrement nouveaux | alpha.1/bootstrap | +| `PGR-VERSION-001` | CHECK | `test "$(cat VERSION)" = "0.0.1-alpha.1"` | tranche `0.0.1-alpha.1` | alpha.1 | +| `PGR-LAYOUT-001` | REVIEW | `find . -type f -not -path './.git/*' -print` puis comparaison au scope du delta | ajout/suppression/déplacement de fichiers | alpha/beta/RC/stable | +| `PGR-DOC-001` | REVIEW | vérifier headers `file/version`, chemins, liens et responsabilités des documents touchés | modification documentaire | alpha/beta/RC/stable | +| `PGR-STATUS-001` | CHECK | `git status --short` | avant fermeture d'une tranche | alpha/beta/RC/stable | + +## Gate `0.0.1-alpha.1` + +Après application du delta : + +```bash +git status --short + +test "$(cat VERSION)" = "0.0.1-alpha.1" + +find . -type f -not -path './.git/*' -print + +git add . +git diff --cached --check + +git status --short +``` + +L'opérateur vérifie également que : + +- `.project`, `.classpath` et `.settings/` Eclipse restent locaux/ignorés ; +- aucun répertoire vide n'a été ajouté uniquement pour anticiper le futur ; +- les fichiers listés par le delta sont les seuls fichiers PGR introduits par la tranche ; +- les headers `file/version` correspondent aux chemins réels ; +- `VERSION` contient exactement une ligne `0.0.1-alpha.1` ; +- les liens Markdown de navigation principaux sont cohérents ; +- aucun secret, chemin machine absolu ou artefact local n'est introduit. + +## Autorité de validation + +Une validation n'est `PASS` qu'après exécution réelle du gate opérateur. La génération du delta ou une prévalidation par l'IA ne constitue pas le résultat opérateur. + +Après `PASS`, la tranche suivante doit enregistrer `history/0.0.1/alpha.1.md` séparément avant le commit de l'état validé et fournir le delta suivant conformément au workflow PGR retenu. diff --git a/history/0.0.1/alpha.1.md b/history/0.0.1/alpha.1.md new file mode 100644 index 0000000..cb910d7 --- /dev/null +++ b/history/0.0.1/alpha.1.md @@ -0,0 +1,91 @@ + + + +# History 0.0.1-alpha.1 — bootstrap et cadrage PGR + +## Statut + +FAIL + +La tranche a été appliquée et les contrôles de base n'ont signalé ni erreur de version ni erreur whitespace, mais la revue opérateur a identifié un défaut de politique Eclipse dans `.gitignore`. + +## Baseline + +Dépôt PGR nouvellement créé depuis `https://git.sasedev.com/Sasedev/pgr.git`, sans release stable antérieure. + +Delta appliqué : `0.0.1-alpha.1`. + +Version attendue et observée : + +```text +0.0.1-alpha.1 +``` + +## Validation opérateur observée + +Les commandes communiquées par l'opérateur sont : + +```bash +git status --short + +test "$(cat VERSION)" = "0.0.1-alpha.1" + +find . -type f -not -path './.git/*' -print + +git diff --cached --check + +git status --short +``` + +Le test de `VERSION` n'a produit aucune erreur. + +L'inventaire a notamment confirmé la présence locale de : + +```text +.project +.settings/org.eclipse.core.resources.prefs +``` + +`git diff --cached --check` n'a produit aucun diagnostic. + +Les sorties `git status --short` communiquées sont vides. + +## Défaut identifié + +Le delta `alpha.1` ignorait `.settings/` intégralement et considérait tous les fichiers Eclipse comme locaux. + +Cette politique est trop large : `.settings/org.eclipse.core.resources.prefs` doit être versionné, car il porte la configuration d'encodage UTF-8 du projet Eclipse et n'est pas nécessairement régénéré lors d'un import depuis Git. + +Le pattern `.settings/` doit donc être remplacé par : + +```text +.settings/* +!.settings/org.eclipse.core.resources.prefs +``` + +Le fichier de préférences attendu contient : + +```text +eclipse.preferences.version=1 +encoding/=UTF-8 +``` + +`.project` et les autres métadonnées Eclipse locales restent ignorés. + +## Limites de la preuve + +Aucun audit PGR automatisé n'existe encore à cette tranche de bootstrap. + +Le défaut a été détecté par revue opérateur, ce qui confirme que la validation `alpha.1` doit rester capable de compléter les contrôles mécaniques par une vérification de politique. + +## Conséquence + +La tranche ne peut pas être déclarée PASS en l'état. + +Rester dans le scope `alpha.1` et appliquer `0.0.1-alpha.1.fix.1` uniquement pour : + +- corriger la politique `.settings` dans `.gitignore` ; +- versionner `.settings/org.eclipse.core.resources.prefs` ; +- passer `VERSION` à `0.0.1-alpha.1.fix.1`. + +Aucun changement du plan `0.0.1` n'est nécessaire : le défaut est local et ne modifie ni le scope ni le forecast de la release. diff --git a/prompts/001-V0_0_1_START_PROMPT.md b/prompts/001-V0_0_1_START_PROMPT.md new file mode 100644 index 0000000..d0d00ae --- /dev/null +++ b/prompts/001-V0_0_1_START_PROMPT.md @@ -0,0 +1,70 @@ + + + +# Prompt de démarrage 0.0.1 — fondation de Project Governance Rules + +## Base et cible + +Dépôt canonique : + +```text +https://git.sasedev.com/Sasedev/pgr +``` + +Le dépôt part initialement vide. Aucune stable, aucun tag et aucune archive PGR antérieure ne doivent être inventés pour le bootstrap. + +Version cible : + +```text +0.0.1 +``` + +Première tranche : + +```text +0.0.1-alpha.1 +``` + +## Mission + +Construire la fondation normative et documentaire de PGR à partir des décisions consolidées lors de la conception préalable, sans essayer de traiter immédiatement tous les langages, plateformes, templates et skeletons. + +`alpha.1` doit obligatoirement : + +- créer l'identité et les objectifs de PGR ; +- établir la hiérarchie normative et le principe de proportionnalité ; +- créer le profil du dépôt et l'architecture du référentiel ; +- définir le plan complet de `0.0.1` ; +- installer la première matrice de validation ; +- dimensionner les tranches suivantes avant tout travail massif. + +## Principes acquis + +- PGR normalise, simplifie, sécurise et automatise uniquement lorsque cela apporte une valeur réelle. +- Les projets créés à partir de PGR restent autonomes. +- PGR fournit des règles, templates, skeleton specifications Markdown et audits ; il ne fournit pas de générateur de projets. +- Les audits sont read-only et grandissent à partir de besoins réels. +- Les tests sont utiles et proportionnés ; aucun quota global de code coverage n'est imposé. +- La nomenclature/code est en anglais et les explications normatives du dépôt principal sont en français. +- Une traduction complète éventuelle vit dans un dépôt séparé (`pgr-en`, `pgr-de`, `pgr-ar`, etc.). + +## Découpage initial attendu + +```text +0.0.1 -> governance foundation +0.0.2 -> technology rule profiles +0.0.3 -> technical templates and initial audit patterns +0.0.4 -> skeleton specifications and composition +0.0.5 -> reconciliation against KSP and sasedev-games +0.1.0 -> first reusable baseline +``` + +Ce découpage est prévisionnel et doit être replanifié s'il cesse de représenter correctement la réalité. + +## Règles de travail + +Une tranche doit rester cohérente et validable indépendamment. L'heuristique de 15 à 30 minutes sert à détecter les tranches trop grosses ; elle ne constitue pas une deadline. + +Un changement documentaire ne doit pas créer artificiellement des toolchains, tests ou audits sans valeur. Une validation doit prouver le scope réellement modifié. + +Si la conversation ou la session se termine avant la stable, reprendre la même release/tranche depuis le dernier état opérateur validé ; ne jamais fabriquer une nouvelle version uniquement à cause d'une interruption de contexte.