Aller au contenu

Refonte des tags des rapports d'activité

Billet #149 : Refonte des tags des rapports d'activité
Type : Gouvernance / Documentation / Assurance qualité
Composants concernés : docs/activity_report/*.md, docs/fr/activity_report/*.md, scripts/tag_inventory.py, scripts/tag_group_by_category.py, scripts/migrate_tags.py, tests/test_activity_report_governance.py

1. Contexte et intention initiale

Le travail est parti d'un objectif stratégique : rendre les tags des rapports d'activité fiables, comparables et gouvernables dans la durée, sur la documentation EN et FR.

Au départ, le problème ne concernait pas uniquement des libellés de tags. C'était un enjeu de gouvernance plus large :

  1. tags dupliqués ou ambigus ;
  2. casses et alias historiques mélangés ;
  3. tags année confondus avec les tags métier ;
  4. qualité de métadonnées inégale selon les rapports ;
  5. absence de garde-fou strict pour éviter les régressions.

Le résultat visé était clair : passer d'un étiquetage ponctuel à une taxonomie canonique imposable, avec des contrôles vérifiables.

2. De l'idée au cadrage (réflexions et décisions)

Avant l'implémentation, une phase de conception de taxonomie et d'alignement a été menée.

Principales décisions issues de la réflexion :

  1. établir une taxonomie canonique unique en anglais ;
  2. structurer les tags par catégories explicites (workstream, domaine technique, qualité, temporalité, etc.) ;
  3. définir une table de correspondance des alias pour les étiquettes historiques ;
  4. plafonner le nombre de tags pour protéger la lisibilité et la qualité du signal ;
  5. valider d'abord EN, puis propager FR avec contrôle de parité.

Cette phase a posé les bases d'une migration déterministe et d'une gouvernance testable.

3. Parcours d'implémentation

3.1 Inventaire et diagnostic

Trois couches ont été livrées pour piloter les décisions par les données :

  1. extraction d'inventaire des tags existants ;
  2. regroupement par catégories canoniques avec normalisation des alias ;
  3. matrice de migration historique → canonique avec justification explicite.

Cela a rendu les incohérences visibles et a supprimé les arbitrages subjectifs pendant la migration.

3.2 Migration canonique (EN puis FR)

Un script dédié a appliqué la canonicalisation à l'échelle :

  1. normalisation de casse et format ;
  2. résolution des alias vers les tags canoniques ;
  3. application de l'unicité par catégorie ;
  4. application du nombre maximal d'étiquettes ;
  5. conservation des métadonnées temporelles dans la bonne catégorie.

La migration a été exécutée d'abord sur EN, puis alignée sur les rapports miroirs FR.

3.3 Validation formelle de gouvernance

Un verrou Pytest formel a été ajouté pour vérifier chaque rapport selon les règles de gouvernance mentionnées en annexe.

Pendant le renforcement de validation, une cause racine invisible a été identifiée : plusieurs fichiers contenaient un BOM UTF-8 avant ---, provoquant de faux diagnostics "frontmatter manquant".

Correction appliquée :

  1. suppression du BOM sur les fichiers concernés ;
  2. renforcement du test pour tolérer proprement le BOM ;
  3. échec explicite si frontmatter absent ou incomplet (plus de contournement silencieux).

La validation est ainsi passée d'un mode permissif à un mode strict et auditable.

4. Résultat opérationnel

À la clôture, le dispositif atteint un niveau de contrôle complet :

  1. les tags canoniques sont appliqués dans les versions EN et FR ;
  2. la validation de gouvernance passe proprement sur l'ensemble des rapports ;
  3. les artefacts Speckit (spec, plan, tasks) sont alignés avec la réalité d'exécution ;
  4. la maintenance de la taxonomie est documentée pour la suite.

Instantané de validation final pendant la clôture : tests de gouvernance valides sur l'ensemble des rapports (58/58), sans échec de règle d'étiquetage.

5. Enseignements

  1. Une refonte de taxonomie doit commencer par inventaire + diagnostic, pas par édition directe.
  2. La qualité de gouvernance dépend de tests stricts ; les skips permissifs masquent le risque.
  3. Les artefacts d'encodage invisibles (BOM) peuvent invalider des flux de traitement des métadonnées pourtant corrects.
  4. La gouvernance documentaire reste durable seulement si conception, scripts, tests et artefacts process restent synchronisés.

6. Conclusion

Cette initiative n'a pas seulement nettoyé des tags : elle a installé un système de gouvernance durable.

Le projet dispose maintenant d'une boucle reproductible : idée → politique → automatisation → validation formelle, en alignement avec l'approche Speckit et prête pour les prochaines extensions.

Annexe : Taxonomie canonique des tags (gouvernance)

Pour garantir la conformité documentaire et la gouvernance durable, la taxonomie suivante a été adoptée pour tous les rapports d’activité :

Règles de gouvernance

  • Maximum 5 tags par rapport.
  • Maximum 3 tags par catégorie canonique (sauf TemporalMetadata).
  • Les tags année (year-2025, year-2026) sont autorisés uniquement dans TemporalMetadata.
  • Le frontmatter YAML est obligatoire sur chaque rapport.

Catégories canoniques

  • Workstream : automation, debugging, documentation, migration, operations, governance
  • ChangeType : bugfix, feature, refactor, hardening, improvement
  • TechnicalDomain : frontend, backend, api, database, infrastructure, pipeline, security, data, ci-cd
  • QualityAttribute : reliability, performance, observability, scalability, maintainability, compliance, data-integrity
  • TechnicalExpertise : architecture, design-patterns, incident-response, cost-optimization
  • TechnologyLanguage : python, typescript, playwright, pytest, mkdocs, docker, postgresql, marketstack, github-actions, nginx
  • NonTechnicalExpertise : documentation, process-improvement, risk-management, business-analysis, decision-support
  • TemporalMetadata : year-2025, year-2026

Commande de validation

Pour vérifier la conformité d’un rapport :

.venv/Scripts/python.exe -m pytest -v tests/test_activity_report_governance.py

Référence de la matrice de correspondance des étiquettes :

  • specs/004-activity-tags-refactor/tag-migration-matrix.csv