KOLOS — Padrão de Documentação (Doc-First)

Contexto

O KOLOS segue “Doc-First”: mudanças precisam ser rastreáveis e reproduzíveis. Sem um padrão, é comum faltar:

• Rotas/URLs/nomes
• Regras de acesso (roles/permissions/policies)
• Passos de validação reais

Decisão

Adotar um padrão mínimo para qualquer mudança que altere comportamento, infraestrutura, rotas, ou acesso.

Padrão mínimo (obrigatório)

Para cada mudança em docs/changes/YYYY-MM-DD_slug.md:

1. Contexto: qual problema/risco/requisito motivou.
2. Decisão: o que foi escolhido + alternativa descartada (quando relevante).
3. Rotas e Acesso (quando aplicável):
   • METHOD /path + route name
   • Middlewares (auth, guest, role:*, etc.)
   • Policies/Gates (authorize(...), @can, etc.)
4. Commands / Jobs / Eventos (quando aplicável): assinatura e propósito.
5. Passos: comandos (sempre com sail) e fluxos manuais.
6. Validação: como provar que funciona (tests/URLs/logs).
7. Impacto: arquivos alterados e efeitos colaterais conhecidos.

Convenções

• Rotas novas/alteradas devem ser registradas também em docs/architecture/kolos_registro-de-rotas.md.
• Se a mudança afeta permissões/policies, incluir:
  • permissão (venue.manage_courts etc.)
  • regra de escopo/tenancy (ex.: dono da arena)
  • testes cobrindo allow/deny
• Preferir textos curtos, objetivos, reproduzíveis.

Checklist rápido

• O documento tem Contexto e Decisão?
• Rotas (path + name) foram incluídas?
• Acesso (middleware/role/policy) foi descrito?
• Há comandos de validação via sail?
• O índice foi atualizado (README correspondente)?