document-evolution-tracker

O que document-evolution-tracker faz?

Uma skill autônoma que rastreia como um documento evolui ao longo das versões. Dada uma família de versões (um diretório com v1.md, v2.md, ... ou arquivos com carimbo de data/hora), ela calcula diferenças no nível de parágrafo entre versões consecutivas e rastreia a linhagem de conceitos (introduzido / mantido / modificado / removido).

FLUXO DE TRABALHO OBRIGATÓRIO

Bootstrap de dependências (executar na primeira execução)

Antes da primeira execução, verifique as dependências de tempo de execução para esta skill:

• Core: biblioteca padrão pura — nenhuma instalação necessária.
• Opcional: PyYAML (apenas quando o config for .yaml; configs JSON funcionam apenas com a biblioteca padrão).

Se o PyYAML estiver faltando e o config for YAML, informe o usuário e pergunte se deseja pip install pyyaml; instale somente após confirmação. Nunca instale no ambiente global sem consentimento explícito.

1. Carregue um config (config/examples/family.json como referência; configs YAML também são suportados quando PyYAML está instalado).

2. Verifique se versions_dir contém pelo menos dois arquivos de versão.

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

4. Relate a contagem de transições e aponte o usuário para ./evolution/evolution_<tracking_id>.{md,json}.

Quando usar

• Uma família de versões de documentos (arquivos com carimbo de data/hora ou nomeados sequencialmente) precisa ser comparada ao longo do tempo.
• O usuário pergunta "rastrear alterações no documento", "histórico de versões", "o que mudou entre rascunhos" ou "linhagem de conceitos".
• Um conceito nomeado (um termo, um cabeçalho, uma definição) precisa ser rastreado entre rascunhos para ver quando foi introduzido, modificado ou removido.
• A evolução de um rascunho precisa ser relatada como uma linha do tempo em vez de uma única comparação de ponta a ponta.

Exemplos de uso

# Validar um config e ver os arquivos de versão descobertos.
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json

# Executar o rastreador; opcionalmente nomear os conceitos a seguir.
python -m src.cli run --config config/examples/family.json --concepts "entropy,partition function"

Os relatórios são escritos em ./evolution/evolution_<tracking_id>.{md,json}; a linha do tempo em Markdown é para leitores, o JSON para uso programático.

Tratamento de falhas

• Config inválido (validate sai com código não-zero) — corrija o campo relatado e revalide; o esquema de nomenclatura e versions_dir são os culpados comuns.
• Menos de duas versões descobertas — a execução é abortada; verifique a regra version_naming em relação aos nomes reais dos arquivos e tente novamente.
• Um conceito nunca aparece — é relatado como ausente em todas as versões, o que é um resultado válido, não um erro.
• Código de saída inesperado — relate a mensagem textualmente; não recorra a fazer diff manual dos arquivos.

Granularidade do diff

Granularidade	Regra de divisão
line	Linhas não vazias
paragraph (padrão)	Blocos separados por linhas em branco
sentence	Frases delimitadas por pontuação

Limitações

• O diff é estrutural (alinhamento de blocos via difflib), não semântico. Um conceito está "presente" apenas quando sua frase exata (insensível a maiúsculas/minúsculas) aparece no texto da versão.
• Esquemas de nomenclatura personalizados além de sequential / timestamp não são suportados.