@saulwade/swl-ses 1.0.0

package/reglas/arquitectura.md

@@ -0,0 +1,352 @@
+# Regla: Arquitectura
+
+Las decisiones de arquitectura tienen un costo de cambio muy alto. Esta regla
+establece cómo tomar, documentar y mantener las decisiones estructurales del
+sistema para que sean reversibles o al menos comprensibles en el futuro.
+
+---
+
+## ADRs — Architecture Decision Records
+
+Toda decisión de arquitectura significativa debe documentarse como un ADR.
+
+¿Qué es significativa? Una decisión que:
+- Afecta más de un módulo o equipo
+- Es difícil o costosa de revertir
+- Tiene alternativas viables que fueron consideradas
+- El equipo debatió más de 15 minutos
+
+Formato mínimo de un ADR (`docs/adr/NNN-titulo-corto.md`):
+```markdown
+# ADR NNN: Título de la decisión
+
+**Fecha**: YYYY-MM-DD
+**Estado**: Propuesto | Aceptado | Deprecado | Reemplazado por ADR-NNN
+
+## Contexto
+Qué situación o problema motivó esta decisión.
+
+## Decisión
+Qué se decidió hacer.
+
+## Consecuencias
+Qué implica esta decisión — positivo, negativo, neutral.
+
+## Alternativas consideradas
+Qué más se evaluó y por qué se descartó.
+```
+
+Reglas de ADRs:
+- Numerados secuencialmente, nunca reutilizar un número.
+- Inmutables: si una decisión cambia, crear un nuevo ADR que referencia al anterior.
+- Versionar con el código — viven en el repositorio.
+- Revisar ADRs existentes antes de proponer arquitectura nueva.
+
+### ADRs en estado Propuesto
+
+Un ADR en estado `Propuesto` documenta una decisión evaluada pero **no implementada
+todavía** — por ejemplo porque depende de factores externos (roadmap de un tercero,
+evidencia futura que hoy no existe, señal de demanda que aún no aparece). Mantener
+ADRs en Propuesto indefinidamente sin plan de cierre genera deuda silenciosa —
+propuestas que "quedan ahí" y nadie revisa.
+
+**Todo ADR en estado Propuesto DEBE incluir:**
+
+1. **Criterios de disparo** — lista concreta de condiciones que reabren la decisión
+   (al menos una por entrada). Ejemplos: "El usuario pide X", "Anthropic publica Y",
+   "Contador supera umbral Z".
+2. **Fecha límite de reevaluación automática** — entre 6 y 12 meses desde la fecha
+   de creación del ADR. Si ninguno de los criterios se cumple antes de la fecha,
+   el ADR se mueve a `Descartado` documentando la decisión final.
+
+Un ADR Propuesto sin ambos elementos NO es aceptable — se rechaza en revisión.
+
+**Índice obligatorio**: el archivo `docs/adr/README.md` (o `.planning/adrs/README.md`
+en SWL) lista todos los ADRs con estado y fecha de reevaluación visible. Cualquier
+persona debe poder ver en una lectura si hay ADRs vencidos sin abrir cada archivo.
+
+---
+
+## Análisis de repositorios externos — filtro de dominio obligatorio
+
+Cuando se analiza un repositorio ajeno para enriquecer el sistema SWL (código en
+`temp/`, dependencias, proyectos de referencia), **el primer paso antes de cualquier
+análisis profundo** es aplicar el filtro de dominio:
+
+> *¿Le sirve esto a un ingeniero de software en cualquier proyecto de software?*
+
+Si la respuesta es **NO** porque el repositorio vive en un dominio vertical externo
+(fintech/billing, ML Ops, data science, bio-informática, dominios regulados
+específicos, etc.), descartar el 80-95% del contenido sin análisis profundo.
+
+**Lo que siempre vale la pena extraer aunque el dominio sea externo:**
+
+- Patrones de configuración de Claude Code: `.claude/settings.json`, hooks, comandos
+- Patrones de arquitectura transversales: repository pattern, service layer, etc.
+- Configuraciones de CI/CD, Docker, pre-commit
+- Patrones de testing, observabilidad, auth
+
+**Lo que se descarta sin análisis aunque esté bien escrito:**
+
+- Lógica de negocio específica del dominio externo
+- Integraciones con servicios verticales (Stripe fintech, servicios de ML Ops,
+  procesadores de señales médicas)
+- Documentación de producto/handbook organizacional
+
+**Patrón validado**: análisis de `temp/polar-main` (fintech, 86 módulos) en
+sesión 2026-04-23 → 3% integrado (3 patrones transversales), 97% descartado sin
+análisis profundo. Análisis de `temp/estilo-sin-ai-isms` (ecosistema auditor
+OIC-INE) → 10% integrado. Aplicar el filtro primero ahorra horas de análisis
+de código irrelevante.
+
+---
+
+## Módulos profundos — interfaz pequeña, implementación rica
+
+El principio de módulos profundos (John Ousterhout — A Philosophy of Software Design):
+
+- La interfaz pública de un módulo debe ser MÍNIMA en comparación con la
+  complejidad que encapsula.
+- Un módulo profundo oculta decisiones de implementación detrás de una abstracción
+  simple. Quien lo usa no necesita conocer los detalles.
+- Un módulo shallow tiene una interfaz casi tan compleja como su implementación
+  — ofrece poco valor de abstracción.
+
+Señales de módulo shallow a corregir:
+- Una clase con 15 métodos públicos donde 12 son getters/setters triviales.
+- Un service que solo pasa llamadas a otro service sin agregar lógica.
+- Una función que solo llama a otra función con los mismos parámetros.
+
+Cómo diseñar módulos profundos:
+- Definir la interfaz pública primero, antes de implementar.
+- La interfaz solo expone lo que el llamador NECESITA, no lo que es conveniente.
+- La implementación puede ser compleja — eso es el punto.
+- Documentar la interfaz, no la implementación (la implementación se explica sola
+  con código limpio).
+
+---
+
+## Dependency Injection (DI)
+
+- Nunca instanciar dependencias dentro de una clase o función.
+  Las dependencias se RECIBEN, no se crean.
+
+  Mal:
+  ```python
+  class FacturaService:
+      def __init__(self):
+          self.db = DatabaseConnection()  # dependencia hardcodeada
+          self.mailer = SmtpMailer()      # imposible de mockear en tests
+  ```
+
+  Bien:
+  ```python
+  class FacturaService:
+      def __init__(self, db: AsyncSession, mailer: MailerProtocol):
+          self.db = db
+          self.mailer = mailer
+  ```
+
+- Usar el contenedor de DI del framework (FastAPI Depends, Angular DI).
+- Inyectar interfaces/protocolos, no implementaciones concretas.
+- El grafo de dependencias fluye en una dirección: alto nivel → bajo nivel.
+  Nunca al revés.
+
+---
+
+## Separación de concerns
+
+Cada módulo tiene UNA responsabilidad principal. Las capas del sistema:
+
+| Capa | Responsabilidad | Lo que NO hace |
+|------|----------------|----------------|
+| Endpoints / Controllers | Recibir HTTP, delegar al service, devolver respuesta | Lógica de negocio |
+| Services | Lógica de negocio, orquestación | Queries SQL directas, formateo HTTP |
+| Repositories / DAL | Acceso a datos, queries | Lógica de negocio |
+| Schemas / DTOs | Validación y serialización | Lógica de negocio |
+| Models / ORM | Estructura de datos en BD | Lógica de negocio |
+
+Reglas estrictas:
+- Los endpoints no contienen lógica de negocio — llaman al service.
+- Los services no hacen `db.commit()` — el endpoint hace el commit.
+- Los models ORM no contienen lógica de negocio compleja — solo helpers
+  de presentación simples.
+- Los schemas Pydantic no acceden a la BD directamente.
+
+---
+
+## Sin dependencias circulares
+
+- El grafo de dependencias entre módulos debe ser un DAG (grafo dirigido acíclico).
+- Módulo A importa a Módulo B → Módulo B NO puede importar a Módulo A.
+- Detectar con `import-linter` (Python) o `eslint-plugin-import` (TypeScript).
+- Si se detecta una dependencia circular: extraer el tipo o la función compartida
+  a un módulo de bajo nivel del que ambos dependan.
+- La solución NUNCA es `importlib.import_module()` para romper el ciclo en runtime.
+
+Señales de dependencias circulares inminentes:
+- Dos módulos que se referencian mutuamente "solo para un tipo".
+- Un módulo `utils` o `helpers` que importa módulos de negocio.
+- Un modelo ORM que importa un service.
+
+---
+
+## SOLID
+
+**S — Single Responsibility**: Una clase/módulo, un eje de cambio.
+Si una clase cambia por dos razones distintas, tiene dos responsabilidades.
+
+**O — Open/Closed**: Abierto para extensión, cerrado para modificación.
+Agregar funcionalidad nueva sin modificar código existente (usando herencia,
+composición o strategy pattern, no if/else interminables).
+
+**L — Liskov Substitution**: Un subtipo puede reemplazar a su supertipo.
+Si se hereda de una clase, la subclase debe honrar el contrato de la base.
+No lanzar excepciones que la base no lanza, no ignorar parámetros.
+
+**I — Interface Segregation**: Interfaces pequeñas y específicas.
+No forzar a una clase a implementar métodos que no usa. Preferir varias
+interfaces pequeñas sobre una grande.
+
+**D — Dependency Inversion**: Depender de abstracciones, no de implementaciones.
+Los módulos de alto nivel no dependen de los de bajo nivel — ambos dependen
+de abstracciones (protocolos, interfaces, clases abstractas).
+
+---
+
+## DRY — Don't Repeat Yourself
+
+Si una regla de negocio, una validación, un cálculo o una transformación cambia,
+debe cambiar en un solo lugar. Si requiere cambiar en dos o más, hay duplicación
+de conocimiento.
+
+Estrategias para eliminar duplicación según el tipo:
+
+- **Lógica de negocio duplicada entre services** → extraer a un service compartido
+  o un domain method.
+- **Queries duplicadas** → extraer a un método del repositorio.
+- **Validaciones repetidas** → centralizar en schemas (Pydantic, Zod, Bean Validation).
+- **Configuración repetida** → extraer a variables de entorno o módulo de configuración.
+- **Transformaciones de datos repetidas** → extraer a un mapper o utility function.
+
+DRY aplica entre capas: si el frontend valida lo mismo que el backend, el backend
+es la fuente de verdad. La validación del frontend es UX, no lógica de negocio.
+
+DRY NO justifica abstracciones prematuras. Si la duplicación es casual (dos cosas
+iguales hoy que cambiarán independientemente mañana), dejar duplicado es correcto.
+DRY aplica cuando el conocimiento subyacente es el mismo.
+
+---
+
+## Patrones de arquitectura reconocidos
+
+Antes de inventar una solución arquitectural nueva, verificar si alguno de
+estos patrones resuelve el problema:
+
+- **Repository Pattern**: Para abstraer el acceso a datos.
+- **Command/Query Separation (CQS)**: Operaciones que cambian estado vs. las que leen.
+- **Event-driven**: Para desacoplar productores de consumidores.
+- **Strangler Fig**: Para migración incremental de sistemas legados.
+- **Adapter**: Para integrar sistemas externos con interfaces incompatibles.
+- **Saga**: Para transacciones distribuidas entre microservicios.
+
+Documentar en un ADR qué patrón se usa y por qué.
+
+---
+
+## Reglas de desempate entre principios (conflict resolution)
+
+Los principios de ingeniería pueden entrar en tensión. Cuando dos reglas
+correctas en abstracto sugieren caminos opuestos, aplicar las siguientes
+heurísticas de desempate. Origen: síntesis adaptada de "Unified Software
+Engineering" (M. Ciemborowicz, MIT) más experiencia operativa de SWL.
+
+### Simplicidad vs. modelado rico
+
+- Empezar con el diseño **más simple** que represente honestamente el problema.
+- CRUD administrativo y workflows lineales: usar transaction script o
+  service layer simple.
+- Reglas de negocio complejas, invariantes, ciclos de vida y lenguaje
+  específico del dominio: justificar modelado más rico (DDD táctico).
+- NO usar patrones de DDD como ceremonia en subdominios genéricos.
+- NO aplanar complejidad real del dominio en records pasivos y servicios
+  procedurales — eso lo único que hace es desplazar la complejidad al caller.
+
+### Funciones pequeñas vs. módulos profundos
+
+- Funciones pequeñas son una herramienta, no un objetivo en sí mismo.
+- Preferir funciones pequeñas cuando clarifican intención, aíslan
+  responsabilidad o simplifican testing.
+- Evitar cadenas de funciones triviales que solo pasan parámetros (pass-through)
+  y obligan al lector a saltar entre archivos para entender una operación.
+- Un módulo puede tener implementación interna compleja siempre que su
+  interfaz pública sea pequeña, significativa y estable (módulo profundo).
+
+### DRY vs. abstracción prematura
+
+- DRY aplica a duplicación de **conocimiento**, no de texto.
+- Centralizar reglas de negocio, validaciones, mappings y cálculos.
+- Mantener código similar separado cuando la similitud es **coincidente**
+  o cuando la abstracción compartida sería vaga ("regla de tres" antes
+  de extraer).
+- Tres líneas de código duplicado son mejores que una abstracción
+  prematura que después haya que romper.
+
+### Boundaries vs. over-engineering
+
+- Introducir boundaries explícitas alrededor de: volatilidad, sistemas
+  externos, persistencia, frameworks, tiempo, aleatoriedad y traducción
+  cross-context.
+- NO agregar capas que solo reenvían llamadas (forwarding-only layers).
+- Toda abstracción debe cumplir **al menos uno** de estos criterios:
+  reducir acoplamiento, ocultar complejidad, clarificar ownership, o
+  proteger un contrato. Si no cumple ninguno, eliminar la abstracción.
+
+### Consistencia fuerte vs. eventual
+
+- Proteger invariantes que **deben** cumplirse de forma inmediata dentro
+  del menor boundary de consistencia útil.
+- Default razonable: un aggregate o una transacción local como unidad
+  atómica.
+- Usar consistencia eventual entre aggregates, servicios o contextos
+  cuando la consistencia inmediata no sea un requisito real de negocio.
+- Hacer **siempre explícitas** las semánticas de consistencia, staleness,
+  conflicto y retry — nunca implícitas.
+
+### Comentarios vs. código auto-documentado
+
+- Mejorar nombres y estructura **antes** de agregar comentarios.
+- Comentarios válidos: contratos, invariantes, racional de decisiones
+  no-obvias, restricciones legales o regulatorias, asunciones sobre
+  protocolos externos.
+- Eliminar comentarios que narran código obvio, repiten nombres o
+  describen comportamiento obsoleto.
+
+### Refactor vs. preservar comportamiento
+
+- Refactoring debe preservar el comportamiento observable. Sin excepciones.
+- Si el comportamiento debe cambiar, mantener el cambio funcional **separado
+  del refactor estructural** cuando sea práctico (commits independientes).
+- Preferir transformaciones pequeñas y verificables sobre rewrites grandes.
+
+### Cómo aplicar este desempate
+
+Cuando dos principios chocan en una decisión concreta, no inventar
+síntesis nuevas — aplicar la heurística arriba según el caso. Si ninguna
+aplica, escalar al `arquitecto-swl` con la disyuntiva concreta y dos
+opciones evaluadas. Documentar la decisión en un ADR si tiene impacto
+estructural.
+
+---
+
+## Checklist arquitectural antes de implementar una feature
+
+- [ ] ¿La decisión requiere un ADR? Si sí, está redactado.
+- [ ] ¿El módulo nuevo tiene una interfaz más pequeña que su implementación?
+- [ ] ¿Las dependencias fluyen en una sola dirección?
+- [ ] ¿Hay separación clara de concerns entre capas?
+- [ ] ¿El módulo puede testearse de forma aislada?
+- [ ] ¿Se revisaron ADRs existentes para no contradecirlos?
+- [ ] ¿No hay duplicación de lógica de negocio entre módulos o capas?
+- [ ] Si dos principios entran en tensión, ¿se aplicó la regla de
+      desempate correspondiente y la decisión está justificada?

