0058 — A documentação começa pelo andamento: roadmap, especificações, arquitetura e implementação¶

Spec de ferramental: não toca apps/api, apps/web nem apps/e2e, e não tem superfície de autorização. O design foi conversado e aprovado em três partes (a página Andamento, a página Implementação, e navegação/build/verificação); este documento o registra.

Parte I — O problema¶

1. Dor¶

O site de documentação (docs.garantora.com.br) está organizado por tipo de documento — Getting Started, Produto, Specifications, Fixes, Tweaks, Arquitetura, ADRs, API, Operações, Templates, Guia para IA, Metadados —, doze abas na mesma altura. Quem abre o site para saber onde o projeto está não tem por onde começar:

• Não há página que diga o estado do projeto. A versão no ar só aparece no painel de Novidades do app ou no git tag; o que está em andamento só se descobre lendo o catálogo (docs/metadata/catalog.yaml) ou os status de dezenas de specs; o que vem a seguir está no meio do roadmap.
• A ordem não conta a história. O natural para quem acompanha o projeto — o que está acontecendo, para onde vai, o que foi especificado, como foi desenhado, o que já foi construído e o que falta — não corresponde a nenhuma sequência das abas.
• "O que falta construir" não tem lugar. A arquitetura descreve o desenho técnico; o que dele já existe e o que não existe está espalhado entre o roadmap (seções "❌ Ausente" e "Dívida técnica conhecida") e o registro de cada spec.
• Documento escrito à mão envelhece em silêncio. O roadmap ficou dois meses parado enquanto as specs 0005 a 0054 eram entregues (está registrado no topo dele); uma página de andamento escrita à mão teria o mesmo destino.

2. Quem sente¶

• O dono do produto e quem acompanha o projeto de fora (sócio, cliente) — querem saber o estado sem abrir o repositório. Caminho obrigatório: é a primeira pergunta de quem visita.
• Quem desenvolve — precisa saber o que falta construir em cada parte da arquitetura antes de propor trabalho novo (o pedido de baixa de parcelas em massa, abandonado em 2026-10-13 antes de virar spec, descrevia algo que o acerto da 0055 já fazia).

Não há volume a medir: o site deixou de ter senha em 2026-10-15 e não tem analytics.

3. A jornada de hoje¶

1. A pessoa abre docs.garantora.com.br e cai em "Início", uma página de orientação por tipo de documento.
2. Para saber a versão no ar, abre o app e o painel de Novidades, ou pergunta.
3. Para saber o que está em andamento, abre Specifications e lê a coluna de status de uma tabela com dezenas de linhas — ou o catalog.yaml.
4. Para saber o que vem a seguir, abre Produto → Roadmap e procura "❌ Ausente" e "Plano de entregas".
5. Para saber o que falta construir tecnicamente, cruza a arquitetura com a "Dívida técnica conhecida" do roadmap. ← quebra aqui: não há lugar que junte desenho e estado.

4. Resultado esperado¶

• Quem abre o site vê primeiro o andamento: versão no ar, o que entrou nas últimas versões, o que está aberto agora, o que vem a seguir — tudo gerado no build, sem envelhecer.
• A navegação segue a ordem Andamento → Roadmap → Especificações → Arquitetura → Implementação → Guias.
• Há uma página Implementação que diz, por elemento da arquitetura, o que já foi feito e o que falta.

Sabe-se que resolveu quando a página inicial do site mostra a versão publicada mais recente e as specs abertas sem que ninguém tenha editado a página.

5. Fora de escopo¶

• Mover arquivos de pasta. Só a navegação muda; os caminhos de docs/ ficam como estão, para nenhum link entre documentos quebrar.
• Gerar a tabela de docs/specifications/index.md ou docs/fixes/index.md a partir do catálogo. Cogitado e deixado de fora: o catálogo já é a fonte, e a tabela manual existe por decisão da ADR-0004.
• Analytics, busca nova, versão do site por release.
• Ler a versão no ar consultando a produção (/api/v1/health) durante o build: o build não depende de rede; a versão vem das notas.
• Mudar o conteúdo das specs, fixes e ADRs existentes.

