@saulwade/swl-ses 2.4.3 → 2.5.1

package/habilidades/meta-reglas-extendido/recursos/arquitectura.md

@@ -0,0 +1,491 @@
+# Arquitectura — extendido
+
+> Extendido de `reglas/arquitectura.md` (Fase D, dieta de contexto). El núcleo
+> instalado es la norma; aquí viven templates, ejemplos y casos completos.
+
+## Índice
+
+- [ADRs — Architecture Decision Records](#adrs--architecture-decision-records)
+- [Análisis de repositorios externos — filtro de dominio obligatorio](#análisis-de-repositorios-externos--filtro-de-dominio-obligatorio)
+- [Módulos profundos — interfaz pequeña, implementación rica](#módulos-profundos--interfaz-pequeña-implementación-rica)
+- [Dependency Injection (DI)](#dependency-injection-di)
+- [Separación de concerns](#separación-de-concerns)
+- [Sin dependencias circulares](#sin-dependencias-circulares)
+- [SOLID](#solid)
+- [Tres capas de reutilización: regla, skill, fragmento](#tres-capas-de-reutilización-regla-skill-fragmento)
+- [DRY — Don't Repeat Yourself](#dry--dont-repeat-yourself)
+- [Patrones de arquitectura reconocidos](#patrones-de-arquitectura-reconocidos)
+- [Tablas append-only — excepción documentada a "audit columns nullable=False"](#tablas-append-only--excepción-documentada-a-audit-columns-nullablefalse)
+- [Split modular con compositor por herencia múltiple](#split-modular-con-compositor-por-herencia-múltiple)
+- [Reglas de desempate entre principios (conflict resolution)](#reglas-de-desempate-entre-principios-conflict-resolution)
+- [Checklist arquitectural antes de implementar una feature](#checklist-arquitectural-antes-de-implementar-una-feature)
+
+---
+
+## 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).
+
+---
+
+## Tres capas de reutilización: regla, skill, fragmento
+
+El sistema SWL distingue tres capas para evitar duplicación. La elección de la
+capa correcta depende de cuándo y cómo se carga el contenido:
+
+- **Regla** (`reglas/X.md`): política global cargada por matcher de archivos.
+  Aplicable a múltiples agentes y skills. Ejemplo: `reglas/seguridad.md`.
+- **Skill** (`habilidades/X/SKILL.md`): conocimiento operacional invocado
+  dinámicamente con `Skill("X")`. Tiene frontmatter, descripción y carga
+  bajo demanda. Ejemplo: `habilidades/tdd-workflow/SKILL.md`.
+- **Fragmento** (`agentes/_X.md`): bloque de prompt compartido por varios
+  agentes que se incrusta literalmente en su system prompt. Sin overhead
+  runtime, sin frontmatter operacional, no routable por el orquestador.
+  Ejemplo: `agentes/_hitl-alto-riesgo.md`.
+
+Antes de crear texto compartido entre agentes, decidir cuál capa aplica. Ver
+`reglas/fragmentos-compartidos.md` para la convención completa.
+
+---
+
+## 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é.
+
+---
+
+## Tablas append-only — excepción documentada a "audit columns nullable=False"
+
+Algunas tablas son **append-only por diseño**: solo se crean filas (INSERT) y
+eventualmente se eliminan por purga (DELETE). Nunca se actualizan. Ejemplos
+típicos: logs de errores (`bitacora_error`, `error_log`), audit trails inmutables,
+telemetría, métricas históricas, event sourcing event store, outbox pattern.
+
+Para estas tablas la regla general del proyecto "`created_by`/`updated_by`
+`nullable=False` en tablas transaccionales" **NO aplica**. Documentar la
+excepción explícitamente:
+
+1. En el **docstring de la clase modelo** (Python/Java/C#):
+
+```python
+class BitacoraError(Base):
+    """
+    Registro inmutable de un error backend o frontend.
+
+    Tabla append-only: solo se crean filas (INSERT) y se purgan por antigüedad
+    (DELETE). Nunca se actualizan. Esta invariante es fundamental para que el
+    log de errores sea un audit trail confiable.
+
+    Excepción a regla "audit columns nullable=False":
+        La convención del proyecto exige `created_by` y `updated_by` NOT NULL
+        en tablas transaccionales. BitacoraError queda exenta porque:
+        (a) Es un log del sistema, no una entidad de negocio modificable.
+        (b) No tiene `updated_at` ni `updated_by` — no hay concepto de
+            "última modificación" en una tabla append-only.
+        (c) `usuario_id` es nullable de forma intencional: los errores de
+            sesiones no autenticadas (401 antes del login) no tienen usuario.
+    """
+```
+
+2. En el **comentario del DDL SQL**:
+
+```sql
+COMMENT ON TABLE bitacora_error IS
+    'Errores backend y frontend persistidos para diagnóstico. '
+    'Append-only: solo INSERT y DELETE (purga). '
+    'Sin updated_at/updated_by por diseño (excepción documentada en CONTEXTO).';
+```
+
+3. En el **GRANT** del rol de aplicación, omitir explícitamente `UPDATE`:
+
+```sql
+-- INSERT: para que el sistema cree entradas.
+-- SELECT: para que el admin las consulte.
+-- DELETE: para que el job de purga elimine antiguas.
+-- NO UPDATE: la tabla es append-only por diseño.
+GRANT SELECT, INSERT, DELETE ON bitacora_error TO ine_user;
+```
+
+**Criterios para considerar una tabla append-only legítima**:
+
+- Toda fila representa un evento ocurrido en un momento específico (immutable in time).
+- No hay caso de negocio que requiera modificar la fila después de creada.
+- La única forma de "corregir" un dato erróneo es insertar una fila correctora
+  posterior (event sourcing) o purgar y re-insertar (telemetría).
+- El borrado se hace por política de retención (antigüedad), no por revocación.
+
+**Origen del patrón**: OIC v1.5 Slice 1 (2026-06-04). Patrón portable a cualquier
+proyecto con logs estructurados, audit trails o event sourcing.
+
+---
+
+## Split modular con compositor por herencia múltiple
+
+Cuando un módulo backend (router, service, repository) supera ~1500 LOC en un
+solo archivo y contiene sub-dominios identificables, aplicar el playbook de
+split documentado en `Skill("proceso-modular-split")`. El patrón clave:
+
+- **Compositor por herencia múltiple, NO `__getattr__`**: el compositor (clase
+  monolítica que mantiene API pública previa) hereda de cada sub-service. MRO
+  inspeccionable, type checker feliz, IDE autocompleta. `__getattr__` para
+  delegación es opaco al tipado y al stack trace.
+
+- **Helpers transversales en clase base, no duplicados entre sub-services**: si
+  un helper como `_validar_predio_existe` lo usan ≥80% de sub-services, vive
+  en `<modulo>/service_base.py` (`<Modulo>ServiceBase`). Cada sub-service
+  hereda de la base. Si solo lo usan 1-2 sub-services, vive en uno de ellos y
+  los demás importan por composición (no por herencia).
+
+- **Helper transversal cross-sub-service NO se duplica**: validación que
+  aparece en ≥3 sub-services es candidata inmediata a la clase base. La
+  duplicación es señal de que el split fue prematuro o de que se perdió el
+  helper común durante la migración.
+
+- **Validar a escala**: el patrón se validó a ~20,000 LOC totales en SIGM
+  (recaudación ADR-0016 + catastro ADR-0017). Aplicar al primer módulo es
+  prudente; antes de aplicar a un tercero, confirmar que el feedback de los
+  dos primeros no requiere ajuste al playbook.
+
+Anti-patrones a evitar (las auditorías técnicas NO los detectan):
+
+- Router que importa el compositor cuando existe sub-service específico.
+- Router que accede a `servicio._repo` o métodos privados del sub-service.
+- Default `None` pasado explícitamente bypasea el default del callee.
+- CLAUDE.md y AGENTS.md desincronizados tras el refactor.
+
+Estos los detecta revisión de arquitectura humana o senior, no `nemesis-auditor-swl`.
+
+---
+
+## 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?