First commit

specs/SPEC-017-Release-Management-and-CICD.md

@@ -0,0 +1,144 @@
+# SPEC-017 — Release Management and CI/CD
+
+## 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
+
+Release management define como mudanças entram na plataforma, são testadas, empacotadas, publicadas, promovidas e auditadas.
+
+CI/CD automatiza validações e reduz risco operacional.
+
+# 2. Pipeline padrão
+
+```mermaid
+flowchart LR
+    C[Commit] --> L[Lint]
+    L --> TC[Type Check]
+    TC --> UT[Unit Tests]
+    UT --> IT[Integration Tests]
+    IT --> CT[Contract Tests]
+    CT --> SS[Security Scan]
+    SS --> B[Build]
+    B --> P[Publish]
+    P --> DD[Deploy Dev]
+    DD --> ST[Smoke Tests]
+    ST --> CERT[Certification]
+    CERT --> HML[Deploy HML]
+    HML --> PROD[Deploy Prod]
+```
+
+# 3. Stages
+
+| Stage | Função |
+| --- | --- |
+| validate | Validação inicial de estrutura. |
+| lint | Estilo e erros simples. |
+| type_check | Tipos e contratos Python. |
+| unit_test | Testes unitários. |
+| integration_test | Integrações locais. |
+| contract_test | Contratos JSON/YAML/API. |
+| security_scan | Dependências, secrets e imagens. |
+| build_package | Wheel/package. |
+| build_image | Imagem Docker. |
+| publish | Registry/artifacts. |
+| deploy_dev | Ambiente dev. |
+| smoke_test | Health e chamadas básicas. |
+| certification | Certification Suite. |
+| deploy_hml | Homologação. |
+| deploy_prod | Produção. |
+
+
+# 4. Artefatos de release
+
+- imagem Docker;
+- pacote Python;
+- release notes;
+- matriz de compatibilidade;
+- migration guide quando necessário;
+- evaluator report;
+- certification report;
+- SBOM quando aplicável;
+- evidência de scan;
+- changelog.
+
+# 5. Exemplo de pipeline
+
+```yaml
+stages:
+  - lint
+  - test
+  - contract
+  - security
+  - build
+  - publish
+  - deploy
+  - certification
+```
+
+# 6. Gates
+
+| Gate | Quando aplica |
+| --- | --- |
+| Architecture Gate | Mudanças estruturais, contratos, runtime, gateways. |
+| Security Gate | Segredos, identidade, dados sensíveis, MCP externo. |
+| Quality Gate | Testes, evaluator, certification. |
+| Operations Gate | Dashboards, alertas, runbook, rollback. |
+
+
+# 7. Estratégia de rollback
+
+Rollback deve restaurar:
+
+- imagem anterior;
+- configuração anterior;
+- contrato anterior;
+- prompt anterior;
+- dataset anterior quando necessário;
+- migration de banco quando aplicável.
+
+# 8. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Deploy sem certification | Risco funcional. | Rodar certification no pipeline. |
+| Sem release notes | Sem rastreabilidade. | Publicar release notes. |
+| Sem contract tests | Quebra integração. | Adicionar testes de contrato. |
+| Sem rollback | Risco operacional. | Definir estratégia de rollback. |
+
+
+# 9. Critérios de aceite
+
+- [ ] Pipeline executa lint, type check e testes.
+- [ ] Contract tests executam.
+- [ ] Security scan executa.
+- [ ] Imagem Docker gerada.
+- [ ] Artifacts publicados.
+- [ ] Smoke tests executados.
+- [ ] Certification executada.
+- [ ] Release notes publicadas.
+- [ ] Rollback definido.
+- [ ] Evidências arquivadas.