Add human review protocol and admin rules contract

docs/fiche-validation-humaine-modele.md

@@ -0,0 +1,71 @@
+# Fiche de validation humaine - modele
+
+## 1. Identification
+
+- Version / commit :
+- Date :
+- Relecteur metier :
+- Operateur :
+- Responsable qualite :
+- Portee :
+
+## 2. Perimetre relu
+
+- Familles documentaires :
+- Cas synthetiques relus :
+- Documents reels relus :
+- Regles ajoutees / modifiees :
+
+## 3. Resultats automatiques
+
+- Tests unitaires : OK / NOK
+- Suite synthetique rapide : OK / NOK
+- Corpus synthetique complet : OK / NOK
+- Corpus reel annote : OK / NOK / NA
+- Scanner de fuite : OK / NOK
+
+## 4. Checklist dossier par dossier
+
+### Cas / document :
+
+- Source :
+- Sortie relue :
+- Diff relu :
+
+#### Fuites
+
+- Nom / prenom patient : OK / NOK
+- Date de naissance : OK / NOK
+- Adresse / code postal / ville : OK / NOK
+- Telephone / email : OK / NOK
+- Identifiants administratifs : OK / NOK
+- Tableaux / en-tetes / pieds de page : OK / NOK
+
+#### Preservation
+
+- Services / actes / structures utiles conserves : OK / NOK
+- Formulations metier preservees : OK / NOK
+- Document exploitable pour le controle : OK / NOK
+
+#### Observations
+
+- Commentaires :
+- Type d'anomalie : BLOQUANT / MAJEUR / MINEUR / AUCUNE
+
+## 5. Decision globale
+
+- Decision :
+  - ACCEPTE
+  - ACCEPTE_AVEC_RESERVE
+  - REFUSE
+  - A_CORRIGER_PUIS_REVOIR
+
+- Motif :
+- Actions demandees :
+- Delai :
+
+## 6. Trace de validation
+
+- Nom validateur final :
+- Date :
+- Signature / attribution :

docs/protocole-validation-humaine.md

