rastreador-de-evolucion-de-documentos

¿Qué hace rastreador-de-evolucion-de-documentos?

Una habilidad autónoma que rastrea cómo un documento evoluciona a través de versiones. Dada una familia de versiones (un directorio con v1.md, v2.md, ... o archivos con marcas de tiempo), calcula diferencias a nivel de párrafo entre versiones consecutivas y rastrea el linaje de conceptos (introducidos / conservados / modificados / eliminados).

FLUJO DE TRABAJO OBLIGATORIO

Inicialización de dependencias (ejecutar en el primer uso)

Antes de la primera ejecución, verifica las dependencias de tiempo de ejecución para esta habilidad:

• Núcleo: biblioteca estándar pura — no requiere instalación.
• Opcional: PyYAML (solo cuando la configuración es un .yaml; las configuraciones JSON funcionan solo con la biblioteca estándar).

Si falta PyYAML y la configuración es YAML, informa al usuario y pregúntale si desea pip install pyyaml; instálalo solo después de su confirmación. Nunca instales en el entorno global sin consentimiento explícito.

1. Carga una configuración (config/examples/family.json como referencia; las configuraciones YAML también son compatibles cuando PyYAML está instalado).

2. Verifica que versions_dir contenga al menos dos archivos versionados.

3. Ejecuta python -m src.cli run --config <ruta> [--concepts "A,B"].

4. Reporta el conteo de transiciones y señala al usuario hacia ./evolution/evolution_<id_de_seguimiento>.{md,json}.

Cuándo usarlo

• Una familia de versiones de documentos (con marcas de tiempo o nombres secuenciales) debe ser comparada a lo largo del tiempo.
• El usuario solicita "seguir cambios de documento", "historial de versiones", "qué cambió entre borradores" o "linaje de conceptos".
• Un concepto con nombre (un término, un encabezado, una definición) debe ser rastreado a través de los borradores para ver cuándo se introdujo, modificó o eliminó.
• La evolución de un borrador debe reportarse como una línea de tiempo, no como una diferencia única de extremo a extremo.

Ejemplos de uso

# Validar una configuración y ver los archivos de versión descubiertos.
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json

# Ejecutar el rastreador; opcionalmente nombrar los conceptos a seguir.
python -m src.cli run --config config/examples/family.json --concepts "entropía,función de partición"

Los informes se escriben en ./evolution/evolution_<id_de_seguimiento>.{md,json}; la línea de tiempo en Markdown es para lectores, el JSON para uso programático.

Manejo de errores

• Configuración inválida (validate termina con código distinto de cero) — corrige el campo reportado y vuelve a validar; el esquema de nombres y versions_dir suelen ser los culpables.
• Menos de dos versiones descubiertas — la ejecución se cancela; verifica la regla version_naming con los nombres de archivo reales y reintenta.
• Un concepto nunca aparece — se reporta como ausente en todas las versiones, lo cual es un resultado válido, no un error.
• Código de salida inesperado — reporta el mensaje textual; no recurras a comparar los archivos manualmente.

Granularidad de diferencias

Granularidad	Regla de división
linea	Líneas no vacías
parrafo (predeterminado)	Bloques separados por líneas en blanco
oracion	Oraciones delimitadas por puntuación

Limitaciones

• La comparación es estructural (alineación de bloques mediante difflib), no semántica. Un concepto está "presente" solo cuando su frase exacta (sin distinción de mayúsculas/minúsculas) aparece en el texto de la versión.
• No se admiten esquemas de nombres personalizados más allá de secuencial/marca_de_tiempo.