@saulwade/swl-ses 1.6.3 → 1.6.6

package/habilidades/postgresql-experto/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: postgresql-experto
 description: PostgreSQL avanzado. JSONB, arrays, tipos personalizados, búsqueda de texto completo, window functions, CTEs recursivos, Row Level Security y funciones almacenadas.
-version: "1.1.0"
+version: "1.2.0"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-05-05"
+evolved-from: "1.1.0"
+evolved-at: "2026-05-20"
 evolved-by: "aprender"
-evolved-note: "3 gotchas nuevos de la sesión SIGM 2026-05-05: RLS bypass por superusuarios, UUIDs hex en seeds, consultar enum_range antes de seedear (L2/L4/L8)"
+evolved-note: "4 gotchas nuevos consolidados SIGM L-152/L-153/L-156 + SIGAF 2026-05-15: race condition SELECT-then-write fuera de transaction (CONFIRMADO x4), UPDATE WHERE col1 sin dimensiones de scoping, drift triple Literal↔validator↔ENUM, partial unique index con WHERE requiere predicado puro (no subqueries)"
 herramientasPermitidas: [Read, Grep]
 exclusiones:
   - "No cargar para optimización de queries SQL (EXPLAIN ANALYZE, índices, partitioning) — para optimización cargar `sql-optimizacion`."
