@saulwade/swl-ses 1.0.0

package/plantillas/research/STACK.md

@@ -0,0 +1,233 @@
+# STACK: Evaluación Tecnológica — [Nombre del Proyecto]
+
+> Investigación del stack tecnológico con análisis de alternativas.
+> Esta evaluación sustenta las decisiones en PROYECTO.md y los ADRs correspondientes.
+> Autor: [nombre] | Fecha: YYYY-MM-DD
+
+---
+
+## Criterios de evaluación
+
+Los criterios con los que se evalúa cada tecnología, ordenados por importancia:
+
+1. **Madurez y estabilidad**: ¿Tiene historial de producción? ¿Comunidad activa?
+2. **Conocimiento del equipo**: ¿El equipo lo conoce o hay curva de aprendizaje?
+3. **Ajuste al problema**: ¿La tecnología resuelve bien el tipo de problema del proyecto?
+4. **Mantenibilidad**: ¿Será mantenible en 3 años? ¿Hay actualizaciones frecuentes?
+5. **Performance**: ¿Cumple los requisitos no funcionales definidos?
+6. **Ecosistema**: ¿Tiene las librerías/plugins necesarios disponibles?
+
+---
+
+## Lenguaje de backend
+
+### Opción A: [ej. Python 3.12]
+
+**Pros**:
+- [Pro específico al proyecto, no genérico]
+- [Pro]
+- [Pro]
+
+**Contras**:
+- [Contra específico, con impacto estimado]
+- [Contra]
+
+**Veredicto**: [Seleccionado / Descartado]
+**Razón del veredicto**: [Justificación concisa]
+
+---
+
+### Opción B: [ej. Node.js 20 / TypeScript]
+
+**Pros**:
+-
+-
+
+**Contras**:
+-
+-
+
+**Veredicto**: Descartado
+**Razón**: [Por qué se prefirió la opción A]
+
+---
+
+**DECISIÓN**: [Opción elegida] — ADR: `docs/adr/NNN-lenguaje-backend.md`
+
+---
+
+## Framework de backend
+
+### Opción A: [ej. FastAPI 0.111]
+
+**Pros**:
+- Tipado nativo con Pydantic — validación automática de inputs
+- OpenAPI/Swagger generado automáticamente
+- Async nativo — ideal para I/O bound (BD, APIs externas)
+- [Pro específico al proyecto]
+
+**Contras**:
+- [Contra — ej. ecosistema más pequeño que Django para admin/cms]
+- [Contra]
+
+**Veredicto**: Seleccionado
+
+---
+
+### Opción B: [ej. Django + DRF]
+
+**Pros**:
+- ORM maduro con migraciones robustas
+- Admin integrado listo para usar
+
+**Contras**:
+- Async más complejo de implementar correctamente
+- Más overhead para API-only (sin templates)
+
+**Veredicto**: Descartado
+**Razón**: [Justificación]
+
+---
+
+**DECISIÓN**: [Opción elegida] — ADR: `docs/adr/NNN-framework-backend.md`
+
+---
+
+## Base de datos
+
+### Opción A: [ej. PostgreSQL 16]
+
+**Pros**:
+- ACID completo
+- JSONB para datos semi-estructurados
+- Full-text search nativo
+- [Pro]
+
+**Contras**:
+- [Contra]
+
+**Veredicto**: Seleccionado
+
+---
+
+### Opción B: [ej. MySQL 8]
+
+**Pros**:
+-
+
+**Contras**:
+-
+
+**Veredicto**: Descartado
+**Razón**:
+
+---
+
+### Opción C: [ej. MongoDB] (solo si aplica)
+
+**Pros**:
+-
+
+**Contras**:
+-
+
+**Veredicto**: Descartado
+**Razón**:
+
+---
+
+**DECISIÓN**: [Opción elegida] — ADR: `docs/adr/NNN-base-de-datos.md`
+
+---
+
+## Framework de frontend
+
+### Opción A: [ej. Angular 18]
+
+**Pros**:
+- Framework completo con DI, router, forms, HttpClient
+- TypeScript first — tipado end-to-end
+- Signals para estado reactivo sin RxJS complejo
+- [Pro]
+
+**Contras**:
+- [Contra — ej. bundle inicial más pesado que React]
+- [Contra]
+
+**Veredicto**: Seleccionado
+
+---
+
+### Opción B: [ej. React + Next.js]
+
+**Pros**:
+-
+
+**Contras**:
+-
+
+**Veredicto**: Descartado
+**Razón**:
+
+---
+
+**DECISIÓN**: [Opción elegida] — ADR: `docs/adr/NNN-framework-frontend.md`
+
+---
+
+## Infraestructura y deployment
+
+### Opción A: [ej. Docker + Kubernetes en GCP]
+
+**Pros**:
+-
+-
+
+**Contras**:
+-
+-
+
+**Veredicto**: Seleccionado
+
+---
+
+### Opción B: [ej. VMs en Azure con Ansible]
+
+**Pros**:
+-
+
+**Contras**:
+-
+
+**Veredicto**: Descartado
+**Razón**:
+
+---
+
+**DECISIÓN**: [Opción elegida] — ADR: `docs/adr/NNN-infraestructura.md`
+
+---
+
+## Herramientas complementarias
+
+| Herramienta | Propósito | Alternativa considerada | Razón de elección |
+|-------------|-----------|------------------------|-------------------|
+| [ej. Redis] | Cache + sesiones | [Memcached] | [TTL con estructuras de datos complejas] |
+| [ej. Celery] | Tareas async | [RQ, ARQ] | [Madurez, integración con Django/FastAPI] |
+| [ej. Alembic] | Migraciones BD | [Django migrations] | [Necesario con FastAPI] |
+| [ej. Pytest] | Testing Python | [unittest] | [Fixtures, plugins, ecosistema] |
+| [ej. Sentry] | Error tracking | [Datadog, Rollbar] | [Plan gratuito suficiente, integración fácil] |
+
+---
+
+## Resumen de decisiones
+
+| Capa | Decisión | Confianza | ADR |
+|------|----------|-----------|-----|
+| Lenguaje backend | [tecnología] | Alta/Media/Baja | ADR-NNN |
+| Framework backend | [tecnología] | | ADR-NNN |
+| Base de datos | [tecnología] | | ADR-NNN |
+| Frontend | [tecnología] | | ADR-NNN |
+| Infraestructura | [tecnología] | | ADR-NNN |
+
+**Confianza global en el stack**: [Alta/Media] — [justificación de una línea]

