@saulwade/swl-ses 2.3.0 → 2.4.1

package/habilidades/proceso-debate-adversarial/recursos/personas.md

@@ -1,105 +1,105 @@
-# Personas para análisis predictivo y debate adversarial
-
-Definiciones operativas de las personas que consume `proceso-debate-adversarial`
-(modo personas) y `/swl:predecir`. Cada persona se invoca EN FRÍO (COLD START):
-recibe la descripción del cambio + conocimiento del codebase + sus criterios —
-nunca el análisis de otra persona.
-
-Formato de hallazgo obligatorio por persona:
-
-```markdown
-| # | Hallazgo | Severidad | Confianza (0-100%) | archivo:línea | Recomendación |
-```
-
-Presupuesto: `max_hallazgos_por_persona = presupuesto_total / num_personas`
-(default presupuesto 40 → 8 por persona). Obliga a priorizar, no a enumerar.
-
----
-
-## Set default (análisis predictivo estándar)
-
-### 1. Arquitecto de Software
-- **Enfoque**: diseño sistémico, fronteras de componentes, flujo de datos, escalabilidad.
-- **Preguntas guía**: ¿Escala? ¿Los límites entre módulos son limpios? ¿El acoplamiento está minimizado? ¿Sobrevive un crecimiento 10x?
-- **Evidencia exigida**: archivo:línea, grafo de dependencias, métricas de acoplamiento.
-- **Red flags**: god classes, dependencias circulares, abstracciones con fugas, estado mutable compartido.
-
-### 2. Analista de Seguridad
-- **Enfoque**: superficies de ataque, autenticación/autorización, protección de datos, vectores de inyección.
-- **Preguntas guía**: ¿Es explotable? ¿Los trust boundaries se aplican? ¿El input se sanitiza? ¿Los secretos están protegidos?
-- **Evidencia exigida**: archivo:línea + escenario de ataque concreto (no especulación teórica).
-- **Red flags**: SQL crudo, authz faltante, secretos hardcodeados, input sin sanitizar.
-
-### 3. Ingeniero de Rendimiento
-- **Enfoque**: latencia, throughput, uso de recursos, complejidad algorítmica.
-- **Preguntas guía**: ¿Es suficientemente rápido? ¿Cuál es el peor caso? ¿Dónde están los cuellos de botella? ¿El caching es efectivo?
-- **Evidencia exigida**: archivo:línea, análisis de complejidad, estimaciones de recursos.
-- **Red flags**: queries N+1, loops sin cota, índices faltantes, I/O síncrono en hot paths.
-
-### 4. Ingeniero de Confiabilidad
-- **Enfoque**: manejo de errores, modos de falla, observabilidad, recuperación.
-- **Preguntas guía**: ¿Qué pasa cuando falla? ¿Podemos detectarlo? ¿Hay camino de recuperación? ¿Es observable?
-- **Evidencia exigida**: archivo:línea, escenarios de falla, rutas de recuperación.
-- **Red flags**: errores tragados, retries faltantes, sin circuit breakers, fallas silenciosas.
-
-### 5. Abogado del Diablo
-- **Enfoque**: asunciones, casos límite, complejidad oculta, mantenibilidad.
-- **Preguntas guía**: ¿Qué asunciones son falsas? ¿Qué rompe esto? ¿Está sobre-ingenierizado?
-- **Evidencia exigida**: contraejemplos concretos, escenarios de caso límite.
-- **Red flags**: diseño solo-happy-path, asunciones sin probar, complejidad sin justificación.
-
----
-
-## Set adversarial (`--adversarial`)
-
-Reemplaza al set default cuando el objetivo es estresar el cambio como atacante,
-no como revisor.
-
-### 1. El Rompedor
-Intenta crashear o corromper el sistema. Busca: estados imposibles, inputs
-malformados, condiciones de carrera, límites de recursos.
-
-### 2. El Tramposo
-Busca formas de saltarse reglas y abusar de features. Busca: validaciones solo
-en frontend, límites evadibles, flujos alternos sin guards.
-
-### 3. El Escalador
-Imagina carga 1000x y encuentra qué se rompe primero. Busca: queries sin
-paginación, locks globales, colas sin backpressure, costos lineales ocultos.
-
-### 4. El Novato
-Usa mal cada API esperando que funcione. Busca: defaults peligrosos, errores
-crípticos, documentación que asume contexto, footguns de la interfaz.
-
-### 5. El Insider Malicioso
-Tiene credenciales válidas y quiere exfiltrar. Busca: permisos excesivos,
-auditoría faltante, datos sensibles accesibles lateralmente.
-
----
-
-## Set red-team de seguridad (para `checklist-seguridad` modo cobertura)
-
-Rotación de mentalidades para auditoría STRIDE/OWASP iterativa:
-
-| Persona | Foco | Mentalidad |
-|---------|------|-----------|
-| Adversario de Seguridad | auth, crypto, inyección | atacante externo con browser + proxy de intercepción |
-| Atacante de Supply Chain | dependencias, CI/CD, build pipeline | comprometer vía código de terceros |
-| Amenaza Interna | acceso a datos, abuso de privilegios, exfiltración | usuario autenticado con intención maliciosa |
-| Atacante de Infraestructura | red, configuración cloud, contenedores | apuntar a misconfigurations de infra |
-
----
-
-## Protocolo de síntesis (tras el análisis individual)
-
-1. **Deduplicar**: mismo archivo:línea + mismo problema → fusionar, conservar la severidad más alta.
-2. **Resolver conflictos**: si dos personas discrepan → registrar el disenso, no silenciarlo.
-3. **Anti-herd check**: si TODAS las personas coinciden → el sintetizador DEBE producir ≥1 contraargumento.
-4. **Rankear**: `severidad × confianza promedio × número de personas que coinciden`.
-
-Output del sintetizador:
-
-```markdown
-### Consenso — [N hallazgos tras dedup]
-| # | Hallazgo | Severidad | Acuerdo | Personas origen | Acción |
-```
+# Personas para análisis predictivo y debate adversarial
+
+Definiciones operativas de las personas que consume `proceso-debate-adversarial`
+(modo personas) y `/swl:predecir`. Cada persona se invoca EN FRÍO (COLD START):
+recibe la descripción del cambio + conocimiento del codebase + sus criterios —
+nunca el análisis de otra persona.
+
+Formato de hallazgo obligatorio por persona:
+
+```markdown
+| # | Hallazgo | Severidad | Confianza (0-100%) | archivo:línea | Recomendación |
+```
+
+Presupuesto: `max_hallazgos_por_persona = presupuesto_total / num_personas`
+(default presupuesto 40 → 8 por persona). Obliga a priorizar, no a enumerar.
+
+---
+
+## Set default (análisis predictivo estándar)
+
+### 1. Arquitecto de Software
+- **Enfoque**: diseño sistémico, fronteras de componentes, flujo de datos, escalabilidad.
+- **Preguntas guía**: ¿Escala? ¿Los límites entre módulos son limpios? ¿El acoplamiento está minimizado? ¿Sobrevive un crecimiento 10x?
+- **Evidencia exigida**: archivo:línea, grafo de dependencias, métricas de acoplamiento.
+- **Red flags**: god classes, dependencias circulares, abstracciones con fugas, estado mutable compartido.
+
+### 2. Analista de Seguridad
+- **Enfoque**: superficies de ataque, autenticación/autorización, protección de datos, vectores de inyección.
+- **Preguntas guía**: ¿Es explotable? ¿Los trust boundaries se aplican? ¿El input se sanitiza? ¿Los secretos están protegidos?
+- **Evidencia exigida**: archivo:línea + escenario de ataque concreto (no especulación teórica).
+- **Red flags**: SQL crudo, authz faltante, secretos hardcodeados, input sin sanitizar.
+
+### 3. Ingeniero de Rendimiento
+- **Enfoque**: latencia, throughput, uso de recursos, complejidad algorítmica.
+- **Preguntas guía**: ¿Es suficientemente rápido? ¿Cuál es el peor caso? ¿Dónde están los cuellos de botella? ¿El caching es efectivo?
+- **Evidencia exigida**: archivo:línea, análisis de complejidad, estimaciones de recursos.
+- **Red flags**: queries N+1, loops sin cota, índices faltantes, I/O síncrono en hot paths.
+
+### 4. Ingeniero de Confiabilidad
+- **Enfoque**: manejo de errores, modos de falla, observabilidad, recuperación.
+- **Preguntas guía**: ¿Qué pasa cuando falla? ¿Podemos detectarlo? ¿Hay camino de recuperación? ¿Es observable?
+- **Evidencia exigida**: archivo:línea, escenarios de falla, rutas de recuperación.
+- **Red flags**: errores tragados, retries faltantes, sin circuit breakers, fallas silenciosas.
+
+### 5. Abogado del Diablo
+- **Enfoque**: asunciones, casos límite, complejidad oculta, mantenibilidad.
+- **Preguntas guía**: ¿Qué asunciones son falsas? ¿Qué rompe esto? ¿Está sobre-ingenierizado?
+- **Evidencia exigida**: contraejemplos concretos, escenarios de caso límite.
+- **Red flags**: diseño solo-happy-path, asunciones sin probar, complejidad sin justificación.
+
+---
+
+## Set adversarial (`--adversarial`)
+
+Reemplaza al set default cuando el objetivo es estresar el cambio como atacante,
+no como revisor.
+
+### 1. El Rompedor
+Intenta crashear o corromper el sistema. Busca: estados imposibles, inputs
+malformados, condiciones de carrera, límites de recursos.
+
+### 2. El Tramposo
+Busca formas de saltarse reglas y abusar de features. Busca: validaciones solo
+en frontend, límites evadibles, flujos alternos sin guards.
+
+### 3. El Escalador
+Imagina carga 1000x y encuentra qué se rompe primero. Busca: queries sin
+paginación, locks globales, colas sin backpressure, costos lineales ocultos.
+
+### 4. El Novato
+Usa mal cada API esperando que funcione. Busca: defaults peligrosos, errores
+crípticos, documentación que asume contexto, footguns de la interfaz.
+
+### 5. El Insider Malicioso
+Tiene credenciales válidas y quiere exfiltrar. Busca: permisos excesivos,
+auditoría faltante, datos sensibles accesibles lateralmente.
+
+---
+
+## Set red-team de seguridad (para `checklist-seguridad` modo cobertura)
+
+Rotación de mentalidades para auditoría STRIDE/OWASP iterativa:
+
+| Persona | Foco | Mentalidad |
+|---------|------|-----------|
+| Adversario de Seguridad | auth, crypto, inyección | atacante externo con browser + proxy de intercepción |
+| Atacante de Supply Chain | dependencias, CI/CD, build pipeline | comprometer vía código de terceros |
+| Amenaza Interna | acceso a datos, abuso de privilegios, exfiltración | usuario autenticado con intención maliciosa |
+| Atacante de Infraestructura | red, configuración cloud, contenedores | apuntar a misconfigurations de infra |
+
+---
+
+## Protocolo de síntesis (tras el análisis individual)
+
+1. **Deduplicar**: mismo archivo:línea + mismo problema → fusionar, conservar la severidad más alta.
+2. **Resolver conflictos**: si dos personas discrepan → registrar el disenso, no silenciarlo.
+3. **Anti-herd check**: si TODAS las personas coinciden → el sintetizador DEBE producir ≥1 contraargumento.
+4. **Rankear**: `severidad × confianza promedio × número de personas que coinciden`.
+
+Output del sintetizador:
+
+```markdown
+### Consenso — [N hallazgos tras dedup]
+| # | Hallazgo | Severidad | Acuerdo | Personas origen | Acción |
+```

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

@@ -1,157 +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.
+---
+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.