pgr/RULES.md

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 :

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 sont structurées progressivement sous docs/rules/.

Familles actuellement actives :

• docs/rules/200-GOVERNANCE.md — versioning, lifecycle des releases, fixes, cadrage, replan et abandon/supersession.
• docs/rules/210-WORKFLOW.md — plans, deltas, histories, prompts, handoffs, manifests, commits, baselines et reprise de session.
• docs/rules/300-DOCUMENTATION.md — rôles documentaires, taxonomie, révisions internes, documents vivants et conservation historique.
• docs/rules/400-VALIDATION.md — sélection proportionnelle des preuves, catégories de validation, tests utiles, doubles de test et autorité opérateur.
• docs/rules/500-LANGUAGES.md — contrat commun des profils langage, écosystème et spécialisations de build associées.
• docs/rules/510-RUST_CARGO.md — profil Rust/Cargo : workspace, manifests, dépendances, lints, API, formatage, tests et validation spécialisée.
• docs/rules/600-PLATFORMS.md — contrat commun des profils plateforme et de leur compatibilité de target/runtime.

Le modèle de composition et d'ownership des profils est défini dans docs/architecture/003-RULE_PROFILE_MODEL.md.

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.