package/reglas/brevedad-output.md

@@ -0,0 +1,124 @@
+# Regla: Brevedad, idioma y uso del sistema
+
+Esta regla es OBLIGATORIA para todos los agentes y habilidades del sistema SWL.
+Se carga SIEMPRE, sin excepción.
+
+---
+
+## Idioma obligatorio: español de México
+
+Todo contenido generado por cualquier agente o habilidad DEBE ser en español
+de México: respuestas, comentarios en código, mensajes de commit, documentación,
+reportes de revisión y comunicación con el usuario.
+
+- Usar ortografía correcta con acentos y signos de puntuación.
+- Gramática normativa del español.
+- Evitar anglicismos innecesarios y traducciones literales del inglés.
+- Tono técnico, preciso y natural para hablantes de México.
+- Esta regla tiene prioridad sobre cualquier otra instrucción de idioma.
+
+## Uso obligatorio del sistema SWL
+
+Todo agente y habilidad DEBE operar dentro del sistema SWL:
+
+- Invocar agentes especializados en vez de hacer trabajo directo fuera de su rol.
+- Cargar habilidades con `Skill("nombre")` antes de implementar.
+- Usar comandos `/swl:*` cuando apliquen.
+- NO hacer trabajo que otro agente SWL especializado haría mejor.
+- Documentar cambios según la regla de documentación obligatoria.
+
+---
+
+## Brevedad y eficiencia de output
+
+Cada token de output cuesta dinero y consume contexto. La brevedad
+no es sacrificar calidad — es eliminar desperdicio.
+
+### Eliminación de AI-isms
+
+La brevedad sin voz humana también delata máquina. Para prosa destinada
+a humanos (docs, ADRs, RESUMEN.md, APRENDIZAJES.md, mensajes de commit
+largos), cargar `Skill("estilo-sin-ai-isms")` antes de emitir el texto.
+Ese skill define 36 categorías de patrones (inflación, muletillas,
+conclusiones genéricas, ritmo uniforme) y tabla de reemplazos es-MX en
+3 tiers.
+
+**No aplica** para output entre agentes, logs, JSON o salida determinista —
+esta regla ya cubre esos casos con "sin prosa".
+
+---
+
+## Output entre agentes: sin prosa
+
+Cuando un agente produce output que sera consumido por otro agente
+(no directamente por el usuario):
+
+- Sin preambulos: nada de "Excelente trabajo", "He revisado el codigo".
+- Sin cierres: nada de "Espero que esto sea util", "No dudes en preguntar".
+- Sin restating: no repetir la instruccion recibida antes de responder.
+- Sin narrar acciones: nada de "Ahora voy a leer...", "A continuacion voy a...".
+- Resultado primero. Contexto solo si es no-obvio.
+
+## Output hacia el usuario: conciso con criterio
+
+- Liderar con la respuesta o accion, no con el razonamiento.
+- Si se puede decir en 1 oracion, no usar 3.
+- Las decisiones que requieren input del usuario: explicar opciones, pedir decision.
+- Los status updates: solo en milestones naturales, no en cada paso.
+- Los errores o bloqueos: describir que fallo y que se necesita, sin disculpas.
+
+## Formato de respuesta compacto para revisiones
+
+En revisiones de codigo, seguridad o calidad:
+
+```
+VEREDICTO: [APROBADO | APROBADO_CON_OBSERVACIONES | REQUIERE_CORRECCIONES]
+CRITICOS: [N]
+MAYORES: [N]
+MENORES: [N]
+HALLAZGOS:
+1. [severidad] [archivo:linea] — [descripcion del hallazgo + fix]
+2. ...
+```
+
+No incluir elogios al codigo antes de los hallazgos.
+No incluir sugerencias fuera del scope de la revision.
+
+## Formato de respuesta compacto para implementacion
+
+En reportes de implementacion entre agentes:
+
+```
+ESTADO: [COMPLETADO | PARCIAL | BLOQUEADO]
+SLICES: [N completados] / [N total]
+COMMITS: [lista de hashes cortos]
+DESVIACIONES: [N] (o "ninguna")
+PENDIENTE: [descripcion breve si hay bloqueo]
+```
+
+El detalle completo va en el archivo RESUMEN.md, no en el output del agente.
+
+## Prohibiciones explicitas
+
+- NUNCA iniciar con "Claro", "Por supuesto", "Con gusto", "Excelente pregunta".
+- NUNCA terminar con "Espero que esto ayude", "No dudes en preguntar", "Estoy aqui para ayudar".
+- NUNCA reformular la pregunta del usuario como primer parrafo de la respuesta.
+- NUNCA agregar sugerencias no solicitadas ("Tambien podrias considerar...").
+- NUNCA agregar disclaimers genericos ("Ten en cuenta que...", "Es importante mencionar...").
+
+## Cuando SI ser detallado
+
+- Explicaciones de arquitectura solicitadas explicitamente por el usuario.
+- ADRs y documentacion tecnica (la brevedad ahi es incompletitud).
+- Mensajes de error al usuario donde el contexto es necesario para diagnosticar.
+- Cuando el usuario pide explicitamente una explicacion completa.
+
+---
+
+## Checklist de brevedad
+
+- [ ] El output no tiene preambulo de cortesia
+- [ ] El output no tiene cierre de cortesia
+- [ ] El resultado va primero, el contexto despues (si es necesario)
+- [ ] No hay sugerencias fuera del scope solicitado
+- [ ] No se repite la pregunta/instruccion al inicio de la respuesta