@saulwade/swl-ses 1.0.0

package/reglas/cloud-infra.md

@@ -0,0 +1,247 @@
+# Regla: Infraestructura Cloud
+
+Esta regla es OBLIGATORIA para todo recurso desplegado en cloud sin excepción.
+Una infraestructura mal configurada puede causar brechas de seguridad, pérdida de datos
+o costos desbocados en cuestión de horas. Ningún recurso cloud se considera listo para
+producción si viola cualquiera de los puntos aquí listados.
+
+---
+
+## Principio de menor privilegio en IAM
+
+Cada identidad (usuario, rol, cuenta de servicio) recibe solo los permisos
+estrictamente necesarios para su función, y nada más.
+
+- NUNCA asignar políticas de administrador (`AdministratorAccess`, `Owner`, `*:*`)
+  a cuentas de servicio, aplicaciones o usuarios que no sean administradores reales.
+- NUNCA asignar permisos de escritura cuando solo se necesita lectura.
+- NUNCA asignar permisos a nivel de cuenta/organización cuando el scope correcto
+  es un recurso específico (ej: un bucket S3, no todos los buckets).
+- Crear roles de IAM específicos por función:
+  - Rol para la aplicación web (lectura de secrets, escritura en BD, publicar en cola)
+  - Rol para el proceso de backup (lectura de BD, escritura en storage)
+  - Rol para el pipeline de CI/CD (push de imágenes, despliegue en el servicio)
+  Estos roles son diferentes y tienen permisos diferentes.
+- Revisar y limpiar permisos no utilizados cada 90 días.
+  AWS tiene `IAM Access Analyzer` para detectar permisos sin uso.
+  GCP tiene `IAM Recommender` con el mismo propósito.
+- Las llaves de acceso programático (API keys, service account keys) deben
+  rotarse cada 90 días máximo. Preferir roles temporales (STS AssumeRole, Workload Identity)
+  sobre llaves de larga duración cuando sea posible.
+- Autenticación multifactor (MFA) obligatoria para todos los usuarios humanos
+  de la consola cloud, sin excepción. Incluyendo administradores.
+
+---
+
+## Cifrado en reposo y en tránsito
+
+Todos los datos deben estar cifrados, tanto almacenados como en movimiento.
+
+### En reposo
+
+- Todos los volúmenes de disco (EBS, Persistent Disk, Managed Disks) deben
+  tener cifrado habilitado. Verificar que no está desactivado por defecto.
+- Todos los buckets de object storage (S3, GCS, Azure Blob) con cifrado activado.
+  Preferir llaves administradas por el cliente (KMS) para datos sensibles.
+- Las bases de datos relacionales y NoSQL con cifrado de almacenamiento habilitado.
+  RDS: `StorageEncrypted: true`. Cloud SQL: `diskEncryptionConfiguration`.
+- Los backups cifrados con la misma llave (o llave separada para mayor aislamiento).
+- Los snapshots de volúmenes y AMIs cifrados.
+
+### En tránsito
+
+- TLS 1.2 mínimo. TLS 1.3 preferido. Deshabilitar TLS 1.0 y TLS 1.1 explícitamente.
+- HTTPS obligatorio para toda comunicación entre servicios, incluyendo comunicación
+  interna entre microservicios dentro de la misma VPC.
+- Certificados de TLS renovados automáticamente (ACM, Let's Encrypt con cert-manager,
+  Google-managed certificates).
+- HSTS habilitado con `max-age` mínimo de 31536000 (1 año) en servicios públicos.
+- La comunicación con bases de datos debe ser sobre TLS:
+  `sslmode=require` en PostgreSQL, `require_secure_transport=ON` en MySQL.
+- Las colas de mensajes (SQS, Pub/Sub, Service Bus) con cifrado de mensajes habilitado.
+
+---
+
+## Prohibición absoluta de credenciales hardcodeadas
+
+Las credenciales en código fuente son una de las causas más comunes de brechas de seguridad.
+
+- NUNCA hardcodear en código fuente: passwords, API keys, tokens de acceso,
+  connection strings, certificados privados, IDs de cuenta, ARNs con cuenta específica.
+- NUNCA hardcodear credenciales en Dockerfiles, docker-compose.yml, manifiestos
+  de Kubernetes, archivos de Terraform, scripts de CI/CD.
+- NUNCA commitear archivos `.env` con valores reales. Solo `.env.example` con
+  nombres de variables y valores de placeholder.
+- Usar el servicio de gestión de secretos correspondiente al cloud provider:
+  - AWS: Secrets Manager o Parameter Store (SSM)
+  - GCP: Secret Manager
+  - Azure: Key Vault
+  - Kubernetes: External Secrets Operator (integrando con el cloud secrets manager)
+- Para variables de entorno en CI/CD, usar las variables de entorno cifradas
+  del servicio de CI (GitHub Actions Secrets, GitLab CI Variables, etc.).
+  NUNCA escribirlas en archivos de configuración del pipeline.
+- Ejecutar `git-secrets` o `truffleHog` en el pipeline de CI para detectar
+  credenciales accidentalmente commiteadas.
+- Si se detecta una credencial comprometida en git:
+  1. Revocarla/rotarla INMEDIATAMENTE
+  2. Asumir que fue vista por actores maliciosos
+  3. Limpiar el historial con `git filter-repo` o BFG Repo Cleaner
+  4. No es suficiente con un commit que la borre — el historial es público
+
+---
+
+## Infraestructura como código (IaC) para todo recurso
+
+Ningún recurso cloud se crea manualmente desde la consola en ambientes no locales.
+
+- Todo recurso de producción y staging debe estar definido en código:
+  Terraform, Pulumi, AWS CDK, AWS CloudFormation, Azure Bicep, o el equivalente.
+- Los recursos creados manualmente no son reproducibles, no son auditables y no
+  son recuperables en caso de desastre. Son deuda técnica crítica.
+- El código de IaC vive en el repositorio del proyecto (o en un repositorio
+  dedicado de infraestructura si el equipo es grande).
+- Los cambios de infraestructura pasan por code review igual que el código de aplicación.
+- Antes de aplicar cambios: `terraform plan` (o equivalente) debe revisarse
+  y aprobarse. NUNCA aplicar IaC sin revisar el plan.
+- Los cambios de infraestructura se despliegan a través del pipeline de CI/CD,
+  no manualmente desde la terminal de un desarrollador.
+- Los módulos de Terraform/Pulumi deben tener versiones pinneadas. No usar
+  rangos abiertos en módulos de infraestructura.
+- Estado de Terraform almacenado en backend remoto (S3+DynamoDB, GCS, Terraform Cloud)
+  con locking habilitado. NUNCA usar estado local en equipos.
+
+---
+
+## Alta disponibilidad y multi-AZ para producción
+
+Los servicios de producción deben tolerar la falla de una zona de disponibilidad.
+
+- Las bases de datos de producción deben ser multi-AZ:
+  RDS con Multi-AZ deployment, Cloud SQL con high availability, Azure SQL con Zone Redundancy.
+- Los servidores de aplicación deben escalar horizontalmente en múltiples AZs.
+  NUNCA desplegar en una sola instancia sin failover para servicios de producción.
+- El load balancer debe distribuir tráfico entre múltiples AZs.
+- Los buckets de object storage son multi-AZ por defecto en la mayoría de providers.
+  Verificar que la clase de almacenamiento seleccionada sea multi-regional o multi-AZ.
+- Para servicios con SLA de alta disponibilidad: considerar multi-región con
+  routing DNS geográfico (Route 53 latency routing, Cloud DNS, Azure Traffic Manager).
+- El objetivo de tiempo de recuperación (RTO) y el objetivo de punto de recuperación (RPO)
+  deben estar definidos y documentados para cada servicio de producción.
+- Las fallas de AZ deben probarse periódicamente (Game Days, Chaos Engineering).
+
+---
+
+## Backups automatizados con retención definida
+
+Los datos deben poder recuperarse. Sin backups verificados, no hay recuperación.
+
+- Todos los servicios con estado (bases de datos, filesystems, object storage crítico)
+  deben tener backups automatizados configurados por IaC.
+- La política de retención debe estar definida explícitamente:
+  - Producción: mínimo 30 días de retención, recomendado 90 días
+  - Staging: mínimo 7 días
+  - Backups de largo plazo (compliance): definir según requisito regulatorio
+- Los backups deben almacenarse en una cuenta o proyecto cloud diferente al de
+  producción para protección contra eliminación accidental o ransomware.
+- El cifrado de backups es obligatorio (misma regla que datos en reposo).
+- La restauración de backups debe probarse mensualmente en staging.
+  Un backup que no se ha restaurado exitosamente no existe.
+- Configurar alertas cuando un backup falla. NUNCA descubrir la falla en el momento
+  en que se necesita restaurar.
+- Para bases de datos: point-in-time recovery (PITR) habilitado en producción.
+  Permite restaurar a cualquier momento dentro de la ventana de retención.
+
+---
+
+## Monitoring, alertas y observabilidad obligatorios
+
+Si no está monitorizado, no está en producción.
+
+- Todo servicio de producción debe tener:
+  - **Métricas de infraestructura**: CPU, memoria, disco, red (CloudWatch, Cloud Monitoring, Azure Monitor)
+  - **Métricas de aplicación**: latencia p50/p95/p99, tasa de errores, throughput
+  - **Logs centralizados**: CloudWatch Logs, Cloud Logging, Azure Log Analytics
+  - **Trazas distribuidas**: X-Ray, Cloud Trace, Application Insights (si hay microservicios)
+- Alertas obligatorias con acción definida (no alertas sin destinatario):
+  - CPU > 80% por más de 5 minutos
+  - Disco > 85% de uso
+  - Tasa de errores HTTP 5xx > 1% del tráfico
+  - Latencia p95 > umbral definido por SLA
+  - Fallo de backup
+  - Certificado TLS con vencimiento < 30 días
+- Las alertas deben ir a un canal con responsable activo (PagerDuty, OpsGenie, Slack con on-call).
+  NUNCA alertas que van a un buzón que nadie revisa.
+- Implementar dashboards de salud accesibles al equipo completo.
+- Los logs NO deben contener datos sensibles: passwords, tokens, PII, números de tarjeta.
+  Configurar filtros de sanitización de logs.
+- Retención de logs: mínimo 90 días en producción. Requisitos de compliance pueden
+  requerir más (1-7 años según el sector).
+
+---
+
+## Tagging obligatorio de recursos
+
+Los recursos sin tags son inauditables, sin dueño y sin costo asignable.
+
+Los siguientes tags son OBLIGATORIOS en TODOS los recursos cloud:
+
+```
+proyecto:      nombre del proyecto o sistema (ej: "swl-core", "facturacion")
+ambiente:      prod | staging | dev | test
+equipo:        nombre del equipo responsable (ej: "backend", "infraestructura")
+costo-center:  centro de costo para facturación interna (ej: "ing-2024", "cliente-abc")
+```
+
+Tags adicionales recomendados:
+
+```
+owner:         correo del responsable técnico
+version:       versión del componente (si aplica)
+auto-apagado:  "true" para recursos de dev/test que se apagan fuera de horario laboral
+```
+
+- Configurar políticas de gobernanza que rechacen la creación de recursos sin los
+  tags obligatorios (AWS Service Control Policies, GCP Organization Policies).
+- Los tags deben definirse en el IaC, no agregarse manualmente después.
+- Usar los tags para:
+  - Filtrar recursos por proyecto en las consultas de costo
+  - Identificar recursos huérfanos (sin equipo asignado)
+  - Implementar apagado automático de recursos de no-producción
+
+---
+
+## Segmentación de red (VPC, subnets, security groups)
+
+La red debe estar diseñada con defensa en profundidad.
+
+- Cada ambiente (prod, staging, dev) debe tener su propia VPC separada.
+  NUNCA mezclar prod y dev en la misma VPC.
+- Las bases de datos y servicios internos NUNCA deben tener IP pública.
+  Deben vivir en subnets privadas sin ruta directa a internet.
+- Los security groups deben seguir el principio de menor privilegio:
+  - NUNCA `0.0.0.0/0` en reglas de ingreso de puertos de aplicación (80, 443 son excepciones para el LB)
+  - NUNCA `0.0.0.0/0` en reglas de ingreso para SSH (22) o RDP (3389) en producción.
+    Usar VPN, bastion host o AWS Systems Manager Session Manager.
+  - Las reglas de egreso deben ser explícitas — no `0.0.0.0/0` sin justificación.
+- El acceso SSH/RDP a instancias de producción debe ser a través de bastion host
+  o VPN corporativa, nunca directamente desde internet.
+- Los balanceadores de carga son los únicos recursos en subnets públicas.
+  Las instancias de aplicación van en subnets privadas.
+- VPC Flow Logs habilitados en producción para auditoría de tráfico de red.
+- Network ACLs como capa adicional de defensa para subnets críticas.
+
+---
+
+## Checklist antes de desplegar un nuevo recurso en producción
+
+- [ ] Definido en IaC — no creado manualmente en la consola
+- [ ] Tag obligatorio de proyecto, ambiente, equipo y costo-center asignados
+- [ ] Principio de menor privilegio aplicado a los roles IAM asociados
+- [ ] Cifrado en reposo habilitado
+- [ ] Comunicación sobre TLS configurada
+- [ ] Multi-AZ configurado (si es un servicio con estado)
+- [ ] Backups automatizados configurados con política de retención definida
+- [ ] Monitoreo y alertas configuradas
+- [ ] El recurso está en subnet privada (si no es un LB o CDN)
+- [ ] No hay credenciales hardcodeadas en la configuración
+- [ ] El código de IaC pasó code review

