First commit

2026-07-09 22:04:21 +00:00 · 2026-06-19 22:17:09 -03:00
commit 239203ee2a
533 changed files with 75195 additions and 0 deletions
--- a/specs/SPEC-011-Governance-Model.md
+++ b/specs/SPEC-011-Governance-Model.md
@@ -0,0 +1,347 @@
+# SPEC-011 — Governance Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Governança é o conjunto de papéis, responsabilidades, controles, aprovações, evidências e processos que permite que a Agent Platform OCI seja usada por múltiplos times sem perder padronização, segurança, rastreabilidade e capacidade de evolução.
+
+A governança não substitui a engenharia. Ela define como a engenharia evolui de forma controlada.
+
+Em uma plataforma de agentes, governança cobre:
+
+- quem pode criar agentes;
+- quem pode alterar prompts;
+- quem pode liberar MCP tools;
+- quem aprova mudanças de guardrails;
+- quem aprova modelos;
+- quem aprova datasets;
+- quem promove para produção;
+- quais evidências são obrigatórias;
+- como auditar decisões da plataforma.
+
+# 2. Problema que resolve
+
+Sem governança, cada time tende a criar agentes de forma diferente.
+
+Problemas comuns:
+
+- prompts sem versionamento;
+- MCP tools sem owner;
+- datasets ausentes;
+- agentes sem avaliação;
+- produção sem certification;
+- mudanças de modelo sem rastreabilidade;
+- guardrails duplicados;
+- regras de negócio dentro do runtime;
+- uso diferente da plataforma por cada fornecedor;
+- dificuldade de manutenção.
+
+A governança cria um modelo único de adoção.
+
+# 3. Domínios de governança
+
+| Domínio | Escopo |
+| --- | --- |
+| Platform Governance | Framework, Runtime, Gateways, Evaluator, Certification Suite. |
+| Agent Governance | Agentes, prompts, regras de negócio, datasets e configs. |
+| Model Governance | LLM profiles, providers, fallback, custo e uso. |
+| MCP Governance | Tools, MCP servers, owners, SLAs, autorização e contratos. |
+| Data Governance | BusinessContext, RAG, datasets, memória e retenção. |
+| Security Governance | Identidade, autorização, secrets, auditoria e PII. |
+| Operational Governance | Deploy, monitoramento, alertas, SLOs e incidentes. |
+| Evaluation Governance | Judges, evaluator, certification e métricas. |
+
+
+# 4. Modelo de ownership
+
+## 4.1. Platform Team
+
+Responsável por:
+
+- Agent Framework;
+- Agent Runtime;
+- Agent Gateway;
+- Channel Gateway;
+- AI Gateway;
+- MCP Gateway;
+- Evaluator;
+- Certification Suite;
+- contratos canônicos;
+- documentação da plataforma;
+- templates oficiais.
+
+## 4.2. Domain Team
+
+Responsável por:
+
+- comportamento do agente;
+- prompts;
+- regras de negócio;
+- datasets;
+- configurações específicas;
+- validação funcional;
+- critérios de sucesso.
+
+## 4.3. Integration Team
+
+Responsável por:
+
+- MCP servers;
+- APIs externas;
+- SLAs de tools;
+- contratos de integração;
+- credenciais de backend;
+- disponibilidade de sistemas externos.
+
+## 4.4. SRE / DevOps
+
+Responsável por:
+
+- CI/CD;
+- deploy;
+- observabilidade;
+- alertas;
+- capacidade;
+- SLOs;
+- runbooks;
+- rollback.
+
+## 4.5. Security / Architecture
+
+Responsável por:
+
+- segurança;
+- arquitetura;
+- policies;
+- Workload Identity;
+- secrets;
+- revisão de risco;
+- aprovação de exceções.
+
+# 5. RACI
+
+| Atividade | Platform | Domain | Integration | SRE | Security |
+| --- | --- | --- | --- | --- | --- |
+| Framework change | R/A | C | I | C | C |
+| Runtime change | R/A | C | I | C | C |
+| New agent | C | R/A | C | I | I |
+| New MCP tool | C | C | R/A | I | C |
+| Prompt change | I | R/A | I | I | C |
+| Guardrail change | R | C | I | I | A |
+| Model profile change | R | C | I | I | C |
+| Production deploy | I | C | C | R/A | C |
+| Security review | I | C | C | C | R/A |
+| Certification | R/A | C | C | I | I |
+
+
+# 6. Governança de agentes
+
+Todo agente deve possuir:
+
+```yaml
+agent:
+  id: telecom_contas
+  owner: billing_team
+  technical_owner: ai_platform_team
+  business_objective: "Atendimento sobre faturas, pagamentos e cobranças"
+  status: active
+  version: 1.0.0
+```
+
+Artefatos obrigatórios:
+
+- `agents.yaml`;
+- `routing.yaml`;
+- `prompt_policy.yaml`;
+- `guardrails.yaml`;
+- `judges.yaml`;
+- `tools.yaml`;
+- `mcp_parameter_mapping.yaml`;
+- dataset de regressão;
+- testes;
+- evidências de evaluator;
+- evidências de certification.
+
+# 7. Governança de prompts
+
+Prompts devem ser versionados e rastreáveis.
+
+```yaml
+prompt:
+  name: billing_system_prompt
+  version: 1.3.0
+  owner: billing_team
+  reviewed_at: 2026-06-19
+  status: approved
+```
+
+Mudanças de prompt exigem:
+
+1. revisão do domain owner;
+2. execução de dataset;
+3. evaluator;
+4. comparação contra baseline;
+5. registro da versão.
+
+# 8. Governança de guardrails
+
+Guardrails globais pertencem à plataforma/segurança.
+
+Guardrails por agente pertencem ao domínio, mas precisam seguir o contrato da plataforma.
+
+```yaml
+guardrail:
+  code: REVPREC
+  version: 2.0.0
+  owner: platform_security
+  phase: output
+  mode: enforce
+```
+
+Mudanças em guardrails `enforce` exigem certification.
+
+# 9. Governança de judges
+
+Judges devem ter objetivo, métrica, threshold e owner.
+
+```yaml
+judge:
+  name: groundedness
+  version: 1.1.0
+  threshold: 0.70
+  owner: platform_quality
+```
+
+Mudanças de threshold exigem reexecução do evaluator.
+
+# 10. Governança de modelos
+
+Agentes não referenciam modelo diretamente.
+
+O modelo é resolvido por profile.
+
+```yaml
+profiles:
+  judge:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+```
+
+Mudanças de modelo exigem:
+
+- validação de custo;
+- evaluator;
+- validação de qualidade;
+- validação de latência;
+- atualização de release notes.
+
+# 11. Governança de MCP
+
+Cada tool deve ter owner, SLA, timeout e contrato.
+
+```yaml
+tool:
+  name: consultar_fatura
+  version: 1.0.0
+  owner: billing_platform
+  sla: p95_2s
+  timeout_seconds: 30
+  idempotent: true
+```
+
+Tools mutáveis exigem política de confirmação.
+
+# 12. Governança de datasets
+
+Datasets são ativos de qualidade.
+
+```yaml
+dataset:
+  name: telecom_contas_regression
+  version: 1.0.0
+  owner: billing_team
+```
+
+Datasets devem conter:
+
+- entrada;
+- BusinessContext;
+- rota esperada;
+- tools esperadas;
+- critérios mínimos;
+- casos negativos;
+- casos de segurança.
+
+# 13. Processo de aprovação
+
+```mermaid
+flowchart LR
+    Dev[Development] --> Tests[Tests]
+    Tests --> Eval[Evaluator]
+    Eval --> Cert[Certification]
+    Cert --> Sec[Security Review]
+    Sec --> Arch[Architecture Approval]
+    Arch --> HML[Homologation]
+    HML --> PROD[Production]
+```
+
+# 14. Evidências obrigatórias
+
+- relatório de testes;
+- relatório evaluator;
+- relatório certification;
+- trace Langfuse;
+- logs e métricas;
+- checklist de segurança;
+- release notes;
+- versão dos artefatos.
+
+# 15. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Prompt sem owner | Dificulta manutenção e aprovação. | Definir owner no metadata. |
+| Tool sem SLA | Operação sem expectativa de resposta. | Registrar SLA em tools.yaml. |
+| Dataset ausente | Sem regressão objetiva. | Criar dataset mínimo. |
+| Guardrail hardcoded | Governança fora do YAML. | Mover para config. |
+| Modelo definido no agente | Quebra governança de modelos. | Usar AI Gateway profiles. |
+
+
+# 16. Critérios de aceite
+
+- [ ] Cada agente possui owner funcional e técnico.
+- [ ] Prompts estão versionados.
+- [ ] Tools MCP possuem owner, SLA e versão.
+- [ ] Guardrails possuem owner e modo.
+- [ ] Judges possuem threshold e versão.
+- [ ] Datasets estão versionados.
+- [ ] Evaluator roda por agente.
+- [ ] Certification aprova antes de produção.
+- [ ] Release possui evidências.
+- [ ] Exceções são documentadas.