@saulwade/swl-ses 2.4.2 → 2.5.1

package/reglas/arquitectura.md

@@ -1,475 +1,54 @@
 # 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.
-
----
+Las decisiones de arquitectura tienen un costo de cambio muy alto. Núcleo denso de
+cómo tomar, documentar y mantener las decisiones estructurales del sistema.
 
 ## 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
+- Toda decisión significativa (afecta >1 módulo/equipo, difícil de revertir, tuvo alternativas viables consideradas, o se debatió >15 min) se documenta como ADR en `docs/adr/NNN-titulo-corto.md` — formato mínimo (Contexto / Decisión / Consecuencias / Alternativas) en el extendido.
+- Numerados secuencialmente, nunca reutilizar un número; inmutables (si la decisión cambia, ADR nuevo que referencia al anterior); versionados con el código; revisar ADRs existentes antes de proponer arquitectura nueva.
+- Todo ADR en estado `Propuesto` EXIGE: criterios de disparo concretos (condiciones observables que reabren la decisión) + fecha límite de reevaluación entre 6 y 12 meses. Sin ambos, se rechaza en revisión; vencido sin disparo → `Descartado`.
+- Índice obligatorio en `docs/adr/README.md` (o `.planning/adrs/README.md` en SWL) con estado y fecha de reevaluación visibles de una lectura.
 
-El principio de módulos profundos (John Ousterhout — A Philosophy of Software Design):
+## Principios de diseño
 
-- 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.
+- **Módulos profundos** (Ousterhout): interfaz pública MÍNIMA frente a la complejidad que encapsula; exponer solo lo que el llamador NECESITA — la implementación puede ser compleja, ese es el punto.
+- **Dependency Injection**: las dependencias se RECIBEN, no se crean dentro de la clase/función; inyectar interfaces/protocolos vía el contenedor del framework. El grafo de dependencias fluye alto nivel → bajo nivel, nunca al revés.
+- **Sin dependencias circulares**: el grafo de módulos debe ser un DAG; ante un ciclo, extraer lo compartido a un módulo de bajo nivel del que ambos dependan. NUNCA `importlib.import_module()` para romper el ciclo en runtime.
+- **DRY**: duplicación de conocimiento, no de texto — si un cambio obliga a cambiar dos lugares, hay duplicación. Regla de tres antes de abstraer; DRY no justifica abstracciones prematuras.
 
-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:
+## Separación de concerns (una responsabilidad por capa)
 
 | 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 |
+|---|---|---|
+| Endpoints / Controllers | Recibir HTTP, delegar al service, responder | Lógica de negocio |
+| Services | Lógica de negocio, orquestación | SQL directo, formateo HTTP, `db.commit()` (lo hace el endpoint) |
 | 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.
-
----
+| Schemas / DTOs | Validación y serialización | Lógica de negocio, acceso directo a BD |
+| Models / ORM | Estructura de datos en BD | Lógica de negocio compleja |
 
 ## 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.
+- **S**: una clase/módulo, un eje de cambio.
+- **O**: extender sin modificar (composición/strategy, no if/else interminables).
+- **L**: el subtipo honra el contrato del supertipo — sin excepciones nuevas ni parámetros ignorados.
+- **I**: varias interfaces pequeñas antes que una grande; no forzar métodos sin uso.
+- **D**: depender de abstracciones, no de implementaciones concretas.
 
-### Cómo aplicar este desempate
+## Repos externos y tablas append-only
 
-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.
+- Análisis de repositorios externos: aplicar el filtro de dominio PRIMERO (*¿le sirve a un ingeniero de software en cualquier proyecto?*); si el dominio es vertical externo, descartar 80-95% del contenido sin análisis profundo.
+- Tablas append-only (logs, audit trails, telemetría, event store): excepción documentada a "audit columns `nullable=False`" — documentar en docstring del modelo + `COMMENT` del DDL + GRANT sin `UPDATE`.
 
----
+## Desempates entre principios
 
-## Checklist arquitectural antes de implementar una feature
+- Simplicidad vs. modelado rico → empezar con lo más simple que represente honestamente el problema; DDD táctico solo ante reglas de negocio complejas reales, nunca como ceremonia.
+- Funciones pequeñas vs. módulos profundos → funciones pequeñas son herramienta, no meta; evitar cadenas pass-through que solo pasan parámetros.
+- DRY vs. abstracción prematura → centralizar conocimiento; tres líneas duplicadas ganan a una abstracción que habrá que romper.
+- Boundaries vs. over-engineering → un boundary solo si reduce acoplamiento, oculta complejidad, clarifica ownership o protege un contrato; sin capas forwarding-only.
+- Consistencia fuerte vs. eventual → fuerte dentro del menor boundary útil (aggregate/transacción local); eventual entre aggregates; semánticas siempre explícitas.
+- Comentarios vs. código auto-documentado → mejorar nombres/estructura antes de comentar; comentarios solo para contratos, invariantes y racional no obvio.
+- Refactor vs. preservar comportamiento → el refactor preserva el comportamiento observable sin excepciones; el cambio funcional va separado del estructural.
+- Si ninguna heurística aplica: escalar a `arquitecto-swl` con dos opciones evaluadas; documentar en ADR si hay impacto estructural.
 
-- [ ] ¿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?
+Detalle extendido (template ADR, ejemplos de código, split modular con compositor, checklists): `Skill("meta-reglas-extendido")` → `recursos/arquitectura.md`.