@@ -0,0 +1,263 @@
+# Protocole de validation humaine
+
+## 1. Objet
+
+Ce protocole sert a valider la fonction d'anonymisation avant diffusion ou activation
+d'une nouvelle version du moteur, d'une nouvelle regle ou d'une nouvelle famille de
+documents.
+
+Il ne remplace pas les tests automatiques. Il les complete sur le point qui compte
+le plus pour le projet : **le document anonymise est-il conforme et exploitable ?**
+
+## 2. Quand la validation humaine est obligatoire
+
+La validation humaine est obligatoire si l'un des points suivants est vrai :
+
+- modification du coeur d'anonymisation ;
+- ajout ou modification d'une regle de masquage globale ;
+- ajout ou modification d'une regle de preservation ;
+- changement sur les noms patients, dates de naissance ou identifiants structurants ;
+- nouvelle famille documentaire ;
+- ecart constate sur le corpus synthetique complet ou le corpus reel annote ;
+- demande explicite du responsable qualite ou du metier.
+
+## 3. Entrees minimales requises
+
+Avant la revue humaine, il faut disposer de :
+
+- l'identifiant de version ou de commit ;
+- la liste des changements ;
+- les resultats des tests unitaires ;
+- les resultats de la suite `tests/synthetic_regression/` ;
+- les resultats de la suite `tests/synthetic_review/` ;
+- les resultats du corpus reel annote si la modification est large ;
+- pour chaque cas relu, le triplet :
+  - source ;
+  - attendu ;
+  - produit reel.
+
+## 4. Roles
+
+### 4.1 Operateur de revue
+
+Prepare les elements de preuve :
+
+- sorties texte ;
+- diffs ;
+- rapport d'audit ;
+- resume des ecarts ;
+- liste des regles impactees.
+
+### 4.2 Relecteur metier
+
+Verifie que :
+
+- les donnees sensibles ne fuient pas ;
+- le document reste lisible ;
+- l'information utile au controle est preservee.
+
+### 4.3 Responsable qualite / referent
+
+Prend la decision finale :
+
+- accepte ;
+- accepte avec reserve ;
+- refuse ;
+- renvoie en correction.
+
+## 5. Corpus a relire
+
+### 5.1 Revue minimale
+
+Pour une correction locale :
+
+- les cas synthetiques impactes ;
+- les cas complets de `tests/synthetic_review/` impactes ;
+- au moins 2 documents reels proches du probleme corrige.
+
+### 5.2 Revue standard
+
+Pour une evolution de regles :
+
+- tous les cas complets de `tests/synthetic_review/` ;
+- un sous-ensemble reel annote representatif ;
+- un echantillon de documents non annotes mais proches de la production.
+
+### 5.3 Revue renforcee
+
+Pour une release importante :
+
+- toutes les familles documentaires critiques ;
+- un echantillon reel relu manuellement pour chaque famille ;
+- une analyse des nouveaux faux positifs et faux negatifs.
+
+## 6. Support de revue
+
+### 6.1 Pour les cas synthetiques complets
+
+Utiliser :
+
+- `tests/synthetic_review/cases/<cas>/test.txt`
+- `tests/synthetic_review/cases/<cas>/expected.txt`
+- `tests/synthetic_review/actual/<cas>/actual.txt`
+- `tests/synthetic_review/actual/<cas>/diff.txt`
+
+### 6.2 Pour les cas reels
+
+Utiliser :
+
+- le document source autorise ;
+- le texte pseudonymise ;
+- le PDF de sortie si disponible ;
+- l'audit JSON/JSONL ;
+- le rapport de fuite ;
+- le rapport d'evaluation si le document est annote.
+
+## 7. Checklist de revue dossier par dossier
+
+### 7.1 Fuites interdites
+
+Verifier l'absence de :
+
+- nom et prenom du patient ;
+- date de naissance ;
+- adresse, code postal, ville de residence ;
+- telephone et email ;
+- IPP, NDA, RPPS, FINESS, OGC, numero d'examen, numero interne ;
+- identifiants visibles en en-tete, pied de page, tableau ou bloc structure ;
+- identifiants coupes sur plusieurs lignes ;
+- variantes compactes ou prefixees type `N°1234567`.
+
+### 7.2 Preservation fonctionnelle
+
+Verifier que restent lisibles :
+
+- la structure du document ;
+- les services, actes et formulations metier legitimes ;
+- les dates non sensibles si elles doivent etre conservees ;
+- les libelles utiles au controle ;
+- les phrases metier explicitement preservees.
+
+### 7.3 Exploitabilite
+
+Verifier que le document reste :
+
+- comprehensible ;
+- utilisable par le controle ;
+- pas sur-caviarde au point de perdre sa valeur.
+
+## 8. Classification des anomalies
+
+### 8.1 Bloquant
+
+- fuite de PII patient ;
+- fuite d'un identifiant administratif critique ;
+- regression majeure sur plusieurs familles ;
+- regle active sans preuve de validation.
+
+Decision :
+
+- pas de release ;
+- correction obligatoire.
+
+### 8.2 Majeur
+
+- faux positif important qui rend le document difficilement exploitable ;
+- preservation non respectee sur un bloc metier cle ;
+- comportement instable ou non explicable.
+
+Decision :
+
+- correction avant activation large ;
+- ou activation limitee a un perimetre test.
+
+### 8.3 Mineur
+
+- ecart de forme sans perte de conformite ;
+- difference de rendu mineure ;
+- bruit d'audit sans impact document.
+
+Decision :
+
+- peut etre accepte si documente.
+
+## 9. Decision de validation
+
+Chaque revue doit se conclure par une decision explicite :
+
+- `ACCEPTE`
+- `ACCEPTE_AVEC_RESERVE`
+- `REFUSE`
+- `A_CORRIGER_PUIS_REVOIR`
+
+La decision doit citer :
+
+- la version revue ;
+- le nom du relecteur ;
+- la date ;
+- les cas relus ;
+- les anomalies ouvertes ;
+- la portee de la decision.
+
+## 10. Preuves a conserver
+
+Conserver a minima :
+
+- identifiant de commit ;
+- resultat des tests automatiques ;
+- liste des cas relus ;
+- fiche de validation humaine ;
+- rapport de diff ;
+- decision signee ou attribuee nominativement.
+
+## 11. Workflow operationnel recommande
+
+### Etape 1
+
+Executer les tests automatiques :
+
+- `pytest ...`
+- `python3 tools/run_synthetic_review_corpus.py`
+
+### Etape 2
+
+Preparer le lot de revue :
+
+- cas impactes ;
+- textes attendus ;
+- textes reels ;
+- synthese des ecarts.
+
+### Etape 3
+
+Faire la revue humaine avec la fiche standard.
+
+### Etape 4
+
+Classer chaque anomalie :
+
+- bloquant ;
+- majeur ;
+- mineur.
+
+### Etape 5
+
+Prendre une decision de version :
+
+- go ;
+- go limite ;
+- no go.
+
+## 12. Regle simple de gouvernance
+
+Une regle nouvelle n'est **jamais** activee directement en production si :
+
+- elle n'a pas de cas de test associe ;
+- elle n'a pas ete simulee ;
+- personne n'a valide ses effets visibles.
+
+## 13. Fichier associe
+
+Le modele de fiche a remplir est dans :
+
+- [fiche-validation-humaine-modele.md](/home/dom/ai/anonymisation/docs/fiche-validation-humaine-modele.md:1)

