pgr/RULES.md

<!-- file: RULES.md -->
<!-- version: 15 -->

# 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 normative dans le scope de la règle ; une contradiction applicable doit être traitée par l'exception ou l'override autorisé, sinon elle constitue une non-conformité ;
- `SHOULD` / `SHOULD NOT` : forte recommandation non obligatoire. Un écart ne constitue pas à lui seul une non-conformité, ne fait pas échouer à lui seul une gate et n'exige pas automatiquement un `OVERRIDE` ; la raison MAY être documentée lorsqu'elle apporte une valeur durable de maintenance, architecture ou reprise ;
- `MAY` : possibilité neutre 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. Une gate, un skeleton, un template ou un profil plus spécifique MUST conserver cette distinction de force normative au lieu de renforcer implicitement un `SHOULD`.

## 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 ou renforcer localement une règle générale dans son scope. Lorsqu'elle contredit intentionnellement un `MUST` / `MUST NOT` réellement applicable, cette contradiction MUST être déclarée comme override ou exception, avec scope et raison. Un choix différent d'un `SHOULD` / `SHOULD NOT` n'est pas, par lui-même, une contradiction normative exigeant un override. 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/`](docs/rules/).

Familles actuellement actives :

- [`docs/rules/200-GOVERNANCE.md`](docs/rules/200-GOVERNANCE.md) — versioning, lifecycle des releases, fixes, cadrage, replan et abandon/supersession.
- [`docs/rules/210-WORKFLOW.md`](docs/rules/210-WORKFLOW.md) — plans, deltas, histories, prompts, handoffs, manifests, commits, baselines et reprise de session.
- [`docs/rules/220-SKELETONS.md`](docs/rules/220-SKELETONS.md) — sélection, composition, adaptation et validation des skeleton specifications.
- [`docs/rules/230-ADOPTION.md`](docs/rules/230-ADOPTION.md) — adoption proportionnée de PGR par un projet existant, mapping des owners, décisions locales et migration progressive.
- [`docs/rules/300-DOCUMENTATION.md`](docs/rules/300-DOCUMENTATION.md) — rôles documentaires, taxonomie, révisions internes, documents vivants et conservation historique.
- [`docs/rules/400-VALIDATION.md`](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`](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`](docs/rules/510-RUST_CARGO.md) — profil Rust/Cargo : workspace, manifests, dépendances, lints, API, formatage, tests et validation spécialisée.
- [`docs/rules/520-JAVA.md`](docs/rules/520-JAVA.md) — profil Java : JDK LTS, compatibilité source/bytecode, structure, packages, API et tests.
- [`docs/rules/521-MAVEN.md`](docs/rules/521-MAVEN.md) — spécialisation Maven : ownership du reactor, wrapper conditionnel, validation et outputs.
- [`docs/rules/522-GRADLE.md`](docs/rules/522-GRADLE.md) — spécialisation Gradle : ownership du build, version/wrapper, DSL, propriétés, validation et outputs.
- [`docs/rules/530-TYPESCRIPT.md`](docs/rules/530-TYPESCRIPT.md) — profil TypeScript : recommandation contrôlée, type-check et frontières typées.
- [`docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md) — manifest `package.json`, sélection du package manager, dépendances et responsabilité du lockfile.
- [`docs/rules/550-VITE.md`](docs/rules/550-VITE.md) — profil Vite : build tool/dev server recommandé, cache, outputs et frontière avec le host.
- [`docs/rules/560-CSS_SASS.md`](docs/rules/560-CSS_SASS.md) — profil CSS/Sass : styles sources, prétraitement optionnel recommandé et dépendances de styles.
- [`docs/rules/600-PLATFORMS.md`](docs/rules/600-PLATFORMS.md) — contrat commun des profils plateforme et de leur compatibilité de target/runtime.
- [`docs/rules/610-ANDROID.md`](docs/rules/610-ANDROID.md) — profil Android : structure, toolchain/SDK, compatibilité, packaging, configuration locale et validation plateforme.
- [`docs/rules/700-FRAMEWORKS.md`](docs/rules/700-FRAMEWORKS.md) — contrat commun des profils framework et de leur orchestration avec langages, plateformes et outils de build.
- [`docs/rules/710-TAURI.md`](docs/rules/710-TAURI.md) — profil Tauri 2 : host Rust, configuration/capabilities, hooks frontend, version produit, artefacts générés et validation d'intégration.

Le modèle de composition et d'ownership des profils est défini dans [`docs/architecture/003-RULE_PROFILE_MODEL.md`](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.