@saulwade/swl-ses 1.4.1 → 1.5.0

package/habilidades/protocolo-revision-swl/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: protocolo-revision-swl
+description: >
+  Protocolo de revisión adversarial per-task con git diff como single source of
+  truth. Adapta el patrón task-local review de cc-sdd al ecosistema SWL: los
+  revisores existentes (revisor-codigo-swl, revisor-seguridad-swl, revisor-*-swl)
+  aplican este protocolo cuando trabajan sobre una sola tarea atómica en lugar
+  de una fase completa. Devuelve APPROVED o REJECTED con findings de severidad
+  estructurados y boundary checks. Cargar desde el agente revisor cuando
+  ejecutar-fase corre en modo --iterative (task por task) o cuando se solicita
+  revisión acotada a un commit / patch específico.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob, Bash]
+exclusiones:
+  - "No cargar para revisión de fase completa multi-archivo — usar el flujo estándar del revisor con `/swl:revisar` y `/swl:verificar`."
+  - "No cargar para auditoría de seguridad profunda — usar `revisor-seguridad-swl` con `checklist-seguridad`."
+  - "No cargar como sustituto de la verificación goal-backward post-ejecución — `verificar-trabajo` cubre eso a nivel de fase."
+  - "No cargar para revisar código que no ha sido staged ni commiteado todavía — el protocolo requiere un diff o set de archivos definido."
+evolvable: true
+---
+
+# Protocolo de revisión per-task
+
+## Propósito
+
+Revisar el resultado de UNA tarea atómica de implementación (no una fase
+completa) con el rigor de un revisor adversarial. El protocolo está diseñado
+para coexistir con los revisores especializados existentes (`revisor-codigo-swl`,
+`revisor-react-swl`, `revisor-typescript-swl`, etc.): esos agentes cargan
+este skill cuando el alcance es task-local en lugar de phase-wide.
+
+Adaptado del patrón `kiro-review` de cc-sdd. Mantiene los principios de
+swl-ses (separación revisor/ejecutor de `reglas/gobernanza.md`, veto items
+y cap enforcement, scoring 9.0+ obligatorio para APPROVED).
+
+## Cuándo cargar
+
+- El orquestador ejecuta `/swl:ejecutar-fase --iterative` y necesita revisión task-por-task
+- Un agente implementador reportó `READY_FOR_REVIEW` para una sub-tarea específica
+- El usuario pide "revisa este último commit" o "revisa lo que acabo de hacer"
+- Tras una remediación de un finding previo y se necesita re-verificación acotada
+
+## Cuándo NO cargar
+
+Ver `exclusiones` en frontmatter.
+
+---
+
+## Inputs requeridos
+
+Antes de empezar, identifica los siguientes inputs. Si falta cualquiera, pide
+clarificación al caller (orquestador o implementador) en lugar de proceder
+con asunciones.
+
+| Input | Forma | Obligatorio |
+|-------|-------|-------------|
+| Task ID | Texto de la tarea desde PLAN.md (ej. "3.2 — Crear endpoint POST /facturas") | Sí |
+| Boundary scope | Lista de paths/módulos que la tarea puede modificar | Sí |
+| Spec references | IDs de requirements y design sections que la tarea satisface | Sí — si existen |
+| Diff | `git diff <base>..HEAD` o set de archivos modificados | Sí |
+| Validation commands | Comandos descubiertos por el caller (test, build, lint, smoke) | Sí — si aplica el stack |
+| Implementer status report | El reporte estructurado del ejecutor (`READY_FOR_REVIEW`, archivos tocados, decisiones) | Recomendado |
+
+---
+
+## Paso 1 — Primera acción obligatoria: `git diff`
+
+Antes de leer cualquier otro archivo, ejecuta:
+
+```bash
+git diff --stat       # alcance del cambio
+git diff <base>..HEAD # contenido real
+```
+
+El reporte del implementador NO es fuente de verdad. El diff sí. Si el diff
+es grande, lee los archivos modificados directamente — no resuamen ni inferas
+desde el reporte del ejecutor.
+
+**Por qué**: el implementador puede honestamente reportar "implementé X" pero
+haber introducido Y como efecto colateral. El diff captura todo, incluido lo
+que el ejecutor no recuerda haber tocado.
+
+---
+
+## Paso 2 — Checks mecánicos (resultado = señal primaria)
+
+Estos checks son determinísticos y producen evidencia directa. Aplica TODOS
+antes de pasar a interpretación.
+
+### Check 1: Regression safety
+
+Corre la suite de tests del proyecto con las `validation_commands` provistas.
+Ejemplo:
+
+```bash
+npm test               # o pytest, o cargo test, etc.
+```
+
+- **Tests pasan** → continuar.
+- **Tests fallan** → `REJECTED` inmediato. Incluye el conteo y nombres de tests fallidos en el reporte.
+- **Tests skipped aumentan vs base** → riesgo de regresión silenciosa (regla `monitor-ci.md`). Reportar el delta como finding de severidad MAJOR.
+
+### Check 2: Sin marcadores placeholder nuevos
+
+```bash
+git diff <base>..HEAD | grep -E "\+.*\b(TBD|TODO|FIXME|HACK|XXX)\b" || true
+```
+
+Marcadores nuevos solo se aceptan con justificación explícita en el reporte
+del implementador asociada al PLAN.md vigente (referencia a task ID, no texto suelto).
+Sin justificación → finding MAYOR.
+
+### Check 3: Sin secretos hardcodeados
+
+```bash
+git diff <base>..HEAD | grep -E "(api[_-]?key|password|secret|token)\s*[=:]\s*[\"'][^\"'\s]{8,}[\"']" -i || true
+```
+
+Cualquier match → `REJECTED` con finding CRÍTICO. Aplica los patrones
+documentados en `reglas/seguridad-agentes.md` § "Protección de secretos".
+
+### Check 4: Boundary violations
+
+Lista de archivos modificados:
+
+```bash
+git diff --name-only <base>..HEAD
+```
+
+Cada archivo modificado DEBE estar dentro del `boundary scope` declarado en
+la tarea. Si un archivo fuera del boundary aparece modificado:
+
+- Si es modificación trivial (formateo, comentario) → finding MENOR.
+- Si es modificación funcional → finding MAYOR. La tarea debe declarar el
+  boundary extendido o el cambio se devuelve al implementador para extraer
+  a una tarea aparte.
+
+---
+
+## Paso 3 — Verificación de alineación con spec
+
+Lee directamente:
+
+- El texto de la tarea en `PLAN.md` (no parafrases — copia literal).
+- Los requirements citados en el campo `requirements` de la tarea.
+- Las secciones de design citadas si existen.
+
+Para cada requirement/design ref, verifica:
+
+| Pregunta | Cómo verificar |
+|----------|----------------|
+| ¿El código implementa lo que el requirement dice? | Mapear líneas concretas del diff al texto del requirement |
+| ¿Falta algo del requirement que el código no cubre? | Listar gaps específicos |
+| ¿Hay código fuera del scope del requirement? | Comparar con design — si no está justificado, es scope creep |
+
+Si hay gap de cobertura → finding MAYOR con cita del requirement y línea
+faltante en el diff.
+
+---
+
+## Paso 4 — Veto items (heredados del revisor base)
+
+Los revisores SWL existentes declaran sus propios veto items (ver
+`reglas/gobernanza.md` § "Veto items y cap enforcement"). Cuando este
+protocolo se carga desde uno de ellos, los veto items del revisor padre
+aplican íntegros.
+
+**Si detectas CUALQUIER veto item**:
+
+- Score CAP automático a 6.0/10.
+- Verdict pasa a `REJECTED` independientemente de qué tan limpio esté el resto.
+- 2+ veto items → cap a 3.0/10.
+
+Lista de veto items del revisor padre debe estar disponible en su SKILL/agente.
+Si no se puede determinar, reporta `MANUAL_VERIFY_REQUIRED` en lugar de inventar.
+
+---
+
+## Paso 5 — Emitir veredicto estructurado
+
+### Formato del reporte
+
+```json
+{
+  "protocol": "protocolo-revision-swl",
+  "task_id": "3.2 — Crear endpoint POST /facturas",
+  "verdict": "APPROVED | REJECTED",
+  "score": 9.2,
+  "score_cap_applied": null,
+  "mechanical_checks": {
+    "regression_safety": "PASS",
+    "no_new_placeholders": "PASS",
+    "no_hardcoded_secrets": "PASS",
+    "boundary_respected": "PASS | VIOLATIONS_FOUND"
+  },
+  "spec_alignment": {
+    "requirements_covered": ["R-12", "R-13"],
+    "requirements_gap": [],
+    "design_drift": "NONE | SLIGHT | SIGNIFICANT"
+  },
+  "veto_items": [],
+  "findings": [
+    {
+      "severity": "CRITICAL | MAJOR | MINOR",
+      "file": "app/api/facturas.py:42",
+      "issue": "Descripción breve",
+      "remediation": "Qué cambiar y cómo"
+    }
+  ],
+  "summary": "Una oración resumiendo el veredicto y la razón principal.",
+  "next_action": "MERGE | FIX_AND_RE_REVIEW | ESCALATE_TO_HUMAN"
+}
+```
+
+### Reglas de scoring (compatibles con `checklist-calidad`)
+
+- `APPROVED` requiere `score >= 9.0` Y `veto_items.length === 0` Y todos los
+  mechanical_checks en PASS.
+- Severidad MAJOR baja el score 1.0 punto cada una.
+- Severidad MINOR baja 0.3 puntos cada una.
+- Severidad CRITICAL → automaticamente `REJECTED` (score irrelevante).
+- 1 veto item → cap a 6.0. 2+ veto items → cap a 3.0.
+
+### Reglas del `next_action`
+
+- `MERGE`: APPROVED — el caller (orquestador) puede commitear y avanzar a la siguiente tarea.
+- `FIX_AND_RE_REVIEW`: REJECTED con findings MAYORES — el implementador aplica remediation, se vuelve a invocar este protocolo. Máximo 2 ciclos antes de escalar.
+- `ESCALATE_TO_HUMAN`: 2 ciclos de FIX no convergieron, O hay CRÍTICO sin remediación clara, O hay decisión de scope ambigua. Activa el `notificador-swl` si está configurado.
+
+---
+
+## Persistencia del veredicto
+
+El veredicto JSON se persiste en:
+
+```
+.planning/audit/reviews/<task-id>-<timestamp>.json
+```
+
+Esto permite que `auto-evolucion-swl` y `/swl:metricas` calculen tasas de
+APPROVED vs REJECTED por agente revisor y por tipo de tarea — datos
+necesarios para identificar revisores con calibración floja o tipos de
+tarea sistemáticamente problemáticos.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Confiar en el reporte del implementador como source of truth**: el primer paso obligatorio es `git diff`. Saltarse esto y derivar el veredicto del status report del implementador deja pasar bugs colaterales no reportados. Causa: optimización falsa para ahorrar tokens. Solución: `git diff --stat` siempre antes de cualquier interpretación.
+- **Boundary violation reportada como MENOR sin verificar funcionalidad**: el revisor ve que se modificó un archivo fuera del boundary y lo marca MENOR porque "se ve pequeño". Causa: no se inspeccionó qué hace el cambio. Solución: para CUALQUIER archivo fuera del boundary, abrir el cambio y clasificar trivial vs funcional antes de asignar severidad.
+- **Tests skipped tratados como tests pasados**: el conteo de tests verde no distingue entre pasados y saltados. Causa: parsing superficial del output del runner. Solución: comparar `skipped` count vs base — si aumenta sin causa documentada en el diff, es regresión silenciosa (regla `monitor-ci.md`).
+- **APPROVED con score < 9.0 "porque la tarea era pequeña"**: el revisor reduce el umbral subjetivamente. Causa: ceder a presión de entrega. Solución: la regla es 9.0 estricto; tareas pequeñas que no llegan a 9.0 indican findings que valen MENOR o MAYOR — emitir como findings y devolver al implementador.
+- **Veto items ignorados porque "el resto está limpio"**: el cap de score es no-negociable. Causa: el revisor pondera "promedio" de calidad. Solución: 1 veto item = score capped automáticamente, sin compensación posible desde otras dimensiones.
+
+---
+
+## Relación con otros componentes SWL
+
+| Componente | Relación |
+|-----------|----------|
+| `revisor-codigo-swl` y revisores de lenguaje | Cargan este skill cuando trabajan task-local en lugar de phase-wide |
+| `ejecutar-task-iterativo` (Sub-fase 4) | Invoca este protocolo después de cada implementer dispatch en modo `--iterative` |
+| `verificar-trabajo` | Complementario — verificar-trabajo es goal-backward post-fase; este protocolo es task-local post-implementación |
+| `reglas/gobernanza.md` | Veto items + cap enforcement heredados |
+| `checklist-calidad` | Score >=9.0 unificado |
+| `auto-evolucion-swl` | Consume los veredictos persistidos para detectar revisores descalibrados |
+
+## Checklist de cierre del protocolo
+
+- [ ] `git diff --stat` ejecutado y diff leído antes de cualquier interpretación
+- [ ] 4 mechanical checks ejecutados (regression, placeholders, secretos, boundary)
+- [ ] Alineación con spec verificada citando IDs concretos
+- [ ] Veto items del revisor padre evaluados
+- [ ] Score calculado y cap aplicado si corresponde
+- [ ] Veredicto JSON persistido en `.planning/audit/reviews/`
+- [ ] `next_action` claro (MERGE / FIX_AND_RE_REVIEW / ESCALATE_TO_HUMAN)