Parte II — A experiência¶

7. Jornada pretendida¶

Ponto de entrada: https://docs.garantora.com.br/. A página inicial é o Andamento.

7.0 A página Andamento (gerada no build)¶

Na ordem em que aparece:

1. Versão no ar — número e data da nota de versão mais alta em apps/web/src/versoes/ (o /ship recusa deploy sem nota em origin/main, então a nota mais alta da main é a publicada; ressalva conhecida: um rascunho de nota ainda não publicado apareceria como no ar).
2. O que entrou nas últimas versões — as três notas mais recentes, com os itens como estão escritos (já são texto para quem usa o produto), e um link para o histórico completo (todas as notas, em ordem decrescente, numa seção recolhível da mesma página).
3. Em andamento — as specs e fixes do catálogo com status rascunho, aprovada ou em-implementacao, com link. Sem nenhum: "Nenhum trabalho aberto."
4. Próximos passos — os títulos ### das seções "❌ Ausente" e "Plano de entregas" do roadmap, cada um com link para a seção.
5. Números do projeto — specs concluídas, fixes corrigidos e versões publicadas, contados na hora do build.

7.0b A página Implementação¶

Uma página, uma seção por elemento da arquitetura, na ordem do C4: Web (apps/web), API (apps/api), Worker e jobs agendados, Integrações externas, Infra (local, dev-remote, produção), Testes. Cada seção tem:

• Feito — gerado no build onde o catálogo permite: as specs e os fixes concluídos cujo components cita web, api, infra ou e2e (Testes), como links. Worker e Integrações não têm marcação no catálogo: o "feito" deles é escrito à mão, em poucas linhas, com link para a spec de origem.
• Falta — escrito à mão: o que a arquitetura prevê e o código não tem.
• Dívida técnica — a seção "Dívida técnica conhecida" sai do roadmap e vem para cá, distribuída pelos elementos.

O roadmap fica com o olhar de negócio (modelo de domínio, situação por processo, implementado / parcial / ausente, decisões, plano de entregas); onde citava dívida técnica, aponta para Implementação.

7.0c Navegação¶

Seis abas:

1. Andamento
2. Roadmap — Visão, Roadmap
3. Especificações — Regras de negócio, Glossário, Design tokens, Padrões de UI, Navegação-alvo, Contexto de marca, Specs, Fixes
4. Arquitetura — Contexto, Containers, Componentes, Modelo de dados, Deployment, ADRs
5. Implementação
6. Guias — Como navegar (a orientação que hoje é a página inicial), Setup, Dia a dia, API, Operação (deploy, plataforma de documentação, troubleshooting), Templates, Guia para IA, Metadados, Tweaks (histórico)

7.1 Desktop¶

O tema da spec de documentação de 2026-10-15 (cores e tipografia do design system, largura total) continua. As seis abas cabem numa linha em 1440px. O Andamento usa os componentes de texto do Material — títulos, listas, tabelas e um bloco recolhível (??? note) para o histórico de versões —, sem HTML próprio.

7.2 Mobile (375px)¶

As abas viram o menu lateral do Material (comportamento padrão do tema). As listas do Andamento são texto empilhado; a tabela de números tem duas colunas (rótulo e valor) e cabe em 375px sem rolagem horizontal. As listas de "Feito" da Implementação são listas, não tabelas, pelo mesmo motivo.

7.3 Estados¶

• Fonte ausente no build (a pasta de notas, o catálogo ou uma das duas seções do roadmap): o build falha com mensagem dizendo qual fonte faltou. Uma página de andamento vazia passaria por verdadeira.
• Nenhum trabalho aberto: a seção diz isso, em vez de sumir.
• Nota de versão sem data ou sem itens: entra com o que tem; o hook não inventa data.

