schema: spec-driven

context: |
  Componente: Golden Path "web-backend/python" (Coralware Cove IDP)
  Tipo: Shape de aplicación tenant — FastAPI + Alembic + MariaDB
  Repo Gitea generado: idp-templates/template-web-backend-python
  Audiencia consumidora: tenants externos (clientes, p.ej. NexoBMS)
  Gobernanza: este openspec es interno de Coralware — NO se sincroniza al
  repo Gitea del template ni llega al repo del cliente.

  Stack del shape:
    - Python 3.12 + FastAPI + Uvicorn
    - SQLAlchemy + Alembic (migraciones como Helm hook pre-upgrade)
    - MariaDB 11 (provisión manual via runbook hasta ADR-052 / Fase 5.5+)
    - Helm chart en helm/<APP_NAME>/ versionado en repo del tenant
    - CI: Gitea Actions invocando reusable workflow ADR-038 + job helm-deploy
    - Runtime: cluster Rancher RKE2 del tenant

  Convenciones obligatorias del shape:
    - Endpoints fijos: /health, /docs, /openapi.json, /demo, /metrics
    - /health retorna {status, db} y 503 si DB caída (fail-safe, no crash)
    - Labels: app.kubernetes.io/name=<APP_NAME>, idp.coralware.cloud/tier,
      idp.coralware.cloud/tenant-id, idp.coralware.cloud/golden-path=web-backend,
      idp.coralware.cloud/golden-path-lang=python
    - SecurityContext: runAsNonRoot=true, runAsUser=1001, readOnlyRootFilesystem=true,
      drop ALL caps, allowPrivilegeEscalation=false
    - Secret esperado: <APP_NAME>-db-creds con DATABASE_URL + MIGRATION_DATABASE_URL
    - Imagen: registry.coralsafety.com/tenant-<id>/<APP_NAME>:<tag>
    - Pipeline ADR-038: black → ruff → bandit → pytest --cov 80 → buildkit → trivy
    - Coverage threshold del shape: 80% (vs 90% en MSs internos del IDP)

  ADRs relacionados:
    - ADR-027 — Golden Paths Fase 5
    - ADR-029 — API standards (R-004 JWT, R-007 correlation_id)
    - ADR-032 — Backstage catalog model
    - ADR-038 — CI estándar reusable workflow Python
    - ADR-052 — TenantAddon / AddonClaim (modelo BD reutilizable)
    - ADR-053 — Anatomía y contrato del shape web-backend/python

  PoC inicial:
    - NexoBMS (Demetrio) — primer caso de uso real
    - Tier startup gratuito durante 30 días
    - 11 criterios de éxito + 5 pruebas negativas (N1-N5) en runbook

rules:
  proposal:
    - Incluir sección "Non-goals" explícita (qué NO entrega el shape)
    - Referenciar ADRs y poc-nexobms.md cuando aplique
    - Indicar impacto sobre repo-provisioner si cambia el contrato de
      placeholders (__APP_NAME__, __TIER__, __TENANT_ID__, __TENANT_ID_NODASHES__)
  design:
    - Especificar variables de entorno consumidas por la app y por Helm values
    - Documentar interacción con AddonClaim (ADR-052) y runbook MariaDB (modo manual)
    - Incluir comportamiento fail-safe (errores de DB no crashean la app)
    - Si el cambio toca el flujo CI/CD, actualizar el flowchart Mermaid de specs/main.md
      ANTES de tocar el workflow YAML
  tasks:
    - Versionar el cambio del shape: shapeVersion en coralware-shape.yaml sigue semver
    - Mantener exclusión de openspec/ en el sync a Gitea (no llega al cliente)
    - Validar render server-side de placeholders por repo-provisioner antes de cada release
    - Tests del scaffold: pytest --cov ≥ 80 sobre code/ del template antes de publicar