ADR-0024: Automação da Sincronização de READMEs para a Wiki em Pipeline CI/CD

Este documento especifica a decisão de arquitetura para a automação do espelhamento de arquivos README.md de aplicações (./apps/) e pacotes (./packages/) para a árvore de conteúdo da Wiki (/content/wiki/apps/ e /content/wiki/packages/) dentro da esteira de CI/CD do GitHub Actions (.github/workflows/gbr_ssg_deploy.yml).

1. Contexto e Motivação

Com a conversão inicial dos READMEs em páginas .djot realizada no ADR-0023, estabelecemos a disponibilidade da documentação técnica na Wiki estática. No entanto, a manutenção manual desses arquivos geraria risco de desatualização (drift) sempre que um desenvolvedor atualizasse o README.md de uma biblioteca ou aplicação.

Para eliminar qualquer necessidade de manutenção manual e garantir que a Wiki reflita rigorosamente 100% da documentação atualizada a cada commit ou pull request, implementaremos um script de sincronização autônomo executado nativamente pelo workflow de Continuous Integration & Delivery (CI/CD).

2. Decisão Arquitetural

1. **Script Utilitário de Sincronização (apps/gbr_ssg/scripts/sync_wiki_readmes.py):** - Varre recursivamente a estrutura de subdiretórios ./apps/*/README.md e ./packages/*/README.md. - Extrai a primeira linha H1 como título do documento (ou utiliza o nome do componente como fallback). - Injeta o frontmatter TOML obrigatório (layout = "wiki", category = "Aplicações" ou "Pacotes"). - Salva e sobrescreve o arquivo .djot correspondente em apps/gbr_ssg/content/wiki/apps/<app>.djot e apps/gbr_ssg/content/wiki/packages/<package>.djot. - Detecta automaticamente a adição de novos pacotes/apps sem necessidade de modificar a lógica do script (varredura dinâmica por sistema de arquivos/glob).

2. **Integração no GitHub Actions Workflow (.github/workflows/gbr_ssg_deploy.yml):** - Inclusão do acionador de caminho (paths) para alterações em apps/**/README.md e packages/**/README.md. - Adição do step Sync READMEs to Wiki no job cd imediatamente antes da etapa Compile static content (gleam run -- --input=./content --output=./dist).

3. Requisitos EARS

*Requisitos Ubíquos (Ubiquitous Requirements)* - *UBQ-01 (Detecção Dinâmica de Componentes):* O script de sincronização DEVE varrer recursivamente todos os subdiretórios em ./apps/ e ./packages/ identificando novos arquivos README.md automaticamente. - *UBQ-02 (Injeção de Frontmatter Válido):* Todo arquivo .djot gerado pelo script DEVE conter o bloco frontmatter TOML compatível com o layout wiki do gerador gbr_ssg.

*Requisitos de Resposta a Eventos (Event-Driven Requirements)* - *EVT-01 (Sincronização Pré-Build no CI):* QUANDO a esteira de CD for disparada no GitHub Actions, O workflow DEVE executar a sincronização dos READMEs antes da etapa de compilação estática (gleam run).