package/reglas/docs.md

@@ -0,0 +1,245 @@
+# Regla: Documentación
+
+La documentación es para los humanos que vienen después — incluyendo tú mismo
+en seis meses. Documenta el POR QUÉ, no el QUÉ: el código ya explica el qué.
+La documentación explica el contexto, las restricciones y las decisiones.
+
+---
+
+## Documentar el POR QUÉ, no el QUÉ
+
+El código bien escrito es autoexplicativo en el QUÉ. Los comentarios agregan
+valor cuando explican lo que el código no puede expresar por sí solo:
+
+- Por qué se tomó esta decisión en lugar de la alternativa obvia
+- Por qué hay una excepción a la regla general
+- Qué restricción externa (API, regulación, legacy) explica una solución poco intuitiva
+- Qué bug histórico motivó este código aparentemente innecesario
+
+Mal — documenta el qué (redundante con el código):
+```python
+# Incrementar el contador
+contador += 1
+
+# Verificar si el usuario está activo
+if usuario.es_activo:
+```
+
+Bien — documenta el por qué:
+```python
+# El SAT requiere que el folio fiscal sea consecutivo sin gaps.
+# Usar SEQUENCE de PostgreSQL garantiza atomicidad bajo concurrencia.
+folio = await db.execute(text("SELECT nextval('folio_fiscal_seq')"))
+
+# HACK: la API de CFDI devuelve 200 incluso para errores de validación.
+# Detectar el error por la presencia del campo "faultcode" en la respuesta.
+if "faultcode" in respuesta:
+```
+
+---
+
+## README actualizado
+
+El README es el punto de entrada al proyecto. Debe estar siempre actualizado.
+Un README desactualizado es peor que no tener README — genera confianza falsa.
+
+Estructura mínima del README del proyecto:
+```markdown
+# Nombre del Proyecto
+
+Descripción en 2-3 líneas: qué hace, para quién, qué problema resuelve.
+
+## Requisitos previos
+- Python 3.12+
+- PostgreSQL 15+
+- Node.js 20+
+
+## Instalación y setup local
+Instrucciones paso a paso. Que funcionen. Probarlas en una máquina limpia.
+
+## Cómo correr los tests
+
+## Cómo levantar el entorno de desarrollo
+
+## Variables de entorno requeridas
+Lista con descripción de cada variable (nunca valores reales).
+
+## Arquitectura
+Link al diagrama o descripción de alto nivel.
+
+## Contribuir
+Link al CONTRIBUTING.md o instrucciones básicas.
+```
+
+Reglas del README:
+- Las instrucciones de instalación deben funcionar. Probarlas periódicamente.
+- Actualizar el README en el mismo PR que introduce el cambio que lo hace obsoleto.
+- Sin secciones "TODO" o "próximamente" — si no está listo, no va en el README.
+- Sin secciones genéricas copiadas de templates sin personalizar.
+
+---
+
+## CHANGELOG con formato Keep a Changelog
+
+Formato oficial: https://keepachangelog.com/es/1.0.0/
+
+Estructura:
+```markdown
+# Changelog
+
+## [Sin publicar]
+
+### Agregado
+- Nueva funcionalidad X
+
+## [1.2.0] - 2026-01-15
+
+### Agregado
+- Soporte para exportación de reportes en PDF
+
+### Cambiado
+- El endpoint /facturas ahora devuelve paginación por defecto
+
+### Corregido
+- Error al calcular IEPS para productos con tasa 0%
+
+### Eliminado
+- Endpoint /facturas/legacy deprecado desde v1.0
+
+## [1.1.0] - 2025-11-20
+...
+```
+
+Reglas del CHANGELOG:
+- Actualizar en cada PR que cambia comportamiento observable por el usuario.
+  Cambios internos de refactor o tests: no requieren entrada en CHANGELOG.
+- Sección "Sin publicar" para cambios no lanzados todavía.
+  Al lanzar: renombrar la sección con la versión y fecha.
+- Una línea por cambio, redactada para el usuario, no para el desarrollador.
+  "Corregido error al exportar PDF con caracteres especiales" > "fix: null pointer en PdfExportService"
+- El CHANGELOG vive en la raíz del repositorio como `CHANGELOG.md`.
+
+---
+
+## ADRs para decisiones arquitecturales
+
+Ver también: `reglas/arquitectura.md`
+
+- Directorio: `docs/adr/` en el repositorio.
+- Índice en `docs/adr/README.md` con lista de todos los ADRs y su estado.
+- Buscar en los ADRs existentes antes de proponer una decisión nueva.
+  Si ya hay un ADR que la cubre: referenciarlo, no crear uno duplicado.
+- ADRs deprecados o reemplazados: no borrar — actualizar el estado y referenciar
+  el ADR nuevo. El historial de decisiones es valioso.
+
+---
+
+## Runbooks para procesos operativos
+
+Un runbook es una guía paso a paso para ejecutar un proceso operativo:
+deploy, rollback, migración de datos, respuesta a incidentes.
+
+Ubicación: `docs/runbooks/`
+
+Estructura mínima de un runbook:
+```markdown
+# Runbook: [Nombre del proceso]
+
+**Propósito**: Qué hace este proceso y cuándo ejecutarlo.
+**Tiempo estimado**: N minutos
+**Prerrequisitos**: Qué accesos/herramientas se necesitan
+**Riesgos**: Qué puede salir mal y cómo mitigarlo
+
+## Pasos
+
+### 1. [Nombre del paso]
+```bash
+comando exacto a ejecutar
+```
+**Resultado esperado**: descripción de qué debe pasar.
+**Si falla**: qué hacer.
+
+## Verificación post-ejecución
+- [ ] Paso de verificación 1
+- [ ] Paso de verificación 2
+
+## Rollback
+Pasos para deshacer el proceso si algo falla.
+```
+
+Procesos que DEBEN tener runbook:
+- Deploy a producción
+- Rollback de deploy
+- Migraciones de BD en producción
+- Rotación de secrets
+- Respuesta a incidente de seguridad
+- Backup y restore de BD
+
+---
+
+## Documentación de APIs
+
+- Toda API REST tiene documentación OpenAPI/Swagger generada automáticamente
+  y disponible en `/docs` (desarrollo) y `/api/docs` (producción con auth).
+- Cada endpoint tiene descripción, parámetros documentados y ejemplos de respuesta.
+- Los campos de schemas Pydantic con `description=` son parte de la spec — no opcionales.
+- Errores posibles documentados (qué regresa en 400, 401, 403, 404, 422, 500).
+
+---
+
+## Sin documentación vacía o genérica
+
+Documentación que no ayuda es ruido que hay que mantener:
+
+Señales de documentación vacía a eliminar:
+- `"""Constructor de la clase Factura"""` — obvio del nombre.
+- `"""Parámetros: id (int): el id"""` — sin información nueva.
+- Secciones del README copiadas de un template sin personalizar.
+- Comentarios `# TODO` sin número de ticket y fecha.
+- ADRs con "Contexto: se necesitaba una solución" sin detalles reales.
+
+Si no se tiene tiempo de documentar bien: es mejor no poner documentación vacía.
+Marcar explícitamente con `# NODOC: pendiente de documentar (ticket #NNN)`.
+
+---
+
+## Docstrings — cuándo y cómo
+
+Python:
+- Docstring obligatorio en módulos, clases públicas y funciones públicas no triviales.
+- Funciones privadas (`_nombre`) y triviales (getters simples): docstring opcional.
+- Formato Google Style:
+  ```python
+  def calcular_iva(precio: Decimal, tasa: float) -> Decimal:
+      """Calcula el IVA sobre el precio dado.
+
+      No incluye IEPS ni retenciones. Para cálculo completo usar
+      `calcular_impuestos_completos()`.
+
+      Args:
+          precio: Precio base sin impuestos.
+          tasa: Tasa como decimal (0.16 para 16%).
+
+      Returns:
+          Monto del IVA redondeado a 2 decimales.
+
+      Raises:
+          ValueError: Si la tasa es negativa o mayor que 1.
+      """
+  ```
+
+TypeScript:
+- JSDoc en funciones públicas de services y utilities.
+- Componentes Angular: comentario en el selector explicando el propósito del componente.
+
+---
+
+## Checklist de documentación antes de merge
+
+- [ ] README refleja los cambios del PR
+- [ ] CHANGELOG actualizado si hay cambio observable por el usuario
+- [ ] ADR creado si hubo decisión arquitectural significativa
+- [ ] Endpoints nuevos con descripción en el schema OpenAPI
+- [ ] Sin comentarios que explican el qué (solo el por qué)
+- [ ] Sin secciones TODO vacías sin ticket asociado
+- [ ] Runbook creado si se agregó proceso operativo nuevo

