Merge branch 'fix/lab-agent-docs-arquitectura' into main

Documentación de gobernanza y arquitectura del agente lab-agent:
lista blanca aprobada, diseño de seguridad (--allowedTools "" en vez
de un Bash tool con patrón, por la vulnerabilidad de coincidencia por
prefijo encontrada en vivo), autenticación por login de suscripción, y
evidencia completa de la prueba end-to-end del 2026-08-26.

workloads/docs-portal/docs/arquitectura/agente-monitoreo.md

@@ -0,0 +1,191 @@
+# Agente de diagnóstico/corrección (lab-agent)
+
+Wrapper headless (`scripts/lab-agent/lab-agent.sh`) que corre `claude -p`
+periódicamente para diagnosticar el estado del lab y, solo para un
+conjunto explícito y aprobado de recursos, ejecutar una acción
+correctiva de bajo riesgo. Este documento es tanto referencia técnica
+como decisión de gobernanza — la lista blanca de abajo es lo que
+autoriza al agente a actuar sin intervención humana, y debe poder
+auditarse.
+
+Estado: **script y prueba end-to-end validados en vivo (2026-08-26)**.
+El timer de systemd (automatización continua) **todavía no está
+activo** — pendiente de decisión explícita para habilitarlo.
+
+## Lista blanca de acciones correctivas automáticas
+
+Aprobada 2026-08-25, antes de escribir una sola línea de código.
+
+### 1. `kubectl rollout restart deployment/<nombre>`
+
+| Condición | Valor |
+|---|---|
+| Trigger | Deployment con `readyReplicas < replicas` o condición `Available=False` durante **≥10 minutos consecutivos** |
+| Namespace elegible | `ecommerce` (todos los deployments detectados ahí en el momento de la corrida) |
+| Excepción | `medusa-deploy` — el deployment real de "commerce-backend" en la terminología de `CLAUDE.md` (confirmado en vivo 2026-08-25: no existe un deployment llamado literalmente `commerce-backend`) — solo elegible si además la hora **local** del host está entre **00:00–06:00** |
+| Namespaces excluidos siempre | `argocd`, `kube-system`, cualquier otro namespace de plataforma |
+
+### 2. `docker restart <contenedor>`
+
+| Condición | Valor |
+|---|---|
+| Contenedores elegibles | **Únicamente `gitea-runner`** |
+| Trigger | Contenedor no está en estado `running` durante ≥10 min, **o** la API de Gitea Actions reporta un run en estado `running` atascado por más de 10 min sin terminar (señal del incidente de runner zombie del 2026-08-16) |
+| Degradación segura | Si no hay `GITEA_TOKEN_FILE` configurado o la API falla, esa señal se omite — nunca dispara una acción sobre una lectura no verificada, solo queda la señal de "contenedor caído" |
+| Excluidos siempre | `gitea`, `nginxproxymanager`, `cloudflared` |
+
+### 3. Fuera de alcance automático — SIEMPRE (solo diagnóstico + notificación)
+
+- Borrar cualquier recurso, escalar réplicas, tocar `ConfigMap`/`Secret`/configuración.
+- Reiniciar `gitea`, `nginxproxymanager`, `cloudflared`.
+- Cualquier acción sobre `medusa-deploy` fuera de la ventana 00:00–06:00.
+- Cualquier namespace/deployment no detectado explícitamente en `ecommerce`.
+
+### 4. Límites obligatorios
+
+- **Rate limit:** máx. 1 acción correctiva por recurso cada 30 min.
+- **Sin reintento silencioso:** tras un primer intento cuyo problema no
+  se resuelve, el recurso queda `blocked` — solo notificación, hasta
+  que un humano limpie la entrada en `state.json` o el recurso se
+  recupere solo.
+- **Logging completo:** cada decisión (actúe o no) se registra en
+  `actions.jsonl` con timestamp, recurso, decisión, resultado y motivo.
+- **Notificación siempre:** toda acción correctiva o anomalía dispara
+  notificación — nunca es silenciosa.
+
+## Diseño de seguridad: por qué Claude nunca ejecuta comandos
+
+`claude -p` se invoca con `--allowedTools ""` (cero herramientas) y
+`--json-schema`, así que el modelo **nunca** ejecuta un comando —
+solo devuelve una decisión estructurada
+(`{"actions":[{"resource","decision","reason"}], "summary"}`). El
+script bash es el único que ejecuta `kubectl`/`docker`, y solo después
+de revalidar la decisión contra su propio cálculo de elegibilidad —
+nunca confía en el JSON de Claude por sí solo.
+
+Se descartó dar a Claude un `Bash` tool con un patrón tipo
+`Bash(kubectl rollout restart deployment/medusa-deploy -n ecommerce)`
+porque se comprobó en vivo (2026-08-25) que `--allowedTools` hace
+**coincidencia por prefijo, no exacta**: un patrón `Bash(echo pintest)`
+también permite ejecutar `echo pintest && echo INJECTED` o
+`echo pintest; rm -rf /`. Para un comando root-capaz eso no es un
+límite seguro. Con `--allowedTools ""`, el peor caso posible es que
+Claude proponga una decisión incorrecta en el JSON — y el wrapper la
+rechaza si el recurso no está en su propia lista de elegibles.
+
+El prompt también advierte contra prompt injection: los datos de
+diagnóstico (estado de pods, logs) podrían contener texto arbitrario
+si algo en el cluster está comprometido, e instruye a Claude a ignorar
+cualquier instrucción incrustada ahí.
+
+## Autenticación: login de suscripción, no API key
+
+`ANTHROPIC_API_KEY_FILE` queda vacío por defecto — `claude -p` usa el
+login de suscripción ya activo del usuario que corre el script
+(`~/.claude/.credentials.json`), el mismo que usa una sesión
+interactiva normal. Esta decisión se tomó en vivo (2026-08-26) al
+confirmar que no había una API key real disponible; el diseño original
+pedía un secreto root-only para la API key, pero se simplificó porque:
+
+1. No hacía falta una API key aparte — la suscripción ya cubre esto.
+2. Elimina la necesidad de crear secretos root-only vía `sudo` (que
+   además está bloqueado para una sesión de Claude Code interactiva
+   por diseño — ver `feedback_scoped_root_access_pattern` en memoria
+   del proyecto).
+
+**Consecuencia directa:** el servicio systemd (cuando se active) debe
+correr como usuario `devops`, no como `root` — root no tiene acceso a
+ese login. `CLAUDE_BIN`/`KUBECTL_BIN` apuntan por ruta absoluta a
+`/DATA/AppData/home-devops/.local/bin/` porque ese directorio no está
+en el `PATH` de root ni de systemd (confirmado en vivo: `sudo which
+claude` no lo encuentra).
+
+El único secreto que queda es `GITEA_TOKEN_FILE` (token de Gitea
+Actions, opcional, scope lectura), dueño `devops`, `600` — sin sudo.
+
+## Prueba end-to-end (2026-08-26)
+
+Ejecutada contra el cluster real, rama `fix/lab-agent-diagnostico-headless`.
+Umbral bajado a 2 minutos solo para esta prueba (`UNHEALTHY_THRESHOLD_MIN`,
+valor real en producción: 10). Canario desechable: `deployment/test-agent-canary`
+en `ecommerce`, imagen `busybox:stable` con `command: ["sh","-c","exit 1"]`
+— garantiza `CrashLoopBackOff` predecible, sin relación con
+`catalog-api-deploy`/`frontend-deploy`/`medusa-deploy`.
+
+### Bugs encontrados y corregidos durante la prueba
+
+1. **Subshell perdía el resultado de la acción.** `execute_corrective_action`
+   se invocaba como `result="$(execute_corrective_action "$resource")"` —
+   al correr en un subshell, las variables `LAST_ACTION_CMD`/`STDOUT`/`STDERR`
+   nunca volvían al script principal → crash con `unbound variable`.
+   Corregido: la función ahora devuelve éxito/fallo por exit status, invocada
+   directamente (sin `$(...)`) para que sus variables globales persistan.
+2. **DRY_RUN contaminaba el estado real.** El wrapper marcaba `blocked=true`
+   en `state.json` incluso en modo simulación, lo que habría bloqueado
+   incorrectamente una corrida real posterior sobre el mismo recurso.
+   Corregido: la actualización de `state.json` (bloqueo/rate-limit) solo
+   ocurre fuera de `DRY_RUN`.
+3. **`claude`/`kubectl` fuera del PATH de root/systemd** — ver sección de
+   autenticación arriba. Corregido con `CLAUDE_BIN`/`KUBECTL_BIN` por ruta
+   absoluta.
+
+### Evidencia por paso
+
+**DRY_RUN (elegibilidad + decisión, sin tocar el cluster):**
+
+- 1ª corrida (recién detectado): `elegibilidad=not_eligible:bajo_umbral(0m<2m)`
+  → Claude devolvió `notify_only` para los 5 recursos.
+- 2ª corrida (&gt;2 min después): `elegibilidad=eligible` para
+  `test-agent-canary` → Claude devolvió `decision:"restart"` solo para
+  ese recurso, `notify_only` para los otros 4 (sanos).
+- Log: `ACCIÓN EJECUTADA: kubectl -n ecommerce rollout restart
+  deployment/test-agent-canary -> OK`, pero verificado en el cluster real
+  que **no hubo restart** (sin anotación `restartedAt`, mismo pod, misma
+  edad). `actions.jsonl` registra `"dry_run": true`.
+
+**Ejecución real (`--live`):**
+
+- Misma decisión de Claude (`restart` para el canario, `notify_only` para
+  el resto).
+- Verificado en el cluster: nueva anotación
+  `kubectl.kubernetes.io/restartedAt` en el deployment, evento
+  `ScalingReplicaSet` de un ReplicaSet **nuevo**, pod nuevo en otro nodo.
+- `actions.jsonl`: `"result": "success", "dry_run": false`.
+- `state.json`: `last_action_at` seteado, `blocked: true`.
+
+**Rate limit / sin reintento silencioso:**
+
+- El canario (siempre crashea por diseño) volvió a estar unhealthy sin
+  intervención extra.
+- Corrida siguiente: `elegibilidad=not_eligible:blocked_tras_intento_previo_sin_recuperacion`.
+- Claude devolvió `notify_only` para **todos** los recursos, incluido el
+  canario — ningún segundo restart propuesto ni ejecutado.
+- `state.json` sin cambios (mismo `last_action_at` que la corrida real
+  anterior) — confirma que no hubo reintento.
+- Notificación real entregada vía ntfy.sh, confirmada leyendo el propio
+  historial del topic (no solo el log del script).
+
+**Limpieza:** `deployment/test-agent-canary` eliminado, entrada
+correspondiente en `state.json` borrada. Los logs de la prueba
+(`actions.jsonl`, `run-*.log`) se conservan como evidencia auditable —
+no se purgaron.
+
+## Notificaciones
+
+Canal: [ntfy](https://ntfy.sh) — sin sistema de notificación previo en
+el lab, se eligió la opción sin infraestructura nueva (tópico público
+de ntfy.sh, nombre privado difícil de adivinar) para validar la prueba
+end-to-end sin bloquear en instalar y exponer un contenedor propio.
+Migrar a un ntfy self-hosted (mismo patrón que gitea/nginxproxymanager/
+cloudflared) es un cambio de una sola variable (`NTFY_URL`) cuando se
+decida.
+
+## Pendiente antes de activar el timer en continuo
+
+- **Confirmación explícita del propietario del lab** para habilitar el
+  timer de systemd (Paso 4 original) — no se activa automáticamente
+  solo por haber pasado la prueba end-to-end.
+- Unidad systemd corriendo como `devops` (no root), con límites de
+  CPU/memoria.
+- Opcional: `GITEA_TOKEN_FILE` para activar la señal de "runner
+  atascado" vía API de Gitea Actions (hoy se omite, degradación segura).

workloads/docs-portal/docs/decisiones/0005-rediseno-storefront.md

@@ -1,13 +1,14 @@
 # ADR 0005 — Rediseño del storefront para catálogo multi-categoría
 
-**Estado:** propuesta — pendiente de aprobación antes de Etapa 2
-**Fecha:** 2026-08-23
+**Estado:** aceptada — Etapa 2 implementada y en producción
+**Fecha:** 2026-08-23 (Etapa 1) — actualizado 2026-08-25 (Etapa 2 completa)
 
-> Este documento es la propuesta de Etapa 1 del rediseño de ARI
-> Shopping. No incluye código de producción — solo auditoría,
-> decisión (ver también [ADR 0004](0004-evaluacion-stack-multi-categoria.md)),
-> patrones de UX y datos demo ya creados y visibles en producción
-> como línea base.
+> Este documento arrancó como la propuesta de Etapa 1 del rediseño de
+> ARI Shopping (auditoría, decisión — ver también [ADR 0004](0004-evaluacion-stack-multi-categoria.md) —
+> patrones de UX y datos demo). Etapa 2 fue aprobada y se implementó
+> completa en tres sub-fases (datos/categorías, navegación,
+> componentes visuales) — ver la sección 6 para el detalle de cada
+> sub-fase y sus PRs.
 
 ## 1. Resumen de la auditoría
 
@@ -255,12 +256,33 @@ objetivo es validar la tubería Admin → MinIO → NPM → frontend, no el
 contenido visual final.
 
 Usuario admin temporal `[email protected]` usado para esta
-auditoría — pendiente de borrar una vez aprobada esta propuesta.
+auditoría — pendiente de borrar (ver sección 6).
 
-## 6. Próximos pasos
+## 6. Etapa 2 — implementada (2026-08-23 a 2026-08-25)
 
-Pendiente de tu aprobación explícita antes de iniciar Etapa 2. Cuando
-apruebes, Etapa 2 se dividirá en sub-fases (datos/categorías primero,
-luego navegación, luego componentes visuales), validando en cada paso
-contra estos 9 productos demo que precio/descripción/imágenes siguen
-actualizándose correctamente desde Admin.
+Aprobada y ejecutada en tres sub-fases, cada una validada en vivo
+contra estos 9 productos demo:
+
+1. **Datos/categorías** (2026-08-23/24): fix del bug de Store API que
+   impedía ver la categoría real de un producto (causa raíz del ADR
+   0004); 21 categorías/9 productos demo creados; `legacyProductMeta`
+   eliminado (PR #29) — 17 productos legacy con categoría/colección/
+   marca/rango de edad reales.
+2. **Navegación** (2026-08-25): navbar y tiles del home pasaron de
+   arrays hardcodeados a data-driven contra el árbol real de
+   categorías (`getCategories()`, PR #32); guard de CI actualizado
+   (PR #33); fix de tipos (PR #34); home/layout forzados a render
+   dinámico para evitar que quedaran cacheados con datos mock (PR #35).
+3. **Componentes visuales** (2026-08-25), los 4 patrones de la
+   sección 3 más el breadcrumb/facetas de Amazon: mega-menú
+   "Departamentos" multi-columna (PR #36), badges antes/ahora
+   (PR #37), swatches de variante inline (PR #38), mensaje de
+   urgencia por inventario real (PR #39), breadcrumb real + conteos
+   por filtro en el catálogo (PR #40), tiles promocionales
+   intercalados en la grilla (PR #41, con fix-forward de tipos en
+   PR #42).
+
+**Pendiente:** borrar el usuario admin temporal `[email protected]`
+de Medusa Admin (creado para la auditoría de la sección 5, ya no
+necesario). Sin próxima etapa definida todavía — este ADR no
+especifica una Etapa 3.

workloads/docs-portal/mkdocs.yml

@@ -84,6 +84,7 @@ nav:
       - Visión general: arquitectura/vision-general.md
       - Red y exposición: arquitectura/red-y-exposicion.md
       - Flujo GitOps: arquitectura/gitops-flujo.md
+      - Agente de monitoreo: arquitectura/agente-monitoreo.md
       - Glosario: arquitectura/glosario.md
   - Decisiones (ADRs):
       - "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md

workloads/docs-portal/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsNonRoot: false
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.125
+          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.159
           # El base saca TODAS las capabilities. Probado en vivo y
           # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE
           # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al

workloads/ecommerce/frontend/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsUser: 1001
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.154
+          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.157
           env:
             - name: HEADLESS_PROVIDER
               value: medusa