# arquivo: .agent
# Agente de desenvolvimento para o projeto e-li.nps
#
# Projeto:
# Widget NPS embutível via 1 arquivo JS + API em Go.
# Foco em robustez, segurança, tipagem consistente, observabilidade
# e operação simples em ambientes reais (Docker / Proxy / Produção).

agent_name: "quero_nps"

# -------------------------------------------------------------------
# Descrição do projeto (fonte de verdade)
# -------------------------------------------------------------------
project_description:
  - "Widget NPS carregado via 1 arquivo JavaScript (e-li.nps.js)."
  - "API HTTP escrita em Go."
  - "PostgreSQL como banco de dados."
  - "Painel administrativo opcional protegido por senha."
  - "Uso por aplicações externas via <script>."
  - "Fail-closed: se a API falhar, o widget não abre."
  - "CORS liberado para uso amplo."

# -------------------------------------------------------------------
# Stack
# -------------------------------------------------------------------
project_stack:
  backend: "Go 1.22+"
  database: "PostgreSQL 14+"
  widget: "JavaScript puro (arquivo único)"
  frontend_internal:
    - "HTML server-side"
    - "HTMX (opcional, apenas se já estiver presente no painel)"
  optional_logic_layer:
    - "Go → WebAssembly (WASM), apenas se adotado explicitamente no projeto"

# -------------------------------------------------------------------
# Regras gerais
# -------------------------------------------------------------------
rules:
  - "Respeitar fielmente o comportamento descrito no README.md."
  - "Não alterar contratos públicos do widget sem versionamento."
  - "Evitar mudanças que quebrem widgets já embedados em clientes."
  - "Mudanças que impactem desenvolvedores OU usuários DEVEM ser documentadas."
  - "Código deve ser previsível, explícito e fácil de auditar."

# -------------------------------------------------------------------
# Linguagem, nomes e comentários
# -------------------------------------------------------------------
naming_and_language:
  - "Nomes de variáveis, funções e arquivos preferencialmente em português."
  - "Nomes orientados ao domínio NPS (ex: `registrarPedido`, `finalizarResposta`)."
  - "Comentários SEMPRE em português."
  - "Comentários devem explicar regras de negócio e decisões técnicas."

# -------------------------------------------------------------------
# Contratos e tipagens
# -------------------------------------------------------------------
typing_and_contracts:
  - "Contratos de API devem ser explícitos e estáveis."
  - "Campos-chave das regras de exibição: produto + inquilino_codigo + usuario_codigo."
  - "Normalizações técnicas NÃO alteram valores exibidos ao usuário."
  - "Tipagens JS/TS são auxiliares e não substituem validação no backend."
  - "Validação SEMPRE no servidor."

# -------------------------------------------------------------------
# Widget JavaScript
# -------------------------------------------------------------------
widget_policy:
  - "Widget deve ser carregado via um único <script>."
  - "Nenhuma dependência externa no cliente."
  - "Cache controlado exclusivamente pelo servidor via ETag."
  - "Browser sempre revalida o JS."
  - "Se a API falhar, o widget NÃO deve abrir (fail-closed)."

# -------------------------------------------------------------------
# Backend Go
# -------------------------------------------------------------------
backend_policy:
  - "Servidor Go é a autoridade de regras e persistência."
  - "Tabelas criadas automaticamente por produto: nps_{produto}."
  - "Normalização de produto SOMENTE para uso técnico."
  - "Nunca usar dados não normalizados em SQL."
  - "Painel só habilita se SENHA_PAINEL estiver definida."

# -------------------------------------------------------------------
# Segurança: prevenção de SQL Injection (OBRIGATÓRIO)
# -------------------------------------------------------------------
sql_injection_prevention:
  - "NUNCA concatenar SQL com entrada do usuário."
  - "Usar queries parametrizadas SEMPRE."
  - "Identificadores dinâmicos SOMENTE via normalização + regex + allowlist."
  - "Regex obrigatória: ^[a-z_][a-z0-9_]*$."
  - "ORDER BY dinâmico apenas com colunas previamente definidas."
  - "Toda decisão dinâmica de SQL deve ser comentada."

# -------------------------------------------------------------------
# Observabilidade e logs (OBRIGATÓRIO)
# -------------------------------------------------------------------
logging_policy:
  - "Registrar logs relevantes em toda a aplicação."
  - "Logar: inicialização, rotas, chamadas de API, banco e erros."
  - "Registrar tempo de execução das requisições."
  - "Incluir IP real do usuário quando disponível."
  - "Evitar log excessivo ou redundante."

# -------------------------------------------------------------------
# Proteção de segredos nos logs (CRÍTICO)
# -------------------------------------------------------------------
secrets_policy:
  - "NUNCA logar senhas, tokens, cookies, Authorization, secrets ou DSN."
  - "Campos sensíveis devem ser omitidos ou mascarados."
  - "Na dúvida, NÃO LOGAR."
  - "Usar '[REDACTED]' quando necessário."

# -------------------------------------------------------------------
# Proxy e IP real
# -------------------------------------------------------------------
proxy_policy:
  - "Respeitar X-Forwarded-For e X-Real-IP."
  - "Uso de middleware RealIP é obrigatório."
  - "Persistir IP real para auditoria."

# -------------------------------------------------------------------
# README.md — regra OBRIGATÓRIA
# -------------------------------------------------------------------
readme_policy:
  - "O README.md é a fonte de verdade operacional do projeto."
  - "SE a mudança for IMPORTANTE para o DESENVOLVEDOR, atualizar o README.md."
  - "SE a mudança for IMPORTANTE para o USUÁRIO, atualizar o README.md."
  - "Considera-se mudança importante:"
  - "– alteração de API, contrato ou payload"
  - "– mudança no widget ou forma de embed"
  - "– cache, ETag ou comportamento de atualização"
  - "– variáveis de ambiente"
  - "– segurança, CORS, autenticação ou painel"
  - "– forma de rodar, build ou deploy"
  - "O README deve explicar o impacto da mudança e como usar o novo comportamento."

# -------------------------------------------------------------------
# Checklist final
# -------------------------------------------------------------------
checklist:
  - "[ ] Compatível com widgets já publicados"
  - "[ ] SQL 100% parametrizado"
  - "[ ] Identificadores normalizados e validados"
  - "[ ] Logs relevantes presentes"
  - "[ ] Nenhum segredo em logs"
  - "[ ] Cache do JS controlado por ETag"
  - "[ ] README.md atualizado se a mudança impacta dev ou usuário"
  - "[ ] Fluxo principal testado manualmente"