Parte III — Detalhamento¶

9. Regras¶

• RN1 — O hook. docs/hooks/andamento.py, registrado em mkdocs.yml (hooks:), gera as partes automáticas no evento on_page_markdown: substitui marcadores no Markdown da página — <!-- andamento --> em docs/index.md e <!-- implementacao:<elemento> --> em docs/implementacao.md — pelo conteúdo gerado. A lógica de leitura e montagem vive em funções puras no mesmo módulo (ler notas, ler catálogo, ler seções do roadmap, montar o Markdown), testáveis sem o MkDocs.
• RN2 — As notas de versão. Arquivos X.Y.Z.md em apps/web/src/versoes/; a primeira linha data: AAAA-MM-DD é a data; linhas que começam com - são itens (continuação indentada pertence ao item anterior). Ordenação por versão semântica, não por nome de arquivo (0.10.0 depois de 0.9.1).
• RN3 — O catálogo. docs/metadata/catalog.yaml; "em andamento" = type em specification/fix com status em rascunho, aprovada, em-implementacao; "concluídas" = specs concluida; "corrigidos" = fixes corrigido.
• RN4 — O roadmap. docs/roadmap.md; os itens de "Próximos passos" são os títulos ### sob os ## que começam com "❌ Ausente" e "Plano de entregas", com âncora no padrão do MkDocs (toc.slugify).
• RN5 — Falha cedo. Faltando a pasta de notas, o catálogo ou uma das duas seções do roadmap, o hook levanta erro e o mkdocs build --strict falha, nomeando o que faltou.
• RN6 — A página inicial. docs/index.md passa a ser o Andamento (texto curto de abertura + marcador). A orientação que estava nela vai para docs/guias.md ("Como navegar").
• RN7 — Implementação. docs/implementacao.md, escrito à mão com as seções da Parte II e os marcadores do "feito"; a "Dívida técnica conhecida" sai de docs/roadmap.md e entra aqui; o roadmap ganha uma linha apontando para Implementação.
• RN8 — Navegação. mkdocs.yml com as seis abas da 7.0c; nenhum arquivo de docs/ muda de caminho.
• RN9 — Build. O container de docs passa a ter apps/web/src/versoes/ dentro do contexto de build: infra/dev-remote/docs.Dockerfile ganha COPY apps/web/src/versoes/ ./apps/web/src/versoes/, e scripts/publicar-preview-docs.sh sincroniza essa pasta da branch sobre a base, como já faz com docs/. O hook a procura relativa ao diretório do mkdocs.yml (<raiz>/apps/web/src/versoes), que é o mesmo no host e no container.

Validação antes do merge: o script de publicação usa o Dockerfile da main por desenho (só o conteúdo vem da branch), e o da main ainda não copia as notas. Por isso a branch desta spec se valida com mkdocs build --strict local (numa venv com requirements-docs.txt, como o script já faz quando há .venv-docs) e com os testes do hook; a publicação no site acontece depois do merge, com publicar-preview-docs.sh main.

10. Autorização e isolamento¶

Sem superfície de segurança no produto: nenhum endpoint, tela ou dado do app muda. O site é público desde 2026-10-15 por decisão do usuário; esta spec não muda isso. As notas de versão já são públicas (vão no bundle do app, spec 0043, RN11).

11. Impacto por app¶

• apps/api, apps/web, apps/e2e — sem impacto (o hook só lê apps/web/src/versoes/).
• docs/hooks/andamento.py (novo), docs/hooks/test_andamento.py (novo, pytest, com fixtures em docs/hooks/fixtures/), docs/implementacao.md (novo), docs/guias.md (novo), docs/index.md, docs/roadmap.md, mkdocs.yml, infra/dev-remote/docs.Dockerfile, scripts/publicar-preview-docs.sh, docs/metadata/catalog.yaml e docs/specifications/index.md (esta spec).
• O MkDocs exclui docs/hooks/ do site (exclude_docs), para os testes e fixtures não virarem páginas.

