AGENTS.md — Instruções para agentes de IA neste repositório

Leitura obrigatória

Antes de qualquer edição, leia integralmente:

rede_civica.md — compilado definitivo do modelo, fonte da verdade.
contexto_IA.md — resumo técnico-conceitual derivado do compilado.
O SDS da área afetada, quando a edição tocar implementação.
Este AGENTS.md e o CONTRIBUTING.md.

Sem essa leitura, a edição corre o risco de contradizer o modelo ou divergir dos contratos técnicos.

O que é este repositório

Repositório de documentação do projeto Rede Cívica. Não há código aqui. Os repositórios de código vivem na org:

mvp-api: back-end NestJS, monolito modular orientado a eventos.
mvp-web: front-end React, PWA map-first.

Toda contribuição parte da leitura do compilado e respeita a hierarquia das fontes descrita abaixo.

Hierarquia das fontes

rede_civica.md é o compilado definitivo do projeto. É a referência para todo o conteúdo conceitual.
contexto_IA.md é o resumo técnico-conceitual para agentes de IA. Deve refletir fielmente o compilado.
sds/ reúne as especificações de software. O Apêndice B traz as fichas das colônias e o mapa de dependências, e a ficha da taxonomia define as categorias.
politica_privacidade.md é o texto canônico exibido no aplicativo.
deploy.md, mapa_e_tiles.md, estatuto_empresa_socializada.md e rastros_conteudo.md são documentos temáticos.

Quando dois documentos divergirem, o compilado vence. A correção do divergente entra na mesma leva.

Estilo de escrita

Estrutura das frases

Frases curtas e autônomas. Cada frase carrega uma ideia, ponto final, próxima frase.
Evite subordinadas encadeadas e períodos longos com múltiplas vírgulas.
Quando uma ideia precisar de dois lados, use duas frases separadas.

Conclusões e contrapontos

Conclusões saem da sequência do texto. Não abra frase com “Em síntese”, “Portanto” ou “Nesse cenário”.
Contraponto vira frase nova, não cláusula de contraste na mesma frase.
Evite fechar parágrafo com frase de impacto.

Referências e termos técnicos

Cite lei ou artigo apenas quando for essencial. Uma ou duas referências por trecho.
Termo técnico desconhecido para leitor leigo ganha explicação curta inline. Sem nota de rodapé.

Listas

Lista é sequência de itens concretos. Itens curtos, uma linha por item, sem subordinadas.

O que evitar

Travessão como recurso retórico, no padrão “X — mas Y”.
Adjetivos empilhados para dar peso.
Frases de virada que empacotam o argumento.
Verbo reflexivo rebuscado quando a forma direta cabe melhor.
Tom promocional, clichê e jargão dramático sem respaldo conceitual.

Nomenclatura de arquivos

Títulos descritivos em português, com espaços e acentos.
Extensão .md para todo documento.
Exceção: o guia visual infografico_formigueiro.html e o infografico_formigueiro.pdf gerado a partir dele.

Como editar o compilado

Leia a seção relevante e o contexto_IA.md.
Mantenha o tom e o estilo do documento original.
Verifique se o ajuste afeta outras seções ou partes do compilado.
Se a mudança tocar princípio ou escopo, atualize o contexto_IA.md na mesma leva.
Não contradiga outras partes do compilado. Conflito se sinaliza antes de aplicar.

Como criar uma seção nova

Verifique se o tema já não está coberto em outra seção.
Posicione a seção na parte correta do índice.
Siga a formatação das seções existentes.
Atualize o contexto_IA.md com o resumo da seção.

Como atualizar o contexto_IA.md

O contexto reflete o compilado. Priorize estrutura e princípios. Detalhes numéricos e exemplos operacionais ficam apenas no compilado.

Princípios que não mudam sem instrução explícita

Sorteio, um conselheiro por demanda, IA não decide e transparência radical.
Estrutura de 7 níveis de unidades cívicas.
Distinção entre conselho de unidade cívica e conselho interno de empresa.
Papel não decisório da IA.
Sequência das duas rupturas na camada de empresas.

SDS como contrato

O SDS define o contrato de implementação de cada colônia. Mudança de contrato exige atualizar o SDS e os repositórios de código na mesma leva.
O código implementado é a referência viva dos endpoints. Quando o SDS divergir do que a API expõe, corrija o SDS.
O Apêndice B reúne as fichas das colônias e o mapa de dependências. Consulte antes de especificar fluxo novo.

Protocolo de sincronização de parâmetros

Parâmetros de negócio têm dois espelhos públicos:

Apêndice C de rede_civica.md, com valor, fonte e mecanismo de revisão.
repos/web/public/public-parameters.json, o espelho estruturado que alimenta a página de parâmetros.

Regras, sem exceção:

Parâmetro alterado no código exige atualizar os dois espelhos na mesma leva.
Parâmetro novo exige linha no Apêndice C e entrada no JSON.
Divergência entre código e documento é defeito. A correção entra por um dos lados e a leva registra.
Valor de referência do modelo só muda junto com a mudança de código correspondente.

Protocolo da política de privacidade

O texto canônico é politica_privacidade.md. O aplicativo mantém o espelho em repos/web/src/lib/lgpd/politica-privacidade.ts e a versão do termo em VERSAO_TERMO_PRIVACIDADE.

Mudou o texto canônico: atualize o espelho e, quando a mudança afetar o consentimento, eleve a versão do termo.
Mudou a versão no aplicativo: atualize o cabeçalho do texto canônico.
Mudança na operação de tratamento acompanha o registro de privacidade do projeto.

Regra de não referência interna

Todo o conteúdo deste repositório é público. Nenhum arquivo cita repositórios, planos, auditorias ou documentos internos que não estejam publicados na org. Antes de commitar, varra o diff e remova qualquer caminho, nome ou citação desse tipo.

Fluxo de contribuição

O fluxo completo está no CONTRIBUTING.md. Resumo: issue primeiro, fork, branch a partir de master, Conventional Commits em português, aceite do CLA no pull request, pull request pelo template da org e revisão de um mantenedor.

Gates deste repositório

Markdown passa no markdownlint e os links resolvem. O CI roda os dois checks.
Sincronização dos parâmetros e da política de privacidade quando a leva tocar os espelhos.
Revisão por leitura para tom, coerência e hierarquia das fontes.
Push no master publica o site de documentação: o workflow notificar-site.yml dispara a atualização em docs.redecivica.com.br.

Checklist pré-commit

A fonte da verdade e o contexto_IA.md estão sincronizados.
Nenhum arquivo cita repositório, plano ou documento interno.
Links internos e externos resolvem.
Parâmetros públicos sincronizados nos dois espelhos, quando aplicável.
Texto canônico e espelho da política de privacidade sincronizados, quando aplicável.
Markdown e links verificados localmente.

Git — regras

Commits atômicos, no formato Conventional Commits em português. Exemplos:

docs: adicionar seção de governança de parâmetros

fix: corrigir divergência entre o compilado e o contexto_IA.md

update: expandir a ficha da D-4 no Apêndice B

refactor: reorganizar a Parte III do compilado

Nunca commite sem confirmação explícita do usuário.