@saulwade/swl-ses 1.0.0

package/habilidades/checkpoints-verificacion/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: checkpoints-verificacion
+description: Sistema de checkpoints del GSD para control de flujo entre agentes. Cubre los 3 tipos (human-verify, decision, human-action), formato XML, auto-mode, notificaciones y session snapshots atómicos para persistencia y reanudación. Incluye estructura completa de snapshot con mensajes, actividades, archivos modificados y último veredicto.
+version: "1.1.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para pausar la ejecución por razones de incertidumbre del agente — los checkpoints son puntos de gobernanza definidos en el plan, no válvulas de escape ante duda."
+  - "No cargar para crear más de un checkpoint `decision` por oleada; si hay múltiples bifurcaciones, consolidarlas en una decisión con opciones o escalar con `ejecutar-fase` Desviación Mayor."
+  - "No cargar si la decisión ya está especificada en el PLAN.md o CONTEXTO.md — un checkpoint `decision` sobre algo ya resuelto es ruido de gobernanza."
+  - "No cargar para registrar el estado de sesión entre agentes; para eso usar `execution-state.js` directamente."
+evolvable: true  # default para skill estandar
+---
+# Checkpoints de Verificación GSD
+
+## Cuándo NO cargar
+
+- El agente quiere pausar porque no está seguro de cómo implementar algo — eso no es un checkpoint, es una Desviación Mayor en `ejecutar-fase`. Escalar a `arquitecto-swl` si el bloqueo es técnico.
+- La decisión ya está en PLAN.md o CONTEXTO.md; ejecutar el plan sin pausa adicional.
+- Se quiere registrar el estado entre agentes para serialización y reanudación; usar `execution-state.js` de `hooks/lib/` directamente — los checkpoints son para gobernanza, no para persistencia técnica.
+- La bifurcación es claramente inferior en una opción; usar `human-verify` con recomendación, no `decision`.
+
+## Concepto
+
+Un **checkpoint** es un punto de pausa controlada en el flujo de ejecución del sistema GSD.
+
+> **Si Claude PUEDE automatizar una decisión, DEBE automatizarla.**
+> Solo se pausa cuando la decisión requiere juicio humano genuino, acción fuera del
+> alcance del agente, o verificación de calidad que el agente no puede hacer por sí solo.
+
+| Tipo | Frecuencia | Cuándo |
+|------|-----------|--------|
+| human-verify | ~90% | El agente termina, el humano confirma calidad |
+| decision | ~9% | El agente necesita elegir entre caminos ambiguos |
+| human-action | ~1% | El agente necesita algo que solo el humano puede hacer |
+
+---
+
+## 1. Tipo: human-verify
+
+El agente completó una tarea y presenta resultados para revisión.
+
+**Cuándo usar**: Al finalizar una fase, generar un documento importante, completar un slice vertical, o detectar una anomalía menor.
+
+**Comportamiento**: Presentar checkpoint con toda la información, NO continuar hasta recibir respuesta (salvo `auto_advance: true`), registrar resultado en ESTADO.md.
+
+Para templates XML completos y ejemplos concretos, ver [recursos/checkpoint-templates.md](recursos/checkpoint-templates.md).
+
+---
+
+## 2. Tipo: decision
+
+El agente encontró una bifurcación donde ambos caminos son válidos pero con implicaciones distintas de negocio, riesgo o prioridad.
+
+**Cuándo usar**: Tecnología A vs B no especificada en spec, migración big-bang vs incremental, dos normalizaciones igualmente válidas.
+
+**Cuándo NO usar**: La spec ya especifica la decisión, una opción es claramente inferior, la decisión es fácilmente reversible.
+
+**Regla de recomendación**: El agente SIEMPRE indica su recomendación con justificación técnica. No es neutral: tiene opinión fundamentada.
+
+Para templates XML con pros/contras y ejemplos de migración, ver [recursos/checkpoint-templates.md](recursos/checkpoint-templates.md).
+
+---
+
+## 3. Tipo: human-action
+
+El agente necesita que el humano realice una acción fuera de su alcance: configurar credenciales, aprobar gastos, ejecutar en sistemas restringidos.
+
+**Cuándo usar**: Configurar secretos, aprobar cargos/licencias, ejecutar en producción con acceso restringido, contactar proveedor externo, aprobar PR con protección de rama.
+
+Para templates XML con acciones numeradas y ejemplos de AWS Secrets Manager, ver [recursos/checkpoint-templates.md](recursos/checkpoint-templates.md).
+
+---
+
+## 4. Auto-Mode (auto_advance: true)
+
+`auto_advance: true` se usa cuando el checkpoint es informativo: el agente reporta progreso pero no necesita confirmación para continuar.
+
+**Reglas estrictas**:
+- `auto_advance: true` SOLO para checkpoints de tipo `human-verify`
+- NUNCA `auto_advance: true` en `decision` o `human-action`
+- Valor por defecto: `false`
+
+---
+
+## 5. Integración con Notificaciones
+
+Cada checkpoint emite notificación al canal configurado:
+
+```javascript
+const PRIORIDAD = {
+  'human-action': 'urgente',    // notificación inmediata, todos los canales
+  'decision':     'alta',       // notificación inmediata, canal principal
+  'human-verify': 'normal',     // notificación normal, canal principal
+};
+```
+
+---
+
+## 6. Registro en ESTADO.md
+
+Todo checkpoint resuelto se registra:
+
+```markdown
+| ID | Tipo | Estado | Resolución | Fecha |
+|----|------|--------|-----------|-------|
+| verify-plan-fase2 | human-verify | resuelto | aprobado | 2024-03-20 |
+| decision-db-engine | decision | resuelto | opción-B | 2024-03-21 |
+```
+
+---
+
+## Reglas de selección de tipo
+
+| Situación | Tipo correcto |
+|-----------|--------------|
+| Agente terminó tarea, quiere confirmación | `human-verify` |
+| Lint/tests pasan, reportar sin bloquear | `human-verify` con `auto_advance="true"` |
+| Dos opciones igualmente válidas con distinto impacto | `decision` |
+| Una opción claramente superior | `human-verify` con recomendación (NO `decision`) |
+| Necesita credenciales, accesos o aprobaciones | `human-action` |
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **`auto_advance: true` en checkpoint `decision`**: el agente marca una decisión de bifurcación real como auto-advance porque "ya tiene preferencia". Causa: se confunde la recomendación del agente con la decisión del usuario. Solución: `auto_advance: true` es exclusivo de `human-verify`; cualquier `decision` o `human-action` siempre espera respuesta explícita del usuario — la regla no tiene excepciones.
+- **Snapshot de sesión escrito con `fs.writeFileSync` en lugar de `atomicWriteJSON`**: si el proceso se interrumpe durante la escritura del snapshot, el archivo queda corrupto y la reanudación falla. Causa: se usa escritura directa por simplicidad. Solución: usar `atomicWriteJSON` de `hooks/lib/atomic-write.js` — escribe a `.tmp` primero y renombra, garantizando atomicidad.
+- **Checkpoint sin `consecuencias_de_espera` en tipo `decision`**: el usuario no sabe cuánto tiempo puede esperar para decidir. Causa: campo omitido como opcional cuando en realidad es crítico para decisiones bloqueantes. Solución: siempre incluir `consecuencias_de_espera` especificando qué tareas quedan bloqueadas si el usuario no responde en N horas.
+- **Session stale reanudada automáticamente después de 24 h**: el agente lee el snapshot con `updated_at` de 2 días antes y reanuda sin verificar. Causa: no se aplicó la detección de sesión stale. Solución: comparar `updated_at` con la hora actual; si hay más de 24 h y `status` es `active`, marcar como `stalled` y emitir `human-verify` antes de continuar.
+
+## Anti-patrones
+
+- Checkpoint sin `id` único (dificulta trazabilidad en ESTADO.md)
+- `auto_advance: true` en `decision` o `human-action`
+- Más de 4 opciones en un `decision` (sobrecarga cognitiva)
+- `human-action` para algo que el agente puede hacer con sus herramientas
+- `decision` sin campo `recomendacion`
+- Omitir `consecuencias_de_espera` en `decision`
+
+---
+
+## 7. Estado de ejecución serializable — execution-state.json
+
+Cuando un plan multi-agente se pausa (checkpoint) o un agente completa su trabajo,
+registrar el estado en `.planning/execution-state.json` usando `hooks/lib/execution-state.js`.
+
+Este archivo permite reanudar planes con estado preciso, sin reconstrucción de contexto
+a partir de texto libre. Inspirado en el patrón ExecutionSnapshot de Sim Studio.
+
+### Al completar un agente
+
+```javascript
+const es = require('./hooks/lib/execution-state');
+es.completarAgente(process.cwd(), 'implementador-swl', 'api-endpoints', {
+  archivosCreados:    ['src/api.py', 'tests/test_api.py'],
+  archivosModificados: ['src/config.py'],
+  resumen:            'API REST implementada con FastAPI, 4 endpoints, tests unitarios',
+});
+es.actualizarContexto(process.cwd(), {
+  archivosModificados: ['src/api.py', 'tests/test_api.py'],
+  testsStatus:         'passing',
+  decisiones:          ['FastAPI por rendimiento', 'Pydantic v2 para validación'],
+});
+```
+
+### Al pausar (checkpoint humano)
+
+```javascript
+// Registrar el próximo agente pendiente
+es.establecerProximo(process.cwd(), 'revisor-codigo-swl', 'revision-api');
+// El archivo execution-state.json persiste entre sesiones
+```
+
+### Al reanudar desde checkpoint
+
+```javascript
+// Leer el estado para saber dónde continuar
+const estado = es.leer(process.cwd());
+console.log(es.formatearResumen(process.cwd()));
+// → "Plan: plan-x — Fase: implementacion
+//    Agentes completados:
+//      ✓ implementador-swl / api-endpoints
+//    → revisor-codigo-swl / revision-api (próximo)"
+```
+
+### Referencias en prompts con variable-resolver
+
+Los outputs registrados pueden referenciarse en prompts del orquestador:
+
+```
+Implementa los endpoints listados en {{planificador-swl.output.archivosACrear}}.
+Decisiones ya tomadas: {{contexto.decisiones}}.
+Tests actuales: {{contexto.testsStatus}}.
+```
+
+Resolver con `hooks/lib/variable-resolver.js`:
+
+```javascript
+const vr = require('./hooks/lib/variable-resolver');
+const promptResuelto = vr.resolver(promptTemplate, process.cwd());
+```
+
+---
+
+## 8. Session Snapshots — Persistencia atómica para reanudación
+
+Cuando una sesión multi-agente se pausa o interrumpe, el snapshot captura el estado
+completo para reanudar sin pérdida de contexto. Complementa `execution-state.json`
+con información de actividad y veredictos.
+
+### Estructura del snapshot
+
+```json
+{
+  "metadata": {
+    "session_id": "ses_abc123",
+    "plan_id": "plan-modulo-pagos",
+    "spec": "Implementar módulo de pagos con Stripe",
+    "status": "paused | active | completed | failed",
+    "iterations": 3,
+    "created_at": "2026-04-12T10:00:00Z",
+    "updated_at": "2026-04-12T14:30:00Z"
+  },
+  "state": {
+    "current_phase": "implementacion",
+    "activities": [
+      {
+        "agent": "implementador-swl",
+        "task": "api-endpoints",
+        "phase": "completed",
+        "duration_ms": 45000
+      },
+      {
+        "agent": "revisor-codigo-swl",
+        "task": "revision-api",
+        "phase": "in_progress",
+        "duration_ms": null
+      }
+    ],
+    "modified_files": [
+      "src/api/pagos.py",
+      "src/services/stripe_service.py",
+      "tests/test_pagos.py"
+    ],
+    "git_tracking": {
+      "branch": "feat/modulo-pagos",
+      "commits_ahead": 3,
+      "last_commit": "abc1234"
+    }
+  },
+  "context": {
+    "decisions": ["Stripe Checkout por simplicidad", "Webhooks async"],
+    "tests_status": "passing",
+    "pending_checkpoints": ["verify-integracion-stripe"]
+  },
+  "last_verdict": {
+    "verdict": "Fail",
+    "risk": "Medium",
+    "score": 0.75,
+    "failures": [{"artifact": "src/services/stripe_service.py", "level": "DATOS_FLUYEN", "reason": "Webhook no procesa evento checkout.session.completed"}],
+    "nextStep": {"action": "Fix", "instructions": ["Implementar handler para checkout.session.completed en webhook endpoint"]}
+  }
+}
+```
+
+### Persistencia atómica
+
+Escribir snapshots con el patrón write-tmp-rename para evitar corrupción:
+
+```javascript
+const { atomicWriteJSON } = require('./hooks/lib/atomic-write');
+// Escribe a .tmp primero, luego renombra — si el proceso muere a mitad
+// de escritura, el archivo original permanece intacto
+atomicWriteJSON(path.join(planningDir, 'session-snapshot.json'), snapshot);
+```
+
+NUNCA escribir directamente al archivo de snapshot — una interrupción a mitad
+de escritura corrompe el estado y pierde la capacidad de reanudación.
+
+### Reanudación desde snapshot
+
+Al reanudar una sesión pausada:
+
+1. Leer `session-snapshot.json` con `execution-state.js`.
+2. Verificar `last_verdict` — si fue `Fail`, las `nextStep.instructions` son la
+   primera tarea del ejecutor.
+3. Verificar `modified_files` contra el estado actual de git para detectar cambios
+   externos durante la pausa.
+4. Restaurar `context.decisions` para que los agentes no re-debatan decisiones ya tomadas.
+5. Continuar desde `state.current_phase` con el siguiente agente pendiente.
+
+### Detección de sesión stale
+
+Si `updated_at` tiene más de 24 horas y `status` es `active`:
+
+- Marcar como `stalled` en el snapshot.
+- Emitir checkpoint `human-verify` para confirmar si se debe continuar o descartar.
+- No reanudar automáticamente sesiones stale — pueden tener contexto desactualizado.