@@ -172,3 +172,79 @@ Si el valor que necesitas no existe, agregar la variante con `ALTER TYPE ... ADD
 **`FORCE ROW LEVEL SECURITY` no protege al usuario dueño de la tabla (superuser/owner)**: el propietario de la tabla y los superusuarios de PostgreSQL bypasean RLS por defecto aunque esté `FORCE` habilitado. Causa: `FORCE` aplica a todos los usuarios excepto al dueño de la tabla y a superusuarios. Fix: si la aplicación conecta como el dueño de la tabla, cambiar el rol de conexión a un rol de aplicación sin privilegios de dueño (`GRANT CONNECT ON DATABASE ... TO app_user`), no usar el usuario `postgres` para conexiones de aplicación.
 
 **`tsvector` `GENERATED ALWAYS AS STORED` no actualiza cuando cambia la configuración de idioma**: si la columna `busqueda_ts` fue generada con `to_tsvector('spanish', ...)` y luego se cambia el contenido con texto en otro idioma, las palabras no se stemmizan correctamente — pero la columna no se regenera. Causa: la columna generada se recalcula solo cuando cambia la fila, no cuando cambia la lógica de la expresión. Fix: si se cambia la expresión de la columna generada, hacer `ALTER TABLE ... DROP COLUMN busqueda_ts; ALTER TABLE ... ADD COLUMN ...` para regenerar todos los valores.
+
+**SELECT-then-INSERT/UPDATE FUERA de `conn.transaction()` produce race condition** (CONFIRMADO x4 en sesiones SIGM 2026-05-20): patrón `SELECT id FROM X WHERE clave=$1` seguido de `INSERT/UPDATE X` sin envolver en transacción permite a otra petición concurrente insertar entre el SELECT y el write — viola unicidad lógica aunque haya UNIQUE constraint (la 2da petición recibe error pero después de hacer trabajo). Casos: doble VIGENTE en valuación, doble documento/orden con mismo folio, subdivisión/fusión/traslado de predios concurrentes. Fix obligatorio:
+```python
+async with self._conn.transaction():
+    # SELECT con lock explícito
+    row = await self._conn.fetchrow(
+        "SELECT id, version FROM tabla WHERE clave=$1 FOR UPDATE",
+        clave,
+    )
+    if row is None:
+        await self._conn.execute(
+            "INSERT INTO tabla (clave, ...) VALUES ($1, ...)",
+            clave, ...,
+        )
+    else:
+        # Si requiere CAS: WHERE clave=$1 AND version=$N en el UPDATE
+        await self._conn.execute(
+            "UPDATE tabla SET ... WHERE id=$1",
+            row["id"],
+        )
+```
+Alternativas:
+- `INSERT ... ON CONFLICT (clave) DO NOTHING/UPDATE` cuando la lógica es upsert puro.
+- `SELECT FOR UPDATE` para bloquear filas existentes durante el chequeo.
+- CAS en `WHERE version=$N` cuando el lock es muy costoso y se prefiere reintento.
+
+Regla de auditoría: cualquier endpoint con `SELECT ... WHERE` seguido de `INSERT`/`UPDATE` sobre la misma tabla DEBE estar dentro de `async with self._conn.transaction():`. El UNIQUE constraint NO sustituye el lock — es defensa de último recurso.
+
+**`UPDATE ... WHERE columna1 = $1` sin filtrar dimensiones adicionales des-actualiza filas hermanas**: SIGM NEM-VA-03 (2026-05-20). `UPDATE valuacion SET es_vigente=false WHERE predio_id=$1` cuando el predio tiene múltiples ejercicios fiscales des-vigentaba TODOS los ejercicios, no solo el actual. El bug pasó UNIQUE constraint (cada fila era válida individualmente) pero rompió integridad de dominio (debe haber 1 VIGENTE por (predio, ejercicio), no 1 VIGENTE por predio). Fix:
+```sql
+-- MAL
+UPDATE valuacion SET es_vigente=false WHERE predio_id=$1;
+
+-- BIEN
+UPDATE valuacion SET es_vigente=false
+WHERE predio_id=$1 AND ejercicio=$2;
+```
+Regla de auditoría: antes de aceptar un UPDATE, listar TODAS las dimensiones de dominio que definen "una fila lógica" (tenant_id, ejercicio, tipo, estatus, ...) y verificar que el WHERE incluye cada dimensión que aplica al scope del cambio. Las dimensiones implícitas (`es_vigente=true`, `activo=true`) también cuentan — un UPDATE que apaga `es_vigente` debe filtrar por la dimensión que define la unicidad de "vigente".
+
+**Drift triple Pydantic `Literal` ↔ validator de schema ↔ ENUM PostgreSQL**: SIGM NEM-VA-11 (2026-05-20). Tres universos incompatibles del mismo concepto: `Literal["A", "B", ..., "F"]` (6 valores) en el schema Pydantic, validator personalizado aceptando 8 valores, ENUM en PostgreSQL declarado con 12 valores. Cast `$N::schema.tipo_enum` falla en BD cuando llega un valor permitido por el Literal pero ausente del ENUM. Fix: **PostgreSQL ENUM como única fuente de verdad** cuando existe. Validar al arrancar la app:
+```python
+from sqlalchemy import text
+
+async def validar_enum_alineado(session, schema: str, enum_name: str, pydantic_values: set[str]):
+    rows = await session.execute(
+        text(f"SELECT enum_range(NULL::{schema}.{enum_name})")
+    )
+    pg_values = set(rows.scalar().strip("{}").split(","))
+    if pydantic_values != pg_values:
+        raise RuntimeError(
+            f"Drift ENUM {enum_name}: pydantic={pydantic_values} pg={pg_values}"
+        )
+```
+O generar el `Literal` Pydantic desde el ENUM PostgreSQL al startup (más estricto pero requiere conexión a BD para arrancar). Tests obligatorios: para cada ENUM, un test que compare `enum_range` contra el `Literal` del schema. La regla simple: si existe ENUM en BD, NO declarar Literal en código — derivarlo. Si NO existe ENUM en BD, NO declarar Literal en código — usar string libre con validator que consulta tabla de catálogo.
+
+**Partial unique index requiere predicado puro sobre columnas de la propia tabla**: SIGAF DT-TRANSICION-UC 2026-05-15. Intento inicial: `CREATE UNIQUE INDEX ... WHERE estatus_destino_id != (SELECT id FROM cat_estatus_acto WHERE clave='CANCELADO')`. PostgreSQL rechaza el predicado en partial index porque no permite subqueries. Workaround común: resolver el UUID en `upgrade()` con `SELECT` y embeber el literal — frágil porque en BD limpia (CI) la tabla está vacía → query retorna None → el índice se crea SIN filtro WHERE → seeds posteriores fallan al insertar lo que el índice ahora rechaza. Fix correcto:
+```sql
+-- 1. Agregar columna discriminadora en la tabla (boolean o enum)
+ALTER TABLE transicion_estatus_acto
+    ADD COLUMN es_automatica BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- 2. Backfill condicional desde el join con la tabla externa
+UPDATE transicion_estatus_acto t
+SET es_automatica = TRUE
+FROM cat_estatus_acto c
+WHERE t.estatus_destino_id = c.id AND c.clave = 'CANCELADO';
+
+-- 3. Partial index con predicado puro sobre columnas propias
+CREATE UNIQUE INDEX uq_transicion_origen_automatica
+ON transicion_estatus_acto (estatus_origen_id)
+WHERE es_automatica = TRUE;
+```
+Regla:
+- El `WHERE` de un partial index DEBE ser sobre columnas de la propia tabla. NUNCA subquery a otra tabla.
+- Si la lógica requiere distinguir filas por relación con otro catálogo, agregar columna discriminadora con backfill desde el JOIN.
+- Toda migración que dependa de datos de catálogo DEBE ser idempotente para BD vacía. NO confiar en que el seed corra antes — en CI fresh corre después.

package/habilidades/proceso-discovery-machote/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: proceso-discovery-machote
+description: >
+  Patrón de discovery para modelar entidades regulatorias (papeles de trabajo,
+  cédulas, oficios, informes, expedientes, actas, dictámenes). Antes de modelar
+  desde el Artículo legal, pedir al usuario el machote oficial real (template
+  institucional). El Art. define el mínimo normativo; el machote revela el
+  contrato institucional real con prácticas no codificadas pero exigidas.
+  Cargar al iniciar la modelación de cualquier entidad nueva que represente
+  un documento normativo emitido por una institución regulatoria (OIC, INE,
+  SAT, etc.), durante /swl:discutir-fase de un módulo regulatorio, o cuando
+  el usuario rechaza un primer diseño por "faltan campos del documento real".
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob]
+exclusiones:
+  - "No cargar para entidades NO regulatorias (productos, usuarios, sesiones, eventos de log) — el machote no aplica a entidades de aplicación generales."
+  - "No cargar cuando el modelo de la entidad ya está estabilizado y solo se va a agregar 1-2 campos — el discovery completo es overhead innecesario para ajustes pequeños."
+  - "No cargar para refactor de entidad existente que ya tiene 6+ meses en producción — el machote ya se consolidó implícitamente en el modelo; cualquier diferencia es decisión de evolución, no de discovery."
+  - "No cargar para CRUD administrativo simple (catálogos, configuraciones) — esos no tienen contrato institucional rico; cargar `discutir-fase` regular."
+evolvable: true
+---
+
+# Proceso Discovery Machote
+
+Patrón obligatorio antes de modelar entidades regulatorias.
+
+## Cuándo NO cargar
+
+- La entidad NO es regulatoria (un producto de catálogo, una sesión de usuario, un evento de log).
+- El modelo ya está estabilizado en producción y solo se agregan 1-2 campos.
+- Es refactor de entidad consolidada (≥6 meses prod) — cargar reglas de refactor, no de discovery.
+- Es CRUD administrativo simple sin contrato institucional rico.
+
+## El gap conceptual
+
+**El Artículo legal define el mínimo normativo. El machote oficial revela el contrato institucional real.**
+
+Caso real SIGAF ADR-081 IPHI (2026-05-15). El Informe de Presunta Hipótesis de Irregularidad (IPHI) se modeló inicialmente desde Art. 44 DBC_FISC_OIC, que enumera 10 fracciones (I-X) de contenido obligatorio:
+
+> Art. 44. El informe contendrá:
+> I.   Antecedentes
+> II.  Marco normativo
+> III. Hechos
+> IV.  Análisis
+> V.   Presunto daño patrimonial
+> VI.  Cuantificación del daño
+> VII. Sujetos involucrados
+> VIII. Pruebas documentales
+> IX.  Conclusiones
+> X.   Auditores que intervinieron
+
+Modelo Pydantic + tabla SQL creados con esas 10 secciones. Commit inicial Fase 1.
+
+Tras Fase 1, el usuario proporcionó el machote oficial real `OIC-DATIC-02-ESP-2025-IPHI-01.docx`. Reveló **7 extensiones institucionales NO presentes en Art. 44**:
+
+| # | Extensión del machote | NO está en Art. 44 |
+|---|---|---|
+| 1 | Distinción `presunto_dano_patrimonial` (directo) vs `perjuicio_total_estimado` (agregado: daño + depreciación + costo oportunidad) | Art. 44 fracción V/VI no distinguen |
+| 2 | Observaciones origen N:M con `hallazgo_identificador` (tabla puente `iphi_observacion_origen`) | Art. 44 no define la relación |
+| 3 | `procedimientos_contratacion_relacionados` JSONB (lista de LP-INE asociadas) | No aparece en el Art. |
+| 4 | `normas_infringidas` JSONB estructurado `[{norma, articulo, contenido}]` | Art. 44 dice "marco normativo" sin estructura |
+| 5 | `desglose_dano_patrimonial` JSONB (auditabilidad del cálculo) | No exigido por Art. |
+| 6 | Estructura específica de `antecedentes` JSONB con 6 sub-secciones | Art. 44 dice "antecedentes" sin desglose |
+| 7 | Roles claros de `auditores_integrantes`: Elaboró/Revisó/Supervisó/Autorizó mapeando a flujo VBO de 3 niveles | Art. 44 dice "auditores que intervinieron" sin roles |
+
+Refactor de Fase 1 = ~600 LOC de cambios + 1 tabla puente nueva + modelo Pydantic re-estructurado. Si el machote hubiera estado disponible al inicio, ese refactor no existiría.
+
+## El patrón
+
+### Paso 1: identificar si la entidad es regulatoria
+
+Una entidad es regulatoria cuando representa un **documento normativo emitido por una institución**:
+
+- Papel de trabajo (de auditoría).
+- Cédula (preliminar, definitiva, observación derivada).
+- Oficio (de investigación, de notificación, de respuesta).
+- Informe (de hipótesis, de irregularidad, de auditoría).
+- Acta (de inicio, de hechos, de cierre).
+- Dictamen.
+- Expediente (con composición fija de documentos).
+- Resolución.
+
+NO es regulatoria:
+- Producto de catálogo, usuario, sesión, configuración.
+- Evento de log o auditoría técnica.
+- Entidad transaccional puramente operacional (pago, factura interna).
+
+### Paso 2: durante /swl:discutir-fase, preguntar explícitamente
+
+Antes de modelar la entidad, plantear al usuario las 3 preguntas:
+
+1. **¿Existe un machote oficial real del documento?** (formato Word/PDF emitido por la institución, no template generado por el equipo).
+2. **¿Existe un Artículo legal o Reglamento que defina el contenido obligatorio?** (cita exacta del Art.).
+3. **Si solo hay Art., ¿hay práctica institucional documentada (manuales operativos, guías, ejemplos previos)?**
+
+Estados posibles del discovery:
+
+| Machote | Art. legal | Acción |
+|---|---|---|
+| ✅ Disponible | ✅ Disponible | Modelar desde machote + verificar que cubre todos los puntos del Art. (el Art. es el mínimo, el machote es el contrato real). |
+| ✅ Disponible | ❌ No disponible | Modelar desde machote. Marcar campos como "exigidos por práctica institucional, sin base legal explícita". |
+| ❌ No disponible | ✅ Disponible | Modelar desde Art. con marca explícita "modelo derivado solo del Art. — pendiente de validar contra machote oficial cuando el usuario lo proporcione". Crear DT formal `DT-MODELO-{ENTIDAD}-MACHOTE-PENDIENTE` con criterio de disparo: "modelo se considera estable cuando el machote oficial confirme o requiera ajustes". |
+| ❌ No disponible | ❌ No disponible | Escalar al usuario: "No hay fuente oficial ni machote — ¿la entidad existe como tal? ¿O debería modelarse como entidad de aplicación sin contrato institucional?". |
+
+### Paso 3: extraer del machote, no del modelo mental
+
+Cuando el machote esté disponible, leerlo COMPLETO con `markitdown` (regla global `markitdown.md` para .docx/.pdf):
+
+```bash
+markitdown OIC-DATIC-02-ESP-2025-IPHI-01.docx > /tmp/machote-iphi.md
+```
+
+Auditar cada sección visible:
+
+- **Tablas estructuradas**: cada fila/columna → posible columna de la entidad o tabla puente.
+- **Campos repetidos con formato uniforme**: posible tipo enum o catálogo.
+- **Secciones con sub-secciones**: posible JSONB estructurado.
+- **Espacios para firma/aprobación**: posible flujo de estados (VBO, aprobación multi-nivel).
+- **Numeración de párrafos**: posible array o relación 1:N.
+- **Referencias a otros documentos**: posibles FKs a otras entidades.
+
+NO inferir campos del modelo mental — extraer literal del machote.
+
+### Paso 4: registrar la divergencia Art. ↔ machote
+
+En el ADR de la entidad (o sección `### Modelo derivado` del schema):
+
+```markdown
+## Origen del modelo
+
+**Artículo legal**: DBC_FISC_OIC Art. 44 (10 fracciones I-X).
+**Machote oficial**: OIC-DATIC-02-ESP-2025-IPHI-01.docx (~25 páginas).
+
+**Extensiones del machote sobre el Art.**:
+1. `perjuicio_total_estimado` distinto de `presunto_dano_patrimonial`.
+2. Observaciones origen N:M con `hallazgo_identificador`.
+3. `procedimientos_contratacion_relacionados` JSONB.
+4. ...
+
+**Cobertura**: el modelo cubre 100% del Art. 44 + 7 extensiones del machote.
+**Divergencia**: cuando el Art. y el machote contradicen, prevalece el machote (es el contrato real de la institución).
+```
+
+## Anti-patrones
+
+- **Modelar desde solo el Art. legal sin pedir el machote** — el modelo cubre el mínimo legal pero pierde 30-50% del contenido institucional real. Refactor garantizado cuando aparezca el machote.
+- **Modelar desde un machote sin verificar contra el Art.** — riesgo de campos derivados de versiones obsoletas del documento. El Art. es la fuente de verdad legal; el machote puede tener campos "heredados" de versiones previas.
+- **Asumir que el machote está internalizado en el modelo del equipo** — el equipo del agente NO tiene el machote en su contexto entrenado. Pedirlo explícitamente al usuario; no inferir.
+- **Diferir el machote a "después del MVP"** — el refactor para incorporar el machote en una entidad regulatoria es 80% reescritura del modelo + cascada a schemas Pydantic + frontend forms. NO es post-MVP barato.
+- **Aceptar un machote en formato propietario sin convertirlo a markdown legible** — abrir el Word/PDF directamente lleva al modelo a olvidar campos. Convertir SIEMPRE con `markitdown` y auditar el markdown resultante.
+
+## Gotchas / Errores comunes no obvios
+
+- **El machote tiene campos "sólo para impresión" que NO son datos de la entidad**: encabezados con logos, secciones de "Para uso oficial", footers. Esos NO van al modelo. Discriminar mientras se audita el markdown extraído.
+- **El machote tiene campos calculados o derivados que SE ALMACENAN para auditoría**: ej. `perjuicio_total_estimado` se calcula desde 3 sumandos pero se persiste explícitamente porque el documento legal lo cita como cifra. Almacenar como columna calculada con backfill o como dato denormalizado con trigger de recálculo.
+- **El machote evoluciona entre años fiscales** (`OIC-DATIC-02-ESP-2024-...` vs `OIC-DATIC-02-ESP-2025-...`): el modelo debe versionar el contrato. Agregar `machote_version: str` a la entidad para registrar contra qué versión se emitió cada documento. Migrar es costoso si no se versiona desde el inicio.
+- **El usuario puede proporcionar un machote "informal" que es solo un Word con texto libre**: discriminar entre machote oficial (emitido por la institución con código de documento, fecha de actualización, autoridad emisora) vs borrador interno del equipo. El borrador NO es contrato — usar Art. como base con DT formal.