package/reglas/estilo-codigo.md

@@ -0,0 +1,201 @@
+# Regla: Estilo de Código
+
+El código se lee muchas más veces de las que se escribe. Estas reglas maximizan
+la legibilidad y reducen la carga cognitiva de quien mantiene el código después.
+Aplican a todos los lenguajes del stack salvo indicación contraria.
+
+---
+
+## Nombres descriptivos
+
+- Los nombres son documentación. Un nombre que requiere un comentario para
+  entenderse es un nombre malo — renombrar.
+- Variables, funciones y clases: nombrar por lo que SON o lo que HACEN,
+  no por su tipo ni su implementación.
+  - Mal: `d`, `tmp`, `data`, `obj`, `flag`, `result`
+  - Bien: `fecha_entrega`, `usuario_autenticado`, `calcular_impuesto()`
+- Booleanos: prefijo `es_`, `tiene_`, `puede_`, `esta_`.
+  - Mal: `activo`, `valido`, `habilitado`
+  - Bien: `es_activo`, `tiene_permisos`, `puede_editar`
+- Funciones: verbo + sustantivo. Describe la acción y el objeto.
+  - Mal: `proceso()`, `handler()`, `manage()`
+  - Bien: `procesar_pago()`, `manejar_solicitud_reembolso()`
+- Colecciones: plural del elemento.
+  - Mal: `lista`, `items`, `data`
+  - Bien: `facturas`, `usuarios_activos`, `errores_validacion`
+- No abreviaciones salvo las universalmente conocidas (`id`, `url`, `http`, `api`).
+  Siempre en el contexto del proyecto — si hay duda, escribir completo.
+
+---
+
+## Funciones cortas — límite estricto de 30 líneas
+
+- Una función hace UNA sola cosa. Si se necesita "y" para describir lo que hace,
+  es candidata a dividirse.
+- Límite de 30 líneas de código efectivo (sin contar comentarios, líneas en blanco
+  ni firmas de función).
+- Si una función supera 30 líneas: extraer subfunciones con nombres descriptivos.
+  El cuerpo de la función original queda como un sumario legible de pasos.
+- Parámetros: máximo 4. Si se necesitan más, agrupar en un objeto/dataclass.
+- Complejidad ciclomática máxima: 5. Más de 5 ramas → refactorizar.
+
+---
+
+## Un solo nivel de abstracción por función
+
+- Cada función opera en un único nivel de abstracción. No mezclar operaciones
+  de alto nivel (lógica de negocio) con detalles de bajo nivel (parsing, formateo).
+
+  Mal — mezcla niveles:
+  ```python
+  def procesar_pedido(pedido_id):
+      pedido = db.execute("SELECT * FROM pedidos WHERE id = %s", (pedido_id,))
+      if pedido["estatus"] == "pendiente":
+          total = sum(item["precio"] * item["cantidad"] for item in pedido["items"])
+          db.execute("UPDATE pedidos SET total = %s WHERE id = %s", (total, pedido_id))
+  ```
+
+  Bien — nivel uniforme:
+  ```python
+  def procesar_pedido(pedido_id):
+      pedido = obtener_pedido(pedido_id)
+      if esta_pendiente(pedido):
+          actualizar_total(pedido)
+  ```
+
+---
+
+## Early return — evitar anidamiento profundo
+
+- Validar precondiciones al inicio y retornar inmediatamente si no se cumplen.
+  Nunca anidar la lógica principal dentro de múltiples `if`.
+- Máximo 2 niveles de anidamiento dentro de una función (sin contar el cuerpo
+  de la función en sí). Si se llega a 3: early return o extracción de función.
+
+  Mal:
+  ```python
+  def crear_factura(usuario, items):
+      if usuario:
+          if items:
+              if len(items) > 0:
+                  # lógica principal aquí, muy adentro
+  ```
+
+  Bien:
+  ```python
+  def crear_factura(usuario, items):
+      if not usuario:
+          raise ValueError("Usuario requerido")
+      if not items:
+          raise ValueError("La factura debe tener al menos un ítem")
+      # lógica principal al nivel superior
+  ```
+
+---
+
+## Sin código muerto
+
+- Eliminar código comentado antes de hacer merge. Si se necesita recuperar algo,
+  existe git. El código comentado genera confusión sobre si está activo o no.
+- Eliminar variables declaradas y nunca usadas.
+- Eliminar imports no utilizados.
+- Eliminar funciones que ya no tienen llamadores (verificar con búsqueda global).
+- Eliminar flags de feature que ya no tienen sentido (limpiar deuda técnica).
+- Los linters (flake8, ESLint, Pylance) deben pasar en CI sin warnings de código muerto.
+
+---
+
+## Principio DRY — no duplicar conocimiento
+
+- DRY no es solo "no duplicar texto". Es no duplicar conocimiento. Si una regla
+  de negocio, una validación, una query o una transformación existe en un lugar,
+  no debe existir en otro. Cuando el conocimiento cambia, debe cambiar en un solo sitio.
+- Antes de crear una función, clase o módulo nuevo: buscar si ya existe algo que
+  haga lo mismo con Grep o Glob. Si existe, reutilizar o extender — no duplicar.
+- Señales de violación DRY que deben corregirse:
+  - Misma query SQL en 2+ lugares → extraer a un método del repositorio
+  - Misma validación de input en 2+ endpoints → extraer a un schema/validator compartido
+  - Misma transformación de datos en 2+ puntos → extraer a una función helper
+  - Misma constante definida en múltiples archivos → mover a un módulo de constantes
+  - Mismo bloque try/except en 2+ funciones → extraer a un decorator o context manager
+- Dos funciones que hacen lo mismo pero por razones de negocio distintas NO son
+  violaciones DRY. DRY aplica cuando el conocimiento duplicado cambiaría junto:
+  si un cambio en un lugar obliga a cambiar el otro, es duplicación.
+- Tres líneas de código similares son mejor que una abstracción prematura. DRY no
+  justifica crear helpers de una sola línea que se usan dos veces.
+
+---
+
+## Sin console.log / print en producción
+
+- `console.log()`, `print()`, `console.debug()`, `System.out.println()` y
+  equivalentes están prohibidos en código que se mergea a main.
+- Usar el logger configurado del proyecto:
+  - Python: `import logging; logger = logging.getLogger(__name__)`
+  - TypeScript/Angular: servicio de logging centralizado o `LoggingService`
+- Nivel de log apropiado: `DEBUG` para desarrollo, `INFO` para flujos importantes,
+  `WARNING` para situaciones inesperadas recuperables, `ERROR` para fallos.
+- Los logs de nivel DEBUG no aparecen en producción — configurar por entorno.
+- CI debe fallar si encuentra `console.log` o `print(` fuera de archivos de test.
+
+---
+
+## Organización de imports
+
+Python — orden PEP 8, separados por línea en blanco:
+1. Standard library (`os`, `sys`, `datetime`, etc.)
+2. Dependencias de terceros (`fastapi`, `sqlalchemy`, `pydantic`, etc.)
+3. Módulos propios del proyecto (con rutas absolutas desde la raíz del proyecto)
+
+TypeScript/Angular — orden ESLint import/order:
+1. Angular core y common (`@angular/core`, `@angular/common`)
+2. Angular material y otras librerías (`@angular/material/*`)
+3. RxJS (`rxjs`, `rxjs/operators`)
+4. Librerías de terceros
+5. Módulos propios (paths con alias `@app/`, `@core/`, `@shared/`)
+
+Reglas adicionales:
+- Sin imports con wildcard (`from module import *`) salvo `__init__.py` explícito.
+- Un import por línea en TypeScript.
+- Usar paths absolutos en imports propios — nunca `../../../../../../modulo`.
+
+---
+
+## Constantes con SCREAMING_CASE
+
+- Toda constante con valor literal que se usa en múltiples lugares:
+  definir una sola vez con nombre en SCREAMING_CASE.
+- Agrupa constantes relacionadas en un módulo o clase de constantes.
+  ```python
+  # constants.py
+  MAX_INTENTOS_LOGIN = 5
+  TIEMPO_EXPIRACION_TOKEN_MINUTOS = 60
+  ROLES_ADMINISTRADORES = ["ADMIN", "SUPERADMIN"]
+  ```
+- En TypeScript, usar `const` con SCREAMING_CASE o `enum` con PascalCase.
+- NUNCA magic numbers o magic strings dispersos en el código.
+  Si aparece un literal numérico o string no trivial: extraerlo a constante.
+
+---
+
+## Reglas adicionales de legibilidad
+
+- Longitud máxima de línea: 100 caracteres (Python), 120 caracteres (TypeScript).
+- Un solo nivel de ternario. Ternarios anidados: prohibidos.
+- No usar `else` después de `return` o `raise` — es redundante y añade anidamiento.
+- Agrupar código relacionado. Separar grupos con una línea en blanco.
+- Comentarios en español (idioma del proyecto). Gramática y ortografía correctas.
+- Comentarios explican el POR QUÉ, no el QUÉ. El código explica el qué.
+
+---
+
+## Checklist de estilo antes de abrir PR
+
+- [ ] Sin variables, imports o funciones sin usar
+- [ ] Sin código comentado
+- [ ] Sin console.log/print de debug
+- [ ] Nombres descriptivos en todo el código nuevo
+- [ ] Funciones <= 30 líneas
+- [ ] Sin magic numbers ni magic strings
+- [ ] Sin duplicación de lógica de negocio entre módulos (DRY)
+- [ ] Linter y type-checker pasan sin warnings