package/habilidades/release-semver/.evolved.json

@@ -1,9 +1,9 @@
-{
-  "SKILL.md": {
-    "evolved": true,
-    "evolvedFrom": "1.0.1",
-    "evolvedAt": "2026-05-02",
-    "evolvedBy": "aprender",
-    "evolvedNote": "Sección nueva: publish a múltiples registries (republish-only + auth GitHub Packages)"
-  }
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "1.0.1",
+    "evolvedAt": "2026-05-02",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Sección nueva: publish a múltiples registries (republish-only + auth GitHub Packages)"
+  }
 }

package/habilidades/state-inconsistency-auditor-swl/SKILL.md

@@ -1,166 +1,166 @@
----
-name: state-inconsistency-auditor-swl
-description: >
-  Encuentra bugs donde una operación muta un fragmento de estado acoplado sin
-  actualizar su contraparte dependiente, causando corrupción silenciosa o fallos
-  en operaciones posteriores. Mapea sistemáticamente pares de estado acoplado,
-  todos sus paths de mutación, y los gaps donde un lado se actualiza sin el otro.
-  Language-agnostic (Python, TS, Go, Rust, Java, C#). Cargar cuando se sospeche
-  estado desincronizado: caché obsoleta, índices secundarios huérfanos, contadores
-  que no coinciden con la suma de sus partes, o permisos derivados que no reflejan
-  el estado de origen.
----
-
-# Cuándo cargar
-
-- Sospechas que un caché, índice secundario, o contador agregado está desincronizado.
-- Una función actualiza la tabla principal pero no el índice derivado.
-- Hay paths de "emergencia" o "admin" que modifican estado sin pasar por el flujo normal.
-- Nemesis está corriendo su Pasada 2.
-
-# Cuándo NO cargar
-
-- Para búsqueda de vulnerabilidades conocidas (inyección SQL, XSS) — usar `revisor-seguridad-swl`.
-- Para revisión de lógica de función individual sin estado acoplado — usar `feynman-auditor-swl`.
-- Para módulos sin persistencia de estado (transformaciones funcionales puras, utilería).
-
----
-
-# State Inconsistency Auditor
-
-Encuentra bugs donde una operación actualiza State A sin actualizar State B, cuando el invariante del sistema exige que ambos cambien juntos.
-
-Los patrones detallados de estado acoplado están en [recursos/coupled-state-patterns.md](recursos/coupled-state-patterns.md).
-
----
-
-## El patrón abstracto
-
-Todo sistema mantiene **PARES DE ESTADO ACOPLADO**: dos o más valores de almacenamiento que deben mantener una relación (un invariante) entre sí. Cuando cualquier operación cambia un lado del par sin ajustar el otro, el invariante se rompe. Operaciones posteriores que leen ambos valores producen resultados incorrectos.
-
----
-
-## Reglas del auditor
-
-```
-REGLA 0: MAPEAR ANTES DE CAZAR
-Nunca empezar a revisar funciones sin tener el mapa completo de
-dependencias de estado acoplado. No se puede encontrar una actualización
-faltante si no se sabe qué actualizaciones son necesarias.
-
-REGLA 1: TODOS LOS PATHS DE MUTACIÓN IMPORTAN
-Una variable de estado puede modificarse desde 5 funciones distintas.
-Las 5 deben actualizar el estado acoplado. Si 4 lo hacen y 1 no — ese es el bug.
-
-REGLA 2: LAS OPERACIONES PARCIALES SON LA FUENTE #1
-Las eliminaciones completas (eliminar todo) generalmente resetean todo el estado
-correctamente. Las operaciones parciales (reducir en X) frecuentemente olvidan
-reducir proporcionalmente el estado acoplado.
-
-REGLA 3: COMPARAR PATHS PARALELOS
-Si transferir() y eliminar() ambos reducen un balance, AMBOS deben actualizar
-el mismo conjunto de estado acoplado. Si uno lo hace y el otro no — hallazgo.
-
-REGLA 4: EL CÓDIGO DEFENSIVO ENMASCARA BUGS
-Código como `valor > minimo ? valor - minimo : 0` o `min(calculado, disponible)`
-oculta invariantes rotos silenciosamente. Son señales de alerta, no protecciones.
-
-REGLA 5: SOLO HALLAZGOS BASADOS EN EVIDENCIA
-Todo hallazgo debe incluir: el par acoplado, la operación que lo rompe,
-una secuencia de trigger concreta, y la consecuencia observable.
-```
-
----
-
-## Proceso
-
-### Fase 1: Mapear pares de estado acoplado
-
-Para cada variable de almacenamiento, preguntar: **"¿Qué otros valores de almacenamiento deben cambiar cuando este cambia?"**
-
-Construir un mapa de dependencias. Ver patrones comunes en `recursos/coupled-state-patterns.md`.
-
-Salida de Fase 1: **Mapa de Dependencias de Estado Acoplado**.
-
-### Fase 2: Matriz de mutación
-
-Para cada variable identificada en Fase 1, listar TODAS las funciones y paths de código que la modifican. Incluir: escrituras directas, incrementos/decrementos, eliminaciones, mutaciones indirectas (llamadas internas), triggers externos (callbacks, hooks).
-
-Marcar con `???` toda entrada donde no se ha confirmado si la contraparte acoplada también se actualiza.
-
-Los `???` son los **objetivos primarios de auditoría**.
-
-### Fase 3: Cross-check — el corazón de la auditoría
-
-Para cada par (operación, variable de estado) de Fase 2:
-
-> "Esta operación modifica State A. ¿También actualiza todo el estado acoplado que depende de A?"
-
-Verificar específicamente:
-- Eliminación completa (A → 0): ¿se resetea/limpia todo el estado acoplado?
-- Eliminación parcial (A decrece): ¿se reduce proporcionalmente todo el estado acoplado?
-- Incremento (A crece): ¿se incrementa proporcionalmente todo el estado acoplado?
-- Transferencia (A se mueve entre entidades): ¿el estado acoplado se mueve también?
-- Eliminación de entrada de colección: ¿la entrada del par también se elimina?
-- Operación en lote: ¿el estado acoplado se actualiza por iteración o solo una vez?
-
-**Si algún path actualiza A sin actualizar su estado acoplado → HALLAZGO.**
-
-### Fase 4: Orden de operaciones dentro de funciones
-
-Muchas funciones realizan múltiples cambios de estado en secuencia. Rastrear el orden exacto y preguntar en cada paso: "¿Después de este paso, todos los pares acoplados siguen siendo consistentes?"
-
-Bugs de orden comunes:
-- Calcular resultado ANTES de actualizar el índice → resultado usa estado obsoleto
-- Leer caché DESPUÉS de modificar el origen → validación usa datos viejos
-- Emitir evento con valores viejos DESPUÉS del cambio de estado → sistemas externos se desincronizarán
-
-### Fase 5: Comparar paths paralelos
-
-Encontrar operaciones que logran resultados similares por paths distintos. Para cada grupo, comparar: ¿TODOS los paths actualizan el mismo estado acoplado?
-
-### Fase 6: Rastrear journeys multi-paso
-
-Simular secuencias donde un actor interactúa múltiples veces:
-
-1. Actor inicializa un recurso (estado inicializado)
-2. Tiempo pasa / estado externo evoluciona
-3. Actor hace modificación PARCIAL (el estado acoplado puede romperse aquí)
-4. Más tiempo pasa
-5. Actor hace otra operación que lee el estado acoplado
-
-En el paso 5: ¿el estado acoplado sigue siendo válido dado el cambio parcial del paso 3?
-
-### Fase 7: Patrones de enmascaramiento
-
-El código defensivo puede ocultar invariantes rotos. Ver patrones en `recursos/coupled-state-patterns.md`.
-
-Señal: si un ternario del tipo `a > b ? a - b : 0` está en un cálculo que involucra dos valores acoplados, preguntar: ¿por qué `a` podría ser menor que `b`? Si el invariante se mantuviera, no podría.
-
----
-
-## Verificación (obligatoria para C/A/M)
-
-**Método A: Rastreo de código** — leer la función exacta, rastrear todas las llamadas internas, confirmar que no existe actualización oculta al estado acoplado.
-
-**Método B: Test de PoC** — escribir un test que ejecute la secuencia de trigger y afirme que el estado es inconsistente después de la operación.
-
-**Método C: Híbrido** — rastreo + PoC para hallazgos que abarcan múltiples módulos.
-
-**Falsos positivos frecuentes:**
-- Reconciliación oculta en un hook `_before_save` / `_after_update` / middleware.
-- Evaluación diferida intencional: el estado acoplado se reconcilia en la próxima lectura.
-- Asimetría de diseño documentada: los dos estados no son realmente acoplados como se asumió.
-
----
-
-## Adaptación por lenguaje
-
-| Concepto | Python | TypeScript | Go | Rust | Java | C# |
-|---------|--------|------------|-----|------|------|-----|
-| Almacenamiento | atributos / BD | propiedades / BD | campos struct / BD | campos struct | campos clase | propiedades |
-| Colección clave-valor | `dict` / `HashMap` Redis | `Map` / objeto | `map[K]V` | `HashMap` | `Map<K,V>` | `Dictionary<K,V>` |
-| Eliminar entrada | `del d[k]` / `pop` | `delete obj[k]` | `delete(m, k)` | `map.remove(&k)` | `map.remove(k)` | `dict.Remove(k)` |
-| Hook post-mutación | `@receiver` / signal | middleware / hook | middleware | `impl Drop` / hook | `@PostUpdate` | event handler |
-
-<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->
+---
+name: state-inconsistency-auditor-swl
+description: >
+  Encuentra bugs donde una operación muta un fragmento de estado acoplado sin
+  actualizar su contraparte dependiente, causando corrupción silenciosa o fallos
+  en operaciones posteriores. Mapea sistemáticamente pares de estado acoplado,
+  todos sus paths de mutación, y los gaps donde un lado se actualiza sin el otro.
+  Language-agnostic (Python, TS, Go, Rust, Java, C#). Cargar cuando se sospeche
+  estado desincronizado: caché obsoleta, índices secundarios huérfanos, contadores
+  que no coinciden con la suma de sus partes, o permisos derivados que no reflejan
+  el estado de origen.
+---
+
+# Cuándo cargar
+
+- Sospechas que un caché, índice secundario, o contador agregado está desincronizado.
+- Una función actualiza la tabla principal pero no el índice derivado.
+- Hay paths de "emergencia" o "admin" que modifican estado sin pasar por el flujo normal.
+- Nemesis está corriendo su Pasada 2.
+
+# Cuándo NO cargar
+
+- Para búsqueda de vulnerabilidades conocidas (inyección SQL, XSS) — usar `revisor-seguridad-swl`.
+- Para revisión de lógica de función individual sin estado acoplado — usar `feynman-auditor-swl`.
+- Para módulos sin persistencia de estado (transformaciones funcionales puras, utilería).
+
+---
+
+# State Inconsistency Auditor
+
+Encuentra bugs donde una operación actualiza State A sin actualizar State B, cuando el invariante del sistema exige que ambos cambien juntos.
+
+Los patrones detallados de estado acoplado están en [recursos/coupled-state-patterns.md](recursos/coupled-state-patterns.md).
+
+---
+
+## El patrón abstracto
+
+Todo sistema mantiene **PARES DE ESTADO ACOPLADO**: dos o más valores de almacenamiento que deben mantener una relación (un invariante) entre sí. Cuando cualquier operación cambia un lado del par sin ajustar el otro, el invariante se rompe. Operaciones posteriores que leen ambos valores producen resultados incorrectos.
+
+---
+
+## Reglas del auditor
+
+```
+REGLA 0: MAPEAR ANTES DE CAZAR
+Nunca empezar a revisar funciones sin tener el mapa completo de
+dependencias de estado acoplado. No se puede encontrar una actualización
+faltante si no se sabe qué actualizaciones son necesarias.
+
+REGLA 1: TODOS LOS PATHS DE MUTACIÓN IMPORTAN
+Una variable de estado puede modificarse desde 5 funciones distintas.
+Las 5 deben actualizar el estado acoplado. Si 4 lo hacen y 1 no — ese es el bug.
+
+REGLA 2: LAS OPERACIONES PARCIALES SON LA FUENTE #1
+Las eliminaciones completas (eliminar todo) generalmente resetean todo el estado
+correctamente. Las operaciones parciales (reducir en X) frecuentemente olvidan
+reducir proporcionalmente el estado acoplado.
+
+REGLA 3: COMPARAR PATHS PARALELOS
+Si transferir() y eliminar() ambos reducen un balance, AMBOS deben actualizar
+el mismo conjunto de estado acoplado. Si uno lo hace y el otro no — hallazgo.
+
+REGLA 4: EL CÓDIGO DEFENSIVO ENMASCARA BUGS
+Código como `valor > minimo ? valor - minimo : 0` o `min(calculado, disponible)`
+oculta invariantes rotos silenciosamente. Son señales de alerta, no protecciones.
+
+REGLA 5: SOLO HALLAZGOS BASADOS EN EVIDENCIA
+Todo hallazgo debe incluir: el par acoplado, la operación que lo rompe,
+una secuencia de trigger concreta, y la consecuencia observable.
+```
+
+---
+
+## Proceso
+
+### Fase 1: Mapear pares de estado acoplado
+
+Para cada variable de almacenamiento, preguntar: **"¿Qué otros valores de almacenamiento deben cambiar cuando este cambia?"**
+
+Construir un mapa de dependencias. Ver patrones comunes en `recursos/coupled-state-patterns.md`.
+
+Salida de Fase 1: **Mapa de Dependencias de Estado Acoplado**.
+
+### Fase 2: Matriz de mutación
+
+Para cada variable identificada en Fase 1, listar TODAS las funciones y paths de código que la modifican. Incluir: escrituras directas, incrementos/decrementos, eliminaciones, mutaciones indirectas (llamadas internas), triggers externos (callbacks, hooks).
+
+Marcar con `???` toda entrada donde no se ha confirmado si la contraparte acoplada también se actualiza.
+
+Los `???` son los **objetivos primarios de auditoría**.
+
+### Fase 3: Cross-check — el corazón de la auditoría
+
+Para cada par (operación, variable de estado) de Fase 2:
+
+> "Esta operación modifica State A. ¿También actualiza todo el estado acoplado que depende de A?"
+
+Verificar específicamente:
+- Eliminación completa (A → 0): ¿se resetea/limpia todo el estado acoplado?
+- Eliminación parcial (A decrece): ¿se reduce proporcionalmente todo el estado acoplado?
+- Incremento (A crece): ¿se incrementa proporcionalmente todo el estado acoplado?
+- Transferencia (A se mueve entre entidades): ¿el estado acoplado se mueve también?
+- Eliminación de entrada de colección: ¿la entrada del par también se elimina?
+- Operación en lote: ¿el estado acoplado se actualiza por iteración o solo una vez?
+
+**Si algún path actualiza A sin actualizar su estado acoplado → HALLAZGO.**
+
+### Fase 4: Orden de operaciones dentro de funciones
+
+Muchas funciones realizan múltiples cambios de estado en secuencia. Rastrear el orden exacto y preguntar en cada paso: "¿Después de este paso, todos los pares acoplados siguen siendo consistentes?"
+
+Bugs de orden comunes:
+- Calcular resultado ANTES de actualizar el índice → resultado usa estado obsoleto
+- Leer caché DESPUÉS de modificar el origen → validación usa datos viejos
+- Emitir evento con valores viejos DESPUÉS del cambio de estado → sistemas externos se desincronizarán
+
+### Fase 5: Comparar paths paralelos
+
+Encontrar operaciones que logran resultados similares por paths distintos. Para cada grupo, comparar: ¿TODOS los paths actualizan el mismo estado acoplado?
+
+### Fase 6: Rastrear journeys multi-paso
+
+Simular secuencias donde un actor interactúa múltiples veces:
+
+1. Actor inicializa un recurso (estado inicializado)
+2. Tiempo pasa / estado externo evoluciona
+3. Actor hace modificación PARCIAL (el estado acoplado puede romperse aquí)
+4. Más tiempo pasa
+5. Actor hace otra operación que lee el estado acoplado
+
+En el paso 5: ¿el estado acoplado sigue siendo válido dado el cambio parcial del paso 3?
+
+### Fase 7: Patrones de enmascaramiento
+
+El código defensivo puede ocultar invariantes rotos. Ver patrones en `recursos/coupled-state-patterns.md`.
+
+Señal: si un ternario del tipo `a > b ? a - b : 0` está en un cálculo que involucra dos valores acoplados, preguntar: ¿por qué `a` podría ser menor que `b`? Si el invariante se mantuviera, no podría.
+
+---
+
+## Verificación (obligatoria para C/A/M)
+
+**Método A: Rastreo de código** — leer la función exacta, rastrear todas las llamadas internas, confirmar que no existe actualización oculta al estado acoplado.
+
+**Método B: Test de PoC** — escribir un test que ejecute la secuencia de trigger y afirme que el estado es inconsistente después de la operación.
+
+**Método C: Híbrido** — rastreo + PoC para hallazgos que abarcan múltiples módulos.
+
+**Falsos positivos frecuentes:**
+- Reconciliación oculta en un hook `_before_save` / `_after_update` / middleware.
+- Evaluación diferida intencional: el estado acoplado se reconcilia en la próxima lectura.
+- Asimetría de diseño documentada: los dos estados no son realmente acoplados como se asumió.
+
+---
+
+## Adaptación por lenguaje
+
+| Concepto | Python | TypeScript | Go | Rust | Java | C# |
+|---------|--------|------------|-----|------|------|-----|
+| Almacenamiento | atributos / BD | propiedades / BD | campos struct / BD | campos struct | campos clase | propiedades |
+| Colección clave-valor | `dict` / `HashMap` Redis | `Map` / objeto | `map[K]V` | `HashMap` | `Map<K,V>` | `Dictionary<K,V>` |
+| Eliminar entrada | `del d[k]` / `pop` | `delete obj[k]` | `delete(m, k)` | `map.remove(&k)` | `map.remove(k)` | `dict.Remove(k)` |
+| Hook post-mutación | `@receiver` / signal | middleware / hook | middleware | `impl Drop` / hook | `@PostUpdate` | event handler |
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->