package/habilidades/proceso-modular-split/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: proceso-modular-split
+description: >
+  Playbook validado a escala (~20,000 LOC, 2 módulos refactorizados en SIGM:
+  recaudacion ADR-0016 + catastro ADR-0017) para dividir un módulo monolítico
+  en sub-paquetes coherentes preservando la API pública. Usa compositor por
+  herencia múltiple (NO __getattr__), helpers transversales en clase base,
+  router compositor zero-LOC con APP_ROUTER raíz. Cubre las 8 sesiones del
+  playbook (S1-S8), criterios para decidir cuándo aplicar el split, y los
+  anti-patrones detectados por auditoría humana que las auditorías técnicas
+  NO detectan. Cargar cuando el módulo backend supera ~1500 LOC en un solo
+  archivo (router.py, service.py o repository.py), cuando hay solicitud
+  explícita de "refactorizar X aplicando ADR-0016/0017", o cuando el módulo
+  monolítico se vuelve unmaintainable por acoplamiento entre sub-dominios.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob]
+exclusiones:
+  - "No cargar para módulos pequeños (<800 LOC en su archivo más grande) — el split agrega overhead arquitectural sin beneficio."
+  - "No cargar para frameworks no-Python — el patrón compositor por herencia múltiple es específico de la flexibilidad de MRO de Python; en Java/C# se hace con interfaces y composition diferente."
+  - "No cargar para refactor de capa de datos (BD schema split, sharding) — este playbook es para split de código aplicación; BD split requiere migración con expand-contract distinta."
+  - "No cargar para split de microservicios (separar en servicios HTTP distintos) — este playbook mantiene un solo proceso/deployment; para microservicios cargar `microservicios`."
+evolvable: true
+---
+
+# Proceso Modular Split (Playbook ADR-0016/0017)
+
+Split de módulo monolítico en sub-paquetes preservando API pública. Validado a escala 20k LOC.
+
+## Cuándo NO cargar
+
+- Módulo pequeño (<800 LOC en su archivo más grande) — overhead arquitectural sin beneficio.
+- Framework no-Python (Java, Go, Rust) — el patrón compositor por herencia múltiple aprovecha MRO de Python.
+- Refactor de capa de datos (BD schema, sharding) — requiere expand-contract distinto.
+- Split de microservicios HTTP — cargar `microservicios`; este playbook mantiene un solo proceso.
+
+## Criterio para aplicar
+
+Aplicar el playbook cuando AL MENOS DOS se cumplen:
+
+1. `router.py` (FastAPI) o equivalente supera **~1500 LOC** con ~30+ endpoints heterogéneos.
+2. `service.py` supera **~1700 LOC** con sub-dominios identificables (e.g., en `catastro/`: predios, valuación, vialidades, manzanas, construcciones, inspecciones, operaciones, factores, geo).
+3. `repository.py` supera **~2400 LOC** o tiene métodos de tablas que NO se cruzan entre sí.
+4. Tests del módulo tardan >60s o requieren imports cross-dominio frágiles.
+5. Cambio en una "sección" del módulo rompe tests de otra sección que no debería estar relacionada (signal de acoplamiento implícito).
+
+Si solo se cumple 1 criterio, probablemente lo correcto es extraer una sub-función o helper, NO aplicar el split completo.
+
+## El patrón: compositor por herencia múltiple (NO `__getattr__`)
+
+### Lo que NO hacer
+
+```python
+# MAL — compositor por __getattr__: invisible al type checker, frágil
+class CatastroService:
+    def __init__(self, conn):
+        self._predios = CatastroPrediosService(conn)
+        self._valuacion = CatastroValuacionService(conn)
+        ...
+
+    def __getattr__(self, name):
+        # Mágico, pero el type checker no ve los métodos delegados.
+        for sub in (self._predios, self._valuacion, ...):
+            if hasattr(sub, name):
+                return getattr(sub, name)
+        raise AttributeError(name)
+```
+
+Problemas:
+- IDE no autocompleta los métodos delegados.
+- `mypy`/`pyright` no detecta llamadas a métodos inexistentes.
+- Stack traces opacos (la línea de error apunta al `__getattr__`, no al sitio real).
+- Imposible inspeccionar el MRO efectivo.
+
+### Lo que SÍ hacer
+
+```python
+# BIEN — herencia múltiple: MRO inspeccionable, type checker feliz
+class CatastroPrediosService(CatastroServiceBase):
+    async def crear_predio(self, ...): ...
+    async def obtener_predio(self, ...): ...
+
+class CatastroValuacionService(CatastroServiceBase):
+    async def crear_valuacion(self, ...): ...
+    async def listar_vigentes(self, ...): ...
+
+class CatastroVialidadesService(CatastroServiceBase):
+    async def listar_vialidades(self, ...): ...
+
+# El compositor hereda de TODOS los sub-services.
+class CatastroService(
+    CatastroPrediosService,
+    CatastroValuacionService,
+    CatastroVialidadesService,
+    # ... 9 sub-services
+):
+    """Compositor monolítico transitorio.
+
+    Mantiene la API pública del módulo monolítico previo. Los routers de la
+    fase posterior consumen sub-services específicos directamente — el
+    compositor queda como fallback de retrocompatibilidad.
+    """
+    pass
+```
+
+Verificación inspeccionable:
+```python
+>>> CatastroService.__mro__
+(CatastroService, CatastroPrediosService, CatastroValuacionService,
+ CatastroVialidadesService, ..., CatastroServiceBase, object)
+```
+
+El type checker ve todos los métodos. El IDE autocompleta. El stack trace apunta al método real, no al compositor.
+
+### Helpers transversales en clase base
+
+Cuando varios sub-services necesitan el mismo helper (ej. `_validar_predio_existe`), va en la clase base (NO se duplica entre sub-services):
+
+```python
+class CatastroServiceBase:
+    """Helpers compartidos por todos los sub-services de catastro."""
+
+    def __init__(self, conn):
+        self._conn = conn
+
+    async def _validar_predio_existe(self, predio_id: uuid.UUID) -> None:
+        row = await self._conn.fetchrow(
+            "SELECT 1 FROM catastro.predio WHERE id=$1",
+            predio_id,
+        )
+        if row is None:
+            raise NotFoundError(
+                message=f"Predio {predio_id} no encontrado",
+                code="PREDIO_NO_ENCONTRADO",
+            )
+
+    async def _tenant_actual(self) -> uuid.UUID:
+        # Lee del contexto async (contextvars), no del estado de instancia.
+        ...
+```
+
+Regla: helper que ≥80% de sub-services necesitan → clase base. Si solo lo necesitan 1-2 sub-services, vive en uno de ellos y los otros lo importan via composición (no herencia).
+
+## El playbook S1-S8
+
+### S1 — ADR + PLAN.md + consolidación previa
+
+- Crear `.planning/adrs/NNNN-split-modulo-X.md` con:
+  - Motivación cuantitativa (LOC actuales, problemas concretos detectados).
+  - Lista de sub-dominios identificados con criterio de separación.
+  - Plan de migración (no hay big-bang — son 8 sesiones secuenciales).
+- Consolidar primero archivos relacionados que ya están separados pero deberían convivir (ej. en catastro: `repository_geo.py` + `router_geo.py` → `geo/`).
+
+### S2 — Split `repository.py` en sub-repositorios
+
+- Crear `<modulo>/<sub>/repository.py` por cada sub-dominio.
+- Mover métodos del repository monolítico a su sub-repositorio.
+- El `<modulo>/repository.py` original queda como compositor por herencia múltiple (mismo patrón que el service).
+
+### S3 — Split `router.py` en sub-routers + APP_ROUTER raíz
+
+- Crear `<modulo>/<sub>/router.py` con sub-APIRouter.
+- Crear `<modulo>/router.py` reducido (~38 LOC) que solo agrega APP_ROUTER raíz e incluye los sub-routers:
+  ```python
+  from fastapi import APIRouter
+  from .predios.router import router as predios_router
+  from .valuacion.router import router as valuacion_router
+  # ...
+
+  app_router = APIRouter(prefix="/catastro", tags=["catastro"])
+  app_router.include_router(predios_router, prefix="/predios")
+  app_router.include_router(valuacion_router, prefix="/valuacion")
+  # ...
+  ```
+
+### S4 — Split `service.py` en sub-services + `service_base.py`
+
+- Aplicar el patrón "compositor por herencia múltiple" descrito arriba.
+- Mover métodos del service monolítico a su sub-service.
+- Helpers transversales → `service_base.py`.
+
+### S5 — Schemas: re-export por sub-paquete
+
+- Schemas Pydantic NO se parten — siguen viviendo en `<modulo>/schemas.py` (un solo archivo) O se mueven a `<modulo>/<sub>/schemas.py` pero NO se duplica definición.
+- Si se mueve, hacer re-export en `<modulo>/schemas.py` para retrocompatibilidad de imports:
+  ```python
+  from .predios.schemas import PredioCreate, PredioResponse  # noqa: F401
+  from .valuacion.schemas import ValuacionCreate, ValuacionResponse  # noqa: F401
+  ```
+
+### S6 — Reorganización de tests
+
+- Mover `tests/<modulo>/test_*.py` a `tests/<modulo>/<sub>/test_*.py` con `git mv` (preserva historial).
+- Conftest.py por sub-dominio si los fixtures divergen.
+
+### S7 — Auditoría nemesis por sub-router + arch-cleanup
+
+- `/swl:nemesis --modulo <modulo>/<sub>/router.py --remediar` por cada sub-router.
+- Documentar hallazgos por sub-dominio.
+- **S7-arch-cleanup**: migrar routers que aún consumen el compositor a su sub-service específico:
+  ```python
+  # MAL — router consume compositor cuando ya existe sub-service
+  from app.catastro.service import CatastroService
+  servicio = CatastroService(conn)
+  predio = await servicio.obtener_predio(id)
+
+  # BIEN — router consume el sub-service directamente
+  from app.catastro.predios.service import CatastroPrediosService
+  servicio = CatastroPrediosService(conn)
+  predio = await servicio.obtener_predio(id)
+  ```
+  El compositor queda como fallback para código legacy, no como ruta normal.
+
+### S8 — Cierre formal + actualización docs
+
+- Actualizar `CLAUDE.md` del proyecto con los anti-patrones detectados en S7-arch-cleanup.
+- Actualizar `AGENTS.md` con la nueva estructura del módulo.
+- Marcar la fase como cerrada en `.planning/HOJA-RUTA.md`.
+
+## Anti-patrones detectados que las auditorías NO detectan (S7-arch-cleanup)
+
+La auditoría técnica (`revisor-codigo-swl`, `nemesis-auditor-swl`) NO detectó estos en SIGM 2026-05-20 — los detectó el usuario al revisar el código post-refactor:
+
+1. **Router importa el compositor cuando existe sub-service específico**: defeating-purpose del refactor. Detectable con `grep -rn "from app.<modulo>.service import <Modulo>Service" app/<modulo>/<sub>/router.py` — debería retornar vacío después del split.
+
+2. **Router accede a `servicio._repo` o métodos privados**: rompe encapsulación. Detectable con `grep -rn "servicio\._repo\|servicio\._mapear_" app/<modulo>/<sub>/router.py`. Fix: encapsular en método público del sub-service.
+
+3. **Default `None` pasado explícitamente bypasea el default del callee**: `await servicio.listar_vialidades(activa=None)` cuando el contrato dice "omitir devuelve solo activas". Fix: en el router, `activa=True if activa is None else activa` o cambiar firma del callee a `activa: bool = True` (no `bool | None`).
+
+4. **CLAUDE.md y AGENTS.md desincronizados**: tras el split, ambos archivos describen el módulo. Si solo se actualiza uno, los agentes que cargan AGENTS.md desconocen el cambio. Fix: gate en CI que compara secciones del módulo entre los dos archivos.
+
+## Reglas no-negociables
+
+- **NUNCA `__getattr__`** para delegación entre sub-services. El compositor es herencia múltiple inspeccionable.
+- **NUNCA partir schemas Pydantic sin re-export** — rompe imports existentes y obliga a refactor cascada.
+- **NUNCA hacer big-bang** — el playbook ES 8 sesiones secuenciales. Saltarse S5 o S6 deja el módulo en estado inconsistente.
+- **SIEMPRE `git mv` para mover archivos** — preserva blame y permite ver el historial post-split.
+- **SIEMPRE actualizar CLAUDE.md + AGENTS.md en S8** — desincronizados generan deuda invisible que aflora en la siguiente fase.
+- **SIEMPRE S7-arch-cleanup después de los fixes nemesis** — sin esa pasada, los routers mantienen acoplamiento al compositor que el split intentaba romper.
+
+## Gotchas / Errores comunes no obvios
+
+- **MRO con conflict en herencia múltiple**: si dos sub-services definen método con el mismo nombre, Python resuelve por MRO (orden de declaración en la clase compositor). Si el conflict es accidental (dos sub-dominios distintos con método homónimo), el MRO oculta uno. Fix: tests de regresión sobre cada método público del compositor, no solo de los sub-services.
+- **Sub-service que requiere estado de otro sub-service en su `__init__`**: ej. `CatastroValuacionService` necesita `CatastroPrediosService` para validar el predio antes de crear valuación. Si el constructor lo recibe, el compositor por herencia múltiple no puede instanciar (`__init__` debe ser igual en todos). Fix: los sub-services NO se referencian mutuamente; comparten helpers en la clase base, no instancias entre sí.
+- **Tests de integración que importan el compositor pasan, tests unitarios del sub-service fallan**: el sub-service requiere fixtures que el compositor ya configura. Fix: cada sub-service tiene su `conftest.py` con fixtures locales (mock de `_conn`, helpers de creación de datos del sub-dominio).
+- **Migración del git history con `git mv` no preserva blame si hay cambios en el mismo commit**: si haces `git mv router.py predios/router.py` y modificas el contenido en el mismo commit, `git blame --follow` puede fallar en versiones antiguas de git. Fix: hacer `git mv` puro en un commit, modificar contenido en commit separado.
+- **El compositor monolítico es "transitorio" pero queda 6+ meses**: si el equipo no migra los consumers al sub-service específico, el compositor se vuelve permanente. Fix: agregar deprecation warning al `__init__` del compositor: `warnings.warn("Use <sub>Service directly", DeprecationWarning, stacklevel=2)`.
+
+## Referencias
+
+| Tema | Recurso |
+|------|---------|
+| ADR-0016 (recaudación split) | SIGM `.planning/adrs/0016-split-modulo-recaudacion.md` |
+| ADR-0017 (catastro split) | SIGM `.planning/adrs/0017-split-modulo-catastro.md` |
+| Patrón de error design (kwargs explícitos) | `Skill("backend-error-design")` |
+| Testing con transaction mock | `Skill("backend-async-postgres-testing")` |
+| Arquitectura general (módulos profundos, DRY) | `~/.claude/rules/arquitectura.md` |