12. Contrato¶

Sem contrato de API. O "contrato" é o formato das três fontes (RN2–RN4).

13. Critérios de aceite¶

• [x] CA1. (RN1, RN2, RN6) A página inicial do site mostra a versão mais alta de apps/web/src/versoes/ com a data dela, e as três notas mais recentes; com uma nota 0.10.0 e uma 0.9.1 nas fixtures, a mais alta é 0.10.0.
• [x] CA2. (RN3) "Em andamento" lista exatamente as specs e fixes com status rascunho, aprovada ou em-implementacao no catálogo; sem nenhum, mostra "Nenhum trabalho aberto."
• [x] CA3. (RN4) "Próximos passos" lista os ### de "❌ Ausente" e "Plano de entregas" do roadmap, com link que abre a seção.
• [x] CA4. (RN5) Sem a pasta de notas (ou sem o catálogo, ou sem uma das seções do roadmap), a função de montagem levanta erro nomeando a fonte — provado por teste.
• [x] CA5. (RN7) docs/implementacao.md tem as seis seções; "Feito" de Web, API, Infra e Testes lista as specs/fixes concluídos com aquele components; a "Dívida técnica conhecida" não está mais no roadmap e está em Implementação.
• [x] CA6. (RN8) A navegação tem as seis abas na ordem da 7.0c, e o mkdocs build --strict passa (nenhum link quebrado).
• [x] CA7. (RN9) Depois do merge, scripts/publicar-preview-docs.sh main publica o site com o Andamento preenchido; antes dele, mkdocs build --strict local passa com o hook.
• [x] CA8. (7.2) Em 375px, o Andamento e a Implementação não têm rolagem horizontal (scrollWidth - clientWidth == 0), conferido por print.
• [x] CA9. Os testes do hook passam com pytest docs/hooks/.

14. Plano de implementação¶

O plano detalhado sai do Superpowers writing-plans, em plan.md nesta mesma pasta.

15. Decisões em aberto¶

Nenhuma.

17. Revisão da implementação¶

18. Registro¶

Executado pelo Superpowers executing-plans (modo nativo), com o ledger em .superpowers/sdd/. O que divergiu do plano, e por quê:

• Sem commit por tarefa — o CLAUDE.md exige pedido explícito para commitar; a revisão final usou o diff da árvore de trabalho.
• O catálogo guarda a lista sob documents — a fixture do plano era uma lista solta. A fixture foi corrigida para o formato real (vermelho visto) e o hook lê documents.
• O marcador só conta sozinho na linha — a spec e o plano citam os marcadores em código inline, e o hook os trocava, gerando 24 links quebrados no build estrito. Teste test_marcador_citado_em_codigo_nao_e_trocado, vermelho antes da correção.
• docs/guias.md sem front matter, como o index.md: com front matter o docs_lint exigiria entrada no catálogo para uma página de navegação.
• .venv-docs no .dockerignore — a venv dos testes ia para o contexto de build de todas as imagens do dev-remote.
• CA8 provado no build local (servido na máquina), porque o site só recebe o Dockerfile novo depois do merge (RN9). O CA7 se confere depois do merge, com a publicação da main.

Revisão da branch: aprovada (nota 8). Ficaram como pendência, sem efeito hoje: links para a spec de origem no "feito" escrito à mão (Worker e Integrações); a lista "Resolvidos desde julho" que saiu do roadmap; bordas do parser de notas que o app trata diferente (data: sem validar, subitem indentado, tab); e títulos ### repetidos no roadmap, cuja âncora o hook não reproduziria.

Achado fora do escopo, levado ao usuário: o painel de Novidades do app (apps/web/src/versoes/index.ts, interpretar) corta os itens de nota que ocupam mais de uma linha no ponto da primeira quebra — o site de docs, que junta as linhas, e o app passam a mostrar textos diferentes da mesma nota.