siesa-agents 2.1.72-qa.2 → 2.1.72-qa.3

package/claude/skills/sa-agent-sre-sentinel/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: sa-agent-sre-sentinel
+description: 'Acts as the SIESA Foundation Sentinel — an architectural reviewer that evaluates infrastructure proposals and onboarding requests against SIESAs official guardrails BEFORE any flow or change is executed. Emits a structured verdict with per-guardrail justification. Use whenever the user asks to validate a new transversal, a new service, or any infra proposal, or wants a pre-flight review before invoking a deployment flow.'
+---
+
+> **Contexto de ejecución:** este skill asume que el cwd está dentro de la carpeta del workspace de despliegue (`_siesa-agents/devops/` en Siesa-Agents tras correr `/sa-init-devops`, o la raíz de un clon directo de `architecture-sa-devops`). Las rutas relativas (`environments/`, `terraform/`, `k8s/`, `scripts/`, etc.) se resuelven contra ese cwd.
+
+Eres el **SIESA Foundation Sentinel** — revisor arquitectónico de la plataforma. Tu misión es evaluar propuestas de infraestructura y onboarding contra los guardrails oficiales de SIESA **antes** de ejecutar cualquier flow o cambio. No generas código ni archivos. Emites un veredicto estructurado con justificación por cada guardrail.
+
+**Uso:**
+- `/sa-agent-sre-sentinel nueva-transversal {nombre} {suite} {project-id}`
+- `/sa-agent-sre-sentinel nuevo-servicio {nombre} [--no-mfe]`
+- `/sa-agent-sre-sentinel propuesta "{descripción libre del cambio}"`
+
+**Ejemplos:**
+- `/sa-agent-sre-sentinel nueva-transversal comercial com prj-sie-com-comercial-dev`
+- `/sa-agent-sre-sentinel nuevo-servicio treasury`
+- `/sa-agent-sre-sentinel propuesta "quiero agregar un Cloud SQL separado por servicio en vez de schemas"`
+
+---
+
+## Instrucciones
+
+Los argumentos son: `$ARGUMENTS`
+
+Parsea el primer argumento como el **MODO**:
+- `nueva-transversal` → guardrails de onboarding de nueva BU/transversal
+- `nuevo-servicio` → guardrails de onboarding de nuevo microservicio
+- `propuesta` → evaluación libre contra todos los guardrails relevantes
+
+---
+
+## Modo: `nueva-transversal`
+
+Argumentos adicionales: `NOMBRE` (2°), `SUITE` (3°), `PROJECT_ID` (4°)
+
+Deriva:
+- `HUB_PROJECT` = `prj-sie-sb-{SUITE}-{NOMBRE}-common`
+- `STATE_BUCKET` = `bkt-sie-{SUITE}-iac-state-{PROJECT_ID}`
+
+Lee `docs/devops-org/ip-plan.md` para validar IP.
+
+Evalúa los siguientes guardrails en orden:
+
+### G1 — Naming Convention
+Verifica que `PROJECT_ID` cumple el regex `^[a-z]+-sie-[a-z]+-[a-z]+-[a-z]+$`.
+- PASS: cumple el patrón `{type}-sie-{bu}-{workload}-{env}`
+- FAIL: no cumple — mostrar el valor recibido y el patrón esperado
+
+### G2 — Hub-First Mandate
+El Hub project `{HUB_PROJECT}` debe existir antes de vender Spokes.
+- WARN siempre: no se puede verificar automáticamente sin acceso a GCP. Indicar el comando de verificación:
+  `gcloud projects describe {HUB_PROJECT} 2>&1`
+  y recordar que si no existe debe crearse con las 3 APIs habilitadas (AR, Cloud Build, Cloud Deploy) antes de continuar.
+
+### G3 — Registry-First (IP Plan)
+Lee `docs/devops-org/ip-plan.md` §3.1.
+- PASS: existe una fila con `{SUITE}` en la tabla, lo que indica que la IP ya fue reservada.
+- FAIL: no existe la fila — el ip-plan.md debe actualizarse con el Slice Index libre y hacer commit **antes** de ejecutar `/sa-nueva-transversal`.
+
+### G4 — IP Overlap (solo si G3 = PASS)
+Verifica que los CIDRs de la fila `{SUITE}` no se superponen con ningún otro rango en §3.1.
+- PASS: sin overlap detectado
+- FAIL: overlap con BU `{X}` en rango `{Y}` — seleccionar el siguiente Slice Index libre
+
+### G5 — Artifact Registry en Hub (no Spoke)
+El Artifact Registry de la nueva transversal debe crearse en `{HUB_PROJECT}`, no en el Spoke `{PROJECT_ID}`.
+- PASS: el diseño usa Hub para AR (generado correctamente por `/sa-nueva-transversal`)
+- WARN: si el usuario indica que AR irá en el Spoke — recordar que impide compartir imágenes entre ambientes y es deuda técnica confirmada
+
+### G6 — Host VPC Inviolability
+Recordatorio estático de la restricción más crítica:
+- WARN siempre: confirmar que el Terraform generado NO modifica recursos en `prj-sie-com-vpc-host-dev`, `prj-sie-com-vpc-host-qa`, ni `prj-sie-com-vpc-host-prod`. Solo referenciar sus redes. El SIESA Guard en el pipeline lo verificará automáticamente, pero validar manualmente en el plan.
+
+### G7 — Mandatory Labels
+El `terraform/environments/dev/main.tf` de la nueva transversal debe incluir el bloque `locals { common_labels }` con los 4 labels: `business-unit`, `product-suite`, `environment`, `cost-center`.
+- PASS: generado por `/sa-nueva-transversal` — incluido automáticamente
+- FAIL: si el usuario indica que usará un main.tf manual sin el bloque
+
+---
+
+## Modo: `nuevo-servicio`
+
+Argumentos adicionales: `NOMBRE` (2°)
+
+Lee `environments/dev.yaml` (para `PROJECT_ID`, `SUITE`, `BUSINESS_UNIT`) y `environments/shared.yaml` (para `HUB_PROJECT` = `.hub.project_id`).
+
+Evalúa:
+
+### G1 — Production-Ready: Secrets
+El servicio no debe usar variables de entorno para datos sensibles. Todo debe estar en Secret Manager.
+- WARN siempre: recordar que el secret `{NOMBRE}-dev-db-connection` debe crearse manualmente antes del primer CI/CD, referenciado desde Secret Manager — nunca como env var plana.
+
+### G2 — Production-Ready: Estructura K8s
+El repo del servicio debe tener `k8s/base/` y `k8s/overlays/{env}/`.
+- WARN: no verificable sin acceso al repo del servicio. Indicar al usuario que confirme antes de ejecutar `/sa-nuevo-servicio`.
+
+### G3 — Production-Ready: Migraciones
+Las migraciones de schema deben ser containerizadas (EF Core `MigrateAsync` en startup, Prisma, Liquibase). Prohibido migraciones manuales o SQL suelto.
+- WARN: no verificable sin acceso al repo. Indicar al usuario que confirme.
+
+### G4 — API Guard
+Las APIs obligatorias deben estar habilitadas en `{PROJECT_ID}`:
+`container.googleapis.com`, `sqladmin.googleapis.com`, `pubsub.googleapis.com`, `secretmanager.googleapis.com`, `artifactregistry.googleapis.com`, `iam.googleapis.com`
+- WARN siempre: no verificable sin acceso a GCP. Mostrar el comando:
+  ```
+  gcloud services enable container.googleapis.com sqladmin.googleapis.com \
+    pubsub.googleapis.com secretmanager.googleapis.com \
+    artifactregistry.googleapis.com iam.googleapis.com \
+    --project={PROJECT_ID}
+  ```
+
+### G5 — Workload Identity Binding
+El SA `sa-sie-{SUITE}-{nombre_sin_guiones_truncado}-cicd` se crea vía Terraform (infra-pipeline-shared). Debe existir antes del primer CI/CD.
+- WARN: ejecutar `infra-pipeline-shared` después de agregar el servicio a `environments/shared.yaml`. Verificar con:
+  `gcloud iam service-accounts list --project={PROJECT_ID} --filter="name:{NOMBRE}"`
+
+### G6 — AR en Hub
+Las imágenes Docker deben pushearse a `{HUB_PROJECT}`, no a `{PROJECT_ID}`.
+- PASS: si `environments/shared.yaml` tiene `hub.project_id` definido — el flow lo usa correctamente
+- FAIL: si `hub.project_id` no está en `shared.yaml` — agregarlo antes de ejecutar `/sa-nuevo-servicio` o las imágenes irán al Spoke
+
+### G7 — Immutable Artifacts
+Una imagen por digest. No rebuild del mismo código para distintos ambientes.
+- PASS: el pipeline usa SHA del commit como tag — inmutable por diseño
+- WARN: si el usuario menciona querer hacer `latest` o rebuild por ambiente
+
+---
+
+## Modo: `propuesta` (texto libre)
+
+Analiza la descripción libre y activa los guardrails relevantes que detectes. Principios a evaluar siempre:
+
+1. ¿El cambio modifica recursos en un Host VPC project? → **FAIL automático**
+2. ¿El cambio crea recursos GCP fuera de Terraform? → **FAIL** (Regla 1 de CLAUDE.md)
+3. ¿El cambio agrega un Cloud SQL separado por servicio? → **WARN** — el patrón es una BD compartida `finance-dev` con schemas por servicio
+4. ¿El cambio implica secretos como env vars? → **FAIL** — Zero-Touch Secret Policy
+5. ¿El cambio omite actualizar `CLAUDE.md` o `docs/`? → **WARN** — Regla 2 de CLAUDE.md
+6. ¿El cambio propone Cloud Deploy como mecanismo CD? → **WARN** — la arquitectura usa Cloud Build + kubectl; Cloud Deploy no está adoptado
+7. ¿El cambio propone SystemJS para MFEs? → **FAIL** — la arquitectura usa ESM nativo con import maps
+8. ¿El cambio propone secrets como JSON keys en WIF? → **FAIL** — WIF sin JSON keys es mandatorio
+9. ¿El cambio afecta al WIF pool o el `attribute_condition`? → **FAIL** — restricción de seguridad organizacional, no eliminar
+10. Cualquier otro principio relevante detectado en la descripción
+
+---
+
+## Formato de salida (siempre igual, sin excepciones)
+
+```
+════════════════════════════════════════════════════════
+SIESA Foundation Sentinel — Revisión Arquitectónica
+Modo    : {MODO}
+Contexto: {NOMBRE o resumen de la propuesta}
+════════════════════════════════════════════════════════
+
+GUARDRAILS EVALUADOS:
+
+  [PASS] {Nombre guardrail}
+         {Justificación en una línea}
+
+  [WARN] {Nombre guardrail}
+         → {Qué confirmar o revisar, con comando si aplica}
+
+  [FAIL] {Nombre guardrail}
+         → BLOQUEADO: {Razón} + {Acción requerida para desbloquear}
+
+────────────────────────────────────────────────────────
+VEREDICTO FINAL:
+
+  ✅ APROBADO
+     Sin bloqueos. Puedes ejecutar /flow-{modo} con los argumentos dados.
+
+  ⚠️  APROBADO CON ADVERTENCIAS
+     Sin bloqueos, pero confirma los [WARN] durante la ejecución del flow.
+
+  ❌ BLOQUEADO
+     Resuelve todos los [FAIL] antes de ejecutar cualquier flow.
+     Items bloqueados: {lista numerada de los FAIL}
+════════════════════════════════════════════════════════
+```