package/habilidades/tdd-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: tdd-workflow
 description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.0.5"
+version: "1.0.6"
 evolved: true
 evolved-from: "1.0.4"
 evolved-at: "2026-05-16"
@@ -350,14 +350,18 @@ function enriquecerDesdeFases(fases, opciones = {}) {
   // ...
 }
 
-// En el test:
-const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
+// En el test (usa setupSandboxes — regla tests-cleanup.md):
+const { setupSandboxes } = require('../_helpers/sandbox');
+const sandboxes = setupSandboxes('swl-test-');
+
+const sandbox = sandboxes.create();
 fs.mkdirSync(path.join(sandbox, '.planning', 'fases'), { recursive: true });
 // Opción A: pasar cwd explícito (recomendado)
 const r = enriquecerDesdeFases([], { cwd: sandbox });
 // Opción B: process.chdir() — solo funciona con cwd dinámico
 process.chdir(sandbox);
 const r2 = enriquecerDesdeFases([]);
+// Cleanup automático al final del archivo vía after() registrado por setupSandboxes.
 ```
 
 ---
@@ -399,10 +403,13 @@ deterministamente. Patrones típicos:
 **Patrón 1 — Aislamiento por path único** (recomendado):
 
 ```javascript
+const { setupSandboxes } = require('../_helpers/sandbox');
+const sandboxes = setupSandboxes('swl-mi-app-test-');
 const env = { ...process.env };
 
