@saulwade/swl-ses 1.0.0

package/habilidades/django-experto/recursos/testing-django.md

@@ -0,0 +1,415 @@
+# Testing con pytest-django y Factory Boy
+
+## Configuración: pytest.ini y conftest.py base
+
+```ini
+# pytest.ini (o sección [tool.pytest.ini_options] en pyproject.toml)
+[pytest]
+DJANGO_SETTINGS_MODULE = config.settings.test
+python_files = tests.py test_*.py *_test.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    --reuse-db          # reutiliza la BD entre sesiones para velocidad
+    --strict-markers    # falla si se usa marker no declarado
+    -p no:warnings      # silenciar deprecation warnings en CI
+markers =
+    slow: tests lentos que se omiten en desarrollo local
+    integration: tests con servicios externos reales
+```
+
+```python
+# config/settings/test.py
+from .base import *  # noqa: F401, F403
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.postgresql",
+        "NAME": "test_db",
+        "USER": "postgres",
+        "PASSWORD": "postgres",
+        "HOST": "localhost",
+        "PORT": "5432",
+    }
+}
+
+# Acelerar hashing en tests — NUNCA en producción
+PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]
+
+# Celery en modo síncrono para tests
+CELERY_TASK_ALWAYS_EAGER = True
+CELERY_TASK_EAGER_PROPAGATES = True
+
+# Caché en memoria para tests
+CACHES = {"default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"}}
+```
+
+```python
+# conftest.py (raíz del proyecto)
+import pytest
+from rest_framework.test import APIClient
+from django.contrib.auth import get_user_model
+
+from tests.factories import UsuarioFactory, EmpresaFactory
+
+Usuario = get_user_model()
+
+
+@pytest.fixture
+def api_client() -> APIClient:
+    """Cliente DRF sin autenticar."""
+    return APIClient()
+
+
+@pytest.fixture
+def empresa(db):
+    """Empresa de prueba creada en BD."""
+    return EmpresaFactory()
+
+
+@pytest.fixture
+def usuario(db, empresa):
+    """Usuario activo con empresa asignada."""
+    return UsuarioFactory(empresa=empresa, is_active=True)
+
+
+@pytest.fixture
+def usuario_admin(db, empresa):
+    """Usuario con rol administrador."""
+    return UsuarioFactory(empresa=empresa, rol="admin", is_active=True)
+
+
+@pytest.fixture
+def cliente_autenticado(api_client: APIClient, usuario) -> APIClient:
+    """Cliente DRF con usuario autenticado via JWT."""
+    api_client.force_authenticate(user=usuario)
+    return api_client
+
+
+@pytest.fixture
+def cliente_admin(api_client: APIClient, usuario_admin) -> APIClient:
+    """Cliente DRF con usuario administrador autenticado."""
+    api_client.force_authenticate(user=usuario_admin)
+    return api_client
+```
+
+---
+
+## Factory Boy: definición de factories
+
+```python
+# tests/factories.py
+import factory
+from factory.django import DjangoModelFactory
+from factory import SubFactory, LazyAttribute, Faker, Sequence
+from django.contrib.auth import get_user_model
+from decimal import Decimal
+
+from apps.empresas.models import Empresa
+from apps.facturas.models import Factura, ItemFactura, Cliente
+
+Usuario = get_user_model()
+
+
+class EmpresaFactory(DjangoModelFactory):
+    class Meta:
+        model = Empresa
+
+    nombre = Faker("company", locale="es_MX")
+    rfc = Sequence(lambda n: f"EMP{n:09d}A1")
+    activa = True
+
+
+class UsuarioFactory(DjangoModelFactory):
+    class Meta:
+        model = Usuario
+
+    email = Sequence(lambda n: f"usuario{n}@prueba.com")
+    nombre = Faker("first_name", locale="es_MX")
+    apellido = Faker("last_name", locale="es_MX")
+    empresa = SubFactory(EmpresaFactory)
+    rol = "operador"
+    is_active = True
+
+    # Contraseña manejada con set_password para que hashee correctamente
+    @factory.post_generation
+    def password(self, create, extracted, **kwargs):
+        if not create:
+            return
+        self.set_password(extracted or "Contraseña!Segura123")
+        self.save(update_fields=["password"])
+
+
+class ClienteFactory(DjangoModelFactory):
+    class Meta:
+        model = Cliente
+
+    nombre = Faker("company", locale="es_MX")
+    rfc = Sequence(lambda n: f"CLI{n:09d}A1")
+    empresa = SubFactory(EmpresaFactory)
+    activo = True
+
+
+class FacturaFactory(DjangoModelFactory):
+    class Meta:
+        model = Factura
+
+    folio = Sequence(lambda n: f"FAC-{n:06d}")
+    cliente = SubFactory(ClienteFactory)
+    empresa = LazyAttribute(lambda obj: obj.cliente.empresa)
+    estatus = "emitida"
+    total = Faker(
+        "pydecimal", min_value=100, max_value=100_000,
+        right_digits=2, positive=True,
+    )
+
+
+class ItemFacturaFactory(DjangoModelFactory):
+    class Meta:
+        model = ItemFactura
+
+    factura = SubFactory(FacturaFactory)
+    descripcion = Faker("sentence", locale="es_MX", nb_words=4)
+    cantidad = Faker("random_int", min=1, max=20)
+    precio_unitario = Faker(
+        "pydecimal", min_value=10, max_value=5_000, right_digits=2, positive=True
+    )
+```
+
+---
+
+## Tests de modelo: validaciones, métodos y señales
+
+```python
+# apps/facturas/tests/test_models.py
+import pytest
+from django.core.exceptions import ValidationError
+from tests.factories import FacturaFactory, ItemFacturaFactory
+
+
+@pytest.mark.django_db
+class TestFacturaModel:
+    def test_calcular_total_suma_items(self):
+        factura = FacturaFactory()
+        ItemFacturaFactory(factura=factura, cantidad=2, precio_unitario=100)
+        ItemFacturaFactory(factura=factura, cantidad=1, precio_unitario=50)
+
+        assert factura.calcular_total() == pytest.approx(250.00)
+
+    def test_no_se_puede_cancelar_factura_ya_cancelada(self):
+        factura = FacturaFactory(estatus="cancelada")
+
+        with pytest.raises(ValueError, match="ya está cancelada"):
+            factura.cancelar(motivo="prueba")
+
+    def test_estatus_emitida_es_valido(self):
+        factura = FacturaFactory.build(estatus="emitida")
+        # .full_clean() ejecuta validadores del modelo sin guardar en BD
+        factura.full_clean()  # no debe lanzar excepción
+
+    def test_estatus_invalido_falla_validacion(self):
+        factura = FacturaFactory.build(estatus="INVALIDO")
+        with pytest.raises(ValidationError):
+            factura.full_clean()
+
+
+@pytest.mark.django_db
+class TestSignalCambioEstatus:
+    def test_signal_post_save_envia_notificacion(self, mocker):
+        """La señal post_save debe llamar al servicio de notificación al cambiar estatus."""
+        mock_notificar = mocker.patch(
+            "apps.facturas.signals.notificacion_service.enviar"
+        )
+        factura = FacturaFactory(estatus="emitida")
+        # Simular tracker manualmente si se usa django-model-utils
+        factura.estatus = "pagada"
+        factura.save()
+
+        mock_notificar.assert_called_once()
+        call_kwargs = mock_notificar.call_args.kwargs
+        assert call_kwargs["tipo"] == "CAMBIO_ESTATUS_FACTURA"
+```
+
+---
+
+## Tests de API: status codes y payloads
+
+```python
+# apps/facturas/tests/test_api.py
+import pytest
+from django.urls import reverse
+from rest_framework import status
+from tests.factories import FacturaFactory, ClienteFactory
+
+
+@pytest.mark.django_db
+class TestFacturaListAPI:
+    def test_listar_requiere_autenticacion(self, api_client):
+        url = reverse("factura-list")
+        respuesta = api_client.get(url)
+        assert respuesta.status_code == status.HTTP_401_UNAUTHORIZED
+
+    def test_listar_solo_facturas_propias(self, cliente_autenticado, usuario):
+        """El usuario solo debe ver facturas de su empresa."""
+        # Facturas de la empresa del usuario
+        factura_propia = FacturaFactory(empresa=usuario.empresa)
+        # Factura de otra empresa — NO debe aparecer
+        FacturaFactory()
+
+        url = reverse("factura-list")
+        respuesta = cliente_autenticado.get(url)
+
+        assert respuesta.status_code == status.HTTP_200_OK
+        ids_retornados = [r["id"] for r in respuesta.data["resultados"]]
+        assert str(factura_propia.id) in ids_retornados
+        assert len(ids_retornados) == 1
+
+    def test_crear_factura_con_items(self, cliente_autenticado, usuario):
+        cliente = ClienteFactory(empresa=usuario.empresa)
+        payload = {
+            "cliente_id": str(cliente.id),
+            "items": [
+                {"producto_id": None, "descripcion": "Servicio A", "cantidad": 2, "precio_unitario": "500.00"},
+                {"producto_id": None, "descripcion": "Servicio B", "cantidad": 1, "precio_unitario": "300.00"},
+            ],
+        }
+        url = reverse("factura-list")
+        respuesta = cliente_autenticado.post(url, data=payload, format="json")
+
+        assert respuesta.status_code == status.HTTP_201_CREATED
+        assert len(respuesta.data["items"]) == 2
+
+
+@pytest.mark.django_db
+class TestFacturaCancelarAccion:
+    def test_cancelar_factura_emitida(self, cliente_admin, usuario_admin):
+        factura = FacturaFactory(empresa=usuario_admin.empresa, estatus="emitida")
+        url = reverse("factura-cancelar", kwargs={"pk": factura.pk})
+
+        respuesta = cliente_admin.post(url, data={"motivo": "Error de captura"}, format="json")
+
+        assert respuesta.status_code == status.HTTP_200_OK
+        factura.refresh_from_db()
+        assert factura.estatus == "cancelada"
+
+    def test_cancelar_factura_ya_cancelada_retorna_422(self, cliente_admin, usuario_admin):
+        factura = FacturaFactory(empresa=usuario_admin.empresa, estatus="cancelada")
+        url = reverse("factura-cancelar", kwargs={"pk": factura.pk})
+
+        respuesta = cliente_admin.post(url, data={}, format="json")
+
+        assert respuesta.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY
+```
+
+---
+
+## Tests de permisos
+
+```python
+# apps/facturas/tests/test_permisos.py
+import pytest
+from django.urls import reverse
+from rest_framework import status
+from tests.factories import FacturaFactory
+
+
+@pytest.mark.django_db
+class TestPermisosFactura:
+    def test_operador_no_puede_cancelar(self, cliente_autenticado, usuario):
+        """El rol 'operador' no tiene permiso para cancelar facturas."""
+        assert usuario.rol == "operador"
+        factura = FacturaFactory(empresa=usuario.empresa, estatus="emitida")
+        url = reverse("factura-cancelar", kwargs={"pk": factura.pk})
+
+        respuesta = cliente_autenticado.post(url, data={}, format="json")
+
+        assert respuesta.status_code == status.HTTP_403_FORBIDDEN
+
+    def test_no_puede_ver_factura_de_otra_empresa(self, cliente_autenticado):
+        factura_ajena = FacturaFactory()  # empresa diferente
+        url = reverse("factura-detail", kwargs={"pk": factura_ajena.pk})
+
+        respuesta = cliente_autenticado.get(url)
+
+        # 404 es preferible a 403 para no revelar que el recurso existe
+        assert respuesta.status_code == status.HTTP_404_NOT_FOUND
+```
+
+---
+
+## Mocking: servicios externos y tareas Celery
+
+```python
+# apps/facturas/tests/test_servicios.py
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+@pytest.mark.django_db
+def test_crear_factura_envia_email(mocker):
+    """El servicio de factura debe encolar email sin llamar SMTP real."""
+    mock_tarea = mocker.patch("apps.facturas.services.enviar_email.delay")
+
+    servicio = FacturaService()
+    factura = servicio.crear(cliente_id=1, items=[...])
+
+    mock_tarea.assert_called_once_with(
+        destinatario=factura.cliente.email,
+        folio=factura.folio,
+    )
+
+
+@pytest.mark.django_db
+def test_integracion_pasarela_pago(mocker):
+    """Mockear cliente HTTP de la pasarela para no hacer llamadas reales."""
+    mock_respuesta = MagicMock()
+    mock_respuesta.status_code = 200
+    mock_respuesta.json.return_value = {"transaccion_id": "TXN-001", "aprobado": True}
+
+    mocker.patch(
+        "apps.pagos.clients.PasarelaPagoClient.procesar",
+        return_value=mock_respuesta.json(),
+    )
+
+    resultado = PasarelaPagoService().pagar(factura_id=1, monto=500.00)
+    assert resultado["aprobado"] is True
+
+
+# Celery con CELERY_TASK_ALWAYS_EAGER=True — las tareas se ejecutan síncronamente
+@pytest.mark.django_db
+def test_tarea_celery_ejecuta_logica():
+    from apps.reportes.tasks import generar_reporte_mensual
+
+    # Con ALWAYS_EAGER, .delay() ejecuta la tarea inmediatamente en el mismo proceso
+    resultado = generar_reporte_mensual.delay(empresa_id=1, mes=1, anio=2025)
+    assert resultado.successful()
+```
+
+---
+
+## Performance en tests: transaction.on_commit
+
+```python
+# El callback de on_commit NO se ejecuta en tests con @pytest.mark.django_db
+# porque los tests hacen rollback en lugar de commit real.
+# Solución: usar transaction=True o TestCase.captureOnCommitCallbacks
+
+@pytest.mark.django_db(transaction=True)
+def test_on_commit_ejecuta_tarea(mocker):
+    """Necesita transaction=True para que on_commit dispare el callback."""
+    mock_tarea = mocker.patch("apps.facturas.tasks.indexar_factura.delay")
+    FacturaFactory()  # el signal usa on_commit para encolar la tarea
+
+    mock_tarea.assert_called_once()
+
+
+# Alternativa con Django 4.1+: captureOnCommitCallbacks sin transaction=True
+@pytest.mark.django_db
+def test_on_commit_sin_transaccion_real(mocker):
+    mock_tarea = mocker.patch("apps.facturas.tasks.indexar_factura.delay")
+
+    from django.test import TestCase
+    # En pytest-django se puede usar con el fixture `django_capture_on_commit_callbacks`
+    # disponible desde pytest-django 4.6+
+    pass  # ver documentación de pytest-django para el fixture exacto
+```

