95 lines
7.2 KiB
Markdown
95 lines
7.2 KiB
Markdown
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
|
|
<!-- version: 10 -->
|
|
|
|
# Matrice de validation PGR
|
|
|
|
## Rôle
|
|
|
|
Cette matrice décrit les validations canoniques du dépôt PGR. Elle évolue avec le projet et ne doit pas inventer des scripts uniquement pour remplir une case.
|
|
|
|
La matrice définit les contrôles disponibles ; chaque delta sélectionne uniquement ceux qui sont nécessaires pour son scope et les preuves qu'il peut avoir invalidées.
|
|
|
|
Les catégories et règles de sélection sont définies dans [`../rules/400-VALIDATION.md`](../rules/400-VALIDATION.md).
|
|
|
|
## Contrôles actifs
|
|
|
|
| ID | Catégorie | Commande / contrôle | Prérequis | Trigger | Phase | Coût | Acteur |
|
|
|---------------------|-----------|--------------------------------------------------------------------------------------|------------------------|---------------------------------|----------------------|--------|-----------------|
|
|
| `PGR-GIT-001` | `CHECK` | `git diff --check` ou `git diff --cached --check` selon l'état de l'index | Git | toute modification suivie | alpha/beta/RC/stable | faible | opérateur |
|
|
| `PGR-VERSION-001` | `CHECK` | comparer `VERSION` à la version attendue par le delta courant | fichier `VERSION` | changement de tranche/version | alpha/beta/RC/stable | faible | opérateur |
|
|
| `PGR-LAYOUT-001` | `AUDIT` | comparer les fichiers ajoutés/remplacés/supprimés au scope déclaré du delta | scope du delta | changement de structure | alpha/beta/RC/stable | faible | opérateur/revue |
|
|
| `PGR-DOC-001` | `AUDIT` | vérifier chemins, rôles et responsabilités des documents touchés | fichiers documentaires | modification documentaire | alpha/beta/RC/stable | faible | opérateur/revue |
|
|
| `PGR-MD-HEADER-001` | `AUDIT` | `python3 -B scripts/audit_markdown_headers.py <paths...>` | Python 3 | Markdown gouverné modifié | alpha/beta/RC/stable | faible | opérateur/CI |
|
|
| `PGR-MD-TABLE-001` | `AUDIT` | `python3 -B scripts/audit_markdown_tables.py <paths...>` | Python 3 | table Markdown ajoutée/modifiée | alpha/beta/RC/stable | faible | opérateur/CI |
|
|
| `PGR-NAV-001` | `AUDIT` | `python3 -B scripts/audit_markdown_links.py <paths...>` | Python 3 | navigation ou réconciliation | alpha/beta/RC/stable | faible | opérateur/CI |
|
|
| `PGR-SCOPE-001` | `AUDIT` | vérifier que les documents vivants pointent vers les propriétaires normatifs actuels | documents vivants | réconciliation de phase | beta/RC/stable | faible | revue |
|
|
| `PGR-STATUS-001` | `CHECK` | `git status --short` | Git | avant fermeture d'une tranche | alpha/beta/RC/stable | faible | opérateur |
|
|
|
|
Un contrôle manuel peut rester dans la matrice lorsqu'aucun audit automatisé fiable n'existe encore. PGR SHOULD automatiser uniquement les propriétés stables et objectivement contrôlables.
|
|
|
|
`PGR-MD-TABLE-001` reste volontairement monotâche : il contrôle uniquement la structure et l'alignement source des tableaux Markdown. Il couvre les tableaux Markdown ordinaires ainsi que les exemples placés dans des fences explicitement `markdown` ou `md`. Les autres blocs fenced restent ignorés afin de ne pas interpréter comme Markdown des sorties terminal, extraits de code ou tableaux ASCII d'un autre langage.
|
|
|
|
`PGR-MD-HEADER-001` contrôle seulement les deux premières lignes des fichiers Markdown sélectionnés : chemin relatif depuis la racine et révision interne positive. La revue `PGR-DOC-001` reste responsable du rôle documentaire et de la pertinence réelle d'un incrément de révision.
|
|
|
|
`PGR-NAV-001` est automatisé séparément par `audit_markdown_links.py`. Il vérifie uniquement l'existence des cibles de liens Markdown locaux inline, sans contrôler les anchors, les headers, les responsabilités documentaires ou la forme des tableaux.
|
|
|
|
PGR préfère plusieurs audits simples avec une responsabilité identifiable à un script unique qui agrège des règles indépendantes.
|
|
|
|
## Contrôles Rust réutilisables, hors gate du dépôt PGR
|
|
|
|
[`002-RUST_STYLE_AUDITS.md`](002-RUST_STYLE_AUDITS.md) décrit deux audits facultatifs : `audit_rust_blank_lines.py` contrôle l'espacement des lignes vides, `audit_rust_const_blocks.py` contrôle l'ordre et l'espacement des blocs de constantes au niveau racine. Ils acceptent des chemins Rust sélectionnés et partagent un petit support lexical ; leur validation ciblée dans PGR est `python3 -B -m unittest discover -s tests -p test_rust_audits.py`.
|
|
|
|
Leur disponibilité ne transforme pas PGR en workspace Rust et ne rend pas automatiquement l'ordre alphabétique applicable à chaque fichier d'un projet. Lors d'une adoption, le projet propriétaire sélectionne ses chemins après `cargo fmt` et applique sa propre gate ; Rustfmt et Clippy conservent les contrôles qu'ils possèdent.
|
|
|
|
## Politique Eclipse actuelle
|
|
|
|
Les métadonnées Eclipse spécifiques à une machine restent ignorées, notamment `.project`, `.classpath` et les préférences non partagées.
|
|
|
|
Le fichier suivant constitue une exception versionnée, car il porte l'encodage UTF-8 du projet et n'est pas nécessairement régénéré lors d'un import Git :
|
|
|
|
```text
|
|
.settings/org.eclipse.core.resources.prefs
|
|
```
|
|
|
|
Le `.gitignore` doit donc contenir :
|
|
|
|
```text
|
|
.settings/*
|
|
!.settings/org.eclipse.core.resources.prefs
|
|
```
|
|
|
|
## Gate documentaire courante
|
|
|
|
Pour une tranche documentaire, le delta sélectionne les contrôles nécessaires à son scope. Une gate typique peut inclure :
|
|
|
|
```bash
|
|
test "$(cat VERSION)" = "<version attendue>"
|
|
|
|
git diff --check
|
|
|
|
git add <fichiers du delta>
|
|
|
|
git diff --cached --check
|
|
|
|
git status --short
|
|
```
|
|
|
|
Le placeholder `<version attendue>` appartient à la documentation de la matrice ; chaque delta fournit la commande concrète avec sa propre version.
|
|
|
|
Selon le scope, la gate peut également vérifier que :
|
|
|
|
- les fichiers ajoutés/remplacés/supprimés correspondent au delta ;
|
|
- les headers `file/version` correspondent aux chemins réels ;
|
|
- les liens Markdown principaux sont cohérents ;
|
|
- aucun secret, chemin machine absolu ou artefact local non autorisé n'est introduit ;
|
|
- les exceptions Git intentionnellement versionnées restent effectivement traçables ;
|
|
- aucun répertoire ou contrôle n'est ajouté uniquement pour satisfaire une structure théorique.
|
|
|
|
## Autorité de validation
|
|
|
|
Une validation n'est `PASS` qu'après exécution réelle de la gate opérateur applicable. La génération du delta ou une prévalidation par l'IA ne constitue pas le résultat opérateur.
|
|
|
|
Les résultats `FAIL`, `PARTIAL` et `BLOCKED` doivent être enregistrés comme tels et ne doivent pas être transformés implicitement en PASS.
|
|
|
|
Après un `PASS`, l'history de la tranche validée est fourni séparément du delta suivant. Un `FAIL` reste normalement dans le scope de la tranche courante via `.fix.N`, sauf REPLAN, abandon ou supersession explicitement justifié.
|