-// Path único por test usando mkdtempSync — sin contención
-const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mi-app-test-'));
+// Path único por test usando el helper canónico (regla tests-cleanup.md).
+// El cleanup es automático al final del archivo vía after() registrado.
+const dir = sandboxes.create();
 env.MI_APP_FLAG_PATH = path.join(dir, 'flag.json');
 
 const res = spawnSync('node', [BIN], { env, ... });

package/hooks/extraccion-aprendizajes.js

@@ -632,6 +632,14 @@ const PATRONES_ARCHIVO_SWL_EXCLUIDO = [
   // Todo .planning/ salvo wiki/ (que puede contener conocimiento del proyecto usuario).
   // En swl-ses .planning/ es meta del sistema; los aprendizajes se gestionan manualmente.
   /(?:^|[\\/])\.planning[\\/](?!wiki[\\/])/,
+  // Todo _userland/ — zona de trabajo del agente (staging para exports al vault,
+  // userland-agentes, userland-habilidades). Su contenido es meta del agente:
+  // promociones temporales, borradores, exports estructurados con keywords
+  // narrativas ("patrón", "decisión", "anti-patrón", "fix") que el hook
+  // confunde con aprendizajes genuinos. Detectado 2026-05-18 cuando staging
+  // con dec1-*.md y res1-*.md (escritos para promover a vault) generaron
+  // 2 entradas espurias en APRENDIZAJES.md.
+  /(?:^|[\\/])_userland[\\/]/,
   /[\\/]CHANGELOG\.md$/i,
   /[\\/]CLAUDE\.md$/i,
   /[\\/]AGENTS\.md$/i,