Suivi d'Évolution de Documents

document-evolution-tracker

Une compétence autonome qui suit l'évolution d'un document à travers ses versions. Étant donné une famille de versions (un répertoire contenant v1.md, v2.md, ... ou des fichiers horodatés), elle calcule les différences au niveau des paragraphes entre les versions consécutives et suit une lignée de concepts (introduit / conservé / modifié / supprimé).

WORKFLOW OBLIGATOIRE

Installation des dépendances (à la première exécution)

Avant la première exécution, vérifiez les dépendances d'exécution pour cette compétence :

• Cœur : bibliothèque standard uniquement — aucune installation requise.
• Optionnel : PyYAML (uniquement lorsque la configuration est un fichier .yaml ; les configurations JSON fonctionnent avec la bibliothèque standard seule).

Si PyYAML est manquant et que la configuration est au format YAML, prévenez l'utilisateur et demandez-lui s'il souhaite exécuter pip install pyyaml ; n'installez qu'après confirmation. N'installez jamais dans l'environnement global sans consentement explicite.

1. Chargez une configuration (utilisez config/examples/family.json comme référence ; les configurations YAML sont également prises en charge si PyYAML est installé).
2. Vérifiez que versions_dir contient au moins deux fichiers versionnés.
3. Exécutez python -m src.cli run --config <chemin> [--concepts "A,B"].
4. Signalez le nombre de transitions et dirigez l'utilisateur vers les fichiers ./evolution/evolution_<tracking_id>.{md,json}.

Quand l'utiliser

• Une famille de versions de documents (fichiers horodatés ou nommés séquentiellement) doit être comparée au fil du temps.
• L'utilisateur demande "suivre les modifications du document", "historique des versions", "ce qui a changé entre les brouillons", ou "lignée de concepts".
• Un concept nommé (un terme, un titre, une définition) doit être tracé à travers les brouillons pour voir quand il a été introduit, modifié ou supprimé.
• L'évolution d'un brouillon doit être rapportée sous forme de chronologie plutôt que d'une simple différence entre deux versions.

Exemples d'utilisation

# Validez une configuration et voyez les fichiers versionnés découverts.
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json

# Exécutez le traceur ; nommez éventuellement les concepts à suivre.
python -m src.cli run --config config/examples/family.json --concepts "entropie,fonction de partition"

Les rapports sont écrits dans ./evolution/evolution_<tracking_id>.{md,json} ; la chronologie Markdown est destinée aux lecteurs, le JSON à un usage programmatique.

Gestion des échecs

• Configuration invalide (validate se termine avec un code non nul) — corrigez le champ signalé et re-validez ; le schéma de nommage et versions_dir sont les causes habituelles.
• Moins de deux versions découvertes — l'exécution est abandonnée ; vérifiez la règle version_naming par rapport aux noms de fichiers réels et réessayez.
• Un concept n'apparaît jamais — il est signalé comme absent dans toutes les versions, ce qui est un résultat valide, pas une erreur.
• Code de sortie inattendu — signalez le message textuellement ; ne passez pas à la comparaison manuelle des fichiers.

Granularité du diff

Granularité	Règle de division
ligne	Lignes non vides
paragraphe (par défaut)	Blocs séparés par des lignes vides
phrase	Phrases délimitées par la ponctuation

Limitations

• La comparaison est structurelle (alignement de blocs via difflib), pas sémantique. Un concept est "présent" uniquement si son expression exacte (insensible à la casse) apparaît dans le texte de la version.
• Les schémas de nommage personnalisés autres que sequential / timestamp ne sont pas pris en charge.