package/plantillas/research/TRAMPAS.md

@@ -0,0 +1,299 @@
+# PITFALLS: Trampas y Anti-patrones — [Nombre del Proyecto]
+
+> Catálogo de errores comunes, anti-patrones del stack elegido y lecciones
+> aprendidas de proyectos anteriores. Leer ANTES de escribir código.
+> El objetivo es no repetir errores conocidos.
+> Autor: [nombre] | Fecha: YYYY-MM-DD
+
+---
+
+## Cómo usar este documento
+
+Antes de implementar cualquier feature, revisar si alguna trampa aplica
+a lo que se va a construir. Si se descubre una trampa nueva durante el desarrollo:
+documentarla aquí para que el siguiente desarrollador (o el agente) no caiga.
+
+Severidad:
+- CRÍTICO: Causa bugs silenciosos, pérdida de datos o vulnerabilidades de seguridad
+- ALTO: Causa errores en producción o degradación de performance
+- MEDIO: Causa deuda técnica o dificulta el mantenimiento
+- BAJO: Mejora de calidad o legibilidad
+
+---
+
+## Trampas de SQLAlchemy + Async
+
+### [CRÍTICO] MissingGreenlet: acceder a relaciones sin eager loading
+
+**Trampa**:
+```python
+# MALO — lanza MissingGreenlet en async
+facturas = await db.execute(select(Factura))
+for factura in facturas.scalars():
+    print(factura.cliente.nombre)  # acceso lazy en contexto async = error
+```
+
+**Solución**:
+```python
+# BIEN — eager loading explícito
+stmt = select(Factura).options(selectinload(Factura.cliente))
+facturas = await db.execute(stmt)
+```
+
+**Regla**: Todo atributo de relación accedido fuera del contexto de la query
+necesita `selectinload()` o `lazy="selectin"` en el modelo.
+
+---
+
+### [ALTO] N+1 queries en endpoints de listado
+
+**Trampa**: Un endpoint que devuelve 100 facturas con sus clientes genera
+101 queries: 1 para las facturas + 1 por cada cliente.
+
+**Cómo detectarlo**: Activar logging SQL y contar queries:
+```python
+# En desarrollo, en alembic.ini o en la config de SQLAlchemy:
+echo=True
+```
+
+**Solución**: `selectinload()` para todas las relaciones que se serializan.
+
+---
+
+### [CRÍTICO] db.commit() en services (no en endpoints)
+
+**Trampa**: El service hace `db.commit()` internamente. Si el endpoint necesita
+hacer dos operaciones en la misma transacción, la primera se commitea antes
+de que la segunda complete, dejando datos inconsistentes.
+
+**Regla**: Los services solo hacen `db.add()`, `db.flush()`, `db.refresh()`.
+El `db.commit()` SIEMPRE en el endpoint, después de que todas las operaciones
+del service completaron correctamente.
+
+---
+
+## Trampas de FastAPI
+
+### [ALTO] Rutas paramétricas antes de rutas estáticas
+
+**Trampa**:
+```python
+router.get("/{factura_id}")     # Esta ruta captura CUALQUIER string
+router.get("/exportar")          # NUNCA se alcanza — capturada por la anterior
+```
+
+**Solución**: Declarar rutas estáticas ANTES de las paramétricas:
+```python
+router.get("/exportar")          # Primero las específicas
+router.get("/{factura_id}")     # Luego las paramétricas
+```
+
+---
+
+### [CRÍTICO] IDOR: filtrar datos solo por query params sin verificar ownership
+
+**Trampa**:
+```python
+@router.get("/facturas")
+async def listar_facturas(empresa_id: UUID, db: AsyncSession = Depends(get_db)):
+    # PELIGRO: cualquier usuario puede ver facturas de cualquier empresa
+    return await db.execute(select(Factura).where(Factura.empresa_id == empresa_id))
+```
+
+**Solución**: El filtro de ownership SIEMPRE viene del JWT, nunca del cliente:
+```python
+@router.get("/facturas")
+async def listar_facturas(
+    db: AsyncSession = Depends(get_db),
+    usuario: Usuario = Depends(get_current_user)  # del JWT
+):
+    return await db.execute(
+        select(Factura).where(Factura.empresa_id == usuario.empresa_id)
+    )
+```
+
+---
+
+### [MEDIO] GET endpoints que modifican estado
+
+**Trampa**: Lógica de negocio que muta datos dentro de un handler GET.
+Viola el principio HTTP de idempotencia. Puede ejecutarse múltiples veces
+por bots, prefetch del navegador, etc.
+
+**Regla**: GET endpoints son read-only. Cualquier mutación va en POST/PUT/PATCH.
+
+---
+
+## Trampas de Pydantic v2
+
+### [ALTO] Usar `str` sin restricciones para campos con dominio cerrado
+
+**Trampa**:
+```python
+class FacturaCreate(BaseModel):
+    estatus: str  # Acepta cualquier string — "activo", "ACTIVO", "Activo", "xyz"
+```
+
+**Solución**: `Literal[]` o `Enum`:
+```python
+from typing import Literal
+class FacturaCreate(BaseModel):
+    estatus: Literal["borrador", "timbrada", "cancelada"]
+```
+
+Los valores DEBEN coincidir exactamente con el CheckConstraint en el modelo ORM.
+
+---
+
+### [ALTO] Optional[datetime] para columnas Time
+
+**Trampa**:
+```python
+hora_inicio: Optional[datetime]  # Incorrecto para columna Time de PostgreSQL
+```
+
+**Solución**:
+```python
+from datetime import time
+hora_inicio: Optional[time]
+```
+
+---
+
+## Trampas de Angular
+
+### [ALTO] No parsear PaginatedResponse — spinner infinito
+
+**Trampa**: El service Angular devuelve el objeto completo del endpoint paginado.
+El componente intenta hacer `.filter()` sobre el objeto en lugar del array.
+
+```typescript
+// MALO — getFacturas() devuelve Observable<PaginatedResponse<Factura>>
+this.facturas = this.facturasService.getFacturas();
+// El template hace @for (f of facturas) — pero facturas es un objeto, no array
+```
+
+**Solución**:
+```typescript
+// BIEN — el service extrae el array
+getFacturas(): Observable<Factura[]> {
+  return this.http.get<PaginatedResponse<Factura>>('/api/facturas')
+    .pipe(map(resp => resp.items));
+}
+```
+
+---
+
+### [MEDIO] Usar *ngIf / *ngFor en lugar de @if / @for
+
+**Trampa**: Angular 17+ usa la nueva sintaxis de control flow. Mezclar sintaxis
+genera inconsistencias y confusión.
+
+**Regla**: SIEMPRE `@if`, `@for`, `@switch`. NUNCA `*ngIf`, `*ngFor`, `*ngSwitch`.
+`@for` requiere `track`: `@for (item of items; track item.id)`.
+
+---
+
+### [ALTO] Funciones en templates que se evalúan en cada change detection cycle
+
+**Trampa**:
+```html
+<!-- MALO: calcularTotal() se llama en CADA ciclo de change detection -->
+<span>{{ calcularTotal(items) }}</span>
+```
+
+**Solución**:
+```typescript
+// BIEN: computed() se recalcula solo cuando cambian sus dependencias
+total = computed(() => this.items().reduce((s, i) => s + i.precio, 0));
+```
+```html
+<span>{{ total() }}</span>
+```
+
+---
+
+## Trampas de PostgreSQL
+
+### [CRÍTICO] NULL en cláusulas IN
+
+**Trampa**:
+```python
+# MALO: column.in_([valor, None]) NO matchea filas donde column IS NULL
+stmt.where(Factura.aprobador_id.in_([usuario_id, None]))
+```
+
+**Solución**:
+```python
+from sqlalchemy import or_
+stmt.where(or_(
+    Factura.aprobador_id == usuario_id,
+    Factura.aprobador_id.is_(None)
+))
+```
+
+---
+
+### [ALTO] Índices no usados por diferencia de tipos
+
+**Trampa**: Un índice en columna `VARCHAR` no se usa si la query compara con
+un valor `TEXT` o viceversa. PostgreSQL necesita hacer cast implícito.
+
+**Solución**: Asegurarse de que el tipo del valor en la query coincida con el
+tipo de la columna indexada. Verificar con `EXPLAIN ANALYZE`.
+
+---
+
+## Trampas de seguridad
+
+### [CRÍTICO] eval() o exec() con input del usuario
+
+Ya documentado en `reglas/seguridad.md`. La trampa más común:
+```python
+# CRÍTICO — permite ejecución arbitraria de código
+formula = request.json["formula"]
+resultado = eval(formula)  # XSS / RCE
+```
+
+### [CRÍTICO] Logging de datos sensibles
+
+**Trampa**:
+```python
+logger.info(f"Login exitoso para usuario {usuario.email}, token: {token}")
+# El token aparece en los logs — cualquiera con acceso a logs puede impersonar
+```
+
+**Regla**: NUNCA loggear tokens, passwords, números de tarjeta, CURP, RFC completo.
+
+---
+
+## Trampas de testing
+
+### [ALTO] Tests que dependen del orden de ejecución
+
+**Trampa**: Un test modifica estado global (BD, archivo, variable de módulo)
+y el siguiente test asume ese estado. Funciona en secuencia, falla en paralelo
+o cuando pytest cambia el orden.
+
+**Solución**: Cada test limpia su propio estado. Usar transacciones que se
+revierten en el teardown o fixtures aislados.
+
+---
+
+## Trampas descubiertas durante el desarrollo de ESTE proyecto
+
+[Sección vacía al inicio. Agregar aquí cualquier trampa específica que se
+descubra durante el desarrollo de este proyecto que no esté cubierta arriba.]
+
+### [SEVERIDAD] Título de la trampa descubierta
+
+**Contexto**: Dónde y cuándo se encontró.
+**Trampa**:
+```
+código que causó el problema
+```
+**Solución**:
+```
+código correcto
+```
+**Fecha**: YYYY-MM-DD | Descubierta por: [nombre]

