5.6 KiB
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 spécification Markdown composable 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. Le contrat transversal de sélection et de composition appartient à ../rules/220-SKELETONS.md ; les spécifications concrètes sont indexées sous ../skeletons/.
Un skeleton n'est pas un générateur et ne doit pas figer l'évolution future du projet. Il orchestre des owners normatifs et des artefacts existants sans devenir lui-même propriétaire d'une règle déjà possédée ailleurs.
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.
Frontière avec les contenus pratiques externes
PGR doit rester auto-suffisant pour comprendre et appliquer ses contrats normatifs. Les règles, owners, objectifs, décisions architecturales, skeleton specifications, templates nécessaires à un contrat réutilisable et validations directement liées aux règles restent possédés par PGR lorsqu'ils sont nécessaires à cette compréhension.
Les howtos détaillés, recettes pratiques, snippets, exemples d'intégration, dépannage, comparatifs et variantes d'implémentation MAY vivre dans une base de connaissances séparée. SaseDev Knowledge est une destination possible pour cette famille de contenus, mais sa disponibilité n'est pas une précondition d'utilisation de PGR.
Un contenu pratique externe MAY compléter PGR, mais MUST NOT devenir la source nécessaire pour déterminer ce qu'une règle PGR exige. PGR MUST NOT dépendre d'un dépôt Knowledge pour être interprétable ou applicable.
Cette frontière est sémantique avant d'être physique : classifier un contenu comme pratique ne déclenche pas automatiquement son déplacement. Une extraction future exige une destination autoritaire explicitement fournie et doit préserver dans PGR tout contrat nécessaire à son auto-suffisance.
Instanciation d'un projet
Le flux conceptuel est :
PGR rules + templates + skeleton specifications
↓
applicabilité + décisions du projet
↓
copie / adaptation contrôlée
↓
validation de la baseline
↓
projet autonome et gouverné
Une évolution ultérieure de PGR ne modifie jamais automatiquement les projets déjà créés.
Adoption d’un projet existant
Un dépôt déjà existant ne repasse pas artificiellement par le flux d’instanciation. Son adoption part de sa baseline réelle et compare les owners PGR applicables avec les contrats locaux avant toute migration. Le mapping utilise la classification ADOPT / KEEP-LOCAL / OVERRIDE / DEFER.
Le flux conceptuel est :
baseline autoritaire du projet
↓
inventaire + owners PGR applicables
↓
ADOPT / KEEP-LOCAL / OVERRIDE / DEFER
↓
migration progressive + validation
↓
projet autonome avec historique préservé
Le contrat normatif appartient à ../rules/230-ADOPTION.md. Un skeleton MAY servir de référence de comparaison, mais l’adoption ne prétend pas que le projet existant a été créé depuis ce skeleton et ne réécrit pas rétroactivement ses snapshots historiques.
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 principes généraux actuellement suffisants restent possédés par le RULES.md racine. Une famille dédiée 100 — general n'est matérialisée que si un corpus général distinct devient réellement utile.
Les familles de croissance peuvent notamment couvrir :
general
governance
documentation
validation
languages
platforms
frameworks
architecture
project-specific rules
Cette classification guide la navigation sans imposer la création anticipée de fichiers ou répertoires vides.