fix: Spec Agent Runtime

specs/en/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
+
+
+---
+
+## Reading guide
+
+each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
+
+The document structure is:
+
+1. Concept.
+2. Problem addressed.
+3. When to use.
+4. When not to use.
+5. Architecture.
+6. Implementation.
+7. Examples.
+8. Common errors.
+9. Acceptance criteria.
+
+---
+
+
+# 1. Concept
+
+Release management Defines como changes entram on the platform, are testadas, empacotadas, publicadas, promovidas and auditadas.
+
+CI/CD automatiza Validations and reduz Risk operacional.
+
+# 2. Pipeline Standard
+
+```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 | Validation inicial of structure. |
+| lint | Estilo and erros simples. |
+| type_check | Tipos and contracts Python. |
+| unit_test | Tests unitários. |
+| integration_test | Integrações locais. |
+| contract_test | contracts JSON/YAML/API. |
+| security_scan | Dependências, secrets and imagens. |
+| build_package | Wheel/package. |
+| build_image | Imagem Docker. |
+| publish | Registry/artifacts. |
+| deploy_dev | Ambiente dev. |
+| smoke_test | Health and Calls básicas. |
+| certification | Certification Suite. |
+| deploy_hml | Homologação. |
+| deploy_prod | Production. |
+
+
+# 4. artifacts of release
+
+- imagem Docker;
+- pacote Python;
+- release notes;
+- matriz of compatibility;
+- migration guide when necessário;
+- evaluator report;
+- certification report;
+- SBOM when aplicável;
+- evidência of scan;
+- changelog.
+
+# 5. Example of pipeline
+
+```yaml
+stages:
+  - lint
+  - test
+  - contract
+  - security
+  - build
+  - publish
+  - deploy
+  - certification
+```
+
+# 6. Gates
+
+| Gate | when applies |
+| --- | --- |
+| Architecture Gate | changes estruturais, contracts, runtime, gateways. |
+| Security Gate | Segredos, Identity, Data sensíveis, MCP External. |
+| Quality Gate | Tests, evaluator, certification. |
+| Operations Gate | Dashboards, Alerts, runbook, rollback. |
+
+
+# 7. Estratégia of rollback
+
+Rollback must restaurar:
+
+- imagem previous;
+- Configuration previous;
+- Contract previous;
+- prompt previous;
+- dataset previous when necessário;
+- migration of banco when aplicável.
+
+# 8. Common errors
+
+| Error | Impact | Correction |
+| --- | --- | --- |
+| Deploy without certification | Risk funcional. | Rodar certification no pipeline. |
+| without release notes | without rastreabilidade. | Publicar release notes. |
+| without contract tests | Quebra integration. | Adicionar Tests of Contract. |
+| without rollback | Risk operacional. | Definir estratégia of rollback. |
+
+
+# 9. Acceptance criteria
+
+- [ ] Pipeline executa lint, type check and Tests.
+- [ ] Contract tests executam.
+- [ ] Security scan executa.
+- [ ] Imagem Docker gerada.
+- [ ] Artifacts publicados.
+- [ ] Smoke tests executados.
+- [ ] Certification executada.
+- [ ] Release notes publicadas.
+- [ ] Rollback definido.
+- [ ] Evidências arquivadas.