Deployment Strategy

Guia de Estrategia de Deployment

Version: 1.0.0 | Marzo 2026 Framework: AI Software Factory OS v7.7 Prerequisito: Git_Branch_Strategy_Guide.md (define branch → ambiente mapping)

---

1. Principio Central

El deployment es especifico de cada proyecto (stack, cloud, escala), pero el framework define patrones, ambientes minimos, safety checks y consideraciones AI que todo proyecto debe seguir. Esta guia NO reemplaza la documentacion de tu cloud provider — la complementa con las capas de governance y AI safety del ADLC.

---

2. Ambientes por Track

Track Solo

main ───────→ production (deploy manual o auto)
  ↑
feat/* ─────→ preview (opcional, efimero)

Ambiente	Proposito	Deploy trigger	Duracion
preview	Verificar PR antes de merge	PR abierto (auto)	Efimero (se destruye al cerrar PR)
production	Sistema live	Push a main (manual o auto)	Permanente

Minimo viable: 1 ambiente (produccion) con feature flags para safety.

Track Lean

main ───────→ production (manual, post-staging validation)
  ↑
develop ────→ staging (auto en merge a develop)
  ↑
feat/* ─────→ preview (auto en PR)

Ambiente	Proposito	Deploy trigger	Datos
preview	Preview de PR individual	PR abierto	Seed/mock
staging	Validacion pre-produccion	Merge a develop	Copia anonimizada de prod
production	Sistema live	Manual gate post-staging	Datos reales

Track Full

main + tag ─→ production (manual, post-release validation)
  ↑
release/* ──→ staging (auto al crear release branch)
  ↑
develop ────→ dev/integration (auto en merge a develop)
  ↑
feat/* ─────→ preview (auto en PR)

Ambiente	Proposito	Deploy trigger	Datos	SLO
preview	PR individual, efimero	PR abierto	Mock	Ninguno
dev	Integracion continua	Merge a develop	Seed	Smoke tests
staging	Pre-produccion, QA completo	Release branch	Anonimizado de prod	Subset de prod SLOs
production	Sistema live, clientes reales	Tag en main	Real	SLOs completos
canary	Subconjunto de produccion (5-10% trafico)	Flag-based	Real	Monitoreo intensivo

---

3. Branch → Ambiente Mapping

Branch                    Ambiente              Gate requerido
──────────────────────────────────────────────────────────────
feat/*, fab/*      ──→    preview (efimero)     Ninguno (auto)
develop            ──→    dev/staging           Gate E (TEVV)
release/*          ──→    staging               Gate F (Security)
main + tag         ──→    production            Human approval
hotfix/*           ──→    production            Emergency protocol

Regla de oro: Ningun commit llega a produccion sin pasar por al menos 1 ambiente previo (excepto hotfixes con emergency protocol documentado).

---

4. Pipeline de Deployment

4.1 Pre-deploy checks (obligatorios)

Estos checks corren en CI antes de CUALQUIER deploy:

# .github/workflows/deploy-staging.yml (ya incluido en project-template)
pre_deploy_checks:
  - name: "Tests"
    run: "pytest / npm test / go test"
    blocker: true  # Falla = no deploy

  - name: "Security scan"
    run: "python3 baseline/scripts/sast-sca-scanner.py"
    blocker: true  # Critical findings = no deploy

  - name: "Gate check"
    run: "python3 baseline/scripts/fab-gate-check.py --gate f"
    blocker: false  # Warning = deploy con alerta

  - name: "SBOM generation"
    run: "python3 baseline/scripts/sbom-generator.py --sign"
    blocker: false  # Informativo

  - name: "Cost guard"
    run: "python3 baseline/scripts/fab-cost-guard.py check"
    blocker: false  # Warning si > 80% budget

4.2 Build

Agnostico de stack — detecta automaticamente:

# El workflow deploy-staging.yml ya hace esto:
if [ -f package.json ]; then npm ci && npm run build
elif [ -f pyproject.toml ]; then python -m build
elif [ -f Dockerfile ]; then docker build -t app .
elif [ -f wrangler.toml ]; then npx wrangler build
fi

4.3 Deploy

Placeholder en el workflow — cada proyecto configura su deploy real:

# Ejemplo: Cloudflare Workers
- run: npx wrangler deploy --env ${{ env.ENVIRONMENT }}

# Ejemplo: AWS ECS
- run: aws ecs update-service --cluster $CLUSTER --service $SERVICE

# Ejemplo: Fly.io
- run: flyctl deploy --app $APP_NAME

# Ejemplo: Vercel
- run: vercel --prod --token $VERCEL_TOKEN

# Ejemplo: Railway
- run: railway up --service $SERVICE

4.4 Post-deploy checks

post_deploy_checks:
  - name: "Health check"
    run: "curl -f $DEPLOY_URL/health"
    timeout: 60s

  - name: "Smoke tests"
    run: "pytest tests/smoke/ --base-url $DEPLOY_URL"
    timeout: 120s

  - name: "AI health check"
    run: "curl -f $DEPLOY_URL/api/ai/health"  # Verifica LLM connectivity
    timeout: 30s

---

5. Deployment Safety para AI

Los sistemas AI tienen riesgos de deployment que los sistemas tradicionales no tienen.

5.1 Canary Deployments para Modelos AI

Cuando cambias el modelo (ej: Sonnet 4 → Sonnet 4.5) o modificas prompts:

100% trafico → Modelo actual (v1)

Canary deploy:
  5% trafico  → Modelo nuevo (v2)     ← Monitorear 24h
  95% trafico → Modelo actual (v1)

Si metricas OK (hallucination < 5%, latency < SLO):
  50% → v2, 50% → v1                   ← Monitorear 4h

Si sigue OK:
  100% → v2                             ← Rollback instant si regresion

Metricas a monitorear durante canary AI:

• Hallucination rate (vs baseline)
• Latency p95 (vs SLO)
• User feedback score (si disponible)
• Token cost per request (vs budget)
• Error rate (5xx from AI calls)

5.2 Prompt Versioning

Los prompts son artefactos versionados, no strings inline:

project/
  prompts/
    v1/
      classifier.txt        ← Version 1 del prompt de clasificacion
      responder.txt          ← Version 1 del prompt de respuesta
    v2/
      classifier.txt        ← Version 2 (mejorado post-eval)
      responder.txt

  prompt-config.yaml:
    classifier:
      active_version: "v2"
      rollback_version: "v1"
      canary_percent: 10     # 10% usa v2, 90% usa v1
    responder:
      active_version: "v1"
      rollback_version: "v1"
      canary_percent: 0

Rollback de prompt: cambiar active_version sin redeploy de codigo.

5.3 RAG Corpus Deployment

El knowledge base (RAG) tiene su propio ciclo de deployment:

Codigo (CI/CD normal)          RAG Corpus (pipeline separado)
─────────────────────          ──────────────────────────────
feat/* → build → deploy        docs updated → re-chunk → re-embed → re-index
                                      ↓
                               Verificar: MRR@5 >= threshold
                                      ↓
                               Swap index (blue-green)

Reglas:

• Nunca re-indexar en produccion durante peak hours
• Blue-green index swap: crear nuevo indice, verificar, swap alias
• Rollback: revertir alias al indice anterior
• Freshness SLO: corpus no mas de 24h desactualizado

5.4 Feature Flags para AI

Habilitar/deshabilitar features AI sin redeploy:

# feature_flags.yaml (o servicio externo: LaunchDarkly, Unleash, Flipt)
flags:
  ai_classifier:
    enabled: true
    rollout_percent: 100
    fallback: "rule_based_classifier"

  ai_responder:
    enabled: true
    rollout_percent: 50         # Solo 50% de usuarios ven respuestas AI
    fallback: "template_response"

  ai_sentiment:
    enabled: false              # Deshabilitado temporalmente
    fallback: "neutral"

Patron: Cada feature AI tiene un fallback deterministico. Si el flag se desactiva, el sistema funciona sin AI (degraded pero funcional).

---

6. Rollback Strategy

6.1 Rollback de codigo

# Revertir ultimo deploy (volver al tag anterior)
git checkout v7.6.0   # Tag anterior
# Re-deploy desde ese tag

6.2 Rollback de modelo AI

# Cambiar en runtime (sin redeploy)
ai_config:
  classifier:
    model: "claude-sonnet-4"      # Revertir de 4.5 a 4
    prompt_version: "v1"           # Revertir prompt

6.3 Rollback de RAG corpus

# Swap alias del indice vectorial al anterior
# Pinecone: switch index pointer
# pgvector: ALTER VIEW to previous table
# Elasticsearch: alias swap

6.4 Emergency Protocol

Cuando algo falla en produccion con componentes AI:

1. DETECTAR    → Alerta (latency, error rate, hallucination spike)
2. EVALUAR     → Es el modelo? El prompt? El corpus? El codigo?
3. MITIGAR     →
   - Si modelo:  Feature flag OFF → fallback deterministico
   - Si prompt:  Revertir prompt_version
   - Si corpus:  Swap index alias
   - Si codigo:  Redeploy tag anterior
4. NOTIFICAR   → Incident channel + stakeholders
5. INVESTIGAR  → Root cause analysis post-mitigacion
6. DOCUMENTAR  → Runbook + DISCOVERIES.md

---

7. Ambientes y Datos

Ambiente	Datos	PII	Costo AI
preview	Mock/seed	Nunca	Modelo barato (Haiku) o mock
dev	Seed sintetico	Nunca	Modelo barato (Haiku)
staging	Copia anonimizada	Anonimizada	Modelo real (Sonnet)
production	Real	Protegida (encryption)	Modelo real (Sonnet/Opus)

Reglas de datos:

• preview/dev: NUNCA datos reales. Usar factories/fixtures.
• staging: Copia de produccion con PII anonimizada (regex + NER).
• production: Datos reales con proteccion segun data_classification.yaml.
• Los modelos AI en preview/dev pueden ser mocks o modelos baratos para reducir costos.

---

8. CI/CD Workflows Incluidos

El project-template/.github/workflows/ incluye:

Workflow	Trigger	Funcion
test.yml	PR + push	Tests unitarios e integracion
gates.yml	PR a main	Gate checks (compliance, artifacts)
security-scan.yml	PR + push	SAST/SCA + secret scanning
sbom.yml	Push a main	SBOM + AIBOM generation
eval.yml	Push a main	AI eval suite (golden dataset)
deploy-staging.yml	Push a main	Build + deploy a staging
update-baseline.yml	Schedule (daily)	Sync baseline submodule

Para produccion: crear deploy-production.yml copiando deploy-staging.yml y agregando:

• Trigger: manual (workflow_dispatch) o tag push
• Approval gate: environment: production con reviewers
• Canary step (opcional)
• Notification post-deploy

---

9. Checklist Pre-Production

Antes del primer deploy a produccion, verificar:

• Tests: Suite completa pasa (unit + integration + e2e)
• Security: SAST/SCA limpio (0 critical, 0 high)
• Gates: Gate F (Security) aprobado
• SBOM: Generado y firmado (--sign)
• AIBOM: Generado con todos los componentes AI registrados
• SLOs: Definidos en operating_baseline.yaml
• Runbooks: Al menos 3 runbooks criticos documentados
• Monitoring: Dashboards y alertas configurados
• Rollback: Procedimiento documentado y probado
• Feature flags: Todos los features AI tienen fallback deterministico
• Data classification: Todos los campos PII clasificados
• Compliance: Matriz completada segun frameworks aplicables
• Cost guard: Budget configurado en .fab-config.yaml
• Kill switch: Probado con fab-kill-switch-drill.sh

---

Companion del AI-First Engineering Framework v7.7 See: Git_Branch_Strategy_Guide.md, CORE_F09_Runbooks_SLOs_Incident_Response.md, deploy-staging.yml