package/habilidades/checkpoints-verificacion/recursos/checkpoint-templates.md

@@ -0,0 +1,360 @@
+# Templates de Checkpoints — Referencia Rápida
+
+Copia el template del tipo correcto y rellena los campos marcados con `[...]`.
+Elimina los comentarios `<!-- ... -->` antes de emitir el checkpoint.
+
+---
+
+## Tipo 1: human-verify
+
+Usar cuando el agente terminó trabajo y el humano debe confirmar calidad antes de continuar.
+
+```xml
+<checkpoint type="human-verify" id="verify-[identificador-unico]" auto_advance="false">
+  <titulo>[Qué se hizo — frase corta descriptiva]</titulo>
+
+  <resumen>
+    [2-4 oraciones describiendo qué se implementó, qué decisiones se tomaron
+    y cuál es el estado actual. Ser concreto: números, archivos, resultados.]
+  </resumen>
+
+  <artefactos>
+    <artefacto tipo="archivo" ruta="[ruta/al/archivo.md]" />
+    <artefacto tipo="archivo" ruta="[ruta/al/otro.py]" />
+    <!-- tipo puede ser: archivo | log | url | directorio -->
+  </artefactos>
+
+  <metricas>
+    <metrica nombre="tareas_completadas" valor="[N]" />
+    <metrica nombre="tareas_totales" valor="[N]" />
+    <metrica nombre="tests_pasando" valor="[N]" />
+    <metrica nombre="cobertura_pct" valor="[N]" />
+    <!-- Agregar métricas relevantes al contexto -->
+  </metricas>
+
+  <preguntas>
+    <!-- Opcional: preguntas específicas que el humano debe considerar -->
+    <pregunta id="q1">[Pregunta concreta sobre el trabajo entregado]</pregunta>
+    <pregunta id="q2">[Pregunta sobre riesgo o edge case identificado]</pregunta>
+  </preguntas>
+
+  <opciones>
+    <opcion valor="aprobar">Aprobar y continuar con [siguiente paso]</opcion>
+    <opcion valor="ajustar">Ajustar con feedback específico</opcion>
+    <opcion valor="rechazar">Rechazar y rehacer desde [punto de reintento]</opcion>
+  </opciones>
+</checkpoint>
+```
+
+### Ejemplo concreto: verificación de slice de autenticación
+
+```xml
+<checkpoint type="human-verify" id="verify-auth-slice1" auto_advance="false">
+  <titulo>Slice 1 completo: modelos y endpoints de autenticación JWT</titulo>
+
+  <resumen>
+    Se implementaron los modelos Usuario y Sesion con migraciones Alembic,
+    los endpoints /auth/login y /auth/refresh con RBAC, y los schemas Pydantic
+    correspondientes. La cobertura de tests es 94%. El linter y mypy pasan sin errores.
+  </resumen>
+
+  <artefactos>
+    <artefacto tipo="archivo" ruta="app/models/usuario.py" />
+    <artefacto tipo="archivo" ruta="app/routers/auth.py" />
+    <artefacto tipo="archivo" ruta="tests/test_auth.py" />
+    <artefacto tipo="archivo" ruta="alembic/versions/001_usuarios.py" />
+  </artefactos>
+
+  <metricas>
+    <metrica nombre="endpoints_implementados" valor="2" />
+    <metrica nombre="tests_pasando" valor="18" />
+    <metrica nombre="cobertura_pct" valor="94" />
+    <metrica nombre="errores_mypy" valor="0" />
+  </metricas>
+
+  <preguntas>
+    <pregunta id="q1">¿El tiempo de expiración del token (24h) coincide con el requerimiento de negocio?</pregunta>
+    <pregunta id="q2">¿Se requiere soporte para múltiples sesiones simultáneas o solo la sesión más reciente?</pregunta>
+  </preguntas>
+
+  <opciones>
+    <opcion valor="aprobar">Aprobar y continuar con Slice 2 (CRUD de usuarios)</opcion>
+    <opcion valor="ajustar">Ajustar con feedback específico antes de Slice 2</opcion>
+    <opcion valor="rechazar">Rechazar y rehacer el slice desde los modelos</opcion>
+  </opciones>
+</checkpoint>
+```
+
+### Variante auto_advance (informativo, sin pausa)
+
+Usar cuando el resultado es positivo y no requiere confirmación explícita:
+
+```xml
+<checkpoint type="human-verify" id="verify-lint-[fase]" auto_advance="true">
+  <titulo>Lint, type-check y tests pasaron — continuando automáticamente</titulo>
+
+  <resumen>
+    Todos los archivos del Slice [N] pasaron ruff, mypy y pytest sin errores.
+    Se continúa automáticamente con el Slice [N+1].
+  </resumen>
+
+  <artefactos>
+    <artefacto tipo="log" ruta=".claude/logs/lint-[fecha].txt" />
+  </artefactos>
+
+  <metricas>
+    <metrica nombre="errores_ruff" valor="0" />
+    <metrica nombre="errores_mypy" valor="0" />
+    <metrica nombre="tests_pasando" valor="[N]" />
+  </metricas>
+</checkpoint>
+```
+
+---
+
+## Tipo 2: decision
+
+Usar cuando hay una bifurcación real donde ambas opciones son válidas y el humano
+debe elegir según criterios de negocio, riesgo o prioridad que el agente no puede resolver.
+
+```xml
+<checkpoint type="decision" id="decision-[dominio]-[tema]" auto_advance="false">
+  <titulo>[Decisión que se necesita — formulada como pregunta o elección]</titulo>
+
+  <contexto>
+    [Explicar por qué se llegó a esta bifurcación. Qué dice (o no dice) la spec.
+    Qué consecuencias tiene cada camino. 3-5 oraciones máximo.]
+  </contexto>
+
+  <opciones>
+    <opcion id="A" recomendada="false">
+      <!-- recomendada="true" en la opción que el agente recomienda -->
+      <nombre>[Nombre corto de la opción A]</nombre>
+      <pros>
+        <pro>[Ventaja concreta y medible]</pro>
+        <pro>[Otra ventaja]</pro>
+      </pros>
+      <contras>
+        <contra>[Desventaja concreta]</contra>
+        <contra>[Otra desventaja]</contra>
+      </contras>
+      <impacto>[Impacto en tiempo, costo, riesgo o mantenimiento. Sé específico.]</impacto>
+    </opcion>
+
+    <opcion id="B" recomendada="true">
+      <nombre>[Nombre corto de la opción B]</nombre>
+      <pros>
+        <pro>[Ventaja]</pro>
+      </pros>
+      <contras>
+        <contra>[Desventaja]</contra>
+      </contras>
+      <impacto>[Impacto]</impacto>
+    </opcion>
+
+    <!-- Agregar opción C solo si genuinamente hay 3 caminos distintos.
+         Máximo 4 opciones por checkpoint. -->
+  </opciones>
+
+  <recomendacion>
+    [Párrafo explicando por qué el agente recomienda la opción marcada.
+    Fundamentar con criterios técnicos, no preferencias. Ser directo.]
+  </recomendacion>
+
+  <consecuencias_de_espera>
+    [Qué está bloqueado mientras no se toma esta decisión.
+    Qué tareas pueden avanzar de forma independiente mientras tanto.]
+  </consecuencias_de_espera>
+</checkpoint>
+```
+
+### Ejemplo concreto: elección de estrategia de migración
+
+```xml
+<checkpoint type="decision" id="decision-migracion-schema-v2" auto_advance="false">
+  <titulo>Estrategia de migración: big-bang vs incremental para schema v2</titulo>
+
+  <contexto>
+    El schema v2 requiere renombrar 12 columnas y agregar 3 tablas nuevas.
+    La base de datos de producción tiene 2.3M registros. La spec no especifica
+    la estrategia de migración. Hay dos caminos viables con trade-offs distintos.
+  </contexto>
+
+  <opciones>
+    <opcion id="A" recomendada="false">
+      <nombre>Big-bang: migración única con ventana de mantenimiento</nombre>
+      <pros>
+        <pro>Código más simple: sin lógica de compatibilidad dual</pro>
+        <pro>Migración completa en una sola operación atómica</pro>
+      </pros>
+      <contras>
+        <contra>Requiere ventana de mantenimiento de ~45 minutos</contra>
+        <contra>Riesgo de rollback complejo si falla a mitad</contra>
+      </contras>
+      <impacto>Downtime de 45 min. Implementación: 2 días. Sin deuda técnica residual.</impacto>
+    </opcion>
+
+    <opcion id="B" recomendada="true">
+      <nombre>Incremental: expand-contract pattern (sin downtime)</nombre>
+      <pros>
+        <pro>Zero downtime: producción nunca se interrumpe</pro>
+        <pro>Rollback simple en cualquier punto de la migración</pro>
+      </pros>
+      <contras>
+        <contra>Código temporal de compatibilidad por ~2 semanas</contra>
+        <contra>Requiere 3 deployments en lugar de 1</contra>
+      </contras>
+      <impacto>Sin downtime. Implementación: 5 días. Complejidad temporal gestionable.</impacto>
+    </opcion>
+  </opciones>
+
+  <recomendacion>
+    Se recomienda la opción B (expand-contract) porque la aplicación tiene SLA de
+    disponibilidad del 99.5% y 45 minutos de downtime viola ese acuerdo. El coste
+    adicional de 3 días de implementación es menor que el riesgo de incumplimiento del SLA.
+  </recomendacion>
+
+  <consecuencias_de_espera>
+    El Slice 3 (endpoints de reportes) está bloqueado hasta esta decisión.
+    Los Slices 1 y 2 (autenticación y CRUD básico) pueden continuar independientemente.
+  </consecuencias_de_espera>
+</checkpoint>
+```
+
+---
+
+## Tipo 3: human-action
+
+Usar cuando el agente necesita que el humano realice una acción fuera del alcance
+del agente: configurar credenciales, aprobar gastos, ejecutar en sistemas restringidos, etc.
+
+```xml
+<checkpoint type="human-action" id="action-[dominio]-[accion]" auto_advance="false">
+  <titulo>[Acción requerida — imperativo claro: "Configurar X", "Aprobar Y", "Ejecutar Z"]</titulo>
+
+  <razon>
+    [Por qué el agente no puede hacer esto por sí solo. Ser honesto y específico:
+    "No tiene acceso a X", "Requiere autorización de Y", "Está fuera del sandbox".]
+  </razon>
+
+  <acciones_requeridas>
+    <accion orden="1">
+      <descripcion>[Paso concreto y accionable]</descripcion>
+      <detalle>
+        [Información específica necesaria para completar el paso:
+        rutas, IDs, formatos, valores exactos.]
+      </detalle>
+    </accion>
+
+    <accion orden="2">
+      <descripcion>[Siguiente paso]</descripcion>
+      <detalle>[Detalles]</detalle>
+    </accion>
+
+    <accion orden="N">
+      <descripcion>Confirmar aquí cuando todas las acciones anteriores estén completadas</descripcion>
+    </accion>
+  </acciones_requeridas>
+
+  <bloqueado_hasta>
+    [Qué tareas están bloqueadas hasta que estas acciones se completen.
+    Ser específico: nombres de tareas, slices o fases.]
+  </bloqueado_hasta>
+
+  <tiempo_estimado>[Estimación realista: "5-10 minutos", "1-2 horas", "1 día hábil"]</tiempo_estimado>
+
+  <!-- Opcional: notificación de urgencia -->
+  <notificacion>
+    <prioridad>urgente</prioridad>
+    <canales>desktop,telegram</canales>
+    <resumen_corto>BLOQUEADO: [descripción de 60 chars máximo]</resumen_corto>
+  </notificacion>
+</checkpoint>
+```
+
+### Ejemplo concreto: configuración de secretos en producción
+
+```xml
+<checkpoint type="human-action" id="action-secrets-produccion" auto_advance="false">
+  <titulo>Configurar credenciales de base de datos en gestor de secretos de producción</titulo>
+
+  <razon>
+    El agente no tiene acceso al gestor de secretos de producción (AWS Secrets Manager).
+    Las credenciales son necesarias para que el pipeline de CI pueda ejecutar las migraciones
+    de Alembic contra la base de datos de producción en el siguiente deployment.
+  </razon>
+
+  <acciones_requeridas>
+    <accion orden="1">
+      <descripcion>Acceder a AWS Secrets Manager en la consola de producción</descripcion>
+      <detalle>
+        Región: us-east-1
+        Cuenta AWS: [número de cuenta]
+        URL: https://console.aws.amazon.com/secretsmanager/home?region=us-east-1
+      </detalle>
+    </accion>
+
+    <accion orden="2">
+      <descripcion>Crear o actualizar el secreto "sigaf/prod/database"</descripcion>
+      <detalle>
+        Estructura JSON requerida (copiar exactamente):
+        {
+          "host": "[hostname RDS de producción]",
+          "port": 5432,
+          "database": "sigaf_prod",
+          "username": "[usuario de producción]",
+          "password": "[contraseña segura — mínimo 32 chars, símbolos incluidos]"
+        }
+      </detalle>
+    </accion>
+
+    <accion orden="3">
+      <descripcion>Agregar el ARN del secreto como variable en GitHub Actions</descripcion>
+      <detalle>
+        Settings → Secrets and variables → Actions → New repository secret
+        Nombre: PROD_DB_SECRET_ARN
+        Valor: arn:aws:secretsmanager:us-east-1:[cuenta]:secret:sigaf/prod/database-[sufijo]
+      </detalle>
+    </accion>
+
+    <accion orden="4">
+      <descripcion>Confirmar aquí que los tres pasos anteriores están completos</descripcion>
+    </accion>
+  </acciones_requeridas>
+
+  <bloqueado_hasta>
+    La tarea "deploy-produccion" y el Slice 4 completo están bloqueados hasta
+    completar estas acciones. El desarrollo local puede continuar sin ellas.
+  </bloqueado_hasta>
+
+  <tiempo_estimado>10-15 minutos</tiempo_estimado>
+
+  <notificacion>
+    <prioridad>urgente</prioridad>
+    <canales>desktop,telegram</canales>
+    <resumen_corto>BLOQUEADO: Configurar credenciales AWS para deploy a producción</resumen_corto>
+  </notificacion>
+</checkpoint>
+```
+
+---
+
+## Reglas de selección de tipo
+
+| Situación | Tipo correcto |
+|-----------|--------------|
+| El agente terminó una tarea y quiere confirmación de calidad | `human-verify` |
+| El lint/tests pasan, reportar sin bloquear | `human-verify` con `auto_advance="true"` |
+| Hay dos opciones técnicas igualmente válidas con distinto impacto | `decision` |
+| Hay una opción claramente superior | NO usar `decision` — usar `human-verify` con recomendación |
+| El agente necesita credenciales, accesos o aprobaciones externas | `human-action` |
+| Necesita que alguien ejecute algo en producción | `human-action` |
+
+## Anti-patrones
+
+- Checkpoint sin `id` único: dificulta la trazabilidad en ESTADO.md
+- `auto_advance="true"` en `decision` o `human-action`: nunca válido
+- Más de 4 opciones en un `decision`: sobrecarga cognitiva
+- `human-action` para algo que el agente puede hacer con sus herramientas disponibles
+- `decision` sin campo `recomendacion`: el agente siempre debe tener una posición fundamentada
+- Omitir `consecuencias_de_espera` en `decision`: el humano necesita saber qué se bloquea