docs/spec-regles-administration.md

@@ -0,0 +1,307 @@
+# Specification MVP - regles d'administration
+
+## 1. Objet
+
+Cette specification decrit un MVP pour administrer des regles d'anonymisation
+sans modifier directement le code du moteur.
+
+Le but n'est pas de donner un acces libre a des regex dangereuses.
+Le but est de fournir un **moteur de regles gouverne**, testable et reversible.
+
+## 2. Objectifs fonctionnels
+
+Le MVP doit permettre de :
+
+- creer une regle ;
+- visualiser sa forme normalisee ;
+- simuler son effet sur un corpus cible ;
+- l'activer ou la desactiver ;
+- garder une trace complete des changements ;
+- lier chaque regle a des cas de test.
+
+## 3. Hors perimetre MVP
+
+Le MVP ne cherche pas encore a :
+
+- couvrir tous les cas regex complexes ;
+- gerer des workflows d'approbation multi-niveaux ;
+- remplacer toute la configuration coeur existante ;
+- editer directement les heuristiques internes du pipeline.
+
+## 4. Types de regles supportes
+
+### 4.1 `exact_term`
+
+Usage :
+
+- masquer un terme exact.
+
+Exemples :
+
+- `CHCB`
+- `LOCAL_SIGLE`
+
+Parametres principaux :
+
+- `match.exact_value`
+- `normalization.case_insensitive`
+- `normalization.whole_word`
+
+### 4.2 `normalized_identifier`
+
+Usage :
+
+- masquer une valeur canonique et ses variantes normalisees.
+
+Exemple :
+
+- valeur canonique : `1234567`
+
+Variantes attendues selon la configuration :
+
+- `1234567`
+- `N°1234567`
+- `N° 1234567`
+- `No1234567`
+- `Numero 1234567`
+
+Parametres principaux :
+
+- `match.canonical_value`
+- `normalization.accepted_prefixes`
+- `normalization.prefix_value_separators`
+- `normalization.allow_bare_value`
+- `normalization.multiline`
+
+### 4.3 `contextual_identifier`
+
+Usage :
+
+- masquer un identifiant seulement dans un contexte structure donne.
+
+Exemples :
+
+- `IPP : ABC12345`
+- `N° venue : 1234567`
+- `N° examen : 23L35781`
+
+Parametres principaux :
+
+- `match.canonical_value`
+- `match.context_prefixes`
+- `match.context_separators`
+- `normalization.multiline`
+
+### 4.4 `preserve_phrase`
+
+Usage :
+
+- garantir qu'une phrase ou formulation metier ne soit jamais masquee.
+
+Exemples :
+
+- `classification internationale`
+- `prise en charge`
+
+Parametres principaux :
+
+- `match.exact_value`
+- `normalization.case_insensitive`
+
+## 5. Structure des regles
+
+Le schema de reference est fourni ici :
+
+- [admin_rules.schema.json](/home/dom/ai/anonymisation/schemas/admin_rules.schema.json:1)
+
+Le template versionne est ici :
+
+- [admin_rules.default.yml](/home/dom/ai/anonymisation/config/admin_rules.default.yml:1)
+
+## 6. Champs minimaux par regle
+
+Chaque regle doit porter :
+
+- `id`
+- `label`
+- `type`
+- `action`
+- `status`
+- `match`
+- `scope`
+- `governance`
+
+Et, si `action = mask` :
+
+- `placeholder`
+
+## 7. Etats de cycle de vie
+
+### `draft`
+
+- regle redigee ;
+- jamais activee ;
+- pas encore validee.
+
+### `candidate`
+
+- regle complete ;
+- simulation en cours ;
+- revue humaine a faire.
+
+### `approved`
+
+- regle validee fonctionnellement ;
+- prete a etre activee.
+
+### `active`
+
+- regle exploitable en environnement autorise.
+
+### `disabled`
+
+- regle desactivee temporairement.
+
+### `retired`
+
+- regle retiree, conservee pour audit.
+
+## 8. Portee d'une regle
+
+Une regle ne doit pas etre globalisee par defaut.
+
+Le MVP doit permettre de preciser :
+
+- familles documentaires ;
+- environnements ;
+- zones documentaires :
+  - `narrative`
+  - `structured`
+  - `table`
+  - `header`
+  - `footer`
+
+## 9. Gouvernance minimale
+
+Chaque regle doit indiquer :
+
+- `owner`
+- `justification`
+- `created_at`
+- `review_required_for_activation`
+- `tests.required_case_ids`
+
+Pour une regle active, l'absence de cas de test associe doit etre interdite.
+
+## 10. Ecrans MVP recommandes
+
+### 10.1 Liste des regles
+
+Colonnes minimales :
+
+- id ;
+- label ;
+- type ;
+- status ;
+- scope ;
+- auteur ;
+- date ;
+- dernier test ;
+- dernier verdict.
+
+Actions :
+
+- filtrer ;
+- dupliquer ;
+- desactiver ;
+- ouvrir ;
+- comparer deux versions.
+
+### 10.2 Creation / edition d'une regle
+
+Blocs de formulaire :
+
+- identification ;
+- type ;
+- valeur source ;
+- normalisation ;
+- portee ;
+- gouvernance ;
+- rattachement des cas de test.
+
+### 10.3 Simulation
+
+Avant activation, afficher :
+
+- variantes generees ;
+- cas touches ;
+- extrait avant / apres ;
+- nouveaux masquages ;
+- pertes de preservation ;
+- verdict automatique.
+
+### 10.4 Validation / activation
+
+Le panneau d'activation doit afficher :
+
+- resultat du validateur de schema ;
+- resultat des tests lies ;
+- resultat du corpus de simulation ;
+- presence ou non d'une revue humaine ;
+- bouton `Activer` ou blocage.
+
+### 10.5 Historique
+
+Chaque changement doit laisser une trace :
+
+- qui ;
+- quand ;
+- quoi ;
+- pourquoi ;
+- sur quel perimetre ;
+- avec quel resultat.
+
+## 11. Garde-fous obligatoires
+
+Le MVP doit bloquer :
+
+- une regle active sans cas de test ;
+- une regle `preserve_phrase` avec action `mask` ;
+- une regle trop large sans justification ;
+- une activation sans simulation ;
+- une regle syntaxiquement invalide.
+
+## 12. Commande de validation hors interface
+
+Le depot fournit un validateur CLI :
+
+- [validate_admin_rules.py](/home/dom/ai/anonymisation/tools/validate_admin_rules.py:1)
+
+Exemple :
+
+```bash
+python3 tools/validate_admin_rules.py --config config/admin_rules.default.yml --show-variants
+```
+
+## 13. Recommandation d'implementation
+
+Ordre recommande :
+
+1. schema et validateur ;
+2. stockage YAML versionne ;
+3. simulation hors interface ;
+4. ecran d'edition ;
+5. ecran de simulation ;
+6. activation gouvernee.
+
+## 14. Point important
+
+Ces artefacts definissent le **contrat de regles** et le **MVP d'administration**.
+Ils ne branchent pas encore ces regles dans le moteur de production.
+
+La prochaine etape technique sera :
+
+- chargement de `admin_rules` ;
+- compilation ;
+- simulation ;
+- puis application controlee dans le pipeline.