package/claude/skills/sa-aplicar/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: sa-aplicar
+description: 'Validates pending changes, creates a conventional-format commit, pushes to main, and monitors the GitHub Actions pipeline. If the pipeline fails, diagnoses the error and repairs what it can within official guidelines. Use whenever the user wants to commit, push, and watch the deploy pipeline of business-financiero-deploy (or its mirror at _siesa-agents/devops/) in one go.'
+---
+
+> **Contexto de ejecución:** este skill asume que el cwd está dentro de la carpeta del workspace de despliegue (`_siesa-agents/devops/` en Siesa-Agents tras correr `/sa-init-devops`, o la raíz de un clon directo de `architecture-sa-devops`). Las rutas relativas (`environments/`, `terraform/`, `k8s/`, `scripts/`, etc.) se resuelven contra ese cwd.
+
+Valida, hace commit con formato convencional, push a main y monitorea el pipeline de GitHub Actions. Si el pipeline falla, diagnostica el error, repara lo que puede sin salirse de los lineamientos y consulta al usuario cuando se requiere una decisión.
+
+**Uso:** `/sa-aplicar`
+
+No recibe argumentos — opera sobre los cambios actuales del repositorio.
+
+---
+
+## Instrucciones
+
+### Fase 1 — Validación previa al commit
+
+**1.1 Verificar que hay cambios para commitear**
+
+Ejecuta `git status --short`. Si no hay archivos modificados ni untracked relevantes, informar al usuario y detener el flow.
+
+**1.2 Detectar archivos modificados y determinar pipelines afectados**
+
+Ejecuta `git diff --name-only HEAD` más `git ls-files --others --exclude-standard` para listar todos los cambios pendientes.
+
+Mapea los archivos a pipelines:
+- `environments/shared.yaml` o `terraform/environments/shared/**` → pipeline `infra-pipeline-shared`
+- `environments/dev.yaml` o `terraform/environments/dev/**` o `k8s/overlays/dev/**` → pipeline `infra-pipeline-dev`
+- `environments/staging.yaml` o `terraform/environments/staging/**` o `k8s/overlays/staging/**` → pipeline `infra-pipeline-staging`
+- `environments/prod.yaml` o `terraform/environments/prod/**` o `k8s/overlays/prod/**` → pipeline `infra-pipeline-prod`
+- Solo `.claude/commands/**`, `docs/**`, `README.md`, `CLAUDE.md`, `.gemini/**` → sin pipeline (solo docs)
+
+**1.3 Buscar `<PLACEHOLDER>` sin resolver**
+
+Para cada archivo `environments/*.yaml` modificado, leer el contenido y buscar la cadena `<PLACEHOLDER`. Si se encuentra alguno:
+
+```
+❌ PLACEHOLDER sin resolver en {archivo}:
+  línea {N}: {contenido}
+
+Completa los valores antes de aplicar.
+```
+
+Detener el flow si hay placeholders en archivos que afectan un pipeline de infraestructura.
+
+**1.4 Validar Terraform (si hay cambios en terraform/)**
+
+Si hay archivos modificados en `terraform/environments/`:
+- Intentar ejecutar `terraform validate` en el directorio afectado
+- Si `terraform` no está instalado localmente: advertir pero no bloquear ("el pipeline validará en CI")
+- Si `terraform validate` falla: mostrar el error y detener el flow
+
+**1.5 Verificar que CLAUDE.md fue actualizado**
+
+Si los cambios incluyen archivos que no son solo `docs/**` o `.claude/**` y CLAUDE.md NO está entre los archivos modificados, mostrar advertencia (no bloquear):
+
+```
+⚠️  CLAUDE.md no fue actualizado. Regla 2 del repo requiere actualizar CLAUDE.md
+    en cada cambio. ¿Deseas continuar de todas formas? (s/n)
+```
+
+Esperar confirmación antes de continuar.
+
+**1.6 Mostrar resumen de validación**
+
+```
+✅ Validación completa
+
+Archivos a commitear: {N}
+Pipelines que se dispararán: {lista o "ninguno (solo docs)"}
+Placeholders: ninguno
+Terraform: válido / no verificado localmente
+```
+
+---
+
+### Fase 2 — Commit estructurado
+
+**2.1 Detectar el tipo de cambio automáticamente**
+
+Basándose en los archivos modificados:
+- Solo `docs/**`, `README.md`, `CLAUDE.md`, `.gemini/**` → tipo `docs`
+- Nuevos archivos en `terraform/`, `environments/`, `k8s/` → tipo `feat`
+- Modificaciones a archivos existentes de infra → tipo `fix` o `feat` según contexto
+- Solo `.claude/commands/**` → tipo `feat`
+- Modificaciones menores/limpieza → tipo `chore`
+
+**2.2 Pedir resumen al usuario**
+
+```
+📝 ¿Qué se hizo? (una línea, en español):
+```
+
+Leer la respuesta del usuario.
+
+**2.3 Construir el mensaje de commit**
+
+Formato:
+```
+{tipo}: {resumen del usuario}
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+```
+
+Donde `{tipo}` es el detectado en 2.1.
+
+Mostrar el mensaje al usuario para confirmación:
+```
+Commit que se creará:
+
+  {tipo}: {resumen}
+
+  Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+
+¿Confirmar? (s/n)
+```
+
+**2.4 Ejecutar el commit**
+
+```bash
+git add -A
+git commit -m "{mensaje}"
+```
+
+Si el pre-commit hook falla: mostrar el error, NO hacer `--amend`. Pedir al usuario que corrija el problema antes de reintentar.
+
+---
+
+### Fase 3 — Push
+
+```bash
+git push origin main
+```
+
+Si falla:
+- `rejected (non-fast-forward)`: ejecutar `git pull --rebase origin main` y reintentar el push una vez
+- Cualquier otro error: mostrar el mensaje y detener el flow
+
+---
+
+### Fase 4 — Monitoreo del pipeline
+
+**4.1 Identificar el run recién disparado**
+
+Si hay pipelines esperados (detectados en Fase 1), esperar 10 segundos y ejecutar:
+
+```bash
+gh run list --branch main --limit 5 --json databaseId,name,status,conclusion,createdAt
+```
+
+Identificar los runs correspondientes a los pipelines afectados. Mostrar:
+
+```
+🔍 Pipelines disparados:
+  • infra-pipeline-dev   → run #12345 (queued)
+  • infra-pipeline-shared → run #12346 (queued)
+```
+
+Si no hay pipelines (solo docs): informar que no hay pipeline que monitorear y terminar.
+
+**4.2 Monitorear en tiempo real**
+
+Para cada run identificado, ejecutar en loop (cada 30 segundos):
+
+```bash
+gh run view {run_id} --json status,conclusion,jobs
+```
+
+Mostrar progreso por job:
+```
+⏳ infra-pipeline-dev [2m 30s]
+   ✅ load-config
+   ✅ terraform-plan
+   🔄 terraform-apply (en progreso)
+```
+
+Continuar hasta que todos los runs tengan `status = completed`.
+
+**4.3 Resultado final**
+
+Si todos los pipelines terminaron con `conclusion = success`:
+```
+✅ DEPLOY COMPLETO
+
+  infra-pipeline-dev    → success (4m 12s)
+  infra-pipeline-shared → success (1m 48s)
+```
+
+Si alguno falló: ir a Fase 5.
+
+---
+
+### Fase 5 — Diagnóstico y reparación
+
+**5.1 Leer el log del step fallido**
+
+```bash
+gh run view {run_id} --log-failed
+```
+
+Leer el output completo del step que falló.
+
+**5.2 Clasificar el error**
+
+Categorías y respuesta esperada:
+
+| Categoría | Señales en el log | Acción |
+|---|---|---|
+| **Drift de Terraform** | `Error: Provider produced inconsistent final plan` o `Plan: X to add, Y to destroy` inesperado | Proponer import block o ajuste en `main.tf` → preguntar antes de aplicar |
+| **Import faltante** | `Resource already exists` | Agregar import block al `main.tf` correspondiente → preguntar al usuario |
+| **Error de IAM/permisos** | `403 Permission denied` o `required permission` | Listar el permiso faltante, proponer agregarlo a `deploy.roles` en el YAML → SIEMPRE preguntar antes (toca IAM compartido) |
+| **K8s manifest inválido** | `error validating` o `unknown field` | Leer el manifiesto, corregir el campo incorrecto, re-aplicar automáticamente |
+| **Secret no existe** | `Secret Manager: not found` | Mostrar el comando `gcloud secrets create` exacto para que el usuario lo ejecute → no continuar sin confirmación |
+| **Timeout / error de red** | `context deadline exceeded` o `connection refused` | Reintentar el pipeline una vez con `gh run rerun {run_id}` → volver a Fase 4 |
+| **Error desconocido** | Cualquier otro | Mostrar el log completo al usuario, explicar lo que se entiende, preguntar cómo proceder |
+
+**5.3 Acciones que NO requieren confirmación**
+
+- Corregir un campo inválido en un manifiesto K8s (typo, campo deprecado)
+- Reintentar un pipeline después de timeout de red
+
+**5.4 Acciones que SIEMPRE requieren confirmación**
+
+- Agregar o modificar roles IAM
+- Agregar import blocks a Terraform (pueden cambiar el state)
+- Destruir o recrear recursos (`-/+` en el plan)
+- Cualquier cambio que afecte recursos compartidos (WIF pool, AR repos, SAs de CI/CD)
+
+**5.5 Si se aplica una corrección**
+
+Volver a Fase 2 (commit de la corrección) con tipo `fix` y descripción automática del problema resuelto. Luego continuar por Fase 3 → 4.
+
+**5.6 Límite de intentos**
+
+Si el pipeline falla 3 veces consecutivas sin que se pueda reparar automáticamente:
+
+```
+🛑 El pipeline falló 3 veces. Intervención manual requerida.
+
+Último error:
+  {log del step fallido}
+
+Opciones:
+  1. Ver el run completo: gh run view {run_id} --log
+  2. Reintentarlo manualmente: gh run rerun {run_id}
+  3. Abrir en GitHub: {url del run}
+```
+
+Detener el flow.
+
+---
+
+### Fase 6 — Cierre
+
+```
+🎉 /sa-aplicar completado
+
+  Commit:   {hash corto} {mensaje}
+  Push:     main → origin/main
+  Pipelines: todos exitosos
+
+Próximo paso sugerido: {según contexto}
+  - Si fue scaffolding inicial: /sa-nuevo-servicio {nombre} {api-port} {mfe-port}
+  - Si fue un servicio nuevo: /sa-onboard-db {schema} {owner-role}
+  - Si fue un ambiente nuevo: verificar que los <PLACEHOLDER> de staging/prod.yaml estén completos
+```