package/habilidades/doc-sync/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: doc-sync
+description: Sincronización de documentación con el estado actual del código. Detecta documentos desactualizados (README, ADRs, docstrings, comentarios de API), genera un changelog estructurado de los cambios relevantes, y mantiene los Architecture Decision Records (ADRs) actualizados con las decisiones tomadas durante el desarrollo.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para crear documentación nueva desde cero — este skill sincroniza documentación existente con el código actual; para crear documentación de feature nueva usar `documentador-swl` o escribir el README/ADR directamente."
+  - "No cargar para mantener al día la documentación interna SWL (INVENTARIO.md, CLAUDE.md, manifiestos) — esa sincronización sigue la tabla de propagación de cambios de CLAUDE.md y no es responsabilidad de este skill."
+  - "No cargar cuando no hay releases ni cambios significativos en los últimos 30 días — el costo del inventario y comparación es alto; si el proyecto está en pausa, la documentación no necesita sincronización."
+  - "No cargar para validar la integridad del sistema SWL (frontmatter, exit codes de hooks) — eso es `validacion-ci-sistema`; este skill sincroniza documentación de usuario (README, ADRs, docstrings, OpenAPI)."
+evolvable: true  # default para skill estandar
+---
+# Habilidad: Sincronización de Documentación con Código
+
+## Propósito
+
+La documentación que miente es peor que la documentación que no existe.
+Un README con instrucciones de instalación obsoletas, un ADR que describe
+una decisión revertida hace meses, o una API con docstrings que contradicen
+el comportamiento real — todos estos son bugs de documentación que generan
+desconfianza y pérdida de tiempo. Esta habilidad los detecta y los corrige.
+
+## Cuándo activar
+
+- Al completar una fase de desarrollo antes de marcar como "done"
+- Al incorporar un colaborador nuevo que reporta confusión con la documentación
+- Trimestralmente como revisión de mantenimiento
+- Cuando el usuario reporta que "la documentación dice X pero el código hace Y"
+- Antes de publicar una release o versión
+
+---
+
+## Paso 1 — Inventario de documentación existente
+
+Identificar todos los artefactos de documentación en el proyecto:
+
+```bash
+# Todos los archivos de documentación
+find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" | sort
+
+# Docstrings en Python (verificar que existen)
+grep -rn '"""' --include="*.py" -l
+
+# JSDoc en TypeScript
+grep -rn '/\*\*' --include="*.ts" -l
+
+# OpenAPI / Swagger
+find . -name "openapi.json" -o -name "openapi.yaml" -o -name "swagger.json" 2>/dev/null
+
+# ADRs
+find . -name "ADR-*.md" -o -path "*/adr/*.md" -o -path "*/decisions/*.md" | sort
+```
+
+Construir un mapa de documentación:
+
+| Documento | Ruta | Última modificación | Última modificación del código relacionado |
+|-----------|------|--------------------|--------------------------------------------|
+| README.md | / | [fecha] | [fecha] |
+| ADR-001.md | docs/adr/ | [fecha] | N/A (decisiones históricas) |
+| API docs | docs/ | [fecha] | [fecha router modificado] |
+
+---
+
+## Paso 2 — Detectar desincronización
+
+### README.md — Verificar secciones críticas
+
+**Instalación y setup**:
+```bash
+# Probar las instrucciones de instalación desde cero (en directorio limpio)
+# ¿Funcionan los comandos listados?
+# ¿Faltan pasos que se añadieron al proceso?
+```
+
+Items a verificar:
+- [ ] Versiones de runtime mencionadas (Python 3.X, Node X.Y) coinciden con `.python-version`, `package.json` engines
+- [ ] Comandos de instalación funcionan como están escritos
+- [ ] Variables de entorno en README coinciden con `.env.example`
+- [ ] Comandos de ejecución del servidor son correctos
+- [ ] Comandos de tests coinciden con la configuración actual (`pytest.ini`, `jest.config.*`)
+- [ ] URLs de la API corresponden al router actual
+
+**Señales de desincronización**:
+```bash
+# Variables de entorno usadas en el código vs documentadas
+grep -rn "os\.getenv\|process\.env\." --include="*.py" --include="*.ts" \
+  | grep -o '"[A-Z_]*"' | sort | uniq > env_en_codigo.txt
+grep "^[A-Z_]*=" .env.example | cut -d= -f1 | sort > env_documentadas.txt
+diff env_en_codigo.txt env_documentadas.txt
+
+# Endpoints en el router vs documentados en README
+grep -rn "@router\.\|app\.[get|post|put|delete]" --include="*.py" \
+  | grep -o '"[/a-z_{}]*"' | sort > endpoints_reales.txt
+grep -oE '/api/v[0-9]+/[a-z_/{}]*' README.md | sort > endpoints_readme.txt
+diff endpoints_reales.txt endpoints_readme.txt
+```
+
+### Docstrings y comentarios de código
+
+```bash
+# Funciones públicas sin docstring (Python)
+grep -rn "^def \|^    def " --include="*.py" -A1 | grep -v '"""' | grep "def " | head -30
+
+# Docstrings que mencionan parámetros que ya no existen
+# Revisión manual: comparar firma actual con docstring
+
+# Comentarios TODO sin ticket
+grep -rn "TODO\|FIXME" --include="*.py" --include="*.ts" | head -20
+```
+
+### OpenAPI / Swagger desactualizado
+
+```bash
+# FastAPI genera el schema automáticamente — verificar que coincide
+# con la versión commiteada en docs/ (si la hay)
+curl http://localhost:8000/openapi.json | python -m json.tool > /tmp/openapi_actual.json
+diff docs/openapi.json /tmp/openapi_actual.json
+
+# Si hay diferencias, actualizar el schema commiteado
+```
+
+---
+
+## Paso 3 — Generar Changelog
+
+El changelog documenta QUÉ cambió y POR QUÉ, no solo el listado de commits.
+
+### Formato de CHANGELOG.md (Keep a Changelog)
+
+```markdown
+# CHANGELOG.md
+
+Todos los cambios notables se documentan aquí.
+Formato basado en [Keep a Changelog](https://keepachangelog.com/es/1.0.0/).
+
+## [Sin publicar] — En desarrollo
+
+## [2.1.0] — 2026-03-25
+
+### Añadido
+- Endpoint `GET /api/v1/reportes` con filtrado por fecha y usuario
+- Autenticación con MFA para cuentas con rol ADMIN
+- Soporte para exportación de datos en formato Excel
+
+### Cambiado
+- `POST /api/v1/pedidos` ahora requiere campo `bodega_id` (antes opcional)
+- Tiempo de expiración de tokens JWT reducido de 24h a 8h
+
+### Deprecado
+- `GET /api/v1/usuarios/lista` — usar `GET /api/v1/usuarios` con paginación
+
+### Eliminado
+- Endpoint `POST /api/v1/auth/refresh-all` eliminado por riesgo de seguridad
+
+### Corregido
+- Error al calcular descuentos para clientes con múltiples contratos activos
+- Timeout en exportaciones de más de 10,000 registros
+
+### Seguridad
+- CVE-2026-XXXXX: actualizado [paquete] de v1.2.3 a v1.2.4
+```
+
+### Cómo generar el changelog desde git
+
+```bash
+# Ver commits desde el último tag
+git log $(git describe --tags --abbrev=0)..HEAD \
+  --pretty=format:"- %s (%h)" --no-merges
+
+# Ver qué archivos cambiaron en la última release
+git diff $(git describe --tags --abbrev=0)..HEAD --name-only | sort
+
+# Commits por tipo (si usan Conventional Commits)
+git log --pretty=format:"%s" | grep "^feat:" | head -20
+git log --pretty=format:"%s" | grep "^fix:" | head -20
+git log --pretty=format:"%s" | grep "^security:" | head -20
+```
+
+---
+
+## Paso 4 — Mantener ADRs vigentes
+
+Un Architecture Decision Record (ADR) documenta una decisión de arquitectura:
+qué se decidió, por qué, y cuáles eran las alternativas.
+
+### Plantilla de ADR
+
+```markdown
+# ADR-[NNN]: [Título de la decisión]
+
+**Estado**: Propuesto | Aceptado | Obsoleto | Reemplazado por ADR-[NNN]
+**Fecha**: [YYYY-MM-DD]
+**Decidido por**: [nombres o roles]
+
+## Contexto
+
+[Describir la situación que requirió una decisión. Qué problema existe,
+qué restricciones aplican, qué opciones se consideraron.]
+
+## Decisión
+
+[La decisión tomada, en tiempo presente: "Usaremos X", "Adoptaremos Y".]
+
+## Consecuencias
+
+**Positivas**:
+- [beneficio 1]
+- [beneficio 2]
+
+**Negativas / trade-offs**:
+- [costo o limitación 1]
+- [costo o limitación 2]
+
+## Alternativas consideradas
+
+### Alternativa A: [nombre]
+- Ventajas: [lista]
+- Desventajas: [lista]
+- Razón de rechazo: [explicación]
+
+### Alternativa B: [nombre]
+- [ídem]
+
+## Referencias
+- [Link a issue, PR o documento relevante]
+```
+
+### Cuándo crear un ADR nuevo
+
+Crear un ADR cuando se toma una decisión que:
+- Afecta a más de un módulo o equipo
+- Sería difícil o costosa de revertir
+- Un desarrollador futuro podría cuestionar ("¿por qué hicieron esto?")
+- Involucra un trade-off no obvio entre opciones razonables
+
+### Cuándo marcar un ADR como "Obsoleto" o "Reemplazado"
+
+Cuando el código ya no refleja lo que el ADR dice, actualizar el ADR:
+```markdown
+**Estado**: Reemplazado por ADR-012
+**Nota**: La decisión de usar Redis como cache fue reemplazada por
+Memcached en 2026-01 por restricciones de licencia del cliente.
+```
+
+NUNCA eliminar ADRs — son historia del proyecto.
+
+---
+
+## Checklist de sincronización completa
+
+- [ ] README.md — instrucciones de instalación verificadas (funcionan paso a paso)
+- [ ] README.md — variables de entorno en `.env.example` coinciden con el código
+- [ ] README.md — comandos de ejecución y tests son correctos
+- [ ] CHANGELOG.md — tiene entrada para todos los cambios de la fase actual
+- [ ] Docstrings — funciones públicas documentadas y descripción coincide con firma
+- [ ] OpenAPI — schema actualizado si se añadieron/modificaron endpoints
+- [ ] ADRs — nuevas decisiones de arquitectura documentadas
+- [ ] ADRs obsoletos — marcados con estado "Obsoleto" o "Reemplazado"
+- [ ] TODOs con ticket — todos los `TODO` en código tienen referencia a issue
+
+---
+
+## Regla de cierre
+
+Ninguna fase se marca como "completada" si la documentación contradice
+el código implementado. La doc desactualizada es deuda técnica de primer nivel.
+
+## Cuándo NO cargar
+
+- No hay documentación existente que sincronizar — este skill compara docs existentes con el código; si el proyecto no tiene README, ADRs ni docstrings, crear esos artefactos primero con `documentador-swl`.
+- Los únicos artefactos que necesitan actualización son manifiestos SWL internos (INVENTARIO.md, CLAUDE.md, plugin.json) — esa actualización sigue la tabla de propagación de cambios de CLAUDE.md, no el flujo de 4 pasos de este skill.
+- El proyecto lleva más de 30 días sin commits — si no hay cambios en el código, la documentación no puede estar desactualizada respecto al código; el checklist de sincronización no aplica.
+- Se necesita validar integridad estructural del sistema SWL — eso es `validacion-ci-sistema`; este skill valida coherencia entre documentación de usuario y código, no frontmatter de agentes ni exit codes de hooks.
+
+## Gotchas / Errores comunes no obvios
+
+- **README marcado como desactualizado porque `grep` encontró un nombre de variable cambiado en un comentario**: el Paso 2 busca variables de entorno que aparezcan en el código pero no en `.env.example`, y el agente concluye que el README está obsoleto. Causa: el grep de variables detecta comentarios y strings de ejemplo, no solo declaraciones reales. Solución: al comparar variables de entorno, filtrar por el patrón de uso real (`os.getenv`, `process.env`, `os.environ`) y excluir archivos de ejemplo y tests.
+- **ADR marcado como "Obsoleto" en lugar de "Reemplazado por ADR-NNN"**: el agente marca decisiones revertidas como obsoletas sin crear el ADR de reemplazo primero. Causa: el estado "Obsoleto" se usa cuando no hay decisión sustituta; "Reemplazado" requiere que el ADR sustituto ya exista. Solución: si la decisión fue reemplazada por otra (no solo abandonada), crear el ADR de reemplazo en el mismo commit y referenciar el número — nunca marcar como "Reemplazado por ADR-NNN" si ese ADR no existe aún.
+- **Changelog generado desde `git log` incluye commits de fix de typo y WIP que no son relevantes para usuarios**: el changelog resultante tiene 40 entradas de "fix: typo" y "wip: progress". Causa: `git log --pretty=format:"- %s"` incluye todos los commits sin filtrar. Solución: usar `git log` con filtros por tipo de commit convencional (`feat:`, `fix:`, `security:`, `BREAKING CHANGE:`) y excluir commits de WIP, typo y refactor — el changelog es para consumidores del paquete, no para el historial interno.
+- **OpenAPI diff muestra diferencias por orden de campos en JSON**: `diff docs/openapi.json /tmp/openapi_actual.json` reporta diferencias aunque la API no cambió. Causa: `python -m json.tool` formatea el JSON pero no garantiza orden consistente de campos. Solución: normalizar ambos JSONs con `jq --sort-keys` antes del diff, o comparar solo los paths y schemas con una herramienta de diff semántico de OpenAPI en lugar de diff de texto.