package/plantillas/skill-evals-template.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "../schemas/skill-evals.schema.json",
+  "skill_name": "NOMBRE-DEL-SKILL",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para NOMBRE-DEL-SKILL — cubre casos normales, edge cases y anti-patrones.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Pregunta representativa del caso principal que esta skill resuelve. Debe ser autocontenida: el evaluador no debería necesitar contexto adicional más allá del skill cargado.",
+      "files": [],
+      "expected_output": "Descripción narrativa breve de cómo debería verse una respuesta correcta.",
+      "expectations": [
+        "La respuesta incluye la herramienta/comando canónico del skill (ej: usar `X` y no `Y`).",
+        "La respuesta menciona el flag/parámetro crítico que suele omitirse.",
+        "La respuesta explica la razón principal por la que se eligió esa ruta."
+      ],
+      "grading_guidance": "Aceptar variantes de comando equivalentes. Rechazar sustituciones (ej: si la skill prescribe `validate`, rechazar `check` o `lint`). No requerir redirecciones específicas de plataforma.",
+      "tags": ["primary-flow"]
+    },
+    {
+      "id": 1,
+      "prompt": "Caso de edge case — una configuración menos común o un input que suele confundir.",
+      "files": [],
+      "expectations": [
+        "La respuesta distingue entre los dos casos relevantes sin mezclarlos.",
+        "La respuesta cita el mecanismo específico que resuelve el edge case."
+      ],
+      "tags": ["edge-case"]
+    },
+    {
+      "id": "anti-pattern-substitution",
+      "prompt": "Prompt diseñado para inducir una sustitución común e incorrecta. El skill debe resistirla.",
+      "files": [],
+      "expectations": [
+        "La respuesta NO usa la herramienta/comando incorrecto [ESPECIFICAR].",
+        "La respuesta explica brevemente por qué esa sustitución no aplica."
+      ],
+      "grading_guidance": "Failure si aparece el patrón prohibido, aunque el resto de la respuesta sea correcto.",
+      "tags": ["anti-pattern", "regression"],
+      "weight": 1.